FHEMWiki - Benutzerbeiträge [de]

HOMEMODE

2020-01-03T07:42:14Z

Binford6000: /* HomeCMDfhemSAVE */

{{
Infobox Modul
|ModPurpose=Das Modul wurde entworfen um den gesamten Heim-/Hausstatus in einem Gerät abzubilden und viele grundlegende Automationen durch Hinzufügen weiterer Geräte bereitzustellen.
|ModType=h
|ModCmdRef=HOMEMODE
|ModFTopic=64317
|ModForumArea=Automatisierung
|ModTechName=22_HOMEMODE.pm
|ModOwner=DeeSPe
}}
Diese Seite beschreibt die Konfiguration und Verwendung des Moduls ''22_HOMEMODE.pm''.

=Allgemeines=
Das Modul ''22_HOMEMODE.pm'' wurde entworfen um den gesamten Heim-/Hausstatus in einem Gerät abzubilden. 
Die hier aufgeführte Anleitung entspricht dem Modul in Version 1.4.2.

Viele allgemein typische Automationen sind bereits fertig integriert.

Die jeweils per Event auszuführenden Befehle können in den entsprechenden ''HomeCMD...'' Atributen hinterlegt werden und so in der Detail Ansicht des HOMEMODE Geräts übersichtlich angezeigt und bearbeitet werden.

Das Anlegen vieler notify/DOIF ist durch den Einsatz von ''HOMEMODE'' unnötig.

Zusätzlich wurde das Modul für die Verwendung mit HomeKit als GUI optimiert. Alle möglichen Mappings für Homebridge sind bereits enthalten und können über einen set Befehl aktualisiert werden.

[[Datei:HOMEMODE_Device.png|800px]]

==Voraussetzungen==
Um Modul ''22_HOMEMODE.pm'' benutzen zu können benötigt man als Mindestvoraussetzung ein bereits angelegtes RESIDENTS Gerät mit entsprechenden ROOMMATE/GUEST Geräten.

==Mögliche Automationen==
Alle Automationen sind optional.

Hier ein paar Beispiele:
*Änderung des Zustands von ROOMMATE/GUEST Geräten anhand von PRESENCE Geräten
*Bereitstellung von CMD Attributen für mögliche Events rund um den Heim-/Hausstatus
*Bereitstellung von Platzhaltern innerhalb der CMD Attribute, z.B. %MODE%, %SEASON% oder %PREVMODE% für die Werte der Readings mode, season und prevMode
*Einbindung von Kontakt Sensoren, für z.B. Offen-Warnungen nach bestimmten Zeitraum oder Alarm Meldungen in bestimmten Alarm Modus - kann pro Kontakt Sensor konfiguriert werden
*Einbindung von Bewegungs Sensoren, für z.B. automatische Licht Schaltungen oder Alarm Meldungen in bestimmten Alarm Modus - kann pro Bewegungs Sensor konfiguriert werden
*Darstellungen und Auslösen von Sabotage Alarmen der eingebundenen Kontakt- und Bewegungssensoren
*Einbindung von jeweils einem Temperatur und Luftfeuchtigkeitssensor
*Einbindung eines lokalen Wetter Devices zur Ermittlung und Ausgabe der lokalen Wetterdaten und Erzeugung der Wettervorhersage
*Einbindung von Power und Energy Sensoren zur Ermittlung der Gesamtmengen
*Einbindung von Calendar/holiday Devices für spezielle im HOMEMODE Device verfügbar zu machende Events
*von Uhrzeit abhängiger Anwesend-Modus
*Bewohner unabhängige Tageszeit-Modus
*Alarm-Modus
*DND-Modus
*Überwachung von Batteriewerten

=HOMEMODE-Gerät=
==Definition==
Das HOMEMODE Gerät - hier mit dem Namen ''Home'' versehen - selbst wird über
define Home HOMEMODE
bei Vorhandensein nur eines RESIDENTS Geräts definiert.

Bei Verwendung mehrerer RESIDENTS Geräte muss das Master RESIDENTS Gerät beim Definieren mit angegeben werden
define Home HOMEMODE rgr_Residents
Dieses Modul verwendet das globale Attribut ''language'' zur Bestimmung der Anzeigedaten (Standard: EN=english). Für deutsche Ausgabedaten kann das Attribut
attr global language DE
gesetzt werden. 
Alternativ kann auch nur das HOMEMODE Gerät auf deutsch geändert werden
attr Home HomeLanguage DE

==Set-Befehle==
''set <required> [optional]''

set Home anyoneElseAtHome <on/off>
einschalten wenn jemand anderes zu Hause ist der kein registrierter ROOMMATE/GUEST ist, z.B. Hund/Katze oder unregistrierte Gäste 
wenn eingeschaltet, dann wird der Alarm Mode beim Verlassen statt auf armaway nur auf armhome gestellt 
schaltet man ein und hat schon Haus/Wohnung verlassen, so wird der Alarm Mode von armaway auf armhome gestellt 
Platzhalter '''%AEAH%''' ist in allen HomeCMD Attributen verfügbar

set Home dnd <on/off>
schaltet den "Bitte nicht stören" Modus ein 
z.B. um Benachrichtigungen zu deaktivieren 
Platzhalter '''%DND%''' ist in allen HomeCMD Attributen verfügbar

set Home dnd-for-minutes <MINUTES>
schaltet den "Bitte nicht stören" Modus für die angegebenen Minuten ein 
kehrt danach zum vorherigen (tageszeitabhängigen) Modus zurück

set Home deviceDisable <DEVICE>
deaktiviert das Gerät für sämtliche HOMEMODE Automationen 
Platzhalter '''%DISABLED%''' ist in allen HomeCMD Attributen verfügbar 
Platzhalter '''%DEVICE%''' und '''%ALIAS%''' sind in allen HomeCMD Attributen verfügbar

set Home deviceEnable <DEVICE>
reaktiviert das Gerät für sämtliche HOMEMODE Automationen 
Platzhalter '''%DISABLED%''' ist in allen HomeCMD Attributen verfügbar 
Platzhalter '''%DEVICE%''' und '''%ALIAS%''' sind in allen HomeCMD Attributen verfügbar

set Home location <arrival/home/bed/underway/wayhome>
manueller Ortswechsel 
Platzhalter '''%LOCATION%''' ist in allen HomeCMD Attributen verfügbar

set Home mode <morning/day/afternoon/evening/night/gotosleep/asleep/absent/gone/home>
manueller Moduswechsel 
Platzhalter '''%MODE%''' und '''%PREVMODE%''' sind in allen HomeCMD Attributen verfügbar

set Home modeAlarm <armaway/armhome/armnight/disarm>
schaltet den angegebenen Alarm Modus ein 
Platzhalter '''%AMODE%''' und '''%PREVAMODE%''' sind in allen HomeCMD Attributen verfügbar

set Home modeAlarm-for-minutes <armaway/armhome/armnight/disarm> <MINUTES>
schaltet den angegebenen Alarm Modus für die angegebenen Minuten ein
kehrt danach zum vorherigen Alarm Modus zurück

set Home updateHomebridgeMapping
aktualisiert das Attribut homebridgeMapping des HOMEMODDE Device abhängig von den verfügbaren Informationen

set Home updateInternalForce
führt eine Aktualisierung der Internals des HOMEMODE Device aus 
das sollte manuell benutzt werden nachdem das Modul aktualisiert und nur ein reload statt restart gemacht wurde 
auch wenn man überwachte/kontrollierte Geräte ändert sollte man diesen Befehl manuell ausführen, z.B. neue ROOMMATE/GUEST im RESIDENTS Device hinzufügt, oder Geräte in FHEM hinzufügt die dem selben Devspec wie bisher entsprechen (Steckdosen, Sensoren)

==Get-Befehle==
''get <required> [optional]''

get Home contactsOpen <all/doorsinside/doorsoutside/doorsmain/outside/windows>
Liste von all/doorsinside/doorsoutside/doorsmain/outside/windows offenen Kontakten 
Platzhalter '''%OPEN%''', '''%OPENCT%''' und '''%OPENHR%''' sind in allen HomeCMD Attributen verfügbar

get Home devicesDisabled
Anzeige der für HOMEMODE deaktivierten Geräte 
Platzhalter '''%DISABLED%''' ist in allen HomeCMD Attributen verfügbar

get Home mode
Anzeige von mode 
Platzhalter '''%MODE%''' ist in allen HomeCMD Attributen verfügbar

get Home modeAlarm
Anzeige von modeAlarm 
Platzhalter '''%AMODE%''' und '''%MODEALARM%''' sind in allen HomeCMD Attributen verfügbar

get Home publicIP
holen der öffentlichen IP Adresse 
Platzhalter '''%IP%''' ist in allen HomeCMD Attributen verfügbar

get Home sensorsTampered
Liste aller sabotierten Sensoren 
Platzhalter '''%TAMPERED%''', '''%TAMPEREDCT%''' und '''%TAMPEREDHR%''' sind in allen HomeCMD Attributen verfügbar

get Home weather <long/short>
Wetterinfo im angegebenen Format anzeigen 
Platzhalter '''%WEATHER%''' und '''%WEATHERLONG%''' sind in allen HomeCMD Attributen verfügbar

get Home weatherForecast [TAG]
Wettervorhersage für angegebenen Tag 
wenn kein Tag angegeben wird, so wird die Vorhersage für morgen (2) ausgegeben 
Platzhalter '''%FORECAST%''' (morgen) und '''%FORECASTTODAY%''' (heute) sind in allen HomeCMD Attributen verfügbar

==webCmd==
Die Schaltmöglichkeiten sind absichtlich gering gehalten, denn im normalen Betrieb sollte nicht mehr benötigt werden als die hier gebotenen. 
Es lässt sich der Alarm Mode manuell umschalten und beim Klick auf das devStateIcon wird der DND Mode an- und ausgeschaltet.

=Konfiguration=

==Grundkonfiguration==

Diese Grundkonfiguration sollte immer als erstes erfolgen um entsprechend darauf weiter aufzubauen. Als zweiter Schritt ist dann die erweiterte Konfiguration angedacht.

Bei der Namensvergabe der Attribute vom HOMEMODE Device wurde nach einem möglichst kurzem Prefix gesucht und nach vielen Tests wurde sich für das Prefix "Home" entschieden. Das hat den Vorteil, dass alle Attribute beisammen stehen und diese auch (durch den Großbuchstaben am Anfang) ziemlich weit oben in der Liste der Attribute stehen. Ebenso wurde bei der Namensvergabe versucht, selbsterklärende Namen zu wählen. Das hat den Vorteil, dass man relativ einfach genau erkennen kann wofür das Attribut steht, allerdings auch den Nachteil, dass einige Attributnamen ganz schön lang werden.

===Attribute===

====HomeAdvancedUserAttr====
Als Erstes wird empfohlen, gerade für Anfänger, das Attribut "HomeAdvancedUserAttr" auf 1 zu setzen. Dadurch werden viel mehr HomeCMD Attribute freigeschaltet. Diese werden im Attribut userattr des HOMEMODE Device hinzugefügt. 
Standardwert: 0

====HomeAutoAlarmModes====
Als Nächstes sollte man sich entscheiden, ob die Alarm Modus evtl. nicht automatisch zum jeweiligen Modus des HOMEMODE Device geschaltet werden sollen. Standardmäßig werden die Alarm Modus automatisch gesteuert. Ist das nicht erwünscht, so ist der Wert dieses Attributs auf 0 zu setzen. 
Bei Modus "absent" des HOMEMODE Device wird automatisch auf "armaway" geschaltet. 
Bei Modus "home" des HOMEMODE Device wird automatisch auf "disarm" geschaltet. 
Bei Modus "asleep" des HOMEMODE Device wird automatisch auf "armnight" geschaltet. 
Alarm Modus "armhome" kann nur manuell gesetzt werden. 
Werte: 0 oder 1 
Standardwert: 1

====HomeAutoArrival====
Ist hier ein Wert größer 0 angegeben, so wird bei Ankunft jedes ROOMMATE/GUEST die location des jeweiligen ROOMMATE/GUEST für die hier angegeben Zeit in Minuten auf "arrival" gesetzt. Beim ersten nach Hause kommenden ROOMMATE/GUEST wird zusätzlich die location des HOMEMODE Device für die hier eingestellte Zeit in Minuten auf "arrival" gesetzt. 
Nach Ablauf der hier eingestellten Minuten wechselt das jeweilige Device von "arrival" auf "home", sofern es noch die location "arrival" hat. 
Werte: 0 bis 5999.9 
Standardwert: 0

====HomeAutoAsleep====
Ist hier ein Wert größer 0 angegeben, so wird beim Schlafengehen (gotosleep) jedes ROOMMATE/GUEST ein Timer gestartet, der den jeweiligen ROOMMATE/GUEST nach der hier angegeben Zeit in Minuten auf "asleep" setzt. 
Werte: 0 bis 5999.9 
Standardwert: 0

====HomeAutoAwoken====
Ist hier ein Wert größer 0 angegeben, so wird beim Erwachen ("awoken" oder "home nach asleep") jedes ROOMMATE/GUEST dieser auf "awoken" gesetzt und ein Timer gestartet, der den jeweiligen ROOMMATE/GUEST nach der hier angegeben Zeit in Minuten auf "home" setzt. 
Werte: 0 bis 5999.9 
Standardwert: 0

====HomeAutoDaytime====
Standardmäßig wird mode anhand der Tageszeit automatisch gesetzt. Ist das nicht gewünscht, kann das über den Wert 0 deaktiviert werden. Dann stehen allerdings tageszeitabhängigen mode(s) nicht mehr zur Verfügung. 
Werte: 0 oder 1 
Standardwert: 1

====HomeResidentCmdDelay====
Normalerweise werden die Events der ROOMMATE/GUEST vor denen des HOMEMODE Device ausgeführt. Um das zu ändern wird die Ausführung der ROOMMATE/GUEST HomeCMD Attribute um die hier eingestellte Zeit in Sekunden verzögert. 
Je genauer der Name des jeweiligen HomeCMD Attributs beschrieben wird, desto später wird dieser ausgeführt. 
Das heißt z.B. dass HomeCMDmode vor HomeCMDmode-absent und dieser wiederrum vor HomeCMDmode-absent-ROOMMATE/GUEST-NAME ausgeführt wird usw. 
Um das normale Verhalten wiederherzustellen ist der Wert dieses Attributs auf 0 zu setzen. Dann wird HomeCMDmode-absent-ROOMMATE/GUEST-NAME vor HomeCMDmode-absent und vor HomeCMDmode ausgeführt. 
Werte: 0 bis unendlich in Sekunden 
Standardwert: 1

==Konfiguration Presence Devices (automatische anwesend/abwesend Umschaltung von ROOMMATE/GUEST)==
Damit die automatische Zuordnung der Presence Devices zu ihren ROOMMATE/GUEST Devices zuverlässig funktioniert, ist es nötig dass der Hauptteil des Namens des ROOMMATE/GUEST innerhalb des Namens des zugehörigen PRESENCE Device(s) vorkommt. 
Im Attribut HomePresenceDeviceType kann man den zu suchenden TYPE von Presence Device vorgeben. 
Per Default werden nur Devices vom TYPE PRESENCE gesucht und versucht den ROOMMATE/GUEST zuzuweisen. 
Falls man z.B. auch Devices vom TYPE dummy zur Anwesenheitssteuerung benutzt, kann man diese im Attribut HomePresenceDeviceType mit hinzunehmen. Es sind alles Device TYPEn möglich die ein "presence" Reading mit den Werten "present/appeared" und "absent/disappeared" bereitstellen. Mehrere TYPEn sind möglich da in diesem Attribut ein Regex erwartet wird. z.B.: dummy oder PRESENCE|dummy oder PRESENCE|dummy|ONKYO_AVR.

===Beispiel===
Der Device Name meines ROOMMATE ist "rr_Dan". 
Auf der Suche nach dem zugehörigen Presence Device wird der erste Teil (rr_ oder rg_) weggeschnitten und der Rest in Kleinbuchstaben umgewandelt. 
Mit dem was übrig bleibt, bei mir also nur dan, werden die möglichen Presence Devices versucht zu erkennen. 
Mein zugehöriges Presence Device heißt, historisch gewachsen, PRESENCE_rr_Dan und würde somit problemlos zugeordnet werden können. 
Die Namen der zugehörigen Presence Devives könnten in ihrer kürzesten Form auch wie folgt sein um meinen ROOMMATE/GUEST Device zugeordnet zu werden: 
pdan
danp
ZDan
DANZ
wenndannsonst
Aber Achtung, es funktioniert nicht mehr wenn die Namen nicht eindeutig sind. Wenn es z.B. eine rr_Dana geben würde mit Presence Device Name "pdani", dann würde dieser Name auch bei mir (dan) passen. Das könnte man aber auch bewußt nutzen um mit einem Presence Device 2 ROOMMATE/GUEST Devices gleichzeitig zu steuern. 
Wenn die Namen wirklich absolut eindeutig sind, dann könnte man den Regex im Attribut HomePresenceDeviceType sogar auf ".*" setzen.

Werden pro ROOMMATE/GUEST mehrere Presence Devices gefunden und zugeordnet, so wird automatisch dass Attribut HomePresenceDeviceAbsentCount-<NAME-ROOMMATE/GUEST> auf die Anzahl der gefundenen Presence Devices gesetzt, so dass der/die jeweilige ROOMMATE/GUEST immer erst als abwesend gewertet wird sobald alle zugehörigen Presence Devices abwesend sind. Analog dazu gibt es noch das Attribut HomePresenceDevicePresentCount-<NAME-ROOMMATE/GUEST>.

===Attribute===

====HomeAutoPresence====
Ist dieses Attribut auf 1 gesetzt, so werden die ROOMMATE/GUEST Devices automatisch zum Status ihrer zugehörigen PRESENCE Devices geschaltet. 
PRESENCE Device present - ROOMMATE/GUEST home 
PRESENCE Device absent - ROOMMATE/GUEST absent 
Falls es sich bei den von Euch benutzen PRESENCE Devices nicht um Devices vom TYPE PRESENCE handeln sollte, sondern z.B. um PRESENCE und dummy, so kann dieses im Attribut HomePresenceDeviceType als Regex konfiguriert werden! z.B.: PRESENCE|dummy 
Damit ein Device als Presence Device erkannt werden kann, muss dieses über ein presence Reading verfügen. 
Werte: 0 oder 1 
Standardwert: 0

====HomeAutoPresenceSuppressState====
unterdrücke Anwesenheitsänderung in angegebenen State(s) der RESIDENTS 
z.B. für "mysteriös" verschwindende Anwesenheitsgeräte in der Nacht 
Werte: asleep|awoken|gotosleep 
Standardwert:

====HomePresenceDeviceType====
Regex des TYPEs/der TYPEn von Presence Devices 
Werte: Regex der Device TYPEn 
Standardwert: PRESENCE

==Erweiterte Konfiguration==
Um das HOMEMODE Device vollumfänglich zu benutzen ist es sinnvoll weitere Devices (zur Überwachung) hinzuzufügen.

Die bereits möglichen hinzuzufügenden Devices werden hier folgend nach Attributnamen erklärt.

===Attribute zum Hinzufügen weiterer Geräte===

====HomeEventsCalendarDevices====
Hier ist ein Devspec von holiday/Calendar Device(s) anzugeben. 
''Es wird empfohlen die holiday/Calendar Namen in Großbuchstaben anzulegen, da dann die daraus resultierenden Platzhalter ebenfalls Großbuchstaben sind und somit zu den anderen Platzhaltern passen.'' 
Es werden alle Typen von holiday Events (1,2,3,4,5) unterstützt. 
Bei Calendar sind auch gleichzeitig startende/laufende Events möglich, sie müssen nur unterschiedliche Titel haben (summary). 
Der jeweilige Event Text kann auch Leerzeichen enthalten, welche in den HomeCMD Attributen durch Bindestriche (-) ersetzt werden. 
Diese Devices stellen zusätzlich die Platzhalter '''%CALENDAR%''', '''%EVENT%''' und '''%PREVEVENT%''' in den HomeCMDevent Attributen zur Verfügung. '''%CALENDAR%''' wird dann durch den Namen, '''%EVENT%''' durch das aktuelle Event und '''%PREVEVENT%''' durch das vorherige Event des jeweiligen Kalenders ersetzt. 
Werte: frei wählbar 
Werteformat: Devspec von holiday/Calendar Geräten 
Standardwert:

====HomeEventsHolidayDevices====
Hier ist ein Devspec von holiday/Calendar Device(s) anzugeben. 
''Es wird empfohlen die holiday/Calendar Namen in Großbuchstaben anzulegen, da dann die daraus resultierenden Platzhalter ebenfalls Großbuchstaben sind und somit zu den anderen Platzhaltern passen.'' 
Es werden alle Typen von holiday Events (1,2,3,4,5) unterstützt. 
Bei Calendar sind auch gleichzeitig startende/laufende Events möglich, sie müssen nur unterschiedliche Titel haben (summary). 
Der jeweilige Event Text kann auch Leerzeichen enthalten, welche in den HomeCMD Attributen durch Bindestriche (-) ersetzt werden. 
Diese Devices stellen zusätzlich die Platzhalter '''%CALENDAR%''', '''%EVENT%''' und '''%PREVEVENT%''' in den HomeCMDevent Attributen zur Verfügung. '''%CALENDAR%''' wird dann durch den Namen, '''%EVENT%''' durch das aktuelle Event und '''%PREVEVENT%''' durch das vorherige Event des jeweiligen Kalenders ersetzt. 
Werte: frei wählbar 
Werteformat: Devspec von holiday/Calendar Geräten 
Standardwert:

====HomeSensorAirpressure====
Luftdrucksensor aussen 
Werte: frei wählbar 
Werteformat: Name des Sensors 
Standardwert:

====HomeSensorHumidityOutside====
Hier ist der Name des (Haupt)Aussensensors für Luftfeuchtigkeit anzugeben. Dieser muss ein Reading humidity besitzen. 
Falls der Sensor für (Aussen)Luftfeuchtigkeit und Aussentemperatur ein und der selbe ist, so muss dieser nur einmalig im Attribut HomeSensorTemperatureOutside hinterlegt werden. Dieser muss dann die beiden Readings humidity und temperature haben. Im Bedarfsfall können diese Readings auch vorher entsprechend durch eigene userReadings erstellt werden. 
Dieser Sensor stellt den Platzhalter '''%HUMIDITY%''' für den Wert des Readings humidity zur Verfügung. 
Werte: frei wählbar 
Werteformat: Device Name mit Reading humidity 
Standardwert:

====HomeSensorTemperatureOutside====
Hier ist der Name des (Haupt)Aussentemperatursensors anzugeben. Dieser muss mindestens ein Reading temperature besitzen. 
Falls der Sensor für Aussentemperatur auch ein Reading humidity besitzen sollte und dieses auch der Sensor für die Aussenlufteuchtigkeit ist, so muss dieser nur einmalig hier in diesem Attribut hinterlegt werden. 
Dieser Sensor stellt den Platzhalter '''%TEMPERATURE%''' für den Wert des Readings temperature zur Verfügung. 
Werte: frei wählbar 
Werteformat: Device Name mit Reading temperature und optional humidity 
Standardwert:

====HomeSensorsContact====
Hier können alle Kontakt Sensoren als Devspec hinterlegt werden. 
Diese Devices stellen zusätzlich die Platzhalter '''%ALIAS%''', '''%SENSOR%''' und '''%STATE%''' in den HomeCMDcontact Attributen zur Verfügung. '''%ALIAS%''' wird dann durch den Alias, '''%SENSOR%''' durch den Namen und '''%STATE%''' durch den aktuellen state des zuletzt ausgelösten Kontakts ersetzt. 
Werte: frei wählbar 
Werteformat: Devspec 
Standardwert: 
''In meinem Falle sind das optische und magnetische Kontaktsensoren vom HomeMatic. HM-SEC-SCO und HM-SEC-SC-2.'' 
''Darum ist bei mir als Devspec '''model=HM-SEC-SC(O|-2)''' eingetragen um alle diese Kontaktsensoren zu erfassen.'' 
Nach Übernehmen des Attributs werden alle gefundenen Kontaktsensoren mit ihren Namen im Internal SENSORSCONTACT des HOMEMODE Device einzeln aufgelistet und können dort auch direkt angeklickt werden. 
Des weiteren werden beim Übernehmen dieses Attributs jedem Kontaktsensor folgende Attribute im Attribut userattr hinzugefügt: 

=====HomeContactType=====
Typ des Kontakts - wird versucht anhand des Namen/Alias beim Hinzufügen zum HOMEMODE Device zu ermitteln, sollte jedoch für jeden Kontaktsensor einzeln überprüft werden 
Werte: doorinside,dooroutside,doormain,window 
Werteformat: vorgegebene Werteauswahl 
Standardwert: window

=====HomeModeAlarmActive=====
Regex der Alarm Mode(s) in denen der Kontaktsensor eine erfolgte Öffnung als Alarm melden soll. 
Werte: armaway|armhome|armnight 
Werteformat: Regex von Alarm Modes 
Standardwert: armaway

=====HomeOpenDontTriggerModes=====
Regex der Mode(s) des HOMEMODE Device in denen keine Offen Warnungen erfolgen sollen. 
Ist ein Kontakt geöffnet während die hier eingestellten Mode(s) eintreten, so wird der noch bestehende Timer abgebrochen. Entgegengesetzt startet er wieder sobal die hier eingestellten Mode(s) verlassen werden. 
Ist hier z.B. "gotosleep|asleep" eingestellt, so kann man z.B. das Fenster schon vor dem Auslösen von gotosleep oder asleep öffnen und der bestehende Offenwarnung-Timer wird dann abgebrochen. Sobald man am Morgen z.B. awoken oder home auslöst, so wird ein neuer Timer gestartet der einen dann an das noch offene Fenster erinnert. 
Werte: alle Modes des HOMEMODE Device 
Werteformat: Regex von Modes 
Standardwert:

=====HomeOpenDontTriggerModesResidents=====
Devspec der ROOMMATE/GUEST Devices deren Status statt der Modes des HOMEMODE Device für Attribut HomeOpenDontTriggerModes benutzt werden soll. 
Werte: alle überwachten ROOMMATE/GUEST 
Werteformat: Devspec 
Standardwert:

=====HomeOpenMaxTrigger=====
Maximale Anzahl an Warnmeldungen 
Werte: 0 bis ~ 
Werteformat: ganze Zahl 
Standardwert:

=====HomeOpenTimes=====
Leerzeichenseparierte Liste von Offen Warnung Zeiten in Minuten. 
Der erste Wert entspricht der ersten Zeit, der zweite Wert der zweiten Zeit usw. 
Die Anzahl sollte dem Wert im Attribut HomeOpenMaxTrigger entsprechen. Wenn hier weniger Zeiten vorgegeben werden, so wird für weitere Offen Warnungen immer die letzte hier angegebene Zeit verwendet. 
Werte: frei wählbar 
Werteformat: leerzeichenseparierte Liste von Zahlen mit einer Kommmastelle, z.B. 2.5 
Standardwert: 10

=====HomeOpenTimesDividers=====
Leerzeichenseparierte Liste von Offenwarnzeit Teilern. 
Es müssen so viele Werte angegeben werden wie in HomeSeasons Jahreszeiten hinterlegt worden sind (Default 4). 
Bei einer normalen Offenwarnzeit von 10 Minuten und den hier anzugebenen Teilern z.B. "2 1 2 3" ergeben sich für Frühling und Herbst Offenwarnzeiten von jeweils 5 Minuten und im Winter 3.3 Minuten. 
Die hier eingetragenen Werte überschreiben die Werte aus dem Attribut HomeSensorsContactOpenTimeDividers des HOMEMODE Device. 
Werte: frei wählbar 
Werteformat: leerzeichenseparierte Liste von Zahlen mit einer Kommmastelle, z.B. 2 1 2 2.5 
Standardwert:

=====HomeReadings=====
Zwei leerzeichenseparierte Readings für open und sabotage Status. 
Die hier eingetragenen Readings überschreiben die Werte aus dem Attribut HomeSensorsContactReadings des HOMEMODE Device. 
Werte: frei wählbar 
Werteformat: zwei Wörter 
Standardwert: state sabotageError

=====HomeValues=====
Regex der Werte die für offen und sabotiert stehen. 
Die hier eingetragenen Werte überschreiben die Werte aus dem Attribut HomeSensorsContactValues des HOMEMODE Device. 
Werte: frei wählbar 
Werteformat: Regex 
Standardwert: open|tilted|on

====HomeSensorsContactReadings====
Zwei leerzeichenseparierte Readings für open und sabotage Status. 
Die hier eingetragenen Readings sind global für alle Kontaktsensoren, können aber durch setzen des Attributs HomeReadings in jedem Sensor überschrieben werden. 
Werte: frei wählbar 
Werteformat: zwei Wörter 
Standardwert: state sabotageError

====HomeSensorsContactValues====
Regex der Werte die für offen und sabotiert stehen. 
Die hier eingetragenen Werte sind global für alle Kontaktsensoren, können aber durch setzen des Attributs HomeValues in jedem Sensor überschrieben werden. 
Werte: frei wählbar 
Werteformat: Regex 
Standardwert: open|tilted|on

====HomeSensorsContactOpenTimeDividers====
Leerzeichenseparierte Liste von Offenwarnzeit Teilern. 
Es müssen so viele Werte angegeben werden wie in HomeSeasons Jahreszeiten hinterlegt worden sind (Default 4). 
Bei einer normalen Offenwarnzeit von 10 Minuten und den hier anzugebenen Teilern z.B. "2 1 2 3" ergeben sich für Frühling und Herbst Offenwarnzeiten von jeweils 5 Minuten und im Winter 3.3 Minuten. 
Die hier eingetragenen Werte sind global für alle Kontaktsensoren, können aber durch setzen des Attributs HomeOpenTimesDividers in jedem Sensor überschrieben werden. 
Werte: frei wählbar 
Werteformat: leerzeichenseparierte Liste von Zahlen mit max. einer Kommmastelle, z.B. 2 1 2 2.5 (für 4 Jahreszeiten) 
Standardwert:

====HomeSensorsContactOpenTimeMin====
Minimale Zeit in Minuten die mindestens für eine Offenwarnung gewartet werden soll - im Falle dass sich durch den Teiler evtl. zu kleine Werte ergeben. 
Werte: frei wählbar 
Werteformat: eine Zahle mit max. einer Kommmastelle, z.B. 2.5 
Standardwert:

====HomeSensorsContactOpenTimes====
Leerzeichenseparierte Liste von Offen Warnung Zeiten in Minuten. 
Der erste Wert entspricht der ersten Zeit, der zweite Wert der zweiten Zeit usw. 
Die Anzahl sollte dem Wert im Attribut HomeOpenMaxTrigger entsprechen. Wenn hier weniger Zeiten vorgegeben werden, so wird für weitere Offen Warnungen immer die letzte hier angegebene Zeit verwendet. 
Werte: frei wählbar 
Werteformat: leerzeichenseparierte Liste von Zahlen mit max. einer Kommmastelle, z.B. 7.5 
Standardwert: 10

====HomeSensorsLuminance====
Devspec von (Innen-)Lichtsensoren deren Durchschnittswert berechnet werden soll 
Werte: frei wählbar 
Werteformat: Devspec 
Standardwert:

====HomeSensorsMotion====
Hier können alle Bewegungs Sensoren als Devspec hinterlegt werden. 
Diese Devices stellen zusätzlich die Platzhalter '''%ALIAS%''', '''%SENSOR%''' und '''%STATE%''' in den HomeCMDmotion Attributen zur Verfügung. '''%ALIAS%''' wird dann durch den Alias, '''%SENSOR%''' durch den Namen und '''%STATE%''' durch den aktuellen state des zuletzt ausgelösten Kontakts ersetzt. 
Werte: frei wählbar 
Werteformat: Devspec 
Standardwert:

''In meinem Falle sind das Fibaro Motion Sensor Gen4/5.'' 
''Darum ist bei mir als Devspec '''modelId=010f-0801-1001|010f-0800-1001''' eingetragen um alle diese Bewegungssensoren zu erfassen.'' 
''Damit bei den Gen5 Sensoren auch das open im reading state steht, habe ich mir bei diesen Sensoren ein userReading angelegt.'' 
Nach Übernehmen des Attributs werden alle gefundenen Bewegungssensoren mit ihren Namen im Internal SENSORSMOTION des HOMEMODE Device einzeln aufgelistet und können dort auch direkt angeklickt werden. 
Des weiteren werden beim Übernehmen dieses Attributs jedem Bewegungssensor folgende Attribute im Attribut userattr hinzugefügt:

=====HomeModeAlarmActive=====
Regex der Alarm Mode(s) in denen der Bewegungssensor eine erfolgte Öffnung als Alarm melden soll. 
Werte: armaway|armhome|armnight 
Werteformat: Regex von Alarm Modes 
Standardwert: armaway

=====HomeReadings=====
2 leerzeichenseparierte Readings für open und sabotage. 
Die hier eingetragenen Readings überschreiben die Werte aus dem Attribut HomeSensorsMotionReadings des HOMEMODE Device. 
Werte: frei wählbar 
Werteformat: zwei Wörter 
Standardwert: state sabotageError

=====HomeSensorLocation=====
Standort des Bewegungssensors (außen oder innen) - wird standardmäßig beim Hinzufügen zum HOMEMODE Device auf "inside" gesetzt, sollte jedoch für jeden Kontaktsensor einzeln überprüft werden 
Werte: inside,outside 
Werteformat: vorgegebene Werteauswahl 
Standardwert: inside

=====HomeValues=====
Regex der Werte die für offen und sabotiert stehen. 
Die hier eingetragenen Werte überschreiben die Werte aus dem Attribut HomeSensorsMotionValues des HOMEMODE Device. 
Werte: frei wählbar 
Werteformat: Regex 
Standardwert: open|on

====HomeSensorsMotionReadings====
2 leerzeichenseparierte Readings für open und sabotage. 
Die hier eingetragenen Readings sind global für alle Kontaktsensoren, können aber durch setzen des Attributs HomeReadings in jedem Sensor überschrieben werden. 
Werte: frei wählbar 
Werteformat: zwei Wörter 
Standardwert: state sabotageError

====HomeSensorsMotionValues====
Regex der Werte die für offen und sabotiert stehen. 
Die hier eingetragenen Werte sind global für alle Kontaktsensoren, können aber durch setzen des Attributs HomeValues in jedem Sensor überschrieben werden. 
Werte: frei wählbar 
Werteformat: Regex 
Standardwert: open|on

====HomeSensorsPowerEnergy====
Hier können alle Energie Sensoren als Devspec hinterlegt werden. Diese müssen die beiden Readings power und energy besitzen. 
Anhand dieser Readings wird dann der Gesamtverbrauch und die derzeitige gesamte Leistungsaufnahme berechnet. 
''In meinem Falle sind das Fibaro Wall Plugs Gen4/5.'' 
''Darum ist bei mir als Devspec '''modelId=010f-0600-1000|010f-0602-1001''' eingetragen um alle diese Energie Sensoren zu erfassen.'' 
Werte: frei wählbar 
Werteformat: Devspec mit vorhandenen energy und power Readings 
Standardwert:

====HomeSensorsSmoke====
Devspec mit Rauchmeldern 
Werte: frei wählbar 
Werteformat: Devspec 
Standardwert:

====HomeSensorWindspeed====
Sensor für Windgeschwindigkeit 
Werte: frei wählbar 
Werteformat: Name des Sensors und Reading der Windgeschwindigkeit separiert mit : (z.B. ga_Windsensor:wind) 
Standardwert:

====HomeSensorsBattery====
Devspec von Batteriesensoren mit einem Reading "battery" 
Werte: frei wählbar 
Werteformat: Devspec 
Standardwert:

====HomeTriggerAnyoneElseAtHome====
auslösendes Gerät für anyoneElseAtHome 
Werte: frei wählbar 
Werteformat: device:reading:valueOn:valueOff 
Standardwert:

====HomeTriggerPanic====
auslösendes Gerät für Panikalarm 
valueOff ist optional, wird es weggelassen, so fungiert valueOn als toggle 
Werte: frei wählbar 
Werteformat: device:reading:valueOn[:valueOff] 
Standardwert:

====HomeTwilightDevice====
Hier ist der Name des lokalen Twilight Device anzugeben. 
Diese Device stellt zusätzlich die Platzhalter '''%LIGHT%''', '''%TWILIGHT%''' und '''%TWILIGHTEVENT%''' in den HomeCMD Attributen zur Verfügung. '''%LIGHT%''' wird dann durch das Reading light, '''%TWILIGHT%''' durch das Reading twilight und '''%TWILIGHTEVENT%''' durch das aktuelle Twilight Event ersetzt. 
Werte: frei wählbar 
Werteformat: Devspec 
Standardwert:

====HomeUWZ====
Hier ist der Name des lokalen UWZ Geräts anzugeben. 
Platzhalter '''%UWZ%''', '''%UWZSHORT%''' und '''%UWZLONG%''' sind verfügbar in allen HomeCMD Attributen 
Werte: frei wählbar 
Werteformat: Name des UWZ Geräts 
Standardwert:

====HomeWeatherDevice====
Hier ist der Name des lokalen Weather Geräts anzugeben. 
Diese Device stellt zusätzlich einige Platzhalter zur Verfügung. Für die genaue Beschreibung derer siehe "Platzhalter". 
Werte: frei wählbar 
Werteformat: Devspec 
Standardwert:

===HomeText Attribute===
Die HomeText Attribute sind größtenteils zur Übersetzung einiger benötigter Begriffe gedacht. 
In den speziellen Attributen die mit HomeTextWeather anfangen, sind ganze Texte mit entsprechenden Platzhaltern einzufügen.

====HomeTextAndAreIs====
Übersetzung für "and", "are" und "is" 
Werte: frei wählbar separiert mit | 
Werteformat: Wort/Wörter 
Standardwert: and|are|is 
'''Beispiel:'''
und|sind|ist

====HomeTextClosedOpen====
Übersetzung für "closed" und "open" 
Werte: frei wählbar separiert mit | 
Werteformat: Wort 
Standardwert: closed|open 
'''Beispiel:'''
geschlossen|geöffnet

====HomeTextNosmokeSmoke====
Übersetzung für "no smoke" und "smoke" 
Werte: frei wählbar separiert mit | 
Werteformat: Wort 
Standardwert: no smoke|smoke 
'''Beispiel:'''
kein Rauch|Rauch

====HomeTextRisingConstantFalling====
Übersetzung für "rising", "constant" und "falling" 
Werte: frei wählbar separiert mit | 
Werteformat: Wort 
Standardwert: rising|constant|falling 
'''Beispiel:'''
steigend|gleichbleibend|fallend

====HomeTextTodayTomorrowAfterTomorrow====
Übersetzung für "today", "tomorrow" und "day after tomorrow" 
Werte: frei wählbar separiert mit | 
Werteformat: Wort 
Standardwert: today|tomorrow|day after tomorrow 
'''Beispiel:'''
Heute|Morgen|Übermorgen

====HomeTextWeatherNoForecast====
Übersetzung für "No forecast available" - Text wenn keine Wettervorhersage verfügbar ist 
Werte: frei wählbar 
Werteformat: Text 
Standardwert: No forecast available 
'''Beispiel:'''
Es ist leider keine Wettervorhersage für den angegebenen Tag verfügbar!

====HomeTextWeatherForecastInSpecDays====
Text mit Platzhaltern für Wettervorhersage in 4-10 Tagen 
spezielle Platzhalter die nur in diesem Attribut gültig sind: '''%CONDITION%''', '''%DAY%''', '''%HIGH%''' und '''%LOW%''' 
Werte: frei wählbar 
Werteformat: Text mit Platzhaltern 
Standardwert: 
'''Beispiel:'''
In %DAY% Tagen %CONDITION% bei Temperaturen von %LOW% bis %HIGH%°C.

====HomeTextWeatherForecastToday====
Text mit Platzhaltern für Wettervorhersage für heute 
spezielle Platzhalter die nur in diesem Attribut gültig sind: '''%CONDITION%''', '''%DAY%''', '''%HIGH%''' und '''%LOW%''' 
Werte: frei wählbar 
Werteformat: Text mit Platzhaltern 
Standardwert: 
'''Beispiel:'''
%DAY% %CONDITION% bei Temperaturen von %LOW% bis %HIGH%°C. Aktuelle Temperatur %TEMPERATURE%°C bei einer Luftfeuchtigkeit von %HUMIDITY%%. Die gefühlte Temperatur ist %WINDCHILL%°C bei einer Windgeschwindigkeit von %WIND%km/h.

====HomeTextWeatherForecastTomorrow====
Text mit Platzhaltern für Wettervorhersage für morgen/übermorgen 
spezielle Platzhalter die nur in diesem Attribut gültig sind: '''%CONDITION%''', '''%DAY%''', '''%HIGH%''' und '''%LOW%''' 
Werte: frei wählbar 
Werteformat: Text mit Platzhaltern 
Standardwert: 
'''Beispiel:'''
%DAY% %CONDITION% bei Temperaturen von %LOW% bis %HIGH%°C.

====HomeTextWeatherLong====
Langer Text mit Platzhaltern für aktuelle Wetterdaten 
Werte: frei wählbar 
Werteformat: Text mit Platzhaltern 
Standardwert: 
'''Beispiel:'''
Es %TOBE% %CONDITION% bei %TEMPERATURE%°C und %HUMIDITY%% Luftfeuchtigkeit. Die gefühlte Temperatur ist %WINDCHILL%°C bei einer Windgeschwindigkeit von %WIND%km/h. Der Luftdruck liegt bei %PRESSURE%hPa.

====HomeTextWeatherShort====
Kurzer Text mit Platzhaltern für aktuelle Wetterdaten 
Werte: frei wählbar 
Werteformat: Text mit Platzhaltern 
Standardwert: 
'''Beispiel:'''
%CONDITION%, %TEMPERATURE%°C, %HUMIDITY%% Luftfeuchtigkeit, Luftdruck %PRESSURE%hPa

===weitere Attribute===
Viele weitere Dinge lassen sich anpassen.

====HomeAdvancedDetails====
mehr Details anzeigen, abhängig von den zu HOMEMODE hinzugefügten Geräten 
Werte: none, detail, both, room 
Werteformat: Auswahlliste 
Standardwert: none

====HomeDaytimes====
Eigene Tageszeiten als Paare aus Zeit|Wort 
Werte: Zeit|Wort Paare separiert mit Leerzeichen 
Werteformat: Zeit|Wort 
Standardwert: 05:00|morning 10:00|day 14:00|afternoon 18:00|evening 23:00|night 
'''Beispiel:'''
00:00|Mitternacht
00:05|Nacht
06:30|Morgen
10:00|Vormittag
13:00|Mittag
14:30|Nachmittag
17:30|Vorabend
19:00|Abend
23:00|Spätabend

====HomeIcewarningOnOffTemps====
2 leerzeichenseparierte Temperaturen für das Ein- und Ausschalten der Eiswarnung. 
Werte: frei wählbar 
Werteformat: zwei leerzeichenseparierte Temperaturen mit maximal einer Kommastelle 
Standardwert: 2 3

====HomeModeAlarmArmDelay====
Zeit in Sekunden um das aktivieren der Alarmschaltung zu verzögern. 
Werte: 0 bis 99999 
Werteformat: einzelne Zahl (gleiche Verzögerung für alle modeAlarm) oder 3 leerzeichenseparierte Zahlen für jeden modeAlarm (Reihenfolge: armaway armnight armhome) 
Standardwert: 0

====HomeAtTmpRoom====
Diesen Raum zu temporäre at(s) hinzufügen die von HOMEMODE generiert werden 
Werte: frei wählbar 
Werteformat: Wort 
Standardwert:

====HomePresenceDeviceAbsentCount-<ROOMMATE/GUEST>====
Anzahl der dem ROOMMATE/GUEST zugeordneten Presence Geräte um den jeweiligen ROOMMATE/GUEST auf "absent" zu setzen 
Das Attribut ist nur verfügbar wenn mehr als ein Presence Gerät pro ROOMMATE/GUEST gefunden/zugeordnet wurde 
Werte: 0 bis ~ 
Werteformat: einzelne Zahl 
Standardwert: maximale Anzahl von verfügbaren Presence Geräten für jeden ROOMMATE/GUEST

====HomePresenceDevicePresentCount-<ROOMMATE/GUEST>====
Anzahl der dem ROOMMATE/GUEST zugeordneten Presence Geräte um den jeweiligen ROOMMATE/GUEST auf "present" zu setzen 
Das Attribut ist nur verfügbar wenn mehr als ein Presence Gerät pro ROOMMATE/GUEST gefunden/zugeordnet wurde 
Werte: 0 bis ~ 
Werteformat: einzelne Zahl 
Standardwert: 1

====HomePublicIpCheckInterval====
Interval in Minuten für die Überprüfung der öffentlichen IP-Adresse 
Werte: 0 bis 99999 
Werteformat: einzelne Zahl 
Standardwert: 0 (deaktiviert)

====HomeSeasons====
Eigene Jahreszeiten als Paare aus Datum|Wort 
Werte: Datum|Wort Paare separiert mit Leerzeichen 
Werteformat: Datum|Wort 
Standardwert: 03.01|spring 06.01|summer 09.01|autumn 12.01|winter 
'''Beispiel:'''
03.01|Frühling
06.01|Sommer
09.01|Herbst
12.01|Winter

====HomeSensorsBatteryLowPercentage====
Prozentsatz um einen Batteriesensor mit geringer Batterie anzuzeigen (nur bei Sensoren die ihren Batteriewert prozentual angeben) 
Werte: frei wählbar 
Werteformat: Zahl 
Standardwert: 50

====HomeSensorsBatteryReading====
Reading der Batteriesensoren welches statt "battery" benutzt werden soll 
Werte: frei wählbar 
Werteformat: einzelnes Wort 
Standardwert: battery

====HomeSensorsLuminanceReading====
Reading der Lichtsensoren welches statt "luminance" benutzt werden soll 
Werte: frei wählbar 
Werteformat: einzelnes Wort 
Standardwert: luminance

====HomeSensorsPowerEnergyReadings====
Readings der Power/Energy Sensoren welche statt "power" und "energy" benutzt werden sollen 
Werte: frei wählbar 
Werteformat: 2 leerzeichenseparierte Wörter 
Standardwert: power energy

====HomeSensorsSmokeReading====
Readings der Rauchmelder welche statt "state" benutzt werden sollen 
Werte: frei wählbar 
Werteformat: ein Wort 
Standardwert: state

====HomeSensorsSmokeValue====
Regex der Auslösewerte von Rauchmeldern 
Werte: frei wählbar 
Werteformat: RegEx 
Standardwert: on

====HomeSpecialLocation====
Hier können eigene zusätzliche location(s) als kommaseparierte Liste angegeben werden. 
Diese können dann über "set <HOMEMODE> location <LOCATION>" gesetzt werden. Dazu passend werden HomeCMD Attribute erstellt. 
Werte: frei wählbar 
Werteformat: kommaseparierte Liste von Wörtern 
Standardwert:

====HomeSpecialModes====
Hier können eigene zusätzliche mode(s) als kommaseparierte Liste angegeben werden. 
Diese können dann über "set <HOMEMODE> mode <MODE>" gesetzt werden. Dazu passend werden HomeCMD Attribute erstellt. 
Werte: frei wählbar 
Werteformat: kommaseparierte Liste von Wörtern 
Standardwert:

====HomeTrendCalcAge====
Zeit in Sekunden für das Maximalalter des vorherigen Wertes für die Trendberechnung 
Werte: frei wählbar 
Werteformat: Zeit in Sekunden 
Standardwert: 900

Ein weiterer Teil der Konfiguration ist das Befüllen der HomeCMD Attribute. Da dieses durch die Vermischung von FHEM Code, Perl Code und zusätzlichen Platzhaltern erst einmal sehr befremdlich sein kann, habe ich bei der Beschreibung der HomeCMD Attribute teilweise Beispiele hinzugefügt um den Einstieg weiter zu erleichtern.

==HomeCMD Attribute (mit Beispielen)==
Die HomeCMD Attribute sind zum Festlegen der jeweiligen Schaltaktionen gedacht und können damit evtl. vorhandene notify/DOIF ablösen. Sie können mit FHEM-Code, Perl-Code oder aber auch mit beidem vermischt befüllt werden (wovon ich allerdings abrate). Zusätzlich sind noch diverse Platzhalter (siehe Platzhalter) verfügbar.

'''Bei Perl-Code innerhalb der HomeCMD Attribute gibt es hier Besonderheiten.''' 
*Im Gegensatz zur FHEM-Eingabezeile müssen hier keine Semikolon verdoppelt werden
*Kommetarzeilen sind zulässig
*Kommentare am Ende einer Perl-Zeile sind nicht zulässig

Typischer Weise werden in den HomeCMD Attributen weitere Module angesprochen. 
Z.B. benutze ich für jegliche Form der Benachrichtigung den msg Befehl.

Keines der HomeCMD Attribute hat einen Standardwert. Es müssen alle Befehle selbst programmiert werden.

Platzhalter die Text(e) (string) beinhalten, müssen im Perl-Code in Anführungszeichen gesetzt werden (Beispiel %SENSOR%). 
Platzhalter die Zahlen beinhalten (int,float) sollten nicht in Anführungszeichen gesetzt werden damit Zahlenvergleiche (mittels ==, <=, >=, >, <) funktionieren (Beispiel %LIGHT%, %ICE% oder %TEMPERATURE%).

====HomeCMDalarmSmoke====
Befehle die beim Anfang/Ende eines Rauchalarms ausgeführt werden sollen. 

====HomeCMDalarmSmoke-off====
Befehle die beim Ende eines Rauchalarms ausgeführt werden sollen. 
Auslöser: Ende Rauchalarm eines beliebigen (von HOMEMODE überwachten) Rauchmelders 
'''Beispiel:'''
msg push ENTWARNUNG: Alle Rauchalarme sind beendet!

====HomeCMDalarmSmoke-on====
Befehle die bei einem Rauchalarm ausgeführt werden sollen. 
Auslöser: Rauchalarm eines beliebigen (von HOMEMODE überwachten) Rauchmelders 
'''Beispiel:'''
{
my $is = "meldet";
$is = "melden" if (%SMOKECT% > 1);
fhem "msg push ACHTUNG: %SMOKEHR% $is Rauchalarm!";
}

====HomeCMDalarmTampered====
Befehle die beim Anfang/Ende eines Sabotage Alarms ausgeführt werden sollen.

====HomeCMDalarmTampered-off====
Befehle die beim Ende eines Sabotage Alarms ausgeführt werden sollen. 
Auslöser: Ende Sabotage Alarm eines beliebigen (von HOMEMODE überwachten) Kontakt-/Bewegungs-Sensors 
'''Beispiel:'''
msg push ENTWARNUNG: Alle Manipulationen wurden beseitigt!

====HomeCMDalarmTampered-on====
Befehle die bei einem Sabotage Alarm ausgeführt werden sollen. 
Auslöser: Sabotage Alarm eines beliebigen (von HOMEMODE überwachten) Kontakt-/Bewegungs-Sensors 
'''Beispiel:'''
{
my $is = "ist";
$is = "sind" if (%TAMPEREDCT% > 1);
fhem "msg push ACHTUNG: %TAMPEREDHR% $is sabotiert!";
}

====HomeCMDalarmTriggered====
Befehle die beim Anfang/Ende eines Alarms ausgeführt werden sollen.

====HomeCMDalarmTriggered-off====
Befehle die beim Ende eines Alarms ausgeführt werden sollen. 
Auslöser: Ende Alarm eines beliebigen (von HOMEMODE überwachten) Kontakt-/Bewegungs-Sensors 
'''Beispiel:'''
msg ENTWARNUNG: Alle Alarme sind beendet!

====HomeCMDalarmTriggered-on====
Befehle die bei einem Alarm ausgeführt werden sollen. 
Auslöser: Alarm eines beliebigen (von HOMEMODE überwachten) Kontakt-/Bewegungs-Sensors 
'''Beispiel:'''
{
my $is = "ist";
$is = "sind" if (%ALARMCT% > 1);
fhem "msg audio,push,light 3 !!! ALARM !!! %ALARMHR% $is ausgelöst!";
}

====HomeCMDanyoneElseAtHome====
Befehle die beim on/off von anyoneElseAtHome ausgeführt werden sollen.

====HomeCMDanyoneElseAtHome-off====
Befehle die ausgeführt werden sollen sobald anyoneElseAtHome deaktiviert wird. 
Bei Abwesenheit und nicht deaktiviertem HomeAutoAlarmModes wird der Alarm Mode von "armaway" auf "armhome" umgeschaltet damit evtl. vorhandene Bewegungsmelder keinen Alarm mehr melden. 
Auslöser: anyoneElseAtHome on 
'''Beispiel:'''
msg HINWEIS: Es ist nun niemand anderes mehr zu Hause!

====HomeCMDanyoneElseAtHome-on====
Befehle die ausgeführt werden sollen sobald anyoneElseAtHome aktiviert wird. 
Bei Abwesenheit und nicht deaktiviertem HomeAutoAlarmModes wird der Alarm Mode von "armhome" auf "armaway" umgeschaltet damit evtl. vorhandene Bewegungsmelder wieder Alarme melden können. 
Wird anyoneElseAtHome bei Anwesenheit und nicht deaktiviertem HomeAutoAlarmModes aktiviert, so passiert erst einmal nichts, ausser dass die hier angegebenen Befehle ausgeführt werden. Wird dann später die Abwesenheit erkannt, schaltet der Alarm Mode auf "armhome" statt auf "armaway" damit evtl. vorhandene Bewegungsmelder keinen Alarm mehr melden. 
Auslöser: anyoneElseAtHome off 
'''Beispiel:'''
msg HINWEIS: Es ist nun noch jemand anderes zu Hause!

====HomeCMDbatteryLow====
Befehle die ausgeführt werden sollen sobald ein Sensor einen niedrigen Batteriewert meldet. 
'''Beispiel:'''
{
my $msg;
$msg = "Die Batterien von %BATTERYLOW% gehen zur Neige und sollten ausgetauscht werden!" if (%BATTERYLOWCT% == 1);
$msg = "Die Batterien bei folgenden Geräten sollten ausgetauscht werden: %BATTERYLOWALL%" if (%BATTERYLOWCT% > 1);
fhem "msg push $msg";
}

====HomeCMDcontact====
Befehle die ausgeführt werden sollen sobald ein Kontaktsensor open/tilted/closed meldet. 
Die speziellen Platzhalter %ALIAS%, %SENSOR% und %STATE% können in diesem Attribut benutzt werden. 
Auslöser: Kontaktsensor open/tilted/closed 
'''Beispiel:'''
{
my $a = "%ALIAS%";
$a =~ s/d/D/;
fhem "msg $a ist nun %STATE%!";
}

====HomeCMDcontactClosed====
Befehle die ausgeführt werden sollen sobald ein Kontaktsensor geschlossen meldet. 
Die speziellen Platzhalter %ALIAS%, %SENSOR% und %STATE% können in diesem Attribut benutzt werden. 
Auslöser: Kontaktsensor closed 
'''Beispiel:'''
{
my $a = "%ALIAS%";
$a =~ s/d/D/;
fhem "msg $a ist nun geschlossen!";
}

====HomeCMDcontactOpen====
Befehle die ausgeführt werden sollen sobald ein Kontaktsensor offen meldet. 
Die speziellen Platzhalter '''%ALIAS%''', '''%SENSOR%''' und '''%STATE%''' können in diesem Attribut benutzt werden. 
Auslöser: Kontaktsensor open/tilted 
'''Beispiel:'''
{
my $a = "%ALIAS%";
$a =~ s/d/D/;
fhem "msg $a ist nun offen!";
}

====HomeCMDcontactDoormain====
Befehle die ausgeführt werden sollen sobald ein Kontaktsensor des Types doormain open/tilted/closed meldet. 
Die speziellen Platzhalter %ALIAS%, %SENSOR% und %STATE% können in diesem Attribut benutzt werden. 
Auslöser: Kontaktsensor Type doormain open/tilted/closed 
'''Beispiel:'''
{
my $a = "%ALIAS%";
$a =~ s/d/D/;
fhem "msg $a ist nun %STATE%!";
}

====HomeCMDcontactDoormainClosed====
Befehle die ausgeführt werden sollen sobald ein Kontaktsensor des Types doormain closed meldet. 
Die speziellen Platzhalter '''%ALIAS%''', '''%SENSOR%''' und '''%STATE%''' können in diesem Attribut benutzt werden. 
Auslöser: Kontaktsensor vom Typ doormain wird geschlossen 
'''Beispiel:'''
{
# Wenn es Ankommende gibt
if ("%ARRIVERS%")
{
# Zusammenstellen der Begrüßung
my $msg = "Gute";

# "n" anhängen wenn Tageszeit nicht Nacht ist
$msg .= "n" if ("%DAYTIME%" ne "Nacht");

# Leerzeichen einfügen
$msg .= " ";

# den Feiertag der Tageszeit voranstellen wenn ein Feiertag im Kalender FEIERTAG ist
$msg .= "%FEIERTAG%-" if ("%FEIERTAG%");

# Tageszeit einfügen
$msg .= "%DAYTIME% ";

# bei ROOMMATE "zu Hause" in Begrüßung einfügen
$msg .= "zu Hause " if ("%RESIDENT%" =~ /^rr_/);

# Ankommende einfügen
$msg .= "%ARRIVERS%";

# Begrüßung am Sonos im Flur ausgeben bei Abwesenheit über 60 min
fhem "msg audio \@fl_Sonos $msg!" if (%DURABSENCELAST% > 60);
}
}

====HomeCMDcontactDoormainOpen====
Befehle die ausgeführt werden sollen sobald ein Kontaktsensor des Types doormain open/tilted meldet. 
Die speziellen Platzhalter '''%ALIAS%''', '''%SENSOR%''' und '''%STATE%''' können in diesem Attribut benutzt werden. 
Auslöser: Kontaktsensor vom Typ doormain geöffnet 
'''Beispiel:'''
{
my $a = "%ALIAS%";
$a =~ s/d/D/;
fhem "msg $a ist nun geöffnet!";
}

====HomeCMDcontactOpenWarning1====
Befehle die ausgeführt werden sollen sobald ein Kontaktsensor die erste Offenwarnzeit erreicht hat. 
Die speziellen Platzhalter '''%ALIAS%''', '''%SENSOR%''' und '''%STATE%''' können in diesem Attribut benutzt werden. 
Auslöser: erste Offenwarnzeit des Kontakts erreicht 
'''Beispiel:'''
msg audio %ALIAS% steht noch offen!

====HomeCMDcontactOpenWarning2====
Befehle die ausgeführt werden sollen sobald ein Kontaktsensor die zweite Offenwarnzeit erreicht hat. 
Die speziellen Platzhalter '''%ALIAS%''', '''%SENSOR%''' und '''%STATE%''' können in diesem Attribut benutzt werden. 
Auslöser: ab Erreichen der zweiten Offenwarnzeit des Kontakts 
'''Beispiel:'''
msg audio %ALIAS% steht immer noch offen!

====HomeCMDcontactOpenWarningLast====
Befehle die ausgeführt werden sollen sobald ein Kontaktsensor die letzte Offenwarnzeit erreicht hat. 
Die speziellen Platzhalter '''%ALIAS%''', '''%SENSOR%''' und '''%STATE%''' können in diesem Attribut benutzt werden. 
Auslöser: Erreichen der letzten Offenwarnzeit des Kontakts 
'''Beispiel:'''
msg audio Das ist der letzte Hinweis %ALIAS% endlich zu schliessen!

====HomeCMDdaytime====
Befehle die ausgeführt werden sollen sobald sich die Tageszeit (daytime) auf einen beliebigen Wert ändert. 
Um die jeweilige eingetretene Tageszeit zu ermitteln ist der Platzhalter '''%DAYTIME%''' vorgesehen. 
Auslöser: Änderung der Tageszeit (daytime)

====HomeCMDdaytime-<DAYTIME>====
Befehle die ausgeführt werden sollen sobald die jeweilige Tageszeit (daytime) erreicht ist. 
Auslöser: Änderung der Tageszeit (daytime) auf bestimmten Wert 
Bei "night" könnte man z.B. die Heizung bewohnerunabhängig ausschalten, bei "morning" wieder ein.

====HomeCMDdeviceDisable====
Befehle die ausgeführt werden sollen sobald ein Gerät deaktiviert wird. 
Auslöser: 'set deviceDisable <DEVICE>' 
'''Beispiel:'''
{
speak "Das Gerät %ALIAS% ist nun deaktiviert!";

# optional wirklich attr disable für Device setzen und Konfig speichern
#fhem "attr %DEVICE%:FILTER=disable!=1 disable 1; save";

# ROOMMATE/GUEST auf gone/none setzen wenn Presence Devices deaktiviert werden
if ("%DEVICE%" =~ /^PRESENCE\d?_(r[rg]_.*)/)
{
my $resident = $1;
my $gone = $resident =~ /^rr_/ ? "gone" : "none";
fhem "set $resident:FILTER=state!=$gone state $gone";
}
}

====HomeCMDdeviceEnable====
Befehle die ausgeführt werden sollen sobald ein Gerät aktiviert wird. 
Auslöser: 'set deviceEnable <DEVICE>' 
'''Beispiel:'''
{
speak "Das Gerät %ALIAS% ist nun aktiviert!";

# optional attr disable für Device entfernen und Konfig speichern
#fhem "deleteattr %DEVICE%:FILTER=disable=1 disable; save";

# ROOMMATE/GUEST auf home setzen wenn Presence Devices aktiviert werden und anwesend sind
if ("%DEVICE%" =~ /^PRESENCE\d?_(r[rg]_.*)/)
{
fhem "set $1:FILTER=state!=home state home" if (ReadingsVal("%DEVICE%","presence","") eq "present");
}
}

====HomeCMDdnd====
Befehle die beim Anfang/Ende des DND Modus ausgeführt werden sollen. 
Auslöser: Ende des DND Modus 
'''Beispiel:'''
{
if (%DND%)
{
fhem "msg audio Der DND Modus ist nun eingeschaltet!";
}
else
{
fhem "msg audio Der DND Modus ist nun beendet!";
}
}

====HomeCMDdnd-off====
Befehle die beim Ende des DND Modus ausgeführt werden sollen. 
Auslöser: Ende des DND Modus 
'''Beispiel:'''
msg audio Der DND Modus ist nun beendet!

====HomeCMDdnd-on====
Befehle die beim Beginn des DND Modus ausgeführt werden sollen. 
Auslöser: Beginn des DND Modus 
'''Beispiel:'''
msg audio Der DND Modus ist nun eingeschaltet!

====HomeCMDevent====
Befehle die beim Beginn eines beliebigen (holiday)Kalender Events ausgeführt werden sollen. 
Auslöser: Beginn eines beliebigen (holiday)Kalender Events 
Platzhalter '''%CALENDAR%''', '''%EVENT%''' und '''%PREVEVENT%''' können zusätzlich verwendet werden 
'''Beispiel:'''
{
fhem "set Weihnachten on" if ("%EVENT%" eq "Weihnachten");
fhem "set Weihnachten off" if ("%PREVEVENT%" eq "Weihnachten");
}

====HomeCMDevent-<KALENDER>-each====
Befehle die beim Beginn/Ende eines beliebigen (holiday)Kalender Events eines bestimmten KALENDERs ausgeführt werden sollen. 
Auslöser: Beginn eines beliebigen (holiday)Kalender Events eines bestimmten KALENDERs 
Platzhalter '''%EVENT%''' und '''%PREVEVENT%''' können zusätzlich verwendet werden 
'''Beispiel für "HomeCMDevent-FEIERTAGE-each":'''
{
fhem "set Weihnachten off" if ("%PREVEVENT%" eq "Weihnachten");
}
'''Beispiel für "HomeCMDevent-URLAUBDAN-each":'''
{
if ("%EVENT%" =~ /urlaub/i)
{
speak "Dan hat jetzt Urlaub!!!";
}
elsif ("%PREVEVENT%" =~ /urlaub/i)
{
speak "Der Urlaub von Dan ist nun zu Ende!!!";
}
}

'''Beispiel für "HomeCMDevent-WOHNUNG-each":'''
{
# Heizung an/aus schalten
my $heiz = "([bksw]z|ku)_Thermostat";
if ("%EVENT%" =~ /^heizung(..+)?$/i)
{
my $zeit = $1;
if ("%SEASON%" ne "Sommer")
{

# morgens nicht alle Thermostaten schalten
$heiz = "([bks]z|ku)_Thermostat" if ($zeit && $zeit =~ /morgens?$/i);
fhem "set $heiz:FILTER=controlMode!=day controlMode day"
}
}
elsif ("%PREVEVENT%" =~ /^heizung/i)
{
fhem "set $heiz:FILTER=controlMode!=night controlMode night" if ("%SEASON%" ne "Sommer");
}

# WLAN an/aus schalten
elsif ("%EVENT%" =~ /^wlan|wifi|wi-fi/i)
{
fhem "set Router wifi off";
}
elsif ("%PREVEVENT%" =~ /^wlan|wifi|wi-fi/i)
{
fhem "set Router wifi on";
}

# G-Tag für Putzfrau (de)aktivieren
elsif ("%EVENT%" =~ /^putz/i)
{
fhem "set %NAME% deviceEnable PRESENCE_rg_Inge";
}
elsif ("%PREVEVENT%" =~ /^putz/i)
{
fhem "set %NAME% deviceDisable PRESENCE_rg_Inge";
}

# G-Tag für Gast (de)aktivieren
elsif ("%EVENT%" =~ /g([aä]|ae)st/i)
{
fhem "set %NAME% deviceEnable PRESENCE_rg_Gast";
}
elsif ("%PREVEVENT%" =~ /g([aä]|ae)st/i)
{
fhem "set %NAME% deviceDisable PRESENCE_rg_Gast";
}
}

====HomeCMDevent-<KALENDER>-<EVENT>-begin====
Befehle die beim Beginn eines bestimmten (holiday)Kalender EVENTs eines bestimmten KALENDERs ausgeführt werden sollen. 
Auslöser: Beginn eines bestimmten (holiday)Kalender EVENTs eines bestimmten KALENDERs 
Platzhalter '''%PREVEVENT%''' kann zusätzlich verwendet werden 
'''Beispiel für "HomeCMDevent-FEIERTAGE-Neujahr-begin":'''
set %SENSORSENERGY% meterReset

====HomeCMDevent-<KALENDER>-<EVENT>-end====
Befehle die bei Ende der (holiday)Kalender EVENTs eines bestimmten KALENDERs ausgeführt werden sollen. 
Auslöser: Ende der (holiday)Kalender EVENTs eines bestimmten KALENDERs 
Platzhalter '''%PREVEVENT%''' kann zusätzlich verwendet werden

====HomeCMDfhemDEFINED====
Befehle die ausgeführt werden sollen wenn ein neues Gerät angelegt wird (define) 
'''Beispiel:'''
{
# Jedem neu definierten Gerät den Geräte-TYPE auch als Raum im Menüpunkt Module zuweisen
fhem "attr %DEFINED% room Module->".InternalVal("%DEFINED%","TYPE","default");
}

====HomeCMDfhemINITIALIZED====
Befehle die ausgeführt werden sollen wenn FHEM gestartet wurde 
'''Beispiel:'''
msg FHEM Home wurde gestartet...

====HomeCMDfhemSAVE====
Befehle die ausgeführt werden sollen wenn in FHEM die Konfigurationsdatei gespeichert wird 
'''Beispiel (Backup von fhem.cfg und fhem.state):'''
{
# Datum/Uhrzeit
my $now = TimeNow();
# Leerzeichen durch Unterstriche ersetzen
$now =~ s/ /_/g;
# Backup der Datei fhem.cfg
`cp $attr{global}{configfile} ./backup/fhem.cfg.$now`;
# Log-Ausgabe der gespeicherten Datei
Log3 undef,3,"saved ./backup/fhem.cfg.$now";
# Backup der Datei fhem.state
`cp $attr{global}{statefile} ./backup/fhem.state.$now`;
# Log-Ausgabe der gespeicherten Datei
Log3 undef,3,"saved ./backup/fhem.state.$now";
}

====HomeCMDfhemUPDATE====
Befehle die ausgeführt werden sollen wenn das Update von FHEM ausgeführt wurde 
'''Beispiel:'''
msg audio Das Update für FHEM ist beendet!

====HomeCMDicewarning====
Befehle die bei Anfang/Ende der Eiswarnung ausgeführt werden sollen 
Auslöser: icewarning 0/1 
'''Beispiel:'''
{
if (%ICE%)
{
fhem "msg push ACHTUNG!!! Es sind nur noch %TEMPERATURE%°C! Somit könnte es glatt werden!";
}
else
{
fhem "msg audio Es sind wieder %TEMPERATURE%°C! Die Glättewarnung ist damit beendet!.";
}
}

====HomeCMDicewarning-off====
Befehle die bei Ende der Eiswarnung ausgeführt werden sollen 
Auslöser: icewarning 0 
'''Beispiel:'''
msg audio Es sind wieder %TEMPERATURE%°C! Die Glättewarnung ist damit beendet!

====HomeCMDicewarning-on====
Befehle die bei Beginn der Eiswarnung ausgeführt werden sollen 
Auslöser: icewarning 1 
'''Beispiel:'''
msg audio ACHTUNG!!! Es sind nur noch %TEMPERATURE%°C! Somit könnte es glatt werden!

====HomeCMDlocation====
Befehle die beim Ändern der location ausgeführt werden sollen. 
Auslöser: Änderung location

====HomeCMDlocation-<LOCATION>====
Befehle die bei Änderung auf eine bestimmte location ausgeführt werden sollen. 
Auslöser: Änderung auf bestimmte location

====HomeCMDmode====
Befehle die beim Ändern von mode ausgeführt werden sollen. 
Auslöser: Änderung mode

====HomeCMDmode-absent-belated====
Befehle die nachträglich zur Abwesenheit ausgeführt werden sollen, die Zeit kann im Atteribut "HomeModeAbsentBelatedTime" eingestellt werden 
Auslöser: Abwesenheit + XX min 
'''Beispiel:'''
set Heizungen [FILTER=controlManu!=off] controlMode night

====HomeCMDmode-<MODE>====
Befehle die bei Änderung auf einen bestimmten mode ausgeführt werden sollen. 
Auslöser: Änderung auf bestimmten mode 
'''Beispiel für "HomeCMDmode-absent":'''
set HarmonyHub:FILTER=activity!=PowerOff activity PowerOff;
set wz_Ventilator:FILTER=speed!=0 speed 0;
set TYPE=SONOSPLAYER:FILTER=Volume>0 Volume 0;
set Sonos stopAll;
sleep 3;
set Wohnung [FILTER=state!=off] off"
'''Beispiel für "HomeCMDmode-asleep":'''
define atTmp_wz_Media_aus_%SELF% at +01:00:00 set HarmonyHub:FILTER=currentActivity!=PowerOff activity PowerOff;
define atTmp_wz_Venti_aus_%SELF% at +01:00:00 set wz_Ventilator:FILTER=speed!=0 speed 0;
define atTmp_wzLS_aus_%SELF% at +00:30:00 set wz_LS scene aus;
define atTmp_all_Sonos_vol_down_%SELF% at +00:02:00 set TYPE=SONOSPLAYER:FILTER=Volume!=0 Volume 0 1;
define atTmp_all_Sonos_off_%SELF% at +00:02:30 set Sonos stopAll;
set [sw]z_Auto(Music|Light):FILTER=state!=off off;
set Heizungen [FILTER=controlManu!=off] controlMode night
'''Beispiel für "HomeCMDmode-awoken":'''
set [sw]z_Auto(Music|Light):FILTER=state!=on on
'''Beispiel für "HomeCMDmode-gone":'''
set Heizungen [FILTER=controlManu!=off] controlManu off

====HomeCMDmode-<MODE>-resident====
Befehle die bei Änderung auf einen bestimmten mode, ausgelöst durch einen beliebigen Resident, ausgeführt werden. 
Auslöser: Änderung mode von beliebigem Resident ausgelöst 
'''Beispiel für "HomeCMDmode-asleep-resident":'''
msg audio @%AUDIO% Guten Nacht und schlaf' gut %ALIAS%!
'''Beispiel für "HomeCMDmode-awoken-resident":'''
{
my $msg = "Guten";
$msg .= " %FEIERTAG%" if ("%FEIERTAG%");
$msg .= " Morgen %ALIAS%";
fhem "msg audio \@%AUDIO% $msg";
fhem "defmod atTmp_wetter_%RESIDENT%_%SELF% at +00:07:00 msg audio Wettervorhersage für heute: %FORECASTTODAY%";
}

====HomeCMDmode-<MODE>-<ROOMMATE/GUEST>====
Befehle die bei Änderung auf einen bestimmten mode, ausgelöst durch einen bestimmten Resident, ausgeführt werden. 
Auslöser: Änderung mode von bestimmten Resident ausgelöst

====HomeCMDmodeAlarm====
Befehle die beim Ändern von modeAlarm ausgeführt werden sollen. 
Auslöser: Änderung modeAlarm

====HomeCMDmodeAlarm-<armaway/armhome/armnight/disarm>====
Befehle die bei Änderung auf einen bestimmten modeAlarm ausgeführt werden sollen. 
Auslöser: Änderung auf bestimmten modeAlarm 
'''Beispiel für "HomeCMDmodeAlarm-armaway":'''
{
if ("%PREVAMODE%" eq "disarm")
{
# Alarmanlage einschalten
fhem "set AA_Arm:FILTER=level!=100 alarmLevel armAll";

# Nachricht zusammensetzen
my $msg;
$msg .= "Die Alarmanlage ist nun scharf geschaltet!" if ("%RESIDENT%" ne "rr_Dan");
my $is = "%ALARMHR%" =~ /und/ ? "sind" : "ist";
$msg .= " " if ($msg);
$msg .= "ACHTUNG: %ALARMHR% $is noch offen!!!" if (%ALARMCT%);

# Nachricht an ROOMMATE/GUEST senden
fhem "msg \@%RESIDENT% $msg" if ($msg);

# Eingangstür abschließen falls noch nicht geschehen
fhem "set fl_Tuerschloss:FILTER=state!=locked lock";
}
}
'''Beispiel für "HomeCMDmodeAlarm-armhome":'''
AA_Arm:FILTER=level!=25 alarmLevel armExtSens;
set fl_Tuerschloss:FILTER=state!=locked lock
'''Beispiel für "HomeCMDmodeAlarm-armnight":'''
AA_Arm:FILTER=level!=25 alarmLevel armExtSens;
set fl_Tuerschloss:FILTER=state!=locked lock
'''Beispiel für "HomeCMDmodeAlarm-disarm":'''
{
# Alarmanlage ausschalten
fhem "set AA_Arm:FILTER=level!=0 alarmLevel disarmed";
my $prio = "";

# Nachrichtenpriorität auf 1 setzen bei Ankunft (höhere Lautstärke beim Abspielen damit man das auch vor der Tür hört)
$prio = " 1" if ("%LOCATION%" eq "arrival");

# Nachricht an ROOMMATE/GUEST senden wenn der vorherige alarmMode nicht "armnight" ist
fhem "msg audio \@fl_Sonos$prio Die Alarmanlage ist nun ausgeschaltet %ALIAS%!" if ("%PREVAMODE%" ne "armnight");
}

====HomeCMDmotion====
Befehle die bei Statusänderung eines beliebigen Bewegungsmelders ausgeführt werden sollen 
Auslöser: öffnen/schließen eines beliebigen Bewegungsmelders 
'''Beispiel:'''
{
# Raum aus Sensornamen ermitteln, z.B. bz_Sensor
my $room = (split /_/,"%SENSOR%")[0];

# Status des structure aller Lichter dieses Raums
my $lichter = Value($room."_Lichter");

# Status des dummy Tageslicht
my $tl = Value("Tageslicht");

if ("%STATE%" eq "geöffnet")
{
# Lichtwert des Sensors
my $lum = ReadingsNum("%SENSOR%","luminance",100);

# Löschen des evtl. schon vorhandenen "at"
fhem "delete atTmp_Bewegungsmelder_Licht_aus_".$room."_%SELF%" if (IsDevice("atTmp_Bewegungsmelder_Licht_aus_".$room."_%SELF%"));

# Licht nur wenn kein Tageslicht oder Lichtwert des Sensors kleiner als 10 und AutoLight eingeschaltet und modeAlarm nicht armaway
if (($tl eq "off" || $lum < 10) && $lichter eq "off" && Value($room."_AutoLight") eq "on" && "%AMODE%" ne "armaway")
{
my $scene;

# verschiedene Szenen für verschiedene Modus bzw. Aussenlichtstärken
if ("%MODE%" eq "gotosleep")
{
$scene = "Abend";
}
elsif ("%MODE%" eq "asleep")
{
$scene = "Nacht";
}
elsif (%LIGHT% > 3)
{
$scene = "viel";
}
elsif (%LIGHT% < 4)
{
$scene = "mittel";
}

# Schalten der entsprechenden Szene (Modul LightScene)
fhem "set ".$room."_LS scene $scene" if ($scene);
}
}
else
{
# unterschiedliche Ausschaltzeiten für unterschiedliche Räume
my $t = 3;
$t = 15 if ($room eq "wz");
$t = 2 if ($room eq "bz" || ($room =~ /wz|ku/ && "%MODE%" =~ /sleep/));
$t = 1 if ($room eq "fl");

# Zahl in Minuten umrechnen in einen Zeitpunkt für das "at"
my $d = HOMEMODE_hourMaker($t);

# Anlegen des "at" zum Ausschalten des Lichts wenn die Lichter angeschaltet sind und auch AutoLight eingeschaltet ist
if ($lichter ne "off" && Value($room."_AutoLight") eq "on")
{
my $cmd = "set ".$room."_LS scene aus";
fhem "defmod atTmp_Bewegungsmelder_Licht_aus_".$room."_%SELF% at +$d $cmd";
}
}
}

====HomeCMDmotion-off====
Befehle die bei Ende der Bewegung eines beliebigen Bewegungsmelders ausgeführt werden sollen 
Auslöser: Ende der Bewegung eines beliebigen Bewegungsmelders

====HomeCMDmotion-on====
Befehle die bei Beginn der Bewegung eines beliebigen Bewegungsmelders ausgeführt werden sollen 
Auslöser: Beginn der Bewegung eines beliebigen Bewegungsmelders

====HomeCMDpresence-<absent/present>====
Befehle die bei Änderung von presence ausgeführt werden sollen 
Auslöser: Änderung presence 
'''Beispiel für "HomeCMDpresence-present":'''
set w_Steckdosen [FILTER=state!=on] on;
set Heizungen [FILTER=controlManu!=off] controlMode auto

====HomeCMDpresence-<absent/present>-device====
Befehle die bei Änderung von presence, ausgelöst durch ein beliebiges Presence Device, ausgeführt werden sollen 
Auslöser: Änderung presence, ausgelöst durch beliebiges Presence Device 
'''Beispiel für "HomeCMDpresence-present-device":'''
{
# mindestens 1x täglich den Batteriewert des PRESENCE Geräts bei erkannter Anwesenheit holen
fhem '"sudo /opt/fhem/scripts/GTag-bat.sh %DEVICE% %ADDRESS% &"'
if ("%DEVICE%" =~ /^PRESENCE_/ && (!defined ReadingsVal("%DEVICE%","battery",undef) || ReadingsAge("%DEVICE%","battery",0) > 64800));
}

====HomeCMDpresence-<absent/present>-resident====
Befehle die bei Änderung von presence, ausgelöst durch einen beliebigen Resident, ausgeführt werden sollen 
Auslöser: Änderung presence, ausgelöst durch beliebigen Resident 
'''Beispiel für "HomeCMDpresence-absent-resident":'''
{
# Mich benachrichtigen wenn ich nicht zu hause bin und jemand anderes die Wohnung verlässt
fhem "msg push \@rr_Dan %ALIAS% hat gerade die Wohnung verlassen!"
if ("%RESIDENT%" ne "rr_Dan" && ReadingsVal("rr_Dan","presence","") ne "present");

# Verabschiedungsnachricht zusammensetzen
my $msg;

# Alle außer mich selbst verabschieden
$msg .= "Bis bald und auf Wiedersehen %ALIAS%..." if ("%RESIDENT%" ne "rr_Dan");

# Glättewarnung wenn nötig
$msg .= " ACHTUNG!!! Es ist %TEMPERATURE%°C kalt! Somit könnte es glatt werden!" if (%ICE%);

# Nachricht senden wenn vorhanden
fhem "msg \@%RESIDENT% $msg" if ($msg);
}
'''Beispielcode für "HomeCMDpresence-present-resident":'''
{
# alle Ankommenden außer mir selbst
if ("%RESIDENT%" ne "rr_Dan")
{
# Benachrichtigung wenn jemand kommt
fhem "msg audio %ALIAS% kommt gerade!" if ("%LOCATION%" ne "arrival");

# Nachricht an Ankommende(n) zusammensetzen
my $g = "gute";
$g .= "n" if ("%DAYTIME%" ne "Nacht);

# Nachricht an Ankommende(n) senden
fhem "msg \@%RESIDENT% Willkommen und $g %DAYTIME% %ALIAS%!";
}
}

====HomeCMDpresence-<absent/present>-<ROOMMATE/GUEST>====
Befehle die bei Änderung von presence, ausgelöst durch einen bestimmten Resident, ausgeführt werden sollen 
Auslöser: Änderung presence, ausgelöst durch bestimmten Resident 

====HomeCMDpresence-<absent/present>-<ROOMMATE/GUEST>-<DEVICE>====
Befehle die bei Änderung von presence, ausgelöst durch ein bestimmtes Presence Device eines bestimmten Resident, ausgeführt werden sollen 
Dieses Attribut ist nur verfügbar wenn ein Resident mehr als ein Presence Device hat 
Auslöser: Änderung presence, ausgelöst durch bestimmtes Presence Device eines bestimmten Resident

====HomeCMDseason====
Befehle die bei Änderung der Jahreszeit ausgeführt werden sollen 
Auslöser: Änderung Jahreszeit 
'''Beispiel'''
{
my $t = "%SEASON%";
$t .= "s" if ($t eq "Frühling");
fhem "msg push Die Wohnung ist nun im $t-Modus!";
fhem "set Heizungen [FILTER=controlMode!=auto] controlMode auto" if ($t ne "Sommer");
}

====HomeCMDseason-<SEASON>====
Befehle die bei Änderung der Jahreszeit in eine bestimmte Jahreszeit ausgeführt werden sollen 
Auslöser: Änderung bestimmte Jahreszeit

====HomeCMDtwilight====
Befehle die bei Änderung der Dämmerung ausgeführt werden sollen 
Auslöser: Änderung Dämmerung

====HomeCMDtwilight-<sr/sr_astro/sr_civil/sr_indoor/sr_weather/ss/ss_astro/ss_civil/ss_indoor/ss_weather>====
Befehle die bei Änderung zu bestimmter Dämmerung ausgeführt werden sollen 
Auslöser: Änderung zu bestimmter Dämmerung

====HomeCMDuwz-warn====
Befehle die bei Beginn/Ende der UWZ Warnungen ausgeführt werden sollen 
Auslöser: Beginn/Ende der UWZ Warnungen

====HomeCMDuwz-warn-begin====
Befehle die bei Beginn der UWZ Warnungen ausgeführt werden sollen 
Auslöser: Beginn der UWZ Warnungen 
'''Beispiel:'''
msg %UWZLONG%

====HomeCMDuwz-warn-end====
Befehle die beim Ende der UWZ Warnungen ausgeführt werden sollen 
Auslöser: Ende der UWZ Warnungen 
'''Beispiel:'''
msg Alle Unwetterwarnungen sind nun beendet!

=Platzhalter=
==verfügbar in allen HomeCMD Attributen==
===%ADDRESS%===
MAC Adresse des zuletzt ausgelösten Presence Geräts

===%ALARM%===
Liste mit Namen der ausgelösten Alarm Geräte 
Wert ist 0 wenn kein Alarm Device ausgelöst ist

===%ALARMCT%===
Anzahl der ausgelösten Alarm Geräte

===%ALARMHR%===
Liste mit (human readable) Namen der ausgelösten Alarm Geräte 
Wert ist 0 wenn kein Alarm Device ausgelöst ist 
kann z.B. für msg benutzt werden

===%ALIAS%===
Alias des zuletzt ausgelösten Resident

===%AMODE%===
aktueller Alarm Mode

===%AEAH%===
Wert von anyoneElseAtHome 
Wert ist 1 wenn on und 0 wenn off

===%ARRIVERS%===
Alias-Liste der ROOMMATE/GUEST deren location auf arrival steht 
kann z.B. dafür benutzt werden um Residents zu begrüßen 
z.B. Peter, Paul und Marry

===%AUDIO%===
Audio Device des zuletzt ausgelösten ROOMMATE/GUEST (Attribut msgContactAudio) 
wenn das Attribut msgContactAudio des jeweiligen Resident keinen Wert hat, so wird versucht den Wert des Attributs aus dem globalMsg (sofern vorhanden) auszulesen 
kann z.B. dafür benutzt werden um Resident spezifische msg(s) vom Typ audio zu senden, z.B. Nacht/Morgen Grüße/Wünsche

===%BATTERYLOW%===
Alias des zu letzt gemeldeten Geräts mit niedrigem Batteriestand

===%BATTERYLOWALL%===
Wert des Reading batteryLow_hr

===%BATTERYLOWCT%===
Wert des Reading batteryLow_ct

===%CONDITION%===
Wert des Reading condition des überwachten weather Device 
kann z.B. für Wetter(vorhersage) benutzt werden

===%CONTACT%===
Wert des Reading lastContact (Name des zuletzt geöffneten Kontakt Sensor) 
kann z.B. dafür benutzt werden um msg zu versenden

===%DAYTIME%===
Wert des Reading daytime 
kann z.B. dafür benutzt werden um Tageszeit spezifische Aktionen zu schalten

===%DEVICE%===
Name des zuletzt ausgelösten Presence Gerät

===%DEVICEA%===
Wert des Reading lastAbsentByPresenceDevice

===%DEVICEP%===
Wert des Reading lastPresentByPresenceDevice

===%DISABLED%===
Wert des Reading devicesDisabled

===%DND%===
DND Status 
1 wenn an, 0 wenn aus

===%DURABSENCE%===
Wert des Reading durTimerAbsence_cr des zu letzt ausgelösten ROOMMATE/GUEST

===%DURABSENCELAST%===
Wert des Reading lastDurAbsence_cr des zu letzt ausgelösten ROOMMATE/GUEST

===%DURPRESENCE%===
Wert des Reading durTimerPresence_cr des zu letzt ausgelösten ROOMMATE/GUEST

===%DURPRESENCELAST%===
Wert des Reading lastDurPresence_cr des zu letzt ausgelösten ROOMMATE/GUEST

===%DURSLEEP%===
Wert des Reading durTimerSleep_cr des zu letzt ausgelösten ROOMMATE/GUEST

===%DURSLEEPLAST%===
Wert des Reading lastDurSleep_cr des zu letzt ausgelösten ROOMMATE/GUEST

===%<CALENDARNAME>%===
Event des benannten Kalenders 
0 wenn kein gerade kein Event ist

===%<CALENDARNAME-EVENTNAME>%===
0 wenn das benannte Event nicht aktiv ist 
1 wenn das benannte Event aktiv ist

===%FORECAST%===
Wettervorhersage für morgen

===%FORECASTTODAY%===
Wettervorhersage für heute

===%HUMIDITY%===
Wert des Reading humidity von HOMEMODE

===%HUMIDITYTREND%===
Wert des Reading humidityTrend von HOMEMODE

===%ICE%===
0 wenn keine Eiswarnung besteht 
1 wenn Eiswarnung besteht

===%IP%===
Wert des Reading publicIP von HOMEMODE

===%LIGHT%===
Wert des Reading light von HOMEMODE

===%LOCATION%===
Wert des Reading location von HOMEMODE

===%LOCATIONR%===
Wert des Reading location des zu letzt ausgelösten ROOMMATE/GUEST

===%LUMINANCE%===
Wert des Reading luminance von HOMEMODE

===%LUMINANCETREND%===
Wert des Reading luminanceTrend von HOMEMODE

===%MODE%===
gerade aktiver Modus von HOMEMODE (Reading mode)

===%MODEALARM%===
aktueller Alarm Mode (wie %AMODE%)

===%MOTION%===
Wert des Reading lastMotion von HOMEMODE

===%NAME%===
Name des HOMEMODE Geräts selbst (identisch zu %SELF%)

===%OPEN%===
Wert des Reading contactsOutsideOpen von HOMEMODE

===%OPENCT%===
Wert des Reading contactsOutsideOpen_ct von HOMEMODE

===%OPENHR%===
Wert des Reading contactsOutsideOpen_hr von HOMEMODE

===%PANIC%===
0 wenn panic ausgeschaltet ist 
1 wenn panic eingeschaltet ist

===%RESIDENT%===
Name des zu letzt ausgelösten ROOMMATE/GUEST

===%PRESENT%===
presence von HOMEMODE
0 wenn absent
1 wenn present

===%PRESENTR%===
presence des zu letzt ausgelösten ROOMMATE/GUEST
0 wenn absent
1 wenn present

===%PRESSURE%===
Wert des Reading pressure von HOMEMODE

===%PREVAMODE%===
vorheriger modeAlarm von HOMEMODE

===%PREVCONTACT%===
vorheriger geöffneter Kontaktsensor

===%PREVMODE%===
vorheriger mode von HOMEMODE

===%PREVMODER%===
vorheriger state des zu letzt ausgelösten ROOMMATE/GUEST

===%PREVMOTION%===
vorheriger geöffneter Bewegungsmelder

===%SEASON%===
Wert des Reading season von HOMEMODE

===%SELF%===
Name des HOMEMODE Geräts selbst (identisch zu %NAME%)

===%SENSORSBATTERY%===
Liste aus Internal SENSORSBATTERY

===%SENSORSCONTACT%===
Liste aus Internal SENSORSCONTACT

===%SENSORSENERGY%===
Liste aus Internal SENSORSENERGY

===%SENSORSMOTION%===
Liste aus Internal SENSORSMOTION

===%SENSORSSMOKE%===
Liste aus Internal SENSORSSMOKE

===%SMOKE%===
Wert des Reading alarmSmoke von HOMEMODE
0 wenn kein Alarm

===%SMOKECT%===
Wert des Reading alarmSmoke_ct von HOMEMODE

===%SMOKEHR%===
Wert des Reading alarmSmoke_hr von HOMEMODE

===%TAMPERED%===
Wert des Reading sensorsTampered von HOMEMODE

===%TAMPEREDCT%===
Wert des Reading sensorsTampered_ct von HOMEMODE

===%TAMPEREDHR%===
Wert des Reading sensorsTampered_hr von HOMEMODE

===%TEMPERATURE%===
Wert des Reading temperature von HOMEMODE

===%TEMPERATURETREND%===
Wert des Reading temperatureTrend von HOMEMODE

===%TOBE%===
are/sind oder is/ist der Wetterkondition

===%TWILIGHT%===
Wert des Reading twilight von HOMEMODE

===%TWILIGHTEVENT%===
aktuelles twilight Event

===%UWZ%===
UWZ Warnlevel

===%UWZLONG%===
alle aktuellen UWZ Warnungen (lange Version)

===%UWZSHORT%===
alle aktuellen UWZ Warnungen (kurze Version)

===%WEATHER%===
Wert von "get <HOMEMODE> weather short"

===%WEATHERLONG%===
Wert von "get <HOMEMODE> weather long"

===%WIND%===
Wert des Reading wind von HOMEMODE

===%WINDCHILL%===
Wert des Reading wind_chill vom eingebundenen Wetter Gerät

==verfügbar in den HomeCMDcontact, HomeCMDmotion und HomeCMDalarm Attributen==
===%ALIAS%===
alias des zuletzt ausgelösten Kontakt/Bewegungs/Rauchsensors

===%SENSOR%===
name des zuletzt ausgelösten Kontakt/Bewegungs/Rauchsensors

===%STATE%===
state des zuletzt ausgelösten Kontakt/Bewegungs/Rauchsensors

==verfügbar in den HomeTextWeatherForecast Attributen==
===%CONDITION%===
Wert des Readings condition des eather Geräts

===%DAY%===
Tag der Wettervorhersage (1 - heute, 2 - morgen)

===%HIGH%===
maximale Temperatur der Wettervorhersage

===%LOW%===
minimale Temperatur der Wettervorhersage

==verfügbar in den HomeCMDevent Attributen==
===%CALENDAR%===
Name der Kalenders

===%DESCRIPTION%===
Beschreibung des aktuellen Event des Kalenders (nicht verfügbar bei holiday Geräten)

===%EVENT%===
Name/Titel des aktuellen Event des Kalenders

===%PREVEVENT%===
Name/Titel des vorherigen Event des Kalenders

==verfügbar in den HomeCMDdevice Attributen==
===%DEVICE%===
name der deaktivierten Geräts

===%ALIAS%===
alias der deaktivierten Geräts

=Benötigte Events=
Folgende Events werden von HOMEMODE ausgewertet bzw. werden benötigt damit HOMEMODE vollumfänglich funktionieren kann.

<table>
<tr>
<td>DEVICE-TYPE</td>
<td>EVENT</td>
</tr>
<tr>
<td>RESIDENTS</td>
<td>state</td>
</tr>
<tr>
<td></td>
<td>presence</td>
</tr>
<tr>
<td>ROOMMATE,GUEST</td>
<td>state</td>
</tr>
<tr>
<td></td>
<td>presence</td>
</tr>
<tr>
<td></td>
<td>wayhome</td>
</tr>
<tr>
<td>{SENSORSCONTACT}</td>
<td>state</td>
</tr>
<tr>
<td></td>
<td>sabotageError</td>
</tr>
<tr>
<td></td>
<td>"HomeReadings"</td>
</tr>
<tr>
<td></td>
<td>"HomeSensorsContactReadings"</td>
</tr>
<tr>
<td>{SENSORSMOTION}</td>
<td>state</td>
</tr>
<tr>
<td></td>
<td>sabotageError</td>
</tr>
<tr>
<td></td>
<td>"HomeReadings"</td>
</tr>
<tr>
<td></td>
<td>"HomeSensorsMotionReadings"</td>
</tr>
<tr>
<td>{SENSORSLUMINANCE}</td>
<td>luminance</td>
</tr>
<tr>
<td></td>
<td>"HomeSensorsLuminanceReading"</td>
</tr>
<tr>
<td>{SENSORSENERGY}</td>
<td>power</td>
</tr>
<tr>
<td></td>
<td>energy</td>
</tr>
<tr>
<td></td>
<td>"HomeSensorsPowerEnergyReadings"</td>
</tr>
<tr>
<td>{SENSORSBATTERY}</td>
<td>battery</td>
</tr>
<tr>
<td></td>
<td>"HomeSensorsBatteryReading"</td>
</tr>
<tr>
<td>"HomePresenceDeviceType"</td>
<td>presence</td>
</tr>
<tr>
<td>"HomeWeatherDevice"</td>
<td>humidity</td>
</tr>
<tr>
<td></td>
<td>temperature</td>
</tr>
<tr>
<td></td>
<td>wind</td>
</tr>
<tr>
<td></td>
<td>pressure</td>
</tr>
<tr>
<td>"HomeTwilightDevice"</td>
<td>light</td>
</tr>
<tr>
<td></td>
<td>twilight</td>
</tr>
<tr>
<td></td>
<td>aktEvent</td>
</tr>
<tr>
<td></td>
<td>pressure</td>
</tr>
<tr>
<td>"HomeSensorTemperatureOutside"</td>
<td>temperature</td>
</tr>
<tr>
<td></td>
<td>humidity</td>
</tr>
<tr>
<td>"HomeSensorHumidityOutside"</td>
<td>humidity</td>
</tr>
<tr>
<td>"HomeSensorWindspeed"</td>
<td>"HomeSensorWindspeed"</td>
</tr>
<tr>
<td>"HomeSensorAirpressure"</td>
<td>"HomeSensorAirpressure"</td>
</tr>
<tr>
<td>"HomeEventsHolidayDevices"</td>
<td>state</td>
</tr>
<tr>
<td>"HomeUWZ"</td>
<td>WarnCount</td>
</tr>
</table>

HOMEMODE

2019-07-16T08:41:00Z

Binford6000:

{{
Infobox Modul
|ModPurpose=Das Modul wurde entworfen um den gesamten Heim-/Hausstatus in einem Gerät abzubilden und viele grundlegende Automationen durch Hinzufügen weiterer Geräte bereitzustellen.
|ModType=h
|ModCmdRef=HOMEMODE
|ModFTopic=64317
|ModForumArea=Automatisierung
|ModTechName=22_HOMEMODE.pm
|ModOwner=DeeSPe
}}
Diese Seite beschreibt die Konfiguration und Verwendung des Moduls ''22_HOMEMODE.pm''.

=Allgemeines=
Das Modul ''22_HOMEMODE.pm'' wurde entworfen um den gesamten Heim-/Hausstatus in einem Gerät abzubilden. 
Die hier aufgeführte Anleitung entspricht dem Modul in Version 1.4.2.

Viele allgemein typische Automationen sind bereits fertig integriert.

Die jeweils per Event auszuführenden Befehle können in den entsprechenden ''HomeCMD...'' Atributen hinterlegt werden und so in der Detail Ansicht des HOMEMODE Geräts übersichtlich angezeigt und bearbeitet werden.

Das Anlegen vieler notify/DOIF ist durch den Einsatz von ''HOMEMODE'' unnötig.

Zusätzlich wurde das Modul für die Verwendung mit HomeKit als GUI optimiert. Alle möglichen Mappings für Homebridge sind bereits enthalten und können über einen set Befehl aktualisiert werden.

[[Datei:HOMEMODE_Device.png|800px]]

==Voraussetzungen==
Um Modul ''22_HOMEMODE.pm'' benutzen zu können benötigt man als Mindestvoraussetzung ein bereits angelegtes RESIDENTS Gerät mit entsprechenden ROOMMATE/GUEST Geräten.

==Mögliche Automationen==
Alle Automationen sind optional.

Hier ein paar Beispiele:
*Änderung des Zustands von ROOMMATE/GUEST Geräten anhand von PRESENCE Geräten
*Bereitstellung von CMD Attributen für mögliche Events rund um den Heim-/Hausstatus
*Bereitstellung von Platzhaltern innerhalb der CMD Attribute, z.B. %MODE%, %SEASON% oder %PREVMODE% für die Werte der Readings mode, season und prevMode
*Einbindung von Kontakt Sensoren, für z.B. Offen-Warnungen nach bestimmten Zeitraum oder Alarm Meldungen in bestimmten Alarm Modus - kann pro Kontakt Sensor konfiguriert werden
*Einbindung von Bewegungs Sensoren, für z.B. automatische Licht Schaltungen oder Alarm Meldungen in bestimmten Alarm Modus - kann pro Bewegungs Sensor konfiguriert werden
*Darstellungen und Auslösen von Sabotage Alarmen der eingebundenen Kontakt- und Bewegungssensoren
*Einbindung von jeweils einem Temperatur und Luftfeuchtigkeitssensor
*Einbindung eines lokalen Wetter Devices zur Ermittlung und Ausgabe der lokalen Wetterdaten und Erzeugung der Wettervorhersage
*Einbindung von Power und Energy Sensoren zur Ermittlung der Gesamtmengen
*Einbindung von Calendar/holiday Devices für spezielle im HOMEMODE Device verfügbar zu machende Events
*von Uhrzeit abhängiger Anwesend-Modus
*Bewohner unabhängige Tageszeit-Modus
*Alarm-Modus
*DND-Modus
*Überwachung von Batteriewerten

=HOMEMODE-Gerät=
==Definition==
Das HOMEMODE Gerät - hier mit dem Namen ''Home'' versehen - selbst wird über
define Home HOMEMODE
bei Vorhandensein nur eines RESIDENTS Geräts definiert.

Bei Verwendung mehrerer RESIDENTS Geräte muss das Master RESIDENTS Gerät beim Definieren mit angegeben werden
define Home HOMEMODE rgr_Residents
Dieses Modul verwendet das globale Attribut ''language'' zur Bestimmung der Anzeigedaten (Standard: EN=english). Für deutsche Ausgabedaten kann das Attribut
attr global language DE
gesetzt werden. 
Alternativ kann auch nur das HOMEMODE Gerät auf deutsch geändert werden
attr Home HomeLanguage DE

==Set-Befehle==
''set <required> [optional]''

set Home anyoneElseAtHome <on/off>
einschalten wenn jemand anderes zu Hause ist der kein registrierter ROOMMATE/GUEST ist, z.B. Hund/Katze oder unregistrierte Gäste 
wenn eingeschaltet, dann wird der Alarm Mode beim Verlassen statt auf armaway nur auf armhome gestellt 
schaltet man ein und hat schon Haus/Wohnung verlassen, so wird der Alarm Mode von armaway auf armhome gestellt 
Platzhalter '''%AEAH%''' ist in allen HomeCMD Attributen verfügbar

set Home dnd <on/off>
schaltet den "Bitte nicht stören" Modus ein 
z.B. um Benachrichtigungen zu deaktivieren 
Platzhalter '''%DND%''' ist in allen HomeCMD Attributen verfügbar

set Home dnd-for-minutes <MINUTES>
schaltet den "Bitte nicht stören" Modus für die angegebenen Minuten ein 
kehrt danach zum vorherigen (tageszeitabhängigen) Modus zurück

set Home deviceDisable <DEVICE>
deaktiviert das Gerät für sämtliche HOMEMODE Automationen 
Platzhalter '''%DISABLED%''' ist in allen HomeCMD Attributen verfügbar 
Platzhalter '''%DEVICE%''' und '''%ALIAS%''' sind in allen HomeCMD Attributen verfügbar

set Home deviceEnable <DEVICE>
reaktiviert das Gerät für sämtliche HOMEMODE Automationen 
Platzhalter '''%DISABLED%''' ist in allen HomeCMD Attributen verfügbar 
Platzhalter '''%DEVICE%''' und '''%ALIAS%''' sind in allen HomeCMD Attributen verfügbar

set Home location <arrival/home/bed/underway/wayhome>
manueller Ortswechsel 
Platzhalter '''%LOCATION%''' ist in allen HomeCMD Attributen verfügbar

set Home mode <morning/day/afternoon/evening/night/gotosleep/asleep/absent/gone/home>
manueller Moduswechsel 
Platzhalter '''%MODE%''' und '''%PREVMODE%''' sind in allen HomeCMD Attributen verfügbar

set Home modeAlarm <armaway/armhome/armnight/disarm>
schaltet den angegebenen Alarm Modus ein 
Platzhalter '''%AMODE%''' und '''%PREVAMODE%''' sind in allen HomeCMD Attributen verfügbar

set Home modeAlarm-for-minutes <armaway/armhome/armnight/disarm> <MINUTES>
schaltet den angegebenen Alarm Modus für die angegebenen Minuten ein
kehrt danach zum vorherigen Alarm Modus zurück

set Home updateHomebridgeMapping
aktualisiert das Attribut homebridgeMapping des HOMEMODDE Device abhängig von den verfügbaren Informationen

set Home updateInternalForce
führt eine Aktualisierung der Internals des HOMEMODE Device aus 
das sollte manuell benutzt werden nachdem das Modul aktualisiert und nur ein reload statt restart gemacht wurde 
auch wenn man überwachte/kontrollierte Geräte ändert sollte man diesen Befehl manuell ausführen, z.B. neue ROOMMATE/GUEST im RESIDENTS Device hinzufügt, oder Geräte in FHEM hinzufügt die dem selben Devspec wie bisher entsprechen (Steckdosen, Sensoren)

==Get-Befehle==
''get <required> [optional]''

get Home contactsOpen <all/doorsinside/doorsoutside/doorsmain/outside/windows>
Liste von all/doorsinside/doorsoutside/doorsmain/outside/windows offenen Kontakten 
Platzhalter '''%OPEN%''', '''%OPENCT%''' und '''%OPENHR%''' sind in allen HomeCMD Attributen verfügbar

get Home devicesDisabled
Anzeige der für HOMEMODE deaktivierten Geräte 
Platzhalter '''%DISABLED%''' ist in allen HomeCMD Attributen verfügbar

get Home mode
Anzeige von mode 
Platzhalter '''%MODE%''' ist in allen HomeCMD Attributen verfügbar

get Home modeAlarm
Anzeige von modeAlarm 
Platzhalter '''%AMODE%''' und '''%MODEALARM%''' sind in allen HomeCMD Attributen verfügbar

get Home publicIP
holen der öffentlichen IP Adresse 
Platzhalter '''%IP%''' ist in allen HomeCMD Attributen verfügbar

get Home sensorsTampered
Liste aller sabotierten Sensoren 
Platzhalter '''%TAMPERED%''', '''%TAMPEREDCT%''' und '''%TAMPEREDHR%''' sind in allen HomeCMD Attributen verfügbar

get Home weather <long/short>
Wetterinfo im angegebenen Format anzeigen 
Platzhalter '''%WEATHER%''' und '''%WEATHERLONG%''' sind in allen HomeCMD Attributen verfügbar

get Home weatherForecast [TAG]
Wettervorhersage für angegebenen Tag 
wenn kein Tag angegeben wird, so wird die Vorhersage für morgen (2) ausgegeben 
Platzhalter '''%FORECAST%''' (morgen) und '''%FORECASTTODAY%''' (heute) sind in allen HomeCMD Attributen verfügbar

==webCmd==
Die Schaltmöglichkeiten sind absichtlich gering gehalten, denn im normalen Betrieb sollte nicht mehr benötigt werden als die hier gebotenen. 
Es lässt sich der Alarm Mode manuell umschalten und beim Klick auf das devStateIcon wird der DND Mode an- und ausgeschaltet.

=Konfiguration=

==Grundkonfiguration==

Diese Grundkonfiguration sollte immer als erstes erfolgen um entsprechend darauf weiter aufzubauen. Als zweiter Schritt ist dann die erweiterte Konfiguration angedacht.

Bei der Namensvergabe der Attribute vom HOMEMODE Device wurde nach einem möglichst kurzem Prefix gesucht und nach vielen Tests wurde sich für das Prefix "Home" entschieden. Das hat den Vorteil, dass alle Attribute beisammen stehen und diese auch (durch den Großbuchstaben am Anfang) ziemlich weit oben in der Liste der Attribute stehen. Ebenso wurde bei der Namensvergabe versucht, selbsterklärende Namen zu wählen. Das hat den Vorteil, dass man relativ einfach genau erkennen kann wofür das Attribut steht, allerdings auch den Nachteil, dass einige Attributnamen ganz schön lang werden.

===Attribute===

====HomeAdvancedUserAttr====
Als Erstes wird empfohlen, gerade für Anfänger, das Attribut "HomeAdvancedUserAttr" auf 1 zu setzen. Dadurch werden viel mehr HomeCMD Attribute freigeschaltet. Diese werden im Attribut userattr des HOMEMODE Device hinzugefügt. 
Standardwert: 0

====HomeAutoAlarmModes====
Als Nächstes sollte man sich entscheiden, ob die Alarm Modus evtl. nicht automatisch zum jeweiligen Modus des HOMEMODE Device geschaltet werden sollen. Standardmäßig werden die Alarm Modus automatisch gesteuert. Ist das nicht erwünscht, so ist der Wert dieses Attributs auf 0 zu setzen. 
Bei Modus "absent" des HOMEMODE Device wird automatisch auf "armaway" geschaltet. 
Bei Modus "home" des HOMEMODE Device wird automatisch auf "disarm" geschaltet. 
Bei Modus "asleep" des HOMEMODE Device wird automatisch auf "armnight" geschaltet. 
Alarm Modus "armhome" kann nur manuell gesetzt werden. 
Werte: 0 oder 1 
Standardwert: 1

====HomeAutoArrival====
Ist hier ein Wert größer 0 angegeben, so wird bei Ankunft jedes ROOMMATE/GUEST die location des jeweiligen ROOMMATE/GUEST für die hier angegeben Zeit in Minuten auf "arrival" gesetzt. Beim ersten nach Hause kommenden ROOMMATE/GUEST wird zusätzlich die location des HOMEMODE Device für die hier eingestellte Zeit in Minuten auf "arrival" gesetzt. 
Nach Ablauf der hier eingestellten Minuten wechselt das jeweilige Device von "arrival" auf "home", sofern es noch die location "arrival" hat. 
Werte: 0 bis 5999.9 
Standardwert: 0

====HomeAutoAsleep====
Ist hier ein Wert größer 0 angegeben, so wird beim Schlafengehen (gotosleep) jedes ROOMMATE/GUEST ein Timer gestartet, der den jeweiligen ROOMMATE/GUEST nach der hier angegeben Zeit in Minuten auf "asleep" setzt. 
Werte: 0 bis 5999.9 
Standardwert: 0

====HomeAutoAwoken====
Ist hier ein Wert größer 0 angegeben, so wird beim Erwachen ("awoken" oder "home nach asleep") jedes ROOMMATE/GUEST dieser auf "awoken" gesetzt und ein Timer gestartet, der den jeweiligen ROOMMATE/GUEST nach der hier angegeben Zeit in Minuten auf "home" setzt. 
Werte: 0 bis 5999.9 
Standardwert: 0

====HomeAutoDaytime====
Standardmäßig wird mode anhand der Tageszeit automatisch gesetzt. Ist das nicht gewünscht, kann das über den Wert 0 deaktiviert werden. Dann stehen allerdings tageszeitabhängigen mode(s) nicht mehr zur Verfügung. 
Werte: 0 oder 1 
Standardwert: 1

====HomeResidentCmdDelay====
Normalerweise werden die Events der ROOMMATE/GUEST vor denen des HOMEMODE Device ausgeführt. Um das zu ändern wird die Ausführung der ROOMMATE/GUEST HomeCMD Attribute um die hier eingestellte Zeit in Sekunden verzögert. 
Je genauer der Name des jeweiligen HomeCMD Attributs beschrieben wird, desto später wird dieser ausgeführt. 
Das heißt z.B. dass HomeCMDmode vor HomeCMDmode-absent und dieser wiederrum vor HomeCMDmode-absent-ROOMMATE/GUEST-NAME ausgeführt wird usw. 
Um das normale Verhalten wiederherzustellen ist der Wert dieses Attributs auf 0 zu setzen. Dann wird HomeCMDmode-absent-ROOMMATE/GUEST-NAME vor HomeCMDmode-absent und vor HomeCMDmode ausgeführt. 
Werte: 0 bis unendlich in Sekunden 
Standardwert: 1

==Konfiguration Presence Devices (automatische anwesend/abwesend Umschaltung von ROOMMATE/GUEST)==
Damit die automatische Zuordnung der Presence Devices zu ihren ROOMMATE/GUEST Devices zuverlässig funktioniert, ist es nötig dass der Hauptteil des Namens des ROOMMATE/GUEST innerhalb des Namens des zugehörigen PRESENCE Device(s) vorkommt. 
Im Attribut HomePresenceDeviceType kann man den zu suchenden TYPE von Presence Device vorgeben. 
Per Default werden nur Devices vom TYPE PRESENCE gesucht und versucht den ROOMMATE/GUEST zuzuweisen. 
Falls man z.B. auch Devices vom TYPE dummy zur Anwesenheitssteuerung benutzt, kann man diese im Attribut HomePresenceDeviceType mit hinzunehmen. Es sind alles Device TYPEn möglich die ein "presence" Reading mit den Werten "present/appeared" und "absent/disappeared" bereitstellen. Mehrere TYPEn sind möglich da in diesem Attribut ein Regex erwartet wird. z.B.: dummy oder PRESENCE|dummy oder PRESENCE|dummy|ONKYO_AVR.

===Beispiel===
Der Device Name meines ROOMMATE ist "rr_Dan". 
Auf der Suche nach dem zugehörigen Presence Device wird der erste Teil (rr_ oder rg_) weggeschnitten und der Rest in Kleinbuchstaben umgewandelt. 
Mit dem was übrig bleibt, bei mir also nur dan, werden die möglichen Presence Devices versucht zu erkennen. 
Mein zugehöriges Presence Device heißt, historisch gewachsen, PRESENCE_rr_Dan und würde somit problemlos zugeordnet werden können. 
Die Namen der zugehörigen Presence Devives könnten in ihrer kürzesten Form auch wie folgt sein um meinen ROOMMATE/GUEST Device zugeordnet zu werden: 
pdan
danp
ZDan
DANZ
wenndannsonst
Aber Achtung, es funktioniert nicht mehr wenn die Namen nicht eindeutig sind. Wenn es z.B. eine rr_Dana geben würde mit Presence Device Name "pdani", dann würde dieser Name auch bei mir (dan) passen. Das könnte man aber auch bewußt nutzen um mit einem Presence Device 2 ROOMMATE/GUEST Devices gleichzeitig zu steuern. 
Wenn die Namen wirklich absolut eindeutig sind, dann könnte man den Regex im Attribut HomePresenceDeviceType sogar auf ".*" setzen.

Werden pro ROOMMATE/GUEST mehrere Presence Devices gefunden und zugeordnet, so wird automatisch dass Attribut HomePresenceDeviceAbsentCount-<NAME-ROOMMATE/GUEST> auf die Anzahl der gefundenen Presence Devices gesetzt, so dass der/die jeweilige ROOMMATE/GUEST immer erst als abwesend gewertet wird sobald alle zugehörigen Presence Devices abwesend sind. Analog dazu gibt es noch das Attribut HomePresenceDevicePresentCount-<NAME-ROOMMATE/GUEST>.

===Attribute===

====HomeAutoPresence====
Ist dieses Attribut auf 1 gesetzt, so werden die ROOMMATE/GUEST Devices automatisch zum Status ihrer zugehörigen PRESENCE Devices geschaltet. 
PRESENCE Device present - ROOMMATE/GUEST home 
PRESENCE Device absent - ROOMMATE/GUEST absent 
Falls es sich bei den von Euch benutzen PRESENCE Devices nicht um Devices vom TYPE PRESENCE handeln sollte, sondern z.B. um PRESENCE und dummy, so kann dieses im Attribut HomePresenceDeviceType als Regex konfiguriert werden! z.B.: PRESENCE|dummy 
Damit ein Device als Presence Device erkannt werden kann, muss dieses über ein presence Reading verfügen. 
Werte: 0 oder 1 
Standardwert: 0

====HomeAutoPresenceSuppressState====
unterdrücke Anwesenheitsänderung in angegebenen State(s) der RESIDENTS 
z.B. für "mysteriös" verschwindende Anwesenheitsgeräte in der Nacht 
Werte: asleep|awoken|gotosleep 
Standardwert:

====HomePresenceDeviceType====
Regex des TYPEs/der TYPEn von Presence Devices 
Werte: Regex der Device TYPEn 
Standardwert: PRESENCE

==Erweiterte Konfiguration==
Um das HOMEMODE Device vollumfänglich zu benutzen ist es sinnvoll weitere Devices (zur Überwachung) hinzuzufügen.

Die bereits möglichen hinzuzufügenden Devices werden hier folgend nach Attributnamen erklärt.

===Attribute zum Hinzufügen weiterer Geräte===

====HomeEventsCalendarDevices====
Hier ist ein Devspec von holiday/Calendar Device(s) anzugeben. 
''Es wird empfohlen die holiday/Calendar Namen in Großbuchstaben anzulegen, da dann die daraus resultierenden Platzhalter ebenfalls Großbuchstaben sind und somit zu den anderen Platzhaltern passen.'' 
Es werden alle Typen von holiday Events (1,2,3,4,5) unterstützt. 
Bei Calendar sind auch gleichzeitig startende/laufende Events möglich, sie müssen nur unterschiedliche Titel haben (summary). 
Der jeweilige Event Text kann auch Leerzeichen enthalten, welche in den HomeCMD Attributen durch Bindestriche (-) ersetzt werden. 
Diese Devices stellen zusätzlich die Platzhalter '''%CALENDAR%''', '''%EVENT%''' und '''%PREVEVENT%''' in den HomeCMDevent Attributen zur Verfügung. '''%CALENDAR%''' wird dann durch den Namen, '''%EVENT%''' durch das aktuelle Event und '''%PREVEVENT%''' durch das vorherige Event des jeweiligen Kalenders ersetzt. 
Werte: frei wählbar 
Werteformat: Devspec von holiday/Calendar Geräten 
Standardwert:

====HomeEventsHolidayDevices====
Hier ist ein Devspec von holiday/Calendar Device(s) anzugeben. 
''Es wird empfohlen die holiday/Calendar Namen in Großbuchstaben anzulegen, da dann die daraus resultierenden Platzhalter ebenfalls Großbuchstaben sind und somit zu den anderen Platzhaltern passen.'' 
Es werden alle Typen von holiday Events (1,2,3,4,5) unterstützt. 
Bei Calendar sind auch gleichzeitig startende/laufende Events möglich, sie müssen nur unterschiedliche Titel haben (summary). 
Der jeweilige Event Text kann auch Leerzeichen enthalten, welche in den HomeCMD Attributen durch Bindestriche (-) ersetzt werden. 
Diese Devices stellen zusätzlich die Platzhalter '''%CALENDAR%''', '''%EVENT%''' und '''%PREVEVENT%''' in den HomeCMDevent Attributen zur Verfügung. '''%CALENDAR%''' wird dann durch den Namen, '''%EVENT%''' durch das aktuelle Event und '''%PREVEVENT%''' durch das vorherige Event des jeweiligen Kalenders ersetzt. 
Werte: frei wählbar 
Werteformat: Devspec von holiday/Calendar Geräten 
Standardwert:

====HomeSensorAirpressure====
Luftdrucksensor aussen 
Werte: frei wählbar 
Werteformat: Name des Sensors 
Standardwert:

====HomeSensorHumidityOutside====
Hier ist der Name des (Haupt)Aussensensors für Luftfeuchtigkeit anzugeben. Dieser muss ein Reading humidity besitzen. 
Falls der Sensor für (Aussen)Luftfeuchtigkeit und Aussentemperatur ein und der selbe ist, so muss dieser nur einmalig im Attribut HomeSensorTemperatureOutside hinterlegt werden. Dieser muss dann die beiden Readings humidity und temperature haben. Im Bedarfsfall können diese Readings auch vorher entsprechend durch eigene userReadings erstellt werden. 
Dieser Sensor stellt den Platzhalter '''%HUMIDITY%''' für den Wert des Readings humidity zur Verfügung. 
Werte: frei wählbar 
Werteformat: Device Name mit Reading humidity 
Standardwert:

====HomeSensorTemperatureOutside====
Hier ist der Name des (Haupt)Aussentemperatursensors anzugeben. Dieser muss mindestens ein Reading temperature besitzen. 
Falls der Sensor für Aussentemperatur auch ein Reading humidity besitzen sollte und dieses auch der Sensor für die Aussenlufteuchtigkeit ist, so muss dieser nur einmalig hier in diesem Attribut hinterlegt werden. 
Dieser Sensor stellt den Platzhalter '''%TEMPERATURE%''' für den Wert des Readings temperature zur Verfügung. 
Werte: frei wählbar 
Werteformat: Device Name mit Reading temperature und optional humidity 
Standardwert:

====HomeSensorsContact====
Hier können alle Kontakt Sensoren als Devspec hinterlegt werden. 
Diese Devices stellen zusätzlich die Platzhalter '''%ALIAS%''', '''%SENSOR%''' und '''%STATE%''' in den HomeCMDcontact Attributen zur Verfügung. '''%ALIAS%''' wird dann durch den Alias, '''%SENSOR%''' durch den Namen und '''%STATE%''' durch den aktuellen state des zuletzt ausgelösten Kontakts ersetzt. 
Werte: frei wählbar 
Werteformat: Devspec 
Standardwert: 
''In meinem Falle sind das optische und magnetische Kontaktsensoren vom HomeMatic. HM-SEC-SCO und HM-SEC-SC-2.'' 
''Darum ist bei mir als Devspec '''model=HM-SEC-SC(O|-2)''' eingetragen um alle diese Kontaktsensoren zu erfassen.'' 
Nach Übernehmen des Attributs werden alle gefundenen Kontaktsensoren mit ihren Namen im Internal SENSORSCONTACT des HOMEMODE Device einzeln aufgelistet und können dort auch direkt angeklickt werden. 
Des weiteren werden beim Übernehmen dieses Attributs jedem Kontaktsensor folgende Attribute im Attribut userattr hinzugefügt: 

=====HomeContactType=====
Typ des Kontakts - wird versucht anhand des Namen/Alias beim Hinzufügen zum HOMEMODE Device zu ermitteln, sollte jedoch für jeden Kontaktsensor einzeln überprüft werden 
Werte: doorinside,dooroutside,doormain,window 
Werteformat: vorgegebene Werteauswahl 
Standardwert: window

=====HomeModeAlarmActive=====
Regex der Alarm Mode(s) in denen der Kontaktsensor eine erfolgte Öffnung als Alarm melden soll. 
Werte: armaway|armhome|armnight 
Werteformat: Regex von Alarm Modes 
Standardwert: armaway

=====HomeOpenDontTriggerModes=====
Regex der Mode(s) des HOMEMODE Device in denen keine Offen Warnungen erfolgen sollen. 
Ist ein Kontakt geöffnet während die hier eingestellten Mode(s) eintreten, so wird der noch bestehende Timer abgebrochen. Entgegengesetzt startet er wieder sobal die hier eingestellten Mode(s) verlassen werden. 
Ist hier z.B. "gotosleep|asleep" eingestellt, so kann man z.B. das Fenster schon vor dem Auslösen von gotosleep oder asleep öffnen und der bestehende Offenwarnung-Timer wird dann abgebrochen. Sobald man am Morgen z.B. awoken oder home auslöst, so wird ein neuer Timer gestartet der einen dann an das noch offene Fenster erinnert. 
Werte: alle Modes des HOMEMODE Device 
Werteformat: Regex von Modes 
Standardwert:

=====HomeOpenDontTriggerModesResidents=====
Devspec der ROOMMATE/GUEST Devices deren Status statt der Modes des HOMEMODE Device für Attribut HomeOpenDontTriggerModes benutzt werden soll. 
Werte: alle überwachten ROOMMATE/GUEST 
Werteformat: Devspec 
Standardwert:

=====HomeOpenMaxTrigger=====
Maximale Anzahl an Warnmeldungen 
Werte: 0 bis ~ 
Werteformat: ganze Zahl 
Standardwert:

=====HomeOpenTimes=====
Leerzeichenseparierte Liste von Offen Warnung Zeiten in Minuten. 
Der erste Wert entspricht der ersten Zeit, der zweite Wert der zweiten Zeit usw. 
Die Anzahl sollte dem Wert im Attribut HomeOpenMaxTrigger entsprechen. Wenn hier weniger Zeiten vorgegeben werden, so wird für weitere Offen Warnungen immer die letzte hier angegebene Zeit verwendet. 
Werte: frei wählbar 
Werteformat: leerzeichenseparierte Liste von Zahlen mit einer Kommmastelle, z.B. 2.5 
Standardwert: 10

=====HomeOpenTimesDividers=====
Leerzeichenseparierte Liste von Offenwarnzeit Teilern. 
Es müssen so viele Werte angegeben werden wie in HomeSeasons Jahreszeiten hinterlegt worden sind (Default 4). 
Bei einer normalen Offenwarnzeit von 10 Minuten und den hier anzugebenen Teilern z.B. "2 1 2 3" ergeben sich für Frühling und Herbst Offenwarnzeiten von jeweils 5 Minuten und im Winter 3.3 Minuten. 
Die hier eingetragenen Werte überschreiben die Werte aus dem Attribut HomeSensorsContactOpenTimeDividers des HOMEMODE Device. 
Werte: frei wählbar 
Werteformat: leerzeichenseparierte Liste von Zahlen mit einer Kommmastelle, z.B. 2 1 2 2.5 
Standardwert:

=====HomeReadings=====
Zwei leerzeichenseparierte Readings für open und sabotage Status. 
Die hier eingetragenen Readings überschreiben die Werte aus dem Attribut HomeSensorsContactReadings des HOMEMODE Device. 
Werte: frei wählbar 
Werteformat: zwei Wörter 
Standardwert: state sabotageError

=====HomeValues=====
Regex der Werte die für offen und sabotiert stehen. 
Die hier eingetragenen Werte überschreiben die Werte aus dem Attribut HomeSensorsContactValues des HOMEMODE Device. 
Werte: frei wählbar 
Werteformat: Regex 
Standardwert: open|tilted|on

====HomeSensorsContactReadings====
Zwei leerzeichenseparierte Readings für open und sabotage Status. 
Die hier eingetragenen Readings sind global für alle Kontaktsensoren, können aber durch setzen des Attributs HomeReadings in jedem Sensor überschrieben werden. 
Werte: frei wählbar 
Werteformat: zwei Wörter 
Standardwert: state sabotageError

====HomeSensorsContactValues====
Regex der Werte die für offen und sabotiert stehen. 
Die hier eingetragenen Werte sind global für alle Kontaktsensoren, können aber durch setzen des Attributs HomeValues in jedem Sensor überschrieben werden. 
Werte: frei wählbar 
Werteformat: Regex 
Standardwert: open|tilted|on

====HomeSensorsContactOpenTimeDividers====
Leerzeichenseparierte Liste von Offenwarnzeit Teilern. 
Es müssen so viele Werte angegeben werden wie in HomeSeasons Jahreszeiten hinterlegt worden sind (Default 4). 
Bei einer normalen Offenwarnzeit von 10 Minuten und den hier anzugebenen Teilern z.B. "2 1 2 3" ergeben sich für Frühling und Herbst Offenwarnzeiten von jeweils 5 Minuten und im Winter 3.3 Minuten. 
Die hier eingetragenen Werte sind global für alle Kontaktsensoren, können aber durch setzen des Attributs HomeOpenTimesDividers in jedem Sensor überschrieben werden. 
Werte: frei wählbar 
Werteformat: leerzeichenseparierte Liste von Zahlen mit max. einer Kommmastelle, z.B. 2 1 2 2.5 (für 4 Jahreszeiten) 
Standardwert:

====HomeSensorsContactOpenTimeMin====
Minimale Zeit in Minuten die mindestens für eine Offenwarnung gewartet werden soll - im Falle dass sich durch den Teiler evtl. zu kleine Werte ergeben. 
Werte: frei wählbar 
Werteformat: eine Zahle mit max. einer Kommmastelle, z.B. 2.5 
Standardwert:

====HomeSensorsContactOpenTimes====
Leerzeichenseparierte Liste von Offen Warnung Zeiten in Minuten. 
Der erste Wert entspricht der ersten Zeit, der zweite Wert der zweiten Zeit usw. 
Die Anzahl sollte dem Wert im Attribut HomeOpenMaxTrigger entsprechen. Wenn hier weniger Zeiten vorgegeben werden, so wird für weitere Offen Warnungen immer die letzte hier angegebene Zeit verwendet. 
Werte: frei wählbar 
Werteformat: leerzeichenseparierte Liste von Zahlen mit max. einer Kommmastelle, z.B. 7.5 
Standardwert: 10

====HomeSensorsLuminance====
Devspec von (Innen-)Lichtsensoren deren Durchschnittswert berechnet werden soll 
Werte: frei wählbar 
Werteformat: Devspec 
Standardwert:

====HomeSensorsMotion====
Hier können alle Bewegungs Sensoren als Devspec hinterlegt werden. 
Diese Devices stellen zusätzlich die Platzhalter '''%ALIAS%''', '''%SENSOR%''' und '''%STATE%''' in den HomeCMDmotion Attributen zur Verfügung. '''%ALIAS%''' wird dann durch den Alias, '''%SENSOR%''' durch den Namen und '''%STATE%''' durch den aktuellen state des zuletzt ausgelösten Kontakts ersetzt. 
Werte: frei wählbar 
Werteformat: Devspec 
Standardwert:

''In meinem Falle sind das Fibaro Motion Sensor Gen4/5.'' 
''Darum ist bei mir als Devspec '''modelId=010f-0801-1001|010f-0800-1001''' eingetragen um alle diese Bewegungssensoren zu erfassen.'' 
''Damit bei den Gen5 Sensoren auch das open im reading state steht, habe ich mir bei diesen Sensoren ein userReading angelegt.'' 
Nach Übernehmen des Attributs werden alle gefundenen Bewegungssensoren mit ihren Namen im Internal SENSORSMOTION des HOMEMODE Device einzeln aufgelistet und können dort auch direkt angeklickt werden. 
Des weiteren werden beim Übernehmen dieses Attributs jedem Bewegungssensor folgende Attribute im Attribut userattr hinzugefügt:

=====HomeModeAlarmActive=====
Regex der Alarm Mode(s) in denen der Bewegungssensor eine erfolgte Öffnung als Alarm melden soll. 
Werte: armaway|armhome|armnight 
Werteformat: Regex von Alarm Modes 
Standardwert: armaway

=====HomeReadings=====
2 leerzeichenseparierte Readings für open und sabotage. 
Die hier eingetragenen Readings überschreiben die Werte aus dem Attribut HomeSensorsMotionReadings des HOMEMODE Device. 
Werte: frei wählbar 
Werteformat: zwei Wörter 
Standardwert: state sabotageError

=====HomeSensorLocation=====
Standort des Bewegungssensors (außen oder innen) - wird standardmäßig beim Hinzufügen zum HOMEMODE Device auf "inside" gesetzt, sollte jedoch für jeden Kontaktsensor einzeln überprüft werden 
Werte: inside,outside 
Werteformat: vorgegebene Werteauswahl 
Standardwert: inside

=====HomeValues=====
Regex der Werte die für offen und sabotiert stehen. 
Die hier eingetragenen Werte überschreiben die Werte aus dem Attribut HomeSensorsMotionValues des HOMEMODE Device. 
Werte: frei wählbar 
Werteformat: Regex 
Standardwert: open|on

====HomeSensorsMotionReadings====
2 leerzeichenseparierte Readings für open und sabotage. 
Die hier eingetragenen Readings sind global für alle Kontaktsensoren, können aber durch setzen des Attributs HomeReadings in jedem Sensor überschrieben werden. 
Werte: frei wählbar 
Werteformat: zwei Wörter 
Standardwert: state sabotageError

====HomeSensorsMotionValues====
Regex der Werte die für offen und sabotiert stehen. 
Die hier eingetragenen Werte sind global für alle Kontaktsensoren, können aber durch setzen des Attributs HomeValues in jedem Sensor überschrieben werden. 
Werte: frei wählbar 
Werteformat: Regex 
Standardwert: open|on

====HomeSensorsPowerEnergy====
Hier können alle Energie Sensoren als Devspec hinterlegt werden. Diese müssen die beiden Readings power und energy besitzen. 
Anhand dieser Readings wird dann der Gesamtverbrauch und die derzeitige gesamte Leistungsaufnahme berechnet. 
''In meinem Falle sind das Fibaro Wall Plugs Gen4/5.'' 
''Darum ist bei mir als Devspec '''modelId=010f-0600-1000|010f-0602-1001''' eingetragen um alle diese Energie Sensoren zu erfassen.'' 
Werte: frei wählbar 
Werteformat: Devspec mit vorhandenen energy und power Readings 
Standardwert:

====HomeSensorsSmoke====
Devspec mit Rauchmeldern 
Werte: frei wählbar 
Werteformat: Devspec 
Standardwert:

====HomeSensorWindspeed====
Sensor für Windgeschwindigkeit 
Werte: frei wählbar 
Werteformat: Name des Sensors und Reading der Windgeschwindigkeit separiert mit : (z.B. ga_Windsensor:wind) 
Standardwert:

====HomeSensorsBattery====
Devspec von Batteriesensoren mit einem Reading "battery" 
Werte: frei wählbar 
Werteformat: Devspec 
Standardwert:

====HomeTriggerAnyoneElseAtHome====
auslösendes Gerät für anyoneElseAtHome 
Werte: frei wählbar 
Werteformat: device:reading:valueOn:valueOff 
Standardwert:

====HomeTriggerPanic====
auslösendes Gerät für Panikalarm 
valueOff ist optional, wird es weggelassen, so fungiert valueOn als toggle 
Werte: frei wählbar 
Werteformat: device:reading:valueOn[:valueOff] 
Standardwert:

====HomeTwilightDevice====
Hier ist der Name des lokalen Twilight Device anzugeben. 
Diese Device stellt zusätzlich die Platzhalter '''%LIGHT%''', '''%TWILIGHT%''' und '''%TWILIGHTEVENT%''' in den HomeCMD Attributen zur Verfügung. '''%LIGHT%''' wird dann durch das Reading light, '''%TWILIGHT%''' durch das Reading twilight und '''%TWILIGHTEVENT%''' durch das aktuelle Twilight Event ersetzt. 
Werte: frei wählbar 
Werteformat: Devspec 
Standardwert:

====HomeUWZ====
Hier ist der Name des lokalen UWZ Geräts anzugeben. 
Platzhalter '''%UWZ%''', '''%UWZSHORT%''' und '''%UWZLONG%''' sind verfügbar in allen HomeCMD Attributen 
Werte: frei wählbar 
Werteformat: Name des UWZ Geräts 
Standardwert:

====HomeWeatherDevice====
Hier ist der Name des lokalen Weather Geräts anzugeben. 
Diese Device stellt zusätzlich einige Platzhalter zur Verfügung. Für die genaue Beschreibung derer siehe "Platzhalter". 
Werte: frei wählbar 
Werteformat: Devspec 
Standardwert:

===HomeText Attribute===
Die HomeText Attribute sind größtenteils zur Übersetzung einiger benötigter Begriffe gedacht. 
In den speziellen Attributen die mit HomeTextWeather anfangen, sind ganze Texte mit entsprechenden Platzhaltern einzufügen.

====HomeTextAndAreIs====
Übersetzung für "and", "are" und "is" 
Werte: frei wählbar separiert mit | 
Werteformat: Wort/Wörter 
Standardwert: and|are|is 
'''Beispiel:'''
und|sind|ist

====HomeTextClosedOpen====
Übersetzung für "closed" und "open" 
Werte: frei wählbar separiert mit | 
Werteformat: Wort 
Standardwert: closed|open 
'''Beispiel:'''
geschlossen|geöffnet

====HomeTextNosmokeSmoke====
Übersetzung für "no smoke" und "smoke" 
Werte: frei wählbar separiert mit | 
Werteformat: Wort 
Standardwert: no smoke|smoke 
'''Beispiel:'''
kein Rauch|Rauch

====HomeTextRisingConstantFalling====
Übersetzung für "rising", "constant" und "falling" 
Werte: frei wählbar separiert mit | 
Werteformat: Wort 
Standardwert: rising|constant|falling 
'''Beispiel:'''
steigend|gleichbleibend|fallend

====HomeTextTodayTomorrowAfterTomorrow====
Übersetzung für "today", "tomorrow" und "day after tomorrow" 
Werte: frei wählbar separiert mit | 
Werteformat: Wort 
Standardwert: today|tomorrow|day after tomorrow 
'''Beispiel:'''
Heute|Morgen|Übermorgen

====HomeTextWeatherNoForecast====
Übersetzung für "No forecast available" - Text wenn keine Wettervorhersage verfügbar ist 
Werte: frei wählbar 
Werteformat: Text 
Standardwert: No forecast available 
'''Beispiel:'''
Es ist leider keine Wettervorhersage für den angegebenen Tag verfügbar!

====HomeTextWeatherForecastInSpecDays====
Text mit Platzhaltern für Wettervorhersage in 4-10 Tagen 
spezielle Platzhalter die nur in diesem Attribut gültig sind: '''%CONDITION%''', '''%DAY%''', '''%HIGH%''' und '''%LOW%''' 
Werte: frei wählbar 
Werteformat: Text mit Platzhaltern 
Standardwert: 
'''Beispiel:'''
In %DAY% Tagen %CONDITION% bei Temperaturen von %LOW% bis %HIGH%°C.

====HomeTextWeatherForecastToday====
Text mit Platzhaltern für Wettervorhersage für heute 
spezielle Platzhalter die nur in diesem Attribut gültig sind: '''%CONDITION%''', '''%DAY%''', '''%HIGH%''' und '''%LOW%''' 
Werte: frei wählbar 
Werteformat: Text mit Platzhaltern 
Standardwert: 
'''Beispiel:'''
%DAY% %CONDITION% bei Temperaturen von %LOW% bis %HIGH%°C. Aktuelle Temperatur %TEMPERATURE%°C bei einer Luftfeuchtigkeit von %HUMIDITY%%. Die gefühlte Temperatur ist %WINDCHILL%°C bei einer Windgeschwindigkeit von %WIND%km/h.

====HomeTextWeatherForecastTomorrow====
Text mit Platzhaltern für Wettervorhersage für morgen/übermorgen 
spezielle Platzhalter die nur in diesem Attribut gültig sind: '''%CONDITION%''', '''%DAY%''', '''%HIGH%''' und '''%LOW%''' 
Werte: frei wählbar 
Werteformat: Text mit Platzhaltern 
Standardwert: 
'''Beispiel:'''
%DAY% %CONDITION% bei Temperaturen von %LOW% bis %HIGH%°C.

====HomeTextWeatherLong====
Langer Text mit Platzhaltern für aktuelle Wetterdaten 
Werte: frei wählbar 
Werteformat: Text mit Platzhaltern 
Standardwert: 
'''Beispiel:'''
Es %TOBE% %CONDITION% bei %TEMPERATURE%°C und %HUMIDITY%% Luftfeuchtigkeit. Die gefühlte Temperatur ist %WINDCHILL%°C bei einer Windgeschwindigkeit von %WIND%km/h. Der Luftdruck liegt bei %PRESSURE%hPa.

====HomeTextWeatherShort====
Kurzer Text mit Platzhaltern für aktuelle Wetterdaten 
Werte: frei wählbar 
Werteformat: Text mit Platzhaltern 
Standardwert: 
'''Beispiel:'''
%CONDITION%, %TEMPERATURE%°C, %HUMIDITY%% Luftfeuchtigkeit, Luftdruck %PRESSURE%hPa

===weitere Attribute===
Viele weitere Dinge lassen sich anpassen.

====HomeAdvancedDetails====
mehr Details anzeigen, abhängig von den zu HOMEMODE hinzugefügten Geräten 
Werte: none, detail, both, room 
Werteformat: Auswahlliste 
Standardwert: none

====HomeDaytimes====
Eigene Tageszeiten als Paare aus Zeit|Wort 
Werte: Zeit|Wort Paare separiert mit Leerzeichen 
Werteformat: Zeit|Wort 
Standardwert: 05:00|morning 10:00|day 14:00|afternoon 18:00|evening 23:00|night 
'''Beispiel:'''
00:00|Mitternacht
00:05|Nacht
06:30|Morgen
10:00|Vormittag
13:00|Mittag
14:30|Nachmittag
17:30|Vorabend
19:00|Abend
23:00|Spätabend

====HomeIcewarningOnOffTemps====
2 leerzeichenseparierte Temperaturen für das Ein- und Ausschalten der Eiswarnung. 
Werte: frei wählbar 
Werteformat: zwei leerzeichenseparierte Temperaturen mit maximal einer Kommastelle 
Standardwert: 2 3

====HomeModeAlarmArmDelay====
Zeit in Sekunden um das aktivieren der Alarmschaltung zu verzögern. 
Werte: 0 bis 99999 
Werteformat: einzelne Zahl (gleiche Verzögerung für alle modeAlarm) oder 3 leerzeichenseparierte Zahlen für jeden modeAlarm (Reihenfolge: armaway armnight armhome) 
Standardwert: 0

====HomeAtTmpRoom====
Diesen Raum zu temporäre at(s) hinzufügen die von HOMEMODE generiert werden 
Werte: frei wählbar 
Werteformat: Wort 
Standardwert:

====HomePresenceDeviceAbsentCount-<ROOMMATE/GUEST>====
Anzahl der dem ROOMMATE/GUEST zugeordneten Presence Geräte um den jeweiligen ROOMMATE/GUEST auf "absent" zu setzen 
Das Attribut ist nur verfügbar wenn mehr als ein Presence Gerät pro ROOMMATE/GUEST gefunden/zugeordnet wurde 
Werte: 0 bis ~ 
Werteformat: einzelne Zahl 
Standardwert: maximale Anzahl von verfügbaren Presence Geräten für jeden ROOMMATE/GUEST

====HomePresenceDevicePresentCount-<ROOMMATE/GUEST>====
Anzahl der dem ROOMMATE/GUEST zugeordneten Presence Geräte um den jeweiligen ROOMMATE/GUEST auf "present" zu setzen 
Das Attribut ist nur verfügbar wenn mehr als ein Presence Gerät pro ROOMMATE/GUEST gefunden/zugeordnet wurde 
Werte: 0 bis ~ 
Werteformat: einzelne Zahl 
Standardwert: 1

====HomePublicIpCheckInterval====
Interval in Minuten für die Überprüfung der öffentlichen IP-Adresse 
Werte: 0 bis 99999 
Werteformat: einzelne Zahl 
Standardwert: 0 (deaktiviert)

====HomeSeasons====
Eigene Jahreszeiten als Paare aus Datum|Wort 
Werte: Datum|Wort Paare separiert mit Leerzeichen 
Werteformat: Datum|Wort 
Standardwert: 03.01|spring 06.01|summer 09.01|autumn 12.01|winter 
'''Beispiel:'''
03.01|Frühling
06.01|Sommer
09.01|Herbst
12.01|Winter

====HomeSensorsBatteryLowPercentage====
Prozentsatz um einen Batteriesensor mit geringer Batterie anzuzeigen (nur bei Sensoren die ihren Batteriewert prozentual angeben) 
Werte: frei wählbar 
Werteformat: Zahl 
Standardwert: 50

====HomeSensorsBatteryReading====
Reading der Batteriesensoren welches statt "battery" benutzt werden soll 
Werte: frei wählbar 
Werteformat: einzelnes Wort 
Standardwert: battery

====HomeSensorsLuminanceReading====
Reading der Lichtsensoren welches statt "luminance" benutzt werden soll 
Werte: frei wählbar 
Werteformat: einzelnes Wort 
Standardwert: luminance

====HomeSensorsPowerEnergyReadings====
Readings der Power/Energy Sensoren welche statt "power" und "energy" benutzt werden sollen 
Werte: frei wählbar 
Werteformat: 2 leerzeichenseparierte Wörter 
Standardwert: power energy

====HomeSensorsSmokeReading====
Readings der Rauchmelder welche statt "state" benutzt werden sollen 
Werte: frei wählbar 
Werteformat: ein Wort 
Standardwert: state

====HomeSensorsSmokeValue====
Regex der Auslösewerte von Rauchmeldern 
Werte: frei wählbar 
Werteformat: RegEx 
Standardwert: on

====HomeSpecialLocation====
Hier können eigene zusätzliche location(s) als kommaseparierte Liste angegeben werden. 
Diese können dann über "set <HOMEMODE> location <LOCATION>" gesetzt werden. Dazu passend werden HomeCMD Attribute erstellt. 
Werte: frei wählbar 
Werteformat: kommaseparierte Liste von Wörtern 
Standardwert:

====HomeSpecialModes====
Hier können eigene zusätzliche mode(s) als kommaseparierte Liste angegeben werden. 
Diese können dann über "set <HOMEMODE> mode <MODE>" gesetzt werden. Dazu passend werden HomeCMD Attribute erstellt. 
Werte: frei wählbar 
Werteformat: kommaseparierte Liste von Wörtern 
Standardwert:

====HomeTrendCalcAge====
Zeit in Sekunden für das Maximalalter des vorherigen Wertes für die Trendberechnung 
Werte: frei wählbar 
Werteformat: Zeit in Sekunden 
Standardwert: 900

Ein weiterer Teil der Konfiguration ist das Befüllen der HomeCMD Attribute. Da dieses durch die Vermischung von FHEM Code, Perl Code und zusätzlichen Platzhaltern erst einmal sehr befremdlich sein kann, habe ich bei der Beschreibung der HomeCMD Attribute teilweise Beispiele hinzugefügt um den Einstieg weiter zu erleichtern.

==HomeCMD Attribute (mit Beispielen)==
Die HomeCMD Attribute sind zum Festlegen der jeweiligen Schaltaktionen gedacht und können damit evtl. vorhandene notify/DOIF ablösen. Sie können mit FHEM-Code, Perl-Code oder aber auch mit beidem vermischt befüllt werden (wovon ich allerdings abrate). Zusätzlich sind noch diverse Platzhalter (siehe Platzhalter) verfügbar.

'''Bei Perl-Code innerhalb der HomeCMD Attribute gibt es hier Besonderheiten.''' 
*Im Gegensatz zur FHEM-Eingabezeile müssen hier keine Semikolon verdoppelt werden
*Kommetarzeilen sind zulässig
*Kommentare am Ende einer Perl-Zeile sind nicht zulässig

Typischer Weise werden in den HomeCMD Attributen weitere Module angesprochen. 
Z.B. benutze ich für jegliche Form der Benachrichtigung den msg Befehl.

Keines der HomeCMD Attribute hat einen Standardwert. Es müssen alle Befehle selbst programmiert werden.

Platzhalter die Text(e) (string) beinhalten, müssen im Perl-Code in Anführungszeichen gesetzt werden (Beispiel %SENSOR%). 
Platzhalter die Zahlen beinhalten (int,float) sollten nicht in Anführungszeichen gesetzt werden damit Zahlenvergleiche (mittels ==, <=, >=, >, <) funktionieren (Beispiel %LIGHT%, %ICE% oder %TEMPERATURE%).

====HomeCMDalarmSmoke====
Befehle die beim Anfang/Ende eines Rauchalarms ausgeführt werden sollen. 

====HomeCMDalarmSmoke-off====
Befehle die beim Ende eines Rauchalarms ausgeführt werden sollen. 
Auslöser: Ende Rauchalarm eines beliebigen (von HOMEMODE überwachten) Rauchmelders 
'''Beispiel:'''
msg push ENTWARNUNG: Alle Rauchalarme sind beendet!

====HomeCMDalarmSmoke-on====
Befehle die bei einem Rauchalarm ausgeführt werden sollen. 
Auslöser: Rauchalarm eines beliebigen (von HOMEMODE überwachten) Rauchmelders 
'''Beispiel:'''
{
my $is = "meldet";
$is = "melden" if (%SMOKECT% > 1);
fhem "msg push ACHTUNG: %SMOKEHR% $is Rauchalarm!";
}

====HomeCMDalarmTampered====
Befehle die beim Anfang/Ende eines Sabotage Alarms ausgeführt werden sollen.

====HomeCMDalarmTampered-off====
Befehle die beim Ende eines Sabotage Alarms ausgeführt werden sollen. 
Auslöser: Ende Sabotage Alarm eines beliebigen (von HOMEMODE überwachten) Kontakt-/Bewegungs-Sensors 
'''Beispiel:'''
msg push ENTWARNUNG: Alle Manipulationen wurden beseitigt!

====HomeCMDalarmTampered-on====
Befehle die bei einem Sabotage Alarm ausgeführt werden sollen. 
Auslöser: Sabotage Alarm eines beliebigen (von HOMEMODE überwachten) Kontakt-/Bewegungs-Sensors 
'''Beispiel:'''
{
my $is = "ist";
$is = "sind" if (%TAMPEREDCT% > 1);
fhem "msg push ACHTUNG: %TAMPEREDHR% $is sabotiert!";
}

====HomeCMDalarmTriggered====
Befehle die beim Anfang/Ende eines Alarms ausgeführt werden sollen.

====HomeCMDalarmTriggered-off====
Befehle die beim Ende eines Alarms ausgeführt werden sollen. 
Auslöser: Ende Alarm eines beliebigen (von HOMEMODE überwachten) Kontakt-/Bewegungs-Sensors 
'''Beispiel:'''
msg ENTWARNUNG: Alle Alarme sind beendet!

====HomeCMDalarmTriggered-on====
Befehle die bei einem Alarm ausgeführt werden sollen. 
Auslöser: Alarm eines beliebigen (von HOMEMODE überwachten) Kontakt-/Bewegungs-Sensors 
'''Beispiel:'''
{
my $is = "ist";
$is = "sind" if (%ALARMCT% > 1);
fhem "msg audio,push,light 3 !!! ALARM !!! %ALARMHR% $is ausgelöst!";
}

====HomeCMDanyoneElseAtHome====
Befehle die beim on/off von anyoneElseAtHome ausgeführt werden sollen.

====HomeCMDanyoneElseAtHome-off====
Befehle die ausgeführt werden sollen sobald anyoneElseAtHome deaktiviert wird. 
Bei Abwesenheit und nicht deaktiviertem HomeAutoAlarmModes wird der Alarm Mode von "armaway" auf "armhome" umgeschaltet damit evtl. vorhandene Bewegungsmelder keinen Alarm mehr melden. 
Auslöser: anyoneElseAtHome on 
'''Beispiel:'''
msg HINWEIS: Es ist nun niemand anderes mehr zu Hause!

====HomeCMDanyoneElseAtHome-on====
Befehle die ausgeführt werden sollen sobald anyoneElseAtHome aktiviert wird. 
Bei Abwesenheit und nicht deaktiviertem HomeAutoAlarmModes wird der Alarm Mode von "armhome" auf "armaway" umgeschaltet damit evtl. vorhandene Bewegungsmelder wieder Alarme melden können. 
Wird anyoneElseAtHome bei Anwesenheit und nicht deaktiviertem HomeAutoAlarmModes aktiviert, so passiert erst einmal nichts, ausser dass die hier angegebenen Befehle ausgeführt werden. Wird dann später die Abwesenheit erkannt, schaltet der Alarm Mode auf "armhome" statt auf "armaway" damit evtl. vorhandene Bewegungsmelder keinen Alarm mehr melden. 
Auslöser: anyoneElseAtHome off 
'''Beispiel:'''
msg HINWEIS: Es ist nun noch jemand anderes zu Hause!

====HomeCMDbatteryLow====
Befehle die ausgeführt werden sollen sobald ein Sensor einen niedrigen Batteriewert meldet. 
'''Beispiel:'''
{
my $msg;
$msg = "Die Batterien von %BATTERYLOW% gehen zur Neige und sollten ausgetauscht werden!" if (%BATTERYLOWCT% == 1);
$msg = "Die Batterien bei folgenden Geräten sollten ausgetauscht werden: %BATTERYLOWALL%" if (%BATTERYLOWCT% > 1);
fhem "msg push $msg";
}

====HomeCMDcontact====
Befehle die ausgeführt werden sollen sobald ein Kontaktsensor open/tilted/closed meldet. 
Die speziellen Platzhalter %ALIAS%, %SENSOR% und %STATE% können in diesem Attribut benutzt werden. 
Auslöser: Kontaktsensor open/tilted/closed 
'''Beispiel:'''
{
my $a = "%ALIAS%";
$a =~ s/d/D/;
fhem "msg $a ist nun %STATE%!";
}

====HomeCMDcontactClosed====
Befehle die ausgeführt werden sollen sobald ein Kontaktsensor geschlossen meldet. 
Die speziellen Platzhalter %ALIAS%, %SENSOR% und %STATE% können in diesem Attribut benutzt werden. 
Auslöser: Kontaktsensor closed 
'''Beispiel:'''
{
my $a = "%ALIAS%";
$a =~ s/d/D/;
fhem "msg $a ist nun geschlossen!";
}

====HomeCMDcontactOpen====
Befehle die ausgeführt werden sollen sobald ein Kontaktsensor offen meldet. 
Die speziellen Platzhalter '''%ALIAS%''', '''%SENSOR%''' und '''%STATE%''' können in diesem Attribut benutzt werden. 
Auslöser: Kontaktsensor open/tilted 
'''Beispiel:'''
{
my $a = "%ALIAS%";
$a =~ s/d/D/;
fhem "msg $a ist nun offen!";
}

====HomeCMDcontactDoormain====
Befehle die ausgeführt werden sollen sobald ein Kontaktsensor des Types doormain open/tilted/closed meldet. 
Die speziellen Platzhalter %ALIAS%, %SENSOR% und %STATE% können in diesem Attribut benutzt werden. 
Auslöser: Kontaktsensor Type doormain open/tilted/closed 
'''Beispiel:'''
{
my $a = "%ALIAS%";
$a =~ s/d/D/;
fhem "msg $a ist nun %STATE%!";
}

====HomeCMDcontactDoormainClosed====
Befehle die ausgeführt werden sollen sobald ein Kontaktsensor des Types doormain closed meldet. 
Die speziellen Platzhalter '''%ALIAS%''', '''%SENSOR%''' und '''%STATE%''' können in diesem Attribut benutzt werden. 
Auslöser: Kontaktsensor vom Typ doormain wird geschlossen 
'''Beispiel:'''
{
# Wenn es Ankommende gibt
if ("%ARRIVERS%")
{
# Zusammenstellen der Begrüßung
my $msg = "Gute";

# "n" anhängen wenn Tageszeit nicht Nacht ist
$msg .= "n" if ("%DAYTIME%" ne "Nacht");

# Leerzeichen einfügen
$msg .= " ";

# den Feiertag der Tageszeit voranstellen wenn ein Feiertag im Kalender FEIERTAG ist
$msg .= "%FEIERTAG%-" if ("%FEIERTAG%");

# Tageszeit einfügen
$msg .= "%DAYTIME% ";

# bei ROOMMATE "zu Hause" in Begrüßung einfügen
$msg .= "zu Hause " if ("%RESIDENT%" =~ /^rr_/);

# Ankommende einfügen
$msg .= "%ARRIVERS%";

# Begrüßung am Sonos im Flur ausgeben bei Abwesenheit über 60 min
fhem "msg audio \@fl_Sonos $msg!" if (%DURABSENCELAST% > 60);
}
}

====HomeCMDcontactDoormainOpen====
Befehle die ausgeführt werden sollen sobald ein Kontaktsensor des Types doormain open/tilted meldet. 
Die speziellen Platzhalter '''%ALIAS%''', '''%SENSOR%''' und '''%STATE%''' können in diesem Attribut benutzt werden. 
Auslöser: Kontaktsensor vom Typ doormain geöffnet 
'''Beispiel:'''
{
my $a = "%ALIAS%";
$a =~ s/d/D/;
fhem "msg $a ist nun geöffnet!";
}

====HomeCMDcontactOpenWarning1====
Befehle die ausgeführt werden sollen sobald ein Kontaktsensor die erste Offenwarnzeit erreicht hat. 
Die speziellen Platzhalter '''%ALIAS%''', '''%SENSOR%''' und '''%STATE%''' können in diesem Attribut benutzt werden. 
Auslöser: erste Offenwarnzeit des Kontakts erreicht 
'''Beispiel:'''
msg audio %ALIAS% steht noch offen!

====HomeCMDcontactOpenWarning2====
Befehle die ausgeführt werden sollen sobald ein Kontaktsensor die zweite Offenwarnzeit erreicht hat. 
Die speziellen Platzhalter '''%ALIAS%''', '''%SENSOR%''' und '''%STATE%''' können in diesem Attribut benutzt werden. 
Auslöser: ab Erreichen der zweiten Offenwarnzeit des Kontakts 
'''Beispiel:'''
msg audio %ALIAS% steht immer noch offen!

====HomeCMDcontactOpenWarningLast====
Befehle die ausgeführt werden sollen sobald ein Kontaktsensor die letzte Offenwarnzeit erreicht hat. 
Die speziellen Platzhalter '''%ALIAS%''', '''%SENSOR%''' und '''%STATE%''' können in diesem Attribut benutzt werden. 
Auslöser: Erreichen der letzten Offenwarnzeit des Kontakts 
'''Beispiel:'''
msg audio Das ist der letzte Hinweis %ALIAS% endlich zu schliessen!

====HomeCMDdaytime====
Befehle die ausgeführt werden sollen sobald sich die Tageszeit (daytime) auf einen beliebigen Wert ändert. 
Um die jeweilige eingetretene Tageszeit zu ermitteln ist der Platzhalter '''%DAYTIME%''' vorgesehen. 
Auslöser: Änderung der Tageszeit (daytime)

====HomeCMDdaytime-<DAYTIME>====
Befehle die ausgeführt werden sollen sobald die jeweilige Tageszeit (daytime) erreicht ist. 
Auslöser: Änderung der Tageszeit (daytime) auf bestimmten Wert 
Bei "night" könnte man z.B. die Heizung bewohnerunabhängig ausschalten, bei "morning" wieder ein.

====HomeCMDdeviceDisable====
Befehle die ausgeführt werden sollen sobald ein Gerät deaktiviert wird. 
Auslöser: 'set deviceDisable <DEVICE>' 
'''Beispiel:'''
{
speak "Das Gerät %ALIAS% ist nun deaktiviert!";

# optional wirklich attr disable für Device setzen und Konfig speichern
#fhem "attr %DEVICE%:FILTER=disable!=1 disable 1; save";

# ROOMMATE/GUEST auf gone/none setzen wenn Presence Devices deaktiviert werden
if ("%DEVICE%" =~ /^PRESENCE\d?_(r[rg]_.*)/)
{
my $resident = $1;
my $gone = $resident =~ /^rr_/ ? "gone" : "none";
fhem "set $resident:FILTER=state!=$gone state $gone";
}
}

====HomeCMDdeviceEnable====
Befehle die ausgeführt werden sollen sobald ein Gerät aktiviert wird. 
Auslöser: 'set deviceEnable <DEVICE>' 
'''Beispiel:'''
{
speak "Das Gerät %ALIAS% ist nun aktiviert!";

# optional attr disable für Device entfernen und Konfig speichern
#fhem "deleteattr %DEVICE%:FILTER=disable=1 disable; save";

# ROOMMATE/GUEST auf home setzen wenn Presence Devices aktiviert werden und anwesend sind
if ("%DEVICE%" =~ /^PRESENCE\d?_(r[rg]_.*)/)
{
fhem "set $1:FILTER=state!=home state home" if (ReadingsVal("%DEVICE%","presence","") eq "present");
}
}

====HomeCMDdnd====
Befehle die beim Anfang/Ende des DND Modus ausgeführt werden sollen. 
Auslöser: Ende des DND Modus 
'''Beispiel:'''
{
if (%DND%)
{
fhem "msg audio Der DND Modus ist nun eingeschaltet!";
}
else
{
fhem "msg audio Der DND Modus ist nun beendet!";
}
}

====HomeCMDdnd-off====
Befehle die beim Ende des DND Modus ausgeführt werden sollen. 
Auslöser: Ende des DND Modus 
'''Beispiel:'''
msg audio Der DND Modus ist nun beendet!

====HomeCMDdnd-on====
Befehle die beim Beginn des DND Modus ausgeführt werden sollen. 
Auslöser: Beginn des DND Modus 
'''Beispiel:'''
msg audio Der DND Modus ist nun eingeschaltet!

====HomeCMDevent====
Befehle die beim Beginn eines beliebigen (holiday)Kalender Events ausgeführt werden sollen. 
Auslöser: Beginn eines beliebigen (holiday)Kalender Events 
Platzhalter '''%CALENDAR%''', '''%EVENT%''' und '''%PREVEVENT%''' können zusätzlich verwendet werden 
'''Beispiel:'''
{
fhem "set Weihnachten on" if ("%EVENT%" eq "Weihnachten");
fhem "set Weihnachten off" if ("%PREVEVENT%" eq "Weihnachten");
}

====HomeCMDevent-<KALENDER>-each====
Befehle die beim Beginn/Ende eines beliebigen (holiday)Kalender Events eines bestimmten KALENDERs ausgeführt werden sollen. 
Auslöser: Beginn eines beliebigen (holiday)Kalender Events eines bestimmten KALENDERs 
Platzhalter '''%EVENT%''' und '''%PREVEVENT%''' können zusätzlich verwendet werden 
'''Beispiel für "HomeCMDevent-FEIERTAGE-each":'''
{
fhem "set Weihnachten off" if ("%PREVEVENT%" eq "Weihnachten");
}
'''Beispiel für "HomeCMDevent-URLAUBDAN-each":'''
{
if ("%EVENT%" =~ /urlaub/i)
{
speak "Dan hat jetzt Urlaub!!!";
}
elsif ("%PREVEVENT%" =~ /urlaub/i)
{
speak "Der Urlaub von Dan ist nun zu Ende!!!";
}
}

'''Beispiel für "HomeCMDevent-WOHNUNG-each":'''
{
# Heizung an/aus schalten
my $heiz = "([bksw]z|ku)_Thermostat";
if ("%EVENT%" =~ /^heizung(..+)?$/i)
{
my $zeit = $1;
if ("%SEASON%" ne "Sommer")
{

# morgens nicht alle Thermostaten schalten
$heiz = "([bks]z|ku)_Thermostat" if ($zeit && $zeit =~ /morgens?$/i);
fhem "set $heiz:FILTER=controlMode!=day controlMode day"
}
}
elsif ("%PREVEVENT%" =~ /^heizung/i)
{
fhem "set $heiz:FILTER=controlMode!=night controlMode night" if ("%SEASON%" ne "Sommer");
}

# WLAN an/aus schalten
elsif ("%EVENT%" =~ /^wlan|wifi|wi-fi/i)
{
fhem "set Router wifi off";
}
elsif ("%PREVEVENT%" =~ /^wlan|wifi|wi-fi/i)
{
fhem "set Router wifi on";
}

# G-Tag für Putzfrau (de)aktivieren
elsif ("%EVENT%" =~ /^putz/i)
{
fhem "set %NAME% deviceEnable PRESENCE_rg_Inge";
}
elsif ("%PREVEVENT%" =~ /^putz/i)
{
fhem "set %NAME% deviceDisable PRESENCE_rg_Inge";
}

# G-Tag für Gast (de)aktivieren
elsif ("%EVENT%" =~ /g([aä]|ae)st/i)
{
fhem "set %NAME% deviceEnable PRESENCE_rg_Gast";
}
elsif ("%PREVEVENT%" =~ /g([aä]|ae)st/i)
{
fhem "set %NAME% deviceDisable PRESENCE_rg_Gast";
}
}

====HomeCMDevent-<KALENDER>-<EVENT>-begin====
Befehle die beim Beginn eines bestimmten (holiday)Kalender EVENTs eines bestimmten KALENDERs ausgeführt werden sollen. 
Auslöser: Beginn eines bestimmten (holiday)Kalender EVENTs eines bestimmten KALENDERs 
Platzhalter '''%PREVEVENT%''' kann zusätzlich verwendet werden 
'''Beispiel für "HomeCMDevent-FEIERTAGE-Neujahr-begin":'''
set %SENSORSENERGY% meterReset

====HomeCMDevent-<KALENDER>-<EVENT>-end====
Befehle die bei Ende der (holiday)Kalender EVENTs eines bestimmten KALENDERs ausgeführt werden sollen. 
Auslöser: Ende der (holiday)Kalender EVENTs eines bestimmten KALENDERs 
Platzhalter '''%PREVEVENT%''' kann zusätzlich verwendet werden

====HomeCMDfhemDEFINED====
Befehle die ausgeführt werden sollen wenn ein neues Gerät angelegt wird (define) 
'''Beispiel:'''
{
# Jedem neu definierten Gerät den Geräte-TYPE auch als Raum im Menüpunkt Module zuweisen
fhem "attr %DEFINED% room Module->".InternalVal("%DEFINED%","TYPE","default");
}

====HomeCMDfhemINITIALIZED====
Befehle die ausgeführt werden sollen wenn FHEM gestartet wurde 
'''Beispiel:'''
msg FHEM Home wurde gestartet...

====HomeCMDfhemSAVE====
Befehle die ausgeführt werden sollen wenn in FHEM die Konfigurationsdatei gespeichert wird 
'''Beispiel (Backup von fhem.cfg und fhem.state):'''
{
# Datum/Uhrzeit
my $now = Timeow();
# Leerzeichen durch Unterstriche ersetzen
$now =~ s/ /_/g;
# Backup der Datei fhem.cfg
`cp $attr{global}{configfile} ./backup/fhem.cfg.$now`;
# Log-Ausgabe der gespeicherten Datei
Log3 undef,3,"saved ./backup/fhem.cfg.$now";
# Backup der Datei fhem.state
`cp $attr{global}{statefile} ./backup/fhem.state.$now`;
# Log-Ausgabe der gespeicherten Datei
Log3 undef,3,"saved ./backup/fhem.state.$now";
}

====HomeCMDfhemUPDATE====
Befehle die ausgeführt werden sollen wenn das Update von FHEM ausgeführt wurde 
'''Beispiel:'''
msg audio Das Update für FHEM ist beendet!

====HomeCMDicewarning====
Befehle die bei Anfang/Ende der Eiswarnung ausgeführt werden sollen 
Auslöser: icewarning 0/1 
'''Beispiel:'''
{
if (%ICE%)
{
fhem "msg push ACHTUNG!!! Es sind nur noch %TEMPERATURE%°C! Somit könnte es glatt werden!";
}
else
{
fhem "msg audio Es sind wieder %TEMPERATURE%°C! Die Glättewarnung ist damit beendet!.";
}
}

====HomeCMDicewarning-off====
Befehle die bei Ende der Eiswarnung ausgeführt werden sollen 
Auslöser: icewarning 0 
'''Beispiel:'''
msg audio Es sind wieder %TEMPERATURE%°C! Die Glättewarnung ist damit beendet!

====HomeCMDicewarning-on====
Befehle die bei Beginn der Eiswarnung ausgeführt werden sollen 
Auslöser: icewarning 1 
'''Beispiel:'''
msg audio ACHTUNG!!! Es sind nur noch %TEMPERATURE%°C! Somit könnte es glatt werden!

====HomeCMDlocation====
Befehle die beim Ändern der location ausgeführt werden sollen. 
Auslöser: Änderung location

====HomeCMDlocation-<LOCATION>====
Befehle die bei Änderung auf eine bestimmte location ausgeführt werden sollen. 
Auslöser: Änderung auf bestimmte location

====HomeCMDmode====
Befehle die beim Ändern von mode ausgeführt werden sollen. 
Auslöser: Änderung mode

====HomeCMDmode-absent-belated====
Befehle die nachträglich zur Abwesenheit ausgeführt werden sollen, die Zeit kann im Atteribut "HomeModeAbsentBelatedTime" eingestellt werden 
Auslöser: Abwesenheit + XX min 
'''Beispiel:'''
set Heizungen [FILTER=controlManu!=off] controlMode night

====HomeCMDmode-<MODE>====
Befehle die bei Änderung auf einen bestimmten mode ausgeführt werden sollen. 
Auslöser: Änderung auf bestimmten mode 
'''Beispiel für "HomeCMDmode-absent":'''
set HarmonyHub:FILTER=activity!=PowerOff activity PowerOff;
set wz_Ventilator:FILTER=speed!=0 speed 0;
set TYPE=SONOSPLAYER:FILTER=Volume>0 Volume 0;
set Sonos stopAll;
sleep 3;
set Wohnung [FILTER=state!=off] off"
'''Beispiel für "HomeCMDmode-asleep":'''
define atTmp_wz_Media_aus_%SELF% at +01:00:00 set HarmonyHub:FILTER=currentActivity!=PowerOff activity PowerOff;
define atTmp_wz_Venti_aus_%SELF% at +01:00:00 set wz_Ventilator:FILTER=speed!=0 speed 0;
define atTmp_wzLS_aus_%SELF% at +00:30:00 set wz_LS scene aus;
define atTmp_all_Sonos_vol_down_%SELF% at +00:02:00 set TYPE=SONOSPLAYER:FILTER=Volume!=0 Volume 0 1;
define atTmp_all_Sonos_off_%SELF% at +00:02:30 set Sonos stopAll;
set [sw]z_Auto(Music|Light):FILTER=state!=off off;
set Heizungen [FILTER=controlManu!=off] controlMode night
'''Beispiel für "HomeCMDmode-awoken":'''
set [sw]z_Auto(Music|Light):FILTER=state!=on on
'''Beispiel für "HomeCMDmode-gone":'''
set Heizungen [FILTER=controlManu!=off] controlManu off

====HomeCMDmode-<MODE>-resident====
Befehle die bei Änderung auf einen bestimmten mode, ausgelöst durch einen beliebigen Resident, ausgeführt werden. 
Auslöser: Änderung mode von beliebigem Resident ausgelöst 
'''Beispiel für "HomeCMDmode-asleep-resident":'''
msg audio @%AUDIO% Guten Nacht und schlaf' gut %ALIAS%!
'''Beispiel für "HomeCMDmode-awoken-resident":'''
{
my $msg = "Guten";
$msg .= " %FEIERTAG%" if ("%FEIERTAG%");
$msg .= " Morgen %ALIAS%";
fhem "msg audio \@%AUDIO% $msg";
fhem "defmod atTmp_wetter_%RESIDENT%_%SELF% at +00:07:00 msg audio Wettervorhersage für heute: %FORECASTTODAY%";
}

====HomeCMDmode-<MODE>-<ROOMMATE/GUEST>====
Befehle die bei Änderung auf einen bestimmten mode, ausgelöst durch einen bestimmten Resident, ausgeführt werden. 
Auslöser: Änderung mode von bestimmten Resident ausgelöst

====HomeCMDmodeAlarm====
Befehle die beim Ändern von modeAlarm ausgeführt werden sollen. 
Auslöser: Änderung modeAlarm

====HomeCMDmodeAlarm-<armaway/armhome/armnight/disarm>====
Befehle die bei Änderung auf einen bestimmten modeAlarm ausgeführt werden sollen. 
Auslöser: Änderung auf bestimmten modeAlarm 
'''Beispiel für "HomeCMDmodeAlarm-armaway":'''
{
if ("%PREVAMODE%" eq "disarm")
{
# Alarmanlage einschalten
fhem "set AA_Arm:FILTER=level!=100 alarmLevel armAll";

# Nachricht zusammensetzen
my $msg;
$msg .= "Die Alarmanlage ist nun scharf geschaltet!" if ("%RESIDENT%" ne "rr_Dan");
my $is = "%ALARMHR%" =~ /und/ ? "sind" : "ist";
$msg .= " " if ($msg);
$msg .= "ACHTUNG: %ALARMHR% $is noch offen!!!" if (%ALARMCT%);

# Nachricht an ROOMMATE/GUEST senden
fhem "msg \@%RESIDENT% $msg" if ($msg);

# Eingangstür abschließen falls noch nicht geschehen
fhem "set fl_Tuerschloss:FILTER=state!=locked lock";
}
}
'''Beispiel für "HomeCMDmodeAlarm-armhome":'''
AA_Arm:FILTER=level!=25 alarmLevel armExtSens;
set fl_Tuerschloss:FILTER=state!=locked lock
'''Beispiel für "HomeCMDmodeAlarm-armnight":'''
AA_Arm:FILTER=level!=25 alarmLevel armExtSens;
set fl_Tuerschloss:FILTER=state!=locked lock
'''Beispiel für "HomeCMDmodeAlarm-disarm":'''
{
# Alarmanlage ausschalten
fhem "set AA_Arm:FILTER=level!=0 alarmLevel disarmed";
my $prio = "";

# Nachrichtenpriorität auf 1 setzen bei Ankunft (höhere Lautstärke beim Abspielen damit man das auch vor der Tür hört)
$prio = " 1" if ("%LOCATION%" eq "arrival");

# Nachricht an ROOMMATE/GUEST senden wenn der vorherige alarmMode nicht "armnight" ist
fhem "msg audio \@fl_Sonos$prio Die Alarmanlage ist nun ausgeschaltet %ALIAS%!" if ("%PREVAMODE%" ne "armnight");
}

====HomeCMDmotion====
Befehle die bei Statusänderung eines beliebigen Bewegungsmelders ausgeführt werden sollen 
Auslöser: öffnen/schließen eines beliebigen Bewegungsmelders 
'''Beispiel:'''
{
# Raum aus Sensornamen ermitteln, z.B. bz_Sensor
my $room = (split /_/,"%SENSOR%")[0];

# Status des structure aller Lichter dieses Raums
my $lichter = Value($room."_Lichter");

# Status des dummy Tageslicht
my $tl = Value("Tageslicht");

if ("%STATE%" eq "geöffnet")
{
# Lichtwert des Sensors
my $lum = ReadingsNum("%SENSOR%","luminance",100);

# Löschen des evtl. schon vorhandenen "at"
fhem "delete atTmp_Bewegungsmelder_Licht_aus_".$room."_%SELF%" if (IsDevice("atTmp_Bewegungsmelder_Licht_aus_".$room."_%SELF%"));

# Licht nur wenn kein Tageslicht oder Lichtwert des Sensors kleiner als 10 und AutoLight eingeschaltet und modeAlarm nicht armaway
if (($tl eq "off" || $lum < 10) && $lichter eq "off" && Value($room."_AutoLight") eq "on" && "%AMODE%" ne "armaway")
{
my $scene;

# verschiedene Szenen für verschiedene Modus bzw. Aussenlichtstärken
if ("%MODE%" eq "gotosleep")
{
$scene = "Abend";
}
elsif ("%MODE%" eq "asleep")
{
$scene = "Nacht";
}
elsif (%LIGHT% > 3)
{
$scene = "viel";
}
elsif (%LIGHT% < 4)
{
$scene = "mittel";
}

# Schalten der entsprechenden Szene (Modul LightScene)
fhem "set ".$room."_LS scene $scene" if ($scene);
}
}
else
{
# unterschiedliche Ausschaltzeiten für unterschiedliche Räume
my $t = 3;
$t = 15 if ($room eq "wz");
$t = 2 if ($room eq "bz" || ($room =~ /wz|ku/ && "%MODE%" =~ /sleep/));
$t = 1 if ($room eq "fl");

# Zahl in Minuten umrechnen in einen Zeitpunkt für das "at"
my $d = HOMEMODE_hourMaker($t);

# Anlegen des "at" zum Ausschalten des Lichts wenn die Lichter angeschaltet sind und auch AutoLight eingeschaltet ist
if ($lichter ne "off" && Value($room."_AutoLight") eq "on")
{
my $cmd = "set ".$room."_LS scene aus";
fhem "defmod atTmp_Bewegungsmelder_Licht_aus_".$room."_%SELF% at +$d $cmd";
}
}
}

====HomeCMDmotion-off====
Befehle die bei Ende der Bewegung eines beliebigen Bewegungsmelders ausgeführt werden sollen 
Auslöser: Ende der Bewegung eines beliebigen Bewegungsmelders

====HomeCMDmotion-on====
Befehle die bei Beginn der Bewegung eines beliebigen Bewegungsmelders ausgeführt werden sollen 
Auslöser: Beginn der Bewegung eines beliebigen Bewegungsmelders

====HomeCMDpresence-<absent/present>====
Befehle die bei Änderung von presence ausgeführt werden sollen 
Auslöser: Änderung presence 
'''Beispiel für "HomeCMDpresence-present":'''
set w_Steckdosen [FILTER=state!=on] on;
set Heizungen [FILTER=controlManu!=off] controlMode auto

====HomeCMDpresence-<absent/present>-device====
Befehle die bei Änderung von presence, ausgelöst durch ein beliebiges Presence Device, ausgeführt werden sollen 
Auslöser: Änderung presence, ausgelöst durch beliebiges Presence Device 
'''Beispiel für "HomeCMDpresence-present-device":'''
{
# mindestens 1x täglich den Batteriewert des PRESENCE Geräts bei erkannter Anwesenheit holen
fhem '"sudo /opt/fhem/scripts/GTag-bat.sh %DEVICE% %ADDRESS% &"'
if ("%DEVICE%" =~ /^PRESENCE_/ && (!defined ReadingsVal("%DEVICE%","battery",undef) || ReadingsAge("%DEVICE%","battery",0) > 64800));
}

====HomeCMDpresence-<absent/present>-resident====
Befehle die bei Änderung von presence, ausgelöst durch einen beliebigen Resident, ausgeführt werden sollen 
Auslöser: Änderung presence, ausgelöst durch beliebigen Resident 
'''Beispiel für "HomeCMDpresence-absent-resident":'''
{
# Mich benachrichtigen wenn ich nicht zu hause bin und jemand anderes die Wohnung verlässt
fhem "msg push \@rr_Dan %ALIAS% hat gerade die Wohnung verlassen!"
if ("%RESIDENT%" ne "rr_Dan" && ReadingsVal("rr_Dan","presence","") ne "present");

# Verabschiedungsnachricht zusammensetzen
my $msg;

# Alle außer mich selbst verabschieden
$msg .= "Bis bald und auf Wiedersehen %ALIAS%..." if ("%RESIDENT%" ne "rr_Dan");

# Glättewarnung wenn nötig
$msg .= " ACHTUNG!!! Es ist %TEMPERATURE%°C kalt! Somit könnte es glatt werden!" if (%ICE%);

# Nachricht senden wenn vorhanden
fhem "msg \@%RESIDENT% $msg" if ($msg);
}
'''Beispielcode für "HomeCMDpresence-present-resident":'''
{
# alle Ankommenden außer mir selbst
if ("%RESIDENT%" ne "rr_Dan")
{
# Benachrichtigung wenn jemand kommt
fhem "msg audio %ALIAS% kommt gerade!" if ("%LOCATION%" ne "arrival");

# Nachricht an Ankommende(n) zusammensetzen
my $g = "gute";
$g .= "n" if ("%DAYTIME%" ne "Nacht);

# Nachricht an Ankommende(n) senden
fhem "msg \@%RESIDENT% Willkommen und $g %DAYTIME% %ALIAS%!";
}
}

====HomeCMDpresence-<absent/present>-<ROOMMATE/GUEST>====
Befehle die bei Änderung von presence, ausgelöst durch einen bestimmten Resident, ausgeführt werden sollen 
Auslöser: Änderung presence, ausgelöst durch bestimmten Resident 

====HomeCMDpresence-<absent/present>-<ROOMMATE/GUEST>-<DEVICE>====
Befehle die bei Änderung von presence, ausgelöst durch ein bestimmtes Presence Device eines bestimmten Resident, ausgeführt werden sollen 
Dieses Attribut ist nur verfügbar wenn ein Resident mehr als ein Presence Device hat 
Auslöser: Änderung presence, ausgelöst durch bestimmtes Presence Device eines bestimmten Resident

====HomeCMDseason====
Befehle die bei Änderung der Jahreszeit ausgeführt werden sollen 
Auslöser: Änderung Jahreszeit 
'''Beispiel'''
{
my $t = "%SEASON%";
$t .= "s" if ($t eq "Frühling");
fhem "msg push Die Wohnung ist nun im $t-Modus!";
fhem "set Heizungen [FILTER=controlMode!=auto] controlMode auto" if ($t ne "Sommer");
}

====HomeCMDseason-<SEASON>====
Befehle die bei Änderung der Jahreszeit in eine bestimmte Jahreszeit ausgeführt werden sollen 
Auslöser: Änderung bestimmte Jahreszeit

====HomeCMDtwilight====
Befehle die bei Änderung der Dämmerung ausgeführt werden sollen 
Auslöser: Änderung Dämmerung

====HomeCMDtwilight-<sr/sr_astro/sr_civil/sr_indoor/sr_weather/ss/ss_astro/ss_civil/ss_indoor/ss_weather>====
Befehle die bei Änderung zu bestimmter Dämmerung ausgeführt werden sollen 
Auslöser: Änderung zu bestimmter Dämmerung

====HomeCMDuwz-warn====
Befehle die bei Beginn/Ende der UWZ Warnungen ausgeführt werden sollen 
Auslöser: Beginn/Ende der UWZ Warnungen

====HomeCMDuwz-warn-begin====
Befehle die bei Beginn der UWZ Warnungen ausgeführt werden sollen 
Auslöser: Beginn der UWZ Warnungen 
'''Beispiel:'''
msg %UWZLONG%

====HomeCMDuwz-warn-end====
Befehle die beim Ende der UWZ Warnungen ausgeführt werden sollen 
Auslöser: Ende der UWZ Warnungen 
'''Beispiel:'''
msg Alle Unwetterwarnungen sind nun beendet!

=Platzhalter=
==verfügbar in allen HomeCMD Attributen==
===%ADDRESS%===
MAC Adresse des zuletzt ausgelösten Presence Geräts

===%ALARM%===
Liste mit Namen der ausgelösten Alarm Geräte 
Wert ist 0 wenn kein Alarm Device ausgelöst ist

===%ALARMCT%===
Anzahl der ausgelösten Alarm Geräte

===%ALARMHR%===
Liste mit (human readable) Namen der ausgelösten Alarm Geräte 
Wert ist 0 wenn kein Alarm Device ausgelöst ist 
kann z.B. für msg benutzt werden

===%ALIAS%===
Alias des zuletzt ausgelösten Resident

===%AMODE%===
aktueller Alarm Mode

===%AEAH%===
Wert von anyoneElseAtHome 
Wert ist 1 wenn on und 0 wenn off

===%ARRIVERS%===
Alias-Liste der ROOMMATE/GUEST deren location auf arrival steht 
kann z.B. dafür benutzt werden um Residents zu begrüßen 
z.B. Peter, Paul und Marry

===%AUDIO%===
Audio Device des zuletzt ausgelösten ROOMMATE/GUEST (Attribut msgContactAudio) 
wenn das Attribut msgContactAudio des jeweiligen Resident keinen Wert hat, so wird versucht den Wert des Attributs aus dem globalMsg (sofern vorhanden) auszulesen 
kann z.B. dafür benutzt werden um Resident spezifische msg(s) vom Typ audio zu senden, z.B. Nacht/Morgen Grüße/Wünsche

===%BATTERYLOW%===
Alias des zu letzt gemeldeten Geräts mit niedrigem Batteriestand

===%BATTERYLOWALL%===
Wert des Reading batteryLow_hr

===%BATTERYLOWCT%===
Wert des Reading batteryLow_ct

===%CONDITION%===
Wert des Reading condition des überwachten weather Device 
kann z.B. für Wetter(vorhersage) benutzt werden

===%CONTACT%===
Wert des Reading lastContact (Name des zuletzt geöffneten Kontakt Sensor) 
kann z.B. dafür benutzt werden um msg zu versenden

===%DAYTIME%===
Wert des Reading daytime 
kann z.B. dafür benutzt werden um Tageszeit spezifische Aktionen zu schalten

===%DEVICE%===
Name des zuletzt ausgelösten Presence Gerät

===%DEVICEA%===
Wert des Reading lastAbsentByPresenceDevice

===%DEVICEP%===
Wert des Reading lastPresentByPresenceDevice

===%DISABLED%===
Wert des Reading devicesDisabled

===%DND%===
DND Status 
1 wenn an, 0 wenn aus

===%DURABSENCE%===
Wert des Reading durTimerAbsence_cr des zu letzt ausgelösten ROOMMATE/GUEST

===%DURABSENCELAST%===
Wert des Reading lastDurAbsence_cr des zu letzt ausgelösten ROOMMATE/GUEST

===%DURPRESENCE%===
Wert des Reading durTimerPresence_cr des zu letzt ausgelösten ROOMMATE/GUEST

===%DURPRESENCELAST%===
Wert des Reading lastDurPresence_cr des zu letzt ausgelösten ROOMMATE/GUEST

===%DURSLEEP%===
Wert des Reading durTimerSleep_cr des zu letzt ausgelösten ROOMMATE/GUEST

===%DURSLEEPLAST%===
Wert des Reading lastDurSleep_cr des zu letzt ausgelösten ROOMMATE/GUEST

===%<CALENDARNAME>%===
Event des benannten Kalenders 
0 wenn kein gerade kein Event ist

===%<CALENDARNAME-EVENTNAME>%===
0 wenn das benannte Event nicht aktiv ist 
1 wenn das benannte Event aktiv ist

===%FORECAST%===
Wettervorhersage für morgen

===%FORECASTTODAY%===
Wettervorhersage für heute

===%HUMIDITY%===
Wert des Reading humidity von HOMEMODE

===%HUMIDITYTREND%===
Wert des Reading humidityTrend von HOMEMODE

===%ICE%===
0 wenn keine Eiswarnung besteht 
1 wenn Eiswarnung besteht

===%IP%===
Wert des Reading publicIP von HOMEMODE

===%LIGHT%===
Wert des Reading light von HOMEMODE

===%LOCATION%===
Wert des Reading location von HOMEMODE

===%LOCATIONR%===
Wert des Reading location des zu letzt ausgelösten ROOMMATE/GUEST

===%LUMINANCE%===
Wert des Reading luminance von HOMEMODE

===%LUMINANCETREND%===
Wert des Reading luminanceTrend von HOMEMODE

===%MODE%===
gerade aktiver Modus von HOMEMODE (Reading mode)

===%MODEALARM%===
aktueller Alarm Mode (wie %AMODE%)

===%MOTION%===
Wert des Reading lastMotion von HOMEMODE

===%NAME%===
Name des HOMEMODE Geräts selbst (identisch zu %SELF%)

===%OPEN%===
Wert des Reading contactsOutsideOpen von HOMEMODE

===%OPENCT%===
Wert des Reading contactsOutsideOpen_ct von HOMEMODE

===%OPENHR%===
Wert des Reading contactsOutsideOpen_hr von HOMEMODE

===%PANIC%===
0 wenn panic ausgeschaltet ist 
1 wenn panic eingeschaltet ist

===%RESIDENT%===
Name des zu letzt ausgelösten ROOMMATE/GUEST

===%PRESENT%===
presence von HOMEMODE
0 wenn absent
1 wenn present

===%PRESENTR%===
presence des zu letzt ausgelösten ROOMMATE/GUEST
0 wenn absent
1 wenn present

===%PRESSURE%===
Wert des Reading pressure von HOMEMODE

===%PREVAMODE%===
vorheriger modeAlarm von HOMEMODE

===%PREVCONTACT%===
vorheriger geöffneter Kontaktsensor

===%PREVMODE%===
vorheriger mode von HOMEMODE

===%PREVMODER%===
vorheriger state des zu letzt ausgelösten ROOMMATE/GUEST

===%PREVMOTION%===
vorheriger geöffneter Bewegungsmelder

===%SEASON%===
Wert des Reading season von HOMEMODE

===%SELF%===
Name des HOMEMODE Geräts selbst (identisch zu %NAME%)

===%SENSORSBATTERY%===
Liste aus Internal SENSORSBATTERY

===%SENSORSCONTACT%===
Liste aus Internal SENSORSCONTACT

===%SENSORSENERGY%===
Liste aus Internal SENSORSENERGY

===%SENSORSMOTION%===
Liste aus Internal SENSORSMOTION

===%SENSORSSMOKE%===
Liste aus Internal SENSORSSMOKE

===%SMOKE%===
Wert des Reading alarmSmoke von HOMEMODE
0 wenn kein Alarm

===%SMOKECT%===
Wert des Reading alarmSmoke_ct von HOMEMODE

===%SMOKEHR%===
Wert des Reading alarmSmoke_hr von HOMEMODE

===%TAMPERED%===
Wert des Reading sensorsTampered von HOMEMODE

===%TAMPEREDCT%===
Wert des Reading sensorsTampered_ct von HOMEMODE

===%TAMPEREDHR%===
Wert des Reading sensorsTampered_hr von HOMEMODE

===%TEMPERATURE%===
Wert des Reading temperature von HOMEMODE

===%TEMPERATURETREND%===
Wert des Reading temperatureTrend von HOMEMODE

===%TOBE%===
are/sind oder is/ist der Wetterkondition

===%TWILIGHT%===
Wert des Reading twilight von HOMEMODE

===%TWILIGHTEVENT%===
aktuelles twilight Event

===%UWZ%===
UWZ Warnlevel

===%UWZLONG%===
alle aktuellen UWZ Warnungen (lange Version)

===%UWZSHORT%===
alle aktuellen UWZ Warnungen (kurze Version)

===%WEATHER%===
Wert von "get <HOMEMODE> weather short"

===%WEATHERLONG%===
Wert von "get <HOMEMODE> weather long"

===%WIND%===
Wert des Reading wind von HOMEMODE

===%WINDCHILL%===
Wert des Reading wind_chill vom eingebundenen Wetter Gerät

==verfügbar in den HomeCMDcontact, HomeCMDmotion und HomeCMDalarm Attributen==
===%ALIAS%===
alias des zuletzt ausgelösten Kontakt/Bewegungs/Rauchsensors

===%SENSOR%===
name des zuletzt ausgelösten Kontakt/Bewegungs/Rauchsensors

===%STATE%===
state des zuletzt ausgelösten Kontakt/Bewegungs/Rauchsensors

==verfügbar in den HomeTextWeatherForecast Attributen==
===%CONDITION%===
Wert des Readings condition des eather Geräts

===%DAY%===
Tag der Wettervorhersage (1 - heute, 2 - morgen)

===%HIGH%===
maximale Temperatur der Wettervorhersage

===%LOW%===
minimale Temperatur der Wettervorhersage

==verfügbar in den HomeCMDevent Attributen==
===%CALENDAR%===
Name der Kalenders

===%DESCRIPTION%===
Beschreibung des aktuellen Event des Kalenders (nicht verfügbar bei holiday Geräten)

===%EVENT%===
Name/Titel des aktuellen Event des Kalenders

===%PREVEVENT%===
Name/Titel des vorherigen Event des Kalenders

==verfügbar in den HomeCMDdevice Attributen==
===%DEVICE%===
name der deaktivierten Geräts

===%ALIAS%===
alias der deaktivierten Geräts

=Benötigte Events=
Folgende Events werden von HOMEMODE ausgewertet bzw. werden benötigt damit HOMEMODE vollumfänglich funktionieren kann.

<table>
<tr>
<td>DEVICE-TYPE</td>
<td>EVENT</td>
</tr>
<tr>
<td>RESIDENTS</td>
<td>state</td>
</tr>
<tr>
<td></td>
<td>presence</td>
</tr>
<tr>
<td>ROOMMATE,GUEST</td>
<td>state</td>
</tr>
<tr>
<td></td>
<td>presence</td>
</tr>
<tr>
<td></td>
<td>wayhome</td>
</tr>
<tr>
<td>{SENSORSCONTACT}</td>
<td>state</td>
</tr>
<tr>
<td></td>
<td>sabotageError</td>
</tr>
<tr>
<td></td>
<td>"HomeReadings"</td>
</tr>
<tr>
<td></td>
<td>"HomeSensorsContactReadings"</td>
</tr>
<tr>
<td>{SENSORSMOTION}</td>
<td>state</td>
</tr>
<tr>
<td></td>
<td>sabotageError</td>
</tr>
<tr>
<td></td>
<td>"HomeReadings"</td>
</tr>
<tr>
<td></td>
<td>"HomeSensorsMotionReadings"</td>
</tr>
<tr>
<td>{SENSORSLUMINANCE}</td>
<td>luminance</td>
</tr>
<tr>
<td></td>
<td>"HomeSensorsLuminanceReading"</td>
</tr>
<tr>
<td>{SENSORSENERGY}</td>
<td>power</td>
</tr>
<tr>
<td></td>
<td>energy</td>
</tr>
<tr>
<td></td>
<td>"HomeSensorsPowerEnergyReadings"</td>
</tr>
<tr>
<td>{SENSORSBATTERY}</td>
<td>battery</td>
</tr>
<tr>
<td></td>
<td>"HomeSensorsBatteryReading"</td>
</tr>
<tr>
<td>"HomePresenceDeviceType"</td>
<td>presence</td>
</tr>
<tr>
<td>"HomeWeatherDevice"</td>
<td>humidity</td>
</tr>
<tr>
<td></td>
<td>temperature</td>
</tr>
<tr>
<td></td>
<td>wind</td>
</tr>
<tr>
<td></td>
<td>pressure</td>
</tr>
<tr>
<td>"HomeTwilightDevice"</td>
<td>light</td>
</tr>
<tr>
<td></td>
<td>twilight</td>
</tr>
<tr>
<td></td>
<td>aktEvent</td>
</tr>
<tr>
<td></td>
<td>pressure</td>
</tr>
<tr>
<td>"HomeSensorTemperatureOutside"</td>
<td>temperature</td>
</tr>
<tr>
<td></td>
<td>humidity</td>
</tr>
<tr>
<td>"HomeSensorHumidityOutside"</td>
<td>humidity</td>
</tr>
<tr>
<td>"HomeSensorWindspeed"</td>
<td>"HomeSensorWindspeed"</td>
</tr>
<tr>
<td>"HomeSensorAirpressure"</td>
<td>"HomeSensorAirpressure"</td>
</tr>
<tr>
<td>"HomeEventsHolidayDevices"</td>
<td>state</td>
</tr>
<tr>
<td>"HomeUWZ"</td>
<td>WarnCount</td>
</tr>
</table>

MsgDialog

2018-01-31T07:23:09Z

Binford6000:

{{Infobox Modul
|ModPurpose=Dialoge für Sofortnachrichten über TelegramBot, Jabber und WhatsApp
|ModType=h
|ModForumArea=Frontends
|ModTechName=76_msgDialog.pm
|ModOwner={{Link2FU|4106|igami}}
}}

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

== Konfiguration ==

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

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

=== msgConfig ===

Als erstes benötigt man ein definiertes msgConfig device:

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

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

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

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

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

=== Define ===

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

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

attr meta_Dialog allowed everyone
</pre>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

== Beispiele ==

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

== TelegramBot ==

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

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

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

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

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

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

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

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

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

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

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

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

[[Kategorie:Hilfsmodul]]

MsgDialog

2017-12-03T17:31:32Z

Binford6000:

{{Infobox Modul
|ModPurpose=Dialoge für Sofortnachrichten über TelegramBot, Jabber und WhatsApp
|ModType=h
|ModForumArea=Frontends
|ModTechName=76_msgDialog.pm
|ModOwner={{Link2FU|4106|igami}}
}}

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

== Konfiguration ==

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

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

=== msgConfig ===

Als erstes benötigt man ein definiertes msgConfig device:

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

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

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

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

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

=== Define ===

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

== Beispiele ==

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

== TelegramBot ==

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

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

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

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

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

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

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

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

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

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

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

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

[[Kategorie:Hilfsmodul]]

MsgDialog

2017-12-03T17:17:13Z

Binford6000: /* Hilfe bei der Fehlersuche */

{{Infobox Modul
|ModPurpose=Dialoge für Sofortnachrichten über TelegramBot, Jabber und WhatsApp
|ModType=h
|ModForumArea=Frontends
|ModTechName=76_msgDialog.pm
|ModOwner={{Link2FU|4106|igami}}
}}

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

== Konfiguration ==

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

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

=== msgConfig ===

Als erstes benötigt man ein definiertes msgConfig device:

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

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

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

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

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

=== Define ===

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

== Beispiele ==

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

== TelegramBot ==

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

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

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

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

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

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

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

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

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

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

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

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

[[Kategorie:Hilfsmodul]]

MsgDialog

2017-12-03T17:16:41Z

Binford6000: /* Hilfe bei der Fehlersuche */

{{Infobox Modul
|ModPurpose=Dialoge für Sofortnachrichten über TelegramBot, Jabber und WhatsApp
|ModType=h
|ModForumArea=Frontends
|ModTechName=76_msgDialog.pm
|ModOwner={{Link2FU|4106|igami}}
}}

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

== Konfiguration ==

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

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

=== msgConfig ===

Als erstes benötigt man ein definiertes msgConfig device:

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

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

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

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

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

=== Define ===

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

== Beispiele ==

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

== TelegramBot ==

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

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

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

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

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

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

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

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

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

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

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

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

[[Kategorie:Hilfsmodul]]

MsgDialog

2017-12-03T17:16:25Z

Binford6000: /* Das Attribut msgDialog_evalSpecials fehlt oder ist nicht korrekt gesetzt */

{{Infobox Modul
|ModPurpose=Dialoge für Sofortnachrichten über TelegramBot, Jabber und WhatsApp
|ModType=h
|ModForumArea=Frontends
|ModTechName=76_msgDialog.pm
|ModOwner={{Link2FU|4106|igami}}
}}

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

== Konfiguration ==

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

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

=== msgConfig ===

Als erstes benötigt man ein definiertes msgConfig device:

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

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

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

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

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

=== Define ===

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

== Beispiele ==

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

== TelegramBot ==

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

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

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

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

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

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

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

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

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

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

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

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

[[Kategorie:Hilfsmodul]]

MsgDialog

2017-12-03T17:15:31Z

Binford6000: /* Hilfe bei der Fehlersuche */

{{Infobox Modul
|ModPurpose=Dialoge für Sofortnachrichten über TelegramBot, Jabber und WhatsApp
|ModType=h
|ModForumArea=Frontends
|ModTechName=76_msgDialog.pm
|ModOwner={{Link2FU|4106|igami}}
}}

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

== Konfiguration ==

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

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

=== msgConfig ===

Als erstes benötigt man ein definiertes msgConfig device:

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

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

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

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

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

=== Define ===

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

== Beispiele ==

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

== TelegramBot ==

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

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

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

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

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

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

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

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

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

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

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

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

[[Kategorie:Hilfsmodul]]

MsgDialog

2017-11-12T08:02:33Z

Binford6000: /* ":" bei Inline Keyboards */

{{Infobox Modul
|ModPurpose=Dialoge für Sofortnachrichten über TelegramBot, Jabber und WhatsApp
|ModType=h
|ModForumArea=Frontends
|ModTechName=76_msgDialog.pm
|ModOwner={{Link2FU|4106|igami}}
}}

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

== Konfiguration ==

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

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

=== msgConfig ===

Als erstes benötigt man ein definiertes msgConfig device:

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

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

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

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

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

=== Define ===

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

== Beispiele ==

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

== TelegramBot ==

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

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

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

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

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

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

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

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

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

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

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

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

[[Kategorie:Hilfsmodul]]

MsgDialog

2017-11-12T07:58:35Z

Binford6000: /* Hilfe bei der Fehlersuche */

{{Infobox Modul
|ModPurpose=Dialoge für Sofortnachrichten über TelegramBot, Jabber und WhatsApp
|ModType=h
|ModForumArea=Frontends
|ModTechName=76_msgDialog.pm
|ModOwner={{Link2FU|4106|igami}}
}}

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

== Konfiguration ==

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

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

=== msgConfig ===

Als erstes benötigt man ein definiertes msgConfig device:

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

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

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

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

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

=== Define ===

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

== Beispiele ==

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

== TelegramBot ==

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

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

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

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

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

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

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

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

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

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

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

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

[[Kategorie:Hilfsmodul]]

MsgDialog

2017-11-12T07:46:58Z

Binford6000: /* Es werden keine Dialoge angezeigt */

{{Infobox Modul
|ModPurpose=Dialoge für Sofortnachrichten über TelegramBot, Jabber und WhatsApp
|ModType=h
|ModForumArea=Frontends
|ModTechName=76_msgDialog.pm
|ModOwner={{Link2FU|4106|igami}}
}}

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

== Konfiguration ==

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

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

=== msgConfig ===

Als erstes benötigt man ein definiertes msgConfig device:

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

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

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

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

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

=== Define ===

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

== Beispiele ==

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

== TelegramBot ==

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

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

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

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

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

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

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

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

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

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

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

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

[[Kategorie:Hilfsmodul]]

MsgDialog

2017-11-12T07:45:50Z

Binford6000: /* Define */

{{Infobox Modul
|ModPurpose=Dialoge für Sofortnachrichten über TelegramBot, Jabber und WhatsApp
|ModType=h
|ModForumArea=Frontends
|ModTechName=76_msgDialog.pm
|ModOwner={{Link2FU|4106|igami}}
}}

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

== Konfiguration ==

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

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

=== msgConfig ===

Als erstes benötigt man ein definiertes msgConfig device:

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

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

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

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

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

=== Define ===

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

== Beispiele ==

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

== TelegramBot ==

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

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

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

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

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

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

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

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

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

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

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

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

[[Kategorie:Hilfsmodul]]

MsgDialog

2017-11-12T07:44:55Z

Binford6000: /* Define */

{{Infobox Modul
|ModPurpose=Dialoge für Sofortnachrichten über TelegramBot, Jabber und WhatsApp
|ModType=h
|ModForumArea=Frontends
|ModTechName=76_msgDialog.pm
|ModOwner={{Link2FU|4106|igami}}
}}

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

== Konfiguration ==

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

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

=== msgConfig ===

Als erstes benötigt man ein definiertes msgConfig device:

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

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

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

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

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

=== Define ===

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

== Beispiele ==

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

== TelegramBot ==

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

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

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

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

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

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

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

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

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

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

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

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

[[Kategorie:Hilfsmodul]]

MsgDialog

2017-11-12T07:43:31Z

Binford6000: /* Define */

{{Infobox Modul
|ModPurpose=Dialoge für Sofortnachrichten über TelegramBot, Jabber und WhatsApp
|ModType=h
|ModForumArea=Frontends
|ModTechName=76_msgDialog.pm
|ModOwner={{Link2FU|4106|igami}}
}}

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

== Konfiguration ==

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

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

=== msgConfig ===

Als erstes benötigt man ein definiertes msgConfig device:

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

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

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

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

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

=== Define ===

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

== Beispiele ==

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

== TelegramBot ==

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

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

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

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

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

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

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

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

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

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

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

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

[[Kategorie:Hilfsmodul]]

MsgDialog

2017-11-12T07:42:52Z

Binford6000: /* msgConfig */

{{Infobox Modul
|ModPurpose=Dialoge für Sofortnachrichten über TelegramBot, Jabber und WhatsApp
|ModType=h
|ModForumArea=Frontends
|ModTechName=76_msgDialog.pm
|ModOwner={{Link2FU|4106|igami}}
}}

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

== Konfiguration ==

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

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

=== msgConfig ===

Als erstes benötigt man ein definiertes msgConfig device:

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

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

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

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

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

=== Define ===

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

<pre>
defmod meta_Dialog msgDialog {\
"%me%": {\
"match": "\/?(start|%me%)",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"{return('(' . join(') (', sort(split('\n', fhem('get TYPE=msgDialog:FILTER=NAME!=$SELF:FILTER=allowed=.*($recipient|everyone).* trigger')))) . ') ')}",\
"(abbrechen) ",\
"Ich kann folgendes für dich tun:"\
]\
},\
"abbrechen": {\
"match": "\/?abbrechen",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"(%me%) ",\
"Dialog abgebrochen."\
] \
},\
"beenden": {\
"match": "\/?beenden",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"(%me%) ",\
"Dialog beendet."\
]\
}\
}

attr meta_Dialog DbLogExclude .*
attr meta_Dialog allowed everyone
attr meta_Dialog room msg
</pre>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

== Beispiele ==

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

== TelegramBot ==

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

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

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

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

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

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

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

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

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

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

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

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

[[Kategorie:Hilfsmodul]]

MsgDialog

2017-11-10T18:10:43Z

Binford6000: /* Innerhalb eines Dialogs fehlen einzelne Menüeinträge */

{{Infobox Modul
|ModPurpose=Dialoge für Sofortnachrichten über TelegramBot, Jabber und WhatsApp
|ModType=h
|ModForumArea=Frontends
|ModTechName=76_msgDialog.pm
|ModOwner={{Link2FU|4106|igami}}
}}

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

== Konfiguration ==

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

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

=== msgConfig ===

Als erstes benötigt man ein definiertes msgConfig device:

<pre>
defmod myMsgConfig msgConfig
attr myMsgConfig msgDialog_evalSpecials me=<Aktivierungswort bzw. -Nachricht>
TelegramBot=<Name des TelegramBot-device>
attr myMsgConfig msgContactPush TelegramBot
attr myMsgConfig room msg
</pre>

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

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

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

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

=== Define ===

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

<pre>
defmod meta_Dialog msgDialog {\
"%me%": {\
"match": "\/?(start|%me%)",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"{return('(' . join(') (', sort(split('\n', fhem('get TYPE=msgDialog:FILTER=NAME!=$SELF:FILTER=allowed=.*($recipient|everyone).* trigger')))) . ') ')}",\
"(abbrechen) ",\
"Ich kann folgendes für dich tun:"\
]\
},\
"abbrechen": {\
"match": "\/?abbrechen",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"(%me%) ",\
"Dialog abgebrochen."\
] \
},\
"beenden": {\
"match": "\/?beenden",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"(%me%) ",\
"Dialog beendet."\
]\
}\
}

attr meta_Dialog DbLogExclude .*
attr meta_Dialog allowed everyone
attr meta_Dialog room msg
</pre>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

== Beispiele ==

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

== TelegramBot ==

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

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

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

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

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

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

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

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

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

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

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

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

[[Kategorie:Hilfsmodul]]

MsgDialog

2017-11-10T18:08:06Z

Binford6000: /* Das Attribut msgDialog_evalSpecials fehlt oder ist nicht korrekt gesetzt */

{{Infobox Modul
|ModPurpose=Dialoge für Sofortnachrichten über TelegramBot, Jabber und WhatsApp
|ModType=h
|ModForumArea=Frontends
|ModTechName=76_msgDialog.pm
|ModOwner={{Link2FU|4106|igami}}
}}

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

== Konfiguration ==

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

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

=== msgConfig ===

Als erstes benötigt man ein definiertes msgConfig device:

<pre>
defmod myMsgConfig msgConfig
attr myMsgConfig msgDialog_evalSpecials me=<Aktivierungswort bzw. -Nachricht>
TelegramBot=<Name des TelegramBot-device>
attr myMsgConfig msgContactPush TelegramBot
attr myMsgConfig room msg
</pre>

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

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

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

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

=== Define ===

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

<pre>
defmod meta_Dialog msgDialog {\
"%me%": {\
"match": "\/?(start|%me%)",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"{return('(' . join(') (', sort(split('\n', fhem('get TYPE=msgDialog:FILTER=NAME!=$SELF:FILTER=allowed=.*($recipient|everyone).* trigger')))) . ') ')}",\
"(abbrechen) ",\
"Ich kann folgendes für dich tun:"\
]\
},\
"abbrechen": {\
"match": "\/?abbrechen",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"(%me%) ",\
"Dialog abgebrochen."\
] \
},\
"beenden": {\
"match": "\/?beenden",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"(%me%) ",\
"Dialog beendet."\
]\
}\
}

attr meta_Dialog DbLogExclude .*
attr meta_Dialog allowed everyone
attr meta_Dialog room msg
</pre>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

== Beispiele ==

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

== TelegramBot ==

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

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

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

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

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

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

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

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

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

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

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

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

[[Kategorie:Hilfsmodul]]

MsgDialog

2017-11-10T18:06:58Z

Binford6000: /* Hilfe bei der Fehlersuche */

{{Infobox Modul
|ModPurpose=Dialoge für Sofortnachrichten über TelegramBot, Jabber und WhatsApp
|ModType=h
|ModForumArea=Frontends
|ModTechName=76_msgDialog.pm
|ModOwner={{Link2FU|4106|igami}}
}}

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

== Konfiguration ==

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

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

=== msgConfig ===

Als erstes benötigt man ein definiertes msgConfig device:

<pre>
defmod myMsgConfig msgConfig
attr myMsgConfig msgDialog_evalSpecials me=<Aktivierungswort bzw. -Nachricht>
TelegramBot=<Name des TelegramBot-device>
attr myMsgConfig msgContactPush TelegramBot
attr myMsgConfig room msg
</pre>

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

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

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

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

=== Define ===

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

<pre>
defmod meta_Dialog msgDialog {\
"%me%": {\
"match": "\/?(start|%me%)",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"{return('(' . join(') (', sort(split('\n', fhem('get TYPE=msgDialog:FILTER=NAME!=$SELF:FILTER=allowed=.*($recipient|everyone).* trigger')))) . ') ')}",\
"(abbrechen) ",\
"Ich kann folgendes für dich tun:"\
]\
},\
"abbrechen": {\
"match": "\/?abbrechen",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"(%me%) ",\
"Dialog abgebrochen."\
] \
},\
"beenden": {\
"match": "\/?beenden",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"(%me%) ",\
"Dialog beendet."\
]\
}\
}

attr meta_Dialog DbLogExclude .*
attr meta_Dialog allowed everyone
attr meta_Dialog room msg
</pre>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

=== Das Attribut msgDialog_evalSpecials fehlt oder ist nicht korrekt gesetzt ===
Dieses Attribut gehört dem msgConfig device und muss wie in 2.3 zu lesen
korrekt befüllt werden.

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

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

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

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

== Beispiele ==

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

== TelegramBot ==

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

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

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

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

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

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

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

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

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

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

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

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

[[Kategorie:Hilfsmodul]]

MsgDialog

2017-11-10T18:02:19Z

Binford6000: /* Hilfe bei der Fehlersuche */

{{Infobox Modul
|ModPurpose=Dialoge für Sofortnachrichten über TelegramBot, Jabber und WhatsApp
|ModType=h
|ModForumArea=Frontends
|ModTechName=76_msgDialog.pm
|ModOwner={{Link2FU|4106|igami}}
}}

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

== Konfiguration ==

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

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

=== msgConfig ===

Als erstes benötigt man ein definiertes msgConfig device:

<pre>
defmod myMsgConfig msgConfig
attr myMsgConfig msgDialog_evalSpecials me=<Aktivierungswort bzw. -Nachricht>
TelegramBot=<Name des TelegramBot-device>
attr myMsgConfig msgContactPush TelegramBot
attr myMsgConfig room msg
</pre>

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

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

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

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

=== Define ===

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

<pre>
defmod meta_Dialog msgDialog {\
"%me%": {\
"match": "\/?(start|%me%)",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"{return('(' . join(') (', sort(split('\n', fhem('get TYPE=msgDialog:FILTER=NAME!=$SELF:FILTER=allowed=.*($recipient|everyone).* trigger')))) . ') ')}",\
"(abbrechen) ",\
"Ich kann folgendes für dich tun:"\
]\
},\
"abbrechen": {\
"match": "\/?abbrechen",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"(%me%) ",\
"Dialog abgebrochen."\
] \
},\
"beenden": {\
"match": "\/?beenden",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"(%me%) ",\
"Dialog beendet."\
]\
}\
}

attr meta_Dialog DbLogExclude .*
attr meta_Dialog allowed everyone
attr meta_Dialog room msg
</pre>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

== Beispiele ==

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

== TelegramBot ==

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

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

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

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

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

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

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

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

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

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

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

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

[[Kategorie:Hilfsmodul]]

MsgDialog

2017-11-10T17:58:06Z

Binford6000: /* Hilfe bei der Fehlersuche */

{{Infobox Modul
|ModPurpose=Dialoge für Sofortnachrichten über TelegramBot, Jabber und WhatsApp
|ModType=h
|ModForumArea=Frontends
|ModTechName=76_msgDialog.pm
|ModOwner={{Link2FU|4106|igami}}
}}

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

== Konfiguration ==

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

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

=== msgConfig ===

Als erstes benötigt man ein definiertes msgConfig device:

<pre>
defmod myMsgConfig msgConfig
attr myMsgConfig msgDialog_evalSpecials me=<Aktivierungswort bzw. -Nachricht>
TelegramBot=<Name des TelegramBot-device>
attr myMsgConfig msgContactPush TelegramBot
attr myMsgConfig room msg
</pre>

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

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

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

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

=== Define ===

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

<pre>
defmod meta_Dialog msgDialog {\
"%me%": {\
"match": "\/?(start|%me%)",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"{return('(' . join(') (', sort(split('\n', fhem('get TYPE=msgDialog:FILTER=NAME!=$SELF:FILTER=allowed=.*($recipient|everyone).* trigger')))) . ') ')}",\
"(abbrechen) ",\
"Ich kann folgendes für dich tun:"\
]\
},\
"abbrechen": {\
"match": "\/?abbrechen",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"(%me%) ",\
"Dialog abgebrochen."\
] \
},\
"beenden": {\
"match": "\/?beenden",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"(%me%) ",\
"Dialog beendet."\
]\
}\
}

attr meta_Dialog DbLogExclude .*
attr meta_Dialog allowed everyone
attr meta_Dialog room msg
</pre>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

== Beispiele ==

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

== TelegramBot ==

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

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

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

Um eine Nachricht bei Telegram zu verändern, gibt es den Befehl "queryEditInline".
Dafür wird die MsgId von der Nachricht benötigt. Das erledigt ein notify, welches die msgId pro Peer abspeichert:

<pre>
defmod sentMsgIdByPeerId notify .+:sentMsgId.+ {\
return unless($TYPE eq "TelegramBot");;\
\
my $dev_hash = $defs{$NAME};;\
my $sentMsgId = ReadingsVal($NAME, "sentMsgId", "");;\
my $sentMsgPeerId = ReadingsVal($NAME, "sentMsgPeerId", "");;\
my ($contact) = devspec2array("TYPE=(ROOMMATE|GUEST):FILTER=msgContactPush=.*$sentMsgPeerId.*");;\
\
readingsSingleUpdate($dev_hash, "$contact\_sentMsgId", $sentMsgId, 1);;\
}
attr sentMsgIdByPeerId devStateIcon {ReadingsVal($name, "state", "inactive") eq "active" ? ".*:ios-on-blue:inactive" : ".*:ios-off:active"}
attr sentMsgIdByPeerId icon audio_mic
attr sentMsgIdByPeerId room msg
</pre>

Danach wird der Message-Befehl von
<pre>
set <TelegramBot> message
</pre>
auf
<pre>
set <TelegramBot> queryEditInline
</pre>
geändert. Dafür wird ein [[cmdalias]] verwendet:

<pre>
defmod message2queryEditInline cmdalias set .+ message (.|\n)+ AS {\
my ($NAME, $cmd, $message) = split(/[\s]+/, $EVENT, 3);;\
my $TYPE = InternalVal($NAME, "TYPE", "");;\
(my $recipient, $message) = ($message =~ m/(@\S+)? (.+)/s);;\
\
if($TYPE eq "TelegramBot" && $recipient){\
my ($contact) = devspec2array("TYPE=(ROOMMATE|GUEST):FILTER=msgContactPush=.*$recipient.*");;\
my $sentMsgId = ReadingsVal($NAME, "$contact\_sentMsgId", "");;\
\
if($sentMsgId ne ""){\
fhem("set $NAME queryEditInline $sentMsgId $recipient $message");;\
}\
else{\
fhem("set $NAME queryInline $recipient $message");;\
}\
}\
else{\
fhem("set $EVENT");;\
}\
}
attr message2queryEditInline room msg
</pre>

Um wieder zurück zum normalen Keyboard zu gelangen genügt es, das notify und den cmdAlias zu deaktivieren.
Das kann komfortabel über ein notify und einen dummy erledigt werden:
<pre>
defmod inline_normal.NOT notify inline_normal.DUM:.* {\
if ("$EVENT" =~ "on") {\
fhem "set sentMsgIdByPeerId active;; attr message2queryEditInline disable 0";;\
} \
elsif ("$EVENT" =~ "off") {\
fhem "set sentMsgIdByPeerId inactive;; attr message2queryEditInline disable 1";;\
}\
}
</pre>

Weitere Infos zum Thema Inline Keyboard sind in der Antwort #10 im Forum zu finden (siehe Link unten).

== JABBER ==
Hier wird die Verwendung mit Jabber beschrieben...

== WhatsApp ==
Hier wird die Verwendung mit yowsup/WhatsApp beschrieben...

== Links ==
* Thread über das Modul im {{Link2Forum|Topic=77297|LinkText=FHEM Forum}}

[[Kategorie:Hilfsmodul]]

MsgDialog

2017-11-10T17:47:05Z

Binford6000: /* Innerhalb eines Dialogs fehlen einzelne Menüeinträge */

{{Infobox Modul
|ModPurpose=Dialoge für Sofortnachrichten über TelegramBot, Jabber und WhatsApp
|ModType=h
|ModForumArea=Frontends
|ModTechName=76_msgDialog.pm
|ModOwner={{Link2FU|4106|igami}}
}}

== Zielsetzung ==
Ein zentrale Anforderung an die Haus-Automation ist die Kommunikation mit den Anwendern. Fast jeder Anwender möchte über bestimmte Ereignisse informiert werden und Einstellungen vornehmen. FHEM bietet schon seit längerem die Unterstützung für verschiedene Messaging Dienste an.
Mit dem msgDialog Modul können vordefinierte Dialoge erstellt werden. Die Kommunikation erfolgt dabei über den [[msg]] Befehl welcher zurzeit die bidirektionale Kommunikation über [[TelegramBot]], [[Jabber]] und [[yowsup]] (WhatsApp) unterstützt. Eingehende Nachrichten werden einem ROMMATE oder GUEST zugeordnet. Darüber werden auch die Berechtigungen für die einzelnen Dialoge festgelegt.
Die grundlegende Bedienung wird in diesem '''[https://youtu.be/yiCOTeR1YVQ Video]''' am Beispiel von TelegramBot gezeigt.

== Konfiguration ==

=== Voraussetzungen ===
Für dieses Modul wird das Perl JSON Modul benötigt. Auf einem Debian-basierten System (z.B RaspberryPI o.ä.) kann man das mit dem folgenden Befehl installieren:
<pre>
sudo apt-get install libjson-perl
</pre>

=== Hinweis zu den Code Beispielen ===
Es handelt sich bei den Beispielen um eine Raw definition, siehe auch [[Import_von_Code_Snippets]]

=== msgConfig ===

Als erstes benötigt man ein definiertes msgConfig device:

<pre>
defmod myMsgConfig msgConfig
attr myMsgConfig msgDialog_evalSpecials me=<Aktivierungswort bzw. -Nachricht>
TelegramBot=<Name des TelegramBot-device>
attr myMsgConfig msgContactPush TelegramBot
attr myMsgConfig room msg
</pre>

Falls bereits vorhanden, müssen natürlich nur die fehlenden Attribute gesetzt werden.

;msgDialog_evalSpecials
:key1=value1 key2=value2 ... Leerzeichen getrennte Liste von Name=Wert Paaren. Wert kann Leerzeichen enthalten, falls es in "" oder {} eingeschlossen :ist. Wert wird als perl-Ausdruck ausgewertet, falls es in {} eingeschlossen ist. In der DEF werden %Name% Zeichenketten durch den zugehörigen Wert :ersetzt. Wenn der selbe Name im msgConfig und msgDialog definiert wurde, wird der Wert aus msgDialog verwendet.

;msgDialog_msgCommand <command>
:Befehl zum Versenden einer Nachricht. Die Vorgabe ist "msg push \@$recipients $message". Wenn nicht gesetzt, wird die Vorgabe verwendet.

=== ROOMMATE / GUEST ===
Für jeden Dialog kann festgelegt werden welche Person dazu berechtigt ist. Dazu sind Geräte vom Typ ROOMMATE oder GUEST mit definiertem msgContactPush Attribut erforderlich. Es ist darauf zu achten, dass das Reading fhemMsgRcvPush ein Event erzeugt. Siehe auch Attribut "allowed" in msgDialog.

=== Define ===

Definition des metaDialogs:
Zur Auflistung aller berechtigten Dialoge dient - was sonst - ein Dialog!

<pre>
defmod meta_Dialog msgDialog {\
"%me%": {\
"match": "\/?(start|%me%)",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"{return('(' . join(') (', sort(split('\n', fhem('get TYPE=msgDialog:FILTER=NAME!=$SELF:FILTER=allowed=.*($recipient|everyone).* trigger')))) . ') ')}",\
"(abbrechen) ",\
"Ich kann folgendes für dich tun:"\
]\
},\
"abbrechen": {\
"match": "\/?abbrechen",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"(%me%) ",\
"Dialog abgebrochen."\
] \
},\
"beenden": {\
"match": "\/?beenden",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"(%me%) ",\
"Dialog beendet."\
]\
}\
}

attr meta_Dialog DbLogExclude .*
attr meta_Dialog allowed everyone
attr meta_Dialog room msg
</pre>

Aufgrund der Komplexität eines Dialogs mit JSON ist es am praktikabelsten, zunächst einen leeren Dialog zu definieren:
<pre>
define <name> msgDialog {}
</pre>

Anschließend kann die '''DEF''' in der Detail-Ansicht des Dialog-Device bearbeitet werden. Jeder Dialog basiert auf der folgenden Struktur von einfach bis komplex.

<pre>
{
"<TRIGGER>": {
"match": "<regex>",
"setOnly": (true|false),
"commands": "(fhem command|{perl code})",
"message": [
"{perl code}",
"text"
],
"<NEXT TRIGGER 1>": {
...
},
"<NEXT TRIGGER 2>": {
...
}
}
}
</pre>

Um den JSON-Teil der Dialoge zu testen, empfiehlt sich ein Besuch auf https://jsonlint.com/
Hier kann der selbst geschriebene JSON-Code validiert werden.

;TRIGGER
:Kann ein beliebiger Text sein. Es wird geprüft ob die eingehende Nachricht damit übereinstimmt. Falls ja, wird der Dialog an dieser Stelle fortgesetzt.

;match
:Wenn nicht nur genau eine Nachricht zugelassen werden soll, kann noch eine regex angegeben werden. Die regex muss auf die gesamte eingehnde Nachricht :zutreffen.

;setOnly
:Kann optional auf true oder false gestellt werden. In beiden fällen wird der TRIGGER dann nicht bei "get <name> trigger" zurück gegeben.
:Wenn setOnly auf "true" gestellt wird, kann der Dialog an dieser Stelle nicht durch eingehende Nachrichten ausgelöst werden, sondern nur über "get <name> say TRIGGER". Dies kann dazu genutzt werden um einen Dialog aus :FHEM heraus zu initiieren.

;commands
:Kann einen einzelnen oder mehrere Befehle enthalten:
<pre>
"commands":
"single command"
"commands": [
"command 1",
"command 2",
"{perl command}"
]
</pre>

;message
:Kann einen einzelnen oder mehrere Textte enthalten die mit einen Zeilenumbruch verbunden werden:
<pre>
"message": "text"
</pre>
<pre>
"message": [
"text 1",
"text 2",
"{return from perl command}"
]
</pre>

Bei mehrstufigen Dialogen wird diese Struktur ineinander verschachtelt angegeben.
Es werden Variablen und Platzhalter, welche unter dem Attribut evalSpecials definiert werden, ausgewertet.

=== Variablen ===
*$SELF: Eigenname des msgDialog
*$message: eingegangene Nachricht
*$recipient: Name des Dialogpartners

=== Attribute ===
*allowed: Liste mit allen RESIDENTS und ROOMMATE die für diesen Dialog berechtigt sind.
*disable: [0|1] Dialog ist aktiviert|deaktiviert.
*disabledForIntervals: HH:MM-HH:MM HH:MM-HH-MM ...
*evalSpecials: key1=value1 key2=value2 ...Leerzeichen getrennte Liste von Name=Wert Paaren. Wert kann Leerzeichen enthalten, falls es in "" oder {} eingeschlossen ist. Wert wird als perl-Ausdruck ausgewertet, falls es in {} eingeschlossen ist. In der DEF werden %Name% Zeichenketten durch den zugehörigen Wert ersetzt. Dieses Attribut ist als "msgDialog_evalSpecials" im msgConfig Gerät vorhanden. Wenn der selbe Name im msgConfig und msgDialog definiert wurde, wird der Wert aus msgDialog verwendet.
*msgCommand <command>: Befehl der zum Versenden einer Nachricht verwendet wird. Die Vorgabe ist "msg push \@$recipients $message" Dieses Attribut ist als "msgDialog_msgCommand" im msgConfig Gerät vorhanden.

=== set ===
*reset: Setzt den Dialog für alle Benutzer zurück.
*say [@<recipient1>[,<recipient2>,...]] <TRIGGER>[|<NEXT TRIGGER>|...]: Der Dialog wird für alle angegeben Empänger an der angegeben Stelle fortgeführt. Sind keine Empfänger angegeben wird der Dialog für alle unter dem Attribut allowed angegebenen Empfänger fortgeführt.
*updateAllowed: Aktualisiert die Auswahl für das Attribut allowed.

=== get ===
*trigger: Listet alle TRIGGER der ersten Ebene auf bei denen nicht setOnly angegeben ist.

=== READINGS ===
*$recipient_history: Durch | getrennte Liste von TRIGGER um den aktuellen Zustand des Dialogs zu sichern. Für jeden Dialogpartner wird ein Reading angelegt. Wenn der Dialog beendet ist wird das Reading zurückgesetzt.

== Hilfe bei der Fehlersuche ==
Hier entsteht eine Sammlung von Tipps bei der Fehlersuche. Die meisten dieser "Stolpersteine"
entstehen häufig bei der Erstellung eines ersten eigenen Dialoges.

=== Es werden keine Dialoge angezeigt ===
Ohne die Angabe einer normalen Nachricht wird kein Dialog angezeigt:
<pre>
"message": [
"(Lampen einschalten) ",
"(Lampen ausschalten) ",
"(zurück:%me%) ",
],
</pre>
Erst mit der Nachricht "Möchtest Du Lampen ein oder ausschalten?" erscheint der Dialog:
<pre>
"message": [
"(Lampen einschalten) ",
"(Lampen ausschalten) ",
"(zurück:%me%) ",
"Möchtest Du Lampen ein oder ausschalten?"
],
</pre>

=== Innerhalb eines Dialogs fehlen einzelne Menüeinträge ===
Fehlen einzelne Menüeinträge innerhalb eines Dialogs, liegt das meistens an einem
fehlenden Leerzeichen:
<pre>
"message": [
"(Lampen einschalten)",
"(Lampen ausschalten) ",
"(zurück:%me%) ",
],
</pre>
Bei "Lampen ausschalten" ist dagegen korrekt ein Leerzeichen zu sehen und somit auch der Menüeintrag im Dialog.

== Beispiele ==

==== Programmierung der Waschmaschine ====
Das ist ein Beispiel zur Programmierung einer Waschmaschine wie auch oben im Video zu sehen:
<pre>
defmod Waschmaschine_Dialog msgDialog { "Waschmaschine": {\
"message": [\
"{return('(Zeitprogramm stoppen) ') if(ReadingsVal('%controlUnit%', 'controlMode', '') eq 'auto')}",\
"{return('(programmieren) ') if(ReadingsVal('%actor%', 'state', '') ne 'on')}",\
"{return('(einschalten) ') if(ReadingsVal('%actor%', 'state', '') ne 'on')}",\
"(Verlaufsdiagramm) ",\
"(abbrechen) ",\
"{return('Waschmaschine: ' . (ReadingsVal('%actor%', 'state', '') eq 'on' ? 'eingeschaltet' : 'ausgeschaltet'))}",\
"{return('Modus: ' . (ReadingsVal('%controlUnit%', 'controlMode', '') eq 'auto' ? 'Automatik' : 'Manuell (' . ReadingsVal('%controlUnit%', 'time', '') . ')'))}"\
],\
"Zeitprogramm stoppen": {\
"commands": "set %controlUnit% controlMode manual",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Das Zeitprogramm wurde gestoppt."\
]\
},\
"programmieren": {\
"message": [\
"(bestätigen|zurück|abbrechen) ",\
"( 00:00 | 00:15 | 00:30 | 00:45 ) ",\
"( 01:00 | 01:15 | 01:30 | 01:45 ) ",\
"( 02:00 | 02:15 | 02:30 | 02:45 ) ",\
"( 03:00 | 03:15 | 03:30 | 03:45 ) ",\
"( 04:00 | 04:15 | 04:30 | 04:45 ) ",\
"( 05:00 | 05:15 | 05:30 | 05:45 ) ",\
"( 06:00 | 06:15 | 06:30 | 06:45 ) ",\
"( 07:00 | 07:15 | 07:30 | 07:45 ) ",\
"( 08:00 | 08:15 | 08:30 | 08:45 ) ",\
"( 09:00 | 09:15 | 09:30 | 09:45 ) ",\
"( 10:00 | 10:15 | 10:30 | 10:45 ) ",\
"( 11:00 | 11:15 | 11:30 | 11:45 ) ",\
"( 12:00 | 12:15 | 12:30 | 12:45 ) ",\
"( 13:00 | 13:15 | 13:30 | 13:45 ) ",\
"( 14:00 | 14:15 | 14:30 | 14:45 ) ",\
"( 15:00 | 15:15 | 15:30 | 15:45 ) ",\
"( 16:00 | 16:15 | 16:30 | 16:45 ) ",\
"( 17:00 | 17:15 | 17:30 | 17:45 ) ",\
"( 18:00 | 18:15 | 18:30 | 18:45 ) ",\
"( 19:00 | 19:15 | 19:30 | 19:45 ) ",\
"( 20:00 | 20:15 | 20:30 | 20:45 ) ",\
"( 21:00 | 21:15 | 21:30 | 21:45 ) ",\
"( 22:00 | 22:15 | 22:30 | 22:45 ) ",\
"( 23:00 | 23:15 | 23:30 | 23:45 ) ",\
"Wann soll die Wäsche fertig sein?",\
"Bitte Uhrzeit in HH:MM angeben.",\
"Aktuell ist [%controlUnit%:time] Uhr eingestellt."\
],\
"Uhrzeit": {\
"match": " ?([0-1][0-9]|2[0-3]):[0-5][0-9] ?",\
"commands": [\
"set %controlUnit% time $message",\
"set $SELF say @$recipient Waschmaschine|programmieren|bestätigen"\
]\
},\
"bestätigen": {\
"commands": "set %controlUnit% controlMode auto",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Das Zeitprogramm wurde eingestellt.",\
"Die Wäsche wird voraussichtlich um [%controlUnit%:time] Uhr fertig sein.",\
"Bitte die Waschmaschine vorbereiten."\
]\
}\
},\
"einschalten": {\
"commands": [\
"set %controlUnit% controlMode manual",\
"set %actor% on"\
]\
},\
"Verlaufsdiagramm": {\
"commands": "set %TelegramBot% cmdSend {plotAsPng('%plot%')}",\
"message": "TelegramBot_MTYPE=queryInline (%me%) $message"\
}\
},\
"auto": {\
"setOnly": true,\
"commands": [\
"set %actor% on",\
"set %controlUnit% controlMode manual"\
],\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine wurde automatisch eingeschaltet."\
]\
},\
"manual": {\
"setOnly": true,\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine wurde manuell eingeschaltet."\
]\
},\
"done": {\
"setOnly": true,\
"commands": "set %actor% off",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine ist fertig."\
]\
}\
}
attr Waschmaschine_Dialog evalSpecials actor=HM_2C10D8_Sw\
controlUnit=Waschkeller_washer_controlUnit\
plot=Waschkeller_washer_SVG
</pre>

== TelegramBot ==

In Telegram gibt es die Möglichkeit die Art des Keyboards zu ändern. Links das normale Keyboard, rechts das Inline Keyboard.

[[Datei:76msgDialog menu.png|Normales Keyboard]] [[Datei:76msgDialog menu inline.PNG|Inline Keyboard]]

In diesem '''[https://youtu.be/oRDy2918mVI Video]''' wird Telegram mit einem Inline Keyboard verwendet.

Um eine Nachricht bei Telegram zu verändern, gibt es den Befehl "queryEditInline".
Dafür wird die MsgId von der Nachricht benötigt. Das erledigt ein notify, welches die msgId pro Peer abspeichert:

<pre>
defmod sentMsgIdByPeerId notify .+:sentMsgId.+ {\
return unless($TYPE eq "TelegramBot");;\
\
my $dev_hash = $defs{$NAME};;\
my $sentMsgId = ReadingsVal($NAME, "sentMsgId", "");;\
my $sentMsgPeerId = ReadingsVal($NAME, "sentMsgPeerId", "");;\
my ($contact) = devspec2array("TYPE=(ROOMMATE|GUEST):FILTER=msgContactPush=.*$sentMsgPeerId.*");;\
\
readingsSingleUpdate($dev_hash, "$contact\_sentMsgId", $sentMsgId, 1);;\
}
attr sentMsgIdByPeerId devStateIcon {ReadingsVal($name, "state", "inactive") eq "active" ? ".*:ios-on-blue:inactive" : ".*:ios-off:active"}
attr sentMsgIdByPeerId icon audio_mic
attr sentMsgIdByPeerId room msg
</pre>

Danach wird der Message-Befehl von
<pre>
set <TelegramBot> message
</pre>
auf
<pre>
set <TelegramBot> queryEditInline
</pre>
geändert. Dafür wird ein [[cmdalias]] verwendet:

<pre>
defmod message2queryEditInline cmdalias set .+ message (.|\n)+ AS {\
my ($NAME, $cmd, $message) = split(/[\s]+/, $EVENT, 3);;\
my $TYPE = InternalVal($NAME, "TYPE", "");;\
(my $recipient, $message) = ($message =~ m/(@\S+)? (.+)/s);;\
\
if($TYPE eq "TelegramBot" && $recipient){\
my ($contact) = devspec2array("TYPE=(ROOMMATE|GUEST):FILTER=msgContactPush=.*$recipient.*");;\
my $sentMsgId = ReadingsVal($NAME, "$contact\_sentMsgId", "");;\
\
if($sentMsgId ne ""){\
fhem("set $NAME queryEditInline $sentMsgId $recipient $message");;\
}\
else{\
fhem("set $NAME queryInline $recipient $message");;\
}\
}\
else{\
fhem("set $EVENT");;\
}\
}
attr message2queryEditInline room msg
</pre>

Um wieder zurück zum normalen Keyboard zu gelangen genügt es, das notify und den cmdAlias zu deaktivieren.
Das kann komfortabel über ein notify und einen dummy erledigt werden:
<pre>
defmod inline_normal.NOT notify inline_normal.DUM:.* {\
if ("$EVENT" =~ "on") {\
fhem "set sentMsgIdByPeerId active;; attr message2queryEditInline disable 0";;\
} \
elsif ("$EVENT" =~ "off") {\
fhem "set sentMsgIdByPeerId inactive;; attr message2queryEditInline disable 1";;\
}\
}
</pre>

Weitere Infos zum Thema Inline Keyboard sind in der Antwort #10 im Forum zu finden (siehe Link unten).

== JABBER ==
Hier wird die Verwendung mit Jabber beschrieben...

== WhatsApp ==
Hier wird die Verwendung mit yowsup/WhatsApp beschrieben...

== Links ==
* Thread über das Modul im {{Link2Forum|Topic=77297|LinkText=FHEM Forum}}

[[Kategorie:Hilfsmodul]]

MsgDialog

2017-11-10T17:46:26Z

Binford6000: /* Hilfe bei der Fehlersuche */

{{Infobox Modul
|ModPurpose=Dialoge für Sofortnachrichten über TelegramBot, Jabber und WhatsApp
|ModType=h
|ModForumArea=Frontends
|ModTechName=76_msgDialog.pm
|ModOwner={{Link2FU|4106|igami}}
}}

== Zielsetzung ==
Ein zentrale Anforderung an die Haus-Automation ist die Kommunikation mit den Anwendern. Fast jeder Anwender möchte über bestimmte Ereignisse informiert werden und Einstellungen vornehmen. FHEM bietet schon seit längerem die Unterstützung für verschiedene Messaging Dienste an.
Mit dem msgDialog Modul können vordefinierte Dialoge erstellt werden. Die Kommunikation erfolgt dabei über den [[msg]] Befehl welcher zurzeit die bidirektionale Kommunikation über [[TelegramBot]], [[Jabber]] und [[yowsup]] (WhatsApp) unterstützt. Eingehende Nachrichten werden einem ROMMATE oder GUEST zugeordnet. Darüber werden auch die Berechtigungen für die einzelnen Dialoge festgelegt.
Die grundlegende Bedienung wird in diesem '''[https://youtu.be/yiCOTeR1YVQ Video]''' am Beispiel von TelegramBot gezeigt.

== Konfiguration ==

=== Voraussetzungen ===
Für dieses Modul wird das Perl JSON Modul benötigt. Auf einem Debian-basierten System (z.B RaspberryPI o.ä.) kann man das mit dem folgenden Befehl installieren:
<pre>
sudo apt-get install libjson-perl
</pre>

=== Hinweis zu den Code Beispielen ===
Es handelt sich bei den Beispielen um eine Raw definition, siehe auch [[Import_von_Code_Snippets]]

=== msgConfig ===

Als erstes benötigt man ein definiertes msgConfig device:

<pre>
defmod myMsgConfig msgConfig
attr myMsgConfig msgDialog_evalSpecials me=<Aktivierungswort bzw. -Nachricht>
TelegramBot=<Name des TelegramBot-device>
attr myMsgConfig msgContactPush TelegramBot
attr myMsgConfig room msg
</pre>

Falls bereits vorhanden, müssen natürlich nur die fehlenden Attribute gesetzt werden.

;msgDialog_evalSpecials
:key1=value1 key2=value2 ... Leerzeichen getrennte Liste von Name=Wert Paaren. Wert kann Leerzeichen enthalten, falls es in "" oder {} eingeschlossen :ist. Wert wird als perl-Ausdruck ausgewertet, falls es in {} eingeschlossen ist. In der DEF werden %Name% Zeichenketten durch den zugehörigen Wert :ersetzt. Wenn der selbe Name im msgConfig und msgDialog definiert wurde, wird der Wert aus msgDialog verwendet.

;msgDialog_msgCommand <command>
:Befehl zum Versenden einer Nachricht. Die Vorgabe ist "msg push \@$recipients $message". Wenn nicht gesetzt, wird die Vorgabe verwendet.

=== ROOMMATE / GUEST ===
Für jeden Dialog kann festgelegt werden welche Person dazu berechtigt ist. Dazu sind Geräte vom Typ ROOMMATE oder GUEST mit definiertem msgContactPush Attribut erforderlich. Es ist darauf zu achten, dass das Reading fhemMsgRcvPush ein Event erzeugt. Siehe auch Attribut "allowed" in msgDialog.

=== Define ===

Definition des metaDialogs:
Zur Auflistung aller berechtigten Dialoge dient - was sonst - ein Dialog!

<pre>
defmod meta_Dialog msgDialog {\
"%me%": {\
"match": "\/?(start|%me%)",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"{return('(' . join(') (', sort(split('\n', fhem('get TYPE=msgDialog:FILTER=NAME!=$SELF:FILTER=allowed=.*($recipient|everyone).* trigger')))) . ') ')}",\
"(abbrechen) ",\
"Ich kann folgendes für dich tun:"\
]\
},\
"abbrechen": {\
"match": "\/?abbrechen",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"(%me%) ",\
"Dialog abgebrochen."\
] \
},\
"beenden": {\
"match": "\/?beenden",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"(%me%) ",\
"Dialog beendet."\
]\
}\
}

attr meta_Dialog DbLogExclude .*
attr meta_Dialog allowed everyone
attr meta_Dialog room msg
</pre>

Aufgrund der Komplexität eines Dialogs mit JSON ist es am praktikabelsten, zunächst einen leeren Dialog zu definieren:
<pre>
define <name> msgDialog {}
</pre>

Anschließend kann die '''DEF''' in der Detail-Ansicht des Dialog-Device bearbeitet werden. Jeder Dialog basiert auf der folgenden Struktur von einfach bis komplex.

<pre>
{
"<TRIGGER>": {
"match": "<regex>",
"setOnly": (true|false),
"commands": "(fhem command|{perl code})",
"message": [
"{perl code}",
"text"
],
"<NEXT TRIGGER 1>": {
...
},
"<NEXT TRIGGER 2>": {
...
}
}
}
</pre>

Um den JSON-Teil der Dialoge zu testen, empfiehlt sich ein Besuch auf https://jsonlint.com/
Hier kann der selbst geschriebene JSON-Code validiert werden.

;TRIGGER
:Kann ein beliebiger Text sein. Es wird geprüft ob die eingehende Nachricht damit übereinstimmt. Falls ja, wird der Dialog an dieser Stelle fortgesetzt.

;match
:Wenn nicht nur genau eine Nachricht zugelassen werden soll, kann noch eine regex angegeben werden. Die regex muss auf die gesamte eingehnde Nachricht :zutreffen.

;setOnly
:Kann optional auf true oder false gestellt werden. In beiden fällen wird der TRIGGER dann nicht bei "get <name> trigger" zurück gegeben.
:Wenn setOnly auf "true" gestellt wird, kann der Dialog an dieser Stelle nicht durch eingehende Nachrichten ausgelöst werden, sondern nur über "get <name> say TRIGGER". Dies kann dazu genutzt werden um einen Dialog aus :FHEM heraus zu initiieren.

;commands
:Kann einen einzelnen oder mehrere Befehle enthalten:
<pre>
"commands":
"single command"
"commands": [
"command 1",
"command 2",
"{perl command}"
]
</pre>

;message
:Kann einen einzelnen oder mehrere Textte enthalten die mit einen Zeilenumbruch verbunden werden:
<pre>
"message": "text"
</pre>
<pre>
"message": [
"text 1",
"text 2",
"{return from perl command}"
]
</pre>

Bei mehrstufigen Dialogen wird diese Struktur ineinander verschachtelt angegeben.
Es werden Variablen und Platzhalter, welche unter dem Attribut evalSpecials definiert werden, ausgewertet.

=== Variablen ===
*$SELF: Eigenname des msgDialog
*$message: eingegangene Nachricht
*$recipient: Name des Dialogpartners

=== Attribute ===
*allowed: Liste mit allen RESIDENTS und ROOMMATE die für diesen Dialog berechtigt sind.
*disable: [0|1] Dialog ist aktiviert|deaktiviert.
*disabledForIntervals: HH:MM-HH:MM HH:MM-HH-MM ...
*evalSpecials: key1=value1 key2=value2 ...Leerzeichen getrennte Liste von Name=Wert Paaren. Wert kann Leerzeichen enthalten, falls es in "" oder {} eingeschlossen ist. Wert wird als perl-Ausdruck ausgewertet, falls es in {} eingeschlossen ist. In der DEF werden %Name% Zeichenketten durch den zugehörigen Wert ersetzt. Dieses Attribut ist als "msgDialog_evalSpecials" im msgConfig Gerät vorhanden. Wenn der selbe Name im msgConfig und msgDialog definiert wurde, wird der Wert aus msgDialog verwendet.
*msgCommand <command>: Befehl der zum Versenden einer Nachricht verwendet wird. Die Vorgabe ist "msg push \@$recipients $message" Dieses Attribut ist als "msgDialog_msgCommand" im msgConfig Gerät vorhanden.

=== set ===
*reset: Setzt den Dialog für alle Benutzer zurück.
*say [@<recipient1>[,<recipient2>,...]] <TRIGGER>[|<NEXT TRIGGER>|...]: Der Dialog wird für alle angegeben Empänger an der angegeben Stelle fortgeführt. Sind keine Empfänger angegeben wird der Dialog für alle unter dem Attribut allowed angegebenen Empfänger fortgeführt.
*updateAllowed: Aktualisiert die Auswahl für das Attribut allowed.

=== get ===
*trigger: Listet alle TRIGGER der ersten Ebene auf bei denen nicht setOnly angegeben ist.

=== READINGS ===
*$recipient_history: Durch | getrennte Liste von TRIGGER um den aktuellen Zustand des Dialogs zu sichern. Für jeden Dialogpartner wird ein Reading angelegt. Wenn der Dialog beendet ist wird das Reading zurückgesetzt.

== Hilfe bei der Fehlersuche ==
Hier entsteht eine Sammlung von Tipps bei der Fehlersuche. Die meisten dieser "Stolpersteine"
entstehen häufig bei der Erstellung eines ersten eigenen Dialoges.

=== Es werden keine Dialoge angezeigt ===
Ohne die Angabe einer normalen Nachricht wird kein Dialog angezeigt:
<pre>
"message": [
"(Lampen einschalten) ",
"(Lampen ausschalten) ",
"(zurück:%me%) ",
],
</pre>
Erst mit der Nachricht "Möchtest Du Lampen ein oder ausschalten?" erscheint der Dialog:
<pre>
"message": [
"(Lampen einschalten) ",
"(Lampen ausschalten) ",
"(zurück:%me%) ",
"Möchtest Du Lampen ein oder ausschalten?"
],
</pre>

=== Innerhalb eines Dialogs fehlen einzelne Menüeinträge ===
Fehlen einzelne Menüeinträge innerhalb eines Dialogs, liegt das meistens an einem
fehlenden Leerzeichen:
<pre>
"message": [
"(Lampen einschalten)",
"(Lampen ausschalten) ",
"(zurück:%me%) ",
],
</pre>
Das wird durch ein fehlendes Leerzeichen nach der geschlossenen runden Klammer verursacht.
Bei "Lampen ausschalten" ist dagegen korrekt ein Leerzeichen zu sehen.

== Beispiele ==

==== Programmierung der Waschmaschine ====
Das ist ein Beispiel zur Programmierung einer Waschmaschine wie auch oben im Video zu sehen:
<pre>
defmod Waschmaschine_Dialog msgDialog { "Waschmaschine": {\
"message": [\
"{return('(Zeitprogramm stoppen) ') if(ReadingsVal('%controlUnit%', 'controlMode', '') eq 'auto')}",\
"{return('(programmieren) ') if(ReadingsVal('%actor%', 'state', '') ne 'on')}",\
"{return('(einschalten) ') if(ReadingsVal('%actor%', 'state', '') ne 'on')}",\
"(Verlaufsdiagramm) ",\
"(abbrechen) ",\
"{return('Waschmaschine: ' . (ReadingsVal('%actor%', 'state', '') eq 'on' ? 'eingeschaltet' : 'ausgeschaltet'))}",\
"{return('Modus: ' . (ReadingsVal('%controlUnit%', 'controlMode', '') eq 'auto' ? 'Automatik' : 'Manuell (' . ReadingsVal('%controlUnit%', 'time', '') . ')'))}"\
],\
"Zeitprogramm stoppen": {\
"commands": "set %controlUnit% controlMode manual",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Das Zeitprogramm wurde gestoppt."\
]\
},\
"programmieren": {\
"message": [\
"(bestätigen|zurück|abbrechen) ",\
"( 00:00 | 00:15 | 00:30 | 00:45 ) ",\
"( 01:00 | 01:15 | 01:30 | 01:45 ) ",\
"( 02:00 | 02:15 | 02:30 | 02:45 ) ",\
"( 03:00 | 03:15 | 03:30 | 03:45 ) ",\
"( 04:00 | 04:15 | 04:30 | 04:45 ) ",\
"( 05:00 | 05:15 | 05:30 | 05:45 ) ",\
"( 06:00 | 06:15 | 06:30 | 06:45 ) ",\
"( 07:00 | 07:15 | 07:30 | 07:45 ) ",\
"( 08:00 | 08:15 | 08:30 | 08:45 ) ",\
"( 09:00 | 09:15 | 09:30 | 09:45 ) ",\
"( 10:00 | 10:15 | 10:30 | 10:45 ) ",\
"( 11:00 | 11:15 | 11:30 | 11:45 ) ",\
"( 12:00 | 12:15 | 12:30 | 12:45 ) ",\
"( 13:00 | 13:15 | 13:30 | 13:45 ) ",\
"( 14:00 | 14:15 | 14:30 | 14:45 ) ",\
"( 15:00 | 15:15 | 15:30 | 15:45 ) ",\
"( 16:00 | 16:15 | 16:30 | 16:45 ) ",\
"( 17:00 | 17:15 | 17:30 | 17:45 ) ",\
"( 18:00 | 18:15 | 18:30 | 18:45 ) ",\
"( 19:00 | 19:15 | 19:30 | 19:45 ) ",\
"( 20:00 | 20:15 | 20:30 | 20:45 ) ",\
"( 21:00 | 21:15 | 21:30 | 21:45 ) ",\
"( 22:00 | 22:15 | 22:30 | 22:45 ) ",\
"( 23:00 | 23:15 | 23:30 | 23:45 ) ",\
"Wann soll die Wäsche fertig sein?",\
"Bitte Uhrzeit in HH:MM angeben.",\
"Aktuell ist [%controlUnit%:time] Uhr eingestellt."\
],\
"Uhrzeit": {\
"match": " ?([0-1][0-9]|2[0-3]):[0-5][0-9] ?",\
"commands": [\
"set %controlUnit% time $message",\
"set $SELF say @$recipient Waschmaschine|programmieren|bestätigen"\
]\
},\
"bestätigen": {\
"commands": "set %controlUnit% controlMode auto",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Das Zeitprogramm wurde eingestellt.",\
"Die Wäsche wird voraussichtlich um [%controlUnit%:time] Uhr fertig sein.",\
"Bitte die Waschmaschine vorbereiten."\
]\
}\
},\
"einschalten": {\
"commands": [\
"set %controlUnit% controlMode manual",\
"set %actor% on"\
]\
},\
"Verlaufsdiagramm": {\
"commands": "set %TelegramBot% cmdSend {plotAsPng('%plot%')}",\
"message": "TelegramBot_MTYPE=queryInline (%me%) $message"\
}\
},\
"auto": {\
"setOnly": true,\
"commands": [\
"set %actor% on",\
"set %controlUnit% controlMode manual"\
],\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine wurde automatisch eingeschaltet."\
]\
},\
"manual": {\
"setOnly": true,\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine wurde manuell eingeschaltet."\
]\
},\
"done": {\
"setOnly": true,\
"commands": "set %actor% off",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine ist fertig."\
]\
}\
}
attr Waschmaschine_Dialog evalSpecials actor=HM_2C10D8_Sw\
controlUnit=Waschkeller_washer_controlUnit\
plot=Waschkeller_washer_SVG
</pre>

== TelegramBot ==

In Telegram gibt es die Möglichkeit die Art des Keyboards zu ändern. Links das normale Keyboard, rechts das Inline Keyboard.

[[Datei:76msgDialog menu.png|Normales Keyboard]] [[Datei:76msgDialog menu inline.PNG|Inline Keyboard]]

In diesem '''[https://youtu.be/oRDy2918mVI Video]''' wird Telegram mit einem Inline Keyboard verwendet.

Um eine Nachricht bei Telegram zu verändern, gibt es den Befehl "queryEditInline".
Dafür wird die MsgId von der Nachricht benötigt. Das erledigt ein notify, welches die msgId pro Peer abspeichert:

<pre>
defmod sentMsgIdByPeerId notify .+:sentMsgId.+ {\
return unless($TYPE eq "TelegramBot");;\
\
my $dev_hash = $defs{$NAME};;\
my $sentMsgId = ReadingsVal($NAME, "sentMsgId", "");;\
my $sentMsgPeerId = ReadingsVal($NAME, "sentMsgPeerId", "");;\
my ($contact) = devspec2array("TYPE=(ROOMMATE|GUEST):FILTER=msgContactPush=.*$sentMsgPeerId.*");;\
\
readingsSingleUpdate($dev_hash, "$contact\_sentMsgId", $sentMsgId, 1);;\
}
attr sentMsgIdByPeerId devStateIcon {ReadingsVal($name, "state", "inactive") eq "active" ? ".*:ios-on-blue:inactive" : ".*:ios-off:active"}
attr sentMsgIdByPeerId icon audio_mic
attr sentMsgIdByPeerId room msg
</pre>

Danach wird der Message-Befehl von
<pre>
set <TelegramBot> message
</pre>
auf
<pre>
set <TelegramBot> queryEditInline
</pre>
geändert. Dafür wird ein [[cmdalias]] verwendet:

<pre>
defmod message2queryEditInline cmdalias set .+ message (.|\n)+ AS {\
my ($NAME, $cmd, $message) = split(/[\s]+/, $EVENT, 3);;\
my $TYPE = InternalVal($NAME, "TYPE", "");;\
(my $recipient, $message) = ($message =~ m/(@\S+)? (.+)/s);;\
\
if($TYPE eq "TelegramBot" && $recipient){\
my ($contact) = devspec2array("TYPE=(ROOMMATE|GUEST):FILTER=msgContactPush=.*$recipient.*");;\
my $sentMsgId = ReadingsVal($NAME, "$contact\_sentMsgId", "");;\
\
if($sentMsgId ne ""){\
fhem("set $NAME queryEditInline $sentMsgId $recipient $message");;\
}\
else{\
fhem("set $NAME queryInline $recipient $message");;\
}\
}\
else{\
fhem("set $EVENT");;\
}\
}
attr message2queryEditInline room msg
</pre>

Um wieder zurück zum normalen Keyboard zu gelangen genügt es, das notify und den cmdAlias zu deaktivieren.
Das kann komfortabel über ein notify und einen dummy erledigt werden:
<pre>
defmod inline_normal.NOT notify inline_normal.DUM:.* {\
if ("$EVENT" =~ "on") {\
fhem "set sentMsgIdByPeerId active;; attr message2queryEditInline disable 0";;\
} \
elsif ("$EVENT" =~ "off") {\
fhem "set sentMsgIdByPeerId inactive;; attr message2queryEditInline disable 1";;\
}\
}
</pre>

Weitere Infos zum Thema Inline Keyboard sind in der Antwort #10 im Forum zu finden (siehe Link unten).

== JABBER ==
Hier wird die Verwendung mit Jabber beschrieben...

== WhatsApp ==
Hier wird die Verwendung mit yowsup/WhatsApp beschrieben...

== Links ==
* Thread über das Modul im {{Link2Forum|Topic=77297|LinkText=FHEM Forum}}

[[Kategorie:Hilfsmodul]]

MsgDialog

2017-11-10T17:43:03Z

Binford6000: /* Hilfe bei der Fehlersuche */

{{Infobox Modul
|ModPurpose=Dialoge für Sofortnachrichten über TelegramBot, Jabber und WhatsApp
|ModType=h
|ModForumArea=Frontends
|ModTechName=76_msgDialog.pm
|ModOwner={{Link2FU|4106|igami}}
}}

== Zielsetzung ==
Ein zentrale Anforderung an die Haus-Automation ist die Kommunikation mit den Anwendern. Fast jeder Anwender möchte über bestimmte Ereignisse informiert werden und Einstellungen vornehmen. FHEM bietet schon seit längerem die Unterstützung für verschiedene Messaging Dienste an.
Mit dem msgDialog Modul können vordefinierte Dialoge erstellt werden. Die Kommunikation erfolgt dabei über den [[msg]] Befehl welcher zurzeit die bidirektionale Kommunikation über [[TelegramBot]], [[Jabber]] und [[yowsup]] (WhatsApp) unterstützt. Eingehende Nachrichten werden einem ROMMATE oder GUEST zugeordnet. Darüber werden auch die Berechtigungen für die einzelnen Dialoge festgelegt.
Die grundlegende Bedienung wird in diesem '''[https://youtu.be/yiCOTeR1YVQ Video]''' am Beispiel von TelegramBot gezeigt.

== Konfiguration ==

=== Voraussetzungen ===
Für dieses Modul wird das Perl JSON Modul benötigt. Auf einem Debian-basierten System (z.B RaspberryPI o.ä.) kann man das mit dem folgenden Befehl installieren:
<pre>
sudo apt-get install libjson-perl
</pre>

=== Hinweis zu den Code Beispielen ===
Es handelt sich bei den Beispielen um eine Raw definition, siehe auch [[Import_von_Code_Snippets]]

=== msgConfig ===

Als erstes benötigt man ein definiertes msgConfig device:

<pre>
defmod myMsgConfig msgConfig
attr myMsgConfig msgDialog_evalSpecials me=<Aktivierungswort bzw. -Nachricht>
TelegramBot=<Name des TelegramBot-device>
attr myMsgConfig msgContactPush TelegramBot
attr myMsgConfig room msg
</pre>

Falls bereits vorhanden, müssen natürlich nur die fehlenden Attribute gesetzt werden.

;msgDialog_evalSpecials
:key1=value1 key2=value2 ... Leerzeichen getrennte Liste von Name=Wert Paaren. Wert kann Leerzeichen enthalten, falls es in "" oder {} eingeschlossen :ist. Wert wird als perl-Ausdruck ausgewertet, falls es in {} eingeschlossen ist. In der DEF werden %Name% Zeichenketten durch den zugehörigen Wert :ersetzt. Wenn der selbe Name im msgConfig und msgDialog definiert wurde, wird der Wert aus msgDialog verwendet.

;msgDialog_msgCommand <command>
:Befehl zum Versenden einer Nachricht. Die Vorgabe ist "msg push \@$recipients $message". Wenn nicht gesetzt, wird die Vorgabe verwendet.

=== ROOMMATE / GUEST ===
Für jeden Dialog kann festgelegt werden welche Person dazu berechtigt ist. Dazu sind Geräte vom Typ ROOMMATE oder GUEST mit definiertem msgContactPush Attribut erforderlich. Es ist darauf zu achten, dass das Reading fhemMsgRcvPush ein Event erzeugt. Siehe auch Attribut "allowed" in msgDialog.

=== Define ===

Definition des metaDialogs:
Zur Auflistung aller berechtigten Dialoge dient - was sonst - ein Dialog!

<pre>
defmod meta_Dialog msgDialog {\
"%me%": {\
"match": "\/?(start|%me%)",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"{return('(' . join(') (', sort(split('\n', fhem('get TYPE=msgDialog:FILTER=NAME!=$SELF:FILTER=allowed=.*($recipient|everyone).* trigger')))) . ') ')}",\
"(abbrechen) ",\
"Ich kann folgendes für dich tun:"\
]\
},\
"abbrechen": {\
"match": "\/?abbrechen",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"(%me%) ",\
"Dialog abgebrochen."\
] \
},\
"beenden": {\
"match": "\/?beenden",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"(%me%) ",\
"Dialog beendet."\
]\
}\
}

attr meta_Dialog DbLogExclude .*
attr meta_Dialog allowed everyone
attr meta_Dialog room msg
</pre>

Aufgrund der Komplexität eines Dialogs mit JSON ist es am praktikabelsten, zunächst einen leeren Dialog zu definieren:
<pre>
define <name> msgDialog {}
</pre>

Anschließend kann die '''DEF''' in der Detail-Ansicht des Dialog-Device bearbeitet werden. Jeder Dialog basiert auf der folgenden Struktur von einfach bis komplex.

<pre>
{
"<TRIGGER>": {
"match": "<regex>",
"setOnly": (true|false),
"commands": "(fhem command|{perl code})",
"message": [
"{perl code}",
"text"
],
"<NEXT TRIGGER 1>": {
...
},
"<NEXT TRIGGER 2>": {
...
}
}
}
</pre>

Um den JSON-Teil der Dialoge zu testen, empfiehlt sich ein Besuch auf https://jsonlint.com/
Hier kann der selbst geschriebene JSON-Code validiert werden.

;TRIGGER
:Kann ein beliebiger Text sein. Es wird geprüft ob die eingehende Nachricht damit übereinstimmt. Falls ja, wird der Dialog an dieser Stelle fortgesetzt.

;match
:Wenn nicht nur genau eine Nachricht zugelassen werden soll, kann noch eine regex angegeben werden. Die regex muss auf die gesamte eingehnde Nachricht :zutreffen.

;setOnly
:Kann optional auf true oder false gestellt werden. In beiden fällen wird der TRIGGER dann nicht bei "get <name> trigger" zurück gegeben.
:Wenn setOnly auf "true" gestellt wird, kann der Dialog an dieser Stelle nicht durch eingehende Nachrichten ausgelöst werden, sondern nur über "get <name> say TRIGGER". Dies kann dazu genutzt werden um einen Dialog aus :FHEM heraus zu initiieren.

;commands
:Kann einen einzelnen oder mehrere Befehle enthalten:
<pre>
"commands":
"single command"
"commands": [
"command 1",
"command 2",
"{perl command}"
]
</pre>

;message
:Kann einen einzelnen oder mehrere Textte enthalten die mit einen Zeilenumbruch verbunden werden:
<pre>
"message": "text"
</pre>
<pre>
"message": [
"text 1",
"text 2",
"{return from perl command}"
]
</pre>

Bei mehrstufigen Dialogen wird diese Struktur ineinander verschachtelt angegeben.
Es werden Variablen und Platzhalter, welche unter dem Attribut evalSpecials definiert werden, ausgewertet.

=== Variablen ===
*$SELF: Eigenname des msgDialog
*$message: eingegangene Nachricht
*$recipient: Name des Dialogpartners

=== Attribute ===
*allowed: Liste mit allen RESIDENTS und ROOMMATE die für diesen Dialog berechtigt sind.
*disable: [0|1] Dialog ist aktiviert|deaktiviert.
*disabledForIntervals: HH:MM-HH:MM HH:MM-HH-MM ...
*evalSpecials: key1=value1 key2=value2 ...Leerzeichen getrennte Liste von Name=Wert Paaren. Wert kann Leerzeichen enthalten, falls es in "" oder {} eingeschlossen ist. Wert wird als perl-Ausdruck ausgewertet, falls es in {} eingeschlossen ist. In der DEF werden %Name% Zeichenketten durch den zugehörigen Wert ersetzt. Dieses Attribut ist als "msgDialog_evalSpecials" im msgConfig Gerät vorhanden. Wenn der selbe Name im msgConfig und msgDialog definiert wurde, wird der Wert aus msgDialog verwendet.
*msgCommand <command>: Befehl der zum Versenden einer Nachricht verwendet wird. Die Vorgabe ist "msg push \@$recipients $message" Dieses Attribut ist als "msgDialog_msgCommand" im msgConfig Gerät vorhanden.

=== set ===
*reset: Setzt den Dialog für alle Benutzer zurück.
*say [@<recipient1>[,<recipient2>,...]] <TRIGGER>[|<NEXT TRIGGER>|...]: Der Dialog wird für alle angegeben Empänger an der angegeben Stelle fortgeführt. Sind keine Empfänger angegeben wird der Dialog für alle unter dem Attribut allowed angegebenen Empfänger fortgeführt.
*updateAllowed: Aktualisiert die Auswahl für das Attribut allowed.

=== get ===
*trigger: Listet alle TRIGGER der ersten Ebene auf bei denen nicht setOnly angegeben ist.

=== READINGS ===
*$recipient_history: Durch | getrennte Liste von TRIGGER um den aktuellen Zustand des Dialogs zu sichern. Für jeden Dialogpartner wird ein Reading angelegt. Wenn der Dialog beendet ist wird das Reading zurückgesetzt.

== Hilfe bei der Fehlersuche ==
Hier entsteht eine Sammlung von Tipps bei der Fehlersuche. Die meisten dieser "Stolpersteine"
entstehen häufig bei der Erstellung eines ersten eigenen Dialoges.

;Es werden keine Dialoge angezeigt, in diesem Beispiel "Beleuchtung":
: Dieses Problem entsteht häufig beider Erstellung eines ersten eigenen Dialoges:
: Ohne die Angabe einer normalen Nachricht wird kein Dialog angezeigt:
<pre>
"message": [
"(Lampen einschalten) ",
"(Lampen ausschalten) ",
"(zurück:%me%) ",
],
</pre>
Mit der Nachricht "Möchtest Du Lampen ein oder ausschalten?" erscheint der Dialog
<pre>
"message": [
"(Lampen einschalten) ",
"(Lampen ausschalten) ",
"(zurück:%me%) ",
"Möchtest Du Lampen ein oder ausschalten?"
],
</pre>

;Innerhalb eines Dialogs fehlen einzelne Menüeinträge, in diesem Beispiel "Lampen einschalten":
:
<pre>
"message": [
"(Lampen einschalten)",
"(Lampen ausschalten) ",
"(zurück:%me%) ",
],
</pre>
: Das wird durch ein fehlendes Leerzeichen nach der geschlossenen runden Klammer verursacht.
: Bei "Lampen ausschalten" ist dagegen korrekt ein Leerzeichen zu sehen.

== Beispiele ==

==== Programmierung der Waschmaschine ====
Das ist ein Beispiel zur Programmierung einer Waschmaschine wie auch oben im Video zu sehen:
<pre>
defmod Waschmaschine_Dialog msgDialog { "Waschmaschine": {\
"message": [\
"{return('(Zeitprogramm stoppen) ') if(ReadingsVal('%controlUnit%', 'controlMode', '') eq 'auto')}",\
"{return('(programmieren) ') if(ReadingsVal('%actor%', 'state', '') ne 'on')}",\
"{return('(einschalten) ') if(ReadingsVal('%actor%', 'state', '') ne 'on')}",\
"(Verlaufsdiagramm) ",\
"(abbrechen) ",\
"{return('Waschmaschine: ' . (ReadingsVal('%actor%', 'state', '') eq 'on' ? 'eingeschaltet' : 'ausgeschaltet'))}",\
"{return('Modus: ' . (ReadingsVal('%controlUnit%', 'controlMode', '') eq 'auto' ? 'Automatik' : 'Manuell (' . ReadingsVal('%controlUnit%', 'time', '') . ')'))}"\
],\
"Zeitprogramm stoppen": {\
"commands": "set %controlUnit% controlMode manual",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Das Zeitprogramm wurde gestoppt."\
]\
},\
"programmieren": {\
"message": [\
"(bestätigen|zurück|abbrechen) ",\
"( 00:00 | 00:15 | 00:30 | 00:45 ) ",\
"( 01:00 | 01:15 | 01:30 | 01:45 ) ",\
"( 02:00 | 02:15 | 02:30 | 02:45 ) ",\
"( 03:00 | 03:15 | 03:30 | 03:45 ) ",\
"( 04:00 | 04:15 | 04:30 | 04:45 ) ",\
"( 05:00 | 05:15 | 05:30 | 05:45 ) ",\
"( 06:00 | 06:15 | 06:30 | 06:45 ) ",\
"( 07:00 | 07:15 | 07:30 | 07:45 ) ",\
"( 08:00 | 08:15 | 08:30 | 08:45 ) ",\
"( 09:00 | 09:15 | 09:30 | 09:45 ) ",\
"( 10:00 | 10:15 | 10:30 | 10:45 ) ",\
"( 11:00 | 11:15 | 11:30 | 11:45 ) ",\
"( 12:00 | 12:15 | 12:30 | 12:45 ) ",\
"( 13:00 | 13:15 | 13:30 | 13:45 ) ",\
"( 14:00 | 14:15 | 14:30 | 14:45 ) ",\
"( 15:00 | 15:15 | 15:30 | 15:45 ) ",\
"( 16:00 | 16:15 | 16:30 | 16:45 ) ",\
"( 17:00 | 17:15 | 17:30 | 17:45 ) ",\
"( 18:00 | 18:15 | 18:30 | 18:45 ) ",\
"( 19:00 | 19:15 | 19:30 | 19:45 ) ",\
"( 20:00 | 20:15 | 20:30 | 20:45 ) ",\
"( 21:00 | 21:15 | 21:30 | 21:45 ) ",\
"( 22:00 | 22:15 | 22:30 | 22:45 ) ",\
"( 23:00 | 23:15 | 23:30 | 23:45 ) ",\
"Wann soll die Wäsche fertig sein?",\
"Bitte Uhrzeit in HH:MM angeben.",\
"Aktuell ist [%controlUnit%:time] Uhr eingestellt."\
],\
"Uhrzeit": {\
"match": " ?([0-1][0-9]|2[0-3]):[0-5][0-9] ?",\
"commands": [\
"set %controlUnit% time $message",\
"set $SELF say @$recipient Waschmaschine|programmieren|bestätigen"\
]\
},\
"bestätigen": {\
"commands": "set %controlUnit% controlMode auto",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Das Zeitprogramm wurde eingestellt.",\
"Die Wäsche wird voraussichtlich um [%controlUnit%:time] Uhr fertig sein.",\
"Bitte die Waschmaschine vorbereiten."\
]\
}\
},\
"einschalten": {\
"commands": [\
"set %controlUnit% controlMode manual",\
"set %actor% on"\
]\
},\
"Verlaufsdiagramm": {\
"commands": "set %TelegramBot% cmdSend {plotAsPng('%plot%')}",\
"message": "TelegramBot_MTYPE=queryInline (%me%) $message"\
}\
},\
"auto": {\
"setOnly": true,\
"commands": [\
"set %actor% on",\
"set %controlUnit% controlMode manual"\
],\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine wurde automatisch eingeschaltet."\
]\
},\
"manual": {\
"setOnly": true,\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine wurde manuell eingeschaltet."\
]\
},\
"done": {\
"setOnly": true,\
"commands": "set %actor% off",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine ist fertig."\
]\
}\
}
attr Waschmaschine_Dialog evalSpecials actor=HM_2C10D8_Sw\
controlUnit=Waschkeller_washer_controlUnit\
plot=Waschkeller_washer_SVG
</pre>

== TelegramBot ==

In Telegram gibt es die Möglichkeit die Art des Keyboards zu ändern. Links das normale Keyboard, rechts das Inline Keyboard.

[[Datei:76msgDialog menu.png|Normales Keyboard]] [[Datei:76msgDialog menu inline.PNG|Inline Keyboard]]

In diesem '''[https://youtu.be/oRDy2918mVI Video]''' wird Telegram mit einem Inline Keyboard verwendet.

Um eine Nachricht bei Telegram zu verändern, gibt es den Befehl "queryEditInline".
Dafür wird die MsgId von der Nachricht benötigt. Das erledigt ein notify, welches die msgId pro Peer abspeichert:

<pre>
defmod sentMsgIdByPeerId notify .+:sentMsgId.+ {\
return unless($TYPE eq "TelegramBot");;\
\
my $dev_hash = $defs{$NAME};;\
my $sentMsgId = ReadingsVal($NAME, "sentMsgId", "");;\
my $sentMsgPeerId = ReadingsVal($NAME, "sentMsgPeerId", "");;\
my ($contact) = devspec2array("TYPE=(ROOMMATE|GUEST):FILTER=msgContactPush=.*$sentMsgPeerId.*");;\
\
readingsSingleUpdate($dev_hash, "$contact\_sentMsgId", $sentMsgId, 1);;\
}
attr sentMsgIdByPeerId devStateIcon {ReadingsVal($name, "state", "inactive") eq "active" ? ".*:ios-on-blue:inactive" : ".*:ios-off:active"}
attr sentMsgIdByPeerId icon audio_mic
attr sentMsgIdByPeerId room msg
</pre>

Danach wird der Message-Befehl von
<pre>
set <TelegramBot> message
</pre>
auf
<pre>
set <TelegramBot> queryEditInline
</pre>
geändert. Dafür wird ein [[cmdalias]] verwendet:

<pre>
defmod message2queryEditInline cmdalias set .+ message (.|\n)+ AS {\
my ($NAME, $cmd, $message) = split(/[\s]+/, $EVENT, 3);;\
my $TYPE = InternalVal($NAME, "TYPE", "");;\
(my $recipient, $message) = ($message =~ m/(@\S+)? (.+)/s);;\
\
if($TYPE eq "TelegramBot" && $recipient){\
my ($contact) = devspec2array("TYPE=(ROOMMATE|GUEST):FILTER=msgContactPush=.*$recipient.*");;\
my $sentMsgId = ReadingsVal($NAME, "$contact\_sentMsgId", "");;\
\
if($sentMsgId ne ""){\
fhem("set $NAME queryEditInline $sentMsgId $recipient $message");;\
}\
else{\
fhem("set $NAME queryInline $recipient $message");;\
}\
}\
else{\
fhem("set $EVENT");;\
}\
}
attr message2queryEditInline room msg
</pre>

Um wieder zurück zum normalen Keyboard zu gelangen genügt es, das notify und den cmdAlias zu deaktivieren.
Das kann komfortabel über ein notify und einen dummy erledigt werden:
<pre>
defmod inline_normal.NOT notify inline_normal.DUM:.* {\
if ("$EVENT" =~ "on") {\
fhem "set sentMsgIdByPeerId active;; attr message2queryEditInline disable 0";;\
} \
elsif ("$EVENT" =~ "off") {\
fhem "set sentMsgIdByPeerId inactive;; attr message2queryEditInline disable 1";;\
}\
}
</pre>

Weitere Infos zum Thema Inline Keyboard sind in der Antwort #10 im Forum zu finden (siehe Link unten).

== JABBER ==
Hier wird die Verwendung mit Jabber beschrieben...

== WhatsApp ==
Hier wird die Verwendung mit yowsup/WhatsApp beschrieben...

== Links ==
* Thread über das Modul im {{Link2Forum|Topic=77297|LinkText=FHEM Forum}}

[[Kategorie:Hilfsmodul]]

MsgDialog

2017-11-10T17:42:39Z

Binford6000:

{{Infobox Modul
|ModPurpose=Dialoge für Sofortnachrichten über TelegramBot, Jabber und WhatsApp
|ModType=h
|ModForumArea=Frontends
|ModTechName=76_msgDialog.pm
|ModOwner={{Link2FU|4106|igami}}
}}

== Zielsetzung ==
Ein zentrale Anforderung an die Haus-Automation ist die Kommunikation mit den Anwendern. Fast jeder Anwender möchte über bestimmte Ereignisse informiert werden und Einstellungen vornehmen. FHEM bietet schon seit längerem die Unterstützung für verschiedene Messaging Dienste an.
Mit dem msgDialog Modul können vordefinierte Dialoge erstellt werden. Die Kommunikation erfolgt dabei über den [[msg]] Befehl welcher zurzeit die bidirektionale Kommunikation über [[TelegramBot]], [[Jabber]] und [[yowsup]] (WhatsApp) unterstützt. Eingehende Nachrichten werden einem ROMMATE oder GUEST zugeordnet. Darüber werden auch die Berechtigungen für die einzelnen Dialoge festgelegt.
Die grundlegende Bedienung wird in diesem '''[https://youtu.be/yiCOTeR1YVQ Video]''' am Beispiel von TelegramBot gezeigt.

== Konfiguration ==

=== Voraussetzungen ===
Für dieses Modul wird das Perl JSON Modul benötigt. Auf einem Debian-basierten System (z.B RaspberryPI o.ä.) kann man das mit dem folgenden Befehl installieren:
<pre>
sudo apt-get install libjson-perl
</pre>

=== Hinweis zu den Code Beispielen ===
Es handelt sich bei den Beispielen um eine Raw definition, siehe auch [[Import_von_Code_Snippets]]

=== msgConfig ===

Als erstes benötigt man ein definiertes msgConfig device:

<pre>
defmod myMsgConfig msgConfig
attr myMsgConfig msgDialog_evalSpecials me=<Aktivierungswort bzw. -Nachricht>
TelegramBot=<Name des TelegramBot-device>
attr myMsgConfig msgContactPush TelegramBot
attr myMsgConfig room msg
</pre>

Falls bereits vorhanden, müssen natürlich nur die fehlenden Attribute gesetzt werden.

;msgDialog_evalSpecials
:key1=value1 key2=value2 ... Leerzeichen getrennte Liste von Name=Wert Paaren. Wert kann Leerzeichen enthalten, falls es in "" oder {} eingeschlossen :ist. Wert wird als perl-Ausdruck ausgewertet, falls es in {} eingeschlossen ist. In der DEF werden %Name% Zeichenketten durch den zugehörigen Wert :ersetzt. Wenn der selbe Name im msgConfig und msgDialog definiert wurde, wird der Wert aus msgDialog verwendet.

;msgDialog_msgCommand <command>
:Befehl zum Versenden einer Nachricht. Die Vorgabe ist "msg push \@$recipients $message". Wenn nicht gesetzt, wird die Vorgabe verwendet.

=== ROOMMATE / GUEST ===
Für jeden Dialog kann festgelegt werden welche Person dazu berechtigt ist. Dazu sind Geräte vom Typ ROOMMATE oder GUEST mit definiertem msgContactPush Attribut erforderlich. Es ist darauf zu achten, dass das Reading fhemMsgRcvPush ein Event erzeugt. Siehe auch Attribut "allowed" in msgDialog.

=== Define ===

Definition des metaDialogs:
Zur Auflistung aller berechtigten Dialoge dient - was sonst - ein Dialog!

<pre>
defmod meta_Dialog msgDialog {\
"%me%": {\
"match": "\/?(start|%me%)",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"{return('(' . join(') (', sort(split('\n', fhem('get TYPE=msgDialog:FILTER=NAME!=$SELF:FILTER=allowed=.*($recipient|everyone).* trigger')))) . ') ')}",\
"(abbrechen) ",\
"Ich kann folgendes für dich tun:"\
]\
},\
"abbrechen": {\
"match": "\/?abbrechen",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"(%me%) ",\
"Dialog abgebrochen."\
] \
},\
"beenden": {\
"match": "\/?beenden",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"(%me%) ",\
"Dialog beendet."\
]\
}\
}

attr meta_Dialog DbLogExclude .*
attr meta_Dialog allowed everyone
attr meta_Dialog room msg
</pre>

Aufgrund der Komplexität eines Dialogs mit JSON ist es am praktikabelsten, zunächst einen leeren Dialog zu definieren:
<pre>
define <name> msgDialog {}
</pre>

Anschließend kann die '''DEF''' in der Detail-Ansicht des Dialog-Device bearbeitet werden. Jeder Dialog basiert auf der folgenden Struktur von einfach bis komplex.

<pre>
{
"<TRIGGER>": {
"match": "<regex>",
"setOnly": (true|false),
"commands": "(fhem command|{perl code})",
"message": [
"{perl code}",
"text"
],
"<NEXT TRIGGER 1>": {
...
},
"<NEXT TRIGGER 2>": {
...
}
}
}
</pre>

Um den JSON-Teil der Dialoge zu testen, empfiehlt sich ein Besuch auf https://jsonlint.com/
Hier kann der selbst geschriebene JSON-Code validiert werden.

;TRIGGER
:Kann ein beliebiger Text sein. Es wird geprüft ob die eingehende Nachricht damit übereinstimmt. Falls ja, wird der Dialog an dieser Stelle fortgesetzt.

;match
:Wenn nicht nur genau eine Nachricht zugelassen werden soll, kann noch eine regex angegeben werden. Die regex muss auf die gesamte eingehnde Nachricht :zutreffen.

;setOnly
:Kann optional auf true oder false gestellt werden. In beiden fällen wird der TRIGGER dann nicht bei "get <name> trigger" zurück gegeben.
:Wenn setOnly auf "true" gestellt wird, kann der Dialog an dieser Stelle nicht durch eingehende Nachrichten ausgelöst werden, sondern nur über "get <name> say TRIGGER". Dies kann dazu genutzt werden um einen Dialog aus :FHEM heraus zu initiieren.

;commands
:Kann einen einzelnen oder mehrere Befehle enthalten:
<pre>
"commands":
"single command"
"commands": [
"command 1",
"command 2",
"{perl command}"
]
</pre>

;message
:Kann einen einzelnen oder mehrere Textte enthalten die mit einen Zeilenumbruch verbunden werden:
<pre>
"message": "text"
</pre>
<pre>
"message": [
"text 1",
"text 2",
"{return from perl command}"
]
</pre>

Bei mehrstufigen Dialogen wird diese Struktur ineinander verschachtelt angegeben.
Es werden Variablen und Platzhalter, welche unter dem Attribut evalSpecials definiert werden, ausgewertet.

=== Variablen ===
*$SELF: Eigenname des msgDialog
*$message: eingegangene Nachricht
*$recipient: Name des Dialogpartners

=== Attribute ===
*allowed: Liste mit allen RESIDENTS und ROOMMATE die für diesen Dialog berechtigt sind.
*disable: [0|1] Dialog ist aktiviert|deaktiviert.
*disabledForIntervals: HH:MM-HH:MM HH:MM-HH-MM ...
*evalSpecials: key1=value1 key2=value2 ...Leerzeichen getrennte Liste von Name=Wert Paaren. Wert kann Leerzeichen enthalten, falls es in "" oder {} eingeschlossen ist. Wert wird als perl-Ausdruck ausgewertet, falls es in {} eingeschlossen ist. In der DEF werden %Name% Zeichenketten durch den zugehörigen Wert ersetzt. Dieses Attribut ist als "msgDialog_evalSpecials" im msgConfig Gerät vorhanden. Wenn der selbe Name im msgConfig und msgDialog definiert wurde, wird der Wert aus msgDialog verwendet.
*msgCommand <command>: Befehl der zum Versenden einer Nachricht verwendet wird. Die Vorgabe ist "msg push \@$recipients $message" Dieses Attribut ist als "msgDialog_msgCommand" im msgConfig Gerät vorhanden.

=== set ===
*reset: Setzt den Dialog für alle Benutzer zurück.
*say [@<recipient1>[,<recipient2>,...]] <TRIGGER>[|<NEXT TRIGGER>|...]: Der Dialog wird für alle angegeben Empänger an der angegeben Stelle fortgeführt. Sind keine Empfänger angegeben wird der Dialog für alle unter dem Attribut allowed angegebenen Empfänger fortgeführt.
*updateAllowed: Aktualisiert die Auswahl für das Attribut allowed.

=== get ===
*trigger: Listet alle TRIGGER der ersten Ebene auf bei denen nicht setOnly angegeben ist.

=== READINGS ===
*$recipient_history: Durch | getrennte Liste von TRIGGER um den aktuellen Zustand des Dialogs zu sichern. Für jeden Dialogpartner wird ein Reading angelegt. Wenn der Dialog beendet ist wird das Reading zurückgesetzt.

=== Hilfe bei der Fehlersuche ===
Hier entsteht eine Sammlung von Tipps bei der Fehlersuche. Die meisten dieser "Stolpersteine"
entstehen häufig bei der Erstellung eines ersten eigenen Dialoges.

;Es werden keine Dialoge angezeigt, in diesem Beispiel "Beleuchtung":
: Dieses Problem entsteht häufig beider Erstellung eines ersten eigenen Dialoges:
: Ohne die Angabe einer normalen Nachricht wird kein Dialog angezeigt:
<pre>
"message": [
"(Lampen einschalten) ",
"(Lampen ausschalten) ",
"(zurück:%me%) ",
],
</pre>
Mit der Nachricht "Möchtest Du Lampen ein oder ausschalten?" erscheint der Dialog
<pre>
"message": [
"(Lampen einschalten) ",
"(Lampen ausschalten) ",
"(zurück:%me%) ",
"Möchtest Du Lampen ein oder ausschalten?"
],
</pre>

;Innerhalb eines Dialogs fehlen einzelne Menüeinträge, in diesem Beispiel "Lampen einschalten":
:
<pre>
"message": [
"(Lampen einschalten)",
"(Lampen ausschalten) ",
"(zurück:%me%) ",
],
</pre>
: Das wird durch ein fehlendes Leerzeichen nach der geschlossenen runden Klammer verursacht.
: Bei "Lampen ausschalten" ist dagegen korrekt ein Leerzeichen zu sehen.

== Beispiele ==

==== Programmierung der Waschmaschine ====
Das ist ein Beispiel zur Programmierung einer Waschmaschine wie auch oben im Video zu sehen:
<pre>
defmod Waschmaschine_Dialog msgDialog { "Waschmaschine": {\
"message": [\
"{return('(Zeitprogramm stoppen) ') if(ReadingsVal('%controlUnit%', 'controlMode', '') eq 'auto')}",\
"{return('(programmieren) ') if(ReadingsVal('%actor%', 'state', '') ne 'on')}",\
"{return('(einschalten) ') if(ReadingsVal('%actor%', 'state', '') ne 'on')}",\
"(Verlaufsdiagramm) ",\
"(abbrechen) ",\
"{return('Waschmaschine: ' . (ReadingsVal('%actor%', 'state', '') eq 'on' ? 'eingeschaltet' : 'ausgeschaltet'))}",\
"{return('Modus: ' . (ReadingsVal('%controlUnit%', 'controlMode', '') eq 'auto' ? 'Automatik' : 'Manuell (' . ReadingsVal('%controlUnit%', 'time', '') . ')'))}"\
],\
"Zeitprogramm stoppen": {\
"commands": "set %controlUnit% controlMode manual",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Das Zeitprogramm wurde gestoppt."\
]\
},\
"programmieren": {\
"message": [\
"(bestätigen|zurück|abbrechen) ",\
"( 00:00 | 00:15 | 00:30 | 00:45 ) ",\
"( 01:00 | 01:15 | 01:30 | 01:45 ) ",\
"( 02:00 | 02:15 | 02:30 | 02:45 ) ",\
"( 03:00 | 03:15 | 03:30 | 03:45 ) ",\
"( 04:00 | 04:15 | 04:30 | 04:45 ) ",\
"( 05:00 | 05:15 | 05:30 | 05:45 ) ",\
"( 06:00 | 06:15 | 06:30 | 06:45 ) ",\
"( 07:00 | 07:15 | 07:30 | 07:45 ) ",\
"( 08:00 | 08:15 | 08:30 | 08:45 ) ",\
"( 09:00 | 09:15 | 09:30 | 09:45 ) ",\
"( 10:00 | 10:15 | 10:30 | 10:45 ) ",\
"( 11:00 | 11:15 | 11:30 | 11:45 ) ",\
"( 12:00 | 12:15 | 12:30 | 12:45 ) ",\
"( 13:00 | 13:15 | 13:30 | 13:45 ) ",\
"( 14:00 | 14:15 | 14:30 | 14:45 ) ",\
"( 15:00 | 15:15 | 15:30 | 15:45 ) ",\
"( 16:00 | 16:15 | 16:30 | 16:45 ) ",\
"( 17:00 | 17:15 | 17:30 | 17:45 ) ",\
"( 18:00 | 18:15 | 18:30 | 18:45 ) ",\
"( 19:00 | 19:15 | 19:30 | 19:45 ) ",\
"( 20:00 | 20:15 | 20:30 | 20:45 ) ",\
"( 21:00 | 21:15 | 21:30 | 21:45 ) ",\
"( 22:00 | 22:15 | 22:30 | 22:45 ) ",\
"( 23:00 | 23:15 | 23:30 | 23:45 ) ",\
"Wann soll die Wäsche fertig sein?",\
"Bitte Uhrzeit in HH:MM angeben.",\
"Aktuell ist [%controlUnit%:time] Uhr eingestellt."\
],\
"Uhrzeit": {\
"match": " ?([0-1][0-9]|2[0-3]):[0-5][0-9] ?",\
"commands": [\
"set %controlUnit% time $message",\
"set $SELF say @$recipient Waschmaschine|programmieren|bestätigen"\
]\
},\
"bestätigen": {\
"commands": "set %controlUnit% controlMode auto",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Das Zeitprogramm wurde eingestellt.",\
"Die Wäsche wird voraussichtlich um [%controlUnit%:time] Uhr fertig sein.",\
"Bitte die Waschmaschine vorbereiten."\
]\
}\
},\
"einschalten": {\
"commands": [\
"set %controlUnit% controlMode manual",\
"set %actor% on"\
]\
},\
"Verlaufsdiagramm": {\
"commands": "set %TelegramBot% cmdSend {plotAsPng('%plot%')}",\
"message": "TelegramBot_MTYPE=queryInline (%me%) $message"\
}\
},\
"auto": {\
"setOnly": true,\
"commands": [\
"set %actor% on",\
"set %controlUnit% controlMode manual"\
],\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine wurde automatisch eingeschaltet."\
]\
},\
"manual": {\
"setOnly": true,\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine wurde manuell eingeschaltet."\
]\
},\
"done": {\
"setOnly": true,\
"commands": "set %actor% off",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine ist fertig."\
]\
}\
}
attr Waschmaschine_Dialog evalSpecials actor=HM_2C10D8_Sw\
controlUnit=Waschkeller_washer_controlUnit\
plot=Waschkeller_washer_SVG
</pre>

== TelegramBot ==

In Telegram gibt es die Möglichkeit die Art des Keyboards zu ändern. Links das normale Keyboard, rechts das Inline Keyboard.

[[Datei:76msgDialog menu.png|Normales Keyboard]] [[Datei:76msgDialog menu inline.PNG|Inline Keyboard]]

In diesem '''[https://youtu.be/oRDy2918mVI Video]''' wird Telegram mit einem Inline Keyboard verwendet.

Um eine Nachricht bei Telegram zu verändern, gibt es den Befehl "queryEditInline".
Dafür wird die MsgId von der Nachricht benötigt. Das erledigt ein notify, welches die msgId pro Peer abspeichert:

<pre>
defmod sentMsgIdByPeerId notify .+:sentMsgId.+ {\
return unless($TYPE eq "TelegramBot");;\
\
my $dev_hash = $defs{$NAME};;\
my $sentMsgId = ReadingsVal($NAME, "sentMsgId", "");;\
my $sentMsgPeerId = ReadingsVal($NAME, "sentMsgPeerId", "");;\
my ($contact) = devspec2array("TYPE=(ROOMMATE|GUEST):FILTER=msgContactPush=.*$sentMsgPeerId.*");;\
\
readingsSingleUpdate($dev_hash, "$contact\_sentMsgId", $sentMsgId, 1);;\
}
attr sentMsgIdByPeerId devStateIcon {ReadingsVal($name, "state", "inactive") eq "active" ? ".*:ios-on-blue:inactive" : ".*:ios-off:active"}
attr sentMsgIdByPeerId icon audio_mic
attr sentMsgIdByPeerId room msg
</pre>

Danach wird der Message-Befehl von
<pre>
set <TelegramBot> message
</pre>
auf
<pre>
set <TelegramBot> queryEditInline
</pre>
geändert. Dafür wird ein [[cmdalias]] verwendet:

<pre>
defmod message2queryEditInline cmdalias set .+ message (.|\n)+ AS {\
my ($NAME, $cmd, $message) = split(/[\s]+/, $EVENT, 3);;\
my $TYPE = InternalVal($NAME, "TYPE", "");;\
(my $recipient, $message) = ($message =~ m/(@\S+)? (.+)/s);;\
\
if($TYPE eq "TelegramBot" && $recipient){\
my ($contact) = devspec2array("TYPE=(ROOMMATE|GUEST):FILTER=msgContactPush=.*$recipient.*");;\
my $sentMsgId = ReadingsVal($NAME, "$contact\_sentMsgId", "");;\
\
if($sentMsgId ne ""){\
fhem("set $NAME queryEditInline $sentMsgId $recipient $message");;\
}\
else{\
fhem("set $NAME queryInline $recipient $message");;\
}\
}\
else{\
fhem("set $EVENT");;\
}\
}
attr message2queryEditInline room msg
</pre>

Um wieder zurück zum normalen Keyboard zu gelangen genügt es, das notify und den cmdAlias zu deaktivieren.
Das kann komfortabel über ein notify und einen dummy erledigt werden:
<pre>
defmod inline_normal.NOT notify inline_normal.DUM:.* {\
if ("$EVENT" =~ "on") {\
fhem "set sentMsgIdByPeerId active;; attr message2queryEditInline disable 0";;\
} \
elsif ("$EVENT" =~ "off") {\
fhem "set sentMsgIdByPeerId inactive;; attr message2queryEditInline disable 1";;\
}\
}
</pre>

Weitere Infos zum Thema Inline Keyboard sind in der Antwort #10 im Forum zu finden (siehe Link unten).

== JABBER ==
Hier wird die Verwendung mit Jabber beschrieben...

== WhatsApp ==
Hier wird die Verwendung mit yowsup/WhatsApp beschrieben...

== Links ==
* Thread über das Modul im {{Link2Forum|Topic=77297|LinkText=FHEM Forum}}

[[Kategorie:Hilfsmodul]]

MsgDialog

2017-10-31T09:40:08Z

Binford6000: /* Define */

{{Infobox Modul
|ModPurpose=Dialoge für Sofortnachrichten über TelegramBot, Jabber und WhatsApp
|ModType=h
|ModForumArea=Frontends
|ModTechName=76_msgDialog.pm
|ModOwner={{Link2FU|4106|igami}}
}}

== Zielsetzung ==
Ein zentrale Anforderung an die Haus-Automation ist die Kommunikation mit den Anwendern. Fast jeder Anwender möchte über bestimmte Ereignisse informiert werden und Einstellungen vornehmen. FHEM bietet schon seit längerem die Unterstützung für verschiedene Messaging Dienste an.
Mit dem msgDialog Modul können vordefinierte Dialoge erstellt werden. Die Kommunikation erfolgt dabei über den [[msg]] Befehl welcher zurzeit die bidirektionale Kommunikation über [[TelegramBot]], [[Jabber]] und [[yowsup]] (WhatsApp) unterstützt. Eingehende Nachrichten werden einem ROMMATE oder GUEST zugeordnet. Darüber werden auch die Berechtigungen für die einzelnen Dialoge festgelegt.
Die grundlegende Bedienung wird in diesem '''[https://youtu.be/yiCOTeR1YVQ Video]''' am Beispiel von TelegramBot gezeigt.

== Konfiguration ==

=== Voraussetzungen ===
Für dieses Modul wird das Perl JSON Modul benötigt. Auf einem Debian-basierten System (z.B RaspberryPI o.ä.) kann man das mit dem folgenden Befehl installieren:
<pre>
sudo apt-get install libjson-perl
</pre>

=== Hinweis zu den Code Beispielen ===
Es handelt sich bei den Beispielen um eine Raw definition, siehe auch [[Import_von_Code_Snippets]]

=== msgConfig ===

Als erstes benötigt man ein definiertes msgConfig device:

<pre>
defmod myMsgConfig msgConfig
attr myMsgConfig msgDialog_evalSpecials me=<Aktivierungswort bzw. -Nachricht>
TelegramBot=<Name des TelegramBot-device>
attr myMsgConfig msgContactPush TelegramBot
attr myMsgConfig room msg
</pre>

Falls bereits vorhanden, müssen natürlich nur die fehlenden Attribute gesetzt werden.

;msgDialog_evalSpecials
:key1=value1 key2=value2 ... Leerzeichen getrennte Liste von Name=Wert Paaren. Wert kann Leerzeichen enthalten, falls es in "" oder {} eingeschlossen :ist. Wert wird als perl-Ausdruck ausgewertet, falls es in {} eingeschlossen ist. In der DEF werden %Name% Zeichenketten durch den zugehörigen Wert :ersetzt. Wenn der selbe Name im msgConfig und msgDialog definiert wurde, wird der Wert aus msgDialog verwendet.

;msgDialog_msgCommand <command>
:Befehl zum Versenden einer Nachricht. Die Vorgabe ist "msg push \@$recipients $message". Wenn nicht gesetzt, wird die Vorgabe verwendet.

=== ROOMMATE / GUEST ===
Für jeden Dialog kann festgelegt werden welche Person dazu berechtigt ist. Dazu sind Geräte vom Typ ROOMMATE oder GUEST mit definiertem msgContactPush Attribut erforderlich. Es ist darauf zu achten, dass das Reading fhemMsgRcvPush ein Event erzeugt. Siehe auch Attribut "allowed" in msgDialog.

=== Define ===

Definition des metaDialogs:
Zur Auflistung aller berechtigten Dialoge dient - was sonst - ein Dialog!

<pre>
defmod meta_Dialog msgDialog {\
"%me%": {\
"match": "\/?(start|%me%)",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"{return('(' . join(') (', sort(split('\n', fhem('get TYPE=msgDialog:FILTER=NAME!=$SELF:FILTER=allowed=.*($recipient|everyone).* trigger')))) . ') ')}",\
"(abbrechen) ",\
"Ich kann folgendes für dich tun:"\
]\
},\
"abbrechen": {\
"match": "\/?abbrechen",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"(%me%) ",\
"Dialog abgebrochen."\
] \
},\
"beenden": {\
"match": "\/?beenden",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"(%me%) ",\
"Dialog beendet."\
]\
}\
}

attr meta_Dialog DbLogExclude .*
attr meta_Dialog allowed everyone
attr meta_Dialog room msg
</pre>

Aufgrund der Komplexität eines Dialogs mit JSON ist es am praktikabelsten, zunächst einen leeren Dialog zu definieren:
<pre>
define <name> msgDialog {}
</pre>

Anschließend kann die '''DEF''' in der Detail-Ansicht des Dialog-Device bearbeitet werden. Jeder Dialog basiert auf der folgenden Struktur von einfach bis komplex.

<pre>
{
"<TRIGGER>": {
"match": "<regex>",
"setOnly": (true|false),
"commands": "(fhem command|{perl code})",
"message": [
"{perl code}",
"text"
],
"<NEXT TRIGGER 1>": {
...
},
"<NEXT TRIGGER 2>": {
...
}
}
}
</pre>

Um den JSON-Teil der Dialoge zu testen, empfiehlt sich ein Besuch auf https://jsonlint.com/
Hier kann der selbst geschriebene JSON-Code validiert werden.

;TRIGGER
:Kann ein beliebiger Text sein. Es wird geprüft ob die eingehende Nachricht damit übereinstimmt. Falls ja, wird der Dialog an dieser Stelle fortgesetzt.

;match
:Wenn nicht nur genau eine Nachricht zugelassen werden soll, kann noch eine regex angegeben werden. Die regex muss auf die gesamte eingehnde Nachricht :zutreffen.

;setOnly
:Kann optional auf true oder false gestellt werden. In beiden fällen wird der TRIGGER dann nicht bei "get <name> trigger" zurück gegeben.
:Wenn setOnly auf "true" gestellt wird, kann der Dialog an dieser Stelle nicht durch eingehende Nachrichten ausgelöst werden, sondern nur über "get <name> say TRIGGER". Dies kann dazu genutzt werden um einen Dialog aus :FHEM heraus zu initiieren.

;commands
:Kann einen einzelnen oder mehrere Befehle enthalten:
<pre>
"commands":
"single command"
"commands": [
"command 1",
"command 2",
"{perl command}"
]
</pre>

;message
:Kann einen einzelnen oder mehrere Textte enthalten die mit einen Zeilenumbruch verbunden werden:
<pre>
"message": "text"
</pre>
<pre>
"message": [
"text 1",
"text 2",
"{return from perl command}"
]
</pre>

Bei mehrstufigen Dialogen wird diese Struktur ineinander verschachtelt angegeben.
Es werden Variablen und Platzhalter, welche unter dem Attribut evalSpecials definiert werden, ausgewertet.

=== Variablen ===
*$SELF: Eigenname des msgDialog
*$message: eingegangene Nachricht
*$recipient: Name des Dialogpartners

=== Attribute ===
*allowed: Liste mit allen RESIDENTS und ROOMMATE die für diesen Dialog berechtigt sind.
*disable: [0|1] Dialog ist aktiviert|deaktiviert.
*disabledForIntervals: HH:MM-HH:MM HH:MM-HH-MM ...
*evalSpecials: key1=value1 key2=value2 ...Leerzeichen getrennte Liste von Name=Wert Paaren. Wert kann Leerzeichen enthalten, falls es in "" oder {} eingeschlossen ist. Wert wird als perl-Ausdruck ausgewertet, falls es in {} eingeschlossen ist. In der DEF werden %Name% Zeichenketten durch den zugehörigen Wert ersetzt. Dieses Attribut ist als "msgDialog_evalSpecials" im msgConfig Gerät vorhanden. Wenn der selbe Name im msgConfig und msgDialog definiert wurde, wird der Wert aus msgDialog verwendet.
*msgCommand <command>: Befehl der zum Versenden einer Nachricht verwendet wird. Die Vorgabe ist "msg push \@$recipients $message" Dieses Attribut ist als "msgDialog_msgCommand" im msgConfig Gerät vorhanden.

=== set ===
*reset: Setzt den Dialog für alle Benutzer zurück.
*say [@<recipient1>[,<recipient2>,...]] <TRIGGER>[|<NEXT TRIGGER>|...]: Der Dialog wird für alle angegeben Empänger an der angegeben Stelle fortgeführt. Sind keine Empfänger angegeben wird der Dialog für alle unter dem Attribut allowed angegebenen Empfänger fortgeführt.
*updateAllowed: Aktualisiert die Auswahl für das Attribut allowed.

=== get ===
*trigger: Listet alle TRIGGER der ersten Ebene auf bei denen nicht setOnly angegeben ist.

=== READINGS ===
*$recipient_history: Durch | getrennte Liste von TRIGGER um den aktuellen Zustand des Dialogs zu sichern. Für jeden Dialogpartner wird ein Reading angelegt. Wenn der Dialog beendet ist wird das Reading zurückgesetzt.

== Beispiele ==

==== Programmierung der Waschmaschine ====
Das ist ein Beispiel zur Programmierung einer Waschmaschine wie auch oben im Video zu sehen:
<pre>
defmod Waschmaschine_Dialog msgDialog { "Waschmaschine": {\
"message": [\
"{return('(Zeitprogramm stoppen) ') if(ReadingsVal('%controlUnit%', 'controlMode', '') eq 'auto')}",\
"{return('(programmieren) ') if(ReadingsVal('%actor%', 'state', '') ne 'on')}",\
"{return('(einschalten) ') if(ReadingsVal('%actor%', 'state', '') ne 'on')}",\
"(Verlaufsdiagramm) ",\
"(abbrechen) ",\
"{return('Waschmaschine: ' . (ReadingsVal('%actor%', 'state', '') eq 'on' ? 'eingeschaltet' : 'ausgeschaltet'))}",\
"{return('Modus: ' . (ReadingsVal('%controlUnit%', 'controlMode', '') eq 'auto' ? 'Automatik' : 'Manuell (' . ReadingsVal('%controlUnit%', 'time', '') . ')'))}"\
],\
"Zeitprogramm stoppen": {\
"commands": "set %controlUnit% controlMode manual",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Das Zeitprogramm wurde gestoppt."\
]\
},\
"programmieren": {\
"message": [\
"(bestätigen|zurück|abbrechen) ",\
"( 00:00 | 00:15 | 00:30 | 00:45 ) ",\
"( 01:00 | 01:15 | 01:30 | 01:45 ) ",\
"( 02:00 | 02:15 | 02:30 | 02:45 ) ",\
"( 03:00 | 03:15 | 03:30 | 03:45 ) ",\
"( 04:00 | 04:15 | 04:30 | 04:45 ) ",\
"( 05:00 | 05:15 | 05:30 | 05:45 ) ",\
"( 06:00 | 06:15 | 06:30 | 06:45 ) ",\
"( 07:00 | 07:15 | 07:30 | 07:45 ) ",\
"( 08:00 | 08:15 | 08:30 | 08:45 ) ",\
"( 09:00 | 09:15 | 09:30 | 09:45 ) ",\
"( 10:00 | 10:15 | 10:30 | 10:45 ) ",\
"( 11:00 | 11:15 | 11:30 | 11:45 ) ",\
"( 12:00 | 12:15 | 12:30 | 12:45 ) ",\
"( 13:00 | 13:15 | 13:30 | 13:45 ) ",\
"( 14:00 | 14:15 | 14:30 | 14:45 ) ",\
"( 15:00 | 15:15 | 15:30 | 15:45 ) ",\
"( 16:00 | 16:15 | 16:30 | 16:45 ) ",\
"( 17:00 | 17:15 | 17:30 | 17:45 ) ",\
"( 18:00 | 18:15 | 18:30 | 18:45 ) ",\
"( 19:00 | 19:15 | 19:30 | 19:45 ) ",\
"( 20:00 | 20:15 | 20:30 | 20:45 ) ",\
"( 21:00 | 21:15 | 21:30 | 21:45 ) ",\
"( 22:00 | 22:15 | 22:30 | 22:45 ) ",\
"( 23:00 | 23:15 | 23:30 | 23:45 ) ",\
"Wann soll die Wäsche fertig sein?",\
"Bitte Uhrzeit in HH:MM angeben.",\
"Aktuell ist [%controlUnit%:time] Uhr eingestellt."\
],\
"Uhrzeit": {\
"match": " ?([0-1][0-9]|2[0-3]):[0-5][0-9] ?",\
"commands": [\
"set %controlUnit% time $message",\
"set $SELF say @$recipient Waschmaschine|programmieren|bestätigen"\
]\
},\
"bestätigen": {\
"commands": "set %controlUnit% controlMode auto",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Das Zeitprogramm wurde eingestellt.",\
"Die Wäsche wird voraussichtlich um [%controlUnit%:time] Uhr fertig sein.",\
"Bitte die Waschmaschine vorbereiten."\
]\
}\
},\
"einschalten": {\
"commands": [\
"set %controlUnit% controlMode manual",\
"set %actor% on"\
]\
},\
"Verlaufsdiagramm": {\
"commands": "set %TelegramBot% cmdSend {plotAsPng('%plot%')}",\
"message": "TelegramBot_MTYPE=queryInline (%me%) $message"\
}\
},\
"auto": {\
"setOnly": true,\
"commands": [\
"set %actor% on",\
"set %controlUnit% controlMode manual"\
],\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine wurde automatisch eingeschaltet."\
]\
},\
"manual": {\
"setOnly": true,\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine wurde manuell eingeschaltet."\
]\
},\
"done": {\
"setOnly": true,\
"commands": "set %actor% off",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine ist fertig."\
]\
}\
}
attr Waschmaschine_Dialog evalSpecials actor=HM_2C10D8_Sw\
controlUnit=Waschkeller_washer_controlUnit\
plot=Waschkeller_washer_SVG
</pre>

== TelegramBot ==

In Telegram gibt es die Möglichkeit die Art des Keyboards zu ändern. Links das normale Keyboard, rechts das Inline Keyboard.

[[Datei:76msgDialog menu.png|Normales Keyboard]] [[Datei:76msgDialog menu inline.PNG|Inline Keyboard]]

In diesem '''[https://youtu.be/oRDy2918mVI Video]''' wird Telegram mit einem Inline Keyboard verwendet.

Um eine Nachricht bei Telegram zu verändern, gibt es den Befehl "queryEditInline".
Dafür wird die MsgId von der Nachricht benötigt. Das erledigt ein notify, welches die msgId pro Peer abspeichert:

<pre>
defmod sentMsgIdByPeerId notify .+:sentMsgId.+ {\
return unless($TYPE eq "TelegramBot");;\
\
my $dev_hash = $defs{$NAME};;\
my $sentMsgId = ReadingsVal($NAME, "sentMsgId", "");;\
my $sentMsgPeerId = ReadingsVal($NAME, "sentMsgPeerId", "");;\
my ($contact) = devspec2array("TYPE=(ROOMMATE|GUEST):FILTER=msgContactPush=.*$sentMsgPeerId.*");;\
\
readingsSingleUpdate($dev_hash, "$contact\_sentMsgId", $sentMsgId, 1);;\
}
attr sentMsgIdByPeerId devStateIcon {ReadingsVal($name, "state", "inactive") eq "active" ? ".*:ios-on-blue:inactive" : ".*:ios-off:active"}
attr sentMsgIdByPeerId icon audio_mic
attr sentMsgIdByPeerId room msg
</pre>

Danach wird der Message-Befehl von
<pre>
set <TelegramBot> message
</pre>
auf
<pre>
set <TelegramBot> queryEditInline
</pre>
geändert. Dafür wird ein [[cmdalias]] verwendet:

<pre>
defmod message2queryEditInline cmdalias set .+ message (.|\n)+ AS {\
my ($NAME, $cmd, $message) = split(/[\s]+/, $EVENT, 3);;\
my $TYPE = InternalVal($NAME, "TYPE", "");;\
(my $recipient, $message) = ($message =~ m/(@\S+)? (.+)/s);;\
\
if($TYPE eq "TelegramBot" && $recipient){\
my ($contact) = devspec2array("TYPE=(ROOMMATE|GUEST):FILTER=msgContactPush=.*$recipient.*");;\
my $sentMsgId = ReadingsVal($NAME, "$contact\_sentMsgId", "");;\
\
if($sentMsgId ne ""){\
fhem("set $NAME queryEditInline $sentMsgId $recipient $message");;\
}\
else{\
fhem("set $NAME queryInline $recipient $message");;\
}\
}\
else{\
fhem("set $EVENT");;\
}\
}
attr message2queryEditInline room msg
</pre>

Um wieder zurück zum normalen Keyboard zu gelangen genügt es, das notify und den cmdAlias zu deaktivieren.
Das kann komfortabel über ein notify und einen dummy erledigt werden:
<pre>
defmod inline_normal.NOT notify inline_normal.DUM:.* {\
if ("$EVENT" =~ "on") {\
fhem "set sentMsgIdByPeerId active;; attr message2queryEditInline disable 0";;\
} \
elsif ("$EVENT" =~ "off") {\
fhem "set sentMsgIdByPeerId inactive;; attr message2queryEditInline disable 1";;\
}\
}
</pre>

Weitere Infos zum Thema Inline Keyboard sind in der Antwort #10 im Forum zu finden (siehe Link unten).

== JABBER ==
Hier wird die Verwendung mit Jabber beschrieben...

== WhatsApp ==
Hier wird die Verwendung mit yowsup/WhatsApp beschrieben...

== Links ==
* Thread über das Modul im {{Link2Forum|Topic=77297|LinkText=FHEM Forum}}

[[Kategorie:Hilfsmodul]]

MsgDialog

2017-10-31T09:38:42Z

Binford6000: /* msgConfig */

{{Infobox Modul
|ModPurpose=Dialoge für Sofortnachrichten über TelegramBot, Jabber und WhatsApp
|ModType=h
|ModForumArea=Frontends
|ModTechName=76_msgDialog.pm
|ModOwner={{Link2FU|4106|igami}}
}}

== Zielsetzung ==
Ein zentrale Anforderung an die Haus-Automation ist die Kommunikation mit den Anwendern. Fast jeder Anwender möchte über bestimmte Ereignisse informiert werden und Einstellungen vornehmen. FHEM bietet schon seit längerem die Unterstützung für verschiedene Messaging Dienste an.
Mit dem msgDialog Modul können vordefinierte Dialoge erstellt werden. Die Kommunikation erfolgt dabei über den [[msg]] Befehl welcher zurzeit die bidirektionale Kommunikation über [[TelegramBot]], [[Jabber]] und [[yowsup]] (WhatsApp) unterstützt. Eingehende Nachrichten werden einem ROMMATE oder GUEST zugeordnet. Darüber werden auch die Berechtigungen für die einzelnen Dialoge festgelegt.
Die grundlegende Bedienung wird in diesem '''[https://youtu.be/yiCOTeR1YVQ Video]''' am Beispiel von TelegramBot gezeigt.

== Konfiguration ==

=== Voraussetzungen ===
Für dieses Modul wird das Perl JSON Modul benötigt. Auf einem Debian-basierten System (z.B RaspberryPI o.ä.) kann man das mit dem folgenden Befehl installieren:
<pre>
sudo apt-get install libjson-perl
</pre>

=== Hinweis zu den Code Beispielen ===
Es handelt sich bei den Beispielen um eine Raw definition, siehe auch [[Import_von_Code_Snippets]]

=== msgConfig ===

Als erstes benötigt man ein definiertes msgConfig device:

<pre>
defmod myMsgConfig msgConfig
attr myMsgConfig msgDialog_evalSpecials me=<Aktivierungswort bzw. -Nachricht>
TelegramBot=<Name des TelegramBot-device>
attr myMsgConfig msgContactPush TelegramBot
attr myMsgConfig room msg
</pre>

Falls bereits vorhanden, müssen natürlich nur die fehlenden Attribute gesetzt werden.

;msgDialog_evalSpecials
:key1=value1 key2=value2 ... Leerzeichen getrennte Liste von Name=Wert Paaren. Wert kann Leerzeichen enthalten, falls es in "" oder {} eingeschlossen :ist. Wert wird als perl-Ausdruck ausgewertet, falls es in {} eingeschlossen ist. In der DEF werden %Name% Zeichenketten durch den zugehörigen Wert :ersetzt. Wenn der selbe Name im msgConfig und msgDialog definiert wurde, wird der Wert aus msgDialog verwendet.

;msgDialog_msgCommand <command>
:Befehl zum Versenden einer Nachricht. Die Vorgabe ist "msg push \@$recipients $message". Wenn nicht gesetzt, wird die Vorgabe verwendet.

=== ROOMMATE / GUEST ===
Für jeden Dialog kann festgelegt werden welche Person dazu berechtigt ist. Dazu sind Geräte vom Typ ROOMMATE oder GUEST mit definiertem msgContactPush Attribut erforderlich. Es ist darauf zu achten, dass das Reading fhemMsgRcvPush ein Event erzeugt. Siehe auch Attribut "allowed" in msgDialog.

=== Define ===

Definition des metaDialogs:
Zur Auflistung aller berechtigten Dialoge dient - was sonst - ein Dialog!

<pre>
defmod meta_Dialog msgDialog {\
"%me%": {\
"match": "\/?(start|%me%)",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"{return('(' . join(') (', sort(split('\n', fhem('get TYPE=msgDialog:FILTER=NAME!=$SELF:FILTER=allowed=.*($recipient|everyone).* trigger')))) . ') ')}",\
"(abbrechen) ",\
"Ich kann folgendes für dich tun:"\
]\
},\
"abbrechen": {\
"match": "\/?abbrechen",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"(%me%) ",\
"Dialog abgebrochen."\
] \
},\
"beenden": {\
"match": "\/?beenden",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"(%me%) ",\
"Dialog beendet."\
]\
}\
}

attr meta_Dialog DbLogExclude .*
attr meta_Dialog allowed everyone
attr meta_Dialog room msg
</pre>

Aufgrund der Komplexität eines Dialogs mit JSON ist es am praktikabelsten, zunächst einen leeren Dialog zu definieren:
<pre>
define <name> msgDialog {}
</pre>

Anschließend kann die DEF in der Detail-Ansicht des Dialog-Device bearbeitet werden. Jeder Dialog basiert auf der folgenden Struktur von einfach bis komplex.

<pre>
{
"<TRIGGER>": {
"match": "<regex>",
"setOnly": (true|false),
"commands": "(fhem command|{perl code})",
"message": [
"{perl code}",
"text"
],
"<NEXT TRIGGER 1>": {
...
},
"<NEXT TRIGGER 2>": {
...
}
}
}
</pre>

Um den JSON-Teil der Dialoge zu testen, empfiehlt sich ein Besuch auf https://jsonlint.com/
Hier kann der selbst geschriebene JSON-Code validiert werden.

;TRIGGER
:Kann ein beliebiger Text sein. Es wird geprüft ob die eingehende Nachricht damit übereinstimmt. Falls ja, wird der Dialog an dieser Stelle fortgesetzt.

;match
:Wenn nicht nur genau eine Nachricht zugelassen werden soll, kann noch eine regex angegeben werden. Die regex muss auf die gesamte eingehnde Nachricht :zutreffen.

;setOnly
:Kann optional auf true oder false gestellt werden. In beiden fällen wird der TRIGGER dann nicht bei "get <name> trigger" zurück gegeben.
:Wenn setOnly auf "true" gestellt wird, kann der Dialog an dieser Stelle nicht durch eingehende Nachrichten ausgelöst werden, sondern nur über "get <name> say TRIGGER". Dies kann dazu genutzt werden um einen Dialog aus :FHEM heraus zu initiieren.

;commands
:Kann einen einzelnen oder mehrere Befehle enthalten:
<pre>
"commands":
"single command"
"commands": [
"command 1",
"command 2",
"{perl command}"
]
</pre>

;message
:Kann einen einzelnen oder mehrere Textte enthalten die mit einen Zeilenumbruch verbunden werden:
<pre>
"message": "text"
</pre>
<pre>
"message": [
"text 1",
"text 2",
"{return from perl command}"
]
</pre>

Bei mehrstufigen Dialogen wird diese Struktur ineinander verschachtelt angegeben.
Es werden Variablen und Platzhalter, welche unter dem Attribut evalSpecials definiert werden, ausgewertet.

=== Variablen ===
*$SELF: Eigenname des msgDialog
*$message: eingegangene Nachricht
*$recipient: Name des Dialogpartners

=== Attribute ===
*allowed: Liste mit allen RESIDENTS und ROOMMATE die für diesen Dialog berechtigt sind.
*disable: [0|1] Dialog ist aktiviert|deaktiviert.
*disabledForIntervals: HH:MM-HH:MM HH:MM-HH-MM ...
*evalSpecials: key1=value1 key2=value2 ...Leerzeichen getrennte Liste von Name=Wert Paaren. Wert kann Leerzeichen enthalten, falls es in "" oder {} eingeschlossen ist. Wert wird als perl-Ausdruck ausgewertet, falls es in {} eingeschlossen ist. In der DEF werden %Name% Zeichenketten durch den zugehörigen Wert ersetzt. Dieses Attribut ist als "msgDialog_evalSpecials" im msgConfig Gerät vorhanden. Wenn der selbe Name im msgConfig und msgDialog definiert wurde, wird der Wert aus msgDialog verwendet.
*msgCommand <command>: Befehl der zum Versenden einer Nachricht verwendet wird. Die Vorgabe ist "msg push \@$recipients $message" Dieses Attribut ist als "msgDialog_msgCommand" im msgConfig Gerät vorhanden.

=== set ===
*reset: Setzt den Dialog für alle Benutzer zurück.
*say [@<recipient1>[,<recipient2>,...]] <TRIGGER>[|<NEXT TRIGGER>|...]: Der Dialog wird für alle angegeben Empänger an der angegeben Stelle fortgeführt. Sind keine Empfänger angegeben wird der Dialog für alle unter dem Attribut allowed angegebenen Empfänger fortgeführt.
*updateAllowed: Aktualisiert die Auswahl für das Attribut allowed.

=== get ===
*trigger: Listet alle TRIGGER der ersten Ebene auf bei denen nicht setOnly angegeben ist.

=== READINGS ===
*$recipient_history: Durch | getrennte Liste von TRIGGER um den aktuellen Zustand des Dialogs zu sichern. Für jeden Dialogpartner wird ein Reading angelegt. Wenn der Dialog beendet ist wird das Reading zurückgesetzt.

== Beispiele ==

==== Programmierung der Waschmaschine ====
Das ist ein Beispiel zur Programmierung einer Waschmaschine wie auch oben im Video zu sehen:
<pre>
defmod Waschmaschine_Dialog msgDialog { "Waschmaschine": {\
"message": [\
"{return('(Zeitprogramm stoppen) ') if(ReadingsVal('%controlUnit%', 'controlMode', '') eq 'auto')}",\
"{return('(programmieren) ') if(ReadingsVal('%actor%', 'state', '') ne 'on')}",\
"{return('(einschalten) ') if(ReadingsVal('%actor%', 'state', '') ne 'on')}",\
"(Verlaufsdiagramm) ",\
"(abbrechen) ",\
"{return('Waschmaschine: ' . (ReadingsVal('%actor%', 'state', '') eq 'on' ? 'eingeschaltet' : 'ausgeschaltet'))}",\
"{return('Modus: ' . (ReadingsVal('%controlUnit%', 'controlMode', '') eq 'auto' ? 'Automatik' : 'Manuell (' . ReadingsVal('%controlUnit%', 'time', '') . ')'))}"\
],\
"Zeitprogramm stoppen": {\
"commands": "set %controlUnit% controlMode manual",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Das Zeitprogramm wurde gestoppt."\
]\
},\
"programmieren": {\
"message": [\
"(bestätigen|zurück|abbrechen) ",\
"( 00:00 | 00:15 | 00:30 | 00:45 ) ",\
"( 01:00 | 01:15 | 01:30 | 01:45 ) ",\
"( 02:00 | 02:15 | 02:30 | 02:45 ) ",\
"( 03:00 | 03:15 | 03:30 | 03:45 ) ",\
"( 04:00 | 04:15 | 04:30 | 04:45 ) ",\
"( 05:00 | 05:15 | 05:30 | 05:45 ) ",\
"( 06:00 | 06:15 | 06:30 | 06:45 ) ",\
"( 07:00 | 07:15 | 07:30 | 07:45 ) ",\
"( 08:00 | 08:15 | 08:30 | 08:45 ) ",\
"( 09:00 | 09:15 | 09:30 | 09:45 ) ",\
"( 10:00 | 10:15 | 10:30 | 10:45 ) ",\
"( 11:00 | 11:15 | 11:30 | 11:45 ) ",\
"( 12:00 | 12:15 | 12:30 | 12:45 ) ",\
"( 13:00 | 13:15 | 13:30 | 13:45 ) ",\
"( 14:00 | 14:15 | 14:30 | 14:45 ) ",\
"( 15:00 | 15:15 | 15:30 | 15:45 ) ",\
"( 16:00 | 16:15 | 16:30 | 16:45 ) ",\
"( 17:00 | 17:15 | 17:30 | 17:45 ) ",\
"( 18:00 | 18:15 | 18:30 | 18:45 ) ",\
"( 19:00 | 19:15 | 19:30 | 19:45 ) ",\
"( 20:00 | 20:15 | 20:30 | 20:45 ) ",\
"( 21:00 | 21:15 | 21:30 | 21:45 ) ",\
"( 22:00 | 22:15 | 22:30 | 22:45 ) ",\
"( 23:00 | 23:15 | 23:30 | 23:45 ) ",\
"Wann soll die Wäsche fertig sein?",\
"Bitte Uhrzeit in HH:MM angeben.",\
"Aktuell ist [%controlUnit%:time] Uhr eingestellt."\
],\
"Uhrzeit": {\
"match": " ?([0-1][0-9]|2[0-3]):[0-5][0-9] ?",\
"commands": [\
"set %controlUnit% time $message",\
"set $SELF say @$recipient Waschmaschine|programmieren|bestätigen"\
]\
},\
"bestätigen": {\
"commands": "set %controlUnit% controlMode auto",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Das Zeitprogramm wurde eingestellt.",\
"Die Wäsche wird voraussichtlich um [%controlUnit%:time] Uhr fertig sein.",\
"Bitte die Waschmaschine vorbereiten."\
]\
}\
},\
"einschalten": {\
"commands": [\
"set %controlUnit% controlMode manual",\
"set %actor% on"\
]\
},\
"Verlaufsdiagramm": {\
"commands": "set %TelegramBot% cmdSend {plotAsPng('%plot%')}",\
"message": "TelegramBot_MTYPE=queryInline (%me%) $message"\
}\
},\
"auto": {\
"setOnly": true,\
"commands": [\
"set %actor% on",\
"set %controlUnit% controlMode manual"\
],\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine wurde automatisch eingeschaltet."\
]\
},\
"manual": {\
"setOnly": true,\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine wurde manuell eingeschaltet."\
]\
},\
"done": {\
"setOnly": true,\
"commands": "set %actor% off",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine ist fertig."\
]\
}\
}
attr Waschmaschine_Dialog evalSpecials actor=HM_2C10D8_Sw\
controlUnit=Waschkeller_washer_controlUnit\
plot=Waschkeller_washer_SVG
</pre>

== TelegramBot ==

In Telegram gibt es die Möglichkeit die Art des Keyboards zu ändern. Links das normale Keyboard, rechts das Inline Keyboard.

[[Datei:76msgDialog menu.png|Normales Keyboard]] [[Datei:76msgDialog menu inline.PNG|Inline Keyboard]]

In diesem '''[https://youtu.be/oRDy2918mVI Video]''' wird Telegram mit einem Inline Keyboard verwendet.

Um eine Nachricht bei Telegram zu verändern, gibt es den Befehl "queryEditInline".
Dafür wird die MsgId von der Nachricht benötigt. Das erledigt ein notify, welches die msgId pro Peer abspeichert:

<pre>
defmod sentMsgIdByPeerId notify .+:sentMsgId.+ {\
return unless($TYPE eq "TelegramBot");;\
\
my $dev_hash = $defs{$NAME};;\
my $sentMsgId = ReadingsVal($NAME, "sentMsgId", "");;\
my $sentMsgPeerId = ReadingsVal($NAME, "sentMsgPeerId", "");;\
my ($contact) = devspec2array("TYPE=(ROOMMATE|GUEST):FILTER=msgContactPush=.*$sentMsgPeerId.*");;\
\
readingsSingleUpdate($dev_hash, "$contact\_sentMsgId", $sentMsgId, 1);;\
}
attr sentMsgIdByPeerId devStateIcon {ReadingsVal($name, "state", "inactive") eq "active" ? ".*:ios-on-blue:inactive" : ".*:ios-off:active"}
attr sentMsgIdByPeerId icon audio_mic
attr sentMsgIdByPeerId room msg
</pre>

Danach wird der Message-Befehl von
<pre>
set <TelegramBot> message
</pre>
auf
<pre>
set <TelegramBot> queryEditInline
</pre>
geändert. Dafür wird ein [[cmdalias]] verwendet:

<pre>
defmod message2queryEditInline cmdalias set .+ message (.|\n)+ AS {\
my ($NAME, $cmd, $message) = split(/[\s]+/, $EVENT, 3);;\
my $TYPE = InternalVal($NAME, "TYPE", "");;\
(my $recipient, $message) = ($message =~ m/(@\S+)? (.+)/s);;\
\
if($TYPE eq "TelegramBot" && $recipient){\
my ($contact) = devspec2array("TYPE=(ROOMMATE|GUEST):FILTER=msgContactPush=.*$recipient.*");;\
my $sentMsgId = ReadingsVal($NAME, "$contact\_sentMsgId", "");;\
\
if($sentMsgId ne ""){\
fhem("set $NAME queryEditInline $sentMsgId $recipient $message");;\
}\
else{\
fhem("set $NAME queryInline $recipient $message");;\
}\
}\
else{\
fhem("set $EVENT");;\
}\
}
attr message2queryEditInline room msg
</pre>

Um wieder zurück zum normalen Keyboard zu gelangen genügt es, das notify und den cmdAlias zu deaktivieren.
Das kann komfortabel über ein notify und einen dummy erledigt werden:
<pre>
defmod inline_normal.NOT notify inline_normal.DUM:.* {\
if ("$EVENT" =~ "on") {\
fhem "set sentMsgIdByPeerId active;; attr message2queryEditInline disable 0";;\
} \
elsif ("$EVENT" =~ "off") {\
fhem "set sentMsgIdByPeerId inactive;; attr message2queryEditInline disable 1";;\
}\
}
</pre>

Weitere Infos zum Thema Inline Keyboard sind in der Antwort #10 im Forum zu finden (siehe Link unten).

== JABBER ==
Hier wird die Verwendung mit Jabber beschrieben...

== WhatsApp ==
Hier wird die Verwendung mit yowsup/WhatsApp beschrieben...

== Links ==
* Thread über das Modul im {{Link2Forum|Topic=77297|LinkText=FHEM Forum}}

[[Kategorie:Hilfsmodul]]

MsgDialog

2017-10-31T09:35:57Z

Binford6000: /* Define */

{{Infobox Modul
|ModPurpose=Dialoge für Sofortnachrichten über TelegramBot, Jabber und WhatsApp
|ModType=h
|ModForumArea=Frontends
|ModTechName=76_msgDialog.pm
|ModOwner={{Link2FU|4106|igami}}
}}

== Zielsetzung ==
Ein zentrale Anforderung an die Haus-Automation ist die Kommunikation mit den Anwendern. Fast jeder Anwender möchte über bestimmte Ereignisse informiert werden und Einstellungen vornehmen. FHEM bietet schon seit längerem die Unterstützung für verschiedene Messaging Dienste an.
Mit dem msgDialog Modul können vordefinierte Dialoge erstellt werden. Die Kommunikation erfolgt dabei über den [[msg]] Befehl welcher zurzeit die bidirektionale Kommunikation über [[TelegramBot]], [[Jabber]] und [[yowsup]] (WhatsApp) unterstützt. Eingehende Nachrichten werden einem ROMMATE oder GUEST zugeordnet. Darüber werden auch die Berechtigungen für die einzelnen Dialoge festgelegt.
Die grundlegende Bedienung wird in diesem '''[https://youtu.be/yiCOTeR1YVQ Video]''' am Beispiel von TelegramBot gezeigt.

== Konfiguration ==

=== Voraussetzungen ===
Für dieses Modul wird das Perl JSON Modul benötigt. Auf einem Debian-basierten System (z.B RaspberryPI o.ä.) kann man das mit dem folgenden Befehl installieren:
<pre>
sudo apt-get install libjson-perl
</pre>

=== Hinweis zu den Code Beispielen ===
Es handelt sich bei den Beispielen um eine Raw definition, siehe auch [[Import_von_Code_Snippets]]

=== msgConfig ===

Als erstes benötigt man ein definiertes msgConfig device:

<pre>
defmod myMsgConfig msgConfig
attr myMsgConfig msgDialog_evalSpecials me=<Aktivierungswort bzw. -Nachricht>
TelegramBot=<Name des TelegramBot-device>
attr myMsgConfig msgContactPush TelegramBot
attr myMsgConfig room msg
</pre>

Falls bereits vorhanden, müssen natürlich nur die fehlenden Attribute gesetzt werden.

;msgDialog_evalSpecials
:key1=value1 key2=value2 ... Leerzeichen getrennte Liste von Name=Wert Paaren. Wert kann Leerzeichen enthalten, falls es in "" oder {} eingeschlossen :ist. Wert wird als perl-Ausdruck ausgewertet, falls es in {} eingeschlossen ist. In der DEF werden %Name% Zeichenketten durch den zugehörigen Wert :ersetzt. Wenn der selbe Name im msgConfig und msgDialog definiert wurde, wird der Wert aus msgDialog verwendet.

;msgDialog_msgCommand <command>
:Befehl zum Versenden einer Nachricht. Die Vorgabe ist "msg push \@$recipients $message"

=== ROOMMATE / GUEST ===
Für jeden Dialog kann festgelegt werden welche Person dazu berechtigt ist. Dazu sind Geräte vom Typ ROOMMATE oder GUEST mit definiertem msgContactPush Attribut erforderlich. Es ist darauf zu achten, dass das Reading fhemMsgRcvPush ein Event erzeugt. Siehe auch Attribut "allowed" in msgDialog.

=== Define ===

Definition des metaDialogs:
Zur Auflistung aller berechtigten Dialoge dient - was sonst - ein Dialog!

<pre>
defmod meta_Dialog msgDialog {\
"%me%": {\
"match": "\/?(start|%me%)",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"{return('(' . join(') (', sort(split('\n', fhem('get TYPE=msgDialog:FILTER=NAME!=$SELF:FILTER=allowed=.*($recipient|everyone).* trigger')))) . ') ')}",\
"(abbrechen) ",\
"Ich kann folgendes für dich tun:"\
]\
},\
"abbrechen": {\
"match": "\/?abbrechen",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"(%me%) ",\
"Dialog abgebrochen."\
] \
},\
"beenden": {\
"match": "\/?beenden",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"(%me%) ",\
"Dialog beendet."\
]\
}\
}

attr meta_Dialog DbLogExclude .*
attr meta_Dialog allowed everyone
attr meta_Dialog room msg
</pre>

Aufgrund der Komplexität eines Dialogs mit JSON ist es am praktikabelsten, zunächst einen leeren Dialog zu definieren:
<pre>
define <name> msgDialog {}
</pre>

Anschließend kann die DEF in der Detail-Ansicht des Dialog-Device bearbeitet werden. Jeder Dialog basiert auf der folgenden Struktur von einfach bis komplex.

<pre>
{
"<TRIGGER>": {
"match": "<regex>",
"setOnly": (true|false),
"commands": "(fhem command|{perl code})",
"message": [
"{perl code}",
"text"
],
"<NEXT TRIGGER 1>": {
...
},
"<NEXT TRIGGER 2>": {
...
}
}
}
</pre>

Um den JSON-Teil der Dialoge zu testen, empfiehlt sich ein Besuch auf https://jsonlint.com/
Hier kann der selbst geschriebene JSON-Code validiert werden.

;TRIGGER
:Kann ein beliebiger Text sein. Es wird geprüft ob die eingehende Nachricht damit übereinstimmt. Falls ja, wird der Dialog an dieser Stelle fortgesetzt.

;match
:Wenn nicht nur genau eine Nachricht zugelassen werden soll, kann noch eine regex angegeben werden. Die regex muss auf die gesamte eingehnde Nachricht :zutreffen.

;setOnly
:Kann optional auf true oder false gestellt werden. In beiden fällen wird der TRIGGER dann nicht bei "get <name> trigger" zurück gegeben.
:Wenn setOnly auf "true" gestellt wird, kann der Dialog an dieser Stelle nicht durch eingehende Nachrichten ausgelöst werden, sondern nur über "get <name> say TRIGGER". Dies kann dazu genutzt werden um einen Dialog aus :FHEM heraus zu initiieren.

;commands
:Kann einen einzelnen oder mehrere Befehle enthalten:
<pre>
"commands":
"single command"
"commands": [
"command 1",
"command 2",
"{perl command}"
]
</pre>

;message
:Kann einen einzelnen oder mehrere Textte enthalten die mit einen Zeilenumbruch verbunden werden:
<pre>
"message": "text"
</pre>
<pre>
"message": [
"text 1",
"text 2",
"{return from perl command}"
]
</pre>

Bei mehrstufigen Dialogen wird diese Struktur ineinander verschachtelt angegeben.
Es werden Variablen und Platzhalter, welche unter dem Attribut evalSpecials definiert werden, ausgewertet.

=== Variablen ===
*$SELF: Eigenname des msgDialog
*$message: eingegangene Nachricht
*$recipient: Name des Dialogpartners

=== Attribute ===
*allowed: Liste mit allen RESIDENTS und ROOMMATE die für diesen Dialog berechtigt sind.
*disable: [0|1] Dialog ist aktiviert|deaktiviert.
*disabledForIntervals: HH:MM-HH:MM HH:MM-HH-MM ...
*evalSpecials: key1=value1 key2=value2 ...Leerzeichen getrennte Liste von Name=Wert Paaren. Wert kann Leerzeichen enthalten, falls es in "" oder {} eingeschlossen ist. Wert wird als perl-Ausdruck ausgewertet, falls es in {} eingeschlossen ist. In der DEF werden %Name% Zeichenketten durch den zugehörigen Wert ersetzt. Dieses Attribut ist als "msgDialog_evalSpecials" im msgConfig Gerät vorhanden. Wenn der selbe Name im msgConfig und msgDialog definiert wurde, wird der Wert aus msgDialog verwendet.
*msgCommand <command>: Befehl der zum Versenden einer Nachricht verwendet wird. Die Vorgabe ist "msg push \@$recipients $message" Dieses Attribut ist als "msgDialog_msgCommand" im msgConfig Gerät vorhanden.

=== set ===
*reset: Setzt den Dialog für alle Benutzer zurück.
*say [@<recipient1>[,<recipient2>,...]] <TRIGGER>[|<NEXT TRIGGER>|...]: Der Dialog wird für alle angegeben Empänger an der angegeben Stelle fortgeführt. Sind keine Empfänger angegeben wird der Dialog für alle unter dem Attribut allowed angegebenen Empfänger fortgeführt.
*updateAllowed: Aktualisiert die Auswahl für das Attribut allowed.

=== get ===
*trigger: Listet alle TRIGGER der ersten Ebene auf bei denen nicht setOnly angegeben ist.

=== READINGS ===
*$recipient_history: Durch | getrennte Liste von TRIGGER um den aktuellen Zustand des Dialogs zu sichern. Für jeden Dialogpartner wird ein Reading angelegt. Wenn der Dialog beendet ist wird das Reading zurückgesetzt.

== Beispiele ==

==== Programmierung der Waschmaschine ====
Das ist ein Beispiel zur Programmierung einer Waschmaschine wie auch oben im Video zu sehen:
<pre>
defmod Waschmaschine_Dialog msgDialog { "Waschmaschine": {\
"message": [\
"{return('(Zeitprogramm stoppen) ') if(ReadingsVal('%controlUnit%', 'controlMode', '') eq 'auto')}",\
"{return('(programmieren) ') if(ReadingsVal('%actor%', 'state', '') ne 'on')}",\
"{return('(einschalten) ') if(ReadingsVal('%actor%', 'state', '') ne 'on')}",\
"(Verlaufsdiagramm) ",\
"(abbrechen) ",\
"{return('Waschmaschine: ' . (ReadingsVal('%actor%', 'state', '') eq 'on' ? 'eingeschaltet' : 'ausgeschaltet'))}",\
"{return('Modus: ' . (ReadingsVal('%controlUnit%', 'controlMode', '') eq 'auto' ? 'Automatik' : 'Manuell (' . ReadingsVal('%controlUnit%', 'time', '') . ')'))}"\
],\
"Zeitprogramm stoppen": {\
"commands": "set %controlUnit% controlMode manual",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Das Zeitprogramm wurde gestoppt."\
]\
},\
"programmieren": {\
"message": [\
"(bestätigen|zurück|abbrechen) ",\
"( 00:00 | 00:15 | 00:30 | 00:45 ) ",\
"( 01:00 | 01:15 | 01:30 | 01:45 ) ",\
"( 02:00 | 02:15 | 02:30 | 02:45 ) ",\
"( 03:00 | 03:15 | 03:30 | 03:45 ) ",\
"( 04:00 | 04:15 | 04:30 | 04:45 ) ",\
"( 05:00 | 05:15 | 05:30 | 05:45 ) ",\
"( 06:00 | 06:15 | 06:30 | 06:45 ) ",\
"( 07:00 | 07:15 | 07:30 | 07:45 ) ",\
"( 08:00 | 08:15 | 08:30 | 08:45 ) ",\
"( 09:00 | 09:15 | 09:30 | 09:45 ) ",\
"( 10:00 | 10:15 | 10:30 | 10:45 ) ",\
"( 11:00 | 11:15 | 11:30 | 11:45 ) ",\
"( 12:00 | 12:15 | 12:30 | 12:45 ) ",\
"( 13:00 | 13:15 | 13:30 | 13:45 ) ",\
"( 14:00 | 14:15 | 14:30 | 14:45 ) ",\
"( 15:00 | 15:15 | 15:30 | 15:45 ) ",\
"( 16:00 | 16:15 | 16:30 | 16:45 ) ",\
"( 17:00 | 17:15 | 17:30 | 17:45 ) ",\
"( 18:00 | 18:15 | 18:30 | 18:45 ) ",\
"( 19:00 | 19:15 | 19:30 | 19:45 ) ",\
"( 20:00 | 20:15 | 20:30 | 20:45 ) ",\
"( 21:00 | 21:15 | 21:30 | 21:45 ) ",\
"( 22:00 | 22:15 | 22:30 | 22:45 ) ",\
"( 23:00 | 23:15 | 23:30 | 23:45 ) ",\
"Wann soll die Wäsche fertig sein?",\
"Bitte Uhrzeit in HH:MM angeben.",\
"Aktuell ist [%controlUnit%:time] Uhr eingestellt."\
],\
"Uhrzeit": {\
"match": " ?([0-1][0-9]|2[0-3]):[0-5][0-9] ?",\
"commands": [\
"set %controlUnit% time $message",\
"set $SELF say @$recipient Waschmaschine|programmieren|bestätigen"\
]\
},\
"bestätigen": {\
"commands": "set %controlUnit% controlMode auto",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Das Zeitprogramm wurde eingestellt.",\
"Die Wäsche wird voraussichtlich um [%controlUnit%:time] Uhr fertig sein.",\
"Bitte die Waschmaschine vorbereiten."\
]\
}\
},\
"einschalten": {\
"commands": [\
"set %controlUnit% controlMode manual",\
"set %actor% on"\
]\
},\
"Verlaufsdiagramm": {\
"commands": "set %TelegramBot% cmdSend {plotAsPng('%plot%')}",\
"message": "TelegramBot_MTYPE=queryInline (%me%) $message"\
}\
},\
"auto": {\
"setOnly": true,\
"commands": [\
"set %actor% on",\
"set %controlUnit% controlMode manual"\
],\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine wurde automatisch eingeschaltet."\
]\
},\
"manual": {\
"setOnly": true,\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine wurde manuell eingeschaltet."\
]\
},\
"done": {\
"setOnly": true,\
"commands": "set %actor% off",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine ist fertig."\
]\
}\
}
attr Waschmaschine_Dialog evalSpecials actor=HM_2C10D8_Sw\
controlUnit=Waschkeller_washer_controlUnit\
plot=Waschkeller_washer_SVG
</pre>

== TelegramBot ==

In Telegram gibt es die Möglichkeit die Art des Keyboards zu ändern. Links das normale Keyboard, rechts das Inline Keyboard.

[[Datei:76msgDialog menu.png|Normales Keyboard]] [[Datei:76msgDialog menu inline.PNG|Inline Keyboard]]

In diesem '''[https://youtu.be/oRDy2918mVI Video]''' wird Telegram mit einem Inline Keyboard verwendet.

Um eine Nachricht bei Telegram zu verändern, gibt es den Befehl "queryEditInline".
Dafür wird die MsgId von der Nachricht benötigt. Das erledigt ein notify, welches die msgId pro Peer abspeichert:

<pre>
defmod sentMsgIdByPeerId notify .+:sentMsgId.+ {\
return unless($TYPE eq "TelegramBot");;\
\
my $dev_hash = $defs{$NAME};;\
my $sentMsgId = ReadingsVal($NAME, "sentMsgId", "");;\
my $sentMsgPeerId = ReadingsVal($NAME, "sentMsgPeerId", "");;\
my ($contact) = devspec2array("TYPE=(ROOMMATE|GUEST):FILTER=msgContactPush=.*$sentMsgPeerId.*");;\
\
readingsSingleUpdate($dev_hash, "$contact\_sentMsgId", $sentMsgId, 1);;\
}
attr sentMsgIdByPeerId devStateIcon {ReadingsVal($name, "state", "inactive") eq "active" ? ".*:ios-on-blue:inactive" : ".*:ios-off:active"}
attr sentMsgIdByPeerId icon audio_mic
attr sentMsgIdByPeerId room msg
</pre>

Danach wird der Message-Befehl von
<pre>
set <TelegramBot> message
</pre>
auf
<pre>
set <TelegramBot> queryEditInline
</pre>
geändert. Dafür wird ein [[cmdalias]] verwendet:

<pre>
defmod message2queryEditInline cmdalias set .+ message (.|\n)+ AS {\
my ($NAME, $cmd, $message) = split(/[\s]+/, $EVENT, 3);;\
my $TYPE = InternalVal($NAME, "TYPE", "");;\
(my $recipient, $message) = ($message =~ m/(@\S+)? (.+)/s);;\
\
if($TYPE eq "TelegramBot" && $recipient){\
my ($contact) = devspec2array("TYPE=(ROOMMATE|GUEST):FILTER=msgContactPush=.*$recipient.*");;\
my $sentMsgId = ReadingsVal($NAME, "$contact\_sentMsgId", "");;\
\
if($sentMsgId ne ""){\
fhem("set $NAME queryEditInline $sentMsgId $recipient $message");;\
}\
else{\
fhem("set $NAME queryInline $recipient $message");;\
}\
}\
else{\
fhem("set $EVENT");;\
}\
}
attr message2queryEditInline room msg
</pre>

Um wieder zurück zum normalen Keyboard zu gelangen genügt es, das notify und den cmdAlias zu deaktivieren.
Das kann komfortabel über ein notify und einen dummy erledigt werden:
<pre>
defmod inline_normal.NOT notify inline_normal.DUM:.* {\
if ("$EVENT" =~ "on") {\
fhem "set sentMsgIdByPeerId active;; attr message2queryEditInline disable 0";;\
} \
elsif ("$EVENT" =~ "off") {\
fhem "set sentMsgIdByPeerId inactive;; attr message2queryEditInline disable 1";;\
}\
}
</pre>

Weitere Infos zum Thema Inline Keyboard sind in der Antwort #10 im Forum zu finden (siehe Link unten).

== JABBER ==
Hier wird die Verwendung mit Jabber beschrieben...

== WhatsApp ==
Hier wird die Verwendung mit yowsup/WhatsApp beschrieben...

== Links ==
* Thread über das Modul im {{Link2Forum|Topic=77297|LinkText=FHEM Forum}}

[[Kategorie:Hilfsmodul]]

MsgDialog

2017-10-31T09:35:27Z

Binford6000: /* Define */

{{Infobox Modul
|ModPurpose=Dialoge für Sofortnachrichten über TelegramBot, Jabber und WhatsApp
|ModType=h
|ModForumArea=Frontends
|ModTechName=76_msgDialog.pm
|ModOwner={{Link2FU|4106|igami}}
}}

== Zielsetzung ==
Ein zentrale Anforderung an die Haus-Automation ist die Kommunikation mit den Anwendern. Fast jeder Anwender möchte über bestimmte Ereignisse informiert werden und Einstellungen vornehmen. FHEM bietet schon seit längerem die Unterstützung für verschiedene Messaging Dienste an.
Mit dem msgDialog Modul können vordefinierte Dialoge erstellt werden. Die Kommunikation erfolgt dabei über den [[msg]] Befehl welcher zurzeit die bidirektionale Kommunikation über [[TelegramBot]], [[Jabber]] und [[yowsup]] (WhatsApp) unterstützt. Eingehende Nachrichten werden einem ROMMATE oder GUEST zugeordnet. Darüber werden auch die Berechtigungen für die einzelnen Dialoge festgelegt.
Die grundlegende Bedienung wird in diesem '''[https://youtu.be/yiCOTeR1YVQ Video]''' am Beispiel von TelegramBot gezeigt.

== Konfiguration ==

=== Voraussetzungen ===
Für dieses Modul wird das Perl JSON Modul benötigt. Auf einem Debian-basierten System (z.B RaspberryPI o.ä.) kann man das mit dem folgenden Befehl installieren:
<pre>
sudo apt-get install libjson-perl
</pre>

=== Hinweis zu den Code Beispielen ===
Es handelt sich bei den Beispielen um eine Raw definition, siehe auch [[Import_von_Code_Snippets]]

=== msgConfig ===

Als erstes benötigt man ein definiertes msgConfig device:

<pre>
defmod myMsgConfig msgConfig
attr myMsgConfig msgDialog_evalSpecials me=<Aktivierungswort bzw. -Nachricht>
TelegramBot=<Name des TelegramBot-device>
attr myMsgConfig msgContactPush TelegramBot
attr myMsgConfig room msg
</pre>

Falls bereits vorhanden, müssen natürlich nur die fehlenden Attribute gesetzt werden.

;msgDialog_evalSpecials
:key1=value1 key2=value2 ... Leerzeichen getrennte Liste von Name=Wert Paaren. Wert kann Leerzeichen enthalten, falls es in "" oder {} eingeschlossen :ist. Wert wird als perl-Ausdruck ausgewertet, falls es in {} eingeschlossen ist. In der DEF werden %Name% Zeichenketten durch den zugehörigen Wert :ersetzt. Wenn der selbe Name im msgConfig und msgDialog definiert wurde, wird der Wert aus msgDialog verwendet.

;msgDialog_msgCommand <command>
:Befehl zum Versenden einer Nachricht. Die Vorgabe ist "msg push \@$recipients $message"

=== ROOMMATE / GUEST ===
Für jeden Dialog kann festgelegt werden welche Person dazu berechtigt ist. Dazu sind Geräte vom Typ ROOMMATE oder GUEST mit definiertem msgContactPush Attribut erforderlich. Es ist darauf zu achten, dass das Reading fhemMsgRcvPush ein Event erzeugt. Siehe auch Attribut "allowed" in msgDialog.

=== Define ===

Definition des metaDialogs:
Zur Auflistung aller berechtigten Dialoge dient - was sonst - ein Dialog!

<pre>
defmod meta_Dialog msgDialog {\
"%me%": {\
"match": "\/?(start|%me%)",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"{return('(' . join(') (', sort(split('\n', fhem('get TYPE=msgDialog:FILTER=NAME!=$SELF:FILTER=allowed=.*($recipient|everyone).* trigger')))) . ') ')}",\
"(abbrechen) ",\
"Ich kann folgendes für dich tun:"\
]\
},\
"abbrechen": {\
"match": "\/?abbrechen",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"(%me%) ",\
"Dialog abgebrochen."\
] \
},\
"beenden": {\
"match": "\/?beenden",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"(%me%) ",\
"Dialog beendet."\
]\
}\
}

attr meta_Dialog DbLogExclude .*
attr meta_Dialog allowed everyone
attr meta_Dialog room msg
</pre>

Aufgrund der Komplexität eines Dialogs mit JSON ist es am praktikabelsten, zunächst einen leeren Dialog zu definieren:
<pre>
define <name> msgDialog {}
</pre>

Anschließend kann die DEF in der Detail-Ansicht des Dialog-Device bearbeitet werden. Jeder Dialog basiert auf der folgenden Struktur von einfach bis komplex.

<pre>
{
"<TRIGGER>": {
"match": "<regex>",
"setOnly": (true|false),
"commands": "(fhem command|{perl code})",
"message": [
"{perl code}",
"text"
],
"<NEXT TRIGGER 1>": {
...
},
"<NEXT TRIGGER 2>": {
...
}
}
}
</pre>

Um den JSON-Teil der Dialoge zu testen, empfiehlt sich ein Besuch auf https://jsonlint.com/
Hier kann der selbst geschriebene JSON-Code validiert werden.

;TRIGGER
:Kann ein beliebiger Text sein. Es wird geprüft ob die eingehende Nachricht damit übereinstimmt. Falls ja, wird der Dialog an dieser Stelle fortgesetzt.

;match
:Wenn nicht nur genau eine Nachricht zugelassen werden soll, kann noch eine regex angegeben werden. Die regex muss auf die gesamte eingehnde Nachricht :zutreffen.

;setOnly
:Kann optional auf true oder false gestellt werden. In beiden fällen wird der TRIGGER dann nicht bei "get <name> trigger" zurück gegeben.
:Wenn setOnly auf "true" gestellt wird, kann der Dialog an dieser Stelle nicht durch eingehende Nachrichten ausgelöst werden, sondern nur über "get ::::<name> say TRIGGER". Dies kann dazu genutzt werden um einen Dialog aus :FHEM heraus zu initiieren.

;commands
:Kann einen einzelnen oder mehrere Befehle enthalten:
<pre>
"commands":
"single command"
"commands": [
"command 1",
"command 2",
"{perl command}"
]
</pre>

;message
:Kann einen einzelnen oder mehrere Textte enthalten die mit einen Zeilenumbruch verbunden werden:
<pre>
"message": "text"
</pre>
<pre>
"message": [
"text 1",
"text 2",
"{return from perl command}"
]
</pre>

Bei mehrstufigen Dialogen wird diese Struktur ineinander verschachtelt angegeben.
Es werden Variablen und Platzhalter, welche unter dem Attribut evalSpecials definiert werden, ausgewertet.

=== Variablen ===
*$SELF: Eigenname des msgDialog
*$message: eingegangene Nachricht
*$recipient: Name des Dialogpartners

=== Attribute ===
*allowed: Liste mit allen RESIDENTS und ROOMMATE die für diesen Dialog berechtigt sind.
*disable: [0|1] Dialog ist aktiviert|deaktiviert.
*disabledForIntervals: HH:MM-HH:MM HH:MM-HH-MM ...
*evalSpecials: key1=value1 key2=value2 ...Leerzeichen getrennte Liste von Name=Wert Paaren. Wert kann Leerzeichen enthalten, falls es in "" oder {} eingeschlossen ist. Wert wird als perl-Ausdruck ausgewertet, falls es in {} eingeschlossen ist. In der DEF werden %Name% Zeichenketten durch den zugehörigen Wert ersetzt. Dieses Attribut ist als "msgDialog_evalSpecials" im msgConfig Gerät vorhanden. Wenn der selbe Name im msgConfig und msgDialog definiert wurde, wird der Wert aus msgDialog verwendet.
*msgCommand <command>: Befehl der zum Versenden einer Nachricht verwendet wird. Die Vorgabe ist "msg push \@$recipients $message" Dieses Attribut ist als "msgDialog_msgCommand" im msgConfig Gerät vorhanden.

=== set ===
*reset: Setzt den Dialog für alle Benutzer zurück.
*say [@<recipient1>[,<recipient2>,...]] <TRIGGER>[|<NEXT TRIGGER>|...]: Der Dialog wird für alle angegeben Empänger an der angegeben Stelle fortgeführt. Sind keine Empfänger angegeben wird der Dialog für alle unter dem Attribut allowed angegebenen Empfänger fortgeführt.
*updateAllowed: Aktualisiert die Auswahl für das Attribut allowed.

=== get ===
*trigger: Listet alle TRIGGER der ersten Ebene auf bei denen nicht setOnly angegeben ist.

=== READINGS ===
*$recipient_history: Durch | getrennte Liste von TRIGGER um den aktuellen Zustand des Dialogs zu sichern. Für jeden Dialogpartner wird ein Reading angelegt. Wenn der Dialog beendet ist wird das Reading zurückgesetzt.

== Beispiele ==

==== Programmierung der Waschmaschine ====
Das ist ein Beispiel zur Programmierung einer Waschmaschine wie auch oben im Video zu sehen:
<pre>
defmod Waschmaschine_Dialog msgDialog { "Waschmaschine": {\
"message": [\
"{return('(Zeitprogramm stoppen) ') if(ReadingsVal('%controlUnit%', 'controlMode', '') eq 'auto')}",\
"{return('(programmieren) ') if(ReadingsVal('%actor%', 'state', '') ne 'on')}",\
"{return('(einschalten) ') if(ReadingsVal('%actor%', 'state', '') ne 'on')}",\
"(Verlaufsdiagramm) ",\
"(abbrechen) ",\
"{return('Waschmaschine: ' . (ReadingsVal('%actor%', 'state', '') eq 'on' ? 'eingeschaltet' : 'ausgeschaltet'))}",\
"{return('Modus: ' . (ReadingsVal('%controlUnit%', 'controlMode', '') eq 'auto' ? 'Automatik' : 'Manuell (' . ReadingsVal('%controlUnit%', 'time', '') . ')'))}"\
],\
"Zeitprogramm stoppen": {\
"commands": "set %controlUnit% controlMode manual",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Das Zeitprogramm wurde gestoppt."\
]\
},\
"programmieren": {\
"message": [\
"(bestätigen|zurück|abbrechen) ",\
"( 00:00 | 00:15 | 00:30 | 00:45 ) ",\
"( 01:00 | 01:15 | 01:30 | 01:45 ) ",\
"( 02:00 | 02:15 | 02:30 | 02:45 ) ",\
"( 03:00 | 03:15 | 03:30 | 03:45 ) ",\
"( 04:00 | 04:15 | 04:30 | 04:45 ) ",\
"( 05:00 | 05:15 | 05:30 | 05:45 ) ",\
"( 06:00 | 06:15 | 06:30 | 06:45 ) ",\
"( 07:00 | 07:15 | 07:30 | 07:45 ) ",\
"( 08:00 | 08:15 | 08:30 | 08:45 ) ",\
"( 09:00 | 09:15 | 09:30 | 09:45 ) ",\
"( 10:00 | 10:15 | 10:30 | 10:45 ) ",\
"( 11:00 | 11:15 | 11:30 | 11:45 ) ",\
"( 12:00 | 12:15 | 12:30 | 12:45 ) ",\
"( 13:00 | 13:15 | 13:30 | 13:45 ) ",\
"( 14:00 | 14:15 | 14:30 | 14:45 ) ",\
"( 15:00 | 15:15 | 15:30 | 15:45 ) ",\
"( 16:00 | 16:15 | 16:30 | 16:45 ) ",\
"( 17:00 | 17:15 | 17:30 | 17:45 ) ",\
"( 18:00 | 18:15 | 18:30 | 18:45 ) ",\
"( 19:00 | 19:15 | 19:30 | 19:45 ) ",\
"( 20:00 | 20:15 | 20:30 | 20:45 ) ",\
"( 21:00 | 21:15 | 21:30 | 21:45 ) ",\
"( 22:00 | 22:15 | 22:30 | 22:45 ) ",\
"( 23:00 | 23:15 | 23:30 | 23:45 ) ",\
"Wann soll die Wäsche fertig sein?",\
"Bitte Uhrzeit in HH:MM angeben.",\
"Aktuell ist [%controlUnit%:time] Uhr eingestellt."\
],\
"Uhrzeit": {\
"match": " ?([0-1][0-9]|2[0-3]):[0-5][0-9] ?",\
"commands": [\
"set %controlUnit% time $message",\
"set $SELF say @$recipient Waschmaschine|programmieren|bestätigen"\
]\
},\
"bestätigen": {\
"commands": "set %controlUnit% controlMode auto",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Das Zeitprogramm wurde eingestellt.",\
"Die Wäsche wird voraussichtlich um [%controlUnit%:time] Uhr fertig sein.",\
"Bitte die Waschmaschine vorbereiten."\
]\
}\
},\
"einschalten": {\
"commands": [\
"set %controlUnit% controlMode manual",\
"set %actor% on"\
]\
},\
"Verlaufsdiagramm": {\
"commands": "set %TelegramBot% cmdSend {plotAsPng('%plot%')}",\
"message": "TelegramBot_MTYPE=queryInline (%me%) $message"\
}\
},\
"auto": {\
"setOnly": true,\
"commands": [\
"set %actor% on",\
"set %controlUnit% controlMode manual"\
],\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine wurde automatisch eingeschaltet."\
]\
},\
"manual": {\
"setOnly": true,\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine wurde manuell eingeschaltet."\
]\
},\
"done": {\
"setOnly": true,\
"commands": "set %actor% off",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine ist fertig."\
]\
}\
}
attr Waschmaschine_Dialog evalSpecials actor=HM_2C10D8_Sw\
controlUnit=Waschkeller_washer_controlUnit\
plot=Waschkeller_washer_SVG
</pre>

== TelegramBot ==

In Telegram gibt es die Möglichkeit die Art des Keyboards zu ändern. Links das normale Keyboard, rechts das Inline Keyboard.

[[Datei:76msgDialog menu.png|Normales Keyboard]] [[Datei:76msgDialog menu inline.PNG|Inline Keyboard]]

In diesem '''[https://youtu.be/oRDy2918mVI Video]''' wird Telegram mit einem Inline Keyboard verwendet.

Um eine Nachricht bei Telegram zu verändern, gibt es den Befehl "queryEditInline".
Dafür wird die MsgId von der Nachricht benötigt. Das erledigt ein notify, welches die msgId pro Peer abspeichert:

<pre>
defmod sentMsgIdByPeerId notify .+:sentMsgId.+ {\
return unless($TYPE eq "TelegramBot");;\
\
my $dev_hash = $defs{$NAME};;\
my $sentMsgId = ReadingsVal($NAME, "sentMsgId", "");;\
my $sentMsgPeerId = ReadingsVal($NAME, "sentMsgPeerId", "");;\
my ($contact) = devspec2array("TYPE=(ROOMMATE|GUEST):FILTER=msgContactPush=.*$sentMsgPeerId.*");;\
\
readingsSingleUpdate($dev_hash, "$contact\_sentMsgId", $sentMsgId, 1);;\
}
attr sentMsgIdByPeerId devStateIcon {ReadingsVal($name, "state", "inactive") eq "active" ? ".*:ios-on-blue:inactive" : ".*:ios-off:active"}
attr sentMsgIdByPeerId icon audio_mic
attr sentMsgIdByPeerId room msg
</pre>

Danach wird der Message-Befehl von
<pre>
set <TelegramBot> message
</pre>
auf
<pre>
set <TelegramBot> queryEditInline
</pre>
geändert. Dafür wird ein [[cmdalias]] verwendet:

<pre>
defmod message2queryEditInline cmdalias set .+ message (.|\n)+ AS {\
my ($NAME, $cmd, $message) = split(/[\s]+/, $EVENT, 3);;\
my $TYPE = InternalVal($NAME, "TYPE", "");;\
(my $recipient, $message) = ($message =~ m/(@\S+)? (.+)/s);;\
\
if($TYPE eq "TelegramBot" && $recipient){\
my ($contact) = devspec2array("TYPE=(ROOMMATE|GUEST):FILTER=msgContactPush=.*$recipient.*");;\
my $sentMsgId = ReadingsVal($NAME, "$contact\_sentMsgId", "");;\
\
if($sentMsgId ne ""){\
fhem("set $NAME queryEditInline $sentMsgId $recipient $message");;\
}\
else{\
fhem("set $NAME queryInline $recipient $message");;\
}\
}\
else{\
fhem("set $EVENT");;\
}\
}
attr message2queryEditInline room msg
</pre>

Um wieder zurück zum normalen Keyboard zu gelangen genügt es, das notify und den cmdAlias zu deaktivieren.
Das kann komfortabel über ein notify und einen dummy erledigt werden:
<pre>
defmod inline_normal.NOT notify inline_normal.DUM:.* {\
if ("$EVENT" =~ "on") {\
fhem "set sentMsgIdByPeerId active;; attr message2queryEditInline disable 0";;\
} \
elsif ("$EVENT" =~ "off") {\
fhem "set sentMsgIdByPeerId inactive;; attr message2queryEditInline disable 1";;\
}\
}
</pre>

Weitere Infos zum Thema Inline Keyboard sind in der Antwort #10 im Forum zu finden (siehe Link unten).

== JABBER ==
Hier wird die Verwendung mit Jabber beschrieben...

== WhatsApp ==
Hier wird die Verwendung mit yowsup/WhatsApp beschrieben...

== Links ==
* Thread über das Modul im {{Link2Forum|Topic=77297|LinkText=FHEM Forum}}

[[Kategorie:Hilfsmodul]]

MsgDialog

2017-10-31T09:33:24Z

Binford6000: /* msgConfig */

{{Infobox Modul
|ModPurpose=Dialoge für Sofortnachrichten über TelegramBot, Jabber und WhatsApp
|ModType=h
|ModForumArea=Frontends
|ModTechName=76_msgDialog.pm
|ModOwner={{Link2FU|4106|igami}}
}}

== Zielsetzung ==
Ein zentrale Anforderung an die Haus-Automation ist die Kommunikation mit den Anwendern. Fast jeder Anwender möchte über bestimmte Ereignisse informiert werden und Einstellungen vornehmen. FHEM bietet schon seit längerem die Unterstützung für verschiedene Messaging Dienste an.
Mit dem msgDialog Modul können vordefinierte Dialoge erstellt werden. Die Kommunikation erfolgt dabei über den [[msg]] Befehl welcher zurzeit die bidirektionale Kommunikation über [[TelegramBot]], [[Jabber]] und [[yowsup]] (WhatsApp) unterstützt. Eingehende Nachrichten werden einem ROMMATE oder GUEST zugeordnet. Darüber werden auch die Berechtigungen für die einzelnen Dialoge festgelegt.
Die grundlegende Bedienung wird in diesem '''[https://youtu.be/yiCOTeR1YVQ Video]''' am Beispiel von TelegramBot gezeigt.

== Konfiguration ==

=== Voraussetzungen ===
Für dieses Modul wird das Perl JSON Modul benötigt. Auf einem Debian-basierten System (z.B RaspberryPI o.ä.) kann man das mit dem folgenden Befehl installieren:
<pre>
sudo apt-get install libjson-perl
</pre>

=== Hinweis zu den Code Beispielen ===
Es handelt sich bei den Beispielen um eine Raw definition, siehe auch [[Import_von_Code_Snippets]]

=== msgConfig ===

Als erstes benötigt man ein definiertes msgConfig device:

<pre>
defmod myMsgConfig msgConfig
attr myMsgConfig msgDialog_evalSpecials me=<Aktivierungswort bzw. -Nachricht>
TelegramBot=<Name des TelegramBot-device>
attr myMsgConfig msgContactPush TelegramBot
attr myMsgConfig room msg
</pre>

Falls bereits vorhanden, müssen natürlich nur die fehlenden Attribute gesetzt werden.

;msgDialog_evalSpecials
:key1=value1 key2=value2 ... Leerzeichen getrennte Liste von Name=Wert Paaren. Wert kann Leerzeichen enthalten, falls es in "" oder {} eingeschlossen :ist. Wert wird als perl-Ausdruck ausgewertet, falls es in {} eingeschlossen ist. In der DEF werden %Name% Zeichenketten durch den zugehörigen Wert :ersetzt. Wenn der selbe Name im msgConfig und msgDialog definiert wurde, wird der Wert aus msgDialog verwendet.

;msgDialog_msgCommand <command>
:Befehl zum Versenden einer Nachricht. Die Vorgabe ist "msg push \@$recipients $message"

=== ROOMMATE / GUEST ===
Für jeden Dialog kann festgelegt werden welche Person dazu berechtigt ist. Dazu sind Geräte vom Typ ROOMMATE oder GUEST mit definiertem msgContactPush Attribut erforderlich. Es ist darauf zu achten, dass das Reading fhemMsgRcvPush ein Event erzeugt. Siehe auch Attribut "allowed" in msgDialog.

=== Define ===

Definition des metaDialogs:
Zur Auflistung aller berechtigten Dialoge dient - was sonst - ein Dialog!

<pre>
defmod meta_Dialog msgDialog {\
"%me%": {\
"match": "\/?(start|%me%)",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"{return('(' . join(') (', sort(split('\n', fhem('get TYPE=msgDialog:FILTER=NAME!=$SELF:FILTER=allowed=.*($recipient|everyone).* trigger')))) . ') ')}",\
"(abbrechen) ",\
"Ich kann folgendes für dich tun:"\
]\
},\
"abbrechen": {\
"match": "\/?abbrechen",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"(%me%) ",\
"Dialog abgebrochen."\
] \
},\
"beenden": {\
"match": "\/?beenden",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"(%me%) ",\
"Dialog beendet."\
]\
}\
}

attr meta_Dialog DbLogExclude .*
attr meta_Dialog allowed everyone
attr meta_Dialog room msg
</pre>

Aufgrund der Komplexität eines Dialogs mit JSON ist es am praktikabelsten, zunächst einen leeren Dialog zu definieren:
<pre>
define <name> msgDialog {}
</pre>

Anschließend kann die DEF in der Detail-Ansicht des Dialog-Device bearbeitet werden. Jeder Dialog basiert auf der folgenden Struktur von einfach bis komplex.

<pre>
{
"<TRIGGER>": {
"match": "<regex>",
"setOnly": (true|false),
"commands": "(fhem command|{perl code})",
"message": [
"{perl code}",
"text"
],
"<NEXT TRIGGER 1>": {
...
},
"<NEXT TRIGGER 2>": {
...
}
}
}
</pre>

Um den JSON-Teil der Dialoge zu testen, empfiehlt sich ein Besuch auf https://jsonlint.com/
Hier kann der selbst geschriebene JSON-Code validiert werden.

*TRIGGER: Kann ein beliebiger Text sein. Es wird geprüft ob die eingehende Nachricht damit übereinstimmt. Falls ja, wird der Dialog an dieser Stelle fortgesetzt.

*match: Wenn nicht nur genau eine Nachricht zugelassen werden soll, kann noch eine regex angegeben werden. Die regex muss auf die gesamte eingehnde Nachricht zutreffen.

*setOnly: Kann optional auf true oder false gestellt werden. In beiden fällen wird der TRIGGER dann nicht bei "get <name> trigger" zurück gegeben.
Wenn setOnly auf "true" gestellt wird, kann der Dialog an dieser Stelle nicht durch eingehende Nachrichten ausgelöst werden, sondern nur über "get <name> say TRIGGER". Dies kann dazu genutzt werden um einen Dialog aus FHEM heraus zu initiieren.

*commands: Kann einen einzelnen oder mehrere Befehle enthalten:
<pre>
"commands":
"single command"
"commands": [
"command 1",
"command 2",
"{perl command}"
]
</pre>

*message: Kann einen einzelnen oder mehrere Textte enthalten die mit einen Zeilenumbruch verbunden werden:
<pre>
"message": "text"
</pre>
<pre>
"message": [
"text 1",
"text 2",
"{return from perl command}"
]
</pre>

Bei mehrstufigen Dialogen wird diese Struktur ineinander verschachtelt angegeben.
Es werden Variablen und Platzhalter, welche unter dem Attribut evalSpecials definiert werden, ausgewertet.

=== Variablen ===
*$SELF: Eigenname des msgDialog
*$message: eingegangene Nachricht
*$recipient: Name des Dialogpartners

=== Attribute ===
*allowed: Liste mit allen RESIDENTS und ROOMMATE die für diesen Dialog berechtigt sind.
*disable: [0|1] Dialog ist aktiviert|deaktiviert.
*disabledForIntervals: HH:MM-HH:MM HH:MM-HH-MM ...
*evalSpecials: key1=value1 key2=value2 ...Leerzeichen getrennte Liste von Name=Wert Paaren. Wert kann Leerzeichen enthalten, falls es in "" oder {} eingeschlossen ist. Wert wird als perl-Ausdruck ausgewertet, falls es in {} eingeschlossen ist. In der DEF werden %Name% Zeichenketten durch den zugehörigen Wert ersetzt. Dieses Attribut ist als "msgDialog_evalSpecials" im msgConfig Gerät vorhanden. Wenn der selbe Name im msgConfig und msgDialog definiert wurde, wird der Wert aus msgDialog verwendet.
*msgCommand <command>: Befehl der zum Versenden einer Nachricht verwendet wird. Die Vorgabe ist "msg push \@$recipients $message" Dieses Attribut ist als "msgDialog_msgCommand" im msgConfig Gerät vorhanden.

=== set ===
*reset: Setzt den Dialog für alle Benutzer zurück.
*say [@<recipient1>[,<recipient2>,...]] <TRIGGER>[|<NEXT TRIGGER>|...]: Der Dialog wird für alle angegeben Empänger an der angegeben Stelle fortgeführt. Sind keine Empfänger angegeben wird der Dialog für alle unter dem Attribut allowed angegebenen Empfänger fortgeführt.
*updateAllowed: Aktualisiert die Auswahl für das Attribut allowed.

=== get ===
*trigger: Listet alle TRIGGER der ersten Ebene auf bei denen nicht setOnly angegeben ist.

=== READINGS ===
*$recipient_history: Durch | getrennte Liste von TRIGGER um den aktuellen Zustand des Dialogs zu sichern. Für jeden Dialogpartner wird ein Reading angelegt. Wenn der Dialog beendet ist wird das Reading zurückgesetzt.

== Beispiele ==

==== Programmierung der Waschmaschine ====
Das ist ein Beispiel zur Programmierung einer Waschmaschine wie auch oben im Video zu sehen:
<pre>
defmod Waschmaschine_Dialog msgDialog { "Waschmaschine": {\
"message": [\
"{return('(Zeitprogramm stoppen) ') if(ReadingsVal('%controlUnit%', 'controlMode', '') eq 'auto')}",\
"{return('(programmieren) ') if(ReadingsVal('%actor%', 'state', '') ne 'on')}",\
"{return('(einschalten) ') if(ReadingsVal('%actor%', 'state', '') ne 'on')}",\
"(Verlaufsdiagramm) ",\
"(abbrechen) ",\
"{return('Waschmaschine: ' . (ReadingsVal('%actor%', 'state', '') eq 'on' ? 'eingeschaltet' : 'ausgeschaltet'))}",\
"{return('Modus: ' . (ReadingsVal('%controlUnit%', 'controlMode', '') eq 'auto' ? 'Automatik' : 'Manuell (' . ReadingsVal('%controlUnit%', 'time', '') . ')'))}"\
],\
"Zeitprogramm stoppen": {\
"commands": "set %controlUnit% controlMode manual",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Das Zeitprogramm wurde gestoppt."\
]\
},\
"programmieren": {\
"message": [\
"(bestätigen|zurück|abbrechen) ",\
"( 00:00 | 00:15 | 00:30 | 00:45 ) ",\
"( 01:00 | 01:15 | 01:30 | 01:45 ) ",\
"( 02:00 | 02:15 | 02:30 | 02:45 ) ",\
"( 03:00 | 03:15 | 03:30 | 03:45 ) ",\
"( 04:00 | 04:15 | 04:30 | 04:45 ) ",\
"( 05:00 | 05:15 | 05:30 | 05:45 ) ",\
"( 06:00 | 06:15 | 06:30 | 06:45 ) ",\
"( 07:00 | 07:15 | 07:30 | 07:45 ) ",\
"( 08:00 | 08:15 | 08:30 | 08:45 ) ",\
"( 09:00 | 09:15 | 09:30 | 09:45 ) ",\
"( 10:00 | 10:15 | 10:30 | 10:45 ) ",\
"( 11:00 | 11:15 | 11:30 | 11:45 ) ",\
"( 12:00 | 12:15 | 12:30 | 12:45 ) ",\
"( 13:00 | 13:15 | 13:30 | 13:45 ) ",\
"( 14:00 | 14:15 | 14:30 | 14:45 ) ",\
"( 15:00 | 15:15 | 15:30 | 15:45 ) ",\
"( 16:00 | 16:15 | 16:30 | 16:45 ) ",\
"( 17:00 | 17:15 | 17:30 | 17:45 ) ",\
"( 18:00 | 18:15 | 18:30 | 18:45 ) ",\
"( 19:00 | 19:15 | 19:30 | 19:45 ) ",\
"( 20:00 | 20:15 | 20:30 | 20:45 ) ",\
"( 21:00 | 21:15 | 21:30 | 21:45 ) ",\
"( 22:00 | 22:15 | 22:30 | 22:45 ) ",\
"( 23:00 | 23:15 | 23:30 | 23:45 ) ",\
"Wann soll die Wäsche fertig sein?",\
"Bitte Uhrzeit in HH:MM angeben.",\
"Aktuell ist [%controlUnit%:time] Uhr eingestellt."\
],\
"Uhrzeit": {\
"match": " ?([0-1][0-9]|2[0-3]):[0-5][0-9] ?",\
"commands": [\
"set %controlUnit% time $message",\
"set $SELF say @$recipient Waschmaschine|programmieren|bestätigen"\
]\
},\
"bestätigen": {\
"commands": "set %controlUnit% controlMode auto",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Das Zeitprogramm wurde eingestellt.",\
"Die Wäsche wird voraussichtlich um [%controlUnit%:time] Uhr fertig sein.",\
"Bitte die Waschmaschine vorbereiten."\
]\
}\
},\
"einschalten": {\
"commands": [\
"set %controlUnit% controlMode manual",\
"set %actor% on"\
]\
},\
"Verlaufsdiagramm": {\
"commands": "set %TelegramBot% cmdSend {plotAsPng('%plot%')}",\
"message": "TelegramBot_MTYPE=queryInline (%me%) $message"\
}\
},\
"auto": {\
"setOnly": true,\
"commands": [\
"set %actor% on",\
"set %controlUnit% controlMode manual"\
],\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine wurde automatisch eingeschaltet."\
]\
},\
"manual": {\
"setOnly": true,\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine wurde manuell eingeschaltet."\
]\
},\
"done": {\
"setOnly": true,\
"commands": "set %actor% off",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine ist fertig."\
]\
}\
}
attr Waschmaschine_Dialog evalSpecials actor=HM_2C10D8_Sw\
controlUnit=Waschkeller_washer_controlUnit\
plot=Waschkeller_washer_SVG
</pre>

== TelegramBot ==

In Telegram gibt es die Möglichkeit die Art des Keyboards zu ändern. Links das normale Keyboard, rechts das Inline Keyboard.

[[Datei:76msgDialog menu.png|Normales Keyboard]] [[Datei:76msgDialog menu inline.PNG|Inline Keyboard]]

In diesem '''[https://youtu.be/oRDy2918mVI Video]''' wird Telegram mit einem Inline Keyboard verwendet.

Um eine Nachricht bei Telegram zu verändern, gibt es den Befehl "queryEditInline".
Dafür wird die MsgId von der Nachricht benötigt. Das erledigt ein notify, welches die msgId pro Peer abspeichert:

<pre>
defmod sentMsgIdByPeerId notify .+:sentMsgId.+ {\
return unless($TYPE eq "TelegramBot");;\
\
my $dev_hash = $defs{$NAME};;\
my $sentMsgId = ReadingsVal($NAME, "sentMsgId", "");;\
my $sentMsgPeerId = ReadingsVal($NAME, "sentMsgPeerId", "");;\
my ($contact) = devspec2array("TYPE=(ROOMMATE|GUEST):FILTER=msgContactPush=.*$sentMsgPeerId.*");;\
\
readingsSingleUpdate($dev_hash, "$contact\_sentMsgId", $sentMsgId, 1);;\
}
attr sentMsgIdByPeerId devStateIcon {ReadingsVal($name, "state", "inactive") eq "active" ? ".*:ios-on-blue:inactive" : ".*:ios-off:active"}
attr sentMsgIdByPeerId icon audio_mic
attr sentMsgIdByPeerId room msg
</pre>

Danach wird der Message-Befehl von
<pre>
set <TelegramBot> message
</pre>
auf
<pre>
set <TelegramBot> queryEditInline
</pre>
geändert. Dafür wird ein [[cmdalias]] verwendet:

<pre>
defmod message2queryEditInline cmdalias set .+ message (.|\n)+ AS {\
my ($NAME, $cmd, $message) = split(/[\s]+/, $EVENT, 3);;\
my $TYPE = InternalVal($NAME, "TYPE", "");;\
(my $recipient, $message) = ($message =~ m/(@\S+)? (.+)/s);;\
\
if($TYPE eq "TelegramBot" && $recipient){\
my ($contact) = devspec2array("TYPE=(ROOMMATE|GUEST):FILTER=msgContactPush=.*$recipient.*");;\
my $sentMsgId = ReadingsVal($NAME, "$contact\_sentMsgId", "");;\
\
if($sentMsgId ne ""){\
fhem("set $NAME queryEditInline $sentMsgId $recipient $message");;\
}\
else{\
fhem("set $NAME queryInline $recipient $message");;\
}\
}\
else{\
fhem("set $EVENT");;\
}\
}
attr message2queryEditInline room msg
</pre>

Um wieder zurück zum normalen Keyboard zu gelangen genügt es, das notify und den cmdAlias zu deaktivieren.
Das kann komfortabel über ein notify und einen dummy erledigt werden:
<pre>
defmod inline_normal.NOT notify inline_normal.DUM:.* {\
if ("$EVENT" =~ "on") {\
fhem "set sentMsgIdByPeerId active;; attr message2queryEditInline disable 0";;\
} \
elsif ("$EVENT" =~ "off") {\
fhem "set sentMsgIdByPeerId inactive;; attr message2queryEditInline disable 1";;\
}\
}
</pre>

Weitere Infos zum Thema Inline Keyboard sind in der Antwort #10 im Forum zu finden (siehe Link unten).

== JABBER ==
Hier wird die Verwendung mit Jabber beschrieben...

== WhatsApp ==
Hier wird die Verwendung mit yowsup/WhatsApp beschrieben...

== Links ==
* Thread über das Modul im {{Link2Forum|Topic=77297|LinkText=FHEM Forum}}

[[Kategorie:Hilfsmodul]]

MsgDialog

2017-10-31T09:31:45Z

Binford6000: /* ROOMMATE / GUEST */

{{Infobox Modul
|ModPurpose=Dialoge für Sofortnachrichten über TelegramBot, Jabber und WhatsApp
|ModType=h
|ModForumArea=Frontends
|ModTechName=76_msgDialog.pm
|ModOwner={{Link2FU|4106|igami}}
}}

== Zielsetzung ==
Ein zentrale Anforderung an die Haus-Automation ist die Kommunikation mit den Anwendern. Fast jeder Anwender möchte über bestimmte Ereignisse informiert werden und Einstellungen vornehmen. FHEM bietet schon seit längerem die Unterstützung für verschiedene Messaging Dienste an.
Mit dem msgDialog Modul können vordefinierte Dialoge erstellt werden. Die Kommunikation erfolgt dabei über den [[msg]] Befehl welcher zurzeit die bidirektionale Kommunikation über [[TelegramBot]], [[Jabber]] und [[yowsup]] (WhatsApp) unterstützt. Eingehende Nachrichten werden einem ROMMATE oder GUEST zugeordnet. Darüber werden auch die Berechtigungen für die einzelnen Dialoge festgelegt.
Die grundlegende Bedienung wird in diesem '''[https://youtu.be/yiCOTeR1YVQ Video]''' am Beispiel von TelegramBot gezeigt.

== Konfiguration ==

=== Voraussetzungen ===
Für dieses Modul wird das Perl JSON Modul benötigt. Auf einem Debian-basierten System (z.B RaspberryPI o.ä.) kann man das mit dem folgenden Befehl installieren:
<pre>
sudo apt-get install libjson-perl
</pre>

=== Hinweis zu den Code Beispielen ===
Es handelt sich bei den Beispielen um eine Raw definition, siehe auch [[Import_von_Code_Snippets]]

=== msgConfig ===

Als erstes benötigt man ein definiertes msgConfig device:

<pre>
defmod myMsgConfig msgConfig
attr myMsgConfig msgDialog_evalSpecials me=<Aktivierungswort bzw. -Nachricht>
TelegramBot=<Name des TelegramBot-device>
attr myMsgConfig msgContactPush TelegramBot
attr myMsgConfig room msg
</pre>

Falls bereits vorhanden, müssen natürlich nur die fehlenden Attribute gesetzt werden.

* msgDialog_evalSpecials: key1=value1 key2=value2 ... Leerzeichen getrennte Liste von Name=Wert Paaren. Wert kann Leerzeichen enthalten, falls es in "" oder {} eingeschlossen ist. Wert wird als perl-Ausdruck ausgewertet, falls es in {} eingeschlossen ist. In der DEF werden %Name% Zeichenketten durch den zugehörigen Wert ersetzt. Wenn der selbe Name im msgConfig und msgDialog definiert wurde, wird der Wert aus msgDialog verwendet.

*msgDialog_msgCommand <command>: Befehl zum Versenden einer Nachricht. Die Vorgabe ist "msg push \@$recipients $message"

=== ROOMMATE / GUEST ===
Für jeden Dialog kann festgelegt werden welche Person dazu berechtigt ist. Dazu sind Geräte vom Typ ROOMMATE oder GUEST mit definiertem msgContactPush Attribut erforderlich. Es ist darauf zu achten, dass das Reading fhemMsgRcvPush ein Event erzeugt. Siehe auch Attribut "allowed" in msgDialog.

=== Define ===

Definition des metaDialogs:
Zur Auflistung aller berechtigten Dialoge dient - was sonst - ein Dialog!

<pre>
defmod meta_Dialog msgDialog {\
"%me%": {\
"match": "\/?(start|%me%)",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"{return('(' . join(') (', sort(split('\n', fhem('get TYPE=msgDialog:FILTER=NAME!=$SELF:FILTER=allowed=.*($recipient|everyone).* trigger')))) . ') ')}",\
"(abbrechen) ",\
"Ich kann folgendes für dich tun:"\
]\
},\
"abbrechen": {\
"match": "\/?abbrechen",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"(%me%) ",\
"Dialog abgebrochen."\
] \
},\
"beenden": {\
"match": "\/?beenden",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"(%me%) ",\
"Dialog beendet."\
]\
}\
}

attr meta_Dialog DbLogExclude .*
attr meta_Dialog allowed everyone
attr meta_Dialog room msg
</pre>

Aufgrund der Komplexität eines Dialogs mit JSON ist es am praktikabelsten, zunächst einen leeren Dialog zu definieren:
<pre>
define <name> msgDialog {}
</pre>

Anschließend kann die DEF in der Detail-Ansicht des Dialog-Device bearbeitet werden. Jeder Dialog basiert auf der folgenden Struktur von einfach bis komplex.

<pre>
{
"<TRIGGER>": {
"match": "<regex>",
"setOnly": (true|false),
"commands": "(fhem command|{perl code})",
"message": [
"{perl code}",
"text"
],
"<NEXT TRIGGER 1>": {
...
},
"<NEXT TRIGGER 2>": {
...
}
}
}
</pre>

Um den JSON-Teil der Dialoge zu testen, empfiehlt sich ein Besuch auf https://jsonlint.com/
Hier kann der selbst geschriebene JSON-Code validiert werden.

*TRIGGER: Kann ein beliebiger Text sein. Es wird geprüft ob die eingehende Nachricht damit übereinstimmt. Falls ja, wird der Dialog an dieser Stelle fortgesetzt.

*match: Wenn nicht nur genau eine Nachricht zugelassen werden soll, kann noch eine regex angegeben werden. Die regex muss auf die gesamte eingehnde Nachricht zutreffen.

*setOnly: Kann optional auf true oder false gestellt werden. In beiden fällen wird der TRIGGER dann nicht bei "get <name> trigger" zurück gegeben.
Wenn setOnly auf "true" gestellt wird, kann der Dialog an dieser Stelle nicht durch eingehende Nachrichten ausgelöst werden, sondern nur über "get <name> say TRIGGER". Dies kann dazu genutzt werden um einen Dialog aus FHEM heraus zu initiieren.

*commands: Kann einen einzelnen oder mehrere Befehle enthalten:
<pre>
"commands":
"single command"
"commands": [
"command 1",
"command 2",
"{perl command}"
]
</pre>

*message: Kann einen einzelnen oder mehrere Textte enthalten die mit einen Zeilenumbruch verbunden werden:
<pre>
"message": "text"
</pre>
<pre>
"message": [
"text 1",
"text 2",
"{return from perl command}"
]
</pre>

Bei mehrstufigen Dialogen wird diese Struktur ineinander verschachtelt angegeben.
Es werden Variablen und Platzhalter, welche unter dem Attribut evalSpecials definiert werden, ausgewertet.

=== Variablen ===
*$SELF: Eigenname des msgDialog
*$message: eingegangene Nachricht
*$recipient: Name des Dialogpartners

=== Attribute ===
*allowed: Liste mit allen RESIDENTS und ROOMMATE die für diesen Dialog berechtigt sind.
*disable: [0|1] Dialog ist aktiviert|deaktiviert.
*disabledForIntervals: HH:MM-HH:MM HH:MM-HH-MM ...
*evalSpecials: key1=value1 key2=value2 ...Leerzeichen getrennte Liste von Name=Wert Paaren. Wert kann Leerzeichen enthalten, falls es in "" oder {} eingeschlossen ist. Wert wird als perl-Ausdruck ausgewertet, falls es in {} eingeschlossen ist. In der DEF werden %Name% Zeichenketten durch den zugehörigen Wert ersetzt. Dieses Attribut ist als "msgDialog_evalSpecials" im msgConfig Gerät vorhanden. Wenn der selbe Name im msgConfig und msgDialog definiert wurde, wird der Wert aus msgDialog verwendet.
*msgCommand <command>: Befehl der zum Versenden einer Nachricht verwendet wird. Die Vorgabe ist "msg push \@$recipients $message" Dieses Attribut ist als "msgDialog_msgCommand" im msgConfig Gerät vorhanden.

=== set ===
*reset: Setzt den Dialog für alle Benutzer zurück.
*say [@<recipient1>[,<recipient2>,...]] <TRIGGER>[|<NEXT TRIGGER>|...]: Der Dialog wird für alle angegeben Empänger an der angegeben Stelle fortgeführt. Sind keine Empfänger angegeben wird der Dialog für alle unter dem Attribut allowed angegebenen Empfänger fortgeführt.
*updateAllowed: Aktualisiert die Auswahl für das Attribut allowed.

=== get ===
*trigger: Listet alle TRIGGER der ersten Ebene auf bei denen nicht setOnly angegeben ist.

=== READINGS ===
*$recipient_history: Durch | getrennte Liste von TRIGGER um den aktuellen Zustand des Dialogs zu sichern. Für jeden Dialogpartner wird ein Reading angelegt. Wenn der Dialog beendet ist wird das Reading zurückgesetzt.

== Beispiele ==

==== Programmierung der Waschmaschine ====
Das ist ein Beispiel zur Programmierung einer Waschmaschine wie auch oben im Video zu sehen:
<pre>
defmod Waschmaschine_Dialog msgDialog { "Waschmaschine": {\
"message": [\
"{return('(Zeitprogramm stoppen) ') if(ReadingsVal('%controlUnit%', 'controlMode', '') eq 'auto')}",\
"{return('(programmieren) ') if(ReadingsVal('%actor%', 'state', '') ne 'on')}",\
"{return('(einschalten) ') if(ReadingsVal('%actor%', 'state', '') ne 'on')}",\
"(Verlaufsdiagramm) ",\
"(abbrechen) ",\
"{return('Waschmaschine: ' . (ReadingsVal('%actor%', 'state', '') eq 'on' ? 'eingeschaltet' : 'ausgeschaltet'))}",\
"{return('Modus: ' . (ReadingsVal('%controlUnit%', 'controlMode', '') eq 'auto' ? 'Automatik' : 'Manuell (' . ReadingsVal('%controlUnit%', 'time', '') . ')'))}"\
],\
"Zeitprogramm stoppen": {\
"commands": "set %controlUnit% controlMode manual",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Das Zeitprogramm wurde gestoppt."\
]\
},\
"programmieren": {\
"message": [\
"(bestätigen|zurück|abbrechen) ",\
"( 00:00 | 00:15 | 00:30 | 00:45 ) ",\
"( 01:00 | 01:15 | 01:30 | 01:45 ) ",\
"( 02:00 | 02:15 | 02:30 | 02:45 ) ",\
"( 03:00 | 03:15 | 03:30 | 03:45 ) ",\
"( 04:00 | 04:15 | 04:30 | 04:45 ) ",\
"( 05:00 | 05:15 | 05:30 | 05:45 ) ",\
"( 06:00 | 06:15 | 06:30 | 06:45 ) ",\
"( 07:00 | 07:15 | 07:30 | 07:45 ) ",\
"( 08:00 | 08:15 | 08:30 | 08:45 ) ",\
"( 09:00 | 09:15 | 09:30 | 09:45 ) ",\
"( 10:00 | 10:15 | 10:30 | 10:45 ) ",\
"( 11:00 | 11:15 | 11:30 | 11:45 ) ",\
"( 12:00 | 12:15 | 12:30 | 12:45 ) ",\
"( 13:00 | 13:15 | 13:30 | 13:45 ) ",\
"( 14:00 | 14:15 | 14:30 | 14:45 ) ",\
"( 15:00 | 15:15 | 15:30 | 15:45 ) ",\
"( 16:00 | 16:15 | 16:30 | 16:45 ) ",\
"( 17:00 | 17:15 | 17:30 | 17:45 ) ",\
"( 18:00 | 18:15 | 18:30 | 18:45 ) ",\
"( 19:00 | 19:15 | 19:30 | 19:45 ) ",\
"( 20:00 | 20:15 | 20:30 | 20:45 ) ",\
"( 21:00 | 21:15 | 21:30 | 21:45 ) ",\
"( 22:00 | 22:15 | 22:30 | 22:45 ) ",\
"( 23:00 | 23:15 | 23:30 | 23:45 ) ",\
"Wann soll die Wäsche fertig sein?",\
"Bitte Uhrzeit in HH:MM angeben.",\
"Aktuell ist [%controlUnit%:time] Uhr eingestellt."\
],\
"Uhrzeit": {\
"match": " ?([0-1][0-9]|2[0-3]):[0-5][0-9] ?",\
"commands": [\
"set %controlUnit% time $message",\
"set $SELF say @$recipient Waschmaschine|programmieren|bestätigen"\
]\
},\
"bestätigen": {\
"commands": "set %controlUnit% controlMode auto",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Das Zeitprogramm wurde eingestellt.",\
"Die Wäsche wird voraussichtlich um [%controlUnit%:time] Uhr fertig sein.",\
"Bitte die Waschmaschine vorbereiten."\
]\
}\
},\
"einschalten": {\
"commands": [\
"set %controlUnit% controlMode manual",\
"set %actor% on"\
]\
},\
"Verlaufsdiagramm": {\
"commands": "set %TelegramBot% cmdSend {plotAsPng('%plot%')}",\
"message": "TelegramBot_MTYPE=queryInline (%me%) $message"\
}\
},\
"auto": {\
"setOnly": true,\
"commands": [\
"set %actor% on",\
"set %controlUnit% controlMode manual"\
],\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine wurde automatisch eingeschaltet."\
]\
},\
"manual": {\
"setOnly": true,\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine wurde manuell eingeschaltet."\
]\
},\
"done": {\
"setOnly": true,\
"commands": "set %actor% off",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine ist fertig."\
]\
}\
}
attr Waschmaschine_Dialog evalSpecials actor=HM_2C10D8_Sw\
controlUnit=Waschkeller_washer_controlUnit\
plot=Waschkeller_washer_SVG
</pre>

== TelegramBot ==

In Telegram gibt es die Möglichkeit die Art des Keyboards zu ändern. Links das normale Keyboard, rechts das Inline Keyboard.

[[Datei:76msgDialog menu.png|Normales Keyboard]] [[Datei:76msgDialog menu inline.PNG|Inline Keyboard]]

In diesem '''[https://youtu.be/oRDy2918mVI Video]''' wird Telegram mit einem Inline Keyboard verwendet.

Um eine Nachricht bei Telegram zu verändern, gibt es den Befehl "queryEditInline".
Dafür wird die MsgId von der Nachricht benötigt. Das erledigt ein notify, welches die msgId pro Peer abspeichert:

<pre>
defmod sentMsgIdByPeerId notify .+:sentMsgId.+ {\
return unless($TYPE eq "TelegramBot");;\
\
my $dev_hash = $defs{$NAME};;\
my $sentMsgId = ReadingsVal($NAME, "sentMsgId", "");;\
my $sentMsgPeerId = ReadingsVal($NAME, "sentMsgPeerId", "");;\
my ($contact) = devspec2array("TYPE=(ROOMMATE|GUEST):FILTER=msgContactPush=.*$sentMsgPeerId.*");;\
\
readingsSingleUpdate($dev_hash, "$contact\_sentMsgId", $sentMsgId, 1);;\
}
attr sentMsgIdByPeerId devStateIcon {ReadingsVal($name, "state", "inactive") eq "active" ? ".*:ios-on-blue:inactive" : ".*:ios-off:active"}
attr sentMsgIdByPeerId icon audio_mic
attr sentMsgIdByPeerId room msg
</pre>

Danach wird der Message-Befehl von
<pre>
set <TelegramBot> message
</pre>
auf
<pre>
set <TelegramBot> queryEditInline
</pre>
geändert. Dafür wird ein [[cmdalias]] verwendet:

<pre>
defmod message2queryEditInline cmdalias set .+ message (.|\n)+ AS {\
my ($NAME, $cmd, $message) = split(/[\s]+/, $EVENT, 3);;\
my $TYPE = InternalVal($NAME, "TYPE", "");;\
(my $recipient, $message) = ($message =~ m/(@\S+)? (.+)/s);;\
\
if($TYPE eq "TelegramBot" && $recipient){\
my ($contact) = devspec2array("TYPE=(ROOMMATE|GUEST):FILTER=msgContactPush=.*$recipient.*");;\
my $sentMsgId = ReadingsVal($NAME, "$contact\_sentMsgId", "");;\
\
if($sentMsgId ne ""){\
fhem("set $NAME queryEditInline $sentMsgId $recipient $message");;\
}\
else{\
fhem("set $NAME queryInline $recipient $message");;\
}\
}\
else{\
fhem("set $EVENT");;\
}\
}
attr message2queryEditInline room msg
</pre>

Um wieder zurück zum normalen Keyboard zu gelangen genügt es, das notify und den cmdAlias zu deaktivieren.
Das kann komfortabel über ein notify und einen dummy erledigt werden:
<pre>
defmod inline_normal.NOT notify inline_normal.DUM:.* {\
if ("$EVENT" =~ "on") {\
fhem "set sentMsgIdByPeerId active;; attr message2queryEditInline disable 0";;\
} \
elsif ("$EVENT" =~ "off") {\
fhem "set sentMsgIdByPeerId inactive;; attr message2queryEditInline disable 1";;\
}\
}
</pre>

Weitere Infos zum Thema Inline Keyboard sind in der Antwort #10 im Forum zu finden (siehe Link unten).

== JABBER ==
Hier wird die Verwendung mit Jabber beschrieben...

== WhatsApp ==
Hier wird die Verwendung mit yowsup/WhatsApp beschrieben...

== Links ==
* Thread über das Modul im {{Link2Forum|Topic=77297|LinkText=FHEM Forum}}

[[Kategorie:Hilfsmodul]]

MsgDialog

2017-10-31T09:27:49Z

Binford6000: /* msgConfig */

{{Infobox Modul
|ModPurpose=Dialoge für Sofortnachrichten über TelegramBot, Jabber und WhatsApp
|ModType=h
|ModForumArea=Frontends
|ModTechName=76_msgDialog.pm
|ModOwner={{Link2FU|4106|igami}}
}}

== Zielsetzung ==
Ein zentrale Anforderung an die Haus-Automation ist die Kommunikation mit den Anwendern. Fast jeder Anwender möchte über bestimmte Ereignisse informiert werden und Einstellungen vornehmen. FHEM bietet schon seit längerem die Unterstützung für verschiedene Messaging Dienste an.
Mit dem msgDialog Modul können vordefinierte Dialoge erstellt werden. Die Kommunikation erfolgt dabei über den [[msg]] Befehl welcher zurzeit die bidirektionale Kommunikation über [[TelegramBot]], [[Jabber]] und [[yowsup]] (WhatsApp) unterstützt. Eingehende Nachrichten werden einem ROMMATE oder GUEST zugeordnet. Darüber werden auch die Berechtigungen für die einzelnen Dialoge festgelegt.
Die grundlegende Bedienung wird in diesem '''[https://youtu.be/yiCOTeR1YVQ Video]''' am Beispiel von TelegramBot gezeigt.

== Konfiguration ==

=== Voraussetzungen ===
Für dieses Modul wird das Perl JSON Modul benötigt. Auf einem Debian-basierten System (z.B RaspberryPI o.ä.) kann man das mit dem folgenden Befehl installieren:
<pre>
sudo apt-get install libjson-perl
</pre>

=== Hinweis zu den Code Beispielen ===
Es handelt sich bei den Beispielen um eine Raw definition, siehe auch [[Import_von_Code_Snippets]]

=== msgConfig ===

Als erstes benötigt man ein definiertes msgConfig device:

<pre>
defmod myMsgConfig msgConfig
attr myMsgConfig msgDialog_evalSpecials me=<Aktivierungswort bzw. -Nachricht>
TelegramBot=<Name des TelegramBot-device>
attr myMsgConfig msgContactPush TelegramBot
attr myMsgConfig room msg
</pre>

Falls bereits vorhanden, müssen natürlich nur die fehlenden Attribute gesetzt werden.

* msgDialog_evalSpecials: key1=value1 key2=value2 ... Leerzeichen getrennte Liste von Name=Wert Paaren. Wert kann Leerzeichen enthalten, falls es in "" oder {} eingeschlossen ist. Wert wird als perl-Ausdruck ausgewertet, falls es in {} eingeschlossen ist. In der DEF werden %Name% Zeichenketten durch den zugehörigen Wert ersetzt. Wenn der selbe Name im msgConfig und msgDialog definiert wurde, wird der Wert aus msgDialog verwendet.

*msgDialog_msgCommand <command>: Befehl zum Versenden einer Nachricht. Die Vorgabe ist "msg push \@$recipients $message"

=== ROOMMATE / GUEST ===
Für jeden Dialog kann festgelegt werden welche Person dazu berechtigt ist. Dazu sind Geräte vom Typ ROOMMATE oder GUEST mit definiertem msgContactPush Attribut erforderlich. Es ist darauf zu achten, dass das Reading fhemMsgRcvPush ein Event erzeugt.

=== Define ===

Definition des metaDialogs:
Zur Auflistung aller berechtigten Dialoge dient - was sonst - ein Dialog!

<pre>
defmod meta_Dialog msgDialog {\
"%me%": {\
"match": "\/?(start|%me%)",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"{return('(' . join(') (', sort(split('\n', fhem('get TYPE=msgDialog:FILTER=NAME!=$SELF:FILTER=allowed=.*($recipient|everyone).* trigger')))) . ') ')}",\
"(abbrechen) ",\
"Ich kann folgendes für dich tun:"\
]\
},\
"abbrechen": {\
"match": "\/?abbrechen",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"(%me%) ",\
"Dialog abgebrochen."\
] \
},\
"beenden": {\
"match": "\/?beenden",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"(%me%) ",\
"Dialog beendet."\
]\
}\
}

attr meta_Dialog DbLogExclude .*
attr meta_Dialog allowed everyone
attr meta_Dialog room msg
</pre>

Aufgrund der Komplexität eines Dialogs mit JSON ist es am praktikabelsten, zunächst einen leeren Dialog zu definieren:
<pre>
define <name> msgDialog {}
</pre>

Anschließend kann die DEF in der Detail-Ansicht des Dialog-Device bearbeitet werden. Jeder Dialog basiert auf der folgenden Struktur von einfach bis komplex.

<pre>
{
"<TRIGGER>": {
"match": "<regex>",
"setOnly": (true|false),
"commands": "(fhem command|{perl code})",
"message": [
"{perl code}",
"text"
],
"<NEXT TRIGGER 1>": {
...
},
"<NEXT TRIGGER 2>": {
...
}
}
}
</pre>

Um den JSON-Teil der Dialoge zu testen, empfiehlt sich ein Besuch auf https://jsonlint.com/
Hier kann der selbst geschriebene JSON-Code validiert werden.

*TRIGGER: Kann ein beliebiger Text sein. Es wird geprüft ob die eingehende Nachricht damit übereinstimmt. Falls ja, wird der Dialog an dieser Stelle fortgesetzt.

*match: Wenn nicht nur genau eine Nachricht zugelassen werden soll, kann noch eine regex angegeben werden. Die regex muss auf die gesamte eingehnde Nachricht zutreffen.

*setOnly: Kann optional auf true oder false gestellt werden. In beiden fällen wird der TRIGGER dann nicht bei "get <name> trigger" zurück gegeben.
Wenn setOnly auf "true" gestellt wird, kann der Dialog an dieser Stelle nicht durch eingehende Nachrichten ausgelöst werden, sondern nur über "get <name> say TRIGGER". Dies kann dazu genutzt werden um einen Dialog aus FHEM heraus zu initiieren.

*commands: Kann einen einzelnen oder mehrere Befehle enthalten:
<pre>
"commands":
"single command"
"commands": [
"command 1",
"command 2",
"{perl command}"
]
</pre>

*message: Kann einen einzelnen oder mehrere Textte enthalten die mit einen Zeilenumbruch verbunden werden:
<pre>
"message": "text"
</pre>
<pre>
"message": [
"text 1",
"text 2",
"{return from perl command}"
]
</pre>

Bei mehrstufigen Dialogen wird diese Struktur ineinander verschachtelt angegeben.
Es werden Variablen und Platzhalter, welche unter dem Attribut evalSpecials definiert werden, ausgewertet.

=== Variablen ===
*$SELF: Eigenname des msgDialog
*$message: eingegangene Nachricht
*$recipient: Name des Dialogpartners

=== Attribute ===
*allowed: Liste mit allen RESIDENTS und ROOMMATE die für diesen Dialog berechtigt sind.
*disable: [0|1] Dialog ist aktiviert|deaktiviert.
*disabledForIntervals: HH:MM-HH:MM HH:MM-HH-MM ...
*evalSpecials: key1=value1 key2=value2 ...Leerzeichen getrennte Liste von Name=Wert Paaren. Wert kann Leerzeichen enthalten, falls es in "" oder {} eingeschlossen ist. Wert wird als perl-Ausdruck ausgewertet, falls es in {} eingeschlossen ist. In der DEF werden %Name% Zeichenketten durch den zugehörigen Wert ersetzt. Dieses Attribut ist als "msgDialog_evalSpecials" im msgConfig Gerät vorhanden. Wenn der selbe Name im msgConfig und msgDialog definiert wurde, wird der Wert aus msgDialog verwendet.
*msgCommand <command>: Befehl der zum Versenden einer Nachricht verwendet wird. Die Vorgabe ist "msg push \@$recipients $message" Dieses Attribut ist als "msgDialog_msgCommand" im msgConfig Gerät vorhanden.

=== set ===
*reset: Setzt den Dialog für alle Benutzer zurück.
*say [@<recipient1>[,<recipient2>,...]] <TRIGGER>[|<NEXT TRIGGER>|...]: Der Dialog wird für alle angegeben Empänger an der angegeben Stelle fortgeführt. Sind keine Empfänger angegeben wird der Dialog für alle unter dem Attribut allowed angegebenen Empfänger fortgeführt.
*updateAllowed: Aktualisiert die Auswahl für das Attribut allowed.

=== get ===
*trigger: Listet alle TRIGGER der ersten Ebene auf bei denen nicht setOnly angegeben ist.

=== READINGS ===
*$recipient_history: Durch | getrennte Liste von TRIGGER um den aktuellen Zustand des Dialogs zu sichern. Für jeden Dialogpartner wird ein Reading angelegt. Wenn der Dialog beendet ist wird das Reading zurückgesetzt.

== Beispiele ==

==== Programmierung der Waschmaschine ====
Das ist ein Beispiel zur Programmierung einer Waschmaschine wie auch oben im Video zu sehen:
<pre>
defmod Waschmaschine_Dialog msgDialog { "Waschmaschine": {\
"message": [\
"{return('(Zeitprogramm stoppen) ') if(ReadingsVal('%controlUnit%', 'controlMode', '') eq 'auto')}",\
"{return('(programmieren) ') if(ReadingsVal('%actor%', 'state', '') ne 'on')}",\
"{return('(einschalten) ') if(ReadingsVal('%actor%', 'state', '') ne 'on')}",\
"(Verlaufsdiagramm) ",\
"(abbrechen) ",\
"{return('Waschmaschine: ' . (ReadingsVal('%actor%', 'state', '') eq 'on' ? 'eingeschaltet' : 'ausgeschaltet'))}",\
"{return('Modus: ' . (ReadingsVal('%controlUnit%', 'controlMode', '') eq 'auto' ? 'Automatik' : 'Manuell (' . ReadingsVal('%controlUnit%', 'time', '') . ')'))}"\
],\
"Zeitprogramm stoppen": {\
"commands": "set %controlUnit% controlMode manual",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Das Zeitprogramm wurde gestoppt."\
]\
},\
"programmieren": {\
"message": [\
"(bestätigen|zurück|abbrechen) ",\
"( 00:00 | 00:15 | 00:30 | 00:45 ) ",\
"( 01:00 | 01:15 | 01:30 | 01:45 ) ",\
"( 02:00 | 02:15 | 02:30 | 02:45 ) ",\
"( 03:00 | 03:15 | 03:30 | 03:45 ) ",\
"( 04:00 | 04:15 | 04:30 | 04:45 ) ",\
"( 05:00 | 05:15 | 05:30 | 05:45 ) ",\
"( 06:00 | 06:15 | 06:30 | 06:45 ) ",\
"( 07:00 | 07:15 | 07:30 | 07:45 ) ",\
"( 08:00 | 08:15 | 08:30 | 08:45 ) ",\
"( 09:00 | 09:15 | 09:30 | 09:45 ) ",\
"( 10:00 | 10:15 | 10:30 | 10:45 ) ",\
"( 11:00 | 11:15 | 11:30 | 11:45 ) ",\
"( 12:00 | 12:15 | 12:30 | 12:45 ) ",\
"( 13:00 | 13:15 | 13:30 | 13:45 ) ",\
"( 14:00 | 14:15 | 14:30 | 14:45 ) ",\
"( 15:00 | 15:15 | 15:30 | 15:45 ) ",\
"( 16:00 | 16:15 | 16:30 | 16:45 ) ",\
"( 17:00 | 17:15 | 17:30 | 17:45 ) ",\
"( 18:00 | 18:15 | 18:30 | 18:45 ) ",\
"( 19:00 | 19:15 | 19:30 | 19:45 ) ",\
"( 20:00 | 20:15 | 20:30 | 20:45 ) ",\
"( 21:00 | 21:15 | 21:30 | 21:45 ) ",\
"( 22:00 | 22:15 | 22:30 | 22:45 ) ",\
"( 23:00 | 23:15 | 23:30 | 23:45 ) ",\
"Wann soll die Wäsche fertig sein?",\
"Bitte Uhrzeit in HH:MM angeben.",\
"Aktuell ist [%controlUnit%:time] Uhr eingestellt."\
],\
"Uhrzeit": {\
"match": " ?([0-1][0-9]|2[0-3]):[0-5][0-9] ?",\
"commands": [\
"set %controlUnit% time $message",\
"set $SELF say @$recipient Waschmaschine|programmieren|bestätigen"\
]\
},\
"bestätigen": {\
"commands": "set %controlUnit% controlMode auto",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Das Zeitprogramm wurde eingestellt.",\
"Die Wäsche wird voraussichtlich um [%controlUnit%:time] Uhr fertig sein.",\
"Bitte die Waschmaschine vorbereiten."\
]\
}\
},\
"einschalten": {\
"commands": [\
"set %controlUnit% controlMode manual",\
"set %actor% on"\
]\
},\
"Verlaufsdiagramm": {\
"commands": "set %TelegramBot% cmdSend {plotAsPng('%plot%')}",\
"message": "TelegramBot_MTYPE=queryInline (%me%) $message"\
}\
},\
"auto": {\
"setOnly": true,\
"commands": [\
"set %actor% on",\
"set %controlUnit% controlMode manual"\
],\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine wurde automatisch eingeschaltet."\
]\
},\
"manual": {\
"setOnly": true,\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine wurde manuell eingeschaltet."\
]\
},\
"done": {\
"setOnly": true,\
"commands": "set %actor% off",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine ist fertig."\
]\
}\
}
attr Waschmaschine_Dialog evalSpecials actor=HM_2C10D8_Sw\
controlUnit=Waschkeller_washer_controlUnit\
plot=Waschkeller_washer_SVG
</pre>

== TelegramBot ==

In Telegram gibt es die Möglichkeit die Art des Keyboards zu ändern. Links das normale Keyboard, rechts das Inline Keyboard.

[[Datei:76msgDialog menu.png|Normales Keyboard]] [[Datei:76msgDialog menu inline.PNG|Inline Keyboard]]

In diesem '''[https://youtu.be/oRDy2918mVI Video]''' wird Telegram mit einem Inline Keyboard verwendet.

Um eine Nachricht bei Telegram zu verändern, gibt es den Befehl "queryEditInline".
Dafür wird die MsgId von der Nachricht benötigt. Das erledigt ein notify, welches die msgId pro Peer abspeichert:

<pre>
defmod sentMsgIdByPeerId notify .+:sentMsgId.+ {\
return unless($TYPE eq "TelegramBot");;\
\
my $dev_hash = $defs{$NAME};;\
my $sentMsgId = ReadingsVal($NAME, "sentMsgId", "");;\
my $sentMsgPeerId = ReadingsVal($NAME, "sentMsgPeerId", "");;\
my ($contact) = devspec2array("TYPE=(ROOMMATE|GUEST):FILTER=msgContactPush=.*$sentMsgPeerId.*");;\
\
readingsSingleUpdate($dev_hash, "$contact\_sentMsgId", $sentMsgId, 1);;\
}
attr sentMsgIdByPeerId devStateIcon {ReadingsVal($name, "state", "inactive") eq "active" ? ".*:ios-on-blue:inactive" : ".*:ios-off:active"}
attr sentMsgIdByPeerId icon audio_mic
attr sentMsgIdByPeerId room msg
</pre>

Danach wird der Message-Befehl von
<pre>
set <TelegramBot> message
</pre>
auf
<pre>
set <TelegramBot> queryEditInline
</pre>
geändert. Dafür wird ein [[cmdalias]] verwendet:

<pre>
defmod message2queryEditInline cmdalias set .+ message (.|\n)+ AS {\
my ($NAME, $cmd, $message) = split(/[\s]+/, $EVENT, 3);;\
my $TYPE = InternalVal($NAME, "TYPE", "");;\
(my $recipient, $message) = ($message =~ m/(@\S+)? (.+)/s);;\
\
if($TYPE eq "TelegramBot" && $recipient){\
my ($contact) = devspec2array("TYPE=(ROOMMATE|GUEST):FILTER=msgContactPush=.*$recipient.*");;\
my $sentMsgId = ReadingsVal($NAME, "$contact\_sentMsgId", "");;\
\
if($sentMsgId ne ""){\
fhem("set $NAME queryEditInline $sentMsgId $recipient $message");;\
}\
else{\
fhem("set $NAME queryInline $recipient $message");;\
}\
}\
else{\
fhem("set $EVENT");;\
}\
}
attr message2queryEditInline room msg
</pre>

Um wieder zurück zum normalen Keyboard zu gelangen genügt es, das notify und den cmdAlias zu deaktivieren.
Das kann komfortabel über ein notify und einen dummy erledigt werden:
<pre>
defmod inline_normal.NOT notify inline_normal.DUM:.* {\
if ("$EVENT" =~ "on") {\
fhem "set sentMsgIdByPeerId active;; attr message2queryEditInline disable 0";;\
} \
elsif ("$EVENT" =~ "off") {\
fhem "set sentMsgIdByPeerId inactive;; attr message2queryEditInline disable 1";;\
}\
}
</pre>

Weitere Infos zum Thema Inline Keyboard sind in der Antwort #10 im Forum zu finden (siehe Link unten).

== JABBER ==
Hier wird die Verwendung mit Jabber beschrieben...

== WhatsApp ==
Hier wird die Verwendung mit yowsup/WhatsApp beschrieben...

== Links ==
* Thread über das Modul im {{Link2Forum|Topic=77297|LinkText=FHEM Forum}}

[[Kategorie:Hilfsmodul]]

MsgDialog

2017-10-31T09:27:34Z

Binford6000: /* msgConfig */

{{Infobox Modul
|ModPurpose=Dialoge für Sofortnachrichten über TelegramBot, Jabber und WhatsApp
|ModType=h
|ModForumArea=Frontends
|ModTechName=76_msgDialog.pm
|ModOwner={{Link2FU|4106|igami}}
}}

== Zielsetzung ==
Ein zentrale Anforderung an die Haus-Automation ist die Kommunikation mit den Anwendern. Fast jeder Anwender möchte über bestimmte Ereignisse informiert werden und Einstellungen vornehmen. FHEM bietet schon seit längerem die Unterstützung für verschiedene Messaging Dienste an.
Mit dem msgDialog Modul können vordefinierte Dialoge erstellt werden. Die Kommunikation erfolgt dabei über den [[msg]] Befehl welcher zurzeit die bidirektionale Kommunikation über [[TelegramBot]], [[Jabber]] und [[yowsup]] (WhatsApp) unterstützt. Eingehende Nachrichten werden einem ROMMATE oder GUEST zugeordnet. Darüber werden auch die Berechtigungen für die einzelnen Dialoge festgelegt.
Die grundlegende Bedienung wird in diesem '''[https://youtu.be/yiCOTeR1YVQ Video]''' am Beispiel von TelegramBot gezeigt.

== Konfiguration ==

=== Voraussetzungen ===
Für dieses Modul wird das Perl JSON Modul benötigt. Auf einem Debian-basierten System (z.B RaspberryPI o.ä.) kann man das mit dem folgenden Befehl installieren:
<pre>
sudo apt-get install libjson-perl
</pre>

=== Hinweis zu den Code Beispielen ===
Es handelt sich bei den Beispielen um eine Raw definition, siehe auch [[Import_von_Code_Snippets]]

=== msgConfig ===

Als erstes benötigt man ein definiertes msgConfig device:

<pre>
defmod myMsgConfig msgConfig
attr myMsgConfig msgDialog_evalSpecials me=<Aktivierungswort bzw. -Nachricht>
TelegramBot=<Name des TelegramBot-device>
attr myMsgConfig msgContactPush TelegramBot
attr myMsgConfig room msg
</pre>

Falls bereits vorhanden, müssen natürlich nur die fehlenden Attribute gesetzt werden.

* msgDialog_evalSpecials: key1=value1 key2=value2 ... Leerzeichen getrennte Liste von Name=Wert Paaren. Wert kann Leerzeichen enthalten, falls es in "" oder {} eingeschlossen ist. Wert wird als perl-Ausdruck ausgewertet, falls es in {} eingeschlossen ist. In der DEF werden %Name% Zeichenketten durch den zugehörigen Wert ersetzt. Wenn der selbe Name im msgConfig und msgDialog definiert wurde, wird der Wert aus msgDialog verwendet.

*msgDialog_msgCommand <command>:
Befehl zum Versenden einer Nachricht. Die Vorgabe ist "msg push \@$recipients $message"

=== ROOMMATE / GUEST ===
Für jeden Dialog kann festgelegt werden welche Person dazu berechtigt ist. Dazu sind Geräte vom Typ ROOMMATE oder GUEST mit definiertem msgContactPush Attribut erforderlich. Es ist darauf zu achten, dass das Reading fhemMsgRcvPush ein Event erzeugt.

=== Define ===

Definition des metaDialogs:
Zur Auflistung aller berechtigten Dialoge dient - was sonst - ein Dialog!

<pre>
defmod meta_Dialog msgDialog {\
"%me%": {\
"match": "\/?(start|%me%)",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"{return('(' . join(') (', sort(split('\n', fhem('get TYPE=msgDialog:FILTER=NAME!=$SELF:FILTER=allowed=.*($recipient|everyone).* trigger')))) . ') ')}",\
"(abbrechen) ",\
"Ich kann folgendes für dich tun:"\
]\
},\
"abbrechen": {\
"match": "\/?abbrechen",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"(%me%) ",\
"Dialog abgebrochen."\
] \
},\
"beenden": {\
"match": "\/?beenden",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"(%me%) ",\
"Dialog beendet."\
]\
}\
}

attr meta_Dialog DbLogExclude .*
attr meta_Dialog allowed everyone
attr meta_Dialog room msg
</pre>

Aufgrund der Komplexität eines Dialogs mit JSON ist es am praktikabelsten, zunächst einen leeren Dialog zu definieren:
<pre>
define <name> msgDialog {}
</pre>

Anschließend kann die DEF in der Detail-Ansicht des Dialog-Device bearbeitet werden. Jeder Dialog basiert auf der folgenden Struktur von einfach bis komplex.

<pre>
{
"<TRIGGER>": {
"match": "<regex>",
"setOnly": (true|false),
"commands": "(fhem command|{perl code})",
"message": [
"{perl code}",
"text"
],
"<NEXT TRIGGER 1>": {
...
},
"<NEXT TRIGGER 2>": {
...
}
}
}
</pre>

Um den JSON-Teil der Dialoge zu testen, empfiehlt sich ein Besuch auf https://jsonlint.com/
Hier kann der selbst geschriebene JSON-Code validiert werden.

*TRIGGER: Kann ein beliebiger Text sein. Es wird geprüft ob die eingehende Nachricht damit übereinstimmt. Falls ja, wird der Dialog an dieser Stelle fortgesetzt.

*match: Wenn nicht nur genau eine Nachricht zugelassen werden soll, kann noch eine regex angegeben werden. Die regex muss auf die gesamte eingehnde Nachricht zutreffen.

*setOnly: Kann optional auf true oder false gestellt werden. In beiden fällen wird der TRIGGER dann nicht bei "get <name> trigger" zurück gegeben.
Wenn setOnly auf "true" gestellt wird, kann der Dialog an dieser Stelle nicht durch eingehende Nachrichten ausgelöst werden, sondern nur über "get <name> say TRIGGER". Dies kann dazu genutzt werden um einen Dialog aus FHEM heraus zu initiieren.

*commands: Kann einen einzelnen oder mehrere Befehle enthalten:
<pre>
"commands":
"single command"
"commands": [
"command 1",
"command 2",
"{perl command}"
]
</pre>

*message: Kann einen einzelnen oder mehrere Textte enthalten die mit einen Zeilenumbruch verbunden werden:
<pre>
"message": "text"
</pre>
<pre>
"message": [
"text 1",
"text 2",
"{return from perl command}"
]
</pre>

Bei mehrstufigen Dialogen wird diese Struktur ineinander verschachtelt angegeben.
Es werden Variablen und Platzhalter, welche unter dem Attribut evalSpecials definiert werden, ausgewertet.

=== Variablen ===
*$SELF: Eigenname des msgDialog
*$message: eingegangene Nachricht
*$recipient: Name des Dialogpartners

=== Attribute ===
*allowed: Liste mit allen RESIDENTS und ROOMMATE die für diesen Dialog berechtigt sind.
*disable: [0|1] Dialog ist aktiviert|deaktiviert.
*disabledForIntervals: HH:MM-HH:MM HH:MM-HH-MM ...
*evalSpecials: key1=value1 key2=value2 ...Leerzeichen getrennte Liste von Name=Wert Paaren. Wert kann Leerzeichen enthalten, falls es in "" oder {} eingeschlossen ist. Wert wird als perl-Ausdruck ausgewertet, falls es in {} eingeschlossen ist. In der DEF werden %Name% Zeichenketten durch den zugehörigen Wert ersetzt. Dieses Attribut ist als "msgDialog_evalSpecials" im msgConfig Gerät vorhanden. Wenn der selbe Name im msgConfig und msgDialog definiert wurde, wird der Wert aus msgDialog verwendet.
*msgCommand <command>: Befehl der zum Versenden einer Nachricht verwendet wird. Die Vorgabe ist "msg push \@$recipients $message" Dieses Attribut ist als "msgDialog_msgCommand" im msgConfig Gerät vorhanden.

=== set ===
*reset: Setzt den Dialog für alle Benutzer zurück.
*say [@<recipient1>[,<recipient2>,...]] <TRIGGER>[|<NEXT TRIGGER>|...]: Der Dialog wird für alle angegeben Empänger an der angegeben Stelle fortgeführt. Sind keine Empfänger angegeben wird der Dialog für alle unter dem Attribut allowed angegebenen Empfänger fortgeführt.
*updateAllowed: Aktualisiert die Auswahl für das Attribut allowed.

=== get ===
*trigger: Listet alle TRIGGER der ersten Ebene auf bei denen nicht setOnly angegeben ist.

=== READINGS ===
*$recipient_history: Durch | getrennte Liste von TRIGGER um den aktuellen Zustand des Dialogs zu sichern. Für jeden Dialogpartner wird ein Reading angelegt. Wenn der Dialog beendet ist wird das Reading zurückgesetzt.

== Beispiele ==

==== Programmierung der Waschmaschine ====
Das ist ein Beispiel zur Programmierung einer Waschmaschine wie auch oben im Video zu sehen:
<pre>
defmod Waschmaschine_Dialog msgDialog { "Waschmaschine": {\
"message": [\
"{return('(Zeitprogramm stoppen) ') if(ReadingsVal('%controlUnit%', 'controlMode', '') eq 'auto')}",\
"{return('(programmieren) ') if(ReadingsVal('%actor%', 'state', '') ne 'on')}",\
"{return('(einschalten) ') if(ReadingsVal('%actor%', 'state', '') ne 'on')}",\
"(Verlaufsdiagramm) ",\
"(abbrechen) ",\
"{return('Waschmaschine: ' . (ReadingsVal('%actor%', 'state', '') eq 'on' ? 'eingeschaltet' : 'ausgeschaltet'))}",\
"{return('Modus: ' . (ReadingsVal('%controlUnit%', 'controlMode', '') eq 'auto' ? 'Automatik' : 'Manuell (' . ReadingsVal('%controlUnit%', 'time', '') . ')'))}"\
],\
"Zeitprogramm stoppen": {\
"commands": "set %controlUnit% controlMode manual",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Das Zeitprogramm wurde gestoppt."\
]\
},\
"programmieren": {\
"message": [\
"(bestätigen|zurück|abbrechen) ",\
"( 00:00 | 00:15 | 00:30 | 00:45 ) ",\
"( 01:00 | 01:15 | 01:30 | 01:45 ) ",\
"( 02:00 | 02:15 | 02:30 | 02:45 ) ",\
"( 03:00 | 03:15 | 03:30 | 03:45 ) ",\
"( 04:00 | 04:15 | 04:30 | 04:45 ) ",\
"( 05:00 | 05:15 | 05:30 | 05:45 ) ",\
"( 06:00 | 06:15 | 06:30 | 06:45 ) ",\
"( 07:00 | 07:15 | 07:30 | 07:45 ) ",\
"( 08:00 | 08:15 | 08:30 | 08:45 ) ",\
"( 09:00 | 09:15 | 09:30 | 09:45 ) ",\
"( 10:00 | 10:15 | 10:30 | 10:45 ) ",\
"( 11:00 | 11:15 | 11:30 | 11:45 ) ",\
"( 12:00 | 12:15 | 12:30 | 12:45 ) ",\
"( 13:00 | 13:15 | 13:30 | 13:45 ) ",\
"( 14:00 | 14:15 | 14:30 | 14:45 ) ",\
"( 15:00 | 15:15 | 15:30 | 15:45 ) ",\
"( 16:00 | 16:15 | 16:30 | 16:45 ) ",\
"( 17:00 | 17:15 | 17:30 | 17:45 ) ",\
"( 18:00 | 18:15 | 18:30 | 18:45 ) ",\
"( 19:00 | 19:15 | 19:30 | 19:45 ) ",\
"( 20:00 | 20:15 | 20:30 | 20:45 ) ",\
"( 21:00 | 21:15 | 21:30 | 21:45 ) ",\
"( 22:00 | 22:15 | 22:30 | 22:45 ) ",\
"( 23:00 | 23:15 | 23:30 | 23:45 ) ",\
"Wann soll die Wäsche fertig sein?",\
"Bitte Uhrzeit in HH:MM angeben.",\
"Aktuell ist [%controlUnit%:time] Uhr eingestellt."\
],\
"Uhrzeit": {\
"match": " ?([0-1][0-9]|2[0-3]):[0-5][0-9] ?",\
"commands": [\
"set %controlUnit% time $message",\
"set $SELF say @$recipient Waschmaschine|programmieren|bestätigen"\
]\
},\
"bestätigen": {\
"commands": "set %controlUnit% controlMode auto",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Das Zeitprogramm wurde eingestellt.",\
"Die Wäsche wird voraussichtlich um [%controlUnit%:time] Uhr fertig sein.",\
"Bitte die Waschmaschine vorbereiten."\
]\
}\
},\
"einschalten": {\
"commands": [\
"set %controlUnit% controlMode manual",\
"set %actor% on"\
]\
},\
"Verlaufsdiagramm": {\
"commands": "set %TelegramBot% cmdSend {plotAsPng('%plot%')}",\
"message": "TelegramBot_MTYPE=queryInline (%me%) $message"\
}\
},\
"auto": {\
"setOnly": true,\
"commands": [\
"set %actor% on",\
"set %controlUnit% controlMode manual"\
],\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine wurde automatisch eingeschaltet."\
]\
},\
"manual": {\
"setOnly": true,\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine wurde manuell eingeschaltet."\
]\
},\
"done": {\
"setOnly": true,\
"commands": "set %actor% off",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine ist fertig."\
]\
}\
}
attr Waschmaschine_Dialog evalSpecials actor=HM_2C10D8_Sw\
controlUnit=Waschkeller_washer_controlUnit\
plot=Waschkeller_washer_SVG
</pre>

== TelegramBot ==

In Telegram gibt es die Möglichkeit die Art des Keyboards zu ändern. Links das normale Keyboard, rechts das Inline Keyboard.

[[Datei:76msgDialog menu.png|Normales Keyboard]] [[Datei:76msgDialog menu inline.PNG|Inline Keyboard]]

In diesem '''[https://youtu.be/oRDy2918mVI Video]''' wird Telegram mit einem Inline Keyboard verwendet.

Um eine Nachricht bei Telegram zu verändern, gibt es den Befehl "queryEditInline".
Dafür wird die MsgId von der Nachricht benötigt. Das erledigt ein notify, welches die msgId pro Peer abspeichert:

<pre>
defmod sentMsgIdByPeerId notify .+:sentMsgId.+ {\
return unless($TYPE eq "TelegramBot");;\
\
my $dev_hash = $defs{$NAME};;\
my $sentMsgId = ReadingsVal($NAME, "sentMsgId", "");;\
my $sentMsgPeerId = ReadingsVal($NAME, "sentMsgPeerId", "");;\
my ($contact) = devspec2array("TYPE=(ROOMMATE|GUEST):FILTER=msgContactPush=.*$sentMsgPeerId.*");;\
\
readingsSingleUpdate($dev_hash, "$contact\_sentMsgId", $sentMsgId, 1);;\
}
attr sentMsgIdByPeerId devStateIcon {ReadingsVal($name, "state", "inactive") eq "active" ? ".*:ios-on-blue:inactive" : ".*:ios-off:active"}
attr sentMsgIdByPeerId icon audio_mic
attr sentMsgIdByPeerId room msg
</pre>

Danach wird der Message-Befehl von
<pre>
set <TelegramBot> message
</pre>
auf
<pre>
set <TelegramBot> queryEditInline
</pre>
geändert. Dafür wird ein [[cmdalias]] verwendet:

<pre>
defmod message2queryEditInline cmdalias set .+ message (.|\n)+ AS {\
my ($NAME, $cmd, $message) = split(/[\s]+/, $EVENT, 3);;\
my $TYPE = InternalVal($NAME, "TYPE", "");;\
(my $recipient, $message) = ($message =~ m/(@\S+)? (.+)/s);;\
\
if($TYPE eq "TelegramBot" && $recipient){\
my ($contact) = devspec2array("TYPE=(ROOMMATE|GUEST):FILTER=msgContactPush=.*$recipient.*");;\
my $sentMsgId = ReadingsVal($NAME, "$contact\_sentMsgId", "");;\
\
if($sentMsgId ne ""){\
fhem("set $NAME queryEditInline $sentMsgId $recipient $message");;\
}\
else{\
fhem("set $NAME queryInline $recipient $message");;\
}\
}\
else{\
fhem("set $EVENT");;\
}\
}
attr message2queryEditInline room msg
</pre>

Um wieder zurück zum normalen Keyboard zu gelangen genügt es, das notify und den cmdAlias zu deaktivieren.
Das kann komfortabel über ein notify und einen dummy erledigt werden:
<pre>
defmod inline_normal.NOT notify inline_normal.DUM:.* {\
if ("$EVENT" =~ "on") {\
fhem "set sentMsgIdByPeerId active;; attr message2queryEditInline disable 0";;\
} \
elsif ("$EVENT" =~ "off") {\
fhem "set sentMsgIdByPeerId inactive;; attr message2queryEditInline disable 1";;\
}\
}
</pre>

Weitere Infos zum Thema Inline Keyboard sind in der Antwort #10 im Forum zu finden (siehe Link unten).

== JABBER ==
Hier wird die Verwendung mit Jabber beschrieben...

== WhatsApp ==
Hier wird die Verwendung mit yowsup/WhatsApp beschrieben...

== Links ==
* Thread über das Modul im {{Link2Forum|Topic=77297|LinkText=FHEM Forum}}

[[Kategorie:Hilfsmodul]]

MsgDialog

2017-10-31T09:26:37Z

Binford6000: /* msgConfig */

{{Infobox Modul
|ModPurpose=Dialoge für Sofortnachrichten über TelegramBot, Jabber und WhatsApp
|ModType=h
|ModForumArea=Frontends
|ModTechName=76_msgDialog.pm
|ModOwner={{Link2FU|4106|igami}}
}}

== Zielsetzung ==
Ein zentrale Anforderung an die Haus-Automation ist die Kommunikation mit den Anwendern. Fast jeder Anwender möchte über bestimmte Ereignisse informiert werden und Einstellungen vornehmen. FHEM bietet schon seit längerem die Unterstützung für verschiedene Messaging Dienste an.
Mit dem msgDialog Modul können vordefinierte Dialoge erstellt werden. Die Kommunikation erfolgt dabei über den [[msg]] Befehl welcher zurzeit die bidirektionale Kommunikation über [[TelegramBot]], [[Jabber]] und [[yowsup]] (WhatsApp) unterstützt. Eingehende Nachrichten werden einem ROMMATE oder GUEST zugeordnet. Darüber werden auch die Berechtigungen für die einzelnen Dialoge festgelegt.
Die grundlegende Bedienung wird in diesem '''[https://youtu.be/yiCOTeR1YVQ Video]''' am Beispiel von TelegramBot gezeigt.

== Konfiguration ==

=== Voraussetzungen ===
Für dieses Modul wird das Perl JSON Modul benötigt. Auf einem Debian-basierten System (z.B RaspberryPI o.ä.) kann man das mit dem folgenden Befehl installieren:
<pre>
sudo apt-get install libjson-perl
</pre>

=== Hinweis zu den Code Beispielen ===
Es handelt sich bei den Beispielen um eine Raw definition, siehe auch [[Import_von_Code_Snippets]]

=== msgConfig ===

Als erstes benötigt man ein definiertes msgConfig device:

<pre>
defmod myMsgConfig msgConfig
attr myMsgConfig msgDialog_evalSpecials me=<Aktivierungswort bzw. -Nachricht>
TelegramBot=<Name des TelegramBot-device>
attr myMsgConfig msgContactPush TelegramBot
attr myMsgConfig room msg
</pre>

Falls bereits vorhanden, müssen natürlich nur die fehlenden Attribute gesetzt werden.

* msgDialog_evalSpecials:
key1=value1 key2=value2 ... Leerzeichen getrennte Liste von Name=Wert Paaren. Wert kann Leerzeichen enthalten, falls es in "" oder {} eingeschlossen ist. Wert wird als perl-Ausdruck ausgewertet, falls es in {} eingeschlossen ist. In der DEF werden %Name% Zeichenketten durch den zugehörigen Wert ersetzt. Wenn der selbe Name im msgConfig und msgDialog definiert wurde, wird der Wert aus msgDialog verwendet.

*msgDialog_msgCommand <command>:
Befehl zum Versenden einer Nachricht. Die Vorgabe ist "msg push \@$recipients $message"

=== ROOMMATE / GUEST ===
Für jeden Dialog kann festgelegt werden welche Person dazu berechtigt ist. Dazu sind Geräte vom Typ ROOMMATE oder GUEST mit definiertem msgContactPush Attribut erforderlich. Es ist darauf zu achten, dass das Reading fhemMsgRcvPush ein Event erzeugt.

=== Define ===

Definition des metaDialogs:
Zur Auflistung aller berechtigten Dialoge dient - was sonst - ein Dialog!

<pre>
defmod meta_Dialog msgDialog {\
"%me%": {\
"match": "\/?(start|%me%)",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"{return('(' . join(') (', sort(split('\n', fhem('get TYPE=msgDialog:FILTER=NAME!=$SELF:FILTER=allowed=.*($recipient|everyone).* trigger')))) . ') ')}",\
"(abbrechen) ",\
"Ich kann folgendes für dich tun:"\
]\
},\
"abbrechen": {\
"match": "\/?abbrechen",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"(%me%) ",\
"Dialog abgebrochen."\
] \
},\
"beenden": {\
"match": "\/?beenden",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"(%me%) ",\
"Dialog beendet."\
]\
}\
}

attr meta_Dialog DbLogExclude .*
attr meta_Dialog allowed everyone
attr meta_Dialog room msg
</pre>

Aufgrund der Komplexität eines Dialogs mit JSON ist es am praktikabelsten, zunächst einen leeren Dialog zu definieren:
<pre>
define <name> msgDialog {}
</pre>

Anschließend kann die DEF in der Detail-Ansicht des Dialog-Device bearbeitet werden. Jeder Dialog basiert auf der folgenden Struktur von einfach bis komplex.

<pre>
{
"<TRIGGER>": {
"match": "<regex>",
"setOnly": (true|false),
"commands": "(fhem command|{perl code})",
"message": [
"{perl code}",
"text"
],
"<NEXT TRIGGER 1>": {
...
},
"<NEXT TRIGGER 2>": {
...
}
}
}
</pre>

Um den JSON-Teil der Dialoge zu testen, empfiehlt sich ein Besuch auf https://jsonlint.com/
Hier kann der selbst geschriebene JSON-Code validiert werden.

*TRIGGER: Kann ein beliebiger Text sein. Es wird geprüft ob die eingehende Nachricht damit übereinstimmt. Falls ja, wird der Dialog an dieser Stelle fortgesetzt.

*match: Wenn nicht nur genau eine Nachricht zugelassen werden soll, kann noch eine regex angegeben werden. Die regex muss auf die gesamte eingehnde Nachricht zutreffen.

*setOnly: Kann optional auf true oder false gestellt werden. In beiden fällen wird der TRIGGER dann nicht bei "get <name> trigger" zurück gegeben.
Wenn setOnly auf "true" gestellt wird, kann der Dialog an dieser Stelle nicht durch eingehende Nachrichten ausgelöst werden, sondern nur über "get <name> say TRIGGER". Dies kann dazu genutzt werden um einen Dialog aus FHEM heraus zu initiieren.

*commands: Kann einen einzelnen oder mehrere Befehle enthalten:
<pre>
"commands":
"single command"
"commands": [
"command 1",
"command 2",
"{perl command}"
]
</pre>

*message: Kann einen einzelnen oder mehrere Textte enthalten die mit einen Zeilenumbruch verbunden werden:
<pre>
"message": "text"
</pre>
<pre>
"message": [
"text 1",
"text 2",
"{return from perl command}"
]
</pre>

Bei mehrstufigen Dialogen wird diese Struktur ineinander verschachtelt angegeben.
Es werden Variablen und Platzhalter, welche unter dem Attribut evalSpecials definiert werden, ausgewertet.

=== Variablen ===
*$SELF: Eigenname des msgDialog
*$message: eingegangene Nachricht
*$recipient: Name des Dialogpartners

=== Attribute ===
*allowed: Liste mit allen RESIDENTS und ROOMMATE die für diesen Dialog berechtigt sind.
*disable: [0|1] Dialog ist aktiviert|deaktiviert.
*disabledForIntervals: HH:MM-HH:MM HH:MM-HH-MM ...
*evalSpecials: key1=value1 key2=value2 ...Leerzeichen getrennte Liste von Name=Wert Paaren. Wert kann Leerzeichen enthalten, falls es in "" oder {} eingeschlossen ist. Wert wird als perl-Ausdruck ausgewertet, falls es in {} eingeschlossen ist. In der DEF werden %Name% Zeichenketten durch den zugehörigen Wert ersetzt. Dieses Attribut ist als "msgDialog_evalSpecials" im msgConfig Gerät vorhanden. Wenn der selbe Name im msgConfig und msgDialog definiert wurde, wird der Wert aus msgDialog verwendet.
*msgCommand <command>: Befehl der zum Versenden einer Nachricht verwendet wird. Die Vorgabe ist "msg push \@$recipients $message" Dieses Attribut ist als "msgDialog_msgCommand" im msgConfig Gerät vorhanden.

=== set ===
*reset: Setzt den Dialog für alle Benutzer zurück.
*say [@<recipient1>[,<recipient2>,...]] <TRIGGER>[|<NEXT TRIGGER>|...]: Der Dialog wird für alle angegeben Empänger an der angegeben Stelle fortgeführt. Sind keine Empfänger angegeben wird der Dialog für alle unter dem Attribut allowed angegebenen Empfänger fortgeführt.
*updateAllowed: Aktualisiert die Auswahl für das Attribut allowed.

=== get ===
*trigger: Listet alle TRIGGER der ersten Ebene auf bei denen nicht setOnly angegeben ist.

=== READINGS ===
*$recipient_history: Durch | getrennte Liste von TRIGGER um den aktuellen Zustand des Dialogs zu sichern. Für jeden Dialogpartner wird ein Reading angelegt. Wenn der Dialog beendet ist wird das Reading zurückgesetzt.

== Beispiele ==

==== Programmierung der Waschmaschine ====
Das ist ein Beispiel zur Programmierung einer Waschmaschine wie auch oben im Video zu sehen:
<pre>
defmod Waschmaschine_Dialog msgDialog { "Waschmaschine": {\
"message": [\
"{return('(Zeitprogramm stoppen) ') if(ReadingsVal('%controlUnit%', 'controlMode', '') eq 'auto')}",\
"{return('(programmieren) ') if(ReadingsVal('%actor%', 'state', '') ne 'on')}",\
"{return('(einschalten) ') if(ReadingsVal('%actor%', 'state', '') ne 'on')}",\
"(Verlaufsdiagramm) ",\
"(abbrechen) ",\
"{return('Waschmaschine: ' . (ReadingsVal('%actor%', 'state', '') eq 'on' ? 'eingeschaltet' : 'ausgeschaltet'))}",\
"{return('Modus: ' . (ReadingsVal('%controlUnit%', 'controlMode', '') eq 'auto' ? 'Automatik' : 'Manuell (' . ReadingsVal('%controlUnit%', 'time', '') . ')'))}"\
],\
"Zeitprogramm stoppen": {\
"commands": "set %controlUnit% controlMode manual",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Das Zeitprogramm wurde gestoppt."\
]\
},\
"programmieren": {\
"message": [\
"(bestätigen|zurück|abbrechen) ",\
"( 00:00 | 00:15 | 00:30 | 00:45 ) ",\
"( 01:00 | 01:15 | 01:30 | 01:45 ) ",\
"( 02:00 | 02:15 | 02:30 | 02:45 ) ",\
"( 03:00 | 03:15 | 03:30 | 03:45 ) ",\
"( 04:00 | 04:15 | 04:30 | 04:45 ) ",\
"( 05:00 | 05:15 | 05:30 | 05:45 ) ",\
"( 06:00 | 06:15 | 06:30 | 06:45 ) ",\
"( 07:00 | 07:15 | 07:30 | 07:45 ) ",\
"( 08:00 | 08:15 | 08:30 | 08:45 ) ",\
"( 09:00 | 09:15 | 09:30 | 09:45 ) ",\
"( 10:00 | 10:15 | 10:30 | 10:45 ) ",\
"( 11:00 | 11:15 | 11:30 | 11:45 ) ",\
"( 12:00 | 12:15 | 12:30 | 12:45 ) ",\
"( 13:00 | 13:15 | 13:30 | 13:45 ) ",\
"( 14:00 | 14:15 | 14:30 | 14:45 ) ",\
"( 15:00 | 15:15 | 15:30 | 15:45 ) ",\
"( 16:00 | 16:15 | 16:30 | 16:45 ) ",\
"( 17:00 | 17:15 | 17:30 | 17:45 ) ",\
"( 18:00 | 18:15 | 18:30 | 18:45 ) ",\
"( 19:00 | 19:15 | 19:30 | 19:45 ) ",\
"( 20:00 | 20:15 | 20:30 | 20:45 ) ",\
"( 21:00 | 21:15 | 21:30 | 21:45 ) ",\
"( 22:00 | 22:15 | 22:30 | 22:45 ) ",\
"( 23:00 | 23:15 | 23:30 | 23:45 ) ",\
"Wann soll die Wäsche fertig sein?",\
"Bitte Uhrzeit in HH:MM angeben.",\
"Aktuell ist [%controlUnit%:time] Uhr eingestellt."\
],\
"Uhrzeit": {\
"match": " ?([0-1][0-9]|2[0-3]):[0-5][0-9] ?",\
"commands": [\
"set %controlUnit% time $message",\
"set $SELF say @$recipient Waschmaschine|programmieren|bestätigen"\
]\
},\
"bestätigen": {\
"commands": "set %controlUnit% controlMode auto",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Das Zeitprogramm wurde eingestellt.",\
"Die Wäsche wird voraussichtlich um [%controlUnit%:time] Uhr fertig sein.",\
"Bitte die Waschmaschine vorbereiten."\
]\
}\
},\
"einschalten": {\
"commands": [\
"set %controlUnit% controlMode manual",\
"set %actor% on"\
]\
},\
"Verlaufsdiagramm": {\
"commands": "set %TelegramBot% cmdSend {plotAsPng('%plot%')}",\
"message": "TelegramBot_MTYPE=queryInline (%me%) $message"\
}\
},\
"auto": {\
"setOnly": true,\
"commands": [\
"set %actor% on",\
"set %controlUnit% controlMode manual"\
],\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine wurde automatisch eingeschaltet."\
]\
},\
"manual": {\
"setOnly": true,\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine wurde manuell eingeschaltet."\
]\
},\
"done": {\
"setOnly": true,\
"commands": "set %actor% off",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine ist fertig."\
]\
}\
}
attr Waschmaschine_Dialog evalSpecials actor=HM_2C10D8_Sw\
controlUnit=Waschkeller_washer_controlUnit\
plot=Waschkeller_washer_SVG
</pre>

== TelegramBot ==

In Telegram gibt es die Möglichkeit die Art des Keyboards zu ändern. Links das normale Keyboard, rechts das Inline Keyboard.

[[Datei:76msgDialog menu.png|Normales Keyboard]] [[Datei:76msgDialog menu inline.PNG|Inline Keyboard]]

In diesem '''[https://youtu.be/oRDy2918mVI Video]''' wird Telegram mit einem Inline Keyboard verwendet.

Um eine Nachricht bei Telegram zu verändern, gibt es den Befehl "queryEditInline".
Dafür wird die MsgId von der Nachricht benötigt. Das erledigt ein notify, welches die msgId pro Peer abspeichert:

<pre>
defmod sentMsgIdByPeerId notify .+:sentMsgId.+ {\
return unless($TYPE eq "TelegramBot");;\
\
my $dev_hash = $defs{$NAME};;\
my $sentMsgId = ReadingsVal($NAME, "sentMsgId", "");;\
my $sentMsgPeerId = ReadingsVal($NAME, "sentMsgPeerId", "");;\
my ($contact) = devspec2array("TYPE=(ROOMMATE|GUEST):FILTER=msgContactPush=.*$sentMsgPeerId.*");;\
\
readingsSingleUpdate($dev_hash, "$contact\_sentMsgId", $sentMsgId, 1);;\
}
attr sentMsgIdByPeerId devStateIcon {ReadingsVal($name, "state", "inactive") eq "active" ? ".*:ios-on-blue:inactive" : ".*:ios-off:active"}
attr sentMsgIdByPeerId icon audio_mic
attr sentMsgIdByPeerId room msg
</pre>

Danach wird der Message-Befehl von
<pre>
set <TelegramBot> message
</pre>
auf
<pre>
set <TelegramBot> queryEditInline
</pre>
geändert. Dafür wird ein [[cmdalias]] verwendet:

<pre>
defmod message2queryEditInline cmdalias set .+ message (.|\n)+ AS {\
my ($NAME, $cmd, $message) = split(/[\s]+/, $EVENT, 3);;\
my $TYPE = InternalVal($NAME, "TYPE", "");;\
(my $recipient, $message) = ($message =~ m/(@\S+)? (.+)/s);;\
\
if($TYPE eq "TelegramBot" && $recipient){\
my ($contact) = devspec2array("TYPE=(ROOMMATE|GUEST):FILTER=msgContactPush=.*$recipient.*");;\
my $sentMsgId = ReadingsVal($NAME, "$contact\_sentMsgId", "");;\
\
if($sentMsgId ne ""){\
fhem("set $NAME queryEditInline $sentMsgId $recipient $message");;\
}\
else{\
fhem("set $NAME queryInline $recipient $message");;\
}\
}\
else{\
fhem("set $EVENT");;\
}\
}
attr message2queryEditInline room msg
</pre>

Um wieder zurück zum normalen Keyboard zu gelangen genügt es, das notify und den cmdAlias zu deaktivieren.
Das kann komfortabel über ein notify und einen dummy erledigt werden:
<pre>
defmod inline_normal.NOT notify inline_normal.DUM:.* {\
if ("$EVENT" =~ "on") {\
fhem "set sentMsgIdByPeerId active;; attr message2queryEditInline disable 0";;\
} \
elsif ("$EVENT" =~ "off") {\
fhem "set sentMsgIdByPeerId inactive;; attr message2queryEditInline disable 1";;\
}\
}
</pre>

Weitere Infos zum Thema Inline Keyboard sind in der Antwort #10 im Forum zu finden (siehe Link unten).

== JABBER ==
Hier wird die Verwendung mit Jabber beschrieben...

== WhatsApp ==
Hier wird die Verwendung mit yowsup/WhatsApp beschrieben...

== Links ==
* Thread über das Modul im {{Link2Forum|Topic=77297|LinkText=FHEM Forum}}

[[Kategorie:Hilfsmodul]]

MsgDialog

2017-10-31T09:20:09Z

Binford6000: /* ROOMMATE / GUEST */

{{Infobox Modul
|ModPurpose=Dialoge für Sofortnachrichten über TelegramBot, Jabber und WhatsApp
|ModType=h
|ModForumArea=Frontends
|ModTechName=76_msgDialog.pm
|ModOwner={{Link2FU|4106|igami}}
}}

== Zielsetzung ==
Ein zentrale Anforderung an die Haus-Automation ist die Kommunikation mit den Anwendern. Fast jeder Anwender möchte über bestimmte Ereignisse informiert werden und Einstellungen vornehmen. FHEM bietet schon seit längerem die Unterstützung für verschiedene Messaging Dienste an.
Mit dem msgDialog Modul können vordefinierte Dialoge erstellt werden. Die Kommunikation erfolgt dabei über den [[msg]] Befehl welcher zurzeit die bidirektionale Kommunikation über [[TelegramBot]], [[Jabber]] und [[yowsup]] (WhatsApp) unterstützt. Eingehende Nachrichten werden einem ROMMATE oder GUEST zugeordnet. Darüber werden auch die Berechtigungen für die einzelnen Dialoge festgelegt.
Die grundlegende Bedienung wird in diesem '''[https://youtu.be/yiCOTeR1YVQ Video]''' am Beispiel von TelegramBot gezeigt.

== Konfiguration ==

=== Voraussetzungen ===
Für dieses Modul wird das Perl JSON Modul benötigt. Auf einem Debian-basierten System (z.B RaspberryPI o.ä.) kann man das mit dem folgenden Befehl installieren:
<pre>
sudo apt-get install libjson-perl
</pre>

=== Hinweis zu den Code Beispielen ===
Es handelt sich bei den Beispielen um eine Raw definition, siehe auch [[Import_von_Code_Snippets]]

=== msgConfig ===

Als erstes benötigt man ein definiertes msgConfig device:

<pre>
defmod myMsgConfig msgConfig
attr myMsgConfig msgDialog_evalSpecials me=<Aktivierungswort bzw. -Nachricht>
TelegramBot=<Name des TelegramBot-device>
attr myMsgConfig msgContactPush TelegramBot
attr myMsgConfig room msg
</pre>

Falls bereits vorhanden, müssen natürlich nur die fehlenden Attribute gesetzt werden.

=== ROOMMATE / GUEST ===
Für jeden Dialog kann festgelegt werden welche Person dazu berechtigt ist. Dazu sind Geräte vom Typ ROOMMATE oder GUEST mit definiertem msgContactPush Attribut erforderlich. Es ist darauf zu achten, dass das Reading fhemMsgRcvPush ein Event erzeugt.

=== Define ===

Definition des metaDialogs:
Zur Auflistung aller berechtigten Dialoge dient - was sonst - ein Dialog!

<pre>
defmod meta_Dialog msgDialog {\
"%me%": {\
"match": "\/?(start|%me%)",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"{return('(' . join(') (', sort(split('\n', fhem('get TYPE=msgDialog:FILTER=NAME!=$SELF:FILTER=allowed=.*($recipient|everyone).* trigger')))) . ') ')}",\
"(abbrechen) ",\
"Ich kann folgendes für dich tun:"\
]\
},\
"abbrechen": {\
"match": "\/?abbrechen",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"(%me%) ",\
"Dialog abgebrochen."\
] \
},\
"beenden": {\
"match": "\/?beenden",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"(%me%) ",\
"Dialog beendet."\
]\
}\
}

attr meta_Dialog DbLogExclude .*
attr meta_Dialog allowed everyone
attr meta_Dialog room msg
</pre>

Aufgrund der Komplexität eines Dialogs mit JSON ist es am praktikabelsten, zunächst einen leeren Dialog zu definieren:
<pre>
define <name> msgDialog {}
</pre>

Anschließend kann die DEF in der Detail-Ansicht des Dialog-Device bearbeitet werden. Jeder Dialog basiert auf der folgenden Struktur von einfach bis komplex.

<pre>
{
"<TRIGGER>": {
"match": "<regex>",
"setOnly": (true|false),
"commands": "(fhem command|{perl code})",
"message": [
"{perl code}",
"text"
],
"<NEXT TRIGGER 1>": {
...
},
"<NEXT TRIGGER 2>": {
...
}
}
}
</pre>

Um den JSON-Teil der Dialoge zu testen, empfiehlt sich ein Besuch auf https://jsonlint.com/
Hier kann der selbst geschriebene JSON-Code validiert werden.

*TRIGGER: Kann ein beliebiger Text sein. Es wird geprüft ob die eingehende Nachricht damit übereinstimmt. Falls ja, wird der Dialog an dieser Stelle fortgesetzt.

*match: Wenn nicht nur genau eine Nachricht zugelassen werden soll, kann noch eine regex angegeben werden. Die regex muss auf die gesamte eingehnde Nachricht zutreffen.

*setOnly: Kann optional auf true oder false gestellt werden. In beiden fällen wird der TRIGGER dann nicht bei "get <name> trigger" zurück gegeben.
Wenn setOnly auf "true" gestellt wird, kann der Dialog an dieser Stelle nicht durch eingehende Nachrichten ausgelöst werden, sondern nur über "get <name> say TRIGGER". Dies kann dazu genutzt werden um einen Dialog aus FHEM heraus zu initiieren.

*commands: Kann einen einzelnen oder mehrere Befehle enthalten:
<pre>
"commands":
"single command"
"commands": [
"command 1",
"command 2",
"{perl command}"
]
</pre>

*message: Kann einen einzelnen oder mehrere Textte enthalten die mit einen Zeilenumbruch verbunden werden:
<pre>
"message": "text"
</pre>
<pre>
"message": [
"text 1",
"text 2",
"{return from perl command}"
]
</pre>

Bei mehrstufigen Dialogen wird diese Struktur ineinander verschachtelt angegeben.
Es werden Variablen und Platzhalter, welche unter dem Attribut evalSpecials definiert werden, ausgewertet.

=== Variablen ===
*$SELF: Eigenname des msgDialog
*$message: eingegangene Nachricht
*$recipient: Name des Dialogpartners

=== Attribute ===
*allowed: Liste mit allen RESIDENTS und ROOMMATE die für diesen Dialog berechtigt sind.
*disable: [0|1] Dialog ist aktiviert|deaktiviert.
*disabledForIntervals: HH:MM-HH:MM HH:MM-HH-MM ...
*evalSpecials: key1=value1 key2=value2 ...Leerzeichen getrennte Liste von Name=Wert Paaren. Wert kann Leerzeichen enthalten, falls es in "" oder {} eingeschlossen ist. Wert wird als perl-Ausdruck ausgewertet, falls es in {} eingeschlossen ist. In der DEF werden %Name% Zeichenketten durch den zugehörigen Wert ersetzt. Dieses Attribut ist als "msgDialog_evalSpecials" im msgConfig Gerät vorhanden. Wenn der selbe Name im msgConfig und msgDialog definiert wurde, wird der Wert aus msgDialog verwendet.
*msgCommand <command>: Befehl der zum Versenden einer Nachricht verwendet wird. Die Vorgabe ist "msg push \@$recipients $message" Dieses Attribut ist als "msgDialog_msgCommand" im msgConfig Gerät vorhanden.

=== set ===
*reset: Setzt den Dialog für alle Benutzer zurück.
*say [@<recipient1>[,<recipient2>,...]] <TRIGGER>[|<NEXT TRIGGER>|...]: Der Dialog wird für alle angegeben Empänger an der angegeben Stelle fortgeführt. Sind keine Empfänger angegeben wird der Dialog für alle unter dem Attribut allowed angegebenen Empfänger fortgeführt.
*updateAllowed: Aktualisiert die Auswahl für das Attribut allowed.

=== get ===
*trigger: Listet alle TRIGGER der ersten Ebene auf bei denen nicht setOnly angegeben ist.

=== READINGS ===
*$recipient_history: Durch | getrennte Liste von TRIGGER um den aktuellen Zustand des Dialogs zu sichern. Für jeden Dialogpartner wird ein Reading angelegt. Wenn der Dialog beendet ist wird das Reading zurückgesetzt.

== Beispiele ==

==== Programmierung der Waschmaschine ====
Das ist ein Beispiel zur Programmierung einer Waschmaschine wie auch oben im Video zu sehen:
<pre>
defmod Waschmaschine_Dialog msgDialog { "Waschmaschine": {\
"message": [\
"{return('(Zeitprogramm stoppen) ') if(ReadingsVal('%controlUnit%', 'controlMode', '') eq 'auto')}",\
"{return('(programmieren) ') if(ReadingsVal('%actor%', 'state', '') ne 'on')}",\
"{return('(einschalten) ') if(ReadingsVal('%actor%', 'state', '') ne 'on')}",\
"(Verlaufsdiagramm) ",\
"(abbrechen) ",\
"{return('Waschmaschine: ' . (ReadingsVal('%actor%', 'state', '') eq 'on' ? 'eingeschaltet' : 'ausgeschaltet'))}",\
"{return('Modus: ' . (ReadingsVal('%controlUnit%', 'controlMode', '') eq 'auto' ? 'Automatik' : 'Manuell (' . ReadingsVal('%controlUnit%', 'time', '') . ')'))}"\
],\
"Zeitprogramm stoppen": {\
"commands": "set %controlUnit% controlMode manual",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Das Zeitprogramm wurde gestoppt."\
]\
},\
"programmieren": {\
"message": [\
"(bestätigen|zurück|abbrechen) ",\
"( 00:00 | 00:15 | 00:30 | 00:45 ) ",\
"( 01:00 | 01:15 | 01:30 | 01:45 ) ",\
"( 02:00 | 02:15 | 02:30 | 02:45 ) ",\
"( 03:00 | 03:15 | 03:30 | 03:45 ) ",\
"( 04:00 | 04:15 | 04:30 | 04:45 ) ",\
"( 05:00 | 05:15 | 05:30 | 05:45 ) ",\
"( 06:00 | 06:15 | 06:30 | 06:45 ) ",\
"( 07:00 | 07:15 | 07:30 | 07:45 ) ",\
"( 08:00 | 08:15 | 08:30 | 08:45 ) ",\
"( 09:00 | 09:15 | 09:30 | 09:45 ) ",\
"( 10:00 | 10:15 | 10:30 | 10:45 ) ",\
"( 11:00 | 11:15 | 11:30 | 11:45 ) ",\
"( 12:00 | 12:15 | 12:30 | 12:45 ) ",\
"( 13:00 | 13:15 | 13:30 | 13:45 ) ",\
"( 14:00 | 14:15 | 14:30 | 14:45 ) ",\
"( 15:00 | 15:15 | 15:30 | 15:45 ) ",\
"( 16:00 | 16:15 | 16:30 | 16:45 ) ",\
"( 17:00 | 17:15 | 17:30 | 17:45 ) ",\
"( 18:00 | 18:15 | 18:30 | 18:45 ) ",\
"( 19:00 | 19:15 | 19:30 | 19:45 ) ",\
"( 20:00 | 20:15 | 20:30 | 20:45 ) ",\
"( 21:00 | 21:15 | 21:30 | 21:45 ) ",\
"( 22:00 | 22:15 | 22:30 | 22:45 ) ",\
"( 23:00 | 23:15 | 23:30 | 23:45 ) ",\
"Wann soll die Wäsche fertig sein?",\
"Bitte Uhrzeit in HH:MM angeben.",\
"Aktuell ist [%controlUnit%:time] Uhr eingestellt."\
],\
"Uhrzeit": {\
"match": " ?([0-1][0-9]|2[0-3]):[0-5][0-9] ?",\
"commands": [\
"set %controlUnit% time $message",\
"set $SELF say @$recipient Waschmaschine|programmieren|bestätigen"\
]\
},\
"bestätigen": {\
"commands": "set %controlUnit% controlMode auto",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Das Zeitprogramm wurde eingestellt.",\
"Die Wäsche wird voraussichtlich um [%controlUnit%:time] Uhr fertig sein.",\
"Bitte die Waschmaschine vorbereiten."\
]\
}\
},\
"einschalten": {\
"commands": [\
"set %controlUnit% controlMode manual",\
"set %actor% on"\
]\
},\
"Verlaufsdiagramm": {\
"commands": "set %TelegramBot% cmdSend {plotAsPng('%plot%')}",\
"message": "TelegramBot_MTYPE=queryInline (%me%) $message"\
}\
},\
"auto": {\
"setOnly": true,\
"commands": [\
"set %actor% on",\
"set %controlUnit% controlMode manual"\
],\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine wurde automatisch eingeschaltet."\
]\
},\
"manual": {\
"setOnly": true,\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine wurde manuell eingeschaltet."\
]\
},\
"done": {\
"setOnly": true,\
"commands": "set %actor% off",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine ist fertig."\
]\
}\
}
attr Waschmaschine_Dialog evalSpecials actor=HM_2C10D8_Sw\
controlUnit=Waschkeller_washer_controlUnit\
plot=Waschkeller_washer_SVG
</pre>

== TelegramBot ==

In Telegram gibt es die Möglichkeit die Art des Keyboards zu ändern. Links das normale Keyboard, rechts das Inline Keyboard.

[[Datei:76msgDialog menu.png|Normales Keyboard]] [[Datei:76msgDialog menu inline.PNG|Inline Keyboard]]

In diesem '''[https://youtu.be/oRDy2918mVI Video]''' wird Telegram mit einem Inline Keyboard verwendet.

Um eine Nachricht bei Telegram zu verändern, gibt es den Befehl "queryEditInline".
Dafür wird die MsgId von der Nachricht benötigt. Das erledigt ein notify, welches die msgId pro Peer abspeichert:

<pre>
defmod sentMsgIdByPeerId notify .+:sentMsgId.+ {\
return unless($TYPE eq "TelegramBot");;\
\
my $dev_hash = $defs{$NAME};;\
my $sentMsgId = ReadingsVal($NAME, "sentMsgId", "");;\
my $sentMsgPeerId = ReadingsVal($NAME, "sentMsgPeerId", "");;\
my ($contact) = devspec2array("TYPE=(ROOMMATE|GUEST):FILTER=msgContactPush=.*$sentMsgPeerId.*");;\
\
readingsSingleUpdate($dev_hash, "$contact\_sentMsgId", $sentMsgId, 1);;\
}
attr sentMsgIdByPeerId devStateIcon {ReadingsVal($name, "state", "inactive") eq "active" ? ".*:ios-on-blue:inactive" : ".*:ios-off:active"}
attr sentMsgIdByPeerId icon audio_mic
attr sentMsgIdByPeerId room msg
</pre>

Danach wird der Message-Befehl von
<pre>
set <TelegramBot> message
</pre>
auf
<pre>
set <TelegramBot> queryEditInline
</pre>
geändert. Dafür wird ein [[cmdalias]] verwendet:

<pre>
defmod message2queryEditInline cmdalias set .+ message (.|\n)+ AS {\
my ($NAME, $cmd, $message) = split(/[\s]+/, $EVENT, 3);;\
my $TYPE = InternalVal($NAME, "TYPE", "");;\
(my $recipient, $message) = ($message =~ m/(@\S+)? (.+)/s);;\
\
if($TYPE eq "TelegramBot" && $recipient){\
my ($contact) = devspec2array("TYPE=(ROOMMATE|GUEST):FILTER=msgContactPush=.*$recipient.*");;\
my $sentMsgId = ReadingsVal($NAME, "$contact\_sentMsgId", "");;\
\
if($sentMsgId ne ""){\
fhem("set $NAME queryEditInline $sentMsgId $recipient $message");;\
}\
else{\
fhem("set $NAME queryInline $recipient $message");;\
}\
}\
else{\
fhem("set $EVENT");;\
}\
}
attr message2queryEditInline room msg
</pre>

Um wieder zurück zum normalen Keyboard zu gelangen genügt es, das notify und den cmdAlias zu deaktivieren.
Das kann komfortabel über ein notify und einen dummy erledigt werden:
<pre>
defmod inline_normal.NOT notify inline_normal.DUM:.* {\
if ("$EVENT" =~ "on") {\
fhem "set sentMsgIdByPeerId active;; attr message2queryEditInline disable 0";;\
} \
elsif ("$EVENT" =~ "off") {\
fhem "set sentMsgIdByPeerId inactive;; attr message2queryEditInline disable 1";;\
}\
}
</pre>

Weitere Infos zum Thema Inline Keyboard sind in der Antwort #10 im Forum zu finden (siehe Link unten).

== JABBER ==
Hier wird die Verwendung mit Jabber beschrieben...

== WhatsApp ==
Hier wird die Verwendung mit yowsup/WhatsApp beschrieben...

== Links ==
* Thread über das Modul im {{Link2Forum|Topic=77297|LinkText=FHEM Forum}}

[[Kategorie:Hilfsmodul]]

MsgDialog

2017-10-31T09:03:47Z

Binford6000: /* TelegramBot: Inline Keyboard verwenden */

{{Infobox Modul
|ModPurpose=Dialoge für Sofortnachrichten über TelegramBot, Jabber und WhatsApp
|ModType=h
|ModForumArea=Frontends
|ModTechName=76_msgDialog.pm
|ModOwner={{Link2FU|4106|igami}}
}}

== Zielsetzung ==
Ein zentrale Anforderung an die Haus-Automation ist die Kommunikation mit den Anwendern. Fast jeder Anwender möchte über bestimmte Ereignisse informiert werden und Einstellungen vornehmen. FHEM bietet schon seit längerem die Unterstützung für verschiedene Messaging Dienste an.
Mit dem msgDialog Modul können vordefinierte Dialoge erstellt werden. Die Kommunikation erfolgt dabei über den [[msg]] Befehl welcher zurzeit die bidirektionale Kommunikation über [[TelegramBot]], [[Jabber]] und [[yowsup]] (WhatsApp) unterstützt. Eingehende Nachrichten werden einem ROMMATE oder GUEST zugeordnet. Darüber werden auch die Berechtigungen für die einzelnen Dialoge festgelegt.
Die grundlegende Bedienung wird in diesem '''[https://youtu.be/yiCOTeR1YVQ Video]''' am Beispiel von TelegramBot gezeigt.

== Konfiguration ==

=== Voraussetzungen ===
Für dieses Modul wird das Perl JSON Modul benötigt. Auf einem Debian-basierten System (z.B RaspberryPI o.ä.) kann man das mit dem folgenden Befehl installieren:
<pre>
sudo apt-get install libjson-perl
</pre>

=== Hinweis zu den Code Beispielen ===
Es handelt sich bei den Beispielen um eine Raw definition, siehe auch [[Import_von_Code_Snippets]]

=== msgConfig ===

Als erstes benötigt man ein definiertes msgConfig device:

<pre>
defmod myMsgConfig msgConfig
attr myMsgConfig msgDialog_evalSpecials me=<Aktivierungswort bzw. -Nachricht>
TelegramBot=<Name des TelegramBot-device>
attr myMsgConfig msgContactPush TelegramBot
attr myMsgConfig room msg
</pre>

Falls bereits vorhanden, müssen natürlich nur die fehlenden Attribute gesetzt werden.

=== ROOMMATE / GUEST ===

=== Define ===

Definition des metaDialogs:
Zur Auflistung aller berechtigten Dialoge dient - was sonst - ein Dialog!

<pre>
defmod meta_Dialog msgDialog {\
"%me%": {\
"match": "\/?(start|%me%)",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"{return('(' . join(') (', sort(split('\n', fhem('get TYPE=msgDialog:FILTER=NAME!=$SELF:FILTER=allowed=.*($recipient|everyone).* trigger')))) . ') ')}",\
"(abbrechen) ",\
"Ich kann folgendes für dich tun:"\
]\
},\
"abbrechen": {\
"match": "\/?abbrechen",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"(%me%) ",\
"Dialog abgebrochen."\
] \
},\
"beenden": {\
"match": "\/?beenden",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"(%me%) ",\
"Dialog beendet."\
]\
}\
}

attr meta_Dialog DbLogExclude .*
attr meta_Dialog allowed everyone
attr meta_Dialog room msg
</pre>

Aufgrund der Komplexität eines Dialogs mit JSON ist es am praktikabelsten, zunächst einen leeren Dialog zu definieren:
<pre>
define <name> msgDialog {}
</pre>

Anschließend kann die DEF in der Detail-Ansicht des Dialog-Device bearbeitet werden. Jeder Dialog basiert auf der folgenden Struktur von einfach bis komplex.

<pre>
{
"<TRIGGER>": {
"match": "<regex>",
"setOnly": (true|false),
"commands": "(fhem command|{perl code})",
"message": [
"{perl code}",
"text"
],
"<NEXT TRIGGER 1>": {
...
},
"<NEXT TRIGGER 2>": {
...
}
}
}
</pre>

Um den JSON-Teil der Dialoge zu testen, empfiehlt sich ein Besuch auf https://jsonlint.com/
Hier kann der selbst geschriebene JSON-Code validiert werden.

*TRIGGER: Kann ein beliebiger Text sein. Es wird geprüft ob die eingehende Nachricht damit übereinstimmt. Falls ja, wird der Dialog an dieser Stelle fortgesetzt.

*match: Wenn nicht nur genau eine Nachricht zugelassen werden soll, kann noch eine regex angegeben werden. Die regex muss auf die gesamte eingehnde Nachricht zutreffen.

*setOnly: Kann optional auf true oder false gestellt werden. In beiden fällen wird der TRIGGER dann nicht bei "get <name> trigger" zurück gegeben.
Wenn setOnly auf "true" gestellt wird, kann der Dialog an dieser Stelle nicht durch eingehende Nachrichten ausgelöst werden, sondern nur über "get <name> say TRIGGER". Dies kann dazu genutzt werden um einen Dialog aus FHEM heraus zu initiieren.

*commands: Kann einen einzelnen oder mehrere Befehle enthalten:
<pre>
"commands":
"single command"
"commands": [
"command 1",
"command 2",
"{perl command}"
]
</pre>

*message: Kann einen einzelnen oder mehrere Textte enthalten die mit einen Zeilenumbruch verbunden werden:
<pre>
"message": "text"
</pre>
<pre>
"message": [
"text 1",
"text 2",
"{return from perl command}"
]
</pre>

Bei mehrstufigen Dialogen wird diese Struktur ineinander verschachtelt angegeben.
Es werden Variablen und Platzhalter, welche unter dem Attribut evalSpecials definiert werden, ausgewertet.

=== Variablen ===
*$SELF: Eigenname des msgDialog
*$message: eingegangene Nachricht
*$recipient: Name des Dialogpartners

=== Attribute ===
*allowed: Liste mit allen RESIDENTS und ROOMMATE die für diesen Dialog berechtigt sind.
*disable: [0|1] Dialog ist aktiviert|deaktiviert.
*disabledForIntervals: HH:MM-HH:MM HH:MM-HH-MM ...
*evalSpecials: key1=value1 key2=value2 ...Leerzeichen getrennte Liste von Name=Wert Paaren. Wert kann Leerzeichen enthalten, falls es in "" oder {} eingeschlossen ist. Wert wird als perl-Ausdruck ausgewertet, falls es in {} eingeschlossen ist. In der DEF werden %Name% Zeichenketten durch den zugehörigen Wert ersetzt. Dieses Attribut ist als "msgDialog_evalSpecials" im msgConfig Gerät vorhanden. Wenn der selbe Name im msgConfig und msgDialog definiert wurde, wird der Wert aus msgDialog verwendet.
*msgCommand <command>: Befehl der zum Versenden einer Nachricht verwendet wird. Die Vorgabe ist "msg push \@$recipients $message" Dieses Attribut ist als "msgDialog_msgCommand" im msgConfig Gerät vorhanden.

=== set ===
*reset: Setzt den Dialog für alle Benutzer zurück.
*say [@<recipient1>[,<recipient2>,...]] <TRIGGER>[|<NEXT TRIGGER>|...]: Der Dialog wird für alle angegeben Empänger an der angegeben Stelle fortgeführt. Sind keine Empfänger angegeben wird der Dialog für alle unter dem Attribut allowed angegebenen Empfänger fortgeführt.
*updateAllowed: Aktualisiert die Auswahl für das Attribut allowed.

=== get ===
*trigger: Listet alle TRIGGER der ersten Ebene auf bei denen nicht setOnly angegeben ist.

=== READINGS ===
*$recipient_history: Durch | getrennte Liste von TRIGGER um den aktuellen Zustand des Dialogs zu sichern. Für jeden Dialogpartner wird ein Reading angelegt. Wenn der Dialog beendet ist wird das Reading zurückgesetzt.

== Beispiele ==

==== Programmierung der Waschmaschine ====
Das ist ein Beispiel zur Programmierung einer Waschmaschine wie auch oben im Video zu sehen:
<pre>
defmod Waschmaschine_Dialog msgDialog { "Waschmaschine": {\
"message": [\
"{return('(Zeitprogramm stoppen) ') if(ReadingsVal('%controlUnit%', 'controlMode', '') eq 'auto')}",\
"{return('(programmieren) ') if(ReadingsVal('%actor%', 'state', '') ne 'on')}",\
"{return('(einschalten) ') if(ReadingsVal('%actor%', 'state', '') ne 'on')}",\
"(Verlaufsdiagramm) ",\
"(abbrechen) ",\
"{return('Waschmaschine: ' . (ReadingsVal('%actor%', 'state', '') eq 'on' ? 'eingeschaltet' : 'ausgeschaltet'))}",\
"{return('Modus: ' . (ReadingsVal('%controlUnit%', 'controlMode', '') eq 'auto' ? 'Automatik' : 'Manuell (' . ReadingsVal('%controlUnit%', 'time', '') . ')'))}"\
],\
"Zeitprogramm stoppen": {\
"commands": "set %controlUnit% controlMode manual",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Das Zeitprogramm wurde gestoppt."\
]\
},\
"programmieren": {\
"message": [\
"(bestätigen|zurück|abbrechen) ",\
"( 00:00 | 00:15 | 00:30 | 00:45 ) ",\
"( 01:00 | 01:15 | 01:30 | 01:45 ) ",\
"( 02:00 | 02:15 | 02:30 | 02:45 ) ",\
"( 03:00 | 03:15 | 03:30 | 03:45 ) ",\
"( 04:00 | 04:15 | 04:30 | 04:45 ) ",\
"( 05:00 | 05:15 | 05:30 | 05:45 ) ",\
"( 06:00 | 06:15 | 06:30 | 06:45 ) ",\
"( 07:00 | 07:15 | 07:30 | 07:45 ) ",\
"( 08:00 | 08:15 | 08:30 | 08:45 ) ",\
"( 09:00 | 09:15 | 09:30 | 09:45 ) ",\
"( 10:00 | 10:15 | 10:30 | 10:45 ) ",\
"( 11:00 | 11:15 | 11:30 | 11:45 ) ",\
"( 12:00 | 12:15 | 12:30 | 12:45 ) ",\
"( 13:00 | 13:15 | 13:30 | 13:45 ) ",\
"( 14:00 | 14:15 | 14:30 | 14:45 ) ",\
"( 15:00 | 15:15 | 15:30 | 15:45 ) ",\
"( 16:00 | 16:15 | 16:30 | 16:45 ) ",\
"( 17:00 | 17:15 | 17:30 | 17:45 ) ",\
"( 18:00 | 18:15 | 18:30 | 18:45 ) ",\
"( 19:00 | 19:15 | 19:30 | 19:45 ) ",\
"( 20:00 | 20:15 | 20:30 | 20:45 ) ",\
"( 21:00 | 21:15 | 21:30 | 21:45 ) ",\
"( 22:00 | 22:15 | 22:30 | 22:45 ) ",\
"( 23:00 | 23:15 | 23:30 | 23:45 ) ",\
"Wann soll die Wäsche fertig sein?",\
"Bitte Uhrzeit in HH:MM angeben.",\
"Aktuell ist [%controlUnit%:time] Uhr eingestellt."\
],\
"Uhrzeit": {\
"match": " ?([0-1][0-9]|2[0-3]):[0-5][0-9] ?",\
"commands": [\
"set %controlUnit% time $message",\
"set $SELF say @$recipient Waschmaschine|programmieren|bestätigen"\
]\
},\
"bestätigen": {\
"commands": "set %controlUnit% controlMode auto",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Das Zeitprogramm wurde eingestellt.",\
"Die Wäsche wird voraussichtlich um [%controlUnit%:time] Uhr fertig sein.",\
"Bitte die Waschmaschine vorbereiten."\
]\
}\
},\
"einschalten": {\
"commands": [\
"set %controlUnit% controlMode manual",\
"set %actor% on"\
]\
},\
"Verlaufsdiagramm": {\
"commands": "set %TelegramBot% cmdSend {plotAsPng('%plot%')}",\
"message": "TelegramBot_MTYPE=queryInline (%me%) $message"\
}\
},\
"auto": {\
"setOnly": true,\
"commands": [\
"set %actor% on",\
"set %controlUnit% controlMode manual"\
],\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine wurde automatisch eingeschaltet."\
]\
},\
"manual": {\
"setOnly": true,\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine wurde manuell eingeschaltet."\
]\
},\
"done": {\
"setOnly": true,\
"commands": "set %actor% off",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine ist fertig."\
]\
}\
}
attr Waschmaschine_Dialog evalSpecials actor=HM_2C10D8_Sw\
controlUnit=Waschkeller_washer_controlUnit\
plot=Waschkeller_washer_SVG
</pre>

== TelegramBot ==

In Telegram gibt es die Möglichkeit die Art des Keyboards zu ändern. Links das normale Keyboard, rechts das Inline Keyboard.

[[Datei:76msgDialog menu.png|Normales Keyboard]] [[Datei:76msgDialog menu inline.PNG|Inline Keyboard]]

In diesem '''[https://youtu.be/oRDy2918mVI Video]''' wird Telegram mit einem Inline Keyboard verwendet.

Um eine Nachricht bei Telegram zu verändern, gibt es den Befehl "queryEditInline".
Dafür wird die MsgId von der Nachricht benötigt. Das erledigt ein notify, welches die msgId pro Peer abspeichert:

<pre>
defmod sentMsgIdByPeerId notify .+:sentMsgId.+ {\
return unless($TYPE eq "TelegramBot");;\
\
my $dev_hash = $defs{$NAME};;\
my $sentMsgId = ReadingsVal($NAME, "sentMsgId", "");;\
my $sentMsgPeerId = ReadingsVal($NAME, "sentMsgPeerId", "");;\
my ($contact) = devspec2array("TYPE=(ROOMMATE|GUEST):FILTER=msgContactPush=.*$sentMsgPeerId.*");;\
\
readingsSingleUpdate($dev_hash, "$contact\_sentMsgId", $sentMsgId, 1);;\
}
attr sentMsgIdByPeerId devStateIcon {ReadingsVal($name, "state", "inactive") eq "active" ? ".*:ios-on-blue:inactive" : ".*:ios-off:active"}
attr sentMsgIdByPeerId icon audio_mic
attr sentMsgIdByPeerId room msg
</pre>

Danach wird der Message-Befehl von
<pre>
set <TelegramBot> message
</pre>
auf
<pre>
set <TelegramBot> queryEditInline
</pre>
geändert. Dafür wird ein [[cmdalias]] verwendet:

<pre>
defmod message2queryEditInline cmdalias set .+ message (.|\n)+ AS {\
my ($NAME, $cmd, $message) = split(/[\s]+/, $EVENT, 3);;\
my $TYPE = InternalVal($NAME, "TYPE", "");;\
(my $recipient, $message) = ($message =~ m/(@\S+)? (.+)/s);;\
\
if($TYPE eq "TelegramBot" && $recipient){\
my ($contact) = devspec2array("TYPE=(ROOMMATE|GUEST):FILTER=msgContactPush=.*$recipient.*");;\
my $sentMsgId = ReadingsVal($NAME, "$contact\_sentMsgId", "");;\
\
if($sentMsgId ne ""){\
fhem("set $NAME queryEditInline $sentMsgId $recipient $message");;\
}\
else{\
fhem("set $NAME queryInline $recipient $message");;\
}\
}\
else{\
fhem("set $EVENT");;\
}\
}
attr message2queryEditInline room msg
</pre>

Um wieder zurück zum normalen Keyboard zu gelangen genügt es, das notify und den cmdAlias zu deaktivieren.
Das kann komfortabel über ein notify und einen dummy erledigt werden:
<pre>
defmod inline_normal.NOT notify inline_normal.DUM:.* {\
if ("$EVENT" =~ "on") {\
fhem "set sentMsgIdByPeerId active;; attr message2queryEditInline disable 0";;\
} \
elsif ("$EVENT" =~ "off") {\
fhem "set sentMsgIdByPeerId inactive;; attr message2queryEditInline disable 1";;\
}\
}
</pre>

Weitere Infos zum Thema Inline Keyboard sind in der Antwort #10 im Forum zu finden (siehe Link unten).

== JABBER ==
Hier wird die Verwendung mit Jabber beschrieben...

== WhatsApp ==
Hier wird die Verwendung mit yowsup/WhatsApp beschrieben...

== Links ==
* Thread über das Modul im {{Link2Forum|Topic=77297|LinkText=FHEM Forum}}

[[Kategorie:Hilfsmodul]]

MsgDialog

2017-10-31T09:02:49Z

Binford6000: /* JABBER */

{{Infobox Modul
|ModPurpose=Dialoge für Sofortnachrichten über TelegramBot, Jabber und WhatsApp
|ModType=h
|ModForumArea=Frontends
|ModTechName=76_msgDialog.pm
|ModOwner={{Link2FU|4106|igami}}
}}

== Zielsetzung ==
Ein zentrale Anforderung an die Haus-Automation ist die Kommunikation mit den Anwendern. Fast jeder Anwender möchte über bestimmte Ereignisse informiert werden und Einstellungen vornehmen. FHEM bietet schon seit längerem die Unterstützung für verschiedene Messaging Dienste an.
Mit dem msgDialog Modul können vordefinierte Dialoge erstellt werden. Die Kommunikation erfolgt dabei über den [[msg]] Befehl welcher zurzeit die bidirektionale Kommunikation über [[TelegramBot]], [[Jabber]] und [[yowsup]] (WhatsApp) unterstützt. Eingehende Nachrichten werden einem ROMMATE oder GUEST zugeordnet. Darüber werden auch die Berechtigungen für die einzelnen Dialoge festgelegt.
Die grundlegende Bedienung wird in diesem '''[https://youtu.be/yiCOTeR1YVQ Video]''' am Beispiel von TelegramBot gezeigt.

== Konfiguration ==

=== Voraussetzungen ===
Für dieses Modul wird das Perl JSON Modul benötigt. Auf einem Debian-basierten System (z.B RaspberryPI o.ä.) kann man das mit dem folgenden Befehl installieren:
<pre>
sudo apt-get install libjson-perl
</pre>

=== Hinweis zu den Code Beispielen ===
Es handelt sich bei den Beispielen um eine Raw definition, siehe auch [[Import_von_Code_Snippets]]

=== msgConfig ===

Als erstes benötigt man ein definiertes msgConfig device:

<pre>
defmod myMsgConfig msgConfig
attr myMsgConfig msgDialog_evalSpecials me=<Aktivierungswort bzw. -Nachricht>
TelegramBot=<Name des TelegramBot-device>
attr myMsgConfig msgContactPush TelegramBot
attr myMsgConfig room msg
</pre>

Falls bereits vorhanden, müssen natürlich nur die fehlenden Attribute gesetzt werden.

=== ROOMMATE / GUEST ===

=== Define ===

Definition des metaDialogs:
Zur Auflistung aller berechtigten Dialoge dient - was sonst - ein Dialog!

<pre>
defmod meta_Dialog msgDialog {\
"%me%": {\
"match": "\/?(start|%me%)",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"{return('(' . join(') (', sort(split('\n', fhem('get TYPE=msgDialog:FILTER=NAME!=$SELF:FILTER=allowed=.*($recipient|everyone).* trigger')))) . ') ')}",\
"(abbrechen) ",\
"Ich kann folgendes für dich tun:"\
]\
},\
"abbrechen": {\
"match": "\/?abbrechen",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"(%me%) ",\
"Dialog abgebrochen."\
] \
},\
"beenden": {\
"match": "\/?beenden",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"(%me%) ",\
"Dialog beendet."\
]\
}\
}

attr meta_Dialog DbLogExclude .*
attr meta_Dialog allowed everyone
attr meta_Dialog room msg
</pre>

Aufgrund der Komplexität eines Dialogs mit JSON ist es am praktikabelsten, zunächst einen leeren Dialog zu definieren:
<pre>
define <name> msgDialog {}
</pre>

Anschließend kann die DEF in der Detail-Ansicht des Dialog-Device bearbeitet werden. Jeder Dialog basiert auf der folgenden Struktur von einfach bis komplex.

<pre>
{
"<TRIGGER>": {
"match": "<regex>",
"setOnly": (true|false),
"commands": "(fhem command|{perl code})",
"message": [
"{perl code}",
"text"
],
"<NEXT TRIGGER 1>": {
...
},
"<NEXT TRIGGER 2>": {
...
}
}
}
</pre>

Um den JSON-Teil der Dialoge zu testen, empfiehlt sich ein Besuch auf https://jsonlint.com/
Hier kann der selbst geschriebene JSON-Code validiert werden.

*TRIGGER: Kann ein beliebiger Text sein. Es wird geprüft ob die eingehende Nachricht damit übereinstimmt. Falls ja, wird der Dialog an dieser Stelle fortgesetzt.

*match: Wenn nicht nur genau eine Nachricht zugelassen werden soll, kann noch eine regex angegeben werden. Die regex muss auf die gesamte eingehnde Nachricht zutreffen.

*setOnly: Kann optional auf true oder false gestellt werden. In beiden fällen wird der TRIGGER dann nicht bei "get <name> trigger" zurück gegeben.
Wenn setOnly auf "true" gestellt wird, kann der Dialog an dieser Stelle nicht durch eingehende Nachrichten ausgelöst werden, sondern nur über "get <name> say TRIGGER". Dies kann dazu genutzt werden um einen Dialog aus FHEM heraus zu initiieren.

*commands: Kann einen einzelnen oder mehrere Befehle enthalten:
<pre>
"commands":
"single command"
"commands": [
"command 1",
"command 2",
"{perl command}"
]
</pre>

*message: Kann einen einzelnen oder mehrere Textte enthalten die mit einen Zeilenumbruch verbunden werden:
<pre>
"message": "text"
</pre>
<pre>
"message": [
"text 1",
"text 2",
"{return from perl command}"
]
</pre>

Bei mehrstufigen Dialogen wird diese Struktur ineinander verschachtelt angegeben.
Es werden Variablen und Platzhalter, welche unter dem Attribut evalSpecials definiert werden, ausgewertet.

=== Variablen ===
*$SELF: Eigenname des msgDialog
*$message: eingegangene Nachricht
*$recipient: Name des Dialogpartners

=== Attribute ===
*allowed: Liste mit allen RESIDENTS und ROOMMATE die für diesen Dialog berechtigt sind.
*disable: [0|1] Dialog ist aktiviert|deaktiviert.
*disabledForIntervals: HH:MM-HH:MM HH:MM-HH-MM ...
*evalSpecials: key1=value1 key2=value2 ...Leerzeichen getrennte Liste von Name=Wert Paaren. Wert kann Leerzeichen enthalten, falls es in "" oder {} eingeschlossen ist. Wert wird als perl-Ausdruck ausgewertet, falls es in {} eingeschlossen ist. In der DEF werden %Name% Zeichenketten durch den zugehörigen Wert ersetzt. Dieses Attribut ist als "msgDialog_evalSpecials" im msgConfig Gerät vorhanden. Wenn der selbe Name im msgConfig und msgDialog definiert wurde, wird der Wert aus msgDialog verwendet.
*msgCommand <command>: Befehl der zum Versenden einer Nachricht verwendet wird. Die Vorgabe ist "msg push \@$recipients $message" Dieses Attribut ist als "msgDialog_msgCommand" im msgConfig Gerät vorhanden.

=== set ===
*reset: Setzt den Dialog für alle Benutzer zurück.
*say [@<recipient1>[,<recipient2>,...]] <TRIGGER>[|<NEXT TRIGGER>|...]: Der Dialog wird für alle angegeben Empänger an der angegeben Stelle fortgeführt. Sind keine Empfänger angegeben wird der Dialog für alle unter dem Attribut allowed angegebenen Empfänger fortgeführt.
*updateAllowed: Aktualisiert die Auswahl für das Attribut allowed.

=== get ===
*trigger: Listet alle TRIGGER der ersten Ebene auf bei denen nicht setOnly angegeben ist.

=== READINGS ===
*$recipient_history: Durch | getrennte Liste von TRIGGER um den aktuellen Zustand des Dialogs zu sichern. Für jeden Dialogpartner wird ein Reading angelegt. Wenn der Dialog beendet ist wird das Reading zurückgesetzt.

== Beispiele ==

==== Programmierung der Waschmaschine ====
Das ist ein Beispiel zur Programmierung einer Waschmaschine wie auch oben im Video zu sehen:
<pre>
defmod Waschmaschine_Dialog msgDialog { "Waschmaschine": {\
"message": [\
"{return('(Zeitprogramm stoppen) ') if(ReadingsVal('%controlUnit%', 'controlMode', '') eq 'auto')}",\
"{return('(programmieren) ') if(ReadingsVal('%actor%', 'state', '') ne 'on')}",\
"{return('(einschalten) ') if(ReadingsVal('%actor%', 'state', '') ne 'on')}",\
"(Verlaufsdiagramm) ",\
"(abbrechen) ",\
"{return('Waschmaschine: ' . (ReadingsVal('%actor%', 'state', '') eq 'on' ? 'eingeschaltet' : 'ausgeschaltet'))}",\
"{return('Modus: ' . (ReadingsVal('%controlUnit%', 'controlMode', '') eq 'auto' ? 'Automatik' : 'Manuell (' . ReadingsVal('%controlUnit%', 'time', '') . ')'))}"\
],\
"Zeitprogramm stoppen": {\
"commands": "set %controlUnit% controlMode manual",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Das Zeitprogramm wurde gestoppt."\
]\
},\
"programmieren": {\
"message": [\
"(bestätigen|zurück|abbrechen) ",\
"( 00:00 | 00:15 | 00:30 | 00:45 ) ",\
"( 01:00 | 01:15 | 01:30 | 01:45 ) ",\
"( 02:00 | 02:15 | 02:30 | 02:45 ) ",\
"( 03:00 | 03:15 | 03:30 | 03:45 ) ",\
"( 04:00 | 04:15 | 04:30 | 04:45 ) ",\
"( 05:00 | 05:15 | 05:30 | 05:45 ) ",\
"( 06:00 | 06:15 | 06:30 | 06:45 ) ",\
"( 07:00 | 07:15 | 07:30 | 07:45 ) ",\
"( 08:00 | 08:15 | 08:30 | 08:45 ) ",\
"( 09:00 | 09:15 | 09:30 | 09:45 ) ",\
"( 10:00 | 10:15 | 10:30 | 10:45 ) ",\
"( 11:00 | 11:15 | 11:30 | 11:45 ) ",\
"( 12:00 | 12:15 | 12:30 | 12:45 ) ",\
"( 13:00 | 13:15 | 13:30 | 13:45 ) ",\
"( 14:00 | 14:15 | 14:30 | 14:45 ) ",\
"( 15:00 | 15:15 | 15:30 | 15:45 ) ",\
"( 16:00 | 16:15 | 16:30 | 16:45 ) ",\
"( 17:00 | 17:15 | 17:30 | 17:45 ) ",\
"( 18:00 | 18:15 | 18:30 | 18:45 ) ",\
"( 19:00 | 19:15 | 19:30 | 19:45 ) ",\
"( 20:00 | 20:15 | 20:30 | 20:45 ) ",\
"( 21:00 | 21:15 | 21:30 | 21:45 ) ",\
"( 22:00 | 22:15 | 22:30 | 22:45 ) ",\
"( 23:00 | 23:15 | 23:30 | 23:45 ) ",\
"Wann soll die Wäsche fertig sein?",\
"Bitte Uhrzeit in HH:MM angeben.",\
"Aktuell ist [%controlUnit%:time] Uhr eingestellt."\
],\
"Uhrzeit": {\
"match": " ?([0-1][0-9]|2[0-3]):[0-5][0-9] ?",\
"commands": [\
"set %controlUnit% time $message",\
"set $SELF say @$recipient Waschmaschine|programmieren|bestätigen"\
]\
},\
"bestätigen": {\
"commands": "set %controlUnit% controlMode auto",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Das Zeitprogramm wurde eingestellt.",\
"Die Wäsche wird voraussichtlich um [%controlUnit%:time] Uhr fertig sein.",\
"Bitte die Waschmaschine vorbereiten."\
]\
}\
},\
"einschalten": {\
"commands": [\
"set %controlUnit% controlMode manual",\
"set %actor% on"\
]\
},\
"Verlaufsdiagramm": {\
"commands": "set %TelegramBot% cmdSend {plotAsPng('%plot%')}",\
"message": "TelegramBot_MTYPE=queryInline (%me%) $message"\
}\
},\
"auto": {\
"setOnly": true,\
"commands": [\
"set %actor% on",\
"set %controlUnit% controlMode manual"\
],\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine wurde automatisch eingeschaltet."\
]\
},\
"manual": {\
"setOnly": true,\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine wurde manuell eingeschaltet."\
]\
},\
"done": {\
"setOnly": true,\
"commands": "set %actor% off",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine ist fertig."\
]\
}\
}
attr Waschmaschine_Dialog evalSpecials actor=HM_2C10D8_Sw\
controlUnit=Waschkeller_washer_controlUnit\
plot=Waschkeller_washer_SVG
</pre>

== TelegramBot: Inline Keyboard verwenden==

In Telegram gibt es die Möglichkeit die Art des Keyboards zu ändern. Links das normale Keyboard, rechts das Inline Keyboard.

[[Datei:76msgDialog menu.png|Normales Keyboard]] [[Datei:76msgDialog menu inline.PNG|Inline Keyboard]]

In diesem '''[https://youtu.be/oRDy2918mVI Video]''' wird Telegram mit einem Inline Keyboard verwendet.

Um eine Nachricht bei Telegram zu verändern, gibt es den Befehl "queryEditInline".
Dafür wird die MsgId von der Nachricht benötigt. Das erledigt ein notify, welches die msgId pro Peer abspeichert:

<pre>
defmod sentMsgIdByPeerId notify .+:sentMsgId.+ {\
return unless($TYPE eq "TelegramBot");;\
\
my $dev_hash = $defs{$NAME};;\
my $sentMsgId = ReadingsVal($NAME, "sentMsgId", "");;\
my $sentMsgPeerId = ReadingsVal($NAME, "sentMsgPeerId", "");;\
my ($contact) = devspec2array("TYPE=(ROOMMATE|GUEST):FILTER=msgContactPush=.*$sentMsgPeerId.*");;\
\
readingsSingleUpdate($dev_hash, "$contact\_sentMsgId", $sentMsgId, 1);;\
}
attr sentMsgIdByPeerId devStateIcon {ReadingsVal($name, "state", "inactive") eq "active" ? ".*:ios-on-blue:inactive" : ".*:ios-off:active"}
attr sentMsgIdByPeerId icon audio_mic
attr sentMsgIdByPeerId room msg
</pre>

Danach wird der Message-Befehl von
<pre>
set <TelegramBot> message
</pre>
auf
<pre>
set <TelegramBot> queryEditInline
</pre>
geändert. Dafür wird ein [[cmdalias]] verwendet:

<pre>
defmod message2queryEditInline cmdalias set .+ message (.|\n)+ AS {\
my ($NAME, $cmd, $message) = split(/[\s]+/, $EVENT, 3);;\
my $TYPE = InternalVal($NAME, "TYPE", "");;\
(my $recipient, $message) = ($message =~ m/(@\S+)? (.+)/s);;\
\
if($TYPE eq "TelegramBot" && $recipient){\
my ($contact) = devspec2array("TYPE=(ROOMMATE|GUEST):FILTER=msgContactPush=.*$recipient.*");;\
my $sentMsgId = ReadingsVal($NAME, "$contact\_sentMsgId", "");;\
\
if($sentMsgId ne ""){\
fhem("set $NAME queryEditInline $sentMsgId $recipient $message");;\
}\
else{\
fhem("set $NAME queryInline $recipient $message");;\
}\
}\
else{\
fhem("set $EVENT");;\
}\
}
attr message2queryEditInline room msg
</pre>

Um wieder zurück zum normalen Keyboard zu gelangen genügt es, das notify und den cmdAlias zu deaktivieren.
Das kann komfortabel über ein notify und einen dummy erledigt werden:
<pre>
defmod inline_normal.NOT notify inline_normal.DUM:.* {\
if ("$EVENT" =~ "on") {\
fhem "set sentMsgIdByPeerId active;; attr message2queryEditInline disable 0";;\
} \
elsif ("$EVENT" =~ "off") {\
fhem "set sentMsgIdByPeerId inactive;; attr message2queryEditInline disable 1";;\
}\
}
</pre>

Weitere Infos zum Thema Inline Keyboard sind in der Antwort #10 im Forum zu finden (siehe Link unten).

== JABBER ==
Hier wird die Verwendung mit Jabber beschrieben...

== WhatsApp ==
Hier wird die Verwendung mit yowsup/WhatsApp beschrieben...

== Links ==
* Thread über das Modul im {{Link2Forum|Topic=77297|LinkText=FHEM Forum}}

[[Kategorie:Hilfsmodul]]

MsgDialog

2017-10-31T09:02:32Z

Binford6000: /* WhatsApp */

{{Infobox Modul
|ModPurpose=Dialoge für Sofortnachrichten über TelegramBot, Jabber und WhatsApp
|ModType=h
|ModForumArea=Frontends
|ModTechName=76_msgDialog.pm
|ModOwner={{Link2FU|4106|igami}}
}}

== Zielsetzung ==
Ein zentrale Anforderung an die Haus-Automation ist die Kommunikation mit den Anwendern. Fast jeder Anwender möchte über bestimmte Ereignisse informiert werden und Einstellungen vornehmen. FHEM bietet schon seit längerem die Unterstützung für verschiedene Messaging Dienste an.
Mit dem msgDialog Modul können vordefinierte Dialoge erstellt werden. Die Kommunikation erfolgt dabei über den [[msg]] Befehl welcher zurzeit die bidirektionale Kommunikation über [[TelegramBot]], [[Jabber]] und [[yowsup]] (WhatsApp) unterstützt. Eingehende Nachrichten werden einem ROMMATE oder GUEST zugeordnet. Darüber werden auch die Berechtigungen für die einzelnen Dialoge festgelegt.
Die grundlegende Bedienung wird in diesem '''[https://youtu.be/yiCOTeR1YVQ Video]''' am Beispiel von TelegramBot gezeigt.

== Konfiguration ==

=== Voraussetzungen ===
Für dieses Modul wird das Perl JSON Modul benötigt. Auf einem Debian-basierten System (z.B RaspberryPI o.ä.) kann man das mit dem folgenden Befehl installieren:
<pre>
sudo apt-get install libjson-perl
</pre>

=== Hinweis zu den Code Beispielen ===
Es handelt sich bei den Beispielen um eine Raw definition, siehe auch [[Import_von_Code_Snippets]]

=== msgConfig ===

Als erstes benötigt man ein definiertes msgConfig device:

<pre>
defmod myMsgConfig msgConfig
attr myMsgConfig msgDialog_evalSpecials me=<Aktivierungswort bzw. -Nachricht>
TelegramBot=<Name des TelegramBot-device>
attr myMsgConfig msgContactPush TelegramBot
attr myMsgConfig room msg
</pre>

Falls bereits vorhanden, müssen natürlich nur die fehlenden Attribute gesetzt werden.

=== ROOMMATE / GUEST ===

=== Define ===

Definition des metaDialogs:
Zur Auflistung aller berechtigten Dialoge dient - was sonst - ein Dialog!

<pre>
defmod meta_Dialog msgDialog {\
"%me%": {\
"match": "\/?(start|%me%)",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"{return('(' . join(') (', sort(split('\n', fhem('get TYPE=msgDialog:FILTER=NAME!=$SELF:FILTER=allowed=.*($recipient|everyone).* trigger')))) . ') ')}",\
"(abbrechen) ",\
"Ich kann folgendes für dich tun:"\
]\
},\
"abbrechen": {\
"match": "\/?abbrechen",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"(%me%) ",\
"Dialog abgebrochen."\
] \
},\
"beenden": {\
"match": "\/?beenden",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"(%me%) ",\
"Dialog beendet."\
]\
}\
}

attr meta_Dialog DbLogExclude .*
attr meta_Dialog allowed everyone
attr meta_Dialog room msg
</pre>

Aufgrund der Komplexität eines Dialogs mit JSON ist es am praktikabelsten, zunächst einen leeren Dialog zu definieren:
<pre>
define <name> msgDialog {}
</pre>

Anschließend kann die DEF in der Detail-Ansicht des Dialog-Device bearbeitet werden. Jeder Dialog basiert auf der folgenden Struktur von einfach bis komplex.

<pre>
{
"<TRIGGER>": {
"match": "<regex>",
"setOnly": (true|false),
"commands": "(fhem command|{perl code})",
"message": [
"{perl code}",
"text"
],
"<NEXT TRIGGER 1>": {
...
},
"<NEXT TRIGGER 2>": {
...
}
}
}
</pre>

Um den JSON-Teil der Dialoge zu testen, empfiehlt sich ein Besuch auf https://jsonlint.com/
Hier kann der selbst geschriebene JSON-Code validiert werden.

*TRIGGER: Kann ein beliebiger Text sein. Es wird geprüft ob die eingehende Nachricht damit übereinstimmt. Falls ja, wird der Dialog an dieser Stelle fortgesetzt.

*match: Wenn nicht nur genau eine Nachricht zugelassen werden soll, kann noch eine regex angegeben werden. Die regex muss auf die gesamte eingehnde Nachricht zutreffen.

*setOnly: Kann optional auf true oder false gestellt werden. In beiden fällen wird der TRIGGER dann nicht bei "get <name> trigger" zurück gegeben.
Wenn setOnly auf "true" gestellt wird, kann der Dialog an dieser Stelle nicht durch eingehende Nachrichten ausgelöst werden, sondern nur über "get <name> say TRIGGER". Dies kann dazu genutzt werden um einen Dialog aus FHEM heraus zu initiieren.

*commands: Kann einen einzelnen oder mehrere Befehle enthalten:
<pre>
"commands":
"single command"
"commands": [
"command 1",
"command 2",
"{perl command}"
]
</pre>

*message: Kann einen einzelnen oder mehrere Textte enthalten die mit einen Zeilenumbruch verbunden werden:
<pre>
"message": "text"
</pre>
<pre>
"message": [
"text 1",
"text 2",
"{return from perl command}"
]
</pre>

Bei mehrstufigen Dialogen wird diese Struktur ineinander verschachtelt angegeben.
Es werden Variablen und Platzhalter, welche unter dem Attribut evalSpecials definiert werden, ausgewertet.

=== Variablen ===
*$SELF: Eigenname des msgDialog
*$message: eingegangene Nachricht
*$recipient: Name des Dialogpartners

=== Attribute ===
*allowed: Liste mit allen RESIDENTS und ROOMMATE die für diesen Dialog berechtigt sind.
*disable: [0|1] Dialog ist aktiviert|deaktiviert.
*disabledForIntervals: HH:MM-HH:MM HH:MM-HH-MM ...
*evalSpecials: key1=value1 key2=value2 ...Leerzeichen getrennte Liste von Name=Wert Paaren. Wert kann Leerzeichen enthalten, falls es in "" oder {} eingeschlossen ist. Wert wird als perl-Ausdruck ausgewertet, falls es in {} eingeschlossen ist. In der DEF werden %Name% Zeichenketten durch den zugehörigen Wert ersetzt. Dieses Attribut ist als "msgDialog_evalSpecials" im msgConfig Gerät vorhanden. Wenn der selbe Name im msgConfig und msgDialog definiert wurde, wird der Wert aus msgDialog verwendet.
*msgCommand <command>: Befehl der zum Versenden einer Nachricht verwendet wird. Die Vorgabe ist "msg push \@$recipients $message" Dieses Attribut ist als "msgDialog_msgCommand" im msgConfig Gerät vorhanden.

=== set ===
*reset: Setzt den Dialog für alle Benutzer zurück.
*say [@<recipient1>[,<recipient2>,...]] <TRIGGER>[|<NEXT TRIGGER>|...]: Der Dialog wird für alle angegeben Empänger an der angegeben Stelle fortgeführt. Sind keine Empfänger angegeben wird der Dialog für alle unter dem Attribut allowed angegebenen Empfänger fortgeführt.
*updateAllowed: Aktualisiert die Auswahl für das Attribut allowed.

=== get ===
*trigger: Listet alle TRIGGER der ersten Ebene auf bei denen nicht setOnly angegeben ist.

=== READINGS ===
*$recipient_history: Durch | getrennte Liste von TRIGGER um den aktuellen Zustand des Dialogs zu sichern. Für jeden Dialogpartner wird ein Reading angelegt. Wenn der Dialog beendet ist wird das Reading zurückgesetzt.

== Beispiele ==

==== Programmierung der Waschmaschine ====
Das ist ein Beispiel zur Programmierung einer Waschmaschine wie auch oben im Video zu sehen:
<pre>
defmod Waschmaschine_Dialog msgDialog { "Waschmaschine": {\
"message": [\
"{return('(Zeitprogramm stoppen) ') if(ReadingsVal('%controlUnit%', 'controlMode', '') eq 'auto')}",\
"{return('(programmieren) ') if(ReadingsVal('%actor%', 'state', '') ne 'on')}",\
"{return('(einschalten) ') if(ReadingsVal('%actor%', 'state', '') ne 'on')}",\
"(Verlaufsdiagramm) ",\
"(abbrechen) ",\
"{return('Waschmaschine: ' . (ReadingsVal('%actor%', 'state', '') eq 'on' ? 'eingeschaltet' : 'ausgeschaltet'))}",\
"{return('Modus: ' . (ReadingsVal('%controlUnit%', 'controlMode', '') eq 'auto' ? 'Automatik' : 'Manuell (' . ReadingsVal('%controlUnit%', 'time', '') . ')'))}"\
],\
"Zeitprogramm stoppen": {\
"commands": "set %controlUnit% controlMode manual",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Das Zeitprogramm wurde gestoppt."\
]\
},\
"programmieren": {\
"message": [\
"(bestätigen|zurück|abbrechen) ",\
"( 00:00 | 00:15 | 00:30 | 00:45 ) ",\
"( 01:00 | 01:15 | 01:30 | 01:45 ) ",\
"( 02:00 | 02:15 | 02:30 | 02:45 ) ",\
"( 03:00 | 03:15 | 03:30 | 03:45 ) ",\
"( 04:00 | 04:15 | 04:30 | 04:45 ) ",\
"( 05:00 | 05:15 | 05:30 | 05:45 ) ",\
"( 06:00 | 06:15 | 06:30 | 06:45 ) ",\
"( 07:00 | 07:15 | 07:30 | 07:45 ) ",\
"( 08:00 | 08:15 | 08:30 | 08:45 ) ",\
"( 09:00 | 09:15 | 09:30 | 09:45 ) ",\
"( 10:00 | 10:15 | 10:30 | 10:45 ) ",\
"( 11:00 | 11:15 | 11:30 | 11:45 ) ",\
"( 12:00 | 12:15 | 12:30 | 12:45 ) ",\
"( 13:00 | 13:15 | 13:30 | 13:45 ) ",\
"( 14:00 | 14:15 | 14:30 | 14:45 ) ",\
"( 15:00 | 15:15 | 15:30 | 15:45 ) ",\
"( 16:00 | 16:15 | 16:30 | 16:45 ) ",\
"( 17:00 | 17:15 | 17:30 | 17:45 ) ",\
"( 18:00 | 18:15 | 18:30 | 18:45 ) ",\
"( 19:00 | 19:15 | 19:30 | 19:45 ) ",\
"( 20:00 | 20:15 | 20:30 | 20:45 ) ",\
"( 21:00 | 21:15 | 21:30 | 21:45 ) ",\
"( 22:00 | 22:15 | 22:30 | 22:45 ) ",\
"( 23:00 | 23:15 | 23:30 | 23:45 ) ",\
"Wann soll die Wäsche fertig sein?",\
"Bitte Uhrzeit in HH:MM angeben.",\
"Aktuell ist [%controlUnit%:time] Uhr eingestellt."\
],\
"Uhrzeit": {\
"match": " ?([0-1][0-9]|2[0-3]):[0-5][0-9] ?",\
"commands": [\
"set %controlUnit% time $message",\
"set $SELF say @$recipient Waschmaschine|programmieren|bestätigen"\
]\
},\
"bestätigen": {\
"commands": "set %controlUnit% controlMode auto",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Das Zeitprogramm wurde eingestellt.",\
"Die Wäsche wird voraussichtlich um [%controlUnit%:time] Uhr fertig sein.",\
"Bitte die Waschmaschine vorbereiten."\
]\
}\
},\
"einschalten": {\
"commands": [\
"set %controlUnit% controlMode manual",\
"set %actor% on"\
]\
},\
"Verlaufsdiagramm": {\
"commands": "set %TelegramBot% cmdSend {plotAsPng('%plot%')}",\
"message": "TelegramBot_MTYPE=queryInline (%me%) $message"\
}\
},\
"auto": {\
"setOnly": true,\
"commands": [\
"set %actor% on",\
"set %controlUnit% controlMode manual"\
],\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine wurde automatisch eingeschaltet."\
]\
},\
"manual": {\
"setOnly": true,\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine wurde manuell eingeschaltet."\
]\
},\
"done": {\
"setOnly": true,\
"commands": "set %actor% off",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine ist fertig."\
]\
}\
}
attr Waschmaschine_Dialog evalSpecials actor=HM_2C10D8_Sw\
controlUnit=Waschkeller_washer_controlUnit\
plot=Waschkeller_washer_SVG
</pre>

== TelegramBot: Inline Keyboard verwenden==

In Telegram gibt es die Möglichkeit die Art des Keyboards zu ändern. Links das normale Keyboard, rechts das Inline Keyboard.

[[Datei:76msgDialog menu.png|Normales Keyboard]] [[Datei:76msgDialog menu inline.PNG|Inline Keyboard]]

In diesem '''[https://youtu.be/oRDy2918mVI Video]''' wird Telegram mit einem Inline Keyboard verwendet.

Um eine Nachricht bei Telegram zu verändern, gibt es den Befehl "queryEditInline".
Dafür wird die MsgId von der Nachricht benötigt. Das erledigt ein notify, welches die msgId pro Peer abspeichert:

<pre>
defmod sentMsgIdByPeerId notify .+:sentMsgId.+ {\
return unless($TYPE eq "TelegramBot");;\
\
my $dev_hash = $defs{$NAME};;\
my $sentMsgId = ReadingsVal($NAME, "sentMsgId", "");;\
my $sentMsgPeerId = ReadingsVal($NAME, "sentMsgPeerId", "");;\
my ($contact) = devspec2array("TYPE=(ROOMMATE|GUEST):FILTER=msgContactPush=.*$sentMsgPeerId.*");;\
\
readingsSingleUpdate($dev_hash, "$contact\_sentMsgId", $sentMsgId, 1);;\
}
attr sentMsgIdByPeerId devStateIcon {ReadingsVal($name, "state", "inactive") eq "active" ? ".*:ios-on-blue:inactive" : ".*:ios-off:active"}
attr sentMsgIdByPeerId icon audio_mic
attr sentMsgIdByPeerId room msg
</pre>

Danach wird der Message-Befehl von
<pre>
set <TelegramBot> message
</pre>
auf
<pre>
set <TelegramBot> queryEditInline
</pre>
geändert. Dafür wird ein [[cmdalias]] verwendet:

<pre>
defmod message2queryEditInline cmdalias set .+ message (.|\n)+ AS {\
my ($NAME, $cmd, $message) = split(/[\s]+/, $EVENT, 3);;\
my $TYPE = InternalVal($NAME, "TYPE", "");;\
(my $recipient, $message) = ($message =~ m/(@\S+)? (.+)/s);;\
\
if($TYPE eq "TelegramBot" && $recipient){\
my ($contact) = devspec2array("TYPE=(ROOMMATE|GUEST):FILTER=msgContactPush=.*$recipient.*");;\
my $sentMsgId = ReadingsVal($NAME, "$contact\_sentMsgId", "");;\
\
if($sentMsgId ne ""){\
fhem("set $NAME queryEditInline $sentMsgId $recipient $message");;\
}\
else{\
fhem("set $NAME queryInline $recipient $message");;\
}\
}\
else{\
fhem("set $EVENT");;\
}\
}
attr message2queryEditInline room msg
</pre>

Um wieder zurück zum normalen Keyboard zu gelangen genügt es, das notify und den cmdAlias zu deaktivieren.
Das kann komfortabel über ein notify und einen dummy erledigt werden:
<pre>
defmod inline_normal.NOT notify inline_normal.DUM:.* {\
if ("$EVENT" =~ "on") {\
fhem "set sentMsgIdByPeerId active;; attr message2queryEditInline disable 0";;\
} \
elsif ("$EVENT" =~ "off") {\
fhem "set sentMsgIdByPeerId inactive;; attr message2queryEditInline disable 1";;\
}\
}
</pre>

Weitere Infos zum Thema Inline Keyboard sind in der Antwort #10 im Forum zu finden (siehe Link unten).

== JABBER ==
Hier wird die Vewrwendung mit Jabber beschrieben...

== WhatsApp ==
Hier wird die Verwendung mit yowsup/WhatsApp beschrieben...

== Links ==
* Thread über das Modul im {{Link2Forum|Topic=77297|LinkText=FHEM Forum}}

[[Kategorie:Hilfsmodul]]

MsgDialog

2017-10-31T09:02:12Z

Binford6000:

{{Infobox Modul
|ModPurpose=Dialoge für Sofortnachrichten über TelegramBot, Jabber und WhatsApp
|ModType=h
|ModForumArea=Frontends
|ModTechName=76_msgDialog.pm
|ModOwner={{Link2FU|4106|igami}}
}}

== Zielsetzung ==
Ein zentrale Anforderung an die Haus-Automation ist die Kommunikation mit den Anwendern. Fast jeder Anwender möchte über bestimmte Ereignisse informiert werden und Einstellungen vornehmen. FHEM bietet schon seit längerem die Unterstützung für verschiedene Messaging Dienste an.
Mit dem msgDialog Modul können vordefinierte Dialoge erstellt werden. Die Kommunikation erfolgt dabei über den [[msg]] Befehl welcher zurzeit die bidirektionale Kommunikation über [[TelegramBot]], [[Jabber]] und [[yowsup]] (WhatsApp) unterstützt. Eingehende Nachrichten werden einem ROMMATE oder GUEST zugeordnet. Darüber werden auch die Berechtigungen für die einzelnen Dialoge festgelegt.
Die grundlegende Bedienung wird in diesem '''[https://youtu.be/yiCOTeR1YVQ Video]''' am Beispiel von TelegramBot gezeigt.

== Konfiguration ==

=== Voraussetzungen ===
Für dieses Modul wird das Perl JSON Modul benötigt. Auf einem Debian-basierten System (z.B RaspberryPI o.ä.) kann man das mit dem folgenden Befehl installieren:
<pre>
sudo apt-get install libjson-perl
</pre>

=== Hinweis zu den Code Beispielen ===
Es handelt sich bei den Beispielen um eine Raw definition, siehe auch [[Import_von_Code_Snippets]]

=== msgConfig ===

Als erstes benötigt man ein definiertes msgConfig device:

<pre>
defmod myMsgConfig msgConfig
attr myMsgConfig msgDialog_evalSpecials me=<Aktivierungswort bzw. -Nachricht>
TelegramBot=<Name des TelegramBot-device>
attr myMsgConfig msgContactPush TelegramBot
attr myMsgConfig room msg
</pre>

Falls bereits vorhanden, müssen natürlich nur die fehlenden Attribute gesetzt werden.

=== ROOMMATE / GUEST ===

=== Define ===

Definition des metaDialogs:
Zur Auflistung aller berechtigten Dialoge dient - was sonst - ein Dialog!

<pre>
defmod meta_Dialog msgDialog {\
"%me%": {\
"match": "\/?(start|%me%)",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"{return('(' . join(') (', sort(split('\n', fhem('get TYPE=msgDialog:FILTER=NAME!=$SELF:FILTER=allowed=.*($recipient|everyone).* trigger')))) . ') ')}",\
"(abbrechen) ",\
"Ich kann folgendes für dich tun:"\
]\
},\
"abbrechen": {\
"match": "\/?abbrechen",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"(%me%) ",\
"Dialog abgebrochen."\
] \
},\
"beenden": {\
"match": "\/?beenden",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"(%me%) ",\
"Dialog beendet."\
]\
}\
}

attr meta_Dialog DbLogExclude .*
attr meta_Dialog allowed everyone
attr meta_Dialog room msg
</pre>

Aufgrund der Komplexität eines Dialogs mit JSON ist es am praktikabelsten, zunächst einen leeren Dialog zu definieren:
<pre>
define <name> msgDialog {}
</pre>

Anschließend kann die DEF in der Detail-Ansicht des Dialog-Device bearbeitet werden. Jeder Dialog basiert auf der folgenden Struktur von einfach bis komplex.

<pre>
{
"<TRIGGER>": {
"match": "<regex>",
"setOnly": (true|false),
"commands": "(fhem command|{perl code})",
"message": [
"{perl code}",
"text"
],
"<NEXT TRIGGER 1>": {
...
},
"<NEXT TRIGGER 2>": {
...
}
}
}
</pre>

Um den JSON-Teil der Dialoge zu testen, empfiehlt sich ein Besuch auf https://jsonlint.com/
Hier kann der selbst geschriebene JSON-Code validiert werden.

*TRIGGER: Kann ein beliebiger Text sein. Es wird geprüft ob die eingehende Nachricht damit übereinstimmt. Falls ja, wird der Dialog an dieser Stelle fortgesetzt.

*match: Wenn nicht nur genau eine Nachricht zugelassen werden soll, kann noch eine regex angegeben werden. Die regex muss auf die gesamte eingehnde Nachricht zutreffen.

*setOnly: Kann optional auf true oder false gestellt werden. In beiden fällen wird der TRIGGER dann nicht bei "get <name> trigger" zurück gegeben.
Wenn setOnly auf "true" gestellt wird, kann der Dialog an dieser Stelle nicht durch eingehende Nachrichten ausgelöst werden, sondern nur über "get <name> say TRIGGER". Dies kann dazu genutzt werden um einen Dialog aus FHEM heraus zu initiieren.

*commands: Kann einen einzelnen oder mehrere Befehle enthalten:
<pre>
"commands":
"single command"
"commands": [
"command 1",
"command 2",
"{perl command}"
]
</pre>

*message: Kann einen einzelnen oder mehrere Textte enthalten die mit einen Zeilenumbruch verbunden werden:
<pre>
"message": "text"
</pre>
<pre>
"message": [
"text 1",
"text 2",
"{return from perl command}"
]
</pre>

Bei mehrstufigen Dialogen wird diese Struktur ineinander verschachtelt angegeben.
Es werden Variablen und Platzhalter, welche unter dem Attribut evalSpecials definiert werden, ausgewertet.

=== Variablen ===
*$SELF: Eigenname des msgDialog
*$message: eingegangene Nachricht
*$recipient: Name des Dialogpartners

=== Attribute ===
*allowed: Liste mit allen RESIDENTS und ROOMMATE die für diesen Dialog berechtigt sind.
*disable: [0|1] Dialog ist aktiviert|deaktiviert.
*disabledForIntervals: HH:MM-HH:MM HH:MM-HH-MM ...
*evalSpecials: key1=value1 key2=value2 ...Leerzeichen getrennte Liste von Name=Wert Paaren. Wert kann Leerzeichen enthalten, falls es in "" oder {} eingeschlossen ist. Wert wird als perl-Ausdruck ausgewertet, falls es in {} eingeschlossen ist. In der DEF werden %Name% Zeichenketten durch den zugehörigen Wert ersetzt. Dieses Attribut ist als "msgDialog_evalSpecials" im msgConfig Gerät vorhanden. Wenn der selbe Name im msgConfig und msgDialog definiert wurde, wird der Wert aus msgDialog verwendet.
*msgCommand <command>: Befehl der zum Versenden einer Nachricht verwendet wird. Die Vorgabe ist "msg push \@$recipients $message" Dieses Attribut ist als "msgDialog_msgCommand" im msgConfig Gerät vorhanden.

=== set ===
*reset: Setzt den Dialog für alle Benutzer zurück.
*say [@<recipient1>[,<recipient2>,...]] <TRIGGER>[|<NEXT TRIGGER>|...]: Der Dialog wird für alle angegeben Empänger an der angegeben Stelle fortgeführt. Sind keine Empfänger angegeben wird der Dialog für alle unter dem Attribut allowed angegebenen Empfänger fortgeführt.
*updateAllowed: Aktualisiert die Auswahl für das Attribut allowed.

=== get ===
*trigger: Listet alle TRIGGER der ersten Ebene auf bei denen nicht setOnly angegeben ist.

=== READINGS ===
*$recipient_history: Durch | getrennte Liste von TRIGGER um den aktuellen Zustand des Dialogs zu sichern. Für jeden Dialogpartner wird ein Reading angelegt. Wenn der Dialog beendet ist wird das Reading zurückgesetzt.

== Beispiele ==

==== Programmierung der Waschmaschine ====
Das ist ein Beispiel zur Programmierung einer Waschmaschine wie auch oben im Video zu sehen:
<pre>
defmod Waschmaschine_Dialog msgDialog { "Waschmaschine": {\
"message": [\
"{return('(Zeitprogramm stoppen) ') if(ReadingsVal('%controlUnit%', 'controlMode', '') eq 'auto')}",\
"{return('(programmieren) ') if(ReadingsVal('%actor%', 'state', '') ne 'on')}",\
"{return('(einschalten) ') if(ReadingsVal('%actor%', 'state', '') ne 'on')}",\
"(Verlaufsdiagramm) ",\
"(abbrechen) ",\
"{return('Waschmaschine: ' . (ReadingsVal('%actor%', 'state', '') eq 'on' ? 'eingeschaltet' : 'ausgeschaltet'))}",\
"{return('Modus: ' . (ReadingsVal('%controlUnit%', 'controlMode', '') eq 'auto' ? 'Automatik' : 'Manuell (' . ReadingsVal('%controlUnit%', 'time', '') . ')'))}"\
],\
"Zeitprogramm stoppen": {\
"commands": "set %controlUnit% controlMode manual",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Das Zeitprogramm wurde gestoppt."\
]\
},\
"programmieren": {\
"message": [\
"(bestätigen|zurück|abbrechen) ",\
"( 00:00 | 00:15 | 00:30 | 00:45 ) ",\
"( 01:00 | 01:15 | 01:30 | 01:45 ) ",\
"( 02:00 | 02:15 | 02:30 | 02:45 ) ",\
"( 03:00 | 03:15 | 03:30 | 03:45 ) ",\
"( 04:00 | 04:15 | 04:30 | 04:45 ) ",\
"( 05:00 | 05:15 | 05:30 | 05:45 ) ",\
"( 06:00 | 06:15 | 06:30 | 06:45 ) ",\
"( 07:00 | 07:15 | 07:30 | 07:45 ) ",\
"( 08:00 | 08:15 | 08:30 | 08:45 ) ",\
"( 09:00 | 09:15 | 09:30 | 09:45 ) ",\
"( 10:00 | 10:15 | 10:30 | 10:45 ) ",\
"( 11:00 | 11:15 | 11:30 | 11:45 ) ",\
"( 12:00 | 12:15 | 12:30 | 12:45 ) ",\
"( 13:00 | 13:15 | 13:30 | 13:45 ) ",\
"( 14:00 | 14:15 | 14:30 | 14:45 ) ",\
"( 15:00 | 15:15 | 15:30 | 15:45 ) ",\
"( 16:00 | 16:15 | 16:30 | 16:45 ) ",\
"( 17:00 | 17:15 | 17:30 | 17:45 ) ",\
"( 18:00 | 18:15 | 18:30 | 18:45 ) ",\
"( 19:00 | 19:15 | 19:30 | 19:45 ) ",\
"( 20:00 | 20:15 | 20:30 | 20:45 ) ",\
"( 21:00 | 21:15 | 21:30 | 21:45 ) ",\
"( 22:00 | 22:15 | 22:30 | 22:45 ) ",\
"( 23:00 | 23:15 | 23:30 | 23:45 ) ",\
"Wann soll die Wäsche fertig sein?",\
"Bitte Uhrzeit in HH:MM angeben.",\
"Aktuell ist [%controlUnit%:time] Uhr eingestellt."\
],\
"Uhrzeit": {\
"match": " ?([0-1][0-9]|2[0-3]):[0-5][0-9] ?",\
"commands": [\
"set %controlUnit% time $message",\
"set $SELF say @$recipient Waschmaschine|programmieren|bestätigen"\
]\
},\
"bestätigen": {\
"commands": "set %controlUnit% controlMode auto",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Das Zeitprogramm wurde eingestellt.",\
"Die Wäsche wird voraussichtlich um [%controlUnit%:time] Uhr fertig sein.",\
"Bitte die Waschmaschine vorbereiten."\
]\
}\
},\
"einschalten": {\
"commands": [\
"set %controlUnit% controlMode manual",\
"set %actor% on"\
]\
},\
"Verlaufsdiagramm": {\
"commands": "set %TelegramBot% cmdSend {plotAsPng('%plot%')}",\
"message": "TelegramBot_MTYPE=queryInline (%me%) $message"\
}\
},\
"auto": {\
"setOnly": true,\
"commands": [\
"set %actor% on",\
"set %controlUnit% controlMode manual"\
],\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine wurde automatisch eingeschaltet."\
]\
},\
"manual": {\
"setOnly": true,\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine wurde manuell eingeschaltet."\
]\
},\
"done": {\
"setOnly": true,\
"commands": "set %actor% off",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine ist fertig."\
]\
}\
}
attr Waschmaschine_Dialog evalSpecials actor=HM_2C10D8_Sw\
controlUnit=Waschkeller_washer_controlUnit\
plot=Waschkeller_washer_SVG
</pre>

== TelegramBot: Inline Keyboard verwenden==

In Telegram gibt es die Möglichkeit die Art des Keyboards zu ändern. Links das normale Keyboard, rechts das Inline Keyboard.

[[Datei:76msgDialog menu.png|Normales Keyboard]] [[Datei:76msgDialog menu inline.PNG|Inline Keyboard]]

In diesem '''[https://youtu.be/oRDy2918mVI Video]''' wird Telegram mit einem Inline Keyboard verwendet.

Um eine Nachricht bei Telegram zu verändern, gibt es den Befehl "queryEditInline".
Dafür wird die MsgId von der Nachricht benötigt. Das erledigt ein notify, welches die msgId pro Peer abspeichert:

<pre>
defmod sentMsgIdByPeerId notify .+:sentMsgId.+ {\
return unless($TYPE eq "TelegramBot");;\
\
my $dev_hash = $defs{$NAME};;\
my $sentMsgId = ReadingsVal($NAME, "sentMsgId", "");;\
my $sentMsgPeerId = ReadingsVal($NAME, "sentMsgPeerId", "");;\
my ($contact) = devspec2array("TYPE=(ROOMMATE|GUEST):FILTER=msgContactPush=.*$sentMsgPeerId.*");;\
\
readingsSingleUpdate($dev_hash, "$contact\_sentMsgId", $sentMsgId, 1);;\
}
attr sentMsgIdByPeerId devStateIcon {ReadingsVal($name, "state", "inactive") eq "active" ? ".*:ios-on-blue:inactive" : ".*:ios-off:active"}
attr sentMsgIdByPeerId icon audio_mic
attr sentMsgIdByPeerId room msg
</pre>

Danach wird der Message-Befehl von
<pre>
set <TelegramBot> message
</pre>
auf
<pre>
set <TelegramBot> queryEditInline
</pre>
geändert. Dafür wird ein [[cmdalias]] verwendet:

<pre>
defmod message2queryEditInline cmdalias set .+ message (.|\n)+ AS {\
my ($NAME, $cmd, $message) = split(/[\s]+/, $EVENT, 3);;\
my $TYPE = InternalVal($NAME, "TYPE", "");;\
(my $recipient, $message) = ($message =~ m/(@\S+)? (.+)/s);;\
\
if($TYPE eq "TelegramBot" && $recipient){\
my ($contact) = devspec2array("TYPE=(ROOMMATE|GUEST):FILTER=msgContactPush=.*$recipient.*");;\
my $sentMsgId = ReadingsVal($NAME, "$contact\_sentMsgId", "");;\
\
if($sentMsgId ne ""){\
fhem("set $NAME queryEditInline $sentMsgId $recipient $message");;\
}\
else{\
fhem("set $NAME queryInline $recipient $message");;\
}\
}\
else{\
fhem("set $EVENT");;\
}\
}
attr message2queryEditInline room msg
</pre>

Um wieder zurück zum normalen Keyboard zu gelangen genügt es, das notify und den cmdAlias zu deaktivieren.
Das kann komfortabel über ein notify und einen dummy erledigt werden:
<pre>
defmod inline_normal.NOT notify inline_normal.DUM:.* {\
if ("$EVENT" =~ "on") {\
fhem "set sentMsgIdByPeerId active;; attr message2queryEditInline disable 0";;\
} \
elsif ("$EVENT" =~ "off") {\
fhem "set sentMsgIdByPeerId inactive;; attr message2queryEditInline disable 1";;\
}\
}
</pre>

Weitere Infos zum Thema Inline Keyboard sind in der Antwort #10 im Forum zu finden (siehe Link unten).

== JABBER ==
Hier wird die Vewrwendung mit Jabber beschrieben...

== WhatsApp ==
Hier wird die Vewrwendung mit yowsup/WhatsApp beschrieben...

== Links ==
* Thread über das Modul im {{Link2Forum|Topic=77297|LinkText=FHEM Forum}}

[[Kategorie:Hilfsmodul]]

MsgDialog

2017-10-31T09:01:39Z

Binford6000:

{{Infobox Modul
|ModPurpose=Dialoge für Sofortnachrichten über TelegramBot, Jabber und WhatsApp
|ModType=h
|ModForumArea=Frontends
|ModTechName=76_msgDialog.pm
|ModOwner={{Link2FU|4106|igami}}
}}

== Zielsetzung ==
Ein zentrale Anforderung an die Haus-Automation ist die Kommunikation mit den Anwendern. Fast jeder Anwender möchte über bestimmte Ereignisse informiert werden und Einstellungen vornehmen. FHEM bietet schon seit längerem die Unterstützung für verschiedene Messaging Dienste an.
Mit dem msgDialog Modul können vordefinierte Dialoge erstellt werden. Die Kommunikation erfolgt dabei über den [[msg]] Befehl welcher zurzeit die bidirektionale Kommunikation über [[TelegramBot]], [[Jabber]] und [[yowsup]] (WhatsApp) unterstützt. Eingehende Nachrichten werden einem ROMMATE oder GUEST zugeordnet. Darüber werden auch die Berechtigungen für die einzelnen Dialoge festgelegt.
Die grundlegende Bedienung wird in diesem '''[https://youtu.be/yiCOTeR1YVQ Video]''' am Beispiel von TelegramBot gezeigt.

== Einbindung in FHEM ==

=== Voraussetzungen ===
Für dieses Modul wird das Perl JSON Modul benötigt. Auf einem Debian-basierten System (z.B RaspberryPI o.ä.) kann man das mit dem folgenden Befehl installieren:
<pre>
sudo apt-get install libjson-perl
</pre>

=== Hinweis zu den Code Beispielen ===
Es handelt sich bei den Beispielen um eine Raw definition, siehe auch [[Import_von_Code_Snippets]]

=== msgConfig ===

Als erstes benötigt man ein definiertes msgConfig device:

<pre>
defmod myMsgConfig msgConfig
attr myMsgConfig msgDialog_evalSpecials me=<Aktivierungswort bzw. -Nachricht>
TelegramBot=<Name des TelegramBot-device>
attr myMsgConfig msgContactPush TelegramBot
attr myMsgConfig room msg
</pre>

Falls bereits vorhanden, müssen natürlich nur die fehlenden Attribute gesetzt werden.

=== ROOMMATE / GUEST ===

=== Define ===

Definition des metaDialogs:
Zur Auflistung aller berechtigten Dialoge dient - was sonst - ein Dialog!

<pre>
defmod meta_Dialog msgDialog {\
"%me%": {\
"match": "\/?(start|%me%)",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"{return('(' . join(') (', sort(split('\n', fhem('get TYPE=msgDialog:FILTER=NAME!=$SELF:FILTER=allowed=.*($recipient|everyone).* trigger')))) . ') ')}",\
"(abbrechen) ",\
"Ich kann folgendes für dich tun:"\
]\
},\
"abbrechen": {\
"match": "\/?abbrechen",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"(%me%) ",\
"Dialog abgebrochen."\
] \
},\
"beenden": {\
"match": "\/?beenden",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"(%me%) ",\
"Dialog beendet."\
]\
}\
}

attr meta_Dialog DbLogExclude .*
attr meta_Dialog allowed everyone
attr meta_Dialog room msg
</pre>

Aufgrund der Komplexität eines Dialogs mit JSON ist es am praktikabelsten, zunächst einen leeren Dialog zu definieren:
<pre>
define <name> msgDialog {}
</pre>

Anschließend kann die DEF in der Detail-Ansicht des Dialog-Device bearbeitet werden. Jeder Dialog basiert auf der folgenden Struktur von einfach bis komplex.

<pre>
{
"<TRIGGER>": {
"match": "<regex>",
"setOnly": (true|false),
"commands": "(fhem command|{perl code})",
"message": [
"{perl code}",
"text"
],
"<NEXT TRIGGER 1>": {
...
},
"<NEXT TRIGGER 2>": {
...
}
}
}
</pre>

Um den JSON-Teil der Dialoge zu testen, empfiehlt sich ein Besuch auf https://jsonlint.com/
Hier kann der selbst geschriebene JSON-Code validiert werden.

*TRIGGER: Kann ein beliebiger Text sein. Es wird geprüft ob die eingehende Nachricht damit übereinstimmt. Falls ja, wird der Dialog an dieser Stelle fortgesetzt.

*match: Wenn nicht nur genau eine Nachricht zugelassen werden soll, kann noch eine regex angegeben werden. Die regex muss auf die gesamte eingehnde Nachricht zutreffen.

*setOnly: Kann optional auf true oder false gestellt werden. In beiden fällen wird der TRIGGER dann nicht bei "get <name> trigger" zurück gegeben.
Wenn setOnly auf "true" gestellt wird, kann der Dialog an dieser Stelle nicht durch eingehende Nachrichten ausgelöst werden, sondern nur über "get <name> say TRIGGER". Dies kann dazu genutzt werden um einen Dialog aus FHEM heraus zu initiieren.

*commands: Kann einen einzelnen oder mehrere Befehle enthalten:
<pre>
"commands":
"single command"
"commands": [
"command 1",
"command 2",
"{perl command}"
]
</pre>

*message: Kann einen einzelnen oder mehrere Textte enthalten die mit einen Zeilenumbruch verbunden werden:
<pre>
"message": "text"
</pre>
<pre>
"message": [
"text 1",
"text 2",
"{return from perl command}"
]
</pre>

Bei mehrstufigen Dialogen wird diese Struktur ineinander verschachtelt angegeben.
Es werden Variablen und Platzhalter, welche unter dem Attribut evalSpecials definiert werden, ausgewertet.

=== Variablen ===
*$SELF: Eigenname des msgDialog
*$message: eingegangene Nachricht
*$recipient: Name des Dialogpartners

=== Attribute ===
*allowed: Liste mit allen RESIDENTS und ROOMMATE die für diesen Dialog berechtigt sind.
*disable: [0|1] Dialog ist aktiviert|deaktiviert.
*disabledForIntervals: HH:MM-HH:MM HH:MM-HH-MM ...
*evalSpecials: key1=value1 key2=value2 ...Leerzeichen getrennte Liste von Name=Wert Paaren. Wert kann Leerzeichen enthalten, falls es in "" oder {} eingeschlossen ist. Wert wird als perl-Ausdruck ausgewertet, falls es in {} eingeschlossen ist. In der DEF werden %Name% Zeichenketten durch den zugehörigen Wert ersetzt. Dieses Attribut ist als "msgDialog_evalSpecials" im msgConfig Gerät vorhanden. Wenn der selbe Name im msgConfig und msgDialog definiert wurde, wird der Wert aus msgDialog verwendet.
*msgCommand <command>: Befehl der zum Versenden einer Nachricht verwendet wird. Die Vorgabe ist "msg push \@$recipients $message" Dieses Attribut ist als "msgDialog_msgCommand" im msgConfig Gerät vorhanden.

=== set ===
*reset: Setzt den Dialog für alle Benutzer zurück.
*say [@<recipient1>[,<recipient2>,...]] <TRIGGER>[|<NEXT TRIGGER>|...]: Der Dialog wird für alle angegeben Empänger an der angegeben Stelle fortgeführt. Sind keine Empfänger angegeben wird der Dialog für alle unter dem Attribut allowed angegebenen Empfänger fortgeführt.
*updateAllowed: Aktualisiert die Auswahl für das Attribut allowed.

=== get ===
*trigger: Listet alle TRIGGER der ersten Ebene auf bei denen nicht setOnly angegeben ist.

=== READINGS ===
*$recipient_history: Durch | getrennte Liste von TRIGGER um den aktuellen Zustand des Dialogs zu sichern. Für jeden Dialogpartner wird ein Reading angelegt. Wenn der Dialog beendet ist wird das Reading zurückgesetzt.

== Beispiele ==

==== Programmierung der Waschmaschine ====
Das ist ein Beispiel zur Programmierung einer Waschmaschine wie auch oben im Video zu sehen:
<pre>
defmod Waschmaschine_Dialog msgDialog { "Waschmaschine": {\
"message": [\
"{return('(Zeitprogramm stoppen) ') if(ReadingsVal('%controlUnit%', 'controlMode', '') eq 'auto')}",\
"{return('(programmieren) ') if(ReadingsVal('%actor%', 'state', '') ne 'on')}",\
"{return('(einschalten) ') if(ReadingsVal('%actor%', 'state', '') ne 'on')}",\
"(Verlaufsdiagramm) ",\
"(abbrechen) ",\
"{return('Waschmaschine: ' . (ReadingsVal('%actor%', 'state', '') eq 'on' ? 'eingeschaltet' : 'ausgeschaltet'))}",\
"{return('Modus: ' . (ReadingsVal('%controlUnit%', 'controlMode', '') eq 'auto' ? 'Automatik' : 'Manuell (' . ReadingsVal('%controlUnit%', 'time', '') . ')'))}"\
],\
"Zeitprogramm stoppen": {\
"commands": "set %controlUnit% controlMode manual",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Das Zeitprogramm wurde gestoppt."\
]\
},\
"programmieren": {\
"message": [\
"(bestätigen|zurück|abbrechen) ",\
"( 00:00 | 00:15 | 00:30 | 00:45 ) ",\
"( 01:00 | 01:15 | 01:30 | 01:45 ) ",\
"( 02:00 | 02:15 | 02:30 | 02:45 ) ",\
"( 03:00 | 03:15 | 03:30 | 03:45 ) ",\
"( 04:00 | 04:15 | 04:30 | 04:45 ) ",\
"( 05:00 | 05:15 | 05:30 | 05:45 ) ",\
"( 06:00 | 06:15 | 06:30 | 06:45 ) ",\
"( 07:00 | 07:15 | 07:30 | 07:45 ) ",\
"( 08:00 | 08:15 | 08:30 | 08:45 ) ",\
"( 09:00 | 09:15 | 09:30 | 09:45 ) ",\
"( 10:00 | 10:15 | 10:30 | 10:45 ) ",\
"( 11:00 | 11:15 | 11:30 | 11:45 ) ",\
"( 12:00 | 12:15 | 12:30 | 12:45 ) ",\
"( 13:00 | 13:15 | 13:30 | 13:45 ) ",\
"( 14:00 | 14:15 | 14:30 | 14:45 ) ",\
"( 15:00 | 15:15 | 15:30 | 15:45 ) ",\
"( 16:00 | 16:15 | 16:30 | 16:45 ) ",\
"( 17:00 | 17:15 | 17:30 | 17:45 ) ",\
"( 18:00 | 18:15 | 18:30 | 18:45 ) ",\
"( 19:00 | 19:15 | 19:30 | 19:45 ) ",\
"( 20:00 | 20:15 | 20:30 | 20:45 ) ",\
"( 21:00 | 21:15 | 21:30 | 21:45 ) ",\
"( 22:00 | 22:15 | 22:30 | 22:45 ) ",\
"( 23:00 | 23:15 | 23:30 | 23:45 ) ",\
"Wann soll die Wäsche fertig sein?",\
"Bitte Uhrzeit in HH:MM angeben.",\
"Aktuell ist [%controlUnit%:time] Uhr eingestellt."\
],\
"Uhrzeit": {\
"match": " ?([0-1][0-9]|2[0-3]):[0-5][0-9] ?",\
"commands": [\
"set %controlUnit% time $message",\
"set $SELF say @$recipient Waschmaschine|programmieren|bestätigen"\
]\
},\
"bestätigen": {\
"commands": "set %controlUnit% controlMode auto",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Das Zeitprogramm wurde eingestellt.",\
"Die Wäsche wird voraussichtlich um [%controlUnit%:time] Uhr fertig sein.",\
"Bitte die Waschmaschine vorbereiten."\
]\
}\
},\
"einschalten": {\
"commands": [\
"set %controlUnit% controlMode manual",\
"set %actor% on"\
]\
},\
"Verlaufsdiagramm": {\
"commands": "set %TelegramBot% cmdSend {plotAsPng('%plot%')}",\
"message": "TelegramBot_MTYPE=queryInline (%me%) $message"\
}\
},\
"auto": {\
"setOnly": true,\
"commands": [\
"set %actor% on",\
"set %controlUnit% controlMode manual"\
],\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine wurde automatisch eingeschaltet."\
]\
},\
"manual": {\
"setOnly": true,\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine wurde manuell eingeschaltet."\
]\
},\
"done": {\
"setOnly": true,\
"commands": "set %actor% off",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine ist fertig."\
]\
}\
}
attr Waschmaschine_Dialog evalSpecials actor=HM_2C10D8_Sw\
controlUnit=Waschkeller_washer_controlUnit\
plot=Waschkeller_washer_SVG
</pre>

== TelegramBot: Inline Keyboard verwenden==

In Telegram gibt es die Möglichkeit die Art des Keyboards zu ändern. Links das normale Keyboard, rechts das Inline Keyboard.

[[Datei:76msgDialog menu.png|Normales Keyboard]] [[Datei:76msgDialog menu inline.PNG|Inline Keyboard]]

In diesem '''[https://youtu.be/oRDy2918mVI Video]''' wird Telegram mit einem Inline Keyboard verwendet.

Um eine Nachricht bei Telegram zu verändern, gibt es den Befehl "queryEditInline".
Dafür wird die MsgId von der Nachricht benötigt. Das erledigt ein notify, welches die msgId pro Peer abspeichert:

<pre>
defmod sentMsgIdByPeerId notify .+:sentMsgId.+ {\
return unless($TYPE eq "TelegramBot");;\
\
my $dev_hash = $defs{$NAME};;\
my $sentMsgId = ReadingsVal($NAME, "sentMsgId", "");;\
my $sentMsgPeerId = ReadingsVal($NAME, "sentMsgPeerId", "");;\
my ($contact) = devspec2array("TYPE=(ROOMMATE|GUEST):FILTER=msgContactPush=.*$sentMsgPeerId.*");;\
\
readingsSingleUpdate($dev_hash, "$contact\_sentMsgId", $sentMsgId, 1);;\
}
attr sentMsgIdByPeerId devStateIcon {ReadingsVal($name, "state", "inactive") eq "active" ? ".*:ios-on-blue:inactive" : ".*:ios-off:active"}
attr sentMsgIdByPeerId icon audio_mic
attr sentMsgIdByPeerId room msg
</pre>

Danach wird der Message-Befehl von
<pre>
set <TelegramBot> message
</pre>
auf
<pre>
set <TelegramBot> queryEditInline
</pre>
geändert. Dafür wird ein [[cmdalias]] verwendet:

<pre>
defmod message2queryEditInline cmdalias set .+ message (.|\n)+ AS {\
my ($NAME, $cmd, $message) = split(/[\s]+/, $EVENT, 3);;\
my $TYPE = InternalVal($NAME, "TYPE", "");;\
(my $recipient, $message) = ($message =~ m/(@\S+)? (.+)/s);;\
\
if($TYPE eq "TelegramBot" && $recipient){\
my ($contact) = devspec2array("TYPE=(ROOMMATE|GUEST):FILTER=msgContactPush=.*$recipient.*");;\
my $sentMsgId = ReadingsVal($NAME, "$contact\_sentMsgId", "");;\
\
if($sentMsgId ne ""){\
fhem("set $NAME queryEditInline $sentMsgId $recipient $message");;\
}\
else{\
fhem("set $NAME queryInline $recipient $message");;\
}\
}\
else{\
fhem("set $EVENT");;\
}\
}
attr message2queryEditInline room msg
</pre>

Um wieder zurück zum normalen Keyboard zu gelangen genügt es, das notify und den cmdAlias zu deaktivieren.
Das kann komfortabel über ein notify und einen dummy erledigt werden:
<pre>
defmod inline_normal.NOT notify inline_normal.DUM:.* {\
if ("$EVENT" =~ "on") {\
fhem "set sentMsgIdByPeerId active;; attr message2queryEditInline disable 0";;\
} \
elsif ("$EVENT" =~ "off") {\
fhem "set sentMsgIdByPeerId inactive;; attr message2queryEditInline disable 1";;\
}\
}
</pre>

Weitere Infos zum Thema Inline Keyboard sind in der Antwort #10 im Forum zu finden (siehe Link unten).

== JABBER ==
Hier wird die Vewrwendung mit Jabber beschrieben...

== WhatsApp ==
Hier wird die Vewrwendung mit yowsup/WhatsApp beschrieben...

== Links ==
* Thread über das Modul im {{Link2Forum|Topic=77297|LinkText=FHEM Forum}}

[[Kategorie:Hilfsmodul]]

MsgDialog

2017-10-31T08:57:34Z

Binford6000:

{{Infobox Modul
|ModPurpose=Dialoge für Sofortnachrichten über TelegramBot, Jabber und WhatsApp
|ModType=d
|ModForumArea=Frontends
|ModTechName=76_msgDialog.pm
|ModOwner={{Link2FU|4106|igami}}
}}

== Zielsetzung ==
Ein zentrale Anforderung an die Haus-Automation ist die Kommunikation mit den Anwendern. Fast jeder Anwender möchte über bestimmte Ereignisse informiert werden und Einstellungen vornehmen. FHEM bietet schon seit längerem die Unterstützung für verschiedene Messaging Dienste an.
Mit dem msgDialog Modul können vordefinierte Dialoge erstellt werden. Die Kommunikation erfolgt dabei über den [[msg]] Befehl welcher zurzeit die bidirektionale Kommunikation über [[TelegramBot]], [[Jabber]] und [[yowsup]] (WhatsApp) unterstützt. Eingehende Nachrichten werden einem ROMMATE oder GUEST zugeordnet. Darüber werden auch die Berechtigungen für die einzelnen Dialoge festgelegt.
Die grundlegende Bedienung wird in diesem '''[https://youtu.be/yiCOTeR1YVQ Video]''' am Beispiel von TelegramBot gezeigt.

== Einbindung in FHEM ==

=== Voraussetzungen ===
Für dieses Modul wird das Perl JSON Modul benötigt. Auf einem Debian-basierten System (z.B RaspberryPI o.ä.) kann man das mit dem folgenden Befehl installieren:
<pre>
sudo apt-get install libjson-perl
</pre>

=== msgConfig ===

Als nächstes benötigt man ein definiertes msgConfig device:

<pre>
defmod myMsgConfig msgConfig
attr myMsgConfig msgDialog_evalSpecials me=<Aktivierungswort bzw. -Nachricht>
TelegramBot=<Name des TelegramBot-device>
attr myMsgConfig msgContactPush TelegramBot
attr myMsgConfig room msg
</pre>

Falls bereits vorhanden müssen, natürlich nur die fehlenden Attribute gesetzt werden.

=== ROOMMATE / GUEST ===

=== Define ===

Definition des metaDialogs:
Zur Auflistung aller berechtigten Dialoge dient - was sonst - ein Dialog!

<pre>
defmod meta_Dialog msgDialog {\
"%me%": {\
"match": "\/?(start|%me%)",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"{return('(' . join(') (', sort(split('\n', fhem('get TYPE=msgDialog:FILTER=NAME!=$SELF:FILTER=allowed=.*($recipient|everyone).* trigger')))) . ') ')}",\
"(abbrechen) ",\
"Ich kann folgendes für dich tun:"\
]\
},\
"abbrechen": {\
"match": "\/?abbrechen",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"(%me%) ",\
"Dialog abgebrochen."\
] \
},\
"beenden": {\
"match": "\/?beenden",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"(%me%) ",\
"Dialog beendet."\
]\
}\
}

attr meta_Dialog DbLogExclude .*
attr meta_Dialog allowed everyone
attr meta_Dialog room msg
</pre>

Aufgrund der Komplexität eines Dialogs mit JSON ist es am praktikabelsten, zunächst einen leeren Dialog zu definieren:
<pre>
define <name> msgDialog {}
</pre>

Anschließend kann die DEF in der Detail-Ansicht des Dialog-Device bearbeitet werden. Jeder Dialog basiert auf der folgenden Struktur von einfach bis komplex.

<pre>
{
"<TRIGGER>": {
"match": "<regex>",
"setOnly": (true|false),
"commands": "(fhem command|{perl code})",
"message": [
"{perl code}",
"text"
],
"<NEXT TRIGGER 1>": {
...
},
"<NEXT TRIGGER 2>": {
...
}
}
}
</pre>

Um den JSON-Teil der Dialoge zu testen, empfiehlt sich ein Besuch auf https://jsonlint.com/
Hier kann der selbst geschriebene JSON-Code validiert werden.

*TRIGGER: Kann ein beliebiger Text sein. Es wird geprüft ob die eingehende Nachricht damit übereinstimmt. Falls ja, wird der Dialog an dieser Stelle fortgesetzt.

*match: Wenn nicht nur genau eine Nachricht zugelassen werden soll, kann noch eine regex angegeben werden. Die regex muss auf die gesamte eingehnde Nachricht zutreffen.

*setOnly: Kann optional auf true oder false gestellt werden. In beiden fällen wird der TRIGGER dann nicht bei "get <name> trigger" zurück gegeben.
Wenn setOnly auf "true" gestellt wird, kann der Dialog an dieser Stelle nicht durch eingehende Nachrichten ausgelöst werden, sondern nur über "get <name> say TRIGGER". Dies kann dazu genutzt werden um einen Dialog aus FHEM heraus zu initiieren.

*commands: Kann einen einzelnen oder mehrere Befehle enthalten:
<pre>
"commands":
"single command"
"commands": [
"command 1",
"command 2",
"{perl command}"
]
</pre>

*message: Kann einen einzelnen oder mehrere Textte enthalten die mit einen Zeilenumbruch verbunden werden:
<pre>
"message": "text"
</pre>
<pre>
"message": [
"text 1",
"text 2",
"{return from perl command}"
]
</pre>

Bei mehrstufigen Dialogen wird diese Struktur ineinander verschachtelt angegeben.
Es werden Variablen und Platzhalter, welche unter dem Attribut evalSpecials definiert werden, ausgewertet.

=== Variablen ===
*$SELF: Eigenname des msgDialog
*$message: eingegangene Nachricht
*$recipient: Name des Dialogpartners

=== Attribute ===
*allowed: Liste mit allen RESIDENTS und ROOMMATE die für diesen Dialog berechtigt sind.
*disable: [0|1] Dialog ist aktiviert|deaktiviert.
*disabledForIntervals: HH:MM-HH:MM HH:MM-HH-MM ...
*evalSpecials: key1=value1 key2=value2 ...Leerzeichen getrennte Liste von Name=Wert Paaren. Wert kann Leerzeichen enthalten, falls es in "" oder {} eingeschlossen ist. Wert wird als perl-Ausdruck ausgewertet, falls es in {} eingeschlossen ist. In der DEF werden %Name% Zeichenketten durch den zugehörigen Wert ersetzt. Dieses Attribut ist als "msgDialog_evalSpecials" im msgConfig Gerät vorhanden. Wenn der selbe Name im msgConfig und msgDialog definiert wurde, wird der Wert aus msgDialog verwendet.
*msgCommand <command>: Befehl der zum Versenden einer Nachricht verwendet wird. Die Vorgabe ist "msg push \@$recipients $message" Dieses Attribut ist als "msgDialog_msgCommand" im msgConfig Gerät vorhanden.

=== set ===
*reset: Setzt den Dialog für alle Benutzer zurück.
*say [@<recipient1>[,<recipient2>,...]] <TRIGGER>[|<NEXT TRIGGER>|...]: Der Dialog wird für alle angegeben Empänger an der angegeben Stelle fortgeführt. Sind keine Empfänger angegeben wird der Dialog für alle unter dem Attribut allowed angegebenen Empfänger fortgeführt.
*updateAllowed: Aktualisiert die Auswahl für das Attribut allowed.

=== get ===
*trigger: Listet alle TRIGGER der ersten Ebene auf bei denen nicht setOnly angegeben ist.

=== READINGS ===
*$recipient_history: Durch | getrennte Liste von TRIGGER um den aktuellen Zustand des Dialogs zu sichern. Für jeden Dialogpartner wird ein Reading angelegt. Wenn der Dialog beendet ist wird das Reading zurückgesetzt.

== Beispiele ==

==== Programmierung der Waschmaschine ====
Das ist ein Beispiel zur Programmierung einer Waschmaschine wie auch oben im Video zu sehen:
<pre>
defmod Waschmaschine_Dialog msgDialog { "Waschmaschine": {\
"message": [\
"{return('(Zeitprogramm stoppen) ') if(ReadingsVal('%controlUnit%', 'controlMode', '') eq 'auto')}",\
"{return('(programmieren) ') if(ReadingsVal('%actor%', 'state', '') ne 'on')}",\
"{return('(einschalten) ') if(ReadingsVal('%actor%', 'state', '') ne 'on')}",\
"(Verlaufsdiagramm) ",\
"(abbrechen) ",\
"{return('Waschmaschine: ' . (ReadingsVal('%actor%', 'state', '') eq 'on' ? 'eingeschaltet' : 'ausgeschaltet'))}",\
"{return('Modus: ' . (ReadingsVal('%controlUnit%', 'controlMode', '') eq 'auto' ? 'Automatik' : 'Manuell (' . ReadingsVal('%controlUnit%', 'time', '') . ')'))}"\
],\
"Zeitprogramm stoppen": {\
"commands": "set %controlUnit% controlMode manual",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Das Zeitprogramm wurde gestoppt."\
]\
},\
"programmieren": {\
"message": [\
"(bestätigen|zurück|abbrechen) ",\
"( 00:00 | 00:15 | 00:30 | 00:45 ) ",\
"( 01:00 | 01:15 | 01:30 | 01:45 ) ",\
"( 02:00 | 02:15 | 02:30 | 02:45 ) ",\
"( 03:00 | 03:15 | 03:30 | 03:45 ) ",\
"( 04:00 | 04:15 | 04:30 | 04:45 ) ",\
"( 05:00 | 05:15 | 05:30 | 05:45 ) ",\
"( 06:00 | 06:15 | 06:30 | 06:45 ) ",\
"( 07:00 | 07:15 | 07:30 | 07:45 ) ",\
"( 08:00 | 08:15 | 08:30 | 08:45 ) ",\
"( 09:00 | 09:15 | 09:30 | 09:45 ) ",\
"( 10:00 | 10:15 | 10:30 | 10:45 ) ",\
"( 11:00 | 11:15 | 11:30 | 11:45 ) ",\
"( 12:00 | 12:15 | 12:30 | 12:45 ) ",\
"( 13:00 | 13:15 | 13:30 | 13:45 ) ",\
"( 14:00 | 14:15 | 14:30 | 14:45 ) ",\
"( 15:00 | 15:15 | 15:30 | 15:45 ) ",\
"( 16:00 | 16:15 | 16:30 | 16:45 ) ",\
"( 17:00 | 17:15 | 17:30 | 17:45 ) ",\
"( 18:00 | 18:15 | 18:30 | 18:45 ) ",\
"( 19:00 | 19:15 | 19:30 | 19:45 ) ",\
"( 20:00 | 20:15 | 20:30 | 20:45 ) ",\
"( 21:00 | 21:15 | 21:30 | 21:45 ) ",\
"( 22:00 | 22:15 | 22:30 | 22:45 ) ",\
"( 23:00 | 23:15 | 23:30 | 23:45 ) ",\
"Wann soll die Wäsche fertig sein?",\
"Bitte Uhrzeit in HH:MM angeben.",\
"Aktuell ist [%controlUnit%:time] Uhr eingestellt."\
],\
"Uhrzeit": {\
"match": " ?([0-1][0-9]|2[0-3]):[0-5][0-9] ?",\
"commands": [\
"set %controlUnit% time $message",\
"set $SELF say @$recipient Waschmaschine|programmieren|bestätigen"\
]\
},\
"bestätigen": {\
"commands": "set %controlUnit% controlMode auto",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Das Zeitprogramm wurde eingestellt.",\
"Die Wäsche wird voraussichtlich um [%controlUnit%:time] Uhr fertig sein.",\
"Bitte die Waschmaschine vorbereiten."\
]\
}\
},\
"einschalten": {\
"commands": [\
"set %controlUnit% controlMode manual",\
"set %actor% on"\
]\
},\
"Verlaufsdiagramm": {\
"commands": "set %TelegramBot% cmdSend {plotAsPng('%plot%')}",\
"message": "TelegramBot_MTYPE=queryInline (%me%) $message"\
}\
},\
"auto": {\
"setOnly": true,\
"commands": [\
"set %actor% on",\
"set %controlUnit% controlMode manual"\
],\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine wurde automatisch eingeschaltet."\
]\
},\
"manual": {\
"setOnly": true,\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine wurde manuell eingeschaltet."\
]\
},\
"done": {\
"setOnly": true,\
"commands": "set %actor% off",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine ist fertig."\
]\
}\
}
attr Waschmaschine_Dialog evalSpecials actor=HM_2C10D8_Sw\
controlUnit=Waschkeller_washer_controlUnit\
plot=Waschkeller_washer_SVG
</pre>

== TelegramBot: Inline Keyboard verwenden==

In Telegram gibt es die Möglichkeit die Art des Keyboards zu ändern. Links das normale Keyboard, rechts das Inline Keyboard.

[[Datei:76msgDialog menu.png|Normales Keyboard]] [[Datei:76msgDialog menu inline.PNG|Inline Keyboard]]

In diesem '''[https://youtu.be/oRDy2918mVI Video]''' wird Telegram mit einem Inline Keyboard verwendet.

Um eine Nachricht bei Telegram zu verändern, gibt es den Befehl "queryEditInline".
Dafür wird die MsgId von der Nachricht benötigt. Das erledigt ein notify, welches die msgId pro Peer abspeichert:

<pre>
defmod sentMsgIdByPeerId notify .+:sentMsgId.+ {\
return unless($TYPE eq "TelegramBot");;\
\
my $dev_hash = $defs{$NAME};;\
my $sentMsgId = ReadingsVal($NAME, "sentMsgId", "");;\
my $sentMsgPeerId = ReadingsVal($NAME, "sentMsgPeerId", "");;\
my ($contact) = devspec2array("TYPE=(ROOMMATE|GUEST):FILTER=msgContactPush=.*$sentMsgPeerId.*");;\
\
readingsSingleUpdate($dev_hash, "$contact\_sentMsgId", $sentMsgId, 1);;\
}
attr sentMsgIdByPeerId devStateIcon {ReadingsVal($name, "state", "inactive") eq "active" ? ".*:ios-on-blue:inactive" : ".*:ios-off:active"}
attr sentMsgIdByPeerId icon audio_mic
attr sentMsgIdByPeerId room msg
</pre>

Danach wird der Message-Befehl von
<pre>
set <TelegramBot> message
</pre>
auf
<pre>
set <TelegramBot> queryEditInline
</pre>
geändert. Dafür wird ein [[cmdalias]] verwendet:

<pre>
defmod message2queryEditInline cmdalias set .+ message (.|\n)+ AS {\
my ($NAME, $cmd, $message) = split(/[\s]+/, $EVENT, 3);;\
my $TYPE = InternalVal($NAME, "TYPE", "");;\
(my $recipient, $message) = ($message =~ m/(@\S+)? (.+)/s);;\
\
if($TYPE eq "TelegramBot" && $recipient){\
my ($contact) = devspec2array("TYPE=(ROOMMATE|GUEST):FILTER=msgContactPush=.*$recipient.*");;\
my $sentMsgId = ReadingsVal($NAME, "$contact\_sentMsgId", "");;\
\
if($sentMsgId ne ""){\
fhem("set $NAME queryEditInline $sentMsgId $recipient $message");;\
}\
else{\
fhem("set $NAME queryInline $recipient $message");;\
}\
}\
else{\
fhem("set $EVENT");;\
}\
}
attr message2queryEditInline room msg
</pre>

Um wieder zurück zum normalen Keyboard zu gelangen genügt es, das notify und den cmdAlias zu deaktivieren.
Das kann komfortabel über ein notify und einen dummy erledigt werden:
<pre>
defmod inline_normal.NOT notify inline_normal.DUM:.* {\
if ("$EVENT" =~ "on") {\
fhem "set sentMsgIdByPeerId active;; attr message2queryEditInline disable 0";;\
} \
elsif ("$EVENT" =~ "off") {\
fhem "set sentMsgIdByPeerId inactive;; attr message2queryEditInline disable 1";;\
}\
}
</pre>

Weitere Infos zum Thema Inline Keyboard sind in der Antwort #10 im Forum zu finden (siehe Link unten).

== JABBER ==
Hier wird die Vewrwendung mit Jabber beschrieben...

== WhatsApp ==
Hier wird die Vewrwendung mit yowsup/WhatsApp beschrieben...

== Links ==
* Thread über das Modul im {{Link2Forum|Topic=77297|LinkText=FHEM Forum}}

[[Kategorie:Hilfsmodul]]

MsgDialog

2017-10-31T08:26:53Z

Binford6000: /* WHatsApp */

{{Infobox Modul
|ModPurpose=Dialoge für Sofortnachrichten über TelegramBot, Jabber und WhatsApp
|ModType=d
|ModForumArea=Frontends
|ModTechName=76_msgDialog.pm
|ModOwner={{Link2FU|4106|igami}}
}}

== Zielsetzung ==
Ein zentrale Anforderung an die Haus-Automation ist die Kommunikation mit den Anwendern. Fast jeder Anwender möchte über bestimmte Ereignisse informiert werden und Einstellungen vornehmen. FHEM bietet schon seit längerem die Unterstützung für verschiedene Messaging Dienste an.
Mit dem msgDialog Modul können vordefinierte Dialoge erstellt werden. Die Kommunikation erfolgt dabei über den [[msg]] Befehl welcher zurzeit die bidirektionale Kommunikation über [[TelegramBot]], [[Jabber]] und [[yowsup]] (WhatsApp) unterstützt. Eingehende Nachrichten werden einem ROMMATE oder GUEST zugeordnet. Darüber werden auch die Berechtigungen für die einzelnen Dialoge festgelegt.
Die grundlegende Bedienung wird in diesem '''[https://youtu.be/yiCOTeR1YVQ Video]''' am Beispiel von TelegramBot gezeigt.

== Einbindung in FHEM ==

=== Voraussetzungen ===
Für dieses Modul wird das Perl JSON Modul benötigt. Auf einem Debian-basierten System (z.B RaspberryPI o.ä.) kann man das mit dem folgenden Befehl installieren:
<pre>
sudo apt-get install libjson-perl
</pre>

=== msgConfig ===

Als nächstes benötigt man ein definiertes msgConfig device:

<pre>
defmod myMsgConfig msgConfig
attr myMsgConfig msgDialog_evalSpecials me=<Aktivierungswort bzw. -Nachricht>
TelegramBot=<Name des TelegramBot-device>
attr myMsgConfig msgContactPush TelegramBot
attr myMsgConfig room msg
</pre>

Falls bereits vorhanden müssen, natürlich nur die fehlenden Attribute gesetzt werden.

=== ROOMMATE / GUEST ===

=== DEFINE ===

Definition des metaDialogs:
Zur Auflistung aller berechtigten Dialoge dient - was sonst - ein Dialog!

<pre>
defmod meta_Dialog msgDialog {\
"%me%": {\
"match": "\/?(start|%me%)",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"{return('(' . join(') (', sort(split('\n', fhem('get TYPE=msgDialog:FILTER=NAME!=$SELF:FILTER=allowed=.*($recipient|everyone).* trigger')))) . ') ')}",\
"(abbrechen) ",\
"Ich kann folgendes für dich tun:"\
]\
},\
"abbrechen": {\
"match": "\/?abbrechen",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"(%me%) ",\
"Dialog abgebrochen."\
] \
},\
"beenden": {\
"match": "\/?beenden",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"(%me%) ",\
"Dialog beendet."\
]\
}\
}

attr meta_Dialog DbLogExclude .*
attr meta_Dialog allowed everyone
attr meta_Dialog room msg
</pre>

Aufgrund der Komplexität eines Dialogs mit JSON ist es am praktikabelsten, zunächst einen leeren Dialog zu definieren:
<pre>
define <name> msgDialog {}
</pre>

Anschließend kann die DEF in der Detail-Ansicht des Dialog-Device bearbeitet werden. Jeder Dialog basiert auf der folgenden Struktur von einfach bis komplex.

<pre>
{
"<TRIGGER>": {
"match": "<regex>",
"setOnly": (true|false),
"commands": "(fhem command|{perl code})",
"message": [
"{perl code}",
"text"
],
"<NEXT TRIGGER 1>": {
...
},
"<NEXT TRIGGER 2>": {
...
}
}
}
</pre>

Um den JSON-Teil der Dialoge zu testen, empfiehlt sich ein Besuch auf https://jsonlint.com/
Hier kann der selbst geschriebene JSON-Code validiert werden.

*TRIGGER: Kann ein beliebiger Text sein. Es wird geprüft ob die eingehende Nachricht damit übereinstimmt. Falls ja, wird der Dialog an dieser Stelle fortgesetzt.

*match: Wenn nicht nur genau eine Nachricht zugelassen werden soll, kann noch eine regex angegeben werden. Die regex muss auf die gesamte eingehnde Nachricht zutreffen.

*setOnly: Kann optional auf true oder false gestellt werden. In beiden fällen wird der TRIGGER dann nicht bei "get <name> trigger" zurück gegeben.
Wenn setOnly auf "true" gestellt wird, kann der Dialog an dieser Stelle nicht durch eingehende Nachrichten ausgelöst werden, sondern nur über "get <name> say TRIGGER". Dies kann dazu genutzt werden um einen Dialog aus FHEM heraus zu initiieren.

*commands: Kann einen einzelnen oder mehrere Befehle enthalten:
<pre>
"commands":
"single command"
"commands": [
"command 1",
"command 2",
"{perl command}"
]
</pre>

*message: Kann einen einzelnen oder mehrere Textte enthalten die mit einen Zeilenumbruch verbunden werden:
<pre>
"message": "text"
</pre>
<pre>
"message": [
"text 1",
"text 2",
"{return from perl command}"
]
</pre>

Bei mehrstufigen Dialogen wird diese Struktur ineinander verschachtelt angegeben.
Es werden Variablen und Platzhalter, welche unter dem Attribut evalSpecials definiert werden, ausgewertet.

=== Variablen ===
*$SELF: Eigenname des msgDialog
*$message: eingegangene Nachricht
*$recipient: Name des Dialogpartners

=== ATTRIBUTE ===
*allowed: Liste mit allen RESIDENTS und ROOMMATE die für diesen Dialog berechtigt sind.
*disable: [0|1] Dialog ist aktiviert|deaktiviert.
*disabledForIntervals: HH:MM-HH:MM HH:MM-HH-MM ...
*evalSpecials: key1=value1 key2=value2 ...Leerzeichen getrennte Liste von Name=Wert Paaren. Wert kann Leerzeichen enthalten, falls es in "" oder {} eingeschlossen ist. Wert wird als perl-Ausdruck ausgewertet, falls es in {} eingeschlossen ist. In der DEF werden %Name% Zeichenketten durch den zugehörigen Wert ersetzt. Dieses Attribut ist als "msgDialog_evalSpecials" im msgConfig Gerät vorhanden. Wenn der selbe Name im msgConfig und msgDialog definiert wurde, wird der Wert aus msgDialog verwendet.
*msgCommand <command>: Befehl der zum Versenden einer Nachricht verwendet wird. Die Vorgabe ist "msg push \@$recipients $message" Dieses Attribut ist als "msgDialog_msgCommand" im msgConfig Gerät vorhanden.

=== set ===
*reset: Setzt den Dialog für alle Benutzer zurück.
*say [@<recipient1>[,<recipient2>,...]] <TRIGGER>[|<NEXT TRIGGER>|...]: Der Dialog wird für alle angegeben Empänger an der angegeben Stelle fortgeführt. Sind keine Empfänger angegeben wird der Dialog für alle unter dem Attribut allowed angegebenen Empfänger fortgeführt.
*updateAllowed: Aktualisiert die Auswahl für das Attribut allowed.

=== get ===
*trigger: Listet alle TRIGGER der ersten Ebene auf bei denen nicht setOnly angegeben ist.

=== READINGS ===
*$recipient_history: Durch | getrennte Liste von TRIGGER um den aktuellen Zustand des Dialogs zu sichern. Für jeden Dialogpartner wird ein Reading angelegt. Wenn der Dialog beendet ist wird das Reading zurückgesetzt.

== Beispiele ==

==== Programmierung der Waschmaschine ====
Das ist ein Beispiel zur Programmierung einer Waschmaschine wie auch oben im Video zu sehen:
<pre>
defmod Waschmaschine_Dialog msgDialog { "Waschmaschine": {\
"message": [\
"{return('(Zeitprogramm stoppen) ') if(ReadingsVal('%controlUnit%', 'controlMode', '') eq 'auto')}",\
"{return('(programmieren) ') if(ReadingsVal('%actor%', 'state', '') ne 'on')}",\
"{return('(einschalten) ') if(ReadingsVal('%actor%', 'state', '') ne 'on')}",\
"(Verlaufsdiagramm) ",\
"(abbrechen) ",\
"{return('Waschmaschine: ' . (ReadingsVal('%actor%', 'state', '') eq 'on' ? 'eingeschaltet' : 'ausgeschaltet'))}",\
"{return('Modus: ' . (ReadingsVal('%controlUnit%', 'controlMode', '') eq 'auto' ? 'Automatik' : 'Manuell (' . ReadingsVal('%controlUnit%', 'time', '') . ')'))}"\
],\
"Zeitprogramm stoppen": {\
"commands": "set %controlUnit% controlMode manual",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Das Zeitprogramm wurde gestoppt."\
]\
},\
"programmieren": {\
"message": [\
"(bestätigen|zurück|abbrechen) ",\
"( 00:00 | 00:15 | 00:30 | 00:45 ) ",\
"( 01:00 | 01:15 | 01:30 | 01:45 ) ",\
"( 02:00 | 02:15 | 02:30 | 02:45 ) ",\
"( 03:00 | 03:15 | 03:30 | 03:45 ) ",\
"( 04:00 | 04:15 | 04:30 | 04:45 ) ",\
"( 05:00 | 05:15 | 05:30 | 05:45 ) ",\
"( 06:00 | 06:15 | 06:30 | 06:45 ) ",\
"( 07:00 | 07:15 | 07:30 | 07:45 ) ",\
"( 08:00 | 08:15 | 08:30 | 08:45 ) ",\
"( 09:00 | 09:15 | 09:30 | 09:45 ) ",\
"( 10:00 | 10:15 | 10:30 | 10:45 ) ",\
"( 11:00 | 11:15 | 11:30 | 11:45 ) ",\
"( 12:00 | 12:15 | 12:30 | 12:45 ) ",\
"( 13:00 | 13:15 | 13:30 | 13:45 ) ",\
"( 14:00 | 14:15 | 14:30 | 14:45 ) ",\
"( 15:00 | 15:15 | 15:30 | 15:45 ) ",\
"( 16:00 | 16:15 | 16:30 | 16:45 ) ",\
"( 17:00 | 17:15 | 17:30 | 17:45 ) ",\
"( 18:00 | 18:15 | 18:30 | 18:45 ) ",\
"( 19:00 | 19:15 | 19:30 | 19:45 ) ",\
"( 20:00 | 20:15 | 20:30 | 20:45 ) ",\
"( 21:00 | 21:15 | 21:30 | 21:45 ) ",\
"( 22:00 | 22:15 | 22:30 | 22:45 ) ",\
"( 23:00 | 23:15 | 23:30 | 23:45 ) ",\
"Wann soll die Wäsche fertig sein?",\
"Bitte Uhrzeit in HH:MM angeben.",\
"Aktuell ist [%controlUnit%:time] Uhr eingestellt."\
],\
"Uhrzeit": {\
"match": " ?([0-1][0-9]|2[0-3]):[0-5][0-9] ?",\
"commands": [\
"set %controlUnit% time $message",\
"set $SELF say @$recipient Waschmaschine|programmieren|bestätigen"\
]\
},\
"bestätigen": {\
"commands": "set %controlUnit% controlMode auto",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Das Zeitprogramm wurde eingestellt.",\
"Die Wäsche wird voraussichtlich um [%controlUnit%:time] Uhr fertig sein.",\
"Bitte die Waschmaschine vorbereiten."\
]\
}\
},\
"einschalten": {\
"commands": [\
"set %controlUnit% controlMode manual",\
"set %actor% on"\
]\
},\
"Verlaufsdiagramm": {\
"commands": "set %TelegramBot% cmdSend {plotAsPng('%plot%')}",\
"message": "TelegramBot_MTYPE=queryInline (%me%) $message"\
}\
},\
"auto": {\
"setOnly": true,\
"commands": [\
"set %actor% on",\
"set %controlUnit% controlMode manual"\
],\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine wurde automatisch eingeschaltet."\
]\
},\
"manual": {\
"setOnly": true,\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine wurde manuell eingeschaltet."\
]\
},\
"done": {\
"setOnly": true,\
"commands": "set %actor% off",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine ist fertig."\
]\
}\
}
attr Waschmaschine_Dialog evalSpecials actor=HM_2C10D8_Sw\
controlUnit=Waschkeller_washer_controlUnit\
plot=Waschkeller_washer_SVG
</pre>

== TelegramBot: Inline Keyboard verwenden==

In Telegram gibt es die Möglichkeit die Art des Keyboards zu ändern. Links das normale Keyboard, rechts das Inline Keyboard.

[[Datei:76msgDialog menu.png|Normales Keyboard]] [[Datei:76msgDialog menu inline.PNG|Inline Keyboard]]

In diesem '''[https://youtu.be/oRDy2918mVI Video]''' wird Telegram mit einem Inline Keyboard verwendet.

Um eine Nachricht bei Telegram zu verändern, gibt es den Befehl "queryEditInline".
Dafür wird die MsgId von der Nachricht benötigt. Das erledigt ein notify, welches die msgId pro Peer abspeichert:

<pre>
defmod sentMsgIdByPeerId notify .+:sentMsgId.+ {\
return unless($TYPE eq "TelegramBot");;\
\
my $dev_hash = $defs{$NAME};;\
my $sentMsgId = ReadingsVal($NAME, "sentMsgId", "");;\
my $sentMsgPeerId = ReadingsVal($NAME, "sentMsgPeerId", "");;\
my ($contact) = devspec2array("TYPE=(ROOMMATE|GUEST):FILTER=msgContactPush=.*$sentMsgPeerId.*");;\
\
readingsSingleUpdate($dev_hash, "$contact\_sentMsgId", $sentMsgId, 1);;\
}
attr sentMsgIdByPeerId devStateIcon {ReadingsVal($name, "state", "inactive") eq "active" ? ".*:ios-on-blue:inactive" : ".*:ios-off:active"}
attr sentMsgIdByPeerId icon audio_mic
attr sentMsgIdByPeerId room msg
</pre>

Danach wird der Message-Befehl von
<pre>
set <TelegramBot> message
</pre>
auf
<pre>
set <TelegramBot> queryEditInline
</pre>
geändert. Dafür wird ein [[cmdalias]] verwendet:

<pre>
defmod message2queryEditInline cmdalias set .+ message (.|\n)+ AS {\
my ($NAME, $cmd, $message) = split(/[\s]+/, $EVENT, 3);;\
my $TYPE = InternalVal($NAME, "TYPE", "");;\
(my $recipient, $message) = ($message =~ m/(@\S+)? (.+)/s);;\
\
if($TYPE eq "TelegramBot" && $recipient){\
my ($contact) = devspec2array("TYPE=(ROOMMATE|GUEST):FILTER=msgContactPush=.*$recipient.*");;\
my $sentMsgId = ReadingsVal($NAME, "$contact\_sentMsgId", "");;\
\
if($sentMsgId ne ""){\
fhem("set $NAME queryEditInline $sentMsgId $recipient $message");;\
}\
else{\
fhem("set $NAME queryInline $recipient $message");;\
}\
}\
else{\
fhem("set $EVENT");;\
}\
}
attr message2queryEditInline room msg
</pre>

Um wieder zurück zum normalen Keyboard zu gelangen genügt es, das notify und den cmdAlias zu deaktivieren.
Das kann komfortabel über ein notify und einen dummy erledigt werden:
<pre>
defmod inline_normal.NOT notify inline_normal.DUM:.* {\
if ("$EVENT" =~ "on") {\
fhem "set sentMsgIdByPeerId active;; attr message2queryEditInline disable 0";;\
} \
elsif ("$EVENT" =~ "off") {\
fhem "set sentMsgIdByPeerId inactive;; attr message2queryEditInline disable 1";;\
}\
}
</pre>

Weitere Infos zum Thema Inline Keyboard sind in der Antwort #10 im Forum zu finden (siehe Link unten).

== JABBER ==
Hier wird die Vewrwendung mit Jabber beschrieben...

== WhatsApp ==
Hier wird die Vewrwendung mit yowsup/WhatsApp beschrieben...

== Links ==
* Thread über das Modul im {{Link2Forum|Topic=77297|LinkText=FHEM Forum}}

[[Kategorie:Hilfsmodul]]

MsgDialog

2017-10-31T08:26:31Z

Binford6000:

{{Infobox Modul
|ModPurpose=Dialoge für Sofortnachrichten über TelegramBot, Jabber und WhatsApp
|ModType=d
|ModForumArea=Frontends
|ModTechName=76_msgDialog.pm
|ModOwner={{Link2FU|4106|igami}}
}}

== Zielsetzung ==
Ein zentrale Anforderung an die Haus-Automation ist die Kommunikation mit den Anwendern. Fast jeder Anwender möchte über bestimmte Ereignisse informiert werden und Einstellungen vornehmen. FHEM bietet schon seit längerem die Unterstützung für verschiedene Messaging Dienste an.
Mit dem msgDialog Modul können vordefinierte Dialoge erstellt werden. Die Kommunikation erfolgt dabei über den [[msg]] Befehl welcher zurzeit die bidirektionale Kommunikation über [[TelegramBot]], [[Jabber]] und [[yowsup]] (WhatsApp) unterstützt. Eingehende Nachrichten werden einem ROMMATE oder GUEST zugeordnet. Darüber werden auch die Berechtigungen für die einzelnen Dialoge festgelegt.
Die grundlegende Bedienung wird in diesem '''[https://youtu.be/yiCOTeR1YVQ Video]''' am Beispiel von TelegramBot gezeigt.

== Einbindung in FHEM ==

=== Voraussetzungen ===
Für dieses Modul wird das Perl JSON Modul benötigt. Auf einem Debian-basierten System (z.B RaspberryPI o.ä.) kann man das mit dem folgenden Befehl installieren:
<pre>
sudo apt-get install libjson-perl
</pre>

=== msgConfig ===

Als nächstes benötigt man ein definiertes msgConfig device:

<pre>
defmod myMsgConfig msgConfig
attr myMsgConfig msgDialog_evalSpecials me=<Aktivierungswort bzw. -Nachricht>
TelegramBot=<Name des TelegramBot-device>
attr myMsgConfig msgContactPush TelegramBot
attr myMsgConfig room msg
</pre>

Falls bereits vorhanden müssen, natürlich nur die fehlenden Attribute gesetzt werden.

=== ROOMMATE / GUEST ===

=== DEFINE ===

Definition des metaDialogs:
Zur Auflistung aller berechtigten Dialoge dient - was sonst - ein Dialog!

<pre>
defmod meta_Dialog msgDialog {\
"%me%": {\
"match": "\/?(start|%me%)",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"{return('(' . join(') (', sort(split('\n', fhem('get TYPE=msgDialog:FILTER=NAME!=$SELF:FILTER=allowed=.*($recipient|everyone).* trigger')))) . ') ')}",\
"(abbrechen) ",\
"Ich kann folgendes für dich tun:"\
]\
},\
"abbrechen": {\
"match": "\/?abbrechen",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"(%me%) ",\
"Dialog abgebrochen."\
] \
},\
"beenden": {\
"match": "\/?beenden",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"(%me%) ",\
"Dialog beendet."\
]\
}\
}

attr meta_Dialog DbLogExclude .*
attr meta_Dialog allowed everyone
attr meta_Dialog room msg
</pre>

Aufgrund der Komplexität eines Dialogs mit JSON ist es am praktikabelsten, zunächst einen leeren Dialog zu definieren:
<pre>
define <name> msgDialog {}
</pre>

Anschließend kann die DEF in der Detail-Ansicht des Dialog-Device bearbeitet werden. Jeder Dialog basiert auf der folgenden Struktur von einfach bis komplex.

<pre>
{
"<TRIGGER>": {
"match": "<regex>",
"setOnly": (true|false),
"commands": "(fhem command|{perl code})",
"message": [
"{perl code}",
"text"
],
"<NEXT TRIGGER 1>": {
...
},
"<NEXT TRIGGER 2>": {
...
}
}
}
</pre>

Um den JSON-Teil der Dialoge zu testen, empfiehlt sich ein Besuch auf https://jsonlint.com/
Hier kann der selbst geschriebene JSON-Code validiert werden.

*TRIGGER: Kann ein beliebiger Text sein. Es wird geprüft ob die eingehende Nachricht damit übereinstimmt. Falls ja, wird der Dialog an dieser Stelle fortgesetzt.

*match: Wenn nicht nur genau eine Nachricht zugelassen werden soll, kann noch eine regex angegeben werden. Die regex muss auf die gesamte eingehnde Nachricht zutreffen.

*setOnly: Kann optional auf true oder false gestellt werden. In beiden fällen wird der TRIGGER dann nicht bei "get <name> trigger" zurück gegeben.
Wenn setOnly auf "true" gestellt wird, kann der Dialog an dieser Stelle nicht durch eingehende Nachrichten ausgelöst werden, sondern nur über "get <name> say TRIGGER". Dies kann dazu genutzt werden um einen Dialog aus FHEM heraus zu initiieren.

*commands: Kann einen einzelnen oder mehrere Befehle enthalten:
<pre>
"commands":
"single command"
"commands": [
"command 1",
"command 2",
"{perl command}"
]
</pre>

*message: Kann einen einzelnen oder mehrere Textte enthalten die mit einen Zeilenumbruch verbunden werden:
<pre>
"message": "text"
</pre>
<pre>
"message": [
"text 1",
"text 2",
"{return from perl command}"
]
</pre>

Bei mehrstufigen Dialogen wird diese Struktur ineinander verschachtelt angegeben.
Es werden Variablen und Platzhalter, welche unter dem Attribut evalSpecials definiert werden, ausgewertet.

=== Variablen ===
*$SELF: Eigenname des msgDialog
*$message: eingegangene Nachricht
*$recipient: Name des Dialogpartners

=== ATTRIBUTE ===
*allowed: Liste mit allen RESIDENTS und ROOMMATE die für diesen Dialog berechtigt sind.
*disable: [0|1] Dialog ist aktiviert|deaktiviert.
*disabledForIntervals: HH:MM-HH:MM HH:MM-HH-MM ...
*evalSpecials: key1=value1 key2=value2 ...Leerzeichen getrennte Liste von Name=Wert Paaren. Wert kann Leerzeichen enthalten, falls es in "" oder {} eingeschlossen ist. Wert wird als perl-Ausdruck ausgewertet, falls es in {} eingeschlossen ist. In der DEF werden %Name% Zeichenketten durch den zugehörigen Wert ersetzt. Dieses Attribut ist als "msgDialog_evalSpecials" im msgConfig Gerät vorhanden. Wenn der selbe Name im msgConfig und msgDialog definiert wurde, wird der Wert aus msgDialog verwendet.
*msgCommand <command>: Befehl der zum Versenden einer Nachricht verwendet wird. Die Vorgabe ist "msg push \@$recipients $message" Dieses Attribut ist als "msgDialog_msgCommand" im msgConfig Gerät vorhanden.

=== set ===
*reset: Setzt den Dialog für alle Benutzer zurück.
*say [@<recipient1>[,<recipient2>,...]] <TRIGGER>[|<NEXT TRIGGER>|...]: Der Dialog wird für alle angegeben Empänger an der angegeben Stelle fortgeführt. Sind keine Empfänger angegeben wird der Dialog für alle unter dem Attribut allowed angegebenen Empfänger fortgeführt.
*updateAllowed: Aktualisiert die Auswahl für das Attribut allowed.

=== get ===
*trigger: Listet alle TRIGGER der ersten Ebene auf bei denen nicht setOnly angegeben ist.

=== READINGS ===
*$recipient_history: Durch | getrennte Liste von TRIGGER um den aktuellen Zustand des Dialogs zu sichern. Für jeden Dialogpartner wird ein Reading angelegt. Wenn der Dialog beendet ist wird das Reading zurückgesetzt.

== Beispiele ==

==== Programmierung der Waschmaschine ====
Das ist ein Beispiel zur Programmierung einer Waschmaschine wie auch oben im Video zu sehen:
<pre>
defmod Waschmaschine_Dialog msgDialog { "Waschmaschine": {\
"message": [\
"{return('(Zeitprogramm stoppen) ') if(ReadingsVal('%controlUnit%', 'controlMode', '') eq 'auto')}",\
"{return('(programmieren) ') if(ReadingsVal('%actor%', 'state', '') ne 'on')}",\
"{return('(einschalten) ') if(ReadingsVal('%actor%', 'state', '') ne 'on')}",\
"(Verlaufsdiagramm) ",\
"(abbrechen) ",\
"{return('Waschmaschine: ' . (ReadingsVal('%actor%', 'state', '') eq 'on' ? 'eingeschaltet' : 'ausgeschaltet'))}",\
"{return('Modus: ' . (ReadingsVal('%controlUnit%', 'controlMode', '') eq 'auto' ? 'Automatik' : 'Manuell (' . ReadingsVal('%controlUnit%', 'time', '') . ')'))}"\
],\
"Zeitprogramm stoppen": {\
"commands": "set %controlUnit% controlMode manual",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Das Zeitprogramm wurde gestoppt."\
]\
},\
"programmieren": {\
"message": [\
"(bestätigen|zurück|abbrechen) ",\
"( 00:00 | 00:15 | 00:30 | 00:45 ) ",\
"( 01:00 | 01:15 | 01:30 | 01:45 ) ",\
"( 02:00 | 02:15 | 02:30 | 02:45 ) ",\
"( 03:00 | 03:15 | 03:30 | 03:45 ) ",\
"( 04:00 | 04:15 | 04:30 | 04:45 ) ",\
"( 05:00 | 05:15 | 05:30 | 05:45 ) ",\
"( 06:00 | 06:15 | 06:30 | 06:45 ) ",\
"( 07:00 | 07:15 | 07:30 | 07:45 ) ",\
"( 08:00 | 08:15 | 08:30 | 08:45 ) ",\
"( 09:00 | 09:15 | 09:30 | 09:45 ) ",\
"( 10:00 | 10:15 | 10:30 | 10:45 ) ",\
"( 11:00 | 11:15 | 11:30 | 11:45 ) ",\
"( 12:00 | 12:15 | 12:30 | 12:45 ) ",\
"( 13:00 | 13:15 | 13:30 | 13:45 ) ",\
"( 14:00 | 14:15 | 14:30 | 14:45 ) ",\
"( 15:00 | 15:15 | 15:30 | 15:45 ) ",\
"( 16:00 | 16:15 | 16:30 | 16:45 ) ",\
"( 17:00 | 17:15 | 17:30 | 17:45 ) ",\
"( 18:00 | 18:15 | 18:30 | 18:45 ) ",\
"( 19:00 | 19:15 | 19:30 | 19:45 ) ",\
"( 20:00 | 20:15 | 20:30 | 20:45 ) ",\
"( 21:00 | 21:15 | 21:30 | 21:45 ) ",\
"( 22:00 | 22:15 | 22:30 | 22:45 ) ",\
"( 23:00 | 23:15 | 23:30 | 23:45 ) ",\
"Wann soll die Wäsche fertig sein?",\
"Bitte Uhrzeit in HH:MM angeben.",\
"Aktuell ist [%controlUnit%:time] Uhr eingestellt."\
],\
"Uhrzeit": {\
"match": " ?([0-1][0-9]|2[0-3]):[0-5][0-9] ?",\
"commands": [\
"set %controlUnit% time $message",\
"set $SELF say @$recipient Waschmaschine|programmieren|bestätigen"\
]\
},\
"bestätigen": {\
"commands": "set %controlUnit% controlMode auto",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Das Zeitprogramm wurde eingestellt.",\
"Die Wäsche wird voraussichtlich um [%controlUnit%:time] Uhr fertig sein.",\
"Bitte die Waschmaschine vorbereiten."\
]\
}\
},\
"einschalten": {\
"commands": [\
"set %controlUnit% controlMode manual",\
"set %actor% on"\
]\
},\
"Verlaufsdiagramm": {\
"commands": "set %TelegramBot% cmdSend {plotAsPng('%plot%')}",\
"message": "TelegramBot_MTYPE=queryInline (%me%) $message"\
}\
},\
"auto": {\
"setOnly": true,\
"commands": [\
"set %actor% on",\
"set %controlUnit% controlMode manual"\
],\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine wurde automatisch eingeschaltet."\
]\
},\
"manual": {\
"setOnly": true,\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine wurde manuell eingeschaltet."\
]\
},\
"done": {\
"setOnly": true,\
"commands": "set %actor% off",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine ist fertig."\
]\
}\
}
attr Waschmaschine_Dialog evalSpecials actor=HM_2C10D8_Sw\
controlUnit=Waschkeller_washer_controlUnit\
plot=Waschkeller_washer_SVG
</pre>

== TelegramBot: Inline Keyboard verwenden==

In Telegram gibt es die Möglichkeit die Art des Keyboards zu ändern. Links das normale Keyboard, rechts das Inline Keyboard.

[[Datei:76msgDialog menu.png|Normales Keyboard]] [[Datei:76msgDialog menu inline.PNG|Inline Keyboard]]

In diesem '''[https://youtu.be/oRDy2918mVI Video]''' wird Telegram mit einem Inline Keyboard verwendet.

Um eine Nachricht bei Telegram zu verändern, gibt es den Befehl "queryEditInline".
Dafür wird die MsgId von der Nachricht benötigt. Das erledigt ein notify, welches die msgId pro Peer abspeichert:

<pre>
defmod sentMsgIdByPeerId notify .+:sentMsgId.+ {\
return unless($TYPE eq "TelegramBot");;\
\
my $dev_hash = $defs{$NAME};;\
my $sentMsgId = ReadingsVal($NAME, "sentMsgId", "");;\
my $sentMsgPeerId = ReadingsVal($NAME, "sentMsgPeerId", "");;\
my ($contact) = devspec2array("TYPE=(ROOMMATE|GUEST):FILTER=msgContactPush=.*$sentMsgPeerId.*");;\
\
readingsSingleUpdate($dev_hash, "$contact\_sentMsgId", $sentMsgId, 1);;\
}
attr sentMsgIdByPeerId devStateIcon {ReadingsVal($name, "state", "inactive") eq "active" ? ".*:ios-on-blue:inactive" : ".*:ios-off:active"}
attr sentMsgIdByPeerId icon audio_mic
attr sentMsgIdByPeerId room msg
</pre>

Danach wird der Message-Befehl von
<pre>
set <TelegramBot> message
</pre>
auf
<pre>
set <TelegramBot> queryEditInline
</pre>
geändert. Dafür wird ein [[cmdalias]] verwendet:

<pre>
defmod message2queryEditInline cmdalias set .+ message (.|\n)+ AS {\
my ($NAME, $cmd, $message) = split(/[\s]+/, $EVENT, 3);;\
my $TYPE = InternalVal($NAME, "TYPE", "");;\
(my $recipient, $message) = ($message =~ m/(@\S+)? (.+)/s);;\
\
if($TYPE eq "TelegramBot" && $recipient){\
my ($contact) = devspec2array("TYPE=(ROOMMATE|GUEST):FILTER=msgContactPush=.*$recipient.*");;\
my $sentMsgId = ReadingsVal($NAME, "$contact\_sentMsgId", "");;\
\
if($sentMsgId ne ""){\
fhem("set $NAME queryEditInline $sentMsgId $recipient $message");;\
}\
else{\
fhem("set $NAME queryInline $recipient $message");;\
}\
}\
else{\
fhem("set $EVENT");;\
}\
}
attr message2queryEditInline room msg
</pre>

Um wieder zurück zum normalen Keyboard zu gelangen genügt es, das notify und den cmdAlias zu deaktivieren.
Das kann komfortabel über ein notify und einen dummy erledigt werden:
<pre>
defmod inline_normal.NOT notify inline_normal.DUM:.* {\
if ("$EVENT" =~ "on") {\
fhem "set sentMsgIdByPeerId active;; attr message2queryEditInline disable 0";;\
} \
elsif ("$EVENT" =~ "off") {\
fhem "set sentMsgIdByPeerId inactive;; attr message2queryEditInline disable 1";;\
}\
}
</pre>

Weitere Infos zum Thema Inline Keyboard sind in der Antwort #10 im Forum zu finden (siehe Link unten).

== JABBER ==
Hier wird die Vewrwendung mit Jabber beschrieben...

== WHatsApp ==
Hier wird die Vewrwendung mit yowsup/WhatsApp beschrieben...

== Links ==
* Thread über das Modul im {{Link2Forum|Topic=77297|LinkText=FHEM Forum}}

[[Kategorie:Hilfsmodul]]

MsgDialog

2017-10-31T08:23:25Z

Binford6000:

{{Infobox Modul
|ModPurpose=Dialoge für Sofortnachrichten über TelegramBot, Jabber und WhatsApp
|ModType=d
|ModForumArea=Frontends
|ModTechName=76_msgDialog.pm
|ModOwner={{Link2FU|4106|igami}}
}}

== Zielsetzung ==
Ein zentrale Anforderung an die Haus-Automation ist die Kommunikation mit den Anwendern. Fast jeder Anwender möchte über bestimmte Ereignisse informiert werden und Einstellungen vornehmen. FHEM bietet schon seit längerem die Unterstützung für verschiedene Messaging Dienste an.
Mit dem msgDialog Modul können vordefinierte Dialoge erstellt werden. Die Kommunikation erfolgt dabei über den [[msg]] Befehl welcher zurzeit die bidirektionale Kommunikation über [[TelegramBot]], [[Jabber]] und [[yowsup]] (WhatsApp) unterstützt. Eingehende Nachrichten werden einem ROMMATE oder GUEST zugeordnet. Darüber werden auch die Berechtigungen für die einzelnen Dialoge festgelegt.
Die grundlegende Bedienung wird in diesem '''[https://youtu.be/yiCOTeR1YVQ Video]''' am Beispiel von TelegramBot gezeigt.

== Einbindung in FHEM ==

=== Voraussetzungen ===
Für dieses Modul wird das Perl JSON Modul benötigt. Auf einem Debian-basierten System (z.B RaspberryPI o.ä.) kann man das mit dem folgenden Befehl installieren:
<pre>
sudo apt-get install libjson-perl
</pre>

=== msgConfig ===

Als nächstes benötigt man ein definiertes msgConfig device:

<pre>
defmod myMsgConfig msgConfig
attr myMsgConfig msgDialog_evalSpecials me=<Aktivierungswort bzw. -Nachricht>
TelegramBot=<Name des TelegramBot-device>
attr myMsgConfig msgContactPush TelegramBot
attr myMsgConfig room msg
</pre>

Falls bereits vorhanden müssen, natürlich nur die fehlenden Attribute gesetzt werden.

=== ROOMMATE / GUEST ===

=== Definition des metaDialogs ===

Zur Auflistung aller berechtigten Dialoge dient - was sonst - ein Dialog!

<pre>
defmod meta_Dialog msgDialog {\
"%me%": {\
"match": "\/?(start|%me%)",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"{return('(' . join(') (', sort(split('\n', fhem('get TYPE=msgDialog:FILTER=NAME!=$SELF:FILTER=allowed=.*($recipient|everyone).* trigger')))) . ') ')}",\
"(abbrechen) ",\
"Ich kann folgendes für dich tun:"\
]\
},\
"abbrechen": {\
"match": "\/?abbrechen",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"(%me%) ",\
"Dialog abgebrochen."\
] \
},\
"beenden": {\
"match": "\/?beenden",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"(%me%) ",\
"Dialog beendet."\
]\
}\
}

attr meta_Dialog DbLogExclude .*
attr meta_Dialog allowed everyone
attr meta_Dialog room msg
</pre>

=== DEFINE ===

Aufgrund der Komplexität eines Dialogs mit JSON ist es am praktikabelsten, zunächst einen leeren Dialog zu definieren:
<pre>
define <name> msgDialog {}
</pre>

Anschließend kann die DEF in der Detail-Ansicht des Dialog-Device bearbeitet werden. Jeder Dialog basiert auf der folgenden Struktur von einfach bis komplex.

<pre>
{
"<TRIGGER>": {
"match": "<regex>",
"setOnly": (true|false),
"commands": "(fhem command|{perl code})",
"message": [
"{perl code}",
"text"
],
"<NEXT TRIGGER 1>": {
...
},
"<NEXT TRIGGER 2>": {
...
}
}
}
</pre>

Um den JSON-Teil der Dialoge zu testen, empfiehlt sich ein Besuch auf https://jsonlint.com/
Hier kann der selbst geschriebene JSON-Code validiert werden.

*TRIGGER: Kann ein beliebiger Text sein. Es wird geprüft ob die eingehende Nachricht damit übereinstimmt. Falls ja, wird der Dialog an dieser Stelle fortgesetzt.

*match: Wenn nicht nur genau eine Nachricht zugelassen werden soll, kann noch eine regex angegeben werden. Die regex muss auf die gesamte eingehnde Nachricht zutreffen.

*setOnly: Kann optional auf true oder false gestellt werden. In beiden fällen wird der TRIGGER dann nicht bei "get <name> trigger" zurück gegeben.
Wenn setOnly auf "true" gestellt wird, kann der Dialog an dieser Stelle nicht durch eingehende Nachrichten ausgelöst werden, sondern nur über "get <name> say TRIGGER". Dies kann dazu genutzt werden um einen Dialog aus FHEM heraus zu initiieren.

*commands: Kann einen einzelnen oder mehrere Befehle enthalten:
<pre>
"commands":
"single command"
"commands": [
"command 1",
"command 2",
"{perl command}"
]
</pre>

*message: Kann einen einzelnen oder mehrere Textte enthalten die mit einen Zeilenumbruch verbunden werden:
<pre>
"message": "text"
</pre>
<pre>
"message": [
"text 1",
"text 2",
"{return from perl command}"
]
</pre>

Bei mehrstufigen Dialogen wird diese Struktur ineinander verschachtelt angegeben.
Es werden Variablen und Platzhalter, welche unter dem Attribut evalSpecials definiert werden, ausgewertet.

=== Variablen ===
*$SELF: Eigenname des msgDialog
*$message: eingegangene Nachricht
*$recipient: Name des Dialogpartners

=== ATTRIBUTE ===
*allowed: Liste mit allen RESIDENTS und ROOMMATE die für diesen Dialog berechtigt sind.
*disable: [0|1] Dialog ist aktiviert|deaktiviert.
*disabledForIntervals: HH:MM-HH:MM HH:MM-HH-MM ...
*evalSpecials: key1=value1 key2=value2 ...Leerzeichen getrennte Liste von Name=Wert Paaren. Wert kann Leerzeichen enthalten, falls es in "" oder {} eingeschlossen ist. Wert wird als perl-Ausdruck ausgewertet, falls es in {} eingeschlossen ist. In der DEF werden %Name% Zeichenketten durch den zugehörigen Wert ersetzt. Dieses Attribut ist als "msgDialog_evalSpecials" im msgConfig Gerät vorhanden. Wenn der selbe Name im msgConfig und msgDialog definiert wurde, wird der Wert aus msgDialog verwendet.
*msgCommand <command>: Befehl der zum Versenden einer Nachricht verwendet wird. Die Vorgabe ist "msg push \@$recipients $message" Dieses Attribut ist als "msgDialog_msgCommand" im msgConfig Gerät vorhanden.

=== set ===
*reset: Setzt den Dialog für alle Benutzer zurück.
*say [@<recipient1>[,<recipient2>,...]] <TRIGGER>[|<NEXT TRIGGER>|...]: Der Dialog wird für alle angegeben Empänger an der angegeben Stelle fortgeführt. Sind keine Empfänger angegeben wird der Dialog für alle unter dem Attribut allowed angegebenen Empfänger fortgeführt.
*updateAllowed: Aktualisiert die Auswahl für das Attribut allowed.

=== get ===
*trigger: Listet alle TRIGGER der ersten Ebene auf bei denen nicht setOnly angegeben ist.

=== READINGS ===
*$recipient_history: Durch | getrennte Liste von TRIGGER um den aktuellen Zustand des Dialogs zu sichern. Für jeden Dialogpartner wird ein Reading angelegt. Wenn der Dialog beendet ist wird das Reading zurückgesetzt.

== Beispiele ==

==== Programmierung der Waschmaschine ====
Das ist ein Beispiel zur Programmierung einer Waschmaschine wie auch oben im Video zu sehen:
<pre>
defmod Waschmaschine_Dialog msgDialog { "Waschmaschine": {\
"message": [\
"{return('(Zeitprogramm stoppen) ') if(ReadingsVal('%controlUnit%', 'controlMode', '') eq 'auto')}",\
"{return('(programmieren) ') if(ReadingsVal('%actor%', 'state', '') ne 'on')}",\
"{return('(einschalten) ') if(ReadingsVal('%actor%', 'state', '') ne 'on')}",\
"(Verlaufsdiagramm) ",\
"(abbrechen) ",\
"{return('Waschmaschine: ' . (ReadingsVal('%actor%', 'state', '') eq 'on' ? 'eingeschaltet' : 'ausgeschaltet'))}",\
"{return('Modus: ' . (ReadingsVal('%controlUnit%', 'controlMode', '') eq 'auto' ? 'Automatik' : 'Manuell (' . ReadingsVal('%controlUnit%', 'time', '') . ')'))}"\
],\
"Zeitprogramm stoppen": {\
"commands": "set %controlUnit% controlMode manual",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Das Zeitprogramm wurde gestoppt."\
]\
},\
"programmieren": {\
"message": [\
"(bestätigen|zurück|abbrechen) ",\
"( 00:00 | 00:15 | 00:30 | 00:45 ) ",\
"( 01:00 | 01:15 | 01:30 | 01:45 ) ",\
"( 02:00 | 02:15 | 02:30 | 02:45 ) ",\
"( 03:00 | 03:15 | 03:30 | 03:45 ) ",\
"( 04:00 | 04:15 | 04:30 | 04:45 ) ",\
"( 05:00 | 05:15 | 05:30 | 05:45 ) ",\
"( 06:00 | 06:15 | 06:30 | 06:45 ) ",\
"( 07:00 | 07:15 | 07:30 | 07:45 ) ",\
"( 08:00 | 08:15 | 08:30 | 08:45 ) ",\
"( 09:00 | 09:15 | 09:30 | 09:45 ) ",\
"( 10:00 | 10:15 | 10:30 | 10:45 ) ",\
"( 11:00 | 11:15 | 11:30 | 11:45 ) ",\
"( 12:00 | 12:15 | 12:30 | 12:45 ) ",\
"( 13:00 | 13:15 | 13:30 | 13:45 ) ",\
"( 14:00 | 14:15 | 14:30 | 14:45 ) ",\
"( 15:00 | 15:15 | 15:30 | 15:45 ) ",\
"( 16:00 | 16:15 | 16:30 | 16:45 ) ",\
"( 17:00 | 17:15 | 17:30 | 17:45 ) ",\
"( 18:00 | 18:15 | 18:30 | 18:45 ) ",\
"( 19:00 | 19:15 | 19:30 | 19:45 ) ",\
"( 20:00 | 20:15 | 20:30 | 20:45 ) ",\
"( 21:00 | 21:15 | 21:30 | 21:45 ) ",\
"( 22:00 | 22:15 | 22:30 | 22:45 ) ",\
"( 23:00 | 23:15 | 23:30 | 23:45 ) ",\
"Wann soll die Wäsche fertig sein?",\
"Bitte Uhrzeit in HH:MM angeben.",\
"Aktuell ist [%controlUnit%:time] Uhr eingestellt."\
],\
"Uhrzeit": {\
"match": " ?([0-1][0-9]|2[0-3]):[0-5][0-9] ?",\
"commands": [\
"set %controlUnit% time $message",\
"set $SELF say @$recipient Waschmaschine|programmieren|bestätigen"\
]\
},\
"bestätigen": {\
"commands": "set %controlUnit% controlMode auto",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Das Zeitprogramm wurde eingestellt.",\
"Die Wäsche wird voraussichtlich um [%controlUnit%:time] Uhr fertig sein.",\
"Bitte die Waschmaschine vorbereiten."\
]\
}\
},\
"einschalten": {\
"commands": [\
"set %controlUnit% controlMode manual",\
"set %actor% on"\
]\
},\
"Verlaufsdiagramm": {\
"commands": "set %TelegramBot% cmdSend {plotAsPng('%plot%')}",\
"message": "TelegramBot_MTYPE=queryInline (%me%) $message"\
}\
},\
"auto": {\
"setOnly": true,\
"commands": [\
"set %actor% on",\
"set %controlUnit% controlMode manual"\
],\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine wurde automatisch eingeschaltet."\
]\
},\
"manual": {\
"setOnly": true,\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine wurde manuell eingeschaltet."\
]\
},\
"done": {\
"setOnly": true,\
"commands": "set %actor% off",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine ist fertig."\
]\
}\
}
attr Waschmaschine_Dialog evalSpecials actor=HM_2C10D8_Sw\
controlUnit=Waschkeller_washer_controlUnit\
plot=Waschkeller_washer_SVG
</pre>

== TelegramBot: Inline Keyboard verwenden==

In Telegram gibt es die Möglichkeit die Art des Keyboards zu ändern. Links das normale Keyboard, rechts das Inline Keyboard.

[[Datei:76msgDialog menu.png|Normales Keyboard]] [[Datei:76msgDialog menu inline.PNG|Inline Keyboard]]

In diesem '''[https://youtu.be/oRDy2918mVI Video]''' wird Telegram mit einem Inline Keyboard verwendet.

Um eine Nachricht bei Telegram zu verändern, gibt es den Befehl "queryEditInline".
Dafür wird die MsgId von der Nachricht benötigt. Das erledigt ein notify, welches die msgId pro Peer abspeichert:

<pre>
defmod sentMsgIdByPeerId notify .+:sentMsgId.+ {\
return unless($TYPE eq "TelegramBot");;\
\
my $dev_hash = $defs{$NAME};;\
my $sentMsgId = ReadingsVal($NAME, "sentMsgId", "");;\
my $sentMsgPeerId = ReadingsVal($NAME, "sentMsgPeerId", "");;\
my ($contact) = devspec2array("TYPE=(ROOMMATE|GUEST):FILTER=msgContactPush=.*$sentMsgPeerId.*");;\
\
readingsSingleUpdate($dev_hash, "$contact\_sentMsgId", $sentMsgId, 1);;\
}
attr sentMsgIdByPeerId devStateIcon {ReadingsVal($name, "state", "inactive") eq "active" ? ".*:ios-on-blue:inactive" : ".*:ios-off:active"}
attr sentMsgIdByPeerId icon audio_mic
attr sentMsgIdByPeerId room msg
</pre>

Danach wird der Message-Befehl von
<pre>
set <TelegramBot> message
</pre>
auf
<pre>
set <TelegramBot> queryEditInline
</pre>
geändert. Dafür wird ein [[cmdalias]] verwendet:

<pre>
defmod message2queryEditInline cmdalias set .+ message (.|\n)+ AS {\
my ($NAME, $cmd, $message) = split(/[\s]+/, $EVENT, 3);;\
my $TYPE = InternalVal($NAME, "TYPE", "");;\
(my $recipient, $message) = ($message =~ m/(@\S+)? (.+)/s);;\
\
if($TYPE eq "TelegramBot" && $recipient){\
my ($contact) = devspec2array("TYPE=(ROOMMATE|GUEST):FILTER=msgContactPush=.*$recipient.*");;\
my $sentMsgId = ReadingsVal($NAME, "$contact\_sentMsgId", "");;\
\
if($sentMsgId ne ""){\
fhem("set $NAME queryEditInline $sentMsgId $recipient $message");;\
}\
else{\
fhem("set $NAME queryInline $recipient $message");;\
}\
}\
else{\
fhem("set $EVENT");;\
}\
}
attr message2queryEditInline room msg
</pre>

Um wieder zurück zum normalen Keyboard zu gelangen genügt es, das notify und den cmdAlias zu deaktivieren.
Das kann komfortabel über ein notify und einen dummy erledigt werden:
<pre>
defmod inline_normal.NOT notify inline_normal.DUM:.* {\
if ("$EVENT" =~ "on") {\
fhem "set sentMsgIdByPeerId active;; attr message2queryEditInline disable 0";;\
} \
elsif ("$EVENT" =~ "off") {\
fhem "set sentMsgIdByPeerId inactive;; attr message2queryEditInline disable 1";;\
}\
}
</pre>

Weitere Infos zum Thema Inline Keyboard sind in der Antwort #10 im Forum zu finden (siehe Link unten).

== JABBER ==
Hier wird die Vewrwendung mit Jabber beschrieben...

== WHatsApp ==
Hier wird die Vewrwendung mit yowsup/WhatsApp beschrieben...

== Links ==
* Thread über das Modul im {{Link2Forum|Topic=77297|LinkText=FHEM Forum}}

[[Kategorie:Hilfsmodul]]

MsgDialog

2017-10-23T13:32:56Z

Binford6000: /* TelegramBot: Inline Keyboard verwenden */

{{Infobox Modul
|ModPurpose=Dialoge für Sofortnachrichten über TelegramBot, Jabber und WhatsApp
|ModType=d
|ModForumArea=Frontends
|ModTechName=76_msgDialog.pm
|ModOwner={{Link2FU|4106|igami}}
}}

== Zielsetzung ==
Eine zentrale Anforderung einer modernen Haus-Automation ist die Steuerung von unterwegs. Mittlerweile nutzt fast jeder einen oder mehrere Messenger Dienste. Da liegt es doch nahe, diese Messenger Dienste für die Kommunikation mit FHEM zu nutzen.
Mit msgDialog ist es jetzt möglich, Dialoge für Sofortnachrichten über [[TelegramBot]], [[Jabber]] und [[yowsup]] (WhatsApp) zu definieren. Dabei können die einzelnen Dialoge für unterschiedliche Nutzer berechtigt werden.
Die grundlegende Bedienung wird in diesem '''[https://youtu.be/yiCOTeR1YVQ Video]''' am Beispiel von TelegramBot gezeigt.

== Einbindung in FHEM ==

=== Voraussetzungen ===
Für dieses Modul wird das Perl JSON Modul benötigt. Auf einem Debian-basierten System (z.B RaspberryPI o.ä.) kann man das mit dem folgenden Befehl installieren:
<pre>
sudo apt-get install libjson-perl
</pre>

=== Hinweise ===

*Telegram: Es kann notwendig sein, dass im TelegramBot das Attribut "utf8specials" auf "1" gesetzt werden muss. Damit werden Nachrichten mit Umlauten korrekt gesendet. Beim msg-Befehl kann der TelegramBot_MTYPE angegeben werden. Die Vorgabe ist "message". Durch den Wert "queryInline" lässt sich ein inline Keyboard erzeugen (siehe unten).

*Jabber: Beim msg Befehl kann der Jabber_MTYPE angegeben werden. Die Vorgabe ist leer. Durch den Wert "otr" lässt sich eine OTR-Nachricht versenden.

*WhatsApp (yowsup): Bisher konnten noch keine Erfahrungen gemacht werden.

=== msgDialog und ROOMATE ===

Für jeden Dialog kann festgelegt werden, welche Person(en) dazu berechtigt ist. Dazu sind Geräte vom Typ ROOMMATE oder GUEST mit definiertem msgContactPush Attribut erforderlich. Es ist darauf zu achten, dass das Reading "fhemMsgRcvPush" ein Event erzeugt.

=== Definition des msgConfig-Device ===

Als nächstes benötigt man ein definiertes msgConfig device:

<pre>
defmod myMsgConfig msgConfig
attr myMsgConfig msgDialog_evalSpecials me=<Aktivierungswort bzw. -Nachricht>
TelegramBot=<Name des TelegramBot-device>
attr myMsgConfig msgContactPush TelegramBot
attr myMsgConfig room msg
</pre>

Falls bereits vorhanden müssen, natürlich nur die fehlenden Attribute gesetzt werden.

=== Definition des metaDialogs ===

Zur Auflistung aller berechtigten Dialoge dient - was sonst - ein Dialog!

<pre>
defmod meta_Dialog msgDialog {\
"%me%": {\
"match": "\/?(start|%me%)",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"{return('(' . join(') (', sort(split('\n', fhem('get TYPE=msgDialog:FILTER=NAME!=$SELF:FILTER=allowed=.*($recipient|everyone).* trigger')))) . ') ')}",\
"(abbrechen) ",\
"Ich kann folgendes für dich tun:"\
]\
},\
"abbrechen": {\
"match": "\/?abbrechen",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"(%me%) ",\
"Dialog abgebrochen."\
] \
},\
"beenden": {\
"match": "\/?beenden",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"(%me%) ",\
"Dialog beendet."\
]\
}\
}

attr meta_Dialog DbLogExclude .*
attr meta_Dialog allowed everyone
attr meta_Dialog room msg
</pre>

=== Definition beliebiger Dialoge ===

Aufgrund der Komplexität eines Dialogs mit JSON ist es am praktikabelsten, zunächst einen leeren Dialog zu definieren:
<pre>
define <name> msgDialog {}
</pre>

Anschließend kann die DEF in der Detail-Ansicht des Dialog-Device bearbeitet werden. Jeder Dialog basiert auf der folgenden Struktur von einfach bis komplex.

<pre>
{
"<TRIGGER>": {
"match": "<regex>",
"setOnly": (true|false),
"commands": "(fhem command|{perl code})",
"message": [
"{perl code}",
"text"
],
"<NEXT TRIGGER 1>": {
...
},
"<NEXT TRIGGER 2>": {
...
}
}
}
</pre>

Um den JSON-Teil der Dialoge zu testen, empfiehlt sich ein Besuch auf https://jsonlint.com/
Hier kann der selbst geschriebene JSON-Code validiert werden.

*TRIGGER: Kann ein beliebiger Text sein. Es wird geprüft ob die eingehende Nachricht damit übereinstimmt. Falls ja, wird der Dialog an dieser Stelle fortgesetzt.

*match: Wenn nicht nur genau eine Nachricht zugelassen werden soll, kann noch eine regex angegeben werden. Die regex muss auf die gesamte eingehnde Nachricht zutreffen.

*setOnly: Kann optional auf true oder false gestellt werden. In beiden fällen wird der TRIGGER dann nicht bei "get <name> trigger" zurück gegeben.
Wenn setOnly auf "true" gestellt wird, kann der Dialog an dieser Stelle nicht durch eingehende Nachrichten ausgelöst werden, sondern nur über "get <name> say TRIGGER". Dies kann dazu genutzt werden um einen Dialog aus FHEM heraus zu initiieren.

*commands: Kann einen einzelnen oder mehrere Befehle enthalten:
<pre>
"commands":
"single command"
"commands": [
"command 1",
"command 2",
"{perl command}"
]
</pre>

*message: Kann einen einzelnen oder mehrere Textte enthalten die mit einen Zeilenumbruch verbunden werden:
<pre>
"message": "text"
</pre>
<pre>
"message": [
"text 1",
"text 2",
"{return from perl command}"
]
</pre>

Bei mehrstufigen Dialogen wird diese Struktur ineinander verschachtelt angegeben.
Es werden Variablen und Platzhalter, welche unter dem Attribut evalSpecials definiert werden, ausgewertet.
=== Variablen ===
*$SELF: Eigenname des msgDialog
*$message: eingegangene Nachricht
*$recipient: Name des Dialogpartners

=== set ===
*reset: Setzt den Dialog für alle Benutzer zurück.
*say [@<recipient1>[,<recipient2>,...]] <TRIGGER>[|<NEXT TRIGGER>|...]: Der Dialog wird für alle angegeben Empänger an der angegeben Stelle fortgeführt. Sind keine Empfänger angegeben wird der Dialog für alle unter dem Attribut allowed angegebenen Empfänger fortgeführt.
*updateAllowed: Aktualisiert die Auswahl für das Attribut allowed.

=== get ===
*trigger: Listet alle TRIGGER der ersten Ebene auf bei denen nicht setOnly angegeben ist.

=== ATTRIBUTE ===
*allowed: Liste mit allen RESIDENTS und ROOMMATE die für diesen Dialog berechtigt sind.
*disable: [0|1] Dialog ist aktiviert|deaktiviert.
*disabledForIntervals: HH:MM-HH:MM HH:MM-HH-MM ...
*evalSpecials: key1=value1 key2=value2 ...Leerzeichen getrennte Liste von Name=Wert Paaren. Wert kann Leerzeichen enthalten, falls es in "" oder {} eingeschlossen ist. Wert wird als perl-Ausdruck ausgewertet, falls es in {} eingeschlossen ist. In der DEF werden %Name% Zeichenketten durch den zugehörigen Wert ersetzt. Dieses Attribut ist als "msgDialog_evalSpecials" im msgConfig Gerät vorhanden. Wenn der selbe Name im msgConfig und msgDialog definiert wurde, wird der Wert aus msgDialog verwendet.
*msgCommand <command>: Befehl der zum Versenden einer Nachricht verwendet wird. Die Vorgabe ist "msg push \@$recipients $message" Dieses Attribut ist als "msgDialog_msgCommand" im msgConfig Gerät vorhanden.

=== READINGS ===
*$recipient_history: Durch | getrennte Liste von TRIGGER um den aktuellen Zustand des Dialogs zu sichern. Für jeden Dialogpartner wird ein Reading angelegt. Wenn der Dialog beendet ist wird das Reading zurückgesetzt.

== Beispiele ==

==== Programmierung der Waschmaschine ====
Das ist ein Beispiel zur Programmierung einer Waschmaschine wie auch oben im Video zu sehen:
<pre>
defmod Waschmaschine_Dialog msgDialog { "Waschmaschine": {\
"message": [\
"{return('(Zeitprogramm stoppen) ') if(ReadingsVal('%controlUnit%', 'controlMode', '') eq 'auto')}",\
"{return('(programmieren) ') if(ReadingsVal('%actor%', 'state', '') ne 'on')}",\
"{return('(einschalten) ') if(ReadingsVal('%actor%', 'state', '') ne 'on')}",\
"(Verlaufsdiagramm) ",\
"(abbrechen) ",\
"{return('Waschmaschine: ' . (ReadingsVal('%actor%', 'state', '') eq 'on' ? 'eingeschaltet' : 'ausgeschaltet'))}",\
"{return('Modus: ' . (ReadingsVal('%controlUnit%', 'controlMode', '') eq 'auto' ? 'Automatik' : 'Manuell (' . ReadingsVal('%controlUnit%', 'time', '') . ')'))}"\
],\
"Zeitprogramm stoppen": {\
"commands": "set %controlUnit% controlMode manual",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Das Zeitprogramm wurde gestoppt."\
]\
},\
"programmieren": {\
"message": [\
"(bestätigen|zurück|abbrechen) ",\
"( 00:00 | 00:15 | 00:30 | 00:45 ) ",\
"( 01:00 | 01:15 | 01:30 | 01:45 ) ",\
"( 02:00 | 02:15 | 02:30 | 02:45 ) ",\
"( 03:00 | 03:15 | 03:30 | 03:45 ) ",\
"( 04:00 | 04:15 | 04:30 | 04:45 ) ",\
"( 05:00 | 05:15 | 05:30 | 05:45 ) ",\
"( 06:00 | 06:15 | 06:30 | 06:45 ) ",\
"( 07:00 | 07:15 | 07:30 | 07:45 ) ",\
"( 08:00 | 08:15 | 08:30 | 08:45 ) ",\
"( 09:00 | 09:15 | 09:30 | 09:45 ) ",\
"( 10:00 | 10:15 | 10:30 | 10:45 ) ",\
"( 11:00 | 11:15 | 11:30 | 11:45 ) ",\
"( 12:00 | 12:15 | 12:30 | 12:45 ) ",\
"( 13:00 | 13:15 | 13:30 | 13:45 ) ",\
"( 14:00 | 14:15 | 14:30 | 14:45 ) ",\
"( 15:00 | 15:15 | 15:30 | 15:45 ) ",\
"( 16:00 | 16:15 | 16:30 | 16:45 ) ",\
"( 17:00 | 17:15 | 17:30 | 17:45 ) ",\
"( 18:00 | 18:15 | 18:30 | 18:45 ) ",\
"( 19:00 | 19:15 | 19:30 | 19:45 ) ",\
"( 20:00 | 20:15 | 20:30 | 20:45 ) ",\
"( 21:00 | 21:15 | 21:30 | 21:45 ) ",\
"( 22:00 | 22:15 | 22:30 | 22:45 ) ",\
"( 23:00 | 23:15 | 23:30 | 23:45 ) ",\
"Wann soll die Wäsche fertig sein?",\
"Bitte Uhrzeit in HH:MM angeben.",\
"Aktuell ist [%controlUnit%:time] Uhr eingestellt."\
],\
"Uhrzeit": {\
"match": " ?([0-1][0-9]|2[0-3]):[0-5][0-9] ?",\
"commands": [\
"set %controlUnit% time $message",\
"set $SELF say @$recipient Waschmaschine|programmieren|bestätigen"\
]\
},\
"bestätigen": {\
"commands": "set %controlUnit% controlMode auto",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Das Zeitprogramm wurde eingestellt.",\
"Die Wäsche wird voraussichtlich um [%controlUnit%:time] Uhr fertig sein.",\
"Bitte die Waschmaschine vorbereiten."\
]\
}\
},\
"einschalten": {\
"commands": [\
"set %controlUnit% controlMode manual",\
"set %actor% on"\
]\
},\
"Verlaufsdiagramm": {\
"commands": "set %TelegramBot% cmdSend {plotAsPng('%plot%')}",\
"message": "TelegramBot_MTYPE=queryInline (%me%) $message"\
}\
},\
"auto": {\
"setOnly": true,\
"commands": [\
"set %actor% on",\
"set %controlUnit% controlMode manual"\
],\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine wurde automatisch eingeschaltet."\
]\
},\
"manual": {\
"setOnly": true,\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine wurde manuell eingeschaltet."\
]\
},\
"done": {\
"setOnly": true,\
"commands": "set %actor% off",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine ist fertig."\
]\
}\
}
attr Waschmaschine_Dialog evalSpecials actor=HM_2C10D8_Sw\
controlUnit=Waschkeller_washer_controlUnit\
plot=Waschkeller_washer_SVG
</pre>

== TelegramBot: Inline Keyboard verwenden==

In Telegram gibt es die Möglichkeit die Art des Keyboards zu ändern. Links das normale Keyboard, rechts das Inline Keyboard.

[[Datei:76msgDialog menu.png|Normales Keyboard]] [[Datei:76msgDialog menu inline.PNG|Inline Keyboard]]

In diesem '''[https://youtu.be/oRDy2918mVI Video]''' wird Telegram mit einem Inline Keyboard verwendet.

Um eine Nachricht bei Telegram zu verändern, gibt es den Befehl "queryEditInline".
Dafür wird die MsgId von der Nachricht benötigt. Das erledigt ein notify, welches die msgId pro Peer abspeichert:

<pre>
defmod sentMsgIdByPeerId notify .+:sentMsgId.+ {\
return unless($TYPE eq "TelegramBot");;\
\
my $dev_hash = $defs{$NAME};;\
my $sentMsgId = ReadingsVal($NAME, "sentMsgId", "");;\
my $sentMsgPeerId = ReadingsVal($NAME, "sentMsgPeerId", "");;\
my ($contact) = devspec2array("TYPE=(ROOMMATE|GUEST):FILTER=msgContactPush=.*$sentMsgPeerId.*");;\
\
readingsSingleUpdate($dev_hash, "$contact\_sentMsgId", $sentMsgId, 1);;\
}
attr sentMsgIdByPeerId devStateIcon {ReadingsVal($name, "state", "inactive") eq "active" ? ".*:ios-on-blue:inactive" : ".*:ios-off:active"}
attr sentMsgIdByPeerId icon audio_mic
attr sentMsgIdByPeerId room msg
</pre>

Danach wird der Message-Befehl von
<pre>
set <TelegramBot> message
</pre>
auf
<pre>
set <TelegramBot> queryEditInline
</pre>
geändert. Dafür wird ein [[cmdalias]] verwendet:

<pre>
defmod message2queryEditInline cmdalias set .+ message (.|\n)+ AS {\
my ($NAME, $cmd, $message) = split(/[\s]+/, $EVENT, 3);;\
my $TYPE = InternalVal($NAME, "TYPE", "");;\
(my $recipient, $message) = ($message =~ m/(@\S+)? (.+)/s);;\
\
if($TYPE eq "TelegramBot" && $recipient){\
my ($contact) = devspec2array("TYPE=(ROOMMATE|GUEST):FILTER=msgContactPush=.*$recipient.*");;\
my $sentMsgId = ReadingsVal($NAME, "$contact\_sentMsgId", "");;\
\
if($sentMsgId ne ""){\
fhem("set $NAME queryEditInline $sentMsgId $recipient $message");;\
}\
else{\
fhem("set $NAME queryInline $recipient $message");;\
}\
}\
else{\
fhem("set $EVENT");;\
}\
}
attr message2queryEditInline room msg
</pre>

Um wieder zurück zum normalen Keyboard zu gelangen genügt es, das notify und den cmdAlias zu deaktivieren.
Das kann komfortabel über ein notify und einen dummy erledigt werden:
<pre>
defmod inline_normal.NOT notify inline_normal.DUM:.* {\
if ("$EVENT" =~ "on") {\
fhem "set sentMsgIdByPeerId active;; attr message2queryEditInline disable 0";;\
} \
elsif ("$EVENT" =~ "off") {\
fhem "set sentMsgIdByPeerId inactive;; attr message2queryEditInline disable 1";;\
}\
}
</pre>

Weitere Infos zum Thema Inline Keyboard sind in der Antwort #10 im Forum zu finden (siehe Link unten).

== Links ==
* Thread über das Modul im {{Link2Forum|Topic=77297|LinkText=FHEM Forum}}

[[Kategorie:Gerätemodul]]

MsgDialog

2017-10-23T13:28:02Z

Binford6000: /* TelegramBot: Inline Keyboard verwenden */

{{Infobox Modul
|ModPurpose=Dialoge für Sofortnachrichten über TelegramBot, Jabber und WhatsApp
|ModType=d
|ModForumArea=Frontends
|ModTechName=76_msgDialog.pm
|ModOwner={{Link2FU|4106|igami}}
}}

== Zielsetzung ==
Eine zentrale Anforderung einer modernen Haus-Automation ist die Steuerung von unterwegs. Mittlerweile nutzt fast jeder einen oder mehrere Messenger Dienste. Da liegt es doch nahe, diese Messenger Dienste für die Kommunikation mit FHEM zu nutzen.
Mit msgDialog ist es jetzt möglich, Dialoge für Sofortnachrichten über [[TelegramBot]], [[Jabber]] und [[yowsup]] (WhatsApp) zu definieren. Dabei können die einzelnen Dialoge für unterschiedliche Nutzer berechtigt werden.
Die grundlegende Bedienung wird in diesem '''[https://youtu.be/yiCOTeR1YVQ Video]''' am Beispiel von TelegramBot gezeigt.

== Einbindung in FHEM ==

=== Voraussetzungen ===
Für dieses Modul wird das Perl JSON Modul benötigt. Auf einem Debian-basierten System (z.B RaspberryPI o.ä.) kann man das mit dem folgenden Befehl installieren:
<pre>
sudo apt-get install libjson-perl
</pre>

=== Hinweise ===

*Telegram: Es kann notwendig sein, dass im TelegramBot das Attribut "utf8specials" auf "1" gesetzt werden muss. Damit werden Nachrichten mit Umlauten korrekt gesendet. Beim msg-Befehl kann der TelegramBot_MTYPE angegeben werden. Die Vorgabe ist "message". Durch den Wert "queryInline" lässt sich ein inline Keyboard erzeugen (siehe unten).

*Jabber: Beim msg Befehl kann der Jabber_MTYPE angegeben werden. Die Vorgabe ist leer. Durch den Wert "otr" lässt sich eine OTR-Nachricht versenden.

*WhatsApp (yowsup): Bisher konnten noch keine Erfahrungen gemacht werden.

=== msgDialog und ROOMATE ===

Für jeden Dialog kann festgelegt werden, welche Person(en) dazu berechtigt ist. Dazu sind Geräte vom Typ ROOMMATE oder GUEST mit definiertem msgContactPush Attribut erforderlich. Es ist darauf zu achten, dass das Reading "fhemMsgRcvPush" ein Event erzeugt.

=== Definition des msgConfig-Device ===

Als nächstes benötigt man ein definiertes msgConfig device:

<pre>
defmod myMsgConfig msgConfig
attr myMsgConfig msgDialog_evalSpecials me=<Aktivierungswort bzw. -Nachricht>
TelegramBot=<Name des TelegramBot-device>
attr myMsgConfig msgContactPush TelegramBot
attr myMsgConfig room msg
</pre>

Falls bereits vorhanden müssen, natürlich nur die fehlenden Attribute gesetzt werden.

=== Definition des metaDialogs ===

Zur Auflistung aller berechtigten Dialoge dient - was sonst - ein Dialog!

<pre>
defmod meta_Dialog msgDialog {\
"%me%": {\
"match": "\/?(start|%me%)",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"{return('(' . join(') (', sort(split('\n', fhem('get TYPE=msgDialog:FILTER=NAME!=$SELF:FILTER=allowed=.*($recipient|everyone).* trigger')))) . ') ')}",\
"(abbrechen) ",\
"Ich kann folgendes für dich tun:"\
]\
},\
"abbrechen": {\
"match": "\/?abbrechen",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"(%me%) ",\
"Dialog abgebrochen."\
] \
},\
"beenden": {\
"match": "\/?beenden",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"(%me%) ",\
"Dialog beendet."\
]\
}\
}

attr meta_Dialog DbLogExclude .*
attr meta_Dialog allowed everyone
attr meta_Dialog room msg
</pre>

=== Definition beliebiger Dialoge ===

Aufgrund der Komplexität eines Dialogs mit JSON ist es am praktikabelsten, zunächst einen leeren Dialog zu definieren:
<pre>
define <name> msgDialog {}
</pre>

Anschließend kann die DEF in der Detail-Ansicht des Dialog-Device bearbeitet werden. Jeder Dialog basiert auf der folgenden Struktur von einfach bis komplex.

<pre>
{
"<TRIGGER>": {
"match": "<regex>",
"setOnly": (true|false),
"commands": "(fhem command|{perl code})",
"message": [
"{perl code}",
"text"
],
"<NEXT TRIGGER 1>": {
...
},
"<NEXT TRIGGER 2>": {
...
}
}
}
</pre>

Um den JSON-Teil der Dialoge zu testen, empfiehlt sich ein Besuch auf https://jsonlint.com/
Hier kann der selbst geschriebene JSON-Code validiert werden.

*TRIGGER: Kann ein beliebiger Text sein. Es wird geprüft ob die eingehende Nachricht damit übereinstimmt. Falls ja, wird der Dialog an dieser Stelle fortgesetzt.

*match: Wenn nicht nur genau eine Nachricht zugelassen werden soll, kann noch eine regex angegeben werden. Die regex muss auf die gesamte eingehnde Nachricht zutreffen.

*setOnly: Kann optional auf true oder false gestellt werden. In beiden fällen wird der TRIGGER dann nicht bei "get <name> trigger" zurück gegeben.
Wenn setOnly auf "true" gestellt wird, kann der Dialog an dieser Stelle nicht durch eingehende Nachrichten ausgelöst werden, sondern nur über "get <name> say TRIGGER". Dies kann dazu genutzt werden um einen Dialog aus FHEM heraus zu initiieren.

*commands: Kann einen einzelnen oder mehrere Befehle enthalten:
<pre>
"commands":
"single command"
"commands": [
"command 1",
"command 2",
"{perl command}"
]
</pre>

*message: Kann einen einzelnen oder mehrere Textte enthalten die mit einen Zeilenumbruch verbunden werden:
<pre>
"message": "text"
</pre>
<pre>
"message": [
"text 1",
"text 2",
"{return from perl command}"
]
</pre>

Bei mehrstufigen Dialogen wird diese Struktur ineinander verschachtelt angegeben.
Es werden Variablen und Platzhalter, welche unter dem Attribut evalSpecials definiert werden, ausgewertet.
=== Variablen ===
*$SELF: Eigenname des msgDialog
*$message: eingegangene Nachricht
*$recipient: Name des Dialogpartners

=== set ===
*reset: Setzt den Dialog für alle Benutzer zurück.
*say [@<recipient1>[,<recipient2>,...]] <TRIGGER>[|<NEXT TRIGGER>|...]: Der Dialog wird für alle angegeben Empänger an der angegeben Stelle fortgeführt. Sind keine Empfänger angegeben wird der Dialog für alle unter dem Attribut allowed angegebenen Empfänger fortgeführt.
*updateAllowed: Aktualisiert die Auswahl für das Attribut allowed.

=== get ===
*trigger: Listet alle TRIGGER der ersten Ebene auf bei denen nicht setOnly angegeben ist.

=== ATTRIBUTE ===
*allowed: Liste mit allen RESIDENTS und ROOMMATE die für diesen Dialog berechtigt sind.
*disable: [0|1] Dialog ist aktiviert|deaktiviert.
*disabledForIntervals: HH:MM-HH:MM HH:MM-HH-MM ...
*evalSpecials: key1=value1 key2=value2 ...Leerzeichen getrennte Liste von Name=Wert Paaren. Wert kann Leerzeichen enthalten, falls es in "" oder {} eingeschlossen ist. Wert wird als perl-Ausdruck ausgewertet, falls es in {} eingeschlossen ist. In der DEF werden %Name% Zeichenketten durch den zugehörigen Wert ersetzt. Dieses Attribut ist als "msgDialog_evalSpecials" im msgConfig Gerät vorhanden. Wenn der selbe Name im msgConfig und msgDialog definiert wurde, wird der Wert aus msgDialog verwendet.
*msgCommand <command>: Befehl der zum Versenden einer Nachricht verwendet wird. Die Vorgabe ist "msg push \@$recipients $message" Dieses Attribut ist als "msgDialog_msgCommand" im msgConfig Gerät vorhanden.

=== READINGS ===
*$recipient_history: Durch | getrennte Liste von TRIGGER um den aktuellen Zustand des Dialogs zu sichern. Für jeden Dialogpartner wird ein Reading angelegt. Wenn der Dialog beendet ist wird das Reading zurückgesetzt.

== Beispiele ==

==== Programmierung der Waschmaschine ====
Das ist ein Beispiel zur Programmierung einer Waschmaschine wie auch oben im Video zu sehen:
<pre>
defmod Waschmaschine_Dialog msgDialog { "Waschmaschine": {\
"message": [\
"{return('(Zeitprogramm stoppen) ') if(ReadingsVal('%controlUnit%', 'controlMode', '') eq 'auto')}",\
"{return('(programmieren) ') if(ReadingsVal('%actor%', 'state', '') ne 'on')}",\
"{return('(einschalten) ') if(ReadingsVal('%actor%', 'state', '') ne 'on')}",\
"(Verlaufsdiagramm) ",\
"(abbrechen) ",\
"{return('Waschmaschine: ' . (ReadingsVal('%actor%', 'state', '') eq 'on' ? 'eingeschaltet' : 'ausgeschaltet'))}",\
"{return('Modus: ' . (ReadingsVal('%controlUnit%', 'controlMode', '') eq 'auto' ? 'Automatik' : 'Manuell (' . ReadingsVal('%controlUnit%', 'time', '') . ')'))}"\
],\
"Zeitprogramm stoppen": {\
"commands": "set %controlUnit% controlMode manual",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Das Zeitprogramm wurde gestoppt."\
]\
},\
"programmieren": {\
"message": [\
"(bestätigen|zurück|abbrechen) ",\
"( 00:00 | 00:15 | 00:30 | 00:45 ) ",\
"( 01:00 | 01:15 | 01:30 | 01:45 ) ",\
"( 02:00 | 02:15 | 02:30 | 02:45 ) ",\
"( 03:00 | 03:15 | 03:30 | 03:45 ) ",\
"( 04:00 | 04:15 | 04:30 | 04:45 ) ",\
"( 05:00 | 05:15 | 05:30 | 05:45 ) ",\
"( 06:00 | 06:15 | 06:30 | 06:45 ) ",\
"( 07:00 | 07:15 | 07:30 | 07:45 ) ",\
"( 08:00 | 08:15 | 08:30 | 08:45 ) ",\
"( 09:00 | 09:15 | 09:30 | 09:45 ) ",\
"( 10:00 | 10:15 | 10:30 | 10:45 ) ",\
"( 11:00 | 11:15 | 11:30 | 11:45 ) ",\
"( 12:00 | 12:15 | 12:30 | 12:45 ) ",\
"( 13:00 | 13:15 | 13:30 | 13:45 ) ",\
"( 14:00 | 14:15 | 14:30 | 14:45 ) ",\
"( 15:00 | 15:15 | 15:30 | 15:45 ) ",\
"( 16:00 | 16:15 | 16:30 | 16:45 ) ",\
"( 17:00 | 17:15 | 17:30 | 17:45 ) ",\
"( 18:00 | 18:15 | 18:30 | 18:45 ) ",\
"( 19:00 | 19:15 | 19:30 | 19:45 ) ",\
"( 20:00 | 20:15 | 20:30 | 20:45 ) ",\
"( 21:00 | 21:15 | 21:30 | 21:45 ) ",\
"( 22:00 | 22:15 | 22:30 | 22:45 ) ",\
"( 23:00 | 23:15 | 23:30 | 23:45 ) ",\
"Wann soll die Wäsche fertig sein?",\
"Bitte Uhrzeit in HH:MM angeben.",\
"Aktuell ist [%controlUnit%:time] Uhr eingestellt."\
],\
"Uhrzeit": {\
"match": " ?([0-1][0-9]|2[0-3]):[0-5][0-9] ?",\
"commands": [\
"set %controlUnit% time $message",\
"set $SELF say @$recipient Waschmaschine|programmieren|bestätigen"\
]\
},\
"bestätigen": {\
"commands": "set %controlUnit% controlMode auto",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Das Zeitprogramm wurde eingestellt.",\
"Die Wäsche wird voraussichtlich um [%controlUnit%:time] Uhr fertig sein.",\
"Bitte die Waschmaschine vorbereiten."\
]\
}\
},\
"einschalten": {\
"commands": [\
"set %controlUnit% controlMode manual",\
"set %actor% on"\
]\
},\
"Verlaufsdiagramm": {\
"commands": "set %TelegramBot% cmdSend {plotAsPng('%plot%')}",\
"message": "TelegramBot_MTYPE=queryInline (%me%) $message"\
}\
},\
"auto": {\
"setOnly": true,\
"commands": [\
"set %actor% on",\
"set %controlUnit% controlMode manual"\
],\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine wurde automatisch eingeschaltet."\
]\
},\
"manual": {\
"setOnly": true,\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine wurde manuell eingeschaltet."\
]\
},\
"done": {\
"setOnly": true,\
"commands": "set %actor% off",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine ist fertig."\
]\
}\
}
attr Waschmaschine_Dialog evalSpecials actor=HM_2C10D8_Sw\
controlUnit=Waschkeller_washer_controlUnit\
plot=Waschkeller_washer_SVG
</pre>

== TelegramBot: Inline Keyboard verwenden==

In Telegram gibt es die Möglichkeit die Art des Keyboards zu ändern. Links das normale Keyboard, rechts das Inline Keyboard.

[[Datei:76msgDialog menu.png|Normales Keyboard]] [[Datei:76msgDialog menu inline.PNG|Inline Keyboard]]

In diesem '''[https://youtu.be/oRDy2918mVI Video]''' wird Telegram mit einem Inline Keyboard verwendet.

Um eine Nachricht bei Telegram zu verändern, gibt es den Befehl "queryEditInline".
Dafür wird die MsgId von der Nachricht benötigt. Das erledigt ein notify, welches die msgId pro Peer abspeichert:

<pre>
defmod sentMsgIdByPeerId notify .+:sentMsgId.+ {\
return unless($TYPE eq "TelegramBot");;\
\
my $dev_hash = $defs{$NAME};;\
my $sentMsgId = ReadingsVal($NAME, "sentMsgId", "");;\
my $sentMsgPeerId = ReadingsVal($NAME, "sentMsgPeerId", "");;\
my ($contact) = devspec2array("TYPE=(ROOMMATE|GUEST):FILTER=msgContactPush=.*$sentMsgPeerId.*");;\
\
readingsSingleUpdate($dev_hash, "$contact\_sentMsgId", $sentMsgId, 1);;\
}
attr sentMsgIdByPeerId devStateIcon {ReadingsVal($name, "state", "inactive") eq "active" ? ".*:ios-on-blue:inactive" : ".*:ios-off:active"}
attr sentMsgIdByPeerId icon audio_mic
attr sentMsgIdByPeerId room msg
</pre>

Danach wird der Message-Befehl von
<pre>
set <TelegramBot> message
</pre>
auf
<pre>
set <TelegramBot> queryEditInline
</pre>
geändert. Dafür wird ein [[cmdalias]] verwendet:

<pre>
defmod message2queryEditInline cmdalias set .+ message (.|\n)+ AS {\
my ($NAME, $cmd, $message) = split(/[\s]+/, $EVENT, 3);;\
my $TYPE = InternalVal($NAME, "TYPE", "");;\
(my $recipient, $message) = ($message =~ m/(@\S+)? (.+)/s);;\
\
if($TYPE eq "TelegramBot" && $recipient){\
my ($contact) = devspec2array("TYPE=(ROOMMATE|GUEST):FILTER=msgContactPush=.*$recipient.*");;\
my $sentMsgId = ReadingsVal($NAME, "$contact\_sentMsgId", "");;\
\
if($sentMsgId ne ""){\
fhem("set $NAME queryEditInline $sentMsgId $recipient $message");;\
}\
else{\
fhem("set $NAME queryInline $recipient $message");;\
}\
}\
else{\
fhem("set $EVENT");;\
}\
}
attr message2queryEditInline room msg
</pre>

Um wieder zurück zum normalen Keyboard zu gelangen genügt es, das notify und den cmdAlias zu deaktivieren.
Hier noch ein kleines notify, welches über einen dummy geschaltet werden kann:
<pre>
defmod inline_normal.NOT notify inline_normal.DUM:.* {\
if ("$EVENT" =~ "on") {\
fhem "set sentMsgIdByPeerId active;; attr message2queryEditInline disable 0";;\
} \
elsif ("$EVENT" =~ "off") {\
fhem "set sentMsgIdByPeerId inactive;; attr message2queryEditInline disable 1";;\
}\
}
</pre>

Weitere Infos zum Thema Inline Keyboard sind in der Antwort #10 im Forum zu finden (siehe Link unten).

== Links ==
* Thread über das Modul im {{Link2Forum|Topic=77297|LinkText=FHEM Forum}}

[[Kategorie:Gerätemodul]]

MsgDialog

2017-10-23T13:22:24Z

Binford6000:

{{Infobox Modul
|ModPurpose=Dialoge für Sofortnachrichten über TelegramBot, Jabber und WhatsApp
|ModType=d
|ModForumArea=Frontends
|ModTechName=76_msgDialog.pm
|ModOwner={{Link2FU|4106|igami}}
}}

== Zielsetzung ==
Eine zentrale Anforderung einer modernen Haus-Automation ist die Steuerung von unterwegs. Mittlerweile nutzt fast jeder einen oder mehrere Messenger Dienste. Da liegt es doch nahe, diese Messenger Dienste für die Kommunikation mit FHEM zu nutzen.
Mit msgDialog ist es jetzt möglich, Dialoge für Sofortnachrichten über [[TelegramBot]], [[Jabber]] und [[yowsup]] (WhatsApp) zu definieren. Dabei können die einzelnen Dialoge für unterschiedliche Nutzer berechtigt werden.
Die grundlegende Bedienung wird in diesem '''[https://youtu.be/yiCOTeR1YVQ Video]''' am Beispiel von TelegramBot gezeigt.

== Einbindung in FHEM ==

=== Voraussetzungen ===
Für dieses Modul wird das Perl JSON Modul benötigt. Auf einem Debian-basierten System (z.B RaspberryPI o.ä.) kann man das mit dem folgenden Befehl installieren:
<pre>
sudo apt-get install libjson-perl
</pre>

=== Hinweise ===

*Telegram: Es kann notwendig sein, dass im TelegramBot das Attribut "utf8specials" auf "1" gesetzt werden muss. Damit werden Nachrichten mit Umlauten korrekt gesendet. Beim msg-Befehl kann der TelegramBot_MTYPE angegeben werden. Die Vorgabe ist "message". Durch den Wert "queryInline" lässt sich ein inline Keyboard erzeugen (siehe unten).

*Jabber: Beim msg Befehl kann der Jabber_MTYPE angegeben werden. Die Vorgabe ist leer. Durch den Wert "otr" lässt sich eine OTR-Nachricht versenden.

*WhatsApp (yowsup): Bisher konnten noch keine Erfahrungen gemacht werden.

=== msgDialog und ROOMATE ===

Für jeden Dialog kann festgelegt werden, welche Person(en) dazu berechtigt ist. Dazu sind Geräte vom Typ ROOMMATE oder GUEST mit definiertem msgContactPush Attribut erforderlich. Es ist darauf zu achten, dass das Reading "fhemMsgRcvPush" ein Event erzeugt.

=== Definition des msgConfig-Device ===

Als nächstes benötigt man ein definiertes msgConfig device:

<pre>
defmod myMsgConfig msgConfig
attr myMsgConfig msgDialog_evalSpecials me=<Aktivierungswort bzw. -Nachricht>
TelegramBot=<Name des TelegramBot-device>
attr myMsgConfig msgContactPush TelegramBot
attr myMsgConfig room msg
</pre>

Falls bereits vorhanden müssen, natürlich nur die fehlenden Attribute gesetzt werden.

=== Definition des metaDialogs ===

Zur Auflistung aller berechtigten Dialoge dient - was sonst - ein Dialog!

<pre>
defmod meta_Dialog msgDialog {\
"%me%": {\
"match": "\/?(start|%me%)",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"{return('(' . join(') (', sort(split('\n', fhem('get TYPE=msgDialog:FILTER=NAME!=$SELF:FILTER=allowed=.*($recipient|everyone).* trigger')))) . ') ')}",\
"(abbrechen) ",\
"Ich kann folgendes für dich tun:"\
]\
},\
"abbrechen": {\
"match": "\/?abbrechen",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"(%me%) ",\
"Dialog abgebrochen."\
] \
},\
"beenden": {\
"match": "\/?beenden",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"(%me%) ",\
"Dialog beendet."\
]\
}\
}

attr meta_Dialog DbLogExclude .*
attr meta_Dialog allowed everyone
attr meta_Dialog room msg
</pre>

=== Definition beliebiger Dialoge ===

Aufgrund der Komplexität eines Dialogs mit JSON ist es am praktikabelsten, zunächst einen leeren Dialog zu definieren:
<pre>
define <name> msgDialog {}
</pre>

Anschließend kann die DEF in der Detail-Ansicht des Dialog-Device bearbeitet werden. Jeder Dialog basiert auf der folgenden Struktur von einfach bis komplex.

<pre>
{
"<TRIGGER>": {
"match": "<regex>",
"setOnly": (true|false),
"commands": "(fhem command|{perl code})",
"message": [
"{perl code}",
"text"
],
"<NEXT TRIGGER 1>": {
...
},
"<NEXT TRIGGER 2>": {
...
}
}
}
</pre>

Um den JSON-Teil der Dialoge zu testen, empfiehlt sich ein Besuch auf https://jsonlint.com/
Hier kann der selbst geschriebene JSON-Code validiert werden.

*TRIGGER: Kann ein beliebiger Text sein. Es wird geprüft ob die eingehende Nachricht damit übereinstimmt. Falls ja, wird der Dialog an dieser Stelle fortgesetzt.

*match: Wenn nicht nur genau eine Nachricht zugelassen werden soll, kann noch eine regex angegeben werden. Die regex muss auf die gesamte eingehnde Nachricht zutreffen.

*setOnly: Kann optional auf true oder false gestellt werden. In beiden fällen wird der TRIGGER dann nicht bei "get <name> trigger" zurück gegeben.
Wenn setOnly auf "true" gestellt wird, kann der Dialog an dieser Stelle nicht durch eingehende Nachrichten ausgelöst werden, sondern nur über "get <name> say TRIGGER". Dies kann dazu genutzt werden um einen Dialog aus FHEM heraus zu initiieren.

*commands: Kann einen einzelnen oder mehrere Befehle enthalten:
<pre>
"commands":
"single command"
"commands": [
"command 1",
"command 2",
"{perl command}"
]
</pre>

*message: Kann einen einzelnen oder mehrere Textte enthalten die mit einen Zeilenumbruch verbunden werden:
<pre>
"message": "text"
</pre>
<pre>
"message": [
"text 1",
"text 2",
"{return from perl command}"
]
</pre>

Bei mehrstufigen Dialogen wird diese Struktur ineinander verschachtelt angegeben.
Es werden Variablen und Platzhalter, welche unter dem Attribut evalSpecials definiert werden, ausgewertet.
=== Variablen ===
*$SELF: Eigenname des msgDialog
*$message: eingegangene Nachricht
*$recipient: Name des Dialogpartners

=== set ===
*reset: Setzt den Dialog für alle Benutzer zurück.
*say [@<recipient1>[,<recipient2>,...]] <TRIGGER>[|<NEXT TRIGGER>|...]: Der Dialog wird für alle angegeben Empänger an der angegeben Stelle fortgeführt. Sind keine Empfänger angegeben wird der Dialog für alle unter dem Attribut allowed angegebenen Empfänger fortgeführt.
*updateAllowed: Aktualisiert die Auswahl für das Attribut allowed.

=== get ===
*trigger: Listet alle TRIGGER der ersten Ebene auf bei denen nicht setOnly angegeben ist.

=== ATTRIBUTE ===
*allowed: Liste mit allen RESIDENTS und ROOMMATE die für diesen Dialog berechtigt sind.
*disable: [0|1] Dialog ist aktiviert|deaktiviert.
*disabledForIntervals: HH:MM-HH:MM HH:MM-HH-MM ...
*evalSpecials: key1=value1 key2=value2 ...Leerzeichen getrennte Liste von Name=Wert Paaren. Wert kann Leerzeichen enthalten, falls es in "" oder {} eingeschlossen ist. Wert wird als perl-Ausdruck ausgewertet, falls es in {} eingeschlossen ist. In der DEF werden %Name% Zeichenketten durch den zugehörigen Wert ersetzt. Dieses Attribut ist als "msgDialog_evalSpecials" im msgConfig Gerät vorhanden. Wenn der selbe Name im msgConfig und msgDialog definiert wurde, wird der Wert aus msgDialog verwendet.
*msgCommand <command>: Befehl der zum Versenden einer Nachricht verwendet wird. Die Vorgabe ist "msg push \@$recipients $message" Dieses Attribut ist als "msgDialog_msgCommand" im msgConfig Gerät vorhanden.

=== READINGS ===
*$recipient_history: Durch | getrennte Liste von TRIGGER um den aktuellen Zustand des Dialogs zu sichern. Für jeden Dialogpartner wird ein Reading angelegt. Wenn der Dialog beendet ist wird das Reading zurückgesetzt.

== Beispiele ==

==== Programmierung der Waschmaschine ====
Das ist ein Beispiel zur Programmierung einer Waschmaschine wie auch oben im Video zu sehen:
<pre>
defmod Waschmaschine_Dialog msgDialog { "Waschmaschine": {\
"message": [\
"{return('(Zeitprogramm stoppen) ') if(ReadingsVal('%controlUnit%', 'controlMode', '') eq 'auto')}",\
"{return('(programmieren) ') if(ReadingsVal('%actor%', 'state', '') ne 'on')}",\
"{return('(einschalten) ') if(ReadingsVal('%actor%', 'state', '') ne 'on')}",\
"(Verlaufsdiagramm) ",\
"(abbrechen) ",\
"{return('Waschmaschine: ' . (ReadingsVal('%actor%', 'state', '') eq 'on' ? 'eingeschaltet' : 'ausgeschaltet'))}",\
"{return('Modus: ' . (ReadingsVal('%controlUnit%', 'controlMode', '') eq 'auto' ? 'Automatik' : 'Manuell (' . ReadingsVal('%controlUnit%', 'time', '') . ')'))}"\
],\
"Zeitprogramm stoppen": {\
"commands": "set %controlUnit% controlMode manual",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Das Zeitprogramm wurde gestoppt."\
]\
},\
"programmieren": {\
"message": [\
"(bestätigen|zurück|abbrechen) ",\
"( 00:00 | 00:15 | 00:30 | 00:45 ) ",\
"( 01:00 | 01:15 | 01:30 | 01:45 ) ",\
"( 02:00 | 02:15 | 02:30 | 02:45 ) ",\
"( 03:00 | 03:15 | 03:30 | 03:45 ) ",\
"( 04:00 | 04:15 | 04:30 | 04:45 ) ",\
"( 05:00 | 05:15 | 05:30 | 05:45 ) ",\
"( 06:00 | 06:15 | 06:30 | 06:45 ) ",\
"( 07:00 | 07:15 | 07:30 | 07:45 ) ",\
"( 08:00 | 08:15 | 08:30 | 08:45 ) ",\
"( 09:00 | 09:15 | 09:30 | 09:45 ) ",\
"( 10:00 | 10:15 | 10:30 | 10:45 ) ",\
"( 11:00 | 11:15 | 11:30 | 11:45 ) ",\
"( 12:00 | 12:15 | 12:30 | 12:45 ) ",\
"( 13:00 | 13:15 | 13:30 | 13:45 ) ",\
"( 14:00 | 14:15 | 14:30 | 14:45 ) ",\
"( 15:00 | 15:15 | 15:30 | 15:45 ) ",\
"( 16:00 | 16:15 | 16:30 | 16:45 ) ",\
"( 17:00 | 17:15 | 17:30 | 17:45 ) ",\
"( 18:00 | 18:15 | 18:30 | 18:45 ) ",\
"( 19:00 | 19:15 | 19:30 | 19:45 ) ",\
"( 20:00 | 20:15 | 20:30 | 20:45 ) ",\
"( 21:00 | 21:15 | 21:30 | 21:45 ) ",\
"( 22:00 | 22:15 | 22:30 | 22:45 ) ",\
"( 23:00 | 23:15 | 23:30 | 23:45 ) ",\
"Wann soll die Wäsche fertig sein?",\
"Bitte Uhrzeit in HH:MM angeben.",\
"Aktuell ist [%controlUnit%:time] Uhr eingestellt."\
],\
"Uhrzeit": {\
"match": " ?([0-1][0-9]|2[0-3]):[0-5][0-9] ?",\
"commands": [\
"set %controlUnit% time $message",\
"set $SELF say @$recipient Waschmaschine|programmieren|bestätigen"\
]\
},\
"bestätigen": {\
"commands": "set %controlUnit% controlMode auto",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Das Zeitprogramm wurde eingestellt.",\
"Die Wäsche wird voraussichtlich um [%controlUnit%:time] Uhr fertig sein.",\
"Bitte die Waschmaschine vorbereiten."\
]\
}\
},\
"einschalten": {\
"commands": [\
"set %controlUnit% controlMode manual",\
"set %actor% on"\
]\
},\
"Verlaufsdiagramm": {\
"commands": "set %TelegramBot% cmdSend {plotAsPng('%plot%')}",\
"message": "TelegramBot_MTYPE=queryInline (%me%) $message"\
}\
},\
"auto": {\
"setOnly": true,\
"commands": [\
"set %actor% on",\
"set %controlUnit% controlMode manual"\
],\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine wurde automatisch eingeschaltet."\
]\
},\
"manual": {\
"setOnly": true,\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine wurde manuell eingeschaltet."\
]\
},\
"done": {\
"setOnly": true,\
"commands": "set %actor% off",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine ist fertig."\
]\
}\
}
attr Waschmaschine_Dialog evalSpecials actor=HM_2C10D8_Sw\
controlUnit=Waschkeller_washer_controlUnit\
plot=Waschkeller_washer_SVG
</pre>

== TelegramBot: Inline Keyboard verwenden==

In Telegram gibt es die Möglichkeit die Art des Keyboards zu ändern. Links das normale Keyboard, rechts das Inline Keyboard.

[[Datei:76msgDialog menu.png]] [[Datei:76msgDialog menu inline.PNG]]

In diesem '''[https://youtu.be/oRDy2918mVI Video]''' wird Telegram mit einem Inline Keyboard verwendet.

Um eine Nachricht bei Telegram zu verändern, gibt es den Befehl "queryEditInline".
Dafür wird die MsgId von der Nachricht benötigt. Das erledigt ein notify, welches die msgId pro Peer abspeichert:

<pre>
defmod sentMsgIdByPeerId notify .+:sentMsgId.+ {\
return unless($TYPE eq "TelegramBot");;\
\
my $dev_hash = $defs{$NAME};;\
my $sentMsgId = ReadingsVal($NAME, "sentMsgId", "");;\
my $sentMsgPeerId = ReadingsVal($NAME, "sentMsgPeerId", "");;\
my ($contact) = devspec2array("TYPE=(ROOMMATE|GUEST):FILTER=msgContactPush=.*$sentMsgPeerId.*");;\
\
readingsSingleUpdate($dev_hash, "$contact\_sentMsgId", $sentMsgId, 1);;\
}
attr sentMsgIdByPeerId devStateIcon {ReadingsVal($name, "state", "inactive") eq "active" ? ".*:ios-on-blue:inactive" : ".*:ios-off:active"}
attr sentMsgIdByPeerId icon audio_mic
attr sentMsgIdByPeerId room msg
</pre>

Danach wird der Message-Befehl von
<pre>
set <TelegramBot> message
</pre>
auf
<pre>
set <TelegramBot> queryEditInline
</pre>
geändert. Dafür wird ein [[cmdalias]] verwendet:

<pre>
defmod message2queryEditInline cmdalias set .+ message (.|\n)+ AS {\
my ($NAME, $cmd, $message) = split(/[\s]+/, $EVENT, 3);;\
my $TYPE = InternalVal($NAME, "TYPE", "");;\
(my $recipient, $message) = ($message =~ m/(@\S+)? (.+)/s);;\
\
if($TYPE eq "TelegramBot" && $recipient){\
my ($contact) = devspec2array("TYPE=(ROOMMATE|GUEST):FILTER=msgContactPush=.*$recipient.*");;\
my $sentMsgId = ReadingsVal($NAME, "$contact\_sentMsgId", "");;\
\
if($sentMsgId ne ""){\
fhem("set $NAME queryEditInline $sentMsgId $recipient $message");;\
}\
else{\
fhem("set $NAME queryInline $recipient $message");;\
}\
}\
else{\
fhem("set $EVENT");;\
}\
}
attr message2queryEditInline room msg
</pre>

Um wieder zurück zum normalen Keyboard zu gelangen genügt es, das notify und den cmdAlias zu deaktivieren.
Hier noch ein kleines notify, welches über einen dummy geschaltet werden kann:
<pre>
defmod inline_normal.NOT notify inline_normal.DUM:.* {\
if ("$EVENT" =~ "on") {\
fhem "set sentMsgIdByPeerId active;; attr message2queryEditInline disable 0";;\
} \
elsif ("$EVENT" =~ "off") {\
fhem "set sentMsgIdByPeerId inactive;; attr message2queryEditInline disable 1";;\
}\
}
</pre>

Weitere Infos zum Thema Inline Keyboard sind in der Antwort #10 im Forum zu finden (siehe Link unten).

== Links ==
* Thread über das Modul im {{Link2Forum|Topic=77297|LinkText=FHEM Forum}}

[[Kategorie:Gerätemodul]]

MsgDialog

2017-10-23T13:07:24Z

Binford6000:

{{Infobox Modul
|ModPurpose=Dialoge für Sofortnachrichten über TelegramBot, Jabber und WhatsApp
|ModType=d
|ModForumArea=Frontends
|ModTechName=76_msgDialog.pm
|ModOwner={{Link2FU|4106|igami}}
}}

== Zielsetzung ==
Eine zentrale Anforderung einer modernen Haus-Automation ist die Steuerung von unterwegs. Mittlerweile nutzt fast jeder einen oder mehrere Messenger Dienste. Da liegt es doch nahe, diese Messenger Dienste für die Kommunikation mit FHEM zu nutzen.
Mit msgDialog ist es jetzt möglich, Dialoge für Sofortnachrichten über [[TelegramBot]], [[Jabber]] und [[yowsup]] (WhatsApp) zu definieren. Dabei können die einzelnen Dialoge für unterschiedliche Nutzer berechtigt werden.
Die grundlegende Bedienung wird in diesem '''[https://youtu.be/yiCOTeR1YVQ Video]''' am Beispiel von TelegramBot gezeigt.

== Einbindung in FHEM ==

=== Voraussetzungen ===
Für dieses Modul wird das Perl JSON Modul benötigt. Auf einem Debian-basierten System (z.B RaspberryPI o.ä.) kann man das mit dem folgenden Befehl installieren:
<pre>
sudo apt-get install libjson-perl
</pre>

=== Hinweise ===

*Telegram: Es kann notwendig sein, dass im TelegramBot das Attribut "utf8specials" auf "1" gesetzt werden muss. Damit werden Nachrichten mit Umlauten korrekt gesendet. Beim msg-Befehl kann der TelegramBot_MTYPE angegeben werden. Die Vorgabe ist "message". Durch den Wert "queryInline" lässt sich ein inline Keyboard erzeugen (siehe unten).

*Jabber: Beim msg Befehl kann der Jabber_MTYPE angegeben werden. Die Vorgabe ist leer. Durch den Wert "otr" lässt sich eine OTR-Nachricht versenden.

*WhatsApp (yowsup): Bisher konnten noch keine Erfahrungen gemacht werden.

=== msgDialog und ROOMATE ===

Für jeden Dialog kann festgelegt werden, welche Person(en) dazu berechtigt ist. Dazu sind Geräte vom Typ ROOMMATE oder GUEST mit definiertem msgContactPush Attribut erforderlich. Es ist darauf zu achten, dass das Reading "fhemMsgRcvPush" ein Event erzeugt.

=== Definition des msgConfig-Device ===

Als nächstes benötigt man ein definiertes msgConfig device:

<pre>
defmod myMsgConfig msgConfig
attr myMsgConfig msgDialog_evalSpecials me=<Aktivierungswort bzw. -Nachricht>
TelegramBot=<Name des TelegramBot-device>
attr myMsgConfig msgContactPush TelegramBot
attr myMsgConfig room msg
</pre>

Falls bereits vorhanden müssen, natürlich nur die fehlenden Attribute gesetzt werden.

=== Definition des metaDialogs ===

Zur Auflistung aller berechtigten Dialoge dient - was sonst - ein Dialog!

<pre>
defmod meta_Dialog msgDialog {\
"%me%": {\
"match": "\/?(start|%me%)",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"{return('(' . join(') (', sort(split('\n', fhem('get TYPE=msgDialog:FILTER=NAME!=$SELF:FILTER=allowed=.*($recipient|everyone).* trigger')))) . ') ')}",\
"(abbrechen) ",\
"Ich kann folgendes für dich tun:"\
]\
},\
"abbrechen": {\
"match": "\/?abbrechen",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"(%me%) ",\
"Dialog abgebrochen."\
] \
},\
"beenden": {\
"match": "\/?beenden",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"(%me%) ",\
"Dialog beendet."\
]\
}\
}

attr meta_Dialog DbLogExclude .*
attr meta_Dialog allowed everyone
attr meta_Dialog room msg
</pre>

=== Definition beliebiger Dialoge ===

Aufgrund der Komplexität eines Dialogs mit JSON ist es am praktikabelsten, zunächst einen leeren Dialog zu definieren:
<pre>
define <name> msgDialog {}
</pre>

Anschließend kann die DEF in der Detail-Ansicht des Dialog-Device bearbeitet werden. Jeder Dialog basiert auf der folgenden Struktur von einfach bis komplex.

<pre>
{
"<TRIGGER>": {
"match": "<regex>",
"setOnly": (true|false),
"commands": "(fhem command|{perl code})",
"message": [
"{perl code}",
"text"
],
"<NEXT TRIGGER 1>": {
...
},
"<NEXT TRIGGER 2>": {
...
}
}
}
</pre>

Um den JSON-Teil der Dialoge zu testen, empfiehlt sich ein Besuch auf https://jsonlint.com/
Hier kann der selbst geschriebene JSON-Code validiert werden.

*TRIGGER: Kann ein beliebiger Text sein. Es wird geprüft ob die eingehende Nachricht damit übereinstimmt. Falls ja, wird der Dialog an dieser Stelle fortgesetzt.

*match: Wenn nicht nur genau eine Nachricht zugelassen werden soll, kann noch eine regex angegeben werden. Die regex muss auf die gesamte eingehnde Nachricht zutreffen.

*setOnly: Kann optional auf true oder false gestellt werden. In beiden fällen wird der TRIGGER dann nicht bei "get <name> trigger" zurück gegeben.
Wenn setOnly auf true gestellt wird kann der Dialog an dieser Stelle nicht durch eingehnde Nachrichten ausgelöst werden, sondern nur über "get <name> say TRIGGER".
Dies kann dazu genutzt werden um einen Dialog von FHEM zu aus zu initieren.

*commands: Kann einen einzelnen oder mehrere Befehle enthalten:
"commands": "single command"

"commands": [
"command 1",
"command 2",
"{perl command}"
]

*message: Kann einen einzelnen oder mehrere Textte enthalten die mit einen Zeilenumbruch verbunden werden:
"message": "text"

"message": [
"text 1",
"text 2",
"{return from perl command}"
]

Bei mehrstufigen Dialogen wird diese Struktur ineinander verschachtelt angegeben.

Es werden Variablen und unter dem Attribut evalSpecials definierte Platzhalter ausgewertet.
=== Variablen ===
*$SELF: Eigenname des msgDialog
*$message: eingegangene Nachricht
*$recipient: Name des Dialogpartners

=== set ===
*reset: Setzt den Dialog für alle Benutzer zurück.
*say [@<recipient1>[,<recipient2>,...]] <TRIGGER>[|<NEXT TRIGGER>|...]: Der Dialog wird für alle angegeben Empänger an der angegeben Stelle fortgeführt. Sind keine Empfänger angegeben wird der Dialog für alle unter dem Attribut allowed angegebenen Empfänger fortgeführt.
*updateAllowed: Aktualisiert die Auswahl für das Attribut allowed.

=== get ===
*trigger: Listet alle TRIGGER der ersten Ebene auf bei denen nicht setOnly angegeben ist.

=== ATTRIBUTE ===
*allowed: Liste mit allen RESIDENTS und ROOMMATE die für diesen Dialog berechtigt sind.
*disable: [0|1] Dialog ist aktiviert|deaktiviert.
*disabledForIntervals: HH:MM-HH:MM HH:MM-HH-MM ...
*evalSpecials: key1=value1 key2=value2 ...Leerzeichen getrennte Liste von Name=Wert Paaren. Wert kann Leerzeichen enthalten, falls es in "" oder {} eingeschlossen ist. Wert wird als perl-Ausdruck ausgewertet, falls es in {} eingeschlossen ist. In der DEF werden %Name% Zeichenketten durch den zugehörigen Wert ersetzt. Dieses Attribut ist als "msgDialog_evalSpecials" im msgConfig Gerät vorhanden. Wenn der selbe Name im msgConfig und msgDialog definiert wurde, wird der Wert aus msgDialog verwendet.
*msgCommand <command>: Befehl der zum Versenden einer Nachricht verwendet wird. Die Vorgabe ist "msg push \@$recipients $message" Dieses Attribut ist als "msgDialog_msgCommand" im msgConfig Gerät vorhanden.

=== READINGS ===
*$recipient_history: Durch | getrennte Liste von TRIGGERN um den aktuellen Zustand des Dialogs zu sichern. Für jeden Dialogpartner wird ein Readings angelegt. Wenn der Dialog beendet ist wird das Reading zurückgesetzt.

== Beispiele ==

==== Programmierung der Waschmaschine ====
Das ist ein Beispiel zur Programmierung einer Waschmaschine wie auch oben im Video zu sehen:
<pre>
defmod Waschmaschine_Dialog msgDialog { "Waschmaschine": {\
"message": [\
"{return('(Zeitprogramm stoppen) ') if(ReadingsVal('%controlUnit%', 'controlMode', '') eq 'auto')}",\
"{return('(programmieren) ') if(ReadingsVal('%actor%', 'state', '') ne 'on')}",\
"{return('(einschalten) ') if(ReadingsVal('%actor%', 'state', '') ne 'on')}",\
"(Verlaufsdiagramm) ",\
"(abbrechen) ",\
"{return('Waschmaschine: ' . (ReadingsVal('%actor%', 'state', '') eq 'on' ? 'eingeschaltet' : 'ausgeschaltet'))}",\
"{return('Modus: ' . (ReadingsVal('%controlUnit%', 'controlMode', '') eq 'auto' ? 'Automatik' : 'Manuell (' . ReadingsVal('%controlUnit%', 'time', '') . ')'))}"\
],\
"Zeitprogramm stoppen": {\
"commands": "set %controlUnit% controlMode manual",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Das Zeitprogramm wurde gestoppt."\
]\
},\
"programmieren": {\
"message": [\
"(bestätigen|zurück|abbrechen) ",\
"( 00:00 | 00:15 | 00:30 | 00:45 ) ",\
"( 01:00 | 01:15 | 01:30 | 01:45 ) ",\
"( 02:00 | 02:15 | 02:30 | 02:45 ) ",\
"( 03:00 | 03:15 | 03:30 | 03:45 ) ",\
"( 04:00 | 04:15 | 04:30 | 04:45 ) ",\
"( 05:00 | 05:15 | 05:30 | 05:45 ) ",\
"( 06:00 | 06:15 | 06:30 | 06:45 ) ",\
"( 07:00 | 07:15 | 07:30 | 07:45 ) ",\
"( 08:00 | 08:15 | 08:30 | 08:45 ) ",\
"( 09:00 | 09:15 | 09:30 | 09:45 ) ",\
"( 10:00 | 10:15 | 10:30 | 10:45 ) ",\
"( 11:00 | 11:15 | 11:30 | 11:45 ) ",\
"( 12:00 | 12:15 | 12:30 | 12:45 ) ",\
"( 13:00 | 13:15 | 13:30 | 13:45 ) ",\
"( 14:00 | 14:15 | 14:30 | 14:45 ) ",\
"( 15:00 | 15:15 | 15:30 | 15:45 ) ",\
"( 16:00 | 16:15 | 16:30 | 16:45 ) ",\
"( 17:00 | 17:15 | 17:30 | 17:45 ) ",\
"( 18:00 | 18:15 | 18:30 | 18:45 ) ",\
"( 19:00 | 19:15 | 19:30 | 19:45 ) ",\
"( 20:00 | 20:15 | 20:30 | 20:45 ) ",\
"( 21:00 | 21:15 | 21:30 | 21:45 ) ",\
"( 22:00 | 22:15 | 22:30 | 22:45 ) ",\
"( 23:00 | 23:15 | 23:30 | 23:45 ) ",\
"Wann soll die Wäsche fertig sein?",\
"Bitte Uhrzeit in HH:MM angeben.",\
"Aktuell ist [%controlUnit%:time] Uhr eingestellt."\
],\
"Uhrzeit": {\
"match": " ?([0-1][0-9]|2[0-3]):[0-5][0-9] ?",\
"commands": [\
"set %controlUnit% time $message",\
"set $SELF say @$recipient Waschmaschine|programmieren|bestätigen"\
]\
},\
"bestätigen": {\
"commands": "set %controlUnit% controlMode auto",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Das Zeitprogramm wurde eingestellt.",\
"Die Wäsche wird voraussichtlich um [%controlUnit%:time] Uhr fertig sein.",\
"Bitte die Waschmaschine vorbereiten."\
]\
}\
},\
"einschalten": {\
"commands": [\
"set %controlUnit% controlMode manual",\
"set %actor% on"\
]\
},\
"Verlaufsdiagramm": {\
"commands": "set %TelegramBot% cmdSend {plotAsPng('%plot%')}",\
"message": "TelegramBot_MTYPE=queryInline (%me%) $message"\
}\
},\
"auto": {\
"setOnly": true,\
"commands": [\
"set %actor% on",\
"set %controlUnit% controlMode manual"\
],\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine wurde automatisch eingeschaltet."\
]\
},\
"manual": {\
"setOnly": true,\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine wurde manuell eingeschaltet."\
]\
},\
"done": {\
"setOnly": true,\
"commands": "set %actor% off",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine ist fertig."\
]\
}\
}
attr Waschmaschine_Dialog evalSpecials actor=HM_2C10D8_Sw\
controlUnit=Waschkeller_washer_controlUnit\
plot=Waschkeller_washer_SVG
</pre>

== TelegramBot: Inline Keyboard verwenden==

In Telegram gibt es die Möglichkeit die Art des Keyboards zu ändern. Links das normale Keyboard, rechts das Inline Keyboard.

[[Datei:76msgDialog menu.png]] [[Datei:76msgDialog menu inline.PNG]]

In diesem '''[https://youtu.be/oRDy2918mVI Video]''' wird Telegram mit einem Inline Keyboard verwendet.

Um eine Nachricht bei Telegram zu verändern, gibt es den Befehl "queryEditInline".
Dafür wird die MsgId von der Nachricht benötigt. Das erledigt ein notify, welches die msgId pro Peer abspeichert:

<pre>
defmod sentMsgIdByPeerId notify .+:sentMsgId.+ {\
return unless($TYPE eq "TelegramBot");;\
\
my $dev_hash = $defs{$NAME};;\
my $sentMsgId = ReadingsVal($NAME, "sentMsgId", "");;\
my $sentMsgPeerId = ReadingsVal($NAME, "sentMsgPeerId", "");;\
my ($contact) = devspec2array("TYPE=(ROOMMATE|GUEST):FILTER=msgContactPush=.*$sentMsgPeerId.*");;\
\
readingsSingleUpdate($dev_hash, "$contact\_sentMsgId", $sentMsgId, 1);;\
}
attr sentMsgIdByPeerId devStateIcon {ReadingsVal($name, "state", "inactive") eq "active" ? ".*:ios-on-blue:inactive" : ".*:ios-off:active"}
attr sentMsgIdByPeerId icon audio_mic
attr sentMsgIdByPeerId room msg
</pre>

Danach wird der Message-Befehl von
<pre>
set <TelegramBot> message
</pre>
auf
<pre>
set <TelegramBot> queryEditInline
</pre>
geändert. Dafür wird ein [[cmdalias]] verwendet:

<pre>
defmod message2queryEditInline cmdalias set .+ message (.|\n)+ AS {\
my ($NAME, $cmd, $message) = split(/[\s]+/, $EVENT, 3);;\
my $TYPE = InternalVal($NAME, "TYPE", "");;\
(my $recipient, $message) = ($message =~ m/(@\S+)? (.+)/s);;\
\
if($TYPE eq "TelegramBot" && $recipient){\
my ($contact) = devspec2array("TYPE=(ROOMMATE|GUEST):FILTER=msgContactPush=.*$recipient.*");;\
my $sentMsgId = ReadingsVal($NAME, "$contact\_sentMsgId", "");;\
\
if($sentMsgId ne ""){\
fhem("set $NAME queryEditInline $sentMsgId $recipient $message");;\
}\
else{\
fhem("set $NAME queryInline $recipient $message");;\
}\
}\
else{\
fhem("set $EVENT");;\
}\
}
attr message2queryEditInline room msg
</pre>

Um wieder zurück zum normalen Keyboard zu gelangen genügt es, das notify und den cmdAlias zu deaktivieren.
Hier noch ein kleines notify, welches über einen dummy geschaltet werden kann:
<pre>
defmod inline_normal.NOT notify inline_normal.DUM:.* {\
if ("$EVENT" =~ "on") {\
fhem "set sentMsgIdByPeerId active;; attr message2queryEditInline disable 0";;\
} \
elsif ("$EVENT" =~ "off") {\
fhem "set sentMsgIdByPeerId inactive;; attr message2queryEditInline disable 1";;\
}\
}
</pre>

Weitere Infos zum Thema Inline Keyboard sind in der Antwort #10 im Forum zu finden (siehe Link unten).

== Links ==
* Thread über das Modul im {{Link2Forum|Topic=77297|LinkText=FHEM Forum}}

[[Kategorie:Gerätemodul]]

MsgDialog

2017-10-23T12:52:25Z

Binford6000: /* Hinweise */

{{Infobox Modul
|ModPurpose=Dialoge für Sofortnachrichten über TelegramBot, Jabber und WhatsApp
|ModType=d
|ModForumArea=Frontends
|ModTechName=76_msgDialog.pm
|ModOwner={{Link2FU|4106|igami}}
}}

== Zielsetzung ==
Eine zentrale Anforderung einer modernen Haus-Automation ist die Steuerung von unterwegs. Mittlerweile nutzt fast jeder einen oder mehrere Messenger Dienste. Da liegt es doch nahe, diese Messenger Dienste für die Kommunikation mit FHEM zu nutzen.
Mit msgDialog ist es jetzt möglich, Dialoge für Sofortnachrichten über [[TelegramBot]], [[Jabber]] und [[yowsup]] (WhatsApp) zu definieren. Dabei können die einzelnen Dialoge für unterschiedliche Nutzer berechtigt werden.
Die grundlegende Bedienung wird in diesem '''[https://youtu.be/yiCOTeR1YVQ Video]''' am Beispiel von TelegramBot gezeigt.

== Einbindung in FHEM ==

=== Voraussetzungen ===
Für dieses Modul wird das Perl JSON Modul benötigt. Auf einem Debian-basierten System (z.B RaspberryPI o.ä.) kann man das mit dem folgenden Befehl installieren:
<pre>
sudo apt-get install libjson-perl
</pre>

=== Hinweise ===

*Telegram: Es kann notwendig sein, dass im TelegramBot das Attribut "utf8specials" auf "1" gesetzt werden muss. Damit werden Nachrichten mit Umlauten korrekt gesendet. Beim msg-Befehl kann der TelegramBot_MTYPE angegeben werden. Die Vorgabe ist "message". Durch den Wert "queryInline" lässt sich ein inline Keyboard erzeugen (siehe unten).

*Jabber: Beim msg Befehl kann der Jabber_MTYPE angegeben werden. Die Vorgabe ist leer. Durch den Wert "otr" lässt sich eine OTR-Nachricht versenden.

*WhatsApp (yowsup): Bisher konnten noch keine Erfahrungen gemacht werden.

=== msgDialog und ROOMATE ===

Für jeden Dialog kann festgelegt werden, welche Person(en) dazu berechtigt ist. Dazu sind Geräte vom Typ ROOMMATE oder GUEST mit definiertem msgContactPush Attribut erforderlich. Es ist darauf zu achten, dass das Reading "fhemMsgRcvPush" ein Event erzeugt.

=== Definition des msgConfig-Device ===

Als nächstes benötigt man ein definiertes msgConfig device:

<pre>
defmod myMsgConfig msgConfig
attr myMsgConfig msgDialog_evalSpecials me=<Aktivierungswort bzw. -Nachricht>
TelegramBot=<Name des TelegramBot-device>
attr myMsgConfig msgContactPush TelegramBot
attr myMsgConfig room msg
</pre>

Falls bereits vorhanden müssen, natürlich nur die fehlenden Attribute gesetzt werden.

=== Definition des metaDialogs ===

Zur Auflistung aller berechtigten Dialoge dient - was sonst - ein Dialog!

<pre>
defmod meta_Dialog msgDialog {\
"%me%": {\
"match": "\/?(start|%me%)",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"{return('(' . join(') (', sort(split('\n', fhem('get TYPE=msgDialog:FILTER=NAME!=$SELF:FILTER=allowed=.*($recipient|everyone).* trigger')))) . ') ')}",\
"(abbrechen) ",\
"Ich kann folgendes für dich tun:"\
]\
},\
"abbrechen": {\
"match": "\/?abbrechen",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"(%me%) ",\
"Dialog abgebrochen."\
] \
},\
"beenden": {\
"match": "\/?beenden",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"(%me%) ",\
"Dialog beendet."\
]\
}\
}

attr meta_Dialog DbLogExclude .*
attr meta_Dialog allowed everyone
attr meta_Dialog room msg
</pre>

=== Definition beliebiger Dialoge ===

Aufgrund der Komplexität eines Dialogs mit JSON ist es am praktikabelsten, zunächst einen leeren Dialog zu definieren:
<pre>
define <name> msgDialog {}
</pre>

Anschließend kann die DEF in der Detail-Ansicht des Dialog-Device bearbeitet werden. Jeder Dialog basiert auf der folgenden Struktur von einfach bis komplex.

<pre>
{
"<TRIGGER>": {
"match": "<regex>",
"setOnly": (true|false),
"commands": "(fhem command|{perl code})",
"message": [
"{perl code}",
"text"
],
"<NEXT TRIGGER 1>": {
...
},
"<NEXT TRIGGER 2>": {
...
}
}
}
</pre>

Um den JSON-Teil der Dialoge zu testen, empfiehlt sich ein Besuch auf https://jsonlint.com/
Hier kann der selbst geschriebene JSON-Code validiert werden.

== Beispiele ==

==== Programmierung der Waschmaschine ====
Das ist ein Beispiel zur Programmierung einer Waschmaschine wie auch oben im Video zu sehen:
<pre>
defmod Waschmaschine_Dialog msgDialog { "Waschmaschine": {\
"message": [\
"{return('(Zeitprogramm stoppen) ') if(ReadingsVal('%controlUnit%', 'controlMode', '') eq 'auto')}",\
"{return('(programmieren) ') if(ReadingsVal('%actor%', 'state', '') ne 'on')}",\
"{return('(einschalten) ') if(ReadingsVal('%actor%', 'state', '') ne 'on')}",\
"(Verlaufsdiagramm) ",\
"(abbrechen) ",\
"{return('Waschmaschine: ' . (ReadingsVal('%actor%', 'state', '') eq 'on' ? 'eingeschaltet' : 'ausgeschaltet'))}",\
"{return('Modus: ' . (ReadingsVal('%controlUnit%', 'controlMode', '') eq 'auto' ? 'Automatik' : 'Manuell (' . ReadingsVal('%controlUnit%', 'time', '') . ')'))}"\
],\
"Zeitprogramm stoppen": {\
"commands": "set %controlUnit% controlMode manual",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Das Zeitprogramm wurde gestoppt."\
]\
},\
"programmieren": {\
"message": [\
"(bestätigen|zurück|abbrechen) ",\
"( 00:00 | 00:15 | 00:30 | 00:45 ) ",\
"( 01:00 | 01:15 | 01:30 | 01:45 ) ",\
"( 02:00 | 02:15 | 02:30 | 02:45 ) ",\
"( 03:00 | 03:15 | 03:30 | 03:45 ) ",\
"( 04:00 | 04:15 | 04:30 | 04:45 ) ",\
"( 05:00 | 05:15 | 05:30 | 05:45 ) ",\
"( 06:00 | 06:15 | 06:30 | 06:45 ) ",\
"( 07:00 | 07:15 | 07:30 | 07:45 ) ",\
"( 08:00 | 08:15 | 08:30 | 08:45 ) ",\
"( 09:00 | 09:15 | 09:30 | 09:45 ) ",\
"( 10:00 | 10:15 | 10:30 | 10:45 ) ",\
"( 11:00 | 11:15 | 11:30 | 11:45 ) ",\
"( 12:00 | 12:15 | 12:30 | 12:45 ) ",\
"( 13:00 | 13:15 | 13:30 | 13:45 ) ",\
"( 14:00 | 14:15 | 14:30 | 14:45 ) ",\
"( 15:00 | 15:15 | 15:30 | 15:45 ) ",\
"( 16:00 | 16:15 | 16:30 | 16:45 ) ",\
"( 17:00 | 17:15 | 17:30 | 17:45 ) ",\
"( 18:00 | 18:15 | 18:30 | 18:45 ) ",\
"( 19:00 | 19:15 | 19:30 | 19:45 ) ",\
"( 20:00 | 20:15 | 20:30 | 20:45 ) ",\
"( 21:00 | 21:15 | 21:30 | 21:45 ) ",\
"( 22:00 | 22:15 | 22:30 | 22:45 ) ",\
"( 23:00 | 23:15 | 23:30 | 23:45 ) ",\
"Wann soll die Wäsche fertig sein?",\
"Bitte Uhrzeit in HH:MM angeben.",\
"Aktuell ist [%controlUnit%:time] Uhr eingestellt."\
],\
"Uhrzeit": {\
"match": " ?([0-1][0-9]|2[0-3]):[0-5][0-9] ?",\
"commands": [\
"set %controlUnit% time $message",\
"set $SELF say @$recipient Waschmaschine|programmieren|bestätigen"\
]\
},\
"bestätigen": {\
"commands": "set %controlUnit% controlMode auto",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Das Zeitprogramm wurde eingestellt.",\
"Die Wäsche wird voraussichtlich um [%controlUnit%:time] Uhr fertig sein.",\
"Bitte die Waschmaschine vorbereiten."\
]\
}\
},\
"einschalten": {\
"commands": [\
"set %controlUnit% controlMode manual",\
"set %actor% on"\
]\
},\
"Verlaufsdiagramm": {\
"commands": "set %TelegramBot% cmdSend {plotAsPng('%plot%')}",\
"message": "TelegramBot_MTYPE=queryInline (%me%) $message"\
}\
},\
"auto": {\
"setOnly": true,\
"commands": [\
"set %actor% on",\
"set %controlUnit% controlMode manual"\
],\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine wurde automatisch eingeschaltet."\
]\
},\
"manual": {\
"setOnly": true,\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine wurde manuell eingeschaltet."\
]\
},\
"done": {\
"setOnly": true,\
"commands": "set %actor% off",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine ist fertig."\
]\
}\
}
attr Waschmaschine_Dialog evalSpecials actor=HM_2C10D8_Sw\
controlUnit=Waschkeller_washer_controlUnit\
plot=Waschkeller_washer_SVG
</pre>

== TelegramBot: Inline Keyboard verwenden==

In Telegram gibt es die Möglichkeit die Art des Keyboards zu ändern. Links das normale Keyboard, rechts das Inline Keyboard.

[[Datei:76msgDialog menu.png]] [[Datei:76msgDialog menu inline.PNG]]

In diesem '''[https://youtu.be/oRDy2918mVI Video]''' wird Telegram mit einem Inline Keyboard verwendet.

Um eine Nachricht bei Telegram zu verändern, gibt es den Befehl "queryEditInline".
Dafür wird die MsgId von der Nachricht benötigt. Das erledigt ein notify, welches die msgId pro Peer abspeichert:

<pre>
defmod sentMsgIdByPeerId notify .+:sentMsgId.+ {\
return unless($TYPE eq "TelegramBot");;\
\
my $dev_hash = $defs{$NAME};;\
my $sentMsgId = ReadingsVal($NAME, "sentMsgId", "");;\
my $sentMsgPeerId = ReadingsVal($NAME, "sentMsgPeerId", "");;\
my ($contact) = devspec2array("TYPE=(ROOMMATE|GUEST):FILTER=msgContactPush=.*$sentMsgPeerId.*");;\
\
readingsSingleUpdate($dev_hash, "$contact\_sentMsgId", $sentMsgId, 1);;\
}
attr sentMsgIdByPeerId devStateIcon {ReadingsVal($name, "state", "inactive") eq "active" ? ".*:ios-on-blue:inactive" : ".*:ios-off:active"}
attr sentMsgIdByPeerId icon audio_mic
attr sentMsgIdByPeerId room msg
</pre>

Danach wird der Message-Befehl von
<pre>
set <TelegramBot> message
</pre>
auf
<pre>
set <TelegramBot> queryEditInline
</pre>
geändert. Dafür wird ein [[cmdalias]] verwendet:

<pre>
defmod message2queryEditInline cmdalias set .+ message (.|\n)+ AS {\
my ($NAME, $cmd, $message) = split(/[\s]+/, $EVENT, 3);;\
my $TYPE = InternalVal($NAME, "TYPE", "");;\
(my $recipient, $message) = ($message =~ m/(@\S+)? (.+)/s);;\
\
if($TYPE eq "TelegramBot" && $recipient){\
my ($contact) = devspec2array("TYPE=(ROOMMATE|GUEST):FILTER=msgContactPush=.*$recipient.*");;\
my $sentMsgId = ReadingsVal($NAME, "$contact\_sentMsgId", "");;\
\
if($sentMsgId ne ""){\
fhem("set $NAME queryEditInline $sentMsgId $recipient $message");;\
}\
else{\
fhem("set $NAME queryInline $recipient $message");;\
}\
}\
else{\
fhem("set $EVENT");;\
}\
}
attr message2queryEditInline room msg
</pre>

Um wieder zurück zum normalen Keyboard zu gelangen genügt es, das notify und den cmdAlias zu deaktivieren.
Hier noch ein kleines notify, welches über einen dummy geschaltet werden kann:
<pre>
defmod inline_normal.NOT notify inline_normal.DUM:.* {\
if ("$EVENT" =~ "on") {\
fhem "set sentMsgIdByPeerId active;; attr message2queryEditInline disable 0";;\
} \
elsif ("$EVENT" =~ "off") {\
fhem "set sentMsgIdByPeerId inactive;; attr message2queryEditInline disable 1";;\
}\
}
</pre>

Weitere Infos zum Thema Inline Keyboard sind in der Antwort #10 im Forum zu finden (siehe Link unten).

== Links ==
* Thread über das Modul im {{Link2Forum|Topic=77297|LinkText=FHEM Forum}}

[[Kategorie:Gerätemodul]]

MsgDialog

2017-10-22T06:59:16Z

Binford6000: /* TelegramBot: Inline Keyboard verwenden */

{{Infobox Modul
|ModPurpose=Dialoge für Sofortnachrichten über TelegramBot, Jabber und WhatsApp
|ModType=d
|ModForumArea=Frontends
|ModTechName=76_msgDialog.pm
|ModOwner={{Link2FU|4106|igami}}
}}

== Zielsetzung ==
Eine zentrale Anforderung einer modernen Haus-Automation ist die Steuerung von unterwegs. Mittlerweile nutzt fast jeder einen oder mehrere Messenger Dienste. Da liegt es doch nahe, diese Messenger Dienste für die Kommunikation mit FHEM zu nutzen.
Mit msgDialog ist es jetzt möglich, Dialoge für Sofortnachrichten über [[TelegramBot]], [[Jabber]] und [[yowsup]] (WhatsApp) zu definieren. Dabei können die einzelnen Dialoge für unterschiedliche Nutzer berechtigt werden.
Die grundlegende Bedienung wird in diesem '''[https://youtu.be/yiCOTeR1YVQ Video]''' am Beispiel von TelegramBot gezeigt.

== Einbindung in FHEM ==

=== Voraussetzungen ===
Für dieses Modul wird das Perl JSON Modul benötigt. Auf einem Debian-basierten System (z.B RaspberryPI o.ä.) kann man das mit dem folgenden Befehl installieren:
<pre>
sudo apt-get install libjson-perl
</pre>

=== Hinweise ===

'''Telegram:''' Es kann notwendig sein, dass im TelegramBot das Attribut "utf8specials" auf "1" gesetzt werden muss. Damit werden Nachrichten mit Umlauten korrekt gesendet. Beim msg-Befehl kann der TelegramBot_MTYPE angegeben werden. Die Vorgabe ist "message". Durch den Wert "queryInline" lässt sich ein inline Keyboard erzeugen (siehe unten).

'''Jabber:''' Beim msg Befehl kann der Jabber_MTYPE angegeben werden. Die Vorgabe ist leer. Durch den Wert "otr" lässt sich eine OTR-Nachricht versenden.

'''WhatsApp (yowsup):''' Bisher konnten noch keine Erfahrungen gemacht werden.

=== msgDialog und ROOMATE ===

Für jeden Dialog kann festgelegt werden, welche Person(en) dazu berechtigt ist. Dazu sind Geräte vom Typ ROOMMATE oder GUEST mit definiertem msgContactPush Attribut erforderlich. Es ist darauf zu achten, dass das Reading "fhemMsgRcvPush" ein Event erzeugt.

=== Definition des msgConfig-Device ===

Als nächstes benötigt man ein definiertes msgConfig device:

<pre>
defmod myMsgConfig msgConfig
attr myMsgConfig msgDialog_evalSpecials me=<Aktivierungswort bzw. -Nachricht>
TelegramBot=<Name des TelegramBot-device>
attr myMsgConfig msgContactPush TelegramBot
attr myMsgConfig room msg
</pre>

Falls bereits vorhanden müssen, natürlich nur die fehlenden Attribute gesetzt werden.

=== Definition des metaDialogs ===

Zur Auflistung aller berechtigten Dialoge dient - was sonst - ein Dialog!

<pre>
defmod meta_Dialog msgDialog {\
"%me%": {\
"match": "\/?(start|%me%)",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"{return('(' . join(') (', sort(split('\n', fhem('get TYPE=msgDialog:FILTER=NAME!=$SELF:FILTER=allowed=.*($recipient|everyone).* trigger')))) . ') ')}",\
"(abbrechen) ",\
"Ich kann folgendes für dich tun:"\
]\
},\
"abbrechen": {\
"match": "\/?abbrechen",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"(%me%) ",\
"Dialog abgebrochen."\
] \
},\
"beenden": {\
"match": "\/?beenden",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"(%me%) ",\
"Dialog beendet."\
]\
}\
}

attr meta_Dialog DbLogExclude .*
attr meta_Dialog allowed everyone
attr meta_Dialog room msg
</pre>

=== Definition beliebiger Dialoge ===

Aufgrund der Komplexität eines Dialogs mit JSON ist es am praktikabelsten, zunächst einen leeren Dialog zu definieren:
<pre>
define <name> msgDialog {}
</pre>

Anschließend kann die DEF in der Detail-Ansicht des Dialog-Device bearbeitet werden. Jeder Dialog basiert auf der folgenden Struktur von einfach bis komplex.

<pre>
{
"<TRIGGER>": {
"match": "<regex>",
"setOnly": (true|false),
"commands": "(fhem command|{perl code})",
"message": [
"{perl code}",
"text"
],
"<NEXT TRIGGER 1>": {
...
},
"<NEXT TRIGGER 2>": {
...
}
}
}
</pre>

Um den JSON-Teil der Dialoge zu testen, empfiehlt sich ein Besuch auf https://jsonlint.com/
Hier kann der selbst geschriebene JSON-Code validiert werden.

== Beispiele ==

==== Programmierung der Waschmaschine ====
Das ist ein Beispiel zur Programmierung einer Waschmaschine wie auch oben im Video zu sehen:
<pre>
defmod Waschmaschine_Dialog msgDialog { "Waschmaschine": {\
"message": [\
"{return('(Zeitprogramm stoppen) ') if(ReadingsVal('%controlUnit%', 'controlMode', '') eq 'auto')}",\
"{return('(programmieren) ') if(ReadingsVal('%actor%', 'state', '') ne 'on')}",\
"{return('(einschalten) ') if(ReadingsVal('%actor%', 'state', '') ne 'on')}",\
"(Verlaufsdiagramm) ",\
"(abbrechen) ",\
"{return('Waschmaschine: ' . (ReadingsVal('%actor%', 'state', '') eq 'on' ? 'eingeschaltet' : 'ausgeschaltet'))}",\
"{return('Modus: ' . (ReadingsVal('%controlUnit%', 'controlMode', '') eq 'auto' ? 'Automatik' : 'Manuell (' . ReadingsVal('%controlUnit%', 'time', '') . ')'))}"\
],\
"Zeitprogramm stoppen": {\
"commands": "set %controlUnit% controlMode manual",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Das Zeitprogramm wurde gestoppt."\
]\
},\
"programmieren": {\
"message": [\
"(bestätigen|zurück|abbrechen) ",\
"( 00:00 | 00:15 | 00:30 | 00:45 ) ",\
"( 01:00 | 01:15 | 01:30 | 01:45 ) ",\
"( 02:00 | 02:15 | 02:30 | 02:45 ) ",\
"( 03:00 | 03:15 | 03:30 | 03:45 ) ",\
"( 04:00 | 04:15 | 04:30 | 04:45 ) ",\
"( 05:00 | 05:15 | 05:30 | 05:45 ) ",\
"( 06:00 | 06:15 | 06:30 | 06:45 ) ",\
"( 07:00 | 07:15 | 07:30 | 07:45 ) ",\
"( 08:00 | 08:15 | 08:30 | 08:45 ) ",\
"( 09:00 | 09:15 | 09:30 | 09:45 ) ",\
"( 10:00 | 10:15 | 10:30 | 10:45 ) ",\
"( 11:00 | 11:15 | 11:30 | 11:45 ) ",\
"( 12:00 | 12:15 | 12:30 | 12:45 ) ",\
"( 13:00 | 13:15 | 13:30 | 13:45 ) ",\
"( 14:00 | 14:15 | 14:30 | 14:45 ) ",\
"( 15:00 | 15:15 | 15:30 | 15:45 ) ",\
"( 16:00 | 16:15 | 16:30 | 16:45 ) ",\
"( 17:00 | 17:15 | 17:30 | 17:45 ) ",\
"( 18:00 | 18:15 | 18:30 | 18:45 ) ",\
"( 19:00 | 19:15 | 19:30 | 19:45 ) ",\
"( 20:00 | 20:15 | 20:30 | 20:45 ) ",\
"( 21:00 | 21:15 | 21:30 | 21:45 ) ",\
"( 22:00 | 22:15 | 22:30 | 22:45 ) ",\
"( 23:00 | 23:15 | 23:30 | 23:45 ) ",\
"Wann soll die Wäsche fertig sein?",\
"Bitte Uhrzeit in HH:MM angeben.",\
"Aktuell ist [%controlUnit%:time] Uhr eingestellt."\
],\
"Uhrzeit": {\
"match": " ?([0-1][0-9]|2[0-3]):[0-5][0-9] ?",\
"commands": [\
"set %controlUnit% time $message",\
"set $SELF say @$recipient Waschmaschine|programmieren|bestätigen"\
]\
},\
"bestätigen": {\
"commands": "set %controlUnit% controlMode auto",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Das Zeitprogramm wurde eingestellt.",\
"Die Wäsche wird voraussichtlich um [%controlUnit%:time] Uhr fertig sein.",\
"Bitte die Waschmaschine vorbereiten."\
]\
}\
},\
"einschalten": {\
"commands": [\
"set %controlUnit% controlMode manual",\
"set %actor% on"\
]\
},\
"Verlaufsdiagramm": {\
"commands": "set %TelegramBot% cmdSend {plotAsPng('%plot%')}",\
"message": "TelegramBot_MTYPE=queryInline (%me%) $message"\
}\
},\
"auto": {\
"setOnly": true,\
"commands": [\
"set %actor% on",\
"set %controlUnit% controlMode manual"\
],\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine wurde automatisch eingeschaltet."\
]\
},\
"manual": {\
"setOnly": true,\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine wurde manuell eingeschaltet."\
]\
},\
"done": {\
"setOnly": true,\
"commands": "set %actor% off",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine ist fertig."\
]\
}\
}
attr Waschmaschine_Dialog evalSpecials actor=HM_2C10D8_Sw\
controlUnit=Waschkeller_washer_controlUnit\
plot=Waschkeller_washer_SVG
</pre>

== TelegramBot: Inline Keyboard verwenden==

In Telegram gibt es die Möglichkeit die Art des Keyboards zu ändern. Links das normale Keyboard, rechts das Inline Keyboard.

[[Datei:76msgDialog menu.png]] [[Datei:76msgDialog menu inline.PNG]]

In diesem '''[https://youtu.be/oRDy2918mVI Video]''' wird Telegram mit einem Inline Keyboard verwendet.

Um eine Nachricht bei Telegram zu verändern, gibt es den Befehl "queryEditInline".
Dafür wird die MsgId von der Nachricht benötigt. Das erledigt ein notify, welches die msgId pro Peer abspeichert:

<pre>
defmod sentMsgIdByPeerId notify .+:sentMsgId.+ {\
return unless($TYPE eq "TelegramBot");;\
\
my $dev_hash = $defs{$NAME};;\
my $sentMsgId = ReadingsVal($NAME, "sentMsgId", "");;\
my $sentMsgPeerId = ReadingsVal($NAME, "sentMsgPeerId", "");;\
my ($contact) = devspec2array("TYPE=(ROOMMATE|GUEST):FILTER=msgContactPush=.*$sentMsgPeerId.*");;\
\
readingsSingleUpdate($dev_hash, "$contact\_sentMsgId", $sentMsgId, 1);;\
}
attr sentMsgIdByPeerId devStateIcon {ReadingsVal($name, "state", "inactive") eq "active" ? ".*:ios-on-blue:inactive" : ".*:ios-off:active"}
attr sentMsgIdByPeerId icon audio_mic
attr sentMsgIdByPeerId room msg
</pre>

Danach wird der Message-Befehl von
<pre>
set <TelegramBot> message
</pre>
auf
<pre>
set <TelegramBot> queryEditInline
</pre>
geändert. Dafür wird ein [[cmdalias]] verwendet:

<pre>
defmod message2queryEditInline cmdalias set .+ message (.|\n)+ AS {\
my ($NAME, $cmd, $message) = split(/[\s]+/, $EVENT, 3);;\
my $TYPE = InternalVal($NAME, "TYPE", "");;\
(my $recipient, $message) = ($message =~ m/(@\S+)? (.+)/s);;\
\
if($TYPE eq "TelegramBot" && $recipient){\
my ($contact) = devspec2array("TYPE=(ROOMMATE|GUEST):FILTER=msgContactPush=.*$recipient.*");;\
my $sentMsgId = ReadingsVal($NAME, "$contact\_sentMsgId", "");;\
\
if($sentMsgId ne ""){\
fhem("set $NAME queryEditInline $sentMsgId $recipient $message");;\
}\
else{\
fhem("set $NAME queryInline $recipient $message");;\
}\
}\
else{\
fhem("set $EVENT");;\
}\
}
attr message2queryEditInline room msg
</pre>

Um wieder zurück zum normalen Keyboard zu gelangen genügt es, das notify und den cmdAlias zu deaktivieren.
Hier noch ein kleines notify, welches über einen dummy geschaltet werden kann:
<pre>
defmod inline_normal.NOT notify inline_normal.DUM:.* {\
if ("$EVENT" =~ "on") {\
fhem "set sentMsgIdByPeerId active;; attr message2queryEditInline disable 0";;\
} \
elsif ("$EVENT" =~ "off") {\
fhem "set sentMsgIdByPeerId inactive;; attr message2queryEditInline disable 1";;\
}\
}
</pre>

Weitere Infos zum Thema Inline Keyboard sind in der Antwort #10 im Forum zu finden (siehe Link unten).

== Links ==
* Thread über das Modul im {{Link2Forum|Topic=77297|LinkText=FHEM Forum}}

[[Kategorie:Gerätemodul]]

MsgDialog

2017-10-20T16:13:05Z

Binford6000: /* Zielsetzung */

{{Infobox Modul
|ModPurpose=Dialoge für Sofortnachrichten über TelegramBot, Jabber und WhatsApp
|ModType=d
|ModForumArea=Frontends
|ModTechName=76_msgDialog.pm
|ModOwner={{Link2FU|4106|igami}}
}}

== Zielsetzung ==
Eine zentrale Anforderung einer modernen Haus-Automation ist die Steuerung von unterwegs. Mittlerweile nutzt fast jeder einen oder mehrere Messenger Dienste. Da liegt es doch nahe, diese Messenger Dienste für die Kommunikation mit FHEM zu nutzen.
Mit msgDialog ist es jetzt möglich, Dialoge für Sofortnachrichten über [[TelegramBot]], [[Jabber]] und [[yowsup]] (WhatsApp) zu definieren. Dabei können die einzelnen Dialoge für unterschiedliche Nutzer berechtigt werden.
Die grundlegende Bedienung wird in diesem '''[https://youtu.be/yiCOTeR1YVQ Video]''' am Beispiel von TelegramBot gezeigt.

== Einbindung in FHEM ==

=== Voraussetzungen ===
Für dieses Modul wird das Perl JSON Modul benötigt. Auf einem Debian-basierten System (z.B RaspberryPI o.ä.) kann man das mit dem folgenden Befehl installieren:
<pre>
sudo apt-get install libjson-perl
</pre>

=== Hinweise ===

'''Telegram:''' Es kann notwendig sein, dass im TelegramBot das Attribut "utf8specials" auf "1" gesetzt werden muss. Damit werden Nachrichten mit Umlauten korrekt gesendet. Beim msg-Befehl kann der TelegramBot_MTYPE angegeben werden. Die Vorgabe ist "message". Durch den Wert "queryInline" lässt sich ein inline Keyboard erzeugen (siehe unten).

'''Jabber:''' Beim msg Befehl kann der Jabber_MTYPE angegeben werden. Die Vorgabe ist leer. Durch den Wert "otr" lässt sich eine OTR-Nachricht versenden.

'''WhatsApp (yowsup):''' Bisher konnten noch keine Erfahrungen gemacht werden.

=== msgDialog und ROOMATE ===

Für jeden Dialog kann festgelegt werden, welche Person(en) dazu berechtigt ist. Dazu sind Geräte vom Typ ROOMMATE oder GUEST mit definiertem msgContactPush Attribut erforderlich. Es ist darauf zu achten, dass das Reading "fhemMsgRcvPush" ein Event erzeugt.

=== Definition des msgConfig-Device ===

Als nächstes benötigt man ein definiertes msgConfig device:

<pre>
defmod myMsgConfig msgConfig
attr myMsgConfig msgDialog_evalSpecials me=<Aktivierungswort bzw. -Nachricht>
TelegramBot=<Name des TelegramBot-device>
attr myMsgConfig msgContactPush TelegramBot
attr myMsgConfig room msg
</pre>

Falls bereits vorhanden müssen, natürlich nur die fehlenden Attribute gesetzt werden.

=== Definition des metaDialogs ===

Zur Auflistung aller berechtigten Dialoge dient - was sonst - ein Dialog!

<pre>
defmod meta_Dialog msgDialog {\
"%me%": {\
"match": "\/?(start|%me%)",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"{return('(' . join(') (', sort(split('\n', fhem('get TYPE=msgDialog:FILTER=NAME!=$SELF:FILTER=allowed=.*($recipient|everyone).* trigger')))) . ') ')}",\
"(abbrechen) ",\
"Ich kann folgendes für dich tun:"\
]\
},\
"abbrechen": {\
"match": "\/?abbrechen",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"(%me%) ",\
"Dialog abgebrochen."\
] \
},\
"beenden": {\
"match": "\/?beenden",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"(%me%) ",\
"Dialog beendet."\
]\
}\
}

attr meta_Dialog DbLogExclude .*
attr meta_Dialog allowed everyone
attr meta_Dialog room msg
</pre>

=== Definition beliebiger Dialoge ===

Aufgrund der Komplexität eines Dialogs mit JSON ist es am praktikabelsten, zunächst einen leeren Dialog zu definieren:
<pre>
define <name> msgDialog {}
</pre>

Anschließend kann die DEF in der Detail-Ansicht des Dialog-Device bearbeitet werden. Jeder Dialog basiert auf der folgenden Struktur von einfach bis komplex.

<pre>
{
"<TRIGGER>": {
"match": "<regex>",
"setOnly": (true|false),
"commands": "(fhem command|{perl code})",
"message": [
"{perl code}",
"text"
],
"<NEXT TRIGGER 1>": {
...
},
"<NEXT TRIGGER 2>": {
...
}
}
}
</pre>

Um den JSON-Teil der Dialoge zu testen, empfiehlt sich ein Besuch auf https://jsonlint.com/
Hier kann der selbst geschriebene JSON-Code validiert werden.

== Beispiele ==

==== Programmierung der Waschmaschine ====
Das ist ein Beispiel zur Programmierung einer Waschmaschine wie auch oben im Video zu sehen:
<pre>
defmod Waschmaschine_Dialog msgDialog { "Waschmaschine": {\
"message": [\
"{return('(Zeitprogramm stoppen) ') if(ReadingsVal('%controlUnit%', 'controlMode', '') eq 'auto')}",\
"{return('(programmieren) ') if(ReadingsVal('%actor%', 'state', '') ne 'on')}",\
"{return('(einschalten) ') if(ReadingsVal('%actor%', 'state', '') ne 'on')}",\
"(Verlaufsdiagramm) ",\
"(abbrechen) ",\
"{return('Waschmaschine: ' . (ReadingsVal('%actor%', 'state', '') eq 'on' ? 'eingeschaltet' : 'ausgeschaltet'))}",\
"{return('Modus: ' . (ReadingsVal('%controlUnit%', 'controlMode', '') eq 'auto' ? 'Automatik' : 'Manuell (' . ReadingsVal('%controlUnit%', 'time', '') . ')'))}"\
],\
"Zeitprogramm stoppen": {\
"commands": "set %controlUnit% controlMode manual",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Das Zeitprogramm wurde gestoppt."\
]\
},\
"programmieren": {\
"message": [\
"(bestätigen|zurück|abbrechen) ",\
"( 00:00 | 00:15 | 00:30 | 00:45 ) ",\
"( 01:00 | 01:15 | 01:30 | 01:45 ) ",\
"( 02:00 | 02:15 | 02:30 | 02:45 ) ",\
"( 03:00 | 03:15 | 03:30 | 03:45 ) ",\
"( 04:00 | 04:15 | 04:30 | 04:45 ) ",\
"( 05:00 | 05:15 | 05:30 | 05:45 ) ",\
"( 06:00 | 06:15 | 06:30 | 06:45 ) ",\
"( 07:00 | 07:15 | 07:30 | 07:45 ) ",\
"( 08:00 | 08:15 | 08:30 | 08:45 ) ",\
"( 09:00 | 09:15 | 09:30 | 09:45 ) ",\
"( 10:00 | 10:15 | 10:30 | 10:45 ) ",\
"( 11:00 | 11:15 | 11:30 | 11:45 ) ",\
"( 12:00 | 12:15 | 12:30 | 12:45 ) ",\
"( 13:00 | 13:15 | 13:30 | 13:45 ) ",\
"( 14:00 | 14:15 | 14:30 | 14:45 ) ",\
"( 15:00 | 15:15 | 15:30 | 15:45 ) ",\
"( 16:00 | 16:15 | 16:30 | 16:45 ) ",\
"( 17:00 | 17:15 | 17:30 | 17:45 ) ",\
"( 18:00 | 18:15 | 18:30 | 18:45 ) ",\
"( 19:00 | 19:15 | 19:30 | 19:45 ) ",\
"( 20:00 | 20:15 | 20:30 | 20:45 ) ",\
"( 21:00 | 21:15 | 21:30 | 21:45 ) ",\
"( 22:00 | 22:15 | 22:30 | 22:45 ) ",\
"( 23:00 | 23:15 | 23:30 | 23:45 ) ",\
"Wann soll die Wäsche fertig sein?",\
"Bitte Uhrzeit in HH:MM angeben.",\
"Aktuell ist [%controlUnit%:time] Uhr eingestellt."\
],\
"Uhrzeit": {\
"match": " ?([0-1][0-9]|2[0-3]):[0-5][0-9] ?",\
"commands": [\
"set %controlUnit% time $message",\
"set $SELF say @$recipient Waschmaschine|programmieren|bestätigen"\
]\
},\
"bestätigen": {\
"commands": "set %controlUnit% controlMode auto",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Das Zeitprogramm wurde eingestellt.",\
"Die Wäsche wird voraussichtlich um [%controlUnit%:time] Uhr fertig sein.",\
"Bitte die Waschmaschine vorbereiten."\
]\
}\
},\
"einschalten": {\
"commands": [\
"set %controlUnit% controlMode manual",\
"set %actor% on"\
]\
},\
"Verlaufsdiagramm": {\
"commands": "set %TelegramBot% cmdSend {plotAsPng('%plot%')}",\
"message": "TelegramBot_MTYPE=queryInline (%me%) $message"\
}\
},\
"auto": {\
"setOnly": true,\
"commands": [\
"set %actor% on",\
"set %controlUnit% controlMode manual"\
],\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine wurde automatisch eingeschaltet."\
]\
},\
"manual": {\
"setOnly": true,\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine wurde manuell eingeschaltet."\
]\
},\
"done": {\
"setOnly": true,\
"commands": "set %actor% off",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine ist fertig."\
]\
}\
}
attr Waschmaschine_Dialog evalSpecials actor=HM_2C10D8_Sw\
controlUnit=Waschkeller_washer_controlUnit\
plot=Waschkeller_washer_SVG
</pre>

== TelegramBot: Inline Keyboard verwenden==

In Telegram gibt es die Möglichkeit die Art des Keyboards zu ändern. Links das normale Keyboard, rechts das Inline Keyboard.

[[Datei:76msgDialog menu.png]] [[Datei:76msgDialog menu inline.PNG]]

In diesem '''[https://youtu.be/oRDy2918mVI Video]''' wird Telegram mit einem Inline Keyboard verwendet.

Um eine Nachricht bei Telegram zu verändern, gibt es den Befehl "queryEditInline".
Dafür wird die MsgId von der Nachricht benötigt. Das erledigt ein notify, welches die msgId pro Peer abspeichert:

<pre>
defmod sentMsgIdByPeerId notify .+:sentMsgId.+ {\
return unless($TYPE eq "TelegramBot");;\
\
my $dev_hash = $defs{$NAME};;\
my $sentMsgId = ReadingsVal($NAME, "sentMsgId", "");;\
my $sentMsgPeerId = ReadingsVal($NAME, "sentMsgPeerId", "");;\
my ($contact) = devspec2array("TYPE=(ROOMMATE|GUEST):FILTER=msgContactPush=.*$sentMsgPeerId.*");;\
\
readingsSingleUpdate($dev_hash, "$contact\_sentMsgId", $sentMsgId, 1);;\
}
attr sentMsgIdByPeerId devStateIcon {ReadingsVal($name, "state", "inactive") eq "active" ? ".*:ios-on-blue:inactive" : ".*:ios-off:active"}
attr sentMsgIdByPeerId icon audio_mic
attr sentMsgIdByPeerId room msg
</pre>

Danach wird der Message-Befehl von
<pre>
set <TelegramBot> message
</pre>
auf
<pre>
set <TelegramBot> queryEditInline
</pre>
geändert. Dafür wird ein [[cmdalias]] verwendet:

<pre>
defmod message2queryEditInline cmdalias set .+ message (.|\n)+ AS {\
my ($NAME, $cmd, $message) = split(/[\s]+/, $EVENT, 3);;\
my $TYPE = InternalVal($NAME, "TYPE", "");;\
(my $recipient, $message) = ($message =~ m/(@\S+)? (.+)/s);;\
\
if($TYPE eq "TelegramBot" && $recipient){\
my ($contact) = devspec2array("TYPE=(ROOMMATE|GUEST):FILTER=msgContactPush=.*$recipient.*");;\
my $sentMsgId = ReadingsVal($NAME, "$contact\_sentMsgId", "");;\
\
if($sentMsgId ne ""){\
fhem("set $NAME queryEditInline $sentMsgId $recipient $message");;\
}\
else{\
fhem("set $NAME queryInline $recipient $message");;\
}\
}\
else{\
fhem("set $EVENT");;\
}\
}
attr message2queryEditInline room msg
</pre>

Um wieder zurück zum normalen Keyboard zu gelangen genügt es, das notify und den cmdAlias zu deaktivieren.

Weitere Infos zum Thema Inline Keyboard sind in der Antwort #10 im Forum zu finden (siehe Link unten).

== Links ==
* Thread über das Modul im {{Link2Forum|Topic=77297|LinkText=FHEM Forum}}

[[Kategorie:Gerätemodul]]