msg

MSG
Zweck / Funktion
Versenden von Nachrichten der Typen Audio, Text, Mail, Push, Light, Screen
Allgemein
Typ	Befehl
Details
Dokumentation	EN / DE Thema
Support (Forum)	Automatisierung
Modulname	75_MSG.pm
Ersteller	Loredo
Wichtig: sofern vorhanden, gilt im Zweifel immer die (englische) Beschreibung in der commandref!

Der FHEM-Befehl msg kann dazu benutzt werden, Benachrichtigungen auszugeben.

Der Befehl unterstützt die Nachrichtentypen

• text
• audio
• light
• screen

und kann an ein FHEM Gerät oder an eine eMail Adresse geschickt werden.

Weitere Details zu den Funktionen und zur Benutzung dieses Befehls finden sich im ersten Beitrag dieser Diskussion im Forum.

Der Befehl msg ersetzt ausserdem das vormals verfügbare Modul MSG. Benutzer des alten Moduls müssen ihre Devices auf MSGFile und/oder MSGMail umstellen; bitte dafür das Forenthema "Benutzer von 75_MSG.pm: Aktion notwendig vor Update ab dem 04.11.2015" beachten!

Vorteil

Der Hauptvorteil ist, dass man hier an zentraler Stelle definiert, wie Nachrichten verteilt und zugestellt werden sollen und sich später auch jederzeit zentral anpassen lasst. Dazu muss man dann nicht mehr jedes einzelne Notify, DOIF oder was auch immer anpassen (beispielsweise weil sich der Empfänger geändert hat oder man nun statt dem einen FHEM Modul ein anderes Modul für die Zustellung der Nachricht verwenden möchte).

Gesteuert wird das ganze über das setzen von Attributen. Zum einen am Device "globalMsg" für die Anpassung des Routing Verhaltens sowie einiger Attribute an einem beliebigen FHEM Device, welches die Adressierung des Bewohners oder der Bewohnergruppe ermöglicht. (Für die Profis: Alle globalen Attribute kann man auch per userattr an jedes beliebige Device hinzufügen; es erhält dort dann Vorrang).

Es können auch globale Empfänger konfiguriert werden, dann wird die Angabe eines Empfängers bei den neuen Kommandos optional und sollte einmal ein Empfänger angegeben werden, der keine Kontaktmöglichkeit für Text, Audio oder Visual hinterlegt hat, gibt es einen Fallback auf die globalen Einstellungen (also quasi eine Art Catch-All). Im Falle eines Fallbacks gibt es einen entsprechenden Logeintrag und eine Textnachricht wird entsprechend mit einem Hinweis ergänzt.

Übertragungsmethoden

text

Sendet eine Textnachricht per Push oder E-Mail. Je nach Priorität wird gepusht, gemailt oder beides. E-Mails werden mit der entsprechenden Priorität im Header markiert (dafür sind bei High und Low Prio HTML Mails zwingend erforderlich. Normale Mails werden als Nur-Text gesendet).

Die Befehle, wie gepusht oder gemailt werden soll, können über Attribute am Device "globalMsg" für die Prioritäts-Kategorien "High", "Normal" und "Low" angepasst werden. Standardmäßig wird für Push das Pushover Modul sowie für E-Mail system() per /usr/bin/mail verwendet.

Die Sub-Typen "mail" und "push" können auch explizit für sich aufgerufen werden.

audio

Gibt die Nachricht zunächst als Sprachnachricht weiter. Je nach Priorität wird die Nachricht auch per Text weitergeleitet. Auch kann optional die Anwesenheit des Bewohners berücksichtigt werden (follow me) und die Nachricht wird dann auch als Text weitergeleitet. Außerdem kann über einen Dummy-Switcher gesteuert werden, ob Audio Nachrichten komplett wiedergegeben werden sollen, nur in einer gekürzten Fassung oder gerade überhaupt nicht (Emergency-Prio Nachrichten werden trotzdem immer wiedergegeben). Ich nutze das beispielsweise dafür, dass ich den Switcher auf "short" setze, wenn meine Wohnungstür offen steht, damit meine Nachbarn nicht meine gesamten Audio Benachrichtigungen zu hören kriegen  ;)

Die Befehle zur Audio Wiedergabe können über Attribute am Device "globalMsg" für die Kategorien "Long", "Short with Priority" und "Short" angepasst werden. Der Nachrichtentitel wird hier als |Titel| mit übergeben.

Bei Verwendung von SONOSPLAYER gilt: Ist eine entsprechende Audio-Datei hinterlegt, wird diese dann vor der Nachricht mit eingebunden (Details siehe SONOS Doku). Ich nutze das, um meinen Audio-Nachrichten verschiedene Varianten von einem Gong voran zu stellen (z.B. wie im Flugzeug), damit sich die Bewohner bei einer plötzlichen Ansage nicht so erschrecken 8) Definiert man den Audio-Titel zentral über das Attribut msgTitleAudio, statt ihn in jedem msg-Kommando explizit anzugeben, kann man später auch zentral ändern, welche Sounddatei den Nachrichten vorangestellt werden soll und muss dann nicht überall Anpassungen vornehmen. Weitere Audio-Dateien können natürlich wie in der SONOS Doku beschrieben in den Text über |Dateiname| aufgenommen werden.

light

Verwendet die Nachricht zunächst nur, um eine Leuchte anzusteuern (z.B. HUE). Je nach Priorität (hoch oder normal) kann die Leuchte anders geschaltet werden. Ist die Priorität hoch genug, wird die Nachricht zusätzlich auch per Audio wiedergegeben (dort greifen dann die Routing-Methoden für Audio). Auch hier kann optional die Anwesenheit des Bewohners berücksichtigt werden und die Nachricht alternativ als Text zugestellt werden, sofern die Priorität hoch genug ist.

Die Befehle zur visuellen Wiedergabe können über Attribute am Device "globaMsgl" für die Kategorien "High" und "Normal" angepasst werden. Standardmäßig wird ein einfaches Kommando für HUE Geräte verwendet (select und lselect zum kurzen bzw. längeren blinken).

screen

Ähnlich wie der Typ "light". Standardmäßig wird ein Text an eine ENIGMA2 Box geschickt.

Verwendung

Eine Liste der direkt unterstützten Module, ohne dass man diese händisch einbinden muss, kann man über den get-Befehl "routeCmd" beim Helfer-Device "globalMsg" (sofern es nicht umbenannt wurde) erhalten. Dort kann man auch sehen, mit welcher Syntax ein bestimmtes Modul angesprochen wird und das ggf. als Vorlage für eine eigene Definition per msgCmd-Attribut nehmen.

Die Syntax ist sehr einfach gehalten:

msg [<type>] [<@device|e-mail address>] [<priority>] [|<title>|] <message>

Type kann auch weggelassen werden und ist dann automatisch auf "text" gesetzt. Wenn kein Device und keine E-Mail Adresse angegeben wurden, dann wird automatisch an das globale msgConfig Device (globalMsg) verschickt (ansonsten gibt es eine Fehlermeldung, wenn dort kein passendes msgContact-Attribut gefunden wurde). Auch können mehrere Typen oder Empfänger durch Komma getrennt angegeben werden (Und-Verknüpfung). Eine Oder-Verknüpfung ist ebenso möglich und wird mit einer Pipe (|) zwischen Type und/oder Empfänger gemacht (Oder-Verknüpfung lässt sich auch mit Und-Verknüpfung kombinieren). Bei einer Oder-Verknüpfung wird nur zum nächsten Adressaten gesprungen, sofern für den vorigen keine der angegebenen Nachrichtentypen zugestellt werden konnte. Damit wird auch die automatische Eskalation zu einem anderen Nachrichten-Typ beeinflusst. Diese wird immer nur für den jeweils letzten Eintrag angewendet.

Grundsätzlich sind alle Syntax-Angaben, die oben in eckigen Klammern (also []) stehen, optional. Es wird dann auf entsprechende Standardwerte zurückgegriffen, die entweder über Attribute am Device oder global gesetzt wurden. Ist auch global nichts vorhanden, wird auf interne Standardwerte zurückgegriffen (gilt natürlich nicht für ein Device, denn irgendwo muss man ja immer einen Empfänger angeben  ;) ).

Der Wertebereich für Priorität orientiert sich dabei an der Pushover API mit -2 bis 2. Es kann jedoch grundsätzlich jeder beliebige Wert verwendet werden. Es ist dann Sache des FHEM Moduls, ob der Wertebereich richtig ist oder ob er dort automatisch begrenzt wird (sofern ein FHEM Modul von der Priorität Gebrauch macht, ansonsten wird sie in erster Linie für das Routing innnerhalb des msg-Befehls benutzt).

Sowohl Und-Verknüpfung als auch Oder-Verknüpfung lassen sich ebenfalls in den Contact- und Recipient-Attributen anwenden. Somit bestehen eine Vielzahl von Möglichkeiten für die Adressierung von Empfängern und das Routing über bestimmte Nachrichtentypen.

Konfiguration

Sämtliche Einstellungen werden über Attribute vorgenommen. Dazu gibt es ein Konfigurationsdevice globalMsg in dem die Defaultwerte festgelegt werden. Alles andere passiert durch setzen von Attributen in den einzelnen Devices. Das Device globalMsg wird automatisch bei erster Verwendung von msg angelegt, sofern es nicht gefunden wurde. Alternativ kann es mit

define globalMsg msgConfig 

angelegt werden

Attribute für das Device "msgConfig"

msgCmdAudio (Standard ohne Verwendung Attribut msgSwitcherDev)

Kommando für das "verschicken" von (langen) Audio Mitteilungen. Entweder FHEM-Befehl oder in {} eingeschlossener Perl Befehl.

Verfügbare Variablen:

• %DEVICE%
• %RECIPIENT% (abhängig davon, ob das Modul optional oder verpflichtend eine gesonderte Adressierung des Empfängers vorsieht)
• %TITLE%
• %MSG%
• %PRIORITY%

msgCmdAudioShortPrio (nur in Verbindung mit msgSwitcherDev)

Kommando für das "verschicken" von Audio Mitteilungen mit Switcher Einstellung "short" und einer Prio höher/gleich msgFwPrioEmergencyAudio. Entweder FHEM-Befehl oder in {} eingeschlossener Perl Befehl.

Verfügbare Variablen:

• %DEVICE%
• %RECIPIENT% (abhängig davon, ob das Modul optional oder verpflichtend eine gesonderte Adressierung des Empfängers vorsieht)
• %TITLE%
• %MSG%
• %PRIORITY%

msgCmdAudioShort (nur in Verbindung mit msgSwitcherDev)

Kommando für das "verschicken" von (gekürzten) Audio Mitteilungen mit Switcher Einstellung "short" unabhängig von der Priorität. Entweder FHEM-Befehl oder in {} eingeschlossener Perl Befehl.

Verfügbare Variablen:

• %DEVICE%
• %RECIPIENT% (abhängig davon, ob das Modul optional oder verpflichtend eine gesonderte Adressierung des Empfängers vorsieht)
• %TITLE%
• %MSG%
• %PRIORITY%

msgCmd<TYPE><PrioCat>

Kommando für den jeweilige Nachrichten-Typen und der entsprechenden Nachrichten-Prioritätskategorie

msgFwPrioAbsent<TYPE>

Schwellenwert, ab dem Nachrichten diesen Typs bei kurzer Abwesenheit aller Bewohner per Text weitergeleitet werden sollen. Voreinstellung: 0

msgFwPrioEmergency<TYPE>

Schwellenwert, ab dem Nachrichten diesen Typs als Emergency Prio behandelt werden. Diese Nachrichten werden immer wiedergegeben, unabhängig der Abwesenheit oder der Einstellung long/short am aSwitcherDev Dummy. Voreinstellung: 2

msgFwPrioGone<TYPE>

Schwellenwert, ab dem Nachrichten diesen Typs bei längerer Abwesenheit aller Bewohner per Text weitergeleitet werden sollen. Voreinstellung: 1

msgPriority<TYPE>

Standard Priorität für Nachrichten diesen Typs, sofern nicht in der Nachricht angegeben. Voreinstellung: 0

msgTitle<TYPE><PrioCat>

Standard Betreff für Nachrichten diesen Typs, sofern in der Nachricht keiner angegeben wurde.

msgResidentsDev

FHEM Gerätename, welcher für die Anwesenheit aller Bewohner verwendet wird. Auf dieses Device wird zurückgegriffen, sofern für das Empfänger-Device die entsprechenden Readings nicht vorhanden sind. Bei Verwendung von ROOMMATE, GUEST oder RESIDENTS Devices als Empfänger wird dieses Attribut ignoriert. Das in diesem Attribut angegebene Device muss die Readings "presence" und "state" haben. Es wird die Verwendung eines Devices vom FHEM Typ RESIDENTS empfohlen. Über "presence" wird generell An/Abwesenheit bewertet. Hat "state" den Wert "gone", wird eine längere Abwesenheit angenommen. Für das Weiterleiten von Nachrichten bei längerer Abwesenheit muss die Nachrichten Priorität höher sein, als wenn die Bewohner nur übergangsweise abwesend sind. Siehe auch entsprechende Readings msgFwPrioGone<TYPE> msgFwPrioAbsent<TYPE>.

Readings Wertebereich: presence: present|absent state: gone|*

msgSwitcherDev

FHEM Gerätename, welcher für die Beeinflussung der Länge von Audio Nachrichten verwendet werden soll. Bei "off" findet auch keine visuelle Benachrichtigung mehr statt. Screen Nachrichten sind nicht betroffen. Hier bietet sich ein Dummy Device wie dieses hier an:

define HouseAnn dummy
attr HouseAnn alias Announcements
attr HouseAnn devStateIcon aktiv:general_an@90EE90 active:general_an@90EE90 lang:general_an@green:off aus:general_aus@red:long kurz:general_an@orange:long visuell:general_an@orange:long
attr HouseAnn event-on-change-reading state
attr HouseAnn eventMap active:aktiv long:lang short:kurz visual:visuell off:aus
attr HouseAnn group Automation
attr HouseAnn icon audio_volume_mid
attr HouseAnn room Apartment
attr HouseAnn setList state:lang,kurz,visuell,aus
attr HouseAnn webCmd state

Attribute für alle FHEM Devices

• Für die Verwendung der Fallback und Catchall-Zustellung von Nachrichten können diese Attribute im Device "global" gesetzt werden.
• Nahezu alle globalen Attribute können auch auf ein Device angewendet werden (Ausnahme: msgResidentsDev). Sie tauchen allerdings dort aus Gründen der Übersicht nicht standardmäßig auf. Man muss sie deshalb zuvor als userattr (entweder beim Device oder eben global) hinzufügen, damit man sie setzen kann.

msgContact<TYPE> (zwingend für Nachrichten diesen Typs)

FHEM Gerätename, welcher zur Übermittlung von Nachrichten diesen Typs angesprochen werden soll. Muss bei Audio Nachrichten ohne eigene Definition von msgCmdAudio* ein Gerät vom Typ SONOSPLAYER sein.Muss bei Screen Nachrichten ohne eigene Definition von msgCmdScreen* ein Gerät vom Typ ENIGMA2 sein.Muss bei Light Nachrichten ohne eigene Definition von msgCmdLight* ein Gerät vom Typ HUEDevice sein. Muss bei Push Nachrichten ohne eigene Definition von msgCmdPush* ein Gerät vom Typ Pushover sein. Muss bei Mail Nachrichten eine oder mehrere gültige E-Mail Adressen enthalten. Bei FHEM Gerätenamen, über die mehrere Empfänger adressiert werden können, kann der Empfänger mittels Doppelpunkt getrennt vom FHEM Gerätenamen angegeben werden. Je nach Modul ist das optional oder verbindlich.

msgRecipient<TYPE>

Leitet Nachrichten, die an dieses Gerät adressiert werden, auf ein anderes FHEM Device um. Es wird dann der Wert von msgContact<TYPE> des anderen Gerätes für die Übermittlung der Nachricht verwendet. Bei Nutzung des Attributs mit Typangabe werden nur Nachrichten des entsprechenden Typs umgeleitet. Kombination von msgRecipient mit msgRecipient<TYPE> führt dazu, dass msgRecipient<TYPE> bevorzugt wird.

Follow-Me Funktion

Sobald ein Device, an welches man eine Nachricht schickt, ein Reading "location" beinhaltet, wird geprüft, ob es für diese Lokation eine speziell hinterlegte Kontaktmöglichkeit gibt (z.B. also eine genaue SONOS Soundbox in dem Raum, wo der Bewohner sich gerade befindet).

Gebraucht wird hierfür ein iBeacon zusammen mit dem GEOFANCY Modul. ich empfehle außerdem den Einsatz des ROOMMATE Moduls dazu, weil es die Handhabung der Location gleich mitbringt (Einrichtung siehe Wiki). Man kann aber auch jede andere Möglichkeit der Raumortung nutzen, es muss nur in einem Reading namens "location" enden.

Über das Attribut "msgLocationDevs" können Devices mit Komma getrennt angegeben werden, welche dann für je einen Raum stehen und welche dann dort die msgContact* Attribute hinterlegt haben (Delegationen mittels msgRecipient* funktionieren dort auch). Am einfachsten ist es also pro Raum ein Dummy-Device anzulegen und dieses dann unter dem globalen Attribut "msgLocationDevs" mit aufzuführen.

Wichtig ist, dass dieses Dummy ein Attribut "msgLocationName" enthält, welches dann den exakt gleichen Wortlaut enthalten muss, wie auch im Reading "location" bei dem ROOMMATE Device (also genau der Lokationsname, den ihr z.B. in eurer Geofency.app angegeben habt). Zusätzlich dann eben noch die Type-Contacts. Hier ein Beispiel für Wohnzimmer und Schlafzimmer:

define msgRoom_Living dummy
attr msgRoom_Living msgContactAudio Sonos_Living_Room
attr msgRoom_Living msgContactLight LR_Ceilling,LR_FloorLamp,LR_SofaCorner,LR_DinnerCorner
attr msgRoom_Living msgLocationName Living
attr msgRoom_Living userattr msgLocationName

define msgRoom_Bedroom dummy
attr msgRoom_Bedroom msgContactAudio Sonos_Bedroom
attr msgRoom_Bedroom msgContactLight BR_FloorLamp
attr msgRoom_Bedroom msgLocationName Bedroom
attr msgRoom_Bedroom userattr msgLocationName

Beide Devices sind als globales Attribut verlinkt:

attr global msgLocationDevs msgRoom_Living,msgRoom_Bedroom

Wenn ich nun einen msg-Audio Befehl absetze während ich im Schlafzimmer oder Wohnzimmer bin (Reading ist gleich "Living" oder "Bedroom"), wird die Nachricht auf demjenigen Gerät abgespielt, welches ich für den Raum hinterlegt habe (gleiches gilt für Light-Nachrichten). Wechsle ich den Raum und führe den Befehl nochmal aus, folgt mir auch die Wiedergabe der Nachricht

Beispiele

Bei der ersten Verwendung von msg wird das Konfigurationsdevice globalMsg angelegt. Es kann aber auch vorher manuell angelegt werden.

Pushover

Um mit msg Pushovernachrichten zu versenden ist vorher die Konfiguration eines Pushoverdevices notwendig. Dieses wird dann mit

attr globalMsg msgContactPush <Pushoverdevice>

dem globalMsg als Standardpushoverdevice hinzugefügt.

anschließend kann der Befehl

msg test

verwendet werden. Folgendes passiert: Das msg-Modul erkennt dass eine Nachricht verschickt werden soll. Da kein Übertragungsweg angegeben ist, wird der Standardweg genommen, nämlich text. Bei text wird eine Mail und ein Push verschickt. Da Mail nicht näher definiert ist, wird nur der Push genommen. Da bei Push kein expliziter Empfänger angegeben ist, wird der Empfänger aus dem Attribut von msgContactPush genommen.

Alternativ kann auch direkt ein Push an einen definiertes Pushoverdevice gesendet werden:

msg push @<Pushoverdevice> |FHEM| test

hier wird eine Pushnachricht ein ein definiertes Pushoverdivce mit dem Titel FHEM und der Nachricht test gesendet