FHEMWiki - Benutzerbeiträge [de]

Signalbot

2021-09-27T13:08:02Z

Weini: notify code extended by msgGroup fix from Flachzange

{{Infobox Modul
|ModPurpose=Senden und Empfangen von Nachrichten (Text und Fotos) mit dem freien Messenger Signal
|ModType=x
|ModForumArea=Unterstützende Dienste
|ModFTopic=118370
|ModTechName=50_Signalbot.pm
|ModOwner=Adimarantis ({{Link2FU|39402|Forum}}/[[Benutzer Diskussion:Adimarantis‎|Wiki]])}}

Das Modul [[Signalbot]] ermöglicht den Versand von Nachrichten über den Instant-Messaging-Dienst [https://signal.org Signal] aus FHEM heraus.

== Beschreibung ==
Beschreibung in Kurzform:

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

Aktuell unterstützte Funktionen aus FHEM:
* Senden und Empfangen von Nachrichten an Gruppen oder Einzelempfänger
* Versenden von einem oder mehreren Attachments (Bilder)
* Einlesen, Speichern und Übersetzen von Gruppennamen (statt base64 Strings)
* Setzen, Empfangen und Übersetzen von Kontaktnamen (statt Telefonnummern)
* Einschränken von Gruppen oder Kontakten, auf die FHEM reagieren soll
* Direkte Verknüpfung mit dem [[Modul Babble|Babble]] Modul zur Interpretation von Befehlen
* Authentifizierte Befehle an FHEM senden ({{Link2CmdRef|Anker=GoogleAuth}})
* Blockieren von Kontakten und Gruppen
* Verwalten und Betreten/Verlassen von Gruppen
Neu mit 3.0:
* Registrierung von neuen Nummern inklusive Hilfestellung für Captchas
* Linken von bestehenden Accounts zu FHEM
Die Installation von signal-cli ist aktuell je nach Linux Kenntnissen durchaus anspruchsvoll. Daher gibt es ein Installationsscript welches für aktuelle Ubuntu und Raspian Distributionen getestet ist (höchstwahrscheinlich aber auch für andere Debian basierte Distributionen funktioniert).

Signalbot ist weitgehend kompatibel mit SiSi, verfolgt aber technisch ein paar andere Ansätze und stellt zusätzliche Funktionalitäten zur Verfügung:
* Signalbot erzeugt keinen eigenen Prozess sondern integriert sich voll in die laufende FHEM Instanz (ist dadurch hoffentlich stabiler und verbraucht auch weniger Speicher)
* Gruppen werden grundsätzlich mit ihren Klarnamen verwendet und können auch nur mit einem vorangestellten "#" (statt "@#") gekennzeichnet werden.
* Kontakte werden soweit möglich auch mit Klarnamen (statt +49....) unterstützt. Diese kommen aus dem internen Adressbuch und können über "setContact" definiert werden, bzw. kommen bei verlinkten Accounts aus dem Adressbuch des Hauptgeräts. Sie können aktuell leider nur über empfangene Nachrichten entschlüsselt werden, da signal-cli die entsprechende Schnittstelle (noch) nicht zur Verfügung stellt. Signalbot lernt diese aber mit der Zeit und kann sie bei Bedarf auch so abspeichern, dass sie auch nach einem FHEM Neustart wieder verfügbar sind
* Die Möglichkeit von Telegrambot in den "send" Befehl eingebetteten Code auszuführen und damit z.B. einen SVG Plot zu erstellen und mit zu verschicken ist verfügbar. Dazu muss der Befehl in runde Klammern eingebettet werden (Beispiele folgen unten).
* Wurde mit und für die aktuelle Version 0.9.0 von signal-cli entwickelt, die auch die neuen "V2" Gruppen unterstützt, ebenso wird die neuste Version vom Perl Modul Protocol::DBus (aktuell 0.19) benötigt
* Wird aktiv (September 2021) gewartet (letztes Update für SiSi auf github ist von August 2018)

=== "set" Funktionen im Detail ===
{{Hinweis|Die Beschreibung bezieht sich jetzt auf die aktuelle Version 3.x
Diese Version wird demnächst über FHEM update zur Verfügung gestellt.}}

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

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

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

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

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

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

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

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

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

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

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

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

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

Ist nur eine Telefonnummer registriert, wird diese automatisch verwendet.

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

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

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

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

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

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

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

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

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

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

==== link ====
Zeigt einen QR Code an, den man mit der Signal App auf dem Smartphone scannen kann um FHEM als "Mitbenutzer" zu registrieren. FHEM erhält dann alle Nachrichten und gesendete Nachrichten haben den Absender des Telefons. Dies ist ein einfacher und schneller Weg um Signalbot auszuprobieren, sollte aber nicht für die produktive Benutzung verwendet werden, um unerwünschte Nebeneffekte zu vermeiden.

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

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

''Achtung: Profilnamen werden nur all 24h aktualisiert. Ein Änderung wird also ggf. nicht sofort sichtbar. Ist kein Kontaktname und auch kein Profilname definiert, bleibt das Feld leer. Mit signal-cli 0.8.1 führt das aktuell noch zu einer Fehlermeldung im Logfile, die ignoriert werden kann. Das dürfte mit der nächsten Version behoben sein.''

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

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

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

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

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

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

''Beispiel:''

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

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

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

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

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

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

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

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

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

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

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

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

== Installation ==
Zur Installation steht das Script "signal_install.sh" zur Verfügung, welches aber nicht zwangsweise in jeder Umgebung funktioniert. Daher erst einmal ein paar Referenzen zur manuellen Installation von signal-cli:
* Die Wikiseite des Vorgängermoduls [[SiSi]] welches grundsätzlich die selben Anforderungen hat
* Quickstart (englisch) für [https://github.com/AsamK/signal-cli/wiki/Quickstart signal-cli]
* Anleitung zum [https://github.com/AsamK/signal-cli/wiki/Provide-native-lib-for-libsignal#libsignal-client Übersetzen und Installieren der Libraries] für armv7 (Raspberry) da die Distribution nur x86 libraries enthält
* CPAN Seite des Perl Moduls zur [https://metacpan.org/pod/Protocol::DBus DBus Kommunikation]
Das Modul und Install Script wird demnächst über "fhem [[update]]" verbreitet, ist aber aktuell noch über dieses {{Link2Forum|Topic=118370|LinkText=Forenthema}} zu finden.

Vorbereitung:

Modul 50_Signalbot.pm wie üblich ins Verzeichnis "FHEM" der FHEM Installation kopieren und FHEM neu starten.

Modul per "define <name> Signalbot" definieren.

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

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

Es prüft außerdem ab, ob es im Container läuft ('''**Aktuell nicht unterstützt**''' hier erfolgt ein etwas anderer Ablauf - mehr dazu unten) und prüft auf Betriebssystem und CPU Architektur. Gegebenenfalls bricht es ab, wenn es sich um keine unterstützte Kombination handelt.

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

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

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

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

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

FHEM führt hierbei durch den Prozess mit Hilfestellungen

Ablauf:[[Datei:Signalbot Captcha Chrome.png|mini|Captcha in Chrome]]
# [https://signalcaptchas.org/registration/generate.html Captcha Seite] von Signal aufrufen. Link ist auch direkt in FHEM verfügbar
# Im Developermode (F12) und nach erfolgreichem Lösen des Captchas (wenn der Bildschirm leer bleibt, ist es auch erfolgreich gelöst) macht der Browser ein redirect auf signalcaptcha://. Das versteht der Browser aber nicht und macht gar nichts.
# Der String steht aber bei Firefox in der Console (recht einfach zu finden), beim Chrome muss man auf Network gehen, mit Ctrl+R refreshen und dann in der Spalte "Name" nach einem kryptischen String suchen. Dass dieser mit signalcaptcha anfängt, sieht man erst im Tooltipp, da der Anfang abgeschnitten wird.
# Diesen String dann in FHEM bei "set captcha" eintragen. Jetzt sollte die Registrierung erfolgreich weitergehen (SMS/Anruf).
Anbei Screenshots von Firefox und Chrome zum besseren Verständnis.
[[Datei:Signalbot Captch Firefox.png|mini|Captcha im Firefox]]

'''Captcha "Automatisierung":'''

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

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

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

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

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

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

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

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

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

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

== Umstieg von SiSi ==
Alle die bereits SiSi verwenden können Signalbot erstmal gefahrlos parallel installieren. Einfach Modul ins FHEM Verzeichnis, reload / restart und "define".

Signalbot benötigt allerdings eine andere Dbus Implementierung (Protocol::DBus), diese muss erst installiert werden:
:<syntaxhighlight lang="bash">cpan install -f Protocol::DBus</syntaxhighlight>
Probleme durch eine veraltete '''signal-cli''' Version sind aber nicht ausgeschlossen. Daher keine Support Anfrage ohne vollständigen Umstieg.

Wer komplett umsteigen möchte, kann dies dann mit dem Installer Script tun. Gegebenenfalls Pfade im Script anpassen. Eine bestehende Registrierung wird dann übernommen und muss nicht erneut erfolgen (keine Garantie, dass dies für sehr alte '''signal-cli''' Versionen funktioniert). Wer's ganz sauber haben will, löscht aber alte Installationsreste.

Sofern nach dem SiSi Wiki vorgegangen wurde, dann sind folgende Anpassungen im Script notwendig:
SIGNALPATH=/opt/fhem
SIGNALUSER=fhem
SIGNALVAR=/opt/fhem/.local/share
Das Verzeichnis /opt/fhem/signal-cli kann gelöscht werden.

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

Jetzt kann das Script einfach wie oben beschrieben gestartet werden.

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

auf dem neuen System dann
cd /
sudo tar xvf ''signalconf.tar.gz''
Dann wie üblich das Install Script ausführen.

== Eigene native Libraries übersetzen ==
Signal-cli ist zwar überwiegend in Java geschrieben, hat aber leider zwei binäre libraries die zwingend benötigt werden. Ohne diese Libraries startet der Service nicht.

Das Install Script kann aktuell automatisch die Standard Libraries (Stand signal-cli 0.9.0 ist das für am64 mit glibc-2.31 - was z.B. Ubuntu 20.04 verwendet) durch native libraries für Raspberry (armv7l) unter "Buster" ersetzen.

Meine apt-packages unterstützen zusätzlich noch amd64/libc-2.27, was z.B. Ubuntu 18.04 verwendet. Was aber jetzt wenn ich eine andere Architektur oder glibc habe?

Es gibt mehrere github Projekte um signal-cli die auch fertig übersetzte libsignal_jni.so und libzkgroup.so haben (einfach mal suchen), es ist aber gar nicht so schwer die selber zu übersetzen.

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

Erstmal brauchst du "rust":

<code>sudo curl <nowiki>https://sh.rustup.rs</nowiki> -sSf | sh</code>

Dann die zkgroup libs übersetzen:

<code>git clone git@github.com:signalapp/zkgroup.git</code>

<code>cd ffi/java</code>

<code>make</code>

Da kommt am Schluss ein Fehler, den kann man aber ignorieren, wenn die library erfolgreich erzeugt wurde.

''libzkgroup.so'' aus ''target/release/'' nach ''/opt/signal/lib'' kopieren

Jetzt libsignal-client übersetzen:

<code>git clone git@github.com:signalapp/libsignal-client.git</code>

<code>cd java</code>

<code>./build_jni.sh desktop</code>

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

Libraries in den Java .jar Files durch die selbst compilierten ersetzen:

<code>cd /opt/signal/lib</code>

<code>sudo -u signal-cli zip -u signal-client-java-*.jar libsignal_jni.so</code>

<code>sudo -u signal-cli zip -u zkgroup-java-*.jar libzkgroup.so</code>

Dann Service neu starten

<code>sudo service signal start</code>

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

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

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

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

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

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

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

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

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

== Favoriten und erweiterte Command Funktionen mit einem notify ergänzen ==
Signalbot kann über [[DOIF]]s/[[notify]]s problemlos um individuelle Funktionen erweitert werden. Der hier beschriebene Ansatz ergänzt eine Favoritenverwaltung und erlaubt die direkt Ausführung von FHEM Befehlen entweder mit oder ohne Authentifizierung via GoogleAuth.

Die Beschreibung hier erfolgt auf Basis von Signalbot Version "Signalbot:2.0.1-beta signal-cli:0.8.1 Protocol::DBus:0.16". Bei künftigen Versionen können sich ggf. Änderungen ergeben.

'''Use Case / Szenario'''

Das Signalbot Modul bietet über die Defintion von "allowedPeers" und durch die von Signal bereitgestellte Ende-zu-Ende Verschlüsselung bereits ein hohes Maß an Sicherheit. Für einfache Abfragen von Temperaturen etc. ist das aus Sicht des Autors absolut ausreichend. Diese Abfragen sollten über Favoriten mit möglichst wenig Tipp-Aufwand gesendet werden können.

Für sicherheitskritische / sensible Aktionen ist aber eine zusätzliche Absicherung wünschenswert. Für solche Befehle bietet das Signalbot Modul die Integration von GoogleAuth bereits an. Auch diese Befehle können über Favoritendefinitionen abgekürzt werden. Das GoogleAuth Token wird dann vorab separt geschickt.

'''Voraussetzungen'''
* Das Signalbot Device wird mit "signalBot" benannt (alternativ muss eben der Code im Notify angepasst werden)
* Es werden zusätzliche Attribute via <code>userattr</code> zum Signalbot Device hinzugefügt: cmdKeywordNoAuth cmdPatternNoAuth favPrefix favList <code>attr signalBot userattr cmdKeywordNoAuth cmdPatternNoAuth favPrefix favList</code>
'''Der Notify Code'''
<syntaxhighlight lang="perl">
signalBot:msgText.* {
my $msgText = ReadingsVal("signalBot", "msgText", "");
my $msgAuth = int(ReadingsVal("signalBot", "msgAuth", 0));
my $FhemCmd;
my $cmdPatternNoAuth = AttrVal("signalBot", "cmdPatternNoAuth", undef);
my $favPrefix = AttrVal("signalBot", "favPrefix", undef);
my $cmdKeyword = AttrVal("signalBot", "cmdKeyword", undef);
my $cmdKeywordNoAuth = AttrVal("signalBot", "cmdKeywordNoAuth", undef);
my @favarray;
my @patternarray;
my $favno;
my $favList;
my $retval;
my $msgSender = ReadingsVal("signalBot", "msgSender", "");
my $msgGroup = ReadingsVal("Signalbot", "msgGroupName", "");
if ($msgGroup ne "") { $msgSender = "#" . $msgGroup }
elsif (substr($msgSender, 0, 1) ne "+") { $msgSender = "@" . $msgSender }

# Sicherheitsprüfung für multi-Command Befehl
if (index($msgText, ";") >= 0) {
Log3("ntf_signalBot", 2, "ntf_signalBot: Semicolon detected, sender may try to send multiple commands in one line. Aborting!");
fhem("set signalBot send $msgSender Semicolon detected, command is ignored!");
return;
}

# ggf. Favoriten auflösen
if ($favPrefix && substr($msgText, 0, length($favPrefix)) eq $favPrefix) {
$favno = $favPrefix eq $msgText ? 0 : int(substr($msgText, length($favPrefix)));
@favarray = split(";", AttrVal("signalBot", "favList", undef));

if ($favno == 0) {
# Favoritenliste zurückgeben
Log3("ntf_signalBot", 4, "ntf_signalBot: list favorites");
$favList = "";
$favno = 1;
foreach my $favLine (@favarray) {
$favLine =~ /^\[(.*)\]/;
$favList .= $favPrefix . $favno . "\t" . $1 . "\n";
$favno++;
}
fhem("set signalBot send $msgSender $favList");
return;
} else {
# favoriten verarbeiten
$FhemCmd = $favarray[$favno-1];
# wenn ein Alias definiert ist, dann den Befehlsteil aus dem Favoriten extrahieren
if (index($FhemCmd, "=") >= 0) {
$FhemCmd = substr($FhemCmd, index($FhemCmd, "=")+1);
}
Log3("ntf_signalBot",3,"ntf_signalBot: FhemCmd after favorite substitution: $FhemCmd");
}

# prüfe auf authorsiertes Command (nur wenn Favoriten expandiert wurden, um doppelte Ausführung zu vermeiden
if ($cmdKeyword && substr($FhemCmd, 0, length($cmdKeyword)) eq $cmdKeyword) {
if ($msgAuth) {
Log3("ntf_signalBot", 3, "ntf_signalBot: execute authenticated cmd");
$FhemCmd = substr($FhemCmd, length($cmdKeyword));
$retval = fhem($FhemCmd);
if ($retval) {
fhem("set signalBot send $msgSender $retval");
}
} else {
# Hinweis auf nicht authorsiertes Command
fhem("set signalBot send $msgSender You are not authorized to execute authenticated commands");
}
}
} else {
$FhemCmd = $msgText
}

# prüfe auf nicht authorsiertes Command
if ($cmdKeywordNoAuth && substr($FhemCmd, 0, length($cmdKeywordNoAuth)) eq $cmdKeywordNoAuth) {
# prüfe patterns
Log3("ntf_signalBot", 4, "ntf_signalBot: received non-authenticated cmd, checking patterns");
@patternarray = split(";", AttrVal("signalBot", "cmdPatternNoAuth", undef));
$FhemCmd = substr($FhemCmd, length($cmdKeywordNoAuth));

my $res = 0;
foreach my $secLine (@patternarray) {
$res += eval '$FhemCmd =~ /' . $secLine . '/';
}
if ($res > 0) {
Log3("ntf_signalBot", 3, "ntf_signalBot: execute non-authenticated cmd");
$retval = fhem($FhemCmd);
if ($retval) {
fhem("set signalBot send $msgSender $retval");
}
} else {
Log3("ntf_signalBot", 2, "ntf_signalBot: non-authenticated cmd execution requested, but no pattern match");
fhem("set signalBot send $msgSender You are not authorized to execute this command without authentication");
}
}

}
</syntaxhighlight>
Die Konfiguration erfolgt mit den Attributen am Signal Device. Diese kann z. B. wie folgt aussehen:
<pre>
attr signalBot cmdKeyword /
attr signalBot cmdKeywordNoAuth -
attr signalBot cmdPatternNoAuth get .*;;trigger .*;;getstate .*
attr signalBot favPrefix fav
attr signalBot favList [Wird später]=-trigger ntf_sayTTS "Es wird leider etwas später";;[Öffne Haustüre]=/set Flur_Tueroeffner press;;[Temperaturen]=-trigger listTemperatures
</pre>
Wichtig ist hier, dass <code>cmdKeyword</code> und <code>cmdKeywordNoAuth</code> unterschiedlich sind. '''Das "="-Zeichen darf nicht verwendet werden,''' weil es in der Favoritenliste für die Zuweisung verwendet wird. In der Favoritenliste müssen die FHEM Befehle mit einem Prefix versehen werden, entweder <code>cmdKeyword</code> oder <code>cmdKeywordNoAuth</code>. Ohne Authentifizierung dürfen <code>get, trigger</code> und <code>getstate</code> aufgerufen werden, alle anderen Befehle erfordern Authentifizierung.

'''Anwendung'''

Im Chat hat man nun folgende Optionen:
* Liste aller Favoriten zurückgeben lassen: <code>fav</code>
* Einen Favoriten aufrufen: <code>fav<x></code>, also z. B. fav3 oder fav13
* Einen FHEM Befehl ohne Authentifizierung aufrufen: <code>-get hzgWZ ist_temp</code>
* Einen FHEM Befehl mit Authentifizierung aufrufen: <code>/set hzgWZ soll_temp 22</code> davor muss via <code>/<token></code> also z.B. <code>/394848</code> das aktuelle GoogleAuth Token gesendet werden

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

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

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

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

Führe '''sudo service signal start''' aus.
|-
|'''Bei Starten von signal-cli:'''
OpenJDK Server VM warning: You have loaded library /tmp/resource17792002454964883349.so which might have disabled stack guard. The VM will try to fix the stack guard now.

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

oder

ERROR App - Missing required native library dependency: libsignal-client

oder

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

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

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

Weitere Tests wenn der Fehler nicht behoben ist:
# Welche Library wird vom System verwendet: ''sudo ldconfig -v | grep libzkgroup.so'' beziehungsweise ''sudo ldconfig -v | grep libsignal_jni.so'' . Da die libraries in .jar files eingebettet sind, darf hier keine gefunden werden.
# Check gibt es irgendwo noch eine andere lib.so <code>sudo find / -name libzkgroup.so 2>/dev/null</code> Wenn ja, sicherstellen, dass diese nicht genommen wird (löschen, umbenennen)
# Check gibt es noch irgendwo ein anderes jar <code>sudo find / -name zkgroup-java-*.jar 2>/dev/null</code> Wenn ja, sicherstellen, dass diese nicht genommen wird (löschen, umbenennen)
# (für den zweiten Fehler, die Schritte 2 und 3 mit libsignal_jni.so bzw. signal-client-java-*.jar durchführen
|-
|Ich kann an Einzelempfänger senden und empfangen, aber nicht an Gruppen versenden
|Du hast wahrscheinlich den vorhergehenden Fehler (libzkgroup) irgendwo, aber er ist dir nicht aufgefallen. Vorgehensweise wie oben.
|-
|Ich kann keiner Gruppe beitreten und/oder nichts an eine Gruppe schicken.
oder

Error in invite:org.asamk.Signal.Error.Failure: Cannot join a V2 group as self does not have a versioned profile
|Die neuen V2 Gruppen benötigen zwingend einen Profil Namen. Sofern also nach der Registrierung keiner gesetzt wurde, kann man keine Gruppen verwenden.
Abhilfe:

'''sudo -E ./signal_install.sh name'''

um einen Namen (und optional ein Avatarbild) festzulegen.
|}

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

[[Kategorie:Messenger]]

Signalbot

2021-09-27T11:48:21Z

Weini: Patch von Flachzange für Favoriten Handling eingepflegt.

{{Infobox Modul
|ModPurpose=Senden und Empfangen von Nachrichten (Text und Fotos) mit dem freien Messenger Signal
|ModType=x
|ModForumArea=Unterstützende Dienste
|ModFTopic=118370
|ModTechName=50_Signalbot.pm
|ModOwner=Adimarantis ({{Link2FU|39402|Forum}}/[[Benutzer Diskussion:Adimarantis‎|Wiki]])}}

Das Modul [[Signalbot]] ermöglicht den Versand von Nachrichten über den Instant-Messaging-Dienst [https://signal.org Signal] aus FHEM heraus.

== Beschreibung ==
Beschreibung in Kurzform:

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

Aktuell unterstützte Funktionen aus FHEM:
* Senden und Empfangen von Nachrichten an Gruppen oder Einzelempfänger
* Versenden von einem oder mehreren Attachments (Bilder)
* Einlesen, Speichern und Übersetzen von Gruppennamen (statt base64 Strings)
* Setzen, Empfangen und Übersetzen von Kontaktnamen (statt Telefonnummern)
* Einschränken von Gruppen oder Kontakten, auf die FHEM reagieren soll
* Direkte Verknüpfung mit dem [[Modul Babble|Babble]] Modul zur Interpretation von Befehlen
* Authentifizierte Befehle an FHEM senden ({{Link2CmdRef|Anker=GoogleAuth}})
* Blockieren von Kontakten und Gruppen
* Verwalten und Betreten/Verlassen von Gruppen
Neu mit 3.0:
* Registrierung von neuen Nummern inklusive Hilfestellung für Captchas
* Linken von bestehenden Accounts zu FHEM
Die Installation von signal-cli ist aktuell je nach Linux Kenntnissen durchaus anspruchsvoll. Daher gibt es ein Installationsscript welches für aktuelle Ubuntu und Raspian Distributionen getestet ist (höchstwahrscheinlich aber auch für andere Debian basierte Distributionen funktioniert).

Signalbot ist weitgehend kompatibel mit SiSi, verfolgt aber technisch ein paar andere Ansätze und stellt zusätzliche Funktionalitäten zur Verfügung:
* Signalbot erzeugt keinen eigenen Prozess sondern integriert sich voll in die laufende FHEM Instanz (ist dadurch hoffentlich stabiler und verbraucht auch weniger Speicher)
* Gruppen werden grundsätzlich mit ihren Klarnamen verwendet und können auch nur mit einem vorangestellten "#" (statt "@#") gekennzeichnet werden.
* Kontakte werden soweit möglich auch mit Klarnamen (statt +49....) unterstützt. Diese kommen aus dem internen Adressbuch und können über "setContact" definiert werden, bzw. kommen bei verlinkten Accounts aus dem Adressbuch des Hauptgeräts. Sie können aktuell leider nur über empfangene Nachrichten entschlüsselt werden, da signal-cli die entsprechende Schnittstelle (noch) nicht zur Verfügung stellt. Signalbot lernt diese aber mit der Zeit und kann sie bei Bedarf auch so abspeichern, dass sie auch nach einem FHEM Neustart wieder verfügbar sind
* Die Möglichkeit von Telegrambot in den "send" Befehl eingebetteten Code auszuführen und damit z.B. einen SVG Plot zu erstellen und mit zu verschicken ist verfügbar. Dazu muss der Befehl in runde Klammern eingebettet werden (Beispiele folgen unten).
* Wurde mit und für die aktuelle Version 0.9.0 von signal-cli entwickelt, die auch die neuen "V2" Gruppen unterstützt, ebenso wird die neuste Version vom Perl Modul Protocol::DBus (aktuell 0.19) benötigt
* Wird aktiv (September 2021) gewartet (letztes Update für SiSi auf github ist von August 2018)

=== "set" Funktionen im Detail ===
{{Hinweis|Die Beschreibung bezieht sich jetzt auf die aktuelle Version 3.x
Diese Version wird demnächst über FHEM update zur Verfügung gestellt.}}

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

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

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

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

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

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

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

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

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

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

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

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

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

Ist nur eine Telefonnummer registriert, wird diese automatisch verwendet.

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

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

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

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

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

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

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

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

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

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

==== link ====
Zeigt einen QR Code an, den man mit der Signal App auf dem Smartphone scannen kann um FHEM als "Mitbenutzer" zu registrieren. FHEM erhält dann alle Nachrichten und gesendete Nachrichten haben den Absender des Telefons. Dies ist ein einfacher und schneller Weg um Signalbot auszuprobieren, sollte aber nicht für die produktive Benutzung verwendet werden, um unerwünschte Nebeneffekte zu vermeiden.

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

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

''Achtung: Profilnamen werden nur all 24h aktualisiert. Ein Änderung wird also ggf. nicht sofort sichtbar. Ist kein Kontaktname und auch kein Profilname definiert, bleibt das Feld leer. Mit signal-cli 0.8.1 führt das aktuell noch zu einer Fehlermeldung im Logfile, die ignoriert werden kann. Das dürfte mit der nächsten Version behoben sein.''

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

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

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

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

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

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

''Beispiel:''

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

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

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

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

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

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

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

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

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

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

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

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

== Installation ==
Zur Installation steht das Script "signal_install.sh" zur Verfügung, welches aber nicht zwangsweise in jeder Umgebung funktioniert. Daher erst einmal ein paar Referenzen zur manuellen Installation von signal-cli:
* Die Wikiseite des Vorgängermoduls [[SiSi]] welches grundsätzlich die selben Anforderungen hat
* Quickstart (englisch) für [https://github.com/AsamK/signal-cli/wiki/Quickstart signal-cli]
* Anleitung zum [https://github.com/AsamK/signal-cli/wiki/Provide-native-lib-for-libsignal#libsignal-client Übersetzen und Installieren der Libraries] für armv7 (Raspberry) da die Distribution nur x86 libraries enthält
* CPAN Seite des Perl Moduls zur [https://metacpan.org/pod/Protocol::DBus DBus Kommunikation]
Das Modul und Install Script wird demnächst über "fhem [[update]]" verbreitet, ist aber aktuell noch über dieses {{Link2Forum|Topic=118370|LinkText=Forenthema}} zu finden.

Vorbereitung:

Modul 50_Signalbot.pm wie üblich ins Verzeichnis "FHEM" der FHEM Installation kopieren und FHEM neu starten.

Modul per "define <name> Signalbot" definieren.

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

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

Es prüft außerdem ab, ob es im Container läuft ('''**Aktuell nicht unterstützt**''' hier erfolgt ein etwas anderer Ablauf - mehr dazu unten) und prüft auf Betriebssystem und CPU Architektur. Gegebenenfalls bricht es ab, wenn es sich um keine unterstützte Kombination handelt.

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

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

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

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

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

FHEM führt hierbei durch den Prozess mit Hilfestellungen

Ablauf:[[Datei:Signalbot Captcha Chrome.png|mini|Captcha in Chrome]]
# [https://signalcaptchas.org/registration/generate.html Captcha Seite] von Signal aufrufen. Link ist auch direkt in FHEM verfügbar
# Im Developermode (F12) und nach erfolgreichem Lösen des Captchas (wenn der Bildschirm leer bleibt, ist es auch erfolgreich gelöst) macht der Browser ein redirect auf signalcaptcha://. Das versteht der Browser aber nicht und macht gar nichts.
# Der String steht aber bei Firefox in der Console (recht einfach zu finden), beim Chrome muss man auf Network gehen, mit Ctrl+R refreshen und dann in der Spalte "Name" nach einem kryptischen String suchen. Dass dieser mit signalcaptcha anfängt, sieht man erst im Tooltipp, da der Anfang abgeschnitten wird.
# Diesen String dann in FHEM bei "set captcha" eintragen. Jetzt sollte die Registrierung erfolgreich weitergehen (SMS/Anruf).
Anbei Screenshots von Firefox und Chrome zum besseren Verständnis.
[[Datei:Signalbot Captch Firefox.png|mini|Captcha im Firefox]]

'''Captcha "Automatisierung":'''

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

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

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

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

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

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

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

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

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

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

== Umstieg von SiSi ==
Alle die bereits SiSi verwenden können Signalbot erstmal gefahrlos parallel installieren. Einfach Modul ins FHEM Verzeichnis, reload / restart und "define".

Signalbot benötigt allerdings eine andere Dbus Implementierung (Protocol::DBus), diese muss erst installiert werden:
:<syntaxhighlight lang="bash">cpan install -f Protocol::DBus</syntaxhighlight>
Probleme durch eine veraltete '''signal-cli''' Version sind aber nicht ausgeschlossen. Daher keine Support Anfrage ohne vollständigen Umstieg.

Wer komplett umsteigen möchte, kann dies dann mit dem Installer Script tun. Gegebenenfalls Pfade im Script anpassen. Eine bestehende Registrierung wird dann übernommen und muss nicht erneut erfolgen (keine Garantie, dass dies für sehr alte '''signal-cli''' Versionen funktioniert). Wer's ganz sauber haben will, löscht aber alte Installationsreste.

Sofern nach dem SiSi Wiki vorgegangen wurde, dann sind folgende Anpassungen im Script notwendig:
SIGNALPATH=/opt/fhem
SIGNALUSER=fhem
SIGNALVAR=/opt/fhem/.local/share
Das Verzeichnis /opt/fhem/signal-cli kann gelöscht werden.

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

Jetzt kann das Script einfach wie oben beschrieben gestartet werden.

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

auf dem neuen System dann
cd /
sudo tar xvf ''signalconf.tar.gz''
Dann wie üblich das Install Script ausführen.

== Eigene native Libraries übersetzen ==
Signal-cli ist zwar überwiegend in Java geschrieben, hat aber leider zwei binäre libraries die zwingend benötigt werden. Ohne diese Libraries startet der Service nicht.

Das Install Script kann aktuell automatisch die Standard Libraries (Stand signal-cli 0.9.0 ist das für am64 mit glibc-2.31 - was z.B. Ubuntu 20.04 verwendet) durch native libraries für Raspberry (armv7l) unter "Buster" ersetzen.

Meine apt-packages unterstützen zusätzlich noch amd64/libc-2.27, was z.B. Ubuntu 18.04 verwendet. Was aber jetzt wenn ich eine andere Architektur oder glibc habe?

Es gibt mehrere github Projekte um signal-cli die auch fertig übersetzte libsignal_jni.so und libzkgroup.so haben (einfach mal suchen), es ist aber gar nicht so schwer die selber zu übersetzen.

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

Erstmal brauchst du "rust":

<code>sudo curl <nowiki>https://sh.rustup.rs</nowiki> -sSf | sh</code>

Dann die zkgroup libs übersetzen:

<code>git clone git@github.com:signalapp/zkgroup.git</code>

<code>cd ffi/java</code>

<code>make</code>

Da kommt am Schluss ein Fehler, den kann man aber ignorieren, wenn die library erfolgreich erzeugt wurde.

''libzkgroup.so'' aus ''target/release/'' nach ''/opt/signal/lib'' kopieren

Jetzt libsignal-client übersetzen:

<code>git clone git@github.com:signalapp/libsignal-client.git</code>

<code>cd java</code>

<code>./build_jni.sh desktop</code>

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

Libraries in den Java .jar Files durch die selbst compilierten ersetzen:

<code>cd /opt/signal/lib</code>

<code>sudo -u signal-cli zip -u signal-client-java-*.jar libsignal_jni.so</code>

<code>sudo -u signal-cli zip -u zkgroup-java-*.jar libzkgroup.so</code>

Dann Service neu starten

<code>sudo service signal start</code>

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

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

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

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

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

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

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

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

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

== Favoriten und erweiterte Command Funktionen mit einem notify ergänzen ==
Signalbot kann über [[DOIF]]s/[[notify]]s problemlos um individuelle Funktionen erweitert werden. Der hier beschriebene Ansatz ergänzt eine Favoritenverwaltung und erlaubt die direkt Ausführung von FHEM Befehlen entweder mit oder ohne Authentifizierung via GoogleAuth.

Die Beschreibung hier erfolgt auf Basis von Signalbot Version "Signalbot:2.0.1-beta signal-cli:0.8.1 Protocol::DBus:0.16". Bei künftigen Versionen können sich ggf. Änderungen ergeben.

'''Use Case / Szenario'''

Das Signalbot Modul bietet über die Defintion von "allowedPeers" und durch die von Signal bereitgestellte Ende-zu-Ende Verschlüsselung bereits ein hohes Maß an Sicherheit. Für einfache Abfragen von Temperaturen etc. ist das aus Sicht des Autors absolut ausreichend. Diese Abfragen sollten über Favoriten mit möglichst wenig Tipp-Aufwand gesendet werden können.

Für sicherheitskritische / sensible Aktionen ist aber eine zusätzliche Absicherung wünschenswert. Für solche Befehle bietet das Signalbot Modul die Integration von GoogleAuth bereits an. Auch diese Befehle können über Favoritendefinitionen abgekürzt werden. Das GoogleAuth Token wird dann vorab separt geschickt.

'''Voraussetzungen'''
* Das Signalbot Device wird mit "signalBot" benannt (alternativ muss eben der Code im Notify angepasst werden)
* Es werden zusätzliche Attribute via <code>userattr</code> zum Signalbot Device hinzugefügt: cmdKeywordNoAuth cmdPatternNoAuth favPrefix favList <code>attr signalBot userattr cmdKeywordNoAuth cmdPatternNoAuth favPrefix favList</code>
'''Der Notify Code'''
<syntaxhighlight lang="perl">
signalBot:msgText.* {
my $msgText = ReadingsVal("signalBot", "msgText", "");
my $msgAuth = int(ReadingsVal("signalBot", "msgAuth", 0));
my $FhemCmd;
my $cmdPatternNoAuth = AttrVal("signalBot", "cmdPatternNoAuth", undef);
my $favPrefix = AttrVal("signalBot", "favPrefix", undef);
my $cmdKeyword = AttrVal("signalBot", "cmdKeyword", undef);
my $cmdKeywordNoAuth = AttrVal("signalBot", "cmdKeywordNoAuth", undef);
my @favarray;
my @patternarray;
my $favno;
my $favList;
my $retval;
my $msgSender = ReadingsVal("signalBot", "msgSender", "");
if (substr($msgSender, 0, 1) ne "+") { $msgSender = "@" . $msgSender }

# Sicherheitsprüfung für multi-Command Befehl
if (index($msgText, ";") >= 0) {
Log3("ntf_signalBot", 2, "ntf_signalBot: Semicolon detected, sender may try to send multiple commands in one line. Aborting!");
fhem("set signalBot send $msgSender Semicolon detected, command is ignored!");
return;
}

# ggf. Favoriten auflösen
if ($favPrefix && substr($msgText, 0, length($favPrefix)) eq $favPrefix) {
$favno = $favPrefix eq $msgText ? 0 : int(substr($msgText, length($favPrefix)));
@favarray = split(";", AttrVal("signalBot", "favList", undef));

if ($favno == 0) {
# Favoritenliste zurückgeben
Log3("ntf_signalBot", 4, "ntf_signalBot: list favorites");
$favList = "";
$favno = 1;
foreach my $favLine (@favarray) {
$favLine =~ /^\[(.*)\]/;
$favList .= $favPrefix . $favno . "\t" . $1 . "\n";
$favno++;
}
fhem("set signalBot send $msgSender $favList");
return;
} else {
# favoriten verarbeiten
$FhemCmd = $favarray[$favno-1];
# wenn ein Alias definiert ist, dann den Befehlsteil aus dem Favoriten extrahieren
if (index($FhemCmd, "=") >= 0) {
$FhemCmd = substr($FhemCmd, index($FhemCmd, "=")+1);
}
Log3("ntf_signalBot",3,"ntf_signalBot: FhemCmd after favorite substitution: $FhemCmd");
}

# prüfe auf authorsiertes Command (nur wenn Favoriten expandiert wurden, um doppelte Ausführung zu vermeiden
if ($cmdKeyword && substr($FhemCmd, 0, length($cmdKeyword)) eq $cmdKeyword) {
if ($msgAuth) {
Log3("ntf_signalBot", 3, "ntf_signalBot: execute authenticated cmd");
$FhemCmd = substr($FhemCmd, length($cmdKeyword));
$retval = fhem($FhemCmd);
if ($retval) {
fhem("set signalBot send $msgSender $retval");
}
} else {
# Hinweis auf nicht authorsiertes Command
fhem("set signalBot send $msgSender You are not authorized to execute authenticated commands");
}
}
} else {
$FhemCmd = $msgText
}

# prüfe auf nicht authorsiertes Command
if ($cmdKeywordNoAuth && substr($FhemCmd, 0, length($cmdKeywordNoAuth)) eq $cmdKeywordNoAuth) {
# prüfe patterns
Log3("ntf_signalBot", 4, "ntf_signalBot: received non-authenticated cmd, checking patterns");
@patternarray = split(";", AttrVal("signalBot", "cmdPatternNoAuth", undef));
$FhemCmd = substr($FhemCmd, length($cmdKeywordNoAuth));

my $res = 0;
foreach my $secLine (@patternarray) {
$res += eval '$FhemCmd =~ /' . $secLine . '/';
}
if ($res > 0) {
Log3("ntf_signalBot", 3, "ntf_signalBot: execute non-authenticated cmd");
$retval = fhem($FhemCmd);
if ($retval) {
fhem("set signalBot send $msgSender $retval");
}
} else {
Log3("ntf_signalBot", 2, "ntf_signalBot: non-authenticated cmd execution requested, but no pattern match");
fhem("set signalBot send $msgSender You are not authorized to execute this command without authentication");
}
}

}
</syntaxhighlight>
Die Konfiguration erfolgt mit den Attributen am Signal Device. Diese kann z. B. wie folgt aussehen:
<pre>
attr signalBot cmdKeyword /
attr signalBot cmdKeywordNoAuth -
attr signalBot cmdPatternNoAuth get .*;;trigger .*;;getstate .*
attr signalBot favPrefix fav
attr signalBot favList [Wird später]=-trigger ntf_sayTTS "Es wird leider etwas später";;[Öffne Haustüre]=/set Flur_Tueroeffner press;;[Temperaturen]=-trigger listTemperatures
</pre>
Wichtig ist hier, dass <code>cmdKeyword</code> und <code>cmdKeywordNoAuth</code> unterschiedlich sind. '''Das "="-Zeichen darf nicht verwendet werden,''' weil es in der Favoritenliste für die Zuweisung verwendet wird. In der Favoritenliste müssen die FHEM Befehle mit einem Prefix versehen werden, entweder <code>cmdKeyword</code> oder <code>cmdKeywordNoAuth</code>. Ohne Authentifizierung dürfen <code>get, trigger</code> und <code>getstate</code> aufgerufen werden, alle anderen Befehle erfordern Authentifizierung.

'''Anwendung'''

Im Chat hat man nun folgende Optionen:
* Liste aller Favoriten zurückgeben lassen: <code>fav</code>
* Einen Favoriten aufrufen: <code>fav<x></code>, also z. B. fav3 oder fav13
* Einen FHEM Befehl ohne Authentifizierung aufrufen: <code>-get hzgWZ ist_temp</code>
* Einen FHEM Befehl mit Authentifizierung aufrufen: <code>/set hzgWZ soll_temp 22</code> davor muss via <code>/<token></code> also z.B. <code>/394848</code> das aktuelle GoogleAuth Token gesendet werden

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

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

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

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

Führe '''sudo service signal start''' aus.
|-
|'''Bei Starten von signal-cli:'''
OpenJDK Server VM warning: You have loaded library /tmp/resource17792002454964883349.so which might have disabled stack guard. The VM will try to fix the stack guard now.

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

oder

ERROR App - Missing required native library dependency: libsignal-client

oder

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

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

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

Weitere Tests wenn der Fehler nicht behoben ist:
# Welche Library wird vom System verwendet: ''sudo ldconfig -v | grep libzkgroup.so'' beziehungsweise ''sudo ldconfig -v | grep libsignal_jni.so'' . Da die libraries in .jar files eingebettet sind, darf hier keine gefunden werden.
# Check gibt es irgendwo noch eine andere lib.so <code>sudo find / -name libzkgroup.so 2>/dev/null</code> Wenn ja, sicherstellen, dass diese nicht genommen wird (löschen, umbenennen)
# Check gibt es noch irgendwo ein anderes jar <code>sudo find / -name zkgroup-java-*.jar 2>/dev/null</code> Wenn ja, sicherstellen, dass diese nicht genommen wird (löschen, umbenennen)
# (für den zweiten Fehler, die Schritte 2 und 3 mit libsignal_jni.so bzw. signal-client-java-*.jar durchführen
|-
|Ich kann an Einzelempfänger senden und empfangen, aber nicht an Gruppen versenden
|Du hast wahrscheinlich den vorhergehenden Fehler (libzkgroup) irgendwo, aber er ist dir nicht aufgefallen. Vorgehensweise wie oben.
|-
|Ich kann keiner Gruppe beitreten und/oder nichts an eine Gruppe schicken.
oder

Error in invite:org.asamk.Signal.Error.Failure: Cannot join a V2 group as self does not have a versioned profile
|Die neuen V2 Gruppen benötigen zwingend einen Profil Namen. Sofern also nach der Registrierung keiner gesetzt wurde, kann man keine Gruppen verwenden.
Abhilfe:

'''sudo -E ./signal_install.sh name'''

um einen Namen (und optional ein Avatarbild) festzulegen.
|}

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

[[Kategorie:Messenger]]

Signalbot

2021-03-07T11:12:02Z

Weini: Erweiterung via notify für Favoriten (Teil 2)

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

== Beschreibung ==
Beschreibung in Kurzform:

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

Da sich signal-cli noch in der Entwicklung befindet (aktuelle Version 0.7.4) steht leider noch nicht die volle Funktionalität über DBus zur Verfügung, wodurch sich auch Einschränkungen für FHEM ergeben.

Aktuell unterstütze Funktionen aus FHEM:
* Senden und Empfangen von Nachrichten an Gruppen oder Einzelempfänger
* Versenden von einem oder mehreren Attachments (Bilder)
* Einlesen, Speichern und Übersetzen von Gruppennamen (statt base64 Strings)
* Setzen, Empfangen und Übersetzen von Kontaktnamen (statt Telefonnummern)
* Einschränken von Gruppen oder Kontakten auf die FHEM reagieren soll
* Direkte Verknüpfung mit dem [[Modul Babble|Babble]] Modul zur Interpretation von Befehlen
Die Installation von signal-cli ist aktuell je nach Linux Kenntnissen durchaus anspruchsvoll. Daher gibt es ein Installationsscript welches aktuell für aktuelle Ubuntu und Raspian Distributionen getestet ist (höchstwahrscheinlich aber auch für andere Debian basierte Distributionen funktioniert)

Signalbot ist weitgehend kompatibel mit SiSi, verfolgt aber technisch ein paar andere Ansätze und stellt zusätzliche Funktionalitäten zur Verfügung:
* Signalbot erzeugt keinen eigenen Prozess sondern integriert sich voll in die laufende FHEM Instanz (ist dadurch hoffentlich stabiler und verbraucht auch weniger Speicher)
* Gruppen werden grundsätzlich mit ihren Klarnamen verwendet und können auch nur mit einem vorangestellten "#" (statt "@#") gekennzeichnet werden.
* Kontakte werden soweit möglich auch mit Klarnamen (statt +49....) unterstützt. Diese kommen aus dem internen Adressbuch und können über "setContact" definiert werden, bzw. kommen bei verlinkten Accounts aus dem Adressbuch des Hauptgeräts. Sie können aktuell leider nur über empfangene Nachrichten entschlüsselt werden, da signal-cli die entsprechende Schnittstelle (noch) nicht zur Verfügung stellt. Signalbot lernt diese aber mit der Zeit und kann sie bei Bedarf auch so abspeichern, dass sie auch nach einem FHEM Neustart wieder verfügbar sind
* Die Möglichkeit von Telegrambot in den "send" Befehl eingebetteten Code auszuführen und damit z.B. einen SVG Plot zu erstellen und mit zu verschicken ist verfügbar. Dazu muss der Befehl in runde Klammern eingebettet werden (Beispiele folgen unten).
* Wurde mit und für die aktuelle Version 0.7.4 von signal-cli entwickelt, die auch die neuen "V2" Gruppen unterstützt, ebenso wird die neuste Version (1.2.0) vom Perl Modul Net::DBus benötigt
* Wird aktiv(Feb 2021) gewartet (letztes Update für SiSi auf github ist von August 2018)

=== Funktionen im Detail ===

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

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

==== refreshGroups ====
Fragt die List der aktuellen Gruppen ab, denen der verknüpfte Account beigetreten ist. Die Liste wird im u.a. Reading '''joinedGroups''' sichtbar gemacht.

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

==== saveContacts ====
Speichert die interne Kontaktliste in das Reading '''contactList''' welches beim Speichern der FHEM Config in ''fhem.save'' abgelegt wird und nach einem Neustart wieder zur Verfügung steht (zur Diskussion: immer automatisch so machen wenn neue Kontakte festgelegt werden?)

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

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

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

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

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

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

=== Attribute im Detail ===

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

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

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

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

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

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

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

=== Readings im Detail ===
{| class="wikitable"
|contactList
|Liste der gespeicherten Kontakt im Format ''Nummer1=Kontakt1,Nummer2=Kontakt2,...''
|-
|joinedGroups
|Liste der beigetretenen Gruppen getrennt mit Leerzeichen
|-
|msgAttachment
|Attachments (Dateinamen im signal-cli repository) der zuletzt empfangenen Attachments
|-
|msgGroupName
|Gruppenname aus der zuletzt eine Nachricht empfangen wurde - leer wenn es eine persönlich Nachricht war
|-
|msgSender
|Absender der letzten Nachricht als Nummer oder wenn bekannt als Name
|-
|msgText
|Empfangenen Nachricht
|-
|msgTimestamp
|Zeitstempel der Nachricht
|-
|prevMsgAttachment
| rowspan="5" |Wie oben, nur enthalten diese Readings die Daten der zuvor empfangenen Nachricht (n-1)
|-
|prevMsgGroupName
|-
|prevMsgSender
|-
|prevMsgText
|-
|prevMsgTimestamp
|-
|sentMsg
|Zuletzt gesendete Nachricht
|-
|sentMsgRecipient
|Empfänger der zuletzt gesendeten Nachricht. Enthält zumeist den Namen aus der Empfangsbestätigung und somit bei vielen Empfängern den zuletzt bestätigten Empfang.

Dies muss nicht zwingend auf die zuletzt gesendete Nachricht (sendMsg) passen, wenn mehrere Nachrichten versendet wurden.
|-
|sentMsgTimestamp
|Zeitstempel des Empfangs oder "pending" wenn noch keine Bestätigung vorliegt
|}

== Installation ==
Zur Installation steht das Script "signal_install.sh" zur Verfügung. Dieses befindet sich noch in der Entwicklung und funktioniert nicht zwangsweise in jeder Umgebung. Daher erst einmal ein paar Referenzen zur manuellen Installation von signal-cli:
* Die Wikiseite des Vorgängermoduls [[SiSi]] welches grundsätzlich die selben Anforderungen hat
* Quickstart (englisch) für [https://github.com/AsamK/signal-cli/wiki/Quickstart signal-cli]
* Anleitung zum [https://github.com/AsamK/signal-cli/wiki/Linking-other-devices-%28Provisioning%29 "linken" einer Nummer] mit signal-cli
* Anleitung zum [https://github.com/AsamK/signal-cli/wiki/Provide-native-lib-for-libsignal#libsignal-client Übersetzen und Installieren der Libraries] für armv7 (Raspberry) da die Distribution nur x86 libraries enthält
* CPAN Seite des Perl Moduls zur [https://metacpan.org/release/Net-DBus DBus Kommunikation]
Das Modul und Install Script wird aktuell nicht über "fhem [[update]]" verbreitet und muss vom ersten Post dieses {{Link2Forum|Topic=118370|LinkText=Forenthemas}} geholt werden.

Vorbereitung:

Modul 50_Signalbot.pm wie üblich ins Verzeichnis "FHEM" der FHEM Installation kopieren.

Das Script "signal_install.sh" ins home Verzeichnis eines beliebigen "sudo"-fähigen Users kopieren.

Am Anfang des Moduls sind einige Informationen und Pfade definiert. Mindestvorrausetzung ist eine Telefonnummer. Es kann eine Festnetznummer oder Mobilfunknummer verwendet werden. Wird Signal schon am Handy benutzt lässt sich die Nummer verknüpfen, was aber den unangenehmen Nebeneffekt hat, dass man dort alle FHEM Nachrichten mitbekommt.

Kontrolliert also bitte vor dem Start des Scripts diese Angaben. Außer bei ''PHONE=+49xxxxx'' sollte aber üblicherweise keine Änderung nötig sein. Wird das sudo mit ''-E'' ausgeführt, so bewirkt das die Übernahme der Environment Variablen. Wenn mit ''export PHONE=+49xxxx'' die Telefonnummer z.B. bereits im ''.bash_profile'' gesetzt wurde, muss das Script nicht mehr editiert werden.

Das Script hat mehrere Optionen um Teilfunktionen direkt auszuführen, diese sind:
{| class="wikitable"
|+
!Argument
!Bedeutung
|-
|system
|System für die signal-cli Installation vorbereiten. Es werden per "apt install" fehlende Pakete installiert und Verzeichnisse erstellt.
Muss mindestens einmal erfolgreich gelaufen sein, damit die restliche Installation funktioniert
|-
|install
|Installiert signal-cli als System Service. Automatischer Download, Installation und Konfiguration (dbus, systemd)
|-
|register
|Registriert die definierte Telefonnummer bei Signal. Dieser Prozess hat seine Tücken und wird unten nochmal eingehend beschrieben
|-
|link
|Verknüpfen einer bestehenden Telefonnummer. Dazu muss in Signal über Settings -> Linked Devices -> "plus" ein QR Code abfotografiert werden.
Dieser wird von dieser Routine als Datei in /tmp/qrcode.png abgelegt. D.h. vorher sicherstellen, dass man mit einem Bildbetrachter an diese Datei kommt
|-
|test
|Versendet eine Testnachricht auf zwei Arten - direkt mit dem Client (klappt das, ist die Grundregistrierung schon mal erfolgreich) und über Dbus (dann ist auch der System Service korrekt eingerichtet)
|-
|remove
|Löscht alle durch "install" installierten Verzeichnisse und Dateien (aber nicht die Pakete die durch "system" installiert wurden)
|-
|join
|Ermöglicht einer Gruppe mithilfe eines Einladungslinks beizutreten
|-
|name
|Definieren des eigenen Namens und Avatar Bildes
|-
|start
|Starten des singal service über systemd bzw. im Container des Dbus daemon and signal-cli Daemon
|}
Das Script muss unter root Rechten, also mit
sudo -E ./signal_install.sh
aufgerufen werden. Wenn kein Argument übergeben wird, dann wird automatisch der Ablauf ''system -> install -> register/link -> test'' durchlaufen.

Das Script fragt üblicherweise nach wenn es etwas tut und führt nur notwendige Aktionen durch (kann also bei teilweisen Fehlern problemlos erneut durchlaufen werden).

Es prüft außerdem ab ob es im Container läuft (hier erfolgt ein etwas anderer Ablauf - mehr dazu unten) und prüft auf Betriebssystem und CPU Architektur. Gegebenenfalls bricht es ab, wenn es sich um keine unterstützte Kombination handelt.

Bitte genau auf die Bildschirmausgaben und Fragen achten. Fehlermeldungen im Thread melden damit das Script weiter verbessert werden kann.

=== Registrierung ===
'''Hinweis:''' Es kann nur '''eine''' Nummer registriert sein. Eine bereits bestehende Registrierung (Smartphone) wird dabei '''aufgehoben'''. Daher entweder eine Festnetznummer verwenden oder das Script hier abbrechen und mit der Option "link" neu starten, dann wird FHEM als Zweitbenutzer zu einer bestehenden Nummer hinzugefügt.

Wenn die Systeminstallation erfolgreich abgeschlossen ist, folgt die Registrierung der Nummer. Hier gibt es zwei Optionen:

'''SMS''' oder '''Voice'''.

Je nachdem wird ein 6-stelliger Aktivierungscode per SMS geschickt oder über einen Telefonanruf (sogar auf Deutsch) diktiert.

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

Nur wie funktioniert sowas in der Kommandozeile?

Das Script erkennt diese Abfrage und fragt nach einem Captcha Code. Diesen erlangt man wie folgt:
[[Datei:Signalbot Captcha Chrome.png|mini|Captcha in Chrome]]
# [https://signalcaptchas.org/registration/generate.html Captcha Seite] von Signal aufrufen. Dabei ist es wahrscheinlich unerheblich von wo (hab es erfolgreich aus meinem Windows Host gemacht und in meinen Linux VM Guest eingetragen) - schätzungsweise ist es einfach zeitlich begrenzt gültig.
# Im Developermode (F12) und nach erfolgreichem Lösen des Captchas (wenn der Bildschirm leer bleibt, ist es auch erfolgreich gelöst) macht der Browser ein redirect auf signalcaptcha://. Das versteht der Browser aber nicht und macht gar nichts.
# Der String steht aber bei Firefox in der Console (recht einfach zu finden), beim Chrome muss man auf Network gehen, mit Ctrl+R refreshen und dann in der Spalte "Name" nach einem kryptischen String suchen. Dass dieser mit signalcaptcha anfängt, sieht man erst im Tooltipp, da der Anfang abgeschnitten wird.
# Diesen String (ohne signalcaptcha://) dann in die Eingabezeile des Scripts einfügen und Return drücken. Jetzt sollte die Registrierung erfolgreich abschließen.
Anbei Screenshots von Firefox und Chrome zum besseren Verständnis.
[[Datei:Signalbot Captch Firefox.png|mini|Captcha im Firefox]]

'''Unterstützung gesucht:''' Das Holen des Captchas ist ziemlich umständlich. Suche jemanden der sich mit z.B. mit der Erstellung von Protokoll plugins in Chrome (Abfangen von signalcaptcha:// und Darstellen des Texts in einem Fenster - evtl. mit "Copy" Button) auskennt - oder vielleicht geht sowas ja auch als FHEM Modul?

=== Bestehende Nummer verlinken ===
Alternativ kann man auch eine bestehende Nummer verlinken. Dazu statt der Registrierung die Option "l" (link) wählen.

Besonders komfortabel geht das, wenn das Script im Terminalfenster einer graphischen Benutzeroberfläche gestartet wird. Hierzu gegebenfalls im Script den Einstellung<blockquote>VIEWER=eog</blockquote>auf einen installierten jpg/png Bildbetrachter anpassen. Wird Ubuntu mit Gnome verwendet kann die Voreinstellung (eog = Eye of Gnome) beibehalten werden. Es wird jetzt automatisch der QR-Code auf dem Bildschirm angezeigt. In der Signal App dann auf Settings->Linked Devices gehen und mit "+" den QR-Code abfotografieren.

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

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

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

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

Weitere Attribute sind optional (siehe oben)

== Umstieg von SiSi ==
Alle die bereits SiSi verwenden können Signalbot erstmal gefahrlos parallel installieren. Einfach Modul ins FHEM Verzeichnis, reload / restart und "define".

Vorher aber zumindest Net::DBus auf V1.2.0 updaten
cpan install -f Net::DBus
Probleme durch eine veraltete '''signal-cli''' Version sind aber nicht ausgeschlossen. Daher keine Support Anfrage ohne vollständigen Umstieg.

Wer komplett umsteigen möchte, kann dies dann mit dem Installer Script tun. Gegebenenfalls Pfade im Script anpassen. Eine bestehende Registrierung wird dann übernommen und muss nicht erneut erfolgen (keine Garantie, dass dies für sehr alte '''signal-cli''' Versionen funktioniert). Wer's ganz sauber haben will, löscht aber alte Installationsreste.

Sofern nach dem SiSi Wiki vorgegangen wurde, dann sind folgende Anpassungen im Script notwendig:
PHONE=+49<eure nummer>
SIGNALPATH=/opt/fhem
SIGNALUSER=fhem
SIGNALVAR=/opt/fhem/.local/share
Das Verzeichnis /opt/fhem/signal-cli kann gelöscht werden.

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

Jetzt kann das Script (PHONE setzen nicht vergessen) einfach wie oben beschrieben gestartet werden.

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

auf dem neuen System dann
cd /
sudo tar xvf ''signalconf.tar.gz''
Dann wie üblich das Install Script ausführen.

== Installation im Docker Container ==
Das Install Script kann auch in einem FHEM Container ausgeführt werden. Diese Funktion ist noch in der Entwicklungsphase (siehe Foren Thread).

Dazu eine interaktive root Shell öffnen und das Script in den Container kopieren (z.B. mit scp).

Dann wie oben beschrieben das Script als root starten.

Im Container wird die Installation des systemd Service ausgelassen und am Anfang ein zusätzliches apt-get update/upgrade ausgeführt (was insbesondere bei einem neuen Container notwendig sein kann).

Sowohl der Dbus daemon und der signal-cli daemon werden vom Script am Ende im Hintergrund gestartet. Dabei wird insbesondere gewartet bis der signal-cli Prozess läuft bevor die Tests durchlaufen werden (das hat in meiner VM durchaus schon mal eine Minute gedauert).

Um Sicherzustellen, dass die beiden Daemons laufen, sollte in den Container Startup ein Aufruf des Scripts mit dem Argument "start".

Dies prüft ob die Daemons laufen und startet die ggf. nach.

Hier noch mein verwendetes docker-compose.yml
<syntaxhighlight lang="Perl">
version: '2'

services:
fhem:
build: .
restart: always
stdin_open: true
tty: true
ports:
- "8083:8083"
- "7072:7072"
volumes:
- ./fhem/core/:/opt/fhem/
networks:
- fhem-network
#devices:
# - "/dev/ttyUSB0:/dev/ttyUSB0"
environment:
FHEM_UID: 1000
FHEM_GID: 1000
TIMEOUT: 10
RESTART: 1
TELNETPORT: 7072
TZ: Europe/Berlin

networks:
fhem-network:
driver: bridge

</syntaxhighlight>
Und mein Dockerfile
<syntaxhighlight lang="Perl">
ARG BASE_IMAGE="fhem/fhem"
ARG BASE_IMAGE_TAG="latest"
FROM ${BASE_IMAGE}:${BASE_IMAGE_TAG}

ARG L_SIGNAL_CLI="0.7.4"

# Install base environment

VOLUME [ "/opt/signal-cli" ]

</syntaxhighlight>
Im Unterverzeichnis fhem/core liegt das ausgepackte fhem.tar.gz (da kann man auch gleich das Install Script und Signalbot installieren).

Dann mit
docker-compose up -d
docker exec -ti fhem-docker_fhem_1 /bin/bash
das Dockerimage erzeugen und root shell starten. Jetzt wird
./signal-install.sh
ausgeführt.

Dann sollte man zum fhem user wechseln und fhem starten können
su - fhem
cd /opt/fhem
perl fhem.pl fhem.cfg
Das aber noch ohne Gewähr und nur rudimentär getestet. Verbesserungsvorschläge, insbesondere wie man gleich alles in die Config Files einbaut willkommen.

== Favoriten und erweiterte Command Funktionen mit einem notify ergänzen ==
Signalbot kann über DOIFs/notifys problemlos um individuelle Funktionen erweitert werden. Der hier beschriebene Ansatz ergänzt eine Favoritenverwaltung und erlaubt die direkt Ausführung von FHEM Befehlen entweder mit oder ohne Authentifizierung via GoogleAuth.

Die Beschreibung hier erfolgt auf Basis von Signalbot Version "Signalbot:2.0.1-beta signal-cli:0.8.1 Protocol::DBus:0.16". Bei künftigen Versionen können sich ggf. Änderungen ergeben.

'''Use Case / Szenario'''

Das Signalbot Modul bietet über die Defintion von "allowedPeers" und durch die von Signal bereitgestellte Ende-zu-Ende Verschlüsselung bereits ein hohes Maß an Sicherheit. Für einfache Abfragen von Temperatiuren etc. ist das aus Sicht des Autors absolut ausreichend. Diese Abfragen sollten über Favoriten mit möglichst wenig Tipp-Aufwand gesendet werden können.

Für sicherheitskritische / sensible Aktionen ist aber eine zusätzliche Absicherung wünschenswert. Für solche Befehle bietet das Signalbot Modul die Integration von GoogleAuth bereits an. Auch diese Befehle können über Favoritendefinitionen abgekürzt werden. Das GoogleAuth Token wird dann vorab separt geschickt.

'''Voraussetzungen'''
* Das Signalbot Device wird mit "signalBot" benannt (alternativ muss eben der Code im Notify angepasst werden)
* Es werden zusätzliche Attribute via <code>userattr</code> zum Signalbot Device hinzugefügt: cmdKeywordNoAuth cmdPatternNoAuth favPrefix favList <code>attr signalBot userattr cmdKeywordNoAuth cmdPatternNoAuth favPrefix favList</code>
'''Der Notify Code'''<syntaxhighlight lang="perl">
signalBot:msgText.* {
my $msgText = ReadingsVal("signalBot", "msgText", "");
my $msgAuth = int(ReadingsVal("signalBot", "msgAuth", 0));
my $FhemCmd;
my $cmdPatternNoAuth = AttrVal("signalBot", "cmdPatternNoAuth", undef);
my $favPrefix = AttrVal("signalBot", "favPrefix", undef);
my $cmdKeyword = AttrVal("signalBot", "cmdKeyword", undef);
my $cmdKeywordNoAuth = AttrVal("signalBot", "cmdKeywordNoAuth", undef);
my @favarray;
my @patternarray;
my $favno;
my $favList;
my $retval;
my $msgSender = ReadingsVal("signalBot", "msgSender", "");
if (substr($msgSender, 0, 1) ne "+") { $msgSender = "@" . $msgSender }

# Sicherheitsprüfung für multi-Command Befehl
if (index($msgText, ";") >= 0) {
Log3("ntf_signalBot", 2, "ntf_signalBot: Semicolon detected, sender may try to send multiple commands in one line. Aborting!");
fhem("set signalBot send $msgSender Semicolon detected, command is ignored!");
return;
}

# ggf. Favoriten auflösen
if ($favPrefix && substr($msgText, 0, length($favPrefix)) eq $favPrefix) {
$favno = int(substr($msgText, length($favPrefix)));
@favarray = split(";", AttrVal("signalBot", "favList", undef));

if ($favno == 0) {
# Favoritenliste zurückgeben
Log3("ntf_signalBot", 4, "ntf_signalBot: list favorites");
$favList = "";
$favno = 1;
foreach my $favLine (@favarray) {
$favLine =~ /^\[(.*)\]/;
$favList .= $favPrefix . $favno . "\t" . $1 . "\n";
$favno++;
}
fhem("set signalBot send $msgSender $favList");
return;
} else {
# favoriten verarbeiten
$FhemCmd = $favarray[$favno-1];
# wenn ein Alias definiert ist, dann den Befehlsteil aus dem Favoriten extrahieren
if (index($FhemCmd, "=") >= 0) {
$FhemCmd = substr($FhemCmd, index($FhemCmd, "=")+1);
}
Log3("ntf_signalBot",3,"ntf_signalBot: FhemCmd after favorite substitution: $FhemCmd");
}

# prüfe auf authorsiertes Command (nur wenn Favoriten expandiert wurden, um doppelte Ausführung zu vermeiden
if ($cmdKeyword && substr($FhemCmd, 0, length($cmdKeyword)) eq $cmdKeyword) {
if ($msgAuth) {
Log3("ntf_signalBot", 3, "ntf_signalBot: execute authenticated cmd");
$FhemCmd = substr($FhemCmd, length($cmdKeyword));
$retval = fhem($FhemCmd);
if ($retval) {
fhem("set signalBot send $msgSender $retval");
}
} else {
# Hinweis auf nicht authorsiertes Command
fhem("set signalBot send $msgSender You are not authorized to execute authenticated commands");
}
}
} else {
$FhemCmd = $msgText
}

# prüfe auf nicht authorsiertes Command
if ($cmdKeywordNoAuth && substr($FhemCmd, 0, length($cmdKeywordNoAuth)) eq $cmdKeywordNoAuth) {
# prüfe patterns
Log3("ntf_signalBot", 4, "ntf_signalBot: received non-authenticated cmd, checking patterns");
@patternarray = split(";", AttrVal("signalBot", "cmdPatternNoAuth", undef));
$FhemCmd = substr($FhemCmd, length($cmdKeywordNoAuth));

my $res = 0;
foreach my $secLine (@patternarray) {
$res += eval '$FhemCmd =~ /' . $secLine . '/';
}
if ($res > 0) {
Log3("ntf_signalBot", 3, "ntf_signalBot: execute non-authenticated cmd");
$retval = fhem($FhemCmd);
if ($retval) {
fhem("set signalBot send $msgSender $retval");
}
} else {
Log3("ntf_signalBot", 2, "ntf_signalBot: non-authenticated cmd execution requested, but no pattern match");
fhem("set signalBot send $msgSender You are not authorized to execute this command without authentication");
}
}

}
</syntaxhighlight>Die Konfiguration erfolgt mit den Attributen am Signal Device. Diese kann z. B. wie folgt aussehen:<syntaxhighlight>
attr signalBot cmdKeyword /
attr signalBot cmdKeywordNoAuth -
attr signalBot cmdPatternNoAuth get .*;;trigger .*;;getstate .*
attr signalBot favPrefix fav
attr signalBot favList [Wird später]=-trigger ntf_sayTTS "Es wird leider etwas später";;[Öffne Haustüre]=/set Flur_Tueroeffner press;;[Temperaturen]=-trigger listTemperatures

</syntaxhighlight>Wichtig ist hier, dass <code>cmdKeyword</code> und <code>cmdKeywordNoAuth</code> unterschiedlich sind. '''Das "="-Zeichen darf nicht verwendet werden,''' weil es in der Favoritenliste für die Zuweisung verwendet wird. In der Favoritenliste müssen die FHEM Befehle mit einem Prefix versehen werden, entweder <code>cmdKeyword</code> oder <code>cmdKeywordNoAuth</code>. Ohne Authentifizierung dürfen <code>get, trigger</code> und <code>getstate</code> aufgerufen werden, alle anderen Befehle erfordern Authentifizierung.

'''Anwendung'''

Im Chat hat man nun folgende Optionen:
* Liste aller Favoriten zurückgeben lassen: <code>fav</code>
* Einen Favoriten aufrufen: <code>fav<x>, also z. B. fav3 oder fav13</code>
* Einen FHEM Befehl ohne Authentifizierung aufrufen: <code>-get hzgWZ ist_temp</code>
* Einen FHEM Befehl mit Authentifizierung aufrufen: <code>/set hzgWZ soll_temp 22</code> davor muss via <code>/<tokern></code> also z. B. <code>/394848</code> das aktuelle GoogleAuth Token gesendet werden

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

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

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

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

Führe '''sudo service signal start''' aus.
|-
|'''Bei Starten von signal-cli:'''
OpenJDK Server VM warning: You have loaded library /tmp/resource17792002454964883349.so which might have disabled stack guard. The VM will try to fix the stack guard now.

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

oder

ERROR App - Missing required native library dependency: libsignal-client

oder

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

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

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

Weitere Tests wenn der Fehler nicht behoben ist:
# Welche Library wird vom System verwendet: ''sudo ldconfig -v | grep libzkgroup.so'' beziehungsweise ''sudo ldconfig -v | grep libsignal_jni.so'' . Da die libraries in .jar files eingebettet sind, darf hier keine gefunden werden.
# Check gibt es irgendwo noch eine andere lib.so <code>sudo find / -name libzkgroup.so 2>/dev/null</code> Wenn ja, sicherstellen, dass diese nicht genommen wird (löschen, umbenennen)
# Check gibt es noch irgendwo ein anderes jar <code>sudo find / -name zkgroup-java-*.jar 2>/dev/null</code> Wenn ja, sicherstellen, dass diese nicht genommen wird (löschen, umbenennen)
# (für den zweiten Fehler, die Schritte 2 und 3 mit libsignal_jni.so bzw. signal-client-java-*.jar durchführen
|-
|Ich kann an Einzelempfänger senden und empfangen, aber nicht an Gruppen versenden
|Du hast wahrscheinlich den vorhergehenden Fehler (libzkgroup) irgendwo, aber er ist dir nicht aufgefallen. Vorgehensweise wie oben.
|-
|Ich kann keiner Gruppe beitreten und/oder nichts an eine Gruppe schicken.
oder

Error in invite:org.asamk.Signal.Error.Failure: Cannot join a V2 group as self does not have a versioned profile
|Die neuen V2 Gruppen benötigen zwingend einen Profil Namen. Sofern also nach der Registrierung keiner gesetzt wurde, kann man keine Gruppen verwenden.
Abhilfe:

'''sudo -E ./signal_install.sh name'''

um einen Namen (und optional ein Avatarbild) festzulegen.
|}

==== Probleme bei Installation im Container ====
{| class="wikitable"
|+
!Fehler
!Lösungsansatz
|-
|org.freedesktop.DBus.Error.Spawn.FileInvalid: Cannot do system-bus activation with no user
|Prüfe Datei ''/usr/share/dbus-1/system-services/org.asamk.Signal.service'' ob es einen Eintrag
'''User=signal-cli'''

gibt
|-
|Signal: Error while initializing Dbus:org.freedesktop.DBus.Error.Disconnected: Connection is closed
|DBus daemon oder signal-cli daemon laufen nicht. Mit dem Installscript als root
'''./signal_install.sh start'''

nachstarten.
|-
|
|
|}

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

[[Kategorie:Messenger]]

Signalbot

2021-03-07T10:37:42Z

Weini: Erweiterung für Favoriten via notify beschrieben (teil 1)

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

== Beschreibung ==
Beschreibung in Kurzform:

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

Da sich signal-cli noch in der Entwicklung befindet (aktuelle Version 0.7.4) steht leider noch nicht die volle Funktionalität über DBus zur Verfügung, wodurch sich auch Einschränkungen für FHEM ergeben.

Aktuell unterstütze Funktionen aus FHEM:
* Senden und Empfangen von Nachrichten an Gruppen oder Einzelempfänger
* Versenden von einem oder mehreren Attachments (Bilder)
* Einlesen, Speichern und Übersetzen von Gruppennamen (statt base64 Strings)
* Setzen, Empfangen und Übersetzen von Kontaktnamen (statt Telefonnummern)
* Einschränken von Gruppen oder Kontakten auf die FHEM reagieren soll
* Direkte Verknüpfung mit dem [[Modul Babble|Babble]] Modul zur Interpretation von Befehlen
Die Installation von signal-cli ist aktuell je nach Linux Kenntnissen durchaus anspruchsvoll. Daher gibt es ein Installationsscript welches aktuell für aktuelle Ubuntu und Raspian Distributionen getestet ist (höchstwahrscheinlich aber auch für andere Debian basierte Distributionen funktioniert)

Signalbot ist weitgehend kompatibel mit SiSi, verfolgt aber technisch ein paar andere Ansätze und stellt zusätzliche Funktionalitäten zur Verfügung:
* Signalbot erzeugt keinen eigenen Prozess sondern integriert sich voll in die laufende FHEM Instanz (ist dadurch hoffentlich stabiler und verbraucht auch weniger Speicher)
* Gruppen werden grundsätzlich mit ihren Klarnamen verwendet und können auch nur mit einem vorangestellten "#" (statt "@#") gekennzeichnet werden.
* Kontakte werden soweit möglich auch mit Klarnamen (statt +49....) unterstützt. Diese kommen aus dem internen Adressbuch und können über "setContact" definiert werden, bzw. kommen bei verlinkten Accounts aus dem Adressbuch des Hauptgeräts. Sie können aktuell leider nur über empfangene Nachrichten entschlüsselt werden, da signal-cli die entsprechende Schnittstelle (noch) nicht zur Verfügung stellt. Signalbot lernt diese aber mit der Zeit und kann sie bei Bedarf auch so abspeichern, dass sie auch nach einem FHEM Neustart wieder verfügbar sind
* Die Möglichkeit von Telegrambot in den "send" Befehl eingebetteten Code auszuführen und damit z.B. einen SVG Plot zu erstellen und mit zu verschicken ist verfügbar. Dazu muss der Befehl in runde Klammern eingebettet werden (Beispiele folgen unten).
* Wurde mit und für die aktuelle Version 0.7.4 von signal-cli entwickelt, die auch die neuen "V2" Gruppen unterstützt, ebenso wird die neuste Version (1.2.0) vom Perl Modul Net::DBus benötigt
* Wird aktiv(Feb 2021) gewartet (letztes Update für SiSi auf github ist von August 2018)

=== Funktionen im Detail ===

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

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

==== refreshGroups ====
Fragt die List der aktuellen Gruppen ab, denen der verknüpfte Account beigetreten ist. Die Liste wird im u.a. Reading '''joinedGroups''' sichtbar gemacht.

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

==== saveContacts ====
Speichert die interne Kontaktliste in das Reading '''contactList''' welches beim Speichern der FHEM Config in ''fhem.save'' abgelegt wird und nach einem Neustart wieder zur Verfügung steht (zur Diskussion: immer automatisch so machen wenn neue Kontakte festgelegt werden?)

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

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

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

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

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

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

=== Attribute im Detail ===

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

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

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

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

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

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

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

=== Readings im Detail ===
{| class="wikitable"
|contactList
|Liste der gespeicherten Kontakt im Format ''Nummer1=Kontakt1,Nummer2=Kontakt2,...''
|-
|joinedGroups
|Liste der beigetretenen Gruppen getrennt mit Leerzeichen
|-
|msgAttachment
|Attachments (Dateinamen im signal-cli repository) der zuletzt empfangenen Attachments
|-
|msgGroupName
|Gruppenname aus der zuletzt eine Nachricht empfangen wurde - leer wenn es eine persönlich Nachricht war
|-
|msgSender
|Absender der letzten Nachricht als Nummer oder wenn bekannt als Name
|-
|msgText
|Empfangenen Nachricht
|-
|msgTimestamp
|Zeitstempel der Nachricht
|-
|prevMsgAttachment
| rowspan="5" |Wie oben, nur enthalten diese Readings die Daten der zuvor empfangenen Nachricht (n-1)
|-
|prevMsgGroupName
|-
|prevMsgSender
|-
|prevMsgText
|-
|prevMsgTimestamp
|-
|sentMsg
|Zuletzt gesendete Nachricht
|-
|sentMsgRecipient
|Empfänger der zuletzt gesendeten Nachricht. Enthält zumeist den Namen aus der Empfangsbestätigung und somit bei vielen Empfängern den zuletzt bestätigten Empfang.

Dies muss nicht zwingend auf die zuletzt gesendete Nachricht (sendMsg) passen, wenn mehrere Nachrichten versendet wurden.
|-
|sentMsgTimestamp
|Zeitstempel des Empfangs oder "pending" wenn noch keine Bestätigung vorliegt
|}

== Installation ==
Zur Installation steht das Script "signal_install.sh" zur Verfügung. Dieses befindet sich noch in der Entwicklung und funktioniert nicht zwangsweise in jeder Umgebung. Daher erst einmal ein paar Referenzen zur manuellen Installation von signal-cli:
* Die Wikiseite des Vorgängermoduls [[SiSi]] welches grundsätzlich die selben Anforderungen hat
* Quickstart (englisch) für [https://github.com/AsamK/signal-cli/wiki/Quickstart signal-cli]
* Anleitung zum [https://github.com/AsamK/signal-cli/wiki/Linking-other-devices-%28Provisioning%29 "linken" einer Nummer] mit signal-cli
* Anleitung zum [https://github.com/AsamK/signal-cli/wiki/Provide-native-lib-for-libsignal#libsignal-client Übersetzen und Installieren der Libraries] für armv7 (Raspberry) da die Distribution nur x86 libraries enthält
* CPAN Seite des Perl Moduls zur [https://metacpan.org/release/Net-DBus DBus Kommunikation]
Das Modul und Install Script wird aktuell nicht über "fhem [[update]]" verbreitet und muss vom ersten Post dieses {{Link2Forum|Topic=118370|LinkText=Forenthemas}} geholt werden.

Vorbereitung:

Modul 50_Signalbot.pm wie üblich ins Verzeichnis "FHEM" der FHEM Installation kopieren.

Das Script "signal_install.sh" ins home Verzeichnis eines beliebigen "sudo"-fähigen Users kopieren.

Am Anfang des Moduls sind einige Informationen und Pfade definiert. Mindestvorrausetzung ist eine Telefonnummer. Es kann eine Festnetznummer oder Mobilfunknummer verwendet werden. Wird Signal schon am Handy benutzt lässt sich die Nummer verknüpfen, was aber den unangenehmen Nebeneffekt hat, dass man dort alle FHEM Nachrichten mitbekommt.

Kontrolliert also bitte vor dem Start des Scripts diese Angaben. Außer bei ''PHONE=+49xxxxx'' sollte aber üblicherweise keine Änderung nötig sein. Wird das sudo mit ''-E'' ausgeführt, so bewirkt das die Übernahme der Environment Variablen. Wenn mit ''export PHONE=+49xxxx'' die Telefonnummer z.B. bereits im ''.bash_profile'' gesetzt wurde, muss das Script nicht mehr editiert werden.

Das Script hat mehrere Optionen um Teilfunktionen direkt auszuführen, diese sind:
{| class="wikitable"
|+
!Argument
!Bedeutung
|-
|system
|System für die signal-cli Installation vorbereiten. Es werden per "apt install" fehlende Pakete installiert und Verzeichnisse erstellt.
Muss mindestens einmal erfolgreich gelaufen sein, damit die restliche Installation funktioniert
|-
|install
|Installiert signal-cli als System Service. Automatischer Download, Installation und Konfiguration (dbus, systemd)
|-
|register
|Registriert die definierte Telefonnummer bei Signal. Dieser Prozess hat seine Tücken und wird unten nochmal eingehend beschrieben
|-
|link
|Verknüpfen einer bestehenden Telefonnummer. Dazu muss in Signal über Settings -> Linked Devices -> "plus" ein QR Code abfotografiert werden.
Dieser wird von dieser Routine als Datei in /tmp/qrcode.png abgelegt. D.h. vorher sicherstellen, dass man mit einem Bildbetrachter an diese Datei kommt
|-
|test
|Versendet eine Testnachricht auf zwei Arten - direkt mit dem Client (klappt das, ist die Grundregistrierung schon mal erfolgreich) und über Dbus (dann ist auch der System Service korrekt eingerichtet)
|-
|remove
|Löscht alle durch "install" installierten Verzeichnisse und Dateien (aber nicht die Pakete die durch "system" installiert wurden)
|-
|join
|Ermöglicht einer Gruppe mithilfe eines Einladungslinks beizutreten
|-
|name
|Definieren des eigenen Namens und Avatar Bildes
|-
|start
|Starten des singal service über systemd bzw. im Container des Dbus daemon and signal-cli Daemon
|}
Das Script muss unter root Rechten, also mit
sudo -E ./signal_install.sh
aufgerufen werden. Wenn kein Argument übergeben wird, dann wird automatisch der Ablauf ''system -> install -> register/link -> test'' durchlaufen.

Das Script fragt üblicherweise nach wenn es etwas tut und führt nur notwendige Aktionen durch (kann also bei teilweisen Fehlern problemlos erneut durchlaufen werden).

Es prüft außerdem ab ob es im Container läuft (hier erfolgt ein etwas anderer Ablauf - mehr dazu unten) und prüft auf Betriebssystem und CPU Architektur. Gegebenenfalls bricht es ab, wenn es sich um keine unterstützte Kombination handelt.

Bitte genau auf die Bildschirmausgaben und Fragen achten. Fehlermeldungen im Thread melden damit das Script weiter verbessert werden kann.

=== Registrierung ===
'''Hinweis:''' Es kann nur '''eine''' Nummer registriert sein. Eine bereits bestehende Registrierung (Smartphone) wird dabei '''aufgehoben'''. Daher entweder eine Festnetznummer verwenden oder das Script hier abbrechen und mit der Option "link" neu starten, dann wird FHEM als Zweitbenutzer zu einer bestehenden Nummer hinzugefügt.

Wenn die Systeminstallation erfolgreich abgeschlossen ist, folgt die Registrierung der Nummer. Hier gibt es zwei Optionen:

'''SMS''' oder '''Voice'''.

Je nachdem wird ein 6-stelliger Aktivierungscode per SMS geschickt oder über einen Telefonanruf (sogar auf Deutsch) diktiert.

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

Nur wie funktioniert sowas in der Kommandozeile?

Das Script erkennt diese Abfrage und fragt nach einem Captcha Code. Diesen erlangt man wie folgt:
[[Datei:Signalbot Captcha Chrome.png|mini|Captcha in Chrome]]
# [https://signalcaptchas.org/registration/generate.html Captcha Seite] von Signal aufrufen. Dabei ist es wahrscheinlich unerheblich von wo (hab es erfolgreich aus meinem Windows Host gemacht und in meinen Linux VM Guest eingetragen) - schätzungsweise ist es einfach zeitlich begrenzt gültig.
# Im Developermode (F12) und nach erfolgreichem Lösen des Captchas (wenn der Bildschirm leer bleibt, ist es auch erfolgreich gelöst) macht der Browser ein redirect auf signalcaptcha://. Das versteht der Browser aber nicht und macht gar nichts.
# Der String steht aber bei Firefox in der Console (recht einfach zu finden), beim Chrome muss man auf Network gehen, mit Ctrl+R refreshen und dann in der Spalte "Name" nach einem kryptischen String suchen. Dass dieser mit signalcaptcha anfängt, sieht man erst im Tooltipp, da der Anfang abgeschnitten wird.
# Diesen String (ohne signalcaptcha://) dann in die Eingabezeile des Scripts einfügen und Return drücken. Jetzt sollte die Registrierung erfolgreich abschließen.
Anbei Screenshots von Firefox und Chrome zum besseren Verständnis.
[[Datei:Signalbot Captch Firefox.png|mini|Captcha im Firefox]]

'''Unterstützung gesucht:''' Das Holen des Captchas ist ziemlich umständlich. Suche jemanden der sich mit z.B. mit der Erstellung von Protokoll plugins in Chrome (Abfangen von signalcaptcha:// und Darstellen des Texts in einem Fenster - evtl. mit "Copy" Button) auskennt - oder vielleicht geht sowas ja auch als FHEM Modul?

=== Bestehende Nummer verlinken ===
Alternativ kann man auch eine bestehende Nummer verlinken. Dazu statt der Registrierung die Option "l" (link) wählen.

Besonders komfortabel geht das, wenn das Script im Terminalfenster einer graphischen Benutzeroberfläche gestartet wird. Hierzu gegebenfalls im Script den Einstellung<blockquote>VIEWER=eog</blockquote>auf einen installierten jpg/png Bildbetrachter anpassen. Wird Ubuntu mit Gnome verwendet kann die Voreinstellung (eog = Eye of Gnome) beibehalten werden. Es wird jetzt automatisch der QR-Code auf dem Bildschirm angezeigt. In der Signal App dann auf Settings->Linked Devices gehen und mit "+" den QR-Code abfotografieren.

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

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

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

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

Weitere Attribute sind optional (siehe oben)

== Umstieg von SiSi ==
Alle die bereits SiSi verwenden können Signalbot erstmal gefahrlos parallel installieren. Einfach Modul ins FHEM Verzeichnis, reload / restart und "define".

Vorher aber zumindest Net::DBus auf V1.2.0 updaten
cpan install -f Net::DBus
Probleme durch eine veraltete '''signal-cli''' Version sind aber nicht ausgeschlossen. Daher keine Support Anfrage ohne vollständigen Umstieg.

Wer komplett umsteigen möchte, kann dies dann mit dem Installer Script tun. Gegebenenfalls Pfade im Script anpassen. Eine bestehende Registrierung wird dann übernommen und muss nicht erneut erfolgen (keine Garantie, dass dies für sehr alte '''signal-cli''' Versionen funktioniert). Wer's ganz sauber haben will, löscht aber alte Installationsreste.

Sofern nach dem SiSi Wiki vorgegangen wurde, dann sind folgende Anpassungen im Script notwendig:
PHONE=+49<eure nummer>
SIGNALPATH=/opt/fhem
SIGNALUSER=fhem
SIGNALVAR=/opt/fhem/.local/share
Das Verzeichnis /opt/fhem/signal-cli kann gelöscht werden.

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

Jetzt kann das Script (PHONE setzen nicht vergessen) einfach wie oben beschrieben gestartet werden.

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

auf dem neuen System dann
cd /
sudo tar xvf ''signalconf.tar.gz''
Dann wie üblich das Install Script ausführen.

== Installation im Docker Container ==
Das Install Script kann auch in einem FHEM Container ausgeführt werden. Diese Funktion ist noch in der Entwicklungsphase (siehe Foren Thread).

Dazu eine interaktive root Shell öffnen und das Script in den Container kopieren (z.B. mit scp).

Dann wie oben beschrieben das Script als root starten.

Im Container wird die Installation des systemd Service ausgelassen und am Anfang ein zusätzliches apt-get update/upgrade ausgeführt (was insbesondere bei einem neuen Container notwendig sein kann).

Sowohl der Dbus daemon und der signal-cli daemon werden vom Script am Ende im Hintergrund gestartet. Dabei wird insbesondere gewartet bis der signal-cli Prozess läuft bevor die Tests durchlaufen werden (das hat in meiner VM durchaus schon mal eine Minute gedauert).

Um Sicherzustellen, dass die beiden Daemons laufen, sollte in den Container Startup ein Aufruf des Scripts mit dem Argument "start".

Dies prüft ob die Daemons laufen und startet die ggf. nach.

Hier noch mein verwendetes docker-compose.yml
<syntaxhighlight lang="Perl">
version: '2'

services:
fhem:
build: .
restart: always
stdin_open: true
tty: true
ports:
- "8083:8083"
- "7072:7072"
volumes:
- ./fhem/core/:/opt/fhem/
networks:
- fhem-network
#devices:
# - "/dev/ttyUSB0:/dev/ttyUSB0"
environment:
FHEM_UID: 1000
FHEM_GID: 1000
TIMEOUT: 10
RESTART: 1
TELNETPORT: 7072
TZ: Europe/Berlin

networks:
fhem-network:
driver: bridge

</syntaxhighlight>
Und mein Dockerfile
<syntaxhighlight lang="Perl">
ARG BASE_IMAGE="fhem/fhem"
ARG BASE_IMAGE_TAG="latest"
FROM ${BASE_IMAGE}:${BASE_IMAGE_TAG}

ARG L_SIGNAL_CLI="0.7.4"

# Install base environment

VOLUME [ "/opt/signal-cli" ]

</syntaxhighlight>
Im Unterverzeichnis fhem/core liegt das ausgepackte fhem.tar.gz (da kann man auch gleich das Install Script und Signalbot installieren).

Dann mit
docker-compose up -d
docker exec -ti fhem-docker_fhem_1 /bin/bash
das Dockerimage erzeugen und root shell starten. Jetzt wird
./signal-install.sh
ausgeführt.

Dann sollte man zum fhem user wechseln und fhem starten können
su - fhem
cd /opt/fhem
perl fhem.pl fhem.cfg
Das aber noch ohne Gewähr und nur rudimentär getestet. Verbesserungsvorschläge, insbesondere wie man gleich alles in die Config Files einbaut willkommen.

== Favoriten und erweiterte Command Funktionen mit einem notify ergänzen ==
Signalbot kann über DOIFs/notifys problemlos um individuelle Funktionen erweitert werden. Der hier beschriebene Ansatz ergänzt eine Favoritenverwaltung und erlaubt die direkt Ausführung von FHEM Befehlen entweder mit oder ohne Authentifizierung via GoogleAuth.

Die Beschreibung hier erfolgt auf Basis von Signalbot Version "Signalbot:2.0.1-beta signal-cli:0.8.1 Protocol::DBus:0.16". Bei künftigen Versionen können sich ggf. Änderungen ergeben.

'''Use Case / Szenario'''

Das Signalbot Modul bietet über die Defintion von "allowedPeers" und durch die von Signal bereitgestellte Ende-zu-Ende Verschlüsselung bereits ein hohes Maß an Sicherheit. Für einfache Abfragen von Temperatiuren etc. ist das aus Sicht des Autors absolut ausreichend. Diese Abfragen sollten über Favoriten mit möglichst wenig Tipp-Aufwand gesendet werden können.

Für sicherheitskritische / sensible Aktionen ist aber eine zusätzliche Absicherung wünschenswert. Für solche Befehle soll eine zusätzliche Absicherung erfolgen, die das Signalbot Modul mit der Integration von GoogleAuth bereits anbietet. Auch diese Befehle können über Favoritendefinitionen abgekürzt werden. Das GoogleAuth Token wird dann vorab separt geschickt.

'''Voraussetzungen'''
* Das Signalbot Device wird mit "signalBot" benannt (alternativ muss eben der Code im Notify angepasst werden
* Es werden zusätzliche Attribute via userattr zum Signalbot Device hinzugefügt: cmdKeywordNoAuth cmdPatternNoAuth favPrefix favList
'''Das eigentliche Notify'''<syntaxhighlight lang="perl">
signalBot:msgText.* {
my $msgText = ReadingsVal("signalBot", "msgText", "");
my $msgAuth = int(ReadingsVal("signalBot", "msgAuth", 0));
my $FhemCmd;
my $cmdPatternNoAuth = AttrVal("signalBot", "cmdPatternNoAuth", undef);
my $favPrefix = AttrVal("signalBot", "favPrefix", undef);
my $cmdKeyword = AttrVal("signalBot", "cmdKeyword", undef);
my $cmdKeywordNoAuth = AttrVal("signalBot", "cmdKeywordNoAuth", undef);
my @favarray;
my @patternarray;
my $favno;
my $favList;
my $retval;
my $msgSender = ReadingsVal("signalBot", "msgSender", "");
if (substr($msgSender, 0, 1) ne "+") { $msgSender = "@" . $msgSender }

# Sicherheitsprüfung für multi-Command Befehl
if (index($msgText, ";") >= 0) {
Log3("ntf_signalBot", 2, "ntf_signalBot: Semicolon detected, sender may try to send multiple commands in one line. Aborting!");
fhem("set signalBot send $msgSender Semicolon detected, command is ignored!");
return;
}

# ggf. Favoriten auflösen
if ($favPrefix && substr($msgText, 0, length($favPrefix)) eq $favPrefix) {
$favno = int(substr($msgText, length($favPrefix)));
@favarray = split(";", AttrVal("signalBot", "favList", undef));

if ($favno == 0) {
# Favoritenliste zurückgeben
Log3("ntf_signalBot", 4, "ntf_signalBot: list favorites");
$favList = "";
$favno = 1;
foreach my $favLine (@favarray) {
$favLine =~ /^\[(.*)\]/;
$favList .= $favPrefix . $favno . "\t" . $1 . "\n";
$favno++;
}
fhem("set signalBot send $msgSender $favList");
return;
} else {
# favoriten verarbeiten
$FhemCmd = $favarray[$favno-1];
# wenn ein Alias definiert ist, dann den Befehlsteil aus dem Favoriten extrahieren
if (index($FhemCmd, "=") >= 0) {
$FhemCmd = substr($FhemCmd, index($FhemCmd, "=")+1);
}
Log3("ntf_signalBot",3,"ntf_signalBot: FhemCmd after favorite substitution: $FhemCmd");
}

# prüfe auf authorsiertes Command (nur wenn Favoriten expandiert wurden, um doppelte Ausführung zu vermeiden
if ($cmdKeyword && substr($FhemCmd, 0, length($cmdKeyword)) eq $cmdKeyword) {
if ($msgAuth) {
Log3("ntf_signalBot", 3, "ntf_signalBot: execute authenticated cmd");
$FhemCmd = substr($FhemCmd, length($cmdKeyword));
$retval = fhem($FhemCmd);
if ($retval) {
fhem("set signalBot send $msgSender $retval");
}
} else {
# Hinweis auf nicht authorsiertes Command
fhem("set signalBot send $msgSender You are not authorized to execute authenticated commands");
}
}
} else {
$FhemCmd = $msgText
}

# prüfe auf nicht authorsiertes Command
if ($cmdKeywordNoAuth && substr($FhemCmd, 0, length($cmdKeywordNoAuth)) eq $cmdKeywordNoAuth) {
# prüfe patterns
Log3("ntf_signalBot", 4, "ntf_signalBot: received non-authenticated cmd, checking patterns");
@patternarray = split(";", AttrVal("signalBot", "cmdPatternNoAuth", undef));
$FhemCmd = substr($FhemCmd, length($cmdKeywordNoAuth));

my $res = 0;
foreach my $secLine (@patternarray) {
$res += eval '$FhemCmd =~ /' . $secLine . '/';
}
if ($res > 0) {
Log3("ntf_signalBot", 3, "ntf_signalBot: execute non-authenticated cmd");
$retval = fhem($FhemCmd);
if ($retval) {
fhem("set signalBot send $msgSender $retval");
}
} else {
Log3("ntf_signalBot", 2, "ntf_signalBot: non-authenticated cmd execution requested, but no pattern match");
fhem("set signalBot send $msgSender You are not authorized to execute this command without authentication");
}
}

}
</syntaxhighlight>Die Konfiguration erfolgt mit den Attributen am Signal Device. Diese kann z. B. wie folgt aussehen:

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

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

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

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

Führe '''sudo service signal start''' aus.
|-
|'''Bei Starten von signal-cli:'''
OpenJDK Server VM warning: You have loaded library /tmp/resource17792002454964883349.so which might have disabled stack guard. The VM will try to fix the stack guard now.

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

oder

ERROR App - Missing required native library dependency: libsignal-client

oder

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

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

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

Weitere Tests wenn der Fehler nicht behoben ist:
# Welche Library wird vom System verwendet: ''sudo ldconfig -v | grep libzkgroup.so'' beziehungsweise ''sudo ldconfig -v | grep libsignal_jni.so'' . Da die libraries in .jar files eingebettet sind, darf hier keine gefunden werden.
# Check gibt es irgendwo noch eine andere lib.so <code>sudo find / -name libzkgroup.so 2>/dev/null</code> Wenn ja, sicherstellen, dass diese nicht genommen wird (löschen, umbenennen)
# Check gibt es noch irgendwo ein anderes jar <code>sudo find / -name zkgroup-java-*.jar 2>/dev/null</code> Wenn ja, sicherstellen, dass diese nicht genommen wird (löschen, umbenennen)
# (für den zweiten Fehler, die Schritte 2 und 3 mit libsignal_jni.so bzw. signal-client-java-*.jar durchführen
|-
|Ich kann an Einzelempfänger senden und empfangen, aber nicht an Gruppen versenden
|Du hast wahrscheinlich den vorhergehenden Fehler (libzkgroup) irgendwo, aber er ist dir nicht aufgefallen. Vorgehensweise wie oben.
|-
|Ich kann keiner Gruppe beitreten und/oder nichts an eine Gruppe schicken.
oder

Error in invite:org.asamk.Signal.Error.Failure: Cannot join a V2 group as self does not have a versioned profile
|Die neuen V2 Gruppen benötigen zwingend einen Profil Namen. Sofern also nach der Registrierung keiner gesetzt wurde, kann man keine Gruppen verwenden.
Abhilfe:

'''sudo -E ./signal_install.sh name'''

um einen Namen (und optional ein Avatarbild) festzulegen.
|}

==== Probleme bei Installation im Container ====
{| class="wikitable"
|+
!Fehler
!Lösungsansatz
|-
|org.freedesktop.DBus.Error.Spawn.FileInvalid: Cannot do system-bus activation with no user
|Prüfe Datei ''/usr/share/dbus-1/system-services/org.asamk.Signal.service'' ob es einen Eintrag
'''User=signal-cli'''

gibt
|-
|Signal: Error while initializing Dbus:org.freedesktop.DBus.Error.Disconnected: Connection is closed
|DBus daemon oder signal-cli daemon laufen nicht. Mit dem Installscript als root
'''./signal_install.sh start'''

nachstarten.
|-
|
|
|}

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

[[Kategorie:Messenger]]

HM-LC-Bl1PBU-FM Funk-Rollladenaktor für Markenschalter

2016-06-06T20:58:39Z

Weini: Tasterverhalten: neue Variante mit Templates ergänzt

{{Infobox Hardware
|Bild=HM-LC-Bl1PBU-FM.jpg
|Bildbeschreibung=HM-LC-Bl1PBU-FM montiert, ohne Adapter
|HWProtocol=BidCoS ([[HomeMatic]])
|HWType=[[HomeMatic Type Blind|Blind]]
|HWCategory=[[:Kategorie:Rollladensteuerung|Rollladensteuerung]]
|HWComm=868,3 MHz
|HWChannels=1
|HWVoltage=230 V
|HWPowerConsumption=0,5 W (Stand-by)
|HWPoweredBy=Netz
|HWSize=71x71x37 mm
|HWDeviceFHEM=[[CUL_HM]]
|HWManufacturer=ELV / eQ-3
}}
== Features ==

Schalten eines angeschlossenen Jalousiemotors mittels CUL/CUN/HMLAN Konfigurator und über lokalen, in bestehendes Schalterprogramm integrierte Schaltwippe.

'''Technische Daten:'''
* Gerätebezeichnung: HM-LC-Bl1PBU-FM
* Versorgungsspannung: 230 V / 50 Hz
* Maximale Schaltleistung: 230 VA (Motorlast)
* Standby-Verbrauch: 0,5 W
* Schaltvermögen: 1 A (Motorlast)
* Funkfrequenz: 868,3 MHz
* Empfängerklasse: SRD Class 2
* Maximale Sendeleistung: 10 mW
* Schutzart: IP20
* Schutzklasse: II
* Umgebungstemperatur: +5°C bis +35°C
* Abmessungen (B x H x T): 71 x 71 x 37 mm
* Gewicht: 43 g

== Hinweise zur Hardware-Installation ==

Der Schaltaktor ersetzt den Unterputzschalter der bestehenden Elektroinstallation. Arbeiten am 230 V Netz dürfen nur von einer Elektrofachkraft durchgeführt werden! Sicherheitsregeln anwenden:

* Freischalten (Sicherung abschalten),
* gegen Wiedereinschalten sichern,
* Spannungsfreiheit feststellen, (Messgerät vor und '''nach''' Messung auf Funktion überprüfen)
* Erden und Kurzschließen,
* benachbarte, unter Spannung stehende Teile abdecken.

Zur Integration in ein bestehendes Schalterprogramm bitte den entsprechenden Adapter mit bestellen.

<gallery>
Datei:HM-LC-BL1PBU schritt 01.jpg|Ausgangssituation
Datei:HM-LC-BL1PBU schritt 02.jpg|Schalter abbauen, Rahmen entfernen, Unterputzschalter lösen
Datei:HM-LC-BL1PBU schritt 03.jpg|Bestehender Anschluss
Datei:HM-LC-BL1PBU schritt 04.jpg|Neuer Anschluss. Achtung: zusätzlicher Nullleiteranschluss!
Datei:HM-LC-BL1PBU schritt 05.jpg|Einbau ohne Adapter
Datei:HM-LC-BL1PBU schritt 06.jpg|Adapter aufsetzen
Datei:HM-LC-BL1PBU schritt 07.jpg|Fertig eingebauter HM-LC-BL1PBU-FM
</gallery>

== Hinweise zum Betrieb mit FHEM ==

Der Schalter wird seit FHEM 5.3 unterstützt. Das [[Pairing (HomeMatic)|Pairing]] sollte wie in [[HomeMatic Devices pairen]] beschrieben durchgeführt werden. Dazu wird der Config-Taster kurz gedrückt.
Zur Darstellung im Webfrontend siehe [[Slider für HM-Rolladensteuerung anzeigen]].

=== FHEM Config-Auszug ===
Ein exemplarischer Auszug aus der fhem.cfg:

define WZ_Rollo_Links CUL_HM ABCDEF
attr WZ_Rollo_Links devInfo 010100
attr WZ_Rollo_Links eventMap on:hoch off:runter stop:stop
attr WZ_Rollo_Links firmware 2.1
attr WZ_Rollo_Links hmClass receiver
attr WZ_Rollo_Links model HM-LC-Bl1PBU-FM
attr WZ_Rollo_Links room Wohnzimmer
attr WZ_Rollo_Links serialNr JEQxxxxxxx
attr WZ_Rollo_Links subType blindActuator
attr WZ_Rollo_Links webCmd pct

=== Variablen===
==== Attribute====
Dem Device können neben den Allgemeinen auch spezielle Attribute gesetzt werden.
* '''param levelInverse''': HM Blind Aktoren stehen auf 100% wenn sie offen sind und auf 0% wenn sie geschlossen sind. Das ist oftmals nicht intuitiv. In FHEM kann man dies "drehen" durch dieses Attribut. Damit dreht sich auch die Bedeutung von On und Off.

Desweiteren empfehlen sich die üblichen Homematic Attribute (wie autoReadReg, event-on-change-reading, expert) zu setzten. Weitere Informationen dazu unter [[HomeMatic#Attribute]]

==== Readings====
*'''level''' numerischer Wert der den Stand des Rollo wiedergibt. Achtung: Der Aktor kennt nicht den Stand des Rollos sondern errechnet diesen aus den Fahrzeiten. Nach einem powerUp wird ein Stand von 50% angenommen.
*'''motor''': zeigt den Zustand des Motors an, ob er steht oder in welche Richtung er fährt
*'''pct''': analog "level"

== Konfiguration==
Die Konfiguration des Devices betrifft Register und Peerings. Dies sind Werte, die zwar über FHEM gesetzt werden, aber im Device im Flash gespeichert werden.
Man kann die Devices mit Sensoren und Tastern <u>[[Homematic_Peering_Beispiele|peeren]]</u>

===Fahrzeiten kalibrieren===
Um die Jalousie mit Prozentangaben auf eine bestimmte Position fahren zu lassen, muss der Aktor die Fahrtzeiten kennen um daraus die relativen Positionen erechnen zu können. Dazu müssen 3 Werte manuell mit einer Stoppuhr gemessen werden.

* Fahrtzeit nach oben
* Fahrtzeit nach unten (ist meistens identisch mit der Fahrzeit nach oben bei herkömlichen Jalousiemotoren)
* Wechsel der Fahrtrichtung

Diese 3 Zeiten werden in Sekunden gemessen und anschließend einmalig mit den folgenden Befehlen eingestellt:
set <name> regSet driveUp 27.0 # Fahrtzeit nach oben in Sekunden
set <name> regSet driveDown 27.0 # Fahrtzeit nach unten in Sekunden
set <name> regSet driveTurn 0.5 # Die Zeit die gebraucht wird um die Fahrtrichtung zu wechseln in Sekunden

=== Tasterverhalten ===
Um den fahrenden Rollladen bei jedem Tastendruck anzuhalten und nicht nur bei Druck auf die entgegengesetzte Richtung:

* Die internen Taster sichtbar schalten und die config abfragen
set <device> regSet intKeyVisib visib
set <device> getConfig

* Die Taster konfigurieren (alte Variante via Register)
set <device> regBulk RegL_03:self01 0B:94 0D:63 8B:94
set <device> regBulk RegL_03:self02 0B:18 0D:63 8B:18

* Die Taster konfigurieren (neue Variante via Template, dazu muss ein [[HomeMatic_HMInfo]] Device anglegt sein)
set <HMinfo> templateSet <device> BlStopUpSh self02:short
set <HMinfo> templateSet <device> BlStopDnSh self01:short
set <device> getConfig

* Die internen Taster unsichtbar schalten und die config überprüfen
set <device> regSet intKeyVisib invisib
set <device> getConfig

Wichtig: bei der alten Variante nach jedem Schritt jeweils die Anlern-Taste drücken und in den Internals schauen ob die kommandos ohne Fehler abgearbeitet wurden.

== Mögliche Schaltoperationen ==

Der Aktor versteht folgende Befehle:
set <name> on -> Schaltet den Aktor ein
set <name> off -> Schaltet den Aktor aus
set <name> toggle -> Ändert den logischen Zustand des Aktors.
set <name> <Prozentangabe[0 bis 100]> -> Öffnet die Jalousie auf absolut prozentuale Öffnungsposition, berechnet aus definierter Laufzeit.
set <name> up/down <Prozentangabe[0 bis 100]> -> Öffnet oder schließt die Jalousie um den prozentualen Wert, berechnet aus definierter Laufzeit. Keine Angabe => 10%

== Log-Auszug ==
In FHEM ist nach dem Schalten des HM-LC-BL1-FM folgendes Log zu sehen:
2013.02.26 07:00:12 2: CUL_HM set WZ_Rollo_Rechts on rxt:1

== Links ==
* [http://www.elv-downloads.de/Assets/Produkte/10/1030/103038/Downloads/103038_FunkRollladenaktor_um.pdf Bedienungsanleitung (PDF)]

[[Kategorie:HomeMatic Components]]
[[Kategorie:HomeMatic Type Blind]]
[[Kategorie:Rollladensteuerung]]