FHEMWiki - Benutzerbeiträge [de]

ABFALL

2019-06-10T18:04:59Z

SirUli: Falsche Namensreferenz

{{Infobox Modul
|ModPurpose=Filtern von (Abfall-)Terminen aus einem Calendar.
|ModType=x
|ModFTopic=48237
|ModForumArea=Codeschnipsel
|ModTechName=57_ABFALL.pm
|ModOwner=Constantin / {{Link2FU|14026|uniqueck}}
}}

[[ABFALL]] ist ein (inoffizielles, nicht Bestandteil der Distribution) Hilfsmodul, das bestimmte Termine aus einem bestehenden Kalender des Moduls [[Calendar]] in Readings übernimmt.

== Voraussetzungen ==
Es muss ein [[Calendar]]-Objekt definiert sein. Der dabei benutzte Name muss in der Definition des ABFALL-Objekts spezifiziert werden.
Es können auch mehrere Calendar Objekte übergeben werden.

Sonderzeichen aus dem Namen der Termine, werden entfernt um die Namen der generierten Readings FHEM tauglich zu machen, für die Werte der Readings bleiben diese allerdings erhalten.

== Anwendung ==
=== Installation ===
Mit folgendem Befehl kann das Modul direkt in den Standard FHEM Update Prozess eingeklinkt werden.
:<code>update add https://raw.githubusercontent.com/uniqueck/fhem-abfall/master/controls_fhemabfall.txt</code>
Um es nur zu installieren, kann auch einfach nur das Command
:<code>update all https://raw.githubusercontent.com/uniqueck/fhem-abfall/master/controls_fhemabfall.txt</code>
eingegeben werden.

=== Entwicklungsstrang ===
:<code>update add https://raw.githubusercontent.com/uniqueck/fhem-abfall/develop/controls_fhemabfall.txt</code>
bzw.
:<code>update all https://raw.githubusercontent.com/uniqueck/fhem-abfall/develop/controls_fhemabfall.txt</code>

=== Define ===
:<code>define <Name> ABFALL <calendarname>,<calendarname2>,...</code>

Erläuterung der Parameter im '''define''':
;<calendarname>
:Name des '''Calendar''' Kalenders

Beispiel:
:<code>define AbfallGoogleCalender Calendar ical url https://......</code>
:<code>define myABFALL ABFALL AbfallGoogleCalender</code>

=== Werte aktualisieren ===
Die Werte aktualisieren sich abhängig vom [[notify]] der entsprechenden Calendar Instanz, welche im define angegeben wurde(n).

=== Weitere Attribute ===

{| class="wikitable"
!Attribut
!Werteliste
!Beschreibung
!Default Wert
|-
!align="right" |calendarname_praefix
|0 und 1
|soll der Kalendername als praefix dem Reading vorangestellt werden, sollte bei nur einem Kalender auf 0 gesetzt werden
|1 - praefix wird vorangestellt, sofern mehrere Kalender angegeben wurden, ansonsten 0 - praefix wird nicht vorangestellt
|-
!align="right" |abfall_clear_reading_regex
|
|regex zum Entfernen von Anteilen aus dem Termin, dieser wird vor dem Entfernen von Sonderzeichen aus den Namen der Termine angewandt.
|
|-
!align="right" |disable
|0 und 1
|deaktiviert das Modul
|0
|-
!align="right" |weekday_mapping
|
|Mapping, wie die Readings der Tage angezeigt werden sollen, zum Beispiel So Mo Di Mi Do Fr Sa
|Sonntag Montag Dienstag Mittwoch Donnerstag Freitag Samstag
|-
!align="right" |delimiter_text_reading
|
|Wenn zwei Abholungen an ein und demselben Tag existieren, wird dieses Trennzeichen genutzt, um die beiden (oder mehrere) Werte zu einem Text zu verbinden. Nur relevant für die Readings next_text und now_text
|und
|-
!align="right" |delimiter_reading
|
|wie attribute delimiter_text_reading, allerdings nur für die readings next und now
|
|-
!align="right" |filter
|
|regex zum Filtern der Namen der Termine aus den Kalendern, so dass nur solche genutzt werden, welche diesem Filter entsprechen
|
|-
|}

== Anwendungsbeispiel(e) ==
=== Einbindung ins Tablet UI ===
<pre><div data-device="myABFALL" data-type="symbol" class="bigger warn wider"
data-get="next" data-get-warn=".*(\d+).*"
data-get-on='["Restmuell_.*","Wertstoff_.*"]'
data-colors='["#000","#6EB54C"]'
data-icons='["fa-trash-o","fa-trash-o"]'></div></pre>

=== Einbindung ins Tablet UI, erweitert ===
Fallen die Leerungen zweier verschiedener Tonnen nicht auf den selben Tag, reicht es normalerweise, nur ein Symbol auf der Oberfläche zu platzieren und dieses dann dynamisch zu befüllen. In folgendem Beispiel werden folgende Anforderungen umgesetzt:
* Anzeige unterschiedlicher Symbole bzw. Farben für Papiertonne, Restmülltonne, Biotonne und gelbe Säcke
* Anzeige der verbleibenden Tage bis zur Leerung als "Warn"-Marker in Rot, aber nur, wenn die Leerung innerhalb der nächsten 2 Tage ist
* Blinken des Symbols, wenn die nächste Leerung morgen ansteht
* Rotation des Symbols, wenn die nächste Leerung noch am selben Tag ansteht. Nach einer bestimmten Uhrzeit (z.B. 9 Uhr morgens) soll dann auf die nächste Tonne geschaltet werden
* Anzeige des Datums bzw. von "heute" oder "morgen" unter dem Symbol als Label

Zur Datumsanzeige wird eine kleine Hilfsfunktion in die 99_myUtils eingebaut.
<syntaxhighlight lang="perl">
sub datumHeuteMorgen($){
my $compareDate = shift;
my ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) = localtime(time);
$year += 1900; $mon += 1;
my $heute = sprintf('%02d.%02d.%04d', $mday, $mon, $year);
($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst)=localtime(time+86400);
$year += 1900; $mon += 1;
my $morgen = sprintf('%02d.%02d.%04d', $mday, $mon, $year);
return "heute" if $compareDate eq $heute;
return "morgen" if $compareDate eq $morgen;
return $compareDate;
}
</syntaxhighlight>
Diese Funktion wird in den userReadings des Abfall-Moduls verwendet. Das Abfallmodul erzeugt eine Gruppe von Readings mit dem Namen now_*, wenn die Leerung am selben Tag ansteht, bzw. genau dann, wenn der Termin im zu Grunde liegenden Kalender gerade aktiv ist. In diesem Beispiel liegt dem Kalender-Modul ein Google-Kalender zu Grunde, bei dem die Termine immer von 0 Uhr bis 9 Uhr morgens eingetragen sind. Dadurch wird erreicht, dass die Anzeige nach 9 Uhr weiterspringt, weil dann die now-Readings verschwinden.

Folgende userReadings werden zum Abfallmodul hinzugefügt, welches in diesem Beispiel "myABFALL" genannt ist:
<syntaxhighlight lang="perl">
attr myABFALL userReadings ftui_datum {ReadingsVal("myABFALL","now_text","") eq "" ? datumHeuteMorgen(ReadingsVal("myABFALL","next_date","")) : "heute";},ftui_next {ReadingsVal("myABFALL","now_text","") eq "" ? ReadingsVal("myABFALL","next","") : ReadingsVal("myABFALL","now","")."_0";;}
</syntaxhighlight>
Das Reading "ftui_next" bildet die Grundlage für das Symbol in TabletUI, das Reading "ftui_datum" wird für das Label genutzt.

Somit lässt sich ganze in FTUI wie folgt darstellen:
<syntaxhighlight lang="html">
<div data-device="myABFALL"
data-type="symbol"
data-get="ftui_next"
data-get-on='["Biotonne_0$","Biotonne_1$","Biotonne_.*","GelberSack_0$","GelberSack_1$","GelberSack_.*","Papiertonne_0$","Papiertonne_1$","Papiertonne_.*","Restmuelltonne_0$","Restmuelltonne_1$","Restmuelltonne_.*"]'
data-get-warn=".*([0|1|2]).*"
data-colors='["#8B4513","#8B4513","#8B4513","#f4e946","#f4e946","#f4e946","#2d9e1c","#2d9e1c","#2d9e1c","#696969","#696969","#696969"]'
class="large warn"
data-icons='["fa-trash-o fa-spin","fa-trash-o blink","fa-trash-o","fs-bag fa-spin","fs-bag blink","fs-bag","fs-dustbin fa-spin","fs-dustbin blink","fs-dustbin","fa-trash fa-spin","fa-trash blink","fa-trash"]'
/>
<div data-device="myABFALL" data-get="ftui_datum" data-type="label"/>
</syntaxhighlight>
Für Jede Tonne werden hier drei Zustände unterschieden und einzeln in "data-get-on", "data-on-colors" und "data-icons" zugeordnet. Daher haben diese Listen jeweils 12 Einträge.

=== Benachrichtigung ===
==== DOIF ====
====== TelegramBot Beispiel ======
<pre>[myABFALL:next_days] == 1) ( set fhemBot message 'Morgen wird [myABFALL:next_text] abgeholt')
[myABFALL:now_text] ne "") ( set fhemBot message 'Heute wird [myABFALL:now_text] abgeholt')</pre>

====== Pushbullet Beispiel ======

Die morgigen Leerungen per Push um 19:30 mittels Pushbullet:

<code>define dAbfallmorgen doif ([19:30] and [myABFALL:next_days] == 1) ( msg |Morgen wird [myABFALL:next_text] abgeholt)

attr dAbfallmorgen do always</code>

Die heutigen Leerungen per Push um 07:00 mittels Pushbullet:

<code>define dAbfallheute doif ([07:00] and [myABFALL:now_text] ne "") ( msg |Heute wird [myABFALL:now_text] abgeholt)

attr dAbfallheute do always</code>

=== Links ===
* Forenthema {{Link2Forum|Topic=50177|LinkText=Abfall Visualisierung mit Bilderrahmen}}

Knxd

2017-01-22T18:05:10Z

SirUli: Removing typos and "-i" is taken care of by systemd (Docs: "-i -- /lib/systemd/system/knxd.socket does this for us")

= knxd mit einem IP Gateway einrichten =
Damit fhem auf den KNX Bus zugreifen kann, benötigt man ein passendes Interface

Es gibt:

* RS232
* USB
* IP

Ich beschreibe die Einrichtung von knxd mit einem IP Gateway auf einen Raspberry Pi2 mit Wheezy oder Jessie.

== Installation ==

'''1. als erstes müssen folgende Pakete installiert werden (Referenz Debian Jessie):'''
<source lang="bash">sudo apt-get update
sudo apt-get install debhelper cdbs automake libtool libusb-1.0-0-dev git-core build-essential libsystemd-daemon-dev dh-systemd libev-dev
</source>
(Bei Debian Jessie-Lite fehlt noch mehr)

'''2. knxd herunterladen und installieren'''
Achtung: Wenn Abhängigkeiten fehlen, dann installiere diese nach. Nicht einfach mittels "-d" diese übergehen!
<source lang="bash">
git clone https://github.com/knxd/knxd.git
cd knxd
dpkg-buildpackage -b -uc
cd ..
sudo dpkg -i knxd_*.deb knxd-tools_*.deb
</source>

== Konfiguration ==
'''1. Ohne systemd'''

es muss als nächstes die Konfigurationsdatei editiert werden.

das geht mit:
<source lang="bash">
sudo nano /etc/default/knxd
</source>
dann folgende Einträge anpassen:
<source lang="bash">
DAEMON_ARGS="-u /tmp/eib -u /var/run/knx -i -b ipt:192.168.188.XX"
</source>
und
<source lang="bash">
START_KNXD=YES
</source>
'''2. Mit systemd z. B. für Debian Jessie'''

Die Konfigurationsdatei bei Jessie hat sich wegen der Nutzung von systemd geändert:
<source lang="bash">
sudo nano /etc/knxd.conf
</source>
dann folgende Einträge anpassen:
<source lang="bash">
KNXD_OPTS="-u /tmp/eib -u /var/run/knx -b ipt:192.168.188.XX"
</source>
und
<source lang="bash">
START_KNXD=YES
</source>
== knxd Status überprüfen ==
<source lang="bash">
/etc/init.d/knxd status
</source>

== FAQ ==
'''Wie wird eibd vorher deinstalliert?'''
<source lang="bash">
sudo rm -r /usr/local/bin/{eibd,knxtool,group*} /usr/local/lib/lib{eib,pthsem}*.so* /usr/local/include/pth*
</source>

'''folgender Fehler: dpkg-buildpackage: Fehler: Fehler-Exitstatus von debian/rules build war 2'''
<source lang="bash">
sudo apt-get install git-core build-essential
</source>

== Links ==
[[Benutzer:Marthinx]]

[https://github.com/knxd/knxd Github knxd]

[[Kategorie:Examples]]
[[Kategorie:EIB/KNX]]

Einrichten knxd mit MDT SCN-IP000.02

2017-01-22T13:31:03Z

SirUli: pthsem ist keine Abhängigkeit mehr

== Vorwort ==
Im Rahmen einer Machbarkeitsstudie ging es um das Thema Zählererfassung im betrieblichen Umfeld. Dazu sollten diverse Techniken und Bus-Systeme mit einbezogen werden.
Als eine Art (halb privates) Nebenprojekt kam auch die Verknüpfung zwischen FHEM und einem KNX-Zählerbaustein zum Einsatz.
Es gibt hier im Wiki zwar schon die Beschreibung [[Einrichten_von_eibd_für_das_Weinzierl_IP_730_Interface]], aber diese beschäftigt sich mit anderer Hardware und dem eib-daemon.

== Voraussetzungen ==
===Hardware===
:* MDT IP-Interface SCN-IP000.02. Wird später als IP-Tunneling-Device verwendet. Adresse wird über DHCP bezogen. '''Sollte geändert werden'''
:* MDT 4fach Binäreingang BE-04000.01. Dient als Zählermodul
:* MDT Spannungsversorgung STV-0160.01. Achtung! Es kann keine Standard 24V Spannungsversorgung verwendet werden, da diese nicht die für KNX benötigte Drossel enthält
===Software===
:* FHEM 5.7 Installation auf Raspberry Pi 3, gemäß Anleitung (folgt!), '''Raspian Jessie'''
:* ETS 5.0 wird für die Konfiguration der KNX-Komponenten benötigt. Kostenfreie Demo-Lizenz. Beschränkt auf 5 Geräte. Download von [https://knx.org/knx-de/software/ets/herunterladen/index.php KNX.org]
:* Katalog-Datei für die ETS vom Binär-Eingang. Quelle: [http://www.mdt.de/Downloads_Produktdatenbanken.html MDT-Homepage]

==Installation von knxd==
KNX-Daemon für Linux installieren: [[Knxd#Installation]]

==Konfiguration von knxd==
:* ''/etc/knxd.conf'' anlegen. Relevant ist nur die letzte Zeile. Die originale Datei enthält eine für das System nicht funktionierende Konfiguration. Daher wird der gesamte Inhalt der Datei hier dokumentiert.
<pre>
# configuration for knxd.service
#KNXD_OPTS="-u /tmp/eib -b ip:"

# The default options are "-u /tmp/eib -b ip:"
# which tell knxd to route between all of
# /tmp/eib (legacy socket (-u))
# multicast client (-b ip:).
# The knxd.socket file also tells knxd to listen to
# /run/eib (socket activation via systemd)
# TCP port 6720 (socket activation via systemd)

# *** DO NOT use "-u" / "-u /run/knx" or "-i" / "-i 6720" here.
# Systemd already does that on behalf of knxd, via 'knx.socket'.

# If you have KNX hardware on a serial port or USB, add the appropriate
# "-b TYPE:…" option. In this case, you probably want to set up a multicast
# server, not a client (i.e. use "-D -T -R -S", not "-b ip:").
# DO NOT use both.
#
# If your KNX hardware is a KNX/IP gateway that doesn't do multicast,
# use "-b ipt:192.168.1.2" (or its DNS name) to talk to it.
#
# KNX MUST NOT have more than one path between any two devices. Thus,
# you need to make sure that the KNX/IP gateway does not route multicast
# before you use both "-S" and "-b ipt:".

# The default bus address of knxd is 0.0.1. If that's in use in your KNX
# network (or if you run more than one knxd on your network), set a
# different address (-e 15.0.99).

# Run `knxd --help` to get a complete list of available options and drivers.

## DO NOT use the following options:
## -i -- /lib/systemd/system/knxd.socket does this for us
## -u /run/knx -- likewise
## -d -- /lib/systemd/system/knxd.service expects knxd to run in the foreground

###############################################################################
# This file is ignored when NOT using systemd: edit /etc/default/knxd instead #
###############################################################################
KNXD_OPTS="-e 1.0.240 -b ipt:192.168.0.88"
</pre>

Die ''192.168.0.88'' ist exemplarisch für die IP-Adresse eures KNX-Gateways.

:* Der Daemon sollte auch einem Jessie-System mit dem System starten.
Der Status des KNX-Dienstes kann mit ''systemctl status knxd.service'' geprüft werden. Die Ausgabe sollte so ähnlich aussehen:
<pre>
root@rasspi-fhem99:~# systemctl status knxd.service
● knxd.service - KNX Daemon
Loaded: loaded (/lib/systemd/system/knxd.service; enabled)
Active: active (running) since Mo 2016-04-11 13:35:53 CEST; 14s ago
Main PID: 1258 (knxd)
CGroup: /system.slice/knxd.service
└─1258 /usr/bin/knxd -e 1.0.240 -b ipt:192.168.0.88
</pre>
Wichtig ist, dass die IP-Adresse des Gateways und die eib-Adresse (1.0.240) in der letzten Zeile stehen.

Der Dienst kann auch manuell gestartet und gestoppt werden:
Start:
<pre>
systemctl start knxd.service
</pre>
Beenden:
<pre>
systemctl stop knxd.service
systemctl stop knxd.socket
</pre>
Achtung! wird der Dienst beendet während FHEM in benutzt, '''hängt sich FHEM auf''' und muss neu gestartet werden.

* Definition des IP-Gateways in FHEM:
<pre>
define KNX TUL eibd:192.168.0.1 1.0.240
</pre>
''192.168.0.1'' Adresse des KNX-Daemons, i.d.R. localhost

''1.0.240'' EIB-Adresse für FHEM/KNXD

Nach dem FHEM-Neustart sollte das neue Device "KNX" den Status "Initialized" haben.

== Installation/Konfiguration ETS==
Die ETS wird benötigt um KNX-Sensoren/Aktoren zu parametrieren und ihnen EIB-konforme Adressen zuzuweisen.
Ich empfehle an dieser Stelle das Dokument "Grundlagenwissen zum KNX Standard", welches von [https://www.google.de/url?sa=t&rct=j&q=&esrc=s&source=web&cd=1&ved=0ahUKEwi9w-O74ojMAhVBfxoKHeXKByAQFggkMAA&url=http%3A%2F%2Fwww.knx.org%2Ffileadmin%2Fdownloads%2F08%2520-%2520KNX%2520Flyers%2FGrundlagenwissen%2520zum%2520KNX%2520Standard%2FGrundlagenwissen_zum_KNX_Standard_German.pdf&usg=AFQjCNETdgrIp23RbSTx-E8Q0qFuNH1hBw&cad=rja KNX.org] heruntergeladen werden kann.

===Einrichtung des Binäreingangs BE-04000-01 in ETS===
* Bevor der Binär-Eingang benutzt werden kann, muss dieser in ETS konfiguriert werden.
Dazu wird in ETS zunächst ein Projekt angelegt. Als "Linientyp" wird TP (Twisted Pair) definiert.
Das IP-Gateway wird von der ETS selbstständig gefunden.
* Bevor das Gerät selbst in ETS angezeigt werden kann, muss eine Struktur für das Gerät erzeugt werden:
[[Datei:Ets struktur.png]]

1 Gebäudestruktur: Haus -> Keller -> Unterverteilung

2 Adressstruktur: "1 Haupt" -> "1/1 Mittel" -> "1/1/1 Schalter" 1.1.1 ist demnach die spätere Adresse für Schalteingang A des 4fach Geräts

3 Katalog-Import: Hier wird der Katalog für das Gerät importiert. Dieser wird dann per DragNDrop auf die erstellte Struktur "Unterverteilung" gezogen

* Jetzt kann das Gerät "Binäreingang 4-fach..." parametriert werden. Dazu im mittleren Fenster den Reiter "Parameter" wählen
[[Datei:Geraet parametrieren.png]]

Hier kann jetzt für jeden Eingang des Bausteins die entsprechende Funktion eingestellt werden, z.B. Schalter, Zähler, usw.
* Aus dem unteren Fenster werden nun per Drag N Drop die erstellten Gruppenadressen auf die jeweiligen Eingänge des Geräts gezogen. Damit wird auch die EIB-Adresse für jeden Eingang festgelegt.
* Jetzt muss das Gerät noch programmiert werden. Dazu Programmieren -> Physikalische Adresse und Applikationsprogramm

=== Installation/Konfiguration FHEM===
* In FHEM sollten jetzt die neu erzeugten EIB-Geräte angezeigt werden. Voraussetzung ist ein aktiviertes AutoCreate in ''fhem.cfg''
<pre>
define autocreate autocreate
</pre>
*[[Datei:Fhem eib.png]]

* Der Schalteingang wird als Glühbirne dargestellt
* Beim Zählereingang steht nur der Zählerstand als HEX-Zahl. In der ETS lässt sich für den Zähleingang festlegen, wie oft er Counter-Werte übertragen soll, z.B. alle 30 Impulse sollen übermittelt werden

[[Kategorie: Examples]]
[[Kategorie:EIB/KNX]]

Knxd

2017-01-22T13:21:49Z

SirUli: pthsem is no

= knxd mit einem IP Gateway einrichten =
Damit fhem auf den KNX Bus zugreifen kann, benötigt man ein passendes Interface

Es gibt:

* RS232
* USB
* IP

Ich beschreibe die Einrichtung von knxd mit einem IP Gateway auf einen Raspberry Pi2 mit Wheezy oder Jessie.

== Installation ==

'''1. als erstes müssen folgende Pakete installiert werden (Referenz Debian Jessie):'''
<source lang="bash">sudo apt-get update
sudo apt-get install debhelper cdbs automake libtool libusb-1.0-0-dev git-core build-essential libsystemd-daemon-dev dh-systemd libev-dev
</source>
(Bei Debian Jessie-Lite fehlt noch mehr)

'''2. knxd herunterladen und installieren'''
Achtung: Wenn Abhängigkeiten fehlen, dann installiere diese nach. Nicht einfach mittels "-d" diese übergehen!
<source lang="bash">
git clone https://github.com/knxd/knxd.git
cd knxd
dpkg-buildpackage -b -uc
cd ..
sudo dpkg -i knxd_*.deb knxd-tools_*.deb
</source>

== Konfiguration ==
'''1. Ohne systemd'''

es muss als nächstes die Konfigurationsdatei editiert werden.

das geht mit:
<source lang="bash">
sudo nano /etc/default/knxd
</source>
dann folgende Einträge anpassen:
<source lang="bash">
DAEMON_ARGS="-u /tmp/eib -u /var/run/knx -i -b ipt:192.168.188.XX"
</source>
und
<source lang="bash">
START_KNXD=YES
</source>
'''2. Mit systemd z. B. für Debian Jessie'''

Die Konfigurationsdatei bei Jessie hat sich wegen der Nutzung von systemd geändert:
<source lang="bash">
sudo nano /etc/knxd.conf
</source>
dann folgende Einträge anpassen:
<source lang="bash">
KNXD_OPTS=="-u /tmp/eib -u /var/run/knx -i -b ipt:192.168.188.XX"
</source>
und
<source lang="bash">
START_KNXD=YES
</source>
== knxd Status überprüfen ==
<source lang="bash">
/etc/init.d/knxd status
</source>

== FAQ ==
'''Wie wird eibd vorher deinstalliert?'''
<source lang="bash">
sudo rm -r /usr/local/bin/{eibd,knxtool,group*} /usr/local/lib/lib{eib,pthsem}*.so* /usr/local/include/pth*
</source>

'''folgender Fehler: dpkg-buildpackage: Fehler: Fehler-Exitstatus von debian/rules build war 2'''
<source lang="bash">
sudo apt-get install git-core build-essential
</source>

== Links ==
[[Benutzer:Marthinx]]

[https://github.com/knxd/knxd Github knxd]

[[Kategorie:Examples]]
[[Kategorie:EIB/KNX]]

AMAD

2016-12-15T18:59:49Z

SirUli: Formatierung und Typos.

{{Infobox Modul
|ModPurpose=Steuern von Adroidgeräten und Anzeige von bestimmten Informationen dieser Geräte
|ModType=d
|ModForumArea=Unterstützende Dienste
|ModTechName=74_AMAD.pm
|ModOwner=CoolTux ([http://forum.fhem.de/index.php?action=profile;u=13684 Forum] / [[Benutzer:CoolTux|Wiki]])
}}

==Vorwort==
===Warum AMAD2===
Bei der Entwicklung von AMAD musste ich auf Grund meines damaligen Wissenstandes ein einfaches Konzept zum Erhalt von Daten wählen. Hierfür wählte ich das Prinzip des pullens. Die Daten wurden alle 3 min vom Gerät angefordert.
Mit AMAD2, also der 2. Version von AMAD werden die Daten nun vom Androidgerät selbst nach FHEM gepusht. So kommen Statusänderungen quasi in Echtzeit als Reading ins Device.

==Vorstellung==
Dieses Modul liefert, '''in Verbindung mit der Android APP Automagic''', diverse Informationen von Android Geräten.
Die AndroidAPP Automagic (welche nicht von mir stammt und 2.90 Euro kostet) funktioniert wie Tasker, ist aber bei weitem User freundlicher.

== Features / Funktionen ==
Im Auslieferiungszustand werden folgende Zustände dargestellt:
* installierte Android Version
* Zustand von Automagic auf dem Gerät
* Spracheingabe
* Bluetooth An/Aus
* Zustand einer definierten App (läuft aktiv im Vordergrund oder nicht?)
* verbundene Bluetoothgeräte, inklusive deren MAC Adresse
* aktuell abgespieltes Musikalbum des verwendeten Mediaplayers
* aktuell abgespielter Musikinterpret des verwendeten Mediaplayers
* aktuell abgespielter Musiktitel des verwendeten Mediaplayers
* Status des Androidgerätes - Online/Offline
* nächster Alarmtag
* nächste Alarmzeit
* Batteriestatus in %
* Ladestatus - Netztei angeschlossen / nicht angeschlossen
* Bildschirmstatus An/Aus
* Bildschirmhelligkeit
* Vollbildmodus An/Aus
* Bildschirmausrichtung Auto/Landscape/Portrait
* Standardlautstärke
* Media Lautstärke
* ...

Mit etwas Einarbeitung können jegliche Informationen welche Automagic bereit stellt, in FHEM angezeigt werden. Hierzu bedarf es lediglich eines eigenen Flows welcher seine Daten an die AMADCommBridge sendet. Das Modul gibt auch die Möglichkeit Androidgeräte zu steuern.

Das Modul gibt Dir auch die Möglichkeit Deine Androidgeräte zu steuern. So können folgende Aktionen durchgeführt werden:
* Bluetooth Ein/Aus schalten
* zu einem bestimmten Bluetoothgerät wechseln/verbinden
* Status des Gerätes (Online,Offline)
* Mediaplayer steuern (Play, Stop, nächster Titel, vorheriger Titel)
* nächste Alarmzeit setzen
* ein Benachrichtigungston abspielen (Notificationsound)
* eine App auf dem Gerät öffnen
* eine URL im Browser öffnen
* Bildschirm An/Aus machen
* Bildschirmhelligkeit einstellen
* Vollbildmodus einschalten
* eine Nachricht senden welche am Bildschirm angezeigt wird
* Bildschirmausrichtung einstellen (Auto,Landscape,Portrait)
* neuen Statusreport des Gerätes anfordern
* Systembefehle setzen (Reboot)
* eine Nachricht senden welche angesagt wird (TTS)
* Medienlautstärke regeln
* ...

== Hinweise zum Betrieb mit Fhem ==
Für all diese Aktionen und Informationen wird auf dem Androidgerät die App Automagic und ein so genannter Flow benötigt. Automagic Premium könnt Ihr Euch aus dem App Store installieren wohingegen die Flows im Ordner $FHEMINSTALL/FHEM/lib/ unter dem Dateinamen 74_AMADautomagicFlowset''$VERSION''.xml zu finden sind, wobei ''$VERSION'' die höchste sein sollte. Diese Datei müsst ihr auf das Gerät kopieren (Ort ist nicht entscheidend, nach dem Import kann die Datei theoretisch gelöscht werden).

== AutomagicApp Anweisung ==
* installiert die App
* importiert das Flowset 74_AMADautomagicFlowset$VERSION.xml aus dem Ordner $INSTALLFHEM/FHEM/lib/ auf Eurem Androidgerät (Menü -> Verwalten -> Flows importierten). '''Wichtig: ''' Die Flows dürfen noch nicht aktiviert werden!

==Definition in FHEM==
<code>define <name> AMAD <IP-ADRESSE></code>

'''!!! Wichtig - Es dürfen ausschließlich nur IP Adressen verwendet werden, keine FQDN !!!'''

'''Beispiel:'''

<code>define WandTabletWohnzimmer AMAD 192.168.0.23</code>

Die Anweisung im Beispiel erstellt zwei neue AMAD-Devices im Raum AMAD:
* "WandTabletWohnzimmer", wobei der Parameter <IP-ADRESSE> die IP Adresse des Android Gerätes festlegt. !!!Comming Soon!!! Wer den Port ändern möchte, kann dies über das Attribut "port" tun. Ihr solltet aber wissen was Ihr tut, da dieser Port im HTTP Request Trigger der beiden Flows eingestellt ist. Demzufolge muß der Port dort auch geändert werden.
* "AMADCommBridge", welches als Kommunikationsbrücke vom Androidgerät zu FHEM dient. Wenn notwendig kann der Port für die Bridge ohne Probleme im Bridge Device mittels dem Attribut "port" verändert werden.

===AMAD Communication Bridge===
Beim ersten anlegen einer AMAD Deviceinstanz wird, wie angesprochen, automatisch ein Gerät Namens AMADCommBridge im Raum AMAD angelegt. Dieses Gerät dient zur Kommunikation vom Androidgerät zu FHEM ohne das zuvor eine Anfrage von FHEM aus ging. Damit das Androidgerät die IP von FHEM kennt, '''muss''' diese sofort nach dem anlegen der Bridge über den set Befehl in ein entsprechendes Reading in die Bridge geschrieben werden. '''DAS IST SUPER WICHTIG UND FÜR DIE FUNKTION DER BRIDGE NOTWENDIG.'''
Bitte führt hierzu folgenden Befehl aus:
<code>set AMADCommBridge fhemServerIP <FHEM-IP></code>

Als zweites Reading könnt ihr ''expertMode'' setzen. Mit diesem Reading wird eine unmittelbare Kommunikation vom Gerät zu FHEM erreicht ohne die Einschränkung, über ein Notify gehen zu müssen und nur reine set Befehle ausführen zu können.

=== Aktivierung ===
Nach der erfolgreichen Konfiguration des FHEM Moduls und der Automagic App können nun die Flows auf dem Gerät aktiviert werden.

Sofern die Geräteinstanz korrekt angelegt wurde und die fhemServerIP in der CommBridge gesetzt wurde, sollten nach spätestens 15 Sekunden bereits die ersten Readings reinkommen. Nun wird alle 15 Sekunden probiert einen Status Request erfolgreich ab zu schließen. Wenn der Status sich über einen längeren Zeitraum nicht auf "activ" ändert, sollte man im Log nach eventuellen Fehlern suchen.

Es gibt die Möglichkeit einer Abfrage des Status jeglicher Geräte in FHEM über das Androidgerät und Auswertung auf dem Androidgerät.

'''Beispiel:'''
Erstelle einen Flow mit einer HTTP Request Aktion mit folgendem Inhalt:

<code>
URL
http://{global_fhemip}:8090

REQUEST METHODE
POST

CONTENT TYP
Genereller Text
text/plain

DATEN
(hier kommen die drei Werte für ein ReadingsVal Aufruf rein, getrennt durch Leerzeichen)
TempFeuchtSensorSchlafzimmer temperature 300

(haken)Setze eigenen Header
FHEMDEVICE: {global_fhemdevice}
FHEMCMD: readingsval

SPEICHERE ANTWORT ...
Variable

VARIABLE
response
</code>

Du erhältst dann den Rückgabewert in der Response-Variablen. Diesen kannst Du dann innerhalb Deines Flows weiter verarbeiten z.B. in einem Text für eine Ansage.

==Readings==
* airplanemode - Status des Flugmodus
* androidVersion - aktuell installierte Androidversion
* automagicState - Statusmeldungen von der AutomagicApp '''(Voraussetzung Android >4.3). Wer ein Android >4.3 hat und im Reading steht "wird nicht unterstützt", muß in den Androideinstellungen unter Ton und Benachrichtigungen -> Benachrichtigungszugriff ein Haken setzen für Automagic'''
* bluetooth on/off - ist auf dem Gerät Bluetooth an oder aus
* checkActiveTask - Zustand einer zuvor definierten APP. 0=nicht aktiv oder nicht aktiv im Vordergrund, 1=aktiv im Vordergrund, '''siehe Hinweis unten'''
* connectedBTdevices - eine Liste der verbundenen Gerät
* connectedBTdevicesMAC - eine Liste der MAC Adressen aller verbundender BT Geräte
* currentMusicAlbum - aktuell abgespieltes Musikalbum des verwendeten Mediaplayers
* currentMusicApp - aktuell verwendeter Mediaplayers
* currentMusicArtist - aktuell abgespielter Musikinterpret des verwendeten Mediaplayers
* currentMusicTrack - aktuell abgespielter Musiktitel des verwendeten Mediaplayers
* daydream - on/off Daydream gestartet oder nicht
* deviceState - Status des Androidgerätes / unknown, online, offline
* doNotDisturb - aktueller Status des nicht stören Modus
* dockingState - undocked/docked Status ob das Gerät in einer Dockinstation ist oder nicht.
* flow_SetCommands - active/inactive, gibt den Status des SetCommands Flow wieder
* flow_informations - active/inactive, gibt den Status des Informations Flow wieder
* flowsetVersionAtDevice - aktuell installiertes Flowset auf dem Device
* intentRadioName - zu letzt eingestellter Intent Radio Name
* intentRadioState - Status des IntentRadio Players
* keyguardSet - 0/1 Displaysperre gesetzt 0=nein 1=ja, bedeutet nicht das sie gerade aktiv ist
* lastSetCommandError - letzte Fehlermeldung vom set Befehl
* lastSetCommandState - letzter Status vom set Befehl, Befehl erfolgreich/nicht erfolgreich gesendet
* lastStatusRequestError - letzte Fehlermeldung vom statusRequest Befehl
* lastStatusRequestState - letzter Status vom statusRequest Befehl, Befehl erfolgreich/nicht erfolgreich gesendet
* nextAlarmDay - aktiver Alarmtag
* nextAlarmState - aktueller Status des Androidinternen Weckers
* nextAlarmTime - aktive Alarmzeit
* powerLevel - Status der Batterie in %
* powerPlugged - Netzteil angeschlossen? 0=NEIN, 1|2=JA
* screen - on locked/unlocked, off locked/unlocked zeigt an ob der Bildschirm an oder aus ist und gleichzeitig gesperrt oder nicht gesperrt
* screenBrightness - Bildschirmhelligkeit von 0-255
* screenFullscreen - Vollbildmodus (On,Off)
* screenOrientation - (Landscape,Portrait) Bildschirmausrichtung
* screenOrientationMode - (auto, manual) Modus für die Ausrichtung
* state - aktueller Status des Devices
* volume - Media Lautstärkewert
* volumeNotification - Benachrichtigungs Lautstärke

Beim Reading checkActivTask muß zuvor der Packagename der zu prüfenden App als Attribut checkActiveTask angegeben werden. Beispiel: attr Nexus10Wohnzimmer checkActiveTask com.android.chrome für den Chrome Browser.

==Befehle==

===Set===
* activateVoiceInput - schaltet die Spracheingabe ein
* bluetooth - Schaltet Bluetooth on/off
* clearNotificationBar - (All,Automagic) löscht alle Meldungen oder nur die Automagic Meldungen in der Statusleiste
* currentFlowsetUpdate - fürt ein Flowset Update auf dem Device aus
* deviceState - setzt den Device Status Online/Offline. Siehe Readings
* installFlowSource - installiert einen Flow auf dem Device, das XML File muss unter /tmp/ liegen und die Endung xml haben. '''Bsp:''' set TabletWohnzimmer installFlowSource WlanUebwerwachen.xml
* doNotDisturb - schaltet den nicht stören Modus, always immer Stören, never niemals stören, alarmClockOnly nur Wecker darf stören, onlyImportant nur wichtige Störungen
* mediaPlayer - steuert den Standard Mediaplayer. play, stop, Titel zürück, Titel vor.
* nextAlarmTime - setzt die Alarmzeit. Geht aber nur innerhalb der nächsten 24Std.
* notifySndFile - spielt die angegebende Mediadatei auf dem Androidgerät ab. '''Die aufzurufende Mediadatei muß sich im Ordner /storage/emulated/0/Notifications/ befinden.'''
* screenBrightness - setzt die Bildschirmhelligkeit, von 0-255.
* screenMsg - versendet eine Bildschirmnachricht
* sendintent - sendet einen Intentstring Bsp: set $AMADDEVICE sendIntent org.smblott.intentradio.PLAY url http://stream.klassikradio.de/live/mp3-192/stream.klassikradio.de/play.m3u name Klassikradio, der erste Befehl ist die Aktion un der zweite das Extra. Es können immer zwei Extras mitgegeben werden.
* statusRequest - Fordert einen neuen Statusreport beim Device an. Es können nicht von allen Readings per statusRequest die Daten geholt werden. Einige wenige geben nur bei Statusänderung ihren Status wieder.
* timer - setzt einen Timer innerhalb der als Standard definierten ClockAPP auf dem Device. Es können nur Sekunden angegeben werden.
* ttsMsg - versendet eine Nachricht welche als Sprachnachricht ausgegeben wird
* vibrate - lässt das Androidgerät vibrieren
* volume - setzt die Medialautstärke. Entweder die internen Lautsprecher oder sofern angeschlossen die Bluetoothlautsprecher und per Klinkenstecker angeschlossenen Lautsprecher, + oder - vor dem Wert reduziert die aktuelle Lautstärke um den Wert
* volumeNotification - setzt die Benachrichtigungslautstärke.

===Set abhängig von gesetzten Attributen===
* changetoBtDevice - wechselt zu einem anderen Bluetooth Gerät. '''Attribut setBluetoothDevice muß gesetzt sein. Siehe Hinweis unten!'''
* openApp - öffnet eine ausgewählte App. '''Attribut setOpenApp'''
* openURL - öffnet eine URL im Standardbrowser, sofern kein anderer Browser über das Attribut setOpenUrlBrowser ausgewählt wurde. '''Bsp:''' ''attr Tablet setOpenUrlBrowser de.ozerov.fully|de.ozerov.fully.MainActivity'', das erste ist der Package Name und das zweite der Class Name
* screen - on/off/lock/unlock schaltet den Bildschirm ein/aus oder sperrt/entsperrt ihn, in den Automagic Einstellungen muss "Admin Funktion" gesetzt werden sonst funktioniert "Screen off" nicht. '''Attribut setScreenOnForTimer''' ändert die Zeit wie lange das Display an bleiben soll!
* screenFullscreen - Schaltet den Vollbildmodus on/off. '''Attribut setFullscreen'''
* screenLock - Sperrt den Bildschirm mit Pinabfrage. '''Attribut setScreenlockPIN''' - hier die Pin dafür eingeben. Erlaubt sind nur Zahlen. Es müßen mindestens 4 bis max 16 Zeichen sein.
* screenOrientation - Schaltet die Bildschirmausrichtung Auto/Landscape/Portait. '''Attribut setScreenOrientation'''
* setAPSSID - setzt die Acces Point SSID um WLAN Sleeps zu verhindern'''
* setTtsMsgSpeed - setzt die Sprachgeschwindigkeit bei der Sprachausgabe '''(Werte zwischen 0.5 bis 4.0 in 0.5er Schritten) default ist 1.0'''
* setTtsMsgLang - setzt die Sprache der Sprachausgabe, (de-Deutsch - en Englisch) default ist de'''
* system - setzt Systembefehle ab (nur bei gerootetet Geräen). reboot,shutdown,airplanemodeON (kann nur aktiviert werden) '''Attribut root''', in den Automagic Einstellungen muss "Root Funktion" gesetzt werden
* setNotifySndFilePath - setzt den korrekten Systempfad zur Notifydatei '''(default ist /storage/emulated/0/Notifications/'''

Um openApp verwenden zu können, muss als Attribut der Package Name der App angegeben werden.

Um zwischen Bluetoothgeräten wechseln zu können, muß das Attribut setBluetoothDevice mit folgender Syntax gesetzt werden. ''attr <DEVICE> BTdeviceName1|MAC,BTDeviceName2|MAC'' Es muss zwingend darauf geachtet werden das beim BTdeviceName kein Leerzeichen vorhanden ist. Am besten zusammen oder mit Unterstrich. Achtet bei der MAC darauf das Ihr wirklich nach jeder zweiten Zahl auch einen : drin habt '''Beispiel:''' ''attr Nexus10Wohnzimmer setBluetoothDevice Logitech_BT_Adapter|AB:12:CD:34:EF:32,Anker_A3565|GH:56:IJ:78:KL:76''

==STATE==
* initialized - Ist der Status kurz nach einem define..
* active - die Geräteinstanz ist im aktiven Status.
* disabled - die Geräteinstanz wurde über das Attribut disable deaktiviert

==deviceState==
* online - Das Gerät ist online und kann set Befehle entgegennehmen.
* offline - Ein Gerät wird in den folgenden 3 Szenarien in den Status offline gesetzt:
** Das Gerät wird mittels shutdown über FHEM runtergefahren.
** Der Airplainmod (Flugmodus) wird über FHEM aktiviert.
** Es wurde mehr als 5 mal ein statusRequest erfolglos und mehr als 3 mal ein set Command erfolglos abgeschickt.
Es bleibt also dem User überlassen das Gerät nach erneuter Verfügbarkeit wieder in den Status online zu setzen. Das kann z.B. über das Presence Modul erzeugt werden (set DEVICE deviceState online)

==Anwendungsbeispiele==
=== Lademanagement ===
Ich habe die Ladegeräte für meine Androidgeräte an Funkschaltsteckdosen. ein DOIF schaltet bei unter 30% die Steckdose ein und bei über 90% wieder aus.

Hier mal ein einfaches DOIF Beispiel für ein Lademanagment

<code>
... DOIF ([Nexus5Handy:powerLevel] < 30) (set LadenetzteilNexus5Handy:FILTER=STATE=off on) DOELSEIF ([Nexus5Handy:powerLevel] > 90) (set LadenetzteilNexus5Handy:FILTER=STATE=on off) DOELSE
</code>

=== Wecker ===
Morgens lasse ich mich über mein Tablet im Schlafzimmer mit Musik wecken. Verwendet wird hierzu der wakeuptimer des RESIDENTS Modules. Das abspielen stoppe ich dann von Hand. Danach erfolgt noch eine Ansage wie das Wetter gerade ist und wird.

=== Mediacenter ===
Mein 10" Tablet im Wohnzimmer ist Mediaplayer für das Wohnzimmer mit Bluetoothlautsprechern. Die Lautstärke wird automatisch runter gesetzt wenn die Fritzbox einen Anruf auf das Wohnzimmer Handgerät signalisiert.

=== Sprachbefehl - Abfragen von Zuständen diverser Sensoren ===
Wenn ich die Spracheingabe aktiviere und nach der Temperatur im Wohnzimmer frage, bekomme ich diese angesagt.

Der Teil im Feld Daten ist ein klassisches RadingsVal, halt nur ohne Komma und ohne Anführungszeichen

WIRD GERADE ÜBERARBEITET

=== Schaltbefehle vom Androidgerät an FHEM senden ===
Hierfür richte bitte einen eigen Flow ein. Wie das genau geht, verrät Dir die Hilfe.
Um einen Schaltbefehl für FHEM zu erstellen, folgt nach dem Trigger eine Aktion als Script (Aktion Type: Script). Hier trägst Du folgendes ein

setcmd = "LichtWohnzimmerLampeRechts on"

fhemcmd = "set"

In der ersten Zeile wird also der Schaltbefehl in der Variablem setcmd eingetragen und in der zweiten Zeile der FHEM Befehl in der Variablen fhemcmd.

Danach müsst Ihr nur noch in einer weiteren Aktion den Flow "Send Data to AMADCommBridge" ausführen (Aktion Type: Flows ausführen). Die Aktion sollte bereits in Eurer Liste Vorhanden sein.

[[Datei:Screenshot_20160717-134948.png|200px]]
[[Datei:Screenshot 17.07.2016 1-50-27.png|200px]]

Nun sollte Lampe1 angeschalten werden wenn der Flow ausgeführt wird.

== Bekannte Meldungen/Hinweise/Probleme ==
<code>PERL WARNING: Use of uninitialized value in hash element at /opt/fhem/FHEM/74_AMAD.pm line 14X</code>
Ist ab Version 2.2.2 gefixt. [https://forum.fhem.de/index.php/topic,54433.0.html Dickes Danke an Andy(gandy)]

Wenn auf dem Android-Gerät die Fehlermeldung 'Accessibility service not running' von Automagic kommt, oder im FHEM das reading state 'Flow Informations mit Fehler beendet' steht, dann muss der Accessibility Service auf dem Android-Device aktiviert werden: Einstellungen --> Bedienungshilfen --> Automagic Premium. Hier muss der Schalter auf 'an' stehen. Sollte dies der Fall sein, hilft u.U. ein kurzes Aus- und wieder Einschalten.

Gerät wird oft als offline angezeigt und es können keine set Befehle abgesetzt werden.
Mit der AMAD Version 2.2 hielt eine neue Behandlung des deviceState Readings Einzug. Das Reading stellt nun den tatsächlichen Status des Gerätes gegenüber FHEM da. Bei vielen Android 6 Geräten kommt es aber auf Grund vom DeepSleep Modus zum wegfall der WLAN Verbindung. Hier hilft die neue KeepAlive Funktion in AMAD. Dafür muß lediglich unter
* Einstellungen --> Akku --> oben auf die drei Punkte - Akku Leistungsoptimierung --> alle Apps und dann Automagic auswählen und "Nicht optimieren"
ausgewählt werden. Alles andere macht das Modul selbst.

==Ich sage Danke==
''Der größte Dank geht an meinen Mentor Andre (justme1968), er hat mir mit hilfreichen Tips geholfen Perlcode zu verstehen und Spaß am programmieren zu haben.''

''Auch möchte ich mich bei Jens bedanken (jensb) welcher mir ebenfalls mit hilfreichen Tips bei meinen aller ersten Gehversuchen beim Perlcode schreiben unterstützt hat.''

''So und nun noch ein besonderer Dank an pah (Prof. Dr. Peter Henning ), ohne seine Aussage "Keine Ahnung hatten wir alle mal, das ist keine Ausrede" hätte ich bestimmt nicht angefangen Interesse an Modulentwicklung zu zeigen :-)''

''Danke an Jürgen(ujaudio) und Andreas(scooty) die sich um die Übersetzung der Commandref ins Englische gekümmert haben''

''Danke auch an Ronny(RoBra81) für seine tollte Idee und Umsetzung von eigenen AMAD Readings aus externen Flows.''

TALKTOME & TALKTOUSER - Sprachverarbeitung für Nutzerinteraktionen

2016-07-22T08:42:01Z

SirUli: Verschiedene Hinweise (Gewünscht hier: https://forum.fhem.de/index.php/topic,54863.msg474625.html#msg474625 und Tippfehlerfixes)

<div style="float:right">{{Infobox Modul
|ModType=h
|ModPurpose=Anbindung von RiveScript an FHEM

|ModCmdRef=TALKTOME
|ModForumArea=Automatisierung
|ModTechName=42_TALKTOME.pm
|ModOwner=SirUli
}}
{{Infobox Modul
|Name=TALKTOUSER
|ModType=h
|ModPurpose=Nutzerverbindung zu TALKTOME

|ModCmdRef=TALKTOUSER
|ModForumArea=Automatisierung
|ModTechName=42_TALKTOUSER.pm
|ModOwner=SirUli
}}</div>

Mit Hilfe der Module TALKTOME & TALKTOUSER und der Sprache RiveScript ist es möglich, Chatbots - bekannt von Webseiten wie IKEA und co - für FHEM einzusetzen, um Frage-Antwort-Dialoge zu bauen.

== Features / Funktionen ==
Die Haupteigenschaften der Module sind:
* Anbindung von [http://rivescript.com/ RiveScript] an fhem
* Abruf von Readings, ReadingTimestamps, Attributen
* Absetzen von fhem Befehlen oder Aufruf von perl Funktionen

== Hinweise zum Betrieb mit FHEM ==
=== Voraussetzungen ===
* Die Einrichtung von msg für Antworten an die diversen Geräte.
* Installation von RiveScript in der Version 2.0.1 (oder neuer, falls eine erscheinen sollte) via CPAN. ACHTUNG nicht via apt-get installieren, da die Version zu alt ist.

==== msg ====
Bei der ersten Verwendung des Befehls "msg" wird ein Device namens globalMsg angelegt, was man aber dem Modul vorweg nehmen kann:
<pre>
define globalMsg msgConfig
</pre>

==== Installation von RiveScript ====
Rufe cpan auf:
<source lang="bash">
cpan
</source>

Das sieht dann etwa so aus:
<source lang="bash">
sudo cpan
Loading internal null logger. Install Log::Log4perl for logging messages
Terminal does not support AddHistory.

cpan shell -- CPAN exploration and modules installation (v2.10)
Enter 'h' for help.

cpan[1]>
</source>

Installiere dann Rivescript mit Hilfe des folgenden Kommandos:
<source lang="bash">
install RiveScript
</source>

Falls Fragen aufkommen, ob man Abhängigkeiten folgen soll, dann bitte richtig beantworten (yes) ;)

=== Installation der Module ===
Geht wie immer:
<pre>
update all https://raw.githubusercontent.com/SirUli/FHEM-TALKTO/master/controls_talkto.txt
</pre>

Anschließend sollte man im Ordner FHEM drei zusätzliche Files (42_TALKTOME.pm, 42_TALKTOUSER.pm sowie TALKTOME.rive.template) finden. Letzteres benennt man nun um in TALKTOME.rive. An dieser Stelle darf man das File natürlich auch schon editieren - wenn man möchte und Rivescript versteht.

Wenn man sich übrigens später sicher ist, dass man das dauerhaft nutzen will, würde ich das update command mit in den reguläre update Prozess einbinden:
<pre>
update add https://raw.githubusercontent.com/SirUli/FHEM-TALKTO/master/controls_talkto.txt
</pre>

==== Definition ====
Dann geht es los mit der Definition des Chatbots an sich:
<pre>
define FHEMTALKTOME TALKTOME
</pre>

FHEMTALKTOME ist sozusagen nun der Bot, welcher zu Beginn noch deaktiviert ist. Bevor man diesen aktiviert, muss man den Pfad zum TALKTOME.rive File setzen. Ist dieses File im Ordner FHEM (sozusagen also wie Auslieferungszustand und oben beschrieben), so setzt man folgendes:

<pre>
attr FHEMTALKTOME rsbrainfile ./FHEM/TALKTOME.rive
</pre>

Dann kann man das Attribut "disable" entfernen. Für die Nutzerinteraktion kann man noch weitere Details eines Nutzer pflegen(derzeit nur den "richtigen" Namen), daher brauchen wir ein Benutzermodul, also z.B. für mich:

<pre>
define TALKTOUSER_ULI TALKTOUSER
</pre>

ACHTUNG EINSCHRÄNKUNG: Derzeit ist nur ein Nutzer sinnvoll - da keine Filterung in den Geräten vorhanden ist. Siehe [https://forum.fhem.de/index.php/topic,54863.msg464432.html#msg464432 ToDo-Liste im Forenthread]

Nun kommt der wichtigste Teil - die Einbindung einer Quelle. Bei mir ist das nun Telegram, welches nun zwei zusätzliche Attribute via userattr bekommen muss:
<pre>
talktouserMonitorReading talktouserModSourceDev
</pre>
(wenn du keine Ahnung hast: attr TELEGRAMBOT userattr talktouserMonitorReading talktouserModSourceDev)

Was heissen die Attribute?

* <code>talktouserMonitorReading</code>: Bezeichnet das Reading welches überwacht werden soll, im falle von Telegram ist dies auf "msgText" zu setzen
* <code>talktouserModSourceDev</code>: Lässt eine Änderung des Quell Devices zu. So muss beispielsweise für Telegram, damit eine Antwort machbar ist, das Quelldevice verändert werden. Lokale Readings (also vom Quelldevice) werden mit <code>%%readingname%%</code> angegeben, das device selbst ist <code>%DEVICE%</code>. Für Telegram muss beispielsweise <code>%DEVICE%:@%%msgPeerId%%</code> gesetzt werden, damit die Antworten ankommen.

=== Wie legt man nun Dialoge an? ===
Dazu empfehle ich einmal durch das [https://www.rivescript.com/docs/tutorial Tutorial] ab den "First Steps" zu gehen und sich die Beispieldatei <code>FHEM/TALKTOME.rive.template</code> zu Gemüte zu führen. Diese bietet schon so Kleinigkeiten wie "Wie heisst du" als Fragen oder die Frage nach dem Wetter (Geräte eben entsprechend austauschen!) oder den Raumtemperaturen.

Zusätzlich:
* Readings lassen sich per <code><call>readingsval BK_Wetter fc1_low_c Error</call></code> auslesen
* Readings Timestamps lassen sich per <code><call>readingstimestamp LR_Wandthermostat temperature Error</call></code> auslesen
* Attribute lassen sich per <code><call>attrval BK_Wetter fc1_low_c Error</call></code> auslesen
* FHEM Kommandos kann man so ausführen:<code><call>fhem set KU_SWITCH_COFFEE_Sw on</call></code>
* Perl Methoden/Funktionen kann man so ausführen: <code><call>perl chatbot_beispielfunktion</call></code>

Hinweise:
* Wie aus den beispielen Erkennbar sind alle ''handler'', also die Zeilen welche mit "+" beginnen, klein geschrieben und das ist Absicht!
* Standardmäßig werden die Zeichen <code>.,!?;:¡¿</code> als überflüssige Satzzeichen behandelt und daher ausgefiltert. Will man nun (wie unten beschrieben) Telegram-Kommandos (welche mit / beginnen) ausführen lassen, so empfiehlt es sich, das Attribut rspunctuation auf <code>.,!?;:¡¿/</code> zu setzen. Somit kann dann Rivescript aus "/Temperaturen" den Befehl "temperaturen" filtern und auf diesen reagieren.

=== Was ist derzeit noch ToDo? ===
Siehe [https://forum.fhem.de/index.php/topic,54863.msg464432.html#msg464432 Thread]

= Umgesetzte Projekte =

== Beleuchtungssteuerung mit Telegram ==

=== Ziel ===

Über Telegram soll es möglich sein, die Beleuchtung im Haus ein und auszuschalten.

=== Ausgangssituation ===

Bei mir haben die meisten Geräte im FHEM das Namensschema

ET.ra.FU.Beschreibung

wobei

ET = Kürzel für Etage
ra = Kürzel für Raum
FU = Kürzel für Funktion

So ist zum Beispiel die Lampe im Esszimmer über dem Esstisch OG.ez.LI.Esstisch.

=== Umsetzung ===

Zunächst wird ein Menü gebaut, welches als Antwort auf die Nachricht "Hauptmenü" über Telegram gesendet wird:

.rive-Datei:
<pre>
! sub hauptmenü = hauptmenue

+ [*] (abbrechen|hauptmenue) [*]
- Hauptmenü:
^ /Licht_Aus
^ /Licht_An

+ leave
- Untermenü verlassen \n \s \n {@ hauptmenue}
</pre>

Die "/" vor den einzelnen Menüpunkten sorgen dafür, dass diese im Telegram direkt anklickbar sind.

Als nächstes werden zwei subs in der myUtils benötigt, um alle ein- bzw. ausgeschalteten Lampen zu ermitteln und als Antwort für Telegram zu formatieren:

99_myUtils.pm:
<source lang="perl">
sub
chatBot_getLightsOn
{
my @lights = devspec2array('.*\.LI\..*:FILTER=state!=off:FILTER=TYPE!=DOIF:FILTER=TYPE!=notify:FILTER=TYPE!=readingsProxy');;
my $msg = "Es sind folgende Lichter eingeschaltet:\n \n";;
my $room = "";

if (@lights > 0 and defined($defs{$lights[0]})){
foreach (@lights){
if ($room ne AttrVal($_, "room", $_))
{
if ($room ne "")
{
$msg .= " \n/".$room."_Aus \n";
}
$room = AttrVal($_, "room", $_);
$msg .= " \n".$room.": \n";
}
$_ =~ s/\./__/g;
$msg .= "/".$_." \n";
}
if ($room ne "")
{
$msg .= " \n/".$room."_Aus \n";
}
$msg .= " \n/Alle_Aus
\n \n/Hauptmenue
";;
}else{
$msg = "Es sind alle Lichter ausgeschaltet.";;
$msg .= "\n/Hauptmenue
";;
}
return $msg;
}

sub
chatBot_getLightsOff
{
my @lights = devspec2array('.*\.LI\..*:FILTER=state!=on:FILTER=TYPE!=DOIF:FILTER=TYPE!=notify:FILTER=TYPE!=readingsProxy');;
my $msg = "Es sind folgende Lichter ausgeschaltet:\n \n";;
my $room = "";

if (@lights > 0 and defined($defs{$lights[0]})){
foreach (@lights){
if ($room ne AttrVal($_, "room", $_))
{
if ($room ne "")
{
$msg .= " \n/".$room."_Ein \n";
}
$room = AttrVal($_, "room", $_);
$msg .= " \n".$room.": \n";
}
$_ =~ s/\./__/g;
$msg .= "/".$_." \n";
}
if ($room ne "")
{
$msg .= " \n/".$room."_Ein \n";
}
$msg .= " \n/Alle_Ein
\n \n/Hauptmenue
";;
}else{
$msg = "Es sind alle Lichter eingeschaltet.";;
$msg .= "\n/Hauptmenue
";;
}
return $msg;
}
</source>

Die Formatierung für Telegram erfolgt, indem die . durch __ ersetzt werden und ein / vorangestellt wird, damit es im Telegram anklickbar wird.

Nun folge die Logik für RiveScript. Zunächst die Abfrage für die Auflistung der ein- bzw. ausgeschalteten Lampen (inklusive notwendiger Definitionen):

.rive-Datei:
<pre>
! array levels = eg og dg au
! array rooms = ku ez ba fk sp ks wz bu sz
! array spacer = __ _

+ licht(@spacer)aus
- <call>perl chatBot_getLightsOn</call>{topic=licht_aus}

+ licht(@spacer)an
- <call>perl chatBot_getLightsOff</call>{topic=licht_an}
</pre>

Anschließend die Schaltfunktionen:

.rive-Datei:
<pre>
> topic licht_aus

+ [*] (abbrechen|hauptmenue) [*]
- {topic=random} {@ leave}

+ (@levels)(@spacer)(@rooms)(@spacer)li(@spacer)(*)(@spacer)(*)
- <set licht={uppercase}<star1>{/uppercase}.<star3>.LI.{formal}<star6>{/formal}_{formal}<star9>{/formal}>
^ Schalte Licht <get licht> aus \n
^ /Hauptmenue
^ <call>fhem set <get licht> off</call>

+ (@levels)(@spacer)(@rooms)(@spacer)li(@spacer)(*)
- <set licht={uppercase}<star1>{/uppercase}.<star3>.LI.{formal}<star6>{/formal}>
^ Schalte Licht <get licht> aus \n
^ /Hauptmenue
^ <call>fhem set <get licht> off</call>

+ alle(@spacer)aus
- Schalte alle Lichter aus \n
^ /Hauptmenue
^ <call>fhem set .*\.LI\..*:FILTER=state!=off:FILTER=TYPE!=DOIF:FILTER=TYPE!=notify:FILTER=TYPE!=readingsProxy off</call>

+ (*)(@spacer)(*)(@spacer)aus
- <set room={formal}<star1>{/formal}_{formal}<star4>{/formal}>
^ Schalte Licht in <get room> aus \n
^ /Hauptmenue
^ <call>fhem set .*\.LI\..*:FILTER=state!=off:FILTER=TYPE!=DOIF:FILTER=TYPE!=notify:FILTER=TYPE!=readingsProxy:FILTER=room=<get room> off</call>

+ (*)(@spacer)aus
- <set room={formal}<star1>{/formal}>
^ Schalte Licht in <get room> aus \n
^ /Hauptmenue
^ <call>fhem set .*\.LI\..*:FILTER=state!=off:FILTER=TYPE!=DOIF:FILTER=TYPE!=notify:FILTER=TYPE!=readingsProxy:FILTER=room=<get room> off</call>

< topic

> topic licht_an

+ [*] (abbrechen|hauptmenue) [*]
- {topic=random} {@ leave}

+ (@levels)(@spacer)(@rooms)(@spacer)li(@spacer)(*)(@spacer)(*)
- <set licht={uppercase}<star1>{/uppercase}.<star3>.LI.{formal}<star6>{/formal}_{formal}<star9>{/formal}>
^ Schalte Licht <get licht> ein \n
^ /Hauptmenue
^ <call>fhem set <get licht> on</call>

+ (@levels)(@spacer)(@rooms)(@spacer)li(@spacer)(*)
- <set licht={uppercase}<star1>{/uppercase}.<star3>.LI.{formal}<star6>{/formal}>
^ Schalte Licht <get licht> ein \n
^ /Hauptmenue
^ <call>fhem set <get licht> on</call>

+ alle(@spacer)ein
- Schalte alle Lichter ein \n
^ /Hauptmenue
^ <call>fhem set .*\.LI\..*:FILTER=state!=on:FILTER=TYPE!=DOIF:FILTER=TYPE!=notify:FILTER=TYPE!=readingsProxy on</call>

+ (*)(@spacer)(*)(@spacer)ein
- <set room={formal}<star1>{/formal}_{formal}<star4>{/formal}>
^ Schalte Licht in <get room> ein \n
^ /Hauptmenue
^ <call>fhem set .*\.LI\..*:FILTER=state!=on:FILTER=TYPE!=DOIF:FILTER=TYPE!=notify:FILTER=TYPE!=readingsProxy:FILTER=room=<get room> on</call>

+ (*)(@spacer)ein
- <set room={formal}<star1>{/formal}>
^ Schalte Licht in <get room> ein \n
^ /Hauptmenue
^ <call>fhem set .*\.LI\..*:FILTER=state!=on:FILTER=TYPE!=DOIF:FILTER=TYPE!=notify:FILTER=TYPE!=readingsProxy:FILTER=room=<get room> on</call>

< topic
</pre>

Ein möglicher Dialog mit FHEM sähe dann wie folgt aus:

Benutzer:
<pre>
Hauptmenü
</pre>

FHEM:
<pre>
Hauptmenü:
/Licht_Aus
/Licht_An
</pre>

Benutzer:
<pre>
/Licht_An
</pre>

FHEM:
<pre>
Es sind folgende Lichter ausgeschaltet:

Aussenwelt:
/AU__ho__LI__Markise
/AU__ho__LI__Terrasse

/Aussenwelt_Ein

Buero:
/DG__bu__LI__Flur
/DG__bu__LI__Schornstein
/DG__bu__LI__Schreibtisch

/Buero_Ein

Schlafzimmer:
/DG__sz__LI__Hinten_Halogen
/DG__sz__LI__Hinten_Led
/DG__sz__LI__Kleiderschrank
/DG__sz__LI__Vorn

/Schlafzimmer_Ein

Wohnzimmer:
/DG__wz__LI__Allgemein

/Wohnzimmer_Ein

Esszimmer:
/OG__ez__LI__Allgemein
/OG__ez__LI__Bogen
/OG__ez__LI__Esstisch
/OG__ez__LI__Vitrine

/Esszimmer_Ein

Flur_Kinder:
/OG__fk__LI__Allgemein

/Flur_Kinder_Ein

Hausflur:
/OG__hf__LI__Schuhschrank
/OG__hf__LI__Treppe

/Hausflur_Ein

Kinderschlafzimmer:
/OG__ks__LI__Allgemein
/OG__ks__LI__Bett
/OG__ks__LI__Sterne

/Kinderschlafzimmer_Ein

Kueche:
/OG__ku__LI__Besenschrank
/OG__ku__LI__Kuechenzeile
/OG__ku__LI__Kuehlschrank
/OG__ku__LI__Theke

/Kueche_Ein

Spielzimmer_Kinder:
/OG__sp__LI__Baggerheck_Schreibtisch
/OG__sp__LI__Baggerschaufel_Podest

/Spielzimmer_Kinder_Ein

Treppe:
/OG__tr__LI__Handlauf_Fenster

/Treppe_Ein

/Alle_Ein

/Hauptmenue</pre>

Benutzer:
<pre>
/OG__ku__LI__Kuechenzeile
</pre>

FHEM:
<pre>
Schalte Licht OG.ku.LI.Kuechenzeile ein
/Hauptmenue
</pre>

Benutzer:
<pre>
/OG__ku__LI__Kuechenschrank
</pre>

FHEM:
<pre>
Schalte Licht OG.ku.LI.Kuechenschrank ein
/Hauptmenue
</pre>

Benutzer:
<pre>
/Hauptmenue
</pre>

FHEM:
<pre>
Untermenü verlassen

Hauptmenü:
/Licht_Aus
/Licht_An
</pre>

Benutzer:
<pre>
/Licht_Aus
</pre>

FHEM:
<pre>
Es sind folgende Lichter eingeschaltet:

Kueche:
/OG__ku__LI__Kuechenschrank
/OG__ku__LI__Kuechenzeile

/Kueche_Aus

/Alle_Aus

/Hauptmenue
</pre>

Benutzer:
<pre>
/Kueche_Aus
</pre>

FHEM:
<pre>
Schalte Licht in Kueche aus
/Hauptmenue
</pre>

== Beleuchtungssteuerung über Sprache ==

Die Module können nicht nur eingesetzt werden, um mittels Telegram zu kommunizieren. Ein weiteres Beispiel ist der Einsatz als Spracherkennung für gesprochene Befehle über z.B. [[AMAD]]. Hier ist allerdings zum jetzigen Zeitpunkt noch keine gesprochene Antwort möglich und das Zieldevice für die Antwort kann nur hardcodiert hinterlegt werden.

Zunächst müssen in der AMADCommBridge die notwendigen Attribute gesetzt werden:
<pre>
attr AMADCommBridge userattr talktouserMonitorReading talktouserModSourceDev
attr AMADCommBridge talktouserModSourceDev HandyRonny
attr AMADCommBridge talktouserMonitorReading receiveVoiceCommand
</pre>

Nun muss noch die Logik für RiveScript hinterlegt werden:
<pre>

// Aus den gesprochenen Räumen werden die Kürzel ermittelt
! person badezimmer = OG.ba.
! person buero = DG.bu.
! person esszimmer = OG.ez.
! person flur_kinder = OG.fk.
! person hausflur = OG.hf.
! person kinderschlafzimmer = OG.ks.
! person kueche = OG.ku.
! person schlafzimmer = DG.sz.
! person spielzimmer_kinder = OG.sp.
! person treppe = OG.tr.
! person unten_kueche = EG.uk.
! person unten_stube = EG.st.
! person waschhaus = EG.wh.
! person wohnzimmer = DG.wz.

// Aus den gesprochenen Befehlen werden die FHEM Befehle ermittelt
! person ein = on
! person an = on
! person aus = off

// einige Ersetzungen, um nicht immer den konkreten Begriff verwenden zu müssen
! sub büro = buero
! sub küche = kueche
! sub bad = badezimmer
! sub flur kinder = flur_kinder
! sub kinderflur = flur_kinder
! sub spielzimmer kinder = spielzimmer_kinder
! sub spielzimmer = spielzimmer_kinder
! sub kinderspielzimmer = spielzimmer_kinder
! sub kinderzimmer = spielzimmer_kinder
! sub kueche unten = unten_kueche
// Die Deckenlampe heißt meistens Allgemein
! sub decke = allgemein

// Ersetzungen, um einen anderen Satzbau zu erlauben
! sub einschalten = ein
! sub anschalten = an
! sub anmachen = an
! sub ausmachen = aus
! sub ausschalten = aus

/*****************************************************************************\
* Lichtsteuerung per Sprache *
\*****************************************************************************/
! array schaltenaliaseinschalten = an|ein
! array schaltenaliasausschalten = aus
! array schaltenaliashandlung = an|ein|aus
! array schaltenaliasartikel = der|die|das
! array schaltenaliasfuellwoerter = schalte|mach
! array schaltenaliasorte = in|am|auf|an|im|auf dem
! array schaltenaliashoeflich = bitte
! array roomsfull = badezimmer|buero|esszimmer|flur_kinder|hausflur|kinderschlafzimmer|kueche|schlafzimmer|spielzimmer_kinder|treppe|unten_kueche|unten_stube|waschhaus|wohnzimmer

// einzelnes Licht ein- bzw. ausschalten
// Bsp: [Bitte] schalte das Licht im Wohnzimmer an der Decke (ein|aus)
+ [@schaltenaliashoeflich] [@schaltenaliasfuellwoerter] [@schaltenaliashoeflich] [@schaltenaliasartikel] licht [@schaltenaliasorte] [@schaltenaliasartikel] (@roomsfull) [@schaltenaliasorte] [@schaltenaliasartikel] _ (@schaltenaliashandlung)
- <set lightroom={person}<star1>{/person}LI.>
^ <set lightname={formal}<star2>{/formal}>
^ Licht <get lightroom><get lightname> wird <star3>geschaltet
^ <call>fhem set <get lightroom>.*<get lightname>.* {person}<star3>{/person}</call>

// einzelnes Licht ein- bzw. ausschalten - anderer Satzbau
// Bsp: [Bitte] schalte das Licht an der Decke im Wohnzimmer (ein|aus)
+ [@schaltenaliashoeflich] [@schaltenaliasfuellwoerter] [@schaltenaliashoeflich] [@schaltenaliasartikel] licht [@schaltenaliasorte] [@schaltenaliasartikel] _ [@schaltenaliasorte] (@roomsfull) (@schaltenaliashandlung)
- <set lightroom={person}<star2>{/person}LI.>
^ <set lightname={formal}<star1>{/formal}>
^ Licht <get lightroom><get lightname> wird <star3>geschaltet
^ <call>fhem set <get lightroom>.*<get lightname>.* {person}<star3>{/person}</call>

// einzelnes Licht mit zweiteiligem Namen ein- bzw. ausschalten
// Bsp: [Bitte] schalte das Licht im Schlafzimmer hinten halogen (ein|aus)
+ [@schaltenaliashoeflich] [@schaltenaliasfuellwoerter] [@schaltenaliashoeflich] [@schaltenaliasartikel] licht [@schaltenaliasorte] [@schaltenaliasartikel] zwei worte _ _ [@schaltenaliasorte] (@roomsfull) (@schaltenaliashandlung)
- <set lightroom={person}<star3>{/person}LI.>
^ <set lightname={formal}<star1>{/formal}_{formal}<star2>{/formal}>
^ Licht <get lightroom><get lightname> wird <star4>geschaltet
^ <call>fhem set <get lightroom>.*<get lightname>.* {person}<star4>{/person}</call>

// Licht in einem Zimmer ein- bzw. ausschalten
// Bsp: [Bitte] schalte das Licht im Schlafzimmer (ein|aus)
+ [@schaltenaliashoeflich] [@schaltenaliasfuellwoerter] [@schaltenaliashoeflich] [@schaltenaliasartikel] licht [@schaltenaliasorte] [@schaltenaliasartikel] (@roomsfull) (@schaltenaliashandlung)
- <set light={person}<star1>{/person}LI.>
^ Licht {formal}<star1>{/formal} wird <star2>geschaltet
^ <call>fhem set <get light>.* {person}<star2>{/person}</call>
</pre>

Damit kann sind zum Beispiel für die Lampe am Küchenschrank folgende Sprachbefehle möglich (Begriffe in eckigen Klammen, wie z.B. [bitte] sind optional; durch | getrennte Begriffe in Klammern stellen Alternativen dar):
<pre>
[bitte] [schalte|mache] [das] Licht [in] [der] Küche [am] Küchenschrank (an|ein|aus)
[schalte|mache] [bitte] [das] Licht [in] [der] Küche [am] Küchenschrank (an|ein|aus)
[bitte] [schalte|mache] [das] Licht [am] Küchenschrank [in] [der] Küche (an|ein|aus)
[schalte|mache] [bitte] [das] Licht [am] Küchenschrank [in] [der] Küche (an|ein|aus)
[bitte] [das] Licht [am] Küchenschrank [in] [der] Küche (an|ein|aus)[schalten|machen]
[bitte] [das] Licht [in] [der] Küche [am] Küchenschrank (an|ein|aus)[schalten|machen]
</pre>

Wird die konkrete Lampe weggelassen, so wird das Licht im gesamten Raum ein-/ausgeschaltet:
<pre>
[bitte] [schalte|mache] [das] Licht [in] [der] Küche (an|ein|aus)
[schalte|mache] [bitte] [das] Licht [in] [der] Küche (an|ein|aus)
[bitte] [das] Licht [in] [der] Küche (an|ein|aus)[schalten|machen]
</pre>

Da ich auch Lampen habe, deren Beschreibung aus zwei durch _ getrennten Begriffen besteht (z.B. OG.sp.LI.Baggerschaufel_Podest ist die vordere Glühbirne einer Baggerlampe, welche ein Podest beleuchtet), habe ich zwei Möglichkeiten eingebaut, diese zu schalten:

1. Ankündigung, dass es sich um einen Begriff mit zwei Worten handelt:
<pre>
[bitte] [schalte|mache] [das] Licht [im] Küche [an] [der] zwei Worte Baggerschaufel Podest (an|ein|aus)
</pre>
(weitere Alternativen zum Satzbau wie oben)

2. Die Beschreibung wird beim schalten generell zwischen zwei ".*" gesetzt, so dass alle Devices geschaltet werden, auf welche die Beschreibung zutrifft. Dadurch führen auch die folgenden Befehle (in allen oben beschriebenen Satzbauvarianten) zum Erfolg:
<pre>
[bitte] [schalte|mache] [das] Licht [im] Küche [am] Podest (an|ein|aus)
[bitte] [schalte|mache] [das] Licht [im] Küche [an] [der] Baggerschaufel (an|ein|aus)
</pre>

Dadurch ist zu beachten, dass z.B. bei den beiden Lampen DG.sz.LI.Hinten_Led und DG.sz.LI.Hinten_Halogen mit
<pre>
[bitte] [schalte|mache] [das] Licht [im] Schlafzimmer hinten (an|ein|aus)
</pre>
beide Lampen geschaltet werden und mit
<pre>
[bitte] [schalte|mache] [das] Licht [im] Schlafzimmer Halogen (an|ein|aus)
</pre>
nur eine der beiden.

= Weblinks =
* Forumsartikel [https://forum.fhem.de/index.php/topic,54863.0.html Module: TALKTOME & TALKTOUSER - Sprachverarbeitung für Nutzerinteraktionen]
* Forumsartikel [https://forum.fhem.de/index.php/topic,39983.0.html Neuer FHEM Befehl "msg" für Benachrichtigungen]
* RiveScript [https://www.rivescript.com/docs/tutorial#first-steps First steps]
* Modul [[AMAD]]

[[Category:Examples]]
[[Category:HOWTOS]]
[[Category:Code Snippets]]

TALKTOME & TALKTOUSER - Sprachverarbeitung für Nutzerinteraktionen

2016-07-06T13:47:25Z

SirUli: Crosslinks zum Thread

<div style="float:right">{{Infobox Modul
|ModType=h
|ModPurpose=Anbindung von RiveScript an FHEM

|ModCmdRef=TALKTOME
|ModForumArea=Automatisierung
|ModTechName=42_TALKTOME.pm
|ModOwner=SirUli
}}
{{Infobox Modul
|Name=TALKTOUSER
|ModType=h
|ModPurpose=Nutzerverbindung zu TALKTOME

|ModCmdRef=TALKTOUSER
|ModForumArea=Automatisierung
|ModTechName=42_TALKTOUSER.pm
|ModOwner=SirUli
}}</div>

Mit Hilfe der Module TALKTOME & TALKTOUSER und der Sprache RiveScript ist es möglich, Chatbots - bekannt von Webseiten wie IKEA und co - für FHEM einzusetzen, um Frage-Antwort-Dialoge zu bauen.

== Features / Funktionen ==
Die Haupteigenschaften von XYZ sind
* Anbindung von RiveScript an fhem
* Abruf von Readings, ReadingTimestamps, Attributen
* Absetzen von fhem Befehlen oder Aufruf von perl Funktionen

== Hinweise zum Betrieb mit FHEM ==
=== Voraussetzungen ===
* Die Einrichtung von msg für Antworten an die diversen Geräte.
* Installation von RiveScript in der Version 2.0.1 (oder neuer, falls eine erscheinen sollte) via CPAN. ACHTUNG nicht via apt-get installieren, da die Version zu alt ist.

==== msg ====
Bei der ersten Verwendung des Befehls "msg" wird ein Device namens globalMsg angelegt, was man aber dem Modul vorweg nehmen kann:
<pre>
define globalMsg msgConfig
</pre>

==== Installation von RiveScript ====
Rufe cpan auf:
<source lang="bash">
cpan
</source>

Das sieht dann etwa so aus:
<source lang="bash">
sudo cpan
Loading internal null logger. Install Log::Log4perl for logging messages
Terminal does not support AddHistory.

cpan shell -- CPAN exploration and modules installation (v2.10)
Enter 'h' for help.

cpan[1]>
</source>

Installiere dann Rivescript mit Hilfe des folgenden Kommandos:
<source lang="bash">
install RiveScript
</source>

Falls Fragen aufkommen, ob man Abhängigkeiten folgen soll, dann bitte richtig beantworten (yes) ;)

=== Installation der Module ===
Geht wie immer:
<pre>
update all https://raw.githubusercontent.com/SirUli/FHEM-TALKTO/master/controls_talkto.txt
</pre>

Anschließend sollte man im Ordner FHEM drei zusätzliche Files (42_TALKTOME.pm, 42_TALKTOUSER.pm sowie TALKTOME.rive.template) finden. Letzteres benennt man nun um in TALKTOME.rive. An dieser Stelle darf man das File natürlich auch schon editieren - wenn man möchte und Rivescript versteht.

Wenn man sich übrigens später sicher ist, dass man das dauerhaft nutzen will, würde ich das update command mit in den reguläre update Prozess einbinden:
<pre>
update add https://raw.githubusercontent.com/SirUli/FHEM-TALKTO/master/controls_talkto.txt
</pre>

==== Definition ====
Dann geht es los mit der Definition des Chatbots an sich:
<pre>
define FHEMTALKTOME TALKTOME
</pre>

FHEMTALKTOME ist sozusagen nun der Bot, welcher zu Beginn noch deaktiviert ist. Bevor man diesen aktiviert, muss man den Pfad zum TALKTOME.rive File setzen. Ist dieses file im Ordner FHEM (sozusagen also wie Auslieferungszustand und oben beschrieben), so setzt man folgendes:

<pre>
attr FHEMTALKTOME rsbrainfile ./FHEM/TALKTOME.rive
</pre>

Dann kann man das Attribut "disable" entfernen. Für die Nutzerinteraktion kann man noch weitere Details eines Nutzer pflegen(derzeit nur den "richtigen" Namen), daher brauchen wir ein Benutzermodul, also z.B. für mich:

<pre>
define TALKTOUSER_ULI TALKTOUSER
</pre>

ACHTUNG EINSCHRÄNKUNG: Derzeit ist nur ein Nutzer sinnvoll - da keine Filterung in den Geräten vorhanden ist. Siehe [https://forum.fhem.de/index.php/topic,54863.msg464432.html#msg464432 ToDo-Liste im Forenthread]

Nun kommt der wichtigste Teil - die Einbindung einer Quelle. Bei mir ist das nun Telegram, welches nun zwei zusätzliche Attribute via userattr bekommen muss:
<pre>
talktouserMonitorReading talktouserModSourceDev
</pre>
(wenn du keine Ahnung hast: attr TELEGRAMBOT userattr talktouserMonitorReading talktouserModSourceDev)

Was heissen die Attribute?

* <code>talktouserMonitorReading</code>: Bezeichnet das Reading welches überwacht werden soll, im falle von Telegram ist dies auf "msgText" zu setzen
* <code>talktouserModSourceDev</code>: Lässt eine Änderung des Quell Devices zu. So muss beispielsweise für Telegram, damit eine Antwort machbar ist, das Quelldevice verändert werden. Lokale Readings (also vom Quellverzeichnis) werden mit <code>%%readingname%%</code> angegeben, das device selbst ist <code>%DEVICE%</code>. Für Telegram muss beispielsweise <code>%DEVICE%:@%%msgPeerId%%</code> gesetzt werden, damit die Antworten ankommen

=== Wie legt man nun Dialoge an? ===
Dazu empfehle ich einmal durch das [https://www.rivescript.com/docs/tutorial Tutorial] ab den "First Steps" zu gehen und sich die Beispieldatei <code>FHEM/TALKTOME.rive.template</code> zu Gemüte zu führen. Diese bietet schon so kleinigkeiten wie "Wie heisst du" als Fragen oder die Frage nach dem Wetter (Geräte eben entsprechend austauschen!) oder den Raumtemperaturen.

Zusätzlich:
* Readings lassen sich per <code><call>readingsval BK_Wetter fc1_low_c Error</call></code> auslesen
* Readings Timestamps lassen sich per <code><call>readingstimestamp LR_Wandthermostat temperature Error</call></code> auslesen
* Attribute lassen sich per <code><call>attrval BK_Wetter fc1_low_c Error</call></code> auslesen
* FHEM Kommandos kann man so ausführen:<code><call>fhem set KU_SWITCH_COFFEE_Sw on</call></code>
* Perl Methoden/Funktionen kann man so ausführen: <code><call>perl chatbot_beispielfunktion</call></code>

=== Was ist derzeit noch ToDo? ===
Siehe [https://forum.fhem.de/index.php/topic,54863.msg464432.html#msg464432 Thread]

= Umgesetzte Projekte =

== Beleuchtungssteuerung mit Telegram ==

=== Ziel ===

Über Telegram soll es möglich sein, die Beleuchtung im Haus ein und auszuschalten.

=== Ausgangssituation ===

Bei mir haben die meisten Geräte im FHEM das Namensschema

ET.ra.FU.Beschreibung

wobei

ET = Kürzel für Etage
ra = Kürzel für Raum
FU = Kürzel für Funktion

So ist zum Beispiel die Lampe im Esszimmer über dem Esstisch OG.ez.LI.Esstisch.

=== Umsetzung ===

Zunächst wird ein Menü gebaut, welches als Antwort auf die Nachricht "Hauptmenü" über Telegram gesendet wird:

.rive-Datei:
<pre>
! sub hauptmenü = hauptmenue

+ [*] (abbrechen|hauptmenue) [*]
- Hauptmenü:
^ /Licht_Aus
^ /Licht_An

+ leave
- Untermenü verlassen \n \s \n {@ hauptmenue}
</pre>

Die "/" vor den einzelnen Menüpunkten sorgen dafür, dass diese im Telegram direkt anklickbar sind.

Als nächstes werden zwei subs in der myUtils benötigt, um alle ein- bzw. ausgeschalteten Lampen zu ermitteln und als Antwort für Telegram zu formatieren:

99_myUtils.pm:
<source lang="perl">
sub
chatBot_getLightsOn
{
my @lights = devspec2array('.*\.LI\..*:FILTER=state!=off:FILTER=TYPE!=DOIF:FILTER=TYPE!=notify:FILTER=TYPE!=readingsProxy');;
my $msg = "Es sind folgende Lichter eingeschaltet:\n \n";;
my $room = "";

if (@lights > 0 and defined($defs{$lights[0]})){
foreach (@lights){
if ($room ne AttrVal($_, "room", $_))
{
if ($room ne "")
{
$msg .= " \n/".$room."_Aus \n";
}
$room = AttrVal($_, "room", $_);
$msg .= " \n".$room.": \n";
}
$_ =~ s/\./__/g;
$msg .= "/".$_." \n";
}
if ($room ne "")
{
$msg .= " \n/".$room."_Aus \n";
}
$msg .= " \n/Alle_Aus
\n \n/Hauptmenue
";;
}else{
$msg = "Es sind alle Lichter ausgeschaltet.";;
$msg .= "\n/Hauptmenue
";;
}
return $msg;
}

sub
chatBot_getLightsOff
{
my @lights = devspec2array('.*\.LI\..*:FILTER=state!=on:FILTER=TYPE!=DOIF:FILTER=TYPE!=notify:FILTER=TYPE!=readingsProxy');;
my $msg = "Es sind folgende Lichter ausgeschaltet:\n \n";;
my $room = "";

if (@lights > 0 and defined($defs{$lights[0]})){
foreach (@lights){
if ($room ne AttrVal($_, "room", $_))
{
if ($room ne "")
{
$msg .= " \n/".$room."_Ein \n";
}
$room = AttrVal($_, "room", $_);
$msg .= " \n".$room.": \n";
}
$_ =~ s/\./__/g;
$msg .= "/".$_." \n";
}
if ($room ne "")
{
$msg .= " \n/".$room."_Ein \n";
}
$msg .= " \n/Alle_Ein
\n \n/Hauptmenue
";;
}else{
$msg = "Es sind alle Lichter eingeschaltet.";;
$msg .= "\n/Hauptmenue
";;
}
return $msg;
}
</source>

Die Formatierung für Telegram erfolgt, indem die . durch __ ersetzt werden und ein / vorangestellt wird, damit es im Telegram anklickbar wird.

Nun folge die Logik für RiveScript. Zunächst die Abfrage für die Auflistung der ein- bzw. ausgeschalteten Lampen (inklusive notwendiger Definitionen):

.rive-Datei:
<pre>
! array levels = eg og dg au
! array rooms = ku ez ba fk sp ks wz bu sz
! array spacer = __ _

+ licht(@spacer)aus
- <call>perl chatBot_getLightsOn</call>{topic=licht_aus}

+ licht(@spacer)an
- <call>perl chatBot_getLightsOff</call>{topic=licht_an}
</pre>

Anschließend die Schaltfunktionen:

.rive-Datei:
<pre>
> topic licht_aus

+ [*] (abbrechen|hauptmenue) [*]
- {topic=random} {@ leave}

+ (@levels)(@spacer)(@rooms)(@spacer)li(@spacer)(*)(@spacer)(*)
- <set licht={uppercase}<star1>{/uppercase}.<star3>.LI.{formal}<star6>{/formal}_{formal}<star9>{/formal}>
^ Schalte Licht <get licht> aus \n
^ /Hauptmenue
^ <call>fhem set <get licht> off</call>

+ (@levels)(@spacer)(@rooms)(@spacer)li(@spacer)(*)
- <set licht={uppercase}<star1>{/uppercase}.<star3>.LI.{formal}<star6>{/formal}>
^ Schalte Licht <get licht> aus \n
^ /Hauptmenue
^ <call>fhem set <get licht> off</call>

+ alle(@spacer)aus
- Schalte alle Lichter aus \n
^ /Hauptmenue
^ <call>fhem set .*\.LI\..*:FILTER=state!=off:FILTER=TYPE!=DOIF:FILTER=TYPE!=notify:FILTER=TYPE!=readingsProxy off</call>

+ (*)(@spacer)(*)(@spacer)aus
- <set room={formal}<star1>{/formal}_{formal}<star4>{/formal}>
^ Schalte Licht in <get room> aus \n
^ /Hauptmenue
^ <call>fhem set .*\.LI\..*:FILTER=state!=off:FILTER=TYPE!=DOIF:FILTER=TYPE!=notify:FILTER=TYPE!=readingsProxy:FILTER=room=<get room> off</call>

+ (*)(@spacer)aus
- <set room={formal}<star1>{/formal}>
^ Schalte Licht in <get room> aus \n
^ /Hauptmenue
^ <call>fhem set .*\.LI\..*:FILTER=state!=off:FILTER=TYPE!=DOIF:FILTER=TYPE!=notify:FILTER=TYPE!=readingsProxy:FILTER=room=<get room> off</call>

< topic

> topic licht_an

+ [*] (abbrechen|hauptmenue) [*]
- {topic=random} {@ leave}

+ (@levels)(@spacer)(@rooms)(@spacer)li(@spacer)(*)(@spacer)(*)
- <set licht={uppercase}<star1>{/uppercase}.<star3>.LI.{formal}<star6>{/formal}_{formal}<star9>{/formal}>
^ Schalte Licht <get licht> ein \n
^ /Hauptmenue
^ <call>fhem set <get licht> on</call>

+ (@levels)(@spacer)(@rooms)(@spacer)li(@spacer)(*)
- <set licht={uppercase}<star1>{/uppercase}.<star3>.LI.{formal}<star6>{/formal}>
^ Schalte Licht <get licht> ein \n
^ /Hauptmenue
^ <call>fhem set <get licht> on</call>

+ alle(@spacer)ein
- Schalte alle Lichter ein \n
^ /Hauptmenue
^ <call>fhem set .*\.LI\..*:FILTER=state!=on:FILTER=TYPE!=DOIF:FILTER=TYPE!=notify:FILTER=TYPE!=readingsProxy on</call>

+ (*)(@spacer)(*)(@spacer)ein
- <set room={formal}<star1>{/formal}_{formal}<star4>{/formal}>
^ Schalte Licht in <get room> ein \n
^ /Hauptmenue
^ <call>fhem set .*\.LI\..*:FILTER=state!=on:FILTER=TYPE!=DOIF:FILTER=TYPE!=notify:FILTER=TYPE!=readingsProxy:FILTER=room=<get room> on</call>

+ (*)(@spacer)ein
- <set room={formal}<star1>{/formal}>
^ Schalte Licht in <get room> ein \n
^ /Hauptmenue
^ <call>fhem set .*\.LI\..*:FILTER=state!=on:FILTER=TYPE!=DOIF:FILTER=TYPE!=notify:FILTER=TYPE!=readingsProxy:FILTER=room=<get room> on</call>

< topic
</pre>

Ein möglicher Dialog mit FHEM sähe dann wie folgt aus:

Benutzer:
<pre>
Hauptmenü
</pre>

FHEM:
<pre>
Hauptmenü:
/Licht_Aus
/Licht_An
</pre>

Benutzer:
<pre>
/Licht_An
</pre>

FHEM:
<pre>
Es sind folgende Lichter ausgeschaltet:

Aussenwelt:
/AU__ho__LI__Markise
/AU__ho__LI__Terrasse

/Aussenwelt_Ein

Buero:
/DG__bu__LI__Flur
/DG__bu__LI__Schornstein
/DG__bu__LI__Schreibtisch

/Buero_Ein

Schlafzimmer:
/DG__sz__LI__Hinten_Halogen
/DG__sz__LI__Hinten_Led
/DG__sz__LI__Kleiderschrank
/DG__sz__LI__Vorn

/Schlafzimmer_Ein

Wohnzimmer:
/DG__wz__LI__Allgemein

/Wohnzimmer_Ein

Esszimmer:
/OG__ez__LI__Allgemein
/OG__ez__LI__Bogen
/OG__ez__LI__Esstisch
/OG__ez__LI__Vitrine

/Esszimmer_Ein

Flur_Kinder:
/OG__fk__LI__Allgemein

/Flur_Kinder_Ein

Hausflur:
/OG__hf__LI__Schuhschrank
/OG__hf__LI__Treppe

/Hausflur_Ein

Kinderschlafzimmer:
/OG__ks__LI__Allgemein
/OG__ks__LI__Bett
/OG__ks__LI__Sterne

/Kinderschlafzimmer_Ein

Kueche:
/OG__ku__LI__Besenschrank
/OG__ku__LI__Kuechenzeile
/OG__ku__LI__Kuehlschrank
/OG__ku__LI__Theke

/Kueche_Ein

Spielzimmer_Kinder:
/OG__sp__LI__Baggerheck_Schreibtisch
/OG__sp__LI__Baggerschaufel_Podest

/Spielzimmer_Kinder_Ein

Treppe:
/OG__tr__LI__Handlauf_Fenster

/Treppe_Ein

/Alle_Ein

/Hauptmenue</pre>

Benutzer:
<pre>
/OG__ku__LI__Kuechenzeile
</pre>

FHEM:
<pre>
Schalte Licht OG.ku.LI.Kuechenzeile ein
/Hauptmenue
</pre>

Benutzer:
<pre>
/OG__ku__LI__Kuechenschrank
</pre>

FHEM:
<pre>
Schalte Licht OG.ku.LI.Kuechenschrank ein
/Hauptmenue
</pre>

Benutzer:
<pre>
/Hauptmenue
</pre>

FHEM:
<pre>
Untermenü verlassen

Hauptmenü:
/Licht_Aus
/Licht_An
</pre>

Benutzer:
<pre>
/Licht_Aus
</pre>

FHEM:
<pre>
Es sind folgende Lichter eingeschaltet:

Kueche:
/OG__ku__LI__Kuechenschrank
/OG__ku__LI__Kuechenzeile

/Kueche_Aus

/Alle_Aus

/Hauptmenue
</pre>

Benutzer:
<pre>
/Kueche_Aus
</pre>

FHEM:
<pre>
Schalte Licht in Kueche aus
/Hauptmenue
</pre>

== Beleuchtungssteuerung über Sprache ==

Die Module können nicht nur eingesetzt werden, um mittels Telegram zu kommunizieren. Ein weiteres Beispiel ist der Einsatz als Spracherkennung für gesprochene Befehle über z.B. [[AMAD]]. Hier ist allerdings zum jetzigen Zeitpunkt noch keine gesprochene Antwort möglich und das Zieldevice für die Antwort kann nur hardcodiert hinterlegt werden.

Zunächst müssen in der AMADCommBridge die notwendigen Attribute gesetzt werden:
<pre>
attr AMADCommBridge userattr talktouserMonitorReading talktouserModSourceDev
attr AMADCommBridge talktouserModSourceDev HandyRonny
attr AMADCommBridge talktouserMonitorReading receiveVoiceCommand
</pre>

Nun muss noch die Logik für RiveScript hinterlegt werden:
<pre>

// Aus den gesprochenen Räumen werden die Kürzel ermittelt
! person badezimmer = OG.ba.
! person buero = DG.bu.
! person esszimmer = OG.ez.
! person flur_kinder = OG.fk.
! person hausflur = OG.hf.
! person kinderschlafzimmer = OG.ks.
! person kueche = OG.ku.
! person schlafzimmer = DG.sz.
! person spielzimmer_kinder = OG.sp.
! person treppe = OG.tr.
! person unten_kueche = EG.uk.
! person unten_stube = EG.st.
! person waschhaus = EG.wh.
! person wohnzimmer = DG.wz.

// Aus den gesprochenen Befehlen werden die FHEM Befehle ermittelt
! person ein = on
! person an = on
! person aus = off

// einige Ersetzungen, um nicht immer den konkreten Begriff verwenden zu müssen
! sub büro = buero
! sub küche = kueche
! sub bad = badezimmer
! sub flur kinder = flur_kinder
! sub kinderflur = flur_kinder
! sub spielzimmer kinder = spielzimmer_kinder
! sub spielzimmer = spielzimmer_kinder
! sub kinderspielzimmer = spielzimmer_kinder
! sub kinderzimmer = spielzimmer_kinder
! sub kueche unten = unten_kueche
// Die Deckenlampe heißt meistens Allgemein
! sub decke = allgemein

// Ersetzungen, um einen anderen Satzbau zu erlauben
! sub einschalten = ein
! sub anschalten = an
! sub anmachen = an
! sub ausmachen = aus
! sub ausschalten = aus

/*****************************************************************************\
* Lichtsteuerung per Sprache *
\*****************************************************************************/
! array schaltenaliaseinschalten = an|ein
! array schaltenaliasausschalten = aus
! array schaltenaliashandlung = an|ein|aus
! array schaltenaliasartikel = der|die|das
! array schaltenaliasfuellwoerter = schalte|mach
! array schaltenaliasorte = in|am|auf|an|im|auf dem
! array schaltenaliashoeflich = bitte
! array roomsfull = badezimmer|buero|esszimmer|flur_kinder|hausflur|kinderschlafzimmer|kueche|schlafzimmer|spielzimmer_kinder|treppe|unten_kueche|unten_stube|waschhaus|wohnzimmer

// einzelnes Licht ein- bzw. ausschalten
// Bsp: [Bitte] schalte das Licht im Wohnzimmer an der Decke (ein|aus)
+ [@schaltenaliashoeflich] [@schaltenaliasfuellwoerter] [@schaltenaliashoeflich] [@schaltenaliasartikel] licht [@schaltenaliasorte] [@schaltenaliasartikel] (@roomsfull) [@schaltenaliasorte] [@schaltenaliasartikel] _ (@schaltenaliashandlung)
- <set lightroom={person}<star1>{/person}LI.>
^ <set lightname={formal}<star2>{/formal}>
^ Licht <get lightroom><get lightname> wird <star3>geschaltet
^ <call>fhem set <get lightroom>.*<get lightname>.* {person}<star3>{/person}</call>

// einzelnes Licht ein- bzw. ausschalten - anderer Satzbau
// Bsp: [Bitte] schalte das Licht an der Decke im Wohnzimmer (ein|aus)
+ [@schaltenaliashoeflich] [@schaltenaliasfuellwoerter] [@schaltenaliashoeflich] [@schaltenaliasartikel] licht [@schaltenaliasorte] [@schaltenaliasartikel] _ [@schaltenaliasorte] (@roomsfull) (@schaltenaliashandlung)
- <set lightroom={person}<star2>{/person}LI.>
^ <set lightname={formal}<star1>{/formal}>
^ Licht <get lightroom><get lightname> wird <star3>geschaltet
^ <call>fhem set <get lightroom>.*<get lightname>.* {person}<star3>{/person}</call>

// einzelnes Licht mit zweiteiligem Namen ein- bzw. ausschalten
// Bsp: [Bitte] schalte das Licht im Schlafzimmer hinten halogen (ein|aus)
+ [@schaltenaliashoeflich] [@schaltenaliasfuellwoerter] [@schaltenaliashoeflich] [@schaltenaliasartikel] licht [@schaltenaliasorte] [@schaltenaliasartikel] zwei worte _ _ [@schaltenaliasorte] (@roomsfull) (@schaltenaliashandlung)
- <set lightroom={person}<star3>{/person}LI.>
^ <set lightname={formal}<star1>{/formal}_{formal}<star2>{/formal}>
^ Licht <get lightroom><get lightname> wird <star4>geschaltet
^ <call>fhem set <get lightroom>.*<get lightname>.* {person}<star4>{/person}</call>

// Licht in einem Zimmer ein- bzw. ausschalten
// Bsp: [Bitte] schalte das Licht im Schlafzimmer (ein|aus)
+ [@schaltenaliashoeflich] [@schaltenaliasfuellwoerter] [@schaltenaliashoeflich] [@schaltenaliasartikel] licht [@schaltenaliasorte] [@schaltenaliasartikel] (@roomsfull) (@schaltenaliashandlung)
- <set light={person}<star1>{/person}LI.>
^ Licht {formal}<star1>{/formal} wird <star2>geschaltet
^ <call>fhem set <get light>.* {person}<star2>{/person}</call>
</pre>

Damit kann sind zum Beispiel für die Lampe am Küchenschrank folgende Sprachbefehle möglich (Begriffe in eckigen Klammen, wie z.B. [bitte] sind optional; durch | getrennte Begriffe in Klammern stellen Alternativen dar):
<pre>
[bitte] [schalte|mache] [das] Licht [in] [der] Küche [am] Küchenschrank (an|ein|aus)
[schalte|mache] [bitte] [das] Licht [in] [der] Küche [am] Küchenschrank (an|ein|aus)
[bitte] [schalte|mache] [das] Licht [am] Küchenschrank [in] [der] Küche (an|ein|aus)
[schalte|mache] [bitte] [das] Licht [am] Küchenschrank [in] [der] Küche (an|ein|aus)
[bitte] [das] Licht [am] Küchenschrank [in] [der] Küche (an|ein|aus)[schalten|machen]
[bitte] [das] Licht [in] [der] Küche [am] Küchenschrank (an|ein|aus)[schalten|machen]
</pre>

Wird die konkrete Lampe weggelassen, so wird das Licht im gesamten Raum ein-/ausgeschaltet:
<pre>
[bitte] [schalte|mache] [das] Licht [in] [der] Küche (an|ein|aus)
[schalte|mache] [bitte] [das] Licht [in] [der] Küche (an|ein|aus)
[bitte] [das] Licht [in] [der] Küche (an|ein|aus)[schalten|machen]
</pre>

Da ich auch Lampen habe, deren Beschreibung aus zwei durch _ getrennten Begriffen besteht (z.B. OG.sp.LI.Baggerschaufel_Podest ist die vordere Glühbirne einer Baggerlampe, welche ein Podest beleuchtet), habe ich zwei Möglichkeiten eingebaut, diese zu schalten:

1. Ankündigung, dass es sich um einen Begriff mit zwei Worten handelt:
<pre>
[bitte] [schalte|mache] [das] Licht [im] Küche [an] [der] zwei Worte Baggerschaufel Podest (an|ein|aus)
</pre>
(weitere Alternativen zum Satzbau wie oben)

2. Die Beschreibung wird beim schalten generell zwischen zwei ".*" gesetzt, so dass alle Devices geschaltet werden, auf welche die Beschreibung zutrifft. Dadurch führen auch die folgenden Befehle (in allen oben beschriebenen Satzbauvarianten) zum Erfolg:
<pre>
[bitte] [schalte|mache] [das] Licht [im] Küche [am] Podest (an|ein|aus)
[bitte] [schalte|mache] [das] Licht [im] Küche [an] [der] Baggerschaufel (an|ein|aus)
</pre>

Dadurch ist zu beachten, dass z.B. bei den beiden Lampen DG.sz.LI.Hinten_Led und DG.sz.LI.Hinten_Halogen mit
<pre>
[bitte] [schalte|mache] [das] Licht [im] Schlafzimmer hinten (an|ein|aus)
</pre>
beide Lampen geschaltet werden und mit
<pre>
[bitte] [schalte|mache] [das] Licht [im] Schlafzimmer Halogen (an|ein|aus)
</pre>
nur eine der beiden.

= Weblinks =
* Forumsartikel [https://forum.fhem.de/index.php/topic,54863.0.html Module: TALKTOME & TALKTOUSER - Sprachverarbeitung für Nutzerinteraktionen]
* Forumsartikel [https://forum.fhem.de/index.php/topic,39983.0.html Neuer FHEM Befehl "msg" für Benachrichtigungen]
* RiveScript [https://www.rivescript.com/docs/tutorial#first-steps First steps]
* Modul [[AMAD]]

[[Category:Examples]]
[[Category:HOWTOS]]
[[Category:Code Snippets]]
[[Categorie:Interfaces]]

DoorPi und FHEM

2016-06-27T06:05:47Z

SirUli: Klarstellung der Fisheye-Thematik

Das [https://www.doorpi.org/forum/ DoorPi-Projekt] dient dazu, auf Basis eines Raspberry Pi eine IP-Türsprechstelle aufzubauen. Dazu gibt es unter dem o.a. Link umfangreiche Informationen. Im Folgenden wird eine komplette DoorPi-Installation und ihre Integration in FHEM beschrieben.

=Funktion=
Die Software DoorPi läuft auf einem Raspberry Pi und stellt einen IP-Phone Client zur Verfügung, der in eine IP-Haustelefonanalage (z.B. mit der FritzBox) eingebunden werden kann. Diesen Raspberry Pi könnte man zwar über längere Audiokabel mit der notwendigen Lautsprecher-Mikrofon-Kombination verbinden, das ist allerdings etwas anfällig für Störsignale. Die meisten Anwender von DoorPi wählen deshalb den Einbau des Raspberry Pi direkt an der Türsprechstelle. Aus Sicht des Autors stellt das eine Sicherheitslücke dar - weil ein direkter Zugang ins Heimnetz außerhalb der eigenen vier Wände geschaffen würde.

Hier soll deshalb eine abgesetzte Installation beschrieben werden: Direkt an der Türsprechstelle sitzen nur Sensoren, Audiohardware und ein Display, angesteuert von einem "dummen" Arduino Mikrocontroller. Ins Innere des Hauses führen drei Kabel:
*Ein USB-Kabel zur digitalen Ankopplung der Audio-Hardware an den Raspberry Pi
*Ein HDMI-Kabel zur digitalen Ankopplung einer Kamera an den Raspberry Pi
*Ein 8-adriges Kabel zur Weiterleitung verschiedener Signale an den Raspberry Pi. Hierfür kann man aus Bequemlichkeitsgründen ein Netzwerk-Patchkabel verwenden - hochfrequente Signale gehen allerdings nicht über diesen Weg.

[[File:Doorpi_block.png]]

==Klingel und Türsprechstelle==
Beim Drücken auf den Klingelknopf wird ein IP-Telefonanruf gestartet - entweder bei einer internen Nummer, oder (konfigurierbar in FHEM) bei einer beliebigen anderen Nummer. Wenn der Empfänger den Ruf annimmt, kann er mit dem Besucher sprechen und ggf. durch das Drücken einer Taste die Tür öffnen. Es ist in der DoorPi-Installation problemlos konfigurierbar, beliebige andere Aktionen zu starten - z.B. könnte man dem Paketlieferanten nur das Gartentor öffnen.

Während des Klingelvorgangs wird eine Aufnahme des Besuchers angefertigt. Das Gespräch wird als WAV-Datei ebenfalls aufgezeichnet, beide sind unter dem FHEM-Frontend abrufbar. Während der Aufnahme wird eine Infrarot-Lichtquelle eingeschaltet. Diese soll nicht die ganze Szene ausleuchten - sondern verhindern, dass man das Gesicht des Besuchers wegen einer hinter ihm befindlichen Beleuchtung mit sichtbarem Licht nicht gut erkennen kann.

==Türöffnung==
Das System verfügt über einen iButton-Reader. Legt man einen iButton auf, der in der Software codiert ist, leuchtet eine im Reader integrierte Tricolor-LED in einer entsprechenden Farbe auf (z.B. roter iButton-Halter => rote LED). Der weitere Ablauf hängt vom Schließzustand der Haustür ab.
*Ist die Haustür nur zugezogen und nicht abgeschlossen, wird sie geöffnet. Gleichzeitig wird über die Türsprechstelle die Stimmnachricht ausgegeben "Willkommen zu Hause !", und auf einem im Haus befindlichen Tablet angesagt "Ein Bewohner betritt das Haus."
*Ist die Haustür abgeschlossen, wird zunächst auf dem Touchscreen des Systems statt der Namen eine virtuelle Tastatur angezeigt. Hier kann ggf. noch die akustische Bitte eingebaut werden, eine fünfstellige PIN einzugeben. Der Fortschritt bei der Eingabe wird durch einen Balken angezeigt.
**Ist die PIN falsch, geht das System wieder in den AUsgangszustand zurück, es wird eine Warnungsmeldung an das interne FHEM-System übermittelt.
**Ist die PIN korrekt, wird zunächst der Entriegelungsvorgang der Tür eingeleitet. Je nach verwendetem System kann das eine Weile dauern - Keymatic ist hierfür ein Beispiel, das können durchaus 3-4 Sekunden werden. Danach wird die Tür geöffnet, gleichzeitig wird über die Türsprechstelle die Stimmnachricht ausgegeben "Willkommen zu Hause !", und auf einem im Haus befindlichen Tablet angesagt "Ein Bewohner betritt das Haus." Je nach Konfiguration kann FHEM an dieser Stelle auch weitere Aktionen auslösen - etwa weitere Entriegelungsvorgänge starten.

==Videostream==
Auf dem Raspberry Pi ist auch die Software mjpeg_streamer installiert, Per Mausklick in der FHEM-Oberfläche wird mjpeg-streamer gestartet und gestoppt (das wird von der DoorPi-Software erledigt, die einen bestimmten virtuellen Tastdruck erkennt und dann lokal ein Skript startet), und stellt dann an TCP-Port 9000 einen Videostream bereit. Wer möchte, kann das System auch so konfigurieren, dass es diesen Videostream zusammen mit dem Audiostream zur Videotelefonie verwendet.
==Bewegungserkennung und Helligkeitsmessung==
Erkennt das System durch den eingebauten PIR-Bewegungsmelder eine Bewegung, wird
*die Anzeigehelligkeit für mindestens eine Minute hochgefahren
*ein Signal an FHEM gesendet.
Wenn eine Minute keine Bewegung erkannt wurde, geht die Anzeigehelligkeit (d.h. vom Display und dem LED-Rimng um den Klingelknopf) wieder auf einen Wert zurück, der durch die externe Helligkeit bestimmt ist.

=Hardware=
==Raspberry Pi==
Verwendet wird
* ein [http://www.pollin.de/shop/dt/OTQxNzkyOTk-/Bauelemente_Bauteile/Entwicklerboards/Raspberry_Pi/Raspberry_Pi_3_Modell_B.html Raspberry Pi 3], der ein integriertes WLAN-Modul besitzt
* eine Zusatzkarte [http://www.pollin.de/shop/dt/NTc1NzkyOTk-/Bauelemente_Bauteile/Entwicklerboards/Raspberry_Pi/Raspberry_Pi_B_Zusatzplatine_PIFACE_DIGITAL_2.html PiFace 2], mit je 8 digitalen Ein- und Ausgängen.
* ein klares [http://www.reichelt.de/CB-RPF-P-CLR/3/index.html?&ACTION=3&LA=446&ARTICLE=160959 Gehäuse], das die Erweiterungskarte mit aufnehmen kann

==Arduino==
* Ein Arduino Micro mit [https://www.doorpi.org/forum/attachment/293-henninghome-haustuer-txt/ Sketch]. Weitere Beispiele zur Auslesung von iButtons gibt es [http://ice-karlsruhe.de/projekte/smarthome/smarthome-hacks-links-und-ergaenzungen/#k6 hier]

==Kamera-Subsystem==
Verwendet werden hierfür
* eine Standard-NoIR-Kamera für den Raspberry Pi (ohne Infrarotfilter, somit IR-empfindlich) (z.B. von [http://www.elv.de/raspberry-pi-noir-kamera-modul.html ELV])
* ein Fisheye 180° zum Aufclippen auf Smartphones (Die untenstehenden STLs für den Kameradome sind auf Basis der "BRESSER Clip-On 180° Fisheye Smartphone-Linse" entworfen. [https://www.amazon.de/Bresser-Clip--Grad-Fisheye-Handylinse/dp/B00MQQSJKY Amazon] / [http://www.elv.de/bresser-handy-kameraaufsatz-clip-on-180-fisheye-handylinse.html ELV] / [https://www.conrad.de/de/smartphone-fish-eye-objektiv-bresser-optik-clip-on-180-fisheye-1359363.html Conrad])
* eine [http://www.ebay.de/itm/321915955373?_trksid=p2057872.m2749.l2649 Acrylglaskuppel] 2 Zoll
* eine [https://www.tindie.com/products/freto/pi-camera-hdmi-cable-extension/ Kabelverlängerung] Flatribbon <-> HDMI <-> Flatribbon
* ein Kameradom aus dem 3D-Drucker mit genauer Passung für das Fisheye vorne und die Kamera hinten, sowie Passungen für 8 LED. Die STL-Datei für diesen Kameradom findet man hier: [https://www.tinkercad.com/things/jv5x6lrihbk PiCameraDome4]
* eine Rückseite des Kameradoms aus dem 3D-Drucker, wird hinten mittig aufgeklebt und hält den Deckel des Kamerasystem durch drei Nippel. Die STL-Datei dafür findet man hier [https://tinkercad.com/things/cV6rkY6DWvc PiCameraDome4addendum]
* ein Deckel des Kameradoms aus dem 3D-Drucker, wird auf die Rückseite aufgesteckt und beinhaltet zwei Halterungen für Mikrofone (die "Ohren" im Bild). Die STL-Datei dafür findet man hier [https://tinkercad.com/things/8X0fhiSTyXk PiCameraDome4back]
* 9 x IR-LED [http://www.conrad.biz/ce/de/product/171140/IR-Emitter-940-nm-17-5-mm-radial-bedrahtet-Vishay-TSAL-6200 TSAL 6200] mit hoher Leistung
* 3 Widerstände 10 Ohm 0,2 W.

[[File:Dome1.jpg|400x300px]][[File:Dome2.jpg|400x300px]][[File:Doorpi_dome3s.jpg|400x300px]][[File:Doorpi_dome4s.jpg|600x300px]]

Zur Montage werden vier M2-Gewindebolzen in die hintere Aussparung des Kameradoms eingeklebt, und auf diese mit entsprechenden Abstandshaltern und Muttern sowohl die Kamera, als auch die eine Hälfte der Kabelverlängerung geschraubt. Dabei empfiehlt es sich, die LED vorher an Ort und Stelle zu haben - ggf. muss bei ungünstiger Klebung der Gewindebolzen bei den Eck-LED ein Gehäusevorsprung etwas abgefeilt werden.

Die Schaltung der LED für dem Betrieb an einer Spannung von 5V ausgelegt - damit fließen durch drei in Reihe geschaltete LED und einen 10 Ohm-Widerstand ziemlich genau 100mA. Bei der Schaltung über einen MOSFET ist das etwas weniger, wegen des Drain-Source-Widerstandes des MOSFET, reicht aber für die notwendige Helligkeit aus. Aus Symmetriegründen werden drei solche Stränge (insgesamt 9 LED) montiert - aber nur 8 davon sind bei dem angegebenen Kameradom nach außen gerichtet (wer möchte, kann gerne ein 3D-Design mit 9 Löchern erstellen), eine LED zeigt also nutzlos nach innen (erkennbar im 3. Bild der obigen Reihe).

Das Fischaugenobjektiv wird mit wenig (!) klarem Silikon in die vordere Öffnung des Kameradoms geklebt, der rückwärtige Aufsatz mit den 3 Nippeln mit Zweikomponentenkleber auf der Rückseite des Kameradoms befestigt. Dabei zur Ausrichtung den Mikrofonhalter (rechtes Bild, mit den "Ohren") probeweise aufstecken.

Die Acrylglaskuppel wird mit Silikon oder einem äquivalenten Dichtmaterial wasserdicht in die Frontplatte eingesetzt, auf diese dann von hinten der Kameradom. Eine staubdichte Verbindung erfordert auch hier die Abdichtung mit Silikon. Für den Fall einer möglichen Demontage empfiehlt es sich, diese Abdichtung nicht als Klebung zu verwenden, sondern als umlaufenden Rand nachträglich aufzubringen - der ist dann einfach mit einem Cutter zu entfernen.

==Audio-Subsystem==
* Soundkarte:
** [https://www.amazon.de/gp/product/B005BYCBO8 BIGtec USB Soundkarte 7.1 USB Adapter] (Gehäuse lässt sich problemlos [https://forum.fhem.de/index.php/topic,49877.msg444478.html#msg444478 entfernen])
** LogiLink USB Soundkarte mit Virtual 7.1 Soundeffekt
* Verstärker:
** [https://www.amazon.de/gp/product/B00UAA7NH8 Foxnovo High Power Super Mini Digital-Audioverstärker Board Platine (rot)]
* Lautsprecher:
** [https://www.reichelt.de/VIS-K28-40-8/3/index.html?&ACTION=3&LA=446&ARTICLE=145413&artnr=VIS+K28.40-8&SEARCH=kleinlautsprecher VISATON Kleinlautsprecher / 2,8 x 4 cm / 8 Ohm VIS K28.40-8]
** VISATON Kleinlautsprecher mit Kunststoffmembran und quadratischem Metallkorb 5 cm, K 50 SQ / 8 Ω

==Sensoren==
* Bewegungsmelder [http://www.elv.de/bewegungsmeldermodul-pir-13.html Bewegungsmelder]
* Fototransistor zur Helligkeitsmessung
* [https://www.amazon.de/gp/product/B01DKTHDXE Klingelknopf]
* Mikroschalter als Sabotagekontakt
* iButtonLesegerät, z.B.:
** [http://www.fuchs-shop.com/de/shop/16/1/13372564/ ohne LED]
** [http://www.fuchs-shop.com/de/shop/16/1/13372377/ mit LED] - Achtung evtl. nicht ausreichend Wetterfest
** [http://www.aliexpress.com/item/2PCS-TM-probe-DS9092-Zinc-Alloy-probe-iButton-probe-reader-with-LED-M98/32635390937.html aus Fernost]

Der Bewegungsmelder ist ein sehr kleines Modul, das einfach von hinten in eine Bohrung der Frontplatte gesteckt wird. Sein Open-Collector-Ausgang wird über eine der vier unbenutzen Adern (blau) des HDMI-Kabels an den Raspberry Pi weitergeleitet.

Der Helligkeitssensor besteht aus einem Fototransistor und zwei festen und einem einstellbaren Widerstand. Seine Ausgangsspannung wird an den Arduino weitergeleitet, der auf Grund dieses Wertes das Display und den LED-Ring des Klingelknopfes dimmt.

Als Klingelknopf wird ein Modell aus Edelstahl mit umlaufendem LED-Ring verwendet.

Der Sabotagekontakt besteht aus einem Mikroschalter, der so in die Rückwandinstallation geklebt wird, dass er bei der Abnahme der Frontplatte geschlossen wird. Dieses Signal wird über eine der unbenutzten Adern des HDMI-Kabels (orange im Bild) an den Raspberry Pi weitergeleitet.

[[File:DoorPi_part1.png|500x350px]][[File:doorpi_sensorss.jpg|800x350px]]

==Display==
* [http://wiki.iteadstudio.com/Nextion_HMI_Solution Nextion Display], z.B.:
** 3,2" 400x240 Pixel: [http://www.aliexpress.com/item/3-2-TFT-480x240-resistive-touch-screen-display-Nextion-3-2-HMI-LCD-Display-Module-TFT/32443541471.html Aus Fernost] oder [http://www.komputer.de/zen/index.php?main_page=product_info&cPath=30&products_id=354&zenid=like084ipplb747m4ur447p5h3 Aus Deutschland]

==Frontplatte==
Die Frontplatte besteht aus 4 mm starken Aluminium, eloxiert und auf 1/10 mm genau mit den passenden Bohrungen und Ausschnitten sowie rückseitig angeschweißten Gewindebolzen versehen. Online bestellbar z.B. bei der Schaeffer AG, für das vorliegende Exemplar wurden ca. 115 € in Rechnung gestellt. Auf Grund ihrer Stabilität dient diese Frontplatte als Baugruppenträger für die Außeninstallation.

[[File:Doorpi_front.jpg]]

==Rückwandinstallation==
Die Rückwandinstallation, die in des Mauerwerk eingelassen wird, kommt ebenfalls aus dem 3D-Drucker. Sie besteht aus drei Teilen mit unterschiedlicher Tiefe, um das Loch im Mauerwerk nicht zu groß werden zu lassen. Das obere und das untere Teil enthalten jeweils zwei stabile Vorsprünge mit Aussparungen, in die eine normgerechte M4-Mutter von unten genau hineinpasst. Bemerkenswert ist, dass dieses Bauteil nicht mit einer konventionellen Methode (z.B. im Spritzgussverfahren) gefertigt werden kann.

[[File:Doorpi_covertop.jpg]]

Diese Muttern kommen damit genau hinter den äußeren Schraubenlöchern der Frontplatte zu liegen, Die Frontplatte kann dadurch mit vier (Sicherheits-)schrauben M4 passgenau auf die im Mauerwerk sitzende Rückwandinstallation geschraubt werden.

Auf der Oberkante der drei Teile verläuft eine 1x1 mm² große Nut, in die eine Dichtung eingelegt werden kann.

DoorPi und FHEM

2016-06-26T18:46:06Z

SirUli: Link zu Quelltext des Arduino hinzugefügt

Das [https://www.doorpi.org/forum/ DoorPi-Projekt] dient dazu, auf Basis eines Raspberry Pi eine IP-Türsprechstelle aufzubauen. Dazu gibt es unter dem o.a. Link umfangreiche Informationen. Im Folgenden wird eine komplette DoorPi-Installation und ihre Integration in FHEM beschrieben.

=Funktion=
Die Software DoorPi läuft auf einem Raspberry Pi und stellt einen IP-Phone Client zur Verfügung, der in eine IP-Haustelefonanalage (z.B. mit der FritzBox) eingebunden werden kann. Diesen Raspberry Pi könnte man zwar über längere Audiokabel mit der notwendigen Lautsprecher-Mikrofon-Kombination verbinden, das ist allerdings etwas anfällig für Störsignale. Die meisten Anwender von DoorPi wählen deshalb den Einbau des Raspberry Pi direkt an der Türsprechstelle. Aus Sicht des Autors stellt das eine Sicherheitslücke dar - weil ein direkter Zugang ins Heimnetz außerhalb der eigenen vier Wände geschaffen würde.

Hier soll deshalb eine abgesetzte Installation beschrieben werden: Direkt an der Türsprechstelle sitzen nur Sensoren, Audiohardware und ein Display, angesteuert von einem "dummen" Arduino Mikrocontroller. Ins Innere des Hauses führen drei Kabel:
*Ein USB-Kabel zur digitalen Ankopplung der Audio-Hardware an den Raspberry Pi
*Ein HDMI-Kabel zur digitalen Ankopplung einer Kamera an den Raspberry Pi
*Ein 8-adriges Kabel zur Weiterleitung verschiedener Signale an den Raspberry Pi. Hierfür kann man aus Bequemlichkeitsgründen ein Netzwerk-Patchkabel verwenden - hochfrequente Signale gehen allerdings nicht über diesen Weg.

[[File:Doorpi_block.png]]

==Klingel und Türsprechstelle==
Beim Drücken auf den Klingelknopf wird ein IP-Telefonanruf gestartet - entweder bei einer internen Nummer, oder (konfigurierbar in FHEM) bei einer beliebigen anderen Nummer. Wenn der Empfänger den Ruf annimmt, kann er mit dem Besucher sprechen und ggf. durch das Drücken einer Taste die Tür öffnen. Es ist in der DoorPi-Installation problemlos konfigurierbar, beliebige andere Aktionen zu starten - z.B. könnte man dem Paketlieferanten nur das Gartentor öffnen.

Während des Klingelvorgangs wird eine Aufnahme des Besuchers angefertigt. Das Gespräch wird als WAV-Datei ebenfalls aufgezeichnet, beide sind unter dem FHEM-Frontend abrufbar. Während der Aufnahme wird eine Infrarot-Lichtquelle eingeschaltet. Diese soll nicht die ganze Szene ausleuchten - sondern verhindern, dass man das Gesicht des Besuchers wegen einer hinter ihm befindlichen Beleuchtung mit sichtbarem Licht nicht gut erkennen kann.

==Türöffnung==
Das System verfügt über einen iButton-Reader. Legt man einen iButton auf, der in der Software codiert ist, leuchtet eine im Reader integrierte Tricolor-LED in einer entsprechenden Farbe auf (z.B. roter iButton-Halter => rote LED). Der weitere Ablauf hängt vom Schließzustand der Haustür ab.
*Ist die Haustür nur zugezogen und nicht abgeschlossen, wird sie geöffnet. Gleichzeitig wird über die Türsprechstelle die Stimmnachricht ausgegeben "Willkommen zu Hause !", und auf einem im Haus befindlichen Tablet angesagt "Ein Bewohner betritt das Haus."
*Ist die Haustür abgeschlossen, wird zunächst auf dem Touchscreen des Systems statt der Namen eine virtuelle Tastatur angezeigt. Hier kann ggf. noch die akustische Bitte eingebaut werden, eine fünfstellige PIN einzugeben. Der Fortschritt bei der Eingabe wird durch einen Balken angezeigt.
**Ist die PIN falsch, geht das System wieder in den AUsgangszustand zurück, es wird eine Warnungsmeldung an das interne FHEM-System übermittelt.
**Ist die PIN korrekt, wird zunächst der Entriegelungsvorgang der Tür eingeleitet. Je nach verwendetem System kann das eine Weile dauern - Keymatic ist hierfür ein Beispiel, das können durchaus 3-4 Sekunden werden. Danach wird die Tür geöffnet, gleichzeitig wird über die Türsprechstelle die Stimmnachricht ausgegeben "Willkommen zu Hause !", und auf einem im Haus befindlichen Tablet angesagt "Ein Bewohner betritt das Haus." Je nach Konfiguration kann FHEM an dieser Stelle auch weitere Aktionen auslösen - etwa weitere Entriegelungsvorgänge starten.

==Videostream==
Auf dem Raspberry Pi ist auch die Software mjpeg_streamer installiert, Per Mausklick in der FHEM-Oberfläche wird mjpeg-streamer gestartet und gestoppt (das wird von der DoorPi-Software erledigt, die einen bestimmten virtuellen Tastdruck erkennt und dann lokal ein Skript startet), und stellt dann an TCP-Port 9000 einen Videostream bereit. Wer möchte, kann das System auch so konfigurieren, dass es diesen Videostream zusammen mit dem Audiostream zur Videotelefonie verwendet.
==Bewegungserkennung und Helligkeitsmessung==
Erkennt das System durch den eingebauten PIR-Bewegungsmelder eine Bewegung, wird
*die Anzeigehelligkeit für mindestens eine Minute hochgefahren
*ein Signal an FHEM gesendet.
Wenn eine Minute keine Bewegung erkannt wurde, geht die Anzeigehelligkeit (d.h. vom Display und dem LED-Rimng um den Klingelknopf) wieder auf einen Wert zurück, der durch die externe Helligkeit bestimmt ist.

=Hardware=
==Raspberry Pi==
Verwendet wird
* ein [http://www.pollin.de/shop/dt/OTQxNzkyOTk-/Bauelemente_Bauteile/Entwicklerboards/Raspberry_Pi/Raspberry_Pi_3_Modell_B.html Raspberry Pi 3], der ein integriertes WLAN-Modul besitzt
* eine Zusatzkarte [http://www.pollin.de/shop/dt/NTc1NzkyOTk-/Bauelemente_Bauteile/Entwicklerboards/Raspberry_Pi/Raspberry_Pi_B_Zusatzplatine_PIFACE_DIGITAL_2.html PiFace 2], mit je 8 digitalen Ein- und Ausgängen.
* ein klares [http://www.reichelt.de/CB-RPF-P-CLR/3/index.html?&ACTION=3&LA=446&ARTICLE=160959 Gehäuse], das die Erweiterungskarte mit aufnehmen kann

==Arduino==
* Ein Arduino Micro mit [https://www.doorpi.org/forum/attachment/293-henninghome-haustuer-txt/ Sketch]. Weitere Beispiele zur Auslesung von iButtons gibt es [http://ice-karlsruhe.de/projekte/smarthome/smarthome-hacks-links-und-ergaenzungen/#k6 hier]

==Kamera-Subsystem==
Verwendet werden hierfür
* eine Standard-NoIR-Kamera für den Raspberry Pi (ohne Infrarotfilter, somit IR-empfindlich) (z.B. von [http://www.elv.de/raspberry-pi-noir-kamera-modul.html ELV])
* ein Fisheye 180° zum Aufclippen auf Smartphones (z.B. [https://www.amazon.de/Bresser-Clip--Grad-Fisheye-Handylinse/dp/B00MQQSJKY Bresser])
* eine [http://www.ebay.de/itm/321915955373?_trksid=p2057872.m2749.l2649 Acrylglaskuppel] 2 Zoll
* eine [https://www.tindie.com/products/freto/pi-camera-hdmi-cable-extension/ Kabelverlängerung] Flatribbon <-> HDMI <-> Flatribbon
* ein Kameradom aus dem 3D-Drucker mit genauer Passung für das Fisheye vorne und die Kamera hinten, sowie Passungen für 8 LED. Die STL-Datei für diesen Kameradom findet man hier: [https://www.tinkercad.com/things/jv5x6lrihbk PiCameraDome4]
* eine Rückseite des Kameradoms aus dem 3D-Drucker, wird hinten mittig aufgeklebt und hält den Deckel des Kamerasystem durch drei Nippel. Die STL-Datei dafür findet man hier [https://tinkercad.com/things/cV6rkY6DWvc PiCameraDome4addendum]
* ein Deckel des Kameradoms aus dem 3D-Drucker, wird auf die Rückseite aufgesteckt und beinhaltet zwei Halterungen für Mikrofone (die "Ohren" im Bild). Die STL-Datei dafür findet man hier [https://tinkercad.com/things/8X0fhiSTyXk PiCameraDome4back]
* 9 x IR-LED [http://www.conrad.biz/ce/de/product/171140/IR-Emitter-940-nm-17-5-mm-radial-bedrahtet-Vishay-TSAL-6200 TSAL 6200] mit hoher Leistung
* 3 Widerstände 10 Ohm 0,2 W.

[[File:Dome1.jpg|400x300px]][[File:Dome2.jpg|400x300px]][[File:Doorpi_dome3s.jpg|400x300px]][[File:Doorpi_dome4s.jpg|600x300px]]

Zur Montage werden vier M2-Gewindebolzen in die hintere Aussparung des Kameradoms eingeklebt, und auf diese mit entsprechenden Abstandshaltern und Muttern sowohl die Kamera, als auch die eine Hälfte der Kabelverlängerung geschraubt. Dabei empfiehlt es sich, die LED vorher an Ort und Stelle zu haben - ggf. muss bei ungünstiger Klebung der Gewindebolzen bei den Eck-LED ein Gehäusevorsprung etwas abgefeilt werden.

Die Schaltung der LED für dem Betrieb an einer Spannung von 5V ausgelegt - damit fließen durch drei in Reihe geschaltete LED und einen 10 Ohm-Widerstand ziemlich genau 100mA. Bei der Schaltung über einen MOSFET ist das etwas weniger, wegen des Drain-Source-Widerstandes des MOSFET, reicht aber für die notwendige Helligkeit aus. Aus Symmetriegründen werden drei solche Stränge (insgesamt 9 LED) montiert - aber nur 8 davon sind bei dem angegebenen Kameradom nach außen gerichtet (wer möchte, kann gerne ein 3D-Design mit 9 Löchern erstellen), eine LED zeigt also nutzlos nach innen (erkennbar im 3. Bild der obigen Reihe).

Das Fischaugenobjektiv wird mit wenig (!) klarem Silikon in die vordere Öffnung des Kameradoms geklebt, der rückwärtige Aufsatz mit den 3 Nippeln mit Zweikomponentenkleber auf der Rückseite des Kameradoms befestigt. Dabei zur Ausrichtung den Mikrofonhalter (rechtes Bild, mit den "Ohren") probeweise aufstecken.

Die Acrylglaskuppel wird mit Silikon oder einem äquivalenten Dichtmaterial wasserdicht in die Frontplatte eingesetzt, auf diese dann von hinten der Kameradom. Eine staubdichte Verbindung erfordert auch hier die Abdichtung mit Silikon. Für den Fall einer möglichen Demontage empfiehlt es sich, diese Abdichtung nicht als Klebung zu verwenden, sondern als umlaufenden Rand nachträglich aufzubringen - der ist dann einfach mit einem Cutter zu entfernen.

==Audio-Subsystem==
* Soundkarte:
** [https://www.amazon.de/gp/product/B005BYCBO8 BIGtec USB Soundkarte 7.1 USB Adapter] (Gehäuse lässt sich problemlos [https://forum.fhem.de/index.php/topic,49877.msg444478.html#msg444478 entfernen])
** LogiLink USB Soundkarte mit Virtual 7.1 Soundeffekt
* Verstärker:
** [https://www.amazon.de/gp/product/B00UAA7NH8 Foxnovo High Power Super Mini Digital-Audioverstärker Board Platine (rot)]
* Lautsprecher:
** [https://www.reichelt.de/VIS-K28-40-8/3/index.html?&ACTION=3&LA=446&ARTICLE=145413&artnr=VIS+K28.40-8&SEARCH=kleinlautsprecher VISATON Kleinlautsprecher / 2,8 x 4 cm / 8 Ohm VIS K28.40-8]
** VISATON Kleinlautsprecher mit Kunststoffmembran und quadratischem Metallkorb 5 cm, K 50 SQ / 8 Ω

==Sensoren==
* [http://www.elv.de/bewegungsmeldermodul-pir-13.html Bewegungsmelder]
* Fototransistor zur Helligkeitsmessung
* [https://www.amazon.de/gp/product/B01DKTHDXE Klingelknopf]
* Mikroschalter als Sabotagekontakt
* iButtonLesegerät, z.B.:
** [http://www.fuchs-shop.com/de/shop/16/1/13372564/ ohne LED]
** [http://www.fuchs-shop.com/de/shop/16/1/13372377/ mit LED] - Achtung evtl. nicht ausreichend Wetterfest
** [http://www.aliexpress.com/item/2PCS-TM-probe-DS9092-Zinc-Alloy-probe-iButton-probe-reader-with-LED-M98/32635390937.html aus Fernost]

Der Bewegungsmelder ist ein sehr kleines Modul, das einfach von hinten in eine Bohrung der Frontplatte gesteckt wird. Sein Open-Collector-Ausgang wird über eine der vier unbenutzen Adern (blau) des HDMI-Kabels an den Raspberry Pi weitergeleitet.

Der Helligkeitssensor besteht aus einem Fototransistor und zwei festen und einem einstellbaren Widerstand. Seine Ausgangsspannung wird an den Arduino weitergeleitet, der auf Grund dieses Wertes das Display und den LED-Ring des Klingelknopfes dimmt.

Als Klingelknopf wird ein Modell aus Edelstahl mit umlaufendem LED-Ring verwendet.

Der Sabotagekontakt besteht aus einem Mikroschalter, der so in die Rückwandinstallation geklebt wird, dass er bei der Abnahme der Frontplatte geschlossen wird. Dieses Signal wird über eine der unbenutzten Adern des HDMI-Kabels (orange im Bild) an den Raspberry Pi weitergeleitet.

[[File:DoorPi_part1.png|500x350px]][[File:doorpi_sensorss.jpg|800x350px]]

==Display==
* [http://wiki.iteadstudio.com/Nextion_HMI_Solution Nextion Display], z.B.:
** 3,2" 400x240 Pixel: [http://www.aliexpress.com/item/3-2-TFT-480x240-resistive-touch-screen-display-Nextion-3-2-HMI-LCD-Display-Module-TFT/32443541471.html Aus Fernost] oder [http://www.komputer.de/zen/index.php?main_page=product_info&cPath=30&products_id=354&zenid=like084ipplb747m4ur447p5h3 Aus Deutschland]

==Frontplatte==
Die Frontplatte besteht aus 4 mm starken Aluminium, eloxiert und auf 1/10 mm genau mit den passenden Bohrungen und Ausschnitten sowie rückseitig angeschweißten Gewindebolzen versehen. Online bestellbar z.B. bei der Schaeffer AG, für das vorliegende Exemplar wurden ca. 115 € in Rechnung gestellt. Auf Grund ihrer Stabilität dient diese Frontplatte als Baugruppenträger für die Außeninstallation.

[[File:Doorpi_front.jpg]]

==Rückwandinstallation==
Die Rückwandinstallation, die in des Mauerwerk eingelassen wird, kommt ebenfalls aus dem 3D-Drucker. Sie besteht aus drei Teilen mit unterschiedlicher Tiefe, um das Loch im Mauerwerk nicht zu groß werden zu lassen. Das obere und das untere Teil enthalten jeweils zwei stabile Vorsprünge mit Aussparungen, in die eine normgerechte M4-Mutter von unten genau hineinpasst. Bemerkenswert ist, dass dieses Bauteil nicht mit einer konventionellen Methode (z.B. im Spritzgussverfahren) gefertigt werden kann.

[[File:Doorpi_covertop.jpg]]

Diese Muttern kommen damit genau hinter den äußeren Schraubenlöchern der Frontplatte zu liegen, Die Frontplatte kann dadurch mit vier (Sicherheits-)schrauben M4 passgenau auf die im Mauerwerk sitzende Rückwandinstallation geschraubt werden.

Auf der Oberkante der drei Teile verläuft eine 1x1 mm² große Nut, in die eine Dichtung eingelegt werden kann.

DoorPi und FHEM

2016-06-26T15:13:30Z

SirUli: Ein paar Links ergänzt

Das [https://www.doorpi.org/forum/ DoorPi-Projekt] dient dazu, auf Basis eines Raspberry Pi eine IP-Türsprechstelle aufzubauen. Dazu gibt es unter dem o.a. Link umfangreiche Informationen. Im Folgenden wird eine komplette DoorPi-Installation und ihre Integration in FHEM beschrieben.

=Funktion=
Die Software DoorPi läuft auf einem Raspberry Pi und stellt einen IP-Phone Client zur Verfügung, der in eine IP-Haustelefonanalage (z.B. mit der FritzBox) eingebunden werden kann. Diesen Raspberry Pi könnte man zwar über längere Audiokabel mit der notwendigen Lautsprecher-Mikrofon-Kombination verbinden, das ist allerdings etwas anfällig für Störsignale. Die meisten Anwender von DoorPi wählen deshalb den Einbau des Raspberry Pi direkt an der Türsprechstelle. Aus Sicht des Autors stellt das eine Sicherheitslücke dar - weil ein direkter Zugang ins Heimnetz außerhalb der eigenen vier Wände geschaffen würde.

Hier soll deshalb eine abgesetzte Installation beschrieben werden: Direkt an der Türsprechstelle sitzen nur Sensoren, Audiohardware und ein Display, angesteuert von einem "dummen" Arduino Mikrocontroller. Ins Innere des Hauses führen drei Kabel:
*Ein USB-Kabel zur digitalen Ankopplung der Audio-Hardware an den Raspberry Pi
*Ein HDMI-Kabel zur digitalen Ankopplung einer Kamera an den Raspberry Pi
*Ein 8-adriges Kabel zur Weiterleitung verschiedener Signale an den Raspberry Pi. Hierfür kann man aus Bequemlichkeitsgründen ein Netzwerk-Patchkabel verwenden - hochfrequente Signale gehen allerdings nicht über diesen Weg.

[[File:Doorpi_block.png]]

==Klingel und Türsprechstelle==
Beim Drücken auf den Klingelknopf wird ein IP-Telefonanruf gestartet - entweder bei einer internen Nummer, oder (konfigurierbar in FHEM) bei einer beliebigen anderen Nummer. Wenn der Empfänger den Ruf annimmt, kann er mit dem Besucher sprechen und ggf. durch das Drücken einer Taste die Tür öffnen. Es ist in der DoorPi-Installation problemlos konfigurierbar, beliebige andere Aktionen zu starten - z.B. könnte man dem Paketlieferanten nur das Gartentor öffnen.

Während des Klingelvorgangs wird eine Aufnahme des Besuchers angefertigt. Das Gespräch wird als WAV-Datei ebenfalls aufgezeichnet, beide sind unter dem FHEM-Frontend abrufbar. Während der Aufnahme wird eine Infrarot-Lichtquelle eingeschaltet. Diese soll nicht die ganze Szene ausleuchten - sondern verhindern, dass man das Gesicht des Besuchers wegen einer hinter ihm befindlichen Beleuchtung mit sichtbarem Licht nicht gut erkennen kann.

==Türöffnung==
Das System verfügt über einen iButton-Reader. Legt man einen iButton auf, der in der Software codiert ist, leuchtet eine im Reader integrierte Tricolor-LED in einer entsprechenden Farbe auf (z.B. roter iButton-Halter => rote LED). Der weitere Ablauf hängt vom Schließzustand der Haustür ab.
*Ist die Haustür nur zugezogen und nicht abgeschlossen, wird sie geöffnet. Gleichzeitig wird über die Türsprechstelle die Stimmnachricht ausgegeben "Willkommen zu Hause !", und auf einem im Haus befindlichen Tablet angesagt "Ein Bewohner betritt das Haus."
*Ist die Haustür abgeschlossen, wird zunächst auf dem Touchscreen des Systems statt der Namen eine virtuelle Tastatur angezeigt. Hier kann ggf. noch die akustische Bitte eingebaut werden, eine fünfstellige PIN einzugeben. Der Fortschritt bei der Eingabe wird durch einen Balken angezeigt.
**Ist die PIN falsch, geht das System wieder in den AUsgangszustand zurück, es wird eine Warnungsmeldung an das interne FHEM-System übermittelt.
**Ist die PIN korrekt, wird zunächst der Entriegelungsvorgang der Tür eingeleitet. Je nach verwendetem System kann das eine Weile dauern - Keymatic ist hierfür ein Beispiel, das können durchaus 3-4 Sekunden werden. Danach wird die Tür geöffnet, gleichzeitig wird über die Türsprechstelle die Stimmnachricht ausgegeben "Willkommen zu Hause !", und auf einem im Haus befindlichen Tablet angesagt "Ein Bewohner betritt das Haus." Je nach Konfiguration kann FHEM an dieser Stelle auch weitere Aktionen auslösen - etwa weitere Entriegelungsvorgänge starten.

==Videostream==
Auf dem Raspberry Pi ist auch die Software mjpeg_streamer installiert, Per Mausklick in der FHEM-Oberfläche wird mjpeg-streamer gestartet und gestoppt (das wird von der DoorPi-Software erledigt, die einen bestimmten virtuellen Tastdruck erkennt und dann lokal ein Skript startet), und stellt dann an TCP-Port 9000 einen Videostream bereit. Wer möchte, kann das System auch so konfigurieren, dass es diesen Videostream zusammen mit dem Audiostream zur Videotelefonie verwendet.
==Bewegungserkennung und Helligkeitsmessung==
Erkennt das System durch den eingebauten PIR-Bewegungsmelder eine Bewegung, wird
*die Anzeigehelligkeit für mindestens eine Minute hochgefahren
*ein Signal an FHEM gesendet.
Wenn eine Minute keine Bewegung erkannt wurde, geht die Anzeigehelligkeit (d.h. vom Display und dem LED-Rimng um den Klingelknopf) wieder auf einen Wert zurück, der durch die externe Helligkeit bestimmt ist.

=Hardware=
==Raspberry Pi==
Verwendet wird
* ein [http://www.pollin.de/shop/dt/OTQxNzkyOTk-/Bauelemente_Bauteile/Entwicklerboards/Raspberry_Pi/Raspberry_Pi_3_Modell_B.html Raspberry Pi 3], der ein integriertes WLAN-Modul besitzt
* eine Zusatzkarte [http://www.pollin.de/shop/dt/NTc1NzkyOTk-/Bauelemente_Bauteile/Entwicklerboards/Raspberry_Pi/Raspberry_Pi_B_Zusatzplatine_PIFACE_DIGITAL_2.html PiFace 2], mit je 8 digitalen Ein- und Ausgängen.
* ein klares [http://www.reichelt.de/CB-RPF-P-CLR/3/index.html?&ACTION=3&LA=446&ARTICLE=160959 Gehäuse], das die Erweiterungskarte mit aufnehmen kann

==Arduino==
* Ein Arduino Micro. Der Sketch ist derzeit noch nicht Verfügbar, beispiele zur Auslesung von iButtons gibt es [http://ice-karlsruhe.de/projekte/smarthome/smarthome-hacks-links-und-ergaenzungen/#k6 hier]

==Kamera-Subsystem==
Verwendet werden hierfür
* eine Standard-NoIR-Kamera für den Raspberry Pi (ohne Infrarotfilter, somit IR-empfindlich) (z.B. von [http://www.elv.de/raspberry-pi-noir-kamera-modul.html ELV])
* ein Fisheye 180° zum Aufclippen auf Smartphones (z.B. [https://www.amazon.de/Bresser-Clip--Grad-Fisheye-Handylinse/dp/B00MQQSJKY Bresser])
* eine [http://www.ebay.de/itm/321915955373?_trksid=p2057872.m2749.l2649 Acrylglaskuppel] 2 Zoll
* eine [https://www.tindie.com/products/freto/pi-camera-hdmi-cable-extension/ Kabelverlängerung] Flatribbon <-> HDMI <-> Flatribbon
* ein Kameradom aus dem 3D-Drucker mit genauer Passung für das Fisheye vorne und die Kamera hinten, sowie Passungen für 8 LED. Die STL-Datei für diesen Kameradom findet man hier: [https://www.tinkercad.com/things/jv5x6lrihbk PiCameraDome4]
* eine Rückseite des Kameradoms aus dem 3D-Drucker, wird hinten mittig aufgeklebt und hält den Deckel des Kamerasystem durch drei Nippel. Die STL-Datei dafür findet man hier [https://tinkercad.com/things/cV6rkY6DWvc PiCameraDome4addendum]
* ein Deckel des Kameradoms aus dem 3D-Drucker, wird auf die Rückseite aufgesteckt und beinhaltet zwei Halterungen für Mikrofone (die "Ohren" im Bild). Die STL-Datei dafür findet man hier [https://tinkercad.com/things/8X0fhiSTyXk PiCameraDome4back]
* 9 x IR-LED [http://www.conrad.biz/ce/de/product/171140/IR-Emitter-940-nm-17-5-mm-radial-bedrahtet-Vishay-TSAL-6200 TSAL 6200] mit hoher Leistung
* 3 Widerstände 10 Ohm 0,2 W.

[[File:Dome1.jpg|400x300px]][[File:Dome2.jpg|400x300px]][[File:Doorpi_dome3s.jpg|400x300px]][[File:Doorpi_dome4s.jpg|600x300px]]

Zur Montage werden vier M2-Gewindebolzen in die hintere Aussparung des Kameradoms eingeklebt, und auf diese mit entsprechenden Abstandshaltern und Muttern sowohl die Kamera, als auch die eine Hälfte der Kabelverlängerung geschraubt. Dabei empfiehlt es sich, die LED vorher an Ort und Stelle zu haben - ggf. muss bei ungünstiger Klebung der Gewindebolzen bei den Eck-LED ein Gehäusevorsprung etwas abgefeilt werden.

Die Schaltung der LED für dem Betrieb an einer Spannung von 5V ausgelegt - damit fließen durch drei in Reihe geschaltete LED und einen 10 Ohm-Widerstand ziemlich genau 100mA. Bei der Schaltung über einen MOSFET ist das etwas weniger, wegen des Drain-Source-Widerstandes des MOSFET, reicht aber für die notwendige Helligkeit aus. Aus Symmetriegründen werden drei solche Stränge (insgesamt 9 LED) montiert - aber nur 8 davon sind bei dem angegebenen Kameradom nach außen gerichtet (wer möchte, kann gerne ein 3D-Design mit 9 Löchern erstellen), eine LED zeigt also nutzlos nach innen (erkennbar im 3. Bild der obigen Reihe).

Das Fischaugenobjektiv wird mit wenig (!) klarem Silikon in die vordere Öffnung des Kameradoms geklebt, der rückwärtige Aufsatz mit den 3 Nippeln mit Zweikomponentenkleber auf der Rückseite des Kameradoms befestigt. Dabei zur Ausrichtung den Mikrofonhalter (rechtes Bild, mit den "Ohren") probeweise aufstecken.

Die Acrylglaskuppel wird mit Silikon oder einem äquivalenten Dichtmaterial wasserdicht in die Frontplatte eingesetzt, auf diese dann von hinten der Kameradom. Eine staubdichte Verbindung erfordert auch hier die Abdichtung mit Silikon. Für den Fall einer möglichen Demontage empfiehlt es sich, diese Abdichtung nicht als Klebung zu verwenden, sondern als umlaufenden Rand nachträglich aufzubringen - der ist dann einfach mit einem Cutter zu entfernen.

==Audio-Subsystem==
* Soundkarte:
** [https://www.amazon.de/gp/product/B005BYCBO8 BIGtec USB Soundkarte 7.1 USB Adapter] (Gehäuse lässt sich problemlos [https://forum.fhem.de/index.php/topic,49877.msg444478.html#msg444478 entfernen])
** LogiLink USB Soundkarte mit Virtual 7.1 Soundeffekt
* Verstärker:
** [https://www.amazon.de/gp/product/B00UAA7NH8 Foxnovo High Power Super Mini Digital-Audioverstärker Board Platine (rot)]
* Lautsprecher:
** [https://www.reichelt.de/VIS-K28-40-8/3/index.html?&ACTION=3&LA=446&ARTICLE=145413&artnr=VIS+K28.40-8&SEARCH=kleinlautsprecher VISATON Kleinlautsprecher / 2,8 x 4 cm / 8 Ohm VIS K28.40-8]
** VISATON Kleinlautsprecher mit Kunststoffmembran und quadratischem Metallkorb 5 cm, K 50 SQ / 8 Ω

==Sensoren==
* [http://www.elv.de/bewegungsmeldermodul-pir-13.html Bewegungsmelder]
* Fototransistor zur Helligkeitsmessung
* [https://www.amazon.de/gp/product/B01DKTHDXE Klingelknopf]
* Mikroschalter als Sabotagekontakt
* iButtonLesegerät, z.B.:
** [http://www.fuchs-shop.com/de/shop/16/1/13372564/ ohne LED]
** [http://www.fuchs-shop.com/de/shop/16/1/13372377/ mit LED] - Achtung evtl. nicht ausreichend Wetterfest
** [http://www.aliexpress.com/item/2PCS-TM-probe-DS9092-Zinc-Alloy-probe-iButton-probe-reader-with-LED-M98/32635390937.html aus Fernost]

Der Bewegungsmelder ist ein sehr kleines Modul, das einfach von hinten in eine Bohrung der Frontplatte gesteckt wird. Sein Open-Collector-Ausgang wird über eine der vier unbenutzen Adern (blau) des HDMI-Kabels an den Raspberry Pi weitergeleitet.

Der Helligkeitssensor besteht aus einem Fototransistor und zwei festen und einem einstellbaren Widerstand. Seine Ausgangsspannung wird an den Arduino weitergeleitet, der auf Grund dieses Wertes das Display und den LED-Ring des Klingelknopfes dimmt.

Als Klingelknopf wird ein Modell aus Edelstahl mit umlaufendem LED-Ring verwendet.

Der Sabotagekontakt besteht aus einem Mikroschalter, der so in die Rückwandinstallation geklebt wird, dass er bei der Abnahme der Frontplatte geschlossen wird. Dieses Signal wird über eine der unbenutzten Adern des HDMI-Kabels (orange im Bild) an den Raspberry Pi weitergeleitet.

[[File:DoorPi_part1.png|500x350px]][[File:doorpi_sensorss.jpg|800x350px]]

==Display==
* [http://wiki.iteadstudio.com/Nextion_HMI_Solution Nextion Display], z.B.:
** 3,2" 400x240 Pixel: [http://www.aliexpress.com/item/3-2-TFT-480x240-resistive-touch-screen-display-Nextion-3-2-HMI-LCD-Display-Module-TFT/32443541471.html Aus Fernost] oder [http://www.komputer.de/zen/index.php?main_page=product_info&cPath=30&products_id=354&zenid=like084ipplb747m4ur447p5h3 Aus Deutschland]

==Frontplatte==
Die Frontplatte besteht aus 4 mm starken Aluminium, eloxiert und auf 1/10 mm genau mit den passenden Bohrungen und Ausschnitten sowie rückseitig angeschweißten Gewindebolzen versehen. Online bestellbar z.B. bei der Schaeffer AG, für das vorliegende Exemplar wurden ca. 115 € in Rechnung gestellt. Auf Grund ihrer Stabilität dient diese Frontplatte als Baugruppenträger für die Außeninstallation.

[[File:Doorpi_front.jpg]]

==Rückwandinstallation==
Die Rückwandinstallation, die in des Mauerwerk eingelassen wird, kommt ebenfalls aus dem 3D-Drucker. Sie besteht aus drei Teilen mit unterschiedlicher Tiefe, um das Loch im Mauerwerk nicht zu groß werden zu lassen. Das obere und das untere Teil enthalten jeweils zwei stabile Vorsprünge mit Aussparungen, in die eine normgerechte M4-Mutter von unten genau hineinpasst. Bemerkenswert ist, dass dieses Bauteil nicht mit einer konventionellen Methode (z.B. im Spritzgussverfahren) gefertigt werden kann.

[[File:Doorpi_covertop.jpg]]

Diese Muttern kommen damit genau hinter den äußeren Schraubenlöchern der Frontplatte zu liegen, Die Frontplatte kann dadurch mit vier (Sicherheits-)schrauben M4 passgenau auf die im Mauerwerk sitzende Rückwandinstallation geschraubt werden.

Auf der Oberkante der drei Teile verläuft eine 1x1 mm² große Nut, in die eine Dichtung eingelegt werden kann.

DoorPi und FHEM

2016-06-26T14:49:15Z

SirUli: Weitere Links ergänzt bezüglich des Displays & Audio Systems

Das [https://www.doorpi.org/forum/ DoorPi-Projekt] dient dazu, auf Basis eines Raspberry Pi eine IP-Türsprechstelle aufzubauen. Dazu gibt es unter dem o.a. Link umfangreiche Informationen. Im Folgenden wird eine komplette DoorPi-Installation und ihre Integration in FHEM beschrieben.

=Funktion=
Die Software DoorPi läuft auf einem Raspberry Pi und stellt einen IP-Phone Client zur Verfügung, der in eine IP-Haustelefonanalage (z.B. mit der FritzBox) eingebunden werden kann. Diesen Raspberry Pi könnte man zwar über längere Audiokabel mit der notwendigen Lautsprecher-Mikrofon-Kombination verbinden, das ist allerdings etwas anfällig für Störsignale. Die meisten Anwender von DoorPi wählen deshalb den Einbau des Raspberry Pi direkt an der Türsprechstelle. Aus Sicht des Autors stellt das eine Sicherheitslücke dar - weil ein direkter Zugang ins Heimnetz außerhalb der eigenen vier Wände geschaffen würde.

Hier soll deshalb eine abgesetzte Installation beschrieben werden: Direkt an der Türsprechstelle sitzen nur Sensoren, Audiohardware und ein Display, angesteuert von einem "dummen" Arduino Mikrocontroller. Ins Innere des Hauses führen drei Kabel:
*Ein USB-Kabel zur digitalen Ankopplung der Audio-Hardware an den Raspberry Pi
*Ein HDMI-Kabel zur digitalen Ankopplung einer Kamera an den Raspberry Pi
*Ein 8-adriges Kabel zur Weiterleitung verschiedener Signale an den Raspberry Pi. Hierfür kann man aus Bequemlichkeitsgründen ein Netzwerk-Patchkabel verwenden - hochfrequente Signale gehen allerdings nicht über diesen Weg.

[[File:Doorpi_block.png]]

==Klingel und Türsprechstelle==
Beim Drücken auf den Klingelknopf wird ein IP-Telefonanruf gestartet - entweder bei einer internen Nummer, oder (konfigurierbar in FHEM) bei einer beliebigen anderen Nummer. Wenn der Empfänger den Ruf annimmt, kann er mit dem Besucher sprechen und ggf. durch das Drücken einer Taste die Tür öffnen. Es ist in der DoorPi-Installation problemlos konfigurierbar, beliebige andere Aktionen zu starten - z.B. könnte man dem Paketlieferanten nur das Gartentor öffnen.

Während des Klingelvorgangs wird eine Aufnahme des Besuchers angefertigt. Das Gespräch wird als WAV-Datei ebenfalls aufgezeichnet, beide sind unter dem FHEM-Frontend abrufbar. Während der Aufnahme wird eine Infrarot-Lichtquelle eingeschaltet. Diese soll nicht die ganze Szene ausleuchten - sondern verhindern, dass man das Gesicht des Besuchers wegen einer hinter ihm befindlichen Beleuchtung mit sichtbarem Licht nicht gut erkennen kann.

==Türöffnung==
Das System verfügt über einen iButton-Reader. Legt man einen iButton auf, der in der Software codiert ist, leuchtet eine im Reader integrierte Tricolor-LED in einer entsprechenden Farbe auf (z.B. roter iButton-Halter => rote LED). Der weitere Ablauf hängt vom Schließzustand der Haustür ab.
*Ist die Haustür nur zugezogen und nicht abgeschlossen, wird sie geöffnet. Gleichzeitig wird über die Türsprechstelle die Stimmnachricht ausgegeben "Willkommen zu Hause !", und auf einem im Haus befindlichen Tablet angesagt "Ein Bewohner betritt das Haus."
*Ist die Haustür abgeschlossen, wird zunächst auf dem Touchscreen des Systems statt der Namen eine virtuelle Tastatur angezeigt. Hier kann ggf. noch die akustische Bitte eingebaut werden, eine fünfstellige PIN einzugeben. Der Fortschritt bei der Eingabe wird durch einen Balken angezeigt.
**Ist die PIN falsch, geht das System wieder in den AUsgangszustand zurück, es wird eine Warnungsmeldung an das interne FHEM-System übermittelt.
**Ist die PIN korrekt, wird zunächst der Entriegelungsvorgang der Tür eingeleitet. Je nach verwendetem System kann das eine Weile dauern - Keymatic ist hierfür ein Beispiel, das können durchaus 3-4 Sekunden werden. Danach wird die Tür geöffnet, gleichzeitig wird über die Türsprechstelle die Stimmnachricht ausgegeben "Willkommen zu Hause !", und auf einem im Haus befindlichen Tablet angesagt "Ein Bewohner betritt das Haus." Je nach Konfiguration kann FHEM an dieser Stelle auch weitere Aktionen auslösen - etwa weitere Entriegelungsvorgänge starten.

==Videostream==
Auf dem Raspberry Pi ist auch die Software mjpeg_streamer installiert, Per Mausklick in der FHEM-Oberfläche wird mjpeg-streamer gestartet und gestoppt (das wird von der DoorPi-Software erledigt, die einen bestimmten virtuellen Tastdruck erkennt und dann lokal ein Skript startet), und stellt dann an TCP-Port 9000 einen Videostream bereit. Wer möchte, kann das System auch so konfigurieren, dass es diesen Videostream zusammen mit dem Audiostream zur Videotelefonie verwendet.
==Bewegungserkennung und Helligkeitsmessung==
Erkennt das System durch den eingebauten PIR-Bewegungsmelder eine Bewegung, wird
*die Anzeigehelligkeit für mindestens eine Minute hochgefahren
*ein Signal an FHEM gesendet.
Wenn eine Minute keine Bewegung erkannt wurde, geht die Anzeigehelligkeit (d.h. vom Display und dem LED-Rimng um den Klingelknopf) wieder auf einen Wert zurück, der durch die externe Helligkeit bestimmt ist.

=Hardware=
==Raspberry Pi==
Verwendet wird
* ein [http://www.pollin.de/shop/dt/OTQxNzkyOTk-/Bauelemente_Bauteile/Entwicklerboards/Raspberry_Pi/Raspberry_Pi_3_Modell_B.html Raspberry Pi 3], der ein integriertes WLAN-Modul besitzt
* eine Zusatzkarte [http://www.pollin.de/shop/dt/NTc1NzkyOTk-/Bauelemente_Bauteile/Entwicklerboards/Raspberry_Pi/Raspberry_Pi_B_Zusatzplatine_PIFACE_DIGITAL_2.html PiFace 2], mit je 8 digitalen Ein- und Ausgängen.
* ein klares [http://www.reichelt.de/CB-RPF-P-CLR/3/index.html?&ACTION=3&LA=446&ARTICLE=160959 Gehäuse], das die Erweiterungskarte mit aufnehmen kann

==Arduino==
* Ein Arduino Micro, welcher mit beispielsweise mit dem Sketch von [http://ice-karlsruhe.de/projekte/smarthome/smarthome-hacks-links-und-ergaenzungen/#k6 hier] programmiert wird

==Kamera-Subsystem==
Verwendet werden hierfür
* eine Standard-NoIR-Kamera für den Raspberry Pi (ohne Infrarotfilter, somit IR-empfindlich)
* ein [https://www.amazon.de/Bresser-Clip--Grad-Fisheye-Handylinse/dp/B00MQQSJKY Bresser Fisheye] 180° zum Aufclippen auf Smartphones
* eine [http://www.ebay.de/itm/321915955373?_trksid=p2057872.m2749.l2649 Acrylglaskuppel] 2 Zoll
* eine [https://www.tindie.com/products/freto/pi-camera-hdmi-cable-extension/ Kabelverlängerung] Flatribbon <-> HDMI <-> Flatribbon
* ein Kameradom aus dem 3D-Drucker mit genauer Passung für das Fisheye vorne und die Kamera hinten, sowie Passungen für 8 LED.Die STL-Datei für diesen Kameradom findet man hier: [https://www.tinkercad.com/things/jv5x6lrihbk PiCameraDome4]
* eine Rückseite des Kameradoms aus dem 3D-Drucker, wird hinten mittig aufgeklebt und hält den Deckel des Kamerasystem durch drei Nippel. Die STL-Datei dafür findet man hier [https://tinkercad.com/things/cV6rkY6DWvc PiCameraDome4addendum]
* ein Deckel des Kameradoms aus dem 3D-Drucker, wird auf die Rückseite aufgesteckt und beinhaltet zwei Halterungen für Mikrofone (die "Ohren" im Bild). Die STL-Datei dafür findet man hier [https://tinkercad.com/things/8X0fhiSTyXk PiCameraDome4back]
* 9 x IR-LED [http://www.conrad.biz/ce/de/product/171140/IR-Emitter-940-nm-17-5-mm-radial-bedrahtet-Vishay-TSAL-6200 TSAL 6200] mit hoher Leistung
* 3 Widerstände 10 Ohm 0,2 W.

[[File:Dome1.jpg|400x300px]][[File:Dome2.jpg|400x300px]][[File:Doorpi_dome3s.jpg|400x300px]][[File:Doorpi_dome4s.jpg|600x300px]]

Zur Montage werden vier M2-Gewindebolzen in die hintere Aussparung des Kameradoms eingeklebt, und auf diese mit entsprechenden Abstandshaltern und Muttern sowohl die Kamera, als auch die eine Hälfte der Kabelverlängerung geschraubt. Dabei empfiehlt es sich, die LED vorher an Ort und Stelle zu haben - ggf. muss bei ungünstiger Klebung der Gewindebolzen bei den Eck-LED ein Gehäusevorsprung etwas abgefeilt werden.

Die Schaltung der LED für dem Betrieb an einer Spannung von 5V ausgelegt - damit fließen durch drei in Reihe geschaltete LED und einen 10 Ohm-Widerstand ziemlich genau 100mA. Bei der Schaltung über einen MOSFET ist das etwas weniger, wegen des Drain-Source-Widerstandes des MOSFET, reicht aber für die notwendige Helligkeit aus. Aus Symmetriegründen werden drei solche Stränge (insgesamt 9 LED) montiert - aber nur 8 davon sind bei dem angegebenen Kameradom nach außen gerichtet (wer möchte, kann gerne ein 3D-Design mit 9 Löchern erstellen), eine LED zeigt also nutzlos nach innen (erkennbar im 3. Bild der obigen Reihe).

Das Fischaugenobjektiv wird mit wenig (!) klarem Silikon in die vordere Öffnung des Kameradoms geklebt, der rückwärtige Aufsatz mit den 3 Nippeln mit Zweikomponentenkleber auf der Rückseite des Kameradoms befestigt. Dabei zur Ausrichtung den Mikrofonhalter (rechtes Bild, mit den "Ohren") probeweise aufstecken.

Die Acrylglaskuppel wird mit Silikon oder einem äquivalenten Dichtmaterial wasserdicht in die Frontplatte eingesetzt, auf diese dann von hinten der Kameradom. Eine staubdichte Verbindung erfordert auch hier die Abdichtung mit Silikon. Für den Fall einer möglichen Demontage empfiehlt es sich, diese Abdichtung nicht als Klebung zu verwenden, sondern als umlaufenden Rand nachträglich aufzubringen - der ist dann einfach mit einem Cutter zu entfernen.

==Audio-Subsystem==
* Soundkarte:
** [https://www.amazon.de/gp/product/B005BYCBO8 BIGtec USB Soundkarte 7.1 USB Adapter] (Gehäuse lässt sich problemlos [https://forum.fhem.de/index.php/topic,49877.msg444478.html#msg444478 entfernen])
** LogiLink USB Soundkarte mit Virtual 7.1 Soundeffekt
* Verstärker:
** [https://www.amazon.de/gp/product/B00UAA7NH8 Foxnovo High Power Super Mini Digital-Audioverstärker Board Platine (rot)]
* Lautsprecher:
** [https://www.reichelt.de/VIS-K28-40-8/3/index.html?&ACTION=3&LA=446&ARTICLE=145413&artnr=VIS+K28.40-8&SEARCH=kleinlautsprecher VISATON Kleinlautsprecher / 2,8 x 4 cm / 8 Ohm VIS K28.40-8]
** VISATON Kleinlautsprecher mit Kunststoffmembran und quadratischem Metallkorb 5 cm, K 50 SQ / 8 Ω

==Sensoren==
* [http://www.elv.de/bewegungsmeldermodul-pir-13.html Bewegungsmelder]
* Fototransistor zur Helligkeitsmessung
* [https://www.amazon.de/gp/product/B01DKTHDXE Klingelknopf]
* Mikroschalter als Sabotagekontakt
* iButtonLesegerät, z.B.:
** [http://www.fuchs-shop.com/de/shop/16/1/13372564/ ohne LED]
** [http://www.fuchs-shop.com/de/shop/16/1/13372377/ mit LED] - Achtung evtl. nicht ausreichend Wetterfest
** [http://www.aliexpress.com/item/2PCS-TM-probe-DS9092-Zinc-Alloy-probe-iButton-probe-reader-with-LED-M98/32635390937.html aus Fernost]

Der Bewegungsmelder ist ein sehr kleines Modul, das einfach von hinten in eine Bohrung der Frontplatte gesteckt wird. Sein Open-Collector-Ausgang wird über eine der vier unbenutzen Adern (blau) des HDMI-Kabels an den Raspberry Pi weitergeleitet.

Der Helligkeitssensor besteht aus einem Fototransistor und zwei festen und einem einstellbaren Widerstand. Seine Ausgangsspannung wird an den Arduino weitergeleitet, der auf Grund dieses Wertes das Display und den LED-Ring des Klingelknopfes dimmt.

Als Klingelknopf wird ein Modell aus Edelstahl mit umlaufendem LED-Ring verwendet.

Der Sabotagekontakt besteht aus einem Mikroschalter, der so in die Rückwandinstallation geklebt wird, dass er bei der Abnahme der Frontplatte geschlossen wird. Dieses Signal wird über eine der unbenutzten Adern des HDMI-Kabels (orange im Bild) an den Raspberry Pi weitergeleitet.

[[File:DoorPi_part1.png|500x350px]][[File:doorpi_sensorss.jpg|800x350px]]

==Display==
* [http://wiki.iteadstudio.com/Nextion_HMI_Solution Nextion Display], z.B.:
** 3,2" 400x240 Pixel: [http://www.aliexpress.com/item/3-2-TFT-480x240-resistive-touch-screen-display-Nextion-3-2-HMI-LCD-Display-Module-TFT/32443541471.html Aus Fernost] oder [http://www.komputer.de/zen/index.php?main_page=product_info&cPath=30&products_id=354&zenid=like084ipplb747m4ur447p5h3 Aus Deutschland]

==Frontplatte==
Die Frontplatte besteht aus 4 mm starken Aluminium, eloxiert und auf 1/10 mm genau mit den passenden Bohrungen und Ausschnitten sowie rückseitig angeschweißten Gewindebolzen versehen. Online bestellbar z.B. bei der Schaeffer AG, für das vorliegende Exemplar wurden ca. 115 € in Rechnung gestellt. Auf Grund ihrer Stabilität dient diese Frontplatte als Baugruppenträger für die Außeninstallation.

[[File:Doorpi_front.jpg]]

==Rückwandinstallation==
Die Rückwandinstallation, die in des Mauerwerk eingelassen wird, kommt ebenfalls aus dem 3D-Drucker. Sie besteht aus drei Teilen mit unterschiedlicher Tiefe, um das Loch im Mauerwerk nicht zu groß werden zu lassen. Das obere und das untere Teil enthalten jeweils zwei stabile Vorsprünge mit Aussparungen, in die eine normgerechte M4-Mutter von unten genau hineinpasst. Bemerkenswert ist, dass dieses Bauteil nicht mit einer konventionellen Methode (z.B. im Spritzgussverfahren) gefertigt werden kann.

[[File:Doorpi_covertop.jpg]]

Diese Muttern kommen damit genau hinter den äußeren Schraubenlöchern der Frontplatte zu liegen, Die Frontplatte kann dadurch mit vier (Sicherheits-)schrauben M4 passgenau auf die im Mauerwerk sitzende Rückwandinstallation geschraubt werden.

Auf der Oberkante der drei Teile verläuft eine 1x1 mm² große Nut, in die eine Dichtung eingelegt werden kann.

DoorPi und FHEM

2016-06-26T13:57:11Z

SirUli: Schönheitsfehler in einigen Links korrigiert

Das [https://www.doorpi.org/forum/ DoorPi-Projekt] dient dazu, auf Basis eines Raspberry Pi eine IP-Türsprechstelle aufzubauen. Dazu gibt es unter dem o.a. Link umfangreiche Informationen. Im Folgenden wird eine komplette DoorPi-Installation und ihre Integration in FHEM beschrieben.

=Funktion=
Die Software DoorPi läuft auf einem Raspberry Pi und stellt einen IP-Phone Client zur Verfügung, der in eine IP-Haustelefonanalage (z.B. mit der FritzBox) eingebunden werden kann. Diesen Raspberry Pi könnte man zwar über längere Audiokabel mit der notwendigen Lautsprecher-Mikrofon-Kombination verbinden, das ist allerdings etwas anfällig für Störsignale. Die meisten Anwender von DoorPi wählen deshalb den Einbau des Raspberry Pi direkt an der Türsprechstelle. Aus Sicht des Autors stellt das eine Sicherheitslücke dar - weil ein direkter Zugang ins Heimnetz außerhalb der eigenen vier Wände geschaffen würde.

Hier soll deshalb eine abgesetzte Installation beschrieben werden: Direkt an der Türsprechstelle sitzen nur Sensoren, Audiohardware und ein Display, angesteuert von einem "dummen" Arduino Mikrocontroller. Ins Innere des Hauses führen drei Kabel:
*Ein USB-Kabel zur digitalen Ankopplung der Audio-Hardware an den Raspberry Pi
*Ein HDMI-Kabel zur digitalen Ankopplung einer Kamera an den Raspberry Pi
*Ein 8-adriges Kabel zur Weiterleitung verschiedener Signale an den Raspberry Pi. Hierfür kann man aus Bequemlichkeitsgründen ein Netzwerk-Patchkabel verwenden - hochfrequente Signale gehen allerdings nicht über diesen Weg.

[[File:Doorpi_block.png]]

==Klingel und Türsprechstelle==
Beim Drücken auf den Klingelknopf wird ein IP-Telefonanruf gestartet - entweder bei einer internen Nummer, oder (konfigurierbar in FHEM) bei einer beliebigen anderen Nummer. Wenn der Empfänger den Ruf annimmt, kann er mit dem Besucher sprechen und ggf. durch das Drücken einer Taste die Tür öffnen. Es ist in der DoorPi-Installation problemlos konfigurierbar, beliebige andere Aktionen zu starten - z.B. könnte man dem Paketlieferanten nur das Gartentor öffnen.

Während des Klingelvorgangs wird eine Aufnahme des Besuchers angefertigt. Das Gespräch wird als WAV-Datei ebenfalls aufgezeichnet, beide sind unter dem FHEM-Frontend abrufbar. Während der Aufnahme wird eine Infrarot-Lichtquelle eingeschaltet. Diese soll nicht die ganz Szene ausleuchten - sondern verhindern, dass man das Gesicht des Besuchers wegen einer hinter ihm befindlichen Beleuchtung mit sichtbarem Licht nicht gut erkennen kann.

==Türöffnung==
Das System verfügt über einen iButton-Reader. Legt man einen iButton auf, der in der Software codiert ist, leuchtet eine im Reader integrierte Tricolor-LED in einer entsprechenden Farbe auf (z.B. roter iButton-Halter => rote LED). Der weitere Ablauf hängt vom Schließzustand der Haustür ab.
*Ist die Haustür nur zugezogen und nicht abgeschlossen, wird sie geöffnet. Gleichzeitig wird über die Türsprechstelle die Stimmnachricht ausgegeben "Willkommen zu Hause !", und auf einem im Haus befindlichen Tablet angesagt "Ein Bewohner betritt das Haus."
*Ist die Haustür abgeschlossen, wird zunächst auf dem Touchscreen des Systems statt der Namen eine virtuelle Tastatur angezeigt. Hier kann ggf. noch die akustische Bitte eingebaut werden, eine fünfstellige PIN einzugeben. Der Fortschritt bei der Eingabe wird durch einen Balken angezeigt.
**Ist die PIN falsch, geht das System wieder in den AUsgangszustand zurück, es wird eine Warnungsmeldung an das interne FHEM-System übermittelt.
**Ist die PIN korrekt, wird zunächst der Entriegelungsvorgang der Tür eingeleitet. Je nach verwendetem System kann das eine Weile dauern - Keymatic ist hierfür ein Beispiel, das können durchaus 3-4 Sekunden werden. Danach wird die Tür geöffnet, gleichzeitig wird über die Türsprechstelle die Stimmnachricht ausgegeben "Willkommen zu Hause !", und auf einem im Haus befindlichen Tablet angesagt "Ein Bewohner betritt das Haus." Je nach Konfiguration kann FHEM an dieser Stelle auch weitere Aktionen auslösen - etwa weitere Entriegelungsvorgänge starten.

==Videostream==
Auf dem Raspberry Pi ist auch die Software mjpeg_streamer installiert, Per Mausklick in der FHEM-Oberfläche wird mjpeg-streamer gestartet und gestoppt (das wird von der DoorPi-Software erledigt, die einen bestimmten virtuellen Tastdruck erkennt und dann lokal ein Skript startet), und stellt dann an TCP-Port 9000 einen Videostream bereit. Wer möchte, kann das System auch so konfigurieren, dass es diesen Videostream zusammen mit dem Audiostream zur Videotelefonie verwendet.
==Bewegungserkennung und Helligkeitsmessung==
Erkennt das System durch den eingebauten PIR-Bewegungsmelder eine Bewegung, wird
*die Anzeigehelligkeit für mindestens eine Minute hochgefahren
*ein Signal an FHEM gesendet.
Wenn eine Minute keine Bewegung erkannt wurde, geht die Anzeigehelligkeit (d.h. vom Display und dem LED-Rimng um den Klingelknopf) wieder auf einen Wert zurück, der durch die externe Helligkeit bestimmt ist.

=Hardware=
==Raspberry Pi==
Verwendet wird
*ein [http://www.pollin.de/shop/dt/OTQxNzkyOTk-/Bauelemente_Bauteile/Entwicklerboards/Raspberry_Pi/Raspberry_Pi_3_Modell_B.html Raspberry Pi 3], der ein integriertes WLAN-Modul beitzt
*eine Zusatzkarte [http://www.pollin.de/shop/dt/NTc1NzkyOTk-/Bauelemente_Bauteile/Entwicklerboards/Raspberry_Pi/Raspberry_Pi_B_Zusatzplatine_PIFACE_DIGITAL_2.html PiFace 2], mit je 8 digitalen Ein- und Ausgängen.
* ein klares [http://www.reichelt.de/CB-RPF-P-CLR/3/index.html?&ACTION=3&LA=446&ARTICLE=160959 Gehäuse], das die Erweiterungskarte mit aufnehmen kann

==Kamera-Subsystem==
Verwendet werden hierfür
*eine Standard-NoIR-Kamera für den Raspberry Pi (ohne Infrarotfilter, somit IR-empfindlich)
*ein [https://www.amazon.de/Bresser-Clip--Grad-Fisheye-Handylinse/dp/B00MQQSJKY Bresser Fisheye] 180° zum Aufclippen auf Smartphones
*eine [http://www.ebay.de/itm/321915955373?_trksid=p2057872.m2749.l2649 Acrylglaskuppel] 2 Zoll
*eine [https://www.tindie.com/products/freto/pi-camera-hdmi-cable-extension/ Kabelverlängerung] Flatribbon <-> HDMI <-> Flatribbon
*ein Kameradom aus dem 3D-Drucker mit genauer Passung für das Fisheye vorne und die Kamera hinten, sowie Passungen für 8 LED.Die STL-Datei für diesen Kameradom findet man hier: [https://www.tinkercad.com/things/jv5x6lrihbk PiCameraDome4]
*eine Rückseite des Kameradoms aus dem 3D-Drucker, wird hinten mittig aufgeklebt und hält den Deckel des Kamerasystem durch drei Nippel. Die STL-Datei dafür findet man hier [https://tinkercad.com/things/cV6rkY6DWvc PiCameraDome4addendum]
*ein Deckel des Kameradoms aus dem 3D-Drucker, wird auf die Rückseite aufgesteckt und beinhaltet zwei Halterungen für Mikrofone (die "Ohren" im Bild). Die STL-Datei dafür findet man hier [https://tinkercad.com/things/8X0fhiSTyXk PiCameraDome4back]
*9 x IR-LED [http://www.conrad.biz/ce/de/product/171140/IR-Emitter-940-nm-17-5-mm-radial-bedrahtet-Vishay-TSAL-6200 TSAL 6200] mit hoher Leistung
*3 Widerstände 10 Ohm 0,2 W.

[[File:Dome1.jpg|400x300px]][[File:Dome2.jpg|400x300px]][[File:Doorpi_dome3s.jpg|400x300px]][[File:Doorpi_dome4s.jpg|600x300px]]

Zur Montage werden vier M2-Gewindebolzen in die hintere Aussparung des Kameradoms eingeklebt, und auf diese mit entsprechenden Abstandshaltern und Muttern sowohl die Kamera, als auch die eine Hälfte der Kabelverlängerung geschraubt. Dabei empfiehlt es sich, die LED vorher an Ort und Stelle zu haben - ggf. muss bei ungünstiger Klebung der Gewindebolzen bei den Eck-LED ein Gehäusevorsprung etwas abgefeilt werden.

Die Schaltung der LED für dem Betrieb an einer Spannung von 5V ausgelegt - damit fließen durch drei in Reihe geschaltete LED und einen 10 Ohm-Widerstand ziemlich genau 100mA. Bei der Schaltung über einen MOSFET ist das etwas weniger, wegen des Drain-Source-Widerstandes des MOSFET, reicht aber für die notwendige Helligkeit aus. Aus Symmetriegründen werden drei solche Stränge (insgesamt 9 LED) montiert - aber nur 8 davon sind bei dem angegebenen Kameradom nach außen gerichtet (wer möchte, kann gerne ein 3D-Design mit 9 Löchern erstellen), eine LED zeigt also nutzlos nach innen (erkennbar im 3. Bild der obigen Reihe).

Das Fischaugenobjektiv wird mit wenig (!) klarem Silikon in die vordere Öffnung des Kameradoms geklebt, der rückwärtige Aufsatz mit den 3 Nippeln mit Zweikomponentenkleber auf der Rückseite des Kameradoms befestigt. Dabei zur Ausrichtung den Mikrofonhalter (rechtes Bild, mit den "Ohren") probeweise aufstecken.

Die Acrylglaskuppel wird mit Silikon oder einem äquivalenten Dichtmaterial wasserdicht in die Frontplatte eingesetzt, auf diese dann von hinten der Kameradom. Eine staubdichte Verbindung erfordert auch hier die Abdichtung mit Silikon. Für den Fall einer möglichen Demontage empfiehlt es sich, diese Abdichtung nicht als Klebung zu verwenden, sondern als umlaufenden Rand nachträglich aufzubringen - der ist dann einfach mit einem Cutter zu entfernen.

==Audio-Subsystem==

==Sensoren==
Der [http://www.elv.de/bewegungsmeldermodul-pir-13.html Bewegungsmelder] ist ein sehr kleines Modul, das einfach von hinten in eine Bohrung der Frontplatte gesteckt wird. Sein Open-Collector-Ausgang wird über eine der vier unbenutzen Adern (blau) des HDMI-Kabels an den Raspberry Pi weitergeleitet.

Der Helligkeitssensor besteht aus einem Fototransistor und zwei festen und einem einstellbaren Widerstand. Seine Ausgangsspannung wird an den Arduino weitergeleitet, der auf Grund dieses Wertes das Display und den LED-Ring des Klingelknopfes dimmt.

Als [https://www.amazon.de/gp/product/B01DKTHDXE Klingelknopf] wird ein Modell aus Edelstahl mit umlaufendem LED-Ring verwendet,

Der Sabotagekontakt besteht aus einem Mikroschalter, der so in die Rückwandinstallation geklebt wird, dass er bei der Abnahme der Frontplatte geschlossen wird. Dieses Signal wird über eine der unbenutzten Adern des HDMI-Kabels (orange im Bild) an den Raspberry Pi weitergeleitet.

[[File:DoorPi_part1.png|500x350px]][[File:doorpi_sensorss.jpg|800x350px]]

==Frontplatte==
Die Frontplatte besteht aus 4 mm starken Aluminium, eloxiert und auf 1/10 mm genau mit den passenden Bohrungen und Ausschnitten sowie rückseitig angeschweißten Gewindebolzen versehen. Online bestellbar z.B. bei der Schaeffer AG, für das vorliegende Exemplar wurden ca. 115 € in Rechnung gestellt. Auf Grund ihrer Stabilität dient diese Frontplatte als Baugruppenträger für die Außeninstallation.

[[File:Doorpi_front.jpg]]

==Rückwandinstallation==
Die Rückwandinstallation, die in des Mauerwerk eingelassen wird, kommt ebenfalls aus dem 3D-Drucker. Sie besteht aus drei Teilen mit unterschiedlicher Tiefe, um das Loch im Mauerwerk nicht zu groß werden zu lassen. Das obere und das untere Teil enthalten jeweils zwei stabile Vorsprünge mit Aussparungen, in die eine normgerechte M4-Mutter von unten genau hineinpasst. Bemerkenswert ist, dass dieses Bauteil nicht mit einer konventionellen Methode (z.B. im Spritzgussverfahren) gefertigt werden kann.

[[File:Doorpi_covertop.jpg]]

Diese Muttern kommen damit genau hinter den äußeren Schraubenlöchern der Frontplatte zu liegen, Die Frontplatte kann dadurch mit vier (Sicherheits-)schrauben M4 passgenau auf die im Mauerwerk sitzende Rückwandinstallation geschraubt werden.

Auf der Oberkante der drei Teile verläuft eine 1x1 mm² große Nut, in die eine Dichtung eingelegt werden kann.

HTTPMOD

2016-01-05T15:44:29Z

SirUli: Formatierung und Korrektur des Tables "Actor"

{{Infobox Modul
|ModPurpose=Extract information from devices with an HTTP interface (or, more generic, from any URL) or send information to such devices
|ModType=d
|ModCmdRef=HTTPMOD
|ModForumArea=Sonstiges
|ModTechName=98_HTTPMOD.pm
|ModOwner=StefanStrobel ({{Link2FU|3960|Forum}} / [[Benutzer:StefanStrobel|Wiki]])
}}

HTTPMOD provides a generic way to retrieve information from devices with an HTTP Interface and store them in Readings or send information to such devices. It queries a given URL with Headers and data defined by attributes.

From the HTTP response it extracts readings named in attributes using Regexes, JSON or XPath parsing also defined by attributes.

In an advanced [[Konfiguration|configuration]] the module can also send information to devices. To do this, a generic <code>set</code> option can be configured using attributes.

== Availability ==
{{Randnotiz|RNText=An extended / modified version of this module that among other features adds XPath and JSON support is currently under development.
If you want to participate in early tests, please follow this {{Link2Forum|Topic=45176|LinkText=discussion thread}} in FHEM forum.
This page has already been updated to describe most of the new features. So if you need one of the new features described here and yout HTTPMOD is still the old version, load the new module
from the forum and help testing
}}
The module is part of the regular FHEM distribution.

== Prerequisites ==
This module uses the non blocking HTTP function <code>HttpUtils_NonblockingGet</code> provided by FHEM's [[HttpUtils]] in a new version published in December 2013.
If not already installed in your environment, please [[update]] FHEM or install it manually using appropriate commands from your environment.

== Define ==
<source lang="perl">
define <name> HTTPMOD <URL> <Interval>
</source>
The module connects to the given <code>URL</code> every <code>Interval</code> seconds, sends optional headers and data and then parses the response with regular expressions, xpath or json to set readings.

URL can be "none" and Interval can be 0 if you prefer to only query data with a get command and not in a defined interval.

Example:
<source lang="perl">
define PM HTTPMOD http://MyPoolManager/cgi-bin/webgui.fcgi 60
</source>

== Set-Commands ==
can be defined using attributes, see advanced configuration

If you set the attribute enableControlSet to 1, the following additional built in set commands are available:
;interval
:set new interval time in seconds and restart the timer
;reread
:request the defined URL and try to parse it just like the automatic update would do it every Interval seconds without modifying the running timer.
;stop
:stop interval timer.
;start
:restart interval timer to call GetUpdate after interval seconds

== Get-Commands ==
can be defined using attributes, see advanced configuration

== simple Attributes ==
;do_not_notify

;readingFnAttributes

;requestHeader.*
:Define an additional HTTP Header to set in the HTTP request

;requestData
:POST Data to be sent in the request. If not defined, it will be a GET request as defined in HttpUtils used by this module

;reading[0-9]+(-[0-9]+)?Name
:the name of a reading to extract with the corresponding readingRegex

;reading[0-9]*(-[0-9]+)?Expr
:defines an expression that is used in an eval to compute the readings value. The raw value will be in the variable $val.

;reading[0-9]*(-[0-9]+)?Map
:defines a mapping from raw to visible values like "0:mittig, 1:oberhalb, 2:unterhalb". If specified as readingMap then the attribute value is a default for all other readings that don't specify an explicit reading[0-9]*Map.

;reading[0-9]*(-[0-9]+)?Format
:Defines a format string that will be used in sprintf to format a reading value. If specified as readingFormat then the attribute value is a default for all other readings that don't specify an explicit reading[0-9]*Format.

;reading[0-9]*(-[0-9]+)?Decode
:defines an encoding to be used in a call to the perl function decode to convert the raw data string read from the device to a reading. This can be used if the device delivers strings in an encoding like cp850 instead of utf8.

;reading[0-9]*(-[0-9]+)?Encode
:defines an encoding to be used in a call to the perl function encode to convert the raw data string read from the device to a reading. This can be used if the device delivers strings in an encoding like cp850 and after decoding it you want to reencode it to e.g. utf8.

;reading[0-9]+Regex
:defines the regex to be used for extracting the reading. The value to extract should be in a sub expression e.g. ([\d\.]+) in the above example

;reading[0-9]+Regex
:defines the regex to be used for extracting the reading. The value to extract should be in a capture group / sub expression
:e.g. ([\d\.]+) in the above example. Multiple capture groups will create multiple readings (see explanation above)

;reading[0-9]+XPath
:defines an xpath to one or more readings when parsing HTML data (see examples below)

;reading[0-9]+XPath-Strict
:defines an xpath to one or more readings when parsing XML data (see examples below)

;reading[0-9]+JSON
:defines a path to the JSON object wanted by concatenating the object names with an underscore as delimiter (see the example below)

;noShutdown
:pass the noshutdown flag to HTTPUtils for webservers that need it (some embedded webservers only deliver empty pages otherwise)

;disable
:stop doing automatic HTTP requests while this attribute is set to 1

;timeout
:time in seconds to wait for an answer. Default value is 2

;enableControlSet
:enables the built in set commands interval, stop, start, reread

;(get|reading)[0-9]*RecombineExpr
:defines an expression that is used in an eval to compute one reading value out of the list of matches.
:This is supposed to be used for regexes or xpath specifications that produce multiple results if only one result that combines them is wanted.
:The list of matches will be in the variable @matchlist.

== simple Configuration of HTTP Devices ==
If your device expects special HTTP-headers then specify them as <code>attr requestHeader1</code> to <code>attr requestHeaderX</code>.
If your Device expects an HTTP POST instead of HTTP GET then the POST-data can be specified as <code>attr requestData</code>.
To get the readings, specify pairs of <code>attr readingXName</code> and <code>attr readingXRegex</code>, <code>attr readingXXPath</code>, <code>attr readingXXPath-Strict</code> or <code>attr readingXJSON</code> to define which readings you want to extract from the HTTP response and how to extract them. (The old syntax <code>attr readingsNameX</code> and <code>attr readingsRegexX</code> is still supported but the new one with <code>attr readingXName</code> and <code>attr readingXRegex</code> should be preferred. The actual values to be extracted have to be sub expressions within () in the regex (see example below)

=== Example for a PoolManager 5: ===
The PoolManager Web GUI can be queried with HTTP POST Requests like this one:

<source lang="perl">
POST /cgi-bin/webgui.fcgi HTTP/1.1
Host: 192.168.70.90
Accept: */*
Content-Type: application/json;charset=UTF-8
Content-Length: 60

{"get" :["34.4001.value" ,"34.4008.value" ,"34.4033.value"]}
</source>

The resulting HTTP Response would look like this:

<source lang="perl">
HTTP/1.1 200 OK
Content-type: application/json; charset=UTF-8
Expires: 0
Cache-Control: no-cache
Date: Sun, 12 Jan 2014 12:23:11 GMT
Server: lighttpd/1.4.26
Content-Length: 179

{
"data": {
"34.4001.value": "7.00",
"34.4008.value": "0.52",
"34.4033.value": "24.8"
},
"status": {
"code": 0
},
"event": {
"type": 1,
"data": "48.30000.0"
}
}
</source>

To configure HTTPMOD for a PoolManager one would first define a PoolManager device with e.g. the name PM, the URL and an interval of e.g. 60 seconds.

Then the data to be sent in the request needs to be defined because in this example the device expects a POST request so the query is not contained in the URL but in the request data.

Also as seen above the device expects special HTTP headers in the request so these headers also need to be defined as <code>attr PM requestHeader1</code> and <code>attr PM requestHeader2</code>

Then the names of the readings to be extracted would be set with attributes

Then for each reading value to be extracted a regular expression needs to be set that will match the value in question within ().

Example:
<source lang="perl">
define PM HTTPMOD http://MyPoolManager/cgi-bin/webgui.fcgi 60
attr PM reading01Name PH
attr PM reading01Regex 34.4001.value":[ \t]+"([\d\.]+)"

attr PM reading02Name CL
attr PM reading02Regex 34.4008.value":[ \t]+"([\d\.]+)"

attr PM reading03Name3TEMP
attr PM reading03Regex 34.4033.value":[ \t]+"([\d\.]+)"

attr PM requestData {"get" :["34.4001.value" ,"34.4008.value" ,"34.4033.value", "14.16601.value", "14.16602.value"]}
attr PM requestHeader1 Content-Type: application/json
attr PM requestHeader2 Accept: */*
attr PM stateFormat {sprintf("%.1f Grad, PH %.1f, %.1f mg/l Chlor", ReadingsVal($name,"TEMP",0), ReadingsVal($name,"PH",0), ReadingsVal($name,"CL",0))}
</source>

=== Example for AmbientMonitor ===
AmbientMonitor is a webbased visualisation for sensors connected to an Arduino device. Its web interface can also be queried with HTTMOD to grab the data into readings.

This example was provided by locutus. The hardware configuration is an Arduino + Ethercard with ENC28J60 Controller + DHT22 Sensor and software can be downloaded from https://github.com/lucadentella/AmbientMonitor

In this example an HTTP GET is sufficent, so no <code>requestData</code> is needed. The device provides temperature and humidity readings in an HTTP response that looks like:
<source lang="perl">
HTTP/1.0 200 OK
Content-Type: text/html

myCB({'temperature':22.00,'humidity':46.00})
</source>

the definition could be:
<source lang="perl">
define AmbientMonitor HTTPMOD http://192.168.1.221/?callback=? 300
attr AmbientMonitor requestHeader Content-Type: application/json
attr AmbientMonitor reading1Name Temperatur
attr AmbientMonitor reading1Regex temperature':([\d\.]+)
attr AmbientMonitor reading2Name Feuchtigkeit
attr AmbientMonitor reading2Regex humidity':([\d\.]+)
attr AmbientMonitor stateFormat {sprintf("Temperatur %.1f C, Feuchtigkeit %.1f %", ReadingsVal($name,"Temperatur",0), ReadingsVal($name,"Feuchtigkeit",0))}
</source>

== formating and manipulating values / readings ==
Values that are parsed from an HTTP response can be further treated or formatted with the following attributes:

* <code>(reading|get)[0-9]*(-[0-9]+)?Expr</code>
* <code>(reading|get)[0-9]*(-[0-9]+)?Map</code>
* <code>(reading|get)[0-9]*(-[0-9]+)?Format</code>
* <code>(reading|get)[0-9]*(-[0-9]+)?Decode</code>
* <code>(reading|get)[0-9]*(-[0-9]+)?Encode</code>

They can all be specified for an individual reading, for all readings in one match (e.g. if a regular expression has several capture groups)or for all readings in a get command (defined by getXX) or for all readings in the main reading list (defined by readingXX):
<source lang="perl">
reading01Format %.1f
</source>

will format the reading with the name specified by the attribute reading01Name to be numerical with one digit after the decimal point.
If the attribute reading01Regex is used and contains several capture groups then the format will be applied to all readings thet are parsed by this regex unless these readings have their own format specified by reading01-1Format, reading01-2Format and so on.

<source lang="perl">
reading01-2Format %.1f
</source>

Can be used in cases where a regular expression specified as reading1regex contains several capture groups or an xpath specified as reading01XPath creates several readings.
In this case reading01-2Format specifies the format to be applied to the second match.

<source lang="perl">
readingFormat %.1f
</source>

applies to all readings defined by a reading-Attribute that have no more specific format.

If you need to do some calculation on a raw value before it is used as a reading, you can define the attribute <code>readingExpr</code>.
It defines a Perl expression that is used in an eval to compute the readings value. The raw value will be in the variable $val.

=== Example: ===
<source lang="perl">
attr PM reading03Expr $val * 10
</source>
Just like in the above example of the readingFormat attributes, readingExpr and the other following attributes can be applied on several levels.

To map a numerical value to a name, you can use the readingMap attribute.
It defines a mapping from raw to visible values like "0:mittig, 1:oberhalb, 2:unterhalb".

=== Example: ===
<source lang="perl">
attr PM reading02-3Map 0:kalt, 1:warm, 2:sehr warm
</source>

To convert character sets, the module can first decode a string read from the device and then encode it again. For example:
<source lang="perl">
attr PM getDecode UTF-8
</source>

This applies to all readings defined for Get-Commands.

== Some help with Regular Expressions ==
If HTTPMOD seems not to work and the FHEM Logfile contains a message like
:<code>HTTPMOD: Response didn't match Reading ...</code>
then you should check if the value you want to extract is read into the internal with the name buf. Internals are visible when you click on the defined HTTPMOD Device. buf is an internal variable that contains the HTTP Response read. If the value is there and you get the mentioned message then probably something is wrong with your regular expression. If you are new to regular expressions then the introduction at http://perldoc.perl.org/perlretut.html might be helpful.

For a typical HTTPMOD use case where you want to extract a number out of a HTTP-Response you can use something like <code>[\d\.]+</code> to match the number itself. The expression matches the number characters (<code>\d</code>) or a <code>.</code> if one of these characters occurs at least once.

To tell HTTPMOD that the number is what you want to use for the reading, you have to put the expression in between <code>()</code>. A <code>([\d\.]+)</code> alone would match the longest number in the HTTP Response which is very likely not the number you are looking for so you need to add something to the expression to give it a context and define how to find the number that you are looking for.
if there is a title text before the number or a special text after the number you can put this in the regex. In one of the examples above <code>humidity':([\d\.]+)</code> is looking for the number that immediately follows the text <code>humidity':</code> without any blanks in between.

=== Regular Expressions with multiple capture Groups ===
The regular expressions used in the above example for a Poolmanager will take the value that matches one capture group. This is the part of the regular expression inside (). In the above example "([\d\.]+)" refers to numerical digits or points between double quotation marks. Only the string consiting of digits and points will match inside (). This piece is assigned to the reading.

You can also use regular expressions that have several capture groups which might be helpful when parsing tables. In this case an attribute like

<source lang="perl">
reading02Regex something[ \t]+([\d\.]+)[ \t]+([\d\.]+)
</source>

could match two numbers. When you specify only one reading02Name like
<source lang="perl">
reading02Name Temp
</source>

the name Temp will be used with the extension -1 and -2 thus giving a reading Temp-1 for the first number and Temp-2 for the second. You can also specify individual names for several readings that get parsed from one regular expression with several capture groups by defining attributes

<source lang="perl">
reading02-1Name
reading02-2Name
...
</source>
The same notation can be used for formatting attributes like readingXMap, readingXFormat and so on.

The usual way to define readings is however to have an individual regular expression with just one capture group per reading as shown in the above example.

== Parsing JSON ==

If a webservice delivers data in JSON format, HTTPMOD can directly parse JSON which might be easier in this case than definig regular expressions.
The next example shows the data that can be requested from a Poolmanager with the following partial configuration:

<source lang="perl">
define test2 HTTPMOD none 0
attr test2 get01Name Chlor
attr test2 getURL http://192.168.70.90/cgi-bin/webgui.fcgi
attr test2 getHeader1 Content-Type: application/json
attr test2 getHeader2 Accept: */*
attr test2 getData {"get" :["34.4008.value"]}
</source>

The data in the HTTP response looks like this:

<source lang="perl">
{
"data": {
"34.4008.value": "0.25"
},
"status": {
"code": 0
},
"event": {
"type": 1,
"data": "48.30000.0"
}
}
</source>

the classic way to extract the value 0.25 into a reading with the name Chlor with a regex would have been
<source lang="perl">
attr test2 get01Regex 34.4008.value":[ \t]+"([\d\.]+)"
</source>

with JSON you can write
<source lang="perl">
attr test2 get01JSON data_34.4008.value
</source>

or if you don't care about the naming of your readings, you can simply extract all JSON data with
<source lang="perl">
attr test2 extractAllJSON
</source>

which would apply to all data read from this device and create the following readings out of the HTTP response shown above:

{| class="wikitable"
| data_34.4008.value || 0.25
|-
| event_data || 48.30000.0
|-
| event_type || 1
|-
| status_code || 0
|}

or you can specify
<source lang="perl">
attr test2 get01ExtractAllJSON
</source>
which would only apply to all data read as response to the get command defined as get01.

== Parsing http / XML using xpath ==
Another alternative to regex parsing is the use of XPath to extract values from HTTP responses.
The following example shows how XML data can be parsed with XPath-Strict or HTML Data can be parsed with XPath.
Both work similar and the example uses XML Data parsed with the XPath-Strict option:

If The XML data in the HTTP response looks like this:

<source lang="xml">
<root xmlns:foo="http://www.foo.org/" xmlns:bar="http://www.bar.org">
<actors>
<actor id="1">Peter X</actor>
<actor id="2">Charles Y</actor>
<actor id="3">John Doe</actor>
</actor>
</root>
</source>

with XPath you can write
<source lang="perl">
attr htest reading01Name Actor
attr htest reading01XPath-Strict //actor[2]/text()
</source>

This will create a reading with the Name "Actor" and the value "Charles Y".

Since XPath specifications can define several values / matches, HTTPMOD can also interpret these and store them in multiple readings:
<source lang="perl">
attr htest reading01Name Actor
attr htest reading01XPath-Strict //actor/text()
</source>

will create the readings

{| class="wikitable"
| Actor-1 || Peter X
|-
| Actor-2 || Charles Y
|-
| Actor-3 || John Doe
|}

== Further replacements of URL, header or post data ==
sometimes it might be helpful to dynamically change parts of a URL, HTTP header or post data depending on existing readings, internals or
perl expressions at runtime. This might be needed to pass further variables to a server, a current date or other things.

To support this HTTPMOD offers generic replacements that are applied to a request before it is sent to the server. A replacement can be defined with the attributes

* <code>replacement[0-9]*Regex</code>
* <code>replacement[0-9]*Mode</code>
* <code>replacement[0-9]*Value</code>
* <code>[gs]et[0-9]*Replacement[0-9]*Value</code>

a replacement always replaces a match of a regular expression.

'''replacement[0-9]*Mode:'''
The way the replacement value is defined can be specified with the replacement mode.
* If the <code>replacement[0-9]*Mode</code> is <code>reading</code>, then the corresponding <code>replacement[0-9]*Value</code> is interpreted as the name of a ''reading'' of the same device or as ''device:reading'' to refer to another device.
* If the <code>replacement[0-9]*Mode</code> is <code>internal</code>, then the corresponding <code>replacement[0-9]*Value</code> is interpreted as the name of an ''internal'' of the same device or as ''device:internal'' to refer to another device.
* If the <code>replacement[0-9]*Mode</code> is <code>text</code>, then the corresponding <code>replacement[0-9]*Value</code> is interpreted as a static text
* If the <code>replacement[0-9]*Mode</code> is <code>expression</code> , then the corresponding <code>replacement[0-9]*Value</code> is evaluated as a perl expression to compute the replacement. Inside such a replacement expression it is possible to refer to capture groups of the replacement regex.

Example:

<source lang="perl">
attr mydevice getData {"get" :["%%value%%.value"]}
attr mydevice replacement01Mode text
attr mydevice replacement01Regex %%value%%

attr mydevice get01Name Chlor
attr mydevice get01Replacement01Value 34.4008

attr mydevice get02Name Something
attr mydevice get02Replacement01Value 31.4024
</source>

defines that <code>%%value%%</code> will be replaced by a static text.

All Get commands will be HTTP post requests of a similar form. Only the <code>%%value%%</code> will be different from get to get.
The first get will set the reading named Chlor and for the request it will take the generic getData and replace %%value%% with 34.4008.
A second get will look the same except a different name and replacement value.

The mode expression allows you to define your own replacement syntax:
<source lang="perl">
attr mydevice replacement01Mode expression
attr mydevice replacement01Regex {{([^}]+)}}
attr mydevice replacement01Value ReadingsVal("mydevice", $1, "")
attr mydevice getData {"get" :["{{temp}}.value"]}
</source>

In this example any <code><nowiki>{{name}}</nowiki></code> in a URL, header or post data will be passed on to the perl function ReadingsVal
which uses the string between <code><nowiki>{{}}</nowiki></code> as second parameter. This way one defined replacement can be used for many different
readings.

== replacing reading values when they have not been updated / the device did not respond ==
If a device does not respond then the values stored in readings will keep the same and only their timestamp shows that they are outdated.
If you want to modify reading values that have not been updated for a number of seconds, you can use the attributes

* <code>(reading|get)[0-9]*(-[0-9]+)?MaxAge</code>
* <code>(reading|get)[0-9]*(-[0-9]+)?MaxAgeReplacementMode</code>
* <code>(reading|get)[0-9]*(-[0-9]+)?MaxAgeReplacement</code>

Every time the module tries to read from a device, it will also check if readings have not been updated
for longer than the <code>MaxAge</code> attributes allow. If readings are outdated, the <code>MaxAgeReplacementMode</code> defines how the affected
reading values should be replaced. <code>MaxAgeReplacementMode</code> can be <code>text</code> or <code>expression</code>.

<code>MaxAge</code> specifies the number of seconds that a reading should remain untouched before it is replaced.

<code>MaxAgeReplacement</code> contains either a static text that is used as replacement value or a Perl expression that is evaluated to
give the replacement value. This can be used for example to replace a temperature that has not bee updated for more than 5 minutes
with the string "outdated - was 12":
<source lang="perl">
attr PM readingMaxAge 300
attr PM readingMaxAgeReplacement "outdated - was " . $val
attr PM readingMaxAgeReplacementMode expression
</source>
The variable <code>$val</code> contains the value of the reading before it became outdated.

Or to show that a device was offline:
<source lang="perl">
attr MyLight reading01Name color
attr MyLight reading01JSON result_02_color
attr MyLight reading01MaxAge 300
attr MyLight reading01MaxAgeReplacement "offline"
attr MyLight reading01MaxAgeReplacementMode text
</source>

== Additional notes ==
If you don't know which URLs, headers or POST data your web GUI uses, you might try a local proxy like BurpSuite [http://portswigger.net/burp/ BurpSuite] to track requests and responses

== Advanced configuration to define a <code>set</code> and send data to a device ==

When a set option is defined by attributes, the module will use the value given to the set command and integrate it into an HTTP-Request that sends the value to the device. The definitions for URL, headers and post data can contain the placeholder $val which will be replaced by the value given to the set command.

This can be as simple as:
<source lang="perl">
# No cyclic requests and no main URL needed in this example
define MyDevice none 0

attr MyDevice set01Name Licht
attr MyDevice set01URL http://192.168.1.22/switch=$val
</source>

A user command
<source lang="perl">
set MyDevice Licht 1
</source>

will be translated into the http GET request
<source lang="perl">
http://192.168.1.22/switch=1
</source>

In this example a map would also be helpful, that translates on / off to 0 or 1 and allows the user to select on/of in fhemweb:
<source lang="perl">
attr MyDevive set01Map 0:off, 1:on
</source>
This also provides input validation to make sure that only on and off can be used with the set command.

In more complex Scenarios you might need to login before sending a command and the Login might create a session id that has to be part of further requests either in the URL, in headers or in the post data.

Extension to the above example for a PoolManager 5 where a set needs a session id in the URL and the values have to be passed in JSON strings as post data:
<source lang="perl">
attr PM set01Name HeizungSoll
attr PM set01URL http://MyPoolManager/cgi-bin/webgui.fcgi?sid=$sid
attr PM set01Hint 6,10,20,30
attr PM set01Min 6
attr PM set01Max 30
attr PM setHeader1 Content-Type: application/json
attr PM set01Data {"set" :{"34.3118.value" :"$val" }}
</source>

This example defines a set option with the name HeizungSoll.
By issuing <code>set PM HeizungSoll 10</code> in FHEM, the value 10 will be sent in the defined HTTP
Post to URL <code>http://MyPoolManager/cgi-bin/webgui.fcgi</code> in the Post Data as

<source lang="html4strict">
{"set" :{"34.3118.value" :"10" }}
</source>

The optional attributes set01Min and set01Max define input validations that will be checked in the set function.
The optional attribute set01Hint will define a selection list for the Fhemweb GUI.

If a parameter to a set command is not numeric but should be passed on to the device as text, then you can specify the attribute setTextArg. For example:
<source lang="perl">
attr PM set01TextArg
</source>

If a set command should not require a parameter at all, then you can specify the attribute NoArg. For example:
<source lang="perl">
attr PM set03Name On
attr PM set03NoArg
</source>

=== Advanced configuration to create a valid session id that might be necessary in set options ===
In simple cases logging in works with basic authentication. In the case HTTPMOD accepts a username and password as part of the URL in the form
<source lang="perl">
http://User:Password@192.168.1.18/something
</source>

However basic auth is seldom used. If you need to fill in a username and password in a HTML form and the session is then managed by a session id, here is how to configure this:

when sending data to an HTTP-Device in a set, HTTPMOD will replace any <code>$sid</code> in the URL, Headers and Post data with the internal <code>$hash->{sid}</code>. To authenticate towards the device and give this internal a value, you can use an optional multi step login procedure defined by the following attributes:

* <code>sid[0-9]*URL</code>
* <code>sid[0-9]*IDRegex</code>
* <code>sid[0-9]*Data.*</code>
* <code>sid[0-9]*Header.*</code>
* <code>sid[0-9]*IgnoreRedirects</code>

Each step can have a URL, Headers, Post Data pieces and a Regex to extract a resulting Session ID into <code>$hash->{sid}</code>.
HTTPMOD will create a sorted list of steps (the numbers between sid and URL / Data / Header) and the loop through these steps and send the corresponding requests to the device. For each step a $sid in a Header or Post Data will be replaced with the current content of <code>$hash->{sid}</code>.

Using this feature, HTTPMOD can perform a forms based authentication and send user name, password or other necessary data to the device and save the session id for further requests.

To determine when this login procedure is necessary, HTTPMOD will first try to do a set without doing the login procedure. If the Attribute ReAuthRegex is defined, it will then compare the HTTP Response to the set request with the regular expression from ReAuthRegex. If it matches, then a login is performed. The ReAuthRegex is meant to match the error page a device returns if authentication or reauthentication is required e.g. because a session timeout has expired.

If for one step not all of the URL, Data or Header Attributes are set, then HTTPMOD tries to use a
<code>sidURL</code>, <code>sidData.*</code> or <code>sidHeader.*</code> Attribue (without the step number after sid). This way parts that are the same for all steps don't need to be defined redundantly.

=== Example for a multi step login procedure: ===

<source lang="perl">
attr PM reAuthRegex /html/dummy_login.htm
attr PM sidURL http://192.168.70.90/cgi-bin/webgui.fcgi?sid=$sid
attr PM sidHeader1 Content-Type: application/json
attr PM sid1IDRegex wui.init\('([^']+)'
attr PM sid2Data {"set" :{"9.17401.user" :"fhem" ,"9.17401.pass" :"password" }}
attr PM sid3Data {"set" :{"35.5062.value" :"128" }}
attr PM sid4Data {"set" :{"42.8026.code" :"pincode" }}
</source>

In this case HTTPMOD detects that a login is necessary by looking for the pattern /html/dummy_login.htm in the HTTP response.
If it matches, it starts a login sequence. In the above example all steps request the same URL. In step 1 only the defined Header is sent in an HTTP get request. The response will contain a session id that is extraced with the regex wui.init\('([^']+)'.

In the next step this session id is sent in a post request to the same URL where tha post data contains a username and password. The a third and a fourth request follow that set a value and a code. The result will be a valid and authorized session id that can be used in other requests where $sid is part of a URL, header or post data and will be replaced with the session id extracted above.

== Advanced configuration to define a <code>get</code> and request additional data with its own request from a device ==

The normal automatic HTTP request that is done repeatedly after the defined interval has elapsed works well in cases where all required readings can be requested in one common HTTP request. If however a device needs individual requests with different URLs or different POST data for each value, then another method is necessary.
For such cases a <code>get</code> option can be defined and the user can either issue Fhem <code>get</code> commands each time he needs the reading or the user can set an attribute to request the reading automatically together with the normal iteration.
For each <code>get</code> option attributes define an individual URL, optional headers, and post data as well as individual regular expressions and formatting options.

Example for a Siemens webserver provided by Lanhydrock:
<source lang="perl">
define ozw672 HTTPMOD https://192.168.178.8/api/auth/login.json?user=test&pwd=test 300

attr ozw672 get1Name tempAussen
attr ozw672 get1URL https://192.168.178.8/api/menutree/read_datapoint.json?SessionId=$sid&Id=1960
attr ozw672 get1Poll 1
attr ozw672 get1PollDelay 1800

attr ozw672 get2Name tempAussenGemischt
attr ozw672 get2URL https://192.168.178.8/api/menutree/read_datapoint.json?SessionId=$sid&Id=1964
attr ozw672 get2Poll 1
attr ozw672 get2PollDelay 1800

attr ozw672 get3Name tempTWW
attr ozw672 get3URL https://192.168.178.8/api/menutree/read_datapoint.json?SessionId=$sid&Id=1996
attr ozw672 get3Poll 1

attr ozw672 get4Name tempKesselSoll
attr ozw672 get4URL https://192.168.178.8/api/menutree/read_datapoint.json?SessionId=$sid&Id=1910
attr ozw672 get4Poll 1

attr ozw672 get5Name tempKesselRuecklauf
attr ozw672 get5URL https://192.168.178.8/api/menutree/read_datapoint.json?SessionId=$sid&Id=1915
attr ozw672 get5Poll 1

attr ozw672 get6Name tempKesselRuecklaufSoll
attr ozw672 get6URL https://192.168.178.8/api/menutree/read_datapoint.json?SessionId=$sid&Id=1916
attr ozw672 get6Poll 1

attr ozw672 get7Name anzahlStartsBrenner
attr ozw672 get7URL https://192.168.178.8/api/menutree/read_datapoint.json?SessionId=$sid&Id=1927
attr ozw672 get7PollDelay 1800
attr ozw672 get7Poll 1

attr ozw672 get8Name statusKessel
attr ozw672 get8URL https://192.168.178.8/api/menutree/read_datapoint.json?SessionId=$sid&Id=1898
attr ozw672 get8Poll 1
attr ozw672 get8Regex Value": "([a-zA-Zü ]*)"
attr ozw672 get8Map Aus:0, Nachlauf aktiv:5, Freigegeben für TWW:10, Freigegeben für HK:20, In Teillastbetrieb für TWW:40, In Teillastbetrieb für HK:50, In Betrieb für Trinkwasser:90, In Betrieb für Heizkreis:100

attr ozw672 getRegex Value": "[ ]*([-.0-9]*)"

attr ozw672 reAuthRegex .*session not valid.*
attr ozw672 sid1IDRegex .*"(.*-.*-.*-[0-9a-z]*).*
attr ozw672 sid1URL https://192.168.178.8/api/auth/login.json?user=test&pwd=test
</source>

=== Advanced attributes ===

;ReAuthRegex
:regular Expression to match an error page indicating that a session has expired and a new authentication for read access needs to be done.
:This attribute only makes sense if you need a forms based authentication for reading data and if you specify a multi step login procedure based on the sid.. attributes.
:This attribute is used for all requests. For set and get operations you can however specify individual reAuthRegexes with the [gs]et[0-9]*ReAuthRegex attributes.

;sid[0-9]*URL
:different URLs or one common URL to be used for each step of an optional login procedure.

;sid[0-9]*IDRegex
:different Regexes per login procedure step or one common Regex for all steps to extract the session ID from the HTTP response

;sid[0-9]*Data.*
:data part for each step to be sent as POST data to the corresponding URL

;sid[0-9]*Header.*
:HTTP Headers to be sent to the URL for the corresponding step

;sid[0-9]*IgnoreRedirects
:Tells the HttpUtils to not follow HTTP Redirects for this Request. Might be needed for some devices that set a session cookie within a 303 Redirect.

;set[0-9]+Name
:Name of a set option

;set[0-9]*URL
:URL to be requested for the set option

;set[0-9]*Data
:Data to be sent to the device as POST data when the set is executed

;set[0-9]*Header
:HTTP Headers to be sent to the device when the set is executed

;set[0-9]+Min
:Minimum value for input validation.

;set[0-9]+Max
:Maximum value for input validation.

;set[0-9]+Expr
:Perl Expression to compute the raw value to be sent to the device from the input value passed to the set.

;set[0-9]+Map
:Map that defines a mapping from raw to visible values like "0:mittig, 1:oberhalb, 2:unterhalb". This attribute atomatically creates a hint for FhemWEB so the user can choose one of the visible values or select a value with a slider.

;set[0-9]+Hint
:Explicit hint for fhemWEB that will be returned when set ? is seen. Can be used to get a slider or a list of values to choose from.

;set[0-9]*ReAuthRegex
:Regex that will detect when a session has expired an a new login needs to be performed.

;get[0-9]+Name
:Name of a get option and Reading to be retrieved / extracted

;get[0-9]*URL
:URL to be requested for the get option. If this option is missing, the URL specified during define will be used.

;get[0-9]*Data
:optional data to be sent to the device as POST data when the get is executed. if this attribute is not specified, an HTTP GET method will be used instead of an HTTP POST

;get[0-9]*NoData
:can be used to override a more generic attribute that specifies POST data for all get commands. With NoData no data is sent and therefor the request will be an HTTP GET.

;get[0-9]*Header
:optional HTTP Headers to be sent to the device when the get is executed

;get[0-9]+Poll
:if set to 1 the get is executed automatically during the normal update cycle (after the interval provided in the define command has elapsed)

;get[0-9]+PollDelay
:if the value should not be read in each iteration (after the interval given to the define command), then a minimum delay can be specified with this attribute. This has only an effect if the above Poll attribute has also been set. Every time the update function is called, it checks if since this get has been read the last time, the defined delay has elapsed. If not, then it is skipped this time.
:PollDelay can be specified as seconds or as x[0-9]+ which means a multiple of the interval in the define command.

;get[0-9]*Regex
:If this attribute is specified, the Regex defined here is used to extract the value from the HTTP Response and assign it to a Reading with the name defined in the get[0-9]+Name attribute.
:If this attribute is not specified for an individual Reading but as getRegex, then it applies to all get options where no specific Regex is defined.
:If neither a generic getRegex attribute nor a specific get[0-9]+Regex attribute is specified, then HTTPMOD tries all Regex / Reading pairs defined in Reading[0-9]+Name and Reading[0-9]+Regex attributes and assigns the Readings that match.

;get[0-9]*Expr
:this attribute behaves just like Reading[0-9]*Expr but is applied to a get value.

;get[0-9]*Map
:this attribute behaves just like Reading[0-9]*Map but is applied to a get value.

;get[0-9]*Format
:this attribute behaves just like Reading[0-9]*Format but is applied to a get value.

;get[0-9]*CheckAllReadings
:this attribute modifies the behavior of HTTPMOD when the HTTP Response of a get command is parsed.
:If this attribute is set to 1, then additionally to any matching of get specific regexes (get[0-9]*Regex), also all the Regex / Reading pairs defined in Reading[0-9]+Name and Reading[0-9]+Regex attributes are checked and if they match, the coresponding Readings are assigned as well.

;replacement[0-9]*Regex
:Defines a replacement to be applied to an HTTP request header, data or URL before it is sent. This allows any part of the request to be modified based on a reading, an internal or an expression.
:The regex defines which part of a header, data or URL should be replaced. The replacement is defined with the following attributes:

;replacement[0-9]*Mode
:Defines how the replacement should be done and what replacementValue means. Valid options are text, reading, interbal and expression.

;replacement[0-9]*Value
:Defines the replacement. If the corresponding replacementMode is text, then value is a static text that is used as the replacement. 
:If replacementMode is reading then Value can be the name of a reading of this device or it can be a reading of a different device referred to by devicename:reading. 
:If replacementMode is internal the Value can be the name of an internal of this device or it can be an internal of a different device referred to by devicename:internal. 
:If replacementMode is expression the the Value is treated as a Perl expression that computes the replacement value. The expression can use $1, $2 and so on to refer to capture groups of the corresponding regex that is matched against the original URL, header or post data.

;[gs]et[0-9]*Replacement[0-9]*Value
:This attribute can be used to override the replacement value for a specific get or set.

;get|reading[0-9]*MaxAge
:Defines how long a reading is valid before it is automatically overwritten with a replacement when the read function is called the next time.

;get|reading[0-9]*MaxAgeReplacement
:specifies the replacement for MaxAge - either as a static text or as a perl expression.

;get|reading[0-9]*MaxAgeReplacementMode
:specifies how the replacement is interpreted: can be text and expression.

;showMatched
:if set to 1 then HTTPMOD will create a reading with the name MATCHED_READINGS
:that contains the names of all readings that could be matched in the last request.

;showError
:if set to 1 then HTTPMOD will create a reading and event with the Name LAST_ERROR
:that contains the error message of the last error returned from HttpUtils.

;queueDelay
:HTTP Requests will be sent from a queue in order to avoid blocking when several Requests have to be sent in sequence. This attribute defines the delay between calls to the function that handles the send queue. It defaults to one second.

;queueMax
:Defines the maximum size of the send queue. If it is reached then further HTTP Requests will be dropped and not be added to the queue

;minSendDelay
:Defines the minimum time between two HTTP Requests.

== Links ==
* Beispiel: [[Wetter_und_Wettervorhersagen#Wetter_von_Weather_Underground|Wetter von WeatherUnderground auslesen]]
* {{Link2Forum|Topic=17804|LinkText=Thread}} in Fhem Forum that discusses the first version of this module
* [http://perldoc.perl.org/perlretut.html Introduction to regular expressions]
* [http://portswigger.net/burp/ BurpSuite]: Tool (local proxy) to help analyze http traffic

[[Kategorie:IP Components]]

HTTPMOD

2016-01-05T15:32:44Z

SirUli: /* Further replacements of URL, header or post data */ Corrected a typo and extended text for better understanding

{{Infobox Modul
|ModPurpose=Extract information from devices with an HTTP interface (or, more generic, from any URL) or send information to such devices
|ModType=d
|ModCmdRef=HTTPMOD
|ModForumArea=Sonstiges
|ModTechName=98_HTTPMOD.pm
|ModOwner=StefanStrobel ({{Link2FU|3960|Forum}} / [[Benutzer:StefanStrobel|Wiki]])
}}

HTTPMOD provides a generic way to retrieve information from devices with an HTTP Interface and store them in Readings or send information to such devices. It queries a given URL with Headers and data defined by attributes.

From the HTTP response it extracts readings named in attributes using Regexes, JSON or XPath parsing also defined by attributes.

In an advanced [[Konfiguration|configuration]] the module can also send information to devices. To do this, a generic <code>set</code> option can be configured using attributes.

== Availability ==
{{Randnotiz|RNText=An extended / modified version of this module that among other features adds XPath and JSON support is currently under development.
If you want to participate in early tests, please follow this {{Link2Forum|Topic=45176|LinkText=discussion thread}} in FHEM forum.
This page has already been updated to describe most of the new features. So if you need one of the new features described here and yout HTTPMOD is still the old version, load the new module
from the forum and help testing
}}
The module is part of the regular FHEM distribution.

== Prerequisites ==
This module uses the non blocking HTTP function <code>HttpUtils_NonblockingGet</code> provided by FHEM's [[HttpUtils]] in a new version published in December 2013.
If not already installed in your environment, please [[update]] FHEM or install it manually using appropriate commands from your environment.

== Define ==
<pre>
define <name> HTTPMOD <URL> <Interval>
</pre>
The module connects to the given <code>URL</code> every <code>Interval</code> seconds, sends optional headers and data and then parses the response with regular expressions, xpath or json to set readings.

URL can be "none" and Interval can be 0 if you prefer to only query data with a get command and not in a defined interval.

Example:
<pre>
define PM HTTPMOD http://MyPoolManager/cgi-bin/webgui.fcgi 60
</pre>

== Set-Commands ==
can be defined using attributes, see advanced configuration

If you set the attribute enableControlSet to 1, the following additional built in set commands are available:
;interval
:set new interval time in seconds and restart the timer
;reread
:request the defined URL and try to parse it just like the automatic update would do it every Interval seconds without modifying the running timer.
;stop
:stop interval timer.
;start
:restart interval timer to call GetUpdate after interval seconds

== Get-Commands ==
can be defined using attributes, see advanced configuration

== simple Attributes ==
;do_not_notify

;readingFnAttributes

;requestHeader.*
:Define an additional HTTP Header to set in the HTTP request

;requestData
:POST Data to be sent in the request. If not defined, it will be a GET request as defined in HttpUtils used by this module

;reading[0-9]+(-[0-9]+)?Name
:the name of a reading to extract with the corresponding readingRegex

;reading[0-9]*(-[0-9]+)?Expr
:defines an expression that is used in an eval to compute the readings value. The raw value will be in the variable $val.

;reading[0-9]*(-[0-9]+)?Map
:defines a mapping from raw to visible values like "0:mittig, 1:oberhalb, 2:unterhalb". If specified as readingMap then the attribute value is a default for all other readings that don't specify an explicit reading[0-9]*Map.

;reading[0-9]*(-[0-9]+)?Format
:Defines a format string that will be used in sprintf to format a reading value. If specified as readingFormat then the attribute value is a default for all other readings that don't specify an explicit reading[0-9]*Format.

;reading[0-9]*(-[0-9]+)?Decode
:defines an encoding to be used in a call to the perl function decode to convert the raw data string read from the device to a reading. This can be used if the device delivers strings in an encoding like cp850 instead of utf8.

;reading[0-9]*(-[0-9]+)?Encode
:defines an encoding to be used in a call to the perl function encode to convert the raw data string read from the device to a reading. This can be used if the device delivers strings in an encoding like cp850 and after decoding it you want to reencode it to e.g. utf8.

;reading[0-9]+Regex
:defines the regex to be used for extracting the reading. The value to extract should be in a sub expression e.g. ([\d\.]+) in the above example

;reading[0-9]+Regex
:defines the regex to be used for extracting the reading. The value to extract should be in a capture group / sub expression
:e.g. ([\d\.]+) in the above example. Multiple capture groups will create multiple readings (see explanation above)

;reading[0-9]+XPath
:defines an xpath to one or more readings when parsing HTML data (see examples below)

;reading[0-9]+XPath-Strict
:defines an xpath to one or more readings when parsing XML data (see examples below)

;reading[0-9]+JSON
:defines a path to the JSON object wanted by concatenating the object names with an underscore as delimiter (see the example below)

;noShutdown
:pass the noshutdown flag to HTTPUtils for webservers that need it (some embedded webservers only deliver empty pages otherwise)

;disable
:stop doing automatic HTTP requests while this attribute is set to 1

;timeout
:time in seconds to wait for an answer. Default value is 2

;enableControlSet
:enables the built in set commands interval, stop, start, reread

;(get|reading)[0-9]*RecombineExpr
:defines an expression that is used in an eval to compute one reading value out of the list of matches.
:This is supposed to be used for regexes or xpath specifications that produce multiple results if only one result that combines them is wanted.
:The list of matches will be in the variable @matchlist.

== simple Configuration of HTTP Devices ==
If your device expects special HTTP-headers then specify them as <code>attr requestHeader1</code> to <code>attr requestHeaderX</code>.
If your Device expects an HTTP POST instead of HTTP GET then the POST-data can be specified as <code>attr requestData</code>.
To get the readings, specify pairs of <code>attr readingXName</code> and <code>attr readingXRegex</code>, <code>attr readingXXPath</code>, <code>attr readingXXPath-Strict</code> or <code>attr readingXJSON</code> to define which readings you want to extract from the HTTP response and how to extract them. (The old syntax <code>attr readingsNameX</code> and <code>attr readingsRegexX</code> is still supported but the new one with <code>attr readingXName</code> and <code>attr readingXRegex</code> should be preferred. The actual values to be extracted have to be sub expressions within () in the regex (see example below)

=== Example for a PoolManager 5: ===
The PoolManager Web GUI can be queried with HTTP POST Requests like this one:

<pre>
POST /cgi-bin/webgui.fcgi HTTP/1.1
Host: 192.168.70.90
Accept: */*
Content-Type: application/json;charset=UTF-8
Content-Length: 60

{"get" :["34.4001.value" ,"34.4008.value" ,"34.4033.value"]}
</pre>

The resulting HTTP Response would look like this:

<pre>
HTTP/1.1 200 OK
Content-type: application/json; charset=UTF-8
Expires: 0
Cache-Control: no-cache
Date: Sun, 12 Jan 2014 12:23:11 GMT
Server: lighttpd/1.4.26
Content-Length: 179

{
"data": {
"34.4001.value": "7.00",
"34.4008.value": "0.52",
"34.4033.value": "24.8"
},
"status": {
"code": 0
},
"event": {
"type": 1,
"data": "48.30000.0"
}
}
</pre>

To configure HTTPMOD for a PoolManager one would first define a PoolManager device with e.g. the name PM, the URL and an interval of e.g. 60 seconds.

Then the data to be sent in the request needs to be defined because in this example the device expects a POST request so the query is not contained in the URL but in the request data.

Also as seen above the device expects special HTTP headers in the request so these headers also need to be defined as <code>attr PM requestHeader1</code> and <code>attr PM requestHeader2</code>

Then the names of the readings to be extracted would be set with attributes

Then for each reading value to be extracted a regular expression needs to be set that will match the value in question within ().

Example:
<pre>
define PM HTTPMOD http://MyPoolManager/cgi-bin/webgui.fcgi 60
attr PM reading01Name PH
attr PM reading01Regex 34.4001.value":[ \t]+"([\d\.]+)"

attr PM reading02Name CL
attr PM reading02Regex 34.4008.value":[ \t]+"([\d\.]+)"

attr PM reading03Name3TEMP
attr PM reading03Regex 34.4033.value":[ \t]+"([\d\.]+)"

attr PM requestData {"get" :["34.4001.value" ,"34.4008.value" ,"34.4033.value", "14.16601.value", "14.16602.value"]}
attr PM requestHeader1 Content-Type: application/json
attr PM requestHeader2 Accept: */*
attr PM stateFormat {sprintf("%.1f Grad, PH %.1f, %.1f mg/l Chlor", ReadingsVal($name,"TEMP",0), ReadingsVal($name,"PH",0), ReadingsVal($name,"CL",0))}
</pre>

=== Example for AmbientMonitor ===
AmbientMonitor is a webbased visualisation for sensors connected to an Arduino device. Its web interface can also be queried with HTTMOD to grab the data into readings.

This example was provided by locutus. The hardware configuration is an Arduino + Ethercard with ENC28J60 Controller + DHT22 Sensor and software can be downloaded from https://github.com/lucadentella/AmbientMonitor

In this example an HTTP GET is sufficent, so no <code>requestData</code> is needed. The device provides temperature and humidity readings in an HTTP response that looks like:
<pre>
HTTP/1.0 200 OK
Content-Type: text/html

myCB({'temperature':22.00,'humidity':46.00})
</pre>

the definition could be:
<pre>
define AmbientMonitor HTTPMOD http://192.168.1.221/?callback=? 300
attr AmbientMonitor requestHeader Content-Type: application/json
attr AmbientMonitor reading1Name Temperatur
attr AmbientMonitor reading1Regex temperature':([\d\.]+)
attr AmbientMonitor reading2Name Feuchtigkeit
attr AmbientMonitor reading2Regex humidity':([\d\.]+)
attr AmbientMonitor stateFormat {sprintf("Temperatur %.1f C, Feuchtigkeit %.1f %", ReadingsVal($name,"Temperatur",0), ReadingsVal($name,"Feuchtigkeit",0))}
</pre>

== formating and manipulating values / readings ==
Values that are parsed from an HTTP response can be further treated or formatted with the following attributes:

* (reading|get)[0-9]*(-[0-9]+)?Expr
* (reading|get)[0-9]*(-[0-9]+)?Map
* (reading|get)[0-9]*(-[0-9]+)?Format
* (reading|get)[0-9]*(-[0-9]+)?Decode
* (reading|get)[0-9]*(-[0-9]+)?Encode

They can all be specified for an individual reading, for all readings in one match (e.g. if a regular expression has several capture groups)or for all readings in a get command (defined by getXX) or for all readings in the main reading list (defined by readingXX):
<pre>
reading01Format %.1f
</pre>

will format the reading with the name specified by the attribute reading01Name to be numerical with one digit after the decimal point.
If the attribute reading01Regex is used and contains several capture groups then the format will be applied to all readings thet are parsed by this regex unless these readings have their own format specified by reading01-1Format, reading01-2Format and so on.

<pre>
reading01-2Format %.1f
</pre>

Can be used in cases where a regular expression specified as reading1regex contains several capture groups or an xpath specified as reading01XPath creates several readings.
In this case reading01-2Format specifies the format to be applied to the second match.

<pre>
readingFormat %.1f
</pre>

applies to all readings defined by a reading-Attribute that have no more specific format.

If you need to do some calculation on a raw value before it is used as a reading, you can define the attribute <code>readingExpr</code>.
It defines a Perl expression that is used in an eval to compute the readings value. The raw value will be in the variable $val.

=== Example: ===
<pre>
attr PM reading03Expr $val * 10
</pre>
Just like in the above example of the readingFormat attributes, readingExpr and the other following attributes can be applied on several levels.

To map a numerical value to a name, you can use the readingMap attribute.
It defines a mapping from raw to visible values like "0:mittig, 1:oberhalb, 2:unterhalb".

=== Example: ===
<pre>
attr PM reading02-3Map 0:kalt, 1:warm, 2:sehr warm
</pre>

To convert character sets, the module can first decode a string read from the device and then encode it again. For example:
<pre>
attr PM getDecode UTF-8
</pre>

This applies to all readings defined for Get-Commands.

== Some help with Regular Expressions ==
If HTTPMOD seems not to work and the FHEM Logfile contains a message like
:<code>HTTPMOD: Response didn't match Reading ...</code>
then you should check if the value you want to extract is read into the internal with the name buf. Internals are visible when you click on the defined HTTPMOD Device. buf is an internal variable that contains the HTTP Response read. If the value is there and you get the mentioned message then probably something is wrong with your regular expression. If you are new to regular expressions then the introduction at http://perldoc.perl.org/perlretut.html might be helpful.

For a typical HTTPMOD use case where you want to extract a number out of a HTTP-Response you can use something like <code>[\d\.]+</code> to match the number itself. The expression matches the number characters (<code>\d</code>) or a <code>.</code> if one of these characters occurs at least once.

To tell HTTPMOD that the number is what you want to use for the reading, you have to put the expression in between <code>()</code>. A <code>([\d\.]+)</code> alone would match the longest number in the HTTP Response which is very likely not the number you are looking for so you need to add something to the expression to give it a context and define how to find the number that you are looking for.
if there is a title text before the number or a special text after the number you can put this in the regex. In one of the examples above <code>humidity':([\d\.]+)</code> is looking for the number that immediately follows the text <code>humidity':</code> without any blanks in between.

=== Regular Expressions with multiple capture Groups ===
The regular expressions used in the above example for a Poolmanager will take the value that matches one capture group. This is the part of the regular expression inside (). In the above example "([\d\.]+)" refers to numerical digits or points between double quotation marks. Only the string consiting of digits and points will match inside (). This piece is assigned to the reading.

You can also use regular expressions that have several capture groups which might be helpful when parsing tables. In this case an attribute like

<pre>
reading02Regex something[ \t]+([\d\.]+)[ \t]+([\d\.]+)
</pre>

could match two numbers. When you specify only one reading02Name like
<pre>
reading02Name Temp
</pre>

the name Temp will be used with the extension -1 and -2 thus giving a reading Temp-1 for the first number and Temp-2 for the second. You can also specify individual names for several readings that get parsed from one regular expression with several capture groups by defining attributes

<pre>
reading02-1Name
reading02-2Name
...
</pre>
The same notation can be used for formatting attributes like readingXMap, readingXFormat and so on.

The usual way to define readings is however to have an individual regular expression with just one capture group per reading as shown in the above example.

== Parsing JSON ==

If a webservice delivers data in JSON format, HTTPMOD can directly parse JSON which might be easier in this case than definig regular expressions.
The next example shows the data that can be requested from a Poolmanager with the following partial configuration:

<pre>
define test2 HTTPMOD none 0
attr test2 get01Name Chlor
attr test2 getURL http://192.168.70.90/cgi-bin/webgui.fcgi
attr test2 getHeader1 Content-Type: application/json
attr test2 getHeader2 Accept: */*
attr test2 getData {"get" :["34.4008.value"]}
</pre>

The data in the HTTP response looks like this:

<pre>
{
"data": {
"34.4008.value": "0.25"
},
"status": {
"code": 0
},
"event": {
"type": 1,
"data": "48.30000.0"
}
}
</pre>

the classic way to extract the value 0.25 into a reading with the name Chlor with a regex would have been
<pre>
attr test2 get01Regex 34.4008.value":[ \t]+"([\d\.]+)"
</pre>

with JSON you can write
<pre>
attr test2 get01JSON data_34.4008.value
</pre>

or if you don't care about the naming of your readings, you can simply extract all JSON data with
<pre>
attr test2 extractAllJSON
</pre>

which would apply to all data read from this device and create the following readings out of the HTTP response shown above:

{| class="wikitable"
| data_34.4008.value || 0.25
|-
| event_data || 48.30000.0
|-
| event_type || 1
|-
| status_code || 0
|}

or you can specify
<pre>
attr test2 get01ExtractAllJSON
</pre>
which would only apply to all data read as response to the get command defined as get01.

== Parsing http / XML using xpath ==
Another alternative to regex parsing is the use of XPath to extract values from HTTP responses.
The following example shows how XML data can be parsed with XPath-Strict or HTML Data can be parsed with XPath.
Both work similar and the example uses XML Data parsed with the XPath-Strict option:

If The XML data in the HTTP response looks like this:

<pre>
<root xmlns:foo="http://www.foo.org/" xmlns:bar="http://www.bar.org">
<actors>
<actor id="1">Peter X</actor>
<actor id="2">Charles Y</actor>
<actor id="3">John Doe</actor>
</actors>
</root>
</pre>

with XPath you can write
<pre>
attr htest reading01Name Actor
attr htest reading01XPath-Strict //actor[2]/text()
</pre>

This will create a reading with the Name "Actor" and the value "Charles Y".

Since XPath specifications can define several values / matches, HTTPMOD can also interpret these and store them in multiple readings:
<pre>
attr htest reading01Name Actor
attr htest reading01XPath-Strict //actor/text()
</pre>

will create the readings

{| class="wikitable"
| Actor-1 | Peter X
|-
| Actor-2 | Charles Y
|-
| Actor-3 | John Doe
|}

== Further replacements of URL, header or post data ==
sometimes it might be helpful to dynamically change parts of a URL, HTTP header or post data depending on existing readings, internals or
perl expressions at runtime. This might be needed to pass further variables to a server, a current date or other things.

To support this HTTPMOD offers generic replacements that are applied to a request before it is sent to the server. A replacement can be defined with the attributes

* <code>replacement[0-9]*Regex</code>
* <code>replacement[0-9]*Mode</code>
* <code>replacement[0-9]*Value</code>
* <code>[gs]et[0-9]*Replacement[0-9]*Value</code>

a replacement always replaces a match of a regular expression.

'''replacement[0-9]*Mode:'''
The way the replacement value is defined can be specified with the replacement mode.
* If the <code>replacement[0-9]*Mode</code> is <code>reading</code>, then the corresponding <code>replacement[0-9]*Value</code> is interpreted as the name of a ''reading'' of the same device or as ''device:reading'' to refer to another device.
* If the <code>replacement[0-9]*Mode</code> is <code>internal</code>, then the corresponding <code>replacement[0-9]*Value</code> is interpreted as the name of an ''internal'' of the same device or as ''device:internal'' to refer to another device.
* If the <code>replacement[0-9]*Mode</code> is <code>text</code>, then the corresponding <code>replacement[0-9]*Value</code> is interpreted as a static text
* If the <code>replacement[0-9]*Mode</code> is <code>expression</code> , then the corresponding <code>replacement[0-9]*Value</code> is evaluated as a perl expression to compute the replacement. Inside such a replacement expression it is possible to refer to capture groups of the replacement regex.

Example:

<source lang="perl">
attr mydevice getData {"get" :["%%value%%.value"]}
attr mydevice replacement01Mode text
attr mydevice replacement01Regex %%value%%

attr mydevice get01Name Chlor
attr mydevice get01Replacement01Value 34.4008

attr mydevice get02Name Something
attr mydevice get02Replacement01Value 31.4024
</source>

defines that <code>%%value%%</code> will be replaced by a static text.

All Get commands will be HTTP post requests of a similar form. Only the <code>%%value%%</code> will be different from get to get.
The first get will set the reading named Chlor and for the request it will take the generic getData and replace %%value%% with 34.4008.
A second get will look the same except a different name and replacement value.

The mode expression allows you to define your own replacement syntax:
<source lang="perl">
attr mydevice replacement01Mode expression
attr mydevice replacement01Regex {{([^}]+)}}
attr mydevice replacement01Value ReadingsVal("mydevice", $1, "")
attr mydevice getData {"get" :["{{temp}}.value"]}
</source>

In this example any <code><nowiki>{{name}}</nowiki></code> in a URL, header or post data will be passed on to the perl function ReadingsVal
which uses the string between <code><nowiki>{{}}</nowiki></code> as second parameter. This way one defined replacement can be used for many different
readings.

== replacing reading values when they have not been updated / the device did not respond ==
If a device does not respond then the values stored in readings will keep the same and only their timestamp shows that they are outdated.
If you want to modify reading values that have not been updated for a number of seconds, you can use the attributes

* (reading|get)[0-9]*(-[0-9]+)?MaxAge
* (reading|get)[0-9]*(-[0-9]+)?MaxAgeReplacementMode
* (reading|get)[0-9]*(-[0-9]+)?MaxAgeReplacement

Every time the module tries to read from a device, it will also check if readings have not been updated
for longer than the MaxAge attributes allow. If readings are outdated, the MaxAgeReplacementMode defines how the affected
reading values should be replaced. MaxAgeReplacementMode can be <code>text</code> or <code>expression</code>.

MaxAge specifies the number of seconds that a reading should remain untouched before it is replaced.

MaxAgeReplacement contains either a static text that is used as replacement value or a Perl expression that is evaluated to
give the replacement value. This can be used for example to replace a temperature that has not bee updated for more than 5 minutes
with the string "outdated - was 12":
<pre>
attr PM readingMaxAge 300
attr PM readingMaxAgeReplacement "outdated - was " . $val
attr PM readingMaxAgeReplacementMode expression
</pre>
The variable $val contains the value of the reading before it became outdated.

== Additional notes ==
If you don't know which URLs, headers or POST data your web GUI uses, you might try a local proxy like BurpSuite [http://portswigger.net/burp/ BurpSuite] to track requests and responses

== Advanced configuration to define a <code>set</code> and send data to a device ==

When a set option is defined by attributes, the module will use the value given to the set command and integrate it into an HTTP-Request that sends the value to the device. The definitions for URL, headers and post data can contain the placeholder $val which will be replaced by the value given to the set command.

This can be as simple as:
<pre>
# No cyclic requests and no main URL needed in this example
define MyDevice none 0

attr MyDevice set01Name Licht
attr MyDevice set01URL http://192.168.1.22/switch=$val
</pre>

A user command
<pre>
set MyDevice Licht 1
</pre>

will be translated into the http GET request
<pre>
http://192.168.1.22/switch=1
</pre>

In this example a map would also be helpful, that translates on / off to 0 or 1 and allows the user to select on/of in fhemweb:
<pre>
attr MyDevive set01Map 0:off, 1:on
</pre>
This also provides input validation to make sure that only on and off can be used with the set command.

In more complex Scenarios you might need to login before sending a command and the Login might create a session id that has to be part of further requests either in the URL, in headers or in the post data.

Extension to the above example for a PoolManager 5 where a set needs a session id in the URL and the values have to be passed in JSON strings as post data:
<pre>
attr PM set01Name HeizungSoll
attr PM set01URL http://MyPoolManager/cgi-bin/webgui.fcgi?sid=$sid
attr PM set01Hint 6,10,20,30
attr PM set01Min 6
attr PM set01Max 30
attr PM setHeader1 Content-Type: application/json
attr PM set01Data {"set" :{"34.3118.value" :"$val" }}
</pre>

This example defines a set option with the name HeizungSoll.
By issuing <code>set PM HeizungSoll 10</code> in FHEM, the value 10 will be sent in the defined HTTP
Post to URL <code>http://MyPoolManager/cgi-bin/webgui.fcgi</code> in the Post Data as

<pre>
{"set" :{"34.3118.value" :"10" }}
</pre>

The optional attributes set01Min and set01Max define input validations that will be checked in the set function.
The optional attribute set01Hint will define a selection list for the Fhemweb GUI.

If a parameter to a set command is not numeric but should be passed on to the device as text, then you can specify the attribute setTextArg. For example:
<pre>
attr PM set01TextArg
</pre>

If a set command should not require a parameter at all, then you can specify the attribute NoArg. For example:
<pre>
attr PM set03Name On
attr PM set03NoArg
</pre>

=== Advanced configuration to create a valid session id that might be necessary in set options ===
In simple cases logging in works with basic authentication. In the case HTTPMOD accepts a username and password as part of the URL in the form
<pre>
http://User:Password@192.168.1.18/something
</pre>

However basic auth is seldom used. If you need to fill in a username and password in a HTML form and the session is then managed by a session id, here is how to configure this:

when sending data to an HTTP-Device in a set, HTTPMOD will replace any <code>$sid</code> in the URL, Headers and Post data with the internal <code>$hash->{sid}</code>. To authenticate towards the device and give this internal a value, you can use an optional multi step login procedure defined by the following attributes:

;sid[0-9]*URL
;sid[0-9]*IDRegex
;sid[0-9]*Data.*
;sid[0-9]*Header.*
;sid[0-9]*IgnoreRedirects

Each step can have a URL, Headers, Post Data pieces and a Regex to extract a resulting Session ID into <code>$hash->{sid}</code>.
HTTPMOD will create a sorted list of steps (the numbers between sid and URL / Data / Header) and the loop through these steps and send the corresponding requests to the device. For each step a $sid in a Header or Post Data will be replaced with the current content of <code>$hash->{sid}</code>.

Using this feature, HTTPMOD can perform a forms based authentication and send user name, password or other necessary data to the device and save the session id for further requests.

To determine when this login procedure is necessary, HTTPMOD will first try to do a set without
doing the login procedure. If the Attribute ReAuthRegex is defined, it will then compare the HTTP Response to the set request with the regular expression from ReAuthRegex. If it matches, then a
login is performed. The ReAuthRegex is meant to match the error page a device returns if authentication or reauthentication is required e.g. because a session timeout has expired.

If for one step not all of the URL, Data or Header Attributes are set, then HTTPMOD tries to use a
<code>sidURL</code>, <code>sidData.*</code> or <code>sidHeader.*</code> Attribue (without the step number after sid). This way parts that are the same for all steps don't need to be defined redundantly.

=== Example for a multi step login procedure: ===

<pre>
attr PM reAuthRegex /html/dummy_login.htm
attr PM sidURL http://192.168.70.90/cgi-bin/webgui.fcgi?sid=$sid
attr PM sidHeader1 Content-Type: application/json
attr PM sid1IDRegex wui.init\('([^']+)'
attr PM sid2Data {"set" :{"9.17401.user" :"fhem" ,"9.17401.pass" :"password" }}
attr PM sid3Data {"set" :{"35.5062.value" :"128" }}
attr PM sid4Data {"set" :{"42.8026.code" :"pincode" }}
</pre>

In this case HTTPMOD detects that a login is necessary by looking for the pattern /html/dummy_login.htm in the HTTP response.
If it matches, it starts a login sequence. In the above example all steps request the same URL. In step 1 only the defined Header is sent in an HTTP get request. The response will contain a session id that is extraced with the regex wui.init\('([^']+)'.

In the next step this session id is sent in a post request to the same URL where tha post data contains a username and password. The a third and a fourth request follow that set a value and a code. The result will be a valid and authorized session id that can be used in other requests where $sid is part of a URL, header or post data and will be replaced with the session id extracted above.

== Advanced configuration to define a <code>get</code> and request additional data with its own request from a device ==

The normal automatic HTTP request that is done repeatedly after the defined interval has elapsed works well in cases where all required readings can be requested in one common HTTP request. If however a device needs individual requests with different URLs or different POST data for each value, then another method is necessary.
For such cases a <code>get</code> option can be defined and the user can either issue Fhem <code>get</code> commands each time he needs the reading or the user can set an attribute to request the reading automatically together with the normal iteration.
For each <code>get</code> option attributes define an individual URL, optional headers, and post data as well as individual regular expressions and formatting options.

Example for a Siemens webserver provided by Lanhydrock:
<pre>
define ozw672 HTTPMOD https://192.168.178.8/api/auth/login.json?user=test&pwd=test 300

attr ozw672 get1Name tempAussen
attr ozw672 get1URL https://192.168.178.8/api/menutree/read_datapoint.json?SessionId=$sid&Id=1960
attr ozw672 get1Poll 1
attr ozw672 get1PollDelay 1800

attr ozw672 get2Name tempAussenGemischt
attr ozw672 get2URL https://192.168.178.8/api/menutree/read_datapoint.json?SessionId=$sid&Id=1964
attr ozw672 get2Poll 1
attr ozw672 get2PollDelay 1800

attr ozw672 get3Name tempTWW
attr ozw672 get3URL https://192.168.178.8/api/menutree/read_datapoint.json?SessionId=$sid&Id=1996
attr ozw672 get3Poll 1

attr ozw672 get4Name tempKesselSoll
attr ozw672 get4URL https://192.168.178.8/api/menutree/read_datapoint.json?SessionId=$sid&Id=1910
attr ozw672 get4Poll 1

attr ozw672 get5Name tempKesselRuecklauf
attr ozw672 get5URL https://192.168.178.8/api/menutree/read_datapoint.json?SessionId=$sid&Id=1915
attr ozw672 get5Poll 1

attr ozw672 get6Name tempKesselRuecklaufSoll
attr ozw672 get6URL https://192.168.178.8/api/menutree/read_datapoint.json?SessionId=$sid&Id=1916
attr ozw672 get6Poll 1

attr ozw672 get7Name anzahlStartsBrenner
attr ozw672 get7URL https://192.168.178.8/api/menutree/read_datapoint.json?SessionId=$sid&Id=1927
attr ozw672 get7PollDelay 1800
attr ozw672 get7Poll 1

attr ozw672 get8Name statusKessel
attr ozw672 get8URL https://192.168.178.8/api/menutree/read_datapoint.json?SessionId=$sid&Id=1898
attr ozw672 get8Poll 1
attr ozw672 get8Regex Value": "([a-zA-Zü ]*)"
attr ozw672 get8Map Aus:0, Nachlauf aktiv:5, Freigegeben für TWW:10, Freigegeben für HK:20, In Teillastbetrieb für TWW:40, In Teillastbetrieb für HK:50, In Betrieb für Trinkwasser:90, In Betrieb für Heizkreis:100

attr ozw672 getRegex Value": "[ ]*([-.0-9]*)"

attr ozw672 reAuthRegex .*session not valid.*
attr ozw672 sid1IDRegex .*"(.*-.*-.*-[0-9a-z]*).*
attr ozw672 sid1URL https://192.168.178.8/api/auth/login.json?user=test&pwd=test
</pre>

=== Advanced attributes ===

;ReAuthRegex
:regular Expression to match an error page indicating that a session has expired and a new authentication for read access needs to be done.
:This attribute only makes sense if you need a forms based authentication for reading data and if you specify a multi step login procedure based on the sid.. attributes.
:This attribute is used for all requests. For set and get operations you can however specify individual reAuthRegexes with the [gs]et[0-9]*ReAuthRegex attributes.

;sid[0-9]*URL
:different URLs or one common URL to be used for each step of an optional login procedure.

;sid[0-9]*IDRegex
:different Regexes per login procedure step or one common Regex for all steps to extract the session ID from the HTTP response

;sid[0-9]*Data.*
:data part for each step to be sent as POST data to the corresponding URL

;sid[0-9]*Header.*
:HTTP Headers to be sent to the URL for the corresponding step

;sid[0-9]*IgnoreRedirects
:Tells the HttpUtils to not follow HTTP Redirects for this Request. Might be needed for some devices that set a session cookie within a 303 Redirect.

;set[0-9]+Name
:Name of a set option

;set[0-9]*URL
:URL to be requested for the set option

;set[0-9]*Data
:Data to be sent to the device as POST data when the set is executed

;set[0-9]*Header
:HTTP Headers to be sent to the device when the set is executed

;set[0-9]+Min
:Minimum value for input validation.

;set[0-9]+Max
:Maximum value for input validation.

;set[0-9]+Expr
:Perl Expression to compute the raw value to be sent to the device from the input value passed to the set.

;set[0-9]+Map
:Map that defines a mapping from raw to visible values like "0:mittig, 1:oberhalb, 2:unterhalb". This attribute atomatically creates a hint for FhemWEB so the user can choose one of the visible values or select a value with a slider.

;set[0-9]+Hint
:Explicit hint for fhemWEB that will be returned when set ? is seen. Can be used to get a slider or a list of values to choose from.

;set[0-9]*ReAuthRegex
:Regex that will detect when a session has expired an a new login needs to be performed.

;get[0-9]+Name
:Name of a get option and Reading to be retrieved / extracted

;get[0-9]*URL
:URL to be requested for the get option. If this option is missing, the URL specified during define will be used.

;get[0-9]*Data
:optional data to be sent to the device as POST data when the get is executed. if this attribute is not specified, an HTTP GET method will be used instead of an HTTP POST

;get[0-9]*NoData
:can be used to override a more generic attribute that specifies POST data for all get commands. With NoData no data is sent and therefor the request will be an HTTP GET.

;get[0-9]*Header
:optional HTTP Headers to be sent to the device when the get is executed

;get[0-9]+Poll
:if set to 1 the get is executed automatically during the normal update cycle (after the interval provided in the define command has elapsed)

;get[0-9]+PollDelay
:if the value should not be read in each iteration (after the interval given to the define command), then a minimum delay can be specified with this attribute. This has only an effect if the above Poll attribute has also been set. Every time the update function is called, it checks if since this get has been read the last time, the defined delay has elapsed. If not, then it is skipped this time.
:PollDelay can be specified as seconds or as x[0-9]+ which means a multiple of the interval in the define command.

;get[0-9]*Regex
:If this attribute is specified, the Regex defined here is used to extract the value from the HTTP Response and assign it to a Reading with the name defined in the get[0-9]+Name attribute.
:If this attribute is not specified for an individual Reading but as getRegex, then it applies to all get options where no specific Regex is defined.
:If neither a generic getRegex attribute nor a specific get[0-9]+Regex attribute is specified, then HTTPMOD tries all Regex / Reading pairs defined in Reading[0-9]+Name and Reading[0-9]+Regex attributes and assigns the Readings that match.

;get[0-9]*Expr
:this attribute behaves just like Reading[0-9]*Expr but is applied to a get value.

;get[0-9]*Map
:this attribute behaves just like Reading[0-9]*Map but is applied to a get value.

;get[0-9]*Format
:this attribute behaves just like Reading[0-9]*Format but is applied to a get value.

;get[0-9]*CheckAllReadings
:this attribute modifies the behavior of HTTPMOD when the HTTP Response of a get command is parsed.
:If this attribute is set to 1, then additionally to any matching of get specific regexes (get[0-9]*Regex), also all the Regex / Reading pairs defined in Reading[0-9]+Name and Reading[0-9]+Regex attributes are checked and if they match, the coresponding Readings are assigned as well.

;replacement[0-9]*Regex
:Defines a replacement to be applied to an HTTP request header, data or URL before it is sent. This allows any part of the request to be modified based on a reading, an internal or an expression.
:The regex defines which part of a header, data or URL should be replaced. The replacement is defined with the following attributes:

;replacement[0-9]*Mode
:Defines how the replacement should be done and what replacementValue means. Valid options are text, reading, interbal and expression.

;replacement[0-9]*Value
:Defines the replacement. If the corresponding replacementMode is text, then value is a static text that is used as the replacement. 
:If replacementMode is reading then Value can be the name of a reading of this device or it can be a reading of a different device referred to by devicename:reading. 
:If replacementMode is internal the Value can be the name of an internal of this device or it can be an internal of a different device referred to by devicename:internal. 
:If replacementMode is expression the the Value is treated as a Perl expression that computes the replacement value. The expression can use $1, $2 and so on to refer to capture groups of the corresponding regex that is matched against the original URL, header or post data.

;[gs]et[0-9]*Replacement[0-9]*Value
:This attribute can be used to override the replacement value for a specific get or set.

;get|reading[0-9]*MaxAge
:Defines how long a reading is valid before it is automatically overwritten with a replacement when the read function is called the next time.

;get|reading[0-9]*MaxAgeReplacement
:specifies the replacement for MaxAge - either as a static text or as a perl expression.

;get|reading[0-9]*MaxAgeReplacementMode
:specifies how the replacement is interpreted: can be text and expression.

;showMatched
:if set to 1 then HTTPMOD will create a reading with the name MATCHED_READINGS
:that contains the names of all readings that could be matched in the last request.

;showError
:if set to 1 then HTTPMOD will create a reading and event with the Name LAST_ERROR
:that contains the error message of the last error returned from HttpUtils.

;queueDelay
:HTTP Requests will be sent from a queue in order to avoid blocking when several Requests have to be sent in sequence. This attribute defines the delay between calls to the function that handles the send queue. It defaults to one second.

;queueMax
:Defines the maximum size of the send queue. If it is reached then further HTTP Requests will be dropped and not be added to the queue

;minSendDelay
:Defines the minimum time between two HTTP Requests.

== Links ==
* Beispiel: [[Wetter_und_Wettervorhersagen#Wetter_von_Weather_Underground|Wetter von WeatherUnderground auslesen]]
* {{Link2Forum|Topic=17804|LinkText=Thread}} in Fhem Forum that discusses the first version of this module
* [http://perldoc.perl.org/perlretut.html Introduction to regular expressions]
* [http://portswigger.net/burp/ BurpSuite]: Tool (local proxy) to help analyze http traffic

[[Kategorie:IP Components]]

Cmdalias

2015-12-30T13:27:19Z

SirUli: /* autocreate */ Eine Codestelle vergessen, sorry :/

{{SEITENTITEL:cmdalias}}
{{Infobox Modul
|ModPurpose=Erstellen von Benutzer-definierten Befehlen in FHEM
|ModType=cmd
|ModCmdRef=cmdalias
|ModForumArea=FHEM
|ModTechName=98_cmdalias.pm
|ModOwner={{Link2FU|8|Rudolf König}}
}}

Der Fhem-Befehl [[cmdalias]] dient zur Erstellung von benutzerdefinierten Befehlen.

= Zielsetzung =
Die jeweiligen Befehlsketten können mit ''cmdalias'' verkürzt oder sogar verändert werden.
Ein schönes Beispiel dafür ist, dass sogar [[:Kategorie:FhemBefehl|interne Befehle]] wie "shutdown restart" ersetzt werden können durch einen alias der genau so heißt aber zusätzlich vorher noch z.B. ein "save" ausführt.

= Einbindung in Fhem =
{{Randnotiz|RNTyp=y|RNText=Die folgenden Codebeispiele sind, sofern nicht anders erwähnt, als Einzeiler '''ohne''' Zeilenumbrüche einzugeben.}}
<source lang="perl">define <name> cmdalias <cmd> [parameter] AS newcommand..."</source>

'''Beispieldefinition'''
<source lang="perl">define s1 cmdalias shutdown update AS save;;shutdown</source>
<source lang="perl">define s2 cmdalias set lamp .* AS { Log 1, "$EVENT";; fhem("set $EVENT") }</source>

= Aufruf in Fhem =
[[Datei:cmdalias_eingabe_telnet.png|mini|right|400px|Ausgabe Telnet]]
Die aliase können entweder in der FHEM Befehlzeile oder direkt im Telnet eingegeben werden.

[[Datei:cmdalias_eingabe_fhemweb.png|mini|right|400px|Ausgabe in FHEMWEB]]
= Beispiele =
== ls ==
Verkürzter Aufruf von list mit Wildcard Suche
<source lang="perl">define c_ls cmdalias ls .* AS list .*$EVENT.*</source>

== showignoreddevices ==
Auflisten von Geräten, die in FHEM das Attribut "ignore" gesetzt haben:
<source lang="perl">define c_showignoreddevices cmdalias showignoreddevices AS { join("\n", grep { $attr{$_}{ignore} } sort keys %attr ) }</source>

== shownotypedevices ==
Auflisten von Geräten ohne TYPE Definition (sollte nur bei einer fehlerhaften Definition eine Ausgabe erstellen):
<source lang="perl">define c_shownotypedevices cmdalias shownotypedevices AS { join("\n", grep { !defined($defs{$_}{TYPE}) } keys %defs) }</source>

== v5 ==
Setzen des "Verbose Level" in FHEM auf 5
<source lang="perl">define c_v5 cmdalias v5 .* AS {fhem ("attr ".($EVENT||="global")." verbose 5")}</source>

== v3 ==
Setzen des "Verbose Level" in FHEM auf 3
<source lang="perl">define c_v3 cmdalias v3 .* AS {fhem ("attr ".($EVENT||="global")." verbose 3")}</source>

== Änderung von Geräte Aktionen ==
In diesem Beispiel wird dem Gerät MiLight_1 nicht erlaubt ausgeschaltet zu werden
<source lang="perl">define c_aliasMiLight_1 cmdalias set MiLight_1 off AS set HMSchaltaktor_1 off</source>

== say ==
Verkürzter Befehlsaufruf des TTS Moduls
<source lang="perl">define c_say cmdalias say .* AS set MyTTS tts '$EVENT'</source>

== roomrename ==
Umbenennen eines FHEM Raumes '''Aufruf roomrename <oldroom> <newroom>'''
<source lang="perl">define c_roomrename cmdalias roomrename .* AS { for my $name (devspec2array("room=$EVTPART0")){ map {s/$EVTPART0/$EVTPART1/;; fhem("attr $name room $_")} AttrVal($name,'room','') } }</source>

== roomdelete ==
Löschen eines FHEM Raumes '''Aufruf: roomdelete <roomName>'''
<source lang="perl">define c_roomdelete cmdalias roomdelete .* AS { for my $name (devspec2array("room=$EVENT")){ map { /^$EVENT$/ ? fhem("deleteattr $name room") : do{s/,$EVENT|$EVENT,//;; fhem("attr $name room $_")} } AttrVal($name,'room','') } }</source>

== regroup ==
Umfangreicher alias zum automatischen Setzen verschiedener Gruppen in FHEM Räumen

<source lang="perl">define c_regroup cmdalias regroup .* AS { my @EVTPART=split(' ',$EVENT);; $EVTPART[2] =~ s/\|/:FILTER=/g if($EVTPART[2]);; for my $name (devspec2array("group=".($EVTPART[0] ? $EVTPART[0] : '.*').($EVTPART[2] ? ":FILTER=$EVTPART[2]" : ''))){ map { ($_ && /^$EVTPART[0]$/ && !$EVTPART[1]) ? fhem("deleteattr $name group") : do{ if(!$EVTPART[1]){$EVTPART[0]=",$EVTPART[0]|$EVTPART[0],";; $EVTPART[1]='';;} s/$EVTPART[0]/$EVTPART[1]/;; fhem("attr $name group $_")} } AttrVal($name,'group',0) } }</source>

Die zusätzlichen Gruppen, in welchen sich die devices sonst noch befinden, bleiben unberührt. Als FILTER kann alles was der normale fhem-devspec Filter verarbeiten kann angegeben werden. Es sollte nur aufgepasst werden, wenn ein "Device" mehrere ähnliche Gruppenbennungen wie "attr name group test2,test" hat. Wenn man hier ein 'regroup test test3' macht, könnte es passieren, dass man dadurch bei diesem device die Gruppe 'test2' nach 'test32' umbenennt. In dem Beispiel müsste man den Befehl z.B. mit 'regroup test$ test3' angeben, damit das nicht passiert.

Beispiele:
<pre>regroup <oldGroup> [<newGroup> [<FILTER>][|<FILTER2>]...]

# Allen devices ohne group die Gruppe 'myGroup' setzen:
regroup 0 myGroup

# Nur den devices im Raum 'myRoom' welche keine group haben die Gruppe 'myGroup' setzen:
regroup 0 myGroup room=myRoom

# Alle devices aus 'oldGroup' in 'newGroup' verschieben
regroup oldGroup newGroup

# Nur die devices im Raum 'myRoom' aus 'oldGroup' in 'newGroup' verschieben
regroup oldGroup newGroup room=myRoom

# Gruppe 'myGroup' löschen
regroup myGroup

# Nur die devices im Raum 'myRoom' aus der Gruppe 'myGroup' löschen.
regroup myGroup 0 room=myRoom

# Devices aus allen Gruppen welche mit 'licht' beginnen aus Raum 'Obergeschoss' entfernen.
regroup licht.* 0 room=Obergeschoss

# Devices aus dem Raum 'myRoom' aus allen Gruppen entfernen und in die Gruppe 'myGroup' verschieben.
regroup .* myGroup room=myRoom

# Devices ohne Gruppe aus dem Raum 'myRoom' mit dem TYPE 'CUL_HM' und welche ebenfalls 'Licht' im Namen enthalten die Gruppe 'myGroup' hinzufügen
regroup 0 myGroup room=myRoom|TYPE=CUL_HM|NAME=.*Licht.*</pre>

== autocreate ==
Schnelles (de)aktivieren der [[autocreate]] Funktion:
<source lang="perl">
define c_autocreate_off cmdalias set autocreate off AS attr autocreate disable 1
define c_autocreate_on cmdalias set autocreate on AS attr autocreate disable 0
</source>

Optional kann noch das autocreate Icon definiert werden:
<source lang="perl">attr autocreate devStateIcon disabled:ios-off:on active:ios-on-blue:off</source>

== renamehm ==
Homematic Devices werden gerne mit zusätzlichen Geräten angelegt (z.B: HM-ES-PMSw1-PI legt die Geräte HM_12345B, HM_12345B_Pwr, HM_12345B_SenF, HM_12345B_SenI, HM_12345B_SenPwr, HM_12345B_SenU, HM_12345B_Sw an). Um diese umzubenennen kann man mit der folgenden Funktion den Prefix von HM_12345B auf einen beliebigen Ändern. Diese wird nach Definition via "<code>renamehm HM_12345B NEW_DEVICE_PREFIX</code>" ausgeführt:
<source lang="perl">define c_renamehm cmdalias renamehm .* AS { for my $name (devspec2array("$EVTPART0.*")){ my $newname=$name;;$newname =~ s/$EVTPART0/$EVTPART1/gi;; fhem("rename $name $newname");;} }</source>

= Links =
* Thread über das Modul im {{Link2Forum|Topic=15648|LinkText=Fhem Forum}}
* Thread mit {{Link2Forum|Topic=42211|LinkText=weiteren Informationen}}

[[Kategorie:Code Snippets]]

Cmdalias

2015-12-30T13:26:35Z

SirUli: Formatierung und hinzufügen der renamehm funktion

{{SEITENTITEL:cmdalias}}
{{Infobox Modul
|ModPurpose=Erstellen von Benutzer-definierten Befehlen in FHEM
|ModType=cmd
|ModCmdRef=cmdalias
|ModForumArea=FHEM
|ModTechName=98_cmdalias.pm
|ModOwner={{Link2FU|8|Rudolf König}}
}}

Der Fhem-Befehl [[cmdalias]] dient zur Erstellung von benutzerdefinierten Befehlen.

= Zielsetzung =
Die jeweiligen Befehlsketten können mit ''cmdalias'' verkürzt oder sogar verändert werden.
Ein schönes Beispiel dafür ist, dass sogar [[:Kategorie:FhemBefehl|interne Befehle]] wie "shutdown restart" ersetzt werden können durch einen alias der genau so heißt aber zusätzlich vorher noch z.B. ein "save" ausführt.

= Einbindung in Fhem =
{{Randnotiz|RNTyp=y|RNText=Die folgenden Codebeispiele sind, sofern nicht anders erwähnt, als Einzeiler '''ohne''' Zeilenumbrüche einzugeben.}}
<source lang="perl">define <name> cmdalias <cmd> [parameter] AS newcommand..."</source>

'''Beispieldefinition'''
<source lang="perl">define s1 cmdalias shutdown update AS save;;shutdown</source>
<source lang="perl">define s2 cmdalias set lamp .* AS { Log 1, "$EVENT";; fhem("set $EVENT") }</source>

= Aufruf in Fhem =
[[Datei:cmdalias_eingabe_telnet.png|mini|right|400px|Ausgabe Telnet]]
Die aliase können entweder in der FHEM Befehlzeile oder direkt im Telnet eingegeben werden.

[[Datei:cmdalias_eingabe_fhemweb.png|mini|right|400px|Ausgabe in FHEMWEB]]
= Beispiele =
== ls ==
Verkürzter Aufruf von list mit Wildcard Suche
<source lang="perl">define c_ls cmdalias ls .* AS list .*$EVENT.*</source>

== showignoreddevices ==
Auflisten von Geräten, die in FHEM das Attribut "ignore" gesetzt haben:
<source lang="perl">define c_showignoreddevices cmdalias showignoreddevices AS { join("\n", grep { $attr{$_}{ignore} } sort keys %attr ) }</source>

== shownotypedevices ==
Auflisten von Geräten ohne TYPE Definition (sollte nur bei einer fehlerhaften Definition eine Ausgabe erstellen):
<source lang="perl">define c_shownotypedevices cmdalias shownotypedevices AS { join("\n", grep { !defined($defs{$_}{TYPE}) } keys %defs) }</source>

== v5 ==
Setzen des "Verbose Level" in FHEM auf 5
<source lang="perl">define c_v5 cmdalias v5 .* AS {fhem ("attr ".($EVENT||="global")." verbose 5")}</source>

== v3 ==
Setzen des "Verbose Level" in FHEM auf 3
<source lang="perl">define c_v3 cmdalias v3 .* AS {fhem ("attr ".($EVENT||="global")." verbose 3")}</source>

== Änderung von Geräte Aktionen ==
In diesem Beispiel wird dem Gerät MiLight_1 nicht erlaubt ausgeschaltet zu werden
<source lang="perl">define c_aliasMiLight_1 cmdalias set MiLight_1 off AS set HMSchaltaktor_1 off</source>

== say ==
Verkürzter Befehlsaufruf des TTS Moduls
<source lang="perl">define c_say cmdalias say .* AS set MyTTS tts '$EVENT'</source>

== roomrename ==
Umbenennen eines FHEM Raumes '''Aufruf roomrename <oldroom> <newroom>'''
<source lang="perl">define c_roomrename cmdalias roomrename .* AS { for my $name (devspec2array("room=$EVTPART0")){ map {s/$EVTPART0/$EVTPART1/;; fhem("attr $name room $_")} AttrVal($name,'room','') } }</source>

== roomdelete ==
Löschen eines FHEM Raumes '''Aufruf: roomdelete <roomName>'''
<source lang="perl">define c_roomdelete cmdalias roomdelete .* AS { for my $name (devspec2array("room=$EVENT")){ map { /^$EVENT$/ ? fhem("deleteattr $name room") : do{s/,$EVENT|$EVENT,//;; fhem("attr $name room $_")} } AttrVal($name,'room','') } }</source>

== regroup ==
Umfangreicher alias zum automatischen Setzen verschiedener Gruppen in FHEM Räumen

<source lang="perl">define c_regroup cmdalias regroup .* AS { my @EVTPART=split(' ',$EVENT);; $EVTPART[2] =~ s/\|/:FILTER=/g if($EVTPART[2]);; for my $name (devspec2array("group=".($EVTPART[0] ? $EVTPART[0] : '.*').($EVTPART[2] ? ":FILTER=$EVTPART[2]" : ''))){ map { ($_ && /^$EVTPART[0]$/ && !$EVTPART[1]) ? fhem("deleteattr $name group") : do{ if(!$EVTPART[1]){$EVTPART[0]=",$EVTPART[0]|$EVTPART[0],";; $EVTPART[1]='';;} s/$EVTPART[0]/$EVTPART[1]/;; fhem("attr $name group $_")} } AttrVal($name,'group',0) } }</source>

Die zusätzlichen Gruppen, in welchen sich die devices sonst noch befinden, bleiben unberührt. Als FILTER kann alles was der normale fhem-devspec Filter verarbeiten kann angegeben werden. Es sollte nur aufgepasst werden, wenn ein "Device" mehrere ähnliche Gruppenbennungen wie "attr name group test2,test" hat. Wenn man hier ein 'regroup test test3' macht, könnte es passieren, dass man dadurch bei diesem device die Gruppe 'test2' nach 'test32' umbenennt. In dem Beispiel müsste man den Befehl z.B. mit 'regroup test$ test3' angeben, damit das nicht passiert.

Beispiele:
<pre>regroup <oldGroup> [<newGroup> [<FILTER>][|<FILTER2>]...]

# Allen devices ohne group die Gruppe 'myGroup' setzen:
regroup 0 myGroup

# Nur den devices im Raum 'myRoom' welche keine group haben die Gruppe 'myGroup' setzen:
regroup 0 myGroup room=myRoom

# Alle devices aus 'oldGroup' in 'newGroup' verschieben
regroup oldGroup newGroup

# Nur die devices im Raum 'myRoom' aus 'oldGroup' in 'newGroup' verschieben
regroup oldGroup newGroup room=myRoom

# Gruppe 'myGroup' löschen
regroup myGroup

# Nur die devices im Raum 'myRoom' aus der Gruppe 'myGroup' löschen.
regroup myGroup 0 room=myRoom

# Devices aus allen Gruppen welche mit 'licht' beginnen aus Raum 'Obergeschoss' entfernen.
regroup licht.* 0 room=Obergeschoss

# Devices aus dem Raum 'myRoom' aus allen Gruppen entfernen und in die Gruppe 'myGroup' verschieben.
regroup .* myGroup room=myRoom

# Devices ohne Gruppe aus dem Raum 'myRoom' mit dem TYPE 'CUL_HM' und welche ebenfalls 'Licht' im Namen enthalten die Gruppe 'myGroup' hinzufügen
regroup 0 myGroup room=myRoom|TYPE=CUL_HM|NAME=.*Licht.*</pre>

== autocreate ==
Schnelles (de)aktivieren der [[autocreate]] Funktion:
<pre style="width:570px;">
define c_autocreate_off cmdalias set autocreate off AS attr autocreate disable 1
define c_autocreate_on cmdalias set autocreate on AS attr autocreate disable 0
</pre>

Optional kann noch das autocreate Icon definiert werden:
<source lang="perl">attr autocreate devStateIcon disabled:ios-off:on active:ios-on-blue:off</source>

== renamehm ==
Homematic Devices werden gerne mit zusätzlichen Geräten angelegt (z.B: HM-ES-PMSw1-PI legt die Geräte HM_12345B, HM_12345B_Pwr, HM_12345B_SenF, HM_12345B_SenI, HM_12345B_SenPwr, HM_12345B_SenU, HM_12345B_Sw an). Um diese umzubenennen kann man mit der folgenden Funktion den Prefix von HM_12345B auf einen beliebigen Ändern. Diese wird nach Definition via "<code>renamehm HM_12345B NEW_DEVICE_PREFIX</code>" ausgeführt:
<source lang="perl">define c_renamehm cmdalias renamehm .* AS { for my $name (devspec2array("$EVTPART0.*")){ my $newname=$name;;$newname =~ s/$EVTPART0/$EVTPART1/gi;; fhem("rename $name $newname");;} }</source>

= Links =
* Thread über das Modul im {{Link2Forum|Topic=15648|LinkText=Fhem Forum}}
* Thread mit {{Link2Forum|Topic=42211|LinkText=weiteren Informationen}}

[[Kategorie:Code Snippets]]

Homebridge einrichten

2015-12-28T14:43:43Z

SirUli: Überarbeitung des Wiki-Eintrags mit aktuellen Hinweisen und ein paar Neusortierungen.

Dieses HOWTO zeigt die Installation und Erstinbetriebnahme von Homebridge.

Damit kann Siri benutzt werden, um FHEM-Devices zu steuern. So können Devices angesprochen werden, die offiziell HomeKit nicht unterstützen (die Vorgehensweise wurde auf einem Intel NUC mit Ubuntu Server 14.04 LTS und auf einem Raspberry Pi mit Raspian getestet). Der WIKI-Eintrag bezieht sich hauptsächlich auf eine {{Link2Forum|Topic=32652|LinkText=Diskussion im FHEM-Forum}}. Ein Riesendank gilt vor allem {{Link2FU|430|Andre (justme1968)}}.

Eine Sammlung funktionsfähiger Homebridge FHEM Konfiguration kann hier gefunden werden: [[Hombridge User Configs]]. Die Sammlung befindet sich noch im Aufbau.

= Vorbereitung der Umgebung =

== NodeJS installieren ==
''Die nachfolgenden Befehle sind alle mit "sudo" prefixed. Wenn du unter "root" arbeitest oder deine Distribution einen anderen Mechanismus verwendet, so kannst du dies natürlich weglassen.''

Zunächst wird das Betriebssystem (in diesem Falle Debian oder Ubuntu) auf den aktuellen Stand gebracht:
<source lang="bash" style="width:50%;">
sudo apt-get update
sudo apt-get upgrade
sudo apt-get install build-essential libssl-dev</source>

Nun muss NodeJS installiert werden. Leider ist die Version im Debian Repository deutlich zu alt, daher wird mit den folgenden Befehlen das Node Repository hinzugefügt und NodeJS (in der LTS Version) entsprechend installiert:
<source lang="bash" style="width:50%;">
curl -sL https://deb.nodesource.com/setup_4.x | sudo -E bash -
sudo apt-get install -y nodejs
</source>

Damit ist NodeJS installiert.

== Python, g++, MDNS installieren ==
<source lang="bash" style="width:50%;">
sudo apt-get install python g++ libavahi-compat-libdnssd-dev
</source>

Nun sind alle Voraussetzungen geschaffen.

= Installation von Homebridge & notwendiger Shims =
Im Nachfolgenden Absatz wird die Installation von Homebridge sowie des notwendigen Plugins (Shim) für FHEM erläutert.

== Homebridge installieren ==
Die aktuelle Homebridge version wird mit
<source lang="bash" style="width:50%;">
npm install -g homebridge
</source>
installiert, was eine Weile dauert. Anschließend wird der FHEM platform shim mit:
<source lang="bash" style="width:60%;">
npm install -g homebridge-fhem
</source>
installiert.

=== Fehler während der Installation ===
Bei folgendem Fehler ist das abrufen von Github nicht möglich.
<pre>npm ERR! git clone --template=/home/hs-server-admin/.npm/_git-remotes/_templates --mirror
git://github.com/KhaosT/ed25519.git /home/hs-server-admin/.npm/_git-remotes/git-github-com-KhaosT-ed25519-git-d8bdee1d:
github.com[0: 192.30.252.128]: errno=Die Wartezeit für die Verbindung ist abgelaufen</pre>
Fehlerursache konnte hier durch eine aktive Firewall verursacht werden.

= Homebridge konfigurieren =
''Wichtig: Für die weiteren Schritte sollte man nicht root verwenden, sondern beispielsweise einen dedizieren Nutzer für homebridge oder der Einfachheit halber den Nutzer unter dem auch FHEM läuft (meist "fhem").''

== Einstellungen für homebridge ==

Zunächst wird das Verzeichnis für die Konfigurationsdatei erstellt und in dieses gewechselt:
<source lang="bash" style="width:50%;">
mkdir -p ~/.homebridge
cd ~/.homebridge/
</source>

Nun muss darin noch die config.json erstellt bzw. angepasst werden:
<source lang="bash" style="width:50%;">
nano ~/.homebridge/config.json
</source>

Hinweise zur Konfiguration:
* "''bridge''":
** "''username''": Sollte so belassen werden. Sollte später auf dem iOS Device keine Homebridge gefunden werden, so kann man hier beispielsweise den String auf 31 statt 30 enden lassen um so eine neue Homebridge vorzutäuschen.
** "''port''": Sollte so belassen werden
** "''pin''": Der PIN kann beliebig in dem Format xxx-xx-xxx angepasst werden. Dieser muss nur einmal bei der Einrichtung in iOS eingegeben werden.
* "''platforms''":
** "''platform''": Hier muss "homebridge-fhem.fhem" beibehalten werden.
** "''server''": Hier muss die IP des FHEM-Servers eingetragen werden. Dabei muss Homebridge nicht auf dem selben Server laufen wie FHEM, kann aber. Wenn es auf dem gleichen Rechner läuft, dann bietet es sich an, die IP 127.0.0.1 zu verwenden.
** "''port''": Hier muss der Port des gewählten FHEMWEBS eingetragen werden (muss nicht das "normale" sein, kann eine extra Instanz sein)
** "''auth''": Ist FHEM nicht mit Nutzername/Password abgesichert, so kann man diese Zeile einfach entfernen.
** "''filter''": Damit nicht alle Devices von Homebridge berücksichtigt werden, bietet es sich an, die Devices zu filtern. In diesem Beispiel wurden alle Devices, die über Siri steuerbar sein sollen, zusätzlich in den Raum Homekit konfiguriert.
<source lang="javascript" style="width:50%;">
{
"bridge": {
"name": "Homebridge",
"username": "CC:22:3D:E3:CE:30",
"port": 51826,
"pin": "031-45-154"
},

"platforms": [
{
"platform": "homebridge-fhem.FHEM",
"name": "FHEM",
"server": "127.0.0.1",
"port": "8083",
"auth": {"user": "FhemUser", "pass": "XXX"},
"filter": "room=Homekit"
}
],

"accessories": []
}
</source>

Wird FHEM mit SSL abgesichert, so muss zusätzlich in der Sektion "platforms" noch diese Zeile (nach "port") eingefügt werden:
<source lang="javascript" style="width:50%;">
"ssl": "true",
</source>

= FHEM konfigurieren =
Um die Devices richtig mit FHEM und Homebridge vertraut zu machen, müssen wir noch unter dem ''global''-Device das folgende userattr hinzufügen:
<source lang="perl" style="width:50%;">
genericDeviceType:ignore,switch,outlet,light,blind,speaker,thermostat,ignore,lock,window,contact
</source>

Das geht am einfachsten via Eingabefeld (nicht in der fhem.cfg):
<source lang="perl" style="width:50%;">
{ addToAttrList("genericDeviceType:ignore,switch,outlet,light,blind,speaker,thermostat,ignore,lock,window,contact") }
</source>

Zusätzlich '''kann''' man an bestimmten Devices noch einen subtype setzen (beispielsweise Thermostaten, Rolladenschaltern oder HM-Fensteröffnersensoren). Dazu erstellt man im Device (hier als Beispiel DEIN.DEVICE als Name) zunächst das userattr "subtype":
<source lang="perl" style="width:50%;">
{ addToDevAttrList("DEIN.DEVICE", "subtype:thermostat,blindActuator,threeStateSensor") }
</source>
Wenn DEIN.DEVICE nun ein HM-CC-RT-DN ist, so wählt man dann in den Attributen einfach als ''subtype'' eben ''thermostat''.

= Start von Homebridge =

== Hinweis ==
Nach allen Änderungen die in FHEM gemacht werden, welche Homebridge betreffen, muss Homebridge neu gestartet werden. Wie der Neustart erfolgen muss, ist abhängig davon, wie man Homebridge gestartet hat. Bitte den entsprechenden Methoden entnehmen.

== Einmaliger Manueller Start ==
<source lang="bash" style="width:50%;">
homebridge
</source>

Homebridge sollte nun laufen. Hier kann man die Kommunikation nachverfolgen. Abbrechen kann das ganze mit CTRL+c (es dann auch keine Befehle mehr mit Siri möglich). Damit Siri auch Befehle ohne ständig offenes Terminal bearbeiten kann, bitten nächsten Punkt beachten.

== Homebridge automatisch starten ==
Es gibt verschiedene Methoden, Homebridge automatisch zu starten.

=== Steuerung via FHEM ===
Auf Basis der unten stehenden ''Alternativen Methode'' wurde eine Version entwickelt, mit der man auch den Status einsehen und den Restart des Dienstes aus FHEM heraus erledigen kann. Diese Version ist auf der Seite [[Homebridge Start und Status in FHEM]] im Detail beschrieben.

=== Alternative Methode ===
Dies startet homebridge als einen Service.

==== Service anlegen ====
<code>
sudo nano /etc/init.d/homebridge
</code>

Code einfügen (startet den Homebridge Server als Benutzer "pi" und nimmt an, dass sich .homebridge/config.json in seinem Homeverzeichnis unter /home/pi/ befindet):

<source lang=bash>
#!/bin/sh
### BEGIN INIT INFO
# Provides: homebridge
# Required-Start: $network $remote_fs $syslog
# Required-Stop: $remote_fs $syslog
# Default-Start: 2 3 4 5
# Default-Stop: 0 1 6
# Short-Description: Start daemon at boot time for homebridge
# Description: Enable service provided by daemon.
### END INIT INFO
export PATH=$PATH:/usr/local/bin
export NODE_PATH=$NODE_PATH:/usr/local/lib/node_modules
PID=`pidof homebridge`
case "$1" in
start)
if ps -p $PID > /dev/null 2>&1; then
echo "Homebridge is already running"
else
su - pi -c "homebridge > /dev/null 2>&1 &"
echo "Homebridge starting"
$0 status
fi
;;
stop)
if ! ps -p $PID > /dev/null 2>&1; then
echo "Homebridge is not running"
else
kill $PID
echo "Homebridge closed"
fi
;;
restart)
if ! ps -p $PID > /dev/null 2>&1; then
$0 start
else
$0 stop
$0 start
fi
;;
status)
if ps -p $PID > /dev/null 2>&1; then
echo "Homebridge is running PID $PID"
else
echo "Homebridge is not running"
fi
;;
*)
echo "Usage: $0 {start|stop|status|restart}"
exit 1
;;
esac
exit 0
</source>

==== Autostart aktivieren ====

<code>
sudo chmod 755 /etc/init.d/homebridge

sudo update-rc.d homebridge defaults
</code>

Nun kann man mit

<code>
sudo service homebridge start
</code>

bzw.

<code>
sudo /etc/init.d/homebridge start
</code>

den Dienst starten

== FHEM Device Einstellungen ==
Damit die zu schaltenden Geräte überhaupt in der Homebridge aufgenommen werden muss man sie im Raum Homekit hinzufügen.

Um HM-CC-RT-DN Thermostate steuern zu können, muss wie oben beschrieben folgendes attribute gesetzt werden (hier als Beispiel das Device "Heizung"):
# attr Heizung subtype thermostat
Für einen Dummy muss man den genericDeviceType setzen, also beispielsweise:
# attr Dummy genericDeviceType switch
# attr Dummy setList on off

Wie bereits vorher angemerkt: Fügt man ein Device hinzu oder führt eine Änderung an einem Device durch, so sollte homebridge neu gestartet werden.

= HomeKit in iOS =

== Einrichtung ==
Um FHEM über Homebridge in iOS nutzen zu können, muss HomeKit eingerichtet werden.

Es gibt verschiedene Apps. Im folgenden wird die App EVE von Elgato empfohlen, die aus dem App-Store geladen werden muss.
In der App auf:
<pre style="width:50%;">
Gerät hinzufügen
</pre>
Es sollte ein Gerät mit der Bezeichnung "Homebridge" zur Auswahl erscheinen. Zur Ersteinrichtung auf PIN manuell eingeben gehen und (falls in der config.json nicht geändert):
<pre style="width:50%;">
031-45-154
</pre>
eingeben.

Im Anschluss können die Devices nach Belieben in verschiedene Räume zugeteilt werden, sowie Szenen und Bereiche erstellt werden.

== Schalten mit Siri ==
'''HolyMoly''' aus dem FHEM-Forum hat ein paar Beispiele gegeben, wie man Siri dazu bringt Devices zu schalten:
<pre style="width:50%;">
"Schalte alle Lampen im Obergeschoss ein."
"Schalte Chloes Licht aus."
"Dimme das Licht in der Küche."
"Dimme das Licht im Esszimmer auf 50 %."
"Stelle das Licht in der Küche am hellsten ein."
"Stelle die Temperatur im Tahoe-Haus auf 22 °C ein."
"Stelle das Thermostat im Erdgeschoss auf 21 °C ein.
"Schalte den Drucker im Büro ein."
"Siri, bereite alles für eine Party vor."
"Bereite das Ambiente fürs Abendessen vor."
"Aktiviere den Nachtruhemodus."
</pre>

Mittlerweile kann Siri auch noch die Lichtfarbe von LEDs ändern.

= Hinweise =

== Unterstützte Geräte ==
Das Fhem Plugin von {{Link2FU|430|Andre (justme1968)}} unterstützt folgende Geräte

switches (devices with set on and set off commands)
lights (devices with set on and set off commands)
homematc and FS20 dimmers (devices with set on, set off and set dim or set pct commands)
HUE, WifiLight, SWAP_0000002200000003 (hue, sat, bri, rgb)
homematic, max and pid20 thermostats
homematic blinds
homematic, MAX and FHTTK contact sensors (door, window)
HM-SEC-WIN, HM-SEC-KEY
presence, ROOMMATE
SONOS (power, volume)
harmony scenes
temperaturecw and humidity sensors
CO20 air quality sensor
probably some more ...

== Steuerung von MiLight Allgemein ==
Wie hier im {{Link2Forum|Topic=32652|Message=351706|LinkText=Forum}} erwähnt, ist es möglich auch MiLight Geräte per Siri anzusprechen. Hierzu muss die config.json angepasst werden.

1. Es muss die Bridge hinterlegt werden. Beispiel
<source lang="javascript" style="width:50%;">
{
"platform": "MiLight",
"name": "MiLight",
"ip_address": "192.168.001.033",
"port": 8899,
"type": "rgbw",
"delay": 30,
"repeat": 3,
"zones":["Wohnzimmer Lampen","Badezimmer Lampen","Büro Lampen","Keller Lampen"]
},
</source>

2. Es muss für jedes zu Steuernde Gerät ein Dummy angelegt werden. Beispiel:

<source lang="javascript" style="width:50%;">
{
"accessory": "Http",
"name": "Kitchen Lamp",
"on_url": "https://192.168.1.22:3030/devices/23222/on",
"off_url": "https://192.168.1.22:3030/devices/23222/off",
"brightness_url": "https://192.168.1.22:3030/devices/23222/brightness/%b",
"http_method": "POST"
},
</source>

== Hinweis für alte homebridge Versionen ==
UPDATE: Homebridge funktioniert mit einer kleinen Einschränkung nun auch mit node 4.0.0. Laut
[https://github.com/cflurin/homebridge-shims/wiki/Minimalist-Homebridge-on-a-Raspberry-Pi Homebridge on a Raspberry Pi] müssen die folgenden Abhängigkeiten (Dependencies) aus der '''package.json''' entfernt werden:
<pre>
"harmonyhubjs-client": "^1.1.4",
"harmonyhubjs-discover": "git+https://github.com/swissmanu/harmonyhubjs-discover.git"
</pre>

== Hinweis zur Geschwindigkeitsoptimierung auf einem Raspberry PI ==

Damit es auf einem Raspberry schneller läuft, wird darüber hinaus empfohlen auch diverse Abhängigkeiten aus der '''package.json''' zu entfernen:
<pre>
"ad2usb": "git+https://github.com/alistairg/node-ad2usb.git#local",
"carwingsjs": "0.0.x",
"chokidar": "^1.0.5",
"eibd": "^0.3.1",
"elkington": "kevinohara80/elkington",
"harmonyhubjs-client": "^1.1.4",
"harmonyhubjs-discover": "git+https://github.com/swissmanu/harmonyhubjs-discover.git",
"lifx-api": "^1.0.1",
"lifx": "git+https://github.com/magicmonkey/lifxjs.git",
"node-hue-api": "^1.0.5",
"node-icontrol": "^0.1.4",
"node-milight-promise": "0.0.x",
"tough-cookie": "^2.0.0",
"sonos": "0.8.x",
"telldus-live": "0.2.x",
"teslams": "1.0.1",
"unofficial-nest-api": "git+https://github.com/hachidorii/unofficial_nodejs_nest.git#d8d48edc952b049ff6320ef99afa7b2f04cdee98",
"wemo": "0.2.x",
"wink-js": "0.0.5",
"komponist" : "0.1.0",
"yamaha-nodejs": "0.4.x",
</pre>

Daher zunächst ein ein Backup der Datei anlegen
<pre>sudo cp package.json package.json.bkp </pre>
Am einfachsten geht das entfernen der Zeilen einem Editor, beispielsweise nano oder vi.
<pre>sudo nano package.json</pre>

Das config file sollte dann wie folgt aussehen: Achtung vor den letzten zwei "}" am Ende darf kein Komma sein.
<source lang="javascript">
{
"name": "homebridge",
"description": "HomeKit support for the impatient",
"version": "0.1.1",
"scripts": {
"start": "DEBUG=* node app.js || true"
},
"repository": {
"type": "git",
"url": "git://github.com/nfarina/homebridge.git"
},
"license": "ISC",
"dependencies": {
"async": "^1.4.2",
"color": "0.10.x",
"debug": "^2.2.0",
"hap-nodejs": "^0.0.2",
"isy-js": "",
"mdns": "^2.2.4",
"netatmo": "1.3.0",
"node-cache": "3.0.0",
"node-persist": "0.0.x",
"node-xmpp-client": "1.0.0-alpha23",
"q": "1.4.x",
"queue": "^3.1.0",
"request": "2.49.x",
"xml2js": "0.4.x",
"xmldoc": "0.1.x"
}
}
</source>

[[Kategorie:HOWTOS]]

Modul Alarm

2015-12-28T12:41:19Z

SirUli: Absicherung des global Attributes gegen dummies und ein paar Formatierungen.

{{
Infobox Modul
|ModPurpose=Das Modul stellt eine komfortable Oberfläche bereit, um per Webinterface Sensoren mit Aktionen zu verknüpfen - und zwar nur innerhalb bestimmter Zeitfenster sowie an- und abschaltbar
|ModType=h

|ModCmdRef=Alarm
|ModForumArea=Unterstuetzende Dienste
|ModTechName=95_Alarm.pm
|ModOwner=Prof. Dr. Peter Henning
}}
Diese Seite beschreibt die Konfiguration und Verwendung des Moduls 95_Alarm.pm.

=Allgemeines=
Das Modul ''95_Alarm.pm'' stellt eine komfortable Oberfläche bereit, um per Webinterface bestimmte auslösende Elemente (nachfolgend 'Sensoren' genannt) mit bestimmten Aktionen (nachfolgend 'Aktoren' genannt) zu verknüpfen - und zwar nur innerhalb bestimmter Zeitfenster sowie an- und abschaltbar ("scharf/armed" bzw. "unscharf/disarmed"). Diese Verknüpfungen werden als "normale" FHEM-Definitionen gespeichert.
==Erste Schritte==
Damit FHEM-Devices als Aktoren oder Sensoren für die Alarmanlage genutzt werden können, müssen zwei neue globale Attribute namens <nowiki>alarmDevice</nowiki> und <nowiki>alarmSettings</nowiki> eingeführt werden. Dazu muss in der Grundkonfiguration von FHEM die Definition der nutzerspezifischen Attribute via ''userattr'' angepasst werden. Bei Konfiguration über FHEMWEB ist es ratsam dazu die folgenden beiden Befehle zu nutzen:

{ addToAttrList("alarmDevice:Actor,Sensor") }
{ addToAttrList("alarmSettings") }

'''Alternativ:''' Möchte man dies direkt im ''global'' device ändern, so sollten die weiteren Attribute beibehalten werden, dies sieht etwa so aus:

attr global userattr '''alarmDevice:Actor,Sensor alarmSettings''' devStateIcon devStateStyle ...''(hier folgen weitere Attribute)''

Zur Erläuterung:
*Soll ein FHEM-Device als Sensor für die Alarmanlage genutzt werden, wird der Wert seines ''alarmDevice''-Attributes auf 'Sensor' gesetzt.
*Soll ein FHEM-Device als Aktor für die Alarmanlage genutzt werden, wird der Wert seines ''alarmDevice''-Attributes auf 'Actor' gesetzt
*Das Attribut ''alarmSettings'' wird beim Setzen der Alarme auf der Alarmkonfigurationsseite automatisch befüllt.
Ferner muss das Modul ''95_Alarm.pm'' im Modulpfad installiert werden, ebenso die JavaScript-Datei ''alarm.js'' in www/pgm2.
==Definition==
Die Alarmanlage - hier mit dem Namen ''AAA'' versehen - selbst wird über
define AAA Alarm
definiert. Die legt einen versteckten Raum "AlarmRoom" an, welcher über einen Weblink im oberen Menü des Webinterfaces erreichbar ist
*Es wird ein weiterer Raum benötigt, der in der gegenwärtigen Fassung des Moduls den Namen ''Alarm'' trägt. Dieser wird automatisch erstellt, sobald die Alarme wie unten konfiguriert werden.

==Konfiguration==
Beim Anklicken des Begriffes ''Alarms'' im oberen Menü des Webinterfaces wird die Alarmkonfiguration angezeigt.
===Settings===
Im oberen Bereich sind drei Eingabefelder zu sehen:
*''Wait Action'' ist ein FHEM-Befehl, der beim Scharfschalten des Alarms ausgeführt wird. Im Beispielbild wird damit ein MP3-Funkgong ausgelöst, durch den eine Stimme sagt ''Alarmanlage wird in Kürze scharf geschaltet''.
*''Arm Delay'' ist eine Verzögerungszeit, die zwischen dem Scharfschalten des Alarms und der tatsächlichen Wirksamkeit vergeht. Diese Zeit kann beispielsweise genutzt werden, um das Haus ohne Auslösung des Alarms zu verlassen.
*''Arm Action'' ist ein FHEM-Befehl, der beim Scharfschalten ausgeführt wird. Im Beispielbild wird damit ein MP3-Funkgong ausgelöst, durch den eine Stimme sagt ''Alarmanlage scharf geschaltet''.
*''Disarm Action'' ist ein FHEM-Befehl, der beim Unscharfschalten ausgeführt wird. Im Beispielbild wird damit ein MP3-Funkgong ausgelöst, durch den eine Stimme sagt ''Alarmanlage unscharf geschaltet''.
*''Cancel Action'' ist ein FHEM-Befehl, der beim Widerrufen eines Alarms ausgeführt wird. Im Beispielbild wird damit ein MP3-Funkgong ausgelöst, durch den eine Stimme sagt ''Alarm widerrufen''.

[[Datei:alarm_settings.png]]

8 Alarmlevel sind für das Modul normalerweise möglich (kann durch Setzen eines einzelnen Parameters im Modulcode verändert werden).
In der Tabelle 'Settings' können für jeden Level die Startzeit ''ts'' und Endzeit ''te'' des Alarmlevels gesetzt werden. Formate für die Zeitangabe können sein:
* hh:mm - direkte Eingabe einer festen Zeit.
* {''funktion''} - eine beliebige Perl-Funktion in geschweiften Klammern, die einen gültigen Zeitwert hh:mm zurückliefert. Die Gültigkeit wird erst zur Laufzeit überprüft. Beispielsweise "30 Minuten vor Sonnenuntergang" als {sunset_abs(-1800)}.
Diese Aktivierungszeiten wirken sich wie folgt auf den Alarmlevel aus:
*Wenn ''ts'' < ''te'', ist dieser Alarmlevel aktiv, falls ''ts'' < Zeit < ''te''.
*Wenn ''ts'' >= ''te'', ist dieser Alarmlevel aktiv, falls ''ts'' < Zeit <= 23:59 sowie wenn 0:00 < Zeit <= ''te''.
Ferner kann für jeden Alarmlevel gesetzt oder bedient werden
*Eine Nachricht zur Erläuterung des Alarms (Teil 2)
*Eine Checkbox ''Armed'' = scharf
*Ein Button ''Cancel'' zum Canceln = Aufheben des Alarms

===Sensors===
Danach wird die Tabelle der Sensoren angezeigt. Für jeden Sensor kann gesetzt werden:
*Alarmlevel, die hierdurch ausgelöst werden
*Ein regulärer Ausdruck, bei dessen Erkennung die Auslösung erfolgt
*Eine Nachricht zur Erläuterung des Alarms (Teil 1)
*Ein Selektor, um festzulegen, ob dieser Sensor den Alarm
**auslöst (=Raise),
**widerruft (=Cancel),
**scharf schaltet (=Arm) oder
**unscharf schaltet (=Disarm).
'''Achtung: Es ist zwingend notwendig, dass für einen auszulösenden Alarmlevel auch ein Sensor für den Widerruf (=Cancel) des Alarms definiert wird, ansonsten ignoriert das Modul die Definition dieses Levels.'''

Die insgesamt in den ''STATE'' der Alarmanlage geschriebene Nachricht besteht dann aus
(Anzeige der Zustände) (Nachricht Teil 1)' '(Nachricht Teil 2).
Bitte weiter unten nachlesen, was mit der [[#Anzeige der Zustände|Anzeige der Zustände]] gemeint ist.
In diesen Nachrichten werden die folgenden Ersetzungen vorgenommen
* $NAME vird durch den Namen des auslösenden Devices ersetzt
* $EVENT wird durch den kompletten Event ersetzt
* $EVTPART1... wird durch den 1. Teilstring des Events gefüllt, etc.

[[Datei:alarm_sensors.png]]

===Actors===
Anschließend wird die Tabelle der Aktoren angezeigt. Für jeden Aktor kann gesetzt werden:
*Alarmlevel, die diesen Aktor starten
*Ein FHEM-Kommando zum Starten des Aktors
*Ein FHEM-Kommando zum Stoppen des Aktors
*Eine Zeitverzögerung - entweder als Angabe von Sekunden (<60) oder im Format mm:ss

[[Datei:alarm_actors.png]]

==Einrichten==
Durch Anklicken des Buttons ''Set Alarms'' werden die ''alarmSettings''-Attribute befüllt.
'''Achtung, Folgendes beachten'''
*Es ist zwingend notwendig, dass für einen auszulösenden Alarmlevel auch ein Sensor für den Widerruf (=Cancel) des Alarms definiert wird, ansonsten ignoriert das Modul die Definition dieses Levels.
*Der Button ''Set Alarms'' wird nur funktionieren, wenn keine [[#Sperrung|Sperrung]] vorliegt, siehe unten.
*Es empfiehlt sich, danach ein ''Save Config'' auszuführen, damit die Attribute und Notifier permanent sind.

===Anzeige der Zustände===
Auf Wunsch können die Zustände der Alarmanlage zusammen mit der konkreten Meldung im internal ''STATE'' (bzw. reading ''state'', beide sind in diesem Modul identisch) angezeigt werden.
Hierfür gibt es ein Attribut ''statedisplay'' mit den folgenden möglichen Werten, die nachfolgend am Beispiel für den Zustand "Alarm Level 1 ausgelöst" erläutert sind:
* ''none'' - keine Anzeige
* ''simple'' - OXOOOOOO
* ''color'' - 0 1 2 3 4 5 6 7
* ''table'' - <table><tr style="height:1ex"><td style="width:1ex;background-color:green"/><td style="width:1ex;background-color:red"/><td style="width:1ex;background-color:green"/><td style="width:1ex;background-color:green"/><td style="width:1ex;background-color:green"/><td style="width:1ex;background-color:green"/><td style="width:1ex;background-color:green"/><td style="width:1ex;background-color:green"/></tr></table>

Das Problem ist, dass möglicherweise das internal ''STATE'' an anderer Stelle verwendet werden soll - z.B. beim Versenden von Mails als
Value('AAA')
Es macht natürlich keinen Sinn, eine HTML-Tabelle in eine Mail zu packen. Deshalb sollte für die Weiterverarbeitung statt des obigen Code verwendet werden
$defs{'AAA'}{READINGS}{"short"}{VAL}
Dies enthält nur die Meldung, nicht aber die Anzeige aller Zustände. Alternativ kann man auch die Zustandsanzeige durch Wahl des Attributwertes ''none'' komplett abstellen.
===Sperrung===
Das Attribut ''lockstate'' muss den Wert ''unlocked'' haben, damit durch Anklicken des Buttons ''Set Alarms'' die ''alarmSettings''-Attribute befüllt werden können. Das ist in der Regel beim ersten Laden des Moduls '''nicht''' der Fall, hierzu muss also das Attribut von Hand auf den richtigen Wert gesetzt werden !

=Sensoren=
==Rauchalarm==
'''Dieser Alarm ist mit Lebensgefahr verbunden und wird deshalb unabhängig von FHEM ausgelöst, und von FHEM nur registriert und mit weiteren Aktoren verbunden'''.

Im Beispiel werden vernetzte Rauchmelder des Typs [[HM-SEC-SD_Rauchmelder|HM-SEC-SD]] verwendet. Deren Teamleader erhalten das Attribut ''alarmDevice Sensor'', so dass sie in der Sensorenliste der Alarmanlage auftauchen. Sie lösen den Alarm mit dem höchsten Level aus. Die Realisierung lässt sich aber auch über beliebige andere in FHEM eingebundene Rauchmelder erreichen.

[[Datei:alarm_smoke.png]]

==Öffnung von Fenstern oder Türen ==
Dies dient der Überwachung von '''Zustandsänderungen''', ebenso wie zur '''Überprüfung eines statischen Zustands'''
===Szenarien===
====Kontrollrunde====
Dieses Alarmszenario (Alarmlevel 4) liegt vor, wenn die Hausbewohner anwesend sind, aber irgendwann zu Bett gehen wollen und vorher noch überprüfen, ob auch alle Türen und das Garagentor geschlossen sind. Sagen wir, beginnend um 22:00 bis 23:59. Man könnte diesen Alarmlevel aber auch durch einen externen Regensensor auslösen, der die Dachfenster auf ihren Öffnungszustand untersucht. Jedenfalls sollte dieser Alarmlevel immer scharf sein.

Durch einen externen Auslöser (sagen wir, beginnend um 22:00 Uhr) wird in periodischen Abständen eine Hilfsroutine gestartet, welche die Zustandsprüfung vornimmt und registriert. Nur wenn diese Registrierung eine Öffnung ergibt, wird der Alarm ausgelöst. Dieser Alarmlevel gehört also zur Kategorie ''Warnung'' und wird deshalb nur eine moderate Signalisierung benötigen - beispielsweise
*eine Nachricht mit gelbem Hintergrund erscheint auf einem [[Digitaler_Bilderrahmen_mit_lcd4linux|Digitalen Bilderrahmen]]
*eine Nachricht erscheint auf einem [[1-Wire_Textdisplay]]
*eine LED geht an auf dem [[1-Wire LED-Statusmonitor]]

====Zutritt====
Dieses Alarmszenario (Alarmlevel 5) liegt vor, wenn die Hausbewohner anwesend sind, aber vermutlich schlafen gegangen sind. Sagen wir, von 0:00 bis 5:00.

Wenn morgens um 4:00 die Haustür geöffnet wird, handelt es sich entweder um ein spätes Heimkommen eines Hausbewohners von einer Party - oder um einen Einbruchsversuch. Der Partygeher sollte also eine gewisse Warnungszeit bekommen, bevor ein moderater akustischer Aktor (sagen wir, ein Funkgong) losgeht. Dieser Aktor muss deshalb mit einer Verzögerung eingeschaltet werden, und der Partygeher erhält eine Warnung. Diese Warnung - sagen wir, eine bestimmte Lampe geht an - informiert ihn, dass er innerhalb von 30 Sekunden einen bestimmten Schalter betätigen muss. Etwa den für genau diese Lampe, um sie auszuschalten. Der Einbrecher kennt diesen Schalter nicht, der moderate Alarm wird also die schlafenden Hausbewohner wecken und ihn abschrecken.

Zusätzlich verfügt dieser Level auch noch über einen Partymodus: Mit diesem kann er für 24 Stunden abgestellt werden, so dass man auch um 3:00 in der Frühe die eigenen Partygäste aus dem Haus lassen kann, ohne ihn auszulösen.
====Einbruch====
Dieses Alarmszenario (Alarmlevel 6) liegt vor, wenn die Hausbewohner abwesend sind und diesen Level vorher scharf geschaltet haben - und idealerweise von 0:00 bis 23:59. Jeder Zutritt zu Haus löst diesen Alarm aus, und der akustische Aktor kann durchaus kräftig sein (etwa Einschalten der Rauchmelder für 1 Minute).

Da die Auslösung auch erfolgt, wenn der Hausbesitzer heimkommt, muss der akustische Aktor eine Verzögerung haben und innerhalb dieser einer Warnung gegeben werden, z.B. indem zunächst eine bestimmte Lampe angeht. Dies informiert ihn, dass er innerhalb von 30 Sekunden einen bestimmten Schalter betätigen muss. Etwa die Kombination, um diesen Alarmlevel unscharf zu schalten. Der Einbrecher kennt diese Kombination nicht, die Beleuchtung wird ihn also zunächst abschrecken und der nachfolgende laute akustische Aktor auch die Nachbarn wecken.
===Zustandsänderung===
Dazu werden alle überwachten Fenster- und Türkontakte mit dem Attribut ''alarmDevice Sensor'' versehen, so dass sie in der Sensorenliste der Alarmanlage auftauchen. In der Alarmkonfiguration sieht das dann so aus:

[[Datei:alarm_tf.png]]

===Zustandsprüfung===
Dies dient der Überprüfung eines '''statischen Zustands''', konkret ob und welche Fenster oder Türen offen sind - z.B. abends, oder bei Regenwetter. Dazu benötigen wir drei ''dummy'' Devices, von denen zwei als ''alarmDevice Sensor'' und einer als ''alarmDevice Actor'' attributiert werden und somit in der Sensoren- bzw. Aktorenliste der Alarmanlage auftauchen.

define TFOpen.warn dummy
attr TFOpen.warn alarmDevice Sensor
'''attr TFOpen.warn alarmSettings alarm4,|TFOpen.warn:.*[TF].*|$EVENT|on''' (Diese Zeile wird vom Modul 95_Alarm.pm automatisch erzeugt)
attr TFOpen.warn group windowDetector
attr TFOpen.warn room Alarm

define TFClose.warn dummy
attr TFClose.warn alarmDevice Sensor
'''attr TFClose.warn alarmSettings alarm4,|TFClose.warn:yes|Alle zu|off''' (Diese Zeile wird vom Modul 95_Alarm.pm automatisch erzeugt)
attr TFClose.warn group windowDetector
attr TFClose.warn room Alarm

define TFOpen.check dummy
attr TFOpen.check alarmDevice Actor
'''attr TFOpen.check alarmSettings alarm4,|{HouseOpen()}||10:00''' (Diese Zeile wird vom Modul 95_Alarm.pm automatisch erzeugt)
attr TFOpen.check group windowDetector
attr TFOpen.check room Alarm

[[Datei:TFAlarm.png|left|thumb|200px|]]Als nächstes muss eine Überwachungsroutine geschrieben werden. Das kann entweder als FHEM-Skript geschehen, oder in der Datei 99_myUtils.pm als perl-Code. Dieses Unterprogramm muss
*den obigen ''dummy'' TFOpen.warn setzen, und zwar auf den oder die Namen der geöffneten Fenster und Türen oder "none", wenn keine geöffnet sind.
*den obigen ''dummy'' TFClose.warn setzen, und zwar auf den Wert "no", wenn irgendeine geöffnet ist und "yes", wenn keine geöffnet sind.
Ein Beispiel für eine solche Überwachungsroutine ist weiter unten zu sehen.

Diese Doppelung ist nötig, weil jeder Sensor nur mit einem notify in den Alarmen auftauchen kann - das dient der Sicherheit gegen Fehlkonfiguration und ist beabsichtigt.

In dem nebenstehenden Flussdiagramm wird der Ablauf dargestellt, der sich mit diesem System ergibt. Dabei wird um 22:00 der erste Test auf ein ordnungsgemäß geschlossenes Haus gestartet - und bis Mitternacht alle 10 Minuten wiederholt. Alternativ könnte man das auch mit einem Regensensor als Erstauslöser koppeln.

Beispielcode für eine Überwachungsroutine:

sub HouseOpen()
{
my $kfo = 0;
my $kfs = "";
my $kto = 0;
my $kts = "";
my $str = "";
if( $main::value{'BK.F'} ne "Closed" ){
$kfo++;
$kfs = "BK/";
}
if( $main::value{'WK.F'} ne 'Closed' ){
$kfo++;
$kfs = $kfs."WK/";
}
if( $main::value{'VK.T'} ne "Closed" ){
$kto++;
$kts = "VK/";
}
if( $main::value{'WZ.T'} ne 'Closed' ){
$kto++;
$kts = $kts."WZ/";
}
if( ($kfo >= 1) && ($kto == 0) ){
$kfs = substr($kfs,0,-1);
fhem("define TFOpen.delay at +00:00:30 set TFOpen.warn $kfs Fenster");
fhem("define TFClose.delay at +00:00:30 set TFClose.warn no");
}elsif( ($kfo == 0) && ($kto >= 1) ){
$kts = substr($kts,0,-1);
fhem("define TFOpen.delay at +00:00:30 set TFOpen.warn $kts Tür");
fhem("define TFClose.delay at +00:00:30 set TFClose.warn no");
}elsif( ($kfo >= 1) && ($kto >= 1)){
$kts = substr($kts,0,-1);
$kfs = substr($kfs,0,-1);
$str = "$kts Tür + $kfs Fenster";
fhem("define TFOpen.delay at +00:00:30 set TFOpen.warn $kts T / $kfs F");
fhem("define TFClose.delay at +00:00:30 set TFClose.warn no");
}else{
fhem("set TFOpen.warn none");
fhem("set TFClose.warn yes");
}
return $str;
}

==Batterie schwach bei FHEM-Devices==
Dieser Sensor besteht aus einem ''notify'' und einem ''dummy'', der bei einer 'battery low'-Meldung eines beliebigen FHEM-Device auf dessen Namen gesetzt wird. Der ''dummy'' wird als ''alarmDevice Sensor'' attributiert, so dass er in der Sensorenliste der Alarmanlage auftaucht.

define LBatt.N notify .*:[Bb]attery.*[Ll]ow.* set LBatt.warn $NAME
attr LBatt.N room Alarm
attr LBatt.N group deviceDetector

define LBatt.warn dummy
attr LBatt.warn alarmDevice Sensor
attr LBatt.warn room Alarm
attr LBatt.warn group deviceDetector
Auf einen Test, ob gleichzeitig bei anderen FHEM-Devices die Batterie ebenfalls schwach ist, wird hier verzichtet. Für diesen Sensor wird ein eigener Alarmlevel (niedriger Priorität) erzeugt. Bei einem beliebigen 'battery low' Event wird somit der STATE der Alarmanlage gesetzt auf '''Batt. <devicename> schwach'''. Dieser Alarm muss manuell zurückgesetzt werden (schließlich sollten die Batterien ja erst gewechselt werden...)

[[Datei:alarm_lbatt.png]]

=Aktoren=
==Rauchmelder als Alarmsignal==
Für Alarme, bei denen es wirklich auf schnelle Reaktionen ankommt, kann man auch Rauchdetektoren verwenden, die über Funk aktivierbar sind. Im Beispiel werden vernetzte Rauchmelder des Typs [[HM-SEC-SD_Rauchmelder|HM-SEC-SD]] verwendet.

'''Achtung: Es ist sehr empfehlenswert, diesen Alarm auch wieder automatisch auszuschalten.'''

Dazu wird ein ''dummy'' erzeugt und mit ''alarmDevice Actor'' attributiert, so dass er in der Aktorenliste auftaucht:

define SD.alarm dummy
attr SD.alarm alarmDevice Actor
attr SD.alarm alarmSettings alarm7,|set TH.SD0 alarmOn|set TH.SD0 alarmOff|30
attr SD.alarm group alarmActor
attr SD.alarm room Alarm
In der Alarmkonfiguration sieht das dann so aus:

[[Datei:alarm_smokeactor.png]]

==Funk-Türgong / MP3-Türgong als Alarmsignal==
Hier wird ein FS20-Türgong als akustisches Alarmsignal verwendet.

define WZ.Gong FS20 <adresse>
attr WZ.Gong IODev CUL
attr WZ.Gong alarmDevice Actor
'''attr WZ.Gong alarmSettings alarm5,alarm6,|set WZ.Gong on||30''' (Vom Modul 95_Alarm.pm automatisch erzeugt)
attr WZ.Gong group alarmActor
attr WZ.Gong room Alarm,Erdgeschoss
In der Alarmkonfiguration sieht das dann so aus:

[[Datei:alarm_gongactor.png]]

Bei Verwendung eines MP3-Funkgongs (z.B. aus dem Homematic-Programm) kann man auf diesem eine ganze Menge verschiedene MP3-Dateien speichern, die z.B. Stimmenmeldungen "Alarmanlage scharf geschaltet" abgeben. Zur Erstellung dieser Meldungen hat es sich bewährt, einen kostenlosen Online-TTS (Text-to-Speech) Service zu nutzen, z.B. Ivona.
==Alarmierung per SMS==
Für Alarme, die man auch im Urlaub auf das Handy bekommen möchte, bedarf es natürlich eines Providers, der eine bestimmte Mailadresse als SMS weiterleitet. Ferner einer FHEM-Konfiguration, die Mails versenden kann. Dann wird ein ''dummy'' erzeugt und mit ''alarmDevice Actor'' attributiert, so dass er in der Aktorenliste auftaucht:
define Mail.alarm dummy
attr Mail.alarm alarmDevice Actor
'''attr Mail.alarm alarmSettings alarm6,alarm7,|{DebianMail(<mailadresse>,'Alarm',Value('AAA'))}||30''' (automatisch erzeugt)
attr Mail.alarm group alarmActor
attr Mail.alarm room Alarm
In der Alarmkonfiguration sieht das dann so aus:

[[Datei:alarm_mailactor.png]]

== Links ==
* {{Link2Forum|Topic=26893.0|LinkText=Forenthread}}

[[Kategorie:Examples]]

Modul Alarm

2015-12-28T12:17:22Z

SirUli: Infobox & Link zum Forenthread hinzugefügt

{{
Infobox Modul
|ModPurpose=Das Modul stellt eine komfortable Oberfläche bereit, um per Webinterface Sensoren mit Aktionen zu verknüpfen - und zwar nur innerhalb bestimmter Zeitfenster sowie an- und abschaltbar
|ModType=h

|ModCmdRef=Alarm
|ModForumArea=Unterstuetzende Dienste
|ModTechName=95_Alarm.pm
|ModOwner=Prof. Dr. Peter Henning
}}
Diese Seite beschreibt die Konfiguration und Verwendung des Moduls 95_Alarm.pm.

=Allgemeines=
Das Modul ''95_Alarm.pm'' stellt eine komfortable Oberfläche bereit, um per Webinterface bestimmte auslösende Elemente (nachfolgend 'Sensoren' genannt) mit bestimmten Aktionen (nachfolgend 'Aktoren' genannt) zu verknüpfen - und zwar nur innerhalb bestimmter Zeitfenster sowie an- und abschaltbar ("scharf/armed" bzw. "unscharf/disarmed"). Diese Verknüpfungen werden als "normale" FHEM-Definitionen gespeichert.
==Erste Schritte==
Damit FHEM-Devices als Aktoren oder Sensoren für die Alarmanlage genutzt werden können, müssen zwei neue globale Attribute eingeführt werden. Dazu muss in der Grundkonfiguration von FHEM die Zeile mit der Definition der nutzerspezifischen Attribute ''userattr'' angepasst werden:
attr global userattr '''alarmDevice alarmSettings''' devStateIcon devStateStyle ...''(hier folgen weitere Attribute)''
*Soll ein FHEM-Device als Sensor für die Alarmanlage genutzt werden, wird der Wert seines ''alarmDevice''-Attributes auf 'Sensor' gesetzt.
*Soll ein FHEM-Device als Aktor für die Alarmanlage genutzt werden, wird der Wert seines ''alarmDevice''-Attributes auf 'Actor' gesetzt
*Das Attribut ''alarmSettings'' wird beim Setzen der Alarme auf der Alarmkonfigurationsseite automatisch befüllt.
Ferner muss das Modul ''95_Alarm.pm'' im Modulpfad installiert werden, ebenso die JavaScript-Datei ''alarm.js'' in www/pgm2.
==Definition==
Die Alarmanlage - hier mit dem Namen ''AAA'' versehen - selbst wird über
define AAA Alarm
attr AAA room AlarmRoom
definiert. Zusätzlich soll sie im oberen Menü des Webinterfaces auftauchen, dazu benötigen wir noch (wird normalerweise automatisch mit angelegt):
define AAA_weblink weblink htmlCode {Alarm_Html("AAA")}
attr AAA_weblink room AlarmRoom
*Der Raum ''AlarmRoom'' ist ein versteckter Raum, der nicht im unteren Menü auftaucht.
*Es wird ein weiterer Raum benötigt, der in der gegenwärtigen Fassung des Moduls den Namen ''Alarm'' trägt

==Konfiguration==
Beim Anklicken des Begriffes ''Alarms'' im oberen Menü des Webinterfaces wird die Alarmkonfiguration angezeigt.
===Settings===
Im oberen Bereich sind drei Eingabefelder zu sehen:
*Wait Action ist ein FHEM-Befehl, der beim Scharfschalten des Alarms ausgeführt wird. Im Beispielbild wird damit ein MP3-Funkgong ausgelöst, durch den eine Stimme sagt ''Alarmanlage wird in Kürze scharf geschaltet''.
*Arm Delay ist eine Verzögerungszeit, die zwischen dem Scharfschalten des Alarms und der tatsächlichen Wirksamkeit vergeht. Diese Zeit kann beispielsweise genutzt werden, um das Haus ohne Auslösung des Alarms zu verlassen.
*Arm Action ist ein FHEM-Befehl, der beim Scharfschalten ausgeführt wird. Im Beispielbild wird damit ein MP3-Funkgong ausgelöst, durch den eine Stimme sagt ''Alarmanlage scharf geschaltet''.
*Disarm Action ist ein FHEM-Befehl, der beim Unscharfschalten ausgeführt wird. Im Beispielbild wird damit ein MP3-Funkgong ausgelöst, durch den eine Stimme sagt ''Alarmanlage unscharf geschaltet''.
*Cancel Action ist ein FHEM-Befehl, der beim Widerrufen eines Alarms ausgeführt wird. Im Beispielbild wird damit ein MP3-Funkgong ausgelöst, durch den eine Stimme sagt ''Alarm widerrufen''.

[[Datei:alarm_settings.png]]

8 Alarmlevel sind für das Modul normalerweise möglich (kann durch Setzen eines einzelnen Parameters im Modulcode verändert werden).
In der Tabelle 'Settings' können für jeden Level die Startzeit ''ts'' und Endzeit ''te'' des Alarmlevels gesetzt werden. Formate für die Zeitangabe können sein:
* hh:mm - direkte Eingabe einer festen Zeit.
* {''funktion''} - eine beliebige Perl-Funktion in geschweiften Klammern, die einen gültigen Zeitwert hh:mm zurückliefert. Die Gültigkeit wird erst zur Laufzeit überprüft. Beispielsweise "30 Minuten vor Sonnenuntergang" als {sunset_abs(-1800)}.
Diese Aktivierungszeiten wirken sich wie folgt auf den Alarmlevel aus:
*Wenn ''ts'' < ''te'', ist dieser Alarmlevel aktiv, falls ''ts'' < Zeit < ''te''.
*Wenn ''ts'' >= ''te'', ist dieser Alarmlevel aktiv, falls ''ts'' < Zeit <= 23:59 sowie wenn 0:00 < Zeit <= ''te''.
Ferner kann für jeden Alarmlevel gesetzt oder bedient werden
*Eine Nachricht zur Erläuterung des Alarms (Teil 2)
*Eine Checkbox ''Armed'' = scharf
*Ein Button ''Cancel'' zum Canceln = Aufheben des Alarms

===Sensors===
Danach wird die Tabelle der Sensoren angezeigt. Für jeden Sensor kann gesetzt werden:
*Alarmlevel, die hierdurch ausgelöst werden
*Ein regulärer Ausdruck, bei dessen Erkennung die Auslösung erfolgt
*Eine Nachricht zur Erläuterung des Alarms (Teil 1)
*Ein Selektor, um festzulegen, ob dieser Sensor den Alarm
**auslöst (=Raise),
**widerruft (=Cancel),
**scharf schaltet (=Arm) oder
**unscharf schaltet (=Disarm).
'''Achtung: Es ist zwingend notwendig, dass für einen auszulösenden Alarmlevel auch ein Sensor für den Widerruf (=Cancel) des Alarms definiert wird, ansonsten ignoriert das Modul die Definition dieses Levels.'''

Die insgesamt in den ''STATE'' der Alarmanlage geschriebene Nachricht besteht dann aus
(Anzeige der Zustände) (Nachricht Teil 1)' '(Nachricht Teil 2).
Bitte weiter unten nachlesen, was mit der [[#Anzeige der Zustände|Anzeige der Zustände]] gemeint ist.
In diesen Nachrichten werden die folgenden Ersetzungen vorgenommen
* $NAME vird durch den Namen des auslösenden Devices ersetzt
* $EVENT wird durch den kompletten Event ersetzt
* $EVTPART1... wird durch den 1. Teilstring des Events gefüllt, etc.

[[Datei:alarm_sensors.png]]

===Actors===
Anschließend wird die Tabelle der Aktoren angezeigt. Für jeden Aktor kann gesetzt werden:
*Alarmlevel, die diesen Aktor starten
*Ein FHEM-Kommando zum Starten des Aktors
*Ein FHEM-Kommando zum Stoppen des Aktors
*Eine Zeitverzögerung - entweder als Angabe von Sekunden (<60) oder im Format mm:ss

[[Datei:alarm_actors.png]]

==Einrichten==
Durch Anklicken des Buttons ''Set Alarms'' werden die ''alarmSettings''-Attribute befüllt.
'''Achtung, Folgendes beachten'''
*Es ist zwingend notwendig, dass für einen auszulösenden Alarmlevel auch ein Sensor für den Widerruf (=Cancel) des Alarms definiert wird, ansonsten ignoriert das Modul die Definition dieses Levels.
*Der Button ''Set Alarms'' wird nur funktionieren, wenn keine [[#Sperrung|Sperrung]] vorliegt, siehe unten.
*Es empfiehlt sich, danach ein ''Save Config'' auszuführen, damit die Attribute und Notifier permanent sind.

===Anzeige der Zustände===
Auf Wunsch können die Zustände der Alarmanlage zusammen mit der konkreten Meldung im internal ''STATE'' (bzw. reading ''state'', beide sind in diesem Modul identisch) angezeigt werden.
Hierfür gibt es ein Attribut ''statedisplay'' mit den folgenden möglichen Werten, die nachfolgend am Beispiel für den Zustand "Alarm Level 1 ausgelöst" erläutert sind:
* ''none'' - keine Anzeige
* ''simple'' - OXOOOOOO
* ''color'' - 0 1 2 3 4 5 6 7
* ''table'' - <table><tr style="height:1ex"><td style="width:1ex;background-color:green"/><td style="width:1ex;background-color:red"/><td style="width:1ex;background-color:green"/><td style="width:1ex;background-color:green"/><td style="width:1ex;background-color:green"/><td style="width:1ex;background-color:green"/><td style="width:1ex;background-color:green"/><td style="width:1ex;background-color:green"/></tr></table>

Das Problem ist, dass möglicherweise das internal ''STATE'' an anderer Stelle verwendet werden soll - z.B. beim Versenden von Mails als
Value('AAA')
Es macht natürlich keinen Sinn, eine HTML-Tabelle in eine Mail zu packen. Deshalb sollte für die Weiterverarbeitung statt des obigen Code verwendet werden
$defs{'AAA'}{READINGS}{"short"}{VAL}
Dies enthält nur die Meldung, nicht aber die Anzeige aller Zustände. Alternativ kann man auch die Zustandsanzeige durch Wahl des Attributwertes ''none'' komplett abstellen.
===Sperrung===
Das Attribut ''lockstate'' muss den Wert ''unlocked'' haben, damit durch Anklicken des Buttons ''Set Alarms'' die ''alarmSettings''-Attribute befüllt werden können. Das ist in der Regel beim ersten Laden des Moduls '''nicht''' der Fall, hierzu muss also das Attribut von Hand auf den richtigen Wert gesetzt werden !

=Sensoren=
==Rauchalarm==
'''Dieser Alarm ist mit Lebensgefahr verbunden und wird deshalb unabhängig von FHEM ausgelöst, und von FHEM nur registriert und mit weiteren Aktoren verbunden'''.

Im Beispiel werden vernetzte Rauchmelder des Typs [[HM-SEC-SD_Rauchmelder|HM-SEC-SD]] verwendet. Deren Teamleader erhalten das Attribut ''alarmDevice Sensor'', so dass sie in der Sensorenliste der Alarmanlage auftauchen. Sie lösen den Alarm mit dem höchsten Level aus. Die Realisierung lässt sich aber auch über beliebige andere in FHEM eingebundene Rauchmelder erreichen.

[[Datei:alarm_smoke.png]]

==Öffnung von Fenstern oder Türen ==
Dies dient der Überwachung von '''Zustandsänderungen''', ebenso wie zur '''Überprüfung eines statischen Zustands'''
===Szenarien===
====Kontrollrunde====
Dieses Alarmszenario (Alarmlevel 4) liegt vor, wenn die Hausbewohner anwesend sind, aber irgendwann zu Bett gehen wollen und vorher noch überprüfen, ob auch alle Türen und das Garagentor geschlossen sind. Sagen wir, beginnend um 22:00 bis 23:59. Man könnte diesen Alarmlevel aber auch durch einen externen Regensensor auslösen, der die Dachfenster auf ihren Öffnungszustand untersucht. Jedenfalls sollte dieser Alarmlevel immer scharf sein.

Durch einen externen Auslöser (sagen wir, beginnend um 22:00 Uhr) wird in periodischen Abständen eine Hilfsroutine gestartet, welche die Zustandsprüfung vornimmt und registriert. Nur wenn diese Registrierung eine Öffnung ergibt, wird der Alarm ausgelöst. Dieser Alarmlevel gehört also zur Kategorie ''Warnung'' und wird deshalb nur eine moderate Signalisierung benötigen - beispielsweise
*eine Nachricht mit gelbem Hintergrund erscheint auf einem [[Digitaler_Bilderrahmen_mit_lcd4linux|Digitalen Bilderrahmen]]
*eine Nachricht erscheint auf einem [[1-Wire_Textdisplay]]
*eine LED geht an auf dem [[1-Wire LED-Statusmonitor]]

====Zutritt====
Dieses Alarmszenario (Alarmlevel 5) liegt vor, wenn die Hausbewohner anwesend sind, aber vermutlich schlafen gegangen sind. Sagen wir, von 0:00 bis 5:00.

Wenn morgens um 4:00 die Haustür geöffnet wird, handelt es sich entweder um ein spätes Heimkommen eines Hausbewohners von einer Party - oder um einen Einbruchsversuch. Der Partygeher sollte also eine gewisse Warnungszeit bekommen, bevor ein moderater akustischer Aktor (sagen wir, ein Funkgong) losgeht. Dieser Aktor muss deshalb mit einer Verzögerung eingeschaltet werden, und der Partygeher erhält eine Warnung. Diese Warnung - sagen wir, eine bestimmte Lampe geht an - informiert ihn, dass er innerhalb von 30 Sekunden einen bestimmten Schalter betätigen muss. Etwa den für genau diese Lampe, um sie auszuschalten. Der Einbrecher kennt diesen Schalter nicht, der moderate Alarm wird also die schlafenden Hausbewohner wecken und ihn abschrecken.

Zusätzlich verfügt dieser Level auch noch über einen Partymodus: Mit diesem kann er für 24 Stunden abgestellt werden, so dass man auch um 3:00 in der Frühe die eigenen Partygäste aus dem Haus lassen kann, ohne ihn auszulösen.
====Einbruch====
Dieses Alarmszenario (Alarmlevel 6) liegt vor, wenn die Hausbewohner abwesend sind und diesen Level vorher scharf geschaltet haben - und idealerweise von 0:00 bis 23:59. Jeder Zutritt zu Haus löst diesen Alarm aus, und der akustische Aktor kann durchaus kräftig sein (etwa Einschalten der Rauchmelder für 1 Minute).

Da die Auslösung auch erfolgt, wenn der Hausbesitzer heimkommt, muss der akustische Aktor eine Verzögerung haben und innerhalb dieser einer Warnung gegeben werden, z.B. indem zunächst eine bestimmte Lampe angeht. Dies informiert ihn, dass er innerhalb von 30 Sekunden einen bestimmten Schalter betätigen muss. Etwa die Kombination, um diesen Alarmlevel unscharf zu schalten. Der Einbrecher kennt diese Kombination nicht, die Beleuchtung wird ihn also zunächst abschrecken und der nachfolgende laute akustische Aktor auch die Nachbarn wecken.
===Zustandsänderung===
Dazu werden alle überwachten Fenster- und Türkontakte mit dem Attribut ''alarmDevice Sensor'' versehen, so dass sie in der Sensorenliste der Alarmanlage auftauchen. In der Alarmkonfiguration sieht das dann so aus:

[[Datei:alarm_tf.png]]

===Zustandsprüfung===
Dies dient der Überprüfung eines '''statischen Zustands''', konkret ob und welche Fenster oder Türen offen sind - z.B. abends, oder bei Regenwetter. Dazu benötigen wir drei ''dummy'' Devices, von denen zwei als ''alarmDevice Sensor'' und einer als ''alarmDevice Actor'' attributiert werden und somit in der Sensoren- bzw. Aktorenliste der Alarmanlage auftauchen.

define TFOpen.warn dummy
attr TFOpen.warn alarmDevice Sensor
'''attr TFOpen.warn alarmSettings alarm4,|TFOpen.warn:.*[TF].*|$EVENT|on''' (Diese Zeile wird vom Modul 95_Alarm.pm automatisch erzeugt)
attr TFOpen.warn group windowDetector
attr TFOpen.warn room Alarm

define TFClose.warn dummy
attr TFClose.warn alarmDevice Sensor
'''attr TFClose.warn alarmSettings alarm4,|TFClose.warn:yes|Alle zu|off''' (Diese Zeile wird vom Modul 95_Alarm.pm automatisch erzeugt)
attr TFClose.warn group windowDetector
attr TFClose.warn room Alarm

define TFOpen.check dummy
attr TFOpen.check alarmDevice Actor
'''attr TFOpen.check alarmSettings alarm4,|{HouseOpen()}||10:00''' (Diese Zeile wird vom Modul 95_Alarm.pm automatisch erzeugt)
attr TFOpen.check group windowDetector
attr TFOpen.check room Alarm

[[Datei:TFAlarm.png|left|thumb|200px|]]Als nächstes muss eine Überwachungsroutine geschrieben werden. Das kann entweder als FHEM-Skript geschehen, oder in der Datei 99_myUtils.pm als perl-Code. Dieses Unterprogramm muss
*den obigen ''dummy'' TFOpen.warn setzen, und zwar auf den oder die Namen der geöffneten Fenster und Türen oder "none", wenn keine geöffnet sind.
*den obigen ''dummy'' TFClose.warn setzen, und zwar auf den Wert "no", wenn irgendeine geöffnet ist und "yes", wenn keine geöffnet sind.
Ein Beispiel für eine solche Überwachungsroutine ist weiter unten zu sehen.

Diese Doppelung ist nötig, weil jeder Sensor nur mit einem notify in den Alarmen auftauchen kann - das dient der Sicherheit gegen Fehlkonfiguration und ist beabsichtigt.

In dem nebenstehenden Flussdiagramm wird der Ablauf dargestellt, der sich mit diesem System ergibt. Dabei wird um 22:00 der erste Test auf ein ordnungsgemäß geschlossenes Haus gestartet - und bis Mitternacht alle 10 Minuten wiederholt. Alternativ könnte man das auch mit einem Regensensor als Erstauslöser koppeln.

Beispielcode für eine Überwachungsroutine:

sub HouseOpen()
{
my $kfo = 0;
my $kfs = "";
my $kto = 0;
my $kts = "";
my $str = "";
if( $main::value{'BK.F'} ne "Closed" ){
$kfo++;
$kfs = "BK/";
}
if( $main::value{'WK.F'} ne 'Closed' ){
$kfo++;
$kfs = $kfs."WK/";
}
if( $main::value{'VK.T'} ne "Closed" ){
$kto++;
$kts = "VK/";
}
if( $main::value{'WZ.T'} ne 'Closed' ){
$kto++;
$kts = $kts."WZ/";
}
if( ($kfo >= 1) && ($kto == 0) ){
$kfs = substr($kfs,0,-1);
fhem("define TFOpen.delay at +00:00:30 set TFOpen.warn $kfs Fenster");
fhem("define TFClose.delay at +00:00:30 set TFClose.warn no");
}elsif( ($kfo == 0) && ($kto >= 1) ){
$kts = substr($kts,0,-1);
fhem("define TFOpen.delay at +00:00:30 set TFOpen.warn $kts Tür");
fhem("define TFClose.delay at +00:00:30 set TFClose.warn no");
}elsif( ($kfo >= 1) && ($kto >= 1)){
$kts = substr($kts,0,-1);
$kfs = substr($kfs,0,-1);
$str = "$kts Tür + $kfs Fenster";
fhem("define TFOpen.delay at +00:00:30 set TFOpen.warn $kts T / $kfs F");
fhem("define TFClose.delay at +00:00:30 set TFClose.warn no");
}else{
fhem("set TFOpen.warn none");
fhem("set TFClose.warn yes");
}
return $str;
}

==Batterie schwach bei FHEM-Devices==
Dieser Sensor besteht aus einem ''notify'' und einem ''dummy'', der bei einer 'battery low'-Meldung eines beliebigen FHEM-Device auf dessen Namen gesetzt wird. Der ''dummy'' wird als ''alarmDevice Sensor'' attributiert, so dass er in der Sensorenliste der Alarmanlage auftaucht.

define LBatt.N notify .*:[Bb]attery.*[Ll]ow.* set LBatt.warn $NAME
attr LBatt.N room Alarm
attr LBatt.N group deviceDetector

define LBatt.warn dummy
attr LBatt.warn alarmDevice Sensor
attr LBatt.warn room Alarm
attr LBatt.warn group deviceDetector
Auf einen Test, ob gleichzeitig bei anderen FHEM-Devices die Batterie ebenfalls schwach ist, wird hier verzichtet. Für diesen Sensor wird ein eigener Alarmlevel (niedriger Priorität) erzeugt. Bei einem beliebigen 'battery low' Event wird somit der STATE der Alarmanlage gesetzt auf '''Batt. <devicename> schwach'''. Dieser Alarm muss manuell zurückgesetzt werden (schließlich sollten die Batterien ja erst gewechselt werden...)

[[Datei:alarm_lbatt.png]]

=Aktoren=
==Rauchmelder als Alarmsignal==
Für Alarme, bei denen es wirklich auf schnelle Reaktionen ankommt, kann man auch Rauchdetektoren verwenden, die über Funk aktivierbar sind. Im Beispiel werden vernetzte Rauchmelder des Typs [[HM-SEC-SD_Rauchmelder|HM-SEC-SD]] verwendet.

'''Achtung: Es ist sehr empfehlenswert, diesen Alarm auch wieder automatisch auszuschalten.'''

Dazu wird ein ''dummy'' erzeugt und mit ''alarmDevice Actor'' attributiert, so dass er in der Aktorenliste auftaucht:

define SD.alarm dummy
attr SD.alarm alarmDevice Actor
attr SD.alarm alarmSettings alarm7,|set TH.SD0 alarmOn|set TH.SD0 alarmOff|30
attr SD.alarm group alarmActor
attr SD.alarm room Alarm
In der Alarmkonfiguration sieht das dann so aus:

[[Datei:alarm_smokeactor.png]]

==Funk-Türgong / MP3-Türgong als Alarmsignal==
Hier wird ein FS20-Türgong als akustisches Alarmsignal verwendet.

define WZ.Gong FS20 <adresse>
attr WZ.Gong IODev CUL
attr WZ.Gong alarmDevice Actor
'''attr WZ.Gong alarmSettings alarm5,alarm6,|set WZ.Gong on||30''' (Vom Modul 95_Alarm.pm automatisch erzeugt)
attr WZ.Gong group alarmActor
attr WZ.Gong room Alarm,Erdgeschoss
In der Alarmkonfiguration sieht das dann so aus:

[[Datei:alarm_gongactor.png]]

Bei Verwendung eines MP3-Funkgongs (z.B. aus dem Homematic-Programm) kann man auf diesem eine ganze Menge verschiedene MP3-Dateien speichern, die z.B. Stimmenmeldungen "Alarmanlage scharf geschaltet" abgeben. Zur Erstellung dieser Meldungen hat es sich bewährt, einen kostenlosen Online-TTS (Text-to-Speech) Service zu nutzen, z.B. Ivona.
==Alarmierung per SMS==
Für Alarme, die man auch im Urlaub auf das Handy bekommen möchte, bedarf es natürlich eines Providers, der eine bestimmte Mailadresse als SMS weiterleitet. Ferner einer FHEM-Konfiguration, die Mails versenden kann. Dann wird ein ''dummy'' erzeugt und mit ''alarmDevice Actor'' attributiert, so dass er in der Aktorenliste auftaucht:
define Mail.alarm dummy
attr Mail.alarm alarmDevice Actor
'''attr Mail.alarm alarmSettings alarm6,alarm7,|{DebianMail(<mailadresse>,'Alarm',Value('AAA'))}||30''' (automatisch erzeugt)
attr Mail.alarm group alarmActor
attr Mail.alarm room Alarm
In der Alarmkonfiguration sieht das dann so aus:

[[Datei:alarm_mailactor.png]]

== Links ==
* {{Link2Forum|Topic=26893.0|LinkText=Forenthread}}

[[Kategorie:Examples]]

OPENWEATHER

2015-12-28T12:08:42Z

SirUli:

{{
Infobox Modul
|ModPurpose=Das Modul extrahiert Wetterdaten über die "openweather"-Schnittstelle (API) von www.wetter.com.
|ModType=d

|ModCmdRef=OPENWEATHER
|ModForumArea=Unterstuetzende Dienste
|ModTechName=59_OPENWEATHER.pm
|ModOwner=tupol
}}
Das Modul extrahiert Wetterdaten über die "openweather"-Schnittstelle (API) von www.wetter.com.

== API-Key erhalten ==

Zuerst ist eine Registrierung für wetter.com unter folgender URL notwendig: http://at.wetter.com/mein_wetter/register/

Nach Bestätigung des Accounts mittels der zugesandten E-Mail ist der Login möglich. Sobald man an der Seite angemeldet ist, kann man über die Navigation ''Apps & Mehr'' - ''Für Ihre Website'' die API auswählen (http://at.wetter.com/apps_und_mehr/website/api/). Dort klickt man auf ''Projektverwaltung''.

[[File:ow01.png|thumb|center|200px]]

In der Projektverwaltung wählt man ''Neues Projekt'' und vergibt dann einen Namen, eine Beschreibung und eine Kategorie des Projekts sowie eine Webseite mit weiteren Informationen zum Projekt.
Die AGBs müssen natürlich noch gelesen und abgenickt werden, danach kann man mit einem Klick auf ''Projekt anlegen'' den Vorgang abschließen.

[[File:ow02.png|center|thumb|200px]]

Anschließend erhält man den gewünschten API-Key, der auch jederzeit in der Projektverwaltung nachgesehen werden kann.

[[File:ow03.png|center|thumb|200px]]

In der Projektverwaltung können dann noch Such- und Vorhersageeinstellungen konfiguriert werden, je nachdem, welche Werte man bei einer Abfrage an das API zurückbekommen möche. '''Wichtig''': Wählt man hier nur einen Tag für die Vorhersage aus (Standard-Einstellung), so gibt es keine Vorhersage für die nachfolgenden Tage!

[[File:ow04.png|center|thumb|200px]]
[[File:ow05.png|center|thumb|200px]]

== Definition in fhem ==

Ein OpenWeather-Device kann in fhem wie folgt angelegt werden:

define <name> OPENWEATHER <project> <cityCode> <apiKey> [language]

Wobei
*'''name''' angibt, unter welchem Namen das Device in fhem angezeigt werden soll
*'''project''' der Projektname ist, den man beim Anlegen des Projektes auf wetter.com vergeben hat
*'''cityCode''' der Code ist, der auch in der URL auf wetter.com ersichtlich ist, wenn man einen Ort auswählt (z.B. Wien: http://at.wetter.com/wetter_aktuell/aktuelles_wetter/oesterreich/wien/ATAT10678.html -> '''ATAT10678''')
*'''apiKey''' der Key ist, den man beim Anlegen des Projektes auf wetter.com erhalten hat
*'''language''' eine optionale Sprachangabe ist (de ... deutsch, en ... englisch, usw.)

Vollständige Beispiel wäre also:
define meinWetter OPENWEATHER meinProjekt ATAT10678 0fb12e... de

== Konfiguration in fhem ==

Nach der Definition des Devices können noch zwei Attribute gesetzt werden:
*'''disable''' (0 oder 1): Der Wert ''1'' stoppt die automatische Aktualisierung der Wettervorhersage. Standard-Wert: ''0''.
*'''INTERVAL''' (0 oder >=3600): Das Zeitintervall in Sekunden, in dem die Wettervorhersage aktualisiert wird. Standard-Wert: ''3600''. ''0'' stoppt die automatische Aktualisierung.

Um die Aktualisierung auf sechs Stunden zu setzen verwendet man also
attr meinWetter INTERVAL 21600

== Hinweis ==
Das OpenWeather-Modul verwendet die Perl-Module [http://search.cpan.org/~ether/HTTP-Message-6.11/lib/HTTP/Request.pm HTTP::Request], [http://search.cpan.org/~ether/libwww-perl-6.13/lib/LWP/UserAgent.pm LWP::UserAgent], [http://search.cpan.org/~cjm/HTML-Tree-5.03/lib/HTML/Parse.pm HTML::Parse] und [http://search.cpan.org/~gaas/Digest-MD5-2.54/MD5.pm Digest::MD5]
Sind sie nicht vorhanden, können sie aus der Shell mittels
cpan Modulname
installiert werden.

== OpenWeather-API Rückgabewerte ==
=== Ortsdaten ===
{| class="wikitable"
!Wertname
!Beschreibung
|-
|'''name'''
|Name des Ortes
|-
|'''post_code'''
|PLZ des Ortes/der Wetterstation
|-
|'''url'''
|Link auf die jeweilige Ortsseite auf wetter.com
|-
|style="vertical-align: top;"|'''Credit'''
|Um die kostenlose wetter.com openweather API benutzen zu dürfen, müssen zwei von den drei
Hinweisen auf wetter.com angezeigt werden.
{|
!Wertname
!Beschreibung
|-
|'''text'''
|Powered by wetter.com
|-
|'''link'''
|Link auf wetter.com
|-
|'''logo'''
|Ein wetter.com Logo (Downloadlink zu offiziellen wetter.com Logos)
|}
|}

=== Wetterdaten ===
Es gibt (derzeit) für jeden Tag vier verschiedene Tagesabschnitte:
*06:00 bis 11:00
*11:00 bis 17:00
*17:00 bis 23:00
*23:00 bis 06:00
Für jeden dieser Abschnitte werden (abhängig von der getroffenen Auswahl in den Projekteinstellungen) folgende Werte zurückgeliefert:
{| class="wikitable"
!Wertname
!Beschreibung
|-
|'''du'''
|Unixtimestamp Unicode [int unsigned]
|-
|'''d'''
|Unixtimestamp lokal [int unsigned]
|-
|'''dhu'''
|ISO 8601 formatiertes Datum und Zeit, UTC [string]
|-
|'''dhl'''
|ISO 8601 formatiertes Datum und Zeit, lokal [string]
|-
|'''p'''
|Gültigkeitszeitraum der Prognose (24 Stunden, 1 Stunde, 3 Stunden, …) [int
unsigned, 0-24]
|-
|'''w'''
|Code für Wetterzustand [int unsigned, 0-999] (siehe [[#Definition Wetterzustände]])
|-
|'''pc'''
|Änderung des Luftdrucks [float 1 Nachkommastelle]
|-
|'''wd'''
|Windrichtung in Grad [int, 0=N, 90=O, 180=S, 270=W]
|-
|'''ws'''
|Windgeschwindigkeit in Kilometer/Stunde [float unsigned, 1 Nachkommastelle]
|-
|'''wd_txt'''
|Windrichtung in Textform (N,NO,S,SW …) [string]
|-
|'''w_txt'''
|Wetterzustand in Textform [string]
|-
|'''tn'''
|Mindesttemperatur
|-
|'''tx'''
|Maximaltemperatur
|}

=== Definition Wetterzustände ===
Die Codes von 0-9 sind die Hauptwetterzustände. Alle anderen Codes sind Varianten dieser Zustände.
Zum Beispiel ist ''65: starker Regen'' eine Variante von ''6: Regen''. Sollen nur die Hauptzustände angezeigt
werden kann einfach die erste Stelle des Codes verwendet werden.

{| class="wikitable"
!Code (w)
!Wetterzustand (w_txt)
|-
|0||sonnig
|-
|1||leicht bewölkt
|-
|2||wolkig
|-
|3||bedeckt
|-
|4||Nebel
|-
|5||Sprühregen
|-
|6||Regen
|-
|7||Schnee
|-
|8||Schauer
|-
|9||Gewitter
|-
|10||leicht bewölkt
|-
|20||wolkig
|-
|30||bedeckt
|-
|40||Nebel
|-
|45||Nebel
|-
|48||Nebel mit Reifbildung
|-
|49||Nebel mit Reifbildung
|-
|50||Sprühregen
|-
|51||leichter Sprühregen
|-
|53||Sprühregen
|-
|55||starker Sprühregen
|-
|56||leichter Sprühregen, gefrierend
|-
|57||starker Sprühregen, gefrierend
|-
|60||leichter Regen
|-
|61||leichter Regen
|-
|63||mäßiger Regen
|-
|65||starker Regen
|-
|66||leichter Regen, gefrierend
|-
|67||mäßiger od. starker Regen, gefrierend
|-
|68||leichter Schnee-Regen
|-
|69||starker Schnee-Regen
|-
|70||leichter Schneefall
|-
|71||leichter Schneefall
|-
|73||mäßiger Schneefall
|-
|75||starker Schneefall
|-
|80||leichter Regen - Schauer
|-
|81||Regen - Schauer
|-
|82||starker Regen - Schauer
|-
|83||leichter Schnee / Regen - Schauer
|-
|84||starker Schnee / Regen - Schauer
|-
|85||leichter Schnee - Schauer
|-
|86||mäßiger od. starker Schnee - Schauer
|-
|90||Gewitter
|-
|95||leichtes Gewitter
|-
|96||starkes Gewitter
|-
|999||Keine Angabe
|}

== Readings des OpenWeather-Moduls in fhem ==
Im folgenden werden die unterschiedlichen Readings erklärt, die das Modul liefert.

Dabei bedeutet fc'''X''' ein Platzhalter für
*fc'''0'''... heute
*fc'''1'''... morgen
*fc'''2'''... übermorgen

Die Zahlen (06,11,17,23) hinter diversen Readings bedeuten den jeweiligen Tagesabschnitt wie in den OpenWeather-Rückgabewerten beschrieben.

{| class="wikitable"
!Reading
!Beispielausgabe
!Beschreibung
!OpenWeather-Wert
|-
|city
|Wien
|Ort
|name
|-
|fcX_chOfRain
|20
|Regenwahrscheinlichkeit
|pc
|-
|fcX_tempMax
|4
|Höchsttemperatur
|tx
|-
|fcX_tempMin
|1
|Mindesttemperatur
|tn
|-
|fcX_valHours
|24
|Gültigkeitszeitraum der Prognose in Stunden
|p
|-
|fcX_wday
|Di
|Abkürzung des Wochentages
|d
|-
|fcX_weather
|leicht bewölkt
|Wetterzustand als Text
|w_txt
|-
|fcX_weatherCode
|1
|Code für den Wetterzustand
|w
|-
|fcX_wind
|6
|Windgeschwindigkeit in km/h
|ws
|-
|fcX_windDir
|135
|Windrichtung in Grad
|wd
|-
|fcX_windDirTxt
|SO
|Windrichtung als Text
|wd_txt
|}

== Weiterführende Informationen ==
*[http://at.wetter.com/apps_und_mehr/website/api/dokumentation/ API-Dokumentation auf wetter.com]
*[http://fhem.de/commandref_DE.html#OPENWEATHER fhem CommandRef]

DevelopmentModuleIntro

2015-08-20T14:13:27Z

SirUli: /* X_Notify */ Completed example and changed a few lines as new functions are available.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

=== X_Initialize ===

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

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

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

<pre>
$hash->{DefFn} = "X_Define";
$hash->{UndefFn} = "X_Undef";
$hash->{SetFn} = "X_Set";
$hash->{GetFn} = "X_Get";
$hash->{AttrFn} = "X_Attr";
</pre>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

=== X_Undef ===

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

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

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

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

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

Beispiel:

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

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

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

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

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

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

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

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

Die möglichen Zusatzinformationen sind:

'''noArg'''

es werden keine weiteren Argumente mehr benötigt
<pre>on:noArg</pre>

'''slider'''

es wird ein Schieberegler für den Wert angezeigt. Dabei Minimum, Schrittweite und Maximum angeben
<pre>dim:slider,0,1,100</pre>

'''RGB'''

es wird ein Colorpicker angezeigt, der dem Anwender die Auswahl einer Farbe ermöglicht. Bitte dazu auch den Wiki Artikel zum Colorpicker lesen, da im Modul noch weiterer Code eingefügt werden muss.
<pre>rgb:colorpicker,RGB</pre>

'''Liste'''

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>

'''Leer'''

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

'''Hinweise'''

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

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

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

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

Beispiel:

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

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

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

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

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

in der Attr-Funktion wenn ein Attribut gesetzt wird.

=== X_Read ===

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

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

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

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

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

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

=== X_Ready ===

muss noch beschrieben werden.

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

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

=== X_Notify ===

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

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

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

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

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

my $max = int(@{$dev_hash->{CHANGED}}); # number of events / changes

for (my $i = 0; $i < $max; $i++) {
my $s = $dev->{CHANGED}[$i];
next if(!defined($s));

# Insert further code here

}
}
</pre>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

== "Hello World" Beispiel ==

98_Hello.pm

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

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

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

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

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

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

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

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

return undef;
}

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

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

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

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

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

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

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

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

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

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

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

1;

=pod
=begin html

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

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

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

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

=end html

=cut
</pre>

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

[[Kategorie:Development]]

Yowsup

2015-06-30T14:01:02Z

SirUli: Änderungen von http://forum.fhem.de/index.php/topic,27543.msg307101/topicseen.html#msg307101

{{SEITENTITEL:yowsup}}
{{Infobox Modul
|ModPurpose=Schnittstelle, um WhatsApp-Nachrichten empfangen und senden zu können.
|ModType=d
|ModCmdRef=yowsup
|ModFTopic=27543
|ModForumArea=Unterstuetzende Dienste
|ModTechName=32_yowsup.pm
|ModOwner=André / justme1968 ({{Link2FU|430|Forum}} / [[Benutzer Diskussion:justme|Wiki]])
}}

Das Modul [[yowsup]] dient dazu, WhatsApp-Nachrichten zu empfangen und zu senden.

== Voraussetzungen ==
* Die Funktionalität ist vermutlich auf Linux/Unix Systeme beschränkt.
* Nach der Erstinstallation/-einrichtung '''muss''' zwingend das ''cmd'' Attribut korrekt gesetzt werden.

== Installation ==
Die ursprüngliche Einrichtung wurde hier {{Link2Forum|Topic=27543|Message=204426|LinkText=hier beschrieben}}, jedoch sind noch einige wichtige Dinge zu setzen.

=== Yowsup Installation ===
Bevor man loslegt sollte man wie immer sicherstellen, dass Debian auf dem aktuellen Stand ist:
<code>sudo apt-get update
sudo apt-get upgrade
sudo apt-get dist-upgrade</code>

Los gehts mit den Paketen:
<code>sudo apt-get install python-soappy python-dateutil python-pip python-dev build-essential</code>

Nun erstmal pip updaten:
<code>sudo pip install --upgrade pip</code>

Und dann axolotl installieren (das dauert ne Weile):
<code>sudo pip install python-axolotl</code>

Will man Bilder verarbeiten, so braucht man noch ein paar Pakete mehr:
* Paketinstallationen:
** Unter Debian Wheezy: <code>sudo apt-get install libtiff4-dev libjpeg8-dev zlib1g-dev libfreetype6-dev liblcms2-dev libwebp-dev tcl8.5-dev tk8.5-dev python-tk</code>
** Unter Debian Jessie: <code>sudo apt-get install libtiff5-dev libjpeg-dev zlib1g-dev libfreetype6-dev liblcms2-dev libwebp-dev tcl8.5-dev tk8.5-dev python-tk</code>
* PIP:<code>sudo pip install pillow</code>

Nun loggt man sich unter dem User ein, unter dem fhem läuft (in den folgenden Beispielen als "fhem" benannt, sein home ist /home/fhem und seine gruppe nenne ich "dialout") und lässt dort die $HOME-Variable heraus:
<pre>sudo su - fhem
echo $HOME
cd $HOME
logout</pre>
Diesen Wert braucht man später - gut merken. Sollte hier ein Fehler auftreten (z.B. das home nicht vorhanden), so muss dies zuerst korrigiert werden.

Desweiteren muss man nun yowsup installieren, was wie folgt vonstatten geht:
<pre>cd /opt
mkdir yowsup-config
sudo wget https://github.com/tgalal/yowsup/archive/master.zip
sudo unzip master.zip
rm master.zip
cd yowsup-config
sudo nano yowsup.config</pre>

Wie bemerkt, ist man nun im Editor für die yowsup.config gelandet. Diese wird nun wie folgt gefüllt:
<pre>## Actual config starts below ##

#cc ist wichtig ansonsten funktioniert es nicht aus dem Script
cc=49
phone=498912345678
id=0000000000
password=</pre>
Ersetze die Nummer 498912345678 gegen eine Festnetz oder Handynummer welche derzeit nicht mit WhatsApp verwendet wird. Mittels STRG+o wird die Datei nun gespeichert und mittels STRG+x verlässt man den Editor.

Vor den weiteren Schritten sollte man nun erstmal die yowsup Verzeichnisse dem fhem-user zugängig machen:
<pre>sudo chown -R fhem:dialout /opt/yowsup-master /opt/yowsup-config</pre>

Für die folgenden Schritte würde ich auf den FHEM-Nutzer wechseln:
<pre>sudo su - fhem
cd /opt/yowsup-master</pre>

Nun erfolgt die anmeldung am WhatsApp-Server. Dies kann man nun via <code>voice</code> oder <code>sms</code> machen. Bei einem Handy bietet sich SMS an, ansonsten bei Festnetznummern unbedingt etwas zum schreiben bereit halten
<pre>python yowsup-cli registration -c /opt/yowsup-config/yowsup.config -r sms</pre>

Die Rückmeldung ist nun entscheidend. Wenn man diese zurückbekommt:
<pre>de sms
status: fail
retry_after: 3600
reason: no_routes</pre>
Dann ist die Nummer so nicht kompatibel. Was man dann noch probieren kann, ist die registration via voice - meistens ist das aber vergebene Liebesmüh'.

Wenn man folgende Rückmeldung bekommt:
<pre>Detected cc: 49
status: sent
retry_after: 1805
length: 6
method: sms</pre>

So ist alles gut gelaufen und man sollte kurz später eine SMS bekommen. Darin ist ein Text, der am Ende z.B. 123-456 lautet. Diesen fügt man ohne Bindestrich am Ende des folgenden Befehls ein:
<pre>python yowsup-cli registration -c /opt/yowsup-config/yowsup.config -R 123456</pre>

Dann kommt ein Text der etwa so aussehen sollte:
<pre>status: ok
kind: free
pw: bfGA9wPWWNeHcSBxxxxxxxxxxxxxxxxx
price: 0,89 €
price_expiration: 1432127524
currency: EUR
cost: 0.89
login: 498912345678
type: existing
expiration: 1460832553</pre>
Den Text hinter dem Zeilenanfang <code>pw: </code> benötigt man nun für die Konfigurationsdatei, wo dieser eingefügt werden muss:
<pre>nano /opt/yowsup-config/yowsup.config</pre>
Sodass die Datei beispielhaft dann so aussieht:
<pre>## Actual config starts below ##

#cc ist wichtig ansonsten funktioniert es nicht aus dem Script
cc=49
phone=498912345678
id=0000000000
password=bfGA9wPWWNeHcSBxxxxxxxxxxxxxxxxx</pre>

Wie man schon gesehen hat, ist der Account nur begrenzt gültig - die Gültigkeit kann man anhand der als <code>expiration: </code> bezeichneten Zeile ablesen, welche einen Unix-Timestamp beinhaltet. Diese kann man hier umrechnen lassen.

Nun mal ein schneller test an die eigene Nummer (im Beispiel 491751234567):
<pre>python yowsup-cli demos -c /opt/yowsup-config/yowsup.config -s 491751234567 "Das ist ein Test"</pre>

Das sollte dir eine Nachricht einbringen. Wenn du darauf antwortest, kommt diese allerdings noch nicht an - der Client hat sich nach dem Befehl sofort beendet. Damit dieser dauerhaft im Hintergrund läuft legen wir nun in FHEM ein Gerät an, welches dies steuert.

=== FHEM Define ===
* Fhem Device anlegen: <code> define <name> yowsup</code>, also z.B. <code>define WhatsApp yowsup</code>
* Nun muss man den Pfad zu yowsup anpassen: <code>attr WhatsApp cmd /opt/yowsup-master/yowsup-cli demos -c /opt/yowsup-config/yowsup.config --yowsup</code>
* Und das Home directory mit dem Pfad zum Home des fhem users: <code>attr WhatsApp home PWD</code>
* Wenn alles gut geht, gibt es danach im Device ein internal PID und das Reading ''state''
* Im Whatsapp Client auf dem Handy sollte man sehen, dass Fhem online ist
* Zum Senden aus Fhem kann man das Kommando <code>set WhatsApp send <nummer> <text></code> verwenden

== Attribute ==
Bitte sehe immer in der [[http://fhem.de/commandref.html#yowsup Commandref]] nach - diese hier könnten veraltet sein.

* <code>cmd</code> komplettes Kommando, um den yowsup Client zu starten. z.B.: <code>attr WhatsApp cmd /opt/local/bin/yowsup-cli demos -c /root/config.yowsup --yowsup</code>
* <code>accept_from</code> kommagetrennte Liste von Kontakten (Nummern), von denen Nachrichten akzeptiert werden. Ist das Attribut nicht gesetzt, so werden die Nachrichten von jedem akzeptiert.
* <code>commandPrefix</code> nicht gesetzt -> es werden keine Befehle akzeptiert. 0 -> es werden keine Befehle akzeptiert. 1 -> erlaubt Befehle, jede Nachricht wird als Fhem-Befehl interpretiert. alles andere -> Wenn die Nachricht mit diesem Prefix startet, wird alles weitere als Befehle interpretiert.
{{Randnotiz|RNTyp=Warn|RNText='''allowedCommands''' should work as intended, but no guarantee can be given, that there is no way to circumvent it.}}
* <code>allowedCommands</code> Eine Komma-getrennte Liste von zulässigen Befehlen für diesen Kontakt. Wenn die Liste leer ist (z.B. nur ein Komma), dann werden keine Befehle akzeptiert.
* <code>home</code> Setzt das Home-directory welches für yowsup verwendet werden soll.

== Befehle ==
* image -> Über diesen Befehl können Bilder gesendet werden.

== Anwendungsbeispiele ==
=== Beispielnachricht ===
Beim Empfang einer Nachricht wird automatisch ein Fhem Device für diesen Kontakt angelegt. In diesem Device gibt es das Reading '''message''' für die empfangene Nachricht und ab der ersten Nachricht auch das Reading '''chatstate''', in dem zu sehen ist, ob gerade getippt wird.
Nachdem ein Device für einen Kontakt angelegt ist, lässt sich auch direkt dieses Device zum Senden verwenden:
:<code>set <device> send <text></code>,
d.h., man spart sich die Angabe der Nummer.

=== Gruppen ===
Gruppennachrichten werden von yowsup mit Sonderzeichen im Absender empfangen:
: 49yyyyyyyyyyyy/49xxxxxxxxxxx-1234567890
: absender/gründer-timestamp
Aufgrund der Sonderzeichen schlägt das automatische Anlegen einer yowsup Instanz fehl. Es kann aber zum Versenden direkt die JID der Gruppe genutzt werden, oder manuell die yowsup Instanz ohne Sonderzeichen gemacht werden.
: erst kommt die Nummer des Gruppenerstellers, dann die Uhrzeit im Unix Zeitformat.
: 49xxxxxxxxxxx-1234567890
: gründer-timestamp
:<code>define whatsapp.gruppe yowsup 49xxxxxxxxxxx-1234567890</code>
==== JID der Gruppe ermitteln ====
Am einfachsten ist es, eine Nachricht an die Gruppe zu senden und aus der Fehlermeldung von Fhem die JID herauszusuchen.
Etwas gezielter geht es mit der Auflistungsfunktion von yowsup direkt.
:<code>set WhatsApp raw /groups list</code>

Um die Ergebnisse eines raw Befehls im Log zu sehen, muss noch [[verbose]] 4 gesetzt werden:
:<code>attr WhatsApp verbose 4</code>
Dieses Attribut sollte, wenn nicht mehr benötigt, wieder gelöscht werden, um unnötige Logeinträge zu vermeiden.

== Links ==
* {{Link2Forum|Topic=27543|LinkText=Forenthread}}, in dem die Whatsapp Anwendung beschrieben wird
* {{Link2Forum|Topic=27543|Message=299292|LinkText=Foreneintrag}}, ab dem das yowsup Modul beschrieben wird
* Die Python Whatsapp Library auf [https://github.com/tgalal/yowsup github]

Yowsup

2015-06-21T13:28:21Z

SirUli: Link to commandref

{{SEITENTITEL:yowsup}}
{{Infobox Modul
|ModPurpose=Schnittstelle, um WhatsApp-Nachrichten empfangen und senden zu können.
|ModType=d
|ModCmdRef=yowsup
|ModFTopic=27543
|ModForumArea=Unterstuetzende Dienste
|ModTechName=32_yowsup.pm
|ModOwner=André / justme1968 ({{Link2FU|430|Forum}} / [[Benutzer Diskussion:justme|Wiki]])
}}

Das Modul [[yowsup]] dient dazu, WhatsApp-Nachrichten zu empfangen und zu senden.

== Voraussetzungen ==
* Die Funktionalität ist vermutlich auf Linux/Unix Systeme beschränkt.
* Nach der Erstinstallation/-einrichtung '''muss''' zwingend das ''cmd'' Attribut korrekt gesetzt werden.

== Installation ==
Die ursprüngliche Einrichtung wurde hier {{Link2Forum|Topic=27543|Message=204426|LinkText=hier beschrieben}}, jedoch sind noch einige wichtige Dinge zu setzen.

=== Yowsup Installation ===
Los gehts mit den Paketen:
<code>sudo apt-get install python-soappy python-dateutil python-pip python-dev build-essential</code>

Nun erstmal pip updaten:
<code>sudo pip install --upgrade pip</code>

Und dann axolotl installieren (das dauert ne Weile):
<code>sudo pip install python-axolotl</code>

Will man Bilder verarbeiten, so braucht man noch ein paar Pakete mehr:
* Paketinstallationen:
** Unter Debian Wheezy: <code>sudo apt-get install libtiff4-dev libjpeg8-dev zlib1g-dev libfreetype6-dev liblcms2-dev libwebp-dev tcl8.5-dev tk8.5-dev python-tkv</code>
** Unter Debian Jessie: <code>sudo apt-get install libtiff5-dev libjpeg-dev zlib1g-dev libfreetype6-dev liblcms2-dev libwebp-dev tcl8.5-dev tk8.5-dev python-tk</code>
* PIP:<code>sudo pip install -l pillow</code>

Nun loggt man sich unter dem User ein, unter dem fhem läuft (in den folgenden Beispielen als "fhem" benannt, sein home ist /home/fhem und seine gruppe nenne ich "dialout") und lässt dort die $HOME-Variable heraus:
<pre>sudo su - fhem
echo $HOME
cd $HOME
logout</pre>
Diesen Wert braucht man später - gut merken. Sollte hier ein Fehler auftreten (z.B. das home nicht vorhanden), so muss dies zuerst korrigiert werden.

Desweiteren muss man nun yowsup installieren, was wie folgt vonstatten geht:
<pre>cd /opt
mkdir yowsup-config
sudo wget https://github.com/tgalal/yowsup/archive/master.zip
sudo unzip master.zip
rm master.zip
cd yowsup-config
sudo nano yowsup.config</pre>

Wie bemerkt, ist man nun im Editor für die yowsup.config gelandet. Diese wird nun wie folgt gefüllt:
<pre>## Actual config starts below ##

#cc ist wichtig ansonsten funktioniert es nicht aus dem Script
cc=49
phone=498912345678
id=0000000000
password=</pre>
Ersetze die Nummer 498912345678 gegen eine Festnetz oder Handynummer welche derzeit nicht mit WhatsApp verwendet wird. Mittels STRG+o wird die Datei nun gespeichert und mittels STRG+x verlässt man den Editor.

Vor den weiteren Schritten sollte man nun erstmal die yowsup Verzeichnisse dem fhem-user zugängig machen:
<pre>sudo chown -R fhem:dialout /opt/yowsup-master /opt/yowsup-config</pre>

Für die folgenden Schritte würde ich auf den FHEM-Nutzer wechseln:
<pre>sudo su - fhem
cd /opt/yowsup-master</pre>

Nun erfolgt die anmeldung am WhatsApp-Server. Dies kann man nun via <code>voice</code> oder <code>sms</code> machen. Bei einem Handy bietet sich SMS an, ansonsten bei Festnetznummern unbedingt etwas zum schreiben bereit halten
<pre>python yowsup-cli registration -c /opt/yowsup-config/yowsup.config -r sms</pre>

Die Rückmeldung ist nun entscheidend. Wenn man diese zurückbekommt:
<pre>de sms
status: fail
retry_after: 3600
reason: no_routes</pre>
Dann ist die Nummer so nicht kompatibel. Was man dann noch probieren kann, ist die registration via voice - meistens ist das aber vergebene Liebesmüh'.

Wenn man folgende Rückmeldung bekommt:
<pre>Detected cc: 49
status: sent
retry_after: 1805
length: 6
method: sms</pre>

So ist alles gut gelaufen und man sollte kurz später eine SMS bekommen. Darin ist ein Text, der am Ende z.B. 123-456 lautet. Diesen fügt man ohne Bindestrich am Ende des folgenden Befehls ein:
<pre>python yowsup-cli registration -c /opt/yowsup-config/yowsup.config -R 123456</pre>

Dann kommt ein Text der etwa so aussehen sollte:
<pre>status: ok
kind: free
pw: bfGA9wPWWNeHcSBxxxxxxxxxxxxxxxxx
price: 0,89 €
price_expiration: 1432127524
currency: EUR
cost: 0.89
login: 498912345678
type: existing
expiration: 1460832553</pre>
Den Text hinter dem Zeilenanfang <code>pw: </code> benötigt man nun für die Konfigurationsdatei, wo dieser eingefügt werden muss:
<pre>nano /opt/yowsup-config/yowsup.config</pre>
Sodass die Datei beispielhaft dann so aussieht:
<pre>## Actual config starts below ##

#cc ist wichtig ansonsten funktioniert es nicht aus dem Script
cc=49
phone=498912345678
id=0000000000
password=bfGA9wPWWNeHcSBxxxxxxxxxxxxxxxxx</pre>

Wie man schon gesehen hat, ist der Account nur begrenzt gültig - die Gültigkeit kann man anhand der als <code>expiration: </code> bezeichneten Zeile ablesen, welche einen Unix-Timestamp beinhaltet. Diese kann man hier umrechnen lassen.

Nun mal ein schneller test an die eigene Nummer (im Beispiel 491751234567):
<pre>python yowsup-cli demos -c /opt/yowsup-config/yowsup.config -s 491751234567 "Das ist ein Test"</pre>

Das sollte dir eine Nachricht einbringen. Wenn du darauf antwortest, kommt diese allerdings noch nicht an - der Client hat sich nach dem Befehl sofort beendet. Damit dieser dauerhaft im Hintergrund läuft legen wir nun in FHEM ein Gerät an, welches dies steuert.

=== FHEM Define ===
* Fhem Device anlegen: <code> define <name> yowsup</code>, also z.B. <code>define WhatsApp yowsup</code>
* Nun muss man den Pfad zu yowsup anpassen: <code>attr WhatsApp cmd /opt/yowsup-master/yowsup-cli demos -c /opt/yowsup-config/yowsup.config --yowsup</code>
* Und das Home directory mit dem Pfad zum Home des fhem users: <code>attr WhatsApp home /home/fhem</code>
* Wenn alles gut geht, gibt es danach im Device ein internal PID und das Reading ''state''
* Im Whatsapp Client auf dem Handy sollte man sehen, dass Fhem online ist
* Zum Senden aus Fhem kann man das Kommando <code>set WhatsApp send <nummer> <text></code> verwenden

== Attribute ==
Bitte sehe immer in der [[http://fhem.de/commandref.html#yowsup Commandref]] nach - diese hier könnten veraltet sein.

* <code>cmd</code> komplettes Kommando, um den yowsup Client zu starten. z.B.: <code>attr WhatsApp cmd /opt/local/bin/yowsup-cli demos -c /root/config.yowsup --yowsup</code>
* <code>accept_from</code> kommagetrennte Liste von Kontakten (Nummern), von denen Nachrichten akzeptiert werden. Ist das Attribut nicht gesetzt, so werden die Nachrichten von jedem akzeptiert.
* <code>commandPrefix</code> nicht gesetzt -> es werden keine Befehle akzeptiert. 0 -> es werden keine Befehle akzeptiert. 1 -> erlaubt Befehle, jede Nachricht wird als Fhem-Befehl interpretiert. alles andere -> Wenn die Nachricht mit diesem Prefix startet, wird alles weitere als Befehle interpretiert.
{{Randnotiz|RNTyp=Warn|RNText='''allowedCommands''' should work as intended, but no guarantee can be given, that there is no way to circumvent it.}}
* <code>allowedCommands</code> Eine Komma-getrennte Liste von zulässigen Befehlen für diesen Kontakt. Wenn die Liste leer ist (z.B. nur ein Komma), dann werden keine Befehle akzeptiert.
* <code>home</code> Setzt das Home-directory welches für yowsup verwendet werden soll.

== Befehle ==
* image -> Über diesen Befehl können Bilder gesendet werden.

== Anwendungsbeispiele ==
=== Beispielnachricht ===
Beim Empfang einer Nachricht wird automatisch ein Fhem Device für diesen Kontakt angelegt. In diesem Device gibt es das Reading '''message''' für die empfangene Nachricht und ab der ersten Nachricht auch das Reading '''chatstate''', in dem zu sehen ist, ob gerade getippt wird.
Nachdem ein Device für einen Kontakt angelegt ist, lässt sich auch direkt dieses Device zum Senden verwenden:
:<code>set <device> send <text></code>,
d.h., man spart sich die Angabe der Nummer.

=== Gruppen ===
Gruppennachrichten werden von yowsup mit Sonderzeichen im Absender empfangen:
: 49yyyyyyyyyyyy/49xxxxxxxxxxx-1234567890
: absender/gründer-timestamp
Aufgrund der Sonderzeichen schlägt das automatische Anlegen einer yowsup Instanz fehl. Es kann aber zum Versenden direkt die JID der Gruppe genutzt werden, oder manuell die yowsup Instanz ohne Sonderzeichen gemacht werden.
: erst kommt die Nummer des Gruppenerstellers, dann die Uhrzeit im Unix Zeitformat.
: 49xxxxxxxxxxx-1234567890
: gründer-timestamp
:<code>define whatsapp.gruppe yowsup 49xxxxxxxxxxx-1234567890</code>
==== JID der Gruppe ermitteln ====
Am einfachsten ist es, eine Nachricht an die Gruppe zu senden und aus der Fehlermeldung von Fhem die JID herauszusuchen.
Etwas gezielter geht es mit der Auflistungsfunktion von yowsup direkt.
:<code>set WhatsApp raw /groups list</code>

Um die Ergebnisse eines raw Befehls im Log zu sehen, muss noch [[verbose]] 4 gesetzt werden:
:<code>attr WhatsApp verbose 4</code>
Dieses Attribut sollte, wenn nicht mehr benötigt, wieder gelöscht werden, um unnötige Logeinträge zu vermeiden.

== Links ==
* {{Link2Forum|Topic=27543|LinkText=Forenthread}}, in dem die Whatsapp Anwendung beschrieben wird
* {{Link2Forum|Topic=27543|Message=299292|LinkText=Foreneintrag}}, ab dem das yowsup Modul beschrieben wird
* Die Python Whatsapp Library auf [https://github.com/tgalal/yowsup github]

Yowsup

2015-06-21T13:25:54Z

SirUli: Update der Installation - die Kleinigkeiten waren alle im Thread zu finden

{{SEITENTITEL:yowsup}}
{{Infobox Modul
|ModPurpose=Schnittstelle, um WhatsApp-Nachrichten empfangen und senden zu können.
|ModType=d
|ModCmdRef=yowsup
|ModFTopic=27543
|ModForumArea=Unterstuetzende Dienste
|ModTechName=32_yowsup.pm
|ModOwner=André / justme1968 ({{Link2FU|430|Forum}} / [[Benutzer Diskussion:justme|Wiki]])
}}

Das Modul [[yowsup]] dient dazu, WhatsApp-Nachrichten zu empfangen und zu senden.

== Voraussetzungen ==
* Die Funktionalität ist vermutlich auf Linux/Unix Systeme beschränkt.
* Nach der Erstinstallation/-einrichtung '''muss''' zwingend das ''cmd'' Attribut korrekt gesetzt werden.

== Installation ==
Die ursprüngliche Einrichtung wurde hier {{Link2Forum|Topic=27543|Message=204426|LinkText=hier beschrieben}}, jedoch sind noch einige wichtige Dinge zu setzen.

=== Yowsup Installation ===
Los gehts mit den Paketen:
<code>sudo apt-get install python-soappy python-dateutil python-pip python-dev build-essential</code>

Nun erstmal pip updaten:
<code>sudo pip install --upgrade pip</code>

Und dann axolotl installieren (das dauert ne Weile):
<code>sudo pip install python-axolotl</code>

Will man Bilder verarbeiten, so braucht man noch ein paar Pakete mehr:
* Paketinstallationen:
** Unter Debian Wheezy: <code>sudo apt-get install libtiff4-dev libjpeg8-dev zlib1g-dev libfreetype6-dev liblcms2-dev libwebp-dev tcl8.5-dev tk8.5-dev python-tkv</code>
** Unter Debian Jessie: <code>sudo apt-get install libtiff5-dev libjpeg-dev zlib1g-dev libfreetype6-dev liblcms2-dev libwebp-dev tcl8.5-dev tk8.5-dev python-tk</code>
* PIP:<code>sudo pip install -l pillow</code>

Nun loggt man sich unter dem User ein, unter dem fhem läuft (in den folgenden Beispielen als "fhem" benannt, sein home ist /home/fhem und seine gruppe nenne ich "dialout") und lässt dort die $HOME-Variable heraus:
<pre>sudo su - fhem
echo $HOME
cd $HOME
logout</pre>
Diesen Wert braucht man später - gut merken. Sollte hier ein Fehler auftreten (z.B. das home nicht vorhanden), so muss dies zuerst korrigiert werden.

Desweiteren muss man nun yowsup installieren, was wie folgt vonstatten geht:
<pre>cd /opt
mkdir yowsup-config
sudo wget https://github.com/tgalal/yowsup/archive/master.zip
sudo unzip master.zip
rm master.zip
cd yowsup-config
sudo nano yowsup.config</pre>

Wie bemerkt, ist man nun im Editor für die yowsup.config gelandet. Diese wird nun wie folgt gefüllt:
<pre>## Actual config starts below ##

#cc ist wichtig ansonsten funktioniert es nicht aus dem Script
cc=49
phone=498912345678
id=0000000000
password=</pre>
Ersetze die Nummer 498912345678 gegen eine Festnetz oder Handynummer welche derzeit nicht mit WhatsApp verwendet wird. Mittels STRG+o wird die Datei nun gespeichert und mittels STRG+x verlässt man den Editor.

Vor den weiteren Schritten sollte man nun erstmal die yowsup Verzeichnisse dem fhem-user zugängig machen:
<pre>sudo chown -R fhem:dialout /opt/yowsup-master /opt/yowsup-config</pre>

Für die folgenden Schritte würde ich auf den FHEM-Nutzer wechseln:
<pre>sudo su - fhem
cd /opt/yowsup-master</pre>

Nun erfolgt die anmeldung am WhatsApp-Server. Dies kann man nun via <code>voice</code> oder <code>sms</code> machen. Bei einem Handy bietet sich SMS an, ansonsten bei Festnetznummern unbedingt etwas zum schreiben bereit halten
<pre>python yowsup-cli registration -c /opt/yowsup-config/yowsup.config -r sms</pre>

Die Rückmeldung ist nun entscheidend. Wenn man diese zurückbekommt:
<pre>de sms
status: fail
retry_after: 3600
reason: no_routes</pre>
Dann ist die Nummer so nicht kompatibel. Was man dann noch probieren kann, ist die registration via voice - meistens ist das aber vergebene Liebesmüh'.

Wenn man folgende Rückmeldung bekommt:
<pre>Detected cc: 49
status: sent
retry_after: 1805
length: 6
method: sms</pre>

So ist alles gut gelaufen und man sollte kurz später eine SMS bekommen. Darin ist ein Text, der am Ende z.B. 123-456 lautet. Diesen fügt man ohne Bindestrich am Ende des folgenden Befehls ein:
<pre>python yowsup-cli registration -c /opt/yowsup-config/yowsup.config -R 123456</pre>

Dann kommt ein Text der etwa so aussehen sollte:
<pre>status: ok
kind: free
pw: bfGA9wPWWNeHcSBxxxxxxxxxxxxxxxxx
price: 0,89 €
price_expiration: 1432127524
currency: EUR
cost: 0.89
login: 498912345678
type: existing
expiration: 1460832553</pre>
Den Text hinter dem Zeilenanfang <code>pw: </code> benötigt man nun für die Konfigurationsdatei, wo dieser eingefügt werden muss:
<pre>nano /opt/yowsup-config/yowsup.config</pre>
Sodass die Datei beispielhaft dann so aussieht:
<pre>## Actual config starts below ##

#cc ist wichtig ansonsten funktioniert es nicht aus dem Script
cc=49
phone=498912345678
id=0000000000
password=bfGA9wPWWNeHcSBxxxxxxxxxxxxxxxxx</pre>

Wie man schon gesehen hat, ist der Account nur begrenzt gültig - die Gültigkeit kann man anhand der als <code>expiration: </code> bezeichneten Zeile ablesen, welche einen Unix-Timestamp beinhaltet. Diese kann man hier umrechnen lassen.

Nun mal ein schneller test an die eigene Nummer (im Beispiel 491751234567):
<pre>python yowsup-cli demos -c /opt/yowsup-config/yowsup.config -s 491751234567 "Das ist ein Test"</pre>

Das sollte dir eine Nachricht einbringen. Wenn du darauf antwortest, kommt diese allerdings noch nicht an - der Client hat sich nach dem Befehl sofort beendet. Damit dieser dauerhaft im Hintergrund läuft legen wir nun in FHEM ein Gerät an, welches dies steuert.

=== FHEM Define ===
* Fhem Device anlegen: <code> define <name> yowsup</code>, also z.B. <code>define WhatsApp yowsup</code>
* Nun muss man den Pfad zu yowsup anpassen: <code>attr WhatsApp cmd /opt/yowsup-master/yowsup-cli demos -c /opt/yowsup-config/yowsup.config --yowsup</code>
* Und das Home directory mit dem Pfad zum Home des fhem users: <code>attr WhatsApp home /home/fhem</code>
* Wenn alles gut geht, gibt es danach im Device ein internal PID und das Reading ''state''
* Im Whatsapp Client auf dem Handy sollte man sehen, dass Fhem online ist
* Zum Senden aus Fhem kann man das Kommando <code>set WhatsApp send <nummer> <text></code> verwenden

=== Attribute ===
Bitte sehe immer in der Commandref nach - diese hier könnten veraltet sein.

* <code>cmd</code> komplettes Kommando, um den yowsup Client zu starten. z.B.: <code>attr WhatsApp cmd /opt/local/bin/yowsup-cli demos -c /root/config.yowsup --yowsup</code>
* <code>accept_from</code> kommagetrennte Liste von Kontakten (Nummern), von denen Nachrichten akzeptiert werden. Ist das Attribut nicht gesetzt, so werden die Nachrichten von jedem akzeptiert.
* <code>commandPrefix</code> nicht gesetzt -> es werden keine Befehle akzeptiert. 0 -> es werden keine Befehle akzeptiert. 1 -> erlaubt Befehle, jede Nachricht wird als Fhem-Befehl interpretiert. alles andere -> Wenn die Nachricht mit diesem Prefix startet, wird alles weitere als Befehle interpretiert.
{{Randnotiz|RNTyp=Warn|RNText='''allowedCommands''' should work as intended, but no guarantee can be given, that there is no way to circumvent it.}}
* <code>allowedCommands</code> Eine Komma-getrennte Liste von zulässigen Befehlen für diesen Kontakt. Wenn die Liste leer ist (z.B. nur ein Komma), dann werden keine Befehle akzeptiert.
* <code>home</code> Setzt das Home-directory welches für yowsup verwendet werden soll.

=== Befehle ===
* image -> Über diesen Befehl können Bilder gesendet werden.

== Anwendungsbeispiele ==
=== Beispielnachricht ===
Beim Empfang einer Nachricht wird automatisch ein Fhem Device für diesen Kontakt angelegt. In diesem Device gibt es das Reading '''message''' für die empfangene Nachricht und ab der ersten Nachricht auch das Reading '''chatstate''', in dem zu sehen ist, ob gerade getippt wird.
Nachdem ein Device für einen Kontakt angelegt ist, lässt sich auch direkt dieses Device zum Senden verwenden:
:<code>set <device> send <text></code>,
d.h., man spart sich die Angabe der Nummer.

=== Gruppen ===
Gruppennachrichten werden von yowsup mit Sonderzeichen im Absender empfangen:
: 49yyyyyyyyyyyy/49xxxxxxxxxxx-1234567890
: absender/gründer-timestamp
Aufgrund der Sonderzeichen schlägt das automatische Anlegen einer yowsup Instanz fehl. Es kann aber zum Versenden direkt die JID der Gruppe genutzt werden, oder manuell die yowsup Instanz ohne Sonderzeichen gemacht werden.
: erst kommt die Nummer des Gruppenerstellers, dann die Uhrzeit im Unix Zeitformat.
: 49xxxxxxxxxxx-1234567890
: gründer-timestamp
:<code>define whatsapp.gruppe yowsup 49xxxxxxxxxxx-1234567890</code>
==== JID der Gruppe ermitteln ====
Am einfachsten ist es, eine Nachricht an die Gruppe zu senden und aus der Fehlermeldung von Fhem die JID herauszusuchen.
Etwas gezielter geht es mit der Auflistungsfunktion von yowsup direkt.
:<code>set WhatsApp raw /groups list</code>

Um die Ergebnisse eines raw Befehls im Log zu sehen, muss noch [[verbose]] 4 gesetzt werden:
:<code>attr WhatsApp verbose 4</code>
Dieses Attribut sollte, wenn nicht mehr benötigt, wieder gelöscht werden, um unnötige Logeinträge zu vermeiden.

== Links ==
* {{Link2Forum|Topic=27543|LinkText=Forenthread}}, in dem die Whatsapp Anwendung beschrieben wird
* {{Link2Forum|Topic=27543|Message=299292|LinkText=Foreneintrag}}, ab dem das yowsup Modul beschrieben wird
* Die Python Whatsapp Library auf [https://github.com/tgalal/yowsup github]

HMS 100 WD Wassermelder

2015-05-21T06:26:36Z

SirUli: Bild-Update

{{Infobox Hardware
|Bild=HMS100WD.jpg
|Bildbeschreibung=HMS 100 WD
|HWProtocol=HMS
|HWType=Sender
|HWCategory=HMS
|HWComm=868MHz
|HWChannels=1
|HWVoltage=3V
|HWPowerConsumption=?
|HWPoweredBy=Batterie, 2xAA
|HWSize=70 x 100 x 24 mm
|HWDeviceFHEM=[http://fhem.de/commandref.html#HMS 12_HMS.pm]
|HWManufacturer=ELV / eq3
}}
Durch zwei, in das Gehäuse integrierte Fühlerpaare registriert der Wassermelder HMS 100 WD auftretende Feuchtigkeit und Flüssigkeiten auf dem Boden. Bereits geringe Pegel sind durch das flache aufliegen des Gehäuses messbar.

== Features ==
Zustandsänderungen werden sofort übertragen und alle 30 Minuten wiederholt. Zudem wird im Alarmfall der Zustand "ständig" ausgegeben.

Der Wassermelder ist bis zu einem Wasserstand von 2mm einsetzbar.

== Readings ==
{| class="wikitable"
! Parameter
! Wertbeispiel
! Erklärung
|-
| battery
| empty
| Ladezustand der Batterie
|-
| state
| Water Detect: off
| Zustand des Wassermelders
|-
| water_detect
| off
| Zustand des Wassermelders
|-
| type
| HMS100WD
| Typenbezeichnung
|}

== Hinweise zum Betrieb mit FHEM ==
Das Gerät ist uneingeschränkt mit FHEM nutzbar.

== Bekannte Probleme ==
Keine

== Link ==
* Bedienungsanleitung [http://files.elv.de/service/manuals/HMS100WD/HMS100WD_UM_G_030226.pdf PDF]

[[Kategorie:HMS Components]]

Datei:HMS100WD.jpg

2015-05-21T06:26:10Z

SirUli:

HMS 100 WD Wassermelder

2015-05-21T06:06:52Z

SirUli: Erste Version

{{Infobox Hardware
|Bild=PlatzHalter.png
|Bildbeschreibung=HMS 100 WD
|HWProtocol=HMS
|HWType=Sender
|HWCategory=HMS
|HWComm=868MHz
|HWChannels=1
|HWVoltage=3V
|HWPowerConsumption=?
|HWPoweredBy=Batterie, 2xAA
|HWSize=70 x 100 x 24 mm
|HWDeviceFHEM=[http://fhem.de/commandref.html#HMS 12_HMS.pm]
|HWManufacturer=ELV / eq3
}}
Durch zwei, in das Gehäuse integrierte Fühlerpaare registriert der Wassermelder HMS 100 WD auftretende Feuchtigkeit und Flüssigkeiten auf dem Boden. Bereits geringe Pegel sind durch das flache aufliegen des Gehäuses messbar.

== Features ==
Zustandsänderungen werden sofort übertragen und alle 30 Minuten wiederholt. Zudem wird im Alarmfall der Zustand "ständig" ausgegeben.

Der Wassermelder ist bis zu einem Wasserstand von 2mm einsetzbar.

== Readings ==
{| class="wikitable"
! Parameter
! Wertbeispiel
! Erklärung
|-
| battery
| empty
| Ladezustand der Batterie
|-
| state
| Water Detect: off
| Zustand des Wassermelders
|-
| water_detect
| off
| Zustand des Wassermelders
|-
| type
| HMS100WD
| Typenbezeichnung
|}

== Hinweise zum Betrieb mit FHEM ==
Das Gerät ist uneingeschränkt mit FHEM nutzbar.

== Bekannte Probleme ==
Keine

== Link ==
* Bedienungsanleitung [http://files.elv.de/service/manuals/HMS100WD/HMS100WD_UM_G_030226.pdf PDF]

[[Kategorie:HMS Components]]

HM-LC-DIM1T-FM 1-Kanal-Dimmer UP

2015-01-10T13:33:08Z

SirUli: Link aktualisiert

Homematic Funk 1-Kanal-Dimmer, Phasenabschnitt (Unterputz)

= Features =

Schalten eines angeschlossenen Verbrauchers mittels [[CUL]]/[[CUN]]/[[HMLAN Konfigurator]] und über einen mechanischen spannungsfesten Taster.

Schaltdoseneinsatz zusätzlich zu vorhandenem Taster (erfordert evtl. tiefere Schaltdose).

'''Technische Daten:'''
* Schaltvermögen: 180VA 230V/50Hz
* Art: Phasenabschnittdimmer
* Standby Verbrauch: 1W
* Maße(BxHxT): 53x53x30mm

= Hinweise zur Hardware-Installation =

Will man die Funk-Schaltaktoren auch manuell betreiben, d.h. man upgradet eine vorhandene Elektroinstallation, so sind Taster notwendig. Schalter können notfalls mittels einer zusätzlichen Feder zu Taster umgebaut werden, Tastschalter sind leider nicht geeignet. Schalter und Tastschalter führen dazu, dass der Aktor nach Betätigung des Schalters in den Anlernmodus versetzt wird und auch in diesem verbleibt.

Je nach vorhandenen Schalterdosen empfiehlt es sich bestehende Schalterdosen nach hinten auszuweiten, d.h. die Abdeckung nach hinten heraus zu brechen, da die Aktoren und Kabel nicht gerade sparsam mit dem Platz umgehen. Alternativ könnte man den Aktor auch in eine zusätzliche Schalterdosen unterbringen und diese mit einem Federdeckel abschließen. Dies hat den Vorteil, dass man auch durch relativ dicke Tapete die LED und somit den Zustand des Aktors ablesen kann.

= Kompatible Leuchtmittel =

Hier eine Übersicht über die Kompatibilität des HM-LC-DIM1T-FM mit diversen Leuchtmitteln:

{| cellspacing="0" border="1"
| '''Art'''
| '''Bezeichnung'''
| '''Sockel'''
| '''Verbrauch'''
| '''Farbtemperatur'''
| '''Laut Hersteller geeignet für'''
| '''Funktion'''
| '''Einschränkungen'''
| '''Kompatibilitätsliste'''
| '''Hersteller Link'''
|-
| Glühlampe
| Glühlampe
|
|
|
| An-/Abschnitt
| ja
| nein
|
|
|-
| Energiesparlampe
| Osram Dulux Intelligent Dim Globe
|
|
|
| Anschnitt
| vermutlich nein
| ?
|
| [http://www.osram.de/osram_de/produkte/lampen/kompaktleuchtstofflampen/osram-dulux-intelligent/osram-dulux-intelligent-dim-globe/index.jsp]
|-
| Energiesparlampe
| Osram Dulux Intelligent Dim Stick
|
|
|
| Anschnitt
| vermutlich nein
| ?
|
| [http://www.osram.de/osram_de/produkte/lampen/kompaktleuchtstofflampen/osram-dulux-intelligent/osram-dulux-intelligent-dim-stick/index.jsp]
|-
| Energiesparlampe
| Phlilips Softone Dimmable
|
|
|
| An-/Abschnitt
| ?
| ?
|
| [http://www.ecat.lighting.philips.de/l/professionelle-lampen/energiesparlampen/energiesparlampen-gluehlampenform/softone-dimmable/20165/cat/]
|-
| Energiesparlampe
| Phlilips MASTER PL-Electronic Dimmable
|
|
|
| An-/Abschnitt
| ?
| ?
|
| [http://www.ecat.lighting.philips.at/l/professionelle-lampen/energiesparlampen/energiesparlampen-roehrenform/master-pl-electronic-dimmable/18109/cat/]
|-
| Energiesparlampe
| Phlilips TORNADO ESaver Dimmable
|
|
|
| Anschnitt
| vermutlich nein
| ?
|
| [http://www.ecat.lighting.philips.de/l/professionelle-lampen/energiesparlampen/energiesparlampen-spezialform/tornado-esaver-dimmable/19666/cat/]
|-
| LED
| Delock Lighting
| GU10
| 6W
| 3000K
| Anschnitt/Universal (RL/RLC)
| eingeschränkt
| Dimmbereich
| ELV [http://www.elv-downloads.de/Assets/Produkte/10/1075/107524/Downloads/107524_delock.pdf]
| [http://www.delock-lighting.de/produkte/G_46327/merkmale.html]
|-
| LED
| Ledon LED-Spot MR16
| GU10
| 5W
| 2700K
| k.A.
| ja
|
| ELV [http://www.elv-downloads.de/Assets/Produkte/10/1026/102699/Downloads/102699_ledon.pdf]
| [http://www.ledon-lamp.com/de/ledon_led-lampe_MR16_5W_GU10_DIM.htm]
|-
| LED
| Ledon Tropfenform
| E14
| 5W
| 2700K
| k.A.
| ja
|
| ELV [http://www.elv-downloads.de/Assets/Produkte/9/995/99557/Downloads/099557_Ledon.pdf]
| [http://www.ledon-lamp.com/de/ledon_led-lampe_P45_5W_E14_DIM.htm]
|-
| LED
| Ledon Kerzenform klar B35/C
| E14
| 5W
| 2700K
| k.A.
| eingeschränkt
| Dimmbereich
| ELV [http://www.elv-downloads.de/Assets/Produkte/9/995/99554/Downloads/099554_Ledon.pdf]
| [http://www.ledon-lamp.com/de/ledon_led-lampe_B35_C_5W_E14%20DIM.htm]
|-
| LED
| Ledon Globe G80
| E27
| 6W
| 2800K
| k.A.
| ja
|
| ELV [http://www.elv-downloads.de/Assets/Produkte/9/995/99586/Downloads/099586_Ledon.pdf]
| [http://www.ledon-lamp.com/de/ledon_led-lampe_G80_6W_E27_DIM.htm]
|-
| LED
| Ledon A65
| E27
| 10W
| 2700K
| k.A.
| ja
|
| ELV [http://www.elv-downloads.de/Assets/Produkte/10/1000/100026/Downloads/100026_Ledon.pdf]
| [http://www.ledon-lamp.com/de/ledon_led-lampe_A65_10W_E27_DIM.htm]
|-
| LED
| Ledon G95
| E27
| 10W
| 2700K
| k.A.
| ja
|
| ELV [http://www.elv-downloads.de/Assets/Produkte/10/1022/102273/Downloads/102273_ledon.pdf]
| [http://www.ledon-lamp.com/de/ledon_led-lampe_G95_10W_E27_DIM.htm]
|-
| LED
| LG LED-Glühbirne A19
| E27
| 12,8W
| 2700K
| k.A.
| eingeschränkt
| Dimmbereich
| ELV [http://www.elv-downloads.de/Assets/Produkte/10/1020/102043/Downloads/102043_LG.pdf]
| [http://www.lg.com/de/innenbeleuchtung/lg-A1912GD0GE1.C0AASAA-gluehbirne]
|-
| LED
| Osram SUPERSTAR PAR 16
| GU10
| 5,5W
| 3000K
| k.A.
| ja
|
| ELV [http://www.elv-downloads.de/Assets/Produkte/10/1025/102569/Downloads/102569_osram.pdf]
| [http://www.osram.de/osram_de/produkte/lampen/led-lampen/consumer-led-reflektorlampen/led-superstar-par-16/index.jsp]
|-
| LED
| Osram PARATHOM PRO PAR 16 advanced 50
| GU10
| 9W
| 4000K
| k.A.
| eingeschränkt
| Dimmbereich
| ELV [http://www.elv-downloads.de/Assets/Produkte/10/1083/108338/Downloads/108338_osram.pdf]
| [http://www.osram.de/osram_de/produkte/lampen/led-lampen/professional-led-reflektorlampen/parathom-pro-par-16-advanced/index.jsp]
|-
| LED
| Osram PARATHOM PRO PAR 16 advanced 35
| GU10
| 5,2W
| 4000K
| k.A.
| ja
|
| ELV [http://www.elv-downloads.de/Assets/Produkte/10/1083/108337/Downloads/108337_osram.pdf]
| [http://www.osram.de/osram_de/produkte/lampen/led-lampen/professional-led-reflektorlampen/parathom-pro-par-16-advanced/index.jsp]
|-
| LED
| Osram LED Superstar Classic A50
| E27
| 12W
| 3000K
| k.A.
|
|
|
| [http://www.osram.de/osram_de/produkte/lampen/led-lampen/consumer-led-lampen-mit-klassischen-kolbenformen/led-superstar-classic-a-advanced/index.jsp]
|-
| LED
| Osram LED Superstar Classic A40
| E27
| 8,5W
| 2700K
| k.A.
| nein
|
| ELV [http://www.elv-downloads.de/Assets/Produkte/10/1082/108212/Downloads/108212_osram.pdf]
| [http://www.osram.de/osram_de/produkte/lampen/led-lampen/consumer-led-lampen-mit-klassischen-kolbenformen/led-superstar-classic-a-advanced/index.jsp]
|-
| LED
| Osram LED Superstar Classic A60
| E27
| 12W
| 2700K
| k.A.
| nein
|
| ELV [http://www.elv-downloads.de/Assets/Produkte/10/1077/107748/Downloads/107748_osram.pdf]
| [http://www.osram.de/osram_de/produkte/lampen/led-lampen/consumer-led-lampen-mit-klassischen-kolbenformen/led-superstar-classic-a-advanced/index.jsp]
|-
| LED
| Osram LED Superstar Classic A75
| E27
| 14,5W
| 2700K
| k.A.
| nein
|
| ELV [http://www.elv-downloads.de/Assets/Produkte/10/1077/107749/Downloads/107749_osram.pdf]
| [http://www.osram.de/osram_de/produkte/lampen/led-lampen/consumer-led-lampen-mit-klassischen-kolbenformen/led-superstar-classic-a-advanced/index.jsp]
|-
| LED
| Osram PARATHOM CLASSIC A advanced 50
| E27
| 12W
| 3000K
| k.A.
|
|
|
| [http://www.osram.de/osram_de/produkte/lampen/led-lampen/professional-led-lampen-mit-klassischen-kolbenformen/parathom-classic-a-advanced/index.jsp]
|-
| LED
| Osram PARATHOM CLASSIC A advanced 60
| E27
| 12W
| 2700K
| k.A.
|
|
|
| [http://www.osram.de/osram_de/produkte/lampen/led-lampen/professional-led-lampen-mit-klassischen-kolbenformen/parathom-classic-a-advanced/index.jsp]
|-
| LED
| Osram PARATHOM CLASSIC A advanced 60
| E27
| 13W
| 2700K
| k.A.
|
|
|
| [http://www.osram.de/osram_de/produkte/lampen/led-lampen/professional-led-lampen-mit-klassischen-kolbenformen/parathom-classic-a-advanced/index.jsp]
|-
| LED
| Osram PARATHOM CLASSIC A advanced 75
| E27
| 14,5W
| 2700K
| k.A.
|
|
|
| [http://www.osram.de/osram_de/produkte/lampen/led-lampen/professional-led-lampen-mit-klassischen-kolbenformen/parathom-classic-a-advanced/index.jsp]
|-
| LED
| Osram PARATHOM CLASSIC P advanced 25
| E14
| 4,5W
| 2700K
| k.A.
|
|
|
| [http://www.osram.de/osram_de/produkte/lampen/led-lampen/professional-led-lampen-mit-klassischen-kolbenformen/parathom-classic-p-advanced/index.jsp]
|-
| LED
| Osram PARATHOM CLASSIC P advanced 25
| E25
| 4,5W
| 2700K
| k.A.
|
|
|
| [http://www.osram.de/osram_de/produkte/lampen/led-lampen/professional-led-lampen-mit-klassischen-kolbenformen/parathom-classic-p-advanced/index.jsp]
|-
| LED
| Philips MASTER LEDspot HV
| GU10
| 4W
| 2700K
| Anschnitt/Universal (RL/RLC)
| eingeschränkt
| Dimmbereich
| ELV [http://www.elv-downloads.de/Assets/Produkte/10/1065/106561/Downloads/106561_philips.pdf]
| [http://www.ecat.lighting.philips.de/l/oem/led-systems/led-retrofit-lampen/master-ledspot-hv/929000212702_eu/]
|-
| LED
| Philips MASTER LEDspot BBL
| GU10
| 7W
| 2700K
| Anschnitt/Universal (RL/RLC)
| eingeschränkt
| Dimmbereich
| ELV [http://www.elv-downloads.de/Assets/Produkte/10/1018/101863/Downloads/101863_Philips.pdf]
| [http://www.ecat.lighting.philips.de/l/professionelle-lampen/led-lampen-und-komponenten/led-lampen/master-led-dimtone/61144/cat/]
|-
| LED
| Philips MASTER LEDbulb Designer
| E27
| 7W
| 2700k
| Anschnitt/Universal (RL/RLC)
|
|
|
| [http://www.ecat.lighting.philips.de/l/professionelle-lampen/led-lampen-und-komponenten/led-lampen/master-ledbulb-designer/61143/cat/]
|-
| LED
| Philips MASTER LEDlamps DimTone
| E27
| 8W
| 2200-2700K
| Anschnitt/Universal (RL/RLC)
| eingeschränkt
| Dimmbereich
| ELV [http://www.elv-downloads.de/Assets/Produkte/10/1027/102789/Downloads/102789_philips.pdf]
| [http://www.ecat.lighting.philips.de/l/professionelle-lampen/led-lampen-komponenten/led-lampen/master-ledlamps-dimtone/929000215102_eu/]
|-
| LED
| Philips MASTER LEDbulb D
| E27
| 8W
| 2700K
| Anschnitt/Universal (RL/RLC)
| eingeschränkt
| Dimmbereich
| ELV [http://www.elv-downloads.de/Assets/Produkte/10/1022/102239/Downloads/102239_Philips.pdf]
| [http://www.ecat.lighting.philips.de/l/professionelle-lampen/led-lampen-und-komponenten/led-lampen/master-ledbulb/19890/cat/]
|-
| LED
| Philips MASTER LEDbulb D
| E27
| 12W
| 2700K
| Anschnitt/Universal (RL/RLC)
| eingeschränkt
| Dimmbereich
| ELV [http://www.elv-downloads.de/Assets/Produkte/10/1006/100657/Downloads/100657_Philips.pdf]
| [http://www.ecat.lighting.philips.de/l/professionelle-lampen/led-lampen-und-komponenten/led-lampen/master-ledbulb/19890/cat/]
|-
| LED
| Philips MASTER LEDbulb D
| E27
| 17W
| 2700K
| Anschnitt/Universal (RL/RLC)
| ja
|
| ELV [http://www.elv-downloads.de/Assets/Produkte/10/1060/106098/Downloads/106098_philips.pdf]
| [http://www.ecat.lighting.philips.de/l/professionelle-lampen/led-lampen-und-komponenten/led-lampen/master-ledbulb/19890/cat/]
|}

== Wichtiger Hinweis zum Betrieb eines Phasenabschnittdimmers ==

Der Dimmer ist nur mit folgenden Lampen zu betreiben:
* Hochvolt-Halogenlampen
* Niedervolt- Halogenlampen mit elektronischem Trafo
* Glühlampen
* dimmbare Energiesparlampen

Im Zweifel vorher beim Hersteller nachhaken, bevor es zu Flackern oder Brummen kommt.

= Hinweise zum Betrieb mit FHEM =

Das Pairing sollte wie in [[HomeMatic Devices pairen]] beschrieben durchgeführt werden. Hierfür wird ein am Aktor temporär angeschlossener spannungsfester Taster zwingend benötigt. Im Gegensatz zu den Schaltaktoren, muss der Phasenabschnittdimmer innerhalb der ersten 5 Minuten nach Zuschalten der Netzspannung erfolgen. Nach dieser Zeitspanne ist ein Anlernen nicht mehr möglich. Darum sollte zum Anlernen des HM-LC-DIM1T-FM zuerst die Netzspannung ab- und zugeschaltet werden, d.h. praktischerweise Sicherung kurz raus und nach einer Minute wieder rein. Bitte auch zuvor alle angeschlossenen Geräte von der Sicherung trennen oder ausschalten.

== FHEM Config-Auszug ==

Ein exemplarischer Auszug aus der fhem.cfg:

<pre>
define LichtWohnzimmerDimmer CUL_HM 184436
attr LichtWohnzimmerDimmer devInfo 110100
attr LichtWohnzimmerDimmer firmware 1.2
attr LichtWohnzimmerDimmer hmClass receiver
attr LichtWohnzimmerDimmer model HM-LC-DIM1T-FM
attr LichtWohnzimmerDimmer room Wohnzimmer
attr LichtWohnzimmerDimmer serialNr IEQ0xxxxxx
attr LichtWohnzimmerDimmer subType dimmer
</pre>

== Mögliche Schaltoperationen ==

Der Aktor versteht folgende Aktionen:
<pre>
set <name> on -> Schaltet den Aktor ein
set <name> off -> Schaltet den Aktor aus
set <name> toggle -> Ein eingeschalteter Dimmer wird ausgeschaltet und ein ausgeschalteter Dimmer wird auf den letztgenutzten Wert hochgedimmt.
set <name> <Helligkeit> [<Einschaltdauer>] [<Rampenzeit>] -> Schaltet den Aktor ein und dimmt dabei auf <Helligkeit>%,
100% entspricht dabei einem "on". Optional kann als Einschaltdauer die Zeit in Sekunden angegeben werden,
bis der Dimmer wieder automatisch abschalten soll (Bereich 0.00-111600 Sekunden). Optional kann weiterhin angegeben werden,
dass der Dimmer über eine angegebene Zeit in Sekunden (Rampenzeit) auf die angegebene Helligkeit hochdimmt
(Bereich 0.00 Sekunden - 111600 Sekunden) abgeschaltet wird.
</pre>

== Log-Auszug ==
In FHEM ist nach dem Schalten des HM-LC-DIM1T-FM folgendes Log zu sehen:
<pre>
2012.02.05 23:09:19 2: CUL_HM set LichtWohnzimmerDimmer on
2012.02.05 23:09:21 2: CUL_HM set LichtWohnzimmerDimmer off
2012.02.06 22:40:15 2: CUL_HM set LichtWohnzimmerDimmer toggle
2012.02.06 22:41:15 2: CUL_HM set LichtWohnzimmerDimmer 32
</pre>

= Links =

Ein Integrationsbeispiel ist in [[Jalousie und Beleuchtung in mehreren Räumen]] zu finden.

Anleitung [http://www.eq-3.de/Downloads/eq3/pdf_produkte/HM-LC-Dim1T-FM_UM_GE_eQ-3_100422.pdf] PDF
[[Kategorie:HomeMatic Components]]
[[Kategorie:Dimmer]]

HMinfo

2015-01-02T20:23:34Z

SirUli: Tag war falsch

'''HMInfo''' ist ein Modul, das alle [[HomeMatic]] repräsentiert. Es bietet Funktionen zur Übersicht, Kontrolle, Archivierung und, begrenzt, zur Programmierung der Homematic Komponenten. Somit soll es eine Hilfestellung bei Konfiguration und Fehlerbehandlung geben.

== Definition ==
HMInfo wird erstellt / angelegt mit dem Befehl
:<code>define hm HMinfo</code>

Danach können alle Funktionen aufgelistet werden mit
:<code>get hm help</code>

== Integritätsprüfungen ==
Befehle, um die Gültigkeit von verschiedenen HomeMatic Eigenschaften zu überprüfen:
{| class="wikitable"
! Erläuterungen !! Definition
|-
| Überprüfen, ob alle peerings auch beidseitig sind:
| <code>set hm peerCheck</code>
|-
| Überprüfen, ob alle register korrekt gelesen wurden:
| <code>set hm regCheck</code>
|-
| Kombination von peerCheck und regCheck
| <code>set hm configCheck</code>
|}

== Anzeigen zur Übertragungssituation ==
===RSSI ===
;<code>get hm rssi [<filter>]</code>
:Erzeugt eine Tabelle aller RSSI Werte.
;<code>set hm clear [<filter>] rssi</code>
:setzt die RSSI Werte aller devices gemäß filter zurück. Eine neue Messung kann beginnen

===protoEvents ===
;<code>get hm protoEvents [<filter>][short|long] </code>
:Es wird eine Tabelle mit allen wichtigen Ereignissen zur Datenübertragung erzeugt. Dies beinhaltet Wiederholungen sowie Übertragungsfehler.
short ist eine Fassung ohne Zeitstempel und lässt sich besser am Bildschirm darstellen.
Ausserdem kann man sehen, welche Abfragen noch in der queue sind, z.B. durch autoReadReg erzeugt.
Die Zustände aller für HM zuständigen IOs sind beinhaltet.
Alles in allen ist hier ein kompletter Überblick zur Kommunikation zu sehen. Insbesondere bei
:<code>set hm clear [<filter>] Protocol </code>
setzt die Protokol Einträge aller gemäß Filter zurück. Kann gut vor einer Konfigurationsaktion genutzt werden, um hinterher zu kontrollieren, ob Fehler aufgetreten sind.

===msgStat===
;<code>set hm msgStat </code>
:Statistic der Übertragenen Messages insgesamt. Es gibt eine Tabelle über die letzten 24h und eine über die letzte Woche.

== Speichern von Konfigurationen==
HMInfo speichert Konfigurationen der Geräte in Files. Mit dem Attribut configDir kann man ein Verzeichnis festlegen, in das alles geschrieben wird.

=== saveConfig===
Peers und Register werden in eine Datei geschrieben. Die Daten kann man ggf. wieder in ein Gerät oder ein Austauschgerät schreiben. Die Speicherung erfolgt kumulativ, man kann alles in eine Datei schreiben.
:<code>set hm saveConfig [<filter>] [<file>] </code>

=== archConfig ===
Arbeitet prinzipiell wie saveConfig. Es werden jedoch nur vollständige Registersätze gespeichert, was einen höheren Level an Sicherheit der Dateninhalte gewährt.
:<code>set hm archConfig [-a] [<file>] </code>
Mit dem '''Attribut autoArchive''' kann man einstellen, dass automatisch nach erfolgreichem Lesen einer Device-Konfiguration diese archiviert wird.
Das Speichern erfolgt kumulativ. Ab einer Dateigröße von 1MB wird gepurged, also alles bis auf den neusten Eintrag jeder Entity gelöscht.

Um eine Konfiguration zu sichern, sollte eine Kopie des Archivs gemacht werden. Das Archiv wird bei Gelegenheit überschrieben.

Template erstellen:
:<code>set hm saveConfig -f ^meinDevice$ <myTempalteFile> </code>

=== loadConfig ===
;<code>set hm loadConfig [<filter>] [<filename>] </code>
:Liest die Registerwerte, die für eine Entity in einem File gespeichert sind, zurück in die Readings. Sollten die Register schon in FHEM vorhanden sein, wird '''nicht''' überschrieben.
Sinn macht dies beispielsweise für remotes, die nicht automatisch gelesen werden sollen. Man kann somit nach einem system-reboot die Register "rekonstruieren" und wieder darstellen.
Es liegt im ermessen des User, eine bekannt aktuelle Version der Register einzulesen.

=== purgeConfig===
;<code>set hm purgeConfig [<filename>] </code>
:Löscht alle älteren Datensätze in einem File.

== Konfigurationen bearbeiten ==
=== Templates ===
HMInfo erlaubt das Erstellen und Nutzen von Templates. Das sind Schablonen, die das Setzen von Registern abstrahieren und auf eine höhere Ebene heben. So kann man das Setzen der Konfiguration eines Aktors beispielsweise um mit einem Bewegungsmelder zusammen zu arbeiten in einem Kommando zusammenfassen.
Faktisch setzt das Template also eine Gruppe von Registern auf einmal.

====templateList ====
Die vorhandenen templates kann man mit templateList sehen.
get hm templateList

SwOnCond params:level cond Info:switch: execute only if condition [geLo|ltLo] level is below limit
SwToggle params: Info:Switch: toggle on trigger
autoOff params:time Info:staircase - auto off after <time>, extend time with each trigger
motionOnDim params:ontime brightness Info:Dimmer: on for time if MDIR-brightness below level
motionOnSw params:ontime brightness Info:Switch: on for time if MDIR-brightness below level
Die Liste der verfügbaren Tempaltes, deren Parameter falls nötig und eine kurze Info, was das Template bewirken soll

get hm templateList autoOff

autoOff params:time Info:staircase - auto off after <time>, extend time with each trigger
ActionType :jmpToTarget
OffTime :111600
OnTime :time
SwJtDlyOff :dlyOn
SwJtDlyOn :no
SwJtOff :dlyOn
SwJtOn :on
Ein templateList auf ein einzelnes Template zeigt im Detail, was das Template verändern wird.

====templateSet ====
Um ein Template auf einen Aktor anzuwenden, muss man neben den spezifischen Parametern angeben, für welchen Peer es gelten soll und ob es bei einem kurzen oder langen Tastendruck angewendet werden soll.
set hm templateSet <entity> <templateName> <peer:[long|short]> [<param1> ...]
set hm templateSet Licht1 autoOff FB1_Btn2:short 10
set hm templateSet Licht1 SwOn FB1_Btn2:long
Licht1 soll, wenn ein kurzer Trigger von FB1_Btn2 kommt für 10 sec eingeschaltet werden, dann ausgehen (Treppenhausfunktion). Kommt aber ein langer Tastendruck wird das Licht dauerhaft eingeschaltet.
set hm templateSet Licht1 motionOnSw MD1:short 30 20
Der Switch Aktor Licht1 soll mit einem Bewegungsmelder betrieben werden. Der Bewegungsmelder sendet keine 'langen' Trigger sondern nur kurze. Im Beispiel wird Licht1 für 30 Sekunden eingeschaltet, wenn der Bewegungsmelder einen Trigger sendet UND es dunkler ist als "20" (Brightness level).

====templateDef ====
Neben den vorbereiteten Templates kann der User eigene definieren oder von anderen Usern sich Templates geben lassen. Die Definition von Templates ist für erfahrene User gedacht, im Gegensatz zur Nutzung eines Templates mit set - das ist für Anfänger gedacht.
set hm templateDef <templateName> <param1[:<param2>...] <description> <reg1>:<val1> [<reg2>:<val2>] ...
set hm templateDef myTemplate anzeit:auszeit "licht schaltet ständig an und aus" OnTime:anzeit OffTime:auszeit OnDly:0
Mit diesem Template wird die Anzeit und die Auszeit eines Schalt-Aktors auf den vom User gewünschten Wert gesetzt. Die Verzögerung OnDly wird auf 0 gesetzt.

====templateChk ====
Man kann prüfen, ob ein Aktor/Peer gemäss einem Template programmiert ist.
get hm templateChk [<filter>] <templateName> <peer:[long|short]> [<param1> ...]
get hm templateChk -f Rollo RolloHoch self01 5
Es wird geprüft für alle HM-Komponenten, die "Rollo" im Namen haben (siehe [[Homematic HMInfo#Filter|Filter]]) dem (hoffentlich vorhandenen) template "RolloHoch" verglichen. Geprüft wird nur der Peer "self01", aber für long UND short.
get hm templateChk -f Rollo RolloHoch self01:sort 5
das selbe, nur für short Einträge

===Temperaturlisten===
HMInfo bietet verschiedene Methoden, Temperaturlisten für Thermostate (CC-TC, TC-IT oder RT) zu verwalten und zu nutzen. Prinzip ist, dass die Temperaturlisten in einer Konfigurationsdatei abgelegt werden. Der Dateiname ist frei wählbar.
Für alle Kommandos können die [[Homematic HMInfo#Filter|Filter]] genutzt werden.
Beim Prüfen und Speichern wird davon ausgegangen, dass die Register und Daten in FHEM aktuell sind. Die Funktionen speichern und vergleichen aus Performancegründen nicht direkt im Device sondern die Daten, die FHEM schon gelesen hat.
Siehe auch '''autoReadReg''' Attribut der HM Komponenten.

====Speichern ====
;<code>set hm tempList save <filename> <code>
:Die in FHEM vorhandenen Temperaturlisten aller devices (hier ist kein Filter gesetzt, also alle) werden in die Datei <filename> geschrieben. Man kann dieses als Basis nehmen, um seine Temperaturlisten zu bearbeiten.
====Prüfen====
;<code>set hm tempList verify <filename> </code>
:HMInfo vergleicht die in der Datei abgelegten Temperaturlisten mit den in FHEM vorliegenden. Unterschiede werden gemeldet. Es wird nichts in das Device geschrieben oder verändert.

====Restore====
;<code>set hm tempList restore <filename> </code>
:Es werden alle Temperaturlisten aus der Datei in die dafür eingerichteten Komponenten eingetragen. Dabei werden ausschließlich die Änderungen geschrieben. Liegen keine Unterschiede zwischen Dateiinhalt und aktuellen Daten vor, wird auch nichts geschrieben. Ein mehrfaches anwenden des Kommandos ist also keine Belastung des Systems.
Will man das '''Schreiben''' ungeachtet der vorhandenen Daten '''erzwingen''' sollte man mit "clear Register" die in FHEM vorhandenen Einträge löschen und dann ein tempList restore ausführen.

====Defaults====
Der Default-Dateiname ist '''tempList.cfg'''.
Die Datei steht im fhem-root Verzeichnis. Hat man das Attribut configDir gesetzt und gibt kein Verzeichnis an, wird die Datei im spezifizierten Verzeichnis gesucht.
Das default-template ist der Name des Device. Ist im Device das '''Attribut tempListTmpl''' gesetzt, wird dies zum Vergleich oder Setzen genutzt.

====Aufbau Tempfile====
Zum erstmaligen Erstellen einer Datei nutzt man am einfachsten das Kommando tempList save.

entities:HK1,HK2
R_0_tempListSat>08:00 14.0 15:00 18.0 21:30 19.0 24:00 14.0
R_1_tempListSun>08:00 14.0 15:00 18.0 21:30 19.0 24:00 14.0
R_2_tempListMon>07:00 14.0 16:00 18.0 21:00 19.0 24:00 14.0
R_3_tempListTue>07:00 14.0 13:00 16.0 16:00 18.0 21:00 19.0 24:00 15.0
R_4_tempListWed>07:00 14.0 16:00 18.0 21:00 19.0 24:00 14.0
R_5_tempListThu>07:00 14.0 16:00 18.0 21:00 19.0 24:00 14.0
R_6_tempListFri>07:00 14.0 13:00 16.0 16:00 18.0 21:00 19.0 24:00 14.0
entities:HK3
R_0_tempListSat>08:00 14.0 15:00 18.0 21:30 19.0 24:00 14.0
R_1_tempListSun>08:00 14.0 15:00 18.0 21:30 19.0 24:00 14.0
R_2_tempListMon>07:00 14.0 16:00 18.0 21:00 19.0 24:00 14.0
R_3_tempListTue>07:00 14.0 13:00 16.0 16:00 18.0 21:00 19.0 24:00 15.0
R_4_tempListWed>07:00 14.0 16:00 18.0 21:00 19.0 24:00 14.0
R_5_tempListThu>07:00 14.0 16:00 18.0 21:00 19.0 24:00 14.0
R_6_tempListFri>07:00 14.0 13:00 16.0 16:00 18.0 21:00 19.0 24:00 14.0

Die Zeile '''entities''' legt fest, für welche Komponenten die nachfolgende Liste gültig sein soll. Die Erste ist also gültig für HK1 und HK2, die Zweite für HK3.
Will man identische Listen für mehrere Komponenten nutzen, schreibt man deren Namen einfach in die Liste der Entities.
Zu Beachten ist, dass nach Ändern der Liste ein erneutes templistSave auf den gleichen Dateinamen die Daten verändern kann. Es ist daher ratsam, den Dateinamen einer manuell bearbeiteten Konfiguration nicht beim Default zu belassen.

====tempList Templates====
User möchten möglicherweise die Temperaturlisten einer Komponente über das Jahr verändern (Sommer- und Winterprofil). Dazu kann man Templates festlegen. Das ganze funktioniert wie das Kommando tempList mit dem Unterschied, dass der Namen des Templates angegeben werden kann.

In der Datei wird der Name des Templates in der Zeile Entities eingegeben, identisch wir(?) der Name einer Komponente.
:<code>set hm tempListTmpl -f hkWZ wzSommer restore tempListFile.cfg </code>
Alle Thermostate mit hkWZ im Namen wird die Templiste, die im File tempListFile.cfg unter entity "wzSommer" abgelegt ist überschrieben. Wie bei tempList restore wird auch hier nur geschrieben, wenn ein Unterschied erkannt wird.

=== Registersätze kopieren ===
HMInfo erlaubt das Kopieren von Register-Listen. Über Register wird ein HM-Gerät eingestellt und die Register sind in Listen gruppiert. Die Reaktion und das Verhalten eines Aktors auf einen Trigger eines Sensors wird in dem Registersatz zu diesem Peer komplett beschrieben.
Durch die Möglichkeit einen solchen Registersatz im Device zu kopieren kann man das Verhalten, das man für einen Knopf/Sensor festgelegt hat identisch in einen zweiten kopieren.
HMInfo geht davon aus, dass die vom Gerät gelesene Konfiguration vor dem Kommando aktuell und komplett ist.
set hm cpRegs Licht1:FB3_Btn2 Licht3:FB1_Btn4
set hm cpRegs Licht2:FB3_Btn2 Licht2:FB1_Btn4
set hm cpRegs Licht4:FB3_Btn2 Licht4:FB5_Btn2
Die obigen Beispiele bewirken der Reihe nach:
Duplizieren das Verhalten, das Fernbedienungsknopf 2 der Fernbedienung 3 bei Aktor Licht1 hervorruft auch nach Licht3 für Fernbedienungsknopf4 der Fernbedienung 1.
Duplizieren das Verhalten, das Fernbedienungsknopf 2 der Fernbedienung 3 bei Aktor Licht2 hervorruft auch nach Licht2 (selber Aktor) für Fernbedienungsknopf4 der Fernbedienung 1.

== Web Einträge und Readings ==
Readings und Internals von HMInfo bieten eine Zusammenfassung des Zustands aller HM Komponenten. Diese sind in Fehler '''ERR' , Warnungen '''W_''' und Information '''I_''' untergliedert. Die Prüfung und Erneuerung der Zähler und Werte wird mit:
:<code>set hm update </code>
erreicht. Mit dem Attribut autoUpdate kann man es automatisch regelmäßig starten.

=== Fehlermeldungen ===
Als Fehler erkannte Zustände werden in Variablen beginnend mit '''ERR''' dargestellt. Erfasste Fehler sind kritische RSSI Werte und Protokoll-/Übertragungsfehler. Ausserdem kann man im Attribut sumERROR eintragen, welche Readings zu einer Fehlermeldung führen sollen. Eingetragen werden:
Reading:<gutwert>. Wenn ein Reading mit einen anderen als dem "gutwert" gefunden wird, wird dies alarmiert.
Beispiel:
:<code>battery:ok </code>
hat eine HM Komponente ein Reading "battery" und dieses hat einen anderen Wert als "ok" wird dies alarmiert.
In den Readings von HMInfo würde im Feherfall
internal:
ERR_names <devicename1>,<devicename2>
Readings:
ERR_battery low:2

Der default aller Error-meldungen ist
battery:ok,sabotageError:off,powerError:ok,overload:off,overheat:off,reduced:off,motorError:no,error:none,uncertain:yes,smoke_detect:none,cover:closed

Diese Zusammenfassung der Fehlermeldungen könnte man nutzen, um über notify einen Alarm auszulösen oder eine E-Mail zu senden.

=== Warnungen===
Hierzu gehören Wiederholungen von Nachrichten (nicht aber Abbrüche, das sind Fehler). Es wird auch ausstehendes Lesen der Konfiguration, das durch autoReadReg getriggert wird, hier angezeigt.

=== Statusmeldungen ===
Analog zu den Fehlermeldungen kann man mit dem Attribut sumStatus gewisse Readings zählen lassen. Beipiel wäre
attr HM sumStatus motor
HMInfo zeigt in dem Reading I_sum_motor dann an, welcher Inhalt des Readings "motor" wie oft gefunden wurde. Es könnte so aussehen
stop:on:4;stop:1;
Vier Komponenten stehen auf motor: stop:on und eine steht auf motor: stop

Das Internal '''I_HM_IOdevices''' zeigt die von HM Komponenten genutzten IOs und deren State.

== Infos ==
get hm models [-f <regexp>]
get hm models
get hm models -f remote
get hm models -f HM_RC
Zeigt alle in FHEM unterstützten Modelle und deren wesentliche Parameter. Man kann mittels regexp die Liste filtern.

get hm param [<typefilter>] [-f <nameFilter>] parameter1 parameter2
get hm param -d IODev DEF model
get hm param -c -f Rollo peerList
man kann sich listen von Parametern anzeigen lassen

get hm register [<typefilter>] [-f <nameFilter>]
zeigt Register in tabellarischer Form.

get hm peerXref[<typefilter>] [-f <nameFilter>]
gibt an, wer mit wem gepeert ist

== Rücksetzen von Variablen und Zählern ==
set HM clear [<typeFilter>] [Protocol|readings|msgStat|register|rssi]
*register löscht alle Register-readings
*readings löscht '''alle''' readings
*Protocol löscht alle Protokol-einträge, pending Kommandos und Protokoll-fehler.
*rssi löscht alle ermittelten RSSI Werte
*msgStat setzt die Message Statistik zurück

== Filter ==
Kommandos in HMInfo wirken auf alle HM Komponenten. Man kann dies mit Hilfe der Filter einschränken. Zum einen gibt es '''modelsFilter''', womit man nur devices, nur channels, nur virtuelle Entities bearbeiten kann
set <name> <cmd> '''[-dcasevi]''' [params]
entities according to list will be processed"
d - device :include devices"
c - channels :include channels"
i - ignore :include devices marked as ignore"
v - virtual :supress fhem virtual"
p - physical :supress physical"
a - aktor :supress actor"
s - sensor :supress sensor"
e - empty :include results even if requested fields are empty"

Ein auf '''-d''' gefiltertes Kommando wird nur auf devices, nicht aber auf channels angewendet.

Dann gibt es noch den '''nameFilter''', mit dem mittels regexp auf den Namen der Entity gefiltert werden kann
-f Rollo # alle Entities mit Rollo im Namen
-f ^Rollo$ # nur Entity mit Namen "Rollo"
-f Rollo$ # nur Entity deren Name auf Rollo endet

Die Filter kann man kombinieren mit
-c -f Rollo # alle Kanäle mit Rollo im Namen

Beispiel:
Zeige mir die Parameter IODev und room der Devices mit Rollo im Namen
set hm param -d -f Rollo IODev room

== Attribute ==
* '''autoArchive ''' automatisch archivieren von vollständigen Konfigurationen.
* '''autoUpdate''' startet regelmäßig das Komamndo "update". Die Wiederholzeit wird eingestellt mit hh:mm. Sinnvoll erscheint z.B. alle 5 Minuten, also 00:05.
* '''configDir''' bietet die Möglichkeit, ein Verzeichnis zu definieren, in das HMInfo Dateien ablegen und von dem es die Dateien lesen wird. Default ist fhem_root.
* '''configFilename''' legt einen default Namen fest, der bei save und archive genutzt wird. Default ist regSave.cfg.
* '''hmAutoReadScan''' zeitinterval in Minuten, in denen CUL_HM prüft, ob offene autoRead bereitstehen und die IOs die Kapazität haben. Default ist 4 min.

== Quellen ==
* Thread [http://forum.fhem.de/index.php?topic=11035.0 HMinfo] im Fhem Forum
* Thread [http://forum.fhem.de/index.php/topic,20119.0.html HMINfo, Intention, Sinn und Zweck] im Fhem Forum

[[Kategorie:HomeMatic Components]]
[[Kategorie:HOWTOS]]

Diskussion:Fronthem

2014-12-30T20:57:17Z

SirUli: Die Seite wurde neu angelegt: „Evtl könnte noch erläutert werden was ein GAD ist? --~~~~“

Evtl könnte noch erläutert werden was ein GAD ist?
--[[Benutzer:SirUli|SirUli]] ([[Benutzer Diskussion:SirUli|Diskussion]]) 20:57, 30. Dez. 2014 (UTC)

Kindle Display

2014-10-03T11:01:01Z

SirUli: /* Cron setting (optional) */

This article shows how to configure a Amazon Kindle eBook-Reader as a information display for fhem. Use this manual at your own risk. Jailbreaking a Kindle is quite easy but there is no guarantee for breaking the system. 
I will show how to configure it with the FileReplacer.pm from Stefan. The "old" method with the special function in MyUtils is not part of this article.

'''NOTE: This Article is not yet finished! This note will be removed once i think it's okay ;) 
As long as I'm working on it, this information will be shown.'''

All of the information shown below is collected from the fhem-forum [http://forum.fhem.de/index.php/topic,21821.0.html fhem-Forum]. Many thanks to everybody who participated on the development of this information to get it done.Special thanks to "alex" and "stefan" from the board. Further information is from the [http://www.mobileread.com mobileread board].

=Hardware requirements=
==Kindle Touch / Paperwhite / Paperwhite 2==
You can use Kindle Touch / Paperwhite / Paperwhite 2 without any limitations.
==Kindle 4==
For setting this up on the Kindle 4 (with the 5-way button) you need some more configuration work but it's also working. Addidional tasks for this version are shown down below.

=Prerequisites=
==fhem and server configuration==
===Server configuration===
Not sure if still needed, but just for in case it is, install imagemagick on your linux system. 
:<code>apt-get install imagemagick</code>
That's it :)
===fhem configuration===
First you need a svg-template. You can find one in the first posting on the [http://forum.fhem.de/index.php/topic,21821.0.html fhem-Forum] thread. In the template just replace the data with some placeholder you like. Later this placeholder is found via a regular expression and replaced by your data. 
For example, you can set XYZ at the place where the first temperature should be shown and ABC for the first humidity value. 
If you want to edit the template you can use the free software [www.inkscape.org/de/ Inkscape]. For more information about generating SVGs for fhem please refer to this article [http://www.fhemwiki.de/wiki/Icons Icons]. Most important information is to save the SVG as a "normal SVG" and not as an inkscape SVG. 
For the Kindle Paperwhite the resolution of the SVG must be 758 x 1024 for the Kindle 4 version use 600x800. This is mandatory. Wrong scaled images won't be displayed on the Kindle. Copy the Kindle_Template.svg to <nowiki>/opt/fhem/www/images/</nowiki>. 
Download and install the [http://forum.fhem.de/index.php/topic,21821.msg200310.html#msg200310 FileReplacer.pm from fhem Forums], save it to /opt/fhem/FHEM and load the module. You can also restart fhem instead. 
All we're doing now is to using the FileReplacer module to read the SVG template, replace a search pattern with our data and saving it. 
:<code>define kindledisplay FileReplacer /opt/fhem/www/images/template1.svg /opt/fhem/www/images/status1.svg 60</code>
:<code>attr kindledisplay DoPNG 1</code>
:<code>attr kindledisplay UTF8-Encode 1</code>
:<code>attr kindledisplay room Display</code>

DoPNG enabled the generation from SVG to PNG. UTF8-Encode is needed to support special characters. 
Now just create your mappings:
:<code>attr kindledisplay Regex1 XYZ </code>
:<code>attr kindledisplay Expr1 sprintf("%.1f", ReadingsVal("Sensor1", "Temp1", 0)) </code>
:<code>attr kindledisplay Regex2 ABC </code>
:<code>attr kindledisplay Expr2 sprintf("%.1f", ReadingsVal("Sensor1", "Hum1", 0)) </code>
And so on... :) The FileReplacer will replace the pattern XYZ with the ReadingsVal from Sensor1. 
Now check if the PNG is created [http://your-fhem-ip:8083/fhem/www/images/status1.png http://your-fhem-ip:8083/fhem/www/images/KindleDisplay.png]. If so, be happy, the first part is done! 
If you want to change readingVals to something in your language you can try using it like this:
:<code>attr kindledisplay Expr11 (ReadingsVal("XY", "Reading", "off") eq "on" ? "An" : "Aus")</code>
=== Templates ===
You can find my templates here: [http://forum.fhem.de/index.php?topic=21821.msg202396#msg202396 fhem Forum]. Feel free to use and modify.

=Modifying the Kindle=
To prevent from error messages like "your Kindle is no longer registered as a test Kindle..." please make sure your Kindle is connected to a valid Amazon Account. 
We need to download some software to install it on the Kindle. 
Please download it from [http://www.mobileread.com/forums/showthread.php?t=88004 Mobileread Forums] 
* Kindle Jailbreak [http://www.mobileread.com/forums/showthread.php?t=88004 Mobileread Forums]
* MKK Mobileread Kindlet Kit [http://www.mobileread.com/forums/showthread.php?t=233932 Mobileread Forums]
* KUAL [http://www.mobileread.com/forums/showthread.php?t=203326 Mobileread Forums]
* Screensavers Hack [http://www.mobileread.com/forums/showthread.php?t=88004 Mobileread Forums]
* OnlineScreenSaver [http://www.mobileread.com/forums/showthread.php?t=236104 Mobileread Forums]

* for Kindle 4 only: USBNETWORK [http://www.mobileread.com/forums/showthread.php?t=88004 also Mobileread Forums]
 Always use the newest version and look for one who fits to your Kindle (e.G. K4).

==Jailbreaking the Kindle==
Don't worry. This sounds more hard and dangerous than it is in fact. It's just a few steps to have full access to your Kindle.
=== Kindle Touch/Paperwhite ===
* Download the kindle-jailbreak-0.12.N.zip file, and unpack it. In there, you'll find some .bin files, and a src directory.Leave the directory alone, and upload the correct Update_*_install.bin file for your kindle & FW version to the root directory of your Kindle.
 
* Now, eject & unplug your Kindle, and go to [HOME] -> [MENU] > Settings -> [MENU] > Update Your Kindle. It should be quick. (And, on FW 2.x only, it should FAIL (With a U006 error, in the bottom left corner of the screen). It's completely normal, intended, and harmless).
 
And that's it, your Kindle is now ready to install custom hacks! 
(Quoted from http://www.mobileread.com/forums/showthread.php?t=88004)

=== Kindle 4 / Universal method ===

* Download and unzip the jailbreak.
* Plug in the Kindle and copy the data.tar.gz & ENABLE_DIAGS files plus the diagnostic_logs folder to the Kindle's USB drive's root
* Safely remove the USB cable and restart the Kindle (Menu -> Settings -> Menu -> Restart)
* Once the device restarts into diagnostics mode, select "D) Exit, Reboot or Disable Diags" (using the 5-way keypad)
* Select "R) Reboot System" and "Q) To continue" (following on-screen instructions, when it tells you to use 'FW Left' to select an option, it means left on the 5-way keypad)
* Wait about 20 seconds: you should see the Jailbreak screen for a while, and the device should then restart normally
* After the Kindle restarts, you should see a new book titled "You are Jailbroken", if you see this, the jailbreak has been successful.

==Installing additional software==

=== MKK ===
The Mobileread Kindlet Kit (MKK) is used to execute custom Kindlets (programs) on the Kindle. 
Download the software from here: [http://www.mobileread.com/forums/showthread.php?t=233932 MKK] 
Unzip the folder and copy the .bin file to the root directory of your kindle. Please note that you need to install the Kindle matching version (e.g. K4 = Kindle 4 with 5-way-button). 
On the Kindle goto Menu -> Settings -> Menu -> Update your Kindle. 
After the update it is installed.

=== KUAL ===
The Kindle Unified Application Launcher (KUAL) running applications on the Kindle. 
Download it from here: [http://www.mobileread.com/forums/showthread.php?t=203326 KUAL] 
Unzip the folder and copy the matching .azw2 file to the documents directory of your kindle. 
 
(K2, DX, K3, K4) 
Put KUAL-KDK-1.0.azw2 in documents folder. 
Run it by clicking new kindlet (book) document in your list. 
 
(Touch, PaperWhite) 
Put KUAL-KDK-2.0.azw2 in documents folder. 
Run it by clicking icon. 

=== Backdoorlock ===
This is used to prevent from getting automated updates which could remove the JailBreak. 
Download from here: [http://www.mobileread.com/forums/showthread.php?t=205666 Backdoorlock] 
Unzip the folder and copy the .bin file to the root directory of your kindle. Please note that you need to install the Kindle matching version (e.g. K4 = Kindle 4 with 5-way-button).
On the Kindle goto Menu -> Settings -> Menu -> Update your Kindle.
After the update it is installed.

=== ScreenSavers Hack ===
The ScreenSavers Hack let you show custom screen savers on the kindle. 
Download the file: [http://www.mobileread.com/forums/showthread.php?t=88004 ScreenSaver Hack] 
Install the corresponding .bin file as the others before and use the "update your kindle" function to install it. 
After the installation you will find a directory called "linkss" in the Kindle root. Here open the screensavers dir and delete all images.

=== Online ScreeSaver ===
This application copies the fhem-PNG from your fhem-server to the ScreenSavers hack.
Just download the application from [http://www.mobileread.com/forums/showthread.php?t=236104 here], extract the file and copy the folder into the extensions directory. 
Now you have to edit the config.sh file up to your need. 
'''NOTE''' Use a linux/unix compatible editor (like notepad++) only! 
You need to enter the image URL, the update interval and the schedule for the updates. That's all.

==== Online Screen Saver - Kindle 4 Special Tasks ====
To get it running on a Kindle 4 you need to change some lines in the OnlineScreenSaver files. 
You can find a .diff file for the changes here: [http://forum.fhem.de/index.php/topic,21821.msg190911.html#msg190911 fhem forum] 
No idea what to do with this file? It just shows you in which lines changes were made and what was changed. I recommend to edit all the files shown in the diff-file locally and then copy the whole package to the kindle first.

==Kindle 4 additional tasks==
As your Kindle 4 needs some more attention to get it done, please find the steps here:

=== USB Network Hack ===
This hack is used to get SSH/Telnet Access to your Kindle. We need this on Kindle 4 to change some settings on the system. 
Download and install the kindle-usbnetwork file from here: [http://www.mobileread.com/forums/showthread.php?t=88004 USBNETWORK] 
I'm sure you know what to do in the meantime ;-) 
After that, activate the USBNetwork via KUAL and connect the Kindle via USB.

=== Connecting to the Kindle ===
Before you can connect you need to install the RNDIS driver. [https://github.com/ev3dev/ev3dev/wiki/Setting-Up-Windows-USB-Ethernet-Networking Here you can find] a very good "HowTo" to do this. Note that the IP-Addresses you need to configure are different then addresses used in the example. Your RNDIS Interface needs to have 192.168.15.201 configured, the Kindle uses 192.168.15.244 on this interface. 
Don't wonder you cannot ping the Kindle! 
Now you can use a ssh-client like putty to connect to the Kindle. Telnet is also an option but only when WiFI mode is disabled. So better forget about it. Success? Great job!
=== Changing the "sleep settings" ===
After you connected to the Kindle you will be asked for a password. Login with root and blank password. Should work. 
Now we need to make the filesystem writeable:
:<code>mntroot rw</code>
Changing the root password:
:<code>passwd</code>
Changing the timeouts:
:<code>cd /etc/kdb.src/yoshi/system/daemon/powerd/</code>
Edit the t1_timeout with the editor "vi" and change the last line to 200. 
Same for the t2_timeout but here we enter 200000 in the last line. 
These values are setting the "sleep" counters on the Kindle. Unfortunately this will lower the battery faster then normal so I recommend to have the display in a docking station. 

=== Cron setting (optional) ===
In my case that all didn't really work for me so i decided to run the onlinescreensaver update script via cron:
:<code>vi /etc/crontab/root</code>
Add the following line at the bottom. */5 means every 5 minutes.
:<code>*/5 * * * * /mnt/us/extensions/onlinescreensaver/bin/update.sh</code>
:<code>/etc/init.d/cron restart</code>
Setting back filesystem in read-only mode
:<code>mntroot ro</code>
That's it for me. Not working? Ask and look here for help: [http://forum.fhem.de/index.php/topic,21821.0.html FHEM Forum]

=Examples and Pictures=
[[Datei:KindleDisplay.jpg|200px]] Kindle Display Example on Kindle 4
----

[[Kategorie:HOWTOS]]

Squeezebox

2014-08-07T12:12:35Z

SirUli: Added Link to Forum

Um eine Logitech Squeezebox (ein Netzwerk-Musikplayer) fernzusteuern muss diese mit einem Logitech Media Server verbunden sein. (Weitere Informationen wie man die Squeezebox mit einem Server verbindet findet man auf [http://www.mysqueezebox.com/download MySqueezeBox.de].)
 '''Hinweis:''' Seit 12/2013 gibt es ein Modul zur Steuerung von Squeezeboxes (98_SB_PLAYER). Bitte im [http://forum.fhem.de/index.php/topic,17667 Forum] den aktuellen Stand prüfen. 

Getestet wurde das folgende auf einer FB7390 mit FHEM [[AVM Fritz!Box]].

Einfach in ein Utils Skript ([[99 myUtils anlegen]]) folgende Funktion einfügen:

<nowiki>sub squeezebox($) {
my ($state) = @_;
if ($state eq "on")
{
system("wget -O /dev/null -q http://[SqueezeboxServerIP]:[SqueezeboxServerPort]/status.html?p0=play");
}
else
{
system("wget -O /dev/null -q http://[SqueezeboxServerIP]:[SqueezeboxServerPort]/status.html?p0=power&p1=0");
}
}</nowiki>
Ein Aufruf erfolgt mit <code>{ squeezebox("on") }</code> oder <code>{ squeezebox("off") }</code>

= Hinweise =
* In dem Skript muss die IP sowie der Port ersetzt werden. Der Standardport ist 9000.
* Es gibt noch weitere Befehle um die Squeezebox zu steuern (Lautstärke erhöhen, Pause, Stop,...)
** Lautstärke setzen: <code>http://[SqueezeboxServerIP]:[SqueezeboxServerPort]/status.html?p0=mixer&p1=volume&p2=YY</code>, wobei YY die Lautstärke auf einer Skala von 0-100 ist.
* Falls mehrere Squeezeboxen mit dem Server verbunden sind, kann mittels Parameter <code>&player=XX%3AXX%3AXX%3AXX%3AXX%3AXX</code> eine spezielle verwendet werden. XX= MAC-Adresse der Squeezebox.
* Mehr Befehle können aus den Links der Statusseite ausgelesen werden: <code>http://[SqueezeboxServerIP]:[SqueezeboxServerPort]/status.html</code>

= Quelle =
Grundlagen in folgendem Beitrag entdeckt: [http://www.squeezebox-forum.de/viewtopic.php?f=13&t=1521#p12286 [1]]
[[Kategorie:Code Snippets]]

Apache Authentication Proxy

2014-06-26T23:35:52Z

SirUli:

Um den Zugriff auf FHEMWEB etwas sicherer zu machen, kann man den Webzugriff über einen Apachen laufen lassen. Dies ist ein kurzes Rezept, um Zugriffe auf FHEMWEB über einen Apachen authentifizieren zu lassen. Erstellt wurde es auf Debian Squeeze, sollte aber auch mit Ubuntu funktionieren.

<nowiki>apt-get install apache2 libapache2-mod-proxy-html</nowiki>

Step 1) FHEMWEB sollte nur noch auf dem Loopback lauschen, also kein 'global' Attribut in der Definition in fhem.cfg

<nowiki>define WEBS FHEMWEB 8084</nowiki>

Step 2) die folgenden Apache2 Module müssen aktiviert sein: mod_proxy + mod_proxy_http

<nowiki>a2enmod proxy
a2enmod proxy_http</nowiki>

Step 3) neue Datei /etc/apache2/conf.d/fhem:

Diese Konfiguration sorgt dafür, dass alle Anfragen unter /fhem weiter nach [http://localhost/fhem http://localhost/fhem] geleitet werden. Zusätzlich wird eine Basic-Authentifizierung eingeschaltet. Die Benutzerdatenbank ist dann in /etc/fhem-htpasswd zu finden.

<nowiki><Location /fhem>
# ProxyPass/ProxyPassReverse leitet HTTP requests auf eine andere URL um
ProxyPass http://localhost:8084/fhem
ProxyPassReverse http://localhost:8084/fhem
# ProxyHTMLURLMap passt Links im HTML/JavaScript Source an
ProxyHTMLURLMap / /fhem/
ProxyHTMLURLMap /fhem/ /fhem/
AuthType Basic
AuthName "Password Required"
AuthUserFile /etc/fhem-htpasswd
Require valid-user
Order deny,allow
Allow from all
</Location></nowiki>

Step 4) Benutzer-Datenbank in /etc/fhem-htpasswd anlegen

<nowiki># -c -> create file
# -s SHA encryption
htpasswd -c -s /etc/fhem-htpasswd <username>
# add more users with
htpasswd -s /etc/fhem-htpasswd <username></nowiki>

Step 5) Apache neu starten

<nowiki>invoke-rc.d apache2 reload</nowiki>

Fertig. FHEM ist jetzt über [http://server/fhem http://server/fhem] erreichbar. Alle Zugriffe müssen aber erst mit Benutzername + Passwort freigeschaltet werden.

Falls nach dem Neustart des Apache folgende Fehlermeldung kommt:

<nowiki>Invalid command 'ProxyHTMLURLMap', perhaps misspelled or defined by a module not included in the server configuration
Action 'configtest' failed.
The Apache error log may have more information.</nowiki>

fehlt das Paket libapache2-mod-proxy-html. Einfach mit

<nowiki>apt-get install libapache2-mod-proxy-html</nowiki>

nachinstallieren.

[[Kategorie:HOWTOS]]

MAX!CubeMigrationToFHEM

2014-06-15T16:57:37Z

SirUli: Executed the tutorial and found a few smaller mistakes until now.

== WORK IN PROGRESS / NOT FINISHED: HowTo Migrate from MAX!Cube to fhem ==
'''Summary:''' This pages describes the steps required to migrate a house installation from MAX!Cube solution (using a Cube and MAX! Software from ELV/EQ-3) to fhem on a Raspberry Pi combined with a CUL. The benefit of such a migration is to gain better logfiles, to get graphs (Desired vs. Actual temperature and Valve position) and more reliable software.

----

=== Initial situation ===
The appartment has 125 sqm and five rooms (child 1, child 2, livingroom, bedroom, working room), one bathroom, a kitchen and a toilette. Each room has one heater below the window, the living room has two heaters. Two rooms require multiple window shutter contacts: bedroom and living room due to the amount of windows. MAX!Cube software is running since a year controlling all heaters, all windows and in combination with one wall thermostat in the living room and one ECO-switch at the main door to bring the full house to ECO mode when leaving.

=== Desired situation ===
MAX!Cube software was unstable and the update to v1.3.10 triggered the decision to move to a new setup: keep the MAX system, but control it via fhem. Have the ability to add more sensors, more actors from other brands than MAX (looking for Homematic due to the amount of different sensors and 1-Wire to avoid the unreliable radio transmission). Have the ability to better see what the system is doing (logfiles) and graph it out (diagrams for each room). Get some more flexibility for home-cinema setup, for light controls, etc. Increase the ''WAF'' (Women's Acceptance Factor) for the wife who was complaining about the MAX!Cube solution.

=== Procurement list ===
While it is possible to use the existing MAX Cube with fhem certain features would not be available. Therefore I decided to go with a Rasperry Pi and a CUL. Here is the shopping list:

# Rasperry Pi from G3 with cooling kit for enhanced reliability ([http://www.amazon.de/pi3g-Raspberry-Betriebssystem-Coolkit-installiert/dp/B00CB1C96E])
# 32 GB SDHX Card Class 10 from SANDisk
# CC1101-USB-Lite 868MHz ([http://shop.busware.de/product_info.php/cPath/1/products_id/29]) with 36cm antenna (+8dBi) for MAX protocol
# 8 Channel 1-Wire Daughterboard without RTC with some sensors for testing ([http://www.sheepwalkelectronics.co.uk/product_info.php?cPath=22&products_id=33])

(Note: The 1-Wire board has not yet arrived and may not fit into the supplied case - but I am too lazy to attach the cooling modules myself).

=== Installation of Raspberry Pi ===
Please follow one of the many documentations how to install Linux on your Raspberry Pi - a good starting point would be [http://www.raspberrypi.org/downloads]. I tried to install Raspbian using the advanced method of copying the image directly to the SD-card but it did not worked out well as many perl/python-modules were missing, had to be identified and installed to use fhem.

For my second approach I used the provided image from busware.de, which also includes drivers for their COC daughter board. Available for download here [http://files.busware.de/RPi/README.kernel]. Unfortunately this has a slightly outdated fhem installation, but works for all other parts. Please note that there is no HDMI output enabled during the first boot. Just use <code>ssh pi@fhem</code> or <code>ssh pi@<IP-address></code> to login and use raspi-config for initial setup of passwords, timezone and disk size. Do not forget to install an ntp-client using <code>apt-get install ntp-client</code>, an editor of your choice (I selected vim <code>apt-get install vim</code>) and edit <code>/etc/ntp.conf</code> to adjust ntpservers and select a country-pool (see [http://www.pool.ntp.org/zone/europe]).

==== Upgrade of fhem ====
Once the initial setup is completed reboot your Raspberry and login into fhem using your web browser at <code><IP-address>:8083</code>. Enter the <code>upgrade</code> command to upgrade your fhem-installation to the latest revision. Use <code>shutdown restart</code> to start the new code version.

==== CUL firmware flashing ====
Login using ssh and become root using <code>su -</code> or <code>sudo -i</code> to flash the empty CUL. This only works as root from the directory <code>/opt/fhem</code> using the command string

dfu-programmer atmega32u4 erase && dfu-programmer atmega32u4 flash ./FHEM/CUL_V3.hex && dfu-programmer atmega32u4 start

If the application dfu-programmer is not installed, install using <code>apt-get install dfu-programmer</code>.

=== Migration Preparation ===
ADD ME
==== Documentation ====
If you have not done it before now it's a good start to document your existing MAX!Cube solution. Room for room write each device, the MAX address, location and intended profile into an Excel file. It could look like

Roomname DeviceName DeviceAddress Location WeekDayProfile WeekendProfile Dependencies

where WeekDayProfile and WeekendProfile only make sense for actors like Heaters within the MAX-solution. Dependencies can indicate Window Contacts to Heater actors or Wall Thermostat to Heater actors. Document as well your current heating profile configuration with MAX!Cube.

Make a backup.

==== Selecting the right time of the year ====
ADD ME
==== What do you want to archive ====
ADD ME
=== Migration Execution ===
ADD ME
==== MAX!Cube Configuration ====
ADD ME
==== fhem Configuration ====
===== CUL Setup =====
First step to setup fhem is to define the protocol and adaptor fhem should use. You need one CUL for each protocol (e.g. FS20, Homematic and MAX) as the CUL can listen to the same frequency, but does not understand multiple protocols. The <fhem.cfg> comes pre-installed with some default configuration. At the end add

#### CUL Definition, MAX!Cube
define CUL0 CUL /dev/ttyACM0@9600 1234
attr CUL0 rfmode MAX
define cm CUL_MAX 123456

and save fhem.cfg. After a reload fhem will start to ''listen'' to MAX-commands sent by your still active MAX-Cube.

===== Find MAX devices =====
As each MAX device communicates with the MAX!Cube over the time of two-three days, fhem will detect in use MAX-devices like Heaters, Thermostats and WindowsContacts (but not the ECO wall switch) and create alias definitions within the fhem.cfg file. To get all devices including addresses in use let fhem listen for a two-three days while the MAX!Cube is still in use and working.

===== Identify MAX devices =====
Login into MAX!Cube using one browser window (or tab) and into fhem using a second browser window (or tab). For each room change the temperature within the MAX!Software to an unsual value (like 27.5), change to the fhem window and identify the change in fhem. This allows you to detect one heater actor by the other.

To identify the Window Contacts just open one window, swap to fhem and see which contact reports an ''Open'' status.

===== Define alias names =====
Open a third browser window (or tab), login to fhem webpage and select Edit Files, fhem.cfg. You can now add the alias by adding lines like

define MAX_Bathroom_Heating MAX HeatingThermostat 05615b
define MAX_Bathroom_WindowSensor MAX ShutterContact 053767

room by room, one by one. Just identify the fhem-name in the "MAX"-room in fhem and adjust the address (last hex-number in the line).

If you already have meaningfull names in the MAX-Software you can try to use the code from this [http://forum.fhem.de/index.php/topic,19473.msg131095.html#msg131095 forum post] to automaticaly use these as the alias names for all MAX devices.

===== Assigning a room name =====
For better structure create and assign devices of one physical room into one room within fhem. Rooms are managed by the ''attribute'' room for a specific device. Each defined devices require one or more room attributes:

attr MAX_Bedroom_Heating room Bedroom

===== Understanding the setup =====
The rooms are still controlled from the MAX!Cube and MAX-software. fhem only listens and has useable names. fhem does not communicate with the devices and it cannot configure devices. However you have useable and human-understandable names instead of hex-codes.

===== Migration =====
As MAX!Cube will interfere with CUL (both sending the same protocol on the same frequency) and due to the sending restrictions (1%-rule) we need to

# Remove all rooms in MAX!Cube (which deletes the devices in MAX!Cube)
# Reset all heaters and window contacts to factory settings
# Pair the device to fhem
# Define the week heating program
# Define the connectivity between heater and window sensors

Make a backup of your MAX!Cube configuration in case something goes seriously wrong. Have the family out of the house for 1-2 days while you run around to re-pair devices. While resetting the devices the PI-learned heating curves will be lost and the heaters need to adopt again to your house-specific heating curves.

===== Re-setting devices =====
Remove batteries and wait 45 seconds. For

# Heater actors: Press all three buttons at the same time, insert battery until <code>reS</code> is displayed. Press Boost for installation menu
# Window contacts: Press button while inserting battery and keep pressed until LED is flashing again
# ECO-Wallcontact: Press Eco or AUTO button while inserting battery and keep pressed until LED is flashing again
# Wallthermostats: Press "Moon", "OK" and "-" at the same time, then insert the battery [http://www.elv.de/controller.aspx?cid=824&detail=10&detail2=3537]

===== Pairing devices with fhem =====
Enter

set cm pairmode 45

into the command field on top of the fhem page to configure the CUL into pairing mode for 45 seconds. Initiate the pair sequence on the device by:

# Heater actors: Pressing Boost for about 3 seconds until <code>30</code> is displayed. The pairing succeeded when the timer is gone.
# Window contacts: Press button, LED starts flashing. Success is reported by one last long LED signal.
# ECO-Wallcontact: Press one button three seconds, LED starts flashing. Success is reported by one last long LED signal
# Wallthermostat: First click several times "OK" to set a random date and time until you see the temperature again. Then press OK button three seconds until <code>30</code> is displayed. The pairing succeeded when the timer is gone.

==== fhem One-Time Device-specific configuration ====
Certain information about fhem are stored in the fhem.cfg which you can edit using a text editor and ssh or using the webfront. A big other, device-specific part is entered as part of commands into the webfrontend, but not documented and not stored within fhem.cfg. You will end up in a documented, structure information stored in fhem.cfg (like any other UNIX related configuration file in /etc) and a un-documented part which is stored within the devices of your appartment only.

My solution for this was to add the relevant commands into fhem.cfg as ''comments'', so after a multiple month pause on playing with fhem I do still see which commands belonged into which room and what I have done. However if you follow this route is important to understand that changes to these ''comments'' will never take place and change your configuration unless you copy and paste them into the command-field and execute your change.

The information stored in devices and not in fhem.cfg are

# Heating weekProfiles - which temperature you want when
# Associations between WindowContacts and Heaters to detect open windows.

Within the fhem forums you find a longer discussion if windows sensors really make sense. The statement there is as the heaters have a decreasing temperature sensor they are not. It is hard for me to follow this argumentation as:

# The heating water temperature will be impacted when it keep running while windows is open
# The WAF (Women's Acceptance Factor) is lowered as the house should be smart
# You may wish to have open windows longer than 10-15 minutes
# I can document the time of getting fresh air into the rooms (for any discussions with the landlord in a rented appartment)

===== Window Contacts and Heaters =====
To connect a window contact with a heater to decrease the temperature they need to be ''associated'' to each other:

set MAX_Bedroom_WindowSensor1 associate MAX_Bedroom_Heating
set MAX_Bedroom_Heating associate MAX_Bedroom_WindowSensor1

As you can see the associations is called twice for both directions and you need to call both commands for each Window Contact in the room. fhem will ask you in the logfile for each command to press the MAX Window Contact button when you open the Window Contact. If you have (against advice) already configured the graphing you need to disable the graphing to get the command being transmitted.

===== Open Window Temperature =====
Configure the desired Open Window temperature for that room using

set MAX_Bedroom_Heating windowOpenTemperature 5.5

You may have to wait a couple of minutes until the command has been transmitted.

Test your room by opening each Window with a Window Contact, the heater should immediately change temperature in both directions.

===== The Heating Profile =====
Device-specific configuration also includes the weekProfile, e.g. the desired temperature for each day and each hour. The format is quite simple and starts with an implicit 00:00 (midnight) and ends with an implicit 24:00 (midnight next day). In between desired temperatures are specificed interleaving with hours, seperated by ''','''s. Temperature is specific in degrees celsius. Example:

17,06:00,21,20:00,17

will set 17 degrees from midnight to 06:00am, 21 degrees 06:00am to 20:00 (8:00pm) and then again 17 degrees until midnight. Such profiles are defined for each day (Mon, Tue, Wed, Thu, Fri, Sat, Sun) and set with the weekProfile command:

set MAX_Child1_Heating weekProfile Mon 17,05:00,19,06:00,22,07:15,19,15:30,21,19:00,19,21:00,17 Tue 17,05:00,19,06:00,22,07:15,19,15:30,21,19:00,19,21:00,17 Wed 17,05:00,19,06:00,22,07:15,19,15:30,21,19:00,19,21:00,17 Thu 17,05:00,19,06:00,22,07:15,19,15:30,21,19:00,19,21:00,17 Fri 17,05:00,19,06:00,22,07:15,19,15:30,21,19:00,19,21:00,17 Sat 17,06:00,21,20:00,17 Sun 17,06:00,21,20:00,17

Do not attempt to break this line into multiple lines for better reading. Just one single long line. Transmission may take a couple of minutes.

==== Testing and Verifying ====
ADD ME

=== Add-Ons ===
ADD ME
==== Graphs using 99_UtilsMaxScan.pm ====
There is a Wiki-articel how to use the [http://www.fhemwiki.de/wiki/MAX!_Temperatur-Scanner] MAX-Temperature-Scanner with fhem. At the time of writing this article v1.05a has been published.

Few people have published changes to this version within the forum, which enables the use of ECO wall button and multiple WindowShutter contacts.

If you consider to create graphs for your installation your migration (as outlined above) should '''work stable'', e.g.

# week programs for all rooms are active and working
# open windows are detected and the desired temperature is decreased
# you do not face any logfile entries like: <code>CUL_MAX_SendQueueHandler: Not enough credit! credit10ms is 101, but we need 110. Waiting 9 seconds.</code>
# you do not face any logfile entries like: <code>CUL_MAX_SendQueueHandler: Missing ack from 020341 for 0f010403123456020341000e18003655</code>
# you do not plan any changes to week programs any time soon.

Do not '''even think''' about starting to graph out heaters and rooms while migration is still in progress.

Do download the Scanner Module you need to register and login into the forum. The Scanner Module is attached to the post linked at [http://www.fhemwiki.de/wiki/MAX!_Temperatur-Scanner]. Copy this file to <code>/opt/fhem/FHEM</code> and change ownership to fhem.

(Original Articles: [http://forum.fhem.de/index.php/topic,11624.msg114140.html#msg114140] und [http://forum.fhem.de/index.php/topic,11624.msg119519.html#msg119519])

==== ECO-Wallswitch ====
According to an extensive Google search it is currently not possible to group all Heater actors and send a single command to the group to save communication credits.

A workaround is to define a fhem ''structure'' which includes all Heaters, assign it to a new room labelled "House" and add a web control button to fhem:

# Define House to control all Heaters at once
define AllHeaters structure MAX_Child2_Heating MAX_Workingroom_Heating MAX_Child1_Heating MAX_Livingroom_THSensor MAX_Bedroom_Heating MAX_Toilette_Heating MAX_Kitchen_Heating MAX_Bathroom_Heating
attr AllHeaters room House
attr AllHeaters webCmd desiredTemperature

The ECO Wall button has a type PushButton and is easily defined using (you have to update the address of course):

### 9.1 ECO-Wallbutton
define MAX_WallButton MAX PushButton 0521c4

To set all heaters into ECO mode until the AUTO mode is pressed on the button or the AUTO mode is called from the webpage use:

define MAX_HouseECOHeating notify MAX_WallButton:(onoff).* { if ("%EVTPART1" eq "0") { Log(3,"Setting ECO-Mode") && fhem("set AllHeaters desiredTemperature eco");;} else { Log(3,"Setting AUTO-Mode") && fhem("set AllHeaters desiredTemperature auto");;}}

(Original discussion: [http://forum.fhem.de/index.php/topic,17128.msg112191.html#msg112191])

=== Full fhem.cfg file (all rooms) ===
This is the full example of all discussed settings for the specific outlined room. If you want to adopt this setup you need to replace all MAX addresses with the addresses of your devices.

attr global autoload_undefined_devices 1
attr global logfile ./log/fhem-%Y-%m.log
attr global modpath .
attr global motd Remember to set passwords
attr global statefile ./log/fhem.save
attr global userattr MAX_Child2_Heating MAX_Child2_Heating_map devStateIcon devStateStyle icon sortby webCmd
attr global verbose 3

#### Telnet
define telnetPort telnet 7072 global

#### Screen setup
define WEB FHEMWEB 8083 global
attr WEB stylesheetPrefix dark

define WEBphone FHEMWEB 8084 global
attr WEBphone stylesheetPrefix smallscreen

define WEBtablet FHEMWEB 8085 global
attr WEBtablet stylesheetPrefix touchpad

#### Logfile
# Fake FileLog entry, to access the fhem log from FHEMWEB
define Logfile FileLog ./log/fhem-%Y-%m.log fakelog

#### Autocreate
define autocreate autocreate
attr autocreate autosave 1
attr autocreate device_room %TYPE
attr autocreate filelog ./log/%NAME-%Y.log
attr autocreate weblink 1
attr autocreate weblink_room Plots

# Disable this to avoid looking for new USB devices on startup
define initialUsbCheck notify global:INITIALIZED usb create

#### CUL Definition, MAX!Cube
define CUL0 CUL /dev/ttyACM0@9600 1234
attr CUL0 rfmode MAX
define cm CUL_MAX 123456

####
#### Room Definitions
#### Heating Control = MAX
####

## 1.1 Bathroom (Heating Thermostat)
define MAX_Bathroom_Heating MAX HeatingThermostat 05615b
attr MAX_Bathroom_Heating MAX_Child2_Heating AllHeaters
attr MAX_Bathroom_Heating room Bathroom
attr MAX_Bathroom_Heating scanTemp 1
define FileLog_MAX_Bathroom_Heating FileLog ./log/MAX_Bathroom_Heating-%Y.log MAX_Bathroom_Heating
attr FileLog_MAX_Bathroom_Heating icon heizung.0
attr FileLog_MAX_Bathroom_Heating logtype text
attr FileLog_MAX_Bathroom_Heating room MAX

### 1.2 Bathroom (Window Sensor)
define MAX_Bathroom_WindowSensor MAX ShutterContact 053767
attr MAX_Bathroom_WindowSensor room Bathroom
define FileLog_MAX_Bathroom_WindowSensor FileLog ./log/MAX_Bathroom_WindowSensor-%Y.log MAX_Bathroom_WindowSensor
attr FileLog_MAX_Bathroom_WindowSensor logtype text
attr FileLog_MAX_Bathroom_WindowSensor room MAX

### 1.3 One-Time Configuration (only stored in actors, not in fhem.cfg) - commented just to document
# Activate Open Window detection
# set MAX_Bathroom_WindowSensor associate MAX_Bathroom_Heating
# set MAX_Bathroom_Heating associate MAX_Bathroom_WindowSensor
#
# Define Week Profile
# set MAX_Bathroom_Heating weekProfile Mon 17,05:00,19,06:00,22,07:15,21,08:30,17,19:00,21,20:45,17 Tue 17,05:00,19,06:00,22,07:15,21,08:30,17,19:00,21,20:45,17 Wed 17,05:00,19,06:00,22,07:15,21,08:30,17,19:00,21,20:45,17 Thu 17,05:00,19,06:00,22,07:15,21,08:30,17,19:00,21,20:45,17 Fri 17,05:00,19,06:00,22,07:15,21,08:30,17,19:00,21,20:45,17 Sat 17,06:00,21,10:00,19,19:00,21,20:45,17 Sun 17,06:00,21,10:00,19,19:00,21,20:45,17
#
# Temperatur Scanner (Graphical)
# attr MAX_Bathroom_Heating scanTemp 1
# attr MAX_Bathroom_Heating userReadings onlyAutoMode { return "1";;}
# attr MAX_Bathroom_Heating userReadings watchShutter { return "MAX_Bathroom_WindowSensor";;}
#
# WindowOpenTemperature (4.5 = OFF, No Window Detection)
# set MAX_Bathroom_Heating windowOpenTemperature 5.5

### 2.1 Bedroom (Heating Thermostat)
define MAX_Bedroom_Heating MAX HeatingThermostat 020341
attr MAX_Bedroom_Heating MAX_Child2_Heating AllHeaters
attr MAX_Bedroom_Heating room Bedroom
attr MAX_Bedroom_Heating scanTemp 1
attr MAX_Bedroom_Heating userReadings onlyAutoMode { return "1";;}
define FileLog_MAX_Bedroom_Heating FileLog ./log/MAX_Bedroom_Heating-%Y.log MAX_Bedroom_Heating
attr FileLog_MAX_Bedroom_Heating icon heizung.0
attr FileLog_MAX_Bedroom_Heating logtype text
attr FileLog_MAX_Bedroom_Heating room MAX

### 2.2 Bedroom (Window Sensor)
define MAX_Bedroom_WindowSensor1 MAX ShutterContact 053fdd
attr MAX_Bedroom_WindowSensor1 room Bedroom
define FileLog_MAX_Bedroom_WindowSensor1 FileLog ./log/MAX_Bedroom_WindowSensor1-%Y.log MAX_Bedroom_WindowSensor1
attr FileLog_MAX_Bedroom_WindowSensor1 logtype text
attr FileLog_MAX_Bedroom_WindowSensor1 room MAX

### 2.3 One-Time Configuration (only stored in actors, not in fhem.cfg) - commented just to document
# Activate Open Window detection
# set MAX_Bedroom_WindowSensor1 associate MAX_Bedroom_Heating
# set MAX_Bedroom_Heating associate MAX_Bedroom_WindowSensor1
#
# Define Week Profile
# set MAX_Bedroom_Heating weekProfile Mon 17,05:00,19,06:00,21,07:15,17,19:00,19,21:00,17 Tue 17,05:00,19,06:00,21,07:15,17,19:00,19,21:00,17 Wed 17,05:00,19,06:00,21,07:15,17,19:00,19,21:00,17 Thu 17,05:00,19,06:00,21,07:15,17,19:00,19,21:00,17 Fri 17,05:00,19,06:00,21,07:15,17,19:00,19,21:00,17 Sat 17,07:00,19,09:00,21,10:00,17 Sun 17,07:00,19,09:00,21,10:00,17
#
# Temperatur Scanner (Graphical)
# attr MAX_Bedroom_Heating scanTemp 1
# attr MAX_Bedroom_Heating userReadings onlyAutoMode { return "1";;}
# attr MAX_Bedroom_Heating userReadings watchShutter { return "MAX_Bedroom_WindowSensor1";;}
#
# WindowOpenTemperature (4.5 = OFF, No Window Detection)
# set MAX_Bedroom_Heating windowOpenTemperature 5.5

### 3.1 Child 1 (Heating Thermostat)
define MAX_Child1_Heating MAX HeatingThermostat 05034f
attr MAX_Child1_Heating MAX_Child2_Heating AllHeaters
attr MAX_Child1_Heating room Child1
attr MAX_Child1_Heating scanTemp 1
attr MAX_Child1_Heating userReadings onlyAutoMode { return "1";;}
define FileLog_MAX_Child1_Heating FileLog ./log/MAX_Child1_Heating-%Y.log MAX_Child1_Heating
attr FileLog_MAX_Child1_Heating icon heizung.0
attr FileLog_MAX_Child1_Heating logtype text
attr FileLog_MAX_Child1_Heating room MAX

### 3.2 Child 1 (Window Sensor)
define MAX_Child1_WindowSensor MAX ShutterContact 053f76
attr MAX_Child1_WindowSensor room Child1
define FileLog_MAX_Child1_WindowSensor FileLog ./log/MAX_Child1_WindowSensor-%Y.log MAX_Child1_WindowSensor
attr FileLog_MAX_Child1_WindowSensor logtype text
attr FileLog_MAX_Child1_WindowSensor room MAX

### 3.3 One-Time Configuration (only stored in actors, not in fhem.cfg) - commented just to document
# Activate Open Window detection
# set MAX_Child1_WindowSensor associate MAX_Child1_Heating
# set MAX_Child1_Heating associate MAX_Child1_WindowSensor
#
# Define Week Profile
# set MAX_Child1_Heating weekProfile Mon 17,05:00,19,06:00,22,07:15,19,15:30,21,19:00,19,21:00,17 Tue 17,05:00,19,06:00,22,07:15,19,15:30,21,19:00,19,21:00,17 Wed 17,05:00,19,06:00,22,07:15,19,15:30,21,19:00,19,21:00,17 Thu 17,05:00,19,06:00,22,07:15,19,15:30,21,19:00,19,21:00,17 Fri 17,05:00,19,06:00,22,07:15,19,15:30,21,19:00,19,21:00,17 Sat 17,06:00,21,20:00,17 Sun 17,06:00,21,20:00,17
#
# Temperatur Scanner (Graphical)
# attr MAX_Child1_Heating scanTemp 1
# attr MAX_Child1_Heating userReadings onlyAutoMode { return "1";;}
# attr MAX_Child1_Heating userReadings watchShutter { return "MAX_Child1_WindowSensor";;}
#
# set MAX_Child1_Heating windowOpenTemperature 5.5

### 4.1 Child 2 (Heating Thermostat)
define MAX_Child2_Heating MAX HeatingThermostat 050352
attr MAX_Child2_Heating room Child2
attr MAX_Child2_Heating scanTemp 1
attr MAX_Child2_Heating userReadings onlyAutoMode { return "1";;}
define FileLog_MAX_Child2_Heating FileLog ./log/MAX_Child2_Heating-%Y.log MAX_Child2_Heating
attr FileLog_MAX_Child2_Heating icon heizung.0
attr FileLog_MAX_Child2_Heating logtype text
attr FileLog_MAX_Child2_Heating room MAX
define SVG_FileLog_MAX_Child2_Heating_1 SVG FileLog_MAX_Child2_Heating:SVG_FileLog_MAX_Child2_Heating_1:CURRENT
attr SVG_FileLog_MAX_Child2_Heating_1 room Child2

### 4.2 Child 2 (Window Sensor)
define MAX_Child2_WindowSensor MAX ShutterContact 053fce
attr MAX_Child2_WindowSensor room Child2
define FileLog_MAX_Child2_WindowSensor FileLog ./log/MAX_Child2_WindowSensor-%Y.log MAX_Child2_WindowSensor
attr FileLog_MAX_Child2_WindowSensor logtype text
attr FileLog_MAX_Child2_WindowSensor room MAX

### 4.3 One-Time Configuration (only stored in actors, not in fhem.cfg) - commented just to document
# Activate Open Window detection
# set MAX_Child2_WindowSensor associate MAX_Child2_Heating
# set MAX_Child2_Heating associate MAX_Child2_WindowSensor
#
# Define Week Profile
# set MAX_Child2_Heating weekProfile Mon 17,05:00,19,06:00,22,07:15,19,15:30,21,19:00,19,21:00,17 Tue 17,05:00,19,06:00,22,07:15,19,15:30,21,19:00,19,21:00,17 Wed 17,05:00,19,06:00,22,07:15,19,15:30,21,19:00,19,21:00,17 Thu 17,05:00,19,06:00,22,07:15,19,15:30,21,19:00,19,21:00,17 Fri 17,05:00,19,06:00,22,07:15,19,15:30,21,19:00,19,21:00,17 Sat 17,06:00,21,20:00,17 Sun 17,06:00,21,20:00,17
#
# Temperatur Scanner (Graphical)
# attr MAX_Child2_Heating scanTemp 1
# attr MAX_Child2_Heating userReadings onlyAutoMode { return "1";;}
# attr MAX_Child2_Heating userReadings watchShutter { return "MAX_Child2_WindowSensor";;}
#
# set MAX_Child2_Heating windowOpenTemperature 5.5

### 5.1 Kitchen (Heating Thermostat)
define MAX_Kitchen_Heating MAX HeatingThermostat 06546c
attr MAX_Kitchen_Heating MAX_Child2_Heating AllHeaters
attr MAX_Kitchen_Heating room Kitchen
attr MAX_Kitchen_Heating scanTemp 1
attr MAX_Kitchen_Heating userReadings onlyAutoMode { return "1";;}
define FileLog_MAX_Kitchen_Heating FileLog ./log/MAX_Kitchen_Heating-%Y.log MAX_Kitchen_Heating
attr FileLog_MAX_Kitchen_Heating icon heizung.0
attr FileLog_MAX_Kitchen_Heating logtype text
attr FileLog_MAX_Kitchen_Heating room MAX

### 5.2 Kitchen (Window Sensor)
define MAX_Kitchen_WindowSensor MAX ShutterContact 0612ce
attr MAX_Kitchen_WindowSensor room Kitchen
define FileLog_MAX_Kitchen_WindowSensor FileLog ./log/MAX_Kitchen_WindowSensor-%Y.log MAX_Kitchen_WindowSensor
attr FileLog_MAX_Kitchen_WindowSensor logtype text
attr FileLog_MAX_Kitchen_WindowSensor room MAX

### 5.3 One-Time Configuration (only stored in actors, not in fhem.cfg) - commented just to document
# Activate Open Window detection
# set MAX_Kitchen_WindowSensor associate MAX_Kitchen_Heating
# set MAX_Kitchen_Heating associate MAX_Kitchen_WindowSensor
#
# Define Week Profile
# set MAX_Kitchen_Heating weekProfile Mon 17,05:00,19,06:00,21,07:30,19,19:00,21,20:00,17 Tue 17,05:00,19,06:00,21,07:30,19,19:00,21,20:00,17 Wed 17,05:00,19,06:00,21,07:30,19,19:00,21,20:00,17 Thu 17,05:00,19,06:00,21,07:30,19,19:00,21,20:00,17 Fri 17,05:00,19,06:00,21,07:30,19,19:00,21,20:00,17 Sat 17,07:00,21,20:00,17 Sun 17,07:00,21,20:00,17
#
# Temperatur Scanner (Graphical)
# attr MAX_Kitchen_Heating scanTemp 1
# attr MAX_Kitchen_Heating userReadings onlyAutoMode { return "1";;}
# attr MAX_Kitchen_Heating userReadings watchShutter { return "MAX_Kitchen_WindowSensor";;}
#
# set MAX_Kitchen_Heating windowOpenTemperature 5.5

### 6.1 Livingroom (Heating Thermostats - Two)
define MAX_Livingroom_Heating1 MAX HeatingThermostat 065531
attr MAX_Livingroom_Heating1 room Livingroom
define FileLog_MAX_Livingroom_Heating1 FileLog ./log/MAX_Livingroom_Heating1-%Y.log MAX_Livingroom_Heating1
attr FileLog_MAX_Livingroom_Heating1 icon heizung.0
attr FileLog_MAX_Livingroom_Heating1 logtype text
attr FileLog_MAX_Livingroom_Heating1 room MAX

define MAX_Livingroom_Heating2 MAX HeatingThermostat 06563a
attr MAX_Livingroom_Heating2 room Livingroom
define FileLog_MAX_Livingroom_Heating2 FileLog ./log/MAX_Livingroom_Heating2-%Y.log MAX_Livingroom_Heating2
attr FileLog_MAX_Livingroom_Heating2 icon heizung.0
attr FileLog_MAX_Livingroom_Heating2 logtype text
attr FileLog_MAX_Livingroom_Heating2 room MAX

### 6.2 Livingroom (Window Sensors - Two)
define MAX_Livingroom_WindowSensor_Balcony MAX ShutterContact 0618ce
attr MAX_Livingroom_WindowSensor_Balcony room Livingroom
define FileLog_MAX_Livingroom_WindowSensor_Balcony FileLog ./log/MAX_Livingroom_WindowSensor_Balcony-%Y.log MAX_Livingroom_WindowSensor_Balcony
attr FileLog_MAX_Livingroom_WindowSensor_Balcony logtype text
attr FileLog_MAX_Livingroom_WindowSensor_Balcony room MAX

### 6.3 Livingroom (Wall Thermostat)
define MAX_Livingroom_THSensor MAX WallMountedThermostat 01c93f
attr MAX_Livingroom_THSensor MAX_Child2_Heating AllHeaters
attr MAX_Livingroom_THSensor room Livingroom
define FileLog_MAX_Livingroom_THSensor FileLog ./log/MAX_Livingroom_THSensor-%Y.log MAX_Livingroom_THSensor
attr FileLog_MAX_Livingroom_THSensor logtype text
attr FileLog_MAX_Livingroom_THSensor room MAX

### 6.4 One-Time Configuration (only stored in actors, not in fhem.cfg) - commented just to document
# Activate Open Window detection
# set MAX_Livingroom_WindowSensor_Balcony associate MAX_Livingroom_Heating1
# set MAX_Livingroom_Heating1 associate MAX_Livingroom_WindowSensor_Balcony
# set MAX_Livingroom_WindowSensor_Balcony associate MAX_Livingroom_Heating2
# set MAX_Livingroom_Heating2 associate MAX_Livingroom_WindowSensor_Balcony
# set MAX_Livingroom_WindowSensor_Balcony associate MAX_Livingroom_THSensor
# set MAX_Livingroom_THSensor associate MAX_Livingroom_WindowSensor_Balcony
# set MAX_Livingroom_THSensor associate MAX_Livingroom_Heating1
# set MAX_Livingroom_Heating1 associate MAX_Livingroom_THSensor
# set MAX_Livingroom_THSensor associate MAX_Livingroom_Heating2
# set MAX_Livingroom_Heating2 associate MAX_Livingroom_THSensor
#
# Define Week Profile
# set MAX_Livingroom_THSensor weekProfile Mon 17,05:00,19,06:00,22,07:15,21,22:30,17 Tue 17,05:00,19,06:00,22,07:15,21,22:30,17 Wed 17,05:00,19,06:00,22,07:15,21,22:30,17 Thu 17,05:00,19,06:00,22,07:15,21,22:30,17 Fri 17,05:00,19,06:00,22,07:15,21,22:30,17 Sat 17,06:00,21,22:30,17 Sun 17,06:00,21,22:30,17
#
# Temperatur Scanner (Graphical)
# attr MAX_Livingroom_Heating1 scanTemp 1
# attr MAX_Livingroom_Heating2 scanTemp 1
# attr MAX_Livingroom_Heating1 userReadings onlyAutoMode { return "1";;}
# attr MAX_Livingroom_Heating1 userReadings watchShutter { return "MAX_Livingroom_WindowSensor_Balcony";;}
# attr MAX_Livingroom_Heating2 userReadings onlyAutoMode { return "1";;}
# attr MAX_Livingroom_Heating2 userReadings watchShutter { return "MAX_Livingroom_WindowSensor_Balcony";;}
# attr MAX_Livingroom_THSensor userReadings onlyAutoMode { return "1";;}
# attr MAX_Livingroom_THSensor scanTemp 1
#
# set MAX_Livingroom_Heating1 windowOpenTemperature 5.5
# set MAX_Livingroom_Heating2 windowOpenTemperature 5.5
# set MAX_Livingroom_THSensor windowOpenTemperature 5.5

### 7.1 Toilette (Heating Thermostat)
define MAX_Toilette_Heating MAX HeatingThermostat 06b990
attr MAX_Toilette_Heating MAX_Child2_Heating AllHeaters
attr MAX_Toilette_Heating room Toilette
attr MAX_Toilette_Heating scanTemp 1
attr MAX_Toilette_Heating userReadings onlyAutoMode { return "1";;}
define FileLog_MAX_Toilette_Heating FileLog ./log/MAX_Toilette_Heating-%Y.log MAX_Toilette_Heating
attr FileLog_MAX_Toilette_Heating icon heizung.0
attr FileLog_MAX_Toilette_Heating logtype text
attr FileLog_MAX_Toilette_Heating room MAX

### 7.2 Toilette (Window Sensor)
define MAX_Toilette_WindowSensor MAX ShutterContact 053d50
attr MAX_Toilette_WindowSensor room Toilette
define FileLog_MAX_Toilette_WindowSensor FileLog ./log/MAX_Toilette_WindowSensor-%Y.log MAX_Toilette_WindowSensor
attr FileLog_MAX_Toilette_WindowSensor logtype text
attr FileLog_MAX_Toilette_WindowSensor room MAX

### 7.3 One-Time Configuration (only stored in actors, not in fhem.cfg) - commented just to document
# Activate Open Window detection
# set MAX_Toilette_WindowSensor associate MAX_Toilette_Heating
# set MAX_Toilette_Heating associate MAX_Toilette_WindowSensor
#
# Define Week Profile
# set MAX_Toilette_Heating weekProfile Mon 17,05:00,19,06:00,21,07:30,19,19:00,21,20:00,17 Tue 17,05:00,19,06:00,21,07:30,19,19:00,21,20:00,17 Wed 17,05:00,19,06:00,21,07:30,19,19:00,21,20:00,17 Thu 17,05:00,19,06:00,21,07:30,19,19:00,21,20:00,17 Fri 17,05:00,19,06:00,21,07:30,19,19:00,21,20:00,17 Sat 17,07:00,21,20:00,17 Sun 17,07:00,21,20:00,17
#
# Temperatur Scanner (Graphical)
# attr MAX_Toilette_Heating scanTemp 1
# attr MAX_Toilette_Heating userReadings onlyAutoMode { return "1";;}
# attr MAX_Toilette_Heating userReadings watchShutter { return "MAX_Kitchen_WindowSensor";;}
#
# set MAX_Toilette_Heating windowOpenTemperature 5.5

### 8.1 Working room (Heating Thermostat)
define MAX_Working_Heating MAX HeatingThermostat 020551
attr MAX_Working_Heating room Workingroom
attr MAX_Working_Heating scanTemp 1
attr MAX_Working_Heating userReadings onlyAutoMode { return "1";;}
define FileLog_MAX_Working_Heating FileLog ./log/MAX_Working_Heating-%Y.log MAX_Working_Heating
attr FileLog_MAX_Working_Heating icon heizung.0
attr FileLog_MAX_Working_Heating logtype text
attr FileLog_MAX_Working_Heating room MAX
define SVG_FileLog_MAX_Working_Heating_1 SVG FileLog_MAX_Working_Heating:SVG_FileLog_MAX_Working_Heating_1:CURRENT
attr SVG_FileLog_MAX_Working_Heating_1 room Workingroom

### 8.2 Working room (Window Sensor)
define MAX_Working_WindowSensor MAX ShutterContact 06102b
attr MAX_Working_WindowSensor room Workingroom
define FileLog_MAX_Working_WindowSensor FileLog ./log/MAX_Working_WindowSensor-%Y.log MAX_Working_WindowSensor
attr FileLog_MAX_Working_WindowSensor logtype text
attr FileLog_MAX_Working_WindowSensor room MAX

### 8.3 One-Time Configuration (only stored in actors, not in fhem.cfg) - commented just to document
# Activate Open Window detection
# set MAX_Working_WindowSensor associate MAX_Working_Heating
# set MAX_Working_Heating associate MAX_Working_WindowSensor
#
# Define Week Profile
# set MAX_Working_Heating weekProfile Mon 17,05:00,19,06:00,21,07:15,19,15:30,21,19:00,19,21:00,17 Tue 17,05:00,19,06:00,21,07:15,19,15:30,21,19:00,19,21:00,17 Wed 17,05:00,19,06:00,21,07:15,19,15:30,21,19:00,19,21:00,17 Thu 17,05:00,19,06:00,21,07:15,19,15:30,21,19:00,19,21:00,17 Fri 17,05:00,19,06:00,21,07:15,19,15:30,21,19:00,19,21:00,17 Sat 17,06:00,21,09:00,19,16:00,21,20:00,17 Sun 17,06:00,21,09:00,19,16:00,21,20:00,17
#
# Temperatur Scanner (Graphical)
# attr MAX_Working_Heating scanTemp 1
# attr MAX_Working_Heating userReadings onlyAutoMode { return "1";;}
# attr MAX_Working_Heating userReadings watchShutter { return "MAX_Working_WindowSensor";;}
#
# set MAX_Working_Heating windowOpenTemperature 5.5

define SVG_FileLog_MAX_Bedroom_Heating_1 SVG FileLog_MAX_Bedroom_Heating:SVG_FileLog_MAX_Bedroom_Heating_1:CURRENT
define SVG_FileLog_MAX_Child1_Heating_1 SVG FileLog_MAX_Child1_Heating:SVG_FileLog_MAX_Child1_Heating_1:CURRENT
define SVG_FileLog_MAX_Bedroom_Heating_2 SVG FileLog_MAX_Bedroom_Heating:SVG_FileLog_MAX_Bedroom_Heating_2:CURRENT

### 9.1 ECO-Wallbutton
define MAX_WallButton MAX PushButton 0521c4
#
# Define House to control all Heaters at once
define AllHeaters structure MAX_Child2_Heating MAX_Workingroom_Heating MAX_Child1_Heating MAX_Livingroom_THSensor MAX_Bedroom_Heating MAX_Toilette_Heating MAX_Kitchen_Heating MAX_Bathroom_Heating
attr AllHeaters room House
attr AllHeaters webCmd desiredTemperature
#
define MAX_HouseECOHeating notify MAX_WallButton:(onoff).* { if ("%EVTPART1" eq "0") { fhem("set AllHeaters desiredTemperature eco") && Log(3,"===> ECO-Mode set");;} else { fhem("set AllHeaters desiredTemperature auto") && Log(3,"===> AUTO-Mode set");;}}
#
#
define SVG_FileLog_MAX_Bathroom_Heating_1 SVG FileLog_MAX_Bathroom_Heating:SVG_FileLog_MAX_Bathroom_Heating_1:CURRENT
define SVG_FileLog_MAX_Bedroom_Heating_3 SVG FileLog_MAX_Bedroom_Heating:SVG_FileLog_MAX_Bedroom_Heating_3:CURRENT
define SVG_FileLog_MAX_Child1_Heating_2 SVG FileLog_MAX_Child1_Heating:SVG_FileLog_MAX_Child1_Heating_2:CURRENT
define SVG_FileLog_MAX_Child2_Heating_2 SVG FileLog_MAX_Child2_Heating:SVG_FileLog_MAX_Child2_Heating_2:CURRENT
define SVG_FileLog_MAX_Kitchen_Heating_1 SVG FileLog_MAX_Kitchen_Heating:SVG_FileLog_MAX_Kitchen_Heating_1:CURRENT
define SVG_FileLog_MAX_Livingroom_THSensor_1 SVG FileLog_MAX_Livingroom_THSensor:SVG_FileLog_MAX_Livingroom_THSensor_1:CURRENT
define SVG_FileLog_MAX_Toilette_Heating_1 SVG FileLog_MAX_Toilette_Heating:SVG_FileLog_MAX_Toilette_Heating_1:CURRENT
define SVG_FileLog_MAX_Working_Heating_2 SVG FileLog_MAX_Working_Heating:SVG_FileLog_MAX_Working_Heating_2:CURRENT

=== Planned changes ===
ADD ME

[[Kategorie:MAX]]

NetIO-230B

2013-09-19T16:59:26Z

SirUli: /* Hinweise zum Betrieb mit FHEM */

= NetIO-230B =
IP-Spannungsverteiler (Mehrfachsteckdose), der über IP-Befehle und manuell gesteuert werden kann.

== Eigenschaften ==
* Eingebauter Webserver
* Vier geschaltete Spannungsausgänge
* Unterstützte Protokolle: HTTP, SMTP, SNTP, DHCP, DNS und Telnet
* CGI Befehle und Telnet-Steuerung
* Abgesichertes Login
* Benutzerrechtgruppen
* LED–Anzeigen für aktuellen Status jedes Ausgangs
* Sicheres Design schützt vor Stromschlag, feuersichere Materialien
* Timer
* Wählbare Start-Einstellungen für jeden Ausgang (An/Aus)
* Taster für Handbetrieb der Ausgänge
* Watchdog (automatischer Neustart von nicht antwortenden Netzwerkgeräten)
* E-Mail Benachrichtigung
== Spezifikationen ==
* Eingangsspannung: 230V AC
* Maximaler Schaltstrom: 6A per Steckdose, 10A gesamt
* Latenzzeit: max. 10 ms
* Maße: 300x60x90 mm (BxHxT)
* Netzwerk-Anschluss: 10/100 Mbit/s, RJ-45
== Allgemein ==
NetIO-230B lässt sich komplett per Web Browser bedienen/konfigurieren. Javascript wird benötigt.

== Hinweise zum Betrieb mit FHEM ==
Kopiert von [[http://forum.fhem.de/index.php?t=msg&th=13399&start=0&rid=0 hier]]

===Definition===
Steuervariablen definieren, für die spätere Steuerung
<pre>define NET_IO_Switch1 dummy</pre>

Notify Script 1 für ON
<pre>define NETIO230_SwitchOn_Switch1 notify NET_IO_Switch1:on {GetHttpFile("<NETIO IP>", "/tgi/control.tgi?login=p:admin:<password>");; \ GetHttpFile("<NETIO IP>", "/tgi/control.tgi?p=1uuu");; \ GetHttpFile("<NETIO IP>", "/tgi/control.tgi?quit=quit");; }</pre>

Notify Script 2 für OFF
<pre>define NETIO230_SwitchOn_Switch1 notify NET_IO_Switch1:on {GetHttpFile("<NETIO IP>", "/tgi/control.tgi?login=p:admin:<password>");; \ GetHttpFile("<NETIO IP>", "/tgi/control.tgi?p=0uuu");; \ GetHttpFile("<NETIO IP>", "/tgi/control.tgi?quit=quit");; }</pre>

===Erläuterung des Aufrufs===
Mit dieser Zeile wird eine Verbindung mit dem NET IO230 aufgebaut:
<pre>GetHttpFile("192.X.X.X", "/tgi/control.tgi?login=p:admin:<Password>");;</pre>

Ersetzungen:
* ''<Password>'' hier müßt Ihr eure Password im Klartext eintragen
* ''<NETIO IP>'' hier ist die IP Adresse, z.B. 192.168.1.3 des NET-IO einzutragen.

Mit dieser Zeile wird der Ausgangsstatus des NET-IO verändert:
<pre>GetHttpFile("<NETIO IP>", "/tgi/control.tgi?p=1uuu");; </pre>

Ersetzungen:
* u=nicht verändern
* 0=Ausschalten
* 1=Einschalten

Hierbei müssen immer 4 Zeichen angegeben werden. Im obigen Beispiel schaltet '''1uuu''' den ersten Port ein und lässt alle anderen unverändert.

Beenden der Verbindung:
<pre>GetHttpFile("<NETIO IP>", "/tgi/control.tgi?quit=quit");;</pre>

===Steuerung in FHEM===
Die Steuerung erfolgt wie folgt:

* Einschalten
<pre>set NET_IO_Switch1 on</pre>

* Ausschalten
<pre>set NET_IO_Switch1 off</pre>

== Bekannte Probleme ==
??

== Links ==
Bedienungsanleitung (deutsch): [http://www.koukaam.se/koukaam/downloads/MAN_DE_NETIO-230B_3-00.pdf MAN_DE_NETIO-230B_3-00.pdf]

[[Kategorie:Other Components]]
[[Kategorie:Schalter (Empfänger)]]

Arduino

2013-09-18T18:38:43Z

SirUli: Link was 404, updated with new destination

== Arduino zur Anbindung eigener Sensoren und Aktoren an FHEM nutzen ==
Mit [http://www.arduino.cc/ Arduino]-Boards lassen sich einfach und recht preisgünstig (ab ca. 15€ Stand Juli 2012) eigene Sensoren/Aktoren an FHEM anbinden.

Das Board lässt sich recht einfach programmieren um Sensorwerte zu verarbeiten und diese z.B. per Ethernet an FHEM zu senden oder abfragen zu lassen. Über zahlreiche Schnittstellen (Standard: RS232, TWI/1-Wire, SPI, PWM, analog/digital-I/O, I2C) mit den entsprechenden Software-Libraries kann auf viele gängige Sensoren zugegriffen werden. Über Erweiterungsboards ("Shields") können die Anschlussmöglichkeiten ausgebaut werden. Zudem ist der Anschluss von Parallel-/Seriell-/I2C-LCD-Displays und SD-Karten möglich.

Die Boards und eine Vielfalt an Sensoren/Aktoren sind über Online-Auktionen bzw. -Anbieter einfach zu bekommen. Kommunikation mit dem Arduino ist z.B. per Netzwerk/Ethernet, WLAN, 433/868MHz/2,4GHz-RF, Bluetooth, 1-Wire etc. möglich.

'''Arduino mit Ethernet'''
Eine einfache und sehr kompakte Lösung ist der Arduino Nano mit Ethernet-Shield. Der Nano hat je 8 nutzbare Analog- und Digital Ein-/Ausgänge über die sich beispielsweise Temperatursensoren, Relais etc. ansprechen lassen.

Folgende Schritte sind zur Vorbereitung zu tun:

# Arduino (bzw. Klon) mit Ethernet-Shield (z.B. mit ENC28J60 Chip) und gewünschten Sensoren kaufen
# Arduino-IDE von der [http://arduino.cc/en/Main/Software Arduino-Homepage] (für Windows, Mac OS X und Linux vorhanden) herunterladen und installieren
# Falls ENC28J60-Ethernet-Shield verwendet wird: Ethernet-Library für ENC28J60 herunterladen und in Arduino-IDE-Installation hineinkopieren (z.B. von hier: [http://trollmaker.com/article11/arduino-1-0-with-enc28j60-ethernet-shield-v1-1/], alternativ nach arduino+ENC28J60+library googeln)
# Folgenden Beispiel-Sketch mit Arduino-IDE öffnen Arduino_FHEM.ino [https://sites.google.com/site/fhemarduino/file-cabinet/Arduino_FHEM.ino?attredirects=0&d=1]
# IP Adresse im Sketch passend zum eigenen Netzwerk ändern (steht im Sketch auf 192.168.2.44)
# Sketch auf Arduino laden
# Arduino mit 5V-USB-Netzteil ans Netzwerk anschliessen
# Verbindung testen indem in einem Webbrowser <arduino_ip_adresse>/?cmd=set_D5_ON [http://192.168.2.44/?cmd=set_D5_ON] eingegeben wird (natürlich hier die im Sketch verwendete IP-Adresse angeben). Falls an Ausgang D5 eine Leuchtdiode o.ä. angeschlossen wurde sollte diese nun leuchten.
# Wenn das geklappt hat sollte sich der Ausgang auch aus der FHEM-Kommandozeile ausschalten lassen mit { GetHttpFile('192.168.2.44:80', '/?cmd=set_D5_OFF');; } -> natürlich wieder die im Sketch verwendete IP-Adresse verwenden.
# Letzter Schritt wäre eine Definition in die fhem.cfg einzutragen um auch entsprechende Buttons in der FHEM-Oberfläche zu haben, ggf. wieder die verwendete IP-Adresse statt arduino:80 verwenden (für die Buttons wurde das FS20-Modul verwendet):

Auszug aus der ''fhem.cfg''
<nowiki>define arduinobutton FS20 55d1 00
attr arduinobutton room Arduino
define FileLog_arduinobutton FileLog /otp/fhem/log/arduinobuttonon-%Y.log arduinobutton
attr FileLog_arduinobutton room Arduino
define arduinoswitchon notify FS20_55d100:on { GetHttpFile("arduino:80","/?cmd=set_D5_ON")}
attr arduinoswitchon room Arduino
define arduinoswitchoff notify FS20_55d100:off { GetHttpFile("arduino:80","/?cmd=set_D5_OFF")}
attr arduinoswitchoff room Arduino
define weblink_arduinobutton weblink fileplot FileLog_arduinobutton:fs20:CURRENT
attr weblink_arduinobutton label "arduinobutton Min $data{min1}, Max $data{max1}, Last $data{currval1}"
attr weblink_arduinobutton room Arduino</nowiki>

Abfragen von Sensorwerten sind natürlich auch möglich, z.B. mit folgender Definition (Analog- und Digital-PINs werden alle fünf Minuten abgefragt und in Plots visualisiert):

Auszug aus der ''fhem.cfg''
<nowiki>define arduinogetsensorvalues at +*00:05:00 {\
my $val = GetHttpFile('arduino:80', '/?cmd=get_analog_values');;\
fhem("trigger arduinogetsensorvalues $val");;\
}
attr arduinogetsensorvalues room Arduino
define FileLog_arduinogetsensorvalues FileLog /opt/fhem/log/arduinogetsensorvalues-%Y.log arduinogetsensorvalues:.*
attr FileLog_arduinogetsensorvalues room Arduino
define weblink_getsensorvalues weblink fileplot FileLog_arduinogetsensorvalues:arduino:CURRENT
attr weblink_getsensorvalues label "Arduino Sensorvalues Min $data{min1}, Max $data{max1}, Last $data{currval1}"
attr weblink_getsensorvalues room Arduino
define arduinogetsensorvaluesD at +*00:05:35 {\
my $val = GetHttpFile('arduino:80', '/?cmd=get_digital_values');;\
fhem("trigger arduinogetsensorvaluesD $val");;\
}
attr arduinogetsensorvaluesD room Arduino
define FileLog_arduinogetsensorvaluesD FileLog /opt/fhem/log/arduinogetsensorvaluesD-%Y.log arduinogetsensorvaluesD:.*
attr FileLog_arduinogetsensorvaluesD room Arduino
define weblink_getsensorvaluesD weblink fileplot FileLog_arduinogetsensorvaluesD:arduino:CURRENT
attr weblink_getsensorvaluesD label "Arduino Digital Values Min $data{min1}, Max $data{max1}, Last $data{currval1}"
attr weblink_getsensorvaluesD room Arduino</nowiki>

TODO: Kommunikation via RF + Bluetooth + WLAN

Fragen zum Thema bitte in das FHEM-Forum [http://forum.fhem.de/] posten.

Neben der hier beschriebenen Methode Arduinos an FHEM anzubinden gibt es noch die möglichkeit [[PanStamp]]s über das SWAP Protokoll per RF an FHEM anzubinden. Eine Firmata über SWAP Implementierung ist gerade in Arbeit.

== Arduino mit StandardFirmata ==
Für den Arduino gibt es ein StandardProtokoll Firmata[https://github.com/ntruchsess/perl-firmata [6]] ist das Protokoll in perl einfach nutzbar und mit dem Modul 10_FRM.pm an FHEM adaptiert. 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.

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

=== FRM ===
Der Arduino wird in FHEM über das Modul 10_FRM.pm angesprochen (dazu bitte die aktuelle Development-version herunterladen ([http://www.dhs-computertechnik.de/downloads/fhem-cvs.tgz http://www.dhs-computertechnik.de/downloads/fhem-cvs.tgz]) aus dem SVN auschecken oder per updatefhem aktualisieren).
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.

define <devicename> FRM <port>

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.
Die Firmware mit Ethernetunterstützung ist in diesem Branch zu finden:
[https://github.com/ntruchsess/arduino/archive/configurable_ethernet.zip https://github.com/ntruchsess/arduino/archive/configurable_ethernet.zip]
Darin den unter den examples zu findenen Sketch 'ConfigurableEthernetclient' ([https://github.com/ntruchsess/arduino/blob/configurable_ethernet/examples/ConfigurableEthernetclient/ConfigurableEthernetclient.ino https://github.com/ntruchsess/arduino/blob/configurable_ethernet/examples/ConfigurableEthernetclient/ConfigurableEthernetclient.ino])

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

Getestet ist das ganze mit UNO R3 + EthernetShield. Andere Arduinos benötigen ggf. Anpassungen in der Setup/Reset Funktion. 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. Wenn man eine andere Hardware (z.B. mit ENC28J60 anstelle des WizNet W5100 des Ethernetshields) benutzen möchte, muss man die zugehörige Libraries in den Sketch einbinden.

=== FRM-Devices ===
==== 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>
==== 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>
==== 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>
==== 20_FRM_PWM.pm ====
Macht einen Arduino-pin als analogen Ausgang nutzbar. Es wird ein pulsweitenmoduliertes Signal ausgegeben.

==== 20_FRM_SERVO.pm ====
Erlaubt die Ansteuerung von analogen Modelbauservos (Ansteuerung über PWM) am Arduino.

==== 20_FRM_I2C.pm ====
Erlaubt das Auslesen von über I2C angeschlossenen ICs

=== Arduino mit OneWireFirmata ===
die Seite [[Arduino mit OneWireFirmata]] beschreibt, wie es möglich ist, mit einer um OneWire erweiterten Version der StandartFirmata an den Arduino angeschlossene 1-Wire Devices in FHEM einzubinden.

[[Kategorie:Other Components]]
[[Kategorie:HOWTOS]]

Windows - CPU Temperatur und Co mit FHEM

2013-07-15T20:27:33Z

SirUli: Formatting

(von kleene 1503)

Hier mal eine Möglichkeit, wie man auf Windows-Systemen die CPU-, HDD-, und andere Temperaturen / Systemdaten in FHEM anzeigen und grafisch darstellen kann.

Voraussetzungen:
- Cygwin installiert
- SpeedFan installiert
- Einen WIRKLICH Unix fähigen Editor. Vergesst hierbei Wordpad und Notepad!!! Ich nutze Proton (ist kostenlos und frei verfügbar). Bei Proton müsst ihr UNBEDINGT darauf achten, dass ihr unter „Datei -> Zeilenumbruchformat“ auf Unix umstellt. Sonst sucht ihr wie ich zwei Wochen nach einem Fehler wo eigentlich gar keiner ist. Das Umstellen unter Syntaxschema auf Unix Shell ist hilfreich aber kein muss.

Laufen tut das ganze bei mir auf Windows 7 Home Premium 64bit.
== Installiert Cygwin ==
Auf die Installation von Cygwin werde ich hier nicht eingehen. Dazu gibt es genug im www.

== Installiert SpeedFan ==
* Um später Leerzeichen in den Pfadangaben zu vermeiden, habe ich nach der Installation von SpeedFan einfach den kompletten Installationsordner direkt nach C: kopiert. Im Klartext heißt das, aus <code>C:\Programme (x86)\SpeedFan\</code> wurde bei mir <code>C:\SpeedFan\</code>.
* SpeedFan selbst habe ich so eingerichtet, dass er mir das Logfile MIT Header schreibt. Das Logfile von SpeedFan findet ihr direkt in dem Installationsordner von SpeedFan.

== Script zum bearbeiten des SpeedFan Logfiles und speichern eines FHEM tauglichen Logfiles erstellen ==
- Die Logfiles von SpeedFan sind noch nicht FHEM tauglich. Also müssen wir uns die Files mit Hilfe eines kleinen Scriptes in ein FHEM taugliches Format umwandeln. Dieses Script sieht bei mir wie folgt aus:

<pre>#!/bin/sh
date=`date +"%Y-%m-%d_%H:%M:%S"`
log="/cygdrive/c/fhem/tmp/system.log"
cat /cygdrive/c/SpeedFan/SFLog*.csv \
| grep "" \
| sed '/Seconds/d' \
| sed 's/[\t]/ /g' \
| sed 's/ \+/ /g' \
| sed '$!d' \
| sed "s/^/$date /" >> $log
#</pre>
Erklärung:

* <code>!/bin/sh</code> <- sollte klar sein
* <code>date=`date +"%Y-%m-%d_%H:%M:%S"`</code> <- sollte auch klar sein
* <code>log="/cygdrive/c/fhem/tmp/system.log"</code> <- /cygdrive sagt unserem PC, dass wir Cygwin nutzen (um es mal grob auszudrücken); /c/fhem/tmp/system.log ist der Pfad wo unser fertiges und FHEM taugliches logfile später gespeichert werden soll.
* <code>cat /cygdrive/c/SpeedFan/SFLog*.csv \</code> <- sagt unserem script, wo das SpeedFan Logfile liegt welches wir bearbeiten wollen.
* <code>| grep "" \</code> <- liest das komplette SpeddFan Logfile ein.
* <code>| sed '/Seconds/d' \</code> <- Entfernt die komplette Zeile in der das Wort Seconds vorkommt was in unserem Fall der Header des SpeedFan Logfiles ist.
* <code>| sed 's/[\t]/ /g' \</code> <- Entfernt alle Tabs aus dem Speedfan Logfile.
* <code>| sed 's/ \+/ /g' \</code> <- Entfernt alle Leerzeichen aus dem SpeedFan Logfile.
* <code>| sed '$!d' \</code> <- kopiert immer nur die letzte Zeile des SpeedFan Logfiles und kopiert uns diese samt Datum mit
* <code>| sed "s/^/$date /" >> $log</code> in unser FHEM taugliches Logfile.

Dieses Script speichert ihr nun als <code>system.sh</code> in eurem Cygwin Home Ordner.

Übrigens: Wenn man sich mit dem "sed" Kommando auseinandersetzt, kann man so auch Logfiles von anderen Windowsprogrammen zum Temperatur- und Systemdaten auslesen wunderbar in ein FHEM taugliches Format bringen.

== .bat erstellen zum ausführen der .sh – Datei ==
- Erstellt euch eine .bat mit folgendem Inhalt:

<pre>@echo off
C:
chdir C:\cygwin\bin
bash --login -i ./system.sh</pre>
und speichert diese als <code>system.bat</code> in eurem fhem Ordner.

== Aufrufen der system.bat durch FHEM ==
- Erstellt in eurer fhem.cfg folgenden Eintrag:

<pre>define SystemDaten at +*00:02:00 { fhem `system`}</pre>
Dieser Eintrag startet alle 2 Minuten die Datei system.bat welche wiederum das Script system.sh ausführt.

Wenn ihr es so wie ich gemacht habt, sollte nun innerhalb der nächsten 2 Minuten) in dem Ordner „C:\fhem\tmp\“ ein Logfile namens system.log auftauchen welches alle nötigen Daten enthält und FHEM tauglich ist.

== Plot Datei erstellen ==
- Als Vorlage habe ich die Datei <code>cpulog.gplot</code> aus dem FHEM Ordner genommen. Wichtig ist hier für uns der untere Teil ab set ylabel. Der obere Teil kann bleiben wie er ist.

Wir müssen uns nun Überlegen, was wir uns anzeigen lassen wollen. In diesem Fall nehmen wir mal die Temperaturen von Core 0 und Core 1.

Als erstes sehen wir uns noch einmal das SpeedFan Logfile an welches bei mir folgendermasen aussieht:

<blockquote><code>Seconds HD0 Core 0 Core 1
71180 34.0 36.0 34.0</code></blockquote>

Core 0 und 1 ist also an 3. und 4. Stelle nach Seconds.

Nun sehe ich mir unser erstelltes system.log Logfile an:

<blockquote><code>2012-03-19_22:33:15 71180 34.0 36.0 34.0</code></blockquote>

Wir haben also vor dem Wert für Seconds noch das Datum und die Uhrzeit und den Temperaturwert für Core 0 und 1 finden wir nun an der 4. und 5. Stelle. Wichtig ist, dass ihr Leerzeichen nicht mit zählt.

Gehen wir nun zurück zur Datei cpulog.gplot und Tragen folgendes ein:

<pre>set ylabel "Temperatur in C"
set y2label "Temperatur in C"
#FileLog 4::0:
#FileLog 5::0:
plot "<IN>" using 1:4 title 'Temperatur Core 0' with lines,\
"<IN>" using 1:5 title 'Temperatur Core 1' with lines</pre>

Erklärung:
* <code>set ylabel "Temperatur in C"</code> <- Ist die linke, senkrechte Bezeichnung des Plot-Fensters.
* <code>set y2label "Temperatur in C"</code> <- Ist die rechte, senkrechte Bezeichnung des Plot-Fensters.
* <code>FileLog 4::0:</code> <- liest die 4 Stelle unseres Logfiles aus.
* <code>FileLog 5::0:</code> <- liest die 5. Stelle unseres Logfiles aus.
* <code>plot "<IN>" using 1:4</code> <- zeigt die 4. Stelle unseres Logfiles im Plot-Fenster.
* <code>title 'Temperatur Core 0' with lines</code> <- Zeigt im Plot-Fenster den Titel unserer Linie.
* <code>,\</code> <- Sagt FHEM das noch eine weitere Linie kommt.

Speichert dies nun Beispielsweise als <code>core01.gplot</code>

== Plot in FHEM anzeigen lassen ==
- Nun Tragen wir in unserer fhem.cfg folgendes ein:

<pre>define SystemLog FileLog C:/fhem/tmp/system.log SystemDaten
attr SystemLog logtype core01
define Sys weblink fileplot SystemLog:core01:CURRENT</pre>

Wenn alles geklappt hat, solltet ihr nun die Temperaturen grafisch in FHEM dargestellt bekommen.

Ich übernehme keine Garantie. Kann nur sagen, dass es bei mir so geklappt hat. Ich hoffe ich kann dem einen oder anderen damit helfen oder wenigstens einen Denkanstoß geben.

Es gibt bestimmt noch elegantere Lösung allerdings habe ich für Windows bis jetzt noch nichts gefunden.

(von kleene 1503)
[[Kategorie:HOWTOS]]

Google-Kalender zur Steuerung von Dummies

2013-07-15T17:17:42Z

SirUli: Formatting of Code

Mit dem Kalendermodul [http://fhem.de/commandref.html Calendar] ist es möglich, Ereignisse aus Kalendern im
ICal-Format abzufragen.
Dies und der Wiki-Eintrag [[Wochenende, Feiertage und Schulferien]] hat mich dazu veranlasst, dass ich durch
Kalendereinträge im Google-Kalender den Status meiner beiden Dummies "Urlaub" und "Besuch" steuere. Durch diese
beiden Dummies werden zum Beispiel die Rolläden im Schlafzimmer oder Gästezimmer bei Besuch oder Urlaub anders
gesteuert als ohne Besuch oder unter der Woche. Auch meine Zirkulationspumpe soll so bedarfsgerecht gesteuert werden.
Dass am Wochenende anders gesteuert wird, ist ja mit $we kein Problem.
Zuerst wird dafür der Kalender definiert:
<pre>define Kalender_Christian Calendar ical url <der richtige Kalenderlink> 14400</pre>

Den Kalenderlink [https://support.google.com/calendar/answer/37103?hl=de] findet man wie beschrieben heraus.
Dann habe ich meine Dummies definiert:
<pre>define Urlaub_dummy dummy
attr Urlaub_dummy room Kalender
attr Urlaub_dummy setList ja nein
attr Urlaub_dummy webCmd ja:nein
define Gast_dummy dummy
attr Gast_dummy room Kalender
attr Gast_dummy setList ja nein
attr Gast_dummy webCmd ja:nein</pre>

Und nun mussten die Notifys definiert werden, um bei entsprechenden Einträgen im Google-Kalender den Status der
Dummies zu setzen.
<pre>define Kalender_Christian_Start notify Kalender_Christian:modeStarted.*googlecom.* {\
Kalenderstart("$EVENT");;\
}
define Kalender_Christian_Ende notify Kalender_Christian:modeEnded.*googlecom.* {\
Kalenderende("$EVENT");;\
}</pre>

Um nicht für verschiedene Dummies immer einzelne Notifys zu bauen, wird hier bei mir je eine Funktion aus meiner
99_MyUtils.pm [[99 myUtils anlegen]] aufgerufen und das Event als Parameter übergeben. Die beiden zugehörigen
Funktionen für den Start und das Ende des Kalenderevents schauen so aus:
<pre>sub
Kalenderstart ($)
{
my ($Ereignis) = @_;
my @Ereignisarray = split(/.*:\s/,$Ereignis);
my $Ereignisteil1 = $Ereignisarray[1];
my @uids=split(/;/,$Ereignisteil1);
foreach my $uid (@uids) {
my $Kalendertext = fhem("get Kalender_Christian summary $uid");
if ($Kalendertext =~ /Urlaub/) {
fhem("set Urlaub_dummy ja");
};
if ($Kalendertext =~ /Besuch/) {
fhem("set Gast_dummy ja");
};
};
}
sub Kalenderende ($) {
my ($Ereignis) = @_;
my @Ereignisarray = split(/.*:\s/,$Ereignis);
my $Ereignisteil1 = $Ereignisarray[1];
my @uids=split(/;/,$Ereignisteil1);
foreach my $uid (@uids) {
my $Kalendertext = fhem("get Kalender_Christian summary $uid");
if ($Kalendertext =~ /Urlaub/) {
fhem("set Urlaub_dummy nein");
};
if ($Kalendertext =~ /Besuch/) {
fhem("set Gast_dummy nein");
};
};
}
</pre>

Zur Erläuterung: Als Ereignis wird z.B. "''modeStarted: 9aas2amo7td47th4sf7mlocl48googlecom''" oder bei 2 gleichzeitigen
Ereignissen: "''modeStarted: arqpe2a2snu6qn64dt0men7nd0googlecom;j0pjiupfb1sk3m5s64hbeo6880googlecom''"
übergeben. Da uns aber nur die eindeutige UID interessiert, wird das Ergeinis beim Vorkommen der Zeichen ": Leerzeichen"
also nach modeStarted: geteilt (''split(/.*:\s/,$Ereignis'')). Die beiden Teile werden in ein Array (@Ereignisarray) gespeichert.
Und als 2. Element in dem Array ist nun die uns interessierende UID ($Ereignisarray[1]) vorhanden, mit welcher wir weiter
arbeiten. Da auch mit dem Fall mehrerer gleichzeitiger Ereignisse umgegangen werden können soll, müssen wir bei mehreren
UID´s diese wieder splitten. Diesmal beim Vorkommen des Semikolons als Trennzeichen (''split(/;/,$Ereignisteil1'')). Auch die
UID´s werden wieder in einem Array gespeichert und dann mittels der foreach-Schleife nacheinander abgearbeitet. Und
hierbei wird abhängig von der mittels UID abgerufenen Kalenderbeschreibung (''fhem("get Kalender_Christian summary
$uid''")) ein Vergleich auf die Werte "Besuch" oder "Urlaub" durchgeführt (''if ($Kalendertext =~ /Urlaub/'')) und davon
abhängig der Dummy-Status gesetzt.
Abhängig von diesen Dummies reagiert dann meine Rollosteuerung.

[[Kategorie:Code Snippets]]