FHEMWiki - Benutzerbeiträge [de]

InfluxDBLogger

2021-11-28T20:15:37Z

Joshi04: Weitere Ergänzungen zur Komplettierung des Artikels

{{Infobox Modul
|ModPurpose=Protokolliert Ereignisse in einer Datenbank
|ModType=h
|ModForumArea=Unterstützende Dienste
|ModTechName=93_InfluxDBLogger.pm
|ModOwner={{Link2FU|41939|timmib}}}}
Genau wie mit dem Modul [[DbLog]] lassen sich mit [[InfluxDBLogger]] Daten in einer Datenbank speichern.

Für die Vorteile der Speicherung von Daten in einer Datenbank sei auf die Beschreibung des Moduls ''DbLog'' verwiesen.

Einer der größten Unterschiede zu einer SQL-Datenbank ist die Tatsache, dass influxDB speziell darauf ausgelegt ist, große Messdatenmengen in kurzer Zeit zusammen mit einem Zeitstempel des Messzeitpunkts zu verarbeiten.

Des Weiteren ist ein sehr wichtiger Unterschied, dass nur numerische Werte verarbeitet werden. Dies kann die Kombination mit anderen Loggingmethodiken situationsabhängig sinnvoll machen. Textbasierte Werte können aber auch durch numerische Werte ersetzt werden.

Ein Interface oder eine Möglichkeit, die Daten mittels SVG-Plots darzustellen ist derzeit nicht vorhanden. Alternativ können die Daten mittels [[Grafana]] analysiert und visualisiert werden.

== Allgemein ==
{{Randnotiz|RNTyp=y|RNText='''Alternativmodul'''
Um Missverständnisse zu vermeiden, sei an dieser Stelle darauf hingewiesen, dass es bereits ein anderes Modul mit den Namen [[InfluxDBLog|93_InfluxDBLog]] für die Anbindung an eine InfluxDB gibt, das zu diesem Zeitpunkt (11/2021) allerdings nicht weiterentwickelt zu werden scheint und um das es in diesem Artikel definitiv nicht geht.

Siehe dazu auch hier: {{Link2Forum|Topic=71551|Message=896556|LinkText=Forumsbeitrag}}, {{Link2Forum|Topic=71551|Message=1071675|LinkText=Forumsbeitrag}}, {{Link2Forum|Topic=71551|Message=1090783|LinkText=Forumsbeitrag}}

Für die Beschreibung der Einrichtung als native Installation in Verbindung mit einer InfluxDB 1.x sei auf [https://waschto.eu/2018/11/02/fhem-und-grafana-tool-zum-visualisieren-von-messdaten/ diesen Artikel] verwiesen. }}
Im Folgenden wird auf die Einrichtung unter Docker (inkl. Docker-Compose) mit einer InfluxDB 2.0 eingegangen.

== Einrichtung einer Datenbank als Docker Container ==
Voraussetzungen:
* Eine laufende Docker-Umgebung (inkl. Docker-Compose)
* Ein FHEM Docker-Image mit source Dateien im Unterordner ./fhem/build
* Die FHEM Konfiguration im Unterordner ./fhem/conf
* Das folgende file <code>docker-compose.yml</code> im Ausgangsordner
<syntaxhighlight lang="YAML">
version: '2.4'
services:

fhem2:
container_name: fhem2
build: ./fhem/build
restart: always
ports:
- 8083:8083
depends_on:
- influxdb
volumes:
- ./fhem/conf:/opt/fhem
environment:
- FHEM_UID=1000
- FHEM_GID=1000
- FHEM_PERM_DIR=0750
- FHEM_PERM_FILE=0640

influxdb:
image: influxdb:latest
restart: always
ports:
- 8086:8086
volumes:
# Mount for influxdb data directory and configuration
- ./influxdb/data:/var/lib/influxdb2:rw
- ./influxdb/config:/etc/influxdb2:rw
environment:
- DOCKER_INFLUXDB_INIT_MODE=setup
- DOCKER_INFLUXDB_INIT_USERNAME=${INFLUXDB_USERNAME}
- DOCKER_INFLUXDB_INIT_PASSWORD=${INFLUXDB_PASSWORD}
- DOCKER_INFLUXDB_INIT_ORG=${INFLUXDB_ORG}
- DOCKER_INFLUXDB_INIT_BUCKET=${INFLUXDB_BUCKET}
- DOCKER_INFLUXDB_INIT_ADMIN_TOKEN=${INFLUXDB_TOKEN}
</syntaxhighlight>

Die Definition des oben genannten Containers "fhem2" ist für die Einrichtung der Datenbank nicht notwendig und ist an dieser Stelle nur der Vollständigkeit halber mit aufgeführt. FHEM kann auch separat installiert sein, es bietet sich aber in diesem Beispiel an, gleich mit in das Docker-Compose-File mit aufgenommen zu werden.

An dieser Stelle sei empfohlen, die Zugangsinformationen in eine .env Datei auszulagern, die zugriffsbeschränkt im gleichen Verzeichnis liegt, wie die <code>docker-compose.yml</code> Datei.
<syntaxhighlight lang="YAML">
INFLUXDB_USERNAME=myusername
INFLUXDB_PASSWORD=passwordpasswordpassword
INFLUXDB_ORG=myorg
INFLUXDB_BUCKET=mybucket
INFLUXDB_ADMIN_TOKEN=mytoken
</syntaxhighlight>

Die Unterverzeichnisse für die InfluxDB Datenbank (./influxdb/data), sowie die Konfiguration (./influxdb/config) werden automatisch beim ersten Starten erstellt.

Der Eintrag "DOCKER_INFLUXDB_INIT_MODE=setup" führt dazu, dass die Datenbank beim ersten Starten initialisiert wird, dieses aber nur, falls keine Datenbank gefunden wird. So kann dieser Eintrag für die spätere Verwendung in der Konfiguration verbleiben und muss nicht entfernt werden.

Mit dieser Konfiguration ist FHEM über <code><ip-des-docker-servers>:8083</code> erreichbar, das Webinterface von InfluxDB über <code><ip-des-docker-servers>:8086</code> erreichbar.

Die gesamte Konfiguration kann über
:<code>docker-compose up -d </code>
gestartet, bzw. über
:<code>docker-compose down </code>
gestoppt werden.

Nach der Einrichtung der Datenbank wird empfohlen, die Ansprechbarkeit der Datenbank über das Webinterface unter Zuhilfenahme des vergebenen Usernamens und Passworts zu testen.
<syntaxhighlight lang="HTML">
http://<ip-des-dockercontainers>:8086
</syntaxhighlight>

== Konfiguration des Loggers als Device in FHEM ==
{{Randnotiz|RNText='''Unterschiede zur Definition von DBLog'''
Um Fehlern bei der Umstellung von DBLog auf InfluxDBLogger zu vermeiden, bitte beachten: anders als bei DBLog werden bei der Definition nur die Devices definiert und nicht zusätzlich auch die Readings {{Link2Forum|Topic=114860|Message=1119696|LinkText=(Forum).}}. }}
Das InfluxDBLogger Device wird dann definiert mit
:<code>define <Device-name> InfluxDBLogger [http|https]://IP_or_Hostname:port dbname devspec,devspec,<weitere devspec></code>
wobei bei der Verwendung der InfluxDB Version 2 folgende Attributfestlegungen notwendig werden:
* Das Attribut api=v2, das die InfluxDB Version 2 festlegt. Hiermit wird auch das Setzen der Org mit dem folgenden Attribut notwendig, wie auch die Verknüpfung des Buckets als ''dbname''.
* Das Attribut org=myorg, das die vergebene Org festlegt.
* Das Attribut security=token, das die Verwendung eines Tokens festlegt. Hiermit ist ebenfalls das Definieren eines Users als Attribut und das Setzen eines Passwortes überflüssig. Der Token wird über <code> set <Device-name> token <mytoken></code> festlegt.

Ein Beispiel für eine Konfiguration wäre:
<syntaxhighlight lang="Text">
define influxDB InfluxDBLogger http://10.10.120.106:8086 FHEM-bucket DB_Temp_Hum,KU_Temp_Hum,FL_Temp_Hum
attr influxDB api v2
attr influxDB org myorg
attr influxDB security token
</syntaxhighlight>

== Finetuning des Loggings ==
Bei der Optimierung ist der Einschränkung an der Quelle (am jeweiligen Device) immer der Vorzug zu geben vor der Einschränkung an zentraler Stelle, um unnötig entstehende Daten zu vermeiden. Allerdings kann es Fälle geben, in denen eine Whitelist oder Blacklist bzgl. der Definition, welche der entstandenen Events geloggt werden sollen, sinnvoll sein kann.

Dieses kann exklusiv oder zusätzlich zu den im Folgenden genannten Einschränkungen über die jeweiligen Devices an zentraler Stelle geschehen.

=== Einschränkung über die jeweiligen Devices ===
Da in Abhängigkeit von Events Einträge in die Datenbank geschrieben werden, lassen sich die gleichen Prinzipien anwenden, wie bei [[DbLog]] und [[FileLog]] um Events zu unterdrücken:
* event-min-interval, event-on-change-reading und event-on-update-reading beeinflussen, wie häufig Werte geloggt werden (vgl. {{Link2CmdRef|Lang=de|Anker=event-on-update-reading}})
* event-aggregator ({{Link2Forum|Topic=114860|Message=1110435|LinkText=Forum}})

=== Einschränkung über den zentralen <code>define</code>-Eintrag ===
Verweis auf die commandref {{Link2CmdRef|Lang=de|Anker=InfluxDBLogger|Label=InfluxDBLogger}} bzgl. der Attribute <code>readingInclude</code> und <code>readingInclude</code> bzw. ein Link ins Forum zu einem Beispiel für dessen Verwendung ({{Link2Forum|Topic=114860|Message=1119696|LinkText=Forum}}).

=== Loggen von Zuständen ===
Wie eingangs erwähnt, ist die Datenbank designt, numerische Werte zu loggen. Nichtnumerische Werte lassen sich nur über dem Umweg „tags“ in der Datenbank ablegen. ({{Link2Forum|Topic=114860|Message=1127469|LinkText=Forum}})
({{Link2Forum|Topic=114860|Message=1131301|LinkText=Forum}})

Sollen nun Zustände von z.B. Fenster- oder Türkontakten geloggt werden, kommt das Attribut <code> conversion </code> zum Einsatz. Mit ihm lassen sich Zustände entsprechend in Werte umwandeln.

Die jeweiligen Umwandelungen werden kommagetrennt aufgezählt. Mehrere Werte können durch ein pipe getrennt aufgezählt werden. Die Parameteraufzählung enthält dabei keine Leerzeichen.
Conversions sind nicht case sensitive ({{Link2Forum|Topic=114860|Message=1122035|LinkText=Forum}}).
Ein entsprechendes Beispiel für die Anwendung befindet sich in der commandref {{Link2CmdRef|Lang=de|Anker=InfluxDBLogger|Label=InfluxDBLogger}}.

=== Mehrere Logging-Devices ===
Um eine weitere Detaillierung des Loggings umzusetzen, bei unterschiedlicher Kombination von devspec, readingInclude, readingExclude, sowie der entsprechenden Limitierung der Events, sei an dieser Stelle ebenfalls darauf verwiesen, mehrere Definitionen des Moduls kombinieren zu können, z.B. 5 separate Logger, einer für Raumsensoren, einer für die Heizung, einer für Energiezähler, einer für das Wetter und ein weiterer für alles weitere Allgemeine.

=== Weiteres Feinetuning ===
Ohne weitere Definition von Attributen werden die numerischen Daten mit <code>Site_name</code> und <code>value</code> in die Datenbank geschrieben. Dieses ist historisch bedingt, siehe ({{Link2Forum|Topic=71551|Message=1072372|LinkText=Forum}}) und ({{Link2Forum|Topic=114860|Message=1090782|LinkText=Forum}}).

Als nützlich Kombination hat sich beispielsweise die Definition folgender Attribute herausgestellt:
<syntaxhighlight lang="Text">
attr influxDB fields $READINGNAME=$READINGVALUE
attr influxDB measurement $DEVICE
attr influxDB tags device={my $str = AttrVal($device,"alias",$device);; $str =~ s/\s/_/g;; return $str;;}
</syntaxhighlight>

Dieses führt dazu, dass
* das durch Unterstriche verbundene Alias als "_Device",
* der Devicename als "_Measurement",
* der Readingsname als "_Field"
verwendet wird.

Für alternative Verwendung der entsprechenden Attribute sei ebenfalls auf die ComandRef {{Link2CmdRef|Lang=de|Anker=InfluxDBLogger|Label=InfluxDBLogger}} verwiesen.

== Datenbank ==
Unterstützte Datenbanksysteme :
* influxDB 1.x
* influxDB 2.x

== Zusätzliches ==
=== Probleme bei der Authentifizierung ===
Bei der Ersteinrichtung des Moduls scheint es Konfigurations-Zustände zu geben, in denen die Authentifizierung trotz richtiger Zugangsdaten zunächst fehlschlägt (aufgetreten bei der Verwendung von Api v2) {{Link2Forum|Topic=121454|Message=1160757|LinkText=(Forum)}}. Dabei scheint es zu helfen, das Modul zu löschen und neu einzurichten.

Da dieses nur bei der Ersteinrichtung aufzutreten scheint, konnte die Ursache bislang noch nicht genauer identifiziert werden.

=== Migration von Altdaten ===
Zwei Hinweise ins Forum bzgl.
* Scripte, um filelogs zu migrieren: ({{Link2Forum|Topic=114860|Message=1104495|LinkText=Forum}}) oder ({{Link2Forum|Topic=71551|Message=732935|LinkText=Forum}})
* Scripte, um Mysql Daten zu migrieren: ({{Link2Forum|Topic=118049|Message=1129622|LinkText=Forum}}) oder ({{Link2Forum|Topic=71551|Message=838940|LinkText=Forum}}) oder ({{Link2Forum|Topic=71551|Message=895012|LinkText=Forum}}) oder ({{Link2Forum|Topic=71551|Message=895764|LinkText=Forum}})

=== Plot-Abrisse vermeiden ===
Mit der Verwendung einer vollkommen neuen Datenverarbeitung, wird auch die Problematik der Plot-Abrisse an Datumsübergängen wieder zum Thema. Da das Modul [[logProxy]] direkt auf der Ebene der Darstellung (SVG-Plot Definition) ansetzt, kann es hier nicht eingesetzt werden.

Das Modul InfluxDBLogger besitzt allerdings selbst die notwendige Funktionalität, um die aktuellen Werte der konfigurierten Readings der konfigurierten Geräte in die Datenbank zu schreiben (Verweis auf die Commandref von {{Link2CmdRef|Lang=de|Anker=InfluxDBLogger|Label=InfluxDBLogger}} für weitere Details).

Ein entsprechendes DOIF müsste dann so aussehen:
<syntaxhighlight lang="Text">
define addlog DOIF ([23:59:59] or [00:00:00])(set influxDB write)
attr addlog do always
</syntaxhighlight>

=== Device Alias mit Leerzeichen als tag ===
Über das Attribut <code>tags</code> lassen sich weitere Informationen den Daten hinzufügen wie z.B. die vergebenen Aliase der Devices. Haben diese allerdings Leerzeichen, schlägt das logging fehl. Eine Ersetzung der Leerzeichen in Aliasen und der Verwendung als tag kann über diese Attributdefinition realisiert werden ({{Link2Forum|Topic=114860|Message=1108269|LinkText=Forum}}):
<syntaxhighlight lang="Text">
attr influxDB tags device={my $str = AttrVal($device,"alias",$device);; $str =~ s/\s/_/g;; return $str;;}
</syntaxhighlight>

== Links ==
* https://www.influxdata.com/

[[Kategorie:Logging]]

InfluxDBLogger

2021-11-25T03:32:06Z

Joshi04: Mehrere kleinere Ergänzungen und Korrekturen

{{Todo|Dieser Artikel befindet sich im Aufbau und beschreibt daher anstatt einer kompletten Konfiguration bislang nur Teilabschnitte.}}
{{Infobox Modul
|ModPurpose=Protokolliert Ereignisse in einer Datenbank
|ModType=h
|ModForumArea=Unterstützende Dienste
|ModTechName=93_InfluxDBLogger.pm
|ModOwner={{Link2FU|41939|timmib}}
}}

Genau wie mit dem Modul [[DbLog]] lassen sich mit [[InfluxDBLogger]] Daten in einer Datenbank speichern.

Für die Vorteile der Speicherung von Daten in einer Datenbank sei auf die Beschreibung des Moduls ''DbLog'' verwiesen.

Einer der größten Unterschiede zu einer SQL-Datenbank ist die Tatsache, dass influxDB speziell darauf ausgelegt ist, große Messdatenmengen in kurzer Zeit zusammen mit einem Zeitstempel des Messzeitpunkts zu verarbeiten.

Des Weiteren ist ein sehr wichtiger Unterschied, dass nur numerische Werte verarbeitet werden. Dies kann die Kombination mit anderen Loggingmethodiken situationsabhängig sinnvoll machen. Textbasierte Werte können aber auch durch numerische Werte ersetzt werden.

Ein Interface oder eine Möglichkeit, die Daten mittels SVG-Plots darzustellen ist derzeit nicht vorhanden. Alternativ können die Daten mittels [[Grafana]] analysiert und visualisiert werden.

== Konfiguration ==
{{Randnotiz|RNText='''Alternativmodul'''
Um Missverständnisse zu vermeiden sei an dieser Stelle darauf hingewiesen, dass es bereits ein anderes Modul mit den Namen 93_InfluxDBLog für die Anbindung an eine InfluxDB gibt, das zu diesem Zeitpunkt (11/2021) allerdings scheint, nicht weiterentwickelt zu werden und um das es in diesem Artikel definitiv nicht geht. {{Link2Forum|Topic=71551|Message=1090783|LinkText=(Forum)}}

Für die Beschreibung der Einrichtung als native Installation in Verbindung mit einer InfluxDB 1.x sei auf [https://waschto.eu/2018/11/02/fhem-und-grafana-tool-zum-visualisieren-von-messdaten/ diesen Artikel] verwiesen. }}

Im folgenden wird auf die Einrichtung unter Docker (inkl. Docker-Compose) mit einer InfluxDB 2.0 eingegangen.

=== Einrichtung einer Datenbank ===
Voraussetzungen:
* Eine laufende Docker-Umgebung (inkl. Docker-Compose)
* Ein FHEM Docker-Image mit source Dateien im Unterordner ./fhem/build
* Die FHEM Konfiguration im Unterordner ./fhem/conf
* Das folgende file <code>docker-compose.yml</code> im Ausgangsordner
<syntaxhighlight lang="YAML">
version: '2.4'
services:

fhem2:
container_name: fhem2
build: ./fhem/build
restart: always
ports:
- 8083:8083
depends_on:
- influxdb
volumes:
- ./fhem/conf:/opt/fhem
environment:
- FHEM_UID=1000
- FHEM_GID=1000
- FHEM_PERM_DIR=0750
- FHEM_PERM_FILE=0640

influxdb:
image: influxdb:latest
restart: always
ports:
- 8086:8086
volumes:
# Mount for influxdb data directory and configuration
- ./influxdb/data:/var/lib/influxdb2:rw
- ./influxdb/config:/etc/influxdb2:rw
environment:
- DOCKER_INFLUXDB_INIT_MODE=setup
- DOCKER_INFLUXDB_INIT_USERNAME=${INFLUXDB_USERNAME}
- DOCKER_INFLUXDB_INIT_PASSWORD=${INFLUXDB_PASSWORD}
- DOCKER_INFLUXDB_INIT_ORG=${INFLUXDB_ORG}
- DOCKER_INFLUXDB_INIT_BUCKET=${INFLUXDB_BUCKET}
- DOCKER_INFLUXDB_INIT_ADMIN_TOKEN=${INFLUXDB_TOKEN}
</syntaxhighlight>

An dieser Stelle sei empfohlen, die Zugangsinformationen in eine .env Datei auszulagern, die zugriffsbeschränkt im gleichen Verzeichnis liegt, wie die <code>docker-compose.yml</code> Datei.
<syntaxhighlight lang="YAML">
INFLUXDB_USERNAME=myusername
INFLUXDB_PASSWORD=passwordpasswordpassword
INFLUXDB_ORG=myorg
INFLUXDB_BUCKET=mybucket
INFLUXDB_ADMIN_TOKEN=mytoken
</syntaxhighlight>

Die Unterverzeichnisse für die InfluxDB Datenbank (./influxdb/data), sowie die Konfiguration (./influxdb/config) werden automatisch beim ersten Starten erstellt.

Der Eintrag "DOCKER_INFLUXDB_INIT_MODE=setup" führt dazu, dass die Datenbank beim ersten Starten initialisiert wird, dieses aber nur, falls keine Datenbank gefunden wird. So kann dieser Eintrag für die spätere Verwendung in der Konfiguration verbleiben und muss nicht entfernt werden.

Mit dieser Konfiguration ist FHEM über <code><ip-des-docker-servers>:8083</code> erreichbar, das Webinterface von InfluxDB über <code><ip-des-docker-servers>:8086</code> erreichbar.

Die gesamte Konfiguration kann über
:<code>docker-compose up -d </code>
gestartet, bzw. über
:<code>docker-compose down </code>
gestoppt werden.

=== Konfiguration des Loggers als Device ===
{{Randnotiz|RNText='''Unterschiede zur Definition von DBLog'''
Um Fehlern bei der Umstellung von DBLog auf InfluxDBLogger zu vermeiden, anders als bei DBLog werden bei der Definition nur die Devices definiert und nicht zusätzlich auch die Readings {{Link2Forum|Topic=114860|Message=1119696|LinkText=(Forum).}}. }}

Das InfluxDBLogger Device wird dann definiert mit
:<code>define <Device-name> InfluxDBLogger [http|https]://IP_or_Hostname:port dbname devspec,devspec,<weitere devspec></code>

wobei bei der Verwendung der InfluxDB Version 2 folgende Attributfestlegungen notwendig werden:
* Das Attribut api=v2, dass die InfluxDV Version 2 festlegt. Hiermit wird auch das Setzten der Org mit dem folgenden Attribut notwendig, wie auch die Verknüpfung des Buckets als ''dbname''.
* Das Attribut org=myorg, dass die vergebene Org festlegt.
* Das Attribut security=token, dass die Verwendung eines Tokens festlegt. Hiermit ist ebenfalls das Definieren eines Users als Attribut und das Setzen eines Passwortes überflüssig. Der Token wird über <code> set <Device-name> token <mytoken></code> festlegt.

Ein Beispiel für eine Konfiguration wäre:
<pre>
define influxDB InfluxDBLogger http://10.10.120.106:8086 FHEM-bucket DB_Temp_Hum,KU_Temp_Hum,FL_Temp_Hum
attr influxDB api v2
attr influxDB org myorg
attr influxDB security token
</pre>

=== Finetuning des Loggings ===
Bei der Optimierung ist der Einschränkung an der Quelle (am jeweiligen Device) immer der Vorzug zu geben vor der der Einschränkung an zentraler Stelle um unnötig entstehende Daten zu vermeiden. Allerdings kann es Fälle geben, in denen eine Whitelist oder Blacklist bzgl. der Definition, welche der entstandenen Event geloggt werden sollen, sinnvoll sein kann.

Dieses kann exklusiv oder zusätzlich zu den im Folgenden genannten Einschränkungen über die jeweiligen Devices an zentraler Stelle geschehen.

==== Einschränkung über die jeweiligen Devices ====
Da in Abhängigkeit von Events Einträge in die Datenbank geschrieben werden, lassen sich die gleichen Prinzipien anwenden, wie bei [[DbLog]] und [[FileLog]] um Events zu unterdrücken:
* event-min-interval, event-on-change-reading und event-on-update-reading beeinflussen, wie häufig Werte geloggt werden (vgl. {{Link2CmdRef|Lang=de|Anker=event-on-update-reading}})
* event-aggregator
{{Link2Forum|Topic=114860|Message=1110435|LinkText=(Forum)}}

==== Einschränkung über den zentralen <code>define</code>-Eintrag ====

Verweis auf die commandref {{Link2CmdRef|Lang=de|Anker=InfluxDBLogger|Label=InfluxDBLogger}} bzgl. der Attribute <code>readingInclude</code> und <code>readingInclude</code> bzw. ein Link ins Forum zu einem Beispiel für dessen Verwendung {{Link2Forum|Topic=114860|Message=1119696|LinkText=(Forum)}}.

== Datenbank ==
Unterstützte Datenbanksysteme :
* influxDB 1.x
* influxDB 2.x

== Zusätzliches ==

=== Probleme bei der Authentifizierung ===
Bei der Ersteinrichtung des Moduls scheint es Konfigurations-Zustände zu geben, in denen die Authentifizierung trotz richtiger Zugangsdaten zunächst fehlschlägt (aufgetreten bei der Verwendung von Api v2) {{Link2Forum|Topic=121454|Message=1160757|LinkText=(Forum)}}. Dabei scheint es zu helfen, das Modul zu löschen und neu einzurichten.

Da dieses nur bei der Ersteinrichtung aufzutreten scheint, konnte die Ursache bislang noch nicht genauer identifiziert werden.

=== Migration von Altdaten ===
Zwei Hinweise ins Forum bzgl.
* Ein Script, um filelogs zu migrieren {{Link2Forum|Topic=114860|Message=1104495|LinkText=(Forum)}}.
* Ein Script, um Mysql Daten zu migrieren {{Link2Forum|Topic=118049|Message=1129622|LinkText=(Forum)}}

=== Plot-Abrisse vermeiden ===
Mit der Verwendung einer vollkommen neuen Datenverarbeitung, wird auch die Problematik der Plot-Abrisse an Datumsübergängen wieder zum Thema. Da das Modul [[logProxy]] direkt auf der Ebene der Darstellung (SVG-Plot Definition) ansetzt, kann es hier nicht eingesetzt werden.

Das Modul InfluxDBLogger besitzt allerdings selbst die notwendige Funktionalität, um die aktuellen Werte der konfigurierten Readings der konfigurierten Geräte in die Datenbank zu schreiben (Verweis auf die Commandref von {{Link2CmdRef|Lang=de|Anker=InfluxDBLogger|Label=InfluxDBLogger}} für weitere Details).

Ein entsprechendes DOIF müsste dann so aussehen:
<pre>
define addlog DOIF ([23:59:59] or [00:00:00])(set influxDB write)
attr addlog do always
</pre>

=== Device Alias mit Leerzeichen als tag ===
Über das Attribut <code>tags</code> lassen sich weitere Informationen den Daten hinzufügen wie z.B. die vergebenen Aliase der Devices. Haben diese allerdings Leerzeichen, schlägt das logging fehl. Eine Ersetzung der Leerzeichen in Aliasen und der Verwendung als tag kann über diese Attributdefinition realisiert werden {{Link2Forum|Topic=114860|Message=1108269|LinkText=(Forum)}}:
<pre>
attr influxDB tags device={my $str = AttrVal($device,"alias",$device);; $str =~ s/\s/_/g;; return $str;;}
</pre>

[[Kategorie:Logging]]

InfluxDBLogger

2021-11-21T13:45:43Z

Joshi04: Schreibfehler korrigiert / Verwendung von .env für "Geheimnisse" / Prob bei Ersteinrichtungsauthentifizierung

{{Todo|Dieser Artikel befindet sich im Aufbau und beschreibt daher anstatt einer kompletten Konfiguration bislang nur Teilabschnitte.}}
{{Infobox Modul
|ModPurpose=Protokolliert Ereignisse in einer Datenbank
|ModType=h
|ModForumArea=Unterstützende Dienste
|ModTechName=93_InfluxDBLogger.pm
|ModOwner={{Link2FU|41939|timmib}}
}}
Genau wie mit dem Modul [[DbLog]] lassen sich mit [[InfluxDBLogger]] Daten in einer Datenbank speichern.

Für die Vorteile der Speicherung von Daten in einer Datenbank sei auf die Beschreibung des Moduls ''DbLog'' verwiesen.

Einer der größten Unterschiede zu einer SQL-Datenbank ist die Tatsache, dass influxDB speziell darauf ausgelegt ist, große Messdatenmengen in kurzer Zeit zusammen mit einem Zeitstempel des Messzeitpunkts zu verarbeiten.

Des Weiteren ist ein sehr wichtiger Unterschied, dass nur numerische Werte verarbeitet werden. Dies kann die Kombination mit anderen Loggingmethodiken situationsabhängig sinnvoll machen. Textbasierte Werte können aber auch durch numerische Werte ersetzt werden.

Ein Interface oder eine Möglichkeit, die Daten mittels SVG-Plots darzustellen ist derzeit nicht vorhanden. Alternativ können die Daten mittels [[Grafana]] analysiert und visualisiert werden.

== Konfiguration ==
Für die Beschreibung der Einrichtung als native Installation in Verbindung mit einer InfluxDB 1.x sei auf [https://waschto.eu/2018/11/02/fhem-und-grafana-tool-zum-visualisieren-von-messdaten/ diesen Artikel] verwiesen.

Im folgenden wird auf die Einrichtung unter Docker (inkl. Docker-Compose) mit einer InfluxDB 2.0 eingegangen.

=== Einrichtung einer Datenbank ===
Voraussetzungen:
* Eine laufende Docker-Umgebung (inkl. Docker-Compose)
* Ein FHEM Docker-Image mit source Dateien im Unterordner ./fhem/build
* Die FHEM Konfiguration im Unterordner ./fhem/conf
* Das folgende file <code>docker-compose.yml</code> im Ausgangsordner
<syntaxhighlight lang="YAML">
version: '2.4'
services:

fhem2:
container_name: fhem2
build: ./fhem/build
restart: always
ports:
- 8083:8083
depends_on:
- influxdb
volumes:
- ./fhem/conf:/opt/fhem
environment:
- FHEM_UID=1000
- FHEM_GID=1000
- FHEM_PERM_DIR=0750
- FHEM_PERM_FILE=0640

influxdb:
image: influxdb:latest
restart: always
ports:
- 8086:8086
volumes:
# Mount for influxdb data directory and configuration
- ./influxdb/data:/var/lib/influxdb2:rw
- ./influxdb/config:/etc/influxdb2:rw
environment:
- DOCKER_INFLUXDB_INIT_MODE=setup
- DOCKER_INFLUXDB_INIT_USERNAME=${INFLUXDB_USERNAME}
- DOCKER_INFLUXDB_INIT_PASSWORD=${INFLUXDB_PASSWORD}
- DOCKER_INFLUXDB_INIT_ORG=${INFLUXDB_ORG}
- DOCKER_INFLUXDB_INIT_BUCKET=${INFLUXDB_BUCKET}
- DOCKER_INFLUXDB_INIT_ADMIN_TOKEN=${INFLUXDB_TOKEN}
</syntaxhighlight>

An dieser Stelle sei empfohlen, die Zugangsinformationen in eine .env Datei auszulagern, die zugriffsbeschränkt im gleichen Verzeichnis liegt, wie die <code>docker-complose.yml</code> Datei.
<syntaxhighlight lang="YAML">
INFLUXDB_USERNAME=myusername
INFLUXDB_PASSWORD=passwordpasswordpassword
INFLUXDB_ORG=myorg
INFLUXDB_BUCKET=mybucket
INFLUXDB_ADMIN_TOKEN=mytoken
</syntaxhighlight>

Die Unterverzeichnisse für die InfluxDB Datenbank (./influxdb/data), sowie die Konfiguration (./influxdb/config) werden automatisch beim ersten Starten erstellt.

Der Eintrag "DOCKER_INFLUXDB_INIT_MODE=setup" führt dazu, dass die Datenbank beim ersten Starten initialisiert wird, dieses aber nur, falls keine Datenbank gefunden wird. So kann dieser Eintrag für die spätere Verwendung in der Konfiguration verbleiben und muss nicht entfernt werden.

Mit dieser Konfiguration ist fhem über <code><ip-des-docker-servers>:8083</code> erreichbar, das Webinterface von InfluxDB über <code><ip-des-docker-servers>:8086</code> erreichbar.

Die gesamte Konfiguration kann über
:<code>docker-compose up -d </code>
gestartet, bzw. über
:<code>docker-compose down </code>
gestoppt werden.

=== Konfiguration des Loggers als Device ===
Das InfluxDBLogger Device wird dann definiert mit
:<code>define <Device-name> InfluxDBLogger [http|https]://IP_or_Hostname:port dbname devspec,devspec,<weitere devspec></code>

wobei bei der Verwendung der InfluxDB Version 2
* ''dbname'' dem vergebenen Bucket entspricht.
* Das Attribut api=v2 die InfluxDV Version 2 festlegt.
* Das Attribut org=myorg die vergebene Org festlegt.
* Das Attribut security=token die Verwendung eines Tokens festlegt.

Der Token wird über <code> set <Device-name> token <mytoken></code> festlegt.

Ein Beispiel für eine Konfiguration wäre:
<pre>
define influxDB InfluxDBLogger http://10.10.120.106:8086 FHEM-bucket DB_Temp_Hum,KU_Temp_Hum,FL_Temp_Hum
attr influxDB api v2
attr influxDB org myorg
attr influxDB security token
</pre>

=== Finetuning des Loggings ===
{{Todo|Todo}}

==== Einschränkung über den zentralen <code>define</code>-Eintrag ====
{{Todo|Todo}}

==== Einschränkung über die jeweiligen Devices ====
Da in Abhängigkeit von Events Einträge in die Datenbank geschrieben werden, lassen sich die gleichen Prinzipien anwenden, wie bei [[DbLog]] und [[FileLog]] um Events zu unterdrücken:
* event-min-interval, event-on-change-reading und event-on-update-reading beeinflussen, wie häufig Werte geloggt werden (vgl. {{Link2CmdRef|Lang=de|Anker=event-on-update-reading}})

== Datenbank ==
Unterstützte Datenbanksysteme :
* influxDB 1.x
* influxDB 2.x

== Zusätzliches ==
=== Plot-Abrisse vermeiden ===
Mit der Verwendung einer vollkommen neuen Datenverarbeitung, wird auch die Problematik der Plot-Abrisse an Datumsübergängen wieder zum Thema. Da das Modul [[logProxy]] direkt auf der Ebene der Darstellung (SVG-Plot Definition) ansetzt, kann es hier nicht eingesetzt werden.

Das Modul InfluxDBLogger besitzt allerdings selbst die notwendige Funktionalität, um die aktuellen Werte der konfigurierten Readings der konfigurierten Geräte in die Datenbank zu schreiben (Verweis auf die Commandref von {{Link2CmdRef|Lang=de|Anker=InfluxDBLogger|Label=InfluxDBLogger}} für weitere Details).

Ein entsprechendes DOIF müsste dann so aussehen:
<pre>
define addlog DOIF ([23:59:59] or [00:00:00])(set influxDB write)
attr addlog do always
</pre>

=== Probleme bei der Authentifizierung ===
Bei der Ersteinrichtung des Moduls scheint es Konfigurations-Zustände zu geben, in denen die Authentifizierung trotz richtiger Zugangsdaten zunächst fehlschlägt (aufgetreten bei der Verwendung von Api v2) {{Link2Forum|Topic=121454|Message=1160757|LinkText=(Forum)}}. Dabei scheint es zu helfen, das Modul zu löschen und neu einzurichten.

Da dieses nur bei der Ersteinrichtung aufzutreten scheint, konnte die Ursache bislang noch nicht genauer identifiziert werden.

[[Kategorie:Logging]]

Plot-Abriss vermeiden

2021-11-21T08:40:04Z

Joshi04: /* Alternativen */

{{Randnotiz|RNTyp=g|RNText='''HINWEIS''': Es gibt mittlerweile (12/2019) das Attribut ''addLog'' für [[FileLog]] Devices.
This attribute takes a comma-separated list of devspec:reading:maxInterval triples. You may use regular expressions for reading. The last value of the reading will be written to the logfile, if after maxInterval seconds no event for this device/reading has arrived.

Siehe auch {{Link2Forum|Topic=106489|LinkText=dieses Forenthema}}.}}
== Attribut addLog ==
Seit 12/2019 können mit dem Attribut ''addLog'' am [[FileLog]] Device maximale Zeitspannen vorgegeben werden, nach denen der letzte bekannte Wert des Readings erneut in das Logfile übernommen werden soll, sofern zwischenzeitlich kein neuer Wert eingetroffen ist. Im Attribut sind Triplette in der Form <code>devspec:reading:maxInterval</code> anzugeben, mehrere Einträge durch Komma getrennt. Die betreffenden Devices und Readings können über Regex bestimmt werden.

== Timerbasierte Zusatzeinträge ==
=== Motivation ===
Bei Nutzung des Attributs <code>event-on-change</code> werden Log-Einträge nur bei Werteänderung geschrieben. Dies führt
# zum Abriss der Logs zum Ende des alten und zum Beginn des neuen Tages
# zu inadäquat langen Pausen zwischen Logeinträgen, z.B. für <code>actuator</code>, der z.B. in den Wintermonaten bei Anwesenheit durchgängig 100%, bei Abwesenheit durchgängig 0% betragen kann. Der Wechsel zwischen diesen Werten wird mit langen Flanken dargestellt.

=== Funktionsweise ===
Aus diesem Grund wurde die Routine <code>addLog</code> erstellt (siehe [[#Implementierung|Implementierung]]).
Sie fügt zu definierten Zeitpunkten Einträge im Log hinzu.
Dadurch sollen die o.g. Effekte vermieden werden.
Zusätzliche Einträge sind mit dem Anhang <code><< addLog</code> gekennzeichnet.
Der Aufruf erfolgt sinnvollerweise aus einem <code>at</code> oder einem <code>DOIF</code>.
Üblich ist der Aufruf für alle Geräte bzw. readings, für die <code>event-on-change</code> gesetzt ist.

Die Routine hat zwei Aufrufparameter:
<syntaxhighlight lang=text>
addLog(<devicename>, <reading>)
</syntaxhighlight>

=== Beispiele aus fhem.cfg ===
<syntaxhighlight lang=text>
### jede Stunde einen Eintrag für FHT actuator
define a_actuator at +*01:00 {addLog("ez_FHT","actuator")}
attr a_actuator room 99_System
</syntaxhighlight>

<code>addLog</code> für mehrere <code>devices</code> in einem "Makro" zusammenfassen:
<syntaxhighlight lang=text>
define addLog notify addLog {addLog("ez_Aussensensor","state");;\
addLog("ez_FHT","actuator");;\
addLog("ez_FHT","measured-temp");;\
addLog("MunichWeather","humidity");;\
addLog("MunichWeather","pressure");;\
addLog("MunichWeather","temperature");;\
addLog("MunichWeather","wind_chill");;}
attr addLog room 99_System
</syntaxhighlight>

<syntaxhighlight lang=text>
### Hier ist ein trigger des o.g. notify verwendet, um nicht in beiden at-defines alle Aufrufe listen zu müssen.
define a_midnight1 at *23:59 trigger addLog
attr a_midnight1 room 99_System
define a_midnight2 at *00:01 trigger addLog
attr a_midnight2 room 99_System
# Alternativ können auch die Einzelaufrufe direkt im at erfolgen, z.B.
define a_midnight_before at *23:59 {addLog("device","reading")}
</syntaxhighlight>

===Beispiele mit DOIF ===
Seitdem es [[DOIF]] gibt, lässt sich das Ganze auch etwas anders umsetzen:

<syntaxhighlight lang=text>
define DF_addLogDaily DOIF ([23:59] or [00:01]) ({addLog("ez_FHT", "actuator")})
attr DF_addLogDaily room 99_System
attr DF_addLogDaily do always
</syntaxhighlight>
Da mit diesem Aufruf aber die Problematik nur nach unten verschoben wird (Zoom auf Stunde oder Vierteltag),
ist folgendes möglich:
<syntaxhighlight lang=text>
define DF_addLogHourly DOIF ([:59] or [:01]) ({addLog("ez_FHT", "actuator")})
attr DF_addLogHourly room 99_System
attr DF_addLogHourly do always
</syntaxhighlight>
Das Ganze lässt sich auch noch auf minütlich runterbrechen, erzeugt dadurch ggf. eine große Menge Logeinträge. Dies sollte man stets bedenken.

=== Log-Beispiele ===
<syntaxhighlight lang=text>
2012-11-04_23:46:28 ez_Aussensensor T: 9.4 H: 78.5
2012-11-04_23:59:00 ez_Aussensensor T: 9.4 H: 78.5 << addLog
2012-11-04_23:59:00 ez_FHT actuator: 0% << addLog
2012-11-04_23:59:00 ez_FHT measured-temp: 17.4 << addLog
2012-11-05_00:01:00 ez_Aussensensor T: 9.4 H: 78.5 << addLog
2012-11-05_00:01:00 ez_FHT actuator: 0% << addLog
2012-11-05_00:01:00 ez_FHT measured-temp: 17.4 << addLog
2012-11-05_00:24:31 ez_FHT actuator: 0% << addLog
2012-11-05_00:42:32 ez_Aussensensor T: 9.1 H: 78.1
2012-11-05_16:02:59 ez_Aussensensor T: 10.3 H: 65.9
2012-11-05_16:05:56 ez_Aussensensor T: 10.2 H: 66.3
2012-11-05_16:21:47 ez_Aussensensor T: 10.2 H: 66.3 << addLog
2012-11-05_16:21:48 ez_FHT actuator: 100% << addLog
2012-11-05_16:21:48 ez_FHT measured-temp: 18.5 << addLog
2012-11-05_16:30:26 ez_FHT measured-temp: 18.7
2012-11-05_16:44:18 ez_Aussensensor T: 9.9 H: 65.8
</syntaxhighlight>

=== Nebeneffekte ===
<code>addLog</code> verwendet die Funktion <code>trigger</code>.
Für fhem ist das gleichwertig mit dem Eintreffen eines Ereignisses.
Es werden also ggf. alle <code>notifies</code> ausgeführt, die für das relevante Gerät abzuarbeiten sind.
Dies ist wohl zu bedenken, bevor man <code>addLog</code> verwendet.

=== Bekannte Probleme ===
Das Modul [[dewpoint]] fügt dem <code>state</code> eines <code>device</code> den zusatz <code>D: xx</code> hinzu.
Abhängig vom Timing kann dies zu "verwurschtelten" Darstellungen führen.
Die Verwendung von <code>addLog</code> in Verbindung mit <code>dewpoint</code> ist daher nicht empfohlen.

=== Implementierung ===
Die Routine wird in eine lokale Programmdatei integriert, z.B. <code>99_myUtils.pm</code> (siehe [[99 myUtils anlegen]]).
Wird die Funktion dort mit einem externen Editor eingefügt, muss anschließend <code>reload 99_myUtils.pm</code> ausgeführt werden.
Auf Fehlermeldungen im fhem.log achten.
<syntaxhighlight lang=perl>
#### Log-abriss vermeiden
# called by
# define addLog notify addLog {addLog("ez_Aussensensor","state");;\
# addLog("ez_FHT","actuator");;\
# addLog("MunichWeather","humidity");;\
# addLog("MunichWeather","pressure");;\
# addLog("MunichWeather","temperature");;\
# addLog("MunichWeather","wind_chill");;}
# define a_midnight1 at *23:59 trigger addLog
# define a_midnight2 at *00:01 trigger addLog
sub
addLog($$) {
my ($logdevice, $reading) = @_; # device and reading to be used
my $logentry = ReadingsVal($logdevice,$reading,"addLog: invalid reading");
if ($reading =~ m,state,i) {
fhem "trigger $logdevice $logentry << addLog";
} else {
fhem "trigger $logdevice $reading: $logentry << addLog";
}
}
</syntaxhighlight>

Zu Problemen mit diesem Code, der auch die Sonderbehandlung des speziellen FHEM-Readings <code>state</code> sicherstellen soll, in Verbindung mit anderen Readingnamen, die den Bestandteil "state" in beliebiger Groß-/Kleinschreibung und an beliebiger Position beinhalten siehe {{Link2Forum|Topic=92111|LinkText=dieses Forenthema}} mit Lösungsansätzen.

== Alternativen ==
Um Plot-Abrisse zu vermeiden, kann man auch [[LogProxy]] verwenden (sofern erforderlich iVm. dem ''createGluedFile''-Attribut des FileLog-Devices).
Da das Modul LogProxy direkt auf der Ebene der Darstellung (SVG-Plot Definition) ansetzt, kann es bei der Darstellung von Daten auf andere Weise (z.B. [[Grafana]] nicht verwendet werden.

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

Plot-Abriss vermeiden

2021-11-21T08:39:35Z

Joshi04: /* Alternativen */ Hinweis: LogProxy nur für SVG-Plot Definitionen hinzugefügt.

{{Randnotiz|RNTyp=g|RNText='''HINWEIS''': Es gibt mittlerweile (12/2019) das Attribut ''addLog'' für [[FileLog]] Devices.
This attribute takes a comma-separated list of devspec:reading:maxInterval triples. You may use regular expressions for reading. The last value of the reading will be written to the logfile, if after maxInterval seconds no event for this device/reading has arrived.

Siehe auch {{Link2Forum|Topic=106489|LinkText=dieses Forenthema}}.}}
== Attribut addLog ==
Seit 12/2019 können mit dem Attribut ''addLog'' am [[FileLog]] Device maximale Zeitspannen vorgegeben werden, nach denen der letzte bekannte Wert des Readings erneut in das Logfile übernommen werden soll, sofern zwischenzeitlich kein neuer Wert eingetroffen ist. Im Attribut sind Triplette in der Form <code>devspec:reading:maxInterval</code> anzugeben, mehrere Einträge durch Komma getrennt. Die betreffenden Devices und Readings können über Regex bestimmt werden.

== Timerbasierte Zusatzeinträge ==
=== Motivation ===
Bei Nutzung des Attributs <code>event-on-change</code> werden Log-Einträge nur bei Werteänderung geschrieben. Dies führt
# zum Abriss der Logs zum Ende des alten und zum Beginn des neuen Tages
# zu inadäquat langen Pausen zwischen Logeinträgen, z.B. für <code>actuator</code>, der z.B. in den Wintermonaten bei Anwesenheit durchgängig 100%, bei Abwesenheit durchgängig 0% betragen kann. Der Wechsel zwischen diesen Werten wird mit langen Flanken dargestellt.

=== Funktionsweise ===
Aus diesem Grund wurde die Routine <code>addLog</code> erstellt (siehe [[#Implementierung|Implementierung]]).
Sie fügt zu definierten Zeitpunkten Einträge im Log hinzu.
Dadurch sollen die o.g. Effekte vermieden werden.
Zusätzliche Einträge sind mit dem Anhang <code><< addLog</code> gekennzeichnet.
Der Aufruf erfolgt sinnvollerweise aus einem <code>at</code> oder einem <code>DOIF</code>.
Üblich ist der Aufruf für alle Geräte bzw. readings, für die <code>event-on-change</code> gesetzt ist.

Die Routine hat zwei Aufrufparameter:
<syntaxhighlight lang=text>
addLog(<devicename>, <reading>)
</syntaxhighlight>

=== Beispiele aus fhem.cfg ===
<syntaxhighlight lang=text>
### jede Stunde einen Eintrag für FHT actuator
define a_actuator at +*01:00 {addLog("ez_FHT","actuator")}
attr a_actuator room 99_System
</syntaxhighlight>

<code>addLog</code> für mehrere <code>devices</code> in einem "Makro" zusammenfassen:
<syntaxhighlight lang=text>
define addLog notify addLog {addLog("ez_Aussensensor","state");;\
addLog("ez_FHT","actuator");;\
addLog("ez_FHT","measured-temp");;\
addLog("MunichWeather","humidity");;\
addLog("MunichWeather","pressure");;\
addLog("MunichWeather","temperature");;\
addLog("MunichWeather","wind_chill");;}
attr addLog room 99_System
</syntaxhighlight>

<syntaxhighlight lang=text>
### Hier ist ein trigger des o.g. notify verwendet, um nicht in beiden at-defines alle Aufrufe listen zu müssen.
define a_midnight1 at *23:59 trigger addLog
attr a_midnight1 room 99_System
define a_midnight2 at *00:01 trigger addLog
attr a_midnight2 room 99_System
# Alternativ können auch die Einzelaufrufe direkt im at erfolgen, z.B.
define a_midnight_before at *23:59 {addLog("device","reading")}
</syntaxhighlight>

===Beispiele mit DOIF ===
Seitdem es [[DOIF]] gibt, lässt sich das Ganze auch etwas anders umsetzen:

<syntaxhighlight lang=text>
define DF_addLogDaily DOIF ([23:59] or [00:01]) ({addLog("ez_FHT", "actuator")})
attr DF_addLogDaily room 99_System
attr DF_addLogDaily do always
</syntaxhighlight>
Da mit diesem Aufruf aber die Problematik nur nach unten verschoben wird (Zoom auf Stunde oder Vierteltag),
ist folgendes möglich:
<syntaxhighlight lang=text>
define DF_addLogHourly DOIF ([:59] or [:01]) ({addLog("ez_FHT", "actuator")})
attr DF_addLogHourly room 99_System
attr DF_addLogHourly do always
</syntaxhighlight>
Das Ganze lässt sich auch noch auf minütlich runterbrechen, erzeugt dadurch ggf. eine große Menge Logeinträge. Dies sollte man stets bedenken.

=== Log-Beispiele ===
<syntaxhighlight lang=text>
2012-11-04_23:46:28 ez_Aussensensor T: 9.4 H: 78.5
2012-11-04_23:59:00 ez_Aussensensor T: 9.4 H: 78.5 << addLog
2012-11-04_23:59:00 ez_FHT actuator: 0% << addLog
2012-11-04_23:59:00 ez_FHT measured-temp: 17.4 << addLog
2012-11-05_00:01:00 ez_Aussensensor T: 9.4 H: 78.5 << addLog
2012-11-05_00:01:00 ez_FHT actuator: 0% << addLog
2012-11-05_00:01:00 ez_FHT measured-temp: 17.4 << addLog
2012-11-05_00:24:31 ez_FHT actuator: 0% << addLog
2012-11-05_00:42:32 ez_Aussensensor T: 9.1 H: 78.1
2012-11-05_16:02:59 ez_Aussensensor T: 10.3 H: 65.9
2012-11-05_16:05:56 ez_Aussensensor T: 10.2 H: 66.3
2012-11-05_16:21:47 ez_Aussensensor T: 10.2 H: 66.3 << addLog
2012-11-05_16:21:48 ez_FHT actuator: 100% << addLog
2012-11-05_16:21:48 ez_FHT measured-temp: 18.5 << addLog
2012-11-05_16:30:26 ez_FHT measured-temp: 18.7
2012-11-05_16:44:18 ez_Aussensensor T: 9.9 H: 65.8
</syntaxhighlight>

=== Nebeneffekte ===
<code>addLog</code> verwendet die Funktion <code>trigger</code>.
Für fhem ist das gleichwertig mit dem Eintreffen eines Ereignisses.
Es werden also ggf. alle <code>notifies</code> ausgeführt, die für das relevante Gerät abzuarbeiten sind.
Dies ist wohl zu bedenken, bevor man <code>addLog</code> verwendet.

=== Bekannte Probleme ===
Das Modul [[dewpoint]] fügt dem <code>state</code> eines <code>device</code> den zusatz <code>D: xx</code> hinzu.
Abhängig vom Timing kann dies zu "verwurschtelten" Darstellungen führen.
Die Verwendung von <code>addLog</code> in Verbindung mit <code>dewpoint</code> ist daher nicht empfohlen.

=== Implementierung ===
Die Routine wird in eine lokale Programmdatei integriert, z.B. <code>99_myUtils.pm</code> (siehe [[99 myUtils anlegen]]).
Wird die Funktion dort mit einem externen Editor eingefügt, muss anschließend <code>reload 99_myUtils.pm</code> ausgeführt werden.
Auf Fehlermeldungen im fhem.log achten.
<syntaxhighlight lang=perl>
#### Log-abriss vermeiden
# called by
# define addLog notify addLog {addLog("ez_Aussensensor","state");;\
# addLog("ez_FHT","actuator");;\
# addLog("MunichWeather","humidity");;\
# addLog("MunichWeather","pressure");;\
# addLog("MunichWeather","temperature");;\
# addLog("MunichWeather","wind_chill");;}
# define a_midnight1 at *23:59 trigger addLog
# define a_midnight2 at *00:01 trigger addLog
sub
addLog($$) {
my ($logdevice, $reading) = @_; # device and reading to be used
my $logentry = ReadingsVal($logdevice,$reading,"addLog: invalid reading");
if ($reading =~ m,state,i) {
fhem "trigger $logdevice $logentry << addLog";
} else {
fhem "trigger $logdevice $reading: $logentry << addLog";
}
}
</syntaxhighlight>

Zu Problemen mit diesem Code, der auch die Sonderbehandlung des speziellen FHEM-Readings <code>state</code> sicherstellen soll, in Verbindung mit anderen Readingnamen, die den Bestandteil "state" in beliebiger Groß-/Kleinschreibung und an beliebiger Position beinhalten siehe {{Link2Forum|Topic=92111|LinkText=dieses Forenthema}} mit Lösungsansätzen.

== Alternativen ==
Um Plot-Abrisse zu vermeiden, kann man auch [[LogProxy]] verwenden (sofern erforderlich iVm. dem ''createGluedFile''-Attribut des FileLog-Devices).
Da das Modul logProxy direkt auf der Ebene der Darstellung (SVG-Plot Definition) ansetzt, kann es bei der Darstellung von Daten auf andere Weise (z.B. [[Grafana]] nicht verwendet werden.

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

InfluxDBLogger

2021-11-21T08:29:24Z

Joshi04: Hinweis für "Plot-Abrisse vermeiden" hinzugefügt.

{{Infobox Modul
|ModPurpose=Protokolliert Ereignisse in einer Datenbank
|ModType=h
|ModForumArea=Unterstützende Dienste
|ModTechName=93_InfluxDBLogger.pm
|ModOwner=timmib ({{Link2FU|41939|Forum}})
}}

{{Todo|Dieser Artikel befindet sich im Aufbau und beschreibt daher anstatt einer kompletten Konfiguration bislang nur Teilabschnitte.}}

== Einleitung ==
Genauso, wie das Modul {{Link2CmdRef|Lang=de|Anker=DbLog|Label=DbLog}} lassen sich mit dem Modul {{Link2CmdRef|Lang=de|Anker=InfluxDBLogger|Label=InfluxDBLogger}} Daten in einer Datenbank speichern.

Für die Vorteile der Speicherung von Daten in einer Datenbank sei auf den Artikel über das Modul [[DbLog]] verwiesen.

Einer der größten Unterschiede zu einer SQL-Datenbank ist die Tatsache, dass influxDB speziell darauf ausgelegt ist, große Messdatenmengen in kurzer Zeit zusammen mit einem Zeitstempel des Messzeitpunkts zu verarbeiten.

Des Weiteren ist ein sehr wichtiger Unterschied, dass nur numerische Werte verarbeitet werden. Dies kann die Kombination mit anderen Loggingmethodiken situationsabhängig sinnvoll machen. Textbasierte Werte können aber auch durch numerische Werte ersetzt werden.

Ein Interface oder eine Möglichkeit, die Daten mittels SVG-Plots darzustellen ist derzeit nicht vorhanden. Alternativ können die Daten mittels [[Grafana]] analysiert und visualisiert werden.

== Konfiguration ==
Für die Beschreibung der Einrichtung als native Installation in Verbindung mit einer InflixDB 1.x sei auf [https://waschto.eu/2018/11/02/fhem-und-grafana-tool-zum-visualisieren-von-messdaten/ diesen Artikel] verwiesen.

Im folgenden wird auf die Einrichtung unter Docker (inkl. Docker-Compose) mit einer InflixDB 2.0 eingegangen.

=== Einrichtung einer Datenbank ===
Voraussetzungen:
* Eine laufende Docker-Umgebung (inkl. Docker-Compose)
* Ein FHEM Docker-Image mit source Dateien im Unterordner ./fhem/build
* Die FHEM Konfiguration im Unterordner ./fhem/conf
* Das folgende file <code>docker-compose.yml</code> im Ausgangsordner
<pre>
version: '2.4'
services:

fhem2:
container_name: fhem2
build: ./fhem/build
restart: always
ports:
- 8083:8083
depends_on:
- influxdb
volumes:
- ./fhem/conf:/opt/fhem
environment:
- FHEM_UID=1000
- FHEM_GID=1000
- FHEM_PERM_DIR=0750
- FHEM_PERM_FILE=0640

influxdb:
image: influxdb:latest
restart: always
ports:
- 8086:8086
volumes:
# Mount for influxdb data directory and configuration
- ./influxdb/data:/var/lib/influxdb2:rw
- ./influxdb/config:/etc/influxdb2:rw
environment:
- DOCKER_INFLUXDB_INIT_MODE=setup
- DOCKER_INFLUXDB_INIT_USERNAME=myusername
- DOCKER_INFLUXDB_INIT_PASSWORD=passwordpasswordpassword
- DOCKER_INFLUXDB_INIT_ORG=myorg
- DOCKER_INFLUXDB_INIT_BUCKET=mybucket
- DOCKER_INFLUXDB_INIT_ADMIN_TOKEN=mytoken
</pre>

Die Unterverzeichnisse für die InfluxDB Datenbank (./influxdb/data), sowie die Konfiguration (./influxdb/config) werden automatisch bei ersten Starten erstellt.

Der Eintrag "DOCKER_INFLUXDB_INIT_MODE=setup" führt dazu, dass die Datenbank beim ersten Starten initialisiert wird, dieses aber nur, falls keine Datenbank gefunden wird. So kann dieser Eintrag für die spätere Verwendung in der Konfiguration verbleiben und muss nicht entfernt werden.

Mit dieser Konfiguration ist fhem über <code><ip-des-docker-servers>:8083</code> erreichbar, das Webinterface von InfluxDB über <code><ip-des-docker-servers>:8086</code> erreichbar.

Die gesamte Konfiguration kann über

<code>
docker-compose up -d
</code>
gestartet, bzw. über

<code>
docker-compose down
</code>
gestoppt werden.

=== Konfiguration des Loggers als Device ===
Das InfluxDBLogger Device wird dann definiert mit
:<code>define <Device-name> InfluxDBLogger [http|https]://IP_or_Hostname:port dbname devspec,devspec,<weitere devspec></code>

wobei bei der Verwendung der InfluxDB Version 2
* ''dbname'' dem vergebenen Bucket entspricht.
* Das Attribut api=v2 die InfluxDV Version 2 festlegt.
* Das Attribut org=myorg die vergebene Org festlegt.
* Das Attribut security=token die Verwendung eines Tokens festlegt.

Der Token wird über <code> set <Device-name> token <mytoken></code> festlegt.

Ein Beispiel für eine Konfiguration wäre:
<pre>
define influxDB InfluxDBLogger http://10.10.120.106:8086 FHEM-bucket DB_Temp_Hum,KU_Temp_Hum,FL_Temp_Hum
attr influxDB api v2
attr influxDB org myorg
attr influxDB security token
</pre>

Ich bin mir nicht sicher, ob das Setzen eines Passwords und Users in Verbindung mit der oben beschriebenen Authentifizierungsmethodik (v2 mit Token) dazu führt, dass die Authentifizierung damit fehlschlägt.

=== Finetuning des Loggings ===
{{Todo|Todo}}

==== Einschränkung über den zentralen <code>define</code>-Eintrag ====
{{Todo|Todo}}

==== Einschränkung über die jeweiligen Devices ====
Da in Abhängigkeit von Events Einträge in die Datenbank geschrieben werden, lassen sich die gleichen Prinzipien anwenden, wie bei [[DbLog]] und [[FileLog]] und Events zu unterdrücken:
* event-min-interval, event-on-change-reading und event-on-update-reading beeinflussen, wie häufig Werte geloggt werden (vgl. {{Link2CmdRef|Lang=de|Anker=event-on-update-reading}})

== Datenbank ==
Unterstützte Datenbanksysteme :
* influxDB 1.x
* influxDB 2.x

== Zusätzliches ==
=== Plot-Abrisse vermeiden ===
Mit der Verwendung einer vollkommen neuen Datenverarbeitung, wird auch die Problematik der Plot-Abrisse an Datumsübergängen wieder zum Thema. Da das Modul [[logProxy]] direkt auf der Ebene der Darstellung (SVG-Plot Definition) ansetzt, kann es hier nicht eingesetzt werden.

Das Modul InfluxDBLogger besitzt allerdings selbst die notwendige Funktionalität, um die aktuellen Werte der konfigurierten Readings der konfigurierten Geräte in die Datenbank zu schreiben (Verweis auf die Commandref von {{Link2CmdRef|Lang=de|Anker=InfluxDBLogger|Label=InfluxDBLogger}} für weitere Details).

Ein entsprechendes DOIF müsste dann so aussehen:
<pre>
define addlog DOIF ([23:59:59] or [00:00:00])(set influxDB write)
attr addlog do always
</pre>

[[Kategorie:Logging]]

InfluxDBLogger

2021-11-20T22:20:20Z

Joshi04: Kleinigkeitenkorrektur

{{Infobox Modul
|ModPurpose=Protokolliert Ereignisse in einer Datenbank
|ModType=h
|ModForumArea=Unterstützende Dienste
|ModTechName=93_InfluxDBLogger.pm
|ModOwner=timmib ({{Link2FU|41939|Forum}})
}}

{{Todo|Dieser Artikel befindet sich im Aufbau und beschreibt daher anstatt einer kompletten Konfiguration bislang nur Teilabschnitte.}}

== Einleitung ==
Genauso, wie das Modul {{Link2CmdRef|Lang=de|Anker=DbLog|Label=DbLog}} lassen sich mit dem Modul {{Link2CmdRef|Lang=de|Anker=InfluxDBLogger|Label=InfluxDBLogger}} Daten in einer Datenbank speichern.

Für die Vorteile der Speicherung von Daten in einer Datenbank sei auf den Artikel über das Modul [[DbLog]] verwiesen.

Einer der größten Unterschiede zu einer SQL-Datenbank ist die Tatsache, dass influxDB speziell darauf ausgelegt ist, große Messdatenmengen in kurzer Zeit zusammen mit einem Zeitstempel des Messzeitpunkts zu verarbeiten.

Des Weiteren ist ein sehr wichtiger Unterschied, dass nur numerische Werte verarbeitet werden. Dies kann die Kombination mit anderen Loggingmethodiken situationsabhängig sinnvoll machen. Textbasierte Werte können aber auch durch numerische Werte ersetzt werden.

Ein Interface oder eine Möglichkeit, die Daten mittels SVG-Plots darzustellen ist derzeit nicht vorhanden. Alternativ können die Daten mittels [[Grafana]] analysiert und visualisiert werden.

== Konfiguration ==
Für die Beschreibung der Einrichtung als native Installation in Verbindung mit einer InflixDB 1.x sei auf [https://waschto.eu/2018/11/02/fhem-und-grafana-tool-zum-visualisieren-von-messdaten/ diesen Artikel] verwiesen.

Im folgenden wird auf die Einrichtung unter Docker (inkl. Docker-Compose) mit einer InflixDB 2.0 eingegangen.

=== Einrichtung einer Datenbank ===
Voraussetzungen:
* Eine laufende Docker-Umgebung (inkl. Docker-Compose)
* Ein FHEM Docker-Image mit source Dateien im Unterordner ./fhem/build
* Die FHEM Konfiguration im Unterordner ./fhem/conf
* Das folgende file <code>docker-compose.yml</code> im Ausgangsordner
<pre>
version: '2.4'
services:

fhem2:
container_name: fhem2
build: ./fhem/build
restart: always
ports:
- 8083:8083
depends_on:
- influxdb
volumes:
- ./fhem/conf:/opt/fhem
environment:
- FHEM_UID=1000
- FHEM_GID=1000
- FHEM_PERM_DIR=0750
- FHEM_PERM_FILE=0640

influxdb:
image: influxdb:latest
restart: always
ports:
- 8086:8086
volumes:
# Mount for influxdb data directory and configuration
- ./influxdb/data:/var/lib/influxdb2:rw
- ./influxdb/config:/etc/influxdb2:rw
environment:
- DOCKER_INFLUXDB_INIT_MODE=setup
- DOCKER_INFLUXDB_INIT_USERNAME=myusername
- DOCKER_INFLUXDB_INIT_PASSWORD=passwordpasswordpassword
- DOCKER_INFLUXDB_INIT_ORG=myorg
- DOCKER_INFLUXDB_INIT_BUCKET=mybucket
- DOCKER_INFLUXDB_INIT_ADMIN_TOKEN=mytoken
</pre>

Die Unterverzeichnisse für die InfluxDB Datenbank (./influxdb/data), sowie die Konfiguration (./influxdb/config) werden automatisch bei ersten Starten erstellt.

Der Eintrag "DOCKER_INFLUXDB_INIT_MODE=setup" führt dazu, dass die Datenbank beim ersten Starten initialisiert wird, dieses aber nur, falls keine Datenbank gefunden wird. So kann dieser Eintrag für die spätere Verwendung in der Konfiguration verbleiben und muss nicht entfernt werden.

Mit dieser Konfiguration ist fhem über <code><ip-des-docker-servers>:8083</code> erreichbar, das Webinterface von InfluxDB über <code><ip-des-docker-servers>:8086</code> erreichbar.

Die gesamte Konfiguration kann über

<code>
docker-compose up -d
</code>
gestartet, bzw. über

<code>
docker-compose down
</code>
gestoppt werden.

=== Konfiguration des Loggers als Device ===
Das InfluxDBLogger Device wird dann definiert mit
:<code>define <Device-name> InfluxDBLogger [http|https]://IP_or_Hostname:port dbname devspec,devspec,<weitere devspec></code>

wobei bei der Verwendung der InfluxDB Version 2
* ''dbname'' dem vergebenen Bucket entspricht.
* Das Attribut api=v2 die InfluxDV Version 2 festlegt.
* Das Attribut org=myorg die vergebene Org festlegt.
* Das Attribut security=token die Verwendung eines Tokens festlegt.

Der Token wird über <code> set <Device-name> token <mytoken></code> festlegt.

Ein Beispiel für eine Konfiguration wäre:
<pre>
define influxDB InfluxDBLogger http://10.10.120.106:8086 FHEM-bucket DB_Temp_Hum,KU_Temp_Hum,FL_Temp_Hum
attr influxDB api v2
attr influxDB org myorg
attr influxDB security token
</pre>

Ich bin mir nicht sicher, ob das Setzen eines Passwords und Users in Verbindung mit der oben beschriebenen Authentifizierungsmethodik (v2 mit Token) dazu führt, dass die Authentifizierung damit fehlschlägt.

=== Finetuning des Loggings ===
{{Todo|Todo}}

==== Einschränkung über den zentralen <code>define</code>-Eintrag ====
{{Todo|Todo}}

==== Einschränkung über die jeweiligen Devices ====
Da in Abhängigkeit von Events Einträge in die Datenbank geschrieben werden, lassen sich die gleichen Prinzipien anwenden, wie bei [[DbLog]] und [[FileLog]] und Events zu unterdrücken:
* event-min-interval, event-on-change-reading und event-on-update-reading beeinflussen, wie häufig Werte geloggt werden (vgl. {{Link2CmdRef|Lang=de|Anker=event-on-update-reading}})

== Datenbank ==
Unterstützte Datenbanksysteme :
* influxDB 1.x
* influxDB 2.x

[[Kategorie:Logging]]

InfluxDBLogger

2021-11-20T21:54:05Z

Joshi04: Neue Seite für InfluxDBLogger

{{Infobox Modul
|ModPurpose=Protokolliert Ereignisse in einer Datenbank
|ModType=h
|ModForumArea=Unterstützende Dienste
|ModTechName=93_InfluxDBLogger.pm
|ModOwner=timmib ({{Link2FU|41939|Forum}})
}}

{{Todo|Dieser Artikel befindet sich im Aufbau und beschreibt daher anstatt einer kompletten Konfiguration bislang nur Teilabschnitte.}}

== Einleitung ==
Genauso, wie das Modul {{Link2CmdRef|Lang=de|Anker=DbLog|Label=DbLog}} lassen sich mit dem Modul {{Link2CmdRef|Lang=de|Anker=InfluxDBLogger|Label=InfluxDBLogger}} Daten in einer Datenbank speichern.

Für die Vorteile der Speicherung von Daten in einer Datenbank sei auf den Artikel über das Modul [[DbLog]] verwiesen.

Einer der größten Unterschiede zu einer SQL-Datenbank ist die Tatsache, dass influxDB speziell darauf ausgelegt ist, große Messdatenmengen in kurzer Zeit zusammen mit einem Zeitstempel des Messzeitpunkts zu verarbeiten.

Des Weiteren ist ein sehr wichtiger Unterschied, dass nur Werte verarbeitet werden. Dies kann die Kombination mit anderen Loggingmethodiken situationsabhängig sinnvoll machen.

Ein Interface oder eine Möglichkeit, die Daten mittels SVG-Plots darzustellen ist derzeit nicht vorhanden. Alternativ können die Daten mittels [[Grafana]] analysiert und visualisiert werden.

== Konfiguration ==
Für die Beschreibung der Einrichtung als native Installation in Verbindung mit einer InflixDB 1.x sei auf [https://waschto.eu/2018/11/02/fhem-und-grafana-tool-zum-visualisieren-von-messdaten/ diesen Artikel] verwiesen.

Im folgenden wird auf die Einrichtung unter Docker (inkl. Docker-Compose) mit einer InflixDB 2.0 eingegangen.

=== Einrichtung einer Datenbank ===
Voraussetzungen:
* Eine laufende Docker-Umgebung (inkl. Docker-Compose)
* Ein FHEM Docker-Image mit source Dateien im Unterordner ./fhem/build
* Die FHEM Konfiguration im Unterordner ./fhem/conf
* Das folgende file <code>docker-compose.yml</code> im Ausgangsordner
<pre>
version: '2.4'
services:

fhem2:
container_name: fhem2
build: ./fhem/build
restart: always
ports:
- 8083:8083
depends_on:
- influxdb
volumes:
- ./fhem/conf:/opt/fhem
environment:
- FHEM_UID=1000
- FHEM_GID=1000
- FHEM_PERM_DIR=0750
- FHEM_PERM_FILE=0640

influxdb:
image: influxdb:latest
restart: always
ports:
- 8086:8086
volumes:
# Mount for influxdb data directory and configuration
- ./influxdb/data:/var/lib/influxdb2:rw
- ./influxdb/config:/etc/influxdb2:rw
environment:
- DOCKER_INFLUXDB_INIT_MODE=setup
- DOCKER_INFLUXDB_INIT_USERNAME=myusername
- DOCKER_INFLUXDB_INIT_PASSWORD=passwordpasswordpassword
- DOCKER_INFLUXDB_INIT_ORG=myorg
- DOCKER_INFLUXDB_INIT_BUCKET=mybucket
- DOCKER_INFLUXDB_INIT_ADMIN_TOKEN=mytoken
</pre>

Die Unterverzeichnisse für die InfluxDB Datenbank (./influxdb/data), sowie die Konfiguration (./influxdb/config) werden automatisch bei ersten Starten erstellt.

Der Eintrag "DOCKER_INFLUXDB_INIT_MODE=setup" führt dazu, dass die Datenbank beim ersten Starten initialisiert wird, dieses aber nur, falls keine Datenbank gefunden wird. So kann dieser Eintrag für die spätere Verwendung in der Konfiguration verbleiben und muss nicht entfernt werden.

Mit dieser Konfiguration ist fhem über <code><ip-des-docker-servers>:8083</code> erreichbar, das Webinterface von InfluxDB über <code><ip-des-docker-servers>:8086</code> erreichbar.

Die gesamte Konfiguration kann über

<code>
docker-compose up -d
</code>
gestartet, bzw. über

<code>
docker-compose down
</code>
gestoppt werden.

=== Konfiguration des Loggers als Device ===
Das InfluxDBLogger Device wird dann definiert mit
:<code>define <Device-name> InfluxDBLogger [http|https]://IP_or_Hostname:port dbname devspec,devspec,<weitere devspec></code>

wobei bei der Verwendung der InfluxDB Version 2
* ''dbname'' dem vergebenen Bucket entspricht.
* Das Attribut api=v2 die InfluxDV Version 2 festlegt.
* Das Attribut org=myorg die vergebene Org festlegt.
* Das Attribut security=token die Verwendung eines Tokens festlegt.

Der Token wird über <code> set <Device-name> token <mytoken></code> festlegt.

Ein Beispiel für eine Konfiguration wäre:
<pre>
define influxDB InfluxDBLogger http://10.10.120.106:8086 FHEM-bucket DB_Temp_Hum,KU_Temp_Hum,FL_Temp_Hum
attr influxDB api v2
attr influxDB org myorg
attr influxDB security token
</pre>

Ich bin mir nicht sicher, ob das Setzen eines Passwords und Users in Verbindung mit der oben beschriebenen Authentifizierungsmethodik (v2 mit Token) dazu führt, dass die Authentifizierung damit fehlschlägt.

=== Finetuning des Loggings ===
{{Todo|Todo}}

==== Einschränkung über den zentralen <code>define</code>-Eintrag ====
{{Todo|Todo}}

==== Einschränkung über die jeweiligen Devices ====
Da in Abhängigkeit von Events Einträge in die Datenbank geschrieben werden, lassen sich die gleichen Prinzipien anwenden, wie bei [[DbLog]] und [[FileLog]] und Events zu unterdrücken:
* event-min-interval, event-on-change-reading und event-on-update-reading beeinflussen, wie häufig Werte geloggt werden (vgl. {{Link2CmdRef|Lang=de|Anker=event-on-update-reading}})

== Datenbank ==
Unterstützte Datenbanksysteme :
* influxDB 1.x
* influxDB 2.x

[[Kategorie:Logging]]

DbLog

2021-11-20T19:55:44Z

Joshi04: Hinweis zur Alternative InfluxDBLogger hinzugefügt.

{{Infobox Modul
|ModPurpose=Protokolliert Ereignisse in einer Datenbank
|ModType=h
|ModForumArea=Automatisierung
|ModTechName=93_DbLog.pm
|ModOwner=tobiasfaust ({{Link2FU|118|Forum}}/[[Benutzer Diskussion:Tobias.faust|Wiki]])<br />DS_Starter ({{Link2FU|16933|Forum}}/[[Benutzer Diskussion:DS_Starter|Wiki]])
}}

== Einleitung ==
Mit der Zeit entstehen in FHEM recht umfangreiche Log-Daten für die verschiedensten konfigurierten Devices. Die übliche Einstiegs-[[Konfiguration]] sieht vor, dass die Logs als {{Link2CmdRef|Lang=de|Anker=FileLog|Label=FileLog}} gespeichert werden - je nach Einstellung in wenigen sehr großen oder vielen kleineren Dateien. Der Datei-basierte Zugriff ist allerdings nicht wirklick performant und kann schnell zum Flaschenhals werden (z.B. bei der Darstellung von Graphen über einen längeren Zeitraum).

Alternativ kann FHEM die Log-Daten mittels {{Link2CmdRef|Lang=de|Anker=DbLog|Label=DbLog}} in einer Datenbank speichern. Diese kann lokal als einfache SQLite- oder als zentrale Server-Datenbank (s.u.) gestaltet sein. Schon eine lokale einfache SQLite-Datenbank ist in der Regel deutlich performanter als File-basierte Logs.

Damit eine Datenbank-Nutzung möglich ist, müssen folgende Anpassungen gemacht werden:
# [[#Datenbank|Erstellen einer entsprechenden Datenbank]]
# [[#Datenbank-Anbindung mittels db.conf|Konfiguration der Datenbank-Anbindung in FHEM]]
# [[#Konfiguration als Device in fhem.cfg|Anpassen aller (oder einzelner) Konfigurationen von FileLog nach DbLog]]
# [[#Anpassen der gplot-Konfigurationen|Ggf. Anpassen der gplot-Konfigurationen]]

Eine weitere Alternative bietet {{Link2CmdRef|Lang=de|Anker=InfluxDBLogger|Label=InfluxDBLogger}}, was allerdings in einem anderen Artikel für das Modul [[InfluxDBLogger]] behandelt wird.

;Hinweis:
Reporting und Management von DbLog-Datenbankinhalten kann mit dem Modul [[DbRep - Reporting und Management von DbLog-Datenbankinhalten|DbRep]] stattfinden.

== Konfiguration ==
=== Datenbank-Anbindung mittels db.conf ===
{{Randnotiz|RNTyp=y|RNText='''Anmerkung''': MariaDB10 nutzt nicht Port 3306 sondern 3307. Dies ist zum Beispiel bei Synology NAS der Fall.}}
DbLog wird durch 2 verschiedene Einträge aktiviert/definiert. In einer Datei namens '''db.conf''' werden die Parameter für eine Verbindung zur Datenbank (host, username, password, etc.) hinterlegt. Diese Datei kann in einem beliebigen Verzeichnis angelegt werden. Für eine MySQL-Datenbank sieht die db.conf folgendermaßen aus:

%dbconfig= (
connection => "mysql:database=fhem;host=db;port=3306",
user => "fhemuser",
password => "fhempassword",
);

Im Verzeichnis '''contrib/dblog''' der FHEM-Installation befindet sich eine Beispielkonfiguration mit der Syntax für jeden unterstützen Datenbanktyp.
Es wird empfohlen, diese Datei zu kopieren und erst dann entsprechend zu bearbeiten. Am Besten kopiert man diese Datei in das FHEM Home Directory /opt/fhem/ und achtet auf die entsprechenden Rechte!
<syntaxhighlight lang="bash">chown fhem:dialout /opt/fhem/db.conf</syntaxhighlight>

=== Konfiguration als Device ===
Das DbLog Device wird dann definiert mit
:<code>define <name> DbLog <configfilename> <regexp> </code>
wobei ''<configfilename>'' dem Pfad zur zuvor angelegten db.conf entspricht.
Ein Beispiel hierfür wäre:
:<code>define logdb DbLog ./db.conf .*:.* </code>
Die Angabe von <code>.*:.*</code> bedeutet, dass sämtliche DeviceMessages (Messwerte, Batteriestatus, KeepAlives, etc.) in die Datenbank geschrieben werden. Dies führt u.U. dazu, dass die Datenbank auch mit vielen teils irrelevanten Werten gefüllt wird. Man kann daher die zu loggenden Werte einschränken, indem man genau angibt welche Werte übertragen werden sollen. Dies ist in [[#Finetuning des Loggings]] beschrieben.

Unbedingt beachten: bei Verwendung des Moduls configdb wird die Konfigurationsdatei aus der '''''Datenbank''''' gelesen. Deshalb ist es erforderlich, die Datei mittels <code>configdb fileimport db.conf </code> vorher zu importieren !

=== Finetuning des Loggings ===
Bei der Konfiguration des Log-Devices werden die zu loggenden Daten definiert - in der einfachsten Form sieht das so aus: <code>define logdb DbLog ./db.conf .*:.* </code>. Die Angabe von <code>.*:.*</code> bedeutet, dass sämtliche DeviceMessages (Messwerte, Batteriestatus, KeepAlives, etc.) in die Datenbank geschrieben werden. Dies führt u.U. dazu, dass die Datenbank auch mit sehr vielen und teils nicht benötigten Werten gefüllt wird und schnell wächst. Die Datenbank ist zwar deutlich leistungsfähiger, was große Datenmengen angeht, Datensparsamkeit kann aber schnell sinnvoll werden...

Um das Log-Aufkommen einzugrenzen gibt es mehrere Ansätze:
* Einschränkung über den <code>define</code>-Eintrag
* Einschränkung über DbLogExclude-Einträge der jeweiligen Devices
* Einschränkung über DbLogInclude-Einträge des jeweiligen Devices
* Ausschluß von Device/Reading-Kombinationen über das Attribut "excludeDevs". Es können {{Link2CmdRef|Anker=devspec|Lang=de|Label=devspec}} verwendet werden.

==== Einschränkung über den zentralen <code>define</code>-Eintrag ====
Man kann die zu loggenden Werte einschränken, indem man genau angibt welche Werte übertragen werden sollen. Die erste Wildcard, also das erste <code>.*</code>, entspricht dem in FHEM verwendeten Device-Namen. Die zweite Wildcard entspricht dem vom Device ausgegebenen zu loggenden Wert. Separiert werden beiden Angaben durch einen Doppelpunkt.

Ein Beispiel, um zwar alle definierten Devices zu erfassen, aber nur die Werte Temperatur, Ventilposition und Luftfeuchte in die Datenbank zu schreiben wäre:
:<code>define myDbLog DbLog ./db.conf .*:(temperature|valveposition|humidity).* </code>

==== Einschränkung über die jeweiligen Devices ====
Man kann die zu loggenden Werte für einzelne Devices separat einschränken, ohne dies im zentralen define-Eintrag machen zu müssen. Dies kann interessant sein, wenn beispielsweise ein Device Fehlerwerte meldet, die uninteressant sind, oder es meldet unnötig häufig Werte - beides ist z.B. bei 1-wire-Temperatursensoren gerne der Fall.

Um das einzuschränken gibt es 2 Stellparameter, die als Attribute direkt zum jeweiligen Device konfiguriert werden:
* DbLogExclude - definiert Werte, die nicht geloggt werden sollen
* DbLogInclude - definiert Werte, die geloggt werden sollen ( siehe attr DbLogSelectionMode )
* event-min-interval, event-on-change-reading und event-on-update-reading beeinflussen, wie häufig Werte geloggt werden (vgl. {{Link2CmdRef|Lang=de|Anker=event-on-update-reading}})

Eine konkrete Konfiguration für einen sehr gesprächigen 1-wire-Temperatursensor könnte wie folgt aussehen:
<pre>
define EG_Balkon GPIO4 BUSMASTER
attr EG_Balkon DbLogExclude failures,T,85 # logge keine "failures", "T"-Werte und "85"-Werte (default-Werte, wenn keine Temperatur gelesen werden kann)
attr EG_Balkon event-on-change-reading state # logge nur, wenn sich ein Wert ändert (wenn sich die Temperatur nicht ändert, logge das nicht)
attr EG_Balkon event-min-interval state:900 # logge spätestens alle 900sec = 15min
attr EG_Balkon event-on-update-reading .* # logge alle Werte, die aktualisiert werden

attr <1-Wire-Device vom Typ OWTHERM oder OWSWITCH> DbLogExclude data.* # verhindert das Logging der state-Eintragungen
</pre>

Eine in diesem {{Link2Forum|Topic=33697|Message=264127}} vorgestellte Strategie zur Vermeidung unnötigen Loggings ist, dass bei der Definition von Devices durch das nachfolgende <code>notify</code> automatisch ein DbLogExclude für alle Werte (.*) des Devices zugewiesen wird und dies nur bei Interesse an geloggten Werten gelöscht bzw. angepasst wird:
<code>define nDbLogExclude notify global:DEFINED.* attr $EVTPART1 DbLogExclude .*</code>

Ebenso ist es mittlerweile möglich, lediglich erwünschte Werte (Positiv-Liste) zu loggen und alle anderen zu verwerfen. Hierfür wird im LogDevice das attribut DbLogSelectionMode Include verwendet. Nun kann für jedes Device mit DbLogInclude <Reading1>,<Reading2>,... angegeben werden, welche Readings geloggt werden sollen.
Integriert ist ebenfalls ein "min-interval", siehe {{Link2CmdRef}}.

== Datenbank ==
Unterstützte Datenbanksysteme (Auswahl):
* Sqlite
* MySQL
* PostGreSql

=== Tabellen ===
Die Datenbank ist relativ simpel gestaltet und besteht lediglich aus den folgenden beiden Tabellen:
* current
* history

DbLog ist auf eine feste Tabellenstruktur angewiesen. Man muss daher in seiner Datenbank eine Tabelle mit folgenden Spalten anlegen:
{| class="wikitable"
|-
! Spalte
! Beschreibung (en)
! Beschreibung (de)
! Beispiel
|-
| '''TIMESTAMP'''
| timestamp of event
| Zeitstempel
| 2007-12-30 21:45:22
|-
| '''DEVICE'''
| device name
| Device-Name
| Wetterstation
|-
| '''TYPE'''
| device type
| Device-Typ
| KS300
|-
| '''EVENT'''
| event specification as full string
| Eventspezifikation als Text
| humidity: 71 (%)
|-
| '''READING'''
| name of reading extracted from event
| Bezeichnung des Readings
| humidity
|-
| '''VALUE'''
| actual reading extracted from event
| Wert des Readings
| 71
|-
| '''UNIT'''
| unit extracted from event
| Einheit des Readings
| %
|-
|}

Die Vorlagen zur Anlage von Tabellen und Indizes sind für jeden unterstützten Datenbanktyp im Verzeichnis '''contrib/dblog''' der FHEM-Installation, oder hier zu finden: [https://svn.fhem.de/trac/browser/trunk/fhem/contrib/dblog/ Link]. Das MySQL-Skript (db_create_mysql.sql) legt eine neue Datenbank, das PostGres-Skript (db_create_postgresql.sql) ein neues Schema mit Namen "fhem" an.

==== current ====
Die Tabelle current enthält für jedes zu loggende Device lediglich den letzten Wert. Falls noch kein Wert geloggt wurde, ist diese Tabelle leer.
Falls der Inhalt gelöscht wird, bauen sich die Daten automatisch wieder auf. Es gehen durch das löschen der Tabelle current keine Log-Informationen verloren.
Der Inhalt wird aber u.a. für die Dropdown-Felder beim Plot-Editor verwendet.

Um doppelte Einträge in der Tabelle zu vermeiden, wurden die Möglichkeit geschaffen Primary Keys zu definieren. Da in der Spalte <code>READING</code> u.U. bei verschiedenen Geräten gleiche Namen vorkommen können, sollte der Primary Key um den Gerätenamen erweitert werden. Der Primary Key sollte also aus <code>DEVICE</code> und <code>READING</code> bestehen. Um in der Datenbank ''fhem'' diesen PK zu setzen, kann folgender SQL Code verwendet werden:

<syntaxhighlight lang="sql">
ALTER TABLE `fhem`.`current`
CHANGE COLUMN `DEVICE` `DEVICE` VARCHAR(64) CHARACTER SET 'utf8' COLLATE 'utf8_bin' NOT NULL ,
CHANGE COLUMN `READING` `READING` VARCHAR(64) CHARACTER SET 'utf8' COLLATE 'utf8_bin' NOT NULL ,
ADD PRIMARY KEY (`DEVICE`, `READING`);
</syntaxhighlight>Achtung: Die Tabelle "current" wird nur befüllt, wenn das Attribut DbLogType auf Current oder Current/History gesetzt ist.

==== history ====
Die Tabelle history enthält alle bisher geloggten Daten. Löschen in dieser Tabelle bedeutet automatisch Datenverlust (gewollt oder nicht ... )
Der Inhalt dieser Tabelle wird verwendet, um die Plots zu zeichnen oder Auswertungen mit [[DbRep - Reporting und Management von DbLog-Datenbankinhalten|DbRep]] anzufertigen

{{Todo|Ausbauen}}

Um Problem beim Import von cacheFiles zu vermeiden, kann in der Datenbank ein PK angelegt werden, welcher Timestamp, Device und Reading umfasst. Dadurch werden doppelte Einträge wirksam verhindert.

== Anpassen der gplot-Konfigurationen ==
Die meisten gplot-Konfigurationen sind bisher lediglich auf FileLog-Konfigurationen ausgelegt. Deshalb müssen sie für die Verwendung mit DbLog angepasst werden. Glücklicherweise beschränkt sich dies auf die reinen FileLog-Zeilen - es müssen die DbLog-Äquivalente hinzugefügt werden. Die FileLog-Einträge müssen zwar nicht gelöscht werden, wenn man aber FileLog und DbLog parallel betreibt, sollte man getrennte gplot-Dateien für beide Logging-Typen haben um Auswertungsprobleme erkennen zu können.

Für die fht.gplot Konfiguration sähe die Anpassung wie folgt aus (lediglich die vier DbLog-Zeilen wurden hinzugefügt):
<pre>
# Created by FHEM/98_SVG.pm, 2014-12-25 21:53:30
set terminal png transparent size <SIZE> crop
set output '<OUT>.png'
set xdata time
set timefmt "%Y-%m-%d_%H:%M:%S"
set xlabel " "
set title '<L1>'
set ytics nomirror
set y2tics
set grid y2tics
set ylabel "Actuator/Window (%)"
set y2label "Temperature in C"
set yrange 0:100
set y2range 5:25

#FileLog 4:.measured-temp\x3a:0:
#FileLog 4:.actuator\x3a:0:int
#FileLog 4:.desired-temp::
#FileLog 4:.window\x3a::

#DbLog <SPEC1>:.measured-temp:0:
#DbLog <SPEC1>:.actuator:0:int
#DbLog <SPEC1>:.desired-temp::
#DbLog <SPEC1>:.window::

plot "<IN>" using 1:2 axes x1y2 title 'Measured temperature' ls l0 lw 1 with lines,\
"<IN>" using 1:2 axes x1y1 title 'Actuator (%)' ls l1 lw 1 with lines,\
"<IN>" using 1:2 axes x1y2 title 'Desired Temperature' ls l2 lw 1 with steps,\
"<IN>" using 1:2 axes x1y1 title 'Window' ls l3 lw 1 with steps
</pre>

Des Weiteren ist zu beachten:

On-Off-Plots

EG_Bad:window:::$val=~s/(on|off)(\d*).*/$1eq"on"?1:0/eg

unter Berücksichtigung von dim-Werten:

EG_WoZi_Licht:value:::$val=~s/(on|off)(\d*).*/$1eq"on"?1:($1eq"dim"?$2*0.01:0)/eg

== Beispiel: Anlegen und Nutzung einer SQLite-Datenbank ==
Im folgenden wird eine lokale SQLite-Datenbank auf einen Ubuntu-System angelegt (nach Quelle: http://www.tatsch-it.de/fhem-dblog/)
<ol>
<li>''Installation von SQLite:''
<pre>sudo aptitude install sqlite3 libdbi-perl libdbd-sqlite3-perl</pre>
</li>
<li>''Anlegen der SQLite-Datenbank fhem.db'' (öffnet auch direkt eine SQL-Kommandozeile):
<pre>sudo sqlite3 /opt/fhem/fhem.db</pre>
In der geöffneten SQL-Kommandozeile eingeben:
<pre>
CREATE TABLE history (TIMESTAMP TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP, DEVICE varchar(64), TYPE varchar(64), EVENT varchar(512), READING varchar(64), VALUE varchar(128), UNIT varchar(32));
CREATE TABLE current (TIMESTAMP TIMESTAMP, DEVICE varchar(64), TYPE varchar(64), EVENT varchar(512), READING varchar(64), VALUE varchar(128), UNIT varchar(32));
CREATE INDEX Search_Idx ON `history` (DEVICE, READING, TIMESTAMP);
</pre>
Die Kommandozeile verlässt man mit <code>.exit</code>.
</li>
<li>''Anpassen des Besitzers und der Rechte der Datenbank-Datei:''
<pre>
sudo chown fhem /opt/fhem/fhem.db
sudo chmod 600 /opt/fhem/fhem.db
</pre>
</li>
<li>''Datenbank-Anbindung des FHEM konfigurieren:''
<pre>sudo nano /opt/fhem/db.conf</pre>
Inhalt:
<pre>
%dbconfig= (
connection => "SQLite:dbname=/opt/fhem/fhem.db",
user => "",
password => ""
);
</pre>
</li>
<li>''Logging des FHEM auf die Datenbank konfigurieren:'' (hier sind nur die Anpassungen aufgeführt)
<pre>sudo nano /opt/fhem/fhem.cfg</pre>
<pre>
...
attr global userattr DbLogExclude ... # erlaubt es einzelne Einträge nicht zu loggen
...
define logdb DbLog ./db.conf .*:.* # logt alle(!) auflaufenden Events aller Konfigurationen
...
</pre>
Da durch diese <code>define</code>-Definition alle auflaufenden Events gelogt werden, müssen keine weiteren Anpassungen in der Konfiguration gemacht werden. Die FileLog-Einträge können bedenkenlos bestehen bleiben - dann wird in Datenbank und FileLog gelogt und man verliert keine Daten, falls etwas nicht klappt. Wenn alles wie geplant läuft, können die FileLog-Definitionen gelöscht werden (ebenso die Log-Dateien). Ebenso können die zu loggenden Daten später eingegrenzt werden (s. [[#Finetuning des Loggings]]).
</li>
<li>''FHEM neu starten:''
<pre>
sudo service fhem stop
sudo service fhem start
</pre>
</li>
<li>''Kontrollieren, ob Logs in die Datenbank geschrieben werden:''
<pre>sudo sqlite3 /opt/fhem/fhem.db</pre>
In der geöffneten SQL-Kommandozeile eingeben:
<pre>
select * from history order by TIMESTAMP; # dies gibt alle(!) Logs chronologisch aus (kann nach längerem Betrieb recht lange dauern)
</pre>
Die Kommandozeile verlässt man mit <code>.exit</code>.
</li>
<li>''Anpassung der glot-Dateien:'' siehe [[#Anpassen der gplot-Konfigurationen]]
</li>
</ol>

== Beispiel: Anlegen und Nutzung einer Mysql-Datenbank ==
Hierfür gibt es eine [[DbLog-MySQL|extra Seite]], die die Unterschiede und Feinheiten zwischen den verschiedenen Versionen berücksichtigt

Anstatt nano kann jeder andere kompatible Editor verwendet werden. Weiterhin bitte beachten, dass die hier genannten Befehle teilweise root-Rechte voraussetzen. Entweder komplett als root arbeiten, oder mittels sudo.

Unter Ubuntu/debian:
apt-get update && apt-get install mysql-server mysql-client libdbd-mysql libdbd-mysql-perl

Bei der Installation sollte man aus Sicherheitsgründen ein Passwort für den mysql-root vergeben, wenn man nicht sogar ganz den Login verbietet.

Hinweis: im Folgenden ist "#" der normale Prompt und "mysql>" der prompt innerhalb mysql, dieser kann mit exit verlassen werden.

Zum Test mal mit mysql verbinden:
# mysql -p -u root
Enter password:
mysql> exit

Jetzt die Tabellenstruktur anlegen.
Hierfür kann die Datei /opt/fhem/contrib/dblog/db_create_mysql.sql als Vorlage verwendet und das Passwort und der Benutzername geändert werden.
cd /opt/fhem/contrib/dblog/
nano db_create_mysql.sql
Dann wird die Datei eingelesen (root Passwort wird abgefragt):

# mysql -u root -p < db_create_mysql.sql

Jetzt kann man den Zugang testen:

# mysql -p -u <fhemuser>
Enter password: <fhempassword>
mysql> show databases;

Nun müsste eine Datenbank "fhem" angezeigt werden, die die Tabellen current und history enthält.

Nun in der Datei db.conf den mysql-Block auskommentieren und ebenfalls Benutzername, Passwort UND HOST anpassen. Leider ist hier nicht standardmäßig localhost eingestellt.
nano /opt/fhem/db.conf

Jetzt kann unter FHEM ein DbLog-Device angelegt werden (mit dem beispiel wird alles geloggt:
define logdb DbLog ./db.conf .*:.*
Als State muss ein "connected" angezeigt werden.

Ein rereadcfg in FHEM stellt sicher, dass die neue Konfiguration übernommen wird - ein Neustart ist nicht erforderlich.

Nun kann die Funktion noch einmal überprüft werden:
<syntaxhighlight lang="sql">
# mysql -u <fhemuser> -p
Enter password: <fhempassword>
mysql> use fhem;
Database changed
mysql> show tables;
+----------------+
| Tables_in_fhem |
+----------------+
| current |
| history |
+----------------+
2 rows in set (0,00 sec)
mysql> select * from history; # Achtung, kann sehr groß werden .... #
</syntaxhighlight>

Anscheinend gibt es bei der neuen Version MariaDB (im Gegensatz zu mysql) ein neues Anmeldeverfahren, so dass in der Datenbank selbst Veränderungen vorgenommen werden müssen, damit der Zugriff durch FHEM funktioniert: https://kofler.info/root-login-problem-mit-mariadb/

Die Daten im MySQL können auch für die längere Aufbewahrung partitioniert werden. Dabei wird pro Partition eine Datei erzeugt statt einer gemeinsamen Datei für alle Daten. Je nach Wunsch zum Beispiel partitioniert nach Jahr.
<syntaxhighlight lang="sql">
Alter table history PARTITION BY RANGE ( UNIX_TIMESTAMP(timestamp) ) (
PARTITION p0 VALUES LESS THAN ( UNIX_TIMESTAMP('2019-01-01 00:00:00') ),
PARTITION p1 VALUES LESS THAN ( UNIX_TIMESTAMP('2020-01-01 00:00:00') ),
PARTITION p2 VALUES LESS THAN ( UNIX_TIMESTAMP('2021-01-01 00:00:00') ),
PARTITION p3 VALUES LESS THAN ( UNIX_TIMESTAMP('2022-01-01 00:00:00') ),
PARTITION p4 VALUES LESS THAN ( UNIX_TIMESTAMP('2023-01-01 00:00:00') ),
PARTITION p5 VALUES LESS THAN ( UNIX_TIMESTAMP('2024-01-01 00:00:00') ),
PARTITION p6 VALUES LESS THAN ( UNIX_TIMESTAMP('2025-01-01 00:00:00') ),
PARTITION p7 VALUES LESS THAN (MAXVALUE) );
</syntaxhighlight>

== Beispiel: Abfragescript PHP/MySQL ==
Um eine schnelle Übersicht zu bekommen habe ich mir dieses Script geschrieben:
<syntaxhighlight lang="php">
<?php $pdo = new PDO('mysql:host=localhost;dbname=fhem', 'fhemuser', 'fhempasswort');
echo '<h2>Tabelle Current</h1><br><table border="1">';
echo "<tr><th>Anzahl</th><th>Name</th><th>Readings</th></tr>";
$sql = "SELECT COUNT(*), DEVICE, GROUP_CONCAT(DISTINCT READING ORDER BY READING DESC SEPARATOR '</li><li>') FROM current GROUP BY DEVICE;"; foreach ($pdo->query($sql) as
$row) {
echo "<tr><td>" . $row[0] . "</td><td>" . $row[1] . "</td><td><ol><li>" . $row[2] . "</li></ol></td></tr>";
}
echo "</table>";

echo '<h2>Tabelle History</h1><br><table border="1">';
echo "<tr><th>Anzahl</th><th>Name</th></tr>";
$sql = "SELECT COUNT(*), DEVICE FROM history GROUP BY DEVICE;"; foreach ($pdo->query($sql) as
$row) {
echo "<tr><td>" . $row[0] . "</td><td>" . $row[1] . "</td></tr>";
}
echo "</table>";
?>
</syntaxhighlight>

Bitte passt ''fhemuser'' und ''fhempasswort'' an. Das Ganze kommt dann nach <code>/var/www/html/fhemdb.php</code> und ist mit <code><nowiki><IP>/fhemdb.php</nowiki></code> aufrufbar. Wenn ihr den zweiten Block für die history Tabelle ausklammert oder entfernt, läuft das Script viel schneller ab - klar die history Tabelle ist meist randvoll.

== Integration von DBLog in eigene Module ==
=== Bereitstellung der UNITS ===
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.

Dazu muss der Modulautor in der [[DevelopmentModuleIntro#X_Initialize|Initialize-Funktion]] eine <code>DbLog_splitFn</code> bereitstellen:

<syntaxhighlight lang="perl">
sub X_Initialize($)
{
my ($hash) = @_;
...
$hash->{DbLog_splitFn} = "X_DbLog_splitFn";
}
</syntaxhighlight>

Die genaue Aufrufsyntax und Funktionweise einer DbLog_split-Funktion findet man [[DevelopmentModuleIntro#X_DbLog_split|hier]].

== Werte auslesen ==
Manchmal möchte man Daten aus den Logs abrufen ohne händisch in der Datenbank herumzuwühlen (s.u.). Dies ist insbesondere auch dann hilfreich, wenn man eigene Funktionen, Notifys oder spezielle Plots entwirft, bei denen man auf Logdaten zugreifen möchte.

Grundsätzlich beschrieben ist dies in der {{Link2CmdRef|Lang=de|Anker=DbLog}} und unterscheidet sich minimal (aber entscheidend) von der Struktur bei [[FileLog#Werte_auslesen|FileLogs]].

Hier ein paar Beispiele, was man damit anstellen kann:

* <code>get meineDB - - 2016-10-01 2016-10-03 meinSensor</code> alle Einträge des meinSensor vom 01.10.-03.10.2016
* <code>get meineDB - - 2016-10-01_08:00:00 2016-10-01_16:00:00 meinSensor</code> alle Einträge des meinSensor von 8-16 Uhr am 01.10.2016
* <code>get meineDB - - 2016-10-01_08:00:00 2016-10-01_16:00:00 meinSensor:temperature</code> nur die temperature Werte
* <code>{ ReadingsTimestamp("meinSensor","state","0") }</code> Timestamp des aktuellen state des meinSensor
* <code>{ OldTimestamp("meinSensor") }</code> Timestamp des letzten state des FHT_3a32
* <code>{ time_str2num(OldTimestamp("meinSensor")) }</code> Timestamp in Sekunden des letzten state des meinSensor
* ...

== Bearbeitung von Datenbank-Einträgen ==
{{Hinweis|Dieser Abschnitt soll lediglich eine kleine Einführung in die Datenbank-Bearbeitung liefern. Für vertiefende Informationen sollte man sich grundsätzlich mit SQL beschäftigen. Eine umfassende und gut verständliche Anleitung zu SQL bietet bspw. [http://www.w3schools.com/sql/default.asp w3schools].}}
Irgendwann wird der Fall eintreten, dass in der Datenbank Einträge drinstehen, die geändert oder gelöscht werden sollen (zB. fehlerhafte Sensor-Rückmeldungen, umbenannte Readings). In klassischen Log-Dateien würde man diese einfach bearbeiten und löschen/anpassen (wobei man aber tunlichst zuvor FHEM stoppt, um Datenfehler zu vermeiden). Eine Datenbank kann bearbeitet werden, ohne FHEM stoppen zu müssen.

Datenbanken kann man ohne weitere Hilfsmittel direkt von der Kommandozeile/Shell aus bearbeiten. Alternativ gibt es auch verschiedenste Tools (webbasiert oder als Applikation), die einen dabei unterstützen (Bsp. findet man u.a. [https://wiki.ubuntuusers.de/SQLite/#Grafische-Benutzeroberflaechen hier]). Für einfache Arbeiten reicht allerdings idR. Shell.

=== SQLite-Datenbanken ===
'''Öffnen der DB unter Linux:'''

(Es werden Schreibrechte benötigt,ohne kann man die DB zwar öffnen, aber nichts machen)
sudo sqlite3 fhem.db
Dadurch öffnet sich ein SQL-Konsole, auf der alle weiteren Befehle ausgeführt werden.

'''Schliessen der DB:'''

sqlite> .exit

'''Hilfe anzeigen:'''

sqlite> .help

'''Alle Tabellen anzeigen:'''

sqlite> .tables

'''Das Schema der DB anzeigen:'''

(vgl. oben [[DbLog#Datenbanken]] und [[DbLog#Beispiel: Anlegen und Nutzung einer SQLite-Datenbank]])

sqlite> .schema

'''Alle Eintäge anzeigen:'''

Die Einträge liegen alle in der Tabelle "History".

'''Ganz wichtig''' ist immer das ";" am Ende Zeile (bei allen Kommandos, die nicht mit einem "." anfangen). Wenn es vergessen wurde zeigt die Konsole solange neue Zeilen bis ein ";" eingegeben wird. So kann ein Befehl auch bequem über mehrere Zeilen geschrieben werden.

sqlite> select * from HISTORY;

Dies kann sehr lange dauern und kann ggf. mit <code>STRG-C</code> abgebrochen werden.

'''Alle Einträge eines Geräts anzeigen:'''

In <code>where</code>-Statements werden Strings in einfache Anführungsstriche gesetzt, Zahlen nicht.

sqlite> select * from HISTORY where DEVICE='Pollenflug';

'''Alle Einträge eines Readings eines Geräts anzeigen:'''

sqlite> select * from HISTORY where DEVICE='Pollenflug' and READING='Graeser';

'''Alle Einträge eines bestimmten Wertes eines Readings eines Geräts anzeigen:'''

sqlite> select * from HISTORY where DEVICE='Pollenflug' and READING='Graeser' and VALUE>1;

'''LÖSCHEN aller Einträge eines bestimmten Wertes eines Readings eines Geräts anzeigen:'''

'''Achtung:''' Löschen kann nicht rückgängig gemacht werden!! Also IMMER erst die entsprechenden SELECT-Statements solange verfeinern bis wirklich nur die gewünschten Einträge angezeigt werden. Dann das <code>select *</code> durch <code>delete</code> ersetzen.

sqlite> delete from HISTORY where DEVICE='Pollenflug' and READING='Graeser' and VALUE>1;

== Datenbank reparieren ==
Es kann immer wieder mal vorkommen, dass Datenbanken Fehler enthalten. Das muss im Alltag garnicht auffallen und auch nicht immer schlimm enden. Wenn man auf der SQL-Konsole aber bspw. eine Meldung <code>Error: database disk image is malformed</code> erhält, sollte man ein Reparatur vornehmen.

'''Hinweis:''' Ist ein DbRep-Device definiert, kann eine Reparatur einfach mit dem eingebauten Befehl '''set <name> repairSQlite''' ausgeführt werden.

=== SQLite-Datenbanken ===
Die folgenden Schritte beschreiben, wie man eine SQLite-DB reparieren kann (Quelle: [http://techblog.dorogin.com/2011/05/sqliteexception-database-disk-image-is.html]):

<ol>
<li>DB öffnen:
<pre>sudo sqlite3 fhem.db</pre>
</li>
<li>Integritäts-Check durchführen:
<pre>sqlite> pragma integrity_check;</pre>
Kommt hier ein "ok" ist die DB gesund. Ansonsten erscheint etwas wie
<pre>
*** in database main ***
On tree page 118786 cell 1: Rowid 75 out of order (previous was 816660)
On tree page 118786 cell 4: Rowid 815704 out of order (previous was 816727)
Corruption detected in cell 0 on page 118786
Multiple uses for byte 132 of page 118786
...
</pre>
</li>
<li>Datenbank-Dump erstellen (Export gesamten DB in die Datei "dump_all_20160516_1043.sql") und DB verlassen:
<pre>
sqlite> .mode insert
sqlite> .output dump_all_20160516_1043.sql
sqlite> .dump
sqlite> .exit
</pre>
</li>
<li>Neue Datenbank erstellen und den Dump einlesen, Integritäts-Check machen und verlassen:
<pre>sudo sqlite3 fhem-neu.db</pre>
<pre>
sqlite> .read dump_all_20160516_1043.sql
sqlite> pragma integrity_check;
ok
sqlite> .exit
</pre>
</li>
<li>Spätestens jetzt FHEM stoppen:
<pre>sudo service fhem stop</pre>
</li>
<li>Alte DB sichern und neue aktivieren:
<pre>
sudo mv fhem.db fhem.db.sv_20160516
sudo mv fhem-neu.db fhem.db
</pre>
</li>
<li>Kontrollieren, dass die neue DB die gleichen Rechte wie die alte DB hat (und ggf. korrigieren):
<pre>
~/fhem$ ls -lha
insgesamt 6,3G
drwxr-xr-x 12 fhem root 4,0K Mai 16 11:07 .
drwxr-xr-x 4 root root 4,0K Dez 25 17:50 ..
...
-rw-r--r-- 1 root root 1,4G Mai 16 11:04 fhem.db
-rw-r--r-- 1 fhem root 2,6G Mai 16 10:59 fhem.db.sv_20160516
...

~/fhem$ sudo chown fhem:root fhem.db

~/fhem$ ls -lha
insgesamt 6,3G
drwxr-xr-x 12 fhem root 4,0K Mai 16 11:07 .
drwxr-xr-x 4 root root 4,0K Dez 25 17:50 ..
...
-rw-r--r-- 1 fhem root 1,4G Mai 16 11:04 fhem.db
-rw-r--r-- 1 fhem root 2,6G Mai 16 10:59 fhem.db.sv_20160516
...
</pre>
</li>
<li>FHEM wieder starten (und natürlich kontrollieren):
<pre>sudo service fhem start</pre>
</li>
</ol>

=== Hinweise für sehr große Datenbanken ===
Wenn die SQLite-DB sehr groß wird, kann es sein, dass der oben beschriebene Weg nicht ohne manuelle Anpassungen funktioniert. Konkret war dies bei einem Nutzer für eine 15 GB große DB nicht möglich, der Prozess hat sich immer nach mehreren Stunden aufgehängt. Die Ursache liegt darin, dass ein Dump alle Daten in einer einzigen Transaktion einfügt. Das Problem kann man lösen, indem man den Dump in mehreren Transaktionen einfügt, also aufteilt. Konkret konnte eine 23GB große DB erfolgreich eingelesen und damit repariert werden, indem alle 10.000.000 Zeilen folgende 2 Zeilen eingefügt wurden:
<pre>BEGIN TRANSACTION;
COMMIT;
</pre>
* Hinweis 1: Mit dem Editor joe kann man unter Linux auch sehr große Dateien flüssig bearbeiten, das Springen zu hohen Zeilennumer dauert trotzdem.
* Hinweis 2: joe verwendet eine temporäre Kopie der Datei. Diese liegt per default unter /tmp. Der Ort kann aber auch durch <code>export TEMP=...</code> geändert werden. Falls also unter /tmp nicht Platz für eine Kopie des Datenbank-Dumps ist, sollte diese Variable vor dem Starten von joe entsprechend gesetzt werden.
* Hinweis 3: Beim Speichern legt joe im gleichen Verzeichnis eine Sicherungskopie an, d.h. im Verzeichnis des Datenbank-Dumps sollte weiterer Platz in Höhe der Dateigröße frei sein.
* Hinweis 4: Der reopen Mechanismus von DbLog kann verwendet werden, um eine manuelle Datenbankreparatur ohne Logunterbrechung durchzuführen (vor dem Wieder-Öffnen der DbLog Datei- und Verzeichnisrechte prüfen!). Damit kann man das harte Stoppen und Starten von FHEM in obiger Anleitung umgehen.
* Letzter Hinweis: Weiter gilt: bei großen DbLog-Datenbanken sollte man immer darüber nachdenken,
** Welche dieser Logdaten man wirklich braucht und im Zweifel per DbRep ausdünnen
** Zu einer echten Datenbank wie MySQL/MariaDB zu wechseln.

== Datenbank migrieren ==
Eine schöne Anleitung zur Migration von SQLite zu MySQL/MariaDB mit Hilfe von [[DbRep - Reporting und Management von DbLog-Datenbankinhalten|DbRep]] findet sich hier: [https://demaya.de/fhem-umzug-sqlite-mysql-mariadb/].

== Nützliche Codeschnipsel ==
Anbei ein paar nützliche Codeschnipsel rund um DbLog

=== Dateigrösse mitloggen ===
Da die Datenbank ins Unermessliche wachsen kann, empfiehlt es sich - je nach Speicherplatz - ab einer bestimmten Grösse tätig zu werden. Dazu muss diese Grösse allerdings ermittelt werden. Diese geschieht mittels des Userreadings, welches man vorteilshafterweise mit im DbLog-device anlegt:

<pre>attr myDbLog userReadings DbFileSize:reduceLogState.* { (split(' ',`du -m fhem.db`))[0] }</pre>

Mittels dieses Attributs wird die Grösse der .db-Datei immer nach dem Ausführen des ReduceLog in das Reading "DbFileSize" in ganzzahligen MByte abgelegt.

Basierend auf diesem Reading können dann weitere Aktionen, beispielsweise ein Plot, erstellt werden.

Die oben beschriebene Möglichkeit ist für SQLite verwendbar. Zur Ermittlung der DB-Größe andere DB-Typen (aber auch für SQLite nutzbar) kann wie [[DbRep_-_Reporting_und_Management_von_DbLog-Datenbankinhalten#Gr.C3.B6.C3.9Fe_der_FHEM-Datenbank_ermitteln | hier]] beschrieben vorgegangen werden.

== Performance-Optimierung ==
Auch eine Datenbank kann mit der Zeit langsamer werden. Dies hängt von mehreren Faktoren ab:
* Menge der gelogten Daten (zB. > 4-5 GB)
* Eingesetzte Hardware (zB. langsame SD-Karte vs. schnelle SSD)
* Eingesetztes Datenbanksystem (zB. SQLite, MySQL)
* Komplexität der Abfragen (zB. für aufwändige Graphen oder Berechnungen)

Diese Punkte sollen im folgenden diskutiert werden:

=== Komplexität der Abfragen ===
Dies ist kein Problem der Datenbank, sondern rein der Abfrage. Dem entsprechend muss die Optimierung auch in der Abfrage oder im Skript gesucht werden. Dies ist nicht Ziel dieses Abschnittes und wird hier nicht weiter behandelt.

=== Eingesetztes Datenbanksystem ===
Welches Datenbanksystem eingesetzt wird (zB. SQLite oder MySQL) hat auf die Performance der Datenbank gar keinen so großen Einfluss, wie vielleicht zuerst gedacht. Selbst SQLite kann problemlos Datenbanken mit etlichen GB Größe performant verarbeiten. Der Flaschenhals ist hier viel mehr die darunter liegende Hardware (s.u.).

Die Performance der Datenbank an sich, kann aber durch verschiedene Maßnahmen verbessert werden:
* Pflegemaßnahmen bzgl. der Daten
* '''Erstellung von Indizes'''

==== Menge der Daten und Pflegemaßnahmen bzgl. der Daten ====
Die Menge der geloggten Daten hat natürlich Einfluss auf die Geschwindigkeit von Abfragen - je mehr Daten vorhanden sind, desto mehr Daten müssen auch durchforstet werden um eine Abfrage zu bedienen. Die Reduzierung der geloggten Datenmenge hat also direkten Einfluss auf die Größe und damit auch die Geschwindigkeit der Datenbank. Die Menge der zu loggenden Daten lässt sich an zwei Stellen einschränken:
* bei der Definition jedes Devices (s. Kapitel oben)
* bei der Festlegung des FHEM-weiten Log-Levels (s. [[Loglevel]])

Die Menge der bereits geloggten Daten kann zB. mit Hilfe von [[DbRep - Reporting und Management von DbLog-Datenbankinhalten|DbRep]] verringert und optimiert werden, bspw.
* löschen unnötiger Daten
* vacuum der Datenbank

Insgesamt haben diese Maßnahmen aber nur einen eingeschränkten Effekt auf die Performance der DB. Deutlich effektiver ist die Erstellung eines Index (s.u.).

==== Erstellung von Indizes ====
Die Erstellung von Indizes hat mit Abstand den größten Einfluss auf die Performance einer Datenbank (auf unveränderter Hardware). Extrem zusammengefasst ist ein Index eine extrem optimiertes Nachschlageverzeichnis für einen bestimmten Typ Daten (ein Index wie im Buch halt). Eine wunderbare Einführung in Indizes bietet [[https://use-the-index-luke.com/de|https://use-the-index-luke.com]].

In FHEM sind Indizes sogar sehr einfach einzurichten da die Datenbank-Nutzung sehr stark vorgegeben ist. Nahezu jede Abfrage folgt dem Schema ''Device -> Reading -> Datum -> Wert''. Ein Index kann genau diese Abfrage bedienen und beschleunigen. Ein Index nur über die Devices wäre ein erster Schritt, brächte aber noch keinen großen Gewinn (wie um Link oben gut beschrieben). Über die gesamten ersten drei Schritte erstellt (Device -> Reading -> Datum) bringt der Index aber sofort eine deutliche Geschwindigkeitssteigerung.

Die Erstellung eines Index erfolgt direkt in der Datenbank (und nicht aus FHEM heraus), hier am Beispiel einer SQLite-DB:

Öffnen der DB:
<pre> sudo sqlite3 fhem.db </pre>

Erzeugen des Index auf der DB-Konsole (das Semikolon am Ende ist wichtig):
<pre> create index idx_device_reading_timestamp on history (device, reading, timestamp); </pre>

Verlassen der DB:
<pre> .exit </pre>

Einzig zu berücksichtigen ist, dass dieser Index die Datenbank um bis zu 1/3 vergrößert. Er kann aber bei Bedarf auch wieder entfernt werden. Bei meiner 15 GB SQLite-Datei (auf einem Mac Mini mit SSD) hat dies ca. 15 min gedauert (den FHEM hatte ich vorsichtshalber währenddessen deaktiviert).

Sollte jemand spezielle Berechnungen oder Skripte ausführen, die nach einem anderen Abfrage-Schema arbeiten, könnte man dafür spezialisierte zusätzliche Indizes erstellen. Das sollte aber dann mit dem Wissen des obigen Links erarbeitet werden, da dann etwas mehr Hintergrundwissen sehr hilfreich ist.

==== DB-Backup ====
Ein anderer Aspekt, der eigentlich nichts mit der Performance der DB zu tun hat, ist der Einfluss aufs Backup. Wird bspw. ein Systembackup per RSYNC gemacht, muss bei SQLite immer die komplette ggf. riesige Datei gesynct werden - bei MySQL würden nur die veränderten DB-Elemente gesynct. Dies soll hier nicht weiter vertieft werden, sollte aber bei einer Gesamtstrategie bedacht werden.

=== Eingesetzte Hardware ===
FHEM hat grundsätzlich sehr viele kleine Datenzugriffe, unabhängig davon ob FileLog oder DbLog eingesetzt wird. Deshalb ist der absolut größte Performance-Gewinn durch den Einsatz schneller Festplatten zu erreichen - ganz einfache Aussage: ''je schneller desto besser ;-)''. Konkret bietet eine SSD mit mind. 250MB/s Datenzugriff eine ordentliche Basis für jedes datengestützte System, wie den FHEM.

Wenn die Datenmenge größer und die Abfragen komplexer werden, müssen natürlich irgendwann auch die Prozessorleistung und der Arbeitsspeicher mit wachsen. Aber auch an einem Raspi wird eine SSD deutlich performanter sein, als eine einfache SD-Karte oder eine klassische rotierende Festplatte.

== Links ==
* [[Heizleistung_und_Gasverbrauch|Beispiel das DbLog-Daten für SVG-Plots verwendet]]
* [[SVG-Plots von FileLog auf DbLog umstellen]]

[[Kategorie:Logging]]

HM-TC-IT-WM-W-EU Funk-Wandthermostat AP

2020-06-21T08:41:50Z

Joshi04: Links aktualisiert

{{Infobox Hardware
|Bild=HM-TC-IT-WM-W-EU.jpg
|Bildbeschreibung=HM-TC-IT-WM-W-EU mit Standard-Einstellungen
|HWProtocol=[[HomeMatic]]
|HWType=[[HomeMatic Type Thermostat|thermostat]]
|HWCategory=[[:Kategorie:Temperatursensoren|Temperatursensoren]] [[:Kategorie:Feuchtesensoren|Feuchtesensoren]]
|HWComm=868,3 MHz
|HWChannels=7
|HWVoltage=3 V
|HWPowerConsumption=40 mA (max)
|HWPoweredBy=2 x LR6/Mignon/AA
|HWSize=ohne Rahmen: 55 x 55 x 20 mm<br />mit Rahmen: 86 x 86 x 21,5 mm
|HWDeviceFHEM=[[CUL_HM]]

|HWManufacturer=ELV / eQ-3
}}
'''HM-TC-IT-WM-W-EU Funk-Wandthermostat AP'''

HomeMatic-Wandthermostat Aufputz. Verfügbar seit Februar 2014. Nachfolger des [[HM-CC-TC_Funk-Wandthermostat|HM-CC-TC]].

== Vorbemerkungen ==
: ''→ Allgemeine Informationen, die alle HomeMatic Thermostate betreffen, sind unter [[HomeMatic Type Thermostat]] zu finden.''

Der '''HM-TC-IT-WM-W-EU Funk-Wandthermostat''' misst die Raumtemperatur und Luftfeuchtigkeit. Er verfügt über individuell einstellbare Wochenprogramme und Programmierung direkt am Gerät. Zusätzlich ist auch eine Boost-Funktion vorhanden (ermöglicht ein schnelles, kurzzeitiges Aufheizen des Heizkörpers). Er verfügt über ein eigenes Anzeigedisplay für Soll- und Isttemperatur sowie Luftfeuchtigkeit. Er kann mittels Klebestreifen irgendwo aufgeklebt werden, soll aber auch in Mehrfachrahmen von Berker, ELSO, Gira, Merten und JUNG passen.

Der Hauptnutzen gegenüber den Heizkörperthermostaten besteht neben einer weitaus bequemeren Bedienung und der möglichen Anzeige von Istwerten von Temperatur und Luftfeuchte auch in einer Entkopplung der Raumtemperaturreglung aus der räumlichen Nähe des Heizkörpers. Zusätzlich oder alternativ zur Heizkörpersteuerung ist auch die Anbindung von Fußbodenheizung oder anderen Wärmequellen über einen funkgesteuerten Schaltaktor durch einen separaten Schaltkanal möglich.

== Technische Daten ==

'''Technische Daten:'''
* Versorgungsspannung: 2 Stck. 1,5 V LR03/Micro/AAA
* Stromaufnahme (max.): 40 mA
* Schutzart: IP20
* Schutzklasse: III
* Abmessungen (BxHxT ohne Rahmen): 55 x 55 x 20 mm
* Abmessungen (BxHxT mit Rahmen): 86 x 86 x 21,5 mm
* Gewicht (ohne Batterien): 74 g
* Temperaturwahl in Schritten von: 0,5 °C

Im Gegensatz zum HM-CC-TC kann der HM-TC-IT-WM-W-EU auch andere HomeMatic-Schaltaktoren (z.B. [[HM-LC-SW1-FM_Schaltaktor_1-fach_UP|HM-LC-SW1-FM]]) über den Channel 07 SwitchTr direkt anlernen, womit z.B. die Steuerung elektrischer Heizungen möglich wird. Der HM-CC-TC konnte direkt nur die HM-CC-VD steuern.

== Betrieb mit FHEM ==
Grundsätzlich sind speziell bei der Ansteuerung von [[HM-CC-RT-DN Funk-Heizkörperthermostat]] zwei Betriebsarten mit FHEM denkbar.

=== Steuerung nur über den Wandthermostat ===

In diesem Fall werden zunächst alle [[HM-CC-RT-DN Funk-Heizkörperthermostat]]e mit dem HM-TC-IT-WM-W-EU Funk-Wandthermostat verbunden wie in den Handbüchern beschrieben (dort "verknüpfen" genannt, technisch handelt es sich um eine peering).
Dazu muss die mittlere Taste der Heizkörper Ventile länger als 3 Sekunden gedrückt werden, ebenso das Einstellrad am Wandthermostat. Die "Verknüpfung" war erfolgreich, wenn beide Geräte "ACK" im Display zeigen.

Wichtig ist, dass keines der Geräte vorher mit einer Zentrale (u.B. VCCU) gepairt sein darf. Im Zweifel vorher unpairen.

Wenn alle Heizkörperthermostat gepeert ("verknüpft") sind, dann wird das HM-TC-IT-WM-W-EU Funk-Wandthermostat mit FHEM wie in [[HomeMatic Devices pairen]] beschrieben gepairt.

Anschliessend kann per FHEM mit dem Befehl
set myTC desired-temp 22
die Zieltemperatur an den Wandthermostat übermittelt werden. Dieser verteilt diese Temperatur und seine gemessene Ist-Temperatur an die Heizkörperthermostate weiter, die dann entsprechend das Ventil öffnen oder schliessen. Die Wunschtemperatur kann auch lokal an '''allen''' Geräten (also auch an einem der Heizkörperthermostate) per Drehregler geändert werden und wird anschliessend an alle anderen Geräte und FHEM weiterübertragen. Kommunikationspartner für FHEM ist aber immer nur das gepairte HM-TC-IT-WM-W-EU Funk-Wandthermostat.

Vorteile dieser Methode:
* schnell eingerichtet - weniger Komplex, keine Channel peering notwendig.
* weniger Geräte in FHEM, weniger Daten, weniger Defs, weniger Prozessorlast, geringer Verbrauch des Funkkontingents an FHEMs Funkschnittstelle etc. (Es ist allerdings fraglich, ob in normalen Installationen diese Effekte überhaupt spürbar sind)
* Heizung kann am HM-TC-IT-WM-W-EU Funk-Wandthermostat auch bei Ausfall von FHEM eingestellt werden.
* eventuelles Wochenprogramm muss nur an einer Stelle eingespielt werden (nämlich in den Wandthmermostaten)

Nachteile dieser Methode:
* keine direkte Kontrolle über die Heizkörperthermostate, weniger Daten. Z.B. ist der Valevöffnungsgrad FHEM unbekannt, ebenso Batteriewarnungen, auch lassen sich diverse Dinge nicht konfigurieren wie Button lock, boost-time, remote Kanal zur Abschaltung, temp-offset, maximale Ventilöffnung etc.
* leichte Verzögerung in der Übermittlung der Zieltemperatur, da diese zuerst an den Wandthermostaten übermittelt wird und dieser erst mit etwas Verzögerung die Daten an die Heizkörperthermostaten weiterreicht.
* eventuelles Wochenprogramm kann nur an einer Stelle eingespielt werden (nämlich in den Wandthmermostaten), man kann also nicht einzelnen Heizkörpern abweichende Programme geben. Da man einen Wandthermostat wohl in der Praxis nur mit Heizkörperthermostaten '''eines''' einzelnen Raumes peeren wird, ist dieser Nachteil ggf eher theoretischern Natur.

=== Steuerung aller Komponenten durch FHEM ===

Diese Methode wird zumindest von den meisten Nutzern des Forums favorisiert, weil sie mehr Kontrolle auch über Details und Geräte ermöglicht.

In diesem Fall werden zunächst alle Geräte - also die Heizkörperthermostate und der Wandthermostat - wie in [[HomeMatic Devices pairen]] beschrieben mit FHEM (also i.d.R. der VCCU) gepairt.

Danach kann das [[Peering (HomeMatic)|Peering]] mit den Heizkörperthermostaten des betreffenden Raumes stattfinden. Je nach Funktion sind dazu einer oder mehrer Channels zu peeren, Details weiter unten.

Vorteile dieser Methode:
* direkte Kontrolle über die Heizkörperthermostate, Verfügbarkeit Daten wie z.B Valevöffnungsgrad FHEM, Batteriestatus, am jedem Heizkörper gemessene Temperatur etc.; diverse Paramter am Heizkörperthermostat konfigurierbar, wie Button lock, boost-time, remote Kanal zur Abschaltung, temp-offset, maximale Ventilöffnung etc.
* schneller Übermittlung der Zieltemperatur (und sonstiger Daten), da diese zugleich an alle gepeerten Thermostaten übermittelt wird.
* Wochenprogramm frei in alle Geräte übertragbar, dadurch in grossen Räumen gezieltes Ansteuern einzelner Heizkörper möglich etc.

Nachteile dieser Methode:
* deutlich komplexer in der Einrichtung
* mehr Geräte in FHEM, mehr Daten, mehr Defs notwendig, höhere Prozessorlast, höhere Auslastung des Funkkontingents an der HM Funkschnittstelle von FHEM (zumindest für ''normale'' Anzahl von Thermostaten eher theoretischer Natur)
* Zieltemperatur kann ohne FHEM nicht mehr am HM-TC-IT-WM-W-EU Funk-Wandthermostat eingestellt werden, sondern müsste an jedem Heizkörper einzeln eingestellt werden.
* Wochenprogramm muss ggf auf mehrere Geräte verteilt werden.

Bei der Steuerung aller Komponenten über FHEM müssen je nach Anwendungsfall bestimmte Channels gepeert werden.

==== Channels (Kanäle) ====

===== Channel (Kanal) 01 _Weather =====
Damit das [[HM-CC-RT-DN Funk-Heizkörperthermostat]] die Temperatur des Wandthermostats übernimmt, muss der Weather Kanal gepeert werden:

set <HM-TC-IT-WM-W-EU-Gerät>_Weather peerChan 0 <HM-CC-RT-DN-Gerät>_Weather single set

Hinweis: Nach jeden dieser peer Aufgaben, sollte am Thermostat sowie am Wandthermostat die Status-Meldung CMDs_pending abgewartet werden, bis wieder CMDs_done ausgegeben wird. Andernfalls bekommt man ggf. unerwartete Probleme oder es wird ggf. beim Thermostat oder beim Wandthermostat das peer nicht sauber durchgeführt.

===== Channel (Kanal) 02 _Climate =====
Damit der Heizkörperthermostat vom Wandthermostat auch eingestellt werden kann (Soll-Temperatur, Mode etc.), muss der Climate Kanal gepeert werden:

set <HM-TC-IT-WM-W-EU-Gerät>_Climate peerChan 0 <HM-CC-RT-DN-Gerät>_Climate single set
Dies muss für jedes zu steuernde Heizkörperthermostat wiederholt werden.

===== Channel (Kanal) 03 _WindowRec =====
Mit diesem Kanal lassen sich Fensterkontakte (HM-SEC-SC oder HM-SEC-RHS) peeren, die ihren Fensterstatus (geöffnet/gekippt) an ein oder mehrere Thermostate senden. Die Thermostate stellen anschließend die entsprechende (konfigurierbare) Temperatur ein. Der Temperaturwert kann je Fenster-Sensor unterschiedlich definiert werden. Sind mehrere Fenster gleichzeitig geöffnet, so wird der Thermostat auf die Temperatur des Sensors mit dem geringsten Temperaturwert eingestellt.

Damit der Tür-Fensterkontakt den Thermostat aufwecken kann, muss zuerst der Burst-Modus aktiviert werden, siehe dazu [[HM-SEC-SC_Tür-Fensterkontakt#Problembehebung]].

Das eigentliche Peering mit einem Tür-Fensterkontakt läuft wie folgt ab:

set <HM-Sec-SC> peerChan 0 <HM-TC-IT-WM-W-EU-Gerät>_WindowRec single set

Der Befehl zur Temperatureinstellung des Heizkörperthermostaten für den Zustand "Fenster offen" lautet, wobei <fensterSensor> die FHEM-Kanalbezeichnung für den Fensterkontakt ist und <tc_WindowRec> die Kanalbezeichnung für den entsprechenden Kanal des Heizkörperthermostates, sowie <Temp> die einzustellende Temperatur (ganzzahliger Wert):
set <tc_WindowRec> regSet winOpnTemp <Temp> <fensterSensor>

===== Channel (Kanal) 06 _remote =====
Dieser Kanal kann an eine Fernbedienung gekoppelt werden. Per Tastendruck kann man einen bestimmten Mode und/oder eine bestimmte Temperatur wählen. Dabei kann die Reaktion auf einen langen oder kurzen Tastendruck gesondert eingestellt werden.

Der Befehl zum peeren lautet, wobei <button> die Kanalbezeichnung der Fernbedienung und <tc-remote> die Kanalbezeichnung des Heizkörperthermostates ist:
<pre>set <button> peerChan 0 <rt-remote> single</pre>

===== Channel (Kanal) 07 _SwitchTr =====
Dieser Kanal kann direkt mit einem HomeMatic-Schaltaktor verknüpft (gepeert) werden, um temperaturgesteuerte Schaltvorgänge auszulösen. Eine direkte Nutzung als Feuchtigkeitssensor zur Lüftungssteuerung ist hingegen nicht möglich. Geeignete Aktoren sind alle dauerhaft mit Klein- oder Netzspannung versorgten Aktoren, die zum Betrieb keinen sog. Burst benötigen (Hutschienen-, Unterputz- und Wandmontage). Nicht geeignet sind demnach die batterieversorgten ein- oder vierkanaligen HM-LC-Sw(x)-BA-PCB-Aktoren oder das Empfangsmodul HM-MOD-Re-8, weil der Thermostat den zum "Aufwecken" dieser Geräte nötigen Burst nicht senden kann.

Das Peering mit einem Schaltaktor läuft z.B. wie folgt ab:

set <HM-TC-IT-WM-W-EU_SwitchTr> peerChan 0 <HM-LC-SW1-FM> single set

Dies allein ist nicht ausreichend, da der so gepeerte Aktor sich bei jedem Heizbefehl abwechselnd ein- und ausschaltet, da er die Ausschaltbefehle des Thermostaten (short trigger mit Wert 0) ignoriert. Um das zu korrigieren, wird er so programmiert, dass er, wenn eingeschaltet, auf den Ausschaltbefehl reagiert (und ihn ansonsten ignoriert):

set <HM-LC-SW1-FM> regSet shCtOn ltLo <HM-TC-IT-WM-W-EU_SwitchTr>

Möchte man mit dem Aktor ein inverses Verhalten erreichen (etwa beim Einsatz als Kühlthermostat oder für stromlos offene Ventilsteuerköpfe von Fußbodenheizungen), so setzt man '''stattdessen'''

set <HM-LC-SW1-FM> regSet shCtOff ltLo <HM-TC-IT-WM-W-EU_SwitchTr>

== Einstellungen ==

Die folgenden Einstellungen werden in **Registern** des HM-TC-IT-WM-W-EU vorgenommen. Das heißt, dass diese Einstellungen im Gerät selbst gespeichert werden, nicht in der Konfigurations-Datei von FHEM.

=== Anzeige ===

Register im Kanal 2 ''(_Climate)'' erlauben es zu konfigurieren, welche Daten der HM-TC-IT-WM-W-EU in seinem LC-Display anzeigt.

==== showInfo time|date ====

Wählt aus, ob die ''Uhrzeit'' (<code>time</code>, Standard-Einstellung) oder das ''Datum'' (<code>date</code>) angezeigt wird. Der folgende Befehl erlaubt es das Datum anzeigen zu lassen:

set <HM-TC-IT-WM-W-EU>_Climate regSet showInfo date

==== showSetTemp actTemp|setTemp ====

Wählt aus, ob die ''Ist-Temperatur'' (<code>actTemp</code>, Standard-Einstellung) oder die ''Soll-Temperatur'' (<code>setTemp</code>) im Display angezeigt wird.

set <HM-TC-IT-WM-W-EU>_Climate regSet showSetTemp setTemp

==== showHumidity temp|tempHum ====

Wählt aus, ob dauerhaft die ''Temperatur'' (<code>temp</code>, Standard-Einstellung) oder ''Temperatur und Luftfeuchtigkeit'' im Wechsel (<code>tempHum</code>) im Display angezeigt werden.

set <HM-TC-IT-WM-W-EU>_Climate regSet showHumidity tempHum

=== Tastensperre ===

Um zu verhindern, dass der Modus oder die Temperatur per Tasten bzw. Drehrad am HM-TC-IT-WM-W-EU verändert wird, kann eine Tastensperre gesetzt werden. Dies erfolgt mittels des Befehls:

set <HM-TC-IT-WM-W-EU> regSet btnLock on

Rückgängig machen geht per:

set <HM-TC-IT-WM-W-EU> regSet btnLock off

Diese Tastensperre kann man aber am Thermostat durch eine Tastenkombination wieder zurücksetzen. Um sie nur per FHEM rücksetzen zu können, muss

set <HM-TC-IT-WM-W-EU> regSet globalBtnLock on

abgesetzt werden. Rückgängig wieder per:

set <HM-TC-IT-WM-W-EU> regSet globalBtnLock off

=== Temperaturlisten ===

Die Temperaturlisten des HM-TC-IT-WM-W-EU werden identisch zu anderern HomeMatic Thermostaten verwaltet, siehe [[HomeMatic Type Thermostat#Temperaturlisten|HomeMatic Type Thermostat]]. Beim HM-TC-IT-WM-W-EU ist der Kanal 2 ''(_Climate)'' für die Temperaturlisten zuständig.

=== Luftfeuchtigkeit in SVG Plot ===

Um die Luftfeuchtigkeit im Plot darzustellen benötigt man im Logfile folgenden Eintrag:

2017-10-24_22:03:12 WANDTHERMOSTAT_Weather humidity: 61

Um diesen zu erhalten muss man in der Logfile Konfiguration evtl. das DEF um die Weather Information erweitern:

Standardbeispiel:
./log/WANDTHERMOSTAT-%Y.log WANDTHERMOSTAT

Erweiterung:
./log/WANDTHERMOSTAT-%Y.log WANDTHERMOSTAT|WANDTHERMOSTAT_Weather:.*

Nach einer Weile, sollte der Eintrag "WANDTHERMOSTAT_Weather humidity:" im SVG Plot zur Auswahl zur Verfügung stehen.

== FHEM-Log ==
=== Event monitor ===

Hier habe ich einmal die Wunschtemperatur erhöht, damit auch was passiert:

2014-04-09 09:35:11 CUL_HM KH_Bad_Therm CMDs_pending
2014-04-09 09:35:11 CUL_HM KH_Bad_Therm_Climate set_desired-temp 18.0
2014-04-09 09:35:11 CUL_HM KH_Bad_Therm CMDs_done

Bei mir ist es so, das der SwitchTr Kanal nur mit dem gepeerten Device spricht, hier ein HM-LC-SW1-FM:

2014-04-09 09:35:17 CUL_HM KH_Bad_Heizung trig_KH_Bad_Therm_SwitchTr: 200
2014-04-09 09:35:17 CUL_HM KH_Bad_Heizung trigLast: KH_Bad_Therm_SwitchTr :200

Der hat auch prompt reagiert und die Heizung eingeschaltet:

2014-04-09 09:35:17 CUL_HM KH_Bad_Heizung level: 100
2014-04-09 09:35:17 CUL_HM KH_Bad_Heizung pct: 100
2014-04-09 09:35:17 CUL_HM KH_Bad_Heizung deviceMsg: on (to KH_Bad_Therm)
2014-04-09 09:35:17 CUL_HM KH_Bad_Heizung on
2014-04-09 09:35:17 CUL_HM KH_Bad_Heizung timedOn: off

und noch ein wenig Geplauder der vorhandenen Kanäle:

2014-04-09 09:36:39 CUL_HM KH_Bad_Therm_Climate measured-temp: 16.0
2014-04-09 09:36:39 CUL_HM KH_Bad_Therm_Climate desired-temp: 18.0
2014-04-09 09:36:39 CUL_HM KH_Bad_Therm_Climate humidity: 50
2014-04-09 09:36:39 CUL_HM KH_Bad_Therm_Climate T: 16.0 desired: 18.0
2014-04-09 09:36:49 CUL_HM KH_Bad_Therm battery: ok
2014-04-09 09:36:49 CUL_HM KH_Bad_Therm batteryLevel: 3
2014-04-09 09:36:49 CUL_HM KH_Bad_Therm measured-temp: 16.0
2014-04-09 09:36:49 CUL_HM KH_Bad_Therm desired-temp: 18.0
2014-04-09 09:36:49 CUL_HM KH_Bad_Therm_Climate measured-temp: 16.0
2014-04-09 09:36:49 CUL_HM KH_Bad_Therm_Climate desired-temp: 18.0
2014-04-09 09:36:49 CUL_HM KH_Bad_Therm_Climate mode: auto
2014-04-09 09:36:49 CUL_HM KH_Bad_Therm_Climate T: 16.0 desired: 18.0
2014-04-09 09:36:59 CUL_HM KH_Bad_Therm_Weather temperature: 16.0
2014-04-09 09:36:59 CUL_HM KH_Bad_Therm_Weather humidity: 50
2014-04-09 09:36:59 CUL_HM KH_Bad_Therm_Weather T: 16.0 H: 50

== Virtuelle Peers: Simulation von Fensterkontakten u.A. ==
=== Simulation von Fensterkontakten ===
Das beim [[HM-CC-RT-DN Funk-Heizkörperthermostat#Simulation von Fensterkontakten und externen Temperatursensoren|HM-CC-RT-DN]] beschriebene Verfahren zum Peering mit einem virtuellen Tür- oder Fensterkontakt kann auch beim ''HM-TC-IT-WM-W-EU'' entsprechend umgesetzt werden.
Anders als der ''HM-CC-RT-DN'' kann der ''HM-TC-IT-WM-W-EU'' dabei Schaltsignale von mehreren Kanälen eines virtuellen Devices unterscheiden, so dass die Anlage je eines eigenen (Stamm-) Devices nicht zwingend erforderlich ist, wenn man nur den Fensterkanal des ''HM-TC-IT-WM-W-EU'' zur Steuerung einer Gruppe aus WT und RT nutzen will.
=== Schalten von Aktoren anderer Hersteller mit dem Trigger-Kanal===
Peert man den ''SwitchTr''-Kanal mit einem Kanal eines virtuellen Devices, kann man die dort eingehenden Events auswerten, um Aktoren beliebiger anderer Systeme zu steuern.

== Firmware Update ==
Updates für den HM-TC-IT-WM-W-EU können von der eQ-3 Webseite heruntergeladen werden. Genauere Informationen gibt es unter [[HomeMatic_Firmware_Update]]. Das Thermostat wird in den Updatemodus gebracht, indem beide äußeren Tasten gedrückt werden, während die Batterien eingesetzt werden. Das Display zeigt "FUP" an.

== Bekannte Probleme ==
* Bei der Firmware 1.2 und dem Kanal Climate funktioniert die Einstellung der Hysterese über das Register hyst2point nicht. Der Eintrag wird ignoriert.

Siehe auch Bericht im [https://de.elv.com/forum/hm-tc-it-wm-w-eu-hystereseeinstellung-hat-keine-funktion-10076 Forum von ELV]

* Der Sensor sollte nur innerhalb seiner Spezifikationen (0° - 50°C) betrieben werden; bei kleineren Temperaturen werden überhöhte Temperaturen gesendet, siehe {{Link2Forum|Topic=80383|LinkText=dieser Forumsbeitrag}}.

== Links ==
* [https://www.eq-3.de/downloads/download/homematic/bda/hm-tc-it-wm-w-eu_um_ge_eq-3_web.pdf Manual]
* [https://www.eq-3.de/downloads/download/homematic/pdb/funk-wandthermostat_132030a0_produktdatenblatt_v14.pdf Produktdatenblatt]

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

DbLog

2017-10-22T19:02:15Z

Joshi04: /* Bekannte Probleme */ gelöscht, da obsolete

{{Infobox Modul
|ModPurpose=Protokolliert Ereignisse in einer Datenbank
|ModType=h
|ModForumArea=Automatisierung
|ModTechName=93_DbLog.pm
|ModOwner=tobiasfaust ({{Link2FU|118|Forum}}/[[Benutzer Diskussion:Tobias.faust|Wiki]])
}}

== Einleitung ==
Mit der Zeit entstehen im fhem recht umfangreiche Log-Daten für die verschiedensten konfigurierten Devices. Die übliche Einstiegs-[[Konfiguration]] sieht vor, dass die Logs als [http://fhem.de/commandref_DE.html#FileLog FileLog] gespeichert werden - je nach Einstellung in wenigen sehr großen oder vielen kleineren Dateien. Der Datei-basierte Zugriff ist allerdings nicht wirklick performant und kann schnell zum Flaschenhals werden (z.B. bei der Darstellung von Graphen über einen längeren Zeitraum).

Alternativ kann Fhem die Log-Daten mittels [http://fhem.de/commandref_DE.html#DbLog DbLog] in einer Datenbank speichern. Diese kann lokal als einfache SQLite- oder als zentrale Server-Datenbank (s.u.) gestaltet sein. Schon eine lokale einfache SQLite-Datenbank ist in der Regel deutlich performanter als File-basierte Logs.

Damit eine Datenbank-Nutzung möglich ist, müssen folgende Anpassungen gemacht werden:
# [[#Datenbank|Erstellen einer entsprechenden Datenbank]]
# [[#Datenbank-Anbindung mittels db.conf|Konfiguration der Datenbank-Anbindung in FHEM]]
# [[#Konfiguration als Device in fhem.cfg|Anpassen aller (oder einzelner) Konfigurationen von FileLog nach DbLog]]
# [[#Anpassen der gplot-Konfigurationen|Ggf. Anpassen der gplot-Konfigurationen]]

== Konfiguration ==
=== Datenbank-Anbindung mittels db.conf ===
DbLog wird durch 2 verschiedene Einträge aktiviert/definiert. In einer Datei namens '''db.conf''' werden die Parameter für eine Verbindung zur Datenbank (host, username, password, etc.) hinterlegt. Diese Datei kann in einem beliebigen Verzeichnis angelegt werden. Für eine MySQL-Datenbank sieht die db.conf folgendermaßen aus:

%dbconfig= (
connection => "mysql:database=fhem;host=db;port=3306",
user => "fhemuser",
password => "fhempassword",
);

Im Verzeichnis '''contrib/dblog''' der FHEM-Installation befindet sich eine Beispielkonfiguration mit der Syntax für jeden unterstützen Datenbanktyp.
Es wird empfohlen diese Datei zu kopieren und erst dann entsprechend zu bearbeiten. Am Besten kopiert man diese Datei in das FHEM Home Directory /opt/fhem/ und achtet auf die entsprechenden Rechte!
chown fhem:dialout /opt/fhem/db.conf

=== Konfiguration als Device ===
Das DbLog Device wird dann definiert mit
:<code>define <name> DbLog <configfilename> <regexp> </code>
wobei ''<configfilename>'' dem Pfad zur zuvor angelegten db.conf entspricht.
Ein Beispiel hierfür wäre:
:<code>define logdb DbLog ./db.conf .*:.* </code>
Die Angabe von <code>.*:.*</code> bedeutet, dass sämtliche DeviceMessages (Messwerte, Batteriestatus, KeepAlives, etc.) in die Datenbank geschrieben werden. Dies führt u.U. dazu, dass die Datenbank auch mit vielen teils irrelevanten Werten gefüllt wird. Man kann daher die zu loggenden Werte einschränken, indem man genau angibt welche Werte übertragen werden sollen. Dies ist in [[#Finetuning des Loggings]] beschrieben.

=== Finetuning des Loggings ===
Bei der Konfiguration des Log-Devices werden die zu loggenden Daten definiert - in der einfachsten Form sieht das so aus: <code>define logdb DbLog ./db.conf .*:.* </code>. Die Angabe von <code>.*:.*</code> bedeutet, dass sämtliche DeviceMessages (Messwerte, Batteriestatus, KeepAlives, etc.) in die Datenbank geschrieben werden. Dies führt u.U. dazu, dass die Datenbank auch mit sehr vielen und teils nicht benötigten Werten gefüllt wird und schnell wächst. Die Datenbank ist zwar deutlich leistungsfähiger, was große Datenmengen angeht, Datensparsamkeit kann aber schnell sinnvoll werden...

Um das Log-Aufkommen einzugrenzen gibt es 2 Ansätze:
* Einschränkung über den <code>define</code>-Eintrag
* Einschränkung über DbLogExclude-Einträge der jeweiligen Devices
* Einschränkung über DbLogInclude-Einträge des jeweiligen Devices

==== Einschränkung über den zentralen <code>define</code>-Eintrag ====
Man kann die zu loggenden Werte einschränken, indem man genau angibt welche Werte übertragen werden sollen. Die erste Wildcard, also das erste <code>.*</code>, entspricht dem in FHEM verwendeten Device-Namen. Die zweite Wildcard entspricht dem vom Device ausgegebenen zu loggenden Wert. Separiert werden beiden Angaben durch einen Doppelpunkt.

Ein Beispiel, um zwar alle definierten Devices zu erfassen, aber nur die Werte Temperatur, Ventilposition und Luftfeuchte in die Datenbank zu schreiben wäre:
:<code>define myDbLog DbLog ./db.conf .*:(temperature|valveposition|humidity).* </code>

==== Einschränkung über die jeweiligen Devices ====
Man kann die zu loggenden Werte für einzelne Devices separat einschränken, ohne dies im zentralen define-Eintrag machen zu müssen. Dies kann interessant sein, wenn beispielsweise ein Device Fehlerwerte meldet, die uninteressant sind, oder es meldet unnötig häufig Werte - beides ist z.B. bei 1-wire-Temperatursensoren gerne der Fall.

Um das einzuschränken gibt es 2 Stellparameter, die als Attribute direkt zum jeweiligen Device konfiguriert werden:
* DbLogExclude - definiert Werte, die nicht geloggt werden sollen
* DbLogInclude - definiert Werte, die geloggt werden sollen ( siehe attr DbLogSelectionMode )
* event-min-interval, event-on-change-reading und event-on-update-reading beeinflussen, wie häufig Werte geloggt werden (vgl. [http://fhem.de/commandref_DE.html#event-on-update-reading commandref])

Eine konkrete Konfiguration für einen sehr gesprächigen 1-wire-Temperatursensor könnte wie folgt aussehen:
<pre>
define EG_Balkon GPIO4 BUSMASTER
attr EG_Balkon DbLogExclude failures,T,85 # logge keine "failures", "T"-Werte und "85"-Werte (default-Werte, wenn keine Temperatur gelesen werden kann)
attr EG_Balkon event-on-change-reading state # logge nur, wenn sich ein Wert ändert (wenn sich die Temperatur nicht ändert, logge das nicht)
attr EG_Balkon event-min-interval state:900 # logge spätestens alle 900sec = 15min
attr EG_Balkon event-on-update-reading .* # logge alle Werte, die aktualisiert werden

attr <1-Wire-Device vom Typ OWTHERM oder OWSWITCH> DbLogExclude data.* # verhindert das Logging der state-Eintragungen
</pre>

Eine in diesem {{Link2Forum|Topic=33697|Message=264127}} vorgestellte Strategie zur Vermeidung unnötigen Loggings ist, dass bei der Definition von Devices durch das nachfolgende <code>notify</code> automatisch ein DbLogExclude für alle Werte (.*) des Devices zugewiesen wird und dies nur bei Interesse an geloggten Werten gelöscht bzw. angepasst wird:
<code>define nDbLogExclude notify global:DEFINED.* attr $EVTPART1 DbLogExclude .*</code>

Ebenso ist es mittlerweile möglich, lediglich erwünschte Werte (Positiv-Liste) zu loggen und alle anderen zu verwerfen. Hierfür wird im LogDevice das attribut DbLogSelectionMode Include verwendet. Nun kann für jedes Device mit DbLogInclude <Reading1>,<Reading2>,... angegeben werden, welche Readings geloggt werden sollen.
Integriert ist ebenfalls ein "min-interval", siehe commandref.

== Datenbank ==
Unterstützte Datenbanksysteme (Auswahl):
* Sqlite
* MySQL
* PostGreSql

=== Tabellen ===
Die Datenbank ist relativ simpel gestaltet und besteht lediglich aus den folgenden beiden Tabellen:
* current
* history

DbLog ist auf eine feste Tabellenstruktur angewiesen. Man muss daher in seiner Datenbank eine Tabelle mit folgenden Spalten anlegen:
{| class="wikitable"
|-
! Spalte
! Beschreibung (en)
! Beschreibung (de)
! Beispiel
|-
| '''TIMESTAMP'''
| timestamp of event
| Zeitstempel
| 2007-12-30 21:45:22
|-
| '''DEVICE'''
| device name
| Device-Name
| Wetterstation
|-
| '''TYPE'''
| device type
| Device-Typ
| KS300
|-
| '''EVENT'''
| event specification as full string
| Eventspezifikation als Text
| humidity: 71 (%)
|-
| '''READING'''
| name of reading extracted from event
| Bezeichnung des Readings
| humidity
|-
| '''VALUE'''
| actual reading extracted from event
| Wert des Readings
| 71
|-
| '''UNIT'''
| unit extracted from event
| Einheit des Readings
| %
|-
|}

Die Vorlagen zur Anlage von Tabellen und Indizes sind für jeden unterstützten Datenbanktyp im Verzeichnis '''contrib/dblog''' der FHEM-Installation, oder hier zu finden: [https://svn.fhem.de/trac/browser/trunk/fhem/contrib/dblog/ Link]. Das MySQL-Skript (db_create_mysql.sql) legt eine neue Datenbank, das PostGres-Skript (db_create_postgresql.sql) ein neues Schema mit Namen "fhem" an.

==== current ====
Die Tabelle current enthält für jedes zu loggende Device lediglich den letzten Wert. Falls noch kein Wert geloggt wurde, ist diese Tabelle leer.
Falls der Inhalt gelöscht wird, bauen sich die Daten automatisch wieder auf. Es gehen durch das löschen der Tabelle current keine Log-Informationen verloren.
Der Inhalt wird aber u.a. für die Dropdown-Felder beim Plot-Editor verwendet.

Um doppelte Einträge in der Tabelle zu vermeiden, wurden die Möglichkeit geschaffen Primary Keys zu definieren. Da in der Spalte <code>READING</code> u.U. bei verschiedenen Geräten gleiche Namen vorkommen können, sollte der Primary Key um den Gerätenamen erweitert werden. Der Primary Key sollte also aus <code>DEVICE</code> und <code>READING</code> bestehen. Um in der Datenbank ''fhem'' diesen PK zu setzen, kann folgender SQL Code verwendet werden:

<syntaxhighlight lang="sql">
ALTER TABLE `fhem`.`current`
CHANGE COLUMN `DEVICE` `DEVICE` VARCHAR(64) CHARACTER SET 'utf8' COLLATE 'utf8_bin' NOT NULL ,
CHANGE COLUMN `READING` `READING` VARCHAR(64) CHARACTER SET 'utf8' COLLATE 'utf8_bin' NOT NULL ,
ADD PRIMARY KEY (`DEVICE`, `READING`);
</syntaxhighlight>

==== history ====
Die Tabelle history enthält alle bisher geloggten Daten. Löschen in dieser Tabelle bedeutet automatisch Datenverlust (gewollt oder nicht ... )
Der Inhalt dieser Tabelle wird verwendet, um die Plots zu zeichnen oder Auswertungen mit [https://wiki.fhem.de/wiki/DbRep_-_Reporting_und_Management_von_DbLog-Datenbankinhalten DbRep] anzufertigen

== Anpassen der gplot-Konfigurationen ==
Die meisten gplot-Konfigurationen sind bisher lediglich auf FileLog-Konfigurationen ausgelegt. Deshalb müssen sie für die Verwendung mit DbLog angepasst werden. Glücklicherweise beschränkt sich dies auf die reinen FileLog-Zeilen - es müssen die DbLog-Äquivalente hinzugefügt werden. Die FileLog-Einträge müssen zwar nicht gelöscht werden, wenn man aber FileLog und DbLog parallel betreibt, sollte man getrennte gplot-Dateien für beide Logging-Typen haben um Auswertungsprobleme erkennen zu können.

Für die fht.gplot Konfiguration sähe die Anpassung wie folgt aus (lediglich die vier DbLog-Zeilen wurden hinzugefügt):
<pre>
# Created by FHEM/98_SVG.pm, 2014-12-25 21:53:30
set terminal png transparent size <SIZE> crop
set output '<OUT>.png'
set xdata time
set timefmt "%Y-%m-%d_%H:%M:%S"
set xlabel " "
set title '<L1>'
set ytics nomirror
set y2tics
set grid y2tics
set ylabel "Actuator/Window (%)"
set y2label "Temperature in C"
set yrange 0:100
set y2range 5:25

#FileLog 4:.measured-temp\x3a:0:
#FileLog 4:.actuator\x3a:0:int
#FileLog 4:.desired-temp::
#FileLog 4:.window\x3a::

#DbLog <SPEC1>:.measured-temp:0:
#DbLog <SPEC1>:.actuator:0:int
#DbLog <SPEC1>:.desired-temp::
#DbLog <SPEC1>:.window::

plot "<IN>" using 1:2 axes x1y2 title 'Measured temperature' ls l0 lw 1 with lines,\
"<IN>" using 1:2 axes x1y1 title 'Actuator (%)' ls l1 lw 1 with lines,\
"<IN>" using 1:2 axes x1y2 title 'Desired Temperature' ls l2 lw 1 with steps,\
"<IN>" using 1:2 axes x1y1 title 'Window' ls l3 lw 1 with steps
</pre>

Des weiteren ist zu beachten:

On-Off-Plots

EG_Bad:window:::$val=~s/(on|off)(\d*).*/$1eq"on"?1:0/eg

unter Berücksichtigung von dim-Werten:

EG_WoZi_Licht:value:::$val=~s/(on|off)(\d*).*/$1eq"on"?1:($1eq"dim"?$2*0.01:0)/eg

== Beispiel: Anlegen und Nutzung einer SQLite-Datenbank ==
Im folgenden wird eine lokale SQLite-Datenbank auf einen Ubuntu-System angelegt (nach Quelle: [http://www.tatsch-it.de/fhem-dblog/ http://www.tatsch-it.de/fhem-dblog/])
<ol>
<li>
''Installation von SQLite:''
<pre>sudo aptitude install sqlite3 libdbi-perl libdbd-sqlite3-perl</pre>
</li>
<li>
''Anlegen der SQLite-Datenbank fhem.db'' (öffnet auch direkt eine SQL-Kommandozeile):
<pre>sudo sqlite3 /opt/fhem/fhem.db</pre>
In der geöffneten SQL-Kommandozeile eingeben:
<pre>
CREATE TABLE 'history' (TIMESTAMP TIMESTAMP, DEVICE varchar(64), TYPE varchar(64), EVENT varchar(512), READING varchar(64), VALUE varchar(128), UNIT varchar(32));
CREATE TABLE 'current' (TIMESTAMP TIMESTAMP, DEVICE varchar(64), TYPE varchar(64), EVENT varchar(512), READING varchar(64), VALUE varchar(128), UNIT varchar(32));
CREATE INDEX Search_Idx ON `history` (DEVICE, READING, TIMESTAMP);
</pre>
Die Kommandozeile verlässt man mit <code>.exit</code>.
</li>
<li>
''Anpassen des Besitzers und der Rechte der Datenbank-Datei:''
<pre>
sudo chown fhem /opt/fhem/fhem.db
sudo chmod 666 /opt/fhem/fhem.db
</pre>
</li>
<li>
''Datenbank-Anbindung des FHEM konfigurieren:''
<pre>sudo nano /opt/fhem/db.conf</pre>
Inhalt:
<pre>
%dbconfig= (
connection => "SQLite:dbname=/opt/fhem/fhem.db",
user => "",
password => ""
);
</pre>
</li>
<li>
''Logging des FHEM auf die Datenbank konfigurieren:'' (hier sind nur die Anpassungen aufgeführt)
<pre>sudo nano /opt/fhem/fhem.cfg</pre>
<pre>
...
attr global userattr DbLogExclude ... # erlaubt es einzelne Einträge nicht zu loggen
...
define logdb DbLog ./db.conf .*:.* # logt alle(!) auflaufenden Events aller Konfigurationen
...
</pre>
Da durch diese <code>define</code>-Definition alle auflaufenden Events gelogt werden, müssen keine weiteren Anpassungen in der Konfiguration gemacht werden. Die FileLog-Einträge können bedenkenlos bestehen bleiben - dann wird in Datenbank und FileLog gelogt und man verliert keine Daten, falls etwas nicht klappt. Wenn alles wie geplant läuft, können die FileLog-Definitionen gelöscht werden (ebenso die Log-Dateien). Ebenso können die zu loggenden Daten später eingegrenzt werden (s. [[#Finetuning des Loggings]]).
</li>
<li>
''FHEM neu starten:''
<pre>
sudo service fhem stop
sudo service fhem start
</pre>
</li>
<li>
''Kontrollieren, ob Logs in die Datenbank geschrieben werden:''
<pre>sudo sqlite3 /opt/fhem/fhem.db</pre>
In der geöffneten SQL-Kommandozeile eingeben:
<pre>
select * from history order by TIMESTAMP; # dies gibt alle(!) Logs chronologisch aus (kann nach längerem Betrieb recht lange dauern)
</pre>
Die Kommandozeile verlässt man mit <code>.exit</code>.
</li>
<li>
''Anpassung der glot-Dateien:'' siehe [[#Anpassen der gplot-Konfigurationen]]
</li>
</ol>

== Beispiel: Anlegen und Nutzung einer Mysql-Datenbank ==
Anstatt nano kann jeder andere kompatible Editor verwendet werden. Weiterhin bitte beachten, dass die hier genannten Befehle teilweise root-Rechte voraussetzen. Entweder komplett als root arbeiten, oder mittels sudo.

Unter Ubuntu/debian:
apt-get update && apt-get install mysql-server mysql-client libdbd-mysql libdbd-mysql-perl

Bei der Installation sollte man aus Sicherheitsgründen ein Passwort für den mysql-root vergeben, wenn man nicht sogar ganz den Login verbietet.

Hinweis: im Folgenden ist "#" der normale Prompt und "mysql>" der prompt innerhalb mysql, dieser kann mit exit verlassen werden.

Zum Test mal mit mysql verbinden:
# mysql -p -u root
Enter password:
mysql> exit

Jetzt die Tabellenstruktur anlegen.
Hierfür kann die Datei /opt/fhem/contrib/dblog/db_create_mysql.sql als Vorlage verwendet und das Passwort und der Benutzername geändert werden.
cd /opt/fhem/contrib/dblog/
nano db_create_mysql.sql
Dann wird die Datei eingelesen (root Passwort wird abgefragt):

# mysql -u root -p < db_create_mysql.sql

Jetzt kann man den Zugang testen:

# mysql -p -u <fhemuser>
Enter password: <fhempassword>
mysql> show databases;

Nun müsste eine Datenbank "fhem" angezeigt werden, die die Tabellen current und history enthält.

Nun in der Datei db.conf den mysql-Block auskommentieren und ebenfalls Benutzername, Passwort UND HOST anpassen. Leider ist hier nicht standardmäßig localhost eingestellt.
nano /opt/fhem/db.conf

Jetzt kann unter FHEM ein DbLog-Device angelegt werden (mit dem beispiel wird alles geloggt:
define logdb DbLog ./db.conf .*:.*
Als State muss ein "connected" angezeigt werden.

Ein rereadcfg in Fhem stellt sicher, dass die neue Konfiguration übernommen wird - ein Neustart ist nicht erforderlich

Nun kann die Funktion noch einmal überprüft werden:
<syntaxhighlight lang="sql">
# mysql -u <fhemuser> -p
Enter password: <fhempassword>
mysql> use fhem;
Database changed
mysql> show tables;
+----------------+
| Tables_in_fhem |
+----------------+
| current |
| history |
+----------------+
2 rows in set (0,00 sec)
mysql> select * from history; # Achtung, kann sehr groß werden .... #
</syntaxhighlight>

== Integration von DBLog in eigene Module ==
=== Bereitstellung der UNITS ===
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.

Dazu muss der Modulautor in der [[DevelopmentModuleIntro#X_Initialize|Initialize-Funktion]] eine <code>DbLog_splitFn</code> bereitstellen:

<syntaxhighlight lang="perl">
sub X_Initialize($)
{
my ($hash) = @_;
...
$hash->{DbLog_splitFn} = "X_DbLog_splitFn";
}
</syntaxhighlight>

Die genaue Aufrufsyntax und Funktionweise einer DbLog_split-Funktion findet man [[DevelopmentModuleIntro#X_DbLog_split|hier]].

== Werte auslesen ==
Manchmal möchte man Daten aus den Logs abrufen ohne händisch in der Datenbank herumzuwühlen (s.u.). Dies ist insb. auch dann hilfreich, wenn man eigenen Funktionen, Notifys oder spezielle Plots entwirft, bei denen man auf Logdaten zugreifen möchte.

Grundsätzlich beschrieben ist dies in der [http://fhem.de/commandref_DE.html#DbLog commandref#DbLog] und unterscheidet sich minimal (aber entscheidend) von der Struktur bei [[FileLog#Werte_auslesen|FileLogs]].

Hier ein paar Beispiele, was man damit anstellen kann:

* <code>get meineDB - - 2016-10-01 2016-10-03 meinSensor</code> alle Einträge des meinSensor vom 01.10.-03.10.2016
* <code>get meineDB - - 2016-10-01_08:00:00 2016-10-01_16:00:00 meinSensor</code> alle Einträge des meinSensor von 8-16 Uhr am 01.10.2016
* <code>get meineDB - - 2016-10-01_08:00:00 2016-10-01_16:00:00 meinSensor:temperature</code> nur die temperature Werte
* <code>{ ReadingsTimestamp("meinSensor","state","0") }</code> Timestamp des aktuellen state des meinSensor
* <code>{ OldTimestamp("meinSensor") }</code> Timestamp des letzten state des FHT_3a32
* <code>{ time_str2num(OldTimestamp("meinSensor")) }</code> Timestamp in Sekunden des letzten state des meinSensor
* ...

== Bearbeitung von Datenbank-Einträgen ==
{{Hinweis|Dieser Abschnitt soll lediglich eine kleine Einführung in die Datenbank-Bearbeitung liefern. Für vertiefende Informationen sollte man sich grundsätzlich mit SQL beschäftigen. Eine umfassende und gut verständliche Anleitung zu SQL bietet bspw. [http://www.w3schools.com/sql/default.asp w3schools].}}
Irgendwann wird der Fall eintreten, dass in der Datenbank Einträge drinstehen, die geändert oder gelöscht werden sollen (zB. fehlerhafte Sensor-Rückmeldungen, umbenannte Readings). In klassischen Log-Dateien würde man diese einfach bearbeiten und löschen/anpassen (wobei man aber tunlichst zuvor den fhem ausmacht um Datenfehler zu vermeiden). Eine Datenbank kann bearbeitet werden ohne den fhem abschalten zu müssen.

Datenbanken kann man ohne weiter Hilfsmittel direkt von der Kommandozeile/Shell aus bearbeiten. Alternativ gibt es auch verschiedenste Tools (webbasiert oder als Applikation), die einen dabei unterstützen (Bsp. findet man u.a. [https://wiki.ubuntuusers.de/SQLite/#Grafische-Benutzeroberflaechen hier]). Für einfache Arbeiten reicht allerdings idR. Shell.

=== SQLite-Datenbanken ===
'''Öffnen der DB unter Linux:'''

(Es werden Schreibrechte benötigt,ohne kann man die DB zwar öffnen, aber nichts machen)
sudo sqlite3 fhem.db
Dadurch öffnet sich ein SQL-Konsole, auf der alle weiteren Befehle ausgeführt werden.

'''Schliessen der DB:'''

sqlite> .exit

'''Hilfe anzeigen:'''

sqlite> .help

'''Alle Tabellen anzeigen:'''

sqlite> .tables

'''Das Schema der DB anzeigen:'''

(vgl. oben [[DbLog#Datenbanken]] und [[DbLog#Beispiel: Anlegen und Nutzung einer SQLite-Datenbank]])

sqlite> .schema

'''Alle Eintäge anzeigen:'''

Die Einträge liegen alle in der Tabelle "History".

'''Ganz wichtig''' ist immer das ";" am Ende Zeile (bei allen Kommandos, die nicht mit einem "." anfangen). Wenn es vergessen wurde zeigt die Konsole solange neue Zeilen bis ein ";" eingegeben wird. So kann ein Befehl auch bequem über mehrere Zeilen geschrieben werden.

sqlite> select * from HISTORY;

Dies kann sehr lange dauern und kann ggf. mit <code>STRG-C</code> abgebrochen werden.

'''Alle Einträge eines Geräts anzeigen:'''

In <code>where</code>-Statements werden Strings in einfache Anführungsstriche gesetzt, Zahlen nicht.

sqlite> select * from HISTORY where DEVICE='Pollenflug';

'''Alle Einträge eines Readings eines Geräts anzeigen:'''

sqlite> select * from HISTORY where DEVICE='Pollenflug' and READING='Graeser';

'''Alle Einträge eines bestimmten Wertes eines Readings eines Geräts anzeigen:'''

sqlite> select * from HISTORY where DEVICE='Pollenflug' and READING='Graeser' and VALUE>1;

'''LÖSCHEN aller Einträge eines bestimmten Wertes eines Readings eines Geräts anzeigen:'''

'''Achtung:''' Löschen kann nicht rückgängig gemacht werden!! Also IMMER erst die entsprechenden SELECT-Statements solange verfeinern bis wirklich nur die gewünschten Einträge angezeigt werden. Dann das <code>select *</code> durch <code>delete</code> ersetzen.

sqlite> delete from HISTORY where DEVICE='Pollenflug' and READING='Graeser' and VALUE>1;

== Datenbank reparieren ==
Es kann immer wieder mal vorkommen, dass Datenbanken Fehler enthalten. Das muss im Alltag garnicht auffallen und auch nicht immer schlimm enden. Wenn man auf der SQL-Konsole aber bspw. eine Meldung <code>Error: database disk image is malformed</code> erhält, sollte man ein Reparatur vornehmen.

=== SQLite-Datenbanken ===
Die folgenden Schritte beschreiben, wie man eine SQLite-DB reparieren kann (Quelle: [http://techblog.dorogin.com/2011/05/sqliteexception-database-disk-image-is.html]):

<ol>
<li>
DB öffnen:
<pre>sudo sqlite3 fhem.db</pre>
</li>
<li>
Integritäts-Check durchführen:
<pre>sqlite> pragma integrity_check;</pre>
Kommt hier ein "ok" ist die DB gesund. Ansonsten erscheint etwas wie
<pre>
*** in database main ***
On tree page 118786 cell 1: Rowid 75 out of order (previous was 816660)
On tree page 118786 cell 4: Rowid 815704 out of order (previous was 816727)
Corruption detected in cell 0 on page 118786
Multiple uses for byte 132 of page 118786
...
</pre>
</li>
<li>
Datenbank-Dump erstellen (Export gesamten DB in die Datei "dump_all_20160516_1043.sql") und DB verlassen:
<pre>
sqlite> .mode insert
sqlite> .output dump_all_20160516_1043.sql
sqlite> .dump
sqlite> .exit
</pre>
</li>
<li>
Neue Datenbank erstellen und den Dump einlesen, Integritäts-Check machen und verlassen:
<pre>sudo sqlite3 fhem-neu.db</pre>
<pre>
sqlite> .read dump_all_20160516_1043.sql
sqlite> pragma integrity_check;
ok
sqlite> .exit
</pre>
</li>
<li>
Spätestens jetzt fhem stoppen:
<pre>sudo service fhem stop</pre>
</li>
<li>
Alte DB sichern und neue aktivieren:
<pre>
sudo mv fhem.db fhem.db.sv_20160516
sudo mv fhem-neu.db fhem.db
</pre>
</li>
<li>
Kontrollieren, dass die neue DB die gleichen Rechte wie die alte DB hat (und ggf. korrigieren):
<pre>
~/fhem$ ls -lha
insgesamt 6,3G
drwxr-xr-x 12 fhem root 4,0K Mai 16 11:07 .
drwxr-xr-x 4 root root 4,0K Dez 25 17:50 ..
...
-rw-r--r-- 1 root root 1,4G Mai 16 11:04 fhem.db
-rw-r--r-- 1 fhem root 2,6G Mai 16 10:59 fhem.db.sv_20160516
...

~/fhem$ sudo chown fhem:root fhem.db

~/fhem$ ls -lha
insgesamt 6,3G
drwxr-xr-x 12 fhem root 4,0K Mai 16 11:07 .
drwxr-xr-x 4 root root 4,0K Dez 25 17:50 ..
...
-rw-r--r-- 1 fhem root 1,4G Mai 16 11:04 fhem.db
-rw-r--r-- 1 fhem root 2,6G Mai 16 10:59 fhem.db.sv_20160516
...
</pre>
</li>
<li>
fhem wieder starten (und natürlich kontrollieren):
<pre>sudo service fhem start</pre>
</li>
</ol>

== Nützliche Codeschnipsel ==
Anbei ein paar nützliche Codeschnipsel rund um DbLog

=== Dateigrösse mitloggen ===
Da die Datenbank ins Unermessliche wachsen kann, empfiehlt es sich - je nach Speicherplatz - ab einer bestimmten Grösse tätig zu werden. Dazu muss diese Grösse allerdings ermittelt werden. Diese geschieht mittels des Userreadings, welches man vorteilshafterweise mit im DbLog-device anlegt:

<pre>attr myDbLog userReadings DbFileSize:reduceLogState.* { (split(' ',`du -m fhem.db`))[0] }</pre>

Mittels dieses Attributs wird die Grösse der .db-Datei immer nach dem Ausführen des ReduceLog in das Reading "DbFileSize" in ganzzahligen MByte abgelegt.

Basierend auf diesem Reading können dann weitere Aktionen, beispielsweise ein Plot, erstellt werden.

== Links ==
* [[Heizleistung_und_Gasverbrauch|Beispiel das DbLog-Daten für SVG-Plots verwendet]]
* [[SVG-Plots von FileLog auf DbLog umstellen]]

HM-LC-RGBW-WM Funk-RGBW-Controller

2017-01-02T17:29:13Z

Joshi04: /* Befehle im Dim Kanal */ <duration> <ramp> für pct

{{Todo|Dieses Device ist seit Anfang Oktober 2015 als Bausatz auf dem Markt - dieser Artikel ist noch im Aufbau - bitte Verständnis für Unvollständigkeiten und fehlende Bereiche}}

{{Infobox Hardware
|Bild=HM-LC-RGBW-WM.jpg
|Bildbeschreibung=HomeMatic Funk-RGBW-Controller
|HWProtocol=HomeMatic
|HWType=Dimmer
|HWCategory=HomeMatic
|HWComm=868 MHz
|HWChannels=3
|HWVoltage=12-24 V DC
|HWPowerConsumption=15 mA max. (LED's aus)
|HWPoweredBy=externe Stromversorgung
|HWSize=89x99x26mm
|HWDeviceFHEM=[http://fhem.de/commandref.html#CUL_HM CUL_HM]
|HWManufacturer=ELV / eQ-3
}}

== Features ==
Der Funk-RGBW-Controller erlaubt das Dimmen von 12/24 Volt Gleichstrom LED-Stripes mit gemeinsamer Anode (+). Es können max. 34W pro Kanal angesteuert werden.

Im Oktober 2015 hat die Auslieferung der Geräte als (einfacher) Bausatz begonnen. Zusätzlich ist das Gerät als "fertig aufgebauter Bausatz" mit einem Aufpreis (derzeit 30 Euro) erhältlich.

'''Technische Daten:'''

Gewicht: 90 g

== Anwendungsszenarien ==

Der Controller ist für die Montage an Ebenen Flächen gedacht. Es ist eine eigene vorhandene 12/24V Stromversorgung notwendig (nicht im Lieferumfang enthalten). Der Controller besitzt Schraubklemmen zum direkten Anschluss von LED-Stripes. Es ist dabei auf die max. zulässige Leistung pro Kanal zu achten. Diese kann je nach Stripe variieren.

== Parameter ==

== Probleme ==

* Die Farbe weiß zusammen mit rot, grün oder blau zu mischen ist offenbar nicht möglich.
* Unklar ist, wie neue Programme erstellt und gespeichert werden können.
* Bei langsamen Farb- und Helligkeitsänderungen sind deutliche Farb- und Helligkeitssprünge wahrnehmbar, da die Änderung nicht kontinuierlich abläuft, sondern sprunghaft.

== Betrieb mit FHEM ==

Der Controller hat drei Kanäle, die jeweils verschiedene Befehle ermöglichen:

=== Befehle im Dim Kanal ===

<code>set <device> on</code>

Schaltet die LEDs mit der zuletzt eingestellten Farbe dauerhaft ein.

<code>set <device> on-for-timer <ontime></code>

Schaltet die LEDs mit der zuletzt eingestellten Farbe ein und nach <ontime> Sekunden wieder aus.

<code>set <device> on-till <nowiki><time></nowiki></code>

Schaltet die LEDs mit der zuletzt eingestellten Farbe ein und um <nowiki><time></nowiki> Uhr wieder aus. <nowiki><time></nowiki> hat das Format hh:mm:ss

<code>set <device> off</code>

Schaltet die LEDs dauerhaft aus.

<code>set <device> press</code>

Wenn die LEDs eingeschaltet sind, werden sie sanft ausgeschaltet. Sind sie ausgeschaltet, werden sie mit der zuletzt eingestellten Farbe sanft eingeschaltet.

<code>set <device> toggle</code>

Wenn die LEDs eingeschaltet sind, werden sie sofort ausgeschaltet. Sind sie ausgeschaltet, werden sie mit der zuletzt eingestellten Farbe sofort eingeschaltet.

<code>set <device> pct <bright> <duration> <ramp></code>

Die LEDs werden auf den angegebenen Helligkeitswert <bright> für die Dauer <duration> mit den entsprechenden Rampen-Zeiten <ramp> gesetzt. <bright> ist ein Wert von 0 bis 100 (Prozent).

Dauer und Rampen-Zeit sind optional und werden jeweils in Sekunden angegeben. Wenn sie nicht angegeben werden, wird für die Dauer 0 = unendlich und für die Rampen-Zeit 2 angenommen.

<code>set <device> up</code>

Die LEDs werden um 10% hoch gedimmt.

<code>set <device> down</code>

Die LEDs werden um 10% herunter gedimmt.

=== Befehle im Color Kanal ===

<code>set <device> brightCol <bright> <colVal> <duration> <ramp></code>

Es gibt eine Ramp-Phase, in der die LEDs von 0% hochgedimmt werden und anschließend eine Duration-Phase, in der sie mit konstanter Helligkeit angeschaltet bleiben. Nach der Duration-Phase dimmen die LEDs innnerhalb von 1 Sekunde auf 0% herunter. Die LED-Farbe ist in allen Phasen gleich.

'''<bright>''' regelt die Helligkeit in der Duration-Phase und geht von 0 (=0%) bis 100 (=100%)

'''<colVal>''' regelt die Farbe in der Ramp- und Duration-Phase und geht von 0 bis 100:<br>
0 = reines Rot, 33 = Grün, 66.5 = Blau, 99.5 = Rot mit minimalem Blauanteil, 100 = Weiß<br>
Werte dazwischen ergeben Mischfarben, z.B. 8 = Gelb, 75 = Lila. Weiß zusammen mit R, G oder B zu mischen ist offenbar nicht möglich.

'''<duration>''' definiert, wie viele Sekunden die LEDs nach der Ramp-Phase eingeschaltet bleiben. Während der Duration-Phase blinkt die Helligkeittaste regelmäßig 1x lang. Ein Wert von 0 lässt die LEDs dauerhaft eingeschaltet.

'''<ramp>''' definiert, in wie vielen Sekunden die LEDs von 0% auf <bright> % hochgedimmt werden. Während der Ramp-Phase blinkt die Helligkeittaste regelmäßig 2x kurz und 1x lang. Bei <ramp> = 0 gehen die LEDs sofort an.

<code>set <device> color <colVal></code>

Stellt die Farbe '''<colVal>''' (siehe oben) in der aktuellen Helligkeit ein.

=== Befehle im Auto Kanal ===

<code>set <device> brightAuto <bright> <colProg> <min> <max> <duration> <ramp></code>

Analog zum brightCol-Befehl im Color-Kanal gibt es eine Ramp-Phase, in der die LEDs von 0% hochgedimmt werden und anschließend eine Duration-Phase, in der sie mit konstanter Grund-Helligkeit angeschaltet bleiben. Nach der Duration-Phase dimmen die LEDs innnerhalb von 1 Sekunde auf 0% herunter. In beiden Phasen wird ein vordefiniertes Programm abgespielt und während dessen blinkt die Automatiktaste regelmäßig 1x lang.

'''<bright>''' steuert die Grund-Helligkeit analog zum brightCol-Befehl im Color-Kanal. Je nach Programm schwankt die Helligkeit während der Programmausführung.

'''<colProg>''' definiert welches Programm abgespielt wird. Im Auslieferungszustand sind folgende Programm-Nummern vorhanden:

1: Farbverlauf langsam (Geschwindigkeit Farbwechsel: 2 * <colChangeSpeed> Sekunden pro Durchgang, default: 20 Sekunden).
Der Farbverlauf geht von colVal <min> bis colVal <max>. colVal ist analog zum brightCol-Befehl im Color-Kanal. Nach der <max> Farbe geht es sofort bei der <min> Farbe weiter. Das kann zu Farbsprüngen führen. Die Geschwindigkeit des Farbwechsels kann mit dem Register colChangeSpeed geändert werden (default: colChangeSpeed = 10 Sekunden pro Durchgang). In Programm 1 dauert ein Durchgang von Farbe 0 (<min> = 0) bis Farbe 200 (<max> = 200) genau 2 * <colChangeSpeed> Sekunden (default also 20 Sekunden). Wenn weniger Farben durchlaufen werden, ist der Durchlauf entsprechend schneller.<br>
Beinhaltet der Farbbereich den Wert 200, so wird auch weiß angesteuert. Beim Einschalten der Automatikmodi über eine gepeerte Fernbedienung (oder bei der Bedienung über virtuelle Buttons) ist dies nicht der Fall, Weiß wird dann ausgespart.

2: Farbverlauf normal (Geschwindigkeit Farbwechsel: <colChangeSpeed> Sekunden pro Durchgang). Wie Programm 1, jedoch mit normaler Geschwindigkeit (default: 10 Sekunden pro Durchgang).

3: Farbverlauf schnell (Geschwindigkeit Farbwechsel: 0.5 * <colChangeSpeed> Sekunden pro Durchgang). Wie Programm 1, jedoch mit doppelter Geschwindigkeit (default: 5 Sekunden pro Durchgang).

4: Kaminfeuer (rotes Licht, das ein Feuer simuliert). <min> und <max> haben keine Bedeutung.

5: Wasserfall (blaues Licht, das die Helligkeit verändert). <min> und <max> haben keine Bedeutung.

6: TV-Simulation (Farb- und Helligkeitsschwankungen simulieren ein eingeschaltetes TV-Gerät, dient zur Abwehr von Einbrechern). <min> und <max> haben keine Bedeutung.

'''<min>''' siehe Programme 1 bis 3

'''<max>''' siehe Programme 1 bis 3

'''<duration>''' definiert, wie viele Sekunden die LEDs nach der Ramp-Phase eingeschaltet bleiben. Während der Duration-Phase blinkt die Helligkeittaste regelmäßig 1x lang. <br>
Eine Ansteuerung mit <duration> 0 als Dauerbetrieb ist im Automatikmodus offenbar nicht möglich. (?)

'''<ramp>''' definiert, in wie vielen Sekunden die LEDs von 0% auf <bright> % hochgedimmt werden. Während der Ramp-Phase blinkt die Helligkeittaste regelmäßig 2x kurz und 1x lang. Bei <ramp> = 0 gehen die LEDs sofort an.

<code>set <device> colProgram <colProg></code>

Es wird das Programm mit der Nummer '''<colProg>''' (siehe oben) in der aktuell gesetzten Helligkeit abgespielt.

=== Peering ===
Die folgenden Befehle peeren alle Tasten eines HomeMatic 6-fach Tasters (HM-PB-6-WM55) mit den 3 Kanälen des RGBW-Controllers mit dem Namen '''rgbw'''. Die Bedienung ist dann wie auf S. 12+13 der Bedienungsanleitung beschrieben.

<code>set taster1_Btn_01 peerChan 0 rgbw_Dim dual set</code><br>
<code>set taster1_Btn_03 peerChan 0 rgbw_Color dual set</code><br>
<code>set taster1_Btn_05 peerChan 0 rgbw_Auto dual set</code>

Taste 1: Kurzes Drücken schaltet das Licht aus, langes Drücken dimmt herunter<br>
Taste 2: Kurzes Drücken schaltet das Licht ein, langes Drücken dimmt herauf<br>
Taste 3: Kurzes Drücken springt um einen Schritt im Farbkreis nach unten, langes Drücken fährt im Farbkreis nach unten<br>
Taste 4: Kurzes Drücken springt um einen Schritt im Farbkreis nach oben, langes Drücken fährt im Farbkreis nach oben<br>
Taste 5: Kurzes Drücken schaltet den Automatikmodus aus, langes schaltet den nächstniedrigeren ein<br>
Taste 6: Kurzes Drücken schaltet den Automatikmodus 1 ein, langes den nächsthöheren<br>

Hinweise:<br>
Die Automatikmodi springen beim Durchschalten vom höchsten (TV) zum niedrigsten (Farbwechsel langsam) und umgekehrt.<br>
Das Durchfahren des Farbkreises hält immer bei Weiß an.

Die folgenden Befehle peeren die ersten 3 Tasten (=Kanäle) eines HomeMatic 6-fach Tasters (HM-PB-6-WM55) mit den 3 Kanälen des RGBW-Controllers.<br>
Die Bedienung ist dadurch etwas anders.<br>
<code>set taster1_Btn_01 peerChan 0 rgbw_Dim single set</code><br>
<code>set taster1_Btn_02 peerChan 0 rgbw_Color single set</code><br>
<code>set taster1_Btn_03 peerChan 0 rgbw_Auto single set</code><br>
Taste 1: Kurzes Drücken schaltet das Licht ein und aus, langes Drücken dimmt hoch bzw. herunter<br>
Taste 2: Kurzes Drücken springt um einen Schritt im Farbkreis nach oben bzw unten, langes Drücken fährt im Farbkreis nach oben bzw unten<br>
Taste 3: Kurzes Drücken schaltet den nächsthöheren Automatikmodus ein, langes den niedrigeren. <br>
Um die Automatik auszuschalten und den aktuellen Farbton einzufrieren, kurz auf Taste 2 (Farbe) drücken.
Auch hier springen die Automatikmodi weiter. Beim Durchfahren des Farbkreises nach unten oben wird aber (warum auch immer) über weiß hinweg nach rot gesprungen.

Ein HomeMatic 2-Kanal Funk-Sender (HM-RC-2-PBU-FM) kann wie folgt mit dem Dim-Kanal gepeert werden. Mit kurzem Druck nach oben/unten werden die LEDs ein-/ausgeschaltet und mit langem Druck hoch- und runtergedimmt.

<code>set taster2_Btn_01 peerChan 0 rgbw_Dim dual set</code><br>

=== Readings im Dim Kanal ===

Die Readings level, pct und state liefern den aktuellen Dim-Level (0 = aus, 100 = maximale Helligkeit) zurück.

=== Readings im Color Kanal ===

Die Readings color, level, pct und state liefern den aktuellen Farbwert zurück (0 = rot, 100 = weiß).

=== Readings im Auto Kanal ===

Die Readings colProgram, level, pct und state liefern das zuletzt gewählte Programm (0 = aus, 1 = Farbautomatik langsam, ..., 6 = TV-Simulation) zurück.

=== Colorpicker in FHEM erzeugen ===

1. Ein Dummy mit dem Namen RGB_Picker erzeugen, mit dem die Farbe ausgewählt wird. Außerdem wird ein Reading mit dem Namen rgb erzeugt, welches den Hex-Code der gewählten Farbe enthält:

<code>
define RGB_Picker dummy

attr RGB_Picker devStateIcon {my $icon=Color_devStateIcon(ReadingsVal($name,"rgb","000000"));;$icon=~s/on/light_light_dim_100/;;$icon}

attr RGB_Picker readingList hue

attr RGB_Picker setList hue:colorpicker,HUE,0,0.5,100

attr RGB_Picker stateFormat hue

attr RGB_Picker userReadings rgb {my $hue=ReadingsVal($name,"hue","0");;($hue eq "100")?"FFFFFF":Color::hsv2hex(($hue/100),1,1)}

attr RGB_Picker webCmd hue

</code>

2. Ein Notify definieren, welches bei jeder Änderung des Dummys (Schritt 1) den Color Befehl an den RGBW-Controller sendet. Statt rgbw_Color den Namen des Color Kanals des RGBW-Controllers eintragen.

<code>
define RGB_Picker_notify notify RGB_Picker:hue.* { fhem "set rgbw_Color color " . ReadingsVal($NAME,'hue',100) }
</code>

3. Jetzt noch die FHEM-Weboberfläche für die Dim und Auto Kanäle definieren (dabei rgbw_Dim und rgbw_Auto mit den Device Namen der entsprechenden Kanäle ersetzen):

<code>
attr rgbw_Dim webCmd pct:on:off

attr rgbw_Auto webCmd colProgram
</code>

=== Events Auszug ===

=== Konfiguration ===

== Logging/Graph. Darstellung ==

== Links ==
* Bedienungsanleitung: [http://files.elv.de/Assets/Produkte/14/1419/141952/Downloads/141952_rgbw_controller_um.pdf]
* Produktseite ELV: [http://www.elv.de/homematic-funk-rgbw-controller-bausatz.html]
* Diskussion im FHEM Forum: [http://forum.fhem.de/index.php/topic,39719.0.html]

[[Kategorie:HomeMatic Components]]
[[Kategorie:Dimmer]]

SmartVISU/ical

2016-08-11T17:55:50Z

Joshi04: Verlinkung für Schreibweise "smartVISU" korrigiert

Um einen Kalender in [[SmartVISU]] mit dem Widget widget_ical einzubinden, ist folgendes zu tun:

* Die Datei iCalcreator.class.php aus dem Paket http://kigkonsult.se/downloads/index.php#iCalcreator unter einem beliebigen Pfad ablegen, der aber in der ical.php eingetragen werden muss.
* Ablegen der Datei ical.php in das Verzeichnis /smartVISU/lib/calendar/service
* Ablegen der Datei widget_ical.html in das Homeverzeichnis der eigenen Seite z.b. /smartVISU/pages/fhem
* Definition der Kalender findet in den Settings statt. Die Kalender werden wie folgt definiert:
: - wie bisher nur die Url
: <code><nowiki>http://xxx:xxx@xxx.xxx.xxx.xxx/davical/caldav.php/norbert/calendar</nowiki></code>
: - die Url mit Parameter Farbe und Icon
: <code><nowiki>http://xxx:xxx@xxx.xxx.xxx.xxx/davical/caldav.php/norbert/calendar(Default Farbe,Default Icon)</nowiki></code>
: - die Url mit Parameter Farbe
: <code><nowiki>http://xxx:xxx@xxx.xxx.xxx.xxx/davical/caldav.php/norbert/calendar(Default Farbe)</nowiki></code>
: - die Url mit Parameter Icon
: <code><nowiki>http://xxx:xxx@xxx.xxx.xxx.xxx/davical/caldav.php/norbert/calendar(,Default Icon)</nowiki></code>
: - zwei Kalenderurls mit unterschiedlichen Parametern
: <code><nowiki>http://xxx:xxx@xxx.xxx.xxx.xxx/davical/caldav.php/norbert/calendar(,message_garbage);http://xxx:xxx@xxx.xxx.xxx.xxx/davical/caldav.php/norbert/Geburtstage(#ff69b4,scene_party)</nowiki></code>
: - eine lokale Url
: <code><nowiki>file:/tmp/calendar.ics</nowiki></code>
: - zwei Kalenderurls eine lokale und eine auf einem Caldav/Webserver
: <code><nowiki>file:/tmp/calendar.ics(,message_garbage);http://xxx:xxx@xxx.xxx.xxx.xxx/davical/caldav.php/norbert/Geburtstage(#ff69b4,scene_party)</nowiki></code>
: Die Icons sind die Namen der png-Dateien ohne .png. Wenn keine Parameter, für Farbe und Icon mitgegeben werden und auch keine in den Terminen hinterlegt sind, wird ein Standardicon und eine Standardfarbe gesetzt. Das setzen dieser Parameter pro Termin erfolgt im Beschreibungsfeld des jeweiligen Termin.
:Bei allen abgelegten Dateien muss auf die Rechte geachtet werden. Es sollten die gleichen User/Group-Rechte verwendet werden, wie auch bei den Dateien im pages Ordner.
* Einbinden es Kalenders auf einer SV-Seite:
: <code>{% import "widget_ical.html" as calendar %}</code>
: <code><nowiki>{{ calendar.list('calendarlist', 'Termine', 6, 21) }}</nowiki></code>
: Die erste Zahl (6) ist die Anzahl der Termine die aufgelistet werden. Die zweite Zahl (21) ist die Anzahl der Tage, die im Kalender in die Zukunft geprüft wird, ob sich ein Termin wiederholt.

Quelle und Download benötigter Dateien: {{Link2Forum|Topic=35831}}

[[Kategorie: fronthem/smartVISU]]

Systemübersicht

2016-08-11T17:54:46Z

Joshi04: Verlinkung für Schreibweise "smartVISU" korrigiert

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

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

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

Als Server '''Hardware''' sind (z. B.) möglich:
* Windows Rechner
* Linux Rechner
* OS X Rechner
* Router (z. B. [[AVM Fritz!Box|FritzBox]])
* Einplatinencomputer, wie [[:Kategorie:Raspberry Pi|Raspberry Pi]], [[BeagleBone Black]]
* DockStar, PogoPlug, etc.
* diverse NAS Systeme wie Buffalo Linkstation, Synology Diskstation
(Diese Aufstellung ist nur eine unvollständige Auswahl; Details zu unterstützten Server Systemen finden sich in der Kategorie [[:Kategorie:Server Hardware|Server Hardware]]).

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

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

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

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

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

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

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

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

Zusätzlich existiert eine Vielzahl von [[:Kategorie:Modul (Inoffiziell)|inoffiziellen Modulen]], die manuell in Fhem installiert werden müssen. Auch die Aktualisierung erfolgt nicht über den Update-Befehl, sondern muss durch den Nutzer selbst erfolgen. Inoffizielle Module sind an den verschiedensten Stellen zu finden:
* [[:Kategorie:Modul (Contrib)|Contrib]]-Verzeichnis im offiziellen Fhem-Sourcecode-SVN [http://sourceforge.net/p/fhem/code/HEAD/tree/trunk/fhem/contrib/]
* Beiträge im Fhem-Forum
* private Homepages

== Interfaces ==
Die Verbindung zu den angeschlossenen '''Geräten''' der Hausautomation wird im Allgemeinen - geräteabhängig - über [[Interface|Interfaces]] (manchmal auch als '''Gateway''' bezeichnet) hergestellt. Das kann z. B. im Falle von [[HomeMatic]] ein [[HMLAN Konfigurator]] sein, ein mittels LAN mit dem Fhem Server verbundenes Gerät, das die Fhem Steuerbefehle in das HomeMatic Funkprotokoll umsetzt - und auch die Funktelegramme der HomeMatic Komponenten an Fhem zurückgibt. Entsprechende Interfaces gibt es auch für andere Funkprotokolle und für die drahtgebundenen Systeme.

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

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


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

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

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

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

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

[[Kategorie:FHEM]]

SmartVISU

2016-08-11T17:50:36Z

Joshi04: /* zusätzliche Widgets */ Repository for Plot-Widget hinzugefügt

{{SEITENTITEL:smartVISU}}

Dieser Artikel beschreibt das Web-Frontend smartVISU, dessen Funktionen und Konfiguration. [http://www.smartvisu.de smartVISU] ist ein Framework zur Visualisierung von Hausautomationssystemen, die eigentlich KNX-Installationen bedient. Für die Anbindung an FHEM ist die Installation und Konfiguration von [[Fronthem]] notwendig, dass das Interface für die Anbindung zur Verfügung stellt.

In einem separaten Artikel wird die [[smartVISU Installation|Basis-Installation von smartVISU]] beschrieben, die eine Voraussetzung für die Verwendung von smartVISU ist.

Ein paar Sceenshots, die einen Eindruck des Frontends vermitteln wurden im {{Link2Forum|Topic= 27291|Message=227568|LinkText=Forum}} veröffentlicht.

Alle Artikel zur Thematik fronthem/smartVISU sind [[:Kategorie:fronthem/smartVISU|hier]] kategorisiert.

----

__TOC__

Hat man die Installation durchgeführt, befindet sich im root-Verzeichnis der smartVISU Installation für die schnelle Einrichtung die Datei readme.md, in der ein 10-Schritte Guide die erste Konfiguration beschreibt.

Wurden ebenfalls die Erweiterungen für FHEM eingespielt, befindet sich in diesem Verzeichnis ebenfalls die Datei readme.txt, die etwas FHEM-spezifischer ebenfalls den 10-Schritte Guide enthält.

== Bausteine ==

[[Datei:Systemuebersicht_fronthem_smartVISU.jpg|550px|thumb|right|Systemübersicht, fronthem/smartVISU]]
Zum besseren Verständnis der Begrifflichkeiten und Zusammenhänge ist hier eine Systemübersicht dargestellt.

=== Statische Seiten ===

Für den Betrieb von smartVISU ist ein Web-Server mit PHP notwendig. Dieser stellt die statischen Inhalte des Frontends zur Verfügung. Die Oberfläche muss den eigenen Bedürfnissen per programmieren der Web-Seite anpassen werden. HTML-, PHP- oder Javascript-Kenntnisse sind hilfreich, aber nicht zwingend erforderlich.
Genügend Beispiele sind vorhanden und leicht anpassbar, so dass durch einfaches Zusammenstellen schnell eine individuelle Seite erstellt werden kann.

=== Treiber ===

==== Funktion ====

Was fronthem für FHEM ist, ist der Treiber für smartVISU. Er ist ein Stück Software (js), das in die ausgeliefertern Webseiten per Link eingebettet ist, auf dem Endgerät ausgeführt wird und die Kommunikation zwischen Endgerät und Websocketserver (fronthem) übernimmt und anpasst {{Link2Forum|Topic=53881|Message=466167|LinkText=(Forum)}}.

Ein explizit auf FHEM angepasster Treiber stellt unter anderem die Mandantenfähigkeit (end-device werden seperat betrachtet und beschickt) sicher.

Der Treiber besteht aus den beiden Files [https://github.com/herrmannj/smartvisu-cleaninstall/blob/master/driver/io_fhem.js io_fhem.js] und [https://github.com/herrmannj/smartvisu-cleaninstall/blob/master/driver/io_fhem.min.js io_fhem.min.js], die im smartVISU/driver/ Verzeichnis der smartVISU Installation abgelegt sind.

==== Verwendung ====

Ruft man die smartVISU-Seite auf einem Endgerät auf, wird auf der Config-Seite (Zahnrädersymbol in der oberen Menüzeile)
* als Driver "Fhem" ausgewählt,
* die Adresse des Websocketservers, auf dem fronthem ansprechbar ist unter "Address URL/IP" eingetragen und
* für den Port "2121" gesetzt.

=== Widgets ===

smartVISU bietet mit seinem Konzept der Widgets eine flexible Möglichkeit der individuellen Erweiterung an. Für viele Anwendungen gibt es bereits Widgets (z.B. Heizung, RGB, Clock, Wetter, etc.), auf die zurückgegriffen werden kann.

Mit einem Widget wird für den jeweiligen Anwendungsfall bestimmt, wie auf der Darstellungsseite das Design aussehen soll und auf der Verarbeitungsseite welche Parameter übergeben werden. So könnte man die Widgets auch als Vorlage verstehen, um diese Designelemente bei Bedarf entsprechend einzubinden.
{{Randnotiz|RNTyp=y|RNText=Schaut man sich die Dokumentation oder die Beispielhäuser an, sollte vorher den Treiber auf offline geschaltet werden, weil sich sonst fronthem die Konfiguration der Demohäuser importiert und merkt {{Link2Forum|Topic=30909|Message=235155|LinkText=(Forum)}}.}}
Es gibt diverse Standard-Widget, die bereits Teil der smartVISU-Installation sind. Darüber hinaus können eigene oder individualisierte Widgets hinzugefügt werden.
Die Dokumentation der verfügbaren Standard-Widgets in der Basisinstallation ist im Unterordner /pages/Docu gespeichert. Die Dokumentation kann angeschaut werden, indem man auf der Config-Seite die Page "Docu" auswählt bzw. direkt in die Widgets schaut, die im Stammverzeichnis der smartVISU im Unterordner /widgets abgelegt sind.

== Standard Seitenladeprozess ==

(Übersetzt aus readme.txt)

Ruft man die smartVISU-Seite über den Aufruf <code>http://<Server-IP>/<Installationsverzeichnis></code> (z.B. http://192.168.1.1/smartvisu) auf, läuft über die <code>index.php</code> ein vordefinierter Ladezyklus ab, der
* über die includes.php, die Einstellungen der config.ini einliest,
* die twig Umgebung startet
* die Pfade setzt (für pages, icons, Standartwidgets, etc.)
* die index.html der in der config.ini configurierten Seite ./pages/<eigener Ordner>

Der Ladeprozess ist in der Datei readme.txt noch etwas detaillierter beschrieben. Der Ladeprozess regelt ebenfalls das Verhalten, wenn noch keine Konfiguration definiert wurde oder bestimmte Dateien an den Orten nicht vorhanden sind.

Gibt es vor allen Dingen bei der Ersteinrichtung Probleme, sollte man sich den Ladeprozess und das Vorhandensein der Dateien und die richtige Konfiguration näher anschauen.

== Ersteinrichtung ==

Die folgende Beschreibung setzt voraus, dass die notwendigen Schritte für die grundsätzliche Installation von smartVISU und fronthem bereits erfolgreich durchgeführt wurden.

=== ein "eigenes-Haus" anlegen ===

Es gilt ein eigenes "Haus" anzulegen, dass man individuell konfiguriert.

* Für eine eigene neue Seite legt man unter ./pages des smartVISU-Root-Verzeichnisses ein neues Verzeichnis <code>eigenes-Haus</code> an.
* Die Dateien auf dem Ordner ./pages/_template kopiert man in dieses Verzeichnis.
* Dort editiert man die Dateien und fügt z.B. Dinge ein, die man aus der Doku z.B. auf von www.smartVISU.de heraus kopiert hat. Auch die Beispielhäuser sind sehr hilfreich zum lernen. Einen speziellen Editor oder eine grafische Oberfläche für die Programmierung ist nicht erforderlich. Als erstes passt man z.B. die Datei <code>rooms_menu.html</code> an die eigenen Bedürfnisse an.
* Die Räume richtet man ein, indem man diese durch Kopien des Beispielraumes (<code>room_sleeping.html</code>) und passende icons und Überschriften erstellt. ([http://www.smartvisu.de/docu/2.7/index.php?page=design/design_icons SmartVisu Icons])
* SmartVISU nutzt [http://twig.sensiolabs.org/ Twig] als Template engine und die Seiten bestehen aus Blöcken und Widgets, die immer in doppelten geschweiften Klammern stehen <nowiki>{{ ... }}</nowiki>
* Widget Syntax auf [http://www.smartvisu.de/docu/2.7/index.php SmartVISU Doku] nachschlagen und kopieren.
* Innerhalb eines Raums zwischen {% block content %} und {% endblock %} als Beispiel folgenden Abschnitt einfügen:

<pre><nowiki>
<h1><img class="icon" src='{{ icon0 }}scene_livingroom.png'/>Wohnzimmer</h1>
<div class="preblock">
</div>
<div class="block">
<div class="set-2" data-role="collapsible-set" data-theme="c" data-content-theme="a" data-mini="true">
<div data-role="collapsible" data-collapsed="false" >
<h3>Licht</h3>
<table width="90%">
<tr><td align="left" width="100px"> {{ basic.switch('Leselampe', 'Leselampe.sw', icon1~'light_floor_lamp.png', icon0~'light_floor_lamp.png') }}</td>
<td>Leselampe</td>
</tr>
</table>
</div>
</div>
</div>
</nowiki></pre>

* Datei speichern und checken, dass die Rechte mindestens auf "755" stehen, ansonsten mit "sudo chmod 755" korrigieren.

Beim erstellen eigener Seiten oder Widgets sollte man darauf achten, nicht in die Dateien der smartVISU-Installation direkt einzugreifen, sondern vornehmlich in den eigenen Pages zu arbeiten. So steht auch einem unbeeinträchtigten späteren Update nichts im Wege.

Beispielsweise anstelle <code>root.html</code> oder <code>base.html</code> im Ordner ./pages/base direkt zu verändern, sollte man jeweils angepasste Kopien in das eigene Pages-Verzeichnis legen - diese haben dann Vorrang vor den System Dateien {{Link2Forum|Topic=30909|Message=268592|LinkText=(Forum)}}.

Die Template-Engine schaut zuerst im Ordner ./pages/<eigeneSeite> nach und anschließend im Ordner ./pages/base. Dadurch sind Anpassungen an (root, base) etc. für spezielle Geräte möglich {{Link2Forum|Topic=30909|Message=241148|LinkText=(Forum)}}.

Für die eigenen Seiteninhalte sollten entsprechend die Dateinamen "base.html, basic.html, device.html" nicht verwendet werden, da dieses System-Seiten sind.

;fronthem
Obwohl der folgende Teil bereits zur Einrichtung von fronthem gehört, sei es der Vollständigkeit halber des Beispiels hier trotzdem erwähnt:
* In FHEM eine fronthemDevice Detailansicht öffnen
* Nun sollten die GADs aufgelistet werden. Aus der Liste ein GAD auswählen (hier: "Leselampe.sw" wie im obigen Code-Beispiel definiert.) und die Parameter vergeben:
<pre>
device: <fhem-Name-des-fhem-devices> (in diesem Fall die Leselampe.sw)
reading: state
converter: OnOff
cmd set: state
write: ja (haken setzen)
read: ja (haken setzen)
</pre>
: "state" immer klein schreiben und speichern nicht vergessen!
* Die Settings für das Device gelten für alle Endgeräte, aber die read/write Rechte müssen für jedes Endgerät separat gesetzt werden.

=== Einrichtung Endgerät ===
Auf dem Endgerät greift man auf die smartVISU-Seiten zu und stellt auf der Config-Seite den Treiber, IP der Servers und den Port ein.

Unter smartVISU in die Konfigurationsoberfläche wechseln <code>http://<IP-Adresse>/smartvisu/index.php?page=config</code> bzw. Zahnrad = Config-Menü:
* Im Feld "Interfaces" für pages das eigenes Haus auswählen (=Ordnername)
* Der Pagecache sollte zumindest während der Einrichtung ausgeschaltet sein.
* Im Feld I/O Connection den Treiber Fhem wählen
* Die IP-Adresse des Servers mit dem Websocket-Server eintragen
* Port 2121 einstellen
Nach allen Eintragungen die Konfiguration am unteren Ende der Seite speichern.

Damit die GADs nun im GAD-Editor auf der Detailseite von einem [[fronthem#fronthemEditor|fronthemDevice]] auftauchen, ist es jetzt wichtig, die neue Seite in smartVISU einmal aufzurufen, damit im Hintergrund die GADs übertragen werden.

Vorausgesetzt, man hat vorher alle notwendigen Schritte für die Installation und Konfiguration von fronthem ausgeführt, kann man nun smartVISU in Verbindung mit FHEM benutzen.

Im Noramlbetrieb stellt man den Pagecache auf "on"- dann werden die templates compiliert gespeichert, was die Geschwindigkeit erhöht {{Link2Forum|Topic=35960|Message=283665|LinkText=(Forum)}}.

=== Die wichtigste Dateien der eigenen Seite ===
Im Folgenden sind die wichtigsten Dateien und Grundlagen beschrieben, aus der eine Seite zusammensetzt ist, die aus den Template-Dateinen erstellt wurde. Jede Seite besteht aus der Menüzeile, einer Seitenleiste auf der linken Seite und den Hauptbereich auf der rechten Seite.

Entsprechend Browser (z.B. Desktop oder Smartphone) werden die Seiten unterschiedlich dargestellt.

;index.html
Der Inhalt dieser Seite ist der erste, der aufgerufen wird. Hauptsächlich besteht er aus 2 Blöcken, gekennzeichnet durch
{% block sidebar %}
...
{% endblock %}

und
{% block content %}
...
{% endblock %}

Im Block <code>sidebar</code> steht der Inhalt, der auf der linken Seite der Startseite dargestellt wird. Im Beispiel wird wird die Uhr, das Datum, das aktuelle Wetter und die Wettervorhersage eingebunden.

Im Block <code>content</code> wird die Datei <code>rooms_menu.html</code> eingebunden. Der Inhalt dieses Blocks wird im rechten Bereich dargestellt.

;rooms_menu.html
Diese Datei enthält die Darstellung des Links für die einzelnen Räume wie z.B. <code>room_sleeping.html</code> für das Schlafzimmer. Ruft man von der Hauptseite einen Raum auf, wird auf einem Desktop-Browser die Seite <code>rooms_menu.html</code>im linken Bereich im Block Sidebar dargestellt, im rechten Bereich wird der Inhalt des Raums dargestellt.

;room_sleeping.html
Pro Raum gibt es eine Datei, die die Darstellung eines Raumes festlegen. Dort wie oben, wird der Bereich, der Darstellung über die Blockdefinition festgelegt.

;rooms.html
Im Rahmen des Ladezyklus, wird diese Datei ebenfalls geladen, läd jedoch ihrerseits gleich die nächste.

;visu.ccs
Möchte man das Design anpassen, verwendet man eine Stylesheet-Datei "visu.css" in seinem Projektordner. Diese Datei ist standardmäßig nicht Teil der Vorlage und kann bei Bedarf angelegt werden.

;visu.js
In dieser Datei kann Javascrict-Code abgelegt werden, der auf einer Seite aufgerufen wird. Diese Datei ist standardmäßig nicht Teil der Vorlage und kann bei Bedarf angelegt werden.

;menu.html
Diese Datei ist nicht Teil der Einrichtung über die Vorlage des template-Ordners. Möchte man das Menü anpassen, das oben auf der Seite angezeigt wird, kopiert man die Datei <code>menu.html</code> aus dem Verzeichnis ./base in sein Verzeichnis ./pages/<eigeneSeite> und passt diese entsprechend an. Über die Reihenfolge, in der die Ordner nach möglichen Dateien durchsucht werden, wird im Folgenden die eigene individualisierte Datei berücksichtigt.

=== Verwendung von Widgets ===

==== Einbindung ====

Eigene oder individualisierte Widgets müssen vor dem Aufruf auf einer Seite "bekannt" gemacht werden. Dafür gibt es unterschiedliche Möglichkeiten.

;Import der html-Datei

Einfache Widgets bestehen meist nur aus einer html-Datei. Diese muss vor der ersten Verwendung des Widgets "importiert" werden.

An zentraler Stelle lässt sich dieses wie folgt durchführen. Man
* legt in seinem Ordner ./pages/eigenes-Haus einen Unterordner ./pages/eigenes-Haus/widgets an.
* kopiert die widgets-Datei in diesen Ordner.
* passt die Rechte entsprechend an.
* fügt der Datei <code>rooms.hmtl</code> in einer neuen Zeile direkt unterhalb von <code>{% extends "base.html" %}</code> folgende Zeile ein
{% import "widgets\\temp_sensor.html" as TempSensor %}

Der Dateiname <code>temp_sensor.html</code> enthält in diesem Beispiel den Code des Widgets {{Link2Forum|Topic=30909|Message=238044|LinkText=(Forum)}}, {{Link2Forum|Topic=30909|Message=238136|LinkText=(Forum)}}, {{Link2Forum|Topic=30909|Message=251586|LinkText=(Forum)}}.

;Import der Style-Definition und JS

Für komplexere Widgets muss ebenfalls die Style-Datei <code>visu.ccs</code> erweitert werden und Javascript-Code der Datei <code>visu.js</code> hinzugefügt werden. Damit der Code nicht komplett in den Dateien verwaltet werden muss, kann über die [https://github.com/ddtlabs/smartvisu-widgets/wiki/HowTo-Install-Widgets hier] beschriebene Methode der Code in Einzeldateien belassen werden. Dieses erleichtert den Überblick und die Möglichkeit separat Weiterentwicklungen der einzelnen Widgets auseinanderzuhalten und zu aktualisieren.

Über die beschriebene Erweiterung der <code>visu.ccs</code> und <code>visu.js</code> müssen die entsprechenden Teiles eines Widget nur noch einmal in diesen beiden Dateien definiert werden.

Auch hier gibt es die Möglichkeit, die Dateien in einem Unterordner ./pages/eigenes-Haus/widgets abzulegen {{Link2Forum|Topic=30909|Message=276232|LinkText=(Forum)}}.

Eine weitere Möglichkeit ist in diesem {{Link2Forum|Topic=30909|Message=278922|LinkText=Forums-Beitrag}} beschrieben, die allerdings nicht updatesicher für eine mögliche Aktualisierung von smartVISU ist.

==== Aufruf ====

Auf der Seite wird der Aufruf des Widgets eingebettet und über seinen Aufruf ebenfalls positioniert. Beispiele für das Einbetten sind im Docu-Haus enthalten.
{{ widgetname.function('<id>', '<gad>', '<weitere Parameter>') }}

Der Aufruf eines Widgets auf einer Seite besteht jeweils aus einem in doppelt geschweifte Klammern eingefassten Ausdrucks.
Der Ausdruck besteht aus der Nennung des Widgets, gefolgt von der mit einem Punkt getrennten Funktion. Wie in FHEM üblich ist auch hier die Groß/Kleinschreibung zu berücksichtigen und eine häufige Fehlerquelle.

Im Anschluss in Klammern folgen die durch Komma getrennten Parameter in Hochkommata:
* id, die ID des Widgets ist eigentlich nur innerhalb von smartVISU wichtig, kann willkürlich gewählt werden, darf sich auf einer html-Seite allerdings nicht wiederholen.
* gad, wird auch als Item bezeichnet. Dieses ist der Ausdruck, der später an fronthem übergeben wird und entsprechend im GAD-Editor auftaucht für die weitere Verarbeitung und Zuordnung.
* weitere Parameter, teilweise optional und teilweise mit Default-Werten, wenn diese nicht angegeben werden.

Ein etwas detaillierteres Beispiel findet sich innerhalb der [http://leseprobe.smartvisu.de/index.php?page=grundlagen_widget Leseprobe] der Dokumentation auf der smartVISU-Homepage.

== Codebeispiele ==



=== Layout ===

* [[smartVISU/IconHighlights in Menus|IconHighlights in Menus]]


=== Standard-Widgets ===

{{Todo|Hier sollte nicht die Dokumentation der Standardwidgets wiedergegeben werden, sondern Spezifika, die nicht in der Dokumentation auftauchen oder Anwendungsbeispiele.}}

==== Basic.switch ====

* [[smartVISU/lichtSzene|lichtSzene]]


=== zusätzliche Widgets ===

Es gibt diverse zusätzliche Widgets, für die es allerdings keine zentrale Quelle gibt. Stattdessen können diese aus den unterschiedlichen Repositories der Entwickler oder aus Beiträgen im Forum heruntergeladen werden.

Für die folgenden Widgets gibt es detailliertere Beschreibungen hier im Wiki:

* [[smartVISU/ical|ical]], Kalendereinbindung

;bekannte Repositories
https://github.com/herrmannj/smartvisu-widgets
* LED
* UZSU V2.0
** [[smartVISU/Universelle ZeitSchaltUhr (UZSU)]]
* auth_switch
* basic
* basic_extra
* chart
* device_extra
* fritzbox
** [[smartVISU/fritz!box_via_TR-064|fritz!box_via_TR-064]], Einbindung Anruferliste, Telefonbuch, etc.
* homematic

* httpcmd
* icon/battery
* icons
*img
* listbutton
* phoneservice/lib/phone/service
* selectmenu
* sonos
* squeezebox
* textinput
* timcounter

https://github.com/ddtlabs/smartvisu-widgets

Voraussetzung für die meisten hier liegenden Widgets ist V2.8 von smartVISU.
* basic-devices
* hm-rtr
* hue
* media
* motionDetection
* powerDistribution
* sonos
* ventilation

https://github.com/ToGe3688/db_plot_widget
* Ein Widget für Plots (nur in Verbindung mit [[DbLog]])

https://github.com/bgewehr/smartVISU
* basic2.html (LED)
* qlock.html
* widget_calendar.html
* widget_fritzbox.html
* widget_fritzbox_list.html
* widget_list.html
* widget_popup.html

https://github.com/mworion/uzsu_widget
* uzsu_widget V5.0

https://github.com/2ndsky/quad
* quad

im Forum
* [[smartVISU/Temperatur-/Feuchtigkeitssensor]]
* RTR für MAX! https://forum.fhem.de/index.php?topic=30909.msg241379#msg241379
* Ein weiteres Widget für ein RTR (Homematic) https://forum.fhem.de/index.php?topic=30909.msg276719#msg276719
* noch ein widget für homematic für HM-CC-RT-DN https://forum.fhem.de/index.php?topic=30909.msg248462#msg248462

== Links ==

[http://www.smartvisu.de smartVISU Hauptseite von smartVISU]

[http://twig.sensiolabs.org/documentation PHP-Twig Doku]

[https://code.google.com/archive/p/smartvisu/wikis Google-Archiv smartVISU]

[[Kategorie: fronthem/smartVISU]]

SmartVISU

2016-08-07T17:48:33Z

Joshi04: /* Codebeispiele */ Links zu Repositories hinzugefügt

{{SEITENTITEL:smartVISU}}

Dieser Artikel beschreibt das Web-Frontend smartVISU, dessen Funktionen und Konfiguration. [http://www.smartvisu.de smartVISU] ist ein Framework zur Visualisierung von Hausautomationssystemen, die eigentlich KNX-Installationen bedient. Für die Anbindung an FHEM ist die Installation und Konfiguration von [[Fronthem]] notwendig, dass das Interface für die Anbindung zur Verfügung stellt.

In einem separaten Artikel wird die [[smartVISU Installation|Basis-Installation von smartVISU]] beschrieben, die eine Voraussetzung für die Verwendung von smartVISU ist.

Ein paar Sceenshots, die einen Eindruck des Frontends vermitteln wurden im {{Link2Forum|Topic= 27291|Message=227568|LinkText=Forum}} veröffentlicht.

Alle Artikel zur Thematik fronthem/smartVISU sind [[:Kategorie:fronthem/smartVISU|hier]] kategorisiert.

----

__TOC__

Hat man die Installation durchgeführt, befindet sich im root-Verzeichnis der smartVISU Installation für die schnelle Einrichtung die Datei readme.md, in der ein 10-Schritte Guide die erste Konfiguration beschreibt.

Wurden ebenfalls die Erweiterungen für FHEM eingespielt, befindet sich in diesem Verzeichnis ebenfalls die Datei readme.txt, die etwas FHEM-spezifischer ebenfalls den 10-Schritte Guide enthält.

== Bausteine ==

[[Datei:Systemuebersicht_fronthem_smartVISU.jpg|550px|thumb|right|Systemübersicht, fronthem/smartVISU]]
Zum besseren Verständnis der Begrifflichkeiten und Zusammenhänge ist hier eine Systemübersicht dargestellt.

=== Statische Seiten ===

Für den Betrieb von smartVISU ist ein Web-Server mit PHP notwendig. Dieser stellt die statischen Inhalte des Frontends zur Verfügung. Die Oberfläche muss den eigenen Bedürfnissen per programmieren der Web-Seite anpassen werden. HTML-, PHP- oder Javascript-Kenntnisse sind hilfreich, aber nicht zwingend erforderlich.
Genügend Beispiele sind vorhanden und leicht anpassbar, so dass durch einfaches Zusammenstellen schnell eine individuelle Seite erstellt werden kann.

=== Treiber ===

==== Funktion ====

Was fronthem für FHEM ist, ist der Treiber für smartVISU. Er ist ein Stück Software (js), das in die ausgeliefertern Webseiten per Link eingebettet ist, auf dem Endgerät ausgeführt wird und die Kommunikation zwischen Endgerät und Websocketserver (fronthem) übernimmt und anpasst {{Link2Forum|Topic=53881|Message=466167|LinkText=(Forum)}}.

Ein explizit auf FHEM angepasster Treiber stellt unter anderem die Mandantenfähigkeit (end-device werden seperat betrachtet und beschickt) sicher.

Der Treiber besteht aus den beiden Files [https://github.com/herrmannj/smartvisu-cleaninstall/blob/master/driver/io_fhem.js io_fhem.js] und [https://github.com/herrmannj/smartvisu-cleaninstall/blob/master/driver/io_fhem.min.js io_fhem.min.js], die im smartVISU/driver/ Verzeichnis der smartVISU Installation abgelegt sind.

==== Verwendung ====

Ruft man die smartVISU-Seite auf einem Endgerät auf, wird auf der Config-Seite (Zahnrädersymbol in der oberen Menüzeile)
* als Driver "Fhem" ausgewählt,
* die Adresse des Websocketservers, auf dem fronthem ansprechbar ist unter "Address URL/IP" eingetragen und
* für den Port "2121" gesetzt.

=== Widgets ===

smartVISU bietet mit seinem Konzept der Widgets eine flexible Möglichkeit der individuellen Erweiterung an. Für viele Anwendungen gibt es bereits Widgets (z.B. Heizung, RGB, Clock, Wetter, etc.), auf die zurückgegriffen werden kann.

Mit einem Widget wird für den jeweiligen Anwendungsfall bestimmt, wie auf der Darstellungsseite das Design aussehen soll und auf der Verarbeitungsseite welche Parameter übergeben werden. So könnte man die Widgets auch als Vorlage verstehen, um diese Designelemente bei Bedarf entsprechend einzubinden.
{{Randnotiz|RNTyp=y|RNText=Schaut man sich die Dokumentation oder die Beispielhäuser an, sollte vorher den Treiber auf offline geschaltet werden, weil sich sonst fronthem die Konfiguration der Demohäuser importiert und merkt {{Link2Forum|Topic=30909|Message=235155|LinkText=(Forum)}}.}}
Es gibt diverse Standard-Widget, die bereits Teil der smartVISU-Installation sind. Darüber hinaus können eigene oder individualisierte Widgets hinzugefügt werden.
Die Dokumentation der verfügbaren Standard-Widgets in der Basisinstallation ist im Unterordner /pages/Docu gespeichert. Die Dokumentation kann angeschaut werden, indem man auf der Config-Seite die Page "Docu" auswählt bzw. direkt in die Widgets schaut, die im Stammverzeichnis der smartVISU im Unterordner /widgets abgelegt sind.

== Standard Seitenladeprozess ==

(Übersetzt aus readme.txt)

Ruft man die smartVISU-Seite über den Aufruf <code>http://<Server-IP>/<Installationsverzeichnis></code> (z.B. http://192.168.1.1/smartvisu) auf, läuft über die <code>index.php</code> ein vordefinierter Ladezyklus ab, der
* über die includes.php, die Einstellungen der config.ini einliest,
* die twig Umgebung startet
* die Pfade setzt (für pages, icons, Standartwidgets, etc.)
* die index.html der in der config.ini configurierten Seite ./pages/<eigener Ordner>

Der Ladeprozess ist in der Datei readme.txt noch etwas detaillierter beschrieben. Der Ladeprozess regelt ebenfalls das Verhalten, wenn noch keine Konfiguration definiert wurde oder bestimmte Dateien an den Orten nicht vorhanden sind.

Gibt es vor allen Dingen bei der Ersteinrichtung Probleme, sollte man sich den Ladeprozess und das Vorhandensein der Dateien und die richtige Konfiguration näher anschauen.

== Ersteinrichtung ==

Die folgende Beschreibung setzt voraus, dass die notwendigen Schritte für die grundsätzliche Installation von smartVISU und fronthem bereits erfolgreich durchgeführt wurden.

=== ein "eigenes-Haus" anlegen ===

Es gilt ein eigenes "Haus" anzulegen, dass man individuell konfiguriert.

* Für eine eigene neue Seite legt man unter ./pages des smartVISU-Root-Verzeichnisses ein neues Verzeichnis <code>eigenes-Haus</code> an.
* Die Dateien auf dem Ordner ./pages/_template kopiert man in dieses Verzeichnis.
* Dort editiert man die Dateien und fügt z.B. Dinge ein, die man aus der Doku z.B. auf von www.smartVISU.de heraus kopiert hat. Auch die Beispielhäuser sind sehr hilfreich zum lernen. Einen speziellen Editor oder eine grafische Oberfläche für die Programmierung ist nicht erforderlich. Als erstes passt man z.B. die Datei <code>rooms_menu.html</code> an die eigenen Bedürfnisse an.
* Die Räume richtet man ein, indem man diese durch Kopien des Beispielraumes (<code>room_sleeping.html</code>) und passende icons und Überschriften erstellt. ([http://www.smartvisu.de/docu/2.7/index.php?page=design/design_icons SmartVisu Icons])
* SmartVISU nutzt [http://twig.sensiolabs.org/ Twig] als Template engine und die Seiten bestehen aus Blöcken und Widgets, die immer in doppelten geschweiften Klammern stehen <nowiki>{{ ... }}</nowiki>
* Widget Syntax auf [http://www.smartvisu.de/docu/2.7/index.php SmartVISU Doku] nachschlagen und kopieren.
* Innerhalb eines Raums zwischen {% block content %} und {% endblock %} als Beispiel folgenden Abschnitt einfügen:

<pre><nowiki>
<h1><img class="icon" src='{{ icon0 }}scene_livingroom.png'/>Wohnzimmer</h1>
<div class="preblock">
</div>
<div class="block">
<div class="set-2" data-role="collapsible-set" data-theme="c" data-content-theme="a" data-mini="true">
<div data-role="collapsible" data-collapsed="false" >
<h3>Licht</h3>
<table width="90%">
<tr><td align="left" width="100px"> {{ basic.switch('Leselampe', 'Leselampe.sw', icon1~'light_floor_lamp.png', icon0~'light_floor_lamp.png') }}</td>
<td>Leselampe</td>
</tr>
</table>
</div>
</div>
</div>
</nowiki></pre>

* Datei speichern und checken, dass die Rechte mindestens auf "755" stehen, ansonsten mit "sudo chmod 755" korrigieren.

Beim erstellen eigener Seiten oder Widgets sollte man darauf achten, nicht in die Dateien der smartVISU-Installation direkt einzugreifen, sondern vornehmlich in den eigenen Pages zu arbeiten. So steht auch einem unbeeinträchtigten späteren Update nichts im Wege.

Beispielsweise anstelle <code>root.html</code> oder <code>base.html</code> im Ordner ./pages/base direkt zu verändern, sollte man jeweils angepasste Kopien in das eigene Pages-Verzeichnis legen - diese haben dann Vorrang vor den System Dateien {{Link2Forum|Topic=30909|Message=268592|LinkText=(Forum)}}.

Die Template-Engine schaut zuerst im Ordner ./pages/<eigeneSeite> nach und anschließend im Ordner ./pages/base. Dadurch sind Anpassungen an (root, base) etc. für spezielle Geräte möglich {{Link2Forum|Topic=30909|Message=241148|LinkText=(Forum)}}.

Für die eigenen Seiteninhalte sollten entsprechend die Dateinamen "base.html, basic.html, device.html" nicht verwendet werden, da dieses System-Seiten sind.

;fronthem
Obwohl der folgende Teil bereits zur Einrichtung von fronthem gehört, sei es der Vollständigkeit halber des Beispiels hier trotzdem erwähnt:
* In FHEM eine fronthemDevice Detailansicht öffnen
* Nun sollten die GADs aufgelistet werden. Aus der Liste ein GAD auswählen (hier: "Leselampe.sw" wie im obigen Code-Beispiel definiert.) und die Parameter vergeben:
<pre>
device: <fhem-Name-des-fhem-devices> (in diesem Fall die Leselampe.sw)
reading: state
converter: OnOff
cmd set: state
write: ja (haken setzen)
read: ja (haken setzen)
</pre>
: "state" immer klein schreiben und speichern nicht vergessen!
* Die Settings für das Device gelten für alle Endgeräte, aber die read/write Rechte müssen für jedes Endgerät separat gesetzt werden.

=== Einrichtung Endgerät ===
Auf dem Endgerät greift man auf die smartVISU-Seiten zu und stellt auf der Config-Seite den Treiber, IP der Servers und den Port ein.

Unter smartVISU in die Konfigurationsoberfläche wechseln <code>http://<IP-Adresse>/smartvisu/index.php?page=config</code> bzw. Zahnrad = Config-Menü:
* Im Feld "Interfaces" für pages das eigenes Haus auswählen (=Ordnername)
* Der Pagecache sollte zumindest während der Einrichtung ausgeschaltet sein.
* Im Feld I/O Connection den Treiber Fhem wählen
* Die IP-Adresse des Servers mit dem Websocket-Server eintragen
* Port 2121 einstellen
Nach allen Eintragungen die Konfiguration am unteren Ende der Seite speichern.

Damit die GADs nun im GAD-Editor auf der Detailseite von einem [[fronthem#fronthemEditor|fronthemDevice]] auftauchen, ist es jetzt wichtig, die neue Seite in smartVISU einmal aufzurufen, damit im Hintergrund die GADs übertragen werden.

Vorausgesetzt, man hat vorher alle notwendigen Schritte für die Installation und Konfiguration von fronthem ausgeführt, kann man nun smartVISU in Verbindung mit FHEM benutzen.

Im Noramlbetrieb stellt man den Pagecache auf "on"- dann werden die templates compiliert gespeichert, was die Geschwindigkeit erhöht {{Link2Forum|Topic=35960|Message=283665|LinkText=(Forum)}}.

=== Die wichtigste Dateien der eigenen Seite ===
Im Folgenden sind die wichtigsten Dateien und Grundlagen beschrieben, aus der eine Seite zusammensetzt ist, die aus den Template-Dateinen erstellt wurde. Jede Seite besteht aus der Menüzeile, einer Seitenleiste auf der linken Seite und den Hauptbereich auf der rechten Seite.

Entsprechend Browser (z.B. Desktop oder Smartphone) werden die Seiten unterschiedlich dargestellt.

;index.html
Der Inhalt dieser Seite ist der erste, der aufgerufen wird. Hauptsächlich besteht er aus 2 Blöcken, gekennzeichnet durch
{% block sidebar %}
...
{% endblock %}

und
{% block content %}
...
{% endblock %}

Im Block <code>sidebar</code> steht der Inhalt, der auf der linken Seite der Startseite dargestellt wird. Im Beispiel wird wird die Uhr, das Datum, das aktuelle Wetter und die Wettervorhersage eingebunden.

Im Block <code>content</code> wird die Datei <code>rooms_menu.html</code> eingebunden. Der Inhalt dieses Blocks wird im rechten Bereich dargestellt.

;rooms_menu.html
Diese Datei enthält die Darstellung des Links für die einzelnen Räume wie z.B. <code>room_sleeping.html</code> für das Schlafzimmer. Ruft man von der Hauptseite einen Raum auf, wird auf einem Desktop-Browser die Seite <code>rooms_menu.html</code>im linken Bereich im Block Sidebar dargestellt, im rechten Bereich wird der Inhalt des Raums dargestellt.

;room_sleeping.html
Pro Raum gibt es eine Datei, die die Darstellung eines Raumes festlegen. Dort wie oben, wird der Bereich, der Darstellung über die Blockdefinition festgelegt.

;rooms.html
Im Rahmen des Ladezyklus, wird diese Datei ebenfalls geladen, läd jedoch ihrerseits gleich die nächste.

;visu.ccs
Möchte man das Design anpassen, verwendet man eine Stylesheet-Datei "visu.css" in seinem Projektordner. Diese Datei ist standardmäßig nicht Teil der Vorlage und kann bei Bedarf angelegt werden.

;visu.js
In dieser Datei kann Javascrict-Code abgelegt werden, der auf einer Seite aufgerufen wird. Diese Datei ist standardmäßig nicht Teil der Vorlage und kann bei Bedarf angelegt werden.

;menu.html
Diese Datei ist nicht Teil der Einrichtung über die Vorlage des template-Ordners. Möchte man das Menü anpassen, das oben auf der Seite angezeigt wird, kopiert man die Datei <code>menu.html</code> aus dem Verzeichnis ./base in sein Verzeichnis ./pages/<eigeneSeite> und passt diese entsprechend an. Über die Reihenfolge, in der die Ordner nach möglichen Dateien durchsucht werden, wird im Folgenden die eigene individualisierte Datei berücksichtigt.

=== Verwendung von Widgets ===

==== Einbindung ====

Eigene oder individualisierte Widgets müssen vor dem Aufruf auf einer Seite "bekannt" gemacht werden. Dafür gibt es unterschiedliche Möglichkeiten.

;Import der html-Datei

Einfache Widgets bestehen meist nur aus einer html-Datei. Diese muss vor der ersten Verwendung des Widgets "importiert" werden.

An zentraler Stelle lässt sich dieses wie folgt durchführen. Man
* legt in seinem Ordner ./pages/eigenes-Haus einen Unterordner ./pages/eigenes-Haus/widgets an.
* kopiert die widgets-Datei in diesen Ordner.
* passt die Rechte entsprechend an.
* fügt der Datei <code>rooms.hmtl</code> in einer neuen Zeile direkt unterhalb von <code>{% extends "base.html" %}</code> folgende Zeile ein
{% import "widgets\\temp_sensor.html" as TempSensor %}

Der Dateiname <code>temp_sensor.html</code> enthält in diesem Beispiel den Code des Widgets {{Link2Forum|Topic=30909|Message=238044|LinkText=(Forum)}}, {{Link2Forum|Topic=30909|Message=238136|LinkText=(Forum)}}, {{Link2Forum|Topic=30909|Message=251586|LinkText=(Forum)}}.

;Import der Style-Definition und JS

Für komplexere Widgets muss ebenfalls die Style-Datei <code>visu.ccs</code> erweitert werden und Javascript-Code der Datei <code>visu.js</code> hinzugefügt werden. Damit der Code nicht komplett in den Dateien verwaltet werden muss, kann über die [https://github.com/ddtlabs/smartvisu-widgets/wiki/HowTo-Install-Widgets hier] beschriebene Methode der Code in Einzeldateien belassen werden. Dieses erleichtert den Überblick und die Möglichkeit separat Weiterentwicklungen der einzelnen Widgets auseinanderzuhalten und zu aktualisieren.

Über die beschriebene Erweiterung der <code>visu.ccs</code> und <code>visu.js</code> müssen die entsprechenden Teiles eines Widget nur noch einmal in diesen beiden Dateien definiert werden.

Auch hier gibt es die Möglichkeit, die Dateien in einem Unterordner ./pages/eigenes-Haus/widgets abzulegen {{Link2Forum|Topic=30909|Message=276232|LinkText=(Forum)}}.

Eine weitere Möglichkeit ist in diesem {{Link2Forum|Topic=30909|Message=278922|LinkText=Forums-Beitrag}} beschrieben, die allerdings nicht updatesicher für eine mögliche Aktualisierung von smartVISU ist.

==== Aufruf ====

Auf der Seite wird der Aufruf des Widgets eingebettet und über seinen Aufruf ebenfalls positioniert. Beispiele für das Einbetten sind im Docu-Haus enthalten.
{{ widgetname.function('<id>', '<gad>', '<weitere Parameter>') }}

Der Aufruf eines Widgets auf einer Seite besteht jeweils aus einem in doppelt geschweifte Klammern eingefassten Ausdrucks.
Der Ausdruck besteht aus der Nennung des Widgets, gefolgt von der mit einem Punkt getrennten Funktion. Wie in FHEM üblich ist auch hier die Groß/Kleinschreibung zu berücksichtigen und eine häufige Fehlerquelle.

Im Anschluss in Klammern folgen die durch Komma getrennten Parameter in Hochkommata:
* id, die ID des Widgets ist eigentlich nur innerhalb von smartVISU wichtig, kann willkürlich gewählt werden, darf sich auf einer html-Seite allerdings nicht wiederholen.
* gad, wird auch als Item bezeichnet. Dieses ist der Ausdruck, der später an fronthem übergeben wird und entsprechend im GAD-Editor auftaucht für die weitere Verarbeitung und Zuordnung.
* weitere Parameter, teilweise optional und teilweise mit Default-Werten, wenn diese nicht angegeben werden.

Ein etwas detaillierteres Beispiel findet sich innerhalb der [http://leseprobe.smartvisu.de/index.php?page=grundlagen_widget Leseprobe] der Dokumentation auf der smartVISU-Homepage.

== Codebeispiele ==



=== Layout ===

* [[smartVISU/IconHighlights in Menus|IconHighlights in Menus]]


=== Standard-Widgets ===

{{Todo|Hier sollte nicht die Dokumentation der Standardwidgets wiedergegeben werden, sondern Spezifika, die nicht in der Dokumentation auftauchen oder Anwendungsbeispiele.}}

==== Basic.switch ====

* [[smartVISU/lichtSzene|lichtSzene]]


=== zusätzliche Widgets ===

Es gibt diverse zusätzliche Widgets, für die es allerdings keine zentrale Quelle gibt. Stattdessen können diese aus den unterschiedlichen Repositories der Entwickler oder aus Beiträgen im Forum heruntergeladen werden.

Für die folgenden Widgets gibt es detailliertere Beschreibungen hier im Wiki:

* [[smartVISU/ical|ical]], Kalendereinbindung

;bekannte Repositories
https://github.com/herrmannj/smartvisu-widgets
* LED
* UZSU V2.0
** [[smartVISU/Universelle ZeitSchaltUhr (UZSU)]]
* auth_switch
* basic
* basic_extra
* chart
* device_extra
* fritzbox
** [[smartVISU/fritz!box_via_TR-064|fritz!box_via_TR-064]], Einbindung Anruferliste, Telefonbuch, etc.
* homematic

* httpcmd
* icon/battery
* icons
*img
* listbutton
* phoneservice/lib/phone/service
* selectmenu
* sonos
* squeezebox
* textinput
* timcounter

https://github.com/ddtlabs/smartvisu-widgets

Voraussetzung für die meisten hier liegenden Widgets ist V2.8 von smartVISU.
* basic-devices
* hm-rtr
* hue
* media
* motionDetection
* powerDistribution
* sonos
* ventilation

https://github.com/bgewehr/smartVISU
* basic2.html (LED)
* qlock.html
* widget_calendar.html
* widget_fritzbox.html
* widget_fritzbox_list.html
* widget_list.html
* widget_popup.html

https://github.com/mworion/uzsu_widget
* uzsu_widget V5.0

https://github.com/2ndsky/quad
* quad

im Forum
* [[smartVISU/Temperatur-/Feuchtigkeitssensor]]
* RTR für MAX! https://forum.fhem.de/index.php?topic=30909.msg241379#msg241379
* Ein weiteres Widget für ein RTR (Homematic) https://forum.fhem.de/index.php?topic=30909.msg276719#msg276719
* noch ein widget für homematic für HM-CC-RT-DN https://forum.fhem.de/index.php?topic=30909.msg248462#msg248462

== Links ==

[http://www.smartvisu.de smartVISU Hauptseite von smartVISU]

[http://twig.sensiolabs.org/documentation PHP-Twig Doku]

[https://code.google.com/archive/p/smartvisu/wikis Google-Archiv smartVISU]

[[Kategorie: fronthem/smartVISU]]

SmartVISU

2016-07-17T11:40:30Z

Joshi04: Erweiterung der Beschreibung

{{SEITENTITEL:smartVISU}}

Dieser Artikel beschreibt das Web-Frontend smartVISU, dessen Funktionen und Konfiguration. [http://www.smartvisu.de smartVISU] ist ein Framework zur Visualisierung von Hausautomationssystemen, die eigentlich KNX-Installationen bedient. Für die Anbindung an FHEM ist die Installation und Konfiguration von [[Fronthem]] notwendig, dass das Interface für die Anbindung zur Verfügung stellt.

In einem separaten Artikel wird die [[smartVISU Installation|Basis-Installation von smartVISU]] beschrieben, die eine Voraussetzung für die Verwendung von smartVISU ist.

Ein paar Sceenshots, die einen Eindruck des Frontends vermitteln wurden im {{Link2Forum|Topic= 27291|Message=227568|LinkText=Forum}} veröffentlicht.

Alle Artikel zur Thematik fronthem/smartVISU sind [[:Kategorie:fronthem/smartVISU|hier]] kategorisiert.

----

__TOC__

Hat man die Installation durchgeführt, befindet sich im root-Verzeichnis der smartVISU Installation für die schnelle Einrichtung die Datei readme.md, in der ein 10-Schritte Guide die erste Konfiguration beschreibt.

Wurden ebenfalls die Erweiterungen für FHEM eingespielt, befindet sich in diesem Verzeichnis ebenfalls die Datei readme.txt, die etwas FHEM-spezifischer ebenfalls den 10-Schritte Guide enthält.

== Bausteine ==

[[Datei:Systemuebersicht_fronthem_smartVISU.jpg|550px|thumb|right|Systemübersicht, fronthem/smartVISU]]
Zum besseren Verständnis der Begrifflichkeiten und Zusammenhänge ist hier eine Systemübersicht dargestellt.

=== Statische Seiten ===

Für den Betrieb von smartVISU ist ein Web-Server mit PHP notwendig. Dieser stellt die statischen Inhalte des Frontends zur Verfügung. Die Oberfläche muss den eigenen Bedürfnissen per programmieren der Web-Seite anpassen werden. HTML-, PHP- oder Javascript-Kenntnisse sind hilfreich, aber nicht zwingend erforderlich.
Genügend Beispiele sind vorhanden und leicht anpassbar, so dass durch einfaches Zusammenstellen schnell eine individuelle Seite erstellt werden kann.

=== Treiber ===

==== Funktion ====

Was fronthem für FHEM ist, ist der Treiber für smartVISU. Er ist ein Stück Software (js), das in die ausgeliefertern Webseiten per Link eingebettet ist, auf dem Endgerät ausgeführt wird und die Kommunikation zwischen Endgerät und Websocketserver (fronthem) übernimmt und anpasst {{Link2Forum|Topic=53881|Message=466167|LinkText=(Forum)}}.

Ein explizit auf FHEM angepasster Treiber stellt unter anderem die Mandantenfähigkeit (end-device werden seperat betrachtet und beschickt) sicher.

Der Treiber besteht aus den beiden Files [https://github.com/herrmannj/smartvisu-cleaninstall/blob/master/driver/io_fhem.js io_fhem.js] und [https://github.com/herrmannj/smartvisu-cleaninstall/blob/master/driver/io_fhem.min.js io_fhem.min.js], die im smartVISU/driver/ Verzeichnis der smartVISU Installation abgelegt sind.

==== Verwendung ====

Ruft man die smartVISU-Seite auf einem Endgerät auf, wird auf der Config-Seite (Zahnrädersymbol in der oberen Menüzeile)
* als Driver "Fhem" ausgewählt,
* die Adresse des Websocketservers, auf dem fronthem ansprechbar ist unter "Address URL/IP" eingetragen und
* für den Port "2121" gesetzt.

=== Widgets ===

smartVISU bietet mit seinem Konzept der Widgets eine flexible Möglichkeit der individuellen Erweiterung an. Für viele Anwendungen gibt es bereits Widgets (z.B. Heizung, RGB, Clock, Wetter, etc.), auf die zurückgegriffen werden kann.

Mit einem Widget wird für den jeweiligen Anwendungsfall bestimmt, wie auf der Darstellungsseite das Design aussehen soll und auf der Verarbeitungsseite welche Parameter übergeben werden. So könnte man die Widgets auch als Vorlage verstehen, um diese Designelemente bei Bedarf entsprechend einzubinden.
{{Randnotiz|RNTyp=y|RNText=Schaut man sich die Dokumentation oder die Beispielhäuser an, sollte vorher den Treiber auf offline geschaltet werden, weil sich sonst fronthem die Konfiguration der Demohäuser importiert und merkt {{Link2Forum|Topic=30909|Message=235155|LinkText=(Forum)}}.}}
Es gibt diverse Standard-Widget, die bereits Teil der smartVISU-Installation sind. Darüber hinaus können eigene oder individualisierte Widgets hinzugefügt werden.
Die Dokumentation der verfügbaren Standard-Widgets in der Basisinstallation ist im Unterordner /pages/Docu gespeichert. Die Dokumentation kann angeschaut werden, indem man auf der Config-Seite die Page "Docu" auswählt bzw. direkt in die Widgets schaut, die im Stammverzeichnis der smartVISU im Unterordner /widgets abgelegt sind.

== Standard Seitenladeprozess ==

(Übersetzt aus readme.txt)

Ruft man die smartVISU-Seite über den Aufruf <code>http://<Server-IP>/<Installationsverzeichnis></code> (z.B. http://192.168.1.1/smartvisu) auf, läuft über die <code>index.php</code> ein vordefinierter Ladezyklus ab, der
* über die includes.php, die Einstellungen der config.ini einliest,
* die twig Umgebung startet
* die Pfade setzt (für pages, icons, Standartwidgets, etc.)
* die index.html der in der config.ini configurierten Seite ./pages/<eigener Ordner>

Der Ladeprozess ist in der Datei readme.txt noch etwas detaillierter beschrieben. Der Ladeprozess regelt ebenfalls das Verhalten, wenn noch keine Konfiguration definiert wurde oder bestimmte Dateien an den Orten nicht vorhanden sind.

Gibt es vor allen Dingen bei der Ersteinrichtung Probleme, sollte man sich den Ladeprozess und das Vorhandensein der Dateien und die richtige Konfiguration näher anschauen.

== Ersteinrichtung ==

Die folgende Beschreibung setzt voraus, dass die notwendigen Schritte für die grundsätzliche Installation von smartVISU und fronthem bereits erfolgreich durchgeführt wurden.

=== ein "eigenes-Haus" anlegen ===

Es gilt ein eigenes "Haus" anzulegen, dass man individuell konfiguriert.

* Für eine eigene neue Seite legt man unter ./pages des smartVISU-Root-Verzeichnisses ein neues Verzeichnis <code>eigenes-Haus</code> an.
* Die Dateien auf dem Ordner ./pages/_template kopiert man in dieses Verzeichnis.
* Dort editiert man die Dateien und fügt z.B. Dinge ein, die man aus der Doku z.B. auf von www.smartVISU.de heraus kopiert hat. Auch die Beispielhäuser sind sehr hilfreich zum lernen. Einen speziellen Editor oder eine grafische Oberfläche für die Programmierung ist nicht erforderlich. Als erstes passt man z.B. die Datei <code>rooms_menu.html</code> an die eigenen Bedürfnisse an.
* Die Räume richtet man ein, indem man diese durch Kopien des Beispielraumes (<code>room_sleeping.html</code>) und passende icons und Überschriften erstellt. ([http://www.smartvisu.de/docu/2.7/index.php?page=design/design_icons SmartVisu Icons])
* SmartVISU nutzt [http://twig.sensiolabs.org/ Twig] als Template engine und die Seiten bestehen aus Blöcken und Widgets, die immer in doppelten geschweiften Klammern stehen <nowiki>{{ ... }}</nowiki>
* Widget Syntax auf [http://www.smartvisu.de/docu/2.7/index.php SmartVISU Doku] nachschlagen und kopieren.
* Innerhalb eines Raums zwischen {% block content %} und {% endblock %} als Beispiel folgenden Abschnitt einfügen:

<pre><nowiki>
<h1><img class="icon" src='{{ icon0 }}scene_livingroom.png'/>Wohnzimmer</h1>
<div class="preblock">
</div>
<div class="block">
<div class="set-2" data-role="collapsible-set" data-theme="c" data-content-theme="a" data-mini="true">
<div data-role="collapsible" data-collapsed="false" >
<h3>Licht</h3>
<table width="90%">
<tr><td align="left" width="100px"> {{ basic.switch('Leselampe', 'Leselampe.sw', icon1~'light_floor_lamp.png', icon0~'light_floor_lamp.png') }}</td>
<td>Leselampe</td>
</tr>
</table>
</div>
</div>
</div>
</nowiki></pre>

* Datei speichern und checken, dass die Rechte mindestens auf "755" stehen, ansonsten mit "sudo chmod 755" korrigieren.

Beim erstellen eigener Seiten oder Widgets sollte man darauf achten, nicht in die Dateien der smartVISU-Installation direkt einzugreifen, sondern vornehmlich in den eigenen Pages zu arbeiten. So steht auch einem unbeeinträchtigten späteren Update nichts im Wege.

Beispielsweise anstelle <code>root.html</code> oder <code>base.html</code> im Ordner ./pages/base direkt zu verändern, sollte man jeweils angepasste Kopien in das eigene Pages-Verzeichnis legen - diese haben dann Vorrang vor den System Dateien {{Link2Forum|Topic=30909|Message=268592|LinkText=(Forum)}}.

Die Template-Engine schaut zuerst im Ordner ./pages/<eigeneSeite> nach und anschließend im Ordner ./pages/base. Dadurch sind Anpassungen an (root, base) etc. für spezielle Geräte möglich {{Link2Forum|Topic=30909|Message=241148|LinkText=(Forum)}}.

Für die eigenen Seiteninhalte sollten entsprechend die Dateinamen "base.html, basic.html, device.html" nicht verwendet werden, da dieses System-Seiten sind.

;fronthem
Obwohl der folgende Teil bereits zur Einrichtung von fronthem gehört, sei es der Vollständigkeit halber des Beispiels hier trotzdem erwähnt:
* In FHEM eine fronthemDevice Detailansicht öffnen
* Nun sollten die GADs aufgelistet werden. Aus der Liste ein GAD auswählen (hier: "Leselampe.sw" wie im obigen Code-Beispiel definiert.) und die Parameter vergeben:
<pre>
device: <fhem-Name-des-fhem-devices> (in diesem Fall die Leselampe.sw)
reading: state
converter: OnOff
cmd set: state
write: ja (haken setzen)
read: ja (haken setzen)
</pre>
: "state" immer klein schreiben und speichern nicht vergessen!
* Die Settings für das Device gelten für alle Endgeräte, aber die read/write Rechte müssen für jedes Endgerät separat gesetzt werden.

=== Einrichtung Endgerät ===
Auf dem Endgerät greift man auf die smartVISU-Seiten zu und stellt auf der Config-Seite den Treiber, IP der Servers und den Port ein.

Unter smartVISU in die Konfigurationsoberfläche wechseln <code>http://<IP-Adresse>/smartvisu/index.php?page=config</code> bzw. Zahnrad = Config-Menü:
* Im Feld "Interfaces" für pages das eigenes Haus auswählen (=Ordnername)
* Der Pagecache sollte zumindest während der Einrichtung ausgeschaltet sein.
* Im Feld I/O Connection den Treiber Fhem wählen
* Die IP-Adresse des Servers mit dem Websocket-Server eintragen
* Port 2121 einstellen
Nach allen Eintragungen die Konfiguration am unteren Ende der Seite speichern.

Damit die GADs nun im GAD-Editor auf der Detailseite von einem [[fronthem#fronthemEditor|fronthemDevice]] auftauchen, ist es jetzt wichtig, die neue Seite in smartVISU einmal aufzurufen, damit im Hintergrund die GADs übertragen werden.

Vorausgesetzt, man hat vorher alle notwendigen Schritte für die Installation und Konfiguration von fronthem ausgeführt, kann man nun smartVISU in Verbindung mit FHEM benutzen.

Im Noramlbetrieb stellt man den Pagecache auf "on"- dann werden die templates compiliert gespeichert, was die Geschwindigkeit erhöht {{Link2Forum|Topic=35960|Message=283665|LinkText=(Forum)}}.

=== Die wichtigste Dateien der eigenen Seite ===
Im Folgenden sind die wichtigsten Dateien und Grundlagen beschrieben, aus der eine Seite zusammensetzt ist, die aus den Template-Dateinen erstellt wurde. Jede Seite besteht aus der Menüzeile, einer Seitenleiste auf der linken Seite und den Hauptbereich auf der rechten Seite.

Entsprechend Browser (z.B. Desktop oder Smartphone) werden die Seiten unterschiedlich dargestellt.

;index.html
Der Inhalt dieser Seite ist der erste, der aufgerufen wird. Hauptsächlich besteht er aus 2 Blöcken, gekennzeichnet durch
{% block sidebar %}
...
{% endblock %}

und
{% block content %}
...
{% endblock %}

Im Block <code>sidebar</code> steht der Inhalt, der auf der linken Seite der Startseite dargestellt wird. Im Beispiel wird wird die Uhr, das Datum, das aktuelle Wetter und die Wettervorhersage eingebunden.

Im Block <code>content</code> wird die Datei <code>rooms_menu.html</code> eingebunden. Der Inhalt dieses Blocks wird im rechten Bereich dargestellt.

;rooms_menu.html
Diese Datei enthält die Darstellung des Links für die einzelnen Räume wie z.B. <code>room_sleeping.html</code> für das Schlafzimmer. Ruft man von der Hauptseite einen Raum auf, wird auf einem Desktop-Browser die Seite <code>rooms_menu.html</code>im linken Bereich im Block Sidebar dargestellt, im rechten Bereich wird der Inhalt des Raums dargestellt.

;room_sleeping.html
Pro Raum gibt es eine Datei, die die Darstellung eines Raumes festlegen. Dort wie oben, wird der Bereich, der Darstellung über die Blockdefinition festgelegt.

;rooms.html
Im Rahmen des Ladezyklus, wird diese Datei ebenfalls geladen, läd jedoch ihrerseits gleich die nächste.

;visu.ccs
Möchte man das Design anpassen, verwendet man eine Stylesheet-Datei "visu.css" in seinem Projektordner. Diese Datei ist standardmäßig nicht Teil der Vorlage und kann bei Bedarf angelegt werden.

;visu.js
In dieser Datei kann Javascrict-Code abgelegt werden, der auf einer Seite aufgerufen wird. Diese Datei ist standardmäßig nicht Teil der Vorlage und kann bei Bedarf angelegt werden.

;menu.html
Diese Datei ist nicht Teil der Einrichtung über die Vorlage des template-Ordners. Möchte man das Menü anpassen, das oben auf der Seite angezeigt wird, kopiert man die Datei <code>menu.html</code> aus dem Verzeichnis ./base in sein Verzeichnis ./pages/<eigeneSeite> und passt diese entsprechend an. Über die Reihenfolge, in der die Ordner nach möglichen Dateien durchsucht werden, wird im Folgenden die eigene individualisierte Datei berücksichtigt.

=== Verwendung von Widgets ===

==== Einbindung ====

Eigene oder individualisierte Widgets müssen vor dem Aufruf auf einer Seite "bekannt" gemacht werden. Dafür gibt es unterschiedliche Möglichkeiten.

;Import der html-Datei

Einfache Widgets bestehen meist nur aus einer html-Datei. Diese muss vor der ersten Verwendung des Widgets "importiert" werden.

An zentraler Stelle lässt sich dieses wie folgt durchführen. Man
* legt in seinem Ordner ./pages/eigenes-Haus einen Unterordner ./pages/eigenes-Haus/widgets an.
* kopiert die widgets-Datei in diesen Ordner.
* passt die Rechte entsprechend an.
* fügt der Datei <code>rooms.hmtl</code> in einer neuen Zeile direkt unterhalb von <code>{% extends "base.html" %}</code> folgende Zeile ein
{% import "widgets\\temp_sensor.html" as TempSensor %}

Der Dateiname <code>temp_sensor.html</code> enthält in diesem Beispiel den Code des Widgets {{Link2Forum|Topic=30909|Message=238044|LinkText=(Forum)}}, {{Link2Forum|Topic=30909|Message=238136|LinkText=(Forum)}}, {{Link2Forum|Topic=30909|Message=251586|LinkText=(Forum)}}.

;Import der Style-Definition und JS

Für komplexere Widgets muss ebenfalls die Style-Datei <code>visu.ccs</code> erweitert werden und Javascript-Code der Datei <code>visu.js</code> hinzugefügt werden. Damit der Code nicht komplett in den Dateien verwaltet werden muss, kann über die [https://github.com/ddtlabs/smartvisu-widgets/wiki/HowTo-Install-Widgets hier] beschriebene Methode der Code in Einzeldateien belassen werden. Dieses erleichtert den Überblick und die Möglichkeit separat Weiterentwicklungen der einzelnen Widgets auseinanderzuhalten und zu aktualisieren.

Über die beschriebene Erweiterung der <code>visu.ccs</code> und <code>visu.js</code> müssen die entsprechenden Teiles eines Widget nur noch einmal in diesen beiden Dateien definiert werden.

Auch hier gibt es die Möglichkeit, die Dateien in einem Unterordner ./pages/eigenes-Haus/widgets abzulegen {{Link2Forum|Topic=30909|Message=276232|LinkText=(Forum)}}.

Eine weitere Möglichkeit ist in diesem {{Link2Forum|Topic=30909|Message=278922|LinkText=Forums-Beitrag}} beschrieben, die allerdings nicht updatesicher für eine mögliche Aktualisierung von smartVISU ist.

==== Aufruf ====

Auf der Seite wird der Aufruf des Widgets eingebettet und über seinen Aufruf ebenfalls positioniert. Beispiele für das Einbetten sind im Docu-Haus enthalten.
{{ widgetname.function('<id>', '<gad>', '<weitere Parameter>') }}

Der Aufruf eines Widgets auf einer Seite besteht jeweils aus einem in doppelt geschweifte Klammern eingefassten Ausdrucks.
Der Ausdruck besteht aus der Nennung des Widgets, gefolgt von der mit einem Punkt getrennten Funktion. Wie in FHEM üblich ist auch hier die Groß/Kleinschreibung zu berücksichtigen und eine häufige Fehlerquelle.

Im Anschluss in Klammern folgen die durch Komma getrennten Parameter in Hochkommata:
* id, die ID des Widgets ist eigentlich nur innerhalb von smartVISU wichtig, kann willkürlich gewählt werden, darf sich auf einer html-Seite allerdings nicht wiederholen.
* gad, wird auch als Item bezeichnet. Dieses ist der Ausdruck, der später an fronthem übergeben wird und entsprechend im GAD-Editor auftaucht für die weitere Verarbeitung und Zuordnung.
* weitere Parameter, teilweise optional und teilweise mit Default-Werten, wenn diese nicht angegeben werden.

Ein etwas detaillierteres Beispiel findet sich innerhalb der [http://leseprobe.smartvisu.de/index.php?page=grundlagen_widget Leseprobe] der Dokumentation auf der smartVISU-Homepage.

== Codebeispiele ==

{{Baustelle|Dieser Bereich befindet sich in Überarbeitung und kann gerne erweitert werden.}}



=== Layout ===

* [[smartVISU/IconHighlights in Menus|IconHighlights in Menus]]

=== Standard-Widgets ===

{{TODO|Hier sollte nicht die Dokumentation der Standardwidgets wiedergegeben werden, sondern Spezifika, die nicht in der Dokumentation auftauchen oder Anwendungsbeispiele.}}
* [[smartVISU/lichtSzene|lichtSzene]]

=== zusätzliche Widgets ===

Zusätzliche Widgets werden im git-Repository https://github.com/herrmannj/smartvisu-widgets bereitgestellt:

* [[smartVISU/Universelle ZeitSchaltUhr (UZSU)]]
* [[smartVISU/ical|ical]], Kalendereinbindung
* [[smartVISU/fritz!box_via_TR-064|fritz!box_via_TR-064]], Einbindung Anruferliste, Telefonbuch, etc.
* [[smartVISU/Temperatur-/Feuchtigkeitssensor]]



== Links ==

[http://www.smartvisu.de smartVISU Hauptseite von smartVISU]

[http://twig.sensiolabs.org/documentation PHP-Twig Doku]

[https://code.google.com/archive/p/smartvisu/wikis Google-Archiv smartVISU]

[[Kategorie: fronthem/smartVISU]]

SmartVISU Installation

2016-07-17T11:35:53Z

Joshi04: Verlagern der Einrichtungsanteile in den smartVISU-Hauptartikel

{{SEITENTITEL:smartVISU Installation}}

Dieser Artikel beschreibt die Installation des Web-Frontends [[smartVISU]] und berücksichtigt mehrerer Alternativen für unterschiedliche Web-Server. Zum Betrieb von smartVISU mit FHEM ist die Installation und Konfiguration von [[fronthem]] erforderlich.

Alle Artikel zur Thematik fronthem/smartVISU sind [[:Kategorie:fronthem/smartVISU|hier]] kategorisiert.

----

__TOC__

Für die Installation ist es immer sinnvoll, von einem auf aktuellem Stand befindlichen System zu starten.

Für das Betriebssystem (Linuxderivat)
sudo apt-get update

sudo apt-get upgrade

Für FHEM
<code>update</code> in der Eingabezeile

Die Installation lässt sich in 4 Bereiche unterteilen.

== Webserver installieren ==

Welcher Webserver zum Einsatz kommt, ist unerheblich. Im Folgenden sind Beispiele für lighttpd, nginx und Apache2 zu finden. Es wird nur '''eine''' Installation benötigt.

=== lighttpd ===
Dieses Beispiel basiert auf diesem {{Link2Forum|Topic= 27291|Message=208880|LinkText=Forumsbeitrag}}.

Webserver installieren:
sudo apt-get install lighttpd

PHP installieren:
sudo apt-get install php5-common php5-cgi php5

PHP konfigurieren:
sudo lighty-enable-mod fastcgi-php

Webserver-Dienst einmal neu starten, damit die Einstellungen wirksam werden:
sudo service lighttpd force-reload

Welchseln in des Root-Verzeichnis des Webservers (bei Bedarf, wenn sich das Root-Verzeichnis einer Distribution woanders ist, muss dieser Pfad entsprechend angepasst werden):
cd /var/www

Setzen des Besitzers und der Gruppe für das Root-Verzeichnis (TODO: Ist dieser Schritt wirklich notwendig?):
sudo chown www-data:www-data /var/www

Setzen der Berechtigungen des Root-Verzeichnis (TODO: Ist dieser Schritt wirklich notwendig?):
sudo chmod 775 /var/www

=== nginx ===
==== mit PHP5 ====

Dieses Beispiel basiert auf diesem {{Link2Forum|Topic=30909|Message=273180|LinkText=Forumsbeitrag}}.

Für die Installation des Webservers und PHP5 werden folgende Pakete benötigt:
sudo apt-get install nginx php5-fpm

Die Konfiguration für PHP muss in der entsprechenden Konfigurationsdatei vorgenommen werden:
sudo nano /etc/nginx/sites-enabled/default

Folgende Konfiguration sollte direkt funktionieren:
<pre>
server {
listen 80;
root /var/www;
index index.html index.php;
server_name localhost;
location / {
try_files $uri $uri/ /index.php?$args;
}
location ~ \.php$ {
try_files $uri =404;
fastcgi_pass unix:/var/run/php5-fpm.sock;
fastcgi_index index.php;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
include fastcgi_params;
}
}
</pre>

==== mit PHP7 ====
Ubuntu 16.04 läuft standardmäßig mit PHP7. Der Betrieb ist noch nicht zu 100% getestet und daher ohne Garantie.

Für die Installation des Webservers und PHP werden folgende Pakete benötigt:
sudo apt-get install nginx php7.0-fpm

Die Konfiguration für PHP muss in der entsprechenden Konfigurationsdatei vorgenommen werden:
sudo nano /etc/nginx/sites-enabled/default

Folgende Konfiguration sollte direkt funktionieren:
<pre>
server {
listen 80 default_server;
listen [::]:80 default_server;
root /var/www/html;
index index.php index.html index.htm index.nginx-debian.html;

server_name _;

location / {
try_files $uri $uri/ =404;
}
location ~ \.php$ {
try_files $uri =404;
fastcgi_split_path_info ^(.+\.php)(/.+)$;
fastcgi_pass unix:/run/php/php7.0-fpm.sock;
fastcgi_index index.php;
include fastcgi.conf;
fastcgi_read_timeout 600;
}
location ~* \.(js|css|png|jpg|jpeg|gif|ico|eot|otf|ttf|woff)$ {
access_log off; log_not_found off; expires 30d;
}
location = /robots.txt { access_log off; log_not_found off; }
location ~ /\. { deny all; access_log off; log_not_found off; }
}
</pre>

=== Apache2 ===

Dieses Beispiel basiert auf diesem [http://www.meintechblog.de/2015/06/smartvisu-mit-fhem-die-perfekte-visualisierung-teil-1-basics/ Blogeintrag].

Für die Installation des Webservers und PHP5 werden folgende Pakete benötigt:
sudo apt-get install apache2 php5 libapache2-mod-php5

Für das git /cleaninstall: da liegt die erweiterte smartVISU, mit Mandanten und reparierten widgets (wo nötig) - ansonsten aber unverfälscht und nicht mit widgets erweitert.

== smartVISU Installation ==

Für das Klonen (Herunterladen) wird folgendes Paket benötigt:
sudo apt-get install git

;Verfügbare Versionen (Stand Juli 2016):
Bis zur V2.7 gibt es ein offizielles Release, auf dem sowohl die Dokumentation auf der Seite [www.smartVISU.de] basiert, als auch das nachfolgend beschriebene smartvisu-cleaninstall.

Die nicht offizielle V2.8 kann aus den Entwicklungszweig von smartVISU heruntergeladen werden, muss aber im Anschluss um die Erweiterungen für den Betrieb mit FHEM ergänzt werden. Ob es ein offizielles Release V2.8 geben wird, ist derzeit unbekannt. Unabhängig davon wird an einem Fork in Zusammenhang für den Betrieb mit FHEM gearbeitet.

Zwar sollten alle Widgets, die auf V2.7 lauffähig sind, auch mit V2.8 kompatibel sein, dieses ist derzeit aber nicht getestet und kann nicht garantiert werden. Die Widgets müssen bei Bedarf entsprechend angepasst werden. Andererseits gibt es bereits Widgets, die V2.8 voraussetzen. Bei manchen Widgets sind die Voraussetzungen ist der Dokumentation beschrieben.

Die Unterschiede zwischen V2.7 und V2.8 sind in diesem {{Link2Forum|Topic=54506|Message=469401|LinkText=Beitrag}} zusammengefasst.

Derzeit kann aber bereits empfohlen werden, bei einer Neuinstallation gleich V2.8 zu installieren {{Link2Forum|Topic=53881|Message=471075|LinkText=(Forum)}}.

=== smartVISU-cleaninstall, V2.7 ===
==== Herunterladen ====
Für die Installation gibt es ein fertig zusammengestelltes Paket aus dem git-Repo von Jörg Herrmanns ([https://github.com/herrmannj/smartvisu-cleaninstall]).

Hierbei handelt es sich um das Original smartVISU inkl. einigen Anpassungen (fhem-Treiber, Widget-Korrekturen, ...).

Einrichten eines Installationsordners im home-Verzeichnis:
mkdir ~/install

Wechseln in das Verzeichnis:
cd ~/install

Klonen der Pakets:
git clone https://github.com/herrmannj/smartvisu-cleaninstall.git
Dabei wird der Unterordner ./smartvisu-cleaninstall angelegt, in den die Dateien heruntergeladen werden.

==== Kopieren in das Webserver Root-Verzeichnis ====
Damit der Webserver die Seiten von smartVISU zur Verfügung stellt, müssen diese an die richtige Stelle in Abhängigkeit des verwendeten Webservers und Konfiguration kopiert werden. Ggf. muss die Konfiguration des Webservers entsprechend angepasst werden.

Das neu erstellte Verzeichnis in das Root-Verzeichnis des Webservers kopieren. Dass, wie in diesem Fall angegeben, das Verzeichnis /var/www/ das richtige Verzeichnis ist, kann z.B. dadurch bestätigt werden, dass dort bereits die Default-Seite des Webservers nach der Ersteinrichtung zu finden ist. Bei Bedarf ist das Verzeichnis anzupassen.
sudo cp -rp smartvisu-cleaninstall /var/www/smartVISU

Selbstverständlich lässt dich auch ein anderes Installationsverzeichnis wählen. Die folgenden Schritte müssen dann entsprechend angepasst werden.

==== Berechtigungen setzen ====
Später wird zumindest die Konfiguration von dem, was auf dem Endgerät angezeigt werden soll, vom Endgerät aus konfiguriert. Damit dieses auch funktioniert, müssen die Berechtigungen der Seiten entsprechend angepasst werden.

Wechseln in das Verzeichnis:
cd /var/www

Setzen des Besitzers und der Gruppe für das Root-Verzeichnis von smartVISU
chown -R www-data:www-data smartVISU

Setzen der Berechtigungen für das Root-Verzeichnis "smartVISU" und alle Unterordner
chmod -R 775 smartVISU

==== ggf. Gruppenmitgliedschaft anpassen ====
Dieser Schritt ist optional und dann hilfreich, wenn man mit einem normalen user z.B. über fileZilla die Dateien austauschen möchte. Da der Schritt zulasten der Sicherheit geht, sollte man ihn nach Abschluss der Konfiguration ggf. wieder rückgängig machen.

In diesem Beispiel wird der user "pi" zur Gruppe <code>www-data</code> hinzugefügt. Verwendet man einen anderen user, muss dieses selbstverständig angepasst werden.
sudo usermod -a -G www-data pi

Rückgängig machen kann man die Gruppenzugehörigkeit über
sudo deluser pi www-data

==== Config.ini kopieren ====
Hierbei handelt es sich um die Hauptdatei mit der das Verhalten von smartVISU gesteuert wird.

Die Datei "config.ini.default" muss zu "config.ini" umbenennen oder besser kopiert werden:
sudo cp /var/www/smartVISU/config.ini.default /var/www/smartVISU/config.ini

==== Installation überprüfen ====

Beim Aufruf der Seite <code>http://<IP-Adresse>/smartVISU</code> sollte folgende Seite angezeigt werden: {{Randnotiz|RNTyp=y|RNText=
Ggf. in der php.ini (error_reporting) die Ausgabe von Warnings abschalten, wenn so was kommt wie "Notice: Undefined index..."
}}

Diese Seite wird ggf. nur einmal direkt nach der Ersteinrichtung angezeigt und ist im Folgenden nicht mehr notwendig.

[[Datei:Installation_SmartVISU.png]]

=== nicht offizielle Version, V2.8 ===

Die Beschreibung für die Installation der nicht offiziellen Version 2.8 von smartVISU basiert auf diesem [https://github.com/ddtlabs/build-smartvisu-cleaninstall Git-Eintrag] von [user=dev0].

Da man das Softwarepaket für smartVISU direkt aus dem Entwicklungszweig herunterläd, müssen die notwendigen Erweiterungen für den Betrieb mit FHEM nachträglich manuell eingefügt werden. Dabei ist der "Treiber" am wichtigsten.

Wie leicht zu erkennen, ist im folgenden Beispiel das Root-Verzeichnis des Webservers <code>/var/www/html</code> und das Verzeichnis, in das smartVISU installiert wird "sv".
Die smartVISU-Seite wird am Ende der Installation entsprechend mit <code>http://<IP-Adresse>/sv</code> aufgerufen.

Anpassen der Gruppenmitgliedschaften kann nach dem oben beschriebenen Muster durchgeführt werden.

==== Herunterladen ====

Die Dateien werden direkt aus dem Entwicklungszweig heruntergeladen.
git clone https://github.com/Martin-Gleiss/smartvisu.git

==== Kopieren in das Webserver Root-Verzeichnis ====
sudo cp -rp smartvisu /var/www/html/sv

==== Herunterladen der Erweiterungen für FHEM ====
git clone https://github.com/herrmannj/smartvisu-cleaninstall.git

==== Kopieren der Erweiterungen ====
sudo cp ./smartvisu-cleaninstall/readme.txt /var/www/html/sv/
sudo cp ./smartvisu-cleaninstall/lib/functions_config.php /var/www/html/sv/lib/
sudo cp ./smartvisu-cleaninstall/lib/includes.php /var/www/html/sv/lib/
sudo cp ./smartvisu-cleaninstall/config.ini.default /var/www/html/sv/
sudo cp ./smartvisu-cleaninstall/pages/base/configure.php /var/www/html/sv/pages/base/
sudo cp ./smartvisu-cleaninstall/driver/io_fhem.js /var/www/html/sv/driver/
sudo cp ./smartvisu-cleaninstall/driver/io_fhem.min.js /var/www/html/sv/driver/

==== Config.ini kopieren ====
sudo cp /var/www/html/sv/config.ini.default /var/www/html/sv/config.ini

==== Setzen der Berechtigungen (Besitzer und Gruppe) ====
cd /var/www/html
sudo chown -R www-data:www-data sv

== Troubleshooting ==

=== SSL ===

Wird derzeit nicht unterstützt {{Link2Forum|Topic=43226|Message=352115|LinkText=(Forum)}}.

=== Performanceproblem ===

Während der Entwicklung gab es mehrere Evolutionen, was die Verbindung über den Treiber angeht. Trotzdem hat auch die Platform, auf der smartVISU läuft einen gehörigen Anteil an der Reaktivität der Oberfläche. Darüber hinaus hat selbstredend die Komplexität einer Seite Einfluss auf die Geschwindigkeit.
Mit einem Webserver auf dem RPi2 scheint es noch potential nach oben zu geben, setzte man eine performantere Platform ein {{Link2Forum|Topic= 48243|Message=402427|LinkText=(Forum)}}.

=== Config-Seite anstatt der individuellen Seite ===

Es wurde vergessen, die Datei config.ini.default nach config.ini zu kopieren {{Link2Forum|Topic= 46501|Message=382426|LinkText=(Forum)}}.

=== Zugriffsprobleme mit Apache ===
Anscheinend gab es vereinzelt Zugriffsprobleme auf das smartVISU-Vereichnis, die sich aber mit dieser Erweiterung der Apache-Konfiguration beheben lies {{Link2Forum|Topic=30909|Message=239882|LinkText=(Forum)}}:

<pre>
<Directory "/var/www/smartvisu">
Options +Indexes FollowSymLinks +ExecCGI
AllowOverride AuthConfig FileInfo
Order allow,deny
Allow from all
</Directory>
</pre>

=== 404 not found ===

Wird noch nicht einmal die Seite gefunden (404), sind bereits die statischen Seiteninhalte der Webseite nicht richtig konfiguriert. Es muss sichergestellt werden, dass eine Datei im Verzeichnis von smartVISU von einem Endgerät angezeigt werden kann {{Link2Forum|Topic= 46501|Message=49524|LinkText=(Forum)}}.

=== *.js dateien ===

Sollte jemand Änderungen an den *.js Dateien bearbeiten muss man daran denken, dass in der config.ini ganz unten vereinbart wird welche Version der Datei benutzt wird {{Link2Forum|Topic=30909|Message=252375|LinkText=(Forum)}}.

=== verschiedene Devices, verschiedene Anzeigen ===

Möchte man sicherstellen, dass auf allen Endgeräten die gleiche page konfiguriert ist, verschiebt man den entsprechenden Teil in der config.ini in den <nowiki>[default]</nowiki>-Bereich.

An dieser Stelle sei eindringlich empfohlen, diese Änderung nur bei nicht laufendem Websocket durchzuführen und in jedem Falle ein Backup der Datei vorzuhalten. Bei Syntaxfehlern wird diese Datei neu erzeugt und überschreibt ohne Nachfrage die Vorversion {{Link2Forum|Topic=46541|Message=383006|LinkText=(Forum)}} {{Link2Forum|Topic=36420|Message=287038|LinkText=(Forum)}}.

=== Welcher Treiber ist installiert ===

Um zu prüfen, welche Version vom Treiber man aktuell verwendet, kann man im Browser die Konsole öffnen und nach einem page reload diesen Log-Eintrag suchen:

[io.fhem]: init [V1.10] (address= ...

In diesem Beispiel ist es Version 1.10 {{Link2Forum|Topic=35960|Message=283617|LinkText=(Forum)}}.

=== neue Clients ===

Das Anlegen neuer Clients In smartVISU müssen nicht händisch ergänzt werden. In der config.ini gibt es den parameter auto_add = true|false. Wenn dieser auf true steht, werden neue Clients automatisch in smartVISU angelegt und bekommen eine Kopie der default Einstellungen.
Im Anschluss können über die Config-Seite die individuellen Einstellungen über die smartVISU-Oberfläche konfiguriert und gespeichert werden (page, design, evtl. calender, etc) {{Link2Forum|Topic=30909|Message=236222|LinkText=(Forum)}}.

=== Ordner und Dateien ===
Auch wenn es im Normalfall nicht notwendig ist sollte, kann es manchmal sinnvoll sein, den genauen Speicherort aller Dateien und Konfigurationsdateien zu kennen und entsprechend Debugging-Trigger hinzuzufügen oder Konfigurationen direkt zu korrigieren.

Die folgenden Pfadangaben gehen davon aus, dass das Root-Verzeichnis des eingesetzten Webservers /var/www/html/ ist und smartVISU im Unterordner /var/www/html/sv liegt.

Dokumenten Root für smartVISU:
/var/www/html/sv/

Konfigurationsdatei von smartVISU:
/var/www/html/sv/config.ini

Treiber:
/var/www/html/sv/driver/io-fhem.js

/var/www/html/sv/driver/io_fhem.min.js

Temp-Ordner:
/var/www/html/sv/temp

Template-Ordner für neue "page":
/var/www/html/sv/pages/_template

Eigener Page-Ordner
/var/www/html/sv/pages/<eigeneSeite>

[[Kategorie:fronthem/smartVISU]]

SmartVISU Installation

2016-07-12T19:10:04Z

Joshi04: /* smartVISU Installation */ V2.7 <-> V2.8

{{SEITENTITEL:smartVISU Installation}}

Dieser Artikel beschreibt die Installation des Web-Frontends [[smartVISU]] und berücksichtigt mehrerer Alternativen für unterschiedliche Web-Server. Zum Betrieb von smartVISU mit FHEM ist die Installation und Konfiguration von [[fronthem]] erforderlich.

Alle Artikel zur Thematik fronthem/smartVISU sind [[:Kategorie:fronthem/smartVISU|hier]] kategorisiert.

----

__TOC__

Für die Installation ist es immer sinnvoll, von einem auf aktuellem Stand befindlichen System zu starten.

Für das Betriebssystem (Linuxderivat)
sudo apt-get update

sudo apt-get upgrade

Für FHEM
<code>update</code> in der Eingabezeile

Die Installation lässt sich in 4 Bereiche unterteilen.

== Webserver installieren ==

Welcher Webserver zum Einsatz kommt, ist unerheblich. Im Folgenden sind Beispiele für lighttpd, nginx und Apache2 zu finden. Es wird nur '''eine''' Installation benötigt.

=== lighttpd ===
Dieses Beispiel basiert auf diesem {{Link2Forum|Topic= 27291|Message=208880|LinkText=Forumsbeitrag}}.

Webserver installieren:
sudo apt-get install lighttpd

PHP installieren:
sudo apt-get install php5-common php5-cgi php5

PHP konfigurieren:
sudo lighty-enable-mod fastcgi-php

Webserver-Dienst einmal neu starten, damit die Einstellungen wirksam werden:
sudo service lighttpd force-reload

Welchseln in des Root-Verzeichnis des Webservers (bei Bedarf, wenn sich das Root-Verzeichnis einer Distribution woanders ist, muss dieser Pfad entsprechend angepasst werden):
cd /var/www

Setzen des Besitzers und der Gruppe für das Root-Verzeichnis (TODO: Ist dieser Schritt wirklich notwendig?):
sudo chown www-data:www-data /var/www

Setzen der Berechtigungen des Root-Verzeichnis (TODO: Ist dieser Schritt wirklich notwendig?):
sudo chmod 775 /var/www

=== nginx ===
==== mit PHP5 ====

Dieses Beispiel basiert auf diesem {{Link2Forum|Topic=30909|Message=273180|LinkText=Forumsbeitrag}}.

Für die Installation des Webservers und PHP5 werden folgende Pakete benötigt:
sudo apt-get install nginx php5-fpm

Die Konfiguration für PHP muss in der entsprechenden Konfigurationsdatei vorgenommen werden:
sudo nano /etc/nginx/sites-enabled/default

Folgende Konfiguration sollte direkt funktionieren:
<pre>
server {
listen 80;
root /var/www;
index index.html index.php;
server_name localhost;
location / {
try_files $uri $uri/ /index.php?$args;
}
location ~ \.php$ {
try_files $uri =404;
fastcgi_pass unix:/var/run/php5-fpm.sock;
fastcgi_index index.php;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
include fastcgi_params;
}
}
</pre>

==== mit PHP7 ====
Ubuntu 16.04 läuft standardmäßig mit PHP7. Der Betrieb ist noch nicht zu 100% getestet und daher ohne Garantie.

Für die Installation des Webservers und PHP werden folgende Pakete benötigt:
sudo apt-get install nginx php7.0-fpm

Die Konfiguration für PHP muss in der entsprechenden Konfigurationsdatei vorgenommen werden:
sudo nano /etc/nginx/sites-enabled/default

Folgende Konfiguration sollte direkt funktionieren:
<pre>
server {
listen 80 default_server;
listen [::]:80 default_server;
root /var/www/html;
index index.php index.html index.htm index.nginx-debian.html;

server_name _;

location / {
try_files $uri $uri/ =404;
}
location ~ \.php$ {
try_files $uri =404;
fastcgi_split_path_info ^(.+\.php)(/.+)$;
fastcgi_pass unix:/run/php/php7.0-fpm.sock;
fastcgi_index index.php;
include fastcgi.conf;
fastcgi_read_timeout 600;
}
location ~* \.(js|css|png|jpg|jpeg|gif|ico|eot|otf|ttf|woff)$ {
access_log off; log_not_found off; expires 30d;
}
location = /robots.txt { access_log off; log_not_found off; }
location ~ /\. { deny all; access_log off; log_not_found off; }
}
</pre>

=== Apache2 ===

Dieses Beispiel basiert auf diesem [http://www.meintechblog.de/2015/06/smartvisu-mit-fhem-die-perfekte-visualisierung-teil-1-basics/ Blogeintrag].

Für die Installation des Webservers und PHP5 werden folgende Pakete benötigt:
sudo apt-get install apache2 php5 libapache2-mod-php5

Für das git /cleaninstall: da liegt die erweiterte smartVISU, mit Mandanten und reparierten widgets (wo nötig) - ansonsten aber unverfälscht und nicht mit widgets erweitert.

== smartVISU Installation ==

Für das Klonen (Herunterladen) wird folgendes Paket benötigt:
sudo apt-get install git

=== Verfügbare Versionen (Stand Juli 2016) ===
Bis zur V2.7 gibt es ein offizielles Release, auf dem sowohl die Dokumentation auf der Seite [http://www.smartVISU.de www.smartVISU.de] basiert, als auch das nachfolgend beschriebene smartvisu-cleaninstall, V2.7.

Die nicht offizielle V2.8 kann aus einem Entwicklungszweig heruntergeladen werden, muss aber im Anschluss um die Erweiterungen für den Betrieb mit FHEM ergänzt werden. Ob es ein offizielles Release V2.8 geben wird, ist derzeit unbekannt. Unabhängig davon wird an einem Fork in Zusammenhang für den Betrieb mit FHEM gearbeitet.

Zwar sollten alle Widgets, die auf V2.7 lauffähig sind, auch mit V2.8 kompatibel sein, dieses ist derzeit aber nicht getestet und kann nicht garantiert werden. Die Widgets müssen bei Bedarf entsprechend angepasst werden. Andererseits gibt es bereits Widgets, die V2.8 voraussetzen. Bei manchen Widgets sind die Voraussetzungen ist der Dokumentation beschrieben.

Die Unterschiede zwischen V2.7 und V2.8 sind in diesem {{Link2Forum|Topic=54506|Message=469401|LinkText=Beitrag}} zusammengefasst.

Zum jetzigen Zeitpunkt wird allerdings bereits empfohlen, bei einer Neuinstallation V2.8 zu installieren {{Link2Forum|Topic=53881|Message=471075|LinkText=(Forum)}}.

=== smartVISU-cleaninstall, V2.7 ===
==== Herunterladen ====
Für die Installation gibt es ein fertig zusammengestelltes Paket aus dem git-Repo von Jörg Herrmanns ([https://github.com/herrmannj/smartvisu-cleaninstall]).

Hierbei handelt es sich um das Original smartVISU inkl. einigen Anpassungen (fhem-Treiber, Widget-Korrekturen, ...).

Einrichten eines Installationsordners im home-Verzeichnis:
mkdir ~/install

Wechseln in das Verzeichnis:
cd ~/install

Klonen der Pakets:
git clone https://github.com/herrmannj/smartvisu-cleaninstall.git
Dabei wird der Unterordner ./smartvisu-cleaninstall angelegt, in den die Dateien heruntergeladen werden.

==== Kopieren in das Webserver Root-Verzeichnis ====
Damit der Webserver die Seiten von smartVISU zur Verfügung stellt, müssen diese an die richtige Stelle in Abhängigkeit des verwendeten Webservers und Konfiguration kopiert werden. Ggf. muss die Konfiguration des Webservers entsprechend angepasst werden.

Das neu erstellte Verzeichnis in das Root-Verzeichnis des Webservers kopieren. Dass, wie in diesem Fall angegeben, das Verzeichnis /var/www/ das richtige Verzeichnis ist, kann z.B. dadurch bestätigt werden, dass dort bereits die Default-Seite des Webservers nach der Ersteinrichtung zu finden ist. Bei Bedarf ist das Verzeichnis anzupassen.
sudo cp -rp smartvisu-cleaninstall /var/www/smartVISU

Selbstverständlich lässt dich auch ein anderes Installationsverzeichnis wählen. Die folgenden Schritte müssen dann entsprechend angepasst werden.

==== Berechtigungen setzen ====
Später wird zumindest die Konfiguration von dem, was auf dem Endgerät angezeigt werden soll, vom Endgerät aus konfiguriert. Damit dieses auch funktioniert, müssen die Berechtigungen der Seiten entsprechend angepasst werden.

Wechseln in das Verzeichnis:
cd /var/www

Setzen des Besitzers und der Gruppe für das Root-Verzeichnis von smartVISU
chown -R www-data:www-data smartVISU

Setzen der Berechtigungen für das Root-Verzeichnis "smartVISU" und alle Unterordner
chmod -R 775 smartVISU

==== ggf. Gruppenmitgliedschaft anpassen ====
Dieser Schritt ist optional und dann hilfreich, wenn man mit einem normalen user z.B. über fileZilla die Dateien austauschen möchte. Da der Schritt zulasten der Sicherheit geht, sollte man ihn nach Abschluss der Konfiguration ggf. wieder rückgängig machen.

In diesem Beispiel wird der user "pi" zur Gruppe <code>www-data</code> hinzugefügt. Verwendet man einen anderen user, muss dieses selbstverständig angepasst werden.
sudo usermod -a -G www-data pi

Rückgängig machen kann man die Gruppenzugehörigkeit über
sudo deluser pi www-data

==== Config.ini kopieren ====
Hierbei handelt es sich um die Hauptdatei mit der das Verhalten von smartVISU gesteuert wird.

Die Datei "config.ini.default" muss zu "config.ini" umbenennen oder besser kopiert werden:
sudo cp /var/www/smartVISU/config.ini.default /var/www/smartVISU/config.ini

==== Installation überprüfen ====

Beim Aufruf der Seite <code>http://<IP-Adresse>/smartVISU</code> sollte folgende Seite angezeigt werden: {{Randnotiz|RNTyp=y|RNText=
Ggf. in der php.ini (error_reporting) die Ausgabe von Warnings abschalten, wenn so was kommt wie "Notice: Undefined index..."
}}

Diese Seite wird ggf. nur einmal direkt nach der Ersteinrichtung angezeigt und ist im Folgenden nicht mehr notwendig.

[[Datei:Installation_SmartVISU.png]]

=== nicht offizielle Version, V2.8 ===

Die Beschreibung für die Installation der nicht offiziellen Version 2.8 von smartVISU basiert auf diesem [https://github.com/ddtlabs/build-smartvisu-cleaninstall Git-Eintrag] von [user=dev0].

Da man das Softwarepaket für smartVISU direkt aus dem Entwicklungszweig herunterläd, müssen die notwendigen Erweiterungen für den Betrieb mit FHEM nachträglich manuell eingefügt werden. Dabei ist der "Treiber" am wichtigsten.

Wie leicht zu erkennen, ist im folgenden Beispiel das Root-Verzeichnis des Webservers <code>/var/www/html</code> und das Verzeichnis, in das smartVISU installiert wird "sv".
Die smartVISU-Seite wird am Ende der Installation entsprechend mit <code>http://<IP-Adresse>/sv</code> aufgerufen.

Anpassen der Gruppenmitgliedschaften kann nach dem oben beschriebenen Muster durchgeführt werden.

==== Herunterladen ====

Die Dateien werden direkt aus dem Entwicklungszweig heruntergeladen.
git clone https://github.com/Martin-Gleiss/smartvisu.git

==== Kopieren in das Webserver Root-Verzeichnis ====
sudo cp -rp smartvisu /var/www/html/sv

==== Herunterladen der Erweiterungen für FHEM ====
git clone https://github.com/herrmannj/smartvisu-cleaninstall.git

==== Kopieren der Erweiterungen ====
sudo cp ./smartvisu-cleaninstall/readme.txt /var/www/html/sv/
sudo cp ./smartvisu-cleaninstall/lib/functions_config.php /var/www/html/sv/lib/
sudo cp ./smartvisu-cleaninstall/lib/includes.php /var/www/html/sv/lib/
sudo cp ./smartvisu-cleaninstall/config.ini.default /var/www/html/sv/
sudo cp ./smartvisu-cleaninstall/pages/base/configure.php /var/www/html/sv/pages/base/
sudo cp ./smartvisu-cleaninstall/driver/io_fhem.js /var/www/html/sv/driver/
sudo cp ./smartvisu-cleaninstall/driver/io_fhem.min.js /var/www/html/sv/driver/

==== Config.ini kopieren ====
sudo cp /var/www/html/sv/config.ini.default /var/www/html/sv/config.ini

==== Setzen der Berechtigungen (Besitzer und Gruppe) ====
cd /var/www/html
sudo chown -R www-data:www-data sv

== ein eigenes "Haus" anlegen ==
Nun gilt es nur noch ein eigenes "Haus" anzulegen, dass man individuell konfiguriert.

* im Ordner "''/var/www/smartVISU/pages''" einen neuen Ordner "''MeinHaus"'' anlegen.
* aus dem Ordner "''../pages/_template''" alles in den neuen Ordner ("''/var/www/smartVISU/pages/MeinHaus"'') kopieren.
* "''rooms_menu.html''" an eigene Gegebenheiten anpassen hierzu dienen die "_template-Dateien" als Orientierung.
* alle rooms anlegen durch Kopien des Beispielraumes (''room_sleeping.html'') und passende icons und Überschriften verteilen. ([http://www.smartvisu.de/docu/2.7/index.php?page=design/design_icons SmartVisu Icons])
* SmartVISU nutzt [http://twig.sensiolabs.org/ Twig] als Template engine und die Seiten bestehen aus Blöcken und Widgets, die immer in doppelten geschweiften Klammern stehen <nowiki>{{ ... }}</nowiki>
* Widget Syntax auf [http://www.smartvisu.de/docu/2.7/index.php SmartVISU Doku] nachschlagen und kopieren.
* innerhalb eines Raums zwischen {% block content %} und {% endblock %} als Beispiel folgenden Abschnitt einfügen:

<pre><nowiki>
<h1><img class="icon" src='{{ icon0 }}scene_livingroom.png'/>Wohnzimmer</h1>
<div class="preblock">
</div>
<div class="block">
<div class="set-2" data-role="collapsible-set" data-theme="c" data-content-theme="a" data-mini="true">
<div data-role="collapsible" data-collapsed="false" >
<h3>Licht</h3>
<table width="90%">
<tr><td align="left" width="100px"> {{ basic.switch('Leselampe', 'Leselampe.sw', icon1~'light_floor_lamp.png', icon0~'light_floor_lamp.png') }}</td>
<td>Leselampe</td>
</tr>
</table>
</div>
</div>
</div>
</nowiki></pre>

* Datei speichern und checken, dass die Rechte mindestens auf "755" stehen, ansonsten mit "sudo chmod 755" korrigieren.

Obwohl der folgende Teil bereits zur Einrichtung von fronthem gehört, sei es der Vollständigkeit halber des Beispiels hier trotzdem erwähnt:
* In FHEM eine fronthemDevice Detailansicht öffnen
* Nun sollten die GADs aufgelistet werden. Aus der Liste ein GAD auswählen (hier: "Leselampe.sw" wie im obigen Code-Beispiel definiert.) und die Parameter vergeben:
<pre>
device: <fhem-Name-des-fhem-devices> (in diesem Fall die Leselampe.sw)
reading: state
converter: OnOff
cmd set: state
write: ja (haken setzen)
read: ja (haken setzen)
</pre>
: "state" immer klein schreiben und speichern nicht vergessen!
* Die Settings für das Device gelten für alle Endgeräte, aber die read/write Rechte müssen für jedes Endgerät separat gesetzt werden.

== Einrichtung Endgerät ==
Als letztes greift man vom Endgerät auf die smartVISU-Seiten zu und stellt auf der Config-Seite den Treiber, IP der Servers und den Port ein.

Unter smartVISU in die Konfigurationsoberfläche wechseln <code>http://<IP-Adresse>/smartvisu/index.php?page=config</code> bzw. Zahnrad = Config-Menü:
* Im Feld "Interfaces" für pages das eigenes Haus auswählen (=Ordnername)
* Der Pagecache sollte zumindest während der Einrichtung ausgeschaltet sein.
* Im Feld I/O Connection den Treiber Fhem wählen
* Die IP-Adresse des Servers mit dem Websocket-Server eintragen
* Port 2121 einstellen
Nach allen Eintragungen die Konfiguration am unteren Ende der Seite speichern.

Damit die GADs nun im GAD-Editor auf der Detailseite von einem [[fronthem#fronthemEditor|fronthemDevice]] auftauchen, ist es jetzt wichtig, die neue Seite in smartVISU einmal aufzurufen, damit im Hintergrund die GADs übertragen werden.

Vorausgesetzt, man hat vorher alle notwendigen Schritte für die Installation und Konfiguration von fronthem ausgeführt, kann man nun smartVISU in Verbindung mit FHEM benutzen.

Im Noramlbetrieb stellt man den Pagecache auf "on"- dann werden die templates compiliert gespeichert, was die Geschwindigkeit erhöht {{Link2Forum|Topic=35960|Message=283665|LinkText=(Forum)}}.

== Troubleshooting ==

=== SSL ===

Wird derzeit nicht unterstützt {{Link2Forum|Topic=43226|Message=352115|LinkText=(Forum)}}.

=== Performanceproblem ===

Während der Entwicklung gab es mehrere Evolutionen, was die Verbindung über den Treiber angeht. Trotzdem hat auch die Platform, auf der smartVISU läuft einen gehörigen Anteil an der Reaktivität der Oberfläche. Darüber hinaus hat selbstredend die Komplexität einer Seite Einfluss auf die Geschwindigkeit.
Mit einem Webserver auf dem RPi2 scheint es noch potential nach oben zu geben, setzte man eine performantere Platform ein {{Link2Forum|Topic= 48243|Message=402427|LinkText=(Forum)}}.

=== Config-Seite anstatt der individuellen Seite ===

Es wurde vergessen, die Datei config.ini.default nach config.ini zu kopieren {{Link2Forum|Topic= 46501|Message=382426|LinkText=(Forum)}}.

=== Zugriffsprobleme mit Apache ===
Anscheinend gab es vereinzelt Zugriffsprobleme auf das smartVISU-Vereichnis, die sich aber mit dieser Erweiterung der Apache-Konfiguration beheben lies {{Link2Forum|Topic=30909|Message=239882|LinkText=(Forum)}}:

<pre>
<Directory "/var/www/smartvisu">
Options +Indexes FollowSymLinks +ExecCGI
AllowOverride AuthConfig FileInfo
Order allow,deny
Allow from all
</Directory>
</pre>

=== 404 not found ===

Wird noch nicht einmal die Seite gefunden (404), sind bereits die statischen Seiteninhalte der Webseite nicht richtig konfiguriert. Es muss sichergestellt werden, dass eine Datei im Verzeichnis von smartVISU von einem Endgerät angezeigt werden kann {{Link2Forum|Topic= 46501|Message=49524|LinkText=(Forum)}}.

=== *.js dateien ===

Sollte jemand Änderungen an den *.js Dateien bearbeiten muss man daran denken, dass in der config.ini ganz unten vereinbart wird welche Version der Datei benutzt wird {{Link2Forum|Topic=30909|Message=252375|LinkText=(Forum)}}.

=== verschiedene Devices, verschiedene Anzeigen ===

Möchte man sicherstellen, dass auf allen Endgeräten die gleiche page konfiguriert ist, verschiebt man den entsprechenden Teil in der config.ini in den <nowiki>[default]</nowiki>-Bereich.

An dieser Stelle sei eindringlich empfohlen, diese Änderung nur bei nicht laufendem Websocket durchzuführen und in jedem Falle ein Backup der Datei vorzuhalten. Bei Syntaxfehlern wird diese Datei neu erzeugt und überschreibt ohne Nachfrage die Vorversion {{Link2Forum|Topic=46541|Message=383006|LinkText=(Forum)}} {{Link2Forum|Topic=36420|Message=287038|LinkText=(Forum)}}.

=== Welcher Treiber ist installiert ===

Um zu prüfen, welche Version vom Treiber man aktuell verwendet, kann man im Browser die Konsole öffnen und nach einem page reload diesen Log-Eintrag suchen:

[io.fhem]: init [V1.10] (address= ...

In diesem Beispiel ist es Version 1.10 {{Link2Forum|Topic=35960|Message=283617|LinkText=(Forum)}}.

=== neue Clients ===

Das Anlegen neuer Clients In smartVISU müssen nicht händisch ergänzt werden. In der config.ini gibt es den parameter auto_add = true|false. Wenn dieser auf true steht, werden neue Clients automatisch in smartVISU angelegt und bekommen eine Kopie der default Einstellungen.
Im Anschluss können über die Config-Seite die individuellen Einstellungen über die smartVISU-Oberfläche konfiguriert und gespeichert werden (page, design, evtl. calender, etc) {{Link2Forum|Topic=30909|Message=236222|LinkText=(Forum)}}.

=== Ordner und Dateien ===
Auch wenn es im Normalfall nicht notwendig ist sollte, kann es manchmal sinnvoll sein, den genauen Speicherort aller Dateien und Konfigurationsdateien zu kennen und entsprechend Debugging-Trigger hinzuzufügen oder Konfigurationen direkt zu korrigieren.

Die folgenden Pfadangaben gehen davon aus, dass das Root-Verzeichnis des eingesetzten Webservers /var/www/html/ ist und smartVISU im Unterordner /var/www/html/sv liegt.

==== Konfigurationsdateien ====

Konfigurationsdatei von smartVISU:
/var/www/html/sv/config.ini

==== Ordner und Dateien ====
Dokumenten Root für smartVISU:
/var/www/html/sv/

Treiber:
/var/www/html/sv/driver/io-fhem.js

/var/www/html/sv/driver/io_fhem.min.js

Temp-Ordner:
/var/www/html/sv/temp

Template-Ordner für neue "page":
/var/www/html/sv/pages/_template

Eigener Page-Ordner
/var/www/html/sv/pages/<eigene page>

[[Kategorie:fronthem/smartVISU]]

PanStamp

2016-07-06T02:58:37Z

Joshi04: /* Anwendungsbeispiele */ Verknüpfung zu Fensterkontakt-Artkiel hinzugefügt.

{{SEITENTITEL:panStamp}}{{Infobox Hardware
|Bild=panStamp.jpg
|Bildbeschreibung=panStamp
|HWProtocol=SWAP
|HWType=Sender, Empfänger, Sensor, [[Interface]]
|HWCategory=
|HWComm=868MHz (433/915MHz)
|HWChannels=
|HWVoltage=3.3V (panStick: 5V USB)
|HWPowerConsumption=
|HWPoweredBy=Battery (panStick: USB)
|HWSize=17.7 x 30.5 mm
|HWDeviceFHEM=[http://fhem.de/commandref.html#panStamp 34_panStamp.pm] [http://fhem.de/commandref.html#SWAP 34_SWAP.pm] [http://fhem.de/commandref.html#SWAP_0000002200000003 35_SWAP_0000002200000003.pm]
|ModOwner=[http://forum.fhem.de/index.php?action=profile;u=430 Andre / justme1968]
|HWManufacturer=panStamp
}}

Dieser Artikel, gedacht als Eingangsartikel zu dem Thema, beschreibt die Zusammenhänge rund um die Hardwaremodule „panStamp“.

Zur Hardware gibt es [http://www.panstamp.com/ herstellerseitig] eine eigenen Community mit [http://www.panstamp.org/forum/ Forum] und [https://github.com/panStamp/panstamp/wiki Wiki], sowie [https://github.com/panStamp/panstamp/wiki/Downloads Downloads] auf [https://github.com/panStamp Github].

panStamps sind [[Arduino]] Clones, die ein CC1101 Funkmodul beinhalten. Mit ihnen lassen sich Sensoren und Aktoren drahtlos an FHEM anbinden. Sie lassen sich genau wie Arduinos über die Arduino IDE oder mit dem ino Kommandozeilen Binary programmieren.

Der panStamp Software Stack unterstützt einen stromsparenden Power-Down- oder Sleep-Modus für batteriebetriebene Sensoren, aus dem diese dann nur zur eigentlichen Messung und Übertragung "aufwachen".

Zur Kommunikation in einem panStamp Netzwerk dient das ''Simple Wireless Abstract Protocol'' ([https://github.com/panStamp/panstamp/wiki/Simple%20Wireless%20Abstract%20Protocol SWAP]).

== Allgemein ==
Grundsätzlich gehören zur Integration in FHEM das [[#FHEM-Module/Device Definition Files|FHEM Modul]] panStamp-Modul, das FHEM Modul SWAP und je nach [[#Anwendungsbeispiele|Anwendung]] ein spezifisches FHEM Modul SWAP_XXXXXXXXXXXXXXXX mit entsprechenden Device Definition Files.
Details über das Zusammenspiel sind in der [[#Systemübersicht|Systemübersicht]] weiter unten beschrieben.

Darüber hinaus muss ein passender [#panStamp Sketches|Sketch]] (wie eine Firmware) auf die Hardwaremodule geladen werden vergleichbar mit der Firmware für einen CUL. Der Sketch bestimmt die Funktion und ist damit abhängig von der Anwendung.
Teilweise findet man fertig kompilierte Sketches. Man kann sich aber auch den Sourcecode herunterladen, den eigenen Bedürfnissen anpassen oder gleich einen eigenen Sketch programmieren. Der Sketch wird dann innerhalb einer passenden Entwicklungsumgebung kompilieren und anschießend auf den panStamp hochladen.

Für die Einrichtung (Device Definition) innerhalb von FHEM wird für die Serverseite das IO-Device definiert, für die Seite der Aktuatoren/Sensoren das entsprechende Device.

Eine Übersicht über alle sich mit dem Thema panStamp befassenden Artikel befindet sich [[:Kategorie:PanStamp|hier]].

== Systemübersicht ==
[[Datei:Panstamp-Systemoverview.jpg|550px|thumb|panStamp Systemübersicht]]
Zum besseren Verständnis der Begrifflichkeiten und Zusammenhänge ist hier eine Systemübersicht dargestellt. Die Kommunikationskette ist wie folgt:

FHEM -> Server Hardware -> USB -> [[#panStick|panStick]] -> panStamp (mit [[#Modem-Sketch|Modem-Sketch]]) -> Funkstrecke (per SWAP-Protokoll) -> panStamp ([[#auf Board abgestimmter Sketch|angepasster Sketch]]) -> Board -> Sensoren/LED-Strip/etc.

(Ein panShield ersetzt "USB -> PanStick" durch "IO's am Rpi -> panShield").

Zum Betrieb werden mindestens 2 panStamp Hardware-Module benötigt, das panStamp FHEM-Modul als IO-Device für FHEM und das FHEM-Modul SWAP zur Integration des Funkprotokolls der panStamps.

Optional kann es noch weitere Module geben als 3. Ebene, die nach dem Schema SWAP_XXXXXXXXXXXXXXXX.pm benannt sind. Besonders bei Aktoren ist oft eine engere FHEM-Integration sinnvoll, um FHEM Konzepte wie on/off/on-for-timer direkt abzubilden und nicht mehr nur auf die SWAP Registerebene und regSet und regGet Kommandos beschränkt zu sein.
Um per autocreate automatisch das passende Modul laden zu können, müssen diese Module nach dem Schema SWAP_XXXXXXXXXXXXXXXX.pm benannt sein wobei XXXXXXXXXXXXXXXX für den jeweiligen ProductCode steht.

== panStamp Hardware ==

Die Beschreibung in folgenden bezieht sich vornehmlich auf die Hardwaremodule der Generation 1 und 1.1, sowie panStick 1.1, 1.2, die derzeit (Mitte 2016) beim Hersteller nicht mehr erworben werden können.

=== panStick/Shield ===
Als Schnittstelle zwischen FHEM Server-Hardware und dem Funkprotokoll dient entweder ein panStick mit aufgestecktem panStamp-Hardwaremodul und Modem-Sketch (USB Stick mit Sockel zum Aufstecken eines panStamp) oder ein panShield (mit integriertem panStamp und RTC) an einem Raspberry Pi.

==== panStick ====
Der panStick stellt die Verbindung zwischen dem USB-Port auf der einen Seite und dem seriellen Interface der panStamp-Hardware auf der anderen Seite dar. Der panStick wird grundsätzlich für zwei Aufgaben benötigt:
# Zur Vorbereitung einer panStamp-Hardware für den Betrieb auf einem ''Board'' wird die neue panStamp-Hardware in den panStick gesteckt, um die Programmierung (flashen des Sketch) vorzunehmen.
# Im "normalen" Betrieb steckt eine panStamp-Hardware auf dem panStick. Der so angebundene panStamp wird mit einem (bei Auslieferung des panStamps vorinstallierten) Modem-Sketch als RF-Modem verwendet und dient so der FHEM Server-Hardware als Interface zu anderen panStamp-Hardwaremodulen, zu denen über eine Funkstrecke mittels des SWAP-Protokolls kommuniziert wird. Der panStick kann auch per USB an einer anderen Serverhardware angebunden werden. Die Kommunikation zu FHEM erfolgt dann z.B. über {{Link2Forum|Topic= 12487|Message=296182l|LinkText=ser2net}} oder [[FHEM2FHEM]] über LAN.

An dieser Stelle sei darauf hingewiesen, dass umgangssprachlich im Forum häufig von panStick die Rede ist, damit aber die Definition des IO-Devices innerhalb von FHEM gemeint ist. Auch kann darunter die Kombination aus panStick, aufgesteckten panStamp und darauf befindlichem Model-Sketch gemeint sein, was gesamt dann als Funk-Interface dient. Ein panStick ohne panStamp-Hardware ist ziemlich nutzlos für die Funktion. Mit panStick ist hier also die reine Hardware als Interface zwischen USB-Port und panStamp gemeint.

==== panShield ====
Ein panShield übernimmt die gleiche Funktion wie ein panStick mit aufgestecktem panStamp, wird aber direkt an die IOs eines Raspberries angeschlossen. Da auf dem panShield der panStamp fest eingelötet ist, übernimmt dieser in der Regel nur die Funktion des IO-Interfaces wie für den panStick der "normale" Betrieb oben beschrieben.

Der Einfachheit halber wird im Folgenden nicht mehr auf den panShield im Speziellen eingegangen, da es keinen funktionalen Unterschied zur Kombination aus panStick und panStamp gibt.

=== panStamp ===
Die panStamps bilden das zentrale Glied und sind wie eingangs bereits beschrieben Arduino Clones mit einem CC1101 Funkmodul. Mit eine passenden Firmware (Sketch) ausgestattet, stecken sie entweder auf dem panStick oder den entsprechenden Boards/Platinen.

Um einen panStamp in Betrieb zu nehmen muss er unbedingt mit einer Antenne oder einem Stück Draht in der [https://github.com/panStamp/panstamp/wiki/Antennae richtigen Länge] bestückt sein. Ohne Antenne funktioniert die Übertragung nicht, auch nicht auf kurze Distanzen!

Um die Verwirrung der Namensgebung komplett zu machen, wird im Forum häufig vom "panStamps" als Device gesprochen, obwohl es eigentlich als SWAP-Devices definiert wird.

Mit der Einführung der 2. Generation (AVR2, NRG2) hat sich das Footprint der Module stark verändert. Adapterplatinen, um die Module mit neuem Footprint in Hardware mit altem zu integrieren, konnten auf Anfrage bei Daniel im Shop noch geordert werden (Stand Ende 2015; {{Link2Forum|Topic= 12487|Message=296464l|LinkText=Forum}}, {{Link2Forum|Topic= 12487|Message=392818l|LinkText=Forum}}). Langfristig ist davon auszugehen, dass diese nicht dauerhaft werden lieferbar sein. Von der Programmierung unterscheiden sich die Module jedoch nicht.

=== spezifisches "Board" ===
Im Gegenzug zum panStick, als Hardware-Interface zwischen panStamp und USB-Port des Servers, stellt das spezifische Board das Hardware-Interface zwischen panStamp-Hardware und Input/Outputs (analog/digital) dar. Das "Board" nimmt den panStamp mit dem passenden Sketch auf und setzt die Outputs der panStamp-Hardware auf die Steuerausgänge des Boards um bzw. leitet die Steuereingänge des Boards zur Auswertung an den panStamp Input weiter. Mit panStamp Input und Output sind in diesem Fall die Pins der CPU gemeint.
Entsprechend Anwendungsfall und Sketch werden die Steuereingänge und Steuerausgänge des panStamps verarbeitet. Z.B. können an ein Board Temperatur-, Feuchtigkeitssensoren oder LED-Strips angeschlossen werden. Der Sketch auf dem panStamp sollte entsprechend der Anwendung auf dem Board angepasst worden sein um nicht nur über die standardmäßig zur Verfügung stehenden Register kommunizieren zu müssen.

Das Board benötigt irgendeine Art von Stromversorgung, um den panStamp zu betreiben. Das kann im Falle eines Sensorboards und entsprechend stromsparend ausgelegtem Sketch eine Batterie sein oder wie im Falle des [[#Anwendungsbeispiele|panStamp RGBWW Board mit DMX und IR]] eine externe Stromversorgung. Speziell beim diesem Board kann die Stromversorgung sogar separat für panStamp und LEDs ausgeführt sein oder insgesamt panStamp und LEDs gemeinsam versorgen.

== panStamp Sketch ==

=== Modem-Sketch ===
Der Modem-Sketch stellt das Software-Verbindungsglied zwischen panStamp und dem SWAP-Funkprotokoll dar. Das SWAP-Protokoll wird über ein serielles Protokoll dem FHEM-Server zur Verfügung gestellt. Die Verarbeitung des SWAP-Protokolls übernimmt das gleichnamige FHEM-Modul [[#Ebene 2: 34_SWAP.pm|SWAP]]. Auf jedem panStamp (AVR, bei NRG unbekannt) ist im Auslieferungszustand der Modem-Sketch installiert. Der panStick besitzt ebenfalls eine SWAP-ID, also eine fest zugeordnete Adresse. Das ist immer die Adresse <code>0x01</code>.

Ein NRG panStamp lässt sich als Modem verwenden, wenn man den Schalter auf dem panStick auf AVR stellt ([http://www.panstamp.org/forum/archive/index.php/thread-4200.html Forum]).

=== auf Board abgestimmter Sketch ===
Ein panStamp ist auf einem entsprechenden Board installiert und übernimmt dort lokal die Schnittstelle zwischen Funkstrecke und Board.
Der Sketch stellt dabei die passende "Software" auf dem panStamp-Hardwaremodul. Der Sketch verarbeitet die über das SWAP-Protokoll versandten Nachrichten, wertet diese aus, reagiert entsprechend und setzt die Outputs des Boards. In umgekehrter Richtung wertet er die an den Inputs des Board angelegten Signale aus, verarbeitet diese und schickt sie per SWAP-Protokoll zum panStamp mit Modem-Sketch zurück.

Die Kompatibilität der bestehenden Sketches hängt stark vom Typ des panStamps und von der Entwicklungsumgebung ab. D.h. die neuesten panStamps (NRG) sind mit den neuesten Umgebungen Arduino 1.6x und unabhängig davon mit den alten Sketches meistens nicht kompatibel.

== FHEM-Module/Device Definition Files ==
Wie eingangs erwähnt erfolgt die Integration in FHEM erfolgt über eine Reihe von Modulen die im Folgenden genauer beschrieben werden. Zusammengefasst gibt es 3 Ebenen mit der Ergänzung eines Konfigurationsfiles in XML-Format. {{Link2Forum|Topic= 13890 |Message=121689 }}

=== Ebene 1: 34_panStamp.pm ===
Das Modul ist dazu da, Nachrichten aus dem Funknetzwerk, die von einem panStamp mit Modem-Sketch auf einem panStick emfangen werden, FHEM zur Verfügung zu stellen und umgekehrt. Alle eintreffenden SWAP-Pakete werden direkt an FHEM durchgereicht und im SWAP-Modul verarbeitet.

Im moduleigenen [[panStamp (Modul)|Artikel]] ist die Einrichtung des IO-Devices innerhalb von FHEM beschrieben.

=== Ebene 2: 34_SWAP.pm ===
Das Modul implementiert das SWAP Protokoll das zwischen den panStamps gesprochen wird. Darüber werden die auf den entsprechenden Boards/Platinen steckenden panStamp innerhalb von FHEM als TYPE SWAP_<ProductCode> definiert.

Das FHEM-Modul SWAP ermöglicht die generische Integration beliebiger panStamp Sensoren und Aktoren in FHEM, und ist in einem eigenen Artikel [[SWAP]] erklärt. Für diese werden hier die allgemeinen Grundfunktionen beschrieben, die bei jedem SWAP-Device funktionieren. Die spezifischen Kommandos und Attribute, die durch die 3. Modulebene in Abhängigkeit des ProductCode zur Verfügung stehen, werden in den Wiki-Artikeln der jeweiligen Module beschrieben.

Um die Verwirrung komplett zu machen, wird im Forum meistens von "panStamps" gesprochen, obwohl es eigentlich SWAP-Devices sind.

=== Ebene 3: SWAP_XXXXXXXXXXXXXXXX.pm ===
[[Datei:SWAP_0000002200000003.png|thumb|rechts|RGB LED Driver Board]]
Besonders bei Aktoren ist oft eine engere FHEM-Integration sinnvoll, um FHEM Konzepte wie on/off/on-for-timer direkt abzubilden und nicht mehr nur auf die Registerebene und regSet und regGet Kommandos beschränkt zu sein. Mit dieser dritten Modulebene ist es auch für Aktoren wie Schalter/Dimmer/... sehr einfach, diese in FHEM zu integrieren.

Wenn die Namenskonvention SWAP_<ProductCode> für diese Module eingehalten wird, funktioniert auch das autocreate sofern das Modul in FHEM bekannt ist.

Um per autocreate automatisch das passende Modul laden zu können, müssen diese Module nach dem Schema SWAP_XXXXXXXXXXXXXXXX.pm benannt sein wobei XXXXXXXXXXXXXXXX für den jeweiligen ProductCode steht. Ein Beispiel für das RGB-Board dafür ist das Modul [[#Anwendungsbeispiele|35_SWAP_0000002200000003.pm]].

=== Device Definition Files ===
Ein XML File was die Ein- und Ausgänge der panStamps beschreibt. Durch diese Datei wird dem FHEM-Modul mitgeteilt wie die Readings zu bennenen sind, welche Werte die Readings haben können und ob die Readings/Register nur ausgelesen werden dürfen, oder auch beschrieben werden können. Im [https://github.com/panStamp/panstamp/wiki/Device-Definition-Files Wiki des Herstellers] ist der Aufbau des Device Definition Files beschrieben. Wenn für einen End Point eine Unit angegeben ist, mit entsprechendem Faktor, dann erstellt das SWAP-Modul automatisch ein passendes userReadings mit der angegebenen Umrechnung.

== panStamps konfigurieren und in Betrieb nehmen ==

Die Inbetriebnahme ist grundsätzlich in die Einrichtung des IO-Devices und die Einrichtung des entfernten Hardwaremoduls (Sensor/Aktuator) zu unterscheiden.

Auf die Einrichtung des IO-Devices ist [[#Ebene 1: 34_panStamp.pm|hier]] bereits verwiesen.

Für die Einrichtung des entfernten Hardwaremoduls müssen im groben folgende Schritte erfolgen:
# Vorbereiten einer [[panStamp_Programmierung|Entwicklungsumgebung]], kompilieren und hochladen der Firmware
# Aufstecken des programmierten panStamps auf das Board
# Mit Strom versorgen und von Autocreate einrichten lassen
# Attribute, Namen, Userreading des neuen SWAP-Device nach Bedarf anpassen

=== während der Einrichtung zu berücksichtigen ===
'''Info: Das SWAP Modul unterstützt [[autocreate]]. Bei der Inbetriebnahme ist autocreate zu aktivieren!'''

Neue panStamps sollten nur Einer nach dem Anderen in Betrieb genommen werden, da sie zuerst mit einer eindeutigen Device-Adresse (ungleich <code>FF</code> und grösser <code>01</code>) versehen werden müssen. Bei batteriebetriebenen Sensoren sollte auch das Sendeintervall auf einen sinnvollen Wert gesetzt werden:
set <device> regSet 09 <device adresse als 2 stellige hex zahl>
set <device> regSet 0A <intervall in Sekunden als 4 stellige hex zahl>
Für panStamp-Hardware im Power-Down-Modus werden diese Kommandos in eine Warteschlange gestellt und übertragen, sobald die panStamp-Hardware seine Initialisierungssequenz durchläuft. Hierzu ist nach Absetzen der Kommandos aus FHEM die Reset-Taste an der panStamp-Hardware zu drücken oder die Stromquelle erneut zu verbinden.

Das SWAP-Modul versucht, panStamp-Hardware mit der Default Adresse <code>FF</code> automatisch auf die erste freie Adresse im Bereich <code>F0</code>-<code>FE</code> zu ändern. Automatisch gesetzte Werte sollten danach manuell auf die jeweilige Installation angepasst werden.
Für batteriebetriebene panStamp-Hardware (genauer: Hardware die den Power-Down-Modus unterstützen) wird das Default Sendeintervall von <code>FFFF</code> zu <code>0384</code> (900 Sekunden) geändert.
Es gibt mit bestimmten panStamp lib Versionen das Problem das ein Wert von <code>FFFF</code> in Systemregister <code>0A</code> zum Überlauf führt und dann ununterbrochen SWAP Nachrichten gesendet werden. Im FHEM Modul wird versucht das abzufangen. Das funktioniert auf manchen langsamen Host-Systemen (z.B. FritzBox) nicht, weil der panStamp so schnell sendet, dass FHEM so mit dem Abarbeiten beschäftigt ist, dass es selber nicht zum Senden kommt.
Zur Abhilfe kann im Sketch in setup() ganz am Anfang ein
EEPROM.write(EEPROM_TX_INTERVAL, 0x55);
EEPROM.write(EEPROM_TX_INTERVAL+1, 0x55);
eingefügt werden. Der Sketch ist dann zu flashen und wenn der Sketch einmal durchgelaufen ist, können diese beiden Zeilen wieder entfernen werden und der panStamp muss noch mal geflasht werden. Ansonsten wird die Adresse bei jedem Start erneut auf <code>5555</code> gesetzt.

=== Beispiel für Kurzentschlossene anhand der Einrichtung für das RGB-Board ===

* Ein panStamp-Hardwaremodul wird in einen panStick gesteckt und der panStick für die Programmierung z.B. unter Windows installiert. Selbstverständlich kann ein panStamp-Hardwaremodul auch über diverse andere Möglichkeiten und unter diversen anderen Betriebssystemen und über diverse andere Schnittstellen programmiert werden.
* Arduino IDE vorbereiten (libs hinzufügen, Board auswählen, etc.).
* Ein Sketch wird in der Arduino IDE entsprechend konfiguriert, kompiliert und auf dem panStamp-Hardwaremodul hochgeladen.
* Das programmierte panStamp-Hardwaremodul, aus dem panStick, in das panStamp_RGBWW_Board stecken.
* Ein panStamp-Hardwaremodul mit Modem-Sketch in den panStick stecken und an den FHEM-Host stecken.
* IO-Device unter FHEM einrichten, wenn nicht durch autocreate automatisch geschehen.
* panStamp_RGBWW_Board mit Strom versorgen und ggf. einmal Reset-Knopf drücken. Dann sollte, falls autocreate aktiv ist, das SWAP-Device automatisch eingerichtet werden.
* SWAP-Device in FHEM an Gegebenheiten anpassen.

== Anwendungsbeispiele ==

Es gibt bereits selbst entwickelte Hardware und Software auf Basis der panStamp Hardware und dem SWAP Protokoll:
* [[panStamp Umweltsensor|Umweltsensor]]
* [[Bodenfeuchtesensor]]
* [[panStamp Innenraumsensor|Innenraumsensor]]
* [[panStamp RGBWW Board mit DMX und IR|RGBWW Board mit DMX und IR]]
* Lithium Battery Charging Board für den panStamp AVR2 [https://forum.fhem.de/index.php/topic,12487.msg349328.html#msg349328]
* [[panStamp FensterkontaktSensor|Fensterkontaktsensor]]

== Bekannte Probleme ==

* Beim Systemstart werden einige Perl-Warnings ins Log geschrieben, die aber die Funktion der Module nicht beeinträchtigen.

* Beim Systemstart wird eine SWAP-Broadcast Nachricht verschickt, die von allen empfangsbereiten panStamps beantwortet wird. Dieses führt bei häufig schnell bei kurz aufeinanderfolgenden Systemstarts zur Überschreitung des Transmit Limits im Rahmen der 1%-Regel für das verwendete Frequenzband.

Weitere Troubleshooting Hinweise finden sich [[SWAP#Trouble Shooting|hier]]

= Weblinks =
* [http://www.panstamp.com/home panStamp] panStamp Hersteller

[[Kategorie:panStamp]]
[[Kategorie:Interfaces]]

Diskussion:Installation Fronthem

2016-06-26T17:06:26Z

Joshi04:

Hallo Joshi04!
Sollte die Weiterleitung nicht besser bestehen bleiben? Der alte Seitentitel könnte bspw. aus dem Forum verlinkt sein. Ohne Weiterleitung landet man dann im "Nichts".
Gruß, --[[Benutzer:Krikan|Christian]] ([[Benutzer Diskussion:Krikan|Diskussion]]) 23:26, 25. Jun. 2016 (CEST)
<hr>
:Hallo Christian, da hast Du natürlich recht. Ich denke, grundsätzlich müssen wir abwägen zwischen 1. Die Struktur des Wiki ist gut genug, dass auch ein toter Link aus dem Forum keine größere Hürde darstellt und 2. Wir behalten die "Dateileichen" in Form der Weiterleitungen, so dass auch die ältesten Verlinkungen noch funktionieren.
:MM ist der Forumsbereich noch relativ jung. Derzeit glaube ich ca. 4000 Posts, davon die Hälfte in nur einem Thread, den sich glaube ich niemand mehr durchlesen mag, wenn er bei der Suche im Wiki nach einem der Hauptbegriffe gleich fündig wird. Wenn das ganze mal so eingefahren ist, wie andere Bereiche, würde ich Dir in jedem Falle recht geben. Noch sehe ich allerdings die Gelegenheit, mit relativ wenig "zerbrochenem Geschirr" es in die richtige Richtung zu lenken. Mein Favorit wäre daher derzeit 2.: Zöpfe abschneiden.
:Das ist aber nur ein Vorschlag und ich kann auch damit leben, den Löscheintrag wieder zu entfernen. Entscheide gerne selbst nach Deiner Überzeugung.
:Die überarbeiteten Artikel "fronthem Installation", "smartVISU" und "smartVISU Installation" sind fast fertig, aber erst sinnvoll in Summe Online zu gehen.
:Schöne Grüße, --[[Benutzer:joshi04|John]] ([[Benutzer Diskussion:joshi04|Diskussion]]) 11:05, 26. Jun. 2016 (CEST)
<hr>
::Hallo John
::Persönlich versuche ich jegliche Links (Seitentitel/Überschriften usw.) immer zu erhalten; auch wenn sie mir überhaupt nicht mehr gefallen (und ich sie teilweise auch noch selbst verbrochen habe ;-) ). Kann Deine Argumente aber nachvollziehen. Zu Deinem Thema selbst (fronthem/smartVISU) bin ich aber eigentlich überfragt, da ich davon keine Ahnung habe. Darum musst Du letztlich selbst entscheiden, was sinnvoll ist oder einer der Wiki-Admins gibt eine Richtung vor.
::Gruß (und danke für Deine Mitarbeit hier!) --[[Benutzer:Krikan|Christian]] ([[Benutzer Diskussion:Krikan|Diskussion]]) 16:45, 26. Jun. 2016 (CEST)
<hr>
:::Hallo Christian,<br />
:::hmm, um eine Entscheidung zu treffen, fühle ich mich nicht wichtig genug. Und ich kann auch mit jeder Entscheidung gut leben, ist eine Frage der Philosophie. Zu meinen Argumenten kann ich nichts hinzufügen. Wenn Du nicht entscheiden magst, wäre das etwas für einen Admin, die Richtung vorzugeben.<br />
:::Was mir noch aufgefallen ist, dass auf der Seite der Löschkandidaten die Umleitungsziele und nicht die Umleitungsseiten verlinkt sind. Wenn hier jemand löscht, sollte er aufpassen, nur die Umleitungen zu entfernen und nicht die Artikel selbst. Und vielen Dank für die Umbenennung im Forum.<br />
:::Und ich freue mich, wenn ich auch etwas beitragen kann. Bei Programmieren hapert es nämlich. :) <br />
:::[[Benutzer:Joshi04|Joshi04]] ([[Benutzer Diskussion:Joshi04|Diskussion]]) 19:04, 26. Jun. 2016 (CEST)

Diskussion:Installation Fronthem

2016-06-26T17:04:02Z

Joshi04:

Hallo Joshi04!
Sollte die Weiterleitung nicht besser bestehen bleiben? Der alte Seitentitel könnte bspw. aus dem Forum verlinkt sein. Ohne Weiterleitung landet man dann im "Nichts".
Gruß, --[[Benutzer:Krikan|Christian]] ([[Benutzer Diskussion:Krikan|Diskussion]]) 23:26, 25. Jun. 2016 (CEST)
<hr>
:Hallo Christian, da hast Du natürlich recht. Ich denke, grundsätzlich müssen wir abwägen zwischen 1. Die Struktur des Wiki ist gut genug, dass auch ein toter Link aus dem Forum keine größere Hürde darstellt und 2. Wir behalten die "Dateileichen" in Form der Weiterleitungen, so dass auch die ältesten Verlinkungen noch funktionieren.
:MM ist der Forumsbereich noch relativ jung. Derzeit glaube ich ca. 4000 Posts, davon die Hälfte in nur einem Thread, den sich glaube ich niemand mehr durchlesen mag, wenn er bei der Suche im Wiki nach einem der Hauptbegriffe gleich fündig wird. Wenn das ganze mal so eingefahren ist, wie andere Bereiche, würde ich Dir in jedem Falle recht geben. Noch sehe ich allerdings die Gelegenheit, mit relativ wenig "zerbrochenem Geschirr" es in die richtige Richtung zu lenken. Mein Favorit wäre daher derzeit 2.: Zöpfe abschneiden.
:Das ist aber nur ein Vorschlag und ich kann auch damit leben, den Löscheintrag wieder zu entfernen. Entscheide gerne selbst nach Deiner Überzeugung.
:Die überarbeiteten Artikel "fronthem Installation", "smartVISU" und "smartVISU Installation" sind fast fertig, aber erst sinnvoll in Summe Online zu gehen.
:Schöne Grüße, --[[Benutzer:joshi04|John]] ([[Benutzer Diskussion:joshi04|Diskussion]]) 11:05, 26. Jun. 2016 (CEST)
<hr>
::Hallo John
::Persönlich versuche ich jegliche Links (Seitentitel/Überschriften usw.) immer zu erhalten; auch wenn sie mir überhaupt nicht mehr gefallen (und ich sie teilweise auch noch selbst verbrochen habe ;-) ). Kann Deine Argumente aber nachvollziehen. Zu Deinem Thema selbst (fronthem/smartVISU) bin ich aber eigentlich überfragt, da ich davon keine Ahnung habe. Darum musst Du letztlich selbst entscheiden, was sinnvoll ist oder einer der Wiki-Admins gibt eine Richtung vor.
::Gruß (und danke für Deine Mitarbeit hier!) --[[Benutzer:Krikan|Christian]] ([[Benutzer Diskussion:Krikan|Diskussion]]) 16:45, 26. Jun. 2016 (CEST)

Hallo Christian,<br />
hmm, um eine Entscheidung zu treffen, fühle ich mich nicht wichtig genug. Und ich kann auch mit jeder Entscheidung gut leben, ist eine Frage der Philosophie. Zu meinen Argumenten kann ich nichts hinzufügen. Wenn Du nicht entscheiden magst, wäre das etwas für einen Admin, die Richtung vorzugeben.<br />
Was mir noch aufgefallen ist, dass auf der Seite der Löschkandidaten die Umleitungsziele und nicht die Umleitungsseiten verlinkt sind. Wenn hier jemand löscht, sollte er aufpassen, nur die Umleitungen zu entfernen und nicht die Artikel selbst.<br />
Und ich freue mich, wenn ich auch etwas beitragen kann. Bei Programmieren hapert es nämlich. :) <br />
[[Benutzer:Joshi04|Joshi04]] ([[Benutzer Diskussion:Joshi04|Diskussion]]) 19:04, 26. Jun. 2016 (CEST)

SmartVISU/Universelle ZeitSchaltUhr (UZSU)

2016-06-26T14:56:22Z

Joshi04: Kategorie geändert

{{SEITENTITEL:smartVISU/Universelle ZeitSchaltUhr (UZSU)}}
Dieser Artikel behandelt die Einrichtung einer universellen Zeitschaltuhr innerhalb des Frontends [[smartVISU]].

Es existiert ein Widget für eine universelle ZeitSchaltUhr auf GitHub unter https://github.com/herrmannj/smartvisu-widgets beziehen

Dank dafür an mworion!

Man muss dazu die uzsu_widget.html in das eigene Verzeichnis in ../pages/.. kopieren und die visu.js und die visu.css in seine Installation integrieren (Achtung, wenn die beiden Dateien schon bestehen, dann muss man das manuell zusammenkopieren!)

Das Widget kann in SmartVISU-Seiten wie gewohnt eingebunden werden:

(für ein Ergebnis, das der Benutzer direkt eintippen kann, z.B. 'on' oder 'off')

<nowiki>
{% import "widget_uzsu.html" as visu %}

{{ visu.uzsu_icon('UZSUtxt', gad_uzsu, '', '', '', '', 'text') }}
</nowiki>

oder Text als Dropdown:

<nowiki>
{% import "widget_uzsu.html" as visu %}

{{ visu.uzsu_icon('UZSUtxt', gad_uzsu, '', '', '', '', 'text', ['an', 'aus']) }}
</nowiki>

oder (für eine einzugebende Ziffer zwischen 0 und 100)
<nowiki>
{% import "widget_uzsu.html" as visu %}

{{ visu.uzsu_icon('UZSUnum', gad_uzsu, '', '', '', '', 'num', [0, 100]) }}
</nowiki>

oder (für ein Ergebnis {0,1}, das aber als flip mit 'an' und 'aus' angezeigt wird)
<nowiki>
{% import "widget_uzsu.html" as visu %}

{{ visu.uzsu_icon('UZSUnum', gad_uzsu, '', '', '', '', 'bool', ['an', 'aus']) }}
</nowiki>

Um die Antwort des Widgets in fhem zu verarbeiten, benötigt man

1. je ein Reading uzsu an dem zu schaltenden Device, das man mit

<nowiki>
setreading <device> uzsu {}
</nowiki>

erzeugen MUSS.

2. eine Anbindung des UZSU-GAD per UZSU Converter aus der 99_fronthemUtils.pm (s. u.) an das Reading uzsu des zu schaltenden Device read und write in fhem

3. Den sonstigen UZSU Code aus der 99_FronthemUtils.pm aus dem http://github.com/herrmannj/fronthem (ist bei aktuellem fronthem alles schon drin)

Dieser Code erzeugt aus den Einstellungen im Widget entsprechende WeekdayTimer in fhem und löscht und erstellt neu bei jeder Änderung in SmartVISU.

4. Die Funktion muss getriggert werden. Dazu ist ein notify nötig, das auf die Veränderung der uzsu Readings reagiert:

<nowiki>

define UZSU notify .*:uzsu:.* { UZSU_execute($NAME, $EVTPART1) }

</nowiki>

5. GAD Editor Einstellungen:

<nowiki>
mode: item
device: <DEIN_DEVICE>
reading: uzsu
converter: UZSU
cmd set: uzsu
</nowiki>

Voila!

[[Kategorie: fronthem/smartVISU]]

SmartVISU/lichtSzene

2016-06-26T14:54:18Z

Joshi04: Kategorie hinzugefügt

{{SEITENTITEL:smartVISU/lichtSzene}}

mit dem folgenden Code lässt sich eine Auswahl für Lichtszenen in smartVisu / fhem erstellen.

So soll es aussehen:

[[Datei:Smartvisu_Lichtszene_radio_buttons.png|600px|thumb|left|Screenshot Frontend smartVISU]]

Die Radio Buttons sollen dabei in einem Raum folgende Lichtszenen steuern:

* automatische Beleuchtung
* Fernsehen
* Arbeitsbeleuchtung
* Essen
* Party
* volle Beleuchtung
* Weihnachtsbeleuchtung
* alles Aus

Die gewünschte Funktionalität ist dabei das sich die Lichtszenen umschalten lassen. Wenn eine bereits aktivierte Funktion nochmal betätigt wird entspricht das "aus". Die Weihnachtsbeleuchtung soll sich unabhängig von den anderen Beleuchtungs Szenen aktivieren oder deaktivieren lassen.

Als Referenz ein Link auf die Online Hilfe von sv zu den hierfür eingesetzten button (typ dual)
[http://www.smartvisu.de/docu/2.7/index.php?page=basic/widget_basic.dual]

Der Screenshot oben wird mit diesem code in sv erzeugt:
<nowiki>
<div class="cells">
<div class="cell4 ui-btn-up-a">Lichtszene</div>
<div class="cell6 ui-btn-up-a">
<span data-role="controlgroup" data-type="horizontal">
{{ basic.dual('light.a', 'wz.light.szene.auto', icon1~'time_automatic.png', icon0~'time_automatic.png', 'auto', 'off', 'midi') }}
{{ basic.dual('light.b', 'wz.light.szene.tv', icon1~'it_television.png', icon0~'it_television.png', 'tv', 'off', 'midi') }}
{{ basic.dual('light.c', 'wz.light.szene.work', icon1~'light_ceiling_light.png', icon0~'light_ceiling_light.png', 'work', 'off', 'midi') }}
{{ basic.dual('light.d', 'wz.light.szene.eat', icon1~'light_dinner_table.png', icon0~'light_dinner_table.png', 'eat', 'off', 'midi') }}
{{ basic.dual('light.e', 'wz.light.szene.party', icon1~'light_party.png', icon0~'light_party.png', 'party', 'off', 'midi') }}
{{ basic.dual('light.f', 'wz.light.szene.full', icon1~'light_light_dim_100.png', icon0~'light_light_dim_100.png', 'full', 'off', 'midi') }}
{{ basic.dual('light.g', 'wz.light.szene.xmas', icon1~'scene_x-mas.png', icon0~'scene_x-mas.png', 'on', 'off', 'midi') }}
{{ basic.dual('light.h', 'wz.light.szene.off', icon1~'control_on_off.png', icon0~'control_on_off.png', 'off', 'off', 'midi') }}
</span>
</div>
</div>
</nowiki>

In diesem Beispiel wird in fhem dazu ein dummy erzeugt über den die Lichtszenen gesteuert werden. Natürlich gäbe es auch alternative Umsetzungen, bspw mit lightscene)

Der dummy (name wz.licht.scene) bekommt diese setlist
<nowiki>
define wz.licht.scene dummy
attr wz.licht.scene setList off auto tv eat work party full
</nowiki>

[[Datei:fronthem_gadeditor_lichtszene.png|600px|thumb|right|ronthem Editor]]

Nach einem reload der sv Seite werden die oben definierten GADs vom fronthemDevice in fhem angezeigt (hier mit bereits definierten GAD). Jetzt müssen die buttons (über ihr GAD) mit der fhem Funktionalität verbunden werden. Hier soll jeder button mit seinem Value den dummy setzen.

Mit den folgenden Einstellungen, die für jedes GAD der Button Group durchgefühert werden müssen, wird das erwünschte Verhalten erreicht. Jeder Button der Group setzt das dummy jetzt auf den den seinen "ON-VALUE" (dritt - vorletzter Wert in der definition oben). Ein weiterer Click (oder der rechte Button) setzt alles aus.

Für die Weihanchtsbeleuchtung wird unabhängig ein Steckdose geschaltet, das ist hier nicht dargestellt.

[[Kategorie: fronthem/smartVISU]]

SmartVISU/lichtSzene

2016-06-26T14:52:34Z

Joshi04: Joshi04 verschob die Seite SmartVisu/lichtSzene nach SmartVISU/lichtSzene: Anpassung an die offizielle Schreibweise

mit dem folgenden Code lässt sich eine Auswahl für Lichtszenen in smartVisu / fhem erstellen.

So soll es aussehen:

[[Datei:Smartvisu_Lichtszene_radio_buttons.png|600px|thumb|left|Screenshot Frontend smartVISU]]

Die Radio Buttons sollen dabei in einem Raum folgende Lichtszenen steuern:

* automatische Beleuchtung
* Fernsehen
* Arbeitsbeleuchtung
* Essen
* Party
* volle Beleuchtung
* Weihnachtsbeleuchtung
* alles Aus

Die gewünschte Funktionalität ist dabei das sich die Lichtszenen umschalten lassen. Wenn eine bereits aktivierte Funktion nochmal betätigt wird entspricht das "aus". Die Weihnachtsbeleuchtung soll sich unabhängig von den anderen Beleuchtungs Szenen aktivieren oder deaktivieren lassen.

Als Referenz ein Link auf die Online Hilfe von sv zu den hierfür eingesetzten button (typ dual)
[http://www.smartvisu.de/docu/2.7/index.php?page=basic/widget_basic.dual]

Der Screenshot oben wird mit diesem code in sv erzeugt:
<nowiki>
<div class="cells">
<div class="cell4 ui-btn-up-a">Lichtszene</div>
<div class="cell6 ui-btn-up-a">
<span data-role="controlgroup" data-type="horizontal">
{{ basic.dual('light.a', 'wz.light.szene.auto', icon1~'time_automatic.png', icon0~'time_automatic.png', 'auto', 'off', 'midi') }}
{{ basic.dual('light.b', 'wz.light.szene.tv', icon1~'it_television.png', icon0~'it_television.png', 'tv', 'off', 'midi') }}
{{ basic.dual('light.c', 'wz.light.szene.work', icon1~'light_ceiling_light.png', icon0~'light_ceiling_light.png', 'work', 'off', 'midi') }}
{{ basic.dual('light.d', 'wz.light.szene.eat', icon1~'light_dinner_table.png', icon0~'light_dinner_table.png', 'eat', 'off', 'midi') }}
{{ basic.dual('light.e', 'wz.light.szene.party', icon1~'light_party.png', icon0~'light_party.png', 'party', 'off', 'midi') }}
{{ basic.dual('light.f', 'wz.light.szene.full', icon1~'light_light_dim_100.png', icon0~'light_light_dim_100.png', 'full', 'off', 'midi') }}
{{ basic.dual('light.g', 'wz.light.szene.xmas', icon1~'scene_x-mas.png', icon0~'scene_x-mas.png', 'on', 'off', 'midi') }}
{{ basic.dual('light.h', 'wz.light.szene.off', icon1~'control_on_off.png', icon0~'control_on_off.png', 'off', 'off', 'midi') }}
</span>
</div>
</div>
</nowiki>

In diesem Beispiel wird in fhem dazu ein dummy erzeugt über den die Lichtszenen gesteuert werden. Natürlich gäbe es auch alternative Umsetzungen, bspw mit lightscene)

Der dummy (name wz.licht.scene) bekommt diese setlist
<nowiki>
define wz.licht.scene dummy
attr wz.licht.scene setList off auto tv eat work party full
</nowiki>

[[Datei:fronthem_gadeditor_lichtszene.png|600px|thumb|right|ronthem Editor]]

Nach einem reload der sv Seite werden die oben definierten GADs vom fronthemDevice in fhem angezeigt (hier mit bereits definierten GAD). Jetzt müssen die buttons (über ihr GAD) mit der fhem Funktionalität verbunden werden. Hier soll jeder button mit seinem Value den dummy setzen.

Mit den folgenden Einstellungen, die für jedes GAD der Button Group durchgefühert werden müssen, wird das erwünschte Verhalten erreicht. Jeder Button der Group setzt das dummy jetzt auf den den seinen "ON-VALUE" (dritt - vorletzter Wert in der definition oben). Ein weiterer Click (oder der rechte Button) setzt alles aus.

Für die Weihanchtsbeleuchtung wird unabhängig ein Steckdose geschaltet, das ist hier nicht dargestellt.

SmartVISU/IconHighlights in Menus

2016-06-26T14:51:49Z

Joshi04: Kategorie hinzugefügt

{{SEITENTITEL:smartVISU/IconHighlights in Menus}}

Mit dem folgenden Code lassen sich, zum Beispiel innerhalb vom Hauptmenu oder in der Raumübersicht die Icons farbig kennzeichnen.

<nowiki>
<a href="index.php?page=room_living">
<img class="icon" src="{{ page == 'room_living' ? icon1 : icon0 }}scene_livingroom.png"/><h3>Wohnzimmer</h3>
</nowiki>

[[Kategorie: fronthem/smartVISU]]

SmartVISU/IconHighlights in Menus

2016-06-26T14:50:24Z

Joshi04: Joshi04 verschob die Seite SmartVisu/IconHighlights in Menus nach SmartVISU/IconHighlights in Menus: Anpassung an die offizielle Schreibweise

Mit dem folgenden Code lassen sich, zum Beispiel innerhalb vom Hauptmenu oder in der Raumübersicht die Icons farbig kennzeichnen.

<nowiki>
<a href="index.php?page=room_living">
<img class="icon" src="{{ page == 'room_living' ? icon1 : icon0 }}scene_livingroom.png"/><h3>Wohnzimmer</h3>
</nowiki>

SmartVISU/fritz!box via TR-064

2016-06-26T14:49:28Z

Joshi04: Kategorie hinzugefügt

{{SEITENTITEL:smartVISU/fritz!box via TR-064}}

==fritz!box_via_TR-064==
Download: https://github.com/herrmannj/smartvisu-widgets/tree/master/phoneservice/lib/phone/service

Dieses Widget verwendet TR-064 zum Auslesen der Anruferliste. Es ist ein Protokoll das nahe am UPnP Standard ist (SOAP).
Getestet wurde es mit den FritzOS Versionen 6.03 und 6.20.
Dieses Widget wird unter der Smartvisu-Config Seite ausgewählt und es muss gegebenenfalls Benutzer und Passwort der Fritzbox in SmartVisu angegeben werden.
Wichtig ist, dass in der Fritzbox unter ->Heimnetz->Netzwerk->Netzwerkeinstellungen->"Zugriff für Anwendungen zulassen" aktiviert ist.

[[Kategorie: fronthem/smartVISU]]

SmartVISU/fritz!box via TR-064

2016-06-26T14:47:38Z

Joshi04: Joshi04 verschob die Seite SmartVisu/fritz!box via TR-064 nach SmartVISU/fritz!box via TR-064: Anpassung an die offizielle Schreibweise

==fritz!box_via_TR-064==
Download: https://github.com/herrmannj/smartvisu-widgets/tree/master/phoneservice/lib/phone/service

Dieses Widget verwendet TR-064 zum Auslesen der Anruferliste. Es ist ein Protokoll das nahe am UPnP Standard ist (SOAP).
Getestet wurde es mit den FritzOS Versionen 6.03 und 6.20.
Dieses Widget wird unter der Smartvisu-Config Seite ausgewählt und es muss gegebenenfalls Benutzer und Passwort der Fritzbox in SmartVisu angegeben werden.
Wichtig ist, dass in der Fritzbox unter ->Heimnetz->Netzwerk->Netzwerkeinstellungen->"Zugriff für Anwendungen zulassen" aktiviert ist.

SmartVISU/ical

2016-06-26T14:46:45Z

Joshi04: Kategorie hinzugefügt

Um einen Kalender in [[SmartVisu]] mit dem Widget widget_ical einzubinden, ist folgendes zu tun:

* Die Datei iCalcreator.class.php aus dem Paket http://kigkonsult.se/downloads/index.php#iCalcreator unter einem beliebigen Pfad ablegen, der aber in der ical.php eingetragen werden muss.
* Ablegen der Datei ical.php in das Verzeichnis /smartVISU/lib/calendar/service
* Ablegen der Datei widget_ical.html in das Homeverzeichnis der eigenen Seite z.b. /smartVISU/pages/fhem
* Definition der Kalender findet in den Settings statt. Die Kalender werden wie folgt definiert:
: - wie bisher nur die Url
: <code><nowiki>http://xxx:xxx@xxx.xxx.xxx.xxx/davical/caldav.php/norbert/calendar</nowiki></code>
: - die Url mit Parameter Farbe und Icon
: <code><nowiki>http://xxx:xxx@xxx.xxx.xxx.xxx/davical/caldav.php/norbert/calendar(Default Farbe,Default Icon)</nowiki></code>
: - die Url mit Parameter Farbe
: <code><nowiki>http://xxx:xxx@xxx.xxx.xxx.xxx/davical/caldav.php/norbert/calendar(Default Farbe)</nowiki></code>
: - die Url mit Parameter Icon
: <code><nowiki>http://xxx:xxx@xxx.xxx.xxx.xxx/davical/caldav.php/norbert/calendar(,Default Icon)</nowiki></code>
: - zwei Kalenderurls mit unterschiedlichen Parametern
: <code><nowiki>http://xxx:xxx@xxx.xxx.xxx.xxx/davical/caldav.php/norbert/calendar(,message_garbage);http://xxx:xxx@xxx.xxx.xxx.xxx/davical/caldav.php/norbert/Geburtstage(#ff69b4,scene_party)</nowiki></code>
: - eine lokale Url
: <code><nowiki>file:/tmp/calendar.ics</nowiki></code>
: - zwei Kalenderurls eine lokale und eine auf einem Caldav/Webserver
: <code><nowiki>file:/tmp/calendar.ics(,message_garbage);http://xxx:xxx@xxx.xxx.xxx.xxx/davical/caldav.php/norbert/Geburtstage(#ff69b4,scene_party)</nowiki></code>
: Die Icons sind die Namen der png-Dateien ohne .png. Wenn keine Parameter, für Farbe und Icon mitgegeben werden und auch keine in den Terminen hinterlegt sind, wird ein Standardicon und eine Standardfarbe gesetzt. Das setzen dieser Parameter pro Termin erfolgt im Beschreibungsfeld des jeweiligen Termin.
:Bei allen abgelegten Dateien muss auf die Rechte geachtet werden. Es sollten die gleichen User/Group-Rechte verwendet werden, wie auch bei den Dateien im pages Ordner.
* Einbinden es Kalenders auf einer SV-Seite:
: <code>{% import "widget_ical.html" as calendar %}</code>
: <code><nowiki>{{ calendar.list('calendarlist', 'Termine', 6, 21) }}</nowiki></code>
: Die erste Zahl (6) ist die Anzahl der Termine die aufgelistet werden. Die zweite Zahl (21) ist die Anzahl der Tage, die im Kalender in die Zukunft geprüft wird, ob sich ein Termin wiederholt.

Quelle und Download benötigter Dateien: {{Link2Forum|Topic=35831}}

[[Kategorie: fronthem/smartVISU]]

SmartVISU/ical

2016-06-26T14:44:04Z

Joshi04: Joshi04 verschob die Seite SmartVisu/ical nach SmartVISU/ical: Anpassung an die offizielle Schreibweise

SmartVISU Installation

2016-06-26T14:41:11Z

Joshi04: Komplette Überarbeitung/neuer Artikel im Rahmen des gesamten Themengebiets fronthem/smartVISU

{{SEITENTITEL:smartVISU Installation}}

Dieser Artikel beschreibt die Installation des Web-Frontends [[smartVISU]] und berücksichtigt mehrerer Alternativen für unterschiedliche Web-Server. Zum Betrieb von smartVISU mit FHEM ist die Installation und Konfiguration von [[fronthem]] erforderlich.

Alle Artikel zur Thematik fronthem/smartVISU sind [[:Kategorie:fronthem/smartVISU|hier]] kategorisiert.

----

__TOC__

Für die Installation ist es immer sinnvoll, von einem auf aktuellem Stand befindlichen System zu starten.

Für das Betriebssystem (Linuxderivat)
sudo apt-get update

sudo apt-get upgrade

Für FHEM
<code>update</code> in der Eingabezeile

Die Installation lässt sich in 4 Bereiche unterteilen.

== Webserver installieren ==

Welcher Webserver zum Einsatz kommt, ist unerheblich. Im Folgenden sind Beispiele für lighttpd, nginx und Apache2 zu finden. Es wird nur '''eine''' Installation benötigt.

=== lighttpd ===
Dieses Beispiel basiert auf diesem {{Link2Forum|Topic= 27291|Message=208880|LinkText=Forumsbeitrag}}.

Webserver installieren:
sudo apt-get install lighttpd

PHP installieren:
sudo apt-get install php5-common php5-cgi php5

PHP konfigurieren:
sudo lighty-enable-mod fastcgi-php

Webserver-Dienst einmal neu starten, damit die Einstellungen wirksam werden:
sudo service lighttpd force-reload

Welchseln in des Root-Verzeichnis des Webservers (bei Bedarf, wenn sich das Root-Verzeichnis einer Distribution woanders ist, muss dieser Pfad entsprechend angepasst werden):
cd /var/www

Setzen des Besitzers und der Gruppe für das Root-Verzeichnis (TODO: Ist dieser Schritt wirklich notwendig?):
sudo chown www-data:www-data /var/www

Setzen der Berechtigungen des Root-Verzeichnis (TODO: Ist dieser Schritt wirklich notwendig?):
sudo chmod 775 /var/www

=== nginx ===
==== mit PHP5 ====

Dieses Beispiel basiert auf diesem {{Link2Forum|Topic=30909|Message=273180|LinkText=Forumsbeitrag}}.

Für die Installation des Webservers und PHP5 werden folgende Pakete benötigt:
sudo apt-get install nginx php5-fpm

Die Konfiguration für PHP muss in der entsprechenden Konfigurationsdatei vorgenommen werden:
sudo nano /etc/nginx/sites-enabled/default

Folgende Konfiguration sollte direkt funktionieren:
<pre>
server {
listen 80;
root /var/www;
index index.html index.php;
server_name localhost;
location / {
try_files $uri $uri/ /index.php?$args;
}
location ~ \.php$ {
try_files $uri =404;
fastcgi_pass unix:/var/run/php5-fpm.sock;
fastcgi_index index.php;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
include fastcgi_params;
}
}
</pre>

==== mit PHP7 ====
Ubuntu 16.04 läuft standardmäßig mit PHP7. Der Betrieb ist noch nicht zu 100% getestet und daher ohne Garantie.

Für die Installation des Webservers und PHP werden folgende Pakete benötigt:
sudo apt-get install nginx php7.0-fpm

Die Konfiguration für PHP muss in der entsprechenden Konfigurationsdatei vorgenommen werden:
sudo nano /etc/nginx/sites-enabled/default

Folgende Konfiguration sollte direkt funktionieren:
<pre>
server {
listen 80 default_server;
listen [::]:80 default_server;
root /var/www/html;
index index.php index.html index.htm index.nginx-debian.html;

server_name _;

location / {
try_files $uri $uri/ =404;
}
location ~ \.php$ {
try_files $uri =404;
fastcgi_split_path_info ^(.+\.php)(/.+)$;
fastcgi_pass unix:/run/php/php7.0-fpm.sock;
fastcgi_index index.php;
include fastcgi.conf;
fastcgi_read_timeout 600;
}
location ~* \.(js|css|png|jpg|jpeg|gif|ico|eot|otf|ttf|woff)$ {
access_log off; log_not_found off; expires 30d;
}
location = /robots.txt { access_log off; log_not_found off; }
location ~ /\. { deny all; access_log off; log_not_found off; }
}
</pre>

=== Apache2 ===

Dieses Beispiel basiert auf diesem [http://www.meintechblog.de/2015/06/smartvisu-mit-fhem-die-perfekte-visualisierung-teil-1-basics/ Blogeintrag].

Für die Installation des Webservers und PHP5 werden folgende Pakete benötigt:
sudo apt-get install apache2 php5 libapache2-mod-php5

Für das git /cleaninstall: da liegt die erweiterte smartVISU, mit Mandanten und reparierten widgets (wo nötig) - ansonsten aber unverfälscht und nicht mit widgets erweitert.

== smartVISU Installation ==

Für das Klonen (Herunterladen) wird folgendes Paket benötigt:
sudo apt-get install git

=== smartVISU herunterladen ===
Für die Installation gibt es ein fertig zusammengestelltes Paket aus dem git-Repo von Jörg Herrmanns ([https://github.com/herrmannj/smartvisu-cleaninstall]).

Hierbei handelt es sich um das Original smartVISU inkl. einigen Anpassungen (fhem-Treiber, Widget-Korrekturen, ...).

Einrichten eines Installationsordners im home-Verzeichnis:
mkdir ~/install

Wechseln in das Verzeichnis:
cd ~/install

Klonen der Pakets:
git clone https://github.com/herrmannj/smartvisu-cleaninstall.git
Dabei wird der Unterordner ./smartvisu-cleaninstall angelegt, in den die Dateien heruntergeladen werden.

=== smartVISU an richtige Stelle kopieren ===
Damit der Webserver die Seiten von smartVISU zur Verfügung stellt, müssen diese an die richtige Stelle in Abhängigkeit des verwendeten Webservers und Konfiguration kopiert werden. Ggf. muss die Konfiguration des Webservers entsprechend angepasst werden.

Das neu erstellte Verzeichnis in das Root-Verzeichnis des Webservers kopieren. Dass, wie in diesem Fall angegeben, das Verzeichnis /var/www/ das richtige Verzeichnis ist, kann z.B. dadurch bestätigt werden, dass dort bereits die Default-Seite des Webservers nach der Ersteinrichtung zu finden ist. Bei Bedarf ist das Verzeichnis anzupassen.
sudo cp -rp smartvisu-cleaninstall /var/www/smartVISU

Selbstverständlich lässt dich auch ein anderes Installationsverzeichnis wählen. Die folgenden Schritte müssen dann entsprechend angepasst werden.

=== Berechtigungen setzen ===
Später wird zumindest die Konfiguration von dem, was auf dem Endgerät angezeigt werden soll, vom Endgerät aus konfiguriert. Damit dieses auch funktioniert, müssen die Berechtigungen der Seiten entsprechend angepasst werden.

Wechseln in das Verzeichnis:
cd /var/www

Setzen des Besitzers und der Gruppe für das Root-Verzeichnis von smartVISU
chown -R www-data:www-data smartVISU

Setzen der Berechtigungen für das Root-Verzeichnis "smartVISU" und alle Unterordner
chmod -R 775 smartVISU

=== ggf. Gruppenmitgliedschaft anpassen ===
Dieser Schritt ist optional und dann hilfreich, wenn man mit einem normalen user z.B. über fileZilla die Dateien austauschen möchte. Da der Schritt zulasten der Sicherheit geht, sollte man ihn nach Abschluss der Konfiguration ggf. wieder rückgängig machen.

In diesem Beispiel wird der user "pi" zur Gruppe <code>www-data</code> hinzugefügt. Verwendet man einen anderen user, muss dieses selbstverständig angepasst werden.
sudo usermod -a -G www-data pi

Rückgängig machen kann man die Gruppenzugehörigkeit über
sudo deluser pi www-data

=== Config.ini kopieren ===
Hierbei handelt es sich um die Hauptdatei mit der das Verhalten von smartVISU gesteuert wird.

Die Datei "config.ini.default" muss zu "config.ini" umbenennen oder besser kopiert werden:
sudo cp /var/www/smartVISU/config.ini.default /var/www/smartVISU/config.ini

=== Installation überprüfen ===

Beim Aufruf der Seite <code>http://<IP-Adresse>/smartVISU</code> sollte folgende Seite angezeigt werden: {{Randnotiz|RNTyp=y|RNText=
Ggf. in der php.ini (error_reporting) die Ausgabe von Warnings abschalten, wenn so was kommt wie "Notice: Undefined index..."
}}

Diese Seite wird ggf. nur einmal direkt nach der Ersteinrichtung angezeigt und ist im Folgenden nicht mehr notwendig.

[[Datei:Installation_SmartVISU.png]]

=== nicht offiziell veröffentlichte Version 2.8 ===

Die Installation der nicht offiziell veröffentlichten Version 2.8 von smartVISU basiert auf diesem [https://github.com/ddtlabs/build-smartvisu-cleaninstall Git-Eintrag].
Die Verwendung geschieht auf eigene Gefahr.

Da man das Softwarepaket für smartVISU direkt von der Quelle herunterläd, müssen die notwendigen Erweiterungen manuell eingefügt werden. Dabei ist der "Treiber" am wichtigsten.

Herunterladen von smartVISU von der Quelle
git clone https://github.com/Martin-Gleiss/smartvisu.git

Kopieren in das Webserver Root-Verzeichnis
sudo cp -rp smartvisu /var/www/html/sv

Herunterladen der Anpassungen für FHEM
git clone https://github.com/herrmannj/smartvisu-cleaninstall.git

Kopieren der Erweiterungen
sudo cp ./smartvisu-cleaninstall/readme.txt /var/www/html/sv/
sudo cp ./smartvisu-cleaninstall/lib/functions_config.php /var/www/html/sv/lib/
sudo cp ./smartvisu-cleaninstall/lib/includes.php /var/www/html/sv/lib/
sudo cp ./smartvisu-cleaninstall/config.ini.default /var/www/html/sv/
sudo cp ./smartvisu-cleaninstall/pages/base/configure.php /var/www/html/sv/pages/base/
sudo cp ./smartvisu-cleaninstall/driver/io_fhem.js /var/www/html/sv/driver/
sudo cp ./smartvisu-cleaninstall/driver/io_fhem.min.js /var/www/html/sv/driver/
sudo cp /var/www/html/sv/config.ini.default /var/www/html/sv/config.ini

Setzen der Berechtigungen (Besitzer und Gruppe)
cd /var/www/html
sudo chown -R www-data:www-data sv

Wie leicht zu erkennen, ist in diesem Beispiel das Root-Verzeichnis des Webserver <code>/var/www/html</code> und das Verzeichnis, in das smartVISU installiert wird "sv".
Die smartVISU-Seite wird entsprechend nur mit <code>http://<IP-Adresse>/sv</code> aufgerufen.

== ein eigenes "Haus" anlegen ==
Nun gilt es nur noch ein eigenes "Haus" anzulegen, dass man individuell konfiguriert.

* im Ordner "''/var/www/smartVISU/pages''" einen neuen Ordner "''MeinHaus"'' anlegen.
* aus dem Ordner "''../pages/_template''" alles in den neuen Ordner ("''/var/www/smartVISU/pages/MeinHaus"'') kopieren.
* "''rooms_menu.html''" an eigene Gegebenheiten anpassen hierzu dienen die "_template-Dateien" als Orientierung.
* alle rooms anlegen durch Kopien des Beispielraumes (''room_sleeping.html'') und passende icons und Überschriften verteilen. ([http://www.smartvisu.de/docu/2.7/index.php?page=design/design_icons SmartVisu Icons])
* SmartVISU nutzt [http://twig.sensiolabs.org/ Twig] als Template engine und die Seiten bestehen aus Blöcken und Widgets, die immer in doppelten geschweiften Klammern stehen <nowiki>{{ ... }}</nowiki>
* Widget Syntax auf [http://www.smartvisu.de/docu/2.7/index.php SmartVISU Doku] nachschlagen und kopieren.
* innerhalb eines Raums zwischen {% block content %} und {% endblock %} als Beispiel folgenden Abschnitt einfügen:

<pre><nowiki>
<h1><img class="icon" src='{{ icon0 }}scene_livingroom.png'/>Wohnzimmer</h1>
<div class="preblock">
</div>
<div class="block">
<div class="set-2" data-role="collapsible-set" data-theme="c" data-content-theme="a" data-mini="true">
<div data-role="collapsible" data-collapsed="false" >
<h3>Licht</h3>
<table width="90%">
<tr><td align="left" width="100px"> {{ basic.switch('Leselampe', 'Leselampe.sw', icon1~'light_floor_lamp.png', icon0~'light_floor_lamp.png') }}</td>
<td>Leselampe</td>
</tr>
</table>
</div>
</div>
</div>
</nowiki></pre>

* Datei speichern und checken, dass die Rechte mindestens auf "755" stehen, ansonsten mit "sudo chmod 755" korrigieren.

Obwohl der folgende Teil bereits zur Einrichtung von fronthem gehört, sei es der Vollständigkeit halber des Beispiels hier trotzdem erwähnt:
* In FHEM eine fronthemDevice Detailansicht öffnen
* Nun sollten die GADs aufgelistet werden. Aus der Liste ein GAD auswählen (hier: "Leselampe.sw" wie im obigen Code-Beispiel definiert.) und die Parameter vergeben:
<pre>
device: <fhem-Name-des-fhem-devices> (in diesem Fall die Leselampe.sw)
reading: state
converter: OnOff
cmd set: state
write: ja (haken setzen)
read: ja (haken setzen)
</pre>
: "state" immer klein schreiben und speichern nicht vergessen!
* Die Settings für das Device gelten für alle Endgeräte, aber die read/write Rechte müssen für jedes Endgerät separat gesetzt werden.

== Einrichtung Endgerät ==
Als letztes greift man vom Endgerät auf die smartVISU-Seiten zu und stellt auf der Config-Seite den Treiber, IP der Servers und den Port ein.

Unter smartVISU in die Konfigurationsoberfläche wechseln <code>http://<IP-Adresse>/smartvisu/index.php?page=config</code> bzw. Zahnrad = Config-Menü:
* Im Feld "Interfaces" für pages das eigenes Haus auswählen (=Ordnername)
* Der Pagecache sollte zumindest während der Einrichtung ausgeschaltet sein.
* Im Feld I/O Connection den Treiber Fhem wählen
* Die IP-Adresse des Servers mit dem Websocket-Server eintragen
* Port 2121 einstellen
Nach allen Eintragungen die Konfiguration am unteren Ende der Seite speichern.

Damit die GADs nun im GAD-Editor auf der Detailseite von einem [[fronthem#fronthemEditor|fronthemDevice]] auftauchen, ist es jetzt wichtig, die neue Seite in smartVISU einmal aufzurufen, damit im Hintergrund die GADs übertragen werden.

Vorausgesetzt, man hat vorher alle notwendigen Schritte für die Installation und Konfiguration von fronthem ausgeführt, kann man nun smartVISU in Verbindung mit FHEM benutzen.

Im Noramlbetrieb stellt man den Pagecache auf "on"- dann werden die templates compiliert gespeichert, was die Geschwindigkeit erhöht {{Link2Forum|Topic=35960|Message=283665|LinkText=(Forum)}}.

== Troubleshooting ==

=== SSL ===

Wird derzeit nicht unterstützt {{Link2Forum|Topic=43226|Message=352115|LinkText=(Forum)}}.

=== Performanceproblem ===

Während der Entwicklung gab es mehrere Evolutionen, was die Verbindung über den Treiber angeht. Trotzdem hat auch die Platform, auf der smartVISU läuft einen gehörigen Anteil an der Reaktivität der Oberfläche. Darüber hinaus hat selbstredend die Komplexität einer Seite Einfluss auf die Geschwindigkeit.
Mit einem Webserver auf dem RPi2 scheint es noch potential nach oben zu geben, setzte man eine performantere Platform ein {{Link2Forum|Topic= 48243|Message=402427|LinkText=(Forum)}}.

=== Config-Seite anstatt der individuellen Seite ===

Es wurde vergessen, die Datei config.ini.default nach config.ini zu kopieren {{Link2Forum|Topic= 46501|Message=382426|LinkText=(Forum)}}.

=== Zugriffsprobleme mit Apache ===
Anscheinend gab es vereinzelt Zugriffsprobleme auf das smartVISU-Vereichnis, die sich aber mit dieser Erweiterung der Apache-Konfiguration beheben lies {{Link2Forum|Topic=30909|Message=239882|LinkText=(Forum)}}:

<pre>
<Directory "/var/www/smartvisu">
Options +Indexes FollowSymLinks +ExecCGI
AllowOverride AuthConfig FileInfo
Order allow,deny
Allow from all
</Directory>
</pre>

=== 404 not found ===

Wird noch nicht einmal die Seite gefunden (404), sind bereits die statischen Seiteninhalte der Webseite nicht richtig konfiguriert. Es muss sichergestellt werden, dass eine Datei im Verzeichnis von smartVISU von einem Endgerät angezeigt werden kann {{Link2Forum|Topic= 46501|Message=49524|LinkText=(Forum)}}.

=== *.js dateien ===

Sollte jemand Änderungen an den *.js Dateien bearbeiten muss man daran denken, dass in der config.ini ganz unten vereinbart wird welche Version der Datei benutzt wird {{Link2Forum|Topic=30909|Message=252375|LinkText=(Forum)}}.

=== verschiedene Devices, verschiedene Anzeigen ===

Möchte man sicherstellen, dass auf allen Endgeräten die gleiche page konfiguriert ist, verschiebt man den entsprechenden Teil in der config.ini in den <nowiki>[default]</nowiki>-Bereich.

An dieser Stelle sei eindringlich empfohlen, diese Änderung nur bei nicht laufendem Websocket durchzuführen und in jedem Falle ein Backup der Datei vorzuhalten. Bei Syntaxfehlern wird diese Datei neu erzeugt und überschreibt ohne Nachfrage die Vorversion {{Link2Forum|Topic=46541|Message=383006|LinkText=(Forum)}} {{Link2Forum|Topic=36420|Message=287038|LinkText=(Forum)}}.

=== Welcher Treiber ist installiert ===

Um zu prüfen, welche Version vom Treiber man aktuell verwendet, kann man im Browser die Konsole öffnen und nach einem page reload diesen Log-Eintrag suchen:

[io.fhem]: init [V1.10] (address= ...

In diesem Beispiel ist es Version 1.10 {{Link2Forum|Topic=35960|Message=283617|LinkText=(Forum)}}.

=== neue Clients ===

Das Anlegen neuer Clients In smartVISU müssen nicht händisch ergänzt werden. In der config.ini gibt es den parameter auto_add = true|false. Wenn dieser auf true steht, werden neue Clients automatisch in smartVISU angelegt und bekommen eine Kopie der default Einstellungen.
Im Anschluss können über die Config-Seite die individuellen Einstellungen über die smartVISU-Oberfläche konfiguriert und gespeichert werden (page, design, evtl. calender, etc) {{Link2Forum|Topic=30909|Message=236222|LinkText=(Forum)}}.

=== Ordner und Dateien ===
Auch wenn es im Normalfall nicht notwendig ist sollte, kann es manchmal sinnvoll sein, den genauen Speicherort aller Dateien und Konfigurationsdateien zu kennen und entsprechend Debugging-Trigger hinzuzufügen oder Konfigurationen direkt zu korrigieren.

Die folgenden Pfadangaben gehen davon aus, dass das Root-Verzeichnis des eingesetzten Webservers /var/www/html/ ist und smartVISU im Unterordner /var/www/html/sv liegt.

==== Konfigurationsdateien ====

Konfigurationsdatei von smartVISU:
/var/www/html/sv/config.ini

==== Ordner und Dateien ====
Dokumenten Root für smartVISU:
/var/www/html/sv/

Treiber:
/var/www/html/sv/driver/io-fhem.js

/var/www/html/sv/driver/io_fhem.min.js

Temp-Ordner:
/var/www/html/sv/temp

Template-Ordner für neue "page":
/var/www/html/sv/pages/_template

Eigener Page-Ordner
/var/www/html/sv/pages/<eigene page>

[[Kategorie:fronthem/smartVISU]]

SmartVISU

2016-06-26T14:33:24Z

Joshi04: Komplette Überarbeitung im Rahmen des gesamten Themengebiets fronthem/smartVISU

SmartVISU

2016-06-26T14:23:31Z

Joshi04: Joshi04 verschob die Seite SmartVisu nach SmartVISU: Anpassung an die offizielle Schreibweise

[[SmartVisu]] ist ein Framework zur Visualisierung von Hausautomationssystemen, die eigentlich KNX-Installationen bedient.

Durch [[Fronthem]] ist es möglich SmartVisu an Fhem anzubinden.

* Ausführliche Beschreibung von Fronthem: [[Fronthem]]
* Installationsanleitung für SmartVisu in Verbindung mit Fronthem: [[Installation Fronthem]]

==Codebeispiele:==

* [[SmartVisu/IconHighlights in Menus]]
* [[SmartVisu/lichtSzene]]

==Widgets:==

Zusätzliche Widgets werden im git-Repository https://github.com/herrmannj/smartvisu-widgets bereitgestellt:

* [[smartVISU/Universelle ZeitSchaltUhr (UZSU)]]
* [[SmartVisu/ical|ical]]
* [[SmartVisu/fritz!box_via_TR-064|fritz!box_via_TR-064]]
* fritz!box_v6.20
*

[[Kategorie: FHEM Frontends]]

Fronthem Installation

2016-06-26T14:22:41Z

Joshi04: Komplette Überarbeitung im Rahmen des gesamten Themengebiets fronthem/smartVISU

{{SEITENTITEL:fronthem Installation}}

Dieser Artikel befasst sich mit der Installation von "fronthem". Es stellt ein Interface zur Verfügung, um ein Webfrontends wie z.B. [[smartVISU]] an FHEM anzubinden. Die Konfiguration und das Interface selbst sind im [[fronthem|Hauptartikel von fronthem]] beschrieben.

Alle Artikel zur Thematik fronthem/smartVISU sind [[:Kategorie:fronthem/smartVISU|hier]] kategorisiert.

----

__TOC__

== Vorraussetzungen schaffen ==

In Abhängigkeit der verwendeten Distribution gibt es mehrere Möglichkeiten, die einzelnen Pakete zu installieren {{Link2Forum|Topic=38639|Message=309479|LinkText=(Forum)}}. Für einige Installationsschritte ist das Paket build-essential, dass über diesen Befehlt installiert werden kann. Sonst können die make's während der folgenden Schritte nicht ausgeführt werden {{Link2Forum|Topic=30909|Message=235986|LinkText=(Forum)}}.
sudo apt-get install build-essential

=== cpanmin ===
curl -L https://cpanmin.us | perl - --sudo App::cpanminus

oder

sudo apt-get install cpanminus

=== WebSocket ===

sudo cpanm Net::WebSocket::Server
oder {{Link2Forum|Topic=47120|Message=388577|LinkText=(Forum)}}
sudo cpan install Net::WebSocket::Server

=== JSON ===

sudo cpanm JSON
oder
sudo cpan install JSON
oder falls es Probleme mit CPAN und Debian z.B. auf dem RPi gibt, kann man JSON auch über die normale Paketverwaltung installieren {{Link2Forum|Topic=30909|Message=237576|LinkText=(Forum)}}:
sudo apt-get install libjson-perl

== Module herunterladen ==

Mit folgendem Befehl kann man fronthem installieren / updaten (in Eingabezeile von FHEM eingeben):
update force https://raw.githubusercontent.com/herrmannj/fronthem/master/controls_fronthem.txt

Durch die Option <code>force</code> werden bei erneutem Aufruf auch erneut alle Dateien heruntergeladen und das Update so erzwungen.

== Ersteinrichtung innerhalb von FHEM ==

Die Konfiguration von fronthem in FHEM (Eingabe in der Fhem Web Kommandozeile):
define <Name Webservice> fronthem

define <Name Endgerät> fronthemDevice <IP Endgerät>

Beispiel:
define meinfronthem fronthem

define meiniphone fronthemDevice 192.168.178.25

Näheres zur Einrichtung und Konfiguration innerhalb von FHEM findet sich im [[fronthem|Hauptartikel]] von fronthem.

==Troubleshooting==

=== Fehler bei Installation von WebSocket ===

Zum einen ist für die Installation das Paket build-essential notwendig, dass z.B. über folgenden Befehl installiert werden kann:
sudo apt-get install build-essential

Darüber hinaus muss die Konfiguration des Netzwerk-Interfaces korrekt und vollständig sein {{Link2Forum|Topic=52694|Message=445277|LinkText=(Forum)}}.

=== Port 2121 belegt ===

Ist der Port 2121 bereits durch einen anderen Dienst belegt, z.B. ein OWS Server, gibt es beim Versuch den Websocketserver zu starten eine Fehlermeldung {{Link2Forum|Topic=38639|Message=313193|LinkText=(Forum)}}.

[[Kategorie:fronthem/smartVISU]]

Fronthem

2016-06-26T14:18:27Z

Joshi04: Kapitel: Dateien/Ordner hinzugefügt; Link zum Forumsbereich aktualisiert; Kleinigkeiten

{{SEITENTITEL:fronthem}}

{{Infobox Modul
|ModPurpose=Anbindung von externen Frontends an FHEM
|ModType=x


|ModForumArea=fronthem/smartVISU
|ModTechName=01_fronthem.pm, 31_fronthemDevice.pm, fhconverter.pm, fronthemEditor.js
|ModOwner=[http://forum.fhem.de/index.php?action=profile;u=769 Jörg alias herrmannj]
}}

Dieser Artikel befasst sich mit den FHEM-Modulen und weiteren Dateien, die für die Integration von fronthem in FHEM notwendig sind. Die [[fronthem Installation|Installation von fronthem]] ist in einem separater Artikel beschrieben.

Alle Artikel zur Thematik fronthem/smartVISU sind [[:Kategorie:fronthem/smartVISU|hier]] kategorisiert.

----

Fronthem verfolgt die Idee, ein externes Web-Frontend (z. B. [[smartVISU]]) an fhem anzukoppeln und den Datenverkehr sowie die Zusammenarbeit von Befehlen und Parametern zwischen FHEM und dem Web-Frontend zu übernehmen. Im Hauptartikel von smartVISU ist ebenfalls eine Systemübersicht der zusammenhänge gezeigt.

Fronthem ist ein Projekt von herrmannj und wurde im {{Link2Forum|Topic= 27291|Message=27291.0l|LinkText=fhem-Forum}} erstmalig angekündigt.

Für die Installation eines passenden Web-Frontends (z.B. smartVISU), sowie dessen [[smartVISU Installation|Installation]] gibt es jeweils eigenständige Artikel.

__TOC__

{{Todo|Redaktionelle Überarbeitung der Detailbeschreibung für Readings Converter RGBCombined. Beschreibung der Converter ReadingsTimestamp, Attribute, Trigger.}}

Die Integration von fronthem als Interface innerhalb von FHEM besteht aus vier Bausteinen:

==Bausteine==
=== websocket ===
Der Websocket ist eine generische http-Schnittstelle, die von einem externen Frontend aus angesprochen werden kann.

Der Websocket Server wird durch das fhem-Modul "fromthem" automatisch gestartet, sobald ein Device vom TYPE <code>fronthem</code> definiert wurde. Der zugehörige Prozess läuft vom fhem Hauptprozess entkoppelt und kann mit ihm kommunizieren.

Der Websocket wird standardmäßig auf Port 2121 angesprochen, wird implizit durch die anderen Bausteine verwendet und benötigt im Prinzip keine weitere Beachtung, außer man möchte das Webinterface auf einem anderen Device neben FHEM laufen lassen.

Allerdings ist dieses das eigentliche Interface zwischen FHEM und einem externen Frontend.

=== device connector ===
Ein Device-Connector dient dazu, ein Endgerät eines Benutzers (PCs, Tablets, Smartphones usw.) als Clients zu konfigurieren und dessen Berechtigungen (read, write) auf der Ebene einzelner Objekte zu steuern. Damit können z. B. die Nachkommen oder Gäste zwar das Licht und die Heizung im eigenen Raum steuern, nicht aber die Programmierung der Heizung ändern oder den Alarm ausschalten.

Ein Endgerät wird dabei jeweils als Device vom TYPE <code>fromthemdevice</code> innerhalb von FHEM definiert. Details zur genauen Einrichtung finden sich im [[#Integration in FHEM|Verlauf]] dieses Artikels.

An einem einzelnen Device-Connector werden die durch den websocket vom externen Frontend mitgeteilten Objekte aufgelistet (GADs) und können dort einerseits mit fhem devices verbunden und andererseits in den Berechtigungen des jeweiligen Endgerätes konfiguriert werden.

Die Kombination der Frontend-items (GADs) mit den fhem-Devices über die Converter wird nur einmal benötigt und hat eine globale Gültigkeit. Die Berechtigungen der verwendeten Endgeräte werden jeweils pro Endgerät gesetzt. Details zum Konfigurieren und Duplizieren von Berechtigungen finden sich im weiteren [[#Integration in FHEM|Verlauf]] dieses Artikels. Auch eine Zugriffsberechtigung über eine PIN-Abfrage ist angedacht, bislang (Juni 2016) aber noch nicht implementiert.

Änderungen von Readings, Events werden dabei per {{Link2Forum|Topic= 27291|Message=209920l|LinkText=push}} auf die Devices verweilt.

=== readings converter ===

Die readings converter dienen dazu, die Verbindung zwischen den Informationen in FHEM (states, readings, events) und den Formaten, die innerhalb des Frontends verwendet werden, herzustellen. Die Readings von FHEM müssen in die Form der möglichen Werte des Frontends umgewandelt werden. Im umgekehrten Fall müssen Befehle des Frontends in FHEM kompatible Befehle umgesetzt werden.

Über das Konzept der converter können FHEM-Devices unterschiedlichster Typen und Funktionen über das Frontend bedient werden. So versorgt der gleiche converter der die Solltemperatur des virtuellen Heizungsthermostats (bidriektional) einstellt auch die Füllstandanzeige der Zisterne sowie den Dimmer. In den genannten Fällen handelt es sich um die Übertragung von numerischen Werten. Converter können dabei auch Spezialaufgaben wie die Begrenzung des Wertebereichs übernehmen. So lässt sich über NumDirect zum Beispiel die Solltemperatur Einstellung für virtuelle Heizungsregler auf Min und Max Werte begrenzen.

Standardmäßig gibt es folgende Converter:
* [[#Direct|Direct]] für Übertragung ohne Konvertierung
* [[#NumDirect|NumDirect]] für Übertragung von Zahlenwerten in einem begrenzten Werteraum zwischen Min und Max
* [[#NumDisplay|NumDisplay]] für Zahlenwerte aus fhem Readings, nur lesend
* [[#OnOff|OnOff]] für Schalter, Übersetzung von On in 1 und Off in 0
* [[#RGBCombined|RGBCombined]] für Übertragung von RGB-Werten so das sie FHEM akzeptiert
* [[#ReadingsTimestamp|ReadingsTimestamp]] (vorhanden, Beschreibung TODO)
* [[#Attribute|Attribute]] (vorhanden, Beschreibung TODO)
* [[#Trigger|Trigger]] (vorhanden, Beschreibung TODO)

Weitere Readings Converter können darüber hinaus [[#eigene Converter|individuell selbst]] definiert werden.

Die hier beschriebenen Converter sind kompatibel mit dem oben erwähnten Frontend smartVISU und werden auf dessen Basis erklärt. Für die Verwendung in Kombination mit anderen Frontends müssen die Converter möglicher Weise entsprechend angepasst werden.

====Direct====
Die Werte werden ohne Konvertierung weitergegeben.

Gibt den Wert des von <reading> ohne weitere Wandlung an das Frontend weiter. In umgekehrter Richtung wird der vom Frontend geliefert Wert ohne Wandlung im hinterlegten <set> eingesetzt.

Beispiel:
:Anzeige eines An- oder Abwesenheitszustandes im Frontend (Textanzeige, Icon, Button)

====NumDirect====
NumDirect arbeitet bidirektional. Die Werte werden genau wie bei Direct ohne Umwandlung weitergegeben.

Der Unterschied zu Direct besteht jedoch darin, dass nur Zahlenwerte übergeben werden, d.h. die Zahlen werden aus <reading> herausgefiltert.

Des Weiteren kann man einen minimalen und maximalen Wert mit angeben. Dieses soll verhindern, dass im Frontend Werte eingestellt werden, die überhaupt keinen Sinn ergeben.

Beispiel:
:In der smartVISU könnte man für einen Raumthermostaten z.B. -100°C einstellen, was der Aktuator auf Seiten von FHEM nicht umsetzen kann (minimal einstellbarer Wert).

==== NumDisplay ====
NumDisplay arbeitet nur in eine Richting, von FHEM zum Frontend. Die Werte werden ohne Umwandlung weitergegeben, bis auf die Tatsache, dass wie beim Converter NumDirect nur Zahlenwerte übergeben werden, d.h. die Zahlen werden aus <reading> herausgefiltert.

Es ist dazu gedacht Zahlenwerte zu übergeben, ohne etwas zu verändern.

Beispiel:
: Anzeige des Raumklimas (Temperatur, Feuchtigkeit, CO2, Lautstärke, etc.)

==== OnOff ====

Dieser Converter ist für das einfache Schalten von Ein/Aus-Funktionen vorgesehen.

FHEM interpretiert Ein/Aus-Funktionen mit on/off, innerhalb von smartVISU entsprechen diese Zustände jedoch 1/0.

Der OnOff-Converter wandelt diese bidirektional ineinander um.

Beispiel:
: Schalter

==== RGBCombined ====
Dieser Converter dient zur Steuerung von RGB Leuchtmitteln über Farbauswahlfelder (zb. Farbkreis). Eine Besonderheit ist hier, dass smartVISU die 3 RGB Werte separat verarbeitet. D.h. von FHEM wird ein RGB-Wert in HEX in 3 Werte, jeweils für R, G und B, aufgeteilt und an das Frotnend übergeben. In umgekehrter Richtung wird die Auswahl einer Farbe im Frontend mit den 3 Werten für R, G und B an den Converter übergeben, kombiniert und an FHEM übergeben.

Entsprechend arbeitet er bidirektional und wandelt 3 Frontend Items in ein FHEM-Objekt um. Damit die Kombination der Werte funktioniert, muss dieser Converter gleichlautend für alle 3 RGB Kanäle des Frontends definiert werden.

reading: Name eines reading mit HEX RGB Wert des Leuchtmittels

converter (mit Parameter): <code>RGBCombined <itemRed>, <itemYellow>, <itemBlue></code>

set: Name des set Befehls, bekommt HEX RGB Wert übergeben

==== ReadingsTimestamp ====
Dieser Converter ist im Modul bereits enthalten, dessen Beschreibung ist allerdings TODO.

==== Attribute ====
Dieser Converter ist im Modul bereits enthalten, dessen Beschreibung ist allerdings TODO.

==== Trigger ====
Dieser Converter ist im Modul bereits enthalten, dessen Beschreibung ist allerdings TODO.

==== eigene Converter ====
Zusätzlich zu den bestehenden Convertern besteht die Möglichkeit, eigene zu definieren. Diese können in der 99_myUtils.pm oder einer neu angelegten 99_fronthemUtils.pm definiert werden. Es ist nicht ratsam, die fhconverter.pm dafür zu verwenden, da bei einem möglichen späteren Update diese Datei überschrieben wird. Wie alle anderen Module, muss sich die Datei im Verzeichnis./fhem/FHEM/ befinden. ({{Link2Forum|Topic= 30909|Message=266944|LinkText=Forum}})

Eigene Converter müssen nur die gleiche Signatur haben und in dem gleichen namespace wie die im fhconverter.pm stehen dann werden sie dynamisch geladen und stehen in fronthem zur Verfügung. ({{Link2Forum|Topic= 30909|Message=236070l|LinkText=Forum}})

==== Ideen für weitere Converter ====

Zwei weitere Converter sind angedacht, aber derzeit noch nicht Teil des Moduls.

===== NumDelayed =====
NumDelayed ist noch in Arbeit.

Ein bidirektionaler numerischer Converter mit einstellbarer Verzögerung.

Bietet bei der Ansteuerung mechanischer Aktoren (Markise, Jalousie) Vorteile gegenüber NumDirect. Als Beispiel sei die Steuerung einer Jalousie über einen Slider genannt. Da Slider ihre Werte kontinuierlich an FHEM übermitteln, würde bei der Verwendung anderer Converter dem entsprechenden Aktor (z.B. HM-BP), während der Benutzer den Slider bedient, mehrfach der vermeindliche Sollwert übermittelt werden. Gleichzeitig beginnt der Aktor seine Fahrt und übermittelt dem Slider seine aktuelle ist Position. Das führt zu einem springen des Sliders und einer "unschönen" Bedienung.

NumDelayed nimmt daher die Signale des Sliders entgegen, wartet jedoch mit der Weitergabe solange, bis sich der Slider (xxx ms, konfigurierbar) nicht mehr bewegt. In Gegenrichtung wird ebenso verfahren, erst wenn der Aktor seine Endposition erreicht, wird der Slider im Frontend aktualisiert. In diesem Beispiel würde das bedeuten das der Slider im Normalfall ohnehin so steht (Soll) wie vom Aktor gemeldet (Ist). Natürlich könnte der Benutzer oder ein Hindernis die Fahrt auch unterbrochen haben, dann würde der Slider auf die gemeldete Position aktualisiert.

===== WordDisplay =====
WordDisplay ist derzeit in Planung, es wird noch über die Umsetzung diskutiert.

Der Converter soll nur in eine Richtung arbeiten, FHEM zu Frontend. Es ist dazu gedacht Wörter oder Textpassagen zu übertragen. Jedoch soll es möglich sein, eine Umwandlung selbst festzulegen. So kann man einfach mehrere Textausgaben abhängig vom Zustand an das Frontend schicken:

Beispiel:
: Geofancy: Home -> Zuhause, Underway -> Unterwegs, Work -> Arbeit

=== fronthemEditor ===

Um einen komfortable Möglichkeit zur Verfügung zustellen, die Bindung und Konvertierung zwischen FHEM Device/Reading und Frontend-Objekt festzulegen, gibt es einen Javascript Editor als Erweiterung von FHEMWEB.

Sobald ein fronthemDevice (Definition für ein Endgerät) definiert ist, kann man über dessen Details in FHEMWEB die GADs definieren und die Rechte verteilen.

==== GAD Liste ====
Auf der Detailseite werden im oberen Teil die GADs aufgelistet die von smartVisu "angefragt" wurden. In vier Spalten werden von links der GAD-Name (wie auf der smartVISU-Seite definiert), das damit verbundene FHEM-Device, für das frontemDevice gesetzte Lese-Rechte und Schreib-Rechte angezeigt. Im oberen Teil des Fensters lässt sich eine Zeichenkette eingeben, nach der die Liste gefiltert wird. (Zumindest in Dark-Style hat die Schrift der eingegebenen Zeichenkette die gleiche Farbe wie der Hintergrund).

Die Verknüpfung zwischen GAD und FHEM-Device gilt global und muss nur einmal für ein beliebiges fronthemDevice eingerichtet werden. Lese- und Schreibrechte können pro fronthemDevice konfiguriert werden.

Wichtig zu berücksichtigen ist die Tatsache, dass die GAD-Liste erst dann aktualisiert wird, wenn einmal die entsprechende Frontend-Seite von einem frontendDevice aufgerufen wurde. Die korrekte Konfiguration des Treiber auf der Config-Seite für das frontendDevice (siehe Installation des Frontends) wird dabei vorausgesetzt. Die Liste wird also erst gefüllt, wenn erstmalig vom Frontend über einen Seitenaufruf die Verbindung zu FHEM initiiert wurde.

Auf der anderen Seite weiß fronthem nicht, welche GADs in smartVISU verwendet werden. Jedes GAD das einmal sichtbar war, wird von fronthem gespeichert und aufgelistet, bis man es explizizt in fronthem löscht. ({{Link2Forum|Topic= 43226|Message=352115|LinkText=Forum}})

==== GAD Edit ====
Klickt man auf einen GAD aus der obigen Liste, öffnet sich ein weiteres Feld mit Titel "GAD Edit".
Das Feld ist in 2 Teile aufgeteilt, im oberen das globale Mapping zwischen GAD und FHEM-Device/Reading, darunter die Zugriffsrechte für das jeweilige Device. Am unteren Ende des Feldes sind Schaltflächen für das Löschen und Sichern von GADs aus der Liste oder das Abbrechen der Bearbeitung angeordnet.

Die GAD-Definierung im oberen Bereich besteht aus:
[[Datei:DeviceDefine.png|400px|thumb|right|GADs definieren]]
*mode
*device
*reading
*converter
*cmd set

===== mode =====

Es gibt 2 Modi:
*item
*plot

Die Unterscheidung ist selbsterklärend, alles was kein "plot" werden soll, wird als "item" definiert.

===== device =====

Hier wird der Name des FHEM-Devices eingetragen, an das die Befehle geschickt werden, bzw. dessen Readings angezeigt werden sollen. Die vorhandenen Devices in fhem werden als Liste unter dem Eingabefeld angezeigt, sobald man mit der Eingabe beginnt.

Wie überall innerhalb von FHEM ist die Groß/Kleinschreibung zu beachten.

===== reading =====

Für das <reading> wird das zu verwendende Reading des FHEM Devices angegeben, z. B. "state" oder "Level". Die vorhandenen Readings des gewählten fhem-Devices werden als Liste unter dem Eingabefeld angezeigt, sobald man mit der Eingabe beginnt.

Änderungen, wenn fhem entsprechende events erzeugt, werden von fronthem mitgelesen und per push an die fronthemDevices gesendet.

===== converter =====

Hier gibt man denn Namen des Converters an, denn man verwenden möchte. Wie oben beschrieben, stehen unterschiedliche [[#readings converter|converter]] für verschiedene Aufgabenstellungen zur Verfügung. Die meisten Devices können mit diesen Convertern angesteuert werden.

Wie überall innerhalb von FHEM ist die Groß/Kleinschreibung zu beachten.

===== cmd set =====

Das zum Schreiben zu verwendende Reading des fhem Devices, z. B. "state" oder "Level". Die vorhandenen Readings des gewählten fhem-Devices werden als Liste unter dem Eingabefeld angezeigt, sobald man mit der Eingabe beginnt.

Das gewählte Reading gibt den "set" des fhem Devices an, der die Rückgabe des Converters entgegen nimmt.

Bei Lampe z.B. "state".

==== Devicerechte vergeben ====

[[Datei:DeviceRechte.png|400px|thumb|right|Devicerechte vergeben]]
Devicerechte bestehen aus:
*Eine Berechtigung für "read"
*Eine Berechtigung für "write"
*Jeweils für Lese- und Schreib-Berechtigung die Festlegung eines PINs

===== read =====
Das Device darf die Statuswerte auslesen.

===== write =====
Das Device darf Statuswerte ändern.

===== PIN GAD =====

Die PIN-Abfrage für die Lese- oder Schreibberechtigung ist derzeit noch nicht implementiert, daher ist es irrelevant, was hier eingetragen wird.

===== Attribut Whitelist =====
Möchte man die differenzierte Berechtigungssteuerung für ein fronthemDevice außer Kraft setzen, kann das Attribut "whitelist" für das entsprechende fronthemDevice auf false gesetzt werden. Das bedeutet dann, dass unabhängig von den Berechtigungs-Checkboxen das fronthemDevice immer für alle GADs lesen und schreiben darf.

== Integration in FHEM ==

=== fronthem ===

Ein Device vom TYPE <code>fronthem</code> und damit das eigentlich Interface, wird nach erfolgreicher Sicherstellung der Voraussetzungen (siehe fronthem Installation) über folgenden Befehl in der Eingabezeile von FHEMWEB definiert:
:<code>define <name> fronthem</code>

Über diese Definition wird ebenfalls die Verbindung zum WebSocket sichergestellt. Logischer Weise benötigt man nur ein Device von diesem Typ.

Als Reading wird
* die Verbindung zum WebSocket angezeigt. "open" stellt dabei den normalen Zustand dar.
* lastError angezeigt, woran man beispielsweise erkennen kann, dass für Endgerät der Zugriff abgelehnt wurde ("client <IP-Adress> rejected").

Der state des Devices gibt dabei derzeit keine Meldung zurück. Ein Wert "???" ist daher kein Hinweis auf einen Fehler, sondern entspricht dem ganz normalen Modulverhalten.

===Device Connector===
Für jedes Endgerät (smartphone, PC, Tablet, etc.) mit dem man auf das Frontend zugreifen möchte, muss ein entsprechendes fronthemDevice definiert werden.
Wie oben bereits beschrieben, kann dadurch genau festgelegt werden, welches Endgerät welche Rechte für eine jeweilige Schalt-/Anzeigefunktion hat.

Wenn man die Berechtigungen für neue Endgeräte kopieren möchte, liegen diese für jedes Endgerät unter ./fhem/www/fronthem/clients/<fronthemDevice> und lassen sich so einfach für neue Endgeräte übertragen.

====IP-Identify====

Ein Endgerät wird über seine IP_Adresse identifiziert. Dies ist nur im internen gesicherten Netzwerk empfehlenswert. Es wird definiert mit:
:<code>define <device> fronthemDevice <ip></code>

Dabei ist für die IP-Adresse die des Endgerätes anzugeben, welches auf den smartVISU zugreifen soll (also das Tablet, Rechner, Smartphone etc.). Entsprechend selbstverständlich ist, dass man durch eine passende Einstellung seine DHCP-Servers oder fest vergebene IP-Adressen sicherstellt, dass ein Endgerät immer die gleiche IP erhält/verwendet.

Wichtig bei der späteren Verwendung ist, dass pro Endgerät immer nur ein Brower-Tab geöffnet wird, mit dem man auf das Frontend zugreift. Sonst erhält fronthem mehrere Zugriffe von der gleichen IP, die sich gegenseitig ins Gehege kommen.

====Zertificate-Identify====
{{Randnotiz|RNTyp=info|RNText=Hinweis: Diese Möglichkeit wurde während der Entwicklung bereits diskutiert und berücksichtigt, die Verwendung von Zertifikaten wurde bislang aber noch nicht implementiert, hauptsächlich aufgrund der teilweise mangelnden oder zumindest sehr unterschiedlichen Unterstützung von Zertifikaten auf Endgeräte-Seite (z.B. webviewcontrol).
}}

Das Endgerät wird über ein Zertifikat identifiziert.
Zuerst wird ein Zertifikat generiert, welches dann auf dem Endgerät installiert werden muss.

Diese Methode der Identifizierung verspricht höhere Sicherheit, wie auch denn Vorteil, das man sich nicht einloggen muss.

==Troubleshooting==
=== allgemeines Vorgehen ===

Generelles Vorgehen bei seltsamen Erscheinungen:
* smartVISU-Page-Cache ausschalten (auf der Config Seite von smartVISU, wo auch der Treiber konfiguriert wird)
* smartVISU-temp-Verzeichnis leeren (e.g. /var/www/html/smartvisu/temp)
* Browser neu starten
* Konsole im Browser öffnen und nach Fehlermeldungen schauen
* In der Datei fronthem.err im Verzeichnis /opt/fhem nach Fehlermeldungen schauen {{Link2Forum|Topic=36858|Message=291272|LinkText=(Forum)}}
* Verbose Level des FHEM-Device <code>fronthem</code> und <code>fronthemDevice</code> auf 5 setzen und im Log nach Errors schauen
* Den Log des Webservers kontrollieren
* Prüfen, ob der WebSocket läuft
{{Link2Forum|Topic= 30909|Message=272083|LinkText=(Forum)}}, {{Link2Forum|Topic= 35960|Message=285384|LinkText=(Forum)}}, {{Link2Forum|Topic= 52624|Message=444004|LinkText=(Forum)}}

=== Verbindung ===

Erhält an eine "no connection" Warnung in smartVISU sollte man folgendes kontrollieren:
* Wurde auf der config-Seite von smartVISU auf dem Endgerät der Treiber auf "Fhem" gestellt?
* Ist auf der config-Seite von smartVISU auf dem Endgerät die richtige Adresse des WebSocket Servers (meistens der Server mit der FHEM-Instanz) und der Port 2121 eingetragen?
* Wurde für das fronthemDevice die richtige IP-Adresse definiert?
* Steht "connected" im state des fronthemDevice ?
{{Link2Forum|Topic= 30909|Message=236681|LinkText=(Forum)}}

Darüber hinaus wird Websocket erst ab Android 4.4 einwandfrei unterstützt {{Link2Forum|Topic= 39587|Message=318219|LinkText=(Forum)}}.

Ebenfalls das iPad 1G wird nicht mehr unterstützt {{Link2Forum|Topic= 46737|Message=384727|LinkText=(Forum)}}.

=== alternativer Treiber zum loggen auf der Konsole ===

Falls mal ein Widget den Websocket Server zum Absturz bringt, was mittlerweile nicht mehr passieren sollte, wurde im {{Link2Forum|Topic= 30909|Message=273617|LinkText=Forum}} ein Treiber veröffentlich, der das "überlebt" und auf der Konsole weiter loggt, welches Widget es verursacht hat.

=== dummy zum Debuggen ===

Hat man Probleme ein FHEM zur Funktion zu überreden, kann man stattdessen ein Dummy einrichten. Anhand des Dummy lässt sich leicht sehen, was genau gesetzt wird {{Link2Forum|Topic=35959|Message=289046|LinkText=(Forum)}}.

=== Logmeldungen ===

Da die Module noch inoffiziell sind, hat sich ein wenig debug code ins git geschlichen.

Folgende Zeile Code muss in den beiden Dateien aus kommentiert werden (# am Anfang der Zeile) {{Link2Forum|Topic= 36407|Message=287499|LinkText=(Forum)}}.

Log3 ($hash, 1, "in $e");

: Zeile 325 in 31_fronthemDevice.pm
: Zeile 154 in 01_fronthem.pm

=== keine Events ===

Es gibt immer mal die Situation, dass man events unterdrückt und für eine spätere Anwendung in Zusammenhang mit einem Frontend, sich nicht mehr daran erinnert. Daher sollte bei ausbleiben eines entsprechenden Auslösung aus FHEM immer kontrolliert werden, dass die Events nicht durch event-min..., event-on..., etc. unterdrückt wird {{Link2Forum|Topic= 30909|Message=236073|LinkText=(Forum)}}.

=== keine GADs im Editor ===

Die GADs werden beim Aufruf einer Seite (in smartVISU) an fhem übertragen.
In smartVISU ein <code>ctrl+F5</code> ausführen, danach einen Seitenreload in fhem {{Link2Forum|Topic= 30909|Message=269984|LinkText=(Forum)}}.

Darüber hinaus ist bekannt, dass ein manuelles Editieren der fhem.cfg ebenfalls dazu führen kann, dass die Liste leer bleibt {{Link2Forum|Topic=43796|Message=357097|LinkText=(Forum)}}.

=== alte GADs löschen ===

Hat man einmal aus versehen einen Demoraum ausgewählt und vergessen den Treiber auf Offline zu stellen, füllt sich der GAD-Editor mit allen GADs aus dem Demoraum. Um diese wieder zu löschen gibt es entweder den Weg über den GAD-Editor (gad-Editor -> gad anklicken -> delete) oder die Möglichkeit direkt die fhserver.fronthem.cfg zu editieren {{Link2Forum|Topic=47281|Message=390051|LinkText=(Forum)}}.

Die Datei befindet sich unter ./fhem/www/fronthem/server/<devicename> {{Link2Forum|Topic=46214|Message=379959|LinkText=(Forum)}}.

=== VPN ===

Beim Zugriff durch einen VPN-Tunnel muss sichergestellt sein, dass der VPN-Tunnel sowohl Zugriff auf Port 8083 (FHEMWEB) als auch auf Port 2121 (fronthem) zulässt. Darüber hinaus wird einem per VPN angemeldeten Endgerät normalerweise eine andere interne IP-Adresse zugeordnet, als wenn das Endgerät sich im lokalen LAN befände {{Link2Forum|Topic= 30909|Message=281398|LinkText=(Forum)}}.

Für ein Script, dass variable fronthemDevices anlegt, sei auf diesen {{Link2Forum|Topic= 50328|Message=420580|LinkText=Forumsbeitrag}} verwiesen.

Ein weiterer Artikel, der sich mit dem Thema befasst, ist dieser {{Link2Forum|Topic= 50019|Message=417592|LinkText=Forumsbeitrag}}.

=== Ordner und Dateien ===
Auch wenn es im Normalfall nicht notwendig ist sollte, kann es manchmal sinnvoll sein, den genauen Speicherort der Module und Konfigurationsdateien zu kennen und entsprechend Debugging-Trigger hinzuzufügen oder Konfigurationen direkt zu korrigieren. Die folgenden Pfadangaben gehen davon aus, dass FHEM im Verzeichnis /opt/fhem/ installiert ist.

==== Konfigurationsdateien ====

Speicherort für Verbindung zwischen GADs und FHEM-Devices:
/opt/fhem/www/fronthem/server/fronthem/fhservr.<device>.cfg

Speicherort für Berechtigungen pro Endgerät:
/opt/fhem/www/fronthem/clients/<Endgerät-Device>

Logdatei des fronthem-Devices:
/opt/fhem/fronthem.err

==== Moduldateien ====
Modul für fronthem und die Verwaltung des Websocketservers:
/opt/fhem/FHEM/01_fronthem.pm

Modul für die fronthemDevices (Einbindung Endgeräte):
/opt/fhem/FHEM/31_fronthemDevice.pm

Modul mit den standardmäßigen Konvertern:
/opt/fhem/FHEM/fhconverter.pm

Optionales Modul für eigene Konverter:
/opt/fhem/FHEM/99_fronthemUtils.pm

Datei, die den GAD-Editor enthält:
/opt/fhem/www/frontend/pgm2/fronthemEditor.js

== Links ==
{{Link2Forum|Topic= 27291|Message=219207|LinkText=Detaillierte Funktionsbeschreibung}} aus der Entwicklungszeit.

{{Link2Forum|Topic=30909|Message=257681|LinkText=Addon-Treiber}} um eine weitere Steuerung Daten in SV zu visualisieren .

[[Kategorie:fronthem/smartVISU]]

Datei:Systemuebersicht fronthem smartVISU.jpg

2016-06-26T13:48:41Z

Joshi04: Systemübersicht der derzeitigen Zusammenhänge zwischen fronthem und smartVISU

Systemübersicht der derzeitigen Zusammenhänge zwischen fronthem und smartVISU

Diskussion:Installation Fronthem

2016-06-26T09:08:47Z

Joshi04:

Hallo Joshi04!
Sollte die Weiterleitung nicht besser bestehen bleiben? Der alte Seitentitel könnte aus bspw. aus dem Forum verlinkt sein. Ohne Weiterleitung landet man dann im "Nichts".
Gruß, --[[Benutzer:Krikan|Christian]] ([[Benutzer Diskussion:Krikan|Diskussion]]) 23:26, 25. Jun. 2016 (CEST)
:Hallo Christian, da hast Du natürlich recht. Ich denke, grundsätzlich müssen wir abwägen zwischen 1. Die Struktur des Wiki ist gut genug, dass auch ein toter Link aus dem Forum keine größere Hürde darstellt und 2. Wir behalten die "Dateileichen" in Form der Weiterleitungen, so dass auch die ältesten Verlinkungen noch funktionieren.
:MM ist der Forumsbereich noch relativ jung. Derzeit glaube ich ca. 4000 Posts, davon die Hälfte in nur einem Thread, den sich glaube ich niemand mehr durchlesen mag, wenn er bei der Suche im Wiki nach einem der Hauptbegriffe gleich fündig wird. Wenn das ganze mal so eingefahren ist, wie andere Bereiche, würde ich Dir in jedem Falle recht geben. Noch sehe ich allerdings die Gelegenheit, mit relativ wenig "zerbrochenem Geschirr" es in die richtige Richtung zu lenken. Mein Favorit wäre daher derzeit 2.: Zöpfe abschneiden.
:Das ist aber nur ein Vorschlag und ich kann auch damit leben, den Löscheintrag wieder zu entfernen. Entscheide gerne selbst nach Deiner Überzeugung.
:Die überarbeiteten Artikel "fronthem Installation", "smartVISU" und "smartVISU Installation" sind fast fertig, aber erst sinnvoll in Summe Online zu gehen.
:Schöne Grüße, --[[Benutzer:joshi04|John]] ([[Benutzer Diskussion:joshi04|Diskussion]]) 11:05, 26. Jun. 2016 (CEST)

Fronthem Installation

2016-06-25T16:34:12Z

Joshi04: Joshi04 verschob die Seite Installation Fronthem nach Fronthem Installation: Zur Optimierung der Auflistungsreihenfolge auf der Kategorieseite

Einen Überblick über Fronthem findet man auf der Seite zu [[Fronthem]]

== Allgemein ==
=== Fhem ===
Ein lauffähiges Fhem mit einem aktuellen Update sollte installiert sein.

=== Webserver ===
Für smartVISU muss ein Webserver (z.B. lighttpd oder Apache oder nginx) installiert sein.

==== lighttpd ====

sudo apt-get update
sudo apt-get install lighttpd
sudo apt-get install php5-common php5-cgi php5
cd /var/www
sudo lighty-enable-mod fastcgi-php
sudo service lighttpd force-reload
sudo chown www-data:www-data /var/www
sudo chmod 775 /var/www
sudo usermod -a -G www-data pi
sudo usermod -a -G www-data bananapi

==== nginx ====
Folgende Pakete werden benötigt:
$ apt-get install nginx php5-fpm

Die Konfiguration für nginx kann man unter
sudo nano /etc/nginx/sites-enabled/default
vornehmen.

Folgende Konfiguration sollte direkt funktionieren:
server {
listen 80;
root /var/www;
index index.html index.php;
server_name localhost;
location / {
try_files $uri $uri/ /index.php?$args;
}
location ~ \.php$ {
try_files $uri =404;
fastcgi_pass unix:/var/run/php5-fpm.sock;
fastcgi_index index.php;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
include fastcgi_params;
}
}

== Installation smartVISU ==
Die Installation stammt aus Jörg Herrmanns git-Repo: https://github.com/herrmannj/smartvisu-cleaninstall

Folgende Pakete werden benötigt:
$ apt-get install git

Hierbei handelt es sich um das original smartVISU inkl. diverser Anpassungen (fhem-Treiber, ...).

'''Download:'''
$ mkdir ~/install
$ cd ~/install
$ git clone https://github.com/herrmannj/smartvisu-cleaninstall.git

'''Installation:'''
$ sudo cp -rp smartvisu-cleaninstall /var/www/smartvisu
$ cd /var/www
$ sudo chown -R www-data:www-data smartvisu

'''Installation überprüfen:'''

Beim Aufruf der Seite http://<IP-Adresse>/smartvisu sollte folgende Seite angezeigt werden: {{Randnotiz|RNTyp=y|RNText=Wenn ihr hier einen Fehler erhaltet und euch nicht die SmartVisu Seite angezeigt wird müsst ihr die Datei "config.ini.default" zu "config.ini" umbenennen, am besten erstellt ihr eine neue Kopie wie folgt:
<code>$ sudo cp /var/www/smartvisu/config.ini.default /var/www/smartvisu/config.ini</code>
Ebenso bitte ggf. in der php.ini (error_reporting) die Ausgabe von Warnings abschalten, wenn so was kommt wie "Notice: Undefined index..."
}}

[[Datei:Installation_SmartVISU.png]]

== Installation Fronthem ==
Folgende Pakete werden benötigt:
curl -L https://cpanmin.us | perl - --sudo App::cpanminus
sudo cpanm Net::WebSocket::Server
sudo cpanm JSON

Mit folgendem Befehl kann man Fronthem installieren / updaten:
update force https://raw.githubusercontent.com/herrmannj/fronthem/master/controls_fronthem.txt

Konfiguration von Fronthem in Fhem (Eingabe in der Fhem Web Kommandozeile):
define <Name Webservice> fronthem
define <Name Endgerät> fronthemDevice <IP Endgerät>

Beispiel:
define meinfronthem fronthem
define meiniphone fronthemDevice 192.168.178.25

"Save" nicht vergessen!
Näheres dazu findet man auch unter http://www.fhemwiki.de/wiki/Fronthem#Basic_Syntax

== Eigenes smartVISU Projekt anlegen ==
* im Ordner "''/var/www/smartVISU/pages''" einen neuen Ordner "''MeinHaus"'' anlegen.
* aus dem Ordner "''../pages/_template''" alles in den neuen Ordner ("''/var/www/smartVISU/pages/MeinHaus"'') kopieren.
* "''rooms_menu.html''" an eigene Gegebenheiten anpassen hierzu dienen die "_template-Dateien" als Orientierung.
* alle rooms anlegen durch Kopien des Beispielraumes (''room_sleeping.html'') und passende icons und Überschriften verteilen. ([http://www.smartvisu.de/docu/2.7/index.php?page=design/design_icons SmartVisu Icons])
* SmartVISU nutzt [http://twig.sensiolabs.org/ Twig] als Template engine und die Seiten bestehen aus Blöcken und Widgets, die immer in doppelten geschweiften Klammern stehen <nowiki>{{ ... }}</nowiki>
* Widget Syntax auf [http://www.smartvisu.de/docu/2.7/index.php SmartVISU Doku] nachschlagen und kopieren.
* innerhalb eines Raums zwischen {% block content %} und {% endblock %} als Beispiel folgenden Abschnitt einfügen:

<pre><nowiki>
<h1><img class="icon" src='{{ icon0 }}scene_livingroom.png'/>Wohnzimmer</h1>
<div class="preblock">
</div>
<div class="block">
<div class="set-2" data-role="collapsible-set" data-theme="c" data-content-theme="a" data-mini="true">
<div data-role="collapsible" data-collapsed="false" >
<h3>Licht</h3>
<table width="90%">
<tr><td align="left" width="100px"> {{ basic.switch('Leselampe', 'Leselampe.sw', icon1~'light_floor_lamp.png', icon0~'light_floor_lamp.png') }}</td>
<td>Leselampe</td>
</tr>
</table>
</div>
</div>
</div>
</nowiki></pre>

* Datei speichern und checken, dass die Rechte mindestens auf "755" stehen, ansonsten mit "sudo chmod 755" korrigieren.
* smartVISU aufrufen, Zahnrad = configmenü, eigenes Haus auswählen (Ordnername!) und als Treiber DOMOTIGA (oder auch FHEM) mit Port 2121 mit der IP des FHEM-Servers
* speichern der Config nicht vergessen (Save ganz unten!)
* jetzt ist es wichtig, dass ihr einmal eure Seiten in Smartvisu aufruft damit im Hintergrund die GADs erstellt werden.
* In Fhem eure fronthemDevice Detailansicht öffnen
* Nun seht ihr eure GADs, aus der gadliste ein gad auswählen (hier: "Leselampe.sw" wie im obigen Code-Beispiel definiert.) und die Parameter vergeben:
<pre>
device: <fhem-Name-des-fhem-devices> (in diesem Fall die Leselampe.sw)
reading: state
converter: OnOff
cmd set: state
write: ja (haken setzen)
read: ja (haken setzen)
</pre>
: "state" immer klein schreiben und speichern nicht vergessen!
* Die Settings für das Device gelten für alle Endgeräte, aber die read/write Rechte müssen für jedes Endgerät separat gesetzt werden.

== Verbindung smartVISU mit Fhem ==
=== Konfiguration smartVISU-Treiber ===
==== Interface ====
TODO

==== I/O-Connection ====
Unter smartVISU in die Konfigurationsoberfläche wechseln (http://<IP-Adresse>/smartvisu/index.php?page=config)

Driver: ''Fhem'' (wird in Github von hermmanj bereitgestellt, falls smartvisu nicht von dort bezogen wird)

Adresse: ''<IP-Adresse Fhem-Server>''

Port: ''2121''

== Bekannte Probleme ==
TODO

[[Kategorie:HOWTOS]]
[[Kategorie:FHEM Frontends]]

Fronthem

2016-06-25T16:32:36Z

Joshi04: Groß/Kleinschreibung

{{Infobox Modul
|ModPurpose=Anbindung von externen Frontends an FHEM
|ModType=x


|ModForumArea=Sonstige Systeme
|ModTechName=01_fronthem.pm, 31_fronthemDevice.pm, fhconverter.pm, fronthemEditor.js
|ModOwner=[http://forum.fhem.de/index.php?action=profile;u=769 Jörg alias herrmannj]
}}

Dieser Artikel befasst sich mit den FHEM-Modulen und weiteren Dateien, die für die Integration von fronthem in FHEM notwendig sind. Die [[fronthem Installation|Installation von fronthem]] ist in einem separater Artikel beschrieben.

Alle Artikel zur Thematik fronthem/smartVISU sind [[:Kategorie:fronthem/smartVISU|hier]] kategorisiert.

----

Fronthem verfolgt die Idee, ein externes Web-Frontend (z. B. [[smartVISU]]) an fhem anzukoppeln und den Datenverkehr sowie die Zusammenarbeit von Befehlen und Parametern zwischen FHEM und dem Web-Frontend zu übernehmen.

Fronthem ist ein Projekt von herrmannj und wurde im {{Link2Forum|Topic= 27291|Message=27291.0l|LinkText=fhem-Forum}} erstmalig angekündigt.

Für die Installation eines passenden Web-Frontends (z.B. smartVISU), sowie dessen [[smartVISU Installation|Installation]] gibt es jeweils eigenständige Artikel.

__TOC__

{{Todo|Redaktionelle Überarbeitung der Detailbeschreibung für Readings Converter RGBCombined. Beschreibung der Converter ReadingsTimestamp, Attribute, Trigger.}}

Die Integration von fronthem als Interface innerhalb von FHEM besteht aus vier Bausteinen:

==Bausteine==
=== websocket ===
Der Websocket ist eine generische http-Schnittstelle, die von einem externen Frontend aus angesprochen werden kann.

Der Websocket Server wird durch das fhem-Modul "fronthem" automatisch gestartet, sobald ein Device vom TYPE <code>fronthem</code> definiert wurde. Der zugehörige Prozess läuft vom fhem Hauptprozess entkoppelt und kann mit ihm kommunizieren.

Der Websocket wird standardmäßig auf Port 2121 angesprochen, wird implizit durch die anderen Bausteine verwendet und benötigt im Prinzip keine weitere Beachtung, außer man möchte das Webinterface auf einem anderen Device neben FHEM laufen lassen.

Allerdings ist dieses das eigentliche Interface zwischen FHEM und einem externen Frontend.

Die Datei 01_fronthem.pm für dieses Modul liegt standardmäßig wie alle anderen Module im Ordner .../fhem/FHEM/.

=== device connector ===
Ein Device-Connector dient dazu, ein Endgerät eines Benutzers (PCs, Tablets, Smartphones usw.) als Clients zu konfigurieren und dessen Berechtigungen (read, write) auf der Ebene einzelner Objekte zu steuern. Damit können z. B. die Nachkommen oder Gäste zwar das Licht und die Heizung im eigenen Raum steuern, nicht aber die Programmierung der Heizung ändern oder den Alarm ausschalten.

Ein Endgerät wird dabei jeweils als Device vom TYPE <code>fromthemdevice</code> innerhalb von FHEM definiert. Details zur genauen Einrichtung finden sich im [[#Integration in FHEM|Verlauf]] dieses Artikels.

An einem einzelnen Device-Connector werden die durch den websocket vom externen Frontend mitgeteilten Objekte aufgelistet (GADs) und können dort einerseits mit fhem devices verbunden und andererseits in den Berechtigungen des jeweiligen Endgerätes konfiguriert werden.

Die Kombination der Frontend-items (GADs) mit den fhem-Devices über die Converter wird nur einmal benötigt und hat eine globale Gültigkeit. Die Berechtigungen der verwendeten Endgeräte werden jeweils pro Endgerät gesetzt. Details zum Konfigurieren und Duplizieren von Berechtigungen finden sich im weiteren [[#Integration in FHEM|Verlauf]] dieses Artikels. Auch eine Zugriffsberechtigung über eine PIN-Abfrage ist angedacht, bislang (Juni 2016) aber noch nicht implementiert.

Änderungen von Readings, Events werden dabei per {{Link2Forum|Topic= 27291|Message=209920l|LinkText=push}} auf die Devices verweilt.

Die Datei 31_fronthemDevice.pm für dieses Modul liegt standardmäßig wie alle anderen Module im Ordner .../fhem/FHEM/.

=== readings converter ===

Die readings converter dienen dazu, die Verbindung zwischen den Informationen in FHEM (states, readings, events) und den Formaten, die innerhalb des Frontends verwendet werden, herzustellen. Die Readings von FHEM müssen in die Form der möglichen Werte des Frontends umgewandelt werden. Im umgekehrten Fall müssen Befehle des Frontends in FHEM kompatible Befehle umgesetzt werden.

Über das Konzept der converter können FHEM-Devices unterschiedlichster Typen und Funktionen über das Frontend bedient werden. So versorgt der gleiche converter der die Solltemperatur des virtuellen Heizungsthermostats (bidriektional) einstellt auch die Füllstandanzeige der Zisterne sowie den Dimmer. In den genannten Fällen handelt es sich um die Übertragung von numerischen Werten. Converter können dabei auch Spezialaufgaben wie die Begrenzung des Wertebereichs übernehmen. So lässt sich über NumDirect zum Beispiel die Solltemperatur Einstellung für virtuelle Heizungsregler auf Min und Max Werte begrenzen.

Standardmäßig gibt es folgende Converter:
* [[#Direct]] für Übertragung ohne Konvertierung
* [[#NumDirect]] für Übertragung von Zahlenwerten in einem begrenzten Werteraum zwischen Min und Max
* [[#NumDisplay]] für Zahlenwerte aus fhem Readings, nur lesend
* [[#OnOff]] für Schalter, Übersetzung von On in 1 und Off in 0
* [[#RGBCombined]] für Übertragung von RGB-Werten so das sie FHEM akzeptiert
* [[#ReadingsTimestamp]] (vorhanden, Beschreibung TODO)
* [[#Attribute]] (vorhanden, Beschreibung TODO)
* [[#Trigger]] (vorhanden, Beschreibung TODO)

Weitere Readings Converter können darüber hinaus [[#eigene Converter|individuell selbst]] definiert werden.

Die Datei fhconverter.pm, die die oben genannten Converter enthält, liegt standardmäßig wie alle anderen Module im Ordner .../fhem/FHEM/.

Die hier beschriebenen Converter sind kompatibel mit dem oben erwähnten Frontend smartVISU und werden auf dessen Basis erklärt. Für die Verwendung in Kombination mit anderen Frontends müssen die Converter möglicher Weise entsprechend angepasst werden.

====Direct====
Die Werte werden ohne Konvertierung weitergegeben.

Gibt den Wert des von <reading> ohne weitere Wandlung an das Frontend weiter. In umgekehrter Richtung wird der vom Frontend geliefert Wert ohne Wandlung im hinterlegten <set> eingesetzt.

Beispiel:
:Anzeige eines An- oder Abwesenheitszustandes im Frontend (Textanzeige, Icon, Button)

====NumDirect====
NumDirect arbeitet bidirektional. Die Werte werden genau wie bei Direct ohne Umwandlung weitergegeben.

Der Unterschied zu Direct besteht jedoch darin, dass nur Zahlenwerte übergeben werden, d.h. die Zahlen werden aus <reading> herausgefiltert.

Des Weiteren kann man einen minimalen und maximalen Wert mit angeben. Dieses soll verhindern, dass im Frontend Werte eingestellt werden, die überhaupt keinen Sinn ergeben.

Beispiel:
:In der smartVISU könnte man für einen Raumthermostaten z.B. -100°C einstellen, was der Aktuator auf Seiten von FHEM nicht umsetzen kann (minimal einstellbarer Wert).

==== NumDisplay ====
NumDisplay arbeitet nur in eine Richting, von FHEM zum Frontend. Die Werte werden ohne Umwandlung weitergegeben, bis auf die Tatsache, dass wie beim Converter NumDirect nur Zahlenwerte übergeben werden, d.h. die Zahlen werden aus <reading> herausgefiltert.

Es ist dazu gedacht Zahlenwerte zu übergeben, ohne etwas zu verändern.

Beispiel:
: Anzeige des Raumklimas (Temperatur, Feuchtigkeit, CO2, Lautstärke, etc.)

==== OnOff ====

Dieser Converter ist für das einfache Schalten von Ein/Aus-Funktionen vorgesehen.

FHEM interpretiert Ein/Aus-Funktionen mit on/off, innerhalb von smartVISU entsprechen diese Zustände jedoch 1/0.

Der OnOff-Converter wandelt diese bidirektional ineinander um.

Beispiel:
: Schalter

==== RGBCombined ====
Dieser Converter dient zur Steuerung von RGB Leuchtmitteln über Farbauswahlfelder (zb. Farbkreis). Eine Besonderheit ist hier, dass smartVISU die 3 RGB Werte separat verarbeitet. D.h. von FHEM wird ein RGB-Wert in HEX in 3 Werte, jeweils für R, G und B, aufgeteilt und an das Frotnend übergeben. In umgekehrter Richtung wird die Auswahl einer Farbe im Frontend mit den 3 Werten für R, G und B an den Converter übergeben, kombiniert und an FHEM übergeben.

Entsprechend arbeitet er bidirektional und wandelt 3 Frontend Items in ein FHEM-Objekt um. Damit die Kombination der Werte funktioniert, muss dieser Converter gleichlautend für alle 3 RGB Kanäle des Frontends definiert werden.

reading: Name eines reading mit HEX RGB Wert des Leuchtmittels

converter (mit Parameter): <code>RGBCombined <itemRed>, <itemYellow>, <itemBlue></code>

set: Name des set Befehls, bekommt HEX RGB Wert übergeben

==== ReadingsTimestamp ====
Dieser Converter ist im Modul bereits enthalten, dessen Beschreibung ist allerdings TODO.

==== Attribute ====
Dieser Converter ist im Modul bereits enthalten, dessen Beschreibung ist allerdings TODO.

==== Trigger ====
Dieser Converter ist im Modul bereits enthalten, dessen Beschreibung ist allerdings TODO.

==== eigene Converter ====
Zusätzlich zu den bestehenden Convertern besteht die Möglichkeit, eigene zu definieren. Diese können in der 99_myUtils.pm oder einer neu angelegten 99_fronthemUtils.pm definiert werden. Es ist nicht ratsam, die fhconverter.pm dafür zu verwenden, da bei einem möglichen späteren Update diese Datei überschrieben wird. Wie alle anderen Module, muss sich die Datei im Verzeichnis./fhem/FHEM/ befinden. ({{Link2Forum|Topic= 30909|Message=266944|LinkText=Forum}})

Eigene Converter müssen nur die gleiche Signatur haben und in dem gleichen namespace wie die im fhconverter.pm stehen dann werden sie dynamisch geladen und stehen in fronthem zur Verfügung. ({{Link2Forum|Topic= 30909|Message=236070l|LinkText=Forum}})

==== Ideen für weitere Converter ====

Zwei weitere Converter sind angedacht, aber derzeit noch nicht Teil des Moduls.

===== NumDelayed =====
NumDelayed ist noch in Arbeit.

Ein bidirektionaler numerischer Converter mit einstellbarer Verzögerung.

Bietet bei der Ansteuerung mechanischer Aktoren (Markise, Jalousie) Vorteile gegenüber NumDirect. Als Beispiel sei die Steuerung einer Jalousie über einen Slider genannt. Da Slider ihre Werte kontinuierlich an FHEM übermitteln, würde bei der Verwendung anderer Converter dem entsprechenden Aktor (z.B. HM-BP), während der Benutzer den Slider bedient, mehrfach der vermeindliche Sollwert übermittelt werden. Gleichzeitig beginnt der Aktor seine Fahrt und übermittelt dem Slider seine aktuelle ist Position. Das führt zu einem springen des Sliders und einer "unschönen" Bedienung.

NumDelayed nimmt daher die Signale des Sliders entgegen, wartet jedoch mit der Weitergabe solange, bis sich der Slider (xxx ms, konfigurierbar) nicht mehr bewegt. In Gegenrichtung wird ebenso verfahren, erst wenn der Aktor seine Endposition erreicht, wird der Slider im Frontend aktualisiert. In diesem Beispiel würde das bedeuten das der Slider im Normalfall ohnehin so steht (Soll) wie vom Aktor gemeldet (Ist). Natürlich könnte der Benutzer oder ein Hindernis die Fahrt auch unterbrochen haben, dann würde der Slider auf die gemeldete Position aktualisiert.

===== WordDisplay =====
WordDisplay ist derzeit in Planung, es wird noch über die Umsetzung diskutiert.

Der Converter soll nur in eine Richtung arbeiten, FHEM zu Frontend. Es ist dazu gedacht Wörter oder Textpassagen zu übertragen. Jedoch soll es möglich sein, eine Umwandlung selbst festzulegen. So kann man einfach mehrere Textausgaben abhängig vom Zustand an das Frontend schicken:

Beispiel:
: Geofancy: Home -> Zuhause, Underway -> Unterwegs, Work -> Arbeit

=== fronthemEditor ===

Um einen komfortable Möglichkeit zur Verfügung zustellen, die Bindung und Konvertierung zwischen FHEM Device/Reading und Frontend-Objekt festzulegen, gibt es einen Javascript Editor als Erweiterung von FHEMWEB. Er wird durch die Datei fronthemEditor.js realisiert, die im Ordner .../fhem/www/frontend/pgm2/ abgelegt ist.

Sobald ein fronthemDevice (Definition für ein Endgerät) definiert ist, kann man über dessen Details in FHEMWEB die GADs definieren und die Rechte verteilen.

==== GAD Liste ====
Auf der Detailseite werden im oberen Teil die GADs aufgelistet die von smartVisu "angefragt" wurden. In vier Spalten werden von links der GAD-Name (wie auf der smartVISU-Seite definiert), das damit verbundene FHEM-Device, für das frontemDevice gesetzte Lese-Rechte und Schreib-Rechte angezeigt. Im oberen Teil des Fensters lässt sich eine Zeichenkette eingeben, nach der die Liste gefiltert wird. (Zumindest in Dark-Style hat die Schrift der eingegebenen Zeichenkette die gleiche Farbe wie der Hintergrund).

Die Verknüpfung zwischen GAD und FHEM-Device gilt global und muss nur einmal für ein beliebiges fronthemDevice eingerichtet werden. Lese- und Schreibrechte können pro fronthemDevice konfiguriert werden.

Wichtig zu berücksichtigen ist die Tatsache, dass die GAD-Liste erst dann aktualisiert wird, wenn einmal die entsprechende Frontend-Seite von einem frontendDevice aufgerufen wurde. Die korrekte Konfiguration des Treiber auf der Config-Seite für das frontendDevice (siehe Installation des Frontends) wird dabei vorausgesetzt. Die Liste wird also erst gefüllt, wenn erstmalig vom Frontend über einen Seitenaufruf die Verbindung zu FHEM initiiert wurde.

Auf der anderen Seite weiß fronthem nicht, welche GADs in smartVISU verwendet werden. Jedes GAD das einmal sichtbar war, wird von fronthem gespeichert und aufgelistet, bis man es explizizt in fronthem löscht. ({{Link2Forum|Topic= 43226|Message=352115|LinkText=Forum}})

==== GAD Edit ====
Klickt man auf einen GAD aus der obigen Liste, öffnet sich ein weiteres Feld mit Titel "GAD Edit".
Das Feld ist in 2 Teile aufgeteilt, im oberen das globale Mapping zwischen GAD und FHEM-Device/Reading, darunter die Zugriffsrechte für das jeweilige Device. Am unteren Ende des Feldes sind Schaltflächen für das Löschen und Sichern von GADs aus der Liste oder das Abbrechen der Bearbeitung angeordnet.

Die GAD-Definierung im oberen Bereich besteht aus:
[[Datei:DeviceDefine.png|400px|thumb|right|GADs definieren]]
*mode
*device
*reading
*converter
*cmd set

===== mode =====

Es gibt 2 Modi:
*item
*plot

Die Unterscheidung ist selbsterklärend, alles was kein "plot" werden soll, wird als "item" definiert.

===== device =====

Hier wird der Name des FHEM-Devices eingetragen, an das die Befehle geschickt werden, bzw. dessen Readings angezeigt werden sollen. Die vorhandenen Devices in fhem werden als Liste unter dem Eingabefeld angezeigt, sobald man mit der Eingabe beginnt.

Wie überall innerhalb von FHEM ist die Groß/Kleinschreibung zu beachten.

===== reading =====

Für das <reading> wird das zu verwendende Reading des FHEM Devices angegeben, z. B. "state" oder "Level". Die vorhandenen Readings des gewählten fhem-Devices werden als Liste unter dem Eingabefeld angezeigt, sobald man mit der Eingabe beginnt.

Änderungen, wenn fhem entsprechende events erzeugt, werden von fronthem mitgelesen und per push an die fronthemDevices gesendet.

===== converter =====

Hier gibt man denn Namen des Converters an, denn man verwenden möchte. Wie oben beschrieben, stehen unterschiedliche [[#readings converter|converter]] für verschiedene Aufgabenstellungen zur Verfügung. Die meisten Devices können mit diesen Convertern angesteuert werden.

Wie überall innerhalb von FHEM ist die Groß/Kleinschreibung zu beachten.

===== cmd set =====

Das zum Schreiben zu verwendende Reading des fhem Devices, z. B. "state" oder "Level". Die vorhandenen Readings des gewählten fhem-Devices werden als Liste unter dem Eingabefeld angezeigt, sobald man mit der Eingabe beginnt.

Das gewählte Reading gibt den "set" des fhem Devices an, der die Rückgabe des Converters entgegen nimmt.

Bei Lampe z.B. "state".

==== Devicerechte vergeben ====

[[Datei:DeviceRechte.png|400px|thumb|right|Devicerechte vergeben]]
Devicerechte bestehen aus:
*Eine Berechtigung für "read"
*Eine Berechtigung für "write"
*Jeweils für Lese- und Schreib-Berechtigung die Festlegung eines PINs

===== read =====
Das Device darf die Statuswerte auslesen.

===== write =====
Das Device darf Statuswerte ändern.

===== PIN GAD =====

Die PIN-Abfrage für die Lese- oder Schreibberechtigung ist derzeit noch nicht implementiert, daher ist es irrelevant, was hier eingetragen wird.

===== Attribut Whitelist =====
Möchte man die differenzierte Berechtigungssteuerung für ein fronthemDevice außer Kraft setzen, kann das Attribut "whitelist" für das entsprechende fronthemDevice auf false gesetzt werden. Das bedeutet dann, dass unabhängig von den Berechtigungs-Checkboxen das fronthemDevice immer für alle GADs lesen und schreiben darf.

== Integration in FHEM ==

=== fronthem ===

Ein Device vom TYPE <code>fronthem</code> und damit das eigentlich Interface, wird nach erfolgreicher Sicherstellung der Voraussetzungen (siehe fronthem Installation) über folgenden Befehl in der Eingabezeile von FHEMWEB definiert:
:<code>define <name> fronthem</code>

Über diese Definition wird ebenfalls die Verbindung zum WebSocket sichergestellt. Logischer Weise benötigt man nur ein Device von diesem Typ.

Als Reading wird
* die Verbindung zum WebSocket angezeigt. "open" stellt dabei den normalen Zustand dar.
* lastError angezeigt, woran man beispielsweise erkennen kann, dass für Endgerät der Zugriff abgelehnt wurde ("client <IP-Adress> rejected").

Der state des Devices gibt dabei derzeit keine Meldung zurück. Ein Wert "???" ist daher kein Hinweis auf einen Fehler, sondern entspricht dem ganz normalen Modulverhalten.

===Device Connector===
Für jedes Endgerät (smartphone, PC, Tablet, etc.) mit dem man auf das Frontend zugreifen möchte, muss ein entsprechendes fronthemDevice definiert werden.
Wie oben bereits beschrieben, kann dadurch genau festgelegt werden, welches Endgerät welche Rechte für eine jeweilige Schalt-/Anzeigefunktion hat.

Wenn man die Berechtigungen für neue Endgeräte kopieren möchte, liegen diese für jedes Endgerät unter ./fhem/www/fronthem/clients/<fronthemDevice> und lassen sich so einfach für neue Endgeräte übertragen.

====IP-Identify====

Ein Endgerät wird über seine IP_Adresse identifiziert. Dies ist nur im internen gesicherten Netzwerk empfehlenswert. Es wird definiert mit:
:<code>define <device> fronthemDevice <ip></code>

Dabei ist für die IP-Adresse die des Endgerätes anzugeben, welches auf den smartVISU zugreifen soll (also das Tablet, Rechner, Smartphone etc.). Entsprechend selbstverständlich ist, dass man durch eine passende Einstellung seine DHCP-Servers oder fest vergebene IP-Adressen sicherstellt, dass ein Endgerät immer die gleiche IP erhält/verwendet.

Wichtig bei der späteren Verwendung ist, dass pro Endgerät immer nur ein Brower-Tab geöffnet wird, mit dem man auf das Frontend zugreift. Sonst erhält fronthem mehrere Zugriffe von der gleichen IP, die sich gegenseitig ins Gehege kommen.

====Zertificate-Identify====
{{Randnotiz|RNTyp=info|RNText=Hinweis: Diese Möglichkeit wurde während der Entwicklung bereits diskutiert und berücksichtigt, die Verwendung von Zertifikaten wurde bislang aber noch nicht implementiert, hauptsächlich aufgrund der teilweise mangelnden oder zumindest sehr unterschiedlichen Unterstützung von Zertifikaten auf Endgeräte-Seite (z.B. webviewcontrol).
}}

Das Endgerät wird über ein Zertifikat identifiziert.
Zuerst wird ein Zertifikat generiert, welches dann auf dem Endgerät installiert werden muss.

Diese Methode der Identifizierung verspricht höhere Sicherheit, wie auch denn Vorteil, das man sich nicht einloggen muss.

==Troubleshooting==
=== allgemeines Vorgehen ===

Generelles Vorgehen bei seltsamen Erscheinungen:
* smartVISU-Page-Cache ausschalten (auf der Config Seite von smartVISU, wo auch der Treiber konfiguriert wird)
* smartVISU-temp-Verzeichnis leeren (e.g. /var/www/html/smartvisu/temp)
* Browser neu starten
* Konsole im Browser öffnen und nach Errors schauen
* Verbose Level des FHEM-Device <code>fronthem</code> und <code>fronthemDevice</code> auf 5 setzen und im Log nach Errors schauen
* Den Log des Webservers kontrollieren
* Prüfen, ob der WebSocket läuft
{{Link2Forum|Topic= 30909|Message=272083|LinkText=Forum}}, {{Link2Forum|Topic= 35960|Message=285384|LinkText=Forum}}, {{Link2Forum|Topic= 52624|Message=444004|LinkText=Forum}}

=== Verbindung ===

Erhält an eine "no connection" Warnung in smartVISU sollte man folgendes kontrollieren:
* Wurde auf der config-Seite von smartVISU auf dem Endgerät der Treiber auf "Fhem" gestellt?
* Ist auf der config-Seite von smartVISU auf dem Endgerät die richtige Adresse des WebSocket Servers (meistens der Server mit der FHEM-Instanz) und der Port 2121 eingetragen?
* Wurde für das fronthemDevice die richtige IP-Adresse definiert?
* Steht "connected" im state des fronthemDevice ?
{{Link2Forum|Topic= 30909|Message=236681|LinkText=Forum}}

Darüber hinaus wird Websocket erst ab Android 4.4 einwandfrei unterstützt {{Link2Forum|Topic= 39587|Message=318219|LinkText=Forum}}.

Ebenfalls das iPad 1G wird nicht mehr unterstützt {{Link2Forum|Topic= 46737|Message=384727|LinkText=Forum}}.

=== alternativer Treiber zum loggen auf der Konsole ===

Falls mal ein Widget den Websocket Server zum Absturz bringt, was mittlerweile nicht mehr passieren sollte, wurde im {{Link2Forum|Topic= 30909|Message=273617|LinkText=Forum}} ein Treiber veröffentlich, der das "überlebt" und auf der Konsole weiter loggt, welches Widget es verursacht hat.

=== Logmeldungen ===

Da die Module noch inoffiziell sind, hat sich ein wenig debug code ins git geschlichen.

Folgende Zeile Code muss in den beiden Dateien aus kommentiert werden (# am Anfang der Zeile).

Log3 ($hash, 1, "in $e");

: Zeile 325 in 31_fronthemDevice.pm
: Zeile 154 in 01_fronthem.pm

{{Link2Forum|Topic= 36407|Message=287499|LinkText=Forum}}

=== keine Events ===

Es gibt immer mal die Situation, dass man events unterdrückt und für eine spätere Anwendung in Zusammenhang mit einem Frontend, sich nicht mehr daran erinnert. Daher sollte bei ausbleiben eines entsprechenden Auslösung aus FHEM immer kontrolliert werden, dass die Events nicht durch event-min..., event-on..., etc. unterdrückt wird. {{Link2Forum|Topic= 30909|Message=236073|LinkText=Forum}}

=== keine GADs im Editor ===

Die GADs werden beim Aufruf einer Seite (in smartVISU) an fhem übertragen.
In smartVISU ein <code>ctrl+F5</code> ausführen, danach einen Seitenreload in fhem.
{{Link2Forum|Topic= 30909|Message=269984|LinkText=Forum}}

Darüber hinaus ist bekannt, dass ein manuelles Editieren der fhem.cfg ebenfalls dazu führen kann, dass die Liste leer bleibt.
{{Link2Forum|Topic=43796|Message=357097|LinkText=Forum}}

=== alte GADs löschen ===

Hat man einmal aus versehen einen Demoraum ausgewählt und vergessen den Treiber auf Offline zu stellen, füllt sich der GAD-Editor mit allen GADs aus dem Demoraum. Um diese wieder zu löschen gibt es entweder den Weg über den GAD-Editor (gad-Editor -> gad anklicken -> delete) oder die Möglichkeit direkt die fhserver.fronthem.cfg zu editieren. {{Link2Forum|Topic=47281|Message=390051|LinkText=Forum}}

Die Datei befindet sich unter ./fhem/www/fronthem/server/<devicename>. {{Link2Forum|Topic=46214|Message=379959|LinkText=Forum}}

=== VPN ===

Beim Zugriff durch einen VPN-Tunnel muss sichergestellt sein, dass der VPN-Tunnel sowohl Zugriff auf Port 8083 (FHEMWEB) als auch auf Port 2121 (fronthem) zulässt. Darüber hinaus wird einem per VPN angemeldeten Endgerät normalerweise eine andere interne IP-Adresse zugeordnet, als wenn das Endgerät sich im lokalen LAN befände. {{Link2Forum|Topic= 30909|Message=281398|LinkText=Forum}}

Für ein Script, dass variable fronthemDevices anlegt, sei auf diesen {{Link2Forum|Topic= 50328|Message=420580|LinkText=Forumsbeitrag}} verwiesen.

Ein weiterer Artikel, der sich mit dem Thema befasst, ist dieser {{Link2Forum|Topic= 50019|Message=417592|LinkText=Forumsbeitrag}}.

== Links ==
{{Link2Forum|Topic= 27291|Message=219207|LinkText=Detaillierte Funktionsbeschreibung}} aus der Entwicklungszeit.

{{Link2Forum|Topic=30909|Message=257681|LinkText=Addon-Treiber}} um eine weitere Steuerung Daten in SV zu visualisieren .

[[Kategorie:fronthem/smartVISU]]

Fronthem

2016-06-25T16:25:23Z

Joshi04: Link angepasst zur Verschiebung von "Installation fronthem" nach "fronthem Installation"

{{Infobox Modul
|ModPurpose=Anbindung von externen Frontends an FHEM
|ModType=x


|ModForumArea=Sonstige Systeme
|ModTechName=01_fronthem.pm, 31_fronthemDevice.pm, fhconverter.pm, fronthemEditor.js
|ModOwner=[http://forum.fhem.de/index.php?action=profile;u=769 Jörg alias herrmannj]
}}

Dieser Artikel befasst sich mit den FHEM-Modulen und weiteren Dateien, die für die Integration von fronthem in FHEM notwendig sind. Die [[Fronthem Installation|Installation von fronthem]] ist in einem separater Artikel beschrieben.

Alle Artikel zur Thematik fronthem/smartVISU sind [[:Kategorie:fronthem/smartVISU|hier]] kategorisiert.

----

Fronthem verfolgt die Idee, ein externes Web-Frontend (z. B. [[smartVISU]]) an fhem anzukoppeln und den Datenverkehr sowie die Zusammenarbeit von Befehlen und Parametern zwischen FHEM und dem Web-Frontend zu übernehmen.

Fronthem ist ein Projekt von herrmannj und wurde im {{Link2Forum|Topic= 27291|Message=27291.0l|LinkText=fhem-Forum}} erstmalig angekündigt.

Für die Installation eines passenden Web-Frontends (z.B. smartVISU), sowie dessen [[smartVISU Installation|Installation]] gibt es jeweils eigenständige Artikel.

__TOC__

{{Todo|Redaktionelle Überarbeitung der Detailbeschreibung für Readings Converter RGBCombined. Beschreibung der Converter ReadingsTimestamp, Attribute, Trigger.}}

Die Integration von fronthem als Interface innerhalb von FHEM besteht aus vier Bausteinen:

==Bausteine==
=== websocket ===
Der Websocket ist eine generische http-Schnittstelle, die von einem externen Frontend aus angesprochen werden kann.

Der Websocket Server wird durch das fhem-Modul "fromthem" automatisch gestartet, sobald ein Device vom TYPE <code>fronthem</code> definiert wurde. Der zugehörige Prozess läuft vom fhem Hauptprozess entkoppelt und kann mit ihm kommunizieren.

Der Websocket wird standardmäßig auf Port 2121 angesprochen, wird implizit durch die anderen Bausteine verwendet und benötigt im Prinzip keine weitere Beachtung, außer man möchte das Webinterface auf einem anderen Device neben FHEM laufen lassen.

Allerdings ist dieses das eigentliche Interface zwischen FHEM und einem externen Frontend.

Die Datei 01_fronthem.pm für dieses Modul liegt standardmäßig wie alle anderen Module im Ordner .../fhem/FHEM/.

=== device connector ===
Ein Device-Connector dient dazu, ein Endgerät eines Benutzers (PCs, Tablets, Smartphones usw.) als Clients zu konfigurieren und dessen Berechtigungen (read, write) auf der Ebene einzelner Objekte zu steuern. Damit können z. B. die Nachkommen oder Gäste zwar das Licht und die Heizung im eigenen Raum steuern, nicht aber die Programmierung der Heizung ändern oder den Alarm ausschalten.

Ein Endgerät wird dabei jeweils als Device vom TYPE <code>fromthemdevice</code> innerhalb von FHEM definiert. Details zur genauen Einrichtung finden sich im [[#Integration in FHEM|Verlauf]] dieses Artikels.

An einem einzelnen Device-Connector werden die durch den websocket vom externen Frontend mitgeteilten Objekte aufgelistet (GADs) und können dort einerseits mit fhem devices verbunden und andererseits in den Berechtigungen des jeweiligen Endgerätes konfiguriert werden.

Die Kombination der Frontend-items (GADs) mit den fhem-Devices über die Converter wird nur einmal benötigt und hat eine globale Gültigkeit. Die Berechtigungen der verwendeten Endgeräte werden jeweils pro Endgerät gesetzt. Details zum Konfigurieren und Duplizieren von Berechtigungen finden sich im weiteren [[#Integration in FHEM|Verlauf]] dieses Artikels. Auch eine Zugriffsberechtigung über eine PIN-Abfrage ist angedacht, bislang (Juni 2016) aber noch nicht implementiert.

Änderungen von Readings, Events werden dabei per {{Link2Forum|Topic= 27291|Message=209920l|LinkText=push}} auf die Devices verweilt.

Die Datei 31_fronthemDevice.pm für dieses Modul liegt standardmäßig wie alle anderen Module im Ordner .../fhem/FHEM/.

=== readings converter ===

Die readings converter dienen dazu, die Verbindung zwischen den Informationen in FHEM (states, readings, events) und den Formaten, die innerhalb des Frontends verwendet werden, herzustellen. Die Readings von FHEM müssen in die Form der möglichen Werte des Frontends umgewandelt werden. Im umgekehrten Fall müssen Befehle des Frontends in FHEM kompatible Befehle umgesetzt werden.

Über das Konzept der converter können FHEM-Devices unterschiedlichster Typen und Funktionen über das Frontend bedient werden. So versorgt der gleiche converter der die Solltemperatur des virtuellen Heizungsthermostats (bidriektional) einstellt auch die Füllstandanzeige der Zisterne sowie den Dimmer. In den genannten Fällen handelt es sich um die Übertragung von numerischen Werten. Converter können dabei auch Spezialaufgaben wie die Begrenzung des Wertebereichs übernehmen. So lässt sich über NumDirect zum Beispiel die Solltemperatur Einstellung für virtuelle Heizungsregler auf Min und Max Werte begrenzen.

Standardmäßig gibt es folgende Converter:
* [[#Direct]] für Übertragung ohne Konvertierung
* [[#NumDirect]] für Übertragung von Zahlenwerten in einem begrenzten Werteraum zwischen Min und Max
* [[#NumDisplay]] für Zahlenwerte aus fhem Readings, nur lesend
* [[#OnOff]] für Schalter, Übersetzung von On in 1 und Off in 0
* [[#RGBCombined]] für Übertragung von RGB-Werten so das sie FHEM akzeptiert
* [[#ReadingsTimestamp]] (vorhanden, Beschreibung TODO)
* [[#Attribute]] (vorhanden, Beschreibung TODO)
* [[#Trigger]] (vorhanden, Beschreibung TODO)

Weitere Readings Converter können darüber hinaus [[#eigene Converter|individuell selbst]] definiert werden.

Die Datei fhconverter.pm, die die oben genannten Converter enthält, liegt standardmäßig wie alle anderen Module im Ordner .../fhem/FHEM/.

Die hier beschriebenen Converter sind kompatibel mit dem oben erwähnten Frontend smartVISU und werden auf dessen Basis erklärt. Für die Verwendung in Kombination mit anderen Frontends müssen die Converter möglicher Weise entsprechend angepasst werden.

====Direct====
Die Werte werden ohne Konvertierung weitergegeben.

Gibt den Wert des von <reading> ohne weitere Wandlung an das Frontend weiter. In umgekehrter Richtung wird der vom Frontend geliefert Wert ohne Wandlung im hinterlegten <set> eingesetzt.

Beispiel:
:Anzeige eines An- oder Abwesenheitszustandes im Frontend (Textanzeige, Icon, Button)

====NumDirect====
NumDirect arbeitet bidirektional. Die Werte werden genau wie bei Direct ohne Umwandlung weitergegeben.

Der Unterschied zu Direct besteht jedoch darin, dass nur Zahlenwerte übergeben werden, d.h. die Zahlen werden aus <reading> herausgefiltert.

Des Weiteren kann man einen minimalen und maximalen Wert mit angeben. Dieses soll verhindern, dass im Frontend Werte eingestellt werden, die überhaupt keinen Sinn ergeben.

Beispiel:
:In der smartVISU könnte man für einen Raumthermostaten z.B. -100°C einstellen, was der Aktuator auf Seiten von FHEM nicht umsetzen kann (minimal einstellbarer Wert).

==== NumDisplay ====
NumDisplay arbeitet nur in eine Richting, von FHEM zum Frontend. Die Werte werden ohne Umwandlung weitergegeben, bis auf die Tatsache, dass wie beim Converter NumDirect nur Zahlenwerte übergeben werden, d.h. die Zahlen werden aus <reading> herausgefiltert.

Es ist dazu gedacht Zahlenwerte zu übergeben, ohne etwas zu verändern.

Beispiel:
: Anzeige des Raumklimas (Temperatur, Feuchtigkeit, CO2, Lautstärke, etc.)

==== OnOff ====

Dieser Converter ist für das einfache Schalten von Ein/Aus-Funktionen vorgesehen.

FHEM interpretiert Ein/Aus-Funktionen mit on/off, innerhalb von smartVISU entsprechen diese Zustände jedoch 1/0.

Der OnOff-Converter wandelt diese bidirektional ineinander um.

Beispiel:
: Schalter

==== RGBCombined ====
Dieser Converter dient zur Steuerung von RGB Leuchtmitteln über Farbauswahlfelder (zb. Farbkreis). Eine Besonderheit ist hier, dass smartVISU die 3 RGB Werte separat verarbeitet. D.h. von FHEM wird ein RGB-Wert in HEX in 3 Werte, jeweils für R, G und B, aufgeteilt und an das Frotnend übergeben. In umgekehrter Richtung wird die Auswahl einer Farbe im Frontend mit den 3 Werten für R, G und B an den Converter übergeben, kombiniert und an FHEM übergeben.

Entsprechend arbeitet er bidirektional und wandelt 3 Frontend Items in ein FHEM-Objekt um. Damit die Kombination der Werte funktioniert, muss dieser Converter gleichlautend für alle 3 RGB Kanäle des Frontends definiert werden.

reading: Name eines reading mit HEX RGB Wert des Leuchtmittels

converter (mit Parameter): <code>RGBCombined <itemRed>, <itemYellow>, <itemBlue></code>

set: Name des set Befehls, bekommt HEX RGB Wert übergeben

==== ReadingsTimestamp ====
Dieser Converter ist im Modul bereits enthalten, dessen Beschreibung ist allerdings TODO.

==== Attribute ====
Dieser Converter ist im Modul bereits enthalten, dessen Beschreibung ist allerdings TODO.

==== Trigger ====
Dieser Converter ist im Modul bereits enthalten, dessen Beschreibung ist allerdings TODO.

==== eigene Converter ====
Zusätzlich zu den bestehenden Convertern besteht die Möglichkeit, eigene zu definieren. Diese können in der 99_myUtils.pm oder einer neu angelegten 99_fronthemUtils.pm definiert werden. Es ist nicht ratsam, die fhconverter.pm dafür zu verwenden, da bei einem möglichen späteren Update diese Datei überschrieben wird. Wie alle anderen Module, muss sich die Datei im Verzeichnis./fhem/FHEM/ befinden. ({{Link2Forum|Topic= 30909|Message=266944|LinkText=Forum}})

Eigene Converter müssen nur die gleiche Signatur haben und in dem gleichen namespace wie die im fhconverter.pm stehen dann werden sie dynamisch geladen und stehen in fronthem zur Verfügung. ({{Link2Forum|Topic= 30909|Message=236070l|LinkText=Forum}})

==== Ideen für weitere Converter ====

Zwei weitere Converter sind angedacht, aber derzeit noch nicht Teil des Moduls.

===== NumDelayed =====
NumDelayed ist noch in Arbeit.

Ein bidirektionaler numerischer Converter mit einstellbarer Verzögerung.

Bietet bei der Ansteuerung mechanischer Aktoren (Markise, Jalousie) Vorteile gegenüber NumDirect. Als Beispiel sei die Steuerung einer Jalousie über einen Slider genannt. Da Slider ihre Werte kontinuierlich an FHEM übermitteln, würde bei der Verwendung anderer Converter dem entsprechenden Aktor (z.B. HM-BP), während der Benutzer den Slider bedient, mehrfach der vermeindliche Sollwert übermittelt werden. Gleichzeitig beginnt der Aktor seine Fahrt und übermittelt dem Slider seine aktuelle ist Position. Das führt zu einem springen des Sliders und einer "unschönen" Bedienung.

NumDelayed nimmt daher die Signale des Sliders entgegen, wartet jedoch mit der Weitergabe solange, bis sich der Slider (xxx ms, konfigurierbar) nicht mehr bewegt. In Gegenrichtung wird ebenso verfahren, erst wenn der Aktor seine Endposition erreicht, wird der Slider im Frontend aktualisiert. In diesem Beispiel würde das bedeuten das der Slider im Normalfall ohnehin so steht (Soll) wie vom Aktor gemeldet (Ist). Natürlich könnte der Benutzer oder ein Hindernis die Fahrt auch unterbrochen haben, dann würde der Slider auf die gemeldete Position aktualisiert.

===== WordDisplay =====
WordDisplay ist derzeit in Planung, es wird noch über die Umsetzung diskutiert.

Der Converter soll nur in eine Richtung arbeiten, FHEM zu Frontend. Es ist dazu gedacht Wörter oder Textpassagen zu übertragen. Jedoch soll es möglich sein, eine Umwandlung selbst festzulegen. So kann man einfach mehrere Textausgaben abhängig vom Zustand an das Frontend schicken:

Beispiel:
: Geofancy: Home -> Zuhause, Underway -> Unterwegs, Work -> Arbeit

=== fronthemEditor ===

Um einen komfortable Möglichkeit zur Verfügung zustellen, die Bindung und Konvertierung zwischen FHEM Device/Reading und Frontend-Objekt festzulegen, gibt es einen Javascript Editor als Erweiterung von FHEMWEB. Er wird durch die Datei fronthemEditor.js realisiert, die im Ordner .../fhem/www/frontend/pgm2/ abgelegt ist.

Sobald ein fronthemDevice (Definition für ein Endgerät) definiert ist, kann man über dessen Details in FHEMWEB die GADs definieren und die Rechte verteilen.

==== GAD Liste ====
Auf der Detailseite werden im oberen Teil die GADs aufgelistet die von smartVisu "angefragt" wurden. In vier Spalten werden von links der GAD-Name (wie auf der smartVISU-Seite definiert), das damit verbundene FHEM-Device, für das frontemDevice gesetzte Lese-Rechte und Schreib-Rechte angezeigt. Im oberen Teil des Fensters lässt sich eine Zeichenkette eingeben, nach der die Liste gefiltert wird. (Zumindest in Dark-Style hat die Schrift der eingegebenen Zeichenkette die gleiche Farbe wie der Hintergrund).

Die Verknüpfung zwischen GAD und FHEM-Device gilt global und muss nur einmal für ein beliebiges fronthemDevice eingerichtet werden. Lese- und Schreibrechte können pro fronthemDevice konfiguriert werden.

Wichtig zu berücksichtigen ist die Tatsache, dass die GAD-Liste erst dann aktualisiert wird, wenn einmal die entsprechende Frontend-Seite von einem frontendDevice aufgerufen wurde. Die korrekte Konfiguration des Treiber auf der Config-Seite für das frontendDevice (siehe Installation des Frontends) wird dabei vorausgesetzt. Die Liste wird also erst gefüllt, wenn erstmalig vom Frontend über einen Seitenaufruf die Verbindung zu FHEM initiiert wurde.

Auf der anderen Seite weiß fronthem nicht, welche GADs in smartVISU verwendet werden. Jedes GAD das einmal sichtbar war, wird von fronthem gespeichert und aufgelistet, bis man es explizizt in fronthem löscht. ({{Link2Forum|Topic= 43226|Message=352115|LinkText=Forum}})

==== GAD Edit ====
Klickt man auf einen GAD aus der obigen Liste, öffnet sich ein weiteres Feld mit Titel "GAD Edit".
Das Feld ist in 2 Teile aufgeteilt, im oberen das globale Mapping zwischen GAD und FHEM-Device/Reading, darunter die Zugriffsrechte für das jeweilige Device. Am unteren Ende des Feldes sind Schaltflächen für das Löschen und Sichern von GADs aus der Liste oder das Abbrechen der Bearbeitung angeordnet.

Die GAD-Definierung im oberen Bereich besteht aus:
[[Datei:DeviceDefine.png|400px|thumb|right|GADs definieren]]
*mode
*device
*reading
*converter
*cmd set

===== mode =====

Es gibt 2 Modi:
*item
*plot

Die Unterscheidung ist selbsterklärend, alles was kein "plot" werden soll, wird als "item" definiert.

===== device =====

Hier wird der Name des FHEM-Devices eingetragen, an das die Befehle geschickt werden, bzw. dessen Readings angezeigt werden sollen. Die vorhandenen Devices in fhem werden als Liste unter dem Eingabefeld angezeigt, sobald man mit der Eingabe beginnt.

Wie überall innerhalb von FHEM ist die Groß/Kleinschreibung zu beachten.

===== reading =====

Für das <reading> wird das zu verwendende Reading des FHEM Devices angegeben, z. B. "state" oder "Level". Die vorhandenen Readings des gewählten fhem-Devices werden als Liste unter dem Eingabefeld angezeigt, sobald man mit der Eingabe beginnt.

Änderungen, wenn fhem entsprechende events erzeugt, werden von fronthem mitgelesen und per push an die fronthemDevices gesendet.

===== converter =====

Hier gibt man denn Namen des Converters an, denn man verwenden möchte. Wie oben beschrieben, stehen unterschiedliche [[#readings converter|converter]] für verschiedene Aufgabenstellungen zur Verfügung. Die meisten Devices können mit diesen Convertern angesteuert werden.

Wie überall innerhalb von FHEM ist die Groß/Kleinschreibung zu beachten.

===== cmd set =====

Das zum Schreiben zu verwendende Reading des fhem Devices, z. B. "state" oder "Level". Die vorhandenen Readings des gewählten fhem-Devices werden als Liste unter dem Eingabefeld angezeigt, sobald man mit der Eingabe beginnt.

Das gewählte Reading gibt den "set" des fhem Devices an, der die Rückgabe des Converters entgegen nimmt.

Bei Lampe z.B. "state".

==== Devicerechte vergeben ====

[[Datei:DeviceRechte.png|400px|thumb|right|Devicerechte vergeben]]
Devicerechte bestehen aus:
*Eine Berechtigung für "read"
*Eine Berechtigung für "write"
*Jeweils für Lese- und Schreib-Berechtigung die Festlegung eines PINs

===== read =====
Das Device darf die Statuswerte auslesen.

===== write =====
Das Device darf Statuswerte ändern.

===== PIN GAD =====

Die PIN-Abfrage für die Lese- oder Schreibberechtigung ist derzeit noch nicht implementiert, daher ist es irrelevant, was hier eingetragen wird.

===== Attribut Whitelist =====
Möchte man die differenzierte Berechtigungssteuerung für ein fronthemDevice außer Kraft setzen, kann das Attribut "whitelist" für das entsprechende fronthemDevice auf false gesetzt werden. Das bedeutet dann, dass unabhängig von den Berechtigungs-Checkboxen das fronthemDevice immer für alle GADs lesen und schreiben darf.

== Integration in FHEM ==

=== fronthem ===

Ein Device vom TYPE <code>fronthem</code> und damit das eigentlich Interface, wird nach erfolgreicher Sicherstellung der Voraussetzungen (siehe fronthem Installation) über folgenden Befehl in der Eingabezeile von FHEMWEB definiert:
:<code>define <name> fronthem</code>

Über diese Definition wird ebenfalls die Verbindung zum WebSocket sichergestellt. Logischer Weise benötigt man nur ein Device von diesem Typ.

Als Reading wird
* die Verbindung zum WebSocket angezeigt. "open" stellt dabei den normalen Zustand dar.
* lastError angezeigt, woran man beispielsweise erkennen kann, dass für Endgerät der Zugriff abgelehnt wurde ("client <IP-Adress> rejected").

Der state des Devices gibt dabei derzeit keine Meldung zurück. Ein Wert "???" ist daher kein Hinweis auf einen Fehler, sondern entspricht dem ganz normalen Modulverhalten.

===Device Connector===
Für jedes Endgerät (smartphone, PC, Tablet, etc.) mit dem man auf das Frontend zugreifen möchte, muss ein entsprechendes fronthemDevice definiert werden.
Wie oben bereits beschrieben, kann dadurch genau festgelegt werden, welches Endgerät welche Rechte für eine jeweilige Schalt-/Anzeigefunktion hat.

Wenn man die Berechtigungen für neue Endgeräte kopieren möchte, liegen diese für jedes Endgerät unter ./fhem/www/fronthem/clients/<fronthemDevice> und lassen sich so einfach für neue Endgeräte übertragen.

====IP-Identify====

Ein Endgerät wird über seine IP_Adresse identifiziert. Dies ist nur im internen gesicherten Netzwerk empfehlenswert. Es wird definiert mit:
:<code>define <device> fronthemDevice <ip></code>

Dabei ist für die IP-Adresse die des Endgerätes anzugeben, welches auf den smartVISU zugreifen soll (also das Tablet, Rechner, Smartphone etc.). Entsprechend selbstverständlich ist, dass man durch eine passende Einstellung seine DHCP-Servers oder fest vergebene IP-Adressen sicherstellt, dass ein Endgerät immer die gleiche IP erhält/verwendet.

Wichtig bei der späteren Verwendung ist, dass pro Endgerät immer nur ein Brower-Tab geöffnet wird, mit dem man auf das Frontend zugreift. Sonst erhält fronthem mehrere Zugriffe von der gleichen IP, die sich gegenseitig ins Gehege kommen.

====Zertificate-Identify====
{{Randnotiz|RNTyp=info|RNText=Hinweis: Diese Möglichkeit wurde während der Entwicklung bereits diskutiert und berücksichtigt, die Verwendung von Zertifikaten wurde bislang aber noch nicht implementiert, hauptsächlich aufgrund der teilweise mangelnden oder zumindest sehr unterschiedlichen Unterstützung von Zertifikaten auf Endgeräte-Seite (z.B. webviewcontrol).
}}

Das Endgerät wird über ein Zertifikat identifiziert.
Zuerst wird ein Zertifikat generiert, welches dann auf dem Endgerät installiert werden muss.

Diese Methode der Identifizierung verspricht höhere Sicherheit, wie auch denn Vorteil, das man sich nicht einloggen muss.

==Troubleshooting==
=== allgemeines Vorgehen ===

Generelles Vorgehen bei seltsamen Erscheinungen:
* smartVISU-Page-Cache ausschalten (auf der Config Seite von smartVISU, wo auch der Treiber konfiguriert wird)
* smartVISU-temp-Verzeichnis leeren (e.g. /var/www/html/smartvisu/temp)
* Browser neu starten
* Konsole im Browser öffnen und nach Errors schauen
* Verbose Level des FHEM-Device <code>fronthem</code> und <code>fronthemDevice</code> auf 5 setzen und im Log nach Errors schauen
* Den Log des Webservers kontrollieren
* Prüfen, ob der WebSocket läuft
{{Link2Forum|Topic= 30909|Message=272083|LinkText=Forum}}, {{Link2Forum|Topic= 35960|Message=285384|LinkText=Forum}}, {{Link2Forum|Topic= 52624|Message=444004|LinkText=Forum}}

=== Verbindung ===

Erhält an eine "no connection" Warnung in smartVISU sollte man folgendes kontrollieren:
* Wurde auf der config-Seite von smartVISU auf dem Endgerät der Treiber auf "Fhem" gestellt?
* Ist auf der config-Seite von smartVISU auf dem Endgerät die richtige Adresse des WebSocket Servers (meistens der Server mit der FHEM-Instanz) und der Port 2121 eingetragen?
* Wurde für das fronthemDevice die richtige IP-Adresse definiert?
* Steht "connected" im state des fronthemDevice ?
{{Link2Forum|Topic= 30909|Message=236681|LinkText=Forum}}

Darüber hinaus wird Websocket erst ab Android 4.4 einwandfrei unterstützt {{Link2Forum|Topic= 39587|Message=318219|LinkText=Forum}}.

Ebenfalls das iPad 1G wird nicht mehr unterstützt {{Link2Forum|Topic= 46737|Message=384727|LinkText=Forum}}.

=== alternativer Treiber zum loggen auf der Konsole ===

Falls mal ein Widget den Websocket Server zum Absturz bringt, was mittlerweile nicht mehr passieren sollte, wurde im {{Link2Forum|Topic= 30909|Message=273617|LinkText=Forum}} ein Treiber veröffentlich, der das "überlebt" und auf der Konsole weiter loggt, welches Widget es verursacht hat.

=== Logmeldungen ===

Da die Module noch inoffiziell sind, hat sich ein wenig debug code ins git geschlichen.

Folgende Zeile Code muss in den beiden Dateien aus kommentiert werden (# am Anfang der Zeile).

Log3 ($hash, 1, "in $e");

: Zeile 325 in 31_fronthemDevice.pm
: Zeile 154 in 01_fronthem.pm

{{Link2Forum|Topic= 36407|Message=287499|LinkText=Forum}}

=== keine Events ===

Es gibt immer mal die Situation, dass man events unterdrückt und für eine spätere Anwendung in Zusammenhang mit einem Frontend, sich nicht mehr daran erinnert. Daher sollte bei ausbleiben eines entsprechenden Auslösung aus FHEM immer kontrolliert werden, dass die Events nicht durch event-min..., event-on..., etc. unterdrückt wird. {{Link2Forum|Topic= 30909|Message=236073|LinkText=Forum}}

=== keine GADs im Editor ===

Die GADs werden beim Aufruf einer Seite (in smartVISU) an fhem übertragen.
In smartVISU ein <code>ctrl+F5</code> ausführen, danach einen Seitenreload in fhem.
{{Link2Forum|Topic= 30909|Message=269984|LinkText=Forum}}

Darüber hinaus ist bekannt, dass ein manuelles Editieren der fhem.cfg ebenfalls dazu führen kann, dass die Liste leer bleibt.
{{Link2Forum|Topic=43796|Message=357097|LinkText=Forum}}

=== alte GADs löschen ===

Hat man einmal aus versehen einen Demoraum ausgewählt und vergessen den Treiber auf Offline zu stellen, füllt sich der GAD-Editor mit allen GADs aus dem Demoraum. Um diese wieder zu löschen gibt es entweder den Weg über den GAD-Editor (gad-Editor -> gad anklicken -> delete) oder die Möglichkeit direkt die fhserver.fronthem.cfg zu editieren. {{Link2Forum|Topic=47281|Message=390051|LinkText=Forum}}

Die Datei befindet sich unter ./fhem/www/fronthem/server/<devicename>. {{Link2Forum|Topic=46214|Message=379959|LinkText=Forum}}

=== VPN ===

Beim Zugriff durch einen VPN-Tunnel muss sichergestellt sein, dass der VPN-Tunnel sowohl Zugriff auf Port 8083 (FHEMWEB) als auch auf Port 2121 (fronthem) zulässt. Darüber hinaus wird einem per VPN angemeldeten Endgerät normalerweise eine andere interne IP-Adresse zugeordnet, als wenn das Endgerät sich im lokalen LAN befände. {{Link2Forum|Topic= 30909|Message=281398|LinkText=Forum}}

Für ein Script, dass variable fronthemDevices anlegt, sei auf diesen {{Link2Forum|Topic= 50328|Message=420580|LinkText=Forumsbeitrag}} verwiesen.

Ein weiterer Artikel, der sich mit dem Thema befasst, ist dieser {{Link2Forum|Topic= 50019|Message=417592|LinkText=Forumsbeitrag}}.

== Links ==
{{Link2Forum|Topic= 27291|Message=219207|LinkText=Detaillierte Funktionsbeschreibung}} aus der Entwicklungszeit.

{{Link2Forum|Topic=30909|Message=257681|LinkText=Addon-Treiber}} um eine weitere Steuerung Daten in SV zu visualisieren .

[[Kategorie:fronthem/smartVISU]]

Kategorie:Fronthem/smartVISU

2016-06-24T20:37:48Z

Joshi04: Neue Kategorie fronthem/smartVISU

Die Bezeichnung ist die Kombination aus dem Interface mit Namen "fronthem" und dem Web-Frontend "smartVISU". Für einen Betrieb muss zum einen das Interface fronthem installiert und konfiguriert werden, als auch das Web-Frontend installiert und konfiguriert.

Konkrete Beispiele sind für bestimmt Anwendungen unter smartVISU beschrieben.

[[Kategorie: FHEM Frontends]]

Fronthem

2016-06-24T20:34:46Z

Joshi04: Kategorie fronthem/smartVISU eingeführt; weitere Kleinigkeiten aus dem Forum hinzugefügt

{{Infobox Modul
|ModPurpose=Anbindung von externen Frontends an FHEM
|ModType=x


|ModForumArea=Sonstige Systeme
|ModTechName=01_fronthem.pm, 31_fronthemDevice.pm, fhconverter.pm, fronthemEditor.js
|ModOwner=[http://forum.fhem.de/index.php?action=profile;u=769 Jörg alias herrmannj]
}}

Dieser Artikel befasst sich mit den FHEM-Modulen und weiteren Dateien, die für die Integration von fronthem in FHEM notwendig sind. Die [[Installation Fronthem|Installation von fronthem]] ist in einem separater Artikel beschrieben.

Alle Artikel zur Thematik fronthem/smartVISU sind [[:Kategorie:fronthem/smartVISU|hier]] kategorisiert.

----

Fronthem verfolgt die Idee, ein externes Web-Frontend (z. B. [[smartVISU]]) an fhem anzukoppeln und den Datenverkehr sowie die Zusammenarbeit von Befehlen und Parametern zwischen FHEM und dem Web-Frontend zu übernehmen.

Fronthem ist ein Projekt von herrmannj und wurde im {{Link2Forum|Topic= 27291|Message=27291.0l|LinkText=fhem-Forum}} erstmalig angekündigt.

Für die Installation eines passenden Web-Frontends (z.B. smartVISU), sowie dessen [[smartVISU Installation|Installation]] gibt es jeweils eigenständige Artikel.

__TOC__

{{Todo|Redaktionelle Überarbeitung der Detailbeschreibung für Readings Converter RGBCombined. Beschreibung der Converter ReadingsTimestamp, Attribute, Trigger.}}

Die Integration von fronthem als Interface innerhalb von FHEM besteht aus vier Bausteinen:

==Bausteine==
=== websocket ===
Der Websocket ist eine generische http-Schnittstelle, die von einem externen Frontend aus angesprochen werden kann.

Der Websocket Server wird durch das fhem-Modul "fromthem" automatisch gestartet, sobald ein Device vom TYPE <code>fronthem</code> definiert wurde. Der zugehörige Prozess läuft vom fhem Hauptprozess entkoppelt und kann mit ihm kommunizieren.

Der Websocket wird standardmäßig auf Port 2121 angesprochen, wird implizit durch die anderen Bausteine verwendet und benötigt im Prinzip keine weitere Beachtung, außer man möchte das Webinterface auf einem anderen Device neben FHEM laufen lassen.

Allerdings ist dieses das eigentliche Interface zwischen FHEM und einem externen Frontend.

Die Datei 01_fronthem.pm für dieses Modul liegt standardmäßig wie alle anderen Module im Ordner .../fhem/FHEM/.

=== device connector ===
Ein Device-Connector dient dazu, ein Endgerät eines Benutzers (PCs, Tablets, Smartphones usw.) als Clients zu konfigurieren und dessen Berechtigungen (read, write) auf der Ebene einzelner Objekte zu steuern. Damit können z. B. die Nachkommen oder Gäste zwar das Licht und die Heizung im eigenen Raum steuern, nicht aber die Programmierung der Heizung ändern oder den Alarm ausschalten.

Ein Endgerät wird dabei jeweils als Device vom TYPE <code>fromthemdevice</code> innerhalb von FHEM definiert. Details zur genauen Einrichtung finden sich im [[#Integration in FHEM|Verlauf]] dieses Artikels.

An einem einzelnen Device-Connector werden die durch den websocket vom externen Frontend mitgeteilten Objekte aufgelistet (GADs) und können dort einerseits mit fhem devices verbunden und andererseits in den Berechtigungen des jeweiligen Endgerätes konfiguriert werden.

Die Kombination der Frontend-items (GADs) mit den fhem-Devices über die Converter wird nur einmal benötigt und hat eine globale Gültigkeit. Die Berechtigungen der verwendeten Endgeräte werden jeweils pro Endgerät gesetzt. Details zum Konfigurieren und Duplizieren von Berechtigungen finden sich im weiteren [[#Integration in FHEM|Verlauf]] dieses Artikels. Auch eine Zugriffsberechtigung über eine PIN-Abfrage ist angedacht, bislang (Juni 2016) aber noch nicht implementiert.

Änderungen von Readings, Events werden dabei per {{Link2Forum|Topic= 27291|Message=209920l|LinkText=push}} auf die Devices verweilt.

Die Datei 31_fronthemDevice.pm für dieses Modul liegt standardmäßig wie alle anderen Module im Ordner .../fhem/FHEM/.

=== readings converter ===

Die readings converter dienen dazu, die Verbindung zwischen den Informationen in FHEM (states, readings, events) und den Formaten, die innerhalb des Frontends verwendet werden, herzustellen. Die Readings von FHEM müssen in die Form der möglichen Werte des Frontends umgewandelt werden. Im umgekehrten Fall müssen Befehle des Frontends in FHEM kompatible Befehle umgesetzt werden.

Über das Konzept der converter können FHEM-Devices unterschiedlichster Typen und Funktionen über das Frontend bedient werden. So versorgt der gleiche converter der die Solltemperatur des virtuellen Heizungsthermostats (bidriektional) einstellt auch die Füllstandanzeige der Zisterne sowie den Dimmer. In den genannten Fällen handelt es sich um die Übertragung von numerischen Werten. Converter können dabei auch Spezialaufgaben wie die Begrenzung des Wertebereichs übernehmen. So lässt sich über NumDirect zum Beispiel die Solltemperatur Einstellung für virtuelle Heizungsregler auf Min und Max Werte begrenzen.

Standardmäßig gibt es folgende Converter:
* [[#Direct]] für Übertragung ohne Konvertierung
* [[#NumDirect]] für Übertragung von Zahlenwerten in einem begrenzten Werteraum zwischen Min und Max
* [[#NumDisplay]] für Zahlenwerte aus fhem Readings, nur lesend
* [[#OnOff]] für Schalter, Übersetzung von On in 1 und Off in 0
* [[#RGBCombined]] für Übertragung von RGB-Werten so das sie FHEM akzeptiert
* [[#ReadingsTimestamp]] (vorhanden, Beschreibung TODO)
* [[#Attribute]] (vorhanden, Beschreibung TODO)
* [[#Trigger]] (vorhanden, Beschreibung TODO)

Weitere Readings Converter können darüber hinaus [[#eigene Converter|individuell selbst]] definiert werden.

Die Datei fhconverter.pm, die die oben genannten Converter enthält, liegt standardmäßig wie alle anderen Module im Ordner .../fhem/FHEM/.

Die hier beschriebenen Converter sind kompatibel mit dem oben erwähnten Frontend smartVISU und werden auf dessen Basis erklärt. Für die Verwendung in Kombination mit anderen Frontends müssen die Converter möglicher Weise entsprechend angepasst werden.

====Direct====
Die Werte werden ohne Konvertierung weitergegeben.

Gibt den Wert des von <reading> ohne weitere Wandlung an das Frontend weiter. In umgekehrter Richtung wird der vom Frontend geliefert Wert ohne Wandlung im hinterlegten <set> eingesetzt.

Beispiel:
:Anzeige eines An- oder Abwesenheitszustandes im Frontend (Textanzeige, Icon, Button)

====NumDirect====
NumDirect arbeitet bidirektional. Die Werte werden genau wie bei Direct ohne Umwandlung weitergegeben.

Der Unterschied zu Direct besteht jedoch darin, dass nur Zahlenwerte übergeben werden, d.h. die Zahlen werden aus <reading> herausgefiltert.

Des Weiteren kann man einen minimalen und maximalen Wert mit angeben. Dieses soll verhindern, dass im Frontend Werte eingestellt werden, die überhaupt keinen Sinn ergeben.

Beispiel:
:In der smartVISU könnte man für einen Raumthermostaten z.B. -100°C einstellen, was der Aktuator auf Seiten von FHEM nicht umsetzen kann (minimal einstellbarer Wert).

==== NumDisplay ====
NumDisplay arbeitet nur in eine Richting, von FHEM zum Frontend. Die Werte werden ohne Umwandlung weitergegeben, bis auf die Tatsache, dass wie beim Converter NumDirect nur Zahlenwerte übergeben werden, d.h. die Zahlen werden aus <reading> herausgefiltert.

Es ist dazu gedacht Zahlenwerte zu übergeben, ohne etwas zu verändern.

Beispiel:
: Anzeige des Raumklimas (Temperatur, Feuchtigkeit, CO2, Lautstärke, etc.)

==== OnOff ====

Dieser Converter ist für das einfache Schalten von Ein/Aus-Funktionen vorgesehen.

FHEM interpretiert Ein/Aus-Funktionen mit on/off, innerhalb von smartVISU entsprechen diese Zustände jedoch 1/0.

Der OnOff-Converter wandelt diese bidirektional ineinander um.

Beispiel:
: Schalter

==== RGBCombined ====
Dieser Converter dient zur Steuerung von RGB Leuchtmitteln über Farbauswahlfelder (zb. Farbkreis). Eine Besonderheit ist hier, dass smartVISU die 3 RGB Werte separat verarbeitet. D.h. von FHEM wird ein RGB-Wert in HEX in 3 Werte, jeweils für R, G und B, aufgeteilt und an das Frotnend übergeben. In umgekehrter Richtung wird die Auswahl einer Farbe im Frontend mit den 3 Werten für R, G und B an den Converter übergeben, kombiniert und an FHEM übergeben.

Entsprechend arbeitet er bidirektional und wandelt 3 Frontend Items in ein FHEM-Objekt um. Damit die Kombination der Werte funktioniert, muss dieser Converter gleichlautend für alle 3 RGB Kanäle des Frontends definiert werden.

reading: Name eines reading mit HEX RGB Wert des Leuchtmittels

converter (mit Parameter): <code>RGBCombined <itemRed>, <itemYellow>, <itemBlue></code>

set: Name des set Befehls, bekommt HEX RGB Wert übergeben

==== ReadingsTimestamp ====
Dieser Converter ist im Modul bereits enthalten, dessen Beschreibung ist allerdings TODO.

==== Attribute ====
Dieser Converter ist im Modul bereits enthalten, dessen Beschreibung ist allerdings TODO.

==== Trigger ====
Dieser Converter ist im Modul bereits enthalten, dessen Beschreibung ist allerdings TODO.

==== eigene Converter ====
Zusätzlich zu den bestehenden Convertern besteht die Möglichkeit, eigene zu definieren. Diese können in der 99_myUtils.pm oder einer neu angelegten 99_fronthemUtils.pm definiert werden. Es ist nicht ratsam, die fhconverter.pm dafür zu verwenden, da bei einem möglichen späteren Update diese Datei überschrieben wird. Wie alle anderen Module, muss sich die Datei im Verzeichnis./fhem/FHEM/ befinden. ({{Link2Forum|Topic= 30909|Message=266944|LinkText=Forum}})

Eigene Converter müssen nur die gleiche Signatur haben und in dem gleichen namespace wie die im fhconverter.pm stehen dann werden sie dynamisch geladen und stehen in fronthem zur Verfügung. ({{Link2Forum|Topic= 30909|Message=236070l|LinkText=Forum}})

==== Ideen für weitere Converter ====

Zwei weitere Converter sind angedacht, aber derzeit noch nicht Teil des Moduls.

===== NumDelayed =====
NumDelayed ist noch in Arbeit.

Ein bidirektionaler numerischer Converter mit einstellbarer Verzögerung.

Bietet bei der Ansteuerung mechanischer Aktoren (Markise, Jalousie) Vorteile gegenüber NumDirect. Als Beispiel sei die Steuerung einer Jalousie über einen Slider genannt. Da Slider ihre Werte kontinuierlich an FHEM übermitteln, würde bei der Verwendung anderer Converter dem entsprechenden Aktor (z.B. HM-BP), während der Benutzer den Slider bedient, mehrfach der vermeindliche Sollwert übermittelt werden. Gleichzeitig beginnt der Aktor seine Fahrt und übermittelt dem Slider seine aktuelle ist Position. Das führt zu einem springen des Sliders und einer "unschönen" Bedienung.

NumDelayed nimmt daher die Signale des Sliders entgegen, wartet jedoch mit der Weitergabe solange, bis sich der Slider (xxx ms, konfigurierbar) nicht mehr bewegt. In Gegenrichtung wird ebenso verfahren, erst wenn der Aktor seine Endposition erreicht, wird der Slider im Frontend aktualisiert. In diesem Beispiel würde das bedeuten das der Slider im Normalfall ohnehin so steht (Soll) wie vom Aktor gemeldet (Ist). Natürlich könnte der Benutzer oder ein Hindernis die Fahrt auch unterbrochen haben, dann würde der Slider auf die gemeldete Position aktualisiert.

===== WordDisplay =====
WordDisplay ist derzeit in Planung, es wird noch über die Umsetzung diskutiert.

Der Converter soll nur in eine Richtung arbeiten, FHEM zu Frontend. Es ist dazu gedacht Wörter oder Textpassagen zu übertragen. Jedoch soll es möglich sein, eine Umwandlung selbst festzulegen. So kann man einfach mehrere Textausgaben abhängig vom Zustand an das Frontend schicken:

Beispiel:
: Geofancy: Home -> Zuhause, Underway -> Unterwegs, Work -> Arbeit

=== fronthemEditor ===

Um einen komfortable Möglichkeit zur Verfügung zustellen, die Bindung und Konvertierung zwischen FHEM Device/Reading und Frontend-Objekt festzulegen, gibt es einen Javascript Editor als Erweiterung von FHEMWEB. Er wird durch die Datei fronthemEditor.js realisiert, die im Ordner .../fhem/www/frontend/pgm2/ abgelegt ist.

Sobald ein fronthemDevice (Definition für ein Endgerät) definiert ist, kann man über dessen Details in FHEMWEB die GADs definieren und die Rechte verteilen.

==== GAD Liste ====
Auf der Detailseite werden im oberen Teil die GADs aufgelistet die von smartVisu "angefragt" wurden. In vier Spalten werden von links der GAD-Name (wie auf der smartVISU-Seite definiert), das damit verbundene FHEM-Device, für das frontemDevice gesetzte Lese-Rechte und Schreib-Rechte angezeigt. Im oberen Teil des Fensters lässt sich eine Zeichenkette eingeben, nach der die Liste gefiltert wird. (Zumindest in Dark-Style hat die Schrift der eingegebenen Zeichenkette die gleiche Farbe wie der Hintergrund).

Die Verknüpfung zwischen GAD und FHEM-Device gilt global und muss nur einmal für ein beliebiges fronthemDevice eingerichtet werden. Lese- und Schreibrechte können pro fronthemDevice konfiguriert werden.

Wichtig zu berücksichtigen ist die Tatsache, dass die GAD-Liste erst dann aktualisiert wird, wenn einmal die entsprechende Frontend-Seite von einem frontendDevice aufgerufen wurde. Die korrekte Konfiguration des Treiber auf der Config-Seite für das frontendDevice (siehe Installation des Frontends) wird dabei vorausgesetzt. Die Liste wird also erst gefüllt, wenn erstmalig vom Frontend über einen Seitenaufruf die Verbindung zu FHEM initiiert wurde.

Auf der anderen Seite weiß fronthem nicht, welche GADs in smartVISU verwendet werden. Jedes GAD das einmal sichtbar war, wird von fronthem gespeichert und aufgelistet, bis man es explizizt in fronthem löscht. ({{Link2Forum|Topic= 43226|Message=352115|LinkText=Forum}})

==== GAD Edit ====
Klickt man auf einen GAD aus der obigen Liste, öffnet sich ein weiteres Feld mit Titel "GAD Edit".
Das Feld ist in 2 Teile aufgeteilt, im oberen das globale Mapping zwischen GAD und FHEM-Device/Reading, darunter die Zugriffsrechte für das jeweilige Device. Am unteren Ende des Feldes sind Schaltflächen für das Löschen und Sichern von GADs aus der Liste oder das Abbrechen der Bearbeitung angeordnet.

Die GAD-Definierung im oberen Bereich besteht aus:
[[Datei:DeviceDefine.png|400px|thumb|right|GADs definieren]]
*mode
*device
*reading
*converter
*cmd set

===== mode =====

Es gibt 2 Modi:
*item
*plot

Die Unterscheidung ist selbsterklärend, alles was kein "plot" werden soll, wird als "item" definiert.

===== device =====

Hier wird der Name des FHEM-Devices eingetragen, an das die Befehle geschickt werden, bzw. dessen Readings angezeigt werden sollen. Die vorhandenen Devices in fhem werden als Liste unter dem Eingabefeld angezeigt, sobald man mit der Eingabe beginnt.

Wie überall innerhalb von FHEM ist die Groß/Kleinschreibung zu beachten.

===== reading =====

Für das <reading> wird das zu verwendende Reading des FHEM Devices angegeben, z. B. "state" oder "Level". Die vorhandenen Readings des gewählten fhem-Devices werden als Liste unter dem Eingabefeld angezeigt, sobald man mit der Eingabe beginnt.

Änderungen, wenn fhem entsprechende events erzeugt, werden von fronthem mitgelesen und per push an die fronthemDevices gesendet.

===== converter =====

Hier gibt man denn Namen des Converters an, denn man verwenden möchte. Wie oben beschrieben, stehen unterschiedliche [[#readings converter|converter]] für verschiedene Aufgabenstellungen zur Verfügung. Die meisten Devices können mit diesen Convertern angesteuert werden.

Wie überall innerhalb von FHEM ist die Groß/Kleinschreibung zu beachten.

===== cmd set =====

Das zum Schreiben zu verwendende Reading des fhem Devices, z. B. "state" oder "Level". Die vorhandenen Readings des gewählten fhem-Devices werden als Liste unter dem Eingabefeld angezeigt, sobald man mit der Eingabe beginnt.

Das gewählte Reading gibt den "set" des fhem Devices an, der die Rückgabe des Converters entgegen nimmt.

Bei Lampe z.B. "state".

==== Devicerechte vergeben ====

[[Datei:DeviceRechte.png|400px|thumb|right|Devicerechte vergeben]]
Devicerechte bestehen aus:
*Eine Berechtigung für "read"
*Eine Berechtigung für "write"
*Jeweils für Lese- und Schreib-Berechtigung die Festlegung eines PINs

===== read =====
Das Device darf die Statuswerte auslesen.

===== write =====
Das Device darf Statuswerte ändern.

===== PIN GAD =====

Die PIN-Abfrage für die Lese- oder Schreibberechtigung ist derzeit noch nicht implementiert, daher ist es irrelevant, was hier eingetragen wird.

===== Attribut Whitelist =====
Möchte man die differenzierte Berechtigungssteuerung für ein fronthemDevice außer Kraft setzen, kann das Attribut "whitelist" für das entsprechende fronthemDevice auf false gesetzt werden. Das bedeutet dann, dass unabhängig von den Berechtigungs-Checkboxen das fronthemDevice immer für alle GADs lesen und schreiben darf.

== Integration in FHEM ==

=== fronthem ===

Ein Device vom TYPE <code>fronthem</code> und damit das eigentlich Interface, wird nach erfolgreicher Sicherstellung der Voraussetzungen (siehe fronthem Installation) über folgenden Befehl in der Eingabezeile von FHEMWEB definiert:
:<code>define <name> fronthem</code>

Über diese Definition wird ebenfalls die Verbindung zum WebSocket sichergestellt. Logischer Weise benötigt man nur ein Device von diesem Typ.

Als Reading wird
* die Verbindung zum WebSocket angezeigt. "open" stellt dabei den normalen Zustand dar.
* lastError angezeigt, woran man beispielsweise erkennen kann, dass für Endgerät der Zugriff abgelehnt wurde ("client <IP-Adress> rejected").

Der state des Devices gibt dabei derzeit keine Meldung zurück. Ein Wert "???" ist daher kein Hinweis auf einen Fehler, sondern entspricht dem ganz normalen Modulverhalten.

===Device Connector===
Für jedes Endgerät (smartphone, PC, Tablet, etc.) mit dem man auf das Frontend zugreifen möchte, muss ein entsprechendes fronthemDevice definiert werden.
Wie oben bereits beschrieben, kann dadurch genau festgelegt werden, welches Endgerät welche Rechte für eine jeweilige Schalt-/Anzeigefunktion hat.

Wenn man die Berechtigungen für neue Endgeräte kopieren möchte, liegen diese für jedes Endgerät unter ./fhem/www/fronthem/clients/<fronthemDevice> und lassen sich so einfach für neue Endgeräte übertragen.

====IP-Identify====

Ein Endgerät wird über seine IP_Adresse identifiziert. Dies ist nur im internen gesicherten Netzwerk empfehlenswert. Es wird definiert mit:
:<code>define <device> fronthemDevice <ip></code>

Dabei ist für die IP-Adresse die des Endgerätes anzugeben, welches auf den smartVISU zugreifen soll (also das Tablet, Rechner, Smartphone etc.). Entsprechend selbstverständlich ist, dass man durch eine passende Einstellung seine DHCP-Servers oder fest vergebene IP-Adressen sicherstellt, dass ein Endgerät immer die gleiche IP erhält/verwendet.

Wichtig bei der späteren Verwendung ist, dass pro Endgerät immer nur ein Brower-Tab geöffnet wird, mit dem man auf das Frontend zugreift. Sonst erhält fronthem mehrere Zugriffe von der gleichen IP, die sich gegenseitig ins Gehege kommen.

====Zertificate-Identify====
{{Randnotiz|RNTyp=info|RNText=Hinweis: Diese Möglichkeit wurde während der Entwicklung bereits diskutiert und berücksichtigt, die Verwendung von Zertifikaten wurde bislang aber noch nicht implementiert, hauptsächlich aufgrund der teilweise mangelnden oder zumindest sehr unterschiedlichen Unterstützung von Zertifikaten auf Endgeräte-Seite (z.B. webviewcontrol).
}}

Das Endgerät wird über ein Zertifikat identifiziert.
Zuerst wird ein Zertifikat generiert, welches dann auf dem Endgerät installiert werden muss.

Diese Methode der Identifizierung verspricht höhere Sicherheit, wie auch denn Vorteil, das man sich nicht einloggen muss.

==Troubleshooting==
=== allgemeines Vorgehen ===

Generelles Vorgehen bei seltsamen Erscheinungen:
* smartVISU-Page-Cache ausschalten (auf der Config Seite von smartVISU, wo auch der Treiber konfiguriert wird)
* smartVISU-temp-Verzeichnis leeren (e.g. /var/www/html/smartvisu/temp)
* Browser neu starten
* Konsole im Browser öffnen und nach Errors schauen
* Verbose Level des FHEM-Device <code>fronthem</code> und <code>fronthemDevice</code> auf 5 setzen und im Log nach Errors schauen
* Den Log des Webservers kontrollieren
* Prüfen, ob der WebSocket läuft
{{Link2Forum|Topic= 30909|Message=272083|LinkText=Forum}}, {{Link2Forum|Topic= 35960|Message=285384|LinkText=Forum}}, {{Link2Forum|Topic= 52624|Message=444004|LinkText=Forum}}

=== Verbindung ===

Erhält an eine "no connection" Warnung in smartVISU sollte man folgendes kontrollieren:
* Wurde auf der config-Seite von smartVISU auf dem Endgerät der Treiber auf "Fhem" gestellt?
* Ist auf der config-Seite von smartVISU auf dem Endgerät die richtige Adresse des WebSocket Servers (meistens der Server mit der FHEM-Instanz) und der Port 2121 eingetragen?
* Wurde für das fronthemDevice die richtige IP-Adresse definiert?
* Steht "connected" im state des fronthemDevice ?
{{Link2Forum|Topic= 30909|Message=236681|LinkText=Forum}}

Darüber hinaus wird Websocket erst ab Android 4.4 einwandfrei unterstützt {{Link2Forum|Topic= 39587|Message=318219|LinkText=Forum}}.

Ebenfalls das iPad 1G wird nicht mehr unterstützt {{Link2Forum|Topic= 46737|Message=384727|LinkText=Forum}}.

=== alternativer Treiber zum loggen auf der Konsole ===

Falls mal ein Widget den Websocket Server zum Absturz bringt, was mittlerweile nicht mehr passieren sollte, wurde im {{Link2Forum|Topic= 30909|Message=273617|LinkText=Forum}} ein Treiber veröffentlich, der das "überlebt" und auf der Konsole weiter loggt, welches Widget es verursacht hat.

=== Logmeldungen ===

Da die Module noch inoffiziell sind, hat sich ein wenig debug code ins git geschlichen.

Folgende Zeile Code muss in den beiden Dateien aus kommentiert werden (# am Anfang der Zeile).

Log3 ($hash, 1, "in $e");

: Zeile 325 in 31_fronthemDevice.pm
: Zeile 154 in 01_fronthem.pm

{{Link2Forum|Topic= 36407|Message=287499|LinkText=Forum}}

=== keine Events ===

Es gibt immer mal die Situation, dass man events unterdrückt und für eine spätere Anwendung in Zusammenhang mit einem Frontend, sich nicht mehr daran erinnert. Daher sollte bei ausbleiben eines entsprechenden Auslösung aus FHEM immer kontrolliert werden, dass die Events nicht durch event-min..., event-on..., etc. unterdrückt wird. {{Link2Forum|Topic= 30909|Message=236073|LinkText=Forum}}

=== keine GADs im Editor ===

Die GADs werden beim Aufruf einer Seite (in smartVISU) an fhem übertragen.
In smartVISU ein <code>ctrl+F5</code> ausführen, danach einen Seitenreload in fhem.
{{Link2Forum|Topic= 30909|Message=269984|LinkText=Forum}}

Darüber hinaus ist bekannt, dass ein manuelles Editieren der fhem.cfg ebenfalls dazu führen kann, dass die Liste leer bleibt.
{{Link2Forum|Topic=43796|Message=357097|LinkText=Forum}}

=== alte GADs löschen ===

Hat man einmal aus versehen einen Demoraum ausgewählt und vergessen den Treiber auf Offline zu stellen, füllt sich der GAD-Editor mit allen GADs aus dem Demoraum. Um diese wieder zu löschen gibt es entweder den Weg über den GAD-Editor (gad-Editor -> gad anklicken -> delete) oder die Möglichkeit direkt die fhserver.fronthem.cfg zu editieren. {{Link2Forum|Topic=47281|Message=390051|LinkText=Forum}}

Die Datei befindet sich unter ./fhem/www/fronthem/server/<devicename>. {{Link2Forum|Topic=46214|Message=379959|LinkText=Forum}}

=== VPN ===

Beim Zugriff durch einen VPN-Tunnel muss sichergestellt sein, dass der VPN-Tunnel sowohl Zugriff auf Port 8083 (FHEMWEB) als auch auf Port 2121 (fronthem) zulässt. Darüber hinaus wird einem per VPN angemeldeten Endgerät normalerweise eine andere interne IP-Adresse zugeordnet, als wenn das Endgerät sich im lokalen LAN befände. {{Link2Forum|Topic= 30909|Message=281398|LinkText=Forum}}

Für ein Script, dass variable fronthemDevices anlegt, sei auf diesen {{Link2Forum|Topic= 50328|Message=420580|LinkText=Forumsbeitrag}} verwiesen.

Ein weiterer Artikel, der sich mit dem Thema befasst, ist dieser {{Link2Forum|Topic= 50019|Message=417592|LinkText=Forumsbeitrag}}.

== Links ==
{{Link2Forum|Topic= 27291|Message=219207|LinkText=Detaillierte Funktionsbeschreibung}} aus der Entwicklungszeit.

{{Link2Forum|Topic=30909|Message=257681|LinkText=Addon-Treiber}} um eine weitere Steuerung Daten in SV zu visualisieren .

[[Kategorie:fronthem/smartVISU]]

Fronthem

2016-06-22T18:27:25Z

Joshi04:

{{Infobox Modul
|ModPurpose=Anbindung von externen Frontends an FHEM
|ModType=x


|ModForumArea=Sonstige Systeme
|ModTechName=01_fronthem.pm, 31_fronthemDevice.pm, fhconverter.pm, fronthemEditor.js
|ModOwner=[http://forum.fhem.de/index.php?action=profile;u=769 Jörg alias herrmannj]
}}

Dieser Artikel befasst sich mit den FHEM-Modulen und weiteren Dateien, die für die Integration von fronthem in FHEM notwendig sind. Ein weiterer separater Artikel beschreibt die [[Installation Fronthem|Installation von Fronthem]].

Fronthem verfolgt die Idee, ein externes Web-Frontend (z. B. [[smartVISU]]) an fhem anzukoppeln und den Datenverkehr sowie die Zusammenarbeit von Befehlen und Parametern zwischen FHEM und dem Web-Frontend zu übernehmen.

Fronthem ist ein Projekt von herrmannj und wurde im {{Link2Forum|Topic= 27291|Message=27291.0l|LinkText=fhem-Forum}} erstmalig angekündigt.

Für die Installation eines passenden Web-Frontends (z.B. smartVISU), sowie dessen [[smartVISU Installation|Installation]] gibt es jeweils eigenständige Artikel.

__TOC__

{{Todo|Redaktionelle Überarbeitung der Detailbeschreibung für Readings Converter RGBCombined. Beschreibung der Converter ReadingsTimestamp, Attribute, Trigger.}}

Die Integration von fronthem als Interface innerhalb von FHEM besteht aus vier Bausteinen:

==Bausteine==
=== websocket ===
Der Websocket ist eine generische http-Schnittstelle, die von einem externen Frontend aus angesprochen werden kann.

Der Websocket Server wird durch das fhem-Modul "fromthem" automatisch gestartet, sobald ein Device vom TYPE <code>fronthem</code> definiert wurde. Der zugehörige Prozess läuft vom fhem Hauptprozess entkoppelt und kann mit ihm kommunizieren.

Der Websocket wird standardmäßig auf Port 2121 angesprochen, wird implizit durch die anderen Bausteine verwendet und benötigt im Prinzip keine weitere Beachtung, außer man möchte das Webinterface auf einem anderen Device neben FHEM laufen lassen.

Allerdings ist dieses das eigentliche Interface zwischen FHEM und einem externen Frontend.

Die Datei 01_fronthem.pm für dieses Modul liegt standardmäßig wie alle anderen Module im Ordner .../fhem/FHEM/.

=== device connector ===
Ein Device-Connector dient dazu, ein Endgerät eines Benutzers (PCs, Tablets, Smartphones usw.) als Clients zu konfigurieren und dessen Berechtigungen (read, write) auf der Ebene einzelner Objekte zu steuern. Damit können z. B. die Nachkommen oder Gäste zwar das Licht und die Heizung im eigenen Raum steuern, nicht aber die Programmierung der Heizung ändern oder den Alarm ausschalten.

Ein Endgerät wird dabei jeweils als Device vom TYPE <code>fromthemdevice</code> innerhalb von FHEM definiert. Details zur genauen Einrichtung finden sich im [[#Integration in FHEM|Verlauf]] dieses Artikels.

An einem einzelnen Device-Connector werden die durch den websocket vom externen Frontend mitgeteilten Objekte aufgelistet (GADs) und können dort einerseits mit fhem devices verbunden und andererseits in den Berechtigungen des jeweiligen Endgerätes konfiguriert werden.

Die Kombination der Frontend-items (GADs) mit den fhem-Devices über die Converter wird nur einmal benötigt und hat eine globale Gültigkeit. Die Berechtigungen der verwendeten Endgeräte werden jeweils pro Endgerät gesetzt. Details zum Konfigurieren und Duplizieren von Berechtigungen finden sich im weiteren [[#Integration in FHEM|Verlauf]] dieses Artikels. Auch eine Zugriffsberechtigung über eine PIN-Abfrage ist angedacht, bislang (Juni 2016) aber noch nicht implementiert.

Änderungen von Readings, Events werden dabei per {{Link2Forum|Topic= 27291|Message=209920l|LinkText=push}} auf die Devices verweilt.

Die Datei 31_fronthemDevice.pm für dieses Modul liegt standardmäßig wie alle anderen Module im Ordner .../fhem/FHEM/.

=== readings converter ===

Die readings converter dienen dazu, die Verbindung zwischen den Informationen in FHEM (states, readings, events) und den Formaten, die innerhalb des Frontends verwendet werden, herzustellen. Die Readings von FHEM müssen in die Form der möglichen Werte des Frontends umgewandelt werden. Im umgekehrten Fall müssen Befehle des Frontends in FHEM kompatible Befehle umgesetzt werden.

Über das Konzept der converter können FHEM-Devices unterschiedlichster Typen und Funktionen über das Frontend bedient werden. So versorgt der gleiche converter der die Solltemperatur des virtuellen Heizungsthermostats (bidriektional) einstellt auch die Füllstandanzeige der Zisterne sowie den Dimmer. In den genannten Fällen handelt es sich um die Übertragung von numerischen Werten. Converter können dabei auch Spezialaufgaben wie die Begrenzung des Wertebereichs übernehmen. So lässt sich über NumDirect zum Beispiel die Solltemperatur Einstellung für virtuelle Heizungsregler auf Min und Max Werte begrenzen.

Standardmäßig gibt es folgende Converter:
* [[#Direct]] für Übertragung ohne Konvertierung
* [[#NumDirect]] für Übertragung von Zahlenwerten in einem begrenzten Werteraum zwischen Min und Max
* [[#NumDisplay]] für Zahlenwerte aus fhem Readings, nur lesend
* [[#OnOff]] für Schalter, Übersetzung von On in 1 und Off in 0
* [[#RGBCombined]] für Übertragung von RGB-Werten so das sie FHEM akzeptiert
* [[#ReadingsTimestamp]] (vorhanden, Beschreibung TODO)
* [[#Attribute]] (vorhanden, Beschreibung TODO)
* [[#Trigger]] (vorhanden, Beschreibung TODO)

Weitere Readings Converter können darüber hinaus [[#eigene Converter|individuell selbst]] definiert werden.

Die Datei fhconverter.pm, die die oben genannten Converter enthält, liegt standardmäßig wie alle anderen Module im Ordner .../fhem/FHEM/.

Die hier beschriebenen Converter sind kompatibel mit dem oben erwähnten Frontend smartVISU und werden auf dessen Basis erklärt. Für die Verwendung in Kombination mit anderen Frontends müssen die Converter möglicher Weise entsprechend angepasst werden.

====Direct====
Die Werte werden ohne Konvertierung weitergegeben.

Gibt den Wert des von <reading> ohne weitere Wandlung an das Frontend weiter. In umgekehrter Richtung wird der vom Frontend geliefert Wert ohne Wandlung im hinterlegten <set> eingesetzt.

Beispiel:
:Anzeige eines An- oder Abwesenheitszustandes im Frontend (Textanzeige, Icon, Button)

====NumDirect====
NumDirect arbeitet bidirektional. Die Werte werden genau wie bei Direct ohne Umwandlung weitergegeben.

Der Unterschied zu Direct besteht jedoch darin, dass nur Zahlenwerte übergeben werden, d.h. die Zahlen werden aus <reading> herausgefiltert.

Des Weiteren kann man einen minimalen und maximalen Wert mit angeben. Dieses soll verhindern, dass im Frontend Werte eingestellt werden, die überhaupt keinen Sinn ergeben.

Beispiel:
:In der smartVISU könnte man für einen Raumthermostaten z.B. -100°C einstellen, was der Aktuator auf Seiten von FHEM nicht umsetzen kann (minimal einstellbarer Wert).

==== NumDisplay ====
NumDisplay arbeitet nur in eine Richting, von FHEM zum Frontend. Die Werte werden ohne Umwandlung weitergegeben, bis auf die Tatsache, dass wie beim Converter NumDirect nur Zahlenwerte übergeben werden, d.h. die Zahlen werden aus <reading> herausgefiltert.

Es ist dazu gedacht Zahlenwerte zu übergeben, ohne etwas zu verändern.

Beispiel:
: Anzeige des Raumklimas (Temperatur, Feuchtigkeit, CO2, Lautstärke, etc.)

==== OnOff ====

Dieser Converter ist für das einfache Schalten von Ein/Aus-Funktionen vorgesehen.

FHEM interpretiert Ein/Aus-Funktionen mit on/off, innerhalb von smartVISU entsprechen diese Zustände jedoch 1/0.

Der OnOff-Converter wandelt diese bidirektional ineinander um.

Beispiel:
: Schalter

==== RGBCombined ====
Dieser Converter dient zur Steuerung von RGB Leuchtmitteln über Farbauswahlfelder (zb. Farbkreis). Eine Besonderheit ist hier, dass smartVISU die 3 RGB Werte separat verarbeitet. D.h. von FHEM wird ein RGB-Wert in HEX in 3 Werte, jeweils für R, G und B, aufgeteilt und an das Frotnend übergeben. In umgekehrter Richtung wird die Auswahl einer Farbe im Frontend mit den 3 Werten für R, G und B an den Converter übergeben, kombiniert und an FHEM übergeben.

Entsprechend arbeitet er bidirektional und wandelt 3 Frontend Items in ein FHEM-Objekt um. Damit die Kombination der Werte funktioniert, muss dieser Converter gleichlautend für alle 3 RGB Kanäle des Frontends definiert werden.

reading: Name eines reading mit HEX RGB Wert des Leuchtmittels

converter (mit Parameter): <code>RGBCombined <itemRed>, <itemYellow>, <itemBlue></code>

set: Name des set Befehls, bekommt HEX RGB Wert übergeben

==== ReadingsTimestamp ====
Dieser Converter ist im Modul bereits enthalten, dessen Beschreibung ist allerdings TODO.

==== Attribute ====
Dieser Converter ist im Modul bereits enthalten, dessen Beschreibung ist allerdings TODO.

==== Trigger ====
Dieser Converter ist im Modul bereits enthalten, dessen Beschreibung ist allerdings TODO.

==== eigene Converter ====
Zusätzlich zu den bestehenden Convertern besteht die Möglichkeit, eigene zu definieren. Diese können in der 99_myUtils.pm oder einer neu angelegten 99_fronthemUtils.pm definiert werden. Es ist nicht ratsam, die fhconverter.pm dafür zu verwenden, da bei einem möglichen späteren Update diese Datei überschrieben wird. Wie alle anderen Module, muss sich die Datei im Verzeichnis./fhem/FHEM/ befinden. ({{Link2Forum|Topic= 30909|Message=266944|LinkText=Forum}})

Eigene Converter müssen nur die gleiche Signatur haben und in dem gleichen namespace wie die im fhconverter.pm stehen dann werden sie dynamisch geladen und stehen in fronthem zur Verfügung. ({{Link2Forum|Topic= 30909|Message=236070l|LinkText=Forum}})

==== Ideen für weitere Converter ====

Zwei weitere Converter sind angedacht, aber derzeit noch nicht Teil des Moduls.

===== NumDelayed =====
NumDelayed ist noch in Arbeit.

Ein bidirektionaler numerischer Converter mit einstellbarer Verzögerung.

Bietet bei der Ansteuerung mechanischer Aktoren (Markise, Jalousie) Vorteile gegenüber NumDirect. Als Beispiel sei die Steuerung einer Jalousie über einen Slider genannt. Da Slider ihre Werte kontinuierlich an FHEM übermitteln, würde bei der Verwendung anderer Converter dem entsprechenden Aktor (z.B. HM-BP), während der Benutzer den Slider bedient, mehrfach der vermeindliche Sollwert übermittelt werden. Gleichzeitig beginnt der Aktor seine Fahrt und übermittelt dem Slider seine aktuelle ist Position. Das führt zu einem springen des Sliders und einer "unschönen" Bedienung.

NumDelayed nimmt daher die Signale des Sliders entgegen, wartet jedoch mit der Weitergabe solange, bis sich der Slider (xxx ms, konfigurierbar) nicht mehr bewegt. In Gegenrichtung wird ebenso verfahren, erst wenn der Aktor seine Endposition erreicht, wird der Slider im Frontend aktualisiert. In diesem Beispiel würde das bedeuten das der Slider im Normalfall ohnehin so steht (Soll) wie vom Aktor gemeldet (Ist). Natürlich könnte der Benutzer oder ein Hindernis die Fahrt auch unterbrochen haben, dann würde der Slider auf die gemeldete Position aktualisiert.

===== WordDisplay =====
WordDisplay ist derzeit in Planung, es wird noch über die Umsetzung diskutiert.

Der Converter soll nur in eine Richtung arbeiten, FHEM zu Frontend. Es ist dazu gedacht Wörter oder Textpassagen zu übertragen. Jedoch soll es möglich sein, eine Umwandlung selbst festzulegen. So kann man einfach mehrere Textausgaben abhängig vom Zustand an das Frontend schicken:

Beispiel:
: Geofancy: Home -> Zuhause, Underway -> Unterwegs, Work -> Arbeit

=== fronthemEditor ===

Um einen komfortable Möglichkeit zur Verfügung zustellen, die Bindung und Konvertierung zwischen FHEM Device/Reading und Frontend-Objekt festzulegen, gibt es einen Javascript Editor als Erweiterung von FHEMWEB. Er wird durch die Datei fronthemEditor.js realisiert, die im Ordner .../fhem/www/frontend/pgm2/ abgelegt ist.

Sobald ein fronthemDevice (Definition für ein Endgerät) definiert ist, kann man über dessen Details in FHEMWEB die GADs definieren und die Rechte verteilen.

==== GAD Liste ====
Auf der Detailseite werden im oberen Teil die GADs aufgelistet die von smartVisu "angefragt" wurden. In vier Spalten werden von links der GAD-Name (wie auf der smartVISU-Seite definiert), das damit verbundene FHEM-Device, für das frontemDevice gesetzte Lese-Rechte und Schreib-Rechte angezeigt. Im oberen Teil des Fensters lässt sich eine Zeichenkette eingeben, nach der die Liste gefiltert wird. (Zumindest in Dark-Style hat die Schrift der eingegebenen Zeichenkette die gleiche Farbe wie der Hintergrund).

Die Verknüpfung zwischen GAD und FHEM-Device gilt global und muss nur einmal für ein beliebiges fronthemDevice eingerichtet werden. Lese- und Schreibrechte können pro fronthemDevice konfiguriert werden.

Wichtig zu berücksichtigen ist die Tatsache, dass die GAD-Liste erst dann aktualisiert wird, wenn einmal die entsprechende Frontend-Seite von einem frontendDevice aufgerufen wurde. Die korrekte Konfiguration des Treiber auf der Config-Seite für das frontendDevice (siehe Installation des Frontends) wird dabei vorausgesetzt. Die Liste wird also erst gefüllt, wenn erstmalig vom Frontend über einen Seitenaufruf die Verbindung zu FHEM initiiert wurde.

==== GAD Edit ====
Klickt man auf einen GAD aus der obigen Liste, öffnet sich ein weiteres Feld mit Titel "GAD Edit".
Das Feld ist in 2 Teile aufgeteilt, im oberen das globale Mapping zwischen GAD und FHEM-Device/Reading, darunter die Zugriffsrechte für das jeweilige Device. Am unteren Ende des Feldes sind Schaltflächen für das Löschen und Sichern von GADs aus der Liste oder das Abbrechen der Bearbeitung angeordnet.

Die GAD-Definierung im oberen Bereich besteht aus:
[[Datei:DeviceDefine.png|400px|thumb|right|GADs definieren]]
*mode
*device
*reading
*converter
*cmd set

===== mode =====

Es gibt 2 Modi:
*item
*plot

Die Unterscheidung ist selbsterklärend, alles was kein "plot" werden soll, wird als "item" definiert.

===== device =====

Hier wird der Name des FHEM-Devices eingetragen, an das die Befehle geschickt werden, bzw. dessen Readings angezeigt werden sollen. Die vorhandenen Devices in fhem werden als Liste unter dem Eingabefeld angezeigt, sobald man mit der Eingabe beginnt.

Wie überall innerhalb von FHEM ist die Groß/Kleinschreibung zu beachten.

===== reading =====

Für das <reading> wird das zu verwendende Reading des FHEM Devices angegeben, z. B. "state" oder "Level". Die vorhandenen Readings des gewählten fhem-Devices werden als Liste unter dem Eingabefeld angezeigt, sobald man mit der Eingabe beginnt.

Änderungen, wenn fhem entsprechende events erzeugt, werden von fronthem mitgelesen und per push an die fronthemDevices gesendet.

===== converter =====

Hier gibt man denn Namen des Converters an, denn man verwenden möchte. Wie oben beschrieben, stehen unterschiedliche [[#readings converter|converter]] für verschiedene Aufgabenstellungen zur Verfügung. Die meisten Devices können mit diesen Convertern angesteuert werden.

Wie überall innerhalb von FHEM ist die Groß/Kleinschreibung zu beachten.

===== cmd set =====

Das zum Schreiben zu verwendende Reading des fhem Devices, z. B. "state" oder "Level". Die vorhandenen Readings des gewählten fhem-Devices werden als Liste unter dem Eingabefeld angezeigt, sobald man mit der Eingabe beginnt.

Das gewählte Reading gibt den "set" des fhem Devices an, der die Rückgabe des Converters entgegen nimmt.

Bei Lampe z.B. "state".

==== Devicerechte vergeben ====

[[Datei:DeviceRechte.png|400px|thumb|right|Devicerechte vergeben]]
Devicerechte bestehen aus:
*Eine Berechtigung für "read"
*Eine Berechtigung für "write"
*Jeweils für Lese- und Schreib-Berechtigung die Festlegung eines PINs

===== read =====
Das Device darf die Statuswerte auslesen.

===== write =====
Das Device darf Statuswerte ändern.

===== PIN GAD =====

Die PIN-Abfrage für die Lese- oder Schreibberechtigung ist derzeit noch nicht implementiert, daher ist es irrelevant, was hier eingetragen wird.

===== Attribut Whitelist =====
Möchte man die differenzierte Berechtigungssteuerung für ein fronthemDevice außer Kraft setzen, kann das Attribut "whitelist" für das entsprechende fronthemDevice auf false gesetzt werden. Das bedeutet dann, dass unabhängig von den Berechtigungs-Checkboxen das fronthemDevice immer für alle GADs lesen und schreiben darf.

== Integration in FHEM ==

=== fronthem ===

Ein Device vom TYPE <code>fronthem</code> und damit das eigentlich Interface, wird nach erfolgreicher Sicherstellung der Voraussetzungen (siehe fronthem Installation) über folgenden Befehl in der Eingabezeile von FHEMWEB definiert:
:<code>define <name> fronthem</code>

Über diese Definition wird ebenfalls die Verbindung zum WebSocket sichergestellt. Logischer Weise benötigt man nur ein Device von diesem Typ.

Als Reading wird
* die Verbindung zum WebSocket angezeigt. "open" stellt dabei den normalen Zustand dar.
* lastError angezeigt, woran man beispielsweise erkennen kann, dass für Endgerät der Zugriff abgelehnt wurde ("client <IP-Adress> rejected").

Der state des Devices gibt dabei derzeit keine Meldung zurück. Ein Wert "???" ist daher kein Hinweis auf einen Fehler, sondern entspricht dem ganz normalen Modulverhalten.

===Device Connector===
Für jedes Endgerät (smartphone, PC, Tablet, etc.) mit dem man auf das Frontend zugreifen möchte, muss ein entsprechendes fronthemDevice definiert werden.
Wie oben bereits beschrieben, kann dadurch genau festgelegt werden, welches Endgerät welche Rechte für eine jeweilige Schalt-/Anzeigefunktion hat.

Wenn man die Berechtigungen für neue Endgeräte kopieren möchte, liegen diese unter ./fhem/www/fronthem/clients/<fronthemDevice> und lassen sich so einfach für neue Endgeräte übertragen.

====IP-Identify====

Ein Endgerät wird über seine IP_Adresse identifiziert. Dies ist nur im internen gesicherten Netzwerk empfehlenswert. Es wird definiert mit:
:<code>define <device> fronthemDevice <ip></code>

Dabei ist für die IP-Adresse die des Endgerätes anzugeben, welches auf den smartVISU zugreifen soll (also das Tablet, Rechner, Smartphone etc.). Entsprechend selbstverständlich ist, dass man durch eine passende Einstellung seine DHCP-Servers oder fest vergebene IP-Adressen sicherstellt, dass ein Endgerät immer die gleiche IP erhält/verwendet.

Wichtig bei der späteren Verwendung ist, dass pro Endgerät immer nur ein Brower-Tab geöffnet wird, mit dem man auf das Frontend zugreift. Sonst erhält fronthem mehrere Zugriffe von der gleichen IP, die sich gegenseitig ins Gehege kommen.

====Zertificate-Identify====
{{Randnotiz|RNTyp=info|RNText=Hinweis: Diese Möglichkeit wurde während der Entwicklung bereits diskutiert und berücksichtigt, die Verwendung von Zertifikaten wurde bislang aber noch nicht implementiert, hauptsächlich aufgrund der teilweise mangelnden oder zumindest sehr unterschiedlichen Unterstützung von Zertifikaten auf Endgeräte-Seite (z.B. webviewcontrol).
}}

Das Endgerät wird über ein Zertifikat identifiziert.
Zuerst wird ein Zertifikat generiert, welches dann auf dem Endgerät installiert werden muss.

Diese Methode der Identifizierung verspricht höhere Sicherheit, wie auch denn Vorteil, das man sich nicht einloggen muss.

==Troubleshooting==
=== generelles Vorgehen ===

Generelles Vorgehen bei seltsamen Erscheinungen:
* smartVISU-Page-Cache ausschalten (auf der Config Seite von smartVISU, wo auch der Treiber konfiguriert wird)
* smartVISU-temp-Verzeichnis leeren (e.g. /var/www/html/smartvisu/temp)
* Browser neu starten
* Konsole im Browser öffnen und nach Errors schauen
* Verbose Level des FHEM-Device <code>fronthem</code> und <code>fronthemDevice</code> auf 5 setzen und im Log nach Errors schauen
{{Link2Forum|Topic= 30909|Message=272083|LinkText=Forum}}, {{Link2Forum|Topic= 35960|Message=285384|LinkText=Forum}}

=== keine Events ===

Es gibt immer mal die Situation, dass man events unterdrückt und für eine spätere Anwendung in Zusammenhang mit einem Frontend, sich nicht mehr daran erinnert. Daher sollte bei ausbleiben eines entsprechenden Auslösung aus FHEM immer kontrolliert werden, dass die Events nicht durch event-min..., event-on..., etc. unterdrückt wird. {{Link2Forum|Topic= 30909|Message=236073|LinkText=Forum}}

=== keine GADs im Editor ===

Die GADs werden beim Aufruf einer Seite (in smartVISU) an fhem übertragen.
In smartVISU ein <code>ctrl+F5</code> ausführen, danach einen Seitenreload in fhem.
{{Link2Forum|Topic= 30909|Message=269984|LinkText=Forum}}

=== Verbindung ===

Erhält an eine "no connection" Warnung in smartVISU sollte man folgendes kontrollieren:
* Wurde auf der config-Seite von smartVISU auf dem Endgerät der Treiber auf "Fhem" gestellt?
* Ist auf der config-Seite von smartVISU auf dem Endgerät die richtige Adresse des WebSocket Servers (meistens der Server mit der FHEM-Instanz) und der Port 2121 eingetragen?
* Wurde für das fronthemDevice die richtige IP-Adresse definiert?
* Steht "connected" im state des fronthemDevice ?
{{Link2Forum|Topic= 30909|Message=236681|LinkText=Forum}}

=== VPN ===

Beim Zugriff durch einen VPN-Tunnel muss sichergestellt sein, dass der VPN-Tunnel sowohl Zugriff auf Port 8083 (FHEMWEB) (Anmerkung: Ist das tatsächlich so?) als auch auf Port 2121 (fronthem) zulässt. Darüber hinaus wird einem per VPN angemeldeten Endgerät normalerweise eine andere interne IP-Adresse zugeordnet, als wenn das Endgerät sich im lokalen LAN befände. {{Link2Forum|Topic= 30909|Message=281398|LinkText=Forum}}

=== alternativer Treiber zum loggen auf der Konsole ===

Falls mal ein Widget den Websocket Server zum Absturz bringt, was mittlerweile nicht mehr passieren sollte, wurde im {{Link2Forum|Topic= 30909|Message=273617|LinkText=Forum}} ein Treiber veröffentlich, der das "überlebt" und auf der Konsole weiter loggt, welches Widget es verursacht hat.

== Links ==
{{Link2Forum|Topic= 27291|Message=219207|LinkText=Detaillierte Funktionsbeschreibung}} aus der Entwicklungszeit.

[[Kategorie: FHEM Frontends]]

Fronthem

2016-06-22T18:26:12Z

Joshi04: Gruundsätzliche Überarbeitung der Artikelserie fronthem/smartVISU

{{Infobox Modul
|ModPurpose=Anbindung von externen Frontends an FHEM
|ModType=x


|ModForumArea=Sonstige Systeme
|ModTechName=01_fronthem.pm, 31_fronthemDevice.pm, fhconverter.pm, fronthemEditor.js
|ModOwner=[http://forum.fhem.de/index.php?action=profile;u=769 Jörg alias herrmannj]
}}

Dieser Artikel befasst sich mit den FHEM-Modulen und weiteren Dateien, die für die Integration von fronthem in FHEM notwendig sein. Ein weiterer separater Artikel beschreibt die [[Installation Fronthem|Installation von Fronthem]].

Fronthem verfolgt die Idee, ein externes Web-Frontend (z. B. [[smartVISU]]) an fhem anzukoppeln und den Datenverkehr sowie die Zusammenarbeit von Befehlen und Parametern zwischen FHEM und dem Web-Frontend zu übernehmen.

Fronthem ist ein Projekt von herrmannj und wurde im {{Link2Forum|Topic= 27291|Message=27291.0l|LinkText=fhem-Forum}} erstmalig angekündigt.

Für die Installation eines passenden Web-Frontends (z.B. smartVISU), sowie dessen [[smartVISU Installation|Installation]] gibt es jeweils eigenständige Artikel.

__TOC__

{{Todo|Redaktionelle Überarbeitung der Detailbeschreibung für Readings Converter RGBCombined. Beschreibung der Converter ReadingsTimestamp, Attribute, Trigger.}}

Die Integration von fronthem als Interface innerhalb von FHEM besteht aus vier Bausteinen:

==Bausteine==
=== websocket ===
Der Websocket ist eine generische http-Schnittstelle, die von einem externen Frontend aus angesprochen werden kann.

Der Websocket Server wird durch das fhem-Modul "fromthem" automatisch gestartet, sobald ein Device vom TYPE <code>fronthem</code> definiert wurde. Der zugehörige Prozess läuft vom fhem Hauptprozess entkoppelt und kann mit ihm kommunizieren.

Der Websocket wird standardmäßig auf Port 2121 angesprochen, wird implizit durch die anderen Bausteine verwendet und benötigt im Prinzip keine weitere Beachtung, außer man möchte das Webinterface auf einem anderen Device neben FHEM laufen lassen.

Allerdings ist dieses das eigentliche Interface zwischen FHEM und einem externen Frontend.

Die Datei 01_fronthem.pm für dieses Modul liegt standardmäßig wie alle anderen Module im Ordner .../fhem/FHEM/.

=== device connector ===
Ein Device-Connector dient dazu, ein Endgerät eines Benutzers (PCs, Tablets, Smartphones usw.) als Clients zu konfigurieren und dessen Berechtigungen (read, write) auf der Ebene einzelner Objekte zu steuern. Damit können z. B. die Nachkommen oder Gäste zwar das Licht und die Heizung im eigenen Raum steuern, nicht aber die Programmierung der Heizung ändern oder den Alarm ausschalten.

Ein Endgerät wird dabei jeweils als Device vom TYPE <code>fromthemdevice</code> innerhalb von FHEM definiert. Details zur genauen Einrichtung finden sich im [[#Integration in FHEM|Verlauf]] dieses Artikels.

An einem einzelnen Device-Connector werden die durch den websocket vom externen Frontend mitgeteilten Objekte aufgelistet (GADs) und können dort einerseits mit fhem devices verbunden und andererseits in den Berechtigungen des jeweiligen Endgerätes konfiguriert werden.

Die Kombination der Frontend-items (GADs) mit den fhem-Devices über die Converter wird nur einmal benötigt und hat eine globale Gültigkeit. Die Berechtigungen der verwendeten Endgeräte werden jeweils pro Endgerät gesetzt. Details zum Konfigurieren und Duplizieren von Berechtigungen finden sich im weiteren [[#Integration in FHEM|Verlauf]] dieses Artikels. Auch eine Zugriffsberechtigung über eine PIN-Abfrage ist angedacht, bislang (Juni 2016) aber noch nicht implementiert.

Änderungen von Readings, Events werden dabei per {{Link2Forum|Topic= 27291|Message=209920l|LinkText=push}} auf die Devices verweilt.

Die Datei 31_fronthemDevice.pm für dieses Modul liegt standardmäßig wie alle anderen Module im Ordner .../fhem/FHEM/.

=== readings converter ===

Die readings converter dienen dazu, die Verbindung zwischen den Informationen in FHEM (states, readings, events) und den Formaten, die innerhalb des Frontends verwendet werden, herzustellen. Die Readings von FHEM müssen in die Form der möglichen Werte des Frontends umgewandelt werden. Im umgekehrten Fall müssen Befehle des Frontends in FHEM kompatible Befehle umgesetzt werden.

Über das Konzept der converter können FHEM-Devices unterschiedlichster Typen und Funktionen über das Frontend bedient werden. So versorgt der gleiche converter der die Solltemperatur des virtuellen Heizungsthermostats (bidriektional) einstellt auch die Füllstandanzeige der Zisterne sowie den Dimmer. In den genannten Fällen handelt es sich um die Übertragung von numerischen Werten. Converter können dabei auch Spezialaufgaben wie die Begrenzung des Wertebereichs übernehmen. So lässt sich über NumDirect zum Beispiel die Solltemperatur Einstellung für virtuelle Heizungsregler auf Min und Max Werte begrenzen.

Standardmäßig gibt es folgende Converter:
* [[#Direct]] für Übertragung ohne Konvertierung
* [[#NumDirect]] für Übertragung von Zahlenwerten in einem begrenzten Werteraum zwischen Min und Max
* [[#NumDisplay]] für Zahlenwerte aus fhem Readings, nur lesend
* [[#OnOff]] für Schalter, Übersetzung von On in 1 und Off in 0
* [[#RGBCombined]] für Übertragung von RGB-Werten so das sie FHEM akzeptiert
* [[#ReadingsTimestamp]] (vorhanden, Beschreibung TODO)
* [[#Attribute]] (vorhanden, Beschreibung TODO)
* [[#Trigger]] (vorhanden, Beschreibung TODO)

Weitere Readings Converter können darüber hinaus [[#eigene Converter|individuell selbst]] definiert werden.

Die Datei fhconverter.pm, die die oben genannten Converter enthält, liegt standardmäßig wie alle anderen Module im Ordner .../fhem/FHEM/.

Die hier beschriebenen Converter sind kompatibel mit dem oben erwähnten Frontend smartVISU und werden auf dessen Basis erklärt. Für die Verwendung in Kombination mit anderen Frontends müssen die Converter möglicher Weise entsprechend angepasst werden.

====Direct====
Die Werte werden ohne Konvertierung weitergegeben.

Gibt den Wert des von <reading> ohne weitere Wandlung an das Frontend weiter. In umgekehrter Richtung wird der vom Frontend geliefert Wert ohne Wandlung im hinterlegten <set> eingesetzt.

Beispiel:
:Anzeige eines An- oder Abwesenheitszustandes im Frontend (Textanzeige, Icon, Button)

====NumDirect====
NumDirect arbeitet bidirektional. Die Werte werden genau wie bei Direct ohne Umwandlung weitergegeben.

Der Unterschied zu Direct besteht jedoch darin, dass nur Zahlenwerte übergeben werden, d.h. die Zahlen werden aus <reading> herausgefiltert.

Des Weiteren kann man einen minimalen und maximalen Wert mit angeben. Dieses soll verhindern, dass im Frontend Werte eingestellt werden, die überhaupt keinen Sinn ergeben.

Beispiel:
:In der smartVISU könnte man für einen Raumthermostaten z.B. -100°C einstellen, was der Aktuator auf Seiten von FHEM nicht umsetzen kann (minimal einstellbarer Wert).

==== NumDisplay ====
NumDisplay arbeitet nur in eine Richting, von FHEM zum Frontend. Die Werte werden ohne Umwandlung weitergegeben, bis auf die Tatsache, dass wie beim Converter NumDirect nur Zahlenwerte übergeben werden, d.h. die Zahlen werden aus <reading> herausgefiltert.

Es ist dazu gedacht Zahlenwerte zu übergeben, ohne etwas zu verändern.

Beispiel:
: Anzeige des Raumklimas (Temperatur, Feuchtigkeit, CO2, Lautstärke, etc.)

==== OnOff ====

Dieser Converter ist für das einfache Schalten von Ein/Aus-Funktionen vorgesehen.

FHEM interpretiert Ein/Aus-Funktionen mit on/off, innerhalb von smartVISU entsprechen diese Zustände jedoch 1/0.

Der OnOff-Converter wandelt diese bidirektional ineinander um.

Beispiel:
: Schalter

==== RGBCombined ====
Dieser Converter dient zur Steuerung von RGB Leuchtmitteln über Farbauswahlfelder (zb. Farbkreis). Eine Besonderheit ist hier, dass smartVISU die 3 RGB Werte separat verarbeitet. D.h. von FHEM wird ein RGB-Wert in HEX in 3 Werte, jeweils für R, G und B, aufgeteilt und an das Frotnend übergeben. In umgekehrter Richtung wird die Auswahl einer Farbe im Frontend mit den 3 Werten für R, G und B an den Converter übergeben, kombiniert und an FHEM übergeben.

Entsprechend arbeitet er bidirektional und wandelt 3 Frontend Items in ein FHEM-Objekt um. Damit die Kombination der Werte funktioniert, muss dieser Converter gleichlautend für alle 3 RGB Kanäle des Frontends definiert werden.

reading: Name eines reading mit HEX RGB Wert des Leuchtmittels

converter (mit Parameter): <code>RGBCombined <itemRed>, <itemYellow>, <itemBlue></code>

set: Name des set Befehls, bekommt HEX RGB Wert übergeben

==== ReadingsTimestamp ====
Dieser Converter ist im Modul bereits enthalten, dessen Beschreibung ist allerdings TODO.

==== Attribute ====
Dieser Converter ist im Modul bereits enthalten, dessen Beschreibung ist allerdings TODO.

==== Trigger ====
Dieser Converter ist im Modul bereits enthalten, dessen Beschreibung ist allerdings TODO.

==== eigene Converter ====
Zusätzlich zu den bestehenden Convertern besteht die Möglichkeit, eigene zu definieren. Diese können in der 99_myUtils.pm oder einer neu angelegten 99_fronthemUtils.pm definiert werden. Es ist nicht ratsam, die fhconverter.pm dafür zu verwenden, da bei einem möglichen späteren Update diese Datei überschrieben wird. Wie alle anderen Module, muss sich die Datei im Verzeichnis./fhem/FHEM/ befinden. ({{Link2Forum|Topic= 30909|Message=266944|LinkText=Forum}})

Eigene Converter müssen nur die gleiche Signatur haben und in dem gleichen namespace wie die im fhconverter.pm stehen dann werden sie dynamisch geladen und stehen in fronthem zur Verfügung. ({{Link2Forum|Topic= 30909|Message=236070l|LinkText=Forum}})

==== Ideen für weitere Converter ====

Zwei weitere Converter sind angedacht, aber derzeit noch nicht Teil des Moduls.

===== NumDelayed =====
NumDelayed ist noch in Arbeit.

Ein bidirektionaler numerischer Converter mit einstellbarer Verzögerung.

Bietet bei der Ansteuerung mechanischer Aktoren (Markise, Jalousie) Vorteile gegenüber NumDirect. Als Beispiel sei die Steuerung einer Jalousie über einen Slider genannt. Da Slider ihre Werte kontinuierlich an FHEM übermitteln, würde bei der Verwendung anderer Converter dem entsprechenden Aktor (z.B. HM-BP), während der Benutzer den Slider bedient, mehrfach der vermeindliche Sollwert übermittelt werden. Gleichzeitig beginnt der Aktor seine Fahrt und übermittelt dem Slider seine aktuelle ist Position. Das führt zu einem springen des Sliders und einer "unschönen" Bedienung.

NumDelayed nimmt daher die Signale des Sliders entgegen, wartet jedoch mit der Weitergabe solange, bis sich der Slider (xxx ms, konfigurierbar) nicht mehr bewegt. In Gegenrichtung wird ebenso verfahren, erst wenn der Aktor seine Endposition erreicht, wird der Slider im Frontend aktualisiert. In diesem Beispiel würde das bedeuten das der Slider im Normalfall ohnehin so steht (Soll) wie vom Aktor gemeldet (Ist). Natürlich könnte der Benutzer oder ein Hindernis die Fahrt auch unterbrochen haben, dann würde der Slider auf die gemeldete Position aktualisiert.

===== WordDisplay =====
WordDisplay ist derzeit in Planung, es wird noch über die Umsetzung diskutiert.

Der Converter soll nur in eine Richtung arbeiten, FHEM zu Frontend. Es ist dazu gedacht Wörter oder Textpassagen zu übertragen. Jedoch soll es möglich sein, eine Umwandlung selbst festzulegen. So kann man einfach mehrere Textausgaben abhängig vom Zustand an das Frontend schicken:

Beispiel:
: Geofancy: Home -> Zuhause, Underway -> Unterwegs, Work -> Arbeit

=== fronthemEditor ===

Um einen komfortable Möglichkeit zur Verfügung zustellen, die Bindung und Konvertierung zwischen FHEM Device/Reading und Frontend-Objekt festzulegen, gibt es einen Javascript Editor als Erweiterung von FHEMWEB. Er wird durch die Datei fronthemEditor.js realisiert, die im Ordner .../fhem/www/frontend/pgm2/ abgelegt ist.

Sobald ein fronthemDevice (Definition für ein Endgerät) definiert ist, kann man über dessen Details in FHEMWEB die GADs definieren und die Rechte verteilen.

==== GAD Liste ====
Auf der Detailseite werden im oberen Teil die GADs aufgelistet die von smartVisu "angefragt" wurden. In vier Spalten werden von links der GAD-Name (wie auf der smartVISU-Seite definiert), das damit verbundene FHEM-Device, für das frontemDevice gesetzte Lese-Rechte und Schreib-Rechte angezeigt. Im oberen Teil des Fensters lässt sich eine Zeichenkette eingeben, nach der die Liste gefiltert wird. (Zumindest in Dark-Style hat die Schrift der eingegebenen Zeichenkette die gleiche Farbe wie der Hintergrund).

Die Verknüpfung zwischen GAD und FHEM-Device gilt global und muss nur einmal für ein beliebiges fronthemDevice eingerichtet werden. Lese- und Schreibrechte können pro fronthemDevice konfiguriert werden.

Wichtig zu berücksichtigen ist die Tatsache, dass die GAD-Liste erst dann aktualisiert wird, wenn einmal die entsprechende Frontend-Seite von einem frontendDevice aufgerufen wurde. Die korrekte Konfiguration des Treiber auf der Config-Seite für das frontendDevice (siehe Installation des Frontends) wird dabei vorausgesetzt. Die Liste wird also erst gefüllt, wenn erstmalig vom Frontend über einen Seitenaufruf die Verbindung zu FHEM initiiert wurde.

==== GAD Edit ====
Klickt man auf einen GAD aus der obigen Liste, öffnet sich ein weiteres Feld mit Titel "GAD Edit".
Das Feld ist in 2 Teile aufgeteilt, im oberen das globale Mapping zwischen GAD und FHEM-Device/Reading, darunter die Zugriffsrechte für das jeweilige Device. Am unteren Ende des Feldes sind Schaltflächen für das Löschen und Sichern von GADs aus der Liste oder das Abbrechen der Bearbeitung angeordnet.

Die GAD-Definierung im oberen Bereich besteht aus:
[[Datei:DeviceDefine.png|400px|thumb|right|GADs definieren]]
*mode
*device
*reading
*converter
*cmd set

===== mode =====

Es gibt 2 Modi:
*item
*plot

Die Unterscheidung ist selbsterklärend, alles was kein "plot" werden soll, wird als "item" definiert.

===== device =====

Hier wird der Name des FHEM-Devices eingetragen, an das die Befehle geschickt werden, bzw. dessen Readings angezeigt werden sollen. Die vorhandenen Devices in fhem werden als Liste unter dem Eingabefeld angezeigt, sobald man mit der Eingabe beginnt.

Wie überall innerhalb von FHEM ist die Groß/Kleinschreibung zu beachten.

===== reading =====

Für das <reading> wird das zu verwendende Reading des FHEM Devices angegeben, z. B. "state" oder "Level". Die vorhandenen Readings des gewählten fhem-Devices werden als Liste unter dem Eingabefeld angezeigt, sobald man mit der Eingabe beginnt.

Änderungen, wenn fhem entsprechende events erzeugt, werden von fronthem mitgelesen und per push an die fronthemDevices gesendet.

===== converter =====

Hier gibt man denn Namen des Converters an, denn man verwenden möchte. Wie oben beschrieben, stehen unterschiedliche [[#readings converter|converter]] für verschiedene Aufgabenstellungen zur Verfügung. Die meisten Devices können mit diesen Convertern angesteuert werden.

Wie überall innerhalb von FHEM ist die Groß/Kleinschreibung zu beachten.

===== cmd set =====

Das zum Schreiben zu verwendende Reading des fhem Devices, z. B. "state" oder "Level". Die vorhandenen Readings des gewählten fhem-Devices werden als Liste unter dem Eingabefeld angezeigt, sobald man mit der Eingabe beginnt.

Das gewählte Reading gibt den "set" des fhem Devices an, der die Rückgabe des Converters entgegen nimmt.

Bei Lampe z.B. "state".

==== Devicerechte vergeben ====

[[Datei:DeviceRechte.png|400px|thumb|right|Devicerechte vergeben]]
Devicerechte bestehen aus:
*Eine Berechtigung für "read"
*Eine Berechtigung für "write"
*Jeweils für Lese- und Schreib-Berechtigung die Festlegung eines PINs

===== read =====
Das Device darf die Statuswerte auslesen.

===== write =====
Das Device darf Statuswerte ändern.

===== PIN GAD =====

Die PIN-Abfrage für die Lese- oder Schreibberechtigung ist derzeit noch nicht implementiert, daher ist es irrelevant, was hier eingetragen wird.

===== Attribut Whitelist =====
Möchte man die differenzierte Berechtigungssteuerung für ein fronthemDevice außer Kraft setzen, kann das Attribut "whitelist" für das entsprechende fronthemDevice auf false gesetzt werden. Das bedeutet dann, dass unabhängig von den Berechtigungs-Checkboxen das fronthemDevice immer für alle GADs lesen und schreiben darf.

== Integration in FHEM ==

=== fronthem ===

Ein Device vom TYPE <code>fronthem</code> und damit das eigentlich Interface, wird nach erfolgreicher Sicherstellung der Voraussetzungen (siehe fronthem Installation) über folgenden Befehl in der Eingabezeile von FHEMWEB definiert:
:<code>define <name> fronthem</code>

Über diese Definition wird ebenfalls die Verbindung zum WebSocket sichergestellt. Logischer Weise benötigt man nur ein Device von diesem Typ.

Als Reading wird
* die Verbindung zum WebSocket angezeigt. "open" stellt dabei den normalen Zustand dar.
* lastError angezeigt, woran man beispielsweise erkennen kann, dass für Endgerät der Zugriff abgelehnt wurde ("client <IP-Adress> rejected").

Der state des Devices gibt dabei derzeit keine Meldung zurück. Ein Wert "???" ist daher kein Hinweis auf einen Fehler, sondern entspricht dem ganz normalen Modulverhalten.

===Device Connector===
Für jedes Endgerät (smartphone, PC, Tablet, etc.) mit dem man auf das Frontend zugreifen möchte, muss ein entsprechendes fronthemDevice definiert werden.
Wie oben bereits beschrieben, kann dadurch genau festgelegt werden, welches Endgerät welche Rechte für eine jeweilige Schalt-/Anzeigefunktion hat.

Wenn man die Berechtigungen für neue Endgeräte kopieren möchte, liegen diese unter ./fhem/www/fronthem/clients/<fronthemDevice> und lassen sich so einfach für neue Endgeräte übertragen.

====IP-Identify====

Ein Endgerät wird über seine IP_Adresse identifiziert. Dies ist nur im internen gesicherten Netzwerk empfehlenswert. Es wird definiert mit:
:<code>define <device> fronthemDevice <ip></code>

Dabei ist für die IP-Adresse die des Endgerätes anzugeben, welches auf den smartVISU zugreifen soll (also das Tablet, Rechner, Smartphone etc.). Entsprechend selbstverständlich ist, dass man durch eine passende Einstellung seine DHCP-Servers oder fest vergebene IP-Adressen sicherstellt, dass ein Endgerät immer die gleiche IP erhält/verwendet.

Wichtig bei der späteren Verwendung ist, dass pro Endgerät immer nur ein Brower-Tab geöffnet wird, mit dem man auf das Frontend zugreift. Sonst erhält fronthem mehrere Zugriffe von der gleichen IP, die sich gegenseitig ins Gehege kommen.

====Zertificate-Identify====
{{Randnotiz|RNTyp=info|RNText=Hinweis: Diese Möglichkeit wurde während der Entwicklung bereits diskutiert und berücksichtigt, die Verwendung von Zertifikaten wurde bislang aber noch nicht implementiert, hauptsächlich aufgrund der teilweise mangelnden oder zumindest sehr unterschiedlichen Unterstützung von Zertifikaten auf Endgeräte-Seite (z.B. webviewcontrol).
}}

Das Endgerät wird über ein Zertifikat identifiziert.
Zuerst wird ein Zertifikat generiert, welches dann auf dem Endgerät installiert werden muss.

Diese Methode der Identifizierung verspricht höhere Sicherheit, wie auch denn Vorteil, das man sich nicht einloggen muss.

==Troubleshooting==
=== generelles Vorgehen ===

Generelles Vorgehen bei seltsamen Erscheinungen:
* smartVISU-Page-Cache ausschalten (auf der Config Seite von smartVISU, wo auch der Treiber konfiguriert wird)
* smartVISU-temp-Verzeichnis leeren (e.g. /var/www/html/smartvisu/temp)
* Browser neu starten
* Konsole im Browser öffnen und nach Errors schauen
* Verbose Level des FHEM-Device <code>fronthem</code> und <code>fronthemDevice</code> auf 5 setzen und im Log nach Errors schauen
{{Link2Forum|Topic= 30909|Message=272083|LinkText=Forum}}, {{Link2Forum|Topic= 35960|Message=285384|LinkText=Forum}}

=== keine Events ===

Es gibt immer mal die Situation, dass man events unterdrückt und für eine spätere Anwendung in Zusammenhang mit einem Frontend, sich nicht mehr daran erinnert. Daher sollte bei ausbleiben eines entsprechenden Auslösung aus FHEM immer kontrolliert werden, dass die Events nicht durch event-min..., event-on..., etc. unterdrückt wird. {{Link2Forum|Topic= 30909|Message=236073|LinkText=Forum}}

=== keine GADs im Editor ===

Die GADs werden beim Aufruf einer Seite (in smartVISU) an fhem übertragen.
In smartVISU ein <code>ctrl+F5</code> ausführen, danach einen Seitenreload in fhem.
{{Link2Forum|Topic= 30909|Message=269984|LinkText=Forum}}

=== Verbindung ===

Erhält an eine "no connection" Warnung in smartVISU sollte man folgendes kontrollieren:
* Wurde auf der config-Seite von smartVISU auf dem Endgerät der Treiber auf "Fhem" gestellt?
* Ist auf der config-Seite von smartVISU auf dem Endgerät die richtige Adresse des WebSocket Servers (meistens der Server mit der FHEM-Instanz) und der Port 2121 eingetragen?
* Wurde für das fronthemDevice die richtige IP-Adresse definiert?
* Steht "connected" im state des fronthemDevice ?
{{Link2Forum|Topic= 30909|Message=236681|LinkText=Forum}}

=== VPN ===

Beim Zugriff durch einen VPN-Tunnel muss sichergestellt sein, dass der VPN-Tunnel sowohl Zugriff auf Port 8083 (FHEMWEB) (Anmerkung: Ist das tatsächlich so?) als auch auf Port 2121 (fronthem) zulässt. Darüber hinaus wird einem per VPN angemeldeten Endgerät normalerweise eine andere interne IP-Adresse zugeordnet, als wenn das Endgerät sich im lokalen LAN befände. {{Link2Forum|Topic= 30909|Message=281398|LinkText=Forum}}

=== alternativer Treiber zum loggen auf der Konsole ===

Falls mal ein Widget den Websocket Server zum Absturz bringt, was mittlerweile nicht mehr passieren sollte, wurde im {{Link2Forum|Topic= 30909|Message=273617|LinkText=Forum}} ein Treiber veröffentlich, der das "überlebt" und auf der Konsole weiter loggt, welches Widget es verursacht hat.

== Links ==
{{Link2Forum|Topic= 27291|Message=219207|LinkText=Detaillierte Funktionsbeschreibung}} aus der Entwicklungszeit.

[[Kategorie: FHEM Frontends]]

SmartVISU/Universelle ZeitSchaltUhr (UZSU)

2016-06-22T18:20:02Z

Joshi04: Auslagerung des Themas UZSU aus dem fronthem Artikel.

SmartVISU

2016-06-22T18:19:06Z

Joshi04: Auslagerung des Themas UZSU aus dem fronthem Artikel.

Diskussion:PanStamp

2016-06-14T02:02:13Z

Joshi04: Mit der Neustrukturierung der Artikelserie panStamp wurde die Diskussionsseite auf den aktuellen Stand gebracht (abgeschlossen).

__NOTOC__

<strike>
== Anmerkung für die hier vorgeschlagene Änderung des Hauptartikels ==
Während ich mich mit dem Thema vertraut gemacht habe, habe ich versucht, alle Informationen, die aus non-developer Sicht für die spätere Anwendung und Inbetriebnahme relevanten Informationen (also aus meiner ;) ) wichtig erscheinen, hier in einem Artikel zusammenfassen. Ich muss gestehen, bis ich meine ersten Panstamps am Laufen hatte, musste ich viel lesen und der derzeitige Artikel setzt mM recht viel Wissen voraus (alles eine Frage des Wissensstandes).
Die Inhalte des derzeitigen Artikels habe ich übernommen und einfließen lassen, d.h. es ist geplant, die derzeitige Seite zu ersetzen!

In diesem Artikel sind alle Posts bis heute (14.04.2015) aus den beiden Threads {{Link2Forum|Topic=12487 |Message=74967 |LinkText=Thema: panStamp support }} und {{Link2Forum|Topic=13890 |Message=86952 |LinkText=Thema: PanStamp Board RGB,CW,WW;DMX;IR }} berücksichtigt.

Da viele Informationen vor allen Dingen aus der Zeit der Entwicklung der Module und der Sketches stammen, bitte ich Euch, hier kritisch quer zu lesen, das geschriebene zu prüfen, ob noch aktuell und ggf. zu korrigieren, zu ergänzen oder im Forum konstruktiv zu kommentieren.
</strike>

Dinge, die mir unklar waren, da noch nicht getestet oder Dinge, die noch näherer beschrieben werden können, habe ich mit "?" bzw. "TBC" (to be confirmed) gekennzeichnet.
----
: Hallo, wie ist denn der Stand mit dem Artikel? Finde es schade, dass das gesammelte Know-how hier nur auf der Diskussionsseite zu finden ist. --[[Benutzer:TeeVau|TeeVau]] ([[Benutzer Diskussion:TeeVau|Diskussion]]) 12:07, 15. Jul. 2015 (CEST)
----
:: Hallo TeeVau, danke, dass Du den Faden aufgenommen hattest. Ich habe die Struktur noch ein wenig überarbeitet und mit Berücksichtigung meiner ursprünglichen Idee den Artikel [[panStamp]] ersetzt. Die Neustrukturierung ist aus meiner Sicht damit vollzogen und abgeschlossen, mein ursprüngliches Ziel erreicht. Änderungshistorie der Artikelserie ist {{Link2Forum|Topic=54109|Message=458488l|LinkText=hier}} nochmal beschrieben.-- [[Benutzer:joshi04|joshi04]] ([[Benutzer Diskussion:joshi04|Diskussion]]) 03:38, 14. Jun. 2016 (CEST)

<strike>
{{SEITENTITEL:panStamp}}

<nowiki>{{Infobox Hardware
|Bild=panStamp.jpg
|Bildbeschreibung=panStamp
|HWProtocol=SWAP
|HWType=Sender, Empfänger, Sensor, [[Interface]]
|HWCategory=
|HWComm=868MHz (433/915MHz)
|HWChannels=
|HWVoltage=3.3V (panStick: 5V USB)
|HWPowerConsumption=
|HWPoweredBy=Battery (panStick: USB)
|HWSize=17.7 x 30.5 mm
|HWDeviceFHEM=[http://fhem.de/commandref.html#panStamp 34_panStamp.pm] [http://fhem.de/commandref.html#SWAP 34_SWAP.pm]
|ModOwner=[http://forum.fhem.de/index.php?action=profile;u=430 Andre / justme1968]
|HWManufacturer=panStamp
}}</nowiki>

<big>Todo:Fehlerkontrolle, Formatierung, Ergänzung, Bestätigung des Geschriebenen, weitere Informationen zur Erstellung/Anpassung eines Device Description Files, Bestätigung des Hochladens mittels XLoader, Bedienung in FHEMWEB(RGB-Board/Sketch)</big>

== Allgemeines ==

=== Hardware ===
==== panStamp mit Antenne ====
[http://www.panstamp.com/home panStamps] sind [[Arduino]] Clones, die ein CC1101 Funkmodul beinhalten. Mit ihnen lassen sich Sensoren und Aktoren drahtlos an FHEM anbinden. Sie lassen sich genau wie Arduinos über die Ardunio IDE oder mit dem ino Kommandozeilen Binary programmieren.

Um einen panStamp in Betrieb zu nehmen muss er unbedingt mit einer Antenne oder einem stück Draht in der [https://code.google.com/p/panstamp/wiki/antennalengths richtigen Länge] bestückt sein. Ohne Antenne funktioniert die Übertragung nicht. Auch nicht auf kurze Distanzen.

Mittlerweile gibt es zwei verschiedene panStamps (AVR und NRG), von denen der NRG neuer und etwas mehr Features zur Verfügung stellt, allerdings (noch) nicht mit allen hier beschriebenen Projekten kompatibel ist.
</strike>

Inhalt wurde spätestens mit der Neustrukturierung der Artikelserie "panStamp" eingearbeitet. -- [[Benutzer:joshi04|joshi04]] ([[Benutzer Diskussion:joshi04|Diskussion]]) 03:38, 14. Jun. 2016 (CEST)

<strike>
==== Panstick oder Panshield ====
Als Schnittstelle zwischen Server-Hardware und einem panStamp dient entweder ein panStick (USB Stick mit Sockel zum aufstecken eines panStamp) oder ein "panStamp Shield" mit integriertem panStamp an einem Raspberry Pi. Der Panstick stellt dabei die Verbindung zwischen dem USB-Port auf der einen Seite und dem seriellen Interface des Panstamps auf der anderen Seite dar. Ein Panshield übernimmt die gleiche Funktion, wird aber direkt an die IOs eines Raspberries angeschlossen.

Der Panstick wird grundsätzlich für zwei Aufgaben benötigt:
# Für die Vorbereitung eines panStamps für den Betrieb auf einem "Board" wird der neue panStamp in den Panstick gesteckt, um die Programmierung (flashen des Sketch) vorzunehmen.
# Im "normalen" Betrieb steckt ein panStamp auf ihm. Der so angebundene panStamp wird mit einem (bei Auslieferung des PanStamps vorinstallierten) Modem-Sketch als RF Modem verwendet und dient so dem Rechner als Interface zu anderen panStamps, zu denen über eine Funkstrecke mittels des SWAP-Protokolls kommuniziert wird.

Da auf dem panStamp Shield der panStamp fest eingelötet ist, übernimmt dieser in der Regel nur die zweite Funktion.

</strike> Inhalt in Artikel <nowiki>[[panStick]]</nowiki> übernommen. --[[Benutzer:TeeVau|TeeVau]] ([[Benutzer Diskussion:TeeVau|Diskussion]]) 21:10, 17. Jul. 2015 (CEST)

==== spezifisches "Board" ====
{{Randnotiz|RNText=In Artikel [[panStamp]]}}
<strike>
: Im Gegenzug zum Panstick als Interface zwischen panStamp und USB-Port des Servers stellt das Board das Interface zwischen panStamp vor Ort und Input/Outputs (analog/digital) dar. Das "Board" nimmt den panStamp mit dem passenden Sketch auf und setzt die Outputs des panStamps auf die Ausgänge um bzw. leitet die Eingänge zur Auswertung an den panStamp weiter.
: Entsprechend Anwendungsfall und Sketch werden die Ein-/Ausgänge des panStamps verarbeitet. Z.B. können an ein Board Temperatur-, Feuchtigkeitssensoren oder LED-Strips angeschlossen werden. Der Sketch auf dem panStamp sollte entsprechend der Anwendung auf dem Board angepasst worden sein um nicht nur über die standardmäßig zur Verfügung stehenden Register kommunizieren zu müssen.

: Das Board benötigt irgend eine Art von Stromversorgung, um den panStamp zu betreiben. Das kann im Falle eines Sensorboards und entsprechend stromsparend ausgelegtem Sketch eine Batterie sein oder wie im Falle des RGB-Boards eine externe Stromversorgung.
: Speziell beim unten beschriebenen RGB-Board kann die Stromversorgung sogar separat für panStamp und LEDs ausgeführt sein oder ingesamt panStamp und LEDs gemeinsam versorgen.

</strike> Inhalt in Artikel [[panStamp]] übernommen.--[[Benutzer:TeeVau|TeeVau]] ([[Benutzer Diskussion:TeeVau|Diskussion]]) 13:08, 19. Jul. 2015 (CEST)
=== Software ===

==== Simple Wireless Abstract Protocol (SWAP) ====
<strike>
Zur Kommunikation in einem panStamp Netzwerk dient das ''Simple Wireless Abstract Protocol'' ([http://code.google.com/p/panstamp/wiki/SWAP SWAP]).
Die komplette SWAP- Kommunikation ist registerbasiert und erfolgt mit Nachrichten um diese Register abzufragen, zu setzen und deren Inhalt zu senden. Alle Register lassen sich lesen, manche auch beschreiben.
Der panStamp Software Stack unterstützt einen stromsparenden Power-Down- oder Sleep-Modus für batteriebetriebene Sensoren, aus dem diese dann nur zur eigentlichen Messung und Übertragung "aufwachen".
</strike> In Artikel [[SWAP]] übernommen. --[[Benutzer:TeeVau|TeeVau]] ([[Benutzer Diskussion:TeeVau|Diskussion]]) 19:59, 16. Jul. 2015 (CEST)

==== Modem-Sketch ====
{{Randnotiz|RNText=In Artikel <nowiki>[[panStick]]</nowiki>}}
<strike>
Der Modem-Sketch stellt das Software-Verbindungsglied zwischen panStamp und Funksignal dar, dass an andere panStamps geht.

Auf jedem panStamp (AVR, NRG?) ist im Auslieferungszustand der Modem-Sketch installiert. Das Protokoll der Funkstrecke folgt dem SWAP-Protokoll.

</strike> Inhalt in Artikel <nowiki>[[panStick]]</nowiki> übernommen. --[[Benutzer:TeeVau|TeeVau]] ([[Benutzer Diskussion:TeeVau|Diskussion]]) 13:08, 19. Jul. 2015 (CEST)

==== auf Board abgestimmter Sketch ====
{{Randnotiz|RNText=In Artikel [[panStamp]]}}
<strike>
Ein panStamp ist auf einem entsprechenden Board installiert und übernimmt dort lokal die Schnittstelle zwischen Funkstrecke und Board.

Der Sketch stellt dabei die passende "Software" auf dem panStamp. Der Sketch verarbeitet die über das SWAP-Protokoll versandte Nachrichten, wertet diese aus, reagiert entsprechend und setzt die Outputs des Boards. In umgekehrter Richtung wertet er die an den Inputs des Board angelegten Signale aus, verarbeitet diese und schickt sie per SWAP-Protokoll zum Panstamp mit Modem-Sketch zurück.

</strike> Inhalt in Artikel [[panStamp]] übernommen. --[[Benutzer:TeeVau|TeeVau]] ([[Benutzer Diskussion:TeeVau|Diskussion]]) 13:08, 19. Jul. 2015 (CEST)

==== Module und Description File ====
{{Randnotiz|RNText=In Artikel [[panStamp]]}}
<strike>
Die Integration in FHEM erfolgt über eine Reihe von Modulen die im folgenden genauer beschrieben werden. Zusammengefasst gibt es 3 Ebenen mit der Ergänzung eines Konfigurationsfiles in xml-format.
{{Link2Forum|Topic= 13890 |Message=121689 }}
[http://forum.fhem.de/index.php/topic,13890.msg121689.html#msg121689]
</strike>

Inhalt in Artikel [[panStamp]] übernommen.--[[Benutzer:TeeVau|TeeVau]] ([[Benutzer Diskussion:TeeVau|Diskussion]]) 13:08, 19. Jul. 2015 (CEST)

===== Ebene 1: 34_panStamp.pm =====
<strike>
Das Modul ist für einen panStamp der auf einem panStick sitzt und das Interface zwischen FHEM und dem panStamp netz bildet. Alle eintreffenden SWAP-Pakete auf dem panStick (mit Modem-Sketch) werden direkt durchgereicht und im nachfolgend beschriebenen SWAP-Modul verarbeitet.
</strike>

Inhalt in Artikel [[panStamp]] übernommen.--[[Benutzer:TeeVau|TeeVau]] ([[Benutzer Diskussion:TeeVau|Diskussion]]) 13:08, 19. Jul. 2015 (CEST)

===== Ebene 2: 34_SWAP.pm =====
[[Datei:SWAP_ 0000000100000005-detail.png|mini|hochkant=2.5|Readings]]
<strike>
Das Modul implementiert das SWAP protokoll das zwischen den panStamps gesprochen wird. Das SWAP Modul ermöglicht die generische Integration beliebiger panStamp Sensoren und Aktoren in FHEM.

Bei SWAP geht alle Komunikation über 'register', dies sind unterschiedlich lange Werte die entweder nur gelesen oder gelesen und geschrieben werden können. Jedes device hat eine Reihe System register (00-0A) und beliebig viele user register die vom jeweiligen Sketch abängen. Welche Register dies sind, steht unter anderem jeweils im Device Description xml file im Verzeichnis .../FHEM/lib/SWAP.

In den System Registern steht z.b. der productcode, die device adresse und das Übertragungsintervall. Konfigurierbare register werden im EEPROM gesichert und die Werte gehen auch beim Neustart nicht verloren. Beim aller ersten Starten ist das EEPROM mit "FF" initialisiert und alle konfigurierbaren register haben diesen Wert. also z.b. Adresse FF und Intervall FFFF (HEX in Sekunden, das wären dann zwischen 18 und 19 Stunden).

Die Inhalte der System Register stehen als internal values im oberen Bereich der Detail Ansicht einer Komponente in FHEM, die user register als readings im unteren.

Alle low level Dinge wie Register id oder Register Wert können mit hex werten direkt angepasst werden. Im Normalbetrieb ist dieses aber nicht notwendig und es kann über 'vereinfachte' Kommandos mit den register namen verwenden kann. Diese Funktionalität stellt das eines der Module zur Verfügung.
<pre>
set <device> regSet 0A <intervall in sekunden als 4 stellige hex zahl>
set <device> regSet 08 <netzwerk id als 2 stellige hex zahl>
</pre>

{{Link2Forum|Topic=12487 |Message=87436 }}
[http://forum.fhem.de/index.php?topic=12487.msg87436#msg87436]

Dieses Modul stellt unter anderem folgende grundlegende Funktionalitäten zur Verfügung
* Es wird eine command Liste für Devices im power down Modus gehalten. Sobald das Device online kommt werden die Kommandos automatisch übertragen.
* Die userReadings für 'menschenlesbare' Readings werden anhand des device description files automatisch erzeugt
* Es ist jetzt möglich direkt endpoints (teile eines registers) zu schreiben (???)
* (Fast) keine hardkodierte Sonderbehandlung mehr für das RGB-Board. Das SWAP Modul kann mit jedem beliebige Swap Device umgehen.
* Es gibt eine dritte (optionale) Modulschicht neben dem panStamp modul für die Hardware und dem SWAP Modul für das Protokoll. Mit dem generellen SWAP Modul lasen sich alle SWAP devices 'zu fuss' über die register ansprechen. Um die register auf einer höheren Ebene auf FHEM Kommandos wie on/off/on-for-timer zu mappen ist dann diese dritte schicht zuständig.

{{Link2Forum|Topic=12487 |Message=78502 }}
[http://forum.fhem.de/index.php/topic=12487.msg78502#msg78502]
</strike>

In Artikel [[SWAP]] übernommen. --[[Benutzer:TeeVau|TeeVau]] ([[Benutzer Diskussion:TeeVau|Diskussion]]) 19:59, 16. Jul. 2015 (CEST)

===== Ebene 3: SWAP_XXXXXXXXXXXXXXXX.pm =====
{{Randnotiz|RNText=In Artikel [[panStamp]]}}
<strike>
Besonders bei Aktoren ist oft eine engere FHEM-Integration sinnvoll, um FHEM Konzepte wie on/off/on-for-timer direkt abzubilden und nicht mehr nur auf die Registerebene und regSet und regGet Kommandos beschränkt zu sein.
Mit dieser dritten Modulebene ist es auch für Aktore wie Schalter/Dimmer/... sehr einfach, diese in FHEM zu integrieren.

Wenn die Namenskonvention SWAP_<ProductCode> für diese Module eingehalten wird, funktioniert auch das autocreate sofern das Modul in FHEM bekannt ist.

Um per autocreate automatisch das passende Modul laden zu können, müssen diese Module nach dem Schema SWAP_XXXXXXXXXXXXXXXX.pm benannt sein wobei XXXXXXXXXXXXXXXX für den jeweiligen productCode steht.

Ein Beispiel für das RGB-Board dafür ist das Modul 35_SWAP_0000002200000003.pm.
[[Datei:SWAP_0000002200000003.png|mini|rechts|hochkant=2.5|RGB LED Driver Board]]
</strike>

Inhalt in Artikel [[panStamp]] übernommen.--[[Benutzer:TeeVau|TeeVau]] ([[Benutzer Diskussion:TeeVau|Diskussion]]) 13:08, 19. Jul. 2015 (CEST)

===== Device Description File =====
<strike>
Mit Hilfe der im jeweiligen Device Description File hinterlegten Beschreibung werden hierzu automatisch userReadings angelegt die neben den reinen Registerwerten in hex auch 'menschenlesbare' readings der Sensorwerte erzeugen.
Damit dies funktioniert, muss das Attribut ProductCode korrekt gesetzt sein. Das geschieht normalerweise automatisch beim Anlegen des Device.

Hier Beispielhaft anhand eines BMP085 Temperatur- und Luftdrucksensors dargestellt:

<code>attr temppress userReadings voltage:0B-Voltage {hex(ReadingsVal($name,"0B-Voltage","0"))*0.001}, temperature:0C.0-Temperature {hex(ReadingsVal($name,"0C.0-Temperature","0"))*0.1-50}, pressure:0C.1-Pressure {hex(ReadingsVal($name,"0C.1-Pressure","0"))*0.01}, pressureNN:0C.1-Pressure {sprintf("%.2f",hex(ReadingsVal($name,"0C.1-Pressure","0"))*0.01 + AttrVal("global", "altitude", 0)/8.5)}</code>

[[Datei:SWAP_ 0000000100000005.png|mini|hochkant=2.5|Resultat eines stateFormat]]
Aus diesen readings kann dann mit stateFormat die gewünschte Darstellung für die Raumübersicht erzeugt werden:

<code>attr temppress stateFormat {sprintf("%.1f",ReadingsVal($name,"temperature",0))."°C ".sprintf("%.1f",ReadingsVal($name,"pressureNN",0))."mbar"}</code>

Ein weiteres Beispiel ist das Description File für das RGB-Board rgbdriver.xml.
</strike> In Artikel [[SWAP]] übernommen. --[[Benutzer:TeeVau|TeeVau]] ([[Benutzer Diskussion:TeeVau|Diskussion]]) 19:59, 16. Jul. 2015 (CEST)

=== Systemübersicht ===
<strike>
Zum besseren Verständnis der Begrifflichkeiten und Zusammenhänge ist hier eine Systemübersicht dargestellt.
[[Datei:Panstamp-Systemoverview.jpg|200px|thumb|panStamp Systemübersicht]]

{{Link2Forum|Topic=12487 |Message=75980 }}
[http://forum.fhem.de/index.php?topic=12487.msg75980#msg75980]

Die Kommunikationskette ist wie folgt:
FHEM -> Host-hardware/OS -> USB -> Panstick -> panStamp (Modem-Sketch) -> Funkstrecke (SWAP) -> panStamp (angepasster Sketch) -> Board -> Sensoren/LED-Strip/etc.

(Ein Panshield ersetzt "USB -> Panstick" durch "IO's am Rpi-> Panshield")
</strike>

Inhalt übernommen in Artikel [[panStamp]]. --[[Benutzer:TeeVau|TeeVau]] ([[Benutzer Diskussion:TeeVau|Diskussion]]) 19:50, 17. Jul. 2015 (CEST)

== Schritte der Inbetriebnahme ==
{{Randnotiz|RNText=In Artikel [[panStamp]]}}
<strike>
Beispiel für Kurzentschlossene anhand der Einrichtung für das RGB-Board:

* Ein panStamp wird in einen Panstick gesteckt und der Panstick für die Programmierung z.B. unter Windows installiert. Selbstverständlich kann ein panStamp auch über diverse andere Möglichkeiten und unter diversen anderen Betriebssystemen und über diverse andere Schnittstellen programmiert werden.
* Arduino IDE vorbereiten (libs hinzufügen, Board auswählen, etc.).
* Ein Sketch wird in der Arduino IDE entsprechend konfiguriert, kompiliert und auf den panStamp hochgeladen.
* Der programmierte panStamp aus dem Panstick in das RGB-Board stecken.
* Einen panStamp mit Modem-Sketch in den Panstick stecken und an den FHEM-Host stecken.
* panStamp unter FHEM einrichten, wenn nicht durch autocreate automatisch geschehen.
* RGB-Board mit Strom versorgen und ggf. einmal Reset-Knopf drücken. Dann sollte, falls autocreate aktiv ist, der panStamp automatisch eingerichtet werden.
* SWAP-Device in FHEM an Gegebenheiten anpassen.

</strike> Inhalt in Artikel <nowiki>[[panStamp (Systemübersicht)]]</nowiki> übernommen. --[[Benutzer:TeeVau|TeeVau]] ([[Benutzer Diskussion:TeeVau|Diskussion]]) 11:41, 24. Jul. 2015 (CEST)

== Programmierung eines panStamps ==
<strike>
=== unter Windows ===

==== Installation Panstick ====
Für die Installation des Pansticks unter Windows gibt es mehrere Möglichkeiten.
# Installiert man eine Arduino IDE, kann dabei auch der Treiber für den Panstick mitinstalliert werden.
# Treiber von der offiziellen Homepage herunterladen und installieren [[http://www.ftdichip.com/]]. Die Treiber befinden sich ebenfalls im Unterordner drivers der Arduino IDE.

Bei der Installation kann es sein, dass kein Treiber gefunden wird. Dann muss der entsprechende Treiber manuell ausgewählt werden entsprechend dieser Anleitung [[https://www.youtube.com/watch?v=SPdSKT6KdF8]].

==== Arduino IDE vorbereiten ====

Zum Flashen der panStamps wird die Arduino IDE benötigt. Eine Installationsanleitung ist unter folgendem Link zu finden:
:https://code.google.com/p/panstamp/wiki/firststeps

Die IDE 1.5.x oder höher ist zwar mit den AVRs und NRGs kompatibel, wichtig zu wissen ist allerdings, dass mit dem Wechsel von 1.0.x zu 1.5.x oder höher es größere Änderungen der APIs gegeben hat. Dadurch lassen sich einige der bislang zur Verfügung stehenden Sketches (derzeit) nicht unter 1.5.x oder höher kompilieren (z.B. der RGB-Sketch). Für die IDE 1.0.x gibt es keine passenden Arduino Lib für den NRG [[https://github.com/panStamp/panstamp/wiki/First%20steps]], die daher nur mit den AVRs kompatibel sind. Im Folgenden wird sich für die Programmierung unter Windows daher auf die letzte 1.0.x IDE bezogen.

* Man läd die '''Arduino IDE 1.0.x''' für Windows [[http://arduino.cc/en/Main/OldSoftwareReleases]].

* Für bestimmte Sketches müssen noch die entsprechenden Libs hinzugefügt werden (siehe [[panStamp#Sketch konfigurieren|explizite Anwendung]]).

* Unter Tools/Board wird das '''passende Board''' ausgewählt, dass dem Chip auf dem Panstamp entspricht. Für den AVR: Arduino Pro or Pro Mini (3,3V, 8 MHz) /w ATmega328. Wenn man das boards.txt file von [http://code.google.com/p/panstamp/downloads/detail?name=boards.txt&can=2&q= hier] installiert, kann man in der IDE auch direkt panStamp als Plattform auswählen.

* Nun muss unter Tools/Serieller Port noch der richtigen '''Com-Port''' auswählen werden, unter dem der Panstick eingebunden worden ist (entsprechend Gerätemanager).

* Als letztes unter Tools/'''Programmer''' noch den AVRISP mkII auswählen.

==== Sketch vorbereiten, kompilieren und hochladen ====

* Den Sketch läd man von der entsprechenden Quelle und entpackt die Dateien in einen Unterordner z.B. parallel zum libraries-Ordner (unter "Eigene Dateien"). Der Ordner darf '''nicht im''' libraries-Ordner liegen, da die Arduino IDE dort das Speichern nicht zulässt. Innerhalb des Unterordners erwartet die IDE die Dateien in einen Unterordner namens "sketch".
* sketch.ino oder ähnlich in der Arduino IDE öffnen.
* Nun entsprechend den Bedürfnissen auf dem geöffneten Reiter in den config.h die nicht benötigten Zeilen mit "//" auskommentieren bzw. anpassen.
* Nun sollte über Sketch/Überprüften/Kompillieren die Erstellung des Sketches möglich sein.
* Falls erfolgreich unter Datei/Hochladen (ohne Programmer) den Sketch auf den Panstamp laden.

Bezüglich der Anpassung des Sketches sind einige spezifische Informationen unten bei den expliziten Anwendungen ergänzt.

==== Hexfile hochladen mit XLoader ====
Um ein fertig kompiliertes HEX-File hochzuladen, soll dieses über ein Programm namens XLoader möglich sein. [[http://xloader.russemotto.com]]

=== unter Linux ===

==== Installation Panstick ====

Zum einen kann es sein, dass der Panstick automatisch unter /dev/ttyUSBx einbunden wird. "x" steht für eine freie fortlaufende Nummer.

Falls er nicht automatisch angelegt worden ist, kann man zunächst prüfen, ob dieser überhaupt eingebunden und richtig erkannt wurde.
<pre>
lsusb
</pre>
Sollte etwas ähnliches zurückmelden:
<pre>
Bus 003 Device 002: ID 0403:0000 Future Technology Devices International, Ltd H4SMK 7 Port Hub
</pre>

Falls das Device nicht automatisch angelegt worden ist, muss dieses ggf. von Hand erledigen.

{{Link2Forum|Topic=12487 |Message=87746 }}
[http://forum.fhem.de/index.php/topic,12487.msg87746.html#msg87746]

Mit dem folgenden Befehl sollte in der Liste ein ttyUSB auftauchen. Normalerweise mit der Nummer 188.
<pre>cat /proc/devices</pre>

Das Device wird dann angelegt mit:
<pre>sudo mknod /dev/ttyUSB0 c 188 0</pre>

Zusätzlich muss für den Betrieb des Pansticks das ftdi_sio Modul zur Verfügung stehen. Dieses lässt sich prüfen mit
<pre>lsmod</pre>

Diese Voraussetzung könnte den Betrieb an einer Fritzbox erschweren, da nicht sicher ist, ob dieses Modul standardmäßig immer installiert ist.

Legt man das Device von Hand an, kann es sein, dass die Berechtigungen nicht richtig gesetzt sind.
<pre>
2015.04.23 22:20:06 3: Opening panStick device /dev/ttyUSB0
2015.04.23 22:20:06 3: Can't open /dev/ttyUSB0: Permission denied
</pre>

Das Device sollte für die Gruppe dialout Lese-/Schreibberechtigungen haben.
Ist dieses nicht der Fall, lassen sich diese über diesen Befehlt setzen.
<pre>
sudo chown root:dialout ttyUSBx
</pre>
Damit wird der "Besitz" festgelegt.
<pre>
sudo chmod a+rw /dev/ttyUSBx
</pre>
Hiermit werden die Berechtigungen gesetzt.

Der Benutzer "fhem" sollte selbstverständlich der Gruppe "dialout" angehören.
Ist dieses nicht der Fall:
<pre>
sudo adduser fhem dialout
</pre>

Falls dem nicht so sein sollte, hilft ggf. einer dieser beiden Links weiter:
[[https://www.youtube.com/watch?v=UOECwHhCWRg]] [[http://www.element14.com/community/community/designcenter/single-board-computers/next-gen_beaglebone/blog/2013/07/15/bbb--usb-io-with-ftdi-ft2232h]] bzw. die Installation des Moduls.

==== IDE unter MacOS ====

Da für den RGB-Sketch die IDE 1.0.x benötigt wird und diese Java SE 6 eine Voraussetzung ist, stellt die IDE und MacOS keine Optimale Konfigurationsumgebung dar. Wer es trotzdem probieren möchte
{{Link2Forum|Topic=12487 |Message=82055 }}
[http://forum.fhem.de/index.php/topic,12487.msg82055.html#msg82055]

==== INO ====
Der RGB-Sketches wurde mit Hilfe des Tools INO entwickelt.
{{Link2Forum|Topic=12487 |Message=82139 }}
[http://forum.fhem.de/index.php/topic,12487.msg82139.html#msg82139]

Die Installation erfolgt am leichtesten mit Hilfe des Tools pip.

Voraussetzungen für das Tool sind darüber hinaus picocom für die Kommunikation mit der seriellen Schnittstelle und die arduino. Im gleichen Zuge lässt sich pip installieren.
Die benötigten Pakete werden über folgenden Aufruf installiert
<pre>
sudo apt-get install picocom python-pip arduino
</pre>

Die Installation erfolgt im Anschluss über
<pre>
sudo pip install ino
</pre>

Die für einen Sketch erforderlichen libs werden in den entsprechenden lib Ordner kopiert (dort in entsprechenden Unterordnern).

Die Pfade im Zip sind an dieses Tool angepasst.
{{Link2Forum|Topic=12487 |Message=94830 }}
[http://forum.fhem.de/index.php/topic,12487.msg94830.html#msg94830]

Der serielle Port in der ino.ini muss selbstverständlich an die passende dev-Schnittstelle angepasst werden.

Als letztes sind die Parameter für das Board noch in die board.txt unter /usr/share/arduino/hardware/arduino einzutragen. Die Parameter lassen sich von hier extrahieren [http://old.panstamp.com/downloads] bzw. lauten für den AVR
<pre>
##############################################################

panstamp.name=PanStamp v2.0 (3.3V, 8 MHz) w/ ATmega328

panstamp.upload.protocol=arduino
panstamp.upload.maximum_size=30720
panstamp.upload.speed=57600

panstamp.bootloader.low_fuses=0xE2
panstamp.bootloader.high_fuses=0xD8
panstamp.bootloader.extended_fuses=0x07
panstamp.bootloader.path=atmega
panstamp.bootloader.file=ATmegaBOOT_168_atmega328_pro_8MHz.hex
panstamp.bootloader.unlock_bits=0x3F
panstamp.bootloader.lock_bits=0x0F

panstamp.build.mcu=atmega328p
panstamp.build.f_cpu=8000000L
panstamp.build.core=arduino
panstamp.build.variant=standard

##############################################################
</pre>

Wichtig zu wissen: Jedes Mal, wenn die Arduino ein Update erhält, wird vermutlich diese Datei überschrieben, so dass die Eintragung wiederholt werden muss.

Hier sind die grundlegendsten Befehle beschrieben [http://inotool.org/quickstart].

Wechselt man nun in das Verzeichnis z.B. des RGBdriver, lässt die der Sketch kompilieren über
<pre>
ino build
</pre>

Und hochladen über
<pre>
sudo ino upload
</pre>

; Troubeshooting
{{Link2Forum|Topic=12487 |Message=134786 }}
[http://forum.fhem.de/index.php/topic,12487.msg134786.html#msg134786]

=== over-the-air (derzeit) nur NRG ===

Die neueren panStamp NRGs können seit einiger Zeit auch over-the-air geflasht werden, wie hier im zugehörigen Forumthread beschrieben [[http://forum.fhem.de/index.php/topic,30589.0.html]].

=== Was überlebt das Flaschen ===
Bestimmte Konfigurationen überstehen das Flashen, dieses sind zumindest Adresse und Intervall, die nicht neu gesetzt werden müssen [http://forum.fhem.de/index.php/topic,12487.msg87560.html#msg87560].

=== EEPROM löschen ===

Das EEPROM lässt sich komplett löschen, indem man in der setup() dieses hier einträgt [http://forum.fhem.de/index.php/topic,13890.msg156868.html#msg156868].
<pre>
eepromToFactoryDefaults()
</pre>
</strike>

In Artikel <nowiki>[[Programmierung eines panStamp]]</nowiki> übernommen. --[[Benutzer:TeeVau|TeeVau]] ([[Benutzer Diskussion:TeeVau|Diskussion]]) 11:36, 17. Jul. 2015 (CEST)

== Integration in FHEM ==
=== FHEM Voraussetzungen ===
<strike>
Für den Betrieb ist XML:Simple notwendig, dass bei Bedarf folgendermaßen nachinstalliert werden kann [http://forum.fhem.de/index.php?topic=12487.msg87373#msg87373].
<pre>
sudo apt-get install libxml-simple-perl
</pre>

Diese Abhängigkeit kann beim Betrieb auf einer Fritzbox ebenfalls zu Problemen führen.
</strike> Zugefügt zu Artikel [[SWAP]] --[[Benutzer:TeeVau|TeeVau]] ([[Benutzer Diskussion:TeeVau|Diskussion]]) 10:51, 17. Jul. 2015 (CEST)

==== Pfade innerhalb der FHEM Installation ====

Die Module befinden sich wie gewohnt im Installationsverzeichnis unter ./FHEM.
<strike>
Das entsprechende Device Description File liegt unter ./FHEM/lib/SWAP wie hier beschrieben [http://forum.fhem.de/index.php/topic,12487.msg86257.html#msg86257].

</strike> In [[SWAP]]. --[[Benutzer:TeeVau|TeeVau]] ([[Benutzer Diskussion:TeeVau|Diskussion]]) 23:59, 18. Jul. 2015 (CEST)

=== Register ===
<strike>
Jeder panStamp stellt elf Systemregister (00-0A) [http://code.google.com/p/panstamp/wiki/SWAPregisters] und beliebig viele sketchabängige Userregister (0B-)bereit. Die Beschreibung der jeweils von einem Sketch bereitgestellten Userregister erfolgt in ''Device Description Files''. Die Identifikation der Art eines panStamp und die Zuordnung zu einem bestimmten Device Description File erfolgt über den productCode der aus ''Hersteller''- und ''Produkt-Id'' gebildet wird.

In den Systemregistern steht z. B. der productCode, die Deviceadresse und das Übertragungsintervall. Konfigurierbare Register werden im EEPROM gesichert, so dass die Werte auch bei einem Neustart nicht verlorengehen. Beim ersten Starten eines panStamp ist das EEPROM mit FF initialisiert und alle konfigurierbaren Register haben diesen Wert, also z. B. die Adresse FF und das Intervall FFFF (zwischen 18 und 19 Stunden).

Die Systemregister werden in der Device Detailansicht bei den InternalValues im oberen Bereich angezeigt und die User-Register als reading im unteren Bereich.

Jeder panStamp durchläuft beim Start eine definierte Einschaltsequenz und überträgt als erstes seinen productCode. Batteriebetriebene panStamps warten anschließend drei Sekunden auf Konfigurationskommandos. Danach werden bestimmte Systemregister und aktuelle Messwerte gesendet.

</strike> In [[SWAP]]. --[[Benutzer:TeeVau|TeeVau]] ([[Benutzer Diskussion:TeeVau|Diskussion]]) 23:59, 18. Jul. 2015 (CEST)

=== Verwendung innerhalb FHEM ===
{{Randnotiz|RNText=In Artikel [[panStamp]] <nowiki>[[panStick]]</nowiki>}}
<strike>
Zu unterscheiden ist die Definition des "Panstick", wobei der panStamp, der als RF-Modem auf dem Panstick sitzt, gemeint ist. Dieser wird im Folgenden mit "Panstick" als Name des Device benannt . Der Type ist "panstamp".

Auf der anderen Seite gibt es die Definition der panStamps, die lokal auf den entsprechenden Boards stecken. Diese sind vom Type SWAP_<ProductCode>. Um die Verwirrung komplett zu machen, wird hier meistens vom "panStamps" gesprochen, obwohl es eigentlich SWAP-Devices sind. Für diese werden hier nur die allgemeinen Grundfunktionen beschrieben, die bei jedem SWAP-Device funktionieren. Die spezifischen Komandos und Attribute, die durch die 3. Modulebene in Abhängigkeit des Productcode zur Verfügung stehen, werden bei den spezifischen Anwendungen beschrieben.

</strike> In [[panStamp]]. --[[Benutzer:TeeVau|TeeVau]] ([[Benutzer Diskussion:TeeVau|Diskussion]]) 13:08, 19. Jul. 2015 (CEST)

==== Panstick ====
<strike>
===== Definition =====
Das Device "Panstick" wird derzeit (01.05.2015) nicht durch autocreate angelegt. Daher muss er manuell entsprechend folgendem Befehl angelegt werden:
<pre>
define panStick panStamp /dev/ttyUSBx@38400
</pre>

Die Schnittstelle muss entsprechend der Installation des Pansticks anzupassen werden. Für die Einrichtung des Pansticks innerhalb des OS siehe [[panStamp#unter Linux|Installation Panstick]]

Dieses panStamp Device versucht dann alle panStamps im Netz zu finden und per autocreate anzulegen, wenn dieses aktiv sind.

'''Betrieb an der FB'''
Spezialitäten zum Betrieb an einer Fritzbox sind hier [http://forum.fhem.de/index.php/topic,12487.msg87778.html#msg87778] und hier [http://forum.fhem.de/index.php/topic,12487.msg95914.html#msg95914] beschrieben. Es scheint nur der hintere USB-Anschluss für die Verwendung zu laufen. Außerdem muss der USB-Fernaschluss deaktiviert sein.

===== Attribute =====

Für den "Panstick" gibt es keine modulspezifischen Attribute.

===== Set =====

* discover?
Mit diesem Befehl wird eine Broadcast SWAP-Message abgesetzt, die alle empfangenden panStamps dazu veranlassen, sich zu melden. Batteriebetriebenen panStamps können systembedingt nur identifiziert werden, wenn diese Empfangsbereit sind und sich nicht im Schlafmodus befinden.

* raw
Ist der Panstick ersteinmal eingerichtet und meldet "Initialized", kann über das panStick device direkt eine raw Message abgesetzt werden. Diese ist zur Zeit eigentlich immer eine SWAP Nachricht wie z.b.
<pre>
set panStick raw 00010000010000
</pre>
In diesem Beispiel wird ein broadcast an alle abgesetzt, damit diese ihre ID und ihren productcode zurück senden.
Das macht der panStick nach dem Initialisieren auch ein mal automatisch um alle nicht schlafenden Devices per autocreate anlegen zu können.

Mit diesem Befehl "raw" lassen sich SWAP-Messages direkt absetzten, was vor allen Dingen dann hilfreich sein kann, wenn man vermutet, dass die Kommunikation über die modulgestützten Befehle fehlschlägt.

</strike> Inhalt in Artikel [[panStamp]] übernommen. --[[Benutzer:TeeVau|TeeVau]] ([[Benutzer Diskussion:TeeVau|Diskussion]]) 20:05, 17. Jul. 2015 (CEST)

==== SWAP ====

Alle empfangen SWAP Nachrichten werden in internals/readings im jeweiligen Device angezeigt.

===== Definition =====
<strike>
'''Info: Das SWAP Modul unterstützt autocreate. Bei der Inbetriebnahme sollte autocreate aktiviert sein, da dies die Einrichtung deutlich vereinfacht.'''

Wenn der panStick läuft, sollten die SWAP-Devices per autocreate angelegt werden, sobald sie das erste mal senden, z.B. nach dem Einschalten oder nach einem Reset.

Normalerweise werden beim autocreate alle Werte abgefragt und angezeigt. Das geht normalerweise ohne jedes Zutun.

Panstick rein -> broadcast -> discovery -> anlegen.

Bei Devices mit power down mode erfolgt dieses das erste mal wenn sie Strom haben.

Alle panStamps durchlaufen beim Starten eine bestimmte Einschaltsequenz. Sie melden sich mit ihrer ID und ihrem productcode. Die ID ist die device Addresse und bei einem frisch geflashten panStamp in der Regel FF. Das SWAP Modul versucht, ein Device mit der Default Adresse <code>FF</code> automatisch auf die erste freie Adresse im Bereich <code>F0</code>-<code>FE</code> zu ändern.

Neue panStamps sollten nur Einer nach dem Anderen in Betrieb genommen werden, sonst haben mehrere die gleiche Addresse und das gibt Konflikte.

Wer mehrere devices hat, sollte jedem nach dem Anlegen mit
<pre>
set <device> regSet 09 <device adresse als 2 stellige hex zahl>
</pre>
eine eigene id zuweisen. Die landen auf dem panStamp im EEPROM und sind auch nach Neustart noch vorhanden.

Die anderen Adressen sind wie folgt belegt:
* 00 ist die Broadcast-ID
* 01 ist die ID des Pansticks am FHEM-System
* FF ist die Default ID, die jeder panStamp im Auslieferungszustand besitzt
* F0-FE sind die IDs, auf die autocreate die Adresse automatisch ändert, wenn ein neuer mit der ID FF erkannt wird und kein entsprechender Device-Name definiert ist.

{{Link2Forum|Topic= 12487 |Message=87261 }}
[http://forum.fhem.de/index.php?topic=12487.msg87261#msg87261]

Ändert man die Adresse, dauert es einen Augenblick, bis alle Register neu übertragen worden sind.

Autocreate ändert bei der Einrichtung und Änderung der ID auch automatisch den Namen. Belässt man die ID im Bereich F0-FE und ändert den Namen des Device, ist zu berücksichtigen, dass autocreate für neue Devices eine freie neue Adresse anhand der Device-Namen sucht. Dadurch könnte es zu Doppeltverwendung von IDs kommen.

Alternativ zum autocreate kann man ein Device auch von Hand anlegen mit
<pre>
define <device> SWAP <ID>
</pre>
Bis allerdings der Productcode nicht per Attribut hinterlegt ist, was bei autocreate ebenfalls automatisch geschied, funktionieren nur die grundlegenden Funktionen bis zur 2. Modulebene.
</strike>

Zugefügt zu Artikel [[SWAP]] --[[Benutzer:TeeVau|TeeVau]] ([[Benutzer Diskussion:TeeVau|Diskussion]]) 10:51, 17. Jul. 2015 (CEST)

===== set =====
''ZUGEFÜGT ZU SWAP ARTIKEL, STRIKE FUNKTIONIERT ABER IN DIESEM ABSATZ NICHT''
Ist ein SWAP-Device definiert, stehen folgende set-Befehle zur Verfügung:
* regGet <reg>
Fragt den Wert des Registers mit der id <reg> ab. Für die Systemregister kann hierzu statt der RegisterID auch der Registername (siehe regListAll) verwendet werden.
{{Link2Forum|Topic= 12487 |Message=87679 }}
[http://forum.fhem.de/index.php/topic,12487.msg87679.html#msg87679]

* regSet <reg> <data>
Schreibt <data> in den Register mit der id <reg>. Für die Systemregister kann hierzu statt der RegisterID auch der Registername (siehe regListAll) verwendet werden.

* regSet <reg>.<ep> <data>
write <data> to endpoint <ep> of register <reg>. will not work if no reading for register <reg> is available as all nibbles that are not part of endpoint <ep> will be filled from this reading. ?

* statusRequest
Veranlasst, dass alle Register und deren Werte einmal übertragen werden.

* readDeviceXML
Liest das Device-Description-XML-File neu ein.

* clearUnconfirmed
Löscht die liste der unbestätigten Nachrichten.

* flash [<productCode>|<firmwareFile>]
Initiiert das „over-the-air“ Firmware update, dass (derzeit) nur von NRG panStamps unterstützt wird.
* ohne Parameter: Verwendet das SWAP_<current productCode>.hex-File aus dem Verzeichnis ./FHEM/firmware.
* <productCode>: Verwendet das SWAP_<productCode>.hex-File aus dem Verzeichnis ./FHEM/firmware.
* <firmwareFile>: Verwendet ein <firmwareFile> als absoluten File-Namen des HEX-Files.

Zugefügt zu Artikel [[SWAP]] --[[Benutzer:TeeVau|TeeVau]] ([[Benutzer Diskussion:TeeVau|Diskussion]]) 10:51, 17. Jul. 2015 (CEST)

===== get =====
<strike>
* regList
Listet alle User-Register des SWAP-Device (Readings).

* regListAll
Listet alle Register des SWAP-Device (Internals und Readings).

* listUnconfirmed
Listet alle unbestätigten Nachrichten in der Warteschlange.

* products
Gibt alle auf dem System bekannten Productcodes nebst Daten aus.

* deviceXML
Gibt die Daten des zum derzeit zum per Attribut (Productcode) eingerichteten Device-XML-Files aus.
</strike>

Zugefügt zu Artikel [[SWAP]] --[[Benutzer:TeeVau|TeeVau]] ([[Benutzer Diskussion:TeeVau|Diskussion]]) 10:51, 17. Jul. 2015 (CEST)

===== Attribute =====
<strike>
Wird der Productcode bei der Definition nicht gesetzt, stehen auch nur die Standardbefehle bei zur 2. Modulebene zur Verfügung.

* createUnknownReadings
Erzeug Readings auch für Register, die im Device-XML-File nicht definiert werden.

* ProductCode
Legt den ProductCode eines SWAP-Device fest. Dieses Attribut wird dazu benutzt, die Konfiguration vom Device-XML-File festzulegen.
Erst wenn der Produktcode als Attribut vorgegeben wurde, z.B. für einen RGB-Sktech:
attr <device> ProductCode 0000002200000003
kommen zu den allgemeinen Kommandos die spezifischen der nächst höheren Modulebene 35_SWAP_<productcode>.pm mit hinzu. Dann werden die SWAP-Nachrichten an das entsprechende Modul weitergegeben und dort verarbeitet.

Für batteriebetriebene Devices, die während der Definition nicht aktiv sind, muss dieses Attribut manuell angelegt werden.
</strike>

Zugefügt zu Artikel [[SWAP]] --[[Benutzer:TeeVau|TeeVau]] ([[Benutzer Diskussion:TeeVau|Diskussion]]) 10:51, 17. Jul. 2015 (CEST)

==== SWAP_<ProductCode> ====
{{Randnotiz|RNText=In Artikel [[SWAP]]}}
<strike>
Ist bei einem SWAP-Device das Attribut Productcode gesetzt, wird die SWAP-Nachricht an das entsprechende Modul der 3. Ebene weitergegeben und dort verarbeitet. Die spezifischen Kommandos und Attribute sind bei den entsprechenden [[panStamp#Explizite Anwendungen|Anwendungen]] näher beschrieben.
</strike>

Zugefügt zu Artikel [[SWAP]]. --[[Benutzer:TeeVau|TeeVau]] ([[Benutzer Diskussion:TeeVau|Diskussion]]) 23:59, 18. Jul. 2015 (CEST)

==== Intervall bei Sketch mit power down / batterie betriebene Panstamps ====
{{Randnotiz|RNText=In Artikel [[SWAP]]}}
<strike>
Devices mit power down mode durchlaufen beim Einschalten oder bei einem Reset eine 3 Sekunden Schleife und warten auf Kommandos, dann werden normaler Weise die Register mit den Sensorwerten gesendet und die normale Loop gestartet. power down devices gehen danach schlafen und wachen regelmässig auf um ihre Werte zu senden.
Alternativ zum Intervall kann man den Resetknopf drücken, wenn man sie nicht im Zugriff hat.

Nachrichten an ein Device im power-down-state werden gepuffert und dann an das Device geschickt, sobald dieses sich im SYNC status befindet. Dieses ist typischer Weise nach dem Startup z.B. nach einem Reset der Fall.

Bei batteriebetriebenen Sensoren sollte das Sendeintervall auf einen sinnvollen Wert gesetzt werden:

<pre> set <device> regSet 0A <intervall in sekunden als 4 stellige hex zahl> </pre>
{{Link2Forum|Topic=12487 |Message=87409}}
[http://forum.fhem.de/index.php?topic=12487.msg87409#msg87409]

Für batteriebetriebene Devices (genauer: Devices die den Power-Down-Modus unterstützen) wird das Default Sendeintervall bei der Einrichtung automatisch von <code>FFFF</code> zu <code>0384</code> (900 Sekunden = 15 Minuten) geändert.

Das Intervall wird nur automatisch gesetzt, wenn pwrdownmode im device description file true ist.
{{Link2Forum|Topic=12487 |Message=89205}}
[http://forum.fhem.de/index.php/topic,12487.msg89205.html#msg89205]

{{Link2Forum|Topic=13890 |Message=157125}}
[http://forum.fhem.de/index.php?topic=13890.msg157125#msg157125]

Es gibt mit bestimmten panStamp lib Versionen das Problem das ein Wert von FFFF in 0A zum Überlauf führt und dann ununterbrochen gesendet wird. Im fhem Modul wird versucht das abzufangen. Das funktioniert auf manchen langsamen host systemen (z.B. FritzBox) nicht, weil der panStamp so schnell sendet, dass fhem so mit dem Abarbeiten beschäftigt ist, dass es selber nicht zum senden kommt.
Zur Abhilfe kann im sketch in setup() ganz am Anfang ein
EEPROM.write(EEPROM_TX_INTERVAL, 0x55);
EEPROM.write(EEPROM_TX_INTERVAL+1, 0x55);
eingefügt werden und noch mal flashen. Wenn der Sketch damit ein mal durchgelaufen ist können diese beiden Zeilen wieder entfernen und der panStamp noch mal geflasht.

Automatisch gesetzte Werte sollten danach manuell auf die jeweilige Installation angepasst werden.
{{Link2Forum|Topic=12487 |Message=87859}}
[http://forum.fhem.de/index.php/topic,12487.msg87859.html#msg87859]

Für Devices im Power-Down-Modus werden diese Kommandos in eine Warteschlange gestellt und übertragen, sobald das Device seine Initialisierungssequenz durchläuft. Hierzu ist nach Absetzen der Kommandos Reset zu drücken oder die Stromquelle erneut zu verbinden.

Die automatisch vergebenen Adressen sind im Bereich F0-FE. d.h. eigentlich auch nur temporär und sollten auf eine lokal passende geändert werden.
{{Link2Forum|Topic=12487 |Message=87919}}
[http://forum.fhem.de/index.php/topic,12487.msg87919.html#msg87919]

Im Log sollte etwas in dieser Art auftauchen:
<pre>
2013.07.29 20:14:29 3: SWAP Unknown device FF, please define it
2013.07.29 20:14:29 2: autocreate: define SWAP_F0 SWAP FF 000000010000000E
2013.07.29 20:14:29 3: SWAP_F0: I/O device is panStamp
2013.07.29 20:14:29 3: SWAP SWAP_F0: changing 09-DeviceAddress from default FF to F0
2013.07.29 20:14:30 3: SWAP SWAP_F0: changing 0A-PeriodicTxInterval from default FFFF to 0384 (900 seconds)

2013.07.29 20:16:35 3: SWAP Unknown device FF, please define it
2013.07.29 20:16:35 2: autocreate: define SWAP_F1 SWAP_0000002200000003 FF 0000002200000003
2013.07.29 20:16:35 3: SWAP_F1: I/O device is panStamp
2013.07.29 20:16:36 3: SWAP SWAP_F1: changing 09-DeviceAddress from default FF to F1
</pre>
Zugefügt zu Artikel [[SWAP]]. --[[Benutzer:TeeVau|TeeVau]] ([[Benutzer Diskussion:TeeVau|Diskussion]]) 23:59, 18. Jul. 2015 (CEST)
==== Verschlüsselung ====

Die Aktivierung der Verschlüsselung für die Kommunikation zwischen panStamp und panStick ist hier beschrieben, scheint allerdings derzeit noch nicht eingecheckt zu sein (Stand 01.05.2015).
{{Link2Forum|Topic=12487 |Message=133040}}
[http://forum.fhem.de/index.php/topic,12487.msg133040.html#msg133040]
{{Link2Forum|Topic=12487 |Message=139341}}
[http://forum.fhem.de/index.php/topic,12487.msg139341.html#msg139341]

=== Trouble Shooting ===
<strike>
==== value has to be 10 byte(s) in size ====

Es besteht die Möglichkeit, dass die Internals aus irgend einem Grund nicht vollständig sind.
Abhilfe in einem solchen Falle kann das Absetzen der folgenden beiden Befehlt schaffen
<pre>
set <device> statusRequest
set <device> readDeviceXML
</pre>

Wenn das nicht zum Erfolg führt, hilft ggf. ein Löschen und neu setzen des ProductCode Attributs.
{{Link2Forum|Topic=34474.0}}
[http://forum.fhem.de/index.php?topic=34474.0]

Das Übertragen aller Daten nach dem Statusrequest kann einen Augenblick dauern.

Eine weitere Möglichkeit:
Die Fehlermeldung kommt immer wenn FHEM nicht weiss welche Firmware auf dem device ist. Das passiert wenn irgendetwas in der Kommunikation schief geht während FHEM initialisiert.
{{Link2Forum|Topic=13890 |Message=122414}}
[http://forum.fhem.de/index.php/topic,13890.msg122414.html#msg122414]

==== register 0F is not known ====

{{Link2Forum|Topic=12487 |Message=84257}}
[http://forum.fhem.de/index.php/topic,12487.msg84257.html#msg84257]

==== Komplette Übersicht eines Device ====

<pre>
list <device>
</pre>
{{Link2Forum|Topic=13890 |Message=201467}}
[http://forum.fhem.de/index.php?topic=13890.msg201467#msg201467]

==== fehlender oder falsche Productcode ====

Fehlt der Productcode, werden die zum Sketch zugehörigen Befehle nicht angezeigt und die Register nicht korrekt zugeordnet.
Verändert man den Productcode, sollte man im Anschluss folgenden Befehlt absetzten, um alle Register neu auszulesen
<pre>
set <device> statusRequest
</pre>

{{Link2Forum|Topic=13890 |Message=201910}}
[http://forum.fhem.de/index.php?topic=13890.msg201910#msg201910]

==== missing commands und register 00-0A unvollständig ====

Wenn in den Internals missing commands (SWAP_Sent_unconfirmed) auftauchen und ggf. die Register 00-0A nicht vollständig sind und das Internal "channels" nicht vorhanden ist, gibt es irgendein Kommunikationsproblem.

{{Link2Forum|Topic=13890 |Message=201939}}
[http://forum.fhem.de/index.php?topic=13890.msg201939#msg201939]

==== Funktion des Autocreate ====

Beim autocreate wird versucht ein Name für das Device zu vergeben, der zur nächsten freien Adresse passt. Während dieses Prozessen bleibt die Adresse erst mal trozdem FF. Erst wenn das Device angelegt wird, kann versucht werden automatisch die Adresse zu setzen, hoffentlich auf die gleiche freie, die beim Namen auch schon gefunden wurde.

{{Link2Forum|Topic=12487 |Message=88110}}
[http://forum.fhem.de/index.php/topic,12487.msg88110.html#msg88110]

==== Adresse manuell setzen ====

Um die Adresse manuell bereits in den Sketch einzubauen kann man wie hier beschrieben vorgehen.
{{Link2Forum|Topic=13890 |Message=122347}}
[http://forum.fhem.de/index.php/topic,13890.msg122347.html#msg122347]

==== Panstamp antwortet nicht/EEprom to factory defaults ====

Wenn der panStamp nicht antwortet, kann es sein das die Adressen durcheinander gekommen sind. Dann musst man einmal in setup() ein eepromToFactoryDefaults() aufrufen und damit flashen. Wenn damit einmal gestartet wurde, die Zeile wieder entfernen und den normalen sketch flashen.

{{Link2Forum|Topic=13890 |Message=121677}}
[http://forum.fhem.de/index.php?topic=13890.msg121677#msg121677]

==== Undefined subroutine &main::XMLin ====
Erhält man diese Fehlermeldung
<pre>
Undefined subroutine &main::XMLin called at ./FHEM/34_SWAP.pm line 108.
</pre>
<pre>
2013.09.26 11:34:24 0: ERROR: Cannot autoload SWAP
2013.09.26 11:34:24 3: panStick: Unknown code 000A001B000A000000000100000007, help me!
</pre>

Es fehlt XML::Simple, was folgendermaßen installiert werden kann:
<pre>
sudo apt-get install libxml-simple-perl
</pre>

==== Factory Defaults ====

Um einen panStamp auf den Auslieferungszustand zurückzusetzen, muss man beim Sketch folgendes in die setup() Routine einfügen:
<pre>
eepromToFactoryDefaults()
</pre>
{{Link2Forum|Topic=13890 |Message=157125}}
[http://forum.fhem.de/index.php?topic=13890.msg157125#msg157125]

==== Status LED ====

Die Status LED auf dem Board wird in der config.h deaktiviert, indem man die Zeit #define LED_DEBUG mit "//" auskommentiert.
{{Link2Forum|Topic=13890 |Message=164731}}
[http://forum.fhem.de/index.php/topic,13890.msg164731.html#msg164731]

</strike> Inhalt in Artikel [[SWAP]] übernommen. --[[Benutzer:TeeVau|TeeVau]] ([[Benutzer Diskussion:TeeVau|Diskussion]]) 21:00, 17. Jul. 2015 (CEST)

== Explizite Anwendungen ==
=== RGB-Board ===
{{Randnotiz|RNText=In Artikel [[PanStamp_RGBWW_Board_mit_DMX_und_IR]]}}
==== Allgemeines ====
<strike>
Das Board unterstützt RGBW LEDs und lässt sich per Infrarot Fernbedienung, DMX Controller (z. B. als Unterputz Touchpanel) und FHEM bedienen.

Der Funktionsumfang wird in diesem [http://forum.fhem.de/index.php/topic,12487.msg81923.html#msg81923 Forenthread] vorgestellt. Die Hardware für das Board wird [http://forum.fhem.de/index.php/topic,13890.0.html hier] im FHEM Forum vorgestellt und ein Prototyp ist [http://forum.fhem.de/index.php/topic,12487.msg85777.html#msg85777 hier] zu sehen.

Die Projektseite zur Hardware findet sich [http://itse.homeip.net/projekte/12/6/ hier]. Eine Version 2 des Boards in geplant.

Eine Übersicht über die derzeit vorhandene Funktionalität (stand 01.05.2015):
{{Link2Forum|Topic=13890 |Message=1205404}}
[http://forum.fhem.de/index.php?topic=13890.msg120404#msg120404]

* bis zu vier LED-Kanäle (je nach Kombination von ir und soft pwm)
* ir senden
* ir empfangen
* Messen ob die LED-Versorgung an ist.
* Helligkeit eines an A2 angeschlossenen Helligkeitssensors
* Konfiguration der DMX-Basis-Adresse über das SWAP Register 0x12
* optional soft on auf letzten Wert
* Alles was auch vorher schon ging: dimmen, faden, IR-Fernbedienungen anlernen, ...

Wichtig zu wissen:
* Wenn IR aktiv ist und kein soft pwm lässt sich der 4. Kanal nur ein- und ausschalten.
* Wenn IR aktiv ist muss soft pwm aktiv sein um den 4. Kanal auch zu dimmen.
* Es wird nur ein zusätzlicher Kanal tatsächlich schon unterstützt, der fünfte ist noch geplant.
* Bei IR-Senden sind nur die Aufrufe für Sony und NEC tatsächlich eingebaut. Die anderen sind aber einfach zu ergänzen.
* Beim IR-Senden sind noch keine Wiederholungen eingebaut. Die müssen laut Protokoll aber eigentlich sein.

was noch kommt:
* besseres soft pwm
* mehr Konfiguration bezüglich default-Verhalten. Ramp-Zeiten, Delays, ...
* HSV-Farb-Modell um besser zu faden und vor Allem um den Weiss-Anteil automatisch auf die Weiss-LEDs zu legen
* die virtuellen Channel
* FHEM kompatibles IR-Senden
* sofortiges senden von Helligkeit und LED-Spannung bei Änderung
* andere IR-Lib mit sehr viel besserer Geräte-Unterstützung

Wie gehabt muss alles über config.h mit Compilerschaltern konfiguriert werden.
</strike>

Inhalt in Artikel [[PanStamp_RGBWW_Board_mit_DMX_und_IR]] übernommen. --[[Benutzer:TeeVau|TeeVau]] ([[Benutzer Diskussion:TeeVau|Diskussion]]) 23:54, 17. Jul. 2015 (CEST)
===== weitrere Screenshots =====
<strike>
<gallery>
File:SWAP_0000002200000003-internal.png|InternalValues
File:SWAP_0000002200000003-readings.png|Readings
File:SWAP_0000002200000003-attributes.png|Attributes
</gallery>
</strike>

Inhalt in Artikel [[SWAP_0000002200000003]] übernommen. --[[Benutzer:TeeVau|TeeVau]] ([[Benutzer Diskussion:TeeVau|Diskussion]]) 23:54, 17. Jul. 2015 (CEST)

===== original RGB-Sketch (von panstamp.com) =====
<strike>
Der originale Sketch von der panStamp.com-Seite und das generelle FHEM-Modul verstehen von Haus aus nur die regSet und regGet Kommandos. Wenn man den colorpicker verwenden möchte, geht das nur per readingsProxy.

Das einfachste ist es den Sketch und das FHEM-Modul für das RGB-Board zu verwenden. Dann hat man neben dem colorpicker, einem farbigen State-Icon auch alle Möglichen Kommandos wie on, off, on-for-timer, dimup, ... und kann konfigurieren, wie das Board nach dem Hart- oder Soft-Einschalten reagieren soll.

Derzeit scheint es keinen Grund zu geben, den original Sketch zu verwenden.
{{Link2Forum|Topic=12487 |Message=220463}}
[http://forum.fhem.de/index.php/topic,12487.msg220463.html#msg220463]

Falls jemand trotzdem den normalen RGB-Sketch verwendet:
* Im Code alle drei 0000002200000003 durch 0000000100000003 ersetzen.
Dann geht on/off/toggle/set rgb RRGGBB und auch der colorpicker, wenn das HUEDevice Modul auch geladen ist.

</strike> Inhalt in Artikel [[SWAP_0000002200000003#Anwendungsbeispiele]] übernommen. --[[Benutzer:TeeVau|TeeVau]] ([[Benutzer Diskussion:TeeVau|Diskussion]]) 13:58, 28. Jul. 2015 (CEST)

==== Sketch vorbereiten, kompilieren und hochladen ====
===== Vorbereitungen =====
<strike>
(Stand 01.05.2015)

Mit der Arduino IDE 1.5.x gab es gundlegende Umstellungen, für die der derzeitige Sketch [r4716] vermutlich angepasst werden müsste.

Für den RGB-Driver sketch sind je nach gewünschtem Funktionsumfang noch folgende libs zu installieren:

* Die Dateien der '''Panstamp Lib''' läd man von hier [[http://old.panstamp.com/downloads]] (panstamp_library.zip, 129k v.25, May 31, 2013). Mit der neueren Lib v.4 läuft die Kompillierung des derzeitigen Sketches nicht durch. Die Dateien der Lib speichert man in einem entsprechend neuen Unterordner, z.B. hierin C:\Users\<username>\Documents\Arduino\libraries. Am Ende der ganzen Aktion im Folgenden sollten sich in diesem Unterordner 3 neue Unterordner befinden: IRremote, DMXSerial und panstamp

* Die Dateien der '''IR Remote Lib''' kopiert man von hier [[https://github.com/shirriff/Arduino-IRremote]] und speichert sie ebenfalls in einem passenden Unterordner von libraries.

* Die Dateien der '''DMX Lib''' kopiert man von hier [[http://www.mathertel.de/Arduino/DMXSerial.aspx]] und speichert sie ein weiteres Mal in einem weiteren Unterordner von libraries. Weitere Informationen zur Verwendung von Arduino Libraties finden sich hier [[http://arduino.cc/en/Hacking/Libraries]]. Dass die Libraries richtig erkannt worden sind, lässt sich dadurch erkennen, dass unter Sketch/Library importieren die 3 weiteren Punkte unten unter "beigetragen" auftauchen.

Die Librarys sollten entweder mit dem entsprechenden Menüpunkt in die IDE integriert werden oder jeweils nach auspacken des zip files als als kompletten Ordner im Arduino libraries Verzeichnis abgelegt werden (siehe [http://www.arduino.cc/en/Hacking/Libraries)]).

Für das kompilieren mit INO siehe [[panStamp#ino|hier]].

===== Link zum sketch =====
Die aktuelle Version des RGB-Driver Sketches findet sich auf [http://sourceforge.net/p/fhem/code/HEAD/tree/trunk/fhem/contrib/arduino/ sourceforge].
{{Link2Forum|Topic=13890 |Message=201391}}
[http://forum.fhem.de/index.php?topic=13890.msg201391#msg201391]

===== Kompillierte hex version =====
Eine kompiliertes HEX-File für drei (vier) Kanäle plus IR-Empfang und DMX ist hier im Forum zu finden:
{{Link2Forum|Topic=13890 |Message=121619}}
[http://forum.fhem.de/index.php?topic=13890.msg121619#msg121619]

===== HEX-File ohne IR und DMX =====
Eine kompiliertes HEX-File ohne IR-Empfang und DMX ist hier im Forum zu finden:
{{Link2Forum|Topic=13890 |Message=201955}}
[http://forum.fhem.de/index.php?topic=13890.msg201955#msg201955]

===== Sketch anpassen, kompilieren und hochladen =====

* Welche Features der sketch bietet lässt sich im config.h file durch ein- oder auskommentieren der #define ENABLE_... Zeilen festlegen. {{Link2Forum|Topic=13890 |Message=173431}} [http://forum.fhem.de/index.php?topic=13890.msg173431#msg173431] Den Sketch entsprechend den Bedürfnissen in den config.h die nicht benötigten Zeilen mit "//" auskommentieren bzw. anpassen. Für die Konfigurationen siehe [[panStamp#Sketch konfigurieren|Sketch konfigurieren]].
* Windows IDE only: Falls alles so bleibt, wie es heruntergeladen wurde, wechselt man wieder auf den Reiter sketch und importiert über ->Sketch Library importieren die entsprechenden Libs für IRremote und DMX. Dadurch werden 3 neue Zeilen hinzugefügt.
* Nun sollte über Sketch/Überprüften/Kompillieren die Erstellung des Sketches möglich sein.
* Falls erfolgreich unter Datei/Hochladen (ohne Programmer) den Sketch auf den Panstamp laden.

==== Sketch konfigurieren ====

===== DMX =====
<pre>
#define ENABLE_DMX
</pre>

Hierbei ist darauf zu achten, dass in der DMX-Lib in der Datei DMXSerial.h die Zeile

<pre>
#define DmxModePin 2 // Arduino pin 2 for controlling the data direction
</pre>

in

<pre>
#define DmxModePin 7 // Arduino pin 7 for controlling the data direction
</pre>

abgeändert werden muss.

===== Temperatur- und Luftfeuchtigkeitssensor =====

<pre>
#define HAS_SENSOR
</pre>

Dieses ermöglicht die Nutzung eines DHT22 Sensors zur Auswerung von Temperatur und Luftfeuchtigkeit.

Dafür sollten diese Konfigurationszeilen auskommentiert sein
<pre>
USE_SOFT_PWM;
ENABLE_IR_SEND;
ENABLE_REPEATER;
</pre>

In der IRremote.cpp Datei in der Irremote Library muss die Zeile
<pre>
void IRrecv::disableIRIn()
{
TIMER_DISABLE_INTR;
}
</pre>
sowie die Irremote.h Datei unter Public: um die Zeile
<pre>
void disableIRIn();
</pre>
erweitert werden.

Der Daten-Pin des DHT22 Sensors muss hierfür an A2 des panStamps angeschlossen werden.

Ein Beispiel für die Umrechnung der Userreading für Spannung Temp etc. ist hier beschrieben.
{{Link2Forum|Topic=12487 |Message=76489}}
[http://forum.fhem.de/index.php?topic=12487.msg76489#msg76489]

===== Zusammenhänge der Konfiguration =====

Die Zusammenhänge der Konfiguration sind hier beschrieben
{{Link2Forum|Topic=13890 |Message=175181}}
[http://forum.fhem.de/index.php?topic=13890.msg175181#msg175181]
</strike>

Inhalt in Artikel [[PanStamp RGBWW Board mit DMX und IR]] übernommen. --[[Benutzer:TeeVau|TeeVau]] ([[Benutzer Diskussion:TeeVau|Diskussion]]) 23:54, 17. Jul. 2015 (CEST)

==== Bedienung in FHEMWEB ====

===== Komandos =====

====== Definition ======

Der Panstick wird entsprechend folgendem Befehlt angelegt:
<pre>
define panStick panStamp /dev/ttyUSBx@38400
</pre>

Die Schnittstelle ist entsprechend Installation des <nowiki>[[panstamp#unter Linux|Pansticks]]</nowiki> anzupassen.

Dieses panStamp Device versucht dann alle panStamps im Netz zu finden und per autocreate anzulegen, wenn dieses aktiv ist.

====== Attribute TBC ======

====== Set TBC ======

====== Get TBC ======
{{Randnotiz|RNText=In Artikel [[SWAP_0000002200000003]]}}
<strike>
http://forum.fhem.de/index.php?topic=12487.msg81923#msg81923

</strike> Inhalt in Artikel [[SWAP 0000002200000003]] übernommen. --[[Benutzer:TeeVau|TeeVau]] ([[Benutzer Diskussion:TeeVau|Diskussion]]) 14:25, 28. Jul. 2015 (CEST)

EIn register verändern
{{Randnotiz|RNText=In Artikel [[SWAP]]}}
<strike>
http://forum.fhem.de/index.php/topic,12487.msg87679.html#msg87679

</strike> In Artikel [[SWAP]] übernommen. --[[Benutzer:TeeVau|TeeVau]] ([[Benutzer Diskussion:TeeVau|Diskussion]]) 23:59, 18. Jul. 2015 (CEST)

===== Register umrechnung dec zu hex TBC =====
{{Randnotiz|RNText=In Artikel [[SWAP]]}}
<strike>
http://forum.fhem.de/index.php/topic,13890.msg162790.html#msg162790

</strike> In Artikel [[SWAP]] übernommen. --[[Benutzer:TeeVau|TeeVau]] ([[Benutzer Diskussion:TeeVau|Diskussion]]) 23:59, 18. Jul. 2015 (CEST)

===== Poweronstate TBC =====
{{Randnotiz|RNText=In Artikel [[SWAP_0000002200000003]]}}
<strike>
http://forum.fhem.de/index.php/topic,12487.msg88054.html#msg88054
http://forum.fhem.de/index.php/topic,12487.msg95574.html#msg95574
http://forum.fhem.de/index.php/topic,13890.msg124456.html#msg124456

</strike> Inhalt in Artikel [[SWAP 0000002200000003]] übernommen. --[[Benutzer:TeeVau|TeeVau]] ([[Benutzer Diskussion:TeeVau|Diskussion]]) 14:25, 28. Jul. 2015 (CEST)

===== Aus nach poweron TBC =====
{{Randnotiz|RNText=In Artikel [[SWAP_0000002200000003]]}}
<strike>
http://forum.fhem.de/index.php?topic=13890.msg121296#msg121296
Power on register
http://forum.fhem.de/index.php?topic=13890.msg121137#msg121137

</strike> Inhalt in Artikel [[SWAP 0000002200000003]] übernommen. --[[Benutzer:TeeVau|TeeVau]] ([[Benutzer Diskussion:TeeVau|Diskussion]]) 14:25, 28. Jul. 2015 (CEST)

===== listunconfirmed TBC =====
{{Randnotiz|RNText=In Artikel [[SWAP]]}}
<strike>
http://forum.fhem.de/index.php/topic,12487.msg88112.html#msg88112

</strike> In Artikel [[SWAP]] übernommen. --[[Benutzer:TeeVau|TeeVau]] ([[Benutzer Diskussion:TeeVau|Diskussion]]) 23:59, 18. Jul. 2015 (CEST)

===== Fadeto TBC =====
{{Randnotiz|RNText=In Artikel [[SWAP_0000002200000003]]}}
<strike>
http://forum.fhem.de/index.php/topic,12487.msg97406.html#msg97406

</strike> Inhalt in Artikel [[SWAP 0000002200000003]] übernommen. --[[Benutzer:TeeVau|TeeVau]] ([[Benutzer Diskussion:TeeVau|Diskussion]]) 14:25, 28. Jul. 2015 (CEST)

{{Randnotiz|RNText=In Artikel [[SWAP_0000002200000003]]}}
<strike>
Default fade time
http://forum.fhem.de/index.php?topic=13890.msg121572#msg121572

</strike> Inhalt in Artikel [[SWAP 0000002200000003]] übernommen. --[[Benutzer:TeeVau|TeeVau]] ([[Benutzer Diskussion:TeeVau|Diskussion]]) 14:25, 28. Jul. 2015 (CEST)

===== Eigenschaften des fade TBC =====
{{Randnotiz|RNText=In Artikel [[PanStamp_RGBWW_Board_mit_DMX_und_IR]]}}
<strike>
http://forum.fhem.de/index.php?topic=13890.msg106644#msg106644
</strike>

In Artikel übernommen. --[[Benutzer:TeeVau|TeeVau]] ([[Benutzer Diskussion:TeeVau|Diskussion]]) 23:54, 17. Jul. 2015 (CEST)

===== 4.,5. kanal TBC =====
{{Randnotiz|RNText=In Artikel [[PanStamp_RGBWW_Board_mit_DMX_und_IR]]}}
<strike>
http://forum.fhem.de/index.php?topic=13890.msg169741#msg169741
http://forum.fhem.de/index.php?topic=13890.msg192132#msg192132
http://forum.fhem.de/index.php?topic=13890.msg201922#msg201922
http://forum.fhem.de/index.php?topic=13890.msg201936#msg201936
</strike>

In Artikel übernommen. --[[Benutzer:TeeVau|TeeVau]] ([[Benutzer Diskussion:TeeVau|Diskussion]]) 23:54, 17. Jul. 2015 (CEST)

===== Extra kanäle TBC =====
{{Randnotiz|RNText=In Artikel [[SWAP_0000002200000003]]}}
<strike>
http://forum.fhem.de/index.php?topic=13890.msg173280#msg173280
http://forum.fhem.de/index.php?topic=13890.msg214329#msg214329
http://forum.fhem.de/index.php?topic=13890.msg214474#msg214474

</strike> Inhalt in Artikel [[SWAP 0000002200000003]] übernommen. --[[Benutzer:TeeVau|TeeVau]] ([[Benutzer Diskussion:TeeVau|Diskussion]]) 14:25, 28. Jul. 2015 (CEST)

==== IR Schnittstelle TBC ====
===== IR TBC =====
{{Randnotiz|RNText=In Artikel [[PanStamp_RGBWW_Board_mit_DMX_und_IR]]}}
<strike>
http://forum.fhem.de/index.php?topic=13890.msg107061#msg107061
http://forum.fhem.de/index.php?topic=13890.msg107197#msg107197
http://forum.fhem.de/index.php?topic=13890.msg107415#msg107415
http://forum.fhem.de/index.php/topic,13890.msg122021.html#msg122021
http://forum.fhem.de/index.php/topic,13890.msg122077.html#msg122077
http://forum.fhem.de/index.php?topic=13890.msg167351#msg167351
http://forum.fhem.de/index.php?topic=13890.msg175269#msg175269
http://forum.fhem.de/index.php?topic=13890.msg175285#msg175285
http://forum.fhem.de/index.php?topic=13890.msg182582#msg182582
http://forum.fhem.de/index.php?topic=13890.msg245597#msg245597
http://forum.fhem.de/index.php?topic=13890.msg259267#msg259267
</strike>

===== IR-Belegung Panstamp RGB-Board TBC =====
{{Randnotiz|RNText=In Artikel [[PanStamp_RGBWW_Board_mit_DMX_und_IR]]}}
<strike>
http://forum.fhem.de/index.php/topic,13890.msg163008.html#msg163008
http://forum.fhem.de/index.php/topic,13890.msg163153.html#msg163153
</strike>

===== Ircluster TBC =====
{{Randnotiz|RNText=In Artikel [[PanStamp_RGBWW_Board_mit_DMX_und_IR]]}}
<strike>
http://forum.fhem.de/index.php?topic=13890.msg175331#msg175331
</strike>

===== Irgate TBC =====
{{Randnotiz|RNText=In Artikel [[PanStamp_RGBWW_Board_mit_DMX_und_IR]]}}
<strike>
http://forum.fhem.de/index.php?topic=13890.msg175278#msg175278
</strike>

In Artikel übernommen. --[[Benutzer:TeeVau|TeeVau]] ([[Benutzer Diskussion:TeeVau|Diskussion]]) 23:54, 17. Jul. 2015 (CEST)

==== DMX Schnittstelle ====
{{Randnotiz|RNText=In Artikel [[PanStamp_RGBWW_Board_mit_DMX_und_IR]]}}
<strike>
Da die DMX-Schrittstelle kein direktes Interface zu FHEM hat, sondern nur die direkte Kommunikation zwischen DMX-Kontroller und RGB-Board betrifft, ist die Schnittstelle nur bei der Konfiguration des Sketches und über die Dokumentation des Boards beschrieben.
</strike>

In Artikel übernommen. --[[Benutzer:TeeVau|TeeVau]] ([[Benutzer Diskussion:TeeVau|Diskussion]]) 23:54, 17. Jul. 2015 (CEST)
==== sonstiges ====

===== Alternativer Fade per Patch =====
{{Randnotiz|RNText=In Artikel [[PanStamp_RGBWW_Board_mit_DMX_und_IR]]}}
<strike>
Als Alternative zum im Sketch und im Modul eingebauten Fade-Befehl ist hier ein Patch vorgestellt:
{{Link2Forum|Topic=12487 |Message=133096}}
[http://forum.fhem.de/index.php/topic,12487.msg133096.html#msg133096]

Der Patch ist '''nicht eingecheckt'''.
</strike>

In Artikel übernommen. --[[Benutzer:TeeVau|TeeVau]] ([[Benutzer Diskussion:TeeVau|Diskussion]]) 23:54, 17. Jul. 2015 (CEST)
===== Kompatibilität RBG-Board mit NRG-panStamps =====
{{Randnotiz|RNText=In Artikel [[PanStamp_RGBWW_Board_mit_DMX_und_IR]]}}
<strike>
Mit dem hier beschriebenen Sketch ist das Board nur mit den AVRs kompatibel.
Die Pinbelegung zwischen AVR und NRG ist im Prinzip gleich bis auf Pin 23. Das ist bei dem NRG ein IO Pin und nicht Ground wie beim AVR.
Das wäre kein Problem wenn man entweder hardwareseitig den Kontakt unterbricht oder aber programmiertechnisch diesen Pin '''NIE''' als Ausgang definiert. Ansonsten gibt’s ein „kurzen“. Oder wenn er als Ausgang definiert ist darf er nur das GND Potential haben, also Low, 0.

{{Link2Forum|Topic=13890 |Message=247069}}
[http://forum.fhem.de/index.php?topic=13890.msg247069#msg247069]

Da es derzeit (Stand 01.05.2015) aber keinen Sketch gibt, der auf den NRG lauffähig ist, wäre vorher noch diese Herausforderung zu lösen.
</strike>

In Artikel übernommen. --[[Benutzer:TeeVau|TeeVau]] ([[Benutzer Diskussion:TeeVau|Diskussion]]) 23:54, 17. Jul. 2015 (CEST)
=== Bodenfeuchtesensor ===
{{Randnotiz|RNText=In Artikel [[SWAP]]}}
<strike>
Der panStamp soilmoisture Sketch aus dem examples Verzeichnis ist mit dem Standard SWAP Modul kompatibel.

Ein Artikel über ein selbstentwickeltes PanStamp Batterieboard zum Anschluss von Analogsensoren/1Wire und Solarversorgung ist hier [[Bodenfeuchtesensor]] beschrieben.

Eine für einen Vegetronix sensor angepasste Version kann von [http://sourceforge.net/p/fhem/code/HEAD/tree/trunk/fhem/contrib/arduino/ sourceforge] heruntergeladen werden. Das Übertragungsintervall ist wie üblich über das regsiter 0A konfigurierbar. Der Sensor wird and GND, D7 für die Versorgungsspannung und A4 für den Messwert angeschlossen. Erfahrungen haben gezeigt, dass bei einem fünfminütigen Übertragungsintervall nach 12 Monaten Laufzeit die Batteriespannung von 1.55V auf 1.4V abfällt. Das würde bedeuten, dass eine Batterie im Batterieboard mindestens eine Laufzeit von drei Jahren haben sollte.

set <MyBodenfeuchte> stateFormat VWC_A%
set <MyBodenfeuchte> userReadings Level0_Voltage {hex(ReadingsVal($name,"0C.0-Moisture_level_0","0"))*(3.3/1024)},
VWC_A:0C.0-Moisture_level_0 {sprintf("%.0f",(11.6552 * (ReadingsVal($name,"Level0_Voltage","0"))**4 + 7.10835 *
(ReadingsVal($name,"Level0_Voltage","0"))**2 - 0.569557) / ((ReadingsVal($name,"Level0_Voltage","0"))**2 + 1))},
voltage:0B-Voltage {hex(ReadingsVal($name,"0B-Voltage","0"))*0.001},
battery:0B-Voltage {(ReadingsVal($name,"voltage","0")<1?"low":"ok")}

[[Datei:SWAP_ soilmositure-plot.jpg|mini|x100px|Bodenfeuchte]]
<div class="tright" style="clear:none">[[Datei:panstamp_vegetronix1.jpg|mini|ohne|x130px|Vegetronix Bodenfeuchtesensor an panStamp]]</div>
<div class="tright" style="clear:none">[[Datei:panstamp_vegetronix2.jpg|mini|ohne|x130px|Vegetronix Bodenfeuchtesensor an panStamp]]</div>

Mit einem entsprechend erweiterten Sketch lassen sich auch mehrere Sensoren an einem panStamp auslesen.

Die folgenden Bilder zeigen eine panStamp/Vegetronix Außeneinheit im IP65-Gehäuse. Dieser Aufbau wird ganzjährig den Witterungseinflüssen ausgesetzt. Die auf den Stab aufgesetzte Antenne muss nicht verwendet werden, bei kürzeren Funkstrecken ist eine innenliegende Drahtantenne ausreichend. Bitte in FHEM den RSSI- und LQI-Wert sowie die Gleichmäßigkeit des Empfangens der 5 Minuten Sendeintervalle dementsprechend beobachten.
</strike>

In Artikel [[SWAP] übernommen. --[[Benutzer:TeeVau|TeeVau]] ([[Benutzer Diskussion:TeeVau|Diskussion]]) 23:59, 18. Jul. 2015 (CEST)

=== Umweltsensor ===
<strike>
Die Weiterentwicklung des Bodenfeuchtesensors zum Umweltsensor ist hier [[PanStamp_Umweltsensor]] beschrieben.
</strike>

=== Ultraschall-Füllstandssensor ===

Projektidee

=== Repeater Mode ===

Die Repeaterfunktionalität ist derzeit (01.05.2015) noch nicht näher beschrieben, wird aber von den Modulen unterstützt.
{{Link2Forum|Topic=12487 |Message=118403}}
[http://forum.fhem.de/index.php/topic,12487.msg118403.html#msg118403]

== Weblinks ==
* [http://www.panstamp.com/home panStamp] panStamp Hersteller
* [http://itse.homeip.net/projekte/12/6/ Projektseite] für das RGB-Multi-Board.
* [http://sourceforge.net/p/fhem/code/HEAD/tree/trunk/fhem/contrib/arduino/ rgbdriver sketch] auf sourceforge
* [http://sourceforge.net/p/fhem/code/HEAD/tree/trunk/fhem/contrib/arduino/ soilmoisture sketch] auf sourceforge

SWAP

2016-06-12T15:19:55Z

Joshi04: Link zu panStick ersetzt

{{SEITENTITEL:SWAP}}

{{Infobox Modul
|ModPurpose=Modul zur generischen Ansteuerung sämtlicher panStamp Boards.
|ModType=d
|ModCmdRef=SWAP
|ModForumArea=
|ModFTopic=
|ModTechName=34_SWAP.pm
|ModOwner=André/ justme1968 ({{Link2FU|430|Forum}} / [[Benutzer Diskussion:Justme|Wiki]])
}}

[[SWAP]] ist das Basismodul für die Unterstützung der panStamp Baugruppen. Zur Kommunikation in einem panStamp Netzwerk dient das ''Simple Wireless Abstract Protocol'' ([https://github.com/panStamp/panstamp/wiki/Simple%20Wireless%20Abstract%20Protocol SWAP]).
Die komplette SWAP- Kommunikation ist registerbasiert und erfolgt mit Nachrichten um diese Register abzufragen, zu setzen und deren Inhalt zu senden. Alle Register lassen sich lesen, manche auch beschreiben. Für eine tiefgreifende FHEM Integration können weitere Module (wie z.B. [[SWAP_0000002200000003]]) vorhanden sein. Diese Module bauen, als 3. Ebene, auf das SWAP Modul (2. Ebene) auf und bedienen im backend ebenfalls die panStamp-Hardware über die Register. Der panStamp Software Stack unterstützt einen stromsparenden Power-Down- oder Sleep-Modus für batteriebetriebene Sensoren, aus dem diese dann nur zur eigentlichen Messung und Übertragung "aufwachen".

== Voraussetzungen ==
Für den Betrieb ist XML:Simple notwendig, dass bei Bedarf folgendermaßen nachinstalliert werden kann [http://forum.fhem.de/index.php?topic=12487.msg87373#msg87373].
sudo apt-get install libxml-simple-perl
Diese Abhängigkeit kann beim Betrieb auf einer Fritzbox ebenfalls zu Problemen führen. Das [[SWAP]] Modul greift auf das [[panStamp]] Modul zu, was vorher per <code>define</code> angelegt werden muss.

== Anwendung ==
[[Datei:SWAP_ 0000000100000005-detail.png|mini|hochkant=2.5|Readings]]
Bei SWAP geht alle Kommunikation über [https://github.com/panStamp/panstamp/wiki/Simple%20Wireless%20Abstract%20Protocol#registers-and-values '''Register'''], dies sind unterschiedlich lange Werte die entweder nur gelesen oder gelesen und geschrieben werden können.
Jeder panStamp stellt elf Systemregister (<code>00</code>-<code>0A</code>) [https://github.com/panStamp/panstamp/wiki/Standard-SWAP-registers] und beliebig viele, sketchabängige Userregister (<code>0B</code>-<code>xx</code>) [https://github.com/panStamp/panstamp/wiki/Standard-SWAP-registers#custom-registers] bereit. Die Beschreibung der jeweils von einem Sketch bereitgestellten Userregister erfolgt in ''Device Definition Files'', die in <code>.../FHEM/lib/SWAP</code> zu finden sind. Die Identifikation der Art eines panStamp und die Zuordnung zu einem bestimmten Device Definition File erfolgt über den ProductCode der aus ''Hersteller''- und ''Produkt''-ID [https://github.com/panStamp/panstamp/wiki/How-to-develop-your-own-SWAP-device#specify-your-product-code] gebildet wird. Damit dies funktioniert, muss das Attribut ProductCode korrekt gesetzt sein. Das geschieht normalerweise automatisch beim Anlegen des Device.
In den Systemregistern steht z.B. der ProductCode, die Device Adresse im SWAP Protokoll und das Übertragungsintervall. Konfigurierbare Register werden im EEPROM gesichert und die Werte gehen auch beim Neustart nicht verloren. Beim aller ersten Starten ist das EEPROM mit <code>FF</code> initialisiert und alle konfigurierbaren Register haben diesen Wert. Also z.B. Adresse <code>FF</code> und Intervall <code>FFFF</code> (HEX in Sekunden, das wären dann zwischen 18 und 19 Stunden).
Die Inhalte der Systemregister stehen als INTERNAL, im oberen Bereich der Detail Ansicht eines FHEM-Device, in FHEMWEB, die Userregister als Readings im unteren.

Jeder panStamp durchläuft beim Start eine definierte Einschaltsequenz und überträgt als erstes seinen ProductCode. Batteriebetriebene panStamps warten anschließend drei Sekunden auf Konfigurationskommandos. Danach werden bestimmte Systemregister und aktuelle Messwerte gesendet.

Alle low Level Dinge wie Register ID oder Register Wert können mit '''hex Werten'' direkt angepasst werden.
set <device> regSet 0A <intervall in Sekunden als 4 stellige hex zahl>
set <device> regSet 08 <Netzwerk ID als 2 stellige hex zahl>
{{Link2Forum|Topic=12487 |Message=87436 }}

Das [[SWAP]]-Modul stellt unter anderem folgende grundlegende Funktionalitäten zur Verfügung
* Es wird eine command Queue für panStamp-Hardware im power down Modus gehalten. Sobald die panStamp-Hardware online (SYNC Modus) kommt werden die Kommandos von FHEM automatisch übertragen.
* Die userReadings für 'menschenlesbare' Readings werden anhand des Device Definition Files automatisch erzeugt
* Es ist möglich direkt Endpoints (Teile eines Registers) zu schreiben
* (Fast) keine hardkodierte Sonderbehandlung mehr für das RGB-Board. Das SWAP Modul kann mit jedem beliebige Swap Device umgehen.
* Es gibt eine dritte (optionale) Modulebene neben dem [[panStamp]] FHEM-Modul (1. Ebene) für die Hardware und dem SWAP Modul (2. Ebene) für das Protokoll. Mit dem generellen SWAP Modul lasen sich alle SWAP Devices ''zu Fuß'' über die Register ansprechen. Um die Register auf einer höheren Ebene auf FHEM Kommandos wie on/off/on-for-timer zu mappen ist dann ein Modul der 3. Ebene notwendig. {{Link2Forum|Topic=12487 |Message=78502 }}

=== Define ===
'''Info: Das SWAP Modul unterstützt autocreate. Bei der Inbetriebnahme sollte autocreate aktiviert sein, da dies die Einrichtung deutlich vereinfacht.'''
Wenn der [[panStamp#panStick/Shield|panStick]] läuft, sollten die SWAP-Devices per autocreate angelegt werden, sobald sie das erste Mal senden, z.B. nach dem Einschalten oder nach einem Reset. Normalerweise werden beim autocreate alle Werte abgefragt und angezeigt. Das geht normalerweise ohne jedes Zutun.

panStick rein -> broadcast -> discovery -> anlegen.

Bei Devices mit power down Mode erfolgt dieses das erste Mal wenn sie Strom haben.

Alle panStamps durchlaufen beim Starten eine bestimmte Einschaltsequenz. Sie melden sich mit ihrer ID und ihrem ProductCode. Die ID ist die SWAP Device Adresse und bei einem frisch geflashten panStamp in der Regel <code>FF</code>. Das SWAP Modul versucht, ein Device mit der Default Adresse <code>FF</code> automatisch auf die erste freie Adresse im Bereich <code>F0 - FE</code> zu ändern.

Neue panStamps sollten nur Einer nach dem Anderen in Betrieb genommen werden, sonst haben mehrere die gleiche Adresse und das gibt Konflikte.

Wer mehrere Devices hat, sollte jedem nach dem Anlegen mit
set <device> regSet 09 <Device Adresse als 2 stellige hex zahl>
eine eigene ID zuweisen. Die landen auf dem panStamp im EEPROM und sind auch nach Neustart noch vorhanden.

Die anderen Adressen sind wie folgt belegt:
* <code>00</code> ist die Broadcast-ID
* <code>01</code> ist die ID des panStick am FHEM-System
* <code>FF</code> ist die Default ID, die jeder panStamp im Auslieferungszustand besitzt
* <code>F0-FE</code> sind die IDs, auf die autocreate die Adresse automatisch ändert, wenn ein neuer mit der ID <code>FF</code> erkannt wird und kein entsprechender Device-Name definiert ist.

{{Link2Forum|Topic= 12487 |Message=87261 }}

Ändert man die Adresse, dauert es einen Augenblick, bis alle Register neu übertragen worden sind.

Autocreate ändert bei der Einrichtung und Änderung der ID auch automatisch den Namen. Belässt man die ID im Bereich <code>F0 - FE</code> und ändert den Namen des Device, ist zu berücksichtigen, dass autocreate für neue Devices eine freie neue Adresse anhand der Device-Namen sucht. Dadurch könnte es zu Doppeltverwendung von IDs kommen.

Alternativ zum autocreate kann man ein Device auch von Hand anlegen mit
define <device> SWAP <ID>
Bis allerdings der ProductCode nicht per Attribut hinterlegt ist, was bei autocreate ebenfalls automatisch passiert, funktionieren nur die grundlegenden Funktionen bis zur 2. Modulebene.

=== set ===
Ist ein SWAP-Device definiert, stehen folgende set-Befehle zur Verfügung:
* regGet <reg>
Fragt den Wert des Registers mit der ID <reg> ab. Für die Systemregister kann hierzu statt der Register ID auch der Registername (siehe regListAll) verwendet werden.
{{Link2Forum|Topic= 12487 |Message=87679 }}

* regSet <reg> <data>
Schreibt <data> in den Register mit der id <reg>. <data> muss als HEX Zahl angegeben werden. Für die Systemregister kann hierzu statt der Register ID auch der Registername (siehe regListAll) verwendet werden.

* regSet <reg>.<ep> <data>
write <data> to endpoint <ep> of register <reg>. will not work if no reading for register <reg> is available as all nibbles that are not part of endpoint <ep> will be filled from this reading. ?

* statusRequest
Veranlasst, dass alle Register und deren Werte einmal übertragen werden.

* readDeviceXML
Liest das Device-Definition-XML-File neu ein.

* clearUnconfirmed
Löscht die Liste der unbestätigten Nachrichten.

* flash [<productCode>|<firmwareFile>]
Initiiert das „over-the-air“ Firmware update, dass (derzeit) nur von panStamps NRG unterstützt wird.
** ohne Parameter: Verwendet das SWAP_<current ProductCode>.hex-File aus dem Verzeichnis ./FHEM/firmware.
** <ProductCode>: Verwendet das SWAP_<ProductCode>.hex-File aus dem Verzeichnis ./FHEM/firmware.
** <firmwareFile>: Verwendet ein <firmwareFile> als absoluten File-Namen des HEX-Files.

=== get ===
* regList
Listet alle User-Register des SWAP-Device (Readings).

* regListAll
Listet alle Register des SWAP-Device (Internals und Readings).

* listUnconfirmed
Listet alle unbestätigten Nachrichten in der Warteschlange auf, also Nachrichten die von FHEM gesendet wurden, aber der Empfang durch das panStamp Modul nicht bestätigt wurde.

* products
Gibt alle auf dem System bekannten Productcodes nebst Daten aus.

* deviceXML
Gibt die Daten des zum derzeit zum per Attribut (ProductCode) eingerichteten Device-XML-Files aus.

=== Attribute ===
Wird der ProductCode bei der Definition nicht gesetzt, stehen auch nur die Standardbefehle bei zur 2. Modulebene zur Verfügung.

* createUnknownReadings
Erzeug Readings auch für Register, die im Device-XML-File nicht definiert werden.

* ProductCode
Legt den ProductCode eines SWAP-Device fest und liest dadurch das dazugehörige Device-Definition-XML-File ein. Erst wenn der ProductCode als Attribut vorgegeben wurde, z.B. für einen RGB-Sketch:
attr <device> ProductCode 0000002200000003
kommen zu den allgemeinen FHEM set- und get-Kommandos des [[SWAP]] Modul die spezifischen der 3. Modulebene 35_SWAP_<productcode>.pm mit hinzu (Siehe z.B. [[SWAP_0000002200000003]]). Dann werden die SWAP-Nachrichten an das entsprechende Modul weitergegeben und dort verarbeitet.

Für batteriebetriebene Devices, die während der Definition nicht aktiv sind, muss dieses Attribut manuell angelegt werden.

=== Device Definition File ===
Mit Hilfe der im jeweiligen Device Definition File hinterlegten Beschreibung werden hierzu automatisch userReadings angelegt (Wenn den Endpoints eine Unit mit Factor zugewiesen ist) die neben den reinen Registerwerten in hex auch ''menschenlesbare'' readings der Sensorwerte erzeugen.
Damit dies funktioniert, muss das Attribut ProductCode korrekt gesetzt sein. Das geschieht normalerweise automatisch beim Anlegen des Device.
Das entsprechende Device Definition File liegt unter ./FHEM/lib/SWAP wie hier beschrieben [http://forum.fhem.de/index.php/topic,12487.msg86257.html#msg86257].

Hier Beispielhaft anhand eines BMP085 Temperatur- und Luftdrucksensors dargestellt:

<code>
attr temp press userReadings voltage:0B-Voltage.* {hex(ReadingsVal($name,"0B-Voltage","0"))*0.001}, temperature:0C.0-Temperature.* {hex(ReadingsVal($name,"0C.0-Temperature","0"))*0.1-50}, pressure:0C.1-Pressure.* {hex(ReadingsVal($name,"0C.1-Pressure","0"))*0.01}, pressureNN:0C.1-Pressure.* {sprintf("%.2f",hex(ReadingsVal($name,"0C.1-Pressure","0"))*0.01 + AttrVal("global", "altitude", 0)/8.5)}
</code>

[[Datei:SWAP_ 0000000100000005.png|mini|hochkant=2.5|Resultat eines stateFormat]]
Aus diesen Readings kann dann mit stateFormat die gewünschte Darstellung für die Raumübersicht erzeugt werden:

<code>
attr temppress stateFormat {sprintf("%.1f",ReadingsVal($name,"temperature",0))."°C ".sprintf("%.1f",ReadingsVal($name,"pressureNN",0))."mbar"}
</code>

Ein weiteres Beispiel ist das Definition File für das RGB-Board rgbdriver.xml.

=== SWAP Register ===
Jeder panStamp stellt elf Systemregister (<code>00</code>-<code>0A</code>) [https://github.com/panStamp/panstamp/wiki/Standard-SWAP-registers] und beliebig viele sketchabängige Userregister (<code>0B</code> - <code>xx</code>)bereit. Die Beschreibung der jeweils von einem Sketch bereitgestellten Userregister erfolgt in ''Device Definition Files''. Die Identifikation der Art eines panStamp und die Zuordnung zu einem bestimmten Device Definition File erfolgt über den ProductCode der aus ''Hersteller''- und ''Produkt-Id'' gebildet wird.

In den Systemregistern stehen z.B. der ProductCode, die Deviceadresse und das Übertragungsintervall. Konfigurierbare Register werden im EEPROM gesichert, so dass die Werte auch bei einem Neustart nicht verlorengehen. Beim ersten Starten eines panStamp ist das EEPROM mit <code>FF</code> initialisiert und alle konfigurierbaren Register haben diesen Wert, also z.B. die Adresse <code>FF</code> und das Intervall <code>FFFF</code> (zwischen 18 und 19 Stunden).

Die Systemregister werden in der Device Detailansicht bei den InternalValues im oberen Bereich angezeigt und die User-Register als reading im unteren Bereich.

Jeder panStamp durchläuft beim Start eine definierte Einschaltsequenz und überträgt als erstes seinen ProductCode. Batteriebetriebene panStamps warten anschließend drei Sekunden auf Konfigurationskommandos. Danach werden bestimmte Systemregister und aktuelle Messwerte gesendet.

== Anwendungsbeispiele ==
=== Übersicht der Register anzeigen ===
Sobald ein SWAP Device mit dem ProductCode korrekt angelegt wurde, können die Userregister bzw. alle Register aufgelistet werden:
get <device> regList
get <device> regListALL

=== Register auslesen oder setzen ===
Einzelne Register können abgefragt werden mit
set <device> regGet <ID>
oder auch gesetzt werden durch
set <device> regSet <ID> <value>
Für die Systemregister kann hierzu statt der Register ID auch der Registername (siehe regListAll) verwendet werden.

=== Intervall bei Sketch mit power down / batterie betriebene panStamps ===
panStamp Hardware mit power down Mode durchlaufen während des Booten (beim Einschalten oder bei einem Reset) eine 3 Sekunden Schleife und warten auf SWAP-Kommandos, die z.B. Register für das Sendeintervall oder sonstige Konfigurationen ändern. Nach dieser Zeit wird die normale Loop Schleife im Arduino Sketch gestartet. Normaler Weise werden dann die Register mit den Sensorwerten an FHEM gesendet. Power down Devices gehen danach schlafen (power down Modus mit extrem niedrigem Stromverbrauch) und wachen regelmäßig auf (TX_INTERVAL aus dem Systemregister) um die Sensoren auszulesen und die Werte wieder an FHEM zu senden. Das Sendeintervall betrifft nur das Senden der Sensorwerte. Normalerweise empfängt das panStamp Modul in diesem Modus keine Befehle mehr. Das passiert nur einmalig nach einem Reset. Je nach Sketch kann das natürlich variieren und anders programmiert sein!

Nachrichten an eine panStamp-Hardware im power-down-state werden in FHEM gepuffert (siehe INTERNAL SWAP_CMDsPending) und dann an die panStamp-Hardware geschickt, sobald dieses sich im SYNC Status befindet. Dieses ist typischer Weise nach dem Startup z.B. nach einem Reset der Fall.

Bei batteriebetriebenen Sensoren sollte das Sendeintervall auf einen sinnvollen Wert gesetzt werden:
set <device> regSet 0A <Intervall in Sekunden als 4 stellige hex zahl>
{{Link2Forum|Topic=12487 |Message=87409}}

Für batteriebetriebene panStamp-Module (genauer: Module die den Power-Down-Modus unterstützen) wird das Default Sendeintervall bei der Einrichtung automatisch von <code>FFFF</code> zu <code>0384</code> (900 Sekunden = 15 Minuten) geändert. Das Intervall wird nur automatisch gesetzt, wenn pwrdownmode im device definition file true ist. {{Link2Forum|Topic=12487 |Message=89205}}

Es gibt mit bestimmten panStamp lib Versionen das Problem das ein Wert von <code>FFFF</code> im Systemregister <code>0A</code> zum Überlauf führt und der panStamp dann ununterbrochen sendet. Im [[SWAP]] Modul wird versucht das abzufangen. Das funktioniert auf manchen langsamen host Systemen (z.B. FritzBox) nicht, weil der panStamp so schnell sendet, dass FHEM mit dem Abarbeiten so beschäftigt und ausgelastet ist, dass es selber nicht zum Senden kommt. Zur Abhilfe kann im Sketch in setup() ganz am Anfang ein
EEPROM.write(EEPROM_TX_INTERVAL, 0x55);
EEPROM.write(EEPROM_TX_INTERVAL+1, 0x55);
eingefügt werden. Den Sketch dann noch mal flashen. Wenn der panStamp mit diesem Sketch einmal durchgelaufen ist, können diese beiden Zeilen wieder entfernen und der panStamp noch mal geflasht werden. Damit wurde das Sendeintervall einmalig auf <code>0x5555</code> (0x5555 in Dezimal = 21.845 (Sekunden), entspricht 364 Minuten) gesetzt.

=== Device Adresse automatisch setzen ===
Erkennt das SWAP Modul eine panStamp-Hardware mit der Adresse <code>0xFF</code> wird automatisch eine neue Adresse durch das [[SWAP] Modul vergeben. Die automatisch vergebenen Adressen sind im Bereich <code>0xF0 - 0xFE</code>. Das soll das Inbetriebnehmen von mehreren panStamp-Hardwaremodulen gleichzeitig erleichtern. Der automatisch vergeben Adressbereich ist begrenzt und sollte nur temporär verwendet werden. Nach der Inbetriebnahme sollte den panStamp Modulen eine individuelle, lokal passende Adresse geändert werden. {{Link2Forum|Topic=12487 |Message=87919}}
Automatisch gesetzte Werte sollten danach manuell auf die jeweilige Installation angepasst werden.
{{Link2Forum|Topic=12487 |Message=87859}}

Im Log sollte etwas in dieser Art auftauchen:
<pre>
2013.07.29 20:14:29 3: SWAP Unknown device FF, please define it
2013.07.29 20:14:29 2: autocreate: define SWAP_F0 SWAP FF 000000010000000E
2013.07.29 20:14:29 3: SWAP_F0: I/O device is panStamp
2013.07.29 20:14:29 3: SWAP SWAP_F0: changing 09-DeviceAddress from default FF to F0
2013.07.29 20:14:30 3: SWAP SWAP_F0: changing 0A-PeriodicTxInterval from default FFFF to 0384 (900 seconds)

2013.07.29 20:16:35 3: SWAP Unknown device FF, please define it
2013.07.29 20:16:35 2: autocreate: define SWAP_F1 SWAP_0000002200000003 FF 0000002200000003
2013.07.29 20:16:35 3: SWAP_F1: I/O device is panStamp
2013.07.29 20:16:36 3: SWAP SWAP_F1: changing 09-DeviceAddress from default FF to F1
</pre>

=== Registerinhalt von hex auf Dezimal umrechnen ===
Die Registerinhalte sind immer hexadezimale Zahlenwerte. In den meisten Fällen werden diese umgerechnet werden in Dezimalzahlen.
Hierzu kann die Perlfunktion hex() verwendet werden.
Beide Funktionsaufrufe geben in diesem Beispiel die Dezimalzahl 250 aus:
{hex("FA")}
{hex("0xFA")}

=== Beispiel: panStamp soilmoisture Sketch in FHEM einbinden ===
Der panStamp soilmoisture Sketch aus dem examples Verzeichnis ist mit dem Standard SWAP Modul kompatibel.

Ein Artikel über ein selbst entwickeltes panStamp Batterieboard zum Anschluss von Analogsensoren/1Wire und Solarversorgung ist hier [[Bodenfeuchtesensor]] beschrieben. Die Weiterentwicklung zum Umweltsensor ist hier [[panStamp_Umweltsensor]] beschrieben.

Eine für einen Vegetronix Sensor angepasste Version kann von [http://sourceforge.net/p/fhem/code/HEAD/tree/trunk/fhem/contrib/arduino/ sourceforge] heruntergeladen werden. Das Übertragungsintervall ist wie üblich über das Register <code>0A</code> konfigurierbar. Der Sensor wird an GND, D7 für die Versorgungsspannung und A4 für den Messwert angeschlossen. Erfahrungen haben gezeigt, dass bei einem fünfminütigen Übertragungsintervall nach 12 Monaten Laufzeit die Batteriespannung von 1.55V auf 1.4V abfällt. Das würde bedeuten, dass eine Batterie im Batterieboard mindestens eine Laufzeit von drei Jahren haben sollte.

<code>set <MyBodenfeuchte> stateFormat VWC_A%</code>

<code>
set <MyBodenfeuchte> userReadings Level0_Voltage {hex(ReadingsVal($name,"0C.0-Moisture_level_0","0"))*(3.3/1024)}, VWC_A:0C.0-Moisture_level_0 {sprintf("%.0f",(11.6552 * (ReadingsVal($name,"Level0_Voltage","0"))**4 + 7.10835 * (ReadingsVal($name,"Level0_Voltage","0"))**2 - 0.569557) / ((ReadingsVal($name,"Level0_Voltage","0"))**2 + 1))}, voltage:0B-Voltage {hex(ReadingsVal($name,"0B-Voltage","0"))*0.001}, battery:0B-Voltage {(ReadingsVal($name,"voltage","0")<1?"low":"ok")}
</code>

[[Datei:SWAP_ soilmositure-plot.jpg|mini|x100px|Bodenfeuchte]]
<div class="tright" style="clear:none">[[Datei:panstamp_vegetronix1.jpg|mini|ohne|x130px|Vegetronix Bodenfeuchtesensor an panStamp]]</div>
<div class="tright" style="clear:none">[[Datei:panstamp_vegetronix2.jpg|mini|ohne|x130px|Vegetronix Bodenfeuchtesensor an panStamp]]</div>

Mit einem entsprechend erweiterten Sketch lassen sich auch mehrere Sensoren an einem panStamp auslesen.

Die folgenden Bilder zeigen eine panStamp/Vegetronix Außeneinheit im IP65-Gehäuse. Dieser Aufbau wird ganzjährig den Witterungseinflüssen ausgesetzt. Die auf den Stab aufgesetzte Antenne muss nicht verwendet werden, bei kürzeren Funkstrecken ist eine innenliegende Drahtantenne ausreichend. Bitte in FHEM den RSSI- und LQI-Wert sowie die Gleichmäßigkeit des Empfangens der 5 Minuten Sendeintervalle dementsprechend beobachten.

== Trouble Shooting ==
=== value has to be 10 byte(s) in size ===
Es besteht die Möglichkeit, dass die Internals aus irgendeinem Grund nicht vollständig sind.
Abhilfe in einem solchen Falle kann das Absetzen der folgenden beiden Befehlt schaffen
set <device> statusRequest
set <device> readDeviceXML

Wenn das nicht zum Erfolg führt, hilft ggf. ein Löschen und neu setzen des ProductCode Attributs.
{{Link2Forum|Topic=34474.0}}

Das Übertragen aller Daten nach dem Statusrequest kann einen Augenblick dauern.

Eine weitere Möglichkeit:
Die Fehlermeldung kommt immer wenn FHEM nicht weiß welche Firmware auf der panStamp-Hardware ist. Das passiert wenn irgendetwas in der Kommunikation schief geht während FHEM initialisiert.
{{Link2Forum|Topic=13890 |Message=122414}}

=== register 0F is not known ===
{{Link2Forum|Topic=12487 |Message=84257}}

=== Komplette Übersicht eines Device ===
list <device>
{{Link2Forum|Topic=13890 |Message=201467}}

=== fehlender oder falsche ProductCode ===
Fehlt der ProductCode, werden die zum Sketch zugehörigen Befehle nicht angezeigt und die Register nicht korrekt zugeordnet.
Verändert man den ProductCode, sollte man im Anschluss folgenden Befehlt absetzten, um alle Register neu auszulesen
set <device> statusRequest

{{Link2Forum|Topic=13890 |Message=201910}}

=== missing commands und register 00-0A unvollständig ===
Wenn in den INTERNALS missing commands (SWAP_Sent_unconfirmed) auftauchen und ggf. die Register <code>00-0A</code> nicht vollständig sind und das INTERNAL "channels" nicht vorhanden ist, gibt es irgendein Kommunikationsproblem.

{{Link2Forum|Topic=13890 |Message=201939}}

=== Funktion des Autocreate ===
Beim autocreate wird versucht ein Name für das Device zu vergeben, der zur nächsten freien Adresse passt. Während dieses Prozessen bleibt die Adresse erst mal trotzdem <code>FF</code>. Erst wenn das Device angelegt wird, kann versucht werden automatisch die Adresse zu setzen, hoffentlich auf die gleiche freie, die beim Namen auch schon gefunden wurde. {{Link2Forum|Topic=12487 |Message=88110}}

=== Adresse manuell setzen ===
Um die Adresse manuell bereits in den Sketch einzubauen kann man wie hier beschrieben vorgehen.
{{Link2Forum|Topic=13890 |Message=122347}}

=== Undefined subroutine &main::XMLin ===
Erhält man diese Fehlermeldung
Undefined subroutine &main::XMLin called at ./FHEM/34_SWAP.pm line 108.

2013.09.26 11:34:24 0: ERROR: Cannot autoload SWAP
2013.09.26 11:34:24 3: panStick: Unknown code 000A001B000A000000000100000007, help me!

Es fehlt XML::Simple, was folgendermaßen installiert werden kann:
sudo apt-get install libxml-simple-perl

=== panStamp antwortet nicht/EEprom to factory defaults ===
Wenn der panStamp nicht antwortet, kann es sein das die Adressen durcheinander gekommen sind. Dann musst man einmal in <code>setup()</code> ein <code>eepromToFactoryDefaults()</code> aufrufen und damit flashen. Wenn damit einmal gestartet wurde, die Zeile wieder entfernen und den normalen Sketch flashen. {{Link2Forum|Topic=13890 |Message=121677}}

=== Factory Defaults ===
Um einen panStamp auf den Auslieferungszustand zurückzusetzen, muss man beim Sketch folgendes in die <code>setup()</code> Routine einfügen:
eepromToFactoryDefaults()
{{Link2Forum|Topic=13890 |Message=157125}}

=== Status LED ===
Die Status LED auf dem Board wird in der config.h deaktiviert, indem man die Zeit <code>#define LED_DEBUG</code> mit "//" auskommentiert. {{Link2Forum|Topic=13890 |Message=164731}}

== Links ==

[[Kategorie:panStamp]]

PanStamp Programmierung

2016-06-04T16:47:00Z

Joshi04: Neustrukturierung der Artikelserie "panStamp"; panStamp Programmierung

{{SEITENTITEL:panStamp Programmierung}}

Dieser Artikel gehört zum Themenkomplex "panStamp" der [[panStamp|hier]] seinen Hauptartikel hat.

== unter Windows ==

=== Installation des USB-Sticks (panStick) ===

Für die Installation des panStick unter Windows gibt es mehrere Möglichkeiten.
# Installiert man eine Arduino IDE, kann dabei auch der Treiber für den panStick mitinstalliert werden.
# Treiber von der offiziellen Homepage herunterladen und installieren [http://www.ftdichip.com/]. Die Treiber befinden sich ebenfalls im Unterordner drivers der Arduino IDE.

Bei der Installation kann es sein, dass kein Treiber gefunden wird. Dann muss der entsprechende Treiber manuell ausgewählt werden entsprechend dieser Anleitung [https://www.youtube.com/watch?v=SPdSKT6KdF8].

=== Arduino IDE 1.0.x vorbereiten ===
Zum Flashen der panStamps wird die Arduino IDE benötigt. Eine Installationsanleitung für Arduino IDE 1.0 ist unter folgendem Link zu finden:
:https://code.google.com/p/panstamp/wiki/firststeps

Die IDE 1.5.x oder höher ist zwar mit den AVRs und NRGs kompatibel, wichtig zu wissen ist allerdings, dass mit dem Wechsel von 1.0.x zu 1.5.x oder höher es größere Änderungen der panStamp/SWAP Librarys gegeben hat. Dadurch lassen sich einige der bislang zur Verfügung stehenden Sketches (derzeit) nicht unter 1.5.x oder höher kompilieren (z.B. der RGBWW-Sketch). Für die IDE 1.0.x gibt es keine passenden Arduino Lib für den NRG [[https://github.com/panStamp/panstamp/wiki/First%20steps]], die daher nur mit den AVRs kompatibel sind. Im Folgenden wird sich für die Programmierung unter Windows daher auf die letzte 1.0.x IDE bezogen.

* Man lädt die '''Arduino IDE 1.0.x''' für Windows [[http://arduino.cc/en/Main/OldSoftwareReleases]].
* Für bestimmte Sketches müssen noch die entsprechenden Libs hinzugefügt werden (siehe [[panStamp#Sketch konfigurieren|explizite Anwendung]]).
* Unter <code>Tools/Board</code> wird das '''passende Board''' ausgewählt, dass dem Chip auf dem panStamp entspricht. Für den panStamp AVR: <code>Arduino Pro or Pro Mini (3,3V, 8 MHz) /w ATmega328</code>. Wenn man das boards.txt file von [http://code.google.com/p/panstamp/downloads/detail?name=boards.txt&can=2&q= hier] installiert, kann man in der IDE auch direkt <code>panStamp</code> als Plattform auswählen.
* Nun muss unter <code>Tools/Serieller Port</code> noch der richtigen '''Com-Port''' auswählen werden, unter dem der panStick eingebunden worden ist (entsprechend Gerätemanager).
* Als letztes unter <code>Tools/'''Programmer'''</code> noch den <code>AVRISPx mkII</code> auswählen.

=== Arduino IDE 1.6.x vorbereiten ===
Eine Installationsanleitung für Arduino IDE 1.6.4 ist unter folgendem Link zu finden:
:https://github.com/panStamp/panstamp/wiki/Installing-panStamp-cores-and-libraries-for-Arduino

'''Wichtiger Hinweis:'''
Bitte in jedem Falle die Einschränkungen bezüglich der Sketch-Kompatibilität beachten (siehe vorheriger Abschnitt).

=== Sketch vorbereiten, kompilieren und hochladen ===
* Den Sketch lädt man von der entsprechenden Quelle und entpackt die Dateien in einen Unterordner z.B. parallel zum libraries-Ordner (unter "Eigene Dateien"). Der Ordner darf '''nicht im''' libraries-Ordner liegen, da die Arduino IDE dort das Speichern nicht zulässt. Innerhalb des Unterordners erwartet die IDE die Dateien in einen Unterordner namens "sketch".
* sketch.ino oder ähnlich in der Arduino IDE öffnen.
* Nun entsprechend den Bedürfnissen auf dem geöffneten Reiter in den config.h die nicht benötigten Zeilen mit "//" auskommentieren bzw. anpassen.
* Nun sollte über Sketch/Überprüften/Kompilieren die Erstellung des Sketches möglich sein.
* Falls erfolgreich unter Datei/Hochladen (ohne Programmer) den Sketch auf den panStamp laden.

Bezüglich der Anpassung des Sketches sind einige spezifische Informationen unten bei den expliziten Anwendungen ergänzt.

=== Hexfile hochladen mit XLoader ===
Um ein fertig kompiliertes HEX-File hochzuladen, soll dieses über ein Programm namens XLoader möglich sein. [[http://xloader.russemotto.com]]

== unter Linux ==

=== Installation des USB-Sticks (panStick) ===

Eigentlich sollte der panStick automatisch von System erkannt und eingerichtet werden.
Er sollte dann automatisch unter /dev/ttyUSBx eingebunden werden. "x" steht für eine freie fortlaufende Nummer.

Falls er nicht automatisch angelegt worden ist, kann man zunächst prüfen, ob dieser überhaupt eingebunden und richtig erkannt wurde.
<source lang="bash">lsusb</source>
Sollte etwas Ähnliches zurückmelden:
<source lang="bash">Bus 003 Device 002: ID 0403:0000 Future Technology Devices International, Ltd H4SMK 7 Port Hub</source>

Falls das Device nicht automatisch angelegt worden ist, muss dieses ggf. von Hand erledigt werden, wie in diesem {{Link2Forum|Topic=12487|Message=87746}} beschrieben.

Mit dem folgenden Befehl sollte in der Liste ein ttyUSB auftauchen. Normalerweise mit der Nummer 188.
<source lang="bash">cat /proc/devices</source>

Das Device wird dann angelegt mit:
<source lang="bash">sudo mknod /dev/ttyUSB0 c 188 0</source>

Zusätzlich muss für den Betrieb des panStick das ftdi_sio Modul zur Verfügung stehen. Dieses lässt sich prüfen mit
<source lang="bash">lsmod</source>

Diese Voraussetzung könnte den Betrieb an einer [[AVM Fritz!Box|Fritz!Box]] erschweren, da nicht sicher ist, ob dieses Modul standardmäßig installiert ist.

Legt man das Device von Hand an, kann es sein, dass die Berechtigungen nicht richtig gesetzt sind. Beim Versuch der Definition erhält man dann die folgende Fehlermeldung:
2015.04.23 22:20:06 3: Opening panStick device /dev/ttyUSB0
2015.04.23 22:20:06 3: Can't open /dev/ttyUSB0: Permission denied

Das Device sollte für die Gruppe dialout Lese-/Schreibberechtigungen haben.
Ist dieses nicht der Fall, lassen sich diese über diesen folgenden Befehl setzen, damit wird der "Besitzer" festgelegt:
<source lang="bash">sudo chown root:dialout ttyUSBx</source>

Hiermit werden die Berechtigungen gesetzt.
<source lang="bash">sudo chmod a+rw /dev/ttyUSBx</source>

Der Benutzer "fhem" sollte selbstverständlich der Gruppe "dialout" angehören. Ist dieses nicht der Fall:
<source lang="bash">sudo adduser fhem dialout</source>

Falls dem nicht so sein sollte, hilft ggf. einer dieser beiden Links weiter:
[[https://www.youtube.com/watch?v=UOECwHhCWRg]] [[http://www.element14.com/community/community/designcenter/single-board-computers/next-gen_beaglebone/blog/2013/07/15/bbb--usb-io-with-ftdi-ft2232h]] bzw. die Installation des Moduls.

Da bei der Verwendung mehrerer USB-Interfaces es durchaus vorkommen kann, dass sich die Reihenfolge und damit die Nummerierung der Adresse ändert, sei darauf hingewiesen, dass die Adressierung auch per "by-id" geschehen kann (siehe {{Link2Forum|Topic=12487|Message=317189|LinkText=diesen Forenbeitrag}}). Dadurch wird die Adressierung wesentlich stabiler gegenüber Änderungen bei Neustarts des Systems oder tauschen der USB-Ports. Die Adressierung über die ID ist daher stark empfohlen, die o.g. Schritte bzgl. der Einrichtung müssen entsprechend bei Bedarf angepasst werden.

Hat man die Adresse herausgefunden, wird der panStick folgendermaßen in der FHEM Eingabezeile definiert:
<source lang="bash"> define mypanStick panStamp /dev/serial/by-id/usb-FTDI_FT232R_USB_UART_A92LHB3Z-if00-port0@38400</source>

Dieses IO-Device, versucht dann, alle panStamps per SWAP-Broadcast zu finden und per autocreate anzulegen, wenn dieses aktiv sind. Die weitere Funktion übernimmt das Modul [[SWAP]], was das Funkprotokoll der panStamp Module in FHEM implementiert.

'''Betrieb an der Fritzbox'''
Spezialitäten zum Betrieb an einer Fritzbox sind hier [http://forum.fhem.de/index.php/topic,12487.msg87778.html#msg87778] und hier [http://forum.fhem.de/index.php/topic,12487.msg95914.html#msg95914] beschrieben. Es scheint nur der hintere USB-Anschluss für die Verwendung zu laufen. Außerdem muss der USB-Fernanschluss deaktiviert sein.

=== INO ===
Der RGB-Sketch wurde mit Hilfe des Tools INO entwickelt.
{{Link2Forum|Topic=12487|Message=82139 }}

Die Installation erfolgt am leichtesten mit Hilfe des Tools pip.

Voraussetzungen für das Tool sind darüber hinaus picocom für die Kommunikation mit der seriellen Schnittstelle und die Arduino. Im gleichen Zuge lässt sich pip installieren.
Die benötigten Pakete werden über folgenden Aufruf installiert
<source lang="bash">sudo apt-get install picocom python-pip arduino</source>

Die Installation erfolgt im Anschluss über
<source lang="bash">sudo pip install ino</source>

Die für einen Sketch erforderlichen libs werden in den entsprechenden lib Ordner kopiert (dort in entsprechenden Unterordnern).

Die Pfade im Zip sind an dieses Tool angepasst.
{{Link2Forum|Topic=12487|Message=94830 }}

Der serielle Port in der ino.ini muss selbstverständlich an die passende dev-Schnittstelle angepasst werden.

Als letztes sind die Parameter für das Board noch in die board.txt unter /usr/share/arduino/hardware/arduino einzutragen. Die Parameter lassen sich von hier extrahieren [http://old.panstamp.com/downloads] bzw. lauten für den AVR
<pre>
##############################################################

panstamp.name=PanStamp v2.0 (3.3V, 8 MHz) w/ ATmega328

panstamp.upload.protocol=arduino
panstamp.upload.maximum_size=30720
panstamp.upload.speed=57600

panstamp.bootloader.low_fuses=0xE2
panstamp.bootloader.high_fuses=0xD8
panstamp.bootloader.extended_fuses=0x07
panstamp.bootloader.path=atmega
panstamp.bootloader.file=ATmegaBOOT_168_atmega328_pro_8MHz.hex
panstamp.bootloader.unlock_bits=0x3F
panstamp.bootloader.lock_bits=0x0F

panstamp.build.mcu=atmega328p
panstamp.build.f_cpu=8000000L
panstamp.build.core=arduino
panstamp.build.variant=standard

##############################################################
</pre>

Wichtig zu wissen: jedesmal, wenn die Arduino ein Update erhält, wird vermutlich diese Datei überschrieben, so dass die Eintragung wiederholt werden muss.

Hier sind die grundlegenden Befehle beschrieben [http://inotool.org/quickstart].

Wechselt man nun in das Verzeichnis z.B. des RGBdriver, lässt die der Sketch kompilieren über
<source lang="bash">ino build</source>

Und hochladen über
<source lang="bash">sudo ino upload</source>

; Troubeshooting
: siehe {{Link2Forum|Topic=12487|Message=134786|LinkText=diesen Forenbeitrag}}

== IDE unter MacOS ==
Da für den RGB-Sketch die IDE 1.0.x benötigt wird und diese Java SE 6 eine Voraussetzung ist, stellt die IDE und MacOS keine Optimale Konfigurationsumgebung dar. Wer es trotzdem probieren möchte
{{Link2Forum|Topic=12487|Message=82055 }}

== over-the-air (derzeit) nur NRG ==
Die neueren panStamp NRGs können seit einiger Zeit auch over-the-air geflasht werden, wie hier im zugehörigen {{Link2Forum|Topic=30589|LinkText=Forumthread}}.

== Was überlebt das Flashen==
Bestimmte Konfigurationen überstehen das Flashen, dieses sind zumindest Adresse und Intervall, die nicht neu gesetzt werden müssen (siehe diesen {{Link2Forum|Topic=12487|Message=87560}}).

== EEPROM löschen ==
Das EEPROM lässt sich komplett löschen, indem man in der setup() die folgende Eintragung vornimmt (siehe dazu diesen {{Link2Forum|Topic=13890|Message=156868}}):
eepromToFactoryDefaults()

[[Kategorie:panStamp]]