FHEMWiki - Benutzerbeiträge [de]

TelegramBot

2020-05-07T13:28:21Z

Viegener: added setjoingroups empfehlung

{{Infobox Modul
|ModPurpose=Senden und Empfangen von Nachrichten (Text und Fotos) mit dem freien Messagingdienst Telegram
|ModType=d
|ModForumArea=Unterstützende Dienste
|ModFTopic=38328
|ModTechName=[https://github.com/viegener/Telegram-fhem/blob/master/50_TelegramBot.pm 50_TelegramBot.pm]
|ModOwner=[[Benutzer:Viegener|Viegener]] ({{Link2FU|12772|Forum}} / [[Benutzer Diskussion:Viegener|Wiki]])}}

Das [[TelegramBot]]-Modul ermöglicht das Senden und Empfangen von Nachrichten über den Telegram-instant messaging Dienst (https://telegram.org/).
Es entsteht eine Möglichkeit Benachrichtungen aus FHEM zu versenden, zum Beispiel Alarmmeldungen.
Ausserdem können auch Kommandos über Telegram an FHEM gesendet werden um Steuerungsbefehle in FHEM auszulösen.

Das TelegramBot-Modul benötigt keine Zusatzsoftware auf dem FHEM-Server<ref>anders als die Vorläufer-Variante über das [[Telegram - old API method|Telegram-API]]</ref>, sondern verwendet das [https://core.telegram.org/bots/api TelegramBot-API] über https-Aufrufe. Es muss jedoch das [http://www.fhemwiki.de/wiki/Raspberry_Pi#N.C3.BCtzliche_Zusatzpakete perl JSON modul] installiert sein.

== Über Telegram Instant Messaging ==
Telegram-IDs und Versand/Empfang von Nachrichten sind kostenfrei.
Clients sind für gängige Smartphonesysteme erhältlich (iOS iPhone und Tablet, Android, Windows Phone) und
können auch aus dem WebBrowser verwendet werden.
Es gibt auch einen Kommandozeilen-Client für Linux, der die Grundlage dieses Moduls darstellt.
Mehrfachanmeldungen, auch parallel mit verschiedenen Geräten (z.B. Tablet und Smartphone), sind möglich.
Gruppenchats und Chats mit End-2-End-Verschlüsselung werden ebenfalls unterstützt.

Für die Unterstützung von ''WhatsApp'' siehe Modul [[yowsup]].

Unterstützt werden:

* Versand von Textnachrichten
* Versand und Empfang von Bildern/Audio/etc
* Empfang von Textnachrichten von beliebigen Kontakten
* Kommandos in FHEM über Telegram-Nachrichten von aussen auslösen
* Ergebnisse der Kommandos zusenden lassen

Eine detaillierte Beschreibung des Moduls ist im FHEM Forum und in der (englischen) Dokumentation zum Modul in der {{Link2CmdRef|Anker=TelegramBot}} und in diesem {{Link2Forum|Topic=38328|LinkText=Diskussionsthread}} zu finden. Seit Oktober 2015 wird das Modul offiziell über FHEM-Update verteilt.

Die jeweils aktuellste Entwicklungs-Version des Moduls ist in Github [https://github.com/viegener/Telegram-fhem/blob/master/50_TelegramBot.pm 50_TelegramBot.pm] verfügbar.

== TelegramBot Devices in FHEM ==
=== Define ===
{{Randnotiz|RNTyp=Info|RNText=Achtung: Dieses Authtoken ist die einzige Authentifizierung für den Bot und sollte deshalb nicht aus der Hand gegeben werden. Die verwendeten Urls sind deshalb auch in den Log-Files nicht enthalten, da diese das Authtoken in Klartext enthalten. Auch im Forum sollte dieses Token nicht aufgenommen werden.
}}

Für die Anlage eines TelegramBot Devices in FHEM ist ein Authtoken erforderlich. Dieses Token wird über Anlegen eines neuen Bots im [https://core.telegram.org/bots#6-botfather BotFather] erzeugt (siehe dazu unten). Dafür muss der BotFather mit einem Telegram-Client kontaktiert werden. Dort mit dem Telegram-Befehl <code>/newbot</code> einen neuen Bot anlegen und mit einem Namen versehen. Hinweis: Die Namen für Bots müssen auf "Bot" enden. 

Das Anlegen eines TelegramBot devices erfolgt durch die Angabe dieses Tokens:

<code>define <name> TelegramBot <token> </code>

Beispiel: <code>define myTelegramBot TelegramBot 110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw</code>

'''Das Empfangen von Nachrichten (polling) erfordert die Einstellung des Attributes'''
<code>pollingTimeout</code> '''auf einen Wert der grösser als Null ist. Beim Wert 0 oder ohne Setzen des Attributes findet kein Polling und damit auch kein Empfang statt.'''

Beispiel: <code>attr myTelegramBot pollingTimeout 120</code>

'''Der TelegramBot kann erst dann Nachrichten an einen telegram user schicken, wenn dieser zuerst an den telegram bot eine Nachricht gesendet hat.'''
Dafür muss man in seinem Telegram-Client den Kontakt @botName suchen und dann eine Nachricht daran versenden.

'''Der TelegramBot kann keine Nachrichten an andere Bots senden. Ein anderer Bot erhält die Nachrichten auch nicht wenn er in einer Gruppe enthalten ist.''' Dies ist eine Beschränkung in der Bot-Funktion bei Telegram. Das Versenden an einen anderen Bot (wenn man den Kontakt manuell hinzugefügt hat) führt zur Fehlermeldung
<code>sentMsgResult - Callback returned error :Bad Request: chat not found:</code>

{{Randnotiz|RNTyp=Info|RNText=TelegramBot setzt eine aktuelle Version von FHEM voraus, insbesondere Versionen weit vor der Umstellung auf 5.7 (also vor Herbst 2015) können mit einem TelegramBot-Modul nicht funktionieren, da insbesondere das HTTPSRV-Modul dann veraltet ist. Am besten auch den TelegramBot über den offiziellen Update mit dem Rest von FHEM installieren/aktualisieren.
}}

=== Registrierung eines neuen Bot ===
Zur Registrierung wird ein funktionierender Telegram-Client (egal ob Web, App oder Programm)benötigt. Hier wird ein Chat zum BotFather gestartet und der Befehl /newbot gesendet. Nun fragt der BotFather die benötigten Angaben ab und liefert am Ende des Dialogs die Informationen für den neuen Bot.
Hier ein Beispiel, wie so ein Chat aussehen könnte:
<pre>Client:
/newbot
----------------
BotFather:
Alright, a new bot. How are we going to call it? Please choose a name for your bot.
----------------
Client:
Mein Name
----------------
BotFather:
Good. Now let's choose a username for your bot. It must end in `bot`. Like this, for example: TetrisBot or tetris_bot.
----------------
Client:
fhem_bot
----------------
BotFather:
Sorry, this username is already taken. Think of something different.
----------------
Client:
fhem1234_bot
----------------
BotFather:
Done! Congratulations on your new bot.
You will find it at telegram.me/fhem1234_bot.
You can now add a description, about section and profile picture for your bot, see /help for a list of commands.
----------------
Use this token to access the HTTP API:
1234567890:AbCdefgHIJklmnOPQRst-uvwxyz

For a description of the Bot API, see this page: https://core.telegram.org/bots/api
</pre>
{{Randnotiz|RNTyp=Info|RNText=Achtung: Da Bots generell für alle Benutzer sichtbar sind und es gelegentlich Problem mit spammern gibt, die fremde bots auch in Gruppen hinzufügen, ist es empfehlenswert die Einstellung /setjoingroups auf false zu setzen, wenn die Zugehörigkeit zu Gruppen (und der Empfang von Meldungen aus gruppen) nicht notwendig ist
}}

Um einen Chat an einen "Contact" versenden zu können, muss zuerst in Contacts (bei Readings) ein Kontakt auftauchen. Wenn man sich zum allerersten Mal bei Telegram angemeldet hat, gibt es noch keinen Chat mit irgendjemanden. Man muss sich zuerstmal selbst eine Nachricht im Smartphone zusenden, dann taucht unter Readings der Eintrag Contacts auf. Erst dann kann man eine Nachricht mit @msgPeerId (das ist Ziffernfolge des Contacts ) oder mit @msgPeer (das ist der Name nach dem Doppelpunkt) vom TelegramBot auf sein Smartphone senden.

== Tipps ==

=== Privacyeinstellungen ===

Damit der TelegramBot auch Meldungen in Gruppen sieht, müssen über den BotFather die Privacy-Einstellungen geändert werden. Beispielchat:<pre>Client:
/setprivacy
----------------
BotFather:
Choose a bot to change group messages settings.
----------------
Client:
@fhem1234_bot
----------------
BotFather:
'Enable' - your bot will only receive messages that either start with the '/' symbol or mention the bot by username.
'Disable' - your bot will receive all messages that people send to groups.
Current status is: ENABLED
----------------
Client:
Disable
----------------
BotFather:
Success! The new status is: DISABLED. /help</pre>

Siehe auch Info zu /setjoingroups oben.

=== Kontakte ===

Der Bot merkt sich die bereits bekannten Kontakte im Reading <code>Contacts</code>. Dabei werden die einzelnen Kontakte jeweils als 3-teilige Einträge gespeichert - bestehend aus UserID, Vor- und Nachname des Benutzers (mit _ verbunden) und dem Username (mit vorangestelltem @).

Beispiel: <code>123456:Ralf_Mustermann:@ralf</code>

Verschiedene Einträge werden durch Leerzeichen getrennt.

Man kann die Kontakte auch manuell überschreiben (z.B. wenn das Reading fehlerhaft oder verloren sein sollte). Dazu gibt es den Set-Befehl <code>replaceContacts</code>. Dieser nimmt die Kontakte ebenfalls in der gleichen Form wie oben beschrieben entgegen.

Die Kontaktliste wird ansonsten nur durch den Empfang von Nachrichten erweitert, da es im TelegramBot-API keine Möglichkeit gibt Kontaktdaten von Telegram abzufragen (siehe auch pollingTimeout)

=== Reset ===

Es ist möglich den Bot im laufenden Betrieb zurückzusetzen (Set-Befehl <code>reset</code>). Dabei werden noch nicht abgeschlossene Übetragungen entfernt und die internen Zustände des Devices zurückgesetzt.

=== Gruppen ===

Um eine Nachricht von FHEM an eine Gruppe zu senden, muss der BOT in die Gruppe aufgenommen werden. Nach dem Senden einer Nachricht an die Gruppe kann im Modul die Gruppen-ID ermittelt werden und zum Senden von Nachrichten verwendet werden. Die Gruppen-ID ist eine negative Zahl. Wenn die Privacy-Einstellungen nicht auf 'Disabled' gesetzt wurden, muss die Nachricht mit einem Slash (/) beginnen.

==== Supergroups / Supergruppen ====

Auch die neuen Supergruppen werden mit dem Bot unterstützt, es ist allerdings zu beachten, dass bei der Umwandlung einer Gruppe in eine Supergruppe eine neue ID in den Kontakten von Telegram vergeben wird. Wenn man also wie empfohlen IDs zur Identifikation von Benutzern einsetzt, muss entsprechend angepasst werden.

==== Fehlermeldungen bei veralteter SSL-Version ====
Telegram nutzt seit Februar 2020 eine neue Verschlüsselung und dies ruft bei veralteter Installation eine Fehlermeldung hervor:

NonBlockingGet: returned <hidden>: Can't connect(2) to <nowiki>https://api.telegram.org:443</nowiki>

Dies deutet auf eine veraltete SSL-Version hin, siehe dazu die Forumsdiskussion ab [https://forum.fhem.de/index.php/topic,38328.msg1021642.html#msg1021642 diesem Eintrag]. Hilfreich hat sich ein upgrade der SSL-Module erwiesen. Zuerst muss uU ein Modul installiert werden
sudo apt-get install libssl-dev
und danach in zwei Schritten
sudo cpan <enter>
upgrade net::SSLeay<enter>
Es ist bei Jessie zwingend ein Upgrade von
IO::Socket::SSL 2.002 -> 2.066
notwendig. Es wird darauf hingewiesen, dass idealerweise nicht einzelne Module, sondern das gesamte OS sowie alle Perlmodule auf den neuesten Stand gebracht werden sollten.

== Beispielszenarien ==

=== Benachrichtigungen über Ereignisse ===

Das einfachste Szenario für die Integration von Messaging-Diensten mit FHEM ist zur Benachrichtigung über Ereignisse. Diese Funktion kann zum Beispiel verwendet werden, um über einen erfolgten Neustart von FHEM zu informieren:

<code>define notify_fhem_reload notify global:INITIALIZED set myTelegramBot message fhem newly started - just now !</code>

In diesem Beispiel wird der Nachrichtentext "fhem newly started - just now !" an den als default eingestellten Kontakt (Attribut: defaultPeer) gesendet, sobald FHEM neu gestartet wurde. Natürlich kann man auch beliebige andere Benachrichtigungen einführen.

Nebenbemerkung: hier ist eine erweiterte Strukturierung evt. empfehlenswert: statt jede Notify-Syntax o.ä. direkt auf TelegramBot-Spezifika gehen zu lassen, kann man sich eine Helper-Funktion (zur Vermittlung all solcher "Alarmtexte") bauen ([[99_myUtils_anlegen]]), die entsprechende Alarm-Meldungen dann nur intern auf (u.a.) einen Messaging-Service wie (momentan!) Telegram schickt.

=== Versand von Bildern ===

Es ist auch möglich Bilder auf dem FHEM-Server, die zum Beispiel von einer Kamera oder einem Wettermodul stammen über Telegram zu versenden. So wäre es z.B. möglich jeweils morgens die aktuelle Wetterkarte zu erhalten.

ACHTUNG: TelegramBot verwendet das HTTPUtils-Modul zur Kommunikation mit dem TelegramBot-API. Erst mit der Version, die seit 22.10.2015
([r9576] HttpUtils.pm: Async write for POST Requests {{Link2Forum|Topic=41583|LinkText=FHEM-Forum}}) verteilt wird, erlaubt auch den Transfer grösserer Bilder. Die Grenze liegt ansonsten bei ca. 14kb auf Raspberries (Plattformspezifische Grenze).

<code>define notify_fhem_reload notify wetter:report set myTelegramBot sendImage /opt/fhem/wetter.jpg</code>

Bei Erreichen des entsprechenden Status am Wetter-Modul wird ein Image über Telegram versendet. Hier sind lokale Pfade (relativ zu fhem) oder absolute Pfade wie oben möglich.

=== Versand von SVG-Plots ===

SVG-Plots können mit dem Befehl
<code>cmdSend [ @<peer1> ... @<peerN> ] <fhem command></code>
verschickt werden.

Das angegebene FHEM-Kommando wird ausgeführt und das Ergebnis an die angegebenen Peers bzw. den Standard-Peer verschickt.

Mit dem folgenden Befehl wird der SVG-Plot SVG_FileLog_Aussen an den Standard-Peer geschickt:
<code>set myTelegramBot cmdSend { plotAsPng('SVG_FileLog_Aussen') }</code>

Nach <code>define cmd_sendTelegramSVG cmdalias TGSVG .* AS set myTelegramBot cmdSend { plotAsPng("$EVENT") }</code>
kann man mit einem kurzen
<code>TGSVG SVG_Garten</code>
ein beliebiges SVG über die Kommandozeile per Telegram versenden.

Um das SVG nun noch mit einem Text zu versehen, muss eine Textnachricht dazu gesendet werden, was sich am einfachsten durch das Ausführen eines FHEM-Befehls auf Perl-Ebene realisieren lässt:

<code>{fhem "set myTelegramBot message Bildbeschreibung;; set myTelegramBot cmdSend { plotAsPng('mein_SVG') }" }</code>

'''Hinweis:''' früher wurde zum Verschicken von Plots auch die interne Funktion TelegramBot_ExecuteCommand verwendet; mit dem Update Ende Februar 2017 hat diese Funktion einen zusätzlichen Parameter erhalten und lautet nun
<code>TelegramBot_ExecuteCommand($defs{"myTelegramBot"}, meine_ZielID, undef, '{plotAsPng("mein_SVG")}');</code>

==== Voraussetzungen für den Versand von SVG-Plots ====
Es muss das Modul libimage-librsvg-perl installiert sein:

<code>sudo apt-get install libimage-librsvg-perl</code>

Evtl. sind weitere Module erforderlich:

<code>sudo apt-get install libgd-graph-perl

sudo apt-get install libgd-text-perl</code>

=== Empfang von Bildern oder ähnlichem ===

Beim Empfang von Bildern wird zuerst nur eine ID vom Telegram-Server empfangen, diese befindet sich im Reading <code>msgFileId</code> angelegt (<code>123456:xxxxxxxxxxxxxxxxxxxxxxx-xxxxxxxx</code>) und im Reading <code>msgText</code> steht dann so etwas wie
<code>received photo # Size: 107701</code>

Über das Get-Kommando <code>urlForFile</code> mit der ID aus dem msgFileId Reading lässt sich dann daraus ein URL ableiten, der dann zur eigentlichen Datei führt:

<code>https://api.telegram.org/file/bot123456:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/photo/file_25.jpg</code>

=== Versand von Emojis (Smileys) ===

Es ist auch möglich Emojis mit den (Text-)Nachrichten zu versenden. Die entsprechenden (Unicode-)Zeichen werden einfach direkt mit in den Text der Nachricht aufgenommen. Um das zu vereinfachen kann man das einfach per Copy und Paste von dieser Seite

http://apps.timwhitlock.info/emoji/tables/unicode (Spalte "Native")

übernehmen und mit der Nachricht verschicken.

Die Emojis können auch empfangen werden und werden so auch in FHEM / FHEMWeb angezeigt. Plattformspezifische (z.B. von iOS oder Android) Emojis werden dabei nicht unterstützt (gerade mit iOS sind viele neue farbige Emojis hinzugekommen, die wohl leider nur auf Apple-devices funktionieren).

=== Kommandos auslösen ===

Ein wichtiges Szenario ist die Möglichkeit Kommandos in FHEM ausführen zu können, ohne einen Zugang durch die Firewall einrichten zu müssen. Dazu ist die Definition eines Schlüsselwortes (Attribut: "cmdKeyword")erforderlich, mit dem man die Nachrichten beginnen muss, damit der TelegramBot die Kommandos erkennt.

<code>attr myTelegramBot cmdKeyword doit</code>

Somit kann man dann durch Nachrichten die mit "doit" beginnen Kommandos an FHEM senden, die ähnlich wie im Kommandoeingabefeld von FHEMweb dann von FHEM ausgeführt werden. Das Ergebnis der Ausführung wird zurück an den Sender (und an den definierten defaultPeer) geschickt.

Somit können nicht nur Aktionen angestossen werden, sondern auch Infos abgefragt werden.

Beispiele

<code>doit set schalter on</code>

<code>doit list telegrambot</code>

{{Randnotiz|RNTyp=Warn|RNText=Achtung: Bei den Kommandos sollten man unbedingt das Attribut "cmdRestrictedPeer" setzen, damit nicht jeder Kommandos auf dem FHEM-Server ausführen kann. Dazu sollten die BenutzerIDs der erlaubten Benutzer (durch Leerzeichen getrennt angeben). Da Benutzernamen selber vergeben werden und nicht unbedingt eindeutig sind, sollten hier auch NUR BenutzerIDs verwendet werden.
}}

==== Favoriten für Kommandos anlegen ====
Grundidee bei den Favoriten ist, dass man lange Befehle, die man häufig braucht auf "Kurzwahl" legt.

Beispiel-Kommandos wie z.B. <code>set TYPE=ROLLLADEN pos 100</code> und <code>set TYPE=ROLLLADEN pos 0</code>, die man immer wieder braucht. Um nicht jedes mal dieses Kommando eintippen zu müssen auf dem Smartphone, kann man auch dafür Favoriten anlegen.

Dazu gibt man erst mal die beiden Kommandos getrennt durch Semikolon im Attribut favorites an:

<code>attr myTelegramBot favorites set TYPE=ROLLLADEN pos 100;set TYPE=ROLLLADEN pos 0</code>

Um die Favorites jetzt ausführen zu können braucht man noch ein Schlüsselwort dafür.
Nehmen wir mal an man möchte die Favoriten mit <code>/short</code> ausführen können. Dazu muss dann das Attribut "cmdFavorites" setzen

<code>attr myTelegramBot cmdFavorites /short</code>

Wenn man nun im Telegram Client
<code>/short 1</code> an den Bot schickt führt der Bot den ersten Favoriten aus und das Ergebnis der Ausführung wird zurückgeschickt.

Ausserdem kann man im Telegram Client
<code>/short</code> an den Bot schicken, dann antwortet der Bot mit

<pre>
Favorites

/short1 = set TYPE=ROLLLADEN pos 100

/short2 = set TYPE=ROLLLADEN pos 0

</pre>

Die Antworten werden als Schaltflächen dargestellt (Telegram inline Keyboard) und können am Mobile-Client direkt angeklickt werden um sie auszuführen.
Um die Beschriftung der Schaltflächen zu optimieren, können die Befehle im Attribut favorites mit Beschreibungen versehen werden:

<code>/[Rolllaeden zu ]=set TYPE=ROLLLADEN pos 100;/[Rolllaeden auf]=set TYPE=ROLLLADEN pos 0</code>

Nun antwortet der Bot auf das Schlüsselwort für die Favoriten mit:

<pre>
Favorites

/short1 = Rolllaeden zu

/short2 = Rolllaeden auf

</pre>

=== Nützliche Kombinationen mit weiteren Modulen ===

==== msgConfig ====
{{Link2CmdRef|Anker=msgConfig|Lang=de|Label=msgConfig}}

{{Link2CmdRef|Anker=msgDialog|Lang=de|Label=msgDialog}}

==== msgDialog ====
[[MsgDialog]]

==== MSG ====
[[Msg]]

{{Link2CmdRef|Anker=MSG|Lang=en|Label=MSG}}

{{Link2Forum|Topic=39983|LinkText=Forum-Beitrag}}

==== PostMe ====
[[Modul PostMe#Steuerung per Telegram|PostMe]]

{{Link2CmdRef|Anker=PostMe|Lang=de|Label=PostMe}}

{{Link2CmdRef|Anker=TBot_List|Lang=en|Label=TBot_List}}

==== ROOMATE ====
{{Link2CmdRef|Anker=ROOMMATE|Lang=de|Label=ROOMMATE}}

==== MAX ====
[[MAX#Telegram-Benachrichtigung bei dauergeöffnetem Fenster|Dauer-offenes Fenster melden]]

==== SSCAM - Steuerung von Kameras in Synology Surveillance Station - Schnappschüsse mit TelegramBot versenden ====
[[SSCAM - Steuerung von Kameras in Synology Surveillance Station#Schnappschüsse mit TelegramBot versenden|Schnappschüsse mit TelegramBot versenden]]

==== PRESENCE ====
[[PRESENCE#Hinweis zur Benutzung / Fehlerhandling|Hinweis zur Benutzung / Fehlerhandling]]

==== AMAD ====
[[AMAD]]

==== TALKTOME & TALKTOUSER ====
[[TALKTOME & TALKTOUSER - Sprachverarbeitung für Nutzerinteraktionen#Beleuchtungssteuerung mit Telegram|Beleuchtungssteuerung mit Telegram]]

==== Staumelder ====
[[Staumelder#telegram|Staumelder]]

==== Grafana ====
[[Grafana#Speichern und Senden von Grafiken (zB_mit_Telegram)|Grafana-Plots versenden]]

==== Talk2Fhem ====
[[Talk2Fhem#Messenger Telegram|Talk2Fhem]]

==== Hausüberwachung ====
[[Hausüberwachung#Nachrichten aus dem Haus|Nachrichten aus dem Haus]]

==== Gäste-WLAN der Fritzbox auswerten und Login per Telegram senden ====

{{Link2Forum|Topic=100119|Message=936495|LinkText=Forum-Beitrag}}

==== Batterieüberwachung nur einmal täglich ====
{{Link2Forum|Topic=99219|Message=926652|LinkText=Forum-Beitrag}}

==== BOTVAC ====
[[BOTVAC#MAPS|Saugroboter-Karten]]

==== Unifi Voucher bereistellen über msgDialog ====
[[Unifi#über Telegram|Unifi Voucher]]

[[Unifi#Erkennung neuer clients|Erkennung unbekannter Clients]]

== Links ==
* Github Repository für die Telegram-FHEM Entwicklung: https://github.com/viegener/Telegram-fhem
* Infos zum Telegram BotFather: https://core.telegram.org/bots#6-botfather

* Source code für das 50_TelegramBot.pm-Modul: https://github.com/viegener/Telegram-fhem/blob/master/50_TelegramBot.pm

* Forum-Thread in dem das Modul vorgestellt wurde {{Link2Forum|Topic=38328|LinkText=FHEM-Forum}}
* Telegram messaging system https://telegram.org/
* TelegramBot API https://core.telegram.org/bots/api

<references />
[[Kategorie:Telegram]]

TelegramBot

2019-04-09T14:17:38Z

Viegener: Added remark on bot to bot not working

{{Infobox Modul
|ModPurpose=Senden und Empfangen von Nachrichten (Text und Fotos) mit dem freien Messagingdienst Telegram
|ModType=d
|ModForumArea=Unterstützende Dienste
|ModFTopic=38328
|ModTechName=[https://github.com/viegener/Telegram-fhem/blob/master/50_TelegramBot.pm 50_TelegramBot.pm]
|ModOwner=[[Benutzer:Viegener|Viegener]] ({{Link2FU|12772|Forum}} / [[Benutzer Diskussion:Viegener|Wiki]])}}

Das [[TelegramBot]]-Modul ermöglicht das Senden und Empfangen von Nachrichten über den Telegram-instant messaging Dienst (https://telegram.org/).
Es entsteht eine Möglichkeit Benachrichtungen aus FHEM zu versenden, zum Beispiel Alarmmeldungen.
Ausserdem können auch Kommandos über Telegram an FHEM gesendet werden um Steuerungsbefehle in FHEM auszulösen.

Das TelegramBot-Modul benötigt keine Zusatzsoftware auf dem FHEM-Server (anders als die Variante [[Telegram]]), sondern verwendet das [https://core.telegram.org/bots/api TelegramBot-API] über https-Aufrufe. Es muss jedoch das [http://www.fhemwiki.de/wiki/Raspberry_Pi#N.C3.BCtzliche_Zusatzpakete perl JSON modul] installiert sein.

== Über Telegram Instant Messaging ==
Telegram-IDs und Versand/Empfang von Nachrichten sind kostenfrei.
Clients sind für gängige Smartphonesysteme erhältlich (iOS iPhone und Tablet, Android, Windows Phone) und
können auch aus dem WebBrowser verwendet werden.
Es gibt auch einen Kommandozeilen-Client für Linux, der die Grundlage dieses Moduls darstellt.
Mehrfachanmeldungen, auch parallel mit verschiedenen Geräten (z.B. Tablet und Smartphone), sind möglich.
Gruppenchats und Chats mit End-2-End-Verschlüsselung werden ebenfalls unterstützt.

Für die Unterstützung von ''WhatsApp'' siehe Modul [[yowsup]].

== Features ==
Unterstützt werden:

* Versand von Textnachrichten
* Versand und Empfang von Bildern/Audio/etc
* Empfang von Textnachrichten von beliebigen Kontakten
* Kommandos in FHEM über Telegram-Nachrichten von aussen auslösen
* Ergebnisse der Kommandos zusenden lassen

Eine detaillierte Beschreibung des Moduls ist im FHEM Forum und in der (englischen) Dokumentation zum Modul in der {{Link2CmdRef|Anker=TelegramBot}} und in diesem {{Link2Forum|Topic=38328|LinkText=Diskussionsthread}} zu finden. Seit Oktober 2015 wird das Modul offiziell über FHEM-Update verteilt.

Die jeweils aktuellste Entwicklungs-Version des Moduls ist in Github [https://github.com/viegener/Telegram-fhem/blob/master/50_TelegramBot.pm 50_TelegramBot.pm] verfügbar.

== Hinweise zum Betrieb mit FHEM ==
{{Randnotiz|RNTyp=Info|RNText=Achtung: Dieses Authtoken ist die einzige Authentifizierung für den Bot und sollte deshalb nicht aus der Hand gegeben werden. Die verwendeten Urls sind deshalb auch in den Log-Files nicht enthalten, da diese das Authtoken in Klartext enthalten. Auch im Forum sollte dieses Token nicht aufgenommen werden.
}}

Für die Anlage eines TelegramBot Devices in FHEM ist ein Authtoken erforderlich. Dieses Token wird über Anlegen eines neuen Bots im [https://core.telegram.org/bots#6-botfather BotFather] erzeugt. Dafür muss der BotFather mit einem Telegram-Client kontaktiert werden. Dort mit dem Telegram-Befehl <code>/newbot</code> einen neuen Bot anlegen und mit einem Namen versehen. Hinweis: Die Namen für Bots müssen auf "Bot" enden. 

Das Anlegen eines TelegramBot devices erfolgt durch die Angabe dieses Tokens:

<code>define <name> TelegramBot <token> </code>

Beispiel: <code>define teleBot TelegramBot 110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw</code>

'''Das Empfangen von Nachrichten (polling) erfordert die Einstellung des Attributes'''
<code>pollingTimeout</code> '''auf einen Wert der grösser als Null ist. Beim Wert 0 oder ohne Setzen des Attributes findet kein Polling und damit auch kein Empfang statt.'''

Beispiel: <code>attr teleBot pollingTimeout 120</code>

'''Der TelegramBot kann erst dann Nachrichten an einen telegram user schicken, wenn dieser zuerst an den telegram bot eine Nachricht gesendet hat.'''
Dafür muss man in seinem Telegram-Client den Kontakt @botName suchen und dann eine Nachricht daran versenden.

'''Der TelegramBot kann keine Nachrichten an andere Bots senden. Ein anderer Bot erhält die Nachrichten auch nicht wenn er in einer Gruppe enthalten ist.''' Dies ist eine Beschränkung in der Bot-Funktion bei Telegram. Das Versenden an einen anderen Bot (wenn man den Kontakt manuell hinzugefügt hat) führt zur Fehlermeldung
<code>sentMsgResult - Callback returned error :Bad Request: chat not found:</code>

{{Randnotiz|RNTyp=Info|RNText=TelegramBot setzt eine aktuelle Version von FHEM voraus, insbesondere Versionen weit vor der Umstellung auf 5.7 (also vor Herbst 2015) können mit einem TelegramBot-Modul nicht funktionieren, da insbesondere das HTTPSRV-Modul dann veraltet ist. Am besten auch den TelegramBot über den offiziellen Update mit dem Rest von FHEM installieren/aktualisieren.
}}

== Registrierung eines neuen Bot ==
Zur Registrierung wird ein funktionierender Telegram-Client (egal ob Web, App oder Programm)benötigt. Hier wird ein Chat zum BotFather gestartet und der Befehl /newbot gesendet. Nun fragt der BotFather die benötigten Angaben ab und liefert am Ende des Dialogs die Informationen für den neuen Bot.
Hier ein Beispiel, wie so ein Chat aussehen könnte:
<pre>Client:
/newbot
----------------
BotFather:
Alright, a new bot. How are we going to call it? Please choose a name for your bot.
----------------
Client:
Mein Name
----------------
BotFather:
Good. Now let's choose a username for your bot. It must end in `bot`. Like this, for example: TetrisBot or tetris_bot.
----------------
Client:
fhem_bot
----------------
BotFather:
Sorry, this username is already taken. Think of something different.
----------------
Client:
fhem1234_bot
----------------
BotFather:
Done! Congratulations on your new bot.
You will find it at telegram.me/fhem1234_bot.
You can now add a description, about section and profile picture for your bot, see /help for a list of commands.
----------------
Use this token to access the HTTP API:
1234567890:AbCdefgHIJklmnOPQRst-uvwxyz

For a description of the Bot API, see this page: https://core.telegram.org/bots/api
</pre>
Um einen Chat an einen "Contact" versenden zu können, muss zuerst in Contacts (bei Readings) ein Kontakt auftauchen. Wenn man sich zum allerersten Mal bei Telegram angemeldet hat, gibt es noch keinen Chat mit irgendjemanden. Man muss sich zuerstmal selbst eine Nachricht im Smartphone zusenden, dann taucht unter Readings der Eintrag Contacts auf. Erst dann kann man eine Nachricht mit @msgPeerId (das ist Ziffernfolge des Contacts ) oder mit @msgPeer (das ist der Name nach dem Doppelpunkt) vom TelegramBot auf sein Smartphone senden.

== Tipps ==

=== Privacyeinstellungen ===

Damit der TelegramBot auch Meldungen in Gruppen sieht, müssen über den BotFather die Privacy-Einstellungen geändert werden. Beispielchat:<pre>Client:
/setprivacy
----------------
BotFather:
Choose a bot to change group messages settings.
----------------
Client:
@fhem1234_bot
----------------
BotFather:
'Enable' - your bot will only receive messages that either start with the '/' symbol or mention the bot by username.
'Disable' - your bot will receive all messages that people send to groups.
Current status is: ENABLED
----------------
Client:
Disable
----------------
BotFather:
Success! The new status is: DISABLED. /help</pre>

=== Kontakte ===

Der Bot merkt sich die bereits bekannten Kontakte im Reading <code>Contacts</code>. Dabei werden die einzelnen Kontakte jeweils als 3-teilige Einträge gespeichert - bestehend aus UserID, Vor- und Nachname des Benutzers (mit _ verbunden) und dem Username (mit vorangestelltem @).

Beispiel: <code>123456:Ralf_Mustermann:@ralf</code>

Verschiedene Einträge werden durch Leerzeichen getrennt.

Man kann die Kontakte auch manuell überschreiben (z.B. wenn das Reading fehlerhaft oder verloren sein sollte). Dazu gibt es den Set-Befehl <code>replaceContacts</code>. Dieser nimmt die Kontakte ebenfalls in der gleichen Form wie oben beschrieben entgegen.

Die Kontaktliste wird ansonsten nur durch den Empfang von Nachrichten erweitert, da es im TelegramBot-API keine Möglichkeit gibt Kontaktdaten von Telegram abzufragen (siehe auch pollingTimeout)

=== Reset ===

Es ist möglich den Bot im laufenden Betrieb zurückzusetzen (Set-Befehl <code>reset</code>). Dabei werden noch nicht abgeschlossene Übetragungen entfernt und die internen Zustände des Devices zurückgesetzt.

=== Gruppen ===

Um eine Nachricht von FHEM an eine Gruppe zu senden, muss der BOT in die Gruppe aufgenommen werden. Nach dem Senden einer Nachricht an die Gruppe kann im Modul die Gruppen-ID ermittelt werden und zum Senden von Nachrichten verwendet werden. Die Gruppen-ID ist eine negative Zahl. Wenn die Privacy-Einstellungen nicht auf 'Disabled' gesetzt wurden, muss die Nachricht mit einem Slash (/) beginnen.

==== Supergroups / Supergruppen ====

Auch die neuen Supergruppen werden mit dem Bot unterstützt, es ist allerdings zu beachten, dass bei der Umwandlung einer Gruppe in eine Supergruppe eine neue ID in den Kontakten von Telegram vergeben wird. Wenn man also wie empfohlen IDs zur Identifikation von Benutzern einsetzt, muss entsprechend angepasst werden.

== Beispielszenarien ==

=== Benachrichtigungen über Ereignisse ===

Das einfachste Szenario für die Integration von Messaging-Diensten mit FHEM ist zur Benachrichtigung über Ereignisse. Diese Funktion kann zum Beispiel verwendet werden, um über einen erfolgten Neustart von FHEM zu informieren:

<code>define notify_fhem_reload notify global:INITIALIZED set telebotdevice message fhem newly started - just now !</code>

In diesem Beispiel wird der Nachrichtentext "fhem newly started - just now !" an den als default eingestellten Kontakt (Attribut: defaultPeer) gesendet, sobald FHEM neu gestartet wurde. Natürlich kann man auch beliebige andere Benachrichtigungen einführen.

=== Versand von Bildern ===

Es ist auch möglich Bilder auf dem FHEM-Server, die zum Beispiel von einer Kamera oder einem Wettermodul stammen über Telegram zu versenden. So wäre es z.B. möglich jeweils morgens die aktuelle Wetterkarte zu erhalten.

ACHTUNG: TelegramBot verwendet das HTTPUtils-Modul zur Kommunikation mit dem TelegramBot-API. Erst mit der Version, die seit 22.10.2015
([r9576] HttpUtils.pm: Async write for POST Requests {{Link2Forum|Topic=41583|LinkText=FHEM-Forum}}) verteilt wird, erlaubt auch den Transfer grösserer Bilder. Die Grenze liegt ansonsten bei ca. 14kb auf Raspberries (Plattformspezifische Grenze).

<code>define notify_fhem_reload notify wetter:report set telebotdevice sendImage /opt/fhem/wetter.jpg</code>

Bei Erreichen des entsprechenden Status am Wetter-Modul wird ein Image über Telegram versendet. Hier sind lokale Pfade (relativ zu fhem) oder absolute Pfade wie oben möglich.

=== Versand von SVG-Plots ===

SVG-Plots können mit dem Befehl
<code>cmdSend [ @<peer1> ... @<peerN> ] <fhem command></code>
verschickt werden.

Das angegebene FHEM-Kommando wird ausgeführt und das Ergebnis an die angegebenen Peers bzw. den Standard-Peer verschickt.

Mit dem folgenden Befehl wird der SVG-Plot SVG_FileLog_Aussen an den Standard-Peer geschickt:
<code>set mein_telegramBot cmdSend { plotAsPng('SVG_FileLog_Aussen') }</code>

Nach <code>define cmd_sendTelegramSVG cmdalias TGSVG .* AS set mein_telegramBot cmdSend { plotAsPng("$EVENT") }</code>
kann man mit einem kurzen
<code>TGSVG SVG_Garten</code>
ein beliebiges SVG über die Kommandozeile per Telegram versenden.

Um das SVG nun noch mit einem Text zu versehen, muss eine Textnachricht dazu gesendet werden, was sich am einfachsten durch das Ausführen eines FHEM-Befehls auf Perl-Ebene realisieren lässt:

<code>{fhem "set mein_telegramBot message Bildbeschreibung;; set mein_telegramBot cmdSend { plotAsPng('mein_SVG') }" }</code>

'''Hinweis:''' früher wurde zum Verschicken von Plots auch die interne Funktion TelegramBot_ExecuteCommand verwendet; mit dem Update Ende Februar 2017 hat diese Funktion einen zusätzlichen Parameter erhalten und lautet nun
<code>TelegramBot_ExecuteCommand($defs{"mein_telegramBot"}, meine_ZielID, undef, '{plotAsPng("mein_SVG")}');</code>

==== Voraussetzungen für den Versand von SVG-Plots ====
Es muss das Modul libimage-librsvg-perl installiert sein:

<code>sudo apt-get install libimage-librsvg-perl</code>

Evtl. sind weitere Module erforderlich:

<code>sudo apt-get install libgd-graph-perl

sudo apt-get install libgd-text-perl</code>

=== Empfang von Bildern oder ähnlichem ===

Beim Empfang von Bildern wird zuerst nur eine ID vom Telegram-Server empfangen, diese befindet sich im Reading <code>msgFileId</code> angelegt (<code>123456:xxxxxxxxxxxxxxxxxxxxxxx-xxxxxxxx</code>) und im Reading <code>msgText</code> steht dann so etwas wie
<code>received photo # Size: 107701</code>

Über das Get-Kommando <code>urlForFile</code> mit der ID aus dem msgFileId Reading lässt sich dann daraus ein URL ableiten, der dann zur eigentlichen Datei führt:

<code>https://api.telegram.org/file/bot123456:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/photo/file_25.jpg</code>

=== Versand von Emojis (Smileys) ===

Es ist auch möglich Emojis mit den (Text-)Nachrichten zu versenden. Die entsprechenden (Unicode-)Zeichen werden einfach direkt mit in den Text der Nachricht aufgenommen. Um das zu vereinfachen kann man das einfach per Copy und Paste von dieser Seite

http://apps.timwhitlock.info/emoji/tables/unicode (Spalte "Native")

übernehmen und mit der Nachricht verschicken.

Die Emojis können auch empfangen werden und werden so auch in FHEM / FHEMWeb angezeigt. Plattformspezifische (z.B. von iOS oder Android) Emojis werden dabei nicht unterstützt (gerade mit iOS sind viele neue farbige Emojis hinzugekommen, die wohl leider nur auf Apple-devices funktionieren).

=== Kommandos auslösen ===

Ein wichtiges Szenario ist die Möglichkeit Kommandos in FHEM ausführen zu können, ohne einen Zugang durch die Firewall einrichten zu müssen. Dazu ist die Definition eines Schlüsselwortes (Attribut: "cmdKeyword")erforderlich, mit dem man die Nachrichten beginnen muss, damit der TelegramBot die Kommandos erkennt.

<code>attr telebotdevice cmdKeyword doit</code>

Somit kann man dann durch Nachrichten die mit "doit" beginnen Kommandos an FHEM senden, die ähnlich wie im Kommandoeingabefeld von FHEMweb dann von FHEM ausgeführt werden. Das Ergebnis der Ausführung wird zurück an den Sender (und an den definierten defaultPeer) geschickt.

Somit können nicht nur Aktionen angestossen werden, sondern auch Infos abgefragt werden.

Beispiele

<code>doit set schalter on</code>

<code>doit list telegrambot</code>

{{Randnotiz|RNTyp=Warn|RNText=Achtung: Bei den Kommandos sollten man unbedingt das Attribut "cmdRestrictedPeer" setzen, damit nicht jeder Kommandos auf dem FHEM-Server ausführen kann. Dazu sollten die BenutzerIDs der erlaubten Benutzer (durch Leerzeichen getrennt angeben). Da Benutzernamen selber vergeben werden und nicht unbedingt eindeutig sind, sollten hier auch NUR BenutzerIDs verwendet werden.
}}

==== Favoriten für Kommandos anlegen ====
Grundidee bei den Favoriten ist, dass man lange Befehle, die man häufig braucht auf "Kurzwahl" legt.

Beispiel-Kommandos wie z.B. <code>set TYPE=ROLLLADEN pos 100</code> und <code>set TYPE=ROLLLADEN pos 0</code>, die man immer wieder braucht. Um nicht jedes mal dieses Kommando eintippen zu müssen auf dem Smartphone, kann man auch dafür Favoriten anlegen.

Dazu gibt man erst mal die beiden Kommandos getrennt durch Semikolon im Attribut favorites an:

<code>attr telegrambotdevice favorites set TYPE=ROLLLADEN pos 100;set TYPE=ROLLLADEN pos 0</code>

Um die Favorites jetzt ausführen zu können braucht man noch ein Schlüsselwort dafür.
Nehmen wir mal an man möchte die Favoriten mit <code>/short</code> ausführen können. Dazu muss dann das Attribut "cmdFavorites" setzen

<code>attr telegrambotdevice cmdFavorites /short</code>

Wenn man nun im Telegram Client
<code>/short 1</code> an den Bot schickt führt der Bot den ersten Favoriten aus und das Ergebnis der Ausführung wird zurückgeschickt.

Ausserdem kann man im Telegram Client
<code>/short</code> an den Bot schicken, dann antwortet der Bot mit

<pre>
Favorites

/short1 = set TYPE=ROLLLADEN pos 100

/short2 = set TYPE=ROLLLADEN pos 0

</pre>

Die Antworten werden als Schaltflächen dargestellt (Telegram inline Keyboard) und können am Mobile-Client direkt angeklickt werden um sie auszuführen.
Um die Beschriftung der Schaltflächen zu optimieren, können die Befehle im Attribut favorites mit Beschreibungen versehen werden:

<code>/[Rolllaeden zu ]=set TYPE=ROLLLADEN pos 100;/[Rolllaeden auf]=set TYPE=ROLLLADEN pos 0</code>

Nun antwortet der Bot auf das Schlüsselwort für die Favoriten mit:

<pre>
Favorites

/short1 = Rolllaeden zu

/short2 = Rolllaeden auf

</pre>

== Links ==
* Github Repository für die Telegram-FHEM Entwicklung: https://github.com/viegener/Telegram-fhem
* Infos zum Telegram BotFather: https://core.telegram.org/bots#6-botfather

* Source code für das 50_TelegramBot.pm-Modul: https://github.com/viegener/Telegram-fhem/blob/master/50_TelegramBot.pm

* Forum-Thread in dem das Modul vorgestellt wurde {{Link2Forum|Topic=38328|LinkText=FHEM-Forum}}
* Telegram messaging system https://telegram.org/
* TelegramBot API https://core.telegram.org/bots/api

[[Kategorie:Telegram]]

Benutzer:Viegener

2017-03-26T21:59:36Z

Viegener: aufgefrischt

; Erstmal nur ein Überblick über meine FHEM-Beteiligung

== FHEM Benutzung ==

Wunsch war die Zusammenführung der verschiedenen Funksysteme in einem zentralen System.
Ausdrücklich mit den Zielen
* Übergreifende Steuerungen und Makros zu ermöglichen
* Zentrale Bedienungsterminals (tablet)
* Steuerung von Aussen
* Am wichtigsten natürlich Spass am Basteln und Programmieren!!!

 
;Komponenten
* Somfy RTS Rolläden (Aktoren und Handfernbedienungen)
* FS20 Steckdosen
* Thermo/Hygro-Sensoren von LaCrosse und Technoline
* Mehrere Sonos-Komponenten
* Fritzbox
* Homematic - Schalter, STeckdosen, Heizkörperthermostate, Fenstersensoren
* Nextion-Displays
* und und und

 
;Mein FHEM habe ich im Februar 2015 installiert.

== FHEM Development ==

Aber klar, das macht ja den Spass aus. Gerne in C, C++, Perl, Java, Javascript und vielen anderen, die heute nicht mehr relevant sind.
Wenns sein muss auch in CSS, HTML etc

* TBot_List modul
* Nextion Modul
* [https://github.com/viegener/Telegram-fhem/blob/master/70_Telegram.pm 70_Telegram.pm]
* [https://github.com/viegener/Telegram-fhem/blob/master/50_TelegramBot.pm 50_TelegramBot.pm]
* Beiträge zu Somfy
** Somfy in FHEMDuino (Perl und C)
** 10_Somfy_PM - Umbau positionsbehandlung
** Übernahm Somfy-Modul
* Beiträge zu FHEM Tablet UI
* FTUISrv Modul

== FHEMWiki ==

* [[TelegramBot]]
* [[Telegram]]
* [[DevelopmentModuleAPI]]

 
 

== Projekte und Ideen ==

* Klingeltaster-Modul mit RGB-LEDs und Arduino+Funk
** Immer noch eine Baustelle, RGB geht, FHEM-Anbindung über Asksin Homematic
** Eigentlich inzwischen obsolet durch Nextion-Displays

* grösseres (10 Zoll ?) Tablet als zentrale Bedienungskonsole
** Jetzt realisiert über Acer Iconia 10 - funktioniert recht gut und für den Preis ein gutes Angebot

* Infrarot-Modul als Homematic Aktor (Selbstbau Arduino Nano / Funkmodul-RFM12B? / IR-LEDs
** Läuft nun als CUL mit WLAN-Interface (ESP8266)
** [https://forum.fhem.de/index.php/topic,49689.0.html]

Modul PostMe

2017-03-26T21:40:42Z

Viegener: Added Info on Tbot_list module for using PostME with TelegramBot

{{
Infobox Modul
|ModPurpose=Das Modul stellt eine komfortable Oberfläche bereit, um per Webinterface beliebige Listen ähnlich wie gelbe Klebezettel (Post-It™) zu verwalten.
|ModType=h

|ModCmdRef=PostMe
|ModForumArea=Unterstuetzende Dienste
|ModTechName=95_PostMe.pm
|ModOwner=Prof. Dr. Peter A. Henning
}}
=Anwendung=
[[File:Postme2.png |600px]]

Das Modul ''95_PostMe.pm'' stellt eine komfortable Oberfläche bereit, um per Webinterface beliebige Listen ähnlich wie gelbe Klebezettel (Post-It™) zu verwalten.
Jede dieser Listen wird im Folgenden als PostMe bezeichnet, und wir verwenden zur Vereinfachung den Devicenamen PostIt (der natürlich durch den eigenen Devicenamen zu ersetzen ist).
==Anwendungsbeispiel==
Mit dem folgenden Beispiel wird eine Liste "Baumarktliste" erzeugt, auf ihr die Einträge für den Kauf eines Sacks Estrichbeton und einer unbestimmten Menge Sägekettenöl vorgenommen
set PostIt create Baumarktliste
set PostIt add Baumarktliste Estrichbeton
set PostIt add Baumarktliste Sägekettenöl
set PostIt modify Baumarktliste Estrichbeton Menge 1 Sack
und die Liste dann per Instant Messenger an den zugeordneten Empfänger verschickt:
get PostIt message Baumarktliste
Der Empfänger wird dann die folgende Nachricht erhalten:
Baumarktliste: Estrichbeton[Menge="1 Sack"],Sägekettenöl

==Listen==
[[File:Postme11.png |600px]]

Jedes PostMe besteht aus einem Listennamen (=Überschrift) zur eindeutigen Identifikation (z.B. "Einkaufsliste"), und beliebig vielen Listeneinträgen. Ein PostMe wird dem System mit den folgenden Kommandos hinzugefügt, entfernt oder geleert:
set PostIt create ''Listenname''
set PostIt delete ''Listenname''
set PostIt clear ''Listenname''

Ein PostMe kann mit einem '''get'''-Befehl ausgegeben oder an eine vordefinierte Adresse geschickt werden. Dazu gibt es die Kommandos
get PostIt list ''Listenname''
Zur Ausgabe an ein Text-to-Speech-Device, hierzu muss das Attribut postmeTTSFun gesetzt sein:
get PostIt ttsSay ''Listenname''
Zur Ausgabe per eMail, hierzu muss dass Attribut postme'''xx'''MailRec für diese Liste (Nr. '''xx''') auf den Empfängernamen gesetzt sein und das Attribut postmeMailFun auf den Namen der eMail-Funktion gesetzt sein:
get PostIt mail ''Listenname''
Zur Ausgabe per instant messenger, hierzu muss dass Attribut postme'''xx'''MsgRec für diese Liste (Nr. '''xx''') auf den Empfängernamen gesetzt sein und das Attribut postmeMsgFun auf den Namen der messenger-Funktion gesetzt sein:
get PostIt message ''Listenname''
==Listeneinträge==
Die Listeneinträge haben das Datenformat
''item'' [''attribute1''="''data1''" ''attribute2''="''data2''" ....]
und sind in einem einzigen langen String gespeichert. Trennzeichen ist das Komma, es darf also im Listeneintrag selbst nicht auftauchen.
*''item'' ist der eigentliche Listeneintrag, es kann sich um einen beliebigen Text (auch mit Leerzeichen) handeln.
**Ein ''item'' wird dem PostMe mit den folgenden Kommandos hinzugefügt bzw. gelöscht
set PostIt add ''Listenname'' ''text''
set PostIt remove ''Listenname'' ''text''
**Dabei darf der ''text'' beim Hinzufügen auch Kommata enthalten - dann werden eben mehrere ''items'' erzeugt. Es dürfen kein eckigen Klammern enthalten sein.
*In eckigen Klammern [...] können einem ''item'' beliebige Metadaten in Form von Attribut-Wert-Paaren hinzugefügt werden. Dafür gibt es das Kommando
set PostIt modify ''Listenname'' ''item'' ''attribute'' ''value''
**Ist das Attribut ''attribute'' noch nicht vorhanden, wird es angelegt und erhält den Wert ''value''
**Ist das Attribut ''attribute'' bereits vorhanden, wird sein Wert mit dem Wert ''value'' überschrieben. Wenn ''value'' leer ist, wird das Attribut entfernt.
==Definition==
Die folgende beispielhafte Definition setzt das PostMe-System mit dem Devicenamen '''PostIt''' in Betrieb:
define PostIt PostMe
attr PostIt postmeStd Einkaufsliste,Baumarktliste ''(Standard-Listen, die immer vorhanden sind (nicht löschbar))''
attr PostIt icon <embed src="/fhem/PostMe_widget?type=pins&postit=PostIt"/> ''(siehe unten)''
attr PostIt postmeTTSFun sendTTS ''(Funktionsname einer Funktion zur Sprachausgabe. Wird mit 1 Parameter (Titelzeile:Inhalt) aufgerufen)''
attr PostIt postmeMailFun DebianMail ''(Funktionsname einer Funktion zum Mailversand. Wird mit 3 Parametern (Empfänger,Titelzeile, Inhalt) aufgerufen)''
attr PostIt postmeMsgFun Telegram ''(Funktionsname einer Funktion zum Versand von Instant messages. Wird mit 3 Parametern (Empfänger,Titelzeile, Inhalt) aufgerufen)''
attr PostIt postme01MailRec ''<mail-Adresse Person 1>''
attr PostIt postme01MsgRec ''<messenger-Adresse Person 1>''
attr PostIt postme02MailRec ''<mail-Adresse Person 2>''
attr PostIt postme02MsgRec ''<messenger-Adresse Person 2>''

attr PostIt postmeStyle jQuery ''(siehe unten)''
attr PostIt postmeClick 0 ''(siehe unten)''
attr PostIt postmeIcon images/default/pin_red_32.png

In der Weboberfläche sieht das dann so aus: [[File:Postme13.png |600px]]
==Service-Routinen==
Das Modul verfügt über zwei Service-Routinen, mit denen ohne Kenntnis von internen Zuständen Listen abgefragt werden können.
===PostMe_tgi(''<Devicename>'',''<Listenname>'')===
liefert das PostMe ''Listenname'' in einem für ''Inline-Keyboards'' des Instant Messenmgers Telegram geeigneten Format zurück, also z.B.
PostMe_tgi('PostIt','Einkaufsliste');
=> (Milch:Einkaufsliste_item00) (Honig:Einkaufsliste_item01) (Streichhölzer:Einkaufsliste_item02) Einkaufsliste
Zur Weiterverarbeitung siehe das entsprechende Kapitel weiter unten. Die Abfrage dieser Service-Routine kann auch von einem anderen Rechner aus erfolgen, dazu verpackt man das idealerweise in ein kleines Shell-Skript:
#!/bin/bash
postme=$1
liste=$2
FHEMIP=''<IP-Adresse des FHEM-Servers''
echo "{PostMe_tgi('$postme','$liste')}" | socat -t50 - TCP:$FHEMIP:7072
===PostMe_tgj(''<Devicename>'',''<Listenname>'')===
liefert das PostMe ''Listenname'' in als "nacktes" Array zurück. Diese Abfrage macht nur Sinn, wenn sie innerhalb eines Perl-Codeblocks ausgeführt wird.
=Steuerung via Spracherkennung=
Für die folgende Anwendung gehen wir davon aus, dass auf einem FHEM-Gerät eine Spracherkennung installiert ist. Der erkannte Sprachstring wird an eine Perl-Funktion als Parameter ''$command'' übergeben. Im Nachfolgenden wird die Auswertung nur für das PostMe '''Einkaufsliste''' beschrieben

}elsif( $command =~ /.*(L|l)iste.*/) {
my $liste;
if( $command =~ /.*Einkaufs.*/ ){
$liste = "Einkaufsliste";
}
if( $command =~ /.*löschen.*/ ){
fhem("set PostIt clear ".$liste);
fhem("set GalaxyTab ttsSay ".$liste." gelöscht");
}elsif( $command =~ /.*E-Mail.*/ ){
fhem("get PostIt mail ".$liste);
fhem("set GalaxyTab ttsSay ".$liste." per Email verschickt");
}elsif( $command =~ /.*(T|t)eleg.*/ ){
fhem("get PostIt message ".$liste);
fhem("set GalaxyTab ttsSay ".$liste." per Telegramm verschickt");
}elsif( $command =~ /.*(H|h)inzufügen.*/ ){
$command =~ s/.*(H|h)inzufügen\s+//;
fhem("set PostIt add ".$liste." ".$command);
fhem("set GalaxyTab ttsSay Zur ".$liste." hinzugefügt ".$command);
}elsif( $command =~ /.*(Ä|ä)ndern.*/ ){
$command =~ s/.*(Ä|ä)ndern\s+//;
fhem("set PostIt modify ".$liste." ".$command);
fhem("set GalaxyTab ttsSay Auf ".$liste." geändert ".$command);
}elsif( $command =~ /.*(E|e)ntfernen.*/ ){
$command =~ s/.*(E|e)ntfernen\s+//;
my $res=fhem("set PostIt remove ".$liste." ".$command);
fhem("set GalaxyTab ttsSay Von der ".$liste." entfernt ".$command);
}else{
fhem("get PostIt ttsSay ".$liste);
}

=Einbinden in die FHEM-Anzeige=
PostMes können in jede beliebige Webseite eingebunden werden. Beispielsweise kann auch das Standard-Attribut ''icon'' des diesem Postme-System zugeordneten Devices durch einen der folgenden Codes ersetzt werden.
* Mit dem HTML-Code
<embed src="/fhem/PostMe_widget?type=pins&postit=''<devicename>''"/>
wird eine interaktive Liste aller Titelzeilen der PostMes dieses Systems angezeigt.
* Mit dem Code
<embed src="/fhem/PostMe_widget?type=pin&postit=''<devicename>''&name=''<name>''"/>
wird ein einzelnes PostMe mit dem Namen ''<name>'' als Titelzeile angezeigt. Zur Anpassung der Höhe kann man noch ein ''height''-Attribut einsetzen, z.B.:
<embed src="/fhem/PostMe_widget?type=pin&postit=''<devicename>''&name=''<name>''" height="350"/>
==Art der Widgets==
In diesen Darstellungen kann durch die Maus erreicht werden, dass zur einzeiligen Anzeige der Titelzeile der volle Inhalt des PostMes angezeigt wird.
* Wenn das Attribut ''postmeClick'' auf 0 gesetzt ist (Default-Wert), erfolgt die Anzeige und das Löschen des PostMe-Inhaltes durch Überfahren bzw. Wegfahren des Mauszeigers auf die Titelzeile.
* Wenn das Attribut ''postmeClick'' auf 1 gesetzt ist, muss die Titelzeile angeklickt werden, um den Inhalt zu sehen - und das entsprechens Fenster bzw. die Dialogbock explizit geschlossen werden.
Welcher Art die Anzeige des PostMe-Inhalte ist, wird durch ein anderes Attribut geregelt.
* Wenn ''postmeStyle=jQuery" (Default-Wert), erfolgt die Anzeige in einer jQuery-Dialogbox.
* Wenn ''postmeStyle=HTML", erfolgt die Anzeige in einem neuen (kleinen) Browser-Fenster.
* Wenn ''postmeStyle=SVG", erfolgt die Anzeige in einer SVG-Viewbox.

==Aussehen der Widgets==
Die oben genannten Widgets werden in ihrem Aussehen über Cascading Stylesheets gesteuert. Drei Klassen sind dafür relevant, sie sollten in die Datei '''style.css''' (oder, wenn man einen anderen Stylesheet-Präfix gesetzt hat, <präfix>style.css) eingetragen werden. Mit beispielhafter Farbe für die Widgets:
.postmeclass { background-color:#ffee80; padding:10px; border-color:black; border:groove}
.postmeclass2 { background-color:#ffee80; padding:10px;}

=Steuerung per Telegram=
Mit dem Messenger ''Telegram'' kann man Kommandos von außen an FHEM schicken. Dazu pollt der Telegram-Client, der mit Hilfe des [[TelegramBot|TelegramBot-Moduls]] realisiert wird, in regelmäßigen Abständen einen entsprechenden Server im Internet. Nach derzeitigem Stand der Technik ist das sicher, allerdings ist es empfehlenswert, diesen TelegramBot nicht auf dem gleichen Rechner wie das FHEM-Hauptsystem laufen zu lassen (siehe Anleitung [[TelegramBot]]).

Mit einem solchen Kommando kann man z.B. einen Dummy setzen - das löst einen Event aus, der via FHEM2FHEM auch auf entfernten FHEM-Systemen registriert werden kann. Mit einem notify bzw. DOIF kann dieser Event abgefangen und zur Absendung einer Antwort durch das PostMe-Modul verwendet werden:

define Remote.N DOIF ([Task] eq "Einkaufsliste") (get PostIt Einkaufsliste message,set Remote.Task Einkaufsliste Telegram)

Insgesamt führt dies dazu, dass man z.B. einfach von außen an seinen eigenen TelegramBot die Nachricht
''magisches_Codewort'' set Task Einkaufsliste
senden kann - und kurz darauf die Einkaufsliste zurückbekommt.
== Komfortabel verwalten mit ''Favorites''==
Komfortabler ist die Bedienung von PostMe mit Telegram, wenn man diesem Messenger so genannte ''Favorites'' beibringt - das sind bevorzugte Kommandos. Beim Absenden dieser Kommandos auf einem Smartphone genügt es, die Kommandoabkürzung mit einem vorangestellten "/" zu senden. Definiert man beispielsweise für das Telegram-Device (''NICHT für das Postme-Device'')
attr Telegram favorites
/H=set Telegram message "/Einkauf <sonstige Listen>";
/Einkauf=set Task get PostIt message Einkaufsliste;
/Einkauf+=set Task set PostIt add Einkaufsliste;
/Einkauf-=set Task set PostIt remove Einkaufsliste;
so kann man mit der Telegram-Nachricht
/H
ein auswählbares Menü seiner Listen erhalten, mit
/Einkauf
die Einkaufsliste abrufen und mit
/Einkauf+ <Item>
/Einkauf- <Item>
Gegenstände hinzufügen oder entfernen.
'''Achtung:''' Eigentlich ist das eine Sicherheitslücke, weil das magische Codewort nicht nötig ist. Man sollte also erstens die Telegram-User sorgfältig begrenzen, die diese Kommandos ausführen können, und zweitens auf keinen Fall beliebige FHEM-Kommandos über diesen Mechanismus ausführbar machen. Im hier diskutierten Fall (separate FHEM-Instanz und Trennung per FHEM2FHEM, indem hier nur die Task-Variable gesetzt wird) kann das also als sicher gelten.
== Noch komfortabler verwalten mit ''Inline-Keyboards''==
{{Randnotiz|RNTyp=Info|RNText=Inzwischen gibt es für diese Funktionalität ein eigenes Modul [https://fhem.de/commandref.html#TBot_List TBot_List], das die Kopplung von TelegramBot und PostME ohne zusätzlichen perlcode erlaubt }}

Noch komfortabler ist die Bedienung von PostMe mit Telegram, wenn man diesem Messenger so genannte ''Inline-Keyboards'' beibringt. Das geht auf zweierlei Arten, die im Folgenden dokumentiert sind.
{| class="wikitable"
|scope="col" style="width: 1000px" colspan="2"|[[File:Pmbot1.png |450px]]
|-
|scope="col" style="width: 1000px" colspan="2"|Benutzer tippt im Client auf den Button "PostIt". Im FHEM wird über ein notify, das auf ''queryData'' triggert, eine Erkennungsroutine aufgerufen, der Benutzer erhält:
|-
|style="width: 500px; vertical-align:top" |[[File:Pmbot2.png |450px]]
|style="width: 500px; vertical-align:top" |[[File:Pmbot2b.png |450px]]
|-
|scope="col" style="width: 1000px" colspan="2"|Benutzer tippt im Client auf den Button "Einkauf".Im FHEM wird über ein notify, das auf ''queryData'' triggert, eine Erkennungsroutine aufgerufen, der Benutzer erhält:
|-
|style="width: 500px; vertical-align:top" |[[File:Pmbot3.png |450px]]
|style="width: 500px; vertical-align:top" |[[File:Pmbot3b.png |450px]]
|-
|scope="col" style="width: 500px; vertical-align:top"|Benutzer tippt im Client auf den Button "Einkauf hinzu".
Im FHEM wird wieder über das notify, das auf ''queryData'' triggert, eine Erkennungsroutine aufgerufen. Diese stellt fest, dass etwas hinzugefügt werden soll sendet an den Client eine msgForceReply "Eingabe einzufügender Posten". Im TelegramBot wird ein Userreading gesetzt auf "add Einkaufsliste"
|scope="col" style="width: 500px; vertical-align:top"|Benutzer tippt im Client auf den Button "hinzufügen".
Im FHEM wird wieder über das notify, das auf ''queryData'' triggert, eine Erkennungsroutine aufgerufen. Diese stellt fest, dass etwas hinzugefügt werden soll sendet an den Client eine msgForceReply "Eingabe einzufügender Posten". Im TelegramBot wird ein Userreading gesetzt auf "add Einkaufsliste"
|-
|style="width: 1000px" colspan="2"|[[File:Pmbot4.png |450px]]
|-
|scope="col" style="width: 1000px" colspan="2"|Benutzer tippt im Client einen Gegenstand ein und sendet diesen an den TelegramBot. Dasselbe notify triggert AUCH auf msgReplyMsgId und ruft erneut die Erkennungsroutine, diese weiß aus dem Userreading, was sie zu tun hat und führt aus
set PostIt add Einkaufsliste Gegenstand
|-
|scope="col" style="width: 500px; vertical-align:top" |Zur Überprüfung tippt der Benutzer erneut auf den Button "Einkauf" und erhält
|scope="col" style="width: 500px; vertical-align:top" |Der Benutzer erhält automatisch
|-
|style="width: 500px; vertical-align:top" |[[File:Pmbot5.png |450px]]
|style="width: 500px; vertical-align:top" |[[File:Pmbot5b.png |450px]]
|-
|scope="col" style="width: 1000px" colspan="2"|
Dazu benötigt man erst einmal, dass die Favorites beim Start eine externe Routine '''telegramRecognition''' aufrufen:
attr Telegram favorites /start={telegramRecognition("menuData: Hauptmenü")};
Außerdem das notify, das auf die richtigen Events triggert
define Telegram.N notify Telegram:((queryData)|(msgReplyMsgId)).* {telegramRecognition("$EVENT")}
|}
Die Erkennungsroutine ist recht komplex, sie wird im Folgenden komplett dargestellt:
#############################################################################
#
# TelegramInlineKeyboard
#
#############################################################################
sub telegramRecognition($){
my ($event) = @_;
my $querypeer = ReadingsVal("TelegramBot", "queryPeer", 0);
my $msgpeer = ReadingsVal("TelegramBot", "msgPeer", 0);
my $queryReplyMsgId= ReadingsVal("TelegramBot", "queryReplyMsgId", 0);
my $MsgId = ReadingsVal("TelegramBot", "MsgId", 0);
my $menuMsgId = ReadingsVal("TelegramBot", "menuMsgId", $queryReplyMsgId);
my $calldata = ReadingsVal("TelegramBot", "callData", "");
my $tg;
my $dp;
my $dm;
my $res;
my $cmd;
my $click;
my ($cb1,$cb2,$cb1raw);

#-- Dieses Flag wird =1 gesetzt, wenn das PostMe-Device auf in derselben FHEM-Instanz läuft,
# =0, wenn das PostMe-Device auf einer anderen FHEM-Instanz läuft und per FHEM2FHEM
# bedient wird
my $postitlocal=1;

#-- Hier kann man - ggf. für jeden $querypeer anders ! - einstellen, welcher Bestätigungstext vom Bot
gesendet wird, und ob es eine nicht-klickbare Liste (linke Spalte oben) oder eine klickbare Liste
(rechte Spalte oben) sein soll
if( $querypeer eq "Peter_A._Henning"){
fhem("attr TelegramBot queryAnswerText Gerne zu Diensten, Meister !");
$click=1;
}elsif( $querypeer eq "Jacqueline_Henning"){
fhem("attr TelegramBot queryAnswerText Gerne zu Diensten, Jacqueline !");
$click=0;
}else{
fhem("attr TelegramBot queryAnswerText Gerne zu Diensten!");
$click=0;
}

#-- Klick event from inline keyboard
if( $event =~ /queryData\:\s(.*)/ ){
($cb1,$cb2) = split(/ /,$1,2);
#-- Level 0/1 => new menuMsgId after start of Bot
if( $cb1 =~ /(PostIt)|(Steuerung)/ ){
$menuMsgId = $queryReplyMsgId;
fhem("setreading TelegramBot menuMsgId $menuMsgId");
}
#-- Level 0
if( $cb1 eq "Hauptmenü"){
fhem("set TelegramBot queryInline \@$querypeer (PostIt) (Steuerung) Hauptmenü");
#-- Level 1
}elsif( $cb1 eq "PostIt"){
#-- PostIt-Menü für nicht-klickbare Listen
if( $querypeer eq "Jacqueline_Henning"){
fhem("set TelegramBot queryEditInline $menuMsgId \@$querypeer (Hauptmenü) (Einkauf|Einkauf hinzu|Einkauf entf) (Baumarkt|Baumarkt hinzu|Baumarkt entf) PostIt Listenverwaltung;");
#-- PostIt-Menü für nicht-klickbare Listen
}elsif( $querypeer eq "Peter_A._Henning"){
fhem("set TelegramBot queryEditInline $menuMsgId \@$querypeer (Hauptmenü) (Einkauf) (Baumarkt) PostIt Listenverwaltung;");
}
}elsif( $cb1 eq "Steuerung"){
... HIER NOCH ANDERE UNTERMENUS FÜR STEUERUNGSZWECKE
#-- Level 2/3 PostIt
}elsif( $cb1 =~ /((Einkauf)|(Baumarkt)).*/ ){
my $cb1raw = $cb1;
if( $cb1 =~ /Einkauf.*/){
$cb1 = "Einkaufsliste";
$tg = 1;
$dp = "<hier Adressaten>";
#$click = 0;
}elsif( $cb1 =~ /Baumarkt.*/){
$cb1 = "Baumarktliste";
$tg = 2;
$dp = "\<hier Adressaten>";
#$click = 0;
}
#-- Level 2/3 for clickable items
if( $click==1 ){
#-- Level 3 to delete an item
if( $cb1raw =~ /.*item\d\d/ ){
$cb2 = $cb1raw;
$cb2 =~ s/^.*_//;
if( $postitlocal==1 ){
#-- local version
fhem("set PostIt remove $cb1 $cb2");
}else{
#-- remote version
fhem("set Task_90 set PostIt remove $cb1 $cb2");
}
#-- redisplay the list - small delay
InternalTimer(gettimeofday()+1, "telegramRecognition","queryData: $cb1",0);
#-- Level 3 to add an item
}elsif( $cb1raw =~ /.*add/ ){
fhem("set TelegramBot msgForceReply \@$querypeer Eingabe hinzuzufügender Posten");
fhem("setreading TelegramBot prevCmd add $cb1");
#-- Level 2 for clickable items
}else{
if( $postitlocal==1 ){
#-- local version
$res = PostMe_tgi("PostIt",$cb1);
}else{
#-- remote version
$cmd = "/opt/fhem/getList.sh PostIt ".$cb1;
$res = `$cmd`;
}
fhem("set TelegramBot queryEditInline $menuMsgId \@$querypeer (Hauptmenü|PostIt|hinzufügen:".$cb1."_add) ".$res."\n Klicken zum Entfernen");
}
#-- Level 2/3 for non-clickable items
}elsif( $click==0 ){
if( $cb2 ){
#-- Level 3 to delete an item
if( $cb2 eq "entf" ){
fhem("set TelegramBot msgForceReply \@$querypeer Eingabe zu entfernender Posten");
fhem("setreading TelegramBot prevCmd remove $cb1");
#-- Level 3 to add an item
}elsif( $cb2 eq "hinzu" ){
fhem("set TelegramBot msgForceReply \@$querypeer Eingabe hinzuzufügender Posten");
fhem("setreading TelegramBot prevCmd add $cb1");
}
#-- Level 2 for non-clickable items
}else{
if( $postitlocal==1 ){
#-- local version
fhem(sprintf("attr PostIt postme%02dMsgRec \@$querypeer",$tg));
fhem( "get PostIt message $cb1");
fhem(sprintf("attr PostIt postme%02dMsgRec %s",$tg,$dp));
}else{
#-- remote version
fhem(sprintf("set Task_90 attr PostIt postme%02dMsgRec \@$querypeer",$tg));
fhem( "set Task_90 get PostIt message $cb1");
fhem(sprintf("set Task_90 attr PostIt postme%02dMsgRec %s",$tg,$dp));
}
}
}
}
#-- Level 0 after start of bot
}elsif( $event =~ /menuData\:\s*(.*)\s*(.*)/ ){
my $cb1 = $1;
my $cb2 = $2;
if( $cb1 eq "Hauptmenü"){
if( $msgpeer eq "Jacqueline_Henning"){
fhem("set TelegramBot queryInline \@$msgpeer (PostIt) (Steuerung) Hauptmenü");
}elsif( $msgpeer eq "Peter_A._Henning"){
fhem("set TelegramBot queryInline \@$msgpeer (PostIt) (Steuerung) Hauptmenü");
}else{
fhem("set TelegramBot queryInline \@$msgpeer (PostIt) Hauptmenü");
}
}
#-- Process line from forced reply
}elsif( $event =~ /msgReplyMsgId\:\s+(\d*)/ ){
my $mn = $1;
my $mo = ReadingsVal("TelegramBot", "prevMsgId", 0)+1;
my $prev = ReadingsVal("TelegramBot","prevCmd","none");
if( $prev =~ /((add)|(remove)).*/ ){
if( $postitlocal==1 ){
#-- local version
fhem("set PostIt $prev ".ReadingsVal("TelegramBot","msgText",""));
}else{
#-- remote version
fhem("set Task_90 set PostIt $prev ".ReadingsVal("TelegramBot","msgText",""));
}
fhem("setreading TelegramBot prevCmd none");
#-- redisplay the list - small delay
$prev =~ s/((add)|(remove))\s*//;
InternalTimer(gettimeofday()+1, "telegramRecognition","queryData: $prev",0);
}
}
}

TelegramBot

2017-03-26T21:31:34Z

Viegener: Changed icon for randnotiz

{{Infobox Modul
|ModPurpose=Senden und Empfangen von Nachrichten (Text und Fotos) mit dem freien Messagingdienst Telegram
|ModType=d
|ModForumArea=Unterstützende Dienste
|ModFTopic=38328
|ModTechName=[https://github.com/viegener/Telegram-fhem/blob/master/50_TelegramBot.pm 50_TelegramBot.pm]
|ModOwner=[[Benutzer:Viegener|Viegener]] ({{Link2FU|12772|Forum}} / [[Benutzer Diskussion:Viegener|Wiki]])}}

Das [[TelegramBot]]-Modul ermöglicht das Senden und Empfangen von Nachrichten über den Telegram-instant messaging Dienst (https://telegram.org/).
Es entsteht eine Möglichkeit Benachrichtungen aus FHEM zu versenden, zum Beispiel Alarmmeldungen.
Ausserdem können auch Kommandos über Telegram an FHEM gesendet werden um Steuerungsbefehle in FHEM auszulösen.

Das TelegramBot-Modul benötigt keine Zusatzsoftware auf dem FHEM-Server (anders als die Variante [[Telegram]]), sondern verwendet das [https://core.telegram.org/bots/api TelegramBot-API] über https-Aufrufe. Es muss jedoch das [http://www.fhemwiki.de/wiki/Raspberry_Pi#N.C3.BCtzliche_Zusatzpakete perl JSON modul] installiert sein.

== Über Telegram Instant Messaging ==
Telegram-IDs und Versand/Empfang von Nachrichten sind kostenfrei.
Clients sind für gängige Smartphonesysteme erhältlich (iOS iPhone und Tablet, Android, Windows Phone) und
können auch aus dem WebBrowser verwendet werden.
Es gibt auch einen Kommandozeilen-Client für Linux, der die Grundlage dieses Moduls darstellt.
Mehrfachanmeldungen, auch parallel mit verschiedenen Geräten (z.B. Tablet und Smartphone), sind möglich.
Gruppenchats und Chats mit End-2-End-Verschlüsselung werden ebenfalls unterstützt.

Für die Unterstützung von ''WhatsApp'' siehe Modul [[yowsup]].

== Features ==
Unterstützt werden:

* Versand von Textnachrichten
* Versand und Empfang von Bildern/Audio/etc
* Empfang von Textnachrichten von beliebigen Kontakten
* Kommandos in FHEM über Telegram-Nachrichten von aussen auslösen
* Ergebnisse der Kommandos zusenden lassen

Eine detaillierte Beschreibung des Moduls ist im FHEM Forum und in der (englischen) Dokumentation zum Modul in der Commandref diesem {{Link2Forum|Topic=38328|LinkText=Diskussionsthread}} zu finden. Seit Oktober 2015 wird das Modul offiziell über FHEM-Update verteilt.

Die jeweils aktuellste Entwicklungs-Version des Moduls ist in Github [https://github.com/viegener/Telegram-fhem/blob/master/50_TelegramBot.pm 50_TelegramBot.pm] verfügbar.

== Hinweise zum Betrieb mit FHEM ==
{{Randnotiz|RNTyp=Info|RNText=Achtung: Dieses Authtoken ist die einzige Authentifizierung für den Bot und sollte deshalb nicht aus der Hand gegeben werden. Die verwendeten Urls sind deshalb auch in den Log-Files nicht enthalten, da diese das Authtoken in Klartext enthalten. Auch im Forum sollte dieses Token nicht aufgenommen werden.
}}

Für die Anlage eines TelegramBot Devices in FHEM ist ein Authtoken erforderlich. Dieses Token wird über Anlegen eines neuen Bots im [https://core.telegram.org/bots#botfather BotFather] erzeugt. Dort mit dem Telegram-Befehl <code>/newbot</code> einen neuen Bot anlegen und mit einem Namen versehen. Hinweis: Die Namen für Bots müssen auf "Bot" enden. 

Das Anlegen eines TelegramBot devices erfolgt durch die Angabe dieses Tokens:

<code>define <name> TelegramBot <token> </code>

Beispiel: <code>define teleBot TelegramBot 110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw</code>

'''Das Empfangen von Nachrichten (polling) erfordert die Einstellung des Attributes'''
<code>pollingTimeout</code> '''auf einen Wert der grösser als Null ist. Beim Wert 0 oder ohne Setzen des Attributes findet kein Polling und damit auch kein Empfang statt.'''

Beispiel: <code>attr teleBot pollingTimeout 120</code>

'''Der TelegramBot kann erst dann Nachrichten an einen telegram user schicken, wenn dieser zuerst an den telegram bot eine Nachricht gesendet hat.'''

{{Randnotiz|RNTyp=Info|RNText=TelegramBot setzt eine aktuelle Version von FHEM voraus, insbesondere Versionen weit vor der Umstellung auf 5.7 (also vor Herbst 2015) können mit einem TelegramBot-Modul nicht funktionieren, da insbesondere das HTTPSRV-Modul dann veraltet ist. Am besten auch den TelegramBot über den offiziellen Update mit dem Rest von FHEM installieren/aktualisieren.
}}

== Registrierung eines neuen Bot ==
Zur Registrierung wird ein funktionierender Telegram-Client (egal ob Web, App oder Programm)benötigt. Hier wird ein Chat zum BotFather gestartet und der Befehl /newbot gesendet. Nun fragt der BotFather die benötigten Angaben ab und liefert am Ende des Dialogs die Informationen für den neuen Bot.
Hier ein Beispiel, wie so ein Chat aussehen könnte:
<pre>Client:
/newbot
----------------
BotFather:
Alright, a new bot. How are we going to call it? Please choose a name for your bot.
----------------
Client:
Mein Name
----------------
BotFather:
Good. Now let's choose a username for your bot. It must end in `bot`. Like this, for example: TetrisBot or tetris_bot.
----------------
Client:
fhem_bot
----------------
BotFather:
Sorry, this username is already taken. Think of something different.
----------------
Client:
fhem1234_bot
----------------
BotFather:
Done! Congratulations on your new bot.
You will find it at telegram.me/fhem1234_bot.
You can now add a description, about section and profile picture for your bot, see /help for a list of commands.
----------------
Use this token to access the HTTP API:
1234567890:AbCdefgHIJklmnOPQRst-uvwxyz

For a description of the Bot API, see this page: https://core.telegram.org/bots/api
</pre>
Um einen Chat an einen "Contact" versenden zu können, muss zuerst in Contacts (bei Readings) ein Kontakt auftauchen. Wenn man sich zum allerersten Mal bei Telegram angemeldet hat, gibt es noch keinen Chat mit irgendjemanden. Man muss sich zuerstmal selbst eine Nachricht im Smartphone zusenden, dann taucht unter Readings der Eintrag Contacts auf. Erst dann kann man eine Nachricht mit @msgPeerId (das ist Ziffernfolge des Contacts ) oder mit @msgPeer (das ist der Name nach dem Doppelpunkt) vom TelegramBot auf sein Smartphone senden.

== Tipps ==

=== Privacyeinstellungen ===

Damit der TelegramBot auch Meldungen in Gruppen sieht, müssen über den BotFather die Privacy-Einstellungen geändert werden. Beispielchat:<pre>Client:
/setprivacy
----------------
BotFather:
Choose a bot to change group messages settings.
----------------
Client:
@fhem1234_bot
----------------
BotFather:
'Enable' - your bot will only receive messages that either start with the '/' symbol or mention the bot by username.
'Disable' - your bot will receive all messages that people send to groups.
Current status is: ENABLED
----------------
Client:
Disable
----------------
BotFather:
Success! The new status is: DISABLED. /help</pre>

=== Kontakte ===

Der Bot merkt sich die bereits bekannten Kontakte im Reading <code>Contacts</code>. Dabei werden die einzelnen Kontakte jeweils als 3-teilige Einträge bestehend aus UserID, Vor- und Nachname des Benutzers (mit _ verbunden) und dem Username (mit vorangestelltem @).

Beispiel: <code>123456:Ralf_Mustermann:@ralf</code>

Verschiedene Einträge werden durch Leerzeichen getrennt.

Man kann die Kontakte auch manuell überschreiben (z.B. wenn das Reading fehlerhaft oder verloren sein sollte). Dazu gibt es den Set-Befehl <code>replaceContacts</code>. Dieser nimmt die Kontakte ebenfalls in der gleichen Form wie oben beschrieben entgegen.

Die Kontaktliste wird ansonsten nur durch den Empfang von Nachrichten erweitert, da es im TelegramBot-API keine Möglichkeit gibt Kontaktdaten von Telegram abzufragen (siehe auch pollingTimeout)

=== Reset ===

Es ist möglich den Bot im laufenden Betrieb zurückzusetzen (Set-Befehl <code>reset</code>). Dabei werden noch nicht abgeschlossene Übetragungen entfernt und die internen Zustände des Devices zurückgesetzt.

=== Gruppen ===

Um eine Nachricht von FHEM an eine Gruppe zu senden, muss der BOT in die Gruppe aufgenommen werden. Nach dem Senden einer Nachricht an die Gruppe kann im Modul die Gruppen-ID ermittelt werden und zum Senden von Nachrichten verwendet werden. Wenn die Privacy-Einstellungen nicht auf 'Disabled' gesetzt wurden, muss die Nachricht mit einem Slash (/) beginnen.

==== Supergroups / Supergruppen ====

Auch die neuen Supergruppen werden mit dem Bot unterstützt, es ist allerdings zu beachten, dass bei der Umwandlung einer Gruppe in eine Supergruppe eine neue ID in den Kontakten von Telegram vergeben wird. Wenn man also wie empfohlen IDs zur Identifikation von Benutzern einsetzt, muss entsprechend angepasst werden.

== Beispielszenarien ==

=== Benachrichtigungen über Ereignisse ===

Das einfachste Szenario für die Integration von Messaging-Diensten mit FHEM ist zur Benachrichtigung über Ereignisse. Diese Funktion kann zum Beispiel verwendet werden, um über einen erfolgten Neustart von FHEM zu informieren:

<code>define notify_fhem_reload notify global:INITIALIZED set telebotdevice message fhem newly started - just now !</code>

In diesem Beispiel wird der Nachrichtentext "fhem newly started - just now !" an den als default eingestellten Kontakt (Attribut: defaultPeer) gesendet, sobald FHEM neu gestartet wurde. Natürlich kann man auch beliebige andere Benachrichtigungen einführen.

=== Versand von Bildern ===

Es ist auch möglich Bilder auf dem FHEM-Server, die zum Beispiel von einer Kamera oder einem Wettermodul stammen über Telegram zu versenden. So wäre es z.B. möglich jeweils morgens die aktuelle Wetterkarte zu erhalten.

ACHTUNG: TelegramBot verwendet das HTTPUtils-Modul zur Kommunikation mit dem TelegramBot-API. Erst mit der Version, die seit 22.10.2015
([r9576] HttpUtils.pm: Async write for POST Requests {{Link2Forum|Topic=41583|LinkText=FHEM-Forum}}) verteilt wird, erlaubt auch den Transfer grösserer Bilder. Die Grenze liegt ansonsten bei ca. 14kb auf Raspberries (Plattformspezifische Grenze).

<code>define notify_fhem_reload notify wetter:report set telebotdevice sendPhoto /opt/fhem/wetter.jpg</code>

Bei Erreichen des entsprechenden Status am Wetter-Modul wird ein Image über Telegram versendet. Hier sind lokale Pfade (relativ zu fhem) oder absolute Pfade wie oben möglich.

=== Versand von SVG-Plots ===

Der Versand ist nicht direkt über das Device möglich, jedoch über den Perl-Befehl 'TelegramBot_ExecuteCommand':

<code>{TelegramBot_ExecuteCommand($defs{"mein_telegramBot"}, meine_ZielID, '{plotAsPng("mein_SVG")}');; return;;}</code>

Hierbei ist die Ziel-ID ohne das @-Zeichen, Anführungszeichen o.ä. anzugeben. Das Ziel kann auch eine Gruppen-ID (beginnend mit dem Minus-Zeichen) sein.

mit <code> define cmd_sendTelegramSVG cmdalias TGSVG .* AS {TelegramBot_ExecuteCommand($defs{"mein_telegramBot"}, meine_ZielID, '{plotAsPng($EVENT)}');; return;;}</code>

kann man mit einem kurzen
<code> TGSVG SVG_Garten </code>
ein beliebiges SVG versenden.

Um das SVG nun noch mit einem Text zu versehen, muss eine Textnachricht dazu gesendet werden, was sich am einfachsten durch das Ausführen eines FHEM-Befehls auf Perl-Ebene realisieren lässt:

<code>{fhem "set mein_telegramBot message \@meine_ZielID Mein Text" ;; TelegramBot_ExecuteCommand($defs{"mein_telegramBot"}, meine_ZielID, '{plotAsPng("mein_SVG")}');; return;;}</code>

'''Hinweis:''' seit dem Update Ende Februar 2017 hat die Funktion einen Parameter mehr, somit benötigt

<code>{TelegramBot_ExecuteCommand($defs{"mein_telegramBot"}, meine_ZielID, '{plotAsPng("mein_SVG")}');; return;;}</code>

die folgende Erweiterung

<code>{TelegramBot_ExecuteCommand($defs{"mein_telegramBot"}, meine_ZielID, undef, '{plotAsPng("mein_SVG")}');; return;;}</code>

==== Voraussetzungen für den Versand von SVG-Plots ====
Es muss das Modul libimage-librsvg-perl installiert sein:

<code>sudo apt-get install libimage-librsvg-perl</code>

Evtl. sind weitere Module erforderlich:

<code>sudo apt-get install libgd-graph-perl

sudo apt-get install libgd-text-perl</code>

=== Empfang von Bildern oder ähnlichem ===

Beim Empfang von Bildern wird zuerst nur eine ID vom Telegram-Server empfangen, diese befindet sich im Reading <code>msgFileId</code> angelegt (<code>123456:xxxxxxxxxxxxxxxxxxxxxxx-xxxxxxxx</code>) und im Reading <code>msgText</code> steht dann so etwas wie
<code>received photo # Size: 107701</code>

Über das Get-Kommando <code>urlForFile</code> mit der ID aus dem msgFileId Reading lässt sich dann daraus ein URL ableiten, der dann zur eigentlichen Datei führt:

<code>https://api.telegram.org/file/bot123456:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/photo/file_25.jpg</code>

=== Versand von Emojis (Smileys) ===

Es ist auch möglich Emojis mit den (Text-)Nachrichten zu versenden. Die entsprechenden (Unicode-)Zeichen werden einfach direkt mit in den Text der Nachricht aufgenommen. Um das zu vereinfachen kann man das einfach per Copy und Paste von dieser Seite

http://apps.timwhitlock.info/emoji/tables/unicode (Spalte "Native")

übernehmen und mit der Nachricht verschicken.

Die Emojis können auch empfangen werden und werden so auch in FHEM / FHEMWeb angezeigt. Plattformspezifische (z.B. von iOS oder Android) Emojis werden dabei nicht unterstützt (gerade mit iOS sind viele neue farbige Emojis hinzugekommen, die wohl leider nur auf Apple-devices funktionieren).

=== Kommandos auslösen ===

Ein wichtiges Szenario ist die Möglichkeit Kommandos in FHEM ausführen zu können, ohne einen Zugang durch die Firewall einrichten zu müssen. Dazu ist die Definition eines Schlüsselwortes (Attribut: "cmdKeyword")erforderlich, mit dem man die Nachrichten beginnen muss, damit der TelegramBot die Kommandos erkennt.

<code>attr telebotdevice cmdKeyword doit</code>

Somit kann man dann durch Nachrichten die mit "doit" beginnen Kommandos an FHEM senden, die ähnlich wie im Kommandoeingabefeld von FHEMweb dann von FHEM ausgeführt werden. Das Ergebnis der Ausführung wird zurück an den Sender (und an den definierten defaultPeer) geschickt.

Somit können nicht nur Aktionen angestossen werden, sondern auch Infos abgefragt werden.

Beispiele

<code>doit set schalter on</code>

<code>doit list telegrambot</code>

{{Randnotiz|RNTyp=Warn|RNText=Achtung: Bei den Kommandos sollten man unbedingt das Attribut "cmdRestrictedPeer" setzen, damit nicht jeder Kommandos auf dem FHEM-Server ausführen kann. Dazu sollten die BenutzerIDs der erlaubten Benutzer (durch Leerzeichen getrennt angeben). Da Benutzernamen selber vergeben werden und nicht unbedingt eindeutig sind, sollten hier auch NUR BenutzerIDs verwendet werden.
}}

==== Favoriten für Kommandos anlegen ====

Grundidee bei den Favoriten ist, dass man lange Befehle, die man häufig braucht auf "Kurzwahl" legt.

Beispiel-Kommandos wie z.B. <code>set TYPE=ROLLADEN pos 100</code> und <code>set TYPE=ROLLADEN pos 0</code>, die man immer wieder braucht. Um nicht jedes mal dieses Kommando eintippen zu müssen auf dem Smartphone, kann man auch dafür Favoriten anlegen.

Dazu gibt man erst mal die beiden Kommandos getrennt durch Semikolon im Attribut favorites an:

<code>attr telegrambotdevice favorites set TYPE=ROLLADEN pos 100;set TYPE=ROLLADEN pos 0</code>

Um die Favorites jetzt ausführen zu können braucht man noch ein Schlüsselwort dafür.
Nehmen wir mal an man möchte die Favoriten mit <code>/short</code> ausführen können. Dazu muss dann das Attribut "cmdFavorites" setzen

<code>attr telegrambotdevice cmdFavorites /short</code>

Wenn man nun im Telegram Client
<code>/short 1</code> an den Bot schickt führt der Bot den ersten Favoriten aus und das Ergebnis der Ausführung wird zurückgeschickt.

Ausserdem kann man im Telegram Client
<code>/short</code> an den Bot schicken, dann antwortet der Bot mit

<pre>
Favorites

/short1 = set TYPE=ROLLADEN pos 100

/short2 = set TYPE=ROLLADEN pos 0

</pre>

Die Antworten werden als Schaltflächen dargestellt (Telegram inline Keyboard) und können am Mobile-Client direkt angeklickt werden um sie auszuführen.
Um die Beschriftung der Schaltflächen zu optimieren, können die Befehle im Attribut favorites mit Beschreibungen versehen werden:

<code>/[Rollaeden zu ]=set TYPE=ROLLADEN pos 100;/[Rollaeden auf]=set TYPE=ROLLADEN pos 0</code>

Nun antwortet der Bot auf das Schlüsselwort für die Favoriten mit:

<pre>
Favorites

/short1 = Rollaeden zu

/short2 = Rollaeden auf

</pre>

== Links ==
* Github Repository für die Telegram-FHEM Entwicklung: https://github.com/viegener/Telegram-fhem
* Infos zum Telegram BotFather: https://core.telegram.org/bots#botfather

* Source code für das 50_TelegramBot.pm-Modul: https://github.com/viegener/Telegram-fhem/blob/master/50_TelegramBot.pm

* Forum-Thread in dem das Modul vorgestellt wurde {{Link2Forum|Topic=38328|LinkText=FHEM-Forum}}
* Telegram messaging system https://telegram.org/
* TelegramBot API https://core.telegram.org/bots/api

FTUI Widget Readingsgroup

2017-02-11T15:01:00Z

Viegener: FHEM-Teile hinzugefügt und korrekturen

Das [[{{PAGENAME}}|readingsgroup Widget]] ist ein Widget für [[FHEM Tablet UI]], mit dem eine in FHEM definierte readingsGroup auch im FHEM Tablet UI angezeigt werden kann

<gallery>
File:Ftui_widget_readingsGroup.png
</gallery>

==Attribute==
{| class="wikitable"
!Attribut
!Beschreibung
!Standard-Wert
!Beispiel
|-
|'''data-device'''||FHEM-Device, dessen HTML-Inhalt angezeigt werden soll||||
|-
|'''data-get'''||Name des Readings, das eine Änderung der ReadingsGroup anzeigt||'STATE'||
|-
|'''data-max-update'''||Maximale Häufigkeit in Sekunden für das Update der ReadingsGoup||60||
|}

==Hinweise==
Im ReadingsGroup widget wird anders als in anderen widgets nicht der angegebene Wert aus dem Device dargestellt, sondern der HTML-Inhalt des angegebenen ReadingsGroup-Devices. Dieser HTML-Inhalt wird ohne Änderungen eingebettet. Das data-get Reading dient nur dazu ein nötiges Update der ReadingsGroup zu erkennen.

==CSS-Klassen==
Keine eigenen CSS-Klassen, im HTML-Rendering können aber Referenzen auf CSS-Klassen aus FHEMWeb enthalten sein

==Beispiele==
===ReadingsGroup von verschiedenen Thermo/Hygro-Sensoren===
Hier werden Readings für verschiedene Typen von Sensoren als Tabelle angezeigt.

[[File:Ftui_widget_readingsGroup.png]]

<source lang="html">
<header>THY readings</header>
<div class="cell">
<div data-type="readingsgroup" data-device="MyTHYReadings"></div>
</div>
</source>

Der Vollständigkeit halber noch die Definition der readingsGroup in FHEM
<pre>
define MyTHYReadings readingsGroup <%temperature_humidity>,<%temp_temperature>,<>,<%weather_humidity>,<>,<%measure_battery_50>,<>,<Update>
TYPE=LaCrosse:temperature,< >,humidity,< >,battery,< >,<{getTimeDiffDesc(getNewestTimestamp($DEVICE,"temperature","humidity"))}@temperature>
TYPE=CUL_TX:temperature,< >,humidity,< >,<>,< >,<{getTimeDiffDesc(getNewestTimestamp($DEVICE,"temperature","humidity"))}@temperature>
HMT_wz:measured-temp,< >,humidity,< >,battery,< >,<{getTimeDiffDesc(getNewestTimestamp($DEVICE,"measured-temp","humidity"))}@measured-temp>
HMT_lars:measured-temp,< >,<>,< >,battery,< >,<{getTimeDiffDesc(getNewestTimestamp($DEVICE,"measured-temp","battery"))}@measured-temp>
attr MyTHYReadings noheading 1
attr MyTHYReadings room TEMP
attr MyTHYReadings valueStyle style="text-align:right"
attr MyTHYReadings valueSuffix { "temperature" => ' C ', "measured-temp" => ' C ' , "humidity" => ' % ' }
</pre>

Und damit auch alles funktioniert hier noch der Perl-Code (aus 99_myUtils) für die beiden Perl-Routinen

<pre>
##############################################
# Berechne Zeitdifferenz von String zeit -> als Beschreibung
#
sub getTimeDiffDesc($) {

my ($str) = @_;

my $now = time;

my $td = $now - time_str2num( $str );

my $tstr = "???";

if ( $td < 1 ) {
$tstr = "<1m";
} elsif ( $td < 60 ) {
$tstr = "<1m";
} elsif ( $td < 3600 ) {
$tstr = sprintf("%2d", int(($td/60) + 0.5) )."m" ;
} elsif ( $td < (3600*24) ) {
$tstr = sprintf("%2d", int(($td/3600) + 0.5) )."h" ;
} else {
$tstr = int(($td/(3600*24)) + 0.5)."d" ;
}

return $tstr;
}

##############################################
# Berechne neuesten Zeitstempel von mehreren Stati
#
sub getNewestTimestamp($@) {

my ($device, @args) = @_;

my $nt = 0;
my $nts = "";

for(my $i=0; $i < int(@args); $i++) {
my $tds = ReadingsTimestamp($device,$args[$i],"");
if ( $tds ne "" ) {
my $td = time_str2num( $tds );
if ( $nt == 0 ) {
$nt = $td;
$nts = $tds;
} elsif ( $td > $nt ) {
$nt = $td;
$nts = $tds;
}
}
}

return $nts;
}
</pre>

[[Kategorie:FHEM Tablet UI]]

FTUI Widget Readingsgroup

2017-02-11T01:23:26Z

Viegener: Erster Entwurf für readingsGroup widget

Das [[{{PAGENAME}}|readingsgroup Widget]] ist ein Widget für [[FHEM Tablet UI]], mit dem eine in FHEM definierte readingsGroup auch im tablet UI angezeigt werden kann

<gallery>
File:Ftui_widget_readingsGroup.png
</gallery>

==Attribute==
{| class="wikitable"
!Attribut
!Beschreibung
!Standard-Wert
!Beispiel
|-
|'''data-device'''||FHEM-Device, dessen Reading Reading angezeigt werden soll||||
|-
|'''data-get'''||Name des Readings, das eine Änderung der ReadingsGroup angibt||'STATE'||
|-
|'''data-max-update'''||Maximale Häufigkeit in Sekunden für das Update der ReadingsGoup||60||
|}

==Hinweise==
Im ReadingsGroup widget wird anders als in anderen widgets nicht der angegebene Wert aus dem Device dargestellt, sondern der HTML-Inhalt des angegebenen Devices. Dieser HTML-Inhalt wird ohne Änderungen eingebettet. Das data-get Reading dient nur dazu ein nötiges Update der ReadingsGroup zu erkennen.

==CSS-Klassen==
Keine eigenen CSS-Klassen, im HTML-Rendering können aber Referenzen auf CSS-Klassen aus FHEMWeb enthalten sein

==Beispiele==
===ReadingsGroup von verschiedenen Thermo/Hygro-Sensoren===
Hier werden Readings für verschiedene Typen von Sensoren als Tabelle angezeigt.

[[File:Ftui_widget_readingsGroup.png]]

<source lang="html">
<header>THY readings</header>
<div class="cell">
<div data-type="readingsgroup" data-device="MyTHYReadings"></div>
</div>
</source>

[[Kategorie:FHEM Tablet UI]]

Datei:Ftui widget readingsGroup.png

2017-02-11T01:21:22Z

Viegener:

TelegramBot

2016-06-23T22:55:52Z

Viegener: Beispiel zu favoriten korrigiert

{{Infobox Modul
|ModPurpose=Senden und Empfangen von Nachrichten (Text und Fotos) mit dem freien Messagingdienst Telegram
|ModType=d
|ModForumArea=Unterstützende Dienste
|ModFTopic=38328
|ModTechName=[https://github.com/viegener/Telegram-fhem/blob/master/50_TelegramBot.pm 50_TelegramBot.pm]
|ModOwner=[[Benutzer:Viegener|Viegener]] ({{Link2FU|12772|Forum}} / [[Benutzer Diskussion:Viegener|Wiki]])}}

Das [[TelegramBot]]-Modul ermöglicht das Senden und Empfangen von Nachrichten über den Telegram-instant messaging Dienst (https://telegram.org/).
Es entsteht eine Möglichkeit Benachrichtungen aus Fhem zu versenden, zum Beispiel Alarmmeldungen.
Ausserdem können auch Kommandos über Telegram an Fhem gesendet werden um Steuerungsbefehle in Fhem auszulösen.

Das TelegramBot-Modul benötigt keine Zusatzsoftware auf dem Fhem-Server (anders als die Variante [[Telegram]]), sondern verwendet das [https://core.telegram.org/bots/api TelegramBot-API] über https-Aufrufe. Es muss jedoch das perl JSON modul installiert sein.

== Über Telegram Instant Messaging ==
Telegram-IDs und Versand/Empfang von Nachrichten sind kostenfrei.
Clients sind für gängige Smartphonesysteme erhältlich (iOS iPhone und Tablet, Android, Windows Phone) und
können auch aus dem WebBrowser verwendet werden.
Es gibt auch einen Kommandozeilen-Client für Linux, der die Grundlage dieses Moduls darstellt.
Mehrfachanmeldungen, auch parallel mit verschiedenen Geräten (z.B. Tablet und Smartphone), sind möglich.
Gruppenchats und Chats mit End-2-End-Verschlüsselung werden ebenfalls unterstützt.

Für die Unterstützung von ''WhatsApp'' siehe Modul [[yowsup]].

== Features ==
Unterstützt werden:

* Versand von Textnachrichten
* Versand und Empfang von Bildern/Audio/etc
* Empfang von Textnachrichten von beliebigen Kontakten
* Kommandos in Fhem über Telegram-Nachrichten von aussen auslösen
* Ergebnisse der Kommandos zusenden lassen

Eine detaillierte Beschreibung des Moduls ist im Fhem Forum und in der (englischen) Dokumentation zum Modul in der Commandref diesem {{Link2Forum|Topic=38328|LinkText=Diskussionsthread}} zu finden. Seit Oktober 2015 wird das Modul offiziell über Fhem-Update verteilt.

Die jeweils aktuellste Entwicklungs-Version des Moduls ist in Github [https://github.com/viegener/Telegram-fhem/blob/master/50_TelegramBot.pm 50_TelegramBot.pm] verfügbar.

== Hinweise zum Betrieb mit Fhem ==
{{Randnotiz|RNTyp=Warn|RNText=Achtung: Dieses Authtoken ist die einzige Authentifizierung für den Bot und sollte deshalb nicht aus der Hand gegeben werden. Die verwendeten Urls sind deshalb auch in den Log-Files nicht enthalten, da diese das Authtoken in Klartext enthalten. Auch im Forum sollte dieses Token nicht aufgenommen werden.
}}

Für die Anlage eines TelegramBot Devices in Fhem ist ein Authtoken erforderlich. Dieses Token wird über Anlegen eines neuen Bots im [https://core.telegram.org/bots#botfather BotFather] erzeugt. Dort mit dem Telegram-Befehl <code>/newbot</code> einen neuen Bot anlegen und mit einem Namen versehen. Hinweis: Die Namen für Bots müssen auf "Bot" enden. 

Das Anlegen eines TelegramBot devices erfolgt durch die Angabe dieses Tokens:

<code>define <name> TelegramBot <token> </code>

Beispiel: <code>define teleBot TelegramBot 110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw</code>

'''Das Empfangen von Nachrichten (polling) erfordert die Einstellung des Attributes'''
<code>pollingTimeout</code> '''auf einen Wert der grösser als Null ist. Beim Wert 0 oder ohne Setzen des Attributes findet kein Polling und damit auch kein Empfang statt.'''

Beispiel: <code>attr teleBot pollingTimeout 120</code>

'''Der TelegramBot kann erst dann Nachrichten an einen telegram user schicken, wenn dieser zuerst an den telegram bot eine Nachricht gesendet hat.'''

{{Randnotiz|RNTyp=Warn|RNText=TelegramBot setzt eine aktuelle Version von FHEM voraus, insbesondere Versionen weit vor der Umstellung auf 5.7 (also vor Herbst 2015) können mit einem TelegramBot-Modul nicht funktionieren, da insbesondere das HTTPSRV-Modul dann veraltet ist. Am besten auch den TelegramBot über den offiziellen Update mit dem Rest von FHEM installieren/aktualisieren.
}}

== Registrierung eines neuen Bot ==
Zur Registrierung wird ein funktionierender Telegram-Client (egal ob Web, App oder Programm)benötigt. Hier wird ein Chat zum BotFather gestartet und der Befehl /newbot gesendet. Nun fragt der BotFather die benötigten Angaben ab und liefert am Ende des Dialogs die Informationen für den neuen Bot.
Hier ein Beispiel, wie so ein Chat aussehen könnte:
<pre>Client:
/newbot
----------------
BotFather:
Alright, a new bot. How are we going to call it? Please choose a name for your bot.
----------------
Client:
Mein Name
----------------
BotFather:
Good. Now let's choose a username for your bot. It must end in `bot`. Like this, for example: TetrisBot or tetris_bot.
----------------
Client:
fhem_bot
----------------
BotFather:
Sorry, this username is already taken. Think of something different.
----------------
Client:
fhem1234_bot
----------------
BotFather:
Done! Congratulations on your new bot.
You will find it at telegram.me/fhem1234_bot.
You can now add a description, about section and profile picture for your bot, see /help for a list of commands.
----------------
Use this token to access the HTTP API:
1234567890:AbCdefgHIJklmnOPQRst-uvwxyz

For a description of the Bot API, see this page: https://core.telegram.org/bots/api
</pre>

== Tipps ==

=== Privacyeinstellungen ===

Damit der TelegramBot auch Meldungen in Gruppen sieht, müssen über den BotFather die Privacy-Einstellungen geändert werden. Beispielchat:<pre>Client:
/setprivacy
----------------
BotFather:
Choose a bot to change group messages settings.
----------------
Client:
@fhem1234_bot
----------------
BotFather:
'Enable' - your bot will only receive messages that either start with the '/' symbol or mention the bot by username.
'Disable' - your bot will receive all messages that people send to groups.
Current status is: ENABLED
----------------
Client:
Disable
----------------
BotFather:
Success! The new status is: DISABLED. /help</pre>

=== Kontakte ===

Der Bot merkt sich die bereits bekannten Kontakte im Reading <code>Contacts</code>. Dabei werden die einzelnen Kontakte jeweils als 3-teilige Einträge bestehend aus UserID, Vor- und Nachname des Benutzers (mit _ verbunden) und dem Username (mit vorangestelltem @).

Beispiel: <code>123456:Ralf_Mustermann:@ralf</code>

Verschiedene Einträge werden durch Leerzeichen getrennt.

Man kann die Kontakte auch manuell überschreiben (z.B. wenn das Reading fehlerhaft oder verloren sein sollte). Dazu gibt es den Set-Befehl <code>replaceContacts</code>. Dieser nimmt die Kontakte ebenfalls in der gleichen Form wie oben beschrieben entgegen.

Die Kontaktliste wird ansonsten nur durch den Empfang von Nachrichten erweitert, da es im TelegramBot-API keine Möglichkeit gibt Kontaktdaten von Telegram abzufragen (siehe auch pollingTimeout)

=== Reset ===

Es ist möglich den Bot im laufenden Betrieb zurückzusetzen (Set-Befehl <code>reset</code>). Dabei werden noch nicht abgeschlossene Übetragungen entfernt und die internen Zustände des Devices zurückgesetzt.

=== Gruppen ===

Um eine Nachricht von FHEM an eine Gruppe zu senden, muss der BOT in die Gruppe aufgenommen werden. Nach dem Senden einer Nachricht an die Gruppe kann im Modul die Gruppen-ID ermittelt werden und zum Senden von Nachrichten verwendet werden. Wenn die Privacy-Einstellungen nicht auf 'Disabled' gesetzt wurden, muss die Nachricht mit einem Slash (/) beginnen.

==== Supergroups / Supergruppen ====

Auch die neuen Supergruppen werden mit dem Bot unterstützt, es ist allerdings zu beachten, dass bei der Umwandlung einer Gruppe in eine Supergruppe eine neue ID in den Kontakten von Telegram vergeben wird. Wenn man also wie empfohlen IDs zur Identifikation von Benutzern einsetzt, muss entsprechend angepasst werden.

== Beispielszenarien ==

=== Benachrichtigungen über Ereignisse ===

Das einfachste Szenario für die Integration von Messaging-Diensten mit Fhem ist zur Benachrichtigung über Ereignisse. Diese Funktion kann zum Beispiel verwendet werden, um über einen erfolgten Neustart von Fhem zu informieren:

<code>define notify_fhem_reload notify global:INITIALIZED set telebotdevice message fhem newly started - just now !</code>

In diesem Beispiel wird der Nachrichtentext "fhem newly started - just now !" an den als default eingestellten Kontakt (Attribut: defaultPeer) gesendet, sobald Fhem neu gestartet wurde. Natürlich kann man auch beliebige andere Benachrichtigungen einführen.

=== Versand von Bildern ===

Es ist auch möglich Bilder auf dem Fhem-Server, die zum Beispiel von einer Kamera oder einem Wettermodul stammen über Telegram zu versenden. So wäre es z.B. möglich jeweils morgens die aktuelle Wetterkarte zu erhalten.

ACHTUNG: TelegramBot verwendet das HTTPUtils-Modul zur Kommunikation mit dem TelegramBot-API. Erst mit der Version, die seit 22.10.2015
([r9576] HttpUtils.pm: Async write for POST Requests {{Link2Forum|Topic=41583|LinkText=Fhem-Forum}}) verteilt wird, erlaubt auch den Transfer grösserer Bilder. Die Grenze liegt ansonsten bei ca. 14kb auf Raspberries (Plattformspezifische Grenze).

<code>define notify_fhem_reload notify wetter:report set telebotdevice sendPhoto /opt/fhem/wetter.jpg</code>

Bei Erreichen des entsprechenden Status am Wetter-Modul wird ein Image über Telegram versendet. Hier sind lokale Pfade (relativ zu fhem) oder absolute Pfade wie oben möglich.

=== Versand von SVG-Plots ===

Der Versand ist nicht direkt über das Device möglich, jedoch über den Perl-Befehl 'TelegramBot_ExecuteCommand':

<code>{TelegramBot_ExecuteCommand($defs{"mein_telegramBot"}, meine_ZielID, '{plotAsPng("mein_SVG")}');; return;;}</code>

Hierbei ist die Ziel-ID ohne das @-Zeichen, Anführungszeichen o.ä. anzugeben. Das Ziel kann auch eine Gruppen-ID (beginnend mit dem Minus-Zeichen) sein. Um das SVG nun noch mit einem Text zu versehen, muss eine Textnachricht dazu gesendet werden, was sich am einfachsten durch das Ausführen eines FHEM-Befehls auf Perl-Ebene realisieren lässt:

<code>{fhem "set mein_telegramBot message \@meine_ZielID Mein Text" ;; TelegramBot_ExecuteCommand($defs{"mein_telegramBot"}, meine_ZielID, '{plotAsPng("mein_SVG")}');; return;;}</code>

==== Voraussetzungen für den Versand von SVG-Plots ====
Es muss das Modul libimage-librsvg-perl installiert sein:

<code>sudo apt-get install libimage-librsvg-perl</code>

Evtl. sind weitere Module erforderlich:

<code>sudo apt-get install libgd-graph-perl

sudo apt-get install libgd-text-perl</code>

=== Empfang von Bildern oder ähnlichem ===

Beim Empfang von Bildern wird zuerst nur eine ID vom Telegram-Server empfangen, diese befindet sich im Reading <code>msgFileId</code> angelegt (<code>123456:xxxxxxxxxxxxxxxxxxxxxxx-xxxxxxxx</code>) und im Reading <code>msgText</code> steht dann so etwas wie
<code>received photo # Size: 107701</code>

Über das Get-Kommando <code>urlForFile</code> mit der ID aus dem msgFileId Reading lässt sich dann daraus ein URL ableiten, der dann zur eigentlichen Datei führt:

<code>https://api.telegram.org/file/bot123456:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/photo/file_25.jpg</code>

=== Versand von Emojis (Smileys) ===

Es ist auch möglich Emojis mit den (Text-)Nachrichten zu versenden. Die entsprechenden (Unicode-)Zeichen werden einfach direkt mit in den Text der Nachricht aufgenommen. Um das zu vereinfachen kann man das einfach per Copy und Paste von dieser Seite

http://apps.timwhitlock.info/emoji/tables/unicode (Spalte "Native")

übernehmen und mit der Nachricht verschicken.

Die Emojis können auch empfangen werden und werden so auch in FHEM / FHEMWeb angezeigt. Plattformspezifische (z.B. von iOS oder Android) Emojis werden dabei nicht unterstützt (gerade mit iOS sind viele neue farbige Emojis hinzugekommen, die wohl leider nur auf Apple-devices funktionieren).

=== Kommandos auslösen ===

Ein wichtiges Szenario ist die Möglichkeit Kommandos in Fhem ausführen zu können, ohne einen Zugang durch die Firewall einrichten zu müssen. Dazu ist die Definition eines Schlüsselwortes (Attribut: "cmdKeyword")erforderlich, mit dem man die Nachrichten beginnen muss, damit der TelegramBot die Kommandos erkennt.

<code>attr telebotdevice cmdKeyword doit</code>

Somit kann man dann durch Nachrichten die mit "doit" beginnen Kommandos an Fhem senden, die ähnlich wie im Kommandoeingabefeld von Fhemweb dann von Fhem ausgeführt werden. Das Ergebnis der Ausführung wird zurück an den Sender (und an den definierten defaultPeer) geschickt.

Somit können nicht nur Aktionen angestossen werden, sondern auch Infos abgefragt werden.

Beispiele

<code>doit set schalter on</code>

<code>doit list telegrambot</code>

{{Randnotiz|RNTyp=Warn|RNText=Achtung: Bei den Kommandos sollten man unbedingt das Attribut "cmdRestrictedPeer" setzen, damit nicht jeder Kommandos auf dem Fhem-Server ausführen kann. Dazu sollten die BenutzerIDs der erlaubten Benutzer (durch Leerzeichen getrennt angeben). Da Benutzernamen selber vergeben werden und nicht unbedingt eindeutig sind, sollten hier auch NUR BenutzerIDs verwendet werden.
}}

==== Favoriten für Kommandos anlegen ====

Grundidee bei den Favoriten ist, dass man lange Befehle, die man häufig braucht auf "Kurzwahl" legt.

Beispiel-Kommandos wie z.B. <code>set TYPE=ROLLADEN pos 100</code> und <code>set TYPE=ROLLADEN pos 0</code>, die man immer wieder braucht. Um nicht jedes mal dieses Kommando eintippen zu müssen auf dem Smartphone, kann man auch dafür Favoriten anlegen.

Dazu gibt man erst mal die beiden Kommandos getrennt durch Semikolon im Attribut favorites an:

<code>attr telegrambotdevice favorites set TYPE=ROLLADEN pos 100;set TYPE=ROLLADEN pos 0</code>

Um die Favorites jetzt ausführen zu können braucht man noch ein Schlüsselwort dafür.
Nehmen wir mal an man möchte die Favoriten mit <code>/short</code> ausführen können. Dazu muss dann das Attribut "cmdFavorites" setzen

<code>attr telegrambotdevice cmdFavorites /short</code>

Wenn man nun im Telegram Client
<code>/short 1</code> an den Bot schickt führt der Bot den ersten Favoriten aus und das Ergebnis der Ausführung wird zurückgeschickt.

Ausserdem kann man im Telegram Client
<code>/short</code> an den Bot schicken, dann antwortet der Bot mit

<pre>
Favorites

/short1 = set TYPE=ROLLADEN pos 100

/short2 = set TYPE=ROLLADEN pos 0

</pre>

Die Antworten werden als Schaltflächen dargestellt (Telegram inline Keyboard) und können am Mobile-Client direkt angeklickt werden um sie auszuführen.
Um die Beschriftung der Schaltflächen zu optimieren, können die Befehle im Attribut favorites mit Beschreibungen versehen werden:

<code>/[Rollaeden zu ]=set TYPE=ROLLADEN pos 100;/[Rollaeden auf]=set TYPE=ROLLADEN pos 0</code>

Nun antwortet der Bot auf das Schlüsselwort für die Favoriten mit:

<pre>
Favorites

/short1 = Rollaeden zu

/short2 = Rollaeden auf

</pre>

== Links ==
* Github Repository für die Telegram-Fhem Entwicklung: https://github.com/viegener/Telegram-fhem
* Infos zum Telegram BotFather: https://core.telegram.org/bots#botfather

* Source code für das 50_TelegramBot.pm-Modul: https://github.com/viegener/Telegram-fhem/blob/master/50_TelegramBot.pm

* Forum-Thread in dem das Modul vorgestellt wurde {{Link2Forum|Topic=38328|LinkText=Fhem-Forum}}
* Telegram messaging system https://telegram.org/
* TelegramBot API https://core.telegram.org/bots/api

--[[Benutzer:Viegener|Viegener]] ([[Benutzer Diskussion:Viegener|Diskussion]]) 22:49, 11. Okt. 2015 (CEST)

DevelopmentModuleAPI

2016-05-05T10:31:12Z

Viegener: Added SNAME for AnalyzeCommand

{{Randnotiz|RNTyp=r|RNText=Bitte beachten: Diese Auflistung von Funktionen wird nicht aktiv durch Entwickler gepflegt. Es kann daher keine Garantie auf Vollständigkeit und Korrektheit gegeben werden. Letztendlich entscheidend ist immer der Perl-Code, Unstimmigkeiten sollten im [https://forum.fhem.de/index.php/board,80.0.html FHEM-Forum] angemerkt werden!
<hr />
Please note: This list of functions is not official maintained by the developers. So there is no guarantee for completeness and correctness. In the end it is always the Perl code itself that is relevant; please report errors and omissions in the [https://forum.fhem.de/index.php/board,80.0.html FHEM forum]!
}}
Dieses Seite soll eine Beschreibung der für Moduleentwickler verfügbaren Funktionen enthalten, um für Modulentwickler
* Wiederverwendbare Routinen leichter identifizieren zu können
* Durch Wiederverwendung mehr Einheitlichkeit zu erzeugen
* Aufwand zu verringern
* Bei Änderungen auch betroffene Module leichter identifiziern zu können

Natürlich hat diese Seite keinen Anspruch auf Vollständigkeit und jeder ist aufgefordert mitzuarbeiten, sobald er beim Stöbern über einen Funktion stolpert, die auch andere interessieren könnte.

== FHEM-Befehlsausführung ==
=== AnalyzeCommand ===
AnalyzeCommand ermöglicht das Parsen und die Ausführung eines FHEM-Befehls, wie in [[FHEMWEB]] im Kommandoeingabefeld enthalten.
:<source lang="perl">$error = AnalyzeCommand($client_hash, $cmd)</source>

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''mandatory can be <code>undef</code>''
|| Der Definition-Hash, welcher für die Ausführung dieses Kommandos verantwortlich ist. Dies dient zur Prüfung, ob diese Definition das Kommando <code>$cmd</code> ausführen darf (Vorgangs-Typ: <code>cmd</code>). Der Definition-Hash muss in <code>SNAME</code> den zum Attribut <code>validFor</code> (im zugehörigen allowed-Device) passenden Devicenamen tragen, damit die Prüfung durchgeführt wird. Wenn anstatt eines Definitions-Hashes der Wert <code>undef</code> übergeben wird, erfolgt keine Prüfung.
|-
| style="vertical-align:top" | '''<code>$cmd</code>'''

''mandatory''
|| Kommandos, die ausgeführt werden sollen. 
Beispiel:
* ''define dummy1 dummy''
* ''{ Log3(undef, 1, "Hallo");}''
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>'''
|| Fehlermeldungen, die beim ausführen des Kommandos aufgetreten sind. Wenn keine Fehlermeldungen aufgetreten sind, wird <code>undef</code> zurückgegeben.
|}

=== AnalyzeCommandChain ===
AnalyzeCommandChain() ermöglicht die Ausführung von FHEM-Befehlsketten. Dabei werden mehrere FHEM-Kommandos durch ein Semikolon getrennt und nacheinander mittels AnalyzeCommand() ausgeführt.
:<source lang="perl">$errors = AnalyzeCommandChain ($client_hash, $cmds)</source>

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''mandatory can be <code>undef</code>''
|| Der Definition-Hash, welcher für die Ausführung dieser Kommandos verantwortlich ist. Dies dient zur Prüfung, ob diese Definition die Kommandos <code>$cmds</code> ausführen darf (Vorgangs-Typ: <code>cmd</code>).Der Definition-Hash muss in <code>SNAME</code> den zum Attribut <code>validFor</code> (im zugehörigen allowed-Device) passenden Devicenamen tragen, damit die Prüfung durchgeführt wird. Wenn anstatt eines Definitions-Hashes der Wert <code>undef</code> übergeben wird, erfolgt keine Prüfung.
|-
|-
| style="vertical-align:top" | '''<code>$cmds</code>'''

''mandatory''
|| Kommandokette, welche ausgeführt werden soll, durch <code>;</code> getrennt. 
Beispiel:
* <code>define dummy1 dummy; list dummy1; {Log(3,"dummy created")}</code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$errors</code>'''
|| Fehlermeldungen, die beim ausführen der Kommandos aufgetreten sind. Wenn keine Fehlermeldungen aufgetreten sind, wird <code>undef</code> zurückgegeben.
|}

=== EvalSpecials ===

:<source lang="perl">$final_cmd = EvalSpecials($cmd, %specials)</source>
EvalSpecials() ermöglicht die Ersetzung von Platzhaltern in FHEM-Befehlen, welche durch AnalyzeCommandChain() zur Ausführung gebracht werden sollen. Dabei werden alle Schlüssel von <code>%specials</code> in <code>$cmd</code> gesucht und durch die entsprechenden Werte aus <code>%specials</code> ersetzt.

Diese Funktion hat je nach gewähltem Featurelevel (globales Attribut <code>featurelevel</code>) unterschiedliches Verhalten um die Kompatibilität mit früheren FHEM-Versionen und deren Konfiguration zu wahren.

In jedem Falle muss der zurückgegebene String mit AnalyzeCommandChain() zur Ausführung gebracht werden.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$cmd</code>'''

''mandatory''
|| Eine gültige FHEM-Kommando-Kette welche mit etwaigen Platzhaltern versehen ist, die ersetzt werden sollen.

Bsp: <code>set $NAME power on; {Log(3, "power on $NAME for $ADDRESS")}</code>
|-
| style="vertical-align:top" | '''<code>%specials</code>'''

''mandatory''
|| Hash, welcher als Schlüssel die zu ersetzenden Platzhalter-Namen den zu ersetzenden Werten zuordnet. Jeder Schlüssel ist aus historischen Gründen mit einem Prozentzeichen zu beginnen. Die Platzhalter müssen zusammenhängend sein und dürfen nur aus Zahlen, Buchstaben und Unterstrichen (<code>_</code>) bestehen. Generell sollten die Schlüssel aber nur aus Großbuchstaben bestehen.

Bspw: <code>("%NAME" => "Definition_A", "%ADDRESS" => "192.168.0.2") </code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$final_cmd</code>'''
|| Das fertige Kommando, welches so direkt an AnalyzeCommandChain() übergeben werden muss.

Ab Featurelevel 5.7 sind die Platzhalter in diesem String nicht ersetzt. Die Ersetzung wird in diesem Fall in AnalyzeCommandChain() vorgenommen, wo die einzelnen Platzhalter ersetzt werden. Die Funktion EvalSpecials() speichert in diesem Falle nur den Hash im Hintergrund, die eigentliche Ersetzung wird dann durch AnalyzeCommandChain() und deren untergeordneten Funktionen übernommen.

In Featurelevel 5.6 und vorher wird ein Suchen/Ersetzen der Platzhalter in EvalSpecials() selbst vorgenommen. Hierbei ist der zurückgegebene String das finale Kommando, welches keine Platzhalter mehr beinhaltet.
|}

=== parseParams ===

:<source lang="perl">my($a, $h) = parseParams($cmd, $separator);</source>
parseParams() ermöglicht das Parsen von Kommandozeilenargumenten und lässt sich z.b. für die Parameter von define (DefFn), get (GetFn) und set (SetFn) verwenden. Beim Parsen werden erkannt:
* einfache durch den Separator getrennte Zeichenfolgen
* benannte Parameter der Form <code><name>=<wert></code>
** Werte können in einfache (<code>'</code>) oder doppelte (<code>"</code>) Anführungszeichen eingeschlossen sein um so den jeweiligen Separator zu enthalten
** Ein solches Pärchen aus gleichen Anführungszeichen an Anfang und Ende eines Wertes wird beim Parsen entfernt.
* in <code>{...}</code> eingeschlossener Perlcode. Hier wird nach der ersten öffnenden bis zur zugehörigen schliessenden Klammer gesucht. D.h. bis die gleichen Anzahl öffnender und schliessender Klammern erreicht ist.

In der Modul <code>X_Initialize</code> routine lässt sich festlegen das parseParams für die define, get und set argumente automatisch aufgerufen und das Ergebniss an die DefFn, GetFn und SetFn übergeben wird.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$cmd</code>'''

''mandatory''
|| Die Argumente des Kommandos als String oder als ArrayRef.

|-
| style="vertical-align:top" | '''<code>$separator</code>'''

''optional''
|| Der Separater an dem die Parameterzeile gesplittet werden soll.

Standardwert: ' '
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$a</code>'''
|| Eine Ref auf ein Array das alle nicht benannten Parameter in der Reihenfolge ihres vorkommen enthält.

|-
| style="vertical-align:top" | '''<code>$h</code>'''
|| Eine Ref auf einen Hash der die Werte aller benannten Parameter mit ihrem Namen als Key enthält.
|}

Beispiel: Die Zeile
:<code>set <name> test1 test2=abc test3 "test4 test4" test5="test5 test5" test6='test6=test6' test7= test8="'" test9='"' {my $x = "abc"} test10={ { my $abc ="xyz" } }';</code>
wird in die folgenden Elemente geparsed:
<source lang="perl">
#Die nicht benannten Paramter:
$a = [
'set',
'<name>',
'test1',
'test3',
'test4 test4',
'{my $x = "abc"}'
];

#Die benannten Parameter:
$h = {
'test10' => '{ { my $abc ="xyz" } }',
'test5' => 'test5 test5',
'test8' => '\'',
'test2' => 'abc',
'test7' => '',
'test9' => '"',
'test6' => 'test6=test6'
};
</source>

== Time / Timestamp ==

=== FmtDateTimeRFC1123===

<ul><source lang="perl">$timestampGMT = FmtDateTimeRFC1123($timestamp)</source>
</ul>
Gibt den übergebenen UNIX-Timestamp (Sekunden seit EPOCH-Beginn) formatiert nach RFC 1123 zurück.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp</code>'''

''mandatory''
|| Zeitangabe wie sie von der <code>time()</code> Funktion zurückgegeben wird 

Bsp: <code>1457201868</code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestampGMT </code>'''

|| Zeitstempel GMT (Greenwich Mean Time) wie er in RFC 1123 beschrieben wird. Diese werden zum Beispiel bei http verwendet. 
<code>Sat, 05 Mar 2016 18:17:48 GMT</code>
|}

=== FmtDateTime===
:<source lang="perl">$timestamp = FmtDateTime($time)</source>
Wandelt einen UNIX-Timestamp (Sekunden seit Beginn der UNIX-Epoche: 01.01.1970 00:00:00 UTC) in eine formatierte Angabe in der lokalen Zeitzone um.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$time</code>'''

''mandatory''
|| Zeitangabe wie sie von der <code>time()</code> Funktion zurückgegeben wird. 

Bsp: <code>1457201868</code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp </code>'''

|| Zeitstempel in lokaler Zeitzone im Format 
<code>2016-02-16 19:34:24</code>
|}

=== TimeNow ===
:<source lang="perl">$timestamp = TimeNow()</source>

Die Funktion TimeNow() gibt die aktuelle lokale Zeit als formatierte Zeichenkette zurück. Diese Funktion hat keine Übergabeparameter.

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp</code>'''

|| Zeitstempel der aktuellen Uhrzeit in lokaler Zeitzone im Format 
<code>2016-02-16 19:34:24</code> 

Benutzt die Funktion <code>FmtDateTime()</code>
|}

=== fhemTimeGm===
:<source lang="perl">$timestamp = fhemTimeGm($sec, $min, $hour, $mday, $month, $year)</source>
Wandelt einen Zeitpunkt als Greenwich Mean Time (GMT) basierend auf den einzelnen Datumsangaben, wie er bspw. durch die Perl-Funktion <code>gmtime()</code> erzeugt wird, in einen UNIX-Timestamp um.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$sec</code>'''

''mandatory''
|| Die Sekunden-Komponente als Ganzzahl zwischen 0 und 59.
|-
| style="vertical-align:top" | '''<code>$min</code>'''

''mandatory''
|| Die Minuten-Komponente als Ganzzahl zwischen 0 und 59.
|-
| style="vertical-align:top" | '''<code>$hour</code>'''

''mandatory''
|| Die Stunden-Komponente als Ganzzahl zwischen 0 und 23.
|-
| style="vertical-align:top" | '''<code>$mday</code>'''

''mandatory''
|| Die Tag-Komponente als Ganzzahl zwischen 1 und 31.
|-
| style="vertical-align:top" | '''<code>$month</code>'''

''mandatory''
|| Die Monats-Komponente als Ganzzahl zwischen 0 und 11. Hier erfolgt eine andere Zuordnung. Der Januar entspricht der 0, Februar der 1, usw. Der Dezember entspricht dem Wert 11.
|-
| style="vertical-align:top" | '''<code>$year</code>'''

''mandatory''
|| Die Jahres-Komponente. Das Jahr wird dabei als nicht als komplette Jahreszahl angegeben, sondern als Differenz seit dem Jahr 1900. Das Jahr 2016 entspricht demnach dem Wert 116.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp </code>'''

|| Zeitstempel als UNIX-Timestamp (Sekunden seit EPOCH-Beginn) 
Bsp: <code>1457201868</code>
|}

=== fhemTimeLocal===
:<source lang="perl">$timestamp = fhemTimeLocal($sec, $min, $hour, $mday, $month, $year)</source>
Wandelt einen Zeitpunkt in lokaler Zeit basierend auf den einzelnen Datumsangaben wie er bspw. durch die Perl-Funktion <code>localtime()</code> erzeugt wird in einen UNIX-Timestamp um.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$sec</code>'''

''mandatory''
|| Die Sekunden-Komponente als Ganzzahl zwischen 0 und 59.
|-
| style="vertical-align:top" | '''<code>$min</code>'''

''mandatory''
|| Die Minuten-Komponente als Ganzzahl zwischen 0 und 59.
|-
| style="vertical-align:top" | '''<code>$hour</code>'''

''mandatory''
|| Die Stunden-Komponente als Ganzzahl zwischen 0 und 23.
|-
| style="vertical-align:top" | '''<code>$mday</code>'''

''mandatory''
|| Die Tag-Komponente als Ganzzahl zwischen 1 und 31.
|-
| style="vertical-align:top" | '''<code>$month</code>'''

''mandatory''
|| Die Monats-Komponente als Ganzzahl zwischen 0 und 11. Hier erfolgt eine andere Zuordnung. Der Januar entspricht der 0, Februar der 1, usw. Der Dezember entspricht dem Wert 11.
|-
| style="vertical-align:top" | '''<code>$year</code>'''

''mandatory''
|| Die Jahres-Komponente. Das Jahr wird dabei als nicht als komplette Jahreszahl angegeben, sondern als Differenz seit dem Jahr 1900. Das Jahr 2016 entspricht demnach dem Wert 116.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp </code>'''

|| Zeitstempel als UNIX-Timestamp (Sekunden seit EPOCH-Beginn) 
Bsp: <code>1457201868</code>
|}

== Erzeugen von Readings / Events ==

=== readingsBeginUpdate ===

:<source lang="perl">
readingsBeginUpdate($hash)
</source>
Die Funktion readingsBeginUpdate() bereitet die Definition mit dem Hash <code>$hash</code> auf ein Update von Readings vor. Dies betrifft insbesondere das setzen von Umgebungsvariablen sowie dem aktuellen Zeitstempel als Änderungszeitpunkt. Der Aufruf dieser Funktion ist notwendig um eigentliche Updates mit der Funktion readingsBulkUpdate() auf der gewünschten Definition durchführen zu können.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>''' || Die Hash-Referenz der Definition wo Readings geupdatet werden sollen
|}

=== readingsBulkUpdate ===

<ul><source lang="perl">
$rv = readingsBulkUpdate($hash, $reading, $value);
$rv = readingsBulkUpdate($hash, $reading, $value, $changed);
</source></ul>
Die Funktion readingsBulkUpdate() führt ein Update eines einzelnen Readings für die Definition <code>$hash</code> durch. Dabei wird das Readings <code>$reading</code> auf den Wert <code>$value</code> gesetzt. Bevor diese Funktion benutzt werden kann, muss readingsBeginUpdate() zuvor aufgerufen werden, ansonsten werden keine Updates durchgeführt.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, wo Readings geupdatet werden sollen
|-
| style="vertical-align:top" | '''<code>$reading</code>'''

''mandatory''
|| Name des Readings, welches geupdatet werden soll
|-
| style="vertical-align:top" | '''<code>$value</code>'''

''mandatory''
|| Der Wert, welchen das Reading annehmen soll
|-
| style="vertical-align:top" | '''<code>$changed</code>'''

''optional''
|| Flag, ob ein Event für dieses Update erzeugt werden soll (Wert: <code>1</code>). Oder ob definitiv kein Event erzeugt werden soll (Wert: <code>0</code>). Wenn nicht gesetzt, wird aufgrund entsprechender Attribute in der Definition von <code>$hash</code> entschieden, ob ein Event zu erzeugen ist, oder nicht (Attribute: event-on-change-reading, event-on-update-reading, event-min-interval, ...)
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$rv</code>''' || Zeichenkette bestehend aus Reading und Wert getrennt durch einen Doppelpunkt, welcher anzeigt, auf welchen Wert das Reading tatsächlich gesetzt wurde.
|}

=== readingsEndUpdate ===

<ul><source lang="perl">
readingsEndUpdate($hash, $do_trigger);
</source></ul>
Die Funktion readingsEndUpdate() beendet den Bulk-Update Prozess durch die Funktionen readingsBeginUpdate() & readingsBulkUpdate() und triggert optional die entsprechenden Events sämtlicher erzeugter Readings für die Definition <code>$hash</code>. Desweiteren werden nachgelagerte Tasks wie bspw. die Erzeugung von User-Readings (Attribut: <code>userReadings</code>), sowie die Erzeugung des STATE aufgrund des Attributs <code>stateFormat</code> durchgeführt. Sofern <code>$do_trigger</code> gesetzt ist, werden alle anstehenden Events nach Abschluss getriggert.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, wo Readings geupdatet wurden.
|-
| style="vertical-align:top" | '''<code>$do_trigger</code>'''

''mandatory''
|| Flag, ob entsprechende Events der einzelnen Readings getriggert werden sollen (Wert: <code>1</code>). Wenn dieses Flag den Wert <code>0</code> oder <code>undef</code> besitzt, werden keine Events für alle Readings die seit dem Aufruf von readingsBeginUpdate() mittels readingsBulkUpdate() gesetzt wurden, erzeugt.
|}

=== readingsSingleUpdate ===

<ul><source lang="perl">
$rv = readingsSingleUpdate($hash, $reading, $value, $do_trigger);
</source></ul>
Die Funktion readingsSingleUpdate() führt ein einzelnes Reading-Update mithilfe der Funktionen readingsBeginUpdate(), readingsBulkUpdate() und readingsEndUpdate() durch. Es entspricht dabei einem Aufruf aller 3 Funktionen nacheinander mit den entsprechenden einzelnen Parametern in den jeweiligen Funktionen.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, wo das Reading geupdatet werden soll
|-
| style="vertical-align:top" | '''<code>$reading</code>'''

''mandatory''
|| Name des Readings, welches geupdatet werden soll
|-
| style="vertical-align:top" | '''<code>$value</code>'''

''mandatory''
|| Der Wert, welchen das Reading annehmen soll
|-
| style="vertical-align:top" | '''<code>$do_trigger</code>'''

''mandatory''
|| Flag, ob evtl. ein Event für das Reading getriggert werden soll (Wert: <code>1</code>, Event ist abhängig von den Attributen: event-on-change-reading, event-on-update-reading, event-min-interval, ...). Wenn dieses Flag den Wert <code>0</code> oder <code>undef</code> besitzt, wird kein Event erzeugt.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$rv</code>''' || Zeichenkette bestehend aus Reading und Wert getrennt durch einen Doppelpunkt, welcher anzeigt, auf welchen Wert das Reading tatsächlich gesetzt wurde.
|}

=== DoTrigger ===

<ul><source lang="perl">
$ret = DoTrigger($name, $new_state);
$ret = DoTrigger($name, $new_state, $no_replace);
</source></ul>
Die Funktion DoTrigger() triggert alle angesammelten Events in <code>$hash->{CHANGED}</code> sowie zusätzlich das Event <code>$new_state</code> für die Definition <code>$name</code> und führt alle verarbeitenden Aktionen in allen Empfängern zu diesem Event aus. Wenn in <code>$hash->{CHANGED}</code> keine zu bearbeitenden Änderungen enthalten sind, wird lediglich <code>$new_state</code> getriggert (sofern gesetzt).

Diese Funktion wird implizit in der Funktion readingsEndUpdate() aufgerufen und muss daher nicht nochmal aufgerufen werden.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Name der Definition deren Events durchgeführt werden sollen.
|-
| style="vertical-align:top" | '''<code>$new_state</code>'''

''mandatory''
|| Das Event welches zusätzlich zu bereits anstehenden Events aus <code>$hash->{CHANGED}</code> getriggert werden soll. Wenn dieser Wert <code>undef</code> ist, werden nur alle Events aus <code>$hash->{CHANGED}</code> bearbeitet, sofern <code>$hash->{CHANGED}</code> gefüllt ist.
|-
| style="vertical-align:top" | '''<code>$no_replace</code>'''

''optional''
|| Optionales Flag, welches die Ersetzung von Events durch das Attribut <code>eventMap</code> verhindert (Wert: <code>1</code>).

|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$ret</code>''' || Zeichenkette welche alle Return-Werte aller aufgerufenen Notify-Funktionen beinhaltet, sofern diese einen Fehler melden. Diese Meldung wird parallel im FHEM-Logfile ausgegeben.
|}

== Timer ==

=== InternalTimer===

<ul><syntaxhighlight lang="perl">InternalTimer($timestamp, $functionName, $args);
InternalTimer($timestamp, $functionName, $args, $waitIfInitNotDone)
</syntaxhighlight></ul>
Die Funktion InternalTimer() ermöglicht das verzögerte Ausführen von einer bestimmten Funktion zu einem späteren Zeitpunkt. Die übergebene Funktion <code>$functionName</code> wird dabei zum Zeitpunkt <code>$timestamp</code> mit dem Parameter <code>$arg</code> ausgeführt.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp</code>'''

''mandatory''
|| Angabe eines UNIX-Timestamp, wann der Timer ausgeführt werden soll (bspw: <code>gettimeofday() + 30</code> um in 30 Sekunden etwas zu starten)
|-
| '''<code>$functionName</code>'''

''mandatory''
|| Der Name der Funktion welche ausgeführt werden soll zum angegebenen Zeitpunkt (bspw: "MODULNAME_GetStatus")
|-
| '''<code>$arg</code>'''

''mandatory''
|| Der Übergabeparameter welchen die genannte Funktion zum Ausführungszeitpunkt erhalten soll. Typischerweise ist das meistens $hash.
|-
| '''<code>$waitIfInitNotDone</code>'''

''optional''
|| VORSICHT! NUR BENUTZEN WENN MAN ES WIRKLICH BENÖTIGT. Wenn dieser Wert auf <code>1</code> ist und die Funktion ausgeführt wird, während FHEM startet ($init_done == 0), dann wird InternalTimer direkt solange warten bis der angegebene Zeitpunkt erreicht ist, UND DIE FUNKION DIREKT AUSFÜHREN. Das bedeutet, dass InternalTimer() dann solange läuft, bis der Zeitpunkt erreicht ist und die angegebene Funktion ausgeführt wurde.

Standardwert: 0
|}

=== RemoveInternalTimer ===
<ul><source lang="perl">RemoveInternalTimer($arg);
RemoveInternalTimer($arg, $function);
</source>
</ul>
Die Funktion RemoveInternalTimer löscht möglicherweise noch anstehende Timer welche mit dem Übergabeparameter <code>$arg</code> gescheduled sind. Optional kann man zusätzlich die Suche auf eine bestimmte Funktion <code>$function</code> weiter einschränken.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$arg</code>'''

''mandatory''
|| Der Übergabeparameter nach wem gesucht wird. Alle Timer die mit diesem Übergabeparameter noch anstehen, werden dabei gelöscht.
|-
| style="vertical-align:top" | '''<code>$function</code>'''

''optional''
|| Der Funktionsname der zusätzlich zu <code>$arg</code> gesucht werden soll.

|}

== Definitionen suchen ==

=== devspec2array ===

<ul><syntaxhighlight lang="perl">
@list = devspec2array($devspec);
@list = devspec2array($devspec, $client_hash)
</syntaxhighlight>
</ul>
Die Funktion devspec2array() gibt eine Array mit Definitionsnamen zurück die auf die übergebene Device-Specification <code>$devspec</code> matchen.

Sollte keine Definition auf die übergebene Spezifikation passen, so wird <code>$devspec</code> als einziges zurückgegeben. Dieser Mechanismus ist aus historischen Gründen so gewählt um die Funktion devspec2array() transparent in Module einzufügen ohne große Änderungen im Code durchführen zu müssen. Daher ist es notwendig im Falle der Rückgabe eines einzelnen Elements dies nochmals auf Existenz in <code>%defs</code> zu prüfen.

Die genaue Syntax einer Device-Specification ist in der [http://fhem.de/commandref.html#devspec commandref] erläutert. Die Funktion devspec2array() setzt diese Syntax um und gibt die gefundenen Definitions-Namen zurück.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$devspec</code>'''

''mandatory''
|| Die Device-Specification zum suchen nach Definitions-Namen.
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''optional''
|| Der Definitions-Hash der für den Aufruf verantwortlich ist. Dies dient zur Prüfung, ob diese Definition diesen Vorgang ausführen darf (Vorgangs-Typ: <code>devicename</code>).
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>@list</code>''' || Array mit einer Liste aller Definitions-Namen die zu der übergebenen Device-Specification passen. Sofern keine Definition auf die Spezifikation passt wird <code>$devspec</code> unverändert zurückgegeben. Wenn <code>$client_hash</code> gesetzt ist und die Definition diesen Vorgang nicht ausführen darf, wird <code>""</code> (Leerstring) zurückgegeben.
|}

== Daten abfragen/auslesen ==

=== ReadingsVal ===

:<source lang="perl">
$value = ReadingsVal($name, $reading, $default)
</source>
Die Funktion ReadingsVal() gibt den inhaltlichen Wert des Readings <code>$reading</code> der Definition <code>$name</code> zurück. Sollte das gewünschte Reading nicht existieren, wird <code>$default</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Namen aus dem das gewünschte Reading ausgelesen werden soll.
|-
| '''<code>$reading</code>'''

''mandatory''
|| Der Name des Readings welcher ausgelesen werden soll.
|-
| '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Reading nicht existiert.
|-
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Inhalt des gewünschten Readings oder <code>$default</code>, wenn es nicht existiert.
|}

=== ReadingsTimestamp===

:<source lang="perl">
$timestamp = ReadingsTimestamp($name, $reading, $default)
</source>
Die Funktion ReadingsTimestamp() gibt den Zeitstempel des Readings <code>$reading</code> der Definition <code>$name</code> zurück. Es handelt sich hierbei um den Zeitpunkt an dem das Reading zuletzt gesetzt/aktualisiert wurde. Sollte das gewünschte Reading nicht existieren, wird <code>$default</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Namen aus dem der Zeitstempel für das gewünschte Reading ausgelesen werden soll.
|-
| '''<code>$reading</code>'''

''mandatory''
|| Der Name des Readings für welches der Zeitstempel ausgelesen werden soll.
|-
| '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Reading nicht existiert.
|-
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp</code>''' || Zeitstempel des gewünschten Readings in lokaler Zeitzone im Format
<code>2016-02-16 19:34:24</code>
|}

=== ReadingsAge===

:<source lang="perl">
$seconds = ReadingsAge($name, $reading, $default)
</source>
Die Funktion ReadingsAge() gibt die Dauer in Sekunden seit der letzten Aktualisierung des Readings <code>$reading</code> der Definition <code>$name</code> zurück. Es handelt sich hierbei um den Zeitpunkt an dem das Reading zuletzt gesetzt/aktualisiert wurde. Sollte das gewünschte Reading nicht existieren, wird <code>$default</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Namen aus dem die Dauer der letzten Aktualisierung für das gewünschte Reading ausgelesen werden soll.
|-
| '''<code>$reading</code>'''

''mandatory''
|| Der Name des Readings für welches die Dauer der letzten Aktualisierung ausgelesen werden soll.
|-
| '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Reading nicht existiert.
|-
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$seconds</code>''' || Die Sekunden als Ganzzahl, welche seit der letzten Aktualisierung vergangen sind
|}

=== ReadingsNum ===

:<source lang="perl">
$number = ReadingsNum($name, $reading, $default)
</source>
Die Funktion ReadingsNum() extrahiert einen numerischen Wert aus dem Reading <code>$reading</code> der Definition <code>$name</code> und gibt diesen zurück. Dabei werden Zeichenketten wie z.B. Einheiten eliminiert und nur die eigentliche Zahl (Ganzzahl- oder Fließkommazahl) zurückgegeben. Sollte das gewünschte Reading nicht existieren, wird <code>$default</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Namen aus dem ein numerischer Wert für das gewünschte Reading ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$reading</code>'''

''mandatory''
|| Der Name des Readings aus dem ein numerischer Wert ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Reading nicht existiert.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$number</code>''' || Numerischer Wert des gewünschten Readings oder <code>$default</code>, wenn es nicht existiert.
|}

=== AttrVal ===

:<source lang="perl">
$value = AttrVal($name, $attribute, $default)
</source>
Die Funktion AttrVal() gibt den aktuell konfigurierten Inhalt des Attribut <code>$attribute</code> der Definition <code>$name</code> zurück. Sollte das gewünschte Attribut nicht existieren bzw. nicht gesetzt sein, wird <code>$default</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Namen aus dem das gewünschte Attribut ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$attribute</code>'''

''mandatory''
|| Der Name des Attributs, dessen Wert ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Attribut nicht existiert.
|-
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Inhalt des gewünschten Attributs oder <code>$default</code>, wenn es nicht existiert.
|}

=== InternalVal ===

:<source lang="perl">
$value = InternalVal($name, $internal, $default)
</source>
Die Funktion InternalVal() gibt den aktuellen Inhalt eines Internals <code>$internal</code> der Definition <code>$name</code> zurück. Sollte das gewünschte Internal nicht existieren bzw. nicht gesetzt sein, wird <code>$default</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Namen aus dem das gewünschte Internal ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$internal</code>'''

''mandatory''
|| Der Name des Internals, dessen Wert ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Internal nicht existiert.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Inhalt des gewünschten Internal oder <code>$default</code>, wenn es nicht existiert.
|}

=== Value===

:<source lang="perl">
$value = Value($name)
</source>
Die Funktion Value() gibt den aktuellen Status Definition <code>$name</code> zurück. Sollte die gewünschte Definition nicht existieren bzw. nicht gesetzt sein, wird <code>""</code> (Leerstring) zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Namen aus dem der Status ausgelesen werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Status der gewünschten Definition
|}

=== OldValue===

:<source lang="perl">
$value = OldValue($name)
</source>
Die Funktion OldValue() gibt den Status der Definition <code>$name</code> zurück BEVOR der aktuelle Status aufgrund eines Events gesetzt wurde. Sollte die gewünschte Definition nicht existieren bzw. nicht gesetzt sein, wird <code>""</code> (Leerstring) zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Namen aus dem der Status ausgelesen werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || vorherige Status der gewünschten Definition
|}

=== OldTimestamp===

:<source lang="perl">
$timestamp = OldTimestamp($name)
</source>
Die Funktion OldTimestamp() gibt den Zeitpunkt der letzten Statusänderung der Definition <code>$name</code> als Zeichenkette zurück. Sollte die gewünschte Definition nicht existieren bzw. nicht gesetzt sein, wird <code>""</code> (Leerstring) zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Namen aus dem der Status ausgelesen werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp</code>''' || Zeitstempel in lokaler Zeitzone im Format
<code>2016-02-16 19:34:24</code>
|}

== Attribute in anderen Definitionen bereitstellen ==

=== addToAttrList===
:<source lang="perl">
addToAttrList($attrib)
</source>
Die Funktion addToAttrList() fügt das Attribut mit dem Namen <code>$attrib</code> zu dem Attribut <code>userattr</code> der Definition <code>global</code> hinzu. Damit kann dieses Attribut in allen systemweiten Definitionen verwendet und gesetzt werden.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$attrib</code>'''

''mandatory''
|| Der Name des Attributs, welches für alle Definitionen verfügbar gemacht werden soll.
|}

=== addToDevAttrList ===

:<source lang="perl">
addToDevAttrList($name, $attrib)
</source>
Die Funktion addToDevAttrList() fügt das Attribut mit dem Namen <code>$attrib</code> zu dem Attribut <code>userattr</code> der Definition <code>$name</code> hinzu. Damit kann dieses Attribut in der Definition <code>$name</code> verwendet und gesetzt werden.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Name der Definition, für welche das Attribut verfügbar gemacht werden soll.
|-
| style="vertical-align:top" | '''<code>$attrib</code>'''

''mandatory''
|| Der Name des Attributs, welches für die Definition <code>$name</code> verfügbar gemacht werden soll.
|}

== Daten dauerhaft schreiben/lesen ==

=== FileRead ===

<ul><syntaxhighlight lang="perl">
($error, @content) = FileRead($filename);
($error, @content) = FileRead($param)
</syntaxhighlight>
</ul>
Die Funktion FileRead() liest den Inhalt der Datei <code>$filename</code> ein und gibt diesen als ein zeilenweises Array zurück. In Verwendung mit configDB wird die Datei standardmäßig aus der Datenbank gelesen. Um im Falle von configDB dennoch auf das Dateisystem zugreifen zu können muss als Übergabeparameter ein Hash <code>$param</code> gesetzt werden in dem ein spezieller Wert den Zugriff auf das Dateisystem forciert.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$filename</code>'''

''mandatory''
|| Der Dateisystempfad der Datei die eingelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$param</code>'''

''mandatory''
|| Um im Falle der Nutzung von configDB den Zugriff auf das lokale Dateisystem zu erzwingen muss ein Parameter-Hash wiefolgt übergeben werden:
<code>{ FileName => $filename, ForceType => "file" }</code>

Die Variable <code>$filename</code> enthält dabei den lokalen Dateisystempfad zu der gewünschten Datei.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>''' || Im Falle eines Fehlers beim Lesen der Datei ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Lesevorgang erfolgreich enthält <code>$error</code> den Wert <code>undef</code> oder <code>""</code> (Leerstring).
|-
| style="vertical-align:top" | '''<code>@content</code>''' || Der Inhalt der gewünschten Datei als zeilenweises Array. Im Falle eines Fehlers beim Lesen trägt dieses Array den Wert <code>undef</code>
|}

=== FileWrite ===

<ul><syntaxhighlight lang="perl">
$error = FileWrite($filename, @content);
$error = FileWrite($param, @content)
</syntaxhighlight></ul>
Die Funktion FileWrite() schreibt den übergebenen Inhalt <code>@content</code> in die Datei <code>$filename</code>. In Verwendung mit configDB wird die Datei standardmäßig in die Datenbank geschrieben. Um im Falle von configDB dennoch auf das Dateisystem zugreifen zu können muss als Übergabeparameter ein Hash <code>$param</code> gesetzt werden in dem ein spezieller Wert den Zugriff auf das Dateisystem forciert.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$filename</code>'''

''mandatory''
|| Der Dateisystempfad der Datei in welche der Inhalt geschrieben werden soll.
|-
| style="vertical-align:top" | '''<code>$param</code>'''

''mandatory''
|| Um im Falle der Nutzung von configDB den Zugriff auf das lokale Dateisystem zu erzwingen muss ein Parameter-Hash wiefolgt übergeben werden:
<code>{ FileName => $filename, ForceType => "file", NoNL => 0 }</code>

Die Variable <code>$filename</code> enthält dabei den lokalen Dateisystempfad der zu schreibenden Datei. Optional kann man den Wert <code>NoNL</code> auf 1 setzen um kein Newline (<code>\n</code>) als Trennzeichen zwischen den einzelnen Zeilen zu erzeugen.
|-
| style="vertical-align:top" | '''<code>@content</code>'''

''mandatory''
|| Die zu schreibenden Daten als ein Array von Zeilen (ohne Newline am Ende jeder Zeile).
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>''' || Im Falle eines Fehlers beim Schreiben der Datei ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Schreibvorgang erfolgreich enthält <code>$error</code> den Wert <code>undef</code>
|}

=== setKeyValue ===

:<syntaxhighlight lang="perl">$error = setKeyValue($key, $value)</syntaxhighlight>
Die Funktion setKeyValue() speichert die Daten <code>$value</code> unter dem Schlüssel <code>$key</code> ab. Die Daten werden in einer Datei auf dem Dateisystem (oder configDB) gespeichert und sind somit persistent auch nach einen Neustart von FHEM verfügbar. Die Daten welche in <code>$value</code> enthalten sind, dürfen dabei keine Zeilenumbrüche enthalten. Sollten Daten mit Zeilenumbrüchen auf diese Weise gespeichert werden, so müssen Zeilenumbrüche durch entsprechende Mechanismen (z.B. Base64 oder das Ersetzen durch alternative Trennzeichen) eliminiert werden.

'''ACHTUNG:''' Die Daten werden im Klartext in einer Datei auf dem Dateisystem abgelegt! Sensible Daten die mit setKeyValue gespeichert werden (z.B. Passwörter, Zugangsdaten, etc.) sollten durch entsprechende Mechanismen (z.B. Verschlüsselung) unleserlich gemacht werden.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$key</code>'''

''mandatory''
|| Der eindeutige Schlüssel als Zeichenkette unter dem die Daten abgespeichert werden soll (bspw. Definitions-Namen). Der Schlüssel darf dabei keine Zeilenumbrüche enthalten.
|-
| style="vertical-align:top" | '''<code>$value</code>'''

''mandatory can be <code>undef</code>''
|| Die zu speichernden Daten als Zeichenkette ohne Zeilenumbruch. Die Daten dürfen dabei keine Zeilenumbrüche enthalten.

Wenn <code>$value</code> den Wert <code>undef</code> besitzt, werden zuvor gespeicherte Daten gelöscht.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>''' || Im Falle eines Fehlers beim Schreiben der Daten ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Schreibvorgang erfolgreich enthält <code>$error</code> den Wert <code>undef</code>
|}

=== getKeyValue ===

:<syntaxhighlight lang="perl">($error, $value) = getKeyValue($key)</syntaxhighlight>
Die Funktion getKeyValue() gibt Daten, welche zuvor per <code>setKeyValue()</code> gespeichert wurden, zurück.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$key</code>'''

''mandatory''
|| Der eindeutige Schlüssel als Zeichenkette unter dem die Daten gespeichert wurden.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>''' || Im Falle eines Fehlers beim Lesen der Daten ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Lesevorgang erfolgreich enthält <code>$error</code> den Wert <code>undef</code>
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Die Daten, welche unter dem gegebenen Schlüssel <code>$key</code> hinterlegt sind. Wenn keine Daten zu dem Schlüssel existieren, besitzt <code>$value</code> den Wert <code>undef</code>
|}

== Logging ==

=== Log ===

<source lang="perl">
Log($verbose, $message)
</source>
Die Funktion Log() schreibt die Meldung <code>$message</code> in das FHEM-Logfile, sofern <code>$verbose</code> kleiner gleich dem globalen Attribut <code>verbose</code> ist. Wenn <code>$verbose</code> größer ist, als das globale Attribut <code>verbose</code>, wird die Meldung nicht geloggt.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$verbose</code>'''

''mandatory''
|| Der Verbose-Level unter dem die Nachricht <code>$message</code> geloggt werden soll.

Ganzzahl zwischen 0 und 5
|-
| style="vertical-align:top" | '''<code>$message</code>'''

''mandatory''
|| Die Log-Meldung als Zeichenkette, welche in das FHEM-Logfile geloggt werden soll.
|}

=== Log3 ===

<source lang="perl">
Log3($name, $verbose, $message)
</source>
Die Funktion Log3() schreibt die Meldung <code>$message</code> in das FHEM-Logfile, sofern <code>$verbose</code> kleiner gleich dem Attribut <code>verbose</code> der Definition <code>$name</code> ist. Wenn das Attribut <code>verbose</code> in der Definition <code>$name</code> nicht gesetzt ist, wird gegen das globale Attribut <code>verbose</code> geprüft.

Diese Funktion ist primär für die Log-Ausgabe in Modulen gedacht um so dem User die Möglichkeit zu geben nur für bestimmte Definitionen den Verbose-Level zu erhöhen ohne den globalen Verbose-Level zu erhöhen.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory can be <code>undef</code>''
|| Der Name der Definition wogegen geprüft werden soll. Wenn <code>$name</code> in FHEM nicht existiert, oder den Wert <code>undef</code> besitzt, wird der Parameter <code>$verbose</code> gegen das globale Attribut <code>verbose</code> geprüft.
|-
| style="vertical-align:top" | '''<code>$verbose</code>'''

''mandatory''
|| Der Verbose-Level unter dem die Nachricht <code>$message</code> geloggt werden soll.

Ganzzahl zwischen 0 und 5
|-
| style="vertical-align:top" | '''<code>$message</code>'''

''mandatory''
|| Die Log-Meldung als Zeichenkette, welche in das FHEM-Logfile geloggt werden soll.
|}

=== Debug ===

<source lang="perl">
Debug($message)
</source>
Die Funktion Debug() schreibt die Meldung <code>$message</code> mit dem Präfix <code>DEBUG></code> in das FHEM-Logfile. Diese Funktion ist zum temporären debuggen gedacht und sollte nicht fest in einem Modul verwendet werden. Sie entspricht dem Aufruf:
<source lang="perl">
Log(1, "DEBUG>".$message);
</source>

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$message</code>'''

''mandatory''
|| Die Debug-Meldung als Zeichenkette, welche in das FHEM-Logfile geloggt werden soll.
|}

== Status-Abfragen ==

=== IsDisabled ===

:<syntaxhighlight lang="perl">
$status = IsDisabled($name)
</syntaxhighlight>
Die Funktion IsDisabled() prüft, ob die Definition <code>$name</code> aktuell deaktiviert (Attribute: disabled/disabledForIntervals) oder durch den Nutzer inaktiv geschaltet wurde (STATE: <code>inactive</code>). Je nachdem ob die Definition deaktiviert/inaktiv ist, gibt sie einen entsprechenden Wert größer <code>0</code> zurück. Wenn die Definition aktiv ist, gibt die Funktion den Wert <code>0</code> zurück.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob eine Definition aktiv/inaktiv ist.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name welcher geprüft werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Der Status der Definition. Je nach Status sind folgende Werte möglich:

0 - Definition ist aktiv 
1 - Definition ist durch das Attribut <code>disable</code> deaktiviert 
2 - Definition ist durch das Attribut <code>disabledForIntervals</code> deaktiviert 
3 - Definition ist durch den User inaktiv geschaltet. Dies bedeutet <code>$hash->{STATE}</code> der Definition besitzt den Wert <code>inactive</code>.
|}

=== IsDummy ===

:<syntaxhighlight lang="perl">
$status = IsDummy($name)
</syntaxhighlight>
Die Funktion IsDummy() prüft, ob die Definition <code>$name</code> in den Dummy-Modus versetzt wurde (Attribut: <code>dummy</code>). Wenn die Definition in den Dummy-Modus gesetzt ist, gibt IsDummy() den Wert <code>1</code> zurück, andernfalls <code>0</code>.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob eine Definition im Dummy-Modus ist.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name welcher geprüft werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Der Status der Definition. Je nach Status sind folgende Werte möglich:

0 - Definition ist aktiv 
1 - Definition ist im Dummy-Modus 
|}

=== IsIgnored ===

:<syntaxhighlight lang="perl">
$status = IsIgnored($name)
</syntaxhighlight>
Die Funktion IsIgnored() prüft, ob die Definition <code>$name</code> durch den User ignoriert wird (Attribut: <code>ignore</code>). Wenn die Definition durch den User ignoriert wird, gibt IsIgnored() den Wert <code>1</code> zurück, andernfalls <code>0</code>.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob eine Definition ignoriert wird.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name welcher geprüft werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Der Status der Definition. Je nach Status sind folgende Werte möglich:

0 - Definition ist aktiv 
1 - Definition wird ignoriert 
|}

=== IsIoDummy ===

:<syntaxhighlight lang="perl">
$status = IsIoDummy($name)
</syntaxhighlight>
Die Funktion IsIoDummy() prüft, ob das zugeordnete IO-Device der Definition <code>$name</code> in den Dummy-Modus versetzt wurde (Attribut: <code>dummy</code>). Wenn das IO-Device in den Dummy-Modus gesetzt ist, gibt IsIoDummy() den Wert <code>1</code> zurück, andernfalls <code>0</code>.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob ein IO-Device einer Definition im Dummy-Modus ist.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name dessen IO-Device geprüft werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Der Status des IO-Devices der Definition. Je nach Status sind folgende Werte möglich:

0 - IO-Device der Definition ist aktiv 
1 - IO-Device der Definition ist im Dummy-Modus 
|}

== Sonstiges ==

=== configDBUsed ===

:<source lang="perl">
$status = configDBUsed()
</source>
Die Funktion configDBUsed() prüft, ob in der aktuellen FHEM-Umgebung configDB verwendet wird und gibt in diesem Fall den Wert <code>1</code> zurück. Die Funktion besitzt keinerlei Übergabeparameter.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob configDB verwendet wird.

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Folgende Werte sind möglich: 

0 - configDB wird nicht verwendet 
1 - configDB wird verwendet
|}

=== getUniqueId ===

:<source lang="perl">
$uniqueID = getUniqueId()
</source>
Die Funktion getUniqueId() gibt einen eindeutige Identifikations-String der lokalen FHEM-Installation zurück. Dieser String wird einmalig per Zufallsalgorithmus erzeugt und anschließend lokal abgespeichert. Jede FHEM-Installation besitzt einen anderen Identifikations-String. Dieser Wert wird bspw. für die Online-Statistik verwendet um die einzelnen Installation zu anonymisieren.

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$uniqueID</code>''' || Eine Zeichenkette in Hexadezimaldarstellung welche pro Installation eindeutig ist.
|}

[[Kategorie:Development]]

Benutzer:Viegener

2016-04-03T12:22:25Z

Viegener: Aktualisiert : Projekte / Links

; Erstmal nur ein Überblick über meine FHEM-Beteiligung

== FHEM Benutzung ==

Wunsch war die Zusammenführung der verschiedenen Funksysteme in einem zentralen System.
Ausdrücklich mit den Zielen
* Übergreifende Steuerungen und Makros zu ermöglichen
* Zentrale Bedienungsterminals (tablet)
* Steuerung von Aussen
* Am wichtigsten natürlich Spass am Basteln und Programmieren!!!

 
;Komponenten
* Somfy RTS Rolläden (Aktoren und Handfernbedienungen)
* FS20 Steckdosen
* Thermo/Hygro-Sensoren von LaCrosse und Technoline
* Mehrere Sonos-Komponenten
* Fritzbox
* Neu: Homematic
* Loewe Fernseher (dafür gibt es noch nichts)

 
;Mein FHEM habe ich im Februar 2015 installiert.
* 03/2015 Umzug Raspberry Pi2
* 04/2015 Somfy-Einbindung
* 05/2015 FHEM Tablet UI
* 06/2015 Entwicklung eines Telegram Moduls für Benachrichtigungen und Kommandos (also bidirektional)
** Telegram ist frei, plattformübergreifend und erlaubt Gruppenchats
* 09/2015 Variante der Telegram-Anbindung mit dem TelegramBot-Modul 50_TelegramBot
* 11/2015 TelegramBot offizielles FHEM-Modul (erhältlich über update)

== FHEM Development ==

Aber klar, das macht ja den Spass aus. Gerne in C, C++, Perl, Java, Javascript und vielen anderen, die heute nicht mehr relevant sind
Wenns sein muss auch in CSS, HTML etc

* [https://github.com/viegener/Telegram-fhem/blob/master/70_Telegram.pm 70_Telegram.pm]
* [https://github.com/viegener/Telegram-fhem/blob/master/50_TelegramBot.pm 50_TelegramBot.pm]
* Beiträge zu Somfy
** Somfy in FHEMDuino (Perl und C)
** 10_Somfy_PM - Umbau positionsbehandlung
* Beiträge zu FHEM Tablet UI

== FHEMWiki ==

;Bisher nur wenig

* [[TelegramBot]]
* [[Telegram]]
* [[DevelopmentModuleAPI]]

 
 

== Projekte und Ideen ==

* Nextion-Display als kleines touchdisplay zum Einbau in kleine Gehäuse/Kästen
** Begonnen [https://forum.fhem.de/index.php/topic,51267.0.html]
** Esp8266 mit Nextion-Display verbunden und mit FHEM gekoppelt
** Erstes modul erstellt
** Erweiterungen in Progress / Tutorial und Mitstreiter benötigt

* Klingeltaster-Modul mit RGB-LEDs und Arduino+Funk
** Immer noch eine Baustelle, RGB geht, FHEM-Anbindung über Asksin Homematic

* grösseres (10 Zoll ?) Tablet als zentrale Bedienungskonsole
** Jetzt realisiert über Acer Iconia 10 - funktioniert recht gut und für den Preis ein gutes Angebot

* Infrarot-Modul als Homematic Aktor (Selbstbau Arduino Nano / Funkmodul-RFM12B? / IR-LEDs
** Läuft nun als CUL mit WLAN-Interface (ESP8266)
** [https://forum.fhem.de/index.php/topic,49689.0.html]

TelegramBot

2016-03-27T14:38:18Z

Viegener: Empfang von Bildern / Aktuelle FHEM version benötigt

DevelopmentModuleIntro

2016-02-28T22:16:03Z

Viegener: Erklärung zur Normalisierung/Korrektur von Attributwerten in X_Attr

== Einleitung ==
Dieser Text ist in Arbeit und muss noch an einigen Stellen ergänzt werden.
Insbesondere beschreibt der Text derzeit nur einstufige Module. Die Abgrenzung zu zweistufigen Modulen und deren Eigenschaften sollte noch ergänzt werden.

Um neue Geräte in FHEM verfügbar zu machen, kann man ein eigenes Modul in Perl schreiben, das automatisch von FHEM geladen wird, wenn ein passendes Gerät in FHEM definiert wird. Das Modul definiert dann wie mit dem Gerät kommuniziert wird, stellt Werte ("Readings") innerhalb von FHEM zur Verfügung oder erlaubt es das Gerät mit "Set"-Befehlen zu beeinflussen. Dieser Text soll den Einstieg in die Entwicklung eigener Module erleichtern.

Mit dem FHEM-Befehl "define", der typischerweise in die zentrale Konfigurationsdatei fhem.cfg eingetragen wird, werden Geräte in FHEM definiert. Der Befehl sorgt dafür dass ein neues Modul bei Bedarf geladen wird und die Initialisierungsfunktion des Moduls aufgerufen wird.

Damit das funktioniert müssen der Name des Geräts, der Name des Moduls und der Name der Initialisierungsfunktion zueinander passen. Das folgende Beispiel soll dies verdeutlichen:

Ein Jeelink USB-Stick in einer Fritz-Box könnte beispielsweise mit dem Befehl <code>define JeeLink1 JeeLink /dev/ttyUSB0@57600</code> definiert werden.

In der fhem.pl wird der define-Befehl verarbeitet, geprüft, ob ein Modul mit Namen JeeLink schon geladen ist und falls nicht ein Modul mit Namen XY_JeeLink.pm im Modulverzeichnis (bei einer FritzBox z.B. /var/media/ftp/fhem/FHEM) gesucht und dann geladen.
Danach wird die Funktion JeeLink_Initialize aufgerufen.
Die Moduldatei muss also nach dem Namen des Geräts benannt werden und eine Funktion mit dem Namen des Geräts und einer _initialize Funktion enthalten.
In der Initialisierungsfunktion des Moduls werden dann die Namen der aller weiteren Funktionen des Moduls, die von fhem.pl aus aufgerufen werden, bekannt gemacht. Dazu wird der Hash - das ist die zentrale Datenstruktur für jede Instanz eines Gerätes - mit entsprechenden Werten gefüllt.

== Der Hash einer Geräteinstanz ==
Eine Besonderheit in Perl sind [http://de.wikipedia.org/wiki/Assoziatives_Array#Perl assoziative Arrays], (nicht ganz richtig als "Hash" bezeichnet) in denen die Adressierung nicht über eine Zählvariable erfolgt, sondern über einen beliebigen String. Die internen Abläufe bei der Adressierung führen dazu, dass die Speicherung in und der Abruf aus Hashes relativ langsam ist.

Der zentrale Speicherort für Informationen einer Geräteinstanz bei FHEM ist ein solcher Hash, der seinerseits in fhem.pl von einem globalen Hash referenziert wird.

<code>$defs{''Devicename''}</code> in fhem.pl verweist auf den Hash der Geräteinstanz. Diesen Verweis (also nur die Adresse) bekommen die Funktionen eines Moduls übergeben, das direkt von fhem.pl aufgerufen wird. In dem Hash stehen beispielsweise die internen Werte des Geräts, die im GUI als "Internals" angezeigt werden oder die Readings des Geräts. Beispiele:
*<code>$hash{NAME}</code> enthält den Namen der Geräteinstanz,
*<code>$hash{TYPE}</code> enthält die Typbezeichnung des Geräts
*<code>$hash->{INTERVAL}</code> enthält ein Abfrageintervall

==Ausführung von Modulen==
FHEM führt Module normalerweise nicht parallel aus. Daher wäre es ungünstig wenn Module Werte von einem Gerät abfragen und dann auf die Antwort des Geräts warten. In dieser Zeit wäre der Rest von FHEM blockiert. Die Ein- und Ausgabe sollte ohne Blockieren erfolgen und die Verarbeitung mehrerer Ein- und Ausgabekanäle quasi parallel ermöglichen.

Dafür werden in FHEM zwei zentrale Listen gepflegt, in der die Filedeskriptoren der geöffneten Kommunikatonsverbindungen gespeichert sein können. Auf Linux- bzw. Unix-basierten Plattformen wird der select-Befehl des Betriebssystems verwendet und entsprechend gibt es in FHEM eine selectlist, in der die Filedeskriptoren der Geräedateien (z.B. /dev/ttyUSBx etc.) gespeichert sind.

In der zentralen Schleife von fhem.pl wird mit select überwacht, ob über eine der geöffneten Schnittstellen Daten zum Lesen anstehen. Wenn dies der Fall ist, dann wird die Lesefunktion (X_Read) des zuständigen Moduls aufgerufen, damit es die Daten entgegennimmt und die Schleife wird weiter ausgeführt.

Auf Windows-Systemen funktioniert dies anders. Hier können USB/Seriell-Geräte nicht per select überwacht werden. In FHEM unter Windows werden daher diese Schnittstellen kontinuierlich abgefragt ob Daten bereitstehen. Dafür müssen Module zusätzlich zur Lesefunktion eine Abfragefunktion (X_Ready) implementieren, die prüft ob Daten zum Lesen anstehen. Auch auf Linux/Unix-Plattformen hat diese Funktion eine Aufgabe. Falls nämlich eine Schnittstelle ausfällt beziehungsweise ein CUL oder USB-zu-Seriell Adapter ausgesteckt wird, dann wird über diese Funktion regelmäßig geprüft ob die Schnittstelle wieder verfügbar wird.

Innerhalb der eigentlichen Lesefunktion (X_Read) werden dann die Daten vom zugehörigen Gerät gelesen, das nötige Protokoll implementiert und Werte in Readings geschrieben.

== Readings ==
Werte, die von einem Gerät gelesen werden und in FHEM zur Verfügung stehen werden Readings genannt. Sie werden als Unterstruktur des Hashes der jeweiligen Geräteinstanz gespeichert, beispielsweise
*<code>$hash{READINGS}{Temp}{VAL}</code> für die Temperatur eines Fühlers
*<code>$hash{READINGS}{Temp}{TIME}</code> für den Zeitstempel der Messung

Für den lesenden Zugriff auf Readings steht die Funktion ReadingsVal($$$) zur Verfügung.

Readings werden im statefile von FHEM automatisch zwischengespeichert, damit sie nach einem Neustart sofort wieder zur Verfügung stehen, auch bevor sie vom Modul neu gesetzt oder aktualisiert werden.

Readings, die mit einem Punkt im Namen beginnen, haben eine funktionale Besonderheit. Sie werden im FhemWeb nicht angezeigt und können somit als "Permanentspeicher" innerhalb des Moduls genutzt werden.

Zum Setzen von Readings sollen
*bei Gruppen von Readings der Funktionsblock <code>readingsBeginUpdate</code>, <code>readingsBulkUpdate</code> (mehrfach wiederholt), <code>readingsEndUpdate</code>
*bei einzelnen Updates die Funktion <code>readingsSingleUpdate</code>
aufgerufen werden. Dabei kann man auch angeben, ob dabei ein Event ausgelöst werden soll oder nicht. Events erzeugen spürbare Last auf dem System (siehe NotifyFn), das Ändern von Readings ohne dass dabei Events erzeugt werden jedoch nicht.

Eine Sequenz zum Setzen von Readings könnte folgendermaßen aussehen:

<pre>
readingsBeginUpdate($hash);
readingsBulkUpdate($hash, $readingName1, $wert1 );
readingsBulkUpdate($hash, $readingName2, $wert2 );
readingsEndUpdate($hash, 1);
</pre>

== Internals ==
Werte, die das Modul intern als Teil des Hashes speichert, die aber keine Readings sind, nennt man Internals. Sie werden ebenfalls als Unterstruktur des Hashes der jeweiligen Geräteinstanz gespeichert, beispielswiese <code>$hash->{INTERVAL}</code> für ein Abfrageintervall, das beim Define-Befehl übergeben wurde und als Internal gespeichert wird. Internals werden jedoch im Gegensatz zu Readings nicht im statefile zwischengespeichert.

Falls Werte wie das gerade erwähnte Intervall nicht über den Define-Befehl gesetzt werden sollen und im Betrieb einfach änderbar sein sollen, ist eine alternative Möglichkeit die Speicherung in so genannten Attributen. Dann würde man den Define-Befehl so implementieren, dass er kein Intervall übergeben bekommt und statt dessen nach dem Define-Befehl zusätzlich den Befehl <code>attr</code> erwarten.

== Attribute ==
Parameter einer Geräteinstanz können mit dem Befehl <code>attr</code> als so genannte Attribute gesetzt und damit dem Modul zur Verfügung gestellt werden. Attribute werden zusammen mit der Definition der Geräte beim Speichern der aktuellen Konfiguration von FHEM in die Konfigurationsdatei geschrieben, die auch bei jedem Neustart von FHEM wieder gelesen wird. Zur Laufzeit werden Attribute in der globalen Datenstruktur <code>$attr{$name}</code> gespeichert. Ein Attribut mit dem Namen <code>header</code> würde beispielsweise mit <code>$attr{$name}{header}</code> adressiert (<code>$attr{$name}->{'header'}</code> wäre eine alternative aber unübliche Schreibweise für die selbe Variable).

Zum Auslesen solcher Attribute sollte die Funktion <code>AttrVal($$$)</code> verwendet werden.

Welche Attribute ein Modul unterstützt sollte in der Funktion <code>[[#X_Initialize|X_Initialize]]</code> durch Setzen der Variable <code>$hash->{AttrList}</code> bekannt gemacht werden (siehe unten). Wenn beim Setzen von Attributen die Werte geprüft werden sollen oder zusätzliche Funktionalität implementiert werden muss, dann kann dies in der Funktion <code>[[#X_Attr|X_Attr]]</code> ([[#X_Attr|siehe unten]]) implementiert werden.

== Die wichtigsten Funktionen in einem Modul ==
Eine typische Grundfunktion eines einfachen Moduls ist das Auslesen von Werten von einem physischen Gerät und Bereitstellen dieser Werte innerhalb von FHEM als Readings. Das Geräte könnte beispielsweise an einem USB-Port angeschlossen sein. Folgende Funktionen könnte man beispielsweise in einem Modul mit Namen X implementieren:
* [[#X_Initialize|X_Initialize]] (initialisiert das Modul und gibt de Namen der zusätzlichen Funktionen bekannt)
* [[#X_Define|X_Define]] (wird beim <code>define</code> aufgerufen)
* [[#X_Undef|X_Undef]] (wird beim <code>delete</code>, sowie <code>rereadcfg</code> aufgerufen. Dient zum Abbau von offenen Verbindungen, Timern, etc.)
* [[#X_Delete|X_Delete]] (wird beim <code>delete</code> aufgerufen um das Gerät endgültig zu löschen)
* [[#X_Set|X_Set]] (wird beim Befehl <code>set</code> aufgerufen um Daten an das Gerät zu senden)
* [[#X_Get|X_Get]] (wird beim Befehl <code>get</code> aufgerufen um Daten vom Gerät abzufragen)
* [[#X_Attr|X_Attr]] (wird beim Befehl <code>attr</code> aufgerufen um beispielsweise Werte zu prüfen)
* [[#X_Read|X_Read]] (wird vom globalen select aufgerufen, falls Daten zur Verfuegung stehen)
* [[#X_Parse|X_Parse]] (wird bei zweistufigen Modulen vom Dispatch aufgerufen und muss hier noch beschrieben werden)
* [[#X_Ready|X_Ready]] (wird unter windows als ReadFn-Erstatz benoetigt bzw. um zu pruefen, ob ein Geraet wieder eingesteckt ist)
* [[#X_Notify|X_Notify]] (falls man benachrichtigt werden will)
* [[#X_Rename|X_Rename]] (falls ein Gerät umbenannt wird)

Die Funktionen werden im folgenden beschrieben (soweit diese Seite inzwischen vollständig ist):

=== X_Initialize ===

<pre>
sub X_Initialize($)
{
my ($hash) = @_;
...
</pre>

Das <code>X</code> im Namen muss dabei auf den Namen des Moduls bzw. des definierten Gerätetyps geändert werden. Im Modul mit der Datei <code>36_JeeLink.pm</code> beispielsweise ist der Name der Funktion <code>JeeLink_Initialize</code>. Die Funktion wird von Fhem.pl nach dem Laden des Moduls aufgerufen und bekommt einen Hash für das Modul als zentrale Datenstruktur übergeben.

Dieser Hash wird im globalen Hash %modules gespeichert. <code>$modules{$ModulName}</code> wäre dabei der Hash für das Modul mit dem Namen <code>$ModulName</code>. Es handelt sich also nicht um den oben beschriebenen Hash der Geräteinstanzen sondern einen Hash, der je Modul Werte enthält, beispielsweise auch die Namen der Funktionen, die das Modul implementiert und die fhem.pl aufrufen soll. Die Initialize-Funktion setzt diese Funktionsnamen, in den Hash des Moduls:

<pre>
$hash->{DefFn} = "X_Define";
$hash->{UndefFn} = "X_Undef";
$hash->{DeleteFn} = "X_Delete";
$hash->{SetFn} = "X_Set";
$hash->{GetFn} = "X_Get";
$hash->{AttrFn} = "X_Attr";
$hash->{NotifyFn} = "X_Notify";
$hash->{ReadFn} = "X_Read";
$hash->{ReadyFn} = "X_Ready";
</pre>

<code>X</code> ist wieder durch den Modulnamen ohne die vorangestellte Zahl zu ersetzen.
Entsprechend können auch die Funktionen <code>X_Read</code>, <code>X_Parse</code> etc. durch Zuweisung an <code>$hash->{ReadFn}</code> etc. bekannt gemacht werden.

Darüber hinaus sollten die vom Modul unterstützen Attribute definiert werden:

<pre>
$hash->{AttrList} =
"do_not_notify:1,0 " .
"header " .
$readingFnAttributes;
</pre>

In Fhem.pl werden dann die entsprechenden Werte beim Aufruf eines <code>attr</code>-Befehls in die globale Datenstruktur <code>$attr{$name}</code>, z.B. <code>$attr{$name}{header}</code> für das Attribut <code>header</code> gespeichert. Falls im Modul weitere Aktionen oder Prüfungen beim Setzen eines Attributs nötig sind, dann kann wie im Beispiel oben die Funktion <code>X_Attr</code> implementiert und in der Initialize-Funktion bekannt gemacht werden.

Die Variable <code>$readingFnAttributes</code>, die im obigen Beispiel an die Liste der unterstützten Attribute angefügt wird, definiert Attributnamen, die dann verfügbar werden wenn das Modul zum Setzen von Readings die Funktionen readingsBeginUpdate, readingsBulkUpdate, readingsEndUpdate oder readingsSingleUpdate verwendet. In diesen Funktionen werden Attribute wie <code>event-min-interval</code> oder auch <code>event-on-change-reading</code> ausgewertet. Für Details hierzu siehe commandref.

Des weiteren ist es möglich, das Verhalten von Autocreate zu beeinflussen.
<code>x</code> ist durch den Namen der Geräte zu ersetzen. Legt ihr Geräte mit dem Namen LaCrosse an, dann sollte x durch LaCrosse ersetzt werden.
<pre>
$hash->{AutoCreate} =
{ "x.*" => { ATTR => "event-min-interval:.*:300 event-on-change-reading:.*",
FILTER => "%NAME",
GPLOT => "temp4hum4:Temp/Hum,"} };
autocreateThreshold => "<count>:<timeout>"
</pre>
Mit <code>ATTR =></code> können Vordefinierte Attribute beim Anlegen definiert werden.
Der Wert von <code>FILTER</code> wird als Regex verwendet, wenn ein Filelog angelegt wird. Damit könnt ihr steuern, welche Events ins Filelog komme. Definiert ihr das Feld <code>FILTER</code> nicht, gebt jedoch andere Felder an, dann kann kein filelog mehr automatisch durch autocreate angelegt werden!
Mit Hilfe von <code>GPLOT</code> kann ein Plot angelegt werden. Mit der Angabe definiert ihr, welcher GPLOT angelegt wird.
Mittels <code>autocreateThreshold</code> wird beeinflusst, wie oft <code>count</code>(default 2) und in welchem Zeitabstand <code>timeout</code> (default 60 Sekunden) die gleiche Nachricht empfangen werden muss, damit ein Gerät per autocreate angelegt wird.
Das Verhalten, kann vom Anwender mittels Attribut <code>autocreateThreshold</code> im device "autocreate" überschrieben werden.

=== X_Define ===
Die Define-Funktion eines Moduls wird von Fhem aufgerufen wenn der Define-Befehl für ein Geräte ausgeführt wird und das Modul bereits geladen und mit der Initialize-Funktion initialisiert ist. Sie ist typischerweise dazu da, die übergebenen Parameter zu prüfen und an geeigneter Stelle zu speichern sowie einen Kommunikationsweg zum Gerät zu öffnen (z.B. TCP-Verbindung, USB-Schnittstelle o.ä.)
Sie beginnt typischerweise mit:

<pre>
sub X_Define($$)
{
my ( $hash, $def ) = @_;
my @a = split( "[ \t][ \t]*", $def );
...
</pre>

Als Übergabeparameter bekommt die Define-Funktion den Hash der Geräteinstanz sowie den Rest der Parameter, die im Befehl angegeben wurden. Welche und wie viele Parameter
akzeptiert werden ist Sache dieser Funktion. Im obigen Beispiel wird alles nach dem übergebenen Hash in ein Array aufgeteilt und so können die vom Modul bzw. der Define-Funktion erwarteten Werte über das Array der Reihe nach verarbeitet werden:

<pre>
my $name = $a[0];
my $url = $a[2];
my $inter = 300;
if(int(@a) == 4) {
$inter = $a[3];
if ($inter < 5) {
return "interval too small, please use something > 5, default is 300";
}
}
</pre>

Damit die übergebenen Werte auch anderen Funktionen zur Verfügung stehen und an die jeweilige Geräteinstanz gebunden sind, werden die Werte typischerweise als Internals im Hash der Geräteinstanz gespeichert:

<pre>
$hash->{url} = $url;
$hash->{Interval} = $inter;
</pre>

Wenn eine physische Schnittstelle geöffnet werden soll und dann bei verfügbaren Eingabedaten eine Lese-Funktion von Fhem aufgerufen werden soll, dann kann man in der Define-Funktion die Funktion DevIo_OpenDev aufrufen, die sich um alles weitere kümmert. Sie öffnet die Schnittstelle und fügt den Filedeskriptor an die globale Liste offener Verbindungen (selectlist / readyfnlist) an. Damit kann Fhem in seiner Hauptschleife erkennen, von welchem Gerät Daten bereit stehen und die zuständigen Funktionen aufrufen:

<pre>
my $ret = DevIo_OpenDev( $hash, 0, "X_DevInit" );
</pre>

Die optionale Funktion <code>X_DevInit</code> wird zur weiteren Initialisierung der Verbindung von <code>DevIo_OpenDev</code> aufgerufen. Der zweite Übergabeparameter an <code>DevIo_OpenDev</code> (hier <code>0</code>) steht für reopen und wird benötigt, da die Funktion auch aufgerufen wird, wenn ein USB-Geräte beispielsweise im Betrieb aus- und wieder eingesteckt wird. In diesem Fall wird die Funktion mit <code>1</code> aufgerufen.

=== X_Undef ===

Die <code>Undef</code>-Funktion wird aufgerufen wenn ein Gerät mit <code>delete</code> gelöscht wird oder bei der Abarbeitung des Befehls rereadcfg, der ebenfalls alle Geräte löscht und danach das Konfigurationsfile neu abarbeitet. Entsprechend müssen in der Funktion typische Aufräumarbeiten durchgeführt werden wie das saubere Schließen von Verbindungen oder das Entfernen von internen Timern sofern diese im Modul zum Pollen verwendet wurden (siehe später).

Zugewiesene Variablen im Hash der Geräteinstanz, Internals oder Readings müssen hier nicht gelöscht werden. In fhem.pl werden die entsprechenden Strukturen beim Löschen der Geräteinstanz ohnehin vollständig gelöscht.

Beispiel:
<pre>
sub X_Undef($$)
{
my ( $hash, $name) = @_;
DevIo_CloseDev($hash);
RemoveInternalTimer($hash);
return undef;
}
</pre>

=== X_Delete ===

Die <code>Delete</code>-Funktion ist das Gegenstück zur <code>Define</code>-Funktion und wird aufgerufen wenn ein Gerät mit <code>delete</code> gelöscht wird.

Wenn ein Gerät mittels <code>delete</code> gelöscht wird, wird zuerst die <code>[[#X_Undef|Undef]]</code>-Funktion aufgerufen um offene Verbindungen abzubauen, anschließend wird die <code>Delete</code>-Funktion aufgerufen. Diese dient eher zum aufräumen von Dateien, welche durch das Modul evtl. für dieses Gerät spezifisch erstellt worden sind. Es geht hier also eher darum, alle Spuren sowohl im laufenden FHEM-Prozess, als auch Dateien oder Verbindungen zu löschen die mit diesem Gerät zu tun haben.

Dies kann z.B. folgendes sein:

* Löschen von Dateien im Dateisystem die während der Nutzung dieses Geräts angelegt worden sind.
* Lösen von evtl. Pairings mit dem physikalischen Gerät

Beispiel:
<pre>
sub X_Delete($$)
{
my ( $hash, $name ) = @_;

# Löschen von Geräte-assoziiertem Temp-File
unlink($attr{global}{modpath}."/FHEM/FhemUtils/$name.tmp";)
}
</pre>

=== X_Get ===
Die Get-Funktion wird aufgerufen wenn der Fhem-Befehl <code>get</code> mit einem Gerät dieses Moduls ausgeführt wird. Mit <code>get</code> werden typischerweise Werte von einem Gerät abgefragt. Einige Module verwenden für diese Funktion einen Hash im Modul, der die möglichen <code>get</code>-Optionen mit zusätzlichen Werten definiert:

<pre>
my X_gets = (
"TempSoll" => "XY",
"Steilheit" => "Z"
);
</pre>
In der Get-Funktion selbst werden dann die übergebenen Parameter gegen diesen Hash geprüft.

Beispiel:

<pre>
sub X_Get($@)
{
my ( $hash, @a ) = @_;
return "\"get X\" needs at least one argument" if ( @a < 2 );
my $name = shift @a;
my $opt = shift @a;
if(!$X_gets{$opt}) {
my @cList = keys %X_gets;
return "Unknown argument $opt, choose one of " . join(" ", @cList);
}
...
</pre>

Die Ausgabe der Meldung mit <code>unknown ... choose one of ...</code> ist dabei wichtig, da sie im GUI-Modul verwendet wird um die möglichen <code>get</code>-Optionen zu ermitteln und als Auswahl anzubieten. Im weiteren Verlauf der Get-Funktion könnte man dann mit dem physischen Gerät kommunizieren und den gefragten Wert abfragen und diesen als Return-Wert der Get-Funktion zurückgeben.

=== X_Set ===
Die Set-Funktion ist das Gegenteil zur Get-Funktion. Sie ist dafür gedacht, Werte zum physischen Gerät zu schicken. Falls nur interne Werte im Modul gesetzt werden sollen, so sollte statt Set die Attr-Funktion verwendet werden. Attribute werden bei Save-Config auch in der Fhem.cfg gesichert. Set-Befehle nicht.

Eine Set-Funktion ist ähnlich aufgebaut wie die Get-Funktion, sie bekommt jedoch nach dem Namen der Option auch den zu setzenden Wert übergeben.

Beispiel:
<pre>
sub X_Set($@)
{
my ( $hash, @a ) = @_;
return "\"set X\" needs at least an argument" if ( @a < 2 );
my $name = shift @a;
my $opt = shift @a;
my $value = join("", @a);

if(!defined($X_sets{$opt})) {
my @cList = keys %X_sets;
return "Unknown argument $opt, choose one of " . join(" ", @cList);
}
</pre>

Das GUI FHEM-Web kann für die einzelnen Set-Optionen, die das Modul versteht auch automatisch Eingabehilfen wie Drop-Down Boxen oder Slider erzeugen. In der Detailansicht des GUI kann der Anwender dann die jeweiligen Werte komfortabel auswählen. Dafür muss die Set-Funktion, wenn sie mit der Option <code>?</code> aufgerufen wird, nicht nur einen Text mit <code>"Unknwon ... choose one of ..."</code> zurückgeben sondern den einzelnen Set-Optionen in diesem Rückgabetext nach einem Doppelpunkt Zusatzinformationen anhängen.
Meist prüft man in den Modulen gar nicht auf die Option <code>?</code> sondern gibt generell bei unbekannten Optionen diesen Text zurück.

Beispiel:
<pre>
if(!defined($X_sets{$opt})) {
return "Unknown argument $opt, choose one of mode:verbose,ultra,relaxed turbo:NoArg";
}
</pre>

Mit Kommata getrennte Werte ergeben eine Drop-Down Liste, mit der der User die Werte auswählen kann
<pre>timer:30,120,300
mode:verbose,ultra,relaxed</pre>

Wird kein Doppelpunkt zum Kommando angegeben, so wird eine Eingabezeile angezeigt, die die freie Eingabe eines Wertes erlaubt.

Man kann jedoch die Eingabe-/Auswahlmöglichkeiten durch Widgets vereinfachen. Dazu gibt man hinter dem Doppelpunkt einen Widgetnamen und widgetspezifische Parameter an. Es existieren mehrere solcher Widgets in FHEMWEB. Die gebräuchlichsten sind:

{| class="wikitable"
|-
! Zusatz !! Beispiel !! Beschreibung
|-
| '''noArg''' || <code>reset:noArg</code>|| Es werden keine weiteren Argumente mehr benötigt. In so einem Fall wird bei der Auswahl keine Textbox oder ähnliches angezeigt, da keine weiteren Argumente für diesen Befehl notwendig sind.
|-
| '''slider''':<min>,<step>,<max> || <code>dim:slider,0,1,100</code>|| Es wird ein Schieberegler angezeigt um den Parameter auszuwählen. Dabei werden als Zusatzparameter Minimum, Schrittweite und Maximum angegeben.
|-
| '''colorpicker''' || <code>rgb:colorpicker,RGB</code>|| es wird ein Colorpicker angezeigt, der dem Anwender die Auswahl einer Farbe ermöglicht. Bitte dazu auch den Wiki Artikel zum Colorpicker lesen: [[Color#Colorpicker]]
|-
| '''multiple''' || <code>...:multiple:Telefon,Multimedia,Licht,Heizung</code> || Es erscheint ein Auswahldialog, wo man verschiedene Werte durch klicken auswählen kann. Optional kann man in einem Freitext eigene Werte ergänzen. dieser Dialog wird bspw. bei der Raum-Auswahl (Attribut "room") oder der Gruppen-Auswahl (Attribut "group") in FHEMWEB genutzt.
|-
| '''sortable''' || <code>...:sortable:Montag,Dienstag,...</code> || Es erscheint ein Auswahldialog, wo man verschiedene Werte auswählen und sortieren kann. Man kann dabei Werte durch Klicken auswählen und durch Drag'n'Drop sortieren.
|}

Es gibt noch weitere solcher Widgets. Eine genaue Auflistung dazu findet sich in der [http://fhem.de/commandref.html#widgetOverride commandref] unter widgetOverride zu FHEMWEB.

'''Hinweise'''

- Damit in einer Eingabe bereits der aktuelle Wert vorbelegt bzw. in einer Auswahlliste der aktuelle Wert vorselektiert ist, muss es im Modul bzw. Gerät ein Reading mit dem gleichen Namen wie die Set-Option geben. Der Wert des gleichnamigen Readings wird dann als Vorbelegung / Vorselektion verwendet.

- bei den üblichen Kommandos wie on off sollte man auf noArg verzichten, da diese durch FHEMWeb automatisch in der Raumübersicht angezeigt werden. Wenn man hier noArg spezifiziert, so werden diese nicht neben dem Modul in der Raumübersicht angezeigt und der User muss sich diese vie webCmd dann erst selbst definieren, was natürlich unschön ist

- der User kann sich in der Raumübersicht nach wie vor via webCmd eine entsprechende Steuerung anlegen.

=== X_Attr ===
Die Attr-Funktion implementiert Prüfungen der bei einem <code>attr</code> übergebenen Werte und eventuell zusätzliche Aktionen wenn ein Attribut gesetzt wird. Die Liste der möglichen Attribute wird in der <code>[[#X_Initialize|X_Initialize]]-Funktion</code> definiert ([[#X_Initialize|siehe oben]]). Fhem ruft bei einem Attr-Befehl die zuständige <code>X-Attr-Funktion</code> auf und wenn diese keine Fehlermeldung sondern <code>undef</code> zurückgibt, dann schreibt fhem.pl die bei <code>attr</code> angegebenen Werte in die jeweilige Datenstruktur <code>$attr{$name}-> ...</code>

Beispiel:

<pre>
X_Attr(@)
{
my ($cmd,$name,$aName,$aVal) = @_;
# $cmd can be "del" or "set"
# $name is device name
# aName and aVal are Attribute name and value
if ($cmd eq "set") {
if ($aName eq "Regex") {
eval { qr/$aVal/ };
if ($@) {
Log3 $name, 3, "X: Invalid regex in attr $name $aName $aVal: $@";
return "Invalid Regex $aVal";
}
}
}
return undef;
}
</pre>

Zusätzlich ist es möglich auch übergebene Attributwerte zu normalisieren und korrigieren, indem man im Parameterhash den ursprünglichen Wert anpasst. Dies erfolgt im Beispiel über die Modifikation des Wertes mit Index 3 im Parameterarray, also <code>$_[3]</code>.

Die Attr-Funktion bekommt nicht den Hash der Geräteinstanz übergeben, da sie ja auch keine Werte dort speichern muss, sondern den Befehl <code>set</code> oder <code>del</code> je nachdem ob ein Attribut gesetzt oder gelöscht wird, den Namen der Geräteinstanz sowie den Namen des Attributs und seinen Wert.
Im obigen Beispiel wird für ein Attribut mit Namen Regex geprüft ob die Regex fehlerhaft ist. Falls sie ok ist, wird <code>undef</code> zurückgegeben und fhem.pl speichert den Wert des Attributs.

Falls man Attribute mit Platzhaltern definiert (Wildcard-Attribute), z.B. mit
<pre>
$hash->{AttrList} =
"reading[0-9]*Name " .
# usw.
</pre>
dann können Anwender Attribute wie reading01Name, reading02Name etc. setzen. Leider funktioniert das bisher nicht durch Klicken, da Fhemweb nicht alle denkbaren Ausprägungen in einem Dropdown anbieten kann. Der Benutzer muß solche Attribute über den <code>attr</code> Befehl eintippen.

Man kann jedoch in der Attr-Funktion neu gesetzte Ausprägungen von Wildcard-Attributen an die gerätespezifische userattr-Variable anfügen. Dann können bereits gesetzte Attribute in Fhemweb durch Klicken ausgewählt und geändert werden.
Dazu reicht ein Aufruf von

<pre>
addToDevAttrList($name, $aName);
</pre>

in der Attr-Funktion wenn ein Attribut gesetzt wird.

=== X_Read ===

Die X_Read-Funktion wird aus der Hauptschleife von FHEM aus aufgerufen wenn das Gerät, für das das Modul zuständig ist, Daten bereit gestellt hat, die gelesen werden können. Im folgenden Beispiel wird über eine serielle Schnittstelle (beziehungsweise über einen USB-To-Seriell-Konverter) von einem angeschlossenen Gerät gelesen. Dazu werden die bisher verfügbaren Daten mit der Funktion <code>DevIo_SimpleRead</code> gelesen. Da die Übertragung möglicherweise noch nicht vollständig ist, kann es sein, dass kurz darauf die X_Read-Funktion wieder aufgerufen wird und ein weiterer Teil oder der Rest der Daten gelesen werden kann.
Die Funktion muss daher prüfen ob schon alle erwarteten Daten angekommen sind und gegebenenfalls die bisher gelesenen Daten zwischenspeichern. Es bietet sich an, dies im Hash der Geräteinstanz zu tun. Im Beispiel ist dies <code>$hash->{buffer}</code> an den die jeweils gelesenen Daten angehängt werden bis die folgende Prüfung ein für das jeweilige Protokoll passendes Frame identifiziert.

<pre>
sub X_Read($)
{
my ($hash) = @_;
my $name = $hash->{NAME};

# read from serial device
my $buf = DevIo_SimpleRead($hash);
return "" if ( !defined($buf) );

# convert to hex string to make parsing with regex easier
$hash->{buffer} .= unpack ('H*', $buf);
Log3 $name, 5, "Current buffer content: " . $hash->{buffer};

# did we already get a full frame?
if ($hash->{buffer} =~ "ff1002(.{4})(.*)1003(.{4})ff(.*)")
...
</pre>

Die zu lesenden Nutzdaten können dann je nach Protokoll des Geräts beispielsweise an einer festgelegten Stelle im Frame (dann in <code>$hash->{buffer}</code>) stehen oder aus dem Kontext mit einem Regex-Match extrahiert werden und in Readings gespeichert werden (siehe unten).

=== X_Ready ===

muss noch beschrieben werden.

Beispiel:
<pre>
sub X_Ready($)
{
my ($hash) = @_;
return DevIo_OpenDev($hash, 1, undef )
if ( $hash->{STATE} eq "disconnected" );

# This is relevant for windows/USB only
my $po = $hash->{USBDev};
my ( $BlockingFlags, $InBytes, $OutBytes, $ErrorFlags ) = $po->status;
return ( $InBytes > 0 );
}
</pre>

=== X_Notify ===

Die X_Notify-Funktion wird aus der Funktion DoTrigger in fhem.pl heraus aufgerufen wenn ein Modul Events erzeugt hat. Damit kann ein Modul auf Events anderer Module reagieren. Typische Beispiele sind das Filelog-Modul oder das Average-Modul. Average reagiert auf Events anderer Module und erweitert diese mit der Berechnung von Tages- und Monats-Durchschnittswerten.

Die Notify-Funktion bekommt dafür zwei Hash-Referenzen übergeben: den Hash des eigenen Geräts und den Hash des Geräts, das die Events erzeugt hat.
Über den Hash des eigenen Geräts kann die Notify-Funktion beispielsweise auf die Internals oder Attribute des eigenen Geräts zugreifen.
Über den Hash des Geräts, das die Events erzeugt hat, kann es die Events verarbeiten. Events werden je Gerät in einem Array, das über das Internal <code>CHANGED</code> referenziert wird, gespeichert.

Beispiel:
<pre>
sub X_Notify($$)
{
my ($own_hash, $dev_hash) = @_;
my $ownName = $own_hash->{NAME}; # own name / hash

return "" if(IsDisabled($ownName)); # Return without any further action if the module is disabled

my $devName = $dev_hash->{NAME}; # Device that created the events

my $count = @{$dev_hash->{CHANGED}}; # number of events / changes

foreach my $event (@{$dev_hash->{CHANGED}}) {
#
# Examples:
# $event = "readingname: value"
# or
# $event = "INITIALIZED" (for device "global")
#
# processing $event with further code
}
}
</pre>

Da die Notify-Funktion für jedes Gerät mit allen seinen Events aufgerufen wird, muss sie in einer Schleife alle Events prüfen und entscheiden, ob es mit dem jeweiligen Event etwas tun möchte. Ein Gerät, das die Notify-Funktion implementiert sieht dafür typischerweise einen regulären Ausdruck vor, der für die Filterung verwendet wird.

Wenn man nur gezielt von bestimmten Definitionen Events erhalten will, kann man diese auch in Form einer kommaseparierten Liste von Definitions-Namen in <code>$hash->{NOTIFYDEV}</code> angeben. Bspw. kann man in der Define-Funktion dort diesen Wert setzen. Dadurch wird die Notify-Funktion nur aufgerufen wenn eines der dort gelisteten Definitionen ein Event erzeugt hat. Ein typischer Fall ist die Begrenzung von Events auf "global":

<pre>
in der Define-Funktion:

$hash->{NOTIFYDEV} = "global";
$hash->{NOTIFYDEV} = "global,Definition_A,Definition_B";
</pre>

Dies schont insbesondere bei grossen Installationen Ressourcen, da die Notify-Funktion nicht sämtliche Events, sondern nur noch Events der hier gelisteten Definitionen erhält. Dadurch erfolgen deutlich weniger Aufrufe der Notify-Funktion, was Systemressourcen schont.

Als anschauliches Beispiel und für weitere Details eignet sich das Modul 98_Average.pm

=== X_DbLog_splitFn ===
Mit der DbLog_SplitFn kann der Modulautor selbst festlegen, wie die Events des Moduls in die Bestandteile Reading/Value/Unit zerlegt werden um ein korrektes Logging per DbLog zu gewährleisten. 
Eingangsparameter: Das generierte Event 
Rückgabewerte: Array: Reading/Value/Unit

Beispiel:
<pre>
sub X_DbLog_splitFn($)
{
my ($event) = @_;
my ($reading, $value, $unit);

if($event =~ m/temperature/) {
$reading = 'temperature';
$value = substr($event,12,4);
$unit = '°C';
}

return ($reading, $value, $unit);
}
</pre>

== Pollen von Geräten ==
Wenn Geräte von sich aus keine Informationen senden sondern abgefragt werden müssen, kann man im Modul die Funktion <code>InternalTimer</code> verwenden. Man übergibt ihr den Zeitpunkt für den nächsten Aufruf, den Namen der Funktion, die aufgerufen werden soll, den zu übergebenden Parameter und ein Flag ob der erste Aufruf verzögert werden soll falls die Initialiserung des Geräts noch nicht abgeschlossen ist. Als zu übergebender Parameter wird üblicherweise der Hash der betroffenen Geräteinstanz verwendet. Damit hat die aufgerufene Funktion Zugriff auf alle wichtigen Daten der Geräteinstanz. Eventuell zusätzlich benötigte Werte können einfach als weitere Internals über den Hash zugänglich gemacht werden.

Beispielsweise könnte man für das Abfragen eines Geräts in der Define-Funktion den Timer folgendermassen setzen:

<pre>
# initial request after 2 secs, there timer is set to interval for further update
InternalTimer(gettimeofday()+2, "X_GetUpdate", $hash, 0);
</pre>

in der Funktion <code>X_GetUpdate</code> selbst wird dann der Timer neu gesetzt, so dass nach einem Intervall die Funktion erneut aufgerufen wird:

<pre>
sub X_GetUpdate($)
{
my ($hash) = @_;
my $name = $hash->{NAME};
InternalTimer(gettimeofday()+$hash->{Interval}, "X_GetUpdate", $hash, 1);
Log3 $name, 4, "X: GetUpdate called ...";
</pre>

Im weiteren Verlauf der Funktion könnte man dann das Gerät abfragen und die abgefragten Werte in Readings speichern. Falls das Abfragen der Werte jedoch zu einer Verzögerung und damit zu einer Blockade von FHEM führen kann, ist es möglich, in der GetUpdate-Funktion nur die Aufforderung zum Senden bestimmter Daten an das angeschlossene Gerät zu senden und dann das Lesen über die oben beschriebene Read-Funktion zu implementieren, die beim Anstehen von Daten aufgerufen wird.

== Logging / Debugging ==
Um Innerhalb eines Moduls eine Protokollmeldung in die Fhem-Logdatei zu schreiben, wird die Funktion Log3 aufgerufen:
<pre>
Log3 $name, 3, "X: Problem erkannt ...";
</pre>

Die Parameter der Funktion Log3 sind der Name oder der Hash der Geräteinstanz, das Verbose-Level, in dem die Meldung sichtbar sein soll und die Meldung selbst.
Den Namen der Geräteinstanz kann man in den Funktionen, die den Hash übergeben bekommen einfach aus diesem Hash nehmen:

<pre>
my $name = $hash->{NAME};
</pre>

Um für ein neues Modul das Verbose-Level zu erhöhen, ohne gleich für das Gesamte FHEM alle Meldungen zu erzeugen kann man den Befehl
<code>attr gerätename verbose</code> verwenden. Beispielsweise <code>attr PM verbose 5</code>

Damit bietet es sich an im Modul Meldungen, die im normalen Betrieb nicht benötigt werden, beim Aufruf von Log3 mit dem Level 4 oder 5 anzugeben. Wenn man dann bei der Fehlersuche mehr Meldungen sehen möchte, erhöht man mit attr X verbose das Level für das betroffene Gerät.

== Zweistufiges Modell für Module ==
siehe auch
* [http://forum.fhem.de/index.php/topic,18920.msg128100.html#msg128100|The FHEM two-level model]
* [http://forum.fhem.de/index.php/topic,13438.msg83643.html#msg83643|Zum Initialize bei physikalischen und logischen Geräten]

Das zweistufige Modell besteht aus
* physisches Modul - z.B. für CUL (00_CUL.pm), der mehrer Protokolle empfängt, u.a. FS20
* logische Modul(e) - z.B. das Protokoll FS20 (10_FS20.pm)

Das physische Modul öffnet die Datenverbindung zum Gerät.

=== Kommunikation vom Gerät zu den logischen Modulen ===
Die [[#X_Read|X_Read]]-Funktion wird aus der Hauptschleife von Fhem aufgerufen sobald das Gerät, für das das Modul zuständig ist, Daten bereit gestellt hat, die gelesen werden können.

Unter Windows funktioniert "select" nur für Geräte, die via TCP verbunden sind. Für alle anderen Geräte ist eine [[#X_Ready|X_Ready]]-Funktion von Nöten, die 10x pro Sekunde das Gerät abfrägt und "true" zurück gibt, sollten Daten bereit stehen.

Die X_Read-Funktion stellt sicher, dass die Daten
* komplett und
* korrekt
sind und sie ruft die globale Funktion Dispatch() mit einer Nachricht auf.

Dispatch() sucht nach einem passenden lokalen Modul via
* $hash->{Clients} oder $hash->{MatchList} im physischen Modul
* $hash->{Match} in allen passenden logischen Modulen
und ruft X_Parse in den gefundenen Modulen auf.

X_Parse
* untersucht die übergebenen Daten (von Dispatch() übergeben)
* setzt alle [[#Readings|readings]] via readings*update Funktionen
* gibt den Namen des logischen Device zurück

Es findet kein Event-Triggering statt, wenn die readings*update Funktionen
* von X_Parse aufgerufen werden und
* X_Parse wiederum von Dispatch() aufgerufen wurde.
(Im Gegensatz zum direkten Aufrufen der readings*update Funktionen ohne vorhergehendes Dispatch() )

Dispatch() triggert das Event-Handling für das von X_Parse zurückgegebene logische Device.

=== Kommunikation von den logischen Modulen zum Gerät ===

Um von einem logischen Modul an ein physisches Gerät zu senden, wird im logischen Modul das Attribut IODev mit dem namen des physischen Devices gesetzt.
Der Befehl
<code>AssignIoPort($hash);</code>
in der X_Define-Funktion des logischen Devices erledigt das.

Als Befehl zum Schreiben vom logischen ins physische Gerät soll <code>IOWrite()</code> verwendet werden. IOWrite() ruft im physischen Gerät die X_Write-Funktion auf.

Wenn es keine direkte Kommunikation zwischen dem logischen und dem physischen Gerät gibt(keine direkten Aufrufe von Funktionen, kein direktes überprüfen von $hash Werten,...) so können die Module hintereinander geschaltet werden (z.B. für Routerfunktionen wie in RFR) oder mittels FHEM2FHEM:RAW zwei Fhem Installationen verbunden werden und die logischen Devices werden dennoch funktionieren.

== Ergänzende Hinweise ==
Die Wahl der vorangestellten Nummer für den Dateinamen eines neuen Moduls hat keine Bedeutung mehr, es sei denn die Nummer ist 99. Module, die mit 99_ beginnen, werden von FHEM automatisch geladen. Module mit einer anderen Nummer nur wenn ein <code>define</code>-Befehl dafür sorgt, dass das Modul geladen wird.

Wenn ein Modul Initialisierungsdaten benötigt, sollten diese im Modul selbst enthalten sein. Eine zusätzliche Datei oder sogar ein Unterverzeichnis mit mehreren Dateien ist bei FHEM nicht üblich und sollte bei Modulen, die mit FHEM ausgeliefert werden nur in Rücksprache mit Rudolf König angelegt werden, da sie sonst bei einem Update nicht verteilt werden.

== Weitere Informationen ==
Wenn man weitere Details wissen möchte, ist ein erster sinnvoller Schritt ein Blick in die Datei fhem.pl. Dort sieht man im Perl-Code wie die Module aufgerufen werden, was vorher passiert und was danach. Am Anfang der Datei (ca. ab Zeile 130) findet man beispielsweise eine Liste der globalen Variablen, die den Modulen zur Verfügung stehen sowie Details zu den wichtigen Hashes %modules und %defs. Wer mit Perl noch nicht so gut klar kommt, dem hilft eventuell ein Blick auf die Perldoc Website[http://perldoc.perl.org/] oder in das Perl-Buch seiner Wahl. Auch die FHEM Commandref [http://fhem.de/commandref.html] sollte nicht unterschätzt werden. Es stehen oft mehr interessante Details auch für Modulentwickler darin als man zunächst vermuten könnte.

== "Hello World" Beispiel ==

98_Hello.pm

<pre>
package main;
use strict;
use warnings;

my %Hello_gets = (
"whatyouwant" => "can't",
"whatyouneed" => "try sometimes",
"satisfaction" => "no"
);

sub Hello_Initialize($) {
my ($hash) = @_;

$hash->{DefFn} = 'Hello_Define';
$hash->{UndefFn} = 'Hello_Undef';
$hash->{SetFn} = 'Hello_Set';
$hash->{GetFn} = 'Hello_Get';
$hash->{AttrFn} = 'Hello_Attr';
$hash->{ReadFn} = 'Hello_Read';

$hash->{AttrList} =
"formal:yes,no "
. $readingFnAttributes;
}

sub Hello_Define($$) {
my ($hash, $def) = @_;
my @param = split('[ \t]+', $def);

if(int(@param) < 3) {
return "too few parameters: define <name> Hello <greet>";
}

my $hash->{name} = $param[0];
my $hash->{greet} = $param[2];

return undef;
}

sub Hello_Undef($$) {
my ($hash, $arg) = @_;
# nothing to do
return undef;
}

sub Hello_Get($@) {
my ($hash, @param) = @_;

return '"get Hello" needs at least one argument' if (int(@param) < 2);

my $name = shift @param;
my $opt = shift @param;
if(!$Hello_gets{$opt}) {
my @cList = keys %Hello_gets;
return "Unknown argument $opt, choose one of " . join(" ", @cList);
}

if($attr{$name}{formal} eq 'yes') {
return $Hello_gets{$opt}.', sir';
}
return $Hello_gets{$opt};
}

sub Hello_Set($@) {
my ($hash, @param) = @_;

return '"set Hello" needs at least one argument' if (int(@param) < 2);

my $name = shift @param;
my $opt = shift @param;
my $value = join("", @param);

if(!defined($Hello_gets{$opt})) {
my @cList = keys %Hello_gets;
return "Unknown argument $opt, choose one of " . join(" ", @cList);
}
$hash->{STATE} = $Hello_gets{$opt} = $value;

return "$opt set to $value. Try to get it.";
}

sub Hello_Attr(@) {
my ($cmd,$name,$attr_name,$attr_value) = @_;
if($cmd eq "set") {
if($attr_name eq "formal") {
if($attr_value !~ /^yes|no$/) {
my $err = "Invalid argument $attr_value to $attr_name. Must be yes or no.";
Log 3, "Hello: ".$err;
return $err;
}
} else {
return "Unknown attr $attr_name";
}
}
return undef;
}

1;

=pod
=begin html

<a name="Hello"></a>
<h3>Hello</h3>
<ul>
Hello implements the classical "Hello World" as a starting point for module development.
You may want to copy 98_Hello.pm to start implementing a module of your very own. See
<a href="http://www.fhemwiki.de/wiki/DevelopmentModuleIntro">DevelopmentModuleIntro</a> for an
in-depth instruction to your first module.
 
<a name="Hellodefine"></a>
Define
<ul>
<code>define <name> Hello <greet></code>
 
Example: <code>define HELLO Hello TurnUrRadioOn</code>
 
The "greet" parameter has no further meaning, it just demonstrates
how to set a so called "Internal" value. See <a href="http://fhem.de/commandref.html#define">commandref#define</a>
for more info about the define command.
</ul>
 

<a name="Helloset"></a>
Set 
<ul>
<code>set <name> <option> <value></code>
 
You can set any value to any of the following options. They're just there to
get them. See <a href="http://fhem.de/commandref.html#set">commandref#set</a>
for more info about the set command.
 
Options:
<ul>
<li>satisfaction 
Defaults to "no"</li>
<li>whatyouwant 
Defaults to "can't"</li>
<li>whatyouneed 
Defaults to "try sometimes"</li>
</ul>
</ul>
 

<a name="Helloget"></a>
Get 
<ul>
<code>get <name> <option></code>
 
You can get the value of any of the options described in
<a href="#Helloset">paragraph "Set" above</a>. See
<a href="http://fhem.de/commandref.html#get">commandref#get</a> for more info about
the get command.
</ul>
 

<a name="Helloattr"></a>
Attributes
<ul>
<code>attr <name> <attribute> <value></code>
 
See <a href="http://fhem.de/commandref.html#attr">commandref#attr</a> for more info about
the attr command.
 
Attributes:
<ul>
<li>formal no|yes 
When you set formal to "yes", all output of get will be in a
more formal language. Default is "no".
</li>
</ul>
</ul>
</ul>

=end html

=cut
</pre>

Der HTML-Code zwischen den Tags <code>=pod</code> und <code>=cut</code> dient zur Generierung der commandref.html. Der HTML-Inhalt wird automatisch beim Verteilen des Moduls im Rahmen des Update-Mechanismus aus jedem Modul extrahiert und daraus die Commandref in verschiedenen Sprachen erstellt. Eine detaillierte Beschreibung wie ein Commandref-Abschnitt in einem Modul definiert wird, siehe: [[Guidelines zur Dokumentation]]

== Noch zu beschreiben ==
* Zweistufiges Modell für Module
* Funktion X_Ready ...
* Funktion X_State_Fn: {{Link2Forum|Topic=32680}}, siehe auch [[DevelopmentState]]
* FW_summaryFn (wird von FHEMWEB aufgerufen fuer Raum-Uebersicht)
* FW_detailFn (wird von FHEMWEB aufgerufen fuer Detail-Ansicht)
* DevIO

[[Kategorie:Development]]

DevelopmentModuleAPI

2016-02-15T21:02:43Z

Viegener: Zeitstempel hinzugefügt

{{Randnotiz|RNTyp=r|RNText=Bitte beachten: letztendlich entscheidend ist immer der Perl-Code, Unstimmigkeiten sollten im Fhem-Forum angemerkt (oder hier berichtigt) werden!
<hr />
Please note: in the end it is always the Perl code itself that is relevant; please report errors and omissions in the fhem forum (or correct them here)!
}}
Dieses Seite soll eine Beschreibung der für Moduleentwickler verfügbaren Funktionen enthalten, um für Modulentwickler
* Wiederverwendbare Routinen leichter identifizieren zu können
* Durch Wiederverwendung mehr Einheitlichkeit zu erzeugen
* Aufwand zu verringern
* Bei Änderungen auch betroffene Module leichter identifiziern zu können

Natürlich hat diese Seite keinen Anspruch auf Vollständigkeit und jeder ist aufgefordert mitzuarbeiten, sobald er beim Stöbern über einen Funktion stolpert, die auch andere interessieren könnte.

== Command handling ==
=== AnalyzeCommand ===
AnalyzeCommand ermöglicht das Parsen und die Ausführung eines FHEM-Befehls, wie in [[FHEMWEB]] im Kommandoeingabefeld enthalten.
:<code>AnalyzeCommand ($cl, $cmd)</code>
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$cl</code>'''

''might be undef''
|| Devicehash für die Ausführung des Kommandos in einem spezifischen Kontext eines Devices (Quelle des Befehles z.B. für Berechtigungsprüfung) 
|-
| style="vertical-align:top" | '''<code>$cmd</code>'''

''mandatory''
|| Kommandos, die ausgeführt werden sollen. 
Beispiel:
* ''define dummy1 dummy''
* ''{ Log3(undef, 1, "Hallo");}''
|}

=== AnalyzeCommandChain ===
AnalyzeCommandChain ermöglicht das Parsen und die Ausführung von FHEM-Befehlen, wie in FHEMWeb im Kommandoeingabefeld enthalten.
:<code>AnalyzeCommandChain ($cl, $cmds)</code>
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$cl</code>'''

''might be undef''
|| Devicehash für die Ausführung des Kommandos in einem spezifischen Kontext eines Devices (Quelle des Befehles z.B. für Berechtigungsprüfung) 
|-
| style="vertical-align:top" | '''<code>$cmds</code>'''

''mandatory''
|| Kommandos, das ausgeführt werden soll, durch ; getrennt. 
Beispiel:
* ''define dummy1 dummy; list dummy1''
|}

== Diverse ==
=== ReplaceSetMagic===
ReplaceSetMagic
:<code>($err, @result) = ReplaceSetMagic($hash, $nsplit, @elements)</code>
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''might be undef''
|| Devicehash für die Ausführung des Kommandos in einem spezifischen Kontext eines Devices (Quelle des Befehles z.B. für Berechtigungsprüfung) 
|-
| style="vertical-align:top" | '''<code>$nsplit</code>'''

''Zahl''
|| Begrenzung für den Split des Ergebnisstrings nach erfolgter Ersetzung (siehe elements)

|-
| style="vertical-align:top" | '''<code>@elements</code>'''

''mandatory''
|| Parameterarray mit Strings Die Elemente des übergebenen Arrays werden in einem String getrennt duch Leerzeichen zusammengefasst.
|}

{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$err</code>'''

|| Im Fehlerfall: Fehlermeldung sonst undef
|-
| style="vertical-align:top" | '''<code>@result</code>'''

|| Ergebnis der Ersetzung von Readings und Perl Aufrufen im Parameterarray. Die Elemente des übergebenen Arrays werden in einem String, getrennt durch Leerzeichen, zusammengefasst und im Rückgabewert wieder in ein Array (unter Berücksichtigung von nsplit als Begrenzung für den perl-Split-Aufruf) zerlegt.
|}

== Time / Timestamp ==
=== FmtDateTimeRFC1123===
:<code>$timestampGMT = FmtDateTimeRFC1123($time)</code>
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$time</code>'''

''might be undef''
|| Zeitangabe wie sie von der <code>time</code> Funktion zurückgegeben wird 
<code>Mon, 15 Feb 2016 20:52:20 GMT</code>
|}

{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestampGMT </code>'''

|| Zeitstempel GMT (Greenwich Mean Time) wie er in RFC1123 beschrieben wird. Diese werden zum Beispiel bei http verwendet. 
<code>Mon, 15 Feb 2016 20:52:20 GMT</code>
|}

=== FmtDateTime===

:<code>$timestamp = FmtDateTime($time)</code>
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$time</code>'''

|| Zeitangabe wie sie von der <code>time</code> Funktion zurückgegeben wird
|}

{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp </code>'''

|| Zeitstempel in lokaler Zeitzone im Format 
<code>2016-02-16 19:34:24</code>
|}

=== TimeNow ===

:<code>$timestamp = TimeNow( )</code>

{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp </code>'''

|| Zeitstempel der aktuellen Uhrzeit in lokaler Zeitzone im Format 
<code>2016-02-16 19:34:24</code> 
Benutzt FmtDateTime
|}

== Readings ==
Die verschiedenen Funktionen zu Readings sind hier beschrieben:

[[DevelopmentIntroduction]] und [[DevelopmentModuleIntro]]

== Fehlt noch ==
* Log3
* IsDisabled
* IsDummy
* IsIgnored
* IsIoDummy
* InternalTimer
* RemoveInternalTimer
* configDBUsed
* devspec2array
* FmtTime
* EvalSpecials
* DoTrigger
* InternalVal
* ReadingsVal
* ReadingsNum
* ReadingsTimestamp
* Value
* OldValue
* OldTimestamp
* AttrVal
* readingsBeginUpdate
* readingsBulkUpdate
* readingsEndUpdate
* readingsSingleUpdate
* computeClientArray
* FileRead
* FileWrite
* getUniqueId
* getKeyValue
* setKeyValue
* Debug
[[Kategorie:Development]]

DevelopmentModuleAPI

2016-02-09T23:30:50Z

Viegener: Erste Version als Einstieg

== Einleitung ==
Dieses Seite soll eine Beschreibung der für Moduleentwickler verfügbaren Funktionen enthalten, um für Modulentwickler
* Wiederverwendbare Routinen leichter identifizieren zu können
* Durch Wiederverwenund mehr Einheitlichkeit zu erzeugen
* Aufwand zu veringern
* Bei Änderungen auch betroffene Module leichter identifiziern zu können

Natürlich hat diese Seite keinen Anspruch auf Vollständigkeit und jeder ist aufgefordert mitzuarbeiten, sobald er beim Stöbern über einen Funktion stolpert, die auch andere interessieren könnte.

== Command handling ==

=== AnalyzeCommand ===
AnalyzeCommand ermöglicht das Parsen und die Ausführung eines FHEM-Befehls, wie in FHEMWeb im Kommandoeingabefeld enthalten.
:<code>AnalyzeCommand ($cl, $cmd)</code>
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$cl</code>'''

''might be undef''
|| Devicehash für die Ausführung des Kommandos in einem spezifischen Kontext eines Devices (Quelle des Befehles z.B. für Berechtigungsprüfung) 
|-
| style="vertical-align:top" | '''<code>$cmd</code>'''

''mandatory''
|| Kommandos, die ausgeführt werden sollen. 
Beispiel:
* ''define dummy1 dummy''
* ''{ Log3(undef, 1, "Hallo");}''
|}

=== AnalyzeCommandChain ===
AnalyzeCommandChain ermöglicht das Parsen und die Ausführung von FHEM-Befehlen, wie in FHEMWeb im Kommandoeingabefeld enthalten.
:<code>AnalyzeCommandChain ($cl, $cmds)</code>
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$cl</code>'''

''might be undef''
|| Devicehash für die Ausführung des Kommandos in einem spezifischen Kontext eines Devices (Quelle des Befehles z.B. für Berechtigungsprüfung) 
|-
| style="vertical-align:top" | '''<code>$cmds</code>'''

''mandatory''
|| Kommandos, das ausgeführt werden soll, durch ; getrennt. 
Beispiel:
* ''define dummy1 dummy; list dummy1''
|}

== Diverse ==

=== ReplaceSetMagic===
ReplaceSetMagic
:<code>($err, @result) = ReplaceSetMagic($hash, $nsplit, @elements)</code>
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''might be undef''
|| Devicehash für die Ausführung des Kommandos in einem spezifischen Kontext eines Devices (Quelle des Befehles z.B. für Berechtigungsprüfung) 
|-
| style="vertical-align:top" | '''<code>$nsplit</code>'''

''Zahl''
|| Begrenzung für den Split des Ergebnisstrings nach erfolgter Ersetzung (siehe elements)

|-
| style="vertical-align:top" | '''<code>@elements</code>'''

''mandatory''
|| Parameterarray mit Strings Die Elemente des übergebenen Arrays werden in einem String getrennt duch Leerzeichen zusammengefasst.
|}

{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$err</code>'''

|| Im Fehlerfall: Fehlermeldung sonst undef
|-
| style="vertical-align:top" | '''<code>@result</code>'''

|| Ergebnis der Ersetzung von Readings und perlaufrufen im Parameterarray. Die Elemente des übergebenen Arrays werden in einem String getrennt duch Leerzeichen zusammengefasst und im Rückgabewert wieder in ein Array (unter Berücksichtigung von nsplit als Begrenzung für den perl-Spllit-Aufruf) zerlegt.
|}

== Readings ==

Die verschiedenen Funktionen zu Readings sind hier beschieben:

[[DevelopmentIntroduction]] und [[DevelopmentModuleIntro]]

== Fehlt noch ==
* Log3

[[Kategorie:Development]]

TelegramBot

2015-12-26T23:15:50Z

Viegener:

TelegramBot

2015-12-19T21:02:29Z

Viegener: Rechtschreibkorrekturen

Telegram - old API method

2015-12-19T15:43:14Z

Viegener:

Telegram - old API method

2015-12-19T15:42:27Z

Viegener:

Telegram - old API method

2015-12-19T15:41:38Z

Viegener: Verweis auf TelegramBot-Modul as offizielle Version

TelegramBot

2015-12-19T15:36:58Z

Viegener: Emojievrsand hinzugefügt

TelegramBot

2015-11-25T16:37:51Z

Viegener:

Benutzer:Viegener

2015-11-25T16:34:53Z

Viegener:

; Erstmal nur ein Überblick über meine FHEM-Beteiligung

== FHEM Benutzung ==

Wunsch war die Zusammenführung der verschiedenen Funksysteme in einem zentralen System.
Ausdrücklich mit den Zielen
* Übergreifende Steuerungen und Makros zu ermöglichen
* Zentrale Bedienungsterminals (tablet)
* Steuerung von Aussen
* Am wichtigsten natürlich Spass am Basteln und Programmieren!!!

 
;Komponenten
* Somfy RTS Rolläden (Aktoren und Handfernbedienungen)
* FS20 Steckdosen
* Thermo/Hygro-Sensoren von LaCrosse und Technoline
* Mehrere Sonos-Komponenten
* Fritzbox
* Neu: Homematic
* Loewe Fernseher (dafür gibt es noch nichts)

 
;Mein FHEM habe ich im Februar 2015 installiert.
* 03/2015 Umzug Raspberry Pi2
* 04/2015 Somfy-Einbindung
* 05/2015 FHEM Tablet UI
* 06/2015 Entwicklung eines Telegram Moduls für Benachrichtigungen und Kommandos (also bidirektional)
** Telegram ist frei, plattformübergreifend und erlaubt Gruppenchats
* 09/2015 Variante der Telegram-Anbindung mit dem TelegramBot-Modul 50_TelegramBot
* 11/2015 TelegramBot offizielles FHEM-Modul (erhältlich über update)

== FHEM Development ==

Aber klar, das macht ja den Spass aus. Gerne in C, C++, Perl, Java, Javascript und vielen anderen, die heute nicht mehr relevant sind
Wenns sein muss auch in CSS, HTML etc

* [https://github.com/viegener/Telegram-fhem/blob/master/70_Telegram.pm 70_Telegram.pm]
* [https://github.com/viegener/Telegram-fhem/blob/master/50_TelegramBot.pm 50_TelegramBot.pm]
* Beiträge zu Somfy
** Somfy in FHEMDuino (Perl und C)
** 10_Somfy_PM - Umbau positionsbehandlung
* Beiträge zu FHEM Tablet UI

== FHEMWiki ==

;Bisher nur wenig

* [[TelegramBot]]
* [[Telegram]]

 
 
;Was hätte mir geholfen und würde ich gerne schreiben
* Beschreibung der Perlfunktionen für Developer
** dev2array
** Log3
** AttrVal
* Umgang mit timestamps und Zeitberechnungen

== Projekte und Ideen ==

* Infrarot-Modul als Homematic Aktor (Selbstbau Arduino Nano / Funkmodul-RFM12B? / IR-LEDs

* Klingeltaster-Modul mit RGB-LEDs und Arduino+Funk

* grösseres (10 Zoll ?) Tablet als zentrale Bedienungskonsole

* Quadcopter-Steuerung aus FHEM - Nein natürlich nicht, wofür auch?

TelegramBot

2015-10-27T20:36:16Z

Viegener: forum#msg350873

TelegramBot

2015-10-22T18:50:25Z

Viegener:

TelegramBot

2015-10-19T13:27:09Z

Viegener: Modul offiziell und verfügbar über SVN

TelegramBot

2015-10-12T21:00:23Z

Viegener: Tipps hinzugefügt

{{Infobox Modul
|ModPurpose=Senden und Empfangen von Nachrichten (Text und Fotos) mit dem freien Messagingdienst Telegram
|ModType=x
|ModForumArea=Unterstützende Dienste
|ModFTopic=38328
|ModTechName=[https://github.com/viegener/Telegram-fhem/blob/master/50_TelegramBot.pm 50_TelegramBot.pm]
|ModOwner=[[Benutzer:Viegener|Viegener]] ({{Link2FU|12772|Forum}} / [[Benutzer Diskussion:Viegener|Wiki]])}}

Das [[TelegramBot]]-Modul ermöglicht das Senden und Empfangen von Nachrichten über den Telegram-instant messaging Dienst (https://telegram.org/).
Es entsteht eine Möglichkeit Benachrichtungen aus Fhem zu versenden, zum Beispiel Alarmmeldungen.
Ausserdem können auch Kommandos über Telegram an Fhem gesendet werden um Steuerungsbefehle in Fhem auszulösen.

Das TelegramBot-Modul benötigt keine Zusatzsoftware auf dem Fhem-Server (anders als die Variante [[Telegram]]), sondern verwendet das [https://core.telegram.org/bots/api TelegramBot-API] über https-Aufrufe.

Für die Unterstützung von ''WhatsApp'' siehe Modul [[yowsup]].

== Über Telegram Instant Messaging ==
Telegram-IDs und Versand/Empfang von Nachrichten sind kostenfrei.
Clients sind für gängige Smartphonesysteme erhältlich (iOS iPhone und Tablet, Android, Windows Phone) und
können auch aus dem WebBrowser verwendet werden.
Es gibt auch einen Kommandozeilen-Client für Linux, der die Grundlage dieses Moduls darstellt.
Mehrfachanmeldungen, auch parallel mit verschiedenen Geräten (z.B. Tablet und Smartphone), sind möglich.
Gruppenchats und Chats mit End-2-End-Verschlüsselung werden ebenfalls unterstützt.

== Features ==
Unterstützt werden:

* Versand von Textnachrichten
* Versand von Bildern
* Empfang von Textnachrichten von beliebigen Kontakten
* Kommandos in Fhem über telegram-Nachrichten von aussen auslösen

Eine detaillierte Beschreibung des Moduls ist im Fhem Forum und in der (englischen) Dokumentation zum Modul in diesem {{Link2Forum|Topic=38328|LinkText=Diskussionsthread}} zu finden, die jeweils aktuelle Version des Moduls ist im ersten Beitrag als Anhang verfügbar.

== Hinweise zum Betrieb mit Fhem ==
{{Randnotiz|RNTyp=Warn|RNText=Achtung: Dieses Authtoken ist die einzige Authentifizierung für den Bot und sollte deshalb nicht aus der Hand gegeben werden. Die verwendeten Urls sind deshalb auch in den Log-Files nicht enthalten, da diese das Authtoken in Klartext enthalten. Auch im Forum sollte dieses Token nicht aufgenommen werden.
}}

Für die Anlage eines TelegramBot Devices in Fhem ist ein Authtoken erforderlich. Dieses Token wird über Anlegen eines neuen Bots im [https://core.telegram.org/bots#botfather Botfather] erzeugt. Die Namen für Bots müssen auf "Bot" enden.

Das Anlegen eines TelegramBot devices erfolgt durch die Angabe dieses Tokens:

<code>define <name> TelegramBot <token> </code>

Beispiel: <code>define teleBot TelegramBot 110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw</code>

'''Das Empfangen von Nachrichten (polling) erfordert die Einstellung des Attributes'''
<code>pollingTimeout</code> '''auf einen Wert der grösser als Null ist. Beim Wert 0 oder ohne Setzen des Attributes findet kein Polling und damit auch kein Empfang statt.'''

'''Der TelegramBot kann erst dann Nachrichten an einen telegram user schicken, wenn dieser zuerst an den telegram bot eine Nachricht gesendet hat.'''

== Tipps ==

=== Privacyeinstellungen ===

Damit der TelegramBot auch Meldungen in Gruppen sieht, müssen über den botfather die prviacy-Einstellungen geändert werden.

=== Kontakte ===

Der Bot merkt sich die bereits bekannten Kontakte im Reading <code>Contacts</code>. Dabei werden die einzelnen Kontakte jeweils als 3-teilige Einträge bestehend aus userid, Vor- und Nachname des Benutzers (mit _ verbunden) und dem usernamen (mit vorangestelltem @).

Beispiel: <code>123456:Ralf_Mustermann:@ralf</code>

Verschiedene Einträge werden durch Leerzeichen getrennt.

Man kann die Kontakte auch manuell überschreiben (z.B. wenn das Reading fehlerhaft oder verloren sein sollte). Dazu gibt es den Set-Befehl <code>replaceContacts</code>. Dieser nimmt die Kontakte ebenfalls in der gleichen Form wie oben beschrieben entgegen.

=== Reset ===

Es ist möglich den Bot im laufenden Betrieb zurückzusetzen (Set-Befehl <code>reset</code>). Dabei werden noch nicht abgeschlossene Übetragungen entfernt und die internen Zustände des devices zurückgesetzt.

== Beispielszenarien ==

=== Benachrichtigungen über Ereignisse ===

Das einfachste Szenario für die Integration von Messaging-Diensten mit Fhem ist zur Benachrichtigung über Ereignisse. Diese Funktion kann zum Beispiel verwendet werden, um über einen erfolgten Neustart von Fhem zu informieren:

<code>define notify_fhem_reload notify global:INITIALIZED set telebotdevice message fhem newly started - just now !</code>

In diesem Beispiel wird der Nachrichtentext "fhem newly started - just now !" an den als default eingestellten Kontakt (Attribut: defaultPeer) gesendet, sobald Fhem neu gestartet wurde. Natürlich kann man auch beliebige andere Benachrichtigungen einführen.

=== Versand von Bildern ===

Es ist auch möglich Bilder auf dem Fhem-Server, die zum Beispiel von einer Kamera oder einem Wettermodul stammen über Telegram zu versenden. So wäre es z.B. möglich jeweils morgens die aktuelle Wetterkarte zu erhalten.

ACHTUNG: TelegramBot verwendet das HTTPUtils-Modul zur Kommunikation mit dem TelegramBot-API. Das aktuelle HTTPUtils-Modul (Stand Oktober 2015) kann noch keine grossen Dateimengen übertragen, so dass momentan nur Bilder bis zu einer Grösse von etwa 14KB versendet werden können (Plattformspezifische Grenze). Detaillierte Infos finden sich im Forum {{Link2Forum|Topic=41583|LinkText=Fhem-Forum}}.
Es gibt dazu ein modifiziertes HTTPUtils-Modul, dass diese Beschränkung aufhebt und auch grosse Dateien übertragen kann.

<code>define notify_fhem_reload notify wetter:report set telebotdevice sendPhoto /opt/fhem/wetter.jpg</code>

Bei Erreichen des entsprechenden Status am wetter-Modul wird ein Image über telegram versendet. Hier sind lokale Pfade (relativ zu fhem) oder absolute Pfade wie oben möglich.

=== Kommandos auslösen ===

Ein wichtiges Szenario ist die Möglichkeit Kommandos in Fhem ausführen zu können, ohne einen Zugang durch die Firewall einrichten zu müssen. Dazu ist die Definition eines Schlüsselwortes (Attribut: "cmdKeyword")erforderlich, mit dem man die Nachrichten beginnen muss, damit der TelegramBot die Kommandos erkennt.

<code>attr telebotdevice cmdKeyword doit</code>

Somit kann man dann durch Nachrichten die mit "doit" beginnen Kommandos an Fhem senden, die ähnlich wie im Kommandoeingabefeld von Fhemweb dann von Fhem ausgeführt werden. Das Ergebnis der Ausführung wird zurück an den Sender (und an den definierten defaultPeer) geschickt.

Somit können nicht nur Aktionen angestossen werden, sondern auch Infos abgefragt werden.

Beispiele

<code>dofhem set schalter on</code>

<code>dofhem list telegrambot</code>

{{Randnotiz|RNTyp=Warn|RNText=Achtung: Bei den Kommandos sollten man unbedingt das Attribut "cmdRestrictedPeer" setzen, damit nicht jeder Kommandos auf dem Fhem-Server ausführen kann. Dazu sollten die Benutzerids der erlaubten Benutzer (durch Leerzeichen getrennt angeben). Da Benutzernamen selber vergeben werden und nicht unbedingt eindeutig sind, sollten hier auch NUR Benutzerids verwendet werden.
}}

=== Favoriten für Kommandos anlegen ===

Grundidee bei den Favoriten ist, dass man lange Befehle, die man haeufig braucht auf "Kurzwahl" legt.

Beispiel-Kommandos wie z.B. <code>set TYPE=ROLLADEN pos 100</code> und <code>set TYPE=ROLLADEN pos 0</code>, die man immer wieder braucht. Um nicht jedesmal dieses Kommando eintippen zu müssen auf dem Smartphone, kann man auch dafür Favoriten anlegen.

Dazu gibt man erstmal die beiden Kommandos getrennt durch Semikolon im Attribut favorites an:

<code>attr telegrambotdevice favorites set TYPE=ROLLADEN pos 100;set TYPE=ROLLADEN pos 0</code>

Um die Favorites jetzt ausführen zu können braucht man noch ein Schlüsselwort dafür.
Nehhmen wir mal an man möchte die Favoriten mit <code>/short</code> ausführen können. Dazu muss dann das Attribut "cmdFavorites" setzen

<code>attr telegrambotdevice cmdFavorites /short</code>

Wenn man nun im Telegram Client
<code>/short 1</code> an den Bot schickt führt der Bot den ersten Favoriten aus und das Ergebnis der Ausführung wird zurückgeschickt.

Ausserdem kann man im Telegram Client
<code>/short</code> an den Bot schicken, dann antwortet der Bot mit

<pre>
Favorites

1
set TYPE=ROLLADEN pos 100
2
set TYPE=ROLLADEN pos 0

</pre>

== Links ==
* Github Repository für die Telegram-Fhem Entwicklung: https://github.com/viegener/Telegram-fhem
* Infos zum Telegram Botfather: https://core.telegram.org/bots#botfather

* Source code für das 50_TelegramBot.pm-Modul: https://github.com/viegener/Telegram-fhem/blob/master/50_TelegramBot.pm
* Source code für das modifizierte HTTPUtils-Modul zur Übertragung grosser Bilder: https://github.com/viegener/Telegram-fhem/blob/master/HttpUtils.pm

* Forum-Thread in dem das Modul vorgestellt wurde {{Link2Forum|Topic=38328|LinkText=Fhem-Forum}}
* Telegram messaging system https://telegram.org/
* TelegramBot API https://core.telegram.org/bots/api

--[[Benutzer:Viegener|Viegener]] ([[Benutzer Diskussion:Viegener|Diskussion]]) 22:49, 11. Okt. 2015 (CEST)

TelegramBot

2015-10-11T20:49:50Z

Viegener: Erste Version zum telegramBot Modul

{{Infobox Modul
|ModPurpose=Senden und Empfangen von Nachrichten (Text und Fotos) mit dem freien Messagingdienst Telegram
|ModType=x
|ModForumArea=Unterstützende Dienste
|ModFTopic=38328
|ModTechName=[https://github.com/viegener/Telegram-fhem/blob/master/50_TelegramBot.pm 50_TelegramBot.pm]
|ModOwner=[[Benutzer:Viegener|Viegener]] ({{Link2FU|12772|Forum}} / [[Benutzer Diskussion:Viegener|Wiki]])}}

Das [[TelegramBot]]-Modul ermöglicht das Senden und Empfangen von Nachrichten über den Telegram-instant messaging Dienst (https://telegram.org/).
Es entsteht eine Möglichkeit Benachrichtungen aus Fhem zu versenden, zum Beispiel Alarmmeldungen.
Ausserdem können auch Kommandos über Telegram an Fhem gesendet werden um Steuerungsbefehle in Fhem auszulösen.

Das TelegramBot-Modul benötigt keine Zusatzsoftware auf dem Fhem-Server (anders als die Variante [[Telegram]]), sondern verwendet das [https://core.telegram.org/bots/api TelegramBot-API] über https-Aufrufe.

Für die Unterstützung von ''WhatsApp'' siehe Modul [[yowsup]].

== Über Telegram Instant Messaging ==
Telegram-IDs und Versand/Empfang von Nachrichten sind kostenfrei.
Clients sind für gängige Smartphonesysteme erhältlich (iOS iPhone und Tablet, Android, Windows Phone) und
können auch aus dem WebBrowser verwendet werden.
Es gibt auch einen Kommandozeilen-Client für Linux, der die Grundlage dieses Moduls darstellt.
Mehrfachanmeldungen, auch parallel mit verschiedenen Geräten (z.B. Tablet und Smartphone), sind möglich.
Gruppenchats und Chats mit End-2-End-Verschlüsselung werden ebenfalls unterstützt.

== Features ==
Unterstützt werden:

* Versand von Textnachrichten
* Versand von Bildern
* Empfang von Textnachrichten von beliebigen Kontakten
* Kommandos in Fhem über telegram-Nachrichten von aussen auslösen

Eine detaillierte Beschreibung des Moduls ist im Fhem Forum und in der (englischen) Dokumentation zum Modul in diesem {{Link2Forum|Topic=38328|LinkText=Diskussionsthread}} zu finden, die jeweils aktuelle Version des Moduls ist im ersten Beitrag als Anhang verfügbar.

== Hinweise zum Betrieb mit Fhem ==
Für die Anlage eines TelegramBot Devices in Fhem ist ein Authtoken erforderlich. Dieses Token wird über Anlegen eines neuen Bots im [https://core.telegram.org/bots#botfather Botfather] erzeugt. Die Namen für Bots müssen auf "Bot" enden.

{{Randnotiz|RNTyp=Warn|RNText=Achtung: Dieses Authtoken ist die einzige Authentifizierung für den Bot und sollte deshalb nicht aus der Hand gegeben werden. Die verwendeten Urls sind deshalb auch in den Log-Files nicht enthalten, da diese das Authtoken in Klartext enthalten. Auch im Forum sollte dieses Token nicht aufgenommen werden.
}}

Der telegram Bot kann erst dann Nachrichten an einen telegram user schicken, wenn dieser zuerst an den telegram bot eine Nachricht gesendet hat.

Damit der telegram bot auch Meldungen in Gruppen sieht, müssen über den botfather die prviacy-Einstellungen geändert werden.

== Beispielszenarien ==

=== Benachrichtigungen über Ereignisse ===

Das einfachste Szenario für die Integration von Messaging-Diensten mit Fhem ist zur Benachrichtigung über Ereignisse. Diese Funktion kann zum Beispiel verwendet werden, um über einen erfolgten Neustart von Fhem zu informieren:

<code>define notify_fhem_reload notify global:INITIALIZED set telebotdevice message fhem newly started - just now !</code>

In diesem Beispiel wird der Nachrichtentext "fhem newly started - just now !" an den als default eingestellten Kontakt (Attribut: defaultPeer) gesendet, sobald Fhem neu gestartet wurde. Natürlich kann man auch beliebige andere Benachrichtigungen einführen.

=== Versand von Bildern ===

Es ist auch möglich Bilder auf dem Fhem-Server, die zum Beispiel von einer Kamera oder einem Wettermodul stammen über Telegram zu versenden. So wäre es z.B. möglich jeweils morgens die aktuelle Wetterkarte zu erhalten.

ACHTUNG: TelegramBot verwendet das HTTPUtils-Modul zur Kommunikation mit dem TelegramBot-API. Das aktuelle HTTPUtils-Modul (Stand Oktober 2015) kann noch keine grossen Dateimengen übertragen, so dass momentan nur Bilder bis zu einer Grösse von etwa 14KB versendet werden können (Plattformspezifische Grenze). Detaillierte Infos finden sich im Forum {{Link2Forum|Topic=41583|LinkText=Fhem-Forum}}.
Es gibt dazu ein modifiziertes HTTPUtils-Modul, dass diese Beschränkung aufhebt und auch grosse Dateien übertragen kann.

<code>define notify_fhem_reload notify wetter:report set telebotdevice sendPhoto /opt/fhem/wetter.jpg</code>

Bei Erreichen des entsprechenden Status am wetter-Modul wird ein Image über telegram versendet. Hier sind lokale Pfade (relativ zu fhem) oder absolute Pfade wie oben möglich.

=== Kommandos auslösen ===

Ein wichtiges Szenario ist die Möglichkeit Kommandos in Fhem ausführen zu können, ohne einen Zugang durch die Firewall einrichten zu müssen. Dazu ist die Definition eines Schlüsselwortes (Attribut: "cmdKeyword")erforderlich, mit dem man die Nachrichten beginnen muss, damit der TelegramBot die Kommandos erkennt.

<code>attr telebotdevice cmdKeyword doit</code>

Somit kann man dann durch Nachrichten die mit "doit" beginnen Kommandos an Fhem senden, die ähnlich wie im Kommandoeingabefeld von Fhemweb dann von Fhem ausgeführt werden. Das Ergebnis der Ausführung wird zurück an den Sender (und an den definierten defaultPeer) geschickt.

Somit können nicht nur Aktionen angestossen werden, sondern auch Infos abgefragt werden.

Beispiele

<code>dofhem set schalter on</code>

<code>dofhem list telegrambot</code>

{{Randnotiz|RNTyp=Warn|RNText=Achtung: Bei den Kommandos sollten man unbedingt das Attribut "cmdRestrictedPeer" setzen, damit nicht jeder Kommandos auf dem Fhem-Server ausführen kann. Dazu sollten die Benutzerids der erlaubten Benutzer (durch Leerzeichen getrennt angeben). Da Benutzernamen selber vergeben werden und nicht unbedingt eindeutig sind, sollten hier auch NUR Benutzerids verwendet werden.
}}

=== Favoriten für Kommandos anlegen ===

Grundidee bei den Favoriten ist, dass man lange Befehle, die man haeufig braucht auf "Kurzwahl" legt.

Beispiel-Kommandos wie z.B. <code>set TYPE=ROLLADEN pos 100</code> und <code>set TYPE=ROLLADEN pos 0</code>, die man immer wieder braucht. Um nicht jedesmal dieses Kommando eintippen zu müssen auf dem Smartphone, kann man auch dafür Favoriten anlegen.

Dazu gibt man erstmal die beiden Kommandos getrennt durch Semikolon im Attribut favorites an:

<code>attr telegrambotdevice favorites set TYPE=ROLLADEN pos 100;set TYPE=ROLLADEN pos 0</code>

Um die Favorites jetzt ausführen zu können braucht man noch ein Schlüsselwort dafür.
Nehhmen wir mal an man möchte die Favoriten mit <code>/short</code> ausführen können. Dazu muss dann das Attribut "cmdFavorites" setzen

<code>attr telegrambotdevice cmdFavorites /short</code>

Wenn man nun im Telegram Client
<code>/short 1</code> an den Bot schickt führt der Bot den ersten Favoriten aus und das Ergebnis der Ausführung wird zurückgeschickt.

Ausserdem kann man im Telegram Client
<code>/short</code> an den Bot schicken, dann antwortet der Bot mit

<pre>
Favorites

1
set TYPE=ROLLADEN pos 100
2
set TYPE=ROLLADEN pos 0

</pre>

== Links ==
* Github Repository für die Telegram-Fhem Entwicklung: https://github.com/viegener/Telegram-fhem
* Infos zum Telegram Botfather: https://core.telegram.org/bots#botfather

* Source code für das 50_TelegramBot.pm-Modul: https://github.com/viegener/Telegram-fhem/blob/master/50_TelegramBot.pm
* Source code für das modifizierte HTTPUtils-Modul zur Übertragung grosser Bilder: https://github.com/viegener/Telegram-fhem/blob/master/HttpUtils.pm

* Forum-Thread in dem das Modul vorgestellt wurde {{Link2Forum|Topic=38328|LinkText=Fhem-Forum}}
* Telegram messaging system https://telegram.org/
* TelegramBot API https://core.telegram.org/bots/api

--[[Benutzer:Viegener|Viegener]] ([[Benutzer Diskussion:Viegener|Diskussion]]) 22:49, 11. Okt. 2015 (CEST)

Benutzer:Viegener

2015-10-11T18:46:33Z

Viegener:

; Erstmal nur ein Überblick über meine FHEM-Beteiligung

== FHEM Benutzung ==

Wunsch war die Zusammenführung der verschiedenen Funksysteme in einem zentralen System.
Ausdrücklich mit den Zielen
* Übergreifende Steuerungen und Makros zu ermöglichen
* Zentrale Bedienungsterminals (tablet)
* Steuerung von Aussen
* Am wichtigsten natürlich Spass am Basteln und Programmieren!!!

 
;Komponenten
* Somfy RTS Rolläden (Aktoren und Handfernbedienungen)
* FS20 Steckdosen
* Thermo/Hygro-Sensoren von LaCrosse und Technoline
* Mehrere Sonos-Komponenten
* Fritzbox
* Neu: Homematic
* Loewe Fernseher (dafür gibt es noch nichts)

 
;Mein FHEM habe ich im Februar 2015 installiert.
* 03/2015 Umzug Raspberry Pi2
* 04/2015 Somfy-Einbindung
* 05/2015 FHEM Tablet UI
* 06/2015 Entwicklung eines Telegram Moduls für Benachrichtigungen und Kommandos (also bidirektional)
** Telegram ist frei, plattformübergreifend und erlaubt Gruppenchats
* 09/2015 Variante der Telegram-Anbindung mit dem TelegramBot-Modul 50_TelegramBot

== FHEM Development ==

Aber klar, das macht ja den Spass aus. Gerne in C, C++, Perl, Java, Javascript und vielen anderen, die heute nicht mehr relevant sind
Wenns sein muss auch in CSS, HTML etc

* [https://github.com/viegener/Telegram-fhem/blob/master/70_Telegram.pm 70_Telegram.pm]
* [https://github.com/viegener/Telegram-fhem/blob/master/50_TelegramBot.pm 50_TelegramBot.pm]
* Beiträge zu Somfy
** Somfy in FHEMDuino (Perl und C)
** 10_Somfy_PM - Umbau positionsbehandlung
* Beiträge zu FHEM Tablet UI

== FHEMWiki ==

;Bisher nur wenig

* [[Telegram]]

 
 
;Was hätte mir geholfen und würde ich gerne schreiben
* Beschreibung der Perlfunktionen für Developer
** dev2array
** Log3
** AttrVal
* Umgang mit timestamps und Zeitberechnungen

== Projekte und Ideen ==

* Infrarot-Modul als Homematic Aktor (Selbstbau Arduino Nano / Funkmodul-RFM12B? / IR-LEDs

* Klingeltaster-Modul mit RGB-LEDs und Arduino+Funk

* grösseres (10 Zoll ?) Tablet als zentrale Bedienungskonsole

* Quadcopter-Steuerung aus FHEM - Nein natürlich nicht, wofür auch?

HttpUtils

2015-09-28T10:55:51Z

Viegener: HttpUtils_Close hinzugefügt

{{Infobox Modul
|ModPurpose=Hilfsfunktionen für HTTP-Zugriffe
|ModType=h
|ModForumArea=Automatisierung
|ModTechName=HttpUtils.pm
|ModOwner=rudolfkoenig ({{Link2FU|8|Forum}} / [[Benutzer Diskussion:Rudolfkoenig|Wiki]])
}}

Das Modul [[HttpUtils]](.pm) ist sowohl für Modulentwickler, als auch Endanwender gedacht um Daten via HTTP auszutauschen. Es stellt dabei eine Reihe von Funktionen zur Verfügung und wird beispielsweise vom Modul [[HTTPMOD]] intensiv genutzt.

== Funktionen ==
Es ist zu beachten, dass bei den Funktionen
* GetHttpFile
* GetFileFromURL
* GetFileFromURLQuiet
* HttpUtils_BlockingGet
ein sogenannter "blockierender" Aufruf durchgeführt wird. Das bedeutet, dass FHEM bei einem Aufruf einer dieser Funktionen solange wartet und dabei absolut nichts macht, bis die Antwort vom HTTP-Server eintrifft und die Funktion damit beendet ist. Das kann bei Verbindungsproblemen evtl. dazu führen, dass FHEM für die gesamte Wartezeit (Timeout) steht und nichts verarbeitet. Problematisch ist das gerade bei Anwendungen oder Hardware, die eine zeitnahe Reaktion von FHEM erwarten (z.B. HomeMatic-Geräte).

Es wird daher empfohlen, die Funktionen so sparsam wie möglich zu verwenden und die Timeouts so niedrig wie möglich zu halten, um ein längeres Einfrieren von FHEM möglichst zu vermeiden.

Alternativ kann die Funktion
:<code>HttpUtils_NonblockingGet</code>
verwendet werden, welche ein Blockieren von FHEM verhindert. Wie das genau funktioniert, wird in dem entsprechenden Kapitel beschrieben.

Die im Folgenden beschriebenen Funktionen sind für Modulentwickler/Endanwender zur direkten Nutzung gedacht.

=== GetHttpFile ===
Die Funktion GetHttpFile ist die denkbar einfachste Variante um eine URL aufzurufen.
:<code>GetHttpFile($server, $file)</code>
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$server</code>'''

''mandatory''
|| Der DNS-Name oder die IP-Adresse des HTTP-Servers 
Beispiel:

* ''<nowiki>www.myhost.com</nowiki>''
* ''<nowiki>192.168.0.10</nowiki>''
|-
| style="vertical-align:top" | '''<code>$file</code>'''

''mandatory''
|| Die Datei, welche auf dem HTTP-Server aufgerufen werden soll. 
Beispiel:
* ''/''
* ''/index.html''
* ''/directory/image.jpg''
|}

Funktionsergebnis ist der Inhalt der aufgerufenen Seite in Form einer Zeichenkette.

=== GetFileFromURL ===
Die Funktion GetFileFromURL ruft die HTTP-URL auf und gibt als Funktionsergebnis den Seiteninhalt zurück. Im Gegensatz zu GetHttpFile beinhaltet GetFileFromURL einige Zusatzoptionen in Form von Funktionsparametern.

'''Aufruf: <code>GetFileFromURL($url, ''[$timeout], [$data], [$noshutdown], [$loglevel]'')</code>'''

{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$url</code>'''

''mandatory''
|| Die HTTP-URL, welche aufgerufen werden soll. Diese kann optional Usernamen, Passwort und einen Port enthalten. Sowohl HTTP als auch HTTPS wird hierbei unterstützt. 
Beispiel:

* ''<nowiki>http://www.myhost.com/directory/</nowiki>''
* ''<nowiki>https://www.myhost.com/</nowiki>''
* ''<nowiki>http://www.myhost.com:8080/</nowiki>''
* ''<nowiki>http://foo:bar@www.myhost.com/</nowiki>''
|-
| style="vertical-align:top" | '''<code>$timeout</code>'''

''optional''
|| Die maximale Dauer in Sekunden für die HTTP-Anfrage

Beispiel: 5 ''(Sekunden)''

Standardwert: 4 Sekunden
|-
| style="vertical-align:top" | '''<code>$data</code>'''

''optional''
|| Wenn man Daten via HTTP-POST übertragen möchte, so kann man die Nutzdaten über $data übergeben. Die Daten werden dabei als Formulardaten übertragen. Wenn man den Content-Type beeinflussen oder mehrere Formular-Felder senden möchte, sollte man zur Funktion HttpUtils_BlockingGet oder HttpUtils_NonblockingGet greifen.

Standardwert: ''[leer]''

|-
| style="vertical-align:top" | '''<code>$noshutdown</code>'''

''optional''
|| Wenn $noshutdown auf 1 gesetzt ist, wird dem HTTP-Server nicht implizit mitgeteilt, dass die Verbindung nach dem Request geschlossen werden soll. Viele Webserver schließen in solch einem Fall die Verbindung bevor sie die Antwort senden. Bei 0 wird dem Webserver mitgeteilt, dass der Sendevorgang beendet ist und nun die Antwort abgewartet wird.

Standardwert: 1
|-
| style="vertical-align:top" | '''<code>$loglevel</code>'''

''optional''
|| Das Logleve, in dem sämtliche Logmeldungen zu dieser HTTP-Abfrage erzeugt werden sollen.

Standardwert: 4
|}

Funktionsergebnis ist der Inhalt der aufgerufenen Seite in Form eines Strings.

=== GetFileFromURLQuiet ===

Diese Funktion funktioniert ähnlich wie GetFileFromURL. Allerdings wird die tatsächliche URL in allen erzeugten Log-Meldungen unkenntlich gemacht um z.B. Zugangsdaten nicht preiszugeben. Die aufgerufene Seite wird ebenfalls als Funktionsergebnis zurückgegeben.

'''Aufruf: <code>GetFileFromURLQuiet($url, ''[$timeout], [$data], [$noshutdown], [$loglevel]'')</code>'''

{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$url</code>'''

''mandatory''
|| Die HTTP-URL, welche aufgerufen werden soll. Diese kann optional Usernamen, Passwort und einen Port enthalten. Sowohl HTTP als auch HTTPS wird hierbei unterstützt. 
Beispiel:

* ''<nowiki>http://www.myhost.com/directory/</nowiki>''
* ''<nowiki>https://www.myhost.com/</nowiki>''
* ''<nowiki>http://www.myhost.com:8080/</nowiki>''
* ''<nowiki>http://foo:bar@www.myhost.com/</nowiki>''
|-
| style="vertical-align:top" | '''<code>$timeout</code>'''

''optional''
|| Die maximale Dauer in Sekunden für die HTTP-Anfrage

Beispiel: 5 ''(Sekunden)''

Standardwert: 4 Sekunden
|-
| style="vertical-align:top" | '''<code>$data</code>'''

''optional''
|| Wenn man Daten via HTTP-POST übertragen möchte, so kann man die Nutzdaten über <code>$data</code> übergeben. Die Daten werden dabei als Formulardaten übertragen. Wenn man den Content-Type beeinflussen möchte, oder mehrere Formular-Felder senden möchte, sollte man zur Funktion HttpUtils_BlockingGet oder HttpUtils_NonblockingGet greifen.

Standardwert: ''[leer]''

|-
| style="vertical-align:top" | '''<code>$noshutdown</code>'''

''optional''
|| Wenn $noshutdown auf 1 gesetzt ist, wird dem HTTP-Server nicht implizit mitgeteilt, dass die Verbindung nach dem Request geschlossen werden soll. Viele Webserver schließen in solch einem Fall die Verbindung bevor sie die Antwort senden. Bei 0 wird dem Webserver mitgeteilt, dass der Sendevorgang beendet ist und nun die Antwort abgewartet wird.

Standardwert: 1
|-
| style="vertical-align:top" | '''<code>$loglevel</code>'''

''optional''
|| Das Loglevel, in dem sämtliche Logmeldungen zu dieser HTTP-Abfrage erzeugt werden sollen.

Standardwert: 4
|}

Funktionsergebnis ist der Inhalt der aufgerufenen Seite in Form eines Strings.

=== HttpUtils_BlockingGet ===

Wenn die bisher genannten Funktionen nicht ausreichen um die gewünschte Abfrage durchzuführen, so kann man diese Funktion verwenden. Aufgrund zahlreicher Parameter ermöglicht sie viele Anpassungsmöglichkeiten. Diese Funktion hat dabei nicht wie üblich eine Liste an Funktionsparametern, sondern lediglich einen Parameter, welcher ein Hash mit allen Funktionsparametern darstellt. Dieser Hash enthält sämtliche Parameter inkl. Werten.

'''Aufruf: <code>HttpUtils_BlockingGet($param)</code>'''

Der Parameter $param ist eine Referenz auf eine Hash-Struktur, welche die einzelnen Parameter enthält. Der Hash $param kann folgende Optionen beinhalten:

{| class="wikitable"
|-
! style="width:175px" | Parameter !! style="width:auto" | Bedeutung
|-
| style="vertical-align:top" | '''<code>$param->{url}</code>'''

''mandatory''
|| Die HTTP-URL, welche aufgerufen werden soll. Diese kann optional Usernamen, Passwort und einen Port enthalten. Sowohl HTTP als auch HTTPS wird hierbei unterstützt. 
Beispiel:

* ''<nowiki>http://www.myhost.com/directory/</nowiki>''
* ''<nowiki>https://www.myhost.com/</nowiki>''
* ''<nowiki>http://www.myhost.com:8080/</nowiki>''
* ''<nowiki>http://foo:bar@www.myhost.com/</nowiki>''

|-
| style="vertical-align:top" |'''<code>$param->{timeout}</code>'''

''optional''
|| Die maximale Dauer in Sekunden für die HTTP-Anfrage

Beispiel: 5 ''(Sekunden)''

Standardwert: 4 Sekunden
|-
| style="vertical-align:top" |'''<code>$param->{data}</code>'''

''optional''
|| Wenn man Daten via HTTP-POST übertragen möchte, so kann man die Nutzdaten über <code>$param->{data}</code> übergeben. Die Daten werden dabei als Formulardaten übertragen. Die Daten können dabei auf zwei Arten übergeben werden:

1. Daten als String:
:* Die Daten werden komplett als gesamter String in <code>$param->{data}</code> abgelegt (z.B.: $param->{data} = "Jede Menge tolle Daten").
2. Daten als Hash:
:* Die Daten werden als Hash mit Key-Value-Pairs übergeben (z.B.: $param->{data}{field1} = "value1", $param{data}{field2} = "value2", ... ). Die Daten werden dann als Formulardaten mit mehrfachen Datenfeldern übertragen.

Standardwert: ''[leer]''

|-
| style="vertical-align:top" | '''<code>$param->{noshutdown}</code>'''

''optional''
||Wenn <code>$param->{noshutdown}</code> auf 1 gesetzt ist, wird dem HTTP-Server nicht implizit mitgeteilt, dass die Verbindung nach dem Request geschlossen werden soll. Viele Webserver schließen in solch einem Fall die Verbindung bevor sie die Antwort senden. Bei 0 wird dem Webserver mitgeteilt, dass der Sendevorgang beendet ist und nun die Antwort abgewartet wird.

Standardwert: 1
|-
| style="vertical-align:top" | '''<code>$param->{loglevel}</code>'''

''optional''
|| Das Loglevel, in dem sämtliche Logmeldungen zu dieser HTTP-Abfrage erzeugt werden sollen.

Standardwert: 4
|-
| style="vertical-align:top" | '''<code>$param->{hideurl}</code>'''

''optional''
|| Wenn dieser Parameter den Wert 1 trägt, wird die URL in sämtlichen Log-Ausgaben unkenntlich gemacht. Dies ist nützlich um z.B. Zugangsdaten geheim zu halten.

Standardwert: 0
|-
| style="vertical-align:top" | '''<code>$param->{ignoreredirects}</code>'''

''optional''
|| Wenn dieser Parameter den Wert 1 trägt, werden Umleitungen durch den Server ignoriert und der Request beendet. Dies kann erforderlich sein um evtl. Cookies aus der Antwort, welche eine Umleitung enthält aus dem HTTP Header zu extrahieren um diese im nächsten Request weiterzuverwenden.

Standardwert: 0
|-
| style="vertical-align:top" | '''<code>$param->{method}</code>'''

''optional''
||Die HTTP-Methode, welche zur Abfrage verwendet werden soll. Sofern keine Daten übertragen werden ist dies standardmäßig "GET", ansonsten "POST". Es können aber auch andere Methoden verwendet werden.

Standardwert: "GET"
|-
| style="vertical-align:top" | '''<code>$param->{header}</code>'''

''optional''
|| Eigene HTTP-Header-Zeilen können über diesen Parameter eingebracht werden. Er kann dazu genutzt werden um z.B. den Content-Type festzulegen, oder einfach nur zusätzliche Header-Felder zu setzen. Mehrere Header-Zeilen müssen dabei mit "\r\n" getrennt werden.

Beispiel:
* <code>User-Agent: Mozilla/1.22'''\r\n'''Content-Type: application/xml</code>
* <code>Content-Type: application/xml</code>

Standardwert: ''[leer]''
|-
| style="vertical-align:top" | '''<code>$param->{sslargs}</code>'''

''optional''
|| Eigene SSL-Optionen können über diesen Parameter eingebracht werden. Er kann dazu genutzt werden um z.B. die SSL-Zertifikats Verifikation abzuschalten. Die SSL-Optionen müssen als eigene Hash-Referenz übergeben werden. Eine Liste aller möglichen Optionen findet man in der Perl-Dokumentation zu [http://search.cpan.org/~sullr/IO-Socket-SSL-2.016/lib/IO/Socket/SSL.pod#Description_Of_Methods IO::Socket::SSL].

Beispiel:
* <code>$param->{sslargs} = { SSL_verify_mode => 'SSL_VERIFY_NONE', sslOpt2 => 'sslVal2' }</code>

Standardwert: ''{ }''
|-
| style="vertical-align:top" | '''<code>$param->{httpversion}</code>'''

''optional''
|| Die HTTP-Version, welche zur Abfrage verwendet werden soll. Standardmäßig werden alle Abfragen mit HTTP/1.0 durchgeführt. Falls es jedoch notwendig ist HTTP/1.1 zu verwenden, so sollte <code>$param->{httpversion}</code> auf "1.1" gesetzt werden. Bei Version 1.1 wird automatisch der Header "<code>Connection: close</code>" implizit mitgesendet.

Standardwert: "1.0"
|}

Als Rückgabewert von HttpUtils_BlockingGet wird ein Array mit 2 Rückgabewerten zurückgegeben:

($err, $data) = HttpUtils_BlockingGet( … )

Diese 2 Rückgabewerten haben folgende Bedeutung:

{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$err</code>'''|| Falls beim Aufruf der URL ein Fehler aufgetreten ist (z.B. Server nicht erreichbar oder Verbindungstimeout), dann ist dieser Wert mit einer Fehlermeldung gefüllt.

Wenn kein Fehler aufgetreten ist, ist dieser Wert mit einem Leerstring gefüllt (<code>$err = ""</code>)
|-
| style="vertical-align:top" | '''<code>$data</code>'''|| Die Ergebnisdaten, welche der HTTP-Server zurückgeliefert hat. Die Daten werden als Klartext in Form eines gesamten Strings zurückgegeben.

Falls ein Fehler aufgetreten ist, ist dieser Wert mit einem Leersting gefüllt (<code>$data = ""</code>)
|}

=== HttpUtils_NonblockingGet ===
{{Randnotiz|RNText=Die Funktion HttpUtils_NonblockingGet ist nicht komplett durchgehend "non-blocking". DNS-Abfragen sind nachwievor blockierend. Insbesondere wenn der DNS-Name nicht aufgelöst werden kann.}}
Diese Funktion arbeitet ähnlich wie HttpUtils_BlockingGet. Allerdings wird das Ergebnis nicht als Funktionsergebnis zurückgegeben. Die Funktion HttpUtils_NonblockingGet initiiert den Verbindungsaufbau und übergibt alles weitere an FHEM interne Routinen. Sobald eine Antwort vom HTTP-Server eintrifft, wird eine Callback-Funktion mit verschiedenen Parametern (unter anderem auch das Ergebnis) aufgerufen, um die Antwort entgegenzunehmen und weiter zu verarbeiten.

Der Aufruf ist daher ähnlich zu HttpUtils_BlockingGet mit nur einem Parameter-Hash:

'''Aufruf: <code>HttpUtils_NonblockingGet($param)</code>'''

{| class="wikitable"
|-
! style="width:175px" | Parameter !! style="width:auto" | Bedeutung
|-
| colspan="2" style="text-align:center" | ''''' Alle Hash-Parameter, welche für HttpUtils_BlockingGet gelten, sind auch für HttpUtils_NonblockingGet gültig''''' 
|-
| style="vertical-align:top" | '''<code>$param->{callback}</code>'''

''mandatory''
|| Eine Funktion (oder eine Referenz auf eine Funktion), welche die Ergebnisdaten entgegennimmt und die Antwort entsprechend weiterverarbeitet. Die Callback-Funktion muss dabei 3 Parameter erwarten. Die Funktionsparameter der Callback-Funktion werden im nachfolgenden Abschnitt näher erläutert.

Beispiel:
* <code>$param->{callback} = \&MyCallbackFn</code> — ''(Referenzzeiger auf Funktionsname)''
* <code>$param->{callback} = sub($$$){ … }</code> — ''(direkte Funktionsdefinition)''
|-
| style="vertical-align:top" | ''Benutzerdefinierte Parameter''
|| Es können im Hash weitere benutzerdefinierte Parameter gesetzt werden, welche evtl. in der Callback-Funktion benötigt werden, um die Antwort korrekt zu verarbeiten.

Zum Beispiel bei der Modul-Programmierung währe das $hash des aktuellen Devices. Alle gesetzten Parameter sind in der Callback-Funktion direkt abrufbar und können ausgewertet werden.

Beispiel:
* <code>$param->{hash} = $hash</code>
* <code>$param->{command} = "on"</code>

|}

Ein Funktionsrückgabewert von HttpUtils_NonblockingGet existiert nicht, da die eigentliche Rückgabe der Daten über die Callback-Funktion erfolgt. Die Callback-Funktion wird aufgerufen, sobdald der HTTP-Request abgeschlossen ist, oder ein Fehler aufgetreten ist. Der Funktionsaufruf erfolgt mit den folgenden Parametern:

<code> ''MyCallbackFn'' ( $param, $err, $data )</code>

Diese 3 Parameter haben dabei folgende Bedeutung:

{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$param</code>''' || Der Parameter-Hash, mit allen Argumenten die beim Aufruf der Funktion übergeben worden sind.

Es ist möglich, dass der Parameter-Hash nach erfolgter Abfrage zusätzliche oder veränderte Elemente enthält:
* '''<code>$param->{redirects}</code>''' - Die Anzahl an Umleitungen die erfolgte, bis die Anfrage beantwortet wurde.
* '''<code>$param->{url}</code>''' - Die URL, die nach erfolgter Umleitung die Anfrage beantwortet hat.
* '''<code>$param->{protocol}</code>''' - Das verwendete Protokoll, welches zur Abfrage verwendet wurde ("http" oder "https").
* '''<code>$param->{path}</code>''' - Der Pfad, welcher auf dem HTTP-Server angefragt wurde.
* '''<code>$param->{host}</code>''' - Der Name oder die IP-Adresse des HTTP-Servers.
* '''<code>$param->{httpheader}</code>''' - Der gesamte HTTP Header, welcher der Server bei der letzten Antwort zurücklieferte.
* '''<code>$param->{code}</code>''' - Der HTTP-Statuscode, mit dem die Anfrage vom Server beantwortet wurde.
* '''<code>$param->{addr}</code>''' - Die HTTP-URL ohne Pfad und evtl. Authentifizerungsinformationen des HTTP-Servers (z.B. "<nowiki>http://myserver.com:8080</nowiki>").
* '''<code>$param->{auth}</code>''' - Der Authentifizierungs-String, welcher verwendet wurde um sich gegenüber dem HTTP-Server zu authentifizieren (nur wenn Authentifizierung benutzt wurde).
|-
| style="vertical-align:top" | '''<code>$err</code>'''|| Falls beim Aufruf der URL ein Fehler aufgetreten ist (z.B. Server nicht erreichbar oder Verbindungstimeout), dann ist dieser Wert mit einer Fehlermeldung gefüllt.

Wenn kein Fehler aufgetreten ist, ist dieser Wert mit einem Leerstring gefüllt (<code>$err = ""</code>)
|-
| style="vertical-align:top" | '''<code>$data</code>'''|| Die Ergebnisdaten, welche der HTTP-Server zurückgeliefert hat. Die Daten werden als Klartext in Form eines gesamten Strings zurückgegeben. Es handelt sich hierbei ausschließlich um den HTTP-Body.

Falls ein Fehler aufgetreten ist, ist dieser Wert mit einem Leersting gefüllt (<code>$data = ""</code>)
|}

Die Callback-Funktion kann nun die Daten aus der HTTP-Antwort verarbeiten oder bei Fehler entsprechende Log-Meldungen ausgeben.

==== Beispiel für HttpUtils_NonblockingGet() für Modulprogrammierer ====

Das folgende Beispiel soll eine Hilfestellung für eigene Anwendungen geben

<pre>use HttpUtils;
sub X_GetHttpResponse($)
{
my ($hash, $def) = @_;
my $name = $hash->{NAME};
my $param = {
url => "http://www.foo.de",
timeout => 5,
hash => $hash, # Muss gesetzt werden, damit die Callback funktion wieder $hash hat
method => "GET", # Lesen von Inhalten
header => "agent: TeleHeater/2.2.3\r\nUser-Agent: TeleHeater/2.2.3\r\nAccept: application/json", # Den Header gemäss abzufragender Daten ändern
callback => \&X_ParseHttpResponse # Diese Funktion soll das Ergebnis dieser HTTP Anfrage bearbeiten
};

HttpUtils_NonblockingGet($param); # Starten der HTTP Abfrage. Es gibt keinen Return-Code.

}

sub X_ParseHttpResponse($)
{

my ($param, $err, $data) = @_;
my $hash = $param->{hash};
my $name = $hash->{NAME};

if($err ne "") # wenn ein Fehler bei der HTTP Abfrage aufgetreten ist
{
Log3 $name, 3, "error while requesting ".$param->{url}." - $err"; # Eintrag fürs Log
readingsSingleUpdate($hash, "fullResponse", "ERROR"); # Readings erzeugen
}

elsif($data ne "") # wenn die Abfrage erfolgreich war ($data enthält die Ergebnisdaten des HTTP Aufrufes)
{
Log3 $name, 3, "url ".$param->{url}." returned: $data"; # Eintrag fürs Log

# An dieser Stelle die Antwort parsen / verarbeiten mit $data

readingsSingleUpdate($hash, "fullResponse", $data); # Readings erzeugen
}

# Damit ist die Abfrage zuende.
# Evtl. einen InternalTimer neu schedulen
}</pre>

=== HttpUtils_Close ===

Für den Abbruch von offenen Verbindungen und noch laufenden NonBockingGet-Aufrufen gibt es die Funktion HttpUtils_Close. Diese kann z.B. beim Löschen eines Devices oder Herunterfahren des Servers aufgerufen werden, um bestehende Verbindungen zu schliessen.

'''Aufruf: <code>HttpUtils_Close($param)</code>'''

{| class="wikitable"
|-
! style="width:175px" | Parameter !! style="width:auto" | Bedeutung
|-
| style="vertical-align:top" | '''<code>$param</code>'''

''mandatory''
|| Der Hash, der beim vorherigen Aufruf an HTTPUtils Funktionen (HttpUtils_NonblockingGet oder HttpUtils_BlockingGet) übergeben wurde

|}

[[Kategorie:Development]]

Benutzer:Viegener

2015-07-21T22:00:47Z

Viegener: Meine Seite

; Erstmal nur ein Überblick über meine FHEM-Beteiligung

== FHEM Benutzung ==

Wunsch war die Zusammenführung der verschiedenen Funksysteme in einem zentralen System.
Ausdrücklich mit den Zielen
* Übergreifende Steuerungen und Makros zu ermöglichen
* Zentrale Bedienungsterminals (tablet)
* Steuerung von Aussen
* Am wichtigsten natürlich Spass am Basteln und Programmieren!!!

 
;Komponenten
* Somfy RTS Rolläden (Aktoren und Handfernbedienungen)
* FS20 Steckdosen
* Thermo/Hygro-Sensoren von LaCrosse und Technoline
* Mehrere Sonos-Komponenten
* Fritzbox
* Neu: Homematic
* Loewe Fernseher (dafür gibt es noch nichts)

 
;Mein FHEM habe ich im Februar 2015 installiert.
* 03/2015 Umzug Raspberry Pi2
* 04/2015 Somfy-Einbindung
* 05/2015 FHEM Tablet UI
* 06/2015 Entwicklung eines Telegram Moduls für Benachrichtigungen und Kommandos (also bidirektional)
** Telegram ist frei, plattformübergreifend und erlaubt Gruppenchats

== FHEM Development ==

Aber klar, das macht ja den Spass aus. Gerne in C, C++, Perl, Java, Javascript und vielen anderen, die heute nicht mehr relevant sind
Wenns sein muss auch in CSS, HTML etc

* [https://github.com/viegener/Telegram-fhem/blob/master/70_Telegram.pm 70_Telegram.pm]
* Beiträge zu Somfy
** Somfy in FHEMDuino (Perl und C)
** 10_Somfy_PM - Umbau positionsbehandlung
* Beiträge zu FHEM Tablet UI

== FHEMWiki ==

;Bisher nur wenig

* [[Telegram]]

 
 
;Was hätte mir geholfen und würde ich gerne schreiben
* Beschreibung der Perlfunktionen für Developer
** dev2array
** Log3
** AttrVal
* Umgang mit timestamps und Zeitberechnungen

== Projekte und Ideen ==

* Infrarot-Modul als Homematic Aktor (Selbstbau Arduino Nano / Funkmodul-RFM12B? / IR-LEDs

* Klingeltaster-Modul mit RGB-LEDs und Arduino+Funk

* grösseres (10 Zoll ?) Tablet als zentrale Bedienungskonsole

* Energieverbrauchsüberwachung auch als Warnung für angebliebene Geräte

* Quadcopter-Steuerung aus FHEM - Nein natürlich nicht, wofür auch?

== Sonstiges / Links ==

Fehlt noch

Telegram - old API method

2015-07-21T20:57:25Z

Viegener:

Telegram - old API method

2015-07-07T22:35:04Z

Viegener: Erste Version zum Telegram Modul

{{Infobox Modul
|ModPurpose=Senden und Empfangen von Nachrichten (Text und Fotos) mit dem freien Messagingdienst Telegram
|ModType=x
|ModCmdRef= ---- noch nicht Teil von FHEM ----
|ModForumArea=Unterstützende Dienste
|ModTechName=[https://github.com/viegener/Telegram-fhem/blob/master/70_Telegram.pm 70_Telegram.pm]
|ModOwner=viegener ([http://forum.fhem.de/index.php/topic,38328.0.html] / [[Benutzer Diskussion:Viegener|Wiki]])}}

Das [[Telegram]]-Modul ermöglicht das Senden und Empfangen von Nachrichten über den Telegram-instant messaging Dienst (https://telegram.org/).
Es entsteht eine Möglichkeit Benachrichtungen aus fhem zu versenden, zum Beispiel Alarmmeldungen.
Ausserdem können auch Kommandos über Telegram an fhem gesendet werden um Steuerungsbefehle in fhem auszulösen.

Für den Betrieb des Telegram Moduls ist eine funktionsfähige Installation des inoffiziellen telegram command-line clients für Linux telegram-cli (https://github.com/vysheng/tg) erforderlich

== Über Telegram Instant Messaging ==

Telegram-IDs und Versand/Empfang von Nachrichten ist kostenfrei.
Clients sind für gängige Smartphonesysteme erhältlich (iOS iPhone und Tablet, Android, Windows Phone) und
können auch aus dem WebBrowser verwendet werden.
Es gibt auch einen Kommandozeilen-Client für Linux, der die Grundlage dieses Moduls darstellt
Mehrfachanmeldungen auch parallel mit verschiedenen Geräten (z.B. tablet und smartphone) sind möglich.
Gruppenchats und Chats mit End-2-End-Verschlüsselung werden ebenfalls unterstützt.

== Features ==

Unterstützt werden

* Versand von Textnachrichten an einen vordefinierten Kontakt (default peer)
* Versand von Textnachrichten an einen vordefinierten Kontakt als verschlüsselter Chat (secret chat)
* Versand von Bildern
* Empfang von Textnachrichten von beliebigen Kontakten
* Direkte Befehle an den telegram-client

Eine detaillierte Beschreibung des Moduls ist in der Diskussion
Thread im {{Link2Forum|Topic=24519|LinkText=Fhem-Forum}} mit der jeweils aktuellen Version des Moduls als Anhang im ersten Beitrag.

== Hinweise zum Betrieb mit Fhem ==

Das Telegram-Modul basiert auf einem im Hintergrund laufenden telegram-cli (https://github.com/vysheng/tg)

Informationen zur Einrichtung und Betrieb von telegram-cli finden sich im Readme in obigem Repository.
Weitere Infos finden sich auch im wiki des github Repositories: https://github.com/vysheng/tg/wiki

Hinweise zum Start von telegram-cli mit fhem finden sich in der Commandref / Doku zum Modul.

{{Randnotiz|RNTyp=Info|RNText=Achtung: telegram-cli wird momentan NICHT aus fhem herausgestartet, sondern muss separat gestartet werden.
Ausserdem muss telegram-cli bereits angemeldet sein und entsprechende Kontakte müssen eingerichtet werden.
Generell ist auch die Verwendung einer existierenden telegram, empfohlen wird aber die Verwendung einer getrennten ID,
zum Beispiel für die eigene Festnetznummer.

telegram-cli kann generell auch auf einem anderen host betrieben werden, da die Kommunikation mit telegram-cli über Netzwerkprotokolle erfolgt.
}}

== Weblinks ==
* Source code für das 70_Telegram.pm-Modul : https://github.com/viegener/Telegram-fhem
* Forum-Thread in dem das Modul vorgestellt wurde {{Link2Forum|Topic=24519|LinkText=Fhem-Forum}}
* Repository mit telegram-cli https://github.com/vysheng/tg
* Telegram messaging system https://telegram.org/

[[Kategorie:Other Components]]