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: Textnachrichten per Push- oder E-Mail-Dienst auf mobile Geräte verschicken
- audio: Sprachnachrichten und akustische Signale über Lautsprecher in der Wohnung ausgeben
- light: optische Signale durch Lampen in der Wohnung anzeigen
- screen: Nachrichten auf einem Bildschirm, etwa einem Fernsehgerät in der Wohnung, anzeigen
und kann an ein FHEM Gerät oder an eine eMail Adresse geschickt werden.
Weitere Details zu den Funktionen und zur Benutzung dieses Befehls finden sich im ersten Beitrag 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 globalMsg 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> 1 |FHEM| test
hier wird eine Pushnachricht ein ein definiertes Pushoverdivce mit der Priorität 1, dem Titel FHEM und der Nachricht test gesendet
Telegram
Der Versand von Nachrichten über Telegram kann anlog zu Pushover verwendet werden. Zunächst muss auch hier ein Telegram-Device angelegt werden.
Anschließend kann dieses in globalMsg als Standardevice festgelgt werden:
attr globalMsg msgContactPush <Telegramdevice>
anschließend kann der Befehl
msg test
verwendet werden. Folgendes passiert:
Alternativ kann auch direkt ein Push an einen definiertes Telegramdevice gesendet werden:
msg push @<Telegramdevice> test
Im vergleich zu Pushover werden Titel und Priorität ignoriert, da Telegram damit nicht umgehen kann.
msg in Verbindung mit ROOMMATES
Werden ROOMMates verwendet dann können jedem ROOMMATE Kontaktdevices hinzugefügt werden. Analog zu diesem Beispiel kann msg nicht nur bei ROOMMATES sondern bei jedem beliebigen FHEM-Device angewendet werden.
attr <ROOMMATEDEVICE> msgContactPush <Pushdevice(s)>
oder konkret:
attr rr_Michael msgContactPush PushoverMichael
bzw. für Telegram:
attr rr_Michael msgContactPush Telegram
bzw. für beide:
attr rr_Michael msgContactPush Telegram,PushoverMichael
Somit kann ich dann ganz einfach über
msg push @rr_Michael |FHEM| Dies ist eine Testnachricht für Michael!
Michael eine Pushnachricht über das in dem Attribut für ihn definierte Device schicken. Sollte sich der ROOMMATE nun dazu entschließen Pushover nicht mehr zu verwenden, so muss nicht an jeder Stelle im Code wo ein Push abgesetzt wird das Device geändert werden, sondern nur an einer Zentralen Stellen, nämlich beim ROOMMATE durch ändern des Attributes.
msg in Verbindung mit RESIDENTS
Möchte man dynamisch Nachrichten an z.B. alle Personen schicken, die gerade zuhause sind, dann kann man sich das RESIDENTS-Modul und die darin vorhandenen Readings zu nutze machen. Alle Anwesenden Personen stehen in dem Reading residentsHomeDevs bzw. residentsTotalRoommatesPresentDevs wenn man zwischen ROOMMATES und GUESTs unterscheidet. Hier sollte man immer das Dev-Reading nutzen, da dort das ROOMMATE-Device angesprochen wird und nicht ggf. ein Alias. Eine Nachricht an alle anwesenden Personen könnte als Beispielsweise so verschickt werden:
msg [msg-typ] @[r<resident-Device>:<Reading des Resident-Devices>] Du bist zuhause
oder konkret
msg push @[rgr_Bewohner:residentsHomeDevs] Du bist zuhause
Es gilt die normale Syntax von MSG. Typ ist beispielsweise Optional und ein Titel kann auch mitgegeben werden. Das Routing des MSG-Moduls Teil dann das Reading in die einzelnen Empfänger auf und schickt in diesem Fall eine Push-Nachricht an die entsprechenden Personen
Lautstärkeanpassung bei Audionachrichten
Um die Lautstärke einer Audioausgabe beim Absetzen des MSG-Befehls anzupassen (wenn diese von den Defaultwerten des msg-Schemas abweichen soll) kann am Ende der Nachricht ein JSON mit Variablen angehangen werden, welche vom Schema (siehe "get globalMsg routeCmd") unterstützt wird oder welche du selbst in einem msgCmd* Attribut verwendest. Für eine Sonos-Nachricht sieht das dann z.B. so aus:
msg audio @Sonos_Bedroom |Hint| Gute Nacht! O[{"VOLUME":"8"}]
Jabber
Der Versand der Nachrichten über Jabber ist ähnlich dem Versand über Telegram. Natürlich muss auch hier zunächst das Jabber-Device eingerichtet werden.
Im msgConfig ist folgendes Attribut zu ergänzen:
attr globalMsg msgContactPush jabberdevice:jabberkontact
Um Nachrichten zu versenden, reicht nun
msg test
Sollen Nachrichten an eine Konferenz/an einem Raum gesendet werden, muss nur der Parameter Jabber_MTYPE=muc mit angegeben werden.
msg push Jabber_MTYPE=muc @JabberClient:raum@conference.jabber.xy Das ist eine Nachricht