FHEMWiki - Benutzerbeiträge [de]

HM-WDS10-TH-O Funk-Temperatur-/Feuchtesensor außen (OTH)

2024-01-14T17:04:52Z

Kaihs: Links aktualisiert

{{Infobox Hardware
|Bild=PlatzHalter.png
|Bildbeschreibung=Bild und Daten müssen noch ergänzt werden
|HWProtocol=[[HomeMatic]]
|HWType=[[HomeMatic Type THSensor|THSensor]]
|HWCategory=[[:Kategorie:Temperatursensoren|Temperatursensoren]] [[:Kategorie:Feuchtesensoren|Feuchtesensoren]]
|HWComm=868,3 MHz
|HWChannels=
|HWVoltage=3 V
|HWPowerConsumption=max. 100 mA
|HWPoweredBy=2x LR6/Mignon/AA
|HWSize=54x135x73 mm (BxHxT)
|HWDeviceFHEM=[[CUL_HM]]

|HWManufacturer=[http://www.elv.de ELV] / [http://www.eq-3.de eQ-3]
}}
'''HM-WDS10-TH-O Funk-Temperatur-/Feuchtesensor außen (OTH)'''

Homematic Außensensor für Temperatur und relative Luftfeuchte.
== Features ==
* Batteriebetrieb (2 x AA)
* Möglichkeit der Wandmontage
* Eignung für Temp. von -19,9 °C bis +79,9 °C
* Datenübermittlung alle 120 bis 180 Sekunden
* Übermittlung des Batteriestatus
== Hinweise zum Betrieb mit FHEM ==
Das Handling des Gerätes ist identisch mit der entsprechenden [[HM-WDS40-TH-I Funk-Temperatur-/Feuchtesensor innen (IT)|Innensensor]]-Version.
== Variablen ==
Das Handling des Gerätes ist identisch mit der entsprechenden [[HM-WDS40-TH-I Funk-Temperatur-/Feuchtesensor innen (IT)|Innensensor]]-Version.
== Bekannte Probleme ==
* {{Link2Forum|Area= |Topic=10445|Message= |LinkText=FHEM:Temperaturwerte mit HM-WDS10-TH-O}}
* [http://www.elv.de/homematic-hm-wds10-th-o-funk-temperatur-luftfeuchtesensor-oth.html www.elv.de] unter ''Bewertungen'', 2 Sterne => Kontakt zur Technik erwünscht.
* Bei schwachen Batterien (reading "battery" = "low") werden z.T. völlig falsche Werte geliefert.

Bessere Batterien ''können'' evtl. helfen:
* [http://homematic-forum.de/forum/viewtopic.php?f=27&t=8230 homematic-forum]
* [http://www.ip-symcon.de/forum/threads/17198-HM-WDS10-TH-O-Temperatur-Sensor-h%C3%A4ngt-ab-8-grad www.ip-symcon.de]

== Links ==
* [https://www.eq-3.de/downloads/download/homematic/bda/hm-wds10-th-o_um_ge_eq-3_web.pdf Montage und Bedienungsanleitung] (PDF)
* [https://www.eq-3.de/downloads/download/homematic/pdb/funk-temperatur-luftfeuchtesensor-auen_76923_produktdatenblatt_v32.pdf Produktdatenblatt] (PDF)

[[Kategorie:HomeMatic Components]]
[[Kategorie:Feuchtesensoren]]
[[Kategorie:Temperatursensoren]]
[[Kategorie:868MHz]]

WMBUS

2021-11-10T19:19:27Z

Kaihs: /* Links */

{{Infobox Modul
|ModPurpose=Dekodierung von Wireless M-Bus Nachrichten
|ModType=d
|ModForumArea=Sonstige Systeme
|ModTechName=36_WMBUS.pm
|ModOwner=kaihs
}}
[[WMBUS]] ist ein Modul zur Dekodierung von Wireless M-Bus Nachrichten. Solche Nachrichten werden z. B. von Zählern für Wasser, Wärme, Gas und Elektrizität ausgestrahlt.
Wireless M-Bus ist ein Standardprotokoll das von unterschiedlichen Herstellern unterstützt wird.
Das Protokoll unterstützt unterschiedliche Kodierungen des Funksignals, im wesentlichen den S-Mode, T-Mode und C-Mode. Der Empfänger (z. B. ein CUL) muss den selben Modus nutzen wie der Sender (der Zähler).
Wireless M-Bus unterstützt optional die Verschlüsselung der Daten.
Die von einem Zähler gesendeten Daten können sehr unterschiedlich sein und hängen u. a. vom Zählertyp und dessen Hersteller ab.

== Voraussetzungen ==
Das Modul interpretiert nur die Nachrichten die von einen geeigneten Empfänger empfangen werden. Aktuell kann ein [[CUL]] und verwandte Geräte die die culfw[http://culfw.de/culfw.html] verwenden sowie ein Amber Wireless AMB8465M dafür verwendet werden. In der culfw muss die Unterstützung des WMBUS-Protokolls aktiviert sein (#define HAS_MBUS in der Datei board.h des Deviceverzeichnisses). Bei einem CUL mit der Hardwareversion V4 ist das nicht der Fall.

Der CUL muss in FHEM mittels Attribut rfmode=WMBus_S, WMBus_T oder WMBus_C in den zum Zähler passenden Empfangsmodus versetzt werden.

== Anwendung ==
Die Erzeugung des passenden Devices in FHEM geschieht automatisch beim Empfang des ersten Datenpakets eines Zählers. Voraussetzung dafür ist, dass [[autocreate]] aktiv ist.
Alternativ kann ein Device manuell angelegt werden. Dazu wird der Hersteller, die Seriennummer, die Version und der Typ (Wasser, Gas, ...) des Zählers benötigt.
Sind die Daten verschlüsselt wird auch noch der passende Schlüssel benötigt um die Daten entschlüsseln zu können.

== Verschlüsselung ==
Die Daten können auf drei verschiedene Arten verschlüsselt sein:
# Security profile A/Symmetric encryption with Mode 5
# Security profile B/Advanced symmetric encryption with Mode 7
# Security profile C/Asymmetric encryption with Mode 13

Das Modul unterstützt aktuell Daten die per 1 oder 2 verschlüsselt wurden.

== Anwendungsbeispiele ==
Ein per [[EnergyCam]] abgelesener Elektrizitätszähler sieht in FHEM z. B. so aus:
<pre>
Internals:
CUL_MBUS_MSGCNT 29
CUL_MBUS_RAWMSG b1944C4189985051701028A7D7A540000A00405FAD4080002FD08222C1295B8::-67.5
CUL_MBUS_RSSI -67.5
CUL_MBUS_TIME 2014-10-24 22:57:53
DEF FFD 17058599 1 2
DeviceMedium Electricity
DeviceType 2
IODev CUL_MBUS
IdentNumber 17058599
LASTInputDev CUL_MBUS
MSGCNT 29
Manufacturer FFD
NAME WMBUS_FFD_17058599_1_2
NR 49
STATE no errors
TYPE WMBUS
Version 1
addr FFD_17058599_1_2
Readings:
2014-10-24 22:57:53 1_storage_no 0
2014-10-24 22:57:53 1_type VIF_ENERGY_WATT
2014-10-24 22:57:53 1_unit Wh
2014-10-24 22:57:53 1_value 57881000
2014-10-24 22:57:53 2_storage_no 0
2014-10-24 22:57:53 2_type VIF_ACCESS_NO
2014-10-24 22:57:53 2_unit
2014-10-24 22:57:53 2_value 11298
2014-10-24 22:57:53 LQI 184
2014-10-24 22:57:53 RSSI -67.5
2014-10-24 22:57:53 battery ok
2014-10-24 22:57:53 decryption_ok 1
2014-10-24 22:57:53 energy 57881
2014-10-24 22:57:53 is_encrypted 0
2014-10-24 22:57:53 state no errors
2014-10-24 22:57:53 unit kWh
Attributes:
IODev CUL_MBUS
room WMBUS
</pre>

== Bekannte Probleme ==
=== Inkompatible Zähler ===
Obwohl Wireless M-Bus ein standardisiertes Protokoll ist, scheint sich kaum ein Hersteller vollständig daran zu halten bzw. verwendet sog. herstellerspezifische Felder um wichtige Daten zu verpacken.
Aus den bisher beobachteten Datenpaketen ergibt sich
* Qundis (Herstellerkürzel LSE) verwendet herstellerspezifische Datenblöcke für den eigentlichen Zählerstand
* Techem und Hydrometer verwenden ein undokumentiertes Datenformat (CI-Field A2)
:''(Techem Heizkostenverteiler (CI-Field A0) können über das Modul [[TechemHKV]] ausgewertet werden)''
* RWE SmartHome Powercontrol[http://www.rwe-smarthome.de/web/cms/de/1776202/smarthome/informieren/geraete/power-control/] sendet verschlüsselt und der Hersteller gibt nicht den vollständigen Schlüssel an ({{Link2Forum|Topic=24517|Message=315949}})

Daher werden bisher erst die [[EnergyCam]] der Firma Q-loud, Zähler von Easymeter und der Kamstrup Multical 21 vollständig unterstützt.
Für den Multical 21 muss eine culfw mit Unterstützung für WMBUS C verwendet werden. Diese ist in der culfw ab dem 24.6.2018 enthalten.

Andere Zähler können auch ohne Probleme funktionieren wenn diese sich an den OMS Standard halten.

=== Empfangsprobleme ===
Der Empfänger (meist ein [[CUL]]) muss das WMBUS Protokoll unterstützen. Die Unterstützung ist vorhanden, wenn in der Ausgabe von <code>get cmds</code> ein kleines [http://culfw.de/commandref.html#cmd_b b] enthalten ist.
Der CUL speichert die empfangenen Daten intern zwischen bevor sie an fhem geschickt werden. Der Puffer für die Speicherung muss groß genug sein, um ein komplettes Datenpaket aufzunehmen. Die Größe des Puffers kann in der culfw eingestellt werden in dem das define TTY_BUFSIZE in der Datei [https://sourceforge.net/p/culfw/code/HEAD/tree/trunk/culfw/Devices/nanoCUL/board.h board.h] des passenden Devices angepasst wird.
Dabei ist darauf zu achten, dass die verwendeten Mikrocontroller nur sehr wenig RAM haben (0,5-4KB). Um mehr freies RAM zu erhalten sollten Protokolle die nicht benötigt in der board.h abgeschaltet werden. Die Unterstützung für WMBUS (#define HAS_MBUS 1) muss aber natürlich eingeschaltet werden.
Anschließend ist die culfw [[Selbstbau_CUL#Software|neu zu übersetzen und zu flashen]].

== Links ==
* Forumsthread {{Link2Forum|Topic=24517}}
* Protokoll Beschreibung [https://oms-group.org/open-metering-system/oms-spezifikation]
* Beschreibung des M-BUS Protokolls [https://m-bus.com/documentation]
[[Kategorie:Energieverbrauchsmessung]]

FHEM mit HTTPS SSL-Zertifikat und eine eigene Zertifizierungsstelle

2021-05-08T21:59:28Z

Kaihs: nicht mehr funktionierenden Link ersetzt

== Vorwort ==
=== Dein Anliegen ===
Du möchtest FHEM mit HTTPS betreiben, hasst es aber, ständig von Deinem Browser darauf aufmerksam gemacht zu werden, dass dies "keine sichere Verbindung" ist.
Oder Du möchtest einen weiteren Serverdienst aufsetzen, welcher verschlüsselte SSL oder TLS-Verbindungen anbietet (z.B. HTTPS, POP3S, IMAPS, LDAPS, SMTP mit TLS).

=== Die Schwierigkeit dabei ===
Um eine mit SSL/TLS abgesicherte Verbindung anzubieten, benötigst Du ein Serverzertifikat. Dieses muss von einer Zertifizierungsstelle (Certification Authority oder kurz CA) signiert sein.
Ein offizielles Serverzertifikat, welches von einer offiziellen Stelle signiert ist, ist leider nicht kostenlos. Meist werden jährliche Gebühren in Höhe von mehreren hundert Euro fällig.

=== Eine mögliche Lösung ===
Unter Linux kann man mit Bordmitteln eine eigene CA aufsetzen und selbst ein Zertifikate erstellen und signieren. Das ist ein Vorgang von wenigen Minuten. Alle Einzelheiten beschreibt dieser Artikel.
Der einzige Unterschied zu einem von einer anerkannten Stelle signierten Zertifikat ist, dass der Client (Emailprogramm, Browser, etc.) einmalig das root CA importieren muß.

== Genaues Vorgehen ==
=== OpenSSL installieren ===
Für die Verwaltung der Zertifikate und im übrigen auch für die Verschlüsselung der Verbindungen mit SSL und TLS kommt unter Linux fast immer OpenSSL zum Einsatz. Wahrscheinlich ist das auf Deinem Sytem deshalb bereits installiert, wenn nicht, musst Du das Paket openssl nachinstallieren. Du benötigst aus diesem Paket den Kommandozeilenbefehl openssl.

=== Erstellen der CA ===
Lege zunächst ein Verzeichnis an, in dem Du das Zertifikat ablegen willst. Wir nehmen in unserem Beispiel /root/ca:
<source lang="bash">
root@linux# mkdir /root/ca
root@linux# cd /root/ca</source>
Die Gültigkeit setzen wir mit 10 Jahren bewusst sehr hoch an. Läuft die CA aus, so werden nämlich auch alle damit signierten Serverzertifikate ungültig. Die CA enthält einen geheimen Schlüssel, welcher automatisch erzeugt und in der Datei cakey.pem abgelegt wird. Das CA-Zertifikat wird nach cacert.pem geschrieben. Der folgende Befehl erzeugt das einen Schlüssel für das Zertifikat mit einer Länge von 2048 Bit:
<source lang="bash">
root@linux# openssl req -new -x509 -newkey rsa:2048 -keyout cakey.pem -out cacert.pem -days 3650
Generating a 2048 bit RSA private key
..............................................................
..............................................................
.........................................+++
......................................+++
writing new private key to 'cakey.pem'</source>

Wer den geheimen Schlüssel der CA kennt, kann damit beliebige Serverzertifikate signieren. Deshalb wird diese Schlüsseldatei nicht im Klartext auf der Festplatte abgelegt, sondern mit einer Passphrase verschlüsselt. Diese Passphrase benötigst Du immer dann, wenn Du mit der CA neue Zertifikate ausstellen willst:
<nowiki>
Enter PEM pass phrase: sehrlangesgeheimespasswort
Verifying - Enter PEM pass phrase: sehrlangesgeheimespasswort</nowiki>
Nun werden wir gebeten, Daten einzugeben, welche die CA identifizieren. Diese werden dem Client angezeigt, wenn er aufgefordert wird, das Zertifikat zu akzeptieren oder abzulehnen. Der Code für Deutschland ist DE. Wenn Du ein Feld leer lassen möchtest, so gib einen Punkt ein. Ansonsten wird der in eckigen Klammern stehende Defaultwert eingetragen:
<nowiki>
-----
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]: DE
State or Province Name (full name) [Some-State]:Brandenburg
Locality Name (eg, city) []:Potsdam
Organization Name (eg, company) [Internet Widgits Pty Ltd]:Familie AG
Organizational Unit Name (eg, section) []:EDV</nowiki>
Das Feld Common Name (CN) ist hier der offizielle Name der Zertifizierungsstelle. Für Dein eigenes CA kannst Du einfach Deinen eigenen Namen eintragen:
<nowiki>
Common Name (eg, YOUR name) []: Cool Tux
Email Address []: cooltux@gmail.tada</nowiki>
Fertig. Folgende zwei Dateien sind entstanden:
<nowiki>
root@linux# ll
insgesamt 9
drwxr-xr-x 2 root root 112 2006-04-30 12:08 .
drwx------ 12 root root 600 2006-04-30 11:54 ..
-rw-r--r-- 1 root root 1212 2006-04-30 12:08 cacert.pem
-rw-r--r-- 1 root root 963 2006-04-30 12:08 cakey.pem</nowiki>
Vorsichtshalber solltest Du die Rechte so setzen, dass die Schlüsseldatei nur für root lesbar ist:
<nowiki>
root@linux# chmod 600 cakey.pem</nowiki>
Du kannst nun ausprobieren, ob Du den Schlüssel mit der Passphrase wieder öffnen kannst:
<nowiki>
root@linux# openssl rsa -in cakey.pem -noout -text
Enter pass phrase for cakey.pem: wrzlprmpft
Private-Key: (1024 bit)
modulus:
00:d5:a5:37:51:e9:d9:fa:e3:97:e7:46:b2:88:1a:
b5:46:80:47:76:14:ae:2b:8b:3e:35:5c:ab:15:84:
53:d9:63:2e:7f:08:4b:ec:77:db:02:45:f8:c7:46:
58:cd:2d:f9:29:4d:96:3d:d8:6c:5d:9f:79:8a:04:
cf:b7:3a:89:da:a9:63:9f:44:b3:83:cf:0d:70:7d:</nowiki>
usw...

=== Schlüssel für das Serverzertifikat erzeugen ===
Nachdem wir nun eine eigene CA haben, kann diese nun endlich für unseren Server ein Zertifikat herausgeben. Dazu erzeugen wir zunächst einen 2048 Bit langen RSA Schlüssel, der mit AES 128 verschlüsselt auf der Platte abgelegt wird (ja wirklich, auch hier wieder ein verschlüsselter Schlüssel). Die Passphrase muss diesmal nicht sonderlich geheim sein, da wir sie ohnehin im Anschluss wieder entfernen werden. OpenSSL lässt allerdings keine leere Phrase zu:
<source lang="bash">
root@linux# openssl genrsa -out serverkey.pem -aes128 2048
Generating RSA private key, 2048 bit long modulus
....+++
.......................................+++
e is 65537 (0x10001)
Enter pass phrase for serverkey.pem: test
Verifying - Enter pass phrase for serverkey.pem: test</source>
So. Nun entfernen wir die Passphrase wieder. Warum? Der Serverdienst (Apache, Cyrus, etc.) muss schließlich in der Lage sein, den Schlüssel ohne Dein Zutun zu lesen. Oder möchtest Du bei jedem Booten des Servers ein Passwort eingeben müssen?
<source lang="bash">
root@linux# openssl rsa -in serverkey.pem -out serverkey.pem
Enter pass phrase for serverkey.pem: jaja
writing RSA key</source>

=== Certificate Signing Request erzeugen ===
Der nächste Schritt zum eigenen Zertifikat ist ein CSR. Dies muss dann nur noch von der CA signiert werden. Hier sind wieder Angaben analog zum Erstellen der CA nötig, was oft Verwirrung stiftet. Die allgemeinen Daten kann man ggfl. gleich wie oben eingeben:
<source lang="bash">
root@linux# openssl req -new -key serverkey.pem -out req.pem -nodes
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]: DE
State or Province Name (full name) [Some-State]:Brandenburg
Locality Name (eg, city) []:Potsdam
Organization Name (eg, company) [Internet Widgits Pty Ltd]:Familie AG
Organizational Unit Name (eg, section) []:EDV</source>
ACHTUNG, jetzt kommt das Wichtige: Beim Serverzertifikat ist der Common Name von entscheidender Bedeutung. Hier muss der DNS-Name stehen, unter dem der Client den Server anspricht! Wird das Zertifikat für eine HTTPS-Verbindung zu fhem.local verwendet, so muss der Common Name eben genau fhem.local heißen. Anderfalls wird der Browser das Zertifikat nicht akzeptieren, da er davon ausgehen muss, auf dem falschen Server gelandet zu sein.
<nowiki>
Common Name (eg, YOUR name) []: fhem.local
Email Address []: admin.fhem.local</nowiki>
Weitere Optionen kann man einfach leer lassen:
<nowiki>
A challenge password []:
An optional company name []:</nowiki>
Mittlerweile tummeln sich schon vier Dateien in unserem Verzeichnis:
<source lang="bash">
root@linux# ll
insgesamt 17
drwxr-xr-x 2 root root 168 2006-04-30 12:29 .
drwx------ 12 root root 600 2006-04-30 11:54 ..
-rw-r--r-- 1 root root 1212 2006-04-30 12:08 cacert.pem
-rw------- 1 root root 963 2006-04-30 12:08 cakey.pem
-rw-r--r-- 1 root root 1017 2006-04-30 12:29 req.pem
-rw-r--r-- 1 root root 1679 2006-04-30 12:21 serverkey.pem</source>

=== OpenSSL-Konfiguration anpassen ===
Leider kann man bei OpenSSL nicht alle Daten als Kommandozeilenargumente übergeben. Einige Einstellungen muss man lästigerweise in der Datei /etc/ssl/openssl.cnf ändern, bevor man signieren kann. Öffne diese Datei und passe folgende Zeilen in der Sektion [ CA_default ] an:
<source lang="bash">
/etc/ssl/openssl.cnf:
dir = . # Where everything is kept
new_certs_dir = $dir # default place for new certs
private_key = $dir/cakey.pem # The private key
RANDFILE = $dir/.rand # private random number file
default_days = 3650 # how long to certify for</source>
Das Feld default_days ist auf 365 Tage voreingestellt und gibt die Gültigkeit des Zertifikates an. Abgelaufene Zertifikate sind im Übrigen ein sehr häufiges Problem. Wenn es soweit ist, kennt sich damit nämlich schon lange keiner mehr aus. Deswegen kannst Du wie im Beispiel angegeben die Lebensdauer z.B. auf 10 Jahre heraufsetzen.

Nun muss man noch einige Dateien anlegen:
<source lang="bash">
root@linux# echo 01 > serial
root@linux# touch index.txt</source>

=== Serverzertifikat signieren ===
Kommen wir zum feierlichen Abschluss: Unsere CA signiert nun das Zertifikat:
<source lang="bash">
root@linux# openssl ca -in req.pem -notext -out servercert.pem
Enter pass phrase for ./cakey.pem: langesgeheimespasswort

...

Certificate is to be certified until Apr 27 10:45:36 2016 GMT (3650 days)
Sign the certificate? [y/n]: y

1 out of 1 certificate requests certified, commit? [y/n] y
Write out database with 1 new entries
Data Base Updated</source>

=== Zertifikate installieren ===
Wie Du das Zertifikat in FHEM installierst, findest Du [[Raspberry_Pi_%26_HTTPS|hier]] und wenn Du ein Server Zertifikat für NGINX installieren möchtest, findest Du Infos dazu [[HTTPS-Absicherung_%26_Authentifizierung_via_nginx_Webserver|hier]]

== Nachwort ==
=== Einbinden der root CA in die Zertifizierungsstelle des Browsers ===
Beim Firefox importieren wir unsere cacert.pem unter Einstellungen -> Erweitert -> Zertifikate -> Zertifikate anzeigen -> Zertifizierungsstellen ein.
Unter Chrome/Chromium finden wir die Zertifikatsverwaltung unter Einstellungen -> Erweitert -> Zertifikate verwalten HTTPS/SSL-Zertifikate und -Einstellungen verwalten -> Zertifizierungsstellen

=== Bekannte Probleme ===
Für den Chrome/Chromium müssen wir zusätzlich "Subject Alternative Names (SAN)" in unser Zertifikat eintragen. Dies geschieht beim Serverzertifikat signieren. Dazu müssen wir uns eine weitere Datei anlegen:
<source lang="bash">
root@linux# vim oats.extensions.cnf

basicConstraints=CA:FALSE
subjectAltName=@my_subject_alt_names
subjectKeyIdentifier = hash

[ my_subject_alt_names ]
DNS.1 = fhem01.tuxnet.local
DNS.2 = fhem02.tuxnet.local
DNS.3 = fhem01-vpn.tuxnet.local</source>

Dabei die DNS.x Namen durch die DNS Namen (bzw. IP Addressen) ersetzen, womit man Fhem aufruft.

Die Signierung unseres Serverzertifikates erfolgt dann mit folgendem Befehl:
<source lang="bash">
openssl ca -in req.pem -notext -extfile oats.extensions.cnf -out servercert.pem</source>

=== Prüfen von Zertifikaten ===
Zertifikate kann man im übrigen auf dieser [https://tools.keycdn.com/ssl| Seite] prüfen lassen.
Dazu kopiert man den Inhalt der servercert.pem in das Eingabefeld der Seite und klickt dann auf Check.

[[Kategorie:HOWTOS]]

SIGNALduino

2021-01-02T14:38:33Z

Kaihs: Wortwahl

{{Infobox Modul
|ModPurpose=Empfang und Verarbeitung von digitalen Signalen
|ModType=d
|ModFTopic=38402
|ModCmdRef=SIGNALduino
|ModForumArea=Sonstige Systeme
|ModTechName=00_SIGNALduino.pm
|ModOwner=Sidey ({{Link2FU|8018|Forum}}/[[Benutzer Diskussion:Sidey|Wiki]])
}}

== Einleitung ==
=== Übersicht ===
Unter den Namen SIGNALduino versteht man sowohl den Low-Cost Empfänger für digitale Signale (vergleichbar dem [[CUL]]) als auch das gleichnamige Modul mit dem Dateinamen 00_SIGNALduino.pm. Mit dem SIGNALduino kann man entweder 433 oder 868 MHz-Geräte auslesen und ansprechen. Der SIGNALduino funktioniert auch mit anderen Medien wie Infrarot oder direkter Kabelverbindung.

Der SIGNALduino(-Stick) erkennt Signale anhand von Mustern und gibt sie (als maximal detaillierte Beschreibung einer Signalabfolge) dann schlicht sofort nur noch an FHEM zur Auswertung (Dekodierung) weiter. Auch nicht erkannte Signale werden an FHEM übergeben.
Aufgabe des SIGNALduino (Firmware/Stick) ist es also nur, Signal-Aktivitäten zu erfassen und maximal präzise (als kurzer Text-String) zu beschreiben.
Alles weitere (echte, finale Auswertung / Zuweisung dieser Signal-Daten) wird dann auf einer großen Box (Raspberry o.ä.) gemacht.

=== Vorteil gegenüber einem CUL/FHEMduino ===
Der SIGNALduino hat den Vorteil einer sehr schnellen Demodulation des Funksignals. Sollen weitere Protokolle dekodiert werden, so muss dazu nur ein passendes FHEM Modul entwickelt oder ein universelles Modul erweitert werden (also auf flexibel direkt updatebarer Rechner-Seite!!). Änderungen am Arduino-Firmware-Code sind normalerweise nicht notwendig (sofern die grundsätzliche Signal-Klassifizierung des Sticks korrekt funktioniert - leider nicht immer, z.B.: [https://github.com/RFD-FHEM/SIGNALDuino/issues/65 MU-Nachrichten werden z.T. als MC erkannt]).

Ein großer Vorteil des SIGNALduino besteht darin, dass auch Geräte mit leicht abweichende Frequenzen steuerbar sind; so empfangen die Somfy-Rolladenmotoren beispielsweise auf 433.42 und nicht, wie bei anderen Geräten sehr oft üblich, auf 433.92 MHz. Die Frequenzumstellung stellt für den SIGNALduino kein Problem dar.

Ebenso kann man den SIGNALduino direkt an den Sendeausgang eines Sensors anbinden und die digitalen Signale empfangen, dabei bitte aber auf die passenden Spannungen achten, denn ein Arduino Nano verträgt nur 5V.

=== Entwicklungsversion ===
Der SIGNALduino wird derzeit aktiv weiterentwickelt, siehe dazu https://github.com/RFD-FHEM. Die offizielle Version wird {{Link2Forum|Topic=58396|LinkText=hier}} genauer beschrieben. Es existieren im Forum diverse angepasste Versionen, auf die hier nicht näher eingegangen wird.

== Hardware ==
=== Controller ===
Der SIGNALduino (Hardware) wird über den USB Port angeschlossen, er kann aber auch mit zusätzlichen ESP Modulen über ein WLAN angebunden werden. Bei Einbindung via ESP muss man beachten, dass der ESP nach 5 Minuten Inaktivität seine TCP-Verbindung unterbricht (siehe [[ESP8266#Bekannte_Probleme|diesen Hinweis]]). Zu diesem Zweck gibt es einen Signalduino-eigenen Ping-Befehl ('get signalduino ping'), der diese Aktivität wieder aufbaut. Ping-Befehle sind auch auf Betriebssystemebene bekannt - allerdings beachte man, dass der ping-Befehl auf Betriebssystemebene ICMP verwendet, zum "aufwachen" des ESP aber auf TCP-Ebene aktiviert werden muss (zum Unterschied siehe [https://www.tippscout.de/internet-was-sind-tcp-ip-udp-und-icmp_tipp_2268.html hier]) und man daher besser den Signalduino-eigenen Befehl und nicht das Betriebssystem verwendet.

Der SIGNALduino basiert auf einem [http://arduino.cc/de/Main/ArduinoBoardNano Arduino Nano], die Schaltung entspricht dem [[Selbstbau_CUL]] (eine frühere Version ist der nicht mehr weiterentwickelte [[FHEMduino]]):
* Entweder wird ein Arduino mit einfachen Sende- und Empfangsmodulen verwendet, dann ist die Verkabelung identisch zum [[FHEMduino]]
* Oder es wird ein CC1101 Transceiver verwendet, dann ist die Verkabelung identisch zum [[Selbstbau_CUL]]. Dieser Aufbau wird derzeit empfohlen.
* Zuletzt gibt es ein fertig konfektioniertes Modul von In-Circuit mit Radino CC1101 Varianten, link zum [http://shop.in-circuit.de/index.php Hersteller].

Achten Sie beim Selbstbau auf die entsprechenden Sender-Empfänger. Der sehr preiswert angebotene XY-MK-5V hat sich als zu unzuverlässig erwiesen, während anscheinend beim CC1101 (insbesondere der "grünen Version") keine Probleme auftreten.

Es stehen auch für den [https://www.arduino.cc/en/Main/arduinoBoardUno UNO] und [https://www.arduino.cc/en/Main/ArduinoBoardProMini PRO Mini] Firmware-Dateien zur Verfügung. Die ausgelieferte Firmware läuft nur auf Mikrocontrollern mit 16 MHz; wer einen Mikrocontroller mit 8 MHz verwenden möchte, muss die Firmware selbst compilieren. Die SW ist auf [https://github.com/RFD-FHEM/SIGNALDuino github]. Vorgesehen ist nur die Übersetzung unter Windows mit Visual Studio und dem Visual Micro Zusatz. Es gibt aber auch eine Anleitung, wie man mit der [[Arduino]] IDE oder einem Makefile [[SIGNALduino Compilieren]] kann.

Es gibt auch eine Variante des SIGNALduino, die auf einem [[ESP8266]] nativ läuft, diese funktioniert seit Anfang 2018 annehmbar, allerdings befindet diese sich noch in einer Entwicklungsphase.

An den "SIGNALESP" kann auch ein CC1101 via SPI angebunden werden:

{| |
!CC1101 Bezeichnung
!ESP Pin
|-
|CLK||GPIO14
|-
|MOSI||GPIO13
|-
|MISO||GPIO12
|-
|CSN||GPIO15
|-
|GDO0||GPIO4
|-
|GDO2||GPIO5
|}

Wird ein einfacher Empfänger / Sender Kombination verwendet, dann über die PINs:

{| |
! Bezeichnung
! ESP Pin
|-
|Transmitter||GPIO4
|-
|Receiver||GPIO5
|}

=== Sendemodule ===
{{Randnotiz|RNTyp=r|RNText=Viele user berichten über Empfangsprobleme bei Nutzung des XY-MK-5V; es wird ausdrücklich empfohlen, ein anderes Empfangsmodul zu nutzen!}}
[[Datei:Fhemduino_schematic.png|200px|thumb|right|Beispielschaltplan SIGNAL(FHEM)duino]]

Mit einem Arduino-Nano und folgenden, billigen Sende- und Empfangsmodulen können Sie einen SIGNALduino bauen:
* FS1000A Dies ist das Sendemodul (TX) und wird oft im Set mit dem billigen XY-MK-5V-Empfänger angeboten (etwa 5€).
* RXB6 Das ist das empfohlene Empfangsmodul (RX), statt XY-MK-5V, etwa 5€ aus Deutschland.

Die Verkabelung erfolgt analog zum [[FHEMduino]] und das bedeutet (Arduino -> Modul):
* PIN D2 an DATA des RX-Moduls
* PIN D11 an DATA des TX-Moduls (PIN links mit Beschriftung ATAD)

Zusätzlich muss noch jeweils GND und 5V des Arduino mit dem GND bzw. VCC des Moduls verbunden werden.

Jetzt fehlen noch die Antennen. Dafür braucht man ein 17,2 cm langes Stück Kupferdraht, das wird beim Anschluss "ANT" jeweils am Modul angelötet (anfängergeeignet).

== Software ==

=== USB-ID ermitteln ===
Bevor der SIGNALduino mit dem FHEM Server (im Beispiel hier ein Raspberry PI) verbunden werden kann, muss die USB-Schnittstelle ermittelt werden. Hierzu bitte auf dem Terminal den Befehl
<pre> ls -l /dev/serial/by-id </pre>
ausführen. Beispielhaft sieht das Ergebnis etwa so aus:
''lrwxrwxrwx 1 root root 13 Jan 31 00:02 '''usb-FTDI_FT232R_USB_UART_A903N5T5-if00-port''' -> ../../ttyUSB0''
Damit ist der Anschluss des SIGNALduino bestimmt und das Gerät kann wie im nächsten Abschnitt beschrieben definiert werden. Zuvor muss noch das Modul geladen werden.

=== FHEM-Modul laden ===
Die SIGNALduino Module werden über das FHEM [[update]] verteilt, sobald die Änderungen einen "stabilen" und alltags tauglichen Zustand haben. Aktuell wird dort die Version 3.4.2 seit 08.04.2020 verteilt.

Die in der Entwicklung befindliche Version (3.4.x) kann mit folgenden Befehlen geladen werden:

* FHEM aktualisieren: <code>update</code>
* SIGNALduino Modul aktualisieren: <code>update all <nowiki>https://raw.githubusercontent.com/RFD-FHEM/RFFHEM/dev-r34/controls_signalduino.txt</nowiki></code> Durch das Update von FHEM wird sichergestellt, dass das Modul mit FHEM arbeitet.
*Danach kann das Gerät wie folgt definiert werden (die Spezifikation des USB-Anschlusses muss dabei an die aktuellen Gegebenheiten angepasst werden):
:<code>define <eigener-SIGNALduino-Name> SIGNALduino /dev/serial/by-id/usb-FTDI_FT232R_USB_UART_A903N5T5-if00-port0@57600</code>
* Solltet Ihr einen SIGNALESP via IP einbinden wollen ist die Syntax
:<code>define <eigener-SIGNALESP-Name> SIGNALduino <ip-adresse>:23</code>
Nach dem Einbinden wird der SIGNALduino, falls er erkannt wird, im Status "Opened" angezeigt. Die Baudrate beim SIGNALduino beträgt 57600 - via telnet muss dann dieselbe Baudrate eingestellt werden.

Für neuere Entwicklungen kann in FHEM auch dauerhaft die developer Version aktualisiert werden:
<code>update add <nowiki>https://raw.githubusercontent.com/RFD-FHEM/RFFHEM/dev-r34/controls_signalduino.txt</nowiki></code>
Danach wird FHEM bei dem normalen Update-Befehl immer automatisch die aktuelle dev Version laden.

Die nachfolgenden Beispiel-Befehle verwenden "sduino" als <eigener-SIGNALduino-Name>.

==== Flashen des Arduino mit der SIGNALduino Firmware ====
Falls avrdude noch nicht vorhanden ist, kann es mit folgendem Befehl installiert werden:
:<code>sudo apt-get install avrdude</code>

In FHEM ist der SIGNALduino mit dem Status "Open" vorhanden. Jetzt müssen wir FHEM noch mitteilen, welche Hardware wir angeschlossen haben. Über das Attribut ''hardware'' lässt sich zwischen den mitgelieferten Firmware-Dateien wechseln. Solltet ihr einen Nano mit cc1101 Transceiver verwenden, so wählt bitte folgende Hardware
:<code>attr sduino hardware nanoCC1101</code>
sonst üblicherweise
:<code>attr sduino hardware nano328</code>

Dann muss mitgeteilt werden, welche Version man geladen haben will: stable oder testing.
:<code>attr sduino updateChannelFW testing</code>
Nun wird die entsprechende Firmware heruntergeladen. Dies geschieht durch den Befehl
:<code>get sduino availableFirmware</code>
Anschließend kann der ''flash'' Befehl abgesetzt werden:
:<code>set sduino flash <und-dann-auswaehlen></code>
Dadurch wird der Arduino mit der gewählten Firmware geflasht. Das Ergebnis wird im Webinterface direkt angezeigt.

Alternativ kann auch der Flash-Befehl mit einem Dateinamen aufgerufen werden. Diese Möglichkeit sollte jedoch nur verwendet werden, wenn die SIGNALduino Firmware selbst compiliert wurde und eine andere Hardware verwendet wird. Der Flash-Befehl wird wie folgt aufgerufen:
:<code>set sduino flash FHEM/firmware/SIGNALduino_mega2560.hex</code>
(je nachdem wo und unter welchem Namen die .hex Datei abgelegt wurde)

Wenn ein miniCUL geflasht werden soll, sind einige Besonderheiten zu beachten. Details dazu in {{Link2Forum|Topic=114413|LinkText=diesem Forenthema}}.

==== Flashen einer Firmware über HTTP ====
Die Firmware wird in nicht mehr über den FHEM Update Mechanismus verteilt.
Damit die passende Firmware auf den SIGNALduino geladen werden kann, wird diese dann über HTTP aus den Github Releases geladen.

==== Vorabversion einer Firmware ====
Die Firmware des SIGNALduino wird ebenso wie das FHEM Modul auch weiter entwickelt.
Die Entwickler sind auf Tests und Rückmeldungen der Nutzer angewiesen, da leider nicht alle Sensoren vorher getestet werden können.

Aktuell (April 2020) ist noch die Version 3.3.1 fertig. Die Version 3.4 ist seit Februar 2020 in einer Vorabversion verfügbar.

Für die folgenden Microcontroller kann man die Firmware seit 21.02.2019 auch direkt downloaden und teilweise flashen.
Dazu muss das Attribut hardware auf einen gültigen Wert angepasst werden!
Über den GET Befehl availableFirmware werden dann für die hinterlegte Hardware die passenden Versionen gesucht. Über das Attribut updateChannelFW kann zwischen "stable" und "testing" definiert werden, welche Art von Firmware angeboten werden soll.

Nachdem die Firmwareversion erfragt wurde, bietet der set flash Befehl eine Auswahlliste an. Wird ein Flash Befehl mit einer der Versionen ausgewählt, wird diese Version zunächst heruntergeladen und bei den AVR Versionen auch versucht diese mittels avrdude zu flashen.
Die Firmware für den ESP8266 kann aktuell leider noch nicht über diesen Befehl aktualisiert werden.

Alternativ funktioniert aber auch die Option, dem Flash Befehl eine URL zu übergeben. Dann wird die Datei aus der URL heruntergeladen und auch versucht diese zu Flashen. z.B.
SIGNALDuino_nanocc1101.hex für einen Nano mit CC1101

<code>set sduino flash </code>https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1/SIGNALDuino_radinocc11013.3.1.hex

oder
SIGNALESP_.hex (mit cc1101) für einen ESP8266
<code>set ipduino flash </code>https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1/SIGNALDuino_ESP8266cc11013.3.1.hex

!Achtung, aktuell wird die Firmware für den ESP dadurch nur herunter geladen. Flashen müsst ihr leider immer noch über ein passendes Tool
z.B. [https://github.com/nodemcu/nodemcu-flasher ESP8266Flasher.exe] oder Esptool und einer seriellen Konsole.
Auch ist zu beachten, es handelt sich hierbei tatsächlich um ein Binary und nicht um ein Hex File.

Nach dem Booten des ESPs, spannt dieser ein eigenes WLAN auf. Habt ihr euch damit verbunden, könnt ihr den ESP mit eurem vorhandenen WLAN nach Eingabe der Daten verbinden.

Die Hauptseite für Firmware-Releases findet sich unter https://github.com/RFD-FHEM/SIGNALDuino/releases/ .
Dort kann auch eine Änderungshistorie eingesehen werden.
==== Flashen eines radino Boards mit ATmega32U4 ====

Diese Funktion steht seit 21.02.2019 nun auch in der via FHEM aktualisierten version zur Verfügung:

Auch sind Berichte bekannt, dass der Radino beim Neustart von FHEM nicht korrekt initialisiert wird.
Weiterhin ist zu beachten, dass der Bootloader eine andere USB ID bekommt und diese im Attribut flashCommand hinterlegt werden muss.

==== Fehler beim Flashen ====
Sollte bei einem Flash Vorgang ein Fehler auftreten, solltet ihr zunächst im Logfile mit Verbose 5 nachsehen.

Findet ihr dort keine Fehlermeldung, gibt es noch ein separates Flashlog, welches ihr über einen Browser aufrufen könnt. Dazu müsst ihr nur den Folgenden Pfad an euren Servernamen anhängen:
<code>
/fhem/FileLog_logWrapper?dev=Logfile&type=text&file=SIGNALduino-Flash.log
</code>

=== Geräteerkennung ===
==== Unterstützte Geräte ====
Für die folgenden Geräte gibt es derzeit (2017) eine Unterstützung für den Betrieb mit FHEM. Die Geräte werden [[autocreate|automatisch erkannt]] und in der Konfiguration eingetragen, wenn der SIGNALduino läuft.
Bitte Geräte mit sehr präzisen Referenzen hier listen (Produktnummer, Protokoll-Variantenname etc.), damit eine globale Suche/Verifikation maximal erfolgreich ist. In der detaillierten Liste [[Geprüfte_Geräte]] lassen sich die Geräte näher identifizieren.
{| class="wikitable"
! style="text-align:left;" | Produkt
! (E)mpfangen<br />(S)enden
! Hinweise
! Verwendetes Modul
! Protokoll ID
|-
|Conrad Wetterstation KW9110||E S||Sensor: KW9010, neben Temperatur u. Luftfeuchte werden auch Trend, Batterie u. Kanal erfasst|| CUL_TCM97001 || 0.3
|-
|TCM Wetterstation (97001 und 21xxx Serie)||E|| || CUL_TCM97001 || 0
|-
|ABS Wetterstation (ABS 700)||E|| || CUL_TCM97001 || 0
|-
|Prologue Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Rubicson Wetterstation ||E|| ||CUL_TCM97001 ||0
|-
|NC_WS Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|[http://www.gt-support.de/ GT-WT-02 Wetterstation]||E|| ||CUL_TCM97001 || 0
|-
|AURIOL Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Mebus Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Intertechno Funkschalter||E S|| ||IT || 3,4,5,17
|-
|<strike>Conrad RSL Funkschalter</strike>||E S|| Funktioniert aktuell nicht || SIGNALduino_RSL ||
|-
|[http://global.oregonscientific.com/product_view.php?id=5 Oregon Scientific Wettersensoren]||E || Protokoll V2 & V3 implementiert || OREGON || 10
|-
|Bresser Temp/Hydro Sensor||E || || Hideki || 12
|-
|[https://de.hama.com/00104985/hama-aussensensor-ts33c-fuer-wetterstation Hama TS33C]||E || || Hideki || 12
|-
|TFA Temp/Hydro Sensor||E || || Hideki || 12
|-
|Lacrosse TX2/TX3 Sensoren||E || || CUL_TX || 8
|-
|TFA 30320902||E || || SD_WS07 || 7
|-
|Eurochron eas800z||E || || SD_WS07 || 7
|-
|Technoline WS6750/TX70DTH||E || || SD_WS07 || 7
|-
|FreeTec Außenmodul NC-7344||E || || SD_WS07 || 7
|-
|CTW600||E || || SD_WS09 || 9
|-
|CTW602||E ||neuere Version des CTW600 mit 868.35 MHz || SD_WS09 || 9
|-
|WH1080||E || || SD_WS09 || 9
|-
|Visivon remote pt4450||E || || none || 24
|-
|Einhell HS 434/6||E || || none || 21
|-
|Flamingo FA20RF / FA21RF / FA22RF Rauchmelder||E || || FLAMINGO || 13,13.1,13.2
|-
|mumbi m-FS300||E || || none || 26,27
|-
|TFA 30.3200||E || || none || 33
|-
|Livolo||E|| || none || 20
|-
|Smartwares RM174RF/2 (RM174RF-001CPR) 4500177571 ||E [S?]|| IT EV1527; TODO herausfinden: Alarmierung (wie Alarmton getriggered werden kann); Batterieinfo? || IT || 3
|-
|Smartwares SH5-TSO-A||E S|| || IT || ?
|-
|X10 Security Devices||E|| || || 39
|-
|[[Somfy_via_SIGNALduino|Somfy RTS]]||E S|| || SOMFY || 43
|}
Bei einigen Intertechno-Funksteckdosen (Brennenstuhl) kann es zu Empfangsproblemen kommen. Hier muss die Taktrate, mit der gesendet wird, angepasst werden. Dazu muss für ''Funksteckdose'' (also sauber per-Client-Instanz-spezifisch, NICHT SIGNALduino-Transceiver-global) das Attribut
:<code>attr <Funksteckdose> ITclock 300</code>
gesetzt werden, der Standardwert ist 250.

==== Mein Gerät wird in FHEM nicht erkannt ====
1. Prüfen, ob vom Sensor die Signaldaten (verbose >=4) erkannt werden. Sobald ihr die empfangenen Signaldaten im Logfile zuordnen könnt, geht es weiter mit:

2. Eröffnet ein Thema unter [https://github.com/RFD-FHEM/RFFHEM/issues/new?template=sensor---device-feature.md github]:<syntaxhighlight lang="md">
## Specifications for new sensor / switch / or other device ...

- manufacturer:
- model name:
- pictures of the device / the board (very helpful)

## Specifications

- Microcontroller:
- Version (Firmware):


- Versionmodul (FHEM Module):

</syntaxhighlight>3. Auszug aus dem Logfile, welches zum Gerät gehört.
:''Alles was ihr sonst noch über das Gerät und die übertragenen Daten wisst.''

Im Forum solltet ihr solche Fragen besser nicht posten, wenn das Gerät noch nicht unterstützt wird, dazu ist Github besser geeignet. Inzwischen wurde im Wiki eine eigene Seite eröffnet, die sich mit der Erkennung unbekannter Protokolle beschäftigt: [[Unbekannte_Funkprotokolle#Ansatz_1_-_Versuchen|Unbekannte_Funkprotokolle]].

==== Es wird ein Protokoll erkannt, Autocreate legt aber kein device an ====
Im SIGNALduino sind >70 Protokolle implementiert. Jedoch gibt es nicht immer ein logisches Module, welche diese Protokolle verarbeiten.
Teilweise ist das auch nicht zwingend notwendig, um seine Anforderungen zu erfüllen. Insbesondere für Schalter bzw. Sensoren, die nur zwei Zustände kennen, geht es meist ohne Modul und automatisch angelegtem Gerät.

Nehmen wir an, wir haben einen Schalter. Dieser kann einen oder zwei Zustände senden.
Im FHEM Log (und, insbesondere, im FHEMWEB Event Monitor) tauchen Meldungen ähnlich dieser auf

<code>
2015.11.15 15:52:23 4: SIGNALduino_unknown incomming msg: u85#FF8081
</code>

Wir können mit Hilfe des Modules DOIF auf diese Nachricht eine Aktion ausführen:

Entweder, wenn wir den Inhalt der Nachricht nur zu Teilen wissen, da er sich ändert:

<code>
define mydoif DOIF ([sduino:&DMSG] =~ "u85#FF8081") (set Lamp on)
attr mydoif do always
</code>

Oder, wenn wir den Inhalt exakt kennen, dann auch als Vergleichsstring

<code>
define mydoif DOIF ([sduino:&DMSG] eq "u85#FF8081") (set relais on)
attr mydoif do always
</code>

Der Teil u85#FF8081 muss individuell angepasst werden, der Name eures SIGNALduino möglicherweise auch.

Als Alternative zu DOIF hier ein regex-verwendendes notify-Beispiel für einen Sender, der meint, zwei Codes alternierend senden zu müssen:

<code>
define n_sender_trigger notify sduino:UNKNOWNCODE.*u41#(13B72253|163873B3) { my_sender_trigger_indicate();; }
</code>

Selbstverständlich muss in diesem Moment auch eine sub my_sender_trigger_indicate() definiert werden (z.B. in FHEM/99_myUtils.pm), die dort z.B. als Test eine Log-Ausgabe (Log3()) machen kann.

=== Das Logfile ===
Im Logfile ab [[Verbose]] 4 tauchen diverse Meldungen auf, deren Bedeutung kurz erläutert wird (verbose 3 unterdrückt diese Meldungen).

UPDATE: der folgende Bereich ist von einem weniger erfahrenen Zeitgenossen früher nach Kräften erweitert/geschrieben worden. Mittlerweile existiert aber ein neuer Inhalt [[Unbekannte_Funkprotokolle]] (siehe auch Erwähnung weiter oben), der als sehr gut beschrieben und unvergleichlich detailreicher bezeichnet werden muss ("endlich gibt es sowas!"). Der Bereich hier dürfte somit zwar für grundlegende Verdeutlichungen noch recht sinnvoll sein, der Inhalt sollte allerdings evt. in eine konsistente Dokumentation überarbeitet (verlagert/dedupliziert/reduziert) werden.

Die Protokolle (von der SIGNALDuino-Firmware gesendete Signal-Beschreibungs-Strings) können wie folgt unterschieden werden:

*MS - Nachricht mit Sync Puls: Hierzu ein Beispiel
:<code>MS;P0=-108;P1=395;P2=-1033;P3=-547;P4=-19932;P5=-8916;P6=1368;D=151313131312131313131313131313131312121212121313131313131312131212132;CP=1;SP=5;</code> P0-P6 sind die Signalpegel (Dauer und positiv/negativ). Hinter D= befindet sich die Abfolge der Signale. Die ersten beiden Ziffern 15 in D sind wie folgt zu lesen. Zuerst wurde ein Signal "1" also P1 mit 395 Mikrosekunden high (die Zeitdauer ergibt sich aufgrund der Mitteilung "P1=395") und anschließend ein Signal "5" also P5 mit 8916 Mikrosekunden low (die Zeitdauer ergibt sich aufgrund der Mitteilung "P5=-8916") gemessen. CP=1 ist die Referenz auf den Takt des Signales - der Basistakt ist in diesem Fall ~395 Mikrosekunden. SP=5 gibt die Referenz zum Syncpuls an, der das gesamte Signal einleitet. Welche Signalfolge nun eine binäre 1 bzw. 0 bedeutet, wird im SIGNALduino über die integrierte Protokoll Liste realisiert.

*MC - Nachricht vom Typ Manchester: Manchesterkodierte Signale können bereits sehr einfach im Arduino in eine Binärform umgewandelt werden. Es wird hier nach IEEE 802.3 umgewandelt. In Manchester Signalen gibt es lange und kurze Pulse. Deren Durchschnittswert wird mit LL (long low), LH (long high), SL (short low) und SH (short high) übermittelt. Zusätzlich, um das Protokoll schneller erkennen zu können, wird die Taktfrequenz mit übermittelt (C=429 Mikrosekunden). Die Daten befinden sich hinter D= und werden in HEX Form übergeben.
:<code>MC;LL=-1066;LH=904;SL=-562;SH=385;D=332B4B4D54D5554B552CD2D554B2B5354A;C=429;</code>

*MU - Message unsynced: Diese Art von Nachrichten sind nicht nach Manchester codiert und haben auch keinen erkennbaren Sync / Clock Signalpegel am Start der Nachricht. Bei diesen Nachrichtentypen ist es, im Vergleich zu den anderen, am wahrscheinlichsten, dass das übermittelte Signal unvollständig oder überhaupt kein Signal ist. Wie bei MS sind P0-P6 die Signalpegel und in D= wird die Abfolge der Signalpegel referenziert. CP=2 gibt auch hier die Referenz zum Takt an, allerdings muss dieser nicht korrekt erkannt worden sein.
:<code>MU;P0=1372;P1=-580;P2=362;P3=-1047;D=01212321212321212121212121212123212123212321232121212121212321;CP=2;</code>

Es erscheinen viele Meldungen dieser Art:

<pre>
Fingerprint for MU Protocol id xxxx -> yyy matches, trying to demodulate
sduino: Starting demodulation at Position 1
Fingerprint for MU Protocol id 28 -> IC Ledspot matches, trying to demodulate
sduino: Starting demodulation at Position 1
Fingerprint for MU Protocol id 29 -> HT12e remote matches, trying to demodulate
</pre>

Dies sind nun Bemühungen, anhand der von der SIGNALDuino-Firmware gelieferten rohen aber detaillierten Signal-Strings eine Vor-Analyse / Fingerprinting vorzunehmen.
Man könnte nun z.B. bei solchen Fingerprinting-Analysen erkennen:
* dass der Basis-Takt-Wert innerhalb eines charakteristischen Zeit-Bereichs liegt
* dass die Anzahl der Sync-Pulse eine präzise Zahl ist
* dass Längen erkannter Puls-Typen innerhalb eines Bereichs liegen

Mittels solcher Untersuchungen kann man also final hoffentlich hinreichend plausibel feststellen, "dass diese Aktivitäten offensichtlich(?) zu einer Funk-Komponente Rauchmelder von Hersteller XYZ gehören müssen, und man somit weiterleiten muss an ein (möglicherweise bereits existierendes) Userdaten-Dekodier-Modul für diese Herstellerkomponente".

Bei einer dann erfolgenden Demodulation des noch rohen SIGNALDuino-Strings könnte man z.B. (hoffentlich richtigerweise) annehmen, dass eine Signalpegel-Typ-Folge "13" eine binäre 1 bedeuten soll, während eine Folge "12" eine binäre 0 bedeuten soll. Man erhält aus dem Gesamt-Puls-String also nach vollständiger Demodulation eine Abfolge von vielen 0/1 Bits, die insgesamt ein Datenwort darstellen, mit einer gewissen Länge von NN bits (diese Längen-Angabe könnte übrigens - neben Namenssuche nach Hersteller oder Produkt etc. - ein wichtiges Such-Merkmal sein, ob andere Frameworks tatsächlich bereits wissen, wie Daten dieser Funk-Komponente zu dekodieren sind!). Dieses demodulierte Datenwort ist nun das finale Datenwort, welches einen Container für die Funk-Komponenten-Informationen darstellt (in diesem Container also beispielsweise enthalten: Temperatur, Feuchte, Akku-Status, ID, Alarm, ... - zumindest wenn nicht dummerweise der ganze Container erst einmal CRC- oder Crypto-verschlüsselt ist...).

Man muss an dieser Stelle unbedingt sagen, dass dieses Userdaten-Datenwort (einer bestimmten Hersteller-Funk-Komponente!) natürlich bei ''jeglichen'' Transceiver-Systemen ''immer'' gleich erkannt werden ''muss'' - an dieser Stelle ist also ganz klar, dass diese Daten an ''allgemeine'' FHEM-Module weitergeleitet (Dispatched) werden müssen, die nach Übernahme von Daten von ''jeglichen'' Transceiver-Systemen diese Daten immer auf die gleiche Weise ('''''generisch/zentral''''') für die jeweilige Hersteller-Funk-Komponente erledigen.

'''Die Abfolge ist also ganz klar:'''
Funk-Aktivität --> Transceiver-Gerät/Firmware (SIGNALDuino) --> maximal detailreich beschreibender Rx-Analyse-Output-String --> Fingerprinting-Grobzuordnung des (SIGNALDuino-Firmware-)Outputs (durch 00_SIGNALduino.pm) auf gerätespezifisches Verhalten --> ''generische/zentrale'' Dekodierung des gerätespezifischen Protokoll-Datenworts, in zentralen Grundsatz-Modulen wie z.B. <code>14_SD_WS.pm</code>).

Und wenn dann bei einer solchen Schritte-Abfolge irgendetwas noch fehlen/unpassend sein sollte, dann muss eben entsprechendes Development an gewissen Stellen erfolgen ;-)

====Minimieren (whitelist/blacklist) von unerwünschter Kommunikations-Aktivität/Einträgen====

"Unknown Code" bedeutet, dass der SIGNALduino Signaldaten empfangen und diese binär interpretiert hat. Diese Meldung soll uns nun aber mitteilen, dass es dann nicht weiter verarbeitet werden kann, da kein Modul existiert (oder kein Weiterleitungs-Dispatch zu einem bereits existierenden), welches diese Daten jetzt in ihre Bedeutung umwandeln kann.
:<code>sduino: Unknown code u1FFFFF0, help me!</code>

Außerdem kommt es gehäuft zu Logmeldungen und auch Events in ähnlicher Form:
:<code>SIGNALduino_unknown incomming msg: u85#FF8081</code>

Mittlerweile sind über 50 Protokolle für den SIGNALduino definiert. Dadurch kommt es vor, dass sich ein Signal mit mehr als einem Protokoll demodulieren lässt. Meist führt dies dann zu zusätzlichen "Unknown code"-Einträgen.

Derartige Einträge können mit dem Attribut WhitelistID minimiert werden. Dabei werden die Geräte, die nach Daten-Empfang tatsächlich verarbeitet werden sollen (also welche Protokolle vom FHEM Modul berücksichtigt werden), mit ihrer Protokollnummer in die WhitelistID aufgenommen.
Für Protokolle, die nicht berücksichtigt werden, gibt es weder Logeinträge noch Events. Diese werden im Programmablauf nicht berücksichtigt. Das spart zum einen Ressourcen und trägt auch zur Übersichtlichkeit bei.
Die Protokollnummer kann Tabelle [[#Unterst.C3.BCtzte_Ger.C3.A4te|Unterstützte Geräte]] entnommen werden (hilfreich ist es auch, wenn in den verwendeten Geräten im Internal <gerätename>_DMSG nachgesehen wird). So bedeutet beispielsweise ein Eintrag der Form <code>W50#FF553335FFBC</code> dass dann das Protokoll #50 in die Whitelist aufzunehmen wäre (<code>attr sduino whitelist_IDs 50</code>).
{{Randnotiz|RNTyp=r|RNText=Achtung Schreibweise: Dokumentation oft als WhitelistID o.ä., aber Name ist whitelist_IDs!!
}}
Die Angabe erfolgt durch Komma getrennt: z.B.:
:<code>1,2,5,10</code>

=== Senden mit dem SIGNALduino ===
Der SIGNALduino kann etwas "raw senden", indem ihm das SIGNAL so übermittelt wird, wie er es moduliert. Hierzu muss der Befehl wie folgt eingegeben werden:

<code>
set sduino sendMsg P3#00111010#R4
</code>

Dieser Befehl moduliert die Bitfolge 00111010 mittels Protokoll #3 und wiederholt die Nachricht 4x.
Die Protokoll Nummer kann aus einer empfangenen Nachricht extrahiert werden. Ebenso die Bits.
<code>
sduino: extracted data 00111010 (bin)
sduino: Found Protocol id 3
</code>

Alternativ kann das Signal auch in einer "rohform" angegeben werden. Dies ist manchmal in speziellen Fällen notwendig:
<code>
set sduino raw SR;;R=3;;P0=4742;;P1=-1554;;P2=286;;P3=-786;;P4=649;;P5=-420;;D=0123234545234545452323232323454523234523454523232345454523232323452345234523452345;;
</code>

R=3 bedeutet, das Signal wird 3x gesendet.
Die Übertragung besteht aus den in D angegeben Pulsen, welche in P0-P5 definiert werden.
Die Daten kann man aus einer empfangenen MS oder MU Nachricht extrahieren.

Alternativ kann ab Version 3.2 auch eine vereinfachte Form eingegeben werden.

====Fehlersuche====
(Zielgerät reagiert nicht, etc.)

* Nachrichtenwiederholungsanzahl muss evt. für manche Geräte entsprechend groß eingestellt sein
{{Randnotiz|RNTyp=r|RNText=VORSICHT blöder Schreibweisen-Mismatch ITClock vs. ITclock!!}}
* Sende-Takt-Wert (Clock) passt evt. nicht ganz, siehe z.B. Thread-Antwort {{Link2Forum|Topic=58397|Message=775434|LinkText=Signalduino Version 3.3.1}}, wo für IT-Geräte ein Attribut anhand der CP= des Empfangsdaten-Logs modifiziert wird. ACHTUNG: dies kann entweder global das Internal-Attribut ITClock eines SIGNALduino-Transceiver-Devices sein, oder (viel besser da korrekt geräte-instanz-spezifische Konfiguration) das ITclock eines IT-Client-Devices.

== Fehlerbehandlung ==
Der SIGNALduino kann mit folgendem Befehl auf Werkseinstellungen zurückgesetzt werden:
:<code>set raw e</code>
Ob ein solcher Reset nötig ist, erkennt man an dem Inhalt vom Reading <code>cc1101_config</code>, dort unsinnige Werte angezeigt werden oder dem Reading <code>config</code> welches durch den Befehl "get config" aktualisiert wird, was im Standard auf "MS=1;MU=1;MC=1" entspricht.

In der Firmware sind die diverse Befehle eingebaut, welche über einen <code>set raw</code> Befehl im Modul direkt ausgeführt werden können. Sofern möglich, sollten die Abfrage von Werten aus dem Modul allerdings mit den dafür vorgesehenen Kommandos erfolgen, da die Rückmeldungen des <code>set raw</code> Befehls nur im Logfile ab Verbose 4 erscheinen. Die Befehle sind nützlich, wenn direkt auf den Microcontroller zugegriffen wird:

:<code>C<reg></code> <reg> is a (two digit) hex number: return the value of the cc1101 register. <reg>=99 dumps the first 48 registers. Example: <code>set raw C35</code> führt ab Verbose 4 zu einer Logausgabe folgender Art <code>Read, msg: C35 = 0D</code>
:<code>e</code> EEPROM / factory reset. resets all eeprom values without reboot
:<code>W<AA><XX></code> Write eeprom (schreibt einen Wert ins EEPROM und ins CC1101 Register. Die eeprom Adresse hat einen Offset von 2. z.B W041D schreibt 1D ins Register 2 des CC1101)

Die Sendeleistung lässt sich mit
:<code>get sduino ccpatable</code>

prüfen, wobei die Rückmeldung wie folgt zu lesen ist:
"-10_dBm" => '34',
"-5_dBm" => '68',
"0_dBm" => '60',
"5_dBm" => '84',
"7_dBm" => 'C8',
"10_dBm" => 'C0'
Dabei wird die Sendeleistung dauerhaft mit dem Befehl
:<code>set sduino cc1101_patable <value></code>
hochgeschaltet (<value> durch den Wert ersetzen).

Weitere Firmware-Befehle sind im Thread-Beitrag {{Link2Forum|Topic=58396|Message=497921}} zu finden.

== Foren Links ==
* {{Link2Forum|Topic=38402|LinkText=Forenthread - Ankündigung}}
* {{Link2Forum|Topic=58396|LinkText=SIGNALDuino Empfänger Firm- und Hardware}}
* {{Link2Forum|Topic=82379|Message=1033374|LinkText=SIGNALDuino Schaltplan}}
* {{Link2Forum|Topic=58397|LinkText=Signalduino Entwicklung Version 3.3.1 }}
* [http://www.rflink.nl/blog2/wiring Beschreibung zu diversen Empfängern und Verbesserung der Empfangsleistung]
* [[SIGNALduino in die Arduino Entwicklungsumgebung einbinden]]
* [[Somfy via SIGNALduino]]

[[Kategorie:Interfaces]]
[[Kategorie:Arduino]]
[[Kategorie:433MHz]]
[[Kategorie:868MHz]]

SIGNALduino

2021-01-02T14:37:43Z

Kaihs: /* Minimieren (whitelist/blacklist) von unerwünschter Kommunikations-Aktivität/Einträgen */

{{Infobox Modul
|ModPurpose=Empfang und Verarbeitung von digitalen Signalen
|ModType=d
|ModFTopic=38402
|ModCmdRef=SIGNALduino
|ModForumArea=Sonstige Systeme
|ModTechName=00_SIGNALduino.pm
|ModOwner=Sidey ({{Link2FU|8018|Forum}}/[[Benutzer Diskussion:Sidey|Wiki]])
}}

== Einleitung ==
=== Übersicht ===
Unter den Namen SIGNALduino versteht man sowohl den Low-Cost Empfänger für digitale Signale (vergleichbar dem [[CUL]]) als auch das gleichnamige Modul mit dem Dateinamen 00_SIGNALduino.pm. Mit dem SIGNALduino kann man entweder 433 oder 868 MHz-Geräte auslesen und ansprechen. Der SIGNALduino funktioniert auch mit anderen Medien wie Infrarot oder direkter Kabelverbindung.

Der SIGNALduino(-Stick) erkennt Signale anhand von Mustern und gibt sie (als maximal detaillierte Beschreibung einer Signalabfolge) dann schlicht sofort nur noch an FHEM zur Auswertung (Dekodierung) weiter. Auch nicht erkannte Signale werden an FHEM übergeben.
Aufgabe des SIGNALduino (Firmware/Stick) ist es also nur, Signal-Aktivitäten zu erfassen und maximal präzise (als kurzer Text-String) zu beschreiben.
Alles weitere (echte, finale Auswertung / Zuweisung dieser Signal-Daten) wird dann auf einer großen Box (Raspberry o.ä.) gemacht.

=== Vorteil gegenüber einem CUL/FHEMduino ===
Der SIGNALduino hat den Vorteil einer sehr schnellen Demodulation des Funksignals. Sollen weitere Protokolle dekodiert werden, so muss dazu nur ein passendes FHEM Modul entwickelt oder ein universelles Modul erweitert werden (also auf flexibel direkt updatebarer Rechner-Seite!!). Änderungen am Arduino-Firmware-Code sind normalerweise nicht notwendig (sofern die grundsätzliche Signal-Klassifizierung des Sticks korrekt funktioniert - leider nicht immer, z.B.: [https://github.com/RFD-FHEM/SIGNALDuino/issues/65 MU-Nachrichten werden z.T. als MC erkannt]).

Ein großer Vorteil des SIGNALduino besteht darin, dass auch Geräte mit leicht abweichende Frequenzen steuerbar sind; so empfangen die Somfy-Rolladenmotoren beispielsweise auf 433.42 und nicht, wie bei anderen Geräten sehr oft üblich, auf 433.92 MHz. Die Frequenzumstellung stellt für den SIGNALduino kein Problem dar.

Ebenso kann man den SIGNALduino direkt an den Sendeausgang eines Sensors anbinden und die digitalen Signale empfangen, dabei bitte aber auf die passenden Spannungen achten, denn ein Arduino Nano verträgt nur 5V.

=== Entwicklungsversion ===
Der SIGNALduino wird derzeit aktiv weiterentwickelt, siehe dazu https://github.com/RFD-FHEM. Die offizielle Version wird {{Link2Forum|Topic=58396|LinkText=hier}} genauer beschrieben. Es existieren im Forum diverse angepasste Versionen, auf die hier nicht näher eingegangen wird.

== Hardware ==
=== Controller ===
Der SIGNALduino (Hardware) wird über den USB Port angeschlossen, er kann aber auch mit zusätzlichen ESP Modulen über ein WLAN angebunden werden. Bei Einbindung via ESP muss man beachten, dass der ESP nach 5 Minuten Inaktivität seine TCP-Verbindung unterbricht (siehe [[ESP8266#Bekannte_Probleme|diesen Hinweis]]). Zu diesem Zweck gibt es einen Signalduino-eigenen Ping-Befehl ('get signalduino ping'), der diese Aktivität wieder aufbaut. Ping-Befehle sind auch auf Betriebssystemebene bekannt - allerdings beachte man, dass der ping-Befehl auf Betriebssystemebene ICMP verwendet, zum "aufwachen" des ESP aber auf TCP-Ebene aktiviert werden muss (zum Unterschied siehe [https://www.tippscout.de/internet-was-sind-tcp-ip-udp-und-icmp_tipp_2268.html hier]) und man daher besser den Signalduino-eigenen Befehl und nicht das Betriebssystem verwendet.

Der SIGNALduino basiert auf einem [http://arduino.cc/de/Main/ArduinoBoardNano Arduino Nano], die Schaltung entspricht dem [[Selbstbau_CUL]] (eine frühere Version ist der nicht mehr weiterentwickelte [[FHEMduino]]):
* Entweder wird ein Arduino mit einfachen Sende- und Empfangsmodulen verwendet, dann ist die Verkabelung identisch zum [[FHEMduino]]
* Oder es wird ein CC1101 Transceiver verwendet, dann ist die Verkabelung identisch zum [[Selbstbau_CUL]]. Dieser Aufbau wird derzeit empfohlen.
* Zuletzt gibt es ein fertig konfektioniertes Modul von In-Circuit mit Radino CC1101 Varianten, link zum [http://shop.in-circuit.de/index.php Hersteller].

Achten Sie beim Selbstbau auf die entsprechenden Sender-Empfänger. Der sehr preiswert angebotene XY-MK-5V hat sich als zu unzuverlässig erwiesen, während anscheinend beim CC1101 (insbesondere der "grünen Version") keine Probleme auftreten.

Es stehen auch für den [https://www.arduino.cc/en/Main/arduinoBoardUno UNO] und [https://www.arduino.cc/en/Main/ArduinoBoardProMini PRO Mini] Firmware-Dateien zur Verfügung. Die ausgelieferte Firmware läuft nur auf Mikrocontrollern mit 16 MHz; wer einen Mikrocontroller mit 8 MHz verwenden möchte, muss die Firmware selbst compilieren. Die SW ist auf [https://github.com/RFD-FHEM/SIGNALDuino github]. Vorgesehen ist nur die Übersetzung unter Windows mit Visual Studio und dem Visual Micro Zusatz. Es gibt aber auch eine Anleitung, wie man mit der [[Arduino]] IDE oder einem Makefile [[SIGNALduino Compilieren]] kann.

Es gibt auch eine Variante des SIGNALduino, die auf einem [[ESP8266]] nativ läuft, diese funktioniert seit Anfang 2018 annehmbar, allerdings befindet diese sich noch in einer Entwicklungsphase.

An den "SIGNALESP" kann auch ein CC1101 via SPI angebunden werden:

{| |
!CC1101 Bezeichnung
!ESP Pin
|-
|CLK||GPIO14
|-
|MOSI||GPIO13
|-
|MISO||GPIO12
|-
|CSN||GPIO15
|-
|GDO0||GPIO4
|-
|GDO2||GPIO5
|}

Wird ein einfacher Empfänger / Sender Kombination verwendet, dann über die PINs:

{| |
! Bezeichnung
! ESP Pin
|-
|Transmitter||GPIO4
|-
|Receiver||GPIO5
|}

=== Sendemodule ===
{{Randnotiz|RNTyp=r|RNText=Viele user berichten über Empfangsprobleme bei Nutzung des XY-MK-5V; es wird ausdrücklich empfohlen, ein anderes Empfangsmodul zu nutzen!}}
[[Datei:Fhemduino_schematic.png|200px|thumb|right|Beispielschaltplan SIGNAL(FHEM)duino]]

Mit einem Arduino-Nano und folgenden, billigen Sende- und Empfangsmodulen können Sie einen SIGNALduino bauen:
* FS1000A Dies ist das Sendemodul (TX) und wird oft im Set mit dem billigen XY-MK-5V-Empfänger angeboten (etwa 5€).
* RXB6 Das ist das empfohlene Empfangsmodul (RX), statt XY-MK-5V, etwa 5€ aus Deutschland.

Die Verkabelung erfolgt analog zum [[FHEMduino]] und das bedeutet (Arduino -> Modul):
* PIN D2 an DATA des RX-Moduls
* PIN D11 an DATA des TX-Moduls (PIN links mit Beschriftung ATAD)

Zusätzlich muss noch jeweils GND und 5V des Arduino mit dem GND bzw. VCC des Moduls verbunden werden.

Jetzt fehlen noch die Antennen. Dafür braucht man ein 17,2 cm langes Stück Kupferdraht, das wird beim Anschluss "ANT" jeweils am Modul angelötet (anfängergeeignet).

== Software ==

=== USB-ID ermitteln ===
Bevor der SIGNALduino mit dem FHEM Server (im Beispiel hier ein Raspberry PI) verbunden werden kann, muss die USB-Schnittstelle ermittelt werden. Hierzu bitte auf dem Terminal den Befehl
<pre> ls -l /dev/serial/by-id </pre>
ausführen. Beispielhaft sieht das Ergebnis etwa so aus:
''lrwxrwxrwx 1 root root 13 Jan 31 00:02 '''usb-FTDI_FT232R_USB_UART_A903N5T5-if00-port''' -> ../../ttyUSB0''
Damit ist der Anschluss des SIGNALduino bestimmt und das Gerät kann wie im nächsten Abschnitt beschrieben definiert werden. Zuvor muss noch das Modul geladen werden.

=== FHEM-Modul laden ===
Die SIGNALduino Module werden über das FHEM [[update]] verteilt, sobald die Änderungen einen "stabilen" und alltags tauglichen Zustand haben. Aktuell wird dort die Version 3.4.2 seit 08.04.2020 verteilt.

Die in der Entwicklung befindliche Version (3.4.x) kann mit folgenden Befehlen geladen werden:

* FHEM aktualisieren: <code>update</code>
* SIGNALduino Modul aktualisieren: <code>update all <nowiki>https://raw.githubusercontent.com/RFD-FHEM/RFFHEM/dev-r34/controls_signalduino.txt</nowiki></code> Durch das Update von FHEM wird sichergestellt, dass das Modul mit FHEM arbeitet.
*Danach kann das Gerät wie folgt definiert werden (die Spezifikation des USB-Anschlusses muss dabei an die aktuellen Gegebenheiten angepasst werden):
:<code>define <eigener-SIGNALduino-Name> SIGNALduino /dev/serial/by-id/usb-FTDI_FT232R_USB_UART_A903N5T5-if00-port0@57600</code>
* Solltet Ihr einen SIGNALESP via IP einbinden wollen ist die Syntax
:<code>define <eigener-SIGNALESP-Name> SIGNALduino <ip-adresse>:23</code>
Nach dem Einbinden wird der SIGNALduino, falls er erkannt wird, im Status "Opened" angezeigt. Die Baudrate beim SIGNALduino beträgt 57600 - via telnet muss dann dieselbe Baudrate eingestellt werden.

Für neuere Entwicklungen kann in FHEM auch dauerhaft die developer Version aktualisiert werden:
<code>update add <nowiki>https://raw.githubusercontent.com/RFD-FHEM/RFFHEM/dev-r34/controls_signalduino.txt</nowiki></code>
Danach wird FHEM bei dem normalen Update-Befehl immer automatisch die aktuelle dev Version laden.

Die nachfolgenden Beispiel-Befehle verwenden "sduino" als <eigener-SIGNALduino-Name>.

==== Flashen des Arduino mit der SIGNALduino Firmware ====
Falls avrdude noch nicht vorhanden ist, kann es mit folgendem Befehl installiert werden:
:<code>sudo apt-get install avrdude</code>

In FHEM ist der SIGNALduino mit dem Status "Open" vorhanden. Jetzt müssen wir FHEM noch mitteilen, welche Hardware wir angeschlossen haben. Über das Attribut ''hardware'' lässt sich zwischen den mitgelieferten Firmware-Dateien wechseln. Solltet ihr einen Nano mit cc1101 Transceiver verwenden, so wählt bitte folgende Hardware
:<code>attr sduino hardware nanoCC1101</code>
sonst üblicherweise
:<code>attr sduino hardware nano328</code>

Dann muss mitgeteilt werden, welche Version man geladen haben will: stable oder testing.
:<code>attr sduino updateChannelFW testing</code>
Nun wird die entsprechende Firmware heruntergeladen. Dies geschieht durch den Befehl
:<code>get sduino availableFirmware</code>
Anschließend kann der ''flash'' Befehl abgesetzt werden:
:<code>set sduino flash <und-dann-auswaehlen></code>
Dadurch wird der Arduino mit der gewählten Firmware geflasht. Das Ergebnis wird im Webinterface direkt angezeigt.

Alternativ kann auch der Flash-Befehl mit einem Dateinamen aufgerufen werden. Diese Möglichkeit sollte jedoch nur verwendet werden, wenn die SIGNALduino Firmware selbst compiliert wurde und eine andere Hardware verwendet wird. Der Flash-Befehl wird wie folgt aufgerufen:
:<code>set sduino flash FHEM/firmware/SIGNALduino_mega2560.hex</code>
(je nachdem wo und unter welchem Namen die .hex Datei abgelegt wurde)

Wenn ein miniCUL geflasht werden soll, sind einige Besonderheiten zu beachten. Details dazu in {{Link2Forum|Topic=114413|LinkText=diesem Forenthema}}.

==== Flashen einer Firmware über HTTP ====
Die Firmware wird in nicht mehr über den FHEM Update Mechanismus verteilt.
Damit die passende Firmware auf den SIGNALduino geladen werden kann, wird diese dann über HTTP aus den Github Releases geladen.

==== Vorabversion einer Firmware ====
Die Firmware des SIGNALduino wird ebenso wie das FHEM Modul auch weiter entwickelt.
Die Entwickler sind auf Tests und Rückmeldungen der Nutzer angewiesen, da leider nicht alle Sensoren vorher getestet werden können.

Aktuell (April 2020) ist noch die Version 3.3.1 fertig. Die Version 3.4 ist seit Februar 2020 in einer Vorabversion verfügbar.

Für die folgenden Microcontroller kann man die Firmware seit 21.02.2019 auch direkt downloaden und teilweise flashen.
Dazu muss das Attribut hardware auf einen gültigen Wert angepasst werden!
Über den GET Befehl availableFirmware werden dann für die hinterlegte Hardware die passenden Versionen gesucht. Über das Attribut updateChannelFW kann zwischen "stable" und "testing" definiert werden, welche Art von Firmware angeboten werden soll.

Nachdem die Firmwareversion erfragt wurde, bietet der set flash Befehl eine Auswahlliste an. Wird ein Flash Befehl mit einer der Versionen ausgewählt, wird diese Version zunächst heruntergeladen und bei den AVR Versionen auch versucht diese mittels avrdude zu flashen.
Die Firmware für den ESP8266 kann aktuell leider noch nicht über diesen Befehl aktualisiert werden.

Alternativ funktioniert aber auch die Option, dem Flash Befehl eine URL zu übergeben. Dann wird die Datei aus der URL heruntergeladen und auch versucht diese zu Flashen. z.B.
SIGNALDuino_nanocc1101.hex für einen Nano mit CC1101

<code>set sduino flash </code>https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1/SIGNALDuino_radinocc11013.3.1.hex

oder
SIGNALESP_.hex (mit cc1101) für einen ESP8266
<code>set ipduino flash </code>https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1/SIGNALDuino_ESP8266cc11013.3.1.hex

!Achtung, aktuell wird die Firmware für den ESP dadurch nur herunter geladen. Flashen müsst ihr leider immer noch über ein passendes Tool
z.B. [https://github.com/nodemcu/nodemcu-flasher ESP8266Flasher.exe] oder Esptool und einer seriellen Konsole.
Auch ist zu beachten, es handelt sich hierbei tatsächlich um ein Binary und nicht um ein Hex File.

Nach dem Booten des ESPs, spannt dieser ein eigenes WLAN auf. Habt ihr euch damit verbunden, könnt ihr den ESP mit eurem vorhandenen WLAN nach Eingabe der Daten verbinden.

Die Hauptseite für Firmware-Releases findet sich unter https://github.com/RFD-FHEM/SIGNALDuino/releases/ .
Dort kann auch eine Änderungshistorie eingesehen werden.
==== Flashen eines radino Boards mit ATmega32U4 ====

Diese Funktion steht seit 21.02.2019 nun auch in der via FHEM aktualisierten version zur Verfügung:

Auch sind Berichte bekannt, dass der Radino beim Neustart von FHEM nicht korrekt initialisiert wird.
Weiterhin ist zu beachten, dass der Bootloader eine andere USB ID bekommt und diese im Attribut flashCommand hinterlegt werden muss.

==== Fehler beim Flashen ====
Sollte bei einem Flash Vorgang ein Fehler auftreten, solltet ihr zunächst im Logfile mit Verbose 5 nachsehen.

Findet ihr dort keine Fehlermeldung, gibt es noch ein separates Flashlog, welches ihr über einen Browser aufrufen könnt. Dazu müsst ihr nur den Folgenden Pfad an euren Servernamen anhängen:
<code>
/fhem/FileLog_logWrapper?dev=Logfile&type=text&file=SIGNALduino-Flash.log
</code>

=== Geräteerkennung ===
==== Unterstützte Geräte ====
Für die folgenden Geräte gibt es derzeit (2017) eine Unterstützung für den Betrieb mit FHEM. Die Geräte werden [[autocreate|automatisch erkannt]] und in der Konfiguration eingetragen, wenn der SIGNALduino läuft.
Bitte Geräte mit sehr präzisen Referenzen hier listen (Produktnummer, Protokoll-Variantenname etc.), damit eine globale Suche/Verifikation maximal erfolgreich ist. In der detaillierten Liste [[Geprüfte_Geräte]] lassen sich die Geräte näher identifizieren.
{| class="wikitable"
! style="text-align:left;" | Produkt
! (E)mpfangen<br />(S)enden
! Hinweise
! Verwendetes Modul
! Protokoll ID
|-
|Conrad Wetterstation KW9110||E S||Sensor: KW9010, neben Temperatur u. Luftfeuchte werden auch Trend, Batterie u. Kanal erfasst|| CUL_TCM97001 || 0.3
|-
|TCM Wetterstation (97001 und 21xxx Serie)||E|| || CUL_TCM97001 || 0
|-
|ABS Wetterstation (ABS 700)||E|| || CUL_TCM97001 || 0
|-
|Prologue Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Rubicson Wetterstation ||E|| ||CUL_TCM97001 ||0
|-
|NC_WS Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|[http://www.gt-support.de/ GT-WT-02 Wetterstation]||E|| ||CUL_TCM97001 || 0
|-
|AURIOL Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Mebus Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Intertechno Funkschalter||E S|| ||IT || 3,4,5,17
|-
|<strike>Conrad RSL Funkschalter</strike>||E S|| Funktioniert aktuell nicht || SIGNALduino_RSL ||
|-
|[http://global.oregonscientific.com/product_view.php?id=5 Oregon Scientific Wettersensoren]||E || Protokoll V2 & V3 implementiert || OREGON || 10
|-
|Bresser Temp/Hydro Sensor||E || || Hideki || 12
|-
|[https://de.hama.com/00104985/hama-aussensensor-ts33c-fuer-wetterstation Hama TS33C]||E || || Hideki || 12
|-
|TFA Temp/Hydro Sensor||E || || Hideki || 12
|-
|Lacrosse TX2/TX3 Sensoren||E || || CUL_TX || 8
|-
|TFA 30320902||E || || SD_WS07 || 7
|-
|Eurochron eas800z||E || || SD_WS07 || 7
|-
|Technoline WS6750/TX70DTH||E || || SD_WS07 || 7
|-
|FreeTec Außenmodul NC-7344||E || || SD_WS07 || 7
|-
|CTW600||E || || SD_WS09 || 9
|-
|CTW602||E ||neuere Version des CTW600 mit 868.35 MHz || SD_WS09 || 9
|-
|WH1080||E || || SD_WS09 || 9
|-
|Visivon remote pt4450||E || || none || 24
|-
|Einhell HS 434/6||E || || none || 21
|-
|Flamingo FA20RF / FA21RF / FA22RF Rauchmelder||E || || FLAMINGO || 13,13.1,13.2
|-
|mumbi m-FS300||E || || none || 26,27
|-
|TFA 30.3200||E || || none || 33
|-
|Livolo||E|| || none || 20
|-
|Smartwares RM174RF/2 (RM174RF-001CPR) 4500177571 ||E [S?]|| IT EV1527; TODO herausfinden: Alarmierung (wie Alarmton getriggered werden kann); Batterieinfo? || IT || 3
|-
|Smartwares SH5-TSO-A||E S|| || IT || ?
|-
|X10 Security Devices||E|| || || 39
|-
|[[Somfy_via_SIGNALduino|Somfy RTS]]||E S|| || SOMFY || 43
|}
Bei einigen Intertechno-Funksteckdosen (Brennenstuhl) kann es zu Empfangsproblemen kommen. Hier muss die Taktrate, mit der gesendet wird, angepasst werden. Dazu muss für ''Funksteckdose'' (also sauber per-Client-Instanz-spezifisch, NICHT SIGNALduino-Transceiver-global) das Attribut
:<code>attr <Funksteckdose> ITclock 300</code>
gesetzt werden, der Standardwert ist 250.

==== Mein Gerät wird in FHEM nicht erkannt ====
1. Prüfen, ob vom Sensor die Signaldaten (verbose >=4) erkannt werden. Sobald ihr die empfangenen Signaldaten im Logfile zuordnen könnt, geht es weiter mit:

2. Eröffnet ein Thema unter [https://github.com/RFD-FHEM/RFFHEM/issues/new?template=sensor---device-feature.md github]:<syntaxhighlight lang="md">
## Specifications for new sensor / switch / or other device ...

- manufacturer:
- model name:
- pictures of the device / the board (very helpful)

## Specifications

- Microcontroller:
- Version (Firmware):


- Versionmodul (FHEM Module):

</syntaxhighlight>3. Auszug aus dem Logfile, welches zum Gerät gehört.
:''Alles was ihr sonst noch über das Gerät und die übertragenen Daten wisst.''

Im Forum solltet ihr solche Fragen besser nicht posten, wenn das Gerät noch nicht unterstützt wird, dazu ist Github besser geeignet. Inzwischen wurde im Wiki eine eigene Seite eröffnet, die sich mit der Erkennung unbekannter Protokolle beschäftigt: [[Unbekannte_Funkprotokolle#Ansatz_1_-_Versuchen|Unbekannte_Funkprotokolle]].

==== Es wird ein Protokoll erkannt, Autocreate legt aber kein device an ====
Im SIGNALduino sind >70 Protokolle implementiert. Jedoch gibt es nicht immer ein logisches Module, welche diese Protokolle verarbeiten.
Teilweise ist das auch nicht zwingend notwendig, um seine Anforderungen zu erfüllen. Insbesondere für Schalter bzw. Sensoren, die nur zwei Zustände kennen, geht es meist ohne Modul und automatisch angelegtem Gerät.

Nehmen wir an, wir haben einen Schalter. Dieser kann einen oder zwei Zustände senden.
Im FHEM Log (und, insbesondere, im FHEMWEB Event Monitor) tauchen Meldungen ähnlich dieser auf

<code>
2015.11.15 15:52:23 4: SIGNALduino_unknown incomming msg: u85#FF8081
</code>

Wir können mit Hilfe des Modules DOIF auf diese Nachricht eine Aktion ausführen:

Entweder, wenn wir den Inhalt der Nachricht nur zu Teilen wissen, da er sich ändert:

<code>
define mydoif DOIF ([sduino:&DMSG] =~ "u85#FF8081") (set Lamp on)
attr mydoif do always
</code>

Oder, wenn wir den Inhalt exakt kennen, dann auch als Vergleichsstring

<code>
define mydoif DOIF ([sduino:&DMSG] eq "u85#FF8081") (set relais on)
attr mydoif do always
</code>

Der Teil u85#FF8081 muss individuell angepasst werden, der Name eures SIGNALduino möglicherweise auch.

Als Alternative zu DOIF hier ein regex-verwendendes notify-Beispiel für einen Sender, der meint, zwei Codes alternierend senden zu müssen:

<code>
define n_sender_trigger notify sduino:UNKNOWNCODE.*u41#(13B72253|163873B3) { my_sender_trigger_indicate();; }
</code>

Selbstverfreilich muss in diesem Moment auch eine sub my_sender_trigger_indicate() definiert werden (z.B. in FHEM/99_myUtils.pm), die dort z.B. als Test eine Log-Ausgabe (Log3()) machen kann.

=== Das Logfile ===
Im Logfile ab [[Verbose]] 4 tauchen diverse Meldungen auf, deren Bedeutung kurz erläutert wird (verbose 3 unterdrückt diese Meldungen).

UPDATE: der folgende Bereich ist von einem weniger erfahrenen Zeitgenossen früher nach Kräften erweitert/geschrieben worden. Mittlerweile existiert aber ein neuer Inhalt [[Unbekannte_Funkprotokolle]] (siehe auch Erwähnung weiter oben), der als sehr gut beschrieben und unvergleichlich detailreicher bezeichnet werden muss ("endlich gibt es sowas!"). Der Bereich hier dürfte somit zwar für grundlegende Verdeutlichungen noch recht sinnvoll sein, der Inhalt sollte allerdings evt. in eine konsistente Dokumentation überarbeitet (verlagert/dedupliziert/reduziert) werden.

Die Protokolle (von der SIGNALDuino-Firmware gesendete Signal-Beschreibungs-Strings) können wie folgt unterschieden werden:

*MS - Nachricht mit Sync Puls: Hierzu ein Beispiel
:<code>MS;P0=-108;P1=395;P2=-1033;P3=-547;P4=-19932;P5=-8916;P6=1368;D=151313131312131313131313131313131312121212121313131313131312131212132;CP=1;SP=5;</code> P0-P6 sind die Signalpegel (Dauer und positiv/negativ). Hinter D= befindet sich die Abfolge der Signale. Die ersten beiden Ziffern 15 in D sind wie folgt zu lesen. Zuerst wurde ein Signal "1" also P1 mit 395 Mikrosekunden high (die Zeitdauer ergibt sich aufgrund der Mitteilung "P1=395") und anschließend ein Signal "5" also P5 mit 8916 Mikrosekunden low (die Zeitdauer ergibt sich aufgrund der Mitteilung "P5=-8916") gemessen. CP=1 ist die Referenz auf den Takt des Signales - der Basistakt ist in diesem Fall ~395 Mikrosekunden. SP=5 gibt die Referenz zum Syncpuls an, der das gesamte Signal einleitet. Welche Signalfolge nun eine binäre 1 bzw. 0 bedeutet, wird im SIGNALduino über die integrierte Protokoll Liste realisiert.

*MC - Nachricht vom Typ Manchester: Manchesterkodierte Signale können bereits sehr einfach im Arduino in eine Binärform umgewandelt werden. Es wird hier nach IEEE 802.3 umgewandelt. In Manchester Signalen gibt es lange und kurze Pulse. Deren Durchschnittswert wird mit LL (long low), LH (long high), SL (short low) und SH (short high) übermittelt. Zusätzlich, um das Protokoll schneller erkennen zu können, wird die Taktfrequenz mit übermittelt (C=429 Mikrosekunden). Die Daten befinden sich hinter D= und werden in HEX Form übergeben.
:<code>MC;LL=-1066;LH=904;SL=-562;SH=385;D=332B4B4D54D5554B552CD2D554B2B5354A;C=429;</code>

*MU - Message unsynced: Diese Art von Nachrichten sind nicht nach Manchester codiert und haben auch keinen erkennbaren Sync / Clock Signalpegel am Start der Nachricht. Bei diesen Nachrichtentypen ist es, im Vergleich zu den anderen, am wahrscheinlichsten, dass das übermittelte Signal unvollständig oder überhaupt kein Signal ist. Wie bei MS sind P0-P6 die Signalpegel und in D= wird die Abfolge der Signalpegel referenziert. CP=2 gibt auch hier die Referenz zum Takt an, allerdings muss dieser nicht korrekt erkannt worden sein.
:<code>MU;P0=1372;P1=-580;P2=362;P3=-1047;D=01212321212321212121212121212123212123212321232121212121212321;CP=2;</code>

Es erscheinen viele Meldungen dieser Art:

<pre>
Fingerprint for MU Protocol id xxxx -> yyy matches, trying to demodulate
sduino: Starting demodulation at Position 1
Fingerprint for MU Protocol id 28 -> IC Ledspot matches, trying to demodulate
sduino: Starting demodulation at Position 1
Fingerprint for MU Protocol id 29 -> HT12e remote matches, trying to demodulate
</pre>

Dies sind nun Bemühungen, anhand der von der SIGNALDuino-Firmware gelieferten rohen aber detaillierten Signal-Strings eine Vor-Analyse / Fingerprinting vorzunehmen.
Man könnte nun z.B. bei solchen Fingerprinting-Analysen erkennen:
* dass der Basis-Takt-Wert innerhalb eines charakteristischen Zeit-Bereichs liegt
* dass die Anzahl der Sync-Pulse eine präzise Zahl ist
* dass Längen erkannter Puls-Typen innerhalb eines Bereichs liegen

Mittels solcher Untersuchungen kann man also final hoffentlich hinreichend plausibel feststellen, "dass diese Aktivitäten offensichtlich(?) zu einer Funk-Komponente Rauchmelder von Hersteller XYZ gehören müssen, und man somit weiterleiten muss an ein (möglicherweise bereits existierendes) Userdaten-Dekodier-Modul für diese Herstellerkomponente".

Bei einer dann erfolgenden Demodulation des noch rohen SIGNALDuino-Strings könnte man z.B. (hoffentlich richtigerweise) annehmen, dass eine Signalpegel-Typ-Folge "13" eine binäre 1 bedeuten soll, während eine Folge "12" eine binäre 0 bedeuten soll. Man erhält aus dem Gesamt-Puls-String also nach vollständiger Demodulation eine Abfolge von vielen 0/1 Bits, die insgesamt ein Datenwort darstellen, mit einer gewissen Länge von NN bits (diese Längen-Angabe könnte übrigens - neben Namenssuche nach Hersteller oder Produkt etc. - ein wichtiges Such-Merkmal sein, ob andere Frameworks tatsächlich bereits wissen, wie Daten dieser Funk-Komponente zu dekodieren sind!). Dieses demodulierte Datenwort ist nun das finale Datenwort, welches einen Container für die Funk-Komponenten-Informationen darstellt (in diesem Container also beispielsweise enthalten: Temperatur, Feuchte, Akku-Status, ID, Alarm, ... - zumindest wenn nicht dummerweise der ganze Container erst einmal CRC- oder Crypto-verschlüsselt ist...).

Man muss an dieser Stelle unbedingt sagen, dass dieses Userdaten-Datenwort (einer bestimmten Hersteller-Funk-Komponente!) natürlich bei ''jeglichen'' Transceiver-Systemen ''immer'' gleich erkannt werden ''muss'' - an dieser Stelle ist also ganz klar, dass diese Daten an ''allgemeine'' FHEM-Module weitergeleitet (Dispatched) werden müssen, die nach Übernahme von Daten von ''jeglichen'' Transceiver-Systemen diese Daten immer auf die gleiche Weise ('''''generisch/zentral''''') für die jeweilige Hersteller-Funk-Komponente erledigen.

'''Die Abfolge ist also ganz klar:'''
Funk-Aktivität --> Transceiver-Gerät/Firmware (SIGNALDuino) --> maximal detailreich beschreibender Rx-Analyse-Output-String --> Fingerprinting-Grobzuordnung des (SIGNALDuino-Firmware-)Outputs (durch 00_SIGNALduino.pm) auf gerätespezifisches Verhalten --> ''generische/zentrale'' Dekodierung des gerätespezifischen Protokoll-Datenworts, in zentralen Grundsatz-Modulen wie z.B. <code>14_SD_WS.pm</code>).

Und wenn dann bei einer solchen Schritte-Abfolge irgendetwas noch fehlen/unpassend sein sollte, dann muss eben entsprechendes Development an gewissen Stellen erfolgen ;-)

====Minimieren (whitelist/blacklist) von unerwünschter Kommunikations-Aktivität/Einträgen====

"Unknown Code" bedeutet, dass der SIGNALduino Signaldaten empfangen und diese binär interpretiert hat. Diese Meldung soll uns nun aber mitteilen, dass es dann nicht weiter verarbeitet werden kann, da kein Modul existiert (oder kein Weiterleitungs-Dispatch zu einem bereits existierenden), welches diese Daten jetzt in ihre Bedeutung umwandeln kann.
:<code>sduino: Unknown code u1FFFFF0, help me!</code>

Außerdem kommt es gehäuft zu Logmeldungen und auch Events in ähnlicher Form:
:<code>SIGNALduino_unknown incomming msg: u85#FF8081</code>

Mittlerweile sind über 50 Protokolle für den SIGNALduino definiert. Dadurch kommt es vor, dass sich ein Signal mit mehr als einem Protokoll demodulieren lässt. Meist führt dies dann zu zusätzlichen "Unknown code"-Einträgen.

Derartige Einträge können mit dem Attribut WhitelistID minimiert werden. Dabei werden die Geräte, die nach Daten-Empfang tatsächlich verarbeitet werden sollen (also welche Protokolle vom FHEM Modul berücksichtigt werden), mit ihrer Protokollnummer in die WhitelistID aufgenommen.
Für Protokolle, die nicht berücksichtigt werden, gibt es weder Logeinträge noch Events. Diese werden im Programmablauf nicht berücksichtigt. Das spart zum einen Ressourcen und trägt auch zur Übersichtlichkeit bei.
Die Protokollnummer kann Tabelle [[#Unterst.C3.BCtzte_Ger.C3.A4te|Unterstützte Geräte]] entnommen werden (hilfreich ist es auch, wenn in den verwendeten Geräten im Internal <gerätename>_DMSG nachgesehen wird). So bedeutet beispielsweise ein Eintrag der Form <code>W50#FF553335FFBC</code> dass dann das Protokoll #50 in die Whitelist aufzunehmen wäre (<code>attr sduino whitelist_IDs 50</code>).
{{Randnotiz|RNTyp=r|RNText=Achtung Schreibweise: Dokumentation oft als WhitelistID o.ä., aber Name ist whitelist_IDs!!
}}
Die Angabe erfolgt durch Komma getrennt: z.B.:
:<code>1,2,5,10</code>

=== Senden mit dem SIGNALduino ===
Der SIGNALduino kann etwas "raw senden", indem ihm das SIGNAL so übermittelt wird, wie er es moduliert. Hierzu muss der Befehl wie folgt eingegeben werden:

<code>
set sduino sendMsg P3#00111010#R4
</code>

Dieser Befehl moduliert die Bitfolge 00111010 mittels Protokoll #3 und wiederholt die Nachricht 4x.
Die Protokoll Nummer kann aus einer empfangenen Nachricht extrahiert werden. Ebenso die Bits.
<code>
sduino: extracted data 00111010 (bin)
sduino: Found Protocol id 3
</code>

Alternativ kann das Signal auch in einer "rohform" angegeben werden. Dies ist manchmal in speziellen Fällen notwendig:
<code>
set sduino raw SR;;R=3;;P0=4742;;P1=-1554;;P2=286;;P3=-786;;P4=649;;P5=-420;;D=0123234545234545452323232323454523234523454523232345454523232323452345234523452345;;
</code>

R=3 bedeutet, das Signal wird 3x gesendet.
Die Übertragung besteht aus den in D angegeben Pulsen, welche in P0-P5 definiert werden.
Die Daten kann man aus einer empfangenen MS oder MU Nachricht extrahieren.

Alternativ kann ab Version 3.2 auch eine vereinfachte Form eingegeben werden.

====Fehlersuche====
(Zielgerät reagiert nicht, etc.)

* Nachrichtenwiederholungsanzahl muss evt. für manche Geräte entsprechend groß eingestellt sein
{{Randnotiz|RNTyp=r|RNText=VORSICHT blöder Schreibweisen-Mismatch ITClock vs. ITclock!!}}
* Sende-Takt-Wert (Clock) passt evt. nicht ganz, siehe z.B. Thread-Antwort {{Link2Forum|Topic=58397|Message=775434|LinkText=Signalduino Version 3.3.1}}, wo für IT-Geräte ein Attribut anhand der CP= des Empfangsdaten-Logs modifiziert wird. ACHTUNG: dies kann entweder global das Internal-Attribut ITClock eines SIGNALduino-Transceiver-Devices sein, oder (viel besser da korrekt geräte-instanz-spezifische Konfiguration) das ITclock eines IT-Client-Devices.

== Fehlerbehandlung ==
Der SIGNALduino kann mit folgendem Befehl auf Werkseinstellungen zurückgesetzt werden:
:<code>set raw e</code>
Ob ein solcher Reset nötig ist, erkennt man an dem Inhalt vom Reading <code>cc1101_config</code>, dort unsinnige Werte angezeigt werden oder dem Reading <code>config</code> welches durch den Befehl "get config" aktualisiert wird, was im Standard auf "MS=1;MU=1;MC=1" entspricht.

In der Firmware sind die diverse Befehle eingebaut, welche über einen <code>set raw</code> Befehl im Modul direkt ausgeführt werden können. Sofern möglich, sollten die Abfrage von Werten aus dem Modul allerdings mit den dafür vorgesehenen Kommandos erfolgen, da die Rückmeldungen des <code>set raw</code> Befehls nur im Logfile ab Verbose 4 erscheinen. Die Befehle sind nützlich, wenn direkt auf den Microcontroller zugegriffen wird:

:<code>C<reg></code> <reg> is a (two digit) hex number: return the value of the cc1101 register. <reg>=99 dumps the first 48 registers. Example: <code>set raw C35</code> führt ab Verbose 4 zu einer Logausgabe folgender Art <code>Read, msg: C35 = 0D</code>
:<code>e</code> EEPROM / factory reset. resets all eeprom values without reboot
:<code>W<AA><XX></code> Write eeprom (schreibt einen Wert ins EEPROM und ins CC1101 Register. Die eeprom Adresse hat einen Offset von 2. z.B W041D schreibt 1D ins Register 2 des CC1101)

Die Sendeleistung lässt sich mit
:<code>get sduino ccpatable</code>

prüfen, wobei die Rückmeldung wie folgt zu lesen ist:
"-10_dBm" => '34',
"-5_dBm" => '68',
"0_dBm" => '60',
"5_dBm" => '84',
"7_dBm" => 'C8',
"10_dBm" => 'C0'
Dabei wird die Sendeleistung dauerhaft mit dem Befehl
:<code>set sduino cc1101_patable <value></code>
hochgeschaltet (<value> durch den Wert ersetzen).

Weitere Firmware-Befehle sind im Thread-Beitrag {{Link2Forum|Topic=58396|Message=497921}} zu finden.

== Foren Links ==
* {{Link2Forum|Topic=38402|LinkText=Forenthread - Ankündigung}}
* {{Link2Forum|Topic=58396|LinkText=SIGNALDuino Empfänger Firm- und Hardware}}
* {{Link2Forum|Topic=82379|Message=1033374|LinkText=SIGNALDuino Schaltplan}}
* {{Link2Forum|Topic=58397|LinkText=Signalduino Entwicklung Version 3.3.1 }}
* [http://www.rflink.nl/blog2/wiring Beschreibung zu diversen Empfängern und Verbesserung der Empfangsleistung]
* [[SIGNALduino in die Arduino Entwicklungsumgebung einbinden]]
* [[Somfy via SIGNALduino]]

[[Kategorie:Interfaces]]
[[Kategorie:Arduino]]
[[Kategorie:433MHz]]
[[Kategorie:868MHz]]

FTUI Widget Volume

2020-04-25T19:36:00Z

Kaihs: /* Farbauswahl für Beleuchtung */

Das [[{{PAGENAME}}|Volume Widget]] ist ein Widget für [[FHEM Tablet UI]], das eine Einstellscheibe zur Änderung eines einzelnen Wertes zur Verfügung stellt.

<gallery>
File:FTUI_Widget_Volume_01.png
File:FTUI_widget_volume-rgb.png
</gallery>

==Attribute==
Für das Volume-Widget gelten alle Attribute des [[FTUI Widget Knob|Knob-Widgets]]. Und zusätzlich die folgenden:
{| class="wikitable"
!Attribut
!Beschreibung
!Standard-Wert
!Beispiel
|-
|'''data-get'''||Name des Readings, das den darzustellenden Wert enthält||STATE||data-get="volume"
|-
|'''data-set'''||Name des Readings, dessen Wert geändert werden soll||||data-set="volume"
|-
|'''data-cmd'''||Name des Befehls, mit dem das Reading geändert wird (z.B. setstate, set, setreading, trigger)||set||
|-
|'''data-get-value'''||[[Regulärer Ausdruck|RegEx]] oder Position des Wertes in einer leerzeichen-getrennten Textzeile, mit der der Wert erhalten werden kann||-1 -> alles anzeigen||
|-
|'''data-set-value'''||Format des Wertes, wie er an FHEM gesendet werden soll||$v (nur der Wert)||
|-
|'''data-min'''||Mindestwert, der gesetzt werden kann||0||data-min="10"
|-
|'''data-max'''||Maximalwert, der gesetzt werden kann||70||data-max="100"
|-
|'''data-tickstep'''||Abstand zwischen den einzelnen Schritten||4/20||data-tickstep="1"
|-
|'''data-unit'''||Einheit zum gewünschten Wert hinzufügen||||<nowiki>data-unit="&deg"</nowiki>
|}

==CSS Klassen==
{|class="wikitable"
{{FTUI Klasse|mini}}{{FTUI Klasse|small}}{{FTUI Klasse|big}}{{FTUI Klasse|bigger}}{{FTUI Klasse|hue-tick}}{{FTUI Klasse|hue-front}}{{FTUI Klasse|hue-back}}{{FTUI Klasse|dim-tick}}{{FTUI Klasse|dim-front}}{{FTUI Klasse|dim-back}}{{FTUI Klasse|readonly}}
|}

==Beispiele==
===Lautstärke===
<syntaxhighlight lang="html">
<div data-type="volume"
data-device="AVReceiver"
data-get="volume"
data-set="volume"></div>
</syntaxhighlight>
[[Datei:FTUI Widget Volume 01.png]]

===Farbauswahl für Beleuchtung===
<syntaxhighlight lang="html">
<div data-type="volume"
data-device="WZ.Deckenlampe"
data-get="hue"
data-set="hue"
data-min="0"
data-max="65535"
class="hue-tick hue-front small top-space-2x">
</div>
</syntaxhighlight>
[[Datei:FTUI_widget_volume-rgb.png]]

[[Kategorie:FHEM Tablet UI|Volume]]

FHEM Tablet UI

2020-04-14T19:47:30Z

Kaihs: /* Templates */

{{Infobox Modul
|ModPurpose=Oberfläche für FHEM
|ModType=x
|ModFTopic=34233
|ModForumArea=TabletUI
|ModTechName=n.a.
|ModOwner=setstate ({{Link2FU|7023|Forum}})
}}
[[FHEM Tablet UI]] (FTUI) ist ein leichtgewichtiges aber funktionsreiches Frontend-Framework zum Steuern und Überwachen von in FHEM integrierten Geräten. Es basiert auf HTML/CSS/JavaScript und stellt somit keine zusätzlichen Anforderungen an den FHEM-Server.

Mit Hilfe zahlreicher Widgets, die sehr leicht mit HTML Code konfiguriert werden können, ist es möglich, innerhalb kurzer Zeit ein den eigenen Wünschen entsprechendes User-Interface aufzubauen.

Für den Betrieb ist nur eine FHEM-Installation mit [[HTTPSRV|HTTPSRV-Modul]] sowie ein gängiger Webbrowser notwendig.

Mit wenigen Anpassungen ist es auch möglich, das UI auf anderen Webservern (Apache, u.a.) zu betreiben. Somit können FHEM und FHEM Tablet UI auch auf getrennten Systemen ausgeführt werden.

[[File:tablet_ui.png|thumb|500px|center|Beispiel für ein mit [[FHEM Tablet UI]] erstelltes User-Interface]]

{{Todo|Design-Möglichkeiten erklären, Navigationsmethoden ausformulieren}}

== Installation ==
Die Installation von FHEM Tablet UI erzeugt keinen großen Aufwand und besteht im Großen und Ganzen aus drei Schritten:
*Dateien aus dem GitHub-Repository herunterladen
*FHEM konfigurieren ([[HTTPSRV]]-Device erstellen, [[FHEMWEB]]-Attribut longpoll einstellen)
*Eine Beispieldatei anlegen

{{Hinweis|Diese Anleitung geht davon aus, dass FHEM unter Debian nach der Anleitung [https://debian.fhem.de Stable build using apt] installiert wurde.
Ist dies nicht der Fall, muss der Pfad '''/opt/fhem''' dementsprechend angepasst werden.}}

'''1.''' Zuerst müssen alle Dateien von FHEM Tablet UI in das FHEM-Verzeichnis '''/opt/fhem/www''' kopiert werden. Das geht mit folgendem '''update'''-Befehl über die FHEM-Befehlszeile.
:<code>update all https://raw.githubusercontent.com/knowthelist/fhem-tablet-ui/master/controls_fhemtabletui.txt</code>

:[[Datei:FTUI_Installation_01.png|thumb|none|Schritt 1: Dateien kopieren]]

'''2.''' Anschließend ist ein neues [[HTTPSRV]]-Device in FHEM anzulegen, welches auf den Ordner mit den gerade heruntergeladenen Dateien verweist.
:<code>define TABLETUI HTTPSRV ftui/ ./www/tablet/ Tablet-UI</code>

:[[Datei:FTUI_Installation_02.png|thumb|none|Schritt 2: HTTPSRV-Device anlegen]]

{{Hinweis|Dieser Schritt kann ausgelassen werden, wenn die Funktionalitäten von [[FHEMWEB]] ausreichend sind. Dann muss FTUI aber in weiterer Folge unter der URL '''<nowiki>http(s)://<fhem-server>:8083/fhem/tablet/index.html</nowiki>''' aufgerufen werden und es wird kein Link auf FTUI in der FHEM GUI erstellt. Vorteil ist aber, dass das FHEMWEB-Caching verwendet werden kann. Siehe dieser {{Link2Forum|Topic=86362|Message=788258}}.}}

'''3.''' Damit FHEM Tablet UI mit FHEM kommunizieren kann, ist noch die '''longpoll'''-Einstellung im [[FHEMWEB]] Device festzulegen.

:<code>attr WEB longpoll websocket</code>
:bzw. bei Problemen mit ''websocket''
:<code>attr WEB longpoll 1</code>

:[[Datei:FTUI_Installation_03.png|thumb|none|Schritt 3: longpoll einstellen]]

'''4.''' Weil FTUI noch nichts anzuzeigen hat, wird die Datei '''/opt/fhem/www/tablet/index-example.html''' nach '''/opt/fhem/www/tablet/index.html''' kopiert.
:<code>sudo cp -a /opt/fhem/www/tablet/index-example.html /opt/fhem/www/tablet/index.html</code>

:[[Datei:FTUI_Installation_04.png|thumb|none|Schritt 4: index.html erstellen]]

'''5.''' Abschließend muss FHEM noch '''neu gestartet''' werden (''shutdown restart'') da das Attribut '''longpoll''' geändert wurde.

Somit ist FHEM Tablet UI bereit zur Verwendung und kann durch Aufruf der URL '''<nowiki>http://<fhem-server>:8083/fhem/ftui/</nowiki>''' oder den Link im FHEM-Menü geöffnet werden

== Update ==
Ein Update von FTUI kann ebenfalls über die FHEM-Kommandozeile erfolgen.

'''1.''' Prüfen der Änderungen seit dem letzten Download/Update durch Eingabe von:
:<code><nowiki>update check https://raw.githubusercontent.com/knowthelist/fhem-tablet-ui/master/controls_fhemtabletui.txt</nowiki></code>

'''2.''' Update der geänderten Dateien durch Eingabe von:
:<code><nowiki>update all https://raw.githubusercontent.com/knowthelist/fhem-tablet-ui/master/controls_fhemtabletui.txt</nowiki></code>

Eine weitere Option ist das Hinzufügen des FTUI-Git-Repositories zum allgemeinem Update-Vorgang von FHEM. Dabei wird dann bei einem FHEM-Update auch gleich FHEM Tablet UI aktualisiert, bzw. die Änderungen angezeigt.
:<code><nowiki>update add https://raw.githubusercontent.com/knowthelist/fhem-tablet-ui/master/controls_fhemtabletui.txt</nowiki></code>

Beachte: Das Ergebnis des o.g. Befehls wird in FHEM/controls.txt eingetragen, siehe auch [[Update#update_add]]

== Konfiguration ==
===DOCTYPE===
In allen HTML-Dateien, die im Browser geladen werden und das typische HTML-Gerüst besitzen (also alle Hauptseiten, jedoch keine Template-Dateien), sollte eine ''Document Type Declaration'' (DTDT) eingefügt werden. Mit ihr wird festgelegt, welche ''Document Type Definition'' hier verwendet wird (das kommt aus der Metasprache XML), konkret also, in welcher Version der nachfolgende HTML-Code vom Browser interpretiert werden soll. Lässt man die DTDT weg, oder definiert sie auf verschiedenen Seiten unterschiedlich, kann ein und der selbe HTML-Code zu unterschiedlichen Darstellungen führen. Die DTDT erfolgt immer auf der ersten Zeile, noch vor dem <code><html></code>-Tag. Nachfolgend wird HTML5 verwendet.

<syntaxhighlight lang="html">
<!DOCTYPE html>
<html>
<head>...</head>
<body>...</body>
</html>
</syntaxhighlight>

===META-Parameter===
Das Tablet UI lässt sich über die META-Parameter konfigurieren. Diese Parameter sind in jeder '''.html''' Datei (z.B. index.html) im Abschnitt '''<head>''' einzutragen. Ausgenommen davon sind Dateien, die als Template, Pagebutton-Zielseiten oder ähnliches eingebunden werden.

Die Parameter sind immer nach diesem Schema aufgebaut:
<meta name="[Parameter-Name]" content="[Parameter-Wert]">

===Verbindung zu FHEM===
{| class="wikitable"
|-
!Parameter-Name!!Standard-Wert!!Mögliche Werte!!Beschreibung
|-
|web_device||WEB||String||FHEM-Device, welches für das Polling verwendet wird
|-
|longpoll||1||0, 1||
'''0''': Longpoll deaktiviert; alle 30s ein Shortpoll (Neuladen der gesamten Statusänderungen)

'''1''': Longpoll aktiv; geänderte Stati werden sofort aktualisiert, zusätzlich werden alle 15min die gesamten Statusänderungen geladen.
|-
|longpoll_type||websocket||websocket, ajax, 0||
'''websocket''': Für die Aktualisierung der Daten wird das Websocket-Protokoll verwendet. Werden vom Browser keine Websockets unterstützt, gibt es einen automatischen Fallback auf Ajax.

'''ajax''': Ajax wird für die Aktualisierung verwendet.

'''0''': Longpoll deaktiviert, Shortpoll wird verwendet.
|-
|longpoll_filter||.*||RegEx||Event-Filter. Kann verwendet werden, wenn z.B. Devices, die in FTUI angezeigt werden, in einem eigenen FHEM-Room sind.
|-
|longpoll_maxage||240||Integer||Kommen in diesem Zeitraum (Sekunden) keine Longpoll-Events bei FTUI an, wird die Verbindung als "disconnected" angesehen und ein neuer Verbindungsversuch wird gestartet.
|-
|shortpoll_interval||900||Integer||Zeitraum in Sekunden, nach dem ein vollständiger Refresh stattfindet
|-
|shortpoll_only_interval||30||Integer||Zeitraum in Sekunden, nach dem ein vollständiger Refresh stattfindet, sollte Longpoll deaktiviert sein
|-
|fhemweb_url||/fhem/||Integer||URL zu FHEM. Wird benötigt wenn FTUI auf einem anderen als dem FHEM Server läuft oder nicht im Standard-Pfad installiert ist.
Hinweis: Wenn FHEM auf einem anderem Server/Domain läuft muss man das "CORS" Attribut im FHEMWEB Modul (s.o.) auf 1 setzen, sonst bekommt man Cross Origin Fehler.
|}

===Funktionalität===
{| class="wikitable"
|-
!Parameter-Name!!Standard-Wert!!Mögliche Werte!!Beschreibung
|-
|debug||0||0 - 5||Log-Level
|-
|toast||5||Integer||Anzahl an gleichzeitig angezeigten Toast-Nachrichten. Um keine anzuzeigen, ist der Wert auf 0 zu setzen.
|-
|toast_position||bottom-left||||Position im Browserfenster, wo die Toast-Nachrichten angezeigt werden.
|-
|lang||de||de||Sprache der Oberfläche (für z.B. Datums-/Zeitfunktionen)
|-
|username||||String||Benutzername für eine Basic-Authentifierung *
|-
|password||||String||Passwort für eine Basic-Authentifizierung *
|}
'''*''' Derzeit wird die Basic-Authentifizierung in Kombination mit WebSockets nicht unterstützt. Die Verwendung von '''longpoll=1''' (ajax) ist daher notwendig.

===Toast-Nachrichten===
[[Datei:Ftui_toast.png|thumb|Toast-Nachrichten]]
Tablet-UI liefert Informationen darüber, was im Moment gerade passiert. Das geschieht über Toast-Nachrichten, die in der Standardeinstellung unten links im Browser auftauchen.

Wird beispielsweise ein Gerät eingeschaltet, so erscheint eine kleine Nachricht mit dem abgesetzten Befehl. Auch Fehlermeldungen und Statusinformationen werden angezeigt. Ob überhaupt und was konkret angezeigt wird, richtet sich nach dem eingestellten Debug-Level (siehe oben). Beim Debug-Level 5 werden alle Nachrichten angezeigt, bei 0 keine.

Die Position der Toast-Nachrichten kann über den Meta-Tag <code>meta name='toast_position'</code> festgelegt werden. Für oben-mittig müsste folgender Code eingefügt werden:
<pre><meta name='toast_position' content='top-center'></pre>

Möglich sind folgende Positionen:
* <code>top-left</code>
* <code>top-right</code>
* <code>bottom-left</code>
* <code>bottom-right</code>
* <code>top-center</code>
* <code>bottom-center</code>
* <code>mid-center</code>

Die maximale Anzahl an Nachrichten, die gleichzeitig angezeigt werden können, lässt sich mit <code>meta name='toast'</code> Sind maximal 2 Nachrichten gewünscht, muss folgender Meta-Tag gesetzt werden:
<pre><meta name='toast' content='2'></pre>

==Navigationsmethoden==
{{Todo|Dieser Abschnitt dient derzeit lediglich als Sammlung von Stichpunkten und muss vollständig überarbeitet werden.}}

'''Unterschied zwischen Pagetab und Pagebutton:

'''Pagetab:''' Ganze Seite austauschen -> Menü muss auf jede Seite
[[FTUI_Widget_Pagetab]]

'''Pagebutton:''' Teil der Seite austauschen -> Menü nur in erster Seite
[[FTUI_Widget_Pagebutton]]

'''Pagelink:''' damit kann man beliebige Widgets kapseln und vorhandene Pagebutton-Seiten ansteuern
[[FTUI Widget Link]]

==Gestaltung==
===Layout-Optionen===
* [[FTUI Layout Gridster|Gridster]]
* [[FTUI Layout Flex|Flex]]
* [[FTUI Layout Sheet|Tabelle]]
* [[FTUI Layout Row|Reihen]]

=== Farben ===
Es besteht die Möglichkeit, die Farbwerte in hexadezimaler Form, als RGB-Wert oder mit dem Farbnamen anzugeben. Zum Beispiel:

*HEX: #ADD8E6
*RBG: rgb(173, 216, 230)
*Namen: lightblue

Knallige Farben wie '''<span style="color: #ff0000;">#ff0000</span>''' für Rot oder '''<span style="color: #00ff00;">#00ff00</span>''' für Grün sollten vermieden werden.
Es ist besser unterhalb von #D0 (208) für die Grundfarben zu bleiben.

Empfohlene Farben sind z.B.:

*Orange: <span style="color: #aa6900;">#aa6900</span>
*Rot: <span style="color: #ad3333;">#ad3333</span>
*Grün: <span style="color: #32a054;">#32a054</span>
*Blau: <span style="color: #6699FF;">#6699FF</span>
*Grau: <span style="color: #8C8C8C;">#8C8C8C</span>

Hilfreich bei der Suche nach den Farbwerten ist zum Beispiel der Color-Picker auf dieser Seite: http://www.colorpicker.com. Für die Suche nach Farben, die einen guten Kontrast bilden, diese Webseite: http://vanisoft.pl/~lopuszanski/public/colors/

Im Ordner ''css'' der FTUI Installation finden sich einige vorbereitete Farbschemata. Diese können mit einem zusätzlichen Eintrag im <nowiki><head></nowiki>-Bereich der FTUI-Seite(n) aktiviert werden.

Hier am Beispiel eines blauen Farbschemas:
<syntaxhighlight lang="html">
<html>
<head>
[...]
<link rel="stylesheet" href="/fhem/tablet/css/fhem-blue-ui.css" />
[...]
</head>
</syntaxhighlight>

Diese Schema-Dateien ändern alle Widgets.
<gallery>
File:Theme_default.png|default
File:Theme_blue.png|fhem-blue-ui.css
File:Theme_green.png|fhem-green-ui.css
File:Theme_mobile.png|fhem-mobile-ui.css
File:Theme_darkblue.png|fhem-darkblue-ui.css
File:Theme_darkgreen.png|fhem-darkgreen-ui.css
</gallery>

Einzelne Widgets können durch Hinzufügen der jeweiligen [[#CSS-Klassen|CSS-Klasse]] geändert werden.

===CSS-Styles===
Das Layout und das Aussehen des UI kann durch diverse vorgegebene CSS-Klassen beeinflusst werden. Die verfügbaren Klassen sind im Abschnitt [[#CSS-Klassen|CSS-Klassen]] aufgeführt.

Soll das Aussehen des UI durch eigene CSS-Klassen oder durch Überschreiben der vorhandenen verändert werden, kann eine eigene CSS-Datei erstellt werden, die dann bei einem eventuellen Update von FTUI nicht überschrieben wird. Diese Datei muss den Dateinamen '''fhem-tablet-ui-user.css''' haben und im Ordner '''/fhem/tablet/css''' abgelegt werden. Sie wird dann beim Aufruf von FTUI automatisch mitgeladen.

=== CSS-Klassen ===
Nicht alle Widgets unterstützen alle hier angegebenen Klassen. Welche genau unterstützt werden, kann auf der jeweiligen Widget-Seite nachgelesen werden.

{|class="wikitable mw-collapsible mw-collapsed" style="width: 100%;"
!colspan="2" style="text-align: left;"|sheet/row/cell-Layout
|-
!class="mw-collapsible-content"|Klasse!!Beschreibung
{{FTUI Klasse|sheet}}{{FTUI Klasse|row}}{{FTUI Klasse|cell}}{{FTUI Klasse|cell-1-x}}{{FTUI Klasse|cell-x}}{{FTUI Klasse|left-align}}{{FTUI Klasse|right-align}}{{FTUI Klasse|bottom-align}}{{FTUI Klasse|top-align}}{{FTUI Klasse|center-align}}
|}

{|class="wikitable mw-collapsible mw-collapsed" style="width: 100%;"
!colspan="2" style="text-align: left;"|row/col-Layout
|-
!class="mw-collapsible-content"|Klasse!!Beschreibung
{{FTUI Klasse|col}}{{FTUI Klasse|col-1-x}}{{FTUI Klasse|col-x}}
|}

{|class="wikitable mw-collapsible mw-collapsed" style="width: 100%;"
!colspan="2" style="text-align: left;"|hbox/vbox-Layout
|-
!class="mw-collapsible-content"|Klasse!!Beschreibung
{{FTUI Klasse|vbox}}{{FTUI Klasse|hbox}}{{FTUI Klasse|card}}{{FTUI Klasse|phone-width}}{{FTUI Klasse|full-height}}{{FTUI Klasse|full-width}}{{FTUI Klasse|grow-0}}{{FTUI Klasse|grow-1}}{{FTUI Klasse|grow-2}}{{FTUI Klasse|grow-x}}{{FTUI Klasse|items-top}}{{FTUI Klasse|items-center}}{{FTUI Klasse|items-bottom}}{{FTUI Klasse|items-space-between}}{{FTUI Klasse|items-space-around}}
|}

{|class="wikitable mw-collapsible mw-collapsed" style="width: 100%;"
!colspan="2" style="text-align: left;"|Generelle Klassen für die Positionierung
|-
!class="mw-collapsible-content"|Klasse!!Beschreibung
{{FTUI Klasse|inline}}{{FTUI Klasse|newline}}{{FTUI Klasse|top-space}}{{FTUI Klasse|top-space-2x}}{{FTUI Klasse|top-space-3x}}{{FTUI Klasse|left-space}}{{FTUI Klasse|left-space-2x}}{{FTUI Klasse|left-space-3x}}{{FTUI Klasse|right-space}}{{FTUI Klasse|right-space-2x}}{{FTUI Klasse|right-space-3x}}{{FTUI Klasse|top-narrow}}{{FTUI Klasse|top-narrow-2x}}{{FTUI Klasse|top-narrow-10}}{{FTUI Klasse|left-narrow}}{{FTUI Klasse|left-narrow-2x}}{{FTUI Klasse|left-narrow-3x}}{{FTUI Klasse|right-narrow}}{{FTUI Klasse|right-narrow-2x}}{{FTUI Klasse|right-narrow-3x}}{{FTUI Klasse|centered}}{{FTUI Klasse|wider}}{{FTUI Klasse|narrow}}{{FTUI Klasse|fullsize}}{{FTUI Klasse|compressed}}{{FTUI Klasse|height-narrow}}{{FTUI Klasse|w1x}}{{FTUI Klasse|w2x}}{{FTUI Klasse|w3x}}{{FTUI Klasse|maxw40}}{{FTUI Klasse|doublebox-v}}{{FTUI Klasse|doublebox-h}}{{FTUI Klasse|triplebox-v}}{{FTUI Klasse|right}}
|}

{|class="wikitable mw-collapsible mw-collapsed" style="width: 100%;"
!colspan="2" style="text-align: left;"|Vordergrundfarben
|-
!class="mw-collapsible-content"|Klasse!!Beschreibung
{{FTUI Klasse|red}}{{FTUI Klasse|green}}{{FTUI Klasse|blue}}{{FTUI Klasse|lightblue}}{{FTUI Klasse|orange}}{{FTUI Klasse|gray}}{{FTUI Klasse|lightgray}}{{FTUI Klasse|white}}{{FTUI Klasse|black}}{{FTUI Klasse|mint}}{{FTUI Klasse|yellow}}
|}

{|class="wikitable mw-collapsible mw-collapsed" style="width: 100%;"
!colspan="2" style="text-align: left;"|Hintergrundfarben
|-
!class="mw-collapsible-content"|Klasse!!Beschreibung
{{FTUI Klasse|bg-red}}{{FTUI Klasse|bg-green}}{{FTUI Klasse|bg-blue}}{{FTUI Klasse|bg-lightblue}}{{FTUI Klasse|bg-orange}}{{FTUI Klasse|bg-gray}}{{FTUI Klasse|bg-lightgray}}{{FTUI Klasse|bg-white}}{{FTUI Klasse|bg-black}}{{FTUI Klasse|bg-mint}}{{FTUI Klasse|bg-yellow}}
|}

{|class="wikitable mw-collapsible mw-collapsed" style="width: 100%;"
!colspan="2" style="text-align: left;"|Rahmen
|-
!class="mw-collapsible-content"|Klasse!!Beschreibung
{{FTUI Klasse|verticalLine}}{{FTUI Klasse|border-black}}{{FTUI Klasse|border-white}}{{FTUI Klasse|border-orange}}{{FTUI Klasse|border-red}}{{FTUI Klasse|border-green}}{{FTUI Klasse|border-mint}}{{FTUI Klasse|border-lightblue}}{{FTUI Klasse|border-blue}}{{FTUI Klasse|border-gray}}{{FTUI Klasse|border-yellow}}{{FTUI Klasse|border-lightgray}}
|}

{|class="wikitable mw-collapsible mw-collapsed" style="width: 100%;"
!colspan="2" style="text-align: left;"|Größen
|-
!class="mw-collapsible-content"|Klasse!!Beschreibung
{{FTUI Klasse|mini}}{{FTUI Klasse|tiny}}{{FTUI Klasse|small}}{{FTUI Klasse|normal}}{{FTUI Klasse|large}}{{FTUI Klasse|big}}{{FTUI Klasse|bigger}}{{FTUI Klasse|tall}}{{FTUI Klasse|great}}{{FTUI Klasse|grande}}{{FTUI Klasse|gigantic}}
|}

{|class="wikitable mw-collapsible mw-collapsed" style="width: 100%;"
!colspan="2" style="text-align: left;"|Schriftstil
|-
!class="mw-collapsible-content"|Klasse!!Beschreibung
{{FTUI Klasse|thin}}{{FTUI Klasse|bold}}{{FTUI Klasse|darker}}{{FTUI Klasse|truncate}}
|}

{|class="wikitable mw-collapsible mw-collapsed" style="width: 100%;"
!colspan="2" style="text-align: left;"|Sonstiges
|-
!class="mw-collapsible-content"|Klasse!!Beschreibung
{{FTUI Klasse|blank}}{{FTUI Klasse|transparent}}{{FTUI Klasse|half-transparent}}{{FTUI Klasse|blurry}}{{FTUI Klasse|shake}}{{FTUI Klasse|fail-shake}}{{FTUI Klasse|marquee}}{{FTUI Klasse|icon round}}{{FTUI Klasse|icon square}}{{FTUI Klasse|readonly}}{{FTUI Klasse|blink}}{{FTUI Klasse|rotate-90}}{{FTUI Klasse|horizontal}}{{FTUI Klasse|circleborder}}{{FTUI Klasse|autohide}}{{FTUI Klasse|notransmit}}{{FTUI Klasse|tap}}{{FTUI Klasse|FS20}}{{FTUI Klasse|value}}{{FTUI Klasse|novalue}}{{FTUI Klasse|timestamp}}{{FTUI Klasse|percent}}{{FTUI Klasse|nocache}}{{FTUI Klasse|fade}}{{FTUI Klasse|rotate}}{{FTUI Klasse|nolabels}}{{FTUI Klasse|default}}{{FTUI Klasse|prefetch}}{{FTUI Klasse|circulate}}{{FTUI Klasse|valueonly}}{{FTUI Klasse|positiononly}}{{FTUI Klasse|lineIndicator}}{{FTUI Klasse|barIndicator}}{{FTUI Klasse|roundIndicator}}{{FTUI Klasse|dim-tick}}{{FTUI Klasse|dim-front}}{{FTUI Klasse|dim-back}}{{FTUI Klasse|hue-tick}}{{FTUI Klasse|hue-front}}{{FTUI Klasse|hue-back}}{{FTUI Klasse|warn}}{{FTUI Klasse|activate}}{{FTUI Klasse|labelright}}{{FTUI Klasse|interlock}}{{FTUI Klasse|keepopen}}{{FTUI Klasse|noshade}}
|}

=== Überlagerung von Text und Bild ===
[[Datei:FTUI_Text_auf_Bild.png||thumb|right]]
Texte können auf Bildern positioniert werden:
<syntaxhighlight lang="html5">
<li data-row="1" data-col="4" data-sizey="4" data-sizex="6">
<div class="display">
<div data-type="image" data-url="https://picsum.photos/200/125/?random" data-size="100%"></div>
<div class="display-center bigger" data-type="label">Text1</div>
<div class="display-topright bigger right-space top-space" data-type="label">Text2</div>
<div class="ontop bigger" style="left: 120px; top: 50px">Text3</div>
</div>
</li>
</syntaxhighlight>

Zur Verfügung stehen folgende Grundpositionen:
* <code>display-topleft</code>
* <code>display-topcenter</code>
* <code>display-topright</code>
* <code>display-centerleft</code>
* <code>display-left</code>
* <code>display-centerright</code>
* <code>display-right</code>
* <code>display-bottomleft</code>
* <code>display-bottomcenter</code>
* <code>display-bottomright</code>

Feinjustage ist möglich über

* <code>right-space</code>
* <code>top-space</code>
* <code>left-space</code>
* <code>bottom-space</code>
* <code>right-space-2</code>
* <code>top-space-2</code>
* <code>left-space-2</code>
* <code>bottom-space-2</code>
* <code>right-space-3</code>
* <code>top-space-3</code>
* <code>left-space-3</code>
* <code>bottom-space-3</code>

[[Datei:FTUI_Beispiel_Positionierung.png|200px|thumb|right]]
Verallgemeinert lassen sich auf diese Weise '''Objekte frei im Elternelement positionieren''':
<syntaxhighlight lang="html5">
<div class="display" data-type="html">
<div class="display-topcenter top-space big">Fenster</div>
<div class="display-center fa fa-4x ftui-window"></div>
<div class="display-bottomleft bottom-space left-space" data-type="label">Text</div>
</div>
</syntaxhighlight>
=== Icons ===
FTUI bringt einige Icons-"Schriftarten" mit, die für die Darstellung genützt werden können. Diese werden automatisch beim Start des UI eingebunden, sobald ein entsprechendes Icon-Präfix im Code der Seite vorkommt.

Verfügbare Icon-Schriftarten sind:
* Eingebaute Icons ''ftui-window'' und ''ftui-door''. Präfix '''ftui-'''. Beispiel: <code>data-icon="ftui-door"</code>
* [http://fontawesome.io/icons/ Font-Awesome]: Mehr als 500 Icons zur Auswahl. Präfix '''fa-'''. Beispiel: <code>data-icon="fa-volume-up"</code>
* [https://material.io/icons/ Material Icons]: Mehr als 900 Icons zur Auswahl. Präfix '''mi-'''. Beispiel: <code>data-icon="mi-local_gas_station"</code>
* FHEM und OpenAutomation Icons: Präfix '''fs-''' und '''oa-'''. Beispiel: <code>data-icon="oa-secur_locked"</code>
* [https://erikflowers.github.io/weather-icons/ Weather-Icons]: Präfix '''wi '''. Beispiel: <code>data-icon="wi wi-day-rain-mix"</code>

Alternativ können auch Bilder Icons (bspw. png) über CSS verwendet werden. Bspw:
<syntaxhighlight lang="html5">
<head>
<style type="text/css">
.logo-fhem {
background: url(https://wiki.fhem.de/fhemlogo.png) no-repeat;
width: 120px;
height: 132px;
background-size: contain;
}
</style>
</head>
<body>
<div data-type="symbol" data-icon="logo-fhem"></div>
</body>
</syntaxhighlight>

== Widgets ==
===Allgemeine Attribute===
Jedes Widget kann über verschiedene Attribute konfiguriert werden. Folgende Attribute gelten für alle Widgets:

{| class="wikitable"
|+allgemeine Attribute
|-
!align="right" |data-type
|Widget-Typ
|-
!align="right" |data-device
|FHEM-Name des Gerätes (mit dem Befehl 'list' bekommt man im FHEM die kpl. Liste)
|-
!align="right" |class
|CSS-Klassen für Aussehen und Formatierung des Widgets
|-
|}

{| class="wikitable"
|+Daten Empfangen
|-
!align="right" |data-get
|Reading Name
|-
!align="right" |data-get-on
|Wert für den Status on
|-
!align="right" |data-get-off
|Wert für den Status off
|-
|}

{| class="wikitable"
|+Daten Senden
|-
!align="right" |data-set
|Reading Name
|-
!align="right" |data-set-on
|Wert für den Status on
|-
!align="right" |data-set-off
|Wert für den Status off
|-
|}

Widget-spezifische Attribute können auf der jeweiligen Widget-Seite nachgelesen werden.

=== Integrierte Widgets ===
Folgende Widgets sind direkt in FHEM Tablet UI integriert und können "out of the box" verwendet werden.

* [[FTUI Widget Button|button]]: Variante der push und switch Widgets, die entweder einen URL ansteuern oder einen FHEM-Befehl absetzen kann
* [[FTUI Widget Checkbox|checkbox]]: Umschalter zwischen zwei definierten Zuständen
* [[FTUI Widget Circlemenu|circlemenu]]: Mehrere Widgets hinter einem Widget verborgen, trotz des 'circle' im Namen kann das Menue jetzt auch horizontal oder vertikal ausgeklappt werden
* [[FTUI Widget Clock|clock]]: Stellt eine einfache Uhr zur Verfügung
* [[FTUI Widget Colorwheel|colorwheel]]: Farbpalette zur Auswahl von Farben
* [[FTUI Widget Controlbutton|controlbutton]]: iOS-ähnlicher Button zum Schalten zwischen zwei Zuständen (z.B. on / off)
* [[FTUI Widget Controller|controller]]: iOS-ähnlicher vertikaler Schieberegler zum Einstellen eines Wertes
* [[FTUI Widget Datetimepicker|datetimepicker]]: Erstellt eine Auswahl für Datum/Uhrzeit
* [[FTUI Widget Departure|departure]]: Abfahrtszeiten öffentlicher Verkehrsmittel
* [[FTUI Widget Dimmer|dimmer]]: Ein-/Aus-Button mit integriertem Schieberegler für z.B. einen Dim-Wert
* [[FTUI Widget Eventmonitor|eventmonitor]]:
* [[FTUI Widget Homestatus|homestatus]]: Auswahl für vier oder fünf definierte Stati eines Objects (z.B.: FHEM Residents)
* [[FTUI Widget Html|html]]:
* [[FTUI Widget Iframe|iframe]]: Widget zum Einbinden externer Inhalte in einem Iframe
* [[FTUI Widget Image|image]]: Zeigt ein Bild, dessen URL fest vorgegeben oder aus einem Device-Reading gelesen werden kann
* [[FTUI Widget Input|input]]: Erstellen eines Texteingabefeldes
* [https://github.com/nesges/Widgets-for-fhem-tablet-ui/wiki/joinedlabel joinedlabel]: verbindet mehrere Readings zu einem Feld
* [[FTUI Widget Klimatrend|klimatrend]]: wandelt Daten aus dem statistics-Modul in einen Pfeil um, der den aktuellen Trend anzeigt
* [[FTUI Widget Knob|knob]]: Erstellt einen Statusbalken auf einer Kreisbahn
* [[FTUI Widget Label|label]]: Reading als Text anzeigen
* [[FTUI Widget Level|level]]: Vertikale oder horizontale Leiste zur Anzeige von Werten zwischen einem Minimal- und einem Maximalwert
* [[FTUI Widget Link|link]]: Erstellt einen Link oder Button zum Aufrufen von URLs oder Senden von Befehlen an FHEM
* [[FTUI Widget Medialist|medialist]]:
* [[FTUI Widget Multistatebutton|multistatebutton]]: Variante des push-Widgets, welches den set-Befehl abhängig vom gelesenen Status ändert
* [[FTUI Widget Notify|notify]]: Blendet ein Hinweisfenster im Browser ein
* [[FTUI Widget Pagebutton|pagebutton]]: Button, mit dem auf andere Seiten gesprungen werden kann. Eignet sich gut für eine Navigation
* [[FTUI Widget Pagetab|pagetab]]: Tauscht den Inhalt einer Seite durch den einer anderen. Eignet sich gut für ein Navigationsmenü
* [[FTUI Widget Playstream|playstream]]: Abspielen eines Webradio-Streams per Button
* [[FTUI Widget Popup|popup]]: Öffnet ein Popup nach einem Klick auf ein Widget oder HTML-Element
* [[FTUI Widget Progress|progress]]: Zeigt einen Prozentwert in Form einer runden Fortschrittsleiste
* [[FTUI_Widget_Push|push]]: Button, mit dem ein Befehl an FHEM gesendet werden kann
* [[FTUI Widget Range|range]]: Erstellt vertikale Balken, die einen Wertebereich in unterschiedlichen Farben darstellen
* [[FTUI Widget Readingsgroup|readingsgroup]]: Zeigt eine Readingsgroup an, wie sie in FHEM definiert wurde
* [[FTUI Widget Rotor|rotor]]: Animiertes Umschalten von zwei oder mehr Widgets an einer Position
* [[FTUI Widget Scale|scale]]: Vertikale oder horizontale Leiste zur Anzeige von Werten zwischen einem Minimal- und einem Maximalwert
* [[FTUI_Widget_Select|select]]: Combobox, die eine Liste an Werten zur Auswahl anzeigt
* [https://github.com/nesges/Widgets-for-fhem-tablet-ui/wiki/settimer settimer]: Zum Anzeigen und Einstellen einer Uhrzeit
* [[FTUI Widget Simplechart|simplechart]]: Einfaches XY-Diagramm zur Anzeige eines Wertes, der direkt aus einem FHEM-Logfile gelesen wird
* [[FTUI Widget Slideout|slideout]]:
* [[FTUI Widget Slider|slider]]: Vertikaler Schieberegler zum Einstellen eines Wertes
* [[FTUI Widget Spinner|spinner]]: Element, um Werte durch Drücken auf Plus-/Minus- oder Höher-/Tiefer-Icons zu ändern
* [[FTUI Widget Swiper|swiper]]: Bietet die Möglichkeit, durch Wischen zwischen verschiedenen Seiten zu wechseln
* [[FTUI Widget Switch|switch]]: Button, um zwischen zwei Zuständen zu schalten (z.B. on / off)
* [[FTUI Widget Symbol|symbol]]: Status eines Devices als Symbol darstellen (z.B. Fenster offen)
* [[FTUI Widget Theme|theme]]: Kontextspezifisches Design
* [[FTUI Widget Thermostat|thermostat]]: Anzeige für Heizungsthermostate, mit der die gewünschte Temperatur eingestellt werden kann
* [[FTUI Widget Volume|volume]]: Einstellscheibe zur Änderung eines einzelnen Wertes
* [[FTUI Widget Weather|weather]]: Wettersymbol anzeigen
* [[FTUI Widget WindDirection|wind_direction]]: Anzeige der Windrichtung auf einer Windrose

===3rd Party Widgets===
Für diese Widgets kann nicht sichergestellt werden, dass sie mit der jeweils aktuellen Version von FTUI funktionieren.
* [[FTUI Widget Agenda|agenda]]: Zeigt Kalendereinträge in einer Listenform an
* [[FTUI_Widget_Analogclock|analogclock]]: Analoguhr
* [[FTUI Widget Calview|calview]]: Zeigt Einträge aus einem [[CALVIEW]]-Device an
* [[FTUI Widget Chart|chart]]: Diagramm mit ähnlichen Möglichkeiten wie die FHEM-Plots
* [[FTUI Widget Classchanger|classchanger]]: Ändert seine CSS-Klassen je nach Status eines Devices
* [[FTUI Widget Clicksound|clicksound]]: Mit dem Widget "clicksound" können Sounds an Click-Events von Elementen gebunden werden.
* [[FTUI Widget Dwdweblink|dwdweblink]]: Grafische Anzeige DWD-Wetter-Weblink
* [[FTUI Widget Filelog|filelog]]: Teile aus einem FHEM Logfile anzeigen
* [[FTUI Widget Fullcalview|fullcalview]]:
* [[FTUI Widget Gds|gds]]:
* [[FTUI Widget Maps|maps]]: Kartendarstellung mit Google Maps API
* [[FTUI Widget Highchart|highchart]]:
* [[FTUI Widget Highchart3d|highchart3d]]:
* [https://github.com/nesges/Widgets-for-fhem-tablet-ui/wiki/itunes_artwork itunes_artwork]: itunes_artwork durchsucht die iTunes-Datenbank anhand eines Arrays von beliebigen Suchworten nach einem Cover-Artwork und zeigt dieses an.
* [https://github.com/nesges/Widgets-for-fhem-tablet-ui/wiki/javascript javascript]: Ermöglicht die Ausführung beliebigen Javascript-Codes aus einem Reading.
* [https://github.com/nesges/Widgets-for-fhem-tablet-ui/wiki/kodinowplaying kodinowplaying]: zeigt Informationen zu grade in KODI gespielten Medien in Form eines Labels an.
* [[FTUI Widget Loading|loading]]:
* [[FTUI Widget Meteogram|meteogram]]:
* [https://github.com/nesges/Widgets-for-fhem-tablet-ui/wiki/mpdnowplaying mpdnowplaying]: Zeigt Titelinformationen eines per MPD-Modul angebundenen Music Player Daemon an.
* [https://forum.fhem.de/index.php/topic,79283.msg712855.html#msg712855 pinpad]: Pinpad für z.B. eine Alarmanlage
* [https://forum.fhem.de/index.php/topic,76643.msg685472.html#msg685472 postme]: Liste des PostMe-Devices anzeigen
* [https://github.com/nesges/Widgets-for-fhem-tablet-ui/wiki/reload reload]: auslösen eine Pagereloads
* [[FTUI Widget Screensaver|screensaver]]:
* [[FTUI Widget SMAPortalSPG|smaportalspg]]: Anzeige von SMAPortal-Daten im FHEM Tablet UI
* [[FTUI Widget für SSCam Streaming Devices (SSCamSTRM)|sscamstrm]]: Integration von SSCam Streaming-Devices (Synology Surveillance Station Kameras) im FHEM Tablet UI
* [https://forum.fhem.de/index.php/topic,73497.0.html scrolllabel]: Texte in Laufschrift darstellen
* [[FTUI Widget Svgplot|svgplot]]: Unveränderte Übernahme eine bestehenden SVG-Plots
* [https://forum.fhem.de/index.php?topic=82883.msg750237#msg750237 todoist]: einfaches widget für todoist
* [[FTUI Widget Tts|tts]]: Sprachausgabe eines Textes aus einem Reading auf dem Endgerät.
* [[FTUI Widget UWZ|uwz]]: Anzeige der Warnungen der Unwetterzentrale
* [[FTUI Widget Wakeup|wakeup]]:
* [https://github.com/svenson08/ftui-weekdaytimer-widget wdtimer]: Visualisierung des [[WeekdayTimer]] Modul
* [[FTUI Widget Weekprofile|weekprofile]]: Visualisierung des [[weekprofile]] Moduls
* [[FTUI Widget Weatherdetail|weatherdetail]]: Detaillierte Wettervorhersage über 4 Tage (Nutzt das Proplanta Modul)
* [[FTUI Widget Video|videodetail]]: Video Widget für die FTUI

===Anwendungsbeispiele===
Durch die Verbindung von Widgets mit dem FHEM-Umfeld entstehen Lösungen für typische Anwendungen.
* [[FTUI_Beispiel_Datetimepicker_für_Timer|Datetimepicker für Timer]]: Oberfläche für Timereinstellungen
* [[FTUI_Beispiel_Mondphase|Mondphase]]: Visuelle Darstellung der Mondphase
* [[FTUI_Beispiel_Webradio|Webradio]]
* [[FTUI Beispiel Zeitschaltung|Verschiedene Zeitschaltungen]]

==Templates==
Kommt ein bestimmtes "Code-Fragment" auf mehreren Seiten oder öfter pro Seite vor, bietet FTUI die Option, Templates zu erstellen. Diese werden einmal gebaut und können dann mit dem Attribut '''data-template''' nach Belieben in eine Seite eingefügt werden. Dabei besteht auch die Möglichkeit, Variablen zu verwenden.

Die Variablennamen sollten möglichst eindeutig und unverwechselbar gewählt werden, da bei der Verwendung von Templates im Prinzip Suchen & Ersetzen angewendet wird. Verwendet man beispielsweise die Variablen '''dev:Thermostat_Kueche''' und '''dev_temp:temperatue''', so kann es passieren, dass die Ergebnisse im erzeugten Code dann '''Thermostat_Kueche''' und '''Thermostat_Kueche_temp''' lauten, statt wie gewünscht '''Thermostat_Kueche''' und '''temperature'''. Um dies zu vermeiden, sollten die Variablen besser '''device:Thermostat_Kueche''' und '''temp:temperature''' lauten.

Im Folgenden ein paar Beispiele, wie Templates verwendet werden können.

===Einzelnes Widget===
Soll ein Widget an mehreren Stellen in exakt der selben Ausführung eingebunden werden, kann diese Widget in einer eigenen Datei erstellt und diese dann auf den Zielseiten automatisch mitgeladen werden.

;Template-Seite
Die Template-Seite soll in diesem Beispiel ''template_symbol.html'' genannt werden. Diese wird daher zuerst im FTUI-Verzeichnis erstellt.
<syntaxhighlight lang="html">
<div data-type="symbol"
data-device="dummy1">
</syntaxhighlight>

;Haupt-Seite
Die oben erstellte Template-Seite kann nun in jeder gewünschten Seite eingebunden werden.
<syntaxhighlight lang="html" highlight="6">
[...]
<body>
<div class="gridster">
<ul>
<li data-row="1" data-col="1" data-sizey="1" data-sizex="1">
<div data-template="template_symbol.html"></div>
</li>
</ul>
</div>
</body>
[...]
</syntaxhighlight>

===Gridster-Element===
Natürlich kann auch ein ganzes Gridster-Element - in diesem Fall ein Menü - als Template eingebunden werden.
<syntaxhighlight lang="html">
<li data-row="1" data-col="1" data-sizex="1" data-sizey="4" data-template="menu.html"></li>
</syntaxhighlight>

=== Widget-Gruppen ===
Die Template-Datei des [[#Einzelnes Widget|ersten Beispiels]] kann natürlich auch mehrere Widgets auf einmal enthalten.

=== Verwendung von Variablen ===
==== Einfaches Beispiel ====
Oft wird ein und dasselbe Widget für verschiedenen Devices verwendet. Um nicht für jedes Device das Widget neu kopieren zu müssen (bzw. bei Änderungen alle Seiten ausbessern zu müssen), kann ein Template verwendet werden, dem einfach per Parameter mitgeteilt wird, von welchem Device es gerade die Daten empfangen soll.

In diesem Beispiel wird ein Template erzeugt, dass nur die Temperatur verschiedenen Thermostate mittels eines [[FTUI Widget Label|Label-Widgets]] anzeigt.

;Template-Seite
Die Template-Seite enthält nur ein einfaches Label-Widget und wird in diesem Beispiel ''template_label.html'' genannt. Um sie für mehrere Devices verwenden zu können, wird im Attribut '''data-device''' der Name des eigentlichen Devices durch den Parameter '''par01''' ersetzt.
<syntaxhighlight lang="html" highlight="2">
<div data-type="label"
data-device="par01"
data-get="measured-temp"></div>
</syntaxhighlight>

;Haupt-Seite
Auf der Haupt-Seite wird die Template-Seite mit dem Attribut '''data-template''' eingebunden und ihr via Attribut '''data-parameter''' das jeweils gewünschte Device übergeben.
<syntaxhighlight lang="html">
[...]
<div data-template="template_label.html" data-parameter='{"par01":"Thermostat1"}'></div>
<div data-template="template_label.html" data-parameter='{"par01":"Thermostat2"}'></div>
<div data-template="template_label.html" data-parameter='{"par01":"Thermostat3"}'></div>
[...]
</syntaxhighlight>

==== Wetter-Slider mit Template ====
In diesem Beispiel wird ein [[FTUI Widget Slider|Slider-Widget]] erstellt, welches die verschiedenen Tage eines Wetterberichtes anzeigt. Dabei wird für den Wetterbericht des jeweiligen Tages immer dasselbe Template verwendet um nicht für jeden Tag ein eigenes Widget schreiben zu müssen.

;Template-Seite
<syntaxhighlight lang="html">
<div class="left">
<div data-type="label" data-device="AgroWeather" data-get="par01" data-unit="°C"></div>
<div class="inline">
<div data-type="label" data-device="AgroWeather" data-get="par02"></div>
<div data-type="weather" data-device="AgroWeather" data-get="par02"></div>
min: <div data-type="label" data-device="AgroWeather" data-get="par03" data-unit="°C"></div>
</div>
</div>
<div class="left">
<div data-type="label" data-device="AgroWeather" data-get="par04" data-substitution="toDate().eeee()+','"></div>
<div data-type="label" data-device="AgroWeather" data-get="par04" data-substitution="toDate().ddmm()"></div>
</div>
</syntaxhighlight>

;Haupt-Seite
In der Haupt-Seite wird das Template dann für jede Slider-Seite eingebunden und das Reading für den jeweiligen Tag via Parameter übergeben.
<syntaxhighlight lang="html">
[...]
<div data-type="swiper">
<ul>
<li data-template="templates/wetter.html" data-parameter='{"par01":"fc0_tempMax","par02":"fc0_weatherDay","par03":"fc0_tempMin","par04":"fc0_date"}'></li>
<li data-template="templates/wetter.html" data-parameter='{"par01":"fc1_tempMax","par02":"fc1_weatherDay","par03":"fc1_tempMin","par04":"fc1_date"}'></li>
<li data-template="templates/wetter.html" data-parameter='{"par01":"fc2_tempMax","par02":"fc2_weatherDay","par03":"fc2_tempMin","par04":"fc2_date"}'></li>
<li data-template="templates/wetter.html" data-parameter='{"par01":"fc3_tempMax","par02":"fc3_weatherDay","par03":"fc3_tempMin","par04":"fc3_date"}'></li>
</ul>
</div>
[...]
</syntaxhighlight>

== JavaScript-Funktionen ==
Neben den Widgets können auch einige JavaScript-Funktionen verwendet werden, um Befehle an FHEM zu senden.

Folgende Zeile setzt einen direkten Befehl an FHEM ab (<code>set dummy1 off</code>):
<syntaxhighlight lang="html"><div onclick="ftui.setFhemStatus('set dummy1 off')">Dummy1 aus</div></syntaxhighlight>

Diese Zeile veranlasst FHEM dazu, eine Funktion aus der 99_myUtils.pm auszuführen (<code>myUtils_HeizungUpDown("WZ.Thermostat_Climate","up")</code>):
<syntaxhighlight lang="html"><div onclick="ftui.setFhemStatus('{myUtils_HeizungUpDown("WZ.Thermostat_Climate","up")}')">+</div></syntaxhighlight>

Ein Beispiel, wie ein Kommando an FHEM gesendet wird und gleichzeitig der Wert eines bereits in FTUI angezeigten Readings verwendet werden kann:
<syntaxhighlight lang="html">
<div data-type="label" data-device="dummy1" data-get="temperature"></div>
<div onClick="ftui.setFhemStatus('set dummy2 '+ftui.getDeviceParameter('dummy1','temperature').val);">Senden</div>
</syntaxhighlight>

== Eigene Widgets erstellen ==
Wie eigenen Widgets für FTUI erstellt werden können, ist auf der Seite [[FTUI eigene Widgets]] beschrieben.

Eine Schritt für Schritt Anleitung für das erste eigene Widget gibts hier [[FTUI eigene Widgets - Beispiel]]

== FAQ ==
Häufig gestellte Fragen zum FHEM Tablet UI sind in der [[FHEM Tablet UI FAQ]] zusammengestellt.

== Links ==
* [https://github.com/knowthelist/fhem-tablet-ui Projekt auf Github]
* {{Link2Forum|Topic=34233|LinkText=Forums-Beitrag}}
* [[FTUI_Snippets|Snippets]]
* [http://knowthelist.github.io/fhem/tablet/demo_widgets.html Live-Demos]
* [https://waschto.eu/fhem-und-tabletui-livedemo/ FHEM und TabletUI Live-Demo]
* {{Link2Forum|Topic=37378|LinkText=User-Demos}}
* [https://github.com/ovibox/fhem-ftui-user-demos Download der User-Demo-Dateien]

[[Kategorie:FHEM Tablet UI|!]]

TRÅDFRI

2019-11-17T16:04:03Z

Kaihs: /* tradfri */

<div style="float:right">{{Infobox Modul
|Name=tradfri
|ModPurpose=Anbindung IKEA TRÅDFRI Gateway
|ModType=d

|ModCmdRef=tradfri
|ModForumArea=Zigbee
|ModTechName=30_tradfri.pm
|ModOwner=Andre ([http://forum.fhem.de/index.php?action=profile;u=430 Forum] / [[Benutzer Diskussion:justme|Wiki]])
}}
</div>

'''TRÅDFRI''' bzw. '''IKEA Home smart''' ist die Serie smarter Beleuchtungslösungen von IKEA auf ZigBee-Basis, ähnlich Phillips Hue.

== tradfri ==

TRÅDFRI (nach Umbennung jetzt '''IKEA Home smart''') ist die Serie smarter Beleuchtungslösungen von IKEA. Ähnlich wie von Phillips [[Hue]] gibt es diverse LEDs in Glühbirnenform, LED-Streifen-Treiber, Flächenleuchten, Wandtaster, Bewegungsmelder, Fernbedienung, Dimmer, etc. und alles via Funk gekoppelt. Außerdem ein Gateway, das sich via Ethernetstecker ins heimische LAN einbinden lässt und die Bedienung via IKEA-App auf dem Handy ermöglicht.
{{Hinweis|Da die Geräte über den [[ZigBee]]-Standard kommunizieren, können auch andere Gateways für diese Leuchtmittel (und andere Geräte wie Rollos) genutzt werden. Dieser Artikel behandelt ausschließlich die Verwendung zusammen mit einem IKEA-Gateway!}}
Mit dem IKEA-Gateway ist auch eine Anbindung in FHEM möglich, dazu funktionieren zwei '''alternative''' Lösungen:

=== alt: IKEA Trådfri Modul ===
IKEA Trådfri Modul (TYPE ''TradfriDevice'' und ''TradfriGateway'', mehr Infos: https://forum.fhem.de/index.php/topic,70653.0.html seit April 2017)
* Erkennt Lampen
* Fernbedienung erscheint zwar in der Geräteliste, lässt sich aber nicht als Gerät anlegen oder Status lesen

Die Weiterentwicklung des Moduls durch den ursprünglichen Entwickler scheint Stand 07.19 eingestellt. Inwieweit andere am Modul weiter arbeiten ist unklar.

=== neu: tradfri-fhem Modul ===
tradfri-fhem Modul (TYPE ''HUEDevice'' und ''tradfri'' Gateway, mehr Infos: https://forum.fhem.de/index.php/topic,96125.0.html seit Januar 2019, Beschreibung folgt auf dieser Seite)
* Unterstützt Lampen (als [[Hue#HUE-Device|HUE-Device]])
* Unterstützt Rollos (Fyrtur und Kadrilj)
* Erkennt Fernbedienung, jedoch zur Zeit Batteriestatus als einziges Reading
* Erstellt (wenn gewünscht) automatisch Gruppen
* Erkennt Bewegungsmelder, jedoch zur Zeit Batteriestatus als einziges Reading
* Erkennt Repeater, nur Erreichbarkeit (reachable) als Reading

====Einrichtung in FHEM====

# node installieren (mindestens version 8)
# sudo npm install -g tradfri-fhem
# <code>define <tradfri> tradfri</code>
# <code>attr <tradfri> tradfriFHEM-securityCode <security code></code>

wenn das gateway nicht automatisch erkannt wird:
<code>attr <tradfri> tradfriFHEM-params --ip <ip></code>

WICHTIG: danach in FHEM einmal die Konfiguration speichern damit der Pairing-Key gesichert wird. Sonst muss beim nächsten FHEM-Neustart das Pairing erneut durchgeführt werden.

==== HUE-Device ====
Alle auf dem Gateway bekannten Geräte automatisch als [[Hue#HUE-Device|HUEDevice]] in FHEM angelegt:
* Lampen, Stecker, Trafos, ...
: Hiermit werden die einzelnen Leuchten gesteuert
* Gruppen
: Hiermit lassen sich ganze Gruppen und Räume steuern
* Fernbedienungen
: aktuell gibt es nur ein Battery-Reading

==== Darstellung im Webfrontend ====
Wenn man die SVG Icons verwendet ist es sinnvoll, das Attribut color-icons zu setzen. Mit <code>attr HUEDevice1 color-icons 2</code> werden z.B. die Farben und der Dimmzustand der Lampe als Icon dargestellt.
Damit das ganze funktioniert, müsst ihr auch noch das <code>attr WEB iconPath fhemSVG:openautomation:default</code> setzen.

== Links ==
* [https://github.com/peterkappelt/Tradfri-FHEM/issues/16#issuecomment-445461242 Githubeintrag über Einstellung der Feature-Entwicklung des IKEA Trådfri Moduls].
[[Kategorie:ZigBee]]
[[Kategorie:Lichteffektgeräte]]
[[Kategorie:IP Components]]

TRÅDFRI

2019-11-17T16:03:22Z

Kaihs: /* tradfri */

<div style="float:right">{{Infobox Modul
|Name=tradfri
|ModPurpose=Anbindung IKEA TRÅDFRI Gateway
|ModType=d

|ModCmdRef=tradfri
|ModForumArea=Zigbee
|ModTechName=30_tradfri.pm
|ModOwner=Andre ([http://forum.fhem.de/index.php?action=profile;u=430 Forum] / [[Benutzer Diskussion:justme|Wiki]])
}}
</div>

'''TRÅDFRI''' bzw. '''IKEA Home smart''' ist die Serie smarter Beleuchtungslösungen von IKEA auf ZigBee-Basis, ähnlich Phillips Hue.

== tradfri ==

TRÅDFRI (nach Umbennung jetzt '''IKEA Home smart''') ist die Serie smarter Beleuchtungslösungen von IKEA. Ähnlich von Phillips [[Hue]] gibt es diverse LEDs in Glühbirnenform, LED-Streifen-Treiber, Flächenleuchten, Wandtaster, Bewegungsmelder, Fernbedienung, Dimmer, etc. und alles via Funk gekoppelt. Außerdem ein Gateway, das sich via Ethernetstecker ins heimische LAN einbinden lässt und die Bedienung via IKEA-App auf dem Handy ermöglicht.
{{Hinweis|Da die Geräte über den [[ZigBee]]-Standard kommunizieren, können auch andere Gateways für diese Leuchtmittel (und andere Geräte wie Rollos) genutzt werden. Dieser Artikel behandelt ausschließlich die Verwendung zusammen mit einem IKEA-Gateway!}}
Mit dem IKEA-Gateway ist auch eine Anbindung in FHEM möglich, dazu funktionieren zwei '''alternative''' Lösungen:

=== alt: IKEA Trådfri Modul ===
IKEA Trådfri Modul (TYPE ''TradfriDevice'' und ''TradfriGateway'', mehr Infos: https://forum.fhem.de/index.php/topic,70653.0.html seit April 2017)
* Erkennt Lampen
* Fernbedienung erscheint zwar in der Geräteliste, lässt sich aber nicht als Gerät anlegen oder Status lesen

Die Weiterentwicklung des Moduls durch den ursprünglichen Entwickler scheint Stand 07.19 eingestellt. Inwieweit andere am Modul weiter arbeiten ist unklar.

=== neu: tradfri-fhem Modul ===
tradfri-fhem Modul (TYPE ''HUEDevice'' und ''tradfri'' Gateway, mehr Infos: https://forum.fhem.de/index.php/topic,96125.0.html seit Januar 2019, Beschreibung folgt auf dieser Seite)
* Unterstützt Lampen (als [[Hue#HUE-Device|HUE-Device]])
* Unterstützt Rollos (Fyrtur und Kadrilj)
* Erkennt Fernbedienung, jedoch zur Zeit Batteriestatus als einziges Reading
* Erstellt (wenn gewünscht) automatisch Gruppen
* Erkennt Bewegungsmelder, jedoch zur Zeit Batteriestatus als einziges Reading
* Erkennt Repeater, nur Erreichbarkeit (reachable) als Reading

====Einrichtung in FHEM====

# node installieren (mindestens version 8)
# sudo npm install -g tradfri-fhem
# <code>define <tradfri> tradfri</code>
# <code>attr <tradfri> tradfriFHEM-securityCode <security code></code>

wenn das gateway nicht automatisch erkannt wird:
<code>attr <tradfri> tradfriFHEM-params --ip <ip></code>

WICHTIG: danach in FHEM einmal die Konfiguration speichern damit der Pairing-Key gesichert wird. Sonst muss beim nächsten FHEM-Neustart das Pairing erneut durchgeführt werden.

==== HUE-Device ====
Alle auf dem Gateway bekannten Geräte automatisch als [[Hue#HUE-Device|HUEDevice]] in FHEM angelegt:
* Lampen, Stecker, Trafos, ...
: Hiermit werden die einzelnen Leuchten gesteuert
* Gruppen
: Hiermit lassen sich ganze Gruppen und Räume steuern
* Fernbedienungen
: aktuell gibt es nur ein Battery-Reading

==== Darstellung im Webfrontend ====
Wenn man die SVG Icons verwendet ist es sinnvoll, das Attribut color-icons zu setzen. Mit <code>attr HUEDevice1 color-icons 2</code> werden z.B. die Farben und der Dimmzustand der Lampe als Icon dargestellt.
Damit das ganze funktioniert, müsst ihr auch noch das <code>attr WEB iconPath fhemSVG:openautomation:default</code> setzen.

== Links ==
* [https://github.com/peterkappelt/Tradfri-FHEM/issues/16#issuecomment-445461242 Githubeintrag über Einstellung der Feature-Entwicklung des IKEA Trådfri Moduls].
[[Kategorie:ZigBee]]
[[Kategorie:Lichteffektgeräte]]
[[Kategorie:IP Components]]

WMBUS

2019-10-29T18:57:02Z

Kaihs: /* Empfangsprobleme */

{{Infobox Modul
|ModPurpose=Dekodierung von Wireless M-Bus Nachrichten
|ModType=d
|ModForumArea=Sonstige Systeme
|ModTechName=36_WMBUS.pm
|ModOwner=kaihs
}}
[[WMBUS]] ist ein Modul zur Dekodierung von Wireless M-Bus Nachrichten. Solche Nachrichten werden z. B. von Zählern für Wasser, Wärme, Gas und Elektrizität ausgestrahlt.
Wireless M-Bus ist ein Standardprotokoll das von unterschiedlichen Herstellern unterstützt wird.
Das Protokoll unterstützt unterschiedliche Kodierungen des Funksignals, im wesentlichen den S-Mode, T-Mode und C-Mode. Der Empfänger (z. B. ein CUL) muss den selben Modus nutzen wie der Sender (der Zähler).
Wireless M-Bus unterstützt optional die Verschlüsselung der Daten.
Die von einem Zähler gesendeten Daten können sehr unterschiedlich sein und hängen u. a. vom Zählertyp und dessen Hersteller ab.

== Voraussetzungen ==
Das Modul interpretiert nur die Nachrichten die von einen geeigneten Empfänger empfangen werden. Aktuell kann ein [[CUL]] und verwandte Geräte die die culfw[http://culfw.de/culfw.html] verwenden sowie ein Amber Wireless AMB8465M dafür verwendet werden. In der culfw muss die Unterstützung des WMBUS-Protokolls aktiviert sein (#define HAS_MBUS in der Datei board.h des Deviceverzeichnisses). Bei einem CUL mit der Hardwareversion V4 ist das nicht der Fall.

Der CUL muss in FHEM mittels Attribut rfmode=WMBus_S, WMBus_T oder WMBus_C in den zum Zähler passenden Empfangsmodus versetzt werden.

== Anwendung ==
Die Erzeugung des passenden Devices in FHEM geschieht automatisch beim Empfang des ersten Datenpakets eines Zählers. Voraussetzung dafür ist, dass [[autocreate]] aktiv ist.
Alternativ kann ein Device manuell angelegt werden. Dazu wird der Hersteller, die Seriennummer, die Version und der Typ (Wasser, Gas, ...) des Zählers benötigt.
Sind die Daten verschlüsselt wird auch noch der passende Schlüssel benötigt um die Daten entschlüsseln zu können.

== Verschlüsselung ==
Die Daten können auf drei verschiedene Arten verschlüsselt sein:
# Security profile A/Symmetric encryption with Mode 5
# Security profile B/Advanced symmetric encryption with Mode 7
# Security profile C/Asymmetric encryption with Mode 13

Das Modul unterstützt aktuell Daten die per 1 oder 2 verschlüsselt wurden.

== Anwendungsbeispiele ==
Ein per [[EnergyCam]] abgelesener Elektrizitätszähler sieht in FHEM z. B. so aus:
<pre>
Internals:
CUL_MBUS_MSGCNT 29
CUL_MBUS_RAWMSG b1944C4189985051701028A7D7A540000A00405FAD4080002FD08222C1295B8::-67.5
CUL_MBUS_RSSI -67.5
CUL_MBUS_TIME 2014-10-24 22:57:53
DEF FFD 17058599 1 2
DeviceMedium Electricity
DeviceType 2
IODev CUL_MBUS
IdentNumber 17058599
LASTInputDev CUL_MBUS
MSGCNT 29
Manufacturer FFD
NAME WMBUS_FFD_17058599_1_2
NR 49
STATE no errors
TYPE WMBUS
Version 1
addr FFD_17058599_1_2
Readings:
2014-10-24 22:57:53 1_storage_no 0
2014-10-24 22:57:53 1_type VIF_ENERGY_WATT
2014-10-24 22:57:53 1_unit Wh
2014-10-24 22:57:53 1_value 57881000
2014-10-24 22:57:53 2_storage_no 0
2014-10-24 22:57:53 2_type VIF_ACCESS_NO
2014-10-24 22:57:53 2_unit
2014-10-24 22:57:53 2_value 11298
2014-10-24 22:57:53 LQI 184
2014-10-24 22:57:53 RSSI -67.5
2014-10-24 22:57:53 battery ok
2014-10-24 22:57:53 decryption_ok 1
2014-10-24 22:57:53 energy 57881
2014-10-24 22:57:53 is_encrypted 0
2014-10-24 22:57:53 state no errors
2014-10-24 22:57:53 unit kWh
Attributes:
IODev CUL_MBUS
room WMBUS
</pre>

== Bekannte Probleme ==
=== Inkompatible Zähler ===
Obwohl Wireless M-Bus ein standardisiertes Protokoll ist, scheint sich kaum ein Hersteller vollständig daran zu halten bzw. verwendet sog. herstellerspezifische Felder um wichtige Daten zu verpacken.
Aus den bisher beobachteten Datenpaketen ergibt sich
* Qundis (Herstellerkürzel LSE) verwendet herstellerspezifische Datenblöcke für den eigentlichen Zählerstand
* Techem und Hydrometer verwenden ein undokumentiertes Datenformat (CI-Field A2)
:''(Techem Heizkostenverteiler (CI-Field A0) können über das Modul [[TechemHKV]] ausgewertet werden)''
* RWE SmartHome Powercontrol[http://www.rwe-smarthome.de/web/cms/de/1776202/smarthome/informieren/geraete/power-control/] sendet verschlüsselt und der Hersteller gibt nicht den vollständigen Schlüssel an ({{Link2Forum|Topic=24517|Message=315949}})

Daher werden bisher erst die [[EnergyCam]] der Firma Q-loud, Zähler von Easymeter und der Kamstrup Multical 21 vollständig unterstützt.
Für den Multical 21 muss eine culfw mit Unterstützung für WMBUS C verwendet werden. Diese ist in der culfw ab dem 24.6.2018 enthalten.

Andere Zähler können auch ohne Probleme funktionieren wenn diese sich an den OMS Standard halten.

=== Empfangsprobleme ===
Der Empfänger (meist ein [[CUL]]) muss das WMBUS Protokoll unterstützen. Die Unterstützung ist vorhanden, wenn in der Ausgabe von <code>get cmds</code> ein kleines [http://culfw.de/commandref.html#cmd_b b] enthalten ist.
Der CUL speichert die empfangenen Daten intern zwischen bevor sie an fhem geschickt werden. Der Puffer für die Speicherung muss groß genug sein, um ein komplettes Datenpaket aufzunehmen. Die Größe des Puffers kann in der culfw eingestellt werden in dem das define TTY_BUFSIZE in der Datei [https://sourceforge.net/p/culfw/code/HEAD/tree/trunk/culfw/Devices/nanoCUL/board.h board.h] des passenden Devices angepasst wird.
Dabei ist darauf zu achten, dass die verwendeten Mikrocontroller nur sehr wenig RAM haben (0,5-4KB). Um mehr freies RAM zu erhalten sollten Protokolle die nicht benötigt in der board.h abgeschaltet werden. Die Unterstützung für WMBUS (#define HAS_MBUS 1) muss aber natürlich eingeschaltet werden.
Anschließend ist die culfw [[Selbstbau_CUL#Software|neu zu übersetzen und zu flashen]].

== Links ==
* Forumsthread {{Link2Forum|Topic=24517}}
* Protokoll Beschreibung [http://oms-group.org/download4all/]
* Beschreibung des M-BUS Protokolls [http://www.m-bus.com/files/MBDOC48.PDF]
[[Kategorie:Energieverbrauchsmessung]]

WMBUS

2019-09-01T16:29:02Z

Kaihs: /* Bekannte Probleme */

{{Infobox Modul
|ModPurpose=Dekodierung von Wireless M-Bus Nachrichten
|ModType=d
|ModForumArea=Sonstige Systeme
|ModTechName=36_WMBUS.pm
|ModOwner=kaihs
}}
[[WMBUS]] ist ein Modul zur Dekodierung von Wireless M-Bus Nachrichten. Solche Nachrichten werden z. B. von Zählern für Wasser, Wärme, Gas und Elektrizität ausgestrahlt.
Wireless M-Bus ist ein Standardprotokoll das von unterschiedlichen Herstellern unterstützt wird.
Das Protokoll unterstützt unterschiedliche Kodierungen des Funksignals, im wesentlichen den S-Mode, T-Mode und C-Mode. Der Empfänger (z. B. ein CUL) muss den selben Modus nutzen wie der Sender (der Zähler).
Wireless M-Bus unterstützt optional die Verschlüsselung der Daten.
Die von einem Zähler gesendeten Daten können sehr unterschiedlich sein und hängen u. a. vom Zählertyp und dessen Hersteller ab.

== Voraussetzungen ==
Das Modul interpretiert nur die Nachrichten die von einen geeigneten Empfänger empfangen werden. Aktuell kann ein [[CUL]] und verwandte Geräte die die culfw[http://culfw.de/culfw.html] verwenden sowie ein Amber Wireless AMB8465M dafür verwendet werden. In der culfw muss die Unterstützung des WMBUS-Protokolls aktiviert sein (#define HAS_MBUS in der Datei board.h des Deviceverzeichnisses). Bei einem CUL mit der Hardwareversion V4 ist das nicht der Fall.

Der CUL muss in FHEM mittels Attribut rfmode=WMBus_S, WMBus_T oder WMBus_C in den zum Zähler passenden Empfangsmodus versetzt werden.

== Anwendung ==
Die Erzeugung des passenden Devices in FHEM geschieht automatisch beim Empfang des ersten Datenpakets eines Zählers. Voraussetzung dafür ist, dass [[autocreate]] aktiv ist.
Alternativ kann ein Device manuell angelegt werden. Dazu wird der Hersteller, die Seriennummer, die Version und der Typ (Wasser, Gas, ...) des Zählers benötigt.
Sind die Daten verschlüsselt wird auch noch der passende Schlüssel benötigt um die Daten entschlüsseln zu können.

== Verschlüsselung ==
Die Daten können auf drei verschiedene Arten verschlüsselt sein:
# Security profile A/Symmetric encryption with Mode 5
# Security profile B/Advanced symmetric encryption with Mode 7
# Security profile C/Asymmetric encryption with Mode 13

Das Modul unterstützt aktuell Daten die per 1 oder 2 verschlüsselt wurden.

== Anwendungsbeispiele ==
Ein per [[EnergyCam]] abgelesener Elektrizitätszähler sieht in FHEM z. B. so aus:
<pre>
Internals:
CUL_MBUS_MSGCNT 29
CUL_MBUS_RAWMSG b1944C4189985051701028A7D7A540000A00405FAD4080002FD08222C1295B8::-67.5
CUL_MBUS_RSSI -67.5
CUL_MBUS_TIME 2014-10-24 22:57:53
DEF FFD 17058599 1 2
DeviceMedium Electricity
DeviceType 2
IODev CUL_MBUS
IdentNumber 17058599
LASTInputDev CUL_MBUS
MSGCNT 29
Manufacturer FFD
NAME WMBUS_FFD_17058599_1_2
NR 49
STATE no errors
TYPE WMBUS
Version 1
addr FFD_17058599_1_2
Readings:
2014-10-24 22:57:53 1_storage_no 0
2014-10-24 22:57:53 1_type VIF_ENERGY_WATT
2014-10-24 22:57:53 1_unit Wh
2014-10-24 22:57:53 1_value 57881000
2014-10-24 22:57:53 2_storage_no 0
2014-10-24 22:57:53 2_type VIF_ACCESS_NO
2014-10-24 22:57:53 2_unit
2014-10-24 22:57:53 2_value 11298
2014-10-24 22:57:53 LQI 184
2014-10-24 22:57:53 RSSI -67.5
2014-10-24 22:57:53 battery ok
2014-10-24 22:57:53 decryption_ok 1
2014-10-24 22:57:53 energy 57881
2014-10-24 22:57:53 is_encrypted 0
2014-10-24 22:57:53 state no errors
2014-10-24 22:57:53 unit kWh
Attributes:
IODev CUL_MBUS
room WMBUS
</pre>

== Bekannte Probleme ==
=== Inkompatible Zähler ===
Obwohl Wireless M-Bus ein standardisiertes Protokoll ist, scheint sich kaum ein Hersteller vollständig daran zu halten bzw. verwendet sog. herstellerspezifische Felder um wichtige Daten zu verpacken.
Aus den bisher beobachteten Datenpaketen ergibt sich
* Qundis (Herstellerkürzel LSE) verwendet herstellerspezifische Datenblöcke für den eigentlichen Zählerstand
* Techem und Hydrometer verwenden ein undokumentiertes Datenformat (CI-Field A2)
:''(Techem Heizkostenverteiler (CI-Field A0) können über das Modul [[TechemHKV]] ausgewertet werden)''
* RWE SmartHome Powercontrol[http://www.rwe-smarthome.de/web/cms/de/1776202/smarthome/informieren/geraete/power-control/] sendet verschlüsselt und der Hersteller gibt nicht den vollständigen Schlüssel an ({{Link2Forum|Topic=24517|Message=315949}})

Daher werden bisher erst die [[EnergyCam]] der Firma Q-loud, Zähler von Easymeter und der Kamstrup Multical 21 vollständig unterstützt.
Für den Multical 21 muss eine culfw mit Unterstützung für WMBUS C verwendet werden. Diese ist in der culfw ab dem 24.6.2018 enthalten.

Andere Zähler können auch ohne Probleme funktionieren wenn diese sich an den OMS Standard halten.

=== Empfangsprobleme ===
Der Empfänger (meist ein [[CUL]]) muss das WMBUS Protokoll unterstützen. Die Unterstützung ist vorhanden, wenn in der Ausgabe von <code>get cmds</code> ein kleines [http://culfw.de/commandref.html#cmd_b b] enthalten ist.
Der CUL speichert die empfangenen Daten intern zwischen bevor sie an fhem geschickt werden. Der Puffer für die Speicherung muss groß genug sein, um ein komplettes Datenpaket aufzunehmen. Die Größe des Puffers kann in der culfw eingestellt werden in dem das define TTY_BUFSIZE in der Datei [https://sourceforge.net/p/culfw/code/HEAD/tree/trunk/culfw/Devices/nanoCUL/board.h board.h] des passenden Devices angepasst wird.
Dabei ist darauf zu achten, dass die verwendeten Mikrocontroller nur sehr wenig RAM haben (0,5-4KB). Um mehr freies RAM zu erhalten sollten Protokolle die nicht benötigt in der board.h abgeschaltet werden.
Anschließend ist die culfw [[Selbstbau_CUL#Software|neu zu übersetzen und zu flashen]].

== Links ==
* Forumsthread {{Link2Forum|Topic=24517}}
* Protokoll Beschreibung [http://oms-group.org/download4all/]
* Beschreibung des M-BUS Protokolls [http://www.m-bus.com/files/MBDOC48.PDF]
[[Kategorie:Energieverbrauchsmessung]]

WMBUS

2019-08-24T18:09:52Z

Kaihs: /* Bekannte Probleme */

{{Infobox Modul
|ModPurpose=Dekodierung von Wireless M-Bus Nachrichten
|ModType=d
|ModForumArea=Sonstige Systeme
|ModTechName=36_WMBUS.pm
|ModOwner=kaihs
}}
[[WMBUS]] ist ein Modul zur Dekodierung von Wireless M-Bus Nachrichten. Solche Nachrichten werden z. B. von Zählern für Wasser, Wärme, Gas und Elektrizität ausgestrahlt.
Wireless M-Bus ist ein Standardprotokoll das von unterschiedlichen Herstellern unterstützt wird.
Das Protokoll unterstützt unterschiedliche Kodierungen des Funksignals, im wesentlichen den S-Mode, T-Mode und C-Mode. Der Empfänger (z. B. ein CUL) muss den selben Modus nutzen wie der Sender (der Zähler).
Wireless M-Bus unterstützt optional die Verschlüsselung der Daten.
Die von einem Zähler gesendeten Daten können sehr unterschiedlich sein und hängen u. a. vom Zählertyp und dessen Hersteller ab.

== Voraussetzungen ==
Das Modul interpretiert nur die Nachrichten die von einen geeigneten Empfänger empfangen werden. Aktuell kann ein [[CUL]] und verwandte Geräte die die culfw[http://culfw.de/culfw.html] verwenden sowie ein Amber Wireless AMB8465M dafür verwendet werden. In der culfw muss die Unterstützung des WMBUS-Protokolls aktiviert sein (#define HAS_MBUS in der Datei board.h des Deviceverzeichnisses). Bei einem CUL mit der Hardwareversion V4 ist das nicht der Fall.

Der CUL muss in FHEM mittels Attribut rfmode=WMBus_S, WMBus_T oder WMBus_C in den zum Zähler passenden Empfangsmodus versetzt werden.

== Anwendung ==
Die Erzeugung des passenden Devices in FHEM geschieht automatisch beim Empfang des ersten Datenpakets eines Zählers. Voraussetzung dafür ist, dass [[autocreate]] aktiv ist.
Alternativ kann ein Device manuell angelegt werden. Dazu wird der Hersteller, die Seriennummer, die Version und der Typ (Wasser, Gas, ...) des Zählers benötigt.
Sind die Daten verschlüsselt wird auch noch der passende Schlüssel benötigt um die Daten entschlüsseln zu können.

== Verschlüsselung ==
Die Daten können auf drei verschiedene Arten verschlüsselt sein:
# Security profile A/Symmetric encryption with Mode 5
# Security profile B/Advanced symmetric encryption with Mode 7
# Security profile C/Asymmetric encryption with Mode 13

Das Modul unterstützt aktuell Daten die per 1 oder 2 verschlüsselt wurden.

== Anwendungsbeispiele ==
Ein per [[EnergyCam]] abgelesener Elektrizitätszähler sieht in FHEM z. B. so aus:
<pre>
Internals:
CUL_MBUS_MSGCNT 29
CUL_MBUS_RAWMSG b1944C4189985051701028A7D7A540000A00405FAD4080002FD08222C1295B8::-67.5
CUL_MBUS_RSSI -67.5
CUL_MBUS_TIME 2014-10-24 22:57:53
DEF FFD 17058599 1 2
DeviceMedium Electricity
DeviceType 2
IODev CUL_MBUS
IdentNumber 17058599
LASTInputDev CUL_MBUS
MSGCNT 29
Manufacturer FFD
NAME WMBUS_FFD_17058599_1_2
NR 49
STATE no errors
TYPE WMBUS
Version 1
addr FFD_17058599_1_2
Readings:
2014-10-24 22:57:53 1_storage_no 0
2014-10-24 22:57:53 1_type VIF_ENERGY_WATT
2014-10-24 22:57:53 1_unit Wh
2014-10-24 22:57:53 1_value 57881000
2014-10-24 22:57:53 2_storage_no 0
2014-10-24 22:57:53 2_type VIF_ACCESS_NO
2014-10-24 22:57:53 2_unit
2014-10-24 22:57:53 2_value 11298
2014-10-24 22:57:53 LQI 184
2014-10-24 22:57:53 RSSI -67.5
2014-10-24 22:57:53 battery ok
2014-10-24 22:57:53 decryption_ok 1
2014-10-24 22:57:53 energy 57881
2014-10-24 22:57:53 is_encrypted 0
2014-10-24 22:57:53 state no errors
2014-10-24 22:57:53 unit kWh
Attributes:
IODev CUL_MBUS
room WMBUS
</pre>

== Bekannte Probleme ==
Obwohl Wireless M-Bus ein standardisiertes Protokoll ist, scheint sich kaum ein Hersteller vollständig daran zu halten bzw. verwendet sog. herstellerspezifische Felder um wichtige Daten zu verpacken.
Aus den bisher beobachteten Datenpaketen ergibt sich
* Qundis (Herstellerkürzel LSE) verwendet herstellerspezifische Datenblöcke für den eigentlichen Zählerstand
* Techem und Hydrometer verwenden ein undokumentiertes Datenformat (CI-Field A2)
:''(Techem Heizkostenverteiler (CI-Field A0) können über das Modul [[TechemHKV]] ausgewertet werden)''
* RWE SmartHome Powercontrol[http://www.rwe-smarthome.de/web/cms/de/1776202/smarthome/informieren/geraete/power-control/] sendet verschlüsselt und der Hersteller gibt nicht den vollständigen Schlüssel an{{Link2Forum|Topic=24517|Message=315949}}

Daher werden bisher erst die [[EnergyCam]] der Firma Q-loud, Zähler von Easymeter und der Kamstrup Multical 21 vollständig unterstützt.
Für den Multical 21 muss eine culfw mit Unterstützung für WMBUS C verwendet werden. Diese ist in der culfw ab dem 24.6.2018 enthalten.

Andere Zähler können auch ohne Probleme funktionieren wenn diese sich an den OMS Standard halten.

== Links ==
* Forumsthread {{Link2Forum|Topic=24517}}
* Protokoll Beschreibung [http://oms-group.org/download4all/]
* Beschreibung des M-BUS Protokolls [http://www.m-bus.com/files/MBDOC48.PDF]
[[Kategorie:Energieverbrauchsmessung]]

WMBUS

2019-08-18T15:00:24Z

Kaihs: Verschlüsselung

{{Infobox Modul
|ModPurpose=Dekodierung von Wireless M-Bus Nachrichten
|ModType=d
|ModForumArea=Sonstige Systeme
|ModTechName=36_WMBUS.pm
|ModOwner=kaihs
}}
[[WMBUS]] ist ein Modul zur Dekodierung von Wireless M-Bus Nachrichten. Solche Nachrichten werden z. B. von Zählern für Wasser, Wärme, Gas und Elektrizität ausgestrahlt.
Wireless M-Bus ist ein Standardprotokoll das von unterschiedlichen Herstellern unterstützt wird.
Das Protokoll unterstützt unterschiedliche Kodierungen des Funksignals, im wesentlichen den S-Mode, T-Mode und C-Mode. Der Empfänger (z. B. ein CUL) muss den selben Modus nutzen wie der Sender (der Zähler).
Wireless M-Bus unterstützt optional die Verschlüsselung der Daten.
Die von einem Zähler gesendeten Daten können sehr unterschiedlich sein und hängen u. a. vom Zählertyp und dessen Hersteller ab.

== Voraussetzungen ==
Das Modul interpretiert nur die Nachrichten die von einen geeigneten Empfänger empfangen werden. Aktuell kann ein [[CUL]] und verwandte Geräte die die culfw[http://culfw.de/culfw.html] verwenden sowie ein Amber Wireless AMB8465M dafür verwendet werden. In der culfw muss die Unterstützung des WMBUS-Protokolls aktiviert sein (#define HAS_MBUS in der Datei board.h des Deviceverzeichnisses). Bei einem CUL mit der Hardwareversion V4 ist das nicht der Fall.

Der CUL muss in FHEM mittels Attribut rfmode=WMBus_S, WMBus_T oder WMBus_C in den zum Zähler passenden Empfangsmodus versetzt werden.

== Anwendung ==
Die Erzeugung des passenden Devices in FHEM geschieht automatisch beim Empfang des ersten Datenpakets eines Zählers. Voraussetzung dafür ist, dass [[autocreate]] aktiv ist.
Alternativ kann ein Device manuell angelegt werden. Dazu wird der Hersteller, die Seriennummer, die Version und der Typ (Wasser, Gas, ...) des Zählers benötigt.
Sind die Daten verschlüsselt wird auch noch der passende Schlüssel benötigt um die Daten entschlüsseln zu können.

== Verschlüsselung ==
Die Daten können auf drei verschiedene Arten verschlüsselt sein:
# Security profile A/Symmetric encryption with Mode 5
# Security profile B/Advanced symmetric encryption with Mode 7
# Security profile C/Asymmetric encryption with Mode 13

Das Modul unterstützt aktuell Daten die per 1 oder 2 verschlüsselt wurden.

== Anwendungsbeispiele ==
Ein per [[EnergyCam]] abgelesener Elektrizitätszähler sieht in FHEM z. B. so aus:
<pre>
Internals:
CUL_MBUS_MSGCNT 29
CUL_MBUS_RAWMSG b1944C4189985051701028A7D7A540000A00405FAD4080002FD08222C1295B8::-67.5
CUL_MBUS_RSSI -67.5
CUL_MBUS_TIME 2014-10-24 22:57:53
DEF FFD 17058599 1 2
DeviceMedium Electricity
DeviceType 2
IODev CUL_MBUS
IdentNumber 17058599
LASTInputDev CUL_MBUS
MSGCNT 29
Manufacturer FFD
NAME WMBUS_FFD_17058599_1_2
NR 49
STATE no errors
TYPE WMBUS
Version 1
addr FFD_17058599_1_2
Readings:
2014-10-24 22:57:53 1_storage_no 0
2014-10-24 22:57:53 1_type VIF_ENERGY_WATT
2014-10-24 22:57:53 1_unit Wh
2014-10-24 22:57:53 1_value 57881000
2014-10-24 22:57:53 2_storage_no 0
2014-10-24 22:57:53 2_type VIF_ACCESS_NO
2014-10-24 22:57:53 2_unit
2014-10-24 22:57:53 2_value 11298
2014-10-24 22:57:53 LQI 184
2014-10-24 22:57:53 RSSI -67.5
2014-10-24 22:57:53 battery ok
2014-10-24 22:57:53 decryption_ok 1
2014-10-24 22:57:53 energy 57881
2014-10-24 22:57:53 is_encrypted 0
2014-10-24 22:57:53 state no errors
2014-10-24 22:57:53 unit kWh
Attributes:
IODev CUL_MBUS
room WMBUS
</pre>

== Bekannte Probleme ==
Obwohl Wireless M-Bus ein standardisiertes Protokoll ist, scheint sich kaum ein Hersteller vollständig daran zu halten bzw. verwendet sog. herstellerspezifische Felder um wichtige Daten zu verpacken.
Aus den bisher beobachteten Datenpaketen ergibt sich
* Qundis (Herstellerkürzel LSE) verwendet herstellerspezifische Datenblöcke für den eigentlichen Zählerstand
* Techem und Hydrometer verwenden ein undokumentiertes Datenformat (CI-Field A2)
:''(Techem Heizkostenverteiler (CI-Field A0) können über das Modul [[TechemHKV]] ausgewertet werden)''
* RWE SmartHome Powercontrol[http://www.rwe-smarthome.de/web/cms/de/1776202/smarthome/informieren/geraete/power-control/] sendet verschlüsselt und der Hersteller gibt nicht den vollständigen Schlüssel an{{Link2Forum|Topic=24517|Message=315949}}

Daher werden bisher erst die [[EnergyCam]] der Firma Q-loud, Zähler von Easymeter und der Kamstrup Multical 21 vollständig unterstützt.
Für den Multical 21 muss eine culfw mit Unterstützung für WMBUS C verwendet werden. Diese ist in der culfw ab dem 24.6.2018 enthalten.

== Links ==
* Forumsthread {{Link2Forum|Topic=24517}}
* Protokoll Beschreibung [http://oms-group.org/download4all/]
* Beschreibung des M-BUS Protokolls [http://www.m-bus.com/files/MBDOC48.PDF]
[[Kategorie:Energieverbrauchsmessung]]

WMBUS

2019-08-18T14:54:43Z

Kaihs: /* Voraussetzungen */

{{Infobox Modul
|ModPurpose=Dekodierung von Wireless M-Bus Nachrichten
|ModType=d
|ModForumArea=Sonstige Systeme
|ModTechName=36_WMBUS.pm
|ModOwner=kaihs
}}
[[WMBUS]] ist ein Modul zur Dekodierung von Wireless M-Bus Nachrichten. Solche Nachrichten werden z. B. von Zählern für Wasser, Wärme, Gas und Elektrizität ausgestrahlt.
Wireless M-Bus ist ein Standardprotokoll das von unterschiedlichen Herstellern unterstützt wird.
Das Protokoll unterstützt unterschiedliche Kodierungen des Funksignals, im wesentlichen den S-Mode, T-Mode und C-Mode. Der Empfänger (z. B. ein CUL) muss den selben Modus nutzen wie der Sender (der Zähler).
Wireless M-Bus unterstützt optional die Verschlüsselung der Daten per AES.
Die von einem Zähler gesendeten Daten können sehr unterschiedlich sein und hängen u. a. vom Zählertyp und dessen Hersteller ab.

== Voraussetzungen ==
Das Modul interpretiert nur die Nachrichten die von einen geeigneten Empfänger empfangen werden. Aktuell kann ein [[CUL]] und verwandte Geräte die die culfw[http://culfw.de/culfw.html] verwenden sowie ein Amber Wireless AMB8465M dafür verwendet werden. In der culfw muss die Unterstützung des WMBUS-Protokolls aktiviert sein (#define HAS_MBUS in der Datei board.h des Deviceverzeichnisses). Bei einem CUL mit der Hardwareversion V4 ist das nicht der Fall.

Der CUL muss in FHEM mittels Attribut rfmode=WMBus_S, WMBus_T oder WMBus_C in den zum Zähler passenden Empfangsmodus versetzt werden.

== Anwendung ==
Die Erzeugung des passenden Devices in FHEM geschieht automatisch beim Empfang des ersten Datenpakets eines Zählers. Voraussetzung dafür ist, dass [[autocreate]] aktiv ist.
Alternativ kann ein Device manuell angelegt werden. Dazu wird der Hersteller, die Seriennummer, die Version und der Typ (Wasser, Gas, ...) des Zählers benötigt.
Sind die Daten verschlüsselt wird auch noch der passende Schlüssel benötigt um die Daten entschlüsseln zu können.

== Anwendungsbeispiele ==
Ein per [[EnergyCam]] abgelesener Elektrizitätszähler sieht in FHEM z. B. so aus:
<pre>
Internals:
CUL_MBUS_MSGCNT 29
CUL_MBUS_RAWMSG b1944C4189985051701028A7D7A540000A00405FAD4080002FD08222C1295B8::-67.5
CUL_MBUS_RSSI -67.5
CUL_MBUS_TIME 2014-10-24 22:57:53
DEF FFD 17058599 1 2
DeviceMedium Electricity
DeviceType 2
IODev CUL_MBUS
IdentNumber 17058599
LASTInputDev CUL_MBUS
MSGCNT 29
Manufacturer FFD
NAME WMBUS_FFD_17058599_1_2
NR 49
STATE no errors
TYPE WMBUS
Version 1
addr FFD_17058599_1_2
Readings:
2014-10-24 22:57:53 1_storage_no 0
2014-10-24 22:57:53 1_type VIF_ENERGY_WATT
2014-10-24 22:57:53 1_unit Wh
2014-10-24 22:57:53 1_value 57881000
2014-10-24 22:57:53 2_storage_no 0
2014-10-24 22:57:53 2_type VIF_ACCESS_NO
2014-10-24 22:57:53 2_unit
2014-10-24 22:57:53 2_value 11298
2014-10-24 22:57:53 LQI 184
2014-10-24 22:57:53 RSSI -67.5
2014-10-24 22:57:53 battery ok
2014-10-24 22:57:53 decryption_ok 1
2014-10-24 22:57:53 energy 57881
2014-10-24 22:57:53 is_encrypted 0
2014-10-24 22:57:53 state no errors
2014-10-24 22:57:53 unit kWh
Attributes:
IODev CUL_MBUS
room WMBUS
</pre>

== Bekannte Probleme ==
Obwohl Wireless M-Bus ein standardisiertes Protokoll ist, scheint sich kaum ein Hersteller vollständig daran zu halten bzw. verwendet sog. herstellerspezifische Felder um wichtige Daten zu verpacken.
Aus den bisher beobachteten Datenpaketen ergibt sich
* Qundis (Herstellerkürzel LSE) verwendet herstellerspezifische Datenblöcke für den eigentlichen Zählerstand
* Techem und Hydrometer verwenden ein undokumentiertes Datenformat (CI-Field A2)
:''(Techem Heizkostenverteiler (CI-Field A0) können über das Modul [[TechemHKV]] ausgewertet werden)''
* RWE SmartHome Powercontrol[http://www.rwe-smarthome.de/web/cms/de/1776202/smarthome/informieren/geraete/power-control/] sendet verschlüsselt und der Hersteller gibt nicht den vollständigen Schlüssel an{{Link2Forum|Topic=24517|Message=315949}}

Daher werden bisher erst die [[EnergyCam]] der Firma Q-loud, Zähler von Easymeter und der Kamstrup Multical 21 vollständig unterstützt.
Für den Multical 21 muss eine culfw mit Unterstützung für WMBUS C verwendet werden. Diese ist in der culfw ab dem 24.6.2018 enthalten.

== Links ==
* Forumsthread {{Link2Forum|Topic=24517}}
* Protokoll Beschreibung [http://oms-group.org/download4all/]
* Beschreibung des M-BUS Protokolls [http://www.m-bus.com/files/MBDOC48.PDF]
[[Kategorie:Energieverbrauchsmessung]]

Weather

2019-07-21T13:38:31Z

Kaihs: Einschränkungen von OpenWeatherMap

{{Hinweis|'''End of Live der Yahoo Weather API'''<br />
Da die Yahoo Weather API zum 03.01.2019 abgeschaltet wurde, kann '''Weather''' keine Wetterdaten von Yahoo mehr beziehen!}}

{{SEITENTITEL:Weather}}
{{
Infobox Modul
|ModPurpose=Wettervorhersagen von Yahoo abfragen.
|ModType=d

|ModCmdRef=Weather
|ModForumArea=Unterstützende Dienste/Wettermodule
|ModTechName=59_Weather.pm
|ModOwner=Dr. Boris Neubert
}}

Mit dem Modul [[Weather]] können aktuelle Wetterdaten und Wettervorhersagen für einen bestimmten Ort von der Yahoo-Wetter-API regelmäßig abgefragt werden.

== Anwendung ==
=== Define ===
siehe {{Link2CmdRef|Lang=de|Anker=Weatherdefine}}.

=== Attribute ===
siehe {{Link2CmdRef|Lang=de|Anker=Weatherattr}}.

=== API Besonderheiten ===
Das Openweathermap API liefert nur stundenweise Daten für drei Tage.
Daher funktioniert dass Attribut forecast daily nicht.

== Anwendungsbeispiele ==
=== Beispiel zur Modul-Einrichtung ===
Zuerst einmal besuchen wir die [http://weather.yahoo.com Yahoo Wetterseite] und öffnen den Wetterbericht für die jeweilige Stadt (z.B. [http://weather.yahoo.com/germany/berlin/berlin-638242 Berlin]). In der URL des Wetterberichtes findet sich dann die sogenannte WOEID (WHERE-ON-EARTH-ID). Sie identifiziert die Wetterinfos, die FHEM abfragen soll. Für Berlin ist dies die Nummer 638242.

In der [[Konfiguration]] richten wir dann folgendes ein:

<pre>
# – Wetterdaten erfassen -
define MeinWetter Weather 638242 3600 de
attr MeinWetter room Wettervorhersage

# - Logfile für alle Wetter Daten (monatsweise getrennt) —
define FileLog_MeinWetter FileLog ./log/meinwetter-%Y-%m.log MeinWetter
attr FileLog_MeinWetter logtype text
attr FileLog_MeinWetter room Wettervorhersage

# — Wetter Icons in vertikaler Ansicht hinzufügen —
define weblink_meinwetter weblink htmlCode {WeatherAsHtml("MeinWetter",7)}
attr weblink_meinwetter room Wettervorhersage
</pre>

Das hat zur Folge, dass FHEM nun die Wetterdaten für Berlin (638242) jede Stunde (3600) neu abholt. Zudem wird eine vertikale Ansicht der Wetterdaten der nächsten 7 Tage erstellt. Die Anzeige erfolgt im Raum "Wettervorhersage".

=== Konfigurationsschwierigkeiten ===

Da Yahoo momentan auf mehreren Browsern Darstellungs-Schwierigkeiten hat, ist es schwer bis unmöglich, nach bestimmten Städten zu suchen (Search Box ist nicht erreichbar).

Für diesen Fall gibt es aber noch die Möglichkeit, die WOEID auf [https://www.computerhilfen.de/hilfen-64-422419-0.html Yahoo WOEID: So bekommt man die "Where on Earth" ID einer Stadt!] zu erhalten.
Erfolgreich gefunden habe ich diese Seite übrigens über den Trick einer Internet-Suche nach ''mehreren'' dominant bekannten Städte-IDs (oder vielleicht einfach Internet-Suche nach "WOEID").

== Links ==
* Weblink mit Stadtangabe für Wetter-Icons-Anzeige definieren: {{Link2Forum|Topic=31428|Message=267555}}
* Einrichtung einer automatische Aktualisierung der Wetter-Anzeige-Seite (Weblinks): {{Link2Forum|Topic=34581|Message=268957}}
* Anzahl der Icons definieren: {{Link2Forum|Topic=20481|Message=253464}}

TRÅDFRI

2019-01-26T09:54:35Z

Kaihs: /* HUE-Device */

{{Baustelle}}

<div style="float:right">{{Infobox Modul
|Name=tradfri
|ModPurpose=Anbindung IKEA TRÅDFRI Gateway
|ModType=d

|ModCmdRef=tradfri
|ModForumArea=Zigbee
|ModTechName=30_tradfri.pm
|ModOwner=Andre ([http://forum.fhem.de/index.php?action=profile;u=430 Forum] / [[Benutzer Diskussion:justme|Wiki]])
}}
</div>

== tradfri ==

=== Einrichtung in FHEM ===

# node installieren (mindestens version 8)
# sudo ppm install -g tradfri-fhem
# <code>define <tradfri> tradfri</code>
# <code>attr <tradfri> tradfriFHEM-securityCode <security code></code>

wenn das gateway nicht automatisch erkannt wird:
<code>attr <tradfri> tradfriFHEM-params --ip <ip></code>{{Randnotiz|RNTyp=r|RNText=Das Modul ist noch nicht eingecheckt und bis auf weiteres hier zu finden:{{Link2Forum|Topic=95272}} }}

WICHTIG: danach in FHEM einmal die Konfiguration speichern damit der Pairing-Key gesichert wird. Sonst muss beim nächsten FHEM-Neustart das Pairing erneut durchgeführt werden.

== HUE-Device ==
Alle auf dem Gateway bekannten Geräte automatisch als [[Hue#HUE-Device|HUEDevice]] in FHEM angelegt:
* Lampen, Stecker, Trafos, ...
: Hiermit werden die einzelnen Leuchten gesteuert
* Gruppen
: Hiermit lassen sich ganze Gruppen und Räume steuern
* Fernbedienungen
: aktuell gibt es nur ein battery Reading

=== Darstellung im Webfrontend ===
Wenn man die SVG Icons verwendet ist es sinnvoll, das Attribut color-icons zu setzen. Mit <code>attr HUEDevice1 color-icons 2</code> werden z.B. die Farben und der Dimmzustand der Lampe als Icon dargestellt.
Damit das ganze funktioniert, müsst ihr auch noch das <code>attr WEB iconPath fhemSVG:openautomation:default</code> setzen.

[[Kategorie:ZigBee Components]]
[[Kategorie:ZigBee]]
[[Kategorie:Lichteffektgeräte]]
[[Kategorie:IP Components]]

Hue

2019-01-24T20:42:33Z

Kaihs: /* HUE-Device */ Müller Licht tint

<div style="float:right">{{Infobox Modul
|Name=HUEBridge
|ModPurpose=Anbindung Bridge des Philips Hue Lighting System
|ModType=d

|ModCmdRef=HUEBridge
|ModForumArea=Beleuchtung
|ModTechName=30_HUEBridge.pm
|ModOwner=Andre ([http://forum.fhem.de/index.php?action=profile;u=430 Forum] / [[Benutzer Diskussion:justme|Wiki]])
}}
{{Infobox Modul
|Name=HUEDevice
|ModPurpose=Ansteuerung Geräte des Philips Hue Lighting System über HUEBridge
|ModType=d

|ModCmdRef=HUEDevice
|ModForumArea=Beleuchtung
|ModTechName=31_HUEDevice.pm
|ModOwner=Andre ([http://forum.fhem.de/index.php?action=profile;u=430 Forum] / [[Benutzer Diskussion:justme|Wiki]])
}}
</div>

== HUE-Bridge ==

=== Einrichtung in fhem ===
Die Einrichtung ist wirklich einfach. Mit

<code>define Wiesollesheißen HUEBridge eu.re.ip.1</code>

wird die Bridge eingebunden. Dann einfach auf den runden Knopf in der Mitte der Bridge drücken und sie wird von FHEM erkannt. Die drei Lampen des Starterkits werden automatisch erkannt und sind ansteuerbar -> fertig!

WICHTIG: danach in FHEM einmal die Konfiguration speichern damit der Pairing-Key gesichert wird. Sonst muss beim nächsten FHEM-Neustart das Pairing erneut durchgeführt werden.

Eine ausführliche Anleitung mit Bildern zudem unter: http://www.meintechblog.de/2014/11/philips-hue-so-klappt-die-integration-in-fhem/

Falls die Hue Bridge resetet wurde bleibt der Status auf "paired" und geht nicht mehr auf connected. Um das paring erneut durchzuführen muss das Attribut "key" gelöscht werden.

=== Nonblocking ===
Wenn man möchte, dass die Versuche, die HUEBridge zu kontaktieren, FHEM nicht blockieren, sollte man

<pre>attr <HUEBridge_Name> httpUtils 1</pre>

setzen.

== HUE-Device ==
Als Gerät können alle Hue und LightLink kompatiblen Modelle verwendet werden. Dies sind unter anderem:
*HueBulbs (E27, GU10, Lux, White, ...)
*Hue Beyond und Phoenix
*Friends of Hue LightStrips und LivingColors Bloom
*LivingColors ab gen2
*LivingColors Bloom, Iris und Aura
*LivingWhites Energiesparlampen
*LivingWhites Leuchtenadapter
*LivingWhites Bulbs
*[[HUE_Dimmer_Switch|Hue Tap und Hue Dimmer]] (mit Einschränkungen)
*dresden elektronik Vorschaltgeräte
*OSRAM LIGHTIFY Lampen (an der Hue Bridge angelernt)
*Müller Licht tint

Diese sind jeweils über eine Bridge (HueDevice) steuerbar. Die LivingColors und LivingWhites Geräte sind vorher mit Hilfe einer LivingColors oder LivingWhites Fernbedienung an der Bridge anzulernen.

Es werden auch alle HUE Sensoren unterstützt. Diese werden aber nicht per autocreate angelegt sondern müssen manuell definiert werden. Hier ist auf ein passendes polling Intervall zu achten. Siehe: [[HUE_Dimmer_Switch|HUE Dimmer Switch]]. Das [[Hue#RaspBee|RaspBee]] Gateway unterstützt auch ein PushAPI über das Sensoren ohne polling eingebunden werden können.

=== Grundlagen - Farbmodelle ===
Ein HueDevice kann per set-Befehl über unterschiedliche Farbmodelle gesteuert werden. In der folgenden Tabelle ist dargestellt, welche Werte-Kombinationen sinnvoll sind:
{| class="wikitable"
|-
! Farbmodell !! Bestandteile !! Beispiel
|-
| xyY || x- und y-Koordinate im Farbraum, Y ist die Helligkeit || <code> set bulb1 xy 0.4595,0.4105 : bri 220 </code>
|-
| hue,sat,bri || Farbwert, Sättigung und Helligkeit || <code> set bulb1 hue 14922 : sat 144 : bri 220 </code>
|-
| ct || Farbwert über Farbtemperatur || <code> set bulb1 color 2600 </code>
|-
| rgb || Farbbestandteile rot, grün und blau || <code> set bulb1 rgb FFC698 </code>
|}
'''Hinweis:''' Zur Regelung der Helligkeit sind die Befehle ''bri'' und ''pct'' gleichwertig. ''bri'' hat den Bereich 0..254, ''pct'' 0..100 .<br>
Das Modul lässt die Mischung von Angaben aus unterschiedlichen Farbmodellen technisch zu, jedoch sind diese nicht immer sinnvoll.

=== Darstellung im Webfrontend ===
Wenn man die SVG Icons verwendet ist es sinnvoll, das Attribut color-icons zu setzen. Mit <code>attr HUEDevice1 color-icons 2</code> werden z.B. die Farben und der Dimmzustand der Lampe als Icon dargestellt.
Damit das ganze funktioniert, müsst ihr auch noch das <code>attr WEB iconPath fhemSVG:openautomation:default</code> setzen.

== RaspBee & ConBee ==
Das HUEBridge Modul unterstützt auch die ZigBee Gateway Module RaspBee und ConBee von Dresden Elektronik über die zugehörige deCONZ Software und die Wireless Light Control WebApp und die Phoscon WebApp (kommt zusammen mit deConz). Die hierzu erhältlichen Funk-Vorschaltgeräte sind noch nicht getestet sollten aber auch funktionieren.

Im {{Link2Forum|Topic=80985|LinkText=Forum}} gibt es eine Betaversion der HUE Module, die das deCONZ PushAPI über Websockets unterstützen. Sensoren müssen hier nicht mehr gepollt werden.

Mittlerweile funktioniert die Einbindung der RaspBee und ConBee Module auf einem sehr einfachen Weg. Dieser ist in {{Link2Forum|Topic=95288|LinkText=Forum}} zusammengefasst. Zusätzliche Plugins sind nicht mehr nötig.

== HUE auf der Fritzbox ==
Da auf der FB standardmäßig kein JSON installiert ist, muss dies nachinstalliert werden: Man lädt das JSON-Paket http://search.cpan.org/CPAN/authors/id/M/MA/MAKAMAKA/JSON-2.53.tar.gz, packt es aus und kopiert den Inhalt vom <b>lib-Verzeichnis</b> nach \fhem\lib\perl5\site_perl\5.12.2

== HUE auf der Synology Diskstation ==
Da auf der DS standardmäßig kein JSON installiert ist, muss dies nachinstalliert werden, die Anleitung dazu {{Link2Forum|Topic=19093|Message=224641|LinkText=hier}}

[[Kategorie:ZigBee Components]]
[[Kategorie:ZigBee]]
[[Kategorie:Lichteffektgeräte]]
[[Kategorie:IP Components]]

Creating Plots

2019-01-01T20:14:25Z

Kaihs: Änderung 28905 von Kaihs (Diskussion) rückgängig gemacht.

{{Randnotiz|RNTyp=[g|Info]|RNText=Hier wird das Anlegen per Hand beschrieben, was für Ungeübte umständlich und nicht empfehlenswert ist.
Mit "Create SVG Plot" in der FileLog-Detail-Ansicht steht inzwischen zur Vereinfachung ein Konfigurations-Frontend zur Verfügung: [[Plots_erzeugen|.gplot-Editor]].}}
= Howto create a PGM2/SVG plot - Introduction =
Output using the PGM2 engine is generated through .gplot files. The name is historical and today files can be generated using gnuplot or SVG graphics. This howto lists the most important aspects of generating a SVG configuration file.

Each graphic generated by FHEM is described by one configuration file. It is currently not possible to generate one page with several graphics from one configuration file.

Taking a high level view for each plot the following is needed:

* Data from a logfile (create it using the FileLog facility)
* Plot configuration (.gplot) file knowing about the internal structure of the logfile
* Association between the FileLog and the plot configuration (using the "logtype" attribute in the FileLog and the LINK in the WebLink object, also see comments below)
* Weblink representing the plot itself
= FileLog objects =
Digging into the more murky details, first thing is the creation of the FileLog object:

* The FileLog object is always associated with a physical device (but see comments below)
* The creation of a FileLog object together with the corresponding logfile is automatic if the "autocreate" attribute is set in FHEM (it is set by default)
* Manual creation is also possible and requires a statement like:
<nowiki>
define FL_KS550 FileLog /var/log/fhem/KS550_%Y.log KS550:T:.*
define FileLog_ZwSt_1 FileLog /opt/fhem/var/log/ZwSt_1_%Y.log ZwSt_1
define FL_ZwSt_ALL FileLog /opt/fhem/var/log/ZwSt_ALL_%Y.log ZwSt_.*deviceMsg.*BidCoS_RF.*
</nowiki>
* Be it manual or automatic: the definition of a FileLog object determines (through the regular expression) which of the output lines of FHEM end up in the logfile

= Plot definition =
Once the logfile is accumulating data, the plot configuration itself is needed. There is no object for this, but plain .gplot files in the share/FHEM directory are used by the system. A good start is to copy an existing one and modify it.

On a side note: if you create your own files instead of using the ones already delivered with FHEM, stick to the convention of prepending them with a "my". Files of pattern "my*" are guaranteed not to be overwritten during FHEM updates (or so Rudi promised me).

The following entries are recognized in a SVG context:

* #FileLog holds the information which data need to be extracted from the logfile. See below for details.
* Set commands: title, ylabel, y2label, yrange, y2range, ytics, y2tics, teminal (only "size" parameter is recognized)
* Plot command: see below for details
== Placeholders ==
It is possible to use placeholders in the .gplot files, which will then be replaced by information provided by the actual WebLink attributes listed below. This has the advantage that you can define one .gplot file and re-use it for several devices, changing size, title and lables accordingly instead of maintaining several separated files.

* <OUT> : only relevant for gnuplot
* <SIZE>: attr plotsize
* <TL> : attr title. The attribute is eval'ed by perl at runtime, be careful and protect by double quotes if you just want to enter strings. This gives access to all internal FHEM values, though admittedly not straightforward
* <Ln> : attr label. Lables 1-#n can be specified by a double-colon-separated (::) list, see below. This is also eval'ed at runtime, same precautions apply
* <IN> :

In general this is good practice and you should especially consider it if you plan to distribute your .gplot files. Using placeholders f.ex. for the title and all the labels and curve descriptors gives other users the possibility to change them without having to touch the .gplot code.

== Data Extraction ==
The central piece of the plotfile is the #FileLog line (yes, it must be prepended by a hash!), which is a special command und internally triggers the use of the FileLog "get" function, which extracts data from the logfile. The general syntax is: <nowiki><col>:<regexp>:<default>:<fn></nowiki>
.
* col: selects the column of the line (columns are white space separated, numbering starts at 1)
* regexp: validates/selects the line
* default: default value, if none is present
* fn: function which operates on values, pre-defined or eval'ed, see below

The "get" function will set the following %data values (which can e.g. be used in titles, labels, ...) for each requested column (curve), beggining with <x> = 1:

* min<x>, max<x>
* mindate<x>, maxdate<x>
* avg<x>, cnt<x>
* sum<x>
* currval<x> (last value)
* currdate<x> (last date)
So you can do something like <nowiki>attr <weblink> title "Min $data{min1}, Max $data{max1}, Last $data{currval1}"</nowiki>
Also implemented in this function is code which operates on the data retrieved. This can be specified at the "<fn>" tag. Up till now following functions are impemented:

* int (to cut off % from a number, as for the actuator)
* delta-h / delta-d to get rain/h and rain/d values from continuous data
* And then there is this: the string is evaluated as a perl expression. @fld is the current line splitted by spaces (0-based). So you can do something like $fld[3]/1000 to plot values divided by 1000 or $fld[3]=~"on"?0.9:0.8 to map the 4th field which contains an on/off information into numerical values to be plotted in a graph. Be warned though: this string/perl expression cannot (!) contain any spaces.

For even more details see [http://fhem.de/commandref.html#FileLog http://fhem.de/commandref.html#FileLog] or the module 92_FileLog.pm.

== Debugging Data Extraction ==
If you do not get the result you are expecting or, worse, no data at all, you may use the debug facility of FHEM to see what the get-command extracts from the logfile. Use telnet to contact FHEM and then use the arguments detailed below ending with the #FileLog argument you are using in the .gplot file:

<nowiki>telnet diskstation 7072
get FileLog_KS550 ?
get FileLog_KS550 - - 2012-01-01 2012-12-31 4::</nowiki>
You should get back the data which you have been asking for, followed by a line holding the .gplot argument. Make sure

* you do not select too much data, this will possibly upset your NAS :-)
* you do select data which really are in the file (beware of year/month changes)
== Plot Commands ==
Once you have extracted the data from the logfile, you need to plot it. There is a plot command which does just that. It has several arguments which you can use:

* axes: not needed by default, but if you want to plot curves which use different y axes, then you must tell the plot command, which y-axis the data should be bound to: "axes x1y1" selects the left, "axes x1y2" the right one
* title: defines the string which is printed in the colour of the curve into the plot. You can (and maybe should) use placeholders like "<Lx>", x being a number
* with: defines how to draw the data. only points, steps, histeps and lines (which acts as a catch all) are currently implemented
* ls: uses CSS definitions, still need to figure out, how this works
* lw: defines the width of a line
== Example ==
A very barebones but functional example of a file using placeholders could be:

<nowiki>set terminal size <SIZE>
set title '<TL>'
set ylabel '<L1>'
set y2label '<L2>'
#FileLog 4:::
plot \
axes x1y1 title '<L3>' with steps lw 2</nowiki>
It implements the placeholders which can be defined by the user through the WebLink attributes later, selects just one column, without regular expression matches, defaults or subsequent data operations and plot is as a steps diagram. In fact even the "axes x1y1" statement could be left out, it would still work.

== Changing text style ==
If you need a text style that is different from the style definition in fhemweb:
Add

<nowiki>text { font-family:Arial, Helvetica, sans-serif; font-size:12px; fill:#xxxxxx;}
text.title {font-family:Arial, Helvetica, sans-serif; font-size:16px; fill:#xxxxxx;}</nowiki>

where #xxxxxx is the color.

== Transparent plots ==
If you need transparent plots, for example in FLOORPLAN, you have to change the following definitions in svg_style.css

Change

<nowiki>.background { fill:#FFFFE7; }</nowiki>
to:

<nowiki>.background { fill:#FFFFE7;fill-opacity: 0; }</nowiki>
Change:

<nowiki>.border { stroke:black; fill:url(#gr_bg); }</nowiki>
to

<nowiki>.border { stroke:black; fill:url(#gr_bg);fill-opacity: 0; }</nowiki>

= WebLink objects =
Once you have created the FileLog object and written the plot specification, there is not much to be done. Click on the reference to the .gplot file in the FileLog section of a device, then click on the link for WebLink creation and then add the attributes you want to have. Put it into a suitable room and you are done.

If you are using placeholders in your .gplot files and after defining your .gplot file you click onto a FileLog "active" link to create the plot itself and get a message like:

<nowiki>XML Parsing Error: mismatched tag. Expected: </L1>.
...
Line Number 51, Column 95:<text x="12" y="80" text-anchor="middle" class="ylabel" transform="rotate(270,12,80)">'<L1>'</text></nowiki>
you can safely ignore it. This is due to the fact, that you are using placeholders in the .gplot definition (which is good, because it favors reuseability) but have not yet defined the corresponding attributes. While annoying, this is not your fault: you can only define attributes once you have a weblink. So click on create weblink and define the attributes you have been using placeholders for. The error message should go away.

The attributes which are generally needed are:

* label: should be defined like "Label 1"::"Label 2". Do not omit double quotes and use them individually for each label. Separator is a double (!) colon. If you ever manage to do away with the double quotes on the axes, please let us all know
* title: Can be as simple as "Some Title" or as complicated as "Temperature $data{currval1} ($data{min1}-$data{max1}), Humidity $data{currval2} ($data{min2}-$data{max2}) @ $data{currdate1}"

= SVG Programs =
The SVG programs can be found in the 98_SVG.pm module. Look for example for the string "histeps". Feel free to adapt and improve. If you ever program a wind rose to plot wind directions, please let me know.

= Details =
What you also should know:

* All data used in a plot come from one (!) file. It is currently not possible to mix data from several files. So make sure that the regular expression of the FileLog object catches everything which you need in one plot
* While it first seems evident that FileLog objects are associated with a given device, this must be mitigated. Imagine that you want to plot the state (and changes) of some socket adaptors (ZwischenStecker) over time. You then need to gather all the data (from several devices) in one file. So instead of define FileLog_ZwSt_1 FileLog /opt/fhem/var/log/ZwSt_1_%Y.log ZwSt_1 you need to specify define FL_ZwSt_ALL FileLog /opt/fhem/var/log/ZwSt_ALL_%Y.log ZwSt_.*deviceMsg.*BidCoS_RF.*
* Be careful when specifying the regular expression which filters the lines for a given logfile. While often it is sufficient to not specify a specific one at all, consider the following case from the Homematic world, where one action results in 4 lines of FHEM output. The switch communicates not only with the CCU, but also with the remote control, issuing 2 lines for each action:
<nowiki>2012-01-01_07:40:23 ZwSt_3 deviceMsg: on (to Dev.WDisp.Kueche)
2012-01-01_07:40:23 ZwSt_3 on
2012-01-01_07:40:26 ZwSt_3 deviceMsg: on (to BidCoS_RF)
2012-01-01_07:40:26 ZwSt_3 on</nowiki>
* Why one needs to specify a logtype (which is nothing else than a plot definition) for the FileLog has always been a mystery to me. It holds no useful information to the object itself and does not influence the way data is written to the associated logfile. Sure, plots need FileLogs, but not the other way round. And since the WebLink contains (again) the name of the plot definition file, the need to define the logtype attribute seems odd. The master himself says regarding this topic: "Ist eine Eigenschaft, die beschreibt, auf welche Art die Daten angezeigt werden koennen. Steht damit direkt neben den Daten, also da wo ich zuerst suchen wuerde. Ist nicht notwendig, aber so kann FHEMWEB ein 'create weblink' anbieten." I have to admit that this link is useful and I use to use it :-)
* If you meet on your way PERL-code snippets in the .gplot files, you can just ignore them safely. They are only used in the gnuplot world, not in SVG anymore. Now you may ask, where you find the corresponding features in SVG? They are hidden in functions defined in the FileLog "get" primitive.

== Documentation ==
Documentation can be found in several places, it is not complete and you need to piece it together:

* [http://fhem.de/HOWTO.html#plotting http://fhem.de/HOWTO.html#plotting]
* [http://fhem.de/commandref.html#FileLogget http://fhem.de/commandref.html#FileLogget]
* [http://fhem.de/commandref.html#label http://fhem.de/commandref.html#label]

[[Kategorie:HOWTOS]]

Creating Plots

2019-01-01T20:13:53Z

Kaihs: Änderung 28904 von Kaihs (Diskussion) rückgängig gemacht.

{{Randnotiz|RNTyp=[g|Info]|RNText=Hier wird das Anlegen per Hand beschrieben, was für Ungeübte umständlich und nicht empfehlenswert ist.
Mit "Create SVG Plot" in der FileLog-Detail-Ansicht steht inzwischen zur Vereinfachung ein Konfigurations-Frontend zur Verfügung: [[Plots_erzeugen|.gplot-Editor]].}}
= Howto create a PGM2/SVG plot - Introduction =
Output using the PGM2 engine is generated through .gplot files. The name is historical and today files can be generated using gnuplot or SVG graphics. This howto lists the most important aspects of generating a SVG configuration file.

Each graphic generated by FHEM is described by one configuration file. It is currently not possible to generate one page with several graphics from one configuration file.

Taking a high level view for each plot the following is needed:

* Data from a logfile (create it using the FileLog facility)
* Plot configuration (.gplot) file knowing about the internal structure of the logfile
* Association between the FileLog and the plot configuration (using the "logtype" attribute in the FileLog and the LINK in the WebLink object, also see comments below)
* Weblink representing the plot itself
= FileLog objects =
Digging into the more murky details, first thing is the creation of the FileLog object:

* The FileLog object is always associated with a physical device (but see comments below)
* The creation of a FileLog object together with the corresponding logfile is automatic if the "autocreate" attribute is set in FHEM (it is set by default)
* Manual creation is also possible and requires a statement like:
<nowiki>
define FL_KS550 FileLog /var/log/fhem/KS550_%Y.log KS550:T:.*
define FileLog_ZwSt_1 FileLog /opt/fhem/var/log/ZwSt_1_%Y.log ZwSt_1
define FL_ZwSt_ALL FileLog /opt/fhem/var/log/ZwSt_ALL_%Y.log ZwSt_.*deviceMsg.*BidCoS_RF.*
</nowiki>
* Be it manual or automatic: the definition of a FileLog object determines (through the regular expression) which of the output lines of FHEM end up in the logfile

= Plot definition =
Once the logfile is accumulating data, the plot configuration itself is needed. There is no object for this, but plain .gplot files in the share/FHEM directory are used by the system. A good start is to copy an existing one and modify it.

On a side note: if you create your own files instead of using the ones already delivered with FHEM, stick to the convention of prepending them with a "my". Files of pattern "my*" are guaranteed not to be overwritten during FHEM updates (or so Rudi promised me).

The following entries are recognized in a SVG context:

* #FileLog holds the information which data need to be extracted from the logfile. See below for details.
* Set commands: title, ylabel, y2label, yrange, y2range, ytics, y2tics, teminal (only "size" parameter is recognized)
* Plot command: see below for details
== Placeholders ==
It is possible to use placeholders in the .gplot files, which will then be replaced by information provided by the actual WebLink attributes listed below. This has the advantage that you can define one .gplot file and re-use it for several devices, changing size, title and lables accordingly instead of maintaining several separated files.

* <OUT> : only relevant for gnuplot
* <SIZE>: attr plotsize
* <TL> : attr title. The attribute is eval'ed by perl at runtime, be careful and protect by double quotes if you just want to enter strings. This gives access to all internal FHEM values, though admittedly not straightforward
* <Ln> : attr label. Lables 1-#n can be specified by a double-colon-separated (::) list, see below. This is also eval'ed at runtime, same precautions apply
* <IN> :

In general this is good practice and you should especially consider it if you plan to distribute your .gplot files. Using placeholders f.ex. for the title and all the labels and curve descriptors gives other users the possibility to change them without having to touch the .gplot code.

== Data Extraction ==
The central piece of the plotfile is the #FileLog line (yes, it must be prepended by a hash!), which is a special command und internally triggers the use of the FileLog "get" function, which extracts data from the logfile. The general syntax is: <nowiki><col>:<regexp>:<default>:<fn></nowiki>
.
* col: selects the column of the line (columns are white space separated, numbering starts at 1)
* regexp: validates/selects the line
* default: default value, if none is present
* fn: function which operates on values, pre-defined or eval'ed, see below

The "get" function will set the following %data values (which can e.g. be used in titles, labels, ...) for each requested column (curve), beggining with <x> = 1:

* min<x>, max<x>
* mindate<x>, maxdate<x>
* avg<x>, cnt<x>
* sum<x>
* currval<x> (last value)
* currdate<x> (last date)
So you can do something like <nowiki>attr <weblink> title "Min $data{min1}, Max $data{max1}, Last $data{currval1}"</nowiki>
Also implemented in this function is code which operates on the data retrieved. This can be specified at the "<fn>" tag. Up till now following functions are impemented:

* int (to cut off % from a number, as for the actuator)
* delta-h / delta-d to get rain/h and rain/d values from continuous data
* And then there is this: the string is evaluated as a perl expression. @fld is the current line splitted by spaces (0-based). So you can do something like $fld[3]/1000 to plot values divided by 1000 or $fld[3]=~"on"?0.9:0.8 to map the 4th field which contains an on/off information into numerical values to be plotted in a graph. Be warned though: this string/perl expression cannot (!) contain any spaces.

For even more details see [http://fhem.de/commandref.html#FileLogger http://fhem.de/commandref.html#FileLogget] or the module 92_FileLog.pm.

== Debugging Data Extraction ==
If you do not get the result you are expecting or, worse, no data at all, you may use the debug facility of FHEM to see what the get-command extracts from the logfile. Use telnet to contact FHEM and then use the arguments detailed below ending with the #FileLog argument you are using in the .gplot file:

<nowiki>telnet diskstation 7072
get FileLog_KS550 ?
get FileLog_KS550 - - 2012-01-01 2012-12-31 4::</nowiki>
You should get back the data which you have been asking for, followed by a line holding the .gplot argument. Make sure

* you do not select too much data, this will possibly upset your NAS :-)
* you do select data which really are in the file (beware of year/month changes)
== Plot Commands ==
Once you have extracted the data from the logfile, you need to plot it. There is a plot command which does just that. It has several arguments which you can use:

* axes: not needed by default, but if you want to plot curves which use different y axes, then you must tell the plot command, which y-axis the data should be bound to: "axes x1y1" selects the left, "axes x1y2" the right one
* title: defines the string which is printed in the colour of the curve into the plot. You can (and maybe should) use placeholders like "<Lx>", x being a number
* with: defines how to draw the data. only points, steps, histeps and lines (which acts as a catch all) are currently implemented
* ls: uses CSS definitions, still need to figure out, how this works
* lw: defines the width of a line
== Example ==
A very barebones but functional example of a file using placeholders could be:

<nowiki>set terminal size <SIZE>
set title '<TL>'
set ylabel '<L1>'
set y2label '<L2>'
#FileLog 4:::
plot \
axes x1y1 title '<L3>' with steps lw 2</nowiki>
It implements the placeholders which can be defined by the user through the WebLink attributes later, selects just one column, without regular expression matches, defaults or subsequent data operations and plot is as a steps diagram. In fact even the "axes x1y1" statement could be left out, it would still work.

== Changing text style ==
If you need a text style that is different from the style definition in fhemweb:
Add

<nowiki>text { font-family:Arial, Helvetica, sans-serif; font-size:12px; fill:#xxxxxx;}
text.title {font-family:Arial, Helvetica, sans-serif; font-size:16px; fill:#xxxxxx;}</nowiki>

where #xxxxxx is the color.

== Transparent plots ==
If you need transparent plots, for example in FLOORPLAN, you have to change the following definitions in svg_style.css

Change

<nowiki>.background { fill:#FFFFE7; }</nowiki>
to:

<nowiki>.background { fill:#FFFFE7;fill-opacity: 0; }</nowiki>
Change:

<nowiki>.border { stroke:black; fill:url(#gr_bg); }</nowiki>
to

<nowiki>.border { stroke:black; fill:url(#gr_bg);fill-opacity: 0; }</nowiki>

= WebLink objects =
Once you have created the FileLog object and written the plot specification, there is not much to be done. Click on the reference to the .gplot file in the FileLog section of a device, then click on the link for WebLink creation and then add the attributes you want to have. Put it into a suitable room and you are done.

If you are using placeholders in your .gplot files and after defining your .gplot file you click onto a FileLog "active" link to create the plot itself and get a message like:

<nowiki>XML Parsing Error: mismatched tag. Expected: </L1>.
...
Line Number 51, Column 95:<text x="12" y="80" text-anchor="middle" class="ylabel" transform="rotate(270,12,80)">'<L1>'</text></nowiki>
you can safely ignore it. This is due to the fact, that you are using placeholders in the .gplot definition (which is good, because it favors reuseability) but have not yet defined the corresponding attributes. While annoying, this is not your fault: you can only define attributes once you have a weblink. So click on create weblink and define the attributes you have been using placeholders for. The error message should go away.

The attributes which are generally needed are:

* label: should be defined like "Label 1"::"Label 2". Do not omit double quotes and use them individually for each label. Separator is a double (!) colon. If you ever manage to do away with the double quotes on the axes, please let us all know
* title: Can be as simple as "Some Title" or as complicated as "Temperature $data{currval1} ($data{min1}-$data{max1}), Humidity $data{currval2} ($data{min2}-$data{max2}) @ $data{currdate1}"

= SVG Programs =
The SVG programs can be found in the 98_SVG.pm module. Look for example for the string "histeps". Feel free to adapt and improve. If you ever program a wind rose to plot wind directions, please let me know.

= Details =
What you also should know:

* All data used in a plot come from one (!) file. It is currently not possible to mix data from several files. So make sure that the regular expression of the FileLog object catches everything which you need in one plot
* While it first seems evident that FileLog objects are associated with a given device, this must be mitigated. Imagine that you want to plot the state (and changes) of some socket adaptors (ZwischenStecker) over time. You then need to gather all the data (from several devices) in one file. So instead of define FileLog_ZwSt_1 FileLog /opt/fhem/var/log/ZwSt_1_%Y.log ZwSt_1 you need to specify define FL_ZwSt_ALL FileLog /opt/fhem/var/log/ZwSt_ALL_%Y.log ZwSt_.*deviceMsg.*BidCoS_RF.*
* Be careful when specifying the regular expression which filters the lines for a given logfile. While often it is sufficient to not specify a specific one at all, consider the following case from the Homematic world, where one action results in 4 lines of FHEM output. The switch communicates not only with the CCU, but also with the remote control, issuing 2 lines for each action:
<nowiki>2012-01-01_07:40:23 ZwSt_3 deviceMsg: on (to Dev.WDisp.Kueche)
2012-01-01_07:40:23 ZwSt_3 on
2012-01-01_07:40:26 ZwSt_3 deviceMsg: on (to BidCoS_RF)
2012-01-01_07:40:26 ZwSt_3 on</nowiki>
* Why one needs to specify a logtype (which is nothing else than a plot definition) for the FileLog has always been a mystery to me. It holds no useful information to the object itself and does not influence the way data is written to the associated logfile. Sure, plots need FileLogs, but not the other way round. And since the WebLink contains (again) the name of the plot definition file, the need to define the logtype attribute seems odd. The master himself says regarding this topic: "Ist eine Eigenschaft, die beschreibt, auf welche Art die Daten angezeigt werden koennen. Steht damit direkt neben den Daten, also da wo ich zuerst suchen wuerde. Ist nicht notwendig, aber so kann FHEMWEB ein 'create weblink' anbieten." I have to admit that this link is useful and I use to use it :-)
* If you meet on your way PERL-code snippets in the .gplot files, you can just ignore them safely. They are only used in the gnuplot world, not in SVG anymore. Now you may ask, where you find the corresponding features in SVG? They are hidden in functions defined in the FileLog "get" primitive.

== Documentation ==
Documentation can be found in several places, it is not complete and you need to piece it together:

* [http://fhem.de/HOWTO.html#plotting http://fhem.de/HOWTO.html#plotting]
* [http://fhem.de/commandref.html#FileLogget http://fhem.de/commandref.html#FileLogget]
* [http://fhem.de/commandref.html#label http://fhem.de/commandref.html#label]

[[Kategorie:HOWTOS]]

Creating Plots

2019-01-01T20:10:58Z

Kaihs: /* Data Extraction */ Typo

Creating Plots

2019-01-01T20:09:26Z

Kaihs: /* Data Extraction */ Typo

{{Randnotiz|RNTyp=[g|Info]|RNText=Hier wird das Anlegen per Hand beschrieben, was für Ungeübte umständlich und nicht empfehlenswert ist.
Mit "Create SVG Plot" in der FileLog-Detail-Ansicht steht inzwischen zur Vereinfachung ein Konfigurations-Frontend zur Verfügung: [[Plots_erzeugen|.gplot-Editor]].}}
= Howto create a PGM2/SVG plot - Introduction =
Output using the PGM2 engine is generated through .gplot files. The name is historical and today files can be generated using gnuplot or SVG graphics. This howto lists the most important aspects of generating a SVG configuration file.

Each graphic generated by FHEM is described by one configuration file. It is currently not possible to generate one page with several graphics from one configuration file.

Taking a high level view for each plot the following is needed:

* Data from a logfile (create it using the FileLog facility)
* Plot configuration (.gplot) file knowing about the internal structure of the logfile
* Association between the FileLog and the plot configuration (using the "logtype" attribute in the FileLog and the LINK in the WebLink object, also see comments below)
* Weblink representing the plot itself
= FileLog objects =
Digging into the more murky details, first thing is the creation of the FileLog object:

* The FileLog object is always associated with a physical device (but see comments below)
* The creation of a FileLog object together with the corresponding logfile is automatic if the "autocreate" attribute is set in FHEM (it is set by default)
* Manual creation is also possible and requires a statement like:
<nowiki>
define FL_KS550 FileLog /var/log/fhem/KS550_%Y.log KS550:T:.*
define FileLog_ZwSt_1 FileLog /opt/fhem/var/log/ZwSt_1_%Y.log ZwSt_1
define FL_ZwSt_ALL FileLog /opt/fhem/var/log/ZwSt_ALL_%Y.log ZwSt_.*deviceMsg.*BidCoS_RF.*
</nowiki>
* Be it manual or automatic: the definition of a FileLog object determines (through the regular expression) which of the output lines of FHEM end up in the logfile

= Plot definition =
Once the logfile is accumulating data, the plot configuration itself is needed. There is no object for this, but plain .gplot files in the share/FHEM directory are used by the system. A good start is to copy an existing one and modify it.

On a side note: if you create your own files instead of using the ones already delivered with FHEM, stick to the convention of prepending them with a "my". Files of pattern "my*" are guaranteed not to be overwritten during FHEM updates (or so Rudi promised me).

The following entries are recognized in a SVG context:

* #FileLog holds the information which data need to be extracted from the logfile. See below for details.
* Set commands: title, ylabel, y2label, yrange, y2range, ytics, y2tics, teminal (only "size" parameter is recognized)
* Plot command: see below for details
== Placeholders ==
It is possible to use placeholders in the .gplot files, which will then be replaced by information provided by the actual WebLink attributes listed below. This has the advantage that you can define one .gplot file and re-use it for several devices, changing size, title and lables accordingly instead of maintaining several separated files.

* <OUT> : only relevant for gnuplot
* <SIZE>: attr plotsize
* <TL> : attr title. The attribute is eval'ed by perl at runtime, be careful and protect by double quotes if you just want to enter strings. This gives access to all internal FHEM values, though admittedly not straightforward
* <Ln> : attr label. Lables 1-#n can be specified by a double-colon-separated (::) list, see below. This is also eval'ed at runtime, same precautions apply
* <IN> :

In general this is good practice and you should especially consider it if you plan to distribute your .gplot files. Using placeholders f.ex. for the title and all the labels and curve descriptors gives other users the possibility to change them without having to touch the .gplot code.

== Data Extraction ==
The central piece of the plotfile is the #FileLog line (yes, it must be prepended by a hash!), which is a special command und internally triggers the use of the FileLog "get" function, which extracts data from the logfile. The general syntax is: <nowiki><col>:<regexp>:<default>:<fn></nowiki>
.
* col: selects the column of the line (columns are white space separated, numbering starts at 1)
* regexp: validates/selects the line
* default: default value, if none is present
* fn: function which operates on values, pre-defined or eval'ed, see below

The "get" function will set the following %data values (which can e.g. be used in titles, labels, ...) for each requested column (curve), beggining with <x> = 1:

* min<x>, max<x>
* mindate<x>, maxdate<x>
* avg<x>, cnt<x>
* sum<x>
* currval<x> (last value)
* currdate<x> (last date)
So you can do something like <nowiki>attr <weblink> title "Min $data{min1}, Max $data{max1}, Last $data{currval1}"</nowiki>
Also implemented in this function is code which operates on the data retrieved. This can be specified at the "<fn>" tag. Up till now following functions are impemented:

* int (to cut off % from a number, as for the actuator)
* delta-h / delta-d to get rain/h and rain/d values from continuous data
* And then there is this: the string is evaluated as a perl expression. @fld is the current line splitted by spaces (0-based). So you can do something like $fld[3]/1000 to plot values divided by 1000 or $fld[3]=~"on"?0.9:0.8 to map the 4th field which contains an on/off information into numerical values to be plotted in a graph. Be warned though: this string/perl expression cannot (!) contain any spaces.

For even more details see [http://fhem.de/commandref.html#FileLogger http://fhem.de/commandref.html#FileLogget] or the module 92_FileLog.pm.

== Debugging Data Extraction ==
If you do not get the result you are expecting or, worse, no data at all, you may use the debug facility of FHEM to see what the get-command extracts from the logfile. Use telnet to contact FHEM and then use the arguments detailed below ending with the #FileLog argument you are using in the .gplot file:

<nowiki>telnet diskstation 7072
get FileLog_KS550 ?
get FileLog_KS550 - - 2012-01-01 2012-12-31 4::</nowiki>
You should get back the data which you have been asking for, followed by a line holding the .gplot argument. Make sure

* you do not select too much data, this will possibly upset your NAS :-)
* you do select data which really are in the file (beware of year/month changes)
== Plot Commands ==
Once you have extracted the data from the logfile, you need to plot it. There is a plot command which does just that. It has several arguments which you can use:

* axes: not needed by default, but if you want to plot curves which use different y axes, then you must tell the plot command, which y-axis the data should be bound to: "axes x1y1" selects the left, "axes x1y2" the right one
* title: defines the string which is printed in the colour of the curve into the plot. You can (and maybe should) use placeholders like "<Lx>", x being a number
* with: defines how to draw the data. only points, steps, histeps and lines (which acts as a catch all) are currently implemented
* ls: uses CSS definitions, still need to figure out, how this works
* lw: defines the width of a line
== Example ==
A very barebones but functional example of a file using placeholders could be:

<nowiki>set terminal size <SIZE>
set title '<TL>'
set ylabel '<L1>'
set y2label '<L2>'
#FileLog 4:::
plot \
axes x1y1 title '<L3>' with steps lw 2</nowiki>
It implements the placeholders which can be defined by the user through the WebLink attributes later, selects just one column, without regular expression matches, defaults or subsequent data operations and plot is as a steps diagram. In fact even the "axes x1y1" statement could be left out, it would still work.

== Changing text style ==
If you need a text style that is different from the style definition in fhemweb:
Add

<nowiki>text { font-family:Arial, Helvetica, sans-serif; font-size:12px; fill:#xxxxxx;}
text.title {font-family:Arial, Helvetica, sans-serif; font-size:16px; fill:#xxxxxx;}</nowiki>

where #xxxxxx is the color.

== Transparent plots ==
If you need transparent plots, for example in FLOORPLAN, you have to change the following definitions in svg_style.css

Change

<nowiki>.background { fill:#FFFFE7; }</nowiki>
to:

<nowiki>.background { fill:#FFFFE7;fill-opacity: 0; }</nowiki>
Change:

<nowiki>.border { stroke:black; fill:url(#gr_bg); }</nowiki>
to

<nowiki>.border { stroke:black; fill:url(#gr_bg);fill-opacity: 0; }</nowiki>

= WebLink objects =
Once you have created the FileLog object and written the plot specification, there is not much to be done. Click on the reference to the .gplot file in the FileLog section of a device, then click on the link for WebLink creation and then add the attributes you want to have. Put it into a suitable room and you are done.

If you are using placeholders in your .gplot files and after defining your .gplot file you click onto a FileLog "active" link to create the plot itself and get a message like:

<nowiki>XML Parsing Error: mismatched tag. Expected: </L1>.
...
Line Number 51, Column 95:<text x="12" y="80" text-anchor="middle" class="ylabel" transform="rotate(270,12,80)">'<L1>'</text></nowiki>
you can safely ignore it. This is due to the fact, that you are using placeholders in the .gplot definition (which is good, because it favors reuseability) but have not yet defined the corresponding attributes. While annoying, this is not your fault: you can only define attributes once you have a weblink. So click on create weblink and define the attributes you have been using placeholders for. The error message should go away.

The attributes which are generally needed are:

* label: should be defined like "Label 1"::"Label 2". Do not omit double quotes and use them individually for each label. Separator is a double (!) colon. If you ever manage to do away with the double quotes on the axes, please let us all know
* title: Can be as simple as "Some Title" or as complicated as "Temperature $data{currval1} ($data{min1}-$data{max1}), Humidity $data{currval2} ($data{min2}-$data{max2}) @ $data{currdate1}"

= SVG Programs =
The SVG programs can be found in the 98_SVG.pm module. Look for example for the string "histeps". Feel free to adapt and improve. If you ever program a wind rose to plot wind directions, please let me know.

= Details =
What you also should know:

* All data used in a plot come from one (!) file. It is currently not possible to mix data from several files. So make sure that the regular expression of the FileLog object catches everything which you need in one plot
* While it first seems evident that FileLog objects are associated with a given device, this must be mitigated. Imagine that you want to plot the state (and changes) of some socket adaptors (ZwischenStecker) over time. You then need to gather all the data (from several devices) in one file. So instead of define FileLog_ZwSt_1 FileLog /opt/fhem/var/log/ZwSt_1_%Y.log ZwSt_1 you need to specify define FL_ZwSt_ALL FileLog /opt/fhem/var/log/ZwSt_ALL_%Y.log ZwSt_.*deviceMsg.*BidCoS_RF.*
* Be careful when specifying the regular expression which filters the lines for a given logfile. While often it is sufficient to not specify a specific one at all, consider the following case from the Homematic world, where one action results in 4 lines of FHEM output. The switch communicates not only with the CCU, but also with the remote control, issuing 2 lines for each action:
<nowiki>2012-01-01_07:40:23 ZwSt_3 deviceMsg: on (to Dev.WDisp.Kueche)
2012-01-01_07:40:23 ZwSt_3 on
2012-01-01_07:40:26 ZwSt_3 deviceMsg: on (to BidCoS_RF)
2012-01-01_07:40:26 ZwSt_3 on</nowiki>
* Why one needs to specify a logtype (which is nothing else than a plot definition) for the FileLog has always been a mystery to me. It holds no useful information to the object itself and does not influence the way data is written to the associated logfile. Sure, plots need FileLogs, but not the other way round. And since the WebLink contains (again) the name of the plot definition file, the need to define the logtype attribute seems odd. The master himself says regarding this topic: "Ist eine Eigenschaft, die beschreibt, auf welche Art die Daten angezeigt werden koennen. Steht damit direkt neben den Daten, also da wo ich zuerst suchen wuerde. Ist nicht notwendig, aber so kann FHEMWEB ein 'create weblink' anbieten." I have to admit that this link is useful and I use to use it :-)
* If you meet on your way PERL-code snippets in the .gplot files, you can just ignore them safely. They are only used in the gnuplot world, not in SVG anymore. Now you may ask, where you find the corresponding features in SVG? They are hidden in functions defined in the FileLog "get" primitive.

== Documentation ==
Documentation can be found in several places, it is not complete and you need to piece it together:

* [http://fhem.de/HOWTO.html#plotting http://fhem.de/HOWTO.html#plotting]
* [http://fhem.de/commandref.html#FileLogget http://fhem.de/commandref.html#FileLogget]
* [http://fhem.de/commandref.html#label http://fhem.de/commandref.html#label]

[[Kategorie:HOWTOS]]

EnergyCam

2018-07-17T15:00:05Z

Kaihs: /* Links */

{{Infobox Hardware
|Bild=EnergyCam.jpg
|Bildbeschreibung=EnergyCam mit externer Batterie und externer Antenne montiert auf einem Ferraris-Zähler
|HWProtocol=Wireless M-Bus
|HWType=Sensor
|HWCategory=Energieverbrauchsmessung
|HWComm=Funk 868MHz, ModBus
|HWChannels=N/A
|HWVoltage=3,0 - 3,6V
|HWPowerConsumption=<0,2W
|HWPoweredBy=interne CR2450 oder externe Batterie, USB
|HWSize=B x H x T 48,00 x 55,50 x 15,50 mm
|HWDeviceFHEM=WMBUS
|HWManufacturer=Q-loud
}}
Die [[EnergyCam]] ist ein Zähleraufsatz der den Zählerstand erfasst und dann drahtlos (Wireless M-Bus) oder drahtgebunden (Modbus) weiterleitet.
== Features ==
Eine EnergyCam erfasst optisch den Zählerstand eines herkömmlichen Zählers für Elektrizität, Gas oder Wasser und wandelt diesen per optischer Zeichenerkennung (OCR) in einen Zahlenwert um. Dieser Wert wird dann zyklisch versandt und kann vom Empfänger ausgewertet werden.

Die EnergyCam wird dazu auf den Zähler aufgeklebt. Das Gerät unterstützt dabei durch eine Anzeige die Montage in der richtigen Position. Für die Verwendung mit Gas- und Wasserzählern sind noch zusätzliche Adapter erforderlich.
Es gibt die EnergyCam sowohl mit interner als auch externer Antenne sowie mit interner und externer Energieversorgung.
Der aktuelle Zählerstand kann bei Bedarf auch direkt am Gerät abgelesen werden und wird auf dem internen Display dargestellt.

== Hinweise zum Betrieb mit FHEM ==
Die EnergyCam im Wireless M-Bus Modus wird vom Modul [[WMBUS]] vollständig unterstützt. Das Herstellerkürzel ist FFD.

== Bekannte Probleme ==
Die Erfassung der Zählerstands erfolgt von schräg unterhalb des eigentlichen Zählwerks. Daher darf dieser Bereich nicht durch Aufdruck oder ähnliches die freie Sicht auf das Zählwerk behindern, sonst ist keine fehlerfreie Erfassung möglich.

== Links ==
* Herstellerseite [https://iot.q-loud.de/energycam-automatische-energiedatenerfassung]
* Dokumentation und Software [http://www.fastforward.ag/#Downloads]
[[Kategorie:Energieverbrauchsmessung]]
[[Kategorie:Other Components]]

EnergyCam

2018-07-17T14:22:24Z

Kaihs: /* Links */

{{Infobox Hardware
|Bild=EnergyCam.jpg
|Bildbeschreibung=EnergyCam mit externer Batterie und externer Antenne montiert auf einem Ferraris-Zähler
|HWProtocol=Wireless M-Bus
|HWType=Sensor
|HWCategory=Energieverbrauchsmessung
|HWComm=Funk 868MHz, ModBus
|HWChannels=N/A
|HWVoltage=3,0 - 3,6V
|HWPowerConsumption=<0,2W
|HWPoweredBy=interne CR2450 oder externe Batterie, USB
|HWSize=B x H x T 48,00 x 55,50 x 15,50 mm
|HWDeviceFHEM=WMBUS
|HWManufacturer=Q-loud
}}
Die [[EnergyCam]] ist ein Zähleraufsatz der den Zählerstand erfasst und dann drahtlos (Wireless M-Bus) oder drahtgebunden (Modbus) weiterleitet.
== Features ==
Eine EnergyCam erfasst optisch den Zählerstand eines herkömmlichen Zählers für Elektrizität, Gas oder Wasser und wandelt diesen per optischer Zeichenerkennung (OCR) in einen Zahlenwert um. Dieser Wert wird dann zyklisch versandt und kann vom Empfänger ausgewertet werden.

Die EnergyCam wird dazu auf den Zähler aufgeklebt. Das Gerät unterstützt dabei durch eine Anzeige die Montage in der richtigen Position. Für die Verwendung mit Gas- und Wasserzählern sind noch zusätzliche Adapter erforderlich.
Es gibt die EnergyCam sowohl mit interner als auch externer Antenne sowie mit interner und externer Energieversorgung.
Der aktuelle Zählerstand kann bei Bedarf auch direkt am Gerät abgelesen werden und wird auf dem internen Display dargestellt.

== Hinweise zum Betrieb mit FHEM ==
Die EnergyCam im Wireless M-Bus Modus wird vom Modul [[WMBUS]] vollständig unterstützt. Das Herstellerkürzel ist FFD.

== Bekannte Probleme ==
Die Erfassung der Zählerstands erfolgt von schräg unterhalb des eigentlichen Zählwerks. Daher darf dieser Bereich nicht durch Aufdruck oder ähnliches die freie Sicht auf das Zählwerk behindern, sonst ist keine fehlerfreie Erfassung möglich.

== Links ==
* Herstellerseite [https://iot.q-loud.de/energycam-automatische-energiedatenerfassung]
[[Kategorie:Energieverbrauchsmessung]]
[[Kategorie:Other Components]]

Rfmode

2018-07-02T20:44:37Z

Kaihs: WMBus_C

[[CUL]], [[CUN]](O) und {{Link2CmdRef|Lang=de|Anker=STACKABLE_CC|Label=STACKABLE_CC}} können (je nach Firmware) in verschiedenen [[rfmode]]s betrieben werden (vgl. {{Link2CmdRef|Lang=de|Anker=rfmode}}):

* "[[SlowRF]]" -- Für die Kommunikation mit FS20/FHT/HMS/EM1010/S300/Hoermann Geräten @1 kHz Datenrate (Standardeinstellung).
* "[[HomeMatic]]" -- Für die Kommunikation mit HomeMatic Geräten @10 kHz Datenrate.
* "[[MAX]]" -- Für die Kommunikation mit MAX! Geräten @10 kHz Datenrate.
* "[[WMBUS|WMBus_S]]", "[[WMBUS|WMBus_T]]" und "[[WMBUS|WMBus_C]]" -- Für die Kommunikation mit Wireless M-Bus Geräten wie Wasser-, Gas- oder Elektrozählern. (vgl. Wireless_M-Bus {{Link2CmdRef|Lang=de|Anker=WMBUS}})

Die Protokolle können nicht zugleich genutzt werden - ein Sende/Empfangsgerät kann also immer nur für einen rfmode genutzt werden. Möchte man mehrere rfmodes bedienen, so braucht man entsprechend viele Sende/Empfangsgeräte.

Technisch wäre es prinzipiell möglich vor jedem Senden den rfmode zu wechseln, jedoch könnten die jeweils anderen Protokolle nicht mehr empfangen werden. Da die Datenübertragung und die Sendehäufigkeit bei diesen Protokollen ziemlich langsam ist, würde man beim ständigen Wechsel der rfmodes zuviele Daten verlieren - selbst bei sehr wenigen Geräten völlig unpraktikabel.

== Links ==
* [[Kommunikationsprobleme mit FHT]]
* [[Was ist der Hauscode?]]

[[Kategorie:Glossary]]
[[Kategorie:CUL]]

HomeMatic Fenster-Drehgriffkontakt Community-Nachbau

2018-06-27T19:08:58Z

Kaihs: Abschnitt Montage

Der HB-Sec-RHS Funk-Fenster-Drehgriffkontakt ist ein Selbstbau threeStateSensor zur
Überwachung eines Fenster-Drehgriffs.

Die Firmware ist identisch mit dem [https://www.elv.de/homematic-funk-fenster-drehgriffkontakt-1.html Originalen Sensor von ELV] und verhält sich dementsprechend auch gleich.

== Übersicht ==

Die Grundidee zu diesem Sensor wurde durch {{Link2Forum|Topic=71413.0|LinkText=Kawaci im Forum}} geliefert.
Die Umsetzung besteht aus einer Atmega328p Platine mit CC1101 Funkmodul (868 MHz) sowie
einer auf der [https://github.com/pa-pa/AskSinPP AskSin++] Portierung des Homematik Protokolls.

Anfangs gab es zwei Ideen wie der Sensor aussehen sollte. Inzwischen hat sich die HomeMatic Variante mit CR2032 Batteriehalterung auf der Platine durchgesetzt. Somit wird hier nicht näher auf andere Versionen (zwei Platinen zur Erfassung der Fensterstellung) eingegangen.

== Platine ==
'''Schaltplan:'''
[[Datei:FDGK_v1.0_sch.jpg]]

'''Platine v1.0 (Oberseite mit korrigierter Pinbelegung):'''
[[Datei:FDGK_v1.0_top.jpg]]

'''Platine v1.0 (Unterseite, ohne bestücktes Radio):'''
[[Datei:FDGK_v1.0_bot.jpg]]

== Bauteilliste ==
Die Bauteilliste gibt es auf [https://github.com/pa-pa/HMSensor/blob/master/HMSensor-CR2032/Parts.xls GitHub].

In der Liste sind die Magnete und Reed-Kontakte nicht aufgeführt.
Folgende können verwendet werden:
* Reed-Kontakt 2x14mm [https://de.aliexpress.com/item/10pcs-N-O-Reed-switch-Magnetic-Switch-2-14mm-Normally-Open-Magnetic-Induction-switch/32803902404.html Aliexpress]
* Neodym Magnet 4x2mm [https://de.aliexpress.com/item/32873144013/32873144013.html Aliexpress]

== Zusammenlöten der SMD Bauteile ==
Die Bestückung der Platine ist im [https://forum.fhem.de/index.php/topic,71413.msg640858.html#msg640858 diesem Post] kurz beschrieben.

'''Bemerkung:'''
Y1 (32 kHz Quarz), C4 und C5 sind nicht erforderlich.
Vor dem Verlöten der Bauteile sollte kontrolliert werden, ob die Platinen in das Gehäuse passen. Falls nicht, sollte entweder das Gehäuse oder die Platine passend gefeilt werden.

Zuerst auf der Unterseite IC1 bestücken:
Hierzu einen beliebigen äußeren Pin verzinnen, den Prozessor mit der richtigen Orientierung von Pin 1 (runder Punkt) platzieren und den Pin verlöten.
Darauf achten, dass der Prozessor mittig auf den Pads aufliegt, ggf. den Pin wieder erhitzen
und den IC drehen oder verschieben. Auf der gegenüberliegenden Seite ebenfalls einen Pin verlöten, damit der IC fixiert ist.
Mit einem Flussmittelstift auf allen vier Seiten die Pins bestreichen und auf jeder Seite die Pins einzeln mit einer feinen Lötspitze bzw. feinem Lötzinn verlöten. Kurzschlüsse zwischen einzelnen Pins müssen unbedingt vermieden werden.

Danach auf der Unterseite C1, C2, C3 sowie R1 bestücken.
Auf der Oberseite R2, D1 (rot), R3, D2 (gelb), C6 und die beiden Taster bestücken.

Nach dem [https://wiki.fhem.de/wiki/HomeMatic_Fenster-Drehgriffkontakt_Community-Nachbau#Firmware Flashen der Firmware] das Radio (IC2) bzw. den Batteriehalter (BT1) bestücken.
Als Antenne (ANT) wird ein Draht mit 72 mm Länge eingelötet.

== Firmware ==

=== Bootloader ===

Die Sensorfirmware kann OTA (Over The Air) oder über den Arduino Bootloader geladen werden.

=== Erstellen des OTA (Over The Air) Bootloaders ===
{{Randnotiz|RNText=Firmware für 'ID=0030'}}
Dafür wird, mit Hilfe der [https://forum.fhem.de/index.php?action=dlattach;topic=71413.0;attach=91780 makeota.html] der Bootloader mit den benötigten Daten gefüllt und anschließend generiert.

Die makeota.html wird dazu in einem beliebigen Browser aufgerufen.

Die Felder ''HM ID'' und ''HM-Serial'' innerhalb der makeota.html können jeweils frei gewählt werden (dabei die Vorgaben beachten, so z.B. ''HM ID'': 6 hexadezimale Zeichen). Das Feld ''Device Type'' muss folgende Nummer beinhalten: "0030". Das Feld ''Config String'' wird aus den eingegebenen Daten automatisch generiert.

Die zwei o.g. Felder müssen sich von Gerät zu Gerät unterscheiden. Aus diesem Grund ist es sinnvoll, sich die eingegebenen Daten aufzuschreiben oder Screenshots zu erstellen.

Nun muss noch dem Bootloader bekannt gemacht werden, welche Batterien mit dem FDGK verwendet werden. Dies wird über die dropdown Liste "Power Presets" ausgewählt:

Dabei bedeutet:

*No StepUp = CR2032 Batterie
*StepUp single AA = eine AA Batterie und StepUp
*StepUp two AAA = zwei AAA Batterien und StepUp

Die Parameter „Step-Up Present“, „Low-Voltage“ und „Critical Voltage” ergeben sich aus der Wahl in der DropDown Liste, können aber individuell angepasst werden. Für den fehlerfreien Betrieb sollten diese aber unverändert bleiben!

Seit 12/2017 kann optional die [https://forum.fhem.de/index.php?action=dlattach;topic=71413.0;attach=91779 aktuelle Firmware] mit angegeben werden, so dass die Firmware gleichzeitig mit dem Bootloader geflasht werden kann. In diesem Fall kann der FDGK sofort in Betrieb genommen werden und nur es wird nur eine aktualisierte Firmware per OTA (Over The Air) geflasht.

Nach drücken der Taste "Create" erscheint eine Schaltfläche "Save Bootloader", mit welcher der angepasste Boorloader gespeichert werden kann. Es wird hierzu kein Netzzugang benötigt. Alles erfolgt per Javascript im Browser.

Seit 01/2018 gibt es die Firmware auch für das sog. ''lazy config''. Hierbei können die Register einfach z.B. durch das nächste Öffnen des Fensters ausgelesen werden, ohne dass die Config-Taste gedrückt werden muss.
Das Update auf ''lazy config'' geht auf zwei Arten:

Keine Änderung der 'ID=0030' und Durchführen eines [https://forum.fhem.de/index.php?action=dlattach;topic=71413.0;attach=94541 Firmware] bzw. eines FHEM Updates oder
{{Randnotiz|RNText=Firmware für 'ID=00C3'}}
Aktualisierung der Firmware auf 'ID=00C3'. Die Dateien können hier: [https://forum.fhem.de/index.php?action=dlattach;topic=71413.0;attach=94538 makeota.html], [https://forum.fhem.de/index.php?action=dlattach;topic=71413.0;attach=94542 Firmware (hex)] bzw. [https://forum.fhem.de/index.php?action=dlattach;topic=71413.0;attach=94541 Firmware (eq3)] heruntergeladen werden.

Verwendet man den Sensor in Kombination mit originaler eq3 Hardware, sollte man die zweite Möglichkeit wählen.

=== Flashen des OTA Bootloaders ===
Anschließend wird per ISP (USBasp oder vergleichbares) der Bootloader geflasht.
Zum Laden des Bootloaders, sowie der Software werden die Arduino SDK bzw. avrdude und die von makeota.html generierte Datei benötigt.

Der Bootloader lässt sich nun bei gestecktem ISP Programmer über folgende Befehle flashen:

<pre>avrdude -p m328p -P usb -c usbasp -B 3 -U lfuse:w:0xE2:m -U hfuse:w:0xD0:m -U efuse:w:0x06:m -U lock:w:0x2F:m</pre>
Setzt die Fuses.

<pre>avrdude -p m328p -P usb -c usbasp -V -U flash:w:bootloader.hex</pre>
lädt den eigentlichen Bootloader. Dabei ist zu achten, dass "bootloader.hex" die Datei mit dem Bootloader (bzw. der Firmware) ist und dementsprechend auch im Verzeichnis sein muss, wo die Datei zu finden ist.

Wenn jetzt die Platine mit Spannung versorgt wird, sollte die rote LED 7x blinken. Das signalisiert, dass der Bootloader erfolgreich gestartet wurde. Er wartet jetzt darauf, dass die Firmware übertragen wird.

=== OTA Update ===
Hierzu wird flash-ota benötigt.

Flash-ota funktioniert aktuell nur mit [[CUL]]/[[COC]] oder [[HM-CFG-USB USB Konfigurations-Adapter|HM-CFG-USB]] unter Linux ([[HomeMatic_Firmware_Update#Firmware_Update_mit_CUL.2FHM-CFG-USB_unter_FHEM|Update mit CUL oder HM-CFG-USB unter Linux]]), mit dem "HomeMatic Firmware Update Tool" unter Windows ([[HomeMatic_Firmware_Update#Firmware_Update_mit_HM-CFG-USB_unter_Windows|Update mit HM-CFG-USB unter Windows]]) oder mit einer CCU2.

Für einen HM-CFG-USB oder den HM-UART sieht der Aufruf wie folgt aus:

<pre>./flash-ota -f avr_HM_SEC_RHS_201705271601.eq3 -s RHS0000000</pre>

Für einen CUL muss noch die USB Schnittstelle oder der Pfad des USB Geräts mit gegeben werden:

<pre>./flash-ota -f avr_HM_SEC_RHS_201705271601.eq3 -s RHS0000000 -c /dev/serial/by-path/platform-3f980000.usb-usb-0:1.3:1.0-port0</pre>

Falls Fehler während der Übertragung auftreten, muss die Übertragung nochmals wiederholt werden.
Wenn die Firmware erfolgreich übertragen werde konnte, kann der Sensor gepairt werden.

== Einlöten der Reedkontakte und Anschluss an A0 & A1 ==
Den Magneten in den Drehring einbauen und diesen in das Gehäuse einbauen. Die Reedkontakte
Platzieren und mit einem Ohmmeter Messen, ob die Reedkontakte bei der entsprechenden Position
der Magnete schalten. Falls nicht, ggf. die Reedkontakte austauschen (Streuung!) bzw. einen stärkeren Magneten verwenden. Danach mittels Silberdraht bzw. Kupferlackdraht (an den zu
verlötenden Enden den Lack mittels eines Cuttermessers entfernen) die Reedkontakte gemäß
Bild verlöten und die Enden (GND, A0 bzw. A1) durch die vorgesehenen Öffnungen im Gehäuse führen.

''Verlötete Reedkontakte:''
[[Datei:HM_Fenstersensor-pic15.jpg]]

Danach die Antenne in die dafür vorgesehene Bohrung einführen und die Platine platzieren. Darauf achten, dass die Anschlüsse der Reedkontakte durch die dafür vorgesehenen Kontakte auf der Platine geführt werden.

''Einführen der Antenne:''
[[Datei:HM_Fenstersensor-pic17.jpg]]

''Platzierte Platine:''
[[Datei:HM_Fenstersensor-pic16.jpg]]

Nach Verlöten der drei Kontaktpunkte ist der Fensterdrehgriff fertig aufgebaut.

== Sensor spezifische Einstellungen ==
Der Sensor meldet die Position entsprechend welcher Zustand an A0 & A1 an liegt. Derzeit ist folgende Logik implementiert:

A0 & A1 offen - PosA -> OPEN

A0 geschlossen - PosB -> CLOSED

A1 geschlossen - PosC -> TILTED

Die Bedeutung der Positionen kann mittels der entsprechenden Register eingestellt werden.

Ebenfalls kann die CyclicInfoMsg aktiviert werden (zum aktivieren siehe Link am Ende des Artikels). Der Sensor meldet sich dann alle 24 Stunden mit dem aktuellen Status.

Register zum ändern der Position von A0 & A1:

<pre>set <Device_Name> regSet msgRhsPosA <closed|open|noMsg|tilted></pre>
<pre>set <Device_Name> regSet msgRhsPosB <closed|open|noMsg|tilted></pre>
<pre>set <Device_Name> regSet msgRhsPosC <closed|open|noMsg|tilted></pre>

== Montage ==
Bei der Standardeinstellung der Register gilt für die Platzierung des Magneten bei geöffnetem Fenster folgendes:
Bei links angeschlagenem Fenster muss der Magnet nach unten, bei rechts angeschlagenem nach oben.

== Gehäuse ==
Für das Gehäuse wurde auf eine 3D-Drucklösung gesetzt. Es gibt inzwischen mehrere Versionen (abgerundete obere Kante, eckige Kante uvm.).

Die Standard Version ist [https://www.thingiverse.com/thing:2354704 hier] zu finden.

Wer keinen 3D-Drucker besitzt kann sich im Forum nach einem 3D-Druckservice um schauen. Einige User bieten gegen kleines Geld einen netten und preiswerten {{Link2Forum|Topic=70413|LinkText=Service}} an.

== Links ==
*[https://forum.fhem.de/index.php/topic,71413.0.0.html Link zum Foren-Thread]
*[https://github.com/pa-pa/AskSinPP AskSinPP Libary]
*[https://github.com/pa-pa/HMSensor Alles Mögliche zu dem Projekt auf Github]
*[[HomeMatic_Type_threeStateSensor|CyclicInfoMsg aktivieren]]
*{{Link2Forum|Topic=70413|LinkText=3D-Druck service}}
*[[HomeMatic_Firmware_Update#Firmware_Update_mit_CUL.2FHM-CFG-USB_unter_FHEM|update-ota]]

[[Kategorie:HomeMatic Components‏‎]]
[[Kategorie:HomeBrew‏‎]]
[[Kategorie:868MHz]]

WMBUS

2018-06-24T20:04:54Z

Kaihs: WMBus_C

{{Infobox Modul
|ModPurpose=Dekodierung von Wireless M-Bus Nachrichten
|ModType=d
|ModForumArea=Sonstige Systeme
|ModTechName=36_WMBUS.pm
|ModOwner=kaihs
}}
[[WMBUS]] ist ein Modul zur Dekodierung von Wireless M-Bus Nachrichten. Solche Nachrichten werden z. B. von Zählern für Wasser, Wärme, Gas und Elektrizität ausgestrahlt.
Wireless M-Bus ist ein Standardprotokoll das von unterschiedlichen Herstellern unterstützt wird.
Das Protokoll unterstützt unterschiedliche Kodierungen des Funksignals, im wesentlichen den S-Mode, T-Mode und C-Mode. Der Empfänger (z. B. ein CUL) muss den selben Modus nutzen wie der Sender (der Zähler).
Wireless M-Bus unterstützt optional die Verschlüsselung der Daten per AES.
Die von einem Zähler gesendeten Daten können sehr unterschiedlich sein und hängen u. a. vom Zählertyp und dessen Hersteller ab.

== Voraussetzungen ==
Das Modul interpretiert nur die Nachrichten die von einen geeigneten Empfänger empfangen werden. Aktuell kann ein [[CUL]] und verwandte Geräte die die culfw[http://culfw.de/culfw.html] verwenden sowie ein Amber Wireless AMB8465M dafür verwendet werden. In der culfw muss die Unterstützung des WMBUS-Protokolls aktiviert sein (#define HAS_MBUS). Bei einem CUL mit der Hardwareversion V4 ist das nicht der Fall.

Der CUL muss in FHEM mittels Attribut rfmode=WMBus_S, WMBus_T oder WMBus_C in den zum Zähler passenden Empfangsmodus versetzt werden.

== Anwendung ==
Die Erzeugung des passenden Devices in FHEM geschieht automatisch beim Empfang des ersten Datenpakets eines Zählers. Voraussetzung dafür ist, dass [[autocreate]] aktiv ist.
Alternativ kann ein Device manuell angelegt werden. Dazu wird der Hersteller, die Seriennummer, die Version und der Typ (Wasser, Gas, ...) des Zählers benötigt.
Sind die Daten verschlüsselt wird auch noch der passende Schlüssel benötigt um die Daten entschlüsseln zu können.

== Anwendungsbeispiele ==
Ein per [[EnergyCam]] abgelesener Elektrizitätszähler sieht in FHEM z. B. so aus:
<pre>
Internals:
CUL_MBUS_MSGCNT 29
CUL_MBUS_RAWMSG b1944C4189985051701028A7D7A540000A00405FAD4080002FD08222C1295B8::-67.5
CUL_MBUS_RSSI -67.5
CUL_MBUS_TIME 2014-10-24 22:57:53
DEF FFD 17058599 1 2
DeviceMedium Electricity
DeviceType 2
IODev CUL_MBUS
IdentNumber 17058599
LASTInputDev CUL_MBUS
MSGCNT 29
Manufacturer FFD
NAME WMBUS_FFD_17058599_1_2
NR 49
STATE no errors
TYPE WMBUS
Version 1
addr FFD_17058599_1_2
Readings:
2014-10-24 22:57:53 1_storage_no 0
2014-10-24 22:57:53 1_type VIF_ENERGY_WATT
2014-10-24 22:57:53 1_unit Wh
2014-10-24 22:57:53 1_value 57881000
2014-10-24 22:57:53 2_storage_no 0
2014-10-24 22:57:53 2_type VIF_ACCESS_NO
2014-10-24 22:57:53 2_unit
2014-10-24 22:57:53 2_value 11298
2014-10-24 22:57:53 LQI 184
2014-10-24 22:57:53 RSSI -67.5
2014-10-24 22:57:53 battery ok
2014-10-24 22:57:53 decryption_ok 1
2014-10-24 22:57:53 energy 57881
2014-10-24 22:57:53 is_encrypted 0
2014-10-24 22:57:53 state no errors
2014-10-24 22:57:53 unit kWh
Attributes:
IODev CUL_MBUS
room WMBUS
</pre>

== Bekannte Probleme ==
Obwohl Wireless M-Bus ein standardisiertes Protokoll ist, scheint sich kaum ein Hersteller vollständig daran zu halten bzw. verwendet sog. herstellerspezifische Felder um wichtige Daten zu verpacken.
Aus den bisher beobachteten Datenpaketen ergibt sich
* Qundis (Herstellerkürzel LSE) verwendet herstellerspezifische Datenblöcke für den eigentlichen Zählerstand
* Techem und Hydrometer verwenden ein undokumentiertes Datenformat (CI-Field A2)
:''(Techem Heizkostenverteiler (CI-Field A0) können über das Modul [[TechemHKV]] ausgewertet werden)''
* RWE SmartHome Powercontrol[http://www.rwe-smarthome.de/web/cms/de/1776202/smarthome/informieren/geraete/power-control/] sendet verschlüsselt und der Hersteller gibt nicht den vollständigen Schlüssel an{{Link2Forum|Topic=24517|Message=315949}}

Daher werden bisher erst die [[EnergyCam]] der Firma Q-loud, Zähler von Easymeter und der Kamstrup Multical 21 vollständig unterstützt.
Für den Multical 21 muss eine culfw mit Unterstützung für WMBUS C verwendet werden. Diese ist in der culfw ab dem 24.6.2018 enthalten.

== Links ==
* Forumsthread {{Link2Forum|Topic=24517}}
* Protokoll Beschreibung [http://oms-group.org/download4all/]
* Beschreibung des M-BUS Protokolls [http://www.m-bus.com/files/MBDOC48.PDF]
[[Kategorie:Energieverbrauchsmessung]]

Systemübersicht

2018-06-24T20:02:42Z

Kaihs: /* Protokolle */ WMBus_C

Ein FHEM '''System''' besteht im Prinzip aus den in der nachfolgenden '''Übersicht''' aufgeführten Bestandteilen.
[[Datei:Systemübersicht.png]]

<div style="float: right;">__TOC__</div>

== Server ==
Bei der Komponente '''Server''' muss unterschieden werden zwischen dem eigentlichen '''FHEM''' Hausautomations-Server (implementiert in der Perl-Datei fhem.pl) und der Hardware, auf der dieser Server ausgeführt wird.

Als Server '''Hardware''' sind (z. B.) möglich:
* Windows Rechner
* Linux Rechner
* OS X Rechner
* Router (z. B. [[AVM Fritz!Box|FritzBox]])
* Einplatinencomputer, wie [[:Kategorie:Raspberry Pi|Raspberry Pi]], [[BeagleBone Black]]
* DockStar, PogoPlug, etc.
* diverse NAS Systeme wie Buffalo Linkstation, Synology Diskstation

(Diese Aufstellung ist nur eine unvollständige Auswahl; Details zu unterstützten Server Systemen finden sich in der Kategorie [[:Kategorie:Server Hardware|Server Hardware]]).

== Perl ==
Auf dem Server muss Perl installiert sein. Zur erforderlichen Version gibt es widersprüchliche Aussagen, die vor allem daraus resultieren, dass verschiedene FHEM-Module von verschiedenen Entwicklern stammen und daher unterschiedliche Anforderungen stellen. Laut FHEM-Webseite wird mindestens Version 5.6 benötigt, faktisch setzen aber viele Module 5.10 oder sogar 5.12 voraus. Der Betrieb mit Grundfunktionen ist jedoch zumindest ab Version 5.8.8 mit Einschränkungen möglich.

== Konfiguration ==
Das Hausautomations-System wird definiert über die [[Konfiguration]], die im Regelfall aus der
* reinen Textdatei <code>fhem.cfg</code> (Standard nach der Erstinstallation) oder alternativ einer
* [[configdb|SQL-Datenbank]]
besteht.

Die Konfiguration enthält Definitionen für die Bestandteile (Geräte) und Funktionen des jeweiligen Hausautomations-Systems. Die verfügbaren Befehle und deren Syntax sind in der Befehlsreferenz ({{Link2CmdRef}}) aufgeführt und beschrieben. Zu einigen Hilfsmodulen gibt es [[:Kategorie:Hilfsmodul|detaillierte Beschreibungen]] mit Beispielen.

== Benutzeroberfläche ==
Der Zugriff auf FHEM erfolgt mittels Webbrowser oder App über die verfügbaren '''[[:Kategorie:FHEM Frontends|FHEM Benutzeroberflächen]]'''.

In den FHEM Server integriert ist ein Webserver ([[PGM2]]), der im Prinzip immer zur Verfügung steht. Abhängig vom benutzten Klienten ist PGM2 über
* <code>serverhostnameoderIP:8083/fhem</code> (Desktop-Darstellung = Port 8083),
* <code>serverhostnameoderIP:8084/fhem</code> (Smartphone-Darstellung = Port 8084) oder
* <code>serverhostnameoderIP:8085/fhem</code> (Tablet-Darstellung = Port 8085)
erreichbar.

Eine Auswahl der Benutzeroberflächen:
* PGM2 - das Standardinterface
* [[FLOORPLAN]]
* [[FHEM Tablet UI]]
* [[SmartVISU]]
* diverse Apps für iOS und Android (Auswahl unter: [[:Kategorie:FHEM Frontends|FHEM Benutzeroberflächen]])

Beispielhafte Screenshots diverser Benutzeroberflächen: http://fhem.de/fhem.html#Screenshots

== Module ==
Die Funktionalität von FHEM kann über '''Module''' erweitert werden. Module können die unterschiedlichsten Aufgaben übernehmen vom Anbinden eines Hardwaresystems
über die Bereitstellung eines Frontends bis zur Automatisierung von Aufgaben. Beispiele für Module:
* 00_CUL.pm - Implementierung der Unterstützung für den [[CUL]]
* 11_FHT.pm - Unterstützung der [[:Kategorie:FHT Components|FHT]] Heizungssteuerung
* 95_FLOORPLAN.pm - Grundriss (oder Ähnliches) als Benutzeroberfläche
* uvm.

Module können unterteilt werden in
* [[:Kategorie:FHEM Befehl|Befehlsmodule]] (FHEM-Befehle sind teilweise eigenständige Module)
* [[:Kategorie:Hilfsmodul|Hilfsmodule]]
* [[:Kategorie:Gerätemodul|Gerätemodule]]
Die offiziell in FHEM enthaltenen Module sind in der {{Link2CmdRef}} beschrieben. Sie werden über den [[Update]]-Befehl von FHEM verteilt und aktualisiert. Voraussetzung für die Aufnahme als offizielles Modul sind Supportwille durch den Entwickler und Dokumentation des Moduls.

Zusätzlich existiert eine Vielzahl von [[:Kategorie:Modul (Inoffiziell)|inoffiziellen Modulen]], die manuell in FHEM installiert werden können. Auch die Aktualisierung erfolgt nicht über den Update-Befehl, sondern muss durch den Nutzer selbst erfolgen. Inoffizielle Module sind an den verschiedensten Stellen zu finden:
* [[:Kategorie:Modul (Contrib)|Contrib]]-Verzeichnis im offiziellen FHEM-Sourcecode-SVN [http://svn.fhem.de/trac/browser/trunk/fhem/contrib]
* Beiträge im [https://forum.fhem.de/ FHEM-Forum]
* private Homepages

== Interfaces ==
Die Verbindung zu den angeschlossenen '''Geräten''' der Hausautomation wird im Allgemeinen - geräteabhängig - über [[Interface|Interfaces]] (manchmal auch als '''Gateway''' bezeichnet) hergestellt. Das kann z. B. im Falle von [[HomeMatic]] ein [[HMLAN Konfigurator]] sein, ein mittels LAN mit dem FHEM Server verbundenes Gerät, das die FHEM Steuerbefehle in das HomeMatic Funkprotokoll umsetzt - und auch die Funktelegramme der HomeMatic Komponenten an FHEM zurückgibt. Bei HomeMatic-Komponenten ist der Einsatz von Interfaces des Hersteller dieser Geräte (eQ-3) zu empfehlen, da bei CUL und seinen Derivaten Probleme mit dem Timing auftreten können. Eine Übersicht hierzu ist [[HomeMatic#FHEM_als_Zentrale|hier]] zu finden.

Entsprechende Interfaces gibt es auch für andere Funkprotokolle und für die drahtgebundenen Systeme.

Eine (unvollständige) Liste solcher Interfaces (siehe auch [[:Kategorie:Interfaces|Kategorie Interfaces]]):
* [[CUL]] - je nach Einstellung für die Kommunikation mit [[:Kategorie:FS20 Components|FS20]], [[:Kategorie:FHT Components|FHT]] und andere [[SlowRF]] Protokolle, [[MAX|MAX!]] Heizungssteuerung oder [[:Kategorie:HomeMatic Components|HomeMatic]] und, mit Einschränkungen, InterTechno (nur senden)
* [[CUNO]], ähnlich CUL, jedoch nicht per USB sondern per IP angebunden (z.Zt. -Stand Januar 2014 - nicht für HomeMatic empfohlen)
* [[HMLAN Konfigurator|HomeMatic LAN Konfigurations-Adapter]] - HomeMatic
* [[HM-MOD-RPI-PCB HomeMatic Funkmodul für Raspberry Pi|HomeMatic Funkmodul für Raspberry Pi]] - Homematic
* [[HMCCU|Homematic CCU2]] - HomeMatic und HomeMatic IP
* [[MAX#MAXLAN|MAX! Cube LAN-Gateway]]
* Schnittstellen(karten) für [[:Kategorie:1-Wire|1-Wire]]
* TCM(120/310) zur Anbindung von [[:Kategorie:EnOcean Components|EnOcean]]
* [[Arduino]] mit Firmata über USB oder Netzwerk
* [[panStamp]] als Möglichkeit Arduinos mit diversen Sensor- und I/O- Boards per 868MHz Funk über das SWAP protokoll anzubinden
* [[JeeLink]], ein weiteres USB-Stick Interface (ebenfalls arduino basiert) für diverse 433MHz und 868MHz Komponenten
* [[RFXtrx]] für InterTechno, RSL, ELRO etc., Wetter-Sensoren (Oregon-Scientific, Cresta, La Crosse, TFA, UPM) und andere 433 Mhz Geräte.
* manche Komponenten ([[:Kategorie:IP Components|IP Komponenten]]) können über TCP/IP (LAN) direkt vom FHEM Server aus angesprochen werden; hier ist dann kein weiteres Interface im eigentlichen Sinne erforderlich. Dies gilt auch für diverse Module die Geräte über WEB Dienste des Herstellers anbinden (z. B. [[Withings]], [[netatmo]], [[MQTT]]).

== Protokolle ==
Der Kommunikation zwischen Interfaces und Geräten liegt jeweils ein bestimmtes Protokoll zugrunde. Unterstützte Protokolle mit ihren Eigenschaften sind in der folgenden Tabelle aufgelistet.

{| class="wikitable sortable"
|+ Übersicht über unterstützte Funkprotokolle
|-
! Name !! rfMode !! Frequenz !! Modulation !! Datenrate !! class="unsortable" | Interfaces !! class="unsortable" | Modul !! class="unsortable" | Geräte (Beispiel) !! class="unsortable" | Bemerkungen
|-
| [[FS20_Allgemein|FS20]] || SlowRF || 868,35MHz || AM || 1kHz || CU*, FHZ || {{Link2CmdRef|Anker=FS20|Label=FS20}} || - || -
|-
| FHT || SlowRF || 868,35MHz || AM || 1kHz || CU*, FHZ || {{Link2CmdRef|Anker=CUL_FHTTK|Label=FHTTK}}, {{Link2CmdRef|Anker=FHT|Label=FHT}} || Heizungsregelung || -
|-
| S300 || SlowRF || 868,35MHz || AM || 1kHz || CU*, FHZ || {{Link2CmdRef|Anker=CUL_WS|Label=CUL_WS}} || Temperatur-/Feuchtesensoren || -
|-
| HMS || SlowRF || 868,35MHz || AM || 1kHz || CU*O, FHZ || - || ?? || -
|-
| EM || SlowRF || 868,35MHz || AM || 1kHz || CU*, FHZ || {{Link2CmdRef|Anker=CUL_EM|Label=CUL_EM}} || Energiemonitore (Strom, Gas) || -
|-
| [[HomeMatic ]]|| HomeMatic || 868,3MHz || FM || 10kHz || CU*, [[HM-CFG-LAN_LAN_Konfigurations-Adapter|HMLan]], [[HM-CFG-USB_USB_Konfigurations-Adapter|HMUsb]], [[HM-MOD-RPI-PCB HomeMatic Funkmodul für Raspberry Pi|HomeMatic Funkmodul für Raspberry Pi]] || {{Link2CmdRef|Anker=CUL_HM|Label=CUL_HM}}, {{Link2CmdRef|Anker=HMUARTLGW|Label=HMUARTLGW }} || [[:Kategorie:HomeMatic_Components|diverse]] || -
|-
| [[MAX|MAX!]] || MAX || 868,3MHz || FM || 20kHz || CU*, [[MAX#MAXLAN|MAXLAN]] || {{Link2CmdRef|Lang=de|Anker=MAX|Label=MAX}} || [[:Kategorie:MAX|Wandthermostat, Heizkörperthermostate, Fensterkontakt, Zwischenstecker]] || -
|-
| IT || - || 433MHz || AM? || 1kHz || CU*433, || - || - || -
|-
| Firmata WiFi || - || 2,4/5 GHz || || || || {{Link2CmdRef|Anker=FRM|Label=FRM}} || Arduino || -
|-
| SWAP || - || 868 (433/915) MHz || GFSK || 38.3835 Kbps || panStamp (+panStick) || {{Link2CmdRef|Anker=SWAP|Label=SWAP}} || RGB LED Driver, diverse Sensoren und Aktoren || -
|-
| [[:Kategorie:EnOcean Components|EnOcean]] || - || 315 / 868 / 902 / 928MHz || ASK || 125 kbit/s || {{Link2CmdRef|Anker=TCM|Label=TCM}} || {{Link2CmdRef|Anker=EnOcean|Label=EnOcean}} || Batterielose Funksensoren, diverse Aktoren || -
|-
| PCA || - || 868,35MHz || ?? || ?? || [[JeeLink]] || {{Link2CmdRef|Anker=PCA301|Label=PCA301}} || [[PCA301 Funkschaltsteckdose mit Energieverbrauchsmessung|PCA301]] || -
|-
| [[La Crosse]] || - || 868,35MHz || ?? || ?? || [[JeeLink]], LGW || {{Link2CmdRef|Anker=Lacrosse|Label=Lacrosse}} || LaCrosse IT+ (Technoline) Sensoren || -
|-
| ZigBee Light Link || - || 2,4 GHz || || || HUE Bridge (RaspBee) || {{Link2CmdRef|Anker=HUEBridge|Label=HUEBridge}} || Philips HUE und LightLink Lampen (auch Osram LIGHTIFY an der HUE-Bridge)|| [http://www.developers.meethue.com/documentation/how-hue-works]
|-
| [[MySensors]] || - || 2,4 GHz, 868/433 MHz, RS485 (2-Draht) || || || MySensors Gateway, [[MQTT]] || [[MYSENSORS]] || [http://www.mysensors.org/build/ Selbstbau-Sensoren] || auch LoRa möglich
|-
| [[:Kategorie:Z-Wave Components|Z-Wave]] || - || 868MHz || 2-FSK || 9.600 bit/s oder 40 Kbit/s || {{Link2CmdRef|Anker=ZWDongle|Label=ZWDongle}} || {{Link2CmdRef|Anker=ZWave|Label=ZWave}} || - || -
|-
| [[WMBUS]] || WMBus_T, WMBus_S, WMBus_C || 868MHz || ?? || 100 kbit/s / 32.768 kbit/s || CU* || {{Link2CmdRef|Anker=WMBUS|Label=WMBUS}} || Wasseruhren, Wärmezähler, Elektrozähler || -
|-
| colspan="9" | ''Tabelle muss noch vervollständigt werden''
|-
| colspan="2" | '''Legende:'''
| colspan="7" | CU* = CUL, CUN, CUNO /
|}

{| class="wikitable sortable"
|+ Übersicht über drahtgebundene Systeme
|-
! Name !! class="unsortable" | Interfaces (Hardware) !! class="unsortable" | Modul !! class="unsortable" | Geräte (Beispiel) !! class="unsortable" | Bemerkungen
|-
| [[1-Wire]] || [[Interfaces für 1-Wire|diverse]] || {{Link2CmdRef|Anker=OWX|Label=OWX}} || [[:Kategorie:1-Wire|1-Wire]] || -
|-
| [[EIB_/_KNX|EIB/KNX]] || {{Link2CmdRef|Anker=TUL|Label=TUL}} || {{Link2CmdRef|Anker=EIB|Label=EIB}} || [[:Kategorie:EIB/KNX|EIB/KNX]] || -
|-
| Firmata || RS-232, USB, Ethernet || {{Link2CmdRef|Anker=FRM|Label=FRM}} || Arduino || -
|-
| [[HomeMatic Wired]] || [[HomeMatic Wired RS485 LAN Gateway|HM485 LAN Gateway]] || {{Link2CmdRef|Anker=HM485_LAN|Label=HM485_LAN}} || [[:Kategorie:HomeMatic Components|Präfix HMW]] || -
|-
| colspan="5" | ''Tabelle muss noch vervollständigt werden''
|-
| colspan="2" | '''Legende:'''
| colspan="3" | ...
|}

== Komponenten ==
Der eigentliche Zweck eines Hausautomatisierungs-Projekts sind dann letztendlich die '''Geräte''' (Komponenten / Aktoren / [[:Kategorie:Schalter (Empfänger)|Empfänger]]), die automatisch gesteuert werden sollen, bzw. auch Auslöser für Aktionen ([[:Kategorie:Schalter (Sender)|Sender]]) und Lieferant von Datenmaterial ([[:Kategorie:Hardware Typen|Sensoren]]) sind.

Diese Geräte sind, sofern es eine detaillierte Beschreibung dazu gibt, in den jeweiligen Unterseiten der [[:Kategorie:Hardware|Hardwareliste]] aufgeführt.

== Weblinks ==
* [http://www.enocean.com/de/home/ EnOcean] Homepage
* [http://www.elv.de ELV], (Haupt-)Lieferant von FS20, FHT, HomeMatic, MAX!
* [https://github.com/firmata/protocol Firmata] Protokoll
* [http://www.panstamp.com panStamp], panStamp Hersteller
* [http://jeelabs.com/products/jeelink Jeelabs], JeeLink Hersteller
* [http://www.zigbee.org/ Zigbee] Homepage

[[Kategorie:FHEM]]
[[Kategorie:FHEM-Verwendung]]

WMBUS

2018-06-24T20:01:45Z

Kaihs: Umterstützung für Kamstrup Multical

{{Infobox Modul
|ModPurpose=Dekodierung von Wireless M-Bus Nachrichten
|ModType=d
|ModForumArea=Sonstige Systeme
|ModTechName=36_WMBUS.pm
|ModOwner=kaihs
}}
[[WMBUS]] ist ein Modul zur Dekodierung von Wireless M-Bus Nachrichten. Solche Nachrichten werden z. B. von Zählern für Wasser, Wärme, Gas und Elektrizität ausgestrahlt.
Wireless M-Bus ist ein Standardprotokoll das von unterschiedlichen Herstellern unterstützt wird.
Das Protokoll unterstützt unterschiedliche Kodierungen des Funksignals, im wesentlichen den sogenannten S-Mode und den T-Mode. Der Empfänger (z. B. ein CUL) muss den selben Modus nutzen wie der Sender (der Zähler).
Wireless M-Bus unterstützt optional die Verschlüsselung der Daten per AES.
Die von einem Zähler gesendeten Daten können sehr unterschiedlich sein und hängen u. a. vom Zählertyp und dessen Hersteller ab.

== Voraussetzungen ==
Das Modul interpretiert nur die Nachrichten die von einen geeigneten Empfänger empfangen werden. Aktuell kann ein [[CUL]] und verwandte Geräte die die culfw[http://culfw.de/culfw.html] verwenden sowie ein Amber Wireless AMB8465M dafür verwendet werden. In der culfw muss die Unterstützung des WMBUS-Protokolls aktiviert sein (#define HAS_MBUS). Bei einem CUL mit der Hardwareversion V4 ist das nicht der Fall.

Der CUL muss in FHEM mittels Attribut rfmode=WMBus_S oder WMBus_T in den zum Zähler passenden Empfangsmodus versetzt werden.

== Anwendung ==
Die Erzeugung des passenden Devices in FHEM geschieht automatisch beim Empfang des ersten Datenpakets eines Zählers. Voraussetzung dafür ist, dass [[autocreate]] aktiv ist.
Alternativ kann ein Device manuell angelegt werden. Dazu wird der Hersteller, die Seriennummer, die Version und der Typ (Wasser, Gas, ...) des Zählers benötigt.
Sind die Daten verschlüsselt wird auch noch der passende Schlüssel benötigt um die Daten entschlüsseln zu können.

== Anwendungsbeispiele ==
Ein per [[EnergyCam]] abgelesener Elektrizitätszähler sieht in FHEM z. B. so aus:
<pre>
Internals:
CUL_MBUS_MSGCNT 29
CUL_MBUS_RAWMSG b1944C4189985051701028A7D7A540000A00405FAD4080002FD08222C1295B8::-67.5
CUL_MBUS_RSSI -67.5
CUL_MBUS_TIME 2014-10-24 22:57:53
DEF FFD 17058599 1 2
DeviceMedium Electricity
DeviceType 2
IODev CUL_MBUS
IdentNumber 17058599
LASTInputDev CUL_MBUS
MSGCNT 29
Manufacturer FFD
NAME WMBUS_FFD_17058599_1_2
NR 49
STATE no errors
TYPE WMBUS
Version 1
addr FFD_17058599_1_2
Readings:
2014-10-24 22:57:53 1_storage_no 0
2014-10-24 22:57:53 1_type VIF_ENERGY_WATT
2014-10-24 22:57:53 1_unit Wh
2014-10-24 22:57:53 1_value 57881000
2014-10-24 22:57:53 2_storage_no 0
2014-10-24 22:57:53 2_type VIF_ACCESS_NO
2014-10-24 22:57:53 2_unit
2014-10-24 22:57:53 2_value 11298
2014-10-24 22:57:53 LQI 184
2014-10-24 22:57:53 RSSI -67.5
2014-10-24 22:57:53 battery ok
2014-10-24 22:57:53 decryption_ok 1
2014-10-24 22:57:53 energy 57881
2014-10-24 22:57:53 is_encrypted 0
2014-10-24 22:57:53 state no errors
2014-10-24 22:57:53 unit kWh
Attributes:
IODev CUL_MBUS
room WMBUS
</pre>

== Bekannte Probleme ==
Obwohl Wireless M-Bus ein standardisiertes Protokoll ist, scheint sich kaum ein Hersteller vollständig daran zu halten bzw. verwendet sog. herstellerspezifische Felder um wichtige Daten zu verpacken.
Aus den bisher beobachteten Datenpaketen ergibt sich
* Qundis (Herstellerkürzel LSE) verwendet herstellerspezifische Datenblöcke für den eigentlichen Zählerstand
* Techem und Hydrometer verwenden ein undokumentiertes Datenformat (CI-Field A2)
:''(Techem Heizkostenverteiler (CI-Field A0) können über das Modul [[TechemHKV]] ausgewertet werden)''
* RWE SmartHome Powercontrol[http://www.rwe-smarthome.de/web/cms/de/1776202/smarthome/informieren/geraete/power-control/] sendet verschlüsselt und der Hersteller gibt nicht den vollständigen Schlüssel an{{Link2Forum|Topic=24517|Message=315949}}

Daher werden bisher erst die [[EnergyCam]] der Firma Q-loud, Zähler von Easymeter und der Kamstrup Multical 21 vollständig unterstützt.
Für den Multical 21 muss eine culfw mit Unterstützung für WMBUS C verwendet werden. Diese ist in der culfw ab dem 24.6.2018 enthalten.

== Links ==
* Forumsthread {{Link2Forum|Topic=24517}}
* Protokoll Beschreibung [http://oms-group.org/download4all/]
* Beschreibung des M-BUS Protokolls [http://www.m-bus.com/files/MBDOC48.PDF]
[[Kategorie:Energieverbrauchsmessung]]

FHEM Tablet UI

2018-06-24T09:56:58Z

Kaihs: /* Icons */ Typo

{{Infobox Modul
|ModPurpose=Oberfläche für FHEM
|ModType=x
|ModFTopic=34233
|ModForumArea=TabletUI
|ModTechName=n.a.
|ModOwner=setstate ({{Link2FU|7023|Forum}})
}}
[[FHEM Tablet UI]] (FTUI) ist ein leichtgewichtiges aber funktionsreiches Frontend-Framework zum Steuern und Überwachen von in FHEM integrierten Geräten. Es basiert auf HTML/CSS/JavaScript und stellt somit keine zusätzlichen Anforderungen an den FHEM-Server.

Mit Hilfe zahlreicher Widgets, die sehr leicht mit HTML Code konfiguriert werden können, ist es möglich, innerhalb kurzer Zeit ein den eigenen Wünschen entsprechendes User-Interface aufzubauen.

Für den Betrieb ist nur eine FHEM-Installation mit [[HTTPSRV|HTTPSRV-Modul]] sowie ein gängiger Webbrowser notwendig.

Mit wenigen Anpassungen ist es auch möglich das UI auf anderen Webservern (Apache, u.a.) zu betreiben. Somit können FHEM und FHEM Tablet UI auch auf getrennten Systemen ausgeführt werden.

[[File:tablet_ui.png|thumb|500px|center|Beispiel für ein mit [[FHEM Tablet UI]] erstelltes User-Interface]]

{{Todo|Design-Möglichkeiten erklären, Navigationsmethoden ausformulieren}}

== Installation ==
Die Installation von FHEM Tablet UI erzeugt keinen großen Aufwand und besteht im Großen und Ganzen aus drei Schritten:
*Dateien aus dem GitHub-Repository herunterladen
*FHEM konfigurieren ([[HTTPSRV]]-Device erstellen, [[FHEMWEB]]-Attribut longpoll einstellen)
*Eine Beispieldatei anlegen

{{Hinweis|Diese Anleitung geht davon aus, dass FHEM unter Debian nach der Anleitung [https://debian.fhem.de Stable build using apt] installiert wurde.
Ist dies nicht der Fall, muss der Pfad '''/opt/fhem''' dementsprechend angepasst werden.}}

'''1.''' Zuerst müssen alle Dateien von FHEM Tablet UI in das FHEM-Verzeichnis '''/opt/fhem/www''' kopiert werden. Das geht mit folgendem '''update'''-Befehl über die FHEM-Befehlszeile.
:<code>update all https://raw.githubusercontent.com/knowthelist/fhem-tablet-ui/master/controls_fhemtabletui.txt</code>

:[[Datei:FTUI_Installation_01.png|thumb|none|Schritt 1: Dateien kopieren]]

'''2.''' Anschließend ist ein neues [[HTTPSRV]]-Device in FHEM anzulegen, welches auf den Ordner mit den gerade heruntergeladenen Dateien verweist.
:<code>define TABLETUI HTTPSRV ftui/ ./www/tablet/ Tablet-UI</code>

:[[Datei:FTUI_Installation_02.png|thumb|none|Schritt 2: HTTPSRV-Device anlegen]]

{{Hinweis|Dieser Schritt kann ausgelassen werden, wenn die Funktionalitäten von [[FHEMWEB]] ausreichend sind. Dann muss FTUI aber in weiterer Folge unter der URL '''<nowiki>http(s)://<fhem-server>:8083/fhem/tablet/index.html</nowiki>''' aufgerufen werden und es wird kein Link auf FTUI in der FHEM GUI erstellt. Vorteil ist aber, dass das FHEMWEB-Caching verwendet werden kann. Siehe dieser {{Link2Forum|Topic=86362|Message=788258}}.}}

'''3.''' Damit FHEM Tablet UI mit FHEM kommunizieren kann, ist noch die '''longpoll'''-Einstellung im [[FHEMWEB]] Device festzulegen.

:<code>attr WEB longpoll websocket</code>
:bzw. bei Problemen mit ''websocket''
:<code>attr WEB longpoll 1</code>

:[[Datei:FTUI_Installation_03.png|thumb|none|Schritt 3: longpoll einstellen]]

'''4.''' Weil FTUI noch nichts anzuzeigen hat, wird die Datei '''/opt/fhem/www/tablet/index-example.html''' nach '''/opt/fhem/www/tablet/index.html''' kopiert.
:<code>sudo cp -a /opt/fhem/www/tablet/index-example.html /opt/fhem/www/tablet/index.html</code>

:[[Datei:FTUI_Installation_04.png|thumb|none|Schritt 4: index.html erstellen]]

'''5.''' Abschließend muss FHEM noch '''neu gestartet''' werden (''shutdown restart'') da das Attribut '''longpoll''' geändert wurde.

Somit ist FHEM Tablet UI bereit zur Verwendung und kann durch Aufruf der URL '''<nowiki>http://<fhem-server>:8083/fhem/ftui/</nowiki>''' oder den Link im FHEM-Menü geöffnet werden

== Update ==
Ein Update von FTUI kann ebenfalls über die FHEM-Kommandozeile erfolgen.

'''1.''' Prüfen der Änderungen seit dem letzten Download/Update durch Eingabe von:
:<code><nowiki>update check https://raw.githubusercontent.com/knowthelist/fhem-tablet-ui/master/controls_fhemtabletui.txt</nowiki></code>

'''2.''' Update der geänderten Dateien durch Eingabe von:
:<code><nowiki>update all https://raw.githubusercontent.com/knowthelist/fhem-tablet-ui/master/controls_fhemtabletui.txt</nowiki></code>

Eine weitere Option ist das Hinzufügen des FTUI-Git-Repositories zum allgemeinem Update-Vorgang von FHEM. Dabei wird dann bei einem FHEM-Update auch gleich FHEM Tablet UI aktualisiert, bzw. die Änderungen angezeigt.
:<code><nowiki>update add https://raw.githubusercontent.com/knowthelist/fhem-tablet-ui/master/controls_fhemtabletui.txt</nowiki></code>

== Konfiguration ==
===DOCTYPE===
In allen HTML-Dateien, die im Browser geladen werden und das typische HTML-Gerüst besitzen (also alle Hauptseiten, jedoch keine Template-Dateien), sollte eine ''Document Type Declaration'' (DTDT) eingefügt werden. Mit ihr wird festgelegt, welche ''Document Type Definition'' hier verwendet wird (das kommt aus der Metasprache XML), konkret also, in welcher Version der nachfolgende HTML-Code vom Browser interpretiert werden soll. Lässt man die DTDT weg, oder definiert sie auf verschiedenen Seiten unterschiedlich, kann ein und der selbe HTML-Code zu unterschiedlichen Darstellungen führen. Die DTDT erfolgt immer auf der ersten Zeile, noch vor dem <code><html></code>-Tag. Nachfolgend wird HTML5 verwendet.

<syntaxhighlight lang="html">
<!DOCTYPE html>
<html>
<head>...</head>
<body>...</body>
</html>
</syntaxhighlight>

===META-Parameter===
Das Tablet UI lässt sich über die META-Parameter konfigurieren. Diese Parameter sind in jeder '''.html''' Datei (z.B. index.html) im Abschnitt '''<head>''' einzutragen. Ausgenommen davon sind Dateien, die als Template, Pagebutton-Zielseiten oder ähnliches eingebunden werden.

Die Parameter sind immer nach diesem Schema aufgebaut:
<meta name="[Parameter-Name]" content="[Parameter-Wert]">

===Verbindung zu FHEM===
{| class="wikitable"
|-
!Parameter-Name!!Standard-Wert!!Mögliche Werte!!Beschreibung
|-
|web_device||WEB||String||FHEM-Device, welches für das Polling verwendet wird
|-
|longpoll||1||0, 1||
'''0''': Longpoll deaktiviert; alle 30s ein Shortpoll (Neuladen der gesamten Statusänderungen)

'''1''': Longpoll aktiv; geänderte Stati werden sofort aktualisiert, zusätzlich werden alle 15min die gesamten Statusänderungen geladen.
|-
|longpoll_type||websocket||websocket, ajax, 0||
'''websocket''': Für die Aktualisierung der Daten wird das Websocket-Protokoll verwendet. Werden vom Browser keine Websockets unterstützt, gibt es einen automatischen Fallback auf Ajax.

'''ajax''': Ajax wird für die Aktualisierung verwendet.

'''0''': Longpoll deaktiviert, Shortpoll wird verwendet.
|-
|longpoll_filter||.*||RegEx||Event-Filter. Kann verwendet werden, wenn z.B. Devices, die in FTUI angezeigt werden, in einem eigenen FHEM-Room sind.
|-
|longpoll_maxage||240||Integer||Kommen in diesem Zeitraum (Sekunden) keine Longpoll-Events bei FTUI an, wird die Verbindung als "disconnected" angesehen und ein neuer Verbindungsversuch wird gestartet.
|-
|shortpoll_interval||900||Integer||Zeitraum in Sekunden, nach dem ein vollständiger Refresh stattfindet
|-
|shortpoll_only_interval||30||Integer||Zeitraum in Sekunden, nach dem ein vollständiger Refresh stattfindet, sollte Longpoll deaktiviert sein
|-
|fhemweb_url||/fhem/||Integer||URL zu FHEM. Wird benötigt wenn FTUI auf einem anderen als dem FHEM Server läuft oder nicht im Standard-Pfad installiert ist.
Hinweis: Wenn FHEM auf einem anderem Server/Domain läuft muss man das "CORS" Attribut im FHEMWEB Modul (s.o.) auf 1 setzen, sonst bekommt man Cross Origin Fehler.
|}

===Funktionalität===
{| class="wikitable"
|-
!Parameter-Name!!Standard-Wert!!Mögliche Werte!!Beschreibung
|-
|debug||0||0 - 5||Log-Level
|-
|toast||5||Integer||Anzahl an gleichzeitig angezeigten Toast-Nachrichten. Um keine anzuzeigen, ist der Wert auf 0 zu setzen.
|-
|toast_position||bottom-left||||Position im Browserfenster, wo die Toast-Nachrichten angezeigt werden.
|-
|lang||de||de||Sprache der Oberfläche (für z.B. Datums-/Zeitfunktionen)
|-
|username||||String||Benutzername für eine Basic-Authentifierung *
|-
|password||||String||Passwort für eine Basic-Authentifizierung *
|}
'''*''' Derzeit wird die Basic-Authentifizierung in Kombination mit WebSockets nicht unterstützt. Die Verwendung von '''longpoll=1''' (ajax) ist daher notwendig.

===Toast-Nachrichten===
[[Datei:Ftui_toast.png|thumb|Toast-Nachrichten]]
Tablet-UI liefert Informationen darüber, was im Moment gerade passiert. Das geschieht über Toast-Nachrichten, die in der Standardeinstellung unten links im Browser auftauchen.

Wird beispielsweise ein Gerät eingeschaltet, so erscheint eine kleine Nachricht mit dem abgesetzten Befehl. Auch Fehlermeldungen und Statusinformationen werden angezeigt. Ob überhaupt und was konkret angezeigt wird, richtet sich nach dem eingestellten Debug-Level (siehe oben). Beim Debug-Level 5 werden alle Nachrichten angezeigt, bei 0 keine.

Die Position der Toast-Nachrichten kann über den Meta-Tag <code>meta name='toast_position'</code> festgelegt werden. Für oben-mittig müsste folgender Code eingefügt werden:
<pre><meta name='toast_position' content='top-center'></pre>

Möglich sind folgende Positionen:
* <code>top-left</code>
* <code>top-right</code>
* <code>bottom-left</code>
* <code>bottom-right</code>
* <code>top-center</code>
* <code>bottom-center</code>
* <code>mid-center</code>

Die maximale Anzahl an Nachrichten, die gleichzeitig angezeigt werden können, lässt sich mit <code>meta name='toast'</code> Sind maximal 2 Nachrichten gewünscht, muss folgender Meta-Tag gesetzt werden:
<pre><meta name='toast' content='2'></pre>

==Navigationsmethoden==
{{Todo|Dieser Abschnitt dient derzeit lediglich als Sammlung von Stichpunkten und muss vollständig überarbeitet werden.}}

'''Unterschied zwischen Pagetab und Pagebutton:

'''Pagetab:''' Ganze Seite austauschen -> Menü muss auf jede Seite
[[FTUI_Widget_Pagetab]]

'''Pagebutton:''' Teil der Seite austauschen -> Menü nur in erster Seite
[[FTUI_Widget_Pagebutton]]

==Gestaltung==
===Layout-Optionen===
* [[FTUI Layout Gridster|Gridster]]
* [[FTUI Layout Flex|Flex]]
* [[FTUI Layout Sheet|Tabelle]]
* [[FTUI Layout Row|Reihen]]

=== Farben ===
Es besteht die Möglichkeit, die Farbwerte in hexadezimaler Form, als RGB-Wert oder mit dem Farbnamen anzugeben. Zum Beispiel:

*HEX: #ADD8E6
*RBG: rgb(173, 216, 230)
*Namen: lightblue

Knallige Farben wie '''<span style="color: #ff0000;">#ff0000</span>''' für Rot oder '''<span style="color: #00ff00;">#00ff00</span>''' für Grün sollten vermieden werden.
Es ist besser unterhalb von #D0 (208) für die Grundfarben zu bleiben.

Empfohlene Farben sind z.B.:

*Orange: <span style="color: #aa6900;">#aa6900</span>
*Rot: <span style="color: #ad3333;">#ad3333</span>
*Grün: <span style="color: #32a054;">#32a054</span>
*Blau: <span style="color: #6699FF;">#6699FF</span>
*Grau: <span style="color: #8C8C8C;">#8C8C8C</span>

Hilfreich bei der Suche nach den Farbwerten ist zum Beispiel der Color-Picker auf dieser Seite: http://www.colorpicker.com. Für die Suche nach Farben, die einen guten Kontrast bilden, diese Webseite: http://vanisoft.pl/~lopuszanski/public/colors/

Im Ordner ''css'' der FTUI Installation finden sich einige vorbereitete Farbschemas. Diese können mit einem zusätzlichen Eintrag im <nowiki><head></nowiki>-Bereich der FTUI-Seite(n) aktiviert werden.

Hier am Beispiel eines blauen Farbschemas:
<syntaxhighlight lang="html">
<html>
<head>
[...]
<link rel="stylesheet" href="/fhem/tablet/css/fhem-blue-ui.css" />
[...]
</head>
</syntaxhighlight>

Diese Schema-Dateien ändern alle Widgets. Einzelne Widgets können durch Hinzufügen der jeweiligen [[#CSS-Klassen|CSS-Klasse]] geändert werden.

===CSS-Styles===
Das Layout und das Aussehen des UI kann durch diverse vorgegebene CSS-Klassen beeinflusst werden. Die verfügbaren Klassen sind im Abschnitt [[#CSS-Klassen|CSS-Klassen]] aufgeführt.

Soll das Aussehen des UI durch eigene CSS-Klassen oder durch Überschreiben der vorhandenen verändert werden, kann eine eigene CSS-Datei erstellt werden, die dann bei einem eventuellen Update von FTUI nicht überschrieben wird. Diese Datei muss den Dateinamen '''fhem-tablet-ui-user.css''' haben und im Ordner '''/fhem/tablet/css''' abgelegt werden. Sie wird dann beim Aufruf von FTUI automatisch mitgeladen.

=== CSS-Klassen ===
Nicht alle Widgets unterstützen alle hier angegebenen Klassen. Welche genau unterstützt werden, kann auf der jeweiligen Widget-Seite nachgelesen werden.

{|class="wikitable mw-collapsible mw-collapsed" style="width: 100%;"
!colspan="2" style="text-align: left;"|sheet/row/cell-Layout
|-
!class="mw-collapsible-content"|Klasse!!Beschreibung
{{FTUI Klasse|sheet}}{{FTUI Klasse|row}}{{FTUI Klasse|cell}}{{FTUI Klasse|cell-1-x}}{{FTUI Klasse|cell-x}}{{FTUI Klasse|left-align}}{{FTUI Klasse|right-align}}{{FTUI Klasse|bottom-align}}{{FTUI Klasse|top-align}}{{FTUI Klasse|center-align}}
|}

{|class="wikitable mw-collapsible mw-collapsed" style="width: 100%;"
!colspan="2" style="text-align: left;"|row/col-Layout
|-
!class="mw-collapsible-content"|Klasse!!Beschreibung
{{FTUI Klasse|col}}{{FTUI Klasse|col-1-x}}{{FTUI Klasse|col-x}}
|}

{|class="wikitable mw-collapsible mw-collapsed" style="width: 100%;"
!colspan="2" style="text-align: left;"|hbox/vbox-Layout
|-
!class="mw-collapsible-content"|Klasse!!Beschreibung
{{FTUI Klasse|vbox}}{{FTUI Klasse|hbox}}{{FTUI Klasse|card}}{{FTUI Klasse|phone-width}}{{FTUI Klasse|full-height}}{{FTUI Klasse|full-width}}{{FTUI Klasse|grow-0}}{{FTUI Klasse|grow-1}}{{FTUI Klasse|grow-2}}{{FTUI Klasse|grow-x}}{{FTUI Klasse|items-top}}{{FTUI Klasse|items-center}}{{FTUI Klasse|items-bottom}}{{FTUI Klasse|items-space-between}}{{FTUI Klasse|items-space-around}}
|}

{|class="wikitable mw-collapsible mw-collapsed" style="width: 100%;"
!colspan="2" style="text-align: left;"|Generelle Klassen für die Positionierung
|-
!class="mw-collapsible-content"|Klasse!!Beschreibung
{{FTUI Klasse|inline}}{{FTUI Klasse|newline}}{{FTUI Klasse|top-space}}{{FTUI Klasse|top-space-2x}}{{FTUI Klasse|top-space-3x}}{{FTUI Klasse|left-space}}{{FTUI Klasse|left-space-2x}}{{FTUI Klasse|left-space-3x}}{{FTUI Klasse|right-space}}{{FTUI Klasse|right-space-2x}}{{FTUI Klasse|right-space-3x}}{{FTUI Klasse|top-narrow}}{{FTUI Klasse|top-narrow-2x}}{{FTUI Klasse|top-narrow-10}}{{FTUI Klasse|left-narrow}}{{FTUI Klasse|left-narrow-2x}}{{FTUI Klasse|left-narrow-3x}}{{FTUI Klasse|right-narrow}}{{FTUI Klasse|right-narrow-2x}}{{FTUI Klasse|right-narrow-3x}}{{FTUI Klasse|centered}}{{FTUI Klasse|wider}}{{FTUI Klasse|narrow}}{{FTUI Klasse|fullsize}}{{FTUI Klasse|compressed}}{{FTUI Klasse|height-narrow}}{{FTUI Klasse|w1x}}{{FTUI Klasse|w2x}}{{FTUI Klasse|w3x}}{{FTUI Klasse|maxw40}}{{FTUI Klasse|doublebox-v}}{{FTUI Klasse|doublebox-h}}{{FTUI Klasse|triplebox-v}}{{FTUI Klasse|right}}
|}

{|class="wikitable mw-collapsible mw-collapsed" style="width: 100%;"
!colspan="2" style="text-align: left;"|Vordergrundfarben
|-
!class="mw-collapsible-content"|Klasse!!Beschreibung
{{FTUI Klasse|red}}{{FTUI Klasse|green}}{{FTUI Klasse|blue}}{{FTUI Klasse|lightblue}}{{FTUI Klasse|orange}}{{FTUI Klasse|gray}}{{FTUI Klasse|lightgray}}{{FTUI Klasse|white}}{{FTUI Klasse|black}}{{FTUI Klasse|mint}}{{FTUI Klasse|yellow}}
|}

{|class="wikitable mw-collapsible mw-collapsed" style="width: 100%;"
!colspan="2" style="text-align: left;"|Hintergrundfarben
|-
!class="mw-collapsible-content"|Klasse!!Beschreibung
{{FTUI Klasse|bg-red}}{{FTUI Klasse|bg-green}}{{FTUI Klasse|bg-blue}}{{FTUI Klasse|bg-lightblue}}{{FTUI Klasse|bg-orange}}{{FTUI Klasse|bg-gray}}{{FTUI Klasse|bg-lightgray}}{{FTUI Klasse|bg-white}}{{FTUI Klasse|bg-black}}{{FTUI Klasse|bg-mint}}{{FTUI Klasse|bg-yellow}}
|}

{|class="wikitable mw-collapsible mw-collapsed" style="width: 100%;"
!colspan="2" style="text-align: left;"|Rahmen
|-
!class="mw-collapsible-content"|Klasse!!Beschreibung
{{FTUI Klasse|verticalLine}}{{FTUI Klasse|border-black}}{{FTUI Klasse|border-white}}{{FTUI Klasse|border-orange}}{{FTUI Klasse|border-red}}{{FTUI Klasse|border-green}}{{FTUI Klasse|border-mint}}{{FTUI Klasse|border-lightblue}}{{FTUI Klasse|border-blue}}{{FTUI Klasse|border-gray}}{{FTUI Klasse|border-yellow}}{{FTUI Klasse|border-lightgray}}
|}

{|class="wikitable mw-collapsible mw-collapsed" style="width: 100%;"
!colspan="2" style="text-align: left;"|Größen
|-
!class="mw-collapsible-content"|Klasse!!Beschreibung
{{FTUI Klasse|mini}}{{FTUI Klasse|tiny}}{{FTUI Klasse|small}}{{FTUI Klasse|normal}}{{FTUI Klasse|large}}{{FTUI Klasse|big}}{{FTUI Klasse|bigger}}{{FTUI Klasse|tall}}{{FTUI Klasse|great}}{{FTUI Klasse|grande}}{{FTUI Klasse|gigantic}}
|}

{|class="wikitable mw-collapsible mw-collapsed" style="width: 100%;"
!colspan="2" style="text-align: left;"|Schriftstil
|-
!class="mw-collapsible-content"|Klasse!!Beschreibung
{{FTUI Klasse|thin}}{{FTUI Klasse|bold}}{{FTUI Klasse|darker}}{{FTUI Klasse|truncate}}
|}

{|class="wikitable mw-collapsible mw-collapsed" style="width: 100%;"
!colspan="2" style="text-align: left;"|Sonstiges
|-
!class="mw-collapsible-content"|Klasse!!Beschreibung
{{FTUI Klasse|blank}}{{FTUI Klasse|transparent}}{{FTUI Klasse|half-transparent}}{{FTUI Klasse|blurry}}{{FTUI Klasse|shake}}{{FTUI Klasse|fail-shake}}{{FTUI Klasse|marquee}}{{FTUI Klasse|icon round}}{{FTUI Klasse|icon square}}{{FTUI Klasse|readonly}}{{FTUI Klasse|blink}}{{FTUI Klasse|rotate-90}}{{FTUI Klasse|horizontal}}{{FTUI Klasse|circleborder}}{{FTUI Klasse|autohide}}{{FTUI Klasse|notransmit}}{{FTUI Klasse|tap}}{{FTUI Klasse|FS20}}{{FTUI Klasse|value}}{{FTUI Klasse|novalue}}{{FTUI Klasse|timestamp}}{{FTUI Klasse|percent}}{{FTUI Klasse|nocache}}{{FTUI Klasse|fade}}{{FTUI Klasse|rotate}}{{FTUI Klasse|nolabels}}{{FTUI Klasse|default}}{{FTUI Klasse|prefetch}}{{FTUI Klasse|circulate}}{{FTUI Klasse|valueonly}}{{FTUI Klasse|positiononly}}{{FTUI Klasse|lineIndicator}}{{FTUI Klasse|barIndicator}}{{FTUI Klasse|roundIndicator}}{{FTUI Klasse|dim-tick}}{{FTUI Klasse|dim-front}}{{FTUI Klasse|dim-back}}{{FTUI Klasse|hue-tick}}{{FTUI Klasse|hue-front}}{{FTUI Klasse|hue-back}}{{FTUI Klasse|warn}}{{FTUI Klasse|activate}}{{FTUI Klasse|labelright}}{{FTUI Klasse|interlock}}{{FTUI Klasse|keepopen}}{{FTUI Klasse|noshade}}
|}

=== Icons ===
FTUI bringt einige Icons-"Schriftarten" mit, die für die Darstellung genützt werden können. Diese werden automatisch beim Start des UI eingebunden, sobald ein entsprechendes Icon-Präfix im Code der Seite vorkommt.

Verfügbare Icon-Schriftarten sind:
* Eingebaute Icons ''ftui-window'' und ''ftui-door''. Präfix '''ftui-'''. Beispiel: <code>data-icon="ftui-door"</code>
* [http://fontawesome.io/icons/ Font-Awesome]: Mehr als 500 Icons zur Auswahl. Präfix '''fa-'''. Beispiel: <code>data-icon="fa-volume-up"</code>
* [https://material.io/icons/ Material Icons]: Mehr als 900 Icons zur Auswahl. Präfix '''mi-'''. Beispiel: <code>data-icon="mi-local_gas_station"</code>
* FHEM und OpenAutomation Icons: Präfix '''fs-''' und '''oa-'''. Beispiel: <code>data-icon="oa-secur_locked"</code>
* [https://erikflowers.github.io/weather-icons/ Weather-Icons]: Präfix '''wi '''. Beispiel: <code>data-icon="wi wi-day-rain-mix"</code>

Alternativ können auch Bilder Icons (bspw. png) über CSS verwendet werden. Bspw:
<syntaxhighlight lang="html5">
<head>
<style type="text/css">
.logo-fhem {
background: url(https://wiki.fhem.de/fhemlogo.png) no-repeat;
width: 120px;
height: 132px;
background-size: contain;
}
</style>
</head>
<body>
<div data-type="symbol" data-icon="logo-fhem"></div>
</body>
</syntaxhighlight>

== Widgets ==
===Allgemeine Attribute===
Jedes Widget kann über verschiedene Attribute konfiguriert werden. Folgende Attribute gelten für alle Widgets:

{| class="wikitable"
|+allgemeine Attribute
|-
!align="right" |data-type
|Widget-Typ
|-
!align="right" |data-device
|FHEM-Name des Gerätes (mit dem Befehl 'list' bekommt man im FHEM die kpl. Liste)
|-
!align="right" |class
|CSS-Klassen für Aussehen und Formatierung des Widgets
|-
|}

{| class="wikitable"
|+Daten Empfangen
|-
!align="right" |data-get
|Reading Name
|-
!align="right" |data-get-on
|Wert für den Status on
|-
!align="right" |data-get-off
|Wert für den Status off
|-
|}

{| class="wikitable"
|+Daten Senden
|-
!align="right" |data-set
|Reading Name
|-
!align="right" |data-set-on
|Wert für den Status on
|-
!align="right" |data-set-off
|Wert für den Status off
|-
|}

Widget-spezifische Attribute können auf der jeweiligen Widget-Seite nachgelesen werden.

=== Integrierte Widgets ===
Folgende Widgets sind direkt in FHEM Tablet UI integriert und können "out of the box" verwendet werden.

* [[FTUI Widget Button|button]]: Variante der push und switch Widgets, die entweder einen URL ansteuern oder einen FHEM-Befehl absetzen kann
* [[FTUI Widget Checkbox|checkbox]]: Umschalter zwischen zwei definierten Zuständen
* [[FTUI Widget Circlemenu|circlemenu]]: Mehrere Widgets hinter einem Widget verborgen, trotz des 'circle' im Namen kann das Menue jetzt auch horizontal oder vertikal ausgeklappt werden
* [[FTUI Widget Clock|clock]]: Stellt eine einfach Uhr zur Verfügung
* [[FTUI Widget Colorwheel|colorwheel]]: Farbpalette zur Auswahl von Farben
* [[FTUI Widget Controlbutton|controlbutton]]: iOS-ähnlicher Button zum Schalten zwischen zwei Zuständen (z.B. on / off)
* [[FTUI Widget Controller|controller]]: iOS-ähnlicher vertikaler Schieberegler zum Einstellen eines Wertes
* [[FTUI Widget Datetimepicker|datetimepicker]]: Erstellt eine Auswahl für Datum/Uhrzeit
* [[FTUI Widget Departure|departure]]: Abfahrtszeiten öffentlicher Verkehrsmittel
* [[FTUI Widget Dimmer|dimmer]]: Ein-/Aus-Button mit integriertem Schieberegler für z.B. einen Dim-Wert
* [[FTUI Widget Eventmonitor|eventmonitor]]:
* [[FTUI Widget Homestatus|homestatus]]: Auswahl für vier oder fünf definierte Stati eines Objects (z.B.: FHEM Residents)
* [[FTUI Widget Html|html]]:
* [https://github.com/nesges/Widgets-for-fhem-tablet-ui/wiki/iframe iframe]: Widget zum Einbinden externer Inhalte in einem Iframe
* [[FTUI Widget Image|image]]: Zeigt ein Bild, dessen URL fest vorgegeben oder aus einem Device-Reading gelesen werden kann
* [[FTUI Widget Input|input]]: Erstellen eines Texteingabefeldes
* [https://github.com/nesges/Widgets-for-fhem-tablet-ui/wiki/joinedlabel joinedlabel]: verbindet mehrere Readings zu einem Feld
* [[FTUI Widget Klimatrend|klimatrend]]: wandelt Daten aus dem statistics-Modul in einen Pfeil um, der den aktuellen Trend anzeigt
* [[FTUI Widget Knob|knob]]: Erstellt einen Statusbalken auf einer Kreisbahn
* [[FTUI Widget Label|label]]: Reading als Text anzeigen
* [[FTUI Widget Level|level]]: Vertikale oder horizontale Leiste zur Anzeige von Werten zwischen einem Minimal- und einem Maximalwert
* [[FTUI Widget Link|link]]: Erstellt einen Link oder Button zum Aufrufen von URLs oder Senden von Befehlen an FHEM
* [[FTUI Widget Medialist|medialist]]:
* [[FTUI Widget Multistatebutton|multistatebutton]]: Variante des push-Widgets, welches den set-Befehl abhängig vom gelesenen Status ändert
* [[FTUI Widget Notify|notify]]: Blendet ein Hinweisfenster im Browser ein
* [[FTUI Widget Pagebutton|pagebutton]]: Button, mit dem auf andere Seiten gesprungen werden kann. Eignet sich gut für eine Navigation
* [[FTUI Widget Pagetab|pagetab]]: Tauscht den Inhalt einer Seite durch den einer anderen. Eignet sich gut für ein Navigationsmenü
* [[FTUI Widget Playstream|playstream]]: Abspielen eines Webradio-Streams per Button
* [[FTUI Widget Popup|popup]]: Öffnet ein Popup nach einem Klick auf ein Widget oder HTML-Element
* [[FTUI Widget Progress|progress]]: Zeigt einen Prozentwert in Form einer runden Fortschrittsleiste
* [[FTUI_Widget_Push|push]]: Button, mir dem ein Befehl an FHEM gesendet werden kann
* [[FTUI Widget Range|range]]: Erstellt vertikale Balken, die einen Wertebereich in unterschiedlichen Farben darstellen
* [[FTUI Widget Readingsgroup|readingsgroup]]: Zeigt eine Readingsgroup an, wie sie in FHEM definiert wurde
* [[FTUI Widget Rotor|rotor]]: Animiertes Umschalten von zwei oder mehr Widgets an einer Position
* [[FTUI Widget Scale|scale]]: Vertikale oder horizontale Leiste zur Anzeige von Werten zwischen einem Minimal- und einem Maximalwert
* [[FTUI_Widget_Select|select]]: Combobox, die eine Liste an Werten zur Auswahl anzeigt
* [https://github.com/nesges/Widgets-for-fhem-tablet-ui/wiki/settimer settimer]: Zum Anzeigen und Einstellen einer Uhrzeit
* [[FTUI Widget Simplechart|simplechart]]: Einfaches XY-Diagramm zur Anzeige eines Wertes, der direkt aus einem FHEM-Logfile gelesen wird
* [[FTUI Widget Slideout|slideout]]:
* [[FTUI Widget Slider|slider]]: Vertikaler Schieberegler zum Einstellen eines Wertes
* [[FTUI Widget Spinner|spinner]]: Element um Werte durch Drücken auf Plus- und Minus- oder Höher-/Tiefer-Icons zu ändern
* [[FTUI Widget Swiper|swiper]]: Bietet die Möglichkeit, durch Wischen zwischen verschiedenen Seiten zu wechseln
* [[FTUI Widget Switch|switch]]: Button um zwischen zwei Zuständen zu schalten (z.B. on / off)
* [[FTUI Widget Symbol|symbol]]: Status eines Devices als Symbol darstellen (z.B. Fenster offen)
* [[FTUI Widget Thermostat|thermostat]]: Anzeige für Heizungsthermostate, mit der die gewünschte Temperatur eingestellt werden kann
* [[FTUI Widget Volume|volume]]: Einstellscheibe zur Änderung eines einzelnen Wertes
* [[FTUI Widget Weather|weather]]: Wettersymbol anzeigen
* [[FTUI Widget WindDirection|wind_direction]]: Anzeige der Windrichtung auf einer Windrose

===3rd Party Widgets===
Für diese Widgets kann nicht sichergestellt werden, dass sie mit der jeweils aktuellen Version von FTUI funktionieren.
* [[FTUI Widget Agenda|agenda]]: Zeigt Kalendereinträge in einer Listenform an
* [[FTUI Widget Calview|calview]]: Zeigt Einträge aus einem [[CALVIEW]]-Device an
* [[FTUI Widget Chart|chart]]: Diagramm mit ähnlichen Möglichkeiten wie die FHEM-Plots
* [[FTUI Widget Classchanger|classchanger]]: Ändert seine CSS-Klassen je nach Status eines Devices
* [[FTUI Widget Clicksound|clicksound]]: Mit dem Widget "clicksound" können Sounds an Click-Events von Elementen gebunden werden.
* [[FTUI Widget Filelog|filelog]]:
* [[FTUI Widget Fullcalview|fullcalview]]:
* [[FTUI Widget Gds|gds]]:
* [https://forum.fhem.de/index.php/topic,78379.msg703359.html#msg703359 gmaps]: Kartendarstellung mit Google Maps API
* [[FTUI Widget Highchart|highchart]]:
* [[FTUI Widget Highchart3d|highchart3d]]:
* [https://github.com/nesges/Widgets-for-fhem-tablet-ui/wiki/itunes_artwork itunes_artwork]: itunes_artwork durchsucht die iTunes-Datenbank anhand eines Arrays von beliebigen Suchworten nach einem Cover-Artwork und zeigt dieses an.
* [https://github.com/nesges/Widgets-for-fhem-tablet-ui/wiki/javascript javascript]: Ermöglicht die Ausführung beliebigen Javascript-Codes aus einem Reading.
* [https://github.com/nesges/Widgets-for-fhem-tablet-ui/wiki/kodinowplaying kodinowplaying]: zeigt Informationen zu grade in KODI gespielten Medien in Form eines Labels an.
* [[FTUI Widget Loading|loading]]:
* [[FTUI Widget Meteogram|meteogram]]:
* [https://github.com/nesges/Widgets-for-fhem-tablet-ui/wiki/mpdnowplaying mpdnowplaying]: Zeigt Titelinformationen eines per MPD-Modul angebundenen Music Player Daemon an.
* [https://forum.fhem.de/index.php/topic,79283.msg712855.html#msg712855 pinpad]: Pinpad für z.B. eine Alarmanlage
* [https://forum.fhem.de/index.php/topic,76643.msg685472.html#msg685472 postme]: Liste des PostMe-Devices anzeigen
* [https://github.com/nesges/Widgets-for-fhem-tablet-ui/wiki/reload reload]: auslösen eine Pagereloads
* [[FTUI Widget Screensaver|screensaver]]:
* [https://forum.fhem.de/index.php/topic,73497.0.html scrolllabel]: Texte in Laufschrift darstellen
* [[FTUI Widget Svgplot|svgplot]]:
* [https://forum.fhem.de/index.php?topic=82883.msg750237#msg750237 todoist]: einfaches widget für todoist
* [[FTUI Widget Tts|tts]]: Sprachausgabe eines Textes aus einem Reading auf dem Endgerät.
* [[FTUI Widget UWZ|uwz]]: Anzeige der Warnungen der Unwetterzentrale
* [[FTUI Widget Wakeup|wakeup]]:
* [https://github.com/svenson08/ftui-weekdaytimer-widget wdtimer]: Visualisierung des [[WeekdayTimer]] Modul
* [[FTUI Widget Weekprofile|weekprofile]]: Visualisierung des [[weekprofile]] Moduls

==Templates==
Kommt ein bestimmtes "Code-Fragment" auf mehreren Seiten oder öfter pro Seite vor, bietet FTUI die Option, Templates zu erstellen. Diese werden einmal gebaut und können dann mit dem Attribut '''data-template''' nach Belieben in eine Seite eingefügt werden. Dabei besteht auch die Möglichkeit, Variablen zu verwenden.

Die Variablennamen sollten möglichst eindeutig und unverwechselbar gewählt werden, da bei der Verwendung von Templates im Prinzip Suchen & Ersetzen angewendet wird. Verwendet man beispielsweise die Variablen '''dev:Thermostat_Kueche''' und '''dev_temp:temperatue''', so kann es passieren, dass die Ergebnisse im erzeugten Code dann '''Thermostat_Kueche''' und '''Thermostat_Kueche_temp''' lauten, statt wie gewünscht '''Thermostat_Kueche''' und '''temperature'''. Um dies zu vermeiden, sollten die Variablen besser '''device:Thermostat_Kueche''' und '''temp:temperatue''' lauten.

Im Folgenden ein paar Beispiele, wie Templates verwendet werden können.

===Einzelnes Widget===
Soll ein Widget an mehreren Stellen in exakt der selben Ausführung eingebunden werden, kann diese Widget in einer eigenen Datei erstellt und diese dann auf den Zielseiten automatisch mitgeladen werden.

;Template-Seite
Die Template-Seite soll in diesem Beispiel ''template_symbol.html'' genannt werden. Diese wird daher zuerst im FTUI-Verzeichnis erstellt.
<syntaxhighlight lang="html">
<div data-type="symbol"
data-device="dummy1">
</syntaxhighlight>

;Haupt-Seite
Die oben erstellte Template-Seite kann nun in jeder gewünschten Seite eingebunden werden.
<syntaxhighlight lang="html" highlight="6">
[...]
<body>
<div class="gridster">
<ul>
<li data-row="1" data-col="1" data-sizey="1" data-sizex="1">
<div data-template="template_symbol.html"></div>
</li>
</ul>
</div>
</body>
[...]
</syntaxhighlight>

===Gridster-Element===
Natürlich kann auch ein ganzes Gridster-Element - in diesem Fall ein Menü - als Template eingebunden werden.
<syntaxhighlight lang="html">
<li data-row="1" data-col="1" data-sizex="1" data-sizey="4" data-template="menu.html"></li>
</syntaxhighlight>

=== Widget-Gruppen ===
Die Template-Datei des [[#Einzelnes Widget|ersten Beispiels]] kann natürlich auch mehrere Widgets auf einmal enthalten.

=== Verwendung von Variablen ===
==== Einfaches Beispiel ====
Oft wird ein und dasselbe Widget für verschiedenen Devices verwendet. Um nicht für jedes Device das Widget neu kopieren zu müssen (bzw. bei Änderungen alle Seiten ausbessern zu müssen), kann ein Template verwendet werden, dem einfach per Parameter mitgeteilt wird, von welchem Device es gerade die Daten empfangen soll.

In diesem Beispiel wird ein Template erzeugt, dass nur die Temperatur verschiedenen Thermostate mittels eines [[FTUI Widget Label|Label-Widgets]] anzeigt.

;Template-Seite
Die Template-Seite enthält nur ein einfaches Label-Widget und wird in diesem Beispiel ''template_label.html'' genannt. Um sie für mehrere Devices verwenden zu können, wird im Attribut '''data-device''' der Name des eigentlichen Devices durch den Parameter '''par01''' ersetzt.
<syntaxhighlight lang="html" highlight="2">
<div data-type="label"
data-device="par01"
data-get="measured-temp"></div>
</syntaxhighlight>

;Haupt-Seite
Auf der Haupt-Seite wird die Template-Seite mit dem Attribut '''data-template''' eingebunden und ihr via Attribut '''data-parameter''' das jeweils gewünschte Device übergeben.
<syntaxhighlight lang="html">
[...]
<div data-template="template_label.html" data-parameter='{"par01":"Thermostat1"}'></div>
<div data-template="template_label.html" data-parameter='{"par01":"Thermostat2"}'></div>
<div data-template="template_label.html" data-parameter='{"par01":"Thermostat3"}'></div>
[...]
</syntaxhighlight>

==== Wetter-Slider mit Template ====
In diesem Beispiel wird ein [[FTUI Widget Slider|Slider-Widget]] erstellt, welches die verschiedenen Tage eines Wetterberichtes anzeigt. Dabei wird für den Wetterbericht des jeweiligen Tages immer dasselbe Template verwendet um nicht für jeden Tag ein eigenes Widget schreiben zu müssen.

;Template-Seite
<syntaxhighlight lang="html">
<div class="left">
<div data-type="label" data-device="AgroWeather" data-get="par01" data-unit="°C"></div>
<div class="inline">
<div data-type="label" data-device="AgroWeather" data-get="par02"></div>
<div data-type="weather" data-device="AgroWeather" data-get="par02"></div>
min: <div data-type="label" data-device="AgroWeather" data-get="par03" data-unit="°C"></div>
</div>
</div>
<div class="left">
<div data-type="label" data-device="AgroWeather" data-get="par04" data-substitution="toDate().eeee()+','"></div>
<div data-type="label" data-device="AgroWeather" data-get="par04" data-substitution="toDate().ddmm()"></div>
</div>
</syntaxhighlight>

;Haupt-Seite
In der Haupt-Seite wird das Template dann für jede Slider-Seite eingebunden und das Reading für den jeweiligen Tag via Parameter übergeben.
<syntaxhighlight lang="html">
[...]
<div data-type="swiper">
<ul>
<li data-template="templates/wetter.html" data-parameter='{"par01":"fc0_tempMax","par02":"fc0_weatherDay","par03":"fc0_tempMin","par04":"fc0_date"}'></li>
<li data-template="templates/wetter.html" data-parameter='{"par01":"fc1_tempMax","par02":"fc1_weatherDay","par03":"fc1_tempMin","par04":"fc1_date"}'></li>
<li data-template="templates/wetter.html" data-parameter='{"par01":"fc2_tempMax","par02":"fc2_weatherDay","par03":"fc2_tempMin","par04":"fc2_date"}'></li>
<li data-template="templates/wetter.html" data-parameter='{"par01":"fc3_tempMax","par02":"fc3_weatherDay","par03":"fc3_tempMin","par04":"fc3_date"}'></li>
</ul>
</div>
[...]
</syntaxhighlight>

== JavaScript-Funktionen ==
Neben den Widgets können auch einige JavaScript-Funktionen verwendet werden, um Befehle an FHEM zu senden.

Folgende Zeile setzt einen direkten Befehl an FHEM ab (<code>set dummy1 off</code>):
<syntaxhighlight lang="html"><div onclick="ftui.setFhemStatus('set dummy1 off')">Dummy1 aus</div></syntaxhighlight>

Diese Zeile veranlasst FHEM dazu, eine Funktion aus der 99_myUtils.pm auszuführen (<code>myUtils_HeizungUpDown("WZ.Thermostat_Climate","up")</code>):
<syntaxhighlight lang="html"><div onclick="ftui.setFhemStatus('{myUtils_HeizungUpDown("WZ.Thermostat_Climate","up")}')">+</div></syntaxhighlight>

Ein Beispiel, wie ein Kommando an FHEM gesendet wird und gleichzeitig der Wert eines bereits in FTUI angezeigten Readings verwendet werden kann:
<syntaxhighlight lang="html">
<div data-type="label" data-device="dummy1" data-get="temperature"></div>
<div onClick="ftui.setFhemStatus('set dummy2 '+ftui.getDeviceParameter('dummy1','temperature').val);">Senden</div>
</syntaxhighlight>

== Eigene Widgets erstellen ==
Wie eigenen Widgets für FTUI erstellt werden können, ist auf der Seite [[FTUI eigene Widgets]] beschrieben.

== FAQ ==
Häufig gestellte Fragen zum FHEM Tablet UI sind in der [[FHEM Tablet UI FAQ]] zusammengestellt.

== Links ==
* [https://github.com/knowthelist/fhem-tablet-ui Projekt auf Github]
* {{Link2Forum|Topic=34233|LinkText=Forums-Beitrag}}
* [[FTUI_Snippets|Snippets]]
* [http://knowthelist.github.io/fhem/tablet/demo_widgets.html Live-Demos]
* [https://waschto.eu/fhem-und-tabletui-livedemo/ FHEM und TabletUI Live-Demo]
* {{Link2Forum|Topic=37378|LinkText=User-Demos}}
* [https://github.com/ovibox/fhem-ftui-user-demos Download der User-Demo-Dateien]

[[Kategorie:FHEM Tablet UI|!]]

HomeMatic Fenster-Drehgriffkontakt Community-Nachbau

2018-04-15T13:22:34Z

Kaihs: /* Erstellen des OTA (Over The Air) Bootloaders */

Der HB-Sec-RHS Funk-Fenster-Drehgriffkontakt ist ein Selbstbau threeStateSensor zur
Überwachung eines Fenster-Drehgriffs.

Die Firmware ist identisch mit dem [https://www.elv.de/homematic-funk-fenster-drehgriffkontakt-1.html Originalen Sensor von ELV] und verhält sich dementsprechend auch gleich.

== Übersicht ==

Die Grundidee zu diesem Sensor wurde durch {{Link2Forum|Topic=71413.0|LinkText=Kawaci im Forum}} geliefert.
Die Umsetzung besteht aus einer Atmega328p Platine mit CC1101 Funkmodul (868 MHz) sowie
einer auf der [https://github.com/pa-pa/AskSinPP AskSin++] Portierung des Homematik Protokolls.

Anfangs gab es zwei Ideen wie der Sensor aussehen sollte. Inzwischen hat sich die HomeMatic Variante mit CR2032 Batteriehalterung auf der Platine durchgesetzt. Somit wird hier nicht näher auf andere Versionen (zwei Platinen zur Erfassung der Fensterstellung) eingegangen.

== Platine ==
'''Schaltplan:'''
[[Datei:FDGK_v1.0_sch.jpg]]

'''Platine v1.0 (Oberseite mit korrigierter Pinbelegung):'''
[[Datei:FDGK_v1.0_top.jpg]]

'''Platine v1.0 (Unterseite, ohne bestücktes Radio):'''
[[Datei:FDGK_v1.0_bot.jpg]]

== Bauteilliste ==
Die Bauteilliste gibt es auf [https://github.com/pa-pa/HMSensor/blob/master/HMSensor-CR2032/Parts.xls GitHub].

In der Liste sind die Magnete und Reed-Kontakte nicht aufgeführt.
Folgende können verwendet werden:
* Reed-Kontakt 2x14mm [https://de.aliexpress.com/item/10pcs-N-O-Reed-switch-Magnetic-Switch-2-14mm-Normally-Open-Magnetic-Induction-switch/32803902404.html Aliexpress]
* Neodym Magnet 2x2mm [https://de.aliexpress.com/item/100pcs-2x2mm-magnet-2x2-Super-strong-neo-neodymium-magnet-N35-D2x2-D2x2mm-permanent-magnet-D2-2mm/32693530575.html Aliexpress]

== Zusammenlöten der SMD Bauteile ==
Die Bestückung der Platine ist im [https://forum.fhem.de/index.php/topic,71413.msg640858.html#msg640858 diesem Post] kurz beschrieben.

'''Bemerkung:'''
Y1 (32 kHz Quarz), C4 und C5 sind nicht erforderlich.
Vor dem Verlöten der Bauteile sollte kontrolliert werden, ob die Platinen in das Gehäuse passen. Falls nicht, sollte entweder das Gehäuse oder die Platine passend gefeilt werden.

Zuerst auf der Unterseite IC1 bestücken:
Hierzu einen beliebigen äußeren Pin verzinnen, den Prozessor mit der richtigen Orientierung von Pin 1 (runder Punkt) platzieren und den Pin verlöten.
Darauf achten, dass der Prozessor mittig auf den Pads aufliegt, ggf. den Pin wieder erhitzen
und den IC drehen oder verschieben. Auf der gegenüberliegenden Seite ebenfalls einen Pin verlöten, damit der IC fixiert ist.
Mit einem Flussmittelstift auf allen vier Seiten die Pins bestreichen und auf jeder Seite die Pins einzeln mit einer feinen Lötspitze bzw. feinem Lötzinn verlöten. Kurzschlüsse zwischen einzelnen Pins müssen unbedingt vermieden werden.

Danach auf der Unterseite C1, C2, C3 sowie R1 bestücken.
Auf der Oberseite R2, D1 (rot), R3, D2 (gelb), C6 und die beiden Taster bestücken.

Nach dem [https://wiki.fhem.de/wiki/HomeMatic_Fenster-Drehgriffkontakt_Community-Nachbau#Firmware Flashen der Firmware] das Radio (IC2) bzw. den Batteriehalter (BT1) bestücken.
Als Antenne (ANT) wird ein Draht mit 72 mm Länge eingelötet.

== Firmware ==

=== Bootloader ===

Die Sensorfirmware kann OTA (Over The Air) oder über den Arduino Bootloader geladen werden.

=== Erstellen des OTA (Over The Air) Bootloaders ===
{{Randnotiz|RNText=Firmware für 'ID=0030'}}
Dafür wird, mit Hilfe der [https://forum.fhem.de/index.php?action=dlattach;topic=71413.0;attach=91780 makeota.html] der Bootloader mit den benötigten Daten gefüllt und anschließend generiert.

Die makeota.html wird dazu in einem beliebigen Browser aufgerufen.

Die Felder ''HM ID'' und ''HM-Serial'' innerhalb der makeota.html können jeweils frei gewählt werden (dabei die Vorgaben beachten, so z.B. ''HM ID'': 6 hexadezimale Zeichen). Das Feld ''Device Type'' muss folgende Nummer beinhalten: "0030". Das Feld ''Config String'' wird aus den eingegebenen Daten automatisch generiert.

Die zwei o.g. Felder müssen sich von Gerät zu Gerät unterscheiden. Aus diesem Grund ist es sinnvoll, sich die eingegebenen Daten aufzuschreiben oder Screenshots zu erstellen.

Nun muss noch dem Bootloader bekannt gemacht werden, welche Batterien mit dem FDGK verwendet werden. Dies wird über die dropdown Liste "Power Presets" ausgewählt:

Dabei bedeutet:

*No StepUp = CR2032 Batterie
*StepUp single AA = eine AA Batterie und StepUp
*StepUp two AAA = zwei AAA Batterien und StepUp

Die Parameter „Step-Up Present“, „Low-Voltage“ und „Critical Voltage” ergeben sich aus der Wahl in der DropDown Liste, können aber individuell angepasst werden. Für den fehlerfreien Betrieb sollten diese aber unverändert bleiben!

Seit 12/2017 kann optional die [https://forum.fhem.de/index.php?action=dlattach;topic=71413.0;attach=91779 aktuelle Firmware] mit angegeben werden, so dass die Firmware gleichzeitig mit dem Bootloader geflasht werden kann. In diesem Fall kann der FDGK sofort in Betrieb genommen werden und nur es wird nur eine aktualisierte Firmware per OTA (Over The Air) geflasht.

Nach drücken der Taste "Create" erscheint eine Schaltfläche "Save Bootloader", mit welcher der angepasste Boorloader gespeichert werden kann. Es wird hierzu kein Netzzugang benötigt. Alles erfolgt per Javascript im Browser.

Seit 01/2018 gibt es die Firmware auch für das sog. ''lazy config''. Hierbei können die Register einfach z.B. durch das nächste Öffnen des Fensters ausgelesen werden, ohne dass die Config-Taste gedrückt werden muss.
Das Update auf ''lazy config'' geht auf zwei Arten:

Keine Änderung der 'ID=0030' und Durchführen eines [https://forum.fhem.de/index.php?action=dlattach;topic=71413.0;attach=94541 Firmware] bzw. eines FHEM Updates oder
{{Randnotiz|RNText=Firmware für 'ID=00C3'}}
Aktualisierung der Firmware auf 'ID=00C3'. Die Dateien können hier: [https://forum.fhem.de/index.php?action=dlattach;topic=71413.0;attach=94538 makeota.html], [https://forum.fhem.de/index.php?action=dlattach;topic=71413.0;attach=94542 Firmware (hex)] bzw. [https://forum.fhem.de/index.php?action=dlattach;topic=71413.0;attach=94541 Firmware (eq3)] heruntergeladen werden.

Verwendet man den Sensor in Kombination mit originaler eq3 Hardware, sollte man die zweite Möglichkeit wählen.

=== Flashen des OTA Bootloaders ===
Anschließend wird per ISP (USBasp oder vergleichbares) der Bootloader geflasht.
Zum Laden des Bootloaders, sowie der Software werden die Arduino SDK bzw. avrdude und die von makeota.html generierte Datei benötigt.

Der Bootloader lässt sich nun bei gestecktem ISP Programmer über folgende Befehle flashen:

<pre>avrdude -p m328p -P usb -c usbasp -B 3 -U lfuse:w:0xE2:m -U hfuse:w:0xD0:m -U efuse:w:0x06:m -U lock:w:0x2F:m</pre>
Setzt die Fuses.

<pre>avrdude -p m328p -P usb -c usbasp -V -U flash:w:bootloader.hex</pre>
lädt den eigentlichen Bootloader. Dabei ist zu achten, dass "bootloader.hex" die Datei mit dem Bootloader (bzw. der Firmware) ist und dementsprechend auch im Verzeichnis sein muss, wo die Datei zu finden ist.

Wenn jetzt die Platine mit Spannung versorgt wird, sollte die rote LED 7x blinken. Das signalisiert, dass der Bootloader erfolgreich gestartet wurde. Er wartet jetzt darauf, dass die Firmware übertragen wird.

=== OTA Update ===
Hierzu wird flash-ota benötigt.

Flash-ota funktioniert aktuell nur mit [[CUL]]/[[COC]] oder [[HM-CFG-USB USB Konfigurations-Adapter|HM-CFG-USB]] unter Linux ([[HomeMatic_Firmware_Update#Firmware_Update_mit_CUL.2FHM-CFG-USB_unter_FHEM|Update mit CUL oder HM-CFG-USB unter Linux]]), mit dem "HomeMatic Firmware Update Tool" unter Windows ([[HomeMatic_Firmware_Update#Firmware_Update_mit_HM-CFG-USB_unter_Windows|Update mit HM-CFG-USB unter Windows]]) oder mit einer CCU2.

Für einen HM-CFG-USB oder den HM-UART sieht der Aufruf wie folgt aus:

<pre>./flash-ota -f avr_HM_SEC_RHS_201705271601.eq3 -s RHS0000000</pre>

Für einen CUL muss noch die USB Schnittstelle oder der Pfad des USB Geräts mit gegeben werden:

<pre>./flash-ota -f avr_HM_SEC_RHS_201705271601.eq3 -s RHS0000000 -c /dev/serial/by-path/platform-3f980000.usb-usb-0:1.3:1.0-port0</pre>

Falls Fehler während der Übertragung auftreten, muss die Übertragung nochmals wiederholt werden.
Wenn die Firmware erfolgreich übertragen werde konnte, kann der Sensor gepairt werden.

== Einlöten der Reedkontakte und Anschluss an A0 & A1 ==
Den Magneten in den Drehring einbauen und diesen in das Gehäuse einbauen. Die Reedkontakte
Platzieren und mit einem Ohmmeter Messen, ob die Reedkontakte bei der entsprechenden Position
der Magnete schalten. Falls nicht, ggf. die Reedkontakte austauschen (Streuung!) bzw. einen stärkeren Magneten verwenden. Danach mittels Silberdraht bzw. Kupferlackdraht (an den zu
verlötenden Enden den Lack mittels eines Cuttermessers entfernen) die Reedkontakte gemäß
Bild verlöten und die Enden (GND, A0 bzw. A1) durch die vorgesehenen Öffnungen im Gehäuse führen.

''Verlötete Reedkontakte:''
[[Datei:HM_Fenstersensor-pic15.jpg]]

Danach die Antenne in die dafür vorgesehene Bohrung einführen und die Platine platzieren. Darauf achten, dass die Anschlüsse der Reedkontakte durch die dafür vorgesehenen Kontakte auf der Platine geführt werden.

''Einführen der Antenne:''
[[Datei:HM_Fenstersensor-pic17.jpg]]

''Platzierte Platine:''
[[Datei:HM_Fenstersensor-pic16.jpg]]

Nach Verlöten der drei Kontaktpunkte ist der Fensterdrehgriff fertig aufgebaut.

== Sensor spezifische Einstellungen ==
Der Sensor meldet die Position entsprechend welcher Zustand an A0 & A1 an liegt. Derzeit ist folgende Logik implementiert:

A0 & A1 offen - PosA -> OPEN

A0 geschlossen - PosB -> CLOSED

A1 geschlossen - PosC -> TILTED

Die Bedeutung der Positionen kann mittels der entsprechenden Register eingestellt werden.

Ebenfalls kann die CyclicInfoMsg aktiviert werden (zum aktivieren siehe Link am Ende des Artikels). Der Sensor meldet sich dann alle 24 Stunden mit dem aktuellen Status.

Register zum ändern der Position von A0 & A1:

<pre>set <Device_Name> regSet msgRhsPosA <closed|open|noMsg|tilted></pre>
<pre>set <Device_Name> regSet msgRhsPosB <closed|open|noMsg|tilted></pre>
<pre>set <Device_Name> regSet msgRhsPosC <closed|open|noMsg|tilted></pre>

== Gehäuse ==
Für das Gehäuse wurde auf eine 3D-Drucklösung gesetzt. Es gibt inzwischen mehrere Versionen (abgerundete obere Kante, eckige Kante uvm.).

Die Standard Version ist [https://www.thingiverse.com/thing:2354704 hier] zu finden.

Wer keinen 3D-Drucker besitzt kann sich im Forum nach einem 3D-Druckservice um schauen. Einige User bieten gegen kleines Geld einen netten und preiswerten {{Link2Forum|Topic=70413|LinkText=Service}} an.

== Links ==
*[https://forum.fhem.de/index.php/topic,71413.0.0.html Link zum Foren-Thread]
*[https://github.com/pa-pa/AskSinPP AskSinPP Libary]
*[https://github.com/pa-pa/HMSensor Alles Mögliche zu dem Projekt auf Github]
*[[HomeMatic_Type_threeStateSensor|CyclicInfoMsg aktivieren]]
*{{Link2Forum|Topic=70413|LinkText=3D-Druck service}}
*[[HomeMatic_Firmware_Update#Firmware_Update_mit_CUL.2FHM-CFG-USB_unter_FHEM|update-ota]]

[[Kategorie:HomeMatic Components‏‎]]
[[Kategorie:HomeBrew‏‎]]

FTUI Widget Pagetab

2018-03-05T19:19:43Z

Kaihs: Typo

Das [[{{PAGENAME}}|Pagetab Widget]] ist ein Widget für [[FHEM Tablet UI]], welches es erlaubt, den Inhalt einer Seite durch den einer anderen zu ersetzen. Es kann zum Beispiel für ein Menü verwendet werden.

<gallery>
File:FTUI_Widget_Pagetab_03.png
File:FTUI_Widget_Pagetab_04.png
File:FTUI_Widget_Pagetab_01.png
File:FTUI_Widget_Pagetab_02.png
</gallery>

==Attribute==
{|class="wikitable"
!Attribut
!Beschreibung
!Standard-Wert
!Beispiel
|-
|'''data-device'''||FHEM Device, dessen Status das Aussehen des Widgets bestimmt||||data-device="dummy1"
|-
|'''data-url'''||URL der neuen Seite, die angezeigt werden soll||||data-url="content_main.html"
|-
|'''data-icon'''||Vordergrund-Icon des Widgets||fa-power-off||data-icon="mi-home"
|-
|'''data-background-icon'''||Hintergrund-Icon des Widgets||fa-circle||data-background-icon="fa-square"
|-
|'''data-on-background-color'''||Farbe des Hintergrund-Icons, wenn der gewünschte Inhalt angezeigt wird||#606060||data-on-background-color="gray"
|-
|'''data-off-background-color'''||Farbe des Vordergrund-Icons, wenn der gewünschte Inhalt nicht angezeigt wird||transparent||data-off-background-color="#cccccc"
|-
|'''data-on-color'''||Farbe des Vordergrund-Icons, wenn der gewünschte Inhalt angezeigt wird||#222222||data-on-color="yellow"
|-
|'''data-off-color'''||Farbe des Vordergrund-Icons, wenn der gewünschte Inhalt nicht angezeigt wird||#505050||data-off-color="#000000"
|-
|'''data-get-on'''||Ein Array an Stati eines Devices. Je nach Status wird ein anderes Icon aus ''data-icons'' angezeigt.||||data-get-on='["Ein","Pause","Aus"]'
|-
|'''data-icons'''||Ein Array an Icons, die in Abhängigkeit von ''data-get-on'' angezeigt werden||||data-icons='["mi-play_arrow","mi-pause","mi-stop"]'
|-
|'''data-return-time'''||Kehrt nach der angegebenen Zeit in Sekunden wieder zur "Startseite" zurück. Muss auf dem ersten Pagetab gesetzt werden||0 (endlos)||data-return-time="5"
|-
|'''data-text'''||Text für die Beschreibung||||data-text="Home"
|}

==CSS Klassen==
{|class="wikitable"
{{FTUI Klasse|warn}}{{FTUI Klasse|activate}}{{FTUI Klasse|labelright}}
|}

==Hinweise==
* Das Attribut '''data-return-time''' muss auf dem "Haupt-Pagetab" (dem ersten; index 0) platziert werden

==Beispiele==
===Einfacher Link===
<syntaxhighlight lang="html">
<div data-type="pagetab"
data-url="index.html"
data-icon="mi-home"></div>
</syntaxhighlight>
[[File:FTUI_Widget_Pagetab_03.png]]

===Einfacher Link mit Beschreibungstext===
<syntaxhighlight lang="html">
<div data-type="pagetab"
data-url="index.html"
data-icon="mi-home"
data-text="home"></div>
</syntaxhighlight>
[[File:FTUI_Widget_Pagetab_04.png]]

===Navigationsleiste===
Ein guter Anwendungszweck für das Pagetab-Widget ist eine Navigationsleiste. Dazu braucht es allerdings mehrere Seiten:
*Eine mit der Navigation selbst. Die wird später als Template auf den Zielseiten eingebunden
*Eine Startseite
*Eine oder mehrere Zielseiten, auf die navigiert werden kann

;Menü-Seite (menu.html)
Eine Menü-Seite könnte z.B. wie folgt aussehen. Auf dieser Seite sind drei Pagetab-Widgets platziert.
*Das erste ist ein ganz einfacher Link mit einem Beschreibungstext. Die Seite unter ''data-url'' wird beim Aufruf der Startseite automatisch geladen.
*Das zweite Widget ändert sein Icon je nach Status-Wert des Dummies ''dummy1''. Ist der Status 0, wird nur das Icon ''fa-fax'' angezeigt. Ist der Status größer 0, erscheint rechts über dem Icon noch ein "Warnhinweis" mit dem Status-Wert des Dummies. Außerdem ist der Beschreibungstext nach rechts gerückt.
*Das dritte Widget funktioniert im Prinzip wie das zweite. Außer der Status-Wert des Dummies ist ''on''. Dann wird die im Widget verlinkte Seite automatisch geöffnet.

<syntaxhighlight lang="html">
<!DOCTYPE html>
<html>
<head>
</head>
<body>
<div class="sheet">
<div class="row">
<div data-type="pagetab"
data-url="pagetab01.html"
data-icon="fa-home"
data-text="home"
class="cell"></div>
</div>
<div class="row">
<div data-type="pagetab"
data-device="dummy1"
data-get-on='["0","1"]'
data-icons='["fa-fax","fa-fax warn"]'
data-url="pagetab02.html"
data-text="anrufe"
class="cell labelright"></div>
</div>
<div class="row">
<div data-type="pagetab"
data-device="dummy2"
data-get-on='["0","(?:[1-9][0-9]*)","on"]'
data-icons='["fa-fax","fa-fax warn","fa-fax warn activate"]'
data-url="pagetab03.html"
class="cell"></div>
</div>
</div>
</body>
</html>
</syntaxhighlight>

;Startseite (index.html)
Auf der Startseite müssen keine Inhalte sein. Durch das erste Pagetab-Widget wird dessen URL automatisch geladen. Allerdings ist das Menü-Template einzubinden.

<syntaxhighlight lang="html">
<!DOCTYPE html>
<html>
<head>
<script src="js/fhem-tablet-ui.js" defer></script>
<title>FHEM-Tablet-UI</title>
</head>
<body>
<div class="gridster">
<ul>
<li data-row="1" data-col="1" data-sizex="1" data-sizey="4" data-template="menu.html"></li>
<li data-row="1" data-col="2" data-sizex="4" data-sizey="4"></li>
</ul>
</div>
</body>
</html>
</syntaxhighlight>

;Zielseiten (pagetab01.html, pagetab02.html, pagetab03.html)
Die Zielseiten können ganz normal gestaltet werden. Es ist nur darauf zu achten, dass auf jeder Zielseite auch das Menü-Template eingebunden wird. Eine Zielseite könnte so aussehen:

<syntaxhighlight lang="html">
<!DOCTYPE html>
<html>
<head></head>
<body>
<div class="gridster">
<ul>
<li data-row="1" data-col="1" data-sizex="1" data-sizey="4" data-template="menu.html"></li>
<li data-row="1" data-col="2" data-sizex="4" data-sizey="4" class="left-align">Pagetab02.html</li>
</ul>
</div>
</body>
</html>
</syntaxhighlight>

Wird nun auf eines der Icons geklickt, blendet die aktuelle Seite aus und die Zielseite wird eingeblendet.

[[File:FTUI_Widget_Pagetab_02.png]]

==Weblinks==

[[Kategorie:FHEM Tablet UI|Pagetab]]

PRESENCE

2018-01-24T19:40:06Z

Kaihs: Typos

{{Infobox Modul
|ModPurpose=Anwesenheitserkennung
|ModType=h

|ModTechName=73_PRESENCE.pm
|ModOwner=markusbloch
}}

Das [[PRESENCE]] Modul bietet für die Anwesenheitserkennung mehrere Varianten an:

* '''lan-ping''' - Das Überwachen via PING Checks, die durch den FHEM Server versandt werden.
* '''fritzbox''' - Das Überwachen von Geräten auf einer FritzBox via ctlmgr_ctl (Nur auf einer FritzBox möglich)
* ''' Bluetooth'''
:- '''local-bluetooth''' - Das Überwachen via Bluetooth Checks, die vom FHEM Server direkt durchgeführt werden (angeschlossener Bluetooth-Stick und die Software bluez voraussgesetzt)
:- '''lan-bluetooth''' - Das Überwachen von Bluetoothgeräten, über Netzwerk. Auf einer oder mehreren Maschinen im Netzwerk (z.B. [[:Kategorie:Raspberry Pi|Raspberry Pi]]) läuft ein Presence-Daemon, der nach Bluetooth-Geräten sucht. Um mehrere Presence-Daemon mit FHEM zu verbinden, gibt es den Collector-Daemon, der sich zu allen Presence-Damons im Netzwerk verbindet und das Ergebnis von allen zusammenfasst.
* '''function''' - Das Überwachen mithilfe einer selbst geschrieben Perl-Funktion, die den Anwesenheitsstatus zurückgibt (0 oder 1)
* '''shell-script''' - Das Überwachen mithilfe eines selbst geschriebenen Shell-Programms/Skript, das eine 0 oder 1 ausgibt, um den Anwesenheitsstatus mitzuteilen.

= Überwachen mittels Ping im WLAN/LAN =
{{Randnotiz|RNText=Um diese Methode auf einer FritzBox nutzen zu können, muss FHEM mit root-Rechten laufen. Dies ist standardmäßig nicht der Fall. Bitte dazu den Wiki Artikel [[FritzBox: fhem unter root starten]] beachten.}}
Um ein Gerät via Ping zu überwachen, muss folgende Definition durchgeführt werden:
:<code>define Handy PRESENCE lan-ping 192.168.0.30</code>

Dadurch wird die IP-Addresse 192.168.0.30 alle 30 Sekunden geprüft, ob sie erreichbar ist. Wenn sie erreichbar ist, ist der Status "present" (anwesend), ansonsten "absent" (abwesend).

Der Timeout kann verändert werden, indem ein Wert (in Sekunden) an das Define anhängt wird:
:<code>define Handy PRESENCE lan-ping 192.168.0.30 '''60'''</code>

Nun würde das Handy alle 60 Sekunden geprüft werden.

Nur wenn bei einem iPhone/iPad die Funktion "über WLAN synchronisieren" aktiviert ist, ist es auch im Standby zuverlässig pingbar. Standardmäßig deaktivieren Apple-Geräte ihr WLAN im Standby-Betrieb um die Akkulaufzeit zu verlängern.

Sollte die Fehlermeldung
:<code> PRESENCE (Handy) - ping command returned with output: ping: icmp open socket: Operation not permitted </code>
im Log auftauchen und lan-ping dadurch nicht funktionieren, liegt ein Berechtigungsproblem vor. Kein Grund den User fhem zu root zu machen!
Prüfe zu erst als User root ob die Capabilities gesetzt sind.
:<code>getcap /bin/ping</code>
Sollte folgendes Ergeben zu Tage fördern.
:<code>/bin/ping = cap_net_raw+ep</code>
Ist dem nicht so, setzen wir die benötigten Capabilities
:<code>setcap cap_net_raw+ep /bin/ping</code>
Mehr Informationen zum Thema Capabilities [https://manpages.debian.org/jessie/manpages-de/capabilities.7.de.html].

= FritzBox: direktes Abfragen der Aktivität via ctlmgr_ctl =
{{Randnotiz|RNText=Um diese Methode auf einer FritzBox nutzen zu können, muss FHEM mit root-Rechten laufen. Dies ist standardmäßig nicht der Fall. Bitte dazu den Wiki Artikel [[FritzBox: fhem unter root starten]] beachten.}}
Eine sehr häufige und auch zuverlässige Methode ist auf einer FritzBox die Abfrage mittels ctlmgr_ctl Befehl. Über diesen lassen sich alle Geräte abfragen ob sie aktiv sind. Ist ein Gerät aktiv, so gilt es als anwesend.

Dieser Modus kann allerdings nur in FHEM Installationen direkt auf einer FritzBox verwendet werden. Des weiteren muss FHEM unter dem User root laufen. Um ein Gerät zu überwachen, wird lediglich der Gerätename benötigt, so wie er unter dem Menüpunkt "Heimnetz" auftaucht.

Die erforderliche Definition:
:<code>define Handy PRESENCE fritzbox iPhone-4S</code>

= Überwachung mittels Perl-Code =
Es ist möglich zum Überwachen von Geräten eine eigene Perl-Funktion zu verwenden die dann vom PRESENCE Modul im Hintergrund aufgerufen wird.

define <name> PRESENCE function {...} [ <check-interval> [ <present-check-interval> ] ]

Sobald die Funktion den Rückgabewert 1 hat, ist das Gerät anwesend, bei 0 abwesend.

== Beispiel DHCP Überwachung auf Airport Basestation ==
Die hier vorgestellte Überwachung der DHCP Lease auf Airport Basestations per SNMP ist absolut robust gegenüber dem Ruhezustand von iOS und setzt keine weitere Konfiguration auf dem iPhone voraus. Das Abmelden beim Verlassen des Empfangsbereiches der Basestation geschieht mit etwa 5-10 Minuten Verzögerung und ist somit auch vor kurzzeitigen Empfangsproblemen sicher. Das nebenstehende Bild (???) verdeutlicht noch mal die Unterschiede zwischen einer IP-Basierten Ping-Überwachung und der Überwachung auf Ebene der Basestation oder FritzBox.

Bevor der folgende Code verwendet werden kann ist das Perl Modul Net:SNMP zu installieren (z. B. mit: <code>cpan install use Net::SNMP</code>).

Zuerst ist folgender Code in 99_myUtils.pm einzufügen, sollte diese noch nicht vorhanden sein muss diese aus dem Template welches unter Edit Files zu finden ist erzeugt werden.
'''Achtung, das ist nicht der komplette Inhalt der 99_myUtils!''' Das ist nur die einzelne Routine

<pre>
use Net::SNMP;
sub
snmpCheck($$)
{
my ($airport,$client)= @_;

my $community = "public";
my $host = $airport;
my $oid = ".1.3.6.1.2.1.3.1.1.2";
#my $oid = ".1.3.6.1.2.1.3.1.1.2.25.1.10.0.1";

my ( $session, $error ) = Net::SNMP->session(
-hostname => $host,
-community => $community,
-port => 161,
-version => 1
);

if( !defined($session) ) {
return 0;
return "Can't connect to host $host.";
}

my @snmpoids = ();

my $response = $session->get_next_request($oid);
my @nextid = keys %$response;
while ( @nextid && $nextid[0] && $nextid[0] =~ m/^$oid/ ) {
push( @snmpoids, $nextid[0] );

$response = $session->get_next_request( $nextid[0] );
@nextid = keys %$response;
}

if( !defined($response = $session->get_request( @snmpoids ) ) ) {
return 0;
}

foreach my $value (values %$response) {
return 1 if( $value eq $client )
}

return 0;
}
</pre>

Danach lässt sich das Mobilgerät so überwachen:
:<code>define iPhone PRESENCE function {snmpCheck("10.0.1.1","0x44d77429f35c")} 30 30</code>

wobei 10.0.1.1 durch die IP-Adresse der Basestation und 0x44d77429f35c durch die MAC Adresse des Geräts als HEX-Zahl ersetzt werden muss.

== Beispiel Anwesenheitserkennung mittels UniFi Controller ==

Die Anwesenheitserkennung bei Geräten in Verbindung mit UniFi-Produkten funktioniert selbst dann, wenn sich die Geräte im PowerSave-Modus befinden.

Beachte: Die Geräte werden erst ungefähr nach 5 Minuten, nachdem das Gerät das WLAN verlassen hat als disconnected angezeigt.

<code>define <NAME> PRESENCE function {ReadingsVal("<UniFi>","<NamedDevice>","") eq "connected" ? 1:0}</code>

= Überwachen mittels Events =
Der Vorteil gegenüber der Function-Variante ist, dass diese Variante ohne Blocking.pm-Overhead direkt ausgeführt werden kann und in "Echtzeit" abläuft (siehe {{Link2Forum|Topic=40287|Message=562823}}).

<code>define <NAME> PRESENCE event UniFi:NamedDevice:.disconnected UniFi:NamedDevice:.connected</code>

= Überwachen mittels Bluetooth =
== Vorbereitung und Informationen ==
=== Getestete Hardware/Software ===
* '''Raspbian System''' - wheezy, Jessie (interner BT-Controller)
* '''BT-Dongle''' - CSL NET BT USB2.0 Stick, Bluetooth V4.0, Nano <br />'''Achtung''': Es muss ein BT V4.0 oder höher verwendet werden. Nur dieser unterstützt ''LowEnergy''
* '''BT-TAG''' - Gtag von Gigaset, TrackR, UDOO Neo, PebbleBee, iTag von Unitec, X4-LIFE Multifunkti BL-Anhänger, iTag Wireless Anti, Trackr bravo

=== BT Dongel am PI installieren ===
Um den BT Dongle ''(hier: CSL NET BT USB2.0)'' am PI verwenden zu können, müssen die notwendigen Pakete über die Paketverwaltung von debain nachinstalliert werden.
Wer bereits ein BT-Dongle installiert hat, kann diesen Schritt überspringen.
<pre>
apt-get install bluetooth
</pre>
Nach erfolgreicher Installation der Pakete sollte der RaspberryPI neu gestartet werden.
<pre>
sudo reboot
</pre>

Nach dem erfolgten Reboot bitte das Log des Raspberry auf folgende Einträge prüfen:
<pre>
Feb 12 19:52:55 fhem kernel: [ 4.773600] Bluetooth: Core ver 2.20
Feb 12 19:52:55 fhem kernel: [ 4.773748] NET: Registered protocol family 31
Feb 12 19:52:55 fhem kernel: [ 4.773765] Bluetooth: HCI device and connection manager initialized
Feb 12 19:52:55 fhem kernel: [ 4.773797] Bluetooth: HCI socket layer initialized
Feb 12 19:52:55 fhem kernel: [ 4.773821] Bluetooth: L2CAP socket layer initialized
Feb 12 19:52:55 fhem kernel: [ 4.773890] Bluetooth: SCO socket layer initialized
Feb 12 19:52:55 fhem kernel: [ 4.797531] usbcore: registered new interface driver btusb
</pre>
Sobald der BT-Dongle erkannt wurde ''leuchtet'' (wenn vorhanden) auch die ''blaue/gelbe'' LED am Dongle auf.

=== BT-Tags aktivieren ===
Jetzt kann der BT-Tag aktiviert werden. Bei einigen Tags muss dafür die '''Batteriesicherung''' gezogen werden.

Einen Tag wird mit folgendem Befehl auf der Konsole gesucht:
<syntaxhighlight lang="bash">
sudo hcitool lescan

Ausgabe z.B.:
LE Scan ...
7C:2F:80:A1:XA:XD (unknown)
7C:2F:80:A1:XA:XD Gigaset G-tag
7C:2F:80:A1:X4:X1 (unknown)</syntaxhighlight>
Eine Übersicht über die möglichen Befehle von hcitool gibt es mit der Eingabe von:
<pre>
sudo hcitool

Ausgabe z.B.:
hcitool - HCI Tool ver 5.23
Usage:
hcitool [options] <command> [command parameters]
Options:
--help Display help
-i dev HCI device
Commands:
dev Display local devices
inq Inquire remote devices
scan Scan for remote devices
name Get name from remote device
info Get information from remote device
spinq Start periodic inquiry
epinq Exit periodic inquiry
cmd Submit arbitrary HCI commands
con Display active connections
cc Create connection to remote device
dc Disconnect from remote device
sr Switch master/slave role
cpt Change connection packet type
rssi Display connection RSSI
lq Display link quality
tpl Display transmit power level
afh Display AFH channel map
lp Set/display link policy settings
lst Set/display link supervision timeout
auth Request authentication
enc Set connection encryption
key Change connection link key
clkoff Read clock offset
clock Read local or remote clock
lescan Start LE scan
lewladd Add device to LE White List
lewlrm Remove device from LE White List
lewlsz Read size of LE White List
lewlclr Clear LE White list
lecc Create a LE Connection
ledc Disconnect a LE Connection
lecup LE Connection Update
</pre>

Falls beim SCAN kein Tag gefunden wird, sollte das BT Interface neu gestartet werden. Dazu ist kein Reboot des PI notwendig.
<syntaxhighlight lang="bash">
sudo hciconfig hci0 down
sudo hciconfig hci0 up
sudo hcitool dev
</syntaxhighlight>

== Überwachung durch den FHEM Server direkt ==
[[Datei:Bluetooth-Adresse-iPhone.png|thumb|Bluetooth-Adresse eines iPhones]]
Jenach Aufstellungsort des FHEM Servers kann es sinnvoll sein, eine Bluetooth-Überwachung direkt durch den FHEM Server durchzuführen. Hierbei gilt allerdings zu beachten, dass Bluetooth nicht für große Reichweiten gedacht ist und in den meisten Fällen keine Wände überwinden kann. Das heisst, dass in den meisten Fällen damit nur ein Raum überwacht werden kann.

Je nach Einsatzzweck kann das auch so gewollt sein. Bluetooth USB Sticks, die bereits Bluetooth 4.0 unterstützen, können höhere Reichweiten über Zimmerwände hinaus erreichen. Vorausgesetzt, das Mobilgerät unterstützt Bluetooth 4.0.

Um eine Überwachung per Bluetooth durchführen zu können, benötigt man die Bluetooth-Adresse eines Gerätes. Diese ähnelt vom Aufbau einer MAC-Adresse. Generell wird die Adresse in den Telefon-Informationen bei Smartphones angezeigt.

Um eine Anwesenheitserkennung via Bluetooth durchzuführen, wird folgende Definition in der [[Konfiguration]] benötigt:
:<code>define Handy PRESENCE local-bluetooth XX:XX:XX:XX:XX:XX</code>

== Überwachung durch verteilte Agenten in der Wohnung (presenced/lepresenced/collectord) ==
[[Datei:Raspberry-Pi-mit-WLAN-und-Bluetooth-Stick.jpg|thumb|left|Raspberry Pi mit Bluetooth- und WLAN-USB-Stick]]
Um eine zuverlässige und flächendeckende Bluetooth-Anwesenheitserkennung durchzuführen, ist es unerlässlich, mehrere Bluetooth-Empfänger zu verwenden, die auf mehrere oder alle Räume verteilt sind.

Hierfür bietet sich zum Beispiel ein [[Raspberry Pi]] mit einem Mini-Bluetooth-USB-Stick und evtl. einem WLAN-USB-Stick an. Jeder Raum wird mit solch einem Raspberry ausgestattet und ist im WLAN Netz verfügbar.

Dieses Netz aus Raspberrys wird mit dem presenced / lepresenced Programm ausgestattet. Beide Programme sind Perl-Skripte, die als Daemon im Hintergrund laufen und auf Anfragen via Netzwerk warten. Es wird lediglich eine vollständige Perl-Grundinstallation mit Standardmodulen benötigt.

=== Unterschied presenced / lepresenced / collectored ===
presenced und lepresenced sind Programme, welche in regelmäßigen Abständen nach Bluetooth-Geräten suchen. Sobald ein Gerät, welches vorab definiert wurde, gefunden wird, wechselt der Status des Geräts in FHEM auf Anwesend. Der Unterschied zwischen presenced und lepresenced ist, dass lepresenced insbesondere für [https://de.wikipedia.org/wiki/Bluetooth_Low_Energy Bluetooth-LE-Devices] ist und presenced für "normale" Bluetooth-Geräte.

collectored wiederum ist ein Programm, welches mehrere Pis verbindet und auf allen den aktuellen Status von presenced/lepresenced abfragt. Ist das gesuchte Bluetooth-Gerät auf einem der Pi anwesend, so wird es auch in der definierten Hauptinstanz auf anwesend gesetzt. Zusätzlich wird der Pi auf dem das Gerät gefunden wurde als Reading angegeben.

=== Installation von (le)presenced ===
Diese Anleitung ist sowohl für presenced, als auch für lepresenced gültig. Einfachheitshalber wird nur lepresenced erwähnt, sämtliche Schritte gehen jedoch auch mit presenced, wobei einfach die genannten Daten durch presenced ersetzt werden müssen.

Die Software lepresenced kann aktuell über drei Varianten installiert werden. Dabei ist die bevorzugte Variante (Variante 1) die Installation über das bereitgestellte .deb-Paket.
Die Variante 2 setzt voraus, dass im FHEM contrib Verzeichnis (/opt/fhem/contrib) die aktuelle Version des .deb-Pakets liegt. Die Variante 3 ist dafür gedacht, wenn man keine .deb-Pakete installieren kann/will oder es aus anderen Gründen nicht funktioniert. Es wird davon abgeraten die Variante 3 zu verwenden. Vollständigkeitshalber wird sie aber aufgeführt.

===== Installation per .deb-Paket =====

Die bevorzugte Variante ist die Installation von lepresenced durch die passenden .deb Pakete.
{{Randnotiz|RNText=Bei einem Upgrade einer älteren Version reicht es, das neue .deb Paket mit
:<code>sudo dpkg -i lepresenced-X.XX-X.deb</code>
zu aktualisieren}}

'''1.Variante:'''
Herunterladen der aktuellen lepresenced-0.83-3.deb (Stand August 2017) Datei über den Webbrowser
[https://svn.fhem.de/trac/export/HEAD/trunk/fhem/contrib/PRESENCE/deb/ SVN-Repository]. Im SVN die passende Datei auswählen und in der folgende Webseite den Link unter:
<pre>
Download in other formats:
Original Format
</pre>
anklicken und die Datei herunterladen.
Die Datei kann jetzt auf den RPi kopiert und mit folgenden Befehlen ausgeführt werden (ggf. Berechtigungen anpassen).

Alternativ per wget Befehl direkt auf den RPi (aktuelle Versionsnummer beachten)
https://svn.fhem.de/trac/export/HEAD/trunk/fhem/contrib/PRESENCE/deb/lepresenced-0.83-3.deb

'''2.Variante:''' (zu Verwenden, wenn es Probleme bei Variante 1 gibt)
Herunterladen aus dem fhem contrib Verzeichnis:
Hierzu muss das contrib auf dem aktuellen Stand sein. Dazu wird die Installation von subversion (normal bereits vorhanden) benötigt.

sudo apt-get install subversion

Danach kann per
sudo svn checkout https://svn.fhem.de/fhem/trunk/fhem/contrib svnrepo

Das aktuelle Repository auf den Pi heruntergeladen werden. Danach sollte im gewählten Verzeichnis die eingecheckten Dateien verfügbar sein.
/opt/fhem/svnrepo/PRESENCE/deb

''' Installation der Variante 1 oder 2 '''

Egal welche Variante gewählt wurde, nun kann mit folgenden Befehlen das Paket installiert werden. Bitte Pfade ggf. anpassen.

'''Wichtig''': Das '''Paket''' hat eine ca. Größe von '''6,5Kb'''. Ab und an gibt es wohl Probleme mit der Installation, wodurch die Datei 11,5kb groß wird.
Diese Datei lässt sich nicht Installieren. In diesem Fall das Paket bitte mit der Variante 1 und dem Bereich "Download in other formats" herunterladen.

sudo dpkg -i lepresenced-0.83-3.deb

sudo apt-get -f install

Die Ausgabe der Installation sollte am Ende ein [ ok ] Starting lepresenced (via systemctl): lepresenced.service. ausgeben.

<pre>
Paketlisten werden gelesen... Fertig
Abhängigkeitsbaum wird aufgebaut.
Statusinformationen werden eingelesen.... Fertig
Abhängigkeiten werden korrigiert ... Fertig
Die folgenden zusätzlichen Pakete werden installiert:
bluez-hcidump
Die folgenden NEUEN Pakete werden installiert:
bluez-hcidump
0 aktualisiert, 1 neu installiert, 0 zu entfernen und 0 nicht aktualisiert.
1 nicht vollständig installiert oder entfernt.
Es müssen 157 kB an Archiven heruntergeladen werden.
Nach dieser Operation werden 490 kB Plattenplatz zusätzlich benutzt.
Möchten Sie fortfahren? [J/n]
Holen: 1 http://archive.raspberrypi.org/debian/ jessie/main bluez-hcidump armhf 5.23-2+rpi2 [157 kB]
Es wurden 157 kB in 0 s geholt (921 kB/s).
Vormals nicht ausgewähltes Paket bluez-hcidump wird gewählt.
(Lese Datenbank ... 42033 Dateien und Verzeichnisse sind derzeit installiert.)
Vorbereitung zum Entpacken von .../bluez-hcidump_5.23-2+rpi2_armhf.deb ...
Entpacken von bluez-hcidump (5.23-2+rpi2) ...
Trigger für man-db (2.7.0.2-5) werden verarbeitet ...
bluez-hcidump (5.23-2+rpi2) wird eingerichtet ...
lepresenced (0.82-1) wird eingerichtet ...
[ ok ] Starting lepresenced (via systemctl): lepresenced.service.
</pre>

'''3.Variante:'''

Bei dieser Variante wird das aktuellste lepresenced Skript aus github heruntergeladen. Das bedeutet, dass jegliche Konfiguration wie automatischer Start, Berechtigungen etc.
manuell konfiguriert werden muss. Diese Variante eignet sich nur für diejenigen, die keine .deb-Pakete installieren wollen/können oder die genau Wissen, was sie tun!
<pre>
https://github.com/mhop/fhem-mirror/blob/master/fhem/contrib/PRESENCE/lepresenced
</pre>

Zur "Installation" des Skripts folgendermaßen vorgehen:
Unter /fhem manuell den Ordner „script“ anlegen:
<pre>
mkdir script
</pre>
Datei lepresenced reinkopieren und ausführbar machen:
<pre>
sudo chmod +x /opt/fhem/script/lepresenced
sudo chgrp -cR dialout lepresenced
</pre>
Skript erstmalig starten:
<pre>
sudo ./lepresenced --loglevel LOG_EMERG -d
</pre>
Kommt beim Starten des Skript eine Fehlermeldung, müssen die Abhängigkeiten aufgelöst werden.
<pre>
Can't locate Net/Server/Daemonize.pm in @INC (@INC contains: /etc/perl /usr/local/lib/perl/5.14.2 /usr/local/share/perl/5.14.2 /usr/lib/perl5 /usr/share/perl5 / usr/lib/perl/5.14 /usr/share/perl/5.14 /usr/local/lib/site_perl .) at /opt/fhem/lepresenced line 17.
BEGIN failed--compilation aborted at /opt/fhem/lepresenced line 17.
</pre>
Um die Abhängigkeiten aufzulösen muss folgendes nachinstalliert werden und anschließend ein Reboot durchgeführt werden.
<pre>
sudo apt-get install libnet-server-*
</pre>

===== Einrichtung eines Bluetooth-Geräts über FHEM =====

Nach dem letzten Schritt sind alle Bedingungen für eine abschließende Konfiguration eines BT-Geräts in FHEM abgeschlossen worden.
Jetzt kann der zum Beispiel ein G-Tag dem FHEM-Server bekannt gemacht werden:
<pre>
-- Name Modul Modus MAC vom Gtag IP vom PI Port Abfragezeit in Sekunden
define MeinGtAG PRESENCE lan-bluetooth xx:xx:xx:xx:xx:xx 127.0.0.1:5333 120
</pre>

'''Wichtig ist den angegeben Port zu unterscheiden. Für presenced muss der Port 5111 genommen werden, für lepresenced der Port 5333.'''
Den absent und present Mode kann man einfach testen, in dem man den Gtag mit Alufolie einwickelt.

Diese Variante sollte eingesetzt werden, wenn nur ein Pi nach Bluetooth-Geräten sucht. Möchte man mehr als ein Gerät nutzen um zum Beispiel eine größere Fläche abzudecken so muss mit collectored gearbeitet werden.

=== Alle Räume gemeinsam ansprechen mittels collectord ===
Um zwei presenced- oder lepresenced Installationen zu verbinden wird der collectord Daemon von Markus Bloch benötigt. Dieser kennt alle presenced-Installationen im Netzwerk und führt eine koordinierte Suche nach den gewünschten Geräten durch. Sobald ein Gerät in einem Raum erkannt wurde, meldet der collectord den Status einschließlich der Angabe des Raumes, in dem das Gerät erkannt wurde.

[[Datei:Presence_Collectord_Uebersicht.jpg|200px|thumb|left|Schematische Darstellung Presence und Collectord, Danke an dtavb]]
Auf Basis folgender Skizze wird die Einrichtung und der Betrieb der Anwesenheitserkennung und Überwachung <p></p>
mit dem PRESENCE-Modul sowie dem Skript (.deb-Paket) lepresenced beschrieben. Zusätzlich wird für die Verbindung <p></p>
mehrere lepresenced Instanzen der collectord verwendet.<p></p>
Diese Skizze dient als Basis für alle genannten Konfigurationen innerhalb dieses Artikels.

==== Aufbau ====
; RPi1 (Hautpinstanz):
: FHEM Installation
: presence/lepresenced Installation
: collectord installation
: Sämtliche Bluetooth-Geräte in FHEM definiert
; RPi2 (Zweitsystem):
: FHEM installation
: presence/lepresenced Installation
: Sämtliche Bluetooth-Geräte in FHEM definiert

==== Installation per .deb-Paket ====
collectord wird heruntergeladen und installiert:
https://svn.fhem.de/trac/export/HEAD/trunk/fhem/contrib/PRESENCE/deb/collectord-1.7.deb (Stand Januar 2017)
<pre>
sudo dpkg -i collectord-1.7.deb
</pre>

Nach der Installation befindet sich im Verzeichnis: /etc/collectord.conf die Konfigurationsdatei für das collectord.

==== Konfiguration auf Shellebene ====
<pre>
sudo vi /etc/collectord.conf
</pre>

Diese Datei muss jetzt nach folgender Vorlage angepasst werden.
<pre>
# room definition
#[room-name] # name of the room
#address=192.168.0.10 # ip-address or hostname
#port=5111 # tcp port which should be used (5111 is default)
#presence_timeout=120 # timeout in seconds for each check when devices are present
#absence_timeout=20 # timeout in secondsfor each check when devices are absent

[RPi1] # Name (wird als Reading room bei den BT-Tags angezeigt) der presence Instanze
address=127.0.0.1 # Lokale Adresse RPi1 , da hier das Collectord später laufen soll!
port=5333 # Port der Presence Installation
presence_timeout=60 # Selbstgewaelte Pruefintervalle
absence_timeout=60 # Selbstgewaelte Pruefintervalle

[RPi2] # Name (wird als Reading room bei den BT-Tags angezeigt) der presence Instanze
address=192.168.178.127 # IP-Adresse der Instanz, wo nur das Presence laueft, also RPi2
port=5333 # Port der Presence Installation
presence_timeout=60 # Selbstgewaelte Pruefintervalle
absence_timeout=60 # Selbstgewaelte Pruefintervalle
</pre>

Hinweis:
* Es dürfen keine [Namen] mit Leerzeichen verwendet werden
* Der angegebene Port richtet sich danach, ob auf dem Pi presenced (Port 5111) oder lepresenced (Port 5333) nach dem Bluetooth-Gerät sucht

==== Konfiguration in FHEM ====
;RPi1
:define Gtag PRESENCE lan-bluetooth XX:XX:XX:XX:XX:XX 127.0.0.1:5222 60 Hinweis: (Der Port ist der, des Collectord!! Standard 5222)
;RPi2
:define Gtag PRESENCE lan-bluetooth XX:XX:XX:XX:XX:XX 192.168.178.127:5222 60 Hinweis: (Der Port ist der, des Collectord!! Standard 5222 - die IP-Adresse von die von RPi1)

Nach der Konfiguration kann der Daemon gestartet werden.
Sobald das Bluetoothgerät irgendwo in der Wohnung erkannt wurde, meldet der Collectord dies sofort
an FHEM und teilt den Raum mit in dem es erkannt worden ist. Diese Information wird im Reading "rooms" des jeweiligen BT-Gerätes dargestellt.

Zum testen sollte collectored einmalig manuell gestartet werden. Dies hat den Vorteil, dass man nochmal den Port des collectored prüfen kann, dieser steht in der Zeile <pre>created socket on 0.0.0.0 with port 5333</pre> und man sehen kann, ob der collectored richtig startet, oder Fehler auswirft. Gestartet wird mit folgendem Kommando:
<pre>
sudo /usr/bin/perl /usr/sbin/collectord -vv -c /etc/collectord.conf
</pre>
Die Ausgabe sieht wie folgt aus:
<pre>
2017-04-02 17:52:55 - =================================================
2017-04-02 17:52:55 - started with PID 15554
2017-04-02 17:52:55 - reading configuration file
2017-04-02 17:52:55 - no config errors found
2017-04-02 17:52:55 - forked with PID 15556
2017-04-02 17:52:56 - created socket on 0.0.0.0 with port 5333
2017-04-02 17:53:20 - new connection from 127.0.0.1:48656
2017-04-02 17:53:20 - created thread 1 for processing device 7C:2F:80:E1:14:31 in room RPi2 for peer 127.0.0.1 (UUID: d0beb79dd4771532eb5e207c7bf31788)
2017-04-02 17:53:20 - created thread 2 for processing device 7C:2F:80:E1:14:31 in room RPi1 for peer 127.0.0.1 (UUID: d0beb79dd4771532eb5e207c7bf31788)
2017-04-02 17:53:20 - new connection from 127.0.0.1:48662
2017-04-02 17:53:20 - new connection from 127.0.0.1:48664
2017-04-02 17:53:20 - created thread 3 for processing device 7C:2F:80:ED:BC:F7 in room RPi2 for peer 127.0.0.1 (UUID: 7495a112063d5db45e6335d3fe305e36)
2017-04-02 17:53:20 - created thread 4 for processing device 7C:2F:80:ED:BC:F7 in room RPi1 for peer 127.0.0.1 (UUID: 7495a112063d5db45e6335d3fe305e36)
2017-04-02 17:53:20 - created thread 5 for processing device 7C:2F:80:E1:2A:4D in room RPi2 for peer 127.0.0.1 (UUID: c228f8d4d33b06787f995c7903c02760)
2017-04-02 17:53:20 - created thread 6 for processing device 7C:2F:80:E1:2A:4D in room RPi1 for peer 127.0.0.1 (UUID: c228f8d4d33b06787f995c7903c02760)
2017-04-02 17:53:22 - new connection from 192.168.xxx.xxx:51638
2017-04-02 17:53:22 - created thread 7 for processing device 7C:2F:80:E1:14:31 in room RPi2 for peer 192.168.xxx.xxx (UUID: 5db7012e709d6dc2fcd8159fc0344e40)
2017-04-02 17:53:22 - created thread 8 for processing device 7C:2F:80:E1:14:31 in room RPi1 for peer 192.168.xxx.xxx (UUID: 5db7012e709d6dc2fcd8159fc0344e40)
2017-04-02 17:53:22 - new connection from 192.168.xxx.xxx:51640
2017-04-02 17:53:22 - created thread 9 for processing device 7C:2F:80:ED:BC:F7 in room RPi2 for peer 192.168.xxx.xxx (UUID: c4b4d7c654132cf88e8c1fec3a956d3d)
2017-04-02 17:53:23 - created thread 10 for processing device 7C:2F:80:ED:BC:F7 in room RPi1 for peer 192.168.xxx.xxx (UUID: c4b4d7c654132cf88e8c1fec3a956d3d)
2017-04-02 17:53:29 - new connection from 192.168.xxx.xxx:51642
2017-04-02 17:53:29 - created thread 11 for processing device 7C:2F:80:E1:2A:4D in room RPi2 for peer 192.168.xxx.xxx (UUID: ecd7081e5ae3a0d8e735c8750cb116a1)
2017-04-02 17:53:29 - created thread 12 for processing device 7C:2F:80:E1:2A:4D in room RPi1 for peer 192.168.xxx.xxx (UUID: ecd7081e5ae3a0d8e735c8750cb116a1)
</pre>

Wenn das Log wie oben abgebildet aussieht wurde alles richtig gemacht und unter dem Device in FHEM erscheint ein neues Reading "rooms" mit dem Wert der Erkannten PRESENCE Installation.

'''Verhalten presence timeout im zusammenhang mit dem Attribut "absenceThreshold" der PRESENCE Konfiguration in FHEM'''
<br>
In der collectord.conf sind presence_timeout und absence_timeout für den jeweiligen Raum konfiguriert.
Das bedeutet, sobald irgendein Gerät in diesem jeweiligen Raum anwesend/abwesend ist, wird das jeweilige Timeout an den verbundenen presenced/lepresenced geschickt um damit das Check-Interval entsprechend zu ändern.

In der PRESENCE-Definition kann man ebenfalls ein absence_timeout/presence_timeout setzen. Sobald sich der Zustand ändert,
wird auch das jeweilige Timeout an den collectord gesandt. Dies hat aber auf die Checks in den jeweiligen Räumen und damit der collectord.conf keinen Einfluss.
Der collectord schickt ein Statusupdate an PRESENCE nur, wenn das vorgegebene Timeout (von PRESENCE) erreicht ist und keine Statusänderung stattfand.
Sobald eine Änderung des Status erfolgt wird natürlich sofort der Status an PRESENCE geschickt.

Das Attribut absenceThreshold/presenceThreshold funktioniert nachwievor. Hier ist nur wichtig wie man die Timeouts sowohl in PRESENCE als auch collectord.conf setzt.

'''Das Reading "room" bei einer PRESENCE Definition und der Zusammenhang zu collectord'''
<br>
Wenn ein BT LE Empfänger in mehr als einem Raum detektiert wird, führt der aktuellste collectord (aus dem SVN) eine RSSI-Erkennung durch. Sofern alle Räume den Empfangspegel (RSSI) ermitteln können, wird der Raum mit dem besten Empfangspegel als Raum für das "room"-Reading ausgewählt. Der lepresenced in aktueller Version von PatrickR gibt immer den Empfangspegel aus.

==== Automatischer Start ====
Wenn das Collectord per .deb Paket installiert wurde, startet es automatisch bei einem Reboot mit.
Manuell Starten als Daemon mit:
<pre>
sudo /usr/bin/perl /usr/sbin/collectord -c /etc/collectord.conf -d -v -l /var/log/collectord.log
</pre>

== Batterieüberwachung ==

=== Batterieüberwachung mit dem Modul BleTagBattery ===
{{Infobox Modul
|ModPurpose=Anwesenheitserkennung
|ModType=h

|ModTechName=74_BleTagBattery
|ModOwner=mumpitzstuff
}}
Mit dem Modul BleTagBattery - können die Batteriestati aller BT-LE Devices gelesen werden.
Es wird das batteryLevel und battery angelegt welches als BT-LE Tags an einer PRESENCE-Installation registriert wurden.

Vorraussetzung und Installation:

Bluez und Gattool
sudo apt-get install bluez

Das Gattool ist in den Installationen von Bluez inbegriffen.

Hinzufügen des githup für das Modul
update add http://raw.githubusercontent.com/mumpitzstuff/fhem-BleTagBattery/master/controls_bletagbattery.txt
update all
restart fhem: shutdown restart
BT-LE tags muss an einer PRESENCE-Installation des type "lan-bluetooth" registriert sein.

Nach dem Neustart von FHEM kann das Modul definiert werden:
define a new device: define <name of device> BleTagBattery

Das Modul versucht in der Standardkonfiguration alle 6 Stunden die BT-LE Devices zu erreichen und das Reading batteryLevel und battery zu aktualisieren.
Das Update kann auch manuell mit dem folgenden Befehl erzwungen werden

set <name of device> statusRequest.

Weiter Informationen und Disskussionen können dem eigentlichen [https://forum.fhem.de/index.php?topic=68104.0 Forumsbeitrag] entnommen werden,

=== Batterieüberwachung (aktuell nur G-Tags) ===

Leider überträgt der G-Tag nach der Einrichtung als Device in FHEM kein Reading mit seinem aktuellen Batteriestatus.
Dem wurde mit Hilfe des Forum Abhilfe geschaffen.
Im Folgenden wird erläutert wie die Batterieüberwachung eingerichtet werden kann.

'''Voraussetzung:'''

bc - Basiscalculator [https://packages.debian.org/de/sid/bc Bc-Paket]
<pre> sudo apt-get install bc </pre>

Anlegen eines Shellskript auf dem Raspberry System.
Die Parameter <<MAC-Adresse>> und <<TagName>> müssen durch die Werte des auszulesenden G-Tags ersetzt werden.
<pre>
#!/bin/bash
stringZ=$(sudo gatttool -b 5C:2B:80:C1:14:41 --char-read --handle=0x001b)
stringZ=${stringZ:33:2}
stringZ=$(echo "$stringZ" | tr a-f A-F)
decimal=$(echo "ibase=16; $stringZ" | bc)
perl /opt/fhem/fhem.pl 7072 "setreading MeinGtag Batterie $decimal"
</pre>

Dem Device in FHEM (hier MeinGtag) ein userReading mit dem Namen '''Batterie''' hinzufügen.
Das Shellskript mit folgendem Befehl starten:
<pre>
./GtagBatterie.sh
</pre>
'''Wichtig ist hierbei,''' dass Skript mit "./" und nicht mit "sh" aufzurufen. Beim Aufruf mit "sh GtagBatterie.sh" produziert es einen Fehler
<pre>GtagBatterie.sh: 3: GtagBatterie.sh: Bad substitution </pre>

Das Reading wird auf den ausgelesenen Wert der Batterie gesetzt.

Hinweis: Es sollte für jeden G-Tag ein eigenes Skript abgelegt werden. Das Skript kann per crontab oder fhem Kommando (system) regelmäßig aufgerufen werden.

=== Batterieüberwachung (alle Devices vom Typ "MODE=lan-bluetooth") ===

Es gibt eine weitere Möglichkeit um den Batteriestatus von LE Devices abzurufen und in FHEM als Reading darzustellen.
Dabei wird der Batteriezustand für alle LE Devices, die bereits in FHEM konfiguriert sind und per lepresenced überwacht werden, automatisch in einem shell-Script ermittelt.
Näheres dazu im Forumartikel {{Link2Forum|Topic=56960|LinkText=Erweiterung: Anwesenheitserkennung/Batterieüberwachung}}.

Vorteile:
* Automatische Ermittlung aller in FHEM konfigurierten LE Devices
* Möglichkeit, diese Devices alternativ manuell im Script einzutragen
* Es werden nur Devices abgefragt, die im Status "present" sind, also mit ziemlicher Sicherheit auch verfügbar sind
* Ein eventuell auf dem FHEM telnet-Port gesetztes Passwort kann im Script hinterlegt werden

'''Voraussetzung:'''

'''Funktionierendes lepresenced''' - siehe [[Anwesenheitserkennung#Anleitung_f.C3.BCr_ein_LE_Device_.28z.B._Gtags.2CPebbles_etc..29|Anleitung für ein LE Device (z.B. Gtags,Pebbles etc.)]]

'''socat''' - TCP port forwarder
<pre>
sudo apt-get update && sudo apt-get install socat
</pre>

'''gawk''' - Zum extrahieren der Daten
<pre>
sudo apt-get update && sudo apt-get install gawk
</pre>

'''gatttool''' - Bestandteil von bluez

gatttool ist auf den meisten Distributionen im bluez-Paket, allerdings nicht bei Opensuse. Dort muss man das Sourcepaket von bluez installieren und selbst kompilieren.
gatttool sollte dann nach /usr/bin oder /usr/local/bin kopiert werden,

Zusätzlich zu den notwendigen Erweiterungen werden für die Ausführung von gatttool '''Root-Rechte benötigt'''!

Das Script selbst gibt es hier: [https://raw.githubusercontent.com/micky0867/lebattery/master/lebattery lebattery]

Am Besten unter /opt/fhem/script/lebattery speichern und ausführbar machen:
<syntaxhighlight lang="bash">
sudo su -
mkdir /opt/fhem/script
cd /opt/fhem/script
wget https://raw.githubusercontent.com/micky0867/lebattery/master/lebattery
chmod 755 lebattery
</syntaxhighlight>

Je nach Bedarf können im Script noch die folgenden 3 Parameter angepasst werden:
<syntaxhighlight lang="bash">
# If allowed_telnetPort is protected by a password, add the password here
TELNETPASSWORD=""
# Attribute for batterylevel in FHEM
ATTRIBUT="batterylevel"
# Use this, if you dont want the script to determine the tags on its own
LETAGS=""
</syntaxhighlight>

Das Skript wird dann unter root folgendermaßen gestartet:
<pre>
/opt/fhem/script/lebattery -v
</pre>

Ausgabe des Skripts, wenn es mit dem Verbose Parameter -v gestartet wird.

Beide Devices sind vom Typ NUT mini, das Device mit dem FHEM-Namen '''nut_Micky''' ist im Status '''absent'''. Das zweite Device ist im Status '''present'''.
<pre>
Determining address for nut_Micky ...
nut_Micky is in state absent, no further action required

Determining address for nut_Test ...
Fetching batterylevel for nut_Test (F3:44:04:81:54:89) ...
Setting batterylevel for nut_Test to 100%
</pre>

Mein crontab-Eintrag (User root) sieht so aus:
<pre>
3 3 * * * /opt/fhem/script/lebattery -v >/opt/fhem/script/lebattery.log 2>&1
</pre>
Damit wird jeden Morgen um 3 Minuten nach 3 Uhr der Zustand der Batterien aller Devices ermittelt und in FHEM abgespeichert.<br>
Bevor man das mit crontab macht, sollte man allerdings zunächst sicher stellen, dass es auch ohne crontab funktioniert....

Bei Problemen kann man auch erstmal schauen, ob das mit dem gattool überhaupt funktioniert:
<pre>
gatttool -t <Typ> -b <MAC-Adresse> --char-read --uuid 0x2a19

handle: 0x0017 value: 64
</pre>
In diesem Fall hat die Batterie noch 100% (hex 64).<br>
Der Typ ist abhängig vom Hersteller und kann public (G-Tags) bzw. random (Nut) sein. Im Zweifelsfall beides ausprobieren.

= Beispiele =
== Anwesenheitserkennung / Anwesenheitsbenachrichtigung mit G-Tags ==
Ein Skript zur Nutzung der Gigaset G-TAGs zur Alarmierung bei öffnen und schließen von Türen und zur Anwesenheitserkennung, um die Alarmierung zu aktivieren bzw. deaktivieren.
Es kann verwendet werden um die Anwesenheit von mehrern Personen im Haushalt zu erkennen. Dabei wird eingeschränkt, dass nur bestimmte Personen die Alarmierung aktivieren können ( Eltern/Kind -Beziehung ).
Des Weiteren werden im Beispiel die Eltern benachrichtigt wenn eins der Kinder das Haus verlässt und die Eltern nicht anwesend sind.

{{Randnotiz|RNText=Namen der G-Tags in den Skripten bitte anpassen!}}

Für die ''Notify'' und die ''RESIDENTS-Erweiterung'' wird ein Dummy benötigt.
<pre>
define Alarm dummy
attr Alarm devStateIcon aktiv:secur_locked@red inaktiv:secur_open@lightgreen
attr Alarm eventMap on:aktiv off:inaktiv
attr Alarm setList on off
attr Alarm webCmd aktiv:inaktiv
attr Alarm room Alarm
</pre>

=== Mit Notify ===
<pre>
gtag.*.presence:.* {Anwesenheit_check("$EVTPART1", "$NAME")}
</pre>

Code für die 99_myUtils.pm
<pre>
### GTAG ANWESENHEITS CHECK
sub Anwesenheit_check($$) {
my ($EVENT, $NAME) = @_;

# gtag_rot - Alias Marco
# gtag_schwarz - Alias Ulli
# gtag_gruen - Alias Frida
# gtag_orange - Alias Hannah

my $RESIDENT = "rr_"; # Alle GTAGs sind Standardmäßig Residents Roommate
# $RESIDENT = "rg_" if (($NAME eq "gtag_orange") xor ($NAME eq "gtag_weis")); # Hier nur Gäste (Roomguest) Auskommentiert, da ich es so nicht brauche
my $ROOMMATE = ("$RESIDENT" . "$NAME"); # Residentsname zusammenbauen
my $ALIASNAME = AttrVal($ROOMMATE,'alias',$ROOMMATE); # ALIAS des Roommates auslesen

my $GTAG1 = Value('gtag_rot'); # ELTERN
my $GTAG2 = Value('gtag_schwarz'); # ELTERN

my $STATUS = "wahrscheinlich gerade los";
$STATUS = "anwesend" if ($EVENT eq "present"); # Status: anwesend
$STATUS = "unterwegs" if ($EVENT eq "absent"); # Status: unterwegs

Log 1, "$ALIASNAME ist $STATUS."; # LOG Eintrag erzeugen

if (($EVENT eq "present" && Value("Alarm") eq "aktiv") && ($NAME eq "gtag_gruen" xor $NAME eq "gtag_orange")) {
fhem("set teleBot send ALARMIERUNG BLEIBT AKTIV: $ALIASNAME ist da..."); # Telegram
# fhem("set Infopush msg 'ALARMIERUNG BLEIBT AKTIV' '$ALIASNAME ist da...'"); # Pushover
}
elsif (($EVENT eq "present" && Value("Alarm") eq "aktiv") && ($NAME eq "gtag_rot" xor $NAME eq "gtag_schwarz")) {
fhem("set teleBot send ALARMIERUNG INAKTIV: $ALIASNAME ist da...; set Alarm inaktiv"); # Telegram
# fhem("set Infopush msg 'ALARMIERUNG INAKTIV' '$ALIASNAME ist da...'; set Alarm inaktiv"); # Pushover
}
elsif (($EVENT eq "absent" && Value("Alarm") eq "aktiv") && ($NAME eq "gtag_gruen" xor $NAME eq "gtag_orange")) {
fhem("set teleBot send ALARMIERUNG BLEIBT AKTIV: $ALIASNAME hat das Haus verlassen."); # Telegram
# fhem("set Infopush msg 'ALARMIERUNG BLEIBT AKTIV' '$ALIASNAME hat das Haus verlassen.'"); # Pushover
}
elsif (($EVENT eq "absent" && Value("Alarm") eq "inaktiv") && ($GTAG1 eq "absent" && $GTAG2 eq "absent")) {
fhem("set Alarm aktiv; set teleBot send ALARMIERUNG AKTIV: $ALIASNAME hat das Haus verlassen."); # Telegram
# fhem("set Alarm aktiv; set Infopush msg 'ALARMIERUNG AKTIV' '$ALIASNAME hat das Haus verlassen.' '' 0 ''"); # Pushover
}
}
</pre>

<br>

=== Mit Notify und Integration des RESIDENTS-MODUL ===

Der hier beschriebene Code erweitert die Funktionen unter dem Punkt 5.93.
Das Notify muss daher mit der folgenden Zeile erweitert werden.

<pre>
define Alarm_AnwesenheitCheck notify gtag.*.presence:.* { Anwesenheit_check("$EVTPART1", "$NAME"), Anwesenheit_check_resi("$NAME") }
</pre>

Zusätzlicher Code für die 99_myUtils.pm um die RESIDENTS Funktion nutzen zu können:
<pre>
### RESIDENTS
sub Anwesenheit_check_resi($) {
my ($NAME) = @_;
my $ALIASNAME = AttrVal($NAME,'alias',$NAME); # ALIASNAME des GTAGs auslesen

my $RESIDENT = "rr_"; # Als Standard sind alle GTAGs Roommates
$RESIDENT = "rg_" if (($NAME eq "gtag_orange") xor ($NAME eq "gtag_weis")); # Hier nur GTAG Namen der Gäste (Roomguest)
my $ROOMMATE = ("$RESIDENT" . "$ALIASNAME"); # Residentsname zusammenbauen

if (ReadingsVal($NAME,'presence',$NAME) eq "absent") {
fhem("set $ROOMMATE absent"); # Resisents Status von Roommates setzen
}
elsif(ReadingsVal($NAME,'presence',$NAME) eq "present") {
fhem("set $ROOMMATE home"); # Resisents Status von Roommates setzen
}
}
</pre>
<br>

=== Mit Notify und Fenster/Tür. -Kontakt Überwachung ===

Erweiterung für die Überwachung von Fenster/Tür. -Kontakten. Dazu sind zwei weitere Notifys notwendig die auf die Trigger der Kontakte regagieren
und so eine weitere Funktion in der 99_myUtils.pm ansprechen. Die Notifys triggern auf Kontakte die mit dem Namen Kontakt* beginnen.
Sollten die eigenen Fenster/Tür. -Kontakt anderen Namen besitzen, müssen die Skripte dementsprechend angepasst werden.
<pre>
define Alarm_Kontaktmeldung notify Kontakt.*:contact:.* {Kontakt_Meldung("$EVTPART1", "$NAME")}
</pre>
<pre>
define Alarm_Sabotagealarm notify Kontakt.*.sabotageError:.on {Kontakt_Sabotage("$EVTPART1", "$NAME")}
</pre>

Zusätzlicher Code für die 99_myUtils.pm um die TÜRKONTAKTE-Meldung nutzen zu können:
<pre>
### TÜRKONTAKTE-Meldung/Zustand
sub Kontakt_Meldung($$) {
my ($EVENT, $NAME) = @_;
my $ALIASNAME = AttrVal($NAME,'alias',$NAME);
Log 1, "$ALIASNAME wurde $EVENT";
if (ReadingsVal("Alarm", "state", "on") eq "on") {
fhem("set teleBot send $ALIASNAME wurde $EVENT"); # Nachricht über Telegram
# fhem("set Infopush msg '$ALIASNAME' '$ALIASNAME wurde $EVENT'"); # Nachricht über Pushover
}
}

### TÜRKONTAKTE-Sabotagealarm

sub Kontakt_Sabotage($$) {
my ($EVENT, $NAME) = @_;
my $ALIASNAME = AttrVal($NAME,'alias',$NAME);
Log 1, "$ALIASNAME meldet Sabotagealarm";
fhem("set teleBot send Alarm: $ALIASNAME meldet Sabotagealarm"); # Nachricht über Telegram
# fhem("set Infopush msg 'Alarmanlage' '$ALIASNAME meldet Sabotagealarm' '' 2 ' ' 60 600 "); # Nachricht über Pushover
}
</pre>
<br>

=== Hinweis zur Benutzung / Fehlerhandling ===

Der Alarm dummy hat den Zustand on:off. Die Bezeichnungen und Namen müssen 1:1 übernommen werden damit das Script funktioniert.
Andernfalls müssen die Bezeichnungen für z.B. absent:unterwegs und present:anwesend - angepasst werden.
Die Benachrichtigung kann aktuell per ''Telegram'' sowie ''Pushover'' ('''Achtung mit zweiterem sind Abokosten verbunden!''') realisiert werden.
Diskussion zum Thema im Forum unter: {{Link2Forum|Topic=64080}}
<br>

= Problemlösungen =
Falls es '''Probleme beim Starten des Skripts''' gibt bzw. man das Skript ohne Reboot des Systems neustarten möchte, kann man dies per kill Befehl erledigen.
<syntaxhighlight lang="bash">
ps -ef | grep lepresenced
sudo kill <pid>
</syntaxhighlight>

Debuglevel lepresenced setzen:
{{Randnotiz|RNText=Um Debug-Meldungen zu bekommen (Vorsicht bei SD-Karten-Systemen wie dem RPi) - Hierbei werden die Schreibzyklen auf die SD-Karte erhöht.}}

Der Log Level muss im lepresenced-Skript selbst verändert werden. Um den Log-Level auf INFO/WARNING/DEBUG zu setzen, dass Skript lepresenced mit einem Editor öffnen und die Stellen, wo LOG_WARNING zu finden sind durch den nötigen LOG-Eintrag ersetzen.

<pre>
lepresenced --loglevel LOG_DEBUG
</pre>
Nur das wichtigste Loggen:
<pre>
lepresenced --loglevel LOG_WARNING
</pre>
Keinerlei LOG-Einträge
<pre>
lepresenced --loglevel LOG_EMERG
</pre>

Bei '''Problemen mit der Batterieüberwachung''' der Tags kann die Pi Firmeware mit folgenden Befehl auf eine ältere Version zurückgesetzt werden.
Fehlermeldung beim Aufruf des lebattery oder anderen Batterietestskripten:
<pre>connect: Connection refused (111)</pre>

Lösung (vorübergehend)
<pre>
sudo rpi-update 8521fd34c8f66b6d109acce943f6e25ec93ec005
</pre>

Mehr dazu unter: {{Link2Forum|Topic=56960|Message=589165}}

'''Das BT-Device ist ständig "absent"'''<br>
Eine Mögliche Lösung kann sein, dass Paket bluez-hcidump zu installieren. Das Werkzeug hcidump erlaubt die Beobachtung von Bluetooth-Aktivität.
Dies ist nicht notwendig, wenn bereits bluez installiert ist, da dies Teil des bluez Paketes ist
<pre>
sudo apt-get install bluez-hcidump
</pre>

'''Fehler in Logdateien /var/log/syslog und /var/log/kernel'''
Jul 29 15:08:11 raspberrypi kernel: [ 4905.634211] bt_err_ratelimited: 1 callbacks suppressed
Jul 29 15:08:11 raspberrypi kernel: [ 4905.634231] Bluetooth: hci0 advertising data length corrected
Jul 29 15:08:12 raspberrypi kernel: [ 4906.647350] Bluetooth: hci0 advertising data length corrected
Jul 29 15:08:13 raspberrypi kernel: [ 4907.532081] Bluetooth: hci0 advertising data length corrected
Jul 29 15:08:13 raspberrypi kernel: [ 4907.655564] Bluetooth: hci0 advertising data length corrected

Die Ursache des Problems ist noch nicht ergründet, allerdings betrifft dies aktuell nur den RPi3. Die Fehlermeldungen werden in verschiedene log's geschrieben. Darunter maßgeblich "syslog" und "kern.log".

Lösung (vorübergehend)
Unterbinden der Einträge durch Anlage eines blocklist Eintrag:

1. Unter "/etc/rsyslog.d" eine Datei erzeugen mit dem Namen "01-blocklist.conf"
2. Inhalt: (Die Ausdrücke in den "" sind diejenigen, die aus dem log verschwinden sollen. - bei mir waren es die unten stehenden")
:msg,contains,"Bluetooth: hci0 advertising data length corrected" stop
:msg,contains,"bt_err_ratelimited:" stop
3. Dienst neu starten "sudo service rsyslog restart"

Weiter Infos werden im offiziellen Thema {{Link2Forum|Topic=28753|Message=499184|LinkText=hier}} diskutiert.

Seit Version 0.82 kann es beim Start zu folgenden Meldungen im Log kommen.
Sep 06 16:13:45 raspberrypi systemd[1]: Started lepresenced.
Sep 06 16:13:45 raspberrypi lepresenced[16010]: [tid:1] main::bluetooth_scan_thread: Received 'Set scan parameters failed: Input/output error', ...tting...
Sep 06 16:13:46 raspberrypi lepresenced[16010]: [tid:1] main::bluetooth_scan_thread: hcitool exited, retrying...

Diese Meldungen können ignoriert werden. Abhilfe schafft sich lepresenced selbst indem es sich resettet.

'''Moderne iPhones und Android Geräte wechseln zum "deep standby" Modus''', und werden dann als "abwesend" gemeldet.
Mittels einer Funktion, die via hping3 Packete an den Geräte senden, um die "wach" zu halten, und dann die MacAdresse ausliest, kann man dieses Problem umgehen. Mehr im Forum [https://forum.fhem.de/index.php/topic,76342.0.html]

= Versionsänderungen lepresenced =
<pre>
--Version 0.81 (BasisVersion)
--Version 0.82 (stable 08/2017)
-Neue Kommandozeilenoption "--debug": Startet lepresenced im Vordergrund und gibt ausführliche Debug-Informationen auf STDOUT aus.
-Sanity Check: lepresenced prüft beim Starten die Verfügbarkeit von hciconfig, hcitool und hcidump.
-Model: lepresenced übermittelt das Reading model nun als lan-lepresenced. Das erlaubt die Erkennung von lepresenced in der FHEM-Statistik (sofern aktiviert).
--Version 0.83 (stable 09/2017)
- Behebung von Systemstart Fehlern
- Weitere Debug-Möglichkeiten. U. a. wird nun mitgezählt, ob hcitool lescan ("legacy") und hcidump eine identische Zahl an Beacons empfangen
</pre>

= Ansprechpartner =
# {{Link2FU|117|markusbloch }} (Markus) für das PRESENCE-Modul und collectord
# {{Link2FU|5068|PatrikR}} (Patrick) für lepresenced
# [[Benutzer Diskussion:Devender|Devender]] ({{Link2FU|20043|Dirk}}) für Wiki und Doku

MsgDialog

2017-10-27T14:25:55Z

Kaihs: /* msgDialog und ROOMATE */

{{Infobox Modul
|ModPurpose=Dialoge für Sofortnachrichten über TelegramBot, Jabber und WhatsApp
|ModType=d
|ModForumArea=Frontends
|ModTechName=76_msgDialog.pm
|ModOwner={{Link2FU|4106|igami}}
}}

== Zielsetzung ==
Eine zentrale Anforderung einer modernen Haus-Automation ist die Steuerung von unterwegs. Mittlerweile nutzt fast jeder einen oder mehrere Messenger Dienste. Da liegt es doch nahe, diese Messenger Dienste für die Kommunikation mit FHEM zu nutzen.
Mit msgDialog ist es jetzt möglich, Dialoge für Sofortnachrichten über [[TelegramBot]], [[Jabber]] und [[yowsup]] (WhatsApp) zu definieren. Dabei können die einzelnen Dialoge für unterschiedliche Nutzer berechtigt werden.
Die grundlegende Bedienung wird in diesem '''[https://youtu.be/yiCOTeR1YVQ Video]''' am Beispiel von TelegramBot gezeigt.

== Einbindung in FHEM ==

=== Voraussetzungen ===
Für dieses Modul wird das Perl JSON Modul benötigt. Auf einem Debian-basierten System (z.B RaspberryPI o.ä.) kann man das mit dem folgenden Befehl installieren:
<pre>
sudo apt-get install libjson-perl
</pre>

=== Hinweise ===

*Telegram: Es kann notwendig sein, dass im TelegramBot das Attribut "utf8specials" auf "1" gesetzt werden muss. Damit werden Nachrichten mit Umlauten korrekt gesendet. Beim msg-Befehl kann der TelegramBot_MTYPE angegeben werden. Die Vorgabe ist "message". Durch den Wert "queryInline" lässt sich ein inline Keyboard erzeugen (siehe unten).

*Jabber: Beim msg Befehl kann der Jabber_MTYPE angegeben werden. Die Vorgabe ist leer. Durch den Wert "otr" lässt sich eine OTR-Nachricht versenden.

*WhatsApp (yowsup): Bisher konnten noch keine Erfahrungen gemacht werden.

=== msgDialog und ROOMMATE ===

Für jeden Dialog kann festgelegt werden, welche Person(en) dazu berechtigt ist. Dazu sind Geräte vom Typ ROOMMATE oder GUEST mit definiertem msgContactPush Attribut erforderlich. Es ist darauf zu achten, dass das Reading "fhemMsgRcvPush" ein Event erzeugt.

=== Definition des msgConfig-Device ===

Als nächstes benötigt man ein definiertes msgConfig device:

<pre>
defmod myMsgConfig msgConfig
attr myMsgConfig msgDialog_evalSpecials me=<Aktivierungswort bzw. -Nachricht>
TelegramBot=<Name des TelegramBot-device>
attr myMsgConfig msgContactPush TelegramBot
attr myMsgConfig room msg
</pre>

Falls bereits vorhanden müssen, natürlich nur die fehlenden Attribute gesetzt werden.

=== Definition des metaDialogs ===

Zur Auflistung aller berechtigten Dialoge dient - was sonst - ein Dialog!

<pre>
defmod meta_Dialog msgDialog {\
"%me%": {\
"match": "\/?(start|%me%)",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"{return('(' . join(') (', sort(split('\n', fhem('get TYPE=msgDialog:FILTER=NAME!=$SELF:FILTER=allowed=.*($recipient|everyone).* trigger')))) . ') ')}",\
"(abbrechen) ",\
"Ich kann folgendes für dich tun:"\
]\
},\
"abbrechen": {\
"match": "\/?abbrechen",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"(%me%) ",\
"Dialog abgebrochen."\
] \
},\
"beenden": {\
"match": "\/?beenden",\
"commands": [\
"deletereading TYPE=msgDialog $recipient_history",\
"deletereading %TelegramBot% $recipient_sentMsgId"\
],\
"message": [\
"(%me%) ",\
"Dialog beendet."\
]\
}\
}

attr meta_Dialog DbLogExclude .*
attr meta_Dialog allowed everyone
attr meta_Dialog room msg
</pre>

=== Definition beliebiger Dialoge ===

Aufgrund der Komplexität eines Dialogs mit JSON ist es am praktikabelsten, zunächst einen leeren Dialog zu definieren:
<pre>
define <name> msgDialog {}
</pre>

Anschließend kann die DEF in der Detail-Ansicht des Dialog-Device bearbeitet werden. Jeder Dialog basiert auf der folgenden Struktur von einfach bis komplex.

<pre>
{
"<TRIGGER>": {
"match": "<regex>",
"setOnly": (true|false),
"commands": "(fhem command|{perl code})",
"message": [
"{perl code}",
"text"
],
"<NEXT TRIGGER 1>": {
...
},
"<NEXT TRIGGER 2>": {
...
}
}
}
</pre>

Um den JSON-Teil der Dialoge zu testen, empfiehlt sich ein Besuch auf https://jsonlint.com/
Hier kann der selbst geschriebene JSON-Code validiert werden.

*TRIGGER: Kann ein beliebiger Text sein. Es wird geprüft ob die eingehende Nachricht damit übereinstimmt. Falls ja, wird der Dialog an dieser Stelle fortgesetzt.

*match: Wenn nicht nur genau eine Nachricht zugelassen werden soll, kann noch eine regex angegeben werden. Die regex muss auf die gesamte eingehnde Nachricht zutreffen.

*setOnly: Kann optional auf true oder false gestellt werden. In beiden fällen wird der TRIGGER dann nicht bei "get <name> trigger" zurück gegeben.
Wenn setOnly auf "true" gestellt wird, kann der Dialog an dieser Stelle nicht durch eingehende Nachrichten ausgelöst werden, sondern nur über "get <name> say TRIGGER". Dies kann dazu genutzt werden um einen Dialog aus FHEM heraus zu initiieren.

*commands: Kann einen einzelnen oder mehrere Befehle enthalten:
<pre>
"commands":
"single command"
"commands": [
"command 1",
"command 2",
"{perl command}"
]
</pre>

*message: Kann einen einzelnen oder mehrere Textte enthalten die mit einen Zeilenumbruch verbunden werden:
<pre>
"message": "text"
</pre>
<pre>
"message": [
"text 1",
"text 2",
"{return from perl command}"
]
</pre>

Bei mehrstufigen Dialogen wird diese Struktur ineinander verschachtelt angegeben.
Es werden Variablen und Platzhalter, welche unter dem Attribut evalSpecials definiert werden, ausgewertet.
=== Variablen ===
*$SELF: Eigenname des msgDialog
*$message: eingegangene Nachricht
*$recipient: Name des Dialogpartners

=== set ===
*reset: Setzt den Dialog für alle Benutzer zurück.
*say [@<recipient1>[,<recipient2>,...]] <TRIGGER>[|<NEXT TRIGGER>|...]: Der Dialog wird für alle angegeben Empänger an der angegeben Stelle fortgeführt. Sind keine Empfänger angegeben wird der Dialog für alle unter dem Attribut allowed angegebenen Empfänger fortgeführt.
*updateAllowed: Aktualisiert die Auswahl für das Attribut allowed.

=== get ===
*trigger: Listet alle TRIGGER der ersten Ebene auf bei denen nicht setOnly angegeben ist.

=== ATTRIBUTE ===
*allowed: Liste mit allen RESIDENTS und ROOMMATE die für diesen Dialog berechtigt sind.
*disable: [0|1] Dialog ist aktiviert|deaktiviert.
*disabledForIntervals: HH:MM-HH:MM HH:MM-HH-MM ...
*evalSpecials: key1=value1 key2=value2 ...Leerzeichen getrennte Liste von Name=Wert Paaren. Wert kann Leerzeichen enthalten, falls es in "" oder {} eingeschlossen ist. Wert wird als perl-Ausdruck ausgewertet, falls es in {} eingeschlossen ist. In der DEF werden %Name% Zeichenketten durch den zugehörigen Wert ersetzt. Dieses Attribut ist als "msgDialog_evalSpecials" im msgConfig Gerät vorhanden. Wenn der selbe Name im msgConfig und msgDialog definiert wurde, wird der Wert aus msgDialog verwendet.
*msgCommand <command>: Befehl der zum Versenden einer Nachricht verwendet wird. Die Vorgabe ist "msg push \@$recipients $message" Dieses Attribut ist als "msgDialog_msgCommand" im msgConfig Gerät vorhanden.

=== READINGS ===
*$recipient_history: Durch | getrennte Liste von TRIGGER um den aktuellen Zustand des Dialogs zu sichern. Für jeden Dialogpartner wird ein Reading angelegt. Wenn der Dialog beendet ist wird das Reading zurückgesetzt.

== Beispiele ==

==== Programmierung der Waschmaschine ====
Das ist ein Beispiel zur Programmierung einer Waschmaschine wie auch oben im Video zu sehen:
<pre>
defmod Waschmaschine_Dialog msgDialog { "Waschmaschine": {\
"message": [\
"{return('(Zeitprogramm stoppen) ') if(ReadingsVal('%controlUnit%', 'controlMode', '') eq 'auto')}",\
"{return('(programmieren) ') if(ReadingsVal('%actor%', 'state', '') ne 'on')}",\
"{return('(einschalten) ') if(ReadingsVal('%actor%', 'state', '') ne 'on')}",\
"(Verlaufsdiagramm) ",\
"(abbrechen) ",\
"{return('Waschmaschine: ' . (ReadingsVal('%actor%', 'state', '') eq 'on' ? 'eingeschaltet' : 'ausgeschaltet'))}",\
"{return('Modus: ' . (ReadingsVal('%controlUnit%', 'controlMode', '') eq 'auto' ? 'Automatik' : 'Manuell (' . ReadingsVal('%controlUnit%', 'time', '') . ')'))}"\
],\
"Zeitprogramm stoppen": {\
"commands": "set %controlUnit% controlMode manual",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Das Zeitprogramm wurde gestoppt."\
]\
},\
"programmieren": {\
"message": [\
"(bestätigen|zurück|abbrechen) ",\
"( 00:00 | 00:15 | 00:30 | 00:45 ) ",\
"( 01:00 | 01:15 | 01:30 | 01:45 ) ",\
"( 02:00 | 02:15 | 02:30 | 02:45 ) ",\
"( 03:00 | 03:15 | 03:30 | 03:45 ) ",\
"( 04:00 | 04:15 | 04:30 | 04:45 ) ",\
"( 05:00 | 05:15 | 05:30 | 05:45 ) ",\
"( 06:00 | 06:15 | 06:30 | 06:45 ) ",\
"( 07:00 | 07:15 | 07:30 | 07:45 ) ",\
"( 08:00 | 08:15 | 08:30 | 08:45 ) ",\
"( 09:00 | 09:15 | 09:30 | 09:45 ) ",\
"( 10:00 | 10:15 | 10:30 | 10:45 ) ",\
"( 11:00 | 11:15 | 11:30 | 11:45 ) ",\
"( 12:00 | 12:15 | 12:30 | 12:45 ) ",\
"( 13:00 | 13:15 | 13:30 | 13:45 ) ",\
"( 14:00 | 14:15 | 14:30 | 14:45 ) ",\
"( 15:00 | 15:15 | 15:30 | 15:45 ) ",\
"( 16:00 | 16:15 | 16:30 | 16:45 ) ",\
"( 17:00 | 17:15 | 17:30 | 17:45 ) ",\
"( 18:00 | 18:15 | 18:30 | 18:45 ) ",\
"( 19:00 | 19:15 | 19:30 | 19:45 ) ",\
"( 20:00 | 20:15 | 20:30 | 20:45 ) ",\
"( 21:00 | 21:15 | 21:30 | 21:45 ) ",\
"( 22:00 | 22:15 | 22:30 | 22:45 ) ",\
"( 23:00 | 23:15 | 23:30 | 23:45 ) ",\
"Wann soll die Wäsche fertig sein?",\
"Bitte Uhrzeit in HH:MM angeben.",\
"Aktuell ist [%controlUnit%:time] Uhr eingestellt."\
],\
"Uhrzeit": {\
"match": " ?([0-1][0-9]|2[0-3]):[0-5][0-9] ?",\
"commands": [\
"set %controlUnit% time $message",\
"set $SELF say @$recipient Waschmaschine|programmieren|bestätigen"\
]\
},\
"bestätigen": {\
"commands": "set %controlUnit% controlMode auto",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Das Zeitprogramm wurde eingestellt.",\
"Die Wäsche wird voraussichtlich um [%controlUnit%:time] Uhr fertig sein.",\
"Bitte die Waschmaschine vorbereiten."\
]\
}\
},\
"einschalten": {\
"commands": [\
"set %controlUnit% controlMode manual",\
"set %actor% on"\
]\
},\
"Verlaufsdiagramm": {\
"commands": "set %TelegramBot% cmdSend {plotAsPng('%plot%')}",\
"message": "TelegramBot_MTYPE=queryInline (%me%) $message"\
}\
},\
"auto": {\
"setOnly": true,\
"commands": [\
"set %actor% on",\
"set %controlUnit% controlMode manual"\
],\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine wurde automatisch eingeschaltet."\
]\
},\
"manual": {\
"setOnly": true,\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine wurde manuell eingeschaltet."\
]\
},\
"done": {\
"setOnly": true,\
"commands": "set %actor% off",\
"message": [\
"TelegramBot_MTYPE=queryInline (%me%) ",\
"Die Wachmaschine ist fertig."\
]\
}\
}
attr Waschmaschine_Dialog evalSpecials actor=HM_2C10D8_Sw\
controlUnit=Waschkeller_washer_controlUnit\
plot=Waschkeller_washer_SVG
</pre>

== TelegramBot: Inline Keyboard verwenden==

In Telegram gibt es die Möglichkeit die Art des Keyboards zu ändern. Links das normale Keyboard, rechts das Inline Keyboard.

[[Datei:76msgDialog menu.png|Normales Keyboard]] [[Datei:76msgDialog menu inline.PNG|Inline Keyboard]]

In diesem '''[https://youtu.be/oRDy2918mVI Video]''' wird Telegram mit einem Inline Keyboard verwendet.

Um eine Nachricht bei Telegram zu verändern, gibt es den Befehl "queryEditInline".
Dafür wird die MsgId von der Nachricht benötigt. Das erledigt ein notify, welches die msgId pro Peer abspeichert:

<pre>
defmod sentMsgIdByPeerId notify .+:sentMsgId.+ {\
return unless($TYPE eq "TelegramBot");;\
\
my $dev_hash = $defs{$NAME};;\
my $sentMsgId = ReadingsVal($NAME, "sentMsgId", "");;\
my $sentMsgPeerId = ReadingsVal($NAME, "sentMsgPeerId", "");;\
my ($contact) = devspec2array("TYPE=(ROOMMATE|GUEST):FILTER=msgContactPush=.*$sentMsgPeerId.*");;\
\
readingsSingleUpdate($dev_hash, "$contact\_sentMsgId", $sentMsgId, 1);;\
}
attr sentMsgIdByPeerId devStateIcon {ReadingsVal($name, "state", "inactive") eq "active" ? ".*:ios-on-blue:inactive" : ".*:ios-off:active"}
attr sentMsgIdByPeerId icon audio_mic
attr sentMsgIdByPeerId room msg
</pre>

Danach wird der Message-Befehl von
<pre>
set <TelegramBot> message
</pre>
auf
<pre>
set <TelegramBot> queryEditInline
</pre>
geändert. Dafür wird ein [[cmdalias]] verwendet:

<pre>
defmod message2queryEditInline cmdalias set .+ message (.|\n)+ AS {\
my ($NAME, $cmd, $message) = split(/[\s]+/, $EVENT, 3);;\
my $TYPE = InternalVal($NAME, "TYPE", "");;\
(my $recipient, $message) = ($message =~ m/(@\S+)? (.+)/s);;\
\
if($TYPE eq "TelegramBot" && $recipient){\
my ($contact) = devspec2array("TYPE=(ROOMMATE|GUEST):FILTER=msgContactPush=.*$recipient.*");;\
my $sentMsgId = ReadingsVal($NAME, "$contact\_sentMsgId", "");;\
\
if($sentMsgId ne ""){\
fhem("set $NAME queryEditInline $sentMsgId $recipient $message");;\
}\
else{\
fhem("set $NAME queryInline $recipient $message");;\
}\
}\
else{\
fhem("set $EVENT");;\
}\
}
attr message2queryEditInline room msg
</pre>

Um wieder zurück zum normalen Keyboard zu gelangen genügt es, das notify und den cmdAlias zu deaktivieren.
Das kann komfortabel über ein notify und einen dummy erledigt werden:
<pre>
defmod inline_normal.NOT notify inline_normal.DUM:.* {\
if ("$EVENT" =~ "on") {\
fhem "set sentMsgIdByPeerId active;; attr message2queryEditInline disable 0";;\
} \
elsif ("$EVENT" =~ "off") {\
fhem "set sentMsgIdByPeerId inactive;; attr message2queryEditInline disable 1";;\
}\
}
</pre>

Weitere Infos zum Thema Inline Keyboard sind in der Antwort #10 im Forum zu finden (siehe Link unten).

== Links ==
* Thread über das Modul im {{Link2Forum|Topic=77297|LinkText=FHEM Forum}}

[[Kategorie:Gerätemodul]]

AndFHEM

2017-10-12T19:19:46Z

Kaihs: URL korrigiert

[[File:AndFHEM_logo.png|48px|right]]

andFHEM is a native Android [[:Kategorie:FHEM Frontends|frontend]] for FHEM.

Since May/13, 2012 the free andFHEM version contains advertisements. There is a (billed) premium version available now.

[[File:AndFHEM_screenshot-1324896614334.png|192px]]

[[File:AndroidMarket_logo.png|291px|right]]

For more information see [https://play.google.com/store/apps/details?id=li.klass.fhem Play Store] "andFHEM" or here:

* [http://andfhem.klass.li/index.html Homepage]
** [http://andfhem.klass.li/changelog/ Changelog]
** [http://andfhem.klass.li/faq.html FAQ]

== Features ==
* Show devices in rooms
* Create your own favorite devices list
* Switch and dim FS20 devices
* Create plots for CUL_WS, HMS, KS300, OREGON devices
* Delete, move and rename devices

== Supported Devices ==
* AT
* CUL_EM
* CUL_FHTTK
* CUL_HM
* CUL_TX
* CUL_WS
* DUMMY
* EIB
* EN_OCEAN
* FHT
* Floorplan
* FS20
* HCS
* HMS
* HOL
* Intertechno
* KS300
* LGTV
* MAX
* Oregon
* Owcount
* OWFS
* Owtemp
* Owtherm
* PID
* RFXCOM
* RFXX10REC
* SIS_PMS
* Structure
* TRX
* TRX_LIGHT
* TRX_WEATHER
* Twilight
* USBWX
* Watchdog
* Weather
* WOL
* ...

[[Kategorie:Glossary]]
[[Kategorie:FHEM Frontends]]

MySensors Starter Guide

2017-03-20T20:39:26Z

Kaihs: Aufrufreihenfolge korrigiert

{{Hinweis|Dieser Artikel ist im Aufbau und soll Einsteigern und Fortgeschrittenen als Referenzquelle für typische Fragen dienen. Alle sind eingeladen hier weitere Möglichkeiten einzubringen. Die beste Referenz für alle Fragen zu MySensors ist und bleibt aber die offizielle Hompage des Projekts!}}

== Einführung ==
[http://www.mysensors.org MySensors] ist ein open-Source-Projekt. Der Schwerpunkt liegt auf selbstgemachten Funk-Sensoren für die Hausautomatisierung und das "Internet der Dinge" in einer Art Baukastensystem. Die Bauanleitungen des Projekts für die einzelnen Musterbausteine sind in der Regel einfach nachzubauen, die Hard- und Softwarebauteile lassen sich dabei auch (fast beliebig) kombinieren.

=== Nodes und Children===
==== Nodes ====
Die Kombination von einem Microcontroller und einem Funkchip wird jeweils als "Node" bezeichnet.
Ein MySensors-Netzwerk besteht also (in der Regel) aus mindestens zwei Nodes, nämlich einer Gateway-Node und einer Sensor-Node. Jede Node ist durch eine sog. NodeID innerhalb des Netzwerks eindeutig identifizierbar, wobei die "0" jeweils für das Gateway reserviert ist.
Als Microcontroller werden in der Regel Arduinos (Nano oder Micro) verwendet, für das GW häufiger auch [[ESP8266]]. Als Funkchips lassen sich derzeit Module mit nRF24L01+ und RFM69 verwenden, die allerdings jeweils eine eigene Funktechnik verwendet und daher innerhalb eines Netzwerks nicht gemischt werden können. Es kann auch ein kabelgebundenes Netzwerk auf Basis von RS485-Modulen aufgebaut werden; hierfür werden 2 Adern als Datenleitung benötigt.
==== Children ====
Als Child wird alles bezeichnet, was jeweils innerhalb einer Node unterschieden werden soll. Beispiel: An einer Node wird ein BME280 angeschlossen. Dies ist ein I2C-Sensor, der drei Werte liefert, nämlich Temperatur, Luftfeuchtigkeit und Luftdruck. Jeder dieser Meßgrößen erhält üblicherweise eine eigene ChildID zugewiesen.

=== Softwarestand ===
{{Randnotiz|RNTyp=g|RNText=Der Verfasser hat in der Vergangenheit festgestellt, dass die bei MySensors beteiligten Entwickler eventuelle Verbesserungen und Fehlerkorrekturen nicht mehr in die "stable"-Version rückportieren. Bei Problemen empfiehlt es sich daher, die jeweilige beta-Version zu testen. Hierzu muß aber in der Regel auch das verwendete Gateway auf diese Version upgedated werden.}}
Bei Abfassung dieses Artikels war
*1.8.0 der Stand der verwendeten Arduino-IDE
*2.1.1 die stable-Version von MySensors.
*2.2.0-beta der aktuelle Development-Zweig von Mysensors

=== Vor- und Nachteile von MySensors ===
==== Vorteile ====
*Preisgünstig
*Modular, Elemente können (fast) beliebig kombiniert werden
*Es kann ein sog. ACK verlangt werden. Damit läßt sich sicherstellen, dass eine Node einen Befehl auch tatsächlich erhalten hat (Bidirektionalität).
*Auf den Microcontrollern kann eine eigene Funktionalität unabhängig von der zentralen FHEM-Instanz vorgesehen werden (z.B. LED-Licht direkt bei Bewegung schalten). Die Nodes können seit 2.0.1-beta dabei auch ohne Verbindung zum Gateway die loop() ausführen, wenn eine entsprechende Option aktiviert ist.
*MQTT kann unterstützt werden.
*Es kann auch eine kabelgebundene Infrastruktur aufgebaut werden (RS485, zwei Adern).

==== Nachteile ====
*Standardmäßig wird ein nicht verschüsselter Funkstandard verwendet, so dass von der Verwendung in sicherheitsrelevanten Funktionen (Türschließer usw.) abzuraten ist.

==== Zum Start ====
Für erste Tests sind sinnvoll:
{{Randnotiz|RNTyp=g|RNText=1. Für Sensbender-Boards sind spezielle [https://raw.githubusercontent.com/mysensors/ArduinoBoards/master/package_mysensors.org_index.json Board-Definitionen] für die IDE verfügbar. Nach den [https://github.com/mysensors/MySensors/releases Release Notes] sind diese ab der Version 2.0.0 zu empfehlen, die Installation erfolgt über File -> Preferencies -> Additional Boards Manager URLs
2. Manche neueren Boarddefinitionen aus der IDE führen u.U. zu häufigeren Reboots. Seit 1.6.18 scheint das Problem behoben zu sein, ansonsten ist ein Downgrade der Boarddefinitionen für AVR-Boards bis <=1.6.11 zu empfehlen.}}
*eine Arduino mit USB-Anschluß (Nano) oder ein ESP8266
*ein weiterer Arduino Nano
*zwei nRF24L01+ (alternativ: zwei RFM69)
*Die Arduino-IDE
*die gewünschte Sensorik, also z.B. einen DS18B20+Widerstand, ein Bewegungsmelder-Modul, ... siehe dazu die [https://www.mysensors.org/build Build-Anleitungen bei MySensors.org], wo auch Bezugsquellen zu finden sind.

== MySensors in FHEM ==
=== Allgemein ===
Die Nutzung von MySensors in FHEM ist (nicht nur für den Anfänger) mit der standardmäßig eingeschalteten [[autocreate|autocreate-Funktion]] einfach umsetzbar. Die Kenntnis der FHEM-Grundlagen und Durcharbeitung der Anfänger-Lektüren wird im Folgenden vorausgesetzt. Insbesondere sind [[Erste Schritte in FHEM]] und [http://fhem.de/Heimautomatisierung-mit-fhem.pdf Heimautomatisierung mit FHEM] Pflicht! Dort werden wesentliche Punkte für ein Verständnis von FHEM vermittelt, auch wenn manches nicht mehr ganz aktuell ist. So sollte man z.B. ein direktes Editieren der fhem.cfg unterlassen.

Im Folgenden werden immer wieder Auszüge aus der [[Konfiguration]] dargestellt. Diese dienen zur Erläuterung und Veranschaulichung. Die Bearbeitung der [[Konfiguration]] sollte - zur Verhinderung von Fehlern - nach Möglichkeit immer über das "[[Konfiguration#Befehl-Eingabefeld|Befehl-Eingabefeld]]" und die "[[Konfiguration#Objektdetails|Objektdetails]]" erfolgen.

=== Vorbereitung: Gateway ===
Zunächst ist das I/O-Device zu definieren, also das Gateway. Dies ist in [[MYSENSORS]] beschrieben.
{{Hinweis|Bei Verwendung eines seriellen Gateways ist zu empfehlen, einen Arduino mit orginalem FTDI-Chip zu verwenden und diesen mit der "by-id"-Methode ([[Trick_der_Woche#CUL_.26_CO_.C3.BCber_Serial_ID-einbinden]]) zuzuweisen. Beim Anschluß mehrer Arduinos mit einem CHG340/CHG341 an denselben Computer/Raspberry sind diese nur mit hohem {{Link2Forum|Topic=44926|Message=446809|LinkText=Aufwand}} eindeutig addressierbar.}}
{{Hinweis|Die Einbindung eines MySensors-Netzwerks kann auch über [http://fhem.de/commandref.html#MQTT MQTT] erfolgen. Dabei übernimmt ein MySensors-MQTT-Gateway die Kommunikation mit dem Broker. Der Autor hat hier jedoch keine eigene Erfahrung, bitte entsprechend nachtragen!}}

Serielles Gateway am Raspberry PI:
define MyGateway_0 MYSENSORS /dev/ttyUSB0@115200

Nach erfolgreicher Definition ist das Gateway im Raum "Everything" in der Gruppe "MYSENSORS" zu finden. Wenn unten "initialized" oder "opened" angezeigt wird, ist FHEM in der Lage, mit dem MySensors-Netz zu kommunizieren. Es sollte dann noch auf [[autocreate]] gestellt werden.

=== Das Gateway ist auch ein MySensors-Device ===
{{Hinweis|Sobald die ersten Meßwerte übertragen wurden, werden '''nach einem Browser-Refresh''' auch die aktuellen Meßwerte angezeigt, dies kann je nach Einstellung im Sketch aber einige Zeit dauern.}}
{{Randnotiz|RNTyp=g|RNText=Die Readings werden dem Modul MYSENSOR_DEVICE.pm entnommen. Sind diese dort nicht im Bereich "reads" bzw. "sends" enthalten, kann man fehlende Readings auch manuell anlegen. }}
Da am Gateway gleichzeitig auch bereits Sensoren angeschlossen sein können, legt FHEM direkt auch ein erstes [[MYSENSORS_DEVICE]] mit der NodeID "0" an. Sollten bereits ChildIDs im presentation()-Abschnitt des Gateway-Sketches enthalten gewesen sein, werden auch die zum Typ des präsentierten Sensor-Child-Typs passenden Readings automatisch angelegt.

=== Das erste Funk-MySensors-Device ===
In der Regel ist aber das erste "echte" MySensors-Device die 2. Node, die neben dem Gateway in Betrieb genommen wird. Hier gilt das Vorgesagte entsprechend: Nach dem ersten Start sind neu erkannte Devices ebenfalls im Raum "Everything" in der Gruppe "MYSENSORS" zu finden, die readings werden automatisch angelegt. Sobald Meßwerte übermittelt werden, werden die Readings damit gefüllt und entsprechend der per Sketch programmierten Vorgaben aktualisiert.

=== Details der Wechselwirkung zwischen FHEM und MySensors ===
==== Vergabe der NodeID ====
Die Vergabe der NodeID kann entweder im einzelnen Sketch erfolgen oder automatisiert. Dabei vergibt FHEM in der Regel fortlaufend Nummern ab 100. Die erste Node mit automatischer Nummernvergabe ist daher in der Regel das Device MYSENSORS_100.
{{Hinweis|Die NodeID wird - wie einige weitere Informationen - im sog. EEPROM des Arduinos abgespeichert. Ist sie einmal vergeben, ändert sie sich auch bei einem erneuten flashen der Node nicht mehr, es sei denn, man gibt per "define" im Sketch eine andere NodeID vor.}}

==== Fehlende Sensor-Typen und Readings ====
Für Anfänger ist zu empfehlen, nur Typen und Variablen zu nutzen, die in der 10_MYSENSORS_DEVICE.pm auch hinterlegt sind. Die Angaben dort zu "receives" und "sends" sind aus der Sicht der Node gemeint. Gibt es einzelne Sensor-Typen oder Readings (noch) nicht, gibt es folgende Möglichkeiten:
*Noch nicht vorhandene Typen kann man umgehen, indem man vergleichbare andere nimmt, also z.B. Wasser- statt Gaszähler (Stand: 11/2015)
*Fehlende Readings können auch
**in die 10_MYSENSORS_DEVICE.pm manuell eingepflegt werden, das automatische Anlegen geht dann aber ggf. bei einem Update wieder verloren
**manuell, z.B. <code>attr MYSENSOR_99 mapReading_ir_send3 3 ir_send</code>
Ist das Reading einmal angelegt, wird es auch automatisch befüllt, sobald die Node einen entsprechenden Wert sendet.

==== Austausch von Variablen oder Texten ====
Es ist möglich, Informationen auch bidirektional zwischen FHEM und den Nodes auszutauschen. Dies ermöglicht z.B. die Ansteuerung von Displays oder die Konfiguration von FHEM aus. Hierzu ist es am einfachsten, ein oder mehrere S_CUSTOM-Child zu präsentieren, die jeweils bis zu 5 Variablen ermöglichen. Die Zuordnung innerhalb der Node zu internen Variablen erfolgt dann über die Auswertung der Messages entsprechend der [https://forum.mysensors.org/topic/1817/weather-and-forecast-display-for-swedish-fhem-users/2 ChildID und der Variablennummer].

==== OTA ====
MySensors unterstützt für NRF-Chips zwar grundsätzlich OTA-updates, man muß dafür aber vorübergehend einen anderen Controller als FHEM einsetzen (Stand 11/2016).
Ein Howto ist in diesem {{Link2Forum|Topic=59388.0|LinkText=Forenbeitrag}} zu finden.
Der dort verwendete Bootloader erwartet OTA-Updates fest auf Channel 76.

== Links, Tricks, Kniffe und Erfahrungen ==

=== Interessante Links ===
==== Offizielles Debugging-Schema ====
*[https://forum.mysensors.org/topic/666/debug-faq-and-how-ask-for-help Debug / FAQ bei MySensors.org]

==== Vorgehensweise zur Kombination von mehreren Sketchen/Sensoren an einer Node ====
Mehrere Sensoren (Children) kann man recht einfach an einen einzigen Arduino anschließen und ist dabei nur durch die Größe des Speichers begrenzt. Die Vorgehensweise erläutert dieses [https://forum.mysensors.org/topic/2597/combining-mysensors-examples/2 Beispiel] .
==== Verschlüsselung und Signierung ====
*{{Link2Forum|Topic=67248|LinkText=Forumsbeitrag zu MySensors Verschlüsselung und Signierung}}
*[https://www.mysensors.org/about/signing Darstellung bei MySensors.org]

=== EEPROM ===
Die Nodes speichern einen Teil ihrer Einstellungen im sog. EEPROM. Dazu gehören z.B. die NodeID, der letzte bekannte "nächste" Punkt im Netzwert (RepeaterID) oder der Zustand von Relais. In der Regel ist nur die NodeID problematisch und kann beim flashen per Sketch auf einen anderen als den bisherigen Wert gestellt werden. Wer dennoch das EEPROM löschen möchte, muß den '''MySensor-Lösch-Sketch''' nehmen, der nicht "0000..." ins EEPROM schreibt wie der Arduino-Standard-Lösch-Sketch, sondern "FFFF...".

=== Funk-Themen (NRF-Chips) ===
Viele berichtete Probleme bei der Einrichtung von MySensors-Netzwerken haben ihren Ursprung in einer unzureichenden Funkverbindung. {{Hinweis|Ob dies der Fall ist, läßt sich leicht testen, indem man die fragliche Node wieder in die Nähe des Gateways bringt. Funktioniert es dort wie erwartet, liegt eine schlechte Funkverbindung vor.}}

==== Abhilfemaßnahmen ====
*Einen bzw. mehrere [https://www.mysensors.org/build/connect_radio#connecting_a_decoupling-capacitor Kondensatoren] einlöten. Es sind auch fertige Module erhältlich, die diese Bauteile und einen Spannungsregler bereits enthalten, auf die der NRF mit einem Stecksockel aufgesteckt wird.
*Einen anderen Kanal wählen; die verwendeten Frequenzen liegen im b/g-WLAN-Bereich, so dass wechselseitige Störungen möglich sind. In Deutschland sind die Kanäle bis 84 erlaubt.
*NRF tauschen (Fake NRF-Chips sind zwar verwendbar, haben aber eine deutlich reduzierte Funkreichweite)
*Ein allgemeiner Guide zur Verwendung der nrf24l01+-Module ist [https://arduino-info.wikispaces.com/Nrf24L01-2.4GHz-HowTo hier] zu finden.
*Für das Gateway empfielt es sich, ein Modul mit externer Antenne zu verwenden (NRF24L01+PA+LNA Antenna version).
*Einstellen des richtigen PA_LEVEL_...s: Insbesondere der Standardsketch für das serielle Gateway definiert diesen als LOW, was korrekt ist, wenn der interne Spannungsregler des Arduino verwendet ist. Besser ist es, die benötigten 3,3V mittels eines seperaten Spannungsreglers zu erzeugen und dann den PA_LEVEL_MAX einzustellen.
*Funkstrecken lassen sich recht unkompliziert mit Repeatern überbrücken. Dieser muß nicht zwingend eine eigene Node sein. Jede (sinnvollerweise nicht Batterie-gespeiste) Node kann per <code> #define MY_REPEATER_FEATURE </code> zum Repeater gemacht werden.
*Sonstige Vorschläge ohne Erfolgsgarantie, aber mit Unterhaltungswert:
**[http://www.instructables.com/id/Enhanced-NRF24L01/ Eigenbau-Antennenverbesserung]
**[http://blog.blackoise.de/2016/02/fixing-your-cheap-nrf24l01-palna-module/ Schirmung]

==== Buffer-Management ====
Die NRF-Chips haben nur einen begrenzten Speicher, um Nachrichten zu puffern. Dieser kann überlaufen, wenn in kurzer Folge Informationen versendet werden, z.B. mehr als 5 Temperaturwerte von 1-Wire-Sensoren. Diese Problematik verschärft sich bei der Verwendung von Message-Signing, weil dort die volle payload-Bandbreite für einzelne Nachrichten genutzt wird. Für Abhilfe sorgen kurze Pausen zwischen den einzelnen Sendungen, z.B. <code>wait(30);</code>.

=== RS485 ===
Seit 2.0.1 ist es möglich, statt der Funkmodule auch ein kabelgebundenes Netzwerk auf Basis von RS485-Modulen aufzubauen; hierfür werden 2 Adern als Datenleitung benötigt, die Zahl der Nodes in einem solchen Netzwerk ist bei Verwendung der Standardmodule auf 32 beschränkt, bei Verwendung anderer Transceiver sind auch mehr Nodes möglich. Hierfür ist ein seperates Gateway erforderlich.

==== Bekannte Probleme bei RS485 ====
(Stand: 2.1.1)

*Die Vergabe der Node-ID's muß im Sketch selbst erfolgen, die automatische Zuweisung funktioniert nicht.
*Die für die Anbindung der Module definierten PINs (8+9) sind tief im Code verankert und sollten nicht geändert werden.

=== Ablauf des Starts einer Node ===
Beim Start durchlaufen alle Nodes nacheinander bestimmte vordefinierte Programmroutinen in folgender Reihenfolge:

==== Vorversionen ====
*setup()
*presentation()
*loop()

==== seit MySensors 2.1.0 ====
*preHwInit()
*before()
*presentation()
*setup()
*loop()

==== Im Detail ====
Dieser Ablauf ermöglicht, die Arduino-Pins vorzukonfigurieren und angeschlossenes Equipment an der für den Programmablauf richtigen Stelle zu initialisieren. Dies ist u.U. wichtig, da
*eine Node im Normalfall nicht in loop() geht, solange die presentation() nicht erfolgreich war (also solange der Controller nicht verfügbar ist). Eine Failsafe-Initialisierung von Schnittstellen sollte demnach in preHwInit() oder before() erfolgen. Es kann zusätzlich seit 2.1.1 auch die Option MY_TRANSPORT_WAIT_READY_MS min. auf 1 gesetzt werden, dann startet die loop() auch ohne Verbindung zum Gateway.
*die Initialisierung anderer SPI-Hardware auf einem gemeinsamen Bus mit den NRF-Modulem vor der presentation() erfolgen muß.

=== Beispiel-Sketche ===
*[https://forum.mysensors.org/topic/938/multisensor-multiactuator-sketch-testboard-tested-with-fhem-controller Mehrfachsensor], allerdings noch für MySensors Vers. 1.5.4
*Bidirektionale {{Link2Forum|Topic=26807|msg=449776|LinkText="Infrarot-Fernbedienung"}} aus FHEM raus iVm. remotecontrol
*mehrere [https://github.com/rejoe2/MySensors-Dallas-Address-ChildID-Consistency Dallas-Temperatursensoren] auf einem Bus eindeutig erkennen
*[https://forum.mysensors.org/topic/1817/weather-and-forecast-display-for-swedish-fhem-users/2 Display] ansteuern

[[Kategorie:Arduino]]
[[Kategorie:IP Components]]
[[Kategorie:Other Components]]

DevelopmentModuleIntro

2017-02-16T20:05:00Z

Kaihs: Änderung 20027 von Kaihs (Diskussion) rückgängig gemacht.

{{Hinweis|Dieser Text ist in Arbeit und muss noch an einigen Stellen ergänzt werden. }}

== Einleitung ==

Um neue Geräte, Dienste, o.ä. in FHEM verfügbar zu machen, kann man ein eigenes Modul in Perl schreiben. Ein Modul wird in FHEM automatisch geladen, wenn ein entsprechendes Device in FHEM definiert wird. Das Modul ermöglicht eine spezifische Kommunikation mit einem physikalischen Gerät, stellt Ergebnisse ("Readings") und Events innerhalb von FHEM zur Verfügung und erlaubt es, das Gerät mit "Set"-/"Get"-Befehlen zu beeinflussen. Dieser Artikel soll den Einstieg in die Entwicklung eigener Module erleichtern.

Mit dem FHEM-Befehl <code>define</code> werden Devices in FHEM basierend auf einem Modul definiert. Dieser Befehl sorgt dafür, dass ein neues Modul bei Bedarf geladen und initialisiert wird. Ein gutes Beispiel ist hierbei die zentrale Konfigurationsdatei "fhem.cfg" in der sämtliche Devices in Form von <code>define</code>-Statements gespeichert sind.

Damit das funktioniert müssen der Name des Moduls und der Name der [[#X_Initialize|Initialisierungsfunktion]] identisch sein. Das folgende Beispiel soll dies verdeutlichen:

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

In fhem.pl wird der define-Befehl verarbeitet und geprüft, ob ein Modul mit dem Namen "JeeLink" schon geladen ist und falls nicht ein Modul mit Namen XY_JeeLink.pm im Modulverzeichnis (z.B. /opt/fhem/FHEM) gesucht und dann geladen.
Danach wird die Funktion <code>''JeeLink''_Initialize()</code> aufgerufen um das Modul in FHEM zu registrieren. Eine Moduldatei muss dazu eine Funktion <code>''<Modulname>''_Initialize()</code> enthalten. Durch den Aufruf dieser Funktion wird FHEM mitgeteilt, welche Funktionalitäten dieses Modul unterstützt.

In der Initialisierungsfunktion des Moduls werden die Namen aller weiteren Perl-Funktionen des Moduls, die von fhem.pl aus aufgerufen werden, bekannt gemacht. Dazu wird für jedes Modul ein eigener Hash (genauer "Modul-Hash") mit entsprechenden Werten gefüllt, der in fhem.pl für jedes Modul entsprechend abgelegt wird. Dadurch weiß FHEM wie dieses Modul anzusprechen ist.

== Grundlegender Aufbau eines Moduls ==

=== Dateiname ===

Ein FHEM-Modul wird als Perl-Modul mit der Dateiendung *.pm abgespeichert. Der Dateiname folgt dabei folgendem Schema:

:<code>''['''Schlüsselnummer''']''<font color="grey">_</font>''['''Modulname''']''<font color="grey">.pm</font></code>

* '''Schlüsselnummer''' - Eine zweistellige Zahl zwischen 00 - 99. Die Schlüsselnummer hat aktuell keine technische Relevanz mehr. In früheren FHEM-Versionen ist sie relevant für [[#Zweistufiges_Modell_f.C3.BCr_Module|zweistufige Module]] (Reihenfolge für [[DevelopmentModuleAPI#Dispatch|Dispatch()]] um logische Module zu prüfen). Die allgemeine Empfehlung ist hierbei eine Schlüsselnummer eines Moduls zu verwenden, welches eine ähnliche Funktionalität bietet. Die Schlüsselnummer 99 hat hierbei eine besondere Bedeutung, da alle Module mit dieser Schlüsselnummer beim Start von FHEM automatisch geladen werden, selbst, wenn sie in der Konfiguration nicht verwendet werden. Daher wird für myUtils 99 als Schlüsselnummer verwendet (99_myUtils.pm). Module mit der Schlüsselnummer 99 werden im SVN nicht akzeptiert (siehe [[SVN Nutzungsregeln]])
* '''Modulname''' - Der Name des Moduls wie er in FHEM bei dem Anlegen einer Gerätedefinition zu verwenden ist. Der Modulname sollte nur aus den folgenden möglichen Zeichen bestehen: Groß-/Kleinbuchstaben, Zahlen sowie Unterstrich (_)

=== Inhaltlicher Aufbau ===

Ein Modul ist inhaltlich in folgende Abschnitte unterteilt:

<source lang="perl">
#
# 72_MYMODULE.pm
#

package main;

# Laden evtl. abhängiger Perl- bzw. FHEM-Module
use HttpUtils;
use [...]

# FHEM Modulfunktionen

sub MYMODULE_Initialize() {
...
}

sub MYMODULE_Define() {
...
}

...

# Eval-Rückgabewert für erfolgreiches
# Laden des Moduls
1;

# Beginn der Commandref

=pod
=item [helper|device|command]
=item summary Kurzbeschreibung in Englisch was MYMODULE steuert/unterstützt
=item summary_DE Kurzbeschreibung in Deutsch was MYMODULE steuert/unterstützt

=begin html
Englische Commandref in HTML
=end html

=begin html_DE
Deustche Commandref in HTML
=end html

# Ende der Commandref
=cut
</source>

Man kann hierbei von folgender Reihenfolge sprechen:

# Perl-Code, welcher das Modul implementiert
# Die Zeile <code>1;</code> nachdem der Perl-Code abgeschlossen ist. Dies dient FHEM der Erkennung, dass das Modul erfolgreich und vollständig geladen wurde. Sollte diese Zeile nicht enthalten sein, wird FHEM beim Laden des Moduls die Fehlermeldung <code>Error:Modul 72_MYMODULE deactivated</code> in das Logfile schreiben.
# Commandref zur Dokumentation des Moduls. Diese Dokumentation soll dem User die möglichen Befehle/Attribute/Readings/Events vermitteln. Weitere Informationen und Hinweise findet man in den [[Guidelines zur Dokumentation]].

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

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

In fhem.pl werden alle Gerätedefinitionen in dem globalen Hash <code>%defs</code> abgelegt. Der Inhalt von <code>$defs{''<Name>''}</code> in fhem.pl verweist dabei auf den Hash der Geräteinstanz in Form einer Hashreferenz. Diesen Verweis (also nur die Adresse) bekommen die Funktionen eines Moduls übergeben (i.d.R. als <code>$hash</code> bezeichnet), welche direkt von fhem.pl aufgerufen werden. In dem Hash stehen beispielsweise die internen Werte des Geräts, die im Frontend als "Internals" angezeigt werden, sowie die Readings des Geräts.

Beispiele:
*<code>$hash->{NAME}</code> enthält den Namen der Geräteinstanz,
*<code>$hash->{TYPE}</code> enthält die Typbezeichnung des Geräts (Modulname)

==Ausführung von Modulen==
FHEM arbeitet intern nicht parallel, sondern arbeitet alle Aufgaben seriell nacheinander kontinuierlich ab. Daher wäre es ungünstig, wenn Module Daten von einem physikalischen Gerät abfragen wollen und dabei innerhalb der selben Funktion auf die Antwort des Geräts warten. In dieser Zeit, in der FHEM auf die Antwort des Gerätes warten muss, wäre der Rest von FHEM blockiert. Da immer nur eine Aufgabe zur selben Zeit bearbeitet wird, müssen alle weiteren Aufgaben solange warten. Eine Datenkommunikation innerhalb eines Moduls sollte daher immer ohne Blockierung erfolgen. Dadurch kann FHEM die Wartezeit effizient für andere Aufgaben nutzen um bspw. anstehende Daten für andere Module zu verarbeiten. Es gibt in FHEM entsprechende Mechanismen, welche eine "Non-Blocking"-Kommunikation über verschiedene Wege (z.B. seriell, HTTP, TCP, ...) ermöglichen.

Dafür werden in FHEM zwei zentrale Listen gepflegt, in der die Filedeskriptoren der geöffneten Kommunikatonsverbindungen gespeichert sind. Auf Linux- bzw. Unix-basierten Plattformen wird der select-Befehl des Betriebssystems verwendet um Filedeskriptoren auf lesbare Daten zu überprüfen. In FHEM gibt es dazu eine Liste (<code>%selectlist</code>), in der die Filedeskriptoren sämtlicher Geräte (z.B. serielle Verbindung, TCP-Verbindung, etc.) gespeichert sind.

In der zentralen Schleife (Main-Loop) von fhem.pl wird mit <code>select()</code> überwacht, ob über eine der geöffneten Schnittstellen Daten zum Lesen anstehen. Wenn dies der Fall ist, dann wird die Lesefunktion ([[#X_Read|X_Read]]) des zuständigen Moduls aufgerufen, damit es die Daten entgegennimmt und verarbeitet. Anschließend wird die Schleife weiter ausgeführt.

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

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

Auch wenn von einem Anwender über einen Get-Befehl Daten aktiv von einem Gerät angefordert werden, sollte nicht blockierend gewartet werden. Eine asynchrone Ausgabe, sobald das Ergebnis vorliegt, ist über [[DevelopmentModuleAPI#asyncOutput|asyncOutput()]] möglich. Siehe {{Link2Forum|Topic=43771|Message=357870|LinkText=Beschreibung}} und {{Link2Forum|Topic=43771|Message=360935|LinkText=Beispiel}}. Weitere Anwendungsbeispiele finden sich im {{Link2Forum|Topic=43052|Message=353477|LinkText=PLEX Modul}} und im überarbeiteten und nicht-blockierenden {{Link2Forum|Topic=42771|Message=348498|LinkText=SYSSTAT Modul}}.

== Wichtige globale Variablen aus fhem.pl ==

FHEM arbeitet mit einer Vielzahl an internen Variablen. Die nun folgenden aufgelisteten Variablen sind die wichtigsten, welche man im Rahmen der Modulprogrammierung kennen sollte:

{| class="wikitable"
|-
! Variable !! Beschreibung
|-
| <code>$init_done</code> || Dient der Erkennung für fhem.pl sowie den Modulen, ob FHEM den Initialisierungsvorgang abgeschlossen hat. Beim Starten von FHEM ist <code>$init_done</code> gleich <code>0</code>. Erst, wenn das Einlesen der Konfiguration, sowie des State-Files (Readings) abgeschlossen ist, wird <code>$init_done</code> auf <code>1</code> gesetzt.
Das gleiche Verfahren wird auch bei dem Befehl <code>rereadcfg</code> angewandt. Während <code>rereadcfg</code> ausgeführt wird (Konfiguration löschen, neu einlesen), ist <code>$init_done</code> gleich <code>0</code>.

Dies ist insbesondere in der [[#X_Define|Define]]-Funktion eines Moduls relevant.
|-
| <code>%attr</code> || In <code>%attr</code> werden sämtliche gesetzten Attribute aller Geräte gespeichert. Diese Datenstruktur wird generell durch den <code>attr</code>-Befehl verwaltet. Hierbei wird einem Gerätenamen eine Mehrzahl an Attributnamen mit einem Wert zugeordnet. Attribut-Inhalte können über die Funktion [[DevelopmentModuleAPI#AttrVal|AttrVal()]] ausgelesen werden.
|-
| <code>%cmds</code> || In <code>%cmds</code> wird jedem in FHEM existierendem Befehl die entsprechende Funktion zugewiesen, welche diesen Befehl umsetzt. Module können durch das Eintragen eines Befehlsnamen samt Funktion in <code>%cmds</code> über die [[#X_Initialize|Initialize]]-Funktion eines Moduls einen (oder mehrere) eigene Befehle in FHEM registrieren.

Die Struktur ist dabei wiefolgt:

$cmds{''<Befehlsname>''} = { Fn => "''<Funktionsname>''",
Hlp => "''<Aufrufsyntax>''"};

|-
| <code>%data</code>|| Der eigentliche Zweck von <code>%data</code> ist dem Nutzer eine Möglichkeit zum Speichern von temporären Daten im globalen Kontext zu ermöglichen. Einige Module verwenden <code>%data</code> jedoch auch um modul- & geräteübergreifend Daten auszutauschen.
|-
| <code>%defs</code>|| In <code>%defs</code> werden sämtliche Gerätedefinitionen, bzw. die Hash-Referenzen auf diese, gespeichert. Hier ist jedem Gerätenamen eine Hash-Referenz zugeordnet.
|-
| <code>%modules</code>|| In <code>%modules</code> sind alle geladenen Module gelistet mit ihren entsprechenden Initialisierungsdaten (Funktionsnamen, Attribut-Listen, spezielle Einstellungen, ...). Hier wird für jeden Modulname der Modul-Hash aus der [[#X_Initialize|Initialize]]-Funktion gespeichert.
Desweiteren legen viele Module, welche nach dem [[DevelopmentModuleIntro#Zweistufiges_Modell_f.C3.BCr_Module|zweistufigen Modulkonzept]] hier eine Rückwärtszuordnung von Geräteadressen zu Geräte-Hash an.
|-
| <code>%readyfnlist</code>|| In <code>%readyfnlist</code> sind alle zu prüfenden Verbindungen mit ihrer entsprechendem Geräte-Hash gelistet. FHEM prüft alle hier gelisteten Geräte regelmäßig über eine Aufruf der entsprechenden [[#X_Ready|Ready]]-Funktion.

Bei einer Nutzung von dem Hilfsmodul DevIo.pm zum Aufbau einer Kommunikationsverbindung, kümmert sich DevIo selbständig um den entsprechenden Eintrag in <code>%readyfnlist</code>.
|-
| <code>%selectlist</code>|| In <code>%selectlist</code> sind alle geöffneten Verbindungen mit ihrer entsprechendem Geräte-Hash gelistet. FHEM prüft alle hier gelisteten Geräte, ob der geöffnete Filedeskriptor unter <code>$hash->{FD}</code> Daten zum Lesen bereitgestellt hat. Ist dass der Fall, wird die entsprechende [[#X_Read|Read]]-Funktion aufgerufen, um anstehende Daten durch das Modul zu verarbeiten.
Bei einer Nutzung von dem Hilfsmodul DevIo.pm zum Aufbau einer Kommunikationsverbindung, kümmert sich DevIo selbständig um den entsprechenden Eintrag in <code>%selectlist</code>.
|}

Es gibt durchaus viele weitere globale Variablen, die jedoch für sehr spezielle Anwendungsfälle und z.T. nur einzelne Module gedacht sind und daher hier nicht aufgeführt werden.

== Internals ==
Daten, die ein Modul im Geräte-Hash speichert nennt man Internals. Sie werden als Unterstruktur des Hashes der jeweiligen Geräteinstanz gespeichert, beispielswiese <code>$hash->{NAME}</code> für den Gerätenamen, welcher beim Define-Befehl übergeben wurde und als Internal gespeichert wird. Diese Daten spielen für FHEM eine sehr wichtige Rolle, da sämtliche gerätespezifischen Daten als Internal im Gerätehash gespeichert werden.

Falls Werte wie z.B. ein Intervall nicht über den Define-Befehl gesetzt werden sollen und im Betrieb einfach änderbar sein sollten, ist eine alternative Möglichkeit die Speicherung in so genannten Attributen. Dann würde man den Define-Befehl so implementieren, dass er kein Intervall übergeben bekommt und statt dessen das Interval als Attribut über den Befehl <code>attr</code> gesetzt wird.

Generell werden alle Werte, welche direkt in der ersten Ebene von <code>$hash</code> (Gerätehash) gespeichert werden auf der Detail-Seite einer Definition in der FHEMWEB Oberfläche angezeigt. Es gibt jedoch Ausnahmen:

* <code>$hash->{helper}{URL]</code> - Alle Elemente, welche als Unterelement wieder einen Hash besitzen werden nicht in FHEMWEB dargestellt. Typischerweise speichern Module Daten unter <code>$hash->{helper}</code> interne Daten zwischen, die für den User nicht relevant sind, sondern nur der internen Verarbeitung dienen.
* <code>$hash->{'''.'''<font color="grey">ELEMENT</font>}</code> - Alle Knoten, welche mit einem Punkt beginnen werden in der FHEMWEB Oberfläche nicht angezeigt. Man kann diese Daten jedoch beim Aufruf des [[List|list-Kommandos]] einsehen.

Es gibt bereits vorbelegte Internals welche in FHEM dazu dienen definitionsbezogene Informationen wie bspw. Namen und Readings zu speichern. Dies sind im besonderen:

{| class="wikitable"
|-
! style="min-width: 13em;" | Internal !! Beschreibung
|-
| <code>$hash->{NAME}</code> || Der Definitionsname, mit dem das Gerät angelegt wurde.
|-
| <code>$hash->{READINGS}</code> || Enthält alle aktuell vorhandenen Readings. Daten unterhalb dieses Knotens sollte man nicht direkt manipulieren. Um Readings zu Erzeugen gibt es entsprechende [[DevelopmentModuleAPI#Readings_.2F_Events|Reading-Funktionen]].
|-
| <code>$hash->{NR}</code> || Die Positions-Nr. der Definition innerhalb der Konfiguration. Diese dient dazu die Konfiguration in der gleichen Reihenfolge zu speichern, wie die einzelnen Geräte angelegt wurden.
|-
| <code>$hash->{TYPE}</code> || Der Modulname, mit welchem die Definition angelegt wurde.
|-
| <code>$hash->{DEF}</code> || Sämtliche Argumente, welche beim <code>define</code>-Befehl nach dem Modulnamen übergeben wurden.
|-
| <code>$hash->{CFGFN}</code> || Der Dateiname der Konfigurationsdatei in der diese Definition enthalten ist (sofern nicht in fhem.cfg). Dieser Wert ist nur gefüllt, wenn man mit mehreren Konfigurationsdateien arbeitet, welche dann in fhem.cfg via include-Befehl eingebunden werden.
|-
| <code>$hash->{NTFY_ORDER}</code> || Sofern das Modul Events via [[DevelopmentModuleIntro#X_Notify|Notify-Funktion]] verarbeitet enthält jede Definition eine Notify-Order als Zeichenkette bestehend aus dem Notify Order Prefix und dem Definitionsnamen. Details zur Funktionsweise gibt es in der Beschreibung zur [[DevelopmentModuleIntro#X_Notify|Notify-Funktion]] im Abschnitt "Reihenfolge für den Aufruf der Notify-Funktion beeinflussen".
|-
| <code>$hash->{NOTIFYDEV}</code> || Sofern das Modul Events via NotifyFn verarbeitet kann man damit die Definitionen, von denen man Events erhalten will begrenzen. Details zur Funktionsweise gibt es in der Beschreibung zur [[DevelopmentModuleIntro#X_Notify|Notify-Funktion]] im Abschnitt "Begrenzung der Aufrufe auf bestimmte Geräte".
|-
| <code>$hash->{IODev}</code> || Hier wird das zugeordnete IO-Gerät durch [[DevelopmentModuleAPI#AssignIoPort|AssignIoPort()]] gespeichert, welches für den Datentransport und -empfang dieses logischen Gerätes zuständig ist. Dieser Wert existiert nur bei Modulen die nach dem [[DevelopmentModuleIntro#Zweistufiges_Modell_f.C3.BCr_Module|zweistufigen Modulkonzept]] arbeiten.
|-
| <code>$hash->{CHANGED}</code> || Hier werden alle Events kurzzeitig gesammelt, welche für die Eventverarbeitung anstehen. Insbesondere die [[DevelopmentModuleAPI#Readings_.2F_Events|Reading-Funktionen]] speichern hier alle Events zwischen um sie nach Abschluss via [[DevelopmentModuleAPI#DoTrigger|DoTrigger()]] zu verarbeiten.
|-
| <code>$hash->{FD}</code> || Wenn die Definition eine Netzwerkverbindung oder serielle Schnittstelle geöffnet hat (z.B. via DevIo), so wird der entsprechende File-Deskriptor in diesem Internal gespeichert. Damit kann FHEM alle geöffneten Filedeskriptoren der entsprechenden Definition zuordnen um bei ankommenden Daten die Definition via [[DevelopmentModuleIntro#X_Read|Read-Funktion]] damit zu versorgen.
|-
| <code>$hash->{EXCEPT_FD}</code> || Ähnlich wie <code>$hash->{FD}</code>. Sofern die Definition in <code>[[#Wichtige_globale_Variablen_aus_fhem.pl|%selectlist]]</code> eingetragen ist und ein Fildeskriptor in diesem Internal gesetzt ist, wird bei einer auftretenden Exception bzw. Interrupt die [[DevelopmentModuleIntro#X_Except|Except]]-Funktion des entsprechenden Moduls aufgerufen um darauf zu reagieren.
|}

Generell sollte man die meisten der hier genannten systemweiten Internals nicht modifizieren, da ansonsten die korrekte Funktionsweise von FHEM nicht mehr garantiert werden kann.

== Readings ==
Daten, welche von einem Gerät gelesen werden und in FHEM in einer für Menschen verständlichen Form zur Verfügung gestellt werden können, werden Readings genannt. Sie geben den Status des Gerätes wieder und erzeugen Events innerhalb von FHEM auf die andere Geräte reagieren können. Sie werden als Unterstruktur des Hashes der jeweiligen Geräteinstanz gespeichert, beispielsweise
*<code>$hash->{READINGS}{temperature}{VAL}</code> für die Temperatur eines Fühlers
*<code>$hash->{READINGS}{temperature}{TIME}</code> für den Zeitstempel der Messung

Für den lesenden Zugriff auf Readings steht die Funktion <code>[[DevelopmentModuleAPI#ReadingsVal|ReadingsVal()]]</code> zur Verfügung. Ein direkter Zugriff auf die Datenstruktur sollte nicht vorgenommen werden.

Readings werden im Statefile von FHEM automatisch auf der Festplatte zwischengespeichert, damit sie nach einem Neustart sofort wieder zur Verfügung stehen. Dadurch ist der letzte Status eines Gerätes vor einem Neustart nachvollziehbar.

Readings, die mit einem Punkt im Namen beginnen, haben eine funktionale Besonderheit. Sie werden im FHEMWEB nicht angezeigt und können somit als "Permanentspeicher" für kleinere Daten innerhalb des Moduls genutzt werden. Um größere Datenmengen permanent zu speichern sollte man jedoch die Funktion <code>[[DevelopmentModuleAPI#setKeyValue|setKeyValue()]]</code> verwenden.

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

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

<source lang="perl">
readingsBeginUpdate($hash);
readingsBulkUpdate($hash, $readingName1, $wert1 );
readingsBulkUpdate($hash, $readingName2, $wert2 );
readingsEndUpdate($hash, 1);
</source>

== Attribute ==
Damit der Nutzer das Verhalten einer einzelnen Gerätedefinition zur Laufzeit individuell anpassen kann, gibt es in FHEM für jede Definition sogenannte Attribute, welche mit dem Befehl <code>attr</code> gesetzt werden können.
Diese stehen dann dem Modul unmittelbar zur Verfügung um das Verhalten während der Ausführung zu beeinflussen. Attribute werden zusammen mit dem <code>define</code>-Befehl der jeweiligen Definition beim Speichern der aktuellen Konfiguration von FHEM in die Konfigurationsdatei geschrieben. Beim Neustart werden die entsprechenden Befehle ausgeführt um alle Definition inkl. Attribute wieder anzulegen. Zur Laufzeit werden Attribute in dem globalen Hash <code>%attr</code> mit dem Definitionsnamen als Index (<code>$attr{$name} = $value</code>) gespeichert. Ein Attribut mit dem Namen <code>header</code> würde beispielsweise mit <code>$attr{$name}{header}</code> adressiert. Generell sollte <code>%attr</code> nicht durch direkten Zugriff manipuliert/benutzt werden.

Zum Auslesen von Attributen sollte die Funktion [[DevelopmentModuleAPI#AttrVal|AttrVal()]] verwendet werden.

Welche Attribute ein Modul unterstützt muss in der Funktion <code>[[#X_Initialize|X_Initialize]]</code> durch Setzen von <code>$hash->{AttrList}</code> bekannt gemacht werden (siehe unten).

Wenn beim Setzen von Attributen in einer Gerätedefinition entsprechende Werte geprüft werden sollen oder zusätzliche Funktionalitäten implementiert werden müssen, dann muss dies in der Funktion <code>[[#X_Attr|X_Attr]]</code> (siehe unten) implementiert werden. Hier kann man bspw. einen Syntaxcheck für Attribut-Werte implementieren um ungültige Werte zurückzuweisen.

== Modulfunktionen ==

Damit fhem.pl ein Modul nutzen kann, muss dieses entsprechende Funktionen mit einer vorgegebenen Aufrufsyntax implementieren. Durch die Bekanntgabe dieser modulspezifischen Funktionen können Daten zwischen fhem.pl und einem Modul entsprechend ausgetauscht werden. Es gibt verschiedene Arten von Funktionen die ein Modul anbieten muss bzw. kann, je nach Funktionsumfang.

=== Die wichtigsten Funktionen in einem Modul ===

Folgende Funktion muss ein Modul mit dem beispielhaften Namen "X" mindestens bereitstellen:

{| class="wikitable"
|-
! style="text-align:left" | Funktionsname !! style="text-align:left" | Kurzbeschreibung
|-
| [[#X_Initialize|X_Initialize]] || Initialisiert das Modul und gibt den Namen zusätzlicher Modulfunktionen bekannt, sowie modulspezifische Einstellungen. Wird direkt nach dem erfolgreichen Laden des Moduls durch fhem.pl aufgerufen.
|}

Die folgenden Funktionen sind die wichtigsten Funktionen, welche je nach Anwendungsfall zu implementieren sind. Es handelt sich hierbei um die wichtigsten Vertreter, welche in den meisten Modulen Verwendung finden. Nicht alle Funktionen machen jedoch in jedem Modul Sinn. Generell sollte auch hier bei jeder Funktion der Modulname vorangestellt werden um ein einheitliches Namensschema zu gewährleisten. Hier die wichtigsten Modulfunktionen:

{| class="wikitable sortable"
|-
! style="text-align:left" | Funktionsname !! style="text-align:left" class="unsortable"| Kurzbeschreibung
|-
| [[#X_Define|X_Define]] || Wird im Rahmen des <code>define</code>-Befehls aufgerufen.
|-
| [[#X_Undef|X_Undef]] || Wird im Rahmen des <code>delete</code>-Befehls, sowie <code>rereadcfg</code>-Befehl aufgerufen. Dient zum Abbau von offenen Verbindungen, Timern, etc.
|-
| [[#X_Delete|X_Delete]] || Wird im Rahmen des beim <code>delete</code>-Befehls aufgerufen wenn das Gerät endgültig gelöscht wird um weiterführende Aktionen vor dem Löschen durchzuführen.
|-
| [[#X_Get|X_Get]] || Wird im Rahmen des <code>get</code>-Befehls aufgerufen um Daten vom Gerät abzufragen
|-
| [[#X_Set|X_Set]] || Wird im Rahmen des <code>set</code>-Befehls aufgerufen um Daten an das Gerät zu senden.
|-
| [[#X_Attr|X_Attr]] || Wird im Rahmen des <code>attr</code>-Befehls aufgerufen um Attributwerte zu prüfen)
|-
| [[#X_Read|X_Read]] || Wird durch FHEM aufgerufen, wenn ein gelisteter Filedeskriptor in <code>[[#Wichtige_globale_Variablen_aus_fhem.pl|%selectlist]]</code> Daten zum Lesen bereitstellt.
|-
| [[#X_Ready|X_Ready]] || Wird unter Windows durch FHEM aufgerufen um zyklisch einen seriellen Filedeskriptor auf lesbare Daten zu prüfen. Unter Linux dient diese Funktion dem Wiederaufbau verlorener Verbindungen.
|-
| [[#X_Notify|X_Notify]] || Verarbeitet Events von anderen Geräten innerhalb von FHEM
|-
| [[#X_Rename|X_Rename]] || Wird aufgerufen, wenn ein Gerät umbenannt wird.
|-
| [[#X_Shutdown|X_Shutdown]] || Wird beim Herunterfahren von FHEM ausgeführt.
|}

Diese Funktionen werden in diesem Abschnitt genauer beschrieben.

==== X_Initialize ====

<source lang="perl">
sub X_Initialize($)
{
my ($hash) = @_;
...
}
</source>

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

Dieser Hash muss nun von X_Initialize mit allen modulrelevanten Funktionsnamen gefüllt werden. Anschließend wird dieser Hash durch fhem.pl im globalen Hash <code>%modules</code> gespeichert. <code>$modules{ModulName}</code> wäre dabei der Hash für das Modul mit dem Namen <code>ModulName</code>. Es handelt sich also nicht um den oben beschriebenen Hash der Geräteinstanzen sondern einen Hash, der für jedes Modul existiert und modulspezifische Daten wie bspw. die implementierten Modulfunktionen enthält. Die Initialize-Funktion setzt diese Funktionsnamen, in den Hash des Moduls wie folgt:

<source lang="perl">
$hash->{DefFn} = "X_Define";
$hash->{UndefFn} = "X_Undef";
$hash->{DeleteFn} = "X_Delete";
$hash->{SetFn} = "X_Set";
$hash->{GetFn} = "X_Get";
$hash->{AttrFn} = "X_Attr";
$hash->{ReadFn} = "X_Read";
$hash->{ReadyFn} = "X_Ready";
$hash->{NotifyFn} = "X_Notify";
$hash->{RenameFn} = "X_Rename";
$hash->{ShutdownFn} = "X_Shutdown";
</source>

Um eine entsprechende Funktion in FHEM bekannt zu machen muss dazu der Funktionsname, wie er im Modul als <code>sub <''Funktionsname''>() { ... }</code> definiert ist, als Zeichenkette in <code>$hash</code> gesetzt werden. Dabei sollten die entsprechenden Funktionsnamen immer den Modulnamen (in diesem Beispiel <code>X</code>) als Präfix verwenden.
Auf diese Weise können sämtliche modulspezifisch implementierten Funktionen wie <code>X_Read</code>, <code>X_Parse</code> etc. durch Zuweisung an <code>$hash->{ReadFn}</code> bzw. <code>$hash->{ParseFn}</code> usw. bekannt gemacht werden.

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

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

Die Auflistung aller unterstützten modulspezifischen Attribute erfolgt in Form einer durch Leerzeichen getrennten Liste in <code>$hash->{AttrList}}</code>. Es gibt in FHEM globale Attribute, die in allen Gerätedefinitionen verfügbar sind und nur modulspezifische Attribute die jedes Modul via <code>$hash->{AttrList}</code> über die eigene Initialize-Funktion setzt. In fhem.pl werden dann die entsprechenden Attributwerte beim Aufruf eines <code>attr</code>-Befehls in die globale Datenstruktur <code>$attr{$name}</code>, z.B. <code>$attr{$name}{header}</code> für das Attribut <code>header</code> gespeichert. Falls im Modul weitere Aktionen oder Prüfungen beim Setzen eines Attributs nötig sind, dann kann wie im Beispiel oben die [[#X_Attr|Attr]]-Funktion implementiert und in der Initialize-Funktion bekannt gemacht werden.

Die Variable <code>$readingFnAttributes</code>, die im obigen Beispiel an die Liste der unterstützten Attribute angefügt wird, definiert Attributnamen, die dann zusätzlich gemacht werden, wenn das Modul zum Setzen von Readings die Funktionen <code>[[DevelopmentModuleAPI#readingsBeginUpdate|readingsBeginUpdate()]]</code>, <code>[[DevelopmentModuleAPI#readingsBulkUpdate|readingsBulkUpdate()]]</code>, <code>[[DevelopmentModuleAPI#readingsEndUpdate|readingsEndUpdate()]]</code> oder <code>[[DevelopmentModuleAPI#readingsSingleUpdate|readingsSingleUpdate()]]</code> verwendet. In diesen Funktionen werden Attribute wie <code>event-min-interval</code> oder auch <code>event-on-change-reading</code> ausgewertet. Für Details hierzu siehe commandref zu [http://fhem.de/commandref.html#readingFnAttributes readingFnAttributes].

<u>Nutzung von parseParams()</u>

Die Funktion <code> [[DevelopmentModuleAPI#parseParams|parseParams()]]</code> unterstützt Modulautoren beim Parsen von Übergabeparametern, welche bei <code>define</code>, <code>get</code> und <code>set</code> Kommandos an die entsprechenden Modulfunktionen übergeben werden. Dadurch lassen sich auf einfache Weise insbesondere komplexe Parameter (wie bspw. Perl-Ausdrücke) sehr einfach parsen.

Diese Zusatzfunktion kann man in der Initialize-Funktion einfach über folgenden Parameter für [[#X_Define|Define]]-, [[#X_Get|Get]]- und [[#X_Set|Set]]-Funktion modulweit aktivieren:
<source lang="perl">$hash->{parseParams} = 1;</source>
Sobald es gesetzt ist wird automatisch durch fhem.pl <code>[[DevelopmentModuleAPI#parseParams|parseParams()]]</code> aufgerufen und die an die [[#X_Define|Define]]-, [[#X_Get|Get]]- und [[#X_Set|Set]]-Funktion übergebenen Parameter ändern sich wie weiter unten in den jeweiligen Funktionen beschrieben.

==== X_Define ====
<source lang="perl">
sub X_Define($$)
{
my ( $hash, $def ) = @_;

...

return $error;
}
</source>

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

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

Als Übergabeparameter bekommt die Define-Funktion den Hash der Geräteinstanz sowie den die im <code>define</code>-Befehl übergebenen Parameter. Welche bzw. wie viele Parameter
akzeptiert werden und welcher Syntax diese entsprechen müssen ist Sache dieser Funktion. Im obigen Beispiel wird die Argumentzeile <code>$def</code> in ein Array aufgeteilt (durch Leerzeichen/Tabulator getrennt) und so können die vom Modul bzw. der Define-Funktion erwarteten Werte über das Array der Reihe nach verarbeitet werden:

<source lang="perl">
my $name = $a[0];
my $module = $a[1];
my $url = $a[2];
my $inter = 300;

if(int(@a) == 4) {
$inter = $a[3];
if ($inter < 5) {
return "interval too small, please use something > 5s, default is 300 seconds";
}
}
</source>

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

<source lang="perl">
$hash->{url} = $url;
$hash->{Interval} = $inter;
</source>

Sobald alle Parameter korrekt verarbeitet wurden, wird in der Regel die erste Verbindung zum Gerät aufgebaut. Je nach Art des Geräts kann das eine permanente Datenverbindung sein (z.B. serielle Schnittstelle oder TCP-Verbindung) oder das Starten eines regelmäßigen Timers, der zyklisch den Status z.B. via [[HttpUtils|HTTP]] ausliest.

Sollten im Rahmen der Define-Funktion Syntax-Probleme der Übergabeparameter festgestellt werden oder es kann bspw. keine Verbindung aufgebaut werden, so ist als Funktionsrückgabewert eine entsprechende Fehlermeldung zurückzugeben. Nur wenn alle Übergabeparameter akzeptiert werden, darf <code>undef</code> zurückgegeben werden. Sobald eine Define-Funktion eine Fehlermeldung zurückmeldet, wird der define-Befehl durch FHEM zurückgewiesen und der User erhält die Fehlermeldung, welche die Define-Funktion produziert hat, als Ausgabe zurück.

<u>Verfügbarkeit von Attributen</u>

Während die Define-Funktion ausgeführt wird, sollte man nicht davon ausgehen, dass alle vom Nutzer konfigurierten Attribute via [[DevelopmentModuleAPI#AttrVal|AttrVal()]] verfügbar sind. Attribute stehen in der Define-Funktion nur dann zur Verfügung, wenn FHEM sich nicht in der Initialisierungsphase befindet (globale Variable <code>$init_done</code> ist wahr; der Nutzer hat die Gerätedefinition modifiziert). Daher sollte man weiterführende Funktion, welche auf gesetzte Attribute angewiesen sind, nur dann in der Define-Funktion starten, wenn <code>$init_done</code> zutrifft.

Andernfalls sollte man den Aufruf in der Notify-Funktion durchführen sobald <code>global:INITIALIZED</code> bzw. <code>global:REREADCFG</code> getriggert wurde:

<source lang="perl">
sub X_Define($$)
{
my ( $hash, $def ) = @_;

...

$hash->{NOTIFYDEV} = "global";

X_FunctionWhoNeedsAttr($hash) if($init_done);
}

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

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

my $devName = $dev_hash->{NAME}; # Device that created the events
my $events = deviceEvents($dev_hash, 1);

if($devName eq "global" && grep(m/^INITIALIZED|REREADCFG$/, @{$events}))
{
X_FunctionWhoNeedsAttr($hash);
}
}
</source>

Dadurch wird die Modulfunktion X_FunctionWhoNeedsAttr() nach dem Start erst aufgerufen, wenn alle Attribute aus der Konfiguration geladen wurden.

<u>Nutzung von parseParams()</u>

Zum Aufteilen und Parsen von <code>$def</code> lässt sich die Funktion [[DevelopmentModuleAPI#parseParams|parseParams]] verwenden um die einzelnen Argumente einfach zu parsen. Wenn in X_Initialize <code>$hash->{parseParams} = 1;</code> gesetzt wurde dann wird parseParams automatisch aufgerufen und X_Define ändert sich wie folgt:
<source lang="perl">
sub X_Define($$$)
{
my ( $hash, $a, $h ) = @_;
...
</source>

Die genauen Möglichkeiten von parseParams sind in dem entsprechenden [[DevelopmentModuleAPI#parseParams|Artikel]] dokumentiert.

<u>Nutzung von DevIo</u>

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

Um DevIo mitzuteilen welche Verbindung genau zu öffnen ist, muss das Internal <code>$hash->{DeviceName} mit einer entsprechenden Syntax gefüllt sein (z.B. <code>"/dev/ttyUSB0@9600"</code>, <code>"192.168.2.105:3000"</code>, ...). Üblicherweise wird diese Information als Argument im <code>define</code>-Befehl vom Nutzer angegeben.

<source lang="perl">
my $ret = DevIo_OpenDev( $hash, 0, "X_DeviceInit" );
</source>

Die optionale Funktion <code>X_DevInit</code> wird zur weiteren Initialisierung der Verbindung von <code>DevIo_OpenDev</code> aufgerufen. Der zweite Übergabeparameter an <code>DevIo_OpenDev</code> (hier <code>0</code>) steht für reopen und wird benötigt, da die Funktion auch aufgerufen wird, wenn ein USB-Geräte beispielsweise im Betrieb aus- und wieder eingesteckt wird. In diesem Fall wird die Funktion mit <code>1</code> aufgerufen. Dies ist jedoch nur in der [[#X_Ready|X_Ready]]-Funktion notwendig. In der Define-Funktion wird immer <code>0</code> (erster Verbindungsversuch) angegen

==== X_Undef ====
<source lang="perl">
sub X_Undef ($$)
{
my ( $hash, $name ) = @_;

...

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

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

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

Sollten im Rahmen der Undef-Funktion Probleme festgestellt werden, die ein Löschen nicht zulassen, so ist als Funktionsrückgabewert eine entsprechende Fehlermeldung zurückzugeben. Nur wenn die Undef-Funktion erfolgreich durchgeführt wurde, darf <code>undef</code> zurückgegeben werden. Nur dann wird eine Gerätedefinition von FHEM auch tatsächlich gelöscht bzw. neu angelegt. Sollte die Undef-Funktion jedoch eine Fehlermeldung zurückgeben, wird der entsprechende Vorgang (<code>delete</code> bzw. <code>rereadcfg</code>) für dieses Gerät abgebrochen. Es bleibt dann unverändert in FHEM bestehen.

==== X_Delete ====
<source lang="perl">
sub X_Delete ($$)
{
my ( $hash, $name ) = @_;

...

return $error;
}
</source>

Die Delete-Funktion ist das Gegenstück zur Funktion [[#X_Define|X_Define]] und wird aufgerufen wenn ein Gerät mit dem Befehl <code>delete</code> gelöscht wird.

Wenn ein Gerät in FHEM gelöscht wird, wird zuerst die Funktion [[#X_Undef|X_Undef]] aufgerufen um offene Verbindungen zu schließen, anschließend wird die Funktion X_Delete aufgerufen. Diese dient eher zum Aufräumen von dauerhaften Daten, welche durch das Modul evtl. für dieses Gerät spezifisch erstellt worden sind. Es geht hier also eher darum, alle Spuren sowohl im laufenden FHEM-Prozess, als auch dauerhafte Daten bspw. im physikalischen Gerät zu löschen die mit dieser Gerätedefinition zu tun haben.

Dies kann z.B. folgendes sein:

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

Beispiel:
<source lang="perl">
sub X_Delete($$)
{
my ( $hash, $name ) = @_;

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

return undef;
}
</source>

Sollten im Rahmen der Delete-Funktion Probleme festgestellt werden, die ein Löschen nicht zulassen, so ist als Funktionsrückgabewert eine entsprechende Fehlermeldung zurückzugeben. Nur die Delete-Funktion erfolgreich durchgeführt wurde, darf <code>undef</code> zurückgegeben werden. Nur dann wird eine Gerätedefinition von FHEM auch tatsächlich gelöscht. Sollte die Delete-Funktion eine Fehlermeldung zurückgeben, wird der Löschvorgang abgebrochen und das Gerät bleibt weiter in FHEM bestehen.

==== X_Get ====
<source lang="perl">
sub X_Get ($$@)
{
my ( $hash, $name, $opt, @args ) = @_;

...

return $result;
}
</source>
Die Get-Funktion wird aufgerufen wenn der FHEM-Befehl <code>get</code> mit einem Gerät dieses Moduls ausgeführt wird. Mit <code>get</code> werden typischerweise Werte von einem Gerät abgefragt. In vielen Modulen wird auf diese Weise auch der Zugriff auf generierte Readings ermöglicht. Der Get-Funktion wird dabei der Geräte-Hash, der Gerätename, sowie die Aufrufparameter des get-Befehls übergeben. Als Rückgabewert wird das Ergebnis des entsprechenden Befehls in Form einer Zeichenkette zurückgegeben. Der Rückgabewert <code>undef</code> hat hierbei keine besondere Bedeutung und wird behandelt wie eine leere Zeichenkette <code>""</code>.

Beispiel:

<source lang="perl">
sub X_Get($$@)
{
my ( $hash, $name, $opt, @args ) = @_;

return "\"get $name\" needs at least one argument" unless(defined($opt)));

if($opt eq "status")
{
...
}
elsif($opt eq "powser")
{
...
}
...
else
{
return "Unknown argument $opt, choose one of status power [...]";
}
}
</source>

Wenn eine unbekannte Option an die Get-Funktion übergeben wird, so muss als Rückgabewert der Funktion eine bestimmte Syntax einhalten um FHEM mitzuteilen, welche Optionen für einen Get-Befehl aktuell unterstützt werden. Die Rückgabe muss dabei folgender Syntax entsprechen:

<code>'''unknown''' argument ''<font color="grey">[Parameter]</font>'' '''choose one of''' ''<font color="grey">[Liste möglicher Optionen]</font>''</code>

Hierbei sind die fett gedruckten Teile der Rückmeldung besonders wichtig. Sind diese nicht vorhanden, kann FHEM nicht die möglichen Get-Kommandos für das entsprechende Gerät ermitteln. Es muss am Anfang der Meldung das Stichwort "unknown" vorkommen gefolgt von einer frei definierbaren Fehlermeldung (i.d.R der übergebene Parameter, welcher ungültig ist). Anschließend folgt "choose one of" mit einer anschließenden Liste möglicher Optionen getrennt durch ein Leerzeichen.

Beispiel:
<ul>
<source lang="perl">return "unknown argument $opt choose one of state temperature humidity";</source>

Hier werden als mögliche Optionen für einen Get-Befehl folgende Parameter angegeben:

* <code>state</code>
* <code>temperature</code>
* <code>humidity</code>

Dies würde in folgenden, mögliche Get-Befehle für einen User resultieren:

* <code>get ''<NAME>'' state</code>
* <code>get ''<NAME>'' temperature</code>
* <code>get ''<NAME>'' humidity</code>
</ul>

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

<u>Nutzung von parseParams()</u>

Wenn in [[#X_Initialize|X_Initialize]] <code>$hash->{parseParams} = 1;</code> gesetzt wurde dann wird [[DevelopmentModuleAPI#parseParams|parseParams]] automatisch aufgerufen und X_Get ändert sich wie folgt:
<source lang="perl">
sub X_Get($$$)
{
my ( $hash, $a, $h ) = @_;
...
</source>

Die genauen Möglichkeiten von parseParams sind in dem entsprechenden [[DevelopmentModuleAPI#parseParams|Artikel]] dokumentiert.

==== X_Set ====
<source lang="perl">
sub X_Set ($$@)
{
my ( $hash, $name, $cmd, @args ) = @_;

...

return $error;
}
</source>

Die Set-Funktion ist das Gegenteil zur [[#X_Get|Get]]-Funktion. Sie ist dafür gedacht, Daten zum physischen Gerät zu schicken, bzw. entsprechende Aktionen im Gerät selber auszulösen. Ein Set-Befehl dient daher der direkten Steuerung des physikalischen Gerätes in dem es bspw. Zustände verändert (wie <code>on</code>/<code>off</code>). Der Set-Funktion wird dabei der Geräte-Hash, der Gerätename, sowie die Aufrufparameter des set-Befehls übergeben. Als Rückgabewert kann eine Fehlermeldung in Form Zeichenkette zurückgegeben werden. Der Rückgabewert <code>undef</code> bedeutet hierbei, dass der Set-Befehl erfolgreich durchgeführt wurde. Eine Set-Funktion gibt daher nur im Fehlerfall eine Rückmeldung mit einer entsprechenden Fehlermeldung. Der Wert <code>undef</code> wird als "erfolgreich" interpretiert. Rückmeldungen von set-Befehlen sämtlicher Module, die im Rahmen eines ausgeführten [[Notify]] auftreten werden im FHEM Logfile festgehalten.

Falls nur interne Daten, die ausschließlich für das Modul relevant sind, gesetzt werden müssen, so sollte statt Set die [[#X_Attr|Attr]]-Funktion verwendet werden. Attribute werden bei Save-Config auch in der Fhem.cfg gesichert. Set-Befehle nicht, da sie nur zur Steuerungszwecken im laufenden Betrieb von FHEM dienen.

Eine Set-Funktion ist ähnlich aufgebaut wie die Get-Funktion, sie bekommt jedoch in der Regel weitere zusätzliche Parameter übergeben um Zustände zu setzen.

Beispiel:
<source lang="perl">
sub X_Set($@)
{
my ( $hash, $name, $cmd, @args ) = @_;

return "\"set $name\" needs at least one argument" unless(defined($cmd)));

if($cmd eq "status")
{
if($args[0] eq "up")
{
...
}
elsif($args[0] eq "down")
{
...
}
else
{
return "Unknown value $args[0] for $cmd, choose one of status power";
}
}
elsif($cmd eq "power")
{
if($args[0] eq "on")
{
...
}
elsif($args[0] eq "off")
{
...
}
else
{
return "Unknown value $args[0] for $cmd, choose one of status power";
}
}
...
else
{
return "Unknown argument $cmd, choose one of status power";
}
}
</source>

Wenn eine unbekannte Option an die Set-Funktion übergeben wird, so muss als Rückgabewert der Funktion eine bestimmte Syntax eingehalten werden um FHEM mitzuteilen, welche Optionen für einen Set-Befehl aktuell unterstützt werden. Die Rückgabe muss dabei folgender Syntax entsprechen:

<code>'''unknown''' argument ''<font color="grey">[Parameter]</font>'' '''choose one of''' ''<font color="grey">[Liste möglicher Optionen]</font>''</code>

Hierbei sind die fett gedruckten Teile der Rückmeldung besonders wichtig. Sind diese nicht vorhanden, kann FHEM nicht die möglichen Set-Kommandos für das entsprechende Gerät ermitteln. Es muss am Anfang der Meldung das Stichwort "unknown" vorkommen gefolgt von einer frei definierbaren Fehlermeldung (i.d.R der übergebene Parameter, welcher ungültig ist). Anschließend folgt "choose one of" mit einer anschließenden Liste möglicher Optionen getrennt durch ein Leerzeichen.

Beispiel:
<ul>
<source lang="perl">return "unknown argument $cmd choose one of state power";</source>

Hier werden als mögliche Optionen für einen Get-Befehl folgende Parameter angegeben:

* <code>state</code>
* <code>power</code>

Dies würde in folgenden, mögliche Get-Befehle für einen User resultieren:

* <code>get ''<NAME>'' state</code>
* <code>get ''<NAME>'' power</code>
</ul>

Die Ausgabe einer solchen Meldung ist sehr wichtig, da sie im GUI-Modul verwendet wird um die möglichen <code>set</code>-Optionen zu ermitteln und als Auswahl anzubieten

<u>Nutzung von SetExtensions.pm</u>

Wenn man dem Nutzer zusätzlich zu den Set-Befehlen <code>on</code> und <code>off</code> auch weiterführende Befehle wie <code>on-for-timer</code>, <code>on-till</code>, usw. anbieten möchte, obwohl die zu steuernde Hardware solche Kommandos nicht unterstützt, kann man dies über das Hilfsmodul SetExtensions.pm realisieren.

Das Hilfsmodul SetExtensions.pm bietet weiterführende Set-Kommandos basierend auf den Befehlen <code>on</code>/<code>off</code> an. Dabei werden durch interne Timer bzw. eigens angelegten [[at]]-Definitionen diese Befehle durch FHEM selber umgesetzt. Je nach ausgeführtem Befehl wird der <code>on</code>- bzw. <code>off</code>-Befehl dann durch FHEM zum richtigen Zeitpunkt ausgeführt. Vorausgesetzt das Modul unterstützt in der Set-Funktion die Befehle <code>on</code> und <code>off</code>, so werden durch den Einsatz von SetExtensions.pm folgende Befehle zusätzlich unterstützt:

{| class="wikitable"
|-
! Set-Kommando !! Beispiel !! Beschreibung
|-
| style="white-space: nowrap;" | <code>on-for-timer ''<Dauer>''</code> || style="white-space: nowrap;" | <code>on-for-timer 120</code> || Schaltet das Gerät sofort mit dem <code>on</code>-Befehl ein und nach der angegebenen Dauer in Sekunden via <code>off</code> wieder aus.
|-
| style="white-space: nowrap;" | <code>off-for-timer ''<Dauer>''</code> || style="white-space: nowrap;" | <code>off-for-timer 120</code> || Schaltet das Gerät sofort mit dem <code>off</code>-Befehl aus und nach der angegebenen Dauer in Sekunden via <code>on</code> wieder ein.
|-
| style="white-space: nowrap;" | <code>on-till ''<Zeitpunkt>''</code> || style="white-space: nowrap;" | <code>on-till 16:30</code> || Schaltet das Gerät sofort mit dem <code>on</code>-Befehl ein und zum angegebenen Zeitpunkt via <code>off</code> wieder aus.
|-
| style="white-space: nowrap;" | <code>off-till ''<Zeitpunkt>''</code> || style="white-space: nowrap;" | <code>off-till 16:30</code> || Schaltet das Gerät sofort mit dem <code>off</code>-Befehl aus und zum angegebenen Zeitpunkt via <code>on</code> wieder ein.
|-
| style="white-space: nowrap;" | <code>on-till-overnight ''<Zeitpunkt>''</code> || style="white-space: nowrap;" | <code>on-till-overnight 01:00</code> || Ähnlich wie <code>on-till</code>. Der übergebene Zeitpunkt wird aber nicht geprüft, ob er für den heutigen Tag bereits überschritten wurde. Dadurch kann man Abends einen Zeitpunkt setzen, der erst am nächsten Tag zutrifft.
|-
| style="white-space: nowrap;" | <code>off-till-overnight ''<Zeitpunkt>''</code> || style="white-space: nowrap;" | <code>off-till-overnight 01:00</code> || Ähnlich wie <code>off-till</code>. Der übergebene Zeitpunkt wird aber nicht geprüft, ob er für den heutigen Tag bereits überschritten wurde. Dadurch kann man Abends einen Zeitpunkt setzen, der erst am nächsten Tag zutrifft.
|-
| style="white-space: nowrap;" | <code>blink ''<Anzahl> <Interval>''</code> || style="white-space: nowrap;" | <code>blink 3 1</code> || Schaltet das Gerät via <code>on</code> für <code>''<Interval>''</code> Sekunden ein und anschließend via <code>off</code> wieder aus. Nach <code>''<Interval>''</code> Sekunden wird das ganze wiederholt, solange bis die angegebene Anzahl erreicht ist.
|-
| style="white-space: nowrap;" | <code>intervals ''<Start>-<Ende>'' ''<Start>-<Ende>'' ...</code> || style="white-space: nowrap;" | <code>intervals 07:00-08:00 16:30-18:00</code> || Schaltet das Gerät innerhalb der übergebenen Zeiträumen via <code>on</code> ein. Sobald die aktuelle Zeit ausserhalb dieser Zeiträume liegt, wird das Gerät via <code>off</code> wieder ausgeschaltet. Es können dabei beliebig viele Zeiträume angegeben werden.
|-
| style="white-space: nowrap;" | <code>toggle</code> || style="white-space: nowrap;" | <code>toggle</code> || Sofern der aktuelle Status <code>on</code> ist, wird das Gerät via <code>off</code> ausgeschaltet. Andernfalls wird es via <code>on</code> eingeschaltet.
|}

Eine kurze Beschreibung zu den möglichen Befehlen durch SetExtensions.pm gibt es auch in der Commandref zum [http://fhem.de/commandref.html#set Set-Befehl].

Um SetExtensions.pm in der Set-Funktion nutzen zu können müssen folgende Aktionen durchgeführt werden:

# Laden von SetExtensions.pm via <code>use SetExtensions;</code> am Anfang des Moduls
# Aufruf und Rückgabe der Funktion [[DevelopmentModuleAPI#SetExtensions|SetExtensions()]] sofern die Set-Funktion mit dem übergebenen Befehl nichts anfangen kann.

Beispiel:

<source lang="perl">
use SetExtensions;

...

sub X_Set($@)
{
my ( $hash, $name, $cmd, @args ) = @_;
my $cmdList = "on off";

return "\"set $name\" needs at least one argument" unless(defined($cmd)));

if($cmd eq "on")
{
# Gerät einschalten...
}
elsif($cmd eq "off")
{
# Gerät ausschalten...
}
...
else # wenn der übergebene Befehl nicht durch X_Set() verarbeitet werden kann, Weitergabe an SetExtensions()
{
return SetExtensions($hash, $cmdList, $name, $cmd, @args);
}
}
</source>

Sollte der übergebene Set-Befehl auch für SetExtensions unbekannt sein (bspw. <code>set ''<Name>'' ?</code>), so generiert SetExtensions() eine entsprechende Usage-Meldung, welche innerhalb der Set-Funktion an FHEM zurückgegeben werden muss.

Eine ausführliche Beschreibung zu der Funktion SetExtensions() gibt es in der [[DevelopmentModuleAPI#SetExtensions|API-Referenz]].

<u>Nutzung von parseParams()</u>

Wenn in [[#X_Initialize|X_Initialize]] <code>$hash->{parseParams} = 1;</code> gesetzt wurde dann wird [[DevelopmentModuleAPI#parseParams|parseParams]] automatisch aufgerufen und X_Set ändert sich wie folgt:
<source lang="perl">
sub X_Set($$$)
{
my ( $hash, $a, $h ) = @_;
...
</source>

Die genauen Möglichkeiten von parseParams sind in dem entsprechenden [[DevelopmentModuleAPI#parseParams|Artikel]] dokumentiert.

<u>Nutzung von FHEMWEB-Widgets</u>

Das GUI-Modul [[FHEMWEB]] kann für die einzelnen Set-Optionen, die das Modul versteht, automatisch Eingabehilfen wie Drop-Down Boxen oder Slider erzeugen. In der Detailansicht der GUI kann der Anwender dann die jeweiligen Werte komfortabel auswählen. Dafür muss die Set-Funktion, wenn sie mit der Option <code>?</code> aufgerufen wird, nicht nur einen Text mit <code>"Unknown ... choose one of ..."</code> zurückgeben sondern den einzelnen Set-Optionen in diesem Rückgabetext nach einem Doppelpunkt entsprechende Zusatzinformationen anhängen.
Meist prüft man in den Modulen gar nicht auf die Option <code>?</code> sondern gibt generell bei unbekannten Optionen diesen Text zurück. Das Modul FHEMWEB ermittelt die Syntax eines Gerätes jedoch immer mit dem Befehl:
set ''<NAME>'' ?

Beispiel:
<source lang="perl">
return "Unknown argument $cmd, choose one of state:up,down power:on,off on:noArg off:noArg";
</source>

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

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

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

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

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

'''Hinweise'''

* Damit in einer Eingabe bereits der aktuelle Wert vorbelegt bzw. in einer Auswahlliste der aktuelle Wert vorselektiert ist, muss es im Modul bzw. Gerät ein Reading mit dem gleichen Namen wie die Set-Option geben. Der Wert des gleichnamigen Readings wird dann als Vorbelegung / Vorselektion verwendet.
* Der User kann sich in der Raumübersicht nach wie vor via [[WebCmd|webCmd]] eine entsprechende Steuerung anlegen.

==== X_Attr ====
<source lang="perl">
sub X_Attr ($$$$)
{
my ( $cmd, $name, $attrName, $attrValue ) = @_;

...

return $error;
}
</source>

Die Attr-Funktion dient der Prüfung von Attributen, welche über den <code>attr</code>-Befehl gesetzt werden können. Sobald versucht wird, ein Attribut für ein Gerät zu setzen, wird vorher die Attr-Funktion des entsprechenden Moduls aufgerufen um zu prüfen, ob das Attribut aus Sicht des Moduls korrekt ist.
Liegt ein Problem mit dem Attribut bzw. dem Wert vor, so muss die Funktion eine aussagekräftige Fehlermeldung zurückgeben, welche dem User angezeigt wird.
Sofern das übergebene Attribut samt Inhalt korrekt ist, gibt die Attr-Funktion den Wert <code>undef</code> zurück. Erst dann wird das Attribut in der globalen Datenstruktur <code>%attr</code> gespeichert und ist somit erst aktiv.

Beispiel:

<source lang="perl">
X_Attr(@)
{
my ( $cmd, $name, $attrName, $attrValue ) = @_;

# $cmd - Vorgangsart - kann die Werte "del" (löschen) oder "set" (setzen) annehmen
# $name - Gerätename
# $attrName/$attrValue sind Attribut-Name und Attribut-Wert

if ($cmd eq "set") {
if ($aName eq "Regex") {
eval { qr/$aVal/ };
if ($@) {
Log3 $name, 3, "X ($name) - Invalid regex in attr $name $aName $aVal: $@";
return "Invalid Regex $aVal: $@";
}
}
}
return undef;
}
</source>

Zusätzlich ist es möglich auch übergebene Attributwerte zu verändern bzw. zu korrigieren, indem man im Parameterarray <code>@_</code> den ursprünglichen Wert anpasst. Dies erfolgt im Beispiel über die Modifikation des Wertes mit Index 3 (entspricht dem 4. Element) im Parameterarray, also <code>$_[3]</code>.

Da das Attribut zum Zeitpunkt des Aufrufs der Attr-Funktion noch nicht gespeichert ist, wird der neue Wert zu diesem Zeitpunkt noch nicht via [[DevelopmentModuleAPI#AttrVal|AttrVal()]] zurückgegeben. Erst, wenn die Attr-Funktion mit <code>undef</code> beendet ist, wird der neue Wert in FHEM gespeichert und steht dann via AttrVal() zur Verfügung.

Die Attr-Funktion bekommt nicht den Hash der Geräteinstanz übergeben, da sie normalerweise keine Werte dort speichern muss, sondern lediglich das Attribut auf Korrektheit prüfen muss.
Im obigen Beispiel wird für ein Attribut mit Namen "Regex" geprüft ob der reguläre Ausdruck fehlerhaft ist. Sofern dieser OK ist, wird <code>undef</code> zurückgegeben und fhem.pl speichert den Wert des Attributs in <code>%attr</code>.

<u>Attributnamen mit Platzhaltern</u>

Falls man Attribute in der [[#X_Initialize|Initialize]]-Funktion mit Platzhaltern definiert (Wildcard-Attribute) wie z.B.:
<source lang="perl">
$hash->{AttrList} =
"reading[0-9]*Name " .
# usw.
</source>
dann können Anwender Attribute wie reading01Name, reading02Name etc. setzen. Leider funktioniert das bisher nicht durch Klicken in der Web-Oberfläche, da FHEMWEB nicht alle denkbaren Ausprägungen in einem Dropdown anbieten kann. Der Benutzer muss solche Attribute manuell über den <code>attr</code>-Befehl eingeben.

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

<source lang="perl">
addToDevAttrList($name, $aName);
</source>

==== X_Read ====
<source lang="perl">
sub X_Read ($)
{
my ( $hash ) = @_;

...
}
</source>
Die X_Read-Funktion wird aufgerufen, wenn ein dem Gerät zugeordneter Filedeskriptor (serielle Schnittstelle, TCP-Verbindung, ...) Daten zum Lesen bereitgestellt hat. Die Daten müssen nun eingelesen und interpretiert werden.

Im folgenden Beispiel wird über eine serielle Schnittstelle (beziehungsweise über einen USB-To-Seriell-Konverter) von einem angeschlossenen Gerät gelesen. Dazu werden die bisher verfügbaren Daten mit der Funktion <code>DevIo_SimpleRead</code> gelesen. Da die Übertragung möglicherweise noch nicht vollständig ist, kann es sein, dass kurz darauf die X_Read-Funktion wieder aufgerufen wird und ein weiterer Teil oder der Rest der Daten gelesen werden kann.
Die Funktion muss daher prüfen ob schon alle erwarteten Daten angekommen sind und gegebenenfalls die bisher gelesenen Daten in einem eigenen Puffer (idealerweise in <code>$hash</code>) zwischenspeichern. Im Beispiel ist dies <code>$hash->{helper}{BUFFER}</code> an den die aktuell gelesenen Daten angehängt werden, bis die folgende Prüfung ein für das jeweilige Protokoll vollständige Frame erkennt.

<source lang="perl">
sub X_Read($)
{
my ($hash) = @_;
my $name = $hash->{NAME};

# einlesen der bereitstehenden Daten
my $buf = DevIo_SimpleRead($hash);
return "" if ( !defined($buf) );
Log3 $name, 5, "X ($name) - received data: ".$buf;

# Daten in Hex konvertieren und an den Puffer anhängen
$hash->{helper}{BUFFER} .= unpack ('H*', $buf);
Log3 $name, 5, "X ($name) - current buffer content: ".$hash->{helper}{BUFFER};

# prüfen, ob im Buffer ein vollständiger Frame zur Verarbeitung vorhanden ist.
if ($hash->{helper}{BUFFER} =~ "ff1002(.{4})(.*)1003(.{4})ff(.*)") {
...
</source>

Die zu lesenden Nutzdaten können dann je nach Protokoll des Geräts beispielsweise an einer festgelegten Stelle im Frame (dann in <code>$hash->{helper}{BUFFER}</code>) stehen oder aus dem Kontext mit einem Regex-Match extrahiert werden und via [[DevelopmentModuleAPI#Readings_.2F_Events|Reading-Funktionen]] in Readings gespeichert werden (siehe unten).

Der Rückgabewert der Read-Funktion wird nicht geprüft und hat daher keinerlei Bedeutung.

==== X_Ready ====
<source lang="perl">
sub X_Ready ($)
{
my ( $hash ) = @_;

...

return $success;
}
</source>

Wird im Main-Loop aufgerufen falls das Modul in der globalen Liste <code>%readyfnlist</code> existiert. Diese Funktion hat je nachdem auf welchem OS FHEM ausgeführt wird unterschiedliche Aufgaben:

* '''UNIX-artiges Betriebssystem:''' prüfen, ob eine Verbindung nach einem Verbindungsabbruch wieder aufgebaut werden kann. Sobald der Verbindungsaufbau erfolgreich war, muss die Funktion einen erfolgreichen Wahrheitswert zurückliefern (z.B. "1") und den eigenen Eintrag entsprechend aus <code>%readyfnlist</code> löschen.
* '''Windows-Betriebssystem:''' prüfen, ob lesbare Daten für ein serielles Device (via COM1, COM2, ...) vorliegen. Sofern lesbare Daten vorliegen, muss Funktion einen erfolgreichen Wahrheitswert zurückliefern (z.B. "1"). Zusätzlich dazu muss die Funktion, wie bei UNIX-artigen Betriebssystem, ebenfalls bei einem Verbindungsabbruch einen neuen Verbindungsversuch initiieren. Der Eintrag in <code>%readyfnlist</code> bleibt solange erhalten, bis die Verbindung seitens FHEM beendet wird.

Der Windows-spezifische Teil zur Datenprüfung ist dabei nur zu implementieren, wenn das Modul über eine serielle Verbindung kommuniziert.

Bei der Nutzung des Moduls DevIo wird dem Modulentwickler der Umgang mit <code>%readyfnlist</code> abgenommen, da DevIo sich selbst um die entsprechenden Einträge kümmert und diese selbstständig wieder entfernt.

In der Regel sieht eine Ready-Funktion immer gleich aus.

Beispiel:
<source lang="perl">
sub X_Ready($)
{
my ($hash) = @_;

# Versuch eines Verbindungsaufbaus, sofern die Verbindung beendet ist.
return DevIo_OpenDev($hash, 1, undef ) if ( $hash->{STATE} eq "disconnected" );

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

==== X_Notify ====

Die X_Notify-Funktion wird aus der Funktion [[DevelopmentModuleAPI#DoTrigger|DoTrigger()]] in fhem.pl heraus aufgerufen sobald ein Modul Events erzeugt hat. Damit kann ein Modul auf Events anderer Module reagieren. Typische Beispiele sind dabei das [[FileLog]]-Modul oder das [[notify]]-Modul.

Die Notify-Funktion bekommt dafür zwei Hash-Referenzen übergeben: den Hash des eigenen Geräts und den Hash des Geräts, dass die Events erzeugt hat.
Über den Hash des eigenen Geräts kann die Notify-Funktion beispielsweise auf die Internals oder Attribute des eigenen Geräts zugreifen.
Über den Hash des Gerätes und der [[DevelopmentModuleAPI#deviceEvents|deviceEvents()]]-Funktion kann man auf die generierten Events zugreifen. Über den zweiten Parameter dieser Routine lässt sich bestimmen ob für das Reading <code>state</code> ein 'normales' Event (d.h. in der form <code>state: <wert></code>) erzeugen soll (Wert: 1) oder ob z.b. aus Gründen der Rückwärtskompatibilität ein Event ohne <code>state: </code> erzeugt werden soll. Falls dem Anwender die Wahl des verwendeten Formats überlassen werden soll ist hierzu das [http://fhem.de/commandref_DE.html#addStateEvent addStateEvent-Attribut] vorzusehen.

Der direkte Zugriff auf <code>$hash->{CHANGED}</code> ist nicht mehr zu empfehlen.

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

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

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

my $events = deviceEvents($dev_hash,1);
return if( !$events );

foreach my $event (@{$events}) {
$event = "" if(!defined($event));

# Examples:
# $event = "readingname: value"
# or
# $event = "INITIALIZED" (for $devName equal "global")
#
# processing $event with further code
}
}
</source>

<u>Begrenzung der Aufrufe auf bestimmte Geräte</u>

Da die Notify-Funktion für jedes definierte Gerät mit all seinen Events aufgerufen wird, muss sie in einer Schleife jedesmal prüfen und entscheiden, ob es mit dem jeweiligen Event etwas anfangen kann. Ein Gerät, dass die Notify-Funktion implementiert, sieht dafür typischerweise einen regulären Ausdruck vor, welcher für die Filterung verwendet wird.

Wenn man nur gezielt von bestimmten Definitionen Events erhalten will, kann man diese auch in Form einer [http://fhem.de/commandref_DE.html#devspec devspec] in <code>$hash->{NOTIFYDEV}</code> angeben. Bspw. kann man in der Define-Funktion diesen Wert setzen. Dadurch wird die Notify-Funktion nur aufgerufen wenn eine der Definitionen, auf welche die devspec passt, ein Event erzeugt hat. Ein typischer Fall ist die Begrenzung von Events auf "global":

<source lang="perl">
in der Define-Funktion:

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

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

Sofern in der [[#X_Define|Define-Funktion]] eine Regexp als Argument übergeben wird, die ähnlich wie beim Modul [[notify]] auf Events wie <code><Definitionsname></code> bzw. <code><Definitionsname>:<Event></code> reagiert, so sollte man in der Define-Funktion die Funktion [[DevelopmentModuleAPI#notifyRegexpChanged|notifyRegexpChanged()]] verwenden. Diese versucht einen passenden Eintrag für <code>$hash->{NOTIFYDEV}</code> basierend auf der übergebenen Regexp zu setzen, sofern dies möglich ist.

<u>Reihenfolge für den Aufruf der Notify-Funktion beeinflussen</u>

Sobald ein Event ausgelöst wurde, stellt sich FHEM eine Liste aller relevanten Geräte-Hashes zusammen, welche via Notify-Funktion prüfen müssen, ob das Event relevant ist. Dabei wird die Liste nach <code>$hash->{NTFY_ORDER}</code> sortiert. Diese enthält ein Order-Präfix in Form einer Ganzzahl, sowie den Namen der Definition (Bsp: <code>'''50'''-Lampe_Wohnzimmer</code>). Dadurch kann man jedoch nicht sicherstellen, dass Events von bestimmten Modulen zuerst verarbeitet werden.

Wenn das eigene Modul bei der Eventverarbeitung gegenüber den anderen Modulen eine bestimmte Reihenfolge einhalten muss, kann man in der [[#X_Initialize|Initialize]]-Funktion durch Setzen von <code>$hash->{NotifyOrderPrefix}</code> diese Reihenfolge beeinflussen. Standardmäßig werden Module immer mit einem Order-Präfix von "50-" in FHEM registriert. Durch die Veränderung dieses Präfixes kann man das eigene Modul in der Reihenfolge gegenüber anderen Modulen bei der Eventverarbeitung beeinflussen.

Beispiel:

<source lang="perl">
sub X_Initialize($)
{
my ($hash) = @_;

...

$hash->{NotifyOrderPrefix} = "45-" # Alle Definitionen des Moduls X werden bei der Eventverarbeitung zuerst geprüft

# oder...

$hash->{NotifyOrderPrefix} = "55-" # Alle Definitionen des Moduls X werden bei der Eventverarbeitung als letztes geprüft

</source>

Da dieses Präfix bei eventverarbeitenden Definitionen in <code>$hash->{NTFY_ORDER}</code> dem Definitionsnamen vorangestellt wird bewirkt es bei einer normalen aufsteigenden Sortierung nach <code>$hash->{NTFY_ORDER}</code> eine veränderte Reihenfolge. Alle Module die in der Initialize-Funktion nicht <code>$hash->{NotifyOrderPrefix}</code> explizit setzen, werden mit "50-" als Standardwert vorbelegt.

==== X_Rename ====
<source lang="perl">
sub X_Rename ($$)
{
my ( $new_name, $old_name) = @_;

...
}
</source>

Die Rename-Funktion wird ausgeführt, nachdem ein Gerät umbenannt wurde. Auf diese Weise kann ein Modul auf eine Namensänderung reagieren, wenn das Gerät <code>$old_name</code> in <code>$new_name</code> umbenannt wurde. Ein typischer Fall ist das Umsetzen der Namensänderungen bei Daten die mittels [[DevelopmentModuleAPI#setKeyValue|setKeyValue()]] gespeichert wurden. Hierbei müssen die Daten, welche unter dem alten Namen gespeichert sind, auf den neuen Namen geändert werden.

Der Rename-Funktion wird lediglich der alte, sowie der neue Gerätename übergeben. Der Rückgabewert wird nicht ausgewertet.

Beispiel:
<source lang="perl">
sub X_Rename ($)
{
my ( $new_name, $old_name ) = @_;

my $old_index = "Module_X_".$old_name."_data";
my $new_index = "Module_X_".$new_name."_data";

my ($err, $data) = getKeyValue($old_index);
return undef unless(defined($old_pwd));

setKeyValue($new_index, $data);
setKeyValue($old_index, undef);
}
</source>

==== X_Shutdown ====
<source lang="perl">
sub X_Shutdown ($)
{
my ( $hash ) = @_;

...
}
</source>
Mit der X_Shutdown Funktion kann ein Modul Aktionen durchführen bevor FHEM gestoppt wird. Dies kann z.B. der ordnungsgemäße Verbindungsabbau mit dem physikalischen Gerät sein (z.B. Session beenden, Logout, etc.). Als Übergabeparameter wird der Geräte-Hash bereitgestellt. Der Rückgabewert einer Shutdown-Funktion wird nicht ausgewertet und ist daher irrelevant.

Beispiel:
<source lang="perl">
sub X_Shutdown($)
{
my ($hash) = @_;

# Verbindung schließen
DevIo_CloseDev($hash);
return undef;
}
</source>

=== Funktionen für zweistufiges Modulkonzept ===

Für das [[#Zweistufiges_Modell_für_Module|zweistufige Modulkonzept]] gibt es weiterhin:

{| class="wikitable sortable"
|-
! style="text-align:left" | Funktionsname !! style="text-align:left" class="unsortable" | Kurzbeschreibung
|-
| [[#X_Parse|X_Parse]] || Zustellen von Daten via [[DevelopmentModuleAPI#Dispatch|Dispatch()]] vom physischen Modul zum logischen Modul zwecks der Verarbeitung.
|-
| [[#X_Write|X_Write]]|| Zustellen von Daten via [[DevelopmentModuleAPI#Dispatch|IOWrite()]] vom logischen zum physischen Modul um diese an die Hardware weiterzureichen.
|-
| [[#X_Fingerprint|X_Fingerprint]] || Rückgabe eines "Fingerabdrucks" einer Nachricht. Dient der Erkennung von Duplikaten im Rahmen von [[DevelopmentModuleAPI#Dispatch|Dispatch()]]. Kann im physischen, als auch logischen Modul benutzt werden.
|}

Für das zweistufige Modulkonzept muss in einem logischen Modul eine [[#X_Parse|Parse]]-Funktion im Modul-Hash registriert werden. In einem physikalischen Modul muss eine [[#X_Write|Write]]-Funktion definiert sein. Diese dienem dem Datenaustausch in beide Richtungen und werden von dem jeweils anderen Modul indirekt aufgerufen.

In der [[#X_Initialize|Initialize]]-Funktion werden diese wie folgt definiert:

<source lang="perl">
$hash->{ParseFn} = "X_Parse";
$hash->{WriteFn} = "X_Write";
$hash->{FingerprintFn} = "X_Fingerprint";
</source>

Diese Funktionen werden in diesem Abschnitt genauer beschrieben.

==== X_Parse ====
{{Randnotiz|RNTyp=Info|RNText=<font color="red"><u>'''ACHTUNG''':</u></font>
Dieser Abschnitt geht davon aus, dass das Modul mit dem Namen "X" ein '''logisches Modul''' im Sinne des zweistufigen Modulkonzepts ist, also Daten mit einem übergeordneten, physikalischen Modul austauscht.}}
<source lang="perl">
sub X_Parse ($$)
{
my ( $io_hash, $message) = @_;

...

return $found;
}
</source>

Die Funktion X_Parse wird aufgerufen, sobald von dem IO-Gerät <code>$io_hash</code> eine Nachricht <code>$message</code> via [[DevelopmentModuleAPI#Dispatch|Dispatch()]] zur Verarbeitung angefragt wird. Die Parse-Funktion muss dann prüfen, zu welcher Gerätedefinition diese Nachricht gehört und diese entsprechend verarbeiten.

Üblicherweise enthält eine Nachricht immer eine Komponente durch welche sich die Nachricht einem Gerät zuordnen lässt (z.B. Adresse, ID-Nummer, ...). Eine solche Identifikation sollte man im Rahmen der [[#X_Define|Define]]-Funktion im logischen Modul an geeigneter Stelle speichern, um in der Parse-Funktion eine einfache Zuordnung von Adresse/ID einer Nachricht zur entsprechenden Gerätedefinition zu haben. Dazu wird in der Regel im Modul-Hash im modulspezifischen Berreich eine Liste <code>defptr</code> (Definition Pointer) geführt, welche jede eindeutige Adresse/ID dem entsprechenden Geräte-Hash zuordnet:

<source lang="perl">

sub X_Define ($$)
{
my ( $hash, $def) = @_;
my @a = split("[ \t][ \t]*", $def);
my $name = $a[0];

...

# erstes Argument ist die eindeutige Geräteadresse
my $address = $a[1];

# Adresse rückwärts dem Hash zuordnen (für ParseFn)
$modules{X}{defptr}{$address} = $hash;

...
}
</source>

Auf Basis dieses Definition Pointers kann die Parse-Funktion nun sehr einfach prüfen, ob für die empfangene Nachricht bereits eine entsprechende Gerätedefinition existiert. Sofern diese existiert, kann die Nachricht entsprechend verarbeitet werden. Sollte jedoch keine passende Gerätedefinition zu der empfangenen Nachricht existieren, so muss die Parse-Funktion den Gerätenamen "UNDEFINED" zusammen mit den Argumenten für einen <code>define</code>-Befehl zurückgeben, welcher ein passendes Gerät in FHEM anlegen würde (durch [[autocreate]]).

Beispiel:

<source lang="perl">

sub X_Parse ($$)
{
my ( $io_hash, $message) = @_;

# Die Stellen 10-15 enthalten die eindeutige Identifikation des Geräts
my $address = substr($message, 10, 5);

# wenn bereits eine Gerätedefinition existiert (via Definition Pointer aus Define-Funktion)
if(my $hash = $modules{X}{defptr}{$address})
{
... # Nachricht für $hash verarbeiten

# Rückgabe des Gerätenamens, für welches die Nachricht bestimmt ist.
return $hash->{NAME};
}
else
{
# Keine Gerätedefinition verfügbar
# Daher Vorschlag define-Befehl: <NAME> <MODULNAME> <ADDRESSE>
return "UNDEFINED X_".$address." X $address";
}
}
</source>

==== X_Write ====
{{Randnotiz|RNTyp=Info|RNText=<font color="red"><u>'''ACHTUNG''':</u></font>
Dieser Abschnitt geht davon aus, dass das Modul mit dem Namen "X" ein '''physisches Modul''' im Sinne des zweistufigen Modulkonzepts ist, also Daten mit untergeordneten logischen Modulen austauscht. }}
<source lang="perl">
sub X_Write ($$)
{
my ( $hash, @arguments) = @_;

...

return $return;
}
</source>

Die Write-Funktion wird durch die Funktion [[DevelopmentModuleAPI#IOWrite|IOWrite()]] aufgerufen, sobald eine logische Gerätedefinition Daten per IO-Gerät an die Hardware übertragen möchte. Dazu kümmert sich die Write-Funktion um die Übertragung der Nachricht in geeigneter Form an die verbundene Hardware. Als Argumente wird der Hash des physischen Gerätes übertragen, sowie alle weiteren Argumente, die das logische Modul beim Aufruf von IOWrite() mitgegeben hat. Im Normalfall ist das ein Skalar mit der zu sendenden Nachricht in Textform. Es kann aber auch sein, dass weitere Daten zum Versand notwendig sind (evtl. Schlüssel, Session-Key, ...). Daher ist die Parametersyntax einer zu schreibenden Nachricht via IOWrite-/Write-Funktion zwischen logischem und physikalischen Modul abzustimmen.

Beispiel:

<source lang="perl">
sub X_Write ($$)
{
my ( $hash, $message, $address) = @_;

DevIo_SimpleWrite($hash, $address.$message, 2);

return undef;
}
</source>

==== X_Fingerprint ====
<source lang="perl">
sub X_Fingerprint($$)
{
my ( $io_name, $msg ) = @_;

...

return ( $io_name, $fingerprint );
}
</source>

Die Fingerprint-Funktion dient der Erkennung von Duplikaten empfangener Nachrichten. Diese Funktion kann dabei sowohl im physischen, als auch im logischen Modul implementiert sein. Je nachdem auf welcher Ebene man für eine Nachricht einen Fingerprint bilden kann.

Als Parameter wird der Name des IO-Geräts <code>$io_name</code> übergeben, sowie die Nachricht <code>$msg</code>, welche empfangen wurde. Nun muss aus dieser Nachricht ein eindeutiger Fingerprint gebildet werden. Dies bedeutet, dass alle variablen Inhalte, die aufgrund des Empfangs dieser Nachricht über unterschiedliche IO-Geräte enthalten sein können, entfernt werden müssen. Dies können bspw. Empfangsadressen von IO-Geräten sein oder Session-ID's die in der Nachricht enthalten sind. Alle Fingerprints sämtlicher Nachrichten, die innerhalb der letzten 500 Millisekunden (konfigurierbar via <code>global</code> Attribut <code>dupTimeout</code>) empfangen wurden, werden gegen diesen generierten Fingerprint getestet. Sollte innerhalb dieser Zeit bereits eine Nachricht mit diesem Fingerprint verarbeitet worden sein, so wird sie als Duplikat erkannt und nicht weiter verarbeitet. In diesem Fall gibt [[DevelopmentModuleAPI#Dispatch|Dispatch()]] den Namen der Gerätedefinition zurück, welche eine Nachricht mit dem selben Fingerprint bereits verarbeitet hat. Es erfolgt dann kein Aufruf der [[#X_Parse|Parse]]-Funktion.

Beispiel:

<source lang="perl">
sub X_Fingerprint($$)
{
my ( $io_name, $msg ) = @_;

substr( $msg, 2, 2, "--" ); # entferne Empfangsadresse
substr( $msg, 4, 1, "-" ); # entferne Hop-Count

return ( $io_name, $msg );
}
</source>

Es wird zuerst, sofern implementiert, die Fingerprint-Funktion des physischen Moduls aufgerufen. Sollte sich hierdurch kein Duplikat erkennen lassen, wird die Fingerprint-Funktion jedes möglichen geladenen logischen Moduls aufgerufen, sofern implementiert.

Sollte sowohl im physischen, als auch im logischen Modul keine Fingerprint-Funktion implementiert sein, so wird keinerlei Duplikatserkennung durchgeführt.

=== FHEMWEB-spezifische Funktionen ===

FHEMWEB bietet Modulautoren die Möglichkeit an durch spezielle Funktionsaufrufe in Modulen, eigene HTML-Inhalte zu verwenden. Dadurch können in Verbindung mit zusätzlichem JavaScript komplexe Dialoge/Inhalte/Steuermöglichkeiten dargestellt werden.

Eine genaue Auflistung aller FHEMWEB-spezifischen Funktionsaufrufe gibt es in dem separaten Artikel [[DevelopmentFHEMWEB]]

=== sonstige Funktionen ===

In diesem Abschnitt werden weitere Funktionen behandelt die zum Teil aus FHEM, aber auch aus anderen Modulen aufgerufen werden. Sie sind dabei nur in speziellen Anwendungsfällen relevant. Hier eine Auflistung aller sonstigen Modulfunktionen:

{| class="wikitable sortable"
|-
! Funktionsname !! class="unsortable" | Kurzbeschreibung
|-
| [[#X_DbLog_split|X_DbLog_split]] || Wird durch das Modul 93_DbLog.pm aufgerufen. Dient dem korrekten Split eines moduleigenen Events in Name/Wert/Einheit für die Nutzung einer Datenbank.
|-
| [[#X_Except|X_Except]]|| Wird aufgerufen, sobald ein ein geöffneter Filedescriptor in [[#Wichtige_globale_Variablen_aus_fhem.pl|<code>%selectlist</code>]], der unter <code>$hash->{EXCEPT_FD}</code> im Geräte-Hash gesetzt ist, einen Interrupt bzw. Exception auslöst.
|-
| [[#X_Copy|X_Copy]]|| Wird durch das Modul 98_copy.pm aufgerufen im Rahmen des <code>copy</code>-Befehls sobald ein Gerät kopiert wurde.
|-
| [[#X_State|X_State]]|| Wird aufgerufen im Rahmen des <code>setstate</code>-Befehls bevor der Status einer Gerätedefinition bzw. eines zugehörigen Readings gesetzt wird.
|-
| [[#X_AsyncOutput|X_AsyncOutput]]|| Nur Relevant für Module die via [[TcpServerUtils]] eine Client-Verbindung zu FHEM ermöglichen (z.B. FHEMWEB und telnet). Ermöglicht die asynchrone Ausgabe von Daten via [[DevelopmentModuleAPI#asyncOutput|asyncOutput()]] an einen einzelnen verbundenen Client.
|-
| [[#X_ActivateInform|X_ActivateInform]]|| Nur Relevant für Module die via [[TcpServerUtils]] eine Client-Verbindung zu FHEM ermöglichen (z.B. FHEMWEB und telnet). Ermöglicht das aktivieren des inform-Mechanismus zum senden von Events für einen einzelnen verbundenen Client.
|-
| [[#X_Authorize|X_Authorize]]|| Wird aufgerufen im Rahmen von [[DevelopmentModuleAPI#Authorize|Authorize()]] um eine gewünschte Vorgangs-Art zu autorisieren.
|-
| [[#X_Authenticate|X_Authenticate]]|| Wird aufgerufen im Rahmen von [[DevelopmentModuleAPI#Authenticate|Authenticate()]] um eine Authentifizierung zu prüfen und ggf. zu genehmigen.
|}

In der [[#X_Initialize|Initialize]]-Funktion werden diese wie folgt definiert:

<source lang="perl">
$hash->{DbLog_splitFn} = "X_DbLog_split";
$hash->{ExceptFn} = "X_Except";
$hash->{CopyFn} = "X_Copy";
$hash->{AsyncOutputFn} = "X_AsyncOutput";
$hash->{ActivateInformFn} = "X_ActivateInform";
$hash->{StateFn} = "X_State";
$hash->{AuthorizeFn} = "X_Authorize";
$hash->{AuthenticateFn} = "X_Authenticate";
</source>

Diese Funktionen werden in diesem Abschnitt genauer beschrieben.
==== X_DbLog_split ====
<source lang="perl">
sub X_DbLog_split ($$)
{
my ( $event, $device_name ) = @_;

...

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

Die DbLog_split-Funktion wird durch das Modul [[DbLog]] aufgerufen, sofern der Nutzer DbLog benutzt. Sofern diese Funktion implementiert ist, kann der Modulautor das Auftrennen von Events in den Reading-Namen, -Wert und der Einheit selbst steuern. Andernfalls nimmt DbLog diese Auftrennung selber mittels Trennung durch Leerzeichen sowie vordefinierten Regeln zu verschiedenen Modulen vor. Je nachdem, welche Readings man in seinem Modul implementiert, passt diese standardmäßige Trennung jedoch nicht immer.

Der Funktion werden folgende Eingangsparameter übergeben:
# Das generierte Event (Bsp: <code>temperature: 20.5 °C</code>)
# Der Name des Geräts, welche das Event erzeugt hat (Bsp: <code>Temperatursensor_Wohnzimmer</code>)

Es ist nicht möglich in der DbLog_split-Funktion auf die verarbeitende DbLog-Definition zu referenzieren.

Als Rückgabewerte muss die Funktion folgende Werte bereitstellen:
# Name des Readings (Bsp: <code>temperature</code>)
# Wert des Readings (Bsp: <code>20.5</code>)
# Einheit des Readings (Bsp: <code>°C</code>)

Beispiel:
<source lang="perl">
sub X_DbLog_splitFn($$)
{
my ($event, $device) = @_;
my ($reading, $value, $unit);
my $devhash = $defs{$device}

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

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

==== X_Except ====
<source lang="perl">
sub X_Except ($)
{
my ( $hash ) = @_;

...
}
</source>

Die X_Except-Funktion wird durch fhem.pl aufgerufen, wenn die Gerätedefinition <code>$hash</code> in <code>[[#Wichtige_globale_Variablen_aus_fhem.pl|%selectlist]]</code> aufgeführt ist und der Filedeskriptor in <code>$hash->{EXCEPT_FD}</code> eine Exception bzw. Interrupt auslöst.

Der Rückgabewert wird nicht ausgewertet und ist daher irrelevant.

Beispiel:

<source lang="perl">
use IO::File;

...

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

# Filehandle aus Filedescriptor erstellen
my $filehandle = IO::File->new_from_fd($hash->{EXCEPT_FD}, 'r');
seek($filehandle,0,0);

# aktuellen Inhalt auslesen
my $current_value = $filehandle->getline;

if($current_value eq "1")
{
...
}
else
{
...
}
}
</source>

==== X_Copy ====
<source lang="perl">
sub X_Copy ($)
{
my ( $old_name, $new_name ) = @_;

...
}
</source>

Die X_Copy-Funktion wird durch das Modul [[copy]] aufgerufen nachdem ein Nutzer eine Gerätedefinition über den Befehl <code>copy</code> kopiert hat. Dazu werden als Funktionsparameter die Definitionsnamen der alten und neuen Gerätedefinition übergeben. Es dient dazu zusätzliche Daten aus der zu kopierenden Gerätedefinition in die neue Definition zu übernehmen. Der Befehl <code>copy</code> überträgt lediglich <code>$hash->{DEF}</code> in die neue Definition sowie sämtliche gesetzte Attribute. Weitere Daten müssen dann durch die X_Copy-Funktion übertragen werden.

Die X_Copy-Funktion wird erst nach dem erfolgtem Kopiervorgang aufgerufen.

Der Rückgabewert wird nicht ausgewertet und ist daher irrelevant.

Beispiel:

<source lang="perl">

sub X_Copy ($$)
{
my ( $old_name, $new_name ) = @_;

my $old_hash = $defs{$old_name};
my $new_hash = $defs{$new_name};

# copy also temporary session key
$new_hash->{helper}{SESSION_KEY} = $old_hash->{helper}{SESSION_KEY};
}
</source>

==== X_AsyncOutput ====
TBD

==== X_ActivateInform ====
TBD
==== X_State ====
<source lang="perl">
sub X_State($)
{
my ( $hash, $time, $readingName, $value ) = @_;

...

return $error;
}
</source>

Die X_State-Funktion wird durch fhem.pl aufgerufen, sobald über den Befehl <code>setstate</code> versucht wird ein Wert für ein Reading oder den Status (<code>$hash->{STATE}</code>) einer Gerätedefinition zu setzen. Dieser Befehl wird primär beim Starten von FHEM aufgerufen sobald das State-File eingelesen wird. Je nachdem, ob im gegebenen Fall ein Reading oder der Definitionsstatus gesetzt wird, haben die Übergabeparameter verschiedene Werte:

{| class="wikitable"
|-
! Funktionsparameter!! Wert beim Setzen eines Readings !! Wert beim Setzen eines Definitionsstatus
|-
| <code>$hash</code> || colspan=2 align=center | Die Hashreferenz der betreffenden Gerätedefinition
|-
| <code>$time</code>|| Der Zeitstempel auf welchen das Reading <code>$readingName</code> gesetzt werden soll. Das Ergebnis entspricht dem Rückgabewert der Funktion || Der aktuelle Zeitstempel zum jetzigen diesem Zeitpunkt.
|-
| <code>$readingName</code>|| Der Name des Readings, welches auf einen neuen Wert gesetzt werden soll. || Statischer Wert "STATE" um anzuzeigen, dass es sich um den Definitionsstatus handelt, welcher gesetzt werden soll (<code>$hash->{STATE}</code>).
|-
| <code>$value</code> || Der Wert, welchen das Reading <code>$readingName</code> annehmen soll. || Der Wert, welchen die Gerätedefinition als Status annehmen soll.
|}

Wenn via <code>setstate</code> ein Reading gesetzt wird, kann die X_State-Funktion das Setzen dieses Readings durch die Rückgabe einer aussagekräftigen Fehlermeldung unterbinden. Sofern <code>undef</code> zurückgegeben wird, wird das entsprechende Reading auf den übergebenen Status gesetzt.

Wenn via <code>setstate</code> der Definitionsstatus gesetzt wird, wird die X_State-Funktion erst nach dem Setzen des Status aufgerufen. Man kann dabei zwar eine Fehlermeldung zurückgeben. Der Status wird aber dennoch übernommen. Die Fehlermeldung wird lediglich dem Nutzer angezeigt.

Beispiel:

<source lang="perl">
sub X_State($)
{
my ( $hash, $time, $readingName, $value ) = @_;

return undef if($readingName "STATE" || $value ne "inactive");
readingsSingleUpdate($hash, "state", "inactive", 1);
return undef;
}
</source>

==== X_Authorize ====
TBD

==== X_Authenticate ====
TBD

== Bereitstellen eines eigenen Befehls (Befehlsmodul) ==

Ein Modul kann primär einen neuen FHEM-Befehl bereitstellen. Man spricht in so einem Fall nicht von einem Gerätemodul, sondern einem Befehlsmodul. Ein solches Befehlsmodul stellt nur einen einzelnen Befehl bereit, der dem Modulnamen entsprechen muss. Nur, wenn der Modulname dem Befehlsname entspricht, kann FHEM das Modul beim ersten Ausführen dieses unbekannten Befehls finden und nachladen.

Der entsprechende Befehl wird dazu in der [[#X_Initialize|Initialize]]-Funktion im globalen Hash <code>[[DevelopmentModuleIntro#Wichtige_globale_Variablen_aus_fhem.pl|%cmds]]</code> registriert:

<source lang="perl">
sub X_Initialize($$) {

$cmds{X} = { Fn => "CommandX",
Hlp => "<argument1> [optional_argument2], print something very useful",

# optional
ClientFilter => "FHEMWEB"
};
}
</source>

Damit wird der neue Befehl <code>X</code> in FHEM registriert. Die Funktion mit dem Namen <code>CommandX</code> setzt diesen Befehl innerhalb des Moduls um. Desweiteren wird eine kurze Aufrufsyntax mitgegeben, welche beim Aufruf des <code>help</code>-Befehls dem Nutzer angezeigt wird um als Gedankenstütze zu dienen. Optional kann man mittels <code>ClientFilter</code> die Ausführbarkeit nur auf bestimmte Client-Module (wie FHEMWEB oder telnet) beschränken.

Nun muss noch die Funktion <code>CommandX</code> im Rahmen des Moduls implementiert werden, welche den Befehl <code>X</code> umsetzt:

<source lang="Perl">
sub CommandX($$)
{
my ($client_hash, $arguments) = @_;

...

return $output;
}
</source>

Dabei werden der Befehlsfunktion zwei Parameter übergeben. Zuerst die Hash-Referenz des aufrufenden Clients (sofern manuell ausgeführt, ansonsten <code>undef</code>) zwecks Rechteprüfung via [[allowed|allowed-Definitionen]]. Anschließend folgen die Aufrufparameter als zusammenhängende Zeichenkette. Die Trennung der einzelnen Argumente obligt der Funktion (bspw. via [[DevelopmentModuleAPI#parseParams|parseParams()]]). Als Funktionsrückgabewert wird eine Ausgabemeldung erwartet, die dem Nutzer angezeigt werden soll.

== Pollen von Geräten ==
Wenn Geräte von sich aus keine Informationen senden sondern abgefragt werden müssen, kann man im Modul die Funktion [[DevelopmentModuleAPI#InternalTimer|InternalTimer()]] verwenden um einen Funktionsaufruf zu einem späteren Zeitpunkt durchführen zu können. Man übergibt dabei den Zeitpunkt für den nächsten Aufruf, den Namen der Funktion, die aufgerufen werden soll, sowie den zu übergebenden Parameter. Als zu übergebender Parameter wird üblicherweise der Hash der betroffenen Geräteinstanz verwendet. Damit hat die aufgerufene Funktion Zugriff auf alle wichtigen Daten der Geräteinstanz. Eventuell zusätzlich benötigte Werte können einfach als weitere Internals über den Hash zugänglich gemacht werden.

Beispielsweise könnte man für das Abfragen eines Geräts in der [[#X_Define|Define]]-Funktion den Timer folgendermaßen setzen:

<source lang="perl">
InternalTimer(gettimeofday()+2, "X_GetUpdate", $hash);
</source>

Alternativ kann man auch in der [[#X_Notify|Notify]]-Funktion auf das Event <code>global:INITIALIZED</code> bzw. <code>global:REREADCFG</code> reagieren und erst dort, den Timer anstoßen, sobald die Konfiguration komplett eingelesen wurde. Dies ist insbesondere notwendig, wenn man sicherstellen will, dass alle Attribute aus der Konfiguration gesetzt sind, sobald man einen Status-Update initiiert.

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

<source lang="perl">
sub X_GetUpdate($)
{
my ($hash) = @_;
my $name = $hash->{NAME};
Log3 $name, 4, "X: GetUpdate called ...";

...

# neuen Timer starten in einem konfigurierten Interval.
InternalTimer(gettimeofday()+$hash->{Interval}, "X_GetUpdate", $hash);
}
</source>

Innerhalb der Funktion kann man nun das Gerät abfragen und die abgefragten Werte in Readings speichern. Falls das Abfragen der Werte jedoch zu einer Verzögerung und damit zu einer Blockade von FHEM führen kann, ist es möglich, in der GetUpdate-Funktion nur die Aufforderung zum Senden bestimmter Daten an das angeschlossene Gerät zu senden und dann das Lesen über die oben beschriebene [[#X_Read|Read]]-Funktion zu implementieren.

Eine genaue Beschreibung der Timer-Funktion gibt es [[DevelopmentModuleAPI#Timer|hier im Wiki]]

== Logging / Debugging ==
Um Innerhalb eines Moduls eine Log-Meldung in die FHEM-Logdatei zu schreiben, wird die Funktion [[DevelopmentModuleAPI#Log3|Log3()]] aufgerufen.
<source lang="perl">
Log3 $name, 3, "X ($name) - Problem erkannt ...";
</source>
Eine genaue Beschreibung zu der Funktion inkl. Aufrufparameter findet man [[DevelopmentModuleAPI#Log3|hier]]. Es ist generell ratsam in der Logmeldung sowohl den Namen des eigenen Moduls zu schreiben, sowie den Namen des Geräts, welche diese Logmeldung produziert, da die Meldung, so wie sie ist, direkt in das Logfile wandert und es für User ohne diese Informationen schwierig ist, die Meldungen korrekt zuzuordnen.

Die Funktion Log3() verwendet den Namen der Geräteinstanz um das <code>verbose</code>-Attribut zu prüfen. In der Regel wird bei Modulfunktionen jedoch immer nur der Gerätehash <code>$hash</code> übergeben. Um den Namen der Definition zu ermitteln ist es daher notwendig sich diesen aus dem Hash extrahieren:

<source lang="perl">
my $name = $hash->{NAME};
</source>

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

Logmeldungen sollten je nach Art und Wichtigkeit für den Nutzer in unterschiedlichen Loglevels erzeugt werden. Es gibt insgesamt 5 Stufen in denen geloggt werden kann. Standardmäßig steht der systemweite Loglevel (<code>global</code>-Attribut <code>verbose</code>) auf der Stufe 3. Die Bedeutung der jeweiligen Stufen ist in der [http://fhem.de/commandref_DE.html#verbose commandref] beschrieben.

Während der Entwicklung eines Moduls kann man für eigene Debug-Zwecke auch die Funktion [[DevelopmentModuleAPI#Debug|Debug()]] verwenden um schnell und einfach Debug-Ausgaben in das Log zu schreiben. Diese sollten in der endgültigen Fassung jedoch nicht mehr vorhanden sein. Sie dienen ausschließlich zum Debugging während der Entwicklung.

Eine genaue Beschreibung der Log-Funktion gibt es [[DevelopmentModuleAPI#Logging|hier im Wiki]].

== Zweistufiges Modell für Module ==
[[Datei:Zweistufiges Modulkonzept.jpg|mini|rechts]]
Es gibt viele Geräte, welche die Kommunikation mit weiteren Geräten mit tlw. unterschiedlichen Protokollen ermöglichen. Das typischste Beispiel bietet hier der [[CUL]], welcher via Funk mit verschiedenen Protokollen weitere Geräte ansprechen kann (z.B. Aktoren, Sensoren, ...). Hier bildet ein Gerät eine Brücke durch die weitere Geräte in FHEM zugänglich gemacht werden können. Dabei werden über einen Kommunikationsweg (z.B. serielle Schnittstelle, TCP, ...) beliebig viele Geräte gesteuert. Typische Beispiele dazu sind:

* [[CUL]]: stellt Geräte mit verschiedenen Kommunikationsprotokollen via Funk bereit (u.a. [[FS20]], [[HomeMatic]], [[Funk-Heizkörperregler_Kurz-Bedienungsanleitung_FHT|FHT]], [[MAX]], ...)
* [[HMLAN]]: stellt HomeMatic Geräte via Funk bereit
* [[MAX#MAXLAN|MAXLAN]]: stellt [[MAX|MAX!]] Geräte via Funk bereit
* [[PanStamp#panStick.2FShield|panStamp]]: stellt weitere panStamp Geräte via Funk bereit

Dabei wird die Kommunikation in 2 Stufen unterteilt:
* physisches Modul - z.B. 00_CUL.pm - zuständig für die physikalische Kommunikation mit der Hardware. Empfangene Daten müssen einem logischen Modul zugeordnet werden.
* logische Modul(e) - z.B. 10_FS20.pm - interpretiert protokollspezifische Nachrichten. Sendet protokollspezifische Daten über das physische Modul an die Hardware.

<u>physisches Modul</u>

Das physische Modul öffnet die Datenverbindung zum Gerät (z.B. CUL) und verarbeitet sämtliche Daten. Es kümmert sich um den Erhalt der Verbindung (bsp. durch Keep-Alives) und konfiguriert das Gerät so, dass eine Kommunikation mit allen weiteren Geräten möglich ist (bsp. Frequenz, Modulation, Kanal, etc.).

Empfangene Nutzdaten werden über die Funktion [[DevelopmentModuleAPI#Dispatch|Dispatch()]] an logische Module weitergegeben.

Das Modul stellt eine [[#Die_Match-Liste|Match-Liste]] bereit, anhand FHEM die Nachricht einem Modul zuordnen kann, sofern dieses noch nicht geladen sein sollte. FHEM lädt dann automatisch dieses Modul nach, zwecks Verarbeitung der Nachricht. Anhand einer bereitgestellten [[#Die_Client-Liste|Client-Liste]] kann FHEM feststellen, welche logischen Module mit diesem Modul kommunizieren können.

Das Modul stellt eine [[#X_Write|Write]]-Funktion zur Verfügung, über die logische Module Daten an die Hardware übertragen können.

<u>logisches Modul</u>

Das logische Modul interpretiert die Nachricht über eine bereitgestellte [[#X_Parse|Parse]]-Funktion und erzeugt entsprechende Readings/Events. Es stellt über <code>set</code>-/<code>get</code>-Kommandos Steuerungsmöglichkeiten dem Nutzer zur Verfügung.

Es stellt FHEM einen [[#Der_Match-Ausdruck|Match-Ausdruck]] zur Verfügung anhand FHEM ermitteln kann, ob die Nachricht durch das logische Modul verarbeitet werden kann.

=== Die Client-Liste ===

Die Client-Liste ist eine Auflistung von Modulnamen (genauer: regulären Ausdrücken die auf Modulnamen passen) die in einem physischen Modul gesetzt ist. Damit wird definiert, mit welche logischen Modulen das physikalische Modul kommunizieren kann.

Eine Client-Liste ist eine Zeichenkette, welche aus allen logischen Modulnamen besteht. Die einzelnen Namen werden durch einen Doppelpunkt getrennt. Anstatt kompletter Modulnamen können auch reguläre Ausdrücke verwendet werden, die auf mehrere Modulnamen passen.

Bsp.: Die Client-Liste von dem Modul CUL lautet daher wie folgt:

FS20:FHT.*:KS300:USF1000:BS:HMS:CUL_EM:CUL_WS:CUL_FHTTK:CUL_HOERMANN:ESA2000:CUL_IR:CUL_TX:Revolt:IT:UNIRoll:SOMFY:STACKABLE_CC:CUL_RFR:CUL_TCM97001:CUL_REDIRECT

Alle hier aufgelisteten Module können über das Modul CUL Daten empfangen bzw. senden.

Die Client-Liste hat generell folgende Funktion:
* Die Funktion [[DevelopmentModuleAPI#Dispatch|Dispatch()]] prüft nur Module, welche in der Client-Liste enthalten sind, ob diese die Nachricht verarbeiten können.
* Die Funktion [[DevelopmentModuleAPI#AssignIoPort|AssignIoPort()]] prüft anhand sämtlicher Client-Listen in FHEM, welches IO-Gerät für ein logisches Gerät nutzbar ist.

Üblicherweise wird die Client-Liste in der [[#X_Initialize|Initialize]]-Funktion im Modul-Hash gesetzt:

<source lang="perl">
sub X_Initialize($)
{
my ($hash) = @_;
...
$hash->{Clients} = "FS20:KS300:FHT.*";
}
</source>

Man kann die Client-Liste jedoch auch pro physikalisches Gerät setzen. Eine gesetzte Client-Liste in einem Gerät hat immer Vorrang vor der Liste im Modul-Hash. Eine gerätespezifische Client-Liste wird dann verwendet, wenn bspw. ein Gerät je nach Konfiguration nur bestimmte logische Module bedienen kann. Bspw. kann ein CUL je nach RF-Einstellungen FS20, uvm. oder nur HomeMatic bedienen. In einem solchen Fall wird die Client-Liste im Geräte-Hash gesetzt:

<source lang="perl">
sub X_Define($$)
{
my ( $hash, $def ) = @_;
...
$hash->{Clients} = "CUL_HM";
}
</source>

In vielen Modulen, welche nach dem zweistufigem Konzept arbeiten, beginnt und endet die Client-Liste mit einem Doppelpunkt. Dies ist ein historisches Überbleibsel, da der Prüfmechanismus die Client-Liste früher auf das Vorhandensein von <code>'''<u><font color="red">:</font></u>'''<Modulname>'''<u><font color="red">:</font></u>'''</code> prüfte. Dies ist nun nicht mehr notwendig. Die einzelnen Modulnamen müssen lediglich durch einen Doppelpunkt getrennt werden.

=== Die Match-Liste ===
{{Randnotiz|RNTyp=Info|RNText=<font color="red"><u>'''ACHTUNG''':</u></font>
Sämtliche regulären Ausdrücke in der Match-Liste werden "case insensitive" überprüft. Das bedeutet, dass Groß-/Kleinschreibung nicht berücksichtigt wird.

Um dennoch in einem regulären Ausdruck auf Groß-/Kleinschreibung zu prüfen, kann man dieses mit dem Modifizierer <code>(?-i)</code> wieder aktivieren:

<source lang="perl">
my %matchListFHEMduino = (
....
"5:FHEMduino_PT2262" => "^(?-i)IR.*\$",
....
"13:IT" => "^(?-i)i......\$",
);
</source>

Siehe dazu Forumsbeitrag: {{Link2Forum|Topic=33422}}
}}
Die Match-Liste ordnet eine Nachrichtensyntax (regulärer Ausdruck) einem Modulnamen zu und wird in einem physikalischen Modul gesetzt. Sollte eine Nachricht vom physikalischen Gerät empfangen werden, die durch kein geladenes Modul verarbeitet werden kann, so wird über die Match-Liste geprüft, welches Modul diese Nachricht verarbeiten kann. Dieses Modul wird anschließend geladen und die Nachricht durch dieses verarbeitet. In dieser Liste findet mittels regulärem Ausdruck eine Zuordnung der Nachrichtenstruktur zum verarbeitenden logischen Modul statt.

Diese Liste wird ausschließlich in der [[DevelopmentModuleAPI#Dispatch|Dispatch()]]-Funktion verwendet. Sollte keine passendes Modul, welches bereits geladen ist, zur Verarbeitung einer Nachricht gefunden werden, so wird mithilfe der Match-Liste aufgrund der vorliegenden Nachricht das entsprechende Modul ermittelt. Dieses Modul wird dann direkt geladen und die Nachricht wird via [[#X_Parse|Parse]]-Funktion verarbeitet.

Die Match-Liste ist eine Zuordnung von einem Sortierpräfix + Modulname zu einem regulären Ausdruck:

<source lang="perl">
{
"1:FS20" => "^81..(04|0c)..0101a001",
"2:KS300" => "^810d04..4027a001",
"3:FHT" => "^81..(04|09|0d)..(0909a001|83098301|c409c401).."
}
</source>

Das Sortierpräfix dient als Sortierhilfe um so die Reihenfolge der Prüfung festzulegen. Bei der Prüfung wird der Hash mittels sort() sortiert und die regulären Ausdrücke werden dann nacheinander getestet. Daher sollten die präzisesten Ausdrücke immer zuerst getestet werden, sofern es weniger präzise Ausdrücke in der Match-Liste gibt. Dabei ist zu beachten, dass der Sortierpräfix nicht nach numerischen Regeln sortiert wird, sondern basierend auf der Zeichenreihenfolge.

Üblicherweise wird die Match-Liste in der [[#X_Initialize|Initialize]]-Funktion im Modul-Hash gesetzt:

<source lang="perl">
sub X_Initialize($)
{
my ($hash) = @_;

...

$hash->{MatchList} = { "1:FS20" => "^81..(04|0c)..0101a001",
"2:KS300" => "^810d04..4027a001",
"3:FHT" => "^81..(04|09|0d)..(0909a001|83098301|c409c401).." };
}
</source>

Man kann die Match-Liste, ähnlich wie bei der Client-Liste, auch pro physikalisches Gerät setzen. Dabei hat auch hier die Match-Liste eines Gerätes immer Vorrang vor der Match-Liste aus dem Modul-Hash:

<source lang="perl">
sub X_Define($$)
{
my ($hash, $def) = @_;

...

$hash->{MatchList} = { "1:CUL_HM" => "^A...................." };
}
</source>

=== Der Match-Ausdruck ===

Ein Match-Ausdruck wird in einem logischen Modul gesetzt und dient der Prüfung, ob eine Nachricht durch das eigene Modul via [[#X_Parse|Parse]]-Funktion verarbeitet werden kann. Es handelt sich hierbei um einen einzelnen regulären Ausdruck, den FHEM innerhalb der [[DevelopmentModuleAPI#Dispatch|Dispatch()]]-Funktion prüft. Nur wenn eine Nachricht via Dispatch() auf diesen Audruck matcht, wird die Parse-Funktion aufgerufen um die Nachricht zu verarbeiten.

Der Hintergrund, warum man den Aufruf mit einem solchen Ausdruck vorher abprüft, liegt in der Möglichkeit, dass ein physikalisches Modul mehrere unterschiedliche logische Module ansprechen kann. So kann FHEM jedes geladene Modul durch diesen Match-Ausdruck prüfen, ob es diese Nachricht verarbeiten kann. Erst, wenn alle geladenen Module, aufgrund einer Prüfung des Ausdrucks, die Nachricht nicht verarbeiten können, wird via [[#Die_Match-Liste|Match-Liste]] ermittelt, welches Modul geladen werden muss um die Nachricht zu verarbeiten.

Der Match-Ausdruck wird in der [[#X_Initialize|Initialize]]-Funktion zur Verfügung gestellt:

<source lang="perl">
sub X_Initialize($)
{
my ($hash) = @_;

...

# Dieses Modul verarbeitet FS20 Nachrichten
$hash->{Match} = "^81..(04|0c)..0101a001";
}
</source>
=== Die vollständige Implementierung ===

Hier nun eine Zusammenfassung beim zweistufigen Modulkonzept in der jeweiligen Stufe implementiert werden muss, damit die Kommunikation funktioniert.

==== physisches Modul ====

Das physische Modul, welches als Kommunikationsbrücke zwischen der Hardware und logischen Modulen fungieren wird, sollte mindestens folgende Funktionen implementieren:

* [[#X_Initialize|Initialize]]-Funktion - Zum Registrieren des Moduls in FHEM.
* [[#X_Define|Define]]-Funktion - Zum öffnen der Datenverbindung zur Hardware (IP-Adresse/serielle Schnittstelle/...).
* [[#X_Read|Read]]-Funktion - Zum Lesen von Daten, welche die Hardware übermittelt.
* [[#X_Read|Ready]]-Funktion - Zum Wiederaufbau der Verbindung bei Verbindungsabbruch, bzw. Prüfung auf lesbare Daten bei serieller Schnittstelle unter Windows.
* [[#X_Write|Write]]-Funktion - Zum Senden von Daten, welche logische Module via [[DevelopmentModuleAPI#IOWrite|IOWrite()]] an die Hardware übertragen möchten.
* [[#X_Undef|Undef]]-Funktion - Schließen der Verbindung zur Hardware beim Löschen via <code>delete</code> bzw. <code>rereadcfg</code>.
* [[#X_Shutdown|Shutdown]]-Funktion - Schließen der Verbindung zur Hardware beim Stopp von FHEM via <code>shutdown</code>.

Desweiteren müssen in der [[#X_Initialize|Initialize]]-Funktion folgende Daten bereitgestellt werden:

* [[#Die_Client-Liste|Client-Liste]] - Auflistung aller logischen Module, die über dieses Modul kommunizieren können
* [[#Die_Match-Liste|Match-Liste]] - Zuordnung von Nachrichtensyntax zu Modul zwecks Autoload-Funktionalität.

==== logisches Modul ====

Das logische Modul, bildet ein einzelnes Gerät ab, über das mit einem physikalisches Modul kommuniziert werden kann. Es sollte mindestens folgende Funktionen implementieren:

* [[#X_Initialize|Initialize]]-Funktion - Zum Registrieren des Moduls in FHEM.
* [[#X_Define|Define]]-Funktion - Speichern des Definition Pointers (siehe [[#X_Parse|Parse-Funktion]])
* [[#X_Parse|Parse]]-Funktion - Zum Lesen von Daten, welche die Hardware übermittelt.
* [[#X_Undef|Undef]]-Funktion - Löschen des Definition Pointers beim Löschen via <code>delete</code> bzw. <code>rereadcfg</code>.

Desweiteren müssen in der [[#X_Initialize|Initialize]]-Funktion folgende Daten bereitgestellt werden:

* [[#Der_Match-Ausdruck|Match-Ausdruck]] - Prüfausdruck, ob eine Nachricht durch dieses Modul verarbeitet werden kann.

=== Kommunikation von der Hardware bis zu den logischen Modulen ===

Die Gerätedefinition eines physische Moduls öffnet eine Verbindung zur Hardware. Die [[#X_Read|Read]]-Funktion wird bei anstehenden Daten aus der Hauptschleife von fhem.pl aufgerufen.

Die Read-Funktion stellt dabei sicher, dass die Daten
* komplett (in der Regel über einen internen Puffer in <code>$hash</code>) und
* korrekt (z.B. via Prüfung mittels regulärem Ausdruck)
sind und ruft die globale Funktion [[DevelopmentModuleAPI#Dispatch|Dispatch()]] mit einer kompletten Nachricht auf.

Die Funktion Dispatch() sucht nach einer passenden Definition via [[#Die_Client-Liste|Client-Liste]] in physischen Definitionen/Modulen nach möglichen logischen Modulen zur Verarbeitung. Alle zum Zeitpunkt geladenen Module, die in der Client-Liste aufgeführt sind, werden über den [[#Der_Match-Ausdruck|Match-Ausdruck]] geprüft, ob sie mit der Nachricht etwas anfangen können. Sollte bei einem Modul der Match-Ausdruck passen, so wird die entsprechende [[#X_Parse|Parse]]-Funktion des logischen Moduls aufgerufen. Sofern keine passendes Modul gefunden wurde, um die Nachricht zu verarbeiten, wird in der [[#Die_Match-Liste|Match-Liste]] im Geräte- bzw. Modul-Hash der physischen Gerätedefinition nach dem passenden Modul gesucht. Sollte es darin ein Modul geben, was diese Art von Nachricht verarbeiten kann, so wird versucht dieses Modul zu laden um nun die Nachricht via Parse-Funktion zu verarbeiten. Es erfolgt in diesem Fall keine Vorprüfung durch den Match-Ausdruck.

Durch Dispatch() wird nun die [[#X_Parse|Parse]]-Funktion des gefundenen logischen Moduls aufgerufen. Diese
* interpretiert die übergebene Nachricht,
* versucht eine existierende Gerätedefinition in FHEM zu finden (z.B. mittels Definition Pointer), für welche die Nachricht addressiert ist,
* setzt alle [[#Readings|Readings]] für die gefundene Gerätedefinition via [[DevelopmentModuleAPI#Readings_.2F_Events|readings*update]]()-Funktionen,
* gibt den Namen der logischen Definition zurück, welche die Nachricht verarbeitet hat.

Sollte keine passende Gerätedefinition für die entsprechende Nachricht existieren (Adresse/ID/Kanal/...), wird der Gerätename "UNDEFINED" inkl. einem passenden <code>define</code>-Statement zurückgegeben, um die Definition durch [[autocreate]] erzeugen zu lassen.

Es findet während der Verarbeitung einer Nachricht durch Dispatch()/Parse-Funktion keine sofortige Eventverarbeitung (via [[DevelopmentModuleAPI#Dispatch|DoTrigger()]]) statt, wenn die [[DevelopmentModuleAPI#Readings_.2F_Events|readings*update]]()-Funktionen verwendet werden.
(Im Gegensatz zum direkten Aufrufen der readings*update Funktionen ohne vorhergehendes Dispatch() )

Die Funktion Dispatch() triggert das Event-Handling für das von der Parse-Funktion zurückgegebene logische Device selbstständig.

Optional führt die Funktion Dispatch() eine Überprüfung auf Nachrichtenduplikate beim Einsatz von mehreren IO-Geräten durch. Dazu wird eine implementierte [[#X_Fingerprint|Fingerprint]]-Funktion im physischen oder logischen Modul benötigt.

=== Kommunikation von den logischen Modulen bis zur Hardware ===

Um von einem logischen Modul eine Nachricht an die Hardware senden zu können, muss zunächst im logischen Gerät ein passenden IO-Gerät ausgewählt sein. Dazu muss die Funktion [[DevelopmentModuleAPI#AssignIoPort|AssignIoPort()]] ein entsprechendes IO-Gerät auswählen und in <code>$hash->{IODev}</code> setzen. Dieser Aufruf wird üblicherweise in der [[#X_Define|Define]]-Funktion des logischen Moduls ausgeführt. Erst, wenn ein IO-Gerät ausgewählt wurde, können Daten über das physikalische Gerät an die Hardware übermittelt werden.

Zum Senden von Daten ruft das logische Modul die Funktion [[DevelopmentModuleAPI#IOWrite|IOWrite()]] samt Daten auf. Diese ruft für das entsprechende IO-Gerät die [[#X_Write|Write]]-Funktion auf und übergibt die Daten zum Schreiben an das physikalische Modul. Die Write-Funktion kümmert sich nun um die Übertragung der Daten an die Hardware.

Keine direkten Zugriffe zwischen dem logischen und dem physischen Gerät gibt (d.h. keine direkten Aufrufe von Funktionen, kein direktes Überprüfen von <code>$hash</code>-Inhalten, ...), so können die Module hintereinander geschaltet werden (z.B. für Routerfunktionen wie bei der [[RFR_CUL|RFR]]-Funktionalität) oder mittels [[FHEM2FHEM]] im RAW-Modus zwei FHEM-Installationen verbunden werden und die logischen Geräte können dennoch kommunizieren.

=== Automatisches Anlegen von logischen Gerätedefinitionen (autocreate) ===

Das logische Modul kann im Rahmen der [[#X_Parse|Parse]]-Funktion eine neue Gerätedefinition anlegen, sofern eine passende Definition nicht existieren sollte. Die Parse-Funktion gibt generell den Namen der logischen Gerätedefinition zurück, für welche die Nachricht verarbeitet wurde. Sollte keine passende Definition gefunden werden, so muss die Parse-Funktion folgenden Rückgabewert liefern (zusammenhängende Zeichenkette):

UNDEFINED ''<Namensvorschlag>'' ''<Modulname>'' ''<Define-Parameter>''

Sollte also bspw. im Rahmen der Parse-Funktion zu Modul X eine Nachricht nicht einer existierenden Gerätedefinition zugeordnet werden können, so muss ein Namensvorschlag erstellt werden der eine eindeutige Komponente wie bspw. eine Adresse/ID/Kanal-Nr enthält. In der Regel wird hier immer der Modulname zusammen mit der eindeutigen Komponente, durch einen Unterstrich getrennt, verwendet (Bsp: <code>X_4834</code>). Der Modulname ist in der Regel immer der, des eigenen Moduls. In besonderen Fällen kann man hier auch einen abweichenden Modulnamen angeben. Dies wird bspw. bei den [[PanStamp#FHEM-Module.2FDevice_Definition_Files|SWAP-Modulen]] eingesetzt. Als Define-Parameter müssen alle notwendigen Parameter angegeben werden, die beim Aufruf des <code>define</code>-Befehls notwendig sind, damit eine neu angelegte Gerätedefinition Nachrichten zu dieser eindeutigen Adresse Daten verarbeitet. Dazu muss mind. die eindeutige Adresse mitgegeben werden.

Beispiel für FS20:

UNDEFINED FS20_0ae42f8 FS20 0ae42 f8

Sobald [[DevelopmentModuleAPI#Dispatch|Dispatch()]] einen solchen Rückgabewert von einer [[#X_Parse|Parse]]-Funktion erhält, wird diese Zeichenkette so wie sie ist via [[DevelopmentModuleAPI#DoTrigger|DoTrigger()]] als Event für die Definition <code>global</code> getriggert.

Sofern der Nutzer das Modul [[autocreate]] verwendet (definiert hat), kümmert sich dieses nun um das Anlegen einer entsprechenden Gerätedefinition. Es lauscht dabei auf generierte Events der Definition <code>global</code> via [[#X_Notify|Notify]]-Funktion. Der Nutzer kann dabei das Verhalten von autocreate durch entsprechende Parameter beeinflussen.

Das Modul, für welches autocreate eine neue Definition anlegen möchte, kann das Verhalten durch entsprechende Parameter im Modul-Hash beeinflussen. Dabei gilt, dass gesetzte Attribute durch den Nutzer generell Vorrang haben. Die entsprechenden Parameter werden dabei im Rahmen der [[#X_Initialize|Initialize]]-Funktion im Modul-Hash gesetzt:

<source lang="perl">
sub X_Initialize($)
{
my ($hash) = @_;

...

$hash->{AutoCreate} = {"X_.*" => { ATTR => "event-on-change-reading:.* event-min-interval:.*:300",
FILTER => "%NAME",
GPLOT => "temp4hum4:Temp/Hum,",
autocreateThreshold => "2:140"
}
};

}
</source>

Hierbei wird unterhalb von <code>$hash->{AutoCreate}</code> eine Liste angelegt, wo einem regulären Ausdruck für einen anzulegenden Definitionsnamen entsprechende Optionen zugeordnet werden. Sobald durch autocreate eine Gerätedefintion angelegt wird, auf den ein hier gelisteter Ausdruck matcht, so werden die zugeordneten Optionen berücksichtigt.

Hier eine Auflistung aller möglichen Optionen und ihrer Bedeutung:

{| class="wikitable"
|-
! Optionsname !! Beispiel !! Bedeutung
|-
| <code>ATTR</code>|| <code>"event-on-change-reading:.* event-min-interval:.*:300"</code> || Eine Auflistung von Attributen, die nach dem Anlegen einer Definition zusätzlich gesetzt werden. Es handelt sich hierbei um eine Leerzeichen-separierte Liste von Doppelpunkt-getrennten Tupels mit Attributname und -wert.

Für das dargestellte Beispiel bedeutet dies, dass nach dem Anlegen der Definition folgende FHEM-Befehle zusätzlich ausgeführt werden:

attr ''<Name>'' event-on-change-reading .*
attr ''<Name>'' event-min-interval .*:300

|-
| <code>FILTER</code> || <code>%NAME</code>|| Sofern in der autocreate-Definiton das Attribut <code>filelog</code> entsprechend durch den Nutzer gesetzt ist, wird eine zugehörige FileLog-Definition angelegt. Diese Option setzt den dabei benutzten Filter-Regexp, der beim Anlegen der FileLog-Definition gesetzt wird.

Dabei werden folgende Platzhalter durch die entsprechenden Werte der neu angelegten Gerätedefinition ersetzt:

* <code>%NAME</code> - wird ersetzt durch den Definitionsnamen
* <code>%TYPE</code> - wird ersetzt durch den Modulnamen
|-
| <code>GPLOT</code> || <code>"temp4hum4:Temp/Hum,"</code> || Sofern eine FileLog-Definition angelegt wurde, kann man weiterführend dazu eine passende SVG-Definition erzeugen um Daten aus dem erzeugten FileLog zu visualisieren. Ein typischer Fall sind hierbei Temperatursensoren, wo es sinnvoll sein kann, einen passenden SVG-Plot mit Temperatur/Luftfeuchtigkeit direkt anzulegen.

Es handelt sich hierbei um eine kommaseparierte Auflistung von gplot-Dateinamen und optionalen Label-Texten durch einen Doppelpunkt getrennt. Im genannten Beispiel entspricht <code>temp4hum4</code> der zu verwendenden GnuPlot-Datei und <code>Temp/Hum</code> dem zu verwendenden Label ([[SVG]] Attribut <code>label</code>). Das Label wird auch durch FileLog verwendet als Link-Text zum entsprechenden SVG Plot. Alternativ kann auch nur die entsprechende GnuPlot-Datei anegeben werden ohne Label. Für jede angegebene GnuPlot-Datei wird anschließend eine entsprechende SVG-Definition erzeugt mit der vorher erzeugten FileLog-Definition als Datenquelle.

Der gesamte Inhalt der <code>GPLOT</code>-Option wird beim Anlegen einer FileLog-Definition dem Attribut <code>logtype</code> als Wert plus dem Text <code>text</code> zugewiesen. Daher muss der Inhalt der Option <code>GPLOT</code> immer mit einem Komma enden.

|-
| <code>autocreateThreshold</code>|| <code>"2:10"|| Definiert, wie viele Aufrufe (im Bsp: <code>2</code>) von autocreate innerhalb welcher Zeit (im Bsp: <code>10</code> Sek.) stattfinden müssen, bevor die Gerätedefinition tatsächlich durch autocreate angelegt wird. Dadurch kann das ungewollte Anlegen von Geräten verhindert werden die tatsächlich nicht in Echt existieren. Aufgrund von Funkstörungen kann es durchaus zum ungewollten Anlegen einer Definition kommen. Diese Funktion lässt eine Definition erst zu wenn innerhalb einer vorgegeben Zeit eine Mindestzahl an Nachrichten eintrifft.

Die erste Zahl stellt dabei die Mindestanzahl an Nachrichten dar. Die Zweite Zahl stellt die Zeit in Sekunden dar, in der die Mindestanzahl an Nachrichten erreicht werden muss um eine entsprechende Gerätedefinition anzulegen.

Sofern diese Option nicht gesetzt ist, wird standardmäßig <code>2:60</code> verwendet.

Diese Option kann durch den Anwender über das Attribut <code>autocreateThreshold</code> übersteuert werden.

Sofern diese Option nicht gesetzt ist
|-
| <code>noAutocreatedFilelog</code>|| <code>1</code>|| Flag. Sofern gesetzt, wird keine FileLog- und ggf. SVG-Definition erzeugt. Selbst wenn der Nutzer durch entsprechende Attribute das Anlegen wünscht. Diese Option ist sinnvoll für Module bzw. Geräte die keine Readings erzeugen.
|}

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

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

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

== "Hello World" Beispiel ==

98_Hello.pm

<source lang="perl">
package main;
use strict;
use warnings;

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

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

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

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

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

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

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

return undef;
}

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

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

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

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

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

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

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

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

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

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

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

1;

=pod
=begin html

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

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

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

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

=end html

=cut
</source>

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

== Noch zu beschreiben ==
* DevIO
* AsyncOutputFn / asyncOutput

[[Kategorie:Development]]

DevelopmentModuleIntro

2017-02-16T19:42:07Z

Kaihs: /* X_Notify */

{{Hinweis|Dieser Text ist in Arbeit und muss noch an einigen Stellen ergänzt werden. }}

== Einleitung ==

Um neue Geräte, Dienste, o.ä. in FHEM verfügbar zu machen, kann man ein eigenes Modul in Perl schreiben. Ein Modul wird in FHEM automatisch geladen, wenn ein entsprechendes Device in FHEM definiert wird. Das Modul ermöglicht eine spezifische Kommunikation mit einem physikalischen Gerät, stellt Ergebnisse ("Readings") und Events innerhalb von FHEM zur Verfügung und erlaubt es, das Gerät mit "Set"-/"Get"-Befehlen zu beeinflussen. Dieser Artikel soll den Einstieg in die Entwicklung eigener Module erleichtern.

Mit dem FHEM-Befehl <code>define</code> werden Devices in FHEM basierend auf einem Modul definiert. Dieser Befehl sorgt dafür, dass ein neues Modul bei Bedarf geladen und initialisiert wird. Ein gutes Beispiel ist hierbei die zentrale Konfigurationsdatei "fhem.cfg" in der sämtliche Devices in Form von <code>define</code>-Statements gespeichert sind.

Damit das funktioniert müssen der Name des Moduls und der Name der [[#X_Initialize|Initialisierungsfunktion]] identisch sein. Das folgende Beispiel soll dies verdeutlichen:

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

In fhem.pl wird der define-Befehl verarbeitet und geprüft, ob ein Modul mit dem Namen "JeeLink" schon geladen ist und falls nicht ein Modul mit Namen XY_JeeLink.pm im Modulverzeichnis (z.B. /opt/fhem/FHEM) gesucht und dann geladen.
Danach wird die Funktion <code>''JeeLink''_Initialize()</code> aufgerufen um das Modul in FHEM zu registrieren. Eine Moduldatei muss dazu eine Funktion <code>''<Modulname>''_Initialize()</code> enthalten. Durch den Aufruf dieser Funktion wird FHEM mitgeteilt, welche Funktionalitäten dieses Modul unterstützt.

In der Initialisierungsfunktion des Moduls werden die Namen aller weiteren Perl-Funktionen des Moduls, die von fhem.pl aus aufgerufen werden, bekannt gemacht. Dazu wird für jedes Modul ein eigener Hash (genauer "Modul-Hash") mit entsprechenden Werten gefüllt, der in fhem.pl für jedes Modul entsprechend abgelegt wird. Dadurch weiß FHEM wie dieses Modul anzusprechen ist.

== Grundlegender Aufbau eines Moduls ==

=== Dateiname ===

Ein FHEM-Modul wird als Perl-Modul mit der Dateiendung *.pm abgespeichert. Der Dateiname folgt dabei folgendem Schema:

:<code>''['''Schlüsselnummer''']''<font color="grey">_</font>''['''Modulname''']''<font color="grey">.pm</font></code>

* '''Schlüsselnummer''' - Eine zweistellige Zahl zwischen 00 - 99. Die Schlüsselnummer hat aktuell keine technische Relevanz mehr. In früheren FHEM-Versionen ist sie relevant für [[#Zweistufiges_Modell_f.C3.BCr_Module|zweistufige Module]] (Reihenfolge für [[DevelopmentModuleAPI#Dispatch|Dispatch()]] um logische Module zu prüfen). Die allgemeine Empfehlung ist hierbei eine Schlüsselnummer eines Moduls zu verwenden, welches eine ähnliche Funktionalität bietet. Die Schlüsselnummer 99 hat hierbei eine besondere Bedeutung, da alle Module mit dieser Schlüsselnummer beim Start von FHEM automatisch geladen werden, selbst, wenn sie in der Konfiguration nicht verwendet werden. Daher wird für myUtils 99 als Schlüsselnummer verwendet (99_myUtils.pm). Module mit der Schlüsselnummer 99 werden im SVN nicht akzeptiert (siehe [[SVN Nutzungsregeln]])
* '''Modulname''' - Der Name des Moduls wie er in FHEM bei dem Anlegen einer Gerätedefinition zu verwenden ist. Der Modulname sollte nur aus den folgenden möglichen Zeichen bestehen: Groß-/Kleinbuchstaben, Zahlen sowie Unterstrich (_)

=== Inhaltlicher Aufbau ===

Ein Modul ist inhaltlich in folgende Abschnitte unterteilt:

<source lang="perl">
#
# 72_MYMODULE.pm
#

package main;

# Laden evtl. abhängiger Perl- bzw. FHEM-Module
use HttpUtils;
use [...]

# FHEM Modulfunktionen

sub MYMODULE_Initialize() {
...
}

sub MYMODULE_Define() {
...
}

...

# Eval-Rückgabewert für erfolgreiches
# Laden des Moduls
1;

# Beginn der Commandref

=pod
=item [helper|device|command]
=item summary Kurzbeschreibung in Englisch was MYMODULE steuert/unterstützt
=item summary_DE Kurzbeschreibung in Deutsch was MYMODULE steuert/unterstützt

=begin html
Englische Commandref in HTML
=end html

=begin html_DE
Deustche Commandref in HTML
=end html

# Ende der Commandref
=cut
</source>

Man kann hierbei von folgender Reihenfolge sprechen:

# Perl-Code, welcher das Modul implementiert
# Die Zeile <code>1;</code> nachdem der Perl-Code abgeschlossen ist. Dies dient FHEM der Erkennung, dass das Modul erfolgreich und vollständig geladen wurde. Sollte diese Zeile nicht enthalten sein, wird FHEM beim Laden des Moduls die Fehlermeldung <code>Error:Modul 72_MYMODULE deactivated</code> in das Logfile schreiben.
# Commandref zur Dokumentation des Moduls. Diese Dokumentation soll dem User die möglichen Befehle/Attribute/Readings/Events vermitteln. Weitere Informationen und Hinweise findet man in den [[Guidelines zur Dokumentation]].

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

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

In fhem.pl werden alle Gerätedefinitionen in dem globalen Hash <code>%defs</code> abgelegt. Der Inhalt von <code>$defs{''<Name>''}</code> in fhem.pl verweist dabei auf den Hash der Geräteinstanz in Form einer Hashreferenz. Diesen Verweis (also nur die Adresse) bekommen die Funktionen eines Moduls übergeben (i.d.R. als <code>$hash</code> bezeichnet), welche direkt von fhem.pl aufgerufen werden. In dem Hash stehen beispielsweise die internen Werte des Geräts, die im Frontend als "Internals" angezeigt werden, sowie die Readings des Geräts.

Beispiele:
*<code>$hash->{NAME}</code> enthält den Namen der Geräteinstanz,
*<code>$hash->{TYPE}</code> enthält die Typbezeichnung des Geräts (Modulname)

==Ausführung von Modulen==
FHEM arbeitet intern nicht parallel, sondern arbeitet alle Aufgaben seriell nacheinander kontinuierlich ab. Daher wäre es ungünstig, wenn Module Daten von einem physikalischen Gerät abfragen wollen und dabei innerhalb der selben Funktion auf die Antwort des Geräts warten. In dieser Zeit, in der FHEM auf die Antwort des Gerätes warten muss, wäre der Rest von FHEM blockiert. Da immer nur eine Aufgabe zur selben Zeit bearbeitet wird, müssen alle weiteren Aufgaben solange warten. Eine Datenkommunikation innerhalb eines Moduls sollte daher immer ohne Blockierung erfolgen. Dadurch kann FHEM die Wartezeit effizient für andere Aufgaben nutzen um bspw. anstehende Daten für andere Module zu verarbeiten. Es gibt in FHEM entsprechende Mechanismen, welche eine "Non-Blocking"-Kommunikation über verschiedene Wege (z.B. seriell, HTTP, TCP, ...) ermöglichen.

Dafür werden in FHEM zwei zentrale Listen gepflegt, in der die Filedeskriptoren der geöffneten Kommunikatonsverbindungen gespeichert sind. Auf Linux- bzw. Unix-basierten Plattformen wird der select-Befehl des Betriebssystems verwendet um Filedeskriptoren auf lesbare Daten zu überprüfen. In FHEM gibt es dazu eine Liste (<code>%selectlist</code>), in der die Filedeskriptoren sämtlicher Geräte (z.B. serielle Verbindung, TCP-Verbindung, etc.) gespeichert sind.

In der zentralen Schleife (Main-Loop) von fhem.pl wird mit <code>select()</code> überwacht, ob über eine der geöffneten Schnittstellen Daten zum Lesen anstehen. Wenn dies der Fall ist, dann wird die Lesefunktion ([[#X_Read|X_Read]]) des zuständigen Moduls aufgerufen, damit es die Daten entgegennimmt und verarbeitet. Anschließend wird die Schleife weiter ausgeführt.

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

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

Auch wenn von einem Anwender über einen Get-Befehl Daten aktiv von einem Gerät angefordert werden, sollte nicht blockierend gewartet werden. Eine asynchrone Ausgabe, sobald das Ergebnis vorliegt, ist über [[DevelopmentModuleAPI#asyncOutput|asyncOutput()]] möglich. Siehe {{Link2Forum|Topic=43771|Message=357870|LinkText=Beschreibung}} und {{Link2Forum|Topic=43771|Message=360935|LinkText=Beispiel}}. Weitere Anwendungsbeispiele finden sich im {{Link2Forum|Topic=43052|Message=353477|LinkText=PLEX Modul}} und im überarbeiteten und nicht-blockierenden {{Link2Forum|Topic=42771|Message=348498|LinkText=SYSSTAT Modul}}.

== Wichtige globale Variablen aus fhem.pl ==

FHEM arbeitet mit einer Vielzahl an internen Variablen. Die nun folgenden aufgelisteten Variablen sind die wichtigsten, welche man im Rahmen der Modulprogrammierung kennen sollte:

{| class="wikitable"
|-
! Variable !! Beschreibung
|-
| <code>$init_done</code> || Dient der Erkennung für fhem.pl sowie den Modulen, ob FHEM den Initialisierungsvorgang abgeschlossen hat. Beim Starten von FHEM ist <code>$init_done</code> gleich <code>0</code>. Erst, wenn das Einlesen der Konfiguration, sowie des State-Files (Readings) abgeschlossen ist, wird <code>$init_done</code> auf <code>1</code> gesetzt.
Das gleiche Verfahren wird auch bei dem Befehl <code>rereadcfg</code> angewandt. Während <code>rereadcfg</code> ausgeführt wird (Konfiguration löschen, neu einlesen), ist <code>$init_done</code> gleich <code>0</code>.

Dies ist insbesondere in der [[#X_Define|Define]]-Funktion eines Moduls relevant.
|-
| <code>%attr</code> || In <code>%attr</code> werden sämtliche gesetzten Attribute aller Geräte gespeichert. Diese Datenstruktur wird generell durch den <code>attr</code>-Befehl verwaltet. Hierbei wird einem Gerätenamen eine Mehrzahl an Attributnamen mit einem Wert zugeordnet. Attribut-Inhalte können über die Funktion [[DevelopmentModuleAPI#AttrVal|AttrVal()]] ausgelesen werden.
|-
| <code>%cmds</code> || In <code>%cmds</code> wird jedem in FHEM existierendem Befehl die entsprechende Funktion zugewiesen, welche diesen Befehl umsetzt. Module können durch das Eintragen eines Befehlsnamen samt Funktion in <code>%cmds</code> über die [[#X_Initialize|Initialize]]-Funktion eines Moduls einen (oder mehrere) eigene Befehle in FHEM registrieren.

Die Struktur ist dabei wiefolgt:

$cmds{''<Befehlsname>''} = { Fn => "''<Funktionsname>''",
Hlp => "''<Aufrufsyntax>''"};

|-
| <code>%data</code>|| Der eigentliche Zweck von <code>%data</code> ist dem Nutzer eine Möglichkeit zum Speichern von temporären Daten im globalen Kontext zu ermöglichen. Einige Module verwenden <code>%data</code> jedoch auch um modul- & geräteübergreifend Daten auszutauschen.
|-
| <code>%defs</code>|| In <code>%defs</code> werden sämtliche Gerätedefinitionen, bzw. die Hash-Referenzen auf diese, gespeichert. Hier ist jedem Gerätenamen eine Hash-Referenz zugeordnet.
|-
| <code>%modules</code>|| In <code>%modules</code> sind alle geladenen Module gelistet mit ihren entsprechenden Initialisierungsdaten (Funktionsnamen, Attribut-Listen, spezielle Einstellungen, ...). Hier wird für jeden Modulname der Modul-Hash aus der [[#X_Initialize|Initialize]]-Funktion gespeichert.
Desweiteren legen viele Module, welche nach dem [[DevelopmentModuleIntro#Zweistufiges_Modell_f.C3.BCr_Module|zweistufigen Modulkonzept]] hier eine Rückwärtszuordnung von Geräteadressen zu Geräte-Hash an.
|-
| <code>%readyfnlist</code>|| In <code>%readyfnlist</code> sind alle zu prüfenden Verbindungen mit ihrer entsprechendem Geräte-Hash gelistet. FHEM prüft alle hier gelisteten Geräte regelmäßig über eine Aufruf der entsprechenden [[#X_Ready|Ready]]-Funktion.

Bei einer Nutzung von dem Hilfsmodul DevIo.pm zum Aufbau einer Kommunikationsverbindung, kümmert sich DevIo selbständig um den entsprechenden Eintrag in <code>%readyfnlist</code>.
|-
| <code>%selectlist</code>|| In <code>%selectlist</code> sind alle geöffneten Verbindungen mit ihrer entsprechendem Geräte-Hash gelistet. FHEM prüft alle hier gelisteten Geräte, ob der geöffnete Filedeskriptor unter <code>$hash->{FD}</code> Daten zum Lesen bereitgestellt hat. Ist dass der Fall, wird die entsprechende [[#X_Read|Read]]-Funktion aufgerufen, um anstehende Daten durch das Modul zu verarbeiten.
Bei einer Nutzung von dem Hilfsmodul DevIo.pm zum Aufbau einer Kommunikationsverbindung, kümmert sich DevIo selbständig um den entsprechenden Eintrag in <code>%selectlist</code>.
|}

Es gibt durchaus viele weitere globale Variablen, die jedoch für sehr spezielle Anwendungsfälle und z.T. nur einzelne Module gedacht sind und daher hier nicht aufgeführt werden.

== Internals ==
Daten, die ein Modul im Geräte-Hash speichert nennt man Internals. Sie werden als Unterstruktur des Hashes der jeweiligen Geräteinstanz gespeichert, beispielswiese <code>$hash->{NAME}</code> für den Gerätenamen, welcher beim Define-Befehl übergeben wurde und als Internal gespeichert wird. Diese Daten spielen für FHEM eine sehr wichtige Rolle, da sämtliche gerätespezifischen Daten als Internal im Gerätehash gespeichert werden.

Falls Werte wie z.B. ein Intervall nicht über den Define-Befehl gesetzt werden sollen und im Betrieb einfach änderbar sein sollten, ist eine alternative Möglichkeit die Speicherung in so genannten Attributen. Dann würde man den Define-Befehl so implementieren, dass er kein Intervall übergeben bekommt und statt dessen das Interval als Attribut über den Befehl <code>attr</code> gesetzt wird.

Generell werden alle Werte, welche direkt in der ersten Ebene von <code>$hash</code> (Gerätehash) gespeichert werden auf der Detail-Seite einer Definition in der FHEMWEB Oberfläche angezeigt. Es gibt jedoch Ausnahmen:

* <code>$hash->{helper}{URL]</code> - Alle Elemente, welche als Unterelement wieder einen Hash besitzen werden nicht in FHEMWEB dargestellt. Typischerweise speichern Module Daten unter <code>$hash->{helper}</code> interne Daten zwischen, die für den User nicht relevant sind, sondern nur der internen Verarbeitung dienen.
* <code>$hash->{'''.'''<font color="grey">ELEMENT</font>}</code> - Alle Knoten, welche mit einem Punkt beginnen werden in der FHEMWEB Oberfläche nicht angezeigt. Man kann diese Daten jedoch beim Aufruf des [[List|list-Kommandos]] einsehen.

Es gibt bereits vorbelegte Internals welche in FHEM dazu dienen definitionsbezogene Informationen wie bspw. Namen und Readings zu speichern. Dies sind im besonderen:

{| class="wikitable"
|-
! style="min-width: 13em;" | Internal !! Beschreibung
|-
| <code>$hash->{NAME}</code> || Der Definitionsname, mit dem das Gerät angelegt wurde.
|-
| <code>$hash->{READINGS}</code> || Enthält alle aktuell vorhandenen Readings. Daten unterhalb dieses Knotens sollte man nicht direkt manipulieren. Um Readings zu Erzeugen gibt es entsprechende [[DevelopmentModuleAPI#Readings_.2F_Events|Reading-Funktionen]].
|-
| <code>$hash->{NR}</code> || Die Positions-Nr. der Definition innerhalb der Konfiguration. Diese dient dazu die Konfiguration in der gleichen Reihenfolge zu speichern, wie die einzelnen Geräte angelegt wurden.
|-
| <code>$hash->{TYPE}</code> || Der Modulname, mit welchem die Definition angelegt wurde.
|-
| <code>$hash->{DEF}</code> || Sämtliche Argumente, welche beim <code>define</code>-Befehl nach dem Modulnamen übergeben wurden.
|-
| <code>$hash->{CFGFN}</code> || Der Dateiname der Konfigurationsdatei in der diese Definition enthalten ist (sofern nicht in fhem.cfg). Dieser Wert ist nur gefüllt, wenn man mit mehreren Konfigurationsdateien arbeitet, welche dann in fhem.cfg via include-Befehl eingebunden werden.
|-
| <code>$hash->{NTFY_ORDER}</code> || Sofern das Modul Events via [[DevelopmentModuleIntro#X_Notify|Notify-Funktion]] verarbeitet enthält jede Definition eine Notify-Order als Zeichenkette bestehend aus dem Notify Order Prefix und dem Definitionsnamen. Details zur Funktionsweise gibt es in der Beschreibung zur [[DevelopmentModuleIntro#X_Notify|Notify-Funktion]] im Abschnitt "Reihenfolge für den Aufruf der Notify-Funktion beeinflussen".
|-
| <code>$hash->{NOTIFYDEV}</code> || Sofern das Modul Events via NotifyFn verarbeitet kann man damit die Definitionen, von denen man Events erhalten will begrenzen. Details zur Funktionsweise gibt es in der Beschreibung zur [[DevelopmentModuleIntro#X_Notify|Notify-Funktion]] im Abschnitt "Begrenzung der Aufrufe auf bestimmte Geräte".
|-
| <code>$hash->{IODev}</code> || Hier wird das zugeordnete IO-Gerät durch [[DevelopmentModuleAPI#AssignIoPort|AssignIoPort()]] gespeichert, welches für den Datentransport und -empfang dieses logischen Gerätes zuständig ist. Dieser Wert existiert nur bei Modulen die nach dem [[DevelopmentModuleIntro#Zweistufiges_Modell_f.C3.BCr_Module|zweistufigen Modulkonzept]] arbeiten.
|-
| <code>$hash->{CHANGED}</code> || Hier werden alle Events kurzzeitig gesammelt, welche für die Eventverarbeitung anstehen. Insbesondere die [[DevelopmentModuleAPI#Readings_.2F_Events|Reading-Funktionen]] speichern hier alle Events zwischen um sie nach Abschluss via [[DevelopmentModuleAPI#DoTrigger|DoTrigger()]] zu verarbeiten.
|-
| <code>$hash->{FD}</code> || Wenn die Definition eine Netzwerkverbindung oder serielle Schnittstelle geöffnet hat (z.B. via DevIo), so wird der entsprechende File-Deskriptor in diesem Internal gespeichert. Damit kann FHEM alle geöffneten Filedeskriptoren der entsprechenden Definition zuordnen um bei ankommenden Daten die Definition via [[DevelopmentModuleIntro#X_Read|Read-Funktion]] damit zu versorgen.
|-
| <code>$hash->{EXCEPT_FD}</code> || Ähnlich wie <code>$hash->{FD}</code>. Sofern die Definition in <code>[[#Wichtige_globale_Variablen_aus_fhem.pl|%selectlist]]</code> eingetragen ist und ein Fildeskriptor in diesem Internal gesetzt ist, wird bei einer auftretenden Exception bzw. Interrupt die [[DevelopmentModuleIntro#X_Except|Except]]-Funktion des entsprechenden Moduls aufgerufen um darauf zu reagieren.
|}

Generell sollte man die meisten der hier genannten systemweiten Internals nicht modifizieren, da ansonsten die korrekte Funktionsweise von FHEM nicht mehr garantiert werden kann.

== Readings ==
Daten, welche von einem Gerät gelesen werden und in FHEM in einer für Menschen verständlichen Form zur Verfügung gestellt werden können, werden Readings genannt. Sie geben den Status des Gerätes wieder und erzeugen Events innerhalb von FHEM auf die andere Geräte reagieren können. Sie werden als Unterstruktur des Hashes der jeweiligen Geräteinstanz gespeichert, beispielsweise
*<code>$hash->{READINGS}{temperature}{VAL}</code> für die Temperatur eines Fühlers
*<code>$hash->{READINGS}{temperature}{TIME}</code> für den Zeitstempel der Messung

Für den lesenden Zugriff auf Readings steht die Funktion <code>[[DevelopmentModuleAPI#ReadingsVal|ReadingsVal()]]</code> zur Verfügung. Ein direkter Zugriff auf die Datenstruktur sollte nicht vorgenommen werden.

Readings werden im Statefile von FHEM automatisch auf der Festplatte zwischengespeichert, damit sie nach einem Neustart sofort wieder zur Verfügung stehen. Dadurch ist der letzte Status eines Gerätes vor einem Neustart nachvollziehbar.

Readings, die mit einem Punkt im Namen beginnen, haben eine funktionale Besonderheit. Sie werden im FHEMWEB nicht angezeigt und können somit als "Permanentspeicher" für kleinere Daten innerhalb des Moduls genutzt werden. Um größere Datenmengen permanent zu speichern sollte man jedoch die Funktion <code>[[DevelopmentModuleAPI#setKeyValue|setKeyValue()]]</code> verwenden.

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

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

<source lang="perl">
readingsBeginUpdate($hash);
readingsBulkUpdate($hash, $readingName1, $wert1 );
readingsBulkUpdate($hash, $readingName2, $wert2 );
readingsEndUpdate($hash, 1);
</source>

== Attribute ==
Damit der Nutzer das Verhalten einer einzelnen Gerätedefinition zur Laufzeit individuell anpassen kann, gibt es in FHEM für jede Definition sogenannte Attribute, welche mit dem Befehl <code>attr</code> gesetzt werden können.
Diese stehen dann dem Modul unmittelbar zur Verfügung um das Verhalten während der Ausführung zu beeinflussen. Attribute werden zusammen mit dem <code>define</code>-Befehl der jeweiligen Definition beim Speichern der aktuellen Konfiguration von FHEM in die Konfigurationsdatei geschrieben. Beim Neustart werden die entsprechenden Befehle ausgeführt um alle Definition inkl. Attribute wieder anzulegen. Zur Laufzeit werden Attribute in dem globalen Hash <code>%attr</code> mit dem Definitionsnamen als Index (<code>$attr{$name} = $value</code>) gespeichert. Ein Attribut mit dem Namen <code>header</code> würde beispielsweise mit <code>$attr{$name}{header}</code> adressiert. Generell sollte <code>%attr</code> nicht durch direkten Zugriff manipuliert/benutzt werden.

Zum Auslesen von Attributen sollte die Funktion [[DevelopmentModuleAPI#AttrVal|AttrVal()]] verwendet werden.

Welche Attribute ein Modul unterstützt muss in der Funktion <code>[[#X_Initialize|X_Initialize]]</code> durch Setzen von <code>$hash->{AttrList}</code> bekannt gemacht werden (siehe unten).

Wenn beim Setzen von Attributen in einer Gerätedefinition entsprechende Werte geprüft werden sollen oder zusätzliche Funktionalitäten implementiert werden müssen, dann muss dies in der Funktion <code>[[#X_Attr|X_Attr]]</code> (siehe unten) implementiert werden. Hier kann man bspw. einen Syntaxcheck für Attribut-Werte implementieren um ungültige Werte zurückzuweisen.

== Modulfunktionen ==

Damit fhem.pl ein Modul nutzen kann, muss dieses entsprechende Funktionen mit einer vorgegebenen Aufrufsyntax implementieren. Durch die Bekanntgabe dieser modulspezifischen Funktionen können Daten zwischen fhem.pl und einem Modul entsprechend ausgetauscht werden. Es gibt verschiedene Arten von Funktionen die ein Modul anbieten muss bzw. kann, je nach Funktionsumfang.

=== Die wichtigsten Funktionen in einem Modul ===

Folgende Funktion muss ein Modul mit dem beispielhaften Namen "X" mindestens bereitstellen:

{| class="wikitable"
|-
! style="text-align:left" | Funktionsname !! style="text-align:left" | Kurzbeschreibung
|-
| [[#X_Initialize|X_Initialize]] || Initialisiert das Modul und gibt den Namen zusätzlicher Modulfunktionen bekannt, sowie modulspezifische Einstellungen. Wird direkt nach dem erfolgreichen Laden des Moduls durch fhem.pl aufgerufen.
|}

Die folgenden Funktionen sind die wichtigsten Funktionen, welche je nach Anwendungsfall zu implementieren sind. Es handelt sich hierbei um die wichtigsten Vertreter, welche in den meisten Modulen Verwendung finden. Nicht alle Funktionen machen jedoch in jedem Modul Sinn. Generell sollte auch hier bei jeder Funktion der Modulname vorangestellt werden um ein einheitliches Namensschema zu gewährleisten. Hier die wichtigsten Modulfunktionen:

{| class="wikitable sortable"
|-
! style="text-align:left" | Funktionsname !! style="text-align:left" class="unsortable"| Kurzbeschreibung
|-
| [[#X_Define|X_Define]] || Wird im Rahmen des <code>define</code>-Befehls aufgerufen.
|-
| [[#X_Undef|X_Undef]] || Wird im Rahmen des <code>delete</code>-Befehls, sowie <code>rereadcfg</code>-Befehl aufgerufen. Dient zum Abbau von offenen Verbindungen, Timern, etc.
|-
| [[#X_Delete|X_Delete]] || Wird im Rahmen des beim <code>delete</code>-Befehls aufgerufen wenn das Gerät endgültig gelöscht wird um weiterführende Aktionen vor dem Löschen durchzuführen.
|-
| [[#X_Get|X_Get]] || Wird im Rahmen des <code>get</code>-Befehls aufgerufen um Daten vom Gerät abzufragen
|-
| [[#X_Set|X_Set]] || Wird im Rahmen des <code>set</code>-Befehls aufgerufen um Daten an das Gerät zu senden.
|-
| [[#X_Attr|X_Attr]] || Wird im Rahmen des <code>attr</code>-Befehls aufgerufen um Attributwerte zu prüfen)
|-
| [[#X_Read|X_Read]] || Wird durch FHEM aufgerufen, wenn ein gelisteter Filedeskriptor in <code>[[#Wichtige_globale_Variablen_aus_fhem.pl|%selectlist]]</code> Daten zum Lesen bereitstellt.
|-
| [[#X_Ready|X_Ready]] || Wird unter Windows durch FHEM aufgerufen um zyklisch einen seriellen Filedeskriptor auf lesbare Daten zu prüfen. Unter Linux dient diese Funktion dem Wiederaufbau verlorener Verbindungen.
|-
| [[#X_Notify|X_Notify]] || Verarbeitet Events von anderen Geräten innerhalb von FHEM
|-
| [[#X_Rename|X_Rename]] || Wird aufgerufen, wenn ein Gerät umbenannt wird.
|-
| [[#X_Shutdown|X_Shutdown]] || Wird beim Herunterfahren von FHEM ausgeführt.
|}

Diese Funktionen werden in diesem Abschnitt genauer beschrieben.

==== X_Initialize ====

<source lang="perl">
sub X_Initialize($)
{
my ($hash) = @_;
...
}
</source>

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

Dieser Hash muss nun von X_Initialize mit allen modulrelevanten Funktionsnamen gefüllt werden. Anschließend wird dieser Hash durch fhem.pl im globalen Hash <code>%modules</code> gespeichert. <code>$modules{ModulName}</code> wäre dabei der Hash für das Modul mit dem Namen <code>ModulName</code>. Es handelt sich also nicht um den oben beschriebenen Hash der Geräteinstanzen sondern einen Hash, der für jedes Modul existiert und modulspezifische Daten wie bspw. die implementierten Modulfunktionen enthält. Die Initialize-Funktion setzt diese Funktionsnamen, in den Hash des Moduls wie folgt:

<source lang="perl">
$hash->{DefFn} = "X_Define";
$hash->{UndefFn} = "X_Undef";
$hash->{DeleteFn} = "X_Delete";
$hash->{SetFn} = "X_Set";
$hash->{GetFn} = "X_Get";
$hash->{AttrFn} = "X_Attr";
$hash->{ReadFn} = "X_Read";
$hash->{ReadyFn} = "X_Ready";
$hash->{NotifyFn} = "X_Notify";
$hash->{RenameFn} = "X_Rename";
$hash->{ShutdownFn} = "X_Shutdown";
</source>

Um eine entsprechende Funktion in FHEM bekannt zu machen muss dazu der Funktionsname, wie er im Modul als <code>sub <''Funktionsname''>() { ... }</code> definiert ist, als Zeichenkette in <code>$hash</code> gesetzt werden. Dabei sollten die entsprechenden Funktionsnamen immer den Modulnamen (in diesem Beispiel <code>X</code>) als Präfix verwenden.
Auf diese Weise können sämtliche modulspezifisch implementierten Funktionen wie <code>X_Read</code>, <code>X_Parse</code> etc. durch Zuweisung an <code>$hash->{ReadFn}</code> bzw. <code>$hash->{ParseFn}</code> usw. bekannt gemacht werden.

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

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

Die Auflistung aller unterstützten modulspezifischen Attribute erfolgt in Form einer durch Leerzeichen getrennten Liste in <code>$hash->{AttrList}}</code>. Es gibt in FHEM globale Attribute, die in allen Gerätedefinitionen verfügbar sind und nur modulspezifische Attribute die jedes Modul via <code>$hash->{AttrList}</code> über die eigene Initialize-Funktion setzt. In fhem.pl werden dann die entsprechenden Attributwerte beim Aufruf eines <code>attr</code>-Befehls in die globale Datenstruktur <code>$attr{$name}</code>, z.B. <code>$attr{$name}{header}</code> für das Attribut <code>header</code> gespeichert. Falls im Modul weitere Aktionen oder Prüfungen beim Setzen eines Attributs nötig sind, dann kann wie im Beispiel oben die [[#X_Attr|Attr]]-Funktion implementiert und in der Initialize-Funktion bekannt gemacht werden.

Die Variable <code>$readingFnAttributes</code>, die im obigen Beispiel an die Liste der unterstützten Attribute angefügt wird, definiert Attributnamen, die dann zusätzlich gemacht werden, wenn das Modul zum Setzen von Readings die Funktionen <code>[[DevelopmentModuleAPI#readingsBeginUpdate|readingsBeginUpdate()]]</code>, <code>[[DevelopmentModuleAPI#readingsBulkUpdate|readingsBulkUpdate()]]</code>, <code>[[DevelopmentModuleAPI#readingsEndUpdate|readingsEndUpdate()]]</code> oder <code>[[DevelopmentModuleAPI#readingsSingleUpdate|readingsSingleUpdate()]]</code> verwendet. In diesen Funktionen werden Attribute wie <code>event-min-interval</code> oder auch <code>event-on-change-reading</code> ausgewertet. Für Details hierzu siehe commandref zu [http://fhem.de/commandref.html#readingFnAttributes readingFnAttributes].

<u>Nutzung von parseParams()</u>

Die Funktion <code> [[DevelopmentModuleAPI#parseParams|parseParams()]]</code> unterstützt Modulautoren beim Parsen von Übergabeparametern, welche bei <code>define</code>, <code>get</code> und <code>set</code> Kommandos an die entsprechenden Modulfunktionen übergeben werden. Dadurch lassen sich auf einfache Weise insbesondere komplexe Parameter (wie bspw. Perl-Ausdrücke) sehr einfach parsen.

Diese Zusatzfunktion kann man in der Initialize-Funktion einfach über folgenden Parameter für [[#X_Define|Define]]-, [[#X_Get|Get]]- und [[#X_Set|Set]]-Funktion modulweit aktivieren:
<source lang="perl">$hash->{parseParams} = 1;</source>
Sobald es gesetzt ist wird automatisch durch fhem.pl <code>[[DevelopmentModuleAPI#parseParams|parseParams()]]</code> aufgerufen und die an die [[#X_Define|Define]]-, [[#X_Get|Get]]- und [[#X_Set|Set]]-Funktion übergebenen Parameter ändern sich wie weiter unten in den jeweiligen Funktionen beschrieben.

==== X_Define ====
<source lang="perl">
sub X_Define($$)
{
my ( $hash, $def ) = @_;

...

return $error;
}
</source>

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

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

Als Übergabeparameter bekommt die Define-Funktion den Hash der Geräteinstanz sowie den die im <code>define</code>-Befehl übergebenen Parameter. Welche bzw. wie viele Parameter
akzeptiert werden und welcher Syntax diese entsprechen müssen ist Sache dieser Funktion. Im obigen Beispiel wird die Argumentzeile <code>$def</code> in ein Array aufgeteilt (durch Leerzeichen/Tabulator getrennt) und so können die vom Modul bzw. der Define-Funktion erwarteten Werte über das Array der Reihe nach verarbeitet werden:

<source lang="perl">
my $name = $a[0];
my $module = $a[1];
my $url = $a[2];
my $inter = 300;

if(int(@a) == 4) {
$inter = $a[3];
if ($inter < 5) {
return "interval too small, please use something > 5s, default is 300 seconds";
}
}
</source>

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

<source lang="perl">
$hash->{url} = $url;
$hash->{Interval} = $inter;
</source>

Sobald alle Parameter korrekt verarbeitet wurden, wird in der Regel die erste Verbindung zum Gerät aufgebaut. Je nach Art des Geräts kann das eine permanente Datenverbindung sein (z.B. serielle Schnittstelle oder TCP-Verbindung) oder das Starten eines regelmäßigen Timers, der zyklisch den Status z.B. via [[HttpUtils|HTTP]] ausliest.

Sollten im Rahmen der Define-Funktion Syntax-Probleme der Übergabeparameter festgestellt werden oder es kann bspw. keine Verbindung aufgebaut werden, so ist als Funktionsrückgabewert eine entsprechende Fehlermeldung zurückzugeben. Nur wenn alle Übergabeparameter akzeptiert werden, darf <code>undef</code> zurückgegeben werden. Sobald eine Define-Funktion eine Fehlermeldung zurückmeldet, wird der define-Befehl durch FHEM zurückgewiesen und der User erhält die Fehlermeldung, welche die Define-Funktion produziert hat, als Ausgabe zurück.

<u>Verfügbarkeit von Attributen</u>

Während die Define-Funktion ausgeführt wird, sollte man nicht davon ausgehen, dass alle vom Nutzer konfigurierten Attribute via [[DevelopmentModuleAPI#AttrVal|AttrVal()]] verfügbar sind. Attribute stehen in der Define-Funktion nur dann zur Verfügung, wenn FHEM sich nicht in der Initialisierungsphase befindet (globale Variable <code>$init_done</code> ist wahr; der Nutzer hat die Gerätedefinition modifiziert). Daher sollte man weiterführende Funktion, welche auf gesetzte Attribute angewiesen sind, nur dann in der Define-Funktion starten, wenn <code>$init_done</code> zutrifft.

Andernfalls sollte man den Aufruf in der Notify-Funktion durchführen sobald <code>global:INITIALIZED</code> bzw. <code>global:REREADCFG</code> getriggert wurde:

<source lang="perl">
sub X_Define($$)
{
my ( $hash, $def ) = @_;

...

$hash->{NOTIFYDEV} = "global";

X_FunctionWhoNeedsAttr($hash) if($init_done);
}

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

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

my $devName = $dev_hash->{NAME}; # Device that created the events
my $events = deviceEvents($dev_hash, 1);

if($devName eq "global" && grep(m/^INITIALIZED|REREADCFG$/, @{$events}))
{
X_FunctionWhoNeedsAttr($hash);
}
}
</source>

Dadurch wird die Modulfunktion X_FunctionWhoNeedsAttr() nach dem Start erst aufgerufen, wenn alle Attribute aus der Konfiguration geladen wurden.

<u>Nutzung von parseParams()</u>

Zum Aufteilen und Parsen von <code>$def</code> lässt sich die Funktion [[DevelopmentModuleAPI#parseParams|parseParams]] verwenden um die einzelnen Argumente einfach zu parsen. Wenn in X_Initialize <code>$hash->{parseParams} = 1;</code> gesetzt wurde dann wird parseParams automatisch aufgerufen und X_Define ändert sich wie folgt:
<source lang="perl">
sub X_Define($$$)
{
my ( $hash, $a, $h ) = @_;
...
</source>

Die genauen Möglichkeiten von parseParams sind in dem entsprechenden [[DevelopmentModuleAPI#parseParams|Artikel]] dokumentiert.

<u>Nutzung von DevIo</u>

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

Um DevIo mitzuteilen welche Verbindung genau zu öffnen ist, muss das Internal <code>$hash->{DeviceName} mit einer entsprechenden Syntax gefüllt sein (z.B. <code>"/dev/ttyUSB0@9600"</code>, <code>"192.168.2.105:3000"</code>, ...). Üblicherweise wird diese Information als Argument im <code>define</code>-Befehl vom Nutzer angegeben.

<source lang="perl">
my $ret = DevIo_OpenDev( $hash, 0, "X_DeviceInit" );
</source>

Die optionale Funktion <code>X_DevInit</code> wird zur weiteren Initialisierung der Verbindung von <code>DevIo_OpenDev</code> aufgerufen. Der zweite Übergabeparameter an <code>DevIo_OpenDev</code> (hier <code>0</code>) steht für reopen und wird benötigt, da die Funktion auch aufgerufen wird, wenn ein USB-Geräte beispielsweise im Betrieb aus- und wieder eingesteckt wird. In diesem Fall wird die Funktion mit <code>1</code> aufgerufen. Dies ist jedoch nur in der [[#X_Ready|X_Ready]]-Funktion notwendig. In der Define-Funktion wird immer <code>0</code> (erster Verbindungsversuch) angegen

==== X_Undef ====
<source lang="perl">
sub X_Undef ($$)
{
my ( $hash, $name ) = @_;

...

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

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

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

Sollten im Rahmen der Undef-Funktion Probleme festgestellt werden, die ein Löschen nicht zulassen, so ist als Funktionsrückgabewert eine entsprechende Fehlermeldung zurückzugeben. Nur wenn die Undef-Funktion erfolgreich durchgeführt wurde, darf <code>undef</code> zurückgegeben werden. Nur dann wird eine Gerätedefinition von FHEM auch tatsächlich gelöscht bzw. neu angelegt. Sollte die Undef-Funktion jedoch eine Fehlermeldung zurückgeben, wird der entsprechende Vorgang (<code>delete</code> bzw. <code>rereadcfg</code>) für dieses Gerät abgebrochen. Es bleibt dann unverändert in FHEM bestehen.

==== X_Delete ====
<source lang="perl">
sub X_Delete ($$)
{
my ( $hash, $name ) = @_;

...

return $error;
}
</source>

Die Delete-Funktion ist das Gegenstück zur Funktion [[#X_Define|X_Define]] und wird aufgerufen wenn ein Gerät mit dem Befehl <code>delete</code> gelöscht wird.

Wenn ein Gerät in FHEM gelöscht wird, wird zuerst die Funktion [[#X_Undef|X_Undef]] aufgerufen um offene Verbindungen zu schließen, anschließend wird die Funktion X_Delete aufgerufen. Diese dient eher zum Aufräumen von dauerhaften Daten, welche durch das Modul evtl. für dieses Gerät spezifisch erstellt worden sind. Es geht hier also eher darum, alle Spuren sowohl im laufenden FHEM-Prozess, als auch dauerhafte Daten bspw. im physikalischen Gerät zu löschen die mit dieser Gerätedefinition zu tun haben.

Dies kann z.B. folgendes sein:

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

Beispiel:
<source lang="perl">
sub X_Delete($$)
{
my ( $hash, $name ) = @_;

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

return undef;
}
</source>

Sollten im Rahmen der Delete-Funktion Probleme festgestellt werden, die ein Löschen nicht zulassen, so ist als Funktionsrückgabewert eine entsprechende Fehlermeldung zurückzugeben. Nur die Delete-Funktion erfolgreich durchgeführt wurde, darf <code>undef</code> zurückgegeben werden. Nur dann wird eine Gerätedefinition von FHEM auch tatsächlich gelöscht. Sollte die Delete-Funktion eine Fehlermeldung zurückgeben, wird der Löschvorgang abgebrochen und das Gerät bleibt weiter in FHEM bestehen.

==== X_Get ====
<source lang="perl">
sub X_Get ($$@)
{
my ( $hash, $name, $opt, @args ) = @_;

...

return $result;
}
</source>
Die Get-Funktion wird aufgerufen wenn der FHEM-Befehl <code>get</code> mit einem Gerät dieses Moduls ausgeführt wird. Mit <code>get</code> werden typischerweise Werte von einem Gerät abgefragt. In vielen Modulen wird auf diese Weise auch der Zugriff auf generierte Readings ermöglicht. Der Get-Funktion wird dabei der Geräte-Hash, der Gerätename, sowie die Aufrufparameter des get-Befehls übergeben. Als Rückgabewert wird das Ergebnis des entsprechenden Befehls in Form einer Zeichenkette zurückgegeben. Der Rückgabewert <code>undef</code> hat hierbei keine besondere Bedeutung und wird behandelt wie eine leere Zeichenkette <code>""</code>.

Beispiel:

<source lang="perl">
sub X_Get($$@)
{
my ( $hash, $name, $opt, @args ) = @_;

return "\"get $name\" needs at least one argument" unless(defined($opt)));

if($opt eq "status")
{
...
}
elsif($opt eq "powser")
{
...
}
...
else
{
return "Unknown argument $opt, choose one of status power [...]";
}
}
</source>

Wenn eine unbekannte Option an die Get-Funktion übergeben wird, so muss als Rückgabewert der Funktion eine bestimmte Syntax einhalten um FHEM mitzuteilen, welche Optionen für einen Get-Befehl aktuell unterstützt werden. Die Rückgabe muss dabei folgender Syntax entsprechen:

<code>'''unknown''' argument ''<font color="grey">[Parameter]</font>'' '''choose one of''' ''<font color="grey">[Liste möglicher Optionen]</font>''</code>

Hierbei sind die fett gedruckten Teile der Rückmeldung besonders wichtig. Sind diese nicht vorhanden, kann FHEM nicht die möglichen Get-Kommandos für das entsprechende Gerät ermitteln. Es muss am Anfang der Meldung das Stichwort "unknown" vorkommen gefolgt von einer frei definierbaren Fehlermeldung (i.d.R der übergebene Parameter, welcher ungültig ist). Anschließend folgt "choose one of" mit einer anschließenden Liste möglicher Optionen getrennt durch ein Leerzeichen.

Beispiel:
<ul>
<source lang="perl">return "unknown argument $opt choose one of state temperature humidity";</source>

Hier werden als mögliche Optionen für einen Get-Befehl folgende Parameter angegeben:

* <code>state</code>
* <code>temperature</code>
* <code>humidity</code>

Dies würde in folgenden, mögliche Get-Befehle für einen User resultieren:

* <code>get ''<NAME>'' state</code>
* <code>get ''<NAME>'' temperature</code>
* <code>get ''<NAME>'' humidity</code>
</ul>

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

<u>Nutzung von parseParams()</u>

Wenn in [[#X_Initialize|X_Initialize]] <code>$hash->{parseParams} = 1;</code> gesetzt wurde dann wird [[DevelopmentModuleAPI#parseParams|parseParams]] automatisch aufgerufen und X_Get ändert sich wie folgt:
<source lang="perl">
sub X_Get($$$)
{
my ( $hash, $a, $h ) = @_;
...
</source>

Die genauen Möglichkeiten von parseParams sind in dem entsprechenden [[DevelopmentModuleAPI#parseParams|Artikel]] dokumentiert.

==== X_Set ====
<source lang="perl">
sub X_Set ($$@)
{
my ( $hash, $name, $cmd, @args ) = @_;

...

return $error;
}
</source>

Die Set-Funktion ist das Gegenteil zur [[#X_Get|Get]]-Funktion. Sie ist dafür gedacht, Daten zum physischen Gerät zu schicken, bzw. entsprechende Aktionen im Gerät selber auszulösen. Ein Set-Befehl dient daher der direkten Steuerung des physikalischen Gerätes in dem es bspw. Zustände verändert (wie <code>on</code>/<code>off</code>). Der Set-Funktion wird dabei der Geräte-Hash, der Gerätename, sowie die Aufrufparameter des set-Befehls übergeben. Als Rückgabewert kann eine Fehlermeldung in Form Zeichenkette zurückgegeben werden. Der Rückgabewert <code>undef</code> bedeutet hierbei, dass der Set-Befehl erfolgreich durchgeführt wurde. Eine Set-Funktion gibt daher nur im Fehlerfall eine Rückmeldung mit einer entsprechenden Fehlermeldung. Der Wert <code>undef</code> wird als "erfolgreich" interpretiert. Rückmeldungen von set-Befehlen sämtlicher Module, die im Rahmen eines ausgeführten [[Notify]] auftreten werden im FHEM Logfile festgehalten.

Falls nur interne Daten, die ausschließlich für das Modul relevant sind, gesetzt werden müssen, so sollte statt Set die [[#X_Attr|Attr]]-Funktion verwendet werden. Attribute werden bei Save-Config auch in der Fhem.cfg gesichert. Set-Befehle nicht, da sie nur zur Steuerungszwecken im laufenden Betrieb von FHEM dienen.

Eine Set-Funktion ist ähnlich aufgebaut wie die Get-Funktion, sie bekommt jedoch in der Regel weitere zusätzliche Parameter übergeben um Zustände zu setzen.

Beispiel:
<source lang="perl">
sub X_Set($@)
{
my ( $hash, $name, $cmd, @args ) = @_;

return "\"set $name\" needs at least one argument" unless(defined($cmd)));

if($cmd eq "status")
{
if($args[0] eq "up")
{
...
}
elsif($args[0] eq "down")
{
...
}
else
{
return "Unknown value $args[0] for $cmd, choose one of status power";
}
}
elsif($cmd eq "power")
{
if($args[0] eq "on")
{
...
}
elsif($args[0] eq "off")
{
...
}
else
{
return "Unknown value $args[0] for $cmd, choose one of status power";
}
}
...
else
{
return "Unknown argument $cmd, choose one of status power";
}
}
</source>

Wenn eine unbekannte Option an die Set-Funktion übergeben wird, so muss als Rückgabewert der Funktion eine bestimmte Syntax eingehalten werden um FHEM mitzuteilen, welche Optionen für einen Set-Befehl aktuell unterstützt werden. Die Rückgabe muss dabei folgender Syntax entsprechen:

<code>'''unknown''' argument ''<font color="grey">[Parameter]</font>'' '''choose one of''' ''<font color="grey">[Liste möglicher Optionen]</font>''</code>

Hierbei sind die fett gedruckten Teile der Rückmeldung besonders wichtig. Sind diese nicht vorhanden, kann FHEM nicht die möglichen Set-Kommandos für das entsprechende Gerät ermitteln. Es muss am Anfang der Meldung das Stichwort "unknown" vorkommen gefolgt von einer frei definierbaren Fehlermeldung (i.d.R der übergebene Parameter, welcher ungültig ist). Anschließend folgt "choose one of" mit einer anschließenden Liste möglicher Optionen getrennt durch ein Leerzeichen.

Beispiel:
<ul>
<source lang="perl">return "unknown argument $cmd choose one of state power";</source>

Hier werden als mögliche Optionen für einen Get-Befehl folgende Parameter angegeben:

* <code>state</code>
* <code>power</code>

Dies würde in folgenden, mögliche Get-Befehle für einen User resultieren:

* <code>get ''<NAME>'' state</code>
* <code>get ''<NAME>'' power</code>
</ul>

Die Ausgabe einer solchen Meldung ist sehr wichtig, da sie im GUI-Modul verwendet wird um die möglichen <code>set</code>-Optionen zu ermitteln und als Auswahl anzubieten

<u>Nutzung von SetExtensions.pm</u>

Wenn man dem Nutzer zusätzlich zu den Set-Befehlen <code>on</code> und <code>off</code> auch weiterführende Befehle wie <code>on-for-timer</code>, <code>on-till</code>, usw. anbieten möchte, obwohl die zu steuernde Hardware solche Kommandos nicht unterstützt, kann man dies über das Hilfsmodul SetExtensions.pm realisieren.

Das Hilfsmodul SetExtensions.pm bietet weiterführende Set-Kommandos basierend auf den Befehlen <code>on</code>/<code>off</code> an. Dabei werden durch interne Timer bzw. eigens angelegten [[at]]-Definitionen diese Befehle durch FHEM selber umgesetzt. Je nach ausgeführtem Befehl wird der <code>on</code>- bzw. <code>off</code>-Befehl dann durch FHEM zum richtigen Zeitpunkt ausgeführt. Vorausgesetzt das Modul unterstützt in der Set-Funktion die Befehle <code>on</code> und <code>off</code>, so werden durch den Einsatz von SetExtensions.pm folgende Befehle zusätzlich unterstützt:

{| class="wikitable"
|-
! Set-Kommando !! Beispiel !! Beschreibung
|-
| style="white-space: nowrap;" | <code>on-for-timer ''<Dauer>''</code> || style="white-space: nowrap;" | <code>on-for-timer 120</code> || Schaltet das Gerät sofort mit dem <code>on</code>-Befehl ein und nach der angegebenen Dauer in Sekunden via <code>off</code> wieder aus.
|-
| style="white-space: nowrap;" | <code>off-for-timer ''<Dauer>''</code> || style="white-space: nowrap;" | <code>off-for-timer 120</code> || Schaltet das Gerät sofort mit dem <code>off</code>-Befehl aus und nach der angegebenen Dauer in Sekunden via <code>on</code> wieder ein.
|-
| style="white-space: nowrap;" | <code>on-till ''<Zeitpunkt>''</code> || style="white-space: nowrap;" | <code>on-till 16:30</code> || Schaltet das Gerät sofort mit dem <code>on</code>-Befehl ein und zum angegebenen Zeitpunkt via <code>off</code> wieder aus.
|-
| style="white-space: nowrap;" | <code>off-till ''<Zeitpunkt>''</code> || style="white-space: nowrap;" | <code>off-till 16:30</code> || Schaltet das Gerät sofort mit dem <code>off</code>-Befehl aus und zum angegebenen Zeitpunkt via <code>on</code> wieder ein.
|-
| style="white-space: nowrap;" | <code>on-till-overnight ''<Zeitpunkt>''</code> || style="white-space: nowrap;" | <code>on-till-overnight 01:00</code> || Ähnlich wie <code>on-till</code>. Der übergebene Zeitpunkt wird aber nicht geprüft, ob er für den heutigen Tag bereits überschritten wurde. Dadurch kann man Abends einen Zeitpunkt setzen, der erst am nächsten Tag zutrifft.
|-
| style="white-space: nowrap;" | <code>off-till-overnight ''<Zeitpunkt>''</code> || style="white-space: nowrap;" | <code>off-till-overnight 01:00</code> || Ähnlich wie <code>off-till</code>. Der übergebene Zeitpunkt wird aber nicht geprüft, ob er für den heutigen Tag bereits überschritten wurde. Dadurch kann man Abends einen Zeitpunkt setzen, der erst am nächsten Tag zutrifft.
|-
| style="white-space: nowrap;" | <code>blink ''<Anzahl> <Interval>''</code> || style="white-space: nowrap;" | <code>blink 3 1</code> || Schaltet das Gerät via <code>on</code> für <code>''<Interval>''</code> Sekunden ein und anschließend via <code>off</code> wieder aus. Nach <code>''<Interval>''</code> Sekunden wird das ganze wiederholt, solange bis die angegebene Anzahl erreicht ist.
|-
| style="white-space: nowrap;" | <code>intervals ''<Start>-<Ende>'' ''<Start>-<Ende>'' ...</code> || style="white-space: nowrap;" | <code>intervals 07:00-08:00 16:30-18:00</code> || Schaltet das Gerät innerhalb der übergebenen Zeiträumen via <code>on</code> ein. Sobald die aktuelle Zeit ausserhalb dieser Zeiträume liegt, wird das Gerät via <code>off</code> wieder ausgeschaltet. Es können dabei beliebig viele Zeiträume angegeben werden.
|-
| style="white-space: nowrap;" | <code>toggle</code> || style="white-space: nowrap;" | <code>toggle</code> || Sofern der aktuelle Status <code>on</code> ist, wird das Gerät via <code>off</code> ausgeschaltet. Andernfalls wird es via <code>on</code> eingeschaltet.
|}

Eine kurze Beschreibung zu den möglichen Befehlen durch SetExtensions.pm gibt es auch in der Commandref zum [http://fhem.de/commandref.html#set Set-Befehl].

Um SetExtensions.pm in der Set-Funktion nutzen zu können müssen folgende Aktionen durchgeführt werden:

# Laden von SetExtensions.pm via <code>use SetExtensions;</code> am Anfang des Moduls
# Aufruf und Rückgabe der Funktion [[DevelopmentModuleAPI#SetExtensions|SetExtensions()]] sofern die Set-Funktion mit dem übergebenen Befehl nichts anfangen kann.

Beispiel:

<source lang="perl">
use SetExtensions;

...

sub X_Set($@)
{
my ( $hash, $name, $cmd, @args ) = @_;
my $cmdList = "on off";

return "\"set $name\" needs at least one argument" unless(defined($cmd)));

if($cmd eq "on")
{
# Gerät einschalten...
}
elsif($cmd eq "off")
{
# Gerät ausschalten...
}
...
else # wenn der übergebene Befehl nicht durch X_Set() verarbeitet werden kann, Weitergabe an SetExtensions()
{
return SetExtensions($hash, $cmdList, $name, $cmd, @args);
}
}
</source>

Sollte der übergebene Set-Befehl auch für SetExtensions unbekannt sein (bspw. <code>set ''<Name>'' ?</code>), so generiert SetExtensions() eine entsprechende Usage-Meldung, welche innerhalb der Set-Funktion an FHEM zurückgegeben werden muss.

Eine ausführliche Beschreibung zu der Funktion SetExtensions() gibt es in der [[DevelopmentModuleAPI#SetExtensions|API-Referenz]].

<u>Nutzung von parseParams()</u>

Wenn in [[#X_Initialize|X_Initialize]] <code>$hash->{parseParams} = 1;</code> gesetzt wurde dann wird [[DevelopmentModuleAPI#parseParams|parseParams]] automatisch aufgerufen und X_Set ändert sich wie folgt:
<source lang="perl">
sub X_Set($$$)
{
my ( $hash, $a, $h ) = @_;
...
</source>

Die genauen Möglichkeiten von parseParams sind in dem entsprechenden [[DevelopmentModuleAPI#parseParams|Artikel]] dokumentiert.

<u>Nutzung von FHEMWEB-Widgets</u>

Das GUI-Modul [[FHEMWEB]] kann für die einzelnen Set-Optionen, die das Modul versteht, automatisch Eingabehilfen wie Drop-Down Boxen oder Slider erzeugen. In der Detailansicht der GUI kann der Anwender dann die jeweiligen Werte komfortabel auswählen. Dafür muss die Set-Funktion, wenn sie mit der Option <code>?</code> aufgerufen wird, nicht nur einen Text mit <code>"Unknown ... choose one of ..."</code> zurückgeben sondern den einzelnen Set-Optionen in diesem Rückgabetext nach einem Doppelpunkt entsprechende Zusatzinformationen anhängen.
Meist prüft man in den Modulen gar nicht auf die Option <code>?</code> sondern gibt generell bei unbekannten Optionen diesen Text zurück. Das Modul FHEMWEB ermittelt die Syntax eines Gerätes jedoch immer mit dem Befehl:
set ''<NAME>'' ?

Beispiel:
<source lang="perl">
return "Unknown argument $cmd, choose one of state:up,down power:on,off on:noArg off:noArg";
</source>

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

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

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

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

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

'''Hinweise'''

* Damit in einer Eingabe bereits der aktuelle Wert vorbelegt bzw. in einer Auswahlliste der aktuelle Wert vorselektiert ist, muss es im Modul bzw. Gerät ein Reading mit dem gleichen Namen wie die Set-Option geben. Der Wert des gleichnamigen Readings wird dann als Vorbelegung / Vorselektion verwendet.
* Der User kann sich in der Raumübersicht nach wie vor via [[WebCmd|webCmd]] eine entsprechende Steuerung anlegen.

==== X_Attr ====
<source lang="perl">
sub X_Attr ($$$$)
{
my ( $cmd, $name, $attrName, $attrValue ) = @_;

...

return $error;
}
</source>

Die Attr-Funktion dient der Prüfung von Attributen, welche über den <code>attr</code>-Befehl gesetzt werden können. Sobald versucht wird, ein Attribut für ein Gerät zu setzen, wird vorher die Attr-Funktion des entsprechenden Moduls aufgerufen um zu prüfen, ob das Attribut aus Sicht des Moduls korrekt ist.
Liegt ein Problem mit dem Attribut bzw. dem Wert vor, so muss die Funktion eine aussagekräftige Fehlermeldung zurückgeben, welche dem User angezeigt wird.
Sofern das übergebene Attribut samt Inhalt korrekt ist, gibt die Attr-Funktion den Wert <code>undef</code> zurück. Erst dann wird das Attribut in der globalen Datenstruktur <code>%attr</code> gespeichert und ist somit erst aktiv.

Beispiel:

<source lang="perl">
X_Attr(@)
{
my ( $cmd, $name, $attrName, $attrValue ) = @_;

# $cmd - Vorgangsart - kann die Werte "del" (löschen) oder "set" (setzen) annehmen
# $name - Gerätename
# $attrName/$attrValue sind Attribut-Name und Attribut-Wert

if ($cmd eq "set") {
if ($aName eq "Regex") {
eval { qr/$aVal/ };
if ($@) {
Log3 $name, 3, "X ($name) - Invalid regex in attr $name $aName $aVal: $@";
return "Invalid Regex $aVal: $@";
}
}
}
return undef;
}
</source>

Zusätzlich ist es möglich auch übergebene Attributwerte zu verändern bzw. zu korrigieren, indem man im Parameterarray <code>@_</code> den ursprünglichen Wert anpasst. Dies erfolgt im Beispiel über die Modifikation des Wertes mit Index 3 (entspricht dem 4. Element) im Parameterarray, also <code>$_[3]</code>.

Da das Attribut zum Zeitpunkt des Aufrufs der Attr-Funktion noch nicht gespeichert ist, wird der neue Wert zu diesem Zeitpunkt noch nicht via [[DevelopmentModuleAPI#AttrVal|AttrVal()]] zurückgegeben. Erst, wenn die Attr-Funktion mit <code>undef</code> beendet ist, wird der neue Wert in FHEM gespeichert und steht dann via AttrVal() zur Verfügung.

Die Attr-Funktion bekommt nicht den Hash der Geräteinstanz übergeben, da sie normalerweise keine Werte dort speichern muss, sondern lediglich das Attribut auf Korrektheit prüfen muss.
Im obigen Beispiel wird für ein Attribut mit Namen "Regex" geprüft ob der reguläre Ausdruck fehlerhaft ist. Sofern dieser OK ist, wird <code>undef</code> zurückgegeben und fhem.pl speichert den Wert des Attributs in <code>%attr</code>.

<u>Attributnamen mit Platzhaltern</u>

Falls man Attribute in der [[#X_Initialize|Initialize]]-Funktion mit Platzhaltern definiert (Wildcard-Attribute) wie z.B.:
<source lang="perl">
$hash->{AttrList} =
"reading[0-9]*Name " .
# usw.
</source>
dann können Anwender Attribute wie reading01Name, reading02Name etc. setzen. Leider funktioniert das bisher nicht durch Klicken in der Web-Oberfläche, da FHEMWEB nicht alle denkbaren Ausprägungen in einem Dropdown anbieten kann. Der Benutzer muss solche Attribute manuell über den <code>attr</code>-Befehl eingeben.

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

<source lang="perl">
addToDevAttrList($name, $aName);
</source>

==== X_Read ====
<source lang="perl">
sub X_Read ($)
{
my ( $hash ) = @_;

...
}
</source>
Die X_Read-Funktion wird aufgerufen, wenn ein dem Gerät zugeordneter Filedeskriptor (serielle Schnittstelle, TCP-Verbindung, ...) Daten zum Lesen bereitgestellt hat. Die Daten müssen nun eingelesen und interpretiert werden.

Im folgenden Beispiel wird über eine serielle Schnittstelle (beziehungsweise über einen USB-To-Seriell-Konverter) von einem angeschlossenen Gerät gelesen. Dazu werden die bisher verfügbaren Daten mit der Funktion <code>DevIo_SimpleRead</code> gelesen. Da die Übertragung möglicherweise noch nicht vollständig ist, kann es sein, dass kurz darauf die X_Read-Funktion wieder aufgerufen wird und ein weiterer Teil oder der Rest der Daten gelesen werden kann.
Die Funktion muss daher prüfen ob schon alle erwarteten Daten angekommen sind und gegebenenfalls die bisher gelesenen Daten in einem eigenen Puffer (idealerweise in <code>$hash</code>) zwischenspeichern. Im Beispiel ist dies <code>$hash->{helper}{BUFFER}</code> an den die aktuell gelesenen Daten angehängt werden, bis die folgende Prüfung ein für das jeweilige Protokoll vollständige Frame erkennt.

<source lang="perl">
sub X_Read($)
{
my ($hash) = @_;
my $name = $hash->{NAME};

# einlesen der bereitstehenden Daten
my $buf = DevIo_SimpleRead($hash);
return "" if ( !defined($buf) );
Log3 $name, 5, "X ($name) - received data: ".$buf;

# Daten in Hex konvertieren und an den Puffer anhängen
$hash->{helper}{BUFFER} .= unpack ('H*', $buf);
Log3 $name, 5, "X ($name) - current buffer content: ".$hash->{helper}{BUFFER};

# prüfen, ob im Buffer ein vollständiger Frame zur Verarbeitung vorhanden ist.
if ($hash->{helper}{BUFFER} =~ "ff1002(.{4})(.*)1003(.{4})ff(.*)") {
...
</source>

Die zu lesenden Nutzdaten können dann je nach Protokoll des Geräts beispielsweise an einer festgelegten Stelle im Frame (dann in <code>$hash->{helper}{BUFFER}</code>) stehen oder aus dem Kontext mit einem Regex-Match extrahiert werden und via [[DevelopmentModuleAPI#Readings_.2F_Events|Reading-Funktionen]] in Readings gespeichert werden (siehe unten).

Der Rückgabewert der Read-Funktion wird nicht geprüft und hat daher keinerlei Bedeutung.

==== X_Ready ====
<source lang="perl">
sub X_Ready ($)
{
my ( $hash ) = @_;

...

return $success;
}
</source>

Wird im Main-Loop aufgerufen falls das Modul in der globalen Liste <code>%readyfnlist</code> existiert. Diese Funktion hat je nachdem auf welchem OS FHEM ausgeführt wird unterschiedliche Aufgaben:

* '''UNIX-artiges Betriebssystem:''' prüfen, ob eine Verbindung nach einem Verbindungsabbruch wieder aufgebaut werden kann. Sobald der Verbindungsaufbau erfolgreich war, muss die Funktion einen erfolgreichen Wahrheitswert zurückliefern (z.B. "1") und den eigenen Eintrag entsprechend aus <code>%readyfnlist</code> löschen.
* '''Windows-Betriebssystem:''' prüfen, ob lesbare Daten für ein serielles Device (via COM1, COM2, ...) vorliegen. Sofern lesbare Daten vorliegen, muss Funktion einen erfolgreichen Wahrheitswert zurückliefern (z.B. "1"). Zusätzlich dazu muss die Funktion, wie bei UNIX-artigen Betriebssystem, ebenfalls bei einem Verbindungsabbruch einen neuen Verbindungsversuch initiieren. Der Eintrag in <code>%readyfnlist</code> bleibt solange erhalten, bis die Verbindung seitens FHEM beendet wird.

Der Windows-spezifische Teil zur Datenprüfung ist dabei nur zu implementieren, wenn das Modul über eine serielle Verbindung kommuniziert.

Bei der Nutzung des Moduls DevIo wird dem Modulentwickler der Umgang mit <code>%readyfnlist</code> abgenommen, da DevIo sich selbst um die entsprechenden Einträge kümmert und diese selbstständig wieder entfernt.

In der Regel sieht eine Ready-Funktion immer gleich aus.

Beispiel:
<source lang="perl">
sub X_Ready($)
{
my ($hash) = @_;

# Versuch eines Verbindungsaufbaus, sofern die Verbindung beendet ist.
return DevIo_OpenDev($hash, 1, undef ) if ( $hash->{STATE} eq "disconnected" );

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

==== X_Notify ====

Die X_Notify-Funktion wird aus der Funktion [[DevelopmentModuleAPI#DoTrigger|DoTrigger()]] in fhem.pl heraus aufgerufen sobald ein Modul Events erzeugt hat. Damit kann ein Modul auf Events anderer Module reagieren. Typische Beispiele sind dabei das [[FileLog]]-Modul oder das [[notify]]-Modul.

Die Notify-Funktion bekommt dafür zwei Hash-Referenzen übergeben: den Hash des eigenen Geräts und den Hash des Geräts, dass die Events erzeugt hat.
Über den Hash des eigenen Geräts kann die Notify-Funktion beispielsweise auf die Internals oder Attribute des eigenen Geräts zugreifen.
Über den Hash des Gerätes und der [[DevelopmentModuleAPI#deviceEvents|deviceEvents()]]-Funktion kann man auf die generierten Events zugreifen. Über den zweiten Parameter dieser Routine lässt sich bestimmen ob für das Reading <code>state</code> ein 'normales' Event (d.h. in der form <code>state: <wert></code>) erzeugen soll (Wert: 1) oder ob z.b. aus Gründen der Rückwärtskompatibilität ein Event ohne <code>state: </code> erzeugt werden soll. Falls dem Anwender die Wahl des verwendeten Formats überlassen werden soll ist hierzu das [http://fhem.de/commandref_DE.html#addStateEvent addStateEvent-Attribut] vorzusehen.

Der direkte Zugriff auf <code>$hash->{CHANGED}</code> ist nicht mehr zu empfehlen.

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

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

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

my $events = deviceEvents($dev_hash,1);
return if( !$events );

foreach my $event (@{$events}) {
$event = "" if(!defined($event));

# Examples:
# $event = "readingname: value"
# or
# $event = "INITIALIZED" (for $devName equal "global")
#
# processing $event with further code
}
return undef;
}
</source>

<u>Begrenzung der Aufrufe auf bestimmte Geräte</u>

Da die Notify-Funktion für jedes definierte Gerät mit all seinen Events aufgerufen wird, muss sie in einer Schleife jedesmal prüfen und entscheiden, ob es mit dem jeweiligen Event etwas anfangen kann. Ein Gerät, dass die Notify-Funktion implementiert, sieht dafür typischerweise einen regulären Ausdruck vor, welcher für die Filterung verwendet wird.

Wenn man nur gezielt von bestimmten Definitionen Events erhalten will, kann man diese auch in Form einer [http://fhem.de/commandref_DE.html#devspec devspec] in <code>$hash->{NOTIFYDEV}</code> angeben. Bspw. kann man in der Define-Funktion diesen Wert setzen. Dadurch wird die Notify-Funktion nur aufgerufen wenn eine der Definitionen, auf welche die devspec passt, ein Event erzeugt hat. Ein typischer Fall ist die Begrenzung von Events auf "global":

<source lang="perl">
in der Define-Funktion:

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

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

Sofern in der [[#X_Define|Define-Funktion]] eine Regexp als Argument übergeben wird, die ähnlich wie beim Modul [[notify]] auf Events wie <code><Definitionsname></code> bzw. <code><Definitionsname>:<Event></code> reagiert, so sollte man in der Define-Funktion die Funktion [[DevelopmentModuleAPI#notifyRegexpChanged|notifyRegexpChanged()]] verwenden. Diese versucht einen passenden Eintrag für <code>$hash->{NOTIFYDEV}</code> basierend auf der übergebenen Regexp zu setzen, sofern dies möglich ist.

<u>Reihenfolge für den Aufruf der Notify-Funktion beeinflussen</u>

Sobald ein Event ausgelöst wurde, stellt sich FHEM eine Liste aller relevanten Geräte-Hashes zusammen, welche via Notify-Funktion prüfen müssen, ob das Event relevant ist. Dabei wird die Liste nach <code>$hash->{NTFY_ORDER}</code> sortiert. Diese enthält ein Order-Präfix in Form einer Ganzzahl, sowie den Namen der Definition (Bsp: <code>'''50'''-Lampe_Wohnzimmer</code>). Dadurch kann man jedoch nicht sicherstellen, dass Events von bestimmten Modulen zuerst verarbeitet werden.

Wenn das eigene Modul bei der Eventverarbeitung gegenüber den anderen Modulen eine bestimmte Reihenfolge einhalten muss, kann man in der [[#X_Initialize|Initialize]]-Funktion durch Setzen von <code>$hash->{NotifyOrderPrefix}</code> diese Reihenfolge beeinflussen. Standardmäßig werden Module immer mit einem Order-Präfix von "50-" in FHEM registriert. Durch die Veränderung dieses Präfixes kann man das eigene Modul in der Reihenfolge gegenüber anderen Modulen bei der Eventverarbeitung beeinflussen.

Beispiel:

<source lang="perl">
sub X_Initialize($)
{
my ($hash) = @_;

...

$hash->{NotifyOrderPrefix} = "45-" # Alle Definitionen des Moduls X werden bei der Eventverarbeitung zuerst geprüft

# oder...

$hash->{NotifyOrderPrefix} = "55-" # Alle Definitionen des Moduls X werden bei der Eventverarbeitung als letztes geprüft

</source>

Da dieses Präfix bei eventverarbeitenden Definitionen in <code>$hash->{NTFY_ORDER}</code> dem Definitionsnamen vorangestellt wird bewirkt es bei einer normalen aufsteigenden Sortierung nach <code>$hash->{NTFY_ORDER}</code> eine veränderte Reihenfolge. Alle Module die in der Initialize-Funktion nicht <code>$hash->{NotifyOrderPrefix}</code> explizit setzen, werden mit "50-" als Standardwert vorbelegt.

==== X_Rename ====
<source lang="perl">
sub X_Rename ($$)
{
my ( $new_name, $old_name) = @_;

...
}
</source>

Die Rename-Funktion wird ausgeführt, nachdem ein Gerät umbenannt wurde. Auf diese Weise kann ein Modul auf eine Namensänderung reagieren, wenn das Gerät <code>$old_name</code> in <code>$new_name</code> umbenannt wurde. Ein typischer Fall ist das Umsetzen der Namensänderungen bei Daten die mittels [[DevelopmentModuleAPI#setKeyValue|setKeyValue()]] gespeichert wurden. Hierbei müssen die Daten, welche unter dem alten Namen gespeichert sind, auf den neuen Namen geändert werden.

Der Rename-Funktion wird lediglich der alte, sowie der neue Gerätename übergeben. Der Rückgabewert wird nicht ausgewertet.

Beispiel:
<source lang="perl">
sub X_Rename ($)
{
my ( $new_name, $old_name ) = @_;

my $old_index = "Module_X_".$old_name."_data";
my $new_index = "Module_X_".$new_name."_data";

my ($err, $data) = getKeyValue($old_index);
return undef unless(defined($old_pwd));

setKeyValue($new_index, $data);
setKeyValue($old_index, undef);
}
</source>

==== X_Shutdown ====
<source lang="perl">
sub X_Shutdown ($)
{
my ( $hash ) = @_;

...
}
</source>
Mit der X_Shutdown Funktion kann ein Modul Aktionen durchführen bevor FHEM gestoppt wird. Dies kann z.B. der ordnungsgemäße Verbindungsabbau mit dem physikalischen Gerät sein (z.B. Session beenden, Logout, etc.). Als Übergabeparameter wird der Geräte-Hash bereitgestellt. Der Rückgabewert einer Shutdown-Funktion wird nicht ausgewertet und ist daher irrelevant.

Beispiel:
<source lang="perl">
sub X_Shutdown($)
{
my ($hash) = @_;

# Verbindung schließen
DevIo_CloseDev($hash);
return undef;
}
</source>

=== Funktionen für zweistufiges Modulkonzept ===

Für das [[#Zweistufiges_Modell_für_Module|zweistufige Modulkonzept]] gibt es weiterhin:

{| class="wikitable sortable"
|-
! style="text-align:left" | Funktionsname !! style="text-align:left" class="unsortable" | Kurzbeschreibung
|-
| [[#X_Parse|X_Parse]] || Zustellen von Daten via [[DevelopmentModuleAPI#Dispatch|Dispatch()]] vom physischen Modul zum logischen Modul zwecks der Verarbeitung.
|-
| [[#X_Write|X_Write]]|| Zustellen von Daten via [[DevelopmentModuleAPI#Dispatch|IOWrite()]] vom logischen zum physischen Modul um diese an die Hardware weiterzureichen.
|-
| [[#X_Fingerprint|X_Fingerprint]] || Rückgabe eines "Fingerabdrucks" einer Nachricht. Dient der Erkennung von Duplikaten im Rahmen von [[DevelopmentModuleAPI#Dispatch|Dispatch()]]. Kann im physischen, als auch logischen Modul benutzt werden.
|}

Für das zweistufige Modulkonzept muss in einem logischen Modul eine [[#X_Parse|Parse]]-Funktion im Modul-Hash registriert werden. In einem physikalischen Modul muss eine [[#X_Write|Write]]-Funktion definiert sein. Diese dienem dem Datenaustausch in beide Richtungen und werden von dem jeweils anderen Modul indirekt aufgerufen.

In der [[#X_Initialize|Initialize]]-Funktion werden diese wie folgt definiert:

<source lang="perl">
$hash->{ParseFn} = "X_Parse";
$hash->{WriteFn} = "X_Write";
$hash->{FingerprintFn} = "X_Fingerprint";
</source>

Diese Funktionen werden in diesem Abschnitt genauer beschrieben.

==== X_Parse ====
{{Randnotiz|RNTyp=Info|RNText=<font color="red"><u>'''ACHTUNG''':</u></font>
Dieser Abschnitt geht davon aus, dass das Modul mit dem Namen "X" ein '''logisches Modul''' im Sinne des zweistufigen Modulkonzepts ist, also Daten mit einem übergeordneten, physikalischen Modul austauscht.}}
<source lang="perl">
sub X_Parse ($$)
{
my ( $io_hash, $message) = @_;

...

return $found;
}
</source>

Die Funktion X_Parse wird aufgerufen, sobald von dem IO-Gerät <code>$io_hash</code> eine Nachricht <code>$message</code> via [[DevelopmentModuleAPI#Dispatch|Dispatch()]] zur Verarbeitung angefragt wird. Die Parse-Funktion muss dann prüfen, zu welcher Gerätedefinition diese Nachricht gehört und diese entsprechend verarbeiten.

Üblicherweise enthält eine Nachricht immer eine Komponente durch welche sich die Nachricht einem Gerät zuordnen lässt (z.B. Adresse, ID-Nummer, ...). Eine solche Identifikation sollte man im Rahmen der [[#X_Define|Define]]-Funktion im logischen Modul an geeigneter Stelle speichern, um in der Parse-Funktion eine einfache Zuordnung von Adresse/ID einer Nachricht zur entsprechenden Gerätedefinition zu haben. Dazu wird in der Regel im Modul-Hash im modulspezifischen Berreich eine Liste <code>defptr</code> (Definition Pointer) geführt, welche jede eindeutige Adresse/ID dem entsprechenden Geräte-Hash zuordnet:

<source lang="perl">

sub X_Define ($$)
{
my ( $hash, $def) = @_;
my @a = split("[ \t][ \t]*", $def);
my $name = $a[0];

...

# erstes Argument ist die eindeutige Geräteadresse
my $address = $a[1];

# Adresse rückwärts dem Hash zuordnen (für ParseFn)
$modules{X}{defptr}{$address} = $hash;

...
}
</source>

Auf Basis dieses Definition Pointers kann die Parse-Funktion nun sehr einfach prüfen, ob für die empfangene Nachricht bereits eine entsprechende Gerätedefinition existiert. Sofern diese existiert, kann die Nachricht entsprechend verarbeitet werden. Sollte jedoch keine passende Gerätedefinition zu der empfangenen Nachricht existieren, so muss die Parse-Funktion den Gerätenamen "UNDEFINED" zusammen mit den Argumenten für einen <code>define</code>-Befehl zurückgeben, welcher ein passendes Gerät in FHEM anlegen würde (durch [[autocreate]]).

Beispiel:

<source lang="perl">

sub X_Parse ($$)
{
my ( $io_hash, $message) = @_;

# Die Stellen 10-15 enthalten die eindeutige Identifikation des Geräts
my $address = substr($message, 10, 5);

# wenn bereits eine Gerätedefinition existiert (via Definition Pointer aus Define-Funktion)
if(my $hash = $modules{X}{defptr}{$address})
{
... # Nachricht für $hash verarbeiten

# Rückgabe des Gerätenamens, für welches die Nachricht bestimmt ist.
return $hash->{NAME};
}
else
{
# Keine Gerätedefinition verfügbar
# Daher Vorschlag define-Befehl: <NAME> <MODULNAME> <ADDRESSE>
return "UNDEFINED X_".$address." X $address";
}
}
</source>

==== X_Write ====
{{Randnotiz|RNTyp=Info|RNText=<font color="red"><u>'''ACHTUNG''':</u></font>
Dieser Abschnitt geht davon aus, dass das Modul mit dem Namen "X" ein '''physisches Modul''' im Sinne des zweistufigen Modulkonzepts ist, also Daten mit untergeordneten logischen Modulen austauscht. }}
<source lang="perl">
sub X_Write ($$)
{
my ( $hash, @arguments) = @_;

...

return $return;
}
</source>

Die Write-Funktion wird durch die Funktion [[DevelopmentModuleAPI#IOWrite|IOWrite()]] aufgerufen, sobald eine logische Gerätedefinition Daten per IO-Gerät an die Hardware übertragen möchte. Dazu kümmert sich die Write-Funktion um die Übertragung der Nachricht in geeigneter Form an die verbundene Hardware. Als Argumente wird der Hash des physischen Gerätes übertragen, sowie alle weiteren Argumente, die das logische Modul beim Aufruf von IOWrite() mitgegeben hat. Im Normalfall ist das ein Skalar mit der zu sendenden Nachricht in Textform. Es kann aber auch sein, dass weitere Daten zum Versand notwendig sind (evtl. Schlüssel, Session-Key, ...). Daher ist die Parametersyntax einer zu schreibenden Nachricht via IOWrite-/Write-Funktion zwischen logischem und physikalischen Modul abzustimmen.

Beispiel:

<source lang="perl">
sub X_Write ($$)
{
my ( $hash, $message, $address) = @_;

DevIo_SimpleWrite($hash, $address.$message, 2);

return undef;
}
</source>

==== X_Fingerprint ====
<source lang="perl">
sub X_Fingerprint($$)
{
my ( $io_name, $msg ) = @_;

...

return ( $io_name, $fingerprint );
}
</source>

Die Fingerprint-Funktion dient der Erkennung von Duplikaten empfangener Nachrichten. Diese Funktion kann dabei sowohl im physischen, als auch im logischen Modul implementiert sein. Je nachdem auf welcher Ebene man für eine Nachricht einen Fingerprint bilden kann.

Als Parameter wird der Name des IO-Geräts <code>$io_name</code> übergeben, sowie die Nachricht <code>$msg</code>, welche empfangen wurde. Nun muss aus dieser Nachricht ein eindeutiger Fingerprint gebildet werden. Dies bedeutet, dass alle variablen Inhalte, die aufgrund des Empfangs dieser Nachricht über unterschiedliche IO-Geräte enthalten sein können, entfernt werden müssen. Dies können bspw. Empfangsadressen von IO-Geräten sein oder Session-ID's die in der Nachricht enthalten sind. Alle Fingerprints sämtlicher Nachrichten, die innerhalb der letzten 500 Millisekunden (konfigurierbar via <code>global</code> Attribut <code>dupTimeout</code>) empfangen wurden, werden gegen diesen generierten Fingerprint getestet. Sollte innerhalb dieser Zeit bereits eine Nachricht mit diesem Fingerprint verarbeitet worden sein, so wird sie als Duplikat erkannt und nicht weiter verarbeitet. In diesem Fall gibt [[DevelopmentModuleAPI#Dispatch|Dispatch()]] den Namen der Gerätedefinition zurück, welche eine Nachricht mit dem selben Fingerprint bereits verarbeitet hat. Es erfolgt dann kein Aufruf der [[#X_Parse|Parse]]-Funktion.

Beispiel:

<source lang="perl">
sub X_Fingerprint($$)
{
my ( $io_name, $msg ) = @_;

substr( $msg, 2, 2, "--" ); # entferne Empfangsadresse
substr( $msg, 4, 1, "-" ); # entferne Hop-Count

return ( $io_name, $msg );
}
</source>

Es wird zuerst, sofern implementiert, die Fingerprint-Funktion des physischen Moduls aufgerufen. Sollte sich hierdurch kein Duplikat erkennen lassen, wird die Fingerprint-Funktion jedes möglichen geladenen logischen Moduls aufgerufen, sofern implementiert.

Sollte sowohl im physischen, als auch im logischen Modul keine Fingerprint-Funktion implementiert sein, so wird keinerlei Duplikatserkennung durchgeführt.

=== FHEMWEB-spezifische Funktionen ===

FHEMWEB bietet Modulautoren die Möglichkeit an durch spezielle Funktionsaufrufe in Modulen, eigene HTML-Inhalte zu verwenden. Dadurch können in Verbindung mit zusätzlichem JavaScript komplexe Dialoge/Inhalte/Steuermöglichkeiten dargestellt werden.

Eine genaue Auflistung aller FHEMWEB-spezifischen Funktionsaufrufe gibt es in dem separaten Artikel [[DevelopmentFHEMWEB]]

=== sonstige Funktionen ===

In diesem Abschnitt werden weitere Funktionen behandelt die zum Teil aus FHEM, aber auch aus anderen Modulen aufgerufen werden. Sie sind dabei nur in speziellen Anwendungsfällen relevant. Hier eine Auflistung aller sonstigen Modulfunktionen:

{| class="wikitable sortable"
|-
! Funktionsname !! class="unsortable" | Kurzbeschreibung
|-
| [[#X_DbLog_split|X_DbLog_split]] || Wird durch das Modul 93_DbLog.pm aufgerufen. Dient dem korrekten Split eines moduleigenen Events in Name/Wert/Einheit für die Nutzung einer Datenbank.
|-
| [[#X_Except|X_Except]]|| Wird aufgerufen, sobald ein ein geöffneter Filedescriptor in [[#Wichtige_globale_Variablen_aus_fhem.pl|<code>%selectlist</code>]], der unter <code>$hash->{EXCEPT_FD}</code> im Geräte-Hash gesetzt ist, einen Interrupt bzw. Exception auslöst.
|-
| [[#X_Copy|X_Copy]]|| Wird durch das Modul 98_copy.pm aufgerufen im Rahmen des <code>copy</code>-Befehls sobald ein Gerät kopiert wurde.
|-
| [[#X_State|X_State]]|| Wird aufgerufen im Rahmen des <code>setstate</code>-Befehls bevor der Status einer Gerätedefinition bzw. eines zugehörigen Readings gesetzt wird.
|-
| [[#X_AsyncOutput|X_AsyncOutput]]|| Nur Relevant für Module die via [[TcpServerUtils]] eine Client-Verbindung zu FHEM ermöglichen (z.B. FHEMWEB und telnet). Ermöglicht die asynchrone Ausgabe von Daten via [[DevelopmentModuleAPI#asyncOutput|asyncOutput()]] an einen einzelnen verbundenen Client.
|-
| [[#X_ActivateInform|X_ActivateInform]]|| Nur Relevant für Module die via [[TcpServerUtils]] eine Client-Verbindung zu FHEM ermöglichen (z.B. FHEMWEB und telnet). Ermöglicht das aktivieren des inform-Mechanismus zum senden von Events für einen einzelnen verbundenen Client.
|-
| [[#X_Authorize|X_Authorize]]|| Wird aufgerufen im Rahmen von [[DevelopmentModuleAPI#Authorize|Authorize()]] um eine gewünschte Vorgangs-Art zu autorisieren.
|-
| [[#X_Authenticate|X_Authenticate]]|| Wird aufgerufen im Rahmen von [[DevelopmentModuleAPI#Authenticate|Authenticate()]] um eine Authentifizierung zu prüfen und ggf. zu genehmigen.
|}

In der [[#X_Initialize|Initialize]]-Funktion werden diese wie folgt definiert:

<source lang="perl">
$hash->{DbLog_splitFn} = "X_DbLog_split";
$hash->{ExceptFn} = "X_Except";
$hash->{CopyFn} = "X_Copy";
$hash->{AsyncOutputFn} = "X_AsyncOutput";
$hash->{ActivateInformFn} = "X_ActivateInform";
$hash->{StateFn} = "X_State";
$hash->{AuthorizeFn} = "X_Authorize";
$hash->{AuthenticateFn} = "X_Authenticate";
</source>

Diese Funktionen werden in diesem Abschnitt genauer beschrieben.
==== X_DbLog_split ====
<source lang="perl">
sub X_DbLog_split ($$)
{
my ( $event, $device_name ) = @_;

...

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

Die DbLog_split-Funktion wird durch das Modul [[DbLog]] aufgerufen, sofern der Nutzer DbLog benutzt. Sofern diese Funktion implementiert ist, kann der Modulautor das Auftrennen von Events in den Reading-Namen, -Wert und der Einheit selbst steuern. Andernfalls nimmt DbLog diese Auftrennung selber mittels Trennung durch Leerzeichen sowie vordefinierten Regeln zu verschiedenen Modulen vor. Je nachdem, welche Readings man in seinem Modul implementiert, passt diese standardmäßige Trennung jedoch nicht immer.

Der Funktion werden folgende Eingangsparameter übergeben:
# Das generierte Event (Bsp: <code>temperature: 20.5 °C</code>)
# Der Name des Geräts, welche das Event erzeugt hat (Bsp: <code>Temperatursensor_Wohnzimmer</code>)

Es ist nicht möglich in der DbLog_split-Funktion auf die verarbeitende DbLog-Definition zu referenzieren.

Als Rückgabewerte muss die Funktion folgende Werte bereitstellen:
# Name des Readings (Bsp: <code>temperature</code>)
# Wert des Readings (Bsp: <code>20.5</code>)
# Einheit des Readings (Bsp: <code>°C</code>)

Beispiel:
<source lang="perl">
sub X_DbLog_splitFn($$)
{
my ($event, $device) = @_;
my ($reading, $value, $unit);
my $devhash = $defs{$device}

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

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

==== X_Except ====
<source lang="perl">
sub X_Except ($)
{
my ( $hash ) = @_;

...
}
</source>

Die X_Except-Funktion wird durch fhem.pl aufgerufen, wenn die Gerätedefinition <code>$hash</code> in <code>[[#Wichtige_globale_Variablen_aus_fhem.pl|%selectlist]]</code> aufgeführt ist und der Filedeskriptor in <code>$hash->{EXCEPT_FD}</code> eine Exception bzw. Interrupt auslöst.

Der Rückgabewert wird nicht ausgewertet und ist daher irrelevant.

Beispiel:

<source lang="perl">
use IO::File;

...

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

# Filehandle aus Filedescriptor erstellen
my $filehandle = IO::File->new_from_fd($hash->{EXCEPT_FD}, 'r');
seek($filehandle,0,0);

# aktuellen Inhalt auslesen
my $current_value = $filehandle->getline;

if($current_value eq "1")
{
...
}
else
{
...
}
}
</source>

==== X_Copy ====
<source lang="perl">
sub X_Copy ($)
{
my ( $old_name, $new_name ) = @_;

...
}
</source>

Die X_Copy-Funktion wird durch das Modul [[copy]] aufgerufen nachdem ein Nutzer eine Gerätedefinition über den Befehl <code>copy</code> kopiert hat. Dazu werden als Funktionsparameter die Definitionsnamen der alten und neuen Gerätedefinition übergeben. Es dient dazu zusätzliche Daten aus der zu kopierenden Gerätedefinition in die neue Definition zu übernehmen. Der Befehl <code>copy</code> überträgt lediglich <code>$hash->{DEF}</code> in die neue Definition sowie sämtliche gesetzte Attribute. Weitere Daten müssen dann durch die X_Copy-Funktion übertragen werden.

Die X_Copy-Funktion wird erst nach dem erfolgtem Kopiervorgang aufgerufen.

Der Rückgabewert wird nicht ausgewertet und ist daher irrelevant.

Beispiel:

<source lang="perl">

sub X_Copy ($$)
{
my ( $old_name, $new_name ) = @_;

my $old_hash = $defs{$old_name};
my $new_hash = $defs{$new_name};

# copy also temporary session key
$new_hash->{helper}{SESSION_KEY} = $old_hash->{helper}{SESSION_KEY};
}
</source>

==== X_AsyncOutput ====
TBD

==== X_ActivateInform ====
TBD
==== X_State ====
<source lang="perl">
sub X_State($)
{
my ( $hash, $time, $readingName, $value ) = @_;

...

return $error;
}
</source>

Die X_State-Funktion wird durch fhem.pl aufgerufen, sobald über den Befehl <code>setstate</code> versucht wird ein Wert für ein Reading oder den Status (<code>$hash->{STATE}</code>) einer Gerätedefinition zu setzen. Dieser Befehl wird primär beim Starten von FHEM aufgerufen sobald das State-File eingelesen wird. Je nachdem, ob im gegebenen Fall ein Reading oder der Definitionsstatus gesetzt wird, haben die Übergabeparameter verschiedene Werte:

{| class="wikitable"
|-
! Funktionsparameter!! Wert beim Setzen eines Readings !! Wert beim Setzen eines Definitionsstatus
|-
| <code>$hash</code> || colspan=2 align=center | Die Hashreferenz der betreffenden Gerätedefinition
|-
| <code>$time</code>|| Der Zeitstempel auf welchen das Reading <code>$readingName</code> gesetzt werden soll. Das Ergebnis entspricht dem Rückgabewert der Funktion || Der aktuelle Zeitstempel zum jetzigen diesem Zeitpunkt.
|-
| <code>$readingName</code>|| Der Name des Readings, welches auf einen neuen Wert gesetzt werden soll. || Statischer Wert "STATE" um anzuzeigen, dass es sich um den Definitionsstatus handelt, welcher gesetzt werden soll (<code>$hash->{STATE}</code>).
|-
| <code>$value</code> || Der Wert, welchen das Reading <code>$readingName</code> annehmen soll. || Der Wert, welchen die Gerätedefinition als Status annehmen soll.
|}

Wenn via <code>setstate</code> ein Reading gesetzt wird, kann die X_State-Funktion das Setzen dieses Readings durch die Rückgabe einer aussagekräftigen Fehlermeldung unterbinden. Sofern <code>undef</code> zurückgegeben wird, wird das entsprechende Reading auf den übergebenen Status gesetzt.

Wenn via <code>setstate</code> der Definitionsstatus gesetzt wird, wird die X_State-Funktion erst nach dem Setzen des Status aufgerufen. Man kann dabei zwar eine Fehlermeldung zurückgeben. Der Status wird aber dennoch übernommen. Die Fehlermeldung wird lediglich dem Nutzer angezeigt.

Beispiel:

<source lang="perl">
sub X_State($)
{
my ( $hash, $time, $readingName, $value ) = @_;

return undef if($readingName "STATE" || $value ne "inactive");
readingsSingleUpdate($hash, "state", "inactive", 1);
return undef;
}
</source>

==== X_Authorize ====
TBD

==== X_Authenticate ====
TBD

== Bereitstellen eines eigenen Befehls (Befehlsmodul) ==

Ein Modul kann primär einen neuen FHEM-Befehl bereitstellen. Man spricht in so einem Fall nicht von einem Gerätemodul, sondern einem Befehlsmodul. Ein solches Befehlsmodul stellt nur einen einzelnen Befehl bereit, der dem Modulnamen entsprechen muss. Nur, wenn der Modulname dem Befehlsname entspricht, kann FHEM das Modul beim ersten Ausführen dieses unbekannten Befehls finden und nachladen.

Der entsprechende Befehl wird dazu in der [[#X_Initialize|Initialize]]-Funktion im globalen Hash <code>[[DevelopmentModuleIntro#Wichtige_globale_Variablen_aus_fhem.pl|%cmds]]</code> registriert:

<source lang="perl">
sub X_Initialize($$) {

$cmds{X} = { Fn => "CommandX",
Hlp => "<argument1> [optional_argument2], print something very useful",

# optional
ClientFilter => "FHEMWEB"
};
}
</source>

Damit wird der neue Befehl <code>X</code> in FHEM registriert. Die Funktion mit dem Namen <code>CommandX</code> setzt diesen Befehl innerhalb des Moduls um. Desweiteren wird eine kurze Aufrufsyntax mitgegeben, welche beim Aufruf des <code>help</code>-Befehls dem Nutzer angezeigt wird um als Gedankenstütze zu dienen. Optional kann man mittels <code>ClientFilter</code> die Ausführbarkeit nur auf bestimmte Client-Module (wie FHEMWEB oder telnet) beschränken.

Nun muss noch die Funktion <code>CommandX</code> im Rahmen des Moduls implementiert werden, welche den Befehl <code>X</code> umsetzt:

<source lang="Perl">
sub CommandX($$)
{
my ($client_hash, $arguments) = @_;

...

return $output;
}
</source>

Dabei werden der Befehlsfunktion zwei Parameter übergeben. Zuerst die Hash-Referenz des aufrufenden Clients (sofern manuell ausgeführt, ansonsten <code>undef</code>) zwecks Rechteprüfung via [[allowed|allowed-Definitionen]]. Anschließend folgen die Aufrufparameter als zusammenhängende Zeichenkette. Die Trennung der einzelnen Argumente obligt der Funktion (bspw. via [[DevelopmentModuleAPI#parseParams|parseParams()]]). Als Funktionsrückgabewert wird eine Ausgabemeldung erwartet, die dem Nutzer angezeigt werden soll.

== Pollen von Geräten ==
Wenn Geräte von sich aus keine Informationen senden sondern abgefragt werden müssen, kann man im Modul die Funktion [[DevelopmentModuleAPI#InternalTimer|InternalTimer()]] verwenden um einen Funktionsaufruf zu einem späteren Zeitpunkt durchführen zu können. Man übergibt dabei den Zeitpunkt für den nächsten Aufruf, den Namen der Funktion, die aufgerufen werden soll, sowie den zu übergebenden Parameter. Als zu übergebender Parameter wird üblicherweise der Hash der betroffenen Geräteinstanz verwendet. Damit hat die aufgerufene Funktion Zugriff auf alle wichtigen Daten der Geräteinstanz. Eventuell zusätzlich benötigte Werte können einfach als weitere Internals über den Hash zugänglich gemacht werden.

Beispielsweise könnte man für das Abfragen eines Geräts in der [[#X_Define|Define]]-Funktion den Timer folgendermaßen setzen:

<source lang="perl">
InternalTimer(gettimeofday()+2, "X_GetUpdate", $hash);
</source>

Alternativ kann man auch in der [[#X_Notify|Notify]]-Funktion auf das Event <code>global:INITIALIZED</code> bzw. <code>global:REREADCFG</code> reagieren und erst dort, den Timer anstoßen, sobald die Konfiguration komplett eingelesen wurde. Dies ist insbesondere notwendig, wenn man sicherstellen will, dass alle Attribute aus der Konfiguration gesetzt sind, sobald man einen Status-Update initiiert.

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

<source lang="perl">
sub X_GetUpdate($)
{
my ($hash) = @_;
my $name = $hash->{NAME};
Log3 $name, 4, "X: GetUpdate called ...";

...

# neuen Timer starten in einem konfigurierten Interval.
InternalTimer(gettimeofday()+$hash->{Interval}, "X_GetUpdate", $hash);
}
</source>

Innerhalb der Funktion kann man nun das Gerät abfragen und die abgefragten Werte in Readings speichern. Falls das Abfragen der Werte jedoch zu einer Verzögerung und damit zu einer Blockade von FHEM führen kann, ist es möglich, in der GetUpdate-Funktion nur die Aufforderung zum Senden bestimmter Daten an das angeschlossene Gerät zu senden und dann das Lesen über die oben beschriebene [[#X_Read|Read]]-Funktion zu implementieren.

Eine genaue Beschreibung der Timer-Funktion gibt es [[DevelopmentModuleAPI#Timer|hier im Wiki]]

== Logging / Debugging ==
Um Innerhalb eines Moduls eine Log-Meldung in die FHEM-Logdatei zu schreiben, wird die Funktion [[DevelopmentModuleAPI#Log3|Log3()]] aufgerufen.
<source lang="perl">
Log3 $name, 3, "X ($name) - Problem erkannt ...";
</source>
Eine genaue Beschreibung zu der Funktion inkl. Aufrufparameter findet man [[DevelopmentModuleAPI#Log3|hier]]. Es ist generell ratsam in der Logmeldung sowohl den Namen des eigenen Moduls zu schreiben, sowie den Namen des Geräts, welche diese Logmeldung produziert, da die Meldung, so wie sie ist, direkt in das Logfile wandert und es für User ohne diese Informationen schwierig ist, die Meldungen korrekt zuzuordnen.

Die Funktion Log3() verwendet den Namen der Geräteinstanz um das <code>verbose</code>-Attribut zu prüfen. In der Regel wird bei Modulfunktionen jedoch immer nur der Gerätehash <code>$hash</code> übergeben. Um den Namen der Definition zu ermitteln ist es daher notwendig sich diesen aus dem Hash extrahieren:

<source lang="perl">
my $name = $hash->{NAME};
</source>

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

Logmeldungen sollten je nach Art und Wichtigkeit für den Nutzer in unterschiedlichen Loglevels erzeugt werden. Es gibt insgesamt 5 Stufen in denen geloggt werden kann. Standardmäßig steht der systemweite Loglevel (<code>global</code>-Attribut <code>verbose</code>) auf der Stufe 3. Die Bedeutung der jeweiligen Stufen ist in der [http://fhem.de/commandref_DE.html#verbose commandref] beschrieben.

Während der Entwicklung eines Moduls kann man für eigene Debug-Zwecke auch die Funktion [[DevelopmentModuleAPI#Debug|Debug()]] verwenden um schnell und einfach Debug-Ausgaben in das Log zu schreiben. Diese sollten in der endgültigen Fassung jedoch nicht mehr vorhanden sein. Sie dienen ausschließlich zum Debugging während der Entwicklung.

Eine genaue Beschreibung der Log-Funktion gibt es [[DevelopmentModuleAPI#Logging|hier im Wiki]].

== Zweistufiges Modell für Module ==
[[Datei:Zweistufiges Modulkonzept.jpg|mini|rechts]]
Es gibt viele Geräte, welche die Kommunikation mit weiteren Geräten mit tlw. unterschiedlichen Protokollen ermöglichen. Das typischste Beispiel bietet hier der [[CUL]], welcher via Funk mit verschiedenen Protokollen weitere Geräte ansprechen kann (z.B. Aktoren, Sensoren, ...). Hier bildet ein Gerät eine Brücke durch die weitere Geräte in FHEM zugänglich gemacht werden können. Dabei werden über einen Kommunikationsweg (z.B. serielle Schnittstelle, TCP, ...) beliebig viele Geräte gesteuert. Typische Beispiele dazu sind:

* [[CUL]]: stellt Geräte mit verschiedenen Kommunikationsprotokollen via Funk bereit (u.a. [[FS20]], [[HomeMatic]], [[Funk-Heizkörperregler_Kurz-Bedienungsanleitung_FHT|FHT]], [[MAX]], ...)
* [[HMLAN]]: stellt HomeMatic Geräte via Funk bereit
* [[MAX#MAXLAN|MAXLAN]]: stellt [[MAX|MAX!]] Geräte via Funk bereit
* [[PanStamp#panStick.2FShield|panStamp]]: stellt weitere panStamp Geräte via Funk bereit

Dabei wird die Kommunikation in 2 Stufen unterteilt:
* physisches Modul - z.B. 00_CUL.pm - zuständig für die physikalische Kommunikation mit der Hardware. Empfangene Daten müssen einem logischen Modul zugeordnet werden.
* logische Modul(e) - z.B. 10_FS20.pm - interpretiert protokollspezifische Nachrichten. Sendet protokollspezifische Daten über das physische Modul an die Hardware.

<u>physisches Modul</u>

Das physische Modul öffnet die Datenverbindung zum Gerät (z.B. CUL) und verarbeitet sämtliche Daten. Es kümmert sich um den Erhalt der Verbindung (bsp. durch Keep-Alives) und konfiguriert das Gerät so, dass eine Kommunikation mit allen weiteren Geräten möglich ist (bsp. Frequenz, Modulation, Kanal, etc.).

Empfangene Nutzdaten werden über die Funktion [[DevelopmentModuleAPI#Dispatch|Dispatch()]] an logische Module weitergegeben.

Das Modul stellt eine [[#Die_Match-Liste|Match-Liste]] bereit, anhand FHEM die Nachricht einem Modul zuordnen kann, sofern dieses noch nicht geladen sein sollte. FHEM lädt dann automatisch dieses Modul nach, zwecks Verarbeitung der Nachricht. Anhand einer bereitgestellten [[#Die_Client-Liste|Client-Liste]] kann FHEM feststellen, welche logischen Module mit diesem Modul kommunizieren können.

Das Modul stellt eine [[#X_Write|Write]]-Funktion zur Verfügung, über die logische Module Daten an die Hardware übertragen können.

<u>logisches Modul</u>

Das logische Modul interpretiert die Nachricht über eine bereitgestellte [[#X_Parse|Parse]]-Funktion und erzeugt entsprechende Readings/Events. Es stellt über <code>set</code>-/<code>get</code>-Kommandos Steuerungsmöglichkeiten dem Nutzer zur Verfügung.

Es stellt FHEM einen [[#Der_Match-Ausdruck|Match-Ausdruck]] zur Verfügung anhand FHEM ermitteln kann, ob die Nachricht durch das logische Modul verarbeitet werden kann.

=== Die Client-Liste ===

Die Client-Liste ist eine Auflistung von Modulnamen (genauer: regulären Ausdrücken die auf Modulnamen passen) die in einem physischen Modul gesetzt ist. Damit wird definiert, mit welche logischen Modulen das physikalische Modul kommunizieren kann.

Eine Client-Liste ist eine Zeichenkette, welche aus allen logischen Modulnamen besteht. Die einzelnen Namen werden durch einen Doppelpunkt getrennt. Anstatt kompletter Modulnamen können auch reguläre Ausdrücke verwendet werden, die auf mehrere Modulnamen passen.

Bsp.: Die Client-Liste von dem Modul CUL lautet daher wie folgt:

FS20:FHT.*:KS300:USF1000:BS:HMS:CUL_EM:CUL_WS:CUL_FHTTK:CUL_HOERMANN:ESA2000:CUL_IR:CUL_TX:Revolt:IT:UNIRoll:SOMFY:STACKABLE_CC:CUL_RFR:CUL_TCM97001:CUL_REDIRECT

Alle hier aufgelisteten Module können über das Modul CUL Daten empfangen bzw. senden.

Die Client-Liste hat generell folgende Funktion:
* Die Funktion [[DevelopmentModuleAPI#Dispatch|Dispatch()]] prüft nur Module, welche in der Client-Liste enthalten sind, ob diese die Nachricht verarbeiten können.
* Die Funktion [[DevelopmentModuleAPI#AssignIoPort|AssignIoPort()]] prüft anhand sämtlicher Client-Listen in FHEM, welches IO-Gerät für ein logisches Gerät nutzbar ist.

Üblicherweise wird die Client-Liste in der [[#X_Initialize|Initialize]]-Funktion im Modul-Hash gesetzt:

<source lang="perl">
sub X_Initialize($)
{
my ($hash) = @_;
...
$hash->{Clients} = "FS20:KS300:FHT.*";
}
</source>

Man kann die Client-Liste jedoch auch pro physikalisches Gerät setzen. Eine gesetzte Client-Liste in einem Gerät hat immer Vorrang vor der Liste im Modul-Hash. Eine gerätespezifische Client-Liste wird dann verwendet, wenn bspw. ein Gerät je nach Konfiguration nur bestimmte logische Module bedienen kann. Bspw. kann ein CUL je nach RF-Einstellungen FS20, uvm. oder nur HomeMatic bedienen. In einem solchen Fall wird die Client-Liste im Geräte-Hash gesetzt:

<source lang="perl">
sub X_Define($$)
{
my ( $hash, $def ) = @_;
...
$hash->{Clients} = "CUL_HM";
}
</source>

In vielen Modulen, welche nach dem zweistufigem Konzept arbeiten, beginnt und endet die Client-Liste mit einem Doppelpunkt. Dies ist ein historisches Überbleibsel, da der Prüfmechanismus die Client-Liste früher auf das Vorhandensein von <code>'''<u><font color="red">:</font></u>'''<Modulname>'''<u><font color="red">:</font></u>'''</code> prüfte. Dies ist nun nicht mehr notwendig. Die einzelnen Modulnamen müssen lediglich durch einen Doppelpunkt getrennt werden.

=== Die Match-Liste ===
{{Randnotiz|RNTyp=Info|RNText=<font color="red"><u>'''ACHTUNG''':</u></font>
Sämtliche regulären Ausdrücke in der Match-Liste werden "case insensitive" überprüft. Das bedeutet, dass Groß-/Kleinschreibung nicht berücksichtigt wird.

Um dennoch in einem regulären Ausdruck auf Groß-/Kleinschreibung zu prüfen, kann man dieses mit dem Modifizierer <code>(?-i)</code> wieder aktivieren:

<source lang="perl">
my %matchListFHEMduino = (
....
"5:FHEMduino_PT2262" => "^(?-i)IR.*\$",
....
"13:IT" => "^(?-i)i......\$",
);
</source>

Siehe dazu Forumsbeitrag: {{Link2Forum|Topic=33422}}
}}
Die Match-Liste ordnet eine Nachrichtensyntax (regulärer Ausdruck) einem Modulnamen zu und wird in einem physikalischen Modul gesetzt. Sollte eine Nachricht vom physikalischen Gerät empfangen werden, die durch kein geladenes Modul verarbeitet werden kann, so wird über die Match-Liste geprüft, welches Modul diese Nachricht verarbeiten kann. Dieses Modul wird anschließend geladen und die Nachricht durch dieses verarbeitet. In dieser Liste findet mittels regulärem Ausdruck eine Zuordnung der Nachrichtenstruktur zum verarbeitenden logischen Modul statt.

Diese Liste wird ausschließlich in der [[DevelopmentModuleAPI#Dispatch|Dispatch()]]-Funktion verwendet. Sollte keine passendes Modul, welches bereits geladen ist, zur Verarbeitung einer Nachricht gefunden werden, so wird mithilfe der Match-Liste aufgrund der vorliegenden Nachricht das entsprechende Modul ermittelt. Dieses Modul wird dann direkt geladen und die Nachricht wird via [[#X_Parse|Parse]]-Funktion verarbeitet.

Die Match-Liste ist eine Zuordnung von einem Sortierpräfix + Modulname zu einem regulären Ausdruck:

<source lang="perl">
{
"1:FS20" => "^81..(04|0c)..0101a001",
"2:KS300" => "^810d04..4027a001",
"3:FHT" => "^81..(04|09|0d)..(0909a001|83098301|c409c401).."
}
</source>

Das Sortierpräfix dient als Sortierhilfe um so die Reihenfolge der Prüfung festzulegen. Bei der Prüfung wird der Hash mittels sort() sortiert und die regulären Ausdrücke werden dann nacheinander getestet. Daher sollten die präzisesten Ausdrücke immer zuerst getestet werden, sofern es weniger präzise Ausdrücke in der Match-Liste gibt. Dabei ist zu beachten, dass der Sortierpräfix nicht nach numerischen Regeln sortiert wird, sondern basierend auf der Zeichenreihenfolge.

Üblicherweise wird die Match-Liste in der [[#X_Initialize|Initialize]]-Funktion im Modul-Hash gesetzt:

<source lang="perl">
sub X_Initialize($)
{
my ($hash) = @_;

...

$hash->{MatchList} = { "1:FS20" => "^81..(04|0c)..0101a001",
"2:KS300" => "^810d04..4027a001",
"3:FHT" => "^81..(04|09|0d)..(0909a001|83098301|c409c401).." };
}
</source>

Man kann die Match-Liste, ähnlich wie bei der Client-Liste, auch pro physikalisches Gerät setzen. Dabei hat auch hier die Match-Liste eines Gerätes immer Vorrang vor der Match-Liste aus dem Modul-Hash:

<source lang="perl">
sub X_Define($$)
{
my ($hash, $def) = @_;

...

$hash->{MatchList} = { "1:CUL_HM" => "^A...................." };
}
</source>

=== Der Match-Ausdruck ===

Ein Match-Ausdruck wird in einem logischen Modul gesetzt und dient der Prüfung, ob eine Nachricht durch das eigene Modul via [[#X_Parse|Parse]]-Funktion verarbeitet werden kann. Es handelt sich hierbei um einen einzelnen regulären Ausdruck, den FHEM innerhalb der [[DevelopmentModuleAPI#Dispatch|Dispatch()]]-Funktion prüft. Nur wenn eine Nachricht via Dispatch() auf diesen Audruck matcht, wird die Parse-Funktion aufgerufen um die Nachricht zu verarbeiten.

Der Hintergrund, warum man den Aufruf mit einem solchen Ausdruck vorher abprüft, liegt in der Möglichkeit, dass ein physikalisches Modul mehrere unterschiedliche logische Module ansprechen kann. So kann FHEM jedes geladene Modul durch diesen Match-Ausdruck prüfen, ob es diese Nachricht verarbeiten kann. Erst, wenn alle geladenen Module, aufgrund einer Prüfung des Ausdrucks, die Nachricht nicht verarbeiten können, wird via [[#Die_Match-Liste|Match-Liste]] ermittelt, welches Modul geladen werden muss um die Nachricht zu verarbeiten.

Der Match-Ausdruck wird in der [[#X_Initialize|Initialize]]-Funktion zur Verfügung gestellt:

<source lang="perl">
sub X_Initialize($)
{
my ($hash) = @_;

...

# Dieses Modul verarbeitet FS20 Nachrichten
$hash->{Match} = "^81..(04|0c)..0101a001";
}
</source>
=== Die vollständige Implementierung ===

Hier nun eine Zusammenfassung beim zweistufigen Modulkonzept in der jeweiligen Stufe implementiert werden muss, damit die Kommunikation funktioniert.

==== physisches Modul ====

Das physische Modul, welches als Kommunikationsbrücke zwischen der Hardware und logischen Modulen fungieren wird, sollte mindestens folgende Funktionen implementieren:

* [[#X_Initialize|Initialize]]-Funktion - Zum Registrieren des Moduls in FHEM.
* [[#X_Define|Define]]-Funktion - Zum öffnen der Datenverbindung zur Hardware (IP-Adresse/serielle Schnittstelle/...).
* [[#X_Read|Read]]-Funktion - Zum Lesen von Daten, welche die Hardware übermittelt.
* [[#X_Read|Ready]]-Funktion - Zum Wiederaufbau der Verbindung bei Verbindungsabbruch, bzw. Prüfung auf lesbare Daten bei serieller Schnittstelle unter Windows.
* [[#X_Write|Write]]-Funktion - Zum Senden von Daten, welche logische Module via [[DevelopmentModuleAPI#IOWrite|IOWrite()]] an die Hardware übertragen möchten.
* [[#X_Undef|Undef]]-Funktion - Schließen der Verbindung zur Hardware beim Löschen via <code>delete</code> bzw. <code>rereadcfg</code>.
* [[#X_Shutdown|Shutdown]]-Funktion - Schließen der Verbindung zur Hardware beim Stopp von FHEM via <code>shutdown</code>.

Desweiteren müssen in der [[#X_Initialize|Initialize]]-Funktion folgende Daten bereitgestellt werden:

* [[#Die_Client-Liste|Client-Liste]] - Auflistung aller logischen Module, die über dieses Modul kommunizieren können
* [[#Die_Match-Liste|Match-Liste]] - Zuordnung von Nachrichtensyntax zu Modul zwecks Autoload-Funktionalität.

==== logisches Modul ====

Das logische Modul, bildet ein einzelnes Gerät ab, über das mit einem physikalisches Modul kommuniziert werden kann. Es sollte mindestens folgende Funktionen implementieren:

* [[#X_Initialize|Initialize]]-Funktion - Zum Registrieren des Moduls in FHEM.
* [[#X_Define|Define]]-Funktion - Speichern des Definition Pointers (siehe [[#X_Parse|Parse-Funktion]])
* [[#X_Parse|Parse]]-Funktion - Zum Lesen von Daten, welche die Hardware übermittelt.
* [[#X_Undef|Undef]]-Funktion - Löschen des Definition Pointers beim Löschen via <code>delete</code> bzw. <code>rereadcfg</code>.

Desweiteren müssen in der [[#X_Initialize|Initialize]]-Funktion folgende Daten bereitgestellt werden:

* [[#Der_Match-Ausdruck|Match-Ausdruck]] - Prüfausdruck, ob eine Nachricht durch dieses Modul verarbeitet werden kann.

=== Kommunikation von der Hardware bis zu den logischen Modulen ===

Die Gerätedefinition eines physische Moduls öffnet eine Verbindung zur Hardware. Die [[#X_Read|Read]]-Funktion wird bei anstehenden Daten aus der Hauptschleife von fhem.pl aufgerufen.

Die Read-Funktion stellt dabei sicher, dass die Daten
* komplett (in der Regel über einen internen Puffer in <code>$hash</code>) und
* korrekt (z.B. via Prüfung mittels regulärem Ausdruck)
sind und ruft die globale Funktion [[DevelopmentModuleAPI#Dispatch|Dispatch()]] mit einer kompletten Nachricht auf.

Die Funktion Dispatch() sucht nach einer passenden Definition via [[#Die_Client-Liste|Client-Liste]] in physischen Definitionen/Modulen nach möglichen logischen Modulen zur Verarbeitung. Alle zum Zeitpunkt geladenen Module, die in der Client-Liste aufgeführt sind, werden über den [[#Der_Match-Ausdruck|Match-Ausdruck]] geprüft, ob sie mit der Nachricht etwas anfangen können. Sollte bei einem Modul der Match-Ausdruck passen, so wird die entsprechende [[#X_Parse|Parse]]-Funktion des logischen Moduls aufgerufen. Sofern keine passendes Modul gefunden wurde, um die Nachricht zu verarbeiten, wird in der [[#Die_Match-Liste|Match-Liste]] im Geräte- bzw. Modul-Hash der physischen Gerätedefinition nach dem passenden Modul gesucht. Sollte es darin ein Modul geben, was diese Art von Nachricht verarbeiten kann, so wird versucht dieses Modul zu laden um nun die Nachricht via Parse-Funktion zu verarbeiten. Es erfolgt in diesem Fall keine Vorprüfung durch den Match-Ausdruck.

Durch Dispatch() wird nun die [[#X_Parse|Parse]]-Funktion des gefundenen logischen Moduls aufgerufen. Diese
* interpretiert die übergebene Nachricht,
* versucht eine existierende Gerätedefinition in FHEM zu finden (z.B. mittels Definition Pointer), für welche die Nachricht addressiert ist,
* setzt alle [[#Readings|Readings]] für die gefundene Gerätedefinition via [[DevelopmentModuleAPI#Readings_.2F_Events|readings*update]]()-Funktionen,
* gibt den Namen der logischen Definition zurück, welche die Nachricht verarbeitet hat.

Sollte keine passende Gerätedefinition für die entsprechende Nachricht existieren (Adresse/ID/Kanal/...), wird der Gerätename "UNDEFINED" inkl. einem passenden <code>define</code>-Statement zurückgegeben, um die Definition durch [[autocreate]] erzeugen zu lassen.

Es findet während der Verarbeitung einer Nachricht durch Dispatch()/Parse-Funktion keine sofortige Eventverarbeitung (via [[DevelopmentModuleAPI#Dispatch|DoTrigger()]]) statt, wenn die [[DevelopmentModuleAPI#Readings_.2F_Events|readings*update]]()-Funktionen verwendet werden.
(Im Gegensatz zum direkten Aufrufen der readings*update Funktionen ohne vorhergehendes Dispatch() )

Die Funktion Dispatch() triggert das Event-Handling für das von der Parse-Funktion zurückgegebene logische Device selbstständig.

Optional führt die Funktion Dispatch() eine Überprüfung auf Nachrichtenduplikate beim Einsatz von mehreren IO-Geräten durch. Dazu wird eine implementierte [[#X_Fingerprint|Fingerprint]]-Funktion im physischen oder logischen Modul benötigt.

=== Kommunikation von den logischen Modulen bis zur Hardware ===

Um von einem logischen Modul eine Nachricht an die Hardware senden zu können, muss zunächst im logischen Gerät ein passenden IO-Gerät ausgewählt sein. Dazu muss die Funktion [[DevelopmentModuleAPI#AssignIoPort|AssignIoPort()]] ein entsprechendes IO-Gerät auswählen und in <code>$hash->{IODev}</code> setzen. Dieser Aufruf wird üblicherweise in der [[#X_Define|Define]]-Funktion des logischen Moduls ausgeführt. Erst, wenn ein IO-Gerät ausgewählt wurde, können Daten über das physikalische Gerät an die Hardware übermittelt werden.

Zum Senden von Daten ruft das logische Modul die Funktion [[DevelopmentModuleAPI#IOWrite|IOWrite()]] samt Daten auf. Diese ruft für das entsprechende IO-Gerät die [[#X_Write|Write]]-Funktion auf und übergibt die Daten zum Schreiben an das physikalische Modul. Die Write-Funktion kümmert sich nun um die Übertragung der Daten an die Hardware.

Keine direkten Zugriffe zwischen dem logischen und dem physischen Gerät gibt (d.h. keine direkten Aufrufe von Funktionen, kein direktes Überprüfen von <code>$hash</code>-Inhalten, ...), so können die Module hintereinander geschaltet werden (z.B. für Routerfunktionen wie bei der [[RFR_CUL|RFR]]-Funktionalität) oder mittels [[FHEM2FHEM]] im RAW-Modus zwei FHEM-Installationen verbunden werden und die logischen Geräte können dennoch kommunizieren.

=== Automatisches Anlegen von logischen Gerätedefinitionen (autocreate) ===

Das logische Modul kann im Rahmen der [[#X_Parse|Parse]]-Funktion eine neue Gerätedefinition anlegen, sofern eine passende Definition nicht existieren sollte. Die Parse-Funktion gibt generell den Namen der logischen Gerätedefinition zurück, für welche die Nachricht verarbeitet wurde. Sollte keine passende Definition gefunden werden, so muss die Parse-Funktion folgenden Rückgabewert liefern (zusammenhängende Zeichenkette):

UNDEFINED ''<Namensvorschlag>'' ''<Modulname>'' ''<Define-Parameter>''

Sollte also bspw. im Rahmen der Parse-Funktion zu Modul X eine Nachricht nicht einer existierenden Gerätedefinition zugeordnet werden können, so muss ein Namensvorschlag erstellt werden der eine eindeutige Komponente wie bspw. eine Adresse/ID/Kanal-Nr enthält. In der Regel wird hier immer der Modulname zusammen mit der eindeutigen Komponente, durch einen Unterstrich getrennt, verwendet (Bsp: <code>X_4834</code>). Der Modulname ist in der Regel immer der, des eigenen Moduls. In besonderen Fällen kann man hier auch einen abweichenden Modulnamen angeben. Dies wird bspw. bei den [[PanStamp#FHEM-Module.2FDevice_Definition_Files|SWAP-Modulen]] eingesetzt. Als Define-Parameter müssen alle notwendigen Parameter angegeben werden, die beim Aufruf des <code>define</code>-Befehls notwendig sind, damit eine neu angelegte Gerätedefinition Nachrichten zu dieser eindeutigen Adresse Daten verarbeitet. Dazu muss mind. die eindeutige Adresse mitgegeben werden.

Beispiel für FS20:

UNDEFINED FS20_0ae42f8 FS20 0ae42 f8

Sobald [[DevelopmentModuleAPI#Dispatch|Dispatch()]] einen solchen Rückgabewert von einer [[#X_Parse|Parse]]-Funktion erhält, wird diese Zeichenkette so wie sie ist via [[DevelopmentModuleAPI#DoTrigger|DoTrigger()]] als Event für die Definition <code>global</code> getriggert.

Sofern der Nutzer das Modul [[autocreate]] verwendet (definiert hat), kümmert sich dieses nun um das Anlegen einer entsprechenden Gerätedefinition. Es lauscht dabei auf generierte Events der Definition <code>global</code> via [[#X_Notify|Notify]]-Funktion. Der Nutzer kann dabei das Verhalten von autocreate durch entsprechende Parameter beeinflussen.

Das Modul, für welches autocreate eine neue Definition anlegen möchte, kann das Verhalten durch entsprechende Parameter im Modul-Hash beeinflussen. Dabei gilt, dass gesetzte Attribute durch den Nutzer generell Vorrang haben. Die entsprechenden Parameter werden dabei im Rahmen der [[#X_Initialize|Initialize]]-Funktion im Modul-Hash gesetzt:

<source lang="perl">
sub X_Initialize($)
{
my ($hash) = @_;

...

$hash->{AutoCreate} = {"X_.*" => { ATTR => "event-on-change-reading:.* event-min-interval:.*:300",
FILTER => "%NAME",
GPLOT => "temp4hum4:Temp/Hum,",
autocreateThreshold => "2:140"
}
};

}
</source>

Hierbei wird unterhalb von <code>$hash->{AutoCreate}</code> eine Liste angelegt, wo einem regulären Ausdruck für einen anzulegenden Definitionsnamen entsprechende Optionen zugeordnet werden. Sobald durch autocreate eine Gerätedefintion angelegt wird, auf den ein hier gelisteter Ausdruck matcht, so werden die zugeordneten Optionen berücksichtigt.

Hier eine Auflistung aller möglichen Optionen und ihrer Bedeutung:

{| class="wikitable"
|-
! Optionsname !! Beispiel !! Bedeutung
|-
| <code>ATTR</code>|| <code>"event-on-change-reading:.* event-min-interval:.*:300"</code> || Eine Auflistung von Attributen, die nach dem Anlegen einer Definition zusätzlich gesetzt werden. Es handelt sich hierbei um eine Leerzeichen-separierte Liste von Doppelpunkt-getrennten Tupels mit Attributname und -wert.

Für das dargestellte Beispiel bedeutet dies, dass nach dem Anlegen der Definition folgende FHEM-Befehle zusätzlich ausgeführt werden:

attr ''<Name>'' event-on-change-reading .*
attr ''<Name>'' event-min-interval .*:300

|-
| <code>FILTER</code> || <code>%NAME</code>|| Sofern in der autocreate-Definiton das Attribut <code>filelog</code> entsprechend durch den Nutzer gesetzt ist, wird eine zugehörige FileLog-Definition angelegt. Diese Option setzt den dabei benutzten Filter-Regexp, der beim Anlegen der FileLog-Definition gesetzt wird.

Dabei werden folgende Platzhalter durch die entsprechenden Werte der neu angelegten Gerätedefinition ersetzt:

* <code>%NAME</code> - wird ersetzt durch den Definitionsnamen
* <code>%TYPE</code> - wird ersetzt durch den Modulnamen
|-
| <code>GPLOT</code> || <code>"temp4hum4:Temp/Hum,"</code> || Sofern eine FileLog-Definition angelegt wurde, kann man weiterführend dazu eine passende SVG-Definition erzeugen um Daten aus dem erzeugten FileLog zu visualisieren. Ein typischer Fall sind hierbei Temperatursensoren, wo es sinnvoll sein kann, einen passenden SVG-Plot mit Temperatur/Luftfeuchtigkeit direkt anzulegen.

Es handelt sich hierbei um eine kommaseparierte Auflistung von gplot-Dateinamen und optionalen Label-Texten durch einen Doppelpunkt getrennt. Im genannten Beispiel entspricht <code>temp4hum4</code> der zu verwendenden GnuPlot-Datei und <code>Temp/Hum</code> dem zu verwendenden Label ([[SVG]] Attribut <code>label</code>). Das Label wird auch durch FileLog verwendet als Link-Text zum entsprechenden SVG Plot. Alternativ kann auch nur die entsprechende GnuPlot-Datei anegeben werden ohne Label. Für jede angegebene GnuPlot-Datei wird anschließend eine entsprechende SVG-Definition erzeugt mit der vorher erzeugten FileLog-Definition als Datenquelle.

Der gesamte Inhalt der <code>GPLOT</code>-Option wird beim Anlegen einer FileLog-Definition dem Attribut <code>logtype</code> als Wert plus dem Text <code>text</code> zugewiesen. Daher muss der Inhalt der Option <code>GPLOT</code> immer mit einem Komma enden.

|-
| <code>autocreateThreshold</code>|| <code>"2:10"|| Definiert, wie viele Aufrufe (im Bsp: <code>2</code>) von autocreate innerhalb welcher Zeit (im Bsp: <code>10</code> Sek.) stattfinden müssen, bevor die Gerätedefinition tatsächlich durch autocreate angelegt wird. Dadurch kann das ungewollte Anlegen von Geräten verhindert werden die tatsächlich nicht in Echt existieren. Aufgrund von Funkstörungen kann es durchaus zum ungewollten Anlegen einer Definition kommen. Diese Funktion lässt eine Definition erst zu wenn innerhalb einer vorgegeben Zeit eine Mindestzahl an Nachrichten eintrifft.

Die erste Zahl stellt dabei die Mindestanzahl an Nachrichten dar. Die Zweite Zahl stellt die Zeit in Sekunden dar, in der die Mindestanzahl an Nachrichten erreicht werden muss um eine entsprechende Gerätedefinition anzulegen.

Sofern diese Option nicht gesetzt ist, wird standardmäßig <code>2:60</code> verwendet.

Diese Option kann durch den Anwender über das Attribut <code>autocreateThreshold</code> übersteuert werden.

Sofern diese Option nicht gesetzt ist
|-
| <code>noAutocreatedFilelog</code>|| <code>1</code>|| Flag. Sofern gesetzt, wird keine FileLog- und ggf. SVG-Definition erzeugt. Selbst wenn der Nutzer durch entsprechende Attribute das Anlegen wünscht. Diese Option ist sinnvoll für Module bzw. Geräte die keine Readings erzeugen.
|}

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

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

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

== "Hello World" Beispiel ==

98_Hello.pm

<source lang="perl">
package main;
use strict;
use warnings;

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

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

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

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

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

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

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

return undef;
}

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

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

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

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

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

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

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

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

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

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

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

1;

=pod
=begin html

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

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

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

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

=end html

=cut
</source>

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

== Noch zu beschreiben ==
* DevIO
* AsyncOutputFn / asyncOutput

[[Kategorie:Development]]

Arduino Firmata

2017-02-06T22:00:16Z

Kaihs: /* Arduino mit OneWireFirmata */

== Arduino mit Firmata ==
Für den Arduino gibt es ein StandardProtokoll Firmata.[[http://firmata.org]]. Mit der perl-firmata[https://github.com/ntruchsess/perl-firmata [6]] ist das Protokoll in perl einfach nutzbar und mit dem Modul [[#FRM|FRM]] in FHEM eingebunden. Damit ist es möglich mit nur geringen Arduino-kenntnissen (Bedienung der Arduino-IDE ist und elektronische Kenntnisse zum Anschluss von Sensoren sind natürlich erforderlich) Messwerte aus eigenen Schaltungen über einen Arduino in FHEM einzulesen.
Die in der Arduino-IDE enthaltene StandardFirmata kommuniziert über USB. Ihre Weiterentwicklung (die ConfigurableFirmata) muss man noch [https://github.com/firmata/arduino/archive/configurable.zip separat herunterladen] und damit die in der IDE enthaltene Firmata-library (komplett) ersetzen.

=== Arduino IDE ===
Zur Installation auf den Arduino wird natürlich erst mal die Arduino-IDE benötigt ([http://arduino.cc/en/Guide/HomePage http://arduino.cc/en/Guide/HomePage]). Die aktuelle Version der IDE enthält auch die StandardFirmata Firmware fertig zum Flashen auf den Arduino.
Diese findet man unter 'Datei'->'Beispiele'->'Firmata'->'StandardFirmata'. Einfach öffnen, unter 'Tools'->'Board' den eigenen Arduino auswählen und mit dem Upload-knopf (der Rechtspfeil im Kreis oben links) den geladenen Sketch compilieren und auf das Board hochladen. Falls man unter Windows Probleme hat, den Arduino über USB zu connecten, findet sich hier weitere Informatation: [http://arduino.cc/en/Guide/Windows#toc2 http://arduino.cc/en/Guide/Windows#toc2]
Wenn man die ConfigurableFirmata installiert hat, findet sich diese genauso bei den Beispielen für Firmata.

=== Installation ConfigurableFirmata ===
Die ConfigurableFirmata <b>ersetzt</b> die vorhandene Firmata-library <b>komplett</b>. Die mitgelieferte Firmata befindet sich typischerweise:

<nowiki>
Arduino 1.0.x:
Mac OSX: /Applications/Arduino.app/Contents/Resources/Java/libraries/Firmata
Windows: c:/Program\ Files/arduino-1.x/libraries/Firmata
Linux: ~/arduino-1.x/libraries/Firmata

Arduino 1.5.x:
Mac OSX:
/Applications/Arduino.app/Contents/Resources/Java/hardware/arduino/avr/libraries/Firmata
/Applications/Arduino.app/Contents/Resources/Java/hardware/arduino/sam/libraries/Firmata

Windows:
/Program\ Files/arduino-1.5.x/hardware/arduino/avr/libraries/Firmata
/Program\ Files/arduino-1.5.x/hardware/arduino/sam/libraries/Firmata

Linux:
~/arduino-1.5.x/hardware/arduino/avr/libraries/Firmata
~/arduino-1.5.x/hardware/arduino/sam/libraries/Firmata</nowiki>

Dieses Verzeichniss 'Firmata' also <b>löschen oder umbenennen</b> und die Configurable-firmata aus der [https://github.com/firmata/arduino/archive/configurable.zip zip-Datei] an die gleiche Stelle (also in ein neues Verzeichniss 'Firmata') entpacken. Nachher muss sich alles wie vorher im Verzeichniss Firmata befinden. Also so:

<nowiki>
<Arduino-Direktory>/libraries/Firmata/Firmata.h
<Arduino-Direktory>/libraries/Firmata/Firmata.cpp
<Arduino-Direktory>/libraries/Firmata/Boards.h
<Arduino-Direktory>/libraries/Firmata/utility/...usw...</nowiki>

alternativ zur Zip-datei kann man die Configurable-Firmata natürlich auch direkt aus Github heraus clonen. Dazu im Verzeichniss <Arduino-Direktory>/libraries/ folgendes eingeben:
<nowiki>'git clone https://github.com/firmata/arduino.git Firmata'</nowiki>
anschließend ins von clone neu erstellte Verzeichnis wechseln und dort eingeben:
<nowiki>'git checkout configurable'</nowiki>

=== ConfigurableFirmata und Ethernet ===

Die Unterstützung für Ethernet ist mittlerweile [https://github.com/firmata/arduino/blob/configurable/examples/ConfigurableFirmata/ConfigurableFirmata.ino in der Configurable-Firmata] enthalten.

Im Sketch muss man unbedingt die IP-konfiguration anpassen, d.h. die IP-addresse und Port des FHEM-servers eintragen (ggf. auch eine neue mac-addresse). Falls der Speicher des Arduinos nicht reicht (insbesonders bei Verwendung eines ENC28J60-shields passt die Configurable-firmata nicht mehr mit allen Features auf einen Uno oder Nano) einfach die includes der nicht benötigten Features im sketch auskommentieren. (Wenn man Servo oder I2C-unterstützung weglassen möchte bitte vorher einmalig den sketch mit allen Features compilieren, sonst treten Fehler beim compilieren der library-klassen wg. fehlendem Include von Servo.h oder Wire.h) auf. Das gleiche gilt, wenn man in der IDE irgendwas ändert, das einen kompletten Neubuild des sketches triggert (was z.B. beim Wechsel des gewählten Boards passiert).

<p>Getestet ist das ganze mit UNO R3 bzw. Mega 2560 + EthernetShield und zusätzlich mit UNO+Mega+Nano in Verbindung mit ENC28J60. Andere Arduinos als der Uno benötigen ggf. Anpassungen in der Setup/Reset Funktion.</p>
<p>Ein MEGA256 z.B. benutzt einen anderen Pin als SS (Slave select) zur Kommunikation mit dem Ethernetmodul. Man muss der Firmata im Setup mitteilen, welche Pins zu ignorieren sind, damit es keine Wechselwirkungen zwischen Firmata und Ethernetlibrary gibt. Das ist im Configurable.ino-sketch [https://github.com/firmata/arduino/blob/configurable/examples/ConfigurableFirmata/ConfigurableFirmata.ino#L231 ab Zeile 231 vorbereitet] und muss (wenn man etwas anderes als ein Standard-Ethernetshield am Uno verwendet) geeignet angepasst werden (Beim Mega muss man z.B. den Pin 10 ignorieren und Pin 53 als hardcodiert auf Output stellen). Das gleiche gilt, wenn man eine andere Hardware (z.B. mit ENC28J60 anstelle des WizNet W5100 des Ethernetshields) benutzen möchte, die einen anderen Pin als CS/SS benutzt.</p>
<p>Die für den ENC28J80 benötigte [https://github.com/ntruchsess/arduino_uip UIPEthernet-library findet sich hier].</p>

== FRM ==
Der Arduino wird in FHEM über das Modul 10_FRM.pm angesprochen.
10_FRM ist sozusagen die Basis (das IODev) für die anderen Module. Es lassen sich jeweils so viele Ein/Ausgabe Devices pro Arduino konfigurieren, wie dieser physikalisch besitzt (natürlich muss man darauf achten, dass nicht alle Arduino-pins alle Ein-/ausgabemöglichkeiten besitzen). Konfiguriert man einen Pin für einen nicht unterstützen Modus so gibt es mit der aktuellen Firmata-version (2.3) direkt einen Fehler - ältere Versionen schlucken so eine Fehlkonfiguration einfach so, der betreffende Pin funktioniert dann einfach nicht.

<code>define <devicename> FRM <port></code>

Hier mal ein kurzer Ausschnitt aus der fhem.cfg:

<hr />
<nowiki># definiere FRM als IO-Device - Baudrate 57600 ist default in der Standardfirmata
define FIRMATA FRM /dev/ttyUSB0@57600
attr FIRMATA loglevel 6
attr FIRMATA sampling-interval 1000 # Wert ist in ms und 14Bit breit, also nur bis 16384 setzbar (Beschränkung des Firmata-protokolls) - gilt für alle Pins</nowiki>
Seit Anfang März 2013 unterstützt FRM auch über Ethernet angebundene Arduinos:

<nowiki>define FIRMATA FRM <port> [global]</nowiki>
FRM macht FHEM-seitig einen Serverport auf (dieser wird in der define-zeile angegeben). 'global' muss angegeben werden, damit der Serversocket an alle IP-addressen gebunden wird. (Sonst nur 'localhost', was hier wohl nicht funktionieren würde). Der Arduino verbindet aktiv zu diesem Port, sonst gilt im Prinzip alles was auch für den über USB angebunden Arduion gilt.

siehe auch: [http://fhem.de/commandref.html#FRM CommandRef FRM]
=== 20_FRM_IN.pm ===
Macht einen Arduino-pin als digitalen Eingang nutzbar.
<nowiki>define Firmata_IN FRM_IN 12 # definiert Arduino Pin 12 als digitalen Eingang</nowiki>
siehe auch: [http://fhem.de/commandref.html#FRM_IN CommandRef FRM_IN]
=== 20_FRM_OUT.pm ===
Macht einen Arduino-pin als digitalen Ausgang nutzbar.
<nowiki>define Firmata_OUT FRM_OUT 11 # definiert Arduino Pin 11 als digitalen Ausgang</nowiki>
siehe auch: [http://fhem.de/commandref.html#FRM_OUT CommandRef FRM_OUT]
=== 20_FRM_AD.pm ===
Macht einen Arduino-pin als analogen Eingang nutzbar.
<nowiki>define Firmata_ANALOG FRM_AD 17 # definiert Arduino Pin 17 als analogen Eingang</nowiki>
siehe auch: [http://fhem.de/commandref.html#FRM_AD CommandRef FRM_AD]
=== 20_FRM_PWM.pm ===
Macht einen Arduino-pin als analogen Ausgang nutzbar. Es wird ein pulsweitenmoduliertes Signal ausgegeben.
<nowiki>define Firmata_ANALOG FRM_PWM 10 # definiert Arduino Pin 10 als analogen Ausgang</nowiki>
siehe auch: [http://fhem.de/commandref.html#FRM_PWM CommandRef FRM_PWM]
=== 20_FRM_SERVO.pm ===
Erlaubt die Ansteuerung von analogen Modelbauservos (Ansteuerung über PWM) am Arduino.
<nowiki>define Firmata_ANALOG FRM_AD 9 # definiert Arduino Pin 9 als analogen Eingang</nowiki>
siehe auch: [http://fhem.de/commandref.html#FRM_SERVO CommandRef FRM_SERVO]
=== 20_FRM_I2C.pm ===
<p>Erlaubt das Auslesen von über I2C angeschlossenen ICs</p>
siehe auch: [http://fhem.de/commandref.html#FRM_I2C CommandRef FRM_I2C]
=== Arduino mit OneWireFirmata ===
<p>die Seite [[Arduino mit OneWireFirmata]] beschreibt, wie es möglich ist, mit einer um OneWire erweiterten Version der Standard Firmata an den Arduino angeschlossene 1-Wire Devices in FHEM einzubinden.</p>
siehe auch: [http://fhem.de/commandref.html#OWX CommandRef OWX]

[[Kategorie:Other_Components]]
[[Kategorie:Arduino]]
[[Kategorie:HOWTOS]]

Anwesenheitserkennung

2017-01-18T20:43:59Z

Kaihs: /* Bluetooth-Überwachung von Geräten durch verteilte Agenten in der Wohnung (presencd/collectord) */

Viele Benutzer führen bereits eine eigene '''Anwesenheitserkennung''' durch. Diese basiert in den meisten Fällen auf Ping Checks oder bei [[AVM Fritz!Box|FritzBoxen]] auf dem Befehl ''ctlmgr_ctl''. Diese Lösungen können aber je nach Aufbau und Funktion FHEM massiv beeinträchtigen. Aufgrund des Aufbaus vom FHEM kann dieses dadurch für mehrere Sekunden zum völligen Stillstand gebracht werden.

In FHEM gibt es mittlerweile mehrere Module, die eine zuverlässige Anwesenheitserkennung bieten, ohne dabei FHEM bei der Ausführung zu beeinträchtigen.

Eine erweiterte Funktion der Anwesenheitserkennung ist die Standortverfolgung, die sich nicht nur auf ein oder sehr wenige mit (eigenem) WLAN versorgte Gebiete beschränkt.

== Vorüberlegungen ==
Generell gibt es mehrere Ansätze um Anwesenheitserkennung mit Handys/Smartphones durchzuführen.

* via PING Checks im gesamten WLAN
* Aktivitätsprüfung auf einer FritzBox
* Bluetooth Checks in der gesamten Wohnung
* eigene Perl-Funktion
* aktive Benachrichtigung des Smartphones, ausgelöst z.B. über Geo-Lokation/Geofence

Dabei gilt bei der Auswahl der Art darauf zu achten wie sich das jeweilige Device verhält. Aufgrund der Vielfältigkeit kann man hier keine allgemeine Vorgehensweise empfehlen. Als einfacher Start (zumindest für Nicht-Apfel Telefone) eignet sich die Ping-Überprüfung und die FritzBox-Abfrage sehr gut.

=== Randbedingungen ===
Es gibt Geräte, die ihr WLAN/Bluetooth auch im Standby ständig aktiv haben und auf Anfragen antworten können (fast alle Android-Geräte). Gerade bei Tests über WLAN kann sich das aber signifikant auf die Akku Leistung auswirken.

Andere Geräte wiederum schalten WLAN im Standby Betrieb aus, um Akkukapazität zu sparen. Bluetooth hingegen bleibt weiterhin aktiviert und kann auf Anfragen reagieren. (iPhone)

Wenn man bei einem iPhone die Funktion "über WLAN synchronisieren" aktiviert hat, so ist dies auch im Standby jederzeit pingbar, wenn der Recher auf dem iTunes zum synchroniseren läuft auch an ist. Ansonsten ist bei iPhone Geräten nur die Aktivitätsprüfung mit einer FritzBox oder das überwachen der DHCP Lease auf einer Airport Basestation wirklich zuverlässig.

Auch wenn Bluetooth aktiviert ist, so bleiben einige Mobiltelefone erst dann empfangsbereit, wenn sie bereits zu irgend einem Bluetoothgerät gekoppelt wurden. Sind diese Geräte noch nie gekoppelt worden, deaktivieren diese ihren Bluetooth Empfänger beim verlassen des Bluetooth-Menüs im Gerät (iPhone).

Hier gilt es vor allem auszuprobieren, wie stark der Akku durch eine Anwesenheitserkennung belastet wird. Entscheidend ist hier, in welchem Abstand man eine Anwesenheitserkennung durchführt. Viele Abfragen wirken sich stärker auf den Akku aus als wenige. Wenige Abfragen bieten aber keine zuverlässige und zeitnahe Erkennung.

Als Alternative, unabhängig vom WLAN und der Erkennung, ob ein Gerät dort eingebucht ist oder nicht, bzw. unabhängig von Bluetooth kann zumindest bei einem iPhone die seit iOS 7 nochmals stark verbesserte Geo-Lokation (Geofencing) genutzt werden. Die iPhone Apps [http://geofency.com/ Geofency] oder [http://geofancy.com/ Geofancy] werden über das FHEM-Modul GEOFANCY angebunden und übertragen ihren Status immer dann, wenn ein definierter Standort betreten oder verlassen wird. Gekoppelt mit entsprechenden Notify und/oder Watchdog Kommandos ist so ebenfalls eine sehr zuverlässige Anwesenheitserkennung möglich (und das nicht nur für das eigene Zuhause).

== Das PRESENCE Modul ==
Das [[PRESENCE]] Modul bietet für die Anwesenheitserkennung mehrere Varianten an. Diese sind aktuell folgende:

* '''lan-ping''' - Das Überwachen via PING Checks, die durch den FHEM Server versandt werden.
* '''fritzbox''' - Das Überwachen von Geräten auf einer FritzBox via ctlmgr_ctl (Nur auf einer FritzBox möglich)
* '''local-bluetooth''' - Das Überwachen via Bluetooth Checks, die vom FHEM Server direkt durchgeführt werden (angeschlossener Bluetooth-Stick und die Software bluez voraussgesetzt)
* '''lan-bluetooth''' - Das Überwachen von Bluetoothgeräte, über Netzwerk. Auf einer oder mehreren Maschinen im Netzwerk (z.B. [[:Kategorie:Raspberry Pi|Raspberry Pi]]) läuft ein Presence-Daemon, der nach Bluetooth-Geräten sucht. Um mehrere Presence-Daemon mit FHEM zu verbinden, gibt es den Collector-Daemon, der sich zu allen Presence-Damons im Netzwerk verbindet und das Ergebnis von allen zusammenfasst.
* '''function''' - Das Überwachen mithilfe einer selbst geschrieben Perl-Funktion, die den Anwesenheitsstatus zurückgibt (0 oder 1)
* '''shell-script''' - Das Überwachen mithilfe eines selbst geschriebenen Shell-Programms/Skript, das eine 0 oder 1 ausgibt, um den Anwesenheitsstatus mitzuteilen.

=== Ping-Überwachung von Geräten im WLAN/LAN ===
{{Randnotiz|RNText=Um diese Methode auf einer FritzBox nutzen zu können, muss FHEM mit root-Rechten laufen. Dies ist standardmäßig nicht der Fall. Bitte dazu den Wiki Artikel [[FritzBox: fhem unter root starten]] beachten.}}
Um ein Gerät via Ping zu überwachen, muss folgende Definition durchgeführt werden:
:<code>define Handy PRESENCE lan-ping 192.168.0.30</code>

Dadurch wird die IP-Addresse 192.168.0.30 alle 30 Sekunden geprüft, ob sie erreichbar ist. Wenn sie erreichbar ist, ist der Status "present" (anwesend), ansonsten "absent" (abwesend).

Der Timeout kann verändert werden, indem ein Wert (in Sekunden) an das Define anhängt wird:
:<code>define Handy PRESENCE lan-ping 192.168.0.30 '''60'''</code>

Nun würde das Handy alle 60 Sekunden geprüft werden.

Nur wenn bei einem iPhone/iPad die Funktion "über WLAN synchronisieren" aktiviert ist, ist es auch im Standby zuverlässig pingbar. Standardmäßig deaktivieren Apple-Geräte ihr WLAN im Standby-Betrieb um die Akkulaufzeit zu verlängern.

Sollte die Fehlermeldung
:<code> PRESENCE (Handy) - ping command returned with output: ping: icmp open socket: Operation not permitted </code>
im Log auftauchen und lan-ping dadurch nicht funktionieren, liegt ein Berechtigungsproblem vor. Kein Grund den User fhem zu root zu machen!
So sollten die Berechtigungen aussehen
:<code>sudo ls -la /bin/ping</code>
unter Jessie
:<code>-rwxr-xr-x 1 root root 38844 Feb 12 2014 /bin/ping</code>
unter Wheezy
:<code>-rwsr-xr-x 1 root root 33220 Mär 30 2012 /bin/ping</code>
Sollte es trotzdem unter Jessie nicht funktionieren kann man auch dort die Berechtigung analog wheezy setzen:
:<code>sudo chmod u+s /bin/ping</code>

=== FritzBox: direktes Abfragen der Aktivität via ctlmgr_ctl ===
{{Randnotiz|RNText=Um diese Methode auf einer FritzBox nutzen zu können, muss FHEM mit root-Rechten laufen. Dies ist standardmäßig nicht der Fall. Bitte dazu den Wiki Artikel [[FritzBox: fhem unter root starten]] beachten.}}
Eine sehr häufige und auch zuverlässige Methode ist auf einer FritzBox die Abfrage mittels ctlmgr_ctl Befehl. Über diesen lassen sich alle Geräte abfragen ob sie aktiv sind. Ist ein Gerät aktiv, so gilt es als anwesend.

Dieser Modus kann allerdings nur in FHEM Installationen direkt auf einer FritzBox verwendet werden. Des weiteren muss FHEM unter dem User root laufen. Um ein Gerät zu überwachen, wird lediglich der Gerätename benötigt, so wie er unter dem Menüpunkt "Heimnetz" auftaucht.

Die erforderliche Definition:
:<code>define Handy PRESENCE fritzbox iPhone-4S</code>

=== Bluetooth-Überwachung von Geräten durch den FHEM Server ===
[[Datei:Bluetooth-Adresse-iPhone.png|thumb|Bluetooth-Adresse eines iPhones]]
Jenach Aufstellungsort des FHEM Servers kann es sinnvoll sein, eine Bluetooth-Überwachung direkt durch den FHEM Server durchzuführen. Hierbei gilt allerdings zu beachten, dass Bluetooth nicht für große Reichweiten gedacht ist und in den meisten Fällen keine Wände überwinden kann. Das heisst, dass in den meisten Fällen damit nur ein Raum überwacht werden kann.

Je nach Einsatzzweck kann das auch so gewollt sein. Bluetooth USB Sticks, die bereits Bluetooth 4.0 unterstützen, können höhere Reichweiten über Zimmerwände hinaus erreichen. Vorausgesetzt, das Mobilgerät unterstützt Bluetooth 4.0.

Um eine Überwachung per Bluetooth durchführen zu können, benötigt man die Bluetooth-Adresse eines Gerätes. Diese ähnelt vom Aufbau einer MAC-Adresse. Generell wird die Adresse in den Telefon-Informationen bei Smartphones angezeigt.

Um eine Anwesenheitserkennung via Bluetooth durchzuführen, wird folgende Definition in der [[Konfiguration]] benötigt:
:<code>define Handy PRESENCE local-bluetooth XX:XX:XX:XX:XX:XX</code>

=== Bluetooth-Überwachung von Geräten durch verteilte Agenten in der Wohnung (presenced/collectord) ===
[[Datei:Raspberry-Pi-mit-WLAN-und-Bluetooth-Stick.jpg|thumb|left|Raspberry Pi mit Bluetooth- und WLAN-USB-Stick]]
Um eine zuverlässige und flächendeckende Bluetooth-Anwesenheitserkennung durchzuführen, ist es unerlässlich, mehrere Bluetooth-Empfänger zu verwenden, die auf mehrere oder alle Räume verteilt sind.

Hierfür bietet sich zum Beispiel ein [[Raspberry Pi]] mit einem Mini-Bluetooth-USB-Stick und evtl. einem WLAN-USB-Stick an. Jeder Raum wird mit solch einem Raspberry ausgestattet und ist im WLAN Netz verfügbar.

Dieses Netz aus Raspberrys wird mit dem presenced (Download-Link ist in der [http://fhem.de/commandref_DE.html#PRESENCE Commandref] zum Modul enthalten) ausgestattet. Es stehen bereits entsprechende Pakete für den Raspberry zur Verfügung.

Beide Programme (presenced/collectord) sind Perl-Skripte, die als Daemon im Hintergrund laufen und auf Anfragen via Netzwerk warten. Es wird lediglich eine vollständige Perl-Grundinstallation mit Standardmodulen benötigt. Nach Installation der *.deb Pakete sollten diese noch angewiesen werden, automatisch beim Rechner-Neustart gestartet zu werden:

<pre>
sudo update-rc.d presenced defaults
sudo update-rc.d collectord defaults
</pre>

Eine detaillierte Benutzung von presenced ist in der [http://fhem.de/commandref_DE.html#PRESENCE Commandref] Beschreibung zum PRESENCE Modul enthalten.

==== Jeden Raum einzeln ansprechen (presenced) ====
Nun kann zuallererst jeder Raum einzeln angesprochen werden. Dabei ist zu beachten, dass pro Definition in der Konfiguration nur ein Gerät in einem Raum spezifisch überwacht werden kann.

Eine Definition sieht dabei folgendermaßen aus:
:<code>define Handy_Wohnzimmer PRESENCE lan-bluetooth XX:XX:XX:XX:XX:XX 192.168.0.10:5111</code>

Damit wird nun das Gerät nur im Wohnzimmer (Raspberry mit IP 192.168.0.10) überwacht.

==== Alle Räume gemeinsam ansprechen (collectord) ====
Um jedoch alle Räume gemeinsam zu verwenden, gibt es den Collector-Daemon. Dieser kennt alle presenced-Installationen im Netzwerk und führt eine koordinierte Suche nach den gewünschten Geräten durch. Sobald ein Gerät in einem Raum erkannt wurde, meldet der collectord den Status einschließlich der Angabe des Raumes, in dem das Gerät erkannt wurde.

Um alle Räume zu kennen, müssen diese mit einem Config-File dem collectord mitgeteilt werden. Dieses sieht folgendermaßen aus:

<pre>
[Schlafzimmer] # Name des Raumes (wird in FHEM als Reading angezeigt)
address=192.168.179.31 # IP-Adresse oder Hostname des presenced
port=5111 # TCP Port, der verwendet werden soll (standardmäßig Port 5111)
presence_timeout=120 # Prüfinterval, das verwendet werden soll, wenn ein Gerät anwesend ist
absence_timeout=20 # Prüfinterval, das verwendet werden soll, wenn ein Gerät abwesend ist

[Wohnzimmer]
address=192.168.179.34
port=5111
presence_timeout=180
absence_timeout=20
</pre>

Standardmäßig ist dieses Config-File unter /etc/collectord.conf zu finden. Mit dieser Konfiguration kann der Collectord gestartet werden. Es empfiehlt sich diesen mit auf dem FHEM Server zu betreiben. Die erforderliche Definition in der Fhem-Konfiguration:
:<code>define Handy PRESENCE lan-bluetooth XX:XX:XX:XX:XX:XX 127.0.0.1:5222</code>

Sobald das Handy irgendwo in der Wohnung erkannt wurde, meldet der Collectord dies sofort an FHEM und teilt den Raum mit.

Eine detaillierte Benutzung von collectord findet man in der [http://fhem.de/commandref.html#PRESENCE Commandref zum PRESENCE Modul].

=== Überwachung von Geräten mit Perl-Code ===
Es ist möglich zum Überwachen von Geräten eine eigene Perl-Funktion zu verwenden die dann vom PRESENCE Modul im Hintergrund aufgerufen wird.

define <name> PRESENCE function {...} [ <check-interval> [ <present-check-interval> ] ]

Sobald die Funktion den Rückgabewert 1 hat, ist das Gerät anwesend, bei 0 abwesend.

==== Beispiel DHCP Überwachung auf Airport Basestation ====
Die hier vorgestellte Überwachung der DHCP Lease auf Airport Basestations per SNMP ist absolut robust gegenüber dem Ruhezustand von iOS und setzt keine weitere Konfiguration auf dem iPhone voraus. Das Abmelden beim Verlassen des Empfangsbereiches der Basestation geschieht mit etwa 5-10 Minuten Verzögerung und ist somit auch vor kurzzeitigen Empfangsproblemen sicher. Das nebenstehende Bild (???) verdeutlicht noch mal die Unterschiede zwischen einer IP-Basierten Ping-Überwachung und der Überwachung auf Ebene der Basestation oder FritzBox.

Bevor der folgende Code verwendet werden kann ist das Perl Modul Net:SNMP zu installieren (z. B. mit: <code>cpan install use Net::SNMP</code>).

Zuerst ist folgender Code in 99_myUtils.pl einzufügen:

<pre>
use Net::SNMP;
sub
snmpCheck($$)
{
my ($airport,$client)= @_;

my $community = "public";
my $host = $airport;
my $oid = ".1.3.6.1.2.1.3.1.1.2";
#my $oid = ".1.3.6.1.2.1.3.1.1.2.25.1.10.0.1";

my ( $session, $error ) = Net::SNMP->session(
-hostname => $host,
-community => $community,
-port => 161,
-version => 1
);

if( !defined($session) ) {
return 0;
return "Can't connect to host $host.";
}

my @snmpoids = ();

my $response = $session->get_next_request($oid);
my @nextid = keys %$response;
while ( @nextid && $nextid[0] && $nextid[0] =~ m/^$oid/ ) {
push( @snmpoids, $nextid[0] );

$response = $session->get_next_request( $nextid[0] );
@nextid = keys %$response;
}

if( !defined($response = $session->get_request( @snmpoids ) ) ) {
return 0;
}

foreach my $value (values %$response) {
return 1 if( $value eq $client )
}

return 0;
}
</pre>

Danach lässt sich das Mobilgerät so überwachen:
:<code>define iPhone PRESENCE function {snmpCheck("10.0.1.1","0x44d77429f35c")} 30 30</code>

wobei 10.0.1.1 durch die IP-Adresse der Basestation und 0x44d77429f35c durch die MAC Adresse des Geräts als HEX-Zahl ersetzt werden muss.

==== Beispiel Anwesenheitserkennung mittels UniFi Controller ====

Die Anwesenheitserkennung bei Geräten in Verbindung mit UniFi-Produkten funktioniert selbst dann, wenn sich die Geräte im PowerSave-Modus befinden.

Beachte: Die Geräte werden erst ungefähr nach 5 Minuten, nachdem das Gerät das WLAN verlassen hat als disconnected angezeigt.

<code>define <NAME> PRESENCE function {ReadingsVal("<UniFi>","<NamedDevice>","") eq "connected" ? 1:0}</code>

=== Eventbasierte Anwesenheitserkennung am Beispiel mittels UniFi Controller ===
Der Vorteil gegenüber der Function-Variante ist, dass diese Variante ohne Blocking.pm-Overhead direkt ausgeführt werden kann und in "Echtzeit" abläuft (siehe {{Link2Forum|Topic=40287|Message=562823}}).

<code>define <NAME> PRESENCE event UniFi:NamedDevice:.disconnected UniFi:NamedDevice:.connected</code>

== Das GEOFANCY Modul ==
Das Modul ermöglicht über einen sogenannten Webhook Mechanismus (umgangssprachlich oft auch als "Push" benannt) das aktive Melden des aktuellen Standortes. Die iPhone Apps [http://geofency.com/ Geofency] und [http://geofancy.com/ Geofancy] können dann aktiv und quasi in dem Moment, wo man den Wohnbereich betritt oder verlässt, benachrichtigen. Android Nutzern können [https://play.google.com/store/apps/details?id=de.egi.geofence.geozone&hl=de EgiGeoZone Geofence] nutzen. Das geht nochmals um einiges schneller, als die Erkennung im WLAN, bei der die Anwesenheit nur in (engen) Zyklen aktiv geprüft werden muss. Gleichzeitig werden Ressourcen in FHEM geschont. Die aktuelle Implementierung im iPhone 5S mit dediziert für das Tracking zuständigem Chip ist so gut, dass der Akku ebenfalls sehr geschont wird.

=== Modul in FHEM einrichten ===
Das Modul ist mit einer einfachen Definition sofort betriebsbereit:
:<code>define geofancy GEOFANCY geo</code>

Damit nimmt FHEM unter <nowiki>http://192.168.178.1:8083/fhem/geo</nowiki> entsprechende Meldungen des iPhones entgegen. Damit das nicht nur über das lokale WLAN funktioniert, bedarf es allerdings noch einiger zusätzlicher Maßnahmen. FHEM muss vom Internet erreichbar gemacht werden, dabei sollte unbedingt an die Absicherung des Zugriffs gedacht werden.

Zunächst einmal habe ich bei mir eine eigene FHEMWEB Instanz dafür angelegt:
<pre>
define WEBhook FHEMWEB 8088 global
attr WEBhook column Alarms: Apartment: Living: Bedroom: Kitchen: Sonos: Residents: Weather: Bathroom: Logs: Statistics: DashboardRoom: System: hidden: all:
attr WEBhook hiddenroom input,detail,save,Unsorted,Everything,CUL_HM,FS20,Commandref,style,Edit files,Select style,Logfile,Floorplans,Remote doc,FileLogs,Apartment,Bathroom,Bedroom,Kitchen,Living,Residents,System,Weather,Event monitor,NEW
attr WEBhook room hidden
attr WEBhook webname webhook
</pre>

Damit ist unter der URL <nowiki>http://192.168.178.1:8088/webhook/geo</nowiki> das GEOFANCY Modul erreichbar. Ich verstecke in dieser Ansicht noch alle Räume, die ich so habe. Wer die Raumnamen allerdings kennt, kann sie trotzdem aufrufen. Die Anzeige in den Räumen kann man mit dem Attribut column und entsprechend leeren Definitionen verstecken. Nun muss man explizit den Devicenamen kennen, um noch etwas über die Konfiguration in Erfahrung bringen zu können.
Auch wenn das Security-by-Obscurity ist - ich fühle mich wohler damit.

=== Webhook weiter absichern ===
Mit Hilfe eines [http://fhem.de/commandref.html#allowed allowed]-Devices lässt sich die FHEMWEB Instanz noch weiter absichern indem nur die tatsächlich benötigten Kommandos erlaubt werden (in diesem Fall keine) und damit alle anderen nicht erlaubten (attr,define,get,set,...) automatisch nicht mehr zur Verfügung stehen:
<pre>
define allowedWEBhook allowed
attr allowedWEBhook allowedCommands ,
attr allowedWEBhook allowedDevices ,
attr allowedWEBhook validFor WEBhook
</pre>

Außerdem ist dringend zu empfehlen, den Zugriff über TLS/SSL und HTTP Basic-Authentication weiter abzusichern. Läuft FHEM auf einem Raspberry Pi, dann empfehle ich dazu die Konfiguration eines ReverseProxy (vorzugsweise HAproxy, Pound oder Varnish, notfalls auch Nginx oder Apache); damit ist man am flexibelsten und kann auch alle FHEMWEB Instanzen direkt über einen einzigen Port (meist 443, der HTTPS Standard Port) zusammenfassen. Ich möchte hier allerdings beschreiben, wie weit man mit FHEM Bordmitteln kommt und nehme das Beispiel einer Installation auf einer Fritzbox.

Wie TLS aktiviert wird, steht in der Commandref für [[FHEMWEB]]. Um die Kommandos auf der Fritzbox ausführen zu können, muss zuerst Telnet aktiviert werden (bitte Google benutzen). Anschließend wechselt man auf der Fritzbox ins Verzeichnis /var/media/ftp/fhem und kann dann den Hinweisen aus der [http://fhem.de/commandref.html#FHEMWEB Commandref] unter dem Punkt HTTPS folgen. Letztlich fehlt noch das entsprechende Attribut:

<pre>
attr WEBhook HTTPS
</pre>

Als nächstes aktivieren wir Benutzername+Passwort für den Zugriff. Die commandref für allowed gibt auch hier unter dem Punkt basicAuth entsprechende Hinweise. Wir fügen hier einfach mal einen Benutzer "webhook" mit dem Passwort "Geofancy" hinzu, das sieht dann so aus:

<pre>
attr allowedWEBhook basicAuth { "$user:$password" eq "webhook:Geofancy" }
</pre>

Weitere Infos zur Absicherung gibt auch [[FritzBox Webzugriff absichern]].

Um zu testen, ob unsere Absicherung erfolgreich war, kann man die URL <nowiki>https://192.168.178.1:8088/webhook/geo</nowiki> aufrufen (wichtig ist, dass man jetzt https und nicht mehr http eingibt; ansonsten bekommt man keine Antwort). Eine Zertifikatswarnung kann getrost ignoriert werden, verschlüsselt wird trotzdem. Es sollte auch eine Passwort Abfrage kommen und die Eingabe der entsprechenden Daten sollte dann zu einer entsprechenden Meldung vom GEOFANCY Modul führen:

<pre>
NOK No data received, see API information on http://wiki.geofancy.com
</pre>

Das ist ok, schließlich sind wir keine App, sondern der Mensch, der nur mal eben prüfen will :-)

=== Zugriff vom Internet ermöglichen ===
Das ist je nach Fritzbox und Software Version unterschiedlich. Grundsätzlich gilt: Eine Weiterleitung des ports 8088 vom Internet auf das laufende FHEM auf Port 8088 intern ist von AVM so nicht vorgesehen.
Bei mir führte folgendes zum Erfolg:

* Einloggen per Telnet auf der Fritzbox (ich habe FritzOS 6 installiert)
* Konfiguration editieren mittels "nvi /var/flash/ar7.cfg"
* Suchen nach richtiger Zeile durch Eingabe von "/internet_forwardrules" und Enter
* Hinzufügen einer weiteren Zeile (Vorsicht, die bestehende Zeile endet mit ; und das muss in , umgeändert werden, so dass das ; schließlich am Ende der Zeile steht.

So sieht es bei mir vorher aus:
:<code>internet_forwardrules = "tcp 0.0.0.0:488 0.0.0.0:488 0";</code>
Hinterher:
:<code>internet_forwardrules = "tcp 0.0.0.0:488 0.0.0.0:488 0", "tcp 0.0.0.0:8088 0.0.0.0:8088 0";</code>

Danach mittels ":x" abspeichern und sofort per "reboot" die Box neu starten, um diese Änderungen zu aktivieren. Das ist wichtig; ansonsten zeigt die Erfahrung, dass die Änderung nicht dauerhaft erhalten bleibt und die gerade gemachten Änderungen verloren gehen.

Wer die Einstellungen zu "internet_forwardrules" bei sich nicht finden kann, hat womöglich eine andere Version als ich oder ein leicht anderes Gerät und bemüht am besten Google, was er tun kann, um das Gleiche zu erreichen. Möglicherweise tauchen die Einträge auch erst auf, wenn man mal über das Webinterface ein Forwarding eingerichtet hatte.

Hat man einen DynDNS Dienst oder myFritz auf der Fritzbox aktiviert, so kann man jetzt auch von draußen auf den Webhook zugreifen. Das kann man prüfen, indem man das iPhone aus dem WLAN ausbucht und einmal die externe Adresse eingibt, also z.B. https://meindyndns.org:8088/webhook/geo.

=== Weitere Alternativen für den Zugriff aus dem Internet ===
Als Alternative zum Port Forwarding kann man sich auch per VPN in das lokale Netzwerk einwählen. iOS bietet dazu auch eine automatische Aktivierung des VPN (VPN on Demand), wie z.B. [http://forum.loxone.com/dede/netzwerk-firewall-and-security/8121-vpn-demand-ios-8-1-1-fritz-box-kleine-how.html hier] beschrieben wird.

Auch eine Alternative ist, das Portforwarding nicht direkt an FHEM einzurichten, sondern an einem im Netzwerk laufenden Reverse-Proxy, der dann seinerseits die Anfragen an FHEM weiterleitet. Dies kann z.B. Apache, Nginx oder am besten HAproxy sein.
Letzterer ist dabei sehr flexibel, allerdings nicht unbedingt einfach zu konfigurieren. Ein paar Inspirationen diesbezüglich gibt es z.B. [https://github.com/Hoanoho/HSE/tree/develop/lib/cfg/any/stat/etc/haproxy hier] und [https://github.com/Hoanoho/HSE/tree/develop/lib/cfg/any/dyn/etc/haproxy hier]. Wer pfSense nutzt, findet [http://loredo.me/post/116633549315/geeking-out-with-haproxy-on-pfsense-the-ultimate diesen Artikel] womöglich auch interessant. Er zeigt auch, dass mit HAproxy noch weit mehr möglich ist.
Der Reverse-Proxy sollte dabei auch unbedingt der TLS Termination Point sein (TLS Offloading). Nicht nur spart man sich dann die Aktivierung von TLS in FHEM, sondern man hat auch mehr Einfluss darauf, wie TLS arbeitet (z.B. Deaktivierung von SSLv3, forcieren von TLSv1.2, nur als sicher eingestufte Cipher Suite... siehe auch Infos auf der [https://wiki.mozilla.org/Security/Server_Side_TLS Mozilla Website]).

=== Einrichten in der Geof[e|a]ncy.app ===
Hat das alles soweit geklappt, können endlich in der Geofency.app bzw. Geofancy.app am iPhone die gewünschten Bereiche definiert werden. Am Besten zuvor in den Global Settings die folgenden Einstellungen hinterlegen:

* URL: https://meindyndns.org:8088/webhook/geo
* POST (oder GET, ist egal - das FHEM Modul kann beides)
* HTTP Basic Authentication: EIN (entsprechend Username und Password eintragen)

Anfänglich ist es empfehlenswert noch "Notification on success" und "Notification on Failure" einzuschalten. Ersteres kann man ausmachen wenn man weiß, dass es soweit funktioniert. Über "Send Test-Request" kann man einmal einen Test schicken und erhält das Ergebnis entsprechend dargestellt. Es sollte sowas kommen wie
:<code>POST Success: test OK</code>. In Geofancy.app gibt es keine Rückmeldung über den Erfolg des Testrequests. In FHEM sollten sich durch den Testrequest jedoch die Readings sofort aktualisieren (Ggf. ist ein Reload der FHEMWEB-Seite nötig da zusätzliche Tabellenzeilen nicht via Longpoll ergänzt werden).

Funktioniert das soweit, kann man eine neue Lokation als sein Zuhause anlegen. Es empfiehlt sich einen ID-Namen zu setzen; dieser ist dann in FHEM als Name für die Lokation sichtbar. Für die eigene Wohnung empfiehlt sich hier "home" (da dies auch direkt vom RESIDENTS Modul so verwendet werden kann). Man kann auch Trigger für andere Standorte anlegen. FHEM weiß dann sogar, wenn ihr im Büro seid und könnte sich dabei auch unterschiedlich verhalten, als wenn ihr "auf Achse" seid. Bei letzterem ist der Status im GEOFANCY Modul "underway", was so viel heißt wie "unbekannter Aufenthaltsort".

Hinweis: Zumindest für Geofancy.app liefert ein Testrequest wohl zufällige Locations zurück. Die eigenen Location-IDs werden also nicht übergeben, selbst wenn man sich in einem Geofence befindet. Um zu testen muss man sich wohl oder übel selbst bewegen ;-).

=== GEOFANCY Modul individualisieren ===
Die im GEOFANCY Modul dargestellten Readings sind nun in etwa so, wenn ihr euch bewegt:

<pre>
Readings:
2014-01-18 14:37:42 lastDevice -
2014-01-18 14:37:42 lastDeviceUUID 51F23894-AAAA-BBBB-CCCC-0123456789AB
2014-01-18 14:37:42 state dev:51F23894-AAAA-BBBB-CCCC-0123456789AB trig:test id:home lat:48.9999 long:11.9999
</pre>

Wer genauer hinschaut sieht: Mein iPhone heißt wohl 51F23894-AAAA-BBBB-CCCC-0123456789AB.
Damit nun die Readings für mein iPhone richtig angelegt werden, muss ein Device Alias gesetzt werden. Sinnvoll erscheint mir der Vorname des Besitzers:
:<code>attr geofancy devAlias 51F23894-AAAA-BBBB-CCCC-0123456789AB:Julian</code>

Weitere Alias-Namen können mit Leerzeichen einfach angehängt werden.
Jetzt werden weitere Readings angelegt, sobald GEOFANCY entsprechende Daten vom Mobilgerät empfängt:

<pre>
Readings:
2014-01-18 14:37:42 Julian arrived home
2014-01-18 14:37:42 currLocLat_Julian 48.9999
2014-01-18 14:37:42 currLocLong_Julian 11.9999
2014-01-18 14:37:42 currLocTime_Julian 2014-01-18 14:37:42
2014-01-18 14:37:42 currLoc_Julian home
2014-01-17 19:18:23 lastArr Julian home
2014-01-17 18:41:46 lastDep Julian Office
2014-01-18 14:37:42 lastDevice Julian
2014-01-18 14:37:42 lastDeviceUUID 51F23894-AAAA-BBBB-CCCC-0123456789AB
2014-01-17 18:41:46 lastLocArr_Julian 2014-01-17 08:58:37
2014-01-17 18:41:46 lastLocDep_Julian 2014-01-17 18:41:46
2014-01-17 18:41:46 lastLocLat_Julian 48.1111
2014-01-17 18:41:46 lastLocLong_Julian 11.1111
2014-01-17 18:41:46 lastLoc_Julian Office
2014-01-18 14:37:42 state dev:Julian trig:test id:home lat:48.9999 long:11.9999
</pre>

Möchte man nun etwas bestimmtes tun, wenn man nach Hause kommt oder das Heim verlässt, kann man am Besten ein entsprechendes Notify auf das Reading currLoc_Name setzen. Ich aktualisiere lediglich zwei Dummies, durch die dann alle weiteren Notifies ausgelöst werden:

<pre>
define n_Julian.Presence notify geofancy:currLoc_Julian:.home set Julian.homestatus:FILTER=STATE!=home home
attr n_Julian.Presence room Residents
define n_Julian.absence notify geofancy:currLoc_Julian:.underway {\
if (Value("Julian.homestatus") ne "gone") {\
fhem("set Julian.homestatus:FILTER=STATE!=absent absent");;\
}\
}
define n_Julian.whereabout notify geofancy:currLoc_Julian:.* set Julian.whereabout:FILTER=STATE!=$EVTPART1 $EVTPART1
</pre>

Wer es noch einfacher möchte (bzw. auch noch mehr Features) schaut sich einmal die neue Modulfamilie aus RESIDENTS[http://fhem.de/commandref_DE.html#RESIDENTS], ROOMMATE[http://fhem.de/commandref_DE.html#ROOMMATE] und GUEST[http://fhem.de/commandref_DE.html#GUEST] an. Diese sind direkt auf GEOFANCY abgestimmt. Dabei kann das devAlias Attribut entfallen und man hinterlegt die UUID stattdessen direkt im ROOMMATE oder GUEST Device (Attribut r*_geofenceUUIDs). Das erspart es für jeden Bewohner und jedes Device zig unterschiedliche Devices der Typen Notify, DOIF oder Watchdog anlegen und pflegen zu müssen.

Wer mehr Kontrolle möchte kann natürlich bei notify, DOIF und Co. bleiben: <code>define n_rr_Julian.location notify geofancy:currLoc_Julian:.* set rr_Julian:FILTER=location!=$EVTPART1 location $EVTPART1</code>. Wobei "Julian" dabei als devAlias in GEOFANCY eingtragen wurde, rr_Julian der Name des ROOMMATE aus RESIDENTS ist. Außerdem wurden die Location-IDs in der Geofency.app bzw. Geofancy.app so gewählt, dass diese direkt einem ROOMMATE-Status entsprechen (also z.B. home, wayhome...).

== Beispiele für die Nutzung der Anwesenheitserkennung ==
Hier sollen Beispiele für den Nutzen von Anwesenheitserkennung aufgezeigt werden.

=== Abschalten aller Verbraucher (Licht, Musikanlage) beim Verlassen der Wohnung ===
Typisches Szenario: Man geht ausser Haus, aber hat vergessen im Bad das Licht aus zu machen. Allerdings geht man heutzutage fast garnicht mehr ohne Handy aus dem Haus.

Nun soll FHEM in der gesamten Wohnung das Licht, sowie sonstige Verbraucher ausschalten, wenn ich länger als 15 Minuten ausser Haus bin. Dazu benötigt man zuerst eine structure, die alle Verbraucher und sonstigen Devices, die das betrifft, zusammenfasst.

<pre>
define Gesamte_Wohnung structure Gesamtes_Licht Licht_Wohnzimmer Licht_Kueche LED_Kueche Licht_Bad Licht_Schlafzimmer AV_Receiver TV_Steckdose
attr Gesamte_Wohnung room Wohnung
</pre>

Nun kann man mittels eines watchdogs eine Überwachung für sein Handy anlegen:

<pre>
# Überwachen der gesamten Wohnung mittels collectord sowie presenced in jedem Raum
define Handy PRESENCE lan-bluetooth XX:XX:XX:XX:XX:XX 127.0.0.1:5222
attr Handy event-on-change-reading state # Ein Event soll nur bei der Änderung des Anwesenheitsstatus (Reading: status) erfolgen. Wichtig für den watchdog!!!

# Nach 15 Minuten Abwesenheit (Handy im Status "absent") soll die gesamte Wohnung ausgeschaltet werden.
define watchdog_Anwesenheit watchdog Handy:absent 00:15 Handy:present set Gesamte_Wohnung off ; trigger watchdog_Anwesenheit .
attr watchdog_Anwesenheit regexp1WontReactivate 1
</pre>

=== Benachrichtigung bei Batteriewechsel ===
Mit Hilfe des PRESENCE-Moduls kann man auch bei batteriebetriebenen Geräten eine Meldung ausgeben, sobald ein Batteriewechsel ansteht. Hier im Beispiel wird der Eve-Room-Sensor von Elgato eingebunden und anschließend mit einer DOIF-Nachricht ausgestattet.
Die Bluetooth-Adresse des Sensors kann mittels eines BLE-Scanners ermittelt werden.

<pre>
# PRESENCE-Modul für Elgato Eve Room Sensor mit Aktualisierung aller 6 Minuten
define Eve_Room_BLE lan-bluetooth <Bluetooth-Adresse> 127.0.0.1:5333 360
</pre>

Anschließend wird eine DOIF-Regel definiert, die eine Nachricht an die installiere [[FHEM_APP|FHEM App]] absendet:
<pre>
define Eve_Room_BLE_Battery_Msg DOIF ([Eve_Room_BLE] eq "absent") (set Msg_iPhone message 'Batteriewechsel beim Eve Room Sensor im Wohnzimmer.')
attr Eve_Room_BLE_Battery_Msg wait 600
</pre>

Die Aktualisierung des PRESENCE-Eintrages sollte nicht größer sein als das WAIT-Attribut der DOIF-Regel. Ansonsten könnte eine kurze Systemstörung zum Fehlalarm führen.

== Anwesenheitserkennung Bluetooth PebbleBee mit PRESENCE Modul ==
Im Forum gibt es einen {{Link2Forum|Topic=28753|LinkText=langen Beitrag}} über die Einrichtung eines BT-Tag an einem RaspberryPI mit FHEM. Dabei werden Skripte wie blescan.pl und lepresenced genannt.
Da mittlerweile viele neue Informationen zusammen gekommen sind wurde der Wiki Eintrag erstellt.

Im Folgenden wird die Konfiguration für '''LE Deviced (z.B. Gtags,Pebbles etc.)''' und '''NICHT LE Device (z.B. IPhone)''' beschreiben.

'''Wo finde ich denn lepresenced?'''

lepresenced kann über Github heruntergeladen werden (Link weiter unten)

'''Was ist der Vorteil gegenüber blescan.pl?'''

{{Randnotiz|RNText=Beide hier beschriebenen Wege (presenced/lepresenced) können parallel auf dem selben BT-Dongle laufen, da sich die Ports unterscheiden!}}
blescan.pl hat u. a. das Problem, dass dank der wundervollen Bluetooth-Implementierung unter Linux ab und zu der Scan fehlschlägt und das Interface resettet werden muss. Das tut blescan.pl auch mit aller Gewalt. Dazu kommt, dass bei längeren Scanzeiten und vielen Tags sich die Prozesse anstauen, weil immer nur auf einen Tag "gewartet" wird. Außerdem wurden mit der Einführung von lepresenced sämtliche Supportverträge gekündigt lepresenced läuft dauerhaft und merkt sich bei allen sendenden Tags den Zeitstempel des letzten Empfangs.

=== Getestete Hardware/Software===
* '''Raspbian System''' - wheezy, Jessie
* '''BT-Dongle''' - CSL NET BT USB2.0 Stick, Bluetooth V4.0, Nano <br />'''Achtung''': Es muss ein BT V4.0 oder höher verwendet werden. Nur dieser unterstützt ''LowEnergy''
* '''BT-TAG''' - Gtag von Gigaset, TrackR, UDOO Neo, PebbleBee, iTag von Unitec, X4-LIFE Multifunkti BL-Anhänger, iTag Wireless Anti, Trackr bravo

=== BT Dongel am PI installieren ===

Um den BT Dongle ''(hier: CSL NET BT USB2.0)'' am PI verwenden zu können, müssen die notwendigen Pakete über die Paketverwaltung von debain nachinstalliert werden.
Wer bereits ein BT-Dongle installiert hat, kann diesen Schritt überspringen.
<pre>
apt-get install bluetooth
</pre>
Nach erfolgreicher Installation der Pakete sollte der RaspberryPI neu gestartet werden.
<pre>
sudo reboot
</pre>

Nach dem erfolgten Reboot bitte das Log des Raspberry auf folgende Einträge prüfen:
<pre>
Feb 12 19:52:55 fhem kernel: [ 4.773600] Bluetooth: Core ver 2.20
Feb 12 19:52:55 fhem kernel: [ 4.773748] NET: Registered protocol family 31
Feb 12 19:52:55 fhem kernel: [ 4.773765] Bluetooth: HCI device and connection manager initialized
Feb 12 19:52:55 fhem kernel: [ 4.773797] Bluetooth: HCI socket layer initialized
Feb 12 19:52:55 fhem kernel: [ 4.773821] Bluetooth: L2CAP socket layer initialized
Feb 12 19:52:55 fhem kernel: [ 4.773890] Bluetooth: SCO socket layer initialized
Feb 12 19:52:55 fhem kernel: [ 4.797531] usbcore: registered new interface driver btusb
</pre>
Sobald der BT-Dongle erkannt wurde ''leuchtet'' (wenn vorhanden) auch die ''blaue/gelbe'' LED am Dongle auf.

=== BT-Tags aktivieren ===
Jetzt kann der BT-Tag aktiviert werden. Bei einigen Tags muss dafür die '''Batteriesicherung''' gezogen werden.

Einen Tag wird mit folgendem Befehl auf der Konsole gesucht:
<source lang="bash">
sudo hcitool lescan

Ausgabe z.B.:
LE Scan ...
7C:2F:80:A1:XA:XD (unknown)
7C:2F:80:A1:XA:XD Gigaset G-tag
7C:2F:80:A1:X4:X1 (unknown)</source>
Eine Übersicht über die möglichen Befehle von hcitool gibt es mit der Eingabe von:
<pre>
sudo hcitool

Ausgabe z.B.:
hcitool - HCI Tool ver 5.23
Usage:
hcitool [options] <command> [command parameters]
Options:
--help Display help
-i dev HCI device
Commands:
dev Display local devices
inq Inquire remote devices
scan Scan for remote devices
name Get name from remote device
info Get information from remote device
spinq Start periodic inquiry
epinq Exit periodic inquiry
cmd Submit arbitrary HCI commands
con Display active connections
cc Create connection to remote device
dc Disconnect from remote device
sr Switch master/slave role
cpt Change connection packet type
rssi Display connection RSSI
lq Display link quality
tpl Display transmit power level
afh Display AFH channel map
lp Set/display link policy settings
lst Set/display link supervision timeout
auth Request authentication
enc Set connection encryption
key Change connection link key
clkoff Read clock offset
clock Read local or remote clock
lescan Start LE scan
lewladd Add device to LE White List
lewlrm Remove device from LE White List
lewlsz Read size of LE White List
lewlclr Clear LE White list
lecc Create a LE Connection
ledc Disconnect a LE Connection
lecup LE Connection Update
</pre>

Falls beim SCAN kein Tag gefunden wird, sollte das BT Interface neu gestartet werden. Dazu ist kein Reboot des PI notwendig.
<source lang="bash">
sudo hciconfig hci0 down
sudo hciconfig hci0 up
sudo hcitool dev
</source>

=== Anleitung für ein LE Device (z.B. Gtags,Pebbles etc.) ===

Herunterladen des Skripts lepresenced.
<pre>
https://github.com/mhop/fhem-mirror/blob/master/fhem/contrib/PRESENCE/lepresenced
</pre>

Zur "Installation" des Skripts folgendermaßen vorgehen:
Unter /fhem manuell den Ordner „script“ anlegen:
<pre>
mkdir script
</pre>
Datei lepresenced reinkopieren und ausführbar machen:
<pre>
sudo chmod +x /opt/fhem/script/lepresenced
sudo chgrp -cR dialout lepresenced
</pre>
Skript erstmalig starten:
<pre>
sudo ./lepresenced --loglevel LOG_EMERG -d
</pre>
Kommt beim Starten des Skript eine Fehlermeldung, müssen die Abhängigkeiten aufgelöst werden.
<pre>
Can't locate Net/Server/Daemonize.pm in @INC (@INC contains: /etc/perl /usr/local/lib/perl/5.14.2 /usr/local/share/perl/5.14.2 /usr/lib/perl5 /usr/share/perl5 / usr/lib/perl/5.14 /usr/share/perl/5.14 /usr/local/lib/site_perl .) at /opt/fhem/lepresenced line 17.
BEGIN failed--compilation aborted at /opt/fhem/lepresenced line 17.
</pre>
Um die Abhängigkeiten aufzulösen muss folgendes nachinstalliert werden und anschließend ein Reboot durchgeführt werden.
<pre>
sudo apt-get install libnet-server-*
</pre>

Nach dem letzten Schritt sind alle Bedingungen für eine abschließende Konfiguration der BT-Tags in FHEM abgeschlossen worden.
Jetzt kann der Tag dem FHEM-Server bekannt gemacht werden.
<pre>
-- Name Modul Modus MAC vom Gtag IP vom PI Port Abfragezeit in Sekunden
define MeinGtAG PRESENCE lan-bluetooth xx:xx:xx:xx:xx:xx 127.0.0.1:5333 120
</pre>

Den absent und present Mode kann man einfach testen, in dem man den Gtag mit Alufolie einwickelt.

=== Anleitung für ein NICHT LE Device (z.B. IPhone) ===
Die Installation kann (wie in der commanref beschrieben) über Debian Pakete erfolgen.
<pre>
.deb package for Debian (noarch): presenced-1.3.deb http://svn.code.sf.net/p/fhem/code/trunk/fhem/contrib/PRESENCE/deb/presenced-1.3.deb

.deb package for Raspberry Pi (raspbian): presenced-rpi-1.3.deb http://svn.code.sf.net/p/fhem/code/trunk/fhem/contrib/PRESENCE/deb/presenced-rpi-1.3.deb
</pre>

<pre>
sudo dpkg -i presenced-rpi-1.3.de
</pre>

Installation perl script file (Auszug commanref)
<pre>
direct perl script file: presenced http://svn.code.sf.net/p/fhem/code/trunk/fhem/contrib/PRESENCE/presenced
</pre>

Nach dem letzten Schritt sind alle Bedingungen für eine abschließende Konfiguration der BT-Tags in FHEM abgeschlossen worden.
Jetzt kann der Tag dem FHEM-Server bekannt gemacht werden.
{{Randnotiz|RNText=Wenn man mit collectord arbeitet muß man die Erkennung bei allen Devices auf port 5222 setzen.
lan-bluetooth xx:xx:80:xx:xx:AC 127.0.0.1:5222 20 120}}
<pre>
-- Name Modul Modus MAC vom Gtag IP vom PI Port Abfragezeit in Sekunden
define MeinGtAG PRESENCE lan-bluetooth xx:xx:xx:xx:xx:xx 127.0.0.1:5333 120
</pre>

=== Automatischer Start ===

Damit das leprecend Skript beim Systemstart mitgestartet wird, sollte eine Crontab Eintrag gesetzt werden. Alternativ die rc.local anpassen.
Ersteres würde so aussehen:

Ein sh-Skript mit dem Inhalt:
<pre>
sudo start-stop-daemon -d /opt/fhem/script -S -x /opt/fhem/script/lepresenced
</pre>
unter dem Verzeichnis /home/pi ablegen, welches sich init_start.sh nennt.

Das Skript dann unter: sudo crontab -e einhängen mit folgender Folge:
<pre>
@reboot /home/pi/init_start.sh
</pre>

Zweiteres so:
<pre>
sudo nano /etc/rc.local
</pre>

Datei rc.local, freie Stelle suchen, vor "exit 0":

<pre>
# Start lepresenced
/opt/fhem/script/lepresenced --loglevel LOG_EMERG -d
exit 0
</pre>

=== Batterieüberwachung (aktuell nur G-Tags) ===

Leider überträgt der G-Tag nach der Einrichtung als Device in FHEM kein Reading mit seinem aktuellen Batteriestatus.
Dem wurde mit Hilfe des Forum Abhilfe geschaffen.
Im Folgenden wird erläutert wie die Batterieüberwachung eingerichtet werden kann.

'''Voraussetzung:'''

bc - Basiscalculator [https://packages.debian.org/de/sid/bc Bc-Paket]
<pre> sudo apt-get install bc </pre>

Anlegen eines Shellskript auf dem Raspberry System.
Die Parameter <<MAC-Adresse>> und <<TagName>> müssen durch die Werte des auszulesenden G-Tags ersetzt werden.
<pre>
#!/bin/bash
stringZ=$(sudo gatttool -b 5C:2B:80:C1:14:41 --char-read --handle=0x001b)
stringZ=${stringZ:33:2}
stringZ=$(echo "$stringZ" | tr a-f A-F)
decimal=$(echo "ibase=16; $stringZ" | bc)
perl /opt/fhem/fhem.pl 7072 "setreading MeinGtag Batterie $decimal"
</pre>

Dem Device in FHEM (hier MeinGtag) ein userReading mit dem Namen '''Batterie''' hinzufügen.
Das Shellskript mit folgendem Befehl starten:
<pre>
./GtagBatterie.sh
</pre>
'''Wichtig ist hierbei,''' dass Skript mit "./" und nicht mit "sh" aufzurufen. Beim Aufruf mit "sh GtagBatterie.sh" produziert es einen Fehler
<pre>GtagBatterie.sh: 3: GtagBatterie.sh: Bad substitution </pre>

Das Reading wird auf den ausgelesenen Wert der Batterie gesetzt.

Hinweis: Es sollte für jeden G-Tag ein eigenes Skript abgelegt werden. Das Skript kann per crontab oder fhem Kommando (system) regelmäßig aufgerufen werden.

=== Batterieüberwachung (alle Devices vom Typ "MODE=lan-bluetooth") ===

Es gibt eine weitere Möglichkeit um den Batteriestatus von LE Devices abzurufen und in FHEM als Reading darzustellen.
Dabei wird der Batteriezustand für alle LE Devices, die bereits in FHEM konfiguriert sind und per lepresenced überwacht werden, automatisch in einem shell-Script ermittelt.
Näheres dazu im Forumartikel [https://forum.fhem.de/index.php/topic,56960.0.html [Erweiterung]: Anwesenheitserkennung/Batterieüberwachung].

Vorteile:
* Automatische Ermittlung aller in FHEM konfigurierten LE Devices
* Möglichkeit, diese Devices alternativ manuell im Script einzutragen
* Es werden nur Devices abgefragt, die im Status "present" sind, also mit ziemlicher Sicherheit auch verfügbar sind
* Ein eventuell auf dem FHEM telnet-Port gesetztes Passwort kann im Script hinterlegt werden

'''Voraussetzung:'''

'''Funktionierendes lepresenced''' - siehe [[Anwesenheitserkennung#Anleitung_f.C3.BCr_ein_LE_Device_.28z.B._Gtags.2CPebbles_etc..29|Anleitung für ein LE Device (z.B. Gtags,Pebbles etc.)]]

'''socat''' - TCP port forwarder
<pre>
sudo apt-get update && sudo apt-get install socat
</pre>

'''gatttool''' - Bestandteil von bluez

gatttool ist auf den meisten Distributionen im bluez-Paket, allerdings nicht bei Opensuse. Dort muss man das Sourcepaket von bluez installieren und selbst kompilieren.
gatttool sollte dann nach /usr/bin oder /usr/local/bin kopiert werden,

Zusätzlich zu den notwendigen Erweiterungen werden für die Ausführung von gatttool '''Root-Rechte benötigt'''!

Das Script selbst gibt es hier: [https://raw.githubusercontent.com/micky0867/lebattery/master/lebattery lebattery]

Am Besten unter /opt/fhem/script/lebattery speichern und ausführbar machen:
<source lang="bash">
sudo su -
mkdir /opt/fhem/script
cd /opt/fhem/script
wget https://raw.githubusercontent.com/micky0867/lebattery/master/lebattery
chmod 755 lebattery
</source>

Je nach Bedarf können im Script noch die folgenden 3 Parameter angepasst werden:
<source lang="bash">
# If allowed_telnetPort is protected by a password, add the password here
TELNETPASSWORD=""
# Attribute for batterylevel in FHEM
ATTRIBUT="batterylevel"
# Use this, if you dont want the script to determine the tags on its own
LETAGS=""
</source>

Das Skript wird dann unter root folgendermaßen gestartet:
<pre>
/opt/fhem/script/lebattery -v
</pre>

Ausgabe des Skripts, wenn es mit dem Verbose Parameter -v gestartet wird.

Beide Devices sind vom Typ NUT mini, das Device mit dem FHEM-Namen '''nut_Micky''' ist im Status '''absent'''. Das zweite Device ist im Status '''present'''.
<pre>
Determining address for nut_Micky ...
nut_Micky is in state absent, no further action required

Determining address for nut_Test ...
Fetching batterylevel for nut_Test (F3:44:04:81:54:89) ...
Setting batterylevel for nut_Test to 100%
</pre>

Mein crontab-Eintrag (User root) sieht so aus:
<pre>
3 3 * * * /opt/fhem/script/lebattery -v >/opt/fhem/script/lebattery.log 2>&1
</pre>
Damit wird jeden Morgen um 3 Minuten nach 3 Uhr der Zustand der Batterien aller Devices ermittelt und in FHEM abgespeichert.<br>
Bevor man das mit crontab macht, sollte man allerdings zunächst sicher stellen, dass es auch ohne crontab funktioniert....

Bei Problemen kann man auch erstmal schauen, ob das mit dem gattool überhaupt funktioniert:
<pre>
gatttool -t random -b <MAC-Adresse> --char-read --uuid 0x2a19

handle: 0x0017 value: 64
</pre>
In diesem Fall hat die Batterie noch 100% (hex 64).

=== Anwesenheitserkennung / Anwesenheitsbenachrichtigung mit G-Tags ===

Ein Skript zur Nutzung der Gigaset G-TAGs zur Alarmierung bei öffnen und schließen von Türen und zur Anwesenheitserkennung, um die Alarmierung zu aktivieren bzw. deaktivieren.
Es kann verwendet werden um die Anwesenheit von mehrern Personen im Haushalt zu erkennen. Dabei wird eingeschränkt, dass nur bestimmte Personen die Alarmierung aktivieren können ( Eltern/Kind -Beziehung ).
Des Weiteren werden im Beispiel die Eltern benachrichtigt wenn eins der Kinder das Haus verlässt und die Eltern nicht anwesend sind.

{{Randnotiz|RNText= Namen der G-Tags in den Skripten bitte Anpassen!}}

Für die ''Notify'' und die ''RESIDENTS-Erweiterung'' wird ein Dummy benötigt.
<pre>
define Alarm dummy
attr Alarm devStateIcon aktiv:secur_locked@red inaktiv:secur_open@lightgreen
attr Alarm eventMap on:aktiv off:inaktiv
attr Alarm setList on off
attr Alarm webCmd aktiv:inaktiv
attr Alarm room Alarm
</pre>

====Mit Notify ====
<pre>
gtag.*.presence:.* {Anwesenheit_check("$EVTPART1", "$NAME")}
</pre>

Code für die 99_myUtils.pm
<pre>
### GTAG ANWESENHEITS CHECK
sub Anwesenheit_check($$) {
my ($EVENT, $NAME) = @_;
my $ALIASNAME = AttrVal($NAME,'alias',$NAME); # ALIAS des GTAGs auslesen
my $GTAG1 = Value('gtag_rot'); # ELTERN
my $GTAG2 = Value('gtag_schwarz'); # ELTERN

Log 1, "$ALIASNAME ist $EVENT."; # LOG Eintrag erzeugen

if (($EVENT eq "anwesend" && Value("Alarm") eq "aktiv") && ($NAME eq "gtag_gruen" xor $NAME eq "gtag_orange")) {
fhem("set Infopush msg 'ALARMIERUNG BLEIBT AKTIV' '$ALIASNAME ist da...'");
}
elsif (($EVENT eq "anwesend" && Value("Alarm") eq "aktiv") && ($NAME eq "gtag_rot" xor $NAME eq "gtag_schwarz")) {
fhem("set Infopush msg 'ALARMIERUNG INAKTIV' '$ALIASNAME ist da...'; set Alarm inaktiv");
}
elsif (($EVENT eq "unterwegs" && Value("Alarm") eq "aktiv") && ($NAME eq "gtag_gruen" xor $NAME eq "gtag_orange")) {
fhem("set Infopush msg 'ALARMIERUNG BLEIBT AKTIV' '$ALIASNAME hat das Haus verlassen.'");
}
elsif (($EVENT eq "unterwegs" && Value("Alarm") eq "inaktiv") && ($GTAG1 eq "unterwegs" && $GTAG2 eq "unterwegs")) {
fhem("set Alarm aktiv; set Infopush msg 'ALARMIERUNG AKTIV' '$ALIASNAME hat als letztes das Haus verlassen.' '' 0 ''");
}
}
</pre>

<br>
====Mit Notify und Integration des RESIDENTS-MODUL====

Der hier beschriebene Code erweitert die Funktionen unter dem Punkt 5.93.
Das Notify muss daher mit der folgenden Zeile erweitert werden.

<pre>
define Alarm_AnwesenheitCheck notify gtag.*.presence:.* { Anwesenheit_check("$EVTPART1", "$NAME"), Anwesenheit_check_resi("$NAME") }
</pre>

Zusätzlicher Code für die 99_myUtils.pm um die RESIDENTS Funktion nutzen zu können:
<pre>
### RESIDENTS
sub Anwesenheit_check_resi($) {
my ($NAME) = @_;
my $ALIASNAME = AttrVal($NAME,'alias',$NAME); # ALIASNAME des GTAGs auslesen
my $RESIUSER = "rr_"; # rr_ Residents Roommate rg_ für Residents Guest
my $ROOMMATE = ("$RESIUSER" . "$ALIASNAME"); # Residentsname zusammenbauen

if (ReadingsVal($NAME,'presence',$NAME) eq "absent") {
fhem("set $ROOMMATE absent"); # Resisents Status von Roommates setzen
}
elsif(ReadingsVal($NAME,'presence',$NAME) eq "present") {
fhem("set $ROOMMATE home"); # Resisents Status von Roommates setzen
}
}
</pre>

Da bei Residents die Benutzernamen unterschiedlich sind für Bewohner (beginnend mit "rr_") und Gäste (beginnend mit "rg_") wurden nur die Bewohner berücksichtigt.
<br>

====Mit Notify und Fenster/Tür. -Kontakt Überwachung====

Erweiterung für die Überwachung von Fenster/Tür. -Kontakten. Dazu sind zwei weitere Notifys notwendig die auf die Trigger der Kontakte regagieren
und so eine weitere Funktion in der 99_myUtils.pm ansprechen. Die Notifys triggern auf Kontakte die mit dem Namen Kontakt* beginnen.
Sollten die eigenen Fenster/Tür. -Kontakt anderen Namen besitzen, müssen die Skripte dementsprechend angepasst werden.
<pre>
define Alarm_Kontaktmeldung notify Kontakt.*:contact:.* {Kontakt_Meldung("$EVTPART1", "$NAME")}
</pre>
<pre>
define Alarm_Sabotagealarm notify Kontakt.*.sabotageError:.on {Kontakt_Sabotage("$EVTPART1", "$NAME")}
</pre>

Zusätzlicher Code für die 99_myUtils.pm um die TÜRKONTAKTE-Meldung nutzen zu können:
<pre>
### TÜRKONTAKTE-Meldung/Zustand
sub Kontakt_Meldung($$) {
my ($EVENT, $NAME) = @_;
my $ALIASNAME = AttrVal($NAME,'alias',$NAME);
Log 1, "$ALIASNAME wurde $EVENT";
if (ReadingsVal("Alarm", "state", "on") eq "on") {
fhem("set teleBot send $ALIASNAME wurde $EVENT"); # Nachricht über Telegram
# fhem("set Infopush msg '$ALIASNAME' '$ALIASNAME wurde $EVENT'"); # Nachricht über Pushover
}
}

### TÜRKONTAKTE-Sabotagealarm

sub Kontakt_Sabotage($$) {
my ($EVENT, $NAME) = @_;
my $ALIASNAME = AttrVal($NAME,'alias',$NAME);
Log 1, "$ALIASNAME meldet Sabotagealarm";
fhem("set teleBot send Alarm: $ALIASNAME meldet Sabotagealarm"); # Nachricht über Telegram
# fhem("set Infopush msg 'Alarmanlage' '$ALIASNAME meldet Sabotagealarm' '' 2 ' ' 60 600 "); # Nachricht über Pushover
}
</pre>
<br>

==== Hinweis zur Benutzung / Fehlerhandling ====

Der Alarm dummy hat den Zustand on:off. Die Bezeichnungen und Namen müssen 1:1 übernommen werden damit das Script funktioniert.
Andernfalls müssen die Bezeichnungen für z.B. absent:unterwegs und present:anwesend - angepasst werden.
Die Benachrichtigung kann aktuell per ''Telegram'' sowie ''Pushover'' ('''Achtung mit zweiterem sind Abokosten verbunden!''') realisiert werden.
Diskussion zum Thema im Forum unter: [[https://forum.fhem.de/index.php/topic,64080.0.html]]
<br>

=== Problemlösungen ===
Falls es Probleme beim Starten des Skripts gibt bzw. man das Skript ohne Reboot des Systems neustarten möchte, kann man dies per kill Befehl erledigen.
<source lang="bash">
ps -ef | grep lepresenced
sudo kill <pid>
</source>

Debuglevel lepresenced setzen:
{{Randnotiz|RNText=Um Debug-Meldungen zu bekommen (Vorsicht bei SD-Karten-Systemen wie dem RPi) - Hierbei werden die Schreibzyklen auf die SD-Karte erhöht.}}
<pre>
lepresenced --loglevel LOG_DEBUG
</pre>
Nur das wichtigste Loggen:
<pre>
lepresenced --loglevel LOG_WARNING
</pre>
Keinerlei LOG-Einträge
<pre>
lepresenced --loglevel LOG_EMERG
</pre>

==== Ansprechpartner ====
# {{Link2FU|5068|PatrikR}} (Patrick) für lepresenced
# [[Benutzer Diskussion:Devender|Devender]] ({{Link2FU|20043|Dirk}}) für Wiki und Doku

[[Kategorie:Code Snippets]]
[[Kategorie:Glossary]]

DevelopmentModuleIntro

2017-01-15T18:49:08Z

Kaihs: /* X_Read */ Codebeispiel korrigiert

{{Hinweis|Dieser Text ist in Arbeit und muss noch an einigen Stellen ergänzt werden. }}

== Einleitung ==

Um neue Geräte, Dienste, o.ä. in FHEM verfügbar zu machen, kann man ein eigenes Modul in Perl schreiben. Ein Modul wird in FHEM automatisch geladen, wenn ein entsprechendes Device in FHEM definiert wird. Das Modul ermöglicht eine spezifische Kommunikation mit einem physikalischen Gerät, stellt Ergebnisse ("Readings") und Events innerhalb von FHEM zur Verfügung und erlaubt es, das Gerät mit "Set"-/"Get"-Befehlen zu beeinflussen. Dieser Artikel soll den Einstieg in die Entwicklung eigener Module erleichtern.

Mit dem FHEM-Befehl <code>define</code> werden Devices in FHEM basierend auf einem Modul definiert. Dieser Befehl sorgt dafür, dass ein neues Modul bei Bedarf geladen und initialisiert wird. Ein gutes Beispiel ist hierbei die zentrale Konfigurationsdatei "fhem.cfg" in der sämtliche Devices in Form von <code>define</code>-Statements gespeichert sind.

Damit das funktioniert müssen der Name des Moduls und der Name der [[#X_Initialize|Initialisierungsfunktion]] identisch sein. Das folgende Beispiel soll dies verdeutlichen:

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

In fhem.pl wird der define-Befehl verarbeitet und geprüft, ob ein Modul mit dem Namen "JeeLink" schon geladen ist und falls nicht ein Modul mit Namen XY_JeeLink.pm im Modulverzeichnis (z.B. /opt/fhem/FHEM) gesucht und dann geladen.
Danach wird die Funktion <code>''JeeLink''_Initialize()</code> aufgerufen um das Modul in FHEM zu registrieren. Eine Moduldatei muss dazu eine Funktion <code>''<Modulname>''_Initialize()</code> enthalten. Durch den Aufruf dieser Funktion wird FHEM mitgeteilt, welche Funktionalitäten dieses Modul unterstützt.

In der Initialisierungsfunktion des Moduls werden die Namen aller weiteren Perl-Funktionen des Moduls, die von fhem.pl aus aufgerufen werden, bekannt gemacht. Dazu wird für jedes Modul ein eigener Hash (genauer "Modul-Hash") mit entsprechenden Werten gefüllt, der in fhem.pl für jedes Modul entsprechend abgelegt wird. Dadurch weiß FHEM wie dieses Modul anzusprechen ist.

== Grundlegender Aufbau eines Moduls ==

=== Dateiname ===

Ein FHEM-Modul wird als Perl-Modul mit der Dateiendung *.pm abgespeichert. Der Dateiname folgt dabei folgendem Schema:

:<code>''['''Schlüsselnummer''']''<font color="grey">_</font>''['''Modulname''']''<font color="grey">.pm</font></code>

* '''Schlüsselnummer''' - Eine zweistellige Zahl zwischen 00 - 99. Die Schlüsselnummer hat aktuell keine technische Relevanz mehr. In früheren FHEM-Versionen ist sie relevant für [[#Zweistufiges_Modell_f.C3.BCr_Module|zweistufige Module]] (Reihenfolge für [[DevelopmentModuleAPI#Dispatch|Dispatch()]] um logische Module zu prüfen). Die allgemeine Empfehlung ist hierbei eine Schlüsselnummer eines Moduls zu verwenden, welches eine ähnliche Funktionalität bietet. Die Schlüsselnummer 99 hat hierbei eine besondere Bedeutung, da alle Module mit dieser Schlüsselnummer beim Start von FHEM automatisch geladen werden, selbst, wenn sie in der Konfiguration nicht verwendet werden. Daher wird für myUtils 99 als Schlüsselnummer verwendet (99_myUtils.pm). Module mit der Schlüsselnummer 99 werden im SVN nicht akzeptiert (siehe [[SVN Nutzungsregeln]])
* '''Modulname''' - Der Name des Moduls wie er in FHEM bei dem Anlegen einer Gerätedefinition zu verwenden ist. Der Modulname sollte nur aus den folgenden möglichen Zeichen bestehen: Groß-/Kleinbuchstaben, Zahlen sowie Unterstrich (_)

=== Inhaltlicher Aufbau ===

Ein Modul ist inhaltlich in folgende Abschnitte unterteilt:

<source lang="perl">
#
# 72_MYMODULE.pm
#

package main;

# Laden evtl. abhängiger Perl- bzw. FHEM-Module
use HttpUtils;
use [...]

# FHEM Modulfunktionen

sub MYMODULE_Initialize() {
...
}

sub MYMODULE_Define() {
...
}

...

# Eval-Rückgabewert für erfolgreiches
# Laden des Moduls
1;

# Beginn der Commandref

=pod
=item [helper|device|command]
=item summary Kurzbeschreibung in Englisch was MYMODULE steuert/unterstützt
=item summary_DE Kurzbeschreibung in Deutsch was MYMODULE steuert/unterstützt

=begin html
Englische Commandref in HTML
=end html

=begin html_DE
Deustche Commandref in HTML
=end html

# Ende der Commandref
=cut
</source>

Man kann hierbei von folgender Reihenfolge sprechen:

# Perl-Code, welcher das Modul implementiert
# Die Zeile <code>1;</code> nachdem der Perl-Code abgeschlossen ist. Dies dient FHEM der Erkennung, dass das Modul erfolgreich und vollständig geladen wurde. Sollte diese Zeile nicht enthalten sein, wird FHEM beim Laden des Moduls die Fehlermeldung <code>Error:Modul 72_MYMODULE deactivated</code> in das Logfile schreiben.
# Commandref zur Dokumentation des Moduls. Diese Dokumentation soll dem User die möglichen Befehle/Attribute/Readings/Events vermitteln. Weitere Informationen und Hinweise findet man in den [[Guidelines zur Dokumentation]].

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

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

In fhem.pl werden alle Gerätedefinitionen in dem globalen Hash <code>%defs</code> abgelegt. Der Inhalt von <code>$defs{''<Name>''}</code> in fhem.pl verweist dabei auf den Hash der Geräteinstanz in Form einer Hashreferenz. Diesen Verweis (also nur die Adresse) bekommen die Funktionen eines Moduls übergeben (i.d.R. als <code>$hash</code> bezeichnet), welche direkt von fhem.pl aufgerufen werden. In dem Hash stehen beispielsweise die internen Werte des Geräts, die im Frontend als "Internals" angezeigt werden, sowie die Readings des Geräts.

Beispiele:
*<code>$hash->{NAME}</code> enthält den Namen der Geräteinstanz,
*<code>$hash->{TYPE}</code> enthält die Typbezeichnung des Geräts (Modulname)

==Ausführung von Modulen==
FHEM arbeitet intern nicht parallel, sondern arbeitet alle Aufgaben seriell nacheinander kontinuierlich ab. Daher wäre es ungünstig, wenn Module Daten von einem physikalischen Gerät abfragen wollen und dabei innerhalb der selben Funktion auf die Antwort des Geräts warten. In dieser Zeit, in der FHEM auf die Antwort des Gerätes warten muss, wäre der Rest von FHEM blockiert. Da immer nur eine Aufgabe zur selben Zeit bearbeitet wird, müssen alle weiteren Aufgaben solange warten. Eine Datenkommunikation innerhalb eines Moduls sollte daher immer ohne Blockierung erfolgen. Dadurch kann FHEM die Wartezeit effizient für andere Aufgaben nutzen um bspw. anstehende Daten für andere Module zu verarbeiten. Es gibt in FHEM entsprechende Mechanismen, welche eine "Non-Blocking"-Kommunikation über verschiedene Wege (z.B. seriell, HTTP, TCP, ...) ermöglichen.

Dafür werden in FHEM zwei zentrale Listen gepflegt, in der die Filedeskriptoren der geöffneten Kommunikatonsverbindungen gespeichert sind. Auf Linux- bzw. Unix-basierten Plattformen wird der select-Befehl des Betriebssystems verwendet um Filedeskriptoren auf lesbare Daten zu überprüfen. In FHEM gibt es dazu eine Liste (<code>%selectlist</code>), in der die Filedeskriptoren sämtlicher Geräte (z.B. serielle Verbindung, TCP-Verbindung, etc.) gespeichert sind.

In der zentralen Schleife (Main-Loop) von fhem.pl wird mit <code>select()</code> überwacht, ob über eine der geöffneten Schnittstellen Daten zum Lesen anstehen. Wenn dies der Fall ist, dann wird die Lesefunktion ([[#X_Read|X_Read]]) des zuständigen Moduls aufgerufen, damit es die Daten entgegennimmt und verarbeitet. Anschließend wird die Schleife weiter ausgeführt.

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

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

Auch wenn von einem Anwender über einen Get-Befehl Daten aktiv von einem Gerät angefordert werden, sollte nicht blockierend gewartet werden. Eine asynchrone Ausgabe, sobald das Ergebnis vorliegt, ist über [[DevelopmentModuleAPI#asyncOutput|asyncOutput()]] möglich. Siehe {{Link2Forum|Topic=43771|Message=357870|LinkText=Beschreibung}} und {{Link2Forum|Topic=43771|Message=360935|LinkText=Beispiel}}. Weitere Anwendungsbeispiele finden sich im {{Link2Forum|Topic=43052|Message=353477|LinkText=PLEX Modul}} und im überarbeiteten und nicht-blockierenden {{Link2Forum|Topic=42771|Message=348498|LinkText=SYSSTAT Modul}}.

== Wichtige globale Variablen aus fhem.pl ==

FHEM arbeitet mit einer Vielzahl an internen Variablen. Die nun folgenden aufgelisteten Variablen sind die wichtigsten, welche man im Rahmen der Modulprogrammierung kennen sollte:

{| class="wikitable"
|-
! Variable !! Beschreibung
|-
| <code>$init_done</code> || Dient der Erkennung für fhem.pl sowie den Modulen, ob FHEM den Initialisierungsvorgang abgeschlossen hat. Beim Starten von FHEM ist <code>$init_done</code> gleich <code>0</code>. Erst, wenn das Einlesen der Konfiguration, sowie des State-Files (Readings) abgeschlossen ist, wird <code>$init_done</code> auf <code>1</code> gesetzt.
Das gleiche Verfahren wird auch bei dem Befehl <code>rereadcfg</code> angewandt. Während <code>rereadcfg</code> ausgeführt wird (Konfiguration löschen, neu einlesen), ist <code>$init_done</code> gleich <code>0</code>.

Dies ist insbesondere in der [[#X_Define|Define]]-Funktion eines Moduls relevant.
|-
| <code>%attr</code> || In <code>%attr</code> werden sämtliche gesetzten Attribute aller Geräte gespeichert. Diese Datenstruktur wird generell durch den <code>attr</code>-Befehl verwaltet. Hierbei wird einem Gerätenamen eine Mehrzahl an Attributnamen mit einem Wert zugeordnet. Attribut-Inhalte können über die Funktion [[DevelopmentModuleAPI#AttrVal|AttrVal()]] ausgelesen werden.
|-
| <code>%cmds</code> || In <code>%cmds</code> wird jedem in FHEM existierendem Befehl die entsprechende Funktion zugewiesen, welche diesen Befehl umsetzt. Module können durch das Eintragen eines Befehlsnamen samt Funktion in <code>%cmds</code> über die [[#X_Initialize|Initialize]]-Funktion eines Moduls einen (oder mehrere) eigene Befehle in FHEM registrieren.

Die Struktur ist dabei wiefolgt:

$cmds{''<Befehlsname>''} = { Fn => "''<Funktionsname>''",
Hlp => "''<Aufrufsyntax>''"};

|-
| <code>%data</code>|| Der eigentliche Zweck von <code>%data</code> ist dem Nutzer eine Möglichkeit zum Speichern von temporären Daten im globalen Kontext zu ermöglichen. Einige Module verwenden <code>%data</code> jedoch auch um modul- & geräteübergreifend Daten auszutauschen.
|-
| <code>%defs</code>|| In <code>%defs</code> werden sämtliche Gerätedefinitionen, bzw. die Hash-Referenzen auf diese, gespeichert. Hier ist jedem Gerätenamen eine Hash-Referenz zugeordnet.
|-
| <code>%modules</code>|| In <code>%modules</code> sind alle geladenen Module gelistet mit ihren entsprechenden Initialisierungsdaten (Funktionsnamen, Attribut-Listen, spezielle Einstellungen, ...). Hier wird für jeden Modulname der Modul-Hash aus der [[#X_Initialize|Initialize]]-Funktion gespeichert.
Desweiteren legen viele Module, welche nach dem [[DevelopmentModuleIntro#Zweistufiges_Modell_f.C3.BCr_Module|zweistufigen Modulkonzept]] hier eine Rückwärtszuordnung von Geräteadressen zu Geräte-Hash an.
|-
| <code>%readyfnlist</code>|| In <code>%readyfnlist</code> sind alle zu prüfenden Verbindungen mit ihrer entsprechendem Geräte-Hash gelistet. FHEM prüft alle hier gelisteten Geräte regelmäßig über eine Aufruf der entsprechenden [[#X_Ready|Ready]]-Funktion.

Bei einer Nutzung von dem Hilfsmodul DevIo.pm zum Aufbau einer Kommunikationsverbindung, kümmert sich DevIo selbständig um den entsprechenden Eintrag in <code>%readyfnlist</code>.
|-
| <code>%selectlist</code>|| In <code>%selectlist</code> sind alle geöffneten Verbindungen mit ihrer entsprechendem Geräte-Hash gelistet. FHEM prüft alle hier gelisteten Geräte, ob der geöffnete Filedeskriptor unter <code>$hash->{FD}</code> Daten zum Lesen bereitgestellt hat. Ist dass der Fall, wird die entsprechende [[#X_Read|Read]]-Funktion aufgerufen, um anstehende Daten durch das Modul zu verarbeiten.
Bei einer Nutzung von dem Hilfsmodul DevIo.pm zum Aufbau einer Kommunikationsverbindung, kümmert sich DevIo selbständig um den entsprechenden Eintrag in <code>%selectlist</code>.
|}

Es gibt durchaus viele weitere globale Variablen, die jedoch für sehr spezielle Anwendungsfälle und z.T. nur einzelne Module gedacht sind und daher hier nicht aufgeführt werden.

== Internals ==
Daten, die ein Modul im Geräte-Hash speichert nennt man Internals. Sie werden als Unterstruktur des Hashes der jeweiligen Geräteinstanz gespeichert, beispielswiese <code>$hash->{NAME}</code> für den Gerätenamen, welcher beim Define-Befehl übergeben wurde und als Internal gespeichert wird. Diese Daten spielen für FHEM eine sehr wichtige Rolle, da sämtliche gerätespezifischen Daten als Internal im Gerätehash gespeichert werden.

Falls Werte wie z.B. ein Intervall nicht über den Define-Befehl gesetzt werden sollen und im Betrieb einfach änderbar sein sollten, ist eine alternative Möglichkeit die Speicherung in so genannten Attributen. Dann würde man den Define-Befehl so implementieren, dass er kein Intervall übergeben bekommt und statt dessen das Interval als Attribut über den Befehl <code>attr</code> gesetzt wird.

Generell werden alle Werte, welche direkt in der ersten Ebene von <code>$hash</code> (Gerätehash) gespeichert werden auf der Detail-Seite einer Definition in der FHEMWEB Oberfläche angezeigt. Es gibt jedoch Ausnahmen:

* <code>$hash->{helper}{URL]</code> - Alle Elemente, welche als Unterelement wieder einen Hash besitzen werden nicht in FHEMWEB dargestellt. Typischerweise speichern Module Daten unter <code>$hash->{helper}</code> interne Daten zwischen, die für den User nicht relevant sind, sondern nur der internen Verarbeitung dienen.
* <code>$hash->{'''.'''<font color="grey">ELEMENT</font>}</code> - Alle Knoten, welche mit einem Punkt beginnen werden in der FHEMWEB Oberfläche nicht angezeigt. Man kann diese Daten jedoch beim Aufruf des [[List|list-Kommandos]] einsehen.

Es gibt bereits vorbelegte Internals welche in FHEM dazu dienen definitionsbezogene Informationen wie bspw. Namen und Readings zu speichern. Dies sind im besonderen:

{| class="wikitable"
|-
! style="min-width: 13em;" | Internal !! Beschreibung
|-
| <code>$hash->{NAME}</code> || Der Definitionsname, mit dem das Gerät angelegt wurde.
|-
| <code>$hash->{READINGS}</code> || Enthält alle aktuell vorhandenen Readings. Daten unterhalb dieses Knotens sollte man nicht direkt manipulieren. Um Readings zu Erzeugen gibt es entsprechende [[DevelopmentModuleAPI#Readings_.2F_Events|Reading-Funktionen]].
|-
| <code>$hash->{NR}</code> || Die Positions-Nr. der Definition innerhalb der Konfiguration. Diese dient dazu die Konfiguration in der gleichen Reihenfolge zu speichern, wie die einzelnen Geräte angelegt wurden.
|-
| <code>$hash->{TYPE}</code> || Der Modulname, mit welchem die Definition angelegt wurde.
|-
| <code>$hash->{DEF}</code> || Sämtliche Argumente, welche beim <code>define</code>-Befehl nach dem Modulnamen übergeben wurden.
|-
| <code>$hash->{CFGFN}</code> || Der Dateiname der Konfigurationsdatei in der diese Definition enthalten ist (sofern nicht in fhem.cfg). Dieser Wert ist nur gefüllt, wenn man mit mehreren Konfigurationsdateien arbeitet, welche dann in fhem.cfg via include-Befehl eingebunden werden.
|-
| <code>$hash->{NTFY_ORDER}</code> || Sofern das Modul Events via [[DevelopmentModuleIntro#X_Notify|Notify-Funktion]] verarbeitet enthält jede Definition eine Notify-Order als Zeichenkette bestehend aus dem Notify Order Prefix und dem Definitionsnamen. Details zur Funktionsweise gibt es in der Beschreibung zur [[DevelopmentModuleIntro#X_Notify|Notify-Funktion]] im Abschnitt "Reihenfolge für den Aufruf der Notify-Funktion beeinflussen".
|-
| <code>$hash->{NOTIFYDEV}</code> || Sofern das Modul Events via NotifyFn verarbeitet kann man damit die Definitionen, von denen man Events erhalten will begrenzen. Details zur Funktionsweise gibt es in der Beschreibung zur [[DevelopmentModuleIntro#X_Notify|Notify-Funktion]] im Abschnitt "Begrenzung der Aufrufe auf bestimmte Geräte".
|-
| <code>$hash->{IODev}</code> || Hier wird das zugeordnete IO-Gerät durch [[DevelopmentModuleAPI#AssignIoPort|AssignIoPort()]] gespeichert, welches für den Datentransport und -empfang dieses logischen Gerätes zuständig ist. Dieser Wert existiert nur bei Modulen die nach dem [[DevelopmentModuleIntro#Zweistufiges_Modell_f.C3.BCr_Module|zweistufigen Modulkonzept]] arbeiten.
|-
| <code>$hash->{CHANGED}</code> || Hier werden alle Events kurzzeitig gesammelt, welche für die Eventverarbeitung anstehen. Insbesondere die [[DevelopmentModuleAPI#Readings_.2F_Events|Reading-Funktionen]] speichern hier alle Events zwischen um sie nach Abschluss via [[DevelopmentModuleAPI#DoTrigger|DoTrigger()]] zu verarbeiten.
|-
| <code>$hash->{FD}</code> || Wenn die Definition eine Netzwerkverbindung oder serielle Schnittstelle geöffnet hat (z.B. via DevIo), so wird der entsprechende File-Deskriptor in diesem Internal gespeichert. Damit kann FHEM alle geöffneten Filedeskriptoren der entsprechenden Definition zuordnen um bei ankommenden Daten die Definition via [[DevelopmentModuleIntro#X_Read|Read-Funktion]] damit zu versorgen.
|-
| <code>$hash->{EXCEPT_FD}</code> || Ähnlich wie <code>$hash->{FD}</code>. Sofern die Definition in <code>[[#Wichtige_globale_Variablen_aus_fhem.pl|%selectlist]]</code> eingetragen ist und ein Fildeskriptor in diesem Internal gesetzt ist, wird bei einer auftretenden Exception bzw. Interrupt die [[DevelopmentModuleIntro#X_Except|Except]]-Funktion des entsprechenden Moduls aufgerufen um darauf zu reagieren.
|}

Generell sollte man die meisten der hier genannten systemweiten Internals nicht modifizieren, da ansonsten die korrekte Funktionsweise von FHEM nicht mehr garantiert werden kann.

== Readings ==
Daten, welche von einem Gerät gelesen werden und in FHEM in einer für Menschen verständlichen Form zur Verfügung gestellt werden können, werden Readings genannt. Sie geben den Status des Gerätes wieder und erzeugen Events innerhalb von FHEM auf die andere Geräte reagieren können. Sie werden als Unterstruktur des Hashes der jeweiligen Geräteinstanz gespeichert, beispielsweise
*<code>$hash->{READINGS}{temperature}{VAL}</code> für die Temperatur eines Fühlers
*<code>$hash->{READINGS}{temperature}{TIME}</code> für den Zeitstempel der Messung

Für den lesenden Zugriff auf Readings steht die Funktion <code>[[DevelopmentModuleAPI#ReadingsVal|ReadingsVal()]]</code> zur Verfügung. Ein direkter Zugriff auf die Datenstruktur sollte nicht vorgenommen werden.

Readings werden im Statefile von FHEM automatisch auf der Festplatte zwischengespeichert, damit sie nach einem Neustart sofort wieder zur Verfügung stehen. Dadurch ist der letzte Status eines Gerätes vor einem Neustart nachvollziehbar.

Readings, die mit einem Punkt im Namen beginnen, haben eine funktionale Besonderheit. Sie werden im FHEMWEB nicht angezeigt und können somit als "Permanentspeicher" für kleinere Daten innerhalb des Moduls genutzt werden. Um größere Datenmengen permanent zu speichern sollte man jedoch die Funktion <code>[[DevelopmentModuleAPI#setKeyValue|setKeyValue()]]</code> verwenden.

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

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

<source lang="perl">
readingsBeginUpdate($hash);
readingsBulkUpdate($hash, $readingName1, $wert1 );
readingsBulkUpdate($hash, $readingName2, $wert2 );
readingsEndUpdate($hash, 1);
</source>

== Attribute ==
Damit der Nutzer das Verhalten einer einzelnen Gerätedefinition zur Laufzeit individuell anpassen kann, gibt es in FHEM für jede Definition sogenannte Attribute, welche mit dem Befehl <code>attr</code> gesetzt werden können.
Diese stehen dann dem Modul unmittelbar zur Verfügung um das Verhalten während der Ausführung zu beeinflussen. Attribute werden zusammen mit dem <code>define</code>-Befehl der jeweiligen Definition beim Speichern der aktuellen Konfiguration von FHEM in die Konfigurationsdatei geschrieben. Beim Neustart werden die entsprechenden Befehle ausgeführt um alle Definition inkl. Attribute wieder anzulegen. Zur Laufzeit werden Attribute in dem globalen Hash <code>%attr</code> mit dem Definitionsnamen als Index (<code>$attr{$name} = $value</code>) gespeichert. Ein Attribut mit dem Namen <code>header</code> würde beispielsweise mit <code>$attr{$name}{header}</code> adressiert. Generell sollte <code>%attr</code> nicht durch direkten Zugriff manipuliert/benutzt werden.

Zum Auslesen von Attributen sollte die Funktion [[DevelopmentModuleAPI#AttrVal|AttrVal()]] verwendet werden.

Welche Attribute ein Modul unterstützt muss in der Funktion <code>[[#X_Initialize|X_Initialize]]</code> durch Setzen von <code>$hash->{AttrList}</code> bekannt gemacht werden (siehe unten).

Wenn beim Setzen von Attributen in einer Gerätedefinition entsprechende Werte geprüft werden sollen oder zusätzliche Funktionalitäten implementiert werden müssen, dann muss dies in der Funktion <code>[[#X_Attr|X_Attr]]</code> (siehe unten) implementiert werden. Hier kann man bspw. einen Syntaxcheck für Attribut-Werte implementieren um ungültige Werte zurückzuweisen.

== Modulfunktionen ==

Damit fhem.pl ein Modul nutzen kann, muss dieses entsprechende Funktionen mit einer vorgegebenen Aufrufsyntax implementieren. Durch die Bekanntgabe dieser modulspezifischen Funktionen können Daten zwischen fhem.pl und einem Modul entsprechend ausgetauscht werden. Es gibt verschiedene Arten von Funktionen die ein Modul anbieten muss bzw. kann, je nach Funktionsumfang.

=== Die wichtigsten Funktionen in einem Modul ===

Folgende Funktion muss ein Modul mit dem beispielhaften Namen "X" mindestens bereitstellen:

{| class="wikitable"
|-
! style="text-align:left" | Funktionsname !! style="text-align:left" | Kurzbeschreibung
|-
| [[#X_Initialize|X_Initialize]] || Initialisiert das Modul und gibt den Namen zusätzlicher Modulfunktionen bekannt, sowie modulspezifische Einstellungen. Wird direkt nach dem erfolgreichen Laden des Moduls durch fhem.pl aufgerufen.
|}

Die folgenden Funktionen sind die wichtigsten Funktionen, welche je nach Anwendungsfall zu implementieren sind. Es handelt sich hierbei um die wichtigsten Vertreter, welche in den meisten Modulen Verwendung finden. Nicht alle Funktionen machen jedoch in jedem Modul Sinn. Generell sollte auch hier bei jeder Funktion der Modulname vorangestellt werden um ein einheitliches Namensschema zu gewährleisten. Hier die wichtigsten Modulfunktionen:

{| class="wikitable sortable"
|-
! style="text-align:left" | Funktionsname !! style="text-align:left" class="unsortable"| Kurzbeschreibung
|-
| [[#X_Define|X_Define]] || Wird im Rahmen des <code>define</code>-Befehls aufgerufen.
|-
| [[#X_Undef|X_Undef]] || Wird im Rahmen des <code>delete</code>-Befehls, sowie <code>rereadcfg</code>-Befehl aufgerufen. Dient zum Abbau von offenen Verbindungen, Timern, etc.
|-
| [[#X_Delete|X_Delete]] || Wird im Rahmen des beim <code>delete</code>-Befehls aufgerufen wenn das Gerät endgültig gelöscht wird um weiterführende Aktionen vor dem Löschen durchzuführen.
|-
| [[#X_Get|X_Get]] || Wird im Rahmen des <code>get</code>-Befehls aufgerufen um Daten vom Gerät abzufragen
|-
| [[#X_Set|X_Set]] || Wird im Rahmen des <code>set</code>-Befehls aufgerufen um Daten an das Gerät zu senden.
|-
| [[#X_Attr|X_Attr]] || Wird im Rahmen des <code>attr</code>-Befehls aufgerufen um Attributwerte zu prüfen)
|-
| [[#X_Read|X_Read]] || Wird durch FHEM aufgerufen, wenn ein gelisteter Filedeskriptor in <code>[[#Wichtige_globale_Variablen_aus_fhem.pl|%selectlist]]</code> Daten zum Lesen bereitstellt.
|-
| [[#X_Ready|X_Ready]] || Wird unter Windows durch FHEM aufgerufen um zyklisch einen seriellen Filedeskriptor auf lesbare Daten zu prüfen. Unter Linux dient diese Funktion dem Wiederaufbau verlorener Verbindungen.
|-
| [[#X_Notify|X_Notify]] || Verarbeitet Events von anderen Geräten innerhalb von FHEM
|-
| [[#X_Rename|X_Rename]] || Wird aufgerufen, wenn ein Gerät umbenannt wird.
|-
| [[#X_Shutdown|X_Shutdown]] || Wird beim Herunterfahren von FHEM ausgeführt.
|}

Diese Funktionen werden in diesem Abschnitt genauer beschrieben.

==== X_Initialize ====

<source lang="perl">
sub X_Initialize($)
{
my ($hash) = @_;
...
}
</source>

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

Dieser Hash muss nun von X_Initialize mit allen modulrelevanten Funktionsnamen gefüllt werden. Anschließend wird dieser Hash durch fhem.pl im globalen Hash <code>%modules</code> gespeichert. <code>$modules{ModulName}</code> wäre dabei der Hash für das Modul mit dem Namen <code>ModulName</code>. Es handelt sich also nicht um den oben beschriebenen Hash der Geräteinstanzen sondern einen Hash, der für jedes Modul existiert und modulspezifische Daten wie bspw. die implementierten Modulfunktionen enthält. Die Initialize-Funktion setzt diese Funktionsnamen, in den Hash des Moduls wie folgt:

<source lang="perl">
$hash->{DefFn} = "X_Define";
$hash->{UndefFn} = "X_Undef";
$hash->{DeleteFn} = "X_Delete";
$hash->{SetFn} = "X_Set";
$hash->{GetFn} = "X_Get";
$hash->{AttrFn} = "X_Attr";
$hash->{ReadFn} = "X_Read";
$hash->{ReadyFn} = "X_Ready";
$hash->{NotifyFn} = "X_Notify";
$hash->{RenameFn} = "X_Rename";
$hash->{ShutdownFn} = "X_Shutdown";
</source>

Um eine entsprechende Funktion in FHEM bekannt zu machen muss dazu der Funktionsname, wie er im Modul als <code>sub <''Funktionsname''>() { ... }</code> definiert ist, als Zeichenkette in <code>$hash</code> gesetzt werden. Dabei sollten die entsprechenden Funktionsnamen immer den Modulnamen (in diesem Beispiel <code>X</code>) als Präfix verwenden.
Auf diese Weise können sämtliche modulspezifisch implementierten Funktionen wie <code>X_Read</code>, <code>X_Parse</code> etc. durch Zuweisung an <code>$hash->{ReadFn}</code> bzw. <code>$hash->{ParseFn}</code> usw. bekannt gemacht werden.

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

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

Die Auflistung aller unterstützten modulspezifischen Attribute erfolgt in Form einer durch Leerzeichen getrennten Liste in <code>$hash->{AttrList}}</code>. Es gibt in FHEM globale Attribute, die in allen Gerätedefinitionen verfügbar sind und nur modulspezifische Attribute die jedes Modul via <code>$hash->{AttrList}</code> über die eigene Initialize-Funktion setzt. In fhem.pl werden dann die entsprechenden Attributwerte beim Aufruf eines <code>attr</code>-Befehls in die globale Datenstruktur <code>$attr{$name}</code>, z.B. <code>$attr{$name}{header}</code> für das Attribut <code>header</code> gespeichert. Falls im Modul weitere Aktionen oder Prüfungen beim Setzen eines Attributs nötig sind, dann kann wie im Beispiel oben die [[#X_Attr|Attr]]-Funktion implementiert und in der Initialize-Funktion bekannt gemacht werden.

Die Variable <code>$readingFnAttributes</code>, die im obigen Beispiel an die Liste der unterstützten Attribute angefügt wird, definiert Attributnamen, die dann zusätzlich gemacht werden, wenn das Modul zum Setzen von Readings die Funktionen <code>[[DevelopmentModuleAPI#readingsBeginUpdate|readingsBeginUpdate()]]</code>, <code>[[DevelopmentModuleAPI#readingsBulkUpdate|readingsBulkUpdate()]]</code>, <code>[[DevelopmentModuleAPI#readingsEndUpdate|readingsEndUpdate()]]</code> oder <code>[[DevelopmentModuleAPI#readingsSingleUpdate|readingsSingleUpdate()]]</code> verwendet. In diesen Funktionen werden Attribute wie <code>event-min-interval</code> oder auch <code>event-on-change-reading</code> ausgewertet. Für Details hierzu siehe commandref zu [http://fhem.de/commandref.html#readingFnAttributes readingFnAttributes].

<u>Nutzung von parseParams()</u>

Die Funktion <code> [[DevelopmentModuleAPI#parseParams|parseParams()]]</code> unterstützt Modulautoren beim Parsen von Übergabeparametern, welche bei <code>define</code>, <code>get</code> und <code>set</code> Kommandos an die entsprechenden Modulfunktionen übergeben werden. Dadurch lassen sich auf einfache Weise insbesondere komplexe Parameter (wie bspw. Perl-Ausdrücke) sehr einfach parsen.

Diese Zusatzfunktion kann man in der Initialize-Funktion einfach über folgenden Parameter für [[#X_Define|Define]]-, [[#X_Get|Get]]- und [[#X_Set|Set]]-Funktion modulweit aktivieren:
<source lang="perl">$hash->{parseParams} = 1;</source>
Sobald es gesetzt ist wird automatisch durch fhem.pl <code>[[DevelopmentModuleAPI#parseParams|parseParams()]]</code> aufgerufen und die an die [[#X_Define|Define]]-, [[#X_Get|Get]]- und [[#X_Set|Set]]-Funktion übergebenen Parameter ändern sich wie weiter unten in den jeweiligen Funktionen beschrieben.

==== X_Define ====
<source lang="perl">
sub X_Define($$)
{
my ( $hash, $def ) = @_;

...

return $error;
}
</source>

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

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

Als Übergabeparameter bekommt die Define-Funktion den Hash der Geräteinstanz sowie den die im <code>define</code>-Befehl übergebenen Parameter. Welche bzw. wie viele Parameter
akzeptiert werden und welcher Syntax diese entsprechen müssen ist Sache dieser Funktion. Im obigen Beispiel wird die Argumentzeile <code>$def</code> in ein Array aufgeteilt (durch Leerzeichen/Tabulator getrennt) und so können die vom Modul bzw. der Define-Funktion erwarteten Werte über das Array der Reihe nach verarbeitet werden:

<source lang="perl">
my $name = $a[0];
my $module = $a[1];
my $url = $a[2];
my $inter = 300;

if(int(@a) == 4) {
$inter = $a[3];
if ($inter < 5) {
return "interval too small, please use something > 5s, default is 300 seconds";
}
}
</source>

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

<source lang="perl">
$hash->{url} = $url;
$hash->{Interval} = $inter;
</source>

Sobald alle Parameter korrekt verarbeitet wurden, wird in der Regel die erste Verbindung zum Gerät aufgebaut. Je nach Art des Geräts kann das eine permanente Datenverbindung sein (z.B. serielle Schnittstelle oder TCP-Verbindung) oder das Starten eines regelmäßigen Timers, der zyklisch den Status z.B. via [[HttpUtils|HTTP]] ausliest.

Sollten im Rahmen der Define-Funktion Syntax-Probleme der Übergabeparameter festgestellt werden oder es kann bspw. keine Verbindung aufgebaut werden, so ist als Funktionsrückgabewert eine entsprechende Fehlermeldung zurückzugeben. Nur wenn alle Übergabeparameter akzeptiert werden, darf <code>undef</code> zurückgegeben werden. Sobald eine Define-Funktion eine Fehlermeldung zurückmeldet, wird der define-Befehl durch FHEM zurückgewiesen und der User erhält die Fehlermeldung, welche die Define-Funktion produziert hat, als Ausgabe zurück.

<u>Verfügbarkeit von Attributen</u>

Während die Define-Funktion ausgeführt wird, sollte man nicht davon ausgehen, dass alle vom Nutzer konfigurierten Attribute via [[DevelopmentModuleAPI#AttrVal|AttrVal()]] verfügbar sind. Attribute stehen in der Define-Funktion nur dann zur Verfügung, wenn FHEM sich nicht in der Initialisierungsphase befindet (globale Variable <code>$init_done</code> ist wahr; der Nutzer hat die Gerätedefinition modifiziert). Daher sollte man weiterführende Funktion, welche auf gesetzte Attribute angewiesen sind, nur dann in der Define-Funktion starten, wenn <code>$init_done</code> zutrifft.

Andernfalls sollte man den Aufruf in der Notify-Funktion durchführen sobald <code>global:INITIALIZED</code> bzw. <code>global:REREADCFG</code> getriggert wurde:

<source lang="perl">
sub X_Define($$)
{
my ( $hash, $def ) = @_;

...

$hash->{NOTIFYDEV} = "global";

X_FunctionWhoNeedsAttr($hash) if($init_done);
}

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

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

my $devName = $dev_hash->{NAME}; # Device that created the events
my $events = deviceEvents($dev_hash, 1);

if($devName eq "global" && grep(m/^INITIALIZED|REREADCFG$/, @{$events}))
{
X_FunctionWhoNeedsAttr($hash);
}
}
</source>

Dadurch wird die Modulfunktion X_FunctionWhoNeedsAttr() nach dem Start erst aufgerufen, wenn alle Attribute aus der Konfiguration geladen wurden.

<u>Nutzung von parseParams()</u>

Zum Aufteilen und Parsen von <code>$def</code> lässt sich die Funktion [[DevelopmentModuleAPI#parseParams|parseParams]] verwenden um die einzelnen Argumente einfach zu parsen. Wenn in X_Initialize <code>$hash->{parseParams} = 1;</code> gesetzt wurde dann wird parseParams automatisch aufgerufen und X_Define ändert sich wie folgt:
<source lang="perl">
sub X_Define($$$)
{
my ( $hash, $a, $h ) = @_;
...
</source>

Die genauen Möglichkeiten von parseParams sind in dem entsprechenden [[DevelopmentModuleAPI#parseParams|Artikel]] dokumentiert.

<u>Nutzung von DevIo</u>

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

Um DevIo mitzuteilen welche Verbindung genau zu öffnen ist, muss das Internal <code>$hash->{DeviceName} mit einer entsprechenden Syntax gefüllt sein (z.B. <code>"/dev/ttyUSB0@9600"</code>, <code>"192.168.2.105:3000"</code>, ...). Üblicherweise wird diese Information als Argument im <code>define</code>-Befehl vom Nutzer angegeben.

<source lang="perl">
my $ret = DevIo_OpenDev( $hash, 0, "X_DeviceInit" );
</source>

Die optionale Funktion <code>X_DevInit</code> wird zur weiteren Initialisierung der Verbindung von <code>DevIo_OpenDev</code> aufgerufen. Der zweite Übergabeparameter an <code>DevIo_OpenDev</code> (hier <code>0</code>) steht für reopen und wird benötigt, da die Funktion auch aufgerufen wird, wenn ein USB-Geräte beispielsweise im Betrieb aus- und wieder eingesteckt wird. In diesem Fall wird die Funktion mit <code>1</code> aufgerufen. Dies ist jedoch nur in der [[#X_Ready|X_Ready]]-Funktion notwendig. In der Define-Funktion wird immer <code>0</code> (erster Verbindungsversuch) angegen

==== X_Undef ====
<source lang="perl">
sub X_Undef ($$)
{
my ( $hash, $name ) = @_;

...

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

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

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

Sollten im Rahmen der Undef-Funktion Probleme festgestellt werden, die ein Löschen nicht zulassen, so ist als Funktionsrückgabewert eine entsprechende Fehlermeldung zurückzugeben. Nur wenn die Undef-Funktion erfolgreich durchgeführt wurde, darf <code>undef</code> zurückgegeben werden. Nur dann wird eine Gerätedefinition von FHEM auch tatsächlich gelöscht bzw. neu angelegt. Sollte die Undef-Funktion jedoch eine Fehlermeldung zurückgeben, wird der entsprechende Vorgang (<code>delete</code> bzw. <code>rereadcfg</code>) für dieses Gerät abgebrochen. Es bleibt dann unverändert in FHEM bestehen.

==== X_Delete ====
<source lang="perl">
sub X_Delete ($$)
{
my ( $hash, $name ) = @_;

...

return $error;
}
</source>

Die Delete-Funktion ist das Gegenstück zur Funktion [[#X_Define|X_Define]] und wird aufgerufen wenn ein Gerät mit dem Befehl <code>delete</code> gelöscht wird.

Wenn ein Gerät in FHEM gelöscht wird, wird zuerst die Funktion [[#X_Undef|X_Undef]] aufgerufen um offene Verbindungen zu schließen, anschließend wird die Funktion X_Delete aufgerufen. Diese dient eher zum Aufräumen von dauerhaften Daten, welche durch das Modul evtl. für dieses Gerät spezifisch erstellt worden sind. Es geht hier also eher darum, alle Spuren sowohl im laufenden FHEM-Prozess, als auch dauerhafte Daten bspw. im physikalischen Gerät zu löschen die mit dieser Gerätedefinition zu tun haben.

Dies kann z.B. folgendes sein:

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

Beispiel:
<source lang="perl">
sub X_Delete($$)
{
my ( $hash, $name ) = @_;

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

return undef;
}
</source>

Sollten im Rahmen der Delete-Funktion Probleme festgestellt werden, die ein Löschen nicht zulassen, so ist als Funktionsrückgabewert eine entsprechende Fehlermeldung zurückzugeben. Nur die Delete-Funktion erfolgreich durchgeführt wurde, darf <code>undef</code> zurückgegeben werden. Nur dann wird eine Gerätedefinition von FHEM auch tatsächlich gelöscht. Sollte die Delete-Funktion eine Fehlermeldung zurückgeben, wird der Löschvorgang abgebrochen und das Gerät bleibt weiter in FHEM bestehen.

==== X_Get ====
<source lang="perl">
sub X_Get ($$@)
{
my ( $hash, $name, $opt, @args ) = @_;

...

return $result;
}
</source>
Die Get-Funktion wird aufgerufen wenn der FHEM-Befehl <code>get</code> mit einem Gerät dieses Moduls ausgeführt wird. Mit <code>get</code> werden typischerweise Werte von einem Gerät abgefragt. In vielen Modulen wird auf diese Weise auch der Zugriff auf generierte Readings ermöglicht. Der Get-Funktion wird dabei der Geräte-Hash, der Gerätename, sowie die Aufrufparameter des get-Befehls übergeben. Als Rückgabewert wird das Ergebnis des entsprechenden Befehls in Form einer Zeichenkette zurückgegeben. Der Rückgabewert <code>undef</code> hat hierbei keine besondere Bedeutung und wird behandelt wie eine leere Zeichenkette <code>""</code>.

Beispiel:

<source lang="perl">
sub X_Get($$@)
{
my ( $hash, $name, $opt, @args ) = @_;

return "\"get $name\" needs at least one argument" unless(defined($opt)));

if($opt eq "status")
{
...
}
elsif($opt eq "powser")
{
...
}
...
else
{
return "Unknown argument $opt, choose one of status power [...]";
}
}
</source>

Wenn eine unbekannte Option an die Get-Funktion übergeben wird, so muss als Rückgabewert der Funktion eine bestimmte Syntax einhalten um FHEM mitzuteilen, welche Optionen für einen Get-Befehl aktuell unterstützt werden. Die Rückgabe muss dabei folgender Syntax entsprechen:

<code>'''unknown''' argument ''<font color="grey">[Parameter]</font>'' '''choose one of''' ''<font color="grey">[Liste möglicher Optionen]</font>''</code>

Hierbei sind die fett gedruckten Teile der Rückmeldung besonders wichtig. Sind diese nicht vorhanden, kann FHEM nicht die möglichen Get-Kommandos für das entsprechende Gerät ermitteln. Es muss am Anfang der Meldung das Stichwort "unknown" vorkommen gefolgt von einer frei definierbaren Fehlermeldung (i.d.R der übergebene Parameter, welcher ungültig ist). Anschließend folgt "choose one of" mit einer anschließenden Liste möglicher Optionen getrennt durch ein Leerzeichen.

Beispiel:
<ul>
<source lang="perl">return "unknown argument $opt choose one of state temperature humidity";</source>

Hier werden als mögliche Optionen für einen Get-Befehl folgende Parameter angegeben:

* <code>state</code>
* <code>temperature</code>
* <code>humidity</code>

Dies würde in folgenden, mögliche Get-Befehle für einen User resultieren:

* <code>get ''<NAME>'' state</code>
* <code>get ''<NAME>'' temperature</code>
* <code>get ''<NAME>'' humidity</code>
</ul>

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

<u>Nutzung von parseParams()</u>

Wenn in [[#X_Initialize|X_Initialize]] <code>$hash->{parseParams} = 1;</code> gesetzt wurde dann wird [[DevelopmentModuleAPI#parseParams|parseParams]] automatisch aufgerufen und X_Get ändert sich wie folgt:
<source lang="perl">
sub X_Get($$$)
{
my ( $hash, $a, $h ) = @_;
...
</source>

Die genauen Möglichkeiten von parseParams sind in dem entsprechenden [[DevelopmentModuleAPI#parseParams|Artikel]] dokumentiert.

==== X_Set ====
<source lang="perl">
sub X_Set ($$@)
{
my ( $hash, $name, $cmd, @args ) = @_;

...

return $error;
}
</source>

Die Set-Funktion ist das Gegenteil zur [[#X_Get|Get]]-Funktion. Sie ist dafür gedacht, Daten zum physischen Gerät zu schicken, bzw. entsprechende Aktionen im Gerät selber auszulösen. Ein Set-Befehl dient daher der direkten Steuerung des physikalischen Gerätes in dem es bspw. Zustände verändert (wie <code>on</code>/<code>off</code>). Der Set-Funktion wird dabei der Geräte-Hash, der Gerätename, sowie die Aufrufparameter des set-Befehls übergeben. Als Rückgabewert kann eine Fehlermeldung in Form Zeichenkette zurückgegeben werden. Der Rückgabewert <code>undef</code> bedeutet hierbei, dass der Set-Befehl erfolgreich durchgeführt wurde. Eine Set-Funktion gibt daher nur im Fehlerfall eine Rückmeldung mit einer entsprechenden Fehlermeldung. Der Wert <code>undef</code> wird als "erfolgreich" interpretiert. Rückmeldungen von set-Befehlen sämtlicher Module, die im Rahmen eines ausgeführten [[Notify]] auftreten werden im FHEM Logfile festgehalten.

Falls nur interne Daten, die ausschließlich für das Modul relevant sind, gesetzt werden müssen, so sollte statt Set die [[#X_Attr|Attr]]-Funktion verwendet werden. Attribute werden bei Save-Config auch in der Fhem.cfg gesichert. Set-Befehle nicht, da sie nur zur Steuerungszwecken im laufenden Betrieb von FHEM dienen.

Eine Set-Funktion ist ähnlich aufgebaut wie die Get-Funktion, sie bekommt jedoch in der Regel weitere zusätzliche Parameter übergeben um Zustände zu setzen.

Beispiel:
<source lang="perl">
sub X_Set($@)
{
my ( $hash, $name, $cmd, @args ) = @_;

return "\"set $name\" needs at least one argument" unless(defined($cmd)));

if($cmd eq "status")
{
if($args[0] eq "up")
{
...
}
elsif($args[0] eq "down")
{
...
}
else
{
return "Unknown value $args[0] for $cmd, choose one of status power";
}
}
elsif($cmd eq "power")
{
if($args[0] eq "on")
{
...
}
elsif($args[0] eq "off")
{
...
}
else
{
return "Unknown value $args[0] for $cmd, choose one of status power";
}
}
...
else
{
return "Unknown argument $cmd, choose one of status power";
}
}
</source>

Wenn eine unbekannte Option an die Set-Funktion übergeben wird, so muss als Rückgabewert der Funktion eine bestimmte Syntax eingehalten werden um FHEM mitzuteilen, welche Optionen für einen Set-Befehl aktuell unterstützt werden. Die Rückgabe muss dabei folgender Syntax entsprechen:

<code>'''unknown''' argument ''<font color="grey">[Parameter]</font>'' '''choose one of''' ''<font color="grey">[Liste möglicher Optionen]</font>''</code>

Hierbei sind die fett gedruckten Teile der Rückmeldung besonders wichtig. Sind diese nicht vorhanden, kann FHEM nicht die möglichen Set-Kommandos für das entsprechende Gerät ermitteln. Es muss am Anfang der Meldung das Stichwort "unknown" vorkommen gefolgt von einer frei definierbaren Fehlermeldung (i.d.R der übergebene Parameter, welcher ungültig ist). Anschließend folgt "choose one of" mit einer anschließenden Liste möglicher Optionen getrennt durch ein Leerzeichen.

Beispiel:
<ul>
<source lang="perl">return "unknown argument $cmd choose one of state power";</source>

Hier werden als mögliche Optionen für einen Get-Befehl folgende Parameter angegeben:

* <code>state</code>
* <code>power</code>

Dies würde in folgenden, mögliche Get-Befehle für einen User resultieren:

* <code>get ''<NAME>'' state</code>
* <code>get ''<NAME>'' power</code>
</ul>

Die Ausgabe einer solchen Meldung ist sehr wichtig, da sie im GUI-Modul verwendet wird um die möglichen <code>set</code>-Optionen zu ermitteln und als Auswahl anzubieten

<u>Nutzung von SetExtensions.pm</u>

Wenn man dem Nutzer zusätzlich zu den Set-Befehlen <code>on</code> und <code>off</code> auch weiterführende Befehle wie <code>on-for-timer</code>, <code>on-till</code>, usw. anbieten möchte, obwohl die zu steuernde Hardware solche Kommandos nicht unterstützt, kann man dies über das Hilfsmodul SetExtensions.pm realisieren.

Das Hilfsmodul SetExtensions.pm bietet weiterführende Set-Kommandos basierend auf den Befehlen <code>on</code>/<code>off</code> an. Dabei werden durch interne Timer bzw. eigens angelegten [[at]]-Definitionen diese Befehle durch FHEM selber umgesetzt. Je nach ausgeführtem Befehl wird der <code>on</code>- bzw. <code>off</code>-Befehl dann durch FHEM zum richtigen Zeitpunkt ausgeführt. Vorausgesetzt das Modul unterstützt in der Set-Funktion die Befehle <code>on</code> und <code>off</code>, so werden durch den Einsatz von SetExtensions.pm folgende Befehle zusätzlich unterstützt:

{| class="wikitable"
|-
! Set-Kommando !! Beispiel !! Beschreibung
|-
| style="white-space: nowrap;" | <code>on-for-timer ''<Dauer>''</code> || style="white-space: nowrap;" | <code>on-for-timer 120</code> || Schaltet das Gerät sofort mit dem <code>on</code>-Befehl ein und nach der angegebenen Dauer in Sekunden via <code>off</code> wieder aus.
|-
| style="white-space: nowrap;" | <code>off-for-timer ''<Dauer>''</code> || style="white-space: nowrap;" | <code>off-for-timer 120</code> || Schaltet das Gerät sofort mit dem <code>off</code>-Befehl aus und nach der angegebenen Dauer in Sekunden via <code>on</code> wieder ein.
|-
| style="white-space: nowrap;" | <code>on-till ''<Zeitpunkt>''</code> || style="white-space: nowrap;" | <code>on-till 16:30</code> || Schaltet das Gerät sofort mit dem <code>on</code>-Befehl ein und zum angegebenen Zeitpunkt via <code>off</code> wieder aus.
|-
| style="white-space: nowrap;" | <code>off-till ''<Zeitpunkt>''</code> || style="white-space: nowrap;" | <code>off-till 16:30</code> || Schaltet das Gerät sofort mit dem <code>off</code>-Befehl aus und zum angegebenen Zeitpunkt via <code>on</code> wieder ein.
|-
| style="white-space: nowrap;" | <code>on-till-overnight ''<Zeitpunkt>''</code> || style="white-space: nowrap;" | <code>on-till-overnight 01:00</code> || Ähnlich wie <code>on-till</code>. Der übergebene Zeitpunkt wird aber nicht geprüft, ob er für den heutigen Tag bereits überschritten wurde. Dadurch kann man Abends einen Zeitpunkt setzen, der erst am nächsten Tag zutrifft.
|-
| style="white-space: nowrap;" | <code>off-till-overnight ''<Zeitpunkt>''</code> || style="white-space: nowrap;" | <code>off-till-overnight 01:00</code> || Ähnlich wie <code>off-till</code>. Der übergebene Zeitpunkt wird aber nicht geprüft, ob er für den heutigen Tag bereits überschritten wurde. Dadurch kann man Abends einen Zeitpunkt setzen, der erst am nächsten Tag zutrifft.
|-
| style="white-space: nowrap;" | <code>blink ''<Anzahl> <Interval>''</code> || style="white-space: nowrap;" | <code>blink 3 1</code> || Schaltet das Gerät via <code>on</code> für <code>''<Interval>''</code> Sekunden ein und anschließend via <code>off</code> wieder aus. Nach <code>''<Interval>''</code> Sekunden wird das ganze wiederholt, solange bis die angegebene Anzahl erreicht ist.
|-
| style="white-space: nowrap;" | <code>intervals ''<Start>-<Ende>'' ''<Start>-<Ende>'' ...</code> || style="white-space: nowrap;" | <code>intervals 07:00-08:00 16:30-18:00</code> || Schaltet das Gerät innerhalb der übergebenen Zeiträumen via <code>on</code> ein. Sobald die aktuelle Zeit ausserhalb dieser Zeiträume liegt, wird das Gerät via <code>off</code> wieder ausgeschaltet. Es können dabei beliebig viele Zeiträume angegeben werden.
|-
| style="white-space: nowrap;" | <code>toggle</code> || style="white-space: nowrap;" | <code>toggle</code> || Sofern der aktuelle Status <code>on</code> ist, wird das Gerät via <code>off</code> ausgeschaltet. Andernfalls wird es via <code>on</code> eingeschaltet.
|}

Eine kurze Beschreibung zu den möglichen Befehlen durch SetExtensions.pm gibt es auch in der Commandref zum [http://fhem.de/commandref.html#set Set-Befehl].

Um SetExtensions.pm in der Set-Funktion nutzen zu können müssen folgende Aktionen durchgeführt werden:

# Laden von SetExtensions.pm via <code>use SetExtensions;</code> am Anfang des Moduls
# Aufruf und Rückgabe der Funktion [[DevelopmentModuleAPI#SetExtensions|SetExtensions()]] sofern die Set-Funktion mit dem übergebenen Befehl nichts anfangen kann.

Beispiel:

<source lang="perl">
use SetExtensions;

...

sub X_Set($@)
{
my ( $hash, $name, $cmd, @args ) = @_;
my $cmdList = "on off";

return "\"set $name\" needs at least one argument" unless(defined($cmd)));

if($cmd eq "on")
{
# Gerät einschalten...
}
elsif($cmd eq "off")
{
# Gerät ausschalten...
}
...
else # wenn der übergebene Befehl nicht durch X_Set() verarbeitet werden kann, Weitergabe an SetExtensions()
{
return SetExtensions($hash, $cmdList, $name, $cmd, @args);
}
}
</source>

Sollte der übergebene Set-Befehl auch für SetExtensions unbekannt sein (bspw. <code>set ''<Name>'' ?</code>), so generiert SetExtensions() eine entsprechende Usage-Meldung, welche innerhalb der Set-Funktion an FHEM zurückgegeben werden muss.

Eine ausführliche Beschreibung zu der Funktion SetExtensions() gibt es in der [[DevelopmentModuleAPI#SetExtensions|API-Referenz]].

<u>Nutzung von parseParams()</u>

Wenn in [[#X_Initialize|X_Initialize]] <code>$hash->{parseParams} = 1;</code> gesetzt wurde dann wird [[DevelopmentModuleAPI#parseParams|parseParams]] automatisch aufgerufen und X_Set ändert sich wie folgt:
<source lang="perl">
sub X_Set($$$)
{
my ( $hash, $a, $h ) = @_;
...
</source>

Die genauen Möglichkeiten von parseParams sind in dem entsprechenden [[DevelopmentModuleAPI#parseParams|Artikel]] dokumentiert.

<u>Nutzung von FHEMWEB-Widgets</u>

Das GUI-Modul [[FHEMWEB]] kann für die einzelnen Set-Optionen, die das Modul versteht, automatisch Eingabehilfen wie Drop-Down Boxen oder Slider erzeugen. In der Detailansicht der GUI kann der Anwender dann die jeweiligen Werte komfortabel auswählen. Dafür muss die Set-Funktion, wenn sie mit der Option <code>?</code> aufgerufen wird, nicht nur einen Text mit <code>"Unknown ... choose one of ..."</code> zurückgeben sondern den einzelnen Set-Optionen in diesem Rückgabetext nach einem Doppelpunkt entsprechende Zusatzinformationen anhängen.
Meist prüft man in den Modulen gar nicht auf die Option <code>?</code> sondern gibt generell bei unbekannten Optionen diesen Text zurück. Das Modul FHEMWEB ermittelt die Syntax eines Gerätes jedoch immer mit dem Befehl:
set ''<NAME>'' ?

Beispiel:
<source lang="perl">
return "Unknown argument $cmd, choose one of state:up,down power:on,off on:noArg off:noArg";
</source>

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

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

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

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

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

'''Hinweise'''

* Damit in einer Eingabe bereits der aktuelle Wert vorbelegt bzw. in einer Auswahlliste der aktuelle Wert vorselektiert ist, muss es im Modul bzw. Gerät ein Reading mit dem gleichen Namen wie die Set-Option geben. Der Wert des gleichnamigen Readings wird dann als Vorbelegung / Vorselektion verwendet.
* Der User kann sich in der Raumübersicht nach wie vor via [[WebCmd|webCmd]] eine entsprechende Steuerung anlegen.

==== X_Attr ====
<source lang="perl">
sub X_Attr ($$$$)
{
my ( $cmd, $name, $attrName, $attrValue ) = @_;

...

return $error;
}
</source>

Die Attr-Funktion dient der Prüfung von Attributen, welche über den <code>attr</code>-Befehl gesetzt werden können. Sobald versucht wird, ein Attribut für ein Gerät zu setzen, wird vorher die Attr-Funktion des entsprechenden Moduls aufgerufen um zu prüfen, ob das Attribut aus Sicht des Moduls korrekt ist.
Liegt ein Problem mit dem Attribut bzw. dem Wert vor, so muss die Funktion eine aussagekräftige Fehlermeldung zurückgeben, welche dem User angezeigt wird.
Sofern das übergebene Attribut samt Inhalt korrekt ist, gibt die Attr-Funktion den Wert <code>undef</code> zurück. Erst dann wird das Attribut in der globalen Datenstruktur <code>%attr</code> gespeichert und ist somit erst aktiv.

Beispiel:

<source lang="perl">
X_Attr(@)
{
my ( $cmd, $name, $attrName, $attrValue ) = @_;

# $cmd - Vorgangsart - kann die Werte "del" (löschen) oder "set" (setzen) annehmen
# $name - Gerätename
# $attrName/$attrValue sind Attribut-Name und Attribut-Wert

if ($cmd eq "set") {
if ($aName eq "Regex") {
eval { qr/$aVal/ };
if ($@) {
Log3 $name, 3, "X ($name) - Invalid regex in attr $name $aName $aVal: $@";
return "Invalid Regex $aVal: $@";
}
}
}
return undef;
}
</source>

Zusätzlich ist es möglich auch übergebene Attributwerte zu verändern bzw. zu korrigieren, indem man im Parameterarray <code>@_</code> den ursprünglichen Wert anpasst. Dies erfolgt im Beispiel über die Modifikation des Wertes mit Index 3 (entspricht dem 4. Element) im Parameterarray, also <code>$_[3]</code>.

Da das Attribut zum Zeitpunkt des Aufrufs der Attr-Funktion noch nicht gespeichert ist, wird der neue Wert zu diesem Zeitpunkt noch nicht via [[DevelopmentModuleAPI#AttrVal|AttrVal()]] zurückgegeben. Erst, wenn die Attr-Funktion mit <code>undef</code> beendet ist, wird der neue Wert in FHEM gespeichert und steht dann via AttrVal() zur Verfügung.

Die Attr-Funktion bekommt nicht den Hash der Geräteinstanz übergeben, da sie normalerweise keine Werte dort speichern muss, sondern lediglich das Attribut auf Korrektheit prüfen muss.
Im obigen Beispiel wird für ein Attribut mit Namen "Regex" geprüft ob der reguläre Ausdruck fehlerhaft ist. Sofern dieser OK ist, wird <code>undef</code> zurückgegeben und fhem.pl speichert den Wert des Attributs in <code>%attr</code>.

<u>Attributnamen mit Platzhaltern</u>

Falls man Attribute in der [[#X_Initialize|Initialize]]-Funktion mit Platzhaltern definiert (Wildcard-Attribute) wie z.B.:
<source lang="perl">
$hash->{AttrList} =
"reading[0-9]*Name " .
# usw.
</source>
dann können Anwender Attribute wie reading01Name, reading02Name etc. setzen. Leider funktioniert das bisher nicht durch Klicken in der Web-Oberfläche, da FHEMWEB nicht alle denkbaren Ausprägungen in einem Dropdown anbieten kann. Der Benutzer muss solche Attribute manuell über den <code>attr</code>-Befehl eingeben.

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

<source lang="perl">
addToDevAttrList($name, $aName);
</source>

==== X_Read ====
<source lang="perl">
sub X_Read ($)
{
my ( $hash ) = @_;

...
}
</source>
Die X_Read-Funktion wird aufgerufen, wenn ein dem Gerät zugeordneter Filedeskriptor (serielle Schnittstelle, TCP-Verbindung, ...) Daten zum Lesen bereitgestellt hat. Die Daten müssen nun eingelesen und interpretiert werden.

Im folgenden Beispiel wird über eine serielle Schnittstelle (beziehungsweise über einen USB-To-Seriell-Konverter) von einem angeschlossenen Gerät gelesen. Dazu werden die bisher verfügbaren Daten mit der Funktion <code>DevIo_SimpleRead</code> gelesen. Da die Übertragung möglicherweise noch nicht vollständig ist, kann es sein, dass kurz darauf die X_Read-Funktion wieder aufgerufen wird und ein weiterer Teil oder der Rest der Daten gelesen werden kann.
Die Funktion muss daher prüfen ob schon alle erwarteten Daten angekommen sind und gegebenenfalls die bisher gelesenen Daten in einem eigenen Puffer (idealerweise in <code>$hash</code>) zwischenspeichern. Im Beispiel ist dies <code>$hash->{helper}{BUFFER}</code> an den die aktuell gelesenen Daten angehängt werden, bis die folgende Prüfung ein für das jeweilige Protokoll vollständige Frame erkennt.

<source lang="perl">
sub X_Read($)
{
my ($hash) = @_;
my $name = $hash->{NAME};

# einlesen der bereitstehenden Daten
my $buf = DevIo_SimpleRead($hash);
return "" if ( !defined($buf) );
Log3 $name, 5, "X ($name) - received data: ".$buf;

# Daten in Hex konvertieren und an den Puffer anhängen
$hash->{helper}{BUFFER} .= unpack ('H*', $buf);
Log3 $name, 5, "X ($name) - current buffer content: ".$hash->{helper}{BUFFER};

# prüfen, ob im Buffer ein vollständiger Frame zur Verarbeitung vorhanden ist.
if ($hash->{helper}{BUFFER} =~ "ff1002(.{4})(.*)1003(.{4})ff(.*)") {
...
</source>

Die zu lesenden Nutzdaten können dann je nach Protokoll des Geräts beispielsweise an einer festgelegten Stelle im Frame (dann in <code>$hash->{helper}{BUFFER}</code>) stehen oder aus dem Kontext mit einem Regex-Match extrahiert werden und via [[DevelopmentModuleAPI#Readings_.2F_Events|Reading-Funktionen]] in Readings gespeichert werden (siehe unten).

Der Rückgabewert der Read-Funktion wird nicht geprüft und hat daher keinerlei Bedeutung.

==== X_Ready ====
<source lang="perl">
sub X_Ready ($)
{
my ( $hash ) = @_;

...

return $success;
}
</source>

Wird im Main-Loop aufgerufen falls das Modul in der globalen Liste <code>%readyfnlist</code> existiert. Diese Funktion hat je nachdem auf welchem OS FHEM ausgeführt wird unterschiedliche Aufgaben:

* '''UNIX-artiges Betriebssystem:''' prüfen, ob eine Verbindung nach einem Verbindungsabbruch wieder aufgebaut werden kann. Sobald der Verbindungsaufbau erfolgreich war, muss die Funktion einen erfolgreichen Wahrheitswert zurückliefern (z.B. "1") und den eigenen Eintrag entsprechend aus <code>%readyfnlist</code> löschen.
* '''Windows-Betriebssystem:''' prüfen, ob lesbare Daten für ein serielles Device (via COM1, COM2, ...) vorliegen. Sofern lesbare Daten vorliegen, muss Funktion einen erfolgreichen Wahrheitswert zurückliefern (z.B. "1"). Zusätzlich dazu muss die Funktion, wie bei UNIX-artigen Betriebssystem, ebenfalls bei einem Verbindungsabbruch einen neuen Verbindungsversuch initiieren. Der Eintrag in <code>%readyfnlist</code> bleibt solange erhalten, bis die Verbindung seitens FHEM beendet wird.

Der Windows-spezifische Teil zur Datenprüfung ist dabei nur zu implementieren, wenn das Modul über eine serielle Verbindung kommuniziert.

Bei der Nutzung des Moduls DevIo wird dem Modulentwickler der Umgang mit <code>%readyfnlist</code> abgenommen, da DevIo sich selbst um die entsprechenden Einträge kümmert und diese selbstständig wieder entfernt.

In der Regel sieht eine Ready-Funktion immer gleich aus.

Beispiel:
<source lang="perl">
sub X_Ready($)
{
my ($hash) = @_;

# Versuch eines Verbindungsaufbaus, sofern die Verbindung beendet ist.
return DevIo_OpenDev($hash, 1, undef ) if ( $hash->{STATE} eq "disconnected" );

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

==== X_Notify ====

Die X_Notify-Funktion wird aus der Funktion [[DevelopmentModuleAPI#DoTrigger|DoTrigger()]] in fhem.pl heraus aufgerufen sobald ein Modul Events erzeugt hat. Damit kann ein Modul auf Events anderer Module reagieren. Typische Beispiele sind dabei das [[FileLog]]-Modul oder das [[notify]]-Modul.

Die Notify-Funktion bekommt dafür zwei Hash-Referenzen übergeben: den Hash des eigenen Geräts und den Hash des Geräts, dass die Events erzeugt hat.
Über den Hash des eigenen Geräts kann die Notify-Funktion beispielsweise auf die Internals oder Attribute des eigenen Geräts zugreifen.
Über den Hash des Gerätes und der [[DevelopmentModuleAPI#deviceEvents|deviceEvents()]]-Funktion kann man auf die generierten Events zugreifen. Über den zweiten Parameter dieser Routine lässt sich bestimmen ob für das Reading <code>state</code> ein 'normales' Event (d.h. in der form <code>state: <wert></code>) erzeugen soll (Wert: 1) oder ob z.b. aus Gründen der Rückwärtskompatibilität ein Event ohne <code>state: </code> erzeugt werden soll. Falls dem Anwender die Wahl des verwendeten Formats überlassen werden soll ist hierzu das [http://fhem.de/commandref_DE.html#addStateEvent addStateEvent-Attribut] vorzusehen.

Der direkte Zugriff auf <code>$hash->{CHANGED}</code> ist nicht mehr zu empfehlen.

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

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

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

my $events = deviceEvents($dev_hash,1);
return if( !$events );

foreach my $event (@{$events}) {
$event = "" if(!defined($event));

# Examples:
# $event = "readingname: value"
# or
# $event = "INITIALIZED" (for $devName equal "global")
#
# processing $event with further code
}
}
</source>

<u>Begrenzung der Aufrufe auf bestimmte Geräte</u>

Da die Notify-Funktion für jedes definierte Gerät mit all seinen Events aufgerufen wird, muss sie in einer Schleife jedesmal prüfen und entscheiden, ob es mit dem jeweiligen Event etwas anfangen kann. Ein Gerät, dass die Notify-Funktion implementiert, sieht dafür typischerweise einen regulären Ausdruck vor, welcher für die Filterung verwendet wird.

Wenn man nur gezielt von bestimmten Definitionen Events erhalten will, kann man diese auch in Form einer [http://fhem.de/commandref_DE.html#devspec devspec] in <code>$hash->{NOTIFYDEV}</code> angeben. Bspw. kann man in der Define-Funktion diesen Wert setzen. Dadurch wird die Notify-Funktion nur aufgerufen wenn eine der Definitionen, auf welche die devspec passt, ein Event erzeugt hat. Ein typischer Fall ist die Begrenzung von Events auf "global":

<source lang="perl">
in der Define-Funktion:

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

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

Sofern in der [[#X_Define|Define-Funktion]] eine Regexp als Argument übergeben wird, die ähnlich wie beim Modul [[notify]] auf Events wie <code><Definitionsname></code> bzw. <code><Definitionsname>:<Event></code> reagiert, so sollte man in der Define-Funktion die Funktion [[DevelopmentModuleAPI#notifyRegexpChanged|notifyRegexpChanged()]] verwenden. Diese versucht einen passenden Eintrag für <code>$hash->{NOTIFYDEV}</code> basierend auf der übergebenen Regexp zu setzen, sofern dies möglich ist.

<u>Reihenfolge für den Aufruf der Notify-Funktion beeinflussen</u>

Sobald ein Event ausgelöst wurde, stellt sich FHEM eine Liste aller relevanten Geräte-Hashes zusammen, welche via Notify-Funktion prüfen müssen, ob das Event relevant ist. Dabei wird die Liste nach <code>$hash->{NTFY_ORDER}</code> sortiert. Diese enthält ein Order-Präfix in Form einer Ganzzahl, sowie den Namen der Definition (Bsp: <code>'''50'''-Lampe_Wohnzimmer</code>). Dadurch kann man jedoch nicht sicherstellen, dass Events von bestimmten Modulen zuerst verarbeitet werden.

Wenn das eigene Modul bei der Eventverarbeitung gegenüber den anderen Modulen eine bestimmte Reihenfolge einhalten muss, kann man in der [[#X_Initialize|Initialize]]-Funktion durch Setzen von <code>$hash->{NotifyOrderPrefix}</code> diese Reihenfolge beeinflussen. Standardmäßig werden Module immer mit einem Order-Präfix von "50-" in FHEM registriert. Durch die Veränderung dieses Präfixes kann man das eigene Modul in der Reihenfolge gegenüber anderen Modulen bei der Eventverarbeitung beeinflussen.

Beispiel:

<source lang="perl">
sub X_Initialize($)
{
my ($hash) = @_;

...

$hash->{NotifyOrderPrefix} = "45-" # Alle Definitionen des Moduls X werden bei der Eventverarbeitung zuerst geprüft

# oder...

$hash->{NotifyOrderPrefix} = "55-" # Alle Definitionen des Moduls X werden bei der Eventverarbeitung als letztes geprüft

</source>

Da dieses Präfix bei eventverarbeitenden Definitionen in <code>$hash->{NTFY_ORDER}</code> dem Definitionsnamen vorangestellt wird bewirkt es bei einer normalen aufsteigenden Sortierung nach <code>$hash->{NTFY_ORDER}</code> eine veränderte Reihenfolge. Alle Module die in der Initialize-Funktion nicht <code>$hash->{NotifyOrderPrefix}</code> explizit setzen, werden mit "50-" als Standardwert vorbelegt.

==== X_Rename ====
<source lang="perl">
sub X_Rename ($$)
{
my ( $new_name, $old_name) = @_;

...
}
</source>

Die Rename-Funktion wird ausgeführt, nachdem ein Gerät umbenannt wurde. Auf diese Weise kann ein Modul auf eine Namensänderung reagieren, wenn das Gerät <code>$old_name</code> in <code>$new_name</code> umbenannt wurde. Ein typischer Fall ist das Umsetzen der Namensänderungen bei Daten die mittels [[DevelopmentModuleAPI#setKeyValue|setKeyValue()]] gespeichert wurden. Hierbei müssen die Daten, welche unter dem alten Namen gespeichert sind, auf den neuen Namen geändert werden.

Der Rename-Funktion wird lediglich der alte, sowie der neue Gerätename übergeben. Der Rückgabewert wird nicht ausgewertet.

Beispiel:
<source lang="perl">
sub X_Rename ($)
{
my ( $new_name, $old_name ) = @_;

my $old_index = "Module_X_".$old_name."_data";
my $new_index = "Module_X_".$new_name."_data";

my ($err, $data) = getKeyValue($old_index);
return undef unless(defined($old_pwd));

setKeyValue($new_index, $data);
setKeyValue($old_index, undef);
}
</source>

==== X_Shutdown ====
<source lang="perl">
sub X_Shutdown ($)
{
my ( $hash ) = @_;

...
}
</source>
Mit der X_Shutdown Funktion kann ein Modul Aktionen durchführen bevor FHEM gestoppt wird. Dies kann z.B. der ordnungsgemäße Verbindungsabbau mit dem physikalischen Gerät sein (z.B. Session beenden, Logout, etc.). Als Übergabeparameter wird der Geräte-Hash bereitgestellt. Der Rückgabewert einer Shutdown-Funktion wird nicht ausgewertet und ist daher irrelevant.

Beispiel:
<source lang="perl">
sub X_Shutdown($)
{
my ($hash) = @_;

# Verbindung schließen
DevIo_CloseDev($hash);
return undef;
}
</source>

=== Funktionen für zweistufiges Modulkonzept ===

Für das [[#Zweistufiges_Modell_für_Module|zweistufige Modulkonzept]] gibt es weiterhin:

{| class="wikitable sortable"
|-
! style="text-align:left" | Funktionsname !! style="text-align:left" class="unsortable" | Kurzbeschreibung
|-
| [[#X_Parse|X_Parse]] || Zustellen von Daten via [[DevelopmentModuleAPI#Dispatch|Dispatch()]] vom physischen Modul zum logischen Modul zwecks der Verarbeitung.
|-
| [[#X_Write|X_Write]]|| Zustellen von Daten via [[DevelopmentModuleAPI#Dispatch|IOWrite()]] vom logischen zum physischen Modul um diese an die Hardware weiterzureichen.
|-
| [[#X_Fingerprint|X_Fingerprint]] || Rückgabe eines "Fingerabdrucks" einer Nachricht. Dient der Erkennung von Duplikaten im Rahmen von [[DevelopmentModuleAPI#Dispatch|Dispatch()]]. Kann im physischen, als auch logischen Modul benutzt werden.
|}

Für das zweistufige Modulkonzept muss in einem logischen Modul eine [[#X_Parse|Parse]]-Funktion im Modul-Hash registriert werden. In einem physikalischen Modul muss eine [[#X_Write|Write]]-Funktion definiert sein. Diese dienem dem Datenaustausch in beide Richtungen und werden von dem jeweils anderen Modul indirekt aufgerufen.

In der [[#X_Initialize|Initialize]]-Funktion werden diese wie folgt definiert:

<source lang="perl">
$hash->{ParseFn} = "X_Parse";
$hash->{WriteFn} = "X_Write";
$hash->{FingerprintFn} = "X_Fingerprint";
</source>

Diese Funktionen werden in diesem Abschnitt genauer beschrieben.

==== X_Parse ====
{{Randnotiz|RNTyp=Info|RNText=<font color="red"><u>'''ACHTUNG''':</u></font>
Dieser Abschnitt geht davon aus, dass das Modul mit dem Namen "X" ein '''logisches Modul''' im Sinne des zweistufigen Modulkonzepts ist, also Daten mit einem übergeordneten, physikalischen Modul austauscht.}}
<source lang="perl">
sub X_Parse ($$)
{
my ( $io_hash, $message) = @_;

...

return $found;
}
</source>

Die Funktion X_Parse wird aufgerufen, sobald von dem IO-Gerät <code>$io_hash</code> eine Nachricht <code>$message</code> via [[DevelopmentModuleAPI#Dispatch|Dispatch()]] zur Verarbeitung angefragt wird. Die Parse-Funktion muss dann prüfen, zu welcher Gerätedefinition diese Nachricht gehört und diese entsprechend verarbeiten.

Üblicherweise enthält eine Nachricht immer eine Komponente durch welche sich die Nachricht einem Gerät zuordnen lässt (z.B. Adresse, ID-Nummer, ...). Eine solche Identifikation sollte man im Rahmen der [[#X_Define|Define]]-Funktion im logischen Modul an geeigneter Stelle speichern, um in der Parse-Funktion eine einfache Zuordnung von Adresse/ID einer Nachricht zur entsprechenden Gerätedefinition zu haben. Dazu wird in der Regel im Modul-Hash im modulspezifischen Berreich eine Liste <code>defptr</code> (Definition Pointer) geführt, welche jede eindeutige Adresse/ID dem entsprechenden Geräte-Hash zuordnet:

<source lang="perl">

sub X_Define ($$)
{
my ( $hash, $def) = @_;
my @a = split("[ \t][ \t]*", $def);
my $name = $a[0];

...

# erstes Argument ist die eindeutige Geräteadresse
my $address = $a[1];

# Adresse rückwärts dem Hash zuordnen (für ParseFn)
$modules{X}{defptr}{$address} = $hash;

...
}
</source>

Auf Basis dieses Definition Pointers kann die Parse-Funktion nun sehr einfach prüfen, ob für die empfangene Nachricht bereits eine entsprechende Gerätedefinition existiert. Sofern diese existiert, kann die Nachricht entsprechend verarbeitet werden. Sollte jedoch keine passende Gerätedefinition zu der empfangenen Nachricht existieren, so muss die Parse-Funktion den Gerätenamen "UNDEFINED" zusammen mit den Argumenten für einen <code>define</code>-Befehl zurückgeben, welcher ein passendes Gerät in FHEM anlegen würde (durch [[autocreate]]).

Beispiel:

<source lang="perl">

sub X_Parse ($$)
{
my ( $io_hash, $message) = @_;

# Die Stellen 10-15 enthalten die eindeutige Identifikation des Geräts
my $address = substr($message, 10, 5);

# wenn bereits eine Gerätedefinition existiert (via Definition Pointer aus Define-Funktion)
if(my $hash = $modules{X}{defptr}{$address})
{
... # Nachricht für $hash verarbeiten

# Rückgabe des Gerätenamens, für welches die Nachricht bestimmt ist.
return $hash->{NAME};
}
else
{
# Keine Gerätedefinition verfügbar
# Daher Vorschlag define-Befehl: <NAME> <MODULNAME> <ADDRESSE>
return "UNDEFINED X_".$address." X $address";
}
}
</source>

==== X_Write ====
{{Randnotiz|RNTyp=Info|RNText=<font color="red"><u>'''ACHTUNG''':</u></font>
Dieser Abschnitt geht davon aus, dass das Modul mit dem Namen "X" ein '''physisches Modul''' im Sinne des zweistufigen Modulkonzepts ist, also Daten mit untergeordneten logischen Modulen austauscht. }}
<source lang="perl">
sub X_Write ($$)
{
my ( $hash, @arguments) = @_;

...

return $return;
}
</source>

Die Write-Funktion wird durch die Funktion [[DevelopmentModuleAPI#IOWrite|IOWrite()]] aufgerufen, sobald eine logische Gerätedefinition Daten per IO-Gerät an die Hardware übertragen möchte. Dazu kümmert sich die Write-Funktion um die Übertragung der Nachricht in geeigneter Form an die verbundene Hardware. Als Argumente wird der Hash des physischen Gerätes übertragen, sowie alle weiteren Argumente, die das logische Modul beim Aufruf von IOWrite() mitgegeben hat. Im Normalfall ist das ein Skalar mit der zu sendenden Nachricht in Textform. Es kann aber auch sein, dass weitere Daten zum Versand notwendig sind (evtl. Schlüssel, Session-Key, ...). Daher ist die Parametersyntax einer zu schreibenden Nachricht via IOWrite-/Write-Funktion zwischen logischem und physikalischen Modul abzustimmen.

Beispiel:

<source lang="perl">
sub X_Write ($$)
{
my ( $hash, $message, $address) = @_;

DevIo_SimpleWrite($hash, $address.$message, 2);

return undef;
}
</source>

==== X_Fingerprint ====
<source lang="perl">
sub X_Fingerprint($$)
{
my ( $io_name, $msg ) = @_;

...

return ( $io_name, $fingerprint );
}
</source>

Die Fingerprint-Funktion dient der Erkennung von Duplikaten empfangener Nachrichten. Diese Funktion kann dabei sowohl im physischen, als auch im logischen Modul implementiert sein. Je nachdem auf welcher Ebene man für eine Nachricht einen Fingerprint bilden kann.

Als Parameter wird der Name des IO-Geräts <code>$io_name</code> übergeben, sowie die Nachricht <code>$msg</code>, welche empfangen wurde. Nun muss aus dieser Nachricht ein eindeutiger Fingerprint gebildet werden. Dies bedeutet, dass alle variablen Inhalte, die aufgrund des Empfangs dieser Nachricht über unterschiedliche IO-Geräte enthalten sein können, entfernt werden müssen. Dies können bspw. Empfangsadressen von IO-Geräten sein oder Session-ID's die in der Nachricht enthalten sind. Alle Fingerprints sämtlicher Nachrichten, die innerhalb der letzten 500 Millisekunden (konfigurierbar via <code>global</code> Attribut <code>dupTimeout</code>) empfangen wurden, werden gegen diesen generierten Fingerprint getestet. Sollte innerhalb dieser Zeit bereits eine Nachricht mit diesem Fingerprint verarbeitet worden sein, so wird sie als Duplikat erkannt und nicht weiter verarbeitet. In diesem Fall gibt [[DevelopmentModuleAPI#Dispatch|Dispatch()]] den Namen der Gerätedefinition zurück, welche eine Nachricht mit dem selben Fingerprint bereits verarbeitet hat. Es erfolgt dann kein Aufruf der [[#X_Parse|Parse]]-Funktion.

Beispiel:

<source lang="perl">
sub X_Fingerprint($$)
{
my ( $io_name, $msg ) = @_;

substr( $msg, 2, 2, "--" ); # entferne Empfangsadresse
substr( $msg, 4, 1, "-" ); # entferne Hop-Count

return ( $io_name, $msg );
}
</source>

Es wird zuerst, sofern implementiert, die Fingerprint-Funktion des physischen Moduls aufgerufen. Sollte sich hierdurch kein Duplikat erkennen lassen, wird die Fingerprint-Funktion jedes möglichen geladenen logischen Moduls aufgerufen, sofern implementiert.

Sollte sowohl im physischen, als auch im logischen Modul keine Fingerprint-Funktion implementiert sein, so wird keinerlei Duplikatserkennung durchgeführt.

=== FHEMWEB-spezifische Funktionen ===

FHEMWEB bietet Modulautoren die Möglichkeit an durch spezielle Funktionsaufrufe in Modulen, eigene HTML-Inhalte zu verwenden. Dadurch können in Verbindung mit zusätzlichem JavaScript komplexe Dialoge/Inhalte/Steuermöglichkeiten dargestellt werden.

Eine genaue Auflistung aller FHEMWEB-spezifischen Funktionsaufrufe gibt es in dem separaten Artikel [[DevelopmentFHEMWEB]]

=== sonstige Funktionen ===

In diesem Abschnitt werden weitere Funktionen behandelt die zum Teil aus FHEM, aber auch aus anderen Modulen aufgerufen werden. Sie sind dabei nur in speziellen Anwendungsfällen relevant. Hier eine Auflistung aller sonstigen Modulfunktionen:

{| class="wikitable sortable"
|-
! Funktionsname !! class="unsortable" | Kurzbeschreibung
|-
| [[#X_DbLog_split|X_DbLog_split]] || Wird durch das Modul 93_DbLog.pm aufgerufen. Dient dem korrekten Split eines moduleigenen Events in Name/Wert/Einheit für die Nutzung einer Datenbank.
|-
| [[#X_Except|X_Except]]|| Wird aufgerufen, sobald ein ein geöffneter Filedescriptor in [[#Wichtige_globale_Variablen_aus_fhem.pl|<code>%selectlist</code>]], der unter <code>$hash->{EXCEPT_FD}</code> im Geräte-Hash gesetzt ist, einen Interrupt bzw. Exception auslöst.
|-
| [[#X_Copy|X_Copy]]|| Wird durch das Modul 98_copy.pm aufgerufen im Rahmen des <code>copy</code>-Befehls sobald ein Gerät kopiert wurde.
|-
| [[#X_State|X_State]]|| Wird aufgerufen im Rahmen des <code>setstate</code>-Befehls bevor der Status einer Gerätedefinition bzw. eines zugehörigen Readings gesetzt wird.
|-
| [[#X_AsyncOutput|X_AsyncOutput]]|| Nur Relevant für Module die via [[TcpServerUtils]] eine Client-Verbindung zu FHEM ermöglichen (z.B. FHEMWEB und telnet). Ermöglicht die asynchrone Ausgabe von Daten via [[DevelopmentModuleAPI#asyncOutput|asyncOutput()]] an einen einzelnen verbundenen Client.
|-
| [[#X_ActivateInform|X_ActivateInform]]|| Nur Relevant für Module die via [[TcpServerUtils]] eine Client-Verbindung zu FHEM ermöglichen (z.B. FHEMWEB und telnet). Ermöglicht das aktivieren des inform-Mechanismus zum senden von Events für einen einzelnen verbundenen Client.
|-
| [[#X_Authorize|X_Authorize]]|| Wird aufgerufen im Rahmen von [[DevelopmentModuleAPI#Authorize|Authorize()]] um eine gewünschte Vorgangs-Art zu autorisieren.
|-
| [[#X_Authenticate|X_Authenticate]]|| Wird aufgerufen im Rahmen von [[DevelopmentModuleAPI#Authenticate|Authenticate()]] um eine Authentifizierung zu prüfen und ggf. zu genehmigen.
|}

In der [[#X_Initialize|Initialize]]-Funktion werden diese wie folgt definiert:

<source lang="perl">
$hash->{DbLog_splitFn} = "X_DbLog_split";
$hash->{ExceptFn} = "X_Except";
$hash->{CopyFn} = "X_Copy";
$hash->{AsyncOutputFn} = "X_AsyncOutput";
$hash->{ActivateInformFn} = "X_ActivateInform";
$hash->{StateFn} = "X_State";
$hash->{AuthorizeFn} = "X_Authorize";
$hash->{AuthenticateFn} = "X_Authenticate";
</source>

Diese Funktionen werden in diesem Abschnitt genauer beschrieben.
==== X_DbLog_split ====
<source lang="perl">
sub X_DbLog_split ($$)
{
my ( $event, $device_name ) = @_;

...

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

Die DbLog_split-Funktion wird durch das Modul [[DbLog]] aufgerufen, sofern der Nutzer DbLog benutzt. Sofern diese Funktion implementiert ist, kann der Modulautor das Auftrennen von Events in den Reading-Namen, -Wert und der Einheit selbst steuern. Andernfalls nimmt DbLog diese Auftrennung selber mittels Trennung durch Leerzeichen sowie vordefinierten Regeln zu verschiedenen Modulen vor. Je nachdem, welche Readings man in seinem Modul implementiert, passt diese standardmäßige Trennung jedoch nicht immer.

Der Funktion werden folgende Eingangsparameter übergeben:
# Das generierte Event (Bsp: <code>temperature: 20.5 °C</code>)
# Der Name des Geräts, welche das Event erzeugt hat (Bsp: <code>Temperatursensor_Wohnzimmer</code>)

Es ist nicht möglich in der DbLog_split-Funktion auf die verarbeitende DbLog-Definition zu referenzieren.

Als Rückgabewerte muss die Funktion folgende Werte bereitstellen:
# Name des Readings (Bsp: <code>temperature</code>)
# Wert des Readings (Bsp: <code>20.5</code>)
# Einheit des Readings (Bsp: <code>°C</code>)

Beispiel:
<source lang="perl">
sub X_DbLog_splitFn($$)
{
my ($event, $device) = @_;
my ($reading, $value, $unit);
my $devhash = $defs{$device}

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

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

==== X_Except ====
<source lang="perl">
sub X_Except ($)
{
my ( $hash ) = @_;

...
}
</source>

Die X_Except-Funktion wird durch fhem.pl aufgerufen, wenn die Gerätedefinition <code>$hash</code> in <code>[[#Wichtige_globale_Variablen_aus_fhem.pl|%selectlist]]</code> aufgeführt ist und der Filedeskriptor in <code>$hash->{EXCEPT_FD}</code> eine Exception bzw. Interrupt auslöst.

Der Rückgabewert wird nicht ausgewertet und ist daher irrelevant.

Beispiel:

<source lang="perl">
use IO::File;

...

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

# Filehandle aus Filedescriptor erstellen
my $filehandle = IO::File->new_from_fd($hash->{EXCEPT_FD}, 'r');
seek($filehandle,0,0);

# aktuellen Inhalt auslesen
my $current_value = $filehandle->getline;

if($current_value eq "1")
{
...
}
else
{
...
}
}
</source>

==== X_Copy ====
<source lang="perl">
sub X_Copy ($)
{
my ( $old_name, $new_name ) = @_;

...
}
</source>

Die X_Copy-Funktion wird durch das Modul [[copy]] aufgerufen nachdem ein Nutzer eine Gerätedefinition über den Befehl <code>copy</code> kopiert hat. Dazu werden als Funktionsparameter die Definitionsnamen der alten und neuen Gerätedefinition übergeben. Es dient dazu zusätzliche Daten aus der zu kopierenden Gerätedefinition in die neue Definition zu übernehmen. Der Befehl <code>copy</code> überträgt lediglich <code>$hash->{DEF}</code> in die neue Definition sowie sämtliche gesetzte Attribute. Weitere Daten müssen dann durch die X_Copy-Funktion übertragen werden.

Die X_Copy-Funktion wird erst nach dem erfolgtem Kopiervorgang aufgerufen.

Der Rückgabewert wird nicht ausgewertet und ist daher irrelevant.

Beispiel:

<source lang="perl">

sub X_Copy ($$)
{
my ( $old_name, $new_name ) = @_;

my $old_hash = $defs{$old_name};
my $new_hash = $defs{$new_name};

# copy also temporary session key
$new_hash->{helper}{SESSION_KEY} = $old_hash->{helper}{SESSION_KEY};
}
</source>

==== X_AsyncOutput ====
TBD

==== X_ActivateInform ====
TBD
==== X_State ====
<source lang="perl">
sub X_State($)
{
my ( $hash, $time, $readingName, $value ) = @_;

...

return $error;
}
</source>

Die X_State-Funktion wird durch fhem.pl aufgerufen, sobald über den Befehl <code>setstate</code> versucht wird ein Wert für ein Reading oder den Status (<code>$hash->{STATE}</code>) einer Gerätedefinition zu setzen. Dieser Befehl wird primär beim Starten von FHEM aufgerufen sobald das State-File eingelesen wird. Je nachdem, ob im gegebenen Fall ein Reading oder der Definitionsstatus gesetzt wird, haben die Übergabeparameter verschiedene Werte:

{| class="wikitable"
|-
! Funktionsparameter!! Wert beim Setzen eines Readings !! Wert beim Setzen eines Definitionsstatus
|-
| <code>$hash</code> || colspan=2 align=center | Die Hashreferenz der betreffenden Gerätedefinition
|-
| <code>$time</code>|| Der Zeitstempel auf welchen das Reading <code>$readingName</code> gesetzt werden soll. Das Ergebnis entspricht dem Rückgabewert der Funktion || Der aktuelle Zeitstempel zum jetzigen diesem Zeitpunkt.
|-
| <code>$readingName</code>|| Der Name des Readings, welches auf einen neuen Wert gesetzt werden soll. || Statischer Wert "STATE" um anzuzeigen, dass es sich um den Definitionsstatus handelt, welcher gesetzt werden soll (<code>$hash->{STATE}</code>).
|-
| <code>$value</code> || Der Wert, welchen das Reading <code>$readingName</code> annehmen soll. || Der Wert, welchen die Gerätedefinition als Status annehmen soll.
|}

Wenn via <code>setstate</code> ein Reading gesetzt wird, kann die X_State-Funktion das Setzen dieses Readings durch die Rückgabe einer aussagekräftigen Fehlermeldung unterbinden. Sofern <code>undef</code> zurückgegeben wird, wird das entsprechende Reading auf den übergebenen Status gesetzt.

Wenn via <code>setstate</code> der Definitionsstatus gesetzt wird, wird die X_State-Funktion erst nach dem Setzen des Status aufgerufen. Man kann dabei zwar eine Fehlermeldung zurückgeben. Der Status wird aber dennoch übernommen. Die Fehlermeldung wird lediglich dem Nutzer angezeigt.

Beispiel:

<source lang="perl">
sub X_State($)
{
my ( $hash, $time, $readingName, $value ) = @_;

return undef if($readingName "STATE" || $value ne "inactive");
readingsSingleUpdate($hash, "state", "inactive", 1);
return undef;
}
</source>

==== X_Authorize ====
TBD

==== X_Authenticate ====
TBD

== Bereitstellen eines eigenen Befehls (Befehlsmodul) ==

Ein Modul kann primär einen neuen FHEM-Befehl bereitstellen. Man spricht in so einem Fall nicht von einem Gerätemodul, sondern einem Befehlsmodul. Ein solches Befehlsmodul stellt nur einen einzelnen Befehl bereit, der dem Modulnamen entsprechen muss. Nur, wenn der Modulname dem Befehlsname entspricht, kann FHEM das Modul beim ersten Ausführen dieses unbekannten Befehls finden und nachladen.

Der entsprechende Befehl wird dazu in der [[#X_Initialize|Initialize]]-Funktion im globalen Hash <code>[[DevelopmentModuleIntro#Wichtige_globale_Variablen_aus_fhem.pl|%cmds]]</code> registriert:

<source lang="perl">
sub X_Initialize($$) {

$cmds{X} = { Fn => "CommandX",
Hlp => "<argument1> [optional_argument2], print something very useful",

# optional
ClientFilter => "FHEMWEB"
};
}
</source>

Damit wird der neue Befehl <code>X</code> in FHEM registriert. Die Funktion mit dem Namen <code>CommandX</code> setzt diesen Befehl innerhalb des Moduls um. Desweiteren wird eine kurze Aufrufsyntax mitgegeben, welche beim Aufruf des <code>help</code>-Befehls dem Nutzer angezeigt wird um als Gedankenstütze zu dienen. Optional kann man mittels <code>ClientFilter</code> die Ausführbarkeit nur auf bestimmte Client-Module (wie FHEMWEB oder telnet) beschränken.

Nun muss noch die Funktion <code>CommandX</code> im Rahmen des Moduls implementiert werden, welche den Befehl <code>X</code> umsetzt:

<source lang="Perl">
sub CommandX($$)
{
my ($client_hash, $arguments) = @_;

...

return $output;
}
</source>

Dabei werden der Befehlsfunktion zwei Parameter übergeben. Zuerst die Hash-Referenz des aufrufenden Clients (sofern manuell ausgeführt, ansonsten <code>undef</code>) zwecks Rechteprüfung via [[allowed|allowed-Definitionen]]. Anschließend folgen die Aufrufparameter als zusammenhängende Zeichenkette. Die Trennung der einzelnen Argumente obligt der Funktion (bspw. via [[DevelopmentModuleAPI#parseParams|parseParams()]]). Als Funktionsrückgabewert wird eine Ausgabemeldung erwartet, die dem Nutzer angezeigt werden soll.

== Pollen von Geräten ==
Wenn Geräte von sich aus keine Informationen senden sondern abgefragt werden müssen, kann man im Modul die Funktion [[DevelopmentModuleAPI#InternalTimer|InternalTimer()]] verwenden um einen Funktionsaufruf zu einem späteren Zeitpunkt durchführen zu können. Man übergibt dabei den Zeitpunkt für den nächsten Aufruf, den Namen der Funktion, die aufgerufen werden soll, sowie den zu übergebenden Parameter. Als zu übergebender Parameter wird üblicherweise der Hash der betroffenen Geräteinstanz verwendet. Damit hat die aufgerufene Funktion Zugriff auf alle wichtigen Daten der Geräteinstanz. Eventuell zusätzlich benötigte Werte können einfach als weitere Internals über den Hash zugänglich gemacht werden.

Beispielsweise könnte man für das Abfragen eines Geräts in der [[#X_Define|Define]]-Funktion den Timer folgendermaßen setzen:

<source lang="perl">
InternalTimer(gettimeofday()+2, "X_GetUpdate", $hash);
</source>

Alternativ kann man auch in der [[#X_Notify|Notify]]-Funktion auf das Event <code>global:INITIALIZED</code> bzw. <code>global:REREADCFG</code> reagieren und erst dort, den Timer anstoßen, sobald die Konfiguration komplett eingelesen wurde. Dies ist insbesondere notwendig, wenn man sicherstellen will, dass alle Attribute aus der Konfiguration gesetzt sind, sobald man einen Status-Update initiiert.

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

<source lang="perl">
sub X_GetUpdate($)
{
my ($hash) = @_;
my $name = $hash->{NAME};
Log3 $name, 4, "X: GetUpdate called ...";

...

# neuen Timer starten in einem konfigurierten Interval.
InternalTimer(gettimeofday()+$hash->{Interval}, "X_GetUpdate", $hash);
}
</source>

Innerhalb der Funktion kann man nun das Gerät abfragen und die abgefragten Werte in Readings speichern. Falls das Abfragen der Werte jedoch zu einer Verzögerung und damit zu einer Blockade von FHEM führen kann, ist es möglich, in der GetUpdate-Funktion nur die Aufforderung zum Senden bestimmter Daten an das angeschlossene Gerät zu senden und dann das Lesen über die oben beschriebene [[#X_Read|Read]]-Funktion zu implementieren.

Eine genaue Beschreibung der Timer-Funktion gibt es [[DevelopmentModuleAPI#Timer|hier im Wiki]]

== Logging / Debugging ==
Um Innerhalb eines Moduls eine Log-Meldung in die FHEM-Logdatei zu schreiben, wird die Funktion [[DevelopmentModuleAPI#Log3|Log3()]] aufgerufen.
<source lang="perl">
Log3 $name, 3, "X ($name) - Problem erkannt ...";
</source>
Eine genaue Beschreibung zu der Funktion inkl. Aufrufparameter findet man [[DevelopmentModuleAPI#Log3|hier]]. Es ist generell ratsam in der Logmeldung sowohl den Namen des eigenen Moduls zu schreiben, sowie den Namen des Geräts, welche diese Logmeldung produziert, da die Meldung, so wie sie ist, direkt in das Logfile wandert und es für User ohne diese Informationen schwierig ist, die Meldungen korrekt zuzuordnen.

Die Funktion Log3() verwendet den Namen der Geräteinstanz um das <code>verbose</code>-Attribut zu prüfen. In der Regel wird bei Modulfunktionen jedoch immer nur der Gerätehash <code>$hash</code> übergeben. Um den Namen der Definition zu ermitteln ist es daher notwendig sich diesen aus dem Hash extrahieren:

<source lang="perl">
my $name = $hash->{NAME};
</source>

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

Logmeldungen sollten je nach Art und Wichtigkeit für den Nutzer in unterschiedlichen Loglevels erzeugt werden. Es gibt insgesamt 5 Stufen in denen geloggt werden kann. Standardmäßig steht der systemweite Loglevel (<code>global</code>-Attribut <code>verbose</code>) auf der Stufe 3. Die Bedeutung der jeweiligen Stufen ist in der [http://fhem.de/commandref_DE.html#verbose commandref] beschrieben.

Während der Entwicklung eines Moduls kann man für eigene Debug-Zwecke auch die Funktion [[DevelopmentModuleAPI#Debug|Debug()]] verwenden um schnell und einfach Debug-Ausgaben in das Log zu schreiben. Diese sollten in der endgültigen Fassung jedoch nicht mehr vorhanden sein. Sie dienen ausschließlich zum Debugging während der Entwicklung.

Eine genaue Beschreibung der Log-Funktion gibt es [[DevelopmentModuleAPI#Logging|hier im Wiki]].

== Zweistufiges Modell für Module ==
[[Datei:Zweistufiges Modulkonzept.jpg|mini|rechts]]
Es gibt viele Geräte, welche die Kommunikation mit weiteren Geräten mit tlw. unterschiedlichen Protokollen ermöglichen. Das typischste Beispiel bietet hier der [[CUL]], welcher via Funk mit verschiedenen Protokollen weitere Geräte ansprechen kann (z.B. Aktoren, Sensoren, ...). Hier bildet ein Gerät eine Brücke durch die weitere Geräte in FHEM zugänglich gemacht werden können. Dabei werden über einen Kommunikationsweg (z.B. serielle Schnittstelle, TCP, ...) beliebig viele Geräte gesteuert. Typische Beispiele dazu sind:

* [[CUL]]: stellt Geräte mit verschiedenen Kommunikationsprotokollen via Funk bereit (u.a. [[FS20]], [[HomeMatic]], [[Funk-Heizkörperregler_Kurz-Bedienungsanleitung_FHT|FHT]], [[MAX]], ...)
* [[HMLAN]]: stellt HomeMatic Geräte via Funk bereit
* [[MAX#MAXLAN|MAXLAN]]: stellt [[MAX|MAX!]] Geräte via Funk bereit
* [[PanStamp#panStick.2FShield|panStamp]]: stellt weitere panStamp Geräte via Funk bereit

Dabei wird die Kommunikation in 2 Stufen unterteilt:
* physisches Modul - z.B. 00_CUL.pm - zuständig für die physikalische Kommunikation mit der Hardware. Empfangene Daten müssen einem logischen Modul zugeordnet werden.
* logische Modul(e) - z.B. 10_FS20.pm - interpretiert protokollspezifische Nachrichten. Sendet protokollspezifische Daten über das physische Modul an die Hardware.

<u>physisches Modul</u>

Das physische Modul öffnet die Datenverbindung zum Gerät (z.B. CUL) und verarbeitet sämtliche Daten. Es kümmert sich um den Erhalt der Verbindung (bsp. durch Keep-Alives) und konfiguriert das Gerät so, dass eine Kommunikation mit allen weiteren Geräten möglich ist (bsp. Frequenz, Modulation, Kanal, etc.).

Empfangene Nutzdaten werden über die Funktion [[DevelopmentModuleAPI#Dispatch|Dispatch()]] an logische Module weitergegeben.

Das Modul stellt eine [[#Die_Match-Liste|Match-Liste]] bereit, anhand FHEM die Nachricht einem Modul zuordnen kann, sofern dieses noch nicht geladen sein sollte. FHEM lädt dann automatisch dieses Modul nach, zwecks Verarbeitung der Nachricht. Anhand einer bereitgestellten [[#Die_Client-Liste|Client-Liste]] kann FHEM feststellen, welche logischen Module mit diesem Modul kommunizieren können.

Das Modul stellt eine [[#X_Write|Write]]-Funktion zur Verfügung, über die logische Module Daten an die Hardware übertragen können.

<u>logisches Modul</u>

Das logische Modul interpretiert die Nachricht über eine bereitgestellte [[#X_Parse|Parse]]-Funktion und erzeugt entsprechende Readings/Events. Es stellt über <code>set</code>-/<code>get</code>-Kommandos Steuerungsmöglichkeiten dem Nutzer zur Verfügung.

Es stellt FHEM einen [[#Der_Match-Ausdruck|Match-Ausdruck]] zur Verfügung anhand FHEM ermitteln kann, ob die Nachricht durch das logische Modul verarbeitet werden kann.

=== Die Client-Liste ===

Die Client-Liste ist eine Auflistung von Modulnamen (genauer: regulären Ausdrücken die auf Modulnamen passen) die in einem physischen Modul gesetzt ist. Damit wird definiert, mit welche logischen Modulen das physikalische Modul kommunizieren kann.

Eine Client-Liste ist eine Zeichenkette, welche aus allen logischen Modulnamen besteht. Die einzelnen Namen werden durch einen Doppelpunkt getrennt. Anstatt kompletter Modulnamen können auch reguläre Ausdrücke verwendet werden, die auf mehrere Modulnamen passen.

Bsp.: Die Client-Liste von dem Modul CUL lautet daher wie folgt:

FS20:FHT.*:KS300:USF1000:BS:HMS:CUL_EM:CUL_WS:CUL_FHTTK:CUL_HOERMANN:ESA2000:CUL_IR:CUL_TX:Revolt:IT:UNIRoll:SOMFY:STACKABLE_CC:CUL_RFR:CUL_TCM97001:CUL_REDIRECT

Alle hier aufgelisteten Module können über das Modul CUL Daten empfangen bzw. senden.

Die Client-Liste hat generell folgende Funktion:
* Die Funktion [[DevelopmentModuleAPI#Dispatch|Dispatch()]] prüft nur Module, welche in der Client-Liste enthalten sind, ob diese die Nachricht verarbeiten können.
* Die Funktion [[DevelopmentModuleAPI#AssignIoPort|AssignIoPort()]] prüft anhand sämtlicher Client-Listen in FHEM, welches IO-Gerät für ein logisches Gerät nutzbar ist.

Üblicherweise wird die Client-Liste in der [[#X_Initialize|Initialize]]-Funktion im Modul-Hash gesetzt:

<source lang="perl">
sub X_Initialize($)
{
my ($hash) = @_;
...
$hash->{Clients} = "FS20:KS300:FHT.*";
}
</source>

Man kann die Client-Liste jedoch auch pro physikalisches Gerät setzen. Eine gesetzte Client-Liste in einem Gerät hat immer Vorrang vor der Liste im Modul-Hash. Eine gerätespezifische Client-Liste wird dann verwendet, wenn bspw. ein Gerät je nach Konfiguration nur bestimmte logische Module bedienen kann. Bspw. kann ein CUL je nach RF-Einstellungen FS20, uvm. oder nur HomeMatic bedienen. In einem solchen Fall wird die Client-Liste im Geräte-Hash gesetzt:

<source lang="perl">
sub X_Define($$)
{
my ( $hash, $def ) = @_;
...
$hash->{Clients} = "CUL_HM";
}
</source>

In vielen Modulen, welche nach dem zweistufigem Konzept arbeiten, beginnt und endet die Client-Liste mit einem Doppelpunkt. Dies ist ein historisches Überbleibsel, da der Prüfmechanismus die Client-Liste früher auf das Vorhandensein von <code>'''<u><font color="red">:</font></u>'''<Modulname>'''<u><font color="red">:</font></u>'''</code> prüfte. Dies ist nun nicht mehr notwendig. Die einzelnen Modulnamen müssen lediglich durch einen Doppelpunkt getrennt werden.

=== Die Match-Liste ===
{{Randnotiz|RNTyp=Info|RNText=<font color="red"><u>'''ACHTUNG''':</u></font>
Sämtliche regulären Ausdrücke in der Match-Liste werden "case insensitive" überprüft. Das bedeutet, dass Groß-/Kleinschreibung nicht berücksichtigt wird.

Um dennoch in einem regulären Ausdruck auf Groß-/Kleinschreibung zu prüfen, kann man dieses mit dem Modifizierer <code>(?-i)</code> wieder aktivieren:

<source lang="perl">
my %matchListFHEMduino = (
....
"5:FHEMduino_PT2262" => "^(?-i)IR.*\$",
....
"13:IT" => "^(?-i)i......\$",
);
</source>

Siehe dazu Forumsbeitrag: {{Link2Forum|Topic=33422}}
}}
Die Match-Liste ordnet eine Nachrichtensyntax (regulärer Ausdruck) einem Modulnamen zu und wird in einem physikalischen Modul gesetzt. Sollte eine Nachricht vom physikalischen Gerät empfangen werden, die durch kein geladenes Modul verarbeitet werden kann, so wird über die Match-Liste geprüft, welches Modul diese Nachricht verarbeiten kann. Dieses Modul wird anschließend geladen und die Nachricht durch dieses verarbeitet. In dieser Liste findet mittels regulärem Ausdruck eine Zuordnung der Nachrichtenstruktur zum verarbeitenden logischen Modul statt.

Diese Liste wird ausschließlich in der [[DevelopmentModuleAPI#Dispatch|Dispatch()]]-Funktion verwendet. Sollte keine passendes Modul, welches bereits geladen ist, zur Verarbeitung einer Nachricht gefunden werden, so wird mithilfe der Match-Liste aufgrund der vorliegenden Nachricht das entsprechende Modul ermittelt. Dieses Modul wird dann direkt geladen und die Nachricht wird via [[#X_Parse|Parse]]-Funktion verarbeitet.

Die Match-Liste ist eine Zuordnung von einem Sortierpräfix + Modulname zu einem regulären Ausdruck:

<source lang="perl">
{
"1:FS20" => "^81..(04|0c)..0101a001",
"2:KS300" => "^810d04..4027a001",
"3:FHT" => "^81..(04|09|0d)..(0909a001|83098301|c409c401).."
}
</source>

Das Sortierpräfix dient als Sortierhilfe um so die Reihenfolge der Prüfung festzulegen. Bei der Prüfung wird der Hash mittels sort() sortiert und die regulären Ausdrücke werden dann nacheinander getestet. Daher sollten die präzisesten Ausdrücke immer zuerst getestet werden, sofern es weniger präzise Ausdrücke in der Match-Liste gibt. Dabei ist zu beachten, dass der Sortierpräfix nicht nach numerischen Regeln sortiert wird, sondern basierend auf der Zeichenreihenfolge.

Üblicherweise wird die Match-Liste in der [[#X_Initialize|Initialize]]-Funktion im Modul-Hash gesetzt:

<source lang="perl">
sub X_Initialize($)
{
my ($hash) = @_;

...

$hash->{MatchList} = { "1:FS20" => "^81..(04|0c)..0101a001",
"2:KS300" => "^810d04..4027a001",
"3:FHT" => "^81..(04|09|0d)..(0909a001|83098301|c409c401).." };
}
</source>

Man kann die Match-Liste, ähnlich wie bei der Client-Liste, auch pro physikalisches Gerät setzen. Dabei hat auch hier die Match-Liste eines Gerätes immer Vorrang vor der Match-Liste aus dem Modul-Hash:

<source lang="perl">
sub X_Define($$)
{
my ($hash, $def) = @_;

...

$hash->{MatchList} = { "1:CUL_HM" => "^A...................." };
}
</source>

=== Der Match-Ausdruck ===

Ein Match-Ausdruck wird in einem logischen Modul gesetzt und dient der Prüfung, ob eine Nachricht durch das eigene Modul via [[#X_Parse|Parse]]-Funktion verarbeitet werden kann. Es handelt sich hierbei um einen einzelnen regulären Ausdruck, den FHEM innerhalb der [[DevelopmentModuleAPI#Dispatch|Dispatch()]]-Funktion prüft. Nur wenn eine Nachricht via Dispatch() auf diesen Audruck matcht, wird die Parse-Funktion aufgerufen um die Nachricht zu verarbeiten.

Der Hintergrund, warum man den Aufruf mit einem solchen Ausdruck vorher abprüft, liegt in der Möglichkeit, dass ein physikalisches Modul mehrere unterschiedliche logische Module ansprechen kann. So kann FHEM jedes geladene Modul durch diesen Match-Ausdruck prüfen, ob es diese Nachricht verarbeiten kann. Erst, wenn alle geladenen Module, aufgrund einer Prüfung des Ausdrucks, die Nachricht nicht verarbeiten können, wird via [[#Die_Match-Liste|Match-Liste]] ermittelt, welches Modul geladen werden muss um die Nachricht zu verarbeiten.

Der Match-Ausdruck wird in der [[#X_Initialize|Initialize]]-Funktion zur Verfügung gestellt:

<source lang="perl">
sub X_Initialize($)
{
my ($hash) = @_;

...

# Dieses Modul verarbeitet FS20 Nachrichten
$hash->{Match} = "^81..(04|0c)..0101a001";
}
</source>
=== Die vollständige Implementierung ===

Hier nun eine Zusammenfassung beim zweistufigen Modulkonzept in der jeweiligen Stufe implementiert werden muss, damit die Kommunikation funktioniert.

==== physisches Modul ====

Das physische Modul, welches als Kommunikationsbrücke zwischen der Hardware und logischen Modulen fungieren wird, sollte mindestens folgende Funktionen implementieren:

* [[#X_Initialize|Initialize]]-Funktion - Zum Registrieren des Moduls in FHEM.
* [[#X_Define|Define]]-Funktion - Zum öffnen der Datenverbindung zur Hardware (IP-Adresse/serielle Schnittstelle/...).
* [[#X_Read|Read]]-Funktion - Zum Lesen von Daten, welche die Hardware übermittelt.
* [[#X_Read|Ready]]-Funktion - Zum Wiederaufbau der Verbindung bei Verbindungsabbruch, bzw. Prüfung auf lesbare Daten bei serieller Schnittstelle unter Windows.
* [[#X_Write|Write]]-Funktion - Zum Senden von Daten, welche logische Module via [[DevelopmentModuleAPI#IOWrite|IOWrite()]] an die Hardware übertragen möchten.
* [[#X_Undef|Undef]]-Funktion - Schließen der Verbindung zur Hardware beim Löschen via <code>delete</code> bzw. <code>rereadcfg</code>.
* [[#X_Shutdown|Shutdown]]-Funktion - Schließen der Verbindung zur Hardware beim Stopp von FHEM via <code>shutdown</code>.

Desweiteren müssen in der [[#X_Initialize|Initialize]]-Funktion folgende Daten bereitgestellt werden:

* [[#Die_Client-Liste|Client-Liste]] - Auflistung aller logischen Module, die über dieses Modul kommunizieren können
* [[#Die_Match-Liste|Match-Liste]] - Zuordnung von Nachrichtensyntax zu Modul zwecks Autoload-Funktionalität.

==== logisches Modul ====

Das logische Modul, bildet ein einzelnes Gerät ab, über das mit einem physikalisches Modul kommuniziert werden kann. Es sollte mindestens folgende Funktionen implementieren:

* [[#X_Initialize|Initialize]]-Funktion - Zum Registrieren des Moduls in FHEM.
* [[#X_Define|Define]]-Funktion - Speichern des Definition Pointers (siehe [[#X_Parse|Parse-Funktion]])
* [[#X_Parse|Parse]]-Funktion - Zum Lesen von Daten, welche die Hardware übermittelt.
* [[#X_Undef|Undef]]-Funktion - Löschen des Definition Pointers beim Löschen via <code>delete</code> bzw. <code>rereadcfg</code>.

Desweiteren müssen in der [[#X_Initialize|Initialize]]-Funktion folgende Daten bereitgestellt werden:

* [[#Der_Match-Ausdruck|Match-Ausdruck]] - Prüfausdruck, ob eine Nachricht durch dieses Modul verarbeitet werden kann.

=== Kommunikation von der Hardware bis zu den logischen Modulen ===

Die Gerätedefinition eines physische Moduls öffnet eine Verbindung zur Hardware. Die [[#X_Read|Read]]-Funktion wird bei anstehenden Daten aus der Hauptschleife von fhem.pl aufgerufen.

Die Read-Funktion stellt dabei sicher, dass die Daten
* komplett (in der Regel über einen internen Puffer in <code>$hash</code>) und
* korrekt (z.B. via Prüfung mittels regulärem Ausdruck)
sind und ruft die globale Funktion [[DevelopmentModuleAPI#Dispatch|Dispatch()]] mit einer kompletten Nachricht auf.

Die Funktion Dispatch() sucht nach einer passenden Definition via [[#Die_Client-Liste|Client-Liste]] in physischen Definitionen/Modulen nach möglichen logischen Modulen zur Verarbeitung. Alle zum Zeitpunkt geladenen Module, die in der Client-Liste aufgeführt sind, werden über den [[#Der_Match-Ausdruck|Match-Ausdruck]] geprüft, ob sie mit der Nachricht etwas anfangen können. Sollte bei einem Modul der Match-Ausdruck passen, so wird die entsprechende [[#X_Parse|Parse]]-Funktion des logischen Moduls aufgerufen. Sofern keine passendes Modul gefunden wurde, um die Nachricht zu verarbeiten, wird in der [[#Die_Match-Liste|Match-Liste]] im Geräte- bzw. Modul-Hash der physischen Gerätedefinition nach dem passenden Modul gesucht. Sollte es darin ein Modul geben, was diese Art von Nachricht verarbeiten kann, so wird versucht dieses Modul zu laden um nun die Nachricht via Parse-Funktion zu verarbeiten. Es erfolgt in diesem Fall keine Vorprüfung durch den Match-Ausdruck.

Durch Dispatch() wird nun die [[#X_Parse|Parse]]-Funktion des gefundenen logischen Moduls aufgerufen. Diese
* interpretiert die übergebene Nachricht,
* versucht eine existierende Gerätedefinition in FHEM zu finden (z.B. mittels Definition Pointer), für welche die Nachricht addressiert ist,
* setzt alle [[#Readings|Readings]] für die gefundene Gerätedefinition via [[DevelopmentModuleAPI#Readings_.2F_Events|readings*update]]()-Funktionen,
* gibt den Namen der logischen Definition zurück, welche die Nachricht verarbeitet hat.

Sollte keine passende Gerätedefinition für die entsprechende Nachricht existieren (Adresse/ID/Kanal/...), wird der Gerätename "UNDEFINED" inkl. einem passenden <code>define</code>-Statement zurückgegeben, um die Definition durch [[autocreate]] erzeugen zu lassen.

Es findet während der Verarbeitung einer Nachricht durch Dispatch()/Parse-Funktion keine sofortige Eventverarbeitung (via [[DevelopmentModuleAPI#Dispatch|DoTrigger()]]) statt, wenn die [[DevelopmentModuleAPI#Readings_.2F_Events|readings*update]]()-Funktionen verwendet werden.
(Im Gegensatz zum direkten Aufrufen der readings*update Funktionen ohne vorhergehendes Dispatch() )

Die Funktion Dispatch() triggert das Event-Handling für das von der Parse-Funktion zurückgegebene logische Device selbstständig.

Optional führt die Funktion Dispatch() eine Überprüfung auf Nachrichtenduplikate beim Einsatz von mehreren IO-Geräten durch. Dazu wird eine implementierte [[#X_Fingerprint|Fingerprint]]-Funktion im physischen oder logischen Modul benötigt.

=== Kommunikation von den logischen Modulen bis zur Hardware ===

Um von einem logischen Modul eine Nachricht an die Hardware senden zu können, muss zunächst im logischen Gerät ein passenden IO-Gerät ausgewählt sein. Dazu muss die Funktion [[DevelopmentModuleAPI#AssignIoPort|AssignIoPort()]] ein entsprechendes IO-Gerät auswählen und in <code>$hash->{IODev}</code> setzen. Dieser Aufruf wird üblicherweise in der [[#X_Define|Define]]-Funktion des logischen Moduls ausgeführt. Erst, wenn ein IO-Gerät ausgewählt wurde, können Daten über das physikalische Gerät an die Hardware übermittelt werden.

Zum Senden von Daten ruft das logische Modul die Funktion [[DevelopmentModuleAPI#IOWrite|IOWrite()]] samt Daten auf. Diese ruft für das entsprechende IO-Gerät die [[#X_Write|Write]]-Funktion auf und übergibt die Daten zum Schreiben an das physikalische Modul. Die Write-Funktion kümmert sich nun um die Übertragung der Daten an die Hardware.

Keine direkten Zugriffe zwischen dem logischen und dem physischen Gerät gibt (d.h. keine direkten Aufrufe von Funktionen, kein direktes Überprüfen von <code>$hash</code>-Inhalten, ...), so können die Module hintereinander geschaltet werden (z.B. für Routerfunktionen wie bei der [[RFR_CUL|RFR]]-Funktionalität) oder mittels [[FHEM2FHEM]] im RAW-Modus zwei FHEM-Installationen verbunden werden und die logischen Geräte können dennoch kommunizieren.

=== Automatisches Anlegen von logischen Gerätedefinitionen (autocreate) ===

Das logische Modul kann im Rahmen der [[#X_Parse|Parse]]-Funktion eine neue Gerätedefinition anlegen, sofern eine passende Definition nicht existieren sollte. Die Parse-Funktion gibt generell den Namen der logischen Gerätedefinition zurück, für welche die Nachricht verarbeitet wurde. Sollte keine passende Definition gefunden werden, so muss die Parse-Funktion folgenden Rückgabewert liefern (zusammenhängende Zeichenkette):

UNDEFINED ''<Namensvorschlag>'' ''<Modulname>'' ''<Define-Parameter>''

Sollte also bspw. im Rahmen der Parse-Funktion zu Modul X eine Nachricht nicht einer existierenden Gerätedefinition zugeordnet werden können, so muss ein Namensvorschlag erstellt werden der eine eindeutige Komponente wie bspw. eine Adresse/ID/Kanal-Nr enthält. In der Regel wird hier immer der Modulname zusammen mit der eindeutigen Komponente, durch einen Unterstrich getrennt, verwendet (Bsp: <code>X_4834</code>). Der Modulname ist in der Regel immer der, des eigenen Moduls. In besonderen Fällen kann man hier auch einen abweichenden Modulnamen angeben. Dies wird bspw. bei den [[PanStamp#FHEM-Module.2FDevice_Definition_Files|SWAP-Modulen]] eingesetzt. Als Define-Parameter müssen alle notwendigen Parameter angegeben werden, die beim Aufruf des <code>define</code>-Befehls notwendig sind, damit eine neu angelegte Gerätedefinition Nachrichten zu dieser eindeutigen Adresse Daten verarbeitet. Dazu muss mind. die eindeutige Adresse mitgegeben werden.

Beispiel für FS20:

UNDEFINED FS20_0ae42f8 FS20 0ae42 f8

Sobald [[DevelopmentModuleAPI#Dispatch|Dispatch()]] einen solchen Rückgabewert von einer [[#X_Parse|Parse]]-Funktion erhält, wird diese Zeichenkette so wie sie ist via [[DevelopmentModuleAPI#DoTrigger|DoTrigger()]] als Event für die Definition <code>global</code> getriggert.

Sofern der Nutzer das Modul [[autocreate]] verwendet (definiert hat), kümmert sich dieses nun um das Anlegen einer entsprechenden Gerätedefinition. Es lauscht dabei auf generierte Events der Definition <code>global</code> via [[#X_Notify|Notify]]-Funktion. Der Nutzer kann dabei das Verhalten von autocreate durch entsprechende Parameter beeinflussen.

Das Modul, für welches autocreate eine neue Definition anlegen möchte, kann das Verhalten durch entsprechende Parameter im Modul-Hash beeinflussen. Dabei gilt, dass gesetzte Attribute durch den Nutzer generell Vorrang haben. Die entsprechenden Parameter werden dabei im Rahmen der [[#X_Initialize|Initialize]]-Funktion im Modul-Hash gesetzt:

<source lang="perl">
sub X_Initialize($)
{
my ($hash) = @_;

...

$hash->{AutoCreate} = {"X_.*" => { ATTR => "event-on-change-reading:.* event-min-interval:.*:300",
FILTER => "%NAME",
GPLOT => "temp4hum4:Temp/Hum,",
autocreateThreshold => "2:140"
}
};

}
</source>

Hierbei wird unterhalb von <code>$hash->{AutoCreate}</code> eine Liste angelegt, wo einem regulären Ausdruck für einen anzulegenden Definitionsnamen entsprechende Optionen zugeordnet werden. Sobald durch autocreate eine Gerätedefintion angelegt wird, auf den ein hier gelisteter Ausdruck matcht, so werden die zugeordneten Optionen berücksichtigt.

Hier eine Auflistung aller möglichen Optionen und ihrer Bedeutung:

{| class="wikitable"
|-
! Optionsname !! Beispiel !! Bedeutung
|-
| <code>ATTR</code>|| <code>"event-on-change-reading:.* event-min-interval:.*:300"</code> || Eine Auflistung von Attributen, die nach dem Anlegen einer Definition zusätzlich gesetzt werden. Es handelt sich hierbei um eine Leerzeichen-separierte Liste von Doppelpunkt-getrennten Tupels mit Attributname und -wert.

Für das dargestellte Beispiel bedeutet dies, dass nach dem Anlegen der Definition folgende FHEM-Befehle zusätzlich ausgeführt werden:

attr ''<Name>'' event-on-change-reading .*
attr ''<Name>'' event-min-interval .*:300

|-
| <code>FILTER</code> || <code>%NAME</code>|| Sofern in der autocreate-Definiton das Attribut <code>filelog</code> entsprechend durch den Nutzer gesetzt ist, wird eine zugehörige FileLog-Definition angelegt. Diese Option setzt den dabei benutzten Filter-Regexp, der beim Anlegen der FileLog-Definition gesetzt wird.

Dabei werden folgende Platzhalter durch die entsprechenden Werte der neu angelegten Gerätedefinition ersetzt:

* <code>%NAME</code> - wird ersetzt durch den Definitionsnamen
* <code>%TYPE</code> - wird ersetzt durch den Modulnamen
|-
| <code>GPLOT</code> || <code>"temp4hum4:Temp/Hum,"</code> || Sofern eine FileLog-Definition angelegt wurde, kann man weiterführend dazu eine passende SVG-Definition erzeugen um Daten aus dem erzeugten FileLog zu visualisieren. Ein typischer Fall sind hierbei Temperatursensoren, wo es sinnvoll sein kann, einen passenden SVG-Plot mit Temperatur/Luftfeuchtigkeit direkt anzulegen.

Es handelt sich hierbei um eine kommaseparierte Auflistung von gplot-Dateinamen und optionalen Label-Texten durch einen Doppelpunkt getrennt. Im genannten Beispiel entspricht <code>temp4hum4</code> der zu verwendenden GnuPlot-Datei und <code>Temp/Hum</code> dem zu verwendenden Label ([[SVG]] Attribut <code>label</code>). Das Label wird auch durch FileLog verwendet als Link-Text zum entsprechenden SVG Plot. Alternativ kann auch nur die entsprechende GnuPlot-Datei anegeben werden ohne Label. Für jede angegebene GnuPlot-Datei wird anschließend eine entsprechende SVG-Definition erzeugt mit der vorher erzeugten FileLog-Definition als Datenquelle.

Der gesamte Inhalt der <code>GPLOT</code>-Option wird beim Anlegen einer FileLog-Definition dem Attribut <code>logtype</code> als Wert plus dem Text <code>text</code> zugewiesen. Daher muss der Inhalt der Option <code>GPLOT</code> immer mit einem Komma enden.

|-
| <code>autocreateThreshold</code>|| <code>"2:10"|| Definiert, wie viele Aufrufe (im Bsp: <code>2</code>) von autocreate innerhalb welcher Zeit (im Bsp: <code>10</code> Sek.) stattfinden müssen, bevor die Gerätedefinition tatsächlich durch autocreate angelegt wird. Dadurch kann das ungewollte Anlegen von Geräten verhindert werden die tatsächlich nicht in Echt existieren. Aufgrund von Funkstörungen kann es durchaus zum ungewollten Anlegen einer Definition kommen. Diese Funktion lässt eine Definition erst zu wenn innerhalb einer vorgegeben Zeit eine Mindestzahl an Nachrichten eintrifft.

Die erste Zahl stellt dabei die Mindestanzahl an Nachrichten dar. Die Zweite Zahl stellt die Zeit in Sekunden dar, in der die Mindestanzahl an Nachrichten erreicht werden muss um eine entsprechende Gerätedefinition anzulegen.

Sofern diese Option nicht gesetzt ist, wird standardmäßig <code>2:60</code> verwendet.

Diese Option kann durch den Anwender über das Attribut <code>autocreateThreshold</code> übersteuert werden.

Sofern diese Option nicht gesetzt ist
|-
| <code>noAutocreatedFilelog</code>|| <code>1</code>|| Flag. Sofern gesetzt, wird keine FileLog- und ggf. SVG-Definition erzeugt. Selbst wenn der Nutzer durch entsprechende Attribute das Anlegen wünscht. Diese Option ist sinnvoll für Module bzw. Geräte die keine Readings erzeugen.
|}

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

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

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

== "Hello World" Beispiel ==

98_Hello.pm

<source lang="perl">
package main;
use strict;
use warnings;

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

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

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

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

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

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

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

return undef;
}

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

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

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

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

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

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

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

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

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

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

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

1;

=pod
=begin html

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

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

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

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

=end html

=cut
</source>

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

== Noch zu beschreiben ==
* DevIO
* AsyncOutputFn / asyncOutput

[[Kategorie:Development]]

WMBUS

2016-12-31T13:05:48Z

Kaihs: /* Bekannte Probleme */

{{Infobox Modul
|ModPurpose=Dekodierung von Wireless M-Bus Nachrichten
|ModType=d
|ModForumArea=Sonstige Systeme
|ModTechName=36_WMBUS.pm
|ModOwner=kaihs
}}
[[WMBUS]] ist ein Modul zur Dekodierung von Wireless M-Bus Nachrichten. Solche Nachrichten werden z. B. von Zählern für Wasser, Wärme, Gas und Elektrizität ausgestrahlt.
Wireless M-Bus ist ein Standardprotokoll das von unterschiedlichen Herstellern unterstützt wird.
Das Protokoll unterstützt unterschiedliche Kodierungen des Funksignals, im wesentlichen den sogenannten S-Mode und den T-Mode. Der Empfänger (z. B. ein CUL) muss den selben Modus nutzen wie der Sender (der Zähler).
Wireless M-Bus unterstützt optional die Verschlüsselung der Daten per AES.
Die von einem Zähler gesendeten Daten können sehr unterschiedlich sein und hängen u. a. vom Zählertyp und dessen Hersteller ab.

== Voraussetzungen ==
Das Modul interpretiert nur die Nachrichten die von einen geeigneten Empfänger empfangen werden. Aktuell kann ein [[CUL]] und verwandte Geräte die die culfw[http://culfw.de/culfw.html] verwenden sowie ein Amber Wireless AMB8465M dafür verwendet werden. In der culfw muss die Unterstützung des WMBUS-Protokolls aktiviert sein (#define HAS_MBUS). Bei einem CUL mit der Hardwareversion V4 ist das nicht der Fall.

Der CUL muss in fhem mittels Attribut rfmode=WMBus_S oder WMBus_T in den zum Zähler passenden Empfangsmodus versetzt werden.

== Anwendung ==
Die Erzeugung des passenden Devices in fhem geschieht automatisch beim Empfang des ersten Datenpakets eines Zählers. Voraussetzung dafür ist, dass [[autocreate]] aktiv ist.
Alternativ kann ein Device manuell angelegt werden. Dazu wird der Hersteller, die Seriennummer, die Version und der Typ (Wasser, Gas, ...) des Zählers benötigt.
Sind die Daten verschlüsselt wird auch noch der passende Schlüssel benötigt um die Daten entschlüsseln zu können.

== Anwendungsbeispiele ==
Ein per [[EnergyCam]] abgelesener Elektrizitätszähler sieht in fhem z. B. so aus:
<pre>
Internals:
CUL_MBUS_MSGCNT 29
CUL_MBUS_RAWMSG b1944C4189985051701028A7D7A540000A00405FAD4080002FD08222C1295B8::-67.5
CUL_MBUS_RSSI -67.5
CUL_MBUS_TIME 2014-10-24 22:57:53
DEF FFD 17058599 1 2
DeviceMedium Electricity
DeviceType 2
IODev CUL_MBUS
IdentNumber 17058599
LASTInputDev CUL_MBUS
MSGCNT 29
Manufacturer FFD
NAME WMBUS_FFD_17058599_1_2
NR 49
STATE no errors
TYPE WMBUS
Version 1
addr FFD_17058599_1_2
Readings:
2014-10-24 22:57:53 1_storage_no 0
2014-10-24 22:57:53 1_type VIF_ENERGY_WATT
2014-10-24 22:57:53 1_unit Wh
2014-10-24 22:57:53 1_value 57881000
2014-10-24 22:57:53 2_storage_no 0
2014-10-24 22:57:53 2_type VIF_ACCESS_NO
2014-10-24 22:57:53 2_unit
2014-10-24 22:57:53 2_value 11298
2014-10-24 22:57:53 LQI 184
2014-10-24 22:57:53 RSSI -67.5
2014-10-24 22:57:53 battery ok
2014-10-24 22:57:53 decryption_ok 1
2014-10-24 22:57:53 energy 57881
2014-10-24 22:57:53 is_encrypted 0
2014-10-24 22:57:53 state no errors
2014-10-24 22:57:53 unit kWh
Attributes:
IODev CUL_MBUS
room WMBUS
</pre>

== Bekannte Probleme ==
Obwohl Wireless M-Bus ein standardisiertes Protokoll ist, scheint sich kaum ein Hersteller vollständig daran zu halten bzw. verwendet sog. herstellerspezifische Felder um wichtige Daten zu verpacken.
Aus den bisher beobachteten Datenpaketen ergibt sich
* Qundis (Herstellerkürzel LSE) verwendet herstellerspezifische Datenblöcke für den eigentlichen Zählerstand
* Techem und Hydrometer verwenden ein undokumentiertes Datenformat (CI-Field A2)
:''(Techem Heizkostenverteiler (CI-Field A0) können über das Modul [[TechemHKV]] ausgewertet werden)''
* RWE SmartHome Powercontrol[http://www.rwe-smarthome.de/web/cms/de/1776202/smarthome/informieren/geraete/power-control/] sendet verschlüsselt und der Hersteller gibt nicht den vollständigen Schlüssel an[http://forum.fhem.de/index.php/topic,24517.msg315949.html#msg315949]

Daher werden bisher erst die [[EnergyCam]] der Firma Q-loud und Zähler von Easymeter vollständig unterstützt.

== Links ==
* Forumsthread [http://forum.fhem.de/index.php/topic,24517.0.html]
* Protokoll Beschreibung [http://oms-group.org/download4all/]
* Beschreibung des M-BUS Protokolls [http://www.m-bus.com/files/MBDOC48.PDF]
[[Kategorie:Energieverbrauchsmessung]]

EnergyCam

2016-12-31T13:04:06Z

Kaihs: Fastforward hat die Herstellung eingestellt und an die Q-loud abgegeben

{{Infobox Hardware
|Bild=EnergyCam.jpg
|Bildbeschreibung=EnergyCam mit externer Batterie und externer Antenne montiert auf einem Ferraris-Zähler
|HWProtocol=Wireless M-Bus
|HWType=Sensor
|HWCategory=Energieverbrauchsmessung
|HWComm=Funk 868MHz, ModBus
|HWChannels=N/A
|HWVoltage=3,0 - 3,6V
|HWPowerConsumption=<0,2W
|HWPoweredBy=interne CR2450 oder externe Batterie, USB
|HWSize=B x H x T 48,00 x 55,50 x 15,50 mm
|HWDeviceFHEM=WMBUS
|HWManufacturer=Q-loud
}}
Die [[EnergyCam]] ist ein Zähleraufsatz der den Zählerstand erfasst und dann drahtlos (Wireless M-Bus) oder drahtgebunden (Modbus) weiterleitet.
== Features ==
Eine EnergyCam erfasst optisch den Zählerstand eines herkömmlichen Zählers für Elektrizität, Gas oder Wasser und wandelt diesen per optischer Zeichenerkennung (OCR) in einen Zahlenwert um. Dieser Wert wird dann zyklisch versandt und kann vom Empfänger ausgewertet werden.

Die EnergyCam wird dazu auf den Zähler aufgeklebt. Das Gerät unterstützt dabei durch eine Anzeige die Montage in der richtigen Position. Für die Verwendung mit Gas- und Wasserzählern sind noch zusätzliche Adapter erforderlich.
Es gibt die EnergyCam sowohl mit interner als auch externer Antenne sowie mit interner und externer Energieversorgung.
Der aktuelle Zählerstand kann bei Bedarf auch direkt am Gerät abgelesen werden und wird auf dem internen Display dargestellt.

== Hinweise zum Betrieb mit FHEM ==
Die EnergyCam im Wireless M-Bus Modus wird vom Modul [[WMBUS]] vollständig unterstützt. Das Herstellerkürzel ist FFD.

== Bekannte Probleme ==
Die Erfassung der Zählerstands erfolgt von schräg unterhalb des eigentlichen Zählwerks. Daher darf dieser Bereich nicht durch Aufdruck oder ähnliches die freie Sicht auf das Zählwerk behindern, sonst ist keine fehlerfreie Erfassung möglich.

== Links ==
* Herstellerseite [https://q-loud.de/solucon/solucon-hardware/]
[[Kategorie:Energieverbrauchsmessung]]
[[Kategorie:Other Components]]

WMBUS

2016-11-13T17:33:31Z

Kaihs: Amber Wireless AMB8465M

{{Infobox Modul
|ModPurpose=Dekodierung von Wireless M-Bus Nachrichten
|ModType=d
|ModForumArea=Sonstige Systeme
|ModTechName=36_WMBUS.pm
|ModOwner=kaihs
}}
[[WMBUS]] ist ein Modul zur Dekodierung von Wireless M-Bus Nachrichten. Solche Nachrichten werden z. B. von Zählern für Wasser, Wärme, Gas und Elektrizität ausgestrahlt.
Wireless M-Bus ist ein Standardprotokoll das von unterschiedlichen Herstellern unterstützt wird.
Das Protokoll unterstützt unterschiedliche Kodierungen des Funksignals, im wesentlichen den sogenannten S-Mode und den T-Mode. Der Empfänger (z. B. ein CUL) muss den selben Modus nutzen wie der Sender (der Zähler).
Wireless M-Bus unterstützt optional die Verschlüsselung der Daten per AES.
Die von einem Zähler gesendeten Daten können sehr unterschiedlich sein und hängen u. a. vom Zählertyp und dessen Hersteller ab.

== Voraussetzungen ==
Das Modul interpretiert nur die Nachrichten die von einen geeigneten Empfänger empfangen werden. Aktuell kann ein [[CUL]] und verwandte Geräte die die culfw[http://culfw.de/culfw.html] verwenden sowie ein Amber Wireless AMB8465M dafür verwendet werden. In der culfw muss die Unterstützung des WMBUS-Protokolls aktiviert sein (#define HAS_MBUS). Bei einem CUL mit der Hardwareversion V4 ist das nicht der Fall.

Der CUL muss in fhem mittels Attribut rfmode=WMBus_S oder WMBus_T in den zum Zähler passenden Empfangsmodus versetzt werden.

== Anwendung ==
Die Erzeugung des passenden Devices in fhem geschieht automatisch beim Empfang des ersten Datenpakets eines Zählers. Voraussetzung dafür ist, dass [[autocreate]] aktiv ist.
Alternativ kann ein Device manuell angelegt werden. Dazu wird der Hersteller, die Seriennummer, die Version und der Typ (Wasser, Gas, ...) des Zählers benötigt.
Sind die Daten verschlüsselt wird auch noch der passende Schlüssel benötigt um die Daten entschlüsseln zu können.

== Anwendungsbeispiele ==
Ein per [[EnergyCam]] abgelesener Elektrizitätszähler sieht in fhem z. B. so aus:
<pre>
Internals:
CUL_MBUS_MSGCNT 29
CUL_MBUS_RAWMSG b1944C4189985051701028A7D7A540000A00405FAD4080002FD08222C1295B8::-67.5
CUL_MBUS_RSSI -67.5
CUL_MBUS_TIME 2014-10-24 22:57:53
DEF FFD 17058599 1 2
DeviceMedium Electricity
DeviceType 2
IODev CUL_MBUS
IdentNumber 17058599
LASTInputDev CUL_MBUS
MSGCNT 29
Manufacturer FFD
NAME WMBUS_FFD_17058599_1_2
NR 49
STATE no errors
TYPE WMBUS
Version 1
addr FFD_17058599_1_2
Readings:
2014-10-24 22:57:53 1_storage_no 0
2014-10-24 22:57:53 1_type VIF_ENERGY_WATT
2014-10-24 22:57:53 1_unit Wh
2014-10-24 22:57:53 1_value 57881000
2014-10-24 22:57:53 2_storage_no 0
2014-10-24 22:57:53 2_type VIF_ACCESS_NO
2014-10-24 22:57:53 2_unit
2014-10-24 22:57:53 2_value 11298
2014-10-24 22:57:53 LQI 184
2014-10-24 22:57:53 RSSI -67.5
2014-10-24 22:57:53 battery ok
2014-10-24 22:57:53 decryption_ok 1
2014-10-24 22:57:53 energy 57881
2014-10-24 22:57:53 is_encrypted 0
2014-10-24 22:57:53 state no errors
2014-10-24 22:57:53 unit kWh
Attributes:
IODev CUL_MBUS
room WMBUS
</pre>

== Bekannte Probleme ==
Obwohl Wireless M-Bus ein standardisiertes Protokoll ist, scheint sich kaum ein Hersteller vollständig daran zu halten bzw. verwendet sog. herstellerspezifische Felder um wichtige Daten zu verpacken.
Aus den bisher beobachteten Datenpaketen ergibt sich
* Qundis (Herstellerkürzel LSE) verwendet herstellerspezifische Datenblöcke für den eigentlichen Zählerstand
* Techem und Hydrometer verwenden ein undokumentiertes Datenformat (CI-Field A2)
:''(Techem Heizkostenverteiler (CI-Field A0) können über das Modul [[TechemHKV]] ausgewertet werden)''
* RWE SmartHome Powercontrol[http://www.rwe-smarthome.de/web/cms/de/1776202/smarthome/informieren/geraete/power-control/] sendet verschlüsselt und der Hersteller gibt nicht den vollständigen Schlüssel an[http://forum.fhem.de/index.php/topic,24517.msg315949.html#msg315949]

Daher werden bisher erst die [[EnergyCam]] der Fast Forward AG und Zähler von Easymeter vollständig unterstützt.

== Links ==
* Forumsthread [http://forum.fhem.de/index.php/topic,24517.0.html]
* Protokoll Beschreibung [http://oms-group.org/download4all/]
* Beschreibung des M-BUS Protokolls [http://www.m-bus.com/files/MBDOC48.PDF]
[[Kategorie:Energieverbrauchsmessung]]

HM-LC-Sw1PBU-FM Alternative Firmware am Raspi bauen u. flashen

2016-11-13T16:53:42Z

Kaihs: Typo

= 1fach Schaltaktor HM-LC-Sw1PBU-FM mit alternativer Firmware =
* Sinn und Zweck: Der Schalter bietet mit der alternativen Firmware die Möglichkeit ihn in Wechselschaltungen zu integrieren. In einer normalen Wechselschaltung ist es nicht möglich, den Schaltzustand der Lampe zu erkennen. Das Funktioniert nur wenn der Schaltzustand(Leistungsaufnahme) von Funkschalter erkannt werden kann.
* Vorwort: Dieser Artikel ist eigentlich nur eine Zusammenfassung dessen, was bereits in [[HM-LC-Sw1PBU-FM_Alternative_Firmware#Bootloader_flashen | HM-LC-Sw1PBU-FM_Alternative_Firmware#Bootloader_flashen]] steht! Dort stammen auch alle Tools, Hilfsprogramme und Informationen her.
Ich habe lediglich alles auf das Flashen am Raspberry Pi ausgerichtet. Mein Dank gilt den Programmierern der Firmware und allen Leuten, die das Projekt mit- und weiterentwickelt haben.

== Vorbereitung ==
* Windows 7 Desktop-Rechner mit Browser, Text-Editor, puTTY und WinSCP. Man kann zwar alle Schritte auch direkt auf dem Raspi durchführen - ich finde den Windows-Rechner aber praktischer
* Raspbian Jessie mit Pixel downloaden [https://www.raspberrypi.org/downloads/raspbian/]. Kernel 4.4 Release 2016 09 23
** Mit WinDiskImager auf min. 8GB SD-Karte spielen, s. auch [http://www.raspberry-projects.com/pi/pi-operating-systems/win32diskimager]
* Raspberry Pi 2B
** Die Pins des Raspi müssen nach folgendem Schema mit den Lötpads des HM-LC-Sw1PBU-FM verbunden werden. Die Messpunkte (MP) befinden sich auf der inneren, festgeschraubten, Platine des HM-Schalters
[[Raspberry Pi|Raspberry]] PIN | Beschreibung | HM-LC-Sw1PBU-FM
--------------|--------------|----------------
Pin #17 | 3,3V | MP2
Pin #19 | MOSI | MP4
Pin #21 | MISO | MP5
Pin #23 | SCLK | MP6
Pin #24 | Reset | MP3
Pin #25 | GND | MP15
** Hinweis: Den Schalter während des gesamten Prozesses '''nicht mit 230V verbinden'''. Während des gesamtem Flash-Vorgangs kann die Spannungsvorsorgung aus dem Raspi genutzt werden
* Nachdem Raspbian sich installiert hat, geht man auf die Linux-Konsole. Entweder direkt oder per puTTY über SSH. Auf dem Raspi arbeite ich gerne als User root, deswegen vergebe ich diesem ein Passwort:
<pre>
sudo passwd root
// user root werden
su - root
</pre>
* Raspi OS updaten
<pre>
apt-get update && apt-get upgrade && apt-get dist-upgrade
</pre>
* Software installieren: C-Compiler, arduino-IDE
<pre>
apt-get install arduino gcc-avr
</pre>

* (Optional) Über ''raspi-config -> Internationialisation Options'' Keyboard-Layout, Locale, Timezone anpassen
* Über ''raspi-config -> Advanced Options'' SPI, Serial, I2C ausschalten (falls aktiv)
* reboot
* Verzeichnis für Downloads auf dem Raspi erstellen und dorthin wechseln
<pre>
mkdir /root/hm_switch
mkdir /root/hm_switch/flash
cd /root/hm_switch
</pre>
* Bootloader-Umgebung herunterladen
<pre>
git clone https://github.com/jabdoa2/Asksin_OTA_Bootloader
</pre>
* Firmware herunterladen
<pre>
git clone https://github.com/jabdoa2/Asksin_HM_LC_Sw1PBU_FM
</pre>
* Dateien aus [https://seafile.partec.org/d/b6590a5a45/] herunterladen und auf dem Raspi in's erstellte Verzeichnis ''/root/hm_switch'' kopieren. Da ich nicht weiß, wie man per wget Dateien eines Cloud-Servers auf einer Linux-Maschine kopiert, führe ich diesen Vorgang mit WinSCP durch.
** Das Modul 99_Asksin_HM_LC_Sw1PBU_FM_CustomFW.pm muss in die fhem-Installation (/opt/fhem/FHEM) kopiert werden. Ansonsten wird der Schalter beim '''Anlernen nicht erkannt'''
* Da die Programming-Software aus dem original Repository nicht verwendet werden kann, muss die Version aus dem Dowload installiert werden
<pre>
dpkg -i avrdude_5.10-4_armhf.deb
</pre>
* In der .conf steht die Definition der Anschlüsse für den Raspi. Diese entpacken und nach /etc kopieren
<pre>
gunzip avrdude.conf.gz && cp avrdude.conf /etc/
</pre>

==Arduino-IDE einrichten /Firmware bauen==
* Die IDE wird zum späteren Kompilieren der Firmware benötigt - es ist keine Arduino-Hardware erforderlich!
* Build-Pfad für Arduino-IDE erstellen:
<pre>
mkdir /home/pi/build && chmod -R 777 /home/pi/build
</pre>
* In den Ordner ''/usr/share/arduino/hardware'' wechseln und Hardware-Board für den ATMega644 laden
<pre>
cd /usr/share/arduino/hardware
git clone https://github.com/jabdoa2/jabduino
</pre>
* Um alle Pfade und Dateien zu erzeugen, muss die Arduino-IDE aufgerufen und anschließend direkt wieder geschlossen werden. Das kann man in der grafischen Umgebung des Raspis, oder über ein entferntes X-Terminal tun.
* In manchen Adruino-IDE Umgebungen werden Builds gelöscht, bevor sie auf die Hardware gespielt werden. Das muss verhindert werden! Bei Raspbian Jessie und dem User pi befinden sich die Voreinstellungen der IDE in ''/home/pi/.arduino/preferences.txt''. Über die Konsole dort folgende Änderungen machen, bzw. Einträge hinzufügen
<pre>
...
build.path=/home/pi/build
...
export.delete_target_folder=false
...
preproc.save_build_files=true
...
</pre>
* Firmware-Quellen in den Sketchbook-Ordner von User ''pi'' kopieren und Rechte für alle setzen
<pre>
cp -R /root/hm_switch/Asksin_HM_LC_Sw1PBU_FM/ /home/pi/sketchbook/ && chmod -R 777 /home/pi/sketchbook/
</pre>
* Wieder in die grafische IDE wechseln
** ''Tools -> Board ->'' "Jabduino ATmega644A" auswählen
** ''File -> Sketchbook -> '' "Asksin_HM_LC_Sw1PBU_FM" öffnen
** In der Datei Asksin_HM_LC_Sw1PBU_FM den Wert in Zeile 64 eventuell "const unsigned long minImpulsLength = 5000;" ändern. Der dort eingetragene Wert gilt als Schwellwert, wann der Schalter erkennen soll, dass ein angeschlossener Wechselschalter gedrückt wurde und somit erkannt wird, dass Strom fließt.
** In der Datei ''Register.h'' in Zeile 22 den Wert von HMID[3] ändern.
Zusätzlich kann die eigene Zentrale bereits als Default-Wert in den Schalter eingetragen werden. Dadurch entfällt ein unter Umständen notwendiges Peering. Dafür muss die Zeile 347 von //#define firstLoad' in '#define firstLoad' geändert werden In den Zeilen 354 bis 356 die Werte für die FHEM-Zentral-ID einfügen (Reading: D-HMIdOriginal 2CC71D) reg.ch_0.pairCentral[0] = 0x2C; reg.ch_0.pairCentral[1] = 0xC7; reg.ch_0.pairCentral[2] = 0x1D; Auch andere Default-Werte wie Peerings und Schaltverhalten können an dieser Stelle verändert werden. Sollte das nicht gewünscht sein, sind diese Zeilen entweder auszukommentieren oder einfach zu löschen.
** Beispiel (Auszug aus Register.h mit Zeilenangaben)
<pre>
<16>/* Serial ID 10 byte */ 'K','E','Q','0','0','0','0','0','0','7', // serial ID, needed for pairing
<22> const uint8_t HMID[3] = { 0x08, 0x15, 0x07 }; // 081507
</pre>
** Die beiden geänderten Dateien speichern und mit ''Sketch -> Überprüfen / Kompilieren'' kompilieren. Im unteren Fenster auf Fehlermeldungen achten!
** Wenn dies funktioniert hat, sollte im Ordner ''/home/pi/build'' die Datei ''Asksin_HM_LC_Sw1PBU_FM.cpp.hex'' mit aktuellem Datum erzeugt worden sein.

== Bootloader ==
* Datei /root/hm_switch/Asksin_OTA_Bootloader/devices/HM-LC-Sw1PBU-FM.h editieren und dabei Seriennummer, HMID und die Typ setzen. Seriennummer und HMID müssen in eurer Umgebung eindeutig sein, Typ ist: '''0xF0A9'''
<pre>
nano /root/hm_switch/Asksin_OTA_Bootloader/devices/HM-LC-Sw1PBU-FM.h
</pre>
** Beispiel: HMID -> 081507, Seriennummer: KEQ0000007
<pre>
/ The model type (not used from bootloader)
#define HM_TYPE 0xF0, 0xA9
// 10 bytes serial number. Must be unique for each device
#define HM_SERIAL 'K', 'E', 'Q', '0', '0', '0', '0', '0', '0', '7'
// 3 bytes The device address (hm_id)
#define HM_ID 0x08, 0x15, 0x07
</pre>
* Eine Verzeichnisebene höher und Bootloader bauen:
<pre>
cd /root/hm_switch/Asksin_OTA_Bootloader/
make clean HM_LC_Sw1PBU_FM_8k
</pre>
Dabei sollte die Datei ''bootloader_HM-LC-Sw1PBU-FM.hex'' herauskommen. Diese wird später auf den Schalter geflasht

== Flashen ==
* Erzeugte Bootloader-Datei und Firmware in ein Verzeichnis kopieren:
<pre>
cp /home/pi/build/Asksin_HM_LC_Sw1PBU_FM.cpp.hex /root/hm_switch/flash/firmware.hex && cp /root/hm_switch/Asksin_OTA_Bootloader/Bootloader-AskSin-OTA-HM_LC_Sw1PBU_FM_8k.hex /root/hm_switch/flash/bootloader.hex
cd /root/hm_switch/flash/
</pre>
* Hinweis: In älteren Beschreibungen findet man häufig die Ziel-Plattform m644. Diese Unterscheidet sich praktisch in der Stromaufnahme des Chips, führt beim avrdude aber zu '''Fehlermeldungen''', deshalb auf '''m6444p''' achten
* '''Fuses''' setzen
''avrdude -p m644p -P gpio -c gpio -U lfuse:w:0xFD:m -U hfuse:w:0xD8:m -U lock:w:0x3F:m''
<pre>
avrdude: AVR device initialized and ready to accept instructions
Reading | ################################################## | 100% 0.00s
avrdude: Device signature = 0x1e960a
avrdude: reading input file "0xFD"
avrdude: writing lfuse (1 bytes):
Writing | ################################################## | 100% 0.00s
avrdude: 1 bytes of lfuse written
avrdude: verifying lfuse memory against 0xFD:
avrdude: load data lfuse data from input file 0xFD:
avrdude: input file 0xFD contains 1 bytes
avrdude: reading on-chip lfuse data:
Reading | ################################################## | 100% 0.00s
avrdude: verifying ...
avrdude: 1 bytes of lfuse verified
avrdude: reading input file "0xD8"
avrdude: writing hfuse (1 bytes):
Writing | ################################################## | 100% 0.00s
avrdude: 1 bytes of hfuse written
avrdude: verifying hfuse memory against 0xD8:
avrdude: load data hfuse data from input file 0xD8:
avrdude: input file 0xD8 contains 1 bytes
avrdude: reading on-chip hfuse data:
Reading | ################################################## | 100% 0.00s
avrdude: verifying ...
avrdude: 1 bytes of hfuse verified
avrdude: safemode: Fuses OK
avrdude done. Thank you.
</pre>
* '''Bootloader''' flashen
''avrdude -p m644p -P gpio -c gpio -U flash:w:bootloader.hex''
<pre>
avrdude: AVR device initialized and ready to accept instructions
Reading | ################################################## | 100% 0.00s
avrdude: Device signature = 0x1e960a
avrdude: NOTE: FLASH memory has been specified, an erase cycle will be performed
To disable this feature, specify the -D option.
avrdude: erasing chip
avrdude: reading input file "bootloader_HM-LC-Sw1PBU-FM.hex"
avrdude: input file bootloader_HM-LC-Sw1PBU-FM.hex auto detected as Intel Hex
avrdude: writing flash (61372 bytes):
Writing | ################################################## | 100% 30.86s
avrdude: 61372 bytes of flash written
avrdude: verifying flash memory against bootloader_HM-LC-Sw1PBU-FM.hex:
avrdude: load data flash data from input file bootloader_HM-LC-Sw1PBU-FM.hex:
avrdude: input file bootloader_HM-LC-Sw1PBU-FM.hex auto detected as Intel Hex
avrdude: input file bootloader_HM-LC-Sw1PBU-FM.hex contains 61372 bytes
avrdude: reading on-chip flash data:
Reading | ################################################## | 100% 28.95s
avrdude: verifying ...
avrdude: 61372 bytes of flash verified
avrdude: safemode: Fuses OK
avrdude done. Thank you.
</pre>
* '''Firmware''' flashen (aus der Arduino-IDE)
''avrdude -p m644p -P gpio -c gpio -U flash:w:firmware.hex''
<pre>
avrdude: AVR device initialized and ready to accept instructions
Reading | ################################################## | 100% 0.00s
avrdude: Device signature = 0x1e960a
avrdude: NOTE: FLASH memory has been specified, an erase cycle will be performed
To disable this feature, specify the -D option.
avrdude: erasing chip
avrdude: reading input file "Asksin_HM_LC_Sw1PBU_FM.cpp.hex"
avrdude: input file Asksin_HM_LC_Sw1PBU_FM.cpp.hex auto detected as Intel Hex
avrdude: writing flash (19042 bytes):
Writing | ################################################## | 100% 9.79s
avrdude: 19042 bytes of flash written
avrdude: verifying flash memory against Asksin_HM_LC_Sw1PBU_FM.cpp.hex:
avrdude: load data flash data from input file Asksin_HM_LC_Sw1PBU_FM.cpp.hex:
avrdude: input file Asksin_HM_LC_Sw1PBU_FM.cpp.hex auto detected as Intel Hex
avrdude: input file Asksin_HM_LC_Sw1PBU_FM.cpp.hex contains 19042 bytes
avrdude: reading on-chip flash data:
Reading | ################################################## | 100% 9.28s
avrdude: verifying ...
avrdude: 19042 bytes of flash verified
avrdude: safemode: Fuses OK
avrdude done. Thank you.
</pre>

[[Kategorie:HomeMatic Components]]
[[Kategorie:Schalter (Sender)]]
[[Kategorie:Schalter (Empfänger)]]

HM-LC-Sw1PBU-FM Alternative Firmware am Raspi bauen u. flashen

2016-11-13T16:53:16Z

Kaihs: Typo

= 1fach Schaltaktor HM-LC-Sw1PBU-FM mit alternativer Firmware =
* Sinn und Zweck: Der Schalter bietet mit der alternativen Firmware die Möglichkeit ihn in Wechselschaltungen zu integrieren. In einer normalen Wechselschaltung ist es nicht möglich, den Schaltzustand der Lampe zu erkennen. Das Funktioniert nur wenn der Schaltzustand(Leistungsaufnahme) von Funkschalter erkannt werden kann.
* Vorwort: Dieser Artikel ist eigentlich nur eine Zusammenfassung dessen, was bereits in [[HM-LC-Sw1PBU-FM_Alternative_Firmware#Bootloader_flashen | HM-LC-Sw1PBU-FM_Alternative_Firmware#Bootloader_flashen]] steht! Dort stammen auch alle Tools, Hilfsprogramme und Informationen her.
Ich habe ledigleich alles auf das Flashen am Raspberry Pi ausgerichtet. Mein Dank gilt den Programmierern der Firmware und allen Leuten, die das Projekt mit- und weiterentwickelt haben.

== Vorbereitung ==
* Windows 7 Desktop-Rechner mit Browser, Text-Editor, puTTY und WinSCP. Man kann zwar alle Schritte auch direkt auf dem Raspi durchführen - ich finde den Windows-Rechner aber praktischer
* Raspbian Jessie mit Pixel downloaden [https://www.raspberrypi.org/downloads/raspbian/]. Kernel 4.4 Release 2016 09 23
** Mit WinDiskImager auf min. 8GB SD-Karte spielen, s. auch [http://www.raspberry-projects.com/pi/pi-operating-systems/win32diskimager]
* Raspberry Pi 2B
** Die Pins des Raspi müssen nach folgendem Schema mit den Lötpads des HM-LC-Sw1PBU-FM verbunden werden. Die Messpunkte (MP) befinden sich auf der inneren, festgeschraubten, Platine des HM-Schalters
[[Raspberry Pi|Raspberry]] PIN | Beschreibung | HM-LC-Sw1PBU-FM
--------------|--------------|----------------
Pin #17 | 3,3V | MP2
Pin #19 | MOSI | MP4
Pin #21 | MISO | MP5
Pin #23 | SCLK | MP6
Pin #24 | Reset | MP3
Pin #25 | GND | MP15
** Hinweis: Den Schalter während des gesamten Prozesses '''nicht mit 230V verbinden'''. Während des gesamtem Flash-Vorgangs kann die Spannungsvorsorgung aus dem Raspi genutzt werden
* Nachdem Raspbian sich installiert hat, geht man auf die Linux-Konsole. Entweder direkt oder per puTTY über SSH. Auf dem Raspi arbeite ich gerne als User root, deswegen vergebe ich diesem ein Passwort:
<pre>
sudo passwd root
// user root werden
su - root
</pre>
* Raspi OS updaten
<pre>
apt-get update && apt-get upgrade && apt-get dist-upgrade
</pre>
* Software installieren: C-Compiler, arduino-IDE
<pre>
apt-get install arduino gcc-avr
</pre>

* (Optional) Über ''raspi-config -> Internationialisation Options'' Keyboard-Layout, Locale, Timezone anpassen
* Über ''raspi-config -> Advanced Options'' SPI, Serial, I2C ausschalten (falls aktiv)
* reboot
* Verzeichnis für Downloads auf dem Raspi erstellen und dorthin wechseln
<pre>
mkdir /root/hm_switch
mkdir /root/hm_switch/flash
cd /root/hm_switch
</pre>
* Bootloader-Umgebung herunterladen
<pre>
git clone https://github.com/jabdoa2/Asksin_OTA_Bootloader
</pre>
* Firmware herunterladen
<pre>
git clone https://github.com/jabdoa2/Asksin_HM_LC_Sw1PBU_FM
</pre>
* Dateien aus [https://seafile.partec.org/d/b6590a5a45/] herunterladen und auf dem Raspi in's erstellte Verzeichnis ''/root/hm_switch'' kopieren. Da ich nicht weiß, wie man per wget Dateien eines Cloud-Servers auf einer Linux-Maschine kopiert, führe ich diesen Vorgang mit WinSCP durch.
** Das Modul 99_Asksin_HM_LC_Sw1PBU_FM_CustomFW.pm muss in die fhem-Installation (/opt/fhem/FHEM) kopiert werden. Ansonsten wird der Schalter beim '''Anlernen nicht erkannt'''
* Da die Programming-Software aus dem original Repository nicht verwendet werden kann, muss die Version aus dem Dowload installiert werden
<pre>
dpkg -i avrdude_5.10-4_armhf.deb
</pre>
* In der .conf steht die Definition der Anschlüsse für den Raspi. Diese entpacken und nach /etc kopieren
<pre>
gunzip avrdude.conf.gz && cp avrdude.conf /etc/
</pre>

==Arduino-IDE einrichten /Firmware bauen==
* Die IDE wird zum späteren Kompilieren der Firmware benötigt - es ist keine Arduino-Hardware erforderlich!
* Build-Pfad für Arduino-IDE erstellen:
<pre>
mkdir /home/pi/build && chmod -R 777 /home/pi/build
</pre>
* In den Ordner ''/usr/share/arduino/hardware'' wechseln und Hardware-Board für den ATMega644 laden
<pre>
cd /usr/share/arduino/hardware
git clone https://github.com/jabdoa2/jabduino
</pre>
* Um alle Pfade und Dateien zu erzeugen, muss die Arduino-IDE aufgerufen und anschließend direkt wieder geschlossen werden. Das kann man in der grafischen Umgebung des Raspis, oder über ein entferntes X-Terminal tun.
* In manchen Adruino-IDE Umgebungen werden Builds gelöscht, bevor sie auf die Hardware gespielt werden. Das muss verhindert werden! Bei Raspbian Jessie und dem User pi befinden sich die Voreinstellungen der IDE in ''/home/pi/.arduino/preferences.txt''. Über die Konsole dort folgende Änderungen machen, bzw. Einträge hinzufügen
<pre>
...
build.path=/home/pi/build
...
export.delete_target_folder=false
...
preproc.save_build_files=true
...
</pre>
* Firmware-Quellen in den Sketchbook-Ordner von User ''pi'' kopieren und Rechte für alle setzen
<pre>
cp -R /root/hm_switch/Asksin_HM_LC_Sw1PBU_FM/ /home/pi/sketchbook/ && chmod -R 777 /home/pi/sketchbook/
</pre>
* Wieder in die grafische IDE wechseln
** ''Tools -> Board ->'' "Jabduino ATmega644A" auswählen
** ''File -> Sketchbook -> '' "Asksin_HM_LC_Sw1PBU_FM" öffnen
** In der Datei Asksin_HM_LC_Sw1PBU_FM den Wert in Zeile 64 eventuell "const unsigned long minImpulsLength = 5000;" ändern. Der dort eingetragene Wert gilt als Schwellwert, wann der Schalter erkennen soll, dass ein angeschlossener Wechselschalter gedrückt wurde und somit erkannt wird, dass Strom fließt.
** In der Datei ''Register.h'' in Zeile 22 den Wert von HMID[3] ändern.
Zusätzlich kann die eigene Zentrale bereits als Default-Wert in den Schalter eingetragen werden. Dadurch entfällt ein unter Umständen notwendiges Peering. Dafür muss die Zeile 347 von //#define firstLoad' in '#define firstLoad' geändert werden In den Zeilen 354 bis 356 die Werte für die FHEM-Zentral-ID einfügen (Reading: D-HMIdOriginal 2CC71D) reg.ch_0.pairCentral[0] = 0x2C; reg.ch_0.pairCentral[1] = 0xC7; reg.ch_0.pairCentral[2] = 0x1D; Auch andere Default-Werte wie Peerings und Schaltverhalten können an dieser Stelle verändert werden. Sollte das nicht gewünscht sein, sind diese Zeilen entweder auszukommentieren oder einfach zu löschen.
** Beispiel (Auszug aus Register.h mit Zeilenangaben)
<pre>
<16>/* Serial ID 10 byte */ 'K','E','Q','0','0','0','0','0','0','7', // serial ID, needed for pairing
<22> const uint8_t HMID[3] = { 0x08, 0x15, 0x07 }; // 081507
</pre>
** Die beiden geänderten Dateien speichern und mit ''Sketch -> Überprüfen / Kompilieren'' kompilieren. Im unteren Fenster auf Fehlermeldungen achten!
** Wenn dies funktioniert hat, sollte im Ordner ''/home/pi/build'' die Datei ''Asksin_HM_LC_Sw1PBU_FM.cpp.hex'' mit aktuellem Datum erzeugt worden sein.

== Bootloader ==
* Datei /root/hm_switch/Asksin_OTA_Bootloader/devices/HM-LC-Sw1PBU-FM.h editieren und dabei Seriennummer, HMID und die Typ setzen. Seriennummer und HMID müssen in eurer Umgebung eindeutig sein, Typ ist: '''0xF0A9'''
<pre>
nano /root/hm_switch/Asksin_OTA_Bootloader/devices/HM-LC-Sw1PBU-FM.h
</pre>
** Beispiel: HMID -> 081507, Seriennummer: KEQ0000007
<pre>
/ The model type (not used from bootloader)
#define HM_TYPE 0xF0, 0xA9
// 10 bytes serial number. Must be unique for each device
#define HM_SERIAL 'K', 'E', 'Q', '0', '0', '0', '0', '0', '0', '7'
// 3 bytes The device address (hm_id)
#define HM_ID 0x08, 0x15, 0x07
</pre>
* Eine Verzeichnisebene höher und Bootloader bauen:
<pre>
cd /root/hm_switch/Asksin_OTA_Bootloader/
make clean HM_LC_Sw1PBU_FM_8k
</pre>
Dabei sollte die Datei ''bootloader_HM-LC-Sw1PBU-FM.hex'' herauskommen. Diese wird später auf den Schalter geflasht

== Flashen ==
* Erzeugte Bootloader-Datei und Firmware in ein Verzeichnis kopieren:
<pre>
cp /home/pi/build/Asksin_HM_LC_Sw1PBU_FM.cpp.hex /root/hm_switch/flash/firmware.hex && cp /root/hm_switch/Asksin_OTA_Bootloader/Bootloader-AskSin-OTA-HM_LC_Sw1PBU_FM_8k.hex /root/hm_switch/flash/bootloader.hex
cd /root/hm_switch/flash/
</pre>
* Hinweis: In älteren Beschreibungen findet man häufig die Ziel-Plattform m644. Diese Unterscheidet sich praktisch in der Stromaufnahme des Chips, führt beim avrdude aber zu '''Fehlermeldungen''', deshalb auf '''m6444p''' achten
* '''Fuses''' setzen
''avrdude -p m644p -P gpio -c gpio -U lfuse:w:0xFD:m -U hfuse:w:0xD8:m -U lock:w:0x3F:m''
<pre>
avrdude: AVR device initialized and ready to accept instructions
Reading | ################################################## | 100% 0.00s
avrdude: Device signature = 0x1e960a
avrdude: reading input file "0xFD"
avrdude: writing lfuse (1 bytes):
Writing | ################################################## | 100% 0.00s
avrdude: 1 bytes of lfuse written
avrdude: verifying lfuse memory against 0xFD:
avrdude: load data lfuse data from input file 0xFD:
avrdude: input file 0xFD contains 1 bytes
avrdude: reading on-chip lfuse data:
Reading | ################################################## | 100% 0.00s
avrdude: verifying ...
avrdude: 1 bytes of lfuse verified
avrdude: reading input file "0xD8"
avrdude: writing hfuse (1 bytes):
Writing | ################################################## | 100% 0.00s
avrdude: 1 bytes of hfuse written
avrdude: verifying hfuse memory against 0xD8:
avrdude: load data hfuse data from input file 0xD8:
avrdude: input file 0xD8 contains 1 bytes
avrdude: reading on-chip hfuse data:
Reading | ################################################## | 100% 0.00s
avrdude: verifying ...
avrdude: 1 bytes of hfuse verified
avrdude: safemode: Fuses OK
avrdude done. Thank you.
</pre>
* '''Bootloader''' flashen
''avrdude -p m644p -P gpio -c gpio -U flash:w:bootloader.hex''
<pre>
avrdude: AVR device initialized and ready to accept instructions
Reading | ################################################## | 100% 0.00s
avrdude: Device signature = 0x1e960a
avrdude: NOTE: FLASH memory has been specified, an erase cycle will be performed
To disable this feature, specify the -D option.
avrdude: erasing chip
avrdude: reading input file "bootloader_HM-LC-Sw1PBU-FM.hex"
avrdude: input file bootloader_HM-LC-Sw1PBU-FM.hex auto detected as Intel Hex
avrdude: writing flash (61372 bytes):
Writing | ################################################## | 100% 30.86s
avrdude: 61372 bytes of flash written
avrdude: verifying flash memory against bootloader_HM-LC-Sw1PBU-FM.hex:
avrdude: load data flash data from input file bootloader_HM-LC-Sw1PBU-FM.hex:
avrdude: input file bootloader_HM-LC-Sw1PBU-FM.hex auto detected as Intel Hex
avrdude: input file bootloader_HM-LC-Sw1PBU-FM.hex contains 61372 bytes
avrdude: reading on-chip flash data:
Reading | ################################################## | 100% 28.95s
avrdude: verifying ...
avrdude: 61372 bytes of flash verified
avrdude: safemode: Fuses OK
avrdude done. Thank you.
</pre>
* '''Firmware''' flashen (aus der Arduino-IDE)
''avrdude -p m644p -P gpio -c gpio -U flash:w:firmware.hex''
<pre>
avrdude: AVR device initialized and ready to accept instructions
Reading | ################################################## | 100% 0.00s
avrdude: Device signature = 0x1e960a
avrdude: NOTE: FLASH memory has been specified, an erase cycle will be performed
To disable this feature, specify the -D option.
avrdude: erasing chip
avrdude: reading input file "Asksin_HM_LC_Sw1PBU_FM.cpp.hex"
avrdude: input file Asksin_HM_LC_Sw1PBU_FM.cpp.hex auto detected as Intel Hex
avrdude: writing flash (19042 bytes):
Writing | ################################################## | 100% 9.79s
avrdude: 19042 bytes of flash written
avrdude: verifying flash memory against Asksin_HM_LC_Sw1PBU_FM.cpp.hex:
avrdude: load data flash data from input file Asksin_HM_LC_Sw1PBU_FM.cpp.hex:
avrdude: input file Asksin_HM_LC_Sw1PBU_FM.cpp.hex auto detected as Intel Hex
avrdude: input file Asksin_HM_LC_Sw1PBU_FM.cpp.hex contains 19042 bytes
avrdude: reading on-chip flash data:
Reading | ################################################## | 100% 9.28s
avrdude: verifying ...
avrdude: 19042 bytes of flash verified
avrdude: safemode: Fuses OK
avrdude done. Thank you.
</pre>

[[Kategorie:HomeMatic Components]]
[[Kategorie:Schalter (Sender)]]
[[Kategorie:Schalter (Empfänger)]]

Interfaces für 1-Wire

2016-07-13T21:54:14Z

Kaihs:

== Einleitung ==
Der '''1-Wire''' Bus mit seinen Sensoren und Aktoren ist über ein [[Interface]] an einen Computer angeschlossen. Hierzu sind folgende Typen gebräuchlich:

* '''DS2480(B)''' ist ein Bus-Master-IC, der einen kompletten 1-Wire Bus an ein serielles Signal ankoppelt, dabei Teile des Timing sowie des Suchalgorithmus übernimmt. Dieser Schaltkreis ist Bestandteil vieler anderer [[Aktives Interface|aktiver Interfaces]].
* '''DS2482''' ist ein Bus-Master-IC, der einen kompletten 1-Wire Bus an ein serielles Signal auf dem I2C-Bus ankoppelt, dabei Teile des Timing sowie des Suchalgorithmus übernimmt. Dieser Schaltkreis ist Bestandteil des [[CUNO und 1-wire]]
* '''DS2490''' ist ein Bus-Master-IC, der einen kompletten 1-Wire Bus an einen USB-Port ankoppelt, dabei Teile des Timing sowie des Suchalgorithmus übernimmt. Dieser Schaltkreis ist Bestandteil verschiedener USB-Interfaces, er ist gegenwärtig nur über die Bibliothek libusb ansteuerbar, die von OWFS unterstützt wird. Eine Ansteuerung über OWX ist in Arbeit.
* '''DS9097''' ist ein [[Passives Interface|passives Interface]], mit dem die 1-Wire Komponenten aus einer seriellen RS232- Schnittstelle angesteuert werden. Dabei wird eine Spannungsversorgung realisiert, indem die RTS/CTS-Signale der Schnittstelle "gestohlen" und gesammelt werden. Der 1-Wire-Suchalgorithmus muss bei dem DS9097-Interface vollständig im ansteuernden Computer realisiert werden.
* '''DS9490R''' ist ein aktives 1-Wire [[USB-Interface]] (Typ 2, basierend auf dem DS2490) das auch eine Versorgungsspannung für den 1-Wire Bus zur Verfügung stellt. Zusätzlich ist ein DS1420 ID-Chip integriert. Der 1-Wire-Anschluss erfolgt über einen 6-Poligen RJ11 ("Western"-)Stecker.
* '''DS9097U''' ist ein [[Aktives Interface|aktives Interface]] (basierend auf dem DS2480B), welches die serielle RS232-Schnittstelle eines Computers an den 1-Wire-Bus ankoppelt. Es kann durch einen zusätzlichen USB-zu-Seriell-Konverter auch an den USB-Port angeschlossen werden. Der 1-Wire-Anschluss erfolgt über einen 6-Poligen RJ11 ("Western"-)Stecker. Den DS9097U gibt es in drei Varianten (009/S09, E25), von denen 2 mit 9-poligem Anschluss und eine mit 25-poligem Anschluss an die serielle Schnittstelle versehen sind. Problematisch ist, dass bei den 9-poligen Varianten auf die RJ-11-Anschlussbuchse keine Versorgungsspannung für den 1-Wire-Bus geführt wird, dies lässt sich aber durch Öffnung des Gehäuses und Herausführung der entsprechenden Leitungen beheben.
* '''USB9097''' ist aktives 1-Wire [[USB-Interface]] (Typ 1, basierend auf dem DS2480(B)). Er benötigt das Linux-Kernmodul ch341.ko
* '''LinkUSBi''' ist ein USB-1-Wire Adapter mit FTDI-Chip, der gegenüber den DS2480 etc. eine verbesserte Ansteuerung des 1-Wire Bus aufweist. '''Achtung:''' Dieser Adapter stellt verschiedene Funktionen für den 1-Wire Bus bereit, und emuliert den DS2480 Chip nur. Es kann daher derzeit zu Timing-Problemem kommen.
* '''[[Arduino mit OneWireFirmata]]''' [http://www.arduino.cc], kann als aktiver Busmaster für 1-Wire am USB-Port verwendet werden. Vorteil ist die preisgünstige Beschaffbarkeit und die einfache Integrierbarkeit in eigene Geräte (z.B. in der Version 'Nano' die sich in übliche Lochrasterplatinen im 2,54 mm Rastermaß einfach einlöten läßt). An einem Arduino können bis zu 54 (modellabhängig) unabhängige 1-Wire-Busse angeschlossen werden. Nicht für 1-Wire benutzte Pins können für parallel für Digital- und Analog- Ein/Ausgabe benutzt werden.
*'''[[1W-IF-ETH]]''' ist eine Kombination aus einem kommerziell erhältlichen Ethernet-Modul und einem oder zwei DS2480(B)-Chips, mit denen ein 1-Wire-Bus direkt an ein Ethernet angeschlossen werden kann.
*'''[[1W-IF-WIFI]]''' ist eine Kombination aus einem kommerziell erhältichen WLAN-Modul und einem oder zwei DS2480(B)-Chips, mit denen ein 1-Wire-Bus direkt an ein Ethernet angeschlossen werden kann.
[[Kategorie:1-Wire]]
[[Kategorie:Interfaces]]
[[Kategorie:HOWTOS]]

Verkehrslage

2016-07-05T20:05:18Z

Kaihs: /* Startort */

Hier wird ein Device erstellt um sich die [[Verkehrslage]] einer bestimmten Strecke anzeigen zu lassen. Das ganze beruht auf dem Modul [[HTTPMOD]].

== Zielsetzung ==
Ziel ist es, dass ein Dummy die aktuelle Verkehrslage für einen bestimmten Weg anzeigt und sich regelmäßig aktualisiert.

== Vorraussetzungen ==
Benötigt wird das Modul [[HTTPMOD]], welches standardmäßig installiert ist. Weiterhin wird ein Google Account benötigt und ein API Key um auf die Daten der Google Verkehrslage zuzugreifen.

== API Key von Google beziehen ==
Der Google API Key ist ein Schlüssel, welcher uns berechtigt Daten von Google zu erhalten. Google hat verschiedene Programme, welche über eine API Schnittstelle zur Verfügung gestellt werden. Damit nicht jeder einfach auf diese Daten zugreifen kann, wird der Key benötigt. Um diesen zu bekommen müsst ihr als aller erstes einen Google Account erstellen auf www.google.de

Sobald ihr dies habt, müssen wir in die Developer Console. Grund ist, dass der Zugriff auf die Daten eigentlich für Entwickler ist. Dorthin gelang ihr über diesen [https://console.developers.google.com/start?hl=de Link].

Als nächstes müsst ihr oben Links auf "Google APIs verwenden" klicken und ein neues Projekt erstellen, wenn ihr noch keins habt.

Jetzt in der Übersicht beim Reiter "Google APIs" unter Google Maps API "Google Maps Distance Matrix API" auswählen und dort auf den blauen Button "Enable" klicken.

Unter dem Reiter "Nutzung" könnt ihr später die Häufigkeit eurer Zugriffe anzeigen lassen. Unter dem Reiter "Kontingente" seht ihr, wie viele Zugriffe ihr an diesem Tag noch tätigen könnt. Insgesamt sind 2500 Zugriffe pro Tag erlaubt. Das sind etwa 1,7 Zugriffe pro Minute. So viele sollte man eigentlich nicht brauchen.

Auf der linken Seite unter "Zugangsdaten" kann man sich nun auch seinen Key anzeigen lassen. Diesen werden wir später für die Zugriffe benötigen.

== Link für das Modul erstellen ==

<pre>https://maps.googleapis.com/maps/api/distancematrix/json?origins=ORT,STRASSE+NR&destinations=ORT,STRASSE+NR&mode=driving&language=de-DE&departure_time=now&key=APIKEY</pre>

Den Link müssen wir mit unseren eigenen Angaben ergänzen. Starten wir zB in Frankfurt an der Friedberger Straße 291 und wollen nach Gießen in die Straße Schiffenberger Weg 115 sieht unser Link wie folgt aus:

<pre>https://maps.googleapis.com/maps/api/distancematrix/json?origins=Frankfurt,Friedberger%20Stra%C3%9Fe%20291&destinations=Gie%C3%9Fen,%20Schiffenberger%20Weg%20115&mode=driving&language=de-DE&departure_time=now&key=APIKEY</pre>

Es empfiehlt sich den Link einmal in die Browserzeile einzugeben. Dann muss auch nicht auf Leerzeichen geachtet werden und Google formatiert ihn uns automatisch, wie wir ihn brauchen. Übrigens seht ihr dann auch, wie die Seite aussieht, auf welche wir später mit dem HTTPMOD Modul zugreifen werden.

== HTTPMOD Einrichtung ==

=== Definieren des Device ===
Wenn wir nun unseren Google API Key und den Link haben, müssen wir ein neues Device mittels des [[HTTPMOD]] Moduls anlegen. In unserem Beispiel werden wir es wie folgt nennen: Verkehr.FFM.GI Verkehr für die Übersicht, FFM, weil wir ins Frankfurt am Main starten werden und GI, weil wir in Gießen enden.

Wir geben also folgendes in unsere Kommandozeile ein:
<pre>define Verkehr.FFM.GI HTTPMOD Link 3600</pre>
in unserem Beispiel also:
<pre>define Verkehr.FFM.GI HTTPMOD https://maps.googleapis.com/maps/api/distancematrix/json?origins=Frankfurt,Friedberger%20Stra%C3%9Fe%20291&destinations=Gie%C3%9Fen,%20Schiffenberger%20Weg%20115&mode=driving&language=de-DE&departure_time=now&key=APIKEY 3600</pre>

Die Zahl am Ende bestimmt die Häufigkeit der Abfrage in Sekunden. In unserem Fall also einmal die Stunde.

=== Anlegen der Attribute ===
Die benötigten Daten werden nun über die Attribut readingXXName und readingXXRegex abgefragt.

readingXXName: Hiermit geben wir dem späteren Reading einen Namen.

readingXXRegex: Hier wird festgelegt, welcher Teil des Textes "herausgeschnitten" werden soll.

XX: Wird durch Zahlen ersetzt, damit man eine Übersicht hat.

Als aller Erstes müssen wir uns unsere eigenen Attribute vorbereiten. Dies machen wir mit dem attr userattr wie folgt:

==== UserReadings Attribut ====
Hier definieren wir die später benötigte Attribute:
<pre>attr Verkehr.FFM.GI userattr reading01Name reading01Regex reading02Name reading02Regex reading03Name reading03Regex reading04Name reading04Regex reading05Name reading05Regex </pre>

Mehr zu den Attributen unter [[HTTPMOD]].

Legen wir nun unsere weiteren Attribut an:

==== Dauer der Reise ====
Die Dauer der Reise greifen wir mit den Attributen:
<pre>attr Verkehr.FFM.GI reading01Name duration
attr Verkehr.FFM.GI reading01Regex "duration"\s*:\s*{\s*["\w\s:,]+"value"\s*:\s*(\d+)\s*} </pre>

Unser Reading wird später "duration" heißen. Darin wird die Dauer der Reise in Sekunden angegeben.

==== Dauer der Reise mit aktuellem Verkehr ====
Die Dauer der Reise mit Verkehr greifen wir mit den Attributen:
<pre>attr Verkehr.FFM.GI reading02Name duration_in_traffic
attr Verkehr.FFM.GI reading02Regex "duration_in_traffic"\s*:\s*{\s*["\w\s:,]+"value"\s*:\s*(\d+)\s*} </pre>

Unser Reading wird später "duration" heißen. Darin wird die Dauer der Reise in Sekunden angegeben.

==== Entfernung ====
Die Entfernung greifen wir mit den Attributen:
<pre>attr Verkehr.FFM.GI reading03Name distance
attr Verkehr.FFM.GI reading03Regex "distance"\s*:\s*{\s*["\w\s:,]+"value"\s*:\s*(\d+)\s*} </pre>

Unser Reading wird später "distance" heißen und uns die Entfernung angeben.

==== Zielort ====
Den Zielort greifen wir mit den Attributen:
<pre>attr Verkehr.FFM.GI reading04Name destination_addresses
attr Verkehr.FFM.GI reading04Regex "destination_addresses"\s*:\s*\[\s*"([\w\s.,-:üöäß(\)]+)"\s*\] </pre>

Unser Reading wird später "destination_addresses" heißen und uns den Zielort angeben.

==== Startort ====
Den Startort greifen wir mit den Attributen:
<pre>attr Verkehr.FFM.GI reading05Name origin_addresses
attr Verkehr.FFM.GI reading05Regex "origin_addresses"\s*:\s*\[\s*"([\w\s.,-:üöäß(\)]+)"\s*\] </pre>

Unser Reading wird später "origin_addresses" heißen und uns den Zielort angeben.

==== Berechnung der Werte für die spätere Anzeige ====
Damit die Werte später User freundlich angezeigt werden, lassen wir sie von FHEM berechnen:
<pre>attr Verkehr.FFM.GI userReadings duration_hr {strftime "%H:%M", gmtime( int( ReadingsVal("$name","duration",0) /60+0.5)*60 );}, duration_in_traffic_hr {strftime "%H:%M", gmtime( int( ReadingsVal("$name","duration_in_traffic",0) /60+0.5)*60 );}, distance_hr:distance {int( ReadingsVal("$name","distance",0) /1000+0.5);}, duration_diff {int((ReadingsVal("$name","duration_in_traffic",0)-ReadingsVal("$name","duration",0))/60+0.5);}, duration_diff_hr {my $diff=int((ReadingsVal("$name","duration_in_traffic",0)-ReadingsVal("$name","duration",0))/60+0.5); return "+".$diff if ($diff>0); return "+0";} </pre>

==== State Anzeige ====
Uns als letztes noch, wie wir das ganze in State angezeigt bekommen möchten:
<pre>attr Verkehr.FFM.GI stateFormat duration_hr duration_diff_hr Min. (distance_hr km) </pre>

== Fertig ==
Fertig ist das Device, welches uns nun unseren Weg anzeigt. Natürlich könnt ihr die einzelnen Berechnungen und auch die State Anzeige für euch selbst anpassen und entsprechend ändern.

== Anmerkung ==
Zwei Dinge möchte ich anmerken:

1. Das ganze beruht auf {{Link2Forum|Topic=20151|Message=363109|LinkText=diesem}} und {{Link2Forum|Topic=20151|Message=365322|LinkText=diesem}} Beitrag.

2. Sobald Google die Ausgabe der Website verändert, wird es vermutlich nicht mehr funktionieren. Wie ihr dem Thema im Forum entnehmen könnt, ist dies schon vorgekommen. Daher nicht wundern, sondern im Forum schauen, ob es schon eine Veränderung gibt oder selbst die Readings anpassen.

[[Kategorie:Code_Snippets]]

Verkehrslage

2016-07-05T20:04:30Z

Kaihs: Doppelten Abschnitt Startort gelöscht

Hier wird ein Device erstellt um sich die [[Verkehrslage]] einer bestimmten Strecke anzeigen zu lassen. Das ganze beruht auf dem Modul [[HTTPMOD]].

== Zielsetzung ==
Ziel ist es, dass ein Dummy die aktuelle Verkehrslage für einen bestimmten Weg anzeigt und sich regelmäßig aktualisiert.

== Vorraussetzungen ==
Benötigt wird das Modul [[HTTPMOD]], welches standardmäßig installiert ist. Weiterhin wird ein Google Account benötigt und ein API Key um auf die Daten der Google Verkehrslage zuzugreifen.

== API Key von Google beziehen ==
Der Google API Key ist ein Schlüssel, welcher uns berechtigt Daten von Google zu erhalten. Google hat verschiedene Programme, welche über eine API Schnittstelle zur Verfügung gestellt werden. Damit nicht jeder einfach auf diese Daten zugreifen kann, wird der Key benötigt. Um diesen zu bekommen müsst ihr als aller erstes einen Google Account erstellen auf www.google.de

Sobald ihr dies habt, müssen wir in die Developer Console. Grund ist, dass der Zugriff auf die Daten eigentlich für Entwickler ist. Dorthin gelang ihr über diesen [https://console.developers.google.com/start?hl=de Link].

Als nächstes müsst ihr oben Links auf "Google APIs verwenden" klicken und ein neues Projekt erstellen, wenn ihr noch keins habt.

Jetzt in der Übersicht beim Reiter "Google APIs" unter Google Maps API "Google Maps Distance Matrix API" auswählen und dort auf den blauen Button "Enable" klicken.

Unter dem Reiter "Nutzung" könnt ihr später die Häufigkeit eurer Zugriffe anzeigen lassen. Unter dem Reiter "Kontingente" seht ihr, wie viele Zugriffe ihr an diesem Tag noch tätigen könnt. Insgesamt sind 2500 Zugriffe pro Tag erlaubt. Das sind etwa 1,7 Zugriffe pro Minute. So viele sollte man eigentlich nicht brauchen.

Auf der linken Seite unter "Zugangsdaten" kann man sich nun auch seinen Key anzeigen lassen. Diesen werden wir später für die Zugriffe benötigen.

== Link für das Modul erstellen ==

<pre>https://maps.googleapis.com/maps/api/distancematrix/json?origins=ORT,STRASSE+NR&destinations=ORT,STRASSE+NR&mode=driving&language=de-DE&departure_time=now&key=APIKEY</pre>

Den Link müssen wir mit unseren eigenen Angaben ergänzen. Starten wir zB in Frankfurt an der Friedberger Straße 291 und wollen nach Gießen in die Straße Schiffenberger Weg 115 sieht unser Link wie folgt aus:

<pre>https://maps.googleapis.com/maps/api/distancematrix/json?origins=Frankfurt,Friedberger%20Stra%C3%9Fe%20291&destinations=Gie%C3%9Fen,%20Schiffenberger%20Weg%20115&mode=driving&language=de-DE&departure_time=now&key=APIKEY</pre>

Es empfiehlt sich den Link einmal in die Browserzeile einzugeben. Dann muss auch nicht auf Leerzeichen geachtet werden und Google formatiert ihn uns automatisch, wie wir ihn brauchen. Übrigens seht ihr dann auch, wie die Seite aussieht, auf welche wir später mit dem HTTPMOD Modul zugreifen werden.

== HTTPMOD Einrichtung ==

=== Definieren des Device ===
Wenn wir nun unseren Google API Key und den Link haben, müssen wir ein neues Device mittels des [[HTTPMOD]] Moduls anlegen. In unserem Beispiel werden wir es wie folgt nennen: Verkehr.FFM.GI Verkehr für die Übersicht, FFM, weil wir ins Frankfurt am Main starten werden und GI, weil wir in Gießen enden.

Wir geben also folgendes in unsere Kommandozeile ein:
<pre>define Verkehr.FFM.GI HTTPMOD Link 3600</pre>
in unserem Beispiel also:
<pre>define Verkehr.FFM.GI HTTPMOD https://maps.googleapis.com/maps/api/distancematrix/json?origins=Frankfurt,Friedberger%20Stra%C3%9Fe%20291&destinations=Gie%C3%9Fen,%20Schiffenberger%20Weg%20115&mode=driving&language=de-DE&departure_time=now&key=APIKEY 3600</pre>

Die Zahl am Ende bestimmt die Häufigkeit der Abfrage in Sekunden. In unserem Fall also einmal die Stunde.

=== Anlegen der Attribute ===
Die benötigten Daten werden nun über die Attribut readingXXName und readingXXRegex abgefragt.

readingXXName: Hiermit geben wir dem späteren Reading einen Namen.

readingXXRegex: Hier wird festgelegt, welcher Teil des Textes "herausgeschnitten" werden soll.

XX: Wird durch Zahlen ersetzt, damit man eine Übersicht hat.

Als aller Erstes müssen wir uns unsere eigenen Attribute vorbereiten. Dies machen wir mit dem attr userattr wie folgt:

==== UserReadings Attribut ====
Hier definieren wir die später benötigte Attribute:
<pre>attr Verkehr.FFM.GI userattr reading01Name reading01Regex reading02Name reading02Regex reading03Name reading03Regex reading04Name reading04Regex reading05Name reading05Regex </pre>

Mehr zu den Attributen unter [[HTTPMOD]].

Legen wir nun unsere weiteren Attribut an:

==== Dauer der Reise ====
Die Dauer der Reise greifen wir mit den Attributen:
<pre>attr Verkehr.FFM.GI reading01Name duration
attr Verkehr.FFM.GI reading01Regex "duration"\s*:\s*{\s*["\w\s:,]+"value"\s*:\s*(\d+)\s*} </pre>

Unser Reading wird später "duration" heißen. Darin wird die Dauer der Reise in Sekunden angegeben.

==== Dauer der Reise mit aktuellem Verkehr ====
Die Dauer der Reise mit Verkehr greifen wir mit den Attributen:
<pre>attr Verkehr.FFM.GI reading02Name duration_in_traffic
attr Verkehr.FFM.GI reading02Regex "duration_in_traffic"\s*:\s*{\s*["\w\s:,]+"value"\s*:\s*(\d+)\s*} </pre>

Unser Reading wird später "duration" heißen. Darin wird die Dauer der Reise in Sekunden angegeben.

==== Entfernung ====
Die Entfernung greifen wir mit den Attributen:
<pre>attr Verkehr.FFM.GI reading03Name distance
attr Verkehr.FFM.GI reading03Regex "distance"\s*:\s*{\s*["\w\s:,]+"value"\s*:\s*(\d+)\s*} </pre>

Unser Reading wird später "distance" heißen und uns die Entfernung angeben.

==== Zielort ====
Den Zielort greifen wir mit den Attributen:
<pre>attr Verkehr.FFM.GI reading04Name destination_addresses
attr Verkehr.FFM.GI reading04Regex "destination_addresses"\s*:\s*\[\s*"([\w\s.,-:üöäß(\)]+)"\s*\] </pre>

Unser Reading wird später "destination_addresses" heißen und uns den Zielort angeben.

==== Startort ====
Den Startort greifen wir mit den Attributen:
<pre>attr Verkehr.FFM.GI reading06Name origin_addresses
attr Verkehr.FFM.GI reading06Regex "origin_addresses"\s*:\s*\[\s*"([\w\s.,-:üöäß(\)]+)"\s*\] </pre>

Unser Reading wird später "origin_addresses" heißen und uns den Zielort angeben.

==== Berechnung der Werte für die spätere Anzeige ====
Damit die Werte später User freundlich angezeigt werden, lassen wir sie von FHEM berechnen:
<pre>attr Verkehr.FFM.GI userReadings duration_hr {strftime "%H:%M", gmtime( int( ReadingsVal("$name","duration",0) /60+0.5)*60 );}, duration_in_traffic_hr {strftime "%H:%M", gmtime( int( ReadingsVal("$name","duration_in_traffic",0) /60+0.5)*60 );}, distance_hr:distance {int( ReadingsVal("$name","distance",0) /1000+0.5);}, duration_diff {int((ReadingsVal("$name","duration_in_traffic",0)-ReadingsVal("$name","duration",0))/60+0.5);}, duration_diff_hr {my $diff=int((ReadingsVal("$name","duration_in_traffic",0)-ReadingsVal("$name","duration",0))/60+0.5); return "+".$diff if ($diff>0); return "+0";} </pre>

==== State Anzeige ====
Uns als letztes noch, wie wir das ganze in State angezeigt bekommen möchten:
<pre>attr Verkehr.FFM.GI stateFormat duration_hr duration_diff_hr Min. (distance_hr km) </pre>

== Fertig ==
Fertig ist das Device, welches uns nun unseren Weg anzeigt. Natürlich könnt ihr die einzelnen Berechnungen und auch die State Anzeige für euch selbst anpassen und entsprechend ändern.

== Anmerkung ==
Zwei Dinge möchte ich anmerken:

1. Das ganze beruht auf {{Link2Forum|Topic=20151|Message=363109|LinkText=diesem}} und {{Link2Forum|Topic=20151|Message=365322|LinkText=diesem}} Beitrag.

2. Sobald Google die Ausgabe der Website verändert, wird es vermutlich nicht mehr funktionieren. Wie ihr dem Thema im Forum entnehmen könnt, ist dies schon vorgekommen. Daher nicht wundern, sondern im Forum schauen, ob es schon eine Veränderung gibt oder selbst die Readings anpassen.

[[Kategorie:Code_Snippets]]

Verkehrslage

2016-07-05T19:57:53Z

Kaihs: /* Definieren des Device */

Hier wird ein Device erstellt um sich die [[Verkehrslage]] einer bestimmten Strecke anzeigen zu lassen. Das ganze beruht auf dem Modul [[HTTPMOD]].

== Zielsetzung ==
Ziel ist es, dass ein Dummy die aktuelle Verkehrslage für einen bestimmten Weg anzeigt und sich regelmäßig aktualisiert.

== Vorraussetzungen ==
Benötigt wird das Modul [[HTTPMOD]], welches standardmäßig installiert ist. Weiterhin wird ein Google Account benötigt und ein API Key um auf die Daten der Google Verkehrslage zuzugreifen.

== API Key von Google beziehen ==
Der Google API Key ist ein Schlüssel, welcher uns berechtigt Daten von Google zu erhalten. Google hat verschiedene Programme, welche über eine API Schnittstelle zur Verfügung gestellt werden. Damit nicht jeder einfach auf diese Daten zugreifen kann, wird der Key benötigt. Um diesen zu bekommen müsst ihr als aller erstes einen Google Account erstellen auf www.google.de

Sobald ihr dies habt, müssen wir in die Developer Console. Grund ist, dass der Zugriff auf die Daten eigentlich für Entwickler ist. Dorthin gelang ihr über diesen [https://console.developers.google.com/start?hl=de Link].

Als nächstes müsst ihr oben Links auf "Google APIs verwenden" klicken und ein neues Projekt erstellen, wenn ihr noch keins habt.

Jetzt in der Übersicht beim Reiter "Google APIs" unter Google Maps API "Google Maps Distance Matrix API" auswählen und dort auf den blauen Button "Enable" klicken.

Unter dem Reiter "Nutzung" könnt ihr später die Häufigkeit eurer Zugriffe anzeigen lassen. Unter dem Reiter "Kontingente" seht ihr, wie viele Zugriffe ihr an diesem Tag noch tätigen könnt. Insgesamt sind 2500 Zugriffe pro Tag erlaubt. Das sind etwa 1,7 Zugriffe pro Minute. So viele sollte man eigentlich nicht brauchen.

Auf der linken Seite unter "Zugangsdaten" kann man sich nun auch seinen Key anzeigen lassen. Diesen werden wir später für die Zugriffe benötigen.

== Link für das Modul erstellen ==

<pre>https://maps.googleapis.com/maps/api/distancematrix/json?origins=ORT,STRASSE+NR&destinations=ORT,STRASSE+NR&mode=driving&language=de-DE&departure_time=now&key=APIKEY</pre>

Den Link müssen wir mit unseren eigenen Angaben ergänzen. Starten wir zB in Frankfurt an der Friedberger Straße 291 und wollen nach Gießen in die Straße Schiffenberger Weg 115 sieht unser Link wie folgt aus:

<pre>https://maps.googleapis.com/maps/api/distancematrix/json?origins=Frankfurt,Friedberger%20Stra%C3%9Fe%20291&destinations=Gie%C3%9Fen,%20Schiffenberger%20Weg%20115&mode=driving&language=de-DE&departure_time=now&key=APIKEY</pre>

Es empfiehlt sich den Link einmal in die Browserzeile einzugeben. Dann muss auch nicht auf Leerzeichen geachtet werden und Google formatiert ihn uns automatisch, wie wir ihn brauchen. Übrigens seht ihr dann auch, wie die Seite aussieht, auf welche wir später mit dem HTTPMOD Modul zugreifen werden.

== HTTPMOD Einrichtung ==

=== Definieren des Device ===
Wenn wir nun unseren Google API Key und den Link haben, müssen wir ein neues Device mittels des [[HTTPMOD]] Moduls anlegen. In unserem Beispiel werden wir es wie folgt nennen: Verkehr.FFM.GI Verkehr für die Übersicht, FFM, weil wir ins Frankfurt am Main starten werden und GI, weil wir in Gießen enden.

Wir geben also folgendes in unsere Kommandozeile ein:
<pre>define Verkehr.FFM.GI HTTPMOD Link 3600</pre>
in unserem Beispiel also:
<pre>define Verkehr.FFM.GI HTTPMOD https://maps.googleapis.com/maps/api/distancematrix/json?origins=Frankfurt,Friedberger%20Stra%C3%9Fe%20291&destinations=Gie%C3%9Fen,%20Schiffenberger%20Weg%20115&mode=driving&language=de-DE&departure_time=now&key=APIKEY 3600</pre>

Die Zahl am Ende bestimmt die Häufigkeit der Abfrage in Sekunden. In unserem Fall also einmal die Stunde.

=== Anlegen der Attribute ===
Die benötigten Daten werden nun über die Attribut readingXXName und readingXXRegex abgefragt.

readingXXName: Hiermit geben wir dem späteren Reading einen Namen.

readingXXRegex: Hier wird festgelegt, welcher Teil des Textes "herausgeschnitten" werden soll.

XX: Wird durch Zahlen ersetzt, damit man eine Übersicht hat.

Als aller Erstes müssen wir uns unsere eigenen Attribute vorbereiten. Dies machen wir mit dem attr userattr wie folgt:

==== UserReadings Attribut ====
Hier definieren wir die später benötigte Attribute:
<pre>attr Verkehr.FFM.GI userattr reading01Name reading01Regex reading02Name reading02Regex reading03Name reading03Regex reading04Name reading04Regex reading05Name reading05Regex </pre>

Mehr zu den Attributen unter [[HTTPMOD]].

Legen wir nun unsere weiteren Attribut an:

==== Dauer der Reise ====
Die Dauer der Reise greifen wir mit den Attributen:
<pre>attr Verkehr.FFM.GI reading01Name duration
attr Verkehr.FFM.GI reading01Regex "duration"\s*:\s*{\s*["\w\s:,]+"value"\s*:\s*(\d+)\s*} </pre>

Unser Reading wird später "duration" heißen. Darin wird die Dauer der Reise in Sekunden angegeben.

==== Dauer der Reise mit aktuellem Verkehr ====
Die Dauer der Reise mit Verkehr greifen wir mit den Attributen:
<pre>attr Verkehr.FFM.GI reading02Name duration_in_traffic
attr Verkehr.FFM.GI reading02Regex "duration_in_traffic"\s*:\s*{\s*["\w\s:,]+"value"\s*:\s*(\d+)\s*} </pre>

Unser Reading wird später "duration" heißen. Darin wird die Dauer der Reise in Sekunden angegeben.

==== Entfernung ====
Die Entfernung greifen wir mit den Attributen:
<pre>attr Verkehr.FFM.GI reading03Name distance
attr Verkehr.FFM.GI reading03Regex "distance"\s*:\s*{\s*["\w\s:,]+"value"\s*:\s*(\d+)\s*} </pre>

Unser Reading wird später "distance" heißen und uns die Entfernung angeben.

==== Zielort ====
Den Zielort greifen wir mit den Attributen:
<pre>attr Verkehr.FFM.GI reading04Name destination_addresses
attr Verkehr.FFM.GI reading04Regex "destination_addresses"\s*:\s*\[\s*"([\w\s.,-:üöäß(\)]+)"\s*\] </pre>

Unser Reading wird später "destination_addresses" heißen und uns den Zielort angeben.

==== Startort ====
Den Startort greifen wir mit den Attributen:
<pre>attr Verkehr.FFM.GI reading05Name origin_addresses
attr Verkehr.FFM.GI reading05Regex "origin_addresses"\s*:\s*\[\s*"([\w\s.,-:üöäß(\)]+)"\s*\] </pre>

Unser Reading wird später "origin_addresses" heißen und uns den Zielort angeben.

==== Startort ====
Den Startort greifen wir mit den Attributen:
<pre>attr Verkehr.FFM.GI reading06Name origin_addresses
attr Verkehr.FFM.GI reading06Regex "origin_addresses"\s*:\s*\[\s*"([\w\s.,-:üöäß(\)]+)"\s*\] </pre>

Unser Reading wird später "origin_addresses" heißen und uns den Zielort angeben.

==== Berechnung der Werte für die spätere Anzeige ====
Damit die Werte später User freundlich angezeigt werden, lassen wir sie von FHEM berechnen:
<pre>attr Verkehr.FFM.GI userReadings duration_hr {strftime "%H:%M", gmtime( int( ReadingsVal("$name","duration",0) /60+0.5)*60 );}, duration_in_traffic_hr {strftime "%H:%M", gmtime( int( ReadingsVal("$name","duration_in_traffic",0) /60+0.5)*60 );}, distance_hr:distance {int( ReadingsVal("$name","distance",0) /1000+0.5);}, duration_diff {int((ReadingsVal("$name","duration_in_traffic",0)-ReadingsVal("$name","duration",0))/60+0.5);}, duration_diff_hr {my $diff=int((ReadingsVal("$name","duration_in_traffic",0)-ReadingsVal("$name","duration",0))/60+0.5); return "+".$diff if ($diff>0); return "+0";} </pre>

==== State Anzeige ====
Uns als letztes noch, wie wir das ganze in State angezeigt bekommen möchten:
<pre>attr Verkehr.FFM.GI stateFormat duration_hr duration_diff_hr Min. (distance_hr km) </pre>

== Fertig ==
Fertig ist das Device, welches uns nun unseren Weg anzeigt. Natürlich könnt ihr die einzelnen Berechnungen und auch die State Anzeige für euch selbst anpassen und entsprechend ändern.

== Anmerkung ==
Zwei Dinge möchte ich anmerken:

1. Das ganze beruht auf {{Link2Forum|Topic=20151|Message=363109|LinkText=diesem}} und {{Link2Forum|Topic=20151|Message=365322|LinkText=diesem}} Beitrag.

2. Sobald Google die Ausgabe der Website verändert, wird es vermutlich nicht mehr funktionieren. Wie ihr dem Thema im Forum entnehmen könnt, ist dies schon vorgekommen. Daher nicht wundern, sondern im Forum schauen, ob es schon eine Veränderung gibt oder selbst die Readings anpassen.

[[Kategorie:Code_Snippets]]

Diskussion:Color

2016-06-21T19:04:19Z

Kaihs:

Funktioniert die Syntax
attr <device> devStateIcon {Color_devStateIcon(ReadingsVal($name,"rgb","000000"))}
nicht nur dann, wenn $name zum Zeitpunkt der Auswertung des Ausdrucks auch definiert ist?

Das mag ja in einigen Modulen durchaus der Fall sein, aber dass es die Variable $name überhaupt gibt ist doch nur eine Konvention und nicht garantiert.

Zumindest gab es dadurch in einem Modul in das ich Color.pm eingebaut habe Probleme und es funktionierte so nicht.