FHEMWiki - Benutzerbeiträge [de]

Ntfy

2026-01-22T17:19:56Z

Torxgewinde: Weitere Quelle von Byterazor gefunden, Hinweis entfernt

==📬 NTFY.sh: Push Nachrichten an iOS, Android, PC, Command-Line, E-Mail & Telefon==
[[Datei:NTFY Screenshot mit einem Bild.png|alternativtext=NTFY Screenshot mit einem Bild|mini|300x300px|NTFY Screenshot mit einem Bild]]
[https://NTFY.sh NTFY.sh] bietet Push-Dienste auf iOS, Android, Console, E-Mail, ja sogar als Anruf auf ein Telefon an. Es ist damit ähnlich zu dem, was man mit PushOver, PushBullet oder auch Gotify anstellen kann, wobei NTFY auch Kriterien wie "Self-hosted" und echte "iOS-Pushnachrichten" erfüllt. Man kann damit von FHEM aus alle diese Kanäle mit einer Push-Nachricht erreichen. Die Nutzung ist extrem einfach, man setzt einen HTTP-Aufruf ab, um eine Push-Nachricht zu versenden. NTFY.sh betreibt sogar einen Gratis-Server, den man nutzen darf. Man kann den Server auch selber hosten, wenn man will.

Öffnet testweise diesen Link, dort tauchen die Nachrichten auch in der PWA (Webapp) auf: https://ntfy.sh/FreundlichenGruesseAnAlleFHEMNutzer

<div style="color:#ffff00; background:#ff0000; border: solid 1px black">'''Wichtig:''' Nutzt man eine öffentliche Instanz ist das Topic so zu wählen, dass es wie ein Passwort funktioniert und schwer zu erraten ist. Wählt man ein einfaches Topic, können andere mitlesen und auch Nachrichten senden. Dies kann zu ungewollten Effekten führen!</div>

=== NTFY mit anderen Systemen nutzen/verbinden ===
Auch ganz ohne FHEM, also aus anderen Systemen, kann man an NTFY Nachrichten senden und empfangen. So kann man sich aus iOS zum Beispiel per Webhook etwas an NTFY senden, oder auch von IP-Kameras Infos an den NTFY Server senden und dann von den diversen Clients empfangen und verarbeiten.

==== Apps (iOS, Android und PWA) ====
Ganz wichtig für die meisten Nutzer ist natürlich der Empfang von NTFY Nachrichten mit:

* der Android-App ([https://play.google.com/store/apps/details?id=io.heckel.ntfy&pli=1 Playstore], [https://f-droid.org/en/packages/io.heckel.ntfy/ F-Droid]),
* der [https://apps.apple.com/us/app/ntfy/id1625396347 iOS-App] *, oder
* der [https://ntfy.sh/app PWA] (Progressive-Web-App)

'''Hinweis zur nativen iOS-App:''' [https://github.com/binwiederhier/ntfy/issues/1226 Zur Zeit] funktioniert die Anzeige von Anhängen unter iOS, iPadOS, MacOS '''nur''' über die Web-App (zu finden unter https://ntfy.sh/app). Um die PWA unter iOS/MacOS fast wie eine gewöhnliche App zu nutzen, kann man die Web-Seite an den "Home-Screen" (iOS) senden oder "Zum Dock hinzufügen" (MacOS). Anschließend noch "Benachrichtigungen erlauben" aktivieren.

==== CLI, Commandline, aus Skripten heraus Nachrichten senden ====
Zum Beispiel kann man mit einem CURL-Befehl etwas senden:

<pre>
curl -d "Your message content here" \
-H "Title: Bla" \
https://ntfy.sh/FreundlichenGruesseAnAlleFHEMNutzer
</pre>

oder auch mit WGET:

<pre>
wget --method=POST \
--body-data="Your message content here" \
--header="Title: Bla" \
https://ntfy.sh/FreundlichenGruesseAnAlleFHEMNutzer -q -O -
</pre>

==== Per Webhook Nachrichten senden ====
Via HTTP-GET als [https://ntfy.sh/FreundlichenGruesseAnAlleFHEMNutzer/publish?message=Your%20message%20content%20here&title=Bla Webhook] kann man ebenfalls Nachrichten via NTFY senden. Diese Option eignet sich besonders für weitere Geräte wie Shelly, Alexa oder auch Apple-Shortcuts und viele weitere Geräte dieser Art:

<pre>
https://ntfy.sh/FreundlichenGruesseAnAlleFHEMNutzer/publish?message=Your%20message%20content%20here&title=Bla
</pre>

==== Per E-Mail Nachrichten senden ====
Der NTFY Server kann auch per E-Mail erreicht werden, sofern dies so eingestellt wurde. Dies ist sehr praktisch, wenn ein System wie zum Beispiel eine IP-Kamera E-Mails bei Bewegung versenden kann, oder wenn ein CI-Build E-Mails verschickt. Die Doku dazu ist unter: https://docs.ntfy.sh/config/?h=mail#e-mail-publishing

Alternativ, kann man ein E-Mail Postfach überwachen und bei neuen E-Mails diese in eine NTFY Nachricht umwandeln und sich dann an die NTFY-Apps senden: [https://forum.fhem.de/index.php?topic=139868.0 📧 Fetchmail, Email von IP-Cam ohne Verzögerung an NTFY/FHEM senden]

===Anbindung in FHEM per Modul/Device "NTFY_CLIENT"===
Es gibt ein FHEM-Device, mit dem man NTFY nutzen kann: [https://rm.byterazor.de/projects/fhem-ntfy fhem-ntfy]

===='''Schritte um NTFY_CLIENT einzurichten:'''====
Den Quelltext für das NTFY_CLIENT-Device kann man von Extern wie folgt in FHEM laden:

<pre>
update add https://rm.byterazor.de/upd-fhem-ntfy/controls_byterazor-fhem-ntfy.txt
update
</pre>

Fall die Adresse nicht erreichbar ist kann man alternativ das Modul herunterladen von:

https://gitea.federationhq.de/byterazor/FHEM-NTFY/src/branch/main/FHEM

Nachdem man den Quelltext in FHEM hat, sollte FHEM einmal neugestartet werden:

<pre>
shutdown restart
</pre>

Danach kann man ein NTFY_CLIENT-Device anlegen:

<pre>
defmod NTFY0 NTFY_CLIENT https://ntfy.sh
attr NTFY0 defaultPriority default
attr NTFY0 defaultTopic FreundlichenGruesseAnAlleFHEMNutzer
attr NTFY0 room Experimente
</pre>

==== Senden von NTFY Nachrichten aus FHEM heraus: ====
Senden kann man Nachrichten mit:
<pre>
set NTFY0 publish @FreundlichenGruesseAnAlleFHEMNutzer Testnachricht!
</pre>
Die genaue Nutzung sind in dem Hilfetext zum Device zu finden. Das "@" setzt zum Beispiel das Topic für NTFY.

==== Empfangen und reagieren auf Nachrichten ====
Im Log wird es Meldungen in der folgenden Art geben wenn Nachrichten empfangen werden:
<pre>
2024-10-29 19:01:16.714 NTFY_TOPIC NTFY0_FreundlichenGruesseAnAlleFHEMNutzer nrReceivedMessages: 7
2024-10-29 19:01:16.715 NTFY_CLIENT NTFY0 subscriptions: FreundlichenGruesseAnAlleFHEMNutzer
2024-10-29 19:01:16.715 NTFY_CLIENT NTFY0 nrReceivedMessages: 7
2024-10-29 19:01:16.715 NTFY_CLIENT NTFY0 lastReceivedTitle: Bla
2024-10-29 19:01:16.715 NTFY_CLIENT NTFY0 lastReceivedData: Your message content here
2024-10-29 19:01:16.715 NTFY_CLIENT NTFY0 lastReceivedRawMessage: {"id":"oU5iqrdSFoeY","time":1730224876,"expires":1730268076,"event":"message","topic":"FreundlichenGruesseAnAlleFHEMNutzer","title":"Bla","message":"Your message content here"}
</pre>

Hier ein Beispiel mit einem notify-Device, dass auf die Nachrichten "Garage auf" oder "Garage zu" reagieren soll:
<pre>
defmod GarageNotify notify NTFY0:lastReceivedData:.* {\
Log(1, "$NAME: $EVTPART1, $EVTPART2, $EVENT");;\
\
if ("$EVTPART1 $EVTPART2" eq "Garage zu") {\
Log(1, "Garage soll zu gemacht werden");;\
fhem("set NTFY0 publish Ich werde die Garage nun schliessen");;\
}\
\
if ("$EVTPART1 $EVTPART2" eq "Garage auf") {\
Log(1, "Garage soll auf gemacht werden");;\
fhem("set NTFY0 publish Ich werde die Garage nun oeffnen");;\
}\
}
attr GarageNotify room Experimente
</pre>

Die zugehörigen Webhooks für obiges Beispiel-notify-Device wären dann:

* https://ntfy.sh/FreundlichenGruesseAnAlleFHEMNutzer/publish?message=Garage%20auf
* https://ntfy.sh/FreundlichenGruesseAnAlleFHEMNutzer/publish?message=Garage%20zu

Testen kann man direkt gegen die bekannteste und vom NTFY-Autor geschaffene NTFY-Installation: https://ntfy.sh/FreundlichenGruesseAnAlleFHEMNutzer

===Anbindung per HTTPMOD und Websocket===
Neben der Option per speziellem NTFY Device kann man auch das HTTPMOD-Device nutzen um Nachrichten oder Attachments/Dateien zu senden:

<pre>
defmod NTFY HTTPMOD none 0
attr NTFY userattr Filename Markdown NtfyServer Priority Title Topic password username
attr NTFY Filename test.png
attr NTFY Markdown true
attr NTFY NtfyServer ntfy.sh
attr NTFY Priority high
attr NTFY Title Titel aus UserAttr heraus
attr NTFY Topic FreundlichenGruesseAnAlleFHEMNutzer
attr NTFY comment # for HTTP Basic authentication use this as "setUrl":\
# https://[$name:username]:[$name:password]@[$name:NtfyServer]/%%path%%
attr NTFY replacement01Mode text
attr NTFY replacement01Regex %%path%%
attr NTFY replacement02Mode expression
attr NTFY replacement02Regex \[([^:]+):([^\]]+)\]
attr NTFY replacement02Value my $device = $name if ($1 eq "\$name") // $1;;\
ReadingsVal($device, $2, undef) or AttrVal($device, $2, "???");;
attr NTFY replacement03Mode expression
attr NTFY replacement03Regex %%title%%
attr NTFY replacement04Mode expression
attr NTFY replacement04Regex %%message%%
attr NTFY replacement05Mode expression
attr NTFY replacement05Regex %%file%%
attr NTFY room Global
attr NTFY set1Data %%message%%
attr NTFY set1HeaderIcon Icon: https://fhem.de/www/images/default/fhemicon.png
attr NTFY set1HeaderMarkdown Markdown: [$name:Markdown]
attr NTFY set1HeaderPrio Priority: [$name:Priority]
attr NTFY set1HeaderTitle Title: %%title%%
attr NTFY set1Method POST
attr NTFY set1Name message
attr NTFY set1Replacement01Value [$name:Topic]
attr NTFY set1Replacement03Value # get the value as passed to the set command:\
my $value = InternalVal($name, "value", "???");;\
\
# find first occurence of pattern Title=".*" and use that as result:\
my ($result) = $value =~ /Title="(.*?)"/;;\
\
# assign value from userAttr if $result is emtpy:\
$result //= AttrVal($name, "Title", "???");;\
\
return $result;;
attr NTFY set1Replacement04Value # get the value as passed to the set command:\
my $value = InternalVal($name, "value", "???");;\
\
# remove everything matching pattern Title=".*"\
$value =~ s/Title=".*?"//;;\
\
#replace the literal character sequence\
# \n with a real linefeed\
$value =~ s/\\n/\n/g;;\
\
return $value;;
attr NTFY set1TextArg 1
attr NTFY set2Data %%file%%
attr NTFY set2HeaderFilename Filename: [$name:Filename]
attr NTFY set2HeaderPrio Priority: [$name:Priority]
attr NTFY set2HeaderTitle Title: [$name:Title]
attr NTFY set2Method PUT
attr NTFY set2Name attach
attr NTFY set2Replacement01Value [$name:Topic]
attr NTFY set2Replacement05Value my $value = InternalVal($name, "value", "???");;\
\
open(my $fh, '<', $value) or return "ERROR: Cannot open file";;\
binmode($fh);; \
my $result = do { local $/;; <$fh> };; \
close($fh);; \
\
return $result;;
attr NTFY set2TextArg 1
attr NTFY setURL https://[$name:NtfyServer]/%%path%%
attr NTFY widgetOverride Priority:select,max,high,default,low,min Markdown:select,true,false
</pre>

====Senden mit HTTPMOD====
<pre>
set NTFY message Title="mein Titel aus dem Set heraus" Meine Nachricht
set NTFY message Title="" Meine Nachricht ohne Titel
set NTFY message Title="✅ Emojis 🚀" 📝 Meine Nachricht mit Emojis 👾
set NTFY attach /opt/fhem/www/images/default/fhemicon.png
</pre>

Wenn man Dateien versendet, wird der Dateiname für den Empfänger per Reading oder Attribut definiert. Das Reading hat Vorrang:
<pre>
setreading NTFY Filename meinDateiName.png
attr NTFY Filename meinDateiName.png
</pre>

====Empfangen mit Websocket und Dummydevice====
Alternativ zum NTFY_CLIENT Modul kann man auch mit folgenden Snippet NTFY Nachrichten empfangen.

<pre>
defmod NTFY_RECEIVE dummy
attr NTFY_RECEIVE userattr URL last_seen_max_age password username
attr NTFY_RECEIVE URL wss:ntfy.sh:443/FreundlichenGruesseAnAlleFHEMNutzer/ws
attr NTFY_RECEIVE alias NTFY_RECEIVE
attr NTFY_RECEIVE devStateIcon opened:general_ok@green:stop disconnected:rc_STOP@red:start
attr NTFY_RECEIVE eventMap /cmd connect:start/cmd disconnect:stop/
attr NTFY_RECEIVE group Experimente
attr NTFY_RECEIVE icon hue_filled_plug

attr NTFY_RECEIVE password superGeheimesPasswort
attr NTFY_RECEIVE readingList cmd

attr NTFY_RECEIVE setList cmd
attr NTFY_RECEIVE userReadings connect:cmd:.connect {\
my $hash = $defs{$name};;\
my $devState = DevIo_IsOpen($hash);;\
return "Device already open" if (defined($devState));;\
\
$hash->{DeviceName} = AttrVal($name, "URL", "wss:ntfy.sh:443/FreundlichenGruesseAnAlleFHEMNutzer/ws");;\
$hash->{DeviceName} =~ m,^(ws:|wss:)?([^/:]+):([0-9]+)(.*?)$,;;\
$hash->{header}{'Host'} = $2;;\
$hash->{header}{'User-Agent'} = 'FHEM';;\
\
my $user = AttrVal($name, "username", "???");;\
my $pwd = AttrVal($name, "password", "???");;\
if ($user ne "???" && $pwd ne "???") {\
my $encoded_auth = MIME::Base64::encode_base64("$user:$pwd", "");;\
$hash->{header}{'Authorization'} = "Basic $encoded_auth";;\
}\
\
$hash->{directReadFn} = sub () {\
my $hash = $defs{$name};;\
readingsBeginUpdate($hash);;\
my $buf = DevIo_SimpleRead($hash);;\
\
# track activity, emtpy buffer normally is from ping/pongs\
readingsBulkUpdate($hash, "last_seen", int(time()*1000));;\
RemoveInternalTimer($name.'Timeout');;\
my $timeoutFunction = sub() {\
my ($arg) = @_;;\
my $hash = $defs{$name};;\
my $myCmd = ReadingsVal($name, "cmd", "disconnect");;\
return if ($myCmd =~ /disconnect|stop/);;\
\
Log3($name, 3, "$name: Timeout occured, restarting websocket...");;\
DevIo_CloseDev($hash);;\
readingsBeginUpdate($hash);;\
readingsBulkUpdate($hash, "state", "disconnected");;\
readingsBulkUpdate($hash, "cmd", "connect", 1);;\
readingsEndUpdate($hash, 1);;\
};;\
InternalTimer(gettimeofday() + 120, $timeoutFunction, $name.'Timeout');;\
\
if(!defined($buf)) {\
DevIo_CloseDev($hash);;\
#readingsBulkUpdate($hash, "last_seen", 0);;\
$buf = "not_connected";;\
}\
\
# only update our reading if buffer is not empty and looks like it contains a message\
if ($buf ne "" && \
$buf =~ /^{.*"event":"message".*}$/) { ## check if buffer looks like JSON with msg\
\
# delete all our readings that begin with "ntfy_"\
foreach my $reading (grep { $_ =~ /^ntfy_.*/ } keys %{$hash->{READINGS}}) {\
readingsDelete($hash, $reading);;\
}\
\
# parse as JSON, do not trust the input fully, thus sanitize buffer\
my %res = %{json2nameValue($buf)};; #(https://wiki.fhem.de/wiki/MQTT2_DEVICE_-_Schritt_f%C3%BCr_Schritt#json2nameValue.28.29)\
foreach my $k (sort keys %res) {\
# only keep ASCII and a German Characters like Umlaute, sharp-S...\
my $sanitizedValue = $res{$k} =~ s/[^[:ascii:]äöüÖÄÜß]/_/rg;; # 'r' flag prevents modifying the input string\
readingsBulkUpdate($hash, "ntfy_".makeReadingName($k), $sanitizedValue);;\
}\
}\
#readingsBulkUpdate($hash, "websocketData", "$buf") if ($buf ne "");;\
Log3($name, 3, "$name: Rx: >>>$buf<<<") if ($buf ne "");;\
\
readingsEndUpdate($hash, 1);;\
};;\
\
DevIo_OpenDev($hash,\
0, ## reopen flag\
undef, ## initFn, on success\
sub() { ## callbackFn, on verdict, req. to make it a non-blocking call\
my ($hash, $error) = @_;;\
if ($error) {\
Log(3, "$name: DevIo_OpenDev Callback: connection failed: $error");;\
\
my $timerFunction = sub() {\
my ($arg) = @_;;\
my $hash = $defs{$name};;\
my $devState = DevIo_IsOpen($hash);;\
readingsSingleUpdate($hash, "cmd", "connect", 1) if (!defined($devState));;\
};;\
\
RemoveInternalTimer($name.'Timer');;\
my $rwait = int(rand(20)) + 10;;\
InternalTimer(gettimeofday() + $rwait, $timerFunction, $name.'Timer');;\
readingsSingleUpdate($hash, "cmd", "reconnect attempt in $rwait seconds", 1);;\
}\
}\
);;\
\
readingsBulkUpdate($hash, "state", "connecting...");;\
return POSIX::strftime("%H:%M:%S",localtime(time()));;\
},\
disconnect:cmd:.(disconnect|reconnect) {\
my $hash = $defs{$name};;\
my $myCmd = ReadingsVal($name, "cmd", "???");;\
\
RemoveInternalTimer($name.'Timer');;\
RemoveInternalTimer($name.'Timeout');;\
DevIo_CloseDev($hash);;\
readingsBulkUpdate($hash, "state", "disconnected") if (!defined(DevIo_IsOpen($hash)));;\
\
if ($myCmd =~ /reconnect/) {\
my $timerFunction = sub() {\
my $hash = $defs{$name};;\
readingsSingleUpdate($hash, "cmd", "connect", 1);;\
};;\
\
RemoveInternalTimer("${name}_${reading}_timer");;\
InternalTimer(gettimeofday()+1, $timerFunction, "${name}_${reading}_timer");;\
} else {\
RemoveInternalTimer("${name}_watchdog_timer");;\
}\
\
return POSIX::strftime("%H:%M:%S",localtime(time()));;\
},\
onDisconnect { ## check on each update if the connection is unintentionally broken...\
my $myState = ReadingsVal($name, "state", "???");;\
my $myData = ReadingsVal($name, "websocketData", "???");;\
my $myCmd = ReadingsVal($name, "cmd", "disconnect");;\
return if ($myState ne "disconnected" and $myData ne "not_connected");;\
return if ($myCmd =~ /disconnect|stop/);;\
\
my $timerFunction = sub() {\
my ($arg) = @_;;\
my $hash = $defs{$name};;\
my $devState = DevIo_IsOpen($hash);;\
readingsSingleUpdate($hash, "cmd", "connect", 1) if (!defined($devState));;\
};;\
\
RemoveInternalTimer($name.'Timer');;\
my $rwait = int(rand(20)) + 10;;\
InternalTimer(gettimeofday() + $rwait, $timerFunction, $name.'Timer');;\
readingsBulkUpdate($hash, "cmd", "reconnect attempt in $rwait seconds");;\
\
return POSIX::strftime("%H:%M:%S",localtime(time()));;\
},\
watchdog:last_seen:.* {\
my $ls = ReadingsVal($name, "last_seen", 0);;\
\
my $timerFunction = sub() {\
##fhem("set FHEMMeldung.ntfy message $name $reading wurde ausgelöst (last_seen: $ls)");;\
readingsSingleUpdate($hash, "cmd", "reconnect", 1);;\
readingsSingleUpdate($hash, "last_seen", 0, 1);;\
};;\
\
RemoveInternalTimer("${name}_${reading}_timer");;\
InternalTimer(gettimeofday()+240, $timerFunction, "${name}_${reading}_timer");;\
\
return POSIX::strftime("%H:%M:%S", localtime(time()));;\
}
attr NTFY_RECEIVE username Torxgewinde
attr NTFY_RECEIVE verbose 1
attr NTFY_RECEIVE webCmd start:stop
</pre>

===Weitere Links===
Forumthread: {{Link2Forum|Topic=137036|LinkText=NTFY.sh: Push Nachrichten an iOS, Android, PC, Command-Line, E-Mail & Telefon}}

[[Kategorie:Code Snippets]]
[[Kategorie:Messenger]]

Ntfy

2026-01-22T17:14:03Z

Torxgewinde: Externes Repo nicht mehr erreichbar

==📬 NTFY.sh: Push Nachrichten an iOS, Android, PC, Command-Line, E-Mail & Telefon==
[[Datei:NTFY Screenshot mit einem Bild.png|alternativtext=NTFY Screenshot mit einem Bild|mini|300x300px|NTFY Screenshot mit einem Bild]]
[https://NTFY.sh NTFY.sh] bietet Push-Dienste auf iOS, Android, Console, E-Mail, ja sogar als Anruf auf ein Telefon an. Es ist damit ähnlich zu dem, was man mit PushOver, PushBullet oder auch Gotify anstellen kann, wobei NTFY auch Kriterien wie "Self-hosted" und echte "iOS-Pushnachrichten" erfüllt. Man kann damit von FHEM aus alle diese Kanäle mit einer Push-Nachricht erreichen. Die Nutzung ist extrem einfach, man setzt einen HTTP-Aufruf ab, um eine Push-Nachricht zu versenden. NTFY.sh betreibt sogar einen Gratis-Server, den man nutzen darf. Man kann den Server auch selber hosten, wenn man will.

Öffnet testweise diesen Link, dort tauchen die Nachrichten auch in der PWA (Webapp) auf: https://ntfy.sh/FreundlichenGruesseAnAlleFHEMNutzer

<div style="color:#ffff00; background:#ff0000; border: solid 1px black">'''Wichtig:''' Nutzt man eine öffentliche Instanz ist das Topic so zu wählen, dass es wie ein Passwort funktioniert und schwer zu erraten ist. Wählt man ein einfaches Topic, können andere mitlesen und auch Nachrichten senden. Dies kann zu ungewollten Effekten führen!</div>

=== NTFY mit anderen Systemen nutzen/verbinden ===
Auch ganz ohne FHEM, also aus anderen Systemen, kann man an NTFY Nachrichten senden und empfangen. So kann man sich aus iOS zum Beispiel per Webhook etwas an NTFY senden, oder auch von IP-Kameras Infos an den NTFY Server senden und dann von den diversen Clients empfangen und verarbeiten.

==== Apps (iOS, Android und PWA) ====
Ganz wichtig für die meisten Nutzer ist natürlich der Empfang von NTFY Nachrichten mit:

* der Android-App ([https://play.google.com/store/apps/details?id=io.heckel.ntfy&pli=1 Playstore], [https://f-droid.org/en/packages/io.heckel.ntfy/ F-Droid]),
* der [https://apps.apple.com/us/app/ntfy/id1625396347 iOS-App] *, oder
* der [https://ntfy.sh/app PWA] (Progressive-Web-App)

'''Hinweis zur nativen iOS-App:''' [https://github.com/binwiederhier/ntfy/issues/1226 Zur Zeit] funktioniert die Anzeige von Anhängen unter iOS, iPadOS, MacOS '''nur''' über die Web-App (zu finden unter https://ntfy.sh/app). Um die PWA unter iOS/MacOS fast wie eine gewöhnliche App zu nutzen, kann man die Web-Seite an den "Home-Screen" (iOS) senden oder "Zum Dock hinzufügen" (MacOS). Anschließend noch "Benachrichtigungen erlauben" aktivieren.

==== CLI, Commandline, aus Skripten heraus Nachrichten senden ====
Zum Beispiel kann man mit einem CURL-Befehl etwas senden:

<pre>
curl -d "Your message content here" \
-H "Title: Bla" \
https://ntfy.sh/FreundlichenGruesseAnAlleFHEMNutzer
</pre>

oder auch mit WGET:

<pre>
wget --method=POST \
--body-data="Your message content here" \
--header="Title: Bla" \
https://ntfy.sh/FreundlichenGruesseAnAlleFHEMNutzer -q -O -
</pre>

==== Per Webhook Nachrichten senden ====
Via HTTP-GET als [https://ntfy.sh/FreundlichenGruesseAnAlleFHEMNutzer/publish?message=Your%20message%20content%20here&title=Bla Webhook] kann man ebenfalls Nachrichten via NTFY senden. Diese Option eignet sich besonders für weitere Geräte wie Shelly, Alexa oder auch Apple-Shortcuts und viele weitere Geräte dieser Art:

<pre>
https://ntfy.sh/FreundlichenGruesseAnAlleFHEMNutzer/publish?message=Your%20message%20content%20here&title=Bla
</pre>

==== Per E-Mail Nachrichten senden ====
Der NTFY Server kann auch per E-Mail erreicht werden, sofern dies so eingestellt wurde. Dies ist sehr praktisch, wenn ein System wie zum Beispiel eine IP-Kamera E-Mails bei Bewegung versenden kann, oder wenn ein CI-Build E-Mails verschickt. Die Doku dazu ist unter: https://docs.ntfy.sh/config/?h=mail#e-mail-publishing

Alternativ, kann man ein E-Mail Postfach überwachen und bei neuen E-Mails diese in eine NTFY Nachricht umwandeln und sich dann an die NTFY-Apps senden: [https://forum.fhem.de/index.php?topic=139868.0 📧 Fetchmail, Email von IP-Cam ohne Verzögerung an NTFY/FHEM senden]

===Anbindung in FHEM per Modul/Device "NTFY_CLIENT"===
Hinweis: Das extern gehostete Repository ist zur Zeit offline, deswegen ist der folgende Abschnitt vorerst noch sichtbar und sollte ca. 03.2026 entfernt werden, falls das Repo weiterhin nicht erreichbar ist :-(

<s>Es gibt ein FHEM-Device, mit dem man NTFY nutzen kann: [https://rm.byterazor.de/projects/fhem-ntfy fhem-ntfy]</s>

===='''<s>Schritte um NTFY_CLIENT einzurichten:</s>'''====
<s>Den Quelltext für das NTFY_CLIENT-Device kann man von Extern wie folgt in FHEM laden:</s>

<pre>
update add https://rm.byterazor.de/upd-fhem-ntfy/controls_byterazor-fhem-ntfy.txt
update
</pre>

<s>Nachdem man den Quelltext in FHEM hat, sollte FHEM einmal neugestartet werden:</s>

<pre>
shutdown restart
</pre>

<s>Danach kann man ein NTFY_CLIENT-Device anlegen:</s>

<pre>
defmod NTFY0 NTFY_CLIENT https://ntfy.sh
attr NTFY0 defaultPriority default
attr NTFY0 defaultTopic FreundlichenGruesseAnAlleFHEMNutzer
attr NTFY0 room Experimente
</pre>

==== <s>Senden von NTFY Nachrichten aus FHEM heraus:</s> ====
<s>Senden kann man Nachrichten mit:</s>
<pre>
set NTFY0 publish @FreundlichenGruesseAnAlleFHEMNutzer Testnachricht!
</pre>
<s>Die genaue Nutzung sind in dem Hilfetext zum Device zu finden. Das "@" setzt zum Beispiel das Topic für NTFY.</s>

==== <s>Empfangen und reagieren auf Nachrichten</s> ====
<s>Im Log wird es Meldungen in der folgenden Art geben wenn Nachrichten empfangen werden:</s>
<pre>
2024-10-29 19:01:16.714 NTFY_TOPIC NTFY0_FreundlichenGruesseAnAlleFHEMNutzer nrReceivedMessages: 7
2024-10-29 19:01:16.715 NTFY_CLIENT NTFY0 subscriptions: FreundlichenGruesseAnAlleFHEMNutzer
2024-10-29 19:01:16.715 NTFY_CLIENT NTFY0 nrReceivedMessages: 7
2024-10-29 19:01:16.715 NTFY_CLIENT NTFY0 lastReceivedTitle: Bla
2024-10-29 19:01:16.715 NTFY_CLIENT NTFY0 lastReceivedData: Your message content here
2024-10-29 19:01:16.715 NTFY_CLIENT NTFY0 lastReceivedRawMessage: {"id":"oU5iqrdSFoeY","time":1730224876,"expires":1730268076,"event":"message","topic":"FreundlichenGruesseAnAlleFHEMNutzer","title":"Bla","message":"Your message content here"}
</pre>

<s>Hier ein Beispiel mit einem notify-Device, dass auf die Nachrichten "Garage auf" oder "Garage zu" reagieren soll:</s>
<pre>
defmod GarageNotify notify NTFY0:lastReceivedData:.* {\
Log(1, "$NAME: $EVTPART1, $EVTPART2, $EVENT");;\
\
if ("$EVTPART1 $EVTPART2" eq "Garage zu") {\
Log(1, "Garage soll zu gemacht werden");;\
fhem("set NTFY0 publish Ich werde die Garage nun schliessen");;\
}\
\
if ("$EVTPART1 $EVTPART2" eq "Garage auf") {\
Log(1, "Garage soll auf gemacht werden");;\
fhem("set NTFY0 publish Ich werde die Garage nun oeffnen");;\
}\
}
attr GarageNotify room Experimente
</pre>

<s>Die zugehörigen Webhooks für obiges Beispiel-notify-Device wären dann:</s>

* <s>https://ntfy.sh/FreundlichenGruesseAnAlleFHEMNutzer/publish?message=Garage%20auf</s>
* <s>https://ntfy.sh/FreundlichenGruesseAnAlleFHEMNutzer/publish?message=Garage%20zu</s>

<s>Testen kann man direkt gegen die bekannteste und vom NTFY-Autor geschaffene NTFY-Installation: https://ntfy.sh/FreundlichenGruesseAnAlleFHEMNutzer</s>

===Anbindung per HTTPMOD und Websocket===
Neben der Option per speziellem NTFY Device kann man auch das HTTPMOD-Device nutzen um Nachrichten oder Attachments/Dateien zu senden:

<pre>
defmod NTFY HTTPMOD none 0
attr NTFY userattr Filename Markdown NtfyServer Priority Title Topic password username
attr NTFY Filename test.png
attr NTFY Markdown true
attr NTFY NtfyServer ntfy.sh
attr NTFY Priority high
attr NTFY Title Titel aus UserAttr heraus
attr NTFY Topic FreundlichenGruesseAnAlleFHEMNutzer
attr NTFY comment # for HTTP Basic authentication use this as "setUrl":\
# https://[$name:username]:[$name:password]@[$name:NtfyServer]/%%path%%
attr NTFY replacement01Mode text
attr NTFY replacement01Regex %%path%%
attr NTFY replacement02Mode expression
attr NTFY replacement02Regex \[([^:]+):([^\]]+)\]
attr NTFY replacement02Value my $device = $name if ($1 eq "\$name") // $1;;\
ReadingsVal($device, $2, undef) or AttrVal($device, $2, "???");;
attr NTFY replacement03Mode expression
attr NTFY replacement03Regex %%title%%
attr NTFY replacement04Mode expression
attr NTFY replacement04Regex %%message%%
attr NTFY replacement05Mode expression
attr NTFY replacement05Regex %%file%%
attr NTFY room Global
attr NTFY set1Data %%message%%
attr NTFY set1HeaderIcon Icon: https://fhem.de/www/images/default/fhemicon.png
attr NTFY set1HeaderMarkdown Markdown: [$name:Markdown]
attr NTFY set1HeaderPrio Priority: [$name:Priority]
attr NTFY set1HeaderTitle Title: %%title%%
attr NTFY set1Method POST
attr NTFY set1Name message
attr NTFY set1Replacement01Value [$name:Topic]
attr NTFY set1Replacement03Value # get the value as passed to the set command:\
my $value = InternalVal($name, "value", "???");;\
\
# find first occurence of pattern Title=".*" and use that as result:\
my ($result) = $value =~ /Title="(.*?)"/;;\
\
# assign value from userAttr if $result is emtpy:\
$result //= AttrVal($name, "Title", "???");;\
\
return $result;;
attr NTFY set1Replacement04Value # get the value as passed to the set command:\
my $value = InternalVal($name, "value", "???");;\
\
# remove everything matching pattern Title=".*"\
$value =~ s/Title=".*?"//;;\
\
#replace the literal character sequence\
# \n with a real linefeed\
$value =~ s/\\n/\n/g;;\
\
return $value;;
attr NTFY set1TextArg 1
attr NTFY set2Data %%file%%
attr NTFY set2HeaderFilename Filename: [$name:Filename]
attr NTFY set2HeaderPrio Priority: [$name:Priority]
attr NTFY set2HeaderTitle Title: [$name:Title]
attr NTFY set2Method PUT
attr NTFY set2Name attach
attr NTFY set2Replacement01Value [$name:Topic]
attr NTFY set2Replacement05Value my $value = InternalVal($name, "value", "???");;\
\
open(my $fh, '<', $value) or return "ERROR: Cannot open file";;\
binmode($fh);; \
my $result = do { local $/;; <$fh> };; \
close($fh);; \
\
return $result;;
attr NTFY set2TextArg 1
attr NTFY setURL https://[$name:NtfyServer]/%%path%%
attr NTFY widgetOverride Priority:select,max,high,default,low,min Markdown:select,true,false
</pre>

====Senden mit HTTPMOD====
<pre>
set NTFY message Title="mein Titel aus dem Set heraus" Meine Nachricht
set NTFY message Title="" Meine Nachricht ohne Titel
set NTFY message Title="✅ Emojis 🚀" 📝 Meine Nachricht mit Emojis 👾
set NTFY attach /opt/fhem/www/images/default/fhemicon.png
</pre>

Wenn man Dateien versendet, wird der Dateiname für den Empfänger per Reading oder Attribut definiert. Das Reading hat Vorrang:
<pre>
setreading NTFY Filename meinDateiName.png
attr NTFY Filename meinDateiName.png
</pre>

====Empfangen mit Websocket und Dummydevice====
Alternativ zum NTFY_CLIENT Modul kann man auch mit folgenden Snippet NTFY Nachrichten empfangen.

<pre>
defmod NTFY_RECEIVE dummy
attr NTFY_RECEIVE userattr URL last_seen_max_age password username
attr NTFY_RECEIVE URL wss:ntfy.sh:443/FreundlichenGruesseAnAlleFHEMNutzer/ws
attr NTFY_RECEIVE alias NTFY_RECEIVE
attr NTFY_RECEIVE devStateIcon opened:general_ok@green:stop disconnected:rc_STOP@red:start
attr NTFY_RECEIVE eventMap /cmd connect:start/cmd disconnect:stop/
attr NTFY_RECEIVE group Experimente
attr NTFY_RECEIVE icon hue_filled_plug

attr NTFY_RECEIVE password superGeheimesPasswort
attr NTFY_RECEIVE readingList cmd

attr NTFY_RECEIVE setList cmd
attr NTFY_RECEIVE userReadings connect:cmd:.connect {\
my $hash = $defs{$name};;\
my $devState = DevIo_IsOpen($hash);;\
return "Device already open" if (defined($devState));;\
\
$hash->{DeviceName} = AttrVal($name, "URL", "wss:ntfy.sh:443/FreundlichenGruesseAnAlleFHEMNutzer/ws");;\
$hash->{DeviceName} =~ m,^(ws:|wss:)?([^/:]+):([0-9]+)(.*?)$,;;\
$hash->{header}{'Host'} = $2;;\
$hash->{header}{'User-Agent'} = 'FHEM';;\
\
my $user = AttrVal($name, "username", "???");;\
my $pwd = AttrVal($name, "password", "???");;\
if ($user ne "???" && $pwd ne "???") {\
my $encoded_auth = MIME::Base64::encode_base64("$user:$pwd", "");;\
$hash->{header}{'Authorization'} = "Basic $encoded_auth";;\
}\
\
$hash->{directReadFn} = sub () {\
my $hash = $defs{$name};;\
readingsBeginUpdate($hash);;\
my $buf = DevIo_SimpleRead($hash);;\
\
# track activity, emtpy buffer normally is from ping/pongs\
readingsBulkUpdate($hash, "last_seen", int(time()*1000));;\
RemoveInternalTimer($name.'Timeout');;\
my $timeoutFunction = sub() {\
my ($arg) = @_;;\
my $hash = $defs{$name};;\
my $myCmd = ReadingsVal($name, "cmd", "disconnect");;\
return if ($myCmd =~ /disconnect|stop/);;\
\
Log3($name, 3, "$name: Timeout occured, restarting websocket...");;\
DevIo_CloseDev($hash);;\
readingsBeginUpdate($hash);;\
readingsBulkUpdate($hash, "state", "disconnected");;\
readingsBulkUpdate($hash, "cmd", "connect", 1);;\
readingsEndUpdate($hash, 1);;\
};;\
InternalTimer(gettimeofday() + 120, $timeoutFunction, $name.'Timeout');;\
\
if(!defined($buf)) {\
DevIo_CloseDev($hash);;\
#readingsBulkUpdate($hash, "last_seen", 0);;\
$buf = "not_connected";;\
}\
\
# only update our reading if buffer is not empty and looks like it contains a message\
if ($buf ne "" && \
$buf =~ /^{.*"event":"message".*}$/) { ## check if buffer looks like JSON with msg\
\
# delete all our readings that begin with "ntfy_"\
foreach my $reading (grep { $_ =~ /^ntfy_.*/ } keys %{$hash->{READINGS}}) {\
readingsDelete($hash, $reading);;\
}\
\
# parse as JSON, do not trust the input fully, thus sanitize buffer\
my %res = %{json2nameValue($buf)};; #(https://wiki.fhem.de/wiki/MQTT2_DEVICE_-_Schritt_f%C3%BCr_Schritt#json2nameValue.28.29)\
foreach my $k (sort keys %res) {\
# only keep ASCII and a German Characters like Umlaute, sharp-S...\
my $sanitizedValue = $res{$k} =~ s/[^[:ascii:]äöüÖÄÜß]/_/rg;; # 'r' flag prevents modifying the input string\
readingsBulkUpdate($hash, "ntfy_".makeReadingName($k), $sanitizedValue);;\
}\
}\
#readingsBulkUpdate($hash, "websocketData", "$buf") if ($buf ne "");;\
Log3($name, 3, "$name: Rx: >>>$buf<<<") if ($buf ne "");;\
\
readingsEndUpdate($hash, 1);;\
};;\
\
DevIo_OpenDev($hash,\
0, ## reopen flag\
undef, ## initFn, on success\
sub() { ## callbackFn, on verdict, req. to make it a non-blocking call\
my ($hash, $error) = @_;;\
if ($error) {\
Log(3, "$name: DevIo_OpenDev Callback: connection failed: $error");;\
\
my $timerFunction = sub() {\
my ($arg) = @_;;\
my $hash = $defs{$name};;\
my $devState = DevIo_IsOpen($hash);;\
readingsSingleUpdate($hash, "cmd", "connect", 1) if (!defined($devState));;\
};;\
\
RemoveInternalTimer($name.'Timer');;\
my $rwait = int(rand(20)) + 10;;\
InternalTimer(gettimeofday() + $rwait, $timerFunction, $name.'Timer');;\
readingsSingleUpdate($hash, "cmd", "reconnect attempt in $rwait seconds", 1);;\
}\
}\
);;\
\
readingsBulkUpdate($hash, "state", "connecting...");;\
return POSIX::strftime("%H:%M:%S",localtime(time()));;\
},\
disconnect:cmd:.(disconnect|reconnect) {\
my $hash = $defs{$name};;\
my $myCmd = ReadingsVal($name, "cmd", "???");;\
\
RemoveInternalTimer($name.'Timer');;\
RemoveInternalTimer($name.'Timeout');;\
DevIo_CloseDev($hash);;\
readingsBulkUpdate($hash, "state", "disconnected") if (!defined(DevIo_IsOpen($hash)));;\
\
if ($myCmd =~ /reconnect/) {\
my $timerFunction = sub() {\
my $hash = $defs{$name};;\
readingsSingleUpdate($hash, "cmd", "connect", 1);;\
};;\
\
RemoveInternalTimer("${name}_${reading}_timer");;\
InternalTimer(gettimeofday()+1, $timerFunction, "${name}_${reading}_timer");;\
} else {\
RemoveInternalTimer("${name}_watchdog_timer");;\
}\
\
return POSIX::strftime("%H:%M:%S",localtime(time()));;\
},\
onDisconnect { ## check on each update if the connection is unintentionally broken...\
my $myState = ReadingsVal($name, "state", "???");;\
my $myData = ReadingsVal($name, "websocketData", "???");;\
my $myCmd = ReadingsVal($name, "cmd", "disconnect");;\
return if ($myState ne "disconnected" and $myData ne "not_connected");;\
return if ($myCmd =~ /disconnect|stop/);;\
\
my $timerFunction = sub() {\
my ($arg) = @_;;\
my $hash = $defs{$name};;\
my $devState = DevIo_IsOpen($hash);;\
readingsSingleUpdate($hash, "cmd", "connect", 1) if (!defined($devState));;\
};;\
\
RemoveInternalTimer($name.'Timer');;\
my $rwait = int(rand(20)) + 10;;\
InternalTimer(gettimeofday() + $rwait, $timerFunction, $name.'Timer');;\
readingsBulkUpdate($hash, "cmd", "reconnect attempt in $rwait seconds");;\
\
return POSIX::strftime("%H:%M:%S",localtime(time()));;\
},\
watchdog:last_seen:.* {\
my $ls = ReadingsVal($name, "last_seen", 0);;\
\
my $timerFunction = sub() {\
##fhem("set FHEMMeldung.ntfy message $name $reading wurde ausgelöst (last_seen: $ls)");;\
readingsSingleUpdate($hash, "cmd", "reconnect", 1);;\
readingsSingleUpdate($hash, "last_seen", 0, 1);;\
};;\
\
RemoveInternalTimer("${name}_${reading}_timer");;\
InternalTimer(gettimeofday()+240, $timerFunction, "${name}_${reading}_timer");;\
\
return POSIX::strftime("%H:%M:%S", localtime(time()));;\
}
attr NTFY_RECEIVE username Torxgewinde
attr NTFY_RECEIVE verbose 1
attr NTFY_RECEIVE webCmd start:stop
</pre>

===Weitere Links===
Forumthread: {{Link2Forum|Topic=137036|LinkText=NTFY.sh: Push Nachrichten an iOS, Android, PC, Command-Line, E-Mail & Telefon}}

[[Kategorie:Code Snippets]]
[[Kategorie:Messenger]]

E-Mail senden

2025-12-21T18:40:06Z

Torxgewinde: Code musste noch angepasst werden damit man From mit Klarnamen setzen kann

Um aus FHEM heraus E-Mails senden zu können, gibt es unterschiedliche Methoden, abhängig von der verwendeten Plattform.

Lange Zeit war <code>sendemail</code> sehr beliebt. Da aber die Homepage des Projekts nicht mehr online ist und Probleme nur noch via erhöhtem Supportaufwand gelöst werden, sollte diese Option als veraltet betrachtet werden.

Eine Liste mit ressourcensparenden E-Mails Clients findet man bei dem OpenWRT Projekt: https://openwrt.org/docs/guide-user/services/email/smtp.client

MSGMail ist ein FHEM eigenes Modul zum Versenden, die Einrichtung ist allerdings nicht gänzlich einfach. Anfängern sei die cURL Methode empfohlen.

=== MSGMail (Linux, Windows) ===
FHEM bringt ein eigenes Device zum Senden von E-Mails mit, welches in Perl implementiert ist: [https://fhem.de/commandref.html#MSGMail MSGMail, https://fhem.de/commandref.html#MSGMail]

=== cURL (Linux, Windows) ===
[https://curl.se/ cURL] kann auf praktisch [https://curl.se/download.html jedem Betriebssystem] genutzt werden, [https://curl.se/windows/ selbst unter Windows]. Es kann direkt mit einem SMTP Server E-Mails versenden und stellt damit eine moderne, portable und sichere Option zum Versenden von E-Mails dar.

In FHEM richtet man sich ein Device ein und passt die Details (<code>$emailTo, $emailFrom, $emailServer</code>) an. Das Programm cURL muss installiert sein (z.B. mit <code>apt install curl</code>, oder durch Herunterladen und Installieren von der [https://curl.se cURL-Webseite]).<syntaxhighlight lang="perl" line="1">
defmod sendMail dummy
attr sendMail readingList message password
attr sendMail setList message:textField-long password
attr sendMail userReadings state:message:[\s\S]* {\
my $emailTo = 'du@example.com';;\
my $emailFrom = 'fhem@example.de';;\
#my $emailFrom = 'FHEM Server <fhem@example.de>';;\
my $emailServer = 'mail.your-server.de';;\
\
#erzeuge Datumsangabe konform zu RFC-5322:\
my @emailDateArray = split(' ', strftime("%w %d %m %Y %H:%M:%S %z", localtime));;\
$emailDateArray[0] = (qw[Sun Mon Tue Wed Thu Fri Sat])[$emailDateArray[0]] . ',';;\
$emailDateArray[2] = (qw[Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec])[$emailDateArray[2]-1];;\
my $emailDate = join(' ', @emailDateArray);;\
\
# Passwort aus getKeyValue abrufen\
my ($err, $emailPass) = getKeyValue("${name}_password");;\
if ($err || !defined $emailPass) {\
return "Error retrieving password: $err";;\
}\
#extrahiere die E-Mail Adresse aus dem From für den Login:\
my ($emailUser) = $emailFrom =~ /([A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,})/i;;\
\
my $message = ReadingsVal($name, 'message', '???');;\
my $subject = "$name: FHEM Nachricht";;\
\
# Betreff extrahieren und aus der Nachricht entfernen\
if ($message =~ s/(?:Subject|Betreff)=["'](.*?)["']//) {\
$subject = $1;;\
}\
\
# Empfänger extrahieren und aus der Nachricht entfernen\
if ($message =~ s/(?:To|An)=["'](.*?)["']//) {\
$emailTo = $1;;\
}\
\
#Dateianhänge bestimmen\
my @attachments;;\
while ($message =~ s/(?:Attachment|Anhang)=["'](.*?)["']//) {\
my $file = $1;;\
return ">>$file<< not found, not sending email" unless (-e $file);;\
push (@attachments, $file);;\
}\
\
#der curl Befehl wird hier aufgebaut:\
my $cmd = "curl -m 19 --noproxy '*' --no-progress-meter --ssl-reqd smtps://$emailServer:465 ";;\
$cmd .= "--user '$emailUser:$emailPass' --mail-from '$emailUser' --mail-rcpt '$emailTo' ";;\
$cmd .= "--write-out 'Email sent with status %{http_code}' ";;\
$cmd .= "-H 'Subject: $subject' ";;\
$cmd .= "-H 'From: $emailFrom' ";;\
$cmd .= "-H 'Date: $emailDate' ";;\
\
#multipart/alternative für Text und HTML EMail Body\
$cmd .= "-F '=(;;type=multipart/alternative' ";;\
\
# Leerzeichen und <br> bzw <br \> am Anfang entfernen:\
$message =~ s/^(\s|<br(?:[ \/]+)>)+//;;\
# Leerzeichen und <br> bzw <br \> am Ende entfernen:\
$message =~ s/(\s|<br(?:[ \/]+)>)+$//;;\
\
#Plaintext E-Mail Inhalt an cURL:\
$cmd .= "-F \"=$message;;type=text/plain;; charset=UTF-8\" ";;\
#ersetze \n bzw. \r\n durch ein HTML-tag <br />:\
$message =~ s/\r?\n/<br \/>/g;;\
\
#HTML E-Mail Inhalt an cURL:\
$cmd .= "-F '= <body>$message</body>;;type=text/html;; charset=UTF-8' ";;\
$cmd .= "-F '=)' ";;\
\
#jetzt alle Attachments (0..N) anhängen:\
foreach my $file (@attachments) {\
$cmd .= "-F '=@".$file.";;encoder=base64' ";;\
}\
\
#stderr auch mit in den output sammeln:\
$cmd .= " 2>&1";;\
\
#Blockierender Aufruf von cURL in dieser Funktion via BlockingCall:\
if (!defined &sendMailfunc1) {\
*sendMailfunc1 = sub ($) {\
my ($param) = @_;;\
my $result;;\
$result = qx/$param/;;\
$result = MIME::Base64::encode_base64($result);;\
$result =~ s/\n//g;;\
return $result;;\
}\
}\
\
#Rückgabe über diese Funktion,\
#anzeigen in dem reading dieses UserReadings:\
if (!defined &sendMailfunc2) {\
*sendMailfunc2 = sub ($) {\
my ($result) = @_;;\
my $hash = $defs{$name};;\
$result = MIME::Base64::decode_base64($result);;\
readingsSingleUpdate($hash, $reading, $result, 1);;\
}\
}\
\
#funktion falls BlockingCall abgebrochen wird:\
if (!defined &sendMailfunc3) {\
*sendMailfunc3 = sub ($) {\
my ($result) = @_;;\
my $hash = $defs{$name};;\
readingsSingleUpdate($hash, $reading, $result, 1);;\
}\
}\
\
BlockingCall("sendMailfunc1", $cmd, "sendMailfunc2", 20, "sendMailfunc3", "Error: timeout");;\
\
return "started cURL command...";;\
},\
state:password:.* {\
# Passwort speichern\
my $ret = setKeyValue("${name}_password", ReadingsVal($name, 'password', undef)) // "password stored";;\
\
#password wieder aus der Variablen rausnehmen, soll nicht sichtbar bleiben:\
#\
# Hinweis: das Password taucht beim Setzen hierüber im Event-Log auf!\
# Alternativ: { setKeyValue("sendMail_password", "geheimesPasswort") }\
readingsBulkUpdate($hash, "password", "****");;\
\
return "$ret";;\
}
</syntaxhighlight>Das Passwort setzt man mit:

* <code>set sendMail password geheimesPasswort</code>
* Alternativ, damit das Passwort nicht im Log auftaucht: <code>{ setKeyValue("sendMail_password", "geheimesPasswort") }</code>

E-Mails kann man dann Senden mit:

* <code>set sendMail message Mein Text</code> (es wird der Standardbetreff und Empfänger aus dem Snippet genutzt)
* <code>set sendMail message Betreff="Mein Betreff" Mein Text</code>(es wird der Empfänger aus dem Snippet genutzt)
* <code>set sendMail message Subject="Dies ist ein Test" Mein Text</code>
* <code>set sendMail message To="jemand@example.com" Mein Text</code>
* <code>set sendMail message An="jemand@example.com" Mein Text</code>
* <code>set sendMail message An="jemand@example.com" Betreff="Mein Betreff" Mein Text</code>
* <code>set sendMail message To="jemand@example.com" Subject="Mein Betreff" Mein Text</code>
* <code>set sendMail message Subject="✅ Dies ist ein Test" Meldung mit Emoji ⚽ geht auch</code>
* Eine Datei mit anhängen: <code>set sendMail message Subject="Dies ist ein Test" Anhang="www/images/fhemSVG/bag.svg" Mein Text</code>
* Zwei Dateien mit anhängen: <code>set sendMail message Subject="Dies ist ein Test" Anhang="./www/images/fhemSVG/bag.svg" Anhang="www/images/fhemSVG/batterie.svg" Mein Text</code>, für die anzuhängenden Dateien können relative und absolute Pfade verwendet werden. Beim Vorbereiten der E-Mail wird geprüft ob die Dateien existieren, da dies sonst eine typische Fehlerquelle ist. Es wird nichts versendet wenn eine Datei nicht gefunden werden kann.

==== Klarname als Absenderadresse ====
Will man als Absenderadresse einen Klarnamen verwenden, versteht CURL das auch, wenn man folgendes ändert ([https://forum.fhem.de/index.php?topic=140814.msg1353962#msg1353962 Hinweis aus dem Forum]):<syntaxhighlight lang="perl">
#my $emailFrom = 'fhem@example.de';;\

my $emailFrom = '"Dein FHEM Server" <fhem@example.de>';;\
</syntaxhighlight>

==== Fehlersuche ====

===== Fehlende Protokolloption in cURL =====
Sollte cURL zwar installiert sein, aber keine E-Mails versenden, kann es sein, dass das Protokoll nicht einkompiliert wurde. Dies ist bei OpenWRT zum Beispiel der Fall.

So sollte es aussehen (hier ein Ubuntu), relevant ist für diese Nutzung das Protokoll smtp und smtps, das braucht man:<syntaxhighlight lang="bash">
curl -V
curl 8.5.0 (x86_64-pc-linux-gnu) libcurl/8.5.0 OpenSSL/3.0.13 zlib/1.3 brotli/1.1.0 zstd/1.5.5 libidn2/2.3.7 libpsl/0.21.2 (+libidn2/2.3.7) libssh/0.10.6/openssl/zlib nghttp2/1.59.0 librtmp/2.3 OpenLDAP/2.6.7
Release-Date: 2023-12-06, security patched: 8.5.0-2ubuntu10.6
Protocols: dict file ftp ftps gopher gophers http https imap imaps ldap ldaps mqtt pop3 pop3s rtmp rtsp scp sftp smb smbs smtp smtps telnet tftp
Features: alt-svc AsynchDNS brotli GSS-API HSTS HTTP2 HTTPS-proxy IDN IPv6 Kerberos Largefile libz NTLM PSL SPNEGO SSL threadsafe TLS-SRP UnixSockets zstd

</syntaxhighlight>
So sollte es nicht aussehen (hier ein OpenWRT):
<syntaxhighlight lang="bash">
curl: (1) Protocol "smtps" not supported

curl -V
curl 8.10.1 (arm-openwrt-linux-gnu) libcurl/8.10.1 mbedTLS/3.6.2 nghttp2/1.63.0
Release-Date: 2024-09-18
Protocols: file ftp ftps http https ipfs ipns mqtt
Features: alt-svc HSTS HTTP2 HTTPS-proxy IPv6 Largefile SSL threadsafe UnixSockets
</syntaxhighlight>
Hat man nur ein cURL ohne das Protokoll, so muss man sich das Paket leider anderweitig beschaffen (chroot, selbst kompilieren, statisch gelinkte Version, ...).

===== Falscher Port, login options =====
Einige Provider nehmen ihre TLS verschlüsselten E-Mails über einen anderen Port an, häufig Port 587 (siehe auch {{Link2Forum|Topic= 140814|Message=1340366|LinkText=diesen Forenbeitrag}}). Ggf. muss man auch mit einigen Loginoptionen experimentieren bis cURL wie gewünscht funktioniert (Stichwort: ''[https://curl.se/docs/manpage.html#--login-options --login-options]'').

===== Alte cURL Version =====
Sollte eine sehr alte cURL Version kleiner 7.67.0 genutzt werden, fehlt der Schalter <code>--no-progress-meter.</code> In solchen Fällen sollte man cURL aktualisieren. Falls dies nicht möglich ist, kann man den Schalter ersetzen durch <code>--silent --show-error</code>

===== Providerspezifisches=====
Eine lose Liste mit providerspezifischen Erfolgen und Misserfolgen:
{| class="wikitable sortable"
|+Liste mit Rückmeldungen zu E-Mail Anbietern
!Provider
!Funktioniert
!Details
|-
|Hetzner
|Ja
|<syntaxhighlight lang="perl">
my $emailServer = 'mail.your-server.de';
...
smtps://$emailServer:465
</syntaxhighlight>
|-
|Vodafone
|Ja
|Folgende Schalter sind hilfreich:<syntaxhighlight lang="perl">
--ssl-reqd --sasl-ir smtps://$emailserver:465
</syntaxhighlight>
|-
|Freenet
|Nein (nicht zuverlässig aufgrund des Spamfilters)
|Der Spamfilter lässt teilweise Nachrichten passieren, teilweise wird die Verbindung abgelehnt:
<code>''550 Spam message rejected''</code>

https://forum.fhem.de/index.php?topic=140814.msg1341872#msg1341872
|-
|T-Online
|Ja?
|<syntaxhighlight lang="perl">
my $emailServer = 'securesmtp.t-online.de';
...
smtps://$emailServer:465
</syntaxhighlight>https://forum.fhem.de/index.php?topic=140814.msg1340258#msg1340258
|-
|GMX
|Ja
|<syntaxhighlight lang="perl">
my $emailServer = 'mail.gmx.net';
...
smtps://$emailserver:465
</syntaxhighlight>https://forum.fhem.de/index.php?topic=140814.msg1341891#msg1341891
|-
|Google -> GMail
|Ja
|<syntaxhighlight lang="perl">
my $emailServer = 'smtp.gmail.com';
...
smtps://$emailserver:465
</syntaxhighlight>https://forum.fhem.de/index.php?topic=140814.msg1341891#msg1341891
|-
|Strato
|Ja
|<syntaxhighlight lang="perl">
my $emailServer = 'smtp.strato.de';
...
smtps://$emailserver:465
</syntaxhighlight>https://forum.fhem.de/index.php?topic=140814.msg1342201#msg1342201
|}

Siehe auch dazu den {{Link2Forum|Message=1341182|Topic=140814|LinkText=Forumspost}}
===EXIM4 (Debian)===
Eine Anleitung zum Versenden von E-Mails mit Exim ist als PDF verfügbar: [[Medium:Anleitung Exim4 Debian GMX.pdf|PDF]]

===SSMTP (OpenWRT, embedded Distros)===

====Installation====
<syntaxhighlight lang="bash">
opkg update
opkg install ssmtp_2.64-4_mpc85xx.ipk
</syntaxhighlight>Damit <code>ssmtp</code> funktioniert müssen die Dateien <code>/etc/ssmtp/ssmtp.conf</code> und <code>/etc/ssmtp/revaliases</code> angepasst werden.

/etc/ssmtp/ssmtp.conf
<syntaxhighlight lang="text">
root=arnold@gmx.net
mailhub=mail.gmx.net:465
rewriteDomain=gmx.net
hostname=gmx.net
FromLineOverride=YES
UseTLS=YES
#UseSTARTTLS=YES
AuthUser=arnold@gmx.net
AuthPass=Passwort_von_arnold@gmx.net
</syntaxhighlight>

/etc/ssmtp/revaliases
<syntaxhighlight lang="text">
root:arnold@gmx.net:mail.gmx.net:465
</syntaxhighlight>

In der [[99_myUtils_anlegen|99_myUtils]] folgende Unterroutine einfügen:

<syntaxhighlight lang="perl">
sub OpenWRTMail
{
my $rcpt = shift;
my $subject = shift;
my $text = shift;
my $ret = "";
my $sender = "dockstar\@heye-tammo.de";
Log 1, "sendEmail RCP: $rcpt, Subject: $subject, Text: $text";
$ret .= qx(echo -e 'to:$rcpt\n from:$sender\nsubject:$subject\n$text\n' | ssmtp $rcpt);
$ret =~ s,[\r\n]*,,g; # remove CR from return-string
Log 1, "sendEmail returned: $ret";
}
</syntaxhighlight>

===PHP Mail Funktion (Synology DiskStation)===
Beim DSM 3.2 funktioniert der <code>php-mail</code>-Befehl, so dass man mittels folgendem Modul E-Mails versenden kann:
<syntaxhighlight lang="perl">
sub sendmail($$$) {
my($empf, $subj, $nachricht) = @_;
system("php -r 'mail(\"$empf\",\"$subj\",\"$nachricht\");'");
}
</syntaxhighlight>

===Sendemail (Veraltet, Debian-basierende Distros)===
Es handelt sich um ein Perl Programm, dass man aus den Paketquellen installieren kann.

Es gibt Probleme:

*mit der TLS bzw STARTTLS Verschlüsselung (https://github.com/fhem/fhem-docker/issues/254, https://www.mail-archive.com/debian-bugs-dist@lists.debian.org/msg1915977.html) ,
*Mit der Webseite des Projekts (https://web.archive.org/web/20190906140125/http://caspian.dotconf.net/menu/Software/SendEmail); diese ist nicht mehr verfügbar und nur eine archivierte Kopie kann eingesehen werden,

weswegen diese Lösung als technisch überholt gelten sollte. Will man trotzdem <code>sendemail</code> verwenden folgenden hier die Informationen dazu:

Auf dem Server muss <code>sendemail</code> installiert werden:<syntaxhighlight lang="bash" line="1">
sudo apt-get update
sudo apt-get install sendemail libio-socket-ssl-perl libnet-ssleay-perl perl
</syntaxhighlight>Man kann die korrekte Funktion im Terminal (ohne <code>{qx()}</code> ) oder auch in der FHEM Kommandozeile testen (Hinweis: manche Provider (z.B. gmail) lassen diesen Zugang erst nach Freischaltung zu!).

''Bei Gmail muss seit dem 30.6.2022 ein separates Passwort erzeugt werden, die alte Einstellung über "Zugriff durch weniger sichere Apps" funktioniert nicht mehr. Siehe Support Seite Google: <nowiki>https://support.google.com/accounts/answer/185833</nowiki>''

''Beispiel mit Gmail über Linux Terminalfenster:''
sendemail -f 'Der.Absender@gmail.com' -t 'Der.Empfaenger@gmail.com' -u 'subject' -m 'text' -a <nowiki>''</nowiki> -s 'smtp.gmail.com:587' -xu 'Der.Absender' -xp DASSUPERGEHEIMEPASSW0RT
In der [[99 myUtils anlegen|99_myUtils]] folgende Unterroutine einfügen:<syntaxhighlight lang="perl" line="1">
######## DebianMail Mail auf dem RPi versenden ############
# $provider für SMTP Server anpassen.
# Einmal in der FHEM Kommandozeile, user und password anpassen:
# {setKeyValue("myEmailKonto",'user@domain');;setKeyValue("myEmailPasswrd",'password')}
sub DebianMail
{
my $rcpt = shift;
my $subject = shift;
my $text = shift;
my $attach = shift;
my $ret = "";
my $error;
my $konto = getKeyValue("myEmailKonto");
my $passwrd = getKeyValue("myEmailPasswrd");
my $from = $konto; # or use different KeyValue if konto is not the from email address
my $provider = "smtp.1und1.de"; # smtp.domain.tld:port see provider documentation
#Log 1, "sendEmail RCP: $rcpt";
#Log 1, "sendEmail Subject: $subject";
#Log 1, "sendEmail Text: $text";
#Log 1, "sendEmail Anhang: $attach";
if (not defined($attach)){$attach=''}
$ret .= qx(sendemail -f '$from' -t '$rcpt' -u '$subject' -m '$text' -a $attach -s '$provider' -xu '$konto' -xp '$passwrd' -o tls=auto -o message-charset=utf-8);
$ret =~ s,[\r\n]*,,g; # remove CR from return-string
Log 1, "sendemail returned: $ret";
}
###############################################################################
</syntaxhighlight>

Die Zugangsdaten für den Email-Account müssen dabei FHEM-intern gespeichert werden. Dazu gibt man einmalig über die Kommandozeile folgendes ein (user@domain und password müssen auf den Email Account geändert werden):

:<code>{setKeyValue("myEmailKonto",'user@domain');;setKeyValue("myEmailPasswrd",'password')}</code>

Um die TLS Verschlüsselung (ehem. SSL) nicht zu nutzen, muss in der viertletzten Zeile tls=no verwendet und der Port des Mailproviders auf 25 eigetragen werden. Sollte anschließend keine Mail verschickt werden, siehe Probleme.

Falls der Body-Text in einem (Android-)Mailer auf dem Handy nicht gezeigt wird, kann der Parameter '''-o message-content-type=html''' helfen.

Die Funktion kann beispielsweise folgendermaßen aufgerufen werden:
<syntaxhighlight lang="perl">
{qx(sendemail -f 'Ab\@send.er' -t 'Emp\@faeng.er' -u 'subject' -m 'text' -a 'DateinameOderLeer' -s 'smtpFQDN:port' -xu 'MailUser' -xp 'PasswortOhneKlammeraffen')}
</syntaxhighlight>
Bei allen Feldern können generell doppelte " oder einfache ' Anführungszeichen verwendet werden. Innerhalb von "" müssen Sonderzeichen wie @ aber maskiert werden, da sie sonst als Steuerzeichen interpretiert werden:

:<code>"email\@email.domain" oder 'email@email.domain'</code>

Direkt in der FHEM Kommandozeile (ohne Anhang)

:<code>{DebianMail("email\@email.domain","Subject","Text")}</code>

Die ordnungsgemäße Ausführung wird mit 71 quittiert.

Beispiele mehrere Anhänge (Es ist wichtig Dateinamen mit Leerzeichen in separate Anführungszeichen zu setzen)
{DebianMail("email\@email.domain","Subject","Text","Anhang1 Anhang2 Anhang3")}
{DebianMail('email@email.domain','Subject','Text',"'with spaces Anhang1' 'with spaces Anhang2'")}
oder (mehr als einen Empfänger, diese können durch Leerzeichen, Semikolon oder Komma getrennt sein)
define Sonstiges at *01:00:00 {\
DebianMail('email@email.domain,email2@email.domain',"Subject","Text","'Anhang1' 'Anhang2' ...");;\
}

Die archivierte Doku zu <code>sendemail</code> befindet sich in der Änderungshistorie: https://wiki.fhem.de/w/index.php?title=E-Mail_senden&oldid=37524
[[Kategorie:E-Mail]]

E-Mail senden

2025-12-21T18:21:59Z

Torxgewinde: Hinweis zum Klarnamen und E-Mail in der Absenderadresse, danke @mabula

Um aus FHEM heraus E-Mails senden zu können, gibt es unterschiedliche Methoden, abhängig von der verwendeten Plattform.

Lange Zeit war <code>sendemail</code> sehr beliebt. Da aber die Homepage des Projekts nicht mehr online ist und Probleme nur noch via erhöhtem Supportaufwand gelöst werden, sollte diese Option als veraltet betrachtet werden.

Eine Liste mit ressourcensparenden E-Mails Clients findet man bei dem OpenWRT Projekt: https://openwrt.org/docs/guide-user/services/email/smtp.client

MSGMail ist ein FHEM eigenes Modul zum Versenden, die Einrichtung ist allerdings nicht gänzlich einfach. Anfängern sei die cURL Methode empfohlen.

=== MSGMail (Linux, Windows) ===
FHEM bringt ein eigenes Device zum Senden von E-Mails mit, welches in Perl implementiert ist: [https://fhem.de/commandref.html#MSGMail MSGMail, https://fhem.de/commandref.html#MSGMail]

=== cURL (Linux, Windows) ===
[https://curl.se/ cURL] kann auf praktisch [https://curl.se/download.html jedem Betriebssystem] genutzt werden, [https://curl.se/windows/ selbst unter Windows]. Es kann direkt mit einem SMTP Server E-Mails versenden und stellt damit eine moderne, portable und sichere Option zum Versenden von E-Mails dar.

In FHEM richtet man sich ein Device ein und passt die Details (<code>$emailTo, $emailFrom, $emailServer</code>) an. Das Programm cURL muss installiert sein (z.B. mit <code>apt install curl</code>, oder durch Herunterladen und Installieren von der [https://curl.se cURL-Webseite]).<syntaxhighlight lang="perl" line="1">
defmod sendMail dummy
attr sendMail readingList message password
attr sendMail setList message:textField-long password
attr sendMail userReadings state:message:[\s\S]* {\
my $emailTo = 'du@example.com';;\
my $emailFrom = 'fhem@example.de';;\
my $emailServer = 'mail.your-server.de';;\
\
#erzeuge Datumsangabe konform zu RFC-5322:\
my @emailDateArray = split(' ', strftime("%w %d %m %Y %H:%M:%S %z", localtime));;\
$emailDateArray[0] = (qw[Sun Mon Tue Wed Thu Fri Sat])[$emailDateArray[0]] . ',';;\
$emailDateArray[2] = (qw[Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec])[$emailDateArray[2]-1];;\
my $emailDate = join(' ', @emailDateArray);;\
\
# Passwort aus getKeyValue abrufen\
my ($err, $emailPass) = getKeyValue("${name}_password");;\
if ($err || !defined $emailPass) {\
return "Error retrieving password: $err";;\
}\
\
my $message = ReadingsVal($name, 'message', '???');;\
my $subject = "$name: FHEM Nachricht";;\
\
# Betreff extrahieren und aus der Nachricht entfernen\
if ($message =~ s/(?:Subject|Betreff)=["'](.*?)["']//) {\
$subject = $1;;\
}\
\
# Empfänger extrahieren und aus der Nachricht entfernen\
if ($message =~ s/(?:To|An)=["'](.*?)["']//) {\
$emailTo = $1;;\
}\
\
#Dateianhänge bestimmen\
my @attachments;;\
while ($message =~ s/(?:Attachment|Anhang)=["'](.*?)["']//) {\
my $file = $1;;\
return ">>$file<< not found, not sending email" unless (-e $file);;\
push (@attachments, $file);;\
}\
\
#der curl Befehl wird hier aufgebaut:\
my $cmd = "curl -m 19 --noproxy '*' --no-progress-meter --ssl-reqd smtps://$emailServer:465 ";;\
$cmd .= "--user '$emailFrom:$emailPass' --mail-from '$emailFrom' --mail-rcpt '$emailTo' ";;\
$cmd .= "--write-out 'Email sent with status %{http_code}' ";;\
$cmd .= "-H 'Subject: $subject' ";;\
$cmd .= "-H 'From: $emailFrom' ";;\
$cmd .= "-H 'Date: $emailDate' ";;\
\
#multipart/alternative für Text und HTML EMail Body\
$cmd .= "-F '=(;;type=multipart/alternative' ";;\
\
# Leerzeichen und <br> bzw <br \> am Anfang entfernen:\
$message =~ s/^(\s|<br(?:[ \/]+)>)+//;;\
# Leerzeichen und <br> bzw <br \> am Ende entfernen:\
$message =~ s/(\s|<br(?:[ \/]+)>)+$//;;\
\
#Plaintext E-Mail Inhalt an cURL:\
$cmd .= "-F \"=$message;;type=text/plain;; charset=UTF-8\" ";;\
#ersetze \n bzw. \r\n durch ein HTML-tag <br />:\
$message =~ s/\r?\n/<br \/>/g;;\
\
#HTML E-Mail Inhalt an cURL:\
$cmd .= "-F '= <body>$message</body>;;type=text/html;; charset=UTF-8' ";;\
$cmd .= "-F '=)' ";;\
\
#jetzt alle Attachments (0..N) anhängen:\
foreach my $file (@attachments) {\
$cmd .= "-F '=@".$file.";;encoder=base64' ";;\
}\
\
#stderr auch mit in den output sammeln:\
$cmd .= " 2>&1";;\
\
#Blockierender Aufruf von cURL in dieser Funktion via BlockingCall:\
if (!defined &sendMailfunc1) {\
*sendMailfunc1 = sub ($) {\
my ($param) = @_;;\
my $result;;\
$result = qx/$param/;;\
$result = MIME::Base64::encode_base64($result);;\
$result =~ s/\n//g;;\
return $result;;\
}\
}\
\
#Rückgabe über diese Funktion,\
#anzeigen in dem reading dieses UserReadings:\
if (!defined &sendMailfunc2) {\
*sendMailfunc2 = sub ($) {\
my ($result) = @_;;\
my $hash = $defs{$name};;\
$result = MIME::Base64::decode_base64($result);;\
readingsSingleUpdate($hash, $reading, $result, 1);;\
}\
}\
\
#funktion falls BlockingCall abgebrochen wird:\
if (!defined &sendMailfunc3) {\
*sendMailfunc3 = sub ($) {\
my ($result) = @_;;\
my $hash = $defs{$name};;\
readingsSingleUpdate($hash, $reading, $result, 1);;\
}\
}\
\
BlockingCall("sendMailfunc1", $cmd, "sendMailfunc2", 20, "sendMailfunc3", "Error: timeout");;\
\
return "started cURL command...";;\
},\
state:password:.* {\
# Passwort speichern\
my $ret = setKeyValue("${name}_password", ReadingsVal($name, 'password', undef)) // "password stored";;\
\
#password wieder aus der Variablen rausnehmen, soll nicht sichtbar bleiben:\
#\
# Hinweis: das Password taucht beim Setzen hierüber im Event-Log auf!\
# Alternativ: { setKeyValue("sendMail_password", "geheimesPasswort") }\
readingsBulkUpdate($hash, "password", "****");;\
\
return "$ret";;\
}
</syntaxhighlight>Das Passwort setzt man mit:

* <code>set sendMail password geheimesPasswort</code>
* Alternativ, damit das Passwort nicht im Log auftaucht: <code>{ setKeyValue("sendMail_password", "geheimesPasswort") }</code>

E-Mails kann man dann Senden mit:

* <code>set sendMail message Mein Text</code> (es wird der Standardbetreff und Empfänger aus dem Snippet genutzt)
* <code>set sendMail message Betreff="Mein Betreff" Mein Text</code>(es wird der Empfänger aus dem Snippet genutzt)
* <code>set sendMail message Subject="Dies ist ein Test" Mein Text</code>
* <code>set sendMail message To="jemand@example.com" Mein Text</code>
* <code>set sendMail message An="jemand@example.com" Mein Text</code>
* <code>set sendMail message An="jemand@example.com" Betreff="Mein Betreff" Mein Text</code>
* <code>set sendMail message To="jemand@example.com" Subject="Mein Betreff" Mein Text</code>
* <code>set sendMail message Subject="✅ Dies ist ein Test" Meldung mit Emoji ⚽ geht auch</code>
* Eine Datei mit anhängen: <code>set sendMail message Subject="Dies ist ein Test" Anhang="www/images/fhemSVG/bag.svg" Mein Text</code>
* Zwei Dateien mit anhängen: <code>set sendMail message Subject="Dies ist ein Test" Anhang="./www/images/fhemSVG/bag.svg" Anhang="www/images/fhemSVG/batterie.svg" Mein Text</code>, für die anzuhängenden Dateien können relative und absolute Pfade verwendet werden. Beim Vorbereiten der E-Mail wird geprüft ob die Dateien existieren, da dies sonst eine typische Fehlerquelle ist. Es wird nichts versendet wenn eine Datei nicht gefunden werden kann.

==== Klarname als Absenderadresse ====
Will man als Absenderadresse einen Klarnamen verwenden, versteht CURL das auch, wenn man folgendes ändert ([https://forum.fhem.de/index.php?topic=140814.msg1353962#msg1353962 Hinweis aus dem Forum]):<syntaxhighlight lang="perl">
#my $emailFrom = 'fhem@example.de';;\

my $emailFrom = '"Dein FHEM Server" <fhem@example.de>';;\
</syntaxhighlight>

==== Fehlersuche ====

===== Fehlende Protokolloption in cURL =====
Sollte cURL zwar installiert sein, aber keine E-Mails versenden, kann es sein, dass das Protokoll nicht einkompiliert wurde. Dies ist bei OpenWRT zum Beispiel der Fall.

So sollte es aussehen (hier ein Ubuntu), relevant ist für diese Nutzung das Protokoll smtp und smtps, das braucht man:<syntaxhighlight lang="bash">
curl -V
curl 8.5.0 (x86_64-pc-linux-gnu) libcurl/8.5.0 OpenSSL/3.0.13 zlib/1.3 brotli/1.1.0 zstd/1.5.5 libidn2/2.3.7 libpsl/0.21.2 (+libidn2/2.3.7) libssh/0.10.6/openssl/zlib nghttp2/1.59.0 librtmp/2.3 OpenLDAP/2.6.7
Release-Date: 2023-12-06, security patched: 8.5.0-2ubuntu10.6
Protocols: dict file ftp ftps gopher gophers http https imap imaps ldap ldaps mqtt pop3 pop3s rtmp rtsp scp sftp smb smbs smtp smtps telnet tftp
Features: alt-svc AsynchDNS brotli GSS-API HSTS HTTP2 HTTPS-proxy IDN IPv6 Kerberos Largefile libz NTLM PSL SPNEGO SSL threadsafe TLS-SRP UnixSockets zstd

</syntaxhighlight>
So sollte es nicht aussehen (hier ein OpenWRT):
<syntaxhighlight lang="bash">
curl: (1) Protocol "smtps" not supported

curl -V
curl 8.10.1 (arm-openwrt-linux-gnu) libcurl/8.10.1 mbedTLS/3.6.2 nghttp2/1.63.0
Release-Date: 2024-09-18
Protocols: file ftp ftps http https ipfs ipns mqtt
Features: alt-svc HSTS HTTP2 HTTPS-proxy IPv6 Largefile SSL threadsafe UnixSockets
</syntaxhighlight>
Hat man nur ein cURL ohne das Protokoll, so muss man sich das Paket leider anderweitig beschaffen (chroot, selbst kompilieren, statisch gelinkte Version, ...).

===== Falscher Port, login options =====
Einige Provider nehmen ihre TLS verschlüsselten E-Mails über einen anderen Port an, häufig Port 587 (siehe auch {{Link2Forum|Topic= 140814|Message=1340366|LinkText=diesen Forenbeitrag}}). Ggf. muss man auch mit einigen Loginoptionen experimentieren bis cURL wie gewünscht funktioniert (Stichwort: ''[https://curl.se/docs/manpage.html#--login-options --login-options]'').

===== Alte cURL Version =====
Sollte eine sehr alte cURL Version kleiner 7.67.0 genutzt werden, fehlt der Schalter <code>--no-progress-meter.</code> In solchen Fällen sollte man cURL aktualisieren. Falls dies nicht möglich ist, kann man den Schalter ersetzen durch <code>--silent --show-error</code>

===== Providerspezifisches=====
Eine lose Liste mit providerspezifischen Erfolgen und Misserfolgen:
{| class="wikitable sortable"
|+Liste mit Rückmeldungen zu E-Mail Anbietern
!Provider
!Funktioniert
!Details
|-
|Hetzner
|Ja
|<syntaxhighlight lang="perl">
my $emailServer = 'mail.your-server.de';
...
smtps://$emailServer:465
</syntaxhighlight>
|-
|Vodafone
|Ja
|Folgende Schalter sind hilfreich:<syntaxhighlight lang="perl">
--ssl-reqd --sasl-ir smtps://$emailserver:465
</syntaxhighlight>
|-
|Freenet
|Nein (nicht zuverlässig aufgrund des Spamfilters)
|Der Spamfilter lässt teilweise Nachrichten passieren, teilweise wird die Verbindung abgelehnt:
<code>''550 Spam message rejected''</code>

https://forum.fhem.de/index.php?topic=140814.msg1341872#msg1341872
|-
|T-Online
|Ja?
|<syntaxhighlight lang="perl">
my $emailServer = 'securesmtp.t-online.de';
...
smtps://$emailServer:465
</syntaxhighlight>https://forum.fhem.de/index.php?topic=140814.msg1340258#msg1340258
|-
|GMX
|Ja
|<syntaxhighlight lang="perl">
my $emailServer = 'mail.gmx.net';
...
smtps://$emailserver:465
</syntaxhighlight>https://forum.fhem.de/index.php?topic=140814.msg1341891#msg1341891
|-
|Google -> GMail
|Ja
|<syntaxhighlight lang="perl">
my $emailServer = 'smtp.gmail.com';
...
smtps://$emailserver:465
</syntaxhighlight>https://forum.fhem.de/index.php?topic=140814.msg1341891#msg1341891
|-
|Strato
|Ja
|<syntaxhighlight lang="perl">
my $emailServer = 'smtp.strato.de';
...
smtps://$emailserver:465
</syntaxhighlight>https://forum.fhem.de/index.php?topic=140814.msg1342201#msg1342201
|}

Siehe auch dazu den {{Link2Forum|Message=1341182|Topic=140814|LinkText=Forumspost}}
===EXIM4 (Debian)===
Eine Anleitung zum Versenden von E-Mails mit Exim ist als PDF verfügbar: [[Medium:Anleitung Exim4 Debian GMX.pdf|PDF]]

===SSMTP (OpenWRT, embedded Distros)===

====Installation====
<syntaxhighlight lang="bash">
opkg update
opkg install ssmtp_2.64-4_mpc85xx.ipk
</syntaxhighlight>Damit <code>ssmtp</code> funktioniert müssen die Dateien <code>/etc/ssmtp/ssmtp.conf</code> und <code>/etc/ssmtp/revaliases</code> angepasst werden.

/etc/ssmtp/ssmtp.conf
<syntaxhighlight lang="text">
root=arnold@gmx.net
mailhub=mail.gmx.net:465
rewriteDomain=gmx.net
hostname=gmx.net
FromLineOverride=YES
UseTLS=YES
#UseSTARTTLS=YES
AuthUser=arnold@gmx.net
AuthPass=Passwort_von_arnold@gmx.net
</syntaxhighlight>

/etc/ssmtp/revaliases
<syntaxhighlight lang="text">
root:arnold@gmx.net:mail.gmx.net:465
</syntaxhighlight>

In der [[99_myUtils_anlegen|99_myUtils]] folgende Unterroutine einfügen:

<syntaxhighlight lang="perl">
sub OpenWRTMail
{
my $rcpt = shift;
my $subject = shift;
my $text = shift;
my $ret = "";
my $sender = "dockstar\@heye-tammo.de";
Log 1, "sendEmail RCP: $rcpt, Subject: $subject, Text: $text";
$ret .= qx(echo -e 'to:$rcpt\n from:$sender\nsubject:$subject\n$text\n' | ssmtp $rcpt);
$ret =~ s,[\r\n]*,,g; # remove CR from return-string
Log 1, "sendEmail returned: $ret";
}
</syntaxhighlight>

===PHP Mail Funktion (Synology DiskStation)===
Beim DSM 3.2 funktioniert der <code>php-mail</code>-Befehl, so dass man mittels folgendem Modul E-Mails versenden kann:
<syntaxhighlight lang="perl">
sub sendmail($$$) {
my($empf, $subj, $nachricht) = @_;
system("php -r 'mail(\"$empf\",\"$subj\",\"$nachricht\");'");
}
</syntaxhighlight>

===Sendemail (Veraltet, Debian-basierende Distros)===
Es handelt sich um ein Perl Programm, dass man aus den Paketquellen installieren kann.

Es gibt Probleme:

*mit der TLS bzw STARTTLS Verschlüsselung (https://github.com/fhem/fhem-docker/issues/254, https://www.mail-archive.com/debian-bugs-dist@lists.debian.org/msg1915977.html) ,
*Mit der Webseite des Projekts (https://web.archive.org/web/20190906140125/http://caspian.dotconf.net/menu/Software/SendEmail); diese ist nicht mehr verfügbar und nur eine archivierte Kopie kann eingesehen werden,

weswegen diese Lösung als technisch überholt gelten sollte. Will man trotzdem <code>sendemail</code> verwenden folgenden hier die Informationen dazu:

Auf dem Server muss <code>sendemail</code> installiert werden:<syntaxhighlight lang="bash" line="1">
sudo apt-get update
sudo apt-get install sendemail libio-socket-ssl-perl libnet-ssleay-perl perl
</syntaxhighlight>Man kann die korrekte Funktion im Terminal (ohne <code>{qx()}</code> ) oder auch in der FHEM Kommandozeile testen (Hinweis: manche Provider (z.B. gmail) lassen diesen Zugang erst nach Freischaltung zu!).

''Bei Gmail muss seit dem 30.6.2022 ein separates Passwort erzeugt werden, die alte Einstellung über "Zugriff durch weniger sichere Apps" funktioniert nicht mehr. Siehe Support Seite Google: <nowiki>https://support.google.com/accounts/answer/185833</nowiki>''

''Beispiel mit Gmail über Linux Terminalfenster:''
sendemail -f 'Der.Absender@gmail.com' -t 'Der.Empfaenger@gmail.com' -u 'subject' -m 'text' -a <nowiki>''</nowiki> -s 'smtp.gmail.com:587' -xu 'Der.Absender' -xp DASSUPERGEHEIMEPASSW0RT
In der [[99 myUtils anlegen|99_myUtils]] folgende Unterroutine einfügen:<syntaxhighlight lang="perl" line="1">
######## DebianMail Mail auf dem RPi versenden ############
# $provider für SMTP Server anpassen.
# Einmal in der FHEM Kommandozeile, user und password anpassen:
# {setKeyValue("myEmailKonto",'user@domain');;setKeyValue("myEmailPasswrd",'password')}
sub DebianMail
{
my $rcpt = shift;
my $subject = shift;
my $text = shift;
my $attach = shift;
my $ret = "";
my $error;
my $konto = getKeyValue("myEmailKonto");
my $passwrd = getKeyValue("myEmailPasswrd");
my $from = $konto; # or use different KeyValue if konto is not the from email address
my $provider = "smtp.1und1.de"; # smtp.domain.tld:port see provider documentation
#Log 1, "sendEmail RCP: $rcpt";
#Log 1, "sendEmail Subject: $subject";
#Log 1, "sendEmail Text: $text";
#Log 1, "sendEmail Anhang: $attach";
if (not defined($attach)){$attach=''}
$ret .= qx(sendemail -f '$from' -t '$rcpt' -u '$subject' -m '$text' -a $attach -s '$provider' -xu '$konto' -xp '$passwrd' -o tls=auto -o message-charset=utf-8);
$ret =~ s,[\r\n]*,,g; # remove CR from return-string
Log 1, "sendemail returned: $ret";
}
###############################################################################
</syntaxhighlight>

Die Zugangsdaten für den Email-Account müssen dabei FHEM-intern gespeichert werden. Dazu gibt man einmalig über die Kommandozeile folgendes ein (user@domain und password müssen auf den Email Account geändert werden):

:<code>{setKeyValue("myEmailKonto",'user@domain');;setKeyValue("myEmailPasswrd",'password')}</code>

Um die TLS Verschlüsselung (ehem. SSL) nicht zu nutzen, muss in der viertletzten Zeile tls=no verwendet und der Port des Mailproviders auf 25 eigetragen werden. Sollte anschließend keine Mail verschickt werden, siehe Probleme.

Falls der Body-Text in einem (Android-)Mailer auf dem Handy nicht gezeigt wird, kann der Parameter '''-o message-content-type=html''' helfen.

Die Funktion kann beispielsweise folgendermaßen aufgerufen werden:
<syntaxhighlight lang="perl">
{qx(sendemail -f 'Ab\@send.er' -t 'Emp\@faeng.er' -u 'subject' -m 'text' -a 'DateinameOderLeer' -s 'smtpFQDN:port' -xu 'MailUser' -xp 'PasswortOhneKlammeraffen')}
</syntaxhighlight>
Bei allen Feldern können generell doppelte " oder einfache ' Anführungszeichen verwendet werden. Innerhalb von "" müssen Sonderzeichen wie @ aber maskiert werden, da sie sonst als Steuerzeichen interpretiert werden:

:<code>"email\@email.domain" oder 'email@email.domain'</code>

Direkt in der FHEM Kommandozeile (ohne Anhang)

:<code>{DebianMail("email\@email.domain","Subject","Text")}</code>

Die ordnungsgemäße Ausführung wird mit 71 quittiert.

Beispiele mehrere Anhänge (Es ist wichtig Dateinamen mit Leerzeichen in separate Anführungszeichen zu setzen)
{DebianMail("email\@email.domain","Subject","Text","Anhang1 Anhang2 Anhang3")}
{DebianMail('email@email.domain','Subject','Text',"'with spaces Anhang1' 'with spaces Anhang2'")}
oder (mehr als einen Empfänger, diese können durch Leerzeichen, Semikolon oder Komma getrennt sein)
define Sonstiges at *01:00:00 {\
DebianMail('email@email.domain,email2@email.domain',"Subject","Text","'Anhang1' 'Anhang2' ...");;\
}

Die archivierte Doku zu <code>sendemail</code> befindet sich in der Änderungshistorie: https://wiki.fhem.de/w/index.php?title=E-Mail_senden&oldid=37524
[[Kategorie:E-Mail]]

DevelopmentFHEMWEB-API

2025-11-22T19:11:49Z

Torxgewinde: Beispiel ergänzt

{{Randnotiz|RNTyp=r|RNText=Bitte beachten: Diese Auflistung von Funktionen wird nicht aktiv durch alle Entwickler gepflegt. Es kann daher keine Garantie auf Vollständigkeit und Korrektheit gegeben werden, entscheidend ist immer der aktuelle Programm-Code.
<hr />
Please note: This list of functions is not official maintained by all developers. So there is no guarantee for completeness and correctness, at least the program code itself is relevant.
}}
Dieses Seite soll die verfügbaren Funktionen zugänglicher machen, um das Beisteuern von Funktionalität zu erleichtern.

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

== FHEMWEB-Server (pgm2) Perl-Funktionen ==

=== Globale Variablen ===

Globale Variablen:
{| class="wikitable"
|-
! Variablenname!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$FW_ME</code>'''

|| URL-Pfad unter dem der FHEMWEB-Server via HTTP erreichbar ist.

Bsp: <code>/fhem</code>
|-
| style="vertical-align:top" | '''<code>$FW_dir</code>'''

|| Das Basisverzeichnis auf dem lokalen Filesystem des FHEMWEB-Servers.

Bsp: <code>./www</code>
|-
| style="vertical-align:top" | '''<code>$FW_CSRF</code>'''

|| Enthält das aktuell gültige CSRF-Token als HTTP URL-Parameter für die aktuelle Verbindung oder bleibt leer.

Bsp: <code>&fwcsrf=csrf_165435377333711</code>
|-
| style="vertical-align:top" | '''<code>$FW_detail</code>'''

|| Enthält den Definitionsnamen der aktuell erzeugten Detailansicht.

Bsp: <code>Licht_Wohnzimmer</code>
|-
| style="vertical-align:top" | '''<code>$FW_room</code>'''

|| Enthält den Raumnamen der aktuell erzeugten Raumansicht.

Bsp: <code>Wohnzimmer</code>
|-
| style="vertical-align:top" | '''<code>$FW_wname</code>'''

|| Enthält den Definitionsnamen der aktuellen FHEMWEB-Instanz.

Bsp: <code>WEB</code>
|-
| style="vertical-align:top" | '''<code>$FW_cname</code>'''

|| Enthält den Definitionsnamen der aktuellen Verbindung (Connection-Name).

Bsp: <code>WEB_192.168.179.65_54406</code>
|-
| style="vertical-align:top" | '''<code>$FW_userAgent</code>'''

|| Enthält den User-Agent, welcher für den aktuellen Aufruf übermittelt wurde.

Bsp: <code>Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/63.0.3239.84 Safari/537.36</code>
|}
Will man mit den Variablen zum Beispiel mittels eines Perl-Codes einen Link aufbauen, dann kann dieser wie folgt zusammengesetzt werden: <syntaxhighlight lang="perl" line="1">
my $cmd = "list";
my $link = "<a href=\"${FW_ME}?XHR=1${FW_CSRF}&cmd=${cmd}\">Klick mich</a>";
</syntaxhighlight>

=== FW_makeImage ===

:<syntaxhighlight lang="perl">$html = FW_makeImage($icon, $text, $class);</syntaxhighlight>

FW_makeImage gibt HTML-Code zurück, der ein Icon aus dem dem FHEMWEB-Iconpool beschreibt.

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

''mandatory''
|| Eine Zeichenkette, mit optionaler Farbangabe <code>'<iconname>[@fillcolor>[@strokecolor>]]'</code>
Die Farbangaben ersetzen bei SVG Dateien nur die Farbwerte für stroke und fill, sofern diese in der SVG Datei <code>#000000</code> sind. Wird also eine Angabe <code>fill:#000000</code> oder <code>fill=#000000</code> im Quelltext des SVG gefunden, wird dies ersetzt durch <code>fill:fillcolor</code> bzw. <code>fill=fillcolor</code>, je nachdem ob ein Doppelpunkt oder Gleichheitszeichen vorhanden war.
|-
| style="vertical-align:top" | '''<code>$text</code>'''

''optional''
|| Wenn hier ein Text angegeben wird und <code>$icon</code> auf eine SVG-Datei verweist, dann wird <code>$text</code> dem svg-HTML-Tag hinzugefügt. Das Resultat im HTML-Quelltext ist dann in der Art <code><svg ... data-txt="$text" ... ></code>
Wenn hier ein Text angegeben wird und <code>$icon</code> auf eine Datei verweist die nicht auf ''.svg'' endet, dann wird der Pfad von der Datei hinter <code>$icon</code> als <code><img></code> eingebunden. Das Resultat im HTML-Quelltext ist dann in der Art <code><img ... src="..." alt="$text" title="$text"></code>
|-
| style="vertical-align:top" | '''<code>$class</code>'''

''optional''
|| Eine Zeichenkette, die eine CSS-Klasse angibt.
Wird der Parameter angegeben, wird dem <img> oder <svg> <code>class="$class"</code> hinzugefügt. Ist der Parameter <code>undef</code> oder nicht übergeben, so wird kein <code>class</code>-Attribut hinzugefügt.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$html</code>'''
|| Wenn '''<code>$icon</code>''' mit einem Iconnamen aus dem FHEMWEB-Iconpool übereinstimmt, wird der HTML-Code zum Einbinden des Icons zurückgegeben.
Mit nachgestellter Farbangabe <code>'<iconname@color>'</code>, wird das Icon entsprechend eingefärbt.
Entspricht die Zeichenkette keinem Iconnamen, wird die Zeichenkette zurückgegeben.
|}

Beispiel:
* <syntaxhighlight lang="perl">$html = FW_makeImage('fts_shutter_10@red');</syntaxhighlight>

=== FW_directNotify ===

:<syntaxhighlight lang="perl">FW_directNotify($filter, $fhemweb_instance, $javascript, "");</syntaxhighlight>

FW_directNotify führt Javascript auf einer longpoll FHEMWEB-Instanz aus, ohne Events zu erzeugen.

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

''optional''
|| Eine Zeichenkette, die mit "FILTER=" beginnt <code>"FILTER=<filter expression>"</code>.
|-
| style="vertical-align:top" | '''<code>$fhemweb_instance</code>'''

''mandatory''
|| Eine Zeichenkette, die eine longpoll FHEMWEB-Instanz <code>"#FHEMWEB:<FHEMWEB devicename>"</code> angibt.<br>
|-
| style="vertical-align:top" | '''<code>$javascript</code>'''

''mandatory''
|| Eine Zeichenkette, die ein Javascript angibt.
|-
| style="vertical-align:top" | '''<code>""</code>'''

''mandatory''
|| Eine Zeichenkette, leer oder (noch zu präzisieren).

|}

Beispiele:
* <syntaxhighlight lang="perl">FW_directNotify("FILTER=room=XXX", "#FHEMWEB:WEB", "FW_okDialog('Hello world!')", "");</syntaxhighlight>
* <syntaxhighlight lang="perl">FW_directNotify("FILTER=room=XXX", "#FHEMWEB:WEB", "location.reload('true')", "");</syntaxhighlight>
* siehe auch {{Link2Forum|Topic=48736|Message=404497|LinkText=diesen Forumbeitrag}} und {{Link2Forum|Topic=134208|LinkText=dieses Forumthema}}

== FHEMWEB-Client (pgm2) Javascript-Funktionen ==

=== Globale Variablen ===

Globale Variablen:
{| class="wikitable"
|-
! Variablenname!! Bedeutung
|-
| style="vertical-align:top" | '''<code>FW_root</code>'''

|| FHEM-Ursprungsverzeichnis, steht auch im head-Element als Attribut <code>root</code> zur Verfügung.
|-
| style="vertical-align:top" | '''<code>FW_version</code>'''

|| Ein assoziatives Array, das die Versionszeichenketten der geladenen Javascript-Dateien enthält.

|}

=== FW_cmd ===

:<syntaxhighlight lang="javascript">FW_cmd(arg, callback);</syntaxhighlight>

FW_cmd führt einen Befehl auf dem FHEMWEB-Server aus.

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

''mandatory''
|| Eine Zeichenkette, die einem Befehl an den Server entspricht.
|-
| style="vertical-align:top" | '''<code>callback</code>'''

''optional''
|| Eine Javascript-Funktion, die ausgeführt wird, wenn der auf dem FHEM-Server ausgeführte Befehl einen Rückgabewert enthält, der weiter verarbeitet werden soll.

|}

Beispiel:
* <syntaxhighlight lang="javascript">FW_cmd(FW_root+'?cmd={FW_makeImage("fts_shutter_10")}&XHR=1', function(data){FW_okDialog(data)});</syntaxhighlight> Das Beispiel holt sich vom Server den HTML-Code des Icon "fts_shutter_10" und zeigt das Icon in einem Popup-Fenster an. Der vom Server auszuführende Befehl lautet <syntaxhighlight lang="perl" inline>{FW_makeImage("fts_shutter_10")}</syntaxhighlight>. An die Callback-Funktion <syntaxhighlight lang="javascript" inline>function(data){FW_okDialog(data)}</syntaxhighlight> wird der Rückgabewert vom Server als Parameter übergeben und steht als Variable <code>data</code> zur Verfügung.
* Will man mehrere Perl-Kommandos senden, kann es hilfreich sein, die Daten vor der Übertragung BASE64 zu codieren. Im Kern nutzt man eine Wrapperfunktion für FW_cmd:<syntaxhighlight lang="javascript">
function FW_cmd_perlcode(arg, callback, rep) {
let perlcode = "eval(MIME::Base64::decode_base64('" +btoa(arg)+ "'))";
return FW_cmd(FW_root + '?cmd={' + perlcode + '}&XHR=1', callback, rep);
}
</syntaxhighlight>
Weitere Details findet man in {{Link2Forum|Topic=141230|diesem Forenthema}}.

=== FW_errmsg ===

:<syntaxhighlight lang="javascript">FW_errmsg(text, timeout);</syntaxhighlight>

FW_errmsg zeigt eine Meldung im FHEMWEB-Client (Browser) an.

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

''mandatory''
|| Eine Zeichenkette, die angezeigt wird. HTML-Code wird interpretiert.
|-
| style="vertical-align:top" | '''<code>timeout</code>'''

''mandatory''
|| Anzeigedauer der Zeichenkette in Millisekunden.

|}

Beispiel:
* <syntaxhighlight lang="javascript">FW_errmsg('Hello world!',10000);</syntaxhighlight>

=== FW_okDialog ===

:<syntaxhighlight lang="javascript">FW_okDialog(txt, parent, removeFn);</syntaxhighlight>

FW_okDialog öffnet im FHEMWEB-Client (Browser) ein modales Popup-Fenster.

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

''mandatory''
|| Eine Zeichenkette, die im Popup-Fenster angezeigt wird. HTML-Code wird interpretiert.
|-
| style="vertical-align:top" | '''<code>parent</code>'''

''optional''
|| Ein Objekt zur Verankerung des Popup-Fensters, default ist das body-Element. Eine FHEM-Widget-Schnittstelle wird interpretiert.

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

''optional''
|| Eine Javascript-Funktion, die beim Schliessen des Popup-Fensters ausgeführt wird.

|}

Beispiel:
* <syntaxhighlight lang="javascript">FW_okDialog('Hello world!',10000);</syntaxhighlight>
* <syntaxhighlight lang="javascript"><a href="#!" onclick="FW_okDialog('Hello world!')">Hello</a></syntaxhighlight>

Soll das Popup-Fenster aus einem Hyperlink heraus aufgerufen werden, dann ist darauf zu achten, dass ein ungültiger Anchor Tag verwendet wird. In diesem Beispiel "!". Dadurch wird ein unkontrolliertes Scrollen der Webseite effektiv verhindert und der Dialog erscheint genau dort wo man ihn haben möchte.

=== loadScript ===

:<syntaxhighlight lang="javascript">loadScript(scriptname, callback, force);</syntaxhighlight>

loadScript läd im FHEMWEB-Client (Browser) ein Javascript nach.

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

''mandatory''
|| Eine Zeichenkette, die den Sriptnamen enthält.

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

''optional''
|| Eine Javascript-Funktion, die ausgeführt wird, wenn das Script geladen wurde.

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

''optional''
|| Ein Flag, wenn gesetzt, wird das Laden erzwungen.

|}

Beispiel:
* <syntaxhighlight lang="javascript">loadScript("pgm2/jquery.knob.min.js", function(){<Javascript-Code>});</syntaxhighlight>

=== log ===

:<syntaxhighlight lang="javascript">log(text);</syntaxhighlight>

log zeigt einen Logeintrag in der Konsole des Browsers an.

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

''mandatory''
|| Eine Zeichenkette, die angezeigt wird.

|}

Beispiel:
* <syntaxhighlight lang="javascript">log('Hello world!');</syntaxhighlight>

== Links ==

* [[DevelopmentFHEMWEB|Development FHEMWEB (englischsprachig)]]
* [[DevelopmentModuleAPI]]

[[Kategorie:Development]]

HttpUtils

2025-11-22T15:45:17Z

Torxgewinde: /* Beispiel #2 eines Snippets um eine Datei herunterzuladen und lokal zu speichern */

{{Infobox Modul
|ModPurpose=Hilfsfunktionen für HTTP-Zugriffe
|ModType=u
|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 für 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.

== Primäre Funktionen (HTTP) ==
Es ist zu beachten, dass bei den Funktionen
* <code>GetHttpFile()</code>
* <code>GetFileFromURL</code>
* <code>GetFileFromURLQuiet</code>
* <code>HttpUtils_BlockingGet</code>
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). In der Zeit, in der auf eine HTTP Antwort gewartet wird, steht FHEM dabei komplett.

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.

Um eine Blockierung zu vermeiden wird generell die Verwendung von
:<code>HttpUtils_NonblockingGet</code>
empfohlen. Diese führt den HTTP-Request asynchron durch, wodurch ein Blockieren von FHEM verhindert wird. Wie das genau funktioniert, wird in dem entsprechenden Kapitel beschrieben.

=== 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<br>
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.<br>
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.<br>
Beispiel:

* ''<nowiki>http://www.myhost.com/directory/</nowiki>''
* ''<nowiki>https://www.myhost.com/</nowiki>''
* ''<nowiki>http://www.myhost.com:8080/</nowiki>''
* ''<nowiki>http://user:password@www.myhost.com/</nowiki>''

'''WICHTIG:''' Falls ein Username sowie Passwort übergeben werden, so müssen diese vorher jeweils mittels [[#urlEncode|urlEncode()]] in URL-kompatible Form umgewandelt werden um Probleme mit evtl. enthaltenen Sonderzeichen zu vermeiden.
|-
| 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 [[verbose|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.

=== 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.<br>
Beispiel:

* ''<nowiki>http://www.myhost.com/directory/</nowiki>''
* ''<nowiki>https://www.myhost.com/</nowiki>''
* ''<nowiki>http://www.myhost.com:8080/</nowiki>''
* ''<nowiki>http://user:password@www.myhost.com/</nowiki>''

'''WICHTIG:''' Falls ein Username sowie Passwort übergeben werden, so müssen diese vorher jeweils mittels [[#urlEncode|urlEncode()]] in URL-kompatible Form umgewandelt werden um Probleme mit evtl. enthaltenen Sonderzeichen zu vermeiden.
|-
| 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 eine Hashreferenz 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.<br>
Beispiel:

* ''<nowiki>http://www.myhost.com/directory/</nowiki>''
* ''<nowiki>https://www.myhost.com/</nowiki>''
* ''<nowiki>http://www.myhost.com:8080/</nowiki>''
* ''<nowiki>http://user:password@www.myhost.com/</nowiki>''

'''WICHTIG:''' Alternativ können die Zugangsdaten auch in <code>$param->{user}</code> und <code>$param->{pwd}</code> übergeben werden. Falls Username und Passwort in der URL übergeben werden, so müssen diese vorher jeweils mittels [[#urlEncode|urlEncode()]] in URL-kompatible Form umgewandelt werden um Probleme mit evtl. enthaltenen Sonderzeichen (z.B. ":" und "@") zu vermeiden, da sonst die URL nicht mehr einer validen Syntax entspricht.
|-
| style="vertical-align:top" |'''<code>$param->{timeout}</code>'''

''optional''
|| Die maximale Dauer in Sekunden bis der Server eine Antwort liefern muss. Andernfalls wird der Request mit einer Fehlermeldung abgebrochen.

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 Zeichenkette:
:* Die Daten werden komplett als gesamte Zeichenkette in <code>$param->{data}</code> abgelegt (z.B.: <code>$param->{data} = "Jede Menge tolle Daten"</code>).
2. Daten als Hash-Struktur:
:* Die Daten werden als Hash mit Key-Value-Pairs übergeben (z.B.: <code>$param->{data}{field1} = "value1", $param{data}{field2} = "value2", ...</code> ). Die Daten werden dann als Formulardaten mit mehrfachen Datenfeldern übertragen.

Standardwert: ''[leer]''

|-
| style="vertical-align:top" | '''<code>$param->{user}</code>'''

''optional''
||Im Falle einer notwendigen HTTP-Authentifizierung, der zu benutzende Username um sich gegenüber dem Server zu identifizieren. Alternativ kann der Username und das Passwort auch direkt in der URL mitgegeben werden (siehe jedoch <code>$param->{hideurl}</code>).

Standardwert: ''[leer]''
|-
| style="vertical-align:top" | '''<code>$param->{pwd}</code>'''

''optional''
||Im Falle einer notwendigen HTTP-Authentifizierung, das zu benutzende Passwort um sich gegenüber dem Server zu identifizieren. Alternativ kann der Username und das Passwort auch direkt in der URL mitgegeben werden (siehe jedoch <code>$param->{hideurl}</code>).
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 gesamte URL in sämtlichen Log-Ausgaben unkenntlich gemacht. Dies notwendig, wenn z.B. Zugangsdaten direkt in der URL angegeben wurden, oder die URL ein geheimes Token oder andere schützenswerte Informationen enthält.

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->{keepalive}</code>'''

''optional''
||Wenn dieser Parameter auf 1 gesetzt ist, wird dem Server der Wunsch mitgeteilt, die Verbindung offen zu lassen für weitere Anfragen. Sobald die Antwort auf den jeweiligen Request eintrifft, bleibt die TCP-Verbindung bestehen (sofern der Server dies unterstützt). Anschließend kann man den Parameter-Hash mit einer neuen URL und Optionen füllen. Der Parameter "keepalive" sollte dabei weiterhin gesetzt bleiben, sofern die Verbindung auch weiterhin möglichst erhalten bleiben soll.

Um eine offene Verbindung endgültig zu schließen, muss die Funktion [[HttpUtils#HttpUtils_Close|HttpUtils_Close]] aufgerufen werden.

Standardwert: 0
|-
| 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. Es gibt zwei Möglichkeiten, diesen Parameter zu befüllen.

# Als '''Zeichenkette'''. Mehrere Header-Zeilen müssen dabei mit "\r\n" getrennt werden.
# Als '''Hash-Struktur'''. Hierbei findet eine Zuordnung von Header-Bezeichnung zum Wert als Key-Value-Pair statt.

Beispiel:
* <code>"User-Agent: Mozilla/1.22'''<u>\r\n</u>'''Content-Type: application/xml"</code>
* <code>"Content-Type: application/xml"</code>
* <code>{ "User-Agent" => "Mozilla/1.22", "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 => 0, 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"
|-
| style="vertical-align:top" | '''<code>$param->{digest}</code>'''

''optional''
|| Wenn dieser Parameter den Wert 1 trägt, wird bei vorhandenen Authentifizierungsdaten (Username+Passwort) eine Authentifizierung via Digest-Verfahren nach RFC 2617<ref name="rfc2617">RFC 2617 - HTTP Authentication: Basic and Digest Access Authentication</ref> erwartet. Die Anmeldedaten werden dann nur verwendet, wenn dieser explizit eine HTTP Digest Authentifizierung einleitet. Ist dieser Parameter nicht gesetzt (Wert: 0), wird bei vorhandenen Authentifizierungsdaten immer eine HTTP Basic<ref name="rfc2617" /> Authentifizierung im Request mitgeschickt.

Standardwert: 0
|-
| style="vertical-align:top" | '''<code>$param->{compress}</code>'''

''optional''
|| Wenn dieser Parameter den Wert 1 trägt, wird dem Server die Verwendung von Komprimierung in Form GZIP oder alternativ Deflate<ref>RFC 1951 - DEFLATE Compressed Data Format Specification version 1.3</ref> zur Übertragung der Antwort ermöglicht. Die komprimierte Antwort wird dabei direkt durch HttpUtils.pm wieder dekomprimiert. Wird dieser Parameter auf den Wert 0 gesetzt, so wird keine Komrpimierung ermöglicht.

'''WICHTIG''': Die Verwendung von Komprimierung in HttpUtils.pm kann mit dem globalen Attribut "httpcompress" (Standardwert: 1) durch setzen auf 0 für die gesamte FHEM Installation durch den Nutzer deaktiviert werden. In diesem Fall ist der Parameter <code>$param->{compress} = 1</code> wirkungslos.

Standardwert: 1
|}

Als Rückgabewert von HttpUtils_BlockingGet wird ein Array mit zwei Rückgabewerten zurückgegeben:
:<code>($err, $data) = HttpUtils_BlockingGet( … )</code>
Diese zwei Rückgabewerte 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 weiterhin 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" | '''''<br>Alle Hash-Parameter, welche für HttpUtils_BlockingGet gelten, sind auch für HttpUtils_NonblockingGet gültig'''''<br>
|-
| 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;white-space:nowrap;" | '''<code>$param->{incrementalTimeout}</code>'''

''optional''
|| Sofern gesetzt (Wert: <code>1</code>), wird der Timeout nach jedem Empfang von Teil-Daten wieder zurückgesetzt. So können größere Datenmengen von langsamen Sendern empfangen werden, ohne den Parameter <code>timeout</code> zu erhöhen und dadurch tatsächliche Verbindungsprobleme erst spät zu erkennen.

Standardwert: 0
|-
| 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 im Rahmen der Modul-Programmierung wäre das <code>$hash</code> der aktuellen Definition. Alle gesetzten Parameter sind in der Callback-Funktion wieder über <code>$param</code> 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>''' - Ein Flag (0/1) ob Zugangsdaten für den Request zur Verfügung standen (durch Angabe in der URL oder direkt in <code>$param</code>).
|-
| 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 Fehlern entsprechende Log-Meldungen ausgeben.

==== Beispiel #1 für HttpUtils_NonblockingGet() für Modulprogrammierer ====
Das folgende Beispiel soll eine Hilfestellung für eigene Anwendungen geben

<syntaxhighlight lang="perl">use HttpUtils;
sub X_PerformHttpRequest($)
{
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 => "User-Agent: TeleHeater/2.2.3\r\nAccept: application/json", # Den Header gemäß 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", 0); # 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, 0); # Readings erzeugen
}

# Damit ist die Abfrage zuende.
# Evtl. einen InternalTimer neu schedulen
}</syntaxhighlight>

==== Beispiel #2 eines Snippets um eine Datei herunterzuladen und lokal zu speichern ====
Dieses vollständige Beispiel eines Device verwendet <code>HttpUtils_NonblockingGet()</code> um eine Datei herunterzuladen und im lokalem Dateisystem mit den Rechten des FHEM Nutzers zu speichern.<syntaxhighlight lang="perl" line="1">
defmod MyDownloader dummy
attr MyDownloader userattr FilePath
attr MyDownloader comment '\
Beispiel:\
set MyDownloader job Filepath="/opt/fhem/www/Dateiname.bin" https://example.com/datei.bin\
'
attr MyDownloader readingList job
attr MyDownloader setList job
attr MyDownloader userReadings result:job:.* {\
my $hash = $defs{$name};;\
my $job = ReadingsVal($name, "job", 'https://fhem.de/www/images/default/fhemicon.png');;\
my $path = AttrVal($name, "Filepath", "/opt/fhem/www/download.bin");;\
\
if ($job =~ s/(?:Filepath|Dateipfad)="(.*?)"//) {\
$path = $1;;\
}\
\
my $fnFct = sub {\
my ($param, $err, $data) = @_;;\
\
my $len = $data ? length($data) : 0;;\
my $error = $err ? $err : FileWrite($path, $data);;\
\
readingsBeginUpdate($hash);;\
readingsBulkUpdate($hash, "busy", 0, 1);;\
readingsBulkUpdate($hash, "result", "saved $len Bytes", 1) if !$error;;\
readingsBulkUpdate($hash, "result", "error ($error, $err)", 1) if $error;;\
readingsEndUpdate($hash, 1);;\
};;\
\
if ( ReadingsVal($name, "busy", 0) == 0 ) {\
readingsBulkUpdate($hash, "busy", 1, 1);;\
$job =~ s/^\s+|\s+$//g;;\
my $param = {\
url => $job,\
timeout => 10,\
hash => $hash,\
method => "GET",\
callback => $fnFct\
};;\
HttpUtils_NonblockingGet($param);;\
return "download job started";;\
}\
\
return;;\
}
</syntaxhighlight>Zugehöriger Forumspost: [https://forum.fhem.de/index.php?topic=143117.msg1352221#msg1352221 📂 Datei herunterladen, Downloader, HttpUtils_NonblockingGet]

=== 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.

Wenn man den Parameter "keepalive" beim Aufruf von HttpUtils_NonBlockingGet/HttpUtils_BlockingGet gesetzt hat, muss man HttpUtils_Close aufrufen um die Verbindung tatsächlich zu schließen, da diese noch durch den Server offen gehalten werden kann.

'''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

|}

== Hilfsfunktionen ==

=== urlEncode ===

:<syntaxhighlight lang="perl">
$encoded = urlEncode($string);
</syntaxhighlight>
Die Funktion urlEncode() wandelt die übergebene Zeichenkette <code>$string</code> in eine URL-kompatible<ref name="rfc3986-2.1">[https://tools.ietf.org/html/rfc3986#section-2.1 RFC 3989] - Abschnitt 2.1 "Percent-Encoding"</ref> Zeichenkette um. Der Rückgabewert <code>$encoded</code> ist eine Zeichenkette welche innerhalb einer URL verwendet werden kann, bspw. als Wert eines GET-Parameters.

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

''mandatory''
|| Die Zeichenkette, welche in eine URL-kompatible Form umgewandelt werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$encoded </code>''' || Die URL-kompatible Version der übergebenen Zeichenkette. Problematische Zeichen sind in diesem Wert durch ein Prozentzeichen gefolgt von der Hexadezimaldarstellung des Zeichens dargestellt.

Bsp:
* "a: b" => "a%3a%20b"
* "a/b" => "a%2fb"
|}

=== urlDecode ===

:<syntaxhighlight lang="perl">
$string = urlDecode($encoded);
</syntaxhighlight>
Die Funktion urlDecode () normalisiert die übergebene Zeichenkette <code>$encoded</code> und ersetzt dabei sämtliche Hexadezimaldarstellungen<ref name="rfc3986-2.1" /> (eingeleitet mit einem Prozentzeichen) durch die entsprechenden Zeichen. Der Rückgabewert <code>$string</code> ist eine Zeichenkette welche keinerlei Hexadezimaldarstellungen mehr aufweist.

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

''mandatory''
|| Eine Zeichenkette, welche URL-kombatible Hexadezimaldarstellungen enthält.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$string</code>''' || Die normale Version der übergebenen Zeichenkette. Sämtliche Hexadezimalddarstellungen sind in ihre entsprechenden Zeichen umgewandelt.

Bsp:
* "a%3a%20b" => "a: b"
* "a%2fb" => "a/b"
|}

== Referenzen ==

<references />

[[Kategorie:Development]]

HttpUtils

2025-11-22T15:42:12Z

Torxgewinde: Weiteres Beispiel hinugefügt

{{Infobox Modul
|ModPurpose=Hilfsfunktionen für HTTP-Zugriffe
|ModType=u
|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 für 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.

== Primäre Funktionen (HTTP) ==
Es ist zu beachten, dass bei den Funktionen
* <code>GetHttpFile()</code>
* <code>GetFileFromURL</code>
* <code>GetFileFromURLQuiet</code>
* <code>HttpUtils_BlockingGet</code>
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). In der Zeit, in der auf eine HTTP Antwort gewartet wird, steht FHEM dabei komplett.

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.

Um eine Blockierung zu vermeiden wird generell die Verwendung von
:<code>HttpUtils_NonblockingGet</code>
empfohlen. Diese führt den HTTP-Request asynchron durch, wodurch ein Blockieren von FHEM verhindert wird. Wie das genau funktioniert, wird in dem entsprechenden Kapitel beschrieben.

=== 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<br>
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.<br>
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.<br>
Beispiel:

* ''<nowiki>http://www.myhost.com/directory/</nowiki>''
* ''<nowiki>https://www.myhost.com/</nowiki>''
* ''<nowiki>http://www.myhost.com:8080/</nowiki>''
* ''<nowiki>http://user:password@www.myhost.com/</nowiki>''

'''WICHTIG:''' Falls ein Username sowie Passwort übergeben werden, so müssen diese vorher jeweils mittels [[#urlEncode|urlEncode()]] in URL-kompatible Form umgewandelt werden um Probleme mit evtl. enthaltenen Sonderzeichen zu vermeiden.
|-
| 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 [[verbose|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.

=== 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.<br>
Beispiel:

* ''<nowiki>http://www.myhost.com/directory/</nowiki>''
* ''<nowiki>https://www.myhost.com/</nowiki>''
* ''<nowiki>http://www.myhost.com:8080/</nowiki>''
* ''<nowiki>http://user:password@www.myhost.com/</nowiki>''

'''WICHTIG:''' Falls ein Username sowie Passwort übergeben werden, so müssen diese vorher jeweils mittels [[#urlEncode|urlEncode()]] in URL-kompatible Form umgewandelt werden um Probleme mit evtl. enthaltenen Sonderzeichen zu vermeiden.
|-
| 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 eine Hashreferenz 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.<br>
Beispiel:

* ''<nowiki>http://www.myhost.com/directory/</nowiki>''
* ''<nowiki>https://www.myhost.com/</nowiki>''
* ''<nowiki>http://www.myhost.com:8080/</nowiki>''
* ''<nowiki>http://user:password@www.myhost.com/</nowiki>''

'''WICHTIG:''' Alternativ können die Zugangsdaten auch in <code>$param->{user}</code> und <code>$param->{pwd}</code> übergeben werden. Falls Username und Passwort in der URL übergeben werden, so müssen diese vorher jeweils mittels [[#urlEncode|urlEncode()]] in URL-kompatible Form umgewandelt werden um Probleme mit evtl. enthaltenen Sonderzeichen (z.B. ":" und "@") zu vermeiden, da sonst die URL nicht mehr einer validen Syntax entspricht.
|-
| style="vertical-align:top" |'''<code>$param->{timeout}</code>'''

''optional''
|| Die maximale Dauer in Sekunden bis der Server eine Antwort liefern muss. Andernfalls wird der Request mit einer Fehlermeldung abgebrochen.

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 Zeichenkette:
:* Die Daten werden komplett als gesamte Zeichenkette in <code>$param->{data}</code> abgelegt (z.B.: <code>$param->{data} = "Jede Menge tolle Daten"</code>).
2. Daten als Hash-Struktur:
:* Die Daten werden als Hash mit Key-Value-Pairs übergeben (z.B.: <code>$param->{data}{field1} = "value1", $param{data}{field2} = "value2", ...</code> ). Die Daten werden dann als Formulardaten mit mehrfachen Datenfeldern übertragen.

Standardwert: ''[leer]''

|-
| style="vertical-align:top" | '''<code>$param->{user}</code>'''

''optional''
||Im Falle einer notwendigen HTTP-Authentifizierung, der zu benutzende Username um sich gegenüber dem Server zu identifizieren. Alternativ kann der Username und das Passwort auch direkt in der URL mitgegeben werden (siehe jedoch <code>$param->{hideurl}</code>).

Standardwert: ''[leer]''
|-
| style="vertical-align:top" | '''<code>$param->{pwd}</code>'''

''optional''
||Im Falle einer notwendigen HTTP-Authentifizierung, das zu benutzende Passwort um sich gegenüber dem Server zu identifizieren. Alternativ kann der Username und das Passwort auch direkt in der URL mitgegeben werden (siehe jedoch <code>$param->{hideurl}</code>).
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 gesamte URL in sämtlichen Log-Ausgaben unkenntlich gemacht. Dies notwendig, wenn z.B. Zugangsdaten direkt in der URL angegeben wurden, oder die URL ein geheimes Token oder andere schützenswerte Informationen enthält.

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->{keepalive}</code>'''

''optional''
||Wenn dieser Parameter auf 1 gesetzt ist, wird dem Server der Wunsch mitgeteilt, die Verbindung offen zu lassen für weitere Anfragen. Sobald die Antwort auf den jeweiligen Request eintrifft, bleibt die TCP-Verbindung bestehen (sofern der Server dies unterstützt). Anschließend kann man den Parameter-Hash mit einer neuen URL und Optionen füllen. Der Parameter "keepalive" sollte dabei weiterhin gesetzt bleiben, sofern die Verbindung auch weiterhin möglichst erhalten bleiben soll.

Um eine offene Verbindung endgültig zu schließen, muss die Funktion [[HttpUtils#HttpUtils_Close|HttpUtils_Close]] aufgerufen werden.

Standardwert: 0
|-
| 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. Es gibt zwei Möglichkeiten, diesen Parameter zu befüllen.

# Als '''Zeichenkette'''. Mehrere Header-Zeilen müssen dabei mit "\r\n" getrennt werden.
# Als '''Hash-Struktur'''. Hierbei findet eine Zuordnung von Header-Bezeichnung zum Wert als Key-Value-Pair statt.

Beispiel:
* <code>"User-Agent: Mozilla/1.22'''<u>\r\n</u>'''Content-Type: application/xml"</code>
* <code>"Content-Type: application/xml"</code>
* <code>{ "User-Agent" => "Mozilla/1.22", "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 => 0, 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"
|-
| style="vertical-align:top" | '''<code>$param->{digest}</code>'''

''optional''
|| Wenn dieser Parameter den Wert 1 trägt, wird bei vorhandenen Authentifizierungsdaten (Username+Passwort) eine Authentifizierung via Digest-Verfahren nach RFC 2617<ref name="rfc2617">RFC 2617 - HTTP Authentication: Basic and Digest Access Authentication</ref> erwartet. Die Anmeldedaten werden dann nur verwendet, wenn dieser explizit eine HTTP Digest Authentifizierung einleitet. Ist dieser Parameter nicht gesetzt (Wert: 0), wird bei vorhandenen Authentifizierungsdaten immer eine HTTP Basic<ref name="rfc2617" /> Authentifizierung im Request mitgeschickt.

Standardwert: 0
|-
| style="vertical-align:top" | '''<code>$param->{compress}</code>'''

''optional''
|| Wenn dieser Parameter den Wert 1 trägt, wird dem Server die Verwendung von Komprimierung in Form GZIP oder alternativ Deflate<ref>RFC 1951 - DEFLATE Compressed Data Format Specification version 1.3</ref> zur Übertragung der Antwort ermöglicht. Die komprimierte Antwort wird dabei direkt durch HttpUtils.pm wieder dekomprimiert. Wird dieser Parameter auf den Wert 0 gesetzt, so wird keine Komrpimierung ermöglicht.

'''WICHTIG''': Die Verwendung von Komprimierung in HttpUtils.pm kann mit dem globalen Attribut "httpcompress" (Standardwert: 1) durch setzen auf 0 für die gesamte FHEM Installation durch den Nutzer deaktiviert werden. In diesem Fall ist der Parameter <code>$param->{compress} = 1</code> wirkungslos.

Standardwert: 1
|}

Als Rückgabewert von HttpUtils_BlockingGet wird ein Array mit zwei Rückgabewerten zurückgegeben:
:<code>($err, $data) = HttpUtils_BlockingGet( … )</code>
Diese zwei Rückgabewerte 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 weiterhin 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" | '''''<br>Alle Hash-Parameter, welche für HttpUtils_BlockingGet gelten, sind auch für HttpUtils_NonblockingGet gültig'''''<br>
|-
| 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;white-space:nowrap;" | '''<code>$param->{incrementalTimeout}</code>'''

''optional''
|| Sofern gesetzt (Wert: <code>1</code>), wird der Timeout nach jedem Empfang von Teil-Daten wieder zurückgesetzt. So können größere Datenmengen von langsamen Sendern empfangen werden, ohne den Parameter <code>timeout</code> zu erhöhen und dadurch tatsächliche Verbindungsprobleme erst spät zu erkennen.

Standardwert: 0
|-
| 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 im Rahmen der Modul-Programmierung wäre das <code>$hash</code> der aktuellen Definition. Alle gesetzten Parameter sind in der Callback-Funktion wieder über <code>$param</code> 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>''' - Ein Flag (0/1) ob Zugangsdaten für den Request zur Verfügung standen (durch Angabe in der URL oder direkt in <code>$param</code>).
|-
| 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 Fehlern entsprechende Log-Meldungen ausgeben.

==== Beispiel #1 für HttpUtils_NonblockingGet() für Modulprogrammierer ====
Das folgende Beispiel soll eine Hilfestellung für eigene Anwendungen geben

<syntaxhighlight lang="perl">use HttpUtils;
sub X_PerformHttpRequest($)
{
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 => "User-Agent: TeleHeater/2.2.3\r\nAccept: application/json", # Den Header gemäß 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", 0); # 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, 0); # Readings erzeugen
}

# Damit ist die Abfrage zuende.
# Evtl. einen InternalTimer neu schedulen
}</syntaxhighlight>

==== Beispiel #2 eines Snippets um eine Datei herunterzuladen und lokal zu speichern ====
Dieses vollständige Beispiel eines Device verwendet <code>HttpUtils_NonblockingGet()</code> um eine Datei herunterzuladen und im lokalem Dateisystem mit den Rechten des FHEM Nutzers zu speichern.<syntaxhighlight lang="perl" line="1">
defmod MyDownloader dummy
attr MyDownloader userattr FilePath
attr MyDownloader FilePath /opt/fhem/www/webhook/tasmota.bin.gz
attr MyDownloader comment '\
set MyDownloader job Filepath="/opt/fhem/fhemicon.png"https://fhem.de/www/images/default/fhemicon.png\
set MyDownloader job https://fhem.de/www/images/default/fhemicon.png\
\
set MyDownloader job Filepath="/opt/fhem/www/webhook/tasmota.bin" https://ota.tasmota.com/tasmota/release/tasmota.bin\
set MyDownloader job Filepath="/opt/fhem/www/webhook/tasmota.bin.gz" https://ota.tasmota.com/tasmota/release/tasmota.bin.gz\
set MyDownloader job Filepath="/opt/fhem/www/webhook/tasmota-minimal.bin.gz" https://ota.tasmota.com/tasmota/release/tasmota-minimal.bin.gz\
set MyDownloader job Filepath="/opt/fhem/www/webhook/tasmota32-zbbrdgpro.bin" https://ota.tasmota.com/tasmota32/release/tasmota32-zbbrdgpro.bin\
\
set MyDownloader job Filepath="/opt/fhem/www/webhook/tasmota.bin" https://ota.tasmota.com/tasmota/release/tasmota.bin;; sleep 5;; set MyDownloader job Filepath="/opt/fhem/www/webhook/tasmota.bin.gz" https://ota.tasmota.com/tasmota/release/tasmota.bin.gz;; sleep 5;; set MyDownloader job Filepath="/opt/fhem/www/webhook/tasmota-minimal.bin.gz" https://ota.tasmota.com/tasmota/release/tasmota-minimal.bin.gz;; sleep 5;; set MyDownloader job Filepath="/opt/fhem/www/webhook/tasmota32-zbbrdgpro.bin" https://ota.tasmota.com/tasmota32/release/tasmota32-zbbrdgpro.bin\
'
attr MyDownloader readingList job
attr MyDownloader setList job
attr MyDownloader userReadings result:job:.* {\
my $hash = $defs{$name};;\
my $job = ReadingsVal($name, "job", 'https://fhem.de/www/images/default/fhemicon.png');;\
my $path = AttrVal($name, "Filepath", "/opt/fhem/www/download.bin");;\
\
if ($job =~ s/(?:Filepath|Dateipfad)="(.*?)"//) {\
$path = $1;;\
}\
\
my $fnFct = sub {\
my ($param, $err, $data) = @_;;\
\
my $len = $data ? length($data) : 0;;\
my $error = $err ? $err : FileWrite($path, $data);;\
\
readingsBeginUpdate($hash);;\
readingsBulkUpdate($hash, "busy", 0, 1);;\
readingsBulkUpdate($hash, "result", "saved $len Bytes", 1) if !$error;;\
readingsBulkUpdate($hash, "result", "error ($error, $err)", 1) if $error;;\
readingsEndUpdate($hash, 1);;\
};;\
\
if ( ReadingsVal($name, "busy", 0) == 0 ) {\
readingsBulkUpdate($hash, "busy", 1, 1);;\
$job =~ s/^\s+|\s+$//g;;\
my $param = {\
url => $job,\
timeout => 10,\
hash => $hash,\
method => "GET",\
callback => $fnFct\
};;\
HttpUtils_NonblockingGet($param);;\
return "download job started";;\
}\
\
return;;\
}
</syntaxhighlight>Zugehöriger Forumspost: [https://forum.fhem.de/index.php?topic=143117.msg1352221#msg1352221 📂 Datei herunterladen, Downloader, HttpUtils_NonblockingGet]

=== 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.

Wenn man den Parameter "keepalive" beim Aufruf von HttpUtils_NonBlockingGet/HttpUtils_BlockingGet gesetzt hat, muss man HttpUtils_Close aufrufen um die Verbindung tatsächlich zu schließen, da diese noch durch den Server offen gehalten werden kann.

'''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

|}

== Hilfsfunktionen ==

=== urlEncode ===

:<syntaxhighlight lang="perl">
$encoded = urlEncode($string);
</syntaxhighlight>
Die Funktion urlEncode() wandelt die übergebene Zeichenkette <code>$string</code> in eine URL-kompatible<ref name="rfc3986-2.1">[https://tools.ietf.org/html/rfc3986#section-2.1 RFC 3989] - Abschnitt 2.1 "Percent-Encoding"</ref> Zeichenkette um. Der Rückgabewert <code>$encoded</code> ist eine Zeichenkette welche innerhalb einer URL verwendet werden kann, bspw. als Wert eines GET-Parameters.

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

''mandatory''
|| Die Zeichenkette, welche in eine URL-kompatible Form umgewandelt werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$encoded </code>''' || Die URL-kompatible Version der übergebenen Zeichenkette. Problematische Zeichen sind in diesem Wert durch ein Prozentzeichen gefolgt von der Hexadezimaldarstellung des Zeichens dargestellt.

Bsp:
* "a: b" => "a%3a%20b"
* "a/b" => "a%2fb"
|}

=== urlDecode ===

:<syntaxhighlight lang="perl">
$string = urlDecode($encoded);
</syntaxhighlight>
Die Funktion urlDecode () normalisiert die übergebene Zeichenkette <code>$encoded</code> und ersetzt dabei sämtliche Hexadezimaldarstellungen<ref name="rfc3986-2.1" /> (eingeleitet mit einem Prozentzeichen) durch die entsprechenden Zeichen. Der Rückgabewert <code>$string</code> ist eine Zeichenkette welche keinerlei Hexadezimaldarstellungen mehr aufweist.

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

''mandatory''
|| Eine Zeichenkette, welche URL-kombatible Hexadezimaldarstellungen enthält.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$string</code>''' || Die normale Version der übergebenen Zeichenkette. Sämtliche Hexadezimalddarstellungen sind in ihre entsprechenden Zeichen umgewandelt.

Bsp:
* "a%3a%20b" => "a: b"
* "a%2fb" => "a/b"
|}

== Referenzen ==

<references />

[[Kategorie:Development]]

Gleitende Mittelwerte berechnen und loggen

2025-09-21T10:16:29Z

Torxgewinde: SVG Plot von Temperaturen und dem Mittelwert

[[Datei:SVG Plot von Temperaturen und dem Mittelwert.png|alternativtext=SVG Plot von Temperaturen und dem Mittelwert|ohne|mini|SVG Plot von Temperaturen und dem Mittelwert]]

Für verschiedene Wettersensoren ist es oftmals wünschenswert, gleitende Mittelwerte (fälschlich auch als "relative" Mittelwerte bezeichnet) über ein bestimmtes Zeitfenster auszugeben oder in den Logs zu speichern und zu plotten. Beispiele:
* Die momentanen Winddaten eines KS300 sind oft stark schwankend. Hier wäre ein Mittelwert z.B. der letzten 2-3 Stunden interessant.
* Für die Außentemperatur ist anhand eines Mittelwertes der letzten 24 Stunden evtl. ein gewisser Trend der generellen Entwicklung der Temperatur ableitbar.

Mit Modulen wie ''rain'' oder ''average'' ist konzeptbedingt nur ein Mittelwert von fixen Zeiträumen (aktueller Tag, Monat, etc.) möglich.

Im Nachfolgenden werden deshalb zwei Programme vorgestellt, die solche gleitenden Mittelwerte bereitstellen. Beide Programme werden in die Datei [[99 myUtils anlegen|99_MyUtils.pm]] eingetragen und dann von FHEM aufgerufen. Das erste Programm macht dies für beliebige Readings beliebiger Devices, das zweite Programm greift auf beliebige [[FileLog|File-]] oder [[DbLog|DbLogs]] zurück.

== Gleitender Mittelwert für beliebige Readings ==
=== Subroutine movingAverage in 99_MyUtils anlegen ===
Es werden die Funktionen ''movingAverage'' und ''movingAverageT'' in die 99_MyUtils Datei übernommen werden. Wenn noch nicht vorhanden, sollte die Datei dann so aussehen, der übliche Speicherort ist ''/opt/fhem/FHEM/99_MyUtils.pm''

<syntaxhighlight lang="perl" line="1">package main;
use strict;
use warnings;
sub
MyUtils_Initialize($$)
{
my ($hash) = @_;
}
###############################################################################
#
# Moving average
#
# Aufruf: movingAverage(devicename,readingname,zeitspanne in s)
#
###############################################################################

sub movingAverage($$$){
my ($name,$reading,$avtime) = @_;
my $hash = $defs{$name};
my @new = my ($val,$time) = ($hash->{READINGS}{$reading}{VAL},$hash->{READINGS}{$reading}{TIME});
my ($cyear, $cmonth, $cday, $chour, $cmin, $csec) = $time =~ /(\d+)-(\d+)-(\d+)\s(\d+):(\d+):(\d+)/;
my $ctime = $csec+60*$cmin+3600*$chour;
my $num;
my $arr;
#-- initialize if requested
if( ($avtime eq "-1") ){
$hash->{READINGS}{$reading}{"history"}=undef;
}
#-- test for existence
if( !$hash->{READINGS}{$reading}{"history"}){
#Log 1,"ARRAY CREATED";
push(@{$hash->{READINGS}{$reading}{"history"}},\@new);
$num = 1;
$arr=\@{$hash->{READINGS}{$reading}{"history"}};
} else {
$num = int(@{$hash->{READINGS}{$reading}{"history"}});
$arr=\@{$hash->{READINGS}{$reading}{"history"}};
my $starttime = $arr->[0][1];
my ($syear, $smonth, $sday, $shour, $smin, $ssec) = $starttime =~ /(\d+)-(\d+)-(\d+)\s(\d+):(\d+):(\d+)/;
my $stime = $ssec+60*$smin+3600*$shour;
#-- correct for daybreak
$stime-=86400
if( $stime > $ctime);
if( ($num < 25)&&( ($ctime-$stime)<$avtime) ){
#Log 1,"ARRAY has $num elements, adding another one";
push(@{$hash->{READINGS}{$reading}{"history"}},\@new);
}else{
shift(@{$hash->{READINGS}{$reading}{"history"}});
push(@{$hash->{READINGS}{$reading}{"history"}},\@new);
}
}
#-- output and average
my $average = 0;
for(my $i=0;$i<$num;$i++){
$average+=$arr->[$i][0];
Log 4,"[$name moving average] Value = ".$arr->[$i][0]." Time = ".$arr->[$i][1];
}
$average=sprintf( "%5.3f", $average/$num);
#--average
Log 4,"[$name moving average] calculated over $num values is $average";
return $average;
}

###############################################################################
#
# Moving average of last X seconds, weighted by time
#
# movingAverageT(Devicename, Readingname, HistoryLength)
#
###############################################################################
sub movingAverageT($$$) {
my ($name, $reading, $hSeconds) = @_;
my $hash = $defs{$name};

# aktuelles Value + Timestamp holen
my ($val, $time) = (
$hash->{READINGS}{$reading}{VAL},
$hash->{READINGS}{$reading}{TIME}
);

# Gültigkeit prüfen (nur Zahlen erlauben)
return undef unless defined $val && $val =~ /^-?\d+(?:\.\d+)?$/ && defined $time;

my @new = ($val, $time);
my $histKey = "history.T.$hSeconds";

# Wenn kein Zeitraum → direkt aktuellen Wert zurückgeben
return sprintf("%5.3f", $val) if $hSeconds == 0;

# History initialisieren, falls nicht vorhanden oder kein Array
if (!exists $hash->{READINGS}{$reading}{$histKey} || ref $hash->{READINGS}{$reading}{$histKey} ne 'ARRAY') {
$hash->{READINGS}{$reading}{$histKey} = [ \@new ];
}

my $arr = $hash->{READINGS}{$reading}{$histKey};

# nur hinzufügen, wenn leer oder neuer Zeitstempel
if (!@$arr || $time ne $arr->[-1]->[1]) {
push @$arr, \@new;
}

# alte Einträge entfernen
my $now = time();
while (@$arr && $now - time_str2num($arr->[0][1]) > $hSeconds) {
shift @$arr;
}

my $aLength = scalar @$arr;
return sprintf("%5.3f", $val) if $aLength <= 1;

# Zeiten vorab umrechnen
my @times = map { time_str2num($_->[1]) } @$arr;
my $oldest = $times[0];
my $timespan = $now - $oldest;
return sprintf("%5.3f", $val) if $timespan <= 0;

# Werte zeitgewichtet mitteln (inkl. letztem Segment bis jetzt)
my $average = 0;
for (my $i = 0; $i < $aLength; $i++) {
my $segmentEnd = ($i < $aLength - 1) ? $times[$i+1] : $now;
my $diffTime = $segmentEnd - $times[$i];
next if $diffTime <= 0;
my $fraction = $diffTime / $timespan;
$average += $arr->[$i][0] * $fraction;
}

return sprintf("%5.3f", $average);
}

1;</syntaxhighlight>

=== Funktion movingAverage() aufrufen und nutzen ===
Bei jedem Aufruf schiebt die obige Funktion den gegenwärtigen Wert sowie den Zeitpunkt eines Readings (zweiter Parameter) ans Ende eines Arrays (maximal 25 Einträge) und wirft dafür den ersten Eintrag heraus. Die Anzahl der Einträge im Array wird so gewählt, dass die Zeitpunkte der Readings größer oder gleich der gewünschten Zeitspanne für die Mittelung sind. Über diese Werte wird dann gemittelt und der Wert zurückgegeben.

Zur Anwendung empfiehlt sich, dem gewünschten Device ein userReading zu geben:
:<code>attr devicename userReadings readingname.av {movingAverage("devicename","readingname",zeitspanne)}</code>

Dieses wird dann automatisch bei jedem neuen Wert des Readings mit dem neuen gleitenden Mittelwert über die vergangene Zeitspanne gefüllt.

Beispiel: Das Reading "pressure" des Devices "A.OWB" wird alle 5 Minuten aktualisiert. Das Device bekommt nun ein userReading:
:<code>attr A.OWB userReadings pressure.av {movingAverage("A.OWB","pressure",1800)}</code>

Dieses schreibt bei jeder Aktualisierung von "pressure" einen neuen Eintrag in sein Array - allerdings maximal sechs Werte, dann wird immer der älteste Eintrag gelöscht. Damit ist sichergestellt, dass diese mindestens 1800 Sekunden abdecken - also sechs Einträge.

=== Funktion movingAverageT() aufrufen und nutzen ===
Bei jedem Aufruf schiebt die Funktion ''movingAverageT'' den gegenwärtigen Wert sowie den Zeitpunkt eines Readings (zweiter Parameter) ans Ende eines Arrays und verwirft Einträge die älter als das Zeitlimit aus dem dritten Parameter sind. Die Anzahl der Einträge im Array ist nicht limitiert und es wird nur anhand des Zeitstempels entschieden, ob ein Wert im Array verbleibt. Über die Werte im Array wird dann gemittelt und der Wert zurückgegeben.

Zur Anwendung empfiehlt sich, dem gewünschten Device ein userReading zu geben:
:<code>attr devicename userReadings readingname.av {movingAverageT("devicename", "readingname", Zeitspanne_in_Sekunden)}</code>

Dieses wird dann automatisch bei jedem neuen Wert des Readings mit dem neuen gleitenden Mittelwert über die vergangene Zeitspanne gefüllt.

Beispiel: Das Reading "pressure" des Devices "A.OWB" wird alle 5 Minuten aktualisiert. Das Device bekommt nun ein userReading:
:<code>attr A.OWB userReadings pressure.av {movingAverageT("A.OWB", "pressure", 1800)}</code>

Dieses schreibt bei jeder Aktualisierung von "pressure" einen neuen Eintrag an das ende seines Array und löscht zu alte Werte am Anfang des Array wieder heraus.

== Gleitender Mittelwert aus Log-Dateien ==
=== Subroutine myAverage() in 99_MyUtils anlegen ===
Zuerst muss die Subroutine myAverage in die 99_MyUtils übernommen werden. Wenn noch nicht vorhanden, sollte die Datei dann so aussehen:
<syntaxhighlight lang="perl">
package main;
use strict;
use warnings;
sub
MyUtils_Initialize($$)
{
my ($hash) = @_;
}
##########################################################
# myAverage
# berechnet den Mittelwert aus LogFiles über einen beliebigen Zeitraum
# Args: $offset = Offset in Sekunden
# $logfile = LogFile, z.B. DbLog Device
# $cspec = column-spec, z.B. 4:temp:: (4.Spalte, Zeile enthält temp)
sub myAverage($$$) {
my ($offset,$logfile,$cspec) = @_;
my $period_s = strftime "%Y-%m-%d\x5f%H:%M:%S", localtime(time-$offset);
my $period_e = strftime "%Y-%m-%d\x5f%H:%M:%S", localtime;
my $oll = $attr{global}{verbose};
$attr{global}{verbose} = 0;
my @logdata = split("\n", fhem("get $logfile - - $period_s $period_e $cspec"));
$attr{global}{verbose} = $oll;
my ($cnt, $cum, $avg) = (0)x3;
foreach (@logdata){
my @line = split(" ", $_);
if(defined $line[1] && $line[1] ne ""){
$cnt += 1;
$cum += $line[1];
}
}
if("$cnt" > 0){$avg = sprintf("%0.1f", $cum/$cnt)};
Log 4, ("myAverage: File: $logfile, Field: $cspec, Period: $period_s bis $period_e, Count: $cnt, Cum: $cum, Average: $avg");
return $avg;
}
##########################################################
1;
</syntaxhighlight>

=== Funktion myAverage() aufrufen und nutzen ===
Jetzt kann die Funktion <code>myAverage(<offset>, <logfile>, <column-spec>)</code> ganz normal auf der FHEM-Konsole (telnet localhost 7072) genutzt werden. Hier z.B. die Ausgabe des Mittelwertes des Windsensors, eines KS300, über die letzten drei Stunden (Angabe in 3*3600s) oder der Temperaturmittelwert der letzten 24 Stunden.

Mit FileLog:

<nowiki>fhem> {myAverage("10800", "FileLog_KS300", "8:::")}
6.3
fhem> {myAverage("86400", "FileLog_KS300", "4:::")}
-2.7
fhem></nowiki>

Mit DbLog:

<nowiki>fhem> {myAverage("10800", "myDbLog", "KS300:wind::")}
5.9
fhem> {myAverage("86400", "myDbLog", "KS300:temperature::")}
-2.7
fhem></nowiki>

Ähnlich ist die Verwendung in perl-Code in der [[Konfiguration|fhem.cfg]]:

<nowiki>my $avg = myAverage("10800", "FileLog_KS300", "8:::");;\</nowiki>
Ein [[notify]], welches bei jedem neuen Sensorwert die Mitteltemperatur der letzten 24 Stunden als Event "average-temp xy" ins Logfile schreibt, sieht dann wie folgt aus:

<nowiki>define KS300_T_notify notify KS300:temperature.* {\
fhem('trigger KS300 average-temp: '.myAverage("86400", "FileLog_KS300", "4:::"));;\
}</nowiki>


Analog dazu wäre mit den Winddaten zu verfahren.

== Gleitender Mittelwert und Minimum und Maximum aus Log-Dateien ==

Manchmal interessieren einem auch Minimum und Maximum Werte über einen bestimmten Zeitraum, die Funktion ''myAverage'' kann einfach entsprechend abgeändert werden:

=== Subroutine avgMinMaxAusLog() in 99_MyUtils anlegen ===
<syntaxhighlight lang="Perl">
# Berechnet den Mittelwert, Minimum und Maximum aus LogFiles über einen beliebigen Zeitraum
# Args: $offset = Offset in Sekunden
# $logfile = LogFile, z.B. DbLog Device
# $cspec = column-spec, siehe https://fhem.de/commandref_DE.html#DbLog -> get
sub avgMinMaxAusLog($$$) {
my($offset, $logfile, $cspec) = @_;
my $period_s = strftime "%Y-%m-%d\x5f%H:%M:%S", localtime(time - $offset);
my $period_e = strftime "%Y-%m-%d\x5f%H:%M:%S", localtime;
my $oll = $attr { global } { verbose };
$attr { global } { verbose } = 0;
my @logdata = split("\n", fhem("get $logfile - - $period_s $period_e $cspec"));
$attr { global } { verbose } = $oll;
my ($cnt, $cum, $avg, $min, $max) = (0)x5;
foreach(@logdata) {
my @line = split(" ", $_);
if (defined $line[1] && $line[1] ne "") {
$cnt += 1;
$cum += $line[1];
# Beim ersten Eintrag min/max setzen
if ($cnt == 1) {
$min = $line[1];
$max = $line[1];
# Bei den darauffolgenden Einträgen $min/max ermitteln
} else {
if ($line[1] < $min) { $min = $line[1]; }
if ($line[1] > $max) { $max = $line[1]; }
}
}
}
if ("$cnt" > 0) {
$avg = sprintf("%0.1f", $cum / $cnt)
};
Log 4, ("avgMinMaxAusLog: File: $logfile, Field: $cspec, Period: $period_s bis $period_e, Count: $cnt, Cum: $cum, Average: $avg, Minimum: $min, Maximum: $max");
return ($avg, $min, $max);
}
</syntaxhighlight>
Anwendung wie oben. Statt nur dem Mittelwert wird eine Liste zurückgeliefert mit Mittelwert, Minimum und Maximum. Verwendung z.B. wie folgt:

<nowiki>my ($avg, $min, $max) = myAverage("10800", "FileLog_KS300", "8:::");;\</nowiki>

== Eigenes Filelog und Plot ==
==== Definitionen ====
Ich schreibe ein komplett eigenes Logfile und lasse über eine spezielle gplot-Definition die Temperatur- und Winddaten loggen und plotten.

<syntaxhighlight lang="Perl">
define KS300_W dummy
define KS300_W_notify notify KS300:wind.* {\
my $avg = myAverage("10800", "FileLog_KS300", "8:::");;\
my $event = sprintf("Wc: %0.1f Wd: %0.1f Wm: %0.1f Wlh: %0.1f", ReadingsVal("KS300","wind","0"), ReadingsVal("KS300","W_avg_day","0"), ReadingsVal("KS300","W_avg_month","0"), $avg);;\
Log 2, ("K300_W: Event: $event");;\
fhem("trigger KS300_W data: $event");;\
fhem("trigger KS300 average-wind: $avg");;\
}
define FileLog_KS300_W FileLog ./log/KS300_W-%Y.log KS300_W.*
attr FileLog_KS300_W logtype text
attr FileLog_KS300_W room Logs
define KS300_TH dummy
define KS300_TH_notify notify KS300:temperature.* {\
my $avg = myAverage("86400", "FileLog_KS300", "4:::");;\
my $event = sprintf("Tc: %0.1f Hc: %0.1f Tavg: %0.1f", ReadingsVal("KS300","temperature","0"), ReadingsVal("KS300","humidity","0"), $avg);;\
Log 2, ("K300_TH: Event: $event");;\
fhem("trigger KS300_TH data: $event");;\
fhem('trigger KS300 average-temp: '.$avg);;\
}
define FileLog_KS300_TH FileLog ./log/KS300_TH-%Y.log KS300_TH.*
attr FileLog_KS300_TH logtype text
attr FileLog_KS300_TH room Logs</nowiki>
Die Definitionen für die Plots schauen so aus:

<nowiki>define weblink_KS300_W weblink fileplot FileLog_KS300_W:ks300_wind:CURRENT
attr weblink_KS300_W label "Wind - Min: $data{min1}, Max: $data{max1}, Last: $data{currval1}"
attr weblink_KS300_W room Dachterasse
define weblink_KS300_TH weblink fileplot FileLog_KS300_TH:ks300_temphum:CURRENT
attr weblink_KS300_TH label "Temperatur/Feuchte - Min: $data{min1}, Max: $data{max1}, Last: $data{currval1}"
attr weblink_KS300_TH room Dachterasse
define weblink_KS300_R weblink fileplot FileLog_KS300:ks300_rain10:CURRENT
attr weblink_KS300_R label "Regen - Min: $data{min1}, Max: $data{max1}, Last: $data{currval1}"
attr weblink_KS300_R room Dachterasse
</syntaxhighlight>

==== Angepasste gplot-Dateien ====
Nun noch die speziellen gplot-Dateien.
ks300_wind.gplot

<syntaxhighlight lang="Perl">
############################
# Display the wind values of a KS300.
# Corresponding FileLog definition:
# define <filelogname> FileLog ./log/KS300_W-%Y.log KS300_W.*
set terminal png transparent size <SIZE> crop
set output '<OUT>.png'
set xdata time
set timefmt "%Y-%m-%d_%H:%M:%S"
set xlabel " "
set ytics nomirror
#set y2tics
set ytics
set title '<L1>'
set grid xtics ytics
set yrange [0:]
set y2range [0:]
set ylabel "Wind (aktuell) [km/h]"
set y2label "Wind (gemittelt) [km/h]"
set format y2 "%0.1f"
#FileLog 5:Wc\x3a:0:
#FileLog 11:Wlh\x3a:0:
plot "<IN>" using 1:5 ls l7fill axes x1y1 title 'Wind (aktuell)' with lines,\
"<IN>" using 1:11 ls l5 axes x1y2 title 'Wind (3h-Mittel)' with steps,\</syntaxhighlight>

ks300_temphum.gplot
<syntaxhighlight lang="Perl">
############################
# Display the Temperature und Humidity values of a KS300.
# Corresponding FileLog definition:
# define <filelogname> FileLog ./log/KS300_TH-%Y.log KS300_TH.*
set terminal png transparent size <SIZE> crop
set output '<OUT>.png'
set xdata time
set timefmt "%Y-%m-%d_%H:%M:%S"
set xlabel " "
set ytics nomirror
set y2tics
#set ytics
set title '<L1>'
set grid xtics y2tics
set y2label "Temperatur [°C]"
set ylabel "Luftfeuchte [%]"
#FileLog 5:Tc\x3a:0:
#FileLog 9:Tavg\x3a:0:
#FileLog 7:Hc\x3a:0:
plot "<IN>" using 1:5 axes x1y2 ls l0 title 'Temperatur' with lines,\
"<IN>" using 1:9 axes x1y2 ls l10 title 'Temperatur (24h-Mittel)' with lines,\
"<IN>" using 1:7 axes x1y1 ls l2fill title 'Luftfeuchte' with lines
</syntaxhighlight>
Den Plot für den Regen habe ich noch um Punkt-Plots für den israining-Status erweitert, so dass Punkte bei "yes" geplottet werden.

ks300_rain10.gplot
<syntaxhighlight lang="Perl">
############################
# Display the Rain values of a KS300.
# Corresponding FileLog definition:
# define <filelogname> FileLog ./log/KS300-%Y.log KS300:T:.*
set terminal png transparent size <SIZE> crop
set output '<OUT>.png'
set xdata time
set timefmt "%Y-%m-%d_%H:%M:%S"
set xlabel " "
set ytics nomirror
#set y2tics
set ytics
set title '<L1>'
set grid xtics ytics
set y2range [0.5:1.5]
set y2tics ("" 0, "Regen" 1)
set pointsize 7
set ylabel "Regen (l/m²)"
set yrange [0:]
# Computing Rain/h and Rain/d values by accumulating the changes.
#FileLog 10:IR\x3a:0:delta-h
#FileLog 10:IR\x3a:0:delta-d
#FileLog 12:IR:0:$fld[11]=~"yes"?1:0
plot "<grep -v avg_ <IN> | perl -ane '\
@a = split(\"[_:]\", $F[0]);\
if(defined($lh) && $lh ne $a[1])\
{ printf(\"${ld}_$lh:30:00 %f\n\", $hv); $hv = 0; }\
if($lv) { $hv += ($F[9]-$lv); }\
$lh = $a[1]; $ld = $a[0]; $lv = $F[9];\
END { printf(\"${ld}_$lh:30:00 %f\n\", $hv) }'"\
using 1:2 axes x1y1 ls l1fill title 'Regen pro Stunde' with histeps,\
"<grep -v avg_ <IN> | perl -ane '\
@a = split(\"[_]\", $F[0]);\
if(defined($ld) && $ld ne $a[0]) {\
printf(\"${ld}_12:00:00 %f\n\", $dv); $dv = 0; }\
if($lv) { $dv += ($F[9]-$lv); }\
$ld = $a[0]; $lv = $F[9];\
END {printf(\"${ld}_12:00:00 %f\n\", $dv)}'"\
using 1:2 axes x1y1 ls l7 title 'Regen pro Tag' with histeps
"<grep -v avg_ <IN> | awk '{print $1, $12==\"yes\"? 1 : 0; }'"\
using 1:2 axes x1y2 ls l11fill title 'Regen aktuell' with points
</syntaxhighlight>
Eventuell müssen in den gplots noch die Linienstile/Farben den eigenen Bedürfnissen angepasst werden. Ich verwende hier eigene Farben und Füllungen.

[[Kategorie:HOWTOS]]
[[Kategorie:Code Snippets]]
[[Kategorie:Logging]]

Datei:SVG Plot von Temperaturen und dem Mittelwert.png

2025-09-21T10:15:48Z

Torxgewinde:

SVG Plot von Temperaturen und dem Mittelwert

Gleitende Mittelwerte berechnen und loggen

2025-09-21T10:13:50Z

Torxgewinde: Aktualisierte Version der Funktion AverageMovingT

Für verschiedene Wettersensoren ist es oftmals wünschenswert, gleitende Mittelwerte (fälschlich auch als "relative" Mittelwerte bezeichnet) über ein bestimmtes Zeitfenster auszugeben oder in den Logs zu speichern und zu plotten. Beispiele:
* Die momentanen Winddaten eines KS300 sind oft stark schwankend. Hier wäre ein Mittelwert z.B. der letzten 2-3 Stunden interessant.
* Für die Außentemperatur ist anhand eines Mittelwertes der letzten 24 Stunden evtl. ein gewisser Trend der generellen Entwicklung der Temperatur ableitbar.

Mit Modulen wie ''rain'' oder ''average'' ist konzeptbedingt nur ein Mittelwert von fixen Zeiträumen (aktueller Tag, Monat, etc.) möglich.

Im Nachfolgenden werden deshalb zwei Programme vorgestellt, die solche gleitenden Mittelwerte bereitstellen. Beide Programme werden in die Datei [[99 myUtils anlegen|99_MyUtils.pm]] eingetragen und dann von FHEM aufgerufen. Das erste Programm macht dies für beliebige Readings beliebiger Devices, das zweite Programm greift auf beliebige [[FileLog|File-]] oder [[DbLog|DbLogs]] zurück.

== Gleitender Mittelwert für beliebige Readings ==
=== Subroutine movingAverage in 99_MyUtils anlegen ===
Es werden die Funktionen ''movingAverage'' und ''movingAverageT'' in die 99_MyUtils Datei übernommen werden. Wenn noch nicht vorhanden, sollte die Datei dann so aussehen, der übliche Speicherort ist ''/opt/fhem/FHEM/99_MyUtils.pm''

<syntaxhighlight lang="perl" line="1">package main;
use strict;
use warnings;
sub
MyUtils_Initialize($$)
{
my ($hash) = @_;
}
###############################################################################
#
# Moving average
#
# Aufruf: movingAverage(devicename,readingname,zeitspanne in s)
#
###############################################################################

sub movingAverage($$$){
my ($name,$reading,$avtime) = @_;
my $hash = $defs{$name};
my @new = my ($val,$time) = ($hash->{READINGS}{$reading}{VAL},$hash->{READINGS}{$reading}{TIME});
my ($cyear, $cmonth, $cday, $chour, $cmin, $csec) = $time =~ /(\d+)-(\d+)-(\d+)\s(\d+):(\d+):(\d+)/;
my $ctime = $csec+60*$cmin+3600*$chour;
my $num;
my $arr;
#-- initialize if requested
if( ($avtime eq "-1") ){
$hash->{READINGS}{$reading}{"history"}=undef;
}
#-- test for existence
if( !$hash->{READINGS}{$reading}{"history"}){
#Log 1,"ARRAY CREATED";
push(@{$hash->{READINGS}{$reading}{"history"}},\@new);
$num = 1;
$arr=\@{$hash->{READINGS}{$reading}{"history"}};
} else {
$num = int(@{$hash->{READINGS}{$reading}{"history"}});
$arr=\@{$hash->{READINGS}{$reading}{"history"}};
my $starttime = $arr->[0][1];
my ($syear, $smonth, $sday, $shour, $smin, $ssec) = $starttime =~ /(\d+)-(\d+)-(\d+)\s(\d+):(\d+):(\d+)/;
my $stime = $ssec+60*$smin+3600*$shour;
#-- correct for daybreak
$stime-=86400
if( $stime > $ctime);
if( ($num < 25)&&( ($ctime-$stime)<$avtime) ){
#Log 1,"ARRAY has $num elements, adding another one";
push(@{$hash->{READINGS}{$reading}{"history"}},\@new);
}else{
shift(@{$hash->{READINGS}{$reading}{"history"}});
push(@{$hash->{READINGS}{$reading}{"history"}},\@new);
}
}
#-- output and average
my $average = 0;
for(my $i=0;$i<$num;$i++){
$average+=$arr->[$i][0];
Log 4,"[$name moving average] Value = ".$arr->[$i][0]." Time = ".$arr->[$i][1];
}
$average=sprintf( "%5.3f", $average/$num);
#--average
Log 4,"[$name moving average] calculated over $num values is $average";
return $average;
}

###############################################################################
#
# Moving average of last X seconds, weighted by time
#
# movingAverageT(Devicename, Readingname, HistoryLength)
#
###############################################################################
sub movingAverageT($$$) {
my ($name, $reading, $hSeconds) = @_;
my $hash = $defs{$name};

# aktuelles Value + Timestamp holen
my ($val, $time) = (
$hash->{READINGS}{$reading}{VAL},
$hash->{READINGS}{$reading}{TIME}
);

# Gültigkeit prüfen (nur Zahlen erlauben)
return undef unless defined $val && $val =~ /^-?\d+(?:\.\d+)?$/ && defined $time;

my @new = ($val, $time);
my $histKey = "history.T.$hSeconds";

# Wenn kein Zeitraum → direkt aktuellen Wert zurückgeben
return sprintf("%5.3f", $val) if $hSeconds == 0;

# History initialisieren, falls nicht vorhanden oder kein Array
if (!exists $hash->{READINGS}{$reading}{$histKey} || ref $hash->{READINGS}{$reading}{$histKey} ne 'ARRAY') {
$hash->{READINGS}{$reading}{$histKey} = [ \@new ];
}

my $arr = $hash->{READINGS}{$reading}{$histKey};

# nur hinzufügen, wenn leer oder neuer Zeitstempel
if (!@$arr || $time ne $arr->[-1]->[1]) {
push @$arr, \@new;
}

# alte Einträge entfernen
my $now = time();
while (@$arr && $now - time_str2num($arr->[0][1]) > $hSeconds) {
shift @$arr;
}

my $aLength = scalar @$arr;
return sprintf("%5.3f", $val) if $aLength <= 1;

# Zeiten vorab umrechnen
my @times = map { time_str2num($_->[1]) } @$arr;
my $oldest = $times[0];
my $timespan = $now - $oldest;
return sprintf("%5.3f", $val) if $timespan <= 0;

# Werte zeitgewichtet mitteln (inkl. letztem Segment bis jetzt)
my $average = 0;
for (my $i = 0; $i < $aLength; $i++) {
my $segmentEnd = ($i < $aLength - 1) ? $times[$i+1] : $now;
my $diffTime = $segmentEnd - $times[$i];
next if $diffTime <= 0;
my $fraction = $diffTime / $timespan;
$average += $arr->[$i][0] * $fraction;
}

return sprintf("%5.3f", $average);
}

1;</syntaxhighlight>

=== Funktion movingAverage() aufrufen und nutzen ===
Bei jedem Aufruf schiebt die obige Funktion den gegenwärtigen Wert sowie den Zeitpunkt eines Readings (zweiter Parameter) ans Ende eines Arrays (maximal 25 Einträge) und wirft dafür den ersten Eintrag heraus. Die Anzahl der Einträge im Array wird so gewählt, dass die Zeitpunkte der Readings größer oder gleich der gewünschten Zeitspanne für die Mittelung sind. Über diese Werte wird dann gemittelt und der Wert zurückgegeben.

Zur Anwendung empfiehlt sich, dem gewünschten Device ein userReading zu geben:
:<code>attr devicename userReadings readingname.av {movingAverage("devicename","readingname",zeitspanne)}</code>

Dieses wird dann automatisch bei jedem neuen Wert des Readings mit dem neuen gleitenden Mittelwert über die vergangene Zeitspanne gefüllt.

Beispiel: Das Reading "pressure" des Devices "A.OWB" wird alle 5 Minuten aktualisiert. Das Device bekommt nun ein userReading:
:<code>attr A.OWB userReadings pressure.av {movingAverage("A.OWB","pressure",1800)}</code>

Dieses schreibt bei jeder Aktualisierung von "pressure" einen neuen Eintrag in sein Array - allerdings maximal sechs Werte, dann wird immer der älteste Eintrag gelöscht. Damit ist sichergestellt, dass diese mindestens 1800 Sekunden abdecken - also sechs Einträge.

=== Funktion movingAverageT() aufrufen und nutzen ===
Bei jedem Aufruf schiebt die Funktion ''movingAverageT'' den gegenwärtigen Wert sowie den Zeitpunkt eines Readings (zweiter Parameter) ans Ende eines Arrays und verwirft Einträge die älter als das Zeitlimit aus dem dritten Parameter sind. Die Anzahl der Einträge im Array ist nicht limitiert und es wird nur anhand des Zeitstempels entschieden, ob ein Wert im Array verbleibt. Über die Werte im Array wird dann gemittelt und der Wert zurückgegeben.

Zur Anwendung empfiehlt sich, dem gewünschten Device ein userReading zu geben:
:<code>attr devicename userReadings readingname.av {movingAverageT("devicename", "readingname", Zeitspanne_in_Sekunden)}</code>

Dieses wird dann automatisch bei jedem neuen Wert des Readings mit dem neuen gleitenden Mittelwert über die vergangene Zeitspanne gefüllt.

Beispiel: Das Reading "pressure" des Devices "A.OWB" wird alle 5 Minuten aktualisiert. Das Device bekommt nun ein userReading:
:<code>attr A.OWB userReadings pressure.av {movingAverageT("A.OWB", "pressure", 1800)}</code>

Dieses schreibt bei jeder Aktualisierung von "pressure" einen neuen Eintrag an das ende seines Array und löscht zu alte Werte am Anfang des Array wieder heraus.

== Gleitender Mittelwert aus Log-Dateien ==
=== Subroutine myAverage() in 99_MyUtils anlegen ===
Zuerst muss die Subroutine myAverage in die 99_MyUtils übernommen werden. Wenn noch nicht vorhanden, sollte die Datei dann so aussehen:
<syntaxhighlight lang="perl">
package main;
use strict;
use warnings;
sub
MyUtils_Initialize($$)
{
my ($hash) = @_;
}
##########################################################
# myAverage
# berechnet den Mittelwert aus LogFiles über einen beliebigen Zeitraum
# Args: $offset = Offset in Sekunden
# $logfile = LogFile, z.B. DbLog Device
# $cspec = column-spec, z.B. 4:temp:: (4.Spalte, Zeile enthält temp)
sub myAverage($$$) {
my ($offset,$logfile,$cspec) = @_;
my $period_s = strftime "%Y-%m-%d\x5f%H:%M:%S", localtime(time-$offset);
my $period_e = strftime "%Y-%m-%d\x5f%H:%M:%S", localtime;
my $oll = $attr{global}{verbose};
$attr{global}{verbose} = 0;
my @logdata = split("\n", fhem("get $logfile - - $period_s $period_e $cspec"));
$attr{global}{verbose} = $oll;
my ($cnt, $cum, $avg) = (0)x3;
foreach (@logdata){
my @line = split(" ", $_);
if(defined $line[1] && $line[1] ne ""){
$cnt += 1;
$cum += $line[1];
}
}
if("$cnt" > 0){$avg = sprintf("%0.1f", $cum/$cnt)};
Log 4, ("myAverage: File: $logfile, Field: $cspec, Period: $period_s bis $period_e, Count: $cnt, Cum: $cum, Average: $avg");
return $avg;
}
##########################################################
1;
</syntaxhighlight>

=== Funktion myAverage() aufrufen und nutzen ===
Jetzt kann die Funktion <code>myAverage(<offset>, <logfile>, <column-spec>)</code> ganz normal auf der FHEM-Konsole (telnet localhost 7072) genutzt werden. Hier z.B. die Ausgabe des Mittelwertes des Windsensors, eines KS300, über die letzten drei Stunden (Angabe in 3*3600s) oder der Temperaturmittelwert der letzten 24 Stunden.

Mit FileLog:

<nowiki>fhem> {myAverage("10800", "FileLog_KS300", "8:::")}
6.3
fhem> {myAverage("86400", "FileLog_KS300", "4:::")}
-2.7
fhem></nowiki>

Mit DbLog:

<nowiki>fhem> {myAverage("10800", "myDbLog", "KS300:wind::")}
5.9
fhem> {myAverage("86400", "myDbLog", "KS300:temperature::")}
-2.7
fhem></nowiki>

Ähnlich ist die Verwendung in perl-Code in der [[Konfiguration|fhem.cfg]]:

<nowiki>my $avg = myAverage("10800", "FileLog_KS300", "8:::");;\</nowiki>
Ein [[notify]], welches bei jedem neuen Sensorwert die Mitteltemperatur der letzten 24 Stunden als Event "average-temp xy" ins Logfile schreibt, sieht dann wie folgt aus:

<nowiki>define KS300_T_notify notify KS300:temperature.* {\
fhem('trigger KS300 average-temp: '.myAverage("86400", "FileLog_KS300", "4:::"));;\
}</nowiki>


Analog dazu wäre mit den Winddaten zu verfahren.

== Gleitender Mittelwert und Minimum und Maximum aus Log-Dateien ==

Manchmal interessieren einem auch Minimum und Maximum Werte über einen bestimmten Zeitraum, die Funktion ''myAverage'' kann einfach entsprechend abgeändert werden:

=== Subroutine avgMinMaxAusLog() in 99_MyUtils anlegen ===
<syntaxhighlight lang="Perl">
# Berechnet den Mittelwert, Minimum und Maximum aus LogFiles über einen beliebigen Zeitraum
# Args: $offset = Offset in Sekunden
# $logfile = LogFile, z.B. DbLog Device
# $cspec = column-spec, siehe https://fhem.de/commandref_DE.html#DbLog -> get
sub avgMinMaxAusLog($$$) {
my($offset, $logfile, $cspec) = @_;
my $period_s = strftime "%Y-%m-%d\x5f%H:%M:%S", localtime(time - $offset);
my $period_e = strftime "%Y-%m-%d\x5f%H:%M:%S", localtime;
my $oll = $attr { global } { verbose };
$attr { global } { verbose } = 0;
my @logdata = split("\n", fhem("get $logfile - - $period_s $period_e $cspec"));
$attr { global } { verbose } = $oll;
my ($cnt, $cum, $avg, $min, $max) = (0)x5;
foreach(@logdata) {
my @line = split(" ", $_);
if (defined $line[1] && $line[1] ne "") {
$cnt += 1;
$cum += $line[1];
# Beim ersten Eintrag min/max setzen
if ($cnt == 1) {
$min = $line[1];
$max = $line[1];
# Bei den darauffolgenden Einträgen $min/max ermitteln
} else {
if ($line[1] < $min) { $min = $line[1]; }
if ($line[1] > $max) { $max = $line[1]; }
}
}
}
if ("$cnt" > 0) {
$avg = sprintf("%0.1f", $cum / $cnt)
};
Log 4, ("avgMinMaxAusLog: File: $logfile, Field: $cspec, Period: $period_s bis $period_e, Count: $cnt, Cum: $cum, Average: $avg, Minimum: $min, Maximum: $max");
return ($avg, $min, $max);
}
</syntaxhighlight>
Anwendung wie oben. Statt nur dem Mittelwert wird eine Liste zurückgeliefert mit Mittelwert, Minimum und Maximum. Verwendung z.B. wie folgt:

<nowiki>my ($avg, $min, $max) = myAverage("10800", "FileLog_KS300", "8:::");;\</nowiki>

== Eigenes Filelog und Plot ==
==== Definitionen ====
Ich schreibe ein komplett eigenes Logfile und lasse über eine spezielle gplot-Definition die Temperatur- und Winddaten loggen und plotten.

<syntaxhighlight lang="Perl">
define KS300_W dummy
define KS300_W_notify notify KS300:wind.* {\
my $avg = myAverage("10800", "FileLog_KS300", "8:::");;\
my $event = sprintf("Wc: %0.1f Wd: %0.1f Wm: %0.1f Wlh: %0.1f", ReadingsVal("KS300","wind","0"), ReadingsVal("KS300","W_avg_day","0"), ReadingsVal("KS300","W_avg_month","0"), $avg);;\
Log 2, ("K300_W: Event: $event");;\
fhem("trigger KS300_W data: $event");;\
fhem("trigger KS300 average-wind: $avg");;\
}
define FileLog_KS300_W FileLog ./log/KS300_W-%Y.log KS300_W.*
attr FileLog_KS300_W logtype text
attr FileLog_KS300_W room Logs
define KS300_TH dummy
define KS300_TH_notify notify KS300:temperature.* {\
my $avg = myAverage("86400", "FileLog_KS300", "4:::");;\
my $event = sprintf("Tc: %0.1f Hc: %0.1f Tavg: %0.1f", ReadingsVal("KS300","temperature","0"), ReadingsVal("KS300","humidity","0"), $avg);;\
Log 2, ("K300_TH: Event: $event");;\
fhem("trigger KS300_TH data: $event");;\
fhem('trigger KS300 average-temp: '.$avg);;\
}
define FileLog_KS300_TH FileLog ./log/KS300_TH-%Y.log KS300_TH.*
attr FileLog_KS300_TH logtype text
attr FileLog_KS300_TH room Logs</nowiki>
Die Definitionen für die Plots schauen so aus:

<nowiki>define weblink_KS300_W weblink fileplot FileLog_KS300_W:ks300_wind:CURRENT
attr weblink_KS300_W label "Wind - Min: $data{min1}, Max: $data{max1}, Last: $data{currval1}"
attr weblink_KS300_W room Dachterasse
define weblink_KS300_TH weblink fileplot FileLog_KS300_TH:ks300_temphum:CURRENT
attr weblink_KS300_TH label "Temperatur/Feuchte - Min: $data{min1}, Max: $data{max1}, Last: $data{currval1}"
attr weblink_KS300_TH room Dachterasse
define weblink_KS300_R weblink fileplot FileLog_KS300:ks300_rain10:CURRENT
attr weblink_KS300_R label "Regen - Min: $data{min1}, Max: $data{max1}, Last: $data{currval1}"
attr weblink_KS300_R room Dachterasse
</syntaxhighlight>

==== Angepasste gplot-Dateien ====
Nun noch die speziellen gplot-Dateien.
ks300_wind.gplot

<syntaxhighlight lang="Perl">
############################
# Display the wind values of a KS300.
# Corresponding FileLog definition:
# define <filelogname> FileLog ./log/KS300_W-%Y.log KS300_W.*
set terminal png transparent size <SIZE> crop
set output '<OUT>.png'
set xdata time
set timefmt "%Y-%m-%d_%H:%M:%S"
set xlabel " "
set ytics nomirror
#set y2tics
set ytics
set title '<L1>'
set grid xtics ytics
set yrange [0:]
set y2range [0:]
set ylabel "Wind (aktuell) [km/h]"
set y2label "Wind (gemittelt) [km/h]"
set format y2 "%0.1f"
#FileLog 5:Wc\x3a:0:
#FileLog 11:Wlh\x3a:0:
plot "<IN>" using 1:5 ls l7fill axes x1y1 title 'Wind (aktuell)' with lines,\
"<IN>" using 1:11 ls l5 axes x1y2 title 'Wind (3h-Mittel)' with steps,\</syntaxhighlight>

ks300_temphum.gplot
<syntaxhighlight lang="Perl">
############################
# Display the Temperature und Humidity values of a KS300.
# Corresponding FileLog definition:
# define <filelogname> FileLog ./log/KS300_TH-%Y.log KS300_TH.*
set terminal png transparent size <SIZE> crop
set output '<OUT>.png'
set xdata time
set timefmt "%Y-%m-%d_%H:%M:%S"
set xlabel " "
set ytics nomirror
set y2tics
#set ytics
set title '<L1>'
set grid xtics y2tics
set y2label "Temperatur [°C]"
set ylabel "Luftfeuchte [%]"
#FileLog 5:Tc\x3a:0:
#FileLog 9:Tavg\x3a:0:
#FileLog 7:Hc\x3a:0:
plot "<IN>" using 1:5 axes x1y2 ls l0 title 'Temperatur' with lines,\
"<IN>" using 1:9 axes x1y2 ls l10 title 'Temperatur (24h-Mittel)' with lines,\
"<IN>" using 1:7 axes x1y1 ls l2fill title 'Luftfeuchte' with lines
</syntaxhighlight>
Den Plot für den Regen habe ich noch um Punkt-Plots für den israining-Status erweitert, so dass Punkte bei "yes" geplottet werden.

ks300_rain10.gplot
<syntaxhighlight lang="Perl">
############################
# Display the Rain values of a KS300.
# Corresponding FileLog definition:
# define <filelogname> FileLog ./log/KS300-%Y.log KS300:T:.*
set terminal png transparent size <SIZE> crop
set output '<OUT>.png'
set xdata time
set timefmt "%Y-%m-%d_%H:%M:%S"
set xlabel " "
set ytics nomirror
#set y2tics
set ytics
set title '<L1>'
set grid xtics ytics
set y2range [0.5:1.5]
set y2tics ("" 0, "Regen" 1)
set pointsize 7
set ylabel "Regen (l/m²)"
set yrange [0:]
# Computing Rain/h and Rain/d values by accumulating the changes.
#FileLog 10:IR\x3a:0:delta-h
#FileLog 10:IR\x3a:0:delta-d
#FileLog 12:IR:0:$fld[11]=~"yes"?1:0
plot "<grep -v avg_ <IN> | perl -ane '\
@a = split(\"[_:]\", $F[0]);\
if(defined($lh) && $lh ne $a[1])\
{ printf(\"${ld}_$lh:30:00 %f\n\", $hv); $hv = 0; }\
if($lv) { $hv += ($F[9]-$lv); }\
$lh = $a[1]; $ld = $a[0]; $lv = $F[9];\
END { printf(\"${ld}_$lh:30:00 %f\n\", $hv) }'"\
using 1:2 axes x1y1 ls l1fill title 'Regen pro Stunde' with histeps,\
"<grep -v avg_ <IN> | perl -ane '\
@a = split(\"[_]\", $F[0]);\
if(defined($ld) && $ld ne $a[0]) {\
printf(\"${ld}_12:00:00 %f\n\", $dv); $dv = 0; }\
if($lv) { $dv += ($F[9]-$lv); }\
$ld = $a[0]; $lv = $F[9];\
END {printf(\"${ld}_12:00:00 %f\n\", $dv)}'"\
using 1:2 axes x1y1 ls l7 title 'Regen pro Tag' with histeps
"<grep -v avg_ <IN> | awk '{print $1, $12==\"yes\"? 1 : 0; }'"\
using 1:2 axes x1y2 ls l11fill title 'Regen aktuell' with points
</syntaxhighlight>
Eventuell müssen in den gplots noch die Linienstile/Farben den eigenen Bedürfnissen angepasst werden. Ich verwende hier eigene Farben und Füllungen.

[[Kategorie:HOWTOS]]
[[Kategorie:Code Snippets]]
[[Kategorie:Logging]]

Öffentliche IP-Adresse

2025-06-29T09:16:48Z

Torxgewinde: Hinweise von @passibe aus dem Forum ergänzt

== Einleitung ==
In FHEM kann die aktuell verwendete öffentliche IP-Adresse (IPv4/IPv6) auf verschiedene Arten ermittelt werden. Eine Methode ist der Abruf über externe Webdienste. Es kann auch auf lokale Router-Informationen (z. B. Fritzbox) oder systemnahe Module (z.B. STUN) zurückgegriffen werden.

== HTTPMOD-Definition zum ermitteln der öffentlichen IPv4 und IPv6 via HTTPS-Webdienst ==
Die öffentliche IP kann man mit Webdiensten ermitteln, die einem die IPv4 und/oder IPv6 anzeigen mit der die Seite abgerufen wird:<syntaxhighlight lang="perl">
defmod PublicIP HTTPMOD https://ipwho.de/json/ 600
attr PublicIP extractAllJSON 1
</syntaxhighlight>Ein Abfrageintervall von 300 bis 600 Sekunden (5 bis 10 Minuten) wird empfohlen – häufigere Abfragen belasten die externen Dienste unnötig.

=== Weitere Dienste ===
{| class="wikitable"
|+Getestete Dienste zum ermitteln der öffentlichen IP via HTTPS
!Anbieter
!Adresse
!Zuletzt erfolgreich getestet im Jahr
|-
|<code>ipify.org</code>
|https://api64.ipify.org/?format=json
|2025
|-
|<code>ipwho.de</code>
|https://ipwho.de/json/
|2025
|-
|<code>ipinfo.io</code>
|https://ipinfo.io/json/
|2025
|-
|<code>myip.com</code>
|https://api.myip.com/
|2025
|-
|<code>ident.me</code>
|https://a.ident.me/json
|2025
|-
|
|
|
|}

== Fritzbox nutzen ==

=== Reguläres Device nutzen ===

Wird eine Fritzbox als Router in das Internet verwendet, kann man die öffentliche IP sehr einfach vom Router abfragen. Der Vorteil dieser Lösung besteht darin, dass kein externer Dienst abgefragt werden muss:<syntaxhighlight lang="perl">
defmod Fritzbox FRITZBOX 192.168.123.123
attr Fritzbox INTERVAL 300
attr Fritzbox boxUser <dein Fritzbox User>
attr Fritzbox nonblockingTimeOut 100
</syntaxhighlight>Hierbei sind die Attribute wie die IP Adresse und Nutzername auf der Fritzbox anzupassen.

Die IPv4 und IPv6 der Fritzbox, als auch das IPv6 Prefix des lokalen Netzes sind als Readings direkt abfragbar:
<code>box_ipv4_Extern</code>
<code>box_ipv6_Extern</code>
<code>box_ipv6_Prefix</code>
Wenn diese Readings nicht verfügbar sind, sollte überprüft werden, ob in den Einstellungen der Fritzbox unter Heimnetz -> Netzwerk -> Netzwerkeinstellungen die Option "Statusinformationen über UPnP übertragen" aktiviert ist. Zum Abrufen der IP-Adressen muss diese Option aktiviert sein (siehe auch: https://forum.fhem.de/index.php?topic=141872.msg1343693#msg1343693).

=== Spezielle Abfrage der Fritzbox für Sonderfälle ===
In einigen Fällen stellt das Fritzbox Device nicht die passenden Readings bereit (zum Beispiel bei einer FB 6660 cable). Da in solchen Fällen CGNAT/DS-Lite eine IPv4 Abfrage vom Internet aus auf FHEM verhindert ist nur die öffentlich erreichbare IPv6 Adresse von Interesse (=GUA).
Es steht zur Zeit alternativ ein BASH Skript bereit ({{Link2Forum|Topic=141872|Message=1343341|LinkText=Quelle}}):<syntaxhighlight lang="bash">
#!/bin/bash

FRITZ_USER="<USER>"
FRITZ_PASS="<PASS>"
FRITZ_HOSTNAME="<HOST>"

FRITZ_IPV6_GUA=$(curl -s --max-time 10 \
--anyauth --user "${FRITZ_USER}:${FRITZ_PASS}" \
http://${FRITZ_HOSTNAME}:49000/upnp/control/wanipconnection1 \
-H "Content-Type: text/xml; charset="utf-8"" \
-H "SoapAction:urn:dslforum-org:service:WANIPConnection:1#GetExternalIPAddress" \
-d "<?xml version='1.0' encoding='utf-8'?> <s:Envelope s:encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' xmlns:s='http://schemas.xmlsoap.org/soap/envelope/'> <s:Body> <u:GetExternalIPAddress xmlns:u='urn:dslforum-org:service:WANIPConnection:1'></u:GetExternalIPAddress> </s:Body> </s:Envelope>" | egrep -o "(::)?[0-9a-fA-F]{1,4}(::?[0-9a-fA-F]{1,4}){1,7}(::)?")
if [ -z "$FRITZ_IPV6_GUA" ]; then
echo "Error! Can't get IPv6 GUA from FRITZ!Box"
exit 0
else
echo "FRITZ!Box IPv6 GUA is: $FRITZ_IPV6_GUA"
fi
</syntaxhighlight>

== STUN Server nutzen ==
Alternativ kann ein STUN-Server zur Ermittlung der externen IP genutzt werden. Beispiel-Snippet (Perl):<syntaxhighlight lang="perl">
sub myip {
use STUN::Client;
my $stun_client = STUN::Client->new;
$stun_client->stun_server('stun.ekiga.net');
my (undef, $result) = $stun_client->get;
return $result->{'attributes'}->{'0001'}->{'address'};
}

</syntaxhighlight>Hinweis: Das Perl-Modul <code>STUN::Client</code> ist ggf. nicht in jeder Distribution verfügbar und muss über CPAN installiert werden.

Weitere Details und Diskussion: https://forum.fhem.de/index.php?topic=141872.msg1343225#msg1343225

== IPs des FHEM Servers ermitteln (ohne Link-Local, Docker, etc) ==
Sofern der FHEM Server bereits eine öffentliche IP hat, kann man diese von den lokalen Netzwerkinterfaces abfragen. Mit wenigen Abhängigkeiten geht dies unter typischen Linux-Distributionen wie Debian Buster, Bullseye, Bookworm oder aktueller mit:<syntaxhighlight lang="perl">
define LocalIPs at +*00:01:00 {
my $hash = $defs{$SELF};
my (@ipv4, @ipv6);

#Abfragen der IP Adressen mittels CLI:
my $json = qx(ip -j addr show scope global);
my $data = decode_json($json);

for my $iface (@$data) {
for my $addr (@{$iface->{addr_info} || []}) {
next unless $addr->{local};
if ($addr->{family} eq 'inet') {
push @ipv4, $addr->{local};
} elsif ($addr->{family} eq 'inet6') {
push @ipv6, $addr->{local};
}
}
}

readingsBeginUpdate($hash);
readingsBulkUpdate($hash, "allIPv4", join(',', @ipv4));
readingsBulkUpdate($hash, "allIPv6", join(',', @ipv6));
readingsEndUpdate($hash, 1);
}
attr LocalIPs alignTime 00:00:00
attr LocalIPs event-on-change-reading .*
attr LocalIPs stateFormat IPv4: allIPv4<br />IPv6: allIPv6
</syntaxhighlight>

Öffentliche IP-Adresse

2025-06-17T05:27:53Z

Torxgewinde: /* Spezielle Abfrage der Fritzbox für Sonderfälle */

== Einleitung ==
In FHEM kann die aktuell verwendete öffentliche IP-Adresse (IPv4/IPv6) auf verschiedene Arten ermittelt werden. Eine Methode ist der Abruf über externe Webdienste. Es kann auch auf lokale Router-Informationen (z. B. Fritzbox) oder systemnahe Module (z.B. STUN) zurückgegriffen werden.

== HTTPMOD-Definition zum ermitteln der öffentlichen IPv4 und IPv6 via HTTPS-Webdienst ==
Die öffentliche IP kann man mit Webdiensten ermitteln, die einem die IPv4 und/oder IPv6 anzeigen mit der die Seite abgerufen wird:<syntaxhighlight lang="perl">
defmod PublicIP HTTPMOD https://ipwho.de/json/ 600
attr PublicIP extractAllJSON 1
</syntaxhighlight>Ein Abfrageintervall von 300 bis 600 Sekunden (5 bis 10 Minuten) wird empfohlen – häufigere Abfragen belasten die externen Dienste unnötig.

=== Weitere Dienste ===
{| class="wikitable"
|+Getestete Dienste zum ermitteln der öffentlichen IP via HTTPS
!Anbieter
!Adresse
!Zuletzt erfolgreich getestet im Jahr
|-
|<code>ipify.org</code>
|https://api64.ipify.org/?format=json
|2025
|-
|<code>ipwho.de</code>
|https://ipwho.de/json/
|2025
|-
|<code>ipinfo.io</code>
|https://ipinfo.io/json/
|2025
|-
|<code>myip.com</code>
|https://api.myip.com/
|2025
|-
|<code>ident.me</code>
|https://a.ident.me/json
|2025
|-
|
|
|
|}

== Fritzbox nutzen ==

=== Reguläres Device nutzen ===

Wird eine Fritzbox als Router in das Internet verwendet, kann man die öffentliche IP sehr einfach vom Router abfragen. Der Vorteil dieser Lösung besteht darin, dass kein externer Dienst abgefragt werden muss:<syntaxhighlight lang="perl">
defmod Fritzbox FRITZBOX 192.168.123.123
attr Fritzbox INTERVAL 300
attr Fritzbox boxUser <dein Fritzbox User>
attr Fritzbox nonblockingTimeOut 100
</syntaxhighlight>Hierbei sind die Attribute wie die IP Adresse und Nutzername auf der Fritzbox anzupassen.

Die IPv4 und IPv6 der Fritzbox, als auch das IPv6 Prefix des lokalen Netzes sind als Readings direkt abfragbar:
<code>box_ipv4_Extern</code>
<code>box_ipv6_Extern</code>
<code>box_ipv6_Prefix</code>

=== Spezielle Abfrage der Fritzbox für Sonderfälle ===
In einigen Fällen stellt das Fritzbox Device nicht die passenden Readings bereit (zum Beispiel bei einer FB 6660 cable). Da in solchen Fällen CGNAT/DS-Lite eine IPv4 Abfrage vom Internet aus auf FHEM verhindert ist nur die öffentlich erreichbare IPv6 Adresse von Interesse (=GUA).

Es steht zur Zeit nur ein BASH Skript bereit ({{Link2Forum|Topic=141872|Message=1343341|LinkText=Quelle}}):<syntaxhighlight lang="bash">
#!/bin/bash

FRITZ_USER="<USER>"
FRITZ_PASS="<PASS>"
FRITZ_HOSTNAME="<HOST>"

FRITZ_IPV6_GUA=$(curl -s --max-time 10 \
--anyauth --user "${FRITZ_USER}:${FRITZ_PASS}" \
http://${FRITZ_HOSTNAME}:49000/upnp/control/wanipconnection1 \
-H "Content-Type: text/xml; charset="utf-8"" \
-H "SoapAction:urn:dslforum-org:service:WANIPConnection:1#GetExternalIPAddress" \
-d "<?xml version='1.0' encoding='utf-8'?> <s:Envelope s:encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' xmlns:s='http://schemas.xmlsoap.org/soap/envelope/'> <s:Body> <u:GetExternalIPAddress xmlns:u='urn:dslforum-org:service:WANIPConnection:1'></u:GetExternalIPAddress> </s:Body> </s:Envelope>" | egrep -o "(::)?[0-9a-fA-F]{1,4}(::?[0-9a-fA-F]{1,4}){1,7}(::)?")
if [ -z "$FRITZ_IPV6_GUA" ]; then
echo "Error! Can't get IPv6 GUA from FRITZ!Box"
exit 0
else
echo "FRITZ!Box IPv6 GUA is: $FRITZ_IPV6_GUA"
fi
</syntaxhighlight>

== STUN Server nutzen ==
Alternativ kann ein STUN-Server zur Ermittlung der externen IP genutzt werden. Beispiel-Snippet (Perl):<syntaxhighlight lang="perl">
sub myip {
use STUN::Client;
my $stun_client = STUN::Client->new;
$stun_client->stun_server('stun.ekiga.net');
my (undef, $result) = $stun_client->get;
return $result->{'attributes'}->{'0001'}->{'address'};
}

</syntaxhighlight>Hinweis: Das Perl-Modul <code>STUN::Client</code> ist ggf. nicht in jeder Distribution verfügbar und muss über CPAN installiert werden.

Weitere Details und Diskussion: https://forum.fhem.de/index.php?topic=141872.msg1343225#msg1343225

== IPs des FHEM Servers ermitteln (ohne Link-Local, Docker, etc) ==
Sofern der FHEM Server bereits eine öffentliche IP hat, kann man diese von den lokalen Netzwerkinterfaces abfragen. Mit wenigen Abhängigkeiten geht dies unter typischen Linux-Distributionen wie Debian Buster, Bullseye, Bookworm oder aktueller mit:<syntaxhighlight lang="perl">
define LocalIPs at +*00:01:00 {
my $hash = $defs{$SELF};
my (@ipv4, @ipv6);

#Abfragen der IP Adressen mittels CLI:
my $json = qx(ip -j addr show scope global);
my $data = decode_json($json);

for my $iface (@$data) {
for my $addr (@{$iface->{addr_info} || []}) {
next unless $addr->{local};
if ($addr->{family} eq 'inet') {
push @ipv4, $addr->{local};
} elsif ($addr->{family} eq 'inet6') {
push @ipv6, $addr->{local};
}
}
}

readingsBeginUpdate($hash);
readingsBulkUpdate($hash, "allIPv4", join(',', @ipv4));
readingsBulkUpdate($hash, "allIPv6", join(',', @ipv6));
readingsEndUpdate($hash, 1);
}
attr LocalIPs alignTime 00:00:00
attr LocalIPs event-on-change-reading .*
attr LocalIPs stateFormat IPv4: allIPv4<br />IPv6: allIPv6
</syntaxhighlight>

Öffentliche IP-Adresse

2025-06-17T05:27:09Z

Torxgewinde: /* Spezielle Abfrage der Fritzbox für Sonderfälle */

== Einleitung ==
In FHEM kann die aktuell verwendete öffentliche IP-Adresse (IPv4/IPv6) auf verschiedene Arten ermittelt werden. Eine Methode ist der Abruf über externe Webdienste. Es kann auch auf lokale Router-Informationen (z. B. Fritzbox) oder systemnahe Module (z.B. STUN) zurückgegriffen werden.

== HTTPMOD-Definition zum ermitteln der öffentlichen IPv4 und IPv6 via HTTPS-Webdienst ==
Die öffentliche IP kann man mit Webdiensten ermitteln, die einem die IPv4 und/oder IPv6 anzeigen mit der die Seite abgerufen wird:<syntaxhighlight lang="perl">
defmod PublicIP HTTPMOD https://ipwho.de/json/ 600
attr PublicIP extractAllJSON 1
</syntaxhighlight>Ein Abfrageintervall von 300 bis 600 Sekunden (5 bis 10 Minuten) wird empfohlen – häufigere Abfragen belasten die externen Dienste unnötig.

=== Weitere Dienste ===
{| class="wikitable"
|+Getestete Dienste zum ermitteln der öffentlichen IP via HTTPS
!Anbieter
!Adresse
!Zuletzt erfolgreich getestet im Jahr
|-
|<code>ipify.org</code>
|https://api64.ipify.org/?format=json
|2025
|-
|<code>ipwho.de</code>
|https://ipwho.de/json/
|2025
|-
|<code>ipinfo.io</code>
|https://ipinfo.io/json/
|2025
|-
|<code>myip.com</code>
|https://api.myip.com/
|2025
|-
|<code>ident.me</code>
|https://a.ident.me/json
|2025
|-
|
|
|
|}

== Fritzbox nutzen ==

=== Reguläres Device nutzen ===

Wird eine Fritzbox als Router in das Internet verwendet, kann man die öffentliche IP sehr einfach vom Router abfragen. Der Vorteil dieser Lösung besteht darin, dass kein externer Dienst abgefragt werden muss:<syntaxhighlight lang="perl">
defmod Fritzbox FRITZBOX 192.168.123.123
attr Fritzbox INTERVAL 300
attr Fritzbox boxUser <dein Fritzbox User>
attr Fritzbox nonblockingTimeOut 100
</syntaxhighlight>Hierbei sind die Attribute wie die IP Adresse und Nutzername auf der Fritzbox anzupassen.

Die IPv4 und IPv6 der Fritzbox, als auch das IPv6 Prefix des lokalen Netzes sind als Readings direkt abfragbar:
<code>box_ipv4_Extern</code>
<code>box_ipv6_Extern</code>
<code>box_ipv6_Prefix</code>

=== Spezielle Abfrage der Fritzbox für Sonderfälle ===
In einigen Fällen stellt das Fritzbox Device nicht die passenden Readings bereit (zum Beispiel bei einer FB 6660 cable). Da in solchen Fällen CGNAT/DS-Lite eine IPv4 Abfrage vom Internet aus auf FHEM verhindert ist nur die öffentlich erreichbare IPv6 Adresse von Interesse (=GUA).

Es steht zur Zeit nur ein BASH Skript bereit ({{Link2Forum|Topic=141872|Message=1343332|LinkText=Quelle}}):<syntaxhighlight lang="bash">
#!/bin/bash

FRITZ_USER="<USER>"
FRITZ_PASS="<PASS>"
FRITZ_HOSTNAME="<HOST>"

FRITZ_IPV6_GUA=$(curl -s --max-time 10 \
--anyauth --user "${FRITZ_USER}:${FRITZ_PASS}" \
http://${FRITZ_HOSTNAME}:49000/upnp/control/wanipconnection1 \
-H "Content-Type: text/xml; charset="utf-8"" \
-H "SoapAction:urn:dslforum-org:service:WANIPConnection:1#GetExternalIPAddress" \
-d "<?xml version='1.0' encoding='utf-8'?> <s:Envelope s:encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' xmlns:s='http://schemas.xmlsoap.org/soap/envelope/'> <s:Body> <u:GetExternalIPAddress xmlns:u='urn:dslforum-org:service:WANIPConnection:1'></u:GetExternalIPAddress> </s:Body> </s:Envelope>" | egrep -o "(::)?[0-9a-fA-F]{1,4}(::?[0-9a-fA-F]{1,4}){1,7}(::)?")
if [ -z "$FRITZ_IPV6_GUA" ]; then
echo "Error! Can't get IPv6 GUA from FRITZ!Box"
exit 0
else
echo "FRITZ!Box IPv6 GUA is: $FRITZ_IPV6_GUA"
fi
</syntaxhighlight>

== STUN Server nutzen ==
Alternativ kann ein STUN-Server zur Ermittlung der externen IP genutzt werden. Beispiel-Snippet (Perl):<syntaxhighlight lang="perl">
sub myip {
use STUN::Client;
my $stun_client = STUN::Client->new;
$stun_client->stun_server('stun.ekiga.net');
my (undef, $result) = $stun_client->get;
return $result->{'attributes'}->{'0001'}->{'address'};
}

</syntaxhighlight>Hinweis: Das Perl-Modul <code>STUN::Client</code> ist ggf. nicht in jeder Distribution verfügbar und muss über CPAN installiert werden.

Weitere Details und Diskussion: https://forum.fhem.de/index.php?topic=141872.msg1343225#msg1343225

== IPs des FHEM Servers ermitteln (ohne Link-Local, Docker, etc) ==
Sofern der FHEM Server bereits eine öffentliche IP hat, kann man diese von den lokalen Netzwerkinterfaces abfragen. Mit wenigen Abhängigkeiten geht dies unter typischen Linux-Distributionen wie Debian Buster, Bullseye, Bookworm oder aktueller mit:<syntaxhighlight lang="perl">
define LocalIPs at +*00:01:00 {
my $hash = $defs{$SELF};
my (@ipv4, @ipv6);

#Abfragen der IP Adressen mittels CLI:
my $json = qx(ip -j addr show scope global);
my $data = decode_json($json);

for my $iface (@$data) {
for my $addr (@{$iface->{addr_info} || []}) {
next unless $addr->{local};
if ($addr->{family} eq 'inet') {
push @ipv4, $addr->{local};
} elsif ($addr->{family} eq 'inet6') {
push @ipv6, $addr->{local};
}
}
}

readingsBeginUpdate($hash);
readingsBulkUpdate($hash, "allIPv4", join(',', @ipv4));
readingsBulkUpdate($hash, "allIPv6", join(',', @ipv6));
readingsEndUpdate($hash, 1);
}
attr LocalIPs alignTime 00:00:00
attr LocalIPs event-on-change-reading .*
attr LocalIPs stateFormat IPv4: allIPv4<br />IPv6: allIPv6
</syntaxhighlight>

Öffentliche IP-Adresse

2025-06-17T05:26:26Z

Torxgewinde: Hinweise von @passibe wie man die GUA abfragen kann

== Einleitung ==
In FHEM kann die aktuell verwendete öffentliche IP-Adresse (IPv4/IPv6) auf verschiedene Arten ermittelt werden. Eine Methode ist der Abruf über externe Webdienste. Es kann auch auf lokale Router-Informationen (z. B. Fritzbox) oder systemnahe Module (z.B. STUN) zurückgegriffen werden.

== HTTPMOD-Definition zum ermitteln der öffentlichen IPv4 und IPv6 via HTTPS-Webdienst ==
Die öffentliche IP kann man mit Webdiensten ermitteln, die einem die IPv4 und/oder IPv6 anzeigen mit der die Seite abgerufen wird:<syntaxhighlight lang="perl">
defmod PublicIP HTTPMOD https://ipwho.de/json/ 600
attr PublicIP extractAllJSON 1
</syntaxhighlight>Ein Abfrageintervall von 300 bis 600 Sekunden (5 bis 10 Minuten) wird empfohlen – häufigere Abfragen belasten die externen Dienste unnötig.

=== Weitere Dienste ===
{| class="wikitable"
|+Getestete Dienste zum ermitteln der öffentlichen IP via HTTPS
!Anbieter
!Adresse
!Zuletzt erfolgreich getestet im Jahr
|-
|<code>ipify.org</code>
|https://api64.ipify.org/?format=json
|2025
|-
|<code>ipwho.de</code>
|https://ipwho.de/json/
|2025
|-
|<code>ipinfo.io</code>
|https://ipinfo.io/json/
|2025
|-
|<code>myip.com</code>
|https://api.myip.com/
|2025
|-
|<code>ident.me</code>
|https://a.ident.me/json
|2025
|-
|
|
|
|}

== Fritzbox nutzen ==

=== Reguläres Device nutzen ===

Wird eine Fritzbox als Router in das Internet verwendet, kann man die öffentliche IP sehr einfach vom Router abfragen. Der Vorteil dieser Lösung besteht darin, dass kein externer Dienst abgefragt werden muss:<syntaxhighlight lang="perl">
defmod Fritzbox FRITZBOX 192.168.123.123
attr Fritzbox INTERVAL 300
attr Fritzbox boxUser <dein Fritzbox User>
attr Fritzbox nonblockingTimeOut 100
</syntaxhighlight>Hierbei sind die Attribute wie die IP Adresse und Nutzername auf der Fritzbox anzupassen.

Die IPv4 und IPv6 der Fritzbox, als auch das IPv6 Prefix des lokalen Netzes sind als Readings direkt abfragbar:
<code>box_ipv4_Extern</code>
<code>box_ipv6_Extern</code>
<code>box_ipv6_Prefix</code>

=== Spezielle Abfrage der Fritzbox für Sonderfälle ===
In einigen Fällen stellt das Fritzbox Device nicht die passenden Readings bereit (zum Beispiel bei einer FB 6660 cable). Da in solchen Fällen CGNAT/DS-Lite eine IPv4 Abfrage vom Internet aus auf FHEM verhindert ist nur die öffentlich erreichbare IPv6 Adresse von Interesse (=GUA).

Es steht zur Zeit nur ein BASH Skript bereit ({{Link2Forum|Topic=141872.msg1343332|Message=msg1343332|LinkText=Quelle}}):<syntaxhighlight lang="bash">
#!/bin/bash

FRITZ_USER="<USER>"
FRITZ_PASS="<PASS>"
FRITZ_HOSTNAME="<HOST>"

FRITZ_IPV6_GUA=$(curl -s --max-time 10 \
--anyauth --user "${FRITZ_USER}:${FRITZ_PASS}" \
http://${FRITZ_HOSTNAME}:49000/upnp/control/wanipconnection1 \
-H "Content-Type: text/xml; charset="utf-8"" \
-H "SoapAction:urn:dslforum-org:service:WANIPConnection:1#GetExternalIPAddress" \
-d "<?xml version='1.0' encoding='utf-8'?> <s:Envelope s:encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' xmlns:s='http://schemas.xmlsoap.org/soap/envelope/'> <s:Body> <u:GetExternalIPAddress xmlns:u='urn:dslforum-org:service:WANIPConnection:1'></u:GetExternalIPAddress> </s:Body> </s:Envelope>" | egrep -o "(::)?[0-9a-fA-F]{1,4}(::?[0-9a-fA-F]{1,4}){1,7}(::)?")
if [ -z "$FRITZ_IPV6_GUA" ]; then
echo "Error! Can't get IPv6 GUA from FRITZ!Box"
exit 0
else
echo "FRITZ!Box IPv6 GUA is: $FRITZ_IPV6_GUA"
fi
</syntaxhighlight>

== STUN Server nutzen ==
Alternativ kann ein STUN-Server zur Ermittlung der externen IP genutzt werden. Beispiel-Snippet (Perl):<syntaxhighlight lang="perl">
sub myip {
use STUN::Client;
my $stun_client = STUN::Client->new;
$stun_client->stun_server('stun.ekiga.net');
my (undef, $result) = $stun_client->get;
return $result->{'attributes'}->{'0001'}->{'address'};
}

</syntaxhighlight>Hinweis: Das Perl-Modul <code>STUN::Client</code> ist ggf. nicht in jeder Distribution verfügbar und muss über CPAN installiert werden.

Weitere Details und Diskussion: https://forum.fhem.de/index.php?topic=141872.msg1343225#msg1343225

== IPs des FHEM Servers ermitteln (ohne Link-Local, Docker, etc) ==
Sofern der FHEM Server bereits eine öffentliche IP hat, kann man diese von den lokalen Netzwerkinterfaces abfragen. Mit wenigen Abhängigkeiten geht dies unter typischen Linux-Distributionen wie Debian Buster, Bullseye, Bookworm oder aktueller mit:<syntaxhighlight lang="perl">
define LocalIPs at +*00:01:00 {
my $hash = $defs{$SELF};
my (@ipv4, @ipv6);

#Abfragen der IP Adressen mittels CLI:
my $json = qx(ip -j addr show scope global);
my $data = decode_json($json);

for my $iface (@$data) {
for my $addr (@{$iface->{addr_info} || []}) {
next unless $addr->{local};
if ($addr->{family} eq 'inet') {
push @ipv4, $addr->{local};
} elsif ($addr->{family} eq 'inet6') {
push @ipv6, $addr->{local};
}
}
}

readingsBeginUpdate($hash);
readingsBulkUpdate($hash, "allIPv4", join(',', @ipv4));
readingsBulkUpdate($hash, "allIPv6", join(',', @ipv6));
readingsEndUpdate($hash, 1);
}
attr LocalIPs alignTime 00:00:00
attr LocalIPs event-on-change-reading .*
attr LocalIPs stateFormat IPv4: allIPv4<br />IPv6: allIPv6
</syntaxhighlight>

Öffentliche IP-Adresse

2025-06-16T20:11:09Z

Torxgewinde: /* IPs des FHEM Servers ermitteln (ohne Link-Local, Docker, etc) */

Öffentliche IP-Adresse

2025-06-16T20:10:24Z

Torxgewinde: Falls man die IP Adressen des Servers direkt nutzen kann, ein at device ergänzt

Öffentliche IP-Adresse

2025-06-16T16:30:12Z

Torxgewinde: /* HTTPMOD-Definition zum ermitteln der öffentlichen IPv4 und IPv6 via HTTPS-Webdienst */

Öffentliche IP-Adresse

2025-06-16T16:29:44Z

Torxgewinde: /* STUN Server nutzen */

Öffentliche IP-Adresse

2025-06-16T15:01:03Z

Torxgewinde: Öffentliche IPv4 und IPv6 ermitteln, Wie in Snippet https://forum.fhem.de/index.php?topic=141872.0 besprochen

E-Mail senden

2025-05-26T05:11:07Z

Torxgewinde: Info von @Remstäler zu Strato hinzugefügt

Um aus FHEM heraus E-Mails senden zu können, gibt es unterschiedliche Methoden, abhängig von der verwendeten Plattform.

Lange Zeit war <code>sendemail</code> sehr beliebt. Da aber die Homepage des Projekts nicht mehr online ist und Probleme nur noch via erhöhtem Supportaufwand gelöst werden, sollte diese Option als veraltet betrachtet werden.

Eine Liste mit ressourcensparenden E-Mails Clients findet man bei dem OpenWRT Projekt: https://openwrt.org/docs/guide-user/services/email/smtp.client

MSGMail ist ein FHEM eigenes Modul zum Versenden, die Einrichtung ist allerdings nicht gänzlich einfach. Anfängern sei die cURL Methode empfohlen.

=== MSGMail (Linux, Windows) ===
FHEM bringt ein eigenes Device zum Senden von E-Mails mit, welches in Perl implementiert ist: [https://fhem.de/commandref.html#MSGMail MSGMail, https://fhem.de/commandref.html#MSGMail]

=== cURL (Linux, Windows) ===
[https://curl.se/ cURL] kann auf praktisch [https://curl.se/download.html jedem Betriebssystem] genutzt werden, [https://curl.se/windows/ selbst unter Windows]. Es kann direkt mit einem SMTP Server E-Mails versenden und stellt damit eine moderne, portable und sichere Option zum Versenden von E-Mails dar.

In FHEM richtet man sich ein Device ein und passt die Details (<code>$emailTo, $emailFrom, $emailServer</code>) an. Das Programm cURL muss installiert sein (z.B. mit <code>apt install curl</code>, oder durch Herunterladen und Installieren von der [https://curl.se cURL-Webseite]).<syntaxhighlight lang="perl" line="1">
defmod sendMail dummy
attr sendMail readingList message password
attr sendMail setList message:textField-long password
attr sendMail userReadings state:message:[\s\S]* {\
my $emailTo = 'du@example.com';;\
my $emailFrom = 'fhem@example.de';;\
my $emailServer = 'mail.your-server.de';;\
\
#erzeuge Datumsangabe konform zu RFC-5322:\
my @emailDateArray = split(' ', strftime("%w %d %m %Y %H:%M:%S %z", localtime));;\
$emailDateArray[0] = (qw[Sun Mon Tue Wed Thu Fri Sat])[$emailDateArray[0]] . ',';;\
$emailDateArray[2] = (qw[Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec])[$emailDateArray[2]-1];;\
my $emailDate = join(' ', @emailDateArray);;\
\
# Passwort aus getKeyValue abrufen\
my ($err, $emailPass) = getKeyValue("${name}_password");;\
if ($err || !defined $emailPass) {\
return "Error retrieving password: $err";;\
}\
\
my $message = ReadingsVal($name, 'message', '???');;\
my $subject = "$name: FHEM Nachricht";;\
\
# Betreff extrahieren und aus der Nachricht entfernen\
if ($message =~ s/(?:Subject|Betreff)=["'](.*?)["']//) {\
$subject = $1;;\
}\
\
# Empfänger extrahieren und aus der Nachricht entfernen\
if ($message =~ s/(?:To|An)=["'](.*?)["']//) {\
$emailTo = $1;;\
}\
\
#Dateianhänge bestimmen\
my @attachments;;\
while ($message =~ s/(?:Attachment|Anhang)=["'](.*?)["']//) {\
my $file = $1;;\
return ">>$file<< not found, not sending email" unless (-e $file);;\
push (@attachments, $file);;\
}\
\
#der curl Befehl wird hier aufgebaut:\
my $cmd = "curl -m 19 --noproxy '*' --no-progress-meter --ssl-reqd smtps://$emailServer:465 ";;\
$cmd .= "--user '$emailFrom:$emailPass' --mail-from '$emailFrom' --mail-rcpt '$emailTo' ";;\
$cmd .= "--write-out 'Email sent with status %{http_code}' ";;\
$cmd .= "-H 'Subject: $subject' ";;\
$cmd .= "-H 'From: $emailFrom' ";;\
$cmd .= "-H 'Date: $emailDate' ";;\
\
#multipart/alternative für Text und HTML EMail Body\
$cmd .= "-F '=(;;type=multipart/alternative' ";;\
\
# Leerzeichen und <br> bzw <br \> am Anfang entfernen:\
$message =~ s/^(\s|<br(?:[ \/]+)>)+//;;\
# Leerzeichen und <br> bzw <br \> am Ende entfernen:\
$message =~ s/(\s|<br(?:[ \/]+)>)+$//;;\
\
#Plaintext E-Mail Inhalt an cURL:\
$cmd .= "-F \"=$message;;type=text/plain;; charset=UTF-8\" ";;\
#ersetze \n bzw. \r\n durch ein HTML-tag <br />:\
$message =~ s/\r?\n/<br \/>/g;;\
\
#HTML E-Mail Inhalt an cURL:\
$cmd .= "-F '= <body>$message</body>;;type=text/html;; charset=UTF-8' ";;\
$cmd .= "-F '=)' ";;\
\
#jetzt alle Attachments (0..N) anhängen:\
foreach my $file (@attachments) {\
$cmd .= "-F '=@".$file.";;encoder=base64' ";;\
}\
\
#stderr auch mit in den output sammeln:\
$cmd .= " 2>&1";;\
\
#Blockierender Aufruf von cURL in dieser Funktion via BlockingCall:\
if (!defined &sendMailfunc1) {\
*sendMailfunc1 = sub ($) {\
my ($param) = @_;;\
my $result;;\
$result = qx/$param/;;\
$result = MIME::Base64::encode_base64($result);;\
$result =~ s/\n//g;;\
return $result;;\
}\
}\
\
#Rückgabe über diese Funktion,\
#anzeigen in dem reading dieses UserReadings:\
if (!defined &sendMailfunc2) {\
*sendMailfunc2 = sub ($) {\
my ($result) = @_;;\
my $hash = $defs{$name};;\
$result = MIME::Base64::decode_base64($result);;\
readingsSingleUpdate($hash, $reading, $result, 1);;\
}\
}\
\
#funktion falls BlockingCall abgebrochen wird:\
if (!defined &sendMailfunc3) {\
*sendMailfunc3 = sub ($) {\
my ($result) = @_;;\
my $hash = $defs{$name};;\
readingsSingleUpdate($hash, $reading, $result, 1);;\
}\
}\
\
BlockingCall("sendMailfunc1", $cmd, "sendMailfunc2", 20, "sendMailfunc3", "Error: timeout");;\
\
return "started cURL command...";;\
},\
state:password:.* {\
# Passwort speichern\
my $ret = setKeyValue("${name}_password", ReadingsVal($name, 'password', undef)) // "password stored";;\
\
#password wieder aus der Variablen rausnehmen, soll nicht sichtbar bleiben:\
#\
# Hinweis: das Password taucht beim Setzen hierüber im Event-Log auf!\
# Alternativ: { setKeyValue("sendMail_password", "geheimesPasswort") }\
readingsBulkUpdate($hash, "password", "****");;\
\
return "$ret";;\
}
</syntaxhighlight>Das Passwort setzt man mit:

* <code>set sendMail password geheimesPasswort</code>
* Alternativ, damit das Passwort nicht im Log auftaucht: <code>{ setKeyValue("sendMail_password", "geheimesPasswort") }</code>

E-Mails kann man dann Senden mit:

* <code>set sendMail message Mein Text</code> (es wird der Standardbetreff und Empfänger aus dem Snippet genutzt)
* <code>set sendMail message Betreff="Mein Betreff" Mein Text</code>(es wird der Empfänger aus dem Snippet genutzt)
* <code>set sendMail message Subject="Dies ist ein Test" Mein Text</code>
* <code>set sendMail message To="jemand@example.com" Mein Text</code>
* <code>set sendMail message An="jemand@example.com" Mein Text</code>
* <code>set sendMail message An="jemand@example.com" Betreff="Mein Betreff" Mein Text</code>
* <code>set sendMail message To="jemand@example.com" Subject="Mein Betreff" Mein Text</code>
* <code>set sendMail message Subject="✅ Dies ist ein Test" Meldung mit Emoji ⚽ geht auch</code>
* Eine Datei mit anhängen: <code>set sendMail message Subject="Dies ist ein Test" Anhang="www/images/fhemSVG/bag.svg" Mein Text</code>
* Zwei Dateien mit anhängen: <code>set sendMail message Subject="Dies ist ein Test" Anhang="./www/images/fhemSVG/bag.svg" Anhang="www/images/fhemSVG/batterie.svg" Mein Text</code>, für die anzuhängenden Dateien können relative und absolute Pfade verwendet werden. Beim Vorbereiten der E-Mail wird geprüft ob die Dateien existieren, da dies sonst eine typische Fehlerquelle ist. Es wird nichts versendet wenn eine Datei nicht gefunden werden kann.

==== Fehlersuche ====

===== Fehlende Protokolloption in cURL =====
Sollte cURL zwar installiert sein, aber keine E-Mails versenden, kann es sein, dass das Protokoll nicht einkompiliert wurde. Dies ist bei OpenWRT zum Beispiel der Fall.

So sollte es aussehen (hier ein Ubuntu), relevant ist für diese Nutzung das Protokoll smtp und smtps, das braucht man:<syntaxhighlight lang="bash">
curl -V
curl 8.5.0 (x86_64-pc-linux-gnu) libcurl/8.5.0 OpenSSL/3.0.13 zlib/1.3 brotli/1.1.0 zstd/1.5.5 libidn2/2.3.7 libpsl/0.21.2 (+libidn2/2.3.7) libssh/0.10.6/openssl/zlib nghttp2/1.59.0 librtmp/2.3 OpenLDAP/2.6.7
Release-Date: 2023-12-06, security patched: 8.5.0-2ubuntu10.6
Protocols: dict file ftp ftps gopher gophers http https imap imaps ldap ldaps mqtt pop3 pop3s rtmp rtsp scp sftp smb smbs smtp smtps telnet tftp
Features: alt-svc AsynchDNS brotli GSS-API HSTS HTTP2 HTTPS-proxy IDN IPv6 Kerberos Largefile libz NTLM PSL SPNEGO SSL threadsafe TLS-SRP UnixSockets zstd

</syntaxhighlight>
So sollte es nicht aussehen (hier ein OpenWRT):
<syntaxhighlight lang="bash">
curl: (1) Protocol "smtps" not supported

curl -V
curl 8.10.1 (arm-openwrt-linux-gnu) libcurl/8.10.1 mbedTLS/3.6.2 nghttp2/1.63.0
Release-Date: 2024-09-18
Protocols: file ftp ftps http https ipfs ipns mqtt
Features: alt-svc HSTS HTTP2 HTTPS-proxy IPv6 Largefile SSL threadsafe UnixSockets
</syntaxhighlight>
Hat man nur ein cURL ohne das Protokoll, so muss man sich das Paket leider anderweitig beschaffen (chroot, selbst kompilieren, statisch gelinkte Version, ...).

===== Falscher Port, login options =====
Einige Provider nehmen ihre TLS verschlüsselten E-Mails über einen anderen Port an, häufig Port 587 (siehe auch {{Link2Forum|Topic= 140814|Message=1340366|LinkText=diesen Forenbeitrag}}). Ggf. muss man auch mit einigen Loginoptionen experimentieren bis cURL wie gewünscht funktioniert (Stichwort: ''[https://curl.se/docs/manpage.html#--login-options --login-options]'').

===== Alte cURL Version =====
Sollte eine sehr alte cURL Version kleiner 7.67.0 genutzt werden, fehlt der Schalter <code>--no-progress-meter.</code> In solchen Fällen sollte man cURL aktualisieren. Falls dies nicht möglich ist, kann man den Schalter ersetzen durch <code>--silent --show-error</code>

===== Providerspezifisches=====
Eine lose Liste mit providerspezifischen Erfolgen und Misserfolgen:
{| class="wikitable sortable"
|+Liste mit Rückmeldungen zu E-Mail Anbietern
!Provider
!Funktioniert
!Details
|-
|Hetzner
|Ja
|<syntaxhighlight lang="perl">
my $emailServer = 'mail.your-server.de';
...
smtps://$emailServer:465
</syntaxhighlight>
|-
|Vodafone
|Ja
|Folgende Schalter sind hilfreich:<syntaxhighlight lang="perl">
--ssl-reqd --sasl-ir smtps://$emailserver:465
</syntaxhighlight>
|-
|Freenet
|Nein (nicht zuverlässig aufgrund des Spamfilters)
|Der Spamfilter lässt teilweise Nachrichten passieren, teilweise wird die Verbindung abgelehnt:
<code>''550 Spam message rejected''</code>

https://forum.fhem.de/index.php?topic=140814.msg1341872#msg1341872
|-
|T-Online
|Ja?
|<syntaxhighlight lang="perl">
my $emailServer = 'securesmtp.t-online.de';
...
smtps://$emailServer:465
</syntaxhighlight>https://forum.fhem.de/index.php?topic=140814.msg1340258#msg1340258
|-
|GMX
|Ja
|<syntaxhighlight lang="perl">
my $emailServer = 'mail.gmx.net';
...
smtps://$emailserver:465
</syntaxhighlight>https://forum.fhem.de/index.php?topic=140814.msg1341891#msg1341891
|-
|Google -> GMail
|Ja
|<syntaxhighlight lang="perl">
my $emailServer = 'smtp.gmail.com';
...
smtps://$emailserver:465
</syntaxhighlight>https://forum.fhem.de/index.php?topic=140814.msg1341891#msg1341891
|-
|Strato
|Ja
|<syntaxhighlight lang="perl">
my $emailServer = 'smtp.strato.de';
...
smtps://$emailserver:465
</syntaxhighlight>https://forum.fhem.de/index.php?topic=140814.msg1342201#msg1342201
|}

Siehe auch dazu den {{Link2Forum|Message=1341182|Topic=140814|LinkText=Forumspost}}
===EXIM4 (Debian)===
Eine Anleitung zum Versenden von E-Mails mit Exim ist als PDF verfügbar: [[Medium:Anleitung Exim4 Debian GMX.pdf|PDF]]

===SSMTP (OpenWRT, embedded Distros)===

====Installation====
<syntaxhighlight lang="bash">
opkg update
opkg install ssmtp_2.64-4_mpc85xx.ipk
</syntaxhighlight>Damit <code>ssmtp</code> funktioniert müssen die Dateien <code>/etc/ssmtp/ssmtp.conf</code> und <code>/etc/ssmtp/revaliases</code> angepasst werden.

/etc/ssmtp/ssmtp.conf
<syntaxhighlight lang="text">
root=arnold@gmx.net
mailhub=mail.gmx.net:465
rewriteDomain=gmx.net
hostname=gmx.net
FromLineOverride=YES
UseTLS=YES
#UseSTARTTLS=YES
AuthUser=arnold@gmx.net
AuthPass=Passwort_von_arnold@gmx.net
</syntaxhighlight>

/etc/ssmtp/revaliases
<syntaxhighlight lang="text">
root:arnold@gmx.net:mail.gmx.net:465
</syntaxhighlight>

In der [[99_myUtils_anlegen|99_myUtils]] folgende Unterroutine einfügen:

<syntaxhighlight lang="perl">
sub OpenWRTMail
{
my $rcpt = shift;
my $subject = shift;
my $text = shift;
my $ret = "";
my $sender = "dockstar\@heye-tammo.de";
Log 1, "sendEmail RCP: $rcpt, Subject: $subject, Text: $text";
$ret .= qx(echo -e 'to:$rcpt\n from:$sender\nsubject:$subject\n$text\n' | ssmtp $rcpt);
$ret =~ s,[\r\n]*,,g; # remove CR from return-string
Log 1, "sendEmail returned: $ret";
}
</syntaxhighlight>

===PHP Mail Funktion (Synology DiskStation)===
Beim DSM 3.2 funktioniert der <code>php-mail</code>-Befehl, so dass man mittels folgendem Modul E-Mails versenden kann:
<syntaxhighlight lang="perl">
sub sendmail($$$) {
my($empf, $subj, $nachricht) = @_;
system("php -r 'mail(\"$empf\",\"$subj\",\"$nachricht\");'");
}
</syntaxhighlight>

===Sendemail (Veraltet, Debian-basierende Distros)===
Es handelt sich um ein Perl Programm, dass man aus den Paketquellen installieren kann.

Es gibt Probleme:

*mit der TLS bzw STARTTLS Verschlüsselung (https://github.com/fhem/fhem-docker/issues/254, https://www.mail-archive.com/debian-bugs-dist@lists.debian.org/msg1915977.html) ,
*Mit der Webseite des Projekts (https://web.archive.org/web/20190906140125/http://caspian.dotconf.net/menu/Software/SendEmail); diese ist nicht mehr verfügbar und nur eine archivierte Kopie kann eingesehen werden,

weswegen diese Lösung als technisch überholt gelten sollte. Will man trotzdem <code>sendemail</code> verwenden folgenden hier die Informationen dazu:

Auf dem Server muss <code>sendemail</code> installiert werden:<syntaxhighlight lang="bash" line="1">
sudo apt-get update
sudo apt-get install sendemail libio-socket-ssl-perl libnet-ssleay-perl perl
</syntaxhighlight>Man kann die korrekte Funktion im Terminal (ohne <code>{qx()}</code> ) oder auch in der FHEM Kommandozeile testen (Hinweis: manche Provider (z.B. gmail) lassen diesen Zugang erst nach Freischaltung zu!).

''Bei Gmail muss seit dem 30.6.2022 ein separates Passwort erzeugt werden, die alte Einstellung über "Zugriff durch weniger sichere Apps" funktioniert nicht mehr. Siehe Support Seite Google: <nowiki>https://support.google.com/accounts/answer/185833</nowiki>''

''Beispiel mit Gmail über Linux Terminalfenster:''
sendemail -f 'Der.Absender@gmail.com' -t 'Der.Empfaenger@gmail.com' -u 'subject' -m 'text' -a <nowiki>''</nowiki> -s 'smtp.gmail.com:587' -xu 'Der.Absender' -xp DASSUPERGEHEIMEPASSW0RT
In der [[99 myUtils anlegen|99_myUtils]] folgende Unterroutine einfügen:<syntaxhighlight lang="perl" line="1">
######## DebianMail Mail auf dem RPi versenden ############
# $provider für SMTP Server anpassen.
# Einmal in der FHEM Kommandozeile, user und password anpassen:
# {setKeyValue("myEmailKonto",'user@domain');;setKeyValue("myEmailPasswrd",'password')}
sub DebianMail
{
my $rcpt = shift;
my $subject = shift;
my $text = shift;
my $attach = shift;
my $ret = "";
my $error;
my $konto = getKeyValue("myEmailKonto");
my $passwrd = getKeyValue("myEmailPasswrd");
my $from = $konto; # or use different KeyValue if konto is not the from email address
my $provider = "smtp.1und1.de"; # smtp.domain.tld:port see provider documentation
#Log 1, "sendEmail RCP: $rcpt";
#Log 1, "sendEmail Subject: $subject";
#Log 1, "sendEmail Text: $text";
#Log 1, "sendEmail Anhang: $attach";
if (not defined($attach)){$attach=''}
$ret .= qx(sendemail -f '$from' -t '$rcpt' -u '$subject' -m '$text' -a $attach -s '$provider' -xu '$konto' -xp '$passwrd' -o tls=auto -o message-charset=utf-8);
$ret =~ s,[\r\n]*,,g; # remove CR from return-string
Log 1, "sendemail returned: $ret";
}
###############################################################################
</syntaxhighlight>

Die Zugangsdaten für den Email-Account müssen dabei FHEM-intern gespeichert werden. Dazu gibt man einmalig über die Kommandozeile folgendes ein (user@domain und password müssen auf den Email Account geändert werden):

:<code>{setKeyValue("myEmailKonto",'user@domain');;setKeyValue("myEmailPasswrd",'password')}</code>

Um die TLS Verschlüsselung (ehem. SSL) nicht zu nutzen, muss in der viertletzten Zeile tls=no verwendet und der Port des Mailproviders auf 25 eigetragen werden. Sollte anschließend keine Mail verschickt werden, siehe Probleme.

Falls der Body-Text in einem (Android-)Mailer auf dem Handy nicht gezeigt wird, kann der Parameter '''-o message-content-type=html''' helfen.

Die Funktion kann beispielsweise folgendermaßen aufgerufen werden:
<syntaxhighlight lang="perl">
{qx(sendemail -f 'Ab\@send.er' -t 'Emp\@faeng.er' -u 'subject' -m 'text' -a 'DateinameOderLeer' -s 'smtpFQDN:port' -xu 'MailUser' -xp 'PasswortOhneKlammeraffen')}
</syntaxhighlight>
Bei allen Feldern können generell doppelte " oder einfache ' Anführungszeichen verwendet werden. Innerhalb von "" müssen Sonderzeichen wie @ aber maskiert werden, da sie sonst als Steuerzeichen interpretiert werden:

:<code>"email\@email.domain" oder 'email@email.domain'</code>

Direkt in der FHEM Kommandozeile (ohne Anhang)

:<code>{DebianMail("email\@email.domain","Subject","Text")}</code>

Die ordnungsgemäße Ausführung wird mit 71 quittiert.

Beispiele mehrere Anhänge (Es ist wichtig Dateinamen mit Leerzeichen in separate Anführungszeichen zu setzen)
{DebianMail("email\@email.domain","Subject","Text","Anhang1 Anhang2 Anhang3")}
{DebianMail('email@email.domain','Subject','Text',"'with spaces Anhang1' 'with spaces Anhang2'")}
oder (mehr als einen Empfänger, diese können durch Leerzeichen, Semikolon oder Komma getrennt sein)
define Sonstiges at *01:00:00 {\
DebianMail('email@email.domain,email2@email.domain',"Subject","Text","'Anhang1' 'Anhang2' ...");;\
}

Die archivierte Doku zu <code>sendemail</code> befindet sich in der Änderungshistorie: https://wiki.fhem.de/w/index.php?title=E-Mail_senden&oldid=37524
[[Kategorie:E-Mail]]

Matrix

2025-05-24T17:07:31Z

Torxgewinde: /* Matrix per Device */

== Allgemeines ==
'''Matrix''' ist ein offenes Kommunikationsprotokoll für dezentrale Echtzeitkommunikation. Es wird von zahlreichen Clients unterstützt, darunter '''Element''', '''Element-X''', '''SchildiChat Next''', '''FluffyChat''' und viele weitere.

Viele Open-Source-Projekte betreiben eigene Chaträume auf föderierten Matrix-Servern. Ein Beispiel dafür ist der '''Gadgetbridge-Chat''', einer der größeren und aktiveren Räume im Matrix-Ökosystem.

== Matrix und FHEM ==
Um mit '''FHEM''' Nachrichten über das Matrix-Protokoll zu senden und zu empfangen, stehen mehrere Möglichkeiten zur Verfügung. Eine einfache und pragmatische Lösung ist die Nutzung eines '''HTTPMOD-Devices'''. Damit lassen sich Nachrichten über die Matrix-API versenden oder empfangen.

=== Matrix per Device ===
Es gibt ein Device für Matrix unter https://git.cooltux.net/FHEM/mod-matrix bzw https://github.com/Man-fred/matrix

==== Einrichten ====
Das Device ist nicht im FHEM Umfang enthalten und wird deswegen mit den folgenden Befehlen hinzugefügt:

<code>update add <nowiki>https://git.cooltux.net/FHEM/mod-matrix/raw/branch/dev/controls_Matrix.txt</nowiki></code>

<code>update</code>

<code>shutdown restart</code>

==== Weiteres ====
https://forum.fhem.de/index.php?topic=129978.0

=== Matrix per HTTPMOD Device ===
[[Datei:Screenshot des Matrix HTTPMOD Device.png|alternativtext=Screenshot des Matrix HTTPMOD Device|ohne|mini|Screenshot des Matrix HTTPMOD Device]]
Folgendes Device kann Matrix Nachrichten senden und empfangen, es hat wenige Abhängigkeiten und sollte in den meisten FHEM Installationen unkompliziert eingerichtet sein. Es wird die Datenübertragung von FHEM zum Server mit HTTPS verschlüsselt, E2EE wird nicht verwendet.

==== Einrichtung ====
Es sind die Attribute MatrixServer und MatrixUser zu setzen:

<code>attr MatrixBot MatrixServer Dein-Servername</code>

<code>attr MatrixBot MatrixUser FHEM-Matrix-Username</code>

Das Passwort des Matrix-FHEM-Users setzt man mit dem Befehl:

<code>set MatrixBot storeKeyValue MatrixPassword yourPassword123</code>

Dann richtet man einen, '''nicht E2E verschlüsselten Raum''' ein in dem der Matrix-FHEM-Account eingeladen ist. Von dem Raum benötigt man die MatrixRoomID, die man mit Element in den Raumdetails finden kann (Room Settings --> Advanced --> Internal room ID).

<code>attr MatrixBot MatrixRoomID !12345678901234:example.com</code>

==== Verwendung ====
Nachrichten senden geht mit:

<code>set MatrixBot sendText Bla Bla Bla</code>

Longpoll von Nachrichten starten und stoppen mit:

<code>set MatrixBot longpollCmd startTimer</code>

<code>set MatrixBot longpollCmd stopTimer</code>

==== Weiteres ====

===== Forumlink =====
https://forum.fhem.de/index.php?topic=120834.msg1339487#msg1339487

===== Demo-Device =====
Das folgende DOIF-Device lauscht auf eine eingehende Nachricht die als Inhalt "ping" oder "Ping" ist und antwortet mit "Pong!". Es dient als Beispiel und kann natürlich um weitere Befehle ergänzt/ersetzt werden um FHEM damit zu steuern:<syntaxhighlight lang="perl" line="1">
defmod MatrixPing.doif DOIF (["MatrixBot:msg: .*: @.*: [Pp]ing$"])\
(set MatrixBot sendText Pong!)
attr MatrixPing.doif alias Matrix Ping/Pong
attr MatrixPing.doif do always
attr MatrixPing.doif group Meldungen
attr MatrixPing.doif icon homeConnect
</syntaxhighlight>

==== Device-Definition ====
<syntaxhighlight lang="perl" line="1">
defmod MatrixBot HTTPMOD none 0
attr MatrixBot userattr MatrixRoomID MatrixServer MatrixUser
attr MatrixBot MatrixRoomID !12345678901234:nope.chat
attr MatrixBot MatrixServer nope.chat
attr MatrixBot MatrixUser DeinUsername
attr MatrixBot bodyDecode utf-8
attr MatrixBot bodyEncode utf-8
attr MatrixBot comment "\
Create a room for FHEM.\
\
The room must not use encryption, a room that has encryption\
enabled, cannot be converted to a non-encrypted room anymore \
\
The room-id can be found in Element-Web at:\
Room Settings --> Advanced --> Internal room ID\
\
To store the password in FHEM in obfuscated way:\
set MatrixBot storeKeyValue MatrixPassword yourPassword123\
\
###\
To send a text:\
set MatrixBot sendText Bla Bla Bla\
\
\
###\
To longpoll for messages once:\
# 1. send special filter to Matrix:\
set MatrixBot sendFilter\
\
# 2. start one longPoll (waits up to 60 seconds\
# or until data is available)\
get MatrixBot longpoll\
\
#alternatively, to keep on longPolling (this also sets filter):\
set MatrixBot longpollCmd startTimer\
#to stop the timers:\
set MatrixBot longpollCmd stopTimer\
\
#############################################################\
https://spec.matrix.org/v1.14/client-server-api/#syncing\
"
attr MatrixBot get02AlwaysNum 0
attr MatrixBot get02HeaderAuthorization Authorization: Bearer $sid
attr MatrixBot get02Name longpoll
attr MatrixBot get02Regex \"next_batch\":\s*\"(?<next_batch>[^\"]+)\"(?:.*?\"timeline\":\s*{\s*\"events\":\s*(?<messages>\[.*?\])\s*)?
attr MatrixBot get02TextArg 0
attr MatrixBot get02URL https://[$name:MatrixServer]/_matrix/client/v3/sync?timeout=60000&filter=[$name:filter_id]%%next_batch_param%%
attr MatrixBot icon message_info
attr MatrixBot parseFunction1 handleAuthErrors
attr MatrixBot reAuthAlways 0
attr MatrixBot reAuthRegex M_UNKNOWN_TOKEN
attr MatrixBot replacement01Mode expression
attr MatrixBot replacement01Regex \[([^:\s\[\"\']+):([^\]\s]+)\]
attr MatrixBot replacement01Value my $device = $name if ($1 eq "\$name") // $1;;\
ReadingsVal($device, $2, undef) or AttrVal($device, $2, "???");;
attr MatrixBot replacement02Mode expression
attr MatrixBot replacement02Regex %%uuid%%
attr MatrixBot replacement02Value join("-", unpack("A8 A4 A4 A4 A12", unpack("H*", join("", map { chr(int rand 256) } 0..15))))
attr MatrixBot replacement03Mode key
attr MatrixBot replacement03Regex %%MatrixPassword%%
attr MatrixBot replacement03Value MatrixPassword
attr MatrixBot replacement04Mode expression
attr MatrixBot replacement04Regex %%next_batch_param%%
attr MatrixBot replacement04Value #is there a reading 'next_batch'?\
my $val = ReadingsVal($name, 'next_batch', '???');;\
\
#return the GET parameter 'sync=value' for /sync Endpoint\
return "&since=$val" if ($val ne '???');;\
\
#return neither since-key nor value for it:\
return "";;
attr MatrixBot set01Data {\
"msgtype": "m.text",\
"body": "$val"\
}
attr MatrixBot set01HeaderAuthorization Authorization: Bearer $sid
attr MatrixBot set01HeaderContent-Type application/json
attr MatrixBot set01IExpr #cancel an active longpoll\
if ($hash->{BUSY}\
&& $hash->{HttpUtils}\
&& $hash->{HttpUtils}->{url} =~ m|^https://[^/]+/_matrix/client/v3/sync\?timeout=\d+&filter=| ) {\
Log(3, "$name: longpoll active, cutting it off now");;\
HttpUtils_Close($hash->{HttpUtils});;\
}\
\
#just return $val unteraltered\
$val
attr MatrixBot set01Method POST
attr MatrixBot set01Name sendText
attr MatrixBot set01ParseResponse 1
attr MatrixBot set01Regex {\"event_id\":\"(.*)\"}
attr MatrixBot set01TextArg 1
attr MatrixBot set01URL https://[$name:MatrixServer]/_matrix/client/v3/rooms/[$name:MatrixRoomID]/send/m.room.message?txnId=%%uuid%%
attr MatrixBot set02Data {\
"room": {\
"rooms": ["[$name:MatrixRoomID]"],\
"timeline": {\
"limit": 10,\
"types": ["m.room.message"]\
},\
"include_leave": false,\
"include_join": false,\
"include_account_data": false,\
"include_state": false,\
"state": {\
"types": []\
},\
"ephemeral": {\
"types": []\
},\
"account_data": {\
"types": []\
}\
},\
"event_fields": [\
"content.body",\
"sender",\
"origin_server_ts"\
],\
"event_format": "client",\
"presence": {\
"types": [],\
"not_types": ["*"]\
},\
"account_data": {\
"types": [],\
"not_types": ["*"]\
}\
}
attr MatrixBot set02HeaderAuthorization Authorization: Bearer $sid
attr MatrixBot set02HeaderContent-Type application/json
attr MatrixBot set02Method POST
attr MatrixBot set02Name sendFilter
attr MatrixBot set02NoArg 1
attr MatrixBot set02ParseResponse 1
attr MatrixBot set02Regex \"filter_id\":\s*\"(?<filter_id>\d+)\"
attr MatrixBot set02URL https://[$name:MatrixServer]/_matrix/client/v3/user/@[$name:MatrixUser]:[$name:MatrixServer]/filter
attr MatrixBot set03Local 1
attr MatrixBot set03Name longpollCmd
attr MatrixBot set03TextArg 1
attr MatrixBot showError 1
attr MatrixBot sid01Data {\
"type": "m.login.password",\
"identifier": {\
"type": "m.id.user",\
"user": "[$name:MatrixUser]"\
},\
"password": "%%MatrixPassword%%"\
}
attr MatrixBot sid01HeaderContent-Type application/json
attr MatrixBot sid01IdRegex "access_token"\s*:\s*"([^"]+)"
attr MatrixBot sid01URL https://[$name:MatrixServer]/_matrix/client/v3/login
attr MatrixBot timeout 65
attr MatrixBot userReadings longpollTimer:(next_batch|longpollCmd|LAST_ERROR|sendText):.* {\
my $longpollCmd = ReadingsVal($name, 'longpollCmd', '???');;\
my $delay = 1;;\
my $timeout = AttrVal($name, 'timeout', 61) + $delay + 5;;\
\
# stop our timers:\
if ($longpollCmd eq "stopTimer") {\
fhem("cancel ${name}_longpollTimer quiet");;\
fhem("cancel ${name}_longpollTimer2 quiet");;\
return "stopped";;\
}\
\
if ($longpollCmd ne "startTimer") {\
return "no timer set, longpollCmd is not set to 'startTimer'";;\
}\
\
#if startTimer cmd was given now, set filter as well:\
if (ReadingsAge($name, 'longpollCmd', 0) <= 1) {\
$delay = 5;; #delay to allow for sendFilter to be answered\
#Log(1, "🪲 $name: >>". InternalVal($name, 'httpbody', '???') ."<<");;\
fhem("sleep 0.1 quiet;; set $name sendFilter");;\
}\
\
#we handle an error reported by http-utils:\
if (ReadingsAge($name, 'LAST_ERROR', 0) <= 1) {\
my $last_error = ReadingsVal($name, 'LAST_ERROR', '???');;\
$delay = 10;; #delay to allow for error reasons to improve\
#Log(1, "🪲 $name: Dealing with error: >>$last_error<<");;\
}\
\
# for testing this: { $defs{MatrixBot}{sid} = 'bla' }\
if (!defined &HTTPMOD::handleAuthErrors) {\
*HTTPMOD::handleAuthErrors = sub {\
my ($hash, $header, $body, $request) = @_;;\
my $name = $hash->{NAME};;\
my $status;;\
\
if ($header =~ m{^HTTP/\d\.\d\s+(\d+)}m) {\
$status = $1;;\
}\
\
Log3($name, 4, "$name: HTTP status code is $status");;\
\
if ( $status == 401 || $status == 403 || $status == 500 ) {\
Log3($name, 3, "$name: auth-error or servererror ($status), calling doAuth()");;\
HTTPMOD::DoAuth($hash);;\
}\
};;\
}\
\
#set timers, one regular and one fallback:\
fhem("sleep $delay ${name}_longpollTimer quiet;; get $name longpoll");;\
fhem("sleep $timeout ${name}_longpollTimer2 quiet;; set $name longpollCmd startTimer");;\
\
return strftime("next longpoll at %H:%M:%S", localtime( time()+$delay ));;\
},\
messages_list:messages:.* {\
my $this = ReadingsVal($name, $reading, '');;\
my @timestampArray = split("\n", $this);;\
my $messages_ref = decode_json(ReadingsVal($name, 'messages', ''));;\
my $length = 20;;\
\
my %seen_messages = map { $_ => 1 } @timestampArray;;\
\
foreach my $msg (@$messages_ref) {\
my $val = $msg->{content}{body};;\
$val = Encode::decode('utf-8', $val) unless Encode::is_utf8($val);;\
$val =~ s/\n/ /g;; #replace newlines with spaces\
\
my $sender = $msg->{sender};;\
my $ts = strftime("%Y-%m-%d %H:%M:%S", localtime($msg->{origin_server_ts} / 1000));;\
my $new_entry = "$ts: $sender: $val";;\
\
next if $seen_messages{$new_entry};;\
\
my $inserted = 0;;\
for (my $i = 0;; $i < @timestampArray;; $i++) {\
my ($existing_ts) = $timestampArray[$i] =~ /^([^:]+):/;;\
if ($ts lt $existing_ts) {\
splice(@timestampArray, $i, 0, $new_entry);;\
$inserted = 1;;\
last;;\
}\
}\
push(@timestampArray, encode('utf-8', $new_entry)) unless $inserted;;\
shift(@timestampArray) while @timestampArray > $length;;\
}\
\
return join("\n", @timestampArray);;\
},\
process_messages:messages:.* {\
my $val = ReadingsVal($name, 'messages_list', '');;\
my $this = ReadingsVal($name, $reading, '');;\
my $latest_ts = $this;;\
\
foreach my $line (split(/\n/, $val)) {\
if ($line =~ /^(\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}):\s*(.*)$/) {\
my ($ts, $msg) = ($1, $2);;\
\
if ($ts gt $this) {\
fhem("trigger $name msg: $line");;\
$latest_ts = $ts if ($ts gt $latest_ts);;\
}\
}\
}\
return $latest_ts;;\
}
attr MatrixBot verbose 3
attr MatrixBot widgetOverride longpollCmd:uzsuSelectRadio,startTimer,stopTimer
</syntaxhighlight>

Matrix

2025-05-24T16:57:42Z

Torxgewinde: /* Matrix per Device */

== Allgemeines ==
'''Matrix''' ist ein offenes Kommunikationsprotokoll für dezentrale Echtzeitkommunikation. Es wird von zahlreichen Clients unterstützt, darunter '''Element''', '''Element-X''', '''SchildiChat Next''', '''FluffyChat''' und viele weitere.

Viele Open-Source-Projekte betreiben eigene Chaträume auf föderierten Matrix-Servern. Ein Beispiel dafür ist der '''Gadgetbridge-Chat''', einer der größeren und aktiveren Räume im Matrix-Ökosystem.

== Matrix und FHEM ==
Um mit '''FHEM''' Nachrichten über das Matrix-Protokoll zu senden und zu empfangen, stehen mehrere Möglichkeiten zur Verfügung. Eine einfache und pragmatische Lösung ist die Nutzung eines '''HTTPMOD-Devices'''. Damit lassen sich Nachrichten über die Matrix-API versenden oder empfangen.

=== Matrix per Device ===
Es gibt ein Device für Matrix unter https://git.cooltux.net/FHEM/mod-matrix bzw https://github.com/Man-fred/matrix

=== Matrix per HTTPMOD Device ===
[[Datei:Screenshot des Matrix HTTPMOD Device.png|alternativtext=Screenshot des Matrix HTTPMOD Device|ohne|mini|Screenshot des Matrix HTTPMOD Device]]
Folgendes Device kann Matrix Nachrichten senden und empfangen, es hat wenige Abhängigkeiten und sollte in den meisten FHEM Installationen unkompliziert eingerichtet sein. Es wird die Datenübertragung von FHEM zum Server mit HTTPS verschlüsselt, E2EE wird nicht verwendet.

==== Einrichtung ====
Es sind die Attribute MatrixServer und MatrixUser zu setzen:

<code>attr MatrixBot MatrixServer Dein-Servername</code>

<code>attr MatrixBot MatrixUser FHEM-Matrix-Username</code>

Das Passwort des Matrix-FHEM-Users setzt man mit dem Befehl:

<code>set MatrixBot storeKeyValue MatrixPassword yourPassword123</code>

Dann richtet man einen, '''nicht E2E verschlüsselten Raum''' ein in dem der Matrix-FHEM-Account eingeladen ist. Von dem Raum benötigt man die MatrixRoomID, die man mit Element in den Raumdetails finden kann (Room Settings --> Advanced --> Internal room ID).

<code>attr MatrixBot MatrixRoomID !12345678901234:example.com</code>

==== Verwendung ====
Nachrichten senden geht mit:

<code>set MatrixBot sendText Bla Bla Bla</code>

Longpoll von Nachrichten starten und stoppen mit:

<code>set MatrixBot longpollCmd startTimer</code>

<code>set MatrixBot longpollCmd stopTimer</code>

==== Weiteres ====

===== Forumlink =====
https://forum.fhem.de/index.php?topic=120834.msg1339487#msg1339487

===== Demo-Device =====
Das folgende DOIF-Device lauscht auf eine eingehende Nachricht die als Inhalt "ping" oder "Ping" ist und antwortet mit "Pong!". Es dient als Beispiel und kann natürlich um weitere Befehle ergänzt/ersetzt werden um FHEM damit zu steuern:<syntaxhighlight lang="perl" line="1">
defmod MatrixPing.doif DOIF (["MatrixBot:msg: .*: @.*: [Pp]ing$"])\
(set MatrixBot sendText Pong!)
attr MatrixPing.doif alias Matrix Ping/Pong
attr MatrixPing.doif do always
attr MatrixPing.doif group Meldungen
attr MatrixPing.doif icon homeConnect
</syntaxhighlight>

==== Device-Definition ====
<syntaxhighlight lang="perl" line="1">
defmod MatrixBot HTTPMOD none 0
attr MatrixBot userattr MatrixRoomID MatrixServer MatrixUser
attr MatrixBot MatrixRoomID !12345678901234:nope.chat
attr MatrixBot MatrixServer nope.chat
attr MatrixBot MatrixUser DeinUsername
attr MatrixBot bodyDecode utf-8
attr MatrixBot bodyEncode utf-8
attr MatrixBot comment "\
Create a room for FHEM.\
\
The room must not use encryption, a room that has encryption\
enabled, cannot be converted to a non-encrypted room anymore \
\
The room-id can be found in Element-Web at:\
Room Settings --> Advanced --> Internal room ID\
\
To store the password in FHEM in obfuscated way:\
set MatrixBot storeKeyValue MatrixPassword yourPassword123\
\
###\
To send a text:\
set MatrixBot sendText Bla Bla Bla\
\
\
###\
To longpoll for messages once:\
# 1. send special filter to Matrix:\
set MatrixBot sendFilter\
\
# 2. start one longPoll (waits up to 60 seconds\
# or until data is available)\
get MatrixBot longpoll\
\
#alternatively, to keep on longPolling (this also sets filter):\
set MatrixBot longpollCmd startTimer\
#to stop the timers:\
set MatrixBot longpollCmd stopTimer\
\
#############################################################\
https://spec.matrix.org/v1.14/client-server-api/#syncing\
"
attr MatrixBot get02AlwaysNum 0
attr MatrixBot get02HeaderAuthorization Authorization: Bearer $sid
attr MatrixBot get02Name longpoll
attr MatrixBot get02Regex \"next_batch\":\s*\"(?<next_batch>[^\"]+)\"(?:.*?\"timeline\":\s*{\s*\"events\":\s*(?<messages>\[.*?\])\s*)?
attr MatrixBot get02TextArg 0
attr MatrixBot get02URL https://[$name:MatrixServer]/_matrix/client/v3/sync?timeout=60000&filter=[$name:filter_id]%%next_batch_param%%
attr MatrixBot icon message_info
attr MatrixBot parseFunction1 handleAuthErrors
attr MatrixBot reAuthAlways 0
attr MatrixBot reAuthRegex M_UNKNOWN_TOKEN
attr MatrixBot replacement01Mode expression
attr MatrixBot replacement01Regex \[([^:\s\[\"\']+):([^\]\s]+)\]
attr MatrixBot replacement01Value my $device = $name if ($1 eq "\$name") // $1;;\
ReadingsVal($device, $2, undef) or AttrVal($device, $2, "???");;
attr MatrixBot replacement02Mode expression
attr MatrixBot replacement02Regex %%uuid%%
attr MatrixBot replacement02Value join("-", unpack("A8 A4 A4 A4 A12", unpack("H*", join("", map { chr(int rand 256) } 0..15))))
attr MatrixBot replacement03Mode key
attr MatrixBot replacement03Regex %%MatrixPassword%%
attr MatrixBot replacement03Value MatrixPassword
attr MatrixBot replacement04Mode expression
attr MatrixBot replacement04Regex %%next_batch_param%%
attr MatrixBot replacement04Value #is there a reading 'next_batch'?\
my $val = ReadingsVal($name, 'next_batch', '???');;\
\
#return the GET parameter 'sync=value' for /sync Endpoint\
return "&since=$val" if ($val ne '???');;\
\
#return neither since-key nor value for it:\
return "";;
attr MatrixBot set01Data {\
"msgtype": "m.text",\
"body": "$val"\
}
attr MatrixBot set01HeaderAuthorization Authorization: Bearer $sid
attr MatrixBot set01HeaderContent-Type application/json
attr MatrixBot set01IExpr #cancel an active longpoll\
if ($hash->{BUSY}\
&& $hash->{HttpUtils}\
&& $hash->{HttpUtils}->{url} =~ m|^https://[^/]+/_matrix/client/v3/sync\?timeout=\d+&filter=| ) {\
Log(3, "$name: longpoll active, cutting it off now");;\
HttpUtils_Close($hash->{HttpUtils});;\
}\
\
#just return $val unteraltered\
$val
attr MatrixBot set01Method POST
attr MatrixBot set01Name sendText
attr MatrixBot set01ParseResponse 1
attr MatrixBot set01Regex {\"event_id\":\"(.*)\"}
attr MatrixBot set01TextArg 1
attr MatrixBot set01URL https://[$name:MatrixServer]/_matrix/client/v3/rooms/[$name:MatrixRoomID]/send/m.room.message?txnId=%%uuid%%
attr MatrixBot set02Data {\
"room": {\
"rooms": ["[$name:MatrixRoomID]"],\
"timeline": {\
"limit": 10,\
"types": ["m.room.message"]\
},\
"include_leave": false,\
"include_join": false,\
"include_account_data": false,\
"include_state": false,\
"state": {\
"types": []\
},\
"ephemeral": {\
"types": []\
},\
"account_data": {\
"types": []\
}\
},\
"event_fields": [\
"content.body",\
"sender",\
"origin_server_ts"\
],\
"event_format": "client",\
"presence": {\
"types": [],\
"not_types": ["*"]\
},\
"account_data": {\
"types": [],\
"not_types": ["*"]\
}\
}
attr MatrixBot set02HeaderAuthorization Authorization: Bearer $sid
attr MatrixBot set02HeaderContent-Type application/json
attr MatrixBot set02Method POST
attr MatrixBot set02Name sendFilter
attr MatrixBot set02NoArg 1
attr MatrixBot set02ParseResponse 1
attr MatrixBot set02Regex \"filter_id\":\s*\"(?<filter_id>\d+)\"
attr MatrixBot set02URL https://[$name:MatrixServer]/_matrix/client/v3/user/@[$name:MatrixUser]:[$name:MatrixServer]/filter
attr MatrixBot set03Local 1
attr MatrixBot set03Name longpollCmd
attr MatrixBot set03TextArg 1
attr MatrixBot showError 1
attr MatrixBot sid01Data {\
"type": "m.login.password",\
"identifier": {\
"type": "m.id.user",\
"user": "[$name:MatrixUser]"\
},\
"password": "%%MatrixPassword%%"\
}
attr MatrixBot sid01HeaderContent-Type application/json
attr MatrixBot sid01IdRegex "access_token"\s*:\s*"([^"]+)"
attr MatrixBot sid01URL https://[$name:MatrixServer]/_matrix/client/v3/login
attr MatrixBot timeout 65
attr MatrixBot userReadings longpollTimer:(next_batch|longpollCmd|LAST_ERROR|sendText):.* {\
my $longpollCmd = ReadingsVal($name, 'longpollCmd', '???');;\
my $delay = 1;;\
my $timeout = AttrVal($name, 'timeout', 61) + $delay + 5;;\
\
# stop our timers:\
if ($longpollCmd eq "stopTimer") {\
fhem("cancel ${name}_longpollTimer quiet");;\
fhem("cancel ${name}_longpollTimer2 quiet");;\
return "stopped";;\
}\
\
if ($longpollCmd ne "startTimer") {\
return "no timer set, longpollCmd is not set to 'startTimer'";;\
}\
\
#if startTimer cmd was given now, set filter as well:\
if (ReadingsAge($name, 'longpollCmd', 0) <= 1) {\
$delay = 5;; #delay to allow for sendFilter to be answered\
#Log(1, "🪲 $name: >>". InternalVal($name, 'httpbody', '???') ."<<");;\
fhem("sleep 0.1 quiet;; set $name sendFilter");;\
}\
\
#we handle an error reported by http-utils:\
if (ReadingsAge($name, 'LAST_ERROR', 0) <= 1) {\
my $last_error = ReadingsVal($name, 'LAST_ERROR', '???');;\
$delay = 10;; #delay to allow for error reasons to improve\
#Log(1, "🪲 $name: Dealing with error: >>$last_error<<");;\
}\
\
# for testing this: { $defs{MatrixBot}{sid} = 'bla' }\
if (!defined &HTTPMOD::handleAuthErrors) {\
*HTTPMOD::handleAuthErrors = sub {\
my ($hash, $header, $body, $request) = @_;;\
my $name = $hash->{NAME};;\
my $status;;\
\
if ($header =~ m{^HTTP/\d\.\d\s+(\d+)}m) {\
$status = $1;;\
}\
\
Log3($name, 4, "$name: HTTP status code is $status");;\
\
if ( $status == 401 || $status == 403 || $status == 500 ) {\
Log3($name, 3, "$name: auth-error or servererror ($status), calling doAuth()");;\
HTTPMOD::DoAuth($hash);;\
}\
};;\
}\
\
#set timers, one regular and one fallback:\
fhem("sleep $delay ${name}_longpollTimer quiet;; get $name longpoll");;\
fhem("sleep $timeout ${name}_longpollTimer2 quiet;; set $name longpollCmd startTimer");;\
\
return strftime("next longpoll at %H:%M:%S", localtime( time()+$delay ));;\
},\
messages_list:messages:.* {\
my $this = ReadingsVal($name, $reading, '');;\
my @timestampArray = split("\n", $this);;\
my $messages_ref = decode_json(ReadingsVal($name, 'messages', ''));;\
my $length = 20;;\
\
my %seen_messages = map { $_ => 1 } @timestampArray;;\
\
foreach my $msg (@$messages_ref) {\
my $val = $msg->{content}{body};;\
$val = Encode::decode('utf-8', $val) unless Encode::is_utf8($val);;\
$val =~ s/\n/ /g;; #replace newlines with spaces\
\
my $sender = $msg->{sender};;\
my $ts = strftime("%Y-%m-%d %H:%M:%S", localtime($msg->{origin_server_ts} / 1000));;\
my $new_entry = "$ts: $sender: $val";;\
\
next if $seen_messages{$new_entry};;\
\
my $inserted = 0;;\
for (my $i = 0;; $i < @timestampArray;; $i++) {\
my ($existing_ts) = $timestampArray[$i] =~ /^([^:]+):/;;\
if ($ts lt $existing_ts) {\
splice(@timestampArray, $i, 0, $new_entry);;\
$inserted = 1;;\
last;;\
}\
}\
push(@timestampArray, encode('utf-8', $new_entry)) unless $inserted;;\
shift(@timestampArray) while @timestampArray > $length;;\
}\
\
return join("\n", @timestampArray);;\
},\
process_messages:messages:.* {\
my $val = ReadingsVal($name, 'messages_list', '');;\
my $this = ReadingsVal($name, $reading, '');;\
my $latest_ts = $this;;\
\
foreach my $line (split(/\n/, $val)) {\
if ($line =~ /^(\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}):\s*(.*)$/) {\
my ($ts, $msg) = ($1, $2);;\
\
if ($ts gt $this) {\
fhem("trigger $name msg: $line");;\
$latest_ts = $ts if ($ts gt $latest_ts);;\
}\
}\
}\
return $latest_ts;;\
}
attr MatrixBot verbose 3
attr MatrixBot widgetOverride longpollCmd:uzsuSelectRadio,startTimer,stopTimer
</syntaxhighlight>

Matrix

2025-05-24T09:32:15Z

Torxgewinde: Cooltux Device auch mit aufgeführt, Screenshot ergänzt

== Allgemeines ==
'''Matrix''' ist ein offenes Kommunikationsprotokoll für dezentrale Echtzeitkommunikation. Es wird von zahlreichen Clients unterstützt, darunter '''Element''', '''Element-X''', '''SchildiChat Next''', '''FluffyChat''' und viele weitere.

Viele Open-Source-Projekte betreiben eigene Chaträume auf föderierten Matrix-Servern. Ein Beispiel dafür ist der '''Gadgetbridge-Chat''', einer der größeren und aktiveren Räume im Matrix-Ökosystem.

== Matrix und FHEM ==
Um mit '''FHEM''' Nachrichten über das Matrix-Protokoll zu senden und zu empfangen, stehen mehrere Möglichkeiten zur Verfügung. Eine einfache und pragmatische Lösung ist die Nutzung eines '''HTTPMOD-Devices'''. Damit lassen sich Nachrichten über die Matrix-API versenden oder empfangen.

=== Matrix per Device ===
Es gibt ein Device für Matrix unter https://git.cooltux.net/FHEM/mod-matrix

=== Matrix per HTTPMOD Device ===
[[Datei:Screenshot des Matrix HTTPMOD Device.png|alternativtext=Screenshot des Matrix HTTPMOD Device|ohne|mini|Screenshot des Matrix HTTPMOD Device]]
Folgendes Device kann Matrix Nachrichten senden und empfangen, es hat wenige Abhängigkeiten und sollte in den meisten FHEM Installationen unkompliziert eingerichtet sein. Es wird die Datenübertragung von FHEM zum Server mit HTTPS verschlüsselt, E2EE wird nicht verwendet.

==== Einrichtung ====
Es sind die Attribute MatrixServer und MatrixUser zu setzen:

<code>attr MatrixBot MatrixServer Dein-Servername</code>

<code>attr MatrixBot MatrixUser FHEM-Matrix-Username</code>

Das Passwort des Matrix-FHEM-Users setzt man mit dem Befehl:

<code>set MatrixBot storeKeyValue MatrixPassword yourPassword123</code>

Dann richtet man einen, '''nicht E2E verschlüsselten Raum''' ein in dem der Matrix-FHEM-Account eingeladen ist. Von dem Raum benötigt man die MatrixRoomID, die man mit Element in den Raumdetails finden kann (Room Settings --> Advanced --> Internal room ID).

<code>attr MatrixBot MatrixRoomID !12345678901234:example.com</code>

==== Verwendung ====
Nachrichten senden geht mit:

<code>set MatrixBot sendText Bla Bla Bla</code>

Longpoll von Nachrichten starten und stoppen mit:

<code>set MatrixBot longpollCmd startTimer</code>

<code>set MatrixBot longpollCmd stopTimer</code>

==== Weiteres ====

===== Forumlink =====
https://forum.fhem.de/index.php?topic=120834.msg1339487#msg1339487

===== Demo-Device =====
Das folgende DOIF-Device lauscht auf eine eingehende Nachricht die als Inhalt "ping" oder "Ping" ist und antwortet mit "Pong!". Es dient als Beispiel und kann natürlich um weitere Befehle ergänzt/ersetzt werden um FHEM damit zu steuern:<syntaxhighlight lang="perl" line="1">
defmod MatrixPing.doif DOIF (["MatrixBot:msg: .*: @.*: [Pp]ing$"])\
(set MatrixBot sendText Pong!)
attr MatrixPing.doif alias Matrix Ping/Pong
attr MatrixPing.doif do always
attr MatrixPing.doif group Meldungen
attr MatrixPing.doif icon homeConnect
</syntaxhighlight>

==== Device-Definition ====
<syntaxhighlight lang="perl" line="1">
defmod MatrixBot HTTPMOD none 0
attr MatrixBot userattr MatrixRoomID MatrixServer MatrixUser
attr MatrixBot MatrixRoomID !12345678901234:nope.chat
attr MatrixBot MatrixServer nope.chat
attr MatrixBot MatrixUser DeinUsername
attr MatrixBot bodyDecode utf-8
attr MatrixBot bodyEncode utf-8
attr MatrixBot comment "\
Create a room for FHEM.\
\
The room must not use encryption, a room that has encryption\
enabled, cannot be converted to a non-encrypted room anymore \
\
The room-id can be found in Element-Web at:\
Room Settings --> Advanced --> Internal room ID\
\
To store the password in FHEM in obfuscated way:\
set MatrixBot storeKeyValue MatrixPassword yourPassword123\
\
###\
To send a text:\
set MatrixBot sendText Bla Bla Bla\
\
\
###\
To longpoll for messages once:\
# 1. send special filter to Matrix:\
set MatrixBot sendFilter\
\
# 2. start one longPoll (waits up to 60 seconds\
# or until data is available)\
get MatrixBot longpoll\
\
#alternatively, to keep on longPolling (this also sets filter):\
set MatrixBot longpollCmd startTimer\
#to stop the timers:\
set MatrixBot longpollCmd stopTimer\
\
#############################################################\
https://spec.matrix.org/v1.14/client-server-api/#syncing\
"
attr MatrixBot get02AlwaysNum 0
attr MatrixBot get02HeaderAuthorization Authorization: Bearer $sid
attr MatrixBot get02Name longpoll
attr MatrixBot get02Regex \"next_batch\":\s*\"(?<next_batch>[^\"]+)\"(?:.*?\"timeline\":\s*{\s*\"events\":\s*(?<messages>\[.*?\])\s*)?
attr MatrixBot get02TextArg 0
attr MatrixBot get02URL https://[$name:MatrixServer]/_matrix/client/v3/sync?timeout=60000&filter=[$name:filter_id]%%next_batch_param%%
attr MatrixBot icon message_info
attr MatrixBot parseFunction1 handleAuthErrors
attr MatrixBot reAuthAlways 0
attr MatrixBot reAuthRegex M_UNKNOWN_TOKEN
attr MatrixBot replacement01Mode expression
attr MatrixBot replacement01Regex \[([^:\s\[\"\']+):([^\]\s]+)\]
attr MatrixBot replacement01Value my $device = $name if ($1 eq "\$name") // $1;;\
ReadingsVal($device, $2, undef) or AttrVal($device, $2, "???");;
attr MatrixBot replacement02Mode expression
attr MatrixBot replacement02Regex %%uuid%%
attr MatrixBot replacement02Value join("-", unpack("A8 A4 A4 A4 A12", unpack("H*", join("", map { chr(int rand 256) } 0..15))))
attr MatrixBot replacement03Mode key
attr MatrixBot replacement03Regex %%MatrixPassword%%
attr MatrixBot replacement03Value MatrixPassword
attr MatrixBot replacement04Mode expression
attr MatrixBot replacement04Regex %%next_batch_param%%
attr MatrixBot replacement04Value #is there a reading 'next_batch'?\
my $val = ReadingsVal($name, 'next_batch', '???');;\
\
#return the GET parameter 'sync=value' for /sync Endpoint\
return "&since=$val" if ($val ne '???');;\
\
#return neither since-key nor value for it:\
return "";;
attr MatrixBot set01Data {\
"msgtype": "m.text",\
"body": "$val"\
}
attr MatrixBot set01HeaderAuthorization Authorization: Bearer $sid
attr MatrixBot set01HeaderContent-Type application/json
attr MatrixBot set01IExpr #cancel an active longpoll\
if ($hash->{BUSY}\
&& $hash->{HttpUtils}\
&& $hash->{HttpUtils}->{url} =~ m|^https://[^/]+/_matrix/client/v3/sync\?timeout=\d+&filter=| ) {\
Log(3, "$name: longpoll active, cutting it off now");;\
HttpUtils_Close($hash->{HttpUtils});;\
}\
\
#just return $val unteraltered\
$val
attr MatrixBot set01Method POST
attr MatrixBot set01Name sendText
attr MatrixBot set01ParseResponse 1
attr MatrixBot set01Regex {\"event_id\":\"(.*)\"}
attr MatrixBot set01TextArg 1
attr MatrixBot set01URL https://[$name:MatrixServer]/_matrix/client/v3/rooms/[$name:MatrixRoomID]/send/m.room.message?txnId=%%uuid%%
attr MatrixBot set02Data {\
"room": {\
"rooms": ["[$name:MatrixRoomID]"],\
"timeline": {\
"limit": 10,\
"types": ["m.room.message"]\
},\
"include_leave": false,\
"include_join": false,\
"include_account_data": false,\
"include_state": false,\
"state": {\
"types": []\
},\
"ephemeral": {\
"types": []\
},\
"account_data": {\
"types": []\
}\
},\
"event_fields": [\
"content.body",\
"sender",\
"origin_server_ts"\
],\
"event_format": "client",\
"presence": {\
"types": [],\
"not_types": ["*"]\
},\
"account_data": {\
"types": [],\
"not_types": ["*"]\
}\
}
attr MatrixBot set02HeaderAuthorization Authorization: Bearer $sid
attr MatrixBot set02HeaderContent-Type application/json
attr MatrixBot set02Method POST
attr MatrixBot set02Name sendFilter
attr MatrixBot set02NoArg 1
attr MatrixBot set02ParseResponse 1
attr MatrixBot set02Regex \"filter_id\":\s*\"(?<filter_id>\d+)\"
attr MatrixBot set02URL https://[$name:MatrixServer]/_matrix/client/v3/user/@[$name:MatrixUser]:[$name:MatrixServer]/filter
attr MatrixBot set03Local 1
attr MatrixBot set03Name longpollCmd
attr MatrixBot set03TextArg 1
attr MatrixBot showError 1
attr MatrixBot sid01Data {\
"type": "m.login.password",\
"identifier": {\
"type": "m.id.user",\
"user": "[$name:MatrixUser]"\
},\
"password": "%%MatrixPassword%%"\
}
attr MatrixBot sid01HeaderContent-Type application/json
attr MatrixBot sid01IdRegex "access_token"\s*:\s*"([^"]+)"
attr MatrixBot sid01URL https://[$name:MatrixServer]/_matrix/client/v3/login
attr MatrixBot timeout 65
attr MatrixBot userReadings longpollTimer:(next_batch|longpollCmd|LAST_ERROR|sendText):.* {\
my $longpollCmd = ReadingsVal($name, 'longpollCmd', '???');;\
my $delay = 1;;\
my $timeout = AttrVal($name, 'timeout', 61) + $delay + 5;;\
\
# stop our timers:\
if ($longpollCmd eq "stopTimer") {\
fhem("cancel ${name}_longpollTimer quiet");;\
fhem("cancel ${name}_longpollTimer2 quiet");;\
return "stopped";;\
}\
\
if ($longpollCmd ne "startTimer") {\
return "no timer set, longpollCmd is not set to 'startTimer'";;\
}\
\
#if startTimer cmd was given now, set filter as well:\
if (ReadingsAge($name, 'longpollCmd', 0) <= 1) {\
$delay = 5;; #delay to allow for sendFilter to be answered\
#Log(1, "🪲 $name: >>". InternalVal($name, 'httpbody', '???') ."<<");;\
fhem("sleep 0.1 quiet;; set $name sendFilter");;\
}\
\
#we handle an error reported by http-utils:\
if (ReadingsAge($name, 'LAST_ERROR', 0) <= 1) {\
my $last_error = ReadingsVal($name, 'LAST_ERROR', '???');;\
$delay = 10;; #delay to allow for error reasons to improve\
#Log(1, "🪲 $name: Dealing with error: >>$last_error<<");;\
}\
\
# for testing this: { $defs{MatrixBot}{sid} = 'bla' }\
if (!defined &HTTPMOD::handleAuthErrors) {\
*HTTPMOD::handleAuthErrors = sub {\
my ($hash, $header, $body, $request) = @_;;\
my $name = $hash->{NAME};;\
my $status;;\
\
if ($header =~ m{^HTTP/\d\.\d\s+(\d+)}m) {\
$status = $1;;\
}\
\
Log3($name, 4, "$name: HTTP status code is $status");;\
\
if ( $status == 401 || $status == 403 || $status == 500 ) {\
Log3($name, 3, "$name: auth-error or servererror ($status), calling doAuth()");;\
HTTPMOD::DoAuth($hash);;\
}\
};;\
}\
\
#set timers, one regular and one fallback:\
fhem("sleep $delay ${name}_longpollTimer quiet;; get $name longpoll");;\
fhem("sleep $timeout ${name}_longpollTimer2 quiet;; set $name longpollCmd startTimer");;\
\
return strftime("next longpoll at %H:%M:%S", localtime( time()+$delay ));;\
},\
messages_list:messages:.* {\
my $this = ReadingsVal($name, $reading, '');;\
my @timestampArray = split("\n", $this);;\
my $messages_ref = decode_json(ReadingsVal($name, 'messages', ''));;\
my $length = 20;;\
\
my %seen_messages = map { $_ => 1 } @timestampArray;;\
\
foreach my $msg (@$messages_ref) {\
my $val = $msg->{content}{body};;\
$val = Encode::decode('utf-8', $val) unless Encode::is_utf8($val);;\
$val =~ s/\n/ /g;; #replace newlines with spaces\
\
my $sender = $msg->{sender};;\
my $ts = strftime("%Y-%m-%d %H:%M:%S", localtime($msg->{origin_server_ts} / 1000));;\
my $new_entry = "$ts: $sender: $val";;\
\
next if $seen_messages{$new_entry};;\
\
my $inserted = 0;;\
for (my $i = 0;; $i < @timestampArray;; $i++) {\
my ($existing_ts) = $timestampArray[$i] =~ /^([^:]+):/;;\
if ($ts lt $existing_ts) {\
splice(@timestampArray, $i, 0, $new_entry);;\
$inserted = 1;;\
last;;\
}\
}\
push(@timestampArray, encode('utf-8', $new_entry)) unless $inserted;;\
shift(@timestampArray) while @timestampArray > $length;;\
}\
\
return join("\n", @timestampArray);;\
},\
process_messages:messages:.* {\
my $val = ReadingsVal($name, 'messages_list', '');;\
my $this = ReadingsVal($name, $reading, '');;\
my $latest_ts = $this;;\
\
foreach my $line (split(/\n/, $val)) {\
if ($line =~ /^(\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}):\s*(.*)$/) {\
my ($ts, $msg) = ($1, $2);;\
\
if ($ts gt $this) {\
fhem("trigger $name msg: $line");;\
$latest_ts = $ts if ($ts gt $latest_ts);;\
}\
}\
}\
return $latest_ts;;\
}
attr MatrixBot verbose 3
attr MatrixBot widgetOverride longpollCmd:uzsuSelectRadio,startTimer,stopTimer
</syntaxhighlight>

Datei:Screenshot des Matrix HTTPMOD Device.png

2025-05-24T09:31:22Z

Torxgewinde:

Screenshot des Matrix HTTPMOD Device

Matrix

2025-05-24T08:46:02Z

Torxgewinde: /* Einrichtung */

== Allgemeines ==
'''Matrix''' ist ein offenes Kommunikationsprotokoll für dezentrale Echtzeitkommunikation. Es wird von zahlreichen Clients unterstützt, darunter '''Element''', '''Element-X''', '''SchildiChat Next''', '''FluffyChat''' und viele weitere.

Viele Open-Source-Projekte betreiben eigene Chaträume auf föderierten Matrix-Servern. Ein Beispiel dafür ist der '''Gadgetbridge-Chat''', einer der größeren und aktiveren Räume im Matrix-Ökosystem.

== Matrix und FHEM ==
Um mit '''FHEM''' Nachrichten über das Matrix-Protokoll zu senden und zu empfangen, stehen mehrere Möglichkeiten zur Verfügung. Eine einfache und pragmatische Lösung ist die Nutzung eines '''HTTPMOD-Devices'''. Damit lassen sich Nachrichten über die Matrix-API versenden oder empfangen.

=== Matrix per HTTPMOD Device ===
Folgendes Device kann Matrix Nachrichten senden und empfangen, es hat wenige Abhängigkeiten und sollte in den meisten FHEM Installationen unkompliziert eingerichtet sein. Es wird die Datenübertragung von FHEM zum Server mit HTTPS verschlüsselt, E2EE wird nicht verwendet.

==== Einrichtung ====
Es sind die Attribute MatrixServer und MatrixUser zu setzen:

<code>attr MatrixBot MatrixServer Dein-Servername</code>

<code>attr MatrixBot MatrixUser FHEM-Matrix-Username</code>

Das Passwort des Matrix-FHEM-Users setzt man mit dem Befehl:

<code>set MatrixBot storeKeyValue MatrixPassword yourPassword123</code>

Dann richtet man einen, '''nicht E2E verschlüsselten Raum''' ein in dem der Matrix-FHEM-Account eingeladen ist. Von dem Raum benötigt man die MatrixRoomID, die man mit Element in den Raumdetails finden kann (Room Settings --> Advanced --> Internal room ID).

<code>attr MatrixBot MatrixRoomID !12345678901234:example.com</code>

==== Verwendung ====
Nachrichten senden geht mit:

<code>set MatrixBot sendText Bla Bla Bla</code>

Longpoll von Nachrichten starten und stoppen mit:

<code>set MatrixBot longpollCmd startTimer</code>

<code>set MatrixBot longpollCmd stopTimer</code>

==== Weiteres ====

===== Forumlink =====
https://forum.fhem.de/index.php?topic=120834.msg1339487#msg1339487

===== Demo-Device =====
Das folgende DOIF-Device lauscht auf eine eingehende Nachricht die als Inhalt "ping" oder "Ping" ist und antwortet mit "Pong!". Es dient als Beispiel und kann natürlich um weitere Befehle ergänzt/ersetzt werden um FHEM damit zu steuern:<syntaxhighlight lang="perl" line="1">
defmod MatrixPing.doif DOIF (["MatrixBot:msg: .*: @.*: [Pp]ing$"])\
(set MatrixBot sendText Pong!)
attr MatrixPing.doif alias Matrix Ping/Pong
attr MatrixPing.doif do always
attr MatrixPing.doif group Meldungen
attr MatrixPing.doif icon homeConnect
</syntaxhighlight>

==== Device-Definition ====
<syntaxhighlight lang="perl" line="1">
defmod MatrixBot HTTPMOD none 0
attr MatrixBot userattr MatrixRoomID MatrixServer MatrixUser
attr MatrixBot MatrixRoomID !12345678901234:nope.chat
attr MatrixBot MatrixServer nope.chat
attr MatrixBot MatrixUser DeinUsername
attr MatrixBot bodyDecode utf-8
attr MatrixBot bodyEncode utf-8
attr MatrixBot comment "\
Create a room for FHEM.\
\
The room must not use encryption, a room that has encryption\
enabled, cannot be converted to a non-encrypted room anymore \
\
The room-id can be found in Element-Web at:\
Room Settings --> Advanced --> Internal room ID\
\
To store the password in FHEM in obfuscated way:\
set MatrixBot storeKeyValue MatrixPassword yourPassword123\
\
###\
To send a text:\
set MatrixBot sendText Bla Bla Bla\
\
\
###\
To longpoll for messages once:\
# 1. send special filter to Matrix:\
set MatrixBot sendFilter\
\
# 2. start one longPoll (waits up to 60 seconds\
# or until data is available)\
get MatrixBot longpoll\
\
#alternatively, to keep on longPolling (this also sets filter):\
set MatrixBot longpollCmd startTimer\
#to stop the timers:\
set MatrixBot longpollCmd stopTimer\
\
#############################################################\
https://spec.matrix.org/v1.14/client-server-api/#syncing\
"
attr MatrixBot get02AlwaysNum 0
attr MatrixBot get02HeaderAuthorization Authorization: Bearer $sid
attr MatrixBot get02Name longpoll
attr MatrixBot get02Regex \"next_batch\":\s*\"(?<next_batch>[^\"]+)\"(?:.*?\"timeline\":\s*{\s*\"events\":\s*(?<messages>\[.*?\])\s*)?
attr MatrixBot get02TextArg 0
attr MatrixBot get02URL https://[$name:MatrixServer]/_matrix/client/v3/sync?timeout=60000&filter=[$name:filter_id]%%next_batch_param%%
attr MatrixBot icon message_info
attr MatrixBot parseFunction1 handleAuthErrors
attr MatrixBot reAuthAlways 0
attr MatrixBot reAuthRegex M_UNKNOWN_TOKEN
attr MatrixBot replacement01Mode expression
attr MatrixBot replacement01Regex \[([^:\s\[\"\']+):([^\]\s]+)\]
attr MatrixBot replacement01Value my $device = $name if ($1 eq "\$name") // $1;;\
ReadingsVal($device, $2, undef) or AttrVal($device, $2, "???");;
attr MatrixBot replacement02Mode expression
attr MatrixBot replacement02Regex %%uuid%%
attr MatrixBot replacement02Value join("-", unpack("A8 A4 A4 A4 A12", unpack("H*", join("", map { chr(int rand 256) } 0..15))))
attr MatrixBot replacement03Mode key
attr MatrixBot replacement03Regex %%MatrixPassword%%
attr MatrixBot replacement03Value MatrixPassword
attr MatrixBot replacement04Mode expression
attr MatrixBot replacement04Regex %%next_batch_param%%
attr MatrixBot replacement04Value #is there a reading 'next_batch'?\
my $val = ReadingsVal($name, 'next_batch', '???');;\
\
#return the GET parameter 'sync=value' for /sync Endpoint\
return "&since=$val" if ($val ne '???');;\
\
#return neither since-key nor value for it:\
return "";;
attr MatrixBot set01Data {\
"msgtype": "m.text",\
"body": "$val"\
}
attr MatrixBot set01HeaderAuthorization Authorization: Bearer $sid
attr MatrixBot set01HeaderContent-Type application/json
attr MatrixBot set01IExpr #cancel an active longpoll\
if ($hash->{BUSY}\
&& $hash->{HttpUtils}\
&& $hash->{HttpUtils}->{url} =~ m|^https://[^/]+/_matrix/client/v3/sync\?timeout=\d+&filter=| ) {\
Log(3, "$name: longpoll active, cutting it off now");;\
HttpUtils_Close($hash->{HttpUtils});;\
}\
\
#just return $val unteraltered\
$val
attr MatrixBot set01Method POST
attr MatrixBot set01Name sendText
attr MatrixBot set01ParseResponse 1
attr MatrixBot set01Regex {\"event_id\":\"(.*)\"}
attr MatrixBot set01TextArg 1
attr MatrixBot set01URL https://[$name:MatrixServer]/_matrix/client/v3/rooms/[$name:MatrixRoomID]/send/m.room.message?txnId=%%uuid%%
attr MatrixBot set02Data {\
"room": {\
"rooms": ["[$name:MatrixRoomID]"],\
"timeline": {\
"limit": 10,\
"types": ["m.room.message"]\
},\
"include_leave": false,\
"include_join": false,\
"include_account_data": false,\
"include_state": false,\
"state": {\
"types": []\
},\
"ephemeral": {\
"types": []\
},\
"account_data": {\
"types": []\
}\
},\
"event_fields": [\
"content.body",\
"sender",\
"origin_server_ts"\
],\
"event_format": "client",\
"presence": {\
"types": [],\
"not_types": ["*"]\
},\
"account_data": {\
"types": [],\
"not_types": ["*"]\
}\
}
attr MatrixBot set02HeaderAuthorization Authorization: Bearer $sid
attr MatrixBot set02HeaderContent-Type application/json
attr MatrixBot set02Method POST
attr MatrixBot set02Name sendFilter
attr MatrixBot set02NoArg 1
attr MatrixBot set02ParseResponse 1
attr MatrixBot set02Regex \"filter_id\":\s*\"(?<filter_id>\d+)\"
attr MatrixBot set02URL https://[$name:MatrixServer]/_matrix/client/v3/user/@[$name:MatrixUser]:[$name:MatrixServer]/filter
attr MatrixBot set03Local 1
attr MatrixBot set03Name longpollCmd
attr MatrixBot set03TextArg 1
attr MatrixBot showError 1
attr MatrixBot sid01Data {\
"type": "m.login.password",\
"identifier": {\
"type": "m.id.user",\
"user": "[$name:MatrixUser]"\
},\
"password": "%%MatrixPassword%%"\
}
attr MatrixBot sid01HeaderContent-Type application/json
attr MatrixBot sid01IdRegex "access_token"\s*:\s*"([^"]+)"
attr MatrixBot sid01URL https://[$name:MatrixServer]/_matrix/client/v3/login
attr MatrixBot timeout 65
attr MatrixBot userReadings longpollTimer:(next_batch|longpollCmd|LAST_ERROR|sendText):.* {\
my $longpollCmd = ReadingsVal($name, 'longpollCmd', '???');;\
my $delay = 1;;\
my $timeout = AttrVal($name, 'timeout', 61) + $delay + 5;;\
\
# stop our timers:\
if ($longpollCmd eq "stopTimer") {\
fhem("cancel ${name}_longpollTimer quiet");;\
fhem("cancel ${name}_longpollTimer2 quiet");;\
return "stopped";;\
}\
\
if ($longpollCmd ne "startTimer") {\
return "no timer set, longpollCmd is not set to 'startTimer'";;\
}\
\
#if startTimer cmd was given now, set filter as well:\
if (ReadingsAge($name, 'longpollCmd', 0) <= 1) {\
$delay = 5;; #delay to allow for sendFilter to be answered\
#Log(1, "🪲 $name: >>". InternalVal($name, 'httpbody', '???') ."<<");;\
fhem("sleep 0.1 quiet;; set $name sendFilter");;\
}\
\
#we handle an error reported by http-utils:\
if (ReadingsAge($name, 'LAST_ERROR', 0) <= 1) {\
my $last_error = ReadingsVal($name, 'LAST_ERROR', '???');;\
$delay = 10;; #delay to allow for error reasons to improve\
#Log(1, "🪲 $name: Dealing with error: >>$last_error<<");;\
}\
\
# for testing this: { $defs{MatrixBot}{sid} = 'bla' }\
if (!defined &HTTPMOD::handleAuthErrors) {\
*HTTPMOD::handleAuthErrors = sub {\
my ($hash, $header, $body, $request) = @_;;\
my $name = $hash->{NAME};;\
my $status;;\
\
if ($header =~ m{^HTTP/\d\.\d\s+(\d+)}m) {\
$status = $1;;\
}\
\
Log3($name, 4, "$name: HTTP status code is $status");;\
\
if ( $status == 401 || $status == 403 || $status == 500 ) {\
Log3($name, 3, "$name: auth-error or servererror ($status), calling doAuth()");;\
HTTPMOD::DoAuth($hash);;\
}\
};;\
}\
\
#set timers, one regular and one fallback:\
fhem("sleep $delay ${name}_longpollTimer quiet;; get $name longpoll");;\
fhem("sleep $timeout ${name}_longpollTimer2 quiet;; set $name longpollCmd startTimer");;\
\
return strftime("next longpoll at %H:%M:%S", localtime( time()+$delay ));;\
},\
messages_list:messages:.* {\
my $this = ReadingsVal($name, $reading, '');;\
my @timestampArray = split("\n", $this);;\
my $messages_ref = decode_json(ReadingsVal($name, 'messages', ''));;\
my $length = 20;;\
\
my %seen_messages = map { $_ => 1 } @timestampArray;;\
\
foreach my $msg (@$messages_ref) {\
my $val = $msg->{content}{body};;\
$val = Encode::decode('utf-8', $val) unless Encode::is_utf8($val);;\
$val =~ s/\n/ /g;; #replace newlines with spaces\
\
my $sender = $msg->{sender};;\
my $ts = strftime("%Y-%m-%d %H:%M:%S", localtime($msg->{origin_server_ts} / 1000));;\
my $new_entry = "$ts: $sender: $val";;\
\
next if $seen_messages{$new_entry};;\
\
my $inserted = 0;;\
for (my $i = 0;; $i < @timestampArray;; $i++) {\
my ($existing_ts) = $timestampArray[$i] =~ /^([^:]+):/;;\
if ($ts lt $existing_ts) {\
splice(@timestampArray, $i, 0, $new_entry);;\
$inserted = 1;;\
last;;\
}\
}\
push(@timestampArray, encode('utf-8', $new_entry)) unless $inserted;;\
shift(@timestampArray) while @timestampArray > $length;;\
}\
\
return join("\n", @timestampArray);;\
},\
process_messages:messages:.* {\
my $val = ReadingsVal($name, 'messages_list', '');;\
my $this = ReadingsVal($name, $reading, '');;\
my $latest_ts = $this;;\
\
foreach my $line (split(/\n/, $val)) {\
if ($line =~ /^(\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}):\s*(.*)$/) {\
my ($ts, $msg) = ($1, $2);;\
\
if ($ts gt $this) {\
fhem("trigger $name msg: $line");;\
$latest_ts = $ts if ($ts gt $latest_ts);;\
}\
}\
}\
return $latest_ts;;\
}
attr MatrixBot verbose 3
attr MatrixBot widgetOverride longpollCmd:uzsuSelectRadio,startTimer,stopTimer
</syntaxhighlight>

Matrix

2025-05-24T08:44:39Z

Torxgewinde: /* Einrichtung */

== Allgemeines ==
'''Matrix''' ist ein offenes Kommunikationsprotokoll für dezentrale Echtzeitkommunikation. Es wird von zahlreichen Clients unterstützt, darunter '''Element''', '''Element-X''', '''SchildiChat Next''', '''FluffyChat''' und viele weitere.

Viele Open-Source-Projekte betreiben eigene Chaträume auf föderierten Matrix-Servern. Ein Beispiel dafür ist der '''Gadgetbridge-Chat''', einer der größeren und aktiveren Räume im Matrix-Ökosystem.

== Matrix und FHEM ==
Um mit '''FHEM''' Nachrichten über das Matrix-Protokoll zu senden und zu empfangen, stehen mehrere Möglichkeiten zur Verfügung. Eine einfache und pragmatische Lösung ist die Nutzung eines '''HTTPMOD-Devices'''. Damit lassen sich Nachrichten über die Matrix-API versenden oder empfangen.

=== Matrix per HTTPMOD Device ===
Folgendes Device kann Matrix Nachrichten senden und empfangen, es hat wenige Abhängigkeiten und sollte in den meisten FHEM Installationen unkompliziert eingerichtet sein. Es wird die Datenübertragung von FHEM zum Server mit HTTPS verschlüsselt, E2EE wird nicht verwendet.

==== Einrichtung ====
Es sind die Attribute MatrixServer und MatrixUser zu setzen:

<code>attr MatrixBot MatrixServer Dein-Servername</code>

<code>attr MatrixBot MatrixUser FHEM-Matrix-Username</code>

Das Passwort des Matrix-FHEM-Users setzt man mit dem Befehl:

<code>set MatrixBot storeKeyValue MatrixPassword yourPassword123</code>

Dann richtet man einen nicht E2E verschlüsselten Raum ein in dem der Matrix-FHEM-Account eingeladen ist. Von dem Raum benötigt man die MatrixRoomID, die man mit Element in den Raumdetails finden kann (Room Settings --> Advanced --> Internal room ID).

<code>attr MatrixBot MatrixRoomID !12345678901234:example.com</code>

==== Verwendung ====
Nachrichten senden geht mit:

<code>set MatrixBot sendText Bla Bla Bla</code>

Longpoll von Nachrichten starten und stoppen mit:

<code>set MatrixBot longpollCmd startTimer</code>

<code>set MatrixBot longpollCmd stopTimer</code>

==== Weiteres ====

===== Forumlink =====
https://forum.fhem.de/index.php?topic=120834.msg1339487#msg1339487

===== Demo-Device =====
Das folgende DOIF-Device lauscht auf eine eingehende Nachricht die als Inhalt "ping" oder "Ping" ist und antwortet mit "Pong!". Es dient als Beispiel und kann natürlich um weitere Befehle ergänzt/ersetzt werden um FHEM damit zu steuern:<syntaxhighlight lang="perl" line="1">
defmod MatrixPing.doif DOIF (["MatrixBot:msg: .*: @.*: [Pp]ing$"])\
(set MatrixBot sendText Pong!)
attr MatrixPing.doif alias Matrix Ping/Pong
attr MatrixPing.doif do always
attr MatrixPing.doif group Meldungen
attr MatrixPing.doif icon homeConnect
</syntaxhighlight>

==== Device-Definition ====
<syntaxhighlight lang="perl" line="1">
defmod MatrixBot HTTPMOD none 0
attr MatrixBot userattr MatrixRoomID MatrixServer MatrixUser
attr MatrixBot MatrixRoomID !12345678901234:nope.chat
attr MatrixBot MatrixServer nope.chat
attr MatrixBot MatrixUser DeinUsername
attr MatrixBot bodyDecode utf-8
attr MatrixBot bodyEncode utf-8
attr MatrixBot comment "\
Create a room for FHEM.\
\
The room must not use encryption, a room that has encryption\
enabled, cannot be converted to a non-encrypted room anymore \
\
The room-id can be found in Element-Web at:\
Room Settings --> Advanced --> Internal room ID\
\
To store the password in FHEM in obfuscated way:\
set MatrixBot storeKeyValue MatrixPassword yourPassword123\
\
###\
To send a text:\
set MatrixBot sendText Bla Bla Bla\
\
\
###\
To longpoll for messages once:\
# 1. send special filter to Matrix:\
set MatrixBot sendFilter\
\
# 2. start one longPoll (waits up to 60 seconds\
# or until data is available)\
get MatrixBot longpoll\
\
#alternatively, to keep on longPolling (this also sets filter):\
set MatrixBot longpollCmd startTimer\
#to stop the timers:\
set MatrixBot longpollCmd stopTimer\
\
#############################################################\
https://spec.matrix.org/v1.14/client-server-api/#syncing\
"
attr MatrixBot get02AlwaysNum 0
attr MatrixBot get02HeaderAuthorization Authorization: Bearer $sid
attr MatrixBot get02Name longpoll
attr MatrixBot get02Regex \"next_batch\":\s*\"(?<next_batch>[^\"]+)\"(?:.*?\"timeline\":\s*{\s*\"events\":\s*(?<messages>\[.*?\])\s*)?
attr MatrixBot get02TextArg 0
attr MatrixBot get02URL https://[$name:MatrixServer]/_matrix/client/v3/sync?timeout=60000&filter=[$name:filter_id]%%next_batch_param%%
attr MatrixBot icon message_info
attr MatrixBot parseFunction1 handleAuthErrors
attr MatrixBot reAuthAlways 0
attr MatrixBot reAuthRegex M_UNKNOWN_TOKEN
attr MatrixBot replacement01Mode expression
attr MatrixBot replacement01Regex \[([^:\s\[\"\']+):([^\]\s]+)\]
attr MatrixBot replacement01Value my $device = $name if ($1 eq "\$name") // $1;;\
ReadingsVal($device, $2, undef) or AttrVal($device, $2, "???");;
attr MatrixBot replacement02Mode expression
attr MatrixBot replacement02Regex %%uuid%%
attr MatrixBot replacement02Value join("-", unpack("A8 A4 A4 A4 A12", unpack("H*", join("", map { chr(int rand 256) } 0..15))))
attr MatrixBot replacement03Mode key
attr MatrixBot replacement03Regex %%MatrixPassword%%
attr MatrixBot replacement03Value MatrixPassword
attr MatrixBot replacement04Mode expression
attr MatrixBot replacement04Regex %%next_batch_param%%
attr MatrixBot replacement04Value #is there a reading 'next_batch'?\
my $val = ReadingsVal($name, 'next_batch', '???');;\
\
#return the GET parameter 'sync=value' for /sync Endpoint\
return "&since=$val" if ($val ne '???');;\
\
#return neither since-key nor value for it:\
return "";;
attr MatrixBot set01Data {\
"msgtype": "m.text",\
"body": "$val"\
}
attr MatrixBot set01HeaderAuthorization Authorization: Bearer $sid
attr MatrixBot set01HeaderContent-Type application/json
attr MatrixBot set01IExpr #cancel an active longpoll\
if ($hash->{BUSY}\
&& $hash->{HttpUtils}\
&& $hash->{HttpUtils}->{url} =~ m|^https://[^/]+/_matrix/client/v3/sync\?timeout=\d+&filter=| ) {\
Log(3, "$name: longpoll active, cutting it off now");;\
HttpUtils_Close($hash->{HttpUtils});;\
}\
\
#just return $val unteraltered\
$val
attr MatrixBot set01Method POST
attr MatrixBot set01Name sendText
attr MatrixBot set01ParseResponse 1
attr MatrixBot set01Regex {\"event_id\":\"(.*)\"}
attr MatrixBot set01TextArg 1
attr MatrixBot set01URL https://[$name:MatrixServer]/_matrix/client/v3/rooms/[$name:MatrixRoomID]/send/m.room.message?txnId=%%uuid%%
attr MatrixBot set02Data {\
"room": {\
"rooms": ["[$name:MatrixRoomID]"],\
"timeline": {\
"limit": 10,\
"types": ["m.room.message"]\
},\
"include_leave": false,\
"include_join": false,\
"include_account_data": false,\
"include_state": false,\
"state": {\
"types": []\
},\
"ephemeral": {\
"types": []\
},\
"account_data": {\
"types": []\
}\
},\
"event_fields": [\
"content.body",\
"sender",\
"origin_server_ts"\
],\
"event_format": "client",\
"presence": {\
"types": [],\
"not_types": ["*"]\
},\
"account_data": {\
"types": [],\
"not_types": ["*"]\
}\
}
attr MatrixBot set02HeaderAuthorization Authorization: Bearer $sid
attr MatrixBot set02HeaderContent-Type application/json
attr MatrixBot set02Method POST
attr MatrixBot set02Name sendFilter
attr MatrixBot set02NoArg 1
attr MatrixBot set02ParseResponse 1
attr MatrixBot set02Regex \"filter_id\":\s*\"(?<filter_id>\d+)\"
attr MatrixBot set02URL https://[$name:MatrixServer]/_matrix/client/v3/user/@[$name:MatrixUser]:[$name:MatrixServer]/filter
attr MatrixBot set03Local 1
attr MatrixBot set03Name longpollCmd
attr MatrixBot set03TextArg 1
attr MatrixBot showError 1
attr MatrixBot sid01Data {\
"type": "m.login.password",\
"identifier": {\
"type": "m.id.user",\
"user": "[$name:MatrixUser]"\
},\
"password": "%%MatrixPassword%%"\
}
attr MatrixBot sid01HeaderContent-Type application/json
attr MatrixBot sid01IdRegex "access_token"\s*:\s*"([^"]+)"
attr MatrixBot sid01URL https://[$name:MatrixServer]/_matrix/client/v3/login
attr MatrixBot timeout 65
attr MatrixBot userReadings longpollTimer:(next_batch|longpollCmd|LAST_ERROR|sendText):.* {\
my $longpollCmd = ReadingsVal($name, 'longpollCmd', '???');;\
my $delay = 1;;\
my $timeout = AttrVal($name, 'timeout', 61) + $delay + 5;;\
\
# stop our timers:\
if ($longpollCmd eq "stopTimer") {\
fhem("cancel ${name}_longpollTimer quiet");;\
fhem("cancel ${name}_longpollTimer2 quiet");;\
return "stopped";;\
}\
\
if ($longpollCmd ne "startTimer") {\
return "no timer set, longpollCmd is not set to 'startTimer'";;\
}\
\
#if startTimer cmd was given now, set filter as well:\
if (ReadingsAge($name, 'longpollCmd', 0) <= 1) {\
$delay = 5;; #delay to allow for sendFilter to be answered\
#Log(1, "🪲 $name: >>". InternalVal($name, 'httpbody', '???') ."<<");;\
fhem("sleep 0.1 quiet;; set $name sendFilter");;\
}\
\
#we handle an error reported by http-utils:\
if (ReadingsAge($name, 'LAST_ERROR', 0) <= 1) {\
my $last_error = ReadingsVal($name, 'LAST_ERROR', '???');;\
$delay = 10;; #delay to allow for error reasons to improve\
#Log(1, "🪲 $name: Dealing with error: >>$last_error<<");;\
}\
\
# for testing this: { $defs{MatrixBot}{sid} = 'bla' }\
if (!defined &HTTPMOD::handleAuthErrors) {\
*HTTPMOD::handleAuthErrors = sub {\
my ($hash, $header, $body, $request) = @_;;\
my $name = $hash->{NAME};;\
my $status;;\
\
if ($header =~ m{^HTTP/\d\.\d\s+(\d+)}m) {\
$status = $1;;\
}\
\
Log3($name, 4, "$name: HTTP status code is $status");;\
\
if ( $status == 401 || $status == 403 || $status == 500 ) {\
Log3($name, 3, "$name: auth-error or servererror ($status), calling doAuth()");;\
HTTPMOD::DoAuth($hash);;\
}\
};;\
}\
\
#set timers, one regular and one fallback:\
fhem("sleep $delay ${name}_longpollTimer quiet;; get $name longpoll");;\
fhem("sleep $timeout ${name}_longpollTimer2 quiet;; set $name longpollCmd startTimer");;\
\
return strftime("next longpoll at %H:%M:%S", localtime( time()+$delay ));;\
},\
messages_list:messages:.* {\
my $this = ReadingsVal($name, $reading, '');;\
my @timestampArray = split("\n", $this);;\
my $messages_ref = decode_json(ReadingsVal($name, 'messages', ''));;\
my $length = 20;;\
\
my %seen_messages = map { $_ => 1 } @timestampArray;;\
\
foreach my $msg (@$messages_ref) {\
my $val = $msg->{content}{body};;\
$val = Encode::decode('utf-8', $val) unless Encode::is_utf8($val);;\
$val =~ s/\n/ /g;; #replace newlines with spaces\
\
my $sender = $msg->{sender};;\
my $ts = strftime("%Y-%m-%d %H:%M:%S", localtime($msg->{origin_server_ts} / 1000));;\
my $new_entry = "$ts: $sender: $val";;\
\
next if $seen_messages{$new_entry};;\
\
my $inserted = 0;;\
for (my $i = 0;; $i < @timestampArray;; $i++) {\
my ($existing_ts) = $timestampArray[$i] =~ /^([^:]+):/;;\
if ($ts lt $existing_ts) {\
splice(@timestampArray, $i, 0, $new_entry);;\
$inserted = 1;;\
last;;\
}\
}\
push(@timestampArray, encode('utf-8', $new_entry)) unless $inserted;;\
shift(@timestampArray) while @timestampArray > $length;;\
}\
\
return join("\n", @timestampArray);;\
},\
process_messages:messages:.* {\
my $val = ReadingsVal($name, 'messages_list', '');;\
my $this = ReadingsVal($name, $reading, '');;\
my $latest_ts = $this;;\
\
foreach my $line (split(/\n/, $val)) {\
if ($line =~ /^(\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}):\s*(.*)$/) {\
my ($ts, $msg) = ($1, $2);;\
\
if ($ts gt $this) {\
fhem("trigger $name msg: $line");;\
$latest_ts = $ts if ($ts gt $latest_ts);;\
}\
}\
}\
return $latest_ts;;\
}
attr MatrixBot verbose 3
attr MatrixBot widgetOverride longpollCmd:uzsuSelectRadio,startTimer,stopTimer
</syntaxhighlight>

Matrix

2025-05-24T08:37:09Z

Torxgewinde: /* Weiteres */

== Allgemeines ==
'''Matrix''' ist ein offenes Kommunikationsprotokoll für dezentrale Echtzeitkommunikation. Es wird von zahlreichen Clients unterstützt, darunter '''Element''', '''Element-X''', '''SchildiChat Next''', '''FluffyChat''' und viele weitere.

Viele Open-Source-Projekte betreiben eigene Chaträume auf föderierten Matrix-Servern. Ein Beispiel dafür ist der '''Gadgetbridge-Chat''', einer der größeren und aktiveren Räume im Matrix-Ökosystem.

== Matrix und FHEM ==
Um mit '''FHEM''' Nachrichten über das Matrix-Protokoll zu senden und zu empfangen, stehen mehrere Möglichkeiten zur Verfügung. Eine einfache und pragmatische Lösung ist die Nutzung eines '''HTTPMOD-Devices'''. Damit lassen sich Nachrichten über die Matrix-API versenden oder empfangen.

=== Matrix per HTTPMOD Device ===
Folgendes Device kann Matrix Nachrichten senden und empfangen, es hat wenige Abhängigkeiten und sollte in den meisten FHEM Installationen unkompliziert eingerichtet sein. Es wird die Datenübertragung von FHEM zum Server mit HTTPS verschlüsselt, E2EE wird nicht verwendet.

==== Einrichtung ====
Es sind die Attribute MatrixServer und MatrixUser zu setzen:

<code>attr MatrixBot MatrixServer Dein-Servername</code>

<code>attr MatrixBot MatrixUser FHEM-Matrix-Username</code>

Dann richtet man einen nicht E2E verschlüsselten Raum ein in dem der Matrix-FHEM-Account eingeladen ist. Von dem Raum benötigt man die MatrixRoomID, die man mit Element in den Raumdetails finden kann (Room Settings --> Advanced --> Internal room ID).

Das Passwort des Matrix-FHEM-Users setzt man mit dem Befehl:

<code>set MatrixBot storeKeyValue MatrixPassword yourPassword123</code>

==== Verwendung ====
Nachrichten senden geht mit:

<code>set MatrixBot sendText Bla Bla Bla</code>

Longpoll von Nachrichten starten und stoppen mit:

<code>set MatrixBot longpollCmd startTimer</code>

<code>set MatrixBot longpollCmd stopTimer</code>

==== Weiteres ====

===== Forumlink =====
https://forum.fhem.de/index.php?topic=120834.msg1339487#msg1339487

===== Demo-Device =====
Das folgende DOIF-Device lauscht auf eine eingehende Nachricht die als Inhalt "ping" oder "Ping" ist und antwortet mit "Pong!". Es dient als Beispiel und kann natürlich um weitere Befehle ergänzt/ersetzt werden um FHEM damit zu steuern:<syntaxhighlight lang="perl" line="1">
defmod MatrixPing.doif DOIF (["MatrixBot:msg: .*: @.*: [Pp]ing$"])\
(set MatrixBot sendText Pong!)
attr MatrixPing.doif alias Matrix Ping/Pong
attr MatrixPing.doif do always
attr MatrixPing.doif group Meldungen
attr MatrixPing.doif icon homeConnect
</syntaxhighlight>

==== Device-Definition ====
<syntaxhighlight lang="perl" line="1">
defmod MatrixBot HTTPMOD none 0
attr MatrixBot userattr MatrixRoomID MatrixServer MatrixUser
attr MatrixBot MatrixRoomID !12345678901234:nope.chat
attr MatrixBot MatrixServer nope.chat
attr MatrixBot MatrixUser DeinUsername
attr MatrixBot bodyDecode utf-8
attr MatrixBot bodyEncode utf-8
attr MatrixBot comment "\
Create a room for FHEM.\
\
The room must not use encryption, a room that has encryption\
enabled, cannot be converted to a non-encrypted room anymore \
\
The room-id can be found in Element-Web at:\
Room Settings --> Advanced --> Internal room ID\
\
To store the password in FHEM in obfuscated way:\
set MatrixBot storeKeyValue MatrixPassword yourPassword123\
\
###\
To send a text:\
set MatrixBot sendText Bla Bla Bla\
\
\
###\
To longpoll for messages once:\
# 1. send special filter to Matrix:\
set MatrixBot sendFilter\
\
# 2. start one longPoll (waits up to 60 seconds\
# or until data is available)\
get MatrixBot longpoll\
\
#alternatively, to keep on longPolling (this also sets filter):\
set MatrixBot longpollCmd startTimer\
#to stop the timers:\
set MatrixBot longpollCmd stopTimer\
\
#############################################################\
https://spec.matrix.org/v1.14/client-server-api/#syncing\
"
attr MatrixBot get02AlwaysNum 0
attr MatrixBot get02HeaderAuthorization Authorization: Bearer $sid
attr MatrixBot get02Name longpoll
attr MatrixBot get02Regex \"next_batch\":\s*\"(?<next_batch>[^\"]+)\"(?:.*?\"timeline\":\s*{\s*\"events\":\s*(?<messages>\[.*?\])\s*)?
attr MatrixBot get02TextArg 0
attr MatrixBot get02URL https://[$name:MatrixServer]/_matrix/client/v3/sync?timeout=60000&filter=[$name:filter_id]%%next_batch_param%%
attr MatrixBot icon message_info
attr MatrixBot parseFunction1 handleAuthErrors
attr MatrixBot reAuthAlways 0
attr MatrixBot reAuthRegex M_UNKNOWN_TOKEN
attr MatrixBot replacement01Mode expression
attr MatrixBot replacement01Regex \[([^:\s\[\"\']+):([^\]\s]+)\]
attr MatrixBot replacement01Value my $device = $name if ($1 eq "\$name") // $1;;\
ReadingsVal($device, $2, undef) or AttrVal($device, $2, "???");;
attr MatrixBot replacement02Mode expression
attr MatrixBot replacement02Regex %%uuid%%
attr MatrixBot replacement02Value join("-", unpack("A8 A4 A4 A4 A12", unpack("H*", join("", map { chr(int rand 256) } 0..15))))
attr MatrixBot replacement03Mode key
attr MatrixBot replacement03Regex %%MatrixPassword%%
attr MatrixBot replacement03Value MatrixPassword
attr MatrixBot replacement04Mode expression
attr MatrixBot replacement04Regex %%next_batch_param%%
attr MatrixBot replacement04Value #is there a reading 'next_batch'?\
my $val = ReadingsVal($name, 'next_batch', '???');;\
\
#return the GET parameter 'sync=value' for /sync Endpoint\
return "&since=$val" if ($val ne '???');;\
\
#return neither since-key nor value for it:\
return "";;
attr MatrixBot set01Data {\
"msgtype": "m.text",\
"body": "$val"\
}
attr MatrixBot set01HeaderAuthorization Authorization: Bearer $sid
attr MatrixBot set01HeaderContent-Type application/json
attr MatrixBot set01IExpr #cancel an active longpoll\
if ($hash->{BUSY}\
&& $hash->{HttpUtils}\
&& $hash->{HttpUtils}->{url} =~ m|^https://[^/]+/_matrix/client/v3/sync\?timeout=\d+&filter=| ) {\
Log(3, "$name: longpoll active, cutting it off now");;\
HttpUtils_Close($hash->{HttpUtils});;\
}\
\
#just return $val unteraltered\
$val
attr MatrixBot set01Method POST
attr MatrixBot set01Name sendText
attr MatrixBot set01ParseResponse 1
attr MatrixBot set01Regex {\"event_id\":\"(.*)\"}
attr MatrixBot set01TextArg 1
attr MatrixBot set01URL https://[$name:MatrixServer]/_matrix/client/v3/rooms/[$name:MatrixRoomID]/send/m.room.message?txnId=%%uuid%%
attr MatrixBot set02Data {\
"room": {\
"rooms": ["[$name:MatrixRoomID]"],\
"timeline": {\
"limit": 10,\
"types": ["m.room.message"]\
},\
"include_leave": false,\
"include_join": false,\
"include_account_data": false,\
"include_state": false,\
"state": {\
"types": []\
},\
"ephemeral": {\
"types": []\
},\
"account_data": {\
"types": []\
}\
},\
"event_fields": [\
"content.body",\
"sender",\
"origin_server_ts"\
],\
"event_format": "client",\
"presence": {\
"types": [],\
"not_types": ["*"]\
},\
"account_data": {\
"types": [],\
"not_types": ["*"]\
}\
}
attr MatrixBot set02HeaderAuthorization Authorization: Bearer $sid
attr MatrixBot set02HeaderContent-Type application/json
attr MatrixBot set02Method POST
attr MatrixBot set02Name sendFilter
attr MatrixBot set02NoArg 1
attr MatrixBot set02ParseResponse 1
attr MatrixBot set02Regex \"filter_id\":\s*\"(?<filter_id>\d+)\"
attr MatrixBot set02URL https://[$name:MatrixServer]/_matrix/client/v3/user/@[$name:MatrixUser]:[$name:MatrixServer]/filter
attr MatrixBot set03Local 1
attr MatrixBot set03Name longpollCmd
attr MatrixBot set03TextArg 1
attr MatrixBot showError 1
attr MatrixBot sid01Data {\
"type": "m.login.password",\
"identifier": {\
"type": "m.id.user",\
"user": "[$name:MatrixUser]"\
},\
"password": "%%MatrixPassword%%"\
}
attr MatrixBot sid01HeaderContent-Type application/json
attr MatrixBot sid01IdRegex "access_token"\s*:\s*"([^"]+)"
attr MatrixBot sid01URL https://[$name:MatrixServer]/_matrix/client/v3/login
attr MatrixBot timeout 65
attr MatrixBot userReadings longpollTimer:(next_batch|longpollCmd|LAST_ERROR|sendText):.* {\
my $longpollCmd = ReadingsVal($name, 'longpollCmd', '???');;\
my $delay = 1;;\
my $timeout = AttrVal($name, 'timeout', 61) + $delay + 5;;\
\
# stop our timers:\
if ($longpollCmd eq "stopTimer") {\
fhem("cancel ${name}_longpollTimer quiet");;\
fhem("cancel ${name}_longpollTimer2 quiet");;\
return "stopped";;\
}\
\
if ($longpollCmd ne "startTimer") {\
return "no timer set, longpollCmd is not set to 'startTimer'";;\
}\
\
#if startTimer cmd was given now, set filter as well:\
if (ReadingsAge($name, 'longpollCmd', 0) <= 1) {\
$delay = 5;; #delay to allow for sendFilter to be answered\
#Log(1, "🪲 $name: >>". InternalVal($name, 'httpbody', '???') ."<<");;\
fhem("sleep 0.1 quiet;; set $name sendFilter");;\
}\
\
#we handle an error reported by http-utils:\
if (ReadingsAge($name, 'LAST_ERROR', 0) <= 1) {\
my $last_error = ReadingsVal($name, 'LAST_ERROR', '???');;\
$delay = 10;; #delay to allow for error reasons to improve\
#Log(1, "🪲 $name: Dealing with error: >>$last_error<<");;\
}\
\
# for testing this: { $defs{MatrixBot}{sid} = 'bla' }\
if (!defined &HTTPMOD::handleAuthErrors) {\
*HTTPMOD::handleAuthErrors = sub {\
my ($hash, $header, $body, $request) = @_;;\
my $name = $hash->{NAME};;\
my $status;;\
\
if ($header =~ m{^HTTP/\d\.\d\s+(\d+)}m) {\
$status = $1;;\
}\
\
Log3($name, 4, "$name: HTTP status code is $status");;\
\
if ( $status == 401 || $status == 403 || $status == 500 ) {\
Log3($name, 3, "$name: auth-error or servererror ($status), calling doAuth()");;\
HTTPMOD::DoAuth($hash);;\
}\
};;\
}\
\
#set timers, one regular and one fallback:\
fhem("sleep $delay ${name}_longpollTimer quiet;; get $name longpoll");;\
fhem("sleep $timeout ${name}_longpollTimer2 quiet;; set $name longpollCmd startTimer");;\
\
return strftime("next longpoll at %H:%M:%S", localtime( time()+$delay ));;\
},\
messages_list:messages:.* {\
my $this = ReadingsVal($name, $reading, '');;\
my @timestampArray = split("\n", $this);;\
my $messages_ref = decode_json(ReadingsVal($name, 'messages', ''));;\
my $length = 20;;\
\
my %seen_messages = map { $_ => 1 } @timestampArray;;\
\
foreach my $msg (@$messages_ref) {\
my $val = $msg->{content}{body};;\
$val = Encode::decode('utf-8', $val) unless Encode::is_utf8($val);;\
$val =~ s/\n/ /g;; #replace newlines with spaces\
\
my $sender = $msg->{sender};;\
my $ts = strftime("%Y-%m-%d %H:%M:%S", localtime($msg->{origin_server_ts} / 1000));;\
my $new_entry = "$ts: $sender: $val";;\
\
next if $seen_messages{$new_entry};;\
\
my $inserted = 0;;\
for (my $i = 0;; $i < @timestampArray;; $i++) {\
my ($existing_ts) = $timestampArray[$i] =~ /^([^:]+):/;;\
if ($ts lt $existing_ts) {\
splice(@timestampArray, $i, 0, $new_entry);;\
$inserted = 1;;\
last;;\
}\
}\
push(@timestampArray, encode('utf-8', $new_entry)) unless $inserted;;\
shift(@timestampArray) while @timestampArray > $length;;\
}\
\
return join("\n", @timestampArray);;\
},\
process_messages:messages:.* {\
my $val = ReadingsVal($name, 'messages_list', '');;\
my $this = ReadingsVal($name, $reading, '');;\
my $latest_ts = $this;;\
\
foreach my $line (split(/\n/, $val)) {\
if ($line =~ /^(\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}):\s*(.*)$/) {\
my ($ts, $msg) = ($1, $2);;\
\
if ($ts gt $this) {\
fhem("trigger $name msg: $line");;\
$latest_ts = $ts if ($ts gt $latest_ts);;\
}\
}\
}\
return $latest_ts;;\
}
attr MatrixBot verbose 3
attr MatrixBot widgetOverride longpollCmd:uzsuSelectRadio,startTimer,stopTimer
</syntaxhighlight>

Matrix

2025-05-24T08:31:54Z

Torxgewinde: Matrix mit FHEM nutzen, erste Version der Seite

== Allgemeines ==
'''Matrix''' ist ein offenes Kommunikationsprotokoll für dezentrale Echtzeitkommunikation. Es wird von zahlreichen Clients unterstützt, darunter '''Element''', '''Element-X''', '''SchildiChat Next''', '''FluffyChat''' und viele weitere.

Viele Open-Source-Projekte betreiben eigene Chaträume auf föderierten Matrix-Servern. Ein Beispiel dafür ist der '''Gadgetbridge-Chat''', einer der größeren und aktiveren Räume im Matrix-Ökosystem.

== Matrix und FHEM ==
Um mit '''FHEM''' Nachrichten über das Matrix-Protokoll zu senden und zu empfangen, stehen mehrere Möglichkeiten zur Verfügung. Eine einfache und pragmatische Lösung ist die Nutzung eines '''HTTPMOD-Devices'''. Damit lassen sich Nachrichten über die Matrix-API versenden oder empfangen.

=== Matrix per HTTPMOD Device ===
Folgendes Device kann Matrix Nachrichten senden und empfangen, es hat wenige Abhängigkeiten und sollte in den meisten FHEM Installationen unkompliziert eingerichtet sein. Es wird die Datenübertragung von FHEM zum Server mit HTTPS verschlüsselt, E2EE wird nicht verwendet.

==== Einrichtung ====
Es sind die Attribute MatrixServer und MatrixUser zu setzen:

<code>attr MatrixBot MatrixServer Dein-Servername</code>

<code>attr MatrixBot MatrixUser FHEM-Matrix-Username</code>

Dann richtet man einen nicht E2E verschlüsselten Raum ein in dem der Matrix-FHEM-Account eingeladen ist. Von dem Raum benötigt man die MatrixRoomID, die man mit Element in den Raumdetails finden kann (Room Settings --> Advanced --> Internal room ID).

Das Passwort des Matrix-FHEM-Users setzt man mit dem Befehl:

<code>set MatrixBot storeKeyValue MatrixPassword yourPassword123</code>

==== Verwendung ====
Nachrichten senden geht mit:

<code>set MatrixBot sendText Bla Bla Bla</code>

Longpoll von Nachrichten starten und stoppen mit:

<code>set MatrixBot longpollCmd startTimer</code>

<code>set MatrixBot longpollCmd stopTimer</code>

==== Weiteres ====
https://forum.fhem.de/index.php?topic=120834.msg1339487#msg1339487

==== Device-Definition ====
<syntaxhighlight lang="perl" line="1">
defmod MatrixBot HTTPMOD none 0
attr MatrixBot userattr MatrixRoomID MatrixServer MatrixUser
attr MatrixBot MatrixRoomID !12345678901234:nope.chat
attr MatrixBot MatrixServer nope.chat
attr MatrixBot MatrixUser DeinUsername
attr MatrixBot bodyDecode utf-8
attr MatrixBot bodyEncode utf-8
attr MatrixBot comment "\
Create a room for FHEM.\
\
The room must not use encryption, a room that has encryption\
enabled, cannot be converted to a non-encrypted room anymore \
\
The room-id can be found in Element-Web at:\
Room Settings --> Advanced --> Internal room ID\
\
To store the password in FHEM in obfuscated way:\
set MatrixBot storeKeyValue MatrixPassword yourPassword123\
\
###\
To send a text:\
set MatrixBot sendText Bla Bla Bla\
\
\
###\
To longpoll for messages once:\
# 1. send special filter to Matrix:\
set MatrixBot sendFilter\
\
# 2. start one longPoll (waits up to 60 seconds\
# or until data is available)\
get MatrixBot longpoll\
\
#alternatively, to keep on longPolling (this also sets filter):\
set MatrixBot longpollCmd startTimer\
#to stop the timers:\
set MatrixBot longpollCmd stopTimer\
\
#############################################################\
https://spec.matrix.org/v1.14/client-server-api/#syncing\
"
attr MatrixBot get02AlwaysNum 0
attr MatrixBot get02HeaderAuthorization Authorization: Bearer $sid
attr MatrixBot get02Name longpoll
attr MatrixBot get02Regex \"next_batch\":\s*\"(?<next_batch>[^\"]+)\"(?:.*?\"timeline\":\s*{\s*\"events\":\s*(?<messages>\[.*?\])\s*)?
attr MatrixBot get02TextArg 0
attr MatrixBot get02URL https://[$name:MatrixServer]/_matrix/client/v3/sync?timeout=60000&filter=[$name:filter_id]%%next_batch_param%%
attr MatrixBot icon message_info
attr MatrixBot parseFunction1 handleAuthErrors
attr MatrixBot reAuthAlways 0
attr MatrixBot reAuthRegex M_UNKNOWN_TOKEN
attr MatrixBot replacement01Mode expression
attr MatrixBot replacement01Regex \[([^:\s\[\"\']+):([^\]\s]+)\]
attr MatrixBot replacement01Value my $device = $name if ($1 eq "\$name") // $1;;\
ReadingsVal($device, $2, undef) or AttrVal($device, $2, "???");;
attr MatrixBot replacement02Mode expression
attr MatrixBot replacement02Regex %%uuid%%
attr MatrixBot replacement02Value join("-", unpack("A8 A4 A4 A4 A12", unpack("H*", join("", map { chr(int rand 256) } 0..15))))
attr MatrixBot replacement03Mode key
attr MatrixBot replacement03Regex %%MatrixPassword%%
attr MatrixBot replacement03Value MatrixPassword
attr MatrixBot replacement04Mode expression
attr MatrixBot replacement04Regex %%next_batch_param%%
attr MatrixBot replacement04Value #is there a reading 'next_batch'?\
my $val = ReadingsVal($name, 'next_batch', '???');;\
\
#return the GET parameter 'sync=value' for /sync Endpoint\
return "&since=$val" if ($val ne '???');;\
\
#return neither since-key nor value for it:\
return "";;
attr MatrixBot set01Data {\
"msgtype": "m.text",\
"body": "$val"\
}
attr MatrixBot set01HeaderAuthorization Authorization: Bearer $sid
attr MatrixBot set01HeaderContent-Type application/json
attr MatrixBot set01IExpr #cancel an active longpoll\
if ($hash->{BUSY}\
&& $hash->{HttpUtils}\
&& $hash->{HttpUtils}->{url} =~ m|^https://[^/]+/_matrix/client/v3/sync\?timeout=\d+&filter=| ) {\
Log(3, "$name: longpoll active, cutting it off now");;\
HttpUtils_Close($hash->{HttpUtils});;\
}\
\
#just return $val unteraltered\
$val
attr MatrixBot set01Method POST
attr MatrixBot set01Name sendText
attr MatrixBot set01ParseResponse 1
attr MatrixBot set01Regex {\"event_id\":\"(.*)\"}
attr MatrixBot set01TextArg 1
attr MatrixBot set01URL https://[$name:MatrixServer]/_matrix/client/v3/rooms/[$name:MatrixRoomID]/send/m.room.message?txnId=%%uuid%%
attr MatrixBot set02Data {\
"room": {\
"rooms": ["[$name:MatrixRoomID]"],\
"timeline": {\
"limit": 10,\
"types": ["m.room.message"]\
},\
"include_leave": false,\
"include_join": false,\
"include_account_data": false,\
"include_state": false,\
"state": {\
"types": []\
},\
"ephemeral": {\
"types": []\
},\
"account_data": {\
"types": []\
}\
},\
"event_fields": [\
"content.body",\
"sender",\
"origin_server_ts"\
],\
"event_format": "client",\
"presence": {\
"types": [],\
"not_types": ["*"]\
},\
"account_data": {\
"types": [],\
"not_types": ["*"]\
}\
}
attr MatrixBot set02HeaderAuthorization Authorization: Bearer $sid
attr MatrixBot set02HeaderContent-Type application/json
attr MatrixBot set02Method POST
attr MatrixBot set02Name sendFilter
attr MatrixBot set02NoArg 1
attr MatrixBot set02ParseResponse 1
attr MatrixBot set02Regex \"filter_id\":\s*\"(?<filter_id>\d+)\"
attr MatrixBot set02URL https://[$name:MatrixServer]/_matrix/client/v3/user/@[$name:MatrixUser]:[$name:MatrixServer]/filter
attr MatrixBot set03Local 1
attr MatrixBot set03Name longpollCmd
attr MatrixBot set03TextArg 1
attr MatrixBot showError 1
attr MatrixBot sid01Data {\
"type": "m.login.password",\
"identifier": {\
"type": "m.id.user",\
"user": "[$name:MatrixUser]"\
},\
"password": "%%MatrixPassword%%"\
}
attr MatrixBot sid01HeaderContent-Type application/json
attr MatrixBot sid01IdRegex "access_token"\s*:\s*"([^"]+)"
attr MatrixBot sid01URL https://[$name:MatrixServer]/_matrix/client/v3/login
attr MatrixBot timeout 65
attr MatrixBot userReadings longpollTimer:(next_batch|longpollCmd|LAST_ERROR|sendText):.* {\
my $longpollCmd = ReadingsVal($name, 'longpollCmd', '???');;\
my $delay = 1;;\
my $timeout = AttrVal($name, 'timeout', 61) + $delay + 5;;\
\
# stop our timers:\
if ($longpollCmd eq "stopTimer") {\
fhem("cancel ${name}_longpollTimer quiet");;\
fhem("cancel ${name}_longpollTimer2 quiet");;\
return "stopped";;\
}\
\
if ($longpollCmd ne "startTimer") {\
return "no timer set, longpollCmd is not set to 'startTimer'";;\
}\
\
#if startTimer cmd was given now, set filter as well:\
if (ReadingsAge($name, 'longpollCmd', 0) <= 1) {\
$delay = 5;; #delay to allow for sendFilter to be answered\
#Log(1, "🪲 $name: >>". InternalVal($name, 'httpbody', '???') ."<<");;\
fhem("sleep 0.1 quiet;; set $name sendFilter");;\
}\
\
#we handle an error reported by http-utils:\
if (ReadingsAge($name, 'LAST_ERROR', 0) <= 1) {\
my $last_error = ReadingsVal($name, 'LAST_ERROR', '???');;\
$delay = 10;; #delay to allow for error reasons to improve\
#Log(1, "🪲 $name: Dealing with error: >>$last_error<<");;\
}\
\
# for testing this: { $defs{MatrixBot}{sid} = 'bla' }\
if (!defined &HTTPMOD::handleAuthErrors) {\
*HTTPMOD::handleAuthErrors = sub {\
my ($hash, $header, $body, $request) = @_;;\
my $name = $hash->{NAME};;\
my $status;;\
\
if ($header =~ m{^HTTP/\d\.\d\s+(\d+)}m) {\
$status = $1;;\
}\
\
Log3($name, 4, "$name: HTTP status code is $status");;\
\
if ( $status == 401 || $status == 403 || $status == 500 ) {\
Log3($name, 3, "$name: auth-error or servererror ($status), calling doAuth()");;\
HTTPMOD::DoAuth($hash);;\
}\
};;\
}\
\
#set timers, one regular and one fallback:\
fhem("sleep $delay ${name}_longpollTimer quiet;; get $name longpoll");;\
fhem("sleep $timeout ${name}_longpollTimer2 quiet;; set $name longpollCmd startTimer");;\
\
return strftime("next longpoll at %H:%M:%S", localtime( time()+$delay ));;\
},\
messages_list:messages:.* {\
my $this = ReadingsVal($name, $reading, '');;\
my @timestampArray = split("\n", $this);;\
my $messages_ref = decode_json(ReadingsVal($name, 'messages', ''));;\
my $length = 20;;\
\
my %seen_messages = map { $_ => 1 } @timestampArray;;\
\
foreach my $msg (@$messages_ref) {\
my $val = $msg->{content}{body};;\
$val = Encode::decode('utf-8', $val) unless Encode::is_utf8($val);;\
$val =~ s/\n/ /g;; #replace newlines with spaces\
\
my $sender = $msg->{sender};;\
my $ts = strftime("%Y-%m-%d %H:%M:%S", localtime($msg->{origin_server_ts} / 1000));;\
my $new_entry = "$ts: $sender: $val";;\
\
next if $seen_messages{$new_entry};;\
\
my $inserted = 0;;\
for (my $i = 0;; $i < @timestampArray;; $i++) {\
my ($existing_ts) = $timestampArray[$i] =~ /^([^:]+):/;;\
if ($ts lt $existing_ts) {\
splice(@timestampArray, $i, 0, $new_entry);;\
$inserted = 1;;\
last;;\
}\
}\
push(@timestampArray, encode('utf-8', $new_entry)) unless $inserted;;\
shift(@timestampArray) while @timestampArray > $length;;\
}\
\
return join("\n", @timestampArray);;\
},\
process_messages:messages:.* {\
my $val = ReadingsVal($name, 'messages_list', '');;\
my $this = ReadingsVal($name, $reading, '');;\
my $latest_ts = $this;;\
\
foreach my $line (split(/\n/, $val)) {\
if ($line =~ /^(\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}):\s*(.*)$/) {\
my ($ts, $msg) = ($1, $2);;\
\
if ($ts gt $this) {\
fhem("trigger $name msg: $line");;\
$latest_ts = $ts if ($ts gt $latest_ts);;\
}\
}\
}\
return $latest_ts;;\
}
attr MatrixBot verbose 3
attr MatrixBot widgetOverride longpollCmd:uzsuSelectRadio,startTimer,stopTimer
</syntaxhighlight>

E-Mail senden

2025-05-24T08:10:25Z

Torxgewinde: /* Providerspezifisches */ Noch ein paar mehr Rückmeldungen eingefügt

Um aus FHEM heraus E-Mails senden zu können, gibt es unterschiedliche Methoden, abhängig von der verwendeten Plattform.

Lange Zeit war <code>sendemail</code> sehr beliebt. Da aber die Homepage des Projekts nicht mehr online ist und Probleme nur noch via erhöhtem Supportaufwand gelöst werden, sollte diese Option als veraltet betrachtet werden.

Eine Liste mit ressourcensparenden E-Mails Clients findet man bei dem OpenWRT Projekt: https://openwrt.org/docs/guide-user/services/email/smtp.client

MSGMail ist ein FHEM eigenes Modul zum Versenden, die Einrichtung ist allerdings nicht gänzlich einfach. Anfängern sei die cURL Methode empfohlen.

=== MSGMail (Linux, Windows) ===
FHEM bringt ein eigenes Device zum Senden von E-Mails mit, welches in Perl implementiert ist: [https://fhem.de/commandref.html#MSGMail MSGMail, https://fhem.de/commandref.html#MSGMail]

=== cURL (Linux, Windows) ===
[https://curl.se/ cURL] kann auf praktisch [https://curl.se/download.html jedem Betriebssystem] genutzt werden, [https://curl.se/windows/ selbst unter Windows]. Es kann direkt mit einem SMTP Server E-Mails versenden und stellt damit eine moderne, portable und sichere Option zum Versenden von E-Mails dar.

In FHEM richtet man sich ein Device ein und passt die Details (<code>$emailTo, $emailFrom, $emailServer</code>) an. Das Programm cURL muss installiert sein (z.B. mit <code>apt install curl</code>, oder durch Herunterladen und Installieren von der [https://curl.se cURL-Webseite]).<syntaxhighlight lang="perl" line="1">
defmod sendMail dummy
attr sendMail readingList message password
attr sendMail setList message:textField-long password
attr sendMail userReadings state:message:[\s\S]* {\
my $emailTo = 'du@example.com';;\
my $emailFrom = 'fhem@example.de';;\
my $emailServer = 'mail.your-server.de';;\
\
#erzeuge Datumsangabe konform zu RFC-5322:\
my @emailDateArray = split(' ', strftime("%w %d %m %Y %H:%M:%S %z", localtime));;\
$emailDateArray[0] = (qw[Sun Mon Tue Wed Thu Fri Sat])[$emailDateArray[0]] . ',';;\
$emailDateArray[2] = (qw[Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec])[$emailDateArray[2]-1];;\
my $emailDate = join(' ', @emailDateArray);;\
\
# Passwort aus getKeyValue abrufen\
my ($err, $emailPass) = getKeyValue("${name}_password");;\
if ($err || !defined $emailPass) {\
return "Error retrieving password: $err";;\
}\
\
my $message = ReadingsVal($name, 'message', '???');;\
my $subject = "$name: FHEM Nachricht";;\
\
# Betreff extrahieren und aus der Nachricht entfernen\
if ($message =~ s/(?:Subject|Betreff)=["'](.*?)["']//) {\
$subject = $1;;\
}\
\
# Empfänger extrahieren und aus der Nachricht entfernen\
if ($message =~ s/(?:To|An)=["'](.*?)["']//) {\
$emailTo = $1;;\
}\
\
#Dateianhänge bestimmen\
my @attachments;;\
while ($message =~ s/(?:Attachment|Anhang)=["'](.*?)["']//) {\
my $file = $1;;\
return ">>$file<< not found, not sending email" unless (-e $file);;\
push (@attachments, $file);;\
}\
\
#der curl Befehl wird hier aufgebaut:\
my $cmd = "curl -m 19 --noproxy '*' --no-progress-meter --ssl-reqd smtps://$emailServer:465 ";;\
$cmd .= "--user '$emailFrom:$emailPass' --mail-from '$emailFrom' --mail-rcpt '$emailTo' ";;\
$cmd .= "--write-out 'Email sent with status %{http_code}' ";;\
$cmd .= "-H 'Subject: $subject' ";;\
$cmd .= "-H 'From: $emailFrom' ";;\
$cmd .= "-H 'Date: $emailDate' ";;\
\
#multipart/alternative für Text und HTML EMail Body\
$cmd .= "-F '=(;;type=multipart/alternative' ";;\
\
# Leerzeichen und <br> bzw <br \> am Anfang entfernen:\
$message =~ s/^(\s|<br(?:[ \/]+)>)+//;;\
# Leerzeichen und <br> bzw <br \> am Ende entfernen:\
$message =~ s/(\s|<br(?:[ \/]+)>)+$//;;\
\
#Plaintext E-Mail Inhalt an cURL:\
$cmd .= "-F \"=$message;;type=text/plain;; charset=UTF-8\" ";;\
#ersetze \n bzw. \r\n durch ein HTML-tag <br />:\
$message =~ s/\r?\n/<br \/>/g;;\
\
#HTML E-Mail Inhalt an cURL:\
$cmd .= "-F '= <body>$message</body>;;type=text/html;; charset=UTF-8' ";;\
$cmd .= "-F '=)' ";;\
\
#jetzt alle Attachments (0..N) anhängen:\
foreach my $file (@attachments) {\
$cmd .= "-F '=@".$file.";;encoder=base64' ";;\
}\
\
#stderr auch mit in den output sammeln:\
$cmd .= " 2>&1";;\
\
#Blockierender Aufruf von cURL in dieser Funktion via BlockingCall:\
if (!defined &sendMailfunc1) {\
*sendMailfunc1 = sub ($) {\
my ($param) = @_;;\
my $result;;\
$result = qx/$param/;;\
$result = MIME::Base64::encode_base64($result);;\
$result =~ s/\n//g;;\
return $result;;\
}\
}\
\
#Rückgabe über diese Funktion,\
#anzeigen in dem reading dieses UserReadings:\
if (!defined &sendMailfunc2) {\
*sendMailfunc2 = sub ($) {\
my ($result) = @_;;\
my $hash = $defs{$name};;\
$result = MIME::Base64::decode_base64($result);;\
readingsSingleUpdate($hash, $reading, $result, 1);;\
}\
}\
\
#funktion falls BlockingCall abgebrochen wird:\
if (!defined &sendMailfunc3) {\
*sendMailfunc3 = sub ($) {\
my ($result) = @_;;\
my $hash = $defs{$name};;\
readingsSingleUpdate($hash, $reading, $result, 1);;\
}\
}\
\
BlockingCall("sendMailfunc1", $cmd, "sendMailfunc2", 20, "sendMailfunc3", "Error: timeout");;\
\
return "started cURL command...";;\
},\
state:password:.* {\
# Passwort speichern\
my $ret = setKeyValue("${name}_password", ReadingsVal($name, 'password', undef)) // "password stored";;\
\
#password wieder aus der Variablen rausnehmen, soll nicht sichtbar bleiben:\
#\
# Hinweis: das Password taucht beim Setzen hierüber im Event-Log auf!\
# Alternativ: { setKeyValue("sendMail_password", "geheimesPasswort") }\
readingsBulkUpdate($hash, "password", "****");;\
\
return "$ret";;\
}
</syntaxhighlight>Das Passwort setzt man mit:

* <code>set sendMail password geheimesPasswort</code>
* Alternativ, damit das Passwort nicht im Log auftaucht: <code>{ setKeyValue("sendMail_password", "geheimesPasswort") }</code>

E-Mails kann man dann Senden mit:

* <code>set sendMail message Mein Text</code> (es wird der Standardbetreff und Empfänger aus dem Snippet genutzt)
* <code>set sendMail message Betreff="Mein Betreff" Mein Text</code>(es wird der Empfänger aus dem Snippet genutzt)
* <code>set sendMail message Subject="Dies ist ein Test" Mein Text</code>
* <code>set sendMail message To="jemand@example.com" Mein Text</code>
* <code>set sendMail message An="jemand@example.com" Mein Text</code>
* <code>set sendMail message An="jemand@example.com" Betreff="Mein Betreff" Mein Text</code>
* <code>set sendMail message To="jemand@example.com" Subject="Mein Betreff" Mein Text</code>
* <code>set sendMail message Subject="✅ Dies ist ein Test" Meldung mit Emoji ⚽ geht auch</code>
* Eine Datei mit anhängen: <code>set sendMail message Subject="Dies ist ein Test" Anhang="www/images/fhemSVG/bag.svg" Mein Text</code>
* Zwei Dateien mit anhängen: <code>set sendMail message Subject="Dies ist ein Test" Anhang="./www/images/fhemSVG/bag.svg" Anhang="www/images/fhemSVG/batterie.svg" Mein Text</code>, für die anzuhängenden Dateien können relative und absolute Pfade verwendet werden. Beim Vorbereiten der E-Mail wird geprüft ob die Dateien existieren, da dies sonst eine typische Fehlerquelle ist. Es wird nichts versendet wenn eine Datei nicht gefunden werden kann.

==== Fehlersuche ====

===== Fehlende Protokolloption in cURL =====
Sollte cURL zwar installiert sein, aber keine E-Mails versenden, kann es sein, dass das Protokoll nicht einkompiliert wurde. Dies ist bei OpenWRT zum Beispiel der Fall.

So sollte es aussehen (hier ein Ubuntu), relevant ist für diese Nutzung das Protokoll smtp und smtps, das braucht man:<syntaxhighlight lang="bash">
curl -V
curl 8.5.0 (x86_64-pc-linux-gnu) libcurl/8.5.0 OpenSSL/3.0.13 zlib/1.3 brotli/1.1.0 zstd/1.5.5 libidn2/2.3.7 libpsl/0.21.2 (+libidn2/2.3.7) libssh/0.10.6/openssl/zlib nghttp2/1.59.0 librtmp/2.3 OpenLDAP/2.6.7
Release-Date: 2023-12-06, security patched: 8.5.0-2ubuntu10.6
Protocols: dict file ftp ftps gopher gophers http https imap imaps ldap ldaps mqtt pop3 pop3s rtmp rtsp scp sftp smb smbs smtp smtps telnet tftp
Features: alt-svc AsynchDNS brotli GSS-API HSTS HTTP2 HTTPS-proxy IDN IPv6 Kerberos Largefile libz NTLM PSL SPNEGO SSL threadsafe TLS-SRP UnixSockets zstd

</syntaxhighlight>
So sollte es nicht aussehen (hier ein OpenWRT):
<syntaxhighlight lang="bash">
curl: (1) Protocol "smtps" not supported

curl -V
curl 8.10.1 (arm-openwrt-linux-gnu) libcurl/8.10.1 mbedTLS/3.6.2 nghttp2/1.63.0
Release-Date: 2024-09-18
Protocols: file ftp ftps http https ipfs ipns mqtt
Features: alt-svc HSTS HTTP2 HTTPS-proxy IPv6 Largefile SSL threadsafe UnixSockets
</syntaxhighlight>
Hat man nur ein cURL ohne das Protokoll, so muss man sich das Paket leider anderweitig beschaffen (chroot, selbst kompilieren, statisch gelinkte Version, ...).

===== Falscher Port, login options =====
Einige Provider nehmen ihre TLS verschlüsselten E-Mails über einen anderen Port an, häufig Port 587 (siehe auch {{Link2Forum|Topic= 140814|Message=1340366|LinkText=diesen Forenbeitrag}}). Ggf. muss man auch mit einigen Loginoptionen experimentieren bis cURL wie gewünscht funktioniert (Stichwort: ''[https://curl.se/docs/manpage.html#--login-options --login-options]'').

===== Alte cURL Version =====
Sollte eine sehr alte cURL Version kleiner 7.67.0 genutzt werden, fehlt der Schalter <code>--no-progress-meter.</code> In solchen Fällen sollte man cURL aktualisieren. Falls dies nicht möglich ist, kann man den Schalter ersetzen durch <code>--silent --show-error</code>

===== Providerspezifisches=====
Eine lose Liste mit providerspezifischen Erfolgen und Misserfolgen:
{| class="wikitable sortable"
|+Liste mit Rückmeldungen zu E-Mail Anbietern
!Provider
!Funktioniert
!Details
|-
|Hetzner
|Ja
|<syntaxhighlight lang="perl">
my $emailServer = 'mail.your-server.de';
...
smtps://$emailServer:465
</syntaxhighlight>
|-
|Vodafone
|Ja
|Folgende Schalter sind hilfreich:<syntaxhighlight lang="perl">
--ssl-reqd --sasl-ir smtps://$emailserver:465
</syntaxhighlight>
|-
|Freenet
|Nein (nicht zuverlässig aufgrund des Spamfilters)
|Der Spamfilter lässt teilweise Nachrichten passieren, teilweise wird die Verbindung abgelehnt:
<code>''550 Spam message rejected''</code>

https://forum.fhem.de/index.php?topic=140814.msg1341872#msg1341872
|-
|T-Online
|Ja?
|<syntaxhighlight lang="perl">
my $emailServer = 'securesmtp.t-online.de';
...
smtps://$emailServer:465
</syntaxhighlight>https://forum.fhem.de/index.php?topic=140814.msg1340258#msg1340258
|-
|GMX
|Ja
|<syntaxhighlight lang="perl">
my $emailServer = 'mail.gmx.net';
...
smtps://$emailserver:465
</syntaxhighlight>https://forum.fhem.de/index.php?topic=140814.msg1341891#msg1341891
|-
|Google -> GMail
|Ja
|<syntaxhighlight lang="perl">
my $emailServer = 'smtp.gmail.com';
...
smtps://$emailserver:465
</syntaxhighlight>https://forum.fhem.de/index.php?topic=140814.msg1341891#msg1341891
|-
|Strato
|Ja
|https://forum.fhem.de/index.php?topic=140814.msg1342201#msg1342201
|}

Siehe auch dazu den {{Link2Forum|Message=1341182|Topic=140814|LinkText=Forumspost}}
===EXIM4 (Debian)===
Eine Anleitung zum Versenden von E-Mails mit Exim ist als PDF verfügbar: [[Medium:Anleitung Exim4 Debian GMX.pdf|PDF]]

===SSMTP (OpenWRT, embedded Distros)===

====Installation====
<syntaxhighlight lang="bash">
opkg update
opkg install ssmtp_2.64-4_mpc85xx.ipk
</syntaxhighlight>Damit <code>ssmtp</code> funktioniert müssen die Dateien <code>/etc/ssmtp/ssmtp.conf</code> und <code>/etc/ssmtp/revaliases</code> angepasst werden.

/etc/ssmtp/ssmtp.conf
<syntaxhighlight lang="text">
root=arnold@gmx.net
mailhub=mail.gmx.net:465
rewriteDomain=gmx.net
hostname=gmx.net
FromLineOverride=YES
UseTLS=YES
#UseSTARTTLS=YES
AuthUser=arnold@gmx.net
AuthPass=Passwort_von_arnold@gmx.net
</syntaxhighlight>

/etc/ssmtp/revaliases
<syntaxhighlight lang="text">
root:arnold@gmx.net:mail.gmx.net:465
</syntaxhighlight>

In der [[99_myUtils_anlegen|99_myUtils]] folgende Unterroutine einfügen:

<syntaxhighlight lang="perl">
sub OpenWRTMail
{
my $rcpt = shift;
my $subject = shift;
my $text = shift;
my $ret = "";
my $sender = "dockstar\@heye-tammo.de";
Log 1, "sendEmail RCP: $rcpt, Subject: $subject, Text: $text";
$ret .= qx(echo -e 'to:$rcpt\n from:$sender\nsubject:$subject\n$text\n' | ssmtp $rcpt);
$ret =~ s,[\r\n]*,,g; # remove CR from return-string
Log 1, "sendEmail returned: $ret";
}
</syntaxhighlight>

===PHP Mail Funktion (Synology DiskStation)===
Beim DSM 3.2 funktioniert der <code>php-mail</code>-Befehl, so dass man mittels folgendem Modul E-Mails versenden kann:
<syntaxhighlight lang="perl">
sub sendmail($$$) {
my($empf, $subj, $nachricht) = @_;
system("php -r 'mail(\"$empf\",\"$subj\",\"$nachricht\");'");
}
</syntaxhighlight>

===Sendemail (Veraltet, Debian-basierende Distros)===
Es handelt sich um ein Perl Programm, dass man aus den Paketquellen installieren kann.

Es gibt Probleme:

*mit der TLS bzw STARTTLS Verschlüsselung (https://github.com/fhem/fhem-docker/issues/254, https://www.mail-archive.com/debian-bugs-dist@lists.debian.org/msg1915977.html) ,
*Mit der Webseite des Projekts (https://web.archive.org/web/20190906140125/http://caspian.dotconf.net/menu/Software/SendEmail); diese ist nicht mehr verfügbar und nur eine archivierte Kopie kann eingesehen werden,

weswegen diese Lösung als technisch überholt gelten sollte. Will man trotzdem <code>sendemail</code> verwenden folgenden hier die Informationen dazu:

Auf dem Server muss <code>sendemail</code> installiert werden:<syntaxhighlight lang="bash" line="1">
sudo apt-get update
sudo apt-get install sendemail libio-socket-ssl-perl libnet-ssleay-perl perl
</syntaxhighlight>Man kann die korrekte Funktion im Terminal (ohne <code>{qx()}</code> ) oder auch in der FHEM Kommandozeile testen (Hinweis: manche Provider (z.B. gmail) lassen diesen Zugang erst nach Freischaltung zu!).

''Bei Gmail muss seit dem 30.6.2022 ein separates Passwort erzeugt werden, die alte Einstellung über "Zugriff durch weniger sichere Apps" funktioniert nicht mehr. Siehe Support Seite Google: <nowiki>https://support.google.com/accounts/answer/185833</nowiki>''

''Beispiel mit Gmail über Linux Terminalfenster:''
sendemail -f 'Der.Absender@gmail.com' -t 'Der.Empfaenger@gmail.com' -u 'subject' -m 'text' -a <nowiki>''</nowiki> -s 'smtp.gmail.com:587' -xu 'Der.Absender' -xp DASSUPERGEHEIMEPASSW0RT
In der [[99 myUtils anlegen|99_myUtils]] folgende Unterroutine einfügen:<syntaxhighlight lang="perl" line="1">
######## DebianMail Mail auf dem RPi versenden ############
# $provider für SMTP Server anpassen.
# Einmal in der FHEM Kommandozeile, user und password anpassen:
# {setKeyValue("myEmailKonto",'user@domain');;setKeyValue("myEmailPasswrd",'password')}
sub DebianMail
{
my $rcpt = shift;
my $subject = shift;
my $text = shift;
my $attach = shift;
my $ret = "";
my $error;
my $konto = getKeyValue("myEmailKonto");
my $passwrd = getKeyValue("myEmailPasswrd");
my $from = $konto; # or use different KeyValue if konto is not the from email address
my $provider = "smtp.1und1.de"; # smtp.domain.tld:port see provider documentation
#Log 1, "sendEmail RCP: $rcpt";
#Log 1, "sendEmail Subject: $subject";
#Log 1, "sendEmail Text: $text";
#Log 1, "sendEmail Anhang: $attach";
if (not defined($attach)){$attach=''}
$ret .= qx(sendemail -f '$from' -t '$rcpt' -u '$subject' -m '$text' -a $attach -s '$provider' -xu '$konto' -xp '$passwrd' -o tls=auto -o message-charset=utf-8);
$ret =~ s,[\r\n]*,,g; # remove CR from return-string
Log 1, "sendemail returned: $ret";
}
###############################################################################
</syntaxhighlight>

Die Zugangsdaten für den Email-Account müssen dabei FHEM-intern gespeichert werden. Dazu gibt man einmalig über die Kommandozeile folgendes ein (user@domain und password müssen auf den Email Account geändert werden):

:<code>{setKeyValue("myEmailKonto",'user@domain');;setKeyValue("myEmailPasswrd",'password')}</code>

Um die TLS Verschlüsselung (ehem. SSL) nicht zu nutzen, muss in der viertletzten Zeile tls=no verwendet und der Port des Mailproviders auf 25 eigetragen werden. Sollte anschließend keine Mail verschickt werden, siehe Probleme.

Falls der Body-Text in einem (Android-)Mailer auf dem Handy nicht gezeigt wird, kann der Parameter '''-o message-content-type=html''' helfen.

Die Funktion kann beispielsweise folgendermaßen aufgerufen werden:
<syntaxhighlight lang="perl">
{qx(sendemail -f 'Ab\@send.er' -t 'Emp\@faeng.er' -u 'subject' -m 'text' -a 'DateinameOderLeer' -s 'smtpFQDN:port' -xu 'MailUser' -xp 'PasswortOhneKlammeraffen')}
</syntaxhighlight>
Bei allen Feldern können generell doppelte " oder einfache ' Anführungszeichen verwendet werden. Innerhalb von "" müssen Sonderzeichen wie @ aber maskiert werden, da sie sonst als Steuerzeichen interpretiert werden:

:<code>"email\@email.domain" oder 'email@email.domain'</code>

Direkt in der FHEM Kommandozeile (ohne Anhang)

:<code>{DebianMail("email\@email.domain","Subject","Text")}</code>

Die ordnungsgemäße Ausführung wird mit 71 quittiert.

Beispiele mehrere Anhänge (Es ist wichtig Dateinamen mit Leerzeichen in separate Anführungszeichen zu setzen)
{DebianMail("email\@email.domain","Subject","Text","Anhang1 Anhang2 Anhang3")}
{DebianMail('email@email.domain','Subject','Text',"'with spaces Anhang1' 'with spaces Anhang2'")}
oder (mehr als einen Empfänger, diese können durch Leerzeichen, Semikolon oder Komma getrennt sein)
define Sonstiges at *01:00:00 {\
DebianMail('email@email.domain,email2@email.domain',"Subject","Text","'Anhang1' 'Anhang2' ...");;\
}

Die archivierte Doku zu <code>sendemail</code> befindet sich in der Änderungshistorie: https://wiki.fhem.de/w/index.php?title=E-Mail_senden&oldid=37524
[[Kategorie:E-Mail]]

E-Mail senden

2025-05-23T05:43:08Z

Torxgewinde: Hinweise von @bertl zu GMX und GMail

Um aus FHEM heraus E-Mails senden zu können, gibt es unterschiedliche Methoden, abhängig von der verwendeten Plattform.

Lange Zeit war <code>sendemail</code> sehr beliebt. Da aber die Homepage des Projekts nicht mehr online ist und Probleme nur noch via erhöhtem Supportaufwand gelöst werden, sollte diese Option als veraltet betrachtet werden.

Eine Liste mit ressourcensparenden E-Mails Clients findet man bei dem OpenWRT Projekt: https://openwrt.org/docs/guide-user/services/email/smtp.client

MSGMail ist ein FHEM eigenes Modul zum Versenden, die Einrichtung ist allerdings nicht gänzlich einfach. Anfängern sei die cURL Methode empfohlen.

=== MSGMail (Linux, Windows) ===
FHEM bringt ein eigenes Device zum Senden von E-Mails mit, welches in Perl implementiert ist: [https://fhem.de/commandref.html#MSGMail MSGMail, https://fhem.de/commandref.html#MSGMail]

=== cURL (Linux, Windows) ===
[https://curl.se/ cURL] kann auf praktisch [https://curl.se/download.html jedem Betriebssystem] genutzt werden, [https://curl.se/windows/ selbst unter Windows]. Es kann direkt mit einem SMTP Server E-Mails versenden und stellt damit eine moderne, portable und sichere Option zum Versenden von E-Mails dar.

In FHEM richtet man sich ein Device ein und passt die Details (<code>$emailTo, $emailFrom, $emailServer</code>) an. Das Programm cURL muss installiert sein (z.B. mit <code>apt install curl</code>, oder durch Herunterladen und Installieren von der [https://curl.se cURL-Webseite]).<syntaxhighlight lang="perl" line="1">
defmod sendMail dummy
attr sendMail readingList message password
attr sendMail setList message:textField-long password
attr sendMail userReadings state:message:[\s\S]* {\
my $emailTo = 'du@example.com';;\
my $emailFrom = 'fhem@example.de';;\
my $emailServer = 'mail.your-server.de';;\
\
#erzeuge Datumsangabe konform zu RFC-5322:\
my @emailDateArray = split(' ', strftime("%w %d %m %Y %H:%M:%S %z", localtime));;\
$emailDateArray[0] = (qw[Sun Mon Tue Wed Thu Fri Sat])[$emailDateArray[0]] . ',';;\
$emailDateArray[2] = (qw[Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec])[$emailDateArray[2]-1];;\
my $emailDate = join(' ', @emailDateArray);;\
\
# Passwort aus getKeyValue abrufen\
my ($err, $emailPass) = getKeyValue("${name}_password");;\
if ($err || !defined $emailPass) {\
return "Error retrieving password: $err";;\
}\
\
my $message = ReadingsVal($name, 'message', '???');;\
my $subject = "$name: FHEM Nachricht";;\
\
# Betreff extrahieren und aus der Nachricht entfernen\
if ($message =~ s/(?:Subject|Betreff)=["'](.*?)["']//) {\
$subject = $1;;\
}\
\
# Empfänger extrahieren und aus der Nachricht entfernen\
if ($message =~ s/(?:To|An)=["'](.*?)["']//) {\
$emailTo = $1;;\
}\
\
#Dateianhänge bestimmen\
my @attachments;;\
while ($message =~ s/(?:Attachment|Anhang)=["'](.*?)["']//) {\
my $file = $1;;\
return ">>$file<< not found, not sending email" unless (-e $file);;\
push (@attachments, $file);;\
}\
\
#der curl Befehl wird hier aufgebaut:\
my $cmd = "curl -m 19 --noproxy '*' --no-progress-meter --ssl-reqd smtps://$emailServer:465 ";;\
$cmd .= "--user '$emailFrom:$emailPass' --mail-from '$emailFrom' --mail-rcpt '$emailTo' ";;\
$cmd .= "--write-out 'Email sent with status %{http_code}' ";;\
$cmd .= "-H 'Subject: $subject' ";;\
$cmd .= "-H 'From: $emailFrom' ";;\
$cmd .= "-H 'Date: $emailDate' ";;\
\
#multipart/alternative für Text und HTML EMail Body\
$cmd .= "-F '=(;;type=multipart/alternative' ";;\
\
# Leerzeichen und <br> bzw <br \> am Anfang entfernen:\
$message =~ s/^(\s|<br(?:[ \/]+)>)+//;;\
# Leerzeichen und <br> bzw <br \> am Ende entfernen:\
$message =~ s/(\s|<br(?:[ \/]+)>)+$//;;\
\
#Plaintext E-Mail Inhalt an cURL:\
$cmd .= "-F \"=$message;;type=text/plain;; charset=UTF-8\" ";;\
#ersetze \n bzw. \r\n durch ein HTML-tag <br />:\
$message =~ s/\r?\n/<br \/>/g;;\
\
#HTML E-Mail Inhalt an cURL:\
$cmd .= "-F '= <body>$message</body>;;type=text/html;; charset=UTF-8' ";;\
$cmd .= "-F '=)' ";;\
\
#jetzt alle Attachments (0..N) anhängen:\
foreach my $file (@attachments) {\
$cmd .= "-F '=@".$file.";;encoder=base64' ";;\
}\
\
#stderr auch mit in den output sammeln:\
$cmd .= " 2>&1";;\
\
#Blockierender Aufruf von cURL in dieser Funktion via BlockingCall:\
if (!defined &sendMailfunc1) {\
*sendMailfunc1 = sub ($) {\
my ($param) = @_;;\
my $result;;\
$result = qx/$param/;;\
$result = MIME::Base64::encode_base64($result);;\
$result =~ s/\n//g;;\
return $result;;\
}\
}\
\
#Rückgabe über diese Funktion,\
#anzeigen in dem reading dieses UserReadings:\
if (!defined &sendMailfunc2) {\
*sendMailfunc2 = sub ($) {\
my ($result) = @_;;\
my $hash = $defs{$name};;\
$result = MIME::Base64::decode_base64($result);;\
readingsSingleUpdate($hash, $reading, $result, 1);;\
}\
}\
\
#funktion falls BlockingCall abgebrochen wird:\
if (!defined &sendMailfunc3) {\
*sendMailfunc3 = sub ($) {\
my ($result) = @_;;\
my $hash = $defs{$name};;\
readingsSingleUpdate($hash, $reading, $result, 1);;\
}\
}\
\
BlockingCall("sendMailfunc1", $cmd, "sendMailfunc2", 20, "sendMailfunc3", "Error: timeout");;\
\
return "started cURL command...";;\
},\
state:password:.* {\
# Passwort speichern\
my $ret = setKeyValue("${name}_password", ReadingsVal($name, 'password', undef)) // "password stored";;\
\
#password wieder aus der Variablen rausnehmen, soll nicht sichtbar bleiben:\
#\
# Hinweis: das Password taucht beim Setzen hierüber im Event-Log auf!\
# Alternativ: { setKeyValue("sendMail_password", "geheimesPasswort") }\
readingsBulkUpdate($hash, "password", "****");;\
\
return "$ret";;\
}
</syntaxhighlight>Das Passwort setzt man mit:

* <code>set sendMail password geheimesPasswort</code>
* Alternativ, damit das Passwort nicht im Log auftaucht: <code>{ setKeyValue("sendMail_password", "geheimesPasswort") }</code>

E-Mails kann man dann Senden mit:

* <code>set sendMail message Mein Text</code> (es wird der Standardbetreff und Empfänger aus dem Snippet genutzt)
* <code>set sendMail message Betreff="Mein Betreff" Mein Text</code>(es wird der Empfänger aus dem Snippet genutzt)
* <code>set sendMail message Subject="Dies ist ein Test" Mein Text</code>
* <code>set sendMail message To="jemand@example.com" Mein Text</code>
* <code>set sendMail message An="jemand@example.com" Mein Text</code>
* <code>set sendMail message An="jemand@example.com" Betreff="Mein Betreff" Mein Text</code>
* <code>set sendMail message To="jemand@example.com" Subject="Mein Betreff" Mein Text</code>
* <code>set sendMail message Subject="✅ Dies ist ein Test" Meldung mit Emoji ⚽ geht auch</code>
* Eine Datei mit anhängen: <code>set sendMail message Subject="Dies ist ein Test" Anhang="www/images/fhemSVG/bag.svg" Mein Text</code>
* Zwei Dateien mit anhängen: <code>set sendMail message Subject="Dies ist ein Test" Anhang="./www/images/fhemSVG/bag.svg" Anhang="www/images/fhemSVG/batterie.svg" Mein Text</code>, für die anzuhängenden Dateien können relative und absolute Pfade verwendet werden. Beim Vorbereiten der E-Mail wird geprüft ob die Dateien existieren, da dies sonst eine typische Fehlerquelle ist. Es wird nichts versendet wenn eine Datei nicht gefunden werden kann.

==== Fehlersuche ====

===== Fehlende Protokolloption in cURL =====
Sollte cURL zwar installiert sein, aber keine E-Mails versenden, kann es sein, dass das Protokoll nicht einkompiliert wurde. Dies ist bei OpenWRT zum Beispiel der Fall.

So sollte es aussehen (hier ein Ubuntu), relevant ist für diese Nutzung das Protokoll smtp und smtps, das braucht man:<syntaxhighlight lang="bash">
curl -V
curl 8.5.0 (x86_64-pc-linux-gnu) libcurl/8.5.0 OpenSSL/3.0.13 zlib/1.3 brotli/1.1.0 zstd/1.5.5 libidn2/2.3.7 libpsl/0.21.2 (+libidn2/2.3.7) libssh/0.10.6/openssl/zlib nghttp2/1.59.0 librtmp/2.3 OpenLDAP/2.6.7
Release-Date: 2023-12-06, security patched: 8.5.0-2ubuntu10.6
Protocols: dict file ftp ftps gopher gophers http https imap imaps ldap ldaps mqtt pop3 pop3s rtmp rtsp scp sftp smb smbs smtp smtps telnet tftp
Features: alt-svc AsynchDNS brotli GSS-API HSTS HTTP2 HTTPS-proxy IDN IPv6 Kerberos Largefile libz NTLM PSL SPNEGO SSL threadsafe TLS-SRP UnixSockets zstd

</syntaxhighlight>
So sollte es nicht aussehen (hier ein OpenWRT):
<syntaxhighlight lang="bash">
curl: (1) Protocol "smtps" not supported

curl -V
curl 8.10.1 (arm-openwrt-linux-gnu) libcurl/8.10.1 mbedTLS/3.6.2 nghttp2/1.63.0
Release-Date: 2024-09-18
Protocols: file ftp ftps http https ipfs ipns mqtt
Features: alt-svc HSTS HTTP2 HTTPS-proxy IPv6 Largefile SSL threadsafe UnixSockets
</syntaxhighlight>
Hat man nur ein cURL ohne das Protokoll, so muss man sich das Paket leider anderweitig beschaffen (chroot, selbst kompilieren, statisch gelinkte Version, ...).

===== Falscher Port, login options =====
Einige Provider nehmen ihre TLS verschlüsselten E-Mails über einen anderen Port an, häufig Port 587 (siehe auch {{Link2Forum|Topic= 140814|Message=1340366|LinkText=diesen Forenbeitrag}}). Ggf. muss man auch mit einigen Loginoptionen experimentieren bis cURL wie gewünscht funktioniert (Stichwort: ''[https://curl.se/docs/manpage.html#--login-options --login-options]'').

===== Alte cURL Version =====
Sollte eine sehr alte cURL Version kleiner 7.67.0 genutzt werden, fehlt der Schalter <code>--no-progress-meter.</code> In solchen Fällen sollte man cURL aktualisieren. Falls dies nicht möglich ist, kann man den Schalter ersetzen durch <code>--silent --show-error</code>

===== Providerspezifisches=====
Eine lose Liste mit providerspezifischen Erfolgen und Misserfolgen:
{| class="wikitable sortable"
|+Liste mit Rückmeldungen zu E-Mail Anbietern
!Provider
!Funktioniert
!Details
|-
|Hetzner
|Ja
|<code>my $emailServer = 'mail.your-server.de';</code><code>...</code><code>smtps://$emailServer:465</code>
|-
|Vodafone
|Ja
|Folgende Schalter sind hilfreich:
<code>--ssl-reqd --sasl-ir smtps://$emailserver:465</code>
|-
|Freenet
|Nein (nicht zuverlässig aufgrund des Spamfilters)
|Der Spamfilter lässt teilweise Nachrichten passieren, teilweise wird die Verbindung abgelehnt:
<code>''550 Spam message rejected''</code>

https://forum.fhem.de/index.php?topic=140814.msg1341872#msg1341872
|-
|T-Online
|Ja?
|<code>my $emailServer = 'securesmtp.t-online.de'</code><code>...</code><code>smtps://$emailServer:465</code>https://forum.fhem.de/index.php?topic=140814.msg1340258#msg1340258
|-
|GMX
|Ja
|<code>my $emailServer = 'mail.gmx.net';</code><code>...</code><code>smtps://$emailserver:465</code>
|-
|Google -> GMail
|Ja
|<code>my $emailServer = 'smtp.gmail.com';</code><code>...</code><code>smtps://$emailserver:465</code>
|}

Siehe auch dazu den {{Link2Forum|Message=1341182|Topic=140814|LinkText=Forumspost}}
===EXIM4 (Debian)===
Eine Anleitung zum Versenden von E-Mails mit Exim ist als PDF verfügbar: [[Medium:Anleitung Exim4 Debian GMX.pdf|PDF]]

===SSMTP (OpenWRT, embedded Distros)===

====Installation====
<syntaxhighlight lang="bash">
opkg update
opkg install ssmtp_2.64-4_mpc85xx.ipk
</syntaxhighlight>Damit <code>ssmtp</code> funktioniert müssen die Dateien <code>/etc/ssmtp/ssmtp.conf</code> und <code>/etc/ssmtp/revaliases</code> angepasst werden.

/etc/ssmtp/ssmtp.conf
<syntaxhighlight lang="text">
root=arnold@gmx.net
mailhub=mail.gmx.net:465
rewriteDomain=gmx.net
hostname=gmx.net
FromLineOverride=YES
UseTLS=YES
#UseSTARTTLS=YES
AuthUser=arnold@gmx.net
AuthPass=Passwort_von_arnold@gmx.net
</syntaxhighlight>

/etc/ssmtp/revaliases
<syntaxhighlight lang="text">
root:arnold@gmx.net:mail.gmx.net:465
</syntaxhighlight>

In der [[99_myUtils_anlegen|99_myUtils]] folgende Unterroutine einfügen:

<syntaxhighlight lang="perl">
sub OpenWRTMail
{
my $rcpt = shift;
my $subject = shift;
my $text = shift;
my $ret = "";
my $sender = "dockstar\@heye-tammo.de";
Log 1, "sendEmail RCP: $rcpt, Subject: $subject, Text: $text";
$ret .= qx(echo -e 'to:$rcpt\n from:$sender\nsubject:$subject\n$text\n' | ssmtp $rcpt);
$ret =~ s,[\r\n]*,,g; # remove CR from return-string
Log 1, "sendEmail returned: $ret";
}
</syntaxhighlight>

===PHP Mail Funktion (Synology DiskStation)===
Beim DSM 3.2 funktioniert der <code>php-mail</code>-Befehl, so dass man mittels folgendem Modul E-Mails versenden kann:
<syntaxhighlight lang="perl">
sub sendmail($$$) {
my($empf, $subj, $nachricht) = @_;
system("php -r 'mail(\"$empf\",\"$subj\",\"$nachricht\");'");
}
</syntaxhighlight>

===Sendemail (Veraltet, Debian-basierende Distros)===
Es handelt sich um ein Perl Programm, dass man aus den Paketquellen installieren kann.

Es gibt Probleme:

*mit der TLS bzw STARTTLS Verschlüsselung (https://github.com/fhem/fhem-docker/issues/254, https://www.mail-archive.com/debian-bugs-dist@lists.debian.org/msg1915977.html) ,
*Mit der Webseite des Projekts (https://web.archive.org/web/20190906140125/http://caspian.dotconf.net/menu/Software/SendEmail); diese ist nicht mehr verfügbar und nur eine archivierte Kopie kann eingesehen werden,

weswegen diese Lösung als technisch überholt gelten sollte. Will man trotzdem <code>sendemail</code> verwenden folgenden hier die Informationen dazu:

Auf dem Server muss <code>sendemail</code> installiert werden:<syntaxhighlight lang="bash" line="1">
sudo apt-get update
sudo apt-get install sendemail libio-socket-ssl-perl libnet-ssleay-perl perl
</syntaxhighlight>Man kann die korrekte Funktion im Terminal (ohne <code>{qx()}</code> ) oder auch in der FHEM Kommandozeile testen (Hinweis: manche Provider (z.B. gmail) lassen diesen Zugang erst nach Freischaltung zu!).

''Bei Gmail muss seit dem 30.6.2022 ein separates Passwort erzeugt werden, die alte Einstellung über "Zugriff durch weniger sichere Apps" funktioniert nicht mehr. Siehe Support Seite Google: <nowiki>https://support.google.com/accounts/answer/185833</nowiki>''

''Beispiel mit Gmail über Linux Terminalfenster:''
sendemail -f 'Der.Absender@gmail.com' -t 'Der.Empfaenger@gmail.com' -u 'subject' -m 'text' -a <nowiki>''</nowiki> -s 'smtp.gmail.com:587' -xu 'Der.Absender' -xp DASSUPERGEHEIMEPASSW0RT
In der [[99 myUtils anlegen|99_myUtils]] folgende Unterroutine einfügen:<syntaxhighlight lang="perl" line="1">
######## DebianMail Mail auf dem RPi versenden ############
# $provider für SMTP Server anpassen.
# Einmal in der FHEM Kommandozeile, user und password anpassen:
# {setKeyValue("myEmailKonto",'user@domain');;setKeyValue("myEmailPasswrd",'password')}
sub DebianMail
{
my $rcpt = shift;
my $subject = shift;
my $text = shift;
my $attach = shift;
my $ret = "";
my $error;
my $konto = getKeyValue("myEmailKonto");
my $passwrd = getKeyValue("myEmailPasswrd");
my $from = $konto; # or use different KeyValue if konto is not the from email address
my $provider = "smtp.1und1.de"; # smtp.domain.tld:port see provider documentation
#Log 1, "sendEmail RCP: $rcpt";
#Log 1, "sendEmail Subject: $subject";
#Log 1, "sendEmail Text: $text";
#Log 1, "sendEmail Anhang: $attach";
if (not defined($attach)){$attach=''}
$ret .= qx(sendemail -f '$from' -t '$rcpt' -u '$subject' -m '$text' -a $attach -s '$provider' -xu '$konto' -xp '$passwrd' -o tls=auto -o message-charset=utf-8);
$ret =~ s,[\r\n]*,,g; # remove CR from return-string
Log 1, "sendemail returned: $ret";
}
###############################################################################
</syntaxhighlight>

Die Zugangsdaten für den Email-Account müssen dabei FHEM-intern gespeichert werden. Dazu gibt man einmalig über die Kommandozeile folgendes ein (user@domain und password müssen auf den Email Account geändert werden):

:<code>{setKeyValue("myEmailKonto",'user@domain');;setKeyValue("myEmailPasswrd",'password')}</code>

Um die TLS Verschlüsselung (ehem. SSL) nicht zu nutzen, muss in der viertletzten Zeile tls=no verwendet und der Port des Mailproviders auf 25 eigetragen werden. Sollte anschließend keine Mail verschickt werden, siehe Probleme.

Falls der Body-Text in einem (Android-)Mailer auf dem Handy nicht gezeigt wird, kann der Parameter '''-o message-content-type=html''' helfen.

Die Funktion kann beispielsweise folgendermaßen aufgerufen werden:
<syntaxhighlight lang="perl">
{qx(sendemail -f 'Ab\@send.er' -t 'Emp\@faeng.er' -u 'subject' -m 'text' -a 'DateinameOderLeer' -s 'smtpFQDN:port' -xu 'MailUser' -xp 'PasswortOhneKlammeraffen')}
</syntaxhighlight>
Bei allen Feldern können generell doppelte " oder einfache ' Anführungszeichen verwendet werden. Innerhalb von "" müssen Sonderzeichen wie @ aber maskiert werden, da sie sonst als Steuerzeichen interpretiert werden:

:<code>"email\@email.domain" oder 'email@email.domain'</code>

Direkt in der FHEM Kommandozeile (ohne Anhang)

:<code>{DebianMail("email\@email.domain","Subject","Text")}</code>

Die ordnungsgemäße Ausführung wird mit 71 quittiert.

Beispiele mehrere Anhänge (Es ist wichtig Dateinamen mit Leerzeichen in separate Anführungszeichen zu setzen)
{DebianMail("email\@email.domain","Subject","Text","Anhang1 Anhang2 Anhang3")}
{DebianMail('email@email.domain','Subject','Text',"'with spaces Anhang1' 'with spaces Anhang2'")}
oder (mehr als einen Empfänger, diese können durch Leerzeichen, Semikolon oder Komma getrennt sein)
define Sonstiges at *01:00:00 {\
DebianMail('email@email.domain,email2@email.domain',"Subject","Text","'Anhang1' 'Anhang2' ...");;\
}

Die archivierte Doku zu <code>sendemail</code> befindet sich in der Änderungshistorie: https://wiki.fhem.de/w/index.php?title=E-Mail_senden&oldid=37524
[[Kategorie:E-Mail]]

E-Mail senden

2025-05-19T17:38:45Z

Torxgewinde: Liste mit E-Mail Anbietern angefangen

Um aus FHEM heraus E-Mails senden zu können, gibt es unterschiedliche Methoden, abhängig von der verwendeten Plattform.

Lange Zeit war <code>sendemail</code> sehr beliebt. Da aber die Homepage des Projekts nicht mehr online ist und Probleme nur noch via erhöhtem Supportaufwand gelöst werden, sollte diese Option als veraltet betrachtet werden.

Eine Liste mit ressourcensparenden E-Mails Clients findet man bei dem OpenWRT Projekt: https://openwrt.org/docs/guide-user/services/email/smtp.client

MSGMail ist ein FHEM eigenes Modul zum Versenden, die Einrichtung ist allerdings nicht gänzlich einfach. Anfängern sei die cURL Methode empfohlen.

=== MSGMail (Linux, Windows) ===
FHEM bringt ein eigenes Device zum Senden von E-Mails mit, welches in Perl implementiert ist: [https://fhem.de/commandref.html#MSGMail MSGMail, https://fhem.de/commandref.html#MSGMail]

=== cURL (Linux, Windows) ===
[https://curl.se/ cURL] kann auf praktisch [https://curl.se/download.html jedem Betriebssystem] genutzt werden, [https://curl.se/windows/ selbst unter Windows]. Es kann direkt mit einem SMTP Server E-Mails versenden und stellt damit eine moderne, portable und sichere Option zum Versenden von E-Mails dar.

In FHEM richtet man sich ein Device ein und passt die Details (<code>$emailTo, $emailFrom, $emailServer</code>) an. Das Programm cURL muss installiert sein (z.B. mit <code>apt install curl</code>, oder durch Herunterladen und Installieren von der [https://curl.se cURL-Webseite]).<syntaxhighlight lang="perl" line="1">
defmod sendMail dummy
attr sendMail readingList message password
attr sendMail setList message:textField-long password
attr sendMail userReadings state:message:[\s\S]* {\
my $emailTo = 'du@example.com';;\
my $emailFrom = 'fhem@example.de';;\
my $emailServer = 'mail.your-server.de';;\
\
#erzeuge Datumsangabe konform zu RFC-5322:\
my @emailDateArray = split(' ', strftime("%w %d %m %Y %H:%M:%S %z", localtime));;\
$emailDateArray[0] = (qw[Sun Mon Tue Wed Thu Fri Sat])[$emailDateArray[0]] . ',';;\
$emailDateArray[2] = (qw[Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec])[$emailDateArray[2]-1];;\
my $emailDate = join(' ', @emailDateArray);;\
\
# Passwort aus getKeyValue abrufen\
my ($err, $emailPass) = getKeyValue("${name}_password");;\
if ($err || !defined $emailPass) {\
return "Error retrieving password: $err";;\
}\
\
my $message = ReadingsVal($name, 'message', '???');;\
my $subject = "$name: FHEM Nachricht";;\
\
# Betreff extrahieren und aus der Nachricht entfernen\
if ($message =~ s/(?:Subject|Betreff)=["'](.*?)["']//) {\
$subject = $1;;\
}\
\
# Empfänger extrahieren und aus der Nachricht entfernen\
if ($message =~ s/(?:To|An)=["'](.*?)["']//) {\
$emailTo = $1;;\
}\
\
#Dateianhänge bestimmen\
my @attachments;;\
while ($message =~ s/(?:Attachment|Anhang)=["'](.*?)["']//) {\
my $file = $1;;\
return ">>$file<< not found, not sending email" unless (-e $file);;\
push (@attachments, $file);;\
}\
\
#der curl Befehl wird hier aufgebaut:\
my $cmd = "curl -m 19 --noproxy '*' --no-progress-meter --ssl-reqd smtps://$emailServer:465 ";;\
$cmd .= "--user '$emailFrom:$emailPass' --mail-from '$emailFrom' --mail-rcpt '$emailTo' ";;\
$cmd .= "--write-out 'Email sent with status %{http_code}' ";;\
$cmd .= "-H 'Subject: $subject' ";;\
$cmd .= "-H 'From: $emailFrom' ";;\
$cmd .= "-H 'Date: $emailDate' ";;\
\
#multipart/alternative für Text und HTML EMail Body\
$cmd .= "-F '=(;;type=multipart/alternative' ";;\
\
# Leerzeichen und <br> bzw <br \> am Anfang entfernen:\
$message =~ s/^(\s|<br(?:[ \/]+)>)+//;;\
# Leerzeichen und <br> bzw <br \> am Ende entfernen:\
$message =~ s/(\s|<br(?:[ \/]+)>)+$//;;\
\
#Plaintext E-Mail Inhalt an cURL:\
$cmd .= "-F \"=$message;;type=text/plain;; charset=UTF-8\" ";;\
#ersetze \n bzw. \r\n durch ein HTML-tag <br />:\
$message =~ s/\r?\n/<br \/>/g;;\
\
#HTML E-Mail Inhalt an cURL:\
$cmd .= "-F '= <body>$message</body>;;type=text/html;; charset=UTF-8' ";;\
$cmd .= "-F '=)' ";;\
\
#jetzt alle Attachments (0..N) anhängen:\
foreach my $file (@attachments) {\
$cmd .= "-F '=@".$file.";;encoder=base64' ";;\
}\
\
#stderr auch mit in den output sammeln:\
$cmd .= " 2>&1";;\
\
#Blockierender Aufruf von cURL in dieser Funktion via BlockingCall:\
if (!defined &sendMailfunc1) {\
*sendMailfunc1 = sub ($) {\
my ($param) = @_;;\
my $result;;\
$result = qx/$param/;;\
$result = MIME::Base64::encode_base64($result);;\
$result =~ s/\n//g;;\
return $result;;\
}\
}\
\
#Rückgabe über diese Funktion,\
#anzeigen in dem reading dieses UserReadings:\
if (!defined &sendMailfunc2) {\
*sendMailfunc2 = sub ($) {\
my ($result) = @_;;\
my $hash = $defs{$name};;\
$result = MIME::Base64::decode_base64($result);;\
readingsSingleUpdate($hash, $reading, $result, 1);;\
}\
}\
\
#funktion falls BlockingCall abgebrochen wird:\
if (!defined &sendMailfunc3) {\
*sendMailfunc3 = sub ($) {\
my ($result) = @_;;\
my $hash = $defs{$name};;\
readingsSingleUpdate($hash, $reading, $result, 1);;\
}\
}\
\
BlockingCall("sendMailfunc1", $cmd, "sendMailfunc2", 20, "sendMailfunc3", "Error: timeout");;\
\
return "started cURL command...";;\
},\
state:password:.* {\
# Passwort speichern\
my $ret = setKeyValue("${name}_password", ReadingsVal($name, 'password', undef)) // "password stored";;\
\
#password wieder aus der Variablen rausnehmen, soll nicht sichtbar bleiben:\
#\
# Hinweis: das Password taucht beim Setzen hierüber im Event-Log auf!\
# Alternativ: { setKeyValue("sendMail_password", "geheimesPasswort") }\
readingsBulkUpdate($hash, "password", "****");;\
\
return "$ret";;\
}
</syntaxhighlight>Das Passwort setzt man mit:

* <code>set sendMail password geheimesPasswort</code>
* Alternativ, damit das Passwort nicht im Log auftaucht: <code>{ setKeyValue("sendMail_password", "geheimesPasswort") }</code>

E-Mails kann man dann Senden mit:

* <code>set sendMail message Mein Text</code> (es wird der Standardbetreff und Empfänger aus dem Snippet genutzt)
* <code>set sendMail message Betreff="Mein Betreff" Mein Text</code>(es wird der Empfänger aus dem Snippet genutzt)
* <code>set sendMail message Subject="Dies ist ein Test" Mein Text</code>
* <code>set sendMail message To="jemand@example.com" Mein Text</code>
* <code>set sendMail message An="jemand@example.com" Mein Text</code>
* <code>set sendMail message An="jemand@example.com" Betreff="Mein Betreff" Mein Text</code>
* <code>set sendMail message To="jemand@example.com" Subject="Mein Betreff" Mein Text</code>
* <code>set sendMail message Subject="✅ Dies ist ein Test" Meldung mit Emoji ⚽ geht auch</code>
* Eine Datei mit anhängen: <code>set sendMail message Subject="Dies ist ein Test" Anhang="www/images/fhemSVG/bag.svg" Mein Text</code>
* Zwei Dateien mit anhängen: <code>set sendMail message Subject="Dies ist ein Test" Anhang="./www/images/fhemSVG/bag.svg" Anhang="www/images/fhemSVG/batterie.svg" Mein Text</code>, für die anzuhängenden Dateien können relative und absolute Pfade verwendet werden. Beim Vorbereiten der E-Mail wird geprüft ob die Dateien existieren, da dies sonst eine typische Fehlerquelle ist. Es wird nichts versendet wenn eine Datei nicht gefunden werden kann.

==== Fehlersuche ====

===== Fehlende Protokolloption in cURL =====
Sollte cURL zwar installiert sein, aber keine E-Mails versenden, kann es sein, dass das Protokoll nicht einkompiliert wurde. Dies ist bei OpenWRT zum Beispiel der Fall.

So sollte es aussehen (hier ein Ubuntu), relevant ist für diese Nutzung das Protokoll smtp und smtps, das braucht man:<syntaxhighlight lang="bash">
curl -V
curl 8.5.0 (x86_64-pc-linux-gnu) libcurl/8.5.0 OpenSSL/3.0.13 zlib/1.3 brotli/1.1.0 zstd/1.5.5 libidn2/2.3.7 libpsl/0.21.2 (+libidn2/2.3.7) libssh/0.10.6/openssl/zlib nghttp2/1.59.0 librtmp/2.3 OpenLDAP/2.6.7
Release-Date: 2023-12-06, security patched: 8.5.0-2ubuntu10.6
Protocols: dict file ftp ftps gopher gophers http https imap imaps ldap ldaps mqtt pop3 pop3s rtmp rtsp scp sftp smb smbs smtp smtps telnet tftp
Features: alt-svc AsynchDNS brotli GSS-API HSTS HTTP2 HTTPS-proxy IDN IPv6 Kerberos Largefile libz NTLM PSL SPNEGO SSL threadsafe TLS-SRP UnixSockets zstd

</syntaxhighlight>
So sollte es nicht aussehen (hier ein OpenWRT):
<syntaxhighlight lang="bash">
curl: (1) Protocol "smtps" not supported

curl -V
curl 8.10.1 (arm-openwrt-linux-gnu) libcurl/8.10.1 mbedTLS/3.6.2 nghttp2/1.63.0
Release-Date: 2024-09-18
Protocols: file ftp ftps http https ipfs ipns mqtt
Features: alt-svc HSTS HTTP2 HTTPS-proxy IPv6 Largefile SSL threadsafe UnixSockets
</syntaxhighlight>
Hat man nur ein cURL ohne das Protokoll, so muss man sich das Paket leider anderweitig beschaffen (chroot, selbst kompilieren, statisch gelinkte Version, ...).

===== Falscher Port, login options =====
Einige Provider nehmen ihre TLS verschlüsselten E-Mails über einen anderen Port an, häufig Port 587 (siehe auch {{Link2Forum|Topic= 140814|Message=1340366|LinkText=diesen Forenbeitrag}}). Ggf. muss man auch mit einigen Loginoptionen experimentieren bis cURL wie gewünscht funktioniert (Stichwort: ''[https://curl.se/docs/manpage.html#--login-options --login-options]'').

===== Alte cURL Version =====
Sollte eine sehr alte cURL Version kleiner 7.67.0 genutzt werden, fehlt der Schalter <code>--no-progress-meter.</code> In solchen Fällen sollte man cURL aktualisieren. Falls dies nicht möglich ist, kann man den Schalter ersetzen durch <code>--silent --show-error</code>

===== Providerspezifisches=====
Eine lose Liste mit providerspezifischen Erfolgen und Misserfolgen:
{| class="wikitable sortable"
|+Liste mit Rückmeldungen zu E-Mail Anbietern
!Provider
!Funktioniert
!Details
|-
|Hetzner
|Ja
|<code>my $emailServer = 'mail.your-server.de';</code><code>...</code><code>smtps://$emailServer:465</code>
|-
|Vodafone
|Ja
|Folgende Schalter sind hilfreich:
<code>--ssl-reqd --sasl-ir smtps://$emailserver:465</code>
|-
|Freenet
|Nein (nicht zuverlässig aufgrund des Spamfilters)
|Der Spamfilter lässt teilweise Nachrichten passieren, teilweise wird die Verbindung abgelehnt:
<code>''550 Spam message rejected''</code>
https://forum.fhem.de/index.php?topic=140814.msg1341872#msg1341872
|-
|T-Online
|Ja?
|<code>my $emailServer = 'securesmtp.t-online.de'</code><code>...</code><code>smtps://$emailServer:465</code>https://forum.fhem.de/index.php?topic=140814.msg1340258#msg1340258
|}

Siehe auch dazu den {{Link2Forum|Message=1341182|Topic=140814|LinkText=Forumspost}}
===EXIM4 (Debian)===
Eine Anleitung zum Versenden von E-Mails mit Exim ist als PDF verfügbar: [[Medium:Anleitung Exim4 Debian GMX.pdf|PDF]]

===SSMTP (OpenWRT, embedded Distros)===

====Installation====
<syntaxhighlight lang="bash">
opkg update
opkg install ssmtp_2.64-4_mpc85xx.ipk
</syntaxhighlight>Damit <code>ssmtp</code> funktioniert müssen die Dateien <code>/etc/ssmtp/ssmtp.conf</code> und <code>/etc/ssmtp/revaliases</code> angepasst werden.

/etc/ssmtp/ssmtp.conf
<syntaxhighlight lang="text">
root=arnold@gmx.net
mailhub=mail.gmx.net:465
rewriteDomain=gmx.net
hostname=gmx.net
FromLineOverride=YES
UseTLS=YES
#UseSTARTTLS=YES
AuthUser=arnold@gmx.net
AuthPass=Passwort_von_arnold@gmx.net
</syntaxhighlight>

/etc/ssmtp/revaliases
<syntaxhighlight lang="text">
root:arnold@gmx.net:mail.gmx.net:465
</syntaxhighlight>

In der [[99_myUtils_anlegen|99_myUtils]] folgende Unterroutine einfügen:

<syntaxhighlight lang="perl">
sub OpenWRTMail
{
my $rcpt = shift;
my $subject = shift;
my $text = shift;
my $ret = "";
my $sender = "dockstar\@heye-tammo.de";
Log 1, "sendEmail RCP: $rcpt, Subject: $subject, Text: $text";
$ret .= qx(echo -e 'to:$rcpt\n from:$sender\nsubject:$subject\n$text\n' | ssmtp $rcpt);
$ret =~ s,[\r\n]*,,g; # remove CR from return-string
Log 1, "sendEmail returned: $ret";
}
</syntaxhighlight>

===PHP Mail Funktion (Synology DiskStation)===
Beim DSM 3.2 funktioniert der <code>php-mail</code>-Befehl, so dass man mittels folgendem Modul E-Mails versenden kann:
<syntaxhighlight lang="perl">
sub sendmail($$$) {
my($empf, $subj, $nachricht) = @_;
system("php -r 'mail(\"$empf\",\"$subj\",\"$nachricht\");'");
}
</syntaxhighlight>

===Sendemail (Veraltet, Debian-basierende Distros)===
Es handelt sich um ein Perl Programm, dass man aus den Paketquellen installieren kann.

Es gibt Probleme:

*mit der TLS bzw STARTTLS Verschlüsselung (https://github.com/fhem/fhem-docker/issues/254, https://www.mail-archive.com/debian-bugs-dist@lists.debian.org/msg1915977.html) ,
*Mit der Webseite des Projekts (https://web.archive.org/web/20190906140125/http://caspian.dotconf.net/menu/Software/SendEmail); diese ist nicht mehr verfügbar und nur eine archivierte Kopie kann eingesehen werden,

weswegen diese Lösung als technisch überholt gelten sollte. Will man trotzdem <code>sendemail</code> verwenden folgenden hier die Informationen dazu:

Auf dem Server muss <code>sendemail</code> installiert werden:<syntaxhighlight lang="bash" line="1">
sudo apt-get update
sudo apt-get install sendemail libio-socket-ssl-perl libnet-ssleay-perl perl
</syntaxhighlight>Man kann die korrekte Funktion im Terminal (ohne <code>{qx()}</code> ) oder auch in der FHEM Kommandozeile testen (Hinweis: manche Provider (z.B. gmail) lassen diesen Zugang erst nach Freischaltung zu!).

''Bei Gmail muss seit dem 30.6.2022 ein separates Passwort erzeugt werden, die alte Einstellung über "Zugriff durch weniger sichere Apps" funktioniert nicht mehr. Siehe Support Seite Google: <nowiki>https://support.google.com/accounts/answer/185833</nowiki>''

''Beispiel mit Gmail über Linux Terminalfenster:''
sendemail -f 'Der.Absender@gmail.com' -t 'Der.Empfaenger@gmail.com' -u 'subject' -m 'text' -a <nowiki>''</nowiki> -s 'smtp.gmail.com:587' -xu 'Der.Absender' -xp DASSUPERGEHEIMEPASSW0RT
In der [[99 myUtils anlegen|99_myUtils]] folgende Unterroutine einfügen:<syntaxhighlight lang="perl" line="1">
######## DebianMail Mail auf dem RPi versenden ############
# $provider für SMTP Server anpassen.
# Einmal in der FHEM Kommandozeile, user und password anpassen:
# {setKeyValue("myEmailKonto",'user@domain');;setKeyValue("myEmailPasswrd",'password')}
sub DebianMail
{
my $rcpt = shift;
my $subject = shift;
my $text = shift;
my $attach = shift;
my $ret = "";
my $error;
my $konto = getKeyValue("myEmailKonto");
my $passwrd = getKeyValue("myEmailPasswrd");
my $from = $konto; # or use different KeyValue if konto is not the from email address
my $provider = "smtp.1und1.de"; # smtp.domain.tld:port see provider documentation
#Log 1, "sendEmail RCP: $rcpt";
#Log 1, "sendEmail Subject: $subject";
#Log 1, "sendEmail Text: $text";
#Log 1, "sendEmail Anhang: $attach";
if (not defined($attach)){$attach=''}
$ret .= qx(sendemail -f '$from' -t '$rcpt' -u '$subject' -m '$text' -a $attach -s '$provider' -xu '$konto' -xp '$passwrd' -o tls=auto -o message-charset=utf-8);
$ret =~ s,[\r\n]*,,g; # remove CR from return-string
Log 1, "sendemail returned: $ret";
}
###############################################################################
</syntaxhighlight>

Die Zugangsdaten für den Email-Account müssen dabei FHEM-intern gespeichert werden. Dazu gibt man einmalig über die Kommandozeile folgendes ein (user@domain und password müssen auf den Email Account geändert werden):

:<code>{setKeyValue("myEmailKonto",'user@domain');;setKeyValue("myEmailPasswrd",'password')}</code>

Um die TLS Verschlüsselung (ehem. SSL) nicht zu nutzen, muss in der viertletzten Zeile tls=no verwendet und der Port des Mailproviders auf 25 eigetragen werden. Sollte anschließend keine Mail verschickt werden, siehe Probleme.

Falls der Body-Text in einem (Android-)Mailer auf dem Handy nicht gezeigt wird, kann der Parameter '''-o message-content-type=html''' helfen.

Die Funktion kann beispielsweise folgendermaßen aufgerufen werden:
<syntaxhighlight lang="perl">
{qx(sendemail -f 'Ab\@send.er' -t 'Emp\@faeng.er' -u 'subject' -m 'text' -a 'DateinameOderLeer' -s 'smtpFQDN:port' -xu 'MailUser' -xp 'PasswortOhneKlammeraffen')}
</syntaxhighlight>
Bei allen Feldern können generell doppelte " oder einfache ' Anführungszeichen verwendet werden. Innerhalb von "" müssen Sonderzeichen wie @ aber maskiert werden, da sie sonst als Steuerzeichen interpretiert werden:

:<code>"email\@email.domain" oder 'email@email.domain'</code>

Direkt in der FHEM Kommandozeile (ohne Anhang)

:<code>{DebianMail("email\@email.domain","Subject","Text")}</code>

Die ordnungsgemäße Ausführung wird mit 71 quittiert.

Beispiele mehrere Anhänge (Es ist wichtig Dateinamen mit Leerzeichen in separate Anführungszeichen zu setzen)
{DebianMail("email\@email.domain","Subject","Text","Anhang1 Anhang2 Anhang3")}
{DebianMail('email@email.domain','Subject','Text',"'with spaces Anhang1' 'with spaces Anhang2'")}
oder (mehr als einen Empfänger, diese können durch Leerzeichen, Semikolon oder Komma getrennt sein)
define Sonstiges at *01:00:00 {\
DebianMail('email@email.domain,email2@email.domain',"Subject","Text","'Anhang1' 'Anhang2' ...");;\
}

Die archivierte Doku zu <code>sendemail</code> befindet sich in der Änderungshistorie: https://wiki.fhem.de/w/index.php?title=E-Mail_senden&oldid=37524
[[Kategorie:E-Mail]]

E-Mail senden

2025-05-09T17:22:14Z

Torxgewinde: /* cURL (Linux, Windows) */

Um aus FHEM heraus E-Mails senden zu können, gibt es unterschiedliche Methoden, abhängig von der verwendeten Plattform.

Lange Zeit war <code>sendemail</code> sehr beliebt. Da aber die Homepage des Projekts nicht mehr online ist und Probleme nur noch via erhöhtem Supportaufwand gelöst werden, sollte diese Option als veraltet betrachtet werden.

Eine Liste mit ressourcensparenden E-Mails Clients findet man bei dem OpenWRT Projekt: https://openwrt.org/docs/guide-user/services/email/smtp.client

MSGMail ist ein FHEM eigenes Modul zum Versenden, die Einrichtung ist allerdings nicht gänzlich einfach. Anfängern sei die cURL Methode empfohlen.

=== MSGMail (Linux, Windows) ===
FHEM bringt ein eigenes Device zum Senden von E-Mails mit, welches in Perl implementiert ist: [https://fhem.de/commandref.html#MSGMail MSGMail, https://fhem.de/commandref.html#MSGMail]

=== cURL (Linux, Windows) ===
[https://curl.se/ cURL] kann auf praktisch [https://curl.se/download.html jedem Betriebssystem] genutzt werden, [https://curl.se/windows/ selbst unter Windows]. Es kann direkt mit einem SMTP Server E-Mails versenden und stellt damit eine moderne, portable und sichere Option zum Versenden von E-Mails dar.

In FHEM richtet man sich ein Device ein und passt die Details (<code>$emailTo, $emailFrom, $emailServer</code>) an. Das Programm cURL muss installiert sein (z.B. mit <code>apt install curl</code>, oder durch Herunterladen und Installieren von der [https://curl.se cURL-Webseite]).<syntaxhighlight lang="perl" line="1">
defmod sendMail dummy
attr sendMail readingList message password
attr sendMail setList message:textField-long password
attr sendMail userReadings state:message:[\s\S]* {\
my $emailTo = 'du@example.com';;\
my $emailFrom = 'fhem@example.de';;\
my $emailServer = 'mail.your-server.de';;\
\
#erzeuge Datumsangabe konform zu RFC-5322:\
my @emailDateArray = split(' ', strftime("%w %d %m %Y %H:%M:%S %z", localtime));;\
$emailDateArray[0] = (qw[Sun Mon Tue Wed Thu Fri Sat])[$emailDateArray[0]] . ',';;\
$emailDateArray[2] = (qw[Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec])[$emailDateArray[2]-1];;\
my $emailDate = join(' ', @emailDateArray);;\
\
# Passwort aus getKeyValue abrufen\
my ($err, $emailPass) = getKeyValue("${name}_password");;\
if ($err || !defined $emailPass) {\
return "Error retrieving password: $err";;\
}\
\
my $message = ReadingsVal($name, 'message', '???');;\
my $subject = "$name: FHEM Nachricht";;\
\
# Betreff extrahieren und aus der Nachricht entfernen\
if ($message =~ s/(?:Subject|Betreff)=["'](.*?)["']//) {\
$subject = $1;;\
}\
\
# Empfänger extrahieren und aus der Nachricht entfernen\
if ($message =~ s/(?:To|An)=["'](.*?)["']//) {\
$emailTo = $1;;\
}\
\
#Dateianhänge bestimmen\
my @attachments;;\
while ($message =~ s/(?:Attachment|Anhang)=["'](.*?)["']//) {\
my $file = $1;;\
return ">>$file<< not found, not sending email" unless (-e $file);;\
push (@attachments, $file);;\
}\
\
#der curl Befehl wird hier aufgebaut:\
my $cmd = "curl -m 19 --noproxy '*' --no-progress-meter --ssl-reqd smtps://$emailServer:465 ";;\
$cmd .= "--user '$emailFrom:$emailPass' --mail-from '$emailFrom' --mail-rcpt '$emailTo' ";;\
$cmd .= "--write-out 'Email sent with status %{http_code}' ";;\
$cmd .= "-H 'Subject: $subject' ";;\
$cmd .= "-H 'From: $emailFrom' ";;\
$cmd .= "-H 'Date: $emailDate' ";;\
\
#multipart/alternative für Text und HTML EMail Body\
$cmd .= "-F '=(;;type=multipart/alternative' ";;\
\
# Leerzeichen und <br> bzw <br \> am Anfang entfernen:\
$message =~ s/^(\s|<br(?:[ \/]+)>)+//;;\
# Leerzeichen und <br> bzw <br \> am Ende entfernen:\
$message =~ s/(\s|<br(?:[ \/]+)>)+$//;;\
\
#Plaintext E-Mail Inhalt an cURL:\
$cmd .= "-F \"=$message;;type=text/plain;; charset=UTF-8\" ";;\
#ersetze \n bzw. \r\n durch ein HTML-tag <br />:\
$message =~ s/\r?\n/<br \/>/g;;\
\
#HTML E-Mail Inhalt an cURL:\
$cmd .= "-F '= <body>$message</body>;;type=text/html;; charset=UTF-8' ";;\
$cmd .= "-F '=)' ";;\
\
#jetzt alle Attachments (0..N) anhängen:\
foreach my $file (@attachments) {\
$cmd .= "-F '=@".$file.";;encoder=base64' ";;\
}\
\
#stderr auch mit in den output sammeln:\
$cmd .= " 2>&1";;\
\
#Blockierender Aufruf von cURL in dieser Funktion via BlockingCall:\
if (!defined &sendMailfunc1) {\
*sendMailfunc1 = sub ($) {\
my ($param) = @_;;\
my $result;;\
$result = qx/$param/;;\
$result = MIME::Base64::encode_base64($result);;\
$result =~ s/\n//g;;\
return $result;;\
}\
}\
\
#Rückgabe über diese Funktion,\
#anzeigen in dem reading dieses UserReadings:\
if (!defined &sendMailfunc2) {\
*sendMailfunc2 = sub ($) {\
my ($result) = @_;;\
my $hash = $defs{$name};;\
$result = MIME::Base64::decode_base64($result);;\
readingsSingleUpdate($hash, $reading, $result, 1);;\
}\
}\
\
#funktion falls BlockingCall abgebrochen wird:\
if (!defined &sendMailfunc3) {\
*sendMailfunc3 = sub ($) {\
my ($result) = @_;;\
my $hash = $defs{$name};;\
readingsSingleUpdate($hash, $reading, $result, 1);;\
}\
}\
\
BlockingCall("sendMailfunc1", $cmd, "sendMailfunc2", 20, "sendMailfunc3", "Error: timeout");;\
\
return "started cURL command...";;\
},\
state:password:.* {\
# Passwort speichern\
my $ret = setKeyValue("${name}_password", ReadingsVal($name, 'password', undef)) // "password stored";;\
\
#password wieder aus der Variablen rausnehmen, soll nicht sichtbar bleiben:\
#\
# Hinweis: das Password taucht beim Setzen hierüber im Event-Log auf!\
# Alternativ: { setKeyValue("sendMail_password", "geheimesPasswort") }\
readingsBulkUpdate($hash, "password", "****");;\
\
return "$ret";;\
}
</syntaxhighlight>Das Passwort setzt man mit:

* <code>set sendMail password geheimesPasswort</code>
* Alternativ, damit das Passwort nicht im Log auftaucht: <code>{ setKeyValue("sendMail_password", "geheimesPasswort") }</code>

E-Mails kann man dann Senden mit:

* <code>set sendMail message Mein Text</code> (es wird der Standardbetreff und Empfänger aus dem Snippet genutzt)
* <code>set sendMail message Betreff="Mein Betreff" Mein Text</code>(es wird der Empfänger aus dem Snippet genutzt)
* <code>set sendMail message Subject="Dies ist ein Test" Mein Text</code>
* <code>set sendMail message To="jemand@example.com" Mein Text</code>
* <code>set sendMail message An="jemand@example.com" Mein Text</code>
* <code>set sendMail message An="jemand@example.com" Betreff="Mein Betreff" Mein Text</code>
* <code>set sendMail message To="jemand@example.com" Subject="Mein Betreff" Mein Text</code>
* <code>set sendMail message Subject="✅ Dies ist ein Test" Meldung mit Emoji ⚽ geht auch</code>
* Eine Datei mit anhängen: <code>set sendMail message Subject="Dies ist ein Test" Anhang="www/images/fhemSVG/bag.svg" Mein Text</code>
* Zwei Dateien mit anhängen: <code>set sendMail message Subject="Dies ist ein Test" Anhang="./www/images/fhemSVG/bag.svg" Anhang="www/images/fhemSVG/batterie.svg" Mein Text</code>, für die anzuhängenden Dateien können relative und absolute Pfade verwendet werden. Beim Vorbereiten der E-Mail wird geprüft ob die Dateien existieren, da dies sonst eine typische Fehlerquelle ist. Es wird nichts versendet wenn eine Datei nicht gefunden werden kann.

==== Fehlersuche ====

===== Fehlende Protokolloption in cURL =====
Sollte cURL zwar installiert sein, aber keine E-Mails versenden, kann es sein, dass das Protokoll nicht einkompiliert wurde. Dies ist bei OpenWRT zum Beispiel der Fall.

So sollte es aussehen (hier ein Ubuntu), relevant ist für diese Nutzung das Protokoll smtp und smtps, das braucht man:<syntaxhighlight lang="bash">
curl -V
curl 8.5.0 (x86_64-pc-linux-gnu) libcurl/8.5.0 OpenSSL/3.0.13 zlib/1.3 brotli/1.1.0 zstd/1.5.5 libidn2/2.3.7 libpsl/0.21.2 (+libidn2/2.3.7) libssh/0.10.6/openssl/zlib nghttp2/1.59.0 librtmp/2.3 OpenLDAP/2.6.7
Release-Date: 2023-12-06, security patched: 8.5.0-2ubuntu10.6
Protocols: dict file ftp ftps gopher gophers http https imap imaps ldap ldaps mqtt pop3 pop3s rtmp rtsp scp sftp smb smbs smtp smtps telnet tftp
Features: alt-svc AsynchDNS brotli GSS-API HSTS HTTP2 HTTPS-proxy IDN IPv6 Kerberos Largefile libz NTLM PSL SPNEGO SSL threadsafe TLS-SRP UnixSockets zstd

</syntaxhighlight>
So sollte es nicht aussehen (hier ein OpenWRT):
<syntaxhighlight lang="bash">
curl: (1) Protocol "smtps" not supported

curl -V
curl 8.10.1 (arm-openwrt-linux-gnu) libcurl/8.10.1 mbedTLS/3.6.2 nghttp2/1.63.0
Release-Date: 2024-09-18
Protocols: file ftp ftps http https ipfs ipns mqtt
Features: alt-svc HSTS HTTP2 HTTPS-proxy IPv6 Largefile SSL threadsafe UnixSockets
</syntaxhighlight>
Hat man nur ein cURL ohne das Protokoll, so muss man sich das Paket leider anderweitig beschaffen (chroot, selbst kompilieren, statisch gelinkte Version, ...).

===== Falscher Port, login options =====
Einige Provider nehmen ihre TLS verschlüsselten E-Mails über einen anderen Port an, häufig Port 587 (siehe auch {{Link2Forum|Topic= 140814|Message=1340366|LinkText=diesen Forenbeitrag}}). Ggf. muss man auch mit einigen Loginoptionen experimentieren bis cURL wie gewünscht funktioniert (Stichwort: ''[https://curl.se/docs/manpage.html#--login-options --login-options]'').

===== Alte cURL Version =====
Sollte eine sehr alte cURL Version kleiner 7.67.0 genutzt werden, fehlt der Schalter <code>--no-progress-meter.</code> In solchen Fällen sollte man cURL aktualisieren. Falls dies nicht möglich ist, kann man den Schalter ersetzen durch <code>--silent --show-error</code>

Siehe auch dazu den {{Link2Forum|Message=1341182|Topic=140814|LinkText=Forumspost}}

=== EXIM4 (Debian) ===
Eine Anleitung zum Versenden von E-Mails mit Exim ist als PDF verfügbar: [[Medium:Anleitung Exim4 Debian GMX.pdf|PDF]]

=== SSMTP (OpenWRT, embedded Distros) ===

==== Installation ====
<syntaxhighlight lang="bash">
opkg update
opkg install ssmtp_2.64-4_mpc85xx.ipk
</syntaxhighlight>Damit <code>ssmtp</code> funktioniert müssen die Dateien <code>/etc/ssmtp/ssmtp.conf</code> und <code>/etc/ssmtp/revaliases</code> angepasst werden.

/etc/ssmtp/ssmtp.conf
<syntaxhighlight lang="text">
root=arnold@gmx.net
mailhub=mail.gmx.net:465
rewriteDomain=gmx.net
hostname=gmx.net
FromLineOverride=YES
UseTLS=YES
#UseSTARTTLS=YES
AuthUser=arnold@gmx.net
AuthPass=Passwort_von_arnold@gmx.net
</syntaxhighlight>

/etc/ssmtp/revaliases
<syntaxhighlight lang="text">
root:arnold@gmx.net:mail.gmx.net:465
</syntaxhighlight>

In der [[99_myUtils_anlegen|99_myUtils]] folgende Unterroutine einfügen:

<syntaxhighlight lang="perl">
sub OpenWRTMail
{
my $rcpt = shift;
my $subject = shift;
my $text = shift;
my $ret = "";
my $sender = "dockstar\@heye-tammo.de";
Log 1, "sendEmail RCP: $rcpt, Subject: $subject, Text: $text";
$ret .= qx(echo -e 'to:$rcpt\n from:$sender\nsubject:$subject\n$text\n' | ssmtp $rcpt);
$ret =~ s,[\r\n]*,,g; # remove CR from return-string
Log 1, "sendEmail returned: $ret";
}
</syntaxhighlight>

=== PHP Mail Funktion (Synology DiskStation) ===
Beim DSM 3.2 funktioniert der <code>php-mail</code>-Befehl, so dass man mittels folgendem Modul E-Mails versenden kann:
<syntaxhighlight lang="perl">
sub sendmail($$$) {
my($empf, $subj, $nachricht) = @_;
system("php -r 'mail(\"$empf\",\"$subj\",\"$nachricht\");'");
}
</syntaxhighlight>

=== Sendemail (Veraltet, Debian-basierende Distros) ===
Es handelt sich um ein Perl Programm, dass man aus den Paketquellen installieren kann.

Es gibt Probleme:

* mit der TLS bzw STARTTLS Verschlüsselung (https://github.com/fhem/fhem-docker/issues/254, https://www.mail-archive.com/debian-bugs-dist@lists.debian.org/msg1915977.html) ,
* Mit der Webseite des Projekts (https://web.archive.org/web/20190906140125/http://caspian.dotconf.net/menu/Software/SendEmail); diese ist nicht mehr verfügbar und nur eine archivierte Kopie kann eingesehen werden,

weswegen diese Lösung als technisch überholt gelten sollte. Will man trotzdem <code>sendemail</code> verwenden folgenden hier die Informationen dazu:

Auf dem Server muss <code>sendemail</code> installiert werden:<syntaxhighlight lang="bash" line="1">
sudo apt-get update
sudo apt-get install sendemail libio-socket-ssl-perl libnet-ssleay-perl perl
</syntaxhighlight>Man kann die korrekte Funktion im Terminal (ohne <code>{qx()}</code> ) oder auch in der FHEM Kommandozeile testen (Hinweis: manche Provider (z.B. gmail) lassen diesen Zugang erst nach Freischaltung zu!).

''Bei Gmail muss seit dem 30.6.2022 ein separates Passwort erzeugt werden, die alte Einstellung über "Zugriff durch weniger sichere Apps" funktioniert nicht mehr. Siehe Support Seite Google: <nowiki>https://support.google.com/accounts/answer/185833</nowiki>''

''Beispiel mit Gmail über Linux Terminalfenster:''
sendemail -f 'Der.Absender@gmail.com' -t 'Der.Empfaenger@gmail.com' -u 'subject' -m 'text' -a <nowiki>''</nowiki> -s 'smtp.gmail.com:587' -xu 'Der.Absender' -xp DASSUPERGEHEIMEPASSW0RT
In der [[99 myUtils anlegen|99_myUtils]] folgende Unterroutine einfügen:<syntaxhighlight lang="perl" line="1">
######## DebianMail Mail auf dem RPi versenden ############
# $provider für SMTP Server anpassen.
# Einmal in der FHEM Kommandozeile, user und password anpassen:
# {setKeyValue("myEmailKonto",'user@domain');;setKeyValue("myEmailPasswrd",'password')}
sub DebianMail
{
my $rcpt = shift;
my $subject = shift;
my $text = shift;
my $attach = shift;
my $ret = "";
my $error;
my $konto = getKeyValue("myEmailKonto");
my $passwrd = getKeyValue("myEmailPasswrd");
my $from = $konto; # or use different KeyValue if konto is not the from email address
my $provider = "smtp.1und1.de"; # smtp.domain.tld:port see provider documentation
#Log 1, "sendEmail RCP: $rcpt";
#Log 1, "sendEmail Subject: $subject";
#Log 1, "sendEmail Text: $text";
#Log 1, "sendEmail Anhang: $attach";
if (not defined($attach)){$attach=''}
$ret .= qx(sendemail -f '$from' -t '$rcpt' -u '$subject' -m '$text' -a $attach -s '$provider' -xu '$konto' -xp '$passwrd' -o tls=auto -o message-charset=utf-8);
$ret =~ s,[\r\n]*,,g; # remove CR from return-string
Log 1, "sendemail returned: $ret";
}
###############################################################################
</syntaxhighlight>

Die Zugangsdaten für den Email-Account müssen dabei FHEM-intern gespeichert werden. Dazu gibt man einmalig über die Kommandozeile folgendes ein (user@domain und password müssen auf den Email Account geändert werden):

: <code>{setKeyValue("myEmailKonto",'user@domain');;setKeyValue("myEmailPasswrd",'password')}</code>

Um die TLS Verschlüsselung (ehem. SSL) nicht zu nutzen, muss in der viertletzten Zeile tls=no verwendet und der Port des Mailproviders auf 25 eigetragen werden. Sollte anschließend keine Mail verschickt werden, siehe Probleme.

Falls der Body-Text in einem (Android-)Mailer auf dem Handy nicht gezeigt wird, kann der Parameter '''-o message-content-type=html''' helfen.

Die Funktion kann beispielsweise folgendermaßen aufgerufen werden:
<syntaxhighlight lang="perl">
{qx(sendemail -f 'Ab\@send.er' -t 'Emp\@faeng.er' -u 'subject' -m 'text' -a 'DateinameOderLeer' -s 'smtpFQDN:port' -xu 'MailUser' -xp 'PasswortOhneKlammeraffen')}
</syntaxhighlight>
Bei allen Feldern können generell doppelte " oder einfache ' Anführungszeichen verwendet werden. Innerhalb von "" müssen Sonderzeichen wie @ aber maskiert werden, da sie sonst als Steuerzeichen interpretiert werden:

: <code>"email\@email.domain" oder 'email@email.domain'</code>

Direkt in der FHEM Kommandozeile (ohne Anhang)

: <code>{DebianMail("email\@email.domain","Subject","Text")}</code>

Die ordnungsgemäße Ausführung wird mit 71 quittiert.

Beispiele mehrere Anhänge (Es ist wichtig Dateinamen mit Leerzeichen in separate Anführungszeichen zu setzen)
{DebianMail("email\@email.domain","Subject","Text","Anhang1 Anhang2 Anhang3")}
{DebianMail('email@email.domain','Subject','Text',"'with spaces Anhang1' 'with spaces Anhang2'")}
oder (mehr als einen Empfänger, diese können durch Leerzeichen, Semikolon oder Komma getrennt sein)
define Sonstiges at *01:00:00 {\
DebianMail('email@email.domain,email2@email.domain',"Subject","Text","'Anhang1' 'Anhang2' ...");;\
}

Die archivierte Doku zu <code>sendemail</code> befindet sich in der Änderungshistorie: https://wiki.fhem.de/w/index.php?title=E-Mail_senden&oldid=37524
[[Kategorie:E-Mail]]

E-Mail senden

2025-05-04T16:56:53Z

Torxgewinde: strftime machte Probleme, Hinweis von @moskito in https://forum.fhem.de/index.php?topic=140814.msg1340788#msg1340788

Um aus FHEM heraus E-Mails senden zu können, gibt es unterschiedliche Methoden, abhängig von der verwendeten Plattform.

Lange Zeit war <code>sendemail</code> sehr beliebt. Da aber die Homepage des Projekts nicht mehr online ist und Probleme nur noch via erhöhtem Supportaufwand gelöst werden, sollte diese Option als veraltet betrachtet werden.

Eine Liste mit ressourcensparenden E-Mails Clients findet man bei dem OpenWRT Projekt: https://openwrt.org/docs/guide-user/services/email/smtp.client

MSGMail ist ein FHEM eigenes Modul zum Versenden, die Einrichtung ist allerdings nicht gänzlich einfach. Anfängern sei die cURL Methode empfohlen.

=== MSGMail (Linux, Windows) ===
FHEM bringt ein eigenes Device zum Senden von E-Mails mit, welches in Perl implementiert ist: [https://fhem.de/commandref.html#MSGMail MSGMail, https://fhem.de/commandref.html#MSGMail]

=== cURL (Linux, Windows) ===
[https://curl.se/ cURL] kann auf praktisch [https://curl.se/download.html jedem Betriebssystem] genutzt werden, [https://curl.se/windows/ selbst unter Windows]. Es kann direkt mit einem SMTP Server E-Mails versenden und stellt damit eine moderne, portable und sichere Option zum Versenden von E-Mails dar.

In FHEM richtet man sich ein Device ein und passt die Details (<code>$emailTo, $emailFrom, $emailServer</code>) an. Das Programm cURL muss installiert sein (z.B. mit <code>apt install curl</code>, oder durch Herunterladen und Installieren von der [https://curl.se cURL-Webseite]).<syntaxhighlight lang="perl" line="1">
defmod sendMail dummy
attr sendMail readingList message password
attr sendMail setList message:textField-long password
attr sendMail userReadings state:message:[\s\S]* {\
my $emailTo = 'du@example.com';;\
my $emailFrom = 'fhem@example.de';;\
my $emailServer = 'mail.your-server.de';;\
\
setlocale(LC_TIME, "C");;\
my $emailDate = strftime("%a, %d %b %Y %H:%M:%S %z", localtime(time()));;\
\
# Passwort aus getKeyValue abrufen\
my ($err, $emailPass) = getKeyValue("${name}_password");;\
if ($err || !defined $emailPass) {\
return "Error retrieving password: $err";;\
}\
\
my $message = ReadingsVal($name, 'message', '???');;\
my $subject = "$name: FHEM Nachricht";;\
\
# Betreff extrahieren und aus der Nachricht entfernen\
if ($message =~ s/(?:Subject|Betreff)=["'](.*?)["']//) {\
$subject = $1;;\
}\
\
# Empfänger extrahieren und aus der Nachricht entfernen\
if ($message =~ s/(?:To|An)=["'](.*?)["']//) {\
$emailTo = $1;;\
}\
\
#Dateianhänge bestimmen\
my @attachments;;\
while ($message =~ s/(?:Attachment|Anhang)=["'](.*?)["']//) {\
my $file = $1;;\
return ">>$file<< not found, not sending email" unless (-e $file);;\
push (@attachments, $file);;\
}\
\
#der curl Befehl wird hier aufgebaut:\
my $cmd = "curl -m 19 --noproxy '*' --no-progress-meter --ssl-reqd smtps://$emailServer:465 ";;\
$cmd .= "--user '$emailFrom:$emailPass' --mail-from '$emailFrom' --mail-rcpt '$emailTo' ";;\
$cmd .= "--write-out 'Email sent with status %{http_code}\n' ";;\
$cmd .= "-H 'Subject: $subject' ";;\
$cmd .= "-H 'From: $emailFrom' ";;\
$cmd .= "-H 'Date: $emailDate' ";;\
$cmd .= "-H 'To: $emailTo' ";;\
\
#multipart/alternative für Text und HTML EMail Body\
$cmd .= "-F '=(;;type=multipart/alternative' ";;\
\
# Leerzeichen und <br> bzw <br \> am Anfang entfernen:\
$message =~ s/^(\s|<br(?:[ \/]+)>)+//;;\
# Leerzeichen und <br> bzw <br \> am Ende entfernen:\
$message =~ s/(\s|<br(?:[ \/]+)>)+$//;;\
\
#Plaintext E-Mail Inhalt an cURL:\
$cmd .= "-F \"=$message;;type=text/plain;; charset=UTF-8\" ";;\
#ersetze \n bzw. \r\n durch ein HTML-tag <br />:\
$message =~ s/\r?\n/<br \/>/g;;\
\
#HTML E-Mail Inhalt an cURL:\
$cmd .= "-F '= <body>$message</body>;;type=text/html;; charset=UTF-8' ";;\
$cmd .= "-F '=)' ";;\
\
#jetzt alle Attachments (0..N) anhängen:\
foreach my $file (@attachments) {\
$cmd .= "-F '=@".$file.";;encoder=base64' ";;\
}\
\
#stderr auch mit in den output sammeln:\
$cmd .= " 2>&1";;\
\
#Blockierender Aufruf von cURL in dieser Funktion via BlockingCall:\
if (!defined &sendMailfunc1) {\
*sendMailfunc1 = sub ($) {\
my ($param) = @_;;\
my $result;;\
$result = qx/$param/;;\
$result = MIME::Base64::encode_base64($result);;\
$result =~ s/\n//g;;\
return $result;;\
}\
}\
\
#Rückgabe über diese Funktion,\
#anzeigen in dem reading dieses UserReadings:\
if (!defined &sendMailfunc2) {\
*sendMailfunc2 = sub ($) {\
my ($result) = @_;;\
my $hash = $defs{$name};;\
$result = MIME::Base64::decode_base64($result);;\
readingsSingleUpdate($hash, $reading, $result, 1);;\
}\
}\
\
#funktion falls BlockingCall abgebrochen wird:\
if (!defined &sendMailfunc3) {\
*sendMailfunc3 = sub ($) {\
my ($result) = @_;;\
my $hash = $defs{$name};;\
readingsSingleUpdate($hash, $reading, $result, 1);;\
}\
}\
\
BlockingCall("sendMailfunc1", $cmd, "sendMailfunc2", 20, "sendMailfunc3", "Error: timeout");;\
\
return "started cURL command...";;\
},\
state:password:.* {\
# Passwort speichern\
my $ret = setKeyValue("${name}_password", ReadingsVal($name, 'password', undef)) // "password stored";;\
\
#password wieder aus der Variablen rausnehmen, soll nicht sichtbar bleiben:\
#\
# Hinweis: das Password taucht beim Setzen hierüber im Event-Log auf!\
# Alternativ: { setKeyValue("sendMail_password", "geheimesPasswort") }\
readingsBulkUpdate($hash, "password", "****");;\
\
return "$ret";;\
}
</syntaxhighlight>Das Passwort setzt man mit:

* <code>set sendMail password geheimesPasswort</code>
* Alternativ, damit das Passwort nicht im Log auftaucht: <code>{ setKeyValue("sendMail_password", "geheimesPasswort") }</code>

E-Mails kann man dann Senden mit:

* <code>set sendMail message Mein Text</code> (es wird der Standardbetreff und Empfänger aus dem Snippet genutzt)
* <code>set sendMail message Betreff="Mein Betreff" Mein Text</code>(es wird der Empfänger aus dem Snippet genutzt)
* <code>set sendMail message Subject="Dies ist ein Test" Mein Text</code>
* <code>set sendMail message To="jemand@example.com" Mein Text</code>
* <code>set sendMail message An="jemand@example.com" Mein Text</code>
* <code>set sendMail message An="jemand@example.com" Betreff="Mein Betreff" Mein Text</code>
* <code>set sendMail message To="jemand@example.com" Subject="Mein Betreff" Mein Text</code>
* <code>set sendMail message Subject="✅ Dies ist ein Test" Meldung mit Emoji ⚽ geht auch</code>
* Eine Datei mit anhängen: <code>set sendMail message Subject="Dies ist ein Test" Anhang="www/images/fhemSVG/bag.svg" Mein Text</code>
* Zwei Dateien mit anhängen: <code>set sendMail message Subject="Dies ist ein Test" Anhang="./www/images/fhemSVG/bag.svg" Anhang="www/images/fhemSVG/batterie.svg" Mein Text</code>, für die anzuhängenden Dateien können relative und absolute Pfade verwendet werden. Beim Vorbereiten der E-Mail wird geprüft ob die Dateien existieren, da dies sonst eine typische Fehlerquelle ist. Es wird nichts versendet wenn eine Datei nicht gefunden werden kann.

==== Fehlersuche ====

===== Fehlende Protokolloption in cURL =====
Sollte cURL zwar installiert sein, aber keine E-Mails versenden, kann es sein, dass das Protokoll nicht einkompiliert wurde. Dies ist bei OpenWRT zum Beispiel der Fall.

So sollte es aussehen (hier ein Ubuntu), relevant ist für diese Nutzung das Protokoll smtp und smtps, das braucht man:<syntaxhighlight lang="bash">
curl -V
curl 8.5.0 (x86_64-pc-linux-gnu) libcurl/8.5.0 OpenSSL/3.0.13 zlib/1.3 brotli/1.1.0 zstd/1.5.5 libidn2/2.3.7 libpsl/0.21.2 (+libidn2/2.3.7) libssh/0.10.6/openssl/zlib nghttp2/1.59.0 librtmp/2.3 OpenLDAP/2.6.7
Release-Date: 2023-12-06, security patched: 8.5.0-2ubuntu10.6
Protocols: dict file ftp ftps gopher gophers http https imap imaps ldap ldaps mqtt pop3 pop3s rtmp rtsp scp sftp smb smbs smtp smtps telnet tftp
Features: alt-svc AsynchDNS brotli GSS-API HSTS HTTP2 HTTPS-proxy IDN IPv6 Kerberos Largefile libz NTLM PSL SPNEGO SSL threadsafe TLS-SRP UnixSockets zstd

</syntaxhighlight>
So sollte es nicht aussehen (hier ein OpenWRT):
<syntaxhighlight lang="bash">
curl: (1) Protocol "smtps" not supported

curl -V
curl 8.10.1 (arm-openwrt-linux-gnu) libcurl/8.10.1 mbedTLS/3.6.2 nghttp2/1.63.0
Release-Date: 2024-09-18
Protocols: file ftp ftps http https ipfs ipns mqtt
Features: alt-svc HSTS HTTP2 HTTPS-proxy IPv6 Largefile SSL threadsafe UnixSockets
</syntaxhighlight>
Hat man nur ein cURL ohne das Protokoll, so muss man sich das Paket leider anderweitig beschaffen (chroot, selbst kompilieren, statisch gelinkte Version, ...).

===== Falscher Port, login options =====
Einige Provider nehmen ihre TLS verschlüsselten E-Mails über einen anderen Port an, häufig Port 587 (siehe auch {{Link2Forum|Topic= 140814|Message=1340366|LinkText=diesen Forenbeitrag}}). Ggf. muss man auch mit einigen Loginoptionen experimentieren bis cURL wie gewünscht funktioniert (Stichwort: ''[https://curl.se/docs/manpage.html#--login-options --login-options]'').

=== EXIM4 (Debian) ===
Eine Anleitung zum Versenden von E-Mails mit Exim ist als PDF verfügbar: [[Medium:Anleitung Exim4 Debian GMX.pdf|PDF]]

=== SSMTP (OpenWRT, embedded Distros) ===

==== Installation ====
<syntaxhighlight lang="bash">
opkg update
opkg install ssmtp_2.64-4_mpc85xx.ipk
</syntaxhighlight>Damit <code>ssmtp</code> funktioniert müssen die Dateien <code>/etc/ssmtp/ssmtp.conf</code> und <code>/etc/ssmtp/revaliases</code> angepasst werden.

/etc/ssmtp/ssmtp.conf
<syntaxhighlight lang="text">
root=arnold@gmx.net
mailhub=mail.gmx.net:465
rewriteDomain=gmx.net
hostname=gmx.net
FromLineOverride=YES
UseTLS=YES
#UseSTARTTLS=YES
AuthUser=arnold@gmx.net
AuthPass=Passwort_von_arnold@gmx.net
</syntaxhighlight>

/etc/ssmtp/revaliases
<syntaxhighlight lang="text">
root:arnold@gmx.net:mail.gmx.net:465
</syntaxhighlight>

In der [[99_myUtils_anlegen|99_myUtils]] folgende Unterroutine einfügen:

<syntaxhighlight lang="perl">
sub OpenWRTMail
{
my $rcpt = shift;
my $subject = shift;
my $text = shift;
my $ret = "";
my $sender = "dockstar\@heye-tammo.de";
Log 1, "sendEmail RCP: $rcpt, Subject: $subject, Text: $text";
$ret .= qx(echo -e 'to:$rcpt\n from:$sender\nsubject:$subject\n$text\n' | ssmtp $rcpt);
$ret =~ s,[\r\n]*,,g; # remove CR from return-string
Log 1, "sendEmail returned: $ret";
}
</syntaxhighlight>

=== PHP Mail Funktion (Synology DiskStation) ===
Beim DSM 3.2 funktioniert der <code>php-mail</code>-Befehl, so dass man mittels folgendem Modul E-Mails versenden kann:
<syntaxhighlight lang="perl">
sub sendmail($$$) {
my($empf, $subj, $nachricht) = @_;
system("php -r 'mail(\"$empf\",\"$subj\",\"$nachricht\");'");
}
</syntaxhighlight>

=== Sendemail (Veraltet, Debian-basierende Distros) ===
Es handelt sich um ein Perl Programm, dass man aus den Paketquellen installieren kann.

Es gibt Probleme:

* mit der TLS bzw STARTTLS Verschlüsselung (https://github.com/fhem/fhem-docker/issues/254, https://www.mail-archive.com/debian-bugs-dist@lists.debian.org/msg1915977.html) ,
* Mit der Webseite des Projekts (https://web.archive.org/web/20190906140125/http://caspian.dotconf.net/menu/Software/SendEmail); diese ist nicht mehr verfügbar und nur eine archivierte Kopie kann eingesehen werden,

weswegen diese Lösung als technisch überholt gelten sollte. Will man trotzdem <code>sendemail</code> verwenden folgenden hier die Informationen dazu:

Auf dem Server muss <code>sendemail</code> installiert werden:<syntaxhighlight lang="bash" line="1">
sudo apt-get update
sudo apt-get install sendemail libio-socket-ssl-perl libnet-ssleay-perl perl
</syntaxhighlight>Man kann die korrekte Funktion im Terminal (ohne <code>{qx()}</code> ) oder auch in der FHEM Kommandozeile testen (Hinweis: manche Provider (z.B. gmail) lassen diesen Zugang erst nach Freischaltung zu!).

''Bei Gmail muss seit dem 30.6.2022 ein separates Passwort erzeugt werden, die alte Einstellung über "Zugriff durch weniger sichere Apps" funktioniert nicht mehr. Siehe Support Seite Google: <nowiki>https://support.google.com/accounts/answer/185833</nowiki>''

''Beispiel mit Gmail über Linux Terminalfenster:''
sendemail -f 'Der.Absender@gmail.com' -t 'Der.Empfaenger@gmail.com' -u 'subject' -m 'text' -a <nowiki>''</nowiki> -s 'smtp.gmail.com:587' -xu 'Der.Absender' -xp DASSUPERGEHEIMEPASSW0RT
In der [[99 myUtils anlegen|99_myUtils]] folgende Unterroutine einfügen:<syntaxhighlight lang="perl" line="1">
######## DebianMail Mail auf dem RPi versenden ############
# $provider für SMTP Server anpassen.
# Einmal in der FHEM Kommandozeile, user und password anpassen:
# {setKeyValue("myEmailKonto",'user@domain');;setKeyValue("myEmailPasswrd",'password')}
sub DebianMail
{
my $rcpt = shift;
my $subject = shift;
my $text = shift;
my $attach = shift;
my $ret = "";
my $error;
my $konto = getKeyValue("myEmailKonto");
my $passwrd = getKeyValue("myEmailPasswrd");
my $from = $konto; # or use different KeyValue if konto is not the from email address
my $provider = "smtp.1und1.de"; # smtp.domain.tld:port see provider documentation
#Log 1, "sendEmail RCP: $rcpt";
#Log 1, "sendEmail Subject: $subject";
#Log 1, "sendEmail Text: $text";
#Log 1, "sendEmail Anhang: $attach";
if (not defined($attach)){$attach=''}
$ret .= qx(sendemail -f '$from' -t '$rcpt' -u '$subject' -m '$text' -a $attach -s '$provider' -xu '$konto' -xp '$passwrd' -o tls=auto -o message-charset=utf-8);
$ret =~ s,[\r\n]*,,g; # remove CR from return-string
Log 1, "sendemail returned: $ret";
}
###############################################################################
</syntaxhighlight>

Die Zugangsdaten für den Email-Account müssen dabei FHEM-intern gespeichert werden. Dazu gibt man einmalig über die Kommandozeile folgendes ein (user@domain und password müssen auf den Email Account geändert werden):

: <code>{setKeyValue("myEmailKonto",'user@domain');;setKeyValue("myEmailPasswrd",'password')}</code>

Um die TLS Verschlüsselung (ehem. SSL) nicht zu nutzen, muss in der viertletzten Zeile tls=no verwendet und der Port des Mailproviders auf 25 eigetragen werden. Sollte anschließend keine Mail verschickt werden, siehe Probleme.

Falls der Body-Text in einem (Android-)Mailer auf dem Handy nicht gezeigt wird, kann der Parameter '''-o message-content-type=html''' helfen.

Die Funktion kann beispielsweise folgendermaßen aufgerufen werden:
<syntaxhighlight lang="perl">
{qx(sendemail -f 'Ab\@send.er' -t 'Emp\@faeng.er' -u 'subject' -m 'text' -a 'DateinameOderLeer' -s 'smtpFQDN:port' -xu 'MailUser' -xp 'PasswortOhneKlammeraffen')}
</syntaxhighlight>
Bei allen Feldern können generell doppelte " oder einfache ' Anführungszeichen verwendet werden. Innerhalb von "" müssen Sonderzeichen wie @ aber maskiert werden, da sie sonst als Steuerzeichen interpretiert werden:

: <code>"email\@email.domain" oder 'email@email.domain'</code>

Direkt in der FHEM Kommandozeile (ohne Anhang)

: <code>{DebianMail("email\@email.domain","Subject","Text")}</code>

Die ordnungsgemäße Ausführung wird mit 71 quittiert.

Beispiele mehrere Anhänge (Es ist wichtig Dateinamen mit Leerzeichen in separate Anführungszeichen zu setzen)
{DebianMail("email\@email.domain","Subject","Text","Anhang1 Anhang2 Anhang3")}
{DebianMail('email@email.domain','Subject','Text',"'with spaces Anhang1' 'with spaces Anhang2'")}
oder (mehr als einen Empfänger, diese können durch Leerzeichen, Semikolon oder Komma getrennt sein)
define Sonstiges at *01:00:00 {\
DebianMail('email@email.domain,email2@email.domain',"Subject","Text","'Anhang1' 'Anhang2' ...");;\
}

Die archivierte Doku zu <code>sendemail</code> befindet sich in der Änderungshistorie: https://wiki.fhem.de/w/index.php?title=E-Mail_senden&oldid=37524
[[Kategorie:E-Mail]]

E-Mail senden

2025-04-29T19:46:42Z

Torxgewinde: Hinweise aus https://forum.fhem.de/index.php?topic=140814.msg1340366#msg1340366

Um aus FHEM heraus E-Mails senden zu können, gibt es unterschiedliche Methoden, abhängig von der verwendeten Plattform.

Lange Zeit war <code>sendemail</code> sehr beliebt. Da aber die Homepage des Projekts nicht mehr online ist und Probleme nur noch via erhöhtem Supportaufwand gelöst werden, sollte diese Option als veraltet betrachtet werden.

Eine Liste mit ressourcensparenden E-Mails Clients findet man bei dem OpenWRT Projekt: https://openwrt.org/docs/guide-user/services/email/smtp.client

MSGMail ist ein FHEM eigenes Modul zum Versenden, die Einrichtung ist allerdings nicht gänzlich einfach. Anfängern sei die cURL Methode empfohlen.

=== MSGMail (Linux, Windows) ===
FHEM bringt ein eigenes Device zum Senden von E-Mails mit, welches in Perl implementiert ist: [https://fhem.de/commandref.html#MSGMail MSGMail, https://fhem.de/commandref.html#MSGMail]

=== cURL (Linux, Windows) ===
[https://curl.se/ cURL] kann auf praktisch [https://curl.se/download.html jedem Betriebssystem] genutzt werden, [https://curl.se/windows/ selbst unter Windows]. Es kann direkt mit einem SMTP Server E-Mails versenden und stellt damit eine moderne, portable und sichere Option zum Versenden von E-Mails dar.

In FHEM richtet man sich ein Device ein und passt die Details (<code>$emailTo, $emailFrom, $emailServer</code>) an. Das Programm cURL muss installiert sein (z.B. mit <code>apt install curl</code>, oder durch Herunterladen und Installieren von der [https://curl.se cURL-Webseite]).<syntaxhighlight lang="perl" line="1">
defmod sendMail dummy
attr sendMail readingList message password
attr sendMail setList message:textField-long password
attr sendMail userReadings state:message:[\s\S]* {\
my $emailTo = 'du@example.com';;\
my $emailFrom = 'fhem@example.de';;\
my $emailServer = 'mail.your-server.de';;\
my $emailDate = strftime("%a, %d %b %Y %H:%M:%S %z", localtime(time()));;\
\
# Passwort aus getKeyValue abrufen\
my ($err, $emailPass) = getKeyValue("${name}_password");;\
if ($err || !defined $emailPass) {\
return "Error retrieving password: $err";;\
}\
\
my $message = ReadingsVal($name, 'message', '???');;\
my $subject = "$name: FHEM Nachricht";;\
\
# Betreff extrahieren und aus der Nachricht entfernen\
if ($message =~ s/(?:Subject|Betreff)=["'](.*?)["']//) {\
$subject = $1;;\
}\
\
# Empfänger extrahieren und aus der Nachricht entfernen\
if ($message =~ s/(?:To|An)=["'](.*?)["']//) {\
$emailTo = $1;;\
}\
\
#Dateianhänge bestimmen\
my @attachments;;\
while ($message =~ s/(?:Attachment|Anhang)=["'](.*?)["']//) {\
my $file = $1;;\
return ">>$file<< not found, not sending email" unless (-e $file);;\
push (@attachments, $file);;\
}\
\
#der curl Befehl wird hier aufgebaut:\
my $cmd = "curl -m 19 --noproxy '*' --no-progress-meter --ssl-reqd smtps://$emailServer:465 ";;\
$cmd .= "--user '$emailFrom:$emailPass' --mail-from '$emailFrom' --mail-rcpt '$emailTo' ";;\
$cmd .= "--write-out 'Email sent with status %{http_code}\n' ";;\
$cmd .= "-H 'Subject: $subject' ";;\
$cmd .= "-H 'From: $emailFrom' ";;\
$cmd .= "-H 'Date: $emailDate' ";;\
$cmd .= "-H 'To: $emailTo' ";;\
\
#multipart/alternative für Text und HTML EMail Body\
$cmd .= "-F '=(;;type=multipart/alternative' ";;\
\
# Leerzeichen und <br> bzw <br \> am Anfang entfernen:\
$message =~ s/^(\s|<br(?:[ \/]+)>)+//;;\
# Leerzeichen und <br> bzw <br \> am Ende entfernen:\
$message =~ s/(\s|<br(?:[ \/]+)>)+$//;;\
\
#Plaintext E-Mail Inhalt an cURL:\
$cmd .= "-F \"=$message;;type=text/plain;; charset=UTF-8\" ";;\
#ersetze \n bzw. \r\n durch ein HTML-tag <br />:\
$message =~ s/\r?\n/<br \/>/g;;\
\
#HTML E-Mail Inhalt an cURL:\
$cmd .= "-F '= <body>$message</body>;;type=text/html;; charset=UTF-8' ";;\
$cmd .= "-F '=)' ";;\
\
#jetzt alle Attachments (0..N) anhängen:\
foreach my $file (@attachments) {\
$cmd .= "-F '=@".$file.";;encoder=base64' ";;\
}\
\
#stderr auch mit in den output sammeln:\
$cmd .= " 2>&1";;\
\
#Blockierender Aufruf von cURL in dieser Funktion via BlockingCall:\
if (!defined &sendMailfunc1) {\
*sendMailfunc1 = sub ($) {\
my ($param) = @_;;\
my $result;;\
$result = qx/$param/;;\
$result = MIME::Base64::encode_base64($result);;\
$result =~ s/\n//g;;\
return $result;;\
}\
}\
\
#Rückgabe über diese Funktion,\
#anzeigen in dem reading dieses UserReadings:\
if (!defined &sendMailfunc2) {\
*sendMailfunc2 = sub ($) {\
my ($result) = @_;;\
my $hash = $defs{$name};;\
$result = MIME::Base64::decode_base64($result);;\
readingsSingleUpdate($hash, $reading, $result, 1);;\
}\
}\
\
#funktion falls BlockingCall abgebrochen wird:\
if (!defined &sendMailfunc3) {\
*sendMailfunc3 = sub ($) {\
my ($result) = @_;;\
my $hash = $defs{$name};;\
readingsSingleUpdate($hash, $reading, $result, 1);;\
}\
}\
\
BlockingCall("sendMailfunc1", $cmd, "sendMailfunc2", 20, "sendMailfunc3", "Error: timeout");;\
\
return "started cURL command...";;\
},\
state:password:.* {\
# Passwort speichern\
my $ret = setKeyValue("${name}_password", ReadingsVal($name, 'password', undef)) // "password stored";;\
\
#password wieder aus der Variablen rausnehmen, soll nicht sichtbar bleiben:\
#\
# Hinweis: das Password taucht beim Setzen hierüber im Event-Log auf!\
# Alternativ: { setKeyValue("sendMail_password", "geheimesPasswort") }\
readingsBulkUpdate($hash, "password", "****");;\
\
return "$ret";;\
}
</syntaxhighlight>Das Passwort setzt man mit:

* <code>set sendMail password geheimesPasswort</code>
* Alternativ, damit das Passwort nicht im Log auftaucht: <code>{ setKeyValue("sendMail_password", "geheimesPasswort") }</code>

E-Mails kann man dann Senden mit:

* <code>set sendMail message Mein Text</code> (es wird der Standardbetreff und Empfänger aus dem Snippet genutzt)
* <code>set sendMail message Betreff="Mein Betreff" Mein Text</code>(es wird der Empfänger aus dem Snippet genutzt)
* <code>set sendMail message Subject="Dies ist ein Test" Mein Text</code>
* <code>set sendMail message To="jemand@example.com" Mein Text</code>
* <code>set sendMail message An="jemand@example.com" Mein Text</code>
* <code>set sendMail message An="jemand@example.com" Betreff="Mein Betreff" Mein Text</code>
* <code>set sendMail message To="jemand@example.com" Subject="Mein Betreff" Mein Text</code>
* <code>set sendMail message Subject="✅ Dies ist ein Test" Meldung mit Emoji ⚽ geht auch</code>
* Eine Datei mit anhängen: <code>set sendMail message Subject="Dies ist ein Test" Anhang="www/images/fhemSVG/bag.svg" Mein Text</code>
* Zwei Dateien mit anhängen: <code>set sendMail message Subject="Dies ist ein Test" Anhang="./www/images/fhemSVG/bag.svg" Anhang="www/images/fhemSVG/batterie.svg" Mein Text</code>, für die anzuhängenden Dateien können relative und absolute Pfade verwendet werden. Beim Vorbereiten der E-Mail wird geprüft ob die Dateien existieren, da dies sonst eine typische Fehlerquelle ist. Es wird nichts versendet wenn eine Datei nicht gefunden werden kann.

==== Fehlersuche ====

===== Fehlende Protokolloption in cURL =====
Sollte cURL zwar installiert sein, aber keine E-Mails versenden, kann es sein, dass das Protokoll nicht einkompiliert wurde. Dies ist bei OpenWRT zum Beispiel der Fall.

So sollte es aussehen (hier ein Ubuntu), relevant ist für diese Nutzung das Protokoll smtp und smtps, das braucht man:<syntaxhighlight lang="bash">
curl -V
curl 8.5.0 (x86_64-pc-linux-gnu) libcurl/8.5.0 OpenSSL/3.0.13 zlib/1.3 brotli/1.1.0 zstd/1.5.5 libidn2/2.3.7 libpsl/0.21.2 (+libidn2/2.3.7) libssh/0.10.6/openssl/zlib nghttp2/1.59.0 librtmp/2.3 OpenLDAP/2.6.7
Release-Date: 2023-12-06, security patched: 8.5.0-2ubuntu10.6
Protocols: dict file ftp ftps gopher gophers http https imap imaps ldap ldaps mqtt pop3 pop3s rtmp rtsp scp sftp smb smbs smtp smtps telnet tftp
Features: alt-svc AsynchDNS brotli GSS-API HSTS HTTP2 HTTPS-proxy IDN IPv6 Kerberos Largefile libz NTLM PSL SPNEGO SSL threadsafe TLS-SRP UnixSockets zstd

</syntaxhighlight>So sollte es nicht aussehen (hier ein OpenWRT):<syntaxhighlight lang="bash">
curl: (1) Protocol "smtps" not supported

curl -V
curl 8.10.1 (arm-openwrt-linux-gnu) libcurl/8.10.1 mbedTLS/3.6.2 nghttp2/1.63.0
Release-Date: 2024-09-18
Protocols: file ftp ftps http https ipfs ipns mqtt
Features: alt-svc HSTS HTTP2 HTTPS-proxy IPv6 Largefile SSL threadsafe UnixSockets

</syntaxhighlight>Hat man nur ein cURL ohne das Protokoll, so muss man sich das Paket leider anderweitig beschaffen (chroot, selbst kompilieren, statisch gelinkte Version, ...).

===== Falscher Port, login options =====
Einige Provider nehmen ihre TLS verschlüsselten E-Mails über einen anderen Port an, häufig Port 587 (siehe auch https://forum.fhem.de/index.php?topic=140814.msg1340366#msg1340366). Ggf. muss man auch mit einigen Loginoptionen experimentieren bis cURL wie gewünscht funktioniert (Stichwort: ''[https://curl.se/docs/manpage.html#--login-options --login-options]'').

==== Forumlink ====
https://forum.fhem.de/index.php?topic=140814.0

=== EXIM4 (Debian) ===
Eine Anleitung zum Versenden von E-Mails mit Exim ist als PDF verfügbar: [[Medium:Anleitung Exim4 Debian GMX.pdf|PDF]]

=== SSMTP (OpenWRT, embedded Distros) ===

==== Installation ====
<syntaxhighlight lang="bash">
opkg update
opkg install ssmtp_2.64-4_mpc85xx.ipk
</syntaxhighlight>Damit <code>ssmtp</code> funktioniert müssen die Dateien <code>/etc/ssmtp/ssmtp.conf</code> und <code>/etc/ssmtp/revaliases</code> angepasst werden.

/etc/ssmtp/ssmtp.conf
<syntaxhighlight lang="text">
root=arnold@gmx.net
mailhub=mail.gmx.net:465
rewriteDomain=gmx.net
hostname=gmx.net
FromLineOverride=YES
UseTLS=YES
#UseSTARTTLS=YES
AuthUser=arnold@gmx.net
AuthPass=Passwort_von_arnold@gmx.net
</syntaxhighlight>

/etc/ssmtp/revaliases
<syntaxhighlight lang="text">
root:arnold@gmx.net:mail.gmx.net:465
</syntaxhighlight>

In der [[99_myUtils_anlegen|99_myUtils]] folgende Unterroutine einfügen:

<syntaxhighlight lang="perl">
sub OpenWRTMail
{
my $rcpt = shift;
my $subject = shift;
my $text = shift;
my $ret = "";
my $sender = "dockstar\@heye-tammo.de";
Log 1, "sendEmail RCP: $rcpt, Subject: $subject, Text: $text";
$ret .= qx(echo -e 'to:$rcpt\n from:$sender\nsubject:$subject\n$text\n' | ssmtp $rcpt);
$ret =~ s,[\r\n]*,,g; # remove CR from return-string
Log 1, "sendEmail returned: $ret";
}
</syntaxhighlight>

=== PHP Mail Funktion (Synology DiskStation) ===
Beim DSM 3.2 funktioniert der <code>php-mail</code>-Befehl, so dass man mittels folgendem Modul E-Mails versenden kann:
<syntaxhighlight lang="perl">
sub sendmail($$$) {
my($empf, $subj, $nachricht) = @_;
system("php -r 'mail(\"$empf\",\"$subj\",\"$nachricht\");'");
}
</syntaxhighlight>

=== Sendemail (Veraltet, Debian-basierende Distros) ===
Es handelt sich um ein Perl Programm, dass man aus den Paketquellen installieren kann.

Es gibt Probleme:

* mit der TLS bzw STARTTLS Verschlüsselung (https://github.com/fhem/fhem-docker/issues/254, https://www.mail-archive.com/debian-bugs-dist@lists.debian.org/msg1915977.html) ,
* Mit der Webseite des Projekts (https://web.archive.org/web/20190906140125/http://caspian.dotconf.net/menu/Software/SendEmail); diese ist nicht mehr verfügbar und nur eine archivierte Kopie kann eingesehen werden,

weswegen diese Lösung als technisch überholt gelten sollte. Will man trotzdem <code>sendemail</code> verwenden folgenden hier die Informationen dazu:

Auf dem Server muss <code>sendemail</code> installiert werden:<syntaxhighlight lang="bash" line="1">
sudo apt-get update
sudo apt-get install sendemail libio-socket-ssl-perl libnet-ssleay-perl perl
</syntaxhighlight>Man kann die korrekte Funktion im Terminal (ohne <code>{qx()}</code> ) oder auch in der FHEM Kommandozeile testen (Hinweis: manche Provider (z.B. gmail) lassen diesen Zugang erst nach Freischaltung zu!).

''Bei Gmail muss seit dem 30.6.2022 ein separates Passwort erzeugt werden, die alte Einstellung über "Zugriff durch weniger sichere Apps" funktioniert nicht mehr. Siehe Support Seite Google: <nowiki>https://support.google.com/accounts/answer/185833</nowiki>''

''Beispiel mit Gmail über Linux Terminalfenster:''
sendemail -f 'Der.Absender@gmail.com' -t 'Der.Empfaenger@gmail.com' -u 'subject' -m 'text' -a <nowiki>''</nowiki> -s 'smtp.gmail.com:587' -xu 'Der.Absender' -xp DASSUPERGEHEIMEPASSW0RT
In der [[99 myUtils anlegen|99_myUtils]] folgende Unterroutine einfügen:<syntaxhighlight lang="perl" line="1">
######## DebianMail Mail auf dem RPi versenden ############
# $provider für SMTP Server anpassen.
# Einmal in der FHEM Kommandozeile, user und password anpassen:
# {setKeyValue("myEmailKonto",'user@domain');;setKeyValue("myEmailPasswrd",'password')}
sub DebianMail
{
my $rcpt = shift;
my $subject = shift;
my $text = shift;
my $attach = shift;
my $ret = "";
my $error;
my $konto = getKeyValue("myEmailKonto");
my $passwrd = getKeyValue("myEmailPasswrd");
my $from = $konto; # or use different KeyValue if konto is not the from email address
my $provider = "smtp.1und1.de"; # smtp.domain.tld:port see provider documentation
#Log 1, "sendEmail RCP: $rcpt";
#Log 1, "sendEmail Subject: $subject";
#Log 1, "sendEmail Text: $text";
#Log 1, "sendEmail Anhang: $attach";
if (not defined($attach)){$attach=''}
$ret .= qx(sendemail -f '$from' -t '$rcpt' -u '$subject' -m '$text' -a $attach -s '$provider' -xu '$konto' -xp '$passwrd' -o tls=auto -o message-charset=utf-8);
$ret =~ s,[\r\n]*,,g; # remove CR from return-string
Log 1, "sendemail returned: $ret";
}
###############################################################################
</syntaxhighlight>

Die Zugangsdaten für den Email-Account müssen dabei FHEM-intern gespeichert werden. Dazu gibt man einmalig über die Kommandozeile folgendes ein (user@domain und password müssen auf den Email Account geändert werden):

: <code>{setKeyValue("myEmailKonto",'user@domain');;setKeyValue("myEmailPasswrd",'password')}</code>

Um die TLS Verschlüsselung (ehem. SSL) nicht zu nutzen, muss in der viertletzten Zeile tls=no verwendet und der Port des Mailproviders auf 25 eigetragen werden. Sollte anschließend keine Mail verschickt werden, siehe Probleme.

Falls der Body-Text in einem (Android-)Mailer auf dem Handy nicht gezeigt wird, kann der Parameter '''-o message-content-type=html''' helfen.

Die Funktion kann beispielsweise folgendermaßen aufgerufen werden:<syntaxhighlight lang="perl">
{qx(sendemail -f 'Ab\@send.er' -t 'Emp\@faeng.er' -u 'subject' -m 'text' -a 'DateinameOderLeer' -s 'smtpFQDN:port' -xu 'MailUser' -xp 'PasswortOhneKlammeraffen')}
</syntaxhighlight>Bei allen Feldern können generell doppelte " oder einfache ' Anführungszeichen verwendet werden. Innerhalb von "" müssen Sonderzeichen wie @ aber maskiert werden, da sie sonst als Steuerzeichen interpretiert werden:

: <code>"email\@email.domain" oder 'email@email.domain'</code>

Direkt in der FHEM Kommandozeile (ohne Anhang)

: <code>{DebianMail("email\@email.domain","Subject","Text")}</code>

Die ordnungsgemäße Ausführung wird mit 71 quittiert.

Beispiele mehrere Anhänge (Es ist wichtig Dateinamen mit Leerzeichen in separate Anführungszeichen zu setzen)
{DebianMail("email\@email.domain","Subject","Text","Anhang1 Anhang2 Anhang3")}
{DebianMail('email@email.domain','Subject','Text',"'with spaces Anhang1' 'with spaces Anhang2'")}
oder (mehr als einen Empfänger, diese können durch Leerzeichen, Semikolon oder Komma getrennt sein)
define Sonstiges at *01:00:00 {\
DebianMail('email@email.domain,email2@email.domain',"Subject","Text","'Anhang1' 'Anhang2' ...");;\
}

Die archivierte Doku zu <code>sendemail</code> befindet sich in der Änderungshistorie: https://wiki.fhem.de/w/index.php?title=E-Mail_senden&oldid=37524
[[Kategorie:E-Mail]]

E-Mail senden

2025-04-29T19:38:22Z

Torxgewinde: Hinweise von User bertl aus https://forum.fhem.de/index.php?topic=140814.msg1340245#msg1340245

Um aus FHEM heraus E-Mails senden zu können, gibt es unterschiedliche Methoden, abhängig von der verwendeten Plattform.

Lange Zeit war <code>sendemail</code> sehr beliebt. Da aber die Homepage des Projekts nicht mehr online ist und Probleme nur noch via erhöhtem Supportaufwand gelöst werden, sollte diese Option als veraltet betrachtet werden.

Eine Liste mit ressourcensparenden E-Mails Clients findet man bei dem OpenWRT Projekt: https://openwrt.org/docs/guide-user/services/email/smtp.client

MSGMail ist ein FHEM eigenes Modul zum Versenden, die Einrichtung ist allerdings nicht gänzlich einfach. Anfängern sei die cURL Methode empfohlen.

=== MSGMail (Linux, Windows) ===
FHEM bringt ein eigenes Device zum Senden von E-Mails mit, welches in Perl implementiert ist: [https://fhem.de/commandref.html#MSGMail MSGMail, https://fhem.de/commandref.html#MSGMail]

=== cURL (Linux, Windows) ===
[https://curl.se/ cURL] kann auf praktisch [https://curl.se/download.html jedem Betriebssystem] genutzt werden, [https://curl.se/windows/ selbst unter Windows]. Es kann direkt mit einem SMTP Server E-Mails versenden und stellt damit eine moderne, portable und sichere Option zum Versenden von E-Mails dar.

In FHEM richtet man sich ein Device ein und passt die Details (<code>$emailTo, $emailFrom, $emailServer</code>) an. Das Programm cURL muss installiert sein (z.B. mit <code>apt install curl</code>, oder durch Herunterladen und Installieren von der [https://curl.se cURL-Webseite]).<syntaxhighlight lang="perl" line="1">
defmod sendMail dummy
attr sendMail readingList message password
attr sendMail setList message:textField-long password
attr sendMail userReadings state:message:[\s\S]* {\
my $emailTo = 'du@example.com';;\
my $emailFrom = 'fhem@example.de';;\
my $emailServer = 'mail.your-server.de';;\
my $emailDate = strftime("%a, %d %b %Y %H:%M:%S %z", localtime(time()));;\
\
# Passwort aus getKeyValue abrufen\
my ($err, $emailPass) = getKeyValue("${name}_password");;\
if ($err || !defined $emailPass) {\
return "Error retrieving password: $err";;\
}\
\
my $message = ReadingsVal($name, 'message', '???');;\
my $subject = "$name: FHEM Nachricht";;\
\
# Betreff extrahieren und aus der Nachricht entfernen\
if ($message =~ s/(?:Subject|Betreff)=["'](.*?)["']//) {\
$subject = $1;;\
}\
\
# Empfänger extrahieren und aus der Nachricht entfernen\
if ($message =~ s/(?:To|An)=["'](.*?)["']//) {\
$emailTo = $1;;\
}\
\
#Dateianhänge bestimmen\
my @attachments;;\
while ($message =~ s/(?:Attachment|Anhang)=["'](.*?)["']//) {\
my $file = $1;;\
return ">>$file<< not found, not sending email" unless (-e $file);;\
push (@attachments, $file);;\
}\
\
#der curl Befehl wird hier aufgebaut:\
my $cmd = "curl -m 19 --noproxy '*' --no-progress-meter --ssl-reqd smtps://$emailServer:465 ";;\
$cmd .= "--user '$emailFrom:$emailPass' --mail-from '$emailFrom' --mail-rcpt '$emailTo' ";;\
$cmd .= "--write-out 'Email sent with status %{http_code}\n' ";;\
$cmd .= "-H 'Subject: $subject' ";;\
$cmd .= "-H 'From: $emailFrom' ";;\
$cmd .= "-H 'Date: $emailDate' ";;\
$cmd .= "-H 'To: $emailTo' ";;\
\
#multipart/alternative für Text und HTML EMail Body\
$cmd .= "-F '=(;;type=multipart/alternative' ";;\
\
# Leerzeichen und <br> bzw <br \> am Anfang entfernen:\
$message =~ s/^(\s|<br(?:[ \/]+)>)+//;;\
# Leerzeichen und <br> bzw <br \> am Ende entfernen:\
$message =~ s/(\s|<br(?:[ \/]+)>)+$//;;\
\
#Plaintext E-Mail Inhalt an cURL:\
$cmd .= "-F \"=$message;;type=text/plain;; charset=UTF-8\" ";;\
#ersetze \n bzw. \r\n durch ein HTML-tag <br />:\
$message =~ s/\r?\n/<br \/>/g;;\
\
#HTML E-Mail Inhalt an cURL:\
$cmd .= "-F '= <body>$message</body>;;type=text/html;; charset=UTF-8' ";;\
$cmd .= "-F '=)' ";;\
\
#jetzt alle Attachments (0..N) anhängen:\
foreach my $file (@attachments) {\
$cmd .= "-F '=@".$file.";;encoder=base64' ";;\
}\
\
#stderr auch mit in den output sammeln:\
$cmd .= " 2>&1";;\
\
#Blockierender Aufruf von cURL in dieser Funktion via BlockingCall:\
if (!defined &sendMailfunc1) {\
*sendMailfunc1 = sub ($) {\
my ($param) = @_;;\
my $result;;\
$result = qx/$param/;;\
$result = MIME::Base64::encode_base64($result);;\
$result =~ s/\n//g;;\
return $result;;\
}\
}\
\
#Rückgabe über diese Funktion,\
#anzeigen in dem reading dieses UserReadings:\
if (!defined &sendMailfunc2) {\
*sendMailfunc2 = sub ($) {\
my ($result) = @_;;\
my $hash = $defs{$name};;\
$result = MIME::Base64::decode_base64($result);;\
readingsSingleUpdate($hash, $reading, $result, 1);;\
}\
}\
\
#funktion falls BlockingCall abgebrochen wird:\
if (!defined &sendMailfunc3) {\
*sendMailfunc3 = sub ($) {\
my ($result) = @_;;\
my $hash = $defs{$name};;\
readingsSingleUpdate($hash, $reading, $result, 1);;\
}\
}\
\
BlockingCall("sendMailfunc1", $cmd, "sendMailfunc2", 20, "sendMailfunc3", "Error: timeout");;\
\
return "started cURL command...";;\
},\
state:password:.* {\
# Passwort speichern\
my $ret = setKeyValue("${name}_password", ReadingsVal($name, 'password', undef)) // "password stored";;\
\
#password wieder aus der Variablen rausnehmen, soll nicht sichtbar bleiben:\
#\
# Hinweis: das Password taucht beim Setzen hierüber im Event-Log auf!\
# Alternativ: { setKeyValue("sendMail_password", "geheimesPasswort") }\
readingsBulkUpdate($hash, "password", "****");;\
\
return "$ret";;\
}
</syntaxhighlight>Das Passwort setzt man mit:

* <code>set sendMail password geheimesPasswort</code>
* Alternativ, damit das Passwort nicht im Log auftaucht: <code>{ setKeyValue("sendMail_password", "geheimesPasswort") }</code>

E-Mails kann man dann Senden mit:

* <code>set sendMail message Mein Text</code> (es wird der Standardbetreff und Empfänger aus dem Snippet genutzt)
* <code>set sendMail message Betreff="Mein Betreff" Mein Text</code>(es wird der Empfänger aus dem Snippet genutzt)
* <code>set sendMail message Subject="Dies ist ein Test" Mein Text</code>
* <code>set sendMail message To="jemand@example.com" Mein Text</code>
* <code>set sendMail message An="jemand@example.com" Mein Text</code>
* <code>set sendMail message An="jemand@example.com" Betreff="Mein Betreff" Mein Text</code>
* <code>set sendMail message To="jemand@example.com" Subject="Mein Betreff" Mein Text</code>
* <code>set sendMail message Subject="✅ Dies ist ein Test" Meldung mit Emoji ⚽ geht auch</code>
* Eine Datei mit anhängen: <code>set sendMail message Subject="Dies ist ein Test" Anhang="www/images/fhemSVG/bag.svg" Mein Text</code>
* Zwei Dateien mit anhängen: <code>set sendMail message Subject="Dies ist ein Test" Anhang="./www/images/fhemSVG/bag.svg" Anhang="www/images/fhemSVG/batterie.svg" Mein Text</code>, für die anzuhängenden Dateien können relative und absolute Pfade verwendet werden. Beim Vorbereiten der E-Mail wird geprüft ob die Dateien existieren, da dies sonst eine typische Fehlerquelle ist. Es wird nichts versendet wenn eine Datei nicht gefunden werden kann.

==== Fehlersuche ====
Sollte cURL zwar installiert sein, aber keine E-Mails versenden, kann es sein, dass das Protokoll nicht einkompiliert wurde. Dies ist bei OpenWRT zum Beispiel der Fall.

So sollte es aussehen (hier ein Ubuntu), relevant ist für diese Nutzung das Protokoll smtp und smtps, das braucht man:<syntaxhighlight lang="bash">
curl -V
curl 8.5.0 (x86_64-pc-linux-gnu) libcurl/8.5.0 OpenSSL/3.0.13 zlib/1.3 brotli/1.1.0 zstd/1.5.5 libidn2/2.3.7 libpsl/0.21.2 (+libidn2/2.3.7) libssh/0.10.6/openssl/zlib nghttp2/1.59.0 librtmp/2.3 OpenLDAP/2.6.7
Release-Date: 2023-12-06, security patched: 8.5.0-2ubuntu10.6
Protocols: dict file ftp ftps gopher gophers http https imap imaps ldap ldaps mqtt pop3 pop3s rtmp rtsp scp sftp smb smbs smtp smtps telnet tftp
Features: alt-svc AsynchDNS brotli GSS-API HSTS HTTP2 HTTPS-proxy IDN IPv6 Kerberos Largefile libz NTLM PSL SPNEGO SSL threadsafe TLS-SRP UnixSockets zstd

</syntaxhighlight>So sollte es nicht aussehen (hier ein OpenWRT):<syntaxhighlight lang="bash">
curl: (1) Protocol "smtps" not supported

curl -V
curl 8.10.1 (arm-openwrt-linux-gnu) libcurl/8.10.1 mbedTLS/3.6.2 nghttp2/1.63.0
Release-Date: 2024-09-18
Protocols: file ftp ftps http https ipfs ipns mqtt
Features: alt-svc HSTS HTTP2 HTTPS-proxy IPv6 Largefile SSL threadsafe UnixSockets

</syntaxhighlight>Hat man nur ein cURL ohne das Protokoll, so muss man sich das Paket leider anderweitig beschaffen (chroot, selbst kompilieren, statisch gelinkte Version, ...).

==== Forumlink ====
https://forum.fhem.de/index.php?topic=140814.0

=== EXIM4 (Debian) ===
Eine Anleitung zum Versenden von E-Mails mit Exim ist als PDF verfügbar: [[Medium:Anleitung Exim4 Debian GMX.pdf|PDF]]

=== SSMTP (OpenWRT, embedded Distros) ===

==== Installation ====
<syntaxhighlight lang="bash">
opkg update
opkg install ssmtp_2.64-4_mpc85xx.ipk
</syntaxhighlight>Damit <code>ssmtp</code> funktioniert müssen die Dateien <code>/etc/ssmtp/ssmtp.conf</code> und <code>/etc/ssmtp/revaliases</code> angepasst werden.

/etc/ssmtp/ssmtp.conf
<syntaxhighlight lang="text">
root=arnold@gmx.net
mailhub=mail.gmx.net:465
rewriteDomain=gmx.net
hostname=gmx.net
FromLineOverride=YES
UseTLS=YES
#UseSTARTTLS=YES
AuthUser=arnold@gmx.net
AuthPass=Passwort_von_arnold@gmx.net
</syntaxhighlight>

/etc/ssmtp/revaliases
<syntaxhighlight lang="text">
root:arnold@gmx.net:mail.gmx.net:465
</syntaxhighlight>

In der [[99_myUtils_anlegen|99_myUtils]] folgende Unterroutine einfügen:

<syntaxhighlight lang="perl">
sub OpenWRTMail
{
my $rcpt = shift;
my $subject = shift;
my $text = shift;
my $ret = "";
my $sender = "dockstar\@heye-tammo.de";
Log 1, "sendEmail RCP: $rcpt, Subject: $subject, Text: $text";
$ret .= qx(echo -e 'to:$rcpt\n from:$sender\nsubject:$subject\n$text\n' | ssmtp $rcpt);
$ret =~ s,[\r\n]*,,g; # remove CR from return-string
Log 1, "sendEmail returned: $ret";
}
</syntaxhighlight>

=== PHP Mail Funktion (Synology DiskStation) ===
Beim DSM 3.2 funktioniert der <code>php-mail</code>-Befehl, so dass man mittels folgendem Modul E-Mails versenden kann:
<syntaxhighlight lang="perl">
sub sendmail($$$) {
my($empf, $subj, $nachricht) = @_;
system("php -r 'mail(\"$empf\",\"$subj\",\"$nachricht\");'");
}
</syntaxhighlight>

=== Sendemail (Veraltet, Debian-basierende Distros) ===
Es handelt sich um ein Perl Programm, dass man aus den Paketquellen installieren kann.

Es gibt Probleme:

* mit der TLS bzw STARTTLS Verschlüsselung (https://github.com/fhem/fhem-docker/issues/254, https://www.mail-archive.com/debian-bugs-dist@lists.debian.org/msg1915977.html) ,
* Mit der Webseite des Projekts (https://web.archive.org/web/20190906140125/http://caspian.dotconf.net/menu/Software/SendEmail); diese ist nicht mehr verfügbar und nur eine archivierte Kopie kann eingesehen werden,

weswegen diese Lösung als technisch überholt gelten sollte. Will man trotzdem <code>sendemail</code> verwenden folgenden hier die Informationen dazu:

Auf dem Server muss <code>sendemail</code> installiert werden:<syntaxhighlight lang="bash" line="1">
sudo apt-get update
sudo apt-get install sendemail libio-socket-ssl-perl libnet-ssleay-perl perl
</syntaxhighlight>Man kann die korrekte Funktion im Terminal (ohne <code>{qx()}</code> ) oder auch in der FHEM Kommandozeile testen (Hinweis: manche Provider (z.B. gmail) lassen diesen Zugang erst nach Freischaltung zu!).

''Bei Gmail muss seit dem 30.6.2022 ein separates Passwort erzeugt werden, die alte Einstellung über "Zugriff durch weniger sichere Apps" funktioniert nicht mehr. Siehe Support Seite Google: <nowiki>https://support.google.com/accounts/answer/185833</nowiki>''

''Beispiel mit Gmail über Linux Terminalfenster:''
sendemail -f 'Der.Absender@gmail.com' -t 'Der.Empfaenger@gmail.com' -u 'subject' -m 'text' -a <nowiki>''</nowiki> -s 'smtp.gmail.com:587' -xu 'Der.Absender' -xp DASSUPERGEHEIMEPASSW0RT
In der [[99 myUtils anlegen|99_myUtils]] folgende Unterroutine einfügen:<syntaxhighlight lang="perl" line="1">
######## DebianMail Mail auf dem RPi versenden ############
# $provider für SMTP Server anpassen.
# Einmal in der FHEM Kommandozeile, user und password anpassen:
# {setKeyValue("myEmailKonto",'user@domain');;setKeyValue("myEmailPasswrd",'password')}
sub DebianMail
{
my $rcpt = shift;
my $subject = shift;
my $text = shift;
my $attach = shift;
my $ret = "";
my $error;
my $konto = getKeyValue("myEmailKonto");
my $passwrd = getKeyValue("myEmailPasswrd");
my $from = $konto; # or use different KeyValue if konto is not the from email address
my $provider = "smtp.1und1.de"; # smtp.domain.tld:port see provider documentation
#Log 1, "sendEmail RCP: $rcpt";
#Log 1, "sendEmail Subject: $subject";
#Log 1, "sendEmail Text: $text";
#Log 1, "sendEmail Anhang: $attach";
if (not defined($attach)){$attach=''}
$ret .= qx(sendemail -f '$from' -t '$rcpt' -u '$subject' -m '$text' -a $attach -s '$provider' -xu '$konto' -xp '$passwrd' -o tls=auto -o message-charset=utf-8);
$ret =~ s,[\r\n]*,,g; # remove CR from return-string
Log 1, "sendemail returned: $ret";
}
###############################################################################
</syntaxhighlight>

Die Zugangsdaten für den Email-Account müssen dabei FHEM-intern gespeichert werden. Dazu gibt man einmalig über die Kommandozeile folgendes ein (user@domain und password müssen auf den Email Account geändert werden):

: <code>{setKeyValue("myEmailKonto",'user@domain');;setKeyValue("myEmailPasswrd",'password')}</code>

Um die TLS Verschlüsselung (ehem. SSL) nicht zu nutzen, muss in der viertletzten Zeile tls=no verwendet und der Port des Mailproviders auf 25 eigetragen werden. Sollte anschließend keine Mail verschickt werden, siehe Probleme.

Falls der Body-Text in einem (Android-)Mailer auf dem Handy nicht gezeigt wird, kann der Parameter '''-o message-content-type=html''' helfen.

Die Funktion kann beispielsweise folgendermaßen aufgerufen werden:<syntaxhighlight lang="perl">
{qx(sendemail -f 'Ab\@send.er' -t 'Emp\@faeng.er' -u 'subject' -m 'text' -a 'DateinameOderLeer' -s 'smtpFQDN:port' -xu 'MailUser' -xp 'PasswortOhneKlammeraffen')}
</syntaxhighlight>Bei allen Feldern können generell doppelte " oder einfache ' Anführungszeichen verwendet werden. Innerhalb von "" müssen Sonderzeichen wie @ aber maskiert werden, da sie sonst als Steuerzeichen interpretiert werden:

: <code>"email\@email.domain" oder 'email@email.domain'</code>

Direkt in der FHEM Kommandozeile (ohne Anhang)

: <code>{DebianMail("email\@email.domain","Subject","Text")}</code>

Die ordnungsgemäße Ausführung wird mit 71 quittiert.

Beispiele mehrere Anhänge (Es ist wichtig Dateinamen mit Leerzeichen in separate Anführungszeichen zu setzen)
{DebianMail("email\@email.domain","Subject","Text","Anhang1 Anhang2 Anhang3")}
{DebianMail('email@email.domain','Subject','Text',"'with spaces Anhang1' 'with spaces Anhang2'")}
oder (mehr als einen Empfänger, diese können durch Leerzeichen, Semikolon oder Komma getrennt sein)
define Sonstiges at *01:00:00 {\
DebianMail('email@email.domain,email2@email.domain',"Subject","Text","'Anhang1' 'Anhang2' ...");;\
}

Die archivierte Doku zu <code>sendemail</code> befindet sich in der Änderungshistorie: https://wiki.fhem.de/w/index.php?title=E-Mail_senden&oldid=37524
[[Kategorie:E-Mail]]

E-Mail senden

2025-04-18T17:09:26Z

Torxgewinde: Absendedatum wird vom Server gesetzt, Hinweis von Nutzer moskito im Forum

Um aus FHEM heraus E-Mails senden zu können, gibt es unterschiedliche Methoden, abhängig von der verwendeten Plattform.

Lange Zeit war <code>sendemail</code> sehr beliebt. Da aber die Homepage des Projekts nicht mehr online ist und Probleme nur noch via erhöhtem Supportaufwand gelöst werden, sollte diese Option als veraltet betrachtet werden.

Eine Liste mit ressourcensparenden E-Mails Clients findet man bei dem OpenWRT Projekt: https://openwrt.org/docs/guide-user/services/email/smtp.client

MSGMail ist ein FHEM eigenes Modul zum Versenden, die Einrichtung ist allerdings nicht gänzlich einfach. Anfängern sei die cURL Methode empfohlen.

=== MSGMail (Linux, Windows) ===
FHEM bringt ein eigenes Device zum Senden von E-Mails mit, welches in Perl implementiert ist: [https://fhem.de/commandref.html#MSGMail MSGMail, https://fhem.de/commandref.html#MSGMail]

=== cURL (Linux, Windows) ===
[https://curl.se/ cURL] kann auf praktisch [https://curl.se/download.html jedem Betriebssystem] genutzt werden, [https://curl.se/windows/ selbst unter Windows]. Es kann direkt mit einem SMTP Server E-Mails versenden und stellt damit eine moderne, portable und sichere Option zum Versenden von E-Mails dar.

In FHEM richtet man sich ein Device ein und passt die Details (<code>$emailTo, $emailFrom, $emailServer</code>) an. Das Programm cURL muss installiert sein (z.B. mit <code>apt install curl</code>, oder durch Herunterladen und Installieren von der [https://curl.se cURL-Webseite]).<syntaxhighlight lang="perl" line="1">
defmod sendMail dummy
attr sendMail readingList message password
attr sendMail setList message:textField-long password
attr sendMail userReadings state:message:[\s\S]* {\
my $emailTo = 'du@example.com';;\
my $emailFrom = 'fhem@example.de';;\
my $emailServer = 'mail.your-server.de';;\
my $emailDate = strftime("%a, %d %b %Y %H:%M:%S %z", localtime(time()));;\
\
# Passwort aus getKeyValue abrufen\
my ($err, $emailPass) = getKeyValue("${name}_password");;\
if ($err || !defined $emailPass) {\
return "Error retrieving password: $err";;\
}\
\
my $message = ReadingsVal($name, 'message', '???');;\
my $subject = "$name: FHEM Nachricht";;\
\
# Betreff extrahieren und aus der Nachricht entfernen\
if ($message =~ s/(?:Subject|Betreff)=["'](.*?)["']//) {\
$subject = $1;;\
}\
\
# Empfänger extrahieren und aus der Nachricht entfernen\
if ($message =~ s/(?:To|An)=["'](.*?)["']//) {\
$emailTo = $1;;\
}\
\
#Dateianhänge bestimmen\
my @attachments;;\
while ($message =~ s/(?:Attachment|Anhang)=["'](.*?)["']//) {\
my $file = $1;;\
return ">>$file<< not found, not sending email" unless (-e $file);;\
push (@attachments, $file);;\
}\
\
#der curl Befehl wird hier aufgebaut:\
my $cmd = "curl -m 19 --noproxy '*' --no-progress-meter --ssl-reqd smtps://$emailServer:465 ";;\
$cmd .= "--user '$emailFrom:$emailPass' --mail-from '$emailFrom' --mail-rcpt '$emailTo' ";;\
$cmd .= "--write-out 'Email sent with status %{http_code}\n' ";;\
$cmd .= "-H 'Subject: $subject' ";;\
$cmd .= "-H 'From: $emailFrom' ";;\
$cmd .= "-H 'Date: $emailDate' ";;\
\
#multipart/alternative für Text und HTML EMail Body\
$cmd .= "-F '=(;;type=multipart/alternative' ";;\
\
# Leerzeichen und <br> bzw <br \> am Anfang entfernen:\
$message =~ s/^(\s|<br(?:[ \/]+)>)+//;;\
# Leerzeichen und <br> bzw <br \> am Ende entfernen:\
$message =~ s/(\s|<br(?:[ \/]+)>)+$//;;\
\
#Plaintext E-Mail Inhalt an cURL:\
$cmd .= "-F \"=$message;;type=text/plain;; charset=UTF-8\" ";;\
#ersetze \n bzw. \r\n durch ein HTML-tag <br />:\
$message =~ s/\r?\n/<br \/>/g;;\
\
#HTML E-Mail Inhalt an cURL:\
$cmd .= "-F '= <body>$message</body>;;type=text/html;; charset=UTF-8' ";;\
$cmd .= "-F '=)' ";;\
\
#jetzt alle Attachments (0..N) anhängen:\
foreach my $file (@attachments) {\
$cmd .= "-F '=@".$file.";;encoder=base64' ";;\
}\
\
#stderr auch mit in den output sammeln:\
$cmd .= " 2>&1";;\
\
#Blockierender Aufruf von cURL in dieser Funktion via BlockingCall:\
if (!defined &sendMailfunc1) {\
*sendMailfunc1 = sub ($) {\
my ($param) = @_;;\
my $result;;\
$result = qx/$param/;;\
$result = MIME::Base64::encode_base64($result);;\
$result =~ s/\n//g;;\
return $result;;\
}\
}\
\
#Rückgabe über diese Funktion,\
#anzeigen in dem reading dieses UserReadings:\
if (!defined &sendMailfunc2) {\
*sendMailfunc2 = sub ($) {\
my ($result) = @_;;\
my $hash = $defs{$name};;\
$result = MIME::Base64::decode_base64($result);;\
readingsSingleUpdate($hash, $reading, $result, 1);;\
}\
}\
\
#funktion falls BlockingCall abgebrochen wird:\
if (!defined &sendMailfunc3) {\
*sendMailfunc3 = sub ($) {\
my ($result) = @_;;\
my $hash = $defs{$name};;\
readingsSingleUpdate($hash, $reading, $result, 1);;\
}\
}\
\
BlockingCall("sendMailfunc1", $cmd, "sendMailfunc2", 20, "sendMailfunc3", "Error: timeout");;\
\
return "started cURL command...";;\
},\
state:password:.* {\
# Passwort speichern\
my $ret = setKeyValue("${name}_password", ReadingsVal($name, 'password', undef)) // "password stored";;\
\
#password wieder aus der Variablen rausnehmen, soll nicht sichtbar bleiben:\
#\
# Hinweis: das Password taucht beim Setzen hierüber im Event-Log auf!\
# Alternativ: { setKeyValue("sendMail_password", "geheimesPasswort") }\
readingsBulkUpdate($hash, "password", "****");;\
\
return "$ret";;\
}
</syntaxhighlight>Das Passwort setzt man mit:

* <code>set sendMail password geheimesPasswort</code>
* Alternativ, damit das Passwort nicht im Log auftaucht: <code>{ setKeyValue("sendMail_password", "geheimesPasswort") }</code>

E-Mails kann man dann Senden mit:

* <code>set sendMail message Mein Text</code> (es wird der Standardbetreff und Empfänger aus dem Snippet genutzt)
* <code>set sendMail message Betreff="Mein Betreff" Mein Text</code>(es wird der Empfänger aus dem Snippet genutzt)
* <code>set sendMail message Subject="Dies ist ein Test" Mein Text</code>
* <code>set sendMail message To="jemand@example.com" Mein Text</code>
* <code>set sendMail message An="jemand@example.com" Mein Text</code>
* <code>set sendMail message An="jemand@example.com" Betreff="Mein Betreff" Mein Text</code>
* <code>set sendMail message To="jemand@example.com" Subject="Mein Betreff" Mein Text</code>
* <code>set sendMail message Subject="✅ Dies ist ein Test" Meldung mit Emoji ⚽ geht auch</code>
* Eine Datei mit anhängen: <code>set sendMail message Subject="Dies ist ein Test" Anhang="www/images/fhemSVG/bag.svg" Mein Text</code>
* Zwei Dateien mit anhängen: <code>set sendMail message Subject="Dies ist ein Test" Anhang="./www/images/fhemSVG/bag.svg" Anhang="www/images/fhemSVG/batterie.svg" Mein Text</code>, für die anzuhängenden Dateien können relative und absolute Pfade verwendet werden. Beim Vorbereiten der E-Mail wird geprüft ob die Dateien existieren, da dies sonst eine typische Fehlerquelle ist. Es wird nichts versendet wenn eine Datei nicht gefunden werden kann.

==== Fehlersuche ====
Sollte cURL zwar installiert sein, aber keine E-Mails versenden, kann es sein, dass das Protokoll nicht einkompiliert wurde. Dies ist bei OpenWRT zum Beispiel der Fall.

So sollte es aussehen (hier ein Ubuntu), relevant ist für diese Nutzung das Protokoll smtp und smtps, das braucht man:<syntaxhighlight lang="bash">
curl -V
curl 8.5.0 (x86_64-pc-linux-gnu) libcurl/8.5.0 OpenSSL/3.0.13 zlib/1.3 brotli/1.1.0 zstd/1.5.5 libidn2/2.3.7 libpsl/0.21.2 (+libidn2/2.3.7) libssh/0.10.6/openssl/zlib nghttp2/1.59.0 librtmp/2.3 OpenLDAP/2.6.7
Release-Date: 2023-12-06, security patched: 8.5.0-2ubuntu10.6
Protocols: dict file ftp ftps gopher gophers http https imap imaps ldap ldaps mqtt pop3 pop3s rtmp rtsp scp sftp smb smbs smtp smtps telnet tftp
Features: alt-svc AsynchDNS brotli GSS-API HSTS HTTP2 HTTPS-proxy IDN IPv6 Kerberos Largefile libz NTLM PSL SPNEGO SSL threadsafe TLS-SRP UnixSockets zstd

</syntaxhighlight>So sollte es nicht aussehen (hier ein OpenWRT):<syntaxhighlight lang="bash">
curl: (1) Protocol "smtps" not supported

curl -V
curl 8.10.1 (arm-openwrt-linux-gnu) libcurl/8.10.1 mbedTLS/3.6.2 nghttp2/1.63.0
Release-Date: 2024-09-18
Protocols: file ftp ftps http https ipfs ipns mqtt
Features: alt-svc HSTS HTTP2 HTTPS-proxy IPv6 Largefile SSL threadsafe UnixSockets

</syntaxhighlight>Hat man nur ein cURL ohne das Protokoll, so muss man sich das Paket leider anderweitig beschaffen (chroot, selbst kompilieren, statisch gelinkte Version, ...).

==== Forumlink ====
https://forum.fhem.de/index.php?topic=140814.0

=== EXIM4 (Debian) ===
Eine Anleitung zum Versenden von E-Mails mit Exim ist als PDF verfügbar: [[Medium:Anleitung Exim4 Debian GMX.pdf|PDF]]

=== SSMTP (OpenWRT, embedded Distros) ===

==== Installation ====
<syntaxhighlight lang="bash">
opkg update
opkg install ssmtp_2.64-4_mpc85xx.ipk
</syntaxhighlight>Damit <code>ssmtp</code> funktioniert müssen die Dateien <code>/etc/ssmtp/ssmtp.conf</code> und <code>/etc/ssmtp/revaliases</code> angepasst werden.

/etc/ssmtp/ssmtp.conf
<syntaxhighlight lang="text">
root=arnold@gmx.net
mailhub=mail.gmx.net:465
rewriteDomain=gmx.net
hostname=gmx.net
FromLineOverride=YES
UseTLS=YES
#UseSTARTTLS=YES
AuthUser=arnold@gmx.net
AuthPass=Passwort_von_arnold@gmx.net
</syntaxhighlight>

/etc/ssmtp/revaliases
<syntaxhighlight lang="text">
root:arnold@gmx.net:mail.gmx.net:465
</syntaxhighlight>

In der [[99_myUtils_anlegen|99_myUtils]] folgende Unterroutine einfügen:

<syntaxhighlight lang="perl">
sub OpenWRTMail
{
my $rcpt = shift;
my $subject = shift;
my $text = shift;
my $ret = "";
my $sender = "dockstar\@heye-tammo.de";
Log 1, "sendEmail RCP: $rcpt, Subject: $subject, Text: $text";
$ret .= qx(echo -e 'to:$rcpt\n from:$sender\nsubject:$subject\n$text\n' | ssmtp $rcpt);
$ret =~ s,[\r\n]*,,g; # remove CR from return-string
Log 1, "sendEmail returned: $ret";
}
</syntaxhighlight>

=== PHP Mail Funktion (Synology DiskStation) ===
Beim DSM 3.2 funktioniert der <code>php-mail</code>-Befehl, so dass man mittels folgendem Modul E-Mails versenden kann:
<syntaxhighlight lang="perl">
sub sendmail($$$) {
my($empf, $subj, $nachricht) = @_;
system("php -r 'mail(\"$empf\",\"$subj\",\"$nachricht\");'");
}
</syntaxhighlight>

=== Sendemail (Veraltet, Debian-basierende Distros) ===
Es handelt sich um ein Perl Programm, dass man aus den Paketquellen installieren kann.

Es gibt Probleme:

* mit der TLS bzw STARTTLS Verschlüsselung (https://github.com/fhem/fhem-docker/issues/254, https://www.mail-archive.com/debian-bugs-dist@lists.debian.org/msg1915977.html) ,
* Mit der Webseite des Projekts (https://web.archive.org/web/20190906140125/http://caspian.dotconf.net/menu/Software/SendEmail); diese ist nicht mehr verfügbar und nur eine archivierte Kopie kann eingesehen werden,

weswegen diese Lösung als technisch überholt gelten sollte. Will man trotzdem <code>sendemail</code> verwenden folgenden hier die Informationen dazu:

Auf dem Server muss <code>sendemail</code> installiert werden:<syntaxhighlight lang="bash" line="1">
sudo apt-get update
sudo apt-get install sendemail libio-socket-ssl-perl libnet-ssleay-perl perl
</syntaxhighlight>Man kann die korrekte Funktion im Terminal (ohne <code>{qx()}</code> ) oder auch in der FHEM Kommandozeile testen (Hinweis: manche Provider (z.B. gmail) lassen diesen Zugang erst nach Freischaltung zu!).

''Bei Gmail muss seit dem 30.6.2022 ein separates Passwort erzeugt werden, die alte Einstellung über "Zugriff durch weniger sichere Apps" funktioniert nicht mehr. Siehe Support Seite Google: <nowiki>https://support.google.com/accounts/answer/185833</nowiki>''

''Beispiel mit Gmail über Linux Terminalfenster:''
sendemail -f 'Der.Absender@gmail.com' -t 'Der.Empfaenger@gmail.com' -u 'subject' -m 'text' -a <nowiki>''</nowiki> -s 'smtp.gmail.com:587' -xu 'Der.Absender' -xp DASSUPERGEHEIMEPASSW0RT
In der [[99 myUtils anlegen|99_myUtils]] folgende Unterroutine einfügen:<syntaxhighlight lang="perl" line="1">
######## DebianMail Mail auf dem RPi versenden ############
# $provider für SMTP Server anpassen.
# Einmal in der FHEM Kommandozeile, user und password anpassen:
# {setKeyValue("myEmailKonto",'user@domain');;setKeyValue("myEmailPasswrd",'password')}
sub DebianMail
{
my $rcpt = shift;
my $subject = shift;
my $text = shift;
my $attach = shift;
my $ret = "";
my $error;
my $konto = getKeyValue("myEmailKonto");
my $passwrd = getKeyValue("myEmailPasswrd");
my $from = $konto; # or use different KeyValue if konto is not the from email address
my $provider = "smtp.1und1.de"; # smtp.domain.tld:port see provider documentation
#Log 1, "sendEmail RCP: $rcpt";
#Log 1, "sendEmail Subject: $subject";
#Log 1, "sendEmail Text: $text";
#Log 1, "sendEmail Anhang: $attach";
if (not defined($attach)){$attach=''}
$ret .= qx(sendemail -f '$from' -t '$rcpt' -u '$subject' -m '$text' -a $attach -s '$provider' -xu '$konto' -xp '$passwrd' -o tls=auto -o message-charset=utf-8);
$ret =~ s,[\r\n]*,,g; # remove CR from return-string
Log 1, "sendemail returned: $ret";
}
###############################################################################
</syntaxhighlight>

Die Zugangsdaten für den Email-Account müssen dabei FHEM-intern gespeichert werden. Dazu gibt man einmalig über die Kommandozeile folgendes ein (user@domain und password müssen auf den Email Account geändert werden):

: <code>{setKeyValue("myEmailKonto",'user@domain');;setKeyValue("myEmailPasswrd",'password')}</code>

Um die TLS Verschlüsselung (ehem. SSL) nicht zu nutzen, muss in der viertletzten Zeile tls=no verwendet und der Port des Mailproviders auf 25 eigetragen werden. Sollte anschließend keine Mail verschickt werden, siehe Probleme.

Falls der Body-Text in einem (Android-)Mailer auf dem Handy nicht gezeigt wird, kann der Parameter '''-o message-content-type=html''' helfen.

Die Funktion kann beispielsweise folgendermaßen aufgerufen werden:<syntaxhighlight lang="perl">
{qx(sendemail -f 'Ab\@send.er' -t 'Emp\@faeng.er' -u 'subject' -m 'text' -a 'DateinameOderLeer' -s 'smtpFQDN:port' -xu 'MailUser' -xp 'PasswortOhneKlammeraffen')}
</syntaxhighlight>Bei allen Feldern können generell doppelte " oder einfache ' Anführungszeichen verwendet werden. Innerhalb von "" müssen Sonderzeichen wie @ aber maskiert werden, da sie sonst als Steuerzeichen interpretiert werden:

: <code>"email\@email.domain" oder 'email@email.domain'</code>

Direkt in der FHEM Kommandozeile (ohne Anhang)

: <code>{DebianMail("email\@email.domain","Subject","Text")}</code>

Die ordnungsgemäße Ausführung wird mit 71 quittiert.

Beispiele mehrere Anhänge (Es ist wichtig Dateinamen mit Leerzeichen in separate Anführungszeichen zu setzen)
{DebianMail("email\@email.domain","Subject","Text","Anhang1 Anhang2 Anhang3")}
{DebianMail('email@email.domain','Subject','Text',"'with spaces Anhang1' 'with spaces Anhang2'")}
oder (mehr als einen Empfänger, diese können durch Leerzeichen, Semikolon oder Komma getrennt sein)
define Sonstiges at *01:00:00 {\
DebianMail('email@email.domain,email2@email.domain',"Subject","Text","'Anhang1' 'Anhang2' ...");;\
}

Die archivierte Doku zu <code>sendemail</code> befindet sich in der Änderungshistorie: https://wiki.fhem.de/w/index.php?title=E-Mail_senden&oldid=37524
[[Kategorie:E-Mail]]

HTTPMOD

2025-04-14T19:32:42Z

Torxgewinde: Moved the code to more suitable location

{{Infobox Modul
|ModPurpose=Extract information from devices with an HTTP interface (or, more generic, from any URL) or send information to such devices
|ModType=d
|ModCmdRef=HTTPMOD
|ModForumArea=Sonstiges
|ModTechName=98_HTTPMOD.pm
|ModOwner=StefanStrobel ({{Link2FU|3960|Forum}} / [[Benutzer:StefanStrobel|Wiki]])
}}
[[HTTPMOD]] provides a generic way to retrieve information from devices with an HTTP Interface and store them in Readings or send information to such devices. It queries a given URL with Headers and data defined by attributes.

From the HTTP response it extracts readings named in attributes using Regexes, JSON or XPath parsing also defined by attributes.

In an advanced [[Konfiguration|configuration]] the module can also send information to devices. To do this, a generic <code>set</code> option can be configured using attributes.

== Introduction ==
With the help of HTTPMOD you can automatically access websites, retrieve information and send data. In the simplest case, an http call is started regularly and the content of a page, for example, is read and processed further. The URL and the time interval in which the call is to be made must then be specified when the call is made. In order to read information from the called web pages, readings are required. In this readings one specifies Regex, which reads the necessary information. Here is an example.

<syntaxhighlight lang="perl">
define PM HTTPMOD http://www.klack.de/fernsehprogramm/was-laeuft-gerade/0/-1/free.html 20000
</syntaxhighlight>

This creates a device that accesses the http://www.klack.de/fernsehprogramm/was-laeuft-gerade/0/-1/free.html website with the TV program every 20000 seconds. If neither readings nor other attributes are defined, then only the call of the website takes place and FHEM receives no further data from the web access.

But now a television program is returned when you call the website, which you might want to read out. In order to save the contents in FHEM, which are related to the ARD, you need a reading. This reading must contain a name (so that FHEM knows under which name the information is stored) and a regex (so that you know where the information is stored on the website). Since usually not one, but many readings are defined, these readings are numbered consecutively. This is done by numbers that are given immediately after the word reading. In our example this would be for example
<syntaxhighlight lang="perl">
attr PM reading1Name ARD
attr PM reading1Regex <span class="stationName">ARD<\/span>[\w\W]*?<div class="content">\s*<a[\w\W]*?>\s*(.*?)\s*<\/a>
attr PM reading2Name ARD_time
attr PM reading2Regex <span class="stationName">ARD<\/span>[\w\W]*?<td class="time">\s*(.*?)\s*<
attr PM reading3Name ARD_details
attr PM reading3Regex <span class="stationName">ARD<\/span>[\w\W]*?<div class="content">\s*<a[\w\W]*?>[\w\W]*?<\/a>\s*<br\/>\s*(.*?)(<img|<\/div)
</syntaxhighlight>

Reading1 contains the programme, reading2 the time and reading3 further details. The Regex result from the structure of the website and may have to be designed in painstaking detail.

There are cases where this is not enough. For example, it could be the case that the information from the web access is not automated, but manually received. Then a 0 must first be entered at the top of the duration. But how does HTTPMOD then know when the data should be retrieved? This is done with get-commands. If a get-command is executed, HTTPMOD accesses the website, fetches the information and fills the corresponding readings.

Again, it is possible to create not one but several get-commands. Therefore, get is always followed by (at least) one number with which the get commands are numbered. Here is another example. The TV program should be called manually and not time-controlled. To do this we first change the definition to
<syntaxhighlight lang="perl">
define PM HTTPMOD http://www.klack.de/fernsehprogramm/was-laeuft-gerade/0/-1/free.html 0
</syntaxhighlight>
and add the following to the attributes
<syntaxhighlight lang="perl">
attr PM get1Name ARDHolen
</syntaxhighlight>
With the command "get PM ARDHolen" the above readings are filled. In order for FHEM to know that the other reading2, reading3, etc. are to be read as well as reading1, the (user) attribute
<syntaxhighlight lang="perl">
attr PM get1CheckAllReadings 1
</syntaxhighlight>
needs to be defined.

If the URL is not sufficient when the web page is called, but a special header is to be sent with it, this can be done with the get1Header attribute. If the header is multiline, the individual lines can be entered with get1Header1, get1Header2, and so on.

If you want to evaluate or control different URLs, you can define several get commands (get1, get2, etc.) and provide them with your own URLs. get1 usually reads only the reading1, get2 reads only the reading2 and so on. With CheckAllReadings all readings are evaluated simultaneously.

If only data is to be sent on the web page, but not read, the set command is recommended. It has the same structure as the get-command.

It becomes a bit more complex if the website requires a login check. The sid attributes are used for this purpose.

== Availability, prerequisites and definition ==
This module is part of the regular FHEM distribution and uses the non blocking HTTP function <code>HttpUtils_NonblockingGet</code> provided by FHEM's [[HttpUtils]] in a new version published in December 2013.
If not already installed in your environment, please [[update]] FHEM or install it manually using appropriate commands from your environment.
Please also note that FHEM HttpUtils need the global attribute dnsServer to be set in order to work really non blocking even when dns requests can not be answered.

The device is defined as follows
<syntaxhighlight lang="perl">
define <name> HTTPMOD <URL> <Interval>
</syntaxhighlight>
The module connects to the given <code>URL</code> every <code>Interval</code> seconds, sends optional headers and data and then parses the response with regular expressions, xpath or json to set readings.

URL can be "none" and Interval can be 0 if you prefer to only query data with a get command and not in a defined interval.

Example:
<syntaxhighlight lang="perl">
define PM HTTPMOD http://MyPoolManager/cgi-bin/webgui.fcgi 60
</syntaxhighlight>

== Set-Commands ==
can be defined using attributes, see advanced configuration

If you set the attribute enableControlSet to 1, the following additional built in set commands are available:
;interval
:set new interval time in seconds and restart the timer
;reread
:request the defined URL and try to parse it just like the automatic update would do it every Interval seconds without modifying the running timer.
;stop
:stop interval timer.
;start
:restart interval timer to call GetUpdate after interval seconds
;upgradeAttributes
:convert outdated attributes for older HTTPMOD-Versions that are still defined for this device from the old syntax to the new one.
:attributes with the description "this attribute should not be used anymore" or similar will be translated to the new syntax, e.g. readingsName1 to reading01Name.
;storeKeyValue
:stores a key value pair in an obfuscated form in the file system. Such values can then be used in replacements where the mode is "key" e.g. to avoid storing passwords in the configuration in clear text

== Get-Commands ==
can be defined using attributes, see advanced configuration

== simple Attributes ==
;enableControlSet
:enables the built in set commands ''interval'', ''stop'', ''start'', ''reread'', ''upgradeAttributes'', ''storeKeyValue''

;enableCookies
:enables the cookie handling inside HTTPMOD. It is advisable to always set this attribute and allow HTTPMOD to track the state of cookies and set them for following HTTP-requests

;enforceGoodReadingNames
:makes sure that HTTPMOD only creates readings that are allowd for Fhem (especially if reading names are dynamically created from JSON object names with extractAllJSON. It is advisable to always set this attribute.

;handleRedirects
:enables the redirect handling inside HTTPMOD which should be used together with the cookie handling of HTTPMOD. HTTPMOD will then automatically follow redirects from a web server and keep track of cookies at the same time. It is advisable to always set this attribute.

;requestHeader.*
:Define an additional HTTP Header to set in the HTTP request

;requestData
:POST Data to be sent in the request. If not defined, it will be a GET request as defined in HttpUtils used by this module

;reading[0-9]+(-[0-9]+)?Name
:the name of a reading to extract with the corresponding readingRegex

;reading[0-9]*(-[0-9]+)?OExpr
:defines an expression that is used in an eval to compute the readings value. The raw value will be in the variable $val.

;reading[0-9]*(-[0-9]+)?OMap
:Output Map. Defines a mapping from raw to visible values like "0:mittig, 1:oberhalb, 2:unterhalb". If specified as readingOMap then the attribute value is a default for all other readings that don't specify an explicit reading[0-9]*OMap.

;reading[0-9]*(-[0-9]+)?Format
:Defines a format string that will be used in sprintf to format a reading value. If specified as readingFormat then the attribute value is a default for all other readings that don't specify an explicit reading[0-9]*Format.

;reading[0-9]*(-[0-9]+)?Decode
:defines an encoding to be used in a call to the perl function decode to convert the raw data string read from the device to a reading. This can be used if the device delivers strings in an encoding like cp850 instead of utf8.

;reading[0-9]*(-[0-9]+)?Encode
:defines an encoding to be used in a call to the perl function encode to convert the raw data string read from the device to a reading. This can be used if the device delivers strings in an encoding like cp850 and after decoding it you want to reencode it to e.g. utf8.

;reading[0-9]+Regex
:defines the regex to be used for extracting the reading. The value to extract should be in a capture group / sub expression
:e.g. ([\d\.]+) in the above example. Multiple capture groups will create multiple readings (see explanation above)

;reading[0-9]+XPath
:defines an xpath to one or more readings when parsing HTML data (see examples below)

;reading[0-9]+XPath-Strict
:defines an xpath to one or more readings when parsing XML data (see examples below)

;reading[0-9]+JSON
:defines a path to the JSON object wanted by concatenating the object names with an underscore as delimiter (see the example below)

;noShutdown
:pass the noshutdown flag to HTTPUtils for webservers that need it (some embedded webservers only deliver empty pages otherwise)

;disable
:stop doing automatic HTTP requests while this attribute is set to 1

;timeout
:time in seconds to wait for an answer. Default value is 2

;do_not_notify

;readingFnAttributes

== Simple Configuration of HTTP Devices ==
If your device expects special HTTP-headers then specify them as <code>attr requestHeader1</code> to <code>attr requestHeaderX</code>.
If your Device expects an HTTP POST instead of HTTP GET then the POST-data can be specified as <code>attr requestData</code>.
To get the readings, specify pairs of <code>attr readingXName</code> and <code>attr readingXRegex</code>, <code>attr readingXXPath</code>, <code>attr readingXXPath-Strict</code> or <code>attr readingXJSON</code> to define which readings you want to extract from the HTTP response and how to extract them. (The old syntax <code>attr readingsNameX</code> and <code>attr readingsRegexX</code> is still supported but the new one with <code>attr readingXName</code> and <code>attr readingXRegex</code> should be preferred. The actual values to be extracted have to be sub expressions within () in the regex (see example below)

=== Example for a PoolManager 5: ===
The PoolManager Web GUI can be queried with HTTP POST Requests like this one:

<syntaxhighlight lang="perl">
POST /cgi-bin/webgui.fcgi HTTP/1.1
Host: 192.168.70.90
Accept: */*
Content-Type: application/json;charset=UTF-8
Content-Length: 60

{"get" :["34.4001.value" ,"34.4008.value" ,"34.4033.value"]}
</syntaxhighlight>

The resulting HTTP Response would look like this:

<syntaxhighlight lang="perl">
HTTP/1.1 200 OK
Content-type: application/json; charset=UTF-8
Expires: 0
Cache-Control: no-cache
Date: Sun, 12 Jan 2014 12:23:11 GMT
Server: lighttpd/1.4.26
Content-Length: 179

{
"data": {
"34.4001.value": "7.00",
"34.4008.value": "0.52",
"34.4033.value": "24.8"
},
"status": {
"code": 0
},
"event": {
"type": 1,
"data": "48.30000.0"
}
}
</syntaxhighlight>

To configure HTTPMOD for a PoolManager one would first define a PoolManager device with e.g. the name PM, the URL and an interval of e.g. 60 seconds.

Then the data to be sent in the request needs to be defined because in this example the device expects a POST request so the query is not contained in the URL but in the request data.

Also as seen above the device expects special HTTP headers in the request so these headers also need to be defined as <code>attr PM requestHeader1</code> and <code>attr PM requestHeader2</code>

Then the names of the readings to be extracted would be set with attributes

Then for each reading value to be extracted a regular expression needs to be set that will match the value in question within ().

Example:
<syntaxhighlight lang="perl">
define PM HTTPMOD http://MyPoolManager/cgi-bin/webgui.fcgi 60

attr PM enableControlSet 1
attr PM enableCookies 1
attr PM enforceGoodReadingNames 1
attr PM handleRedirects 1

attr PM reading01Name PH
attr PM reading01Regex 34.4001.value":[ \t]+"([\d\.]+)"

attr PM reading02Name CL
attr PM reading02Regex 34.4008.value":[ \t]+"([\d\.]+)"

attr PM reading03Name3TEMP
attr PM reading03Regex 34.4033.value":[ \t]+"([\d\.]+)"

attr PM requestData {"get" :["34.4001.value" ,"34.4008.value" ,"34.4033.value", "14.16601.value", "14.16602.value"]}
attr PM requestHeader1 Content-Type: application/json
attr PM requestHeader2 Accept: */*
attr PM stateFormat {sprintf("%.1f Grad, PH %.1f, %.1f mg/l Chlor", ReadingsVal($name,"TEMP",0), ReadingsVal($name,"PH",0), ReadingsVal($name,"CL",0))}
</syntaxhighlight>

=== Example for AmbientMonitor ===
AmbientMonitor is a webbased visualisation for sensors connected to an Arduino device. Its web interface can also be queried with HTTMOD to grab the data into readings.

This example was provided by locutus. The hardware configuration is an Arduino + Ethercard with ENC28J60 Controller + DHT22 Sensor and software can be downloaded from https://github.com/lucadentella/AmbientMonitor

In this example an HTTP GET is sufficent, so no <code>requestData</code> is needed. The device provides temperature and humidity readings in an HTTP response that looks like:
<syntaxhighlight lang="perl">
HTTP/1.0 200 OK
Content-Type: text/html

myCB({'temperature':22.00,'humidity':46.00})
</syntaxhighlight>

the definition could be:
<syntaxhighlight lang="perl">
define AmbientMonitor HTTPMOD http://192.168.1.221/?callback=? 300

attr AmbientMonitor enableControlSet 1
attr AmbientMonitor enableCookies 1
attr AmbientMonitor enforceGoodReadingNames 1
attr AmbientMonitor handleRedirects 1

attr AmbientMonitor requestHeader Content-Type: application/json
attr AmbientMonitor reading1Name Temperatur
attr AmbientMonitor reading1Regex temperature':([\d\.]+)
attr AmbientMonitor reading2Name Feuchtigkeit
attr AmbientMonitor reading2Regex humidity':([\d\.]+)
attr AmbientMonitor stateFormat {sprintf("Temperatur %.1f C, Feuchtigkeit %.1f %", ReadingsVal($name,"Temperatur",0), ReadingsVal($name,"Feuchtigkeit",0))}
</syntaxhighlight>

== formatting and manipulating values / readings ==
Values that are parsed from an HTTP response can be further treated or formatted with the following attributes:

* <code>(reading|get)[0-9]*(-[0-9]+)?OExpr</code>
* <code>(reading|get)[0-9]*(-[0-9]+)?OMap</code>
* <code>(reading|get)[0-9]*(-[0-9]+)?Format</code>
* <code>(reading|get)[0-9]*(-[0-9]+)?Decode</code>
* <code>(reading|get)[0-9]*(-[0-9]+)?Encode</code>

They can all be specified for an individual reading, for all readings in one match (e.g. if a regular expression has several capture groups) or for all readings in a get command (defined by getXX) or for all readings in the main reading list (defined by readingXX):
<syntaxhighlight lang="perl">
reading01Format %.1f
</syntaxhighlight>

will format the reading with the name specified by the attribute reading01Name to be numerical with one digit after the decimal point.
If the attribute reading01Regex is used and contains several capture groups then the format will be applied to all readings parsed by this regex unless these readings have their own format specified by reading01-1Format, reading01-2Format and so on.

<syntaxhighlight lang="perl">
reading01-2Format %.1f
</syntaxhighlight>

Can be used in cases where a regular expression specified as reading01regex contains several capture groups or an xpath specified as reading01XPath creates several readings.
In this case reading01-2Format specifies the format to be applied to the second match.

<syntaxhighlight lang="perl">
readingFormat %.1f
</syntaxhighlight>

applies to all readings defined by a reading-Attribute that have no more specific format.

If you need to do some calculation on a raw value before it is used as a reading, you can define the attribute <code>readingOExpr</code>.
It defines a Perl expression that is used in an eval to compute the readings value. The raw value will be in the variable $val.

Example for an expression:
<syntaxhighlight lang="perl">
attr PM reading03OExpr $val * 10
</syntaxhighlight>
Just like in the above example of the readingFormat attributes, readingOExpr and the other following attributes can be applied on several levels.

To map a numerical value to a name, you can use the readingOMap attribute.
It defines a mapping from raw to visible values like "0:mittig, 1:oberhalb, 2:unterhalb".

Example for a map:
<syntaxhighlight lang="perl">
attr PM reading02-3OMap 0:kalt, 1:warm, 2:sehr warm
</syntaxhighlight>

To convert character sets, the module can first decode a string read from the device and then encode it again. For example:
<syntaxhighlight lang="perl">
attr PM getDecode UTF-8
</syntaxhighlight>

This applies to all readings defined for Get-Commands.

== Some help with Regular Expressions ==
{{Randnotiz|RNTyp=y|RNText=Starting with version ''2018-02-10'' the internal that holds the HTTP response is no longer called '''''buf''''' but rather '''''httpbody''''', and it is only displayed when attribute '''''showBody''''' is set to "1".}}
If HTTPMOD seems not to work and the FHEM Logfile contains a message like
:<code>HTTPMOD: Response didn't match Reading ...</code>
then you should check if the value you want to extract is read into the internal with the name buf. Internals are visible when you click on the defined HTTPMOD Device. buf is an internal variable that contains the HTTP Response read. If the value is there and you get the mentioned message then probably something is wrong with your regular expression. Please note that buf might contain special characters like newlines but they are not shown in fhemweb. If you are new to regular expressions then the introduction at http://perldoc.perl.org/perlretut.html might be helpful.

For a typical HTTPMOD use case where you want to extract a number out of a HTTP-Response you can use something like <code>[\d\.]+</code> to match the number itself. The expression matches the number characters (<code>\d</code>) or a <code>.</code> if one of these characters occurs at least once.

To tell HTTPMOD that the number is what you want to use for the reading, you have to put the expression in between <code>()</code>. A <code>([\d\.]+)</code> alone would match the longest number in the HTTP Response which is very likely not the number you are looking for so you need to add something to the expression to give it a context and define how to find the number that you are looking for.

If there is a title text before the number or a special text after the number you can put this in the regex. In one of the examples above <code>humidity':([\d\.]+)</code> is looking for the number that immediately follows the text <code>humidity':</code> without any blanks in between.
Be careful if the text you are getting from your device contains special characters like newline. You don't see such special characters in the fhem webinterface as contents of the internal buf but they might cause your regular expression to fail.

If you have trouble defining a regular expression that matches a certain name, then many complicated characters and then a number, it might be helpful to use a negation in matching like <code>temp[^\d]+([\d\.]).*</code>. In this examle <code>[^\d]+</code> means any character that is not a numerical digit, more than once.

=== Regular Expressions with multiple capture Groups ===
The regular expressions used in the above example for a Poolmanager will take the value that matches one capture group. This is the part of the regular expression inside (). In the above example "([\d\.]+)" refers to numerical digits or points between double quotation marks. Only the string consiting of digits and points will match inside (). This piece is assigned to the reading.

You can also use regular expressions that have several capture groups which might be helpful when parsing tables. In this case an attribute like

<syntaxhighlight lang="perl">
reading02Regex something[ \t]+([\d\.]+)[ \t]+([\d\.]+)
</syntaxhighlight>

could match two numbers. When you specify only one reading02Name like
<syntaxhighlight lang="perl">
reading02Name Temp
</syntaxhighlight>

the name Temp will be used with the extension -1 and -2 thus giving a reading Temp-1 for the first number and Temp-2 for the second. You can also specify individual names for several readings that get parsed from one regular expression with several capture groups by defining attributes

<syntaxhighlight lang="perl">
reading02-1Name
reading02-2Name
...
</syntaxhighlight>
The same notation can be used for formatting attributes like readingXOMap, readingXFormat and so on.

The usual way to define readings is however to have an individual regular expression with just one capture group per reading as shown in the above example.

== Parsing JSON ==

If a webservice delivers data in JSON format, HTTPMOD can directly parse JSON which might be easier in this case than definig regular expressions.
The next example shows the data that can be requested from a Poolmanager with the following partial configuration:

<syntaxhighlight lang="perl">
define test2 HTTPMOD none 0
attr test2 get01Name Chlor
attr test2 getURL http://192.168.70.90/cgi-bin/webgui.fcgi
attr test2 getHeader1 Content-Type: application/json
attr test2 getHeader2 Accept: */*
attr test2 getData {"get" :["34.4008.value"]}
</syntaxhighlight>

The data in the HTTP response looks like this:

<syntaxhighlight lang="perl">
{
"data": {
"34.4008.value": "0.25"
},
"status": {
"code": 0
},
"event": {
"type": 1,
"data": "48.30000.0"
}
}
</syntaxhighlight>

the classic way to extract the value 0.25 into a reading with the name Chlor with a regex would have been
<syntaxhighlight lang="perl">
attr test2 get01Regex 34.4008.value":[ \t]+"([\d\.]+)"
</syntaxhighlight>

with JSON you can write
<syntaxhighlight lang="perl">
attr test2 get01JSON data_34.4008.value
</syntaxhighlight>
which will create a reading with the Name "Chlor" (as shown above) and take the value 0.25 from the JSON string.

or if you don't care about the naming of your readings, you can simply extract all JSON data with
<syntaxhighlight lang="perl">
attr test2 extractAllJSON
</syntaxhighlight>

which would apply to all data read from this device and create the following readings out of the HTTP response shown above:

{| class="wikitable"
| data_34.4008.value || 0.25
|-
| event_data || 48.30000.0
|-
| event_type || 1
|-
| status_code || 0
|}

or you can specify
<syntaxhighlight lang="perl">
attr test2 get01ExtractAllJSON
</syntaxhighlight>
which would only apply to all data read as response to the get command defined as get01.

It might seem very simple at first sight to use extractAllJSON but if you prefer readings with a meaningful name you should instead define these readings with readingXXName and readingXXJSON or getXXName and getXXJSON individually. Of Course it would be possible to create additional user readings outside HTTPMOD but doing calculations, naming and formatting inside HTTPMOD is more efficient.

=== JSON Lists ===

imagine the HTTP Response contains:

<syntaxhighlight lang="perl">
{ "power":"0",
"modes":["Off","SimpleColor","RainbowChase"],
"code1":3,
"code2":4
}
</syntaxhighlight>

then a configuration like

<syntaxhighlight lang="perl">
attr device reading01JSON modes
attr device reading01Name Mode
</syntaxhighlight>

will create a list of Subreadings just like a regex with multiple matches can create multiple subreadings:

{| class="wikitable"
| Mode-1 || Off
|-
| Mode-2 || SimpleColor
|-
| Mode-3 || RainbowChase
|}

if you don't want several subreadings but one reading that contains the list of modes, you can specify a recombine expression:

<syntaxhighlight lang="perl">
attr device reading01Name Modes
attr device reading01RecombineExpr join ",", @matchlist
</syntaxhighlight>

which will create one reading containing a list:

{| class="wikitable"
| Modes || Off,SimpleColor,RainbowChase
|}

JSON parsing specifications also don't Need to match exactly. If there is no exact match for a defined reading, the HTTPMOD will try to Interpret the specification as a regex and look for json object paths that match the specification as a regex. For example:

<syntaxhighlight lang="perl">
attr device reading01Name CodeElem
attr device reading01JSON code
</syntaxhighlight>

which will create a list of readings:

{| class="wikitable"
| CodeElem-1|| 3
|-
| CodeElem-2 || 4
|}

and of course they could also be recombined into one reading with a RecombineExpr Attribute.

== Parsing http / XML using xpath ==
Another alternative to regex parsing is the use of XPath to extract values from HTTP responses.
The following example shows how XML data can be parsed with XPath-Strict or HTML Data can be parsed with XPath.
Both work similar and the example uses XML Data parsed with the XPath-Strict option:

If The XML data in the HTTP response looks like this:

<syntaxhighlight lang="xml">
<root xmlns:foo="http://www.foo.org/" xmlns:bar="http://www.bar.org">
<actors>
<actor id="1">Peter X</actor>
<actor id="2">Charles Y</actor>
<actor id="3">John Doe</actor>
</actor>
</root>
</syntaxhighlight>

with XPath you can write
<syntaxhighlight lang="perl">
attr htest reading01Name Actor
attr htest reading01XPath-Strict //actor[2]/text()
</syntaxhighlight>

This will create a reading with the Name "Actor" and the value "Charles Y".

Since XPath specifications can define several values / matches, HTTPMOD can also interpret these and store them in multiple readings:
<syntaxhighlight lang="perl">
attr htest reading01Name Actor
attr htest reading01XPath-Strict //actor/text()
</syntaxhighlight>

will create the readings

{| class="wikitable"
| Actor-1 || Peter X
|-
| Actor-2 || Charles Y
|-
| Actor-3 || John Doe
|}

== Further replacements of URL, header or post data ==
sometimes it might be helpful to dynamically change parts of a URL, HTTP header or post data depending on existing readings, internals or
perl expressions at runtime. This might be needed to pass further variables to a server, a current date or other things.

To support this HTTPMOD offers generic replacements that are applied to a request before it is sent to the server. A replacement can be defined with the attributes

* <code>replacement[0-9]*Regex</code>
* <code>replacement[0-9]*Mode</code>
* <code>replacement[0-9]*Value</code>
* <code>[gs]et[0-9]*Replacement[0-9]*Value</code>

a replacement always replaces a match of a regular expression.

'''replacement[0-9]*Mode:'''
The way the replacement value is defined can be specified with the replacement mode.
* If the <code>replacement[0-9]*Mode</code> is <code>reading</code>, then the corresponding <code>replacement[0-9]*Value</code> is interpreted as the name of a ''reading'' of the same device or as ''device:reading'' to refer to another device.
* If the <code>replacement[0-9]*Mode</code> is <code>internal</code>, then the corresponding <code>replacement[0-9]*Value</code> is interpreted as the name of an ''internal'' of the same device or as ''device:internal'' to refer to another device.
* If the <code>replacement[0-9]*Mode</code> is <code>text</code>, then the corresponding <code>replacement[0-9]*Value</code> is interpreted as a static text
* If the <code>replacement[0-9]*Mode</code> is <code>expression</code>, then the corresponding <code>replacement[0-9]*Value</code> is evaluated as a perl expression to compute the replacement. Inside such a replacement expression it is possible to refer to capture groups of the replacement regex.
* If the <code>replacement[0-9]*Mode</code> is <code>key</code>, then the module will use a value from a key / value pair that is stored in an obfuscated form in the file system with the set storeKeyValue command. This might be useful for storing passwords.

Example:

<syntaxhighlight lang="perl" line="1">
attr mydevice getData {"get" :["%%value%%.value"]}
attr mydevice replacement01Mode text
attr mydevice replacement01Regex %%value%%

attr mydevice get01Name Chlor
attr mydevice get01Replacement01Value 34.4008

attr mydevice get02Name Something
attr mydevice get02Replacement01Value 31.4024

attr mydevice get05Name profile
attr mydevice get05URL http://www.mydevice.local/getprofile?password=%%password%%
attr mydevice replacement02Mode key
attr mydevice replacement02Regex %%password%%
attr mydevice replacement02Value password
</syntaxhighlight>

defines that <code>%%value%%</code> will be replaced by a static text.

All Get commands will be HTTP post requests of a similar form. Only the <code>%%value%%</code> will be different from get to get.
The first get will set the reading named Chlor and for the request it will take the generic getData and replace %%value%% with 34.4008.

A second get will look the same except a different name and replacement value.

With the command <code>set mydevice storeKeyValue password geheim</code> you can store the password geheim in an obfuscated form in the file system.
To use this password and send it in a request you can use the above replacement with mode key. The value password will then refer to the ofuscated string stored with the key password.

The mode <code>expression</code> allows you to define your own replacement syntax:
<syntaxhighlight lang="perl">
attr mydevice replacement01Mode expression
attr mydevice replacement01Regex {{([^}]+)}}
attr mydevice replacement01Value ReadingsVal("mydevice", $1, "")
attr mydevice getData {"get" :["{{temp}}.value"]}
</syntaxhighlight>

In this example any <code><nowiki>{{name}}</nowiki></code> in a URL, header or post data will be passed on to the perl function ReadingsVal
which uses the string between <code><nowiki>{{}}</nowiki></code> as second parameter. This way one defined replacement can be used for many different
readings.

HTTPMOD has two built in replacements: One for session Ids and another one for the input value in a set command.
The placeholder $sid is always replaced with the internal <code>$hash->{sid}</code> which contains the session id after it is extracted from a previous HTTP response.
If you don't like to use the placeholder $sid then you can define your own replacement for example like:

<syntaxhighlight lang="perl">
attr mydevice replacement01Mode internal
attr mydevice replacement01Regex %session%
attr mydevice replacement01Value sid
</syntaxhighlight>

Now the internal <code>$hash->{sid}</code> will be used as a replacement for the placeholder %session%.

In the same way a value that is passed to a set-command can be put into a request with a user defined replacement.
In this case the internal <code>$hash->{value}</code> will contain the value passed to the set command.
<code>$hash->{value}</code> might even be a string containing several values that could be put into several different positions in a request by using user defined replacements.

'''Example: set-magic in HTTPMOD'''

To achieve the same just like [[set magic]] the following can be added to a HTTPMOD device:<syntaxhighlight lang="perl">
attr Owntone.device replacement02Mode expression
attr Owntone.device replacement02Regex \[([^:]+):([^\]]+)\]
attr Owntone.device replacement02Value my $device = $name if ($1 eq "\$name") // $1;;\
ReadingsVal($device, $2, undef) or AttrVal($device, $2, "???");;
</syntaxhighlight>With that definition you can just write <code>[$name:state]</code> to get the state-reading of your own HTTPMOD device there. It also accepts other devicenames and first searches for a reading and if no reading is found it searches for an attrbibute with a matching name. This neat trick is used throughout in the Owntone-HTTPMOD-device (see links section below) to keep it easily adoptable to different server names without editing many places in the listing.

'''Other example : steering a pellet stove from Rika'''

The stove API of Rika on https://www.rika-firenet.com/web/ delivers a JSON string with all settings and values, and can be piloted with a data string containing all the "set" values at once.

Delivered JSON on get https://www.rika-firenet.com/api/client/xxxxxxxx/status : (xxxxxxxx must be replaced with the unique stove ID)
<syntaxhighlight lang="perl">
{
"name": "Vorzimmer",
"stoveID": "xxxxxxxxx",
"lastSeenMinutes": 1,
"lastConfirmedRevision": 1504385700,
"controls": {
"revision": 1504385700,
"onOff": true,
"operatingMode": 2,
"heatingPower": 65,
"targetTemperature": 24,
"heatingTimesActive": false,
"heatingTimesActiveForComfort": true,
"setBackTemperature": 18,
"convectionFan1Active": false,
"convectionFan1Level": 0,
"convectionFan1Area": 0,
"convectionFan2Active": false,
"convectionFan2Level": 0,
"convectionFan2Area": 0,
"frostProtectionActive": false,
"frostProtectionTemperature": 5
},
"sensors": {
"statusError": 0,
"statusWarning": 0,
"statusService": 0,
"statusMainState": 1,
"statusSubState": 3,
"statusFrostStarted": false,
"inputFlameTemperature": 21,
"inputRoomTemperature": 21,
"inputExternalRequest": true,
"outputDischargeMotor": 0,
"outputInsertionMotor": 0,
"outputIDFan": 0,
"outputAirFlaps": 0,
"outputIgnition": false,
"parameterStoveTypeNumber": 13,
"parameterVersionMainBoard": 223,
"parameterVersionTFT": 223,
"parameterRuntimePellets": 11,
"parameterRuntimeLogs": 0,
"parameterFeedRateTotal": 17,
"parameterFeedRateService": 683,
"parameterOnOffCycles": 2
},
"stoveType": "DOMO MultiAir",
"stoveFeatures": {
"multiAir1": true,
"multiAir2": true,
"insertionMotor": false,
"airFlaps": false,
"logRuntime": false
}
}
</syntaxhighlight>

Data string to send to https://www.rika-firenet.com/api/client/xxxxxxxx/controls in order to set values:
<syntaxhighlight lang="perl">
heatingTimesActiveForComfort=true&frostProtectionTemperature=3&setBackTemperature=18&targetTemperature=24&convectionFan2Level=0&convectionFan2Active=false&convectionFan1Level=0&onOff=true&convectionFan1Active=false&convectionFan2Area=0&revision=1505550101&heatingTimesActive=false&convectionFan1Area=0&frostProtectionActive=false&operatingMode=2&heatingPower=65
</syntaxhighlight>

Code in 99_myUtils.pm:
<syntaxhighlight lang="perl">
use JSON;
...
sub
replaceJSON ($$) {
my ($valToReplace, $value) = @_;

#$value in the parameters is a default value
#It has to be replaced through the real value nnn passed in the set command "set <device> valToset nnn"
$value = InternalVal("Ofen", "value", $value);
Log3 ("Ofen", 3, "replaceJSON Internalvalue: $value");

#Force an update to avoid outdated revision number
fhem ("get Ofen revision");

#Get all the controls as json
my $json = ReadingsVal("Ofen", "controlsJSON","");
Log3 ("Ofen", 3, "replaceJSON configsJSON: $json");

# When starting FHEM or rereading config, the reading controlsJSON is empty
return if ($json eq "");

my $decoded = decode_json($json);
my $result;
for my $key ( keys %$decoded ) {
$result .= "$key=";
if ($key eq $valToReplace) {
$result .= $value."&";
} else {
$result .= $decoded->{$key}."&";
}
}
chop($result); #remove last &
Log3("Ofen", 3, "replaceJSON Result: $result");
return $result;
}
</syntaxhighlight>

Define stove in fhem:
<syntaxhighlight lang="perl">
defmod Ofen HTTPMOD https://www.rika-firenet.com/api/client/xxxxxxxx/status 60

attr Ofen enableCookies 1
attr Ofen reAuthRegex id="login"|Unauthorized
attr Ofen sid01Data email=xx@xx&password=xx
attr Ofen sid01URL https://www.rika-firenet.com/web/login

attr Ofen reading01JSON sensors_inputRoomTemperature
attr Ofen reading01Name RaumTemp
attr Ofen reading02JSON controls_setBackTemperature
attr Ofen reading02Name Absenkung
attr Ofen reading03JSON controls_frostProtectionTemperature
attr Ofen reading03Name Frostschutz
attr Ofen reading10Name controlsJSON
attr Ofen reading10Regex (?s)controls.*?({.*?})

attr Ofen get09Name revision
attr Ofen get09URL https://www.rika-firenet.com/api/client/xxxxxxxx/status

attr Ofen setURL https://www.rika-firenet.com/api/client/xxxxxxxx/controls
attr Ofen setData {{data}}
attr Ofen replacement01Mode expression
attr Ofen replacement01Regex {{data}}

attr Ofen set11Name frostProtectionTemperature
attr Ofen set11Replacement01Value replaceJSON("frostProtectionTemperature", 2)

attr Ofen set12Name targetTemperature
attr Ofen set12Replacement01Value replaceJSON("targetTemperature", 24)
</syntaxhighlight>

A detailed explanation (in german) of the login process can be found here: [https://forum.fhem.de/index.php/topic,76220.msg682514.html#msg682514]
and the explanation of the other parameters here: [https://forum.fhem.de/index.php/topic,76220.msg685710.html#msg685710]

== replacing reading values when they have not been updated / the device did not respond ==
If a device does not respond then the values stored in readings will keep the same and only their timestamp shows that they are outdated.
If you want to modify reading values that have not been updated for a number of seconds, you can use the attributes

* <code>(reading|get)[0-9]*(-[0-9]+)?MaxAge</code>
* <code>(reading|get)[0-9]*(-[0-9]+)?MaxAgeReplacementMode</code>
* <code>(reading|get)[0-9]*(-[0-9]+)?MaxAgeReplacement</code>

Every time the module tries to read from a device, it will also check if readings have not been updated
for longer than the <code>MaxAge</code> attributes allow. If readings are outdated, the <code>MaxAgeReplacementMode</code> defines how the affected
reading values should be replaced. <code>MaxAgeReplacementMode</code> can be <code>text</code>, <code>reading</code>, <code>internal</code>, <code>expression</code> or <code>delete</code>.

<code>MaxAge</code> specifies the number of seconds that a reading should remain untouched before it is replaced.

<code>MaxAgeReplacement</code> contains either a static text that is used as replacement value or a Perl expression that is evaluated to
give the replacement value. This can be used for example to replace a temperature that has not bee updated for more than 5 minutes
with the string "outdated - was 12":
<syntaxhighlight lang="perl">
attr PM readingMaxAge 300
attr PM readingMaxAgeReplacement "outdated - was " . $val
attr PM readingMaxAgeReplacementMode expression
</syntaxhighlight>
The variable <code>$val</code> contains the value of the reading before it became outdated.

Or to show that a device was offline:
<syntaxhighlight lang="perl">
attr MyLight reading01Name color
attr MyLight reading01JSON result_02_color
attr MyLight reading01MaxAge 300
attr MyLight reading01MaxAgeReplacement "offline"
attr MyLight reading01MaxAgeReplacementMode text
</syntaxhighlight>

== Note on determining how to send requests to a special device ==
If you don't know which URLs, headers or POST data your web GUI uses, you might try a local proxy like BurpSuite [http://portswigger.net/burp/ BurpSuite] to track requests and responses. This is a tedious task but probably the best way to achieve a successful result.

Let us consider an example. The Telekom Speedport W724V has a login-site that is famous for being cumbersome. Burp allows to monitor each step in the login procedure. In the case of a speedport the following steps occur:

First burp shows that a get command is issued
##################################################################################################
GET / HTTP/1.1
Host: speedport.ip
Cache-Control: max-age=0
Upgrade-Insecure-Requests: 1
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/57.0.2987.133 Safari/537.36
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8
Accept-Language: de-DE,de;q=0.8,en-US;q=0.6,en;q=0.4
Cookie: lang=de
Connection: close
In order to mimic the behavior of a real person calling the website HTTPMOD should copy all necessary steps. Host, Cookie and the GET-command are usually necessary. The same cannot be said of the User-Agent because the website can be called from any mobile or desktop computer.

Then, the speedport will answer with a command that consists of several lines. By going through every line for every step in the login procedure one will finally arrive at the information that is necessary to successfully enter the login of the speedport (in case of the W724V, for example, it is necessary to copy a token called _httoken and to include the referer).

== Advanced configuration to define a <code>set</code> command and send data to a device ==

When a set option is defined by attributes, the module will use the value given to the set command and integrate it into an HTTP-Request that sends the value to the device. The definitions for URL, headers and post data can contain the placeholder $val which will be replaced by the (numerical) value given to the set command.

This can be as simple as:
<syntaxhighlight lang="perl">
# No cyclic requests and no main URL needed in this example
define MyDevice HTTPMOD none 0

attr MyDevice set01Name Licht
attr MyDevice set01URL http://192.168.1.22/switch=$val
</syntaxhighlight>

A user command
<syntaxhighlight lang="perl">
set MyDevice Licht 1
</syntaxhighlight>

will be translated into the http GET request
<syntaxhighlight lang="perl">
http://192.168.1.22/switch=1
</syntaxhighlight>

In this example a map would also be helpful, that translates on / off to 0 or 1 and allows the user to select on/of in fhemweb:
<syntaxhighlight lang="perl">
attr MyDevive set01IMap 0:off, 1:on
</syntaxhighlight>
This also provides input validation to make sure that only on and off can be used with the set command.

In more complex Scenarios you might need to login before sending a command and the Login might create a session id that has to be part of further requests either in the URL, in headers or in the post data.

Extension to the above example for a PoolManager 5 where a set needs a session id in the URL and the values have to be passed in JSON strings as post data:
<syntaxhighlight lang="perl">
attr PM set01Name HeizungSoll
attr PM set01URL http://MyPoolManager/cgi-bin/webgui.fcgi?sid=$sid
attr PM set01Hint 6,10,20,30
attr PM set01Min 6
attr PM set01Max 30
attr PM setHeader1 Content-Type: application/json
attr PM set01Data {"set" :{"34.3118.value" :"$val" }}
</syntaxhighlight>

This example defines a set option with the name HeizungSoll.
By issuing <code>set PM HeizungSoll 10</code> in FHEM, the value 10 will be sent in the defined HTTP
Post to URL <code>http://MyPoolManager/cgi-bin/webgui.fcgi</code> in the Post Data as

<syntaxhighlight lang="html">
{"set" :{"34.3118.value" :"10" }}
</syntaxhighlight>

The optional attributes set01Min and set01Max define input validations that will be checked in the set function.
The optional attribute set01Hint will define a selection list for the FHEMweb GUI.

The HTTP response to such a request will be ignored unless you specify the attribute <code>setParseResponse</code>
for all set commands or <code>set01ParseResponse</code> for the set command with number 01.
If the HTTP response to a set command is parsed then this is done like the parsing of responses to get commands and you can use the attributes ending e.g. on Format, Encode, Decode, OMap and OExpr to manipulate / format the values read.

If a parameter to a set command is not numeric but should be passed on to the device as text, then you can specify the attribute setTextArg. For example:
<syntaxhighlight lang="perl">
attr PM set01TextArg
</syntaxhighlight>

If a set command should not require a parameter at all, then you can specify the attribute NoArg. For example:
<syntaxhighlight lang="perl">
attr PM set03Name On
attr PM set03NoArg
</syntaxhighlight>

This example defines the set of parameters for Wiesemann&Theiss Web-IO Analog 4.0 #57761. The current limit is set to 16mA (setxxMax)
<syntaxhighlight lang="Perl">
defmod WuT_Analog1 HTTPMOD none 30
attr WuT_Analog1 room W&T
attr WuT_Analog1 set01Max 16
attr WuT_Analog1 set01Min 0
attr WuT_Analog1 set01Name Output1
attr WuT_Analog1 set01URL http://192.xx.My_IP/outputaccess1?PW=MyPassword&State=$val&
attr WuT_Analog1 set02Max 16
attr WuT_Analog1 set02Min 0
attr WuT_Analog1 set02Name Output2
attr WuT_Analog1 set02URL http://192.xx.My_IP/outputaccess2?PW=MyPassword&State=$val&
</syntaxhighlight>

== Advanced configuration to create a valid session id that might be necessary ==
In simple cases logging in works with basic authentication. In the case HTTPMOD accepts a username and password as part of the URL in the form
<syntaxhighlight lang="perl">
http://User:Password@192.168.1.18/something
</syntaxhighlight>

However basic auth is seldom used. If you need to fill in a username and password in a HTML form and the session is then managed by a session id, here is how to configure this:

when sending data to an HTTP-Device in a set, HTTPMOD will replace any <code>$sid</code> in the URL, Headers and Post data with the internal <code>$hash->{sid}</code>. To authenticate towards the device and give this internal a value, you can use an optional multi step login procedure defined by the following attributes:

* <code>sid[0-9]*URL</code>
* <code>sid[0-9]*Data.*</code>
* <code>sid[0-9]*Header.*</code>
* <code>sid[0-9]*IgnoreRedirects</code>
* <code>idRegex</code>
* <code>idJSON</code>
* <code>idXPath</code>
* <code>idXPath-Strict</code>
* <code>(get|set|sid)[0-9]*IdRegex</code>
* <code>(get|set|sid)[0-9]*IdJSON</code>
* <code>(get|set|sid)[0-9]*IdXPath</code>
* <code>(get|set|sid)[0-9]*IdXPath-Strict</code>

Each step can have a URL, Headers, Post Data pieces and a Regex to extract a resulting Session ID into <code>$hash->{sid}</code>.
HTTPMOD will create a sorted list of steps (the numbers between sid and URL / Data / Header) and the loop through these steps and send the corresponding requests to the device. For each step a $sid in a Header or Post Data will be replaced with the current content of <code>$hash->{sid}</code>.

Using this feature, HTTPMOD can perform a forms based authentication and send user name, password or other necessary data to the device and save the session id for further requests.

To determine when this login procedure is necessary, HTTPMOD will first try to send a request without
doing the login procedure. If the result contains an error that authentication is necessary, then a login is performed.
To detect such an error in the HTTP response, you can again use a regular expression, JSON or XPath, this time with the attributes

* <code>reAuthRegex</code>
* <code>reAuthJSON</code>
* <code>reAuthXPath</code>
* <code>reAuthXPath-Strict</code>
* <code>(get|set)[0-9]*ReAuthRegex</code>
* <code>(get|set)[0-9]*ReAuthJSON</code>
* <code>(get|set)[0-9]*ReAuthXPath</code>
* <code>(get|set)[0-9]*ReAuthXPath-Strict</code>

reAuthJSON or reAuthXPath typically only extract one piece of data from a response.
If the existence of the specified piece of data is sufficent to start a login procedure, then nothing more needs to be defined to detect this situation.
If however the indicator is a status code that contains different values depending on a successful request and a failed request if a new authentication is needed,
then you can combine things like reAuthJSON with reAuthRegex. In this case the regex is only matched to the data extracted by JSON (or XPath).
This way you can easily extract the status code using JSON parsing and then specify the code that means "authentication needed" as a regular expression.

If for one step not all of the URL, Data or Header Attributes are set, then HTTPMOD tries to use a
<code>sidURL</code>, <code>sidData.*</code> or <code>sidHeader.*</code> Attribute (without the step number after sid). This way parts that are the same for all steps don't need to be defined redundantly.

=== Example for a multi step login procedure: ===
<syntaxhighlight lang="perl">
attr PM reAuthRegex /html/dummy_login.htm
attr PM sidURL http://192.168.70.90/cgi-bin/webgui.fcgi?sid=$sid
attr PM sidHeader1 Content-Type: application/json
attr PM sid1IDRegex wui.init\('([^']+)'
attr PM sid2Data {"set" :{"9.17401.user" :"fhem" ,"9.17401.pass" :"password" }}
attr PM sid3Data {"set" :{"35.5062.value" :"128" }}
attr PM sid4Data {"set" :{"42.8026.code" :"pincode" }}
</syntaxhighlight>

In this case HTTPMOD detects that a login is necessary by looking for the pattern /html/dummy_login.htm in the HTTP response.
If it matches, it starts a login sequence. In the above example all steps request the same URL. In step 1 only the defined Header is sent in an HTTP get request. The response will contain a session id that is extraced with the regex wui.init\('([^']+)'.

In the next step this session id is sent in a post request to the same URL where tha post data contains a username and password. The a third and a fourth request follow that set a value and a code. The result will be a valid and authorized session id that can be used in other requests where $sid is part of a URL, header or post data and will be replaced with the session id extracted above.

===Another Practical Example reading the SOC from a Renault Zoe===
<syntaxhighlight lang="perl">
define myZoe HTTPMOD https://www.services.renault-ze.com/api/vehicle/VINVINVIN/battery 7000
attr myZoe userattr reading01JSON reading01Name reading02JSON reading02Name reading03JSON reading03Nam\
e reading04JSON reading04Name reading05JSON reading05Name requestHeader02 sid1Data sid1Header01 sid1Id\
JSON sid1IgnoreRedirects:0,1 sid1URL
attr myZoe reAuthJSON message
attr myZoe reading01JSON charge_level
attr myZoe reading01Name SOC
attr myZoe reading02JSON charging
attr myZoe reading02Name charging
attr myZoe reading03JSON plugged
attr myZoe reading03Name plugged
attr myZoe reading04JSON remaining_range
attr myZoe reading04Name remaining_range
attr myZoe reading05JSON last_update
attr myZoe reading05Name last_update
attr myZoe requestHeader02 Authorization: Bearer $sid
attr myZoe sid1Data {"username":"ZEUSERNAME","password":"ZEPASSWORD"}
attr myZoe sid1Header01 Content-Type: application/json
attr myZoe sid1IdJSON token
attr myZoe sid1IgnoreRedirects 1
attr myZoe sid1URL https://www.services.renault-ze.com/api/user/login
attr myZoe timeout 10
#attr myZoe verbose 7
</syntaxhighlight>

The $sid is read by logging in with username and password from JSON {"token": ..} after detecting an error {"message": ..} from a failed request. This example offers no solution for the reading of the VIN from the login request, which in turn is part of the reading URL. It should be possible to read more than just the $sid from the login sequence.

In the special case where a session id is set as a HTTP-Cookie (with the header Set-cookie: in the HTTP response) HTTPMOD offers an even simpler way. With the attribute enableCookies a very basic cookie handling mechanism is activated that stores all cookies that the server sends to the HTTPMOD device and puts them back as cookie headers in the following requests.

For such cases no sidIdRegex and no $sid in a user defined header is necessary.

== Advanced configuration to define a <code>get</code> and request additional data with its own request from a device ==

The normal automatic HTTP request that is done repeatedly after the defined interval has elapsed works well in cases where all required readings can be requested in one common HTTP request. If however a device needs individual requests with different URLs or different POST data for each value, then another method is necessary.
For such cases a <code>get</code> option can be defined and the user can either issue FHEM <code>get</code> commands each time he needs the reading or the user can set an attribute to request the reading automatically together with the normal iteration.
For each <code>get</code> option attributes define an individual URL, optional headers, and post data as well as individual regular expressions and formatting options.

When a get option is defined by attributes, the module allows querying additional values from the device that require individual HTTP-Requests or special parameters to be sent

Extension to the above example:

<syntaxhighlight lang="perl">
attr PM get01Name MyGetValue
attr PM get01URL http://MyPoolManager/cgi-bin/directory/webgui.fcgi?special=1?sid=$sid
attr PM getHeader1 Content-Type: application/json
attr PM get01Data {"get" :{"30.1234.value"}}
</syntaxhighlight>

This example defines a get option with the name MyGetValue.
By issuing <code>get PM MyGetValue</code> in FHEM, the defined HTTP request is sent to the device.
The HTTP response is then parsed using the same readingXXName and readingXXRegex attributes as above so
additional pairs will probably be needed there for additional values.

if you prefer to define the parsing and formatting of readings individually per get command, you can use
attributes like get01Regex, get01XPath, get01Format, get01OMap and so on just like for reading01...

You can also include parameters / values that are passed to the get command in the request just like for set commands.
The placeholder $val will be replaced with the value given to the get command or you can specify your own replacement as described above.

If the new get parameter should also be queried regularly, you can define the following optional attributes:

<syntaxhighlight lang="perl">
attr PM get01Poll 1
attr PM get01PollDelay 300
</syntaxhighlight>

The first attribute includes this reading in the automatic update cycle and the second defines an alternative lower update frequency. When the interval defined initially in the define is over and the normal readings are read from the device, the update function will check for additional get parameters that should be included in the update cycle.

If a PollDelay is specified for a get parameter, the update function also checks if the time passed since it has last read this value is more than the given PollDelay. If not, this reading is skipped and it will be rechecked in the next cycle when interval is over again. So the effective PollDelay will always be a multiple of the interval specified in the initial define.

Please note that each defined get command that is included in the regular update cycle will create its own HTTP request. So if you want to extract several values from the same request, it is much more efficient to do this by defining readingXXName and readingXXRegex, XPath or JSON attributes and to specify an interval and a URL in the define of the HTTPMOD device.

Example for a Siemens webserver provided by Lanhydrock:
<syntaxhighlight lang="perl">
define ozw672 HTTPMOD https://192.168.178.8/api/auth/login.json?user=test&pwd=test 300

attr ozw672 get1Name tempAussen
attr ozw672 get1URL https://192.168.178.8/api/menutree/read_datapoint.json?SessionId=$sid&Id=1960
attr ozw672 get1Poll 1
attr ozw672 get1PollDelay 1800

attr ozw672 get2Name tempAussenGemischt
attr ozw672 get2URL https://192.168.178.8/api/menutree/read_datapoint.json?SessionId=$sid&Id=1964
attr ozw672 get2Poll 1
attr ozw672 get2PollDelay 1800

attr ozw672 get3Name tempTWW
attr ozw672 get3URL https://192.168.178.8/api/menutree/read_datapoint.json?SessionId=$sid&Id=1996
attr ozw672 get3Poll 1

attr ozw672 get4Name tempKesselSoll
attr ozw672 get4URL https://192.168.178.8/api/menutree/read_datapoint.json?SessionId=$sid&Id=1910
attr ozw672 get4Poll 1

attr ozw672 get5Name tempKesselRuecklauf
attr ozw672 get5URL https://192.168.178.8/api/menutree/read_datapoint.json?SessionId=$sid&Id=1915
attr ozw672 get5Poll 1

attr ozw672 get6Name tempKesselRuecklaufSoll
attr ozw672 get6URL https://192.168.178.8/api/menutree/read_datapoint.json?SessionId=$sid&Id=1916
attr ozw672 get6Poll 1

attr ozw672 get7Name anzahlStartsBrenner
attr ozw672 get7URL https://192.168.178.8/api/menutree/read_datapoint.json?SessionId=$sid&Id=1927
attr ozw672 get7PollDelay 1800
attr ozw672 get7Poll 1

attr ozw672 get8Name statusKessel
attr ozw672 get8URL https://192.168.178.8/api/menutree/read_datapoint.json?SessionId=$sid&Id=1898
attr ozw672 get8Poll 1
attr ozw672 get8Regex Value": "([a-zA-Zü ]*)"
attr ozw672 get8OMap Aus:0, Nachlauf aktiv:5, Freigegeben für TWW:10, Freigegeben für HK:20, In Teillastbetrieb für TWW:40, In Teillastbetrieb für HK:50, In Betrieb für Trinkwasser:90, In Betrieb für Heizkreis:100

attr ozw672 getRegex Value": "[ ]*([-.0-9]*)"

attr ozw672 reAuthRegex .*session not valid.*
attr ozw672 sid1IDRegex .*"(.*-.*-.*-[0-9a-z]*).*
attr ozw672 sid1URL https://192.168.178.8/api/auth/login.json?user=test&pwd=test
</syntaxhighlight>

== All attributes ==
;reading[0-9]+Name
:the name of a reading to extract with the corresponding readingRegex, readingJSON, readingXPath or readingXPath-Strict
:Please note that the old syntax <b>readingsName.*</b> does not work with all features of HTTPMOD and should be avoided. It might go away in a future version of HTTPMOD.

;(get|set)[0-9]+Name
:Name of a get or set command
:If the HTTP response that is received after the command is parsed with an individual parse option then this name is also used as a reading name. Please note that no individual parsing needs to be defined for a get or set. If no regex, XPath or JSON is specified for the command, then HTTPMOD will try to parse the response using all the defined readingRegex, reading XPath or readingJSON attributes.

;(get|set|reading)[0-9]+Regex
:If this attribute is specified, the Regex defined here is used to extract the value from the HTTP Response and assign it to a Reading with the name defined in the (get|set|reading)[0-9]+Name attribute.
:If this attribute is not specified for an individual Reading or get or set but without the numbers in the middle, e.g. as getRegex or readingRegex, then it applies to all the other readings / get / set commands where no specific Regex is defined.<br>
:The value to extract should be in a capture group / sub expression e.g. ([\d\.]+) in the above example. Multiple capture groups will create multiple readings (see explanation above)
:Using this attribute for a set command (setXXRegex) only makes sense if you want to parse the HTTP response to the HTTP request that the set command sent by defining the attribute setXXParseResponse.
:Please note that the old syntax <code>readingsRegex.*</code> does not work with all features of HTTPMOD and should be avoided. It might go away in a future version of HTTPMOD.
:If for get or set commands neither a generic Regex attribute without numbers nor a specific (get|set)[0-9]+Regex attribute is specified and also no XPath or JSON parsing specification is given for the get or set command, then HTTPMOD tries to use the parsing definitions for general readings defined in reading[0-9]+Name, reading[0-9]+Regex or XPath or JSON attributes and assigns the Readings that match here.

;(get|set|reading)[0-9]+RegOpt
:Lets the user specify regular expression modifiers. For example if the same regular expression should be matched as often as possible in the HTTP response, then you can specify RegOpt g which will case the matching to be done as /regex/g
:The results will be trated the same way as multiple capture groups so the reading name will be extended with -number.
:For other possible regular expression modifiers see http://perldoc.perl.org/perlre.html#Modifiers

;(get|set|reading)[0-9]+XPath
:defines an xpath to one or more values when parsing HTML data (see examples above)
:Using this attribute for a set command only makes sense if you want to parse the HTTP response to the HTTP request that the set command sent by defining the attribute setXXParseResponse.

;get|set|reading[0-9]+XPath-Strict
:defines an xpath to one or more values when parsing XML data (see examples above)
:Using this attribute for a set command only makes sense if you want to parse the HTTP response to the HTTP request that the set command sent by defining the attribute setXXParseResponse.

;(get|set|reading)[0-9]+AutoNumLen
:In cases where a regular expression or an XPath results in multiple results and these results are stored in a common reading name with extension -number, then you can modify the format of this number to have a fixed length with leading zeros. AutoNumLen 3 for example will lead to reading names ending with -001 -002 and so on.

;(get|set|reading)[0-9]+AlwaysNum
:if set to 1 this attributes forces reading names to end with a -1, -01 (depending on the above described AutoNumLen) even if just one value is parsed.

;get|set|reading[0-9]+JSON
:defines a path to the JSON object wanted by concatenating the object names. See the above example.
:If you don't know the paths, then start by using extractAllJSON and the use the names of the readings as values for the JSON attribute.<br>
:Please don't forget to also specify a name for a reading, get or set.
:Using this attribute for a set command only makes sense if you want to parse the HTTP response to the HTTP request that the set command sent by defining the attribute setXXParseResponse.

;(get|set|reading)[0-9]*RecombineExpr
:defines an expression that is used in an eval to compute one reading value out of the list of matches.
:This is supposed to be used for regexes or xpath specifications that produce multiple results if only one result that combines them is wanted. The list of matches will be in the variable @matchlist.
:Using this attribute for a set command only makes sense if you want to parse the HTTP response to the HTTP request that the set command sent by defining the attribute setXXParseResponse.

;get[0-9]*CheckAllReadings
:this attribute modifies the behavior of HTTPMOD when the HTTP Response of a get command is parsed. <br>
:If this attribute is set to 1, then additionally to the matching of the corresponding get specific regex (get[0-9]*Regex), XPath or JSON attribute also all the reading names and parse definitions defined in Reading[0-9]+Name and Reading[0-9]+Regex, XPath or JSON attributes are checked and if they match, the coresponding Readings are assigned as well.
:Please note that this does not mean that get01CheckAllReadings will cause a get02Regex to be used. Only the corresponding get01Regex will be used but additionally all the readingXYRegex attributes.
:This is automatically done if a get or set command is defined without its own parse attributes.

;(get|reading)[0-9]*OExpr
:defines an optional expression that is used in an eval to compute / format a readings value after parsing an HTTP response
:The raw value from the parsing will be in the variable $val.
:If specified as readingOExpr then the attribute value is a default for all other readings that don't specify an explicit reading[0-9]*Expr.
:Please note that the old syntax <b>readingsExpr.*</b> does not work with all features of HTTPMOD and should be avoided. It might go away in a future version of HTTPMOD.

;(get|reading)[0-9]*Expr
:This is the old syntax for (get|reading)[0-9]*OExpr. It should be replaced by (get|reading)[0-9]*OExpr. The set command upgradeAttributes which becomes visible when the attribute enableControlSet is set to 1, can do this renaming automatically.

;(get|reading)[0-9]*OMap
:Map that defines a mapping from raw value parsed to visible values like "0:mittig, 1:oberhalb, 2:unterhalb".
:If specified as readingOMap then the attribute value is a default for all other readings that don't specify an explicit reading[0-9]*Map.<br>
:The individual options in a map are separated by a komma and an optional space. Spaces are allowed to appear in a visible value however kommas are not possible.

;(get|reading)[0-9]*Map
:This is the old syntax for (get|reading)[0-9]*OMap. It should be replaced by (get|reading)[0-9]*OMap. The set command upgradeAttributes which becomes visible when the attribute enableControlSet is set to 1, can do this renaming automatically.

;(get|set|reading)[0-9]*Format
:Defines a format string that will be used in sprintf to format a reading value.
:If specified without the numbers in the middle e.g. as readingFormat then the attribute value is a default for all other readings that don't specify an explicit reading[0-9]*Format.
:Using this attribute for a set command only makes sense if you want to parse the HTTP response to the HTTP request that the set command sent by defining the attribute setXXParseResponse.<br>

;(get|set|reading)[0-9]*Decode
:defines an encoding to be used in a call to the perl function decode to convert the raw data string read from the device to a reading.
:This can be used if the device delivers strings in an encoding like cp850 instead of utf8.
:If your reading values contain Umlauts and they are shown as strange looking icons then you probably need to use this feature.
:Using this attribute for a set command only makes sense if you want to parse the HTTP response to the HTTP request that the set command sent by defining the attribute setXXParseResponse.

;(get|set|reading)[0-9]*Encode
:defines an encoding to be used in a call to the perl function encode to convert the raw data string read from the device to a reading.
:This can be used if the device delivers strings in an encoding like cp850 and after decoding it you want to reencode it to e.g. utf8.
:If your reading values contain Umlauts and they are shown as strange looking icons then you probably need to use this feature.
:Using this attribute for a set command only makes sense if you want to parse the HTTP response to the HTTP request that the set command sent by defining the attribute setXXParseResponse.

;(get|set)[0-9]*URL
:URL to be requested for the set or get command. If this option is missing, the URL specified during define will be used.

;(get|set)[0-9]*Data
:Data to be sent to the device as POST data when the get or set command is executed. if this attribute is not specified, an HTTP GET method will be used instead of an HTTP POST

;(get|set)[0-9]*NoData
:can be used to override a more generic attribute that specifies POST data for all get or set commands. With NoData no data is sent and therefor the request will be an HTTP GET.

;(get|set)[0-9]*Header.*
:HTTP Headers to be sent to the device when the set is executed

;requestHeader.*
:Define an optional additional HTTP Header to set in the HTTP request of the main loop

;requestData
:optional POST Data to be sent in the request of the main loop. If not defined, it will be an HTTP GET request as defined in HttpUtils which is used by this module

;get[0-9]+Poll
:if set to 1 the get is executed automatically during the normal update cycle (after the interval provided in the define command has elapsed)

;get[0-9]+PollDelay
:if the value should not be read in each iteration (after the interval given to the define command), then a minimum delay can be specified with this attribute. This has only an effect if the above Poll attribute has also been set. Every time the update function is called, it checks if since this get has been read the last time, the defined delay has elapsed. If not, then it is skipped this time.
:PollDelay can be specified as seconds or as x[0-9]+ which means a multiple of the interval in the define command.

;(get|set)[0-9]*TextArg
:For a get command this defines that the command accepts a text value after the option name. By default a get command doesn't accept optional values after the command name.
:If TextArg is specified and a value is passed after the get name then this value can then be used in a request URL, header or data as replacement for $val or in a user defined replacement that uses the internal "value" ($hash->{value}).
:If used for a set command then it defines that the value to be set doesn't require any validation / conversion.
:The raw value is passed on as text to the device. By default a set command expects a numerical value or a text value that is converted to a numeric value using a map.

;set[0-9]+Min
:Minimum value for input validation.

;set[0-9]+Max
:Maximum value for input validation.

;set[0-9]+IExpr
:Perl Expression to compute the raw value to be sent to the device from the input value passed to the set.

;set[0-9]+Expr
:This is the old syntax for (get|reading)[0-9]*IExpr. It should be replaced by (get|reading)[0-9]*IExpr. The set command upgradeAttributes which becomes visible when the attribute enableControlSet is set to 1, can do this renaming automatically.

;set[0-9]+IMap
:Map that defines a mapping from raw to input values like "0:mittig, 1:oberhalb, 2:unterhalb". This attribute atomatically creates a hint for FHEMWEB so the user can choose one of the input values.

;set[0-9]+Map
:This is the old syntax for (get|reading)[0-9]*IMap. It should be replaced by (get|reading)[0-9]*IMap. The set command upgradeAttributes which becomes visible when the attribute enableControlSet is set to 1, can do this renaming automatically.

;set[0-9]+Hint
:Explicit hint for fhemWEB that will be returned when set ? is seen. Can be used to get a slider or a list of values to choose from.

;set[0-9]*NoArg
:Defines that this set option doesn't require arguments. It allows sets like "on" or "off" without further values.

;set[0-9]*ParseResponse
:defines that the HTTP response to the set will be parsed as if it was the response to a get command.

;(get|set)[0-9]*URLExpr
:Defines a Perl expression to specify the HTTP Headers for this request. This overwrites any other header specification and should be used carefully only if needed. The original Header is availabe as $old. Typically this feature is not needed and it might go away in future versions of HTTPMOD. Please use the "replacement" attributes if you want to pass additional variable data to a web service.

;(get|set)[0-9]*DatExpr
:Defines a Perl expression to specify the HTTP Post data for this request. This overwrites any other post data specification and should be used carefully only if needed. The original Data is availabe as $old. Typically this feature is not needed and it might go away in future versions of HTTPMOD. Please use the "replacement" attributes if you want to pass additional variable data to a web service.

;(get|set)[0-9]*HdrExpr
:Defines a Perl expression to specify the URL for this request. This overwrites any other URL specification and should be used carefully only if needed. The original URL is availabe as $old. Typically this feature is not needed and it might go away in future versions of HTTPMOD. Please use the "replacement" attributes if you want to pass additional variable data to a web service.

;ReAuthRegex
:regular Expression to match an error page indicating that a session has expired and a new authentication for read access needs to be done.
:This attribute only makes sense if you need a forms based authentication for reading data and if you specify a multi step login procedure based on the sid.. attributes.
:This attribute is used for all requests. For set and get operations you can however specify individual reAuthRegexes with the (get|set)[0-9]*ReAuthRegex attributes.

;(get|set)[0-9]*ReAuthRegex
:Regex that will detect when a session has expired during a set operation and a new login needs to be performed.
:It works like the global reAuthRegex but is used for set operations.

;sid[0-9]*URL
:different URLs or one common URL to be used for each step of an optional login procedure.

;sid[0-9]*IDRegex
:different Regexes per login procedure step or one common Regex for all steps to extract the session ID from the HTTP response

;sid[0-9]*Data.*
:data part for each step to be sent as POST data to the corresponding URL

;sid[0-9]*Header.*
:HTTP Headers to be sent to the URL for the corresponding step

;sid[0-9]*IgnoreRedirects
:Tells the HttpUtils to not follow HTTP Redirects for this Request. Might be needed for some devices that set a session cookie within a 303 Redirect.

;clearSIdBeforeAuth
:will set the session id to "" before doing the authentication steps

;authRetries
:number of retries for authentication procedure - defaults to 1

;replacement[0-9]*Regex
:Defines a replacement to be applied to an HTTP request header, data or URL before it is sent. This allows any part of the request to be modified based on a reading, an internal or an expression.
:The regex defines which part of a header, data or URL should be replaced. The replacement is defined with the following attributes:

;replacement[0-9]*Mode
:Defines how the replacement should be done and what replacementValue means. Valid options are text, reading, internal and expression.

;replacement[0-9]*Value
:Defines the replacement. If the corresponding replacementMode is <code>text</code>, then value is a static text that is used as the replacement.
:If replacementMode is <code>reading</code> then Value can be the name of a reading of this device or it can be a reading of a different device referred to by devicename:reading.
:If replacementMode is <code>internal</code> the Value can be the name of an internal of this device or it can be an internal of a different device referred to by devicename:internal.
:If replacementMode is <code>expression</code> the the Value is treated as a Perl expression that computes the replacement value. The expression can use $1, $2 and so on to refer to capture groups of the corresponding regex that is matched against the original URL, header or post data.
:If replacementMode is <code>key</code> then the module will use a value from a key / value pair that is stored in an obfuscated form in the file system with the set storeKeyValue command. This might be useful for storing passwords.

;[gs]et[0-9]*Replacement[0-9]*Value
:This attribute can be used to override the replacement value for a specific get or set.

;get|reading[0-9]*MaxAge
:Defines how long a reading is valid before it is automatically overwritten with a replacement when the read function is called the next time.

;get|reading[0-9]*MaxAgeReplacement
:specifies the replacement for MaxAge - either as a static text or as a perl expression.

;get|reading[0-9]*MaxAgeReplacementMode
:specifies how the replacement is interpreted: can be text, expression and delete.

;get|reading[0-9]*DeleteIfUnmatched
:If set to 1 this attribute causes certain readings to be deleted when the parsing of the website does not match the specified reading. Internally HTTPMOD remembers which kind of operation created a reading (update, Get01, Get02 and so on). Specified readings will only be deleted if the same operation does not parse this reading again. This is especially useful for parsing that creates several matches / readings and the number of matches can vary from request to request. For example if reading01Regex creates 4 readings in one update cycle and in the next cycle it only matches two times then the readings containing the remaining values from the last round will be deleted.
:Please note that this mechanism will not work in all cases after a restart. Especially when a get definition does not contain its own parsing definition but ExtractAllJSON or relies on HTTPMOD to use all defined reading.* attributes to parse the responsee to a get command, old readings might not be deleted after a restart of fhem.
;get|reading[0-9]*DeleteOnError
:If set to 1 this attribute causes certain readings to be deleted when the website can not be reached and the HTTP request returns an error. Internally HTTPMOD remembers which kind of operation created a reading (update, Get01, Get02 and so on). Specified readings will only be deleted if the same operation returns an error.
The same restrictions as for DeleteIfUnmatched apply regarding a fhem restart.

;httpVersion
:defines the HTTP-Version to be sent to the server. This defaults to 1.0.

;sslVersion
:defines the SSL Version for the negotiation with the server. The attribute is evaluated by HttpUtils. If it is not specified, HttpUtils assumes SSLv23:!SSLv3:!SSLv2

;sslArgs
:defines a list that is converted to a key / value hash and gets passed to HttpUtils. To avoid certificate validation for broken servers you can for example specify
:<code>attr myDevice sslArgs SSL_verify_mode,SSL_VERIFY_NONE</code>

;alignTime
:Aligns each periodic read request for the defined interval to this base time. This is typcally something like 00:00 (see the FHEM at command)

;noShutdown
:pass the noshutdown flag to HTTPUtils for webservers that need it (some embedded webservers only deliver empty pages otherwise)

;disable
:stop doing automatic HTTP requests while this attribute is set to 1

;enableControlSet
:enables the built in set commands interval, stop, start, reread, upgradeAttributes, storeKeyValue.

;enableCookies
:enables the built in cookie handling if set to 1. With cookie handling each HTTPMOD device will remember cookies that the server sets and send them back to the server in the following requests.
:This simplifies session magamenet in cases where the server uses a session ID in a cookie. In such cases enabling cookies should be sufficient and no sidRegex and no manual definition of a cookie header should be necessary.

;showMatched
:if set to 1 then HTTPMOD will create a reading with the name MATCHED_READINGS that contains the names of all readings that could be matched in the last request as well as UNMATCHED_READINGS and LAST_REQUEST.

;showError
:if set to 1 then HTTPMOD will create a reading and event with the Name LAST_ERROR that contains the error message of the last error returned from HttpUtils.

;removeBuf
:if set to 1 then HTTPMOD removes the internal named buf when a HTTP-response has been received.
:$hash->{buf} is used internally be Fhem httpUtils and in some use cases it is desireable to remove this internal after reception
:because it contains a very long response which looks ugly in Fhemweb.

;timeout
:time in seconds to wait for an answer. Default value is 2

;queueDelay
:HTTP Requests will be sent from a queue in order to avoid blocking when several Requests have to be sent in sequence. This attribute defines the delay between calls to the function that handles the send queue. It defaults to one second.

;queueMax
:Defines the maximum size of the send queue. If it is reached then further HTTP Requests will be dropped and not be added to the queue

;minSendDelay
:Defines the minimum time between two HTTP Requests.

== Links ==
* Example: This example uses many features of HTTPMOD, universally useful is the access to other readings just like what [[Set magic|set-magic]] (<code>[device:reading]</code>) does [https://forum.fhem.de/index.php?topic=135666.0 🎸 Owntone (Musik-Player) mit FHEM steuern]
* Example: [https://www.goingelectric.de/forum/viewtopic.php?f=57&t=21462|Abfrage Akkustand einer Zoe und mehr von Renault ZE Services]
* Example: [[Wetter_und_Wettervorhersagen#Wetter_von_Weather_Underground|Extract weather information from WeatherUnderground]]
* Example: [[Pollenflug|Pollen count]]
* Example: [[HTTPMOD Beispielkonfiguration zur Anbindung einer Daikin Klimaanlage mit WLAN-Modul|Connect Daikin aircondition to FHEM]]
* Example: [[Go-eCharger|Extract information from go-eCharger]]
* Example: [[Sonnenspeicher|Integration of energy supplies from sonnen (https://sonnenbatterie.de/en/start)]]
* Example: [https://forum.fhem.de/index.php/topic,95989.msg915870.html#msg915870 Miele 3rd party API für Miele Smarthome Geräte]
* Example: [https://forum.fhem.de/index.php/topic,84215.msg918662.html#msg918662 Honeywell Evohome Totalconnect]
* Example: [https://forum.fhem.de/index.php/topic,78613.msg889015.html#msg889015 Tigo Energy Integration]
* Example: [https://forum.fhem.de/index.php/topic,78613.msg708518.html#msg708518 Ecowater]
* {{Link2Forum|Topic=17804|LinkText=Thread}} in FHEM Forum that discusses the first version of this module
* {{Link2Forum|Topic=29471|LinkText=Thread}} in FHEM Forum that discusses the second major version of this module
* {{Link2Forum|Topic=45176|LinkText=Thread}} in FHEM Forum that discusses the third major version of this module
* [http://perldoc.perl.org/perlretut.html Introduction to regular expressions]
* [http://portswigger.net/burp/ BurpSuite]: Tool (local proxy) to help analyze http traffic

[[Kategorie:IP Components]]

HTTPMOD

2025-04-05T09:20:51Z

Torxgewinde: /* Some help with Regular Expressions */

{{Infobox Modul
|ModPurpose=Extract information from devices with an HTTP interface (or, more generic, from any URL) or send information to such devices
|ModType=d
|ModCmdRef=HTTPMOD
|ModForumArea=Sonstiges
|ModTechName=98_HTTPMOD.pm
|ModOwner=StefanStrobel ({{Link2FU|3960|Forum}} / [[Benutzer:StefanStrobel|Wiki]])
}}
[[HTTPMOD]] provides a generic way to retrieve information from devices with an HTTP Interface and store them in Readings or send information to such devices. It queries a given URL with Headers and data defined by attributes.

From the HTTP response it extracts readings named in attributes using Regexes, JSON or XPath parsing also defined by attributes.

In an advanced [[Konfiguration|configuration]] the module can also send information to devices. To do this, a generic <code>set</code> option can be configured using attributes.

== Introduction ==
With the help of HTTPMOD you can automatically access websites, retrieve information and send data. In the simplest case, an http call is started regularly and the content of a page, for example, is read and processed further. The URL and the time interval in which the call is to be made must then be specified when the call is made. In order to read information from the called web pages, readings are required. In this readings one specifies Regex, which reads the necessary information. Here is an example.

<syntaxhighlight lang="perl">
define PM HTTPMOD http://www.klack.de/fernsehprogramm/was-laeuft-gerade/0/-1/free.html 20000
</syntaxhighlight>

This creates a device that accesses the http://www.klack.de/fernsehprogramm/was-laeuft-gerade/0/-1/free.html website with the TV program every 20000 seconds. If neither readings nor other attributes are defined, then only the call of the website takes place and FHEM receives no further data from the web access.

But now a television program is returned when you call the website, which you might want to read out. In order to save the contents in FHEM, which are related to the ARD, you need a reading. This reading must contain a name (so that FHEM knows under which name the information is stored) and a regex (so that you know where the information is stored on the website). Since usually not one, but many readings are defined, these readings are numbered consecutively. This is done by numbers that are given immediately after the word reading. In our example this would be for example
<syntaxhighlight lang="perl">
attr PM reading1Name ARD
attr PM reading1Regex <span class="stationName">ARD<\/span>[\w\W]*?<div class="content">\s*<a[\w\W]*?>\s*(.*?)\s*<\/a>
attr PM reading2Name ARD_time
attr PM reading2Regex <span class="stationName">ARD<\/span>[\w\W]*?<td class="time">\s*(.*?)\s*<
attr PM reading3Name ARD_details
attr PM reading3Regex <span class="stationName">ARD<\/span>[\w\W]*?<div class="content">\s*<a[\w\W]*?>[\w\W]*?<\/a>\s*<br\/>\s*(.*?)(<img|<\/div)
</syntaxhighlight>

Reading1 contains the programme, reading2 the time and reading3 further details. The Regex result from the structure of the website and may have to be designed in painstaking detail.

There are cases where this is not enough. For example, it could be the case that the information from the web access is not automated, but manually received. Then a 0 must first be entered at the top of the duration. But how does HTTPMOD then know when the data should be retrieved? This is done with get-commands. If a get-command is executed, HTTPMOD accesses the website, fetches the information and fills the corresponding readings.

Again, it is possible to create not one but several get-commands. Therefore, get is always followed by (at least) one number with which the get commands are numbered. Here is another example. The TV program should be called manually and not time-controlled. To do this we first change the definition to
<syntaxhighlight lang="perl">
define PM HTTPMOD http://www.klack.de/fernsehprogramm/was-laeuft-gerade/0/-1/free.html 0
</syntaxhighlight>
and add the following to the attributes
<syntaxhighlight lang="perl">
attr PM get1Name ARDHolen
</syntaxhighlight>
With the command "get PM ARDHolen" the above readings are filled. In order for FHEM to know that the other reading2, reading3, etc. are to be read as well as reading1, the (user) attribute
<syntaxhighlight lang="perl">
attr PM get1CheckAllReadings 1
</syntaxhighlight>
needs to be defined.

If the URL is not sufficient when the web page is called, but a special header is to be sent with it, this can be done with the get1Header attribute. If the header is multiline, the individual lines can be entered with get1Header1, get1Header2, and so on.

If you want to evaluate or control different URLs, you can define several get commands (get1, get2, etc.) and provide them with your own URLs. get1 usually reads only the reading1, get2 reads only the reading2 and so on. With CheckAllReadings all readings are evaluated simultaneously.

If only data is to be sent on the web page, but not read, the set command is recommended. It has the same structure as the get-command.

It becomes a bit more complex if the website requires a login check. The sid attributes are used for this purpose.

== Availability, prerequisites and definition ==
This module is part of the regular FHEM distribution and uses the non blocking HTTP function <code>HttpUtils_NonblockingGet</code> provided by FHEM's [[HttpUtils]] in a new version published in December 2013.
If not already installed in your environment, please [[update]] FHEM or install it manually using appropriate commands from your environment.
Please also note that FHEM HttpUtils need the global attribute dnsServer to be set in order to work really non blocking even when dns requests can not be answered.

The device is defined as follows
<syntaxhighlight lang="perl">
define <name> HTTPMOD <URL> <Interval>
</syntaxhighlight>
The module connects to the given <code>URL</code> every <code>Interval</code> seconds, sends optional headers and data and then parses the response with regular expressions, xpath or json to set readings.

URL can be "none" and Interval can be 0 if you prefer to only query data with a get command and not in a defined interval.

Example:
<syntaxhighlight lang="perl">
define PM HTTPMOD http://MyPoolManager/cgi-bin/webgui.fcgi 60
</syntaxhighlight>

== Set-Commands ==
can be defined using attributes, see advanced configuration

If you set the attribute enableControlSet to 1, the following additional built in set commands are available:
;interval
:set new interval time in seconds and restart the timer
;reread
:request the defined URL and try to parse it just like the automatic update would do it every Interval seconds without modifying the running timer.
;stop
:stop interval timer.
;start
:restart interval timer to call GetUpdate after interval seconds
;upgradeAttributes
:convert outdated attributes for older HTTPMOD-Versions that are still defined for this device from the old syntax to the new one.
:attributes with the description "this attribute should not be used anymore" or similar will be translated to the new syntax, e.g. readingsName1 to reading01Name.
;storeKeyValue
:stores a key value pair in an obfuscated form in the file system. Such values can then be used in replacements where the mode is "key" e.g. to avoid storing passwords in the configuration in clear text

== Get-Commands ==
can be defined using attributes, see advanced configuration

== simple Attributes ==
;enableControlSet
:enables the built in set commands ''interval'', ''stop'', ''start'', ''reread'', ''upgradeAttributes'', ''storeKeyValue''

;enableCookies
:enables the cookie handling inside HTTPMOD. It is advisable to always set this attribute and allow HTTPMOD to track the state of cookies and set them for following HTTP-requests

;enforceGoodReadingNames
:makes sure that HTTPMOD only creates readings that are allowd for Fhem (especially if reading names are dynamically created from JSON object names with extractAllJSON. It is advisable to always set this attribute.

;handleRedirects
:enables the redirect handling inside HTTPMOD which should be used together with the cookie handling of HTTPMOD. HTTPMOD will then automatically follow redirects from a web server and keep track of cookies at the same time. It is advisable to always set this attribute.

;requestHeader.*
:Define an additional HTTP Header to set in the HTTP request

;requestData
:POST Data to be sent in the request. If not defined, it will be a GET request as defined in HttpUtils used by this module

;reading[0-9]+(-[0-9]+)?Name
:the name of a reading to extract with the corresponding readingRegex

;reading[0-9]*(-[0-9]+)?OExpr
:defines an expression that is used in an eval to compute the readings value. The raw value will be in the variable $val.

;reading[0-9]*(-[0-9]+)?OMap
:Output Map. Defines a mapping from raw to visible values like "0:mittig, 1:oberhalb, 2:unterhalb". If specified as readingOMap then the attribute value is a default for all other readings that don't specify an explicit reading[0-9]*OMap.

;reading[0-9]*(-[0-9]+)?Format
:Defines a format string that will be used in sprintf to format a reading value. If specified as readingFormat then the attribute value is a default for all other readings that don't specify an explicit reading[0-9]*Format.

;reading[0-9]*(-[0-9]+)?Decode
:defines an encoding to be used in a call to the perl function decode to convert the raw data string read from the device to a reading. This can be used if the device delivers strings in an encoding like cp850 instead of utf8.

;reading[0-9]*(-[0-9]+)?Encode
:defines an encoding to be used in a call to the perl function encode to convert the raw data string read from the device to a reading. This can be used if the device delivers strings in an encoding like cp850 and after decoding it you want to reencode it to e.g. utf8.

;reading[0-9]+Regex
:defines the regex to be used for extracting the reading. The value to extract should be in a capture group / sub expression
:e.g. ([\d\.]+) in the above example. Multiple capture groups will create multiple readings (see explanation above)

;reading[0-9]+XPath
:defines an xpath to one or more readings when parsing HTML data (see examples below)

;reading[0-9]+XPath-Strict
:defines an xpath to one or more readings when parsing XML data (see examples below)

;reading[0-9]+JSON
:defines a path to the JSON object wanted by concatenating the object names with an underscore as delimiter (see the example below)

;noShutdown
:pass the noshutdown flag to HTTPUtils for webservers that need it (some embedded webservers only deliver empty pages otherwise)

;disable
:stop doing automatic HTTP requests while this attribute is set to 1

;timeout
:time in seconds to wait for an answer. Default value is 2

;do_not_notify

;readingFnAttributes

== Simple Configuration of HTTP Devices ==
If your device expects special HTTP-headers then specify them as <code>attr requestHeader1</code> to <code>attr requestHeaderX</code>.
If your Device expects an HTTP POST instead of HTTP GET then the POST-data can be specified as <code>attr requestData</code>.
To get the readings, specify pairs of <code>attr readingXName</code> and <code>attr readingXRegex</code>, <code>attr readingXXPath</code>, <code>attr readingXXPath-Strict</code> or <code>attr readingXJSON</code> to define which readings you want to extract from the HTTP response and how to extract them. (The old syntax <code>attr readingsNameX</code> and <code>attr readingsRegexX</code> is still supported but the new one with <code>attr readingXName</code> and <code>attr readingXRegex</code> should be preferred. The actual values to be extracted have to be sub expressions within () in the regex (see example below)

=== Example for a PoolManager 5: ===
The PoolManager Web GUI can be queried with HTTP POST Requests like this one:

<syntaxhighlight lang="perl">
POST /cgi-bin/webgui.fcgi HTTP/1.1
Host: 192.168.70.90
Accept: */*
Content-Type: application/json;charset=UTF-8
Content-Length: 60

{"get" :["34.4001.value" ,"34.4008.value" ,"34.4033.value"]}
</syntaxhighlight>

The resulting HTTP Response would look like this:

<syntaxhighlight lang="perl">
HTTP/1.1 200 OK
Content-type: application/json; charset=UTF-8
Expires: 0
Cache-Control: no-cache
Date: Sun, 12 Jan 2014 12:23:11 GMT
Server: lighttpd/1.4.26
Content-Length: 179

{
"data": {
"34.4001.value": "7.00",
"34.4008.value": "0.52",
"34.4033.value": "24.8"
},
"status": {
"code": 0
},
"event": {
"type": 1,
"data": "48.30000.0"
}
}
</syntaxhighlight>

To configure HTTPMOD for a PoolManager one would first define a PoolManager device with e.g. the name PM, the URL and an interval of e.g. 60 seconds.

Then the data to be sent in the request needs to be defined because in this example the device expects a POST request so the query is not contained in the URL but in the request data.

Also as seen above the device expects special HTTP headers in the request so these headers also need to be defined as <code>attr PM requestHeader1</code> and <code>attr PM requestHeader2</code>

Then the names of the readings to be extracted would be set with attributes

Then for each reading value to be extracted a regular expression needs to be set that will match the value in question within ().

Example:
<syntaxhighlight lang="perl">
define PM HTTPMOD http://MyPoolManager/cgi-bin/webgui.fcgi 60

attr PM enableControlSet 1
attr PM enableCookies 1
attr PM enforceGoodReadingNames 1
attr PM handleRedirects 1

attr PM reading01Name PH
attr PM reading01Regex 34.4001.value":[ \t]+"([\d\.]+)"

attr PM reading02Name CL
attr PM reading02Regex 34.4008.value":[ \t]+"([\d\.]+)"

attr PM reading03Name3TEMP
attr PM reading03Regex 34.4033.value":[ \t]+"([\d\.]+)"

attr PM requestData {"get" :["34.4001.value" ,"34.4008.value" ,"34.4033.value", "14.16601.value", "14.16602.value"]}
attr PM requestHeader1 Content-Type: application/json
attr PM requestHeader2 Accept: */*
attr PM stateFormat {sprintf("%.1f Grad, PH %.1f, %.1f mg/l Chlor", ReadingsVal($name,"TEMP",0), ReadingsVal($name,"PH",0), ReadingsVal($name,"CL",0))}
</syntaxhighlight>

=== Example for AmbientMonitor ===
AmbientMonitor is a webbased visualisation for sensors connected to an Arduino device. Its web interface can also be queried with HTTMOD to grab the data into readings.

This example was provided by locutus. The hardware configuration is an Arduino + Ethercard with ENC28J60 Controller + DHT22 Sensor and software can be downloaded from https://github.com/lucadentella/AmbientMonitor

In this example an HTTP GET is sufficent, so no <code>requestData</code> is needed. The device provides temperature and humidity readings in an HTTP response that looks like:
<syntaxhighlight lang="perl">
HTTP/1.0 200 OK
Content-Type: text/html

myCB({'temperature':22.00,'humidity':46.00})
</syntaxhighlight>

the definition could be:
<syntaxhighlight lang="perl">
define AmbientMonitor HTTPMOD http://192.168.1.221/?callback=? 300

attr AmbientMonitor enableControlSet 1
attr AmbientMonitor enableCookies 1
attr AmbientMonitor enforceGoodReadingNames 1
attr AmbientMonitor handleRedirects 1

attr AmbientMonitor requestHeader Content-Type: application/json
attr AmbientMonitor reading1Name Temperatur
attr AmbientMonitor reading1Regex temperature':([\d\.]+)
attr AmbientMonitor reading2Name Feuchtigkeit
attr AmbientMonitor reading2Regex humidity':([\d\.]+)
attr AmbientMonitor stateFormat {sprintf("Temperatur %.1f C, Feuchtigkeit %.1f %", ReadingsVal($name,"Temperatur",0), ReadingsVal($name,"Feuchtigkeit",0))}
</syntaxhighlight>

== formatting and manipulating values / readings ==
Values that are parsed from an HTTP response can be further treated or formatted with the following attributes:

* <code>(reading|get)[0-9]*(-[0-9]+)?OExpr</code>
* <code>(reading|get)[0-9]*(-[0-9]+)?OMap</code>
* <code>(reading|get)[0-9]*(-[0-9]+)?Format</code>
* <code>(reading|get)[0-9]*(-[0-9]+)?Decode</code>
* <code>(reading|get)[0-9]*(-[0-9]+)?Encode</code>

They can all be specified for an individual reading, for all readings in one match (e.g. if a regular expression has several capture groups) or for all readings in a get command (defined by getXX) or for all readings in the main reading list (defined by readingXX):
<syntaxhighlight lang="perl">
reading01Format %.1f
</syntaxhighlight>

will format the reading with the name specified by the attribute reading01Name to be numerical with one digit after the decimal point.
If the attribute reading01Regex is used and contains several capture groups then the format will be applied to all readings parsed by this regex unless these readings have their own format specified by reading01-1Format, reading01-2Format and so on.

<syntaxhighlight lang="perl">
reading01-2Format %.1f
</syntaxhighlight>

Can be used in cases where a regular expression specified as reading01regex contains several capture groups or an xpath specified as reading01XPath creates several readings.
In this case reading01-2Format specifies the format to be applied to the second match.

<syntaxhighlight lang="perl">
readingFormat %.1f
</syntaxhighlight>

applies to all readings defined by a reading-Attribute that have no more specific format.

If you need to do some calculation on a raw value before it is used as a reading, you can define the attribute <code>readingOExpr</code>.
It defines a Perl expression that is used in an eval to compute the readings value. The raw value will be in the variable $val.

Example for an expression:
<syntaxhighlight lang="perl">
attr PM reading03OExpr $val * 10
</syntaxhighlight>
Just like in the above example of the readingFormat attributes, readingOExpr and the other following attributes can be applied on several levels.

To map a numerical value to a name, you can use the readingOMap attribute.
It defines a mapping from raw to visible values like "0:mittig, 1:oberhalb, 2:unterhalb".

Example for a map:
<syntaxhighlight lang="perl">
attr PM reading02-3OMap 0:kalt, 1:warm, 2:sehr warm
</syntaxhighlight>

To convert character sets, the module can first decode a string read from the device and then encode it again. For example:
<syntaxhighlight lang="perl">
attr PM getDecode UTF-8
</syntaxhighlight>

This applies to all readings defined for Get-Commands.

== Some help with Regular Expressions ==
{{Randnotiz|RNTyp=y|RNText=Starting with version ''2018-02-10'' the internal that holds the HTTP response is no longer called '''''buf''''' but rather '''''httpbody''''', and it is only displayed when attribute '''''showBody''''' is set to "1".}}
If HTTPMOD seems not to work and the FHEM Logfile contains a message like
:<code>HTTPMOD: Response didn't match Reading ...</code>
then you should check if the value you want to extract is read into the internal with the name buf. Internals are visible when you click on the defined HTTPMOD Device. buf is an internal variable that contains the HTTP Response read. If the value is there and you get the mentioned message then probably something is wrong with your regular expression. Please note that buf might contain special characters like newlines but they are not shown in fhemweb. If you are new to regular expressions then the introduction at http://perldoc.perl.org/perlretut.html might be helpful.

For a typical HTTPMOD use case where you want to extract a number out of a HTTP-Response you can use something like <code>[\d\.]+</code> to match the number itself. The expression matches the number characters (<code>\d</code>) or a <code>.</code> if one of these characters occurs at least once.

To tell HTTPMOD that the number is what you want to use for the reading, you have to put the expression in between <code>()</code>. A <code>([\d\.]+)</code> alone would match the longest number in the HTTP Response which is very likely not the number you are looking for so you need to add something to the expression to give it a context and define how to find the number that you are looking for.

If there is a title text before the number or a special text after the number you can put this in the regex. In one of the examples above <code>humidity':([\d\.]+)</code> is looking for the number that immediately follows the text <code>humidity':</code> without any blanks in between.
Be careful if the text you are getting from your device contains special characters like newline. You don't see such special characters in the fhem webinterface as contents of the internal buf but they might cause your regular expression to fail.

If you have trouble defining a regular expression that matches a certain name, then many complicated characters and then a number, it might be helpful to use a negation in matching like <code>temp[^\d]+([\d\.]).*</code>. In this examle <code>[^\d]+</code> means any character that is not a numerical digit, more than once.

=== Regular Expressions with multiple capture Groups ===
The regular expressions used in the above example for a Poolmanager will take the value that matches one capture group. This is the part of the regular expression inside (). In the above example "([\d\.]+)" refers to numerical digits or points between double quotation marks. Only the string consiting of digits and points will match inside (). This piece is assigned to the reading.

You can also use regular expressions that have several capture groups which might be helpful when parsing tables. In this case an attribute like

<syntaxhighlight lang="perl">
reading02Regex something[ \t]+([\d\.]+)[ \t]+([\d\.]+)
</syntaxhighlight>

could match two numbers. When you specify only one reading02Name like
<syntaxhighlight lang="perl">
reading02Name Temp
</syntaxhighlight>

the name Temp will be used with the extension -1 and -2 thus giving a reading Temp-1 for the first number and Temp-2 for the second. You can also specify individual names for several readings that get parsed from one regular expression with several capture groups by defining attributes

<syntaxhighlight lang="perl">
reading02-1Name
reading02-2Name
...
</syntaxhighlight>
The same notation can be used for formatting attributes like readingXOMap, readingXFormat and so on.

The usual way to define readings is however to have an individual regular expression with just one capture group per reading as shown in the above example.

=== Example: set-magic in HTTPMOD ===
To achieve the same just like [[set magic]] the following can be added to a HTTPMOD device:<syntaxhighlight lang="perl">
attr Owntone.device replacement02Mode expression
attr Owntone.device replacement02Regex \[([^:]+):([^\]]+)\]
attr Owntone.device replacement02Value my $device = $name if ($1 eq "\$name") // $1;;\
ReadingsVal($device, $2, undef) or AttrVal($device, $2, "???");;
</syntaxhighlight>With that definition you can just write <code>[$name:state]</code> to get the state-reading of your own HTTPMOD device there. It also accepts other devicenames and first searches for a reading and if no reading is found it searches for an attrbibute with a matching name. This neat trick is used throughout in the Owntone-HTTPMOD-device (see links section below) to keep it easily adoptable to different server names without editing many places in the listing.

== Parsing JSON ==

If a webservice delivers data in JSON format, HTTPMOD can directly parse JSON which might be easier in this case than definig regular expressions.
The next example shows the data that can be requested from a Poolmanager with the following partial configuration:

<syntaxhighlight lang="perl">
define test2 HTTPMOD none 0
attr test2 get01Name Chlor
attr test2 getURL http://192.168.70.90/cgi-bin/webgui.fcgi
attr test2 getHeader1 Content-Type: application/json
attr test2 getHeader2 Accept: */*
attr test2 getData {"get" :["34.4008.value"]}
</syntaxhighlight>

The data in the HTTP response looks like this:

<syntaxhighlight lang="perl">
{
"data": {
"34.4008.value": "0.25"
},
"status": {
"code": 0
},
"event": {
"type": 1,
"data": "48.30000.0"
}
}
</syntaxhighlight>

the classic way to extract the value 0.25 into a reading with the name Chlor with a regex would have been
<syntaxhighlight lang="perl">
attr test2 get01Regex 34.4008.value":[ \t]+"([\d\.]+)"
</syntaxhighlight>

with JSON you can write
<syntaxhighlight lang="perl">
attr test2 get01JSON data_34.4008.value
</syntaxhighlight>
which will create a reading with the Name "Chlor" (as shown above) and take the value 0.25 from the JSON string.

or if you don't care about the naming of your readings, you can simply extract all JSON data with
<syntaxhighlight lang="perl">
attr test2 extractAllJSON
</syntaxhighlight>

which would apply to all data read from this device and create the following readings out of the HTTP response shown above:

{| class="wikitable"
| data_34.4008.value || 0.25
|-
| event_data || 48.30000.0
|-
| event_type || 1
|-
| status_code || 0
|}

or you can specify
<syntaxhighlight lang="perl">
attr test2 get01ExtractAllJSON
</syntaxhighlight>
which would only apply to all data read as response to the get command defined as get01.

It might seem very simple at first sight to use extractAllJSON but if you prefer readings with a meaningful name you should instead define these readings with readingXXName and readingXXJSON or getXXName and getXXJSON individually. Of Course it would be possible to create additional user readings outside HTTPMOD but doing calculations, naming and formatting inside HTTPMOD is more efficient.

=== JSON Lists ===

imagine the HTTP Response contains:

<syntaxhighlight lang="perl">
{ "power":"0",
"modes":["Off","SimpleColor","RainbowChase"],
"code1":3,
"code2":4
}
</syntaxhighlight>

then a configuration like

<syntaxhighlight lang="perl">
attr device reading01JSON modes
attr device reading01Name Mode
</syntaxhighlight>

will create a list of Subreadings just like a regex with multiple matches can create multiple subreadings:

{| class="wikitable"
| Mode-1 || Off
|-
| Mode-2 || SimpleColor
|-
| Mode-3 || RainbowChase
|}

if you don't want several subreadings but one reading that contains the list of modes, you can specify a recombine expression:

<syntaxhighlight lang="perl">
attr device reading01Name Modes
attr device reading01RecombineExpr join ",", @matchlist
</syntaxhighlight>

which will create one reading containing a list:

{| class="wikitable"
| Modes || Off,SimpleColor,RainbowChase
|}

JSON parsing specifications also don't Need to match exactly. If there is no exact match for a defined reading, the HTTPMOD will try to Interpret the specification as a regex and look for json object paths that match the specification as a regex. For example:

<syntaxhighlight lang="perl">
attr device reading01Name CodeElem
attr device reading01JSON code
</syntaxhighlight>

which will create a list of readings:

{| class="wikitable"
| CodeElem-1|| 3
|-
| CodeElem-2 || 4
|}

and of course they could also be recombined into one reading with a RecombineExpr Attribute.

== Parsing http / XML using xpath ==
Another alternative to regex parsing is the use of XPath to extract values from HTTP responses.
The following example shows how XML data can be parsed with XPath-Strict or HTML Data can be parsed with XPath.
Both work similar and the example uses XML Data parsed with the XPath-Strict option:

If The XML data in the HTTP response looks like this:

<syntaxhighlight lang="xml">
<root xmlns:foo="http://www.foo.org/" xmlns:bar="http://www.bar.org">
<actors>
<actor id="1">Peter X</actor>
<actor id="2">Charles Y</actor>
<actor id="3">John Doe</actor>
</actor>
</root>
</syntaxhighlight>

with XPath you can write
<syntaxhighlight lang="perl">
attr htest reading01Name Actor
attr htest reading01XPath-Strict //actor[2]/text()
</syntaxhighlight>

This will create a reading with the Name "Actor" and the value "Charles Y".

Since XPath specifications can define several values / matches, HTTPMOD can also interpret these and store them in multiple readings:
<syntaxhighlight lang="perl">
attr htest reading01Name Actor
attr htest reading01XPath-Strict //actor/text()
</syntaxhighlight>

will create the readings

{| class="wikitable"
| Actor-1 || Peter X
|-
| Actor-2 || Charles Y
|-
| Actor-3 || John Doe
|}

== Further replacements of URL, header or post data ==
sometimes it might be helpful to dynamically change parts of a URL, HTTP header or post data depending on existing readings, internals or
perl expressions at runtime. This might be needed to pass further variables to a server, a current date or other things.

To support this HTTPMOD offers generic replacements that are applied to a request before it is sent to the server. A replacement can be defined with the attributes

* <code>replacement[0-9]*Regex</code>
* <code>replacement[0-9]*Mode</code>
* <code>replacement[0-9]*Value</code>
* <code>[gs]et[0-9]*Replacement[0-9]*Value</code>

a replacement always replaces a match of a regular expression.

'''replacement[0-9]*Mode:'''
The way the replacement value is defined can be specified with the replacement mode.
* If the <code>replacement[0-9]*Mode</code> is <code>reading</code>, then the corresponding <code>replacement[0-9]*Value</code> is interpreted as the name of a ''reading'' of the same device or as ''device:reading'' to refer to another device.
* If the <code>replacement[0-9]*Mode</code> is <code>internal</code>, then the corresponding <code>replacement[0-9]*Value</code> is interpreted as the name of an ''internal'' of the same device or as ''device:internal'' to refer to another device.
* If the <code>replacement[0-9]*Mode</code> is <code>text</code>, then the corresponding <code>replacement[0-9]*Value</code> is interpreted as a static text
* If the <code>replacement[0-9]*Mode</code> is <code>expression</code>, then the corresponding <code>replacement[0-9]*Value</code> is evaluated as a perl expression to compute the replacement. Inside such a replacement expression it is possible to refer to capture groups of the replacement regex.
* If the <code>replacement[0-9]*Mode</code> is <code>key</code>, then the module will use a value from a key / value pair that is stored in an obfuscated form in the file system with the set storeKeyValue command. This might be useful for storing passwords.

Example:

<syntaxhighlight lang="perl" line="1">
attr mydevice getData {"get" :["%%value%%.value"]}
attr mydevice replacement01Mode text
attr mydevice replacement01Regex %%value%%

attr mydevice get01Name Chlor
attr mydevice get01Replacement01Value 34.4008

attr mydevice get02Name Something
attr mydevice get02Replacement01Value 31.4024

attr mydevice get05Name profile
attr mydevice get05URL http://www.mydevice.local/getprofile?password=%%password%%
attr mydevice replacement02Mode key
attr mydevice replacement02Regex %%password%%
attr mydevice replacement02Value password
</syntaxhighlight>

defines that <code>%%value%%</code> will be replaced by a static text.

All Get commands will be HTTP post requests of a similar form. Only the <code>%%value%%</code> will be different from get to get.
The first get will set the reading named Chlor and for the request it will take the generic getData and replace %%value%% with 34.4008.

A second get will look the same except a different name and replacement value.

With the command <code>set mydevice storeKeyValue password geheim</code> you can store the password geheim in an obfuscated form in the file system.
To use this password and send it in a request you can use the above replacement with mode key. The value password will then refer to the ofuscated string stored with the key password.

The mode <code>expression</code> allows you to define your own replacement syntax:
<syntaxhighlight lang="perl">
attr mydevice replacement01Mode expression
attr mydevice replacement01Regex {{([^}]+)}}
attr mydevice replacement01Value ReadingsVal("mydevice", $1, "")
attr mydevice getData {"get" :["{{temp}}.value"]}
</syntaxhighlight>

In this example any <code><nowiki>{{name}}</nowiki></code> in a URL, header or post data will be passed on to the perl function ReadingsVal
which uses the string between <code><nowiki>{{}}</nowiki></code> as second parameter. This way one defined replacement can be used for many different
readings.

HTTPMOD has two built in replacements: One for session Ids and another one for the input value in a set command.
The placeholder $sid is always replaced with the internal <code>$hash->{sid}</code> which contains the session id after it is extracted from a previous HTTP response.
If you don't like to use the placeholder $sid then you can define your own replacement for example like:

<syntaxhighlight lang="perl">
attr mydevice replacement01Mode internal
attr mydevice replacement01Regex %session%
attr mydevice replacement01Value sid
</syntaxhighlight>

Now the internal <code>$hash->{sid}</code> will be used as a replacement for the placeholder %session%.

In the same way a value that is passed to a set-command can be put into a request with a user defined replacement.
In this case the internal <code>$hash->{value}</code> will contain the value passed to the set command.
<code>$hash->{value}</code> might even be a string containing several values that could be put into several different positions in a request by using user defined replacements.

'''Other example : steering a pellet stove from Rika'''

The stove API of Rika on https://www.rika-firenet.com/web/ delivers a JSON string with all settings and values, and can be piloted with a data string containing all the "set" values at once.

Delivered JSON on get https://www.rika-firenet.com/api/client/xxxxxxxx/status : (xxxxxxxx must be replaced with the unique stove ID)
<syntaxhighlight lang="perl">
{
"name": "Vorzimmer",
"stoveID": "xxxxxxxxx",
"lastSeenMinutes": 1,
"lastConfirmedRevision": 1504385700,
"controls": {
"revision": 1504385700,
"onOff": true,
"operatingMode": 2,
"heatingPower": 65,
"targetTemperature": 24,
"heatingTimesActive": false,
"heatingTimesActiveForComfort": true,
"setBackTemperature": 18,
"convectionFan1Active": false,
"convectionFan1Level": 0,
"convectionFan1Area": 0,
"convectionFan2Active": false,
"convectionFan2Level": 0,
"convectionFan2Area": 0,
"frostProtectionActive": false,
"frostProtectionTemperature": 5
},
"sensors": {
"statusError": 0,
"statusWarning": 0,
"statusService": 0,
"statusMainState": 1,
"statusSubState": 3,
"statusFrostStarted": false,
"inputFlameTemperature": 21,
"inputRoomTemperature": 21,
"inputExternalRequest": true,
"outputDischargeMotor": 0,
"outputInsertionMotor": 0,
"outputIDFan": 0,
"outputAirFlaps": 0,
"outputIgnition": false,
"parameterStoveTypeNumber": 13,
"parameterVersionMainBoard": 223,
"parameterVersionTFT": 223,
"parameterRuntimePellets": 11,
"parameterRuntimeLogs": 0,
"parameterFeedRateTotal": 17,
"parameterFeedRateService": 683,
"parameterOnOffCycles": 2
},
"stoveType": "DOMO MultiAir",
"stoveFeatures": {
"multiAir1": true,
"multiAir2": true,
"insertionMotor": false,
"airFlaps": false,
"logRuntime": false
}
}
</syntaxhighlight>

Data string to send to https://www.rika-firenet.com/api/client/xxxxxxxx/controls in order to set values:
<syntaxhighlight lang="perl">
heatingTimesActiveForComfort=true&frostProtectionTemperature=3&setBackTemperature=18&targetTemperature=24&convectionFan2Level=0&convectionFan2Active=false&convectionFan1Level=0&onOff=true&convectionFan1Active=false&convectionFan2Area=0&revision=1505550101&heatingTimesActive=false&convectionFan1Area=0&frostProtectionActive=false&operatingMode=2&heatingPower=65
</syntaxhighlight>

Code in 99_myUtils.pm:
<syntaxhighlight lang="perl">
use JSON;
...
sub
replaceJSON ($$) {
my ($valToReplace, $value) = @_;

#$value in the parameters is a default value
#It has to be replaced through the real value nnn passed in the set command "set <device> valToset nnn"
$value = InternalVal("Ofen", "value", $value);
Log3 ("Ofen", 3, "replaceJSON Internalvalue: $value");

#Force an update to avoid outdated revision number
fhem ("get Ofen revision");

#Get all the controls as json
my $json = ReadingsVal("Ofen", "controlsJSON","");
Log3 ("Ofen", 3, "replaceJSON configsJSON: $json");

# When starting FHEM or rereading config, the reading controlsJSON is empty
return if ($json eq "");

my $decoded = decode_json($json);
my $result;
for my $key ( keys %$decoded ) {
$result .= "$key=";
if ($key eq $valToReplace) {
$result .= $value."&";
} else {
$result .= $decoded->{$key}."&";
}
}
chop($result); #remove last &
Log3("Ofen", 3, "replaceJSON Result: $result");
return $result;
}
</syntaxhighlight>

Define stove in fhem:
<syntaxhighlight lang="perl">
defmod Ofen HTTPMOD https://www.rika-firenet.com/api/client/xxxxxxxx/status 60

attr Ofen enableCookies 1
attr Ofen reAuthRegex id="login"|Unauthorized
attr Ofen sid01Data email=xx@xx&password=xx
attr Ofen sid01URL https://www.rika-firenet.com/web/login

attr Ofen reading01JSON sensors_inputRoomTemperature
attr Ofen reading01Name RaumTemp
attr Ofen reading02JSON controls_setBackTemperature
attr Ofen reading02Name Absenkung
attr Ofen reading03JSON controls_frostProtectionTemperature
attr Ofen reading03Name Frostschutz
attr Ofen reading10Name controlsJSON
attr Ofen reading10Regex (?s)controls.*?({.*?})

attr Ofen get09Name revision
attr Ofen get09URL https://www.rika-firenet.com/api/client/xxxxxxxx/status

attr Ofen setURL https://www.rika-firenet.com/api/client/xxxxxxxx/controls
attr Ofen setData {{data}}
attr Ofen replacement01Mode expression
attr Ofen replacement01Regex {{data}}

attr Ofen set11Name frostProtectionTemperature
attr Ofen set11Replacement01Value replaceJSON("frostProtectionTemperature", 2)

attr Ofen set12Name targetTemperature
attr Ofen set12Replacement01Value replaceJSON("targetTemperature", 24)
</syntaxhighlight>

A detailed explanation (in german) of the login process can be found here: [https://forum.fhem.de/index.php/topic,76220.msg682514.html#msg682514]
and the explanation of the other parameters here: [https://forum.fhem.de/index.php/topic,76220.msg685710.html#msg685710]

== replacing reading values when they have not been updated / the device did not respond ==
If a device does not respond then the values stored in readings will keep the same and only their timestamp shows that they are outdated.
If you want to modify reading values that have not been updated for a number of seconds, you can use the attributes

* <code>(reading|get)[0-9]*(-[0-9]+)?MaxAge</code>
* <code>(reading|get)[0-9]*(-[0-9]+)?MaxAgeReplacementMode</code>
* <code>(reading|get)[0-9]*(-[0-9]+)?MaxAgeReplacement</code>

Every time the module tries to read from a device, it will also check if readings have not been updated
for longer than the <code>MaxAge</code> attributes allow. If readings are outdated, the <code>MaxAgeReplacementMode</code> defines how the affected
reading values should be replaced. <code>MaxAgeReplacementMode</code> can be <code>text</code>, <code>reading</code>, <code>internal</code>, <code>expression</code> or <code>delete</code>.

<code>MaxAge</code> specifies the number of seconds that a reading should remain untouched before it is replaced.

<code>MaxAgeReplacement</code> contains either a static text that is used as replacement value or a Perl expression that is evaluated to
give the replacement value. This can be used for example to replace a temperature that has not bee updated for more than 5 minutes
with the string "outdated - was 12":
<syntaxhighlight lang="perl">
attr PM readingMaxAge 300
attr PM readingMaxAgeReplacement "outdated - was " . $val
attr PM readingMaxAgeReplacementMode expression
</syntaxhighlight>
The variable <code>$val</code> contains the value of the reading before it became outdated.

Or to show that a device was offline:
<syntaxhighlight lang="perl">
attr MyLight reading01Name color
attr MyLight reading01JSON result_02_color
attr MyLight reading01MaxAge 300
attr MyLight reading01MaxAgeReplacement "offline"
attr MyLight reading01MaxAgeReplacementMode text
</syntaxhighlight>

== Note on determining how to send requests to a special device ==
If you don't know which URLs, headers or POST data your web GUI uses, you might try a local proxy like BurpSuite [http://portswigger.net/burp/ BurpSuite] to track requests and responses. This is a tedious task but probably the best way to achieve a successful result.

Let us consider an example. The Telekom Speedport W724V has a login-site that is famous for being cumbersome. Burp allows to monitor each step in the login procedure. In the case of a speedport the following steps occur:

First burp shows that a get command is issued
##################################################################################################
GET / HTTP/1.1
Host: speedport.ip
Cache-Control: max-age=0
Upgrade-Insecure-Requests: 1
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/57.0.2987.133 Safari/537.36
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8
Accept-Language: de-DE,de;q=0.8,en-US;q=0.6,en;q=0.4
Cookie: lang=de
Connection: close
In order to mimic the behavior of a real person calling the website HTTPMOD should copy all necessary steps. Host, Cookie and the GET-command are usually necessary. The same cannot be said of the User-Agent because the website can be called from any mobile or desktop computer.

Then, the speedport will answer with a command that consists of several lines. By going through every line for every step in the login procedure one will finally arrive at the information that is necessary to successfully enter the login of the speedport (in case of the W724V, for example, it is necessary to copy a token called _httoken and to include the referer).

== Advanced configuration to define a <code>set</code> command and send data to a device ==

When a set option is defined by attributes, the module will use the value given to the set command and integrate it into an HTTP-Request that sends the value to the device. The definitions for URL, headers and post data can contain the placeholder $val which will be replaced by the (numerical) value given to the set command.

This can be as simple as:
<syntaxhighlight lang="perl">
# No cyclic requests and no main URL needed in this example
define MyDevice HTTPMOD none 0

attr MyDevice set01Name Licht
attr MyDevice set01URL http://192.168.1.22/switch=$val
</syntaxhighlight>

A user command
<syntaxhighlight lang="perl">
set MyDevice Licht 1
</syntaxhighlight>

will be translated into the http GET request
<syntaxhighlight lang="perl">
http://192.168.1.22/switch=1
</syntaxhighlight>

In this example a map would also be helpful, that translates on / off to 0 or 1 and allows the user to select on/of in fhemweb:
<syntaxhighlight lang="perl">
attr MyDevive set01IMap 0:off, 1:on
</syntaxhighlight>
This also provides input validation to make sure that only on and off can be used with the set command.

In more complex Scenarios you might need to login before sending a command and the Login might create a session id that has to be part of further requests either in the URL, in headers or in the post data.

Extension to the above example for a PoolManager 5 where a set needs a session id in the URL and the values have to be passed in JSON strings as post data:
<syntaxhighlight lang="perl">
attr PM set01Name HeizungSoll
attr PM set01URL http://MyPoolManager/cgi-bin/webgui.fcgi?sid=$sid
attr PM set01Hint 6,10,20,30
attr PM set01Min 6
attr PM set01Max 30
attr PM setHeader1 Content-Type: application/json
attr PM set01Data {"set" :{"34.3118.value" :"$val" }}
</syntaxhighlight>

This example defines a set option with the name HeizungSoll.
By issuing <code>set PM HeizungSoll 10</code> in FHEM, the value 10 will be sent in the defined HTTP
Post to URL <code>http://MyPoolManager/cgi-bin/webgui.fcgi</code> in the Post Data as

<syntaxhighlight lang="html">
{"set" :{"34.3118.value" :"10" }}
</syntaxhighlight>

The optional attributes set01Min and set01Max define input validations that will be checked in the set function.
The optional attribute set01Hint will define a selection list for the FHEMweb GUI.

The HTTP response to such a request will be ignored unless you specify the attribute <code>setParseResponse</code>
for all set commands or <code>set01ParseResponse</code> for the set command with number 01.
If the HTTP response to a set command is parsed then this is done like the parsing of responses to get commands and you can use the attributes ending e.g. on Format, Encode, Decode, OMap and OExpr to manipulate / format the values read.

If a parameter to a set command is not numeric but should be passed on to the device as text, then you can specify the attribute setTextArg. For example:
<syntaxhighlight lang="perl">
attr PM set01TextArg
</syntaxhighlight>

If a set command should not require a parameter at all, then you can specify the attribute NoArg. For example:
<syntaxhighlight lang="perl">
attr PM set03Name On
attr PM set03NoArg
</syntaxhighlight>

This example defines the set of parameters for Wiesemann&Theiss Web-IO Analog 4.0 #57761. The current limit is set to 16mA (setxxMax)
<syntaxhighlight lang="Perl">
defmod WuT_Analog1 HTTPMOD none 30
attr WuT_Analog1 room W&T
attr WuT_Analog1 set01Max 16
attr WuT_Analog1 set01Min 0
attr WuT_Analog1 set01Name Output1
attr WuT_Analog1 set01URL http://192.xx.My_IP/outputaccess1?PW=MyPassword&State=$val&
attr WuT_Analog1 set02Max 16
attr WuT_Analog1 set02Min 0
attr WuT_Analog1 set02Name Output2
attr WuT_Analog1 set02URL http://192.xx.My_IP/outputaccess2?PW=MyPassword&State=$val&
</syntaxhighlight>

== Advanced configuration to create a valid session id that might be necessary ==
In simple cases logging in works with basic authentication. In the case HTTPMOD accepts a username and password as part of the URL in the form
<syntaxhighlight lang="perl">
http://User:Password@192.168.1.18/something
</syntaxhighlight>

However basic auth is seldom used. If you need to fill in a username and password in a HTML form and the session is then managed by a session id, here is how to configure this:

when sending data to an HTTP-Device in a set, HTTPMOD will replace any <code>$sid</code> in the URL, Headers and Post data with the internal <code>$hash->{sid}</code>. To authenticate towards the device and give this internal a value, you can use an optional multi step login procedure defined by the following attributes:

* <code>sid[0-9]*URL</code>
* <code>sid[0-9]*Data.*</code>
* <code>sid[0-9]*Header.*</code>
* <code>sid[0-9]*IgnoreRedirects</code>
* <code>idRegex</code>
* <code>idJSON</code>
* <code>idXPath</code>
* <code>idXPath-Strict</code>
* <code>(get|set|sid)[0-9]*IdRegex</code>
* <code>(get|set|sid)[0-9]*IdJSON</code>
* <code>(get|set|sid)[0-9]*IdXPath</code>
* <code>(get|set|sid)[0-9]*IdXPath-Strict</code>

Each step can have a URL, Headers, Post Data pieces and a Regex to extract a resulting Session ID into <code>$hash->{sid}</code>.
HTTPMOD will create a sorted list of steps (the numbers between sid and URL / Data / Header) and the loop through these steps and send the corresponding requests to the device. For each step a $sid in a Header or Post Data will be replaced with the current content of <code>$hash->{sid}</code>.

Using this feature, HTTPMOD can perform a forms based authentication and send user name, password or other necessary data to the device and save the session id for further requests.

To determine when this login procedure is necessary, HTTPMOD will first try to send a request without
doing the login procedure. If the result contains an error that authentication is necessary, then a login is performed.
To detect such an error in the HTTP response, you can again use a regular expression, JSON or XPath, this time with the attributes

* <code>reAuthRegex</code>
* <code>reAuthJSON</code>
* <code>reAuthXPath</code>
* <code>reAuthXPath-Strict</code>
* <code>(get|set)[0-9]*ReAuthRegex</code>
* <code>(get|set)[0-9]*ReAuthJSON</code>
* <code>(get|set)[0-9]*ReAuthXPath</code>
* <code>(get|set)[0-9]*ReAuthXPath-Strict</code>

reAuthJSON or reAuthXPath typically only extract one piece of data from a response.
If the existence of the specified piece of data is sufficent to start a login procedure, then nothing more needs to be defined to detect this situation.
If however the indicator is a status code that contains different values depending on a successful request and a failed request if a new authentication is needed,
then you can combine things like reAuthJSON with reAuthRegex. In this case the regex is only matched to the data extracted by JSON (or XPath).
This way you can easily extract the status code using JSON parsing and then specify the code that means "authentication needed" as a regular expression.

If for one step not all of the URL, Data or Header Attributes are set, then HTTPMOD tries to use a
<code>sidURL</code>, <code>sidData.*</code> or <code>sidHeader.*</code> Attribute (without the step number after sid). This way parts that are the same for all steps don't need to be defined redundantly.

=== Example for a multi step login procedure: ===
<syntaxhighlight lang="perl">
attr PM reAuthRegex /html/dummy_login.htm
attr PM sidURL http://192.168.70.90/cgi-bin/webgui.fcgi?sid=$sid
attr PM sidHeader1 Content-Type: application/json
attr PM sid1IDRegex wui.init\('([^']+)'
attr PM sid2Data {"set" :{"9.17401.user" :"fhem" ,"9.17401.pass" :"password" }}
attr PM sid3Data {"set" :{"35.5062.value" :"128" }}
attr PM sid4Data {"set" :{"42.8026.code" :"pincode" }}
</syntaxhighlight>

In this case HTTPMOD detects that a login is necessary by looking for the pattern /html/dummy_login.htm in the HTTP response.
If it matches, it starts a login sequence. In the above example all steps request the same URL. In step 1 only the defined Header is sent in an HTTP get request. The response will contain a session id that is extraced with the regex wui.init\('([^']+)'.

In the next step this session id is sent in a post request to the same URL where tha post data contains a username and password. The a third and a fourth request follow that set a value and a code. The result will be a valid and authorized session id that can be used in other requests where $sid is part of a URL, header or post data and will be replaced with the session id extracted above.

===Another Practical Example reading the SOC from a Renault Zoe===
<syntaxhighlight lang="perl">
define myZoe HTTPMOD https://www.services.renault-ze.com/api/vehicle/VINVINVIN/battery 7000
attr myZoe userattr reading01JSON reading01Name reading02JSON reading02Name reading03JSON reading03Nam\
e reading04JSON reading04Name reading05JSON reading05Name requestHeader02 sid1Data sid1Header01 sid1Id\
JSON sid1IgnoreRedirects:0,1 sid1URL
attr myZoe reAuthJSON message
attr myZoe reading01JSON charge_level
attr myZoe reading01Name SOC
attr myZoe reading02JSON charging
attr myZoe reading02Name charging
attr myZoe reading03JSON plugged
attr myZoe reading03Name plugged
attr myZoe reading04JSON remaining_range
attr myZoe reading04Name remaining_range
attr myZoe reading05JSON last_update
attr myZoe reading05Name last_update
attr myZoe requestHeader02 Authorization: Bearer $sid
attr myZoe sid1Data {"username":"ZEUSERNAME","password":"ZEPASSWORD"}
attr myZoe sid1Header01 Content-Type: application/json
attr myZoe sid1IdJSON token
attr myZoe sid1IgnoreRedirects 1
attr myZoe sid1URL https://www.services.renault-ze.com/api/user/login
attr myZoe timeout 10
#attr myZoe verbose 7
</syntaxhighlight>

The $sid is read by logging in with username and password from JSON {"token": ..} after detecting an error {"message": ..} from a failed request. This example offers no solution for the reading of the VIN from the login request, which in turn is part of the reading URL. It should be possible to read more than just the $sid from the login sequence.

In the special case where a session id is set as a HTTP-Cookie (with the header Set-cookie: in the HTTP response) HTTPMOD offers an even simpler way. With the attribute enableCookies a very basic cookie handling mechanism is activated that stores all cookies that the server sends to the HTTPMOD device and puts them back as cookie headers in the following requests.

For such cases no sidIdRegex and no $sid in a user defined header is necessary.

== Advanced configuration to define a <code>get</code> and request additional data with its own request from a device ==

The normal automatic HTTP request that is done repeatedly after the defined interval has elapsed works well in cases where all required readings can be requested in one common HTTP request. If however a device needs individual requests with different URLs or different POST data for each value, then another method is necessary.
For such cases a <code>get</code> option can be defined and the user can either issue FHEM <code>get</code> commands each time he needs the reading or the user can set an attribute to request the reading automatically together with the normal iteration.
For each <code>get</code> option attributes define an individual URL, optional headers, and post data as well as individual regular expressions and formatting options.

When a get option is defined by attributes, the module allows querying additional values from the device that require individual HTTP-Requests or special parameters to be sent

Extension to the above example:

<syntaxhighlight lang="perl">
attr PM get01Name MyGetValue
attr PM get01URL http://MyPoolManager/cgi-bin/directory/webgui.fcgi?special=1?sid=$sid
attr PM getHeader1 Content-Type: application/json
attr PM get01Data {"get" :{"30.1234.value"}}
</syntaxhighlight>

This example defines a get option with the name MyGetValue.
By issuing <code>get PM MyGetValue</code> in FHEM, the defined HTTP request is sent to the device.
The HTTP response is then parsed using the same readingXXName and readingXXRegex attributes as above so
additional pairs will probably be needed there for additional values.

if you prefer to define the parsing and formatting of readings individually per get command, you can use
attributes like get01Regex, get01XPath, get01Format, get01OMap and so on just like for reading01...

You can also include parameters / values that are passed to the get command in the request just like for set commands.
The placeholder $val will be replaced with the value given to the get command or you can specify your own replacement as described above.

If the new get parameter should also be queried regularly, you can define the following optional attributes:

<syntaxhighlight lang="perl">
attr PM get01Poll 1
attr PM get01PollDelay 300
</syntaxhighlight>

The first attribute includes this reading in the automatic update cycle and the second defines an alternative lower update frequency. When the interval defined initially in the define is over and the normal readings are read from the device, the update function will check for additional get parameters that should be included in the update cycle.

If a PollDelay is specified for a get parameter, the update function also checks if the time passed since it has last read this value is more than the given PollDelay. If not, this reading is skipped and it will be rechecked in the next cycle when interval is over again. So the effective PollDelay will always be a multiple of the interval specified in the initial define.

Please note that each defined get command that is included in the regular update cycle will create its own HTTP request. So if you want to extract several values from the same request, it is much more efficient to do this by defining readingXXName and readingXXRegex, XPath or JSON attributes and to specify an interval and a URL in the define of the HTTPMOD device.

Example for a Siemens webserver provided by Lanhydrock:
<syntaxhighlight lang="perl">
define ozw672 HTTPMOD https://192.168.178.8/api/auth/login.json?user=test&pwd=test 300

attr ozw672 get1Name tempAussen
attr ozw672 get1URL https://192.168.178.8/api/menutree/read_datapoint.json?SessionId=$sid&Id=1960
attr ozw672 get1Poll 1
attr ozw672 get1PollDelay 1800

attr ozw672 get2Name tempAussenGemischt
attr ozw672 get2URL https://192.168.178.8/api/menutree/read_datapoint.json?SessionId=$sid&Id=1964
attr ozw672 get2Poll 1
attr ozw672 get2PollDelay 1800

attr ozw672 get3Name tempTWW
attr ozw672 get3URL https://192.168.178.8/api/menutree/read_datapoint.json?SessionId=$sid&Id=1996
attr ozw672 get3Poll 1

attr ozw672 get4Name tempKesselSoll
attr ozw672 get4URL https://192.168.178.8/api/menutree/read_datapoint.json?SessionId=$sid&Id=1910
attr ozw672 get4Poll 1

attr ozw672 get5Name tempKesselRuecklauf
attr ozw672 get5URL https://192.168.178.8/api/menutree/read_datapoint.json?SessionId=$sid&Id=1915
attr ozw672 get5Poll 1

attr ozw672 get6Name tempKesselRuecklaufSoll
attr ozw672 get6URL https://192.168.178.8/api/menutree/read_datapoint.json?SessionId=$sid&Id=1916
attr ozw672 get6Poll 1

attr ozw672 get7Name anzahlStartsBrenner
attr ozw672 get7URL https://192.168.178.8/api/menutree/read_datapoint.json?SessionId=$sid&Id=1927
attr ozw672 get7PollDelay 1800
attr ozw672 get7Poll 1

attr ozw672 get8Name statusKessel
attr ozw672 get8URL https://192.168.178.8/api/menutree/read_datapoint.json?SessionId=$sid&Id=1898
attr ozw672 get8Poll 1
attr ozw672 get8Regex Value": "([a-zA-Zü ]*)"
attr ozw672 get8OMap Aus:0, Nachlauf aktiv:5, Freigegeben für TWW:10, Freigegeben für HK:20, In Teillastbetrieb für TWW:40, In Teillastbetrieb für HK:50, In Betrieb für Trinkwasser:90, In Betrieb für Heizkreis:100

attr ozw672 getRegex Value": "[ ]*([-.0-9]*)"

attr ozw672 reAuthRegex .*session not valid.*
attr ozw672 sid1IDRegex .*"(.*-.*-.*-[0-9a-z]*).*
attr ozw672 sid1URL https://192.168.178.8/api/auth/login.json?user=test&pwd=test
</syntaxhighlight>

== All attributes ==
;reading[0-9]+Name
:the name of a reading to extract with the corresponding readingRegex, readingJSON, readingXPath or readingXPath-Strict
:Please note that the old syntax <b>readingsName.*</b> does not work with all features of HTTPMOD and should be avoided. It might go away in a future version of HTTPMOD.

;(get|set)[0-9]+Name
:Name of a get or set command
:If the HTTP response that is received after the command is parsed with an individual parse option then this name is also used as a reading name. Please note that no individual parsing needs to be defined for a get or set. If no regex, XPath or JSON is specified for the command, then HTTPMOD will try to parse the response using all the defined readingRegex, reading XPath or readingJSON attributes.

;(get|set|reading)[0-9]+Regex
:If this attribute is specified, the Regex defined here is used to extract the value from the HTTP Response and assign it to a Reading with the name defined in the (get|set|reading)[0-9]+Name attribute.
:If this attribute is not specified for an individual Reading or get or set but without the numbers in the middle, e.g. as getRegex or readingRegex, then it applies to all the other readings / get / set commands where no specific Regex is defined.<br>
:The value to extract should be in a capture group / sub expression e.g. ([\d\.]+) in the above example. Multiple capture groups will create multiple readings (see explanation above)
:Using this attribute for a set command (setXXRegex) only makes sense if you want to parse the HTTP response to the HTTP request that the set command sent by defining the attribute setXXParseResponse.
:Please note that the old syntax <code>readingsRegex.*</code> does not work with all features of HTTPMOD and should be avoided. It might go away in a future version of HTTPMOD.
:If for get or set commands neither a generic Regex attribute without numbers nor a specific (get|set)[0-9]+Regex attribute is specified and also no XPath or JSON parsing specification is given for the get or set command, then HTTPMOD tries to use the parsing definitions for general readings defined in reading[0-9]+Name, reading[0-9]+Regex or XPath or JSON attributes and assigns the Readings that match here.

;(get|set|reading)[0-9]+RegOpt
:Lets the user specify regular expression modifiers. For example if the same regular expression should be matched as often as possible in the HTTP response, then you can specify RegOpt g which will case the matching to be done as /regex/g
:The results will be trated the same way as multiple capture groups so the reading name will be extended with -number.
:For other possible regular expression modifiers see http://perldoc.perl.org/perlre.html#Modifiers

;(get|set|reading)[0-9]+XPath
:defines an xpath to one or more values when parsing HTML data (see examples above)
:Using this attribute for a set command only makes sense if you want to parse the HTTP response to the HTTP request that the set command sent by defining the attribute setXXParseResponse.

;get|set|reading[0-9]+XPath-Strict
:defines an xpath to one or more values when parsing XML data (see examples above)
:Using this attribute for a set command only makes sense if you want to parse the HTTP response to the HTTP request that the set command sent by defining the attribute setXXParseResponse.

;(get|set|reading)[0-9]+AutoNumLen
:In cases where a regular expression or an XPath results in multiple results and these results are stored in a common reading name with extension -number, then you can modify the format of this number to have a fixed length with leading zeros. AutoNumLen 3 for example will lead to reading names ending with -001 -002 and so on.

;(get|set|reading)[0-9]+AlwaysNum
:if set to 1 this attributes forces reading names to end with a -1, -01 (depending on the above described AutoNumLen) even if just one value is parsed.

;get|set|reading[0-9]+JSON
:defines a path to the JSON object wanted by concatenating the object names. See the above example.
:If you don't know the paths, then start by using extractAllJSON and the use the names of the readings as values for the JSON attribute.<br>
:Please don't forget to also specify a name for a reading, get or set.
:Using this attribute for a set command only makes sense if you want to parse the HTTP response to the HTTP request that the set command sent by defining the attribute setXXParseResponse.

;(get|set|reading)[0-9]*RecombineExpr
:defines an expression that is used in an eval to compute one reading value out of the list of matches.
:This is supposed to be used for regexes or xpath specifications that produce multiple results if only one result that combines them is wanted. The list of matches will be in the variable @matchlist.
:Using this attribute for a set command only makes sense if you want to parse the HTTP response to the HTTP request that the set command sent by defining the attribute setXXParseResponse.

;get[0-9]*CheckAllReadings
:this attribute modifies the behavior of HTTPMOD when the HTTP Response of a get command is parsed. <br>
:If this attribute is set to 1, then additionally to the matching of the corresponding get specific regex (get[0-9]*Regex), XPath or JSON attribute also all the reading names and parse definitions defined in Reading[0-9]+Name and Reading[0-9]+Regex, XPath or JSON attributes are checked and if they match, the coresponding Readings are assigned as well.
:Please note that this does not mean that get01CheckAllReadings will cause a get02Regex to be used. Only the corresponding get01Regex will be used but additionally all the readingXYRegex attributes.
:This is automatically done if a get or set command is defined without its own parse attributes.

;(get|reading)[0-9]*OExpr
:defines an optional expression that is used in an eval to compute / format a readings value after parsing an HTTP response
:The raw value from the parsing will be in the variable $val.
:If specified as readingOExpr then the attribute value is a default for all other readings that don't specify an explicit reading[0-9]*Expr.
:Please note that the old syntax <b>readingsExpr.*</b> does not work with all features of HTTPMOD and should be avoided. It might go away in a future version of HTTPMOD.

;(get|reading)[0-9]*Expr
:This is the old syntax for (get|reading)[0-9]*OExpr. It should be replaced by (get|reading)[0-9]*OExpr. The set command upgradeAttributes which becomes visible when the attribute enableControlSet is set to 1, can do this renaming automatically.

;(get|reading)[0-9]*OMap
:Map that defines a mapping from raw value parsed to visible values like "0:mittig, 1:oberhalb, 2:unterhalb".
:If specified as readingOMap then the attribute value is a default for all other readings that don't specify an explicit reading[0-9]*Map.<br>
:The individual options in a map are separated by a komma and an optional space. Spaces are allowed to appear in a visible value however kommas are not possible.

;(get|reading)[0-9]*Map
:This is the old syntax for (get|reading)[0-9]*OMap. It should be replaced by (get|reading)[0-9]*OMap. The set command upgradeAttributes which becomes visible when the attribute enableControlSet is set to 1, can do this renaming automatically.

;(get|set|reading)[0-9]*Format
:Defines a format string that will be used in sprintf to format a reading value.
:If specified without the numbers in the middle e.g. as readingFormat then the attribute value is a default for all other readings that don't specify an explicit reading[0-9]*Format.
:Using this attribute for a set command only makes sense if you want to parse the HTTP response to the HTTP request that the set command sent by defining the attribute setXXParseResponse.<br>

;(get|set|reading)[0-9]*Decode
:defines an encoding to be used in a call to the perl function decode to convert the raw data string read from the device to a reading.
:This can be used if the device delivers strings in an encoding like cp850 instead of utf8.
:If your reading values contain Umlauts and they are shown as strange looking icons then you probably need to use this feature.
:Using this attribute for a set command only makes sense if you want to parse the HTTP response to the HTTP request that the set command sent by defining the attribute setXXParseResponse.

;(get|set|reading)[0-9]*Encode
:defines an encoding to be used in a call to the perl function encode to convert the raw data string read from the device to a reading.
:This can be used if the device delivers strings in an encoding like cp850 and after decoding it you want to reencode it to e.g. utf8.
:If your reading values contain Umlauts and they are shown as strange looking icons then you probably need to use this feature.
:Using this attribute for a set command only makes sense if you want to parse the HTTP response to the HTTP request that the set command sent by defining the attribute setXXParseResponse.

;(get|set)[0-9]*URL
:URL to be requested for the set or get command. If this option is missing, the URL specified during define will be used.

;(get|set)[0-9]*Data
:Data to be sent to the device as POST data when the get or set command is executed. if this attribute is not specified, an HTTP GET method will be used instead of an HTTP POST

;(get|set)[0-9]*NoData
:can be used to override a more generic attribute that specifies POST data for all get or set commands. With NoData no data is sent and therefor the request will be an HTTP GET.

;(get|set)[0-9]*Header.*
:HTTP Headers to be sent to the device when the set is executed

;requestHeader.*
:Define an optional additional HTTP Header to set in the HTTP request of the main loop

;requestData
:optional POST Data to be sent in the request of the main loop. If not defined, it will be an HTTP GET request as defined in HttpUtils which is used by this module

;get[0-9]+Poll
:if set to 1 the get is executed automatically during the normal update cycle (after the interval provided in the define command has elapsed)

;get[0-9]+PollDelay
:if the value should not be read in each iteration (after the interval given to the define command), then a minimum delay can be specified with this attribute. This has only an effect if the above Poll attribute has also been set. Every time the update function is called, it checks if since this get has been read the last time, the defined delay has elapsed. If not, then it is skipped this time.
:PollDelay can be specified as seconds or as x[0-9]+ which means a multiple of the interval in the define command.

;(get|set)[0-9]*TextArg
:For a get command this defines that the command accepts a text value after the option name. By default a get command doesn't accept optional values after the command name.
:If TextArg is specified and a value is passed after the get name then this value can then be used in a request URL, header or data as replacement for $val or in a user defined replacement that uses the internal "value" ($hash->{value}).
:If used for a set command then it defines that the value to be set doesn't require any validation / conversion.
:The raw value is passed on as text to the device. By default a set command expects a numerical value or a text value that is converted to a numeric value using a map.

;set[0-9]+Min
:Minimum value for input validation.

;set[0-9]+Max
:Maximum value for input validation.

;set[0-9]+IExpr
:Perl Expression to compute the raw value to be sent to the device from the input value passed to the set.

;set[0-9]+Expr
:This is the old syntax for (get|reading)[0-9]*IExpr. It should be replaced by (get|reading)[0-9]*IExpr. The set command upgradeAttributes which becomes visible when the attribute enableControlSet is set to 1, can do this renaming automatically.

;set[0-9]+IMap
:Map that defines a mapping from raw to input values like "0:mittig, 1:oberhalb, 2:unterhalb". This attribute atomatically creates a hint for FHEMWEB so the user can choose one of the input values.

;set[0-9]+Map
:This is the old syntax for (get|reading)[0-9]*IMap. It should be replaced by (get|reading)[0-9]*IMap. The set command upgradeAttributes which becomes visible when the attribute enableControlSet is set to 1, can do this renaming automatically.

;set[0-9]+Hint
:Explicit hint for fhemWEB that will be returned when set ? is seen. Can be used to get a slider or a list of values to choose from.

;set[0-9]*NoArg
:Defines that this set option doesn't require arguments. It allows sets like "on" or "off" without further values.

;set[0-9]*ParseResponse
:defines that the HTTP response to the set will be parsed as if it was the response to a get command.

;(get|set)[0-9]*URLExpr
:Defines a Perl expression to specify the HTTP Headers for this request. This overwrites any other header specification and should be used carefully only if needed. The original Header is availabe as $old. Typically this feature is not needed and it might go away in future versions of HTTPMOD. Please use the "replacement" attributes if you want to pass additional variable data to a web service.

;(get|set)[0-9]*DatExpr
:Defines a Perl expression to specify the HTTP Post data for this request. This overwrites any other post data specification and should be used carefully only if needed. The original Data is availabe as $old. Typically this feature is not needed and it might go away in future versions of HTTPMOD. Please use the "replacement" attributes if you want to pass additional variable data to a web service.

;(get|set)[0-9]*HdrExpr
:Defines a Perl expression to specify the URL for this request. This overwrites any other URL specification and should be used carefully only if needed. The original URL is availabe as $old. Typically this feature is not needed and it might go away in future versions of HTTPMOD. Please use the "replacement" attributes if you want to pass additional variable data to a web service.

;ReAuthRegex
:regular Expression to match an error page indicating that a session has expired and a new authentication for read access needs to be done.
:This attribute only makes sense if you need a forms based authentication for reading data and if you specify a multi step login procedure based on the sid.. attributes.
:This attribute is used for all requests. For set and get operations you can however specify individual reAuthRegexes with the (get|set)[0-9]*ReAuthRegex attributes.

;(get|set)[0-9]*ReAuthRegex
:Regex that will detect when a session has expired during a set operation and a new login needs to be performed.
:It works like the global reAuthRegex but is used for set operations.

;sid[0-9]*URL
:different URLs or one common URL to be used for each step of an optional login procedure.

;sid[0-9]*IDRegex
:different Regexes per login procedure step or one common Regex for all steps to extract the session ID from the HTTP response

;sid[0-9]*Data.*
:data part for each step to be sent as POST data to the corresponding URL

;sid[0-9]*Header.*
:HTTP Headers to be sent to the URL for the corresponding step

;sid[0-9]*IgnoreRedirects
:Tells the HttpUtils to not follow HTTP Redirects for this Request. Might be needed for some devices that set a session cookie within a 303 Redirect.

;clearSIdBeforeAuth
:will set the session id to "" before doing the authentication steps

;authRetries
:number of retries for authentication procedure - defaults to 1

;replacement[0-9]*Regex
:Defines a replacement to be applied to an HTTP request header, data or URL before it is sent. This allows any part of the request to be modified based on a reading, an internal or an expression.
:The regex defines which part of a header, data or URL should be replaced. The replacement is defined with the following attributes:

;replacement[0-9]*Mode
:Defines how the replacement should be done and what replacementValue means. Valid options are text, reading, internal and expression.

;replacement[0-9]*Value
:Defines the replacement. If the corresponding replacementMode is <code>text</code>, then value is a static text that is used as the replacement.
:If replacementMode is <code>reading</code> then Value can be the name of a reading of this device or it can be a reading of a different device referred to by devicename:reading.
:If replacementMode is <code>internal</code> the Value can be the name of an internal of this device or it can be an internal of a different device referred to by devicename:internal.
:If replacementMode is <code>expression</code> the the Value is treated as a Perl expression that computes the replacement value. The expression can use $1, $2 and so on to refer to capture groups of the corresponding regex that is matched against the original URL, header or post data.
:If replacementMode is <code>key</code> then the module will use a value from a key / value pair that is stored in an obfuscated form in the file system with the set storeKeyValue command. This might be useful for storing passwords.

;[gs]et[0-9]*Replacement[0-9]*Value
:This attribute can be used to override the replacement value for a specific get or set.

;get|reading[0-9]*MaxAge
:Defines how long a reading is valid before it is automatically overwritten with a replacement when the read function is called the next time.

;get|reading[0-9]*MaxAgeReplacement
:specifies the replacement for MaxAge - either as a static text or as a perl expression.

;get|reading[0-9]*MaxAgeReplacementMode
:specifies how the replacement is interpreted: can be text, expression and delete.

;get|reading[0-9]*DeleteIfUnmatched
:If set to 1 this attribute causes certain readings to be deleted when the parsing of the website does not match the specified reading. Internally HTTPMOD remembers which kind of operation created a reading (update, Get01, Get02 and so on). Specified readings will only be deleted if the same operation does not parse this reading again. This is especially useful for parsing that creates several matches / readings and the number of matches can vary from request to request. For example if reading01Regex creates 4 readings in one update cycle and in the next cycle it only matches two times then the readings containing the remaining values from the last round will be deleted.
:Please note that this mechanism will not work in all cases after a restart. Especially when a get definition does not contain its own parsing definition but ExtractAllJSON or relies on HTTPMOD to use all defined reading.* attributes to parse the responsee to a get command, old readings might not be deleted after a restart of fhem.
;get|reading[0-9]*DeleteOnError
:If set to 1 this attribute causes certain readings to be deleted when the website can not be reached and the HTTP request returns an error. Internally HTTPMOD remembers which kind of operation created a reading (update, Get01, Get02 and so on). Specified readings will only be deleted if the same operation returns an error.
The same restrictions as for DeleteIfUnmatched apply regarding a fhem restart.

;httpVersion
:defines the HTTP-Version to be sent to the server. This defaults to 1.0.

;sslVersion
:defines the SSL Version for the negotiation with the server. The attribute is evaluated by HttpUtils. If it is not specified, HttpUtils assumes SSLv23:!SSLv3:!SSLv2

;sslArgs
:defines a list that is converted to a key / value hash and gets passed to HttpUtils. To avoid certificate validation for broken servers you can for example specify
:<code>attr myDevice sslArgs SSL_verify_mode,SSL_VERIFY_NONE</code>

;alignTime
:Aligns each periodic read request for the defined interval to this base time. This is typcally something like 00:00 (see the FHEM at command)

;noShutdown
:pass the noshutdown flag to HTTPUtils for webservers that need it (some embedded webservers only deliver empty pages otherwise)

;disable
:stop doing automatic HTTP requests while this attribute is set to 1

;enableControlSet
:enables the built in set commands interval, stop, start, reread, upgradeAttributes, storeKeyValue.

;enableCookies
:enables the built in cookie handling if set to 1. With cookie handling each HTTPMOD device will remember cookies that the server sets and send them back to the server in the following requests.
:This simplifies session magamenet in cases where the server uses a session ID in a cookie. In such cases enabling cookies should be sufficient and no sidRegex and no manual definition of a cookie header should be necessary.

;showMatched
:if set to 1 then HTTPMOD will create a reading with the name MATCHED_READINGS that contains the names of all readings that could be matched in the last request as well as UNMATCHED_READINGS and LAST_REQUEST.

;showError
:if set to 1 then HTTPMOD will create a reading and event with the Name LAST_ERROR that contains the error message of the last error returned from HttpUtils.

;removeBuf
:if set to 1 then HTTPMOD removes the internal named buf when a HTTP-response has been received.
:$hash->{buf} is used internally be Fhem httpUtils and in some use cases it is desireable to remove this internal after reception
:because it contains a very long response which looks ugly in Fhemweb.

;timeout
:time in seconds to wait for an answer. Default value is 2

;queueDelay
:HTTP Requests will be sent from a queue in order to avoid blocking when several Requests have to be sent in sequence. This attribute defines the delay between calls to the function that handles the send queue. It defaults to one second.

;queueMax
:Defines the maximum size of the send queue. If it is reached then further HTTP Requests will be dropped and not be added to the queue

;minSendDelay
:Defines the minimum time between two HTTP Requests.

== Links ==
* Example: This example uses many features of HTTPMOD, universally useful is the access to other readings just like what [[Set magic|set-magic]] (<code>[device:reading]</code>) does [https://forum.fhem.de/index.php?topic=135666.0 🎸 Owntone (Musik-Player) mit FHEM steuern]
* Example: [https://www.goingelectric.de/forum/viewtopic.php?f=57&t=21462|Abfrage Akkustand einer Zoe und mehr von Renault ZE Services]
* Example: [[Wetter_und_Wettervorhersagen#Wetter_von_Weather_Underground|Extract weather information from WeatherUnderground]]
* Example: [[Pollenflug|Pollen count]]
* Example: [[HTTPMOD Beispielkonfiguration zur Anbindung einer Daikin Klimaanlage mit WLAN-Modul|Connect Daikin aircondition to FHEM]]
* Example: [[Go-eCharger|Extract information from go-eCharger]]
* Example: [[Sonnenspeicher|Integration of energy supplies from sonnen (https://sonnenbatterie.de/en/start)]]
* Example: [https://forum.fhem.de/index.php/topic,95989.msg915870.html#msg915870 Miele 3rd party API für Miele Smarthome Geräte]
* Example: [https://forum.fhem.de/index.php/topic,84215.msg918662.html#msg918662 Honeywell Evohome Totalconnect]
* Example: [https://forum.fhem.de/index.php/topic,78613.msg889015.html#msg889015 Tigo Energy Integration]
* Example: [https://forum.fhem.de/index.php/topic,78613.msg708518.html#msg708518 Ecowater]
* {{Link2Forum|Topic=17804|LinkText=Thread}} in FHEM Forum that discusses the first version of this module
* {{Link2Forum|Topic=29471|LinkText=Thread}} in FHEM Forum that discusses the second major version of this module
* {{Link2Forum|Topic=45176|LinkText=Thread}} in FHEM Forum that discusses the third major version of this module
* [http://perldoc.perl.org/perlretut.html Introduction to regular expressions]
* [http://portswigger.net/burp/ BurpSuite]: Tool (local proxy) to help analyze http traffic

[[Kategorie:IP Components]]

HTTPMOD

2025-04-05T08:57:16Z

Torxgewinde: /* Links */

{{Infobox Modul
|ModPurpose=Extract information from devices with an HTTP interface (or, more generic, from any URL) or send information to such devices
|ModType=d
|ModCmdRef=HTTPMOD
|ModForumArea=Sonstiges
|ModTechName=98_HTTPMOD.pm
|ModOwner=StefanStrobel ({{Link2FU|3960|Forum}} / [[Benutzer:StefanStrobel|Wiki]])
}}
[[HTTPMOD]] provides a generic way to retrieve information from devices with an HTTP Interface and store them in Readings or send information to such devices. It queries a given URL with Headers and data defined by attributes.

From the HTTP response it extracts readings named in attributes using Regexes, JSON or XPath parsing also defined by attributes.

In an advanced [[Konfiguration|configuration]] the module can also send information to devices. To do this, a generic <code>set</code> option can be configured using attributes.

== Introduction ==
With the help of HTTPMOD you can automatically access websites, retrieve information and send data. In the simplest case, an http call is started regularly and the content of a page, for example, is read and processed further. The URL and the time interval in which the call is to be made must then be specified when the call is made. In order to read information from the called web pages, readings are required. In this readings one specifies Regex, which reads the necessary information. Here is an example.

<syntaxhighlight lang="perl">
define PM HTTPMOD http://www.klack.de/fernsehprogramm/was-laeuft-gerade/0/-1/free.html 20000
</syntaxhighlight>

This creates a device that accesses the http://www.klack.de/fernsehprogramm/was-laeuft-gerade/0/-1/free.html website with the TV program every 20000 seconds. If neither readings nor other attributes are defined, then only the call of the website takes place and FHEM receives no further data from the web access.

But now a television program is returned when you call the website, which you might want to read out. In order to save the contents in FHEM, which are related to the ARD, you need a reading. This reading must contain a name (so that FHEM knows under which name the information is stored) and a regex (so that you know where the information is stored on the website). Since usually not one, but many readings are defined, these readings are numbered consecutively. This is done by numbers that are given immediately after the word reading. In our example this would be for example
<syntaxhighlight lang="perl">
attr PM reading1Name ARD
attr PM reading1Regex <span class="stationName">ARD<\/span>[\w\W]*?<div class="content">\s*<a[\w\W]*?>\s*(.*?)\s*<\/a>
attr PM reading2Name ARD_time
attr PM reading2Regex <span class="stationName">ARD<\/span>[\w\W]*?<td class="time">\s*(.*?)\s*<
attr PM reading3Name ARD_details
attr PM reading3Regex <span class="stationName">ARD<\/span>[\w\W]*?<div class="content">\s*<a[\w\W]*?>[\w\W]*?<\/a>\s*<br\/>\s*(.*?)(<img|<\/div)
</syntaxhighlight>

Reading1 contains the programme, reading2 the time and reading3 further details. The Regex result from the structure of the website and may have to be designed in painstaking detail.

There are cases where this is not enough. For example, it could be the case that the information from the web access is not automated, but manually received. Then a 0 must first be entered at the top of the duration. But how does HTTPMOD then know when the data should be retrieved? This is done with get-commands. If a get-command is executed, HTTPMOD accesses the website, fetches the information and fills the corresponding readings.

Again, it is possible to create not one but several get-commands. Therefore, get is always followed by (at least) one number with which the get commands are numbered. Here is another example. The TV program should be called manually and not time-controlled. To do this we first change the definition to
<syntaxhighlight lang="perl">
define PM HTTPMOD http://www.klack.de/fernsehprogramm/was-laeuft-gerade/0/-1/free.html 0
</syntaxhighlight>
and add the following to the attributes
<syntaxhighlight lang="perl">
attr PM get1Name ARDHolen
</syntaxhighlight>
With the command "get PM ARDHolen" the above readings are filled. In order for FHEM to know that the other reading2, reading3, etc. are to be read as well as reading1, the (user) attribute
<syntaxhighlight lang="perl">
attr PM get1CheckAllReadings 1
</syntaxhighlight>
needs to be defined.

If the URL is not sufficient when the web page is called, but a special header is to be sent with it, this can be done with the get1Header attribute. If the header is multiline, the individual lines can be entered with get1Header1, get1Header2, and so on.

If you want to evaluate or control different URLs, you can define several get commands (get1, get2, etc.) and provide them with your own URLs. get1 usually reads only the reading1, get2 reads only the reading2 and so on. With CheckAllReadings all readings are evaluated simultaneously.

If only data is to be sent on the web page, but not read, the set command is recommended. It has the same structure as the get-command.

It becomes a bit more complex if the website requires a login check. The sid attributes are used for this purpose.

== Availability, prerequisites and definition ==
This module is part of the regular FHEM distribution and uses the non blocking HTTP function <code>HttpUtils_NonblockingGet</code> provided by FHEM's [[HttpUtils]] in a new version published in December 2013.
If not already installed in your environment, please [[update]] FHEM or install it manually using appropriate commands from your environment.
Please also note that FHEM HttpUtils need the global attribute dnsServer to be set in order to work really non blocking even when dns requests can not be answered.

The device is defined as follows
<syntaxhighlight lang="perl">
define <name> HTTPMOD <URL> <Interval>
</syntaxhighlight>
The module connects to the given <code>URL</code> every <code>Interval</code> seconds, sends optional headers and data and then parses the response with regular expressions, xpath or json to set readings.

URL can be "none" and Interval can be 0 if you prefer to only query data with a get command and not in a defined interval.

Example:
<syntaxhighlight lang="perl">
define PM HTTPMOD http://MyPoolManager/cgi-bin/webgui.fcgi 60
</syntaxhighlight>

== Set-Commands ==
can be defined using attributes, see advanced configuration

If you set the attribute enableControlSet to 1, the following additional built in set commands are available:
;interval
:set new interval time in seconds and restart the timer
;reread
:request the defined URL and try to parse it just like the automatic update would do it every Interval seconds without modifying the running timer.
;stop
:stop interval timer.
;start
:restart interval timer to call GetUpdate after interval seconds
;upgradeAttributes
:convert outdated attributes for older HTTPMOD-Versions that are still defined for this device from the old syntax to the new one.
:attributes with the description "this attribute should not be used anymore" or similar will be translated to the new syntax, e.g. readingsName1 to reading01Name.
;storeKeyValue
:stores a key value pair in an obfuscated form in the file system. Such values can then be used in replacements where the mode is "key" e.g. to avoid storing passwords in the configuration in clear text

== Get-Commands ==
can be defined using attributes, see advanced configuration

== simple Attributes ==
;enableControlSet
:enables the built in set commands ''interval'', ''stop'', ''start'', ''reread'', ''upgradeAttributes'', ''storeKeyValue''

;enableCookies
:enables the cookie handling inside HTTPMOD. It is advisable to always set this attribute and allow HTTPMOD to track the state of cookies and set them for following HTTP-requests

;enforceGoodReadingNames
:makes sure that HTTPMOD only creates readings that are allowd for Fhem (especially if reading names are dynamically created from JSON object names with extractAllJSON. It is advisable to always set this attribute.

;handleRedirects
:enables the redirect handling inside HTTPMOD which should be used together with the cookie handling of HTTPMOD. HTTPMOD will then automatically follow redirects from a web server and keep track of cookies at the same time. It is advisable to always set this attribute.

;requestHeader.*
:Define an additional HTTP Header to set in the HTTP request

;requestData
:POST Data to be sent in the request. If not defined, it will be a GET request as defined in HttpUtils used by this module

;reading[0-9]+(-[0-9]+)?Name
:the name of a reading to extract with the corresponding readingRegex

;reading[0-9]*(-[0-9]+)?OExpr
:defines an expression that is used in an eval to compute the readings value. The raw value will be in the variable $val.

;reading[0-9]*(-[0-9]+)?OMap
:Output Map. Defines a mapping from raw to visible values like "0:mittig, 1:oberhalb, 2:unterhalb". If specified as readingOMap then the attribute value is a default for all other readings that don't specify an explicit reading[0-9]*OMap.

;reading[0-9]*(-[0-9]+)?Format
:Defines a format string that will be used in sprintf to format a reading value. If specified as readingFormat then the attribute value is a default for all other readings that don't specify an explicit reading[0-9]*Format.

;reading[0-9]*(-[0-9]+)?Decode
:defines an encoding to be used in a call to the perl function decode to convert the raw data string read from the device to a reading. This can be used if the device delivers strings in an encoding like cp850 instead of utf8.

;reading[0-9]*(-[0-9]+)?Encode
:defines an encoding to be used in a call to the perl function encode to convert the raw data string read from the device to a reading. This can be used if the device delivers strings in an encoding like cp850 and after decoding it you want to reencode it to e.g. utf8.

;reading[0-9]+Regex
:defines the regex to be used for extracting the reading. The value to extract should be in a capture group / sub expression
:e.g. ([\d\.]+) in the above example. Multiple capture groups will create multiple readings (see explanation above)

;reading[0-9]+XPath
:defines an xpath to one or more readings when parsing HTML data (see examples below)

;reading[0-9]+XPath-Strict
:defines an xpath to one or more readings when parsing XML data (see examples below)

;reading[0-9]+JSON
:defines a path to the JSON object wanted by concatenating the object names with an underscore as delimiter (see the example below)

;noShutdown
:pass the noshutdown flag to HTTPUtils for webservers that need it (some embedded webservers only deliver empty pages otherwise)

;disable
:stop doing automatic HTTP requests while this attribute is set to 1

;timeout
:time in seconds to wait for an answer. Default value is 2

;do_not_notify

;readingFnAttributes

== Simple Configuration of HTTP Devices ==
If your device expects special HTTP-headers then specify them as <code>attr requestHeader1</code> to <code>attr requestHeaderX</code>.
If your Device expects an HTTP POST instead of HTTP GET then the POST-data can be specified as <code>attr requestData</code>.
To get the readings, specify pairs of <code>attr readingXName</code> and <code>attr readingXRegex</code>, <code>attr readingXXPath</code>, <code>attr readingXXPath-Strict</code> or <code>attr readingXJSON</code> to define which readings you want to extract from the HTTP response and how to extract them. (The old syntax <code>attr readingsNameX</code> and <code>attr readingsRegexX</code> is still supported but the new one with <code>attr readingXName</code> and <code>attr readingXRegex</code> should be preferred. The actual values to be extracted have to be sub expressions within () in the regex (see example below)

=== Example for a PoolManager 5: ===
The PoolManager Web GUI can be queried with HTTP POST Requests like this one:

<syntaxhighlight lang="perl">
POST /cgi-bin/webgui.fcgi HTTP/1.1
Host: 192.168.70.90
Accept: */*
Content-Type: application/json;charset=UTF-8
Content-Length: 60

{"get" :["34.4001.value" ,"34.4008.value" ,"34.4033.value"]}
</syntaxhighlight>

The resulting HTTP Response would look like this:

<syntaxhighlight lang="perl">
HTTP/1.1 200 OK
Content-type: application/json; charset=UTF-8
Expires: 0
Cache-Control: no-cache
Date: Sun, 12 Jan 2014 12:23:11 GMT
Server: lighttpd/1.4.26
Content-Length: 179

{
"data": {
"34.4001.value": "7.00",
"34.4008.value": "0.52",
"34.4033.value": "24.8"
},
"status": {
"code": 0
},
"event": {
"type": 1,
"data": "48.30000.0"
}
}
</syntaxhighlight>

To configure HTTPMOD for a PoolManager one would first define a PoolManager device with e.g. the name PM, the URL and an interval of e.g. 60 seconds.

Then the data to be sent in the request needs to be defined because in this example the device expects a POST request so the query is not contained in the URL but in the request data.

Also as seen above the device expects special HTTP headers in the request so these headers also need to be defined as <code>attr PM requestHeader1</code> and <code>attr PM requestHeader2</code>

Then the names of the readings to be extracted would be set with attributes

Then for each reading value to be extracted a regular expression needs to be set that will match the value in question within ().

Example:
<syntaxhighlight lang="perl">
define PM HTTPMOD http://MyPoolManager/cgi-bin/webgui.fcgi 60

attr PM enableControlSet 1
attr PM enableCookies 1
attr PM enforceGoodReadingNames 1
attr PM handleRedirects 1

attr PM reading01Name PH
attr PM reading01Regex 34.4001.value":[ \t]+"([\d\.]+)"

attr PM reading02Name CL
attr PM reading02Regex 34.4008.value":[ \t]+"([\d\.]+)"

attr PM reading03Name3TEMP
attr PM reading03Regex 34.4033.value":[ \t]+"([\d\.]+)"

attr PM requestData {"get" :["34.4001.value" ,"34.4008.value" ,"34.4033.value", "14.16601.value", "14.16602.value"]}
attr PM requestHeader1 Content-Type: application/json
attr PM requestHeader2 Accept: */*
attr PM stateFormat {sprintf("%.1f Grad, PH %.1f, %.1f mg/l Chlor", ReadingsVal($name,"TEMP",0), ReadingsVal($name,"PH",0), ReadingsVal($name,"CL",0))}
</syntaxhighlight>

=== Example for AmbientMonitor ===
AmbientMonitor is a webbased visualisation for sensors connected to an Arduino device. Its web interface can also be queried with HTTMOD to grab the data into readings.

This example was provided by locutus. The hardware configuration is an Arduino + Ethercard with ENC28J60 Controller + DHT22 Sensor and software can be downloaded from https://github.com/lucadentella/AmbientMonitor

In this example an HTTP GET is sufficent, so no <code>requestData</code> is needed. The device provides temperature and humidity readings in an HTTP response that looks like:
<syntaxhighlight lang="perl">
HTTP/1.0 200 OK
Content-Type: text/html

myCB({'temperature':22.00,'humidity':46.00})
</syntaxhighlight>

the definition could be:
<syntaxhighlight lang="perl">
define AmbientMonitor HTTPMOD http://192.168.1.221/?callback=? 300

attr AmbientMonitor enableControlSet 1
attr AmbientMonitor enableCookies 1
attr AmbientMonitor enforceGoodReadingNames 1
attr AmbientMonitor handleRedirects 1

attr AmbientMonitor requestHeader Content-Type: application/json
attr AmbientMonitor reading1Name Temperatur
attr AmbientMonitor reading1Regex temperature':([\d\.]+)
attr AmbientMonitor reading2Name Feuchtigkeit
attr AmbientMonitor reading2Regex humidity':([\d\.]+)
attr AmbientMonitor stateFormat {sprintf("Temperatur %.1f C, Feuchtigkeit %.1f %", ReadingsVal($name,"Temperatur",0), ReadingsVal($name,"Feuchtigkeit",0))}
</syntaxhighlight>

== formatting and manipulating values / readings ==
Values that are parsed from an HTTP response can be further treated or formatted with the following attributes:

* <code>(reading|get)[0-9]*(-[0-9]+)?OExpr</code>
* <code>(reading|get)[0-9]*(-[0-9]+)?OMap</code>
* <code>(reading|get)[0-9]*(-[0-9]+)?Format</code>
* <code>(reading|get)[0-9]*(-[0-9]+)?Decode</code>
* <code>(reading|get)[0-9]*(-[0-9]+)?Encode</code>

They can all be specified for an individual reading, for all readings in one match (e.g. if a regular expression has several capture groups) or for all readings in a get command (defined by getXX) or for all readings in the main reading list (defined by readingXX):
<syntaxhighlight lang="perl">
reading01Format %.1f
</syntaxhighlight>

will format the reading with the name specified by the attribute reading01Name to be numerical with one digit after the decimal point.
If the attribute reading01Regex is used and contains several capture groups then the format will be applied to all readings parsed by this regex unless these readings have their own format specified by reading01-1Format, reading01-2Format and so on.

<syntaxhighlight lang="perl">
reading01-2Format %.1f
</syntaxhighlight>

Can be used in cases where a regular expression specified as reading01regex contains several capture groups or an xpath specified as reading01XPath creates several readings.
In this case reading01-2Format specifies the format to be applied to the second match.

<syntaxhighlight lang="perl">
readingFormat %.1f
</syntaxhighlight>

applies to all readings defined by a reading-Attribute that have no more specific format.

If you need to do some calculation on a raw value before it is used as a reading, you can define the attribute <code>readingOExpr</code>.
It defines a Perl expression that is used in an eval to compute the readings value. The raw value will be in the variable $val.

Example for an expression:
<syntaxhighlight lang="perl">
attr PM reading03OExpr $val * 10
</syntaxhighlight>
Just like in the above example of the readingFormat attributes, readingOExpr and the other following attributes can be applied on several levels.

To map a numerical value to a name, you can use the readingOMap attribute.
It defines a mapping from raw to visible values like "0:mittig, 1:oberhalb, 2:unterhalb".

Example for a map:
<syntaxhighlight lang="perl">
attr PM reading02-3OMap 0:kalt, 1:warm, 2:sehr warm
</syntaxhighlight>

To convert character sets, the module can first decode a string read from the device and then encode it again. For example:
<syntaxhighlight lang="perl">
attr PM getDecode UTF-8
</syntaxhighlight>

This applies to all readings defined for Get-Commands.

== Some help with Regular Expressions ==
{{Randnotiz|RNTyp=y|RNText=Starting with version ''2018-02-10'' the internal that holds the HTTP response is no longer called '''''buf''''' but rather '''''httpbody''''', and it is only displayed when attribute '''''showBody''''' is set to "1".}}
If HTTPMOD seems not to work and the FHEM Logfile contains a message like
:<code>HTTPMOD: Response didn't match Reading ...</code>
then you should check if the value you want to extract is read into the internal with the name buf. Internals are visible when you click on the defined HTTPMOD Device. buf is an internal variable that contains the HTTP Response read. If the value is there and you get the mentioned message then probably something is wrong with your regular expression. Please note that buf might contain special characters like newlines but they are not shown in fhemweb. If you are new to regular expressions then the introduction at http://perldoc.perl.org/perlretut.html might be helpful.

For a typical HTTPMOD use case where you want to extract a number out of a HTTP-Response you can use something like <code>[\d\.]+</code> to match the number itself. The expression matches the number characters (<code>\d</code>) or a <code>.</code> if one of these characters occurs at least once.

To tell HTTPMOD that the number is what you want to use for the reading, you have to put the expression in between <code>()</code>. A <code>([\d\.]+)</code> alone would match the longest number in the HTTP Response which is very likely not the number you are looking for so you need to add something to the expression to give it a context and define how to find the number that you are looking for.

If there is a title text before the number or a special text after the number you can put this in the regex. In one of the examples above <code>humidity':([\d\.]+)</code> is looking for the number that immediately follows the text <code>humidity':</code> without any blanks in between.
Be careful if the text you are getting from your device contains special characters like newline. You don't see such special characters in the fhem webinterface as contents of the internal buf but they might cause your regular expression to fail.

If you have trouble defining a regular expression that matches a certain name, then many complicated characters and then a number, it might be helpful to use a negation in matching like <code>temp[^\d]+([\d\.]).*</code>. In this examle <code>[^\d]+</code> means any character that is not a numerical digit, more than once.

=== Regular Expressions with multiple capture Groups ===
The regular expressions used in the above example for a Poolmanager will take the value that matches one capture group. This is the part of the regular expression inside (). In the above example "([\d\.]+)" refers to numerical digits or points between double quotation marks. Only the string consiting of digits and points will match inside (). This piece is assigned to the reading.

You can also use regular expressions that have several capture groups which might be helpful when parsing tables. In this case an attribute like

<syntaxhighlight lang="perl">
reading02Regex something[ \t]+([\d\.]+)[ \t]+([\d\.]+)
</syntaxhighlight>

could match two numbers. When you specify only one reading02Name like
<syntaxhighlight lang="perl">
reading02Name Temp
</syntaxhighlight>

the name Temp will be used with the extension -1 and -2 thus giving a reading Temp-1 for the first number and Temp-2 for the second. You can also specify individual names for several readings that get parsed from one regular expression with several capture groups by defining attributes

<syntaxhighlight lang="perl">
reading02-1Name
reading02-2Name
...
</syntaxhighlight>
The same notation can be used for formatting attributes like readingXOMap, readingXFormat and so on.

The usual way to define readings is however to have an individual regular expression with just one capture group per reading as shown in the above example.

== Parsing JSON ==

If a webservice delivers data in JSON format, HTTPMOD can directly parse JSON which might be easier in this case than definig regular expressions.
The next example shows the data that can be requested from a Poolmanager with the following partial configuration:

<syntaxhighlight lang="perl">
define test2 HTTPMOD none 0
attr test2 get01Name Chlor
attr test2 getURL http://192.168.70.90/cgi-bin/webgui.fcgi
attr test2 getHeader1 Content-Type: application/json
attr test2 getHeader2 Accept: */*
attr test2 getData {"get" :["34.4008.value"]}
</syntaxhighlight>

The data in the HTTP response looks like this:

<syntaxhighlight lang="perl">
{
"data": {
"34.4008.value": "0.25"
},
"status": {
"code": 0
},
"event": {
"type": 1,
"data": "48.30000.0"
}
}
</syntaxhighlight>

the classic way to extract the value 0.25 into a reading with the name Chlor with a regex would have been
<syntaxhighlight lang="perl">
attr test2 get01Regex 34.4008.value":[ \t]+"([\d\.]+)"
</syntaxhighlight>

with JSON you can write
<syntaxhighlight lang="perl">
attr test2 get01JSON data_34.4008.value
</syntaxhighlight>
which will create a reading with the Name "Chlor" (as shown above) and take the value 0.25 from the JSON string.

or if you don't care about the naming of your readings, you can simply extract all JSON data with
<syntaxhighlight lang="perl">
attr test2 extractAllJSON
</syntaxhighlight>

which would apply to all data read from this device and create the following readings out of the HTTP response shown above:

{| class="wikitable"
| data_34.4008.value || 0.25
|-
| event_data || 48.30000.0
|-
| event_type || 1
|-
| status_code || 0
|}

or you can specify
<syntaxhighlight lang="perl">
attr test2 get01ExtractAllJSON
</syntaxhighlight>
which would only apply to all data read as response to the get command defined as get01.

It might seem very simple at first sight to use extractAllJSON but if you prefer readings with a meaningful name you should instead define these readings with readingXXName and readingXXJSON or getXXName and getXXJSON individually. Of Course it would be possible to create additional user readings outside HTTPMOD but doing calculations, naming and formatting inside HTTPMOD is more efficient.

=== JSON Lists ===

imagine the HTTP Response contains:

<syntaxhighlight lang="perl">
{ "power":"0",
"modes":["Off","SimpleColor","RainbowChase"],
"code1":3,
"code2":4
}
</syntaxhighlight>

then a configuration like

<syntaxhighlight lang="perl">
attr device reading01JSON modes
attr device reading01Name Mode
</syntaxhighlight>

will create a list of Subreadings just like a regex with multiple matches can create multiple subreadings:

{| class="wikitable"
| Mode-1 || Off
|-
| Mode-2 || SimpleColor
|-
| Mode-3 || RainbowChase
|}

if you don't want several subreadings but one reading that contains the list of modes, you can specify a recombine expression:

<syntaxhighlight lang="perl">
attr device reading01Name Modes
attr device reading01RecombineExpr join ",", @matchlist
</syntaxhighlight>

which will create one reading containing a list:

{| class="wikitable"
| Modes || Off,SimpleColor,RainbowChase
|}

JSON parsing specifications also don't Need to match exactly. If there is no exact match for a defined reading, the HTTPMOD will try to Interpret the specification as a regex and look for json object paths that match the specification as a regex. For example:

<syntaxhighlight lang="perl">
attr device reading01Name CodeElem
attr device reading01JSON code
</syntaxhighlight>

which will create a list of readings:

{| class="wikitable"
| CodeElem-1|| 3
|-
| CodeElem-2 || 4
|}

and of course they could also be recombined into one reading with a RecombineExpr Attribute.

== Parsing http / XML using xpath ==
Another alternative to regex parsing is the use of XPath to extract values from HTTP responses.
The following example shows how XML data can be parsed with XPath-Strict or HTML Data can be parsed with XPath.
Both work similar and the example uses XML Data parsed with the XPath-Strict option:

If The XML data in the HTTP response looks like this:

<syntaxhighlight lang="xml">
<root xmlns:foo="http://www.foo.org/" xmlns:bar="http://www.bar.org">
<actors>
<actor id="1">Peter X</actor>
<actor id="2">Charles Y</actor>
<actor id="3">John Doe</actor>
</actor>
</root>
</syntaxhighlight>

with XPath you can write
<syntaxhighlight lang="perl">
attr htest reading01Name Actor
attr htest reading01XPath-Strict //actor[2]/text()
</syntaxhighlight>

This will create a reading with the Name "Actor" and the value "Charles Y".

Since XPath specifications can define several values / matches, HTTPMOD can also interpret these and store them in multiple readings:
<syntaxhighlight lang="perl">
attr htest reading01Name Actor
attr htest reading01XPath-Strict //actor/text()
</syntaxhighlight>

will create the readings

{| class="wikitable"
| Actor-1 || Peter X
|-
| Actor-2 || Charles Y
|-
| Actor-3 || John Doe
|}

== Further replacements of URL, header or post data ==
sometimes it might be helpful to dynamically change parts of a URL, HTTP header or post data depending on existing readings, internals or
perl expressions at runtime. This might be needed to pass further variables to a server, a current date or other things.

To support this HTTPMOD offers generic replacements that are applied to a request before it is sent to the server. A replacement can be defined with the attributes

* <code>replacement[0-9]*Regex</code>
* <code>replacement[0-9]*Mode</code>
* <code>replacement[0-9]*Value</code>
* <code>[gs]et[0-9]*Replacement[0-9]*Value</code>

a replacement always replaces a match of a regular expression.

'''replacement[0-9]*Mode:'''
The way the replacement value is defined can be specified with the replacement mode.
* If the <code>replacement[0-9]*Mode</code> is <code>reading</code>, then the corresponding <code>replacement[0-9]*Value</code> is interpreted as the name of a ''reading'' of the same device or as ''device:reading'' to refer to another device.
* If the <code>replacement[0-9]*Mode</code> is <code>internal</code>, then the corresponding <code>replacement[0-9]*Value</code> is interpreted as the name of an ''internal'' of the same device or as ''device:internal'' to refer to another device.
* If the <code>replacement[0-9]*Mode</code> is <code>text</code>, then the corresponding <code>replacement[0-9]*Value</code> is interpreted as a static text
* If the <code>replacement[0-9]*Mode</code> is <code>expression</code>, then the corresponding <code>replacement[0-9]*Value</code> is evaluated as a perl expression to compute the replacement. Inside such a replacement expression it is possible to refer to capture groups of the replacement regex.
* If the <code>replacement[0-9]*Mode</code> is <code>key</code>, then the module will use a value from a key / value pair that is stored in an obfuscated form in the file system with the set storeKeyValue command. This might be useful for storing passwords.

Example:

<syntaxhighlight lang="perl" line="1">
attr mydevice getData {"get" :["%%value%%.value"]}
attr mydevice replacement01Mode text
attr mydevice replacement01Regex %%value%%

attr mydevice get01Name Chlor
attr mydevice get01Replacement01Value 34.4008

attr mydevice get02Name Something
attr mydevice get02Replacement01Value 31.4024

attr mydevice get05Name profile
attr mydevice get05URL http://www.mydevice.local/getprofile?password=%%password%%
attr mydevice replacement02Mode key
attr mydevice replacement02Regex %%password%%
attr mydevice replacement02Value password
</syntaxhighlight>

defines that <code>%%value%%</code> will be replaced by a static text.

All Get commands will be HTTP post requests of a similar form. Only the <code>%%value%%</code> will be different from get to get.
The first get will set the reading named Chlor and for the request it will take the generic getData and replace %%value%% with 34.4008.

A second get will look the same except a different name and replacement value.

With the command <code>set mydevice storeKeyValue password geheim</code> you can store the password geheim in an obfuscated form in the file system.
To use this password and send it in a request you can use the above replacement with mode key. The value password will then refer to the ofuscated string stored with the key password.

The mode <code>expression</code> allows you to define your own replacement syntax:
<syntaxhighlight lang="perl">
attr mydevice replacement01Mode expression
attr mydevice replacement01Regex {{([^}]+)}}
attr mydevice replacement01Value ReadingsVal("mydevice", $1, "")
attr mydevice getData {"get" :["{{temp}}.value"]}
</syntaxhighlight>

In this example any <code><nowiki>{{name}}</nowiki></code> in a URL, header or post data will be passed on to the perl function ReadingsVal
which uses the string between <code><nowiki>{{}}</nowiki></code> as second parameter. This way one defined replacement can be used for many different
readings.

HTTPMOD has two built in replacements: One for session Ids and another one for the input value in a set command.
The placeholder $sid is always replaced with the internal <code>$hash->{sid}</code> which contains the session id after it is extracted from a previous HTTP response.
If you don't like to use the placeholder $sid then you can define your own replacement for example like:

<syntaxhighlight lang="perl">
attr mydevice replacement01Mode internal
attr mydevice replacement01Regex %session%
attr mydevice replacement01Value sid
</syntaxhighlight>

Now the internal <code>$hash->{sid}</code> will be used as a replacement for the placeholder %session%.

In the same way a value that is passed to a set-command can be put into a request with a user defined replacement.
In this case the internal <code>$hash->{value}</code> will contain the value passed to the set command.
<code>$hash->{value}</code> might even be a string containing several values that could be put into several different positions in a request by using user defined replacements.

'''Other example : steering a pellet stove from Rika'''

The stove API of Rika on https://www.rika-firenet.com/web/ delivers a JSON string with all settings and values, and can be piloted with a data string containing all the "set" values at once.

Delivered JSON on get https://www.rika-firenet.com/api/client/xxxxxxxx/status : (xxxxxxxx must be replaced with the unique stove ID)
<syntaxhighlight lang="perl">
{
"name": "Vorzimmer",
"stoveID": "xxxxxxxxx",
"lastSeenMinutes": 1,
"lastConfirmedRevision": 1504385700,
"controls": {
"revision": 1504385700,
"onOff": true,
"operatingMode": 2,
"heatingPower": 65,
"targetTemperature": 24,
"heatingTimesActive": false,
"heatingTimesActiveForComfort": true,
"setBackTemperature": 18,
"convectionFan1Active": false,
"convectionFan1Level": 0,
"convectionFan1Area": 0,
"convectionFan2Active": false,
"convectionFan2Level": 0,
"convectionFan2Area": 0,
"frostProtectionActive": false,
"frostProtectionTemperature": 5
},
"sensors": {
"statusError": 0,
"statusWarning": 0,
"statusService": 0,
"statusMainState": 1,
"statusSubState": 3,
"statusFrostStarted": false,
"inputFlameTemperature": 21,
"inputRoomTemperature": 21,
"inputExternalRequest": true,
"outputDischargeMotor": 0,
"outputInsertionMotor": 0,
"outputIDFan": 0,
"outputAirFlaps": 0,
"outputIgnition": false,
"parameterStoveTypeNumber": 13,
"parameterVersionMainBoard": 223,
"parameterVersionTFT": 223,
"parameterRuntimePellets": 11,
"parameterRuntimeLogs": 0,
"parameterFeedRateTotal": 17,
"parameterFeedRateService": 683,
"parameterOnOffCycles": 2
},
"stoveType": "DOMO MultiAir",
"stoveFeatures": {
"multiAir1": true,
"multiAir2": true,
"insertionMotor": false,
"airFlaps": false,
"logRuntime": false
}
}
</syntaxhighlight>

Data string to send to https://www.rika-firenet.com/api/client/xxxxxxxx/controls in order to set values:
<syntaxhighlight lang="perl">
heatingTimesActiveForComfort=true&frostProtectionTemperature=3&setBackTemperature=18&targetTemperature=24&convectionFan2Level=0&convectionFan2Active=false&convectionFan1Level=0&onOff=true&convectionFan1Active=false&convectionFan2Area=0&revision=1505550101&heatingTimesActive=false&convectionFan1Area=0&frostProtectionActive=false&operatingMode=2&heatingPower=65
</syntaxhighlight>

Code in 99_myUtils.pm:
<syntaxhighlight lang="perl">
use JSON;
...
sub
replaceJSON ($$) {
my ($valToReplace, $value) = @_;

#$value in the parameters is a default value
#It has to be replaced through the real value nnn passed in the set command "set <device> valToset nnn"
$value = InternalVal("Ofen", "value", $value);
Log3 ("Ofen", 3, "replaceJSON Internalvalue: $value");

#Force an update to avoid outdated revision number
fhem ("get Ofen revision");

#Get all the controls as json
my $json = ReadingsVal("Ofen", "controlsJSON","");
Log3 ("Ofen", 3, "replaceJSON configsJSON: $json");

# When starting FHEM or rereading config, the reading controlsJSON is empty
return if ($json eq "");

my $decoded = decode_json($json);
my $result;
for my $key ( keys %$decoded ) {
$result .= "$key=";
if ($key eq $valToReplace) {
$result .= $value."&";
} else {
$result .= $decoded->{$key}."&";
}
}
chop($result); #remove last &
Log3("Ofen", 3, "replaceJSON Result: $result");
return $result;
}
</syntaxhighlight>

Define stove in fhem:
<syntaxhighlight lang="perl">
defmod Ofen HTTPMOD https://www.rika-firenet.com/api/client/xxxxxxxx/status 60

attr Ofen enableCookies 1
attr Ofen reAuthRegex id="login"|Unauthorized
attr Ofen sid01Data email=xx@xx&password=xx
attr Ofen sid01URL https://www.rika-firenet.com/web/login

attr Ofen reading01JSON sensors_inputRoomTemperature
attr Ofen reading01Name RaumTemp
attr Ofen reading02JSON controls_setBackTemperature
attr Ofen reading02Name Absenkung
attr Ofen reading03JSON controls_frostProtectionTemperature
attr Ofen reading03Name Frostschutz
attr Ofen reading10Name controlsJSON
attr Ofen reading10Regex (?s)controls.*?({.*?})

attr Ofen get09Name revision
attr Ofen get09URL https://www.rika-firenet.com/api/client/xxxxxxxx/status

attr Ofen setURL https://www.rika-firenet.com/api/client/xxxxxxxx/controls
attr Ofen setData {{data}}
attr Ofen replacement01Mode expression
attr Ofen replacement01Regex {{data}}

attr Ofen set11Name frostProtectionTemperature
attr Ofen set11Replacement01Value replaceJSON("frostProtectionTemperature", 2)

attr Ofen set12Name targetTemperature
attr Ofen set12Replacement01Value replaceJSON("targetTemperature", 24)
</syntaxhighlight>

A detailed explanation (in german) of the login process can be found here: [https://forum.fhem.de/index.php/topic,76220.msg682514.html#msg682514]
and the explanation of the other parameters here: [https://forum.fhem.de/index.php/topic,76220.msg685710.html#msg685710]

== replacing reading values when they have not been updated / the device did not respond ==
If a device does not respond then the values stored in readings will keep the same and only their timestamp shows that they are outdated.
If you want to modify reading values that have not been updated for a number of seconds, you can use the attributes

* <code>(reading|get)[0-9]*(-[0-9]+)?MaxAge</code>
* <code>(reading|get)[0-9]*(-[0-9]+)?MaxAgeReplacementMode</code>
* <code>(reading|get)[0-9]*(-[0-9]+)?MaxAgeReplacement</code>

Every time the module tries to read from a device, it will also check if readings have not been updated
for longer than the <code>MaxAge</code> attributes allow. If readings are outdated, the <code>MaxAgeReplacementMode</code> defines how the affected
reading values should be replaced. <code>MaxAgeReplacementMode</code> can be <code>text</code>, <code>reading</code>, <code>internal</code>, <code>expression</code> or <code>delete</code>.

<code>MaxAge</code> specifies the number of seconds that a reading should remain untouched before it is replaced.

<code>MaxAgeReplacement</code> contains either a static text that is used as replacement value or a Perl expression that is evaluated to
give the replacement value. This can be used for example to replace a temperature that has not bee updated for more than 5 minutes
with the string "outdated - was 12":
<syntaxhighlight lang="perl">
attr PM readingMaxAge 300
attr PM readingMaxAgeReplacement "outdated - was " . $val
attr PM readingMaxAgeReplacementMode expression
</syntaxhighlight>
The variable <code>$val</code> contains the value of the reading before it became outdated.

Or to show that a device was offline:
<syntaxhighlight lang="perl">
attr MyLight reading01Name color
attr MyLight reading01JSON result_02_color
attr MyLight reading01MaxAge 300
attr MyLight reading01MaxAgeReplacement "offline"
attr MyLight reading01MaxAgeReplacementMode text
</syntaxhighlight>

== Note on determining how to send requests to a special device ==
If you don't know which URLs, headers or POST data your web GUI uses, you might try a local proxy like BurpSuite [http://portswigger.net/burp/ BurpSuite] to track requests and responses. This is a tedious task but probably the best way to achieve a successful result.

Let us consider an example. The Telekom Speedport W724V has a login-site that is famous for being cumbersome. Burp allows to monitor each step in the login procedure. In the case of a speedport the following steps occur:

First burp shows that a get command is issued
##################################################################################################
GET / HTTP/1.1
Host: speedport.ip
Cache-Control: max-age=0
Upgrade-Insecure-Requests: 1
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/57.0.2987.133 Safari/537.36
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8
Accept-Language: de-DE,de;q=0.8,en-US;q=0.6,en;q=0.4
Cookie: lang=de
Connection: close
In order to mimic the behavior of a real person calling the website HTTPMOD should copy all necessary steps. Host, Cookie and the GET-command are usually necessary. The same cannot be said of the User-Agent because the website can be called from any mobile or desktop computer.

Then, the speedport will answer with a command that consists of several lines. By going through every line for every step in the login procedure one will finally arrive at the information that is necessary to successfully enter the login of the speedport (in case of the W724V, for example, it is necessary to copy a token called _httoken and to include the referer).

== Advanced configuration to define a <code>set</code> command and send data to a device ==

When a set option is defined by attributes, the module will use the value given to the set command and integrate it into an HTTP-Request that sends the value to the device. The definitions for URL, headers and post data can contain the placeholder $val which will be replaced by the (numerical) value given to the set command.

This can be as simple as:
<syntaxhighlight lang="perl">
# No cyclic requests and no main URL needed in this example
define MyDevice HTTPMOD none 0

attr MyDevice set01Name Licht
attr MyDevice set01URL http://192.168.1.22/switch=$val
</syntaxhighlight>

A user command
<syntaxhighlight lang="perl">
set MyDevice Licht 1
</syntaxhighlight>

will be translated into the http GET request
<syntaxhighlight lang="perl">
http://192.168.1.22/switch=1
</syntaxhighlight>

In this example a map would also be helpful, that translates on / off to 0 or 1 and allows the user to select on/of in fhemweb:
<syntaxhighlight lang="perl">
attr MyDevive set01IMap 0:off, 1:on
</syntaxhighlight>
This also provides input validation to make sure that only on and off can be used with the set command.

In more complex Scenarios you might need to login before sending a command and the Login might create a session id that has to be part of further requests either in the URL, in headers or in the post data.

Extension to the above example for a PoolManager 5 where a set needs a session id in the URL and the values have to be passed in JSON strings as post data:
<syntaxhighlight lang="perl">
attr PM set01Name HeizungSoll
attr PM set01URL http://MyPoolManager/cgi-bin/webgui.fcgi?sid=$sid
attr PM set01Hint 6,10,20,30
attr PM set01Min 6
attr PM set01Max 30
attr PM setHeader1 Content-Type: application/json
attr PM set01Data {"set" :{"34.3118.value" :"$val" }}
</syntaxhighlight>

This example defines a set option with the name HeizungSoll.
By issuing <code>set PM HeizungSoll 10</code> in FHEM, the value 10 will be sent in the defined HTTP
Post to URL <code>http://MyPoolManager/cgi-bin/webgui.fcgi</code> in the Post Data as

<syntaxhighlight lang="html">
{"set" :{"34.3118.value" :"10" }}
</syntaxhighlight>

The optional attributes set01Min and set01Max define input validations that will be checked in the set function.
The optional attribute set01Hint will define a selection list for the FHEMweb GUI.

The HTTP response to such a request will be ignored unless you specify the attribute <code>setParseResponse</code>
for all set commands or <code>set01ParseResponse</code> for the set command with number 01.
If the HTTP response to a set command is parsed then this is done like the parsing of responses to get commands and you can use the attributes ending e.g. on Format, Encode, Decode, OMap and OExpr to manipulate / format the values read.

If a parameter to a set command is not numeric but should be passed on to the device as text, then you can specify the attribute setTextArg. For example:
<syntaxhighlight lang="perl">
attr PM set01TextArg
</syntaxhighlight>

If a set command should not require a parameter at all, then you can specify the attribute NoArg. For example:
<syntaxhighlight lang="perl">
attr PM set03Name On
attr PM set03NoArg
</syntaxhighlight>

This example defines the set of parameters for Wiesemann&Theiss Web-IO Analog 4.0 #57761. The current limit is set to 16mA (setxxMax)
<syntaxhighlight lang="Perl">
defmod WuT_Analog1 HTTPMOD none 30
attr WuT_Analog1 room W&T
attr WuT_Analog1 set01Max 16
attr WuT_Analog1 set01Min 0
attr WuT_Analog1 set01Name Output1
attr WuT_Analog1 set01URL http://192.xx.My_IP/outputaccess1?PW=MyPassword&State=$val&
attr WuT_Analog1 set02Max 16
attr WuT_Analog1 set02Min 0
attr WuT_Analog1 set02Name Output2
attr WuT_Analog1 set02URL http://192.xx.My_IP/outputaccess2?PW=MyPassword&State=$val&
</syntaxhighlight>

== Advanced configuration to create a valid session id that might be necessary ==
In simple cases logging in works with basic authentication. In the case HTTPMOD accepts a username and password as part of the URL in the form
<syntaxhighlight lang="perl">
http://User:Password@192.168.1.18/something
</syntaxhighlight>

However basic auth is seldom used. If you need to fill in a username and password in a HTML form and the session is then managed by a session id, here is how to configure this:

when sending data to an HTTP-Device in a set, HTTPMOD will replace any <code>$sid</code> in the URL, Headers and Post data with the internal <code>$hash->{sid}</code>. To authenticate towards the device and give this internal a value, you can use an optional multi step login procedure defined by the following attributes:

* <code>sid[0-9]*URL</code>
* <code>sid[0-9]*Data.*</code>
* <code>sid[0-9]*Header.*</code>
* <code>sid[0-9]*IgnoreRedirects</code>
* <code>idRegex</code>
* <code>idJSON</code>
* <code>idXPath</code>
* <code>idXPath-Strict</code>
* <code>(get|set|sid)[0-9]*IdRegex</code>
* <code>(get|set|sid)[0-9]*IdJSON</code>
* <code>(get|set|sid)[0-9]*IdXPath</code>
* <code>(get|set|sid)[0-9]*IdXPath-Strict</code>

Each step can have a URL, Headers, Post Data pieces and a Regex to extract a resulting Session ID into <code>$hash->{sid}</code>.
HTTPMOD will create a sorted list of steps (the numbers between sid and URL / Data / Header) and the loop through these steps and send the corresponding requests to the device. For each step a $sid in a Header or Post Data will be replaced with the current content of <code>$hash->{sid}</code>.

Using this feature, HTTPMOD can perform a forms based authentication and send user name, password or other necessary data to the device and save the session id for further requests.

To determine when this login procedure is necessary, HTTPMOD will first try to send a request without
doing the login procedure. If the result contains an error that authentication is necessary, then a login is performed.
To detect such an error in the HTTP response, you can again use a regular expression, JSON or XPath, this time with the attributes

* <code>reAuthRegex</code>
* <code>reAuthJSON</code>
* <code>reAuthXPath</code>
* <code>reAuthXPath-Strict</code>
* <code>(get|set)[0-9]*ReAuthRegex</code>
* <code>(get|set)[0-9]*ReAuthJSON</code>
* <code>(get|set)[0-9]*ReAuthXPath</code>
* <code>(get|set)[0-9]*ReAuthXPath-Strict</code>

reAuthJSON or reAuthXPath typically only extract one piece of data from a response.
If the existence of the specified piece of data is sufficent to start a login procedure, then nothing more needs to be defined to detect this situation.
If however the indicator is a status code that contains different values depending on a successful request and a failed request if a new authentication is needed,
then you can combine things like reAuthJSON with reAuthRegex. In this case the regex is only matched to the data extracted by JSON (or XPath).
This way you can easily extract the status code using JSON parsing and then specify the code that means "authentication needed" as a regular expression.

If for one step not all of the URL, Data or Header Attributes are set, then HTTPMOD tries to use a
<code>sidURL</code>, <code>sidData.*</code> or <code>sidHeader.*</code> Attribute (without the step number after sid). This way parts that are the same for all steps don't need to be defined redundantly.

=== Example for a multi step login procedure: ===
<syntaxhighlight lang="perl">
attr PM reAuthRegex /html/dummy_login.htm
attr PM sidURL http://192.168.70.90/cgi-bin/webgui.fcgi?sid=$sid
attr PM sidHeader1 Content-Type: application/json
attr PM sid1IDRegex wui.init\('([^']+)'
attr PM sid2Data {"set" :{"9.17401.user" :"fhem" ,"9.17401.pass" :"password" }}
attr PM sid3Data {"set" :{"35.5062.value" :"128" }}
attr PM sid4Data {"set" :{"42.8026.code" :"pincode" }}
</syntaxhighlight>

In this case HTTPMOD detects that a login is necessary by looking for the pattern /html/dummy_login.htm in the HTTP response.
If it matches, it starts a login sequence. In the above example all steps request the same URL. In step 1 only the defined Header is sent in an HTTP get request. The response will contain a session id that is extraced with the regex wui.init\('([^']+)'.

In the next step this session id is sent in a post request to the same URL where tha post data contains a username and password. The a third and a fourth request follow that set a value and a code. The result will be a valid and authorized session id that can be used in other requests where $sid is part of a URL, header or post data and will be replaced with the session id extracted above.

===Another Practical Example reading the SOC from a Renault Zoe===
<syntaxhighlight lang="perl">
define myZoe HTTPMOD https://www.services.renault-ze.com/api/vehicle/VINVINVIN/battery 7000
attr myZoe userattr reading01JSON reading01Name reading02JSON reading02Name reading03JSON reading03Nam\
e reading04JSON reading04Name reading05JSON reading05Name requestHeader02 sid1Data sid1Header01 sid1Id\
JSON sid1IgnoreRedirects:0,1 sid1URL
attr myZoe reAuthJSON message
attr myZoe reading01JSON charge_level
attr myZoe reading01Name SOC
attr myZoe reading02JSON charging
attr myZoe reading02Name charging
attr myZoe reading03JSON plugged
attr myZoe reading03Name plugged
attr myZoe reading04JSON remaining_range
attr myZoe reading04Name remaining_range
attr myZoe reading05JSON last_update
attr myZoe reading05Name last_update
attr myZoe requestHeader02 Authorization: Bearer $sid
attr myZoe sid1Data {"username":"ZEUSERNAME","password":"ZEPASSWORD"}
attr myZoe sid1Header01 Content-Type: application/json
attr myZoe sid1IdJSON token
attr myZoe sid1IgnoreRedirects 1
attr myZoe sid1URL https://www.services.renault-ze.com/api/user/login
attr myZoe timeout 10
#attr myZoe verbose 7
</syntaxhighlight>

The $sid is read by logging in with username and password from JSON {"token": ..} after detecting an error {"message": ..} from a failed request. This example offers no solution for the reading of the VIN from the login request, which in turn is part of the reading URL. It should be possible to read more than just the $sid from the login sequence.

In the special case where a session id is set as a HTTP-Cookie (with the header Set-cookie: in the HTTP response) HTTPMOD offers an even simpler way. With the attribute enableCookies a very basic cookie handling mechanism is activated that stores all cookies that the server sends to the HTTPMOD device and puts them back as cookie headers in the following requests.

For such cases no sidIdRegex and no $sid in a user defined header is necessary.

== Advanced configuration to define a <code>get</code> and request additional data with its own request from a device ==

The normal automatic HTTP request that is done repeatedly after the defined interval has elapsed works well in cases where all required readings can be requested in one common HTTP request. If however a device needs individual requests with different URLs or different POST data for each value, then another method is necessary.
For such cases a <code>get</code> option can be defined and the user can either issue FHEM <code>get</code> commands each time he needs the reading or the user can set an attribute to request the reading automatically together with the normal iteration.
For each <code>get</code> option attributes define an individual URL, optional headers, and post data as well as individual regular expressions and formatting options.

When a get option is defined by attributes, the module allows querying additional values from the device that require individual HTTP-Requests or special parameters to be sent

Extension to the above example:

<syntaxhighlight lang="perl">
attr PM get01Name MyGetValue
attr PM get01URL http://MyPoolManager/cgi-bin/directory/webgui.fcgi?special=1?sid=$sid
attr PM getHeader1 Content-Type: application/json
attr PM get01Data {"get" :{"30.1234.value"}}
</syntaxhighlight>

This example defines a get option with the name MyGetValue.
By issuing <code>get PM MyGetValue</code> in FHEM, the defined HTTP request is sent to the device.
The HTTP response is then parsed using the same readingXXName and readingXXRegex attributes as above so
additional pairs will probably be needed there for additional values.

if you prefer to define the parsing and formatting of readings individually per get command, you can use
attributes like get01Regex, get01XPath, get01Format, get01OMap and so on just like for reading01...

You can also include parameters / values that are passed to the get command in the request just like for set commands.
The placeholder $val will be replaced with the value given to the get command or you can specify your own replacement as described above.

If the new get parameter should also be queried regularly, you can define the following optional attributes:

<syntaxhighlight lang="perl">
attr PM get01Poll 1
attr PM get01PollDelay 300
</syntaxhighlight>

The first attribute includes this reading in the automatic update cycle and the second defines an alternative lower update frequency. When the interval defined initially in the define is over and the normal readings are read from the device, the update function will check for additional get parameters that should be included in the update cycle.

If a PollDelay is specified for a get parameter, the update function also checks if the time passed since it has last read this value is more than the given PollDelay. If not, this reading is skipped and it will be rechecked in the next cycle when interval is over again. So the effective PollDelay will always be a multiple of the interval specified in the initial define.

Please note that each defined get command that is included in the regular update cycle will create its own HTTP request. So if you want to extract several values from the same request, it is much more efficient to do this by defining readingXXName and readingXXRegex, XPath or JSON attributes and to specify an interval and a URL in the define of the HTTPMOD device.

Example for a Siemens webserver provided by Lanhydrock:
<syntaxhighlight lang="perl">
define ozw672 HTTPMOD https://192.168.178.8/api/auth/login.json?user=test&pwd=test 300

attr ozw672 get1Name tempAussen
attr ozw672 get1URL https://192.168.178.8/api/menutree/read_datapoint.json?SessionId=$sid&Id=1960
attr ozw672 get1Poll 1
attr ozw672 get1PollDelay 1800

attr ozw672 get2Name tempAussenGemischt
attr ozw672 get2URL https://192.168.178.8/api/menutree/read_datapoint.json?SessionId=$sid&Id=1964
attr ozw672 get2Poll 1
attr ozw672 get2PollDelay 1800

attr ozw672 get3Name tempTWW
attr ozw672 get3URL https://192.168.178.8/api/menutree/read_datapoint.json?SessionId=$sid&Id=1996
attr ozw672 get3Poll 1

attr ozw672 get4Name tempKesselSoll
attr ozw672 get4URL https://192.168.178.8/api/menutree/read_datapoint.json?SessionId=$sid&Id=1910
attr ozw672 get4Poll 1

attr ozw672 get5Name tempKesselRuecklauf
attr ozw672 get5URL https://192.168.178.8/api/menutree/read_datapoint.json?SessionId=$sid&Id=1915
attr ozw672 get5Poll 1

attr ozw672 get6Name tempKesselRuecklaufSoll
attr ozw672 get6URL https://192.168.178.8/api/menutree/read_datapoint.json?SessionId=$sid&Id=1916
attr ozw672 get6Poll 1

attr ozw672 get7Name anzahlStartsBrenner
attr ozw672 get7URL https://192.168.178.8/api/menutree/read_datapoint.json?SessionId=$sid&Id=1927
attr ozw672 get7PollDelay 1800
attr ozw672 get7Poll 1

attr ozw672 get8Name statusKessel
attr ozw672 get8URL https://192.168.178.8/api/menutree/read_datapoint.json?SessionId=$sid&Id=1898
attr ozw672 get8Poll 1
attr ozw672 get8Regex Value": "([a-zA-Zü ]*)"
attr ozw672 get8OMap Aus:0, Nachlauf aktiv:5, Freigegeben für TWW:10, Freigegeben für HK:20, In Teillastbetrieb für TWW:40, In Teillastbetrieb für HK:50, In Betrieb für Trinkwasser:90, In Betrieb für Heizkreis:100

attr ozw672 getRegex Value": "[ ]*([-.0-9]*)"

attr ozw672 reAuthRegex .*session not valid.*
attr ozw672 sid1IDRegex .*"(.*-.*-.*-[0-9a-z]*).*
attr ozw672 sid1URL https://192.168.178.8/api/auth/login.json?user=test&pwd=test
</syntaxhighlight>

== All attributes ==
;reading[0-9]+Name
:the name of a reading to extract with the corresponding readingRegex, readingJSON, readingXPath or readingXPath-Strict
:Please note that the old syntax <b>readingsName.*</b> does not work with all features of HTTPMOD and should be avoided. It might go away in a future version of HTTPMOD.

;(get|set)[0-9]+Name
:Name of a get or set command
:If the HTTP response that is received after the command is parsed with an individual parse option then this name is also used as a reading name. Please note that no individual parsing needs to be defined for a get or set. If no regex, XPath or JSON is specified for the command, then HTTPMOD will try to parse the response using all the defined readingRegex, reading XPath or readingJSON attributes.

;(get|set|reading)[0-9]+Regex
:If this attribute is specified, the Regex defined here is used to extract the value from the HTTP Response and assign it to a Reading with the name defined in the (get|set|reading)[0-9]+Name attribute.
:If this attribute is not specified for an individual Reading or get or set but without the numbers in the middle, e.g. as getRegex or readingRegex, then it applies to all the other readings / get / set commands where no specific Regex is defined.<br>
:The value to extract should be in a capture group / sub expression e.g. ([\d\.]+) in the above example. Multiple capture groups will create multiple readings (see explanation above)
:Using this attribute for a set command (setXXRegex) only makes sense if you want to parse the HTTP response to the HTTP request that the set command sent by defining the attribute setXXParseResponse.
:Please note that the old syntax <code>readingsRegex.*</code> does not work with all features of HTTPMOD and should be avoided. It might go away in a future version of HTTPMOD.
:If for get or set commands neither a generic Regex attribute without numbers nor a specific (get|set)[0-9]+Regex attribute is specified and also no XPath or JSON parsing specification is given for the get or set command, then HTTPMOD tries to use the parsing definitions for general readings defined in reading[0-9]+Name, reading[0-9]+Regex or XPath or JSON attributes and assigns the Readings that match here.

;(get|set|reading)[0-9]+RegOpt
:Lets the user specify regular expression modifiers. For example if the same regular expression should be matched as often as possible in the HTTP response, then you can specify RegOpt g which will case the matching to be done as /regex/g
:The results will be trated the same way as multiple capture groups so the reading name will be extended with -number.
:For other possible regular expression modifiers see http://perldoc.perl.org/perlre.html#Modifiers

;(get|set|reading)[0-9]+XPath
:defines an xpath to one or more values when parsing HTML data (see examples above)
:Using this attribute for a set command only makes sense if you want to parse the HTTP response to the HTTP request that the set command sent by defining the attribute setXXParseResponse.

;get|set|reading[0-9]+XPath-Strict
:defines an xpath to one or more values when parsing XML data (see examples above)
:Using this attribute for a set command only makes sense if you want to parse the HTTP response to the HTTP request that the set command sent by defining the attribute setXXParseResponse.

;(get|set|reading)[0-9]+AutoNumLen
:In cases where a regular expression or an XPath results in multiple results and these results are stored in a common reading name with extension -number, then you can modify the format of this number to have a fixed length with leading zeros. AutoNumLen 3 for example will lead to reading names ending with -001 -002 and so on.

;(get|set|reading)[0-9]+AlwaysNum
:if set to 1 this attributes forces reading names to end with a -1, -01 (depending on the above described AutoNumLen) even if just one value is parsed.

;get|set|reading[0-9]+JSON
:defines a path to the JSON object wanted by concatenating the object names. See the above example.
:If you don't know the paths, then start by using extractAllJSON and the use the names of the readings as values for the JSON attribute.<br>
:Please don't forget to also specify a name for a reading, get or set.
:Using this attribute for a set command only makes sense if you want to parse the HTTP response to the HTTP request that the set command sent by defining the attribute setXXParseResponse.

;(get|set|reading)[0-9]*RecombineExpr
:defines an expression that is used in an eval to compute one reading value out of the list of matches.
:This is supposed to be used for regexes or xpath specifications that produce multiple results if only one result that combines them is wanted. The list of matches will be in the variable @matchlist.
:Using this attribute for a set command only makes sense if you want to parse the HTTP response to the HTTP request that the set command sent by defining the attribute setXXParseResponse.

;get[0-9]*CheckAllReadings
:this attribute modifies the behavior of HTTPMOD when the HTTP Response of a get command is parsed. <br>
:If this attribute is set to 1, then additionally to the matching of the corresponding get specific regex (get[0-9]*Regex), XPath or JSON attribute also all the reading names and parse definitions defined in Reading[0-9]+Name and Reading[0-9]+Regex, XPath or JSON attributes are checked and if they match, the coresponding Readings are assigned as well.
:Please note that this does not mean that get01CheckAllReadings will cause a get02Regex to be used. Only the corresponding get01Regex will be used but additionally all the readingXYRegex attributes.
:This is automatically done if a get or set command is defined without its own parse attributes.

;(get|reading)[0-9]*OExpr
:defines an optional expression that is used in an eval to compute / format a readings value after parsing an HTTP response
:The raw value from the parsing will be in the variable $val.
:If specified as readingOExpr then the attribute value is a default for all other readings that don't specify an explicit reading[0-9]*Expr.
:Please note that the old syntax <b>readingsExpr.*</b> does not work with all features of HTTPMOD and should be avoided. It might go away in a future version of HTTPMOD.

;(get|reading)[0-9]*Expr
:This is the old syntax for (get|reading)[0-9]*OExpr. It should be replaced by (get|reading)[0-9]*OExpr. The set command upgradeAttributes which becomes visible when the attribute enableControlSet is set to 1, can do this renaming automatically.

;(get|reading)[0-9]*OMap
:Map that defines a mapping from raw value parsed to visible values like "0:mittig, 1:oberhalb, 2:unterhalb".
:If specified as readingOMap then the attribute value is a default for all other readings that don't specify an explicit reading[0-9]*Map.<br>
:The individual options in a map are separated by a komma and an optional space. Spaces are allowed to appear in a visible value however kommas are not possible.

;(get|reading)[0-9]*Map
:This is the old syntax for (get|reading)[0-9]*OMap. It should be replaced by (get|reading)[0-9]*OMap. The set command upgradeAttributes which becomes visible when the attribute enableControlSet is set to 1, can do this renaming automatically.

;(get|set|reading)[0-9]*Format
:Defines a format string that will be used in sprintf to format a reading value.
:If specified without the numbers in the middle e.g. as readingFormat then the attribute value is a default for all other readings that don't specify an explicit reading[0-9]*Format.
:Using this attribute for a set command only makes sense if you want to parse the HTTP response to the HTTP request that the set command sent by defining the attribute setXXParseResponse.<br>

;(get|set|reading)[0-9]*Decode
:defines an encoding to be used in a call to the perl function decode to convert the raw data string read from the device to a reading.
:This can be used if the device delivers strings in an encoding like cp850 instead of utf8.
:If your reading values contain Umlauts and they are shown as strange looking icons then you probably need to use this feature.
:Using this attribute for a set command only makes sense if you want to parse the HTTP response to the HTTP request that the set command sent by defining the attribute setXXParseResponse.

;(get|set|reading)[0-9]*Encode
:defines an encoding to be used in a call to the perl function encode to convert the raw data string read from the device to a reading.
:This can be used if the device delivers strings in an encoding like cp850 and after decoding it you want to reencode it to e.g. utf8.
:If your reading values contain Umlauts and they are shown as strange looking icons then you probably need to use this feature.
:Using this attribute for a set command only makes sense if you want to parse the HTTP response to the HTTP request that the set command sent by defining the attribute setXXParseResponse.

;(get|set)[0-9]*URL
:URL to be requested for the set or get command. If this option is missing, the URL specified during define will be used.

;(get|set)[0-9]*Data
:Data to be sent to the device as POST data when the get or set command is executed. if this attribute is not specified, an HTTP GET method will be used instead of an HTTP POST

;(get|set)[0-9]*NoData
:can be used to override a more generic attribute that specifies POST data for all get or set commands. With NoData no data is sent and therefor the request will be an HTTP GET.

;(get|set)[0-9]*Header.*
:HTTP Headers to be sent to the device when the set is executed

;requestHeader.*
:Define an optional additional HTTP Header to set in the HTTP request of the main loop

;requestData
:optional POST Data to be sent in the request of the main loop. If not defined, it will be an HTTP GET request as defined in HttpUtils which is used by this module

;get[0-9]+Poll
:if set to 1 the get is executed automatically during the normal update cycle (after the interval provided in the define command has elapsed)

;get[0-9]+PollDelay
:if the value should not be read in each iteration (after the interval given to the define command), then a minimum delay can be specified with this attribute. This has only an effect if the above Poll attribute has also been set. Every time the update function is called, it checks if since this get has been read the last time, the defined delay has elapsed. If not, then it is skipped this time.
:PollDelay can be specified as seconds or as x[0-9]+ which means a multiple of the interval in the define command.

;(get|set)[0-9]*TextArg
:For a get command this defines that the command accepts a text value after the option name. By default a get command doesn't accept optional values after the command name.
:If TextArg is specified and a value is passed after the get name then this value can then be used in a request URL, header or data as replacement for $val or in a user defined replacement that uses the internal "value" ($hash->{value}).
:If used for a set command then it defines that the value to be set doesn't require any validation / conversion.
:The raw value is passed on as text to the device. By default a set command expects a numerical value or a text value that is converted to a numeric value using a map.

;set[0-9]+Min
:Minimum value for input validation.

;set[0-9]+Max
:Maximum value for input validation.

;set[0-9]+IExpr
:Perl Expression to compute the raw value to be sent to the device from the input value passed to the set.

;set[0-9]+Expr
:This is the old syntax for (get|reading)[0-9]*IExpr. It should be replaced by (get|reading)[0-9]*IExpr. The set command upgradeAttributes which becomes visible when the attribute enableControlSet is set to 1, can do this renaming automatically.

;set[0-9]+IMap
:Map that defines a mapping from raw to input values like "0:mittig, 1:oberhalb, 2:unterhalb". This attribute atomatically creates a hint for FHEMWEB so the user can choose one of the input values.

;set[0-9]+Map
:This is the old syntax for (get|reading)[0-9]*IMap. It should be replaced by (get|reading)[0-9]*IMap. The set command upgradeAttributes which becomes visible when the attribute enableControlSet is set to 1, can do this renaming automatically.

;set[0-9]+Hint
:Explicit hint for fhemWEB that will be returned when set ? is seen. Can be used to get a slider or a list of values to choose from.

;set[0-9]*NoArg
:Defines that this set option doesn't require arguments. It allows sets like "on" or "off" without further values.

;set[0-9]*ParseResponse
:defines that the HTTP response to the set will be parsed as if it was the response to a get command.

;(get|set)[0-9]*URLExpr
:Defines a Perl expression to specify the HTTP Headers for this request. This overwrites any other header specification and should be used carefully only if needed. The original Header is availabe as $old. Typically this feature is not needed and it might go away in future versions of HTTPMOD. Please use the "replacement" attributes if you want to pass additional variable data to a web service.

;(get|set)[0-9]*DatExpr
:Defines a Perl expression to specify the HTTP Post data for this request. This overwrites any other post data specification and should be used carefully only if needed. The original Data is availabe as $old. Typically this feature is not needed and it might go away in future versions of HTTPMOD. Please use the "replacement" attributes if you want to pass additional variable data to a web service.

;(get|set)[0-9]*HdrExpr
:Defines a Perl expression to specify the URL for this request. This overwrites any other URL specification and should be used carefully only if needed. The original URL is availabe as $old. Typically this feature is not needed and it might go away in future versions of HTTPMOD. Please use the "replacement" attributes if you want to pass additional variable data to a web service.

;ReAuthRegex
:regular Expression to match an error page indicating that a session has expired and a new authentication for read access needs to be done.
:This attribute only makes sense if you need a forms based authentication for reading data and if you specify a multi step login procedure based on the sid.. attributes.
:This attribute is used for all requests. For set and get operations you can however specify individual reAuthRegexes with the (get|set)[0-9]*ReAuthRegex attributes.

;(get|set)[0-9]*ReAuthRegex
:Regex that will detect when a session has expired during a set operation and a new login needs to be performed.
:It works like the global reAuthRegex but is used for set operations.

;sid[0-9]*URL
:different URLs or one common URL to be used for each step of an optional login procedure.

;sid[0-9]*IDRegex
:different Regexes per login procedure step or one common Regex for all steps to extract the session ID from the HTTP response

;sid[0-9]*Data.*
:data part for each step to be sent as POST data to the corresponding URL

;sid[0-9]*Header.*
:HTTP Headers to be sent to the URL for the corresponding step

;sid[0-9]*IgnoreRedirects
:Tells the HttpUtils to not follow HTTP Redirects for this Request. Might be needed for some devices that set a session cookie within a 303 Redirect.

;clearSIdBeforeAuth
:will set the session id to "" before doing the authentication steps

;authRetries
:number of retries for authentication procedure - defaults to 1

;replacement[0-9]*Regex
:Defines a replacement to be applied to an HTTP request header, data or URL before it is sent. This allows any part of the request to be modified based on a reading, an internal or an expression.
:The regex defines which part of a header, data or URL should be replaced. The replacement is defined with the following attributes:

;replacement[0-9]*Mode
:Defines how the replacement should be done and what replacementValue means. Valid options are text, reading, internal and expression.

;replacement[0-9]*Value
:Defines the replacement. If the corresponding replacementMode is <code>text</code>, then value is a static text that is used as the replacement.
:If replacementMode is <code>reading</code> then Value can be the name of a reading of this device or it can be a reading of a different device referred to by devicename:reading.
:If replacementMode is <code>internal</code> the Value can be the name of an internal of this device or it can be an internal of a different device referred to by devicename:internal.
:If replacementMode is <code>expression</code> the the Value is treated as a Perl expression that computes the replacement value. The expression can use $1, $2 and so on to refer to capture groups of the corresponding regex that is matched against the original URL, header or post data.
:If replacementMode is <code>key</code> then the module will use a value from a key / value pair that is stored in an obfuscated form in the file system with the set storeKeyValue command. This might be useful for storing passwords.

;[gs]et[0-9]*Replacement[0-9]*Value
:This attribute can be used to override the replacement value for a specific get or set.

;get|reading[0-9]*MaxAge
:Defines how long a reading is valid before it is automatically overwritten with a replacement when the read function is called the next time.

;get|reading[0-9]*MaxAgeReplacement
:specifies the replacement for MaxAge - either as a static text or as a perl expression.

;get|reading[0-9]*MaxAgeReplacementMode
:specifies how the replacement is interpreted: can be text, expression and delete.

;get|reading[0-9]*DeleteIfUnmatched
:If set to 1 this attribute causes certain readings to be deleted when the parsing of the website does not match the specified reading. Internally HTTPMOD remembers which kind of operation created a reading (update, Get01, Get02 and so on). Specified readings will only be deleted if the same operation does not parse this reading again. This is especially useful for parsing that creates several matches / readings and the number of matches can vary from request to request. For example if reading01Regex creates 4 readings in one update cycle and in the next cycle it only matches two times then the readings containing the remaining values from the last round will be deleted.
:Please note that this mechanism will not work in all cases after a restart. Especially when a get definition does not contain its own parsing definition but ExtractAllJSON or relies on HTTPMOD to use all defined reading.* attributes to parse the responsee to a get command, old readings might not be deleted after a restart of fhem.
;get|reading[0-9]*DeleteOnError
:If set to 1 this attribute causes certain readings to be deleted when the website can not be reached and the HTTP request returns an error. Internally HTTPMOD remembers which kind of operation created a reading (update, Get01, Get02 and so on). Specified readings will only be deleted if the same operation returns an error.
The same restrictions as for DeleteIfUnmatched apply regarding a fhem restart.

;httpVersion
:defines the HTTP-Version to be sent to the server. This defaults to 1.0.

;sslVersion
:defines the SSL Version for the negotiation with the server. The attribute is evaluated by HttpUtils. If it is not specified, HttpUtils assumes SSLv23:!SSLv3:!SSLv2

;sslArgs
:defines a list that is converted to a key / value hash and gets passed to HttpUtils. To avoid certificate validation for broken servers you can for example specify
:<code>attr myDevice sslArgs SSL_verify_mode,SSL_VERIFY_NONE</code>

;alignTime
:Aligns each periodic read request for the defined interval to this base time. This is typcally something like 00:00 (see the FHEM at command)

;noShutdown
:pass the noshutdown flag to HTTPUtils for webservers that need it (some embedded webservers only deliver empty pages otherwise)

;disable
:stop doing automatic HTTP requests while this attribute is set to 1

;enableControlSet
:enables the built in set commands interval, stop, start, reread, upgradeAttributes, storeKeyValue.

;enableCookies
:enables the built in cookie handling if set to 1. With cookie handling each HTTPMOD device will remember cookies that the server sets and send them back to the server in the following requests.
:This simplifies session magamenet in cases where the server uses a session ID in a cookie. In such cases enabling cookies should be sufficient and no sidRegex and no manual definition of a cookie header should be necessary.

;showMatched
:if set to 1 then HTTPMOD will create a reading with the name MATCHED_READINGS that contains the names of all readings that could be matched in the last request as well as UNMATCHED_READINGS and LAST_REQUEST.

;showError
:if set to 1 then HTTPMOD will create a reading and event with the Name LAST_ERROR that contains the error message of the last error returned from HttpUtils.

;removeBuf
:if set to 1 then HTTPMOD removes the internal named buf when a HTTP-response has been received.
:$hash->{buf} is used internally be Fhem httpUtils and in some use cases it is desireable to remove this internal after reception
:because it contains a very long response which looks ugly in Fhemweb.

;timeout
:time in seconds to wait for an answer. Default value is 2

;queueDelay
:HTTP Requests will be sent from a queue in order to avoid blocking when several Requests have to be sent in sequence. This attribute defines the delay between calls to the function that handles the send queue. It defaults to one second.

;queueMax
:Defines the maximum size of the send queue. If it is reached then further HTTP Requests will be dropped and not be added to the queue

;minSendDelay
:Defines the minimum time between two HTTP Requests.

== Links ==
* Example: This example uses many features of HTTPMOD, universally useful is the access to other readings just like what [[Set magic|set-magic]] (<code>[device:reading]</code>) does [https://forum.fhem.de/index.php?topic=135666.0 🎸 Owntone (Musik-Player) mit FHEM steuern]
* Example: [https://www.goingelectric.de/forum/viewtopic.php?f=57&t=21462|Abfrage Akkustand einer Zoe und mehr von Renault ZE Services]
* Example: [[Wetter_und_Wettervorhersagen#Wetter_von_Weather_Underground|Extract weather information from WeatherUnderground]]
* Example: [[Pollenflug|Pollen count]]
* Example: [[HTTPMOD Beispielkonfiguration zur Anbindung einer Daikin Klimaanlage mit WLAN-Modul|Connect Daikin aircondition to FHEM]]
* Example: [[Go-eCharger|Extract information from go-eCharger]]
* Example: [[Sonnenspeicher|Integration of energy supplies from sonnen (https://sonnenbatterie.de/en/start)]]
* Example: [https://forum.fhem.de/index.php/topic,95989.msg915870.html#msg915870 Miele 3rd party API für Miele Smarthome Geräte]
* Example: [https://forum.fhem.de/index.php/topic,84215.msg918662.html#msg918662 Honeywell Evohome Totalconnect]
* Example: [https://forum.fhem.de/index.php/topic,78613.msg889015.html#msg889015 Tigo Energy Integration]
* Example: [https://forum.fhem.de/index.php/topic,78613.msg708518.html#msg708518 Ecowater]
* {{Link2Forum|Topic=17804|LinkText=Thread}} in FHEM Forum that discusses the first version of this module
* {{Link2Forum|Topic=29471|LinkText=Thread}} in FHEM Forum that discusses the second major version of this module
* {{Link2Forum|Topic=45176|LinkText=Thread}} in FHEM Forum that discusses the third major version of this module
* [http://perldoc.perl.org/perlretut.html Introduction to regular expressions]
* [http://portswigger.net/burp/ BurpSuite]: Tool (local proxy) to help analyze http traffic

[[Kategorie:IP Components]]

HTTPMOD

2025-04-05T08:53:56Z

Torxgewinde: /* Links */

{{Infobox Modul
|ModPurpose=Extract information from devices with an HTTP interface (or, more generic, from any URL) or send information to such devices
|ModType=d
|ModCmdRef=HTTPMOD
|ModForumArea=Sonstiges
|ModTechName=98_HTTPMOD.pm
|ModOwner=StefanStrobel ({{Link2FU|3960|Forum}} / [[Benutzer:StefanStrobel|Wiki]])
}}
[[HTTPMOD]] provides a generic way to retrieve information from devices with an HTTP Interface and store them in Readings or send information to such devices. It queries a given URL with Headers and data defined by attributes.

From the HTTP response it extracts readings named in attributes using Regexes, JSON or XPath parsing also defined by attributes.

In an advanced [[Konfiguration|configuration]] the module can also send information to devices. To do this, a generic <code>set</code> option can be configured using attributes.

== Introduction ==
With the help of HTTPMOD you can automatically access websites, retrieve information and send data. In the simplest case, an http call is started regularly and the content of a page, for example, is read and processed further. The URL and the time interval in which the call is to be made must then be specified when the call is made. In order to read information from the called web pages, readings are required. In this readings one specifies Regex, which reads the necessary information. Here is an example.

<syntaxhighlight lang="perl">
define PM HTTPMOD http://www.klack.de/fernsehprogramm/was-laeuft-gerade/0/-1/free.html 20000
</syntaxhighlight>

This creates a device that accesses the http://www.klack.de/fernsehprogramm/was-laeuft-gerade/0/-1/free.html website with the TV program every 20000 seconds. If neither readings nor other attributes are defined, then only the call of the website takes place and FHEM receives no further data from the web access.

But now a television program is returned when you call the website, which you might want to read out. In order to save the contents in FHEM, which are related to the ARD, you need a reading. This reading must contain a name (so that FHEM knows under which name the information is stored) and a regex (so that you know where the information is stored on the website). Since usually not one, but many readings are defined, these readings are numbered consecutively. This is done by numbers that are given immediately after the word reading. In our example this would be for example
<syntaxhighlight lang="perl">
attr PM reading1Name ARD
attr PM reading1Regex <span class="stationName">ARD<\/span>[\w\W]*?<div class="content">\s*<a[\w\W]*?>\s*(.*?)\s*<\/a>
attr PM reading2Name ARD_time
attr PM reading2Regex <span class="stationName">ARD<\/span>[\w\W]*?<td class="time">\s*(.*?)\s*<
attr PM reading3Name ARD_details
attr PM reading3Regex <span class="stationName">ARD<\/span>[\w\W]*?<div class="content">\s*<a[\w\W]*?>[\w\W]*?<\/a>\s*<br\/>\s*(.*?)(<img|<\/div)
</syntaxhighlight>

Reading1 contains the programme, reading2 the time and reading3 further details. The Regex result from the structure of the website and may have to be designed in painstaking detail.

There are cases where this is not enough. For example, it could be the case that the information from the web access is not automated, but manually received. Then a 0 must first be entered at the top of the duration. But how does HTTPMOD then know when the data should be retrieved? This is done with get-commands. If a get-command is executed, HTTPMOD accesses the website, fetches the information and fills the corresponding readings.

Again, it is possible to create not one but several get-commands. Therefore, get is always followed by (at least) one number with which the get commands are numbered. Here is another example. The TV program should be called manually and not time-controlled. To do this we first change the definition to
<syntaxhighlight lang="perl">
define PM HTTPMOD http://www.klack.de/fernsehprogramm/was-laeuft-gerade/0/-1/free.html 0
</syntaxhighlight>
and add the following to the attributes
<syntaxhighlight lang="perl">
attr PM get1Name ARDHolen
</syntaxhighlight>
With the command "get PM ARDHolen" the above readings are filled. In order for FHEM to know that the other reading2, reading3, etc. are to be read as well as reading1, the (user) attribute
<syntaxhighlight lang="perl">
attr PM get1CheckAllReadings 1
</syntaxhighlight>
needs to be defined.

If the URL is not sufficient when the web page is called, but a special header is to be sent with it, this can be done with the get1Header attribute. If the header is multiline, the individual lines can be entered with get1Header1, get1Header2, and so on.

If you want to evaluate or control different URLs, you can define several get commands (get1, get2, etc.) and provide them with your own URLs. get1 usually reads only the reading1, get2 reads only the reading2 and so on. With CheckAllReadings all readings are evaluated simultaneously.

If only data is to be sent on the web page, but not read, the set command is recommended. It has the same structure as the get-command.

It becomes a bit more complex if the website requires a login check. The sid attributes are used for this purpose.

== Availability, prerequisites and definition ==
This module is part of the regular FHEM distribution and uses the non blocking HTTP function <code>HttpUtils_NonblockingGet</code> provided by FHEM's [[HttpUtils]] in a new version published in December 2013.
If not already installed in your environment, please [[update]] FHEM or install it manually using appropriate commands from your environment.
Please also note that FHEM HttpUtils need the global attribute dnsServer to be set in order to work really non blocking even when dns requests can not be answered.

The device is defined as follows
<syntaxhighlight lang="perl">
define <name> HTTPMOD <URL> <Interval>
</syntaxhighlight>
The module connects to the given <code>URL</code> every <code>Interval</code> seconds, sends optional headers and data and then parses the response with regular expressions, xpath or json to set readings.

URL can be "none" and Interval can be 0 if you prefer to only query data with a get command and not in a defined interval.

Example:
<syntaxhighlight lang="perl">
define PM HTTPMOD http://MyPoolManager/cgi-bin/webgui.fcgi 60
</syntaxhighlight>

== Set-Commands ==
can be defined using attributes, see advanced configuration

If you set the attribute enableControlSet to 1, the following additional built in set commands are available:
;interval
:set new interval time in seconds and restart the timer
;reread
:request the defined URL and try to parse it just like the automatic update would do it every Interval seconds without modifying the running timer.
;stop
:stop interval timer.
;start
:restart interval timer to call GetUpdate after interval seconds
;upgradeAttributes
:convert outdated attributes for older HTTPMOD-Versions that are still defined for this device from the old syntax to the new one.
:attributes with the description "this attribute should not be used anymore" or similar will be translated to the new syntax, e.g. readingsName1 to reading01Name.
;storeKeyValue
:stores a key value pair in an obfuscated form in the file system. Such values can then be used in replacements where the mode is "key" e.g. to avoid storing passwords in the configuration in clear text

== Get-Commands ==
can be defined using attributes, see advanced configuration

== simple Attributes ==
;enableControlSet
:enables the built in set commands ''interval'', ''stop'', ''start'', ''reread'', ''upgradeAttributes'', ''storeKeyValue''

;enableCookies
:enables the cookie handling inside HTTPMOD. It is advisable to always set this attribute and allow HTTPMOD to track the state of cookies and set them for following HTTP-requests

;enforceGoodReadingNames
:makes sure that HTTPMOD only creates readings that are allowd for Fhem (especially if reading names are dynamically created from JSON object names with extractAllJSON. It is advisable to always set this attribute.

;handleRedirects
:enables the redirect handling inside HTTPMOD which should be used together with the cookie handling of HTTPMOD. HTTPMOD will then automatically follow redirects from a web server and keep track of cookies at the same time. It is advisable to always set this attribute.

;requestHeader.*
:Define an additional HTTP Header to set in the HTTP request

;requestData
:POST Data to be sent in the request. If not defined, it will be a GET request as defined in HttpUtils used by this module

;reading[0-9]+(-[0-9]+)?Name
:the name of a reading to extract with the corresponding readingRegex

;reading[0-9]*(-[0-9]+)?OExpr
:defines an expression that is used in an eval to compute the readings value. The raw value will be in the variable $val.

;reading[0-9]*(-[0-9]+)?OMap
:Output Map. Defines a mapping from raw to visible values like "0:mittig, 1:oberhalb, 2:unterhalb". If specified as readingOMap then the attribute value is a default for all other readings that don't specify an explicit reading[0-9]*OMap.

;reading[0-9]*(-[0-9]+)?Format
:Defines a format string that will be used in sprintf to format a reading value. If specified as readingFormat then the attribute value is a default for all other readings that don't specify an explicit reading[0-9]*Format.

;reading[0-9]*(-[0-9]+)?Decode
:defines an encoding to be used in a call to the perl function decode to convert the raw data string read from the device to a reading. This can be used if the device delivers strings in an encoding like cp850 instead of utf8.

;reading[0-9]*(-[0-9]+)?Encode
:defines an encoding to be used in a call to the perl function encode to convert the raw data string read from the device to a reading. This can be used if the device delivers strings in an encoding like cp850 and after decoding it you want to reencode it to e.g. utf8.

;reading[0-9]+Regex
:defines the regex to be used for extracting the reading. The value to extract should be in a capture group / sub expression
:e.g. ([\d\.]+) in the above example. Multiple capture groups will create multiple readings (see explanation above)

;reading[0-9]+XPath
:defines an xpath to one or more readings when parsing HTML data (see examples below)

;reading[0-9]+XPath-Strict
:defines an xpath to one or more readings when parsing XML data (see examples below)

;reading[0-9]+JSON
:defines a path to the JSON object wanted by concatenating the object names with an underscore as delimiter (see the example below)

;noShutdown
:pass the noshutdown flag to HTTPUtils for webservers that need it (some embedded webservers only deliver empty pages otherwise)

;disable
:stop doing automatic HTTP requests while this attribute is set to 1

;timeout
:time in seconds to wait for an answer. Default value is 2

;do_not_notify

;readingFnAttributes

== Simple Configuration of HTTP Devices ==
If your device expects special HTTP-headers then specify them as <code>attr requestHeader1</code> to <code>attr requestHeaderX</code>.
If your Device expects an HTTP POST instead of HTTP GET then the POST-data can be specified as <code>attr requestData</code>.
To get the readings, specify pairs of <code>attr readingXName</code> and <code>attr readingXRegex</code>, <code>attr readingXXPath</code>, <code>attr readingXXPath-Strict</code> or <code>attr readingXJSON</code> to define which readings you want to extract from the HTTP response and how to extract them. (The old syntax <code>attr readingsNameX</code> and <code>attr readingsRegexX</code> is still supported but the new one with <code>attr readingXName</code> and <code>attr readingXRegex</code> should be preferred. The actual values to be extracted have to be sub expressions within () in the regex (see example below)

=== Example for a PoolManager 5: ===
The PoolManager Web GUI can be queried with HTTP POST Requests like this one:

<syntaxhighlight lang="perl">
POST /cgi-bin/webgui.fcgi HTTP/1.1
Host: 192.168.70.90
Accept: */*
Content-Type: application/json;charset=UTF-8
Content-Length: 60

{"get" :["34.4001.value" ,"34.4008.value" ,"34.4033.value"]}
</syntaxhighlight>

The resulting HTTP Response would look like this:

<syntaxhighlight lang="perl">
HTTP/1.1 200 OK
Content-type: application/json; charset=UTF-8
Expires: 0
Cache-Control: no-cache
Date: Sun, 12 Jan 2014 12:23:11 GMT
Server: lighttpd/1.4.26
Content-Length: 179

{
"data": {
"34.4001.value": "7.00",
"34.4008.value": "0.52",
"34.4033.value": "24.8"
},
"status": {
"code": 0
},
"event": {
"type": 1,
"data": "48.30000.0"
}
}
</syntaxhighlight>

To configure HTTPMOD for a PoolManager one would first define a PoolManager device with e.g. the name PM, the URL and an interval of e.g. 60 seconds.

Then the data to be sent in the request needs to be defined because in this example the device expects a POST request so the query is not contained in the URL but in the request data.

Also as seen above the device expects special HTTP headers in the request so these headers also need to be defined as <code>attr PM requestHeader1</code> and <code>attr PM requestHeader2</code>

Then the names of the readings to be extracted would be set with attributes

Then for each reading value to be extracted a regular expression needs to be set that will match the value in question within ().

Example:
<syntaxhighlight lang="perl">
define PM HTTPMOD http://MyPoolManager/cgi-bin/webgui.fcgi 60

attr PM enableControlSet 1
attr PM enableCookies 1
attr PM enforceGoodReadingNames 1
attr PM handleRedirects 1

attr PM reading01Name PH
attr PM reading01Regex 34.4001.value":[ \t]+"([\d\.]+)"

attr PM reading02Name CL
attr PM reading02Regex 34.4008.value":[ \t]+"([\d\.]+)"

attr PM reading03Name3TEMP
attr PM reading03Regex 34.4033.value":[ \t]+"([\d\.]+)"

attr PM requestData {"get" :["34.4001.value" ,"34.4008.value" ,"34.4033.value", "14.16601.value", "14.16602.value"]}
attr PM requestHeader1 Content-Type: application/json
attr PM requestHeader2 Accept: */*
attr PM stateFormat {sprintf("%.1f Grad, PH %.1f, %.1f mg/l Chlor", ReadingsVal($name,"TEMP",0), ReadingsVal($name,"PH",0), ReadingsVal($name,"CL",0))}
</syntaxhighlight>

=== Example for AmbientMonitor ===
AmbientMonitor is a webbased visualisation for sensors connected to an Arduino device. Its web interface can also be queried with HTTMOD to grab the data into readings.

This example was provided by locutus. The hardware configuration is an Arduino + Ethercard with ENC28J60 Controller + DHT22 Sensor and software can be downloaded from https://github.com/lucadentella/AmbientMonitor

In this example an HTTP GET is sufficent, so no <code>requestData</code> is needed. The device provides temperature and humidity readings in an HTTP response that looks like:
<syntaxhighlight lang="perl">
HTTP/1.0 200 OK
Content-Type: text/html

myCB({'temperature':22.00,'humidity':46.00})
</syntaxhighlight>

the definition could be:
<syntaxhighlight lang="perl">
define AmbientMonitor HTTPMOD http://192.168.1.221/?callback=? 300

attr AmbientMonitor enableControlSet 1
attr AmbientMonitor enableCookies 1
attr AmbientMonitor enforceGoodReadingNames 1
attr AmbientMonitor handleRedirects 1

attr AmbientMonitor requestHeader Content-Type: application/json
attr AmbientMonitor reading1Name Temperatur
attr AmbientMonitor reading1Regex temperature':([\d\.]+)
attr AmbientMonitor reading2Name Feuchtigkeit
attr AmbientMonitor reading2Regex humidity':([\d\.]+)
attr AmbientMonitor stateFormat {sprintf("Temperatur %.1f C, Feuchtigkeit %.1f %", ReadingsVal($name,"Temperatur",0), ReadingsVal($name,"Feuchtigkeit",0))}
</syntaxhighlight>

== formatting and manipulating values / readings ==
Values that are parsed from an HTTP response can be further treated or formatted with the following attributes:

* <code>(reading|get)[0-9]*(-[0-9]+)?OExpr</code>
* <code>(reading|get)[0-9]*(-[0-9]+)?OMap</code>
* <code>(reading|get)[0-9]*(-[0-9]+)?Format</code>
* <code>(reading|get)[0-9]*(-[0-9]+)?Decode</code>
* <code>(reading|get)[0-9]*(-[0-9]+)?Encode</code>

They can all be specified for an individual reading, for all readings in one match (e.g. if a regular expression has several capture groups) or for all readings in a get command (defined by getXX) or for all readings in the main reading list (defined by readingXX):
<syntaxhighlight lang="perl">
reading01Format %.1f
</syntaxhighlight>

will format the reading with the name specified by the attribute reading01Name to be numerical with one digit after the decimal point.
If the attribute reading01Regex is used and contains several capture groups then the format will be applied to all readings parsed by this regex unless these readings have their own format specified by reading01-1Format, reading01-2Format and so on.

<syntaxhighlight lang="perl">
reading01-2Format %.1f
</syntaxhighlight>

Can be used in cases where a regular expression specified as reading01regex contains several capture groups or an xpath specified as reading01XPath creates several readings.
In this case reading01-2Format specifies the format to be applied to the second match.

<syntaxhighlight lang="perl">
readingFormat %.1f
</syntaxhighlight>

applies to all readings defined by a reading-Attribute that have no more specific format.

If you need to do some calculation on a raw value before it is used as a reading, you can define the attribute <code>readingOExpr</code>.
It defines a Perl expression that is used in an eval to compute the readings value. The raw value will be in the variable $val.

Example for an expression:
<syntaxhighlight lang="perl">
attr PM reading03OExpr $val * 10
</syntaxhighlight>
Just like in the above example of the readingFormat attributes, readingOExpr and the other following attributes can be applied on several levels.

To map a numerical value to a name, you can use the readingOMap attribute.
It defines a mapping from raw to visible values like "0:mittig, 1:oberhalb, 2:unterhalb".

Example for a map:
<syntaxhighlight lang="perl">
attr PM reading02-3OMap 0:kalt, 1:warm, 2:sehr warm
</syntaxhighlight>

To convert character sets, the module can first decode a string read from the device and then encode it again. For example:
<syntaxhighlight lang="perl">
attr PM getDecode UTF-8
</syntaxhighlight>

This applies to all readings defined for Get-Commands.

== Some help with Regular Expressions ==
{{Randnotiz|RNTyp=y|RNText=Starting with version ''2018-02-10'' the internal that holds the HTTP response is no longer called '''''buf''''' but rather '''''httpbody''''', and it is only displayed when attribute '''''showBody''''' is set to "1".}}
If HTTPMOD seems not to work and the FHEM Logfile contains a message like
:<code>HTTPMOD: Response didn't match Reading ...</code>
then you should check if the value you want to extract is read into the internal with the name buf. Internals are visible when you click on the defined HTTPMOD Device. buf is an internal variable that contains the HTTP Response read. If the value is there and you get the mentioned message then probably something is wrong with your regular expression. Please note that buf might contain special characters like newlines but they are not shown in fhemweb. If you are new to regular expressions then the introduction at http://perldoc.perl.org/perlretut.html might be helpful.

For a typical HTTPMOD use case where you want to extract a number out of a HTTP-Response you can use something like <code>[\d\.]+</code> to match the number itself. The expression matches the number characters (<code>\d</code>) or a <code>.</code> if one of these characters occurs at least once.

To tell HTTPMOD that the number is what you want to use for the reading, you have to put the expression in between <code>()</code>. A <code>([\d\.]+)</code> alone would match the longest number in the HTTP Response which is very likely not the number you are looking for so you need to add something to the expression to give it a context and define how to find the number that you are looking for.

If there is a title text before the number or a special text after the number you can put this in the regex. In one of the examples above <code>humidity':([\d\.]+)</code> is looking for the number that immediately follows the text <code>humidity':</code> without any blanks in between.
Be careful if the text you are getting from your device contains special characters like newline. You don't see such special characters in the fhem webinterface as contents of the internal buf but they might cause your regular expression to fail.

If you have trouble defining a regular expression that matches a certain name, then many complicated characters and then a number, it might be helpful to use a negation in matching like <code>temp[^\d]+([\d\.]).*</code>. In this examle <code>[^\d]+</code> means any character that is not a numerical digit, more than once.

=== Regular Expressions with multiple capture Groups ===
The regular expressions used in the above example for a Poolmanager will take the value that matches one capture group. This is the part of the regular expression inside (). In the above example "([\d\.]+)" refers to numerical digits or points between double quotation marks. Only the string consiting of digits and points will match inside (). This piece is assigned to the reading.

You can also use regular expressions that have several capture groups which might be helpful when parsing tables. In this case an attribute like

<syntaxhighlight lang="perl">
reading02Regex something[ \t]+([\d\.]+)[ \t]+([\d\.]+)
</syntaxhighlight>

could match two numbers. When you specify only one reading02Name like
<syntaxhighlight lang="perl">
reading02Name Temp
</syntaxhighlight>

the name Temp will be used with the extension -1 and -2 thus giving a reading Temp-1 for the first number and Temp-2 for the second. You can also specify individual names for several readings that get parsed from one regular expression with several capture groups by defining attributes

<syntaxhighlight lang="perl">
reading02-1Name
reading02-2Name
...
</syntaxhighlight>
The same notation can be used for formatting attributes like readingXOMap, readingXFormat and so on.

The usual way to define readings is however to have an individual regular expression with just one capture group per reading as shown in the above example.

== Parsing JSON ==

If a webservice delivers data in JSON format, HTTPMOD can directly parse JSON which might be easier in this case than definig regular expressions.
The next example shows the data that can be requested from a Poolmanager with the following partial configuration:

<syntaxhighlight lang="perl">
define test2 HTTPMOD none 0
attr test2 get01Name Chlor
attr test2 getURL http://192.168.70.90/cgi-bin/webgui.fcgi
attr test2 getHeader1 Content-Type: application/json
attr test2 getHeader2 Accept: */*
attr test2 getData {"get" :["34.4008.value"]}
</syntaxhighlight>

The data in the HTTP response looks like this:

<syntaxhighlight lang="perl">
{
"data": {
"34.4008.value": "0.25"
},
"status": {
"code": 0
},
"event": {
"type": 1,
"data": "48.30000.0"
}
}
</syntaxhighlight>

the classic way to extract the value 0.25 into a reading with the name Chlor with a regex would have been
<syntaxhighlight lang="perl">
attr test2 get01Regex 34.4008.value":[ \t]+"([\d\.]+)"
</syntaxhighlight>

with JSON you can write
<syntaxhighlight lang="perl">
attr test2 get01JSON data_34.4008.value
</syntaxhighlight>
which will create a reading with the Name "Chlor" (as shown above) and take the value 0.25 from the JSON string.

or if you don't care about the naming of your readings, you can simply extract all JSON data with
<syntaxhighlight lang="perl">
attr test2 extractAllJSON
</syntaxhighlight>

which would apply to all data read from this device and create the following readings out of the HTTP response shown above:

{| class="wikitable"
| data_34.4008.value || 0.25
|-
| event_data || 48.30000.0
|-
| event_type || 1
|-
| status_code || 0
|}

or you can specify
<syntaxhighlight lang="perl">
attr test2 get01ExtractAllJSON
</syntaxhighlight>
which would only apply to all data read as response to the get command defined as get01.

It might seem very simple at first sight to use extractAllJSON but if you prefer readings with a meaningful name you should instead define these readings with readingXXName and readingXXJSON or getXXName and getXXJSON individually. Of Course it would be possible to create additional user readings outside HTTPMOD but doing calculations, naming and formatting inside HTTPMOD is more efficient.

=== JSON Lists ===

imagine the HTTP Response contains:

<syntaxhighlight lang="perl">
{ "power":"0",
"modes":["Off","SimpleColor","RainbowChase"],
"code1":3,
"code2":4
}
</syntaxhighlight>

then a configuration like

<syntaxhighlight lang="perl">
attr device reading01JSON modes
attr device reading01Name Mode
</syntaxhighlight>

will create a list of Subreadings just like a regex with multiple matches can create multiple subreadings:

{| class="wikitable"
| Mode-1 || Off
|-
| Mode-2 || SimpleColor
|-
| Mode-3 || RainbowChase
|}

if you don't want several subreadings but one reading that contains the list of modes, you can specify a recombine expression:

<syntaxhighlight lang="perl">
attr device reading01Name Modes
attr device reading01RecombineExpr join ",", @matchlist
</syntaxhighlight>

which will create one reading containing a list:

{| class="wikitable"
| Modes || Off,SimpleColor,RainbowChase
|}

JSON parsing specifications also don't Need to match exactly. If there is no exact match for a defined reading, the HTTPMOD will try to Interpret the specification as a regex and look for json object paths that match the specification as a regex. For example:

<syntaxhighlight lang="perl">
attr device reading01Name CodeElem
attr device reading01JSON code
</syntaxhighlight>

which will create a list of readings:

{| class="wikitable"
| CodeElem-1|| 3
|-
| CodeElem-2 || 4
|}

and of course they could also be recombined into one reading with a RecombineExpr Attribute.

== Parsing http / XML using xpath ==
Another alternative to regex parsing is the use of XPath to extract values from HTTP responses.
The following example shows how XML data can be parsed with XPath-Strict or HTML Data can be parsed with XPath.
Both work similar and the example uses XML Data parsed with the XPath-Strict option:

If The XML data in the HTTP response looks like this:

<syntaxhighlight lang="xml">
<root xmlns:foo="http://www.foo.org/" xmlns:bar="http://www.bar.org">
<actors>
<actor id="1">Peter X</actor>
<actor id="2">Charles Y</actor>
<actor id="3">John Doe</actor>
</actor>
</root>
</syntaxhighlight>

with XPath you can write
<syntaxhighlight lang="perl">
attr htest reading01Name Actor
attr htest reading01XPath-Strict //actor[2]/text()
</syntaxhighlight>

This will create a reading with the Name "Actor" and the value "Charles Y".

Since XPath specifications can define several values / matches, HTTPMOD can also interpret these and store them in multiple readings:
<syntaxhighlight lang="perl">
attr htest reading01Name Actor
attr htest reading01XPath-Strict //actor/text()
</syntaxhighlight>

will create the readings

{| class="wikitable"
| Actor-1 || Peter X
|-
| Actor-2 || Charles Y
|-
| Actor-3 || John Doe
|}

== Further replacements of URL, header or post data ==
sometimes it might be helpful to dynamically change parts of a URL, HTTP header or post data depending on existing readings, internals or
perl expressions at runtime. This might be needed to pass further variables to a server, a current date or other things.

To support this HTTPMOD offers generic replacements that are applied to a request before it is sent to the server. A replacement can be defined with the attributes

* <code>replacement[0-9]*Regex</code>
* <code>replacement[0-9]*Mode</code>
* <code>replacement[0-9]*Value</code>
* <code>[gs]et[0-9]*Replacement[0-9]*Value</code>

a replacement always replaces a match of a regular expression.

'''replacement[0-9]*Mode:'''
The way the replacement value is defined can be specified with the replacement mode.
* If the <code>replacement[0-9]*Mode</code> is <code>reading</code>, then the corresponding <code>replacement[0-9]*Value</code> is interpreted as the name of a ''reading'' of the same device or as ''device:reading'' to refer to another device.
* If the <code>replacement[0-9]*Mode</code> is <code>internal</code>, then the corresponding <code>replacement[0-9]*Value</code> is interpreted as the name of an ''internal'' of the same device or as ''device:internal'' to refer to another device.
* If the <code>replacement[0-9]*Mode</code> is <code>text</code>, then the corresponding <code>replacement[0-9]*Value</code> is interpreted as a static text
* If the <code>replacement[0-9]*Mode</code> is <code>expression</code>, then the corresponding <code>replacement[0-9]*Value</code> is evaluated as a perl expression to compute the replacement. Inside such a replacement expression it is possible to refer to capture groups of the replacement regex.
* If the <code>replacement[0-9]*Mode</code> is <code>key</code>, then the module will use a value from a key / value pair that is stored in an obfuscated form in the file system with the set storeKeyValue command. This might be useful for storing passwords.

Example:

<syntaxhighlight lang="perl" line="1">
attr mydevice getData {"get" :["%%value%%.value"]}
attr mydevice replacement01Mode text
attr mydevice replacement01Regex %%value%%

attr mydevice get01Name Chlor
attr mydevice get01Replacement01Value 34.4008

attr mydevice get02Name Something
attr mydevice get02Replacement01Value 31.4024

attr mydevice get05Name profile
attr mydevice get05URL http://www.mydevice.local/getprofile?password=%%password%%
attr mydevice replacement02Mode key
attr mydevice replacement02Regex %%password%%
attr mydevice replacement02Value password
</syntaxhighlight>

defines that <code>%%value%%</code> will be replaced by a static text.

All Get commands will be HTTP post requests of a similar form. Only the <code>%%value%%</code> will be different from get to get.
The first get will set the reading named Chlor and for the request it will take the generic getData and replace %%value%% with 34.4008.

A second get will look the same except a different name and replacement value.

With the command <code>set mydevice storeKeyValue password geheim</code> you can store the password geheim in an obfuscated form in the file system.
To use this password and send it in a request you can use the above replacement with mode key. The value password will then refer to the ofuscated string stored with the key password.

The mode <code>expression</code> allows you to define your own replacement syntax:
<syntaxhighlight lang="perl">
attr mydevice replacement01Mode expression
attr mydevice replacement01Regex {{([^}]+)}}
attr mydevice replacement01Value ReadingsVal("mydevice", $1, "")
attr mydevice getData {"get" :["{{temp}}.value"]}
</syntaxhighlight>

In this example any <code><nowiki>{{name}}</nowiki></code> in a URL, header or post data will be passed on to the perl function ReadingsVal
which uses the string between <code><nowiki>{{}}</nowiki></code> as second parameter. This way one defined replacement can be used for many different
readings.

HTTPMOD has two built in replacements: One for session Ids and another one for the input value in a set command.
The placeholder $sid is always replaced with the internal <code>$hash->{sid}</code> which contains the session id after it is extracted from a previous HTTP response.
If you don't like to use the placeholder $sid then you can define your own replacement for example like:

<syntaxhighlight lang="perl">
attr mydevice replacement01Mode internal
attr mydevice replacement01Regex %session%
attr mydevice replacement01Value sid
</syntaxhighlight>

Now the internal <code>$hash->{sid}</code> will be used as a replacement for the placeholder %session%.

In the same way a value that is passed to a set-command can be put into a request with a user defined replacement.
In this case the internal <code>$hash->{value}</code> will contain the value passed to the set command.
<code>$hash->{value}</code> might even be a string containing several values that could be put into several different positions in a request by using user defined replacements.

'''Other example : steering a pellet stove from Rika'''

The stove API of Rika on https://www.rika-firenet.com/web/ delivers a JSON string with all settings and values, and can be piloted with a data string containing all the "set" values at once.

Delivered JSON on get https://www.rika-firenet.com/api/client/xxxxxxxx/status : (xxxxxxxx must be replaced with the unique stove ID)
<syntaxhighlight lang="perl">
{
"name": "Vorzimmer",
"stoveID": "xxxxxxxxx",
"lastSeenMinutes": 1,
"lastConfirmedRevision": 1504385700,
"controls": {
"revision": 1504385700,
"onOff": true,
"operatingMode": 2,
"heatingPower": 65,
"targetTemperature": 24,
"heatingTimesActive": false,
"heatingTimesActiveForComfort": true,
"setBackTemperature": 18,
"convectionFan1Active": false,
"convectionFan1Level": 0,
"convectionFan1Area": 0,
"convectionFan2Active": false,
"convectionFan2Level": 0,
"convectionFan2Area": 0,
"frostProtectionActive": false,
"frostProtectionTemperature": 5
},
"sensors": {
"statusError": 0,
"statusWarning": 0,
"statusService": 0,
"statusMainState": 1,
"statusSubState": 3,
"statusFrostStarted": false,
"inputFlameTemperature": 21,
"inputRoomTemperature": 21,
"inputExternalRequest": true,
"outputDischargeMotor": 0,
"outputInsertionMotor": 0,
"outputIDFan": 0,
"outputAirFlaps": 0,
"outputIgnition": false,
"parameterStoveTypeNumber": 13,
"parameterVersionMainBoard": 223,
"parameterVersionTFT": 223,
"parameterRuntimePellets": 11,
"parameterRuntimeLogs": 0,
"parameterFeedRateTotal": 17,
"parameterFeedRateService": 683,
"parameterOnOffCycles": 2
},
"stoveType": "DOMO MultiAir",
"stoveFeatures": {
"multiAir1": true,
"multiAir2": true,
"insertionMotor": false,
"airFlaps": false,
"logRuntime": false
}
}
</syntaxhighlight>

Data string to send to https://www.rika-firenet.com/api/client/xxxxxxxx/controls in order to set values:
<syntaxhighlight lang="perl">
heatingTimesActiveForComfort=true&frostProtectionTemperature=3&setBackTemperature=18&targetTemperature=24&convectionFan2Level=0&convectionFan2Active=false&convectionFan1Level=0&onOff=true&convectionFan1Active=false&convectionFan2Area=0&revision=1505550101&heatingTimesActive=false&convectionFan1Area=0&frostProtectionActive=false&operatingMode=2&heatingPower=65
</syntaxhighlight>

Code in 99_myUtils.pm:
<syntaxhighlight lang="perl">
use JSON;
...
sub
replaceJSON ($$) {
my ($valToReplace, $value) = @_;

#$value in the parameters is a default value
#It has to be replaced through the real value nnn passed in the set command "set <device> valToset nnn"
$value = InternalVal("Ofen", "value", $value);
Log3 ("Ofen", 3, "replaceJSON Internalvalue: $value");

#Force an update to avoid outdated revision number
fhem ("get Ofen revision");

#Get all the controls as json
my $json = ReadingsVal("Ofen", "controlsJSON","");
Log3 ("Ofen", 3, "replaceJSON configsJSON: $json");

# When starting FHEM or rereading config, the reading controlsJSON is empty
return if ($json eq "");

my $decoded = decode_json($json);
my $result;
for my $key ( keys %$decoded ) {
$result .= "$key=";
if ($key eq $valToReplace) {
$result .= $value."&";
} else {
$result .= $decoded->{$key}."&";
}
}
chop($result); #remove last &
Log3("Ofen", 3, "replaceJSON Result: $result");
return $result;
}
</syntaxhighlight>

Define stove in fhem:
<syntaxhighlight lang="perl">
defmod Ofen HTTPMOD https://www.rika-firenet.com/api/client/xxxxxxxx/status 60

attr Ofen enableCookies 1
attr Ofen reAuthRegex id="login"|Unauthorized
attr Ofen sid01Data email=xx@xx&password=xx
attr Ofen sid01URL https://www.rika-firenet.com/web/login

attr Ofen reading01JSON sensors_inputRoomTemperature
attr Ofen reading01Name RaumTemp
attr Ofen reading02JSON controls_setBackTemperature
attr Ofen reading02Name Absenkung
attr Ofen reading03JSON controls_frostProtectionTemperature
attr Ofen reading03Name Frostschutz
attr Ofen reading10Name controlsJSON
attr Ofen reading10Regex (?s)controls.*?({.*?})

attr Ofen get09Name revision
attr Ofen get09URL https://www.rika-firenet.com/api/client/xxxxxxxx/status

attr Ofen setURL https://www.rika-firenet.com/api/client/xxxxxxxx/controls
attr Ofen setData {{data}}
attr Ofen replacement01Mode expression
attr Ofen replacement01Regex {{data}}

attr Ofen set11Name frostProtectionTemperature
attr Ofen set11Replacement01Value replaceJSON("frostProtectionTemperature", 2)

attr Ofen set12Name targetTemperature
attr Ofen set12Replacement01Value replaceJSON("targetTemperature", 24)
</syntaxhighlight>

A detailed explanation (in german) of the login process can be found here: [https://forum.fhem.de/index.php/topic,76220.msg682514.html#msg682514]
and the explanation of the other parameters here: [https://forum.fhem.de/index.php/topic,76220.msg685710.html#msg685710]

== replacing reading values when they have not been updated / the device did not respond ==
If a device does not respond then the values stored in readings will keep the same and only their timestamp shows that they are outdated.
If you want to modify reading values that have not been updated for a number of seconds, you can use the attributes

* <code>(reading|get)[0-9]*(-[0-9]+)?MaxAge</code>
* <code>(reading|get)[0-9]*(-[0-9]+)?MaxAgeReplacementMode</code>
* <code>(reading|get)[0-9]*(-[0-9]+)?MaxAgeReplacement</code>

Every time the module tries to read from a device, it will also check if readings have not been updated
for longer than the <code>MaxAge</code> attributes allow. If readings are outdated, the <code>MaxAgeReplacementMode</code> defines how the affected
reading values should be replaced. <code>MaxAgeReplacementMode</code> can be <code>text</code>, <code>reading</code>, <code>internal</code>, <code>expression</code> or <code>delete</code>.

<code>MaxAge</code> specifies the number of seconds that a reading should remain untouched before it is replaced.

<code>MaxAgeReplacement</code> contains either a static text that is used as replacement value or a Perl expression that is evaluated to
give the replacement value. This can be used for example to replace a temperature that has not bee updated for more than 5 minutes
with the string "outdated - was 12":
<syntaxhighlight lang="perl">
attr PM readingMaxAge 300
attr PM readingMaxAgeReplacement "outdated - was " . $val
attr PM readingMaxAgeReplacementMode expression
</syntaxhighlight>
The variable <code>$val</code> contains the value of the reading before it became outdated.

Or to show that a device was offline:
<syntaxhighlight lang="perl">
attr MyLight reading01Name color
attr MyLight reading01JSON result_02_color
attr MyLight reading01MaxAge 300
attr MyLight reading01MaxAgeReplacement "offline"
attr MyLight reading01MaxAgeReplacementMode text
</syntaxhighlight>

== Note on determining how to send requests to a special device ==
If you don't know which URLs, headers or POST data your web GUI uses, you might try a local proxy like BurpSuite [http://portswigger.net/burp/ BurpSuite] to track requests and responses. This is a tedious task but probably the best way to achieve a successful result.

Let us consider an example. The Telekom Speedport W724V has a login-site that is famous for being cumbersome. Burp allows to monitor each step in the login procedure. In the case of a speedport the following steps occur:

First burp shows that a get command is issued
##################################################################################################
GET / HTTP/1.1
Host: speedport.ip
Cache-Control: max-age=0
Upgrade-Insecure-Requests: 1
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/57.0.2987.133 Safari/537.36
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8
Accept-Language: de-DE,de;q=0.8,en-US;q=0.6,en;q=0.4
Cookie: lang=de
Connection: close
In order to mimic the behavior of a real person calling the website HTTPMOD should copy all necessary steps. Host, Cookie and the GET-command are usually necessary. The same cannot be said of the User-Agent because the website can be called from any mobile or desktop computer.

Then, the speedport will answer with a command that consists of several lines. By going through every line for every step in the login procedure one will finally arrive at the information that is necessary to successfully enter the login of the speedport (in case of the W724V, for example, it is necessary to copy a token called _httoken and to include the referer).

== Advanced configuration to define a <code>set</code> command and send data to a device ==

When a set option is defined by attributes, the module will use the value given to the set command and integrate it into an HTTP-Request that sends the value to the device. The definitions for URL, headers and post data can contain the placeholder $val which will be replaced by the (numerical) value given to the set command.

This can be as simple as:
<syntaxhighlight lang="perl">
# No cyclic requests and no main URL needed in this example
define MyDevice HTTPMOD none 0

attr MyDevice set01Name Licht
attr MyDevice set01URL http://192.168.1.22/switch=$val
</syntaxhighlight>

A user command
<syntaxhighlight lang="perl">
set MyDevice Licht 1
</syntaxhighlight>

will be translated into the http GET request
<syntaxhighlight lang="perl">
http://192.168.1.22/switch=1
</syntaxhighlight>

In this example a map would also be helpful, that translates on / off to 0 or 1 and allows the user to select on/of in fhemweb:
<syntaxhighlight lang="perl">
attr MyDevive set01IMap 0:off, 1:on
</syntaxhighlight>
This also provides input validation to make sure that only on and off can be used with the set command.

In more complex Scenarios you might need to login before sending a command and the Login might create a session id that has to be part of further requests either in the URL, in headers or in the post data.

Extension to the above example for a PoolManager 5 where a set needs a session id in the URL and the values have to be passed in JSON strings as post data:
<syntaxhighlight lang="perl">
attr PM set01Name HeizungSoll
attr PM set01URL http://MyPoolManager/cgi-bin/webgui.fcgi?sid=$sid
attr PM set01Hint 6,10,20,30
attr PM set01Min 6
attr PM set01Max 30
attr PM setHeader1 Content-Type: application/json
attr PM set01Data {"set" :{"34.3118.value" :"$val" }}
</syntaxhighlight>

This example defines a set option with the name HeizungSoll.
By issuing <code>set PM HeizungSoll 10</code> in FHEM, the value 10 will be sent in the defined HTTP
Post to URL <code>http://MyPoolManager/cgi-bin/webgui.fcgi</code> in the Post Data as

<syntaxhighlight lang="html">
{"set" :{"34.3118.value" :"10" }}
</syntaxhighlight>

The optional attributes set01Min and set01Max define input validations that will be checked in the set function.
The optional attribute set01Hint will define a selection list for the FHEMweb GUI.

The HTTP response to such a request will be ignored unless you specify the attribute <code>setParseResponse</code>
for all set commands or <code>set01ParseResponse</code> for the set command with number 01.
If the HTTP response to a set command is parsed then this is done like the parsing of responses to get commands and you can use the attributes ending e.g. on Format, Encode, Decode, OMap and OExpr to manipulate / format the values read.

If a parameter to a set command is not numeric but should be passed on to the device as text, then you can specify the attribute setTextArg. For example:
<syntaxhighlight lang="perl">
attr PM set01TextArg
</syntaxhighlight>

If a set command should not require a parameter at all, then you can specify the attribute NoArg. For example:
<syntaxhighlight lang="perl">
attr PM set03Name On
attr PM set03NoArg
</syntaxhighlight>

This example defines the set of parameters for Wiesemann&Theiss Web-IO Analog 4.0 #57761. The current limit is set to 16mA (setxxMax)
<syntaxhighlight lang="Perl">
defmod WuT_Analog1 HTTPMOD none 30
attr WuT_Analog1 room W&T
attr WuT_Analog1 set01Max 16
attr WuT_Analog1 set01Min 0
attr WuT_Analog1 set01Name Output1
attr WuT_Analog1 set01URL http://192.xx.My_IP/outputaccess1?PW=MyPassword&State=$val&
attr WuT_Analog1 set02Max 16
attr WuT_Analog1 set02Min 0
attr WuT_Analog1 set02Name Output2
attr WuT_Analog1 set02URL http://192.xx.My_IP/outputaccess2?PW=MyPassword&State=$val&
</syntaxhighlight>

== Advanced configuration to create a valid session id that might be necessary ==
In simple cases logging in works with basic authentication. In the case HTTPMOD accepts a username and password as part of the URL in the form
<syntaxhighlight lang="perl">
http://User:Password@192.168.1.18/something
</syntaxhighlight>

However basic auth is seldom used. If you need to fill in a username and password in a HTML form and the session is then managed by a session id, here is how to configure this:

when sending data to an HTTP-Device in a set, HTTPMOD will replace any <code>$sid</code> in the URL, Headers and Post data with the internal <code>$hash->{sid}</code>. To authenticate towards the device and give this internal a value, you can use an optional multi step login procedure defined by the following attributes:

* <code>sid[0-9]*URL</code>
* <code>sid[0-9]*Data.*</code>
* <code>sid[0-9]*Header.*</code>
* <code>sid[0-9]*IgnoreRedirects</code>
* <code>idRegex</code>
* <code>idJSON</code>
* <code>idXPath</code>
* <code>idXPath-Strict</code>
* <code>(get|set|sid)[0-9]*IdRegex</code>
* <code>(get|set|sid)[0-9]*IdJSON</code>
* <code>(get|set|sid)[0-9]*IdXPath</code>
* <code>(get|set|sid)[0-9]*IdXPath-Strict</code>

Each step can have a URL, Headers, Post Data pieces and a Regex to extract a resulting Session ID into <code>$hash->{sid}</code>.
HTTPMOD will create a sorted list of steps (the numbers between sid and URL / Data / Header) and the loop through these steps and send the corresponding requests to the device. For each step a $sid in a Header or Post Data will be replaced with the current content of <code>$hash->{sid}</code>.

Using this feature, HTTPMOD can perform a forms based authentication and send user name, password or other necessary data to the device and save the session id for further requests.

To determine when this login procedure is necessary, HTTPMOD will first try to send a request without
doing the login procedure. If the result contains an error that authentication is necessary, then a login is performed.
To detect such an error in the HTTP response, you can again use a regular expression, JSON or XPath, this time with the attributes

* <code>reAuthRegex</code>
* <code>reAuthJSON</code>
* <code>reAuthXPath</code>
* <code>reAuthXPath-Strict</code>
* <code>(get|set)[0-9]*ReAuthRegex</code>
* <code>(get|set)[0-9]*ReAuthJSON</code>
* <code>(get|set)[0-9]*ReAuthXPath</code>
* <code>(get|set)[0-9]*ReAuthXPath-Strict</code>

reAuthJSON or reAuthXPath typically only extract one piece of data from a response.
If the existence of the specified piece of data is sufficent to start a login procedure, then nothing more needs to be defined to detect this situation.
If however the indicator is a status code that contains different values depending on a successful request and a failed request if a new authentication is needed,
then you can combine things like reAuthJSON with reAuthRegex. In this case the regex is only matched to the data extracted by JSON (or XPath).
This way you can easily extract the status code using JSON parsing and then specify the code that means "authentication needed" as a regular expression.

If for one step not all of the URL, Data or Header Attributes are set, then HTTPMOD tries to use a
<code>sidURL</code>, <code>sidData.*</code> or <code>sidHeader.*</code> Attribute (without the step number after sid). This way parts that are the same for all steps don't need to be defined redundantly.

=== Example for a multi step login procedure: ===
<syntaxhighlight lang="perl">
attr PM reAuthRegex /html/dummy_login.htm
attr PM sidURL http://192.168.70.90/cgi-bin/webgui.fcgi?sid=$sid
attr PM sidHeader1 Content-Type: application/json
attr PM sid1IDRegex wui.init\('([^']+)'
attr PM sid2Data {"set" :{"9.17401.user" :"fhem" ,"9.17401.pass" :"password" }}
attr PM sid3Data {"set" :{"35.5062.value" :"128" }}
attr PM sid4Data {"set" :{"42.8026.code" :"pincode" }}
</syntaxhighlight>

In this case HTTPMOD detects that a login is necessary by looking for the pattern /html/dummy_login.htm in the HTTP response.
If it matches, it starts a login sequence. In the above example all steps request the same URL. In step 1 only the defined Header is sent in an HTTP get request. The response will contain a session id that is extraced with the regex wui.init\('([^']+)'.

In the next step this session id is sent in a post request to the same URL where tha post data contains a username and password. The a third and a fourth request follow that set a value and a code. The result will be a valid and authorized session id that can be used in other requests where $sid is part of a URL, header or post data and will be replaced with the session id extracted above.

===Another Practical Example reading the SOC from a Renault Zoe===
<syntaxhighlight lang="perl">
define myZoe HTTPMOD https://www.services.renault-ze.com/api/vehicle/VINVINVIN/battery 7000
attr myZoe userattr reading01JSON reading01Name reading02JSON reading02Name reading03JSON reading03Nam\
e reading04JSON reading04Name reading05JSON reading05Name requestHeader02 sid1Data sid1Header01 sid1Id\
JSON sid1IgnoreRedirects:0,1 sid1URL
attr myZoe reAuthJSON message
attr myZoe reading01JSON charge_level
attr myZoe reading01Name SOC
attr myZoe reading02JSON charging
attr myZoe reading02Name charging
attr myZoe reading03JSON plugged
attr myZoe reading03Name plugged
attr myZoe reading04JSON remaining_range
attr myZoe reading04Name remaining_range
attr myZoe reading05JSON last_update
attr myZoe reading05Name last_update
attr myZoe requestHeader02 Authorization: Bearer $sid
attr myZoe sid1Data {"username":"ZEUSERNAME","password":"ZEPASSWORD"}
attr myZoe sid1Header01 Content-Type: application/json
attr myZoe sid1IdJSON token
attr myZoe sid1IgnoreRedirects 1
attr myZoe sid1URL https://www.services.renault-ze.com/api/user/login
attr myZoe timeout 10
#attr myZoe verbose 7
</syntaxhighlight>

The $sid is read by logging in with username and password from JSON {"token": ..} after detecting an error {"message": ..} from a failed request. This example offers no solution for the reading of the VIN from the login request, which in turn is part of the reading URL. It should be possible to read more than just the $sid from the login sequence.

In the special case where a session id is set as a HTTP-Cookie (with the header Set-cookie: in the HTTP response) HTTPMOD offers an even simpler way. With the attribute enableCookies a very basic cookie handling mechanism is activated that stores all cookies that the server sends to the HTTPMOD device and puts them back as cookie headers in the following requests.

For such cases no sidIdRegex and no $sid in a user defined header is necessary.

== Advanced configuration to define a <code>get</code> and request additional data with its own request from a device ==

The normal automatic HTTP request that is done repeatedly after the defined interval has elapsed works well in cases where all required readings can be requested in one common HTTP request. If however a device needs individual requests with different URLs or different POST data for each value, then another method is necessary.
For such cases a <code>get</code> option can be defined and the user can either issue FHEM <code>get</code> commands each time he needs the reading or the user can set an attribute to request the reading automatically together with the normal iteration.
For each <code>get</code> option attributes define an individual URL, optional headers, and post data as well as individual regular expressions and formatting options.

When a get option is defined by attributes, the module allows querying additional values from the device that require individual HTTP-Requests or special parameters to be sent

Extension to the above example:

<syntaxhighlight lang="perl">
attr PM get01Name MyGetValue
attr PM get01URL http://MyPoolManager/cgi-bin/directory/webgui.fcgi?special=1?sid=$sid
attr PM getHeader1 Content-Type: application/json
attr PM get01Data {"get" :{"30.1234.value"}}
</syntaxhighlight>

This example defines a get option with the name MyGetValue.
By issuing <code>get PM MyGetValue</code> in FHEM, the defined HTTP request is sent to the device.
The HTTP response is then parsed using the same readingXXName and readingXXRegex attributes as above so
additional pairs will probably be needed there for additional values.

if you prefer to define the parsing and formatting of readings individually per get command, you can use
attributes like get01Regex, get01XPath, get01Format, get01OMap and so on just like for reading01...

You can also include parameters / values that are passed to the get command in the request just like for set commands.
The placeholder $val will be replaced with the value given to the get command or you can specify your own replacement as described above.

If the new get parameter should also be queried regularly, you can define the following optional attributes:

<syntaxhighlight lang="perl">
attr PM get01Poll 1
attr PM get01PollDelay 300
</syntaxhighlight>

The first attribute includes this reading in the automatic update cycle and the second defines an alternative lower update frequency. When the interval defined initially in the define is over and the normal readings are read from the device, the update function will check for additional get parameters that should be included in the update cycle.

If a PollDelay is specified for a get parameter, the update function also checks if the time passed since it has last read this value is more than the given PollDelay. If not, this reading is skipped and it will be rechecked in the next cycle when interval is over again. So the effective PollDelay will always be a multiple of the interval specified in the initial define.

Please note that each defined get command that is included in the regular update cycle will create its own HTTP request. So if you want to extract several values from the same request, it is much more efficient to do this by defining readingXXName and readingXXRegex, XPath or JSON attributes and to specify an interval and a URL in the define of the HTTPMOD device.

Example for a Siemens webserver provided by Lanhydrock:
<syntaxhighlight lang="perl">
define ozw672 HTTPMOD https://192.168.178.8/api/auth/login.json?user=test&pwd=test 300

attr ozw672 get1Name tempAussen
attr ozw672 get1URL https://192.168.178.8/api/menutree/read_datapoint.json?SessionId=$sid&Id=1960
attr ozw672 get1Poll 1
attr ozw672 get1PollDelay 1800

attr ozw672 get2Name tempAussenGemischt
attr ozw672 get2URL https://192.168.178.8/api/menutree/read_datapoint.json?SessionId=$sid&Id=1964
attr ozw672 get2Poll 1
attr ozw672 get2PollDelay 1800

attr ozw672 get3Name tempTWW
attr ozw672 get3URL https://192.168.178.8/api/menutree/read_datapoint.json?SessionId=$sid&Id=1996
attr ozw672 get3Poll 1

attr ozw672 get4Name tempKesselSoll
attr ozw672 get4URL https://192.168.178.8/api/menutree/read_datapoint.json?SessionId=$sid&Id=1910
attr ozw672 get4Poll 1

attr ozw672 get5Name tempKesselRuecklauf
attr ozw672 get5URL https://192.168.178.8/api/menutree/read_datapoint.json?SessionId=$sid&Id=1915
attr ozw672 get5Poll 1

attr ozw672 get6Name tempKesselRuecklaufSoll
attr ozw672 get6URL https://192.168.178.8/api/menutree/read_datapoint.json?SessionId=$sid&Id=1916
attr ozw672 get6Poll 1

attr ozw672 get7Name anzahlStartsBrenner
attr ozw672 get7URL https://192.168.178.8/api/menutree/read_datapoint.json?SessionId=$sid&Id=1927
attr ozw672 get7PollDelay 1800
attr ozw672 get7Poll 1

attr ozw672 get8Name statusKessel
attr ozw672 get8URL https://192.168.178.8/api/menutree/read_datapoint.json?SessionId=$sid&Id=1898
attr ozw672 get8Poll 1
attr ozw672 get8Regex Value": "([a-zA-Zü ]*)"
attr ozw672 get8OMap Aus:0, Nachlauf aktiv:5, Freigegeben für TWW:10, Freigegeben für HK:20, In Teillastbetrieb für TWW:40, In Teillastbetrieb für HK:50, In Betrieb für Trinkwasser:90, In Betrieb für Heizkreis:100

attr ozw672 getRegex Value": "[ ]*([-.0-9]*)"

attr ozw672 reAuthRegex .*session not valid.*
attr ozw672 sid1IDRegex .*"(.*-.*-.*-[0-9a-z]*).*
attr ozw672 sid1URL https://192.168.178.8/api/auth/login.json?user=test&pwd=test
</syntaxhighlight>

== All attributes ==
;reading[0-9]+Name
:the name of a reading to extract with the corresponding readingRegex, readingJSON, readingXPath or readingXPath-Strict
:Please note that the old syntax <b>readingsName.*</b> does not work with all features of HTTPMOD and should be avoided. It might go away in a future version of HTTPMOD.

;(get|set)[0-9]+Name
:Name of a get or set command
:If the HTTP response that is received after the command is parsed with an individual parse option then this name is also used as a reading name. Please note that no individual parsing needs to be defined for a get or set. If no regex, XPath or JSON is specified for the command, then HTTPMOD will try to parse the response using all the defined readingRegex, reading XPath or readingJSON attributes.

;(get|set|reading)[0-9]+Regex
:If this attribute is specified, the Regex defined here is used to extract the value from the HTTP Response and assign it to a Reading with the name defined in the (get|set|reading)[0-9]+Name attribute.
:If this attribute is not specified for an individual Reading or get or set but without the numbers in the middle, e.g. as getRegex or readingRegex, then it applies to all the other readings / get / set commands where no specific Regex is defined.<br>
:The value to extract should be in a capture group / sub expression e.g. ([\d\.]+) in the above example. Multiple capture groups will create multiple readings (see explanation above)
:Using this attribute for a set command (setXXRegex) only makes sense if you want to parse the HTTP response to the HTTP request that the set command sent by defining the attribute setXXParseResponse.
:Please note that the old syntax <code>readingsRegex.*</code> does not work with all features of HTTPMOD and should be avoided. It might go away in a future version of HTTPMOD.
:If for get or set commands neither a generic Regex attribute without numbers nor a specific (get|set)[0-9]+Regex attribute is specified and also no XPath or JSON parsing specification is given for the get or set command, then HTTPMOD tries to use the parsing definitions for general readings defined in reading[0-9]+Name, reading[0-9]+Regex or XPath or JSON attributes and assigns the Readings that match here.

;(get|set|reading)[0-9]+RegOpt
:Lets the user specify regular expression modifiers. For example if the same regular expression should be matched as often as possible in the HTTP response, then you can specify RegOpt g which will case the matching to be done as /regex/g
:The results will be trated the same way as multiple capture groups so the reading name will be extended with -number.
:For other possible regular expression modifiers see http://perldoc.perl.org/perlre.html#Modifiers

;(get|set|reading)[0-9]+XPath
:defines an xpath to one or more values when parsing HTML data (see examples above)
:Using this attribute for a set command only makes sense if you want to parse the HTTP response to the HTTP request that the set command sent by defining the attribute setXXParseResponse.

;get|set|reading[0-9]+XPath-Strict
:defines an xpath to one or more values when parsing XML data (see examples above)
:Using this attribute for a set command only makes sense if you want to parse the HTTP response to the HTTP request that the set command sent by defining the attribute setXXParseResponse.

;(get|set|reading)[0-9]+AutoNumLen
:In cases where a regular expression or an XPath results in multiple results and these results are stored in a common reading name with extension -number, then you can modify the format of this number to have a fixed length with leading zeros. AutoNumLen 3 for example will lead to reading names ending with -001 -002 and so on.

;(get|set|reading)[0-9]+AlwaysNum
:if set to 1 this attributes forces reading names to end with a -1, -01 (depending on the above described AutoNumLen) even if just one value is parsed.

;get|set|reading[0-9]+JSON
:defines a path to the JSON object wanted by concatenating the object names. See the above example.
:If you don't know the paths, then start by using extractAllJSON and the use the names of the readings as values for the JSON attribute.<br>
:Please don't forget to also specify a name for a reading, get or set.
:Using this attribute for a set command only makes sense if you want to parse the HTTP response to the HTTP request that the set command sent by defining the attribute setXXParseResponse.

;(get|set|reading)[0-9]*RecombineExpr
:defines an expression that is used in an eval to compute one reading value out of the list of matches.
:This is supposed to be used for regexes or xpath specifications that produce multiple results if only one result that combines them is wanted. The list of matches will be in the variable @matchlist.
:Using this attribute for a set command only makes sense if you want to parse the HTTP response to the HTTP request that the set command sent by defining the attribute setXXParseResponse.

;get[0-9]*CheckAllReadings
:this attribute modifies the behavior of HTTPMOD when the HTTP Response of a get command is parsed. <br>
:If this attribute is set to 1, then additionally to the matching of the corresponding get specific regex (get[0-9]*Regex), XPath or JSON attribute also all the reading names and parse definitions defined in Reading[0-9]+Name and Reading[0-9]+Regex, XPath or JSON attributes are checked and if they match, the coresponding Readings are assigned as well.
:Please note that this does not mean that get01CheckAllReadings will cause a get02Regex to be used. Only the corresponding get01Regex will be used but additionally all the readingXYRegex attributes.
:This is automatically done if a get or set command is defined without its own parse attributes.

;(get|reading)[0-9]*OExpr
:defines an optional expression that is used in an eval to compute / format a readings value after parsing an HTTP response
:The raw value from the parsing will be in the variable $val.
:If specified as readingOExpr then the attribute value is a default for all other readings that don't specify an explicit reading[0-9]*Expr.
:Please note that the old syntax <b>readingsExpr.*</b> does not work with all features of HTTPMOD and should be avoided. It might go away in a future version of HTTPMOD.

;(get|reading)[0-9]*Expr
:This is the old syntax for (get|reading)[0-9]*OExpr. It should be replaced by (get|reading)[0-9]*OExpr. The set command upgradeAttributes which becomes visible when the attribute enableControlSet is set to 1, can do this renaming automatically.

;(get|reading)[0-9]*OMap
:Map that defines a mapping from raw value parsed to visible values like "0:mittig, 1:oberhalb, 2:unterhalb".
:If specified as readingOMap then the attribute value is a default for all other readings that don't specify an explicit reading[0-9]*Map.<br>
:The individual options in a map are separated by a komma and an optional space. Spaces are allowed to appear in a visible value however kommas are not possible.

;(get|reading)[0-9]*Map
:This is the old syntax for (get|reading)[0-9]*OMap. It should be replaced by (get|reading)[0-9]*OMap. The set command upgradeAttributes which becomes visible when the attribute enableControlSet is set to 1, can do this renaming automatically.

;(get|set|reading)[0-9]*Format
:Defines a format string that will be used in sprintf to format a reading value.
:If specified without the numbers in the middle e.g. as readingFormat then the attribute value is a default for all other readings that don't specify an explicit reading[0-9]*Format.
:Using this attribute for a set command only makes sense if you want to parse the HTTP response to the HTTP request that the set command sent by defining the attribute setXXParseResponse.<br>

;(get|set|reading)[0-9]*Decode
:defines an encoding to be used in a call to the perl function decode to convert the raw data string read from the device to a reading.
:This can be used if the device delivers strings in an encoding like cp850 instead of utf8.
:If your reading values contain Umlauts and they are shown as strange looking icons then you probably need to use this feature.
:Using this attribute for a set command only makes sense if you want to parse the HTTP response to the HTTP request that the set command sent by defining the attribute setXXParseResponse.

;(get|set|reading)[0-9]*Encode
:defines an encoding to be used in a call to the perl function encode to convert the raw data string read from the device to a reading.
:This can be used if the device delivers strings in an encoding like cp850 and after decoding it you want to reencode it to e.g. utf8.
:If your reading values contain Umlauts and they are shown as strange looking icons then you probably need to use this feature.
:Using this attribute for a set command only makes sense if you want to parse the HTTP response to the HTTP request that the set command sent by defining the attribute setXXParseResponse.

;(get|set)[0-9]*URL
:URL to be requested for the set or get command. If this option is missing, the URL specified during define will be used.

;(get|set)[0-9]*Data
:Data to be sent to the device as POST data when the get or set command is executed. if this attribute is not specified, an HTTP GET method will be used instead of an HTTP POST

;(get|set)[0-9]*NoData
:can be used to override a more generic attribute that specifies POST data for all get or set commands. With NoData no data is sent and therefor the request will be an HTTP GET.

;(get|set)[0-9]*Header.*
:HTTP Headers to be sent to the device when the set is executed

;requestHeader.*
:Define an optional additional HTTP Header to set in the HTTP request of the main loop

;requestData
:optional POST Data to be sent in the request of the main loop. If not defined, it will be an HTTP GET request as defined in HttpUtils which is used by this module

;get[0-9]+Poll
:if set to 1 the get is executed automatically during the normal update cycle (after the interval provided in the define command has elapsed)

;get[0-9]+PollDelay
:if the value should not be read in each iteration (after the interval given to the define command), then a minimum delay can be specified with this attribute. This has only an effect if the above Poll attribute has also been set. Every time the update function is called, it checks if since this get has been read the last time, the defined delay has elapsed. If not, then it is skipped this time.
:PollDelay can be specified as seconds or as x[0-9]+ which means a multiple of the interval in the define command.

;(get|set)[0-9]*TextArg
:For a get command this defines that the command accepts a text value after the option name. By default a get command doesn't accept optional values after the command name.
:If TextArg is specified and a value is passed after the get name then this value can then be used in a request URL, header or data as replacement for $val or in a user defined replacement that uses the internal "value" ($hash->{value}).
:If used for a set command then it defines that the value to be set doesn't require any validation / conversion.
:The raw value is passed on as text to the device. By default a set command expects a numerical value or a text value that is converted to a numeric value using a map.

;set[0-9]+Min
:Minimum value for input validation.

;set[0-9]+Max
:Maximum value for input validation.

;set[0-9]+IExpr
:Perl Expression to compute the raw value to be sent to the device from the input value passed to the set.

;set[0-9]+Expr
:This is the old syntax for (get|reading)[0-9]*IExpr. It should be replaced by (get|reading)[0-9]*IExpr. The set command upgradeAttributes which becomes visible when the attribute enableControlSet is set to 1, can do this renaming automatically.

;set[0-9]+IMap
:Map that defines a mapping from raw to input values like "0:mittig, 1:oberhalb, 2:unterhalb". This attribute atomatically creates a hint for FHEMWEB so the user can choose one of the input values.

;set[0-9]+Map
:This is the old syntax for (get|reading)[0-9]*IMap. It should be replaced by (get|reading)[0-9]*IMap. The set command upgradeAttributes which becomes visible when the attribute enableControlSet is set to 1, can do this renaming automatically.

;set[0-9]+Hint
:Explicit hint for fhemWEB that will be returned when set ? is seen. Can be used to get a slider or a list of values to choose from.

;set[0-9]*NoArg
:Defines that this set option doesn't require arguments. It allows sets like "on" or "off" without further values.

;set[0-9]*ParseResponse
:defines that the HTTP response to the set will be parsed as if it was the response to a get command.

;(get|set)[0-9]*URLExpr
:Defines a Perl expression to specify the HTTP Headers for this request. This overwrites any other header specification and should be used carefully only if needed. The original Header is availabe as $old. Typically this feature is not needed and it might go away in future versions of HTTPMOD. Please use the "replacement" attributes if you want to pass additional variable data to a web service.

;(get|set)[0-9]*DatExpr
:Defines a Perl expression to specify the HTTP Post data for this request. This overwrites any other post data specification and should be used carefully only if needed. The original Data is availabe as $old. Typically this feature is not needed and it might go away in future versions of HTTPMOD. Please use the "replacement" attributes if you want to pass additional variable data to a web service.

;(get|set)[0-9]*HdrExpr
:Defines a Perl expression to specify the URL for this request. This overwrites any other URL specification and should be used carefully only if needed. The original URL is availabe as $old. Typically this feature is not needed and it might go away in future versions of HTTPMOD. Please use the "replacement" attributes if you want to pass additional variable data to a web service.

;ReAuthRegex
:regular Expression to match an error page indicating that a session has expired and a new authentication for read access needs to be done.
:This attribute only makes sense if you need a forms based authentication for reading data and if you specify a multi step login procedure based on the sid.. attributes.
:This attribute is used for all requests. For set and get operations you can however specify individual reAuthRegexes with the (get|set)[0-9]*ReAuthRegex attributes.

;(get|set)[0-9]*ReAuthRegex
:Regex that will detect when a session has expired during a set operation and a new login needs to be performed.
:It works like the global reAuthRegex but is used for set operations.

;sid[0-9]*URL
:different URLs or one common URL to be used for each step of an optional login procedure.

;sid[0-9]*IDRegex
:different Regexes per login procedure step or one common Regex for all steps to extract the session ID from the HTTP response

;sid[0-9]*Data.*
:data part for each step to be sent as POST data to the corresponding URL

;sid[0-9]*Header.*
:HTTP Headers to be sent to the URL for the corresponding step

;sid[0-9]*IgnoreRedirects
:Tells the HttpUtils to not follow HTTP Redirects for this Request. Might be needed for some devices that set a session cookie within a 303 Redirect.

;clearSIdBeforeAuth
:will set the session id to "" before doing the authentication steps

;authRetries
:number of retries for authentication procedure - defaults to 1

;replacement[0-9]*Regex
:Defines a replacement to be applied to an HTTP request header, data or URL before it is sent. This allows any part of the request to be modified based on a reading, an internal or an expression.
:The regex defines which part of a header, data or URL should be replaced. The replacement is defined with the following attributes:

;replacement[0-9]*Mode
:Defines how the replacement should be done and what replacementValue means. Valid options are text, reading, internal and expression.

;replacement[0-9]*Value
:Defines the replacement. If the corresponding replacementMode is <code>text</code>, then value is a static text that is used as the replacement.
:If replacementMode is <code>reading</code> then Value can be the name of a reading of this device or it can be a reading of a different device referred to by devicename:reading.
:If replacementMode is <code>internal</code> the Value can be the name of an internal of this device or it can be an internal of a different device referred to by devicename:internal.
:If replacementMode is <code>expression</code> the the Value is treated as a Perl expression that computes the replacement value. The expression can use $1, $2 and so on to refer to capture groups of the corresponding regex that is matched against the original URL, header or post data.
:If replacementMode is <code>key</code> then the module will use a value from a key / value pair that is stored in an obfuscated form in the file system with the set storeKeyValue command. This might be useful for storing passwords.

;[gs]et[0-9]*Replacement[0-9]*Value
:This attribute can be used to override the replacement value for a specific get or set.

;get|reading[0-9]*MaxAge
:Defines how long a reading is valid before it is automatically overwritten with a replacement when the read function is called the next time.

;get|reading[0-9]*MaxAgeReplacement
:specifies the replacement for MaxAge - either as a static text or as a perl expression.

;get|reading[0-9]*MaxAgeReplacementMode
:specifies how the replacement is interpreted: can be text, expression and delete.

;get|reading[0-9]*DeleteIfUnmatched
:If set to 1 this attribute causes certain readings to be deleted when the parsing of the website does not match the specified reading. Internally HTTPMOD remembers which kind of operation created a reading (update, Get01, Get02 and so on). Specified readings will only be deleted if the same operation does not parse this reading again. This is especially useful for parsing that creates several matches / readings and the number of matches can vary from request to request. For example if reading01Regex creates 4 readings in one update cycle and in the next cycle it only matches two times then the readings containing the remaining values from the last round will be deleted.
:Please note that this mechanism will not work in all cases after a restart. Especially when a get definition does not contain its own parsing definition but ExtractAllJSON or relies on HTTPMOD to use all defined reading.* attributes to parse the responsee to a get command, old readings might not be deleted after a restart of fhem.
;get|reading[0-9]*DeleteOnError
:If set to 1 this attribute causes certain readings to be deleted when the website can not be reached and the HTTP request returns an error. Internally HTTPMOD remembers which kind of operation created a reading (update, Get01, Get02 and so on). Specified readings will only be deleted if the same operation returns an error.
The same restrictions as for DeleteIfUnmatched apply regarding a fhem restart.

;httpVersion
:defines the HTTP-Version to be sent to the server. This defaults to 1.0.

;sslVersion
:defines the SSL Version for the negotiation with the server. The attribute is evaluated by HttpUtils. If it is not specified, HttpUtils assumes SSLv23:!SSLv3:!SSLv2

;sslArgs
:defines a list that is converted to a key / value hash and gets passed to HttpUtils. To avoid certificate validation for broken servers you can for example specify
:<code>attr myDevice sslArgs SSL_verify_mode,SSL_VERIFY_NONE</code>

;alignTime
:Aligns each periodic read request for the defined interval to this base time. This is typcally something like 00:00 (see the FHEM at command)

;noShutdown
:pass the noshutdown flag to HTTPUtils for webservers that need it (some embedded webservers only deliver empty pages otherwise)

;disable
:stop doing automatic HTTP requests while this attribute is set to 1

;enableControlSet
:enables the built in set commands interval, stop, start, reread, upgradeAttributes, storeKeyValue.

;enableCookies
:enables the built in cookie handling if set to 1. With cookie handling each HTTPMOD device will remember cookies that the server sets and send them back to the server in the following requests.
:This simplifies session magamenet in cases where the server uses a session ID in a cookie. In such cases enabling cookies should be sufficient and no sidRegex and no manual definition of a cookie header should be necessary.

;showMatched
:if set to 1 then HTTPMOD will create a reading with the name MATCHED_READINGS that contains the names of all readings that could be matched in the last request as well as UNMATCHED_READINGS and LAST_REQUEST.

;showError
:if set to 1 then HTTPMOD will create a reading and event with the Name LAST_ERROR that contains the error message of the last error returned from HttpUtils.

;removeBuf
:if set to 1 then HTTPMOD removes the internal named buf when a HTTP-response has been received.
:$hash->{buf} is used internally be Fhem httpUtils and in some use cases it is desireable to remove this internal after reception
:because it contains a very long response which looks ugly in Fhemweb.

;timeout
:time in seconds to wait for an answer. Default value is 2

;queueDelay
:HTTP Requests will be sent from a queue in order to avoid blocking when several Requests have to be sent in sequence. This attribute defines the delay between calls to the function that handles the send queue. It defaults to one second.

;queueMax
:Defines the maximum size of the send queue. If it is reached then further HTTP Requests will be dropped and not be added to the queue

;minSendDelay
:Defines the minimum time between two HTTP Requests.

== Links ==
* Example: This example uses many features of HTTPMOD [https://forum.fhem.de/index.php?topic=135666.0 🎸 Owntone (Musik-Player) mit FHEM steuern]
* Example: [https://www.goingelectric.de/forum/viewtopic.php?f=57&t=21462|Abfrage Akkustand einer Zoe und mehr von Renault ZE Services]
* Example: [[Wetter_und_Wettervorhersagen#Wetter_von_Weather_Underground|Extract weather information from WeatherUnderground]]
* Example: [[Pollenflug|Pollen count]]
* Example: [[HTTPMOD Beispielkonfiguration zur Anbindung einer Daikin Klimaanlage mit WLAN-Modul|Connect Daikin aircondition to FHEM]]
* Example: [[Go-eCharger|Extract information from go-eCharger]]
* Example: [[Sonnenspeicher|Integration of energy supplies from sonnen (https://sonnenbatterie.de/en/start)]]
* Example: [https://forum.fhem.de/index.php/topic,95989.msg915870.html#msg915870 Miele 3rd party API für Miele Smarthome Geräte]
* Example: [https://forum.fhem.de/index.php/topic,84215.msg918662.html#msg918662 Honeywell Evohome Totalconnect]
* Example: [https://forum.fhem.de/index.php/topic,78613.msg889015.html#msg889015 Tigo Energy Integration]
* Example: [https://forum.fhem.de/index.php/topic,78613.msg708518.html#msg708518 Ecowater]
* {{Link2Forum|Topic=17804|LinkText=Thread}} in FHEM Forum that discusses the first version of this module
* {{Link2Forum|Topic=29471|LinkText=Thread}} in FHEM Forum that discusses the second major version of this module
* {{Link2Forum|Topic=45176|LinkText=Thread}} in FHEM Forum that discusses the third major version of this module
* [http://perldoc.perl.org/perlretut.html Introduction to regular expressions]
* [http://portswigger.net/burp/ BurpSuite]: Tool (local proxy) to help analyze http traffic

[[Kategorie:IP Components]]

DevelopmentFHEMWEB-API

2025-03-27T13:47:11Z

Torxgewinde: /* FW_directNotify */

{{Randnotiz|RNTyp=r|RNText=Bitte beachten: Diese Auflistung von Funktionen wird nicht aktiv durch alle Entwickler gepflegt. Es kann daher keine Garantie auf Vollständigkeit und Korrektheit gegeben werden, entscheidend ist immer der aktuelle Programm-Code.
<hr />
Please note: This list of functions is not official maintained by all developers. So there is no guarantee for completeness and correctness, at least the program code itself is relevant.
}}
Dieses Seite soll die verfügbaren Funktionen zugänglicher machen, um das Beisteuern von Funktionalität zu erleichtern.

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

== FHEMWEB-Server (pgm2) Perl-Funktionen ==

=== Globale Variablen ===

Globale Variablen:
{| class="wikitable"
|-
! Variablenname!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$FW_ME</code>'''

|| URL-Pfad unter dem der FHEMWEB-Server via HTTP erreichbar ist.

Bsp: <code>/fhem</code>
|-
| style="vertical-align:top" | '''<code>$FW_dir</code>'''

|| Das Basisverzeichnis auf dem lokalen Filesystem des FHEMWEB-Servers.

Bsp: <code>./www</code>
|-
| style="vertical-align:top" | '''<code>$FW_CSRF</code>'''

|| Enthält das aktuell gültige CSRF-Token als HTTP URL-Parameter für die aktuelle Verbindung oder bleibt leer.

Bsp: <code>&fwcsrf=csrf_165435377333711</code>
|-
| style="vertical-align:top" | '''<code>$FW_detail</code>'''

|| Enthält den Definitionsnamen der aktuell erzeugten Detailansicht.

Bsp: <code>Licht_Wohnzimmer</code>
|-
| style="vertical-align:top" | '''<code>$FW_room</code>'''

|| Enthält den Raumnamen der aktuell erzeugten Raumansicht.

Bsp: <code>Wohnzimmer</code>
|-
| style="vertical-align:top" | '''<code>$FW_wname</code>'''

|| Enthält den Definitionsnamen der aktuellen FHEMWEB-Instanz.

Bsp: <code>WEB</code>
|-
| style="vertical-align:top" | '''<code>$FW_cname</code>'''

|| Enthält den Definitionsnamen der aktuellen Verbindung (Connection-Name).

Bsp: <code>WEB_192.168.179.65_54406</code>
|-
| style="vertical-align:top" | '''<code>$FW_userAgent</code>'''

|| Enthält den User-Agent, welcher für den aktuellen Aufruf übermittelt wurde.

Bsp: <code>Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/63.0.3239.84 Safari/537.36</code>
|}

=== FW_makeImage ===

:<syntaxhighlight lang="perl">$html = FW_makeImage($icon, $text, $class);</syntaxhighlight>

FW_makeImage gibt HTML-Code zurück, der ein Icon aus dem dem FHEMWEB-Iconpool beschreibt.

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

''mandatory''
|| Eine Zeichenkette, mit optionaler Farbangabe <code>'<iconname>[@fillcolor>[@strokecolor>]]'</code>
Die Farbangaben ersetzen bei SVG Dateien nur die Farbwerte für stroke und fill, sofern diese in der SVG Datei <code>#000000</code> sind. Wird also eine Angabe <code>fill:#000000</code> oder <code>fill=#000000</code> im Quelltext des SVG gefunden, wird dies ersetzt durch <code>fill:fillcolor</code> bzw. <code>fill=fillcolor</code>, je nachdem ob ein Doppelpunkt oder Gleichheitszeichen vorhanden war.
|-
| style="vertical-align:top" | '''<code>$text</code>'''

''optional''
|| Wenn hier ein Text angegeben wird und <code>$icon</code> auf eine SVG-Datei verweist, dann wird <code>$text</code> dem svg-HTML-Tag hinzugefügt. Das Resultat im HTML-Quelltext ist dann in der Art <code><svg ... data-txt="$text" ... ></code>
Wenn hier ein Text angegeben wird und <code>$icon</code> auf eine Datei verweist die nicht auf ''.svg'' endet, dann wird der Pfad von der Datei hinter <code>$icon</code> als <code><img></code> eingebunden. Das Resultat im HTML-Quelltext ist dann in der Art <code><img ... src="..." alt="$text" title="$text"></code>
|-
| style="vertical-align:top" | '''<code>$class</code>'''

''optional''
|| Eine Zeichenkette, die eine CSS-Klasse angibt.
Wird der Parameter angegeben, wird dem <img> oder <svg> <code>class="$class"</code> hinzugefügt. Ist der Parameter <code>undef</code> oder nicht übergeben, so wird kein <code>class</code>-Attribut hinzugefügt.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$html</code>'''
|| Wenn '''<code>$icon</code>''' mit einem Iconnamen aus dem FHEMWEB-Iconpool übereinstimmt, wird der HTML-Code zum Einbinden des Icons zurückgegeben.
Mit nachgestellter Farbangabe <code>'<iconname@color>'</code>, wird das Icon entsprechend eingefärbt.
Entspricht die Zeichenkette keinem Iconnamen, wird die Zeichenkette zurückgegeben.
|}

Beispiel:
* <syntaxhighlight lang="perl">$html = FW_makeImage('fts_shutter_10@red');</syntaxhighlight>

=== FW_directNotify ===

:<syntaxhighlight lang="perl">FW_directNotify($filter, $fhemweb_instance, $javascript, "");</syntaxhighlight>

FW_directNotify führt Javascript auf einer longpoll FHEMWEB-Instanz aus, ohne Events zu erzeugen.

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

''optional''
|| Eine Zeichenkette, die mit "FILTER=" beginnt <code>"FILTER=<filter expression>"</code>.
|-
| style="vertical-align:top" | '''<code>$fhemweb_instance</code>'''

''mandatory''
|| Eine Zeichenkette, die eine longpoll FHEMWEB-Instanz <code>"#FHEMWEB:<FHEMWEB devicename>"</code> angibt.<br>
|-
| style="vertical-align:top" | '''<code>$javascript</code>'''

''mandatory''
|| Eine Zeichenkette, die ein Javascript angibt.
|-
| style="vertical-align:top" | '''<code>""</code>'''

''mandatory''
|| Eine Zeichenkette, leer oder (noch zu präzisieren).

|}

Beispiele:
* <syntaxhighlight lang="perl">FW_directNotify("FILTER=room=XXX", "#FHEMWEB:WEB", "FW_okDialog('Hello world!')", "");</syntaxhighlight>
* <syntaxhighlight lang="perl">FW_directNotify("FILTER=room=XXX", "#FHEMWEB:WEB", "location.reload('true')", "");</syntaxhighlight>
* siehe auch {{Link2Forum|Topic=48736|Message=404497|LinkText=Forenthread}} und https://forum.fhem.de/index.php?topic=134208.0

== FHEMWEB-Client (pgm2) Javascript-Funktionen ==

=== Globale Variablen ===

Globale Variablen:
{| class="wikitable"
|-
! Variablenname!! Bedeutung
|-
| style="vertical-align:top" | '''<code>FW_root</code>'''

|| FHEM-Ursprungsverzeichnis, steht auch im head-Element als Attribut <code>root</code> zur Verfügung.
|-
| style="vertical-align:top" | '''<code>FW_version</code>'''

|| Ein assoziatives Array, das die Versionszeichenketten der geladenen Javascript-Dateien enthält.

|}

=== FW_cmd ===

:<syntaxhighlight lang="javascript">FW_cmd(arg, callback);</syntaxhighlight>

FW_cmd führt einen Befehl auf dem FHEMWEB-Server aus.

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

''mandatory''
|| Eine Zeichenkette, die einem Befehl an den Server entspricht.
|-
| style="vertical-align:top" | '''<code>callback</code>'''

''optional''
|| Eine Javascript-Funktion, die ausgeführt wird, wenn der auf dem FHEM-Server ausgeführte Befehl einen Rückgabewert enthält, der weiter verarbeitet werden soll.

|}

Beispiel:
* <syntaxhighlight lang="javascript">FW_cmd(FW_root+'?cmd={FW_makeImage("fts_shutter_10")}&XHR=1', function(data){FW_okDialog(data)});</syntaxhighlight> Das Beispiel holt sich vom Server den HTML-Code des Icon "fts_shutter_10" und zeigt das Icon in einem Popup-Fenster an. Der vom Server auszuführende Befehl lautet <syntaxhighlight lang="perl" inline>{FW_makeImage("fts_shutter_10")}</syntaxhighlight>. An die Callback-Funktion <syntaxhighlight lang="javascript" inline>function(data){FW_okDialog(data)}</syntaxhighlight> wird der Rückgabewert vom Server als Parameter übergeben und steht als Variable <code>data</code> zur Verfügung.
* Will man mehrere Perl-Kommandos senden, kann es hilfreich sein die Daten vor der Übertragung BASE64 zu codieren. Im Kern nutzt man eine Wrapperfunktion für FW_cmd:<syntaxhighlight lang="javascript">
function FW_cmd_perlcode(arg, callback, rep) {
let perlcode = "eval(MIME::Base64::decode_base64('" +btoa(arg)+ "'))";
return FW_cmd(FW_root + '?cmd={' + perlcode + '}&XHR=1', callback, rep);
}
</syntaxhighlight>Weitere Details findet man im Forumspost: https://forum.fhem.de/index.php?topic=141230.0

=== FW_errmsg ===

:<syntaxhighlight lang="javascript">FW_errmsg(text, timeout);</syntaxhighlight>

FW_errmsg zeigt eine Meldung im FHEMWEB-Client (Browser) an.

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

''mandatory''
|| Eine Zeichenkette, die angezeigt wird. HTML-Code wird interpretiert.
|-
| style="vertical-align:top" | '''<code>timeout</code>'''

''mandatory''
|| Anzeigedauer der Zeichenkette in Millisekunden.

|}

Beispiel:
* <syntaxhighlight lang="javascript">FW_errmsg('Hello world!',10000);</syntaxhighlight>

=== FW_okDialog ===

:<syntaxhighlight lang="javascript">FW_okDialog(txt, parent, removeFn);</syntaxhighlight>

FW_okDialog öffnet im FHEMWEB-Client (Browser) ein modales Popup-Fenster.

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

''mandatory''
|| Eine Zeichenkette, die im Popup-Fenster angezeigt wird. HTML-Code wird interpretiert.
|-
| style="vertical-align:top" | '''<code>parent</code>'''

''optional''
|| Ein Objekt zur Verankerung des Popup-Fensters, default ist das body-Element. Eine FHEM-Widget-Schnittstelle wird interpretiert.

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

''optional''
|| Eine Javascript-Funktion, die beim Schliessen des Popup-Fensters ausgeführt wird.

|}

Beispiel:
* <syntaxhighlight lang="javascript">FW_okDialog('Hello world!',10000);</syntaxhighlight>
* <syntaxhighlight lang="javascript"><a href="#!" onclick="FW_okDialog('Hello world!')">Hello</a></syntaxhighlight>

Soll das Popup-Fenster aus einem Hyperlink heraus aufgerufen werden, dann ist darauf zu achten, dass ein ungültiger Anchor Tag verwendet wird. In diesem Beispiel "!". Dadurch wird ein unkontrolliertes Scrollen der Webseite effektiv verhindert und der Dialog erscheint genau dort wo man ihn haben möchte.

=== loadScript ===

:<syntaxhighlight lang="javascript">loadScript(scriptname, callback, force);</syntaxhighlight>

loadScript läd im FHEMWEB-Client (Browser) ein Javascript nach.

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

''mandatory''
|| Eine Zeichenkette, die den Sriptnamen enthält.

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

''optional''
|| Eine Javascript-Funktion, die ausgeführt wird, wenn das Script geladen wurde.

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

''optional''
|| Ein Flag, wenn gesetzt, wird das Laden erzwungen.

|}

Beispiel:
* <syntaxhighlight lang="javascript">loadScript("pgm2/jquery.knob.min.js", function(){<Javascript-Code>});</syntaxhighlight>

=== log ===

:<syntaxhighlight lang="javascript">log(text);</syntaxhighlight>

log zeigt einen Logeintrag in der Konsole des Browsers an.

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

''mandatory''
|| Eine Zeichenkette, die angezeigt wird.

|}

Beispiel:
* <syntaxhighlight lang="javascript">log('Hello world!');</syntaxhighlight>

== Links ==

* [[DevelopmentFHEMWEB|Development FHEMWEB (englischsprachig)]]
* [[DevelopmentModuleAPI]]

[[Kategorie:Development]]

DevelopmentFHEMWEB-API

2025-03-27T09:22:24Z

Torxgewinde: /* FW_cmd */

{{Randnotiz|RNTyp=r|RNText=Bitte beachten: Diese Auflistung von Funktionen wird nicht aktiv durch alle Entwickler gepflegt. Es kann daher keine Garantie auf Vollständigkeit und Korrektheit gegeben werden, entscheidend ist immer der aktuelle Programm-Code.
<hr />
Please note: This list of functions is not official maintained by all developers. So there is no guarantee for completeness and correctness, at least the program code itself is relevant.
}}
Dieses Seite soll die verfügbaren Funktionen zugänglicher machen, um das Beisteuern von Funktionalität zu erleichtern.

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

== FHEMWEB-Server (pgm2) Perl-Funktionen ==

=== Globale Variablen ===

Globale Variablen:
{| class="wikitable"
|-
! Variablenname!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$FW_ME</code>'''

|| URL-Pfad unter dem der FHEMWEB-Server via HTTP erreichbar ist.

Bsp: <code>/fhem</code>
|-
| style="vertical-align:top" | '''<code>$FW_dir</code>'''

|| Das Basisverzeichnis auf dem lokalen Filesystem des FHEMWEB-Servers.

Bsp: <code>./www</code>
|-
| style="vertical-align:top" | '''<code>$FW_CSRF</code>'''

|| Enthält das aktuell gültige CSRF-Token als HTTP URL-Parameter für die aktuelle Verbindung oder bleibt leer.

Bsp: <code>&fwcsrf=csrf_165435377333711</code>
|-
| style="vertical-align:top" | '''<code>$FW_detail</code>'''

|| Enthält den Definitionsnamen der aktuell erzeugten Detailansicht.

Bsp: <code>Licht_Wohnzimmer</code>
|-
| style="vertical-align:top" | '''<code>$FW_room</code>'''

|| Enthält den Raumnamen der aktuell erzeugten Raumansicht.

Bsp: <code>Wohnzimmer</code>
|-
| style="vertical-align:top" | '''<code>$FW_wname</code>'''

|| Enthält den Definitionsnamen der aktuellen FHEMWEB-Instanz.

Bsp: <code>WEB</code>
|-
| style="vertical-align:top" | '''<code>$FW_cname</code>'''

|| Enthält den Definitionsnamen der aktuellen Verbindung (Connection-Name).

Bsp: <code>WEB_192.168.179.65_54406</code>
|-
| style="vertical-align:top" | '''<code>$FW_userAgent</code>'''

|| Enthält den User-Agent, welcher für den aktuellen Aufruf übermittelt wurde.

Bsp: <code>Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/63.0.3239.84 Safari/537.36</code>
|}

=== FW_makeImage ===

:<syntaxhighlight lang="perl">$html = FW_makeImage($icon, $text, $class);</syntaxhighlight>

FW_makeImage gibt HTML-Code zurück, der ein Icon aus dem dem FHEMWEB-Iconpool beschreibt.

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

''mandatory''
|| Eine Zeichenkette, mit optionaler Farbangabe <code>'<iconname>[@fillcolor>[@strokecolor>]]'</code>
Die Farbangaben ersetzen bei SVG Dateien nur die Farbwerte für stroke und fill, sofern diese in der SVG Datei <code>#000000</code> sind. Wird also eine Angabe <code>fill:#000000</code> oder <code>fill=#000000</code> im Quelltext des SVG gefunden, wird dies ersetzt durch <code>fill:fillcolor</code> bzw. <code>fill=fillcolor</code>, je nachdem ob ein Doppelpunkt oder Gleichheitszeichen vorhanden war.
|-
| style="vertical-align:top" | '''<code>$text</code>'''

''optional''
|| Wenn hier ein Text angegeben wird und <code>$icon</code> auf eine SVG-Datei verweist, dann wird <code>$text</code> dem svg-HTML-Tag hinzugefügt. Das Resultat im HTML-Quelltext ist dann in der Art <code><svg ... data-txt="$text" ... ></code>
Wenn hier ein Text angegeben wird und <code>$icon</code> auf eine Datei verweist die nicht auf ''.svg'' endet, dann wird der Pfad von der Datei hinter <code>$icon</code> als <code><img></code> eingebunden. Das Resultat im HTML-Quelltext ist dann in der Art <code><img ... src="..." alt="$text" title="$text"></code>
|-
| style="vertical-align:top" | '''<code>$class</code>'''

''optional''
|| Eine Zeichenkette, die eine CSS-Klasse angibt.
Wird der Parameter angegeben, wird dem <img> oder <svg> <code>class="$class"</code> hinzugefügt. Ist der Parameter <code>undef</code> oder nicht übergeben, so wird kein <code>class</code>-Attribut hinzugefügt.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$html</code>'''
|| Wenn '''<code>$icon</code>''' mit einem Iconnamen aus dem FHEMWEB-Iconpool übereinstimmt, wird der HTML-Code zum Einbinden des Icons zurückgegeben.
Mit nachgestellter Farbangabe <code>'<iconname@color>'</code>, wird das Icon entsprechend eingefärbt.
Entspricht die Zeichenkette keinem Iconnamen, wird die Zeichenkette zurückgegeben.
|}

Beispiel:
* <syntaxhighlight lang="perl">$html = FW_makeImage('fts_shutter_10@red');</syntaxhighlight>

=== FW_directNotify ===

:<syntaxhighlight lang="perl">FW_directNotify($filter, $fhemweb_instance, $javascript, "");</syntaxhighlight>

FW_directNotify führt Javascript auf einer longpoll FHEMWEB-Instanz aus, ohne Events zu erzeugen.

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

''optional''
|| Eine Zeichenkette, die mit "FILTER=" beginnt <code>"FILTER=<filter expression>"</code>.
|-
| style="vertical-align:top" | '''<code>$fhemweb_instance</code>'''

''mandatory''
|| Eine Zeichenkette, die eine longpoll FHEMWEB-Instanz <code>"#FHEMWEB:<FHEMWEB devicename>"</code> angibt.<br>
|-
| style="vertical-align:top" | '''<code>$javascript</code>'''

''mandatory''
|| Eine Zeichenkette, die ein Javascript angibt.
|-
| style="vertical-align:top" | '''<code>""</code>'''

''mandatory''
|| Eine Zeichenkette, leer oder (noch zu präzisieren).

|}

Beispiele:
* <syntaxhighlight lang="perl">FW_directNotify("FILTER=room=XXX", "#FHEMWEB:WEB", "FW_okDialog('Hello world!')", "");</syntaxhighlight>
* <syntaxhighlight lang="perl">FW_directNotify("FILTER=room=XXX", "#FHEMWEB:WEB", "location.reload('true')", "");</syntaxhighlight>
* siehe auch {{Link2Forum|Topic=48736|Message=404497|LinkText=Forenthread}}

== FHEMWEB-Client (pgm2) Javascript-Funktionen ==

=== Globale Variablen ===

Globale Variablen:
{| class="wikitable"
|-
! Variablenname!! Bedeutung
|-
| style="vertical-align:top" | '''<code>FW_root</code>'''

|| FHEM-Ursprungsverzeichnis, steht auch im head-Element als Attribut <code>root</code> zur Verfügung.
|-
| style="vertical-align:top" | '''<code>FW_version</code>'''

|| Ein assoziatives Array, das die Versionszeichenketten der geladenen Javascript-Dateien enthält.

|}

=== FW_cmd ===

:<syntaxhighlight lang="javascript">FW_cmd(arg, callback);</syntaxhighlight>

FW_cmd führt einen Befehl auf dem FHEMWEB-Server aus.

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

''mandatory''
|| Eine Zeichenkette, die einem Befehl an den Server entspricht.
|-
| style="vertical-align:top" | '''<code>callback</code>'''

''optional''
|| Eine Javascript-Funktion, die ausgeführt wird, wenn der auf dem FHEM-Server ausgeführte Befehl einen Rückgabewert enthält, der weiter verarbeitet werden soll.

|}

Beispiel:
* <syntaxhighlight lang="javascript">FW_cmd(FW_root+'?cmd={FW_makeImage("fts_shutter_10")}&XHR=1', function(data){FW_okDialog(data)});</syntaxhighlight> Das Beispiel holt sich vom Server den HTML-Code des Icon "fts_shutter_10" und zeigt das Icon in einem Popup-Fenster an. Der vom Server auszuführende Befehl lautet <syntaxhighlight lang="perl" inline>{FW_makeImage("fts_shutter_10")}</syntaxhighlight>. An die Callback-Funktion <syntaxhighlight lang="javascript" inline>function(data){FW_okDialog(data)}</syntaxhighlight> wird der Rückgabewert vom Server als Parameter übergeben und steht als Variable <code>data</code> zur Verfügung.
* Will man mehrere Perl-Kommandos senden, kann es hilfreich sein die Daten vor der Übertragung BASE64 zu codieren. Im Kern nutzt man eine Wrapperfunktion für FW_cmd:<syntaxhighlight lang="javascript">
function FW_cmd_perlcode(arg, callback, rep) {
let perlcode = "eval(MIME::Base64::decode_base64('" +btoa(arg)+ "'))";
return FW_cmd(FW_root + '?cmd={' + perlcode + '}&XHR=1', callback, rep);
}
</syntaxhighlight>Weitere Details findet man im Forumspost: https://forum.fhem.de/index.php?topic=141230.0

=== FW_errmsg ===

:<syntaxhighlight lang="javascript">FW_errmsg(text, timeout);</syntaxhighlight>

FW_errmsg zeigt eine Meldung im FHEMWEB-Client (Browser) an.

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

''mandatory''
|| Eine Zeichenkette, die angezeigt wird. HTML-Code wird interpretiert.
|-
| style="vertical-align:top" | '''<code>timeout</code>'''

''mandatory''
|| Anzeigedauer der Zeichenkette in Millisekunden.

|}

Beispiel:
* <syntaxhighlight lang="javascript">FW_errmsg('Hello world!',10000);</syntaxhighlight>

=== FW_okDialog ===

:<syntaxhighlight lang="javascript">FW_okDialog(txt, parent, removeFn);</syntaxhighlight>

FW_okDialog öffnet im FHEMWEB-Client (Browser) ein modales Popup-Fenster.

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

''mandatory''
|| Eine Zeichenkette, die im Popup-Fenster angezeigt wird. HTML-Code wird interpretiert.
|-
| style="vertical-align:top" | '''<code>parent</code>'''

''optional''
|| Ein Objekt zur Verankerung des Popup-Fensters, default ist das body-Element. Eine FHEM-Widget-Schnittstelle wird interpretiert.

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

''optional''
|| Eine Javascript-Funktion, die beim Schliessen des Popup-Fensters ausgeführt wird.

|}

Beispiel:
* <syntaxhighlight lang="javascript">FW_okDialog('Hello world!',10000);</syntaxhighlight>
* <syntaxhighlight lang="javascript"><a href="#!" onclick="FW_okDialog('Hello world!')">Hello</a></syntaxhighlight>

Soll das Popup-Fenster aus einem Hyperlink heraus aufgerufen werden, dann ist darauf zu achten, dass ein ungültiger Anchor Tag verwendet wird. In diesem Beispiel "!". Dadurch wird ein unkontrolliertes Scrollen der Webseite effektiv verhindert und der Dialog erscheint genau dort wo man ihn haben möchte.

=== loadScript ===

:<syntaxhighlight lang="javascript">loadScript(scriptname, callback, force);</syntaxhighlight>

loadScript läd im FHEMWEB-Client (Browser) ein Javascript nach.

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

''mandatory''
|| Eine Zeichenkette, die den Sriptnamen enthält.

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

''optional''
|| Eine Javascript-Funktion, die ausgeführt wird, wenn das Script geladen wurde.

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

''optional''
|| Ein Flag, wenn gesetzt, wird das Laden erzwungen.

|}

Beispiel:
* <syntaxhighlight lang="javascript">loadScript("pgm2/jquery.knob.min.js", function(){<Javascript-Code>});</syntaxhighlight>

=== log ===

:<syntaxhighlight lang="javascript">log(text);</syntaxhighlight>

log zeigt einen Logeintrag in der Konsole des Browsers an.

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

''mandatory''
|| Eine Zeichenkette, die angezeigt wird.

|}

Beispiel:
* <syntaxhighlight lang="javascript">log('Hello world!');</syntaxhighlight>

== Links ==

* [[DevelopmentFHEMWEB|Development FHEMWEB (englischsprachig)]]
* [[DevelopmentModuleAPI]]

[[Kategorie:Development]]

DevelopmentFHEMWEB-API

2025-03-27T09:19:37Z

Torxgewinde: /* FW_cmd */

{{Randnotiz|RNTyp=r|RNText=Bitte beachten: Diese Auflistung von Funktionen wird nicht aktiv durch alle Entwickler gepflegt. Es kann daher keine Garantie auf Vollständigkeit und Korrektheit gegeben werden, entscheidend ist immer der aktuelle Programm-Code.
<hr />
Please note: This list of functions is not official maintained by all developers. So there is no guarantee for completeness and correctness, at least the program code itself is relevant.
}}
Dieses Seite soll die verfügbaren Funktionen zugänglicher machen, um das Beisteuern von Funktionalität zu erleichtern.

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

== FHEMWEB-Server (pgm2) Perl-Funktionen ==

=== Globale Variablen ===

Globale Variablen:
{| class="wikitable"
|-
! Variablenname!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$FW_ME</code>'''

|| URL-Pfad unter dem der FHEMWEB-Server via HTTP erreichbar ist.

Bsp: <code>/fhem</code>
|-
| style="vertical-align:top" | '''<code>$FW_dir</code>'''

|| Das Basisverzeichnis auf dem lokalen Filesystem des FHEMWEB-Servers.

Bsp: <code>./www</code>
|-
| style="vertical-align:top" | '''<code>$FW_CSRF</code>'''

|| Enthält das aktuell gültige CSRF-Token als HTTP URL-Parameter für die aktuelle Verbindung oder bleibt leer.

Bsp: <code>&fwcsrf=csrf_165435377333711</code>
|-
| style="vertical-align:top" | '''<code>$FW_detail</code>'''

|| Enthält den Definitionsnamen der aktuell erzeugten Detailansicht.

Bsp: <code>Licht_Wohnzimmer</code>
|-
| style="vertical-align:top" | '''<code>$FW_room</code>'''

|| Enthält den Raumnamen der aktuell erzeugten Raumansicht.

Bsp: <code>Wohnzimmer</code>
|-
| style="vertical-align:top" | '''<code>$FW_wname</code>'''

|| Enthält den Definitionsnamen der aktuellen FHEMWEB-Instanz.

Bsp: <code>WEB</code>
|-
| style="vertical-align:top" | '''<code>$FW_cname</code>'''

|| Enthält den Definitionsnamen der aktuellen Verbindung (Connection-Name).

Bsp: <code>WEB_192.168.179.65_54406</code>
|-
| style="vertical-align:top" | '''<code>$FW_userAgent</code>'''

|| Enthält den User-Agent, welcher für den aktuellen Aufruf übermittelt wurde.

Bsp: <code>Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/63.0.3239.84 Safari/537.36</code>
|}

=== FW_makeImage ===

:<syntaxhighlight lang="perl">$html = FW_makeImage($icon, $text, $class);</syntaxhighlight>

FW_makeImage gibt HTML-Code zurück, der ein Icon aus dem dem FHEMWEB-Iconpool beschreibt.

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

''mandatory''
|| Eine Zeichenkette, mit optionaler Farbangabe <code>'<iconname>[@fillcolor>[@strokecolor>]]'</code>
Die Farbangaben ersetzen bei SVG Dateien nur die Farbwerte für stroke und fill, sofern diese in der SVG Datei <code>#000000</code> sind. Wird also eine Angabe <code>fill:#000000</code> oder <code>fill=#000000</code> im Quelltext des SVG gefunden, wird dies ersetzt durch <code>fill:fillcolor</code> bzw. <code>fill=fillcolor</code>, je nachdem ob ein Doppelpunkt oder Gleichheitszeichen vorhanden war.
|-
| style="vertical-align:top" | '''<code>$text</code>'''

''optional''
|| Wenn hier ein Text angegeben wird und <code>$icon</code> auf eine SVG-Datei verweist, dann wird <code>$text</code> dem svg-HTML-Tag hinzugefügt. Das Resultat im HTML-Quelltext ist dann in der Art <code><svg ... data-txt="$text" ... ></code>
Wenn hier ein Text angegeben wird und <code>$icon</code> auf eine Datei verweist die nicht auf ''.svg'' endet, dann wird der Pfad von der Datei hinter <code>$icon</code> als <code><img></code> eingebunden. Das Resultat im HTML-Quelltext ist dann in der Art <code><img ... src="..." alt="$text" title="$text"></code>
|-
| style="vertical-align:top" | '''<code>$class</code>'''

''optional''
|| Eine Zeichenkette, die eine CSS-Klasse angibt.
Wird der Parameter angegeben, wird dem <img> oder <svg> <code>class="$class"</code> hinzugefügt. Ist der Parameter <code>undef</code> oder nicht übergeben, so wird kein <code>class</code>-Attribut hinzugefügt.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$html</code>'''
|| Wenn '''<code>$icon</code>''' mit einem Iconnamen aus dem FHEMWEB-Iconpool übereinstimmt, wird der HTML-Code zum Einbinden des Icons zurückgegeben.
Mit nachgestellter Farbangabe <code>'<iconname@color>'</code>, wird das Icon entsprechend eingefärbt.
Entspricht die Zeichenkette keinem Iconnamen, wird die Zeichenkette zurückgegeben.
|}

Beispiel:
* <syntaxhighlight lang="perl">$html = FW_makeImage('fts_shutter_10@red');</syntaxhighlight>

=== FW_directNotify ===

:<syntaxhighlight lang="perl">FW_directNotify($filter, $fhemweb_instance, $javascript, "");</syntaxhighlight>

FW_directNotify führt Javascript auf einer longpoll FHEMWEB-Instanz aus, ohne Events zu erzeugen.

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

''optional''
|| Eine Zeichenkette, die mit "FILTER=" beginnt <code>"FILTER=<filter expression>"</code>.
|-
| style="vertical-align:top" | '''<code>$fhemweb_instance</code>'''

''mandatory''
|| Eine Zeichenkette, die eine longpoll FHEMWEB-Instanz <code>"#FHEMWEB:<FHEMWEB devicename>"</code> angibt.<br>
|-
| style="vertical-align:top" | '''<code>$javascript</code>'''

''mandatory''
|| Eine Zeichenkette, die ein Javascript angibt.
|-
| style="vertical-align:top" | '''<code>""</code>'''

''mandatory''
|| Eine Zeichenkette, leer oder (noch zu präzisieren).

|}

Beispiele:
* <syntaxhighlight lang="perl">FW_directNotify("FILTER=room=XXX", "#FHEMWEB:WEB", "FW_okDialog('Hello world!')", "");</syntaxhighlight>
* <syntaxhighlight lang="perl">FW_directNotify("FILTER=room=XXX", "#FHEMWEB:WEB", "location.reload('true')", "");</syntaxhighlight>
* siehe auch {{Link2Forum|Topic=48736|Message=404497|LinkText=Forenthread}}

== FHEMWEB-Client (pgm2) Javascript-Funktionen ==

=== Globale Variablen ===

Globale Variablen:
{| class="wikitable"
|-
! Variablenname!! Bedeutung
|-
| style="vertical-align:top" | '''<code>FW_root</code>'''

|| FHEM-Ursprungsverzeichnis, steht auch im head-Element als Attribut <code>root</code> zur Verfügung.
|-
| style="vertical-align:top" | '''<code>FW_version</code>'''

|| Ein assoziatives Array, das die Versionszeichenketten der geladenen Javascript-Dateien enthält.

|}

=== FW_cmd ===

:<syntaxhighlight lang="javascript">FW_cmd(arg, callback);</syntaxhighlight>

FW_cmd führt einen Befehl auf dem FHEMWEB-Server aus.

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

''mandatory''
|| Eine Zeichenkette, die einem Befehl an den Server entspricht.
|-
| style="vertical-align:top" | '''<code>callback</code>'''

''optional''
|| Eine Javascript-Funktion, die ausgeführt wird, wenn der auf dem FHEM-Server ausgeführte Befehl einen Rückgabewert enthält, der weiter verarbeitet werden soll.

|}

Beispiel:
* <syntaxhighlight lang="javascript">FW_cmd(FW_root+'?cmd={FW_makeImage("fts_shutter_10")}&XHR=1', function(data){FW_okDialog(data)});</syntaxhighlight> Das Beispiel holt sich vom Server den HTML-Code des Icon "fts_shutter_10" und zeigt das Icon in einem Popup-Fenster an. Der vom Server auszuführende Befehl lautet <syntaxhighlight lang="perl" inline>{FW_makeImage("fts_shutter_10")}</syntaxhighlight>. An die Callback-Funktion <syntaxhighlight lang="javascript" inline>function(data){FW_okDialog(data)}</syntaxhighlight> wird der Rückgabewert vom Server als Parameter übergeben und steht als Variable <code>data</code> zur Verfügung.
* Will man mehrere Perl-Kommandos senden, kann es hilfreich sein die Daten vor der Übertragung BASE64 zu codieren. Wie man dies nutzt behandelt ein Forumspost: https://forum.fhem.de/index.php?topic=141230.0

=== FW_errmsg ===

:<syntaxhighlight lang="javascript">FW_errmsg(text, timeout);</syntaxhighlight>

FW_errmsg zeigt eine Meldung im FHEMWEB-Client (Browser) an.

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

''mandatory''
|| Eine Zeichenkette, die angezeigt wird. HTML-Code wird interpretiert.
|-
| style="vertical-align:top" | '''<code>timeout</code>'''

''mandatory''
|| Anzeigedauer der Zeichenkette in Millisekunden.

|}

Beispiel:
* <syntaxhighlight lang="javascript">FW_errmsg('Hello world!',10000);</syntaxhighlight>

=== FW_okDialog ===

:<syntaxhighlight lang="javascript">FW_okDialog(txt, parent, removeFn);</syntaxhighlight>

FW_okDialog öffnet im FHEMWEB-Client (Browser) ein modales Popup-Fenster.

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

''mandatory''
|| Eine Zeichenkette, die im Popup-Fenster angezeigt wird. HTML-Code wird interpretiert.
|-
| style="vertical-align:top" | '''<code>parent</code>'''

''optional''
|| Ein Objekt zur Verankerung des Popup-Fensters, default ist das body-Element. Eine FHEM-Widget-Schnittstelle wird interpretiert.

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

''optional''
|| Eine Javascript-Funktion, die beim Schliessen des Popup-Fensters ausgeführt wird.

|}

Beispiel:
* <syntaxhighlight lang="javascript">FW_okDialog('Hello world!',10000);</syntaxhighlight>
* <syntaxhighlight lang="javascript"><a href="#!" onclick="FW_okDialog('Hello world!')">Hello</a></syntaxhighlight>

Soll das Popup-Fenster aus einem Hyperlink heraus aufgerufen werden, dann ist darauf zu achten, dass ein ungültiger Anchor Tag verwendet wird. In diesem Beispiel "!". Dadurch wird ein unkontrolliertes Scrollen der Webseite effektiv verhindert und der Dialog erscheint genau dort wo man ihn haben möchte.

=== loadScript ===

:<syntaxhighlight lang="javascript">loadScript(scriptname, callback, force);</syntaxhighlight>

loadScript läd im FHEMWEB-Client (Browser) ein Javascript nach.

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

''mandatory''
|| Eine Zeichenkette, die den Sriptnamen enthält.

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

''optional''
|| Eine Javascript-Funktion, die ausgeführt wird, wenn das Script geladen wurde.

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

''optional''
|| Ein Flag, wenn gesetzt, wird das Laden erzwungen.

|}

Beispiel:
* <syntaxhighlight lang="javascript">loadScript("pgm2/jquery.knob.min.js", function(){<Javascript-Code>});</syntaxhighlight>

=== log ===

:<syntaxhighlight lang="javascript">log(text);</syntaxhighlight>

log zeigt einen Logeintrag in der Konsole des Browsers an.

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

''mandatory''
|| Eine Zeichenkette, die angezeigt wird.

|}

Beispiel:
* <syntaxhighlight lang="javascript">log('Hello world!');</syntaxhighlight>

== Links ==

* [[DevelopmentFHEMWEB|Development FHEMWEB (englischsprachig)]]
* [[DevelopmentModuleAPI]]

[[Kategorie:Development]]

DevelopmentFHEMWEB-API

2025-03-24T15:58:18Z

Torxgewinde: /* FW_makeImage */

{{Randnotiz|RNTyp=r|RNText=Bitte beachten: Diese Auflistung von Funktionen wird nicht aktiv durch alle Entwickler gepflegt. Es kann daher keine Garantie auf Vollständigkeit und Korrektheit gegeben werden, entscheidend ist immer der aktuelle Programm-Code.
<hr />
Please note: This list of functions is not official maintained by all developers. So there is no guarantee for completeness and correctness, at least the program code itself is relevant.
}}
Dieses Seite soll die verfügbaren Funktionen zugänglicher machen, um das Beisteuern von Funktionalität zu erleichtern.

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

== FHEMWEB-Server (pgm2) Perl-Funktionen ==

=== Globale Variablen ===

Globale Variablen:
{| class="wikitable"
|-
! Variablenname!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$FW_ME</code>'''

|| URL-Pfad unter dem der FHEMWEB-Server via HTTP erreichbar ist.

Bsp: <code>/fhem</code>
|-
| style="vertical-align:top" | '''<code>$FW_dir</code>'''

|| Das Basisverzeichnis auf dem lokalen Filesystem des FHEMWEB-Servers.

Bsp: <code>./www</code>
|-
| style="vertical-align:top" | '''<code>$FW_CSRF</code>'''

|| Enthält das aktuell gültige CSRF-Token als HTTP URL-Parameter für die aktuelle Verbindung oder bleibt leer.

Bsp: <code>&fwcsrf=csrf_165435377333711</code>
|-
| style="vertical-align:top" | '''<code>$FW_detail</code>'''

|| Enthält den Definitionsnamen der aktuell erzeugten Detailansicht.

Bsp: <code>Licht_Wohnzimmer</code>
|-
| style="vertical-align:top" | '''<code>$FW_room</code>'''

|| Enthält den Raumnamen der aktuell erzeugten Raumansicht.

Bsp: <code>Wohnzimmer</code>
|-
| style="vertical-align:top" | '''<code>$FW_wname</code>'''

|| Enthält den Definitionsnamen der aktuellen FHEMWEB-Instanz.

Bsp: <code>WEB</code>
|-
| style="vertical-align:top" | '''<code>$FW_cname</code>'''

|| Enthält den Definitionsnamen der aktuellen Verbindung (Connection-Name).

Bsp: <code>WEB_192.168.179.65_54406</code>
|-
| style="vertical-align:top" | '''<code>$FW_userAgent</code>'''

|| Enthält den User-Agent, welcher für den aktuellen Aufruf übermittelt wurde.

Bsp: <code>Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/63.0.3239.84 Safari/537.36</code>
|}

=== FW_makeImage ===

:<syntaxhighlight lang="perl">$html = FW_makeImage($icon, $text, $class);</syntaxhighlight>

FW_makeImage gibt HTML-Code zurück, der ein Icon aus dem dem FHEMWEB-Iconpool beschreibt.

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

''mandatory''
|| Eine Zeichenkette, mit optionaler Farbangabe <code>'<iconname>[@fillcolor>[@strokecolor>]]'</code>
Die Farbangaben ersetzen bei SVG Dateien nur die Farbwerte für stroke und fill, sofern diese in der SVG Datei <code>#000000</code> sind. Wird also eine Angabe <code>fill:#000000</code> oder <code>fill=#000000</code> im Quelltext des SVG gefunden, wird dies ersetzt durch <code>fill:fillcolor</code> bzw. <code>fill=fillcolor</code>, je nachdem ob ein Doppelpunkt oder Gleichheitszeichen vorhanden war.
|-
| style="vertical-align:top" | '''<code>$text</code>'''

''optional''
|| Wenn hier ein Text angegeben wird und <code>$icon</code> auf eine SVG-Datei verweist, dann wird <code>$text</code> dem svg-HTML-Tag hinzugefügt. Das Resultat im HTML-Quelltext ist dann in der Art <code><svg ... data-txt="$text" ... ></code>
Wenn hier ein Text angegeben wird und <code>$icon</code> auf eine Datei verweist die nicht auf ''.svg'' endet, dann wird der Pfad von der Datei hinter <code>$icon</code> als <code><img></code> eingebunden. Das Resultat im HTML-Quelltext ist dann in der Art <code><img ... src="..." alt="$text" title="$text"></code>
|-
| style="vertical-align:top" | '''<code>$class</code>'''

''optional''
|| Eine Zeichenkette, die eine CSS-Klasse angibt.
Wird der Parameter angegeben, wird dem <img> oder <svg> <code>class="$class"</code> hinzugefügt. Ist der Parameter <code>undef</code> oder nicht übergeben, so wird kein <code>class</code>-Attribut hinzugefügt.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$html</code>'''
|| Wenn '''<code>$icon</code>''' mit einem Iconnamen aus dem FHEMWEB-Iconpool übereinstimmt, wird der HTML-Code zum Einbinden des Icons zurückgegeben.
Mit nachgestellter Farbangabe <code>'<iconname@color>'</code>, wird das Icon entsprechend eingefärbt.
Entspricht die Zeichenkette keinem Iconnamen, wird die Zeichenkette zurückgegeben.
|}

Beispiel:
* <syntaxhighlight lang="perl">$html = FW_makeImage('fts_shutter_10@red');</syntaxhighlight>

=== FW_directNotify ===

:<syntaxhighlight lang="perl">FW_directNotify($filter, $fhemweb_instance, $javascript, "");</syntaxhighlight>

FW_directNotify führt Javascript auf einer longpoll FHEMWEB-Instanz aus, ohne Events zu erzeugen.

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

''optional''
|| Eine Zeichenkette, die mit "FILTER=" beginnt <code>"FILTER=<filter expression>"</code>.
|-
| style="vertical-align:top" | '''<code>$fhemweb_instance</code>'''

''mandatory''
|| Eine Zeichenkette, die eine longpoll FHEMWEB-Instanz <code>"#FHEMWEB:<FHEMWEB devicename>"</code> angibt.<br>
|-
| style="vertical-align:top" | '''<code>$javascript</code>'''

''mandatory''
|| Eine Zeichenkette, die ein Javascript angibt.
|-
| style="vertical-align:top" | '''<code>""</code>'''

''mandatory''
|| Eine Zeichenkette, leer oder (noch zu präzisieren).

|}

Beispiele:
* <syntaxhighlight lang="perl">FW_directNotify("FILTER=room=XXX", "#FHEMWEB:WEB", "FW_okDialog('Hello world!')", "");</syntaxhighlight>
* <syntaxhighlight lang="perl">FW_directNotify("FILTER=room=XXX", "#FHEMWEB:WEB", "location.reload('true')", "");</syntaxhighlight>
* siehe auch {{Link2Forum|Topic=48736|Message=404497|LinkText=Forenthread}}

== FHEMWEB-Client (pgm2) Javascript-Funktionen ==

=== Globale Variablen ===

Globale Variablen:
{| class="wikitable"
|-
! Variablenname!! Bedeutung
|-
| style="vertical-align:top" | '''<code>FW_root</code>'''

|| FHEM-Ursprungsverzeichnis, steht auch im head-Element als Attribut <code>root</code> zur Verfügung.
|-
| style="vertical-align:top" | '''<code>FW_version</code>'''

|| Ein assoziatives Array, das die Versionszeichenketten der geladenen Javascript-Dateien enthält.

|}

=== FW_cmd ===

:<syntaxhighlight lang="javascript">FW_cmd(arg, callback);</syntaxhighlight>

FW_cmd führt einen Befehl auf dem FHEMWEB-Server aus.

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

''mandatory''
|| Eine Zeichenkette, die einem Befehl an den Server entspricht.
|-
| style="vertical-align:top" | '''<code>callback</code>'''

''optional''
|| Eine Javascript-Funktion, die ausgeführt wird, wenn der auf dem FHEM-Server ausgeführte Befehl einen Rückgabewert enthält, der weiter verarbeitet werden soll.

|}

Beispiel:
* <syntaxhighlight lang="javascript">FW_cmd(FW_root+'?cmd={FW_makeImage("fts_shutter_10")}&XHR=1', function(data){FW_okDialog(data)});</syntaxhighlight> Das Beispiel holt sich vom Server den HTML-Code des Icon "fts_shutter_10" und zeigt das Icon in einem Popup-Fenster an. Der vom Server auszuführende Befehl lautet <syntaxhighlight lang="perl" inline>{FW_makeImage("fts_shutter_10")}</syntaxhighlight>. An die Callback-Funktion <syntaxhighlight lang="javascript" inline>function(data){FW_okDialog(data)}</syntaxhighlight> wird der Rückgabewert vom Server als Parameter übergeben und steht als Variable <code>data</code> zur Verfügung.

=== FW_errmsg ===

:<syntaxhighlight lang="javascript">FW_errmsg(text, timeout);</syntaxhighlight>

FW_errmsg zeigt eine Meldung im FHEMWEB-Client (Browser) an.

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

''mandatory''
|| Eine Zeichenkette, die angezeigt wird. HTML-Code wird interpretiert.
|-
| style="vertical-align:top" | '''<code>timeout</code>'''

''mandatory''
|| Anzeigedauer der Zeichenkette in Millisekunden.

|}

Beispiel:
* <syntaxhighlight lang="javascript">FW_errmsg('Hello world!',10000);</syntaxhighlight>

=== FW_okDialog ===

:<syntaxhighlight lang="javascript">FW_okDialog(txt, parent, removeFn);</syntaxhighlight>

FW_okDialog öffnet im FHEMWEB-Client (Browser) ein modales Popup-Fenster.

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

''mandatory''
|| Eine Zeichenkette, die im Popup-Fenster angezeigt wird. HTML-Code wird interpretiert.
|-
| style="vertical-align:top" | '''<code>parent</code>'''

''optional''
|| Ein Objekt zur Verankerung des Popup-Fensters, default ist das body-Element. Eine FHEM-Widget-Schnittstelle wird interpretiert.

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

''optional''
|| Eine Javascript-Funktion, die beim Schliessen des Popup-Fensters ausgeführt wird.

|}

Beispiel:
* <syntaxhighlight lang="javascript">FW_okDialog('Hello world!',10000);</syntaxhighlight>
* <syntaxhighlight lang="javascript"><a href="#!" onclick="FW_okDialog('Hello world!')">Hello</a></syntaxhighlight>

Soll das Popup-Fenster aus einem Hyperlink heraus aufgerufen werden, dann ist darauf zu achten, dass ein ungültiger Anchor Tag verwendet wird. In diesem Beispiel "!". Dadurch wird ein unkontrolliertes Scrollen der Webseite effektiv verhindert und der Dialog erscheint genau dort wo man ihn haben möchte.

=== loadScript ===

:<syntaxhighlight lang="javascript">loadScript(scriptname, callback, force);</syntaxhighlight>

loadScript läd im FHEMWEB-Client (Browser) ein Javascript nach.

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

''mandatory''
|| Eine Zeichenkette, die den Sriptnamen enthält.

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

''optional''
|| Eine Javascript-Funktion, die ausgeführt wird, wenn das Script geladen wurde.

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

''optional''
|| Ein Flag, wenn gesetzt, wird das Laden erzwungen.

|}

Beispiel:
* <syntaxhighlight lang="javascript">loadScript("pgm2/jquery.knob.min.js", function(){<Javascript-Code>});</syntaxhighlight>

=== log ===

:<syntaxhighlight lang="javascript">log(text);</syntaxhighlight>

log zeigt einen Logeintrag in der Konsole des Browsers an.

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

''mandatory''
|| Eine Zeichenkette, die angezeigt wird.

|}

Beispiel:
* <syntaxhighlight lang="javascript">log('Hello world!');</syntaxhighlight>

== Links ==

* [[DevelopmentFHEMWEB|Development FHEMWEB (englischsprachig)]]
* [[DevelopmentModuleAPI]]

[[Kategorie:Development]]

DevelopmentFHEMWEB-API

2025-03-24T15:53:20Z

Torxgewinde: /* FW_makeImage */

{{Randnotiz|RNTyp=r|RNText=Bitte beachten: Diese Auflistung von Funktionen wird nicht aktiv durch alle Entwickler gepflegt. Es kann daher keine Garantie auf Vollständigkeit und Korrektheit gegeben werden, entscheidend ist immer der aktuelle Programm-Code.
<hr />
Please note: This list of functions is not official maintained by all developers. So there is no guarantee for completeness and correctness, at least the program code itself is relevant.
}}
Dieses Seite soll die verfügbaren Funktionen zugänglicher machen, um das Beisteuern von Funktionalität zu erleichtern.

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

== FHEMWEB-Server (pgm2) Perl-Funktionen ==

=== Globale Variablen ===

Globale Variablen:
{| class="wikitable"
|-
! Variablenname!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$FW_ME</code>'''

|| URL-Pfad unter dem der FHEMWEB-Server via HTTP erreichbar ist.

Bsp: <code>/fhem</code>
|-
| style="vertical-align:top" | '''<code>$FW_dir</code>'''

|| Das Basisverzeichnis auf dem lokalen Filesystem des FHEMWEB-Servers.

Bsp: <code>./www</code>
|-
| style="vertical-align:top" | '''<code>$FW_CSRF</code>'''

|| Enthält das aktuell gültige CSRF-Token als HTTP URL-Parameter für die aktuelle Verbindung oder bleibt leer.

Bsp: <code>&fwcsrf=csrf_165435377333711</code>
|-
| style="vertical-align:top" | '''<code>$FW_detail</code>'''

|| Enthält den Definitionsnamen der aktuell erzeugten Detailansicht.

Bsp: <code>Licht_Wohnzimmer</code>
|-
| style="vertical-align:top" | '''<code>$FW_room</code>'''

|| Enthält den Raumnamen der aktuell erzeugten Raumansicht.

Bsp: <code>Wohnzimmer</code>
|-
| style="vertical-align:top" | '''<code>$FW_wname</code>'''

|| Enthält den Definitionsnamen der aktuellen FHEMWEB-Instanz.

Bsp: <code>WEB</code>
|-
| style="vertical-align:top" | '''<code>$FW_cname</code>'''

|| Enthält den Definitionsnamen der aktuellen Verbindung (Connection-Name).

Bsp: <code>WEB_192.168.179.65_54406</code>
|-
| style="vertical-align:top" | '''<code>$FW_userAgent</code>'''

|| Enthält den User-Agent, welcher für den aktuellen Aufruf übermittelt wurde.

Bsp: <code>Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/63.0.3239.84 Safari/537.36</code>
|}

=== FW_makeImage ===

:<syntaxhighlight lang="perl">$html = FW_makeImage($icon, $text, $class);</syntaxhighlight>

FW_makeImage gibt HTML-Code zurück, der ein Icon aus dem dem FHEMWEB-Iconpool beschreibt.

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

''mandatory''
|| Eine Zeichenkette, mit optionaler Farbangabe <code>'<iconname>[@color>]'</code>
|-
| style="vertical-align:top" | '''<code>$text</code>'''

''optional''
|| Wenn hier ein Text angegeben wird und <code>$icon</code> auf eine SVG-Datei verweist, dann wird <code>$text</code> dem svg-HTML-Tag hinzugefügt. Das Resultat im HTML-Quelltext ist dann in der Art <code><svg ... data-txt="$text" ... ></code>
Wenn hier ein Text angegeben wird und <code>$icon</code> auf eine Datei verweist die nicht auf ''.svg'' endet, dann wird der Pfad von der Datei hinter <code>$icon</code> als <code><img></code> eingebunden. Das Resultat im HTML-Quelltext ist dann in der Art <code><img ... src="..." alt="$text" title="$text"></code>
|-
| style="vertical-align:top" | '''<code>$class</code>'''

''optional''
|| Eine Zeichenkette, die eine CSS-Klasse angibt.
Wird der Parameter angegeben, wird dem <img> oder <svg> <code>class="$class"</code> hinzugefügt. Ist der Parameter <code>undef</code> oder nicht übergeben, so wird kein <code>class</code>-Attribut hinzugefügt.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$html</code>'''
|| Wenn '''<code>$icon</code>''' mit einem Iconnamen aus dem FHEMWEB-Iconpool übereinstimmt, wird der HTML-Code zum Einbinden des Icons zurückgegeben.
Mit nachgestellter Farbangabe <code>'<iconname@color>'</code>, wird das Icon entsprechend eingefärbt.
Entspricht die Zeichenkette keinem Iconnamen, wird die Zeichenkette zurückgegeben.
|}

Beispiel:
* <syntaxhighlight lang="perl">$html = FW_makeImage('fts_shutter_10@red');</syntaxhighlight>

=== FW_directNotify ===

:<syntaxhighlight lang="perl">FW_directNotify($filter, $fhemweb_instance, $javascript, "");</syntaxhighlight>

FW_directNotify führt Javascript auf einer longpoll FHEMWEB-Instanz aus, ohne Events zu erzeugen.

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

''optional''
|| Eine Zeichenkette, die mit "FILTER=" beginnt <code>"FILTER=<filter expression>"</code>.
|-
| style="vertical-align:top" | '''<code>$fhemweb_instance</code>'''

''mandatory''
|| Eine Zeichenkette, die eine longpoll FHEMWEB-Instanz <code>"#FHEMWEB:<FHEMWEB devicename>"</code> angibt.<br>
|-
| style="vertical-align:top" | '''<code>$javascript</code>'''

''mandatory''
|| Eine Zeichenkette, die ein Javascript angibt.
|-
| style="vertical-align:top" | '''<code>""</code>'''

''mandatory''
|| Eine Zeichenkette, leer oder (noch zu präzisieren).

|}

Beispiele:
* <syntaxhighlight lang="perl">FW_directNotify("FILTER=room=XXX", "#FHEMWEB:WEB", "FW_okDialog('Hello world!')", "");</syntaxhighlight>
* <syntaxhighlight lang="perl">FW_directNotify("FILTER=room=XXX", "#FHEMWEB:WEB", "location.reload('true')", "");</syntaxhighlight>
* siehe auch {{Link2Forum|Topic=48736|Message=404497|LinkText=Forenthread}}

== FHEMWEB-Client (pgm2) Javascript-Funktionen ==

=== Globale Variablen ===

Globale Variablen:
{| class="wikitable"
|-
! Variablenname!! Bedeutung
|-
| style="vertical-align:top" | '''<code>FW_root</code>'''

|| FHEM-Ursprungsverzeichnis, steht auch im head-Element als Attribut <code>root</code> zur Verfügung.
|-
| style="vertical-align:top" | '''<code>FW_version</code>'''

|| Ein assoziatives Array, das die Versionszeichenketten der geladenen Javascript-Dateien enthält.

|}

=== FW_cmd ===

:<syntaxhighlight lang="javascript">FW_cmd(arg, callback);</syntaxhighlight>

FW_cmd führt einen Befehl auf dem FHEMWEB-Server aus.

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

''mandatory''
|| Eine Zeichenkette, die einem Befehl an den Server entspricht.
|-
| style="vertical-align:top" | '''<code>callback</code>'''

''optional''
|| Eine Javascript-Funktion, die ausgeführt wird, wenn der auf dem FHEM-Server ausgeführte Befehl einen Rückgabewert enthält, der weiter verarbeitet werden soll.

|}

Beispiel:
* <syntaxhighlight lang="javascript">FW_cmd(FW_root+'?cmd={FW_makeImage("fts_shutter_10")}&XHR=1', function(data){FW_okDialog(data)});</syntaxhighlight> Das Beispiel holt sich vom Server den HTML-Code des Icon "fts_shutter_10" und zeigt das Icon in einem Popup-Fenster an. Der vom Server auszuführende Befehl lautet <syntaxhighlight lang="perl" inline>{FW_makeImage("fts_shutter_10")}</syntaxhighlight>. An die Callback-Funktion <syntaxhighlight lang="javascript" inline>function(data){FW_okDialog(data)}</syntaxhighlight> wird der Rückgabewert vom Server als Parameter übergeben und steht als Variable <code>data</code> zur Verfügung.

=== FW_errmsg ===

:<syntaxhighlight lang="javascript">FW_errmsg(text, timeout);</syntaxhighlight>

FW_errmsg zeigt eine Meldung im FHEMWEB-Client (Browser) an.

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

''mandatory''
|| Eine Zeichenkette, die angezeigt wird. HTML-Code wird interpretiert.
|-
| style="vertical-align:top" | '''<code>timeout</code>'''

''mandatory''
|| Anzeigedauer der Zeichenkette in Millisekunden.

|}

Beispiel:
* <syntaxhighlight lang="javascript">FW_errmsg('Hello world!',10000);</syntaxhighlight>

=== FW_okDialog ===

:<syntaxhighlight lang="javascript">FW_okDialog(txt, parent, removeFn);</syntaxhighlight>

FW_okDialog öffnet im FHEMWEB-Client (Browser) ein modales Popup-Fenster.

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

''mandatory''
|| Eine Zeichenkette, die im Popup-Fenster angezeigt wird. HTML-Code wird interpretiert.
|-
| style="vertical-align:top" | '''<code>parent</code>'''

''optional''
|| Ein Objekt zur Verankerung des Popup-Fensters, default ist das body-Element. Eine FHEM-Widget-Schnittstelle wird interpretiert.

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

''optional''
|| Eine Javascript-Funktion, die beim Schliessen des Popup-Fensters ausgeführt wird.

|}

Beispiel:
* <syntaxhighlight lang="javascript">FW_okDialog('Hello world!',10000);</syntaxhighlight>
* <syntaxhighlight lang="javascript"><a href="#!" onclick="FW_okDialog('Hello world!')">Hello</a></syntaxhighlight>

Soll das Popup-Fenster aus einem Hyperlink heraus aufgerufen werden, dann ist darauf zu achten, dass ein ungültiger Anchor Tag verwendet wird. In diesem Beispiel "!". Dadurch wird ein unkontrolliertes Scrollen der Webseite effektiv verhindert und der Dialog erscheint genau dort wo man ihn haben möchte.

=== loadScript ===

:<syntaxhighlight lang="javascript">loadScript(scriptname, callback, force);</syntaxhighlight>

loadScript läd im FHEMWEB-Client (Browser) ein Javascript nach.

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

''mandatory''
|| Eine Zeichenkette, die den Sriptnamen enthält.

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

''optional''
|| Eine Javascript-Funktion, die ausgeführt wird, wenn das Script geladen wurde.

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

''optional''
|| Ein Flag, wenn gesetzt, wird das Laden erzwungen.

|}

Beispiel:
* <syntaxhighlight lang="javascript">loadScript("pgm2/jquery.knob.min.js", function(){<Javascript-Code>});</syntaxhighlight>

=== log ===

:<syntaxhighlight lang="javascript">log(text);</syntaxhighlight>

log zeigt einen Logeintrag in der Konsole des Browsers an.

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

''mandatory''
|| Eine Zeichenkette, die angezeigt wird.

|}

Beispiel:
* <syntaxhighlight lang="javascript">log('Hello world!');</syntaxhighlight>

== Links ==

* [[DevelopmentFHEMWEB|Development FHEMWEB (englischsprachig)]]
* [[DevelopmentModuleAPI]]

[[Kategorie:Development]]

DevelopmentFHEMWEB-API

2025-03-24T15:52:56Z

Torxgewinde: /* FW_makeImage */

{{Randnotiz|RNTyp=r|RNText=Bitte beachten: Diese Auflistung von Funktionen wird nicht aktiv durch alle Entwickler gepflegt. Es kann daher keine Garantie auf Vollständigkeit und Korrektheit gegeben werden, entscheidend ist immer der aktuelle Programm-Code.
<hr />
Please note: This list of functions is not official maintained by all developers. So there is no guarantee for completeness and correctness, at least the program code itself is relevant.
}}
Dieses Seite soll die verfügbaren Funktionen zugänglicher machen, um das Beisteuern von Funktionalität zu erleichtern.

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

== FHEMWEB-Server (pgm2) Perl-Funktionen ==

=== Globale Variablen ===

Globale Variablen:
{| class="wikitable"
|-
! Variablenname!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$FW_ME</code>'''

|| URL-Pfad unter dem der FHEMWEB-Server via HTTP erreichbar ist.

Bsp: <code>/fhem</code>
|-
| style="vertical-align:top" | '''<code>$FW_dir</code>'''

|| Das Basisverzeichnis auf dem lokalen Filesystem des FHEMWEB-Servers.

Bsp: <code>./www</code>
|-
| style="vertical-align:top" | '''<code>$FW_CSRF</code>'''

|| Enthält das aktuell gültige CSRF-Token als HTTP URL-Parameter für die aktuelle Verbindung oder bleibt leer.

Bsp: <code>&fwcsrf=csrf_165435377333711</code>
|-
| style="vertical-align:top" | '''<code>$FW_detail</code>'''

|| Enthält den Definitionsnamen der aktuell erzeugten Detailansicht.

Bsp: <code>Licht_Wohnzimmer</code>
|-
| style="vertical-align:top" | '''<code>$FW_room</code>'''

|| Enthält den Raumnamen der aktuell erzeugten Raumansicht.

Bsp: <code>Wohnzimmer</code>
|-
| style="vertical-align:top" | '''<code>$FW_wname</code>'''

|| Enthält den Definitionsnamen der aktuellen FHEMWEB-Instanz.

Bsp: <code>WEB</code>
|-
| style="vertical-align:top" | '''<code>$FW_cname</code>'''

|| Enthält den Definitionsnamen der aktuellen Verbindung (Connection-Name).

Bsp: <code>WEB_192.168.179.65_54406</code>
|-
| style="vertical-align:top" | '''<code>$FW_userAgent</code>'''

|| Enthält den User-Agent, welcher für den aktuellen Aufruf übermittelt wurde.

Bsp: <code>Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/63.0.3239.84 Safari/537.36</code>
|}

=== FW_makeImage ===

:<syntaxhighlight lang="perl">$html = FW_makeImage($icon, $text, $class);</syntaxhighlight>

FW_makeImage gibt HTML-Code zurück, der ein Icon aus dem dem FHEMWEB-Iconpool beschreibt.

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

''mandatory''
|| Eine Zeichenkette, mit optionaler Farbangabe <code>'<iconname>[@color>]'</code>
|-
| style="vertical-align:top" | '''<code>$text</code>'''

''optional''
|| Wenn hier ein Text angegeben wird und <code>$icon</code> auf eine SVG-Datei verweist, dann wird <code>$text</code> dem svg-HTML-Tag hinzugefügt. Das Resultat im HTML-Quelltext ist dann in der Art <code><svg ... data-txt="$text" ... ></code>
Wenn hier ein Text angegeben wird und <code>$icon</code> auf eine Datei verweist die nicht auf ''.svg'' endet, dann wird der Pfad von der Datei hinter <code>$icon</code> als <code><img></code> eingebunden. Das Resultat im HTML-Quelltext ist dann in der Art <code><img ... src="..." alt="$text" title="$text"></code>
|-
| style="vertical-align:top" | '''<code>$class</code>'''

''optional''
|| Eine Zeichenkette, die eine CSS-Klasse angibt.
Wir der Parameter angegeben, wird dem <img> oder <svg> <code>class="$class"</code> hinzugefügt. Ist der Parameter <code>undef</code> oder nicht übergeben, so wird kein <code>class</code>-Attribut hinzugefügt.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$html</code>'''
|| Wenn '''<code>$icon</code>''' mit einem Iconnamen aus dem FHEMWEB-Iconpool übereinstimmt, wird der HTML-Code zum Einbinden des Icons zurückgegeben.
Mit nachgestellter Farbangabe <code>'<iconname@color>'</code>, wird das Icon entsprechend eingefärbt.
Entspricht die Zeichenkette keinem Iconnamen, wird die Zeichenkette zurückgegeben.
|}

Beispiel:
* <syntaxhighlight lang="perl">$html = FW_makeImage('fts_shutter_10@red');</syntaxhighlight>

=== FW_directNotify ===

:<syntaxhighlight lang="perl">FW_directNotify($filter, $fhemweb_instance, $javascript, "");</syntaxhighlight>

FW_directNotify führt Javascript auf einer longpoll FHEMWEB-Instanz aus, ohne Events zu erzeugen.

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

''optional''
|| Eine Zeichenkette, die mit "FILTER=" beginnt <code>"FILTER=<filter expression>"</code>.
|-
| style="vertical-align:top" | '''<code>$fhemweb_instance</code>'''

''mandatory''
|| Eine Zeichenkette, die eine longpoll FHEMWEB-Instanz <code>"#FHEMWEB:<FHEMWEB devicename>"</code> angibt.<br>
|-
| style="vertical-align:top" | '''<code>$javascript</code>'''

''mandatory''
|| Eine Zeichenkette, die ein Javascript angibt.
|-
| style="vertical-align:top" | '''<code>""</code>'''

''mandatory''
|| Eine Zeichenkette, leer oder (noch zu präzisieren).

|}

Beispiele:
* <syntaxhighlight lang="perl">FW_directNotify("FILTER=room=XXX", "#FHEMWEB:WEB", "FW_okDialog('Hello world!')", "");</syntaxhighlight>
* <syntaxhighlight lang="perl">FW_directNotify("FILTER=room=XXX", "#FHEMWEB:WEB", "location.reload('true')", "");</syntaxhighlight>
* siehe auch {{Link2Forum|Topic=48736|Message=404497|LinkText=Forenthread}}

== FHEMWEB-Client (pgm2) Javascript-Funktionen ==

=== Globale Variablen ===

Globale Variablen:
{| class="wikitable"
|-
! Variablenname!! Bedeutung
|-
| style="vertical-align:top" | '''<code>FW_root</code>'''

|| FHEM-Ursprungsverzeichnis, steht auch im head-Element als Attribut <code>root</code> zur Verfügung.
|-
| style="vertical-align:top" | '''<code>FW_version</code>'''

|| Ein assoziatives Array, das die Versionszeichenketten der geladenen Javascript-Dateien enthält.

|}

=== FW_cmd ===

:<syntaxhighlight lang="javascript">FW_cmd(arg, callback);</syntaxhighlight>

FW_cmd führt einen Befehl auf dem FHEMWEB-Server aus.

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

''mandatory''
|| Eine Zeichenkette, die einem Befehl an den Server entspricht.
|-
| style="vertical-align:top" | '''<code>callback</code>'''

''optional''
|| Eine Javascript-Funktion, die ausgeführt wird, wenn der auf dem FHEM-Server ausgeführte Befehl einen Rückgabewert enthält, der weiter verarbeitet werden soll.

|}

Beispiel:
* <syntaxhighlight lang="javascript">FW_cmd(FW_root+'?cmd={FW_makeImage("fts_shutter_10")}&XHR=1', function(data){FW_okDialog(data)});</syntaxhighlight> Das Beispiel holt sich vom Server den HTML-Code des Icon "fts_shutter_10" und zeigt das Icon in einem Popup-Fenster an. Der vom Server auszuführende Befehl lautet <syntaxhighlight lang="perl" inline>{FW_makeImage("fts_shutter_10")}</syntaxhighlight>. An die Callback-Funktion <syntaxhighlight lang="javascript" inline>function(data){FW_okDialog(data)}</syntaxhighlight> wird der Rückgabewert vom Server als Parameter übergeben und steht als Variable <code>data</code> zur Verfügung.

=== FW_errmsg ===

:<syntaxhighlight lang="javascript">FW_errmsg(text, timeout);</syntaxhighlight>

FW_errmsg zeigt eine Meldung im FHEMWEB-Client (Browser) an.

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

''mandatory''
|| Eine Zeichenkette, die angezeigt wird. HTML-Code wird interpretiert.
|-
| style="vertical-align:top" | '''<code>timeout</code>'''

''mandatory''
|| Anzeigedauer der Zeichenkette in Millisekunden.

|}

Beispiel:
* <syntaxhighlight lang="javascript">FW_errmsg('Hello world!',10000);</syntaxhighlight>

=== FW_okDialog ===

:<syntaxhighlight lang="javascript">FW_okDialog(txt, parent, removeFn);</syntaxhighlight>

FW_okDialog öffnet im FHEMWEB-Client (Browser) ein modales Popup-Fenster.

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

''mandatory''
|| Eine Zeichenkette, die im Popup-Fenster angezeigt wird. HTML-Code wird interpretiert.
|-
| style="vertical-align:top" | '''<code>parent</code>'''

''optional''
|| Ein Objekt zur Verankerung des Popup-Fensters, default ist das body-Element. Eine FHEM-Widget-Schnittstelle wird interpretiert.

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

''optional''
|| Eine Javascript-Funktion, die beim Schliessen des Popup-Fensters ausgeführt wird.

|}

Beispiel:
* <syntaxhighlight lang="javascript">FW_okDialog('Hello world!',10000);</syntaxhighlight>
* <syntaxhighlight lang="javascript"><a href="#!" onclick="FW_okDialog('Hello world!')">Hello</a></syntaxhighlight>

Soll das Popup-Fenster aus einem Hyperlink heraus aufgerufen werden, dann ist darauf zu achten, dass ein ungültiger Anchor Tag verwendet wird. In diesem Beispiel "!". Dadurch wird ein unkontrolliertes Scrollen der Webseite effektiv verhindert und der Dialog erscheint genau dort wo man ihn haben möchte.

=== loadScript ===

:<syntaxhighlight lang="javascript">loadScript(scriptname, callback, force);</syntaxhighlight>

loadScript läd im FHEMWEB-Client (Browser) ein Javascript nach.

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

''mandatory''
|| Eine Zeichenkette, die den Sriptnamen enthält.

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

''optional''
|| Eine Javascript-Funktion, die ausgeführt wird, wenn das Script geladen wurde.

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

''optional''
|| Ein Flag, wenn gesetzt, wird das Laden erzwungen.

|}

Beispiel:
* <syntaxhighlight lang="javascript">loadScript("pgm2/jquery.knob.min.js", function(){<Javascript-Code>});</syntaxhighlight>

=== log ===

:<syntaxhighlight lang="javascript">log(text);</syntaxhighlight>

log zeigt einen Logeintrag in der Konsole des Browsers an.

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

''mandatory''
|| Eine Zeichenkette, die angezeigt wird.

|}

Beispiel:
* <syntaxhighlight lang="javascript">log('Hello world!');</syntaxhighlight>

== Links ==

* [[DevelopmentFHEMWEB|Development FHEMWEB (englischsprachig)]]
* [[DevelopmentModuleAPI]]

[[Kategorie:Development]]

DevelopmentFHEMWEB-API

2025-03-24T15:52:26Z

Torxgewinde: /* FW_makeImage */

{{Randnotiz|RNTyp=r|RNText=Bitte beachten: Diese Auflistung von Funktionen wird nicht aktiv durch alle Entwickler gepflegt. Es kann daher keine Garantie auf Vollständigkeit und Korrektheit gegeben werden, entscheidend ist immer der aktuelle Programm-Code.
<hr />
Please note: This list of functions is not official maintained by all developers. So there is no guarantee for completeness and correctness, at least the program code itself is relevant.
}}
Dieses Seite soll die verfügbaren Funktionen zugänglicher machen, um das Beisteuern von Funktionalität zu erleichtern.

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

== FHEMWEB-Server (pgm2) Perl-Funktionen ==

=== Globale Variablen ===

Globale Variablen:
{| class="wikitable"
|-
! Variablenname!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$FW_ME</code>'''

|| URL-Pfad unter dem der FHEMWEB-Server via HTTP erreichbar ist.

Bsp: <code>/fhem</code>
|-
| style="vertical-align:top" | '''<code>$FW_dir</code>'''

|| Das Basisverzeichnis auf dem lokalen Filesystem des FHEMWEB-Servers.

Bsp: <code>./www</code>
|-
| style="vertical-align:top" | '''<code>$FW_CSRF</code>'''

|| Enthält das aktuell gültige CSRF-Token als HTTP URL-Parameter für die aktuelle Verbindung oder bleibt leer.

Bsp: <code>&fwcsrf=csrf_165435377333711</code>
|-
| style="vertical-align:top" | '''<code>$FW_detail</code>'''

|| Enthält den Definitionsnamen der aktuell erzeugten Detailansicht.

Bsp: <code>Licht_Wohnzimmer</code>
|-
| style="vertical-align:top" | '''<code>$FW_room</code>'''

|| Enthält den Raumnamen der aktuell erzeugten Raumansicht.

Bsp: <code>Wohnzimmer</code>
|-
| style="vertical-align:top" | '''<code>$FW_wname</code>'''

|| Enthält den Definitionsnamen der aktuellen FHEMWEB-Instanz.

Bsp: <code>WEB</code>
|-
| style="vertical-align:top" | '''<code>$FW_cname</code>'''

|| Enthält den Definitionsnamen der aktuellen Verbindung (Connection-Name).

Bsp: <code>WEB_192.168.179.65_54406</code>
|-
| style="vertical-align:top" | '''<code>$FW_userAgent</code>'''

|| Enthält den User-Agent, welcher für den aktuellen Aufruf übermittelt wurde.

Bsp: <code>Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/63.0.3239.84 Safari/537.36</code>
|}

=== FW_makeImage ===

:<syntaxhighlight lang="perl">$html = FW_makeImage($icon, $text, $class);</syntaxhighlight>

FW_makeImage gibt HTML-Code zurück, der ein Icon aus dem dem FHEMWEB-Iconpool beschreibt.

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

''mandatory''
|| Eine Zeichenkette, mit optionaler Farbangabe <code>'<iconname>[@color>]'</code>
|-
| style="vertical-align:top" | '''<code>$text</code>'''

''optional''
|| Wenn hier ein Text angegeben wird und <code>$icon</code> auf eine SVG-Datei verweist, dann wird <code>$text</code> dem svg-HTML-Tag hinzugefügt. Das Resultat im HTML-Quelltext ist dann in der Art <code><svg ... data-txt="$text" ... ></code>
Wenn hier ein Text angegeben wird und <code>$icon</code> auf eine Datei verweist die nicht auf ''.svg'' endet, dann wird der Pfad von der Datei hinter <code>$icon</code> als <code><img></code> eingebunden. Das Resultat im HTML-Quelltext ist dann in der Art <code><img ... src="..." alt="$text" title="$text"></code>
|-
| style="vertical-align:top" | '''<code>$class</code>'''

''optional''
|| Eine Zeichenkette, die eine CSS-Klasse angibt.
Wir der Parameter angegeben, wird dem <img> oder <svg> class="$class" hinzugefügt. Ist der Parameter <code>undef</code> oder nicht übergeben, so wird kein <code>class</code>-Attribut hinzugefügt.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$html</code>'''
|| Wenn '''<code>$icon</code>''' mit einem Iconnamen aus dem FHEMWEB-Iconpool übereinstimmt, wird der HTML-Code zum Einbinden des Icons zurückgegeben.
Mit nachgestellter Farbangabe <code>'<iconname@color>'</code>, wird das Icon entsprechend eingefärbt.
Entspricht die Zeichenkette keinem Iconnamen, wird die Zeichenkette zurückgegeben.
|}

Beispiel:
* <syntaxhighlight lang="perl">$html = FW_makeImage('fts_shutter_10@red');</syntaxhighlight>

=== FW_directNotify ===

:<syntaxhighlight lang="perl">FW_directNotify($filter, $fhemweb_instance, $javascript, "");</syntaxhighlight>

FW_directNotify führt Javascript auf einer longpoll FHEMWEB-Instanz aus, ohne Events zu erzeugen.

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

''optional''
|| Eine Zeichenkette, die mit "FILTER=" beginnt <code>"FILTER=<filter expression>"</code>.
|-
| style="vertical-align:top" | '''<code>$fhemweb_instance</code>'''

''mandatory''
|| Eine Zeichenkette, die eine longpoll FHEMWEB-Instanz <code>"#FHEMWEB:<FHEMWEB devicename>"</code> angibt.<br>
|-
| style="vertical-align:top" | '''<code>$javascript</code>'''

''mandatory''
|| Eine Zeichenkette, die ein Javascript angibt.
|-
| style="vertical-align:top" | '''<code>""</code>'''

''mandatory''
|| Eine Zeichenkette, leer oder (noch zu präzisieren).

|}

Beispiele:
* <syntaxhighlight lang="perl">FW_directNotify("FILTER=room=XXX", "#FHEMWEB:WEB", "FW_okDialog('Hello world!')", "");</syntaxhighlight>
* <syntaxhighlight lang="perl">FW_directNotify("FILTER=room=XXX", "#FHEMWEB:WEB", "location.reload('true')", "");</syntaxhighlight>
* siehe auch {{Link2Forum|Topic=48736|Message=404497|LinkText=Forenthread}}

== FHEMWEB-Client (pgm2) Javascript-Funktionen ==

=== Globale Variablen ===

Globale Variablen:
{| class="wikitable"
|-
! Variablenname!! Bedeutung
|-
| style="vertical-align:top" | '''<code>FW_root</code>'''

|| FHEM-Ursprungsverzeichnis, steht auch im head-Element als Attribut <code>root</code> zur Verfügung.
|-
| style="vertical-align:top" | '''<code>FW_version</code>'''

|| Ein assoziatives Array, das die Versionszeichenketten der geladenen Javascript-Dateien enthält.

|}

=== FW_cmd ===

:<syntaxhighlight lang="javascript">FW_cmd(arg, callback);</syntaxhighlight>

FW_cmd führt einen Befehl auf dem FHEMWEB-Server aus.

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

''mandatory''
|| Eine Zeichenkette, die einem Befehl an den Server entspricht.
|-
| style="vertical-align:top" | '''<code>callback</code>'''

''optional''
|| Eine Javascript-Funktion, die ausgeführt wird, wenn der auf dem FHEM-Server ausgeführte Befehl einen Rückgabewert enthält, der weiter verarbeitet werden soll.

|}

Beispiel:
* <syntaxhighlight lang="javascript">FW_cmd(FW_root+'?cmd={FW_makeImage("fts_shutter_10")}&XHR=1', function(data){FW_okDialog(data)});</syntaxhighlight> Das Beispiel holt sich vom Server den HTML-Code des Icon "fts_shutter_10" und zeigt das Icon in einem Popup-Fenster an. Der vom Server auszuführende Befehl lautet <syntaxhighlight lang="perl" inline>{FW_makeImage("fts_shutter_10")}</syntaxhighlight>. An die Callback-Funktion <syntaxhighlight lang="javascript" inline>function(data){FW_okDialog(data)}</syntaxhighlight> wird der Rückgabewert vom Server als Parameter übergeben und steht als Variable <code>data</code> zur Verfügung.

=== FW_errmsg ===

:<syntaxhighlight lang="javascript">FW_errmsg(text, timeout);</syntaxhighlight>

FW_errmsg zeigt eine Meldung im FHEMWEB-Client (Browser) an.

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

''mandatory''
|| Eine Zeichenkette, die angezeigt wird. HTML-Code wird interpretiert.
|-
| style="vertical-align:top" | '''<code>timeout</code>'''

''mandatory''
|| Anzeigedauer der Zeichenkette in Millisekunden.

|}

Beispiel:
* <syntaxhighlight lang="javascript">FW_errmsg('Hello world!',10000);</syntaxhighlight>

=== FW_okDialog ===

:<syntaxhighlight lang="javascript">FW_okDialog(txt, parent, removeFn);</syntaxhighlight>

FW_okDialog öffnet im FHEMWEB-Client (Browser) ein modales Popup-Fenster.

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

''mandatory''
|| Eine Zeichenkette, die im Popup-Fenster angezeigt wird. HTML-Code wird interpretiert.
|-
| style="vertical-align:top" | '''<code>parent</code>'''

''optional''
|| Ein Objekt zur Verankerung des Popup-Fensters, default ist das body-Element. Eine FHEM-Widget-Schnittstelle wird interpretiert.

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

''optional''
|| Eine Javascript-Funktion, die beim Schliessen des Popup-Fensters ausgeführt wird.

|}

Beispiel:
* <syntaxhighlight lang="javascript">FW_okDialog('Hello world!',10000);</syntaxhighlight>
* <syntaxhighlight lang="javascript"><a href="#!" onclick="FW_okDialog('Hello world!')">Hello</a></syntaxhighlight>

Soll das Popup-Fenster aus einem Hyperlink heraus aufgerufen werden, dann ist darauf zu achten, dass ein ungültiger Anchor Tag verwendet wird. In diesem Beispiel "!". Dadurch wird ein unkontrolliertes Scrollen der Webseite effektiv verhindert und der Dialog erscheint genau dort wo man ihn haben möchte.

=== loadScript ===

:<syntaxhighlight lang="javascript">loadScript(scriptname, callback, force);</syntaxhighlight>

loadScript läd im FHEMWEB-Client (Browser) ein Javascript nach.

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

''mandatory''
|| Eine Zeichenkette, die den Sriptnamen enthält.

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

''optional''
|| Eine Javascript-Funktion, die ausgeführt wird, wenn das Script geladen wurde.

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

''optional''
|| Ein Flag, wenn gesetzt, wird das Laden erzwungen.

|}

Beispiel:
* <syntaxhighlight lang="javascript">loadScript("pgm2/jquery.knob.min.js", function(){<Javascript-Code>});</syntaxhighlight>

=== log ===

:<syntaxhighlight lang="javascript">log(text);</syntaxhighlight>

log zeigt einen Logeintrag in der Konsole des Browsers an.

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

''mandatory''
|| Eine Zeichenkette, die angezeigt wird.

|}

Beispiel:
* <syntaxhighlight lang="javascript">log('Hello world!');</syntaxhighlight>

== Links ==

* [[DevelopmentFHEMWEB|Development FHEMWEB (englischsprachig)]]
* [[DevelopmentModuleAPI]]

[[Kategorie:Development]]

DevelopmentFHEMWEB-API

2025-03-24T15:51:29Z

Torxgewinde: FW_makeImage Paremeter ein wenig genauer beschrieben

{{Randnotiz|RNTyp=r|RNText=Bitte beachten: Diese Auflistung von Funktionen wird nicht aktiv durch alle Entwickler gepflegt. Es kann daher keine Garantie auf Vollständigkeit und Korrektheit gegeben werden, entscheidend ist immer der aktuelle Programm-Code.
<hr />
Please note: This list of functions is not official maintained by all developers. So there is no guarantee for completeness and correctness, at least the program code itself is relevant.
}}
Dieses Seite soll die verfügbaren Funktionen zugänglicher machen, um das Beisteuern von Funktionalität zu erleichtern.

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

== FHEMWEB-Server (pgm2) Perl-Funktionen ==

=== Globale Variablen ===

Globale Variablen:
{| class="wikitable"
|-
! Variablenname!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$FW_ME</code>'''

|| URL-Pfad unter dem der FHEMWEB-Server via HTTP erreichbar ist.

Bsp: <code>/fhem</code>
|-
| style="vertical-align:top" | '''<code>$FW_dir</code>'''

|| Das Basisverzeichnis auf dem lokalen Filesystem des FHEMWEB-Servers.

Bsp: <code>./www</code>
|-
| style="vertical-align:top" | '''<code>$FW_CSRF</code>'''

|| Enthält das aktuell gültige CSRF-Token als HTTP URL-Parameter für die aktuelle Verbindung oder bleibt leer.

Bsp: <code>&fwcsrf=csrf_165435377333711</code>
|-
| style="vertical-align:top" | '''<code>$FW_detail</code>'''

|| Enthält den Definitionsnamen der aktuell erzeugten Detailansicht.

Bsp: <code>Licht_Wohnzimmer</code>
|-
| style="vertical-align:top" | '''<code>$FW_room</code>'''

|| Enthält den Raumnamen der aktuell erzeugten Raumansicht.

Bsp: <code>Wohnzimmer</code>
|-
| style="vertical-align:top" | '''<code>$FW_wname</code>'''

|| Enthält den Definitionsnamen der aktuellen FHEMWEB-Instanz.

Bsp: <code>WEB</code>
|-
| style="vertical-align:top" | '''<code>$FW_cname</code>'''

|| Enthält den Definitionsnamen der aktuellen Verbindung (Connection-Name).

Bsp: <code>WEB_192.168.179.65_54406</code>
|-
| style="vertical-align:top" | '''<code>$FW_userAgent</code>'''

|| Enthält den User-Agent, welcher für den aktuellen Aufruf übermittelt wurde.

Bsp: <code>Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/63.0.3239.84 Safari/537.36</code>
|}

=== FW_makeImage ===

:<syntaxhighlight lang="perl">$html = FW_makeImage($icon, $text, $class);</syntaxhighlight>

FW_makeImage gibt HTML-Code zurück, der ein Icon aus dem dem FHEMWEB-Iconpool beschreibt.

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

''mandatory''
|| Eine Zeichenkette, mit optionaler Farbangabe <code>'<iconname>[@color>]'</code>
|-
| style="vertical-align:top" | '''<code>$text</code>'''

''optional''
|| Wenn hier ein Text angegeben wird und <code>$icon</code> auf eine SVG-Datei verweist, dann wird <code>$text</code> dem svg-HTML-Tag hinzugefügt. Das Resultat im HTML-Quelltext ist dann in der Art <code><svg class="$class" data-txt="$text" ... ></code>
Wenn hier ein Text angegeben wird und <code>$icon</code> auf eine Datei verweist die nicht auf ''.svg'' endet, dann wird der Pfad von der Datei hinter <code>$icon</code> als <code><img></code> eingebunden. Das Resultat im HTML-Quelltext ist dann in der Art <code><img ... src="..." alt=\"$text\" title=\"$text\"></code>
|-
| style="vertical-align:top" | '''<code>$class</code>'''

''optional''
|| Eine Zeichenkette, die eine CSS-Klasse angibt.
Wir der Parameter angegeben, wird dem <img> oder <svg> class="$class" hinzugefügt. Ist der Parameter <code>undef</code> oder nicht übergeben, so wird kein <code>class</code>-Attribut hinzugefügt.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$html</code>'''
|| Wenn '''<code>$icon</code>''' mit einem Iconnamen aus dem FHEMWEB-Iconpool übereinstimmt, wird der HTML-Code zum Einbinden des Icons zurückgegeben.
Mit nachgestellter Farbangabe <code>'<iconname@color>'</code>, wird das Icon entsprechend eingefärbt.
Entspricht die Zeichenkette keinem Iconnamen, wird die Zeichenkette zurückgegeben.
|}

Beispiel:
* <syntaxhighlight lang="perl">$html = FW_makeImage('fts_shutter_10@red');</syntaxhighlight>

=== FW_directNotify ===

:<syntaxhighlight lang="perl">FW_directNotify($filter, $fhemweb_instance, $javascript, "");</syntaxhighlight>

FW_directNotify führt Javascript auf einer longpoll FHEMWEB-Instanz aus, ohne Events zu erzeugen.

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

''optional''
|| Eine Zeichenkette, die mit "FILTER=" beginnt <code>"FILTER=<filter expression>"</code>.
|-
| style="vertical-align:top" | '''<code>$fhemweb_instance</code>'''

''mandatory''
|| Eine Zeichenkette, die eine longpoll FHEMWEB-Instanz <code>"#FHEMWEB:<FHEMWEB devicename>"</code> angibt.<br>
|-
| style="vertical-align:top" | '''<code>$javascript</code>'''

''mandatory''
|| Eine Zeichenkette, die ein Javascript angibt.
|-
| style="vertical-align:top" | '''<code>""</code>'''

''mandatory''
|| Eine Zeichenkette, leer oder (noch zu präzisieren).

|}

Beispiele:
* <syntaxhighlight lang="perl">FW_directNotify("FILTER=room=XXX", "#FHEMWEB:WEB", "FW_okDialog('Hello world!')", "");</syntaxhighlight>
* <syntaxhighlight lang="perl">FW_directNotify("FILTER=room=XXX", "#FHEMWEB:WEB", "location.reload('true')", "");</syntaxhighlight>
* siehe auch {{Link2Forum|Topic=48736|Message=404497|LinkText=Forenthread}}

== FHEMWEB-Client (pgm2) Javascript-Funktionen ==

=== Globale Variablen ===

Globale Variablen:
{| class="wikitable"
|-
! Variablenname!! Bedeutung
|-
| style="vertical-align:top" | '''<code>FW_root</code>'''

|| FHEM-Ursprungsverzeichnis, steht auch im head-Element als Attribut <code>root</code> zur Verfügung.
|-
| style="vertical-align:top" | '''<code>FW_version</code>'''

|| Ein assoziatives Array, das die Versionszeichenketten der geladenen Javascript-Dateien enthält.

|}

=== FW_cmd ===

:<syntaxhighlight lang="javascript">FW_cmd(arg, callback);</syntaxhighlight>

FW_cmd führt einen Befehl auf dem FHEMWEB-Server aus.

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

''mandatory''
|| Eine Zeichenkette, die einem Befehl an den Server entspricht.
|-
| style="vertical-align:top" | '''<code>callback</code>'''

''optional''
|| Eine Javascript-Funktion, die ausgeführt wird, wenn der auf dem FHEM-Server ausgeführte Befehl einen Rückgabewert enthält, der weiter verarbeitet werden soll.

|}

Beispiel:
* <syntaxhighlight lang="javascript">FW_cmd(FW_root+'?cmd={FW_makeImage("fts_shutter_10")}&XHR=1', function(data){FW_okDialog(data)});</syntaxhighlight> Das Beispiel holt sich vom Server den HTML-Code des Icon "fts_shutter_10" und zeigt das Icon in einem Popup-Fenster an. Der vom Server auszuführende Befehl lautet <syntaxhighlight lang="perl" inline>{FW_makeImage("fts_shutter_10")}</syntaxhighlight>. An die Callback-Funktion <syntaxhighlight lang="javascript" inline>function(data){FW_okDialog(data)}</syntaxhighlight> wird der Rückgabewert vom Server als Parameter übergeben und steht als Variable <code>data</code> zur Verfügung.

=== FW_errmsg ===

:<syntaxhighlight lang="javascript">FW_errmsg(text, timeout);</syntaxhighlight>

FW_errmsg zeigt eine Meldung im FHEMWEB-Client (Browser) an.

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

''mandatory''
|| Eine Zeichenkette, die angezeigt wird. HTML-Code wird interpretiert.
|-
| style="vertical-align:top" | '''<code>timeout</code>'''

''mandatory''
|| Anzeigedauer der Zeichenkette in Millisekunden.

|}

Beispiel:
* <syntaxhighlight lang="javascript">FW_errmsg('Hello world!',10000);</syntaxhighlight>

=== FW_okDialog ===

:<syntaxhighlight lang="javascript">FW_okDialog(txt, parent, removeFn);</syntaxhighlight>

FW_okDialog öffnet im FHEMWEB-Client (Browser) ein modales Popup-Fenster.

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

''mandatory''
|| Eine Zeichenkette, die im Popup-Fenster angezeigt wird. HTML-Code wird interpretiert.
|-
| style="vertical-align:top" | '''<code>parent</code>'''

''optional''
|| Ein Objekt zur Verankerung des Popup-Fensters, default ist das body-Element. Eine FHEM-Widget-Schnittstelle wird interpretiert.

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

''optional''
|| Eine Javascript-Funktion, die beim Schliessen des Popup-Fensters ausgeführt wird.

|}

Beispiel:
* <syntaxhighlight lang="javascript">FW_okDialog('Hello world!',10000);</syntaxhighlight>
* <syntaxhighlight lang="javascript"><a href="#!" onclick="FW_okDialog('Hello world!')">Hello</a></syntaxhighlight>

Soll das Popup-Fenster aus einem Hyperlink heraus aufgerufen werden, dann ist darauf zu achten, dass ein ungültiger Anchor Tag verwendet wird. In diesem Beispiel "!". Dadurch wird ein unkontrolliertes Scrollen der Webseite effektiv verhindert und der Dialog erscheint genau dort wo man ihn haben möchte.

=== loadScript ===

:<syntaxhighlight lang="javascript">loadScript(scriptname, callback, force);</syntaxhighlight>

loadScript läd im FHEMWEB-Client (Browser) ein Javascript nach.

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

''mandatory''
|| Eine Zeichenkette, die den Sriptnamen enthält.

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

''optional''
|| Eine Javascript-Funktion, die ausgeführt wird, wenn das Script geladen wurde.

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

''optional''
|| Ein Flag, wenn gesetzt, wird das Laden erzwungen.

|}

Beispiel:
* <syntaxhighlight lang="javascript">loadScript("pgm2/jquery.knob.min.js", function(){<Javascript-Code>});</syntaxhighlight>

=== log ===

:<syntaxhighlight lang="javascript">log(text);</syntaxhighlight>

log zeigt einen Logeintrag in der Konsole des Browsers an.

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

''mandatory''
|| Eine Zeichenkette, die angezeigt wird.

|}

Beispiel:
* <syntaxhighlight lang="javascript">log('Hello world!');</syntaxhighlight>

== Links ==

* [[DevelopmentFHEMWEB|Development FHEMWEB (englischsprachig)]]
* [[DevelopmentModuleAPI]]

[[Kategorie:Development]]

Icons

2025-03-23T17:55:37Z

Torxgewinde: Icons tauchen erst nach Neustart oder set WEB rereadicons auf

Icons - alles rund um die Icons in FHEM
= FHEM mit Icons verschönern =
== Geräten Icons zuweisen ==
Im [[FHEMWEB]] auf Detail-Ansicht des Gerätes gehen, danach in der attr Zeile per dropdown
# Icon auswählen, um das Icon zu wählen, das standardmäßig links vom Gerät gezeigt wird; alternativ ganz unten auf '''Select Icon''' klicken, dann bekommt ihr alle Bilder angezeigt
# '''[[devStateIcon]] auswählen''', um unterschiedliche Schaltzustände mit unterschiedlichen Icons zu versehen; alternativ ganz unten auf '''Extend devStateIcon''' klicken, dann bekommt ihr alle Bilder angezeigt und könnt sie dem jeweiligen Schaltzustand zuordnen.

Dabei gilt folgendes:
* Icon-Dateiname OHNE Dateiendung eingeben
* wenn es sich bei dem Icon um eine svg-Datei handelt, kann mit @farbe die Farbe beeinflusst werden, z.B. <br /> <code>attr Geraet devStateIcon an:general_an@green aus:general_aus@red</code>, <br /> wobei hier die beiden Dateien general_an.svg und general_aus.svg heißen.
* statt des Standardfarbnamens, kann übrigens auch der 6-stellige Hex-Code übergeben werden (ohne # am Anfang). Den Code könnt ihr z.B. hier bei [http://www.colorpicker.com Colorpicker] generieren
* Möchte man dass bei Klick auf das Icon auch eine Aktion ausgelöst wird, kann man dies als dritten Parameter mit angeben. Beispiel für einen Wechsel zwischen "around" und "away": <code>around:status_available:away away:status_away_2:around</code>.

Wenn ihr die Änderungen wie oben beschrieben durchführt, könnt ihr das Ergebnis gleich betrachten. Wenn alles passt, dann noch '''Save config''' drücken, dann wird alles fest abgespeichert.

== Größe der Icons verändern ==
Auch das kein Problem. Öffnet einfach die für Eurer Template (wie sieht fhem bei Euch aus: rechts unten -> Select Style -> das was ihr dort gewählt habt ist Euer Template) zuständige css-Datei. Diese findet ihr im fhem-Verzeichnis unter www/pgm2. Dort fügt ihr einfach folgende Zeile ein und ändert ggf. die Größenangaben.
<pre>svg { height:32px; width:32px; }</pre>

== Mehr Icons zur Auswahl ==
Grundsätzlich sind bei aktuellen fhem-Installationen die meisten Icons standardmäßig aktiviert. Navigiert doch einfach mal im fhem Verzeichnis in den www Ordner und dort in images. Die Ordner default, openautomation und fhemSVG sind standardmäßig aktiviert, d.h., Icons aus diesen Ordnern werden in fhem angezeigt. Wenn ihr zusätzlich die Icons auch aus den anderen Ordnern (z.B. icons_small) verwenden wollt, dann ergänzt einfach die entsprechende Zeile "WEB iconPath" in der fhem.cfg:
<pre>attr WEB iconPath fhemSVG:openautomation:default:icons_small</pre>

Das gleiche gilt, wenn ihr eine ältere fhem-Installation habt und noch nicht die Bilder z.B. aus fhemSVG angezeigt bekommt.

Damit neu hinzugefügte Icons erkannt werden ist es notwendig FHEM neuzustarten, oder dem FHEMWEB device einen Befehl zum einlesen der Icons zu senden:<syntaxhighlight lang="perl">
set WEB rereadicons
</syntaxhighlight>

=== Weitere Iconsätze ===

Im Ordner /contrib der FHEM-Installation oder des SVN befinden sich weitere Iconsätze in Form von SVG-Dateien.

* FontAwesome in IconFontAwesome.zip, s. [http://fontawesome.io/icons/ http://fontawesome.io/icons/]
* IcoMoon in IcoMoon.zip, s. [https://icomoon.io/#preview-free https://icomoon.io/#preview-free]

== Icons Farben zuweisen ==
Man kann Icons beliebige Farben zuweisen, indem man den Icon-Namen per "@" mit einem Farbnamen oder einer Farbcodierung versieht.
<pre>
rc_dot@red
rc_dot@#a1d490
</pre>
Hilfe zur Bestimmung der Farbcodierung kann man auf den folgenden Seiten finden:
* [http://www.colorpicker.com www.colorpicker.com]
* [http://www.html-color-names.com www.html-color-names.com]

== Weitere Tipps ==
Weitere Tipps zu Icons finden sich auch auf der Seite [[Slider für HM-Rolladensteuerung anzeigen]].

= Eigene Icons erstellen =
Falls ihr eigene Icons basteln wollt - sehr gerne. Umso besser, wenn ihr diese dann mit uns teilt. Der passende {{Link2Forum|Topic=12605|LinkText=Thread im Forum}}.

== SVG-Icons ==
Hier einige Tipps zum Erstellen von SVG-Icons. SVGs bieten einige Vorteile:
* SVGs sind vektorbasiert und somit frei skalierbar
* SVGs sind, wenn man sie genauer betrachtet, gut lesbarer und veränderbarer Quellcode und können deswegen leicht über css manipuliert werden

Wie geht es nun:
* [http://inkscape.org/download/?lang=de Inkscape] besorgen (Open Source)
* Loszeichnen

Jetzt wird es wichtig - fhem ist etwas sensibel, was svgs anbelangt und will diese zudem farblich umgestalten. Daher folgendes unbedingt beachten:

* fhem ersetzt bei allen fill:#000000 und fill="#000000" die sechs Nullen mit einem Farbcode, wenn dieser mit übergeben wurde (sh. FHEM mit Icons verschönern weiter oben) - das solltet ihr beim zeichnen beachten
* daher arbeite ich immer so, dass ich beispielsweise Rechtecke/Kreise zeichne und diese dann mit "Kontur in Pfad umwandeln" umwandle -> dann ist das Rechteck transparent, die Linie schwarz (und wird von fhem erstetzt) und alles klappt
* alle Texte müssen in Pfade umgewandelt werden
* das gesamte Bild muss als "Normales SVG" gespeichert werden (Standardeinstellung bei Inkscape ist "Inkscape SVG")
* Wenn die Grafik nicht angezeigt wird sondern nur Text: In einem Editor den Inhalt mit einer funktionierenden SVG-Datei vergleichen und anpassen.
* letzter wichtiger Tipp: Eine Zeile darf im SVG nicht fehlen, sonst zeigt fhem es nicht an. Wenn ihr Euer SVG in einem Texteditor öffnet (ich empfehle notepad++), schaut in in der <svg>-Definition, ob die Zeile mit viewBox dabei ist. Wenn nicht, dann nach unterem Format ergänzen.

<syntaxhighlight lang="XML">
<?xml version="1.0" encoding="UTF-8" standalone="no"?>

<svg
version="1.0"
width="585"
height="585"
viewBox="0 0 585 585"
id="svg2421"
sodipodi:docname="usb-stick.svg">
</syntaxhighlight>

== SVG-Icons für das Modul remotecontrol: Schriftvorlage ==
Wer beispielsweise für das Modul remotecontrol noch andere Beschriftungen braucht, der kann sich diese ganz fix selbst machen. Im Ordner fhem\www\images\fhemSVG findet ihr die Datei rc_templatebutton.svg. Mit der macht ihr folgendes:
Ganz einfach inkscape runterladen (http://inkscape.org/download/?lang=de), Datei öffnen, auf Text klicken, dann oben in der Leiste auf Text -> Schrift und Text -> Reiter Text, Text ändern. Ggf. Größe/Position anpassen, dann Pfad -> Objekt in Pfad umwandeln, dann Datei -> Speichern unter -> euer name und "Normales SVG" => FERTIG

[[Kategorie:HOWTOS]]

E-Mail senden

2025-02-28T06:31:31Z

Torxgewinde: Snippet für cUrl mit Feedback aus Forum verbessert für Nachrichten mit Zeilenumbrüchen

Um aus FHEM heraus E-Mails senden zu können, gibt es unterschiedliche Methoden, abhängig von der verwendeten Plattform.

Lange Zeit war <code>sendemail</code> sehr beliebt. Da aber die Homepage des Projekts nicht mehr online ist und Probleme nur noch via erhöhtem Supportaufwand gelöst werden, sollte diese Option als veraltet betrachtet werden.

Eine Liste mit ressourcensparenden E-Mails Clients findet man bei dem OpenWRT Projekt: https://openwrt.org/docs/guide-user/services/email/smtp.client

MSGMail ist ein FHEM eigenes Modul zum Versenden, die Einrichtung ist allerdings nicht gänzlich einfach. Anfängern sei die cURL Methode empfohlen.

=== MSGMail (Linux, Windows) ===
FHEM bringt ein eigenes Device zum Senden von E-Mails mit, welches in Perl implementiert ist: [https://fhem.de/commandref.html#MSGMail MSGMail, https://fhem.de/commandref.html#MSGMail]

=== cURL (Linux, Windows) ===
[https://curl.se/ cURL] kann auf praktisch [https://curl.se/download.html jedem Betriebssystem] genutzt werden, [https://curl.se/windows/ selbst unter Windows]. Es kann direkt mit einem SMTP Server E-Mails versenden und stellt damit eine moderne, portable und sichere Option zum Versenden von E-Mails dar.

In FHEM richtet man sich ein Device ein und passt die Details (<code>$emailTo, $emailFrom, $emailServer</code>) an. Das Programm cURL muss installiert sein (z.B. mit <code>apt install curl</code>, oder durch Herunterladen und Installieren von der [https://curl.se cURL-Webseite]).<syntaxhighlight lang="perl" line="1">
defmod sendMail dummy
attr sendMail readingList message password
attr sendMail setList message:textField-long password
attr sendMail userReadings state:message:[\s\S]* {\
my $emailTo = 'you@example.com';;\
my $emailFrom = 'fhem@example.org';;\
my $emailServer = 'mail.smtpserver.de';;\
\
# Passwort aus getKeyValue abrufen\
my ($err, $emailPass) = getKeyValue("${name}_password");;\
if ($err || !defined $emailPass) {\
return "Error retrieving password: $err";;\
}\
\
my $message = ReadingsVal($name, 'message', '???');;\
my $subject = "$name: FHEM Nachricht";;\
\
# Betreff extrahieren und aus der Nachricht entfernen\
if ($message =~ s/(?:Subject|Betreff)=["'](.*?)["']//) {\
$subject = $1;;\
}\
\
# Empfänger extrahieren und aus der Nachricht entfernen\
if ($message =~ s/(?:To|An)=["'](.*?)["']//) {\
$emailTo = $1;;\
}\
\
#Dateianhänge bestimmen\
my @attachments;;\
while ($message =~ s/(?:Attachment|Anhang)=["'](.*?)["']//) {\
my $file = $1;;\
return ">>$file<< not found, not sending email" unless (-e $file);;\
push (@attachments, $file);;\
}\
\
#der curl Befehl wird hier aufgebaut:\
my $cmd = "curl -m 19 --noproxy '*' --no-progress-meter --ssl-reqd smtps://$emailServer:465 ";;\
$cmd .= "--user '$emailFrom:$emailPass' --mail-from '$emailFrom' --mail-rcpt '$emailTo' ";;\
$cmd .= "--write-out 'Email sent with status %{http_code}\n' ";;\
$cmd .= "-H 'Subject: $subject' ";;\
$cmd .= "-H 'From: $emailFrom' ";;\
\
#multipart/alternative für Text und HTML EMail Body\
$cmd .= "-F '=(;;type=multipart/alternative' ";;\
\
# Leerzeichen und <br> bzw <br \> am Anfang entfernen:\
$message =~ s/^(\s|<br(?:[ \/]+)>)+//;;\
# Leerzeichen und <br> bzw <br \> am Ende entfernen:\
$message =~ s/(\s|<br(?:[ \/]+)>)+$//;;\
\
#Plaintext E-Mail Inhalt an cURL:\
$cmd .= "-F \"=$message;;type=text/plain;; charset=UTF-8\" ";;\
#ersetze \n bzw. \r\n durch ein HTML-tag <br />:\
$message =~ s/\r?\n/<br \/>/g;;\
\
#HTML E-Mail Inhalt an cURL:\
$cmd .= "-F '= <body>$message</body>;;type=text/html;; charset=UTF-8' ";;\
$cmd .= "-F '=)' ";;\
\
#jetzt alle Attachments (0..N) anhängen:\
foreach my $file (@attachments) {\
$cmd .= "-F '=@".$file.";;encoder=base64' ";;\
}\
\
#stderr auch mit in den output sammeln:\
$cmd .= " 2>&1";;\
\
#Blockierender Aufruf von cURL in dieser Funktion via BlockingCall:\
if (!defined &sendMailfunc1) {\
*sendMailfunc1 = sub ($) {\
my ($param) = @_;;\
my $result;;\
$result = qx/$param/;;\
$result = MIME::Base64::encode_base64($result);;\
$result =~ s/\n//g;;\
return $result;;\
}\
}\
\
#Rückgabe über diese Funktion,\
#anzeigen in dem reading dieses UserReadings:\
if (!defined &sendMailfunc2) {\
*sendMailfunc2 = sub ($) {\
my ($result) = @_;;\
my $hash = $defs{$name};;\
$result = MIME::Base64::decode_base64($result);;\
readingsSingleUpdate($hash, $reading, $result, 1);;\
}\
}\
\
#funktion falls BlockingCall abgebrochen wird:\
if (!defined &sendMailfunc3) {\
*sendMailfunc3 = sub ($) {\
my ($result) = @_;;\
my $hash = $defs{$name};;\
readingsSingleUpdate($hash, $reading, $result, 1);;\
}\
}\
\
BlockingCall("sendMailfunc1", $cmd, "sendMailfunc2", 20, "sendMailfunc3", "Error: timeout");;\
\
return "started cURL command...";;\
},\
state:password:.* {\
# Passwort speichern\
my $ret = setKeyValue("${name}_password", ReadingsVal($name, 'password', undef)) // "password stored";;\
\
#password wieder aus der Variablen rausnehmen, soll nicht sichtbar bleiben:\
#\
# Hinweis: das Password taucht beim Setzen hierüber im Event-Log auf!\
# Alternativ: { setKeyValue("sendMail_password", "geheimesPasswort") }\
readingsBulkUpdate($hash, "password", "****");;\
\
return "$ret";;\
}
</syntaxhighlight>Das Passwort setzt man mit:

* <code>set sendMail password geheimesPasswort</code>
* Alternativ, damit das Passwort nicht im Log auftaucht: <code>{ setKeyValue("sendMail_password", "geheimesPasswort") }</code>

E-Mails kann man dann Senden mit:

* <code>set sendMail message Mein Text</code> (es wird der Standardbetreff und Empfänger aus dem Snippet genutzt)
* <code>set sendMail message Betreff="Mein Betreff" Mein Text</code>(es wird der Empfänger aus dem Snippet genutzt)
* <code>set sendMail message Subject="Dies ist ein Test" Mein Text</code>
* <code>set sendMail message To="jemand@example.com" Mein Text</code>
* <code>set sendMail message An="jemand@example.com" Mein Text</code>
* <code>set sendMail message An="jemand@example.com" Betreff="Mein Betreff" Mein Text</code>
* <code>set sendMail message To="jemand@example.com" Subject="Mein Betreff" Mein Text</code>
* <code>set sendMail message Subject="✅ Dies ist ein Test" Meldung mit Emoji ⚽ geht auch</code>
* Eine Datei mit anhängen: <code>set sendMail message Subject="Dies ist ein Test" Anhang="www/images/fhemSVG/bag.svg" Mein Text</code>
* Zwei Dateien mit anhängen: <code>set sendMail message Subject="Dies ist ein Test" Anhang="./www/images/fhemSVG/bag.svg" Anhang="www/images/fhemSVG/batterie.svg" Mein Text</code>, für die anzuhängenden Dateien können relative und absolute Pfade verwendet werden. Beim Vorbereiten der E-Mail wird geprüft ob die Dateien existieren, da dies sonst eine typische Fehlerquelle ist. Es wird nichts versendet wenn eine Datei nicht gefunden werden kann.

==== Fehlersuche ====
Sollte cURL zwar installiert sein, aber keine E-Mails versenden, kann es sein, dass das Protokoll nicht einkompiliert wurde. Dies ist bei OpenWRT zum Beispiel der Fall.

So sollte es aussehen (hier ein Ubuntu), relevant ist für diese Nutzung das Protokoll smtp und smtps, das braucht man:<syntaxhighlight lang="bash">
curl -V
curl 8.5.0 (x86_64-pc-linux-gnu) libcurl/8.5.0 OpenSSL/3.0.13 zlib/1.3 brotli/1.1.0 zstd/1.5.5 libidn2/2.3.7 libpsl/0.21.2 (+libidn2/2.3.7) libssh/0.10.6/openssl/zlib nghttp2/1.59.0 librtmp/2.3 OpenLDAP/2.6.7
Release-Date: 2023-12-06, security patched: 8.5.0-2ubuntu10.6
Protocols: dict file ftp ftps gopher gophers http https imap imaps ldap ldaps mqtt pop3 pop3s rtmp rtsp scp sftp smb smbs smtp smtps telnet tftp
Features: alt-svc AsynchDNS brotli GSS-API HSTS HTTP2 HTTPS-proxy IDN IPv6 Kerberos Largefile libz NTLM PSL SPNEGO SSL threadsafe TLS-SRP UnixSockets zstd

</syntaxhighlight>So sollte es nicht aussehen (hier ein OpenWRT):<syntaxhighlight lang="bash">
curl: (1) Protocol "smtps" not supported

curl -V
curl 8.10.1 (arm-openwrt-linux-gnu) libcurl/8.10.1 mbedTLS/3.6.2 nghttp2/1.63.0
Release-Date: 2024-09-18
Protocols: file ftp ftps http https ipfs ipns mqtt
Features: alt-svc HSTS HTTP2 HTTPS-proxy IPv6 Largefile SSL threadsafe UnixSockets

</syntaxhighlight>Hat man nur ein cURL ohne das Protokoll, so muss man sich das Paket leider anderweitig beschaffen (chroot, selbst kompilieren, statisch gelinkte Version, ...).

==== Forumlink ====
https://forum.fhem.de/index.php?topic=140814.0

=== EXIM4 (Debian) ===
Eine Anleitung zum Versenden von E-Mails mit Exim ist als PDF verfügbar: [[Medium:Anleitung Exim4 Debian GMX.pdf|PDF]]

=== SSMTP (OpenWRT, embedded Distros) ===

==== Installation ====
<syntaxhighlight lang="bash">
opkg update
opkg install ssmtp_2.64-4_mpc85xx.ipk
</syntaxhighlight>Damit <code>ssmtp</code> funktioniert müssen die Dateien <code>/etc/ssmtp/ssmtp.conf</code> und <code>/etc/ssmtp/revaliases</code> angepasst werden.

/etc/ssmtp/ssmtp.conf
<syntaxhighlight lang="text">
root=arnold@gmx.net
mailhub=mail.gmx.net:465
rewriteDomain=gmx.net
hostname=gmx.net
FromLineOverride=YES
UseTLS=YES
#UseSTARTTLS=YES
AuthUser=arnold@gmx.net
AuthPass=Passwort_von_arnold@gmx.net
</syntaxhighlight>

/etc/ssmtp/revaliases
<syntaxhighlight lang="text">
root:arnold@gmx.net:mail.gmx.net:465
</syntaxhighlight>

In der [[99_myUtils_anlegen|99_myUtils]] folgende Unterroutine einfügen:

<syntaxhighlight lang="perl">
sub OpenWRTMail
{
my $rcpt = shift;
my $subject = shift;
my $text = shift;
my $ret = "";
my $sender = "dockstar\@heye-tammo.de";
Log 1, "sendEmail RCP: $rcpt, Subject: $subject, Text: $text";
$ret .= qx(echo -e 'to:$rcpt\n from:$sender\nsubject:$subject\n$text\n' | ssmtp $rcpt);
$ret =~ s,[\r\n]*,,g; # remove CR from return-string
Log 1, "sendEmail returned: $ret";
}
</syntaxhighlight>

=== PHP Mail Funktion (Synology DiskStation) ===
Beim DSM 3.2 funktioniert der <code>php-mail</code>-Befehl, so dass man mittels folgendem Modul E-Mails versenden kann:
<syntaxhighlight lang="perl">
sub sendmail($$$) {
my($empf, $subj, $nachricht) = @_;
system("php -r 'mail(\"$empf\",\"$subj\",\"$nachricht\");'");
}
</syntaxhighlight>

=== Sendemail (Veraltet, Debian-basierende Distros) ===
Es handelt sich um ein Perl Programm, dass man aus den Paketquellen installieren kann.

Es gibt Probleme:

* mit der TLS bzw STARTTLS Verschlüsselung (https://github.com/fhem/fhem-docker/issues/254, https://www.mail-archive.com/debian-bugs-dist@lists.debian.org/msg1915977.html) ,
* Mit der Webseite des Projekts (https://web.archive.org/web/20190906140125/http://caspian.dotconf.net/menu/Software/SendEmail); diese ist nicht mehr verfügbar und nur eine archivierte Kopie kann eingesehen werden,

weswegen diese Lösung als technisch überholt gelten sollte. Will man trotzdem <code>sendemail</code> verwenden folgenden hier die Informationen dazu:

Auf dem Server muss <code>sendemail</code> installiert werden:<syntaxhighlight lang="bash" line="1">
sudo apt-get update
sudo apt-get install sendemail libio-socket-ssl-perl libnet-ssleay-perl perl
</syntaxhighlight>Man kann die korrekte Funktion im Terminal (ohne <code>{qx()}</code> ) oder auch in der FHEM Kommandozeile testen (Hinweis: manche Provider (z.B. gmail) lassen diesen Zugang erst nach Freischaltung zu!).

''Bei Gmail muss seit dem 30.6.2022 ein separates Passwort erzeugt werden, die alte Einstellung über "Zugriff durch weniger sichere Apps" funktioniert nicht mehr. Siehe Support Seite Google: <nowiki>https://support.google.com/accounts/answer/185833</nowiki>''

''Beispiel mit Gmail über Linux Terminalfenster:''
sendemail -f 'Der.Absender@gmail.com' -t 'Der.Empfaenger@gmail.com' -u 'subject' -m 'text' -a <nowiki>''</nowiki> -s 'smtp.gmail.com:587' -xu 'Der.Absender' -xp DASSUPERGEHEIMEPASSW0RT
In der [[99 myUtils anlegen|99_myUtils]] folgende Unterroutine einfügen:<syntaxhighlight lang="perl" line="1">
######## DebianMail Mail auf dem RPi versenden ############
# $provider für SMTP Server anpassen.
# Einmal in der FHEM Kommandozeile, user und password anpassen:
# {setKeyValue("myEmailKonto",'user@domain');;setKeyValue("myEmailPasswrd",'password')}
sub DebianMail
{
my $rcpt = shift;
my $subject = shift;
my $text = shift;
my $attach = shift;
my $ret = "";
my $error;
my $konto = getKeyValue("myEmailKonto");
my $passwrd = getKeyValue("myEmailPasswrd");
my $from = $konto; # or use different KeyValue if konto is not the from email address
my $provider = "smtp.1und1.de"; # smtp.domain.tld:port see provider documentation
#Log 1, "sendEmail RCP: $rcpt";
#Log 1, "sendEmail Subject: $subject";
#Log 1, "sendEmail Text: $text";
#Log 1, "sendEmail Anhang: $attach";
if (not defined($attach)){$attach=''}
$ret .= qx(sendemail -f '$from' -t '$rcpt' -u '$subject' -m '$text' -a $attach -s '$provider' -xu '$konto' -xp '$passwrd' -o tls=auto -o message-charset=utf-8);
$ret =~ s,[\r\n]*,,g; # remove CR from return-string
Log 1, "sendemail returned: $ret";
}
###############################################################################
</syntaxhighlight>

Die Zugangsdaten für den Email-Account müssen dabei FHEM-intern gespeichert werden. Dazu gibt man einmalig über die Kommandozeile folgendes ein (user@domain und password müssen auf den Email Account geändert werden):

: <code>{setKeyValue("myEmailKonto",'user@domain');;setKeyValue("myEmailPasswrd",'password')}</code>

Um die TLS Verschlüsselung (ehem. SSL) nicht zu nutzen, muss in der viertletzten Zeile tls=no verwendet und der Port des Mailproviders auf 25 eigetragen werden. Sollte anschließend keine Mail verschickt werden, siehe Probleme.

Falls der Body-Text in einem (Android-)Mailer auf dem Handy nicht gezeigt wird, kann der Parameter '''-o message-content-type=html''' helfen.

Die Funktion kann beispielsweise folgendermaßen aufgerufen werden:<syntaxhighlight lang="perl">
{qx(sendemail -f 'Ab\@send.er' -t 'Emp\@faeng.er' -u 'subject' -m 'text' -a 'DateinameOderLeer' -s 'smtpFQDN:port' -xu 'MailUser' -xp 'PasswortOhneKlammeraffen')}
</syntaxhighlight>Bei allen Feldern können generell doppelte " oder einfache ' Anführungszeichen verwendet werden. Innerhalb von "" müssen Sonderzeichen wie @ aber maskiert werden, da sie sonst als Steuerzeichen interpretiert werden:

: <code>"email\@email.domain" oder 'email@email.domain'</code>

Direkt in der FHEM Kommandozeile (ohne Anhang)

: <code>{DebianMail("email\@email.domain","Subject","Text")}</code>

Die ordnungsgemäße Ausführung wird mit 71 quittiert.

Beispiele mehrere Anhänge (Es ist wichtig Dateinamen mit Leerzeichen in separate Anführungszeichen zu setzen)
{DebianMail("email\@email.domain","Subject","Text","Anhang1 Anhang2 Anhang3")}
{DebianMail('email@email.domain','Subject','Text',"'with spaces Anhang1' 'with spaces Anhang2'")}
oder (mehr als einen Empfänger, diese können durch Leerzeichen, Semikolon oder Komma getrennt sein)
define Sonstiges at *01:00:00 {\
DebianMail('email@email.domain,email2@email.domain',"Subject","Text","'Anhang1' 'Anhang2' ...");;\
}

Die archivierte Doku zu <code>sendemail</code> befindet sich in der Änderungshistorie: https://wiki.fhem.de/w/index.php?title=E-Mail_senden&oldid=37524
[[Kategorie:E-Mail]]