MsgDialog

MsgDialog
Zweck / Funktion
Dialoge für Sofortnachrichten über TelegramBot, Jabber und WhatsApp
Allgemein
Typ	Gerätemodul
Details
Dokumentation	EN / DE
Support (Forum)	Frontends
Modulname	76msgDialog.pm
Ersteller	igami
Wichtig: sofern vorhanden, gilt im Zweifel immer die (englische) Beschreibung in der commandref!

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 WhatsApp (yowsup) zu definieren. Dabei können die einzelnen Dialoge für unterschiedliche Nutzer berechtigt werden. Die grundlegende Bedienung wird in diesem Video am Beispiel von TelegramBot gezeigt: https://youtu.be/yiCOTeR1YVQ

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:

sudo apt-get install libjson-perl

Hinweise

Telegram: Es kann notwendig sein, dass im TelegramBot das Attribut "utf8specials" auf "1" gesetzt wird, damit Nachrichten mit Umlauten gesendert werden. Bei dem msg-Befehl kann der TelegramBot_MTYPE angegeben werden. Die Vorgabe ist "message". Durch den Wert "queryInline" lässt sich ein inline Keyboard erzeugen (siehe weiter unten).

Jabber: Bei dem 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 noch keine Erfahungen.

msgDialog und ROOMATE

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.

Definition des msgConfig-Device

Als nächstes benötigt man ein definiertes msgConfig device:

defmod myMsgConfig msgConfig
attr myMsgConfig msgDialog_evalSpecials me=<Aktivierungswort bzw. -Nachricht>
TelegramBot=<Name des TelegramBot-device>
attr myMsgConfig msgContactPush TelegramBot
attr myMsgConfig room msg

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!

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

Definition beliebiger Dialoge

Aufgrund der Komplexität eines Dialogs mit JSON ist es am praktikabelsten, zunächst einen leeren Dialog zu definieren:

define <name> msgDialog {} 

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.

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

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 oben im Video zu sehen:

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

Links

• Thread über das Modul im FHEM Forum