FHEMWiki - Benutzerbeiträge [de]

Meta

2019-07-11T14:37:40Z

Loredo: /* Encoding */

= Development Module and Package Meta Data =

== Einleitung ==

Neben den für ein FHEM Modul notwendigen [[DevelopmentModuleIntro|obligatorischen]] Metadaten (CommandRef, Kurzbeschreibung, Typ), gibt es in FHEM das Perl Package FHEM::Meta (oder kurz Meta.pm). Die Einbindung in ein FHEM Modul (= stellt Devices zur Verfügung) oder ein FHEM Package (= stellt Subroutinen für ein oder mehrere FHEM Module bereit) ermöglicht es, Informationen über das Modul in Form eines JSON [https://perldoc.perl.org/perlpod.html Pod] (auch META.json genannt) direkt in die Datei mit einzubetten. Darüber wird es möglich, diese Zusatzinformationen auch bereits auszuwerten und anzuzeigen, ohne dass ein Modul geladen oder verwendet wird. Beispielsweise kann ermittelt werden, welche Perl Module für die Nutzung des Moduls notwendig sind und ob eine bestimmte Version vorausgesetzt wird. Außerdem können Informationen über die Version des Moduls, die Historie, den Autor, für Supportanfragen und vieles weiteres hinterlegt werden.

Das Grundschema für die JSON Struktur basiert dabei auf der offiziellen [https://metacpan.org/pod/CPAN::Meta::Spec CPAN::Meta::Spec] Spezifikation, welche auch bei regulär veröffentlichten Perl Modulen verwendet wird. Das FHEM::Meta Package hilft dabei, diese JSON Informationen aus der Datei auszulesen und stellt diese im globalen %modules Hash des jeweiligen Moduls zur weiteren Verarbeitung bereit. Meta wertet dabei die in der Moduldatei (bei Modulen, die im SVN veröffentlicht sind, auch weitere Informationsquellen/-dateien des SVN) hinterlegten Maintenance und Supportdaten aus, so dass diese Informationen für sämtliche FHEM Module grundsätzlich bereitgestellt werden können. Meta erweitert die Standard Spezifikation dafür mit eigenen JSON Attributen, die spezifikationskonform im Namen mit <code>x_</code> beginnen. Diese Art, zusätzliche Informationen über die Funktionalität eines Modules bereitzustellen, ohne dass ein Modul dafür tatsächlich geladen werden muss, steht jedem Modul als Erweiterung zur Verfügung. Es ist also denkbar, dass Module darüber bekanntmachen, welche Netzwerk-Protokolle sie beherrschen, wie bestimmte Geräte im Netzwerk gefunden werden können und mit welchen define-Parametern ein Gerät in FHEM angelegt werden kann. Hierzu gibt es erste Ansätze, die sich in [https://forum.fhem.de/index.php/topic,67368.0.html Planung] befinden.

== Der FHEM Installer ==

Der FHEM Installer ist ein FHEM Modul, welches ein graphisches Interface für die Metadaten bereitstellt. Mit Hilfe des FHEM Installers werden die Metadaten auch für Module in den Speicher geladen, welche keine explizite Unterstützung eingebaut haben. Sobald man die Informationen für ein bestimmtes Modul oder Package abfragt, wird der Meta-Hash über die Funktion FHEM::Meta::Load() geladen. Für FHEM Module, die beim Start von FHEM bereits in Verwendung sind, werden die Metadaten automatisch im Voraus geladen, so dass sie zur Laufzeit zur Verfügung stehen. Es ist geplant, dass dies auch zur Laufzeit für Module, für die der Benutzer ein neues Device anlegt, geschieht.

Die Grundfunktion des FHEM Installer ist jedoch nicht die Bereitstellung der Metadaten, sondern die Auswertung derselben. In seiner weiteren Entwicklung soll er dabei unterstützen fehlende Systemkomponenten, die für die Nutzung eines FHEM Moduls notwendig sind, zu installieren und aktuell zu halten. Die Installation und Aktualisierung von Perl Modulen ist bereits jetzt in einer ersten Ausbaustufe möglich.

Stellt man am FHEM Installer Device das Attribut <code>installerMode</code> auf developer, dann werden einige weitere Get Befehle sichtbar, über die sich auch der Inhalt des kummulierten META.json Hashes anzeigen lässt. Dies ist oft hilfreich für ein initiales Verständnis, welche Informationen FHEM::Meta bereits über ein Modul gesammelt hat, bevor man diese über einen eigenen META.json Pod in der Moduldatei ergänzen oder verändern möchte.

Hinweis: Die Weiterentwicklung von FHEM::Meta ist stark an die weitere Entwicklung des FHEM Installer geknüpft. Dort geht es dann insbesondere darum, dass FHEM Module aus anderen Installationsquellen neben dem SVN die gleiche Metadaten einliefern können, insbesondere was Versionierung und Historie angehen. Dieses und mehr ist jedoch ein ganz eigenes Kapitel und soll deshalb für das Thema FHEM::Meta nur kurz erwähnt sein.

== Der search-Befehl ==

Der FHEM Befehl <code>search</code> ist ein Wrapper, um den Get-Befehl <code>search</code> beim FHEM Installer Device im Schnellzugriff über die FHEM Befehlszeile aufzurufen. Hierüber lassen sich die Metadaten aller FHEM Module durchsuchen und ermöglicht so das Auffinden von FHEM Modulen für eine bestimmte Funktion oder ein Gebiet. FHEM Module, die einen META.json Pod bereitstellen, können dort Schlagworte hinterlegen, über die das Modul in der Suche gefunden werden können soll. FHEM::Meta generiert für Module, die über das SVN bereitgestellt werden, bereits einige Schlagworte basierend auf dem hinterlegten Support Forum in MAINTAINER.txt. Auch Der Modul Typ (helper|device|command) findet sich als eigenes Schlagwort wieder. Man erhält also Out-of-the-Box bereits eine ziemlich gute Kategorisierung über den Anwendungsbereich eines bestimmten Moduls und welche anderen Module noch in diesen Bereich fallen. Ein Modulname alleine hingegen lässt oftmals nicht auf die Funktionalität dahinter schließen, insbesondere wenn Hersteller- oder Produktnamen eine Rolle spielen, die man selbst bisher nicht kennt.

== Erweiterung eines FHEM Moduls mit META.json Pod ==

Möchte ein Modulautor aktiven Support für FHEM::Meta einbauen, dann ist der erste Schritt die Bereitstellung eines META.json Abschnitts am Ende der Modul- oder Paketdatei. Dieser Abschnitt beinhaltet ein reguläres JSON Objekt. Deshalb empfiehlt es sich den Abschnitt vor dem hinzufügen über einen JSON Validator auf seine Syntax zu überprüfen. Ansonsten wird von FHEM::Meta beim laden eine entsprechende Meldung im FHEM Log ausgegeben und es werden keinerlei Metadaten mehr über das Modul bereitgestellt. Sobald ein META.json Abschnitt vorhanden ist, geht FHEM::Meta davon aus, dass dieses maßgeblich ist und wird deshalb nur noch Daten ergänzen, die dort nicht enthalten sind. Fehlt also ein valides META.json Objekt als Basis, so werden auch diese Ergänzungen nicht erfolgen und der Modulautor muss zunächst zwingend das JSON Gerüst korrigieren.

Für das Hinzufügen des META.json Abschnitts kann man mit der Beispieldatei [https://svn.fhem.de/trac/browser/trunk/fhem/contrib/META.json.txt contrib/META.json.txt] als Ausgangsbasis starten. Die oben erwähnte Spezifikation sollte man einmal gelesen haben um zu verstehen, welches Format für ein Datenfeld gilt und welche Angaben die Spezifikation als zwingend vorschreibt. Es ist empfehlenswert alle dort als ''mandatory'' erwähnten Angaben in META.json anzugeben, auch wenn diese Informationen vielleicht teilweise in anderen Dateien in FHEM bereits vorhanden sind (gilt natürlich nur für Module, die auch über das SVN verteilt werden). Beispielsweise sollte eine (Kurz-)Beschreibung trotzdem enthalten sein. Der Grund ist, dass zumindest theoretisch dann auch andere 3rd-party Tools, die mit Perl Modulen hantieren, diese Informationen in vereinfachter Art ebenfalls auslesen und auswerten können. Diese Tools könnten darauf bestehen, dass sie eben diese als zwingend spezifizierten Attribute dort auch vorfinden. FHEM::Meta fügt fehlende Informationen zwar zur Laufzeit selbst hinzu, dies hilft jedoch anderen Tools, die das JSON Objekt direkt auswerten, eben nicht. Wie genau ein Modulautor dieser Empfehlung folgen möchte, ist ihm überlassen.

Die Inhalte aus der Beispieldatei oben sollten als Mindestvoraussetzung angesehen werden. Insbesondere der Abschnitt <code>prereqs</code> für verwendete Perl Module ist hier wichtig, da das Vorhandensein eines selben eine wesentlich schnellere Ladezeit der Metainformationen zur Folge hat, da die Abhängigkeiten nicht durch eine Analyse erfolgen muss. Das bedeutet jedoch auch, dass diese Informationen vollständig sein müssen und der Autor dafür verantwortlich ist, das diese stimmig sind. Als Hilfestellung, was man hier für sein Modul eintragen sollte, kann man sich über den FHEM Installer im oben erwähnten Developer-Modus das über das Analyseverfahren erzeugte META.json ansehen und dort den entsprechenden prereqs Abschnitt kopieren. Im Grunde werden dort alle "use" und "require" Aufrufe, die ein Modul macht, aufgeführt. Das schließt auch den Aufruf von Perl Builtin Funktionen wie "use strict;" oder ähnliches ein. Es ist empfehlenswert diese hier ebenfalls mit aufzuführen. Über die Metadaten kann man dann auch als FHEM Entwickler entsprechende Statistiken über die Code/Modul Qualität (so man die Nutzung von "use strict;" denn beispielhaft als positiv wirkend interpretieren möchte) fahren.

Hat man das JSON Objekt für sein Modul nun also fertig, dann kopiert man es in seine Moduldatei ''hinter'' den letzten commandRef Abschnitt und ''vor'' der Schlussformel <code>=cut</code>. Dabei wird das META.json Objekt von folgender Markierung umschlossen:

==== META.json Abschnitt ====
<syntaxhighlight lang="perl">
=for :application/json;q=META.json 00_myModule.pm
{ ... }
=end :application/json;q=META.json
</syntaxhighlight>

Dabei ist 00_myModule.pm durch den Dateinamen der jeweiligen Moduldatei zu ersetzen. Auf diese Weise wird sichergestellt, dass eine Metainformation auch wirklich zu genau dieser Moduldatei dazugehört.
Alle Informationen innerhalb des META.json sind im UTF-8 Format. Dies machen wir deshalb zusätzlich nochmals zum Beginn des <code>=pod</code> Abschnitts ''vor'' dem ersten CommandRef Eintrag deutlich:

==== Encoding ====
<syntaxhighlight lang="perl">
=pod

=encoding utf8

...

=cut
</syntaxhighlight>

Ein komplettes Beispiel, wie sich der META.json Abschnitt in eine Moduldatei einfügt, zeigt die Datei [https://svn.fhem.de/trac/browser/trunk/fhem/contrib/META.json.full.txt contrib/META.json.full.txt].
Für Fortgeschrittene sind dort außerdem weitere Beispieleinträge für Metadaten, die der FHEM Installer auswerten und verarbeiten kann.

Hat man nun also den META.json Abschnitt ordnungsgemäß hinzugefügt, kann man mit Hilfe des FHEM Installer überprüfen, ob die Daten richtig hinterlegt worden sind und geladen werden können.

== Eigenständiges Laden der Metadaten aus einem FHEM Modul heraus ==

Ein FHEM Modul kann selbstständig die Unterstützung für das Laden der Metadaten in den %modules Hash einbauen, um diese unabhängig vom FHEM Installer zur Verfügung zu haben.
Hierfür muss am Beginn der Moduldatei zunächst <code>use FHEM::Meta;</code> hinzugefügt werden und die <code>X_Initialize();</code> Funktion am Ende um einen Initialisierungsaufruf erweitert werden:

==== X_Initialize ====
<syntaxhighlight lang="perl">
use FHEM::Meta;

sub X_Initialize($)
{
my ($hash) = @_;
...

return FHEM::Meta::InitMod( __FILE__, $hash );
}
</syntaxhighlight>

Die Metadaten werden dann beim Initialisieren des Moduls nach $modules{<TYPE>}{META} geladen und stehen dort bereit.

== Anzeigen der Modulversion über FHEM::Meta ==

Im META.json Objekt kann eine Version des Moduls explizit in [https://semver.org/ semantischer Form] (beispielsweise v1.2.3) angegeben werden. Ist dies nicht der Fall, dann generiert FHEM::Meta eine eigene Versionsnummer auf Basis der Revisionsnummer aus dem Subversion Repository im <code>$Id$</code> Abschnitt der Moduldatei. Dies gilt jedoch nur für Module, die auch tatsächlich über das SVN verteilt werden, ansonsten wird dieser Abschnitt ignoriert. Durch die Angabe der Versionsnummer im META.json Objekt wird es somit erstmals möglich, dass auch Module außerhalb des SVN mit einer einheitlichen Art der Versionierung auftreten können.
Eine semantische Versionsnummer wird von FHEM::Meta automatisch über die Perl Builtin Module version in einen Float Wert umgewandelt, um nummerische Vergleiche zu ermöglichen.

FHEM::Meta bietet eine Funktion, um die essentiellen Metadaten zum Versionsstand eines Moduls als Internal mit dem Namen FVERSION anzuzeigen. Dafür kann man an den Beginn der <code>X_Define()</code> Funktion folgenden Aufruf setzen:

==== X_Define ====
<syntaxhighlight lang="perl">
sub X_Define($$)
{
my ( $hash, $def ) = @_;
return $@ unless ( FHEM::Meta::SetInternals($hash) );
...

return $error;
}
</syntaxhighlight>

Zum aktuellen Zeitpunkt wird hierdurch lediglich das Internal FVERSION gesetzt. Dieses sieht dann beispielsweise so aus:

<code>
00_myModule.pm:v0.5.6-s19500/2019-05-30
</code>

Als Informationen sind hier verpackt:
* Dateiname des Moduls inkl. Präfix
* semantische Version (= version-Attribut in META.json vorhanden)
* Subversion Revision (-s steht für "Subversion", danach folgt die Revisionsnummer des jeweiligen Commits)
* das Release Datum (hier konkret das Check-in Datum in das SVN)

Für Module außerhalb des SVN werden diese Informationen entsprechend anders zusammengetragen oder müssen/können über das META.json Objekt bereitgestellt werden.
Hierbei ist zu erwähnen, dass ein FHEM Modul erst dann als dem SVN zugehörig angesehen wird, wenn es einen Eintrag in MAINTAINER.txt hat. Fehlt dieser Eintrag, dann wird das Modul nicht als FHEM Core Modul behandelt, sondern als externes 3rd-party Modul.

Meta

2019-07-11T14:35:46Z

Loredo: /* Erweiterung eines FHEM Moduls mit META.json Pod */

= Development Module and Package Meta Data =

== Einleitung ==

Neben den für ein FHEM Modul notwendigen [[DevelopmentModuleIntro|obligatorischen]] Metadaten (CommandRef, Kurzbeschreibung, Typ), gibt es in FHEM das Perl Package FHEM::Meta (oder kurz Meta.pm). Die Einbindung in ein FHEM Modul (= stellt Devices zur Verfügung) oder ein FHEM Package (= stellt Subroutinen für ein oder mehrere FHEM Module bereit) ermöglicht es, Informationen über das Modul in Form eines JSON [https://perldoc.perl.org/perlpod.html Pod] (auch META.json genannt) direkt in die Datei mit einzubetten. Darüber wird es möglich, diese Zusatzinformationen auch bereits auszuwerten und anzuzeigen, ohne dass ein Modul geladen oder verwendet wird. Beispielsweise kann ermittelt werden, welche Perl Module für die Nutzung des Moduls notwendig sind und ob eine bestimmte Version vorausgesetzt wird. Außerdem können Informationen über die Version des Moduls, die Historie, den Autor, für Supportanfragen und vieles weiteres hinterlegt werden.

Das Grundschema für die JSON Struktur basiert dabei auf der offiziellen [https://metacpan.org/pod/CPAN::Meta::Spec CPAN::Meta::Spec] Spezifikation, welche auch bei regulär veröffentlichten Perl Modulen verwendet wird. Das FHEM::Meta Package hilft dabei, diese JSON Informationen aus der Datei auszulesen und stellt diese im globalen %modules Hash des jeweiligen Moduls zur weiteren Verarbeitung bereit. Meta wertet dabei die in der Moduldatei (bei Modulen, die im SVN veröffentlicht sind, auch weitere Informationsquellen/-dateien des SVN) hinterlegten Maintenance und Supportdaten aus, so dass diese Informationen für sämtliche FHEM Module grundsätzlich bereitgestellt werden können. Meta erweitert die Standard Spezifikation dafür mit eigenen JSON Attributen, die spezifikationskonform im Namen mit <code>x_</code> beginnen. Diese Art, zusätzliche Informationen über die Funktionalität eines Modules bereitzustellen, ohne dass ein Modul dafür tatsächlich geladen werden muss, steht jedem Modul als Erweiterung zur Verfügung. Es ist also denkbar, dass Module darüber bekanntmachen, welche Netzwerk-Protokolle sie beherrschen, wie bestimmte Geräte im Netzwerk gefunden werden können und mit welchen define-Parametern ein Gerät in FHEM angelegt werden kann. Hierzu gibt es erste Ansätze, die sich in [https://forum.fhem.de/index.php/topic,67368.0.html Planung] befinden.

== Der FHEM Installer ==

Der FHEM Installer ist ein FHEM Modul, welches ein graphisches Interface für die Metadaten bereitstellt. Mit Hilfe des FHEM Installers werden die Metadaten auch für Module in den Speicher geladen, welche keine explizite Unterstützung eingebaut haben. Sobald man die Informationen für ein bestimmtes Modul oder Package abfragt, wird der Meta-Hash über die Funktion FHEM::Meta::Load() geladen. Für FHEM Module, die beim Start von FHEM bereits in Verwendung sind, werden die Metadaten automatisch im Voraus geladen, so dass sie zur Laufzeit zur Verfügung stehen. Es ist geplant, dass dies auch zur Laufzeit für Module, für die der Benutzer ein neues Device anlegt, geschieht.

Die Grundfunktion des FHEM Installer ist jedoch nicht die Bereitstellung der Metadaten, sondern die Auswertung derselben. In seiner weiteren Entwicklung soll er dabei unterstützen fehlende Systemkomponenten, die für die Nutzung eines FHEM Moduls notwendig sind, zu installieren und aktuell zu halten. Die Installation und Aktualisierung von Perl Modulen ist bereits jetzt in einer ersten Ausbaustufe möglich.

Stellt man am FHEM Installer Device das Attribut <code>installerMode</code> auf developer, dann werden einige weitere Get Befehle sichtbar, über die sich auch der Inhalt des kummulierten META.json Hashes anzeigen lässt. Dies ist oft hilfreich für ein initiales Verständnis, welche Informationen FHEM::Meta bereits über ein Modul gesammelt hat, bevor man diese über einen eigenen META.json Pod in der Moduldatei ergänzen oder verändern möchte.

Hinweis: Die Weiterentwicklung von FHEM::Meta ist stark an die weitere Entwicklung des FHEM Installer geknüpft. Dort geht es dann insbesondere darum, dass FHEM Module aus anderen Installationsquellen neben dem SVN die gleiche Metadaten einliefern können, insbesondere was Versionierung und Historie angehen. Dieses und mehr ist jedoch ein ganz eigenes Kapitel und soll deshalb für das Thema FHEM::Meta nur kurz erwähnt sein.

== Der search-Befehl ==

Der FHEM Befehl <code>search</code> ist ein Wrapper, um den Get-Befehl <code>search</code> beim FHEM Installer Device im Schnellzugriff über die FHEM Befehlszeile aufzurufen. Hierüber lassen sich die Metadaten aller FHEM Module durchsuchen und ermöglicht so das Auffinden von FHEM Modulen für eine bestimmte Funktion oder ein Gebiet. FHEM Module, die einen META.json Pod bereitstellen, können dort Schlagworte hinterlegen, über die das Modul in der Suche gefunden werden können soll. FHEM::Meta generiert für Module, die über das SVN bereitgestellt werden, bereits einige Schlagworte basierend auf dem hinterlegten Support Forum in MAINTAINER.txt. Auch Der Modul Typ (helper|device|command) findet sich als eigenes Schlagwort wieder. Man erhält also Out-of-the-Box bereits eine ziemlich gute Kategorisierung über den Anwendungsbereich eines bestimmten Moduls und welche anderen Module noch in diesen Bereich fallen. Ein Modulname alleine hingegen lässt oftmals nicht auf die Funktionalität dahinter schließen, insbesondere wenn Hersteller- oder Produktnamen eine Rolle spielen, die man selbst bisher nicht kennt.

== Erweiterung eines FHEM Moduls mit META.json Pod ==

Möchte ein Modulautor aktiven Support für FHEM::Meta einbauen, dann ist der erste Schritt die Bereitstellung eines META.json Abschnitts am Ende der Modul- oder Paketdatei. Dieser Abschnitt beinhaltet ein reguläres JSON Objekt. Deshalb empfiehlt es sich den Abschnitt vor dem hinzufügen über einen JSON Validator auf seine Syntax zu überprüfen. Ansonsten wird von FHEM::Meta beim laden eine entsprechende Meldung im FHEM Log ausgegeben und es werden keinerlei Metadaten mehr über das Modul bereitgestellt. Sobald ein META.json Abschnitt vorhanden ist, geht FHEM::Meta davon aus, dass dieses maßgeblich ist und wird deshalb nur noch Daten ergänzen, die dort nicht enthalten sind. Fehlt also ein valides META.json Objekt als Basis, so werden auch diese Ergänzungen nicht erfolgen und der Modulautor muss zunächst zwingend das JSON Gerüst korrigieren.

Für das Hinzufügen des META.json Abschnitts kann man mit der Beispieldatei [https://svn.fhem.de/trac/browser/trunk/fhem/contrib/META.json.txt contrib/META.json.txt] als Ausgangsbasis starten. Die oben erwähnte Spezifikation sollte man einmal gelesen haben um zu verstehen, welches Format für ein Datenfeld gilt und welche Angaben die Spezifikation als zwingend vorschreibt. Es ist empfehlenswert alle dort als ''mandatory'' erwähnten Angaben in META.json anzugeben, auch wenn diese Informationen vielleicht teilweise in anderen Dateien in FHEM bereits vorhanden sind (gilt natürlich nur für Module, die auch über das SVN verteilt werden). Beispielsweise sollte eine (Kurz-)Beschreibung trotzdem enthalten sein. Der Grund ist, dass zumindest theoretisch dann auch andere 3rd-party Tools, die mit Perl Modulen hantieren, diese Informationen in vereinfachter Art ebenfalls auslesen und auswerten können. Diese Tools könnten darauf bestehen, dass sie eben diese als zwingend spezifizierten Attribute dort auch vorfinden. FHEM::Meta fügt fehlende Informationen zwar zur Laufzeit selbst hinzu, dies hilft jedoch anderen Tools, die das JSON Objekt direkt auswerten, eben nicht. Wie genau ein Modulautor dieser Empfehlung folgen möchte, ist ihm überlassen.

Die Inhalte aus der Beispieldatei oben sollten als Mindestvoraussetzung angesehen werden. Insbesondere der Abschnitt <code>prereqs</code> für verwendete Perl Module ist hier wichtig, da das Vorhandensein eines selben eine wesentlich schnellere Ladezeit der Metainformationen zur Folge hat, da die Abhängigkeiten nicht durch eine Analyse erfolgen muss. Das bedeutet jedoch auch, dass diese Informationen vollständig sein müssen und der Autor dafür verantwortlich ist, das diese stimmig sind. Als Hilfestellung, was man hier für sein Modul eintragen sollte, kann man sich über den FHEM Installer im oben erwähnten Developer-Modus das über das Analyseverfahren erzeugte META.json ansehen und dort den entsprechenden prereqs Abschnitt kopieren. Im Grunde werden dort alle "use" und "require" Aufrufe, die ein Modul macht, aufgeführt. Das schließt auch den Aufruf von Perl Builtin Funktionen wie "use strict;" oder ähnliches ein. Es ist empfehlenswert diese hier ebenfalls mit aufzuführen. Über die Metadaten kann man dann auch als FHEM Entwickler entsprechende Statistiken über die Code/Modul Qualität (so man die Nutzung von "use strict;" denn beispielhaft als positiv wirkend interpretieren möchte) fahren.

Hat man das JSON Objekt für sein Modul nun also fertig, dann kopiert man es in seine Moduldatei ''hinter'' den letzten commandRef Abschnitt und ''vor'' der Schlussformel <code>=cut</code>. Dabei wird das META.json Objekt von folgender Markierung umschlossen:

==== META.json Abschnitt ====
<syntaxhighlight lang="perl">
=for :application/json;q=META.json 00_myModule.pm
{ ... }
=end :application/json;q=META.json
</syntaxhighlight>

Dabei ist 00_myModule.pm durch den Dateinamen der jeweiligen Moduldatei zu ersetzen. Auf diese Weise wird sichergestellt, dass eine Metainformation auch wirklich zu genau dieser Moduldatei dazugehört.
Alle Informationen innerhalb des META.json sind im UTF-8 Format. Dies machen wir deshalb zusätzlich nochmals zum Beginn des <code>=pod</code> Abschnitts ''vor'' dem ersten CommandRef Eintrag deutlich:

==== Encoding ====
<syntaxhighlight lang="perl">
=pod

=encoding utf8

=for :application/json;q=META.json 00_myModule.pm
{ ... }
=end :application/json;q=META.json

=cut
</syntaxhighlight>

Ein komplettes Beispiel, wie sich der META.json Abschnitt in eine Moduldatei einfügt, zeigt die Datei [https://svn.fhem.de/trac/browser/trunk/fhem/contrib/META.json.full.txt contrib/META.json.full.txt].
Für Fortgeschrittene sind dort außerdem weitere Beispieleinträge für Metadaten, die der FHEM Installer auswerten und verarbeiten kann.

Hat man nun also den META.json Abschnitt ordnungsgemäß hinzugefügt, kann man mit Hilfe des FHEM Installer überprüfen, ob die Daten richtig hinterlegt worden sind und geladen werden können.

== Eigenständiges Laden der Metadaten aus einem FHEM Modul heraus ==

Ein FHEM Modul kann selbstständig die Unterstützung für das Laden der Metadaten in den %modules Hash einbauen, um diese unabhängig vom FHEM Installer zur Verfügung zu haben.
Hierfür muss am Beginn der Moduldatei zunächst <code>use FHEM::Meta;</code> hinzugefügt werden und die <code>X_Initialize();</code> Funktion am Ende um einen Initialisierungsaufruf erweitert werden:

==== X_Initialize ====
<syntaxhighlight lang="perl">
use FHEM::Meta;

sub X_Initialize($)
{
my ($hash) = @_;
...

return FHEM::Meta::InitMod( __FILE__, $hash );
}
</syntaxhighlight>

Die Metadaten werden dann beim Initialisieren des Moduls nach $modules{<TYPE>}{META} geladen und stehen dort bereit.

== Anzeigen der Modulversion über FHEM::Meta ==

Im META.json Objekt kann eine Version des Moduls explizit in [https://semver.org/ semantischer Form] (beispielsweise v1.2.3) angegeben werden. Ist dies nicht der Fall, dann generiert FHEM::Meta eine eigene Versionsnummer auf Basis der Revisionsnummer aus dem Subversion Repository im <code>$Id$</code> Abschnitt der Moduldatei. Dies gilt jedoch nur für Module, die auch tatsächlich über das SVN verteilt werden, ansonsten wird dieser Abschnitt ignoriert. Durch die Angabe der Versionsnummer im META.json Objekt wird es somit erstmals möglich, dass auch Module außerhalb des SVN mit einer einheitlichen Art der Versionierung auftreten können.
Eine semantische Versionsnummer wird von FHEM::Meta automatisch über die Perl Builtin Module version in einen Float Wert umgewandelt, um nummerische Vergleiche zu ermöglichen.

FHEM::Meta bietet eine Funktion, um die essentiellen Metadaten zum Versionsstand eines Moduls als Internal mit dem Namen FVERSION anzuzeigen. Dafür kann man an den Beginn der <code>X_Define()</code> Funktion folgenden Aufruf setzen:

==== X_Define ====
<syntaxhighlight lang="perl">
sub X_Define($$)
{
my ( $hash, $def ) = @_;
return $@ unless ( FHEM::Meta::SetInternals($hash) );
...

return $error;
}
</syntaxhighlight>

Zum aktuellen Zeitpunkt wird hierdurch lediglich das Internal FVERSION gesetzt. Dieses sieht dann beispielsweise so aus:

<code>
00_myModule.pm:v0.5.6-s19500/2019-05-30
</code>

Als Informationen sind hier verpackt:
* Dateiname des Moduls inkl. Präfix
* semantische Version (= version-Attribut in META.json vorhanden)
* Subversion Revision (-s steht für "Subversion", danach folgt die Revisionsnummer des jeweiligen Commits)
* das Release Datum (hier konkret das Check-in Datum in das SVN)

Für Module außerhalb des SVN werden diese Informationen entsprechend anders zusammengetragen oder müssen/können über das META.json Objekt bereitgestellt werden.
Hierbei ist zu erwähnen, dass ein FHEM Modul erst dann als dem SVN zugehörig angesehen wird, wenn es einen Eintrag in MAINTAINER.txt hat. Fehlt dieser Eintrag, dann wird das Modul nicht als FHEM Core Modul behandelt, sondern als externes 3rd-party Modul.

Meta

2019-07-11T14:34:31Z

Loredo: /* Erweiterung eines FHEM Moduls mit META.json Pod */

= Development Module and Package Meta Data =

== Einleitung ==

Neben den für ein FHEM Modul notwendigen [[DevelopmentModuleIntro|obligatorischen]] Metadaten (CommandRef, Kurzbeschreibung, Typ), gibt es in FHEM das Perl Package FHEM::Meta (oder kurz Meta.pm). Die Einbindung in ein FHEM Modul (= stellt Devices zur Verfügung) oder ein FHEM Package (= stellt Subroutinen für ein oder mehrere FHEM Module bereit) ermöglicht es, Informationen über das Modul in Form eines JSON [https://perldoc.perl.org/perlpod.html Pod] (auch META.json genannt) direkt in die Datei mit einzubetten. Darüber wird es möglich, diese Zusatzinformationen auch bereits auszuwerten und anzuzeigen, ohne dass ein Modul geladen oder verwendet wird. Beispielsweise kann ermittelt werden, welche Perl Module für die Nutzung des Moduls notwendig sind und ob eine bestimmte Version vorausgesetzt wird. Außerdem können Informationen über die Version des Moduls, die Historie, den Autor, für Supportanfragen und vieles weiteres hinterlegt werden.

Das Grundschema für die JSON Struktur basiert dabei auf der offiziellen [https://metacpan.org/pod/CPAN::Meta::Spec CPAN::Meta::Spec] Spezifikation, welche auch bei regulär veröffentlichten Perl Modulen verwendet wird. Das FHEM::Meta Package hilft dabei, diese JSON Informationen aus der Datei auszulesen und stellt diese im globalen %modules Hash des jeweiligen Moduls zur weiteren Verarbeitung bereit. Meta wertet dabei die in der Moduldatei (bei Modulen, die im SVN veröffentlicht sind, auch weitere Informationsquellen/-dateien des SVN) hinterlegten Maintenance und Supportdaten aus, so dass diese Informationen für sämtliche FHEM Module grundsätzlich bereitgestellt werden können. Meta erweitert die Standard Spezifikation dafür mit eigenen JSON Attributen, die spezifikationskonform im Namen mit <code>x_</code> beginnen. Diese Art, zusätzliche Informationen über die Funktionalität eines Modules bereitzustellen, ohne dass ein Modul dafür tatsächlich geladen werden muss, steht jedem Modul als Erweiterung zur Verfügung. Es ist also denkbar, dass Module darüber bekanntmachen, welche Netzwerk-Protokolle sie beherrschen, wie bestimmte Geräte im Netzwerk gefunden werden können und mit welchen define-Parametern ein Gerät in FHEM angelegt werden kann. Hierzu gibt es erste Ansätze, die sich in [https://forum.fhem.de/index.php/topic,67368.0.html Planung] befinden.

== Der FHEM Installer ==

Der FHEM Installer ist ein FHEM Modul, welches ein graphisches Interface für die Metadaten bereitstellt. Mit Hilfe des FHEM Installers werden die Metadaten auch für Module in den Speicher geladen, welche keine explizite Unterstützung eingebaut haben. Sobald man die Informationen für ein bestimmtes Modul oder Package abfragt, wird der Meta-Hash über die Funktion FHEM::Meta::Load() geladen. Für FHEM Module, die beim Start von FHEM bereits in Verwendung sind, werden die Metadaten automatisch im Voraus geladen, so dass sie zur Laufzeit zur Verfügung stehen. Es ist geplant, dass dies auch zur Laufzeit für Module, für die der Benutzer ein neues Device anlegt, geschieht.

Die Grundfunktion des FHEM Installer ist jedoch nicht die Bereitstellung der Metadaten, sondern die Auswertung derselben. In seiner weiteren Entwicklung soll er dabei unterstützen fehlende Systemkomponenten, die für die Nutzung eines FHEM Moduls notwendig sind, zu installieren und aktuell zu halten. Die Installation und Aktualisierung von Perl Modulen ist bereits jetzt in einer ersten Ausbaustufe möglich.

Stellt man am FHEM Installer Device das Attribut <code>installerMode</code> auf developer, dann werden einige weitere Get Befehle sichtbar, über die sich auch der Inhalt des kummulierten META.json Hashes anzeigen lässt. Dies ist oft hilfreich für ein initiales Verständnis, welche Informationen FHEM::Meta bereits über ein Modul gesammelt hat, bevor man diese über einen eigenen META.json Pod in der Moduldatei ergänzen oder verändern möchte.

Hinweis: Die Weiterentwicklung von FHEM::Meta ist stark an die weitere Entwicklung des FHEM Installer geknüpft. Dort geht es dann insbesondere darum, dass FHEM Module aus anderen Installationsquellen neben dem SVN die gleiche Metadaten einliefern können, insbesondere was Versionierung und Historie angehen. Dieses und mehr ist jedoch ein ganz eigenes Kapitel und soll deshalb für das Thema FHEM::Meta nur kurz erwähnt sein.

== Der search-Befehl ==

Der FHEM Befehl <code>search</code> ist ein Wrapper, um den Get-Befehl <code>search</code> beim FHEM Installer Device im Schnellzugriff über die FHEM Befehlszeile aufzurufen. Hierüber lassen sich die Metadaten aller FHEM Module durchsuchen und ermöglicht so das Auffinden von FHEM Modulen für eine bestimmte Funktion oder ein Gebiet. FHEM Module, die einen META.json Pod bereitstellen, können dort Schlagworte hinterlegen, über die das Modul in der Suche gefunden werden können soll. FHEM::Meta generiert für Module, die über das SVN bereitgestellt werden, bereits einige Schlagworte basierend auf dem hinterlegten Support Forum in MAINTAINER.txt. Auch Der Modul Typ (helper|device|command) findet sich als eigenes Schlagwort wieder. Man erhält also Out-of-the-Box bereits eine ziemlich gute Kategorisierung über den Anwendungsbereich eines bestimmten Moduls und welche anderen Module noch in diesen Bereich fallen. Ein Modulname alleine hingegen lässt oftmals nicht auf die Funktionalität dahinter schließen, insbesondere wenn Hersteller- oder Produktnamen eine Rolle spielen, die man selbst bisher nicht kennt.

== Erweiterung eines FHEM Moduls mit META.json Pod ==

Möchte ein Modulautor aktiven Support für FHEM::Meta einbauen, dann ist der erste Schritt die Bereitstellung eines META.json Abschnitts am Ende der Modul- oder Paketdatei. Dieser Abschnitt beinhaltet ein reguläres JSON Objekt. Deshalb empfiehlt es sich den Abschnitt vor dem hinzufügen über einen JSON Validator auf seine Syntax zu überprüfen. Ansonsten wird von FHEM::Meta beim laden eine entsprechende Meldung im FHEM Log ausgegeben und es werden keinerlei Metadaten mehr über das Modul bereitgestellt. Sobald ein META.json Abschnitt vorhanden ist, geht FHEM::Meta davon aus, dass dieses maßgeblich ist und wird deshalb nur noch Daten ergänzen, die dort nicht enthalten sind. Fehlt also ein valides META.json Objekt als Basis, so werden auch diese Ergänzungen nicht erfolgen und der Modulautor muss zunächst zwingend das JSON Gerüst korrigieren.

Für das Hinzufügen des META.json Abschnitts kann man mit der Beispieldatei [https://svn.fhem.de/trac/browser/trunk/fhem/contrib/META.json.txt contrib/META.json.txt] als Ausgangsbasis starten. Die oben erwähnte Spezifikation sollte man einmal gelesen haben um zu verstehen, welches Format für ein Datenfeld gilt und welche Angaben die Spezifikation als zwingend vorschreibt. Es ist empfehlenswert alle dort als ''mandatory'' erwähnten Angaben in META.json anzugeben, auch wenn diese Informationen vielleicht teilweise in anderen Dateien in FHEM bereits vorhanden sind (gilt natürlich nur für Module, die auch über das SVN verteilt werden). Beispielsweise sollte eine (Kurz-)Beschreibung trotzdem enthalten sein. Der Grund ist, dass zumindest theoretisch dann auch andere 3rd-party Tools, die mit Perl Modulen hantieren, diese Informationen in vereinfachter Art ebenfalls auslesen und auswerten können. Diese Tools könnten darauf bestehen, dass sie eben diese als zwingend spezifizierten Attribute dort auch vorfinden. FHEM::Meta fügt fehlende Informationen zwar zur Laufzeit selbst hinzu, dies hilft jedoch anderen Tools, die das JSON Objekt direkt auswerten, eben nicht. Wie genau ein Modulautor dieser Empfehlung folgen möchte, ist ihm überlassen.

Die Inhalte aus der Beispieldatei oben sollten als Mindestvoraussetzung angesehen werden. Insbesondere der Abschnitt <code>prereqs</code> für verwendete Perl Module ist hier wichtig, da das Vorhandensein eines selben eine wesentlich schnellere Ladezeit der Metainformationen zur Folge hat, da die Abhängigkeiten nicht durch eine Analyse erfolgen muss. Das bedeutet jedoch auch, dass diese Informationen vollständig sein müssen und der Autor dafür verantwortlich ist, das diese stimmig sind. Als Hilfestellung, was man hier für sein Modul eintragen sollte, kann man sichüber den FHEM Installer im oben erwähnten Developer-Modus das über das Analyse-Verfahren erzeugte META.json ansehen und dort den entsprechenden prereqs Abschnitt kopieren. Im Grunde werden dort alle "use" und "require" Aufrufe, die ein Modul macht, aufgeführt. Das schließt auch den Aufruf von Perl Builtin Funktionen wie "use strict;" oder ähnliches ein. Es ist empfehlenswert diese hier ebenfalls mit aufzuführen. Über die Metadaten kann man dann auch als FHEM Entwickler entsprechende Statistiken über die Code/Modul Qualität (so man die Nutzung von "use strict;" denn beispielhaft als positiv wirkend interpretieren möchte) fahren.

Hat man das JSON Objekt für sein Modul nun also fertig, dann kopiert man es in seine Moduldatei ''hinter'' den letzten commandRef Abschnitt und ''vor'' der Schlussformel <code>=cut</code>. Dabei wird das META.json Objekt von folgender Markierung umschlossen:

==== META.json Abschnitt ====
<syntaxhighlight lang="perl">
=for :application/json;q=META.json 00_myModule.pm
{ ... }
=end :application/json;q=META.json
</syntaxhighlight>

Dabei ist 00_myModule.pm durch den Dateinamen der jeweiligen Moduldatei zu ersetzen. Auf diese Weise wird sichergestellt, dass eine Metainformation auch wirklich zu genau dieser Moduldatei dazugehört.
Alle Informationen innerhalb des META.json sind im UTF-8 Format. Dies machen wir deshalb zusätzlich nochmals zum Beginn des <code>=pod</code> Abschnitts ''vor'' dem ersten CommandRef Eintrag deutlich:

==== Encoding ====
<syntaxhighlight lang="perl">
=pod

=encoding utf8

=for :application/json;q=META.json 00_myModule.pm
{ ... }
=end :application/json;q=META.json

=cut
</syntaxhighlight>

Ein komplettes Beispiel, wie sich der META.json Abschnitt in eine Moduldatei einfügt, zeigt die Datei [https://svn.fhem.de/trac/browser/trunk/fhem/contrib/META.json.full.txt contrib/META.json.full.txt].
Für Fortgeschrittene sind dort außerdem weitere Beispieleinträge für Metadaten, die der FHEM Installer auswerten und verarbeiten kann.

Hat man nun also den META.json Abschnitt ordnungsgemäß hinzugefügt, kann man mit Hilfe des FHEM Installer überprüfen, ob die Daten richtig hinterlegt worden sind und geladen werden können.

== Eigenständiges Laden der Metadaten aus einem FHEM Modul heraus ==

Ein FHEM Modul kann selbstständig die Unterstützung für das Laden der Metadaten in den %modules Hash einbauen, um diese unabhängig vom FHEM Installer zur Verfügung zu haben.
Hierfür muss am Beginn der Moduldatei zunächst <code>use FHEM::Meta;</code> hinzugefügt werden und die <code>X_Initialize();</code> Funktion am Ende um einen Initialisierungsaufruf erweitert werden:

==== X_Initialize ====
<syntaxhighlight lang="perl">
use FHEM::Meta;

sub X_Initialize($)
{
my ($hash) = @_;
...

return FHEM::Meta::InitMod( __FILE__, $hash );
}
</syntaxhighlight>

Die Metadaten werden dann beim Initialisieren des Moduls nach $modules{<TYPE>}{META} geladen und stehen dort bereit.

== Anzeigen der Modulversion über FHEM::Meta ==

Im META.json Objekt kann eine Version des Moduls explizit in [https://semver.org/ semantischer Form] (beispielsweise v1.2.3) angegeben werden. Ist dies nicht der Fall, dann generiert FHEM::Meta eine eigene Versionsnummer auf Basis der Revisionsnummer aus dem Subversion Repository im <code>$Id$</code> Abschnitt der Moduldatei. Dies gilt jedoch nur für Module, die auch tatsächlich über das SVN verteilt werden, ansonsten wird dieser Abschnitt ignoriert. Durch die Angabe der Versionsnummer im META.json Objekt wird es somit erstmals möglich, dass auch Module außerhalb des SVN mit einer einheitlichen Art der Versionierung auftreten können.
Eine semantische Versionsnummer wird von FHEM::Meta automatisch über die Perl Builtin Module version in einen Float Wert umgewandelt, um nummerische Vergleiche zu ermöglichen.

FHEM::Meta bietet eine Funktion, um die essentiellen Metadaten zum Versionsstand eines Moduls als Internal mit dem Namen FVERSION anzuzeigen. Dafür kann man an den Beginn der <code>X_Define()</code> Funktion folgenden Aufruf setzen:

==== X_Define ====
<syntaxhighlight lang="perl">
sub X_Define($$)
{
my ( $hash, $def ) = @_;
return $@ unless ( FHEM::Meta::SetInternals($hash) );
...

return $error;
}
</syntaxhighlight>

Zum aktuellen Zeitpunkt wird hierdurch lediglich das Internal FVERSION gesetzt. Dieses sieht dann beispielsweise so aus:

<code>
00_myModule.pm:v0.5.6-s19500/2019-05-30
</code>

Als Informationen sind hier verpackt:
* Dateiname des Moduls inkl. Präfix
* semantische Version (= version-Attribut in META.json vorhanden)
* Subversion Revision (-s steht für "Subversion", danach folgt die Revisionsnummer des jeweiligen Commits)
* das Release Datum (hier konkret das Check-in Datum in das SVN)

Für Module außerhalb des SVN werden diese Informationen entsprechend anders zusammengetragen oder müssen/können über das META.json Objekt bereitgestellt werden.
Hierbei ist zu erwähnen, dass ein FHEM Modul erst dann als dem SVN zugehörig angesehen wird, wenn es einen Eintrag in MAINTAINER.txt hat. Fehlt dieser Eintrag, dann wird das Modul nicht als FHEM Core Modul behandelt, sondern als externes 3rd-party Modul.

Meta

2019-07-11T14:32:36Z

Loredo: /* Erweiterung eines FHEM Moduls mit META.json Pod */

= Development Module and Package Meta Data =

== Einleitung ==

Neben den für ein FHEM Modul notwendigen [[DevelopmentModuleIntro|obligatorischen]] Metadaten (CommandRef, Kurzbeschreibung, Typ), gibt es in FHEM das Perl Package FHEM::Meta (oder kurz Meta.pm). Die Einbindung in ein FHEM Modul (= stellt Devices zur Verfügung) oder ein FHEM Package (= stellt Subroutinen für ein oder mehrere FHEM Module bereit) ermöglicht es, Informationen über das Modul in Form eines JSON [https://perldoc.perl.org/perlpod.html Pod] (auch META.json genannt) direkt in die Datei mit einzubetten. Darüber wird es möglich, diese Zusatzinformationen auch bereits auszuwerten und anzuzeigen, ohne dass ein Modul geladen oder verwendet wird. Beispielsweise kann ermittelt werden, welche Perl Module für die Nutzung des Moduls notwendig sind und ob eine bestimmte Version vorausgesetzt wird. Außerdem können Informationen über die Version des Moduls, die Historie, den Autor, für Supportanfragen und vieles weiteres hinterlegt werden.

Das Grundschema für die JSON Struktur basiert dabei auf der offiziellen [https://metacpan.org/pod/CPAN::Meta::Spec CPAN::Meta::Spec] Spezifikation, welche auch bei regulär veröffentlichten Perl Modulen verwendet wird. Das FHEM::Meta Package hilft dabei, diese JSON Informationen aus der Datei auszulesen und stellt diese im globalen %modules Hash des jeweiligen Moduls zur weiteren Verarbeitung bereit. Meta wertet dabei die in der Moduldatei (bei Modulen, die im SVN veröffentlicht sind, auch weitere Informationsquellen/-dateien des SVN) hinterlegten Maintenance und Supportdaten aus, so dass diese Informationen für sämtliche FHEM Module grundsätzlich bereitgestellt werden können. Meta erweitert die Standard Spezifikation dafür mit eigenen JSON Attributen, die spezifikationskonform im Namen mit <code>x_</code> beginnen. Diese Art, zusätzliche Informationen über die Funktionalität eines Modules bereitzustellen, ohne dass ein Modul dafür tatsächlich geladen werden muss, steht jedem Modul als Erweiterung zur Verfügung. Es ist also denkbar, dass Module darüber bekanntmachen, welche Netzwerk-Protokolle sie beherrschen, wie bestimmte Geräte im Netzwerk gefunden werden können und mit welchen define-Parametern ein Gerät in FHEM angelegt werden kann. Hierzu gibt es erste Ansätze, die sich in [https://forum.fhem.de/index.php/topic,67368.0.html Planung] befinden.

== Der FHEM Installer ==

Der FHEM Installer ist ein FHEM Modul, welches ein graphisches Interface für die Metadaten bereitstellt. Mit Hilfe des FHEM Installers werden die Metadaten auch für Module in den Speicher geladen, welche keine explizite Unterstützung eingebaut haben. Sobald man die Informationen für ein bestimmtes Modul oder Package abfragt, wird der Meta-Hash über die Funktion FHEM::Meta::Load() geladen. Für FHEM Module, die beim Start von FHEM bereits in Verwendung sind, werden die Metadaten automatisch im Voraus geladen, so dass sie zur Laufzeit zur Verfügung stehen. Es ist geplant, dass dies auch zur Laufzeit für Module, für die der Benutzer ein neues Device anlegt, geschieht.

Die Grundfunktion des FHEM Installer ist jedoch nicht die Bereitstellung der Metadaten, sondern die Auswertung derselben. In seiner weiteren Entwicklung soll er dabei unterstützen fehlende Systemkomponenten, die für die Nutzung eines FHEM Moduls notwendig sind, zu installieren und aktuell zu halten. Die Installation und Aktualisierung von Perl Modulen ist bereits jetzt in einer ersten Ausbaustufe möglich.

Stellt man am FHEM Installer Device das Attribut <code>installerMode</code> auf developer, dann werden einige weitere Get Befehle sichtbar, über die sich auch der Inhalt des kummulierten META.json Hashes anzeigen lässt. Dies ist oft hilfreich für ein initiales Verständnis, welche Informationen FHEM::Meta bereits über ein Modul gesammelt hat, bevor man diese über einen eigenen META.json Pod in der Moduldatei ergänzen oder verändern möchte.

Hinweis: Die Weiterentwicklung von FHEM::Meta ist stark an die weitere Entwicklung des FHEM Installer geknüpft. Dort geht es dann insbesondere darum, dass FHEM Module aus anderen Installationsquellen neben dem SVN die gleiche Metadaten einliefern können, insbesondere was Versionierung und Historie angehen. Dieses und mehr ist jedoch ein ganz eigenes Kapitel und soll deshalb für das Thema FHEM::Meta nur kurz erwähnt sein.

== Der search-Befehl ==

Der FHEM Befehl <code>search</code> ist ein Wrapper, um den Get-Befehl <code>search</code> beim FHEM Installer Device im Schnellzugriff über die FHEM Befehlszeile aufzurufen. Hierüber lassen sich die Metadaten aller FHEM Module durchsuchen und ermöglicht so das Auffinden von FHEM Modulen für eine bestimmte Funktion oder ein Gebiet. FHEM Module, die einen META.json Pod bereitstellen, können dort Schlagworte hinterlegen, über die das Modul in der Suche gefunden werden können soll. FHEM::Meta generiert für Module, die über das SVN bereitgestellt werden, bereits einige Schlagworte basierend auf dem hinterlegten Support Forum in MAINTAINER.txt. Auch Der Modul Typ (helper|device|command) findet sich als eigenes Schlagwort wieder. Man erhält also Out-of-the-Box bereits eine ziemlich gute Kategorisierung über den Anwendungsbereich eines bestimmten Moduls und welche anderen Module noch in diesen Bereich fallen. Ein Modulname alleine hingegen lässt oftmals nicht auf die Funktionalität dahinter schließen, insbesondere wenn Hersteller- oder Produktnamen eine Rolle spielen, die man selbst bisher nicht kennt.

== Erweiterung eines FHEM Moduls mit META.json Pod ==

Möchte ein Modulautor aktiven Support für FHEM::Meta einbauen, dann ist der erste Schritt die Bereitstellung eines META.json Abschnitts am Ende der Modul- oder Paketdatei. Dieser Abschnitt beinhaltet ein reguläres JSON Objekt. Deshalb empfiehlt es sich den Abschnitt vor dem hinzufügen über einen JSON Validator auf seine Syntax zu überprüfen. Ansonsten wird von FHEM::Meta beim laden eine entsprechende Meldung im FHEM Log ausgegeben und es werden keinerlei Metadaten mehr über das Modul bereitgestellt. Sobald ein META.json Abschnitt vorhanden ist, geht FHEM::Meta davon aus, dass dieses maßgeblich ist und wird deshalb nur noch Daten ergänzen, die dort nicht enthalten sind. Fehlt also ein valides META.json Objekt als Basis, so werden auch diese Ergänzungen nicht erfolgen und der Modulautor muss zunächst zwingend das JSON Gerüst korrigieren.

Für das Hinzufügen des META.json Abschnitts kann man mit der Beispieldatei [https://svn.fhem.de/trac/browser/trunk/fhem/contrib/META.json.txt contrib/META.json.txt] als Ausgangsbasis starten. Die oben erwähnte Spezifikation sollte man einmal gelesen haben um zu verstehen, welches Format für ein Datenfeld gilt und welche Angaben die Spezifikation als zwingend vorschreibt. Es ist empfehlenswert alle dort als ''mandatory'' erwähnten Angaben in META.json anzugeben, auch wenn diese Informationen vielleicht teilweise in anderen Dateien in FHEM bereits vorhanden sind (gilt natürlich nur für Module, die auch über das SVN verteilt werden). Beispielsweise sollte eine (Kurz-)Beschreibung trotzdem enthalten sein. Der Grund ist, dass zumindest theoretisch dann auch andere 3rd-party Tools, die mit Perl Modulen hantieren, diese Informationen in vereinfachter Art ebenfalls auslesen und auswerten können. Diese Tools könnten darauf bestehen, dass sie eben diese als zwingend spezifizierten Attribute dort auch vorfinden. FHEM::Meta fügt fehlende Informationen zwar zur Laufzeit selbst hinzu, dies hilt jedoch anderen Tools, die das JSON Objekt direkt auswerten, eben nicht. Wie genau ein Modulautor dieser Empfehlung folgen möchte, ist ihm überlassen.

Die Inhalte aus der Beispieldatei oben sollten als Mindestvoraussetzung angesehen werden. Insbesondere der Abschnitt <code>prereqs</code> für verwendete Perl Module ist hier wichtig, da das Vorhandensein eines selben eine wesentlich schnellere Ladezeit der Metainformationen zur Folge hat, da die Abhängigkeiten nicht durch eine Analyse erfolgen muss. Das bedeutet jedoch auch, dass diese Informationen vollständig sein müssen und der Autor dafür verantwortlich ist, das diese stimmig sind. Als Hilfestellung, was man hier für sein Modul eintragen sollte, kann man sichüber den FHEM Installer im oben erwähnten Developer-Modus das über das Analyse-Verfahren erzeugte META.json ansehen und dort den entsprechenden prereqs Abschnitt kopieren. Im Grunde werden dort alle "use" und "require" Aufrufe, die ein Modul macht, aufgeführt. Das schließt auch den Aufruf von Perl Builtin Funktionen wie "use strict;" oder ähnliches ein. Es ist empfehlenswert diese hier ebenfalls mit aufzuführen. Über die Metadaten kann man dann auch als FHEM Entwickler entsprechende Statistiken über die Code/Modul Qualität (so man die Nutzung von "use strict;" denn beispielhaft als positiv wirkend interpretieren möchte) fahren.

Hat man das JSON Objekt für sein Modul nun also fertig, dann kopiert man es in seine Moduldatei ''hinter'' den letzten commandRef Abschnitt und ''vor'' der Schlussformel <code>=cut</code>. Dabei wird das META.json Objekt von folgender Markierung umschlossen:

==== META.json Abschnitt ====
<syntaxhighlight lang="perl">
=for :application/json;q=META.json 00_myModule.pm
{ ... }
=end :application/json;q=META.json
</syntaxhighlight>

Dabei ist 00_myModule.pm durch den Dateinamen der jeweiligen Moduldatei zu ersetzen. Auf diese Weise wird sichergestellt, dass eine Metainformation auch wirklich zu genau dieser Moduldatei dazugehört.
Alle Informationen innerhalb des META.json sind im UTF-8 Format. Dies machen wir deshalb zusätzlich nochmals zum Beginn des <code>=pod</code> Abschnitts ''vor'' dem ersten CommandRef Eintrag deutlich:

==== Encoding ====
<syntaxhighlight lang="perl">
=pod

=encoding utf8

=for :application/json;q=META.json 00_myModule.pm
{ ... }
=end :application/json;q=META.json

=cut
</syntaxhighlight>

Ein komplettes Beispiel, wie sich der META.json Abschnitt in eine Moduldatei einfügt, zeigt die Datei [https://svn.fhem.de/trac/browser/trunk/fhem/contrib/META.json.full.txt contrib/META.json.full.txt].
Für Fortgeschrittene sind dort außerdem weitere Beispieleinträge für Metadaten, die der FHEM Installer auswerten und verarbeiten kann.

Hat man nun also den META.json Abschnitt ordnungsgemäß hinzugefügt, kann man mit Hilfe des FHEM Installer überprüfen, ob die Daten richtig hinterlegt worden sind und geladen werden können.

== Eigenständiges Laden der Metadaten aus einem FHEM Modul heraus ==

Ein FHEM Modul kann selbstständig die Unterstützung für das Laden der Metadaten in den %modules Hash einbauen, um diese unabhängig vom FHEM Installer zur Verfügung zu haben.
Hierfür muss am Beginn der Moduldatei zunächst <code>use FHEM::Meta;</code> hinzugefügt werden und die <code>X_Initialize();</code> Funktion am Ende um einen Initialisierungsaufruf erweitert werden:

==== X_Initialize ====
<syntaxhighlight lang="perl">
use FHEM::Meta;

sub X_Initialize($)
{
my ($hash) = @_;
...

return FHEM::Meta::InitMod( __FILE__, $hash );
}
</syntaxhighlight>

Die Metadaten werden dann beim Initialisieren des Moduls nach $modules{<TYPE>}{META} geladen und stehen dort bereit.

== Anzeigen der Modulversion über FHEM::Meta ==

Im META.json Objekt kann eine Version des Moduls explizit in [https://semver.org/ semantischer Form] (beispielsweise v1.2.3) angegeben werden. Ist dies nicht der Fall, dann generiert FHEM::Meta eine eigene Versionsnummer auf Basis der Revisionsnummer aus dem Subversion Repository im <code>$Id$</code> Abschnitt der Moduldatei. Dies gilt jedoch nur für Module, die auch tatsächlich über das SVN verteilt werden, ansonsten wird dieser Abschnitt ignoriert. Durch die Angabe der Versionsnummer im META.json Objekt wird es somit erstmals möglich, dass auch Module außerhalb des SVN mit einer einheitlichen Art der Versionierung auftreten können.
Eine semantische Versionsnummer wird von FHEM::Meta automatisch über die Perl Builtin Module version in einen Float Wert umgewandelt, um nummerische Vergleiche zu ermöglichen.

FHEM::Meta bietet eine Funktion, um die essentiellen Metadaten zum Versionsstand eines Moduls als Internal mit dem Namen FVERSION anzuzeigen. Dafür kann man an den Beginn der <code>X_Define()</code> Funktion folgenden Aufruf setzen:

==== X_Define ====
<syntaxhighlight lang="perl">
sub X_Define($$)
{
my ( $hash, $def ) = @_;
return $@ unless ( FHEM::Meta::SetInternals($hash) );
...

return $error;
}
</syntaxhighlight>

Zum aktuellen Zeitpunkt wird hierdurch lediglich das Internal FVERSION gesetzt. Dieses sieht dann beispielsweise so aus:

<code>
00_myModule.pm:v0.5.6-s19500/2019-05-30
</code>

Als Informationen sind hier verpackt:
* Dateiname des Moduls inkl. Präfix
* semantische Version (= version-Attribut in META.json vorhanden)
* Subversion Revision (-s steht für "Subversion", danach folgt die Revisionsnummer des jeweiligen Commits)
* das Release Datum (hier konkret das Check-in Datum in das SVN)

Für Module außerhalb des SVN werden diese Informationen entsprechend anders zusammengetragen oder müssen/können über das META.json Objekt bereitgestellt werden.
Hierbei ist zu erwähnen, dass ein FHEM Modul erst dann als dem SVN zugehörig angesehen wird, wenn es einen Eintrag in MAINTAINER.txt hat. Fehlt dieser Eintrag, dann wird das Modul nicht als FHEM Core Modul behandelt, sondern als externes 3rd-party Modul.

Meta

2019-07-11T14:29:30Z

Loredo: /* Einleitung */

= Development Module and Package Meta Data =

== Einleitung ==

Neben den für ein FHEM Modul notwendigen [[DevelopmentModuleIntro|obligatorischen]] Metadaten (CommandRef, Kurzbeschreibung, Typ), gibt es in FHEM das Perl Package FHEM::Meta (oder kurz Meta.pm). Die Einbindung in ein FHEM Modul (= stellt Devices zur Verfügung) oder ein FHEM Package (= stellt Subroutinen für ein oder mehrere FHEM Module bereit) ermöglicht es, Informationen über das Modul in Form eines JSON [https://perldoc.perl.org/perlpod.html Pod] (auch META.json genannt) direkt in die Datei mit einzubetten. Darüber wird es möglich, diese Zusatzinformationen auch bereits auszuwerten und anzuzeigen, ohne dass ein Modul geladen oder verwendet wird. Beispielsweise kann ermittelt werden, welche Perl Module für die Nutzung des Moduls notwendig sind und ob eine bestimmte Version vorausgesetzt wird. Außerdem können Informationen über die Version des Moduls, die Historie, den Autor, für Supportanfragen und vieles weiteres hinterlegt werden.

Das Grundschema für die JSON Struktur basiert dabei auf der offiziellen [https://metacpan.org/pod/CPAN::Meta::Spec CPAN::Meta::Spec] Spezifikation, welche auch bei regulär veröffentlichten Perl Modulen verwendet wird. Das FHEM::Meta Package hilft dabei, diese JSON Informationen aus der Datei auszulesen und stellt diese im globalen %modules Hash des jeweiligen Moduls zur weiteren Verarbeitung bereit. Meta wertet dabei die in der Moduldatei (bei Modulen, die im SVN veröffentlicht sind, auch weitere Informationsquellen/-dateien des SVN) hinterlegten Maintenance und Supportdaten aus, so dass diese Informationen für sämtliche FHEM Module grundsätzlich bereitgestellt werden können. Meta erweitert die Standard Spezifikation dafür mit eigenen JSON Attributen, die spezifikationskonform im Namen mit <code>x_</code> beginnen. Diese Art, zusätzliche Informationen über die Funktionalität eines Modules bereitzustellen, ohne dass ein Modul dafür tatsächlich geladen werden muss, steht jedem Modul als Erweiterung zur Verfügung. Es ist also denkbar, dass Module darüber bekanntmachen, welche Netzwerk-Protokolle sie beherrschen, wie bestimmte Geräte im Netzwerk gefunden werden können und mit welchen define-Parametern ein Gerät in FHEM angelegt werden kann. Hierzu gibt es erste Ansätze, die sich in [https://forum.fhem.de/index.php/topic,67368.0.html Planung] befinden.

== Der FHEM Installer ==

Der FHEM Installer ist ein FHEM Modul, welches ein graphisches Interface für die Metadaten bereitstellt. Mit Hilfe des FHEM Installers werden die Metadaten auch für Module in den Speicher geladen, welche keine explizite Unterstützung eingebaut haben. Sobald man die Informationen für ein bestimmtes Modul oder Package abfragt, wird der Meta-Hash über die Funktion FHEM::Meta::Load() geladen. Für FHEM Module, die beim Start von FHEM bereits in Verwendung sind, werden die Metadaten automatisch im Voraus geladen, so dass sie zur Laufzeit zur Verfügung stehen. Es ist geplant, dass dies auch zur Laufzeit für Module, für die der Benutzer ein neues Device anlegt, geschieht.

Die Grundfunktion des FHEM Installer ist jedoch nicht die Bereitstellung der Metadaten, sondern die Auswertung derselben. In seiner weiteren Entwicklung soll er dabei unterstützen fehlende Systemkomponenten, die für die Nutzung eines FHEM Moduls notwendig sind, zu installieren und aktuell zu halten. Die Installation und Aktualisierung von Perl Modulen ist bereits jetzt in einer ersten Ausbaustufe möglich.

Stellt man am FHEM Installer Device das Attribut <code>installerMode</code> auf developer, dann werden einige weitere Get Befehle sichtbar, über die sich auch der Inhalt des kummulierten META.json Hashes anzeigen lässt. Dies ist oft hilfreich für ein initiales Verständnis, welche Informationen FHEM::Meta bereits über ein Modul gesammelt hat, bevor man diese über einen eigenen META.json Pod in der Moduldatei ergänzen oder verändern möchte.

Hinweis: Die Weiterentwicklung von FHEM::Meta ist stark an die weitere Entwicklung des FHEM Installer geknüpft. Dort geht es dann insbesondere darum, dass FHEM Module aus anderen Installationsquellen neben dem SVN die gleiche Metadaten einliefern können, insbesondere was Versionierung und Historie angehen. Dieses und mehr ist jedoch ein ganz eigenes Kapitel und soll deshalb für das Thema FHEM::Meta nur kurz erwähnt sein.

== Der search-Befehl ==

Der FHEM Befehl <code>search</code> ist ein Wrapper, um den Get-Befehl <code>search</code> beim FHEM Installer Device im Schnellzugriff über die FHEM Befehlszeile aufzurufen. Hierüber lassen sich die Metadaten aller FHEM Module durchsuchen und ermöglicht so das Auffinden von FHEM Modulen für eine bestimmte Funktion oder ein Gebiet. FHEM Module, die einen META.json Pod bereitstellen, können dort Schlagworte hinterlegen, über die das Modul in der Suche gefunden werden können soll. FHEM::Meta generiert für Module, die über das SVN bereitgestellt werden, bereits einige Schlagworte basierend auf dem hinterlegten Support Forum in MAINTAINER.txt. Auch Der Modul Typ (helper|device|command) findet sich als eigenes Schlagwort wieder. Man erhält also Out-of-the-Box bereits eine ziemlich gute Kategorisierung über den Anwendungsbereich eines bestimmten Moduls und welche anderen Module noch in diesen Bereich fallen. Ein Modulname alleine hingegen lässt oftmals nicht auf die Funktionalität dahinter schließen, insbesondere wenn Hersteller- oder Produktnamen eine Rolle spielen, die man selbst bisher nicht kennt.

== Erweiterung eines FHEM Moduls mit META.json Pod ==

Möchte ein Modulautor aktiven Support FHEM::Meta einbauen, dann ist der erste Schritt die Bereitstellung eines META.json Abschnitts am Ende der Modul- oder Paketdatei. Dieser Abschnitt beinhaltet ein reguläres JSON Objekt. Deshalb empfiehlt es sich den Abschnitt vor dem hinzufügen über einen JSON Validator auf seine Syntax zu überprüfen. Ansonsten wird von FHEM::Meta beim laden eine entsprechende Meldung im FHEM Log ausgegeben und es werden keinerlei Metadaten mehr über das Modul bereitgestellt. Sobald ein META.json Abschnitt vorhanden ist, geht FHEM::Meta davon aus, dass dieses maßgeblich ist und wird deshalb nur noch Daten ergänzen, die dort nicht enthalten sind. Fehlt also ein valides META.json Objekt als Basis, so werden auch diese Ergänzungen nicht erfolgen und der Modulautor muss zunächst zwingend das JSON Gerüst korrigieren.

Für das Hinzufügen des META.json Abschnitts kann man mit der Beispieldatei [https://svn.fhem.de/trac/browser/trunk/fhem/contrib/META.json.txt contrib/META.json.txt] als Ausgangsbasis starten. Die oben erwähnte Spezifikation sollte man einmal gelesen haben um zu verstehen, welches Format für ein Datenfeld gilt und welche Angaben die Spezifikation als zwingend vorschreibt. Es ist empfehlenswert alle dort als ''mandatory'' erwähnten Angaben in META.json anzugeben, auch wenn diese Informationen vielleicht teilweise in anderen Dateien in FHEM bereits vorhanden sind (gilt natürlich nur für Module, die auch über das SVN verteilt werden). Beispielsweise sollte eine (Kurz-)Beschreibung trotzdem enthalten sein. Der Grund ist, dass zumindest theoretisch dann auch andere 3rd-party Tools, die mit Perl Modulen hantieren, diese Informationen in vereinfachter Art ebenfalls auslesen und auswerten können. Diese Tools könnten darauf bestehen, dass sie eben diese als zwingend spezifizierten Attribute dort auch vorfinden. FHEM::Meta fügt fehlende Informationen zwar zur Laufzeit selbst hinzu, dies hilt jedoch anderen Tools, die das JSON Objekt direkt auswerten, eben nicht. Wie genau ein Modulautor dieser Empfehlung folgen möchte, ist ihm überlassen.

Die Inhalte aus der Beispieldatei oben sollten als Mindestvoraussetzung angesehen werden. Insbesondere der Abschnitt <code>prereqs</code> für verwendete Perl Module ist hier wichtig, da das Vorhandensein eines selben eine wesentlich schnellere Ladezeit der Metainformationen zur Folge hat, da die Abhängigkeiten nicht durch eine Analyse erfolgen muss. Das bedeutet jedoch auch, dass diese Informationen vollständig sein müssen und der Autor dafür verantwortlich ist, das diese stimmig sind. Als Hilfestellung, was man hier für sein Modul eintragen sollte, kann man sichüber den FHEM Installer im oben erwähnten Developer-Modus das über das Analyse-Verfahren erzeugte META.json ansehen und dort den entsprechenden prereqs Abschnitt kopieren. Im Grunde werden dort alle "use" und "require" Aufrufe, die ein Modul macht, aufgeführt. Das schließt auch den Aufruf von Perl Builtin Funktionen wie "use strict;" oder ähnliches ein. Es ist empfehlenswert diese hier ebenfalls mit aufzuführen. Über die Metadaten kann man dann auch als FHEM Entwickler entsprechende Statistiken über die Code/Modul Qualität (so man die Nutzung von "use strict;" denn beispielhaft als positiv wirkend interpretieren möchte) fahren.

Hat man das JSON Objekt für sein Modul nun also fertig, dann kopiert man es in seine Moduldatei ''hinter'' den letzten commandRef Abschnitt und ''vor'' der Schlussformel <code>=cut</code>. Dabei wird das META.json Objekt von folgender Markierung umschlossen:

==== META.json Abschnitt ====
<syntaxhighlight lang="perl">
=for :application/json;q=META.json 00_myModule.pm
{ ... }
=end :application/json;q=META.json
</syntaxhighlight>

Dabei ist 00_myModule.pm durch den Dateinamen der jeweiligen Moduldatei zu ersetzen. Auf diese Weise wird sichergestellt, dass eine Metainformation auch wirklich zu genau dieser Moduldatei dazugehört.
Alle Informationen innerhalb des META.json sind im UTF-8 Format. Dies machen wir deshalb zusätzlich nochmals zum Beginn des <code>=pod</code> Abschnitts ''vor'' dem ersten CommandRef Eintrag deutlich:

==== Encoding ====
<syntaxhighlight lang="perl">
=pod

=encoding utf8

=for :application/json;q=META.json 00_myModule.pm
{ ... }
=end :application/json;q=META.json

=cut
</syntaxhighlight>

Ein komplettes Beispiel, wie sich der META.json Abschnitt in eine Moduldatei einfügt, zeigt die Datei [https://svn.fhem.de/trac/browser/trunk/fhem/contrib/META.json.full.txt contrib/META.json.full.txt].
Für Fortgeschrittene sind dort außerdem weitere Beispieleinträge für Metadaten, die der FHEM Installer auswerten und verarbeiten kann.

Hat man nun also den META.json Abschnitt ordnungsgemäß hinzugefügt, kann man mit Hilfe des FHEM Installer überprüfen, ob die Daten richtig hinterlegt worden sind und geladen werden können.

== Eigenständiges Laden der Metadaten aus einem FHEM Modul heraus ==

Ein FHEM Modul kann selbstständig die Unterstützung für das Laden der Metadaten in den %modules Hash einbauen, um diese unabhängig vom FHEM Installer zur Verfügung zu haben.
Hierfür muss am Beginn der Moduldatei zunächst <code>use FHEM::Meta;</code> hinzugefügt werden und die <code>X_Initialize();</code> Funktion am Ende um einen Initialisierungsaufruf erweitert werden:

==== X_Initialize ====
<syntaxhighlight lang="perl">
use FHEM::Meta;

sub X_Initialize($)
{
my ($hash) = @_;
...

return FHEM::Meta::InitMod( __FILE__, $hash );
}
</syntaxhighlight>

Die Metadaten werden dann beim Initialisieren des Moduls nach $modules{<TYPE>}{META} geladen und stehen dort bereit.

== Anzeigen der Modulversion über FHEM::Meta ==

Im META.json Objekt kann eine Version des Moduls explizit in [https://semver.org/ semantischer Form] (beispielsweise v1.2.3) angegeben werden. Ist dies nicht der Fall, dann generiert FHEM::Meta eine eigene Versionsnummer auf Basis der Revisionsnummer aus dem Subversion Repository im <code>$Id$</code> Abschnitt der Moduldatei. Dies gilt jedoch nur für Module, die auch tatsächlich über das SVN verteilt werden, ansonsten wird dieser Abschnitt ignoriert. Durch die Angabe der Versionsnummer im META.json Objekt wird es somit erstmals möglich, dass auch Module außerhalb des SVN mit einer einheitlichen Art der Versionierung auftreten können.
Eine semantische Versionsnummer wird von FHEM::Meta automatisch über die Perl Builtin Module version in einen Float Wert umgewandelt, um nummerische Vergleiche zu ermöglichen.

FHEM::Meta bietet eine Funktion, um die essentiellen Metadaten zum Versionsstand eines Moduls als Internal mit dem Namen FVERSION anzuzeigen. Dafür kann man an den Beginn der <code>X_Define()</code> Funktion folgenden Aufruf setzen:

==== X_Define ====
<syntaxhighlight lang="perl">
sub X_Define($$)
{
my ( $hash, $def ) = @_;
return $@ unless ( FHEM::Meta::SetInternals($hash) );
...

return $error;
}
</syntaxhighlight>

Zum aktuellen Zeitpunkt wird hierdurch lediglich das Internal FVERSION gesetzt. Dieses sieht dann beispielsweise so aus:

<code>
00_myModule.pm:v0.5.6-s19500/2019-05-30
</code>

Als Informationen sind hier verpackt:
* Dateiname des Moduls inkl. Präfix
* semantische Version (= version-Attribut in META.json vorhanden)
* Subversion Revision (-s steht für "Subversion", danach folgt die Revisionsnummer des jeweiligen Commits)
* das Release Datum (hier konkret das Check-in Datum in das SVN)

Für Module außerhalb des SVN werden diese Informationen entsprechend anders zusammengetragen oder müssen/können über das META.json Objekt bereitgestellt werden.
Hierbei ist zu erwähnen, dass ein FHEM Modul erst dann als dem SVN zugehörig angesehen wird, wenn es einen Eintrag in MAINTAINER.txt hat. Fehlt dieser Eintrag, dann wird das Modul nicht als FHEM Core Modul behandelt, sondern als externes 3rd-party Modul.

Meta

2019-07-11T13:21:18Z

Loredo: /* Development Module and Package Meta Data */

= Development Module and Package Meta Data =

== Einleitung ==

Neben den für ein FHEM Modul notwendigen [[DevelopmentModuleIntro|obligatorischen]] Metadaten (CommandRef, Kurzbeschreibung, Typ), gibt es in FHEM das Perl Package FHEM::Meta (oder kurz Meta.pm). Die Einbindung in ein FHEM Modul (= stellt Devices zur Verfügung) oder ein FHEM Package (= stellt Subroutinen für ein oder mehrere FHEM Module bereit) ermöglicht es, Informationen über das Modul in Form eines JSON [https://perldoc.perl.org/perlpod.html Pod] (auch META.json genannt) direkt in die Datei mit einzubetten. Darüber wird es möglich, diese Zusatzinformationen auch bereits auszuwerten und anzuzeigen, ohne dass ein Modul geladen oder verwendet wird. Beispielsweise kann ermittelt werden, welche Perl Module für die Nutzung des Moduls notwendig sind und ob eine bestimmte Version vorausgesetzt wird. Außerdem können Informationen über die Version des Moduls, die Historie, den Autor, für Supportanfragen und vieles weiteres hinterlegt werden.

Das Grundschema für die JSON Struktur basiert dabei auf der offiziellen [https://metacpan.org/pod/CPAN::Meta::Spec CPAN::Meta::Spec] Spezifikation, welche auch bei regulär veröffentlichten Perl Modulen verwendet wird. Das FHEM::Meta Package hilft dabei, diese JSON Informationen aus der Datei auszulesen und stellt diese im globalen %modules Hash des jeweiligen Moduls zur weiteren Verarbeitung bereit. Meta wertet dabei die in der Moduldatei (bei Modulen, die im SVN veröffentlicht sind, auch die in FHEM bereits bekannten) hinterlegten Maintenance und Supportdaten aus, so dass diese Informationen für sämtliche FHEM Module grundsätzlich bereitgestellt werden können. Meta erweitert die Standard Spezifikation dafür mit eigenen JSON Attributen, die spezifikationskonform im Namen mit <code>x_</code> beginnen. Diese Art, zusätzliche Informationen über die Funktionalität eines Modules bereitzustellen, ohne dass ein Modul dafür tatsächlich geladen werden muss, steht jedem Modul als Erweiterung zur Verfügung. Es ist also denkbar, dass Module darüber bekanntmachen, welche Netzwerk-Protokolle sie beherrschen, wie bestimmte Geräte im Netzwerk gefunden werden können und mit welchen define-Parametern ein Gerät in FHEM angelegt werden kann. Hierzu gibt es erste Ansätze, die sich in [https://forum.fhem.de/index.php/topic,67368.0.html Planung] befinden.

== Der FHEM Installer ==

Der FHEM Installer ist ein FHEM Modul, welches ein graphisches Interface für die Metadaten bereitstellt. Mit Hilfe des FHEM Installers werden die Metadaten auch für Module in den Speicher geladen, welche keine explizite Unterstützung eingebaut haben. Sobald man die Informationen für ein bestimmtes Modul oder Package abfragt, wird der Meta-Hash über die Funktion FHEM::Meta::Load() geladen. Für FHEM Module, die beim Start von FHEM bereits in Verwendung sind, werden die Metadaten automatisch im Voraus geladen, so dass sie zur Laufzeit zur Verfügung stehen. Es ist geplant, dass dies auch zur Laufzeit für Module, für die der Benutzer ein neues Device anlegt, geschieht.

Die Grundfunktion des FHEM Installer ist jedoch nicht die Bereitstellung der Metadaten, sondern die Auswertung derselben. In seiner weiteren Entwicklung soll er dabei unterstützen fehlende Systemkomponenten, die für die Nutzung eines FHEM Moduls notwendig sind, zu installieren und aktuell zu halten. Die Installation und Aktualisierung von Perl Modulen ist bereits jetzt in einer ersten Ausbaustufe möglich.

Stellt man am FHEM Installer Device das Attribut <code>installerMode</code> auf developer, dann werden einige weitere Get Befehle sichtbar, über die sich auch der Inhalt des kummulierten META.json Hashes anzeigen lässt. Dies ist oft hilfreich für ein initiales Verständnis, welche Informationen FHEM::Meta bereits über ein Modul gesammelt hat, bevor man diese über einen eigenen META.json Pod in der Moduldatei ergänzen oder verändern möchte.

Hinweis: Die Weiterentwicklung von FHEM::Meta ist stark an die weitere Entwicklung des FHEM Installer geknüpft. Dort geht es dann insbesondere darum, dass FHEM Module aus anderen Installationsquellen neben dem SVN die gleiche Metadaten einliefern können, insbesondere was Versionierung und Historie angehen. Dieses und mehr ist jedoch ein ganz eigenes Kapitel und soll deshalb für das Thema FHEM::Meta nur kurz erwähnt sein.

== Der search-Befehl ==

Der FHEM Befehl <code>search</code> ist ein Wrapper, um den Get-Befehl <code>search</code> beim FHEM Installer Device im Schnellzugriff über die FHEM Befehlszeile aufzurufen. Hierüber lassen sich die Metadaten aller FHEM Module durchsuchen und ermöglicht so das Auffinden von FHEM Modulen für eine bestimmte Funktion oder ein Gebiet. FHEM Module, die einen META.json Pod bereitstellen, können dort Schlagworte hinterlegen, über die das Modul in der Suche gefunden werden können soll. FHEM::Meta generiert für Module, die über das SVN bereitgestellt werden, bereits einige Schlagworte basierend auf dem hinterlegten Support Forum in MAINTAINER.txt. Auch Der Modul Typ (helper|device|command) findet sich als eigenes Schlagwort wieder. Man erhält also Out-of-the-Box bereits eine ziemlich gute Kategorisierung über den Anwendungsbereich eines bestimmten Moduls und welche anderen Module noch in diesen Bereich fallen. Ein Modulname alleine hingegen lässt oftmals nicht auf die Funktionalität dahinter schließen, insbesondere wenn Hersteller- oder Produktnamen eine Rolle spielen, die man selbst bisher nicht kennt.

== Erweiterung eines FHEM Moduls mit META.json Pod ==

Möchte ein Modulautor aktiven Support FHEM::Meta einbauen, dann ist der erste Schritt die Bereitstellung eines META.json Abschnitts am Ende der Modul- oder Paketdatei. Dieser Abschnitt beinhaltet ein reguläres JSON Objekt. Deshalb empfiehlt es sich den Abschnitt vor dem hinzufügen über einen JSON Validator auf seine Syntax zu überprüfen. Ansonsten wird von FHEM::Meta beim laden eine entsprechende Meldung im FHEM Log ausgegeben und es werden keinerlei Metadaten mehr über das Modul bereitgestellt. Sobald ein META.json Abschnitt vorhanden ist, geht FHEM::Meta davon aus, dass dieses maßgeblich ist und wird deshalb nur noch Daten ergänzen, die dort nicht enthalten sind. Fehlt also ein valides META.json Objekt als Basis, so werden auch diese Ergänzungen nicht erfolgen und der Modulautor muss zunächst zwingend das JSON Gerüst korrigieren.

Für das Hinzufügen des META.json Abschnitts kann man mit der Beispieldatei [https://svn.fhem.de/trac/browser/trunk/fhem/contrib/META.json.txt contrib/META.json.txt] als Ausgangsbasis starten. Die oben erwähnte Spezifikation sollte man einmal gelesen haben um zu verstehen, welches Format für ein Datenfeld gilt und welche Angaben die Spezifikation als zwingend vorschreibt. Es ist empfehlenswert alle dort als ''mandatory'' erwähnten Angaben in META.json anzugeben, auch wenn diese Informationen vielleicht teilweise in anderen Dateien in FHEM bereits vorhanden sind (gilt natürlich nur für Module, die auch über das SVN verteilt werden). Beispielsweise sollte eine (Kurz-)Beschreibung trotzdem enthalten sein. Der Grund ist, dass zumindest theoretisch dann auch andere 3rd-party Tools, die mit Perl Modulen hantieren, diese Informationen in vereinfachter Art ebenfalls auslesen und auswerten können. Diese Tools könnten darauf bestehen, dass sie eben diese als zwingend spezifizierten Attribute dort auch vorfinden. FHEM::Meta fügt fehlende Informationen zwar zur Laufzeit selbst hinzu, dies hilt jedoch anderen Tools, die das JSON Objekt direkt auswerten, eben nicht. Wie genau ein Modulautor dieser Empfehlung folgen möchte, ist ihm überlassen.

Die Inhalte aus der Beispieldatei oben sollten als Mindestvoraussetzung angesehen werden. Insbesondere der Abschnitt <code>prereqs</code> für verwendete Perl Module ist hier wichtig, da das Vorhandensein eines selben eine wesentlich schnellere Ladezeit der Metainformationen zur Folge hat, da die Abhängigkeiten nicht durch eine Analyse erfolgen muss. Das bedeutet jedoch auch, dass diese Informationen vollständig sein müssen und der Autor dafür verantwortlich ist, das diese stimmig sind. Als Hilfestellung, was man hier für sein Modul eintragen sollte, kann man sichüber den FHEM Installer im oben erwähnten Developer-Modus das über das Analyse-Verfahren erzeugte META.json ansehen und dort den entsprechenden prereqs Abschnitt kopieren. Im Grunde werden dort alle "use" und "require" Aufrufe, die ein Modul macht, aufgeführt. Das schließt auch den Aufruf von Perl Builtin Funktionen wie "use strict;" oder ähnliches ein. Es ist empfehlenswert diese hier ebenfalls mit aufzuführen. Über die Metadaten kann man dann auch als FHEM Entwickler entsprechende Statistiken über die Code/Modul Qualität (so man die Nutzung von "use strict;" denn beispielhaft als positiv wirkend interpretieren möchte) fahren.

Hat man das JSON Objekt für sein Modul nun also fertig, dann kopiert man es in seine Moduldatei ''hinter'' den letzten commandRef Abschnitt und ''vor'' der Schlussformel <code>=cut</code>. Dabei wird das META.json Objekt von folgender Markierung umschlossen:

==== META.json Abschnitt ====
<syntaxhighlight lang="perl">
=for :application/json;q=META.json 00_myModule.pm
{ ... }
=end :application/json;q=META.json
</syntaxhighlight>

Dabei ist 00_myModule.pm durch den Dateinamen der jeweiligen Moduldatei zu ersetzen. Auf diese Weise wird sichergestellt, dass eine Metainformation auch wirklich zu genau dieser Moduldatei dazugehört.
Alle Informationen innerhalb des META.json sind im UTF-8 Format. Dies machen wir deshalb zusätzlich nochmals zum Beginn des <code>=pod</code> Abschnitts ''vor'' dem ersten CommandRef Eintrag deutlich:

==== Encoding ====
<syntaxhighlight lang="perl">
=pod

=encoding utf8

=for :application/json;q=META.json 00_myModule.pm
{ ... }
=end :application/json;q=META.json

=cut
</syntaxhighlight>

Ein komplettes Beispiel, wie sich der META.json Abschnitt in eine Moduldatei einfügt, zeigt die Datei [https://svn.fhem.de/trac/browser/trunk/fhem/contrib/META.json.full.txt contrib/META.json.full.txt].
Für Fortgeschrittene sind dort außerdem weitere Beispieleinträge für Metadaten, die der FHEM Installer auswerten und verarbeiten kann.

Hat man nun also den META.json Abschnitt ordnungsgemäß hinzugefügt, kann man mit Hilfe des FHEM Installer überprüfen, ob die Daten richtig hinterlegt worden sind und geladen werden können.

== Eigenständiges Laden der Metadaten aus einem FHEM Modul heraus ==

Ein FHEM Modul kann selbstständig die Unterstützung für das Laden der Metadaten in den %modules Hash einbauen, um diese unabhängig vom FHEM Installer zur Verfügung zu haben.
Hierfür muss am Beginn der Moduldatei zunächst <code>use FHEM::Meta;</code> hinzugefügt werden und die <code>X_Initialize();</code> Funktion am Ende um einen Initialisierungsaufruf erweitert werden:

==== X_Initialize ====
<syntaxhighlight lang="perl">
use FHEM::Meta;

sub X_Initialize($)
{
my ($hash) = @_;
...

return FHEM::Meta::InitMod( __FILE__, $hash );
}
</syntaxhighlight>

Die Metadaten werden dann beim Initialisieren des Moduls nach $modules{<TYPE>}{META} geladen und stehen dort bereit.

== Anzeigen der Modulversion über FHEM::Meta ==

Im META.json Objekt kann eine Version des Moduls explizit in [https://semver.org/ semantischer Form] (beispielsweise v1.2.3) angegeben werden. Ist dies nicht der Fall, dann generiert FHEM::Meta eine eigene Versionsnummer auf Basis der Revisionsnummer aus dem Subversion Repository im <code>$Id$</code> Abschnitt der Moduldatei. Dies gilt jedoch nur für Module, die auch tatsächlich über das SVN verteilt werden, ansonsten wird dieser Abschnitt ignoriert. Durch die Angabe der Versionsnummer im META.json Objekt wird es somit erstmals möglich, dass auch Module außerhalb des SVN mit einer einheitlichen Art der Versionierung auftreten können.
Eine semantische Versionsnummer wird von FHEM::Meta automatisch über die Perl Builtin Module version in einen Float Wert umgewandelt, um nummerische Vergleiche zu ermöglichen.

FHEM::Meta bietet eine Funktion, um die essentiellen Metadaten zum Versionsstand eines Moduls als Internal mit dem Namen FVERSION anzuzeigen. Dafür kann man an den Beginn der <code>X_Define()</code> Funktion folgenden Aufruf setzen:

==== X_Define ====
<syntaxhighlight lang="perl">
sub X_Define($$)
{
my ( $hash, $def ) = @_;
return $@ unless ( FHEM::Meta::SetInternals($hash) );
...

return $error;
}
</syntaxhighlight>

Zum aktuellen Zeitpunkt wird hierdurch lediglich das Internal FVERSION gesetzt. Dieses sieht dann beispielsweise so aus:

<code>
00_myModule.pm:v0.5.6-s19500/2019-05-30
</code>

Als Informationen sind hier verpackt:
* Dateiname des Moduls inkl. Präfix
* semantische Version (= version-Attribut in META.json vorhanden)
* Subversion Revision (-s steht für "Subversion", danach folgt die Revisionsnummer des jeweiligen Commits)
* das Release Datum (hier konkret das Check-in Datum in das SVN)

Für Module außerhalb des SVN werden diese Informationen entsprechend anders zusammengetragen oder müssen/können über das META.json Objekt bereitgestellt werden.
Hierbei ist zu erwähnen, dass ein FHEM Modul erst dann als dem SVN zugehörig angesehen wird, wenn es einen Eintrag in MAINTAINER.txt hat. Fehlt dieser Eintrag, dann wird das Modul nicht als FHEM Core Modul behandelt, sondern als externes 3rd-party Modul.

Meta

2019-07-11T13:00:14Z

Loredo:

= Development Module and Package Meta Data =

== Einleitung ==

Neben den für ein FHEM Modul notwendigen [[DevelopmentModuleIntro|obligatorischen]] Metadaten (CommandRef, Kurzbeschreibung, Typ), gibt es in FHEM das Perl Package FHEM::Meta (oder kurz Meta.pm). Die Einbindung in ein FHEM Modul (= stellt Devices zur Verfügung) oder ein FHEM Package (= stellt Subroutinen für ein oder mehrere FHEM Module bereit) ermöglicht es, Informationen über das Modul in Form eines JSON [https://perldoc.perl.org/perlpod.html Pod] (auch META.json genannt) direkt in die Datei mit einzubetten. Darüber wird es möglich, diese Zusatzinformationen auch bereits auszuwerten und anzuzeigen, ohne dass ein Modul bereits geladen oder verwendet wird. Beispielsweise kann ermittelt werden, welche Perl Module für die Nutzung des Moduls notwendig sind und ob eine bestimmte Version vorausgesetzt wird. Außerdem können Informationen über die Version des Moduls, die Historie, den Autor, für Supportanfragen und vieles weiteres hinterlegt werden.

Das Grundschema für die JSON Struktur basiert dabei auf der offiziellen [https://metacpan.org/pod/CPAN::Meta::Spec CPAN::Meta::Spec] Spezifikation, welche auch bei regulär veröffentlichten Perl Modulen verwendet wird. Das FHEM::Meta Package hilft dabei, diese JSON Informationen aus der Datei auszulesen und stellt diese im globalen %modules Hash des jeweiligen Moduls zur weiteren Verarbeitung bereit. Meta wertet dabei die in der Moduldatei (bei Modulen, die im SVN veröffentlicht sind, auch die in FHEM bereits bekannten) hinterlegten Maintenance und Supportdaten aus, so dass diese Informationen für sämtliche FHEM Module grundsätzlich bereitgestellt werden können. Meta erweitert die Standard Spezifikation dafür mit eigenen JSON Attributen, die spezifikationskonform im Namen mit <code>x_</code> beginnen. Diese Art, zusätzliche Informationen über die Funktionalität eines Modules bereitzustellen, ohne dass ein Modul dafür tatsächlich geladen werden muss, steht jedem Modul als Erweiterung zur Verfügung. Es ist also denkbar, dass Module darüber bekanntmachen, welche Netzwerk-Protokolle sie beherrschen, wie bestimmte Geräte im Netzwerk gefunden werden können und mit welchen define-Parametern ein Gerät in FHEM angelegt werden kann. Hierzu gibt es erste Ansätze, die sich in [https://forum.fhem.de/index.php/topic,67368.0.html Planung] befinden.

== Der FHEM Installer ==

Der FHEM Installer ist ein FHEM Modul, welches ein graphisches Interface für die Metadaten bereitstellt. Mit Hilfe des FHEM Installers werden die Metadaten auch für Module in den Speicher geladen, welche keine explizite Unterstützung eingebaut haben. Sobald man die Informationen für ein bestimmtes Modul oder Package abfragt, wird der Meta-Hash über die Funktion FHEM::Meta::Load() geladen. Für FHEM Module, die beim Start von FHEM bereits in Verwendung sind, werden die Metadaten automatisch im Voraus geladen, so dass sie zur Laufzeit zur Verfügung stehen. Es ist geplant, dass dies auch zur Laufzeit für Module, für die der Benutzer ein neues Device anlegt, geschieht.

Die Grundfunktion des FHEM Installer ist jedoch nicht die Bereitstellung der Metadaten, sondern die Auswertung derselben. In seiner weiteren Entwicklung soll er dabei unterstützen fehlende Systemkomponenten, die für die Nutzung eines FHEM Moduls notwendig sind, zu installieren und aktuell zu halten. Die Installation und Aktualisierung von Perl Modulen ist bereits jetzt in einer ersten Ausbaustufe möglich.

Stellt man am FHEM Installer Device das Attribut <code>installerMode</code> auf developer, dann werden einige weitere Get Befehle sichtbar, über die sich auch der Inhalt des kummulierten META.json Hashes anzeigen lässt. Dies ist oft hilfreich für ein initiales Verständnis, welche Informationen FHEM::Meta bereits über ein Modul gesammelt hat, bevor man diese über einen eigenen META.json Pod in der Moduldatei ergänzen oder verändern möchte.

Hinweis: Die Weiterentwicklung von FHEM::Meta ist stark an die weitere Entwicklung des FHEM Installer geknüpft. Dort geht es dann insbesondere darum, dass FHEM Module aus anderen Installationsquellen neben dem SVN die gleiche Metadaten einliefern können, insbesondere was Versionierung und Historie angehen. Dieses und mehr ist jedoch ein ganz eigenes Kapitel und soll deshalb für das Thema FHEM::Meta nur kurz erwähnt sein.

== Der search-Befehl ==

Der FHEM Befehl <code>search</code> ist ein Wrapper, um den Get-Befehl <code>search</code> beim FHEM Installer Device im Schnellzugriff über die FHEM Befehlszeile aufzurufen. Hierüber lassen sich die Metadaten aller FHEM Module durchsuchen und ermöglicht so das Auffinden von FHEM Modulen für eine bestimmte Funktion oder ein Gebiet. FHEM Module, die einen META.json Pod bereitstellen, können dort Schlagworte hinterlegen, über die das Modul in der Suche gefunden werden können soll. FHEM::Meta generiert für Module, die über das SVN bereitgestellt werden, bereits einige Schlagworte basierend auf dem hinterlegten Support Forum in MAINTAINER.txt. Auch Der Modul Typ (helper|device|command) findet sich als eigenes Schlagwort wieder. Man erhält also Out-of-the-Box bereits eine ziemlich gute Kategorisierung über den Anwendungsbereich eines bestimmten Moduls und welche anderen Module noch in diesen Bereich fallen. Ein Modulname alleine hingegen lässt oftmals nicht auf die Funktionalität dahinter schließen, insbesondere wenn Hersteller- oder Produktnamen eine Rolle spielen, die man selbst bisher nicht kennt.

== Erweiterung eines FHEM Moduls mit META.json Pod ==

Möchte ein Modulautor aktiven Support FHEM::Meta einbauen, dann ist der erste Schritt die Bereitstellung eines META.json Abschnitts am Ende der Modul- oder Paketdatei. Dieser Abschnitt beinhaltet ein reguläres JSON Objekt. Deshalb empfiehlt es sich den Abschnitt vor dem hinzufügen über einen JSON Validator auf seine Syntax zu überprüfen. Ansonsten wird von FHEM::Meta beim laden eine entsprechende Meldung im FHEM Log ausgegeben und es werden keinerlei Metadaten mehr über das Modul bereitgestellt. Sobald ein META.json Abschnitt vorhanden ist, geht FHEM::Meta davon aus, dass dieses maßgeblich ist und wird deshalb nur noch Daten ergänzen, die dort nicht enthalten sind. Fehlt also ein valides META.json Objekt als Basis, so werden auch diese Ergänzungen nicht erfolgen und der Modulautor muss zunächst zwingend das JSON Gerüst korrigieren.

Für das Hinzufügen des META.json Abschnitts kann man mit der Beispieldatei [https://svn.fhem.de/trac/browser/trunk/fhem/contrib/META.json.txt contrib/META.json.txt] als Ausgangsbasis starten. Die oben erwähnte Spezifikation sollte man einmal gelesen haben um zu verstehen, welches Format für ein Datenfeld gilt und welche Angaben die Spezifikation als zwingend vorschreibt. Es ist empfehlenswert alle dort als ''mandatory'' erwähnten Angaben in META.json anzugeben, auch wenn diese Informationen vielleicht teilweise in anderen Dateien in FHEM bereits vorhanden sind (gilt natürlich nur für Module, die auch über das SVN verteilt werden). Beispielsweise sollte eine (Kurz-)Beschreibung trotzdem enthalten sein. Der Grund ist, dass zumindest theoretisch dann auch andere 3rd-party Tools, die mit Perl Modulen hantieren, diese Informationen in vereinfachter Art ebenfalls auslesen und auswerten können. Diese Tools könnten darauf bestehen, dass sie eben diese als zwingend spezifizierten Attribute dort auch vorfinden. FHEM::Meta fügt fehlende Informationen zwar zur Laufzeit selbst hinzu, dies hilt jedoch anderen Tools, die das JSON Objekt direkt auswerten, eben nicht. Wie genau ein Modulautor dieser Empfehlung folgen möchte, ist ihm überlassen.

Die Inhalte aus der Beispieldatei oben sollten als Mindestvoraussetzung angesehen werden. Insbesondere der Abschnitt <code>prereqs</code> für verwendete Perl Module ist hier wichtig, da das Vorhandensein eines selben eine wesentlich schnellere Ladezeit der Metainformationen zur Folge hat, da die Abhängigkeiten nicht durch eine Analyse erfolgen muss. Das bedeutet jedoch auch, dass diese Informationen vollständig sein müssen und der Autor dafür verantwortlich ist, das diese stimmig sind. Als Hilfestellung, was man hier für sein Modul eintragen sollte, kann man sichüber den FHEM Installer im oben erwähnten Developer-Modus das über das Analyse-Verfahren erzeugte META.json ansehen und dort den entsprechenden prereqs Abschnitt kopieren. Im Grunde werden dort alle "use" und "require" Aufrufe, die ein Modul macht, aufgeführt. Das schließt auch den Aufruf von Perl Builtin Funktionen wie "use strict;" oder ähnliches ein. Es ist empfehlenswert diese hier ebenfalls mit aufzuführen. Über die Metadaten kann man dann auch als FHEM Entwickler entsprechende Statistiken über die Code/Modul Qualität (so man die Nutzung von "use strict;" denn beispielhaft als positiv wirkend interpretieren möchte) fahren.

Hat man das JSON Objekt für sein Modul nun also fertig, dann kopiert man es in seine Moduldatei ''hinter'' den letzten commandRef Abschnitt und ''vor'' der Schlussformel <code>=cut</code>. Dabei wird das META.json Objekt von folgender Markierung umschlossen:

==== META.json Abschnitt ====
<syntaxhighlight lang="perl">
=for :application/json;q=META.json 00_myModule.pm
{ ... }
=end :application/json;q=META.json
</syntaxhighlight>

Dabei ist 00_myModule.pm durch den Dateinamen der jeweiligen Moduldatei zu ersetzen. Auf diese Weise wird sichergestellt, dass eine Metainformation auch wirklich zu genau dieser Moduldatei dazugehört.
Alle Informationen innerhalb des META.json sind im UTF-8 Format. Dies machen wir deshalb zusätzlich nochmals zum Beginn des <code>=pod</code> Abschnitts ''vor'' dem ersten CommandRef Eintrag deutlich:

==== Encoding ====
<syntaxhighlight lang="perl">
=pod

=encoding utf8

=for :application/json;q=META.json 00_myModule.pm
{ ... }
=end :application/json;q=META.json

=cut
</syntaxhighlight>

Ein komplettes Beispiel, wie sich der META.json Abschnitt in eine Moduldatei einfügt, zeigt die Datei [https://svn.fhem.de/trac/browser/trunk/fhem/contrib/META.json.full.txt contrib/META.json.full.txt].
Für Fortgeschrittene sind dort außerdem weitere Beispieleinträge für Metadaten, die der FHEM Installer auswerten und verarbeiten kann.

Hat man nun also den META.json Abschnitt ordnungsgemäß hinzugefügt, kann man mit Hilfe des FHEM Installer überprüfen, ob die Daten richtig hinterlegt worden sind und geladen werden können.

== Eigenständiges Laden der Metadaten aus einem FHEM Modul heraus ==

Ein FHEM Modul kann selbstständig die Unterstützung für das Laden der Metadaten in den %modules Hash einbauen, um diese unabhängig vom FHEM Installer zur Verfügung zu haben.
Hierfür muss am Beginn der Moduldatei zunächst <code>use FHEM::Meta;</code> hinzugefügt werden und die <code>X_Initialize();</code> Funktion am Ende um einen Initialisierungsaufruf erweitert werden:

==== X_Initialize ====
<syntaxhighlight lang="perl">
use FHEM::Meta;

sub X_Initialize($)
{
my ($hash) = @_;
...

return FHEM::Meta::InitMod( __FILE__, $hash );
}
</syntaxhighlight>

Die Metadaten werden dann beim Initialisieren des Moduls nach $modules{<TYPE>}{META} geladen und stehen dort bereit.

== Anzeigen der Modulversion über FHEM::Meta ==

Im META.json Objekt kann eine Version des Moduls explizit in [https://semver.org/ semantischer Form] (beispielsweise v1.2.3) angegeben werden. Ist dies nicht der Fall, dann generiert FHEM::Meta eine eigene Versionsnummer auf Basis der Revisionsnummer aus dem Subversion Repository im <code>$Id$</code> Abschnitt der Moduldatei. Dies gilt jedoch nur für Module, die auch tatsächlich über das SVN verteilt werden, ansonsten wird dieser Abschnitt ignoriert. Durch die Angabe der Versionsnummer im META.json Objekt wird es somit erstmals möglich, dass auch Module außerhalb des SVN mit einer einheitlichen Art der Versionierung auftreten können.
Eine semantische Versionsnummer wird von FHEM::Meta automatisch über die Perl Builtin Module version in einen Float Wert umgewandelt, um nummerische Vergleiche zu ermöglichen.

FHEM::Meta bietet eine Funktion, um die essentiellen Metadaten zum Versionsstand eines Moduls als Internal mit dem Namen FVERSION anzuzeigen. Dafür kann man an den Beginn der <code>X_Define()</code> Funktion folgenden Aufruf setzen:

==== X_Define ====
<syntaxhighlight lang="perl">
sub X_Define($$)
{
my ( $hash, $def ) = @_;
return $@ unless ( FHEM::Meta::SetInternals($hash) );
...

return $error;
}
</syntaxhighlight>

Zum aktuellen Zeitpunkt wird hierdurch lediglich das Internal FVERSION gesetzt. Dieses sieht dann beispielsweise so aus:

<code>
00_myModule.pm:v0.5.6-s19500/2019-05-30
</code>

Als Informationen sind hier verpackt:
* Dateiname des Moduls inkl. Präfix
* semantische Version (= version-Attribut in META.json vorhanden)
* Subversion Revision (-s steht für "Subversion", danach folgt die Revisionsnummer des jeweiligen Commits)
* das Release Datum (hier konkret das Check-in Datum in das SVN)

Für Module außerhalb des SVN werden diese Informationen entsprechend anders zusammengetragen oder müssen/können über das META.json Objekt bereitgestellt werden.
Hierbei ist zu erwähnen, dass ein FHEM Modul erst dann als dem SVN zugehörig angesehen wird, wenn es einen Eintrag in MAINTAINER.txt hat. Fehlt dieser Eintrag, dann wird das Modul nicht als FHEM Core Modul behandelt, sondern als externes 3rd-party Modul.

Meta

2019-07-11T12:58:43Z

Loredo: /* Anzeigen der Modulversion über FHEM::Meta */

= Development Module and Package Meta Data =

== Einleitung ==

Neben den für ein FHEM Modul notwendigen [[DevelopmentModuleIntro|obligatorischen]] Metadaten (CommandRef, Kurzbeschreibung, Typ), gibt es in FHEM das Perl Package FHEM::Meta (oder kurz Meta.pm). Die Einbindung in ein FHEM Modul (= stellt Devices zur Verfügung) oder ein FHEM Package (= stellt Subroutinen für ein oder mehrere FHEM Module bereit) ermöglicht es, Informationen über das Modul in Form eines JSON [https://perldoc.perl.org/perlpod.html Pod] (auch META.json genannt) direkt in die Datei mit einzubetten. Darüber wird es möglich, diese Zusatzinformationen auch bereits auszuwerten und anzuzeigen, ohne dass ein Modul bereits geladen oder verwendet wird. Beispielsweise kann ermittelt werden, welche Perl Module für die Nutzung des Moduls notwendig sind und ob eine bestimmte Version vorausgesetzt wird. Außerdem können Informationen über die Version des Moduls, die Historie, den Autor, für Supportanfragen und vieles weiteres hinterlegt werden.

Das Grundschema für die JSON Struktur basiert dabei auf der offiziellen [https://metacpan.org/pod/CPAN::Meta::Spec CPAN::Meta::Spec] Spezifikation, welche auch bei regulär veröffentlichten Perl Modulen verwendet wird. Das FHEM::Meta Package hilft dabei, diese JSON Informationen aus der Datei auszulesen und stellt diese im globalen %modules Hash des jeweiligen Moduls zur weiteren Verarbeitung bereit. Meta wertet dabei die in der Moduldatei (bei Modulen, die im SVN veröffentlicht sind, auch die in FHEM bereits bekannten) hinterlegten Maintenance und Supportdaten aus, so dass diese Informationen für sämtliche FHEM Module grundsätzlich bereitgestellt werden können. Meta erweitert die Standard Spezifikation dafür mit eigenen JSON Attributen, die spezifikationskonform im Namen mit <code>x_</code> beginnen. Diese Art, zusätzliche Informationen über die Funktionalität eines Modules bereitzustellen, ohne dass ein Modul dafür tatsächlich geladen werden muss, steht jedem Modul als Erweiterung zur Verfügung. Es ist also denkbar, dass Module darüber bekanntmachen, welche Netzwerk-Protokolle sie beherrschen, wie bestimmte Geräte im Netzwerk gefunden werden können und mit welchen define-Parametern ein Gerät in FHEM angelegt werden kann. Hierzu gibt es erste Ansätze, die sich in [https://forum.fhem.de/index.php/topic,67368.0.html Planung] befinden.

== Der FHEM Installer ==

Der FHEM Installer ist ein FHEM Modul, welches ein graphisches Interface für die Metadaten bereitstellt. Mit Hilfe des FHEM Installers werden die Metadaten auch für Module in den Speicher geladen, welche keine explizite Unterstützung eingebaut haben. Sobald man die Informationen für ein bestimmtes Modul oder Package abfragt, wird der Meta-Hash über die Funktion FHEM::Meta::Load() geladen. Für FHEM Module, die beim Start von FHEM bereits in Verwendung sind, werden die Metadaten automatisch im Voraus geladen, so dass sie zur Laufzeit zur Verfügung stehen. Es ist geplant, dass dies auch zur Laufzeit für Module, für die der Benutzer ein neues Device anlegt, geschieht.

Die Grundfunktion des FHEM Installer ist jedoch nicht die Bereitstellung der Metadaten, sondern die Auswertung derselben. In seiner weiteren Entwicklung soll er dabei unterstützen fehlende Systemkomponenten, die für die Nutzung eines FHEM Moduls notwendig sind, zu installieren und aktuell zu halten. Die Installation und Aktualisierung von Perl Modulen ist bereits jetzt in einer ersten Ausbaustufe möglich.

Stellt man am FHEM Installer Device das Attribut <code>installerMode</code> auf developer, dann werden einige weitere Get Befehle sichtbar, über die sich auch der Inhalt des kummulierten META.json Hashes anzeigen lässt. Dies ist oft hilfreich für ein initiales Verständnis, welche Informationen FHEM::Meta bereits über ein Modul gesammelt hat, bevor man diese über einen eigenen META.json Pod in der Moduldatei ergänzen oder verändern möchte.

Hinweis: Die Weiterentwicklung von FHEM::Meta ist stark an die weitere Entwicklung des FHEM Installer geknüpft. Dort geht es dann insbesondere darum, dass FHEM Module aus anderen Installationsquellen neben dem SVN die gleiche Metadaten einliefern können, insbesondere was Versionierung und Historie angehen. Dieses und mehr ist jedoch ein ganz eigenes Kapitel und soll deshalb für das Thema FHEM::Meta nur kurz erwähnt sein.

== Der search-Befehl ==

Der FHEM Befehl <code>search</code> ist ein Wrapper, um den Get-Befehl <code>search</code> beim FHEM Installer Device im Schnellzugriff über die FHEM Befehlszeile aufzurufen. Hierüber lassen sich die Metadaten aller FHEM Module durchsuchen und ermöglicht so das Auffinden von FHEM Modulen für eine bestimmte Funktion oder ein Gebiet. FHEM Module, die einen META.json Pod bereitstellen, können dort Schlagworte hinterlegen, über die das Modul in der Suche gefunden werden können soll. FHEM::Meta generiert für Module, die über das SVN bereitgestellt werden, bereits einige Schlagworte basierend auf dem hinterlegten Support Forum in MAINTAINER.txt. Auch Der Modul Typ (helper|device|command) findet sich als eigenes Schlagwort wieder. Man erhält also Out-of-the-Box bereits eine ziemlich gute Kategorisierung über den Anwendungsbereich eines bestimmten Moduls und welche anderen Module noch in diesen Bereich fallen. Ein Modulname alleine hingegen lässt oftmals nicht auf die Funktionalität dahinter schließen, insbesondere wenn Hersteller- oder Produktnamen eine Rolle spielen, die man selbst bisher nicht kennt.

== Erweiterung eines FHEM Moduls mit META.json Pod ==

Möchte ein Modulautor aktiven Support FHEM::Meta einbauen, dann ist der erste Schritt die Bereitstellung eines META.json Abschnitts am Ende der Modul- oder Paketdatei. Dieser Abschnitt beinhaltet ein reguläres JSON Objekt. Deshalb empfiehlt es sich den Abschnitt vor dem hinzufügen über einen JSON Validator auf seine Syntax zu überprüfen. Ansonsten wird von FHEM::Meta beim laden eine entsprechende Meldung im FHEM Log ausgegeben und es werden keinerlei Metadaten mehr über das Modul bereitgestellt. Sobald ein META.json Abschnitt vorhanden ist, geht FHEM::Meta davon aus, dass dieses maßgeblich ist und wird deshalb nur noch Daten ergänzen, die dort nicht enthalten sind. Fehlt also ein valides META.json Objekt als Basis, so werden auch diese Ergänzungen nicht erfolgen und der Modulautor muss zunächst zwingend das JSON Gerüst korrigieren.

Für das Hinzufügen des META.json Abschnitts kann man mit der Beispieldatei [https://svn.fhem.de/trac/browser/trunk/fhem/contrib/META.json.txt contrib/META.json.txt] als Ausgangsbasis starten. Die oben erwähnte Spezifikation sollte man einmal gelesen haben um zu verstehen, welches Format für ein Datenfeld gilt und welche Angaben die Spezifikation als zwingend vorschreibt. Es ist empfehlenswert alle dort als ''mandatory'' erwähnten Angaben in META.json anzugeben, auch wenn diese Informationen vielleicht teilweise in anderen Dateien in FHEM bereits vorhanden sind (gilt natürlich nur für Module, die auch über das SVN verteilt werden). Beispielsweise sollte eine (Kurz-)Beschreibung trotzdem enthalten sein. Der Grund ist, dass zumindest theoretisch dann auch andere 3rd-party Tools, die mit Perl Modulen hantieren, diese Informationen in vereinfachter Art ebenfalls auslesen und auswerten können. Diese Tools könnten darauf bestehen, dass sie eben diese als zwingend spezifizierten Attribute dort auch vorfinden. FHEM::Meta fügt fehlende Informationen zwar zur Laufzeit selbst hinzu, dies hilt jedoch anderen Tools, die das JSON Objekt direkt auswerten, eben nicht. Wie genau ein Modulautor dieser Empfehlung folgen möchte, ist ihm überlassen.

Die Inhalte aus der Beispieldatei oben sollten als Mindestvoraussetzung angesehen werden. Insbesondere der Abschnitt <code>prereqs</code> für verwendete Perl Module ist hier wichtig, da das Vorhandensein eines selben eine wesentlich schnellere Ladezeit der Metainformationen zur Folge hat, da die Abhängigkeiten nicht durch eine Analyse erfolgen muss. Das bedeutet jedoch auch, dass diese Informationen vollständig sein müssen und der Autor dafür verantwortlich ist, das diese stimmig sind. Als Hilfestellung, was man hier für sein Modul eintragen sollte, kann man sichüber den FHEM Installer im oben erwähnten Developer-Modus das über das Analyse-Verfahren erzeugte META.json ansehen und dort den entsprechenden prereqs Abschnitt kopieren. Im Grunde werden dort alle "use" und "require" Aufrufe, die ein Modul macht, aufgeführt. Das schließt auch den Aufruf von Perl Builtin Funktionen wie "use strict;" oder ähnliches ein. Es ist empfehlenswert diese hier ebenfalls mit aufzuführen. Über die Metadaten kann man dann auch als FHEM Entwickler entsprechende Statistiken über die Code/Modul Qualität (so man die Nutzung von "use strict;" denn beispielhaft als positiv wirkend interpretieren möchte) fahren.

Hat man das JSON Objekt für sein Modul nun also fertig, dann kopiert man es in seine Moduldatei ''hinter'' den letzten commandRef Abschnitt und ''vor'' der Schlussformel <code>=cut</code>. Dabei wird das META.json Objekt von folgender Markierung umschlossen:

<syntaxhighlight lang="perl">
=for :application/json;q=META.json 00_myModule.pm
{ ... }
=end :application/json;q=META.json
</syntaxhighlight>

Dabei ist 00_myModule.pm durch den Dateinamen der jeweiligen Moduldatei zu ersetzen. Auf diese Weise wird sichergestellt, dass eine Metainformation auch wirklich zu genau dieser Moduldatei dazugehört.
Alle Informationen innerhalb des META.json sind im UTF-8 Format. Dies machen wir deshalb zusätzlich nochmals zum Beginn des <code>=pod</code> Abschnitts ''vor'' dem ersten CommandRef Eintrag deutlich:

<syntaxhighlight lang="perl">
=pod

=encoding utf8

=for :application/json;q=META.json 00_myModule.pm
{ ... }
=end :application/json;q=META.json

=cut
</syntaxhighlight>

Ein komplettes Beispiel, wie sich der META.json Abschnitt in eine Moduldatei einfügt, zeigt die Datei [https://svn.fhem.de/trac/browser/trunk/fhem/contrib/META.json.full.txt contrib/META.json.full.txt].
Für Fortgeschrittene sind dort außerdem weitere Beispieleinträge für Metadaten, die der FHEM Installer auswerten und verarbeiten kann.

Hat man nun also den META.json Abschnitt ordnungsgemäß hinzugefügt, kann man mit Hilfe des FHEM Installer überprüfen, ob die Daten richtig hinterlegt worden sind und geladen werden können.

== Eigenständiges Laden der Metadaten aus einem FHEM Modul heraus ==

Ein FHEM Modul kann selbstständig die Unterstützung für das Laden der Metadaten in den %modules Hash einbauen, um diese unabhängig vom FHEM Installer zur Verfügung zu haben.
Hierfür muss am Beginn der Moduldatei zunächst <code>use FHEM::Meta;</code> hinzugefügt werden und die <code>X_Initialize();</code> Funktion am Ende um einen Initialisierungsaufruf erweitert werden:

==== X_Initialize ====
<syntaxhighlight lang="perl">
use FHEM::Meta;

sub X_Initialize($)
{
my ($hash) = @_;
...

return FHEM::Meta::InitMod( __FILE__, $hash );
}
</syntaxhighlight>

Die Metadaten werden dann beim Initialisieren des Moduls nach $modules{<TYPE>}{META} geladen und stehen dort bereit.

== Anzeigen der Modulversion über FHEM::Meta ==

Im META.json Objekt kann eine Version des Moduls explizit in [https://semver.org/ semantischer Form] (beispielsweise v1.2.3) angegeben werden. Ist dies nicht der Fall, dann generiert FHEM::Meta eine eigene Versionsnummer auf Basis der Revisionsnummer aus dem Subversion Repository im <code>$Id$</code> Abschnitt der Moduldatei. Dies gilt jedoch nur für Module, die auch tatsächlich über das SVN verteilt werden, ansonsten wird dieser Abschnitt ignoriert. Durch die Angabe der Versionsnummer im META.json Objekt wird es somit erstmals möglich, dass auch Module außerhalb des SVN mit einer einheitlichen Art der Versionierung auftreten können.
Eine semantische Versionsnummer wird von FHEM::Meta automatisch über die Perl Builtin Module version in einen Float Wert umgewandelt, um nummerische Vergleiche zu ermöglichen.

FHEM::Meta bietet eine Funktion, um die essentiellen Metadaten zum Versionsstand eines Moduls als Internal mit dem Namen FVERSION anzuzeigen. Dafür kann man an den Beginn der <code>X_Define()</code> Funktion folgenden Aufruf setzen:

==== X_Define ====
<syntaxhighlight lang="perl">
sub X_Define($$)
{
my ( $hash, $def ) = @_;
return $@ unless ( FHEM::Meta::SetInternals($hash) );
...

return $error;
}
</syntaxhighlight>

Zum aktuellen Zeitpunkt wird hierdurch lediglich das Internal FVERSION gesetzt. Dieses sieht dann beispielsweise so aus:

<code>
00_myModule.pm:v0.5.6-s19500/2019-05-30
</code>

Als Informationen sind hier verpackt:
* Dateiname des Moduls inkl. Präfix
* semantische Version (= version-Attribut in META.json vorhanden)
* Subversion Revision (-s steht für "Subversion", danach folgt die Revisionsnummer des jeweiligen Commits)
* das Release Datum (hier konkret das Check-in Datum in das SVN)

Für Module außerhalb des SVN werden diese Informationen entsprechend anders zusammengetragen oder müssen/können über das META.json Objekt bereitgestellt werden.
Hierbei ist zu erwähnen, dass ein FHEM Modul erst dann als dem SVN zugehörig angesehen wird, wenn es einen Eintrag in MAINTAINER.txt hat. Fehlt dieser Eintrag, dann wird das Modul nicht als FHEM Core Modul behandelt, sondern als externes 3rd-party Modul.

Meta

2019-07-11T12:57:01Z

Loredo: /* Eigenständiges Laden der Metadaten aus einem FHEM Modul heraus */

= Development Module and Package Meta Data =

== Einleitung ==

Neben den für ein FHEM Modul notwendigen [[DevelopmentModuleIntro|obligatorischen]] Metadaten (CommandRef, Kurzbeschreibung, Typ), gibt es in FHEM das Perl Package FHEM::Meta (oder kurz Meta.pm). Die Einbindung in ein FHEM Modul (= stellt Devices zur Verfügung) oder ein FHEM Package (= stellt Subroutinen für ein oder mehrere FHEM Module bereit) ermöglicht es, Informationen über das Modul in Form eines JSON [https://perldoc.perl.org/perlpod.html Pod] (auch META.json genannt) direkt in die Datei mit einzubetten. Darüber wird es möglich, diese Zusatzinformationen auch bereits auszuwerten und anzuzeigen, ohne dass ein Modul bereits geladen oder verwendet wird. Beispielsweise kann ermittelt werden, welche Perl Module für die Nutzung des Moduls notwendig sind und ob eine bestimmte Version vorausgesetzt wird. Außerdem können Informationen über die Version des Moduls, die Historie, den Autor, für Supportanfragen und vieles weiteres hinterlegt werden.

Das Grundschema für die JSON Struktur basiert dabei auf der offiziellen [https://metacpan.org/pod/CPAN::Meta::Spec CPAN::Meta::Spec] Spezifikation, welche auch bei regulär veröffentlichten Perl Modulen verwendet wird. Das FHEM::Meta Package hilft dabei, diese JSON Informationen aus der Datei auszulesen und stellt diese im globalen %modules Hash des jeweiligen Moduls zur weiteren Verarbeitung bereit. Meta wertet dabei die in der Moduldatei (bei Modulen, die im SVN veröffentlicht sind, auch die in FHEM bereits bekannten) hinterlegten Maintenance und Supportdaten aus, so dass diese Informationen für sämtliche FHEM Module grundsätzlich bereitgestellt werden können. Meta erweitert die Standard Spezifikation dafür mit eigenen JSON Attributen, die spezifikationskonform im Namen mit <code>x_</code> beginnen. Diese Art, zusätzliche Informationen über die Funktionalität eines Modules bereitzustellen, ohne dass ein Modul dafür tatsächlich geladen werden muss, steht jedem Modul als Erweiterung zur Verfügung. Es ist also denkbar, dass Module darüber bekanntmachen, welche Netzwerk-Protokolle sie beherrschen, wie bestimmte Geräte im Netzwerk gefunden werden können und mit welchen define-Parametern ein Gerät in FHEM angelegt werden kann. Hierzu gibt es erste Ansätze, die sich in [https://forum.fhem.de/index.php/topic,67368.0.html Planung] befinden.

== Der FHEM Installer ==

Der FHEM Installer ist ein FHEM Modul, welches ein graphisches Interface für die Metadaten bereitstellt. Mit Hilfe des FHEM Installers werden die Metadaten auch für Module in den Speicher geladen, welche keine explizite Unterstützung eingebaut haben. Sobald man die Informationen für ein bestimmtes Modul oder Package abfragt, wird der Meta-Hash über die Funktion FHEM::Meta::Load() geladen. Für FHEM Module, die beim Start von FHEM bereits in Verwendung sind, werden die Metadaten automatisch im Voraus geladen, so dass sie zur Laufzeit zur Verfügung stehen. Es ist geplant, dass dies auch zur Laufzeit für Module, für die der Benutzer ein neues Device anlegt, geschieht.

Die Grundfunktion des FHEM Installer ist jedoch nicht die Bereitstellung der Metadaten, sondern die Auswertung derselben. In seiner weiteren Entwicklung soll er dabei unterstützen fehlende Systemkomponenten, die für die Nutzung eines FHEM Moduls notwendig sind, zu installieren und aktuell zu halten. Die Installation und Aktualisierung von Perl Modulen ist bereits jetzt in einer ersten Ausbaustufe möglich.

Stellt man am FHEM Installer Device das Attribut <code>installerMode</code> auf developer, dann werden einige weitere Get Befehle sichtbar, über die sich auch der Inhalt des kummulierten META.json Hashes anzeigen lässt. Dies ist oft hilfreich für ein initiales Verständnis, welche Informationen FHEM::Meta bereits über ein Modul gesammelt hat, bevor man diese über einen eigenen META.json Pod in der Moduldatei ergänzen oder verändern möchte.

Hinweis: Die Weiterentwicklung von FHEM::Meta ist stark an die weitere Entwicklung des FHEM Installer geknüpft. Dort geht es dann insbesondere darum, dass FHEM Module aus anderen Installationsquellen neben dem SVN die gleiche Metadaten einliefern können, insbesondere was Versionierung und Historie angehen. Dieses und mehr ist jedoch ein ganz eigenes Kapitel und soll deshalb für das Thema FHEM::Meta nur kurz erwähnt sein.

== Der search-Befehl ==

Der FHEM Befehl <code>search</code> ist ein Wrapper, um den Get-Befehl <code>search</code> beim FHEM Installer Device im Schnellzugriff über die FHEM Befehlszeile aufzurufen. Hierüber lassen sich die Metadaten aller FHEM Module durchsuchen und ermöglicht so das Auffinden von FHEM Modulen für eine bestimmte Funktion oder ein Gebiet. FHEM Module, die einen META.json Pod bereitstellen, können dort Schlagworte hinterlegen, über die das Modul in der Suche gefunden werden können soll. FHEM::Meta generiert für Module, die über das SVN bereitgestellt werden, bereits einige Schlagworte basierend auf dem hinterlegten Support Forum in MAINTAINER.txt. Auch Der Modul Typ (helper|device|command) findet sich als eigenes Schlagwort wieder. Man erhält also Out-of-the-Box bereits eine ziemlich gute Kategorisierung über den Anwendungsbereich eines bestimmten Moduls und welche anderen Module noch in diesen Bereich fallen. Ein Modulname alleine hingegen lässt oftmals nicht auf die Funktionalität dahinter schließen, insbesondere wenn Hersteller- oder Produktnamen eine Rolle spielen, die man selbst bisher nicht kennt.

== Erweiterung eines FHEM Moduls mit META.json Pod ==

Möchte ein Modulautor aktiven Support FHEM::Meta einbauen, dann ist der erste Schritt die Bereitstellung eines META.json Abschnitts am Ende der Modul- oder Paketdatei. Dieser Abschnitt beinhaltet ein reguläres JSON Objekt. Deshalb empfiehlt es sich den Abschnitt vor dem hinzufügen über einen JSON Validator auf seine Syntax zu überprüfen. Ansonsten wird von FHEM::Meta beim laden eine entsprechende Meldung im FHEM Log ausgegeben und es werden keinerlei Metadaten mehr über das Modul bereitgestellt. Sobald ein META.json Abschnitt vorhanden ist, geht FHEM::Meta davon aus, dass dieses maßgeblich ist und wird deshalb nur noch Daten ergänzen, die dort nicht enthalten sind. Fehlt also ein valides META.json Objekt als Basis, so werden auch diese Ergänzungen nicht erfolgen und der Modulautor muss zunächst zwingend das JSON Gerüst korrigieren.

Für das Hinzufügen des META.json Abschnitts kann man mit der Beispieldatei [https://svn.fhem.de/trac/browser/trunk/fhem/contrib/META.json.txt contrib/META.json.txt] als Ausgangsbasis starten. Die oben erwähnte Spezifikation sollte man einmal gelesen haben um zu verstehen, welches Format für ein Datenfeld gilt und welche Angaben die Spezifikation als zwingend vorschreibt. Es ist empfehlenswert alle dort als ''mandatory'' erwähnten Angaben in META.json anzugeben, auch wenn diese Informationen vielleicht teilweise in anderen Dateien in FHEM bereits vorhanden sind (gilt natürlich nur für Module, die auch über das SVN verteilt werden). Beispielsweise sollte eine (Kurz-)Beschreibung trotzdem enthalten sein. Der Grund ist, dass zumindest theoretisch dann auch andere 3rd-party Tools, die mit Perl Modulen hantieren, diese Informationen in vereinfachter Art ebenfalls auslesen und auswerten können. Diese Tools könnten darauf bestehen, dass sie eben diese als zwingend spezifizierten Attribute dort auch vorfinden. FHEM::Meta fügt fehlende Informationen zwar zur Laufzeit selbst hinzu, dies hilt jedoch anderen Tools, die das JSON Objekt direkt auswerten, eben nicht. Wie genau ein Modulautor dieser Empfehlung folgen möchte, ist ihm überlassen.

Die Inhalte aus der Beispieldatei oben sollten als Mindestvoraussetzung angesehen werden. Insbesondere der Abschnitt <code>prereqs</code> für verwendete Perl Module ist hier wichtig, da das Vorhandensein eines selben eine wesentlich schnellere Ladezeit der Metainformationen zur Folge hat, da die Abhängigkeiten nicht durch eine Analyse erfolgen muss. Das bedeutet jedoch auch, dass diese Informationen vollständig sein müssen und der Autor dafür verantwortlich ist, das diese stimmig sind. Als Hilfestellung, was man hier für sein Modul eintragen sollte, kann man sichüber den FHEM Installer im oben erwähnten Developer-Modus das über das Analyse-Verfahren erzeugte META.json ansehen und dort den entsprechenden prereqs Abschnitt kopieren. Im Grunde werden dort alle "use" und "require" Aufrufe, die ein Modul macht, aufgeführt. Das schließt auch den Aufruf von Perl Builtin Funktionen wie "use strict;" oder ähnliches ein. Es ist empfehlenswert diese hier ebenfalls mit aufzuführen. Über die Metadaten kann man dann auch als FHEM Entwickler entsprechende Statistiken über die Code/Modul Qualität (so man die Nutzung von "use strict;" denn beispielhaft als positiv wirkend interpretieren möchte) fahren.

Hat man das JSON Objekt für sein Modul nun also fertig, dann kopiert man es in seine Moduldatei ''hinter'' den letzten commandRef Abschnitt und ''vor'' der Schlussformel <code>=cut</code>. Dabei wird das META.json Objekt von folgender Markierung umschlossen:

<syntaxhighlight lang="perl">
=for :application/json;q=META.json 00_myModule.pm
{ ... }
=end :application/json;q=META.json
</syntaxhighlight>

Dabei ist 00_myModule.pm durch den Dateinamen der jeweiligen Moduldatei zu ersetzen. Auf diese Weise wird sichergestellt, dass eine Metainformation auch wirklich zu genau dieser Moduldatei dazugehört.
Alle Informationen innerhalb des META.json sind im UTF-8 Format. Dies machen wir deshalb zusätzlich nochmals zum Beginn des <code>=pod</code> Abschnitts ''vor'' dem ersten CommandRef Eintrag deutlich:

<syntaxhighlight lang="perl">
=pod

=encoding utf8

=for :application/json;q=META.json 00_myModule.pm
{ ... }
=end :application/json;q=META.json

=cut
</syntaxhighlight>

Ein komplettes Beispiel, wie sich der META.json Abschnitt in eine Moduldatei einfügt, zeigt die Datei [https://svn.fhem.de/trac/browser/trunk/fhem/contrib/META.json.full.txt contrib/META.json.full.txt].
Für Fortgeschrittene sind dort außerdem weitere Beispieleinträge für Metadaten, die der FHEM Installer auswerten und verarbeiten kann.

Hat man nun also den META.json Abschnitt ordnungsgemäß hinzugefügt, kann man mit Hilfe des FHEM Installer überprüfen, ob die Daten richtig hinterlegt worden sind und geladen werden können.

== Eigenständiges Laden der Metadaten aus einem FHEM Modul heraus ==

Ein FHEM Modul kann selbstständig die Unterstützung für das Laden der Metadaten in den %modules Hash einbauen, um diese unabhängig vom FHEM Installer zur Verfügung zu haben.
Hierfür muss am Beginn der Moduldatei zunächst <code>use FHEM::Meta;</code> hinzugefügt werden und die <code>X_Initialize();</code> Funktion am Ende um einen Initialisierungsaufruf erweitert werden:

==== X_Initialize ====
<syntaxhighlight lang="perl">
use FHEM::Meta;

sub X_Initialize($)
{
my ($hash) = @_;
...

return FHEM::Meta::InitMod( __FILE__, $hash );
}
</syntaxhighlight>

Die Metadaten werden dann beim Initialisieren des Moduls nach $modules{<TYPE>}{META} geladen und stehen dort bereit.

== Anzeigen der Modulversion über FHEM::Meta ==

Im META.json Objekt kann eine Version des Moduls explizit in [https://semver.org/ semantischer Form] (beispielsweise v1.2.3) angegeben werden. Ist dies nicht der Fall, dann generiert FHEM::Meta eine eigene Versionsnummer auf Basis der Revisionsnummer aus dem Subversion Repository im <code>$Id$</code> Abschnitt der Moduldatei. Dies gilt jedoch nur für Module, die auch tatsächlich über das SVN verteilt werden, ansonsten wird dieser Abschnitt ignoriert. Durch die Angabe der Versionsnummer im META.json Objekt wird es somit erstmals möglich, dass auch Module außerhalb des SVN mit einer einheitlichen Art der Versionierung auftreten können.
Eine semantische Versionsnummer wird von FHEM::Meta automatisch über die Perl Builtin Module version in einen Float Wert umgewandelt, um nummerische Vergleiche zu ermöglichen.

FHEM::Meta bietet eine Funktion, um die essentiellen Metadaten zum Versionsstand eines Moduls als Internal mit dem Namen FVERSION anzuzeigen. Dafür kann man an den Beginn der <code>X_Define()</code> Funktion folgenden Aufruf setzen:

==== X_Define ====
<syntaxhighlight lang="perl">
sub X_Define($$)
{
my ( $hash, $def ) = @_;
return $@ unless ( FHEM::Meta::SetInternals($hash) );
...

return $error;
}
</syntaxhighlight>

Zum aktuellen Zeitpunkt wird hierdurch lediglich das Internal FVERSION gesetzt. Dieses sieht dann beispielsweise so aus:

<code>
00_myModule.pm:v0.5.6-s19500/2019-05-30
</code>

Als Informationen sind hier verpackt:
* Dateiname des Moduls inkl. Präfix
* semantische Version (version-Attribut in META.json vorhanden)
* Subversion Revision (-s steht für "Subversion", danach folgt die Revisionsnummer des jeweiligen Commits)
* das Release Datum (hier konkret das Check-in Datum in das SVN)

Für Module außerhalb des SVN werden diese Informationen entsprechend anders zusammengetragen oder müssen/können über das META.json Objekt bereitgestellt werden.
Hierbei ist zu erwähnen, dass ein FHEM Modul erst dann als dem SVN zugehörig angesehen wird, wenn es einen Eintrag in MAINTAINER.txt hat. Fehlt dieser Eintrag, dann wird das Modul nicht als FHEM Core Modul behandelt, sondern als externes 3rd-party Modul.

Hauptseite

2019-07-11T12:56:15Z

Loredo:

<div><h1 style="font-family:sans-serif; font-size: 1.8em; border: none; text-align: center;">'''FHEM Wiki - Informationsportal zum FHEM SmartHome-Server'''</h1></div>

<div class="flexbox"> 
<div class="mainpagebox" style="order: 1; flex: 1 1 80%; background-color:#cce5ff;">
<div class="mw-collapsible mw-collapsed">
'''Was ist FHEM?'''
<div class="mw-collapsible-content">
'''FHEM''' ([https://register.dpma.de/DPMAregister/marke/register/3020152110040/DE R]) ist ein in Perl geschriebener, GPL v2 lizensierter Server für die Heimautomatisierung. Man kann mit FHEM häufig auftretende Aufgaben automatisieren, wie z.B. Lampen / Rollladen / Heizung / usw. schalten, oder Ereignisse wie Temperatur / Feuchtigkeit / Stromverbrauch protokollieren und visualisieren.

Das Programm läuft als Server, man kann es über WEB, dedizierte Smartphone Apps oder telnet bedienen, TCP Schnittstellen für JSON und XML existieren ebenfalls.

Um es zu verwenden, benötigt man einen 24/7 Rechner (NAS, RPi, PC, MacMini, etc) mit einem Perl Interpreter und angeschlossene Interfaces wie CUL-, EnOcean-, Z-Wave-USB-Stick etc. für einen Zugang zu den Aktoren und Sensoren.
</div></div></div>

<div class="mainpagebox" style="order: 4; background-color:#efefef;">
'''Wie fange ich an?'''
* [[Datei:Info_green.png|20px]][http://fhem.de/Heimautomatisierung-mit-fhem.pdf Heimautomatisierung mit FHEM][[Datei:Info_green.png|20px]]<br />DAS Einsteiger-PDF. '''Pflichtlektüre!'''<br />
* [[Quick-Start]], english version: [[Quick-Start/en|Quick-Start]]
* kleiner FHEM-Kurs, benötigt keine Hardware: [[Erste Schritte in FHEM]] / [[First steps in FHEM]]
* [[Systemübersicht]]
* Phasen eines FHEM-Projekts:
** [[Planung]]
** [[Umsetzung]] (Implementierung)
** [[Betrieb]] ("Produktion")
* [[:Kategorie:Glossary|Glossar]] (Erklärung für bestimmte Begriffe)<br />
* [[:Kategorie:HOWTOS|Verschiedene HowTos]]<br />
* [[:Kategorie:FAQ|Frequently asked Questions - Häufig gestellte Fragen mit Antworten]]<br />

</div>

<div class="mainpagebox" style="order: 6; background-color:#fff0e0;">
'''Unterstützte Hardware (Auszug)'''

* [[:Kategorie:Hardware Typen|Hardware Typen]] - Funktionsbezogene Übersicht (z.B. [[:Kategorie:Unterhaltungselektronik|Unterhaltungselektronik / Multimedia]], [[:Kategorie:Heizungssteuerung|Heizungssteuerung]], [[:Kategorie:Energieverbrauchsmessung|Energieverbrauchsmessung]], etc.)
* [[:Kategorie:Server Hardware|Server Hardware]] - Hardware, auf der FHEM installiert werden kann
* [[:Kategorie:EMS Components|EMS]], [[:Kategorie:FHT Components|FHT]], [[:Kategorie:HMS Components|HMS]] Komponenten
* [[:Kategorie:1-Wire|1-Wire System]]
* [[:Kategorie:EIB/KNX|EIB/KNX Komponenten]]
* [[:Kategorie:FS20 Components|FS20 Komponenten]]
* [[:Kategorie:EnOcean Components|EnOcean Komponenten]]
* [[:Kategorie:HomeMatic Components|HomeMatic Komponenten]]
* [[:Kategorie:MAX|MAX! Komponenten]]
* [[:Kategorie:panStamp|panStamp Komponenten]]
* [[:Kategorie:Z-Wave Components|Z-Wave Komponenten]]
* [[:Kategorie:ZigBee|Zigbee Komponenten]]
* [[:Kategorie:IP Components|Geräte mit Webinterface ("IP")]]
* [[:Kategorie:Other Components|Andere Komponenten / Sonstige Systeme]]

<div align="right"><small>'''[[:Kategorie:Hardware|Alle Hardware-Kategorien]]'''</small></div>
</div>

<div class="mainpagebox" style="order: 5; background-color:#F8F8FF;">
'''Ideen und Lösungen'''

* [[:Kategorie:Code_Snippets|Verschiedene kommentierte Lösungen und Code-Schnippsel]]
* [[:Kategorie:Examples|Beispielanwendungen - Hardwarelösungen - Fremdsystemanbindungen]]
* [[Anwendungsszenarien]]
* [[Trick der Woche|Tipp der Woche]]
* [[Wie kann ich...]]?

<div align="right"><small>'''[[:Kategorie:FHEM|FHEM-Haupt-Kategorien]]'''</small></div>
</div>

<div class="mainpagebox" style="order: 7; background-color:#FFFFE7;">
'''Developers Corner'''

* Informationen zur Modul-Entwicklung:
** [[DevelopmentModuleIntro|Development Module Introduction]]
** [[Meta|Development Module and Package Meta Data]]
** [[DevelopmentModuleAPI|Development Module API]]
** [[DevelopmentFHEMWEB-API|Development FHEMWEB API]]
** [[Blocking Call]]
** [[CoProcess]]
** [[HttpUtils]]
** [[DevIo]]
** [[Guidelines zur Dokumentation]]
** [[DevelopmentGuidelinesAV|Development Guidelines AV-Module]]

* Organisatorisches:
** [[How to write a patch]]
** [[SVN Nutzungsregeln]]

<div align="right"><small>'''[[:Kategorie:Development|Alle Artikel zu Development]]'''</small></div>
</div>

<div class="mainpagebox" style="order: 3; background-color:#d7ffff;">
'''FHEM Wiki News'''
<div style="height:20em;overflow:scroll;overflow-x:hidden;">{{FHEMWiki_News}}</div>
<div align="right"><small>'''Mehr [[FHEMWiki:News|News]]'''</small></div>
</div>

<div class="mainpagebox" style="order: 2; background-color:#e7f8ff;">
'''Was ist FHEM Wiki?'''

Das '''FHEM Wiki''' ergänzt die stets tagesaktuelle, von den zuständigen Entwicklern gepflegte {{Link2CmdRef}} (Befehls-Referenz) um weitergehende Informationen rund um FHEM. Im Wiki arbeiten Nutzer und Entwickler gemeinsam an zusätzlicher Dokumentation von FHEM und damit zusammenhängenden Themen.

Das FHEMWiki stellt neben der {{Link2CmdRef}}, dem [http://forum.fhem.de/ Forum] und der [http://www.fhem.de FHEM] Seite die zentrale Informationsquelle rund um FHEM dar. Bedeutung und Zusammenspiel dieser Elemente [[Dokumentationsstruktur|ist hier]] erläutert.


Bitte [[FHEMWiki:Support | unterstütze uns]] und hilf, [[:Kategorie:NeedsEditing| das Wiki zu erweitern]]. Vielen Dank!

<div align="right"><small>'''Mehr [[FHEMWiki:Über_FHEMWiki|über FHEMWiki]]'''</small></div>
</div>

<div class="mainpagebox" style="order: 8; background-color:#F8F8FF;">
'''Letzte Änderungen'''
<div style="font-size:small;color:black;"><small>{{Special:Recentchanges/8}}</small></div>
<div align="right"><small>'''Mehr [[Special:Recentchanges|Änderungen]]'''</small></div>
</div>

<div class="mainpagebox" style="order: 9; flex: 1 1 80%; background-color:#FFFFAA;">
'''Die letzten fünf neuen Seiten'''
<small>{{Special:NewPages/5}}</small>
<div align="right"><small>'''Mehr [[Special:NewPages|Neue Seiten]]'''</small></div>
</div>

<div class="mainpagebox" style="order: 10; background-color:#DDD68F;">
'''Administratives zum Wiki'''

''Allgemeine Aktivitäten:''
* Registrierung zur Mitarbeit: wende Dich bitte an einen [[FHEMWiki:Administratoren|Administrator]]
* Basiswissen über die Mitarbeit an einem Wiki erarbeiten ([http://de.wikipedia.org/wiki/Wikipedia:Beteiligen z.B. Wikipedia])
* Erweiterung und Korrektur von Artikeln, wo immer nötig
* Ein(ig)e der [[Spezial:Gewünschte Seiten|gewünschten Seiten]] erstellen
* Ideen aus dem [http://forum.fhem.de Forum] in bestehende oder neue Artikel einarbeiten
* [[Spezial:Verwaiste Seiten|verwaiste Seiten]] in sinnvoller Weise verlinken
* [[Spezial:Sackgassenseiten|Sackgassenseiten]] wikifizieren (Links auf andere Seiten einfügen)
* [[Datei:Info_red.png|20px]] '''Tips / Regeln / Hinweise auf "[[FHEMWiki:Über FHEMWiki|Über FHEMWiki]]" beachten!''' [[Datei:Info_red.png|20px]]

''Sonstiges:''
* Zum Ausprobieren bitte die [[FHEMWiki:Sandbox]] benutzen
* [//meta.wikimedia.org/wiki/Help:Contents Wiki Benutzerhandbuch].
* [//www.mediawiki.org/wiki/Manual:Configuration_settings Liste der Wiki-Konfigurationsvariablen]
* [//www.mediawiki.org/wiki/Manual:FAQ MediaWiki FAQ]
* [[FHEMWiki:Interna|Internes zu diesem Wiki]]
</div>

</div>
[[Kategorie:FHEM]]

Hauptseite

2019-07-11T12:54:59Z

Loredo:

<div><h1 style="font-family:sans-serif; font-size: 1.8em; border: none; text-align: center;">'''FHEM Wiki - Informationsportal zum FHEM SmartHome-Server'''</h1></div>

<div class="flexbox"> 
<div class="mainpagebox" style="order: 1; flex: 1 1 80%; background-color:#cce5ff;">
<div class="mw-collapsible mw-collapsed">
'''Was ist FHEM?'''
<div class="mw-collapsible-content">
'''FHEM''' ([https://register.dpma.de/DPMAregister/marke/register/3020152110040/DE R]) ist ein in Perl geschriebener, GPL v2 lizensierter Server für die Heimautomatisierung. Man kann mit FHEM häufig auftretende Aufgaben automatisieren, wie z.B. Lampen / Rollladen / Heizung / usw. schalten, oder Ereignisse wie Temperatur / Feuchtigkeit / Stromverbrauch protokollieren und visualisieren.

Das Programm läuft als Server, man kann es über WEB, dedizierte Smartphone Apps oder telnet bedienen, TCP Schnittstellen für JSON und XML existieren ebenfalls.

Um es zu verwenden, benötigt man einen 24/7 Rechner (NAS, RPi, PC, MacMini, etc) mit einem Perl Interpreter und angeschlossene Interfaces wie CUL-, EnOcean-, Z-Wave-USB-Stick etc. für einen Zugang zu den Aktoren und Sensoren.
</div></div></div>

<div class="mainpagebox" style="order: 4; background-color:#efefef;">
'''Wie fange ich an?'''
* [[Datei:Info_green.png|20px]][http://fhem.de/Heimautomatisierung-mit-fhem.pdf Heimautomatisierung mit FHEM][[Datei:Info_green.png|20px]]<br />DAS Einsteiger-PDF. '''Pflichtlektüre!'''<br />
* [[Quick-Start]], english version: [[Quick-Start/en|Quick-Start]]
* kleiner FHEM-Kurs, benötigt keine Hardware: [[Erste Schritte in FHEM]] / [[First steps in FHEM]]
* [[Systemübersicht]]
* Phasen eines FHEM-Projekts:
** [[Planung]]
** [[Umsetzung]] (Implementierung)
** [[Betrieb]] ("Produktion")
* [[:Kategorie:Glossary|Glossar]] (Erklärung für bestimmte Begriffe)<br />
* [[:Kategorie:HOWTOS|Verschiedene HowTos]]<br />
* [[:Kategorie:FAQ|Frequently asked Questions - Häufig gestellte Fragen mit Antworten]]<br />

</div>

<div class="mainpagebox" style="order: 6; background-color:#fff0e0;">
'''Unterstützte Hardware (Auszug)'''

* [[:Kategorie:Hardware Typen|Hardware Typen]] - Funktionsbezogene Übersicht (z.B. [[:Kategorie:Unterhaltungselektronik|Unterhaltungselektronik / Multimedia]], [[:Kategorie:Heizungssteuerung|Heizungssteuerung]], [[:Kategorie:Energieverbrauchsmessung|Energieverbrauchsmessung]], etc.)
* [[:Kategorie:Server Hardware|Server Hardware]] - Hardware, auf der FHEM installiert werden kann
* [[:Kategorie:EMS Components|EMS]], [[:Kategorie:FHT Components|FHT]], [[:Kategorie:HMS Components|HMS]] Komponenten
* [[:Kategorie:1-Wire|1-Wire System]]
* [[:Kategorie:EIB/KNX|EIB/KNX Komponenten]]
* [[:Kategorie:FS20 Components|FS20 Komponenten]]
* [[:Kategorie:EnOcean Components|EnOcean Komponenten]]
* [[:Kategorie:HomeMatic Components|HomeMatic Komponenten]]
* [[:Kategorie:MAX|MAX! Komponenten]]
* [[:Kategorie:panStamp|panStamp Komponenten]]
* [[:Kategorie:Z-Wave Components|Z-Wave Komponenten]]
* [[:Kategorie:ZigBee|Zigbee Komponenten]]
* [[:Kategorie:IP Components|Geräte mit Webinterface ("IP")]]
* [[:Kategorie:Other Components|Andere Komponenten / Sonstige Systeme]]

<div align="right"><small>'''[[:Kategorie:Hardware|Alle Hardware-Kategorien]]'''</small></div>
</div>

<div class="mainpagebox" style="order: 5; background-color:#F8F8FF;">
'''Ideen und Lösungen'''

* [[:Kategorie:Code_Snippets|Verschiedene kommentierte Lösungen und Code-Schnippsel]]
* [[:Kategorie:Examples|Beispielanwendungen - Hardwarelösungen - Fremdsystemanbindungen]]
* [[Anwendungsszenarien]]
* [[Trick der Woche|Tipp der Woche]]
* [[Wie kann ich...]]?

<div align="right"><small>'''[[:Kategorie:FHEM|FHEM-Haupt-Kategorien]]'''</small></div>
</div>

<div class="mainpagebox" style="order: 7; background-color:#FFFFE7;">
'''Developers Corner'''

* Informationen zur Modul-Entwicklung:
** [[DevelopmentModuleIntro|Development Module Introduction]]
** [[DevelopmentModuleAPI|Development Module API]]
** [[DevelopmentFHEMWEB-API|Development FHEMWEB API]]
** [[Blocking Call]]
** [[CoProcess]]
** [[HttpUtils]]
** [[DevIo]]
** [[Meta]]
** [[Guidelines zur Dokumentation]]
** [[DevelopmentGuidelinesAV|Development Guidelines AV-Module]]

* Organisatorisches:
** [[How to write a patch]]
** [[SVN Nutzungsregeln]]

<div align="right"><small>'''[[:Kategorie:Development|Alle Artikel zu Development]]'''</small></div>
</div>

<div class="mainpagebox" style="order: 3; background-color:#d7ffff;">
'''FHEM Wiki News'''
<div style="height:20em;overflow:scroll;overflow-x:hidden;">{{FHEMWiki_News}}</div>
<div align="right"><small>'''Mehr [[FHEMWiki:News|News]]'''</small></div>
</div>

<div class="mainpagebox" style="order: 2; background-color:#e7f8ff;">
'''Was ist FHEM Wiki?'''

Das '''FHEM Wiki''' ergänzt die stets tagesaktuelle, von den zuständigen Entwicklern gepflegte {{Link2CmdRef}} (Befehls-Referenz) um weitergehende Informationen rund um FHEM. Im Wiki arbeiten Nutzer und Entwickler gemeinsam an zusätzlicher Dokumentation von FHEM und damit zusammenhängenden Themen.

Das FHEMWiki stellt neben der {{Link2CmdRef}}, dem [http://forum.fhem.de/ Forum] und der [http://www.fhem.de FHEM] Seite die zentrale Informationsquelle rund um FHEM dar. Bedeutung und Zusammenspiel dieser Elemente [[Dokumentationsstruktur|ist hier]] erläutert.


Bitte [[FHEMWiki:Support | unterstütze uns]] und hilf, [[:Kategorie:NeedsEditing| das Wiki zu erweitern]]. Vielen Dank!

<div align="right"><small>'''Mehr [[FHEMWiki:Über_FHEMWiki|über FHEMWiki]]'''</small></div>
</div>

<div class="mainpagebox" style="order: 8; background-color:#F8F8FF;">
'''Letzte Änderungen'''
<div style="font-size:small;color:black;"><small>{{Special:Recentchanges/8}}</small></div>
<div align="right"><small>'''Mehr [[Special:Recentchanges|Änderungen]]'''</small></div>
</div>

<div class="mainpagebox" style="order: 9; flex: 1 1 80%; background-color:#FFFFAA;">
'''Die letzten fünf neuen Seiten'''
<small>{{Special:NewPages/5}}</small>
<div align="right"><small>'''Mehr [[Special:NewPages|Neue Seiten]]'''</small></div>
</div>

<div class="mainpagebox" style="order: 10; background-color:#DDD68F;">
'''Administratives zum Wiki'''

''Allgemeine Aktivitäten:''
* Registrierung zur Mitarbeit: wende Dich bitte an einen [[FHEMWiki:Administratoren|Administrator]]
* Basiswissen über die Mitarbeit an einem Wiki erarbeiten ([http://de.wikipedia.org/wiki/Wikipedia:Beteiligen z.B. Wikipedia])
* Erweiterung und Korrektur von Artikeln, wo immer nötig
* Ein(ig)e der [[Spezial:Gewünschte Seiten|gewünschten Seiten]] erstellen
* Ideen aus dem [http://forum.fhem.de Forum] in bestehende oder neue Artikel einarbeiten
* [[Spezial:Verwaiste Seiten|verwaiste Seiten]] in sinnvoller Weise verlinken
* [[Spezial:Sackgassenseiten|Sackgassenseiten]] wikifizieren (Links auf andere Seiten einfügen)
* [[Datei:Info_red.png|20px]] '''Tips / Regeln / Hinweise auf "[[FHEMWiki:Über FHEMWiki|Über FHEMWiki]]" beachten!''' [[Datei:Info_red.png|20px]]

''Sonstiges:''
* Zum Ausprobieren bitte die [[FHEMWiki:Sandbox]] benutzen
* [//meta.wikimedia.org/wiki/Help:Contents Wiki Benutzerhandbuch].
* [//www.mediawiki.org/wiki/Manual:Configuration_settings Liste der Wiki-Konfigurationsvariablen]
* [//www.mediawiki.org/wiki/Manual:FAQ MediaWiki FAQ]
* [[FHEMWiki:Interna|Internes zu diesem Wiki]]
</div>

</div>
[[Kategorie:FHEM]]

Meta

2019-07-11T12:49:50Z

Loredo:

= Development Module and Package Meta Data =

== Einleitung ==

Neben den für ein FHEM Modul notwendigen [[DevelopmentModuleIntro|obligatorischen]] Metadaten (CommandRef, Kurzbeschreibung, Typ), gibt es in FHEM das Perl Package FHEM::Meta (oder kurz Meta.pm). Die Einbindung in ein FHEM Modul (= stellt Devices zur Verfügung) oder ein FHEM Package (= stellt Subroutinen für ein oder mehrere FHEM Module bereit) ermöglicht es, Informationen über das Modul in Form eines JSON [https://perldoc.perl.org/perlpod.html Pod] (auch META.json genannt) direkt in die Datei mit einzubetten. Darüber wird es möglich, diese Zusatzinformationen auch bereits auszuwerten und anzuzeigen, ohne dass ein Modul bereits geladen oder verwendet wird. Beispielsweise kann ermittelt werden, welche Perl Module für die Nutzung des Moduls notwendig sind und ob eine bestimmte Version vorausgesetzt wird. Außerdem können Informationen über die Version des Moduls, die Historie, den Autor, für Supportanfragen und vieles weiteres hinterlegt werden.

Das Grundschema für die JSON Struktur basiert dabei auf der offiziellen [https://metacpan.org/pod/CPAN::Meta::Spec CPAN::Meta::Spec] Spezifikation, welche auch bei regulär veröffentlichten Perl Modulen verwendet wird. Das FHEM::Meta Package hilft dabei, diese JSON Informationen aus der Datei auszulesen und stellt diese im globalen %modules Hash des jeweiligen Moduls zur weiteren Verarbeitung bereit. Meta wertet dabei die in der Moduldatei (bei Modulen, die im SVN veröffentlicht sind, auch die in FHEM bereits bekannten) hinterlegten Maintenance und Supportdaten aus, so dass diese Informationen für sämtliche FHEM Module grundsätzlich bereitgestellt werden können. Meta erweitert die Standard Spezifikation dafür mit eigenen JSON Attributen, die spezifikationskonform im Namen mit <code>x_</code> beginnen. Diese Art, zusätzliche Informationen über die Funktionalität eines Modules bereitzustellen, ohne dass ein Modul dafür tatsächlich geladen werden muss, steht jedem Modul als Erweiterung zur Verfügung. Es ist also denkbar, dass Module darüber bekanntmachen, welche Netzwerk-Protokolle sie beherrschen, wie bestimmte Geräte im Netzwerk gefunden werden können und mit welchen define-Parametern ein Gerät in FHEM angelegt werden kann. Hierzu gibt es erste Ansätze, die sich in [https://forum.fhem.de/index.php/topic,67368.0.html Planung] befinden.

== Der FHEM Installer ==

Der FHEM Installer ist ein FHEM Modul, welches ein graphisches Interface für die Metadaten bereitstellt. Mit Hilfe des FHEM Installers werden die Metadaten auch für Module in den Speicher geladen, welche keine explizite Unterstützung eingebaut haben. Sobald man die Informationen für ein bestimmtes Modul oder Package abfragt, wird der Meta-Hash über die Funktion FHEM::Meta::Load() geladen. Für FHEM Module, die beim Start von FHEM bereits in Verwendung sind, werden die Metadaten automatisch im Voraus geladen, so dass sie zur Laufzeit zur Verfügung stehen. Es ist geplant, dass dies auch zur Laufzeit für Module, für die der Benutzer ein neues Device anlegt, geschieht.

Die Grundfunktion des FHEM Installer ist jedoch nicht die Bereitstellung der Metadaten, sondern die Auswertung derselben. In seiner weiteren Entwicklung soll er dabei unterstützen fehlende Systemkomponenten, die für die Nutzung eines FHEM Moduls notwendig sind, zu installieren und aktuell zu halten. Die Installation und Aktualisierung von Perl Modulen ist bereits jetzt in einer ersten Ausbaustufe möglich.

Stellt man am FHEM Installer Device das Attribut <code>installerMode</code> auf developer, dann werden einige weitere Get Befehle sichtbar, über die sich auch der Inhalt des kummulierten META.json Hashes anzeigen lässt. Dies ist oft hilfreich für ein initiales Verständnis, welche Informationen FHEM::Meta bereits über ein Modul gesammelt hat, bevor man diese über einen eigenen META.json Pod in der Moduldatei ergänzen oder verändern möchte.

Hinweis: Die Weiterentwicklung von FHEM::Meta ist stark an die weitere Entwicklung des FHEM Installer geknüpft. Dort geht es dann insbesondere darum, dass FHEM Module aus anderen Installationsquellen neben dem SVN die gleiche Metadaten einliefern können, insbesondere was Versionierung und Historie angehen. Dieses und mehr ist jedoch ein ganz eigenes Kapitel und soll deshalb für das Thema FHEM::Meta nur kurz erwähnt sein.

== Der search-Befehl ==

Der FHEM Befehl <code>search</code> ist ein Wrapper, um den Get-Befehl <code>search</code> beim FHEM Installer Device im Schnellzugriff über die FHEM Befehlszeile aufzurufen. Hierüber lassen sich die Metadaten aller FHEM Module durchsuchen und ermöglicht so das Auffinden von FHEM Modulen für eine bestimmte Funktion oder ein Gebiet. FHEM Module, die einen META.json Pod bereitstellen, können dort Schlagworte hinterlegen, über die das Modul in der Suche gefunden werden können soll. FHEM::Meta generiert für Module, die über das SVN bereitgestellt werden, bereits einige Schlagworte basierend auf dem hinterlegten Support Forum in MAINTAINER.txt. Auch Der Modul Typ (helper|device|command) findet sich als eigenes Schlagwort wieder. Man erhält also Out-of-the-Box bereits eine ziemlich gute Kategorisierung über den Anwendungsbereich eines bestimmten Moduls und welche anderen Module noch in diesen Bereich fallen. Ein Modulname alleine hingegen lässt oftmals nicht auf die Funktionalität dahinter schließen, insbesondere wenn Hersteller- oder Produktnamen eine Rolle spielen, die man selbst bisher nicht kennt.

== Erweiterung eines FHEM Moduls mit META.json Pod ==

Möchte ein Modulautor aktiven Support FHEM::Meta einbauen, dann ist der erste Schritt die Bereitstellung eines META.json Abschnitts am Ende der Modul- oder Paketdatei. Dieser Abschnitt beinhaltet ein reguläres JSON Objekt. Deshalb empfiehlt es sich den Abschnitt vor dem hinzufügen über einen JSON Validator auf seine Syntax zu überprüfen. Ansonsten wird von FHEM::Meta beim laden eine entsprechende Meldung im FHEM Log ausgegeben und es werden keinerlei Metadaten mehr über das Modul bereitgestellt. Sobald ein META.json Abschnitt vorhanden ist, geht FHEM::Meta davon aus, dass dieses maßgeblich ist und wird deshalb nur noch Daten ergänzen, die dort nicht enthalten sind. Fehlt also ein valides META.json Objekt als Basis, so werden auch diese Ergänzungen nicht erfolgen und der Modulautor muss zunächst zwingend das JSON Gerüst korrigieren.

Für das Hinzufügen des META.json Abschnitts kann man mit der Beispieldatei [https://svn.fhem.de/trac/browser/trunk/fhem/contrib/META.json.txt contrib/META.json.txt] als Ausgangsbasis starten. Die oben erwähnte Spezifikation sollte man einmal gelesen haben um zu verstehen, welches Format für ein Datenfeld gilt und welche Angaben die Spezifikation als zwingend vorschreibt. Es ist empfehlenswert alle dort als ''mandatory'' erwähnten Angaben in META.json anzugeben, auch wenn diese Informationen vielleicht teilweise in anderen Dateien in FHEM bereits vorhanden sind (gilt natürlich nur für Module, die auch über das SVN verteilt werden). Beispielsweise sollte eine (Kurz-)Beschreibung trotzdem enthalten sein. Der Grund ist, dass zumindest theoretisch dann auch andere 3rd-party Tools, die mit Perl Modulen hantieren, diese Informationen in vereinfachter Art ebenfalls auslesen und auswerten können. Diese Tools könnten darauf bestehen, dass sie eben diese als zwingend spezifizierten Attribute dort auch vorfinden. FHEM::Meta fügt fehlende Informationen zwar zur Laufzeit selbst hinzu, dies hilt jedoch anderen Tools, die das JSON Objekt direkt auswerten, eben nicht. Wie genau ein Modulautor dieser Empfehlung folgen möchte, ist ihm überlassen.

Die Inhalte aus der Beispieldatei oben sollten als Mindestvoraussetzung angesehen werden. Insbesondere der Abschnitt <code>prereqs</code> für verwendete Perl Module ist hier wichtig, da das Vorhandensein eines selben eine wesentlich schnellere Ladezeit der Metainformationen zur Folge hat, da die Abhängigkeiten nicht durch eine Analyse erfolgen muss. Das bedeutet jedoch auch, dass diese Informationen vollständig sein müssen und der Autor dafür verantwortlich ist, das diese stimmig sind. Als Hilfestellung, was man hier für sein Modul eintragen sollte, kann man sichüber den FHEM Installer im oben erwähnten Developer-Modus das über das Analyse-Verfahren erzeugte META.json ansehen und dort den entsprechenden prereqs Abschnitt kopieren. Im Grunde werden dort alle "use" und "require" Aufrufe, die ein Modul macht, aufgeführt. Das schließt auch den Aufruf von Perl Builtin Funktionen wie "use strict;" oder ähnliches ein. Es ist empfehlenswert diese hier ebenfalls mit aufzuführen. Über die Metadaten kann man dann auch als FHEM Entwickler entsprechende Statistiken über die Code/Modul Qualität (so man die Nutzung von "use strict;" denn beispielhaft als positiv wirkend interpretieren möchte) fahren.

Hat man das JSON Objekt für sein Modul nun also fertig, dann kopiert man es in seine Moduldatei ''hinter'' den letzten commandRef Abschnitt und ''vor'' der Schlussformel <code>=cut</code>. Dabei wird das META.json Objekt von folgender Markierung umschlossen:

<syntaxhighlight lang="perl">
=for :application/json;q=META.json 00_myModule.pm
{ ... }
=end :application/json;q=META.json
</syntaxhighlight>

Dabei ist 00_myModule.pm durch den Dateinamen der jeweiligen Moduldatei zu ersetzen. Auf diese Weise wird sichergestellt, dass eine Metainformation auch wirklich zu genau dieser Moduldatei dazugehört.
Alle Informationen innerhalb des META.json sind im UTF-8 Format. Dies machen wir deshalb zusätzlich nochmals zum Beginn des <code>=pod</code> Abschnitts ''vor'' dem ersten CommandRef Eintrag deutlich:

<syntaxhighlight lang="perl">
=pod

=encoding utf8

=for :application/json;q=META.json 00_myModule.pm
{ ... }
=end :application/json;q=META.json

=cut
</syntaxhighlight>

Ein komplettes Beispiel, wie sich der META.json Abschnitt in eine Moduldatei einfügt, zeigt die Datei [https://svn.fhem.de/trac/browser/trunk/fhem/contrib/META.json.full.txt contrib/META.json.full.txt].
Für Fortgeschrittene sind dort außerdem weitere Beispieleinträge für Metadaten, die der FHEM Installer auswerten und verarbeiten kann.

Hat man nun also den META.json Abschnitt ordnungsgemäß hinzugefügt, kann man mit Hilfe des FHEM Installer überprüfen, ob die Daten richtig hinterlegt worden sind und geladen werden können.

== Eigenständiges Laden der Metadaten aus einem FHEM Modul heraus ==

Ein FHEM Modul kann selbstständig die Unterstützung für das Laden der Metadaten in den %modules Hash einbauen, um diese unabhängig vom FHEM Installer zur Verfügung zu haben.
Hierfür muss am Beginn der Moduldatei zunächst <code>use FHEM::Meta;</code> hinzugefügt werden und die <code>X_Initialize();</code> Funktion am Ende um einen Initialisierungsaufruf erweitert werden:

<syntaxhighlight lang="perl">
use FHEM::Meta;

sub X_Initialize($)
{
my ($hash) = @_;
...

return FHEM::Meta::InitMod( __FILE__, $hash );
}
</syntaxhighlight>

Die Metadaten werden dann beim Initialisieren des Moduls nach $modules{<TYPE>}{META} geladen und stehen dort bereit.

== Anzeigen der Modulversion über FHEM::Meta ==

Im META.json Objekt kann eine Version des Moduls explizit in [https://semver.org/ semantischer Form] (beispielsweise v1.2.3) angegeben werden. Ist dies nicht der Fall, dann generiert FHEM::Meta eine eigene Versionsnummer auf Basis der Revisionsnummer aus dem Subversion Repository im <code>$Id$</code> Abschnitt der Moduldatei. Dies gilt jedoch nur für Module, die auch tatsächlich über das SVN verteilt werden, ansonsten wird dieser Abschnitt ignoriert. Durch die Angabe der Versionsnummer im META.json Objekt wird es somit erstmals möglich, dass auch Module außerhalb des SVN mit einer einheitlichen Art der Versionierung auftreten können.
Eine semantische Versionsnummer wird von FHEM::Meta automatisch über die Perl Builtin Module version in einen Float Wert umgewandelt, um nummerische Vergleiche zu ermöglichen.

FHEM::Meta bietet eine Funktion, um die essentiellen Metadaten zum Versionsstand eines Moduls als Internal mit dem Namen FVERSION anzuzeigen. Dafür kann man an den Beginn der <code>X_Define()</code> Funktion folgenden Aufruf setzen:

==== X_Define ====
<syntaxhighlight lang="perl">
sub X_Define($$)
{
my ( $hash, $def ) = @_;
return $@ unless ( FHEM::Meta::SetInternals($hash) );
...

return $error;
}
</syntaxhighlight>

Zum aktuellen Zeitpunkt wird hierdurch lediglich das Internal FVERSION gesetzt. Dieses sieht dann beispielsweise so aus:

<code>
00_myModule.pm:v0.5.6-s19500/2019-05-30
</code>

Als Informationen sind hier verpackt:
* Dateiname des Moduls inkl. Präfix
* semantische Version (version-Attribut in META.json vorhanden)
* Subversion Revision (-s steht für "Subversion", danach folgt die Revisionsnummer des jeweiligen Commits)
* das Release Datum (hier konkret das Check-in Datum in das SVN)

Für Module außerhalb des SVN werden diese Informationen entsprechend anders zusammengetragen oder müssen/können über das META.json Objekt bereitgestellt werden.
Hierbei ist zu erwähnen, dass ein FHEM Modul erst dann als dem SVN zugehörig angesehen wird, wenn es einen Eintrag in MAINTAINER.txt hat. Fehlt dieser Eintrag, dann wird das Modul nicht als FHEM Core Modul behandelt, sondern als externes 3rd-party Modul.

Meta

2019-07-11T12:49:01Z

Loredo: Die Seite wurde neu angelegt: „= Development Module and Package Meta Data = == Einleitung == Neben den für ein FHEM Modul notwendigen obligatorischen Metadaten…“

= Development Module and Package Meta Data =

== Einleitung ==

Neben den für ein FHEM Modul notwendigen [[DevelopmentModuleIntro|obligatorischen]] Metadaten (CommandRef, Kurzbeschreibung, Typ), gibt es in FHEM das Perl Package FHEM::Meta (oder kurz Meta.pm). Die Einbindung in ein FHEM Modul (= stellt Devices zur Verfügung) oder ein FHEM Package (= stellt Subroutinen für ein oder mehrere FHEM Module bereit) ermöglicht es, Informationen über das Modul in Form eines JSON [https://perldoc.perl.org/perlpod.html Pod] (auch META.json genannt) direkt in die Datei mit einzubetten. Darüber wird es möglich, diese Zusatzinformationen auch bereits auszuwerten und anzuzeigen, ohne dass ein Modul bereits geladen oder verwendet wird. Beispielsweise kann ermittelt werden, welche Perl Module für die Nutzung des Moduls notwendig sind und ob eine bestimmte Version vorausgesetzt wird. Außerdem können Informationen über die Version des Moduls, die Historie, den Autor, für Supportanfragen und vieles weiteres hinterlegt werden.

Das Grundschema für die JSON Struktur basiert dabei auf der offiziellen [https://metacpan.org/pod/CPAN::Meta::Spec CPAN::Meta::Spec] Spezifikation, welche auch bei regulär veröffentlichten Perl Modulen verwendet wird. Das FHEM::Meta Package hilft dabei, diese JSON Informationen aus der Datei auszulesen und stellt diese im globalen %modules Hash des jeweiligen Moduls zur weiteren Verarbeitung bereit. Meta wertet dabei die in der Moduldatei (bei Modulen, die im SVN veröffentlicht sind, auch die in FHEM bereits bekannten) hinterlegten Maintenance und Supportdaten aus, so dass diese Informationen für sämtliche FHEM Module grundsätzlich bereitgestellt werden können. Meta erweitert die Standard Spezifikation dafür mit eigenen JSON Attributen, die spezifikationskonform im Namen mit <code>x_</code> beginnen. Diese Art, zusätzliche Informationen über die Funktionalität eines Modules bereitzustellen, ohne dass ein Modul dafür tatsächlich geladen werden muss, steht jedem Modul als Erweiterung zur Verfügung. Es ist also denkbar, dass Module darüber bekanntmachen, welche Netzwerk-Protokolle sie beherrschen, wie bestimmte Geräte im Netzwerk gefunden werden können und mit welchen define-Parametern ein Gerät in FHEM angelegt werden kann. Hierzu gibt es erste Ansätze, die sich in [https://forum.fhem.de/index.php/topic,67368.0.html Planung] befinden.

== Der FHEM Installer ==

Der FHEM Installer ist ein FHEM Modul, welches ein graphisches Interface für die Metadaten bereitstellt. Mit Hilfe des FHEM Installers werden die Metadaten auch für Module in den Speicher geladen, welche keine explizite Unterstützung eingebaut haben. Sobald man die Informationen für ein bestimmtes Modul oder Package abfragt, wird der Meta-Hash über die Funktion FHEM::Meta::Load() geladen. Für FHEM Module, die beim Start von FHEM bereits in Verwendung sind, werden die Metadaten automatisch im Voraus geladen, so dass sie zur Laufzeit zur Verfügung stehen. Es ist geplant, dass dies auch zur Laufzeit für Module, für die der Benutzer ein neues Device anlegt, geschieht.

Die Grundfunktion des FHEM Installer ist jedoch nicht die Bereitstellung der Metadaten, sondern die Auswertung derselben. In seiner weiteren Entwicklung soll er dabei unterstützen fehlende Systemkomponenten, die für die Nutzung eines FHEM Moduls notwendig sind, zu installieren und aktuell zu halten. Die Installation und Aktualisierung von Perl Modulen ist bereits jetzt in einer ersten Ausbaustufe möglich.

Stellt man am FHEM Installer Device das Attribut <code>installerMode</code> auf developer, dann werden einige weitere Get Befehle sichtbar, über die sich auch der Inhalt des kummulierten META.json Hashes anzeigen lässt. Dies ist oft hilfreich für ein initiales Verständnis, welche Informationen FHEM::Meta bereits über ein Modul gesammelt hat, bevor man diese über einen eigenen META.json Pod in der Moduldatei ergänzen oder verändern möchte.

Hinweis: Die Weiterentwicklung von FHEM::Meta ist stark an die weitere Entwicklung des FHEM Installer geknüpft. Dort geht es dann insbesondere darum, dass FHEM Module aus anderen Installationsquellen neben dem SVN die gleiche Metadaten einliefern können, insbesondere was Versionierung und Historie angehen. Dieses und mehr ist jedoch ein ganz eigenes Kapitel und soll deshalb für das Thema FHEM::Meta nur kurz erwähnt sein.

== Der search-Befehl ==

Der FHEM Befehl <code>search</code> ist ein Wrapper, um den Get-Befehl <code>search</code> beim FHEM Installer Device im Schnellzugriff über die FHEM Befehlszeile aufzurufen. Hierüber lassen sich die Metadaten aller FHEM Module durchsuchen und ermöglicht so das Auffinden von FHEM Modulen für eine bestimmte Funktion oder ein Gebiet. FHEM Module, die einen META.json Pod bereitstellen, können dort Schlagworte hinterlegen, über die das Modul in der Suche gefunden werden können soll. FHEM::Meta generiert für Module, die über das SVN bereitgestellt werden, bereits einige Schlagworte basierend auf dem hinterlegten Support Forum in MAINTAINER.txt. Auch Der Modul Typ (helper|device|command) findet sich als eigenes Schlagwort wieder. Man erhält also Out-of-the-Box bereits eine ziemlich gute Kategorisierung über den Anwendungsbereich eines bestimmten Moduls und welche anderen Module noch in diesen Bereich fallen. Ein Modulname alleine hingegen lässt oftmals nicht auf die Funktionalität dahinter schließen, insbesondere wenn Hersteller- oder Produktnamen eine Rolle spielen, die man selbst bisher nicht kennt.

== Erweiterung eines FHEM Moduls mit META.json Pod ==

Möchte ein Modulautor aktiven Support FHEM::Meta einbauen, dann ist der erste Schritt die Bereitstellung eines META.json Abschnitts am Ende der Modul- oder Paketdatei. Dieser Abschnitt beinhaltet ein reguläres JSON Objekt. Deshalb empfiehlt es sich den Abschnitt vor dem hinzufügen über einen JSON Validator auf seine Syntax zu überprüfen. Ansonsten wird von FHEM::Meta beim laden eine entsprechende Meldung im FHEM Log ausgegeben und es werden keinerlei Metadaten mehr über das Modul bereitgestellt. Sobald ein META.json Abschnitt vorhanden ist, geht FHEM::Meta davon aus, dass dieses maßgeblich ist und wird deshalb nur noch Daten ergänzen, die dort nicht enthalten sind. Fehlt also ein valides META.json Objekt als Basis, so werden auch diese Ergänzungen nicht erfolgen und der Modulautor muss zunächst zwingend das JSON Gerüst korrigieren.

Für das Hinzufügen des META.json Abschnitts kann man mit der Beispieldatei [https://svn.fhem.de/trac/browser/trunk/fhem/contrib/META.json.txt contrib/META.json.txt] als Ausgangsbasis starten. Die oben erwähnte Spezifikation sollte man einmal gelesen haben um zu verstehen, welches Format für ein Datenfeld gilt und welche Angaben die Spezifikation als zwingend vorschreibt. Es ist empfehlenswert alle dort als ''mandatory'' erwähnten Angaben in META.json anzugeben, auch wenn diese Informationen vielleicht teilweise in anderen Dateien in FHEM bereits vorhanden sind (gilt natürlich nur für Module, die auch über das SVN verteilt werden). Beispielsweise sollte eine (Kurz-)Beschreibung trotzdem enthalten sein. Der Grund ist, dass zumindest theoretisch dann auch andere 3rd-party Tools, die mit Perl Modulen hantieren, diese Informationen in vereinfachter Art ebenfalls auslesen und auswerten können. Diese Tools könnten darauf bestehen, dass sie eben diese als zwingend spezifizierten Attribute dort auch vorfinden. FHEM::Meta fügt fehlende Informationen zwar zur Laufzeit selbst hinzu, dies hilt jedoch anderen Tools, die das JSON Objekt direkt auswerten, eben nicht. Wie genau ein Modulautor dieser Empfehlung folgen möchte, ist ihm überlassen.

Die Inhalte aus der Beispieldatei oben sollten als Mindestvoraussetzung angesehen werden. Insbesondere der Abschnitt <code>prereqs</code> für verwendete Perl Module ist hier wichtig, da das Vorhandensein eines selben eine wesentlich schnellere Ladezeit der Metainformationen zur Folge hat, da die Abhängigkeiten nicht durch eine Analyse erfolgen muss. Das bedeutet jedoch auch, dass diese Informationen vollständig sein müssen und der Autor dafür verantwortlich ist, das diese stimmig sind. Als Hilfestellung, was man hier für sein Modul eintragen sollte, kann man sichüber den FHEM Installer im oben erwähnten Developer-Modus das über das Analyse-Verfahren erzeugte META.json ansehen und dort den entsprechenden prereqs Abschnitt kopieren. Im Grunde werden dort alle "use" und "require" Aufrufe, die ein Modul macht, aufgeführt. Das schließt auch den Aufruf von Perl Builtin Funktionen wie "use strict;" oder ähnliches ein. Es ist empfehlenswert diese hier ebenfalls mit aufzuführen. Über die Metadaten kann man dann auch als FHEM Entwickler entsprechende Statistiken über die Code/Modul Qualität (so man die Nutzung von "use strict;" denn beispielhaft als positiv wirkend interpretieren möchte) fahren.

Hat man das JSON Objekt für sein Modul nun also fertig, dann kopiert man es in seine Moduldatei ''hinter'' den letzten commandRef Abschnitt und ''vor'' der Schlussformel <code>=cut</code>. Dabei wird das META.json Objekt von folgender Markierung umschlossen:

<syntaxhighlight lang="perl">
=for :application/json;q=META.json '''00_myModule.pm'''
{ ... }
=end :application/json;q=META.json
</syntaxhighlight>

Dabei ist 00_myModule.pm durch den Dateinamen der jeweiligen Moduldatei zu ersetzen. Auf diese Weise wird sichergestellt, dass eine Metainformation auch wirklich zu genau dieser Moduldatei dazugehört.
Alle Informationen innerhalb des META.json sind im UTF-8 Format. Dies machen wir deshalb zusätzlich nochmals zum Beginn des <code>=pod</code> Abschnitts ''vor'' dem ersten CommandRef Eintrag deutlich:

<syntaxhighlight lang="perl">
=pod

'''=encoding utf8'''

=for :application/json;q=META.json 00_myModule.pm
{ ... }
=end :application/json;q=META.json

=cut
</syntaxhighlight>

Ein komplettes Beispiel, wie sich der META.json Abschnitt in eine Moduldatei einfügt, zeigt die Datei [https://svn.fhem.de/trac/browser/trunk/fhem/contrib/META.json.full.txt contrib/META.json.full.txt].
Für Fortgeschrittene sind dort außerdem weitere Beispieleinträge für Metadaten, die der FHEM Installer auswerten und verarbeiten kann.

Hat man nun also den META.json Abschnitt ordnungsgemäß hinzugefügt, kann man mit Hilfe des FHEM Installer überprüfen, ob die Daten richtig hinterlegt worden sind und geladen werden können.

== Eigenständiges Laden der Metadaten aus einem FHEM Modul heraus ==

Ein FHEM Modul kann selbstständig die Unterstützung für das Laden der Metadaten in den %modules Hash einbauen, um diese unabhängig vom FHEM Installer zur Verfügung zu haben.
Hierfür muss am Beginn der Moduldatei zunächst <code>use FHEM::Meta;</code> hinzugefügt werden und die <code>X_Initialize();</code> Funktion am Ende um einen Initialisierungsaufruf erweitert werden:

<syntaxhighlight lang="perl">
'''use FHEM::Meta;'''

sub X_Initialize($)
{
my ($hash) = @_;
...

'''return FHEM::Meta::InitMod( __FILE__, $hash );'''
}
</syntaxhighlight>

Die Metadaten werden dann beim Initialisieren des Moduls nach $modules{<TYPE>}{META} geladen und stehen dort bereit.

== Anzeigen der Modulversion über FHEM::Meta ==

Im META.json Objekt kann eine Version des Moduls explizit in [https://semver.org/ semantischer Form] (beispielsweise v1.2.3) angegeben werden. Ist dies nicht der Fall, dann generiert FHEM::Meta eine eigene Versionsnummer auf Basis der Revisionsnummer aus dem Subversion Repository im <code>$Id$</code> Abschnitt der Moduldatei. Dies gilt jedoch nur für Module, die auch tatsächlich über das SVN verteilt werden, ansonsten wird dieser Abschnitt ignoriert. Durch die Angabe der Versionsnummer im META.json Objekt wird es somit erstmals möglich, dass auch Module außerhalb des SVN mit einer einheitlichen Art der Versionierung auftreten können.
Eine semantische Versionsnummer wird von FHEM::Meta automatisch über die Perl Builtin Module version in einen Float Wert umgewandelt, um nummerische Vergleiche zu ermöglichen.

FHEM::Meta bietet eine Funktion, um die essentiellen Metadaten zum Versionsstand eines Moduls als Internal mit dem Namen FVERSION anzuzeigen. Dafür kann man an den Beginn der <code>X_Define()</code> Funktion folgenden Aufruf setzen:

==== X_Define ====
<syntaxhighlight lang="perl">
sub X_Define($$)
{
my ( $hash, $def ) = @_;
'''return $@ unless ( FHEM::Meta::SetInternals($hash) );'''
...

return $error;
}
</syntaxhighlight>

Zum aktuellen Zeitpunkt wird hierdurch lediglich das Internal FVERSION gesetzt. Dieses sieht dann beispielsweise so aus:

<code>
00_myModule.pm:v0.5.6-s19500/2019-05-30
</code>

Als Informationen sind hier verpackt:
* Dateiname des Moduls inkl. Präfix
* semantische Version (version-Attribut in META.json vorhanden)
* Subversion Revision (-s steht für "Subversion", danach folgt die Revisionsnummer des jeweiligen Commits)
* das Release Datum (hier konkret das Check-in Datum in das SVN)

Für Module außerhalb des SVN werden diese Informationen entsprechend anders zusammengetragen oder müssen/können über das META.json Objekt bereitgestellt werden.
Hierbei ist zu erwähnen, dass ein FHEM Modul erst dann als dem SVN zugehörig angesehen wird, wenn es einen Eintrag in MAINTAINER.txt hat. Fehlt dieser Eintrag, dann wird das Modul nicht als FHEM Core Modul behandelt, sondern als externes 3rd-party Modul.

Modul Astro

2019-06-22T09:08:25Z

Loredo:

{{
Infobox Modul
|ModPurpose=Das Modul stellt astronomische Daten zur Verfügung (etwa Sonnenauf- und Untergänge)
|ModType=h

|ModCmdRef=Astro
|ModForumArea=Unterstuetzende Dienste
|ModTechName=95_Astro.pm
|ModOwner=Prof. Dr. Peter A. Henning
}}
Diese Seite beschreibt die Konfiguration und Verwendung des Moduls 95_Astro.pm.

=Allgemeines=
Das Modul ''95_Astro.pm'' stellt astronomische Daten zur Verfügung (etwa Sonnenauf- und Untergänge). Die Berechungen sind für den Zeitraum 1900 - 2100 gültig.

Ein SVG-Bild der gegenwärtigen Mondphase gibt es unter dem Link
<ip addresse von fhem>/fhem/Astro_moonwidget?name='<device name>'
Optionale Web-Parameter sind
[&size='<width>x<height>']
[&mooncolor=<color>]
[&moonshadow=<color>]

<li>Calculations are only valid between the years 1900 and 2100</li>
<li>Attention: Timezone is taken from the local Perl settings, NOT automatically defined for a location</li>
<li>This module uses the global attribute <code>language</code> to determine its output data<br/>
(default: EN=english). For German output set <code>attr global language DE</code>.</li>
<li>The time zone is determined automatically from the local settings of the <br/>
operating system. If geocordinates from a different time zone are used, the results are<br/>
not corrected automatically.
==Definition==
Ein Astro-Device wird definiert durch
define <name> Astro
Dieses Modul verwendet das globale Attribut language zur Bestimmung der Anzeigedaten (Standard: EN=english). Für deutsche Ausgabedaten muss in FHEM das Attribut
attr global language DE
gesetzt werden.
==Position des Beobachters==
Das Modul verwendet verschiedene Attribute zur Bestimmung der Beobachterdefinition, die im ''global''-Device von FHEM abgelegt sein sollten:
attr global longitude <value>
attr global latitude <value>
attr global altitude <value>
Die beiden ersten Angaben erfolgen in Dezimalgrad, die dritte Angabe ist die Höhe in Metern über dem Meeresspiegel. Globale Definitionen dieser Werte werden nur verwendet, wenn keine lokalen Attribute mit diesen Namen vorhanden sind (siehe unten).

Die Zeitzone wird nicht automatisch eingestellt, sondern aus der lokalen Perl-Installation bezogen.

==Ausgabedaten==
Readings mit dem Präfix <i>Sun</i> beziehen sich auf die Sonne, solche mit dem Präfix <i>Moon</i> auf den Mond.
*<i>Age</i> = Winkel (in Dezimalgrad) des Körpers auf seiner Bahn
*<i>Az,Alt</i> = Azimuth und Höhe (in Dezimalgrad) des Körpers über dem Horizont
*<i>Dec,Ra</i> = Deklination und Rektaszension (in HH:MM) der Position des Körpers
*<i>Lat,Lon</i> = geografische Breite und Länge der Position des Körpers
*<i>Diameter</i> = Virtueller Durchmesser des Körpers in Bogenminuten
*<i>Distance,DistanceObserver</i> = Entfernung (in km) des Körpers zum Erdmittelpunkt oder zum Beobachter
*<i>PhaseN,PhaseS</i> = Nummerischer Wert und Stringwert für die Phase des Körpers</li>
*<i>Sign</i> = Tierkreiszeichen des Körpers auf seiner Bahn
*<i>Rise,Transit,Set</i> = Zeiten (in HH:MM) für Aufgang, höchsten Punkt (Transit) und Untergang des Körpers

Readings mit dem Präfix <i>Obs</i> beziehen sich auf den Beobachter

Weitere Readings umfassen
*<i>Date,Dayofyear</i> = Datum
*<i>JD</i> = Julianisches Datum
*<i>Season,SeasonN</i> = Stringwert und nummerischer Wert für die Jahreszeit
*<i>Time,Timezone</i> raten Sie mal...
*<i>IsDST</i> = 1 wenn Sommerzeit gilt, 0 sonst
*<i>GMST,LMST</i> = Greenwich und Local Mean Sidereal Time (in HH:MM)

=Bedienung=
==Get==
Achtung: Die Ergebnisse von Get-Aufrufen werden nicht in die Readings geschrieben, sondern nur die Ergebnisse zyklischer Updates. Das dient dazu, schnell und ohne Readings spezielle Datenwerte (etwa für andere Zeiten oder Orte) zu generieren. Möglichkeiten für Aufrufe:
get <name> json [<reading>]
get <name> json [<reading>] YYYY-MM-DD
get <name> json [<reading>] YYYY-MM-DD HH:MM:[SS]
liefert JSON-Code für den kompletten Datensatz oder nur einen Datenwert der astronomischen Daten entweder für die gegenwärtige Zeit, oder für ein Datum und eine Zeit im Argument.
get <name> text [<reading>]
get <name> text [<reading>] YYYY-MM-DD
get <name> text [<reading>] YYYY-MM-DD HH:MM:[SS]
liefert Text für den kompletten Datensatz oder nur einen Datenwert der astronomischen Daten entweder für die gegenwärtige Zeit, oder für ein Datum und eine Zeit im Argument.
get <name> version
zeigt die aktuelle Modulversion an.

==Attribute==
attr <name> <interval>
Update-Interval in Sekunden. Default sind 3600 Sekunden, ein Wert 0 verhindert das periodische Update.
Das Astro-Module verwendet verschiedene Attribute zur Bestimmung der Beobachterdefinition, die entweder im ''global''-Device von FHEM abgelegt sein sollten (siehe oben), oder als lokale Attribute gespeichert sind:
attr <name> longitude <value>
attr <name> latitude <value>
attr <name> altitude <value>
Die beiden ersten Angaben erfolgen in Dezimalgrad, die dritte Angabe ist die Höhe in Metern über dem Meeresspiegel.
attr <name> horizon <value>
Nutzerdefinierter Horizontwinkel in Dezimalgrad, Defaulwert 0°

=Verwendung ohne Astro-Device=
Es ist nicht notwendig, für die gelegentliche Verwendung der astronomischen Daten ein Device zu definieren. Es muss lediglich das Modul geladen werden, z.B. durch den Perl-Code
LoadModule("Astro");
Die Verwendung von ''require'' wird nicht empfohlen, da je nach Konstellation dabei Warnmeldungen im Logfile ausgegeben werden können.
Dann kann man z.B. durch den Code
my $somehash
Astro_Get( $somehash,"somehash","text", "SunRise","2019-12-24");
den Sonnenuntergang an Heiligabend 2019 berechnen.

Die Funktion ''Astro_Get'' bekommt im ersten Argument eine hash-Referenz übergeben, die auch leer sein kann. Wenn sie aber nicht leer ist, versucht das Modul, sich die notwendigen Attribute aus diesem Hash zu holen (etwa geografische Länge und Beite). Es kann z.B. ein beliebiges Dummy-Device angelegt werden, sagen wir mit dem Namen "Blabla". Gibt man diesem als Attribut einen Horizontwinkel, oder andere Geodaten, kann man mit
Astro_Get( $defs{"Blabla"},"Blabla","text", "CustomTwilightEvening","2019-12-24");
den Sonnenuntergang für diesen Horizontwinkel erhalten. Natürlich geht auch
Astro_Get( $defs{"global"},"global","text", <reading>,<datum> );

Tradfri

2019-03-11T00:18:03Z

Loredo: Die Seite wurde neu angelegt: „Das Modul wird hier beschrieben: TRÅDFRI“

Das Modul wird hier beschrieben:
[[TRÅDFRI]]

Siri

2019-03-11T00:16:45Z

Loredo: Die Seite wurde neu angelegt: „Die Funktionsweise wird hier beschrieben: Homebridge_einrichten“

Die Funktionsweise wird hier beschrieben:
[[Homebridge_einrichten]]

Alexa

2019-03-10T21:13:20Z

Loredo:

Es gibt zwei Betriebsmodi für das alexa Modul, die separat beschrieben sind:

# Public FHEM Connector Skill: [[FHEM_Connector]]
# Private Skills: [[Alexa-Fhem|alexa-fhem]]

Alexa

2019-03-10T21:12:20Z

Loredo: Die Seite wurde neu angelegt: „Es gibt zwei Betriebsmodi für das alexa Modul, die separat beschrieben sind: Public FHEM Connector Skill: FHEM_Connector Private Skills: Alexa-Fhem|ale…“

Es gibt zwei Betriebsmodi für das alexa Modul, die separat beschrieben sind:

Public FHEM Connector Skill: [[FHEM_Connector]]
Private Skills: [[Alexa-Fhem|alexa-fhem]]

Weckautomation

2017-04-09T11:15:01Z

Loredo: /* Definition des Weckprogramms */

Die Module ROOMMATE und GUEST können dazu genutzt werden, Bewohner und Gäste in FHEM als ein Device zu repräsentieren und durch Events deren Status zu erfassen bzw. zu ändern (beispielsweise durch das GEOFANCY Modul für [[Anwesenheitserkennung]]). Das zur Modulfamilie dazugehörige Modul RESIDENTS fasst die Status mehrerer Bewohner logisch zusammen.

Inzwischen unterstützen die Module auch bei der Erstellung einer Weckautomation, indem sie die Logik kapseln und häufig verwendete Standardfunktionen bereitstellen. Die Verwendung soll in diesem Artikel anhand eines Beispiels näher erläutert werden.

[[Datei:Weckprogramm_Ergebnisdarstellung.png|500px|thumb|right|Darstellung der Beispiel-Konfiguration]]

== Was soll erreicht werden? ==

Hier ein kurzer Überblick über die Funktionen, die wir am Ende realisiert haben werden:

; 3 unterschiedliche Wecker
: 1 für Werktage Mo-Fr
: 1 für werktägliche Samstage
: 1 für Sonn- und Feiertage
; Automatischer Reset der Weckzeiten
: werktäglicher Wecker soll auf einen Standardwert zurückstellen, falls er mal verstellt wurde
: automatischer Reset des werktäglicher Weckers soll zeitweise abschaltbar sein
: nach einem Sonn- oder Feiertagen soll der automatische Reset des werktäglichen Weckers immer wieder eingeschaltet werden
: die Samstags- und Sonntags-Wecker sollen immer nach ihrer Ausführung resettet werden
; jeder Wecker startet ein Weckprogramm 30 Minuten vor der programmierten Zeit
: langsames hochfahren der Rollläden
: Wakeup Light über eine HUE Birne von Warmweiß/2000K zu Kaltweiß/5600K
: an Werktagen: Chillout Weckmusik wird langsam lauter gestellt
: Snooze Funktion über die SONOS Taste am Gerät an Werktagen (erneutes Play nach 5 Minuten)
: forciertes Aufstehen an Werktagen durch automatischen Wechsel des Bewohner Devices zu "awake" und dadurch starten der "aufgestanden sein" Prozesse (siehe unten)
; Starten des Weckprogramms nur bei tatsächlicher Anwesenheit des betroffenen Bewohners
; Ansage der Uhrzeit zur gewählten Weckzeit
; Prozess / Automation für:
: <u>bettfertig machen</u>: Lichtszene setzen, Chillout Musik in Schlafzimmer und Badezimmer abspielen
: <u>schlafen legen</u>: Ansage der eingestellten Weckzeit & Ausschalten aller Verbraucher
: <u>aufgestanden sein</u>: Ansage Raumluftqualität, Wettervorhersage; Lokalradio einschalten und in Räume verteilen; Küchenlicht an, HUE in Schlafzimmer mit Aufwach-Farbtemperatur
; Berücksichtigung / Steuerung des Haus Modus
: Wechsel zwischen Morgen-, Tag-, Abend- und Nacht-Modus entsprechend der Schlafgewohnheiten (zusätzlich zur Tageszeit abhängigen Steuerung/Umschaltung, die hier aber nicht Thema sein soll)
; Statuswerte, Events, Readings und Funktionen:
: Wurde ein Wecker ausgelöst?
: Ist gerade ein Weckprogramm aktiv?
: Abbrechen/sofortiges beenden des Weckprogramms
: Verhindern von durch Fehlkonfiguration parallel ausgeführten Weckern für die selbe Person
: Welcher ist der nächste Wecker, der bis Mitternacht des nächsten Tages ausgeführt wird und wann ist das?
: Wann wurde ein Wecker zuletzt ausgeführt und welcher Wecker wurde überhaupt zuletzt ausgeführt?
: Wie viele Bewohner werden gerade geweckt?
: Wie viele Bewohner sind gerade aufgestanden?
: Schaltung bei erstem Bewohner, der geweckt wird
: Schaltung bei erstem Bewohner, der aufgestanden ist
; Statistik
: Wie lange dauerte der Schlaf des Bewohners?
: Wie lange war in dem Haus niemand wach?

Wichtig dabei zu erwähnen ist, dass die Prozesse so umgesetzt worden sind, dass Bewohner sowohl zeitgleich, als auch zeitversetzt oder komplett getrennt ins Bett gehen und aufwachen können.
Dafür werden einige Schaltungen pro Bewohner und dessen Schlafzimmer vorgenommen und andere erst dann, wenn die RESIDENTS Bewohnergruppe einen bestimmten Status erreicht hat.

== Notwendige Devices anlegen ==

=== RESIDENTS und ROOMMATE Devices ===
Wir starten mit einem RESIDENTS Device, um die Bewohner Status später logisch zusammenfassen zu können:

<pre>
define rgr_Bewohner RESIDENTS
</pre>

Anschließend legen wir pro Bewohner ein ROOMMATE Device an. Dafür verwenden wir eine Funktion, die in RESIDENTS eingebaut ist und die Devices korrekt untereinander verbindet (die Reihenfolge, in der RESIDENTS und ROOMMATE/GUEST Geräte definiert werden, sind hier entscheidend). Der Einfachheit halber definieren wir in diesem Beispiel nur einen Bewohner.

<pre>
set rgr_Bewohner addRoommate Julian
</pre>

Es wurde nun automatisch ein Device namens "rr_Julian" angelegt (abgeleitet aus dem angegebenen Vornamen aus dem addRoommate Befehl).
Anschließend setzen wir einmalig den initialen Status für die Bewohner mittels set Befehl:

<pre>
set rr_Julian home
</pre>

Der automatische Wechsel des Status bei Anwesenheit/Abwesenheit wird hier nicht weiter thematisiert, hier sei auf den Artikel [[Anwesenheitserkennung]] verwiesen, insbesondere den GEOFANCY Teil.

=== Wecker Devices anlegen ===

Die Devices, über die die Weckzeit und das Auslöseverhalten eingestellt werden, sind eigentlich normale Dummy Devices. Das zugewiesene ROOMMATE/GUEST/RESIDENTS Device "versklavt" diese Geräte jedoch und führt bestimmte Befehle zur Wecksteuerung und -Verwaltung aus, sobald das Dummy-Device geändert wird. Der Vorteil dabei ist, dass man sich eine Menge eigenen Code und viele unterschiedliche Notify und Dummy Devices spart, was wiederum der Übersichtlichkeit zu Gute kommt.

Wir legen nun unsere drei Wecker für unseren Beispiel Bewohner an. Dafür führen wir einfach 3 mal den selben Befehl hintereinander aus:

<pre>
set rr_Julian create wakeuptimer
set rr_Julian create wakeuptimer
set rr_Julian create wakeuptimer
</pre>

In der Logdatei erscheinen verschiedene Meldungen über alle automatisch angelegte Devices inkl. Name und Typ:

<pre>
2015.03.28 12:19:49 3: RESIDENTStk rr_Julian_wakeuptimer1: new notify macro device Macro_rr_Julian_wakeuptimer1 created
2015.03.28 12:19:50 3: RESIDENTStk rr_Julian_wakeuptimer1: new at-device at_rr_Julian_wakeuptimer1 created
2015.03.28 12:19:50 3: RESIDENTStk rr_Julian_wakeuptimer1: new macro device Macro_rr_Julian_gotosleep created
2015.03.28 12:19:50 3: RESIDENTStk rr_Julian_wakeuptimer1: new watchdog device wd_rr_Julian_gotosleep created
2015.03.28 12:19:50 3: RESIDENTStk rr_Julian_wakeuptimer1: new macro device Macro_rr_Julian_asleep created
2015.03.28 12:19:50 3: RESIDENTStk rr_Julian_wakeuptimer1: new watchdog device wd_rr_Julian_asleep created
2015.03.28 12:19:50 3: RESIDENTStk rr_Julian_wakeuptimer1: new macro device Macro_rr_Julian_awoken created
2015.03.28 12:19:50 3: RESIDENTStk rr_Julian_wakeuptimer1: new watchdog device wd_rr_Julian_awoken created
2015.03.28 12:19:50 3: RESIDENTStk rr_Julian_wakeuptimer1: new macro device Macro_rgr_Bewohner_gotosleep created
2015.03.28 12:19:50 3: RESIDENTStk rr_Julian_wakeuptimer1: new watchdog device wd_rgr_Bewohner_gotosleep created
2015.03.28 12:19:50 3: RESIDENTStk rr_Julian_wakeuptimer1: new macro device Macro_rgr_Bewohner_asleep created
2015.03.28 12:19:50 3: RESIDENTStk rr_Julian_wakeuptimer1: new watchdog device wd_rr_Julian_asleep created
2015.03.28 12:19:50 3: RESIDENTStk rr_Julian_wakeuptimer1: new macro device Macro_rgr_Bewohner_awoken created
2015.03.28 12:19:51 3: RESIDENTStk rr_Julian_wakeuptimer1: new watchdog device wd_rr_Julian_awoken created
2015.03.28 12:21:49 3: RESIDENTStk rr_Julian_wakeuptimer2: new notify macro device Macro_rr_Julian_wakeuptimer2 created
2015.03.28 12:21:49 3: RESIDENTStk rr_Julian_wakeuptimer2: new at-device at_rr_Julian_wakeuptimer2 created
2015.03.28 12:21:56 3: RESIDENTStk rr_Julian_wakeuptimer3: new notify macro device Macro_rr_Julian_wakeuptimer3 created
2015.03.28 12:21:56 3: RESIDENTStk rr_Julian_wakeuptimer3: new at-device at_rr_Julian_wakeuptimer3 created
</pre>

Als Rückgabe in FHEMWEB erhält man eine Meldung wie diese hier:

<pre>
Dummy rr_Julian_wakeuptimer1 and other pending devices created and pre-configured.
You may edit Macro_rr_Julian_wakeuptimer1 to define your wake-up actions
and at_rr_Julian_wakeuptimer1 for optional at-device adjustments.
</pre>

Wie man sieht wurden anfänglich eine ganze Menge von Notify-Macros und Watchdogs sowie ein at-Device pro Wecker angelegt.
Dabei sind vor allem die Macro-Devices und die Wecker Dummy Devices interessant. Hier werden Weck- und Auslöseverhalten konfiguriert. die at- und Watchdog-Devices können aber für fortgeschrittene Nutzer beliebig angepasst werden. Auch die Dummy Devices können bis auf wenige Ausnahmen (Attribut "userattr") vollständig umkonfiguriert werden. Wer Devices umbenennt, sollte unbedingt darauf achten, dass auch das entsprechende Attribut im Wecker-Dummy-Device angepasst wird.

Allen Devices ist ein entsprechender Kommentar hinzugefügt, der dessen Funktion kurz erklärt.
Alle Macros enthalten bereits ein Gerüst für den Weckprozess mit einigen Beispielen. Die Beispielschaltungen sind dabei noch auskommentiert. Nicht auskommentierter Code sollte als notwendiger Teil für die Weckautomation betrachtet werden und wird dort auch durch einen entsprechenden Kommentar erklärt.

Im Folgenden werden wir jetzt Schritt für Schritt das oben beschriebene Szenario konfigurieren.

== Konfiguration des Auslöseverhaltens ==

In der Grundkonfiguration löst jeder Wecker sein eigenes Weckprogramm täglich zur voreingestellten Zeit aus. Dabei wird allerdings kein längeres Programm gestartet, sondern lediglich einmalig das im Attribut wakeupMacro hinterlegte Notify-Macro getriggert. Das ist in der Beispiel-Grundkonfiguration kein Problem und lässt lediglich einen Logfile Eintrag erstellen.

Als erstes möchten wir, dass alle 3 Timer das selbe Macro zum Wecken verwenden, damit wir den Code nur einmal pflegen müssen. Die anderen beiden Macros löschen wir anschließend:

<pre>
attr rr_Julian_wakeuptimer2 wakeupMacro Macro_rr_Julian_wakeuptimer1
attr rr_Julian_wakeuptimer3 wakeupMacro Macro_rr_Julian_wakeuptimer1
delete Macro_rr_Julian_wakeuptimer2
delete Macro_rr_Julian_wakeuptimer3
</pre>

Nun konfigurieren wir die Auslöseverhalten so, wie wir es oben vorgegeben haben:

=== Wake-up Timer 1 ===

Wecker nur Mo-Fr auslösen:
<pre>
attr rr_Julian_wakeuptimer1 wakeupDays 1,2,3,4,5
</pre>

Wecker zusätzlich auf Tage beschränken, die keine Feiertage sind:
<pre>
attr rr_Julian_wakeuptimer1 wakeupHolidays andNoHoliday
</pre>
<i><u>Hinweis:</u> Hierfür muss ein [http://fhem.de/commandref.html#holiday holiday-Device] erstellt sein und in der global Config im Attribut 'holidays2we‘ verlinkt sein. Ansonsten erhält man beim setzen einer Weckzeit später entsprechende Fehlermeldungen, die darauf hinweisen.</i>

Länge des Weckprogramms auf 30 Minuten festlegen (sprich 30 Minuten vor der eingestellten Weckzeit beginnen):
<pre>
attr rr_Julian_wakeuptimer1 wakeupOffset 30
</pre>

Aufstehen forcieren:
<pre>
attr rr_Julian_wakeuptimer1 wakeupEnforced 1
</pre>

Standard Weckzeit hinterlegen:
<pre>
attr rr_Julian_wakeuptimer1 wakeupDefaultTime 07:30
</pre>

Weckzeit nur an diesen Tagen automatisch zurückstellen:
<pre>
attr rr_Julian_wakeuptimer1 wakeupResetdays 1,2,3,4,5
</pre>
<i><u>Hinweis:</u> Ein Reset findet normalerweise nach jeder Auslösung statt, sprich wenn das Weckprogramm tatsächlich gestartet wurde. Dies kann man auf bestimmte Tage einschränken.</i>

Zum einfacheren Aktivieren/Deaktivieren des Resets wollen wir ein weiteres Dummy nutzen:
<pre>
attr rr_Julian_wakeuptimer1 wakeupResetSwitcher rr_Julian_wakeuptimer1_resetswitcher
</pre>
<i><u>Hinweis:</u> Der Dummy-Gerätename kann frei gewählt werden. Sofern es nicht existiert wird es automatisch angelegt und vorkonfiguriert.</i>

=== Wake-up Timer 2 ===

Wecker nur Samstags auslösen:
<pre>
attr rr_Julian_wakeuptimer2 wakeupDays 6
</pre>

Wecker zusätzlich auf Tage beschränken, die keine Feiertage sind:
<pre>
attr rr_Julian_wakeuptimer2 wakeupHolidays andNoHoliday
</pre>

Länge des Weckprogramms auf 30 Minuten festlegen (sprich 30 Minuten vor der eingestellten Weckzeit beginnen):
<pre>
attr rr_Julian_wakeuptimer2 wakeupOffset 30
</pre>

Aufstehen forcieren:
<pre>
attr rr_Julian_wakeuptimer2 wakeupEnforce 1
</pre>

Standard Weckzeit hinterlegen:
<pre>
attr rr_Julian_wakeuptimer2 wakeupDefaultTime 09:30
</pre>

Weckzeit nur an diesen Tagen automatisch zurückstellen:
<pre>
attr rr_Julian_wakeuptimer2 wakeupResetdays 6
</pre>

=== Wake-up Timer 3 ===

Wecker nur Sonntags auslösen:
<pre>
attr rr_Julian_wakeuptimer3 wakeupDays 0
</pre>

Wecker zusätzlich auch an Feiertagen ausführen:
<pre>
attr rr_Julian_wakeuptimer3 wakeupHolidays orHoliday
</pre>

Aufstehen nur forcieren, wenn eine frühere Weckzeit als die Standard Weckzeit eingestellt wurde:
<pre>
attr rr_Julian_wakeuptimer3 wakeupEnforce 3
</pre>

Länge des Weckprogramms auf 30 Minuten festlegen (sprich 30 Minuten vor der eingestellten Weckzeit beginnen):
<pre>
attr rr_Julian_wakeuptimer3 wakeupOffset 30
</pre>

Standard Weckzeit hinterlegen:
<pre>
attr rr_Julian_wakeuptimer3 wakeupDefaultTime 10:30
</pre>

== Definition des Weckprogramms ==

Die Aktionen, welche innerhalb der 30 Minuten Weckzeitraum abgearbeitet werden sollen, sind im Device Macro_rr_Julian_wakeuptimer1 hinterlegt.
Dieses Macro wird 2 Mal aufgerufen: Das erste Mal beim Beginn des Weckprogramms und ein zweites Mal beim Ende des Weckprogramms. Der Hintergrund ist, dass das Macro beim Beenden dann entsprechend dafür sorgen kann bisher nicht ausgeführte Befehle des Programmablaufes zu stornieren. Hierfür ist der delete-Befehl am Anfang des Macros gedacht.

Das Macro Template hat bereits alle oben beschriebenen Funktionen als auskommentierte FHEM Befehle enthalten. Diese sollen natürlich nur dem Beispiel und der eigenen Inspiration dienen. Wir müssten diese an dieser Stelle lediglich einkommentieren...
Insgesamt fällt bei genauerem hinsehen folgendes auf:

* es stehen bestimmte Umgebungsvariablen bereit, die während des Programmablaufes genutzt werden können
* das Macro ist in 3 Bereiche unterteilt und nutzt dafür die Umgebungsvariable $EVTPART0 bzw. ob deren Wert auf "start" oder "stop" steht
* der erste Bereich mit dem delete-Befehl wird immer ausgeführt. Er räumt durch das Macro erzeugte temporäre at-Devices auf (entweder weil das Programm früher beendet werden soll oder von vorne beginnen soll)
* der zweite Bereich "start" führt erste FHEM Befehle direkt nach dem Beginn des Weckprogramms aus. Außerdem werden weitere Befehle in bestimmten Etappen zur zeitversetzten Ausführung vorgemerkt. Dafür werden temporär erzeugte at-Devices verwendet.
* der Name der at-Devices folgt einem bestimmten Schema, nämlich atTmp_<LAUFENDE-NUMMER>_$NAME. Die laufende Nummer muss man manuell hochzählen, der Rest kann einfach kopiert werden. Wenn man davon abweicht, muss man den delete-Befehl am Anfang auch anpassen.
* bei der Definition der at-Devices müssen mehrere FHEM Befehle hintereinander mit 2 Semikolon statt einem getrennt werden (siehe auch [http://fhem.de/commandref_DE.html#command Kommando-Referenz]).
* bei bedingten Schaltungen empfehlt es sich für übersichtlicheren Code die :FILTER Funktion zu nutzen (siehe auch [http://fhem.de/commandref_DE.html#devspec Kommando-Referenz]).
* es ist unbedingt darauf zu achten, dass das letzte at-Device nicht nach der wakeupOffset Zeit definiert wird, da es ansonsten automatisch gelöscht und somit nicht mehr ausgeführt wird
* nach einem ordentlichen Ende des Weckprogramms wird ein at-Device erzeugt, welches das Benutzer-Device automatisch nach "awoken" oder "home" schaltet, abhängig davon ob das Wecken forciert werden soll oder nicht. Dieser Teil wird tatsächlich nur geplant, wenn das Weckprogramm ordentlich beendet wurde. Wurde das Weckprogramm durch ein "set rr_Julian_wakeuptimer1 stop" bzw. durch Klick auf das blaue Device-Icon beendet, so werden die Post-Wakeup Befehle nicht mehr ausgeführt, weil man davon ausgehen kann, dass ein Abbruch des Programms und somit aller seiner weiteren Schaltungen gewünscht ist.

Man kann sein Weckprogramm auf zwei Arten testen:

* durch senden des set-Befehls "trigger": hier werden die aktuellen Auslösedefinitionen berücksichtigt; sprich, wenn heute nicht der richtige Tag ist, wird das Programm nicht gestartet
* durch senden des set-Befehls "start" kann man alle Auslösedefinitionen umgehen und das Weckprogramm direkt auslösen

Zu Debug-Zwecken kann man auf das Wecker Dummy-Device das Attribut "verbose" auf 4 setzen. Im Logfile wird dann sehr ausführlich geloggt, warum wie geschaltet oder nicht geschaltet wird und wie die Entscheidungen getroffen worden sind, Readings zu aktualisieren etc. Damit lässt sich prüfen, ob das gewünschte Auslöseverhalten tatsächlich richtig funktioniert.

== Definition der Aktionen für den Prozess "bettfertig machen" ==

Möchte der Bewohner nun ins Bett gehen und sich dabei noch etwas darauf einstimmen, kann er sein "bettfertig machen"-Programm dadurch starten, dass er den Status seines ROOMMATE-Devices in FHEM auf "gotosleep" setzt.
In unserem Beispiel werden dann die Aktionen aus Macro_rr_Julian_gotosleep ausgeführt.

Zeitgleich wird im RESIDENTS-Device rgr_Bewohner das Reading "residentsGotosleep" um 1 erhöht und ein Event erzeugt. Befinden sich gar alle anwesenden Bewohner im Status "gotosleep" wechselt der Gesamtstatus von rgr_Bewohner auch auf "gotosleep". Dies löst dann Macro_rgr_Bewohner_gotosleep aus. Dort werden dann Schaltungen vorgenommen, die von größerer Tragweite sind, als wenn nur ein einzelner Bewohner ins Bett geht. Beispielsweise könnte man in bestimmten Räumen das Licht oder Geräte ausschalten, die man ansonsten unberührt gelassen hätte, wenn andere noch wach blieben.

== Definition der Aktionen für den Prozess "schlafen legen" ==

Legt sich der Bewohner ins Bett und möchte schlafen, wechselt er den Status seines ROOMMATE-Devices auf "asleep". Ich mache das bei mir durch einen extra Wandschalter.

In unserem Beispiel werden jetzt die Aktionen aus Macro_rr_Julian_asleep ausgeführt. In dem Macro wird besonders Wert darauf gelegt, dass ausschließlich Aktionen ausgeführt werden, die mit dem Schlafzimmer des Bewohners zu tun haben, damit andere Bewohner in anderen Räumen nicht beeinträchtigt werden.

Zeitgleich werden im RESIDENTS-Device rgr_Bewohner das Reading "residentsGotosleep" um 1 erniedrigt, das Reading "residentsAsleep" um 1 erhöht und ein Event erzeugt. Befinden sich gar alle anwesenden Bewohner im Status "asleep" wechselt der Gesamtstatus von rgr_Bewohner auch auf "asleep". Dies löst dann Macro_rgr_Bewohner_asleep aus. Dort werden dann auch wieder Schaltungen vorgenommen, die von größerer Tragweite sind. Beispielsweise werden alle noch übrigen Lichter im Haus ausgeschaltet und die Musikwiedergabe in Gemeinschaftsräumen (wie hier dem Badezimmer) gestoppt.

== Definition der Aktionen für den Prozess "aufgestanden sein" ==

Wir gehen nun davon aus, dass irgendwann morgens das Weckprogramm wie oben zuvor definiert abgespielt wird. Dabei wechselt im Device rgr_Bewohner das Reading residentsTotalWakeup auf 1 (oder höher bei mehreren gleichzeitig aktiven Weckprogrammen unterschiedlicher Bewohner).

Während des Weckprogramms (oder natürlich auch davor) kann der Bewohner jederzeit in den Status "awoken" wechseln. Ich nutze bei mir auch hier wieder den Wandschalter.
Dadurch wird ein evtl. noch laufendes Weckprogramm unterbrochen (die at-Devices in FHEM werden automatisch aufgräumt) und die Aktionen in Macro_rr_Julian_awoken werden ausgeführt.

Neben dem expliziten Wechsel zum Status "awoken" kann aber, wie oben beschrieben, auch das Weckprogramm selbst den Bewohner auf diesen Status setzen. Dies wird dann als forciertes Wecken bezeichnet; sozusagen um seinen Hintern aus dem Bett zu bewegen :-)
Sinnvollerweise wechselt der Status des Bewohners nach kurzer Zeit dann automatisch von "awoken" auf "home", also den Standard-Status wenn man zuhause ist.

Zeitgleich zum Wechsel des ROOMMATE-Devices auf "awoken" wird auch wieder das RESIDENTS-Device automatisch angepasst: Das Reading "residentsAsleep" wird um 1 erniedrigt, das Reading "residentsAwoken" um 1 erhöht und ein Event erzeugt.
Außerdem wird der Gesamtstatus auf "awoken" gesetzt. Dies löst Macro_rgr_Bewohner_awoken aus. Hier werden auch wieder Schaltungen vorgenommen, die das Haus dann für den ersten, der aufsteht, entsprechend einzustellen, also beispielsweise das Licht in der Küche einschalten.
Zusätzlich wird dann ein temporäres at-Devices angelegt, welches dafür sorgt, dass der Haus Modus nach 1,5h von "Morgen" auf "Tag" wechselt. Allerdings ist der Haus Modus wie schon erwähnt hier nicht das Hauptthema und wird aktuell auch noch nicht direkt vom RESIDENTS Toolkit unterstützt (Sneak-Peek auf zukünftige Erweiterungen ;-)).

== Snooze Funktion bei SONOS ==

Damit man an gewissen Tagen auch dem Wecker mal auf'n Kopp hauen kann (bzw. auf den Start/Stop Button am SONOS Gerät), kann man ein einfaches DOIF erzeugen, welches dafür sorgt, dass man nach 5 Minuten wieder daran erinnert wird aufzustehen:

<pre>
define di_Sonos_Snooze DOIF (
[Sonos_Bedroom:?transportState] and (
([rr_Julian:wakeup] == 0 and [rr_Julian:wakeup:sec] >= 600) or
$we
) or
(
([rr_Julian:wakeup] == 0 and [rr_Julian:wakeup:sec] >= 600) or
$we
)
)

DOELSEIF
(
[Sonos_Bedroom:?transportState] and
([Sonos_Bedroom:transportState] eq "STOPPED" or [Sonos_Bedroom:transportState] eq "PAUSED_PLAYBACK") and
([?rr_Julian:wakeup] == 1 or [rr_Julian:wakeup:sec] < 600) and
!$we
)
(
set Sonos_Bedroom:FILTER=transportState!=PLAYING Play
)

DOELSE

attr alias Automation: Sonos Snoozing
attr cmdState off|on|standby
attr comment snooze function for wake-up program via SONOS device button
attr devStateIcon off:general_aus on:general_an@green standby:general_an@orange
attr wait 0:300:0
</pre>

Das DOIF hier greift nur während ein Weckprogramm läuft oder maximal noch 10 Minuten danach; zudem nur wochentags :-)

Außerdem zeigt der DOIF Status an, ob die Snooze Funktion gerade scharf geschaltet ist oder nicht.

Wichtig ist auch, dass das ROOMMATE Device ein Event bei der Änderung des wakeup Readings auslöst, also z.B. das Attribut event-on-change-reading dann entsprechend auch "wakeup" enthält.

[[Kategorie:Examples]]
[[Kategorie:Code_Snippets]]

Weckautomation

2017-04-09T10:58:10Z

Loredo:

Die Module ROOMMATE und GUEST können dazu genutzt werden, Bewohner und Gäste in FHEM als ein Device zu repräsentieren und durch Events deren Status zu erfassen bzw. zu ändern (beispielsweise durch das GEOFANCY Modul für [[Anwesenheitserkennung]]). Das zur Modulfamilie dazugehörige Modul RESIDENTS fasst die Status mehrerer Bewohner logisch zusammen.

Inzwischen unterstützen die Module auch bei der Erstellung einer Weckautomation, indem sie die Logik kapseln und häufig verwendete Standardfunktionen bereitstellen. Die Verwendung soll in diesem Artikel anhand eines Beispiels näher erläutert werden.

[[Datei:Weckprogramm_Ergebnisdarstellung.png|500px|thumb|right|Darstellung der Beispiel-Konfiguration]]

== Was soll erreicht werden? ==

Hier ein kurzer Überblick über die Funktionen, die wir am Ende realisiert haben werden:

; 3 unterschiedliche Wecker
: 1 für Werktage Mo-Fr
: 1 für werktägliche Samstage
: 1 für Sonn- und Feiertage
; Automatischer Reset der Weckzeiten
: werktäglicher Wecker soll auf einen Standardwert zurückstellen, falls er mal verstellt wurde
: automatischer Reset des werktäglicher Weckers soll zeitweise abschaltbar sein
: nach einem Sonn- oder Feiertagen soll der automatische Reset des werktäglichen Weckers immer wieder eingeschaltet werden
: die Samstags- und Sonntags-Wecker sollen immer nach ihrer Ausführung resettet werden
; jeder Wecker startet ein Weckprogramm 30 Minuten vor der programmierten Zeit
: langsames hochfahren der Rollläden
: Wakeup Light über eine HUE Birne von Warmweiß/2000K zu Kaltweiß/5600K
: an Werktagen: Chillout Weckmusik wird langsam lauter gestellt
: Snooze Funktion über die SONOS Taste am Gerät an Werktagen (erneutes Play nach 5 Minuten)
: forciertes Aufstehen an Werktagen durch automatischen Wechsel des Bewohner Devices zu "awake" und dadurch starten der "aufgestanden sein" Prozesse (siehe unten)
; Starten des Weckprogramms nur bei tatsächlicher Anwesenheit des betroffenen Bewohners
; Ansage der Uhrzeit zur gewählten Weckzeit
; Prozess / Automation für:
: <u>bettfertig machen</u>: Lichtszene setzen, Chillout Musik in Schlafzimmer und Badezimmer abspielen
: <u>schlafen legen</u>: Ansage der eingestellten Weckzeit & Ausschalten aller Verbraucher
: <u>aufgestanden sein</u>: Ansage Raumluftqualität, Wettervorhersage; Lokalradio einschalten und in Räume verteilen; Küchenlicht an, HUE in Schlafzimmer mit Aufwach-Farbtemperatur
; Berücksichtigung / Steuerung des Haus Modus
: Wechsel zwischen Morgen-, Tag-, Abend- und Nacht-Modus entsprechend der Schlafgewohnheiten (zusätzlich zur Tageszeit abhängigen Steuerung/Umschaltung, die hier aber nicht Thema sein soll)
; Statuswerte, Events, Readings und Funktionen:
: Wurde ein Wecker ausgelöst?
: Ist gerade ein Weckprogramm aktiv?
: Abbrechen/sofortiges beenden des Weckprogramms
: Verhindern von durch Fehlkonfiguration parallel ausgeführten Weckern für die selbe Person
: Welcher ist der nächste Wecker, der bis Mitternacht des nächsten Tages ausgeführt wird und wann ist das?
: Wann wurde ein Wecker zuletzt ausgeführt und welcher Wecker wurde überhaupt zuletzt ausgeführt?
: Wie viele Bewohner werden gerade geweckt?
: Wie viele Bewohner sind gerade aufgestanden?
: Schaltung bei erstem Bewohner, der geweckt wird
: Schaltung bei erstem Bewohner, der aufgestanden ist
; Statistik
: Wie lange dauerte der Schlaf des Bewohners?
: Wie lange war in dem Haus niemand wach?

Wichtig dabei zu erwähnen ist, dass die Prozesse so umgesetzt worden sind, dass Bewohner sowohl zeitgleich, als auch zeitversetzt oder komplett getrennt ins Bett gehen und aufwachen können.
Dafür werden einige Schaltungen pro Bewohner und dessen Schlafzimmer vorgenommen und andere erst dann, wenn die RESIDENTS Bewohnergruppe einen bestimmten Status erreicht hat.

== Notwendige Devices anlegen ==

=== RESIDENTS und ROOMMATE Devices ===
Wir starten mit einem RESIDENTS Device, um die Bewohner Status später logisch zusammenfassen zu können:

<pre>
define rgr_Bewohner RESIDENTS
</pre>

Anschließend legen wir pro Bewohner ein ROOMMATE Device an. Dafür verwenden wir eine Funktion, die in RESIDENTS eingebaut ist und die Devices korrekt untereinander verbindet (die Reihenfolge, in der RESIDENTS und ROOMMATE/GUEST Geräte definiert werden, sind hier entscheidend). Der Einfachheit halber definieren wir in diesem Beispiel nur einen Bewohner.

<pre>
set rgr_Bewohner addRoommate Julian
</pre>

Es wurde nun automatisch ein Device namens "rr_Julian" angelegt (abgeleitet aus dem angegebenen Vornamen aus dem addRoommate Befehl).
Anschließend setzen wir einmalig den initialen Status für die Bewohner mittels set Befehl:

<pre>
set rr_Julian home
</pre>

Der automatische Wechsel des Status bei Anwesenheit/Abwesenheit wird hier nicht weiter thematisiert, hier sei auf den Artikel [[Anwesenheitserkennung]] verwiesen, insbesondere den GEOFANCY Teil.

=== Wecker Devices anlegen ===

Die Devices, über die die Weckzeit und das Auslöseverhalten eingestellt werden, sind eigentlich normale Dummy Devices. Das zugewiesene ROOMMATE/GUEST/RESIDENTS Device "versklavt" diese Geräte jedoch und führt bestimmte Befehle zur Wecksteuerung und -Verwaltung aus, sobald das Dummy-Device geändert wird. Der Vorteil dabei ist, dass man sich eine Menge eigenen Code und viele unterschiedliche Notify und Dummy Devices spart, was wiederum der Übersichtlichkeit zu Gute kommt.

Wir legen nun unsere drei Wecker für unseren Beispiel Bewohner an. Dafür führen wir einfach 3 mal den selben Befehl hintereinander aus:

<pre>
set rr_Julian create wakeuptimer
set rr_Julian create wakeuptimer
set rr_Julian create wakeuptimer
</pre>

In der Logdatei erscheinen verschiedene Meldungen über alle automatisch angelegte Devices inkl. Name und Typ:

<pre>
2015.03.28 12:19:49 3: RESIDENTStk rr_Julian_wakeuptimer1: new notify macro device Macro_rr_Julian_wakeuptimer1 created
2015.03.28 12:19:50 3: RESIDENTStk rr_Julian_wakeuptimer1: new at-device at_rr_Julian_wakeuptimer1 created
2015.03.28 12:19:50 3: RESIDENTStk rr_Julian_wakeuptimer1: new macro device Macro_rr_Julian_gotosleep created
2015.03.28 12:19:50 3: RESIDENTStk rr_Julian_wakeuptimer1: new watchdog device wd_rr_Julian_gotosleep created
2015.03.28 12:19:50 3: RESIDENTStk rr_Julian_wakeuptimer1: new macro device Macro_rr_Julian_asleep created
2015.03.28 12:19:50 3: RESIDENTStk rr_Julian_wakeuptimer1: new watchdog device wd_rr_Julian_asleep created
2015.03.28 12:19:50 3: RESIDENTStk rr_Julian_wakeuptimer1: new macro device Macro_rr_Julian_awoken created
2015.03.28 12:19:50 3: RESIDENTStk rr_Julian_wakeuptimer1: new watchdog device wd_rr_Julian_awoken created
2015.03.28 12:19:50 3: RESIDENTStk rr_Julian_wakeuptimer1: new macro device Macro_rgr_Bewohner_gotosleep created
2015.03.28 12:19:50 3: RESIDENTStk rr_Julian_wakeuptimer1: new watchdog device wd_rgr_Bewohner_gotosleep created
2015.03.28 12:19:50 3: RESIDENTStk rr_Julian_wakeuptimer1: new macro device Macro_rgr_Bewohner_asleep created
2015.03.28 12:19:50 3: RESIDENTStk rr_Julian_wakeuptimer1: new watchdog device wd_rr_Julian_asleep created
2015.03.28 12:19:50 3: RESIDENTStk rr_Julian_wakeuptimer1: new macro device Macro_rgr_Bewohner_awoken created
2015.03.28 12:19:51 3: RESIDENTStk rr_Julian_wakeuptimer1: new watchdog device wd_rr_Julian_awoken created
2015.03.28 12:21:49 3: RESIDENTStk rr_Julian_wakeuptimer2: new notify macro device Macro_rr_Julian_wakeuptimer2 created
2015.03.28 12:21:49 3: RESIDENTStk rr_Julian_wakeuptimer2: new at-device at_rr_Julian_wakeuptimer2 created
2015.03.28 12:21:56 3: RESIDENTStk rr_Julian_wakeuptimer3: new notify macro device Macro_rr_Julian_wakeuptimer3 created
2015.03.28 12:21:56 3: RESIDENTStk rr_Julian_wakeuptimer3: new at-device at_rr_Julian_wakeuptimer3 created
</pre>

Als Rückgabe in FHEMWEB erhält man eine Meldung wie diese hier:

<pre>
Dummy rr_Julian_wakeuptimer1 and other pending devices created and pre-configured.
You may edit Macro_rr_Julian_wakeuptimer1 to define your wake-up actions
and at_rr_Julian_wakeuptimer1 for optional at-device adjustments.
</pre>

Wie man sieht wurden anfänglich eine ganze Menge von Notify-Macros und Watchdogs sowie ein at-Device pro Wecker angelegt.
Dabei sind vor allem die Macro-Devices und die Wecker Dummy Devices interessant. Hier werden Weck- und Auslöseverhalten konfiguriert. die at- und Watchdog-Devices können aber für fortgeschrittene Nutzer beliebig angepasst werden. Auch die Dummy Devices können bis auf wenige Ausnahmen (Attribut "userattr") vollständig umkonfiguriert werden. Wer Devices umbenennt, sollte unbedingt darauf achten, dass auch das entsprechende Attribut im Wecker-Dummy-Device angepasst wird.

Allen Devices ist ein entsprechender Kommentar hinzugefügt, der dessen Funktion kurz erklärt.
Alle Macros enthalten bereits ein Gerüst für den Weckprozess mit einigen Beispielen. Die Beispielschaltungen sind dabei noch auskommentiert. Nicht auskommentierter Code sollte als notwendiger Teil für die Weckautomation betrachtet werden und wird dort auch durch einen entsprechenden Kommentar erklärt.

Im Folgenden werden wir jetzt Schritt für Schritt das oben beschriebene Szenario konfigurieren.

== Konfiguration des Auslöseverhaltens ==

In der Grundkonfiguration löst jeder Wecker sein eigenes Weckprogramm täglich zur voreingestellten Zeit aus. Dabei wird allerdings kein längeres Programm gestartet, sondern lediglich einmalig das im Attribut wakeupMacro hinterlegte Notify-Macro getriggert. Das ist in der Beispiel-Grundkonfiguration kein Problem und lässt lediglich einen Logfile Eintrag erstellen.

Als erstes möchten wir, dass alle 3 Timer das selbe Macro zum Wecken verwenden, damit wir den Code nur einmal pflegen müssen. Die anderen beiden Macros löschen wir anschließend:

<pre>
attr rr_Julian_wakeuptimer2 wakeupMacro Macro_rr_Julian_wakeuptimer1
attr rr_Julian_wakeuptimer3 wakeupMacro Macro_rr_Julian_wakeuptimer1
delete Macro_rr_Julian_wakeuptimer2
delete Macro_rr_Julian_wakeuptimer3
</pre>

Nun konfigurieren wir die Auslöseverhalten so, wie wir es oben vorgegeben haben:

=== Wake-up Timer 1 ===

Wecker nur Mo-Fr auslösen:
<pre>
attr rr_Julian_wakeuptimer1 wakeupDays 1,2,3,4,5
</pre>

Wecker zusätzlich auf Tage beschränken, die keine Feiertage sind:
<pre>
attr rr_Julian_wakeuptimer1 wakeupHolidays andNoHoliday
</pre>
<i><u>Hinweis:</u> Hierfür muss ein [http://fhem.de/commandref.html#holiday holiday-Device] erstellt sein und in der global Config im Attribut 'holidays2we‘ verlinkt sein. Ansonsten erhält man beim setzen einer Weckzeit später entsprechende Fehlermeldungen, die darauf hinweisen.</i>

Länge des Weckprogramms auf 30 Minuten festlegen (sprich 30 Minuten vor der eingestellten Weckzeit beginnen):
<pre>
attr rr_Julian_wakeuptimer1 wakeupOffset 30
</pre>

Aufstehen forcieren:
<pre>
attr rr_Julian_wakeuptimer1 wakeupEnforced 1
</pre>

Standard Weckzeit hinterlegen:
<pre>
attr rr_Julian_wakeuptimer1 wakeupDefaultTime 07:30
</pre>

Weckzeit nur an diesen Tagen automatisch zurückstellen:
<pre>
attr rr_Julian_wakeuptimer1 wakeupResetdays 1,2,3,4,5
</pre>
<i><u>Hinweis:</u> Ein Reset findet normalerweise nach jeder Auslösung statt, sprich wenn das Weckprogramm tatsächlich gestartet wurde. Dies kann man auf bestimmte Tage einschränken.</i>

Zum einfacheren Aktivieren/Deaktivieren des Resets wollen wir ein weiteres Dummy nutzen:
<pre>
attr rr_Julian_wakeuptimer1 wakeupResetSwitcher rr_Julian_wakeuptimer1_resetswitcher
</pre>
<i><u>Hinweis:</u> Der Dummy-Gerätename kann frei gewählt werden. Sofern es nicht existiert wird es automatisch angelegt und vorkonfiguriert.</i>

=== Wake-up Timer 2 ===

Wecker nur Samstags auslösen:
<pre>
attr rr_Julian_wakeuptimer2 wakeupDays 6
</pre>

Wecker zusätzlich auf Tage beschränken, die keine Feiertage sind:
<pre>
attr rr_Julian_wakeuptimer2 wakeupHolidays andNoHoliday
</pre>

Länge des Weckprogramms auf 30 Minuten festlegen (sprich 30 Minuten vor der eingestellten Weckzeit beginnen):
<pre>
attr rr_Julian_wakeuptimer2 wakeupOffset 30
</pre>

Aufstehen forcieren:
<pre>
attr rr_Julian_wakeuptimer2 wakeupEnforce 1
</pre>

Standard Weckzeit hinterlegen:
<pre>
attr rr_Julian_wakeuptimer2 wakeupDefaultTime 09:30
</pre>

Weckzeit nur an diesen Tagen automatisch zurückstellen:
<pre>
attr rr_Julian_wakeuptimer2 wakeupResetdays 6
</pre>

=== Wake-up Timer 3 ===

Wecker nur Sonntags auslösen:
<pre>
attr rr_Julian_wakeuptimer3 wakeupDays 0
</pre>

Wecker zusätzlich auch an Feiertagen ausführen:
<pre>
attr rr_Julian_wakeuptimer3 wakeupHolidays orHoliday
</pre>

Aufstehen nur forcieren, wenn eine frühere Weckzeit als die Standard Weckzeit eingestellt wurde:
<pre>
attr rr_Julian_wakeuptimer3 wakeupEnforce 3
</pre>

Länge des Weckprogramms auf 30 Minuten festlegen (sprich 30 Minuten vor der eingestellten Weckzeit beginnen):
<pre>
attr rr_Julian_wakeuptimer3 wakeupOffset 30
</pre>

Standard Weckzeit hinterlegen:
<pre>
attr rr_Julian_wakeuptimer3 wakeupDefaultTime 10:30
</pre>

== Definition des Weckprogramms ==

Die Aktionen, welche innerhalb der 30 Minuten Weckzeitraum abgearbeitet werden sollen, sind im Device Macro_rr_Julian_wakeuptimer1 hinterlegt.
Dieses Macro wird 2 Mal aufgerufen: Das erste Mal beim Beginn des Weckprogramms und ein zweites Mal beim Ende des Weckprogramms. Der Hintergrund ist, dass das Macro beim Beenden dann entsprechend dafür sorgen kann bisher nicht ausgeführte Befehle des Programmablaufes zu stornieren. Hierfür ist die for-Schleife am Anfang des Macros gedacht und deckt per Default 10 Arbeitsschritte ab (ansonsten einfach die Zahl entsprechend erhöhen).

Das Macro Template hat bereits alle oben beschriebenen Funktionen als auskommentierte FHEM Befehle enthalten. Diese sollen natürlich nur dem Beispiel und der eigenen Inspiration dienen. Wir müssten diese an dieser Stelle lediglich einkommentieren...
Insgesamt fällt bei genauerem hinsehen folgendes auf:

* es stehen bestimmte Umgebungsvariablen bereit, die während des Programmablaufes genutzt werden können
* das Macro ist in 3 Bereiche unterteilt und nutzt dafür die Umgebungsvariable $EVTPART0 bzw. ob deren Wert auf "start" oder "stop" steht
* der erste Bereich mit der for-Schleife wird immer ausgeführt. Sie räumt durch das Macro erzeugte temporäre at-Devices auf (entweder weil das Programm früher beendet werden soll oder von vorne beginnen soll)
* der zweite Bereich "start" führt erste FHEM Befehle direkt nach dem Beginn des Weckprogramms aus. Außerdem werden weitere Befehle in bestimmten Etappen zur zeitversetzten Ausführung vorgemerkt. Dafür werden temporär erzeugte at-Devices verwendet.
* der Name der at-Devices folgt einem bestimmten Schema, nämlich atTmp_<LAUFENDE-NUMMER>_$NAME. Die laufende Nummer muss man manuell hochzählen, der Rest kann einfach kopiert werden. Dadurch wird das aufräumen oben im Macro einfacher.
* bei der Definition der at-Devices müssen mehrere FHEM Befehle hintereinander mit 2 Semikolon statt einem getrennt werden (siehe auch [http://fhem.de/commandref_DE.html#command Kommando-Referenz]).
* bei bedingten Schaltungen empfehlt es sich für übersichtlicheren Code die :FILTER Funktion zu nutzen (siehe auch [http://fhem.de/commandref_DE.html#devspec Kommando-Referenz]).
* es ist unbedingt darauf zu achten, dass das letzte at-Device nicht nach der wakeupOffset Zeit definiert wird, da es ansonsten automatisch gelöscht und somit nicht mehr ausgeführt wird
* nach einem ordentlichen Ende des Weckprogramms wird ein at-Device erzeugt, welches das Benutzer-Device automatisch nach "awoken" oder "home" schaltet, abhängig davon ob das Wecken forciert werden soll oder nicht. Dieser Teil wird tatsächlich nur geplant, wenn das Weckprogramm ordentlich beendet wurde. Wurde das Weckprogramm durch ein "set rr_Julian_wakeuptimer1 stop" bzw. durch Klick auf das blaue Device-Icon beendet, so werden die Post-Wakeup Befehle nicht mehr ausgeführt, weil man davon ausgehen kann, dass ein Abbruch des Programms und somit aller seiner weiteren Schaltungen gewünscht ist.

Man kann sein Weckprogramm auf zwei Arten testen:

* durch senden des set-Befehls "trigger": hier werden die aktuellen Auslösedefinitionen berücksichtigt; sprich, wenn heute nicht der richtige Tag ist, wird das Programm nicht gestartet
* durch senden des set-Befehls "start" kann man alle Auslösedefinitionen umgehen und das Weckprogramm direkt auslösen

Zu Debug-Zwecken kann man auf das Wecker Dummy-Device das Attribut "verbose" auf 4 setzen. Im Logfile wird dann sehr ausführlich geloggt, warum wie geschaltet oder nicht geschaltet wird und wie die Entscheidungen getroffen worden sind, Readings zu aktualisieren etc. Damit lässt sich prüfen, ob das gewünschte Auslöseverhalten tatsächlich richtig funktioniert.

== Definition der Aktionen für den Prozess "bettfertig machen" ==

Möchte der Bewohner nun ins Bett gehen und sich dabei noch etwas darauf einstimmen, kann er sein "bettfertig machen"-Programm dadurch starten, dass er den Status seines ROOMMATE-Devices in FHEM auf "gotosleep" setzt.
In unserem Beispiel werden dann die Aktionen aus Macro_rr_Julian_gotosleep ausgeführt.

Zeitgleich wird im RESIDENTS-Device rgr_Bewohner das Reading "residentsGotosleep" um 1 erhöht und ein Event erzeugt. Befinden sich gar alle anwesenden Bewohner im Status "gotosleep" wechselt der Gesamtstatus von rgr_Bewohner auch auf "gotosleep". Dies löst dann Macro_rgr_Bewohner_gotosleep aus. Dort werden dann Schaltungen vorgenommen, die von größerer Tragweite sind, als wenn nur ein einzelner Bewohner ins Bett geht. Beispielsweise könnte man in bestimmten Räumen das Licht oder Geräte ausschalten, die man ansonsten unberührt gelassen hätte, wenn andere noch wach blieben.

== Definition der Aktionen für den Prozess "schlafen legen" ==

Legt sich der Bewohner ins Bett und möchte schlafen, wechselt er den Status seines ROOMMATE-Devices auf "asleep". Ich mache das bei mir durch einen extra Wandschalter.

In unserem Beispiel werden jetzt die Aktionen aus Macro_rr_Julian_asleep ausgeführt. In dem Macro wird besonders Wert darauf gelegt, dass ausschließlich Aktionen ausgeführt werden, die mit dem Schlafzimmer des Bewohners zu tun haben, damit andere Bewohner in anderen Räumen nicht beeinträchtigt werden.

Zeitgleich werden im RESIDENTS-Device rgr_Bewohner das Reading "residentsGotosleep" um 1 erniedrigt, das Reading "residentsAsleep" um 1 erhöht und ein Event erzeugt. Befinden sich gar alle anwesenden Bewohner im Status "asleep" wechselt der Gesamtstatus von rgr_Bewohner auch auf "asleep". Dies löst dann Macro_rgr_Bewohner_asleep aus. Dort werden dann auch wieder Schaltungen vorgenommen, die von größerer Tragweite sind. Beispielsweise werden alle noch übrigen Lichter im Haus ausgeschaltet und die Musikwiedergabe in Gemeinschaftsräumen (wie hier dem Badezimmer) gestoppt.

== Definition der Aktionen für den Prozess "aufgestanden sein" ==

Wir gehen nun davon aus, dass irgendwann morgens das Weckprogramm wie oben zuvor definiert abgespielt wird. Dabei wechselt im Device rgr_Bewohner das Reading residentsTotalWakeup auf 1 (oder höher bei mehreren gleichzeitig aktiven Weckprogrammen unterschiedlicher Bewohner).

Während des Weckprogramms (oder natürlich auch davor) kann der Bewohner jederzeit in den Status "awoken" wechseln. Ich nutze bei mir auch hier wieder den Wandschalter.
Dadurch wird ein evtl. noch laufendes Weckprogramm unterbrochen (die at-Devices in FHEM werden automatisch aufgräumt) und die Aktionen in Macro_rr_Julian_awoken werden ausgeführt.

Neben dem expliziten Wechsel zum Status "awoken" kann aber, wie oben beschrieben, auch das Weckprogramm selbst den Bewohner auf diesen Status setzen. Dies wird dann als forciertes Wecken bezeichnet; sozusagen um seinen Hintern aus dem Bett zu bewegen :-)
Sinnvollerweise wechselt der Status des Bewohners nach kurzer Zeit dann automatisch von "awoken" auf "home", also den Standard-Status wenn man zuhause ist.

Zeitgleich zum Wechsel des ROOMMATE-Devices auf "awoken" wird auch wieder das RESIDENTS-Device automatisch angepasst: Das Reading "residentsAsleep" wird um 1 erniedrigt, das Reading "residentsAwoken" um 1 erhöht und ein Event erzeugt.
Außerdem wird der Gesamtstatus auf "awoken" gesetzt. Dies löst Macro_rgr_Bewohner_awoken aus. Hier werden auch wieder Schaltungen vorgenommen, die das Haus dann für den ersten, der aufsteht, entsprechend einzustellen, also beispielsweise das Licht in der Küche einschalten.
Zusätzlich wird dann ein temporäres at-Devices angelegt, welches dafür sorgt, dass der Haus Modus nach 1,5h von "Morgen" auf "Tag" wechselt. Allerdings ist der Haus Modus wie schon erwähnt hier nicht das Hauptthema und wird aktuell auch noch nicht direkt vom RESIDENTS Toolkit unterstützt (Sneak-Peek auf zukünftige Erweiterungen ;-)).

== Snooze Funktion bei SONOS ==

Damit man an gewissen Tagen auch dem Wecker mal auf'n Kopp hauen kann (bzw. auf den Start/Stop Button am SONOS Gerät), kann man ein einfaches DOIF erzeugen, welches dafür sorgt, dass man nach 5 Minuten wieder daran erinnert wird aufzustehen:

<pre>
define di_Sonos_Snooze DOIF (
[Sonos_Bedroom:?transportState] and (
([rr_Julian:wakeup] == 0 and [rr_Julian:wakeup:sec] >= 600) or
$we
) or
(
([rr_Julian:wakeup] == 0 and [rr_Julian:wakeup:sec] >= 600) or
$we
)
)

DOELSEIF
(
[Sonos_Bedroom:?transportState] and
([Sonos_Bedroom:transportState] eq "STOPPED" or [Sonos_Bedroom:transportState] eq "PAUSED_PLAYBACK") and
([?rr_Julian:wakeup] == 1 or [rr_Julian:wakeup:sec] < 600) and
!$we
)
(
set Sonos_Bedroom:FILTER=transportState!=PLAYING Play
)

DOELSE

attr alias Automation: Sonos Snoozing
attr cmdState off|on|standby
attr comment snooze function for wake-up program via SONOS device button
attr devStateIcon off:general_aus on:general_an@green standby:general_an@orange
attr wait 0:300:0
</pre>

Das DOIF hier greift nur während ein Weckprogramm läuft oder maximal noch 10 Minuten danach; zudem nur wochentags :-)

Außerdem zeigt der DOIF Status an, ob die Snooze Funktion gerade scharf geschaltet ist oder nicht.

Wichtig ist auch, dass das ROOMMATE Device ein Event bei der Änderung des wakeup Readings auslöst, also z.B. das Attribut event-on-change-reading dann entsprechend auch "wakeup" enthält.

[[Kategorie:Examples]]
[[Kategorie:Code_Snippets]]

Weckautomation

2017-04-09T10:56:13Z

Loredo:

Die Module ROOMMATE und GUEST können dazu genutzt werden, Bewohner und Gäste in FHEM als ein Device zu repräsentieren und durch Events deren Status zu erfassen bzw. zu ändern (beispielsweise durch das GEOFANCY Modul für [[Anwesenheitserkennung]]). Das zur Modulfamilie dazugehörige Modul RESIDENTS fasst die Status mehrerer Bewohner logisch zusammen.

Inzwischen unterstützen die Module auch bei der Erstellung einer Weckautomation, indem sie die Logik kapseln und häufig verwendete Standardfunktionen bereitstellen. Die Verwendung soll in diesem Artikel anhand eines Beispiels näher erläutert werden.

[[Datei:Weckprogramm_Ergebnisdarstellung.png|500px|thumb|right|Darstellung der Beispiel-Konfiguration]]

== Was soll erreicht werden? ==

Hier ein kurzer Überblick über die Funktionen, die wir am Ende realisiert haben werden:

; 3 unterschiedliche Wecker
: 1 für Werktage Mo-Fr
: 1 für werktägliche Samstage
: 1 für Sonn- und Feiertage
; Automatischer Reset der Weckzeiten
: werktäglicher Wecker soll auf einen Standardwert zurückstellen, falls er mal verstellt wurde
: automatischer Reset des werktäglicher Weckers soll zeitweise abschaltbar sein
: nach einem Sonn- oder Feiertagen soll der automatische Reset des werktäglichen Weckers immer wieder eingeschaltet werden
: die Samstags- und Sonntags-Wecker sollen immer nach ihrer Ausführung resettet werden
; jeder Wecker startet ein Weckprogramm 30 Minuten vor der programmierten Zeit
: langsames hochfahren der Rollläden
: Wakeup Light über eine HUE Birne von Warmweiß/2000K zu Kaltweiß/5600K
: an Werktagen: Chillout Weckmusik wird langsam lauter gestellt
: Snooze Funktion über die SONOS Taste am Gerät an Werktagen (erneutes Play nach 5 Minuten)
: forciertes Aufstehen an Werktagen durch automatischen Wechsel des Bewohner Devices zu "awake" und dadurch starten der "aufgewacht sein" Prozesse (siehe unten)
; Starten des Weckprogramms nur bei tatsächlicher Anwesenheit des betroffenen Bewohners
; Ansage der Uhrzeit zur gewählten Weckzeit
; Prozess / Automation für:
: <u>bettfertig machen</u>: Lichtszene setzen, Chillout Musik in Schlafzimmer und Badezimmer abspielen
: <u>schlafen legen</u>: Ansage der eingestellten Weckzeit & Ausschalten aller Verbraucher
: <u>aufgewacht sein</u>: Ansage Raumluftqualität, Wettervorhersage; Lokalradio einschalten und in Räume verteilen; Küchenlicht an, HUE in Schlafzimmer mit Aufwach-Farbtemperatur
; Berücksichtigung / Steuerung des Haus Modus
: Wechsel zwischen Morgen-, Tag-, Abend- und Nacht-Modus entsprechend der Schlafgewohnheiten (zusätzlich zur Tageszeit abhängigen Steuerung/Umschaltung, die hier aber nicht Thema sein soll)
; Statuswerte, Events, Readings und Funktionen:
: Wurde ein Wecker ausgelöst?
: Ist gerade ein Weckprogramm aktiv?
: Abbrechen/sofortiges beenden des Weckprogramms
: Verhindern von durch Fehlkonfiguration parallel ausgeführten Weckern für die selbe Person
: Welcher ist der nächste Wecker, der bis Mitternacht des nächsten Tages ausgeführt wird und wann ist das?
: Wann wurde ein Wecker zuletzt ausgeführt und welcher Wecker wurde überhaupt zuletzt ausgeführt?
: Wie viele Bewohner werden gerade geweckt?
: Wie viele Bewohner sind gerade aufgewacht?
: Schaltung bei erstem Bewohner, der geweckt wird
: Schaltung bei erstem Bewohner, der aufgewacht ist
; Statistik
: Wie lange dauerte der Schlaf des Bewohners?
: Wie lange war in dem Haus niemand wach?

Wichtig dabei zu erwähnen ist, dass die Prozesse so umgesetzt worden sind, dass Bewohner sowohl zeitgleich, als auch zeitversetzt oder komplett getrennt ins Bett gehen und aufwachen können.
Dafür werden einige Schaltungen pro Bewohner und dessen Schlafzimmer vorgenommen und andere erst dann, wenn die RESIDENTS Bewohnergruppe einen bestimmten Status erreicht hat.

== Notwendige Devices anlegen ==

=== RESIDENTS und ROOMMATE Devices ===
Wir starten mit einem RESIDENTS Device, um die Bewohner Status später logisch zusammenfassen zu können:

<pre>
define rgr_Bewohner RESIDENTS
</pre>

Anschließend legen wir pro Bewohner ein ROOMMATE Device an. Dafür verwenden wir eine Funktion, die in RESIDENTS eingebaut ist und die Devices korrekt untereinander verbindet (die Reihenfolge, in der RESIDENTS und ROOMMATE/GUEST Geräte definiert werden, sind hier entscheidend). Der Einfachheit halber definieren wir in diesem Beispiel nur einen Bewohner.

<pre>
set rgr_Bewohner addRoommate Julian
</pre>

Es wurde nun automatisch ein Device namens "rr_Julian" angelegt (abgeleitet aus dem angegebenen Vornamen aus dem addRoommate Befehl).
Anschließend setzen wir einmalig den initialen Status für die Bewohner mittels set Befehl:

<pre>
set rr_Julian home
</pre>

Der automatische Wechsel des Status bei Anwesenheit/Abwesenheit wird hier nicht weiter thematisiert, hier sei auf den Artikel [[Anwesenheitserkennung]] verwiesen, insbesondere den GEOFANCY Teil.

=== Wecker Devices anlegen ===

Die Devices, über die die Weckzeit und das Auslöseverhalten eingestellt werden, sind eigentlich normale Dummy Devices. Das zugewiesene ROOMMATE/GUEST/RESIDENTS Device "versklavt" diese Geräte jedoch und führt bestimmte Befehle zur Wecksteuerung und -Verwaltung aus, sobald das Dummy-Device geändert wird. Der Vorteil dabei ist, dass man sich eine Menge eigenen Code und viele unterschiedliche Notify und Dummy Devices spart, was wiederum der Übersichtlichkeit zu Gute kommt.

Wir legen nun unsere drei Wecker für unseren Beispiel Bewohner an. Dafür führen wir einfach 3 mal den selben Befehl hintereinander aus:

<pre>
set rr_Julian create wakeuptimer
set rr_Julian create wakeuptimer
set rr_Julian create wakeuptimer
</pre>

In der Logdatei erscheinen verschiedene Meldungen über alle automatisch angelegte Devices inkl. Name und Typ:

<pre>
2015.03.28 12:19:49 3: RESIDENTStk rr_Julian_wakeuptimer1: new notify macro device Macro_rr_Julian_wakeuptimer1 created
2015.03.28 12:19:50 3: RESIDENTStk rr_Julian_wakeuptimer1: new at-device at_rr_Julian_wakeuptimer1 created
2015.03.28 12:19:50 3: RESIDENTStk rr_Julian_wakeuptimer1: new macro device Macro_rr_Julian_gotosleep created
2015.03.28 12:19:50 3: RESIDENTStk rr_Julian_wakeuptimer1: new watchdog device wd_rr_Julian_gotosleep created
2015.03.28 12:19:50 3: RESIDENTStk rr_Julian_wakeuptimer1: new macro device Macro_rr_Julian_asleep created
2015.03.28 12:19:50 3: RESIDENTStk rr_Julian_wakeuptimer1: new watchdog device wd_rr_Julian_asleep created
2015.03.28 12:19:50 3: RESIDENTStk rr_Julian_wakeuptimer1: new macro device Macro_rr_Julian_awoken created
2015.03.28 12:19:50 3: RESIDENTStk rr_Julian_wakeuptimer1: new watchdog device wd_rr_Julian_awoken created
2015.03.28 12:19:50 3: RESIDENTStk rr_Julian_wakeuptimer1: new macro device Macro_rgr_Bewohner_gotosleep created
2015.03.28 12:19:50 3: RESIDENTStk rr_Julian_wakeuptimer1: new watchdog device wd_rgr_Bewohner_gotosleep created
2015.03.28 12:19:50 3: RESIDENTStk rr_Julian_wakeuptimer1: new macro device Macro_rgr_Bewohner_asleep created
2015.03.28 12:19:50 3: RESIDENTStk rr_Julian_wakeuptimer1: new watchdog device wd_rr_Julian_asleep created
2015.03.28 12:19:50 3: RESIDENTStk rr_Julian_wakeuptimer1: new macro device Macro_rgr_Bewohner_awoken created
2015.03.28 12:19:51 3: RESIDENTStk rr_Julian_wakeuptimer1: new watchdog device wd_rr_Julian_awoken created
2015.03.28 12:21:49 3: RESIDENTStk rr_Julian_wakeuptimer2: new notify macro device Macro_rr_Julian_wakeuptimer2 created
2015.03.28 12:21:49 3: RESIDENTStk rr_Julian_wakeuptimer2: new at-device at_rr_Julian_wakeuptimer2 created
2015.03.28 12:21:56 3: RESIDENTStk rr_Julian_wakeuptimer3: new notify macro device Macro_rr_Julian_wakeuptimer3 created
2015.03.28 12:21:56 3: RESIDENTStk rr_Julian_wakeuptimer3: new at-device at_rr_Julian_wakeuptimer3 created
</pre>

Als Rückgabe in FHEMWEB erhält man eine Meldung wie diese hier:

<pre>
Dummy rr_Julian_wakeuptimer1 and other pending devices created and pre-configured.
You may edit Macro_rr_Julian_wakeuptimer1 to define your wake-up actions
and at_rr_Julian_wakeuptimer1 for optional at-device adjustments.
</pre>

Wie man sieht wurden anfänglich eine ganze Menge von Notify-Macros und Watchdogs sowie ein at-Device pro Wecker angelegt.
Dabei sind vor allem die Macro-Devices und die Wecker Dummy Devices interessant. Hier werden Weck- und Auslöseverhalten konfiguriert. die at- und Watchdog-Devices können aber für fortgeschrittene Nutzer beliebig angepasst werden. Auch die Dummy Devices können bis auf wenige Ausnahmen (Attribut "userattr") vollständig umkonfiguriert werden. Wer Devices umbenennt, sollte unbedingt darauf achten, dass auch das entsprechende Attribut im Wecker-Dummy-Device angepasst wird.

Allen Devices ist ein entsprechender Kommentar hinzugefügt, der dessen Funktion kurz erklärt.
Alle Macros enthalten bereits ein Gerüst für den Weckprozess mit einigen Beispielen. Die Beispielschaltungen sind dabei noch auskommentiert. Nicht auskommentierter Code sollte als notwendiger Teil für die Weckautomation betrachtet werden und wird dort auch durch einen entsprechenden Kommentar erklärt.

Im Folgenden werden wir jetzt Schritt für Schritt das oben beschriebene Szenario konfigurieren.

== Konfiguration des Auslöseverhaltens ==

In der Grundkonfiguration löst jeder Wecker sein eigenes Weckprogramm täglich zur voreingestellten Zeit aus. Dabei wird allerdings kein längeres Programm gestartet, sondern lediglich einmalig das im Attribut wakeupMacro hinterlegte Notify-Macro getriggert. Das ist in der Beispiel-Grundkonfiguration kein Problem und lässt lediglich einen Logfile Eintrag erstellen.

Als erstes möchten wir, dass alle 3 Timer das selbe Macro zum Wecken verwenden, damit wir den Code nur einmal pflegen müssen. Die anderen beiden Macros löschen wir anschließend:

<pre>
attr rr_Julian_wakeuptimer2 wakeupMacro Macro_rr_Julian_wakeuptimer1
attr rr_Julian_wakeuptimer3 wakeupMacro Macro_rr_Julian_wakeuptimer1
delete Macro_rr_Julian_wakeuptimer2
delete Macro_rr_Julian_wakeuptimer3
</pre>

Nun konfigurieren wir die Auslöseverhalten so, wie wir es oben vorgegeben haben:

=== Wake-up Timer 1 ===

Wecker nur Mo-Fr auslösen:
<pre>
attr rr_Julian_wakeuptimer1 wakeupDays 1,2,3,4,5
</pre>

Wecker zusätzlich auf Tage beschränken, die keine Feiertage sind:
<pre>
attr rr_Julian_wakeuptimer1 wakeupHolidays andNoHoliday
</pre>
<i><u>Hinweis:</u> Hierfür muss ein [http://fhem.de/commandref.html#holiday holiday-Device] erstellt sein und in der global Config im Attribut 'holidays2we‘ verlinkt sein. Ansonsten erhält man beim setzen einer Weckzeit später entsprechende Fehlermeldungen, die darauf hinweisen.</i>

Länge des Weckprogramms auf 30 Minuten festlegen (sprich 30 Minuten vor der eingestellten Weckzeit beginnen):
<pre>
attr rr_Julian_wakeuptimer1 wakeupOffset 30
</pre>

Aufstehen forcieren:
<pre>
attr rr_Julian_wakeuptimer1 wakeupEnforced 1
</pre>

Standard Weckzeit hinterlegen:
<pre>
attr rr_Julian_wakeuptimer1 wakeupDefaultTime 07:30
</pre>

Weckzeit nur an diesen Tagen automatisch zurückstellen:
<pre>
attr rr_Julian_wakeuptimer1 wakeupResetdays 1,2,3,4,5
</pre>
<i><u>Hinweis:</u> Ein Reset findet normalerweise nach jeder Auslösung statt, sprich wenn das Weckprogramm tatsächlich gestartet wurde. Dies kann man auf bestimmte Tage einschränken.</i>

Zum einfacheren Aktivieren/Deaktivieren des Resets wollen wir ein weiteres Dummy nutzen:
<pre>
attr rr_Julian_wakeuptimer1 wakeupResetSwitcher rr_Julian_wakeuptimer1_resetswitcher
</pre>
<i><u>Hinweis:</u> Der Dummy-Gerätename kann frei gewählt werden. Sofern es nicht existiert wird es automatisch angelegt und vorkonfiguriert.</i>

=== Wake-up Timer 2 ===

Wecker nur Samstags auslösen:
<pre>
attr rr_Julian_wakeuptimer2 wakeupDays 6
</pre>

Wecker zusätzlich auf Tage beschränken, die keine Feiertage sind:
<pre>
attr rr_Julian_wakeuptimer2 wakeupHolidays andNoHoliday
</pre>

Länge des Weckprogramms auf 30 Minuten festlegen (sprich 30 Minuten vor der eingestellten Weckzeit beginnen):
<pre>
attr rr_Julian_wakeuptimer2 wakeupOffset 30
</pre>

Aufstehen forcieren:
<pre>
attr rr_Julian_wakeuptimer2 wakeupEnforce 1
</pre>

Standard Weckzeit hinterlegen:
<pre>
attr rr_Julian_wakeuptimer2 wakeupDefaultTime 09:30
</pre>

Weckzeit nur an diesen Tagen automatisch zurückstellen:
<pre>
attr rr_Julian_wakeuptimer2 wakeupResetdays 6
</pre>

=== Wake-up Timer 3 ===

Wecker nur Sonntags auslösen:
<pre>
attr rr_Julian_wakeuptimer3 wakeupDays 0
</pre>

Wecker zusätzlich auch an Feiertagen ausführen:
<pre>
attr rr_Julian_wakeuptimer3 wakeupHolidays orHoliday
</pre>

Aufstehen nur forcieren, wenn eine frühere Weckzeit als die Standard Weckzeit eingestellt wurde:
<pre>
attr rr_Julian_wakeuptimer3 wakeupEnforce 3
</pre>

Länge des Weckprogramms auf 30 Minuten festlegen (sprich 30 Minuten vor der eingestellten Weckzeit beginnen):
<pre>
attr rr_Julian_wakeuptimer3 wakeupOffset 30
</pre>

Standard Weckzeit hinterlegen:
<pre>
attr rr_Julian_wakeuptimer3 wakeupDefaultTime 10:30
</pre>

== Definition des Weckprogramms ==

Die Aktionen, welche innerhalb der 30 Minuten Weckzeitraum abgearbeitet werden sollen, sind im Device Macro_rr_Julian_wakeuptimer1 hinterlegt.
Dieses Macro wird 2 Mal aufgerufen: Das erste Mal beim Beginn des Weckprogramms und ein zweites Mal beim Ende des Weckprogramms. Der Hintergrund ist, dass das Macro beim Beenden dann entsprechend dafür sorgen kann bisher nicht ausgeführte Befehle des Programmablaufes zu stornieren. Hierfür ist die for-Schleife am Anfang des Macros gedacht und deckt per Default 10 Arbeitsschritte ab (ansonsten einfach die Zahl entsprechend erhöhen).

Das Macro Template hat bereits alle oben beschriebenen Funktionen als auskommentierte FHEM Befehle enthalten. Diese sollen natürlich nur dem Beispiel und der eigenen Inspiration dienen. Wir müssten diese an dieser Stelle lediglich einkommentieren...
Insgesamt fällt bei genauerem hinsehen folgendes auf:

* es stehen bestimmte Umgebungsvariablen bereit, die während des Programmablaufes genutzt werden können
* das Macro ist in 3 Bereiche unterteilt und nutzt dafür die Umgebungsvariable $EVTPART0 bzw. ob deren Wert auf "start" oder "stop" steht
* der erste Bereich mit der for-Schleife wird immer ausgeführt. Sie räumt durch das Macro erzeugte temporäre at-Devices auf (entweder weil das Programm früher beendet werden soll oder von vorne beginnen soll)
* der zweite Bereich "start" führt erste FHEM Befehle direkt nach dem Beginn des Weckprogramms aus. Außerdem werden weitere Befehle in bestimmten Etappen zur zeitversetzten Ausführung vorgemerkt. Dafür werden temporär erzeugte at-Devices verwendet.
* der Name der at-Devices folgt einem bestimmten Schema, nämlich atTmp_<LAUFENDE-NUMMER>_$NAME. Die laufende Nummer muss man manuell hochzählen, der Rest kann einfach kopiert werden. Dadurch wird das aufräumen oben im Macro einfacher.
* bei der Definition der at-Devices müssen mehrere FHEM Befehle hintereinander mit 2 Semikolon statt einem getrennt werden (siehe auch [http://fhem.de/commandref_DE.html#command Kommando-Referenz]).
* bei bedingten Schaltungen empfehlt es sich für übersichtlicheren Code die :FILTER Funktion zu nutzen (siehe auch [http://fhem.de/commandref_DE.html#devspec Kommando-Referenz]).
* es ist unbedingt darauf zu achten, dass das letzte at-Device nicht nach der wakeupOffset Zeit definiert wird, da es ansonsten automatisch gelöscht und somit nicht mehr ausgeführt wird
* nach einem ordentlichen Ende des Weckprogramms wird ein at-Device erzeugt, welches das Benutzer-Device automatisch nach "awoken" oder "home" schaltet, abhängig davon ob das Wecken forciert werden soll oder nicht. Dieser Teil wird tatsächlich nur geplant, wenn das Weckprogramm ordentlich beendet wurde. Wurde das Weckprogramm durch ein "set rr_Julian_wakeuptimer1 stop" bzw. durch Klick auf das blaue Device-Icon beendet, so werden die Post-Wakeup Befehle nicht mehr ausgeführt, weil man davon ausgehen kann, dass ein Abbruch des Programms und somit aller seiner weiteren Schaltungen gewünscht ist.

Man kann sein Weckprogramm auf zwei Arten testen:

* durch senden des set-Befehls "trigger": hier werden die aktuellen Auslösedefinitionen berücksichtigt; sprich, wenn heute nicht der richtige Tag ist, wird das Programm nicht gestartet
* durch senden des set-Befehls "start" kann man alle Auslösedefinitionen umgehen und das Weckprogramm direkt auslösen

Zu Debug-Zwecken kann man auf das Wecker Dummy-Device das Attribut "verbose" auf 4 setzen. Im Logfile wird dann sehr ausführlich geloggt, warum wie geschaltet oder nicht geschaltet wird und wie die Entscheidungen getroffen worden sind, Readings zu aktualisieren etc. Damit lässt sich prüfen, ob das gewünschte Auslöseverhalten tatsächlich richtig funktioniert.

== Definition der Aktionen für den Prozess "bettfertig machen" ==

Möchte der Bewohner nun ins Bett gehen und sich dabei noch etwas darauf einstimmen, kann er sein "bettfertig machen"-Programm dadurch starten, dass er den Status seines ROOMMATE-Devices in FHEM auf "gotosleep" setzt.
In unserem Beispiel werden dann die Aktionen aus Macro_rr_Julian_gotosleep ausgeführt.

Zeitgleich wird im RESIDENTS-Device rgr_Bewohner das Reading "residentsGotosleep" um 1 erhöht und ein Event erzeugt. Befinden sich gar alle anwesenden Bewohner im Status "gotosleep" wechselt der Gesamtstatus von rgr_Bewohner auch auf "gotosleep". Dies löst dann Macro_rgr_Bewohner_gotosleep aus. Dort werden dann Schaltungen vorgenommen, die von größerer Tragweite sind, als wenn nur ein einzelner Bewohner ins Bett geht. Beispielsweise könnte man in bestimmten Räumen das Licht oder Geräte ausschalten, die man ansonsten unberührt gelassen hätte, wenn andere noch wach blieben.

== Definition der Aktionen für den Prozess "schlafen legen" ==

Legt sich der Bewohner ins Bett und möchte schlafen, wechselt er den Status seines ROOMMATE-Devices auf "asleep". Ich mache das bei mir durch einen extra Wandschalter.

In unserem Beispiel werden jetzt die Aktionen aus Macro_rr_Julian_asleep ausgeführt. In dem Macro wird besonders Wert darauf gelegt, dass ausschließlich Aktionen ausgeführt werden, die mit dem Schlafzimmer des Bewohners zu tun haben, damit andere Bewohner in anderen Räumen nicht beeinträchtigt werden.

Zeitgleich werden im RESIDENTS-Device rgr_Bewohner das Reading "residentsGotosleep" um 1 erniedrigt, das Reading "residentsAsleep" um 1 erhöht und ein Event erzeugt. Befinden sich gar alle anwesenden Bewohner im Status "asleep" wechselt der Gesamtstatus von rgr_Bewohner auch auf "asleep". Dies löst dann Macro_rgr_Bewohner_asleep aus. Dort werden dann auch wieder Schaltungen vorgenommen, die von größerer Tragweite sind. Beispielsweise werden alle noch übrigen Lichter im Haus ausgeschaltet und die Musikwiedergabe in Gemeinschaftsräumen (wie hier dem Badezimmer) gestoppt.

== Definition der Aktionen für den Prozess "aufgewacht sein" ==

Wir gehen nun davon aus, dass irgendwann morgens das Weckprogramm wie oben zuvor definiert abgespielt wird. Dabei wechselt im Device rgr_Bewohner das Reading residentsTotalWakeup auf 1 (oder höher bei mehreren gleichzeitig aktiven Weckprogrammen unterschiedlicher Bewohner).

Während des Weckprogramms (oder natürlich auch davor) kann der Bewohner jederzeit in den Status "awoken" wechseln. Ich nutze bei mir auch hier wieder den Wandschalter.
Dadurch wird ein evtl. noch laufendes Weckprogramm unterbrochen (die at-Devices in FHEM werden automatisch aufgräumt) und die Aktionen in Macro_rr_Julian_awoken werden ausgeführt.

Neben dem expliziten Wechsel zum Status "awoken" kann aber, wie oben beschrieben, auch das Weckprogramm selbst den Bewohner auf diesen Status setzen. Dies wird dann als forciertes Wecken bezeichnet; sozusagen um seinen Hintern aus dem Bett zu bewegen :-)
Sinnvollerweise wechselt der Status des Bewohners nach kurzer Zeit dann automatisch von "awoken" auf "home", also den Standard-Status wenn man zuhause ist.

Zeitgleich zum Wechsel des ROOMMATE-Devices auf "awoken" wird auch wieder das RESIDENTS-Device automatisch angepasst: Das Reading "residentsAsleep" wird um 1 erniedrigt, das Reading "residentsAwoken" um 1 erhöht und ein Event erzeugt.
Außerdem wird der Gesamtstatus auf "awoken" gesetzt. Dies löst Macro_rgr_Bewohner_awoken aus. Hier werden auch wieder Schaltungen vorgenommen, die das Haus dann für den ersten, der aufsteht, entsprechend einzustellen, also beispielsweise das Licht in der Küche einschalten.
Zusätzlich wird dann ein temporäres at-Devices angelegt, welches dafür sorgt, dass der Haus Modus nach 1,5h von "Morgen" auf "Tag" wechselt. Allerdings ist der Haus Modus wie schon erwähnt hier nicht das Hauptthema und wird aktuell auch noch nicht direkt vom RESIDENTS Toolkit unterstützt (Sneak-Peek auf zukünftige Erweiterungen ;-)).

== Snooze Funktion bei SONOS ==

Damit man an gewissen Tagen auch dem Wecker mal auf'n Kopp hauen kann (bzw. auf den Start/Stop Button am SONOS Gerät), kann man ein einfaches DOIF erzeugen, welches dafür sorgt, dass man nach 5 Minuten wieder daran erinnert wird aufzustehen:

<pre>
define di_Sonos_Snooze DOIF (
[Sonos_Bedroom:?transportState] and (
([rr_Julian:wakeup] == 0 and [rr_Julian:wakeup:sec] >= 600) or
$we
) or
(
([rr_Julian:wakeup] == 0 and [rr_Julian:wakeup:sec] >= 600) or
$we
)
)

DOELSEIF
(
[Sonos_Bedroom:?transportState] and
([Sonos_Bedroom:transportState] eq "STOPPED" or [Sonos_Bedroom:transportState] eq "PAUSED_PLAYBACK") and
([?rr_Julian:wakeup] == 1 or [rr_Julian:wakeup:sec] < 600) and
!$we
)
(
set Sonos_Bedroom:FILTER=transportState!=PLAYING Play
)

DOELSE

attr alias Automation: Sonos Snoozing
attr cmdState off|on|standby
attr comment snooze function for wake-up program via SONOS device button
attr devStateIcon off:general_aus on:general_an@green standby:general_an@orange
attr wait 0:300:0
</pre>

Das DOIF hier greift nur während ein Weckprogramm läuft oder maximal noch 10 Minuten danach; zudem nur wochentags :-)

Außerdem zeigt der DOIF Status an, ob die Snooze Funktion gerade scharf geschaltet ist oder nicht.

Wichtig ist auch, dass das ROOMMATE Device ein Event bei der Änderung des wakeup Readings auslöst, also z.B. das Attribut event-on-change-reading dann entsprechend auch "wakeup" enthält.

[[Kategorie:Examples]]
[[Kategorie:Code_Snippets]]

Weckautomation

2017-04-09T10:55:21Z

Loredo: /* Wake-up Timer 3 */

Die Module ROOMMATE und GUEST können dazu genutzt werden, Bewohner und Gäste in FHEM als ein Device zu repräsentieren und durch Events deren Status zu erfassen bzw. zu ändern (beispielsweise durch das GEOFANCY Modul für [[Anwesenheitserkennung]]). Das zur Modulfamilie dazugehörige Modul RESIDENTS fasst die Status mehrerer Bewohner logisch zusammen.

Inzwischen unterstützen die Module auch bei der Erstellung einer Weckautomation, indem sie die Logik kapseln und häufig verwendete Standardfunktionen bereitstellen. Die Verwendung soll in diesem Artikel anhand eines Beispiels näher erläutert werden.

[[Datei:Weckprogramm_Ergebnisdarstellung.png|500px|thumb|right|Darstellung der Beispiel-Konfiguration]]

== Was soll erreicht werden? ==

Hier ein kurzer Überblick über die Funktionen, die wir am Ende realisiert haben werden:

; 3 unterschiedliche Wecker
: 1 für Werktage Mo-Fr
: 1 für werktägliche Samstage
: 1 für Sonn- und Feiertage
; Automatischer Reset der Weckzeiten
: werktäglicher Wecker soll auf einen Standardwert zurückstellen, falls er mal verstellt wurde
: automatischer Reset des werktäglicher Weckers soll zeitweise abschaltbar sein
: nach einem Sonn- oder Feiertagen soll der automatische Reset des werktäglichen Weckers immer wieder eingeschaltet werden
: die Samstags- und Sonntags-Wecker sollen immer nach ihrer Ausführung resettet werden
; jeder Wecker startet ein Weckprogramm 30 Minuten vor der programmierten Zeit
: langsames hochfahren der Rollläden
: Wakeup Light über eine HUE Birne von Warmweiß/2000K zu Kaltweiß/5600K
: an Werktagen: Chillout Weckmusik wird langsam lauter gestellt
: Snooze Funktion über die SONOS Taste am Gerät an Werktagen (erneutes Play nach 5 Minuten)
: forciertes Aufstehen an Werktagen durch automatischen Wechsel des Bewohner Devices zu "awake" und dadurch starten der "aufgewacht sein" Prozesse (siehe unten)
; Starten des Weckprogramms nur bei tatsächlicher Anwesenheit des betroffenen Bewohners
; Ansage der Uhrzeit zur gewählten Weckzeit
; Prozess / Automation für:
: <u>bettfein machen</u>: Lichtszene setzen, Chillout Musik in Schlafzimmer und Badezimmer abspielen
: <u>schlafen legen</u>: Ansage der eingestellten Weckzeit & Ausschalten aller Verbraucher
: <u>aufgewacht sein</u>: Ansage Raumluftqualität, Wettervorhersage; Lokalradio einschalten und in Räume verteilen; Küchenlicht an, HUE in Schlafzimmer mit Aufwach-Farbtemperatur
; Berücksichtigung / Steuerung des Haus Modus
: Wechsel zwischen Morgen-, Tag-, Abend- und Nacht-Modus entsprechend der Schlafgewohnheiten (zusätzlich zur Tageszeit abhängigen Steuerung/Umschaltung, die hier aber nicht Thema sein soll)
; Statuswerte, Events, Readings und Funktionen:
: Wurde ein Wecker ausgelöst?
: Ist gerade ein Weckprogramm aktiv?
: Abbrechen/sofortiges beenden des Weckprogramms
: Verhindern von durch Fehlkonfiguration parallel ausgeführten Weckern für die selbe Person
: Welcher ist der nächste Wecker, der bis Mitternacht des nächsten Tages ausgeführt wird und wann ist das?
: Wann wurde ein Wecker zuletzt ausgeführt und welcher Wecker wurde überhaupt zuletzt ausgeführt?
: Wie viele Bewohner werden gerade geweckt?
: Wie viele Bewohner sind gerade aufgewacht?
: Schaltung bei erstem Bewohner, der geweckt wird
: Schaltung bei erstem Bewohner, der aufgewacht ist
; Statistik
: Wie lange dauerte der Schlaf des Bewohners?
: Wie lange war in dem Haus niemand wach?

Wichtig dabei zu erwähnen ist, dass die Prozesse so umgesetzt worden sind, dass Bewohner sowohl zeitgleich, als auch zeitversetzt oder komplett getrennt ins Bett gehen und aufwachen können.
Dafür werden einige Schaltungen pro Bewohner und dessen Schlafzimmer vorgenommen und andere erst dann, wenn die RESIDENTS Bewohnergruppe einen bestimmten Status erreicht hat.

== Notwendige Devices anlegen ==

=== RESIDENTS und ROOMMATE Devices ===
Wir starten mit einem RESIDENTS Device, um die Bewohner Status später logisch zusammenfassen zu können:

<pre>
define rgr_Bewohner RESIDENTS
</pre>

Anschließend legen wir pro Bewohner ein ROOMMATE Device an. Dafür verwenden wir eine Funktion, die in RESIDENTS eingebaut ist und die Devices korrekt untereinander verbindet (die Reihenfolge, in der RESIDENTS und ROOMMATE/GUEST Geräte definiert werden, sind hier entscheidend). Der Einfachheit halber definieren wir in diesem Beispiel nur einen Bewohner.

<pre>
set rgr_Bewohner addRoommate Julian
</pre>

Es wurde nun automatisch ein Device namens "rr_Julian" angelegt (abgeleitet aus dem angegebenen Vornamen aus dem addRoommate Befehl).
Anschließend setzen wir einmalig den initialen Status für die Bewohner mittels set Befehl:

<pre>
set rr_Julian home
</pre>

Der automatische Wechsel des Status bei Anwesenheit/Abwesenheit wird hier nicht weiter thematisiert, hier sei auf den Artikel [[Anwesenheitserkennung]] verwiesen, insbesondere den GEOFANCY Teil.

=== Wecker Devices anlegen ===

Die Devices, über die die Weckzeit und das Auslöseverhalten eingestellt werden, sind eigentlich normale Dummy Devices. Das zugewiesene ROOMMATE/GUEST/RESIDENTS Device "versklavt" diese Geräte jedoch und führt bestimmte Befehle zur Wecksteuerung und -Verwaltung aus, sobald das Dummy-Device geändert wird. Der Vorteil dabei ist, dass man sich eine Menge eigenen Code und viele unterschiedliche Notify und Dummy Devices spart, was wiederum der Übersichtlichkeit zu Gute kommt.

Wir legen nun unsere drei Wecker für unseren Beispiel Bewohner an. Dafür führen wir einfach 3 mal den selben Befehl hintereinander aus:

<pre>
set rr_Julian create wakeuptimer
set rr_Julian create wakeuptimer
set rr_Julian create wakeuptimer
</pre>

In der Logdatei erscheinen verschiedene Meldungen über alle automatisch angelegte Devices inkl. Name und Typ:

<pre>
2015.03.28 12:19:49 3: RESIDENTStk rr_Julian_wakeuptimer1: new notify macro device Macro_rr_Julian_wakeuptimer1 created
2015.03.28 12:19:50 3: RESIDENTStk rr_Julian_wakeuptimer1: new at-device at_rr_Julian_wakeuptimer1 created
2015.03.28 12:19:50 3: RESIDENTStk rr_Julian_wakeuptimer1: new macro device Macro_rr_Julian_gotosleep created
2015.03.28 12:19:50 3: RESIDENTStk rr_Julian_wakeuptimer1: new watchdog device wd_rr_Julian_gotosleep created
2015.03.28 12:19:50 3: RESIDENTStk rr_Julian_wakeuptimer1: new macro device Macro_rr_Julian_asleep created
2015.03.28 12:19:50 3: RESIDENTStk rr_Julian_wakeuptimer1: new watchdog device wd_rr_Julian_asleep created
2015.03.28 12:19:50 3: RESIDENTStk rr_Julian_wakeuptimer1: new macro device Macro_rr_Julian_awoken created
2015.03.28 12:19:50 3: RESIDENTStk rr_Julian_wakeuptimer1: new watchdog device wd_rr_Julian_awoken created
2015.03.28 12:19:50 3: RESIDENTStk rr_Julian_wakeuptimer1: new macro device Macro_rgr_Bewohner_gotosleep created
2015.03.28 12:19:50 3: RESIDENTStk rr_Julian_wakeuptimer1: new watchdog device wd_rgr_Bewohner_gotosleep created
2015.03.28 12:19:50 3: RESIDENTStk rr_Julian_wakeuptimer1: new macro device Macro_rgr_Bewohner_asleep created
2015.03.28 12:19:50 3: RESIDENTStk rr_Julian_wakeuptimer1: new watchdog device wd_rr_Julian_asleep created
2015.03.28 12:19:50 3: RESIDENTStk rr_Julian_wakeuptimer1: new macro device Macro_rgr_Bewohner_awoken created
2015.03.28 12:19:51 3: RESIDENTStk rr_Julian_wakeuptimer1: new watchdog device wd_rr_Julian_awoken created
2015.03.28 12:21:49 3: RESIDENTStk rr_Julian_wakeuptimer2: new notify macro device Macro_rr_Julian_wakeuptimer2 created
2015.03.28 12:21:49 3: RESIDENTStk rr_Julian_wakeuptimer2: new at-device at_rr_Julian_wakeuptimer2 created
2015.03.28 12:21:56 3: RESIDENTStk rr_Julian_wakeuptimer3: new notify macro device Macro_rr_Julian_wakeuptimer3 created
2015.03.28 12:21:56 3: RESIDENTStk rr_Julian_wakeuptimer3: new at-device at_rr_Julian_wakeuptimer3 created
</pre>

Als Rückgabe in FHEMWEB erhält man eine Meldung wie diese hier:

<pre>
Dummy rr_Julian_wakeuptimer1 and other pending devices created and pre-configured.
You may edit Macro_rr_Julian_wakeuptimer1 to define your wake-up actions
and at_rr_Julian_wakeuptimer1 for optional at-device adjustments.
</pre>

Wie man sieht wurden anfänglich eine ganze Menge von Notify-Macros und Watchdogs sowie ein at-Device pro Wecker angelegt.
Dabei sind vor allem die Macro-Devices und die Wecker Dummy Devices interessant. Hier werden Weck- und Auslöseverhalten konfiguriert. die at- und Watchdog-Devices können aber für fortgeschrittene Nutzer beliebig angepasst werden. Auch die Dummy Devices können bis auf wenige Ausnahmen (Attribut "userattr") vollständig umkonfiguriert werden. Wer Devices umbenennt, sollte unbedingt darauf achten, dass auch das entsprechende Attribut im Wecker-Dummy-Device angepasst wird.

Allen Devices ist ein entsprechender Kommentar hinzugefügt, der dessen Funktion kurz erklärt.
Alle Macros enthalten bereits ein Gerüst für den Weckprozess mit einigen Beispielen. Die Beispielschaltungen sind dabei noch auskommentiert. Nicht auskommentierter Code sollte als notwendiger Teil für die Weckautomation betrachtet werden und wird dort auch durch einen entsprechenden Kommentar erklärt.

Im Folgenden werden wir jetzt Schritt für Schritt das oben beschriebene Szenario konfigurieren.

== Konfiguration des Auslöseverhaltens ==

In der Grundkonfiguration löst jeder Wecker sein eigenes Weckprogramm täglich zur voreingestellten Zeit aus. Dabei wird allerdings kein längeres Programm gestartet, sondern lediglich einmalig das im Attribut wakeupMacro hinterlegte Notify-Macro getriggert. Das ist in der Beispiel-Grundkonfiguration kein Problem und lässt lediglich einen Logfile Eintrag erstellen.

Als erstes möchten wir, dass alle 3 Timer das selbe Macro zum Wecken verwenden, damit wir den Code nur einmal pflegen müssen. Die anderen beiden Macros löschen wir anschließend:

<pre>
attr rr_Julian_wakeuptimer2 wakeupMacro Macro_rr_Julian_wakeuptimer1
attr rr_Julian_wakeuptimer3 wakeupMacro Macro_rr_Julian_wakeuptimer1
delete Macro_rr_Julian_wakeuptimer2
delete Macro_rr_Julian_wakeuptimer3
</pre>

Nun konfigurieren wir die Auslöseverhalten so, wie wir es oben vorgegeben haben:

=== Wake-up Timer 1 ===

Wecker nur Mo-Fr auslösen:
<pre>
attr rr_Julian_wakeuptimer1 wakeupDays 1,2,3,4,5
</pre>

Wecker zusätzlich auf Tage beschränken, die keine Feiertage sind:
<pre>
attr rr_Julian_wakeuptimer1 wakeupHolidays andNoHoliday
</pre>
<i><u>Hinweis:</u> Hierfür muss ein [http://fhem.de/commandref.html#holiday holiday-Device] erstellt sein und in der global Config im Attribut 'holidays2we‘ verlinkt sein. Ansonsten erhält man beim setzen einer Weckzeit später entsprechende Fehlermeldungen, die darauf hinweisen.</i>

Länge des Weckprogramms auf 30 Minuten festlegen (sprich 30 Minuten vor der eingestellten Weckzeit beginnen):
<pre>
attr rr_Julian_wakeuptimer1 wakeupOffset 30
</pre>

Aufstehen forcieren:
<pre>
attr rr_Julian_wakeuptimer1 wakeupEnforced 1
</pre>

Standard Weckzeit hinterlegen:
<pre>
attr rr_Julian_wakeuptimer1 wakeupDefaultTime 07:30
</pre>

Weckzeit nur an diesen Tagen automatisch zurückstellen:
<pre>
attr rr_Julian_wakeuptimer1 wakeupResetdays 1,2,3,4,5
</pre>
<i><u>Hinweis:</u> Ein Reset findet normalerweise nach jeder Auslösung statt, sprich wenn das Weckprogramm tatsächlich gestartet wurde. Dies kann man auf bestimmte Tage einschränken.</i>

Zum einfacheren Aktivieren/Deaktivieren des Resets wollen wir ein weiteres Dummy nutzen:
<pre>
attr rr_Julian_wakeuptimer1 wakeupResetSwitcher rr_Julian_wakeuptimer1_resetswitcher
</pre>
<i><u>Hinweis:</u> Der Dummy-Gerätename kann frei gewählt werden. Sofern es nicht existiert wird es automatisch angelegt und vorkonfiguriert.</i>

=== Wake-up Timer 2 ===

Wecker nur Samstags auslösen:
<pre>
attr rr_Julian_wakeuptimer2 wakeupDays 6
</pre>

Wecker zusätzlich auf Tage beschränken, die keine Feiertage sind:
<pre>
attr rr_Julian_wakeuptimer2 wakeupHolidays andNoHoliday
</pre>

Länge des Weckprogramms auf 30 Minuten festlegen (sprich 30 Minuten vor der eingestellten Weckzeit beginnen):
<pre>
attr rr_Julian_wakeuptimer2 wakeupOffset 30
</pre>

Aufstehen forcieren:
<pre>
attr rr_Julian_wakeuptimer2 wakeupEnforce 1
</pre>

Standard Weckzeit hinterlegen:
<pre>
attr rr_Julian_wakeuptimer2 wakeupDefaultTime 09:30
</pre>

Weckzeit nur an diesen Tagen automatisch zurückstellen:
<pre>
attr rr_Julian_wakeuptimer2 wakeupResetdays 6
</pre>

=== Wake-up Timer 3 ===

Wecker nur Sonntags auslösen:
<pre>
attr rr_Julian_wakeuptimer3 wakeupDays 0
</pre>

Wecker zusätzlich auch an Feiertagen ausführen:
<pre>
attr rr_Julian_wakeuptimer3 wakeupHolidays orHoliday
</pre>

Aufstehen nur forcieren, wenn eine frühere Weckzeit als die Standard Weckzeit eingestellt wurde:
<pre>
attr rr_Julian_wakeuptimer3 wakeupEnforce 3
</pre>

Länge des Weckprogramms auf 30 Minuten festlegen (sprich 30 Minuten vor der eingestellten Weckzeit beginnen):
<pre>
attr rr_Julian_wakeuptimer3 wakeupOffset 30
</pre>

Standard Weckzeit hinterlegen:
<pre>
attr rr_Julian_wakeuptimer3 wakeupDefaultTime 10:30
</pre>

== Definition des Weckprogramms ==

Die Aktionen, welche innerhalb der 30 Minuten Weckzeitraum abgearbeitet werden sollen, sind im Device Macro_rr_Julian_wakeuptimer1 hinterlegt.
Dieses Macro wird 2 Mal aufgerufen: Das erste Mal beim Beginn des Weckprogramms und ein zweites Mal beim Ende des Weckprogramms. Der Hintergrund ist, dass das Macro beim Beenden dann entsprechend dafür sorgen kann bisher nicht ausgeführte Befehle des Programmablaufes zu stornieren. Hierfür ist die for-Schleife am Anfang des Macros gedacht und deckt per Default 10 Arbeitsschritte ab (ansonsten einfach die Zahl entsprechend erhöhen).

Das Macro Template hat bereits alle oben beschriebenen Funktionen als auskommentierte FHEM Befehle enthalten. Diese sollen natürlich nur dem Beispiel und der eigenen Inspiration dienen. Wir müssten diese an dieser Stelle lediglich einkommentieren...
Insgesamt fällt bei genauerem hinsehen folgendes auf:

* es stehen bestimmte Umgebungsvariablen bereit, die während des Programmablaufes genutzt werden können
* das Macro ist in 3 Bereiche unterteilt und nutzt dafür die Umgebungsvariable $EVTPART0 bzw. ob deren Wert auf "start" oder "stop" steht
* der erste Bereich mit der for-Schleife wird immer ausgeführt. Sie räumt durch das Macro erzeugte temporäre at-Devices auf (entweder weil das Programm früher beendet werden soll oder von vorne beginnen soll)
* der zweite Bereich "start" führt erste FHEM Befehle direkt nach dem Beginn des Weckprogramms aus. Außerdem werden weitere Befehle in bestimmten Etappen zur zeitversetzten Ausführung vorgemerkt. Dafür werden temporär erzeugte at-Devices verwendet.
* der Name der at-Devices folgt einem bestimmten Schema, nämlich atTmp_<LAUFENDE-NUMMER>_$NAME. Die laufende Nummer muss man manuell hochzählen, der Rest kann einfach kopiert werden. Dadurch wird das aufräumen oben im Macro einfacher.
* bei der Definition der at-Devices müssen mehrere FHEM Befehle hintereinander mit 2 Semikolon statt einem getrennt werden (siehe auch [http://fhem.de/commandref_DE.html#command Kommando-Referenz]).
* bei bedingten Schaltungen empfehlt es sich für übersichtlicheren Code die :FILTER Funktion zu nutzen (siehe auch [http://fhem.de/commandref_DE.html#devspec Kommando-Referenz]).
* es ist unbedingt darauf zu achten, dass das letzte at-Device nicht nach der wakeupOffset Zeit definiert wird, da es ansonsten automatisch gelöscht und somit nicht mehr ausgeführt wird
* nach einem ordentlichen Ende des Weckprogramms wird ein at-Device erzeugt, welches das Benutzer-Device automatisch nach "awoken" oder "home" schaltet, abhängig davon ob das Wecken forciert werden soll oder nicht. Dieser Teil wird tatsächlich nur geplant, wenn das Weckprogramm ordentlich beendet wurde. Wurde das Weckprogramm durch ein "set rr_Julian_wakeuptimer1 stop" bzw. durch Klick auf das blaue Device-Icon beendet, so werden die Post-Wakeup Befehle nicht mehr ausgeführt, weil man davon ausgehen kann, dass ein Abbruch des Programms und somit aller seiner weiteren Schaltungen gewünscht ist.

Man kann sein Weckprogramm auf zwei Arten testen:

* durch senden des set-Befehls "trigger": hier werden die aktuellen Auslösedefinitionen berücksichtigt; sprich, wenn heute nicht der richtige Tag ist, wird das Programm nicht gestartet
* durch senden des set-Befehls "start" kann man alle Auslösedefinitionen umgehen und das Weckprogramm direkt auslösen

Zu Debug-Zwecken kann man auf das Wecker Dummy-Device das Attribut "verbose" auf 4 setzen. Im Logfile wird dann sehr ausführlich geloggt, warum wie geschaltet oder nicht geschaltet wird und wie die Entscheidungen getroffen worden sind, Readings zu aktualisieren etc. Damit lässt sich prüfen, ob das gewünschte Auslöseverhalten tatsächlich richtig funktioniert.

== Definition der Aktionen für den Prozess "bettfein machen" ==

Möchte der Bewohner nun ins Bett gehen und sich dabei noch etwas darauf einstimmen, kann er sein "bettfein machen"-Programm dadurch starten, dass er den Status seines ROOMMATE-Devices in FHEM auf "gotosleep" setzt.
In unserem Beispiel werden dann die Aktionen aus Macro_rr_Julian_gotosleep ausgeführt.

Zeitgleich wird im RESIDENTS-Device rgr_Bewohner das Reading "residentsGotosleep" um 1 erhöht und ein Event erzeugt. Befinden sich gar alle anwesenden Bewohner im Status "gotosleep" wechselt der Gesamtstatus von rgr_Bewohner auch auf "gotosleep". Dies löst dann Macro_rgr_Bewohner_gotosleep aus. Dort werden dann Schaltungen vorgenommen, die von größerer Tragweite sind, als wenn nur ein einzelner Bewohner ins Bett geht. Beispielsweise könnte man in bestimmten Räumen das Licht oder Geräte ausschalten, die man ansonsten unberührt gelassen hätte, wenn andere noch wach blieben.

== Definition der Aktionen für den Prozess "schlafen legen" ==

Legt sich der Bewohner ins Bett und möchte schlafen, wechselt er den Status seines ROOMMATE-Devices auf "asleep". Ich mache das bei mir durch einen extra Wandschalter.

In unserem Beispiel werden jetzt die Aktionen aus Macro_rr_Julian_asleep ausgeführt. In dem Macro wird besonders Wert darauf gelegt, dass ausschließlich Aktionen ausgeführt werden, die mit dem Schlafzimmer des Bewohners zu tun haben, damit andere Bewohner in anderen Räumen nicht beeinträchtigt werden.

Zeitgleich werden im RESIDENTS-Device rgr_Bewohner das Reading "residentsGotosleep" um 1 erniedrigt, das Reading "residentsAsleep" um 1 erhöht und ein Event erzeugt. Befinden sich gar alle anwesenden Bewohner im Status "asleep" wechselt der Gesamtstatus von rgr_Bewohner auch auf "asleep". Dies löst dann Macro_rgr_Bewohner_asleep aus. Dort werden dann auch wieder Schaltungen vorgenommen, die von größerer Tragweite sind. Beispielsweise werden alle noch übrigen Lichter im Haus ausgeschaltet und die Musikwiedergabe in Gemeinschaftsräumen (wie hier dem Badezimmer) gestoppt.

== Definition der Aktionen für den Prozess "aufgewacht sein" ==

Wir gehen nun davon aus, dass irgendwann morgens das Weckprogramm wie oben zuvor definiert abgespielt wird. Dabei wechselt im Device rgr_Bewohner das Reading residentsTotalWakeup auf 1 (oder höher bei mehreren gleichzeitig aktiven Weckprogrammen unterschiedlicher Bewohner).

Während des Weckprogramms (oder natürlich auch davor) kann der Bewohner jederzeit in den Status "awoken" wechseln. Ich nutze bei mir auch hier wieder den Wandschalter.
Dadurch wird ein evtl. noch laufendes Weckprogramm unterbrochen (die at-Devices in FHEM werden automatisch aufgräumt) und die Aktionen in Macro_rr_Julian_awoken werden ausgeführt.

Neben dem expliziten Wechsel zum Status "awoken" kann aber, wie oben beschrieben, auch das Weckprogramm selbst den Bewohner auf diesen Status setzen. Dies wird dann als forciertes Wecken bezeichnet; sozusagen um seinen Hintern aus dem Bett zu bewegen :-)
Sinnvollerweise wechselt der Status des Bewohners nach kurzer Zeit dann automatisch von "awoken" auf "home", also den Standard-Status wenn man zuhause ist.

Zeitgleich zum Wechsel des ROOMMATE-Devices auf "awoken" wird auch wieder das RESIDENTS-Device automatisch angepasst: Das Reading "residentsAsleep" wird um 1 erniedrigt, das Reading "residentsAwoken" um 1 erhöht und ein Event erzeugt.
Außerdem wird der Gesamtstatus auf "awoken" gesetzt. Dies löst Macro_rgr_Bewohner_awoken aus. Hier werden auch wieder Schaltungen vorgenommen, die das Haus dann für den ersten, der aufsteht, entsprechend einzustellen, also beispielsweise das Licht in der Küche einschalten.
Zusätzlich wird dann ein temporäres at-Devices angelegt, welches dafür sorgt, dass der Haus Modus nach 1,5h von "Morgen" auf "Tag" wechselt. Allerdings ist der Haus Modus wie schon erwähnt hier nicht das Hauptthema und wird aktuell auch noch nicht direkt vom RESIDENTS Toolkit unterstützt (Sneak-Peek auf zukünftige Erweiterungen ;-)).

== Snooze Funktion bei SONOS ==

Damit man an gewissen Tagen auch dem Wecker mal auf'n Kopp hauen kann (bzw. auf den Start/Stop Button am SONOS Gerät), kann man ein einfaches DOIF erzeugen, welches dafür sorgt, dass man nach 5 Minuten wieder daran erinnert wird aufzustehen:

<pre>
define di_Sonos_Snooze DOIF (
[Sonos_Bedroom:?transportState] and (
([rr_Julian:wakeup] == 0 and [rr_Julian:wakeup:sec] >= 600) or
$we
) or
(
([rr_Julian:wakeup] == 0 and [rr_Julian:wakeup:sec] >= 600) or
$we
)
)

DOELSEIF
(
[Sonos_Bedroom:?transportState] and
([Sonos_Bedroom:transportState] eq "STOPPED" or [Sonos_Bedroom:transportState] eq "PAUSED_PLAYBACK") and
([?rr_Julian:wakeup] == 1 or [rr_Julian:wakeup:sec] < 600) and
!$we
)
(
set Sonos_Bedroom:FILTER=transportState!=PLAYING Play
)

DOELSE

attr alias Automation: Sonos Snoozing
attr cmdState off|on|standby
attr comment snooze function for wake-up program via SONOS device button
attr devStateIcon off:general_aus on:general_an@green standby:general_an@orange
attr wait 0:300:0
</pre>

Das DOIF hier greift nur während ein Weckprogramm läuft oder maximal noch 10 Minuten danach; zudem nur wochentags :-)

Außerdem zeigt der DOIF Status an, ob die Snooze Funktion gerade scharf geschaltet ist oder nicht.

Wichtig ist auch, dass das ROOMMATE Device ein Event bei der Änderung des wakeup Readings auslöst, also z.B. das Attribut event-on-change-reading dann entsprechend auch "wakeup" enthält.

[[Kategorie:Examples]]
[[Kategorie:Code_Snippets]]

Weckautomation

2017-04-09T10:55:10Z

Loredo: /* Wake-up Timer 3 */ wakeupEnforce hinzugefügt

Die Module ROOMMATE und GUEST können dazu genutzt werden, Bewohner und Gäste in FHEM als ein Device zu repräsentieren und durch Events deren Status zu erfassen bzw. zu ändern (beispielsweise durch das GEOFANCY Modul für [[Anwesenheitserkennung]]). Das zur Modulfamilie dazugehörige Modul RESIDENTS fasst die Status mehrerer Bewohner logisch zusammen.

Inzwischen unterstützen die Module auch bei der Erstellung einer Weckautomation, indem sie die Logik kapseln und häufig verwendete Standardfunktionen bereitstellen. Die Verwendung soll in diesem Artikel anhand eines Beispiels näher erläutert werden.

[[Datei:Weckprogramm_Ergebnisdarstellung.png|500px|thumb|right|Darstellung der Beispiel-Konfiguration]]

== Was soll erreicht werden? ==

Hier ein kurzer Überblick über die Funktionen, die wir am Ende realisiert haben werden:

; 3 unterschiedliche Wecker
: 1 für Werktage Mo-Fr
: 1 für werktägliche Samstage
: 1 für Sonn- und Feiertage
; Automatischer Reset der Weckzeiten
: werktäglicher Wecker soll auf einen Standardwert zurückstellen, falls er mal verstellt wurde
: automatischer Reset des werktäglicher Weckers soll zeitweise abschaltbar sein
: nach einem Sonn- oder Feiertagen soll der automatische Reset des werktäglichen Weckers immer wieder eingeschaltet werden
: die Samstags- und Sonntags-Wecker sollen immer nach ihrer Ausführung resettet werden
; jeder Wecker startet ein Weckprogramm 30 Minuten vor der programmierten Zeit
: langsames hochfahren der Rollläden
: Wakeup Light über eine HUE Birne von Warmweiß/2000K zu Kaltweiß/5600K
: an Werktagen: Chillout Weckmusik wird langsam lauter gestellt
: Snooze Funktion über die SONOS Taste am Gerät an Werktagen (erneutes Play nach 5 Minuten)
: forciertes Aufstehen an Werktagen durch automatischen Wechsel des Bewohner Devices zu "awake" und dadurch starten der "aufgewacht sein" Prozesse (siehe unten)
; Starten des Weckprogramms nur bei tatsächlicher Anwesenheit des betroffenen Bewohners
; Ansage der Uhrzeit zur gewählten Weckzeit
; Prozess / Automation für:
: <u>bettfein machen</u>: Lichtszene setzen, Chillout Musik in Schlafzimmer und Badezimmer abspielen
: <u>schlafen legen</u>: Ansage der eingestellten Weckzeit & Ausschalten aller Verbraucher
: <u>aufgewacht sein</u>: Ansage Raumluftqualität, Wettervorhersage; Lokalradio einschalten und in Räume verteilen; Küchenlicht an, HUE in Schlafzimmer mit Aufwach-Farbtemperatur
; Berücksichtigung / Steuerung des Haus Modus
: Wechsel zwischen Morgen-, Tag-, Abend- und Nacht-Modus entsprechend der Schlafgewohnheiten (zusätzlich zur Tageszeit abhängigen Steuerung/Umschaltung, die hier aber nicht Thema sein soll)
; Statuswerte, Events, Readings und Funktionen:
: Wurde ein Wecker ausgelöst?
: Ist gerade ein Weckprogramm aktiv?
: Abbrechen/sofortiges beenden des Weckprogramms
: Verhindern von durch Fehlkonfiguration parallel ausgeführten Weckern für die selbe Person
: Welcher ist der nächste Wecker, der bis Mitternacht des nächsten Tages ausgeführt wird und wann ist das?
: Wann wurde ein Wecker zuletzt ausgeführt und welcher Wecker wurde überhaupt zuletzt ausgeführt?
: Wie viele Bewohner werden gerade geweckt?
: Wie viele Bewohner sind gerade aufgewacht?
: Schaltung bei erstem Bewohner, der geweckt wird
: Schaltung bei erstem Bewohner, der aufgewacht ist
; Statistik
: Wie lange dauerte der Schlaf des Bewohners?
: Wie lange war in dem Haus niemand wach?

Wichtig dabei zu erwähnen ist, dass die Prozesse so umgesetzt worden sind, dass Bewohner sowohl zeitgleich, als auch zeitversetzt oder komplett getrennt ins Bett gehen und aufwachen können.
Dafür werden einige Schaltungen pro Bewohner und dessen Schlafzimmer vorgenommen und andere erst dann, wenn die RESIDENTS Bewohnergruppe einen bestimmten Status erreicht hat.

== Notwendige Devices anlegen ==

=== RESIDENTS und ROOMMATE Devices ===
Wir starten mit einem RESIDENTS Device, um die Bewohner Status später logisch zusammenfassen zu können:

<pre>
define rgr_Bewohner RESIDENTS
</pre>

Anschließend legen wir pro Bewohner ein ROOMMATE Device an. Dafür verwenden wir eine Funktion, die in RESIDENTS eingebaut ist und die Devices korrekt untereinander verbindet (die Reihenfolge, in der RESIDENTS und ROOMMATE/GUEST Geräte definiert werden, sind hier entscheidend). Der Einfachheit halber definieren wir in diesem Beispiel nur einen Bewohner.

<pre>
set rgr_Bewohner addRoommate Julian
</pre>

Es wurde nun automatisch ein Device namens "rr_Julian" angelegt (abgeleitet aus dem angegebenen Vornamen aus dem addRoommate Befehl).
Anschließend setzen wir einmalig den initialen Status für die Bewohner mittels set Befehl:

<pre>
set rr_Julian home
</pre>

Der automatische Wechsel des Status bei Anwesenheit/Abwesenheit wird hier nicht weiter thematisiert, hier sei auf den Artikel [[Anwesenheitserkennung]] verwiesen, insbesondere den GEOFANCY Teil.

=== Wecker Devices anlegen ===

Die Devices, über die die Weckzeit und das Auslöseverhalten eingestellt werden, sind eigentlich normale Dummy Devices. Das zugewiesene ROOMMATE/GUEST/RESIDENTS Device "versklavt" diese Geräte jedoch und führt bestimmte Befehle zur Wecksteuerung und -Verwaltung aus, sobald das Dummy-Device geändert wird. Der Vorteil dabei ist, dass man sich eine Menge eigenen Code und viele unterschiedliche Notify und Dummy Devices spart, was wiederum der Übersichtlichkeit zu Gute kommt.

Wir legen nun unsere drei Wecker für unseren Beispiel Bewohner an. Dafür führen wir einfach 3 mal den selben Befehl hintereinander aus:

<pre>
set rr_Julian create wakeuptimer
set rr_Julian create wakeuptimer
set rr_Julian create wakeuptimer
</pre>

In der Logdatei erscheinen verschiedene Meldungen über alle automatisch angelegte Devices inkl. Name und Typ:

<pre>
2015.03.28 12:19:49 3: RESIDENTStk rr_Julian_wakeuptimer1: new notify macro device Macro_rr_Julian_wakeuptimer1 created
2015.03.28 12:19:50 3: RESIDENTStk rr_Julian_wakeuptimer1: new at-device at_rr_Julian_wakeuptimer1 created
2015.03.28 12:19:50 3: RESIDENTStk rr_Julian_wakeuptimer1: new macro device Macro_rr_Julian_gotosleep created
2015.03.28 12:19:50 3: RESIDENTStk rr_Julian_wakeuptimer1: new watchdog device wd_rr_Julian_gotosleep created
2015.03.28 12:19:50 3: RESIDENTStk rr_Julian_wakeuptimer1: new macro device Macro_rr_Julian_asleep created
2015.03.28 12:19:50 3: RESIDENTStk rr_Julian_wakeuptimer1: new watchdog device wd_rr_Julian_asleep created
2015.03.28 12:19:50 3: RESIDENTStk rr_Julian_wakeuptimer1: new macro device Macro_rr_Julian_awoken created
2015.03.28 12:19:50 3: RESIDENTStk rr_Julian_wakeuptimer1: new watchdog device wd_rr_Julian_awoken created
2015.03.28 12:19:50 3: RESIDENTStk rr_Julian_wakeuptimer1: new macro device Macro_rgr_Bewohner_gotosleep created
2015.03.28 12:19:50 3: RESIDENTStk rr_Julian_wakeuptimer1: new watchdog device wd_rgr_Bewohner_gotosleep created
2015.03.28 12:19:50 3: RESIDENTStk rr_Julian_wakeuptimer1: new macro device Macro_rgr_Bewohner_asleep created
2015.03.28 12:19:50 3: RESIDENTStk rr_Julian_wakeuptimer1: new watchdog device wd_rr_Julian_asleep created
2015.03.28 12:19:50 3: RESIDENTStk rr_Julian_wakeuptimer1: new macro device Macro_rgr_Bewohner_awoken created
2015.03.28 12:19:51 3: RESIDENTStk rr_Julian_wakeuptimer1: new watchdog device wd_rr_Julian_awoken created
2015.03.28 12:21:49 3: RESIDENTStk rr_Julian_wakeuptimer2: new notify macro device Macro_rr_Julian_wakeuptimer2 created
2015.03.28 12:21:49 3: RESIDENTStk rr_Julian_wakeuptimer2: new at-device at_rr_Julian_wakeuptimer2 created
2015.03.28 12:21:56 3: RESIDENTStk rr_Julian_wakeuptimer3: new notify macro device Macro_rr_Julian_wakeuptimer3 created
2015.03.28 12:21:56 3: RESIDENTStk rr_Julian_wakeuptimer3: new at-device at_rr_Julian_wakeuptimer3 created
</pre>

Als Rückgabe in FHEMWEB erhält man eine Meldung wie diese hier:

<pre>
Dummy rr_Julian_wakeuptimer1 and other pending devices created and pre-configured.
You may edit Macro_rr_Julian_wakeuptimer1 to define your wake-up actions
and at_rr_Julian_wakeuptimer1 for optional at-device adjustments.
</pre>

Wie man sieht wurden anfänglich eine ganze Menge von Notify-Macros und Watchdogs sowie ein at-Device pro Wecker angelegt.
Dabei sind vor allem die Macro-Devices und die Wecker Dummy Devices interessant. Hier werden Weck- und Auslöseverhalten konfiguriert. die at- und Watchdog-Devices können aber für fortgeschrittene Nutzer beliebig angepasst werden. Auch die Dummy Devices können bis auf wenige Ausnahmen (Attribut "userattr") vollständig umkonfiguriert werden. Wer Devices umbenennt, sollte unbedingt darauf achten, dass auch das entsprechende Attribut im Wecker-Dummy-Device angepasst wird.

Allen Devices ist ein entsprechender Kommentar hinzugefügt, der dessen Funktion kurz erklärt.
Alle Macros enthalten bereits ein Gerüst für den Weckprozess mit einigen Beispielen. Die Beispielschaltungen sind dabei noch auskommentiert. Nicht auskommentierter Code sollte als notwendiger Teil für die Weckautomation betrachtet werden und wird dort auch durch einen entsprechenden Kommentar erklärt.

Im Folgenden werden wir jetzt Schritt für Schritt das oben beschriebene Szenario konfigurieren.

== Konfiguration des Auslöseverhaltens ==

In der Grundkonfiguration löst jeder Wecker sein eigenes Weckprogramm täglich zur voreingestellten Zeit aus. Dabei wird allerdings kein längeres Programm gestartet, sondern lediglich einmalig das im Attribut wakeupMacro hinterlegte Notify-Macro getriggert. Das ist in der Beispiel-Grundkonfiguration kein Problem und lässt lediglich einen Logfile Eintrag erstellen.

Als erstes möchten wir, dass alle 3 Timer das selbe Macro zum Wecken verwenden, damit wir den Code nur einmal pflegen müssen. Die anderen beiden Macros löschen wir anschließend:

<pre>
attr rr_Julian_wakeuptimer2 wakeupMacro Macro_rr_Julian_wakeuptimer1
attr rr_Julian_wakeuptimer3 wakeupMacro Macro_rr_Julian_wakeuptimer1
delete Macro_rr_Julian_wakeuptimer2
delete Macro_rr_Julian_wakeuptimer3
</pre>

Nun konfigurieren wir die Auslöseverhalten so, wie wir es oben vorgegeben haben:

=== Wake-up Timer 1 ===

Wecker nur Mo-Fr auslösen:
<pre>
attr rr_Julian_wakeuptimer1 wakeupDays 1,2,3,4,5
</pre>

Wecker zusätzlich auf Tage beschränken, die keine Feiertage sind:
<pre>
attr rr_Julian_wakeuptimer1 wakeupHolidays andNoHoliday
</pre>
<i><u>Hinweis:</u> Hierfür muss ein [http://fhem.de/commandref.html#holiday holiday-Device] erstellt sein und in der global Config im Attribut 'holidays2we‘ verlinkt sein. Ansonsten erhält man beim setzen einer Weckzeit später entsprechende Fehlermeldungen, die darauf hinweisen.</i>

Länge des Weckprogramms auf 30 Minuten festlegen (sprich 30 Minuten vor der eingestellten Weckzeit beginnen):
<pre>
attr rr_Julian_wakeuptimer1 wakeupOffset 30
</pre>

Aufstehen forcieren:
<pre>
attr rr_Julian_wakeuptimer1 wakeupEnforced 1
</pre>

Standard Weckzeit hinterlegen:
<pre>
attr rr_Julian_wakeuptimer1 wakeupDefaultTime 07:30
</pre>

Weckzeit nur an diesen Tagen automatisch zurückstellen:
<pre>
attr rr_Julian_wakeuptimer1 wakeupResetdays 1,2,3,4,5
</pre>
<i><u>Hinweis:</u> Ein Reset findet normalerweise nach jeder Auslösung statt, sprich wenn das Weckprogramm tatsächlich gestartet wurde. Dies kann man auf bestimmte Tage einschränken.</i>

Zum einfacheren Aktivieren/Deaktivieren des Resets wollen wir ein weiteres Dummy nutzen:
<pre>
attr rr_Julian_wakeuptimer1 wakeupResetSwitcher rr_Julian_wakeuptimer1_resetswitcher
</pre>
<i><u>Hinweis:</u> Der Dummy-Gerätename kann frei gewählt werden. Sofern es nicht existiert wird es automatisch angelegt und vorkonfiguriert.</i>

=== Wake-up Timer 2 ===

Wecker nur Samstags auslösen:
<pre>
attr rr_Julian_wakeuptimer2 wakeupDays 6
</pre>

Wecker zusätzlich auf Tage beschränken, die keine Feiertage sind:
<pre>
attr rr_Julian_wakeuptimer2 wakeupHolidays andNoHoliday
</pre>

Länge des Weckprogramms auf 30 Minuten festlegen (sprich 30 Minuten vor der eingestellten Weckzeit beginnen):
<pre>
attr rr_Julian_wakeuptimer2 wakeupOffset 30
</pre>

Aufstehen forcieren:
<pre>
attr rr_Julian_wakeuptimer2 wakeupEnforce 1
</pre>

Standard Weckzeit hinterlegen:
<pre>
attr rr_Julian_wakeuptimer2 wakeupDefaultTime 09:30
</pre>

Weckzeit nur an diesen Tagen automatisch zurückstellen:
<pre>
attr rr_Julian_wakeuptimer2 wakeupResetdays 6
</pre>

=== Wake-up Timer 3 ===

Wecker nur Sonntags auslösen:
<pre>
attr rr_Julian_wakeuptimer3 wakeupDays 0
</pre>

Wecker zusätzlich auch an Feiertagen ausführen:
<pre>
attr rr_Julian_wakeuptimer3 wakeupHolidays orHoliday
</pre>

Aufstehen nur forcieren, wenn eine frühere Weckzeit als die Standard Weckzeit eingestellt wurde:
<pre>
attr rr_Julian_wakeuptimer2 wakeupEnforce 3
</pre>

Länge des Weckprogramms auf 30 Minuten festlegen (sprich 30 Minuten vor der eingestellten Weckzeit beginnen):
<pre>
attr rr_Julian_wakeuptimer3 wakeupOffset 30
</pre>

Standard Weckzeit hinterlegen:
<pre>
attr rr_Julian_wakeuptimer3 wakeupDefaultTime 10:30
</pre>

== Definition des Weckprogramms ==

Die Aktionen, welche innerhalb der 30 Minuten Weckzeitraum abgearbeitet werden sollen, sind im Device Macro_rr_Julian_wakeuptimer1 hinterlegt.
Dieses Macro wird 2 Mal aufgerufen: Das erste Mal beim Beginn des Weckprogramms und ein zweites Mal beim Ende des Weckprogramms. Der Hintergrund ist, dass das Macro beim Beenden dann entsprechend dafür sorgen kann bisher nicht ausgeführte Befehle des Programmablaufes zu stornieren. Hierfür ist die for-Schleife am Anfang des Macros gedacht und deckt per Default 10 Arbeitsschritte ab (ansonsten einfach die Zahl entsprechend erhöhen).

Das Macro Template hat bereits alle oben beschriebenen Funktionen als auskommentierte FHEM Befehle enthalten. Diese sollen natürlich nur dem Beispiel und der eigenen Inspiration dienen. Wir müssten diese an dieser Stelle lediglich einkommentieren...
Insgesamt fällt bei genauerem hinsehen folgendes auf:

* es stehen bestimmte Umgebungsvariablen bereit, die während des Programmablaufes genutzt werden können
* das Macro ist in 3 Bereiche unterteilt und nutzt dafür die Umgebungsvariable $EVTPART0 bzw. ob deren Wert auf "start" oder "stop" steht
* der erste Bereich mit der for-Schleife wird immer ausgeführt. Sie räumt durch das Macro erzeugte temporäre at-Devices auf (entweder weil das Programm früher beendet werden soll oder von vorne beginnen soll)
* der zweite Bereich "start" führt erste FHEM Befehle direkt nach dem Beginn des Weckprogramms aus. Außerdem werden weitere Befehle in bestimmten Etappen zur zeitversetzten Ausführung vorgemerkt. Dafür werden temporär erzeugte at-Devices verwendet.
* der Name der at-Devices folgt einem bestimmten Schema, nämlich atTmp_<LAUFENDE-NUMMER>_$NAME. Die laufende Nummer muss man manuell hochzählen, der Rest kann einfach kopiert werden. Dadurch wird das aufräumen oben im Macro einfacher.
* bei der Definition der at-Devices müssen mehrere FHEM Befehle hintereinander mit 2 Semikolon statt einem getrennt werden (siehe auch [http://fhem.de/commandref_DE.html#command Kommando-Referenz]).
* bei bedingten Schaltungen empfehlt es sich für übersichtlicheren Code die :FILTER Funktion zu nutzen (siehe auch [http://fhem.de/commandref_DE.html#devspec Kommando-Referenz]).
* es ist unbedingt darauf zu achten, dass das letzte at-Device nicht nach der wakeupOffset Zeit definiert wird, da es ansonsten automatisch gelöscht und somit nicht mehr ausgeführt wird
* nach einem ordentlichen Ende des Weckprogramms wird ein at-Device erzeugt, welches das Benutzer-Device automatisch nach "awoken" oder "home" schaltet, abhängig davon ob das Wecken forciert werden soll oder nicht. Dieser Teil wird tatsächlich nur geplant, wenn das Weckprogramm ordentlich beendet wurde. Wurde das Weckprogramm durch ein "set rr_Julian_wakeuptimer1 stop" bzw. durch Klick auf das blaue Device-Icon beendet, so werden die Post-Wakeup Befehle nicht mehr ausgeführt, weil man davon ausgehen kann, dass ein Abbruch des Programms und somit aller seiner weiteren Schaltungen gewünscht ist.

Man kann sein Weckprogramm auf zwei Arten testen:

* durch senden des set-Befehls "trigger": hier werden die aktuellen Auslösedefinitionen berücksichtigt; sprich, wenn heute nicht der richtige Tag ist, wird das Programm nicht gestartet
* durch senden des set-Befehls "start" kann man alle Auslösedefinitionen umgehen und das Weckprogramm direkt auslösen

Zu Debug-Zwecken kann man auf das Wecker Dummy-Device das Attribut "verbose" auf 4 setzen. Im Logfile wird dann sehr ausführlich geloggt, warum wie geschaltet oder nicht geschaltet wird und wie die Entscheidungen getroffen worden sind, Readings zu aktualisieren etc. Damit lässt sich prüfen, ob das gewünschte Auslöseverhalten tatsächlich richtig funktioniert.

== Definition der Aktionen für den Prozess "bettfein machen" ==

Möchte der Bewohner nun ins Bett gehen und sich dabei noch etwas darauf einstimmen, kann er sein "bettfein machen"-Programm dadurch starten, dass er den Status seines ROOMMATE-Devices in FHEM auf "gotosleep" setzt.
In unserem Beispiel werden dann die Aktionen aus Macro_rr_Julian_gotosleep ausgeführt.

Zeitgleich wird im RESIDENTS-Device rgr_Bewohner das Reading "residentsGotosleep" um 1 erhöht und ein Event erzeugt. Befinden sich gar alle anwesenden Bewohner im Status "gotosleep" wechselt der Gesamtstatus von rgr_Bewohner auch auf "gotosleep". Dies löst dann Macro_rgr_Bewohner_gotosleep aus. Dort werden dann Schaltungen vorgenommen, die von größerer Tragweite sind, als wenn nur ein einzelner Bewohner ins Bett geht. Beispielsweise könnte man in bestimmten Räumen das Licht oder Geräte ausschalten, die man ansonsten unberührt gelassen hätte, wenn andere noch wach blieben.

== Definition der Aktionen für den Prozess "schlafen legen" ==

Legt sich der Bewohner ins Bett und möchte schlafen, wechselt er den Status seines ROOMMATE-Devices auf "asleep". Ich mache das bei mir durch einen extra Wandschalter.

In unserem Beispiel werden jetzt die Aktionen aus Macro_rr_Julian_asleep ausgeführt. In dem Macro wird besonders Wert darauf gelegt, dass ausschließlich Aktionen ausgeführt werden, die mit dem Schlafzimmer des Bewohners zu tun haben, damit andere Bewohner in anderen Räumen nicht beeinträchtigt werden.

Zeitgleich werden im RESIDENTS-Device rgr_Bewohner das Reading "residentsGotosleep" um 1 erniedrigt, das Reading "residentsAsleep" um 1 erhöht und ein Event erzeugt. Befinden sich gar alle anwesenden Bewohner im Status "asleep" wechselt der Gesamtstatus von rgr_Bewohner auch auf "asleep". Dies löst dann Macro_rgr_Bewohner_asleep aus. Dort werden dann auch wieder Schaltungen vorgenommen, die von größerer Tragweite sind. Beispielsweise werden alle noch übrigen Lichter im Haus ausgeschaltet und die Musikwiedergabe in Gemeinschaftsräumen (wie hier dem Badezimmer) gestoppt.

== Definition der Aktionen für den Prozess "aufgewacht sein" ==

Wir gehen nun davon aus, dass irgendwann morgens das Weckprogramm wie oben zuvor definiert abgespielt wird. Dabei wechselt im Device rgr_Bewohner das Reading residentsTotalWakeup auf 1 (oder höher bei mehreren gleichzeitig aktiven Weckprogrammen unterschiedlicher Bewohner).

Während des Weckprogramms (oder natürlich auch davor) kann der Bewohner jederzeit in den Status "awoken" wechseln. Ich nutze bei mir auch hier wieder den Wandschalter.
Dadurch wird ein evtl. noch laufendes Weckprogramm unterbrochen (die at-Devices in FHEM werden automatisch aufgräumt) und die Aktionen in Macro_rr_Julian_awoken werden ausgeführt.

Neben dem expliziten Wechsel zum Status "awoken" kann aber, wie oben beschrieben, auch das Weckprogramm selbst den Bewohner auf diesen Status setzen. Dies wird dann als forciertes Wecken bezeichnet; sozusagen um seinen Hintern aus dem Bett zu bewegen :-)
Sinnvollerweise wechselt der Status des Bewohners nach kurzer Zeit dann automatisch von "awoken" auf "home", also den Standard-Status wenn man zuhause ist.

Zeitgleich zum Wechsel des ROOMMATE-Devices auf "awoken" wird auch wieder das RESIDENTS-Device automatisch angepasst: Das Reading "residentsAsleep" wird um 1 erniedrigt, das Reading "residentsAwoken" um 1 erhöht und ein Event erzeugt.
Außerdem wird der Gesamtstatus auf "awoken" gesetzt. Dies löst Macro_rgr_Bewohner_awoken aus. Hier werden auch wieder Schaltungen vorgenommen, die das Haus dann für den ersten, der aufsteht, entsprechend einzustellen, also beispielsweise das Licht in der Küche einschalten.
Zusätzlich wird dann ein temporäres at-Devices angelegt, welches dafür sorgt, dass der Haus Modus nach 1,5h von "Morgen" auf "Tag" wechselt. Allerdings ist der Haus Modus wie schon erwähnt hier nicht das Hauptthema und wird aktuell auch noch nicht direkt vom RESIDENTS Toolkit unterstützt (Sneak-Peek auf zukünftige Erweiterungen ;-)).

== Snooze Funktion bei SONOS ==

Damit man an gewissen Tagen auch dem Wecker mal auf'n Kopp hauen kann (bzw. auf den Start/Stop Button am SONOS Gerät), kann man ein einfaches DOIF erzeugen, welches dafür sorgt, dass man nach 5 Minuten wieder daran erinnert wird aufzustehen:

<pre>
define di_Sonos_Snooze DOIF (
[Sonos_Bedroom:?transportState] and (
([rr_Julian:wakeup] == 0 and [rr_Julian:wakeup:sec] >= 600) or
$we
) or
(
([rr_Julian:wakeup] == 0 and [rr_Julian:wakeup:sec] >= 600) or
$we
)
)

DOELSEIF
(
[Sonos_Bedroom:?transportState] and
([Sonos_Bedroom:transportState] eq "STOPPED" or [Sonos_Bedroom:transportState] eq "PAUSED_PLAYBACK") and
([?rr_Julian:wakeup] == 1 or [rr_Julian:wakeup:sec] < 600) and
!$we
)
(
set Sonos_Bedroom:FILTER=transportState!=PLAYING Play
)

DOELSE

attr alias Automation: Sonos Snoozing
attr cmdState off|on|standby
attr comment snooze function for wake-up program via SONOS device button
attr devStateIcon off:general_aus on:general_an@green standby:general_an@orange
attr wait 0:300:0
</pre>

Das DOIF hier greift nur während ein Weckprogramm läuft oder maximal noch 10 Minuten danach; zudem nur wochentags :-)

Außerdem zeigt der DOIF Status an, ob die Snooze Funktion gerade scharf geschaltet ist oder nicht.

Wichtig ist auch, dass das ROOMMATE Device ein Event bei der Änderung des wakeup Readings auslöst, also z.B. das Attribut event-on-change-reading dann entsprechend auch "wakeup" enthält.

[[Kategorie:Examples]]
[[Kategorie:Code_Snippets]]

HttpUtils

2017-02-20T19:23:40Z

Loredo: /* HttpUtils_BlockingGet */ $param->{digest}</code>

{{Infobox Modul
|ModPurpose=Hilfsfunktionen für HTTP-Zugriffe
|ModType=h
|ModForumArea=Automatisierung
|ModTechName=HttpUtils.pm
|ModOwner=rudolfkoenig ({{Link2FU|8|Forum}} / [[Benutzer Diskussion:Rudolfkoenig|Wiki]])
}}

Das Modul [[HttpUtils]](.pm) ist sowohl für Modulentwickler als auch für Endanwender gedacht, um Daten via HTTP auszutauschen. Es stellt dabei eine Reihe von Funktionen zur Verfügung und wird beispielsweise vom Modul [[HTTPMOD]] intensiv genutzt.

== Funktionen ==
Es ist zu beachten, dass bei den Funktionen
* <code>GetHttpFile()</code>
* <code>GetFileFromURL</code>
* <code>GetFileFromURLQuiet</code>
* <code>HttpUtils_BlockingGet</code>
ein sogenannter "blockierender" Aufruf durchgeführt wird. Das bedeutet, dass FHEM bei einem Aufruf einer dieser Funktionen solange wartet und dabei absolut nichts macht, bis die Antwort vom HTTP-Server eintrifft und die Funktion damit beendet ist. Das kann bei Verbindungsproblemen evtl. dazu führen, dass FHEM für die gesamte Wartezeit (Timeout) steht und nichts verarbeitet. Problematisch ist das gerade bei Anwendungen oder Hardware, die eine zeitnahe Reaktion von FHEM erwarten (z.B. HomeMatic-Geräte). In der Zeit, in der auf eine HTTP Antwort gewartet wird, steht FHEM dabei komplett.

Es wird daher empfohlen, die Funktionen so sparsam wie möglich zu verwenden und die Timeouts so niedrig wie möglich zu halten, um ein längeres Einfrieren von FHEM möglichst zu vermeiden.

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

=== GetHttpFile ===
Die Funktion GetHttpFile ist die denkbar einfachste Variante um eine URL aufzurufen.
:<code>GetHttpFile($server, $file)</code>
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$server</code>'''

''mandatory''
|| Der DNS-Name oder die IP-Adresse des HTTP-Servers<br>
Beispiel:

* ''<nowiki>www.myhost.com</nowiki>''
* ''<nowiki>192.168.0.10</nowiki>''
|-
| style="vertical-align:top" | '''<code>$file</code>'''

''mandatory''
|| Die Datei, welche auf dem HTTP-Server aufgerufen werden soll.<br>
Beispiel:
* ''/''
* ''/index.html''
* ''/directory/image.jpg''
|}

Funktionsergebnis ist der Inhalt der aufgerufenen Seite in Form einer Zeichenkette.

=== GetFileFromURL ===
Die Funktion GetFileFromURL ruft die HTTP-URL auf und gibt als Funktionsergebnis den Seiteninhalt zurück. Im Gegensatz zu GetHttpFile beinhaltet GetFileFromURL einige Zusatzoptionen in Form von Funktionsparametern.

'''Aufruf: <code>GetFileFromURL($url, ''[$timeout], [$data], [$noshutdown], [$loglevel]'')</code>'''

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

''mandatory''
|| Die HTTP-URL, welche aufgerufen werden soll. Diese kann optional Usernamen, Passwort und einen Port enthalten. Sowohl HTTP als auch HTTPS wird hierbei unterstützt.<br>
Beispiel:

* ''<nowiki>http://www.myhost.com/directory/</nowiki>''
* ''<nowiki>https://www.myhost.com/</nowiki>''
* ''<nowiki>http://www.myhost.com:8080/</nowiki>''
* ''<nowiki>http://foo:bar@www.myhost.com/</nowiki>''
|-
| style="vertical-align:top" | '''<code>$timeout</code>'''

''optional''
|| Die maximale Dauer in Sekunden für die HTTP-Anfrage

Beispiel: 5 ''(Sekunden)''

Standardwert: 4 Sekunden
|-
| style="vertical-align:top" | '''<code>$data</code>'''

''optional''
|| Wenn man Daten via HTTP-POST übertragen möchte, so kann man die Nutzdaten über $data übergeben. Die Daten werden dabei als Formulardaten übertragen. Wenn man den Content-Type beeinflussen oder mehrere Formular-Felder senden möchte, sollte man zur Funktion HttpUtils_BlockingGet oder HttpUtils_NonblockingGet greifen.

Standardwert: ''[leer]''

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

''optional''
|| Wenn $noshutdown auf 1 gesetzt ist, wird dem HTTP-Server nicht implizit mitgeteilt, dass die Verbindung nach dem Request geschlossen werden soll. Viele Webserver schließen in solch einem Fall die Verbindung, bevor sie die Antwort senden. Bei 0 wird dem Webserver mitgeteilt, dass der Sendevorgang beendet ist und nun die Antwort abgewartet wird.

Standardwert: 1
|-
| style="vertical-align:top" | '''<code>$loglevel</code>'''

''optional''
|| Das [[verbose|Loglevel]], in dem sämtliche Logmeldungen zu dieser HTTP-Abfrage erzeugt werden sollen.

Standardwert: 4
|}

Funktionsergebnis ist der Inhalt der aufgerufenen Seite in Form eines Strings.

=== GetFileFromURLQuiet ===
Diese Funktion funktioniert ähnlich wie GetFileFromURL. Allerdings wird die tatsächliche URL in allen erzeugten Log-Meldungen unkenntlich gemacht um z.B. Zugangsdaten nicht preiszugeben. Die aufgerufene Seite wird ebenfalls als Funktionsergebnis zurückgegeben.

'''Aufruf: <code>GetFileFromURLQuiet($url, ''[$timeout], [$data], [$noshutdown], [$loglevel]'')</code>'''

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

''mandatory''
|| Die HTTP-URL, welche aufgerufen werden soll. Diese kann optional Usernamen, Passwort und einen Port enthalten. Sowohl HTTP als auch HTTPS wird hierbei unterstützt.<br>
Beispiel:

* ''<nowiki>http://www.myhost.com/directory/</nowiki>''
* ''<nowiki>https://www.myhost.com/</nowiki>''
* ''<nowiki>http://www.myhost.com:8080/</nowiki>''
* ''<nowiki>http://foo:bar@www.myhost.com/</nowiki>''
|-
| style="vertical-align:top" | '''<code>$timeout</code>'''

''optional''
|| Die maximale Dauer in Sekunden für die HTTP-Anfrage

Beispiel: 5 ''(Sekunden)''

Standardwert: 4 Sekunden
|-
| style="vertical-align:top" | '''<code>$data</code>'''

''optional''
|| Wenn man Daten via HTTP-POST übertragen möchte, so kann man die Nutzdaten über <code>$data</code> übergeben. Die Daten werden dabei als Formulardaten übertragen. Wenn man den Content-Type beeinflussen möchte, oder mehrere Formular-Felder senden möchte, sollte man zur Funktion HttpUtils_BlockingGet oder HttpUtils_NonblockingGet greifen.

Standardwert: ''[leer]''

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

''optional''
|| Wenn $noshutdown auf 1 gesetzt ist, wird dem HTTP-Server nicht implizit mitgeteilt, dass die Verbindung nach dem Request geschlossen werden soll. Viele Webserver schließen in solch einem Fall die Verbindung bevor, sie die Antwort senden. Bei 0 wird dem Webserver mitgeteilt, dass der Sendevorgang beendet ist und nun die Antwort abgewartet wird.

Standardwert: 1
|-
| style="vertical-align:top" | '''<code>$loglevel</code>'''

''optional''
|| Das Loglevel, in dem sämtliche Logmeldungen zu dieser HTTP-Abfrage erzeugt werden sollen.

Standardwert: 4
|}

Funktionsergebnis ist der Inhalt der aufgerufenen Seite in Form eines Strings.

=== HttpUtils_BlockingGet ===
Wenn die bisher genannten Funktionen nicht ausreichen um die gewünschte Abfrage durchzuführen, so kann man diese Funktion verwenden. Aufgrund zahlreicher Parameter ermöglicht sie viele Anpassungsmöglichkeiten. Diese Funktion hat dabei nicht wie üblich eine Liste an Funktionsparametern, sondern lediglich einen Parameter, welcher eine Hashreferenz mit allen Funktionsparametern darstellt. Dieser Hash enthält sämtliche Parameter inkl. Werten.

'''Aufruf: <code>HttpUtils_BlockingGet($param)</code>'''

Der Parameter $param ist eine Referenz auf eine Hash-Struktur, welche die einzelnen Parameter enthält. Der Hash $param kann folgende Optionen beinhalten:

{| class="wikitable"
|-
! style="width:175px" | Parameter !! style="width:auto" | Bedeutung
|-
| style="vertical-align:top" | '''<code>$param->{url}</code>'''

''mandatory''
|| Die HTTP-URL, welche aufgerufen werden soll. Diese kann optional Usernamen, Passwort und einen Port enthalten. Sowohl HTTP als auch HTTPS wird hierbei unterstützt.<br>
Beispiel:

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

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

''optional''
|| Die maximale Dauer in Sekunden für die HTTP-Anfrage

Beispiel: 5 ''(Sekunden)''

Standardwert: 4 Sekunden
|-
| style="vertical-align:top" |'''<code>$param->{data}</code>'''

''optional''
|| Wenn man Daten via HTTP-POST übertragen möchte, so kann man die Nutzdaten über <code>$param->{data}</code> übergeben. Die Daten werden dabei als Formulardaten übertragen. Die Daten können dabei auf zwei Arten übergeben werden:

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

Standardwert: ''[leer]''

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

''optional''
||Wenn <code>$param->{noshutdown}</code> auf 1 gesetzt ist, wird dem HTTP-Server nicht implizit mitgeteilt, dass die Verbindung nach dem Request geschlossen werden soll. Viele Webserver schließen in solch einem Fall die Verbindung, bevor sie die Antwort senden. Bei 0 wird dem Webserver mitgeteilt, dass der Sendevorgang beendet ist und nun die Antwort abgewartet wird.

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

''optional''
|| Das Loglevel, in dem sämtliche Logmeldungen zu dieser HTTP-Abfrage erzeugt werden sollen.

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

''optional''
|| Wenn dieser Parameter den Wert 1 trägt, wird die URL in sämtlichen Log-Ausgaben unkenntlich gemacht. Dies ist nützlich um z.B. Zugangsdaten geheim zu halten.

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

''optional''
|| Wenn dieser Parameter den Wert 1 trägt, werden Umleitungen durch den Server ignoriert und der Request beendet. Dies kann erforderlich sein um evtl. Cookies aus der Antwort, welche eine Umleitung enthält aus dem HTTP Header zu extrahieren um diese im nächsten Request weiterzuverwenden.

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

''optional''
||Die HTTP-Methode, welche zur Abfrage verwendet werden soll. Sofern keine Daten übertragen werden ist dies standardmäßig "GET", ansonsten "POST". Es können aber auch andere Methoden verwendet werden.

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

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

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

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

''optional''
|| Eigene HTTP-Header-Zeilen können über diesen Parameter eingebracht werden. Er kann dazu genutzt werden um z.B. den Content-Type festzulegen, oder einfach nur zusätzliche Header-Felder zu setzen. Es gibt zwei Möglichkeiten, diesen Parameter zu befüllen.

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

Beispiel:
* <code>"User-Agent: Mozilla/1.22'''<u>\r\n</u>'''Content-Type: application/xml"</code>
* <code>"Content-Type: application/xml"</code>
* <code>{ "User-Agent" => "Mozilla/1.22", "Content-Type" => "application/xml" }</code>
* <code>{ "Content-Type" => "application/xml" }</code>

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

''optional''
|| Eigene SSL-Optionen können über diesen Parameter eingebracht werden. Er kann dazu genutzt werden um z.B. die SSL-Zertifikats Verifikation abzuschalten. Die SSL-Optionen müssen als eigene Hash-Referenz übergeben werden. Eine Liste aller möglichen Optionen findet man in der Perl-Dokumentation zu [http://search.cpan.org/~sullr/IO-Socket-SSL-2.016/lib/IO/Socket/SSL.pod#Description_Of_Methods IO::Socket::SSL].

Beispiel:
* <code>$param->{sslargs} = { SSL_verify_mode => 0, sslOpt2 => 'sslVal2' }</code>

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

''optional''
|| Die HTTP-Version, welche zur Abfrage verwendet werden soll. Standardmäßig werden alle Abfragen mit HTTP/1.0 durchgeführt. Falls es jedoch notwendig ist HTTP/1.1 zu verwenden, so sollte <code>$param->{httpversion}</code> auf "1.1" gesetzt werden. Bei Version 1.1 wird automatisch der Header "<code>Connection: close</code>" implizit mitgesendet.

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

''optional''
|| Verhindert, dass Benutzerdaten zunächst als Basic-Auth gesendet werden. Anmeldedaten werden dann nur an den Server geschickt, wenn dieser explizit nach HTTP Digest gefragt hat.

Standardwert: "0"
|}

Als Rückgabewert von HttpUtils_BlockingGet wird ein Array mit zwei Rückgabewerten zurückgegeben:
:<code>($err, $data) = HttpUtils_BlockingGet( … )</code>
Diese zwei Rückgabewerte haben folgende Bedeutung:

{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$err</code>'''|| Falls beim Aufruf der URL ein Fehler aufgetreten ist (z.B. Server nicht erreichbar oder Verbindungstimeout), dann ist dieser Wert mit einer Fehlermeldung gefüllt.

Wenn kein Fehler aufgetreten ist, ist dieser Wert mit einem Leerstring gefüllt (<code>$err = ""</code>)
|-
| style="vertical-align:top" | '''<code>$data</code>'''|| Die Ergebnisdaten, welche der HTTP-Server zurückgeliefert hat. Die Daten werden als Klartext in Form eines gesamten Strings zurückgegeben.

Falls ein Fehler aufgetreten ist, ist dieser Wert mit einem Leersting gefüllt (<code>$data = ""</code>)
|}

=== HttpUtils_NonblockingGet ===
{{Randnotiz|RNText=Die Funktion HttpUtils_NonblockingGet ist nicht komplett durchgehend "non-blocking". DNS-Abfragen sind weiterhin blockierend. Insbesondere wenn der DNS-Name nicht aufgelöst werden kann.}}
Diese Funktion arbeitet ähnlich wie HttpUtils_BlockingGet. Allerdings wird das Ergebnis nicht als Funktionsergebnis zurückgegeben. Die Funktion HttpUtils_NonblockingGet initiiert den Verbindungsaufbau und übergibt alles weitere an FHEM interne Routinen. Sobald eine Antwort vom HTTP-Server eintrifft, wird eine Callback-Funktion mit verschiedenen Parametern (unter anderem auch das Ergebnis) aufgerufen, um die Antwort entgegenzunehmen und weiter zu verarbeiten.

Der Aufruf ist daher ähnlich zu HttpUtils_BlockingGet mit nur einem Parameter-Hash:

'''Aufruf: <code>HttpUtils_NonblockingGet($param)</code>'''

{| class="wikitable"
|-
! style="width:175px" | Parameter !! style="width:auto" | Bedeutung
|-
| colspan="2" style="text-align:center" | '''''<br>Alle Hash-Parameter, welche für HttpUtils_BlockingGet gelten, sind auch für HttpUtils_NonblockingGet gültig'''''<br>
|-
| style="vertical-align:top" | '''<code>$param->{callback}</code>'''

''mandatory''
|| Eine Funktion (oder eine Referenz auf eine Funktion), welche die Ergebnisdaten entgegennimmt und die Antwort entsprechend weiterverarbeitet. Die Callback-Funktion muss dabei 3 Parameter erwarten. Die Funktionsparameter der Callback-Funktion werden im nachfolgenden Abschnitt näher erläutert.

Beispiel:
* <code>$param->{callback} = \&MyCallbackFn</code> — ''(Referenzzeiger auf Funktionsname)''
* <code>$param->{callback} = sub($$$){ … }</code> — ''(direkte Funktionsdefinition)''
|-
| style="vertical-align:top" | ''Benutzerdefinierte Parameter''
|| Es können im Hash weitere benutzerdefinierte Parameter gesetzt werden, welche evtl. in der Callback-Funktion benötigt werden, um die Antwort korrekt zu verarbeiten.

Zum Beispiel bei der Modul-Programmierung währe das $hash des aktuellen Devices. Alle gesetzten Parameter sind in der Callback-Funktion direkt abrufbar und können ausgewertet werden.

Beispiel:
* <code>$param->{hash} = $hash</code>
* <code>$param->{command} = "on"</code>

|}

Ein Funktionsrückgabewert von HttpUtils_NonblockingGet existiert nicht, da die eigentliche Rückgabe der Daten über die Callback-Funktion erfolgt. Die Callback-Funktion wird aufgerufen, sobdald der HTTP-Request abgeschlossen ist, oder ein Fehler aufgetreten ist. Der Funktionsaufruf erfolgt mit den folgenden Parametern:

<code> ''MyCallbackFn'' ( $param, $err, $data )</code>

Diese 3 Parameter haben dabei folgende Bedeutung:

{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$param</code>''' || Der Parameter-Hash, mit allen Argumenten die beim Aufruf der Funktion übergeben worden sind.

Es ist möglich, dass der Parameter-Hash nach erfolgter Abfrage zusätzliche oder veränderte Elemente enthält:
* '''<code>$param->{redirects}</code>''' - Die Anzahl an Umleitungen die erfolgte, bis die Anfrage beantwortet wurde.
* '''<code>$param->{url}</code>''' - Die URL, die nach erfolgter Umleitung die Anfrage beantwortet hat.
* '''<code>$param->{protocol}</code>''' - Das verwendete Protokoll, welches zur Abfrage verwendet wurde ("http" oder "https").
* '''<code>$param->{path}</code>''' - Der Pfad, welcher auf dem HTTP-Server angefragt wurde.
* '''<code>$param->{host}</code>''' - Der Name oder die IP-Adresse des HTTP-Servers.
* '''<code>$param->{httpheader}</code>''' - Der gesamte HTTP Header, welcher der Server bei der letzten Antwort zurücklieferte.
* '''<code>$param->{code}</code>''' - Der HTTP-Statuscode, mit dem die Anfrage vom Server beantwortet wurde.
* '''<code>$param->{addr}</code>''' - Die HTTP-URL ohne Pfad und evtl. Authentifizerungsinformationen des HTTP-Servers (z.B. "<nowiki>http://myserver.com:8080</nowiki>").
* '''<code>$param->{auth}</code>''' - Die Zugangsdaten als <code>Username:Passwort</code>, welcher verwendet wurde um sich gegenüber dem HTTP-Server zu authentifizieren (nur wenn Authentifizierung benutzt wurde).
|-
| style="vertical-align:top" | '''<code>$err</code>'''|| Falls beim Aufruf der URL ein Fehler aufgetreten ist (z.B. Server nicht erreichbar oder Verbindungstimeout), dann ist dieser Wert mit einer Fehlermeldung gefüllt.

Wenn kein Fehler aufgetreten ist, ist dieser Wert mit einem Leerstring gefüllt (<code>$err = ""</code>)
|-
| style="vertical-align:top" | '''<code>$data</code>'''|| Die Ergebnisdaten, welche der HTTP-Server zurückgeliefert hat. Die Daten werden als Klartext in Form eines gesamten Strings zurückgegeben. Es handelt sich hierbei ausschließlich um den HTTP-Body.

Falls ein Fehler aufgetreten ist, ist dieser Wert mit einem Leersting gefüllt (<code>$data = ""</code>)
|}

Die Callback-Funktion kann nun die Daten aus der HTTP-Antwort verarbeiten oder bei Fehlern entsprechende Log-Meldungen ausgeben.

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

<source lang="perl">use HttpUtils;
sub X_GetHttpResponse($)
{
my ($hash, $def) = @_;
my $name = $hash->{NAME};
my $param = {
url => "http://www.foo.de",
timeout => 5,
hash => $hash, # Muss gesetzt werden, damit die Callback funktion wieder $hash hat
method => "GET", # Lesen von Inhalten
header => "agent: TeleHeater/2.2.3\r\nUser-Agent: TeleHeater/2.2.3\r\nAccept: application/json", # Den Header gemäss abzufragender Daten ändern
callback => \&X_ParseHttpResponse # Diese Funktion soll das Ergebnis dieser HTTP Anfrage bearbeiten
};

HttpUtils_NonblockingGet($param); # Starten der HTTP Abfrage. Es gibt keinen Return-Code.
}

sub X_ParseHttpResponse($)
{
my ($param, $err, $data) = @_;
my $hash = $param->{hash};
my $name = $hash->{NAME};

if($err ne "") # wenn ein Fehler bei der HTTP Abfrage aufgetreten ist
{
Log3 $name, 3, "error while requesting ".$param->{url}." - $err"; # Eintrag fürs Log
readingsSingleUpdate($hash, "fullResponse", "ERROR"); # Readings erzeugen
}

elsif($data ne "") # wenn die Abfrage erfolgreich war ($data enthält die Ergebnisdaten des HTTP Aufrufes)
{
Log3 $name, 3, "url ".$param->{url}." returned: $data"; # Eintrag fürs Log

# An dieser Stelle die Antwort parsen / verarbeiten mit $data

readingsSingleUpdate($hash, "fullResponse", $data); # Readings erzeugen
}

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

=== HttpUtils_Close ===

Für den Abbruch von offenen Verbindungen und noch laufenden NonBockingGet-Aufrufen gibt es die Funktion HttpUtils_Close. Diese kann z.B. beim Löschen eines Devices oder Herunterfahren des Servers aufgerufen werden, um bestehende Verbindungen zu schliessen.

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

'''Aufruf: <code>HttpUtils_Close($param)</code>'''

{| class="wikitable"
|-
! style="width:175px" | Parameter !! style="width:auto" | Bedeutung
|-
| style="vertical-align:top" | '''<code>$param</code>'''

''mandatory''
|| Der Hash, der beim vorherigen Aufruf an HTTPUtils Funktionen (HttpUtils_NonblockingGet oder HttpUtils_BlockingGet) übergeben wurde

|}

[[Kategorie:Development]]

Homebridge User Configs

2016-12-04T15:18:15Z

Loredo: /* Roomba über THINKINGCLEANER Modul */

Dieser Eintrag dient zur Sammlung funktionsfähiger Homebridge Configs.

Bitte immer die FHEM Version und Homebridge Version angegeben.

Sehr gute Hinweise gibt es hier: http://www.meintechblog.de/2015/10/mit-siri-und-fhem-das-gesamte-smart-home-per-stimme-steuern/

== EnOcean STM 250 Tür-/Fensterkontakt ==
Der STM 250 liefert als Status in FHEM <code>open</code>, wenn das Fenster offen und damit der Kontakt "offen" ist. Analog liefert er <code>closed</code> wenn das Fenster geschlossen und damit auch der Kontakt geschlossen ist. Diese Statusangaben sind sehr intuitiv zu verstehen und zu interpretieren.

Die characteristic <code>ContactSensorState</code> von HomeKit liefert entweder den Wert <code>CONTACT_DETECTED=0</code> oder <code>CONTACT_NOT_DETECTED=1</code> zurück. Wobei <code>CONTACT_DETECTED</code> bedeutet, dass der Kontakt geschlossen ist. Je nach Darstellung in der HomeKit-fähigen App muss dieses Verhalten bei der Interpretation berücksichtigt werden. Die App Eve von Elgato zum Beispiel liefert für Kontaktsensoren "JA" oder "NEIN" mit der Bedeutung <code>CONTACT_DETECTED=0=JA</code> bzw. <code>CONTACT_NOT_DETECTED=1=NEIN</code> zurück.

Noch ein wichtiger Punkt: Um einen Sensorkontakt sinnvoll einzurichten sollte als zusätzlicher Wert für das Attribut <code>genericdeviceType</code> der Wert <code>ContactSensor</code> hinzugefügt werden. Wie das geht ist im Eintrag [[Homebridge_einrichten#FHEM_konfigurieren | Homebridge einrichten]] ausführlicher beschrieben.

Folgende Attribute dann hinzufügen:
attr STM250 genericDeviceType ContactSensor
attr STM250 homebridgeMapping ContactSensorState=state,values=closed:CONTACT_DETECTED;open:CONTACT_NOT_DETECTED

Getestet mit
FHEM 5.7 Rev. 9893
Homebridge 0.2.16
homebridge-fhem Vorschauversion aus [http://forum.fhem.de/index.php/topic,48558.msg402024.html#msg402024 homebridge/homekit]

== Modul RESIDENTS für Anwesenheitserkennung und Steuerung der Anwesenheit benutzen ==
[[Datei:Homebridge_bewohner_zu_szene.jpeg|mini|Schaltzustand eines Bewohners zu einer Szene hinzufügen]]
Aus den einzelnen Komponenten des Moduls RESIDENTS, homebridge sowie der characteristic <code>On</code> und der Szenensteuerung lässt sich eine gleichzeitige Steuerung der Anwesenheit und Anwesenheitserkennung basteln.

Dazu müssen folgende Schritte unternommen werden:
* einem Bewohner aus dem Modul ROOMMATE die Steuerung über homebridgeMapping hinzufügen
* Szene für "Ich bin zu Hause" und "Ich gehe jetzt" in einer HomeKit-fähigen App wie z.B. Eve einrichten

Man kann einen beliebigen Bewohner aus dem Modul ROOMMATE nehmen und ihn über die characteristic <code>On</code> in Form eines Schalters sozusagen schaltbar machen. Nur wird das Ein- und Ausschalten des Bewohners über HomeKit in FHEM auf den Status home bzw. absent gemappt. Seit dem 06.02.2016 werden RESIDENTS automatisch als Occupancy Sensor für HomeKit annonciert. Nun noch die Attribute des ROOMMATE wie folgt setzen:
attr <ROOMMATE> genericDeviceType switch
attr <ROOMMATE> homebridgeMapping On=state,valueOn=/home|awoken|asleep|gotosleep/,valueOff=/gone|absent/,cmdOn=home,cmdOff=absent

Natürlich muss der Bewohner noch dem Filter von homebridge hinzugefügt und homebridge neu gestartet werden.

Anschließend geht es in der HomeKit-fähigen App Deiner Wahl weiter. In Eve von Elgato ist von vornherein zum Beispiel vorgesehen, dass man zwei Szenen "Ich bin zuhause" und "Ich verlasse das Haus" hat. Zu diesen Szenen wird eine Aktion hinzugefügt indem der Bewohner, den das ROOMMATE-Modul meldet zur Szene hinzugefügt wird und beim Nachhausekommen "eingeschaltet" wird. Genauso wird mit der Szene "Ich verlasse das Haus" verfahren: Bewohner zur Szene hinzufügen und den Schaltvorgang auf "ausschalten" setzen.

Mit den Sprachbefehlen "Ich bin zuhause" oder "Ich verlasse das Haus" wird die entsprechende Szene eingeschaltet, homebridge schaltet über das <code>homebridgeMapping</code> Attribut dann den Bewohner auf "home" oder "absent".

Getestet mit
FHEM 5.7 Rev. 9893
Homebridge 0.2.16
homebridge-fhem Vorschauversion aus [http://forum.fhem.de/index.php/topic,48558.msg402024.html#msg402024 homebridge/homekit]

== ZWave Türschloss Vision ZM1701 einbinden ==
Das ZWave Türschloss ZM1701 von der Firma Vision sendet seinen aktuellen Schließstatus in ein einzelnes Reading wie "lock", sondern schickt eine ganze Reihe von Informationen über den Zustand in das Reading <code>doorLockOperation</code>. Das Schließen und Öffnen der Türschlosses wird auch nicht mit einem Setzen des <code>state</code> erreicht, sondern mit dem Setzen von <code>doorLockOperation</code>. Das macht das Einbinden in homebridge nicht trivial, funktioniert aber über folgendes Homebridge-Mapping:
attr <ZM1701> genericDeviceType lock
attr <ZM1701> homebridgeMapping LockCurrentState=doorLockOperation,values=/\ssecured/:SECURED;/unsecured/:UNSECURED LockTargetState=doorLockOperation,values=/\ssecured/:SECURED;/unsecured/:UNSECURED,cmds=SECURED:doorLockOperation+close;UNSECURED:doorLockOperation+open

Kurz zur Erklärung: Um ein Schloss über HomeKit steuern zu können braucht es zwei characteristics. LockCurrentState zeigt an, ob das Schloss geöffnet oder geschlossen ist. Und mit LockTargetState wird das Schloss geöffnet oder geschlossen. Damit der aktuelle Status des Schlosses ausgelesen werden kann, muss aus dem FHEM-Reading <code>doorLockOperation</code> die Zeichenfolge <code> secured</code> oder <code>unsecured</code> extrahiert werden, daher die beiden regulären Ausdrücke <code>/\ssecured/</code> und <code>/unsecured/</code>. In der characteristic <code>LockTargetState</code> muss sowohl der aktuelle Status des Schlosses als auch das Kommando angegeben werden, schließlich möchte man ein geschlossenes Schloss nicht nochmal schließen. Daher wird erst aus dem Reading <code>doorLockOperation</code> der aktuelle Status des Schlosses ausgelesen und die damit korrespondierenden Befehle über <code>cmds=SECURED:doorLockOperation+close;UNSECURED:doorLockOperation+open</code> generiert.

Wer es in FHEM über ein webCmd einfacher zu bedienen haben möchte, fügt bitte noch die dafür notwendigen Attribute und die leicht geänderten homebridgeMappings wie folgt ein:
attr <ZM1701> genericDeviceType lock
attr <ZM1701> homebridgeMapping LockCurrentState=doorLockOperation,values=/\ssecured/:SECURED;/unsecured/:UNSECURED LockTargetState=doorLockOperation,values=/\ssecured/:SECURED;/unsecured/:UNSECURED,cmds=SECURED:close;UNSECURED:open
attr <ZM1701> /doorLockOperation open:open/doorLockOperation close:close
attr <ZM1701> webCmd open:close

Getestet mit
FHEM 5.7 Rev. 12191
homebridge 0.4.6
homebridge-fhem 0.2.48

== Roomba über THINKINGCLEANER Modul ==
attr <THINKINGCLEANER> genericDeviceType switch
attr <THINKINGCLEANER> homebridgeMapping clear On=state,valueOn=/^(on|dock)/,cmdOn=on,cmdOff=off,nocache=1 ChargingState=deviceStatus,values=/(_recon|_full|_trickle)$/:CHARGING;/^.*/:NOT_CHARGING
attr <THINKINGCLEANER> siriName Robby

Getestet mit
FHEM 5.7 Rev. 12680
homebridge 0.4.11
homebridge-fhem 0.2.66

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

Homebridge User Configs

2016-12-04T15:17:10Z

Loredo:

Dieser Eintrag dient zur Sammlung funktionsfähiger Homebridge Configs.

Bitte immer die FHEM Version und Homebridge Version angegeben.

Sehr gute Hinweise gibt es hier: http://www.meintechblog.de/2015/10/mit-siri-und-fhem-das-gesamte-smart-home-per-stimme-steuern/

== EnOcean STM 250 Tür-/Fensterkontakt ==
Der STM 250 liefert als Status in FHEM <code>open</code>, wenn das Fenster offen und damit der Kontakt "offen" ist. Analog liefert er <code>closed</code> wenn das Fenster geschlossen und damit auch der Kontakt geschlossen ist. Diese Statusangaben sind sehr intuitiv zu verstehen und zu interpretieren.

Die characteristic <code>ContactSensorState</code> von HomeKit liefert entweder den Wert <code>CONTACT_DETECTED=0</code> oder <code>CONTACT_NOT_DETECTED=1</code> zurück. Wobei <code>CONTACT_DETECTED</code> bedeutet, dass der Kontakt geschlossen ist. Je nach Darstellung in der HomeKit-fähigen App muss dieses Verhalten bei der Interpretation berücksichtigt werden. Die App Eve von Elgato zum Beispiel liefert für Kontaktsensoren "JA" oder "NEIN" mit der Bedeutung <code>CONTACT_DETECTED=0=JA</code> bzw. <code>CONTACT_NOT_DETECTED=1=NEIN</code> zurück.

Noch ein wichtiger Punkt: Um einen Sensorkontakt sinnvoll einzurichten sollte als zusätzlicher Wert für das Attribut <code>genericdeviceType</code> der Wert <code>ContactSensor</code> hinzugefügt werden. Wie das geht ist im Eintrag [[Homebridge_einrichten#FHEM_konfigurieren | Homebridge einrichten]] ausführlicher beschrieben.

Folgende Attribute dann hinzufügen:
attr STM250 genericDeviceType ContactSensor
attr STM250 homebridgeMapping ContactSensorState=state,values=closed:CONTACT_DETECTED;open:CONTACT_NOT_DETECTED

Getestet mit
FHEM 5.7 Rev. 9893
Homebridge 0.2.16
homebridge-fhem Vorschauversion aus [http://forum.fhem.de/index.php/topic,48558.msg402024.html#msg402024 homebridge/homekit]

== Modul RESIDENTS für Anwesenheitserkennung und Steuerung der Anwesenheit benutzen ==
[[Datei:Homebridge_bewohner_zu_szene.jpeg|mini|Schaltzustand eines Bewohners zu einer Szene hinzufügen]]
Aus den einzelnen Komponenten des Moduls RESIDENTS, homebridge sowie der characteristic <code>On</code> und der Szenensteuerung lässt sich eine gleichzeitige Steuerung der Anwesenheit und Anwesenheitserkennung basteln.

Dazu müssen folgende Schritte unternommen werden:
* einem Bewohner aus dem Modul ROOMMATE die Steuerung über homebridgeMapping hinzufügen
* Szene für "Ich bin zu Hause" und "Ich gehe jetzt" in einer HomeKit-fähigen App wie z.B. Eve einrichten

Man kann einen beliebigen Bewohner aus dem Modul ROOMMATE nehmen und ihn über die characteristic <code>On</code> in Form eines Schalters sozusagen schaltbar machen. Nur wird das Ein- und Ausschalten des Bewohners über HomeKit in FHEM auf den Status home bzw. absent gemappt. Seit dem 06.02.2016 werden RESIDENTS automatisch als Occupancy Sensor für HomeKit annonciert. Nun noch die Attribute des ROOMMATE wie folgt setzen:
attr <ROOMMATE> genericDeviceType switch
attr <ROOMMATE> homebridgeMapping On=state,valueOn=/home|awoken|asleep|gotosleep/,valueOff=/gone|absent/,cmdOn=home,cmdOff=absent

Natürlich muss der Bewohner noch dem Filter von homebridge hinzugefügt und homebridge neu gestartet werden.

Anschließend geht es in der HomeKit-fähigen App Deiner Wahl weiter. In Eve von Elgato ist von vornherein zum Beispiel vorgesehen, dass man zwei Szenen "Ich bin zuhause" und "Ich verlasse das Haus" hat. Zu diesen Szenen wird eine Aktion hinzugefügt indem der Bewohner, den das ROOMMATE-Modul meldet zur Szene hinzugefügt wird und beim Nachhausekommen "eingeschaltet" wird. Genauso wird mit der Szene "Ich verlasse das Haus" verfahren: Bewohner zur Szene hinzufügen und den Schaltvorgang auf "ausschalten" setzen.

Mit den Sprachbefehlen "Ich bin zuhause" oder "Ich verlasse das Haus" wird die entsprechende Szene eingeschaltet, homebridge schaltet über das <code>homebridgeMapping</code> Attribut dann den Bewohner auf "home" oder "absent".

Getestet mit
FHEM 5.7 Rev. 9893
Homebridge 0.2.16
homebridge-fhem Vorschauversion aus [http://forum.fhem.de/index.php/topic,48558.msg402024.html#msg402024 homebridge/homekit]

== ZWave Türschloss Vision ZM1701 einbinden ==
Das ZWave Türschloss ZM1701 von der Firma Vision sendet seinen aktuellen Schließstatus in ein einzelnes Reading wie "lock", sondern schickt eine ganze Reihe von Informationen über den Zustand in das Reading <code>doorLockOperation</code>. Das Schließen und Öffnen der Türschlosses wird auch nicht mit einem Setzen des <code>state</code> erreicht, sondern mit dem Setzen von <code>doorLockOperation</code>. Das macht das Einbinden in homebridge nicht trivial, funktioniert aber über folgendes Homebridge-Mapping:
attr <ZM1701> genericDeviceType lock
attr <ZM1701> homebridgeMapping LockCurrentState=doorLockOperation,values=/\ssecured/:SECURED;/unsecured/:UNSECURED LockTargetState=doorLockOperation,values=/\ssecured/:SECURED;/unsecured/:UNSECURED,cmds=SECURED:doorLockOperation+close;UNSECURED:doorLockOperation+open

Kurz zur Erklärung: Um ein Schloss über HomeKit steuern zu können braucht es zwei characteristics. LockCurrentState zeigt an, ob das Schloss geöffnet oder geschlossen ist. Und mit LockTargetState wird das Schloss geöffnet oder geschlossen. Damit der aktuelle Status des Schlosses ausgelesen werden kann, muss aus dem FHEM-Reading <code>doorLockOperation</code> die Zeichenfolge <code> secured</code> oder <code>unsecured</code> extrahiert werden, daher die beiden regulären Ausdrücke <code>/\ssecured/</code> und <code>/unsecured/</code>. In der characteristic <code>LockTargetState</code> muss sowohl der aktuelle Status des Schlosses als auch das Kommando angegeben werden, schließlich möchte man ein geschlossenes Schloss nicht nochmal schließen. Daher wird erst aus dem Reading <code>doorLockOperation</code> der aktuelle Status des Schlosses ausgelesen und die damit korrespondierenden Befehle über <code>cmds=SECURED:doorLockOperation+close;UNSECURED:doorLockOperation+open</code> generiert.

Wer es in FHEM über ein webCmd einfacher zu bedienen haben möchte, fügt bitte noch die dafür notwendigen Attribute und die leicht geänderten homebridgeMappings wie folgt ein:
attr <ZM1701> genericDeviceType lock
attr <ZM1701> homebridgeMapping LockCurrentState=doorLockOperation,values=/\ssecured/:SECURED;/unsecured/:UNSECURED LockTargetState=doorLockOperation,values=/\ssecured/:SECURED;/unsecured/:UNSECURED,cmds=SECURED:close;UNSECURED:open
attr <ZM1701> /doorLockOperation open:open/doorLockOperation close:close
attr <ZM1701> webCmd open:close

Getestet mit
FHEM 5.7 Rev. 12191
homebridge 0.4.6
homebridge-fhem 0.2.48

== Roomba über THINKINGCLEANER Modul ==
attr <THINKINGCLEANER> genericDeviceType switch
attr <THINKINGCLEANER> homebridgeMapping clear On=state,valueOn=/^(on|standby|dock)/,cmdOn=on,cmdOff=off,nocache=1 ChargingState=deviceStatus,values=/(_recon|_full|_trickle)$/:CHARGING;/^.*/:NOT_CHARGING
attr <THINKINGCLEANER> siriName Robby

Getestet mit
FHEM 5.7 Rev. 12680
homebridge 0.4.11
homebridge-fhem 0.2.66

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

Homebridge User Configs

2016-12-04T15:12:01Z

Loredo:

Dieser Eintrag dient zur Sammlung funktionsfähiger Homebridge Configs.

Bitte immer die FHEM Version und Homebridge Version angegeben.

Sehr gute Hinweise gibt es hier: http://www.meintechblog.de/2015/10/mit-siri-und-fhem-das-gesamte-smart-home-per-stimme-steuern/

== EnOcean STM 250 Tür-/Fensterkontakt ==
Der STM 250 liefert als Status in FHEM <code>open</code>, wenn das Fenster offen und damit der Kontakt "offen" ist. Analog liefert er <code>closed</code> wenn das Fenster geschlossen und damit auch der Kontakt geschlossen ist. Diese Statusangaben sind sehr intuitiv zu verstehen und zu interpretieren.

Die characteristic <code>ContactSensorState</code> von HomeKit liefert entweder den Wert <code>CONTACT_DETECTED=0</code> oder <code>CONTACT_NOT_DETECTED=1</code> zurück. Wobei <code>CONTACT_DETECTED</code> bedeutet, dass der Kontakt geschlossen ist. Je nach Darstellung in der HomeKit-fähigen App muss dieses Verhalten bei der Interpretation berücksichtigt werden. Die App Eve von Elgato zum Beispiel liefert für Kontaktsensoren "JA" oder "NEIN" mit der Bedeutung <code>CONTACT_DETECTED=0=JA</code> bzw. <code>CONTACT_NOT_DETECTED=1=NEIN</code> zurück.

Noch ein wichtiger Punkt: Um einen Sensorkontakt sinnvoll einzurichten sollte als zusätzlicher Wert für das Attribut <code>genericdeviceType</code> der Wert <code>ContactSensor</code> hinzugefügt werden. Wie das geht ist im Eintrag [[Homebridge_einrichten#FHEM_konfigurieren | Homebridge einrichten]] ausführlicher beschrieben.

Folgende Attribute dann hinzufügen:
attr STM250 genericDeviceType ContactSensor
attr STM250 homebridgeMapping ContactSensorState=state,values=closed:CONTACT_DETECTED;open:CONTACT_NOT_DETECTED

Getestet mit
FHEM 5.7 Rev. 9893
Homebridge 0.2.16
homebridge-fhem Vorschauversion aus [http://forum.fhem.de/index.php/topic,48558.msg402024.html#msg402024 homebridge/homekit]

== Modul RESIDENTS für Anwesenheitserkennung und Steuerung der Anwesenheit benutzen ==
[[Datei:Homebridge_bewohner_zu_szene.jpeg|mini|Schaltzustand eines Bewohners zu einer Szene hinzufügen]]
Aus den einzelnen Komponenten des Moduls RESIDENTS, homebridge sowie der characteristic <code>On</code> und der Szenensteuerung lässt sich eine gleichzeitige Steuerung der Anwesenheit und Anwesenheitserkennung basteln.

Dazu müssen folgende Schritte unternommen werden:
* einem Bewohner aus dem Modul ROOMMATE die Steuerung über homebridgeMapping hinzufügen
* Szene für "Ich bin zu Hause" und "Ich gehe jetzt" in einer HomeKit-fähigen App wie z.B. Eve einrichten

Man kann einen beliebigen Bewohner aus dem Modul ROOMMATE nehmen und ihn über die characteristic <code>On</code> in Form eines Schalters sozusagen schaltbar machen. Nur wird das Ein- und Ausschalten des Bewohners über HomeKit in FHEM auf den Status home bzw. absent gemappt. Seit dem 06.02.2016 werden RESIDENTS automatisch als Occupancy Sensor für HomeKit annonciert. Nun noch die Attribute des ROOMMATE wie folgt setzen:
attr <ROOMMATE> genericDeviceType switch
attr <ROOMMATE> homebridgeMapping On=state,valueOn=/home|awoken|asleep|gotosleep/,valueOff=/gone|absent/,cmdOn=home,cmdOff=absent

Natürlich muss der Bewohner noch dem Filter von homebridge hinzugefügt und homebridge neu gestartet werden.

Anschließend geht es in der HomeKit-fähigen App Deiner Wahl weiter. In Eve von Elgato ist von vornherein zum Beispiel vorgesehen, dass man zwei Szenen "Ich bin zuhause" und "Ich verlasse das Haus" hat. Zu diesen Szenen wird eine Aktion hinzugefügt indem der Bewohner, den das ROOMMATE-Modul meldet zur Szene hinzugefügt wird und beim Nachhausekommen "eingeschaltet" wird. Genauso wird mit der Szene "Ich verlasse das Haus" verfahren: Bewohner zur Szene hinzufügen und den Schaltvorgang auf "ausschalten" setzen.

Mit den Sprachbefehlen "Ich bin zuhause" oder "Ich verlasse das Haus" wird die entsprechende Szene eingeschaltet, homebridge schaltet über das <code>homebridgeMapping</code> Attribut dann den Bewohner auf "home" oder "absent".

Getestet mit
FHEM 5.7 Rev. 9893
Homebridge 0.2.16
homebridge-fhem Vorschauversion aus [http://forum.fhem.de/index.php/topic,48558.msg402024.html#msg402024 homebridge/homekit]

== ZWave Türschloss Vision ZM1701 einbinden ==
Das ZWave Türschloss ZM1701 von der Firma Vision sendet seinen aktuellen Schließstatus in ein einzelnes Reading wie "lock", sondern schickt eine ganze Reihe von Informationen über den Zustand in das Reading <code>doorLockOperation</code>. Das Schließen und Öffnen der Türschlosses wird auch nicht mit einem Setzen des <code>state</code> erreicht, sondern mit dem Setzen von <code>doorLockOperation</code>. Das macht das Einbinden in homebridge nicht trivial, funktioniert aber über folgendes Homebridge-Mapping:
attr <ZM1701> genericDeviceType lock
attr <ZM1701> homebridgeMapping LockCurrentState=doorLockOperation,values=/\ssecured/:SECURED;/unsecured/:UNSECURED LockTargetState=doorLockOperation,values=/\ssecured/:SECURED;/unsecured/:UNSECURED,cmds=SECURED:doorLockOperation+close;UNSECURED:doorLockOperation+open

Kurz zur Erklärung: Um ein Schloss über HomeKit steuern zu können braucht es zwei characteristics. LockCurrentState zeigt an, ob das Schloss geöffnet oder geschlossen ist. Und mit LockTargetState wird das Schloss geöffnet oder geschlossen. Damit der aktuelle Status des Schlosses ausgelesen werden kann, muss aus dem FHEM-Reading <code>doorLockOperation</code> die Zeichenfolge <code> secured</code> oder <code>unsecured</code> extrahiert werden, daher die beiden regulären Ausdrücke <code>/\ssecured/</code> und <code>/unsecured/</code>. In der characteristic <code>LockTargetState</code> muss sowohl der aktuelle Status des Schlosses als auch das Kommando angegeben werden, schließlich möchte man ein geschlossenes Schloss nicht nochmal schließen. Daher wird erst aus dem Reading <code>doorLockOperation</code> der aktuelle Status des Schlosses ausgelesen und die damit korrespondierenden Befehle über <code>cmds=SECURED:doorLockOperation+close;UNSECURED:doorLockOperation+open</code> generiert.

Wer es in FHEM über ein webCmd einfacher zu bedienen haben möchte, fügt bitte noch die dafür notwendigen Attribute und die leicht geänderten homebridgeMappings wie folgt ein:
attr <ZM1701> genericDeviceType lock
attr <ZM1701> homebridgeMapping LockCurrentState=doorLockOperation,values=/\ssecured/:SECURED;/unsecured/:UNSECURED LockTargetState=doorLockOperation,values=/\ssecured/:SECURED;/unsecured/:UNSECURED,cmds=SECURED:close;UNSECURED:open
attr <ZM1701> /doorLockOperation open:open/doorLockOperation close:close
attr <ZM1701> webCmd open:close

Getestet mit
FHEM 5.7 Rev. 12191
homebridge 0.4.6
homebridge-fhem 0.2.48

== Roomba über THINKINGCLEANER Modul ==
attr <THINKINGCLEANER> genericDeviceType switch
attr <THINKINGCLEANER> homebridgeMapping clear On=state,valueOn=/^(on|dock)/,cmdOn=on,cmdOff=off ChargingState=deviceStatus,values=/(_recon|_full|_trickle)$/:CHARGING;;/^.*/:NOT_CHARGING
attr <THINKINGCLEANER> siriName Robby

Getestet mit
FHEM 5.7 Rev. 12680
homebridge 0.4.11
homebridge-fhem 0.2.66

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

Homebridge User Configs

2016-12-04T15:11:34Z

Loredo: Add Roomba/THINKINGCLEANER

Dieser Eintrag dient zur Sammlung funktionsfähiger Homebridge Configs.

Bitte immer die FHEM Version und Homebridge Version angegeben.

Sehr gute Hinweise gibt es hier: http://www.meintechblog.de/2015/10/mit-siri-und-fhem-das-gesamte-smart-home-per-stimme-steuern/

== EnOcean STM 250 Tür-/Fensterkontakt ==
Der STM 250 liefert als Status in FHEM <code>open</code>, wenn das Fenster offen und damit der Kontakt "offen" ist. Analog liefert er <code>closed</code> wenn das Fenster geschlossen und damit auch der Kontakt geschlossen ist. Diese Statusangaben sind sehr intuitiv zu verstehen und zu interpretieren.

Die characteristic <code>ContactSensorState</code> von HomeKit liefert entweder den Wert <code>CONTACT_DETECTED=0</code> oder <code>CONTACT_NOT_DETECTED=1</code> zurück. Wobei <code>CONTACT_DETECTED</code> bedeutet, dass der Kontakt geschlossen ist. Je nach Darstellung in der HomeKit-fähigen App muss dieses Verhalten bei der Interpretation berücksichtigt werden. Die App Eve von Elgato zum Beispiel liefert für Kontaktsensoren "JA" oder "NEIN" mit der Bedeutung <code>CONTACT_DETECTED=0=JA</code> bzw. <code>CONTACT_NOT_DETECTED=1=NEIN</code> zurück.

Noch ein wichtiger Punkt: Um einen Sensorkontakt sinnvoll einzurichten sollte als zusätzlicher Wert für das Attribut <code>genericdeviceType</code> der Wert <code>ContactSensor</code> hinzugefügt werden. Wie das geht ist im Eintrag [[Homebridge_einrichten#FHEM_konfigurieren | Homebridge einrichten]] ausführlicher beschrieben.

Folgende Attribute dann hinzufügen:
attr STM250 genericDeviceType ContactSensor
attr STM250 homebridgeMapping ContactSensorState=state,values=closed:CONTACT_DETECTED;open:CONTACT_NOT_DETECTED

Getestet mit
FHEM 5.7 Rev. 9893
Homebridge 0.2.16
homebridge-fhem Vorschauversion aus [http://forum.fhem.de/index.php/topic,48558.msg402024.html#msg402024 homebridge/homekit]

== Modul RESIDENTS für Anwesenheitserkennung und Steuerung der Anwesenheit benutzen ==
[[Datei:Homebridge_bewohner_zu_szene.jpeg|mini|Schaltzustand eines Bewohners zu einer Szene hinzufügen]]
Aus den einzelnen Komponenten des Moduls RESIDENTS, homebridge sowie der characteristic <code>On</code> und der Szenensteuerung lässt sich eine gleichzeitige Steuerung der Anwesenheit und Anwesenheitserkennung basteln.

Dazu müssen folgende Schritte unternommen werden:
* einem Bewohner aus dem Modul ROOMMATE die Steuerung über homebridgeMapping hinzufügen
* Szene für "Ich bin zu Hause" und "Ich gehe jetzt" in einer HomeKit-fähigen App wie z.B. Eve einrichten

Man kann einen beliebigen Bewohner aus dem Modul ROOMMATE nehmen und ihn über die characteristic <code>On</code> in Form eines Schalters sozusagen schaltbar machen. Nur wird das Ein- und Ausschalten des Bewohners über HomeKit in FHEM auf den Status home bzw. absent gemappt. Seit dem 06.02.2016 werden RESIDENTS automatisch als Occupancy Sensor für HomeKit annonciert. Nun noch die Attribute des ROOMMATE wie folgt setzen:
attr <ROOMMATE> genericDeviceType switch
attr <ROOMMATE> homebridgeMapping On=state,valueOn=/home|awoken|asleep|gotosleep/,valueOff=/gone|absent/,cmdOn=home,cmdOff=absent

Natürlich muss der Bewohner noch dem Filter von homebridge hinzugefügt und homebridge neu gestartet werden.

Anschließend geht es in der HomeKit-fähigen App Deiner Wahl weiter. In Eve von Elgato ist von vornherein zum Beispiel vorgesehen, dass man zwei Szenen "Ich bin zuhause" und "Ich verlasse das Haus" hat. Zu diesen Szenen wird eine Aktion hinzugefügt indem der Bewohner, den das ROOMMATE-Modul meldet zur Szene hinzugefügt wird und beim Nachhausekommen "eingeschaltet" wird. Genauso wird mit der Szene "Ich verlasse das Haus" verfahren: Bewohner zur Szene hinzufügen und den Schaltvorgang auf "ausschalten" setzen.

Mit den Sprachbefehlen "Ich bin zuhause" oder "Ich verlasse das Haus" wird die entsprechende Szene eingeschaltet, homebridge schaltet über das <code>homebridgeMapping</code> Attribut dann den Bewohner auf "home" oder "absent".

Getestet mit
FHEM 5.7 Rev. 9893
Homebridge 0.2.16
homebridge-fhem Vorschauversion aus [http://forum.fhem.de/index.php/topic,48558.msg402024.html#msg402024 homebridge/homekit]

== ZWave Türschloss Vision ZM1701 einbinden ==
Das ZWave Türschloss ZM1701 von der Firma Vision sendet seinen aktuellen Schließstatus in ein einzelnes Reading wie "lock", sondern schickt eine ganze Reihe von Informationen über den Zustand in das Reading <code>doorLockOperation</code>. Das Schließen und Öffnen der Türschlosses wird auch nicht mit einem Setzen des <code>state</code> erreicht, sondern mit dem Setzen von <code>doorLockOperation</code>. Das macht das Einbinden in homebridge nicht trivial, funktioniert aber über folgendes Homebridge-Mapping:
attr <ZM1701> genericDeviceType lock
attr <ZM1701> homebridgeMapping LockCurrentState=doorLockOperation,values=/\ssecured/:SECURED;/unsecured/:UNSECURED LockTargetState=doorLockOperation,values=/\ssecured/:SECURED;/unsecured/:UNSECURED,cmds=SECURED:doorLockOperation+close;UNSECURED:doorLockOperation+open

Kurz zur Erklärung: Um ein Schloss über HomeKit steuern zu können braucht es zwei characteristics. LockCurrentState zeigt an, ob das Schloss geöffnet oder geschlossen ist. Und mit LockTargetState wird das Schloss geöffnet oder geschlossen. Damit der aktuelle Status des Schlosses ausgelesen werden kann, muss aus dem FHEM-Reading <code>doorLockOperation</code> die Zeichenfolge <code> secured</code> oder <code>unsecured</code> extrahiert werden, daher die beiden regulären Ausdrücke <code>/\ssecured/</code> und <code>/unsecured/</code>. In der characteristic <code>LockTargetState</code> muss sowohl der aktuelle Status des Schlosses als auch das Kommando angegeben werden, schließlich möchte man ein geschlossenes Schloss nicht nochmal schließen. Daher wird erst aus dem Reading <code>doorLockOperation</code> der aktuelle Status des Schlosses ausgelesen und die damit korrespondierenden Befehle über <code>cmds=SECURED:doorLockOperation+close;UNSECURED:doorLockOperation+open</code> generiert.

Wer es in FHEM über ein webCmd einfacher zu bedienen haben möchte, fügt bitte noch die dafür notwendigen Attribute und die leicht geänderten homebridgeMappings wie folgt ein:
attr <ZM1701> genericDeviceType lock
attr <ZM1701> homebridgeMapping LockCurrentState=doorLockOperation,values=/\ssecured/:SECURED;/unsecured/:UNSECURED LockTargetState=doorLockOperation,values=/\ssecured/:SECURED;/unsecured/:UNSECURED,cmds=SECURED:close;UNSECURED:open
attr <ZM1701> /doorLockOperation open:open/doorLockOperation close:close
attr <ZM1701> webCmd open:close

Getestet mit
FHEM 5.7 Rev. 12191
homebridge 0.4.6
homebridge-fhem 0.2.48

== Roomba über THINKINGCLEANER Modul ==
attr <THINKINGCLEANER> genericDeviceType switch
attr <THINKINGCLEANER> homebridgeMapping clear On=state,valueOn=/^(on|dock)/,cmdOn=on,cmdOff=off ChargingState=deviceStatus,values=/(_recon|_full|_trickle)$/:CHARGING;;/^.*/:NOT_CHARGING
attr <THINKINGCLEANER> siriName Robby

Getestet mit
FHEM 5.7 Rev. 12680
homebridge 0.4.11
homebridge-fhem 0.2.66

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

HP1000

2016-10-23T09:45:27Z

Loredo: Ergänzung zur automatischen Anlage einer FHEMWEB Instanz

{{Infobox Modul
|ModPurpose=Einbindung einer HP1000 Wetterstation
|ModType=d
|ModForumArea=Wettermodule
|ModFTopic=44022
|ModTechName=50_HP1000.pm
|ModOwner={{Link2FU|1363|Loredo}}
}}
== HP1000 ==
HP1000 ist ein Modul zum Auslesen von HP1000/WH2600 Wetterstationen von renkforce/Froggit, etc.

Funktionsweise des Moduls ist, dass in der Wetterstation eine FHEMWEB Instanz angegeben wird, an die die Wetterstation dann regelmäßig die Daten sendet.
== Konfiguration ==
Die Konfiguration des Moduls erfolgt in zwei Schritten:
=== Definition der Wetterstation ===
Zunächst wird das Modul in Fhem definiert. Die Definition kann mit und ohne Benutzernamen und Passwort erfolgen. Wenn bei der Definition Benutzername und Passwort nicht angegeben werden, werden die von der Wetterstation gesendeten Benutzerdaten von Fhem nicht überprüft. Eine WH2600 Station erfordert im Webinterfache immer die Angabe von Benutzername und Passwort.
Definition mit Benutzername und Passwort:
define Wetterstation HP1000 Benutzer Passwort
Definition ohne Benutzername und Passwort:
define Wetterstation HP1000
Es wird dabei automatisch eine neue FHEMWEB Instanz namens "WEBweatherstation" und dem webname Attribut "weatherstation" angelegt, sofern nicht bereits eine passende Instanz gefunden werden konnte. Diese kann anschließend weiter konfiguriert (z.B. anderer Port, anderer Device Name etc.), entscheidend ist das Attribut webname exakt so beizubehalten.

=== Einstellungen in der Station ===
Dann muss der Station eingestellt werden, dass die Wetterinformationen an Fhem geschickt werden sollen. Bei einer WH2600 (Station ohne LCD Display) geschieht das im Webinterface, bei einer HP1000 direkt in den Einstellungen des LCD Displays.
Dazu unter "Weather Network" folgendes eintragen:
<pre>Remote Server => Customized
Server IP/Hostname => <Fhem-Domainname> bzw. <Fhem-IP> (siehe unten)
Server Port => Der Port der neuen Webinstanz in Fhem (im Beispiel oben 8089)
Station ID => selbst gewählter Benutzername
Password => selbst gewähltes Passwort</pre>
Zu '''Server IP/Hostname''': Hier muss entweder der Domainname angegeben werden, unter dem Fhem erreichbar ist (vollständige Domain nicht vergessen!), oder die IP. Wenn in Fhem keine Daten ankommen, ist das hier meist der Knackpunkt. Erfahrungen zeigen, dass teilweise der Domainname nicht vollständig angegeben wurde oder aber der Domainname nicht aufgelöst werden kann (vielleicht gibt es hier Probleme einzelner Stationen, bei der Konfiguration via DHCP den Nameserver-Eintrag richtig umzusetzen). Auch hat die Firmware oft einen Bug der verhindert, dass IP Adressen direkt verwendet werden können. Hier muss dann zwingend auf einen Domainnamen zurückgegriffen werden!
Einfach mal alle Möglichkeiten durchprobieren.

'''Station ID''' und '''Passwort''' müssen hier angegeben werden. Bei der Definition der Station in Fhem kann man diese angeben (dann wird geprüft, ob die berechtigte Station Daten schickt) oder weglassen (dann werden Benutzername und Passwort nicht von Fhem geprüft).

== Tipps, Tricks, Problemlösungen ==
=== FileLog ===
Das Modul definiert bei der Erstellung kein FileLog. Wenn man eines definiert, bietet sich aufgrund der Häufigkeit von Datenübertragungen und damit der Menge an übertragenen Informationen das Loggen nur des T:-Readings an:
define FileLog_WeatherStation FileLog ./log/WeatherStation-%Y.log WeatherStation:T:.*

Alternativ sei auch auf die Verwendung von DbLog verwiesen. Dort kann man mit Hilfe des DbLogInclude Attributs granularer einstellen wie oft ein Wert geloggt werden soll:
attr WeatherStation DbLogInclude windSpeed:300 windGust:300 windChill:300 temperature.*:300 humidity.*:300 luminosity:300 uv:300

Wichtig ist auch, dass für das Logging die richtigen Events ausgelöst werden. Wer die event-on-* Attribute benutzt kann diese in Kombination mit DbLogInclude z.B. so setzen:
attr event-on-update-reading temperature.*,humidity.*,windSpeed,windGust,windChill,luminosity,uv.*,dewpoint.*,rain.*,solarradiation
attr event-on-change-reading wu_state,extsrv_state,Activity

=== Falsch angezeigte/zu wenig Readings ===
Abhängig von der Firmwareversion und/oder dem Modell der Station kann es dazu kommen, dass teilweise nicht alle Readings oder die Readings mit den falschen Einheiten (z. B. Wingeschwindigkeit in mph, obwohl km/h konfiguriert wurde) angezeigt werden. In diesem Fall hilft es, im Webinterface der Wetterstation bei der Definition "Weather Network" den "Server Type" auf "JSP" zu stellen.

=== Keine Daten in Fhem ===
Wenn in Fhem keine Daten von der Wetterstation ankommen, liegt das häufig daran, dass FHEM nicht richtig als "Weather Network" konfiguriert wurde. Wenn die '''erforderlichen Eingaben im Webinterface''' (s. o.) der Station nicht helfen, kann man sich zum Testen per telnet mit der Wetterstation verbinden (Benutzername admin, Passwort admin). Mögliche Befehle:
<pre>help
quit
reboot
Usage: passwd
Old Password:
New Password:
Re-enter New Password:
Usage: username <user name>
Usage: ipconfig
Usage: setip <ip addr>
Usage: setmask <netmask>
Usage: setgateway <ip addr>
Usage: setdns <ip addr>
Usage: setmode <mode>
<mode>: 0: SERVER 1: CLIENT
Usage: setsrvport <port>
Usage: setdstport <port>
Usage: dhcpclient <status>
<status>: 0: disable 1: enable
Usage: connectype <protocol>
<protocol>: 0: TCP 1: UDP
Usage: transmitimer <time>
<time>: time in ms
Usage: saveconfig
Usage: accessip <index> <ip addr>
<index>: index of accessible IP
<ip addr>: accessible IP address
Usage: setaccip <mode>
<mode>: 0: disable 1: enable
Usage: setaw <cold start> <authentication fail> <ip changed> <password changed>
<cold start>: 0: Disable 1: Enable
<authentication fail>: 0: Disable 1: Enable
<ip changed>: 0: Disable 1: Enable
<password changed>: 0: Disable 1: Enable
Usage: setdsthn <Host name/IP>
Usage: tftpsrv <ip addr>
Usage: filename <file name>
Usage: dlfirmware
Usage: seteep <HEX RegStartAddr> <HEX Byte 0> <HEX Byte 1>...<HEX Byte N>
Usage: dbgmsg <mode>
<mode>: 0: Disable 1: Enable
Usage: connstatus
Usage: ping xxx.xxx.xxx.xxx
Usage: setRTC <HEX RegStartAddr> <HEX Byte 0> <HEX Byte 1>...<HEX Byte N></pre>
Am besten mit "ipconfig" sich die aktuelle Konfiguration anzeigen lassen. Mit ping kann man Verbindungen z. B. zu Fhem testen.

UConv

2016-10-22T13:48:34Z

Loredo:

{{Infobox Modul
|ModPurpose=Hilfsfunktionen zur modulübergreifenden Benutzung bei der Umrechnung von Einheiten.
|ModType=h
|ModCmdRef=intro 
|ModForumArea=FHEM Development
|ModTechName=UConv.pm
|ModOwner=Loredo ([http://forum.fhem.de/index.php?action=profile;u=1363 Forum] / [[Benutzer Diskussion:loredo|Wiki]])}}

[[UConv]] soll modulübergreifend Funktionen bereitstellen, um verschiedene Einheiten umzurechnen. Es wird zur Zeit von dem [[HP1000|HP1000]] Modul verwendet.

== Benutzung ==
Um die im Folgenden beschriebenen Funktionen zu nutzen, muss die Datei UConv.pm eingebunden werden. Ein Modulautor kann das durch eine
:<code>use UConv;</code>
Anweisung in seinem Modul tun. Ein Endanwender mit einem notify:
:<code><nowiki>define uconvInit notify global:INITIALIZED {use UConv}</nowiki></code>

Es stehen verschiedene Funktionen zur Verfügung, die alle über <code>UConv::<nowiki><Funktionsname></nowiki></code> aufgerufen werden können.
Die Datei UConv beinhaltet entsprechende Kommentare dafür, welche Einheiten eine Funktion genau umrechnet.

[[Kategorie:Development]]

UConv

2016-10-22T13:47:10Z

Loredo: Hinweis auf UConv.pm hinzugefügt

{{Infobox Modul
|ModPurpose=Hilfsfunktionen zur modulübergreifenden Benutzung bei der Umrechnung von Einheiten.
|ModType=h
|ModCmdRef=intro 
|ModForumArea=FHEM Development
|ModTechName=UConv.pm
|ModOwner=Loredo ([http://forum.fhem.de/index.php?action=profile;u=430 Forum] / [[Benutzer Diskussion:loredo|Wiki]])}}

[[UConv]] soll modulübergreifend Funktionen bereitstellen, um verschiedene Einheiten umzurechnen. Es wird zur Zeit von dem [[HP1000|HP1000]] Modul verwendet.

== Benutzung ==
Um die im Folgenden beschriebenen Funktionen zu nutzen, muss die Datei UConv.pm eingebunden werden. Ein Modulautor kann das durch eine
:<code>use UConv;</code>
Anweisung in seinem Modul tun. Ein Endanwender mit einem notify:
:<code><nowiki>define uconvInit notify global:INITIALIZED {use UConv}</nowiki></code>

Es stehen verschiedene Funktionen zur Verfügung, die alle über <code>UConv::<nowiki><Funktionsname></nowiki></code> aufgerufen werden können.
Die Datei UConv beinhaltet entsprechende Kommentare dafür, welche Einheiten eine Funktion genau umrechnet.

[[Kategorie:Development]]

HP1000

2016-10-11T12:22:59Z

Loredo: /* Tipps, Tricks, Problemlösungen */

{{Infobox Modul
|ModPurpose=Einbindung einer HP1000 Wetterstation
|ModType=d
|ModForumArea=Wettermodule
|ModFTopic=44022
|ModTechName=50_HP1000.pm
|ModOwner={{Link2FU|1363|Loredo}}
}}
== HP1000 ==
HP1000 ist ein Modul zum Auslesen von HP1000/WH2600 Wetterstationen von renkforce/Froggit, etc.

Funktionsweise des Moduls ist, dass in der Wetterstation eine FHEMWEB Instanz angegeben wird, an die die Wetterstation dann regelmäßig die Daten sendet.
== Konfiguration ==
Die Konfiguration des Moduls erfolgt in drei Schritten:
=== Definition einer Webinstanz für die Wetterstation ===
Zunächst muss auf einem eigenen Port eine neue FHEMWEB-Instanz angelegt werden, z.B. mit dem Namen WEBweather. Dieser muss zwingend der Name weatherstation zugewiesen werden. Dieser ist in der Firmware der Stationen fest codiert.
define WEBweather FHEMWEB 8089 global
attr WEBweather webname weatherstation
=== Definition der Wetterstation ===
Dann wird das Modul noch in Fhem definiert. Die Definition kann mit und ohne Benutzernamen und Passwort erfolgen. Wenn bei der Definition Benutzername und Passwort nicht angegeben werden, werden die von der Wetterstation gesendeten Benutzerdaten von Fhem nicht überprüft. Eine WH2600 Station erfordert im Webinterfache immer die Angabe von Benutzername und Passwort.
Definition mit Benutzername und Passwort:
define Wetterstation HP1000 Benutzer Passwort
Definition ohne Benutzername und Passwort:
define Wetterstation HP1000

=== Einstellungen in der Station ===
Dann muss der Station eingestellt werden, dass die Wetterinformationen an Fhem geschickt werden sollen. Bei einer WH2600 (Station ohne LCD Display) geschieht das im Webinterface, bei einer HP1000 direkt in den Einstellungen des LCD Displays.
Dazu unter "Weather Network" folgendes eintragen:
<pre>Remote Server => Customized
Server IP/Hostname => <Fhem-Domainname> bzw. <Fhem-IP> (siehe unten)
Server Port => Der Port der neuen Webinstanz in Fhem (im Beispiel oben 8089)
Station ID => selbst gewählter Benutzername
Password => selbst gewähltes Passwort</pre>
Zu '''Server IP/Hostname''': Hier muss entweder der Domainname angegeben werden, unter dem Fhem erreichbar ist (vollständige Domain nicht vergessen!), oder die IP. Wenn in Fhem keine Daten ankommen, ist das hier meist der Knackpunkt. Erfahrungen zeigen, dass teilweise der Domainname nicht vollständig angegeben wurde oder aber der Domainname nicht aufgelöst werden kann (vielleicht gibt es hier Probleme einzelner Stationen, bei der Konfiguration via DHCP den Nameserver-Eintrag richtig umzusetzen). Auch hat die Firmware oft einen Bug der verhindert, dass IP Adressen direkt verwendet werden können. Hier muss dann zwingend auf einen Domainnamen zurückgegriffen werden!
Einfach mal alle Möglichkeiten durchprobieren.

'''Station ID''' und '''Passwort''' müssen hier angegeben werden. Bei der Definition der Station in Fhem kann man diese angeben (dann wird geprüft, ob die berechtigte Station Daten schickt) oder weglassen (dann werden Benutzername und Passwort nicht von Fhem geprüft).

== Tipps, Tricks, Problemlösungen ==
=== FileLog ===
Das Modul definiert bei der Erstellung kein FileLog. Wenn man eines definiert, bietet sich aufgrund der Häufigkeit von Datenübertragungen und damit der Menge an übertragenen Informationen das Loggen nur des T:-Readings an:
define FileLog_WeatherStation FileLog ./log/WeatherStation-%Y.log WeatherStation:T:.*

Alternativ sei auch auf die Verwendung von DbLog verwiesen. Dort kann man mit Hilfe des DbLogInclude Attributs granularer einstellen wie oft ein Wert geloggt werden soll:
attr WeatherStation DbLogInclude windSpeed:300 windGust:300 windChill:300 temperature.*:300 humidity.*:300 luminosity:300 uv:300

Wichtig ist auch, dass für das Logging die richtigen Events ausgelöst werden. Wer die event-on-* Attribute benutzt kann diese in Kombination mit DbLogInclude z.B. so setzen:
attr event-on-update-reading temperature.*,humidity.*,windSpeed,windGust,windChill,luminosity,uv.*,dewpoint.*,rain.*,solarradiation
attr event-on-change-reading wu_state,extsrv_state,Activity

=== Falsch angezeigte/zu wenig Readings ===
Abhängig von der Firmwareversion und/oder dem Modell der Station kann es dazu kommen, dass teilweise nicht alle Readings oder die Readings mit den falschen Einheiten (z. B. Wingeschwindigkeit in mph, obwohl km/h konfiguriert wurde) angezeigt werden. In diesem Fall hilft es, im Webinterface der Wetterstation bei der Definition "Weather Network" den "Server Type" auf "JSP" zu stellen.

=== Keine Daten in Fhem ===
Wenn in Fhem keine Daten von der Wetterstation ankommen, liegt das häufig daran, dass FHEM nicht richtig als "Weather Network" konfiguriert wurde. Wenn die '''erforderlichen Eingaben im Webinterface''' (s. o.) der Station nicht helfen, kann man sich zum Testen per telnet mit der Wetterstation verbinden (Benutzername admin, Passwort admin). Mögliche Befehle:
<pre>help
quit
reboot
Usage: passwd
Old Password:
New Password:
Re-enter New Password:
Usage: username <user name>
Usage: ipconfig
Usage: setip <ip addr>
Usage: setmask <netmask>
Usage: setgateway <ip addr>
Usage: setdns <ip addr>
Usage: setmode <mode>
<mode>: 0: SERVER 1: CLIENT
Usage: setsrvport <port>
Usage: setdstport <port>
Usage: dhcpclient <status>
<status>: 0: disable 1: enable
Usage: connectype <protocol>
<protocol>: 0: TCP 1: UDP
Usage: transmitimer <time>
<time>: time in ms
Usage: saveconfig
Usage: accessip <index> <ip addr>
<index>: index of accessible IP
<ip addr>: accessible IP address
Usage: setaccip <mode>
<mode>: 0: disable 1: enable
Usage: setaw <cold start> <authentication fail> <ip changed> <password changed>
<cold start>: 0: Disable 1: Enable
<authentication fail>: 0: Disable 1: Enable
<ip changed>: 0: Disable 1: Enable
<password changed>: 0: Disable 1: Enable
Usage: setdsthn <Host name/IP>
Usage: tftpsrv <ip addr>
Usage: filename <file name>
Usage: dlfirmware
Usage: seteep <HEX RegStartAddr> <HEX Byte 0> <HEX Byte 1>...<HEX Byte N>
Usage: dbgmsg <mode>
<mode>: 0: Disable 1: Enable
Usage: connstatus
Usage: ping xxx.xxx.xxx.xxx
Usage: setRTC <HEX RegStartAddr> <HEX Byte 0> <HEX Byte 1>...<HEX Byte N></pre>
Am besten mit "ipconfig" sich die aktuelle Konfiguration anzeigen lassen. Mit ping kann man Verbindungen z. B. zu Fhem testen.

HP1000

2016-10-04T11:25:57Z

Loredo:

{{Infobox Modul
|ModPurpose=Einbindung einer HP1000 Wetterstation
|ModType=d
|ModForumArea=Wettermodule
|ModFTopic=44022
|ModTechName=50_HP1000.pm
|ModOwner={{Link2FU|1363|Loredo}}
}}
== HP1000 ==
HP1000 ist ein Modul zum Auslesen von HP1000/WH2600 Wetterstationen von renkforce/Froggit, etc.

Funktionsweise des Moduls ist, dass in der Wetterstation eine FHEMWEB Instanz angegeben wird, an die die Wetterstation dann regelmäßig die Daten sendet.
== Konfiguration ==
Die Konfiguration des Moduls erfolgt in drei Schritten:
=== Definition einer Webinstanz für die Wetterstation ===
Zunächst muss auf einem eigenen Port eine neue FHEMWEB-Instanz angelegt werden, z.B. mit dem Namen WEBweather. Dieser muss zwingend der Name weatherstation zugewiesen werden. Dieser ist in der Firmware der Stationen fest codiert.
define WEBweather FHEMWEB 8089 global
attr WEBweather webname weatherstation
=== Definition der Wetterstation ===
Dann wird das Modul noch in Fhem definiert. Die Definition kann mit und ohne Benutzernamen und Passwort erfolgen. Wenn bei der Definition Benutzername und Passwort nicht angegeben werden, werden die von der Wetterstation gesendeten Benutzerdaten von Fhem nicht überprüft. Eine WH2600 Station erfordert im Webinterfache immer die Angabe von Benutzername und Passwort.
Definition mit Benutzername und Passwort:
define Wetterstation HP1000 Benutzer Passwort
Definition ohne Benutzername und Passwort:
define Wetterstation HP1000

=== Einstellungen in der Station ===
Dann muss der Station eingestellt werden, dass die Wetterinformationen an Fhem geschickt werden sollen. Bei einer WH2600 (Station ohne LCD Display) geschieht das im Webinterface, bei einer HP1000 direkt in den Einstellungen des LCD Displays.
Dazu unter "Weather Network" folgendes eintragen:
<pre>Remote Server => Customized
Server IP/Hostname => <Fhem-Domainname> bzw. <Fhem-IP> (siehe unten)
Server Port => Der Port der neuen Webinstanz in Fhem (im Beispiel oben 8089)
Station ID => selbst gewählter Benutzername
Password => selbst gewähltes Passwort</pre>
Zu '''Server IP/Hostname''': Hier muss entweder der Domainname angegeben werden, unter dem Fhem erreichbar ist (vollständige Domain nicht vergessen!), oder die IP. Wenn in Fhem keine Daten ankommen, ist das hier meist der Knackpunkt. Erfahrungen zeigen, dass teilweise der Domainname nicht vollständig angegeben wurde oder aber der Domainname nicht aufgelöst werden kann (vielleicht gibt es hier Probleme einzelner Stationen, bei der Konfiguration via DHCP den Nameserver-Eintrag richtig umzusetzen). Auch hat die Firmware oft einen Bug der verhindert, dass IP Adressen direkt verwendet werden können. Hier muss dann zwingend auf einen Domainnamen zurückgegriffen werden!
Einfach mal alle Möglichkeiten durchprobieren.

'''Station ID''' und '''Passwort''' müssen hier angegeben werden. Bei der Definition der Station in Fhem kann man diese angeben (dann wird geprüft, ob die berechtigte Station Daten schickt) oder weglassen (dann werden Benutzername und Passwort nicht von Fhem geprüft).

== Tipps, Tricks, Problemlösungen ==
=== FileLog ===
Das Modul definiert bei der Erstellung kein FileLog. Wenn man eines definiert, bietet sich aufgrund der Häufigkeit von Datenübertragungen und damit der Menge an übertragenen Informationen das Loggen nur des T:-Readings an:
define FileLog_WeatherStation FileLog ./log/WeatherStation-%Y.log WeatherStation:T:.*

Alternativ sei auch auf die Verwendung von DbLog verwiesen. Dort kann man mit Hilfe des DbLogInclude Attributs granularer einstellen wie oft ein Wert geloggt werden soll:
attr WeatherStation DbLogInclude windSpeed:300 windGust:300 windChill:300 temperature.*:300 humidity.*:300 luminosity:300 uv:300

Wichtig ist auch, dass für das Logging die richtigen Events ausgelöst werden. Wer die event-on-* Attribute benutzt kann diese in Kombination mit DbLogInclude z.B. so setzen:
attr event-on-update-reading temperature.*,humidity.*,windSpeed,windGust,windChill,luminosity,uv,dewpoint.*,rain.*

=== Falsch angezeigte/zu wenig Readings ===
Abhängig von der Firmwareversion und/oder dem Modell der Station kann es dazu kommen, dass teilweise nicht alle Readings oder die Readings mit den falschen Einheiten (z. B. Wingeschwindigkeit in mph, obwohl km/h konfiguriert wurde) angezeigt werden. In diesem Fall hilft es, im Webinterface der Wetterstation bei der Definition "Weather Network" den "Server Type" auf "JSP" zu stellen.

=== Keine Daten in Fhem ===
Wenn in Fhem keine Daten von der Wetterstation ankommen, liegt das häufig daran, dass FHEM nicht richtig als "Weather Network" konfiguriert wurde. Wenn die '''erforderlichen Eingaben im Webinterface''' (s. o.) der Station nicht helfen, kann man sich zum Testen per telnet mit der Wetterstation verbinden (Benutzername admin, Passwort admin). Mögliche Befehle:
<pre>help
quit
reboot
Usage: passwd
Old Password:
New Password:
Re-enter New Password:
Usage: username <user name>
Usage: ipconfig
Usage: setip <ip addr>
Usage: setmask <netmask>
Usage: setgateway <ip addr>
Usage: setdns <ip addr>
Usage: setmode <mode>
<mode>: 0: SERVER 1: CLIENT
Usage: setsrvport <port>
Usage: setdstport <port>
Usage: dhcpclient <status>
<status>: 0: disable 1: enable
Usage: connectype <protocol>
<protocol>: 0: TCP 1: UDP
Usage: transmitimer <time>
<time>: time in ms
Usage: saveconfig
Usage: accessip <index> <ip addr>
<index>: index of accessible IP
<ip addr>: accessible IP address
Usage: setaccip <mode>
<mode>: 0: disable 1: enable
Usage: setaw <cold start> <authentication fail> <ip changed> <password changed>
<cold start>: 0: Disable 1: Enable
<authentication fail>: 0: Disable 1: Enable
<ip changed>: 0: Disable 1: Enable
<password changed>: 0: Disable 1: Enable
Usage: setdsthn <Host name/IP>
Usage: tftpsrv <ip addr>
Usage: filename <file name>
Usage: dlfirmware
Usage: seteep <HEX RegStartAddr> <HEX Byte 0> <HEX Byte 1>...<HEX Byte N>
Usage: dbgmsg <mode>
<mode>: 0: Disable 1: Enable
Usage: connstatus
Usage: ping xxx.xxx.xxx.xxx
Usage: setRTC <HEX RegStartAddr> <HEX Byte 0> <HEX Byte 1>...<HEX Byte N></pre>
Am besten mit "ipconfig" sich die aktuelle Konfiguration anzeigen lassen. Mit ping kann man Verbindungen z. B. zu Fhem testen.

HP1000

2016-10-04T11:24:10Z

Loredo: /* Eingaben im Webinterface der Station */

{{Infobox Modul
|ModPurpose=Einbindung einer HP1000 Wetterstation
|ModType=d
|ModForumArea=Heizungssteuerung/Raumklima
|ModFTopic=44022
|ModTechName=50_HP1000.pm
|ModOwner={{Link2FU|1363|Loredo}}
}}
== HP1000 ==
HP1000 ist ein Modul zum Auslesen von HP1000/WH2600 Wetterstationen von renkforce/Froggit, etc.

Funktionsweise des Moduls ist, dass in der Wetterstation eine FHEMWEB Instanz angegeben wird, an die die Wetterstation dann regelmäßig die Daten sendet.
== Konfiguration ==
Die Konfiguration des Moduls erfolgt in drei Schritten:
=== Definition einer Webinstanz für die Wetterstation ===
Zunächst muss auf einem eigenen Port eine neue FHEMWEB-Instanz angelegt werden, z.B. mit dem Namen WEBweather. Dieser muss zwingend der Name weatherstation zugewiesen werden. Dieser ist in der Firmware der Stationen fest codiert.
define WEBweather FHEMWEB 8089 global
attr WEBweather webname weatherstation
=== Definition der Wetterstation ===
Dann wird das Modul noch in Fhem definiert. Die Definition kann mit und ohne Benutzernamen und Passwort erfolgen. Wenn bei der Definition Benutzername und Passwort nicht angegeben werden, werden die von der Wetterstation gesendeten Benutzerdaten von Fhem nicht überprüft. Eine WH2600 Station erfordert im Webinterfache immer die Angabe von Benutzername und Passwort.
Definition mit Benutzername und Passwort:
define Wetterstation HP1000 Benutzer Passwort
Definition ohne Benutzername und Passwort:
define Wetterstation HP1000

=== Einstellungen in der Station ===
Dann muss der Station eingestellt werden, dass die Wetterinformationen an Fhem geschickt werden sollen. Bei einer WH2600 (Station ohne LCD Display) geschieht das im Webinterface, bei einer HP1000 direkt in den Einstellungen des LCD Displays.
Dazu unter "Weather Network" folgendes eintragen:
<pre>Remote Server => Customized
Server IP/Hostname => <Fhem-Domainname> bzw. <Fhem-IP> (siehe unten)
Server Port => Der Port der neuen Webinstanz in Fhem (im Beispiel oben 8089)
Station ID => selbst gewählter Benutzername
Password => selbst gewähltes Passwort</pre>
Zu '''Server IP/Hostname''': Hier muss entweder der Domainname angegeben werden, unter dem Fhem erreichbar ist (vollständige Domain nicht vergessen!), oder die IP. Wenn in Fhem keine Daten ankommen, ist das hier meist der Knackpunkt. Erfahrungen zeigen, dass teilweise der Domainname nicht vollständig angegeben wurde oder aber der Domainname nicht aufgelöst werden kann (vielleicht gibt es hier Probleme einzelner Stationen, bei der Konfiguration via DHCP den Nameserver-Eintrag richtig umzusetzen). Auch hat die Firmware oft einen Bug der verhindert, dass IP Adressen direkt verwendet werden können. Hier muss dann zwingend auf einen Domainnamen zurückgegriffen werden!
Einfach mal alle Möglichkeiten durchprobieren.

'''Station ID''' und '''Passwort''' müssen hier angegeben werden. Bei der Definition der Station in Fhem kann man diese angeben (dann wird geprüft, ob die berechtigte Station Daten schickt) oder weglassen (dann werden Benutzername und Passwort nicht von Fhem geprüft).

== Tipps, Tricks, Problemlösungen ==
=== FileLog ===
Das Modul definiert bei der Erstellung kein FileLog. Wenn man eines definiert, bietet sich aufgrund der Häufigkeit von Datenübertragungen und damit der Menge an übertragenen Informationen das Loggen nur des T:-Readings an:
define FileLog_WeatherStation FileLog ./log/WeatherStation-%Y.log WeatherStation:T:.*

Alternativ sei auch auf die Verwendung von DbLog verwiesen. Dort kann man mit Hilfe des DbLogInclude Attributs granularer einstellen wie oft ein Wert geloggt werden soll:
attr WeatherStation DbLogInclude windSpeed:300 windGust:300 windChill:300 temperature.*:300 humidity.*:300 luminosity:300 uv:300

Wichtig ist auch, dass für das Logging die richtigen Events ausgelöst werden. Wer die event-on-* Attribute benutzt kann diese in Kombination mit DbLogInclude z.B. so setzen:
attr event-on-update-reading temperature.*,humidity.*,windSpeed,windGust,windChill,luminosity,uv,dewpoint.*,rain.*

=== Falsch angezeigte/zu wenig Readings ===
Abhängig von der Firmwareversion und/oder dem Modell der Station kann es dazu kommen, dass teilweise nicht alle Readings oder die Readings mit den falschen Einheiten (z. B. Wingeschwindigkeit in mph, obwohl km/h konfiguriert wurde) angezeigt werden. In diesem Fall hilft es, im Webinterface der Wetterstation bei der Definition "Weather Network" den "Server Type" auf "JSP" zu stellen.

=== Keine Daten in Fhem ===
Wenn in Fhem keine Daten von der Wetterstation ankommen, liegt das häufig daran, dass FHEM nicht richtig als "Weather Network" konfiguriert wurde. Wenn die '''erforderlichen Eingaben im Webinterface''' (s. o.) der Station nicht helfen, kann man sich zum Testen per telnet mit der Wetterstation verbinden (Benutzername admin, Passwort admin). Mögliche Befehle:
<pre>help
quit
reboot
Usage: passwd
Old Password:
New Password:
Re-enter New Password:
Usage: username <user name>
Usage: ipconfig
Usage: setip <ip addr>
Usage: setmask <netmask>
Usage: setgateway <ip addr>
Usage: setdns <ip addr>
Usage: setmode <mode>
<mode>: 0: SERVER 1: CLIENT
Usage: setsrvport <port>
Usage: setdstport <port>
Usage: dhcpclient <status>
<status>: 0: disable 1: enable
Usage: connectype <protocol>
<protocol>: 0: TCP 1: UDP
Usage: transmitimer <time>
<time>: time in ms
Usage: saveconfig
Usage: accessip <index> <ip addr>
<index>: index of accessible IP
<ip addr>: accessible IP address
Usage: setaccip <mode>
<mode>: 0: disable 1: enable
Usage: setaw <cold start> <authentication fail> <ip changed> <password changed>
<cold start>: 0: Disable 1: Enable
<authentication fail>: 0: Disable 1: Enable
<ip changed>: 0: Disable 1: Enable
<password changed>: 0: Disable 1: Enable
Usage: setdsthn <Host name/IP>
Usage: tftpsrv <ip addr>
Usage: filename <file name>
Usage: dlfirmware
Usage: seteep <HEX RegStartAddr> <HEX Byte 0> <HEX Byte 1>...<HEX Byte N>
Usage: dbgmsg <mode>
<mode>: 0: Disable 1: Enable
Usage: connstatus
Usage: ping xxx.xxx.xxx.xxx
Usage: setRTC <HEX RegStartAddr> <HEX Byte 0> <HEX Byte 1>...<HEX Byte N></pre>
Am besten mit "ipconfig" sich die aktuelle Konfiguration anzeigen lassen. Mit ping kann man Verbindungen z. B. zu Fhem testen.

Msg

2016-10-04T11:21:58Z

Loredo:

{{SEITENTITEL:msg}}{{Infobox Modul
|ModPurpose=Versenden von Nachrichten der Typen Audio, Text, Mail, Push, Light, Screen
|ModType=cmd
|ModForumArea=Automatisierung
|ModFTopic=39983
|ModCmdRef=MSG
|ModTechName=75_MSG.pm
|ModOwner={{Link2FU|1363|Loredo}}
}}

Bisher keine über das in der Infobox verlinkte Forenthema hinausgehenden Informationen verfügbar, auch der commandref-Eintrag ist bisher (warum eigentlich?) leer. Darüber hinaus ist die Schreibweise inkonsistent und/oder irreführend: der Befehl ist in Kleinbuchstaben einzugeben, obwohl der Modulname mit Großbuchstaben geschrieben wird. (--> Antwort dazu: [http://www.fhemwiki.de/wiki/Benutzer_Diskussion:Ph1959de#Wiki_Beitrag_zu_msg])

Der Befehl [[msg]] ersetzt ausserdem das vormals verfügbare Modul '''MSG'''. Benutzer des alten Moduls müssen ihre Devices auf MSGFile und/oder MSGMail umstellen; bitte dafür das Forenthema {{Link2Forum|Topic=43447|LinkText="Benutzer von 75_MSG.pm: Aktion notwendig vor Update ab dem 04.11.2015"}} beachten!

Benutzer Diskussion:Ph1959de

2016-10-04T11:19:52Z

Loredo: Neuer Abschnitt /* Wiki Beitrag zu msg */

== Kategoriestruktur ==

Ich habe eine Bestandsaufnahme der Kategoriestruktur mittels Freeplane Mindmap Programm erstellt. Die Quelldatei kann ich derzeit hier nicht ablegen, da nur Bilddateien erlaubt sind. Bei Bedarf bitte nach der .mm Datei fragen, ich sende sie gern an Interessenten (die willens sind, an der Umstrukturierung mitzuarbeiten). --[[Benutzer:Ph1959de|Greetz, Peter]] ([[Benutzer Diskussion:Ph1959de|Diskussion]]) 13:13, 8. Jul. 2013 (CEST)

::Darfst du die Datei im Forum hochladen? Dann könntest einfach von hier dorthin verlinken? Grüße, [[Benutzer:Rince|Rince]] ([[Benutzer Diskussion:Rince|Diskussion]]) 08:43, 10. Jul. 2013 (CEST)

== Löschkandidaten ==

Die ganzen unverlinkten Bilde in Löschkandidaten packen hättest du nicht machen brauchen. Ich lösch unverlinkte Bilder die aus dem Import kommen auch so... wenn ich zwischendurch immer mal Zeit [[Benutzer:Soulman|Soulman]] ([[Benutzer Diskussion:Soulman|Diskussion]]) 17:00, 9. Jul. 2013 (CEST)

: :-) ... War ich ja gar nicht - das war Markusbloch ... von mir war der Hinweis auf die unverlinkten Dateien. --[[Benutzer:Ph1959de|Greetz, Peter]] ([[Benutzer Diskussion:Ph1959de|Diskussion]]) 23:03, 9. Jul. 2013 (CEST)

::: Manchmal hab ich eben so ne Phase irgendwie. Ist genauso wie bei der manuellen Korrektur aller Artikel direkt nach dem Import ;-) --[[Benutzer:Markusbloch|Markusbloch]] ([[Benutzer Diskussion:Markusbloch|Diskussion]]) 18:33, 10. Jul. 2013 (CEST)

::::Oh ja, hab irgendwie nicht aufgepasst. Also gegen die Phasen hab ich nix :-) [[Benutzer:Soulman|Soulman]] ([[Benutzer Diskussion:Soulman|Diskussion]]) 20:24, 10. Jul. 2013 (CEST)

== Abbildung von Bauteilen als Foto ==

Hallo Peter,

ich habe eine grundsätzliche Frage zur Darstellung von eigenen Fotos unter FHEMWiki. Ist es urheberrechtilich zulässig, eigene Fotos von Bauteilen darzustellen ?

Gruß
Lothar

:Hallo Lothar, ich bin da zwar kein Experte, denke aber, dass genau diese Art von Bildern erlaubt ist. Was nicht geht, ist das Übernehmen von Bildern von z.B. einer Herstellerseite, oder das direkte einbinden von Bildern aus fremdem Webspace. Ich denke, diese Aussage ist auch durch die Beschreibung bei Wikipedia abgedeckt: http://de.wikipedia.org/wiki/Hilfe:Bildertutorial/2_Bildrechte.
:<hr>
:--[[Benutzer:Ph1959de|Greetz, Peter]] ([[Benutzer Diskussion:Ph1959de|Diskussion]]) 13:30, 27. Aug. 2013 (CEST)

== Urheberschaft der alten Einträge ==

Hallo,

ich habe festgestellt, dass ihr beim Neuaufsetzen des Wiki alle Urheberinformationen gelöscht habt. War das Absicht, oder ein Unfall ?

KG

pah
<hr />
:Hallo pah, muss man wohl eher als Unfall bezeichnen. Das Wiki war komplett weg (und das Backup war nicht wirklich als solches zu bezeichnen, sondern komplett unbrauchbar) und wurde aus dem Google-Cache wieder hergestellt. Dabei ist natürlich die ganze Änderungshistorie (und damit auch das was Du vermutlich als Urheberinformation bezeichnest?) verloren gegangen.
:Aber das erinnert mich daran, dass ich bei einem der Administratoren dringend mal nachfragen wollte, wie es jetzt um die Sicherstellung der Backups steht.
:Und noch ein Nachsatz: ''...dass ihr beim Neuaufsetzen des Wiki...'': daran war ich nicht wirklich aktiv beteiligt. Bin auch nur "ganz normaler" Wiki Benutzer ohne besondere Rechte. --[[Benutzer:Ph1959de|Greetz, Peter]] ([[Benutzer Diskussion:Ph1959de|Diskussion]]) 14:43, 10. Nov. 2013 (CET)

== Links auf der Willkommensseite ==
Hallo Peter,

ich bin - als Neuling - nicht ganz sicher, ob die Kommunikation mit Dir so gedacht ist, aber zumindest stand das so auf der Begrüßungsseite ;-)

Ich habe festgestellt, dass in der Begrüßungsseite die Links auf die englische Version von wikipedia verweisen. Ich denke gerade für Neulinge wäre da die deutsche Version besser. (Z.B. http://de.wikipedia.org/wiki/Wikipedia:Tutorial)

--[[Benutzer:Funfactor|Funfactor]] ([[Benutzer Diskussion:Funfactor|Diskussion]]) 12:31, 28. Nov. 2013 (CET)
: ... ja, ist mir bekannt (trotzdem danke für die Rückmeldung). Kann ich aber leider nicht ändern, aber wenn ich mich recht erinnere, habe ich da beim "Betreiber" unseres Wiki schon mal nachgefragt aber bisher keine Antwort bekommen. Ich werde noch mal nachhaken. --[[Benutzer:Ph1959de|Greetz, Peter]] ([[Benutzer Diskussion:Ph1959de|Diskussion]]) 13:40, 28. Nov. 2013 (CET)
:: Ok, ich habe mir das noch mal angeschaut. Ist für neue Benutzer wirklich ziemlich verwirrend, deshalb habe ich vorerst mal "hartcodiert" auf die Links auf die deutschen Wikipedia:-Hilfeseiten umgestellt. --[[Benutzer:Ph1959de|Greetz, Peter]] ([[Benutzer Diskussion:Ph1959de|Diskussion]]) 18:42, 28. Nov. 2013 (CET)

== Verwendung der Sandbox ==
Hallo Peter,

den Wiki "sauber" zu halten ist ja eine wichtige Sache und ich denke dafür ist die [[FhemWiki:Sandbox]] gedacht.
Leider ist mir völlig unklar, wie ich diese in diesem Sinne verwenden soll. Gibt es hierzu eine Anleitung oder ein paar Hinweise?

--[[Benutzer:Funfactor|Funfactor]] ([[Benutzer Diskussion:Funfactor|Diskussion]]) 17:01, 29. Nov. 2013 (CET)
:Die Geschichte mit der Sandbox sollte man vielleicht nicht überbewerten. Was vermieden werden sollte ist
:* das wilde Anlegen von neuen Artikeln mit zusätzlichem experimentieren mit den Seitennamen (das gibt dann immer gleich eine Weiterleitung und zusätzlichen Aufräumaufwand)
:* jede noch so kleine Änderung separat abzuspeichern (Vorschau, Vorschau, Vorschau!); es gibt einige Leute, die neue Änderungen querlesen - denen macht man die Arbeit sonst unnötig schwer
:* was mir sonst noch so eingefallen ist, habe ich schon auf die [[FHEMWiki:Über FHEMWiki]]-Seite geschrieben (darf natürlich ergänzt werden)
:Experimentieren kann man zur Not auch im eigenen Namensraum (also in Deinem Fall <nowiki>[[Funfactor/Experiment...]]</nowiki>. Aber weitere Ideen sind jederzeit willkommen (bitte beachten: ich bin auch nur "ganz normaler User" hier). --[[Benutzer:Ph1959de|Greetz, Peter]] ([[Benutzer Diskussion:Ph1959de|Diskussion]]) 18:35, 29. Nov. 2013 (CET)

== On-for-timer zurücksetzen ==
Hi, es gibt da einen Artikel, den ich erstmals gerne mit einem Template Löschkandidat oder Qualtitästsicherung versehen würde: '''On-for-timer zurücksetzen'''
Erbitte Zweitmeinung. Und ich weiss nicht, ob wir ggf passende Templates haben muss ich zugeben.

[[Benutzer:Soulman|Soulman]] ([[Benutzer Diskussion:Soulman|Diskussion]]) 16:38, 27. Dez. 2013 (CET)
:<hr>
:--[[Benutzer:Stephan|Stephan]] ([[Benutzer Diskussion:Stephan|Diskussion]]) 16:45, 27. Dez. 2013 (CET) ''(Stefans Beitrag auf die Diskussionsseite des Artikels ([[Diskussion:On-for-timer_zurücksetzen]]) verschoben [ph1959de])''

:<hr>
:Ich (traue mich fast nicht :-), aber ich ...) verweise einfach mal auf die [[:Kategorie:Löschkandidaten]] und dortselbst auf den einleitenden Text.
:--[[Benutzer:Ph1959de|Greetz, Peter]] ([[Benutzer Diskussion:Ph1959de|Diskussion]]) 17:54, 27. Dez. 2013 (CET)

== autocreate ==
du hast recht. in der default konfiguration von autocreate ist autosave an. aber es gibt devices wie z.b. OWServer/HUE und ich glaube sogar HM die gehen nicht über autocreate und da ist es auf jeden fall nötig von hand save zu sagen. [[Benutzer:Justme|Justme]] 19:56, 8. Jan. 2014 (CET)

== 1-Wire - Kategorie vs. Artikel ==
Ich finde es nicht richtig, die Übersichtsbeschreibung - z.B. was das 1-Wire System ist - aus der Kategorieseite herauszunehmen. Diese Trennung schafft Redundanz und verhindert sie nicht.

Die Beschreibung ist eine unmittelbare semantische Eigenschaft der Kategorie, und kein untergeordneter Begriff.
--[[Benutzer:Pahenning|Pahenning]] ([[Benutzer Diskussion:Pahenning|Diskussion]]) 19:05, 22. Feb. 2014 (UTC)
:''Ich habe mir mal erlaubt, die Diskussion zu einem eigenen Abschnitt zu machen.''
:Nachdem Du meine Änderung mittlerweile rückgängig gemacht hast, erübrigt sich ja eine weitere Diskussion. Konsequenterweise müsstest Du aber dann auch den Artikel [[1-Wire]] mitpflegen - Artikel und Kategorietext sind derzeit nur deshalb gleich, weil ich die Inhalte mit meiner Änderung auch konsolidiert hatte.
:Damit die Diskussion über dieses Thema leichter auffindbar ist, kopiere ich sie noch in die [[Kategorie_Diskussion:1-Wire]], wo sie dann ggf. auch weitergeführt werden kann/sollte.

::Werde ich machen
::--[[Benutzer:Pahenning|Pahenning]] ([[Benutzer Diskussion:Pahenning|Diskussion]]) 15:38, 24. Mär. 2014 (UTC)

== Disclaimer ==

Es erscheinen immer mehr Schaltpläne hier im Wiki. Vorschlag: Einen allgemeinen Disclaimer des Inhaltes:

- Nachbau aller Schaltpläne auf eigene Gefahr
- Weder Betreiber noch Autoren übernehmen irgendeine Haftung für Inhalte und unmittelbare oder mittelbare Folgen
- Hinweis auf die gesetzlichen Regelungen beim Anschluss an 230 V-Netze

und diesen dann ausdrücklich unten neben "Datenschutz etc." referenzieren.

LG

pah
--[[Benutzer:Pahenning|Pahenning]] ([[Benutzer Diskussion:Pahenning|Diskussion]]) 15:42, 24. Mär. 2014 (UTC)
<hr>
:Wenn Du damit ein Template/eine Vorlage meinst, die auf relevanten Seiten gezielt eingebunden werden kann/muss, kann ich das gern mal in Angriff nehmen. Ich würde mich dann an dem Text orientieren, den Du auf [[1W-WPump]] eingefügt hast. Im Augenblick ließe sich dafür auch die Vorlage <nowiki>{{Randnotiz|...}}</nowiki> (siehe [[FHEMWiki:Über_FHEMWiki#Vorlagen]]) verwenden.
:Für einen generellen Wiki-weiten Disclaimer würde ich Dich eher bitten, das selbst zu machen oder den Wiki-Admin [[Benutzer Diskussion:akw|Arno]] anzusprechen.
:--[[Benutzer:Ph1959de|Greetz, Peter]] ([[Benutzer Diskussion:Ph1959de|Diskussion]]) 10:45, 25. Mär. 2014 (UTC)

== Erweiterung der Vorlage "Infobox Hardware" ==

hallo peter,
ich habe deine nachricht eben erst gesehen.

die idee war die infoboxen für modul und hardware ähnlicher zu machen. es ging mir nicht um den link zum modul sondern tatsächlich zum maintainer und da die möglichkeit aufs forums profil zu verlinken. so wie du es bei der neuen FLOORPLAN seite gemacht hast. zumindest bei 'meinen' modulen ist es zur zeit so das die info für die hardware und das fhem modul auf einer seite stehen. siehe: pca301 oder panstamp/swap. da gibt es entweder nur eine der beiden boxen oder die gleiche info taucht in beiden boxen auf. beides gefällt mir nicht wirklich.

eigentlich wollte ich die komplette ersteller zeile optional haben. das habe ich aber mit der tabellen formatierung noch nicht hin bekommen. jetzt ist erst mal nur der inhalt optional.

inzwischen habe ich noch "FHEMDevice" in "Modulname" geändert so wie es in der modul infobox auch ist. und die reihenfolge unter sonstiges geändert.

ich kann das aber auch wieder zurück bauen.

--[[Benutzer:Justme|Justme]] ([[Benutzer Diskussion:Justme|Diskussion]]) 13:51, 16. Mai 2014 (UTC)
:Auf der [[Vorlage_Diskussion:Infobox_Hardware]]-Seite geht's weiter.

== neue seiten ==
wo wir gerade dabei sind :). ich glaube es wäre schon den auskommentierten abschnitt 'neue seiten' auf der einstiegsseite zu aktivieren. --[[Benutzer:Justme|Justme]] ([[Benutzer Diskussion:Justme|Diskussion]]) 14:01, 16. Mai 2014 (UTC)

== neue Seiten ==
Hallo Peter,

Ich bin auch ein Neuling, und will meine Erfahrungen gerne anbieten an andere Benutzer. Zum Beispiel habe ich gerade der Modul Openweathermap in Betrieb genommen, und habe dabei einige Probleme gelöst. Ich hätte gern mehr Beispiele gehabt, und will die darum in eine Seite verwenden. Ist das erwünscht? Wenn ja, wie sollen neue Seiten über Devices eingeordnet werden, z.B. Openweathermap? (Deutsch ist nicht meine Muttersprache, so hoffentlich mache ich nicht zuviel Fehler).

[[Benutzer:TrudiB|TrudiB]] ([[Benutzer Diskussion:TrudiB|Diskussion]]) 11:37, 23. Mai 2014 (UTC)

<hr />
:Hallo Trudi, es ist auf jeden Fall erwünscht, dass (funktionierende) Beispiele (möglichst komplett) vorgestellt werden.
:Um eine neue Modulbeschreibung anzulegen, würde ich empfehlen, mal [[Vorlage:Infobox_Modul]] anzuschauen. Auf der [[FHEMWiki:Über_FHEMWiki]]-Seite findest Du auch in der Spalte "Ref" eine Liste der Seiten, die nach dem Schema angelegt oder überarbeitet wurden.
:Im Zweifel einfach noch mal nachfragen. --[[Benutzer:Ph1959de|Peter]] ([[Benutzer Diskussion:Ph1959de|Diskussion]]) 13:11, 23. Mai 2014 (UTC)

== Admin ==

Ph1959de erhält mit sofortiger Wirkung Administrator-Status im FHEMWiki. --[[Benutzer:Akw|Akw]] ([[Benutzer Diskussion:Akw|Diskussion]]) 10:56, 31. Mai 2014 (UTC)

==ZHK Seiten Einzelmodule ==

Hallo Peter,
Ich würde den Meinungsaustausch zum Thema wiki Pages valves/stellmotor gerne zu einem gemeinsamen Abschluss bringen. Ein (Erneutes) Feedback von dir wäre dabei hilfreich. Ich möchte dich daher herzlich einladen meine
Disk.Seite erneut zu besuchen und um Dein Feedback zu bereichern.
LG florian

==Kategorien für EnOcean ==
Hallo Peter,
für EnOcean gibt es 2 Kategorien: EnOcean und EnOcean_Components (anlog Homematic u.a.). In EnOcean ist der "EnOcean starter guide" und die Kategorie ist sinnvoll ins Wiki eingebunden. In der nichteingebundenen Kategorie "EnOcean_Components" befindet sich nur ein Sensor. Ist das so beabsichtigt? oder sollte das nicht angepasste werden.
Danke, Christian
<hr>
:Hallo Christian, nachdem die "EnOcean Components" Kategorie gerade erst "angelegt" wurde, würde ich erst mal abwarten. Eigentlich passt die Kategorie eher ins Konzept als das reine "EnOcean". Ich tendiere also eher dazu, alles auf "EnOcean Components" zu konsolidieren. --[[Benutzer:Ph1959de|Peter]] ([[Benutzer Diskussion:Ph1959de|Diskussion]]) 17:45, 13. Jul. 2014 (UTC)
::Hallo Peter, bin dabei, den EnOcean starter guide schrittweise zu überarbeiten. Ich würde dabei einige Aktoren- und Sensorenerläuterungen aus dem Starter guide entnehmen und als separate Artikel in "EnOcean components" aufnehmen; jedoch hätte ich gerne auch eine vernünftige Erreichbarkeit. Am einfachsten wäre es doch auch den starter guide zu verschieben. Dazu habe ich aber zuwenig Ahnung und würde das lieber einem Admin überlassen. --[[Benutzer:Krikan|Krikan]] ([[Benutzer Diskussion:Krikan|Diskussion]]) 18:09, 13. Jul. 2014 (UTC)
::<hr>
:::Christian, wenn Du mit "Starter Guide verschieben" das Umhängen in Kategorie "EnOcean Components" meinst: das habe ich gerade gemacht (die Änderung besteht einfach nur aus dem Einsetzen des neuen Kategorienames im Artikel). Außerdem habe ich Kategorie "EnOcean" nach [[:Kategorie:EnOcean Components]] verschoben. Jetzt ist es einheitlich zu FS20, HomeMatic, etc.
:::... und jetzt kannst Du loslegen mit den weiteren Änderungen - nur eine Bitte noch: Namensschema gut überlegen und neue Artikel möglichst erst speichern, wenn Du wirklich komplett damit zufrieden bist (Vorschaufunktion "großzügig verwenden"). Das macht es den (wenigen) Leuten, die alle Änderungen hier im Wiki "sichten" einfacher. --[[Benutzer:Ph1959de|Peter]] ([[Benutzer Diskussion:Ph1959de|Diskussion]]) 05:15, 14. Jul. 2014 (UTC)
:::: Vielen Dank für Deine schnelle Reaktion; werde versuchen Deine Bitten umzusetzen. Einen Wunsch habe ich natürlich noch ;-). Könnten wir EnOcean nicht auch auf der Hauptseite verlinken? Gruß, Christian--[[Benutzer:Krikan|Krikan]] ([[Benutzer Diskussion:Krikan|Diskussion]]) 09:27, 14. Jul. 2014 (UTC)
::::<hr>
:::::Ich habe ohnehin noch einige Änderungen für die Hauptseite auf meiner Liste. Da werde ich dann EnOcean auch mit aufnehmen ... bis dahin gibts ja dann vielleicht auch noch mehr Artikel in der Kategorie. --[[Benutzer:Ph1959de|Peter]] ([[Benutzer Diskussion:Ph1959de|Diskussion]]) 09:44, 14. Jul. 2014 (UTC)
::::::zum Namensschema: Habe in der Kategorie den Hinweis zum Namensschema analog der anderen Hardwaresystme eingefügt. Mich stört eigentlich das Vorsetzen von EnOcean- ,würde es gerne weglassen, aber es scheint übliche Konvention hier zu sein. In der der Übersicht erscheint so aber alles unter "E". Hast Du dazu eine Meinung? Sorry, wenn ich so viel frage, aber bevor ich alles durcheinanderbringe...
::::::<hr>
:::::::Kein Problem (zu fragen) - ist wirklich einfacher, als nachher alles wieder "geradebiegen" zu müssen.
:::::::Nun, das Namensschema kannst ja Du im Augenblick noch festlegen. Bei den (z.B.) [[:Kategorie:FS20 Components|FS20 Komponenten]] ist es, wie Du schon bemerkt hast, so, dass alles unter einem Buchstaben im Index erscheint. Wie man das ändern kann, habe ich exemplarisch mal im [[FS20 WS1 Wechselschalter]] gezeigt.
:::::::Hat alles so seine Vor- und Nachteile. Auch wenn Du nicht immer "EnOcean" davor schreibst, werden doch trotzdem viele Geräte mit den gleichen Buchstaben beginnen. Dann kann es ja auch gleich das EnOcean sein. --[[Benutzer:Ph1959de|Peter]] ([[Benutzer Diskussion:Ph1959de|Diskussion]]) 11:27, 14. Jul. 2014 (UTC)
:::: Hallo Peter! Danke für das kurzfristige Aufnehmen von EnOcean auf der Hauptseite. --[[Benutzer:Krikan|Krikan]] ([[Benutzer Diskussion:Krikan|Diskussion]]) 15:14, 17. Jul. 2014 (UTC)

== Subtype Tabelle für EnOcean ... Wiki-Tipps? ==
Hallo Peter, bräuchte noch einmal Wiki-Nachhilfe, da ich keine einfache Lösung gefunden habe. Vielleicht hast Du eine Idee:
Ich würde gerne auf der Kategorie-Seite EnOcean Components die vorhandenen EnOcean-Wiki-Artikel noch einmal separat anhand des EnOcean-Attributs "subType" zuordnen und sichtbar machen.
Quasi eine (lange) Tabelle der Art
{| class="wikitable"
|-
! subType !! Wiki-Seite Geräte
|-
| switch || [[EnOcean-PTM-210-Taster]]
|-
| lightSensor.01 || [[EnOcean-FAH60-Au%C3%9Fen-Helligkeitssensor]]
|-
|}
Manuell könnte ich das auf die Kategorienseite einpflegen -> fehleranfällig

Unterkategorien -> nicht erwünscht und klickintensiv, aber weniger wartungsintensiv

Unterseite zu EnOcean Components -> fehleranfällig und nicht auffällig

Hast Du dazu eine Idee/Meinung? Danke --[[Benutzer:Krikan|Krikan]] ([[Benutzer Diskussion:Krikan|Diskussion]]) 22:41, 5. Aug. 2014 (UTC)
<hr />
:Ich würde (zumindest für's Erste) mal was Ähnliches machen wie die "News" Sektion auf der Hauptseite. Da wird Vorlage [[Vorlage:FHEMWiki_News]] eingebunden. In dieser Vorlage wird (manuell, aber wie ich finde recht übersichtlich) eine Tabelle unter zuhilfenahme der Vorlage [[Vorlage:News]] aufgebaut.
:Wenn ich das richtig sehe, könntest Du sogar in (D)einer neuen Vorlage (nennen wir sie mal <nowiki>{{EnOceanSubTypeTable}}</nowiki>) einfach die News Vorlage so <nowiki>{{News|subType|Wiki-Seite}}</nowiki> "missbrauchen". Und die EnOceanSubTypeTable ließe sich dann nicht nur auf der Kategorie-Seite, sondern auch auf anderen Seiten bei Bedarf einfach so einbinden. Ansonsten halte ich mal die Augen offen und schaue, ob ich noch eine andere Lösung / einen besseren Ansatz finde.
:P.S.: Ich finde, Du machst einen Superjob in der "EnOcean-Abteilung" hier im Wiki. --[[Benutzer:Ph1959de|Peter]] ([[Benutzer Diskussion:Ph1959de|Diskussion]]) 06:16, 6. Aug. 2014 (UTC)
:<hr />
:: Ich probiere einmal Deinen Vorschlag umzusetzen. Hoffe es gelingt; löschen kann man immer noch....
:: Nach Lösungen hatte ich auch gesucht, aber mit meinem Wiki-Halbwissen nichts einfaches entdecken können.
::P.S.: Danke, zurück an Dich (auch wegen Nachhilfe). Bei EnOcean hilft 50watt auch mit. --[[Benutzer:Krikan|Krikan]] ([[Benutzer Diskussion:Krikan|Diskussion]]) 12:04, 6. Aug. 2014 (UTC)
:: Hm, hatte es befürchtet, Vorlage und Text waren schnell erstellt, aber dann: <s>Deine "nowiki" Geschichte habe ich anscheinend falsch verstanden.</s> (Man/Ich sollte erst denken und dann schreiben) Als Box -wie die News auf der Hauptseite- einbinden habe ich auf die Schnelle nicht hinbekommen. Da sind soviele Codetags mit denen ich mich noch beschäftigen muss. Hoffe ich habe hier kein Chaos verursacht; ansonsten bitte löschen. --[[Benutzer:Krikan|Krikan]] ([[Benutzer Diskussion:Krikan|Diskussion]]) 13:31, 6. Aug. 2014 (UTC)
::<hr />
:::Sieht doch schon ganz gut aus. Für eine direkte Einbindung auf der Kategorieseite ist die Tabelle meiner Ansicht nach eh zu groß, daher finde ich den von Dir gewählen Ansatz mit der eigenen Seite ganz gut.
:::In der Vorlage müsstest Du noch die Erläuterung zum "xx" überarbeiten (die führende Leerstelle macht das automatisch zu einem <nowiki><pre></nowiki>. Wenn Du die Hervorhebung willst, müsstest Du den Satz in <nowiki><code></code></nowiki> setzen.
:::Das Layout der Tabelle kann man ja auch jederzeit noch ändern.
:::Wenn Du noch Hilfe / Unterstützung brauchst, lass es mich wissen. --[[Benutzer:Ph1959de|Peter]] ([[Benutzer Diskussion:Ph1959de|Diskussion]]) 14:36, 6. Aug. 2014 (UTC)
:::<hr />
::::Mit dem Ergebnis bin ich nicht wirklich zufrieden. Aber bevor ich daran weiterarbeite, muss ich mehr zur Wiki-Bearbeitung lernen.
::::Danke für Deine bisherige Unterstützung und auch das Hilfsangebot. Werde sicherlich darauf zurückkommen. --[[Benutzer:Krikan|Krikan]] ([[Benutzer Diskussion:Krikan|Diskussion]]) 14:53, 6. Aug. 2014 (UTC)

== Vorlage Link2Forum ==
Hallo Peter, soll ich die Vorlage Link2Forum schon nutzen? Wenn ich es zeitlich morgen schaffe, wollte ich sowieso noch einige EnOcean Wiki-Seiten anfassen. Würde es dann schon mitändern. Oder kannst Du das automatisiert? Gruß, Christian --[[Benutzer:Krikan|Krikan]] ([[Benutzer Diskussion:Krikan|Diskussion]]) 19:32, 11. Aug. 2014 (UTC)
<hr />
:Hallo Christian, ich würde die Vorlage bisher nur für den sparsamen Einsatz (kannst sie gern in ein oder zwei Artikeln ausprobieren) empfehlen. Insbesondere innerhalb der "Infobox Modul" bin ich noch nicht ganz soweit - da tendiere ich eher noch dazu, das Link2Forum direkt aus der Infobox heraus einzusetzen. Das wäre dann nur eine Änderung, die hoffentlich alle bisherigen Einsatzstellen der Infobox erwischen würde (wobei, der Forenlink ist meines Wissens noch lange nicht überall drin; das habe ich ja erst kürzlich in die Infobox aufgenommen).
:Automatisieren kann ich leider nichts; mir ist (zumindest noch) nicht bewusst, dass wir hier die Möglichkeit haben, irgendwelche Bots einzusetzen. --[[Benutzer:Ph1959de|Peter]] ([[Benutzer Diskussion:Ph1959de|Diskussion]]) 21:32, 11. Aug. 2014 (UTC)
:<hr />
::Nutze bei EnOcean nur "Infobox Hardware" intensiv, dort brauche ich die Links nicht. Innerhalb der Wiki-Seiten verlinke ich häufiger auf einen bestimmeten Beitrag im Forum. Dort könnte ich schon umstellen auf <nowiki>{{Link2Forum|Topic=12345|Message=54321}}</nowiki>. Über die Vorlage "Infobox Modul" habe ich mir bei EnOcean noch keine Gedanken gemacht (Momentan grübel ich eher noch Einsatzbeispiele analog zur Vorlage EnOceanSubTypetable zusammenzufassen). --[[Benutzer:Krikan|Krikan]] ([[Benutzer Diskussion:Krikan|Diskussion]]) 22:04, 11. Aug. 2014 (UTC)
::<hr />
:::Wie gesagt, bitte noch "defensiv" benutzen, da ich noch keine umfangreicheren Tests gemacht habe. Daher bin ich aber natürlich auch an Rückmeldungen (die bitte dann auf der entsprechenden Diskussionsseite) zu der Vorlage interessiert (gibts Probleme, Änderungs-, Erweiterungswünsche und/oder -bedarf...?).
:::Ansonsten: Infobox Modul - dafür gäbe es bei EnOcean wohl nur genau eine Einsatzmöglichkeit, wenn ich das richtig sehe. Das könntest Du anlegen, wenn Du die Vorlage mal einsetzen möchtests. Oder gibt es weitere Module, die EnOcean implementieren? --[[Benutzer:Ph1959de|Peter]] ([[Benutzer Diskussion:Ph1959de|Diskussion]]) 05:06, 12. Aug. 2014 (UTC)

== Inhalt Hauptseite ==
Hallo Peter, folgende Idee/Vorschläge zur Wiki-Hauptseite:
Developers Corner: die dort direkt verlinkten Seiten sind -vorsichtig formuliert- nicht gerade die Aktuellsten; könnte man dort nicht besser gut gepflegte Seiten wie [[DevelopmentModuleIntro]] oder [[DevelopmentGuidelinesAV]] direkt verlinken? Außerdem ist das "Guter Startpunkt, sehr empfohlen!" unter "Wie fange ich an" meiner Meinung nach zu schwach. Ich denke das ist DIE Grundvoraussetzung für den ersten Überblick; hast Du auch unter [[Planung]] geschrieben. "Tipp der Woche" unter Ideen und Lösungen ist (war?) "nur" der "Tipp des Monats" und sollte dann auch so genannt werden. Wird anscheinend nur von soulman gepflegt. Wenn da nichts Aktuelles drin steht, wirkt das Wiki ziemlich tot. Andererseits habe ich persönlich auch keinen großen Antrieb dort etwas zu verfassen. Wer sucht dort wirklich?
Ich weis, kaum aktiv und schon Rumnörgeln... (Nicht wundern: Ich habe mich heute aber schon wieder darüber geärgert, dass immer mehr Blogs Fhem-Artikel mit typischen Wiki-Inhalt veröffentlichen statt dies hier zu tuen, wo ein zentraler Anlaufpunkt sein sollte. Wenn diese Blog-Artikel auch noch umständlich oder fehlerbehaftet sind, hat man keine Einfluß auf Korrekturen und der Kram ist im Umlauf. Dagegen sollten wir arbeiten.)--[[Benutzer:Krikan|Krikan]] ([[Benutzer Diskussion:Krikan|Diskussion]]) 15:22, 14. Aug. 2014 (UTC)
Auch <nowiki>[[Links|wichtige Fhem Links]]</nowiki> sind nicht gerade top-aktuell. Für wichtig halte ich die schon gar nicht. So, Frust weg ;-). Aber dennoch halte ich meine Anmerkungen für diskussionswürdig. Ich möchte auf der Hauptseite nicht eigenständig ändern, da mir nicht bekannt ist, ob das für Normal-Anwender erlaubt ist. --[[Benutzer:Krikan|Krikan]] ([[Benutzer Diskussion:Krikan|Diskussion]]) 18:31, 14. Aug. 2014 (UTC)
<hr />
:Christian, auch die Hauptseite kann von jedem bearbeitet werden - aber vorherige Diskussion ist da vielleicht nicht falsch. Ich habe daher Deine Anregungen mal auf die [[Diskussion:Hauptseite#Vorschläge zur Überarbeitung der Hauptseite|Diskussionsseite]] übertragen. Lass uns die Sache da weiterführen ... vielleicht beteiligt sich ja noch jemand... --[[Benutzer:Ph1959de|Peter]] ([[Benutzer Diskussion:Ph1959de|Diskussion]]) 05:41, 15. Aug. 2014 (UTC)
<hr />
::Ok, werde auch versuchen meine Anmerkungen passender zu platzieren. Hoffe nur, dass das dann nicht komplett untergeht. Habe aber teilweise keine Ahnung, wo das hin soll - bin noch zu Wiki-unerfahren. Aktuell bspw. [[Spezial:Gewünschte_Seiten]] enthält nach meiner Meinung eine Vielzahl von "Leichen", die weg können (FR und alles was damit zusammenhängt; Links durch STELLMOTOR). Ich habe da keine Ahnung, wo ich anfangen soll/darf. Ich würde beispielsweise bei [[STELLMOTOR]] die "toten" Lemmas/Seiten herausnehmen. Der Ersteller von STELLMOTOR könnte sie wieder reinnehmen, wenn er tatsächlich daran arbeiten will; traue mich aber nicht.
::'' ... vielleicht beteiligt sich ja noch jemand...'' Hoffnung stirbt zuletzt.... ;-) --[[Benutzer:Krikan|Krikan]] ([[Benutzer Diskussion:Krikan|Diskussion]]) 08:15, 15. Aug. 2014 (UTC)
::<hr />
:::* Ist schon ok, das hier zu plazieren ... aber außer mir findet das hier keiner, daher der "Umzug"
:::* "Gewünschte Seiten" ... enthält alle <nowiki>[[Lemma...]]</nowiki> Stellen, die auf nicht existierende Seiten verweisen. Wenn's so extrem vorkommt wie in Deinem genannten Beispiel, einfach den entsprechenden Benutzer anschreiben. Wirklich stören tut's aber auch nicht - du glaubst gar nicht, wie '''wenige''' Benutzer die "Gewünschte Seiten" Seite jemals gesehen haben, geschweige denn regelmäßig benutzen.
:::* Anfangen darfst Du sicherlich da, wo ein Eintrag in die "Gewünschten Seiten" offensichtlich versehentlich entstanden ist, z.B. weil jemand sich schlicht vertippt hat; wenn jemand schon mal eine Liste erstellt hat, welche Seiten noch gemacht werden müssen (wie ich z.B. auf meiner Benutzerseite :-) ), würde ich das erst mal ganz gelassen so stehen lassen.
:::* Und immer im Hinterkopf behalten, dass viele Benutzer hier im Wiki nur ganz gelegentlich unterwegs sind um vielleicht den einen oder anderen Tippfehler zu korrigieren - und das war's dann auch schon. Die meisten Benutzer bekommen nicht mal die Begrüßungshinweise mit ... und/oder lesen sie nicht, halten sich nicht dran, verstehen sie nicht...
:::Bottom line: nicht zu viel erwarten, Dich selbst nicht "aufreiben", aber fleißig weitermachen. --[[Benutzer:Ph1959de|Peter]] ([[Benutzer Diskussion:Ph1959de|Diskussion]]) 08:35, 15. Aug. 2014 (UTC)
:::<hr />
::::Bottom line: keine Sorge, reibe mich schon nicht auf. ''weiter'''machen''''': ich würde es grds. einfach machen, will aber niemanden vergraulen und den Admins unnötig Arbeit machen; hätte in STELLMOTOR die "toten" Lemmas in normale Aufzählung verwandelt, FR gelöscht (Leiche des Absturzes), kleinere Änderungen an Hauptseite vorgenommen oder... Rückgängig kann man (Admin/Ersteller) es immer noch machen; eigentlich ist es mir zu viel Diskussion, die mMn keinen weiterbringt, (wie lange soll man auf Entgegnungen warten?).....
::::Meine Bottom line: Keine Sorge Umstrukturierungen (Kategorien) o.ä. würde ich nicht undiskutiert vornehmen
:::::Nur teilweise Offtoic: Peter, wenn Du meine Verlinkung in der Homematic-Kategorie nicht OK findest, mach es einfach rückgängig: Für mich ist das in Ordnung, habe damit grds. kein Problem; gilt immer. Gruß, Christian (Habe da eh noch einen Tippfehler eingebaut!)

== WikiArtikel Pflege ==
Hallo Peter,
die "Verschieben" Option von Artikeln kannte ich in der Tat noch nicht. Danke für den Hinweis..
:Kein Problem & gern geschehen. --[[Benutzer:Ph1959de|Peter]] ([[Benutzer Diskussion:Ph1959de|Diskussion]]) 06:45, 29. Aug. 2014 (UTC)

Du kannst meine Wiki-Artikel gerne korrigieren und vereinheitlichen. Wenn du mir zusätzlich noch verrätst worauf du achtest, kann ich versuchen diese Dinge gleich selbst zu beachten.
:<hr />
:Lässt sich so generell nicht beantworten; manchmal nur Kleinigkeiten. Beispiele:
:* Artikel in Ich-Form schreibe ich normalerweise auf neutrale Ausdrucksweise um (später weiß ohnehin niemand mehr, wer der "Ich" war); das ist verbindlicher und mMn für technische Beschreibungen angemessener.
:* Querverweise (Links auf andere Artikel) einfügen - auch IN anderen Artikeln wo sinnvoll Verweise auf Deinen neuen Artikel setzen (sonst entstehen "Waisen" und "Sackgassen"); ob es schon Links auf Deine Seite gibt, kannst Du über das "Links auf diese Seite" (links in der Navigationsleiste) herausfinden.
:* Rechtschreibung / Grammatik / Formulierung... ist eigentlich immer dabei
:* usw.
:-- [[Benutzer:Ph1959de|Peter]] ([[Benutzer Diskussion:Ph1959de|Diskussion]]) 06:45, 29. Aug. 2014 (UTC) <hr />

Nochetwas: ich vermisse eine Kategorie für selbst gebaute Schaltungen. Ich bin mir immer unsicher wo ich meine Artikel einstellen soll. ZurZeit sind 1wire-Schaltungen bei 1wire. Aber für Panstamps und Arduino basierte Schaltungen habe ich nichts gefunden. Kannst du helfen?
:<hr />
:Es bei Hardware die Unterkategorie "Other Components", da passt sowas derzeit immer rein. Sofern mal eine "kritische Masse" erreicht ist (also mehr als nur ein oder zwei Artikel), kann man ja überlegen, mal eine Unterkategorie "Eigenentwicklungen" (oder ähnlich) bei Hardware einzufügen.
:Für Arduino gibt es schon eine Kategorie (Unterkategorie von Hardware), für Panstamp könnte man sowas auch einrichten - wenn es vom Konzept her passt (dazu verstehe ich von der Arduino/Panstamp...-Welt zu wenig). Es sollten halt immer ähnliche Dinge in einer Kategorie/Unterkategorie... zusammengefasst sein.
:-- [[Benutzer:Ph1959de|Peter]] ([[Benutzer Diskussion:Ph1959de|Diskussion]]) 06:45, 29. Aug. 2014 (UTC) <hr />
::Misch mich mal ein: Fände Kategorie Eigenentwicklungen o.ä. nicht schlecht, da bestimmte Zielgruppe angesprochen wird. Ich lasse bspw. meine Finger davon. Würde den Artikel trotzdem zusätzlich noch in Other Components aufnehmen oder wenn es 1-wire ist auf jeden Fall in 1-Wire. Bei Homematic haben wir doch Unterkategorie HomeBrew, analog auch bei anderen anlegen!? Wir sollten etwas angehen....--[[Benutzer:Krikan|Krikan]] ([[Benutzer Diskussion:Krikan|Diskussion]]) 08:18, 29. Aug. 2014 (UTC) <hr />
:::Ok, dann machen wir doch einfach einen Auftrag an Tobias daraus: mal sammeln, welche Artikel schon vorliegen (oder er in Planung hat) für eine solche Kategorie, dann schauen wir kurz drüber und beschließen, welche neuen Unterkategorien und wie einsortiert...
:::@Tobias: ich stell das mal so auf Deine Diskussionsseite --[[Benutzer:Ph1959de|Peter]] ([[Benutzer Diskussion:Ph1959de|Diskussion]]) 08:48, 29. Aug. 2014 (UTC) <hr />

GRuss
Tobias

== Verschieben von Wiki-Seiten ohne Weiterleitung ==

Hallo Peter,
könntest Du bitte
* [[Z-Wave-EVR_ST814-Temperatur-_und_Feuchtesensor]] auf Z-Wave-EVR_ST81'''4'''-Temperatur-_und_Feuchtesensor ohne Weiterleitung verschieben. Der Ersteller [[Benutzer_Diskussion:Morgennebel]] ist anscheinend nicht mehr aktiv; reagiert auch nicht auf PM.
: -> Erledigt --[[Benutzer:Ph1959de|Peter]] ([[Benutzer Diskussion:Ph1959de|Diskussion]]) 12:31, 27. Dez. 2014 (UTC)
* hier [[Diskussion:WS3600]] mal reinschauen. Dort hätte ich auch gerne eine Wiki Seite verschoben. Keine Ahnung, ob Dir das aufgefallen ist.
: -> Ja, hatte ich gesehen ... und jetzt auch erledigt --[[Benutzer:Ph1959de|Peter]] ([[Benutzer Diskussion:Ph1959de|Diskussion]]) 12:31, 27. Dez. 2014 (UTC)
* WebIO_Digital auf WEBIO_12DIGITAL verschieben --[[Benutzer:Krikan|Christian]] ([[Benutzer Diskussion:Krikan|Diskussion]]) 17:36, 7. Dez. 2015 (CET)
: -> Erledigt --[[Benutzer:Ph1959de|Peter]] ([[Benutzer Diskussion:Ph1959de|Diskussion]]) 17:52, 7. Dez. 2015 (CET)

== Nutzung von <nowiki><pre style="width:500px;"></nowiki> statt <nowiki><code></nowiki> ==

Hallo Peter,<BR>
Du ersetzt teilweise in den Wikiseiten die Formatierung <nowiki><code></nowiki> durch <nowiki><pre style="width:500px;"></nowiki>. Hat das einen bestimmten Grund? Das führt nämlich dazu, dass der Text in einigen Fällen über den Boxrand geht. Mir ist nicht klar, wie ich das umsetzen/anwenden soll. Danke. --[[Benutzer:Krikan|Christian]] ([[Benutzer Diskussion:Krikan|Diskussion]]) 07:28, 5. Feb. 2015 (UTC)

:Hallo Christian, das mache ich (dachte ich) eigentlich nur, wenn die Zeilen in dem pre-Bereich durchweg relativ kurz sind. Was ich eigentlich häufiger mache, ist, pre durch code Tags zu ersetzen, gerade weil bei code ein automatischer Zeilenumbruch stattfindet. Insbesondere Einzeiler, die per nowiki, pre oder Leerzeichen in Spalte1 dann als Box formatiert werden ersetze ich gern duch <nowiki>:<code>define, attr, ...</code></nowiki>, weil's meiner Ansicht nach einfach flüssiger lesbar ist Gesamtkontext.
:Verhalte ich mich am Ende anders, als ich es in [[FHEMWiki:Über_FHEMWiki#Gewünschtes Verhalten / "Do and Don't"|diesem Abschnitt]] beschrieben habe? --[[Benutzer:Ph1959de|Peter]] ([[Benutzer Diskussion:Ph1959de|Diskussion]]) 07:45, 5. Feb. 2015 (UTC)
::Werde es beobachten. Vielleicht bin ich auch nur übermüdet/unkonzentriert: Habe nämlich gerade gesehen, dass ich [[HM-OU-CFM-Pl_MP3_Funk-Gong_mit_Signalleuchte|hier]] -was letztliche Anstoß zum Schreiben war- falsch geschaut habe. Die anderen Beispiele, die ich in Erinnerung habe, müsste ich mir noch einmal raussuchen. Vielleicht habe ich da auch schief geschaut. Also bitte erst einmal vergessen. Gruß, --[[Benutzer:Krikan|Christian]] ([[Benutzer Diskussion:Krikan|Diskussion]]) 08:18, 5. Feb. 2015 (UTC) PS: Schaust Du bitte mit auf die diversen Unterkategorien zu "Hardware Typen" die ich angelegt habe und greifst bitte ggfs. korrigiernd ein.
:::Die neuen Unterkategorien habe ich schon zur Kenntnis genommen. Nachdem Du die letzten Änderungen an der Kategoriestruktur gemacht hast, kennst Du Dich da mittlerweile ja mindestens so gut aus wie ich. Das Einzige, was mir aufgefallen ist: auf den Kategorieseiten könnten noch ein paar kurze Worte zur Beschreibung der Kategorie eingefügt werden... aber das eilt nicht. --[[Benutzer:Ph1959de|Peter]] ([[Benutzer Diskussion:Ph1959de|Diskussion]]) 08:26, 5. Feb. 2015 (UTC)

== PGM3 - Entwicklungsstand ==
Hallo Peter!
Habe heute bei PGM3 und PGM5 recht selbstsicher einen Hinweis "seit längerem nicht aktiv weiterentwickelt" hinzugefügt. Im Forum habe ich nichts gefunden und auch zu Google-Groups-Zeiten kann ich mich nicht wirklich erinnern. Bei der Nachkontrolle habe ich dann mit Erschrecken festgestellt, dass Du PGM3 auf der ToDo-Liste stehen hast und das plötzlich Martin Hass' PGM3 Screenshot-Seiten nach einer gefühlten Ewigkeit wieder erreichbar sind. Irre ich mich und PGM3 ist doch noch ein (aktuelles) Thema? Gruß, [[Benutzer:Krikan|Christian]] ([[Benutzer Diskussion:Krikan|Diskussion]]) 21:09, 18. Feb. 2015 (CET)
<hr />
:Christian, PGM3 auf meiner Todo-Liste ... eine Jugendsünde :-) ... fliegt gleich runter, weil bestimmt zwei Jahre alt und nie was gemacht. Die Updates auf Martin's Seiten solltest Du natürlich beobachten, aber auf mich musst Du keine Rücksicht nehmen. --[[Benutzer:Ph1959de|Peter]] ([[Benutzer Diskussion:Ph1959de|Diskussion]]) 06:55, 19. Feb. 2015 (CET)

== Begrüßungsseite Link: Was Wikipedia nicht ist ==
Hallo Peter,
ich hoffe, dass ich das hier jetzt richtig mache :-). Beim aufmerksamen Lesen der Begrüßungseite bin ich gleich auf einen Link: Was_Wikipedia_nicht_ist getappst.

Den kennt Wikipedia nicht...
Gruß Otto
<hr />
:Hallo Otto, danke für's aufmerksame Lesen :-)
:habe den (und einen weiteren) fehlerhaften Link korrigiert. Da die Vorlage mit "subst:" eingebunden wird, profitieren leider nur die Neuankömmlinge ab jetzt davon.
:Grund für das Problem ist wohl die Art, wie das Fhem-Wiki aufgesetzt wurde (bin mir aber jetzt nicht sicher, ob sich da in dieser Hinsicht nochmal was geändert hat, oder ob ich die beiden Links schlicht vergessen habe ... andere Links, wie z.B. den auf das Tutorial, habe ich vor längerer Zeit schon mal umgestellt). --[[Benutzer:Ph1959de|Peter]] ([[Benutzer Diskussion:Ph1959de|Diskussion]]) 06:57, 2. Apr. 2015 (CEST)

== Pflege von [[Spezial:Gewünschte_Seiten]] ==
Hallo Peter,
bin gerade im Aufräumfieber und über die gewünschten Seiten gestolpert. Einige Dinge habe ich eigenständig geklärt, aber nun benötige ich Deine Hilfe. Insbesondere das zum Aussterben verurteilte FS20 taucht dort sehr umfangreich auf. Die abnehmende Bedeutung spricht aus meiner Sicht dafür, diese "gewünschten Seiten" dort herauszunehmen. Denke es gibt wichtigere Baustellen und dringendere notwendige Seiten. Zudem sind das teilweise Karteileichen, die seit Urzeiten dort geführt werden. Aus meiner Sicht schreckt das, neben den Wiki-Softwareproblemen, Interessenten von der Mitarbeit ab. Darum bitte ich Dich um Deine Meinung als FS20-User, bevor ich das weiter anleiere. Andere Punkte, die ich nicht '''''<- meinst Du wirklich *nicht*?''''' ''<-ergänze: allein/eigenständig!'' klären wollte, betreffen bspw. die gewünschte Seite "Hilfe:Seite bearbeiten", "FHEMWiki:Stubs entfernen". Schöne Feiertage, [[Benutzer:Krikan|Christian]] ([[Benutzer Diskussion:Krikan|Diskussion]])
:Hallo Christian, nur als schnelle Antwort (zu viele Baustellen gerade):
:* Gewünschte Seiten, speziell FS20: das was Mediawiki in die "gewünschten Seiten" einsortiert, sind die intra-Wiki Links, die nicht existieren also <nowiki>[[Existiert nicht]]</nowiki> würde da z.B. auftauchen - gewünschte Seiten im eigentlichen Sinn sind das nur dann, wenn der Verlinkung absichtlich gemacht wurde ... wie z.B. bei den vielen FS20 Seiten. Die sind nämlich häufig bei mir (hast Du doch bestimmt gesehen ;-) ), weil ich noch zu diversen FS20 Geräten was schreiben möchte und sollte. Leider (die vielen Baustellen, siehe oben) komme ich derzeit und schon lange nicht dazu. Ansonsten habe ich da immer mal wieder reingeschaut, um falsch geschriebene Links aufzuspüren und zu bereinigen. Aber vielleicht sollten wir den Link darauf einfach von der Hauptseite entfernen und z.B. auf die/eine Interna Seite holen. Vielleicht als Ersatz / Nachfolger der Randnotiz von der Über FHEMWiki Seite, auf der ich die offenen Baustellen mal aufgelistet hatte (und schon länger nicht mehr gepflegt).
::* Natürlich habe ich gesehen, dass FS20 (auch) von Dir kommt; darum habe ich mich auch mit Wiki-Eingriffen zurückgehalten, sonst.. ;-). Dein Alternativvorschlag ist gut. Die offenen Baustellen auf der Über FHEMWiki Seite: Zu den Kategorien wollte ich -auch seit langem- eine bessere "Anweisung" an die anderen Wikibearbeiter schreiben und dann abschließen. Und mich dann wieder verstärkt "meinen" eigentlichen Themen ZWave/EnO widmen.
:* Die Stubs-Seite / Kategorie / Vorlage kommt von Arno (akw), ist aber schon lange nicht mehr gepflegt worden und wird wohl auch nicht mehr aktiv genutzt
:* '''Hilfe:Seite bearbeiten''' fällt wohl in die Kategorie "Wiki-Softwareprobleme" (Du meinst den Link "Bearbeitungshilfe" neben den {{Taste|Speichern}} {{Taste|Vorschau zeigen}} Buttons?) und würde ich erst wieder aktiv in Angriff nehmen, wenn Arno die offenen Probleme komplett abgearbeitet hat :-(
::* Ja, werde mal Arno bitten.... [[Benutzer:Krikan|Christian]] ([[Benutzer Diskussion:Krikan|Diskussion]])
:Ebenfalls schöne Feiertage, --[[Benutzer:Ph1959de|Peter]] ([[Benutzer Diskussion:Ph1959de|Diskussion]]) 15:21, 3. Apr. 2015 (CEST)

== Vorlagen: Link2Forum,.. ==
Hallo Peter,
ist die Notwendigkeit der Vorlagen "Link2Forum",.. nur darin begründet, dass man dann einfacher Anpassungen bei Änderungen der zugrundeliegenden Links vornehmen kann? Ich stelle nämlich immer wieder fest, dass außer uns beiden, die sowieso von (fast) keinem Wiki-Bearbeiter genutzt werden. Der Umstellungsaufwand im Änderungsfalle wird so vermutlich nicht sehr reduziert. Kann man dieses Problem der Linkänderungen nicht einfacher mit einem Bot lösen, der das Wiki mit Suchen/Ersetzen durchgeht? Dann hättest Du auch nicht den Pflegeaufwand für die Vorlagen. Gruß, --[[Benutzer:Krikan|Christian]] ([[Benutzer Diskussion:Krikan|Diskussion]]) 11:16, 13. Aug. 2015 (CEST)
<hr>
:Hallo Christian, leider habe ich keine große Hoffnung, dass wir hier einmal die Chance haben werden, '''bot'''s einzusetzen und kenne mich damit auch (zumindest noch) nicht aus (Ausreden? Vielleicht).
:Interessant: ich habe gerade die DocLink Vorlage mal soweit fertig, dass man zumindest die ELV Links überarbeiten / generalisieren kann.
:Unterm Strich: ich werde die Vorlagen weiter pflegen und benutzen, wer sie benutzen mag soll's tun, zwingen werd ich niemanden. Wir haben halt immer noch sehr wenige Wiki-erfahrene Benutzer hier, was man auch an anderen Stellen merkt. --[[Benutzer:Ph1959de|Peter]] ([[Benutzer Diskussion:Ph1959de|Diskussion]]) 11:50, 13. Aug. 2015 (CEST)
<hr>
:: Hallo Peter, will Dich auch nicht abhalten ;-) , sondern entlasten. Weil ich die DocLink-Vorlage gesehen habe, kam ich auf das Thema. Ich werde das bot-Thema mal auf meinen "Wunschzettel" aufnehmen und aktiv verfolgen. Schauen wir einmal, was sich ergibt. Gruß, --[[Benutzer:Krikan|Christian]] ([[Benutzer Diskussion:Krikan|Diskussion]]) 12:04, 13. Aug. 2015 (CEST)
::<hr>
:::Kein Problem - ich denke es gibt bei beiden Vorgehensweisen Vor- und Nachteile. Meine Skepsis beruht darauf, dass die Bots ja wohl auf dem Wiki-Server laufen und ich kaum Hoffnung habe, da mehr Zugriff zu bekommen. --[[Benutzer:Ph1959de|Peter]] ([[Benutzer Diskussion:Ph1959de|Diskussion]]) 12:16, 13. Aug. 2015 (CEST)
== Codierung ==
Hallo Peter,

Du schreibst auf meiner Benutzerseite
HTML-Tags bitte nur verwenden, wenn es nicht anders geht
im Artikel
[[EnOcean-D-452-FU-EP-JR-Aktor-Beschattungselemente-Rollladen]]
hast Du die Codierung mittels Leerzeichen durch <nowiki><code></Code></nowiki> ersetzt. Die Leerzeichen waren aber in [[http://www.fhemwiki.de/wiki/FHEMWiki:%C3%9Cber_FHEMWiki#Gewünschtes Verhalten / "Do and Don't"]] explizit erlaubt.
Einen anderen Artikel von mir hast Du nicht korrigert.
Wo liegt mein Fehler? Ich wollte der Gemeinschaft gerne etwas zurück geben - vor allem für die Arbeit die Christian mit mir gehabt hat.

--[[Benutzer:BenMarloe|BenMarloe]] ([[Benutzer Diskussion:BenMarloe|Diskussion]]) 00:25, 21. Aug. 2015 (CEST)
<hr />
:Hallo Ben(Marloe), das ist schnell erklärt:
:HTML-Tags nur verwenden - bezieht sich, wenn ich das jemandem schreibe, meist auf exzessive <nowiki><br></nowiki>-Tags. Da kann (sollte) im Wiki meistens einfach eine Leerzeile oder ein Zeilenumbruch verwendet werden (einfach die "Vorschau-funktion" verwenden, um zu kontrollieren, ob's "richtig" aussieht). Außerdem sieht der Wiki-Quelltext damit schon dem formatierten Ergebnis ähnlicher und ist einfacher lesbar. Nur bei manchen Vorlagen oder z.B. in Aufzählungen ist ein Zeilenumbruch "kontraproduktiv" und dann ist ein br nötig.
:Leerzeichen vs. code ... am besten veranschaulicht:
Leerzeichen in Position 1
:... und der weitere Text. Im Vergleich dazu:
::<code>ein (eingerückter) Einzeiler, der als Code formatiert werden soll</code>
:oder noch mal anders:
Leerzeichen und ganz viel, ganz viel, ganz viel, ganz viel, ganz viel, ganz viel, ganz viel, ganz viel, ganz viel, ganz viel, ganz viel, ganz viel, ganz viel, ganz viel, ganz viel, ganz viel, ganz viel Text
::<code>ganz viel, ganz viel, ganz viel, ganz viel, ganz viel, ganz viel, ganz viel, ganz viel, ganz viel, ganz viel, ganz viel, ganz viel, ganz viel, ganz viel, ganz viel, ganz viel, ganz viel Text, der als Code formatiert werden soll</code>
:Ich hoffe, der Unterschied wird damit klar: der Text wird meiner Ansicht nach kompakter, die Hervorhebung ist aber trotzdem da. Und: bei Mehrzeilern sieht das schon wieder ganz anders aus. Da ist aber meistens dann die Verwendung von <nowiki><pre></pre></nowiki> die bessere Wahl, weil damit (im Wiki Source Text) besser verdeutlicht wird, dass die Formatierung absichtlich so gewählt ist.
:Zum Thema ''Einen anderen Artikel von mir hast Du nicht korrigert'' ... ich kann nicht überall sein :-) ... nein, ohne Scherz, ich mache das hier auch "nur nebenbei", manches ist Geschmackssache, manches übersehe ich, manches ist "zu unwichtig", etc.
:Und ''Wo liegt mein Fehler?'' - nirgends; einfach fleissig weiter mitmachen.
:--[[Benutzer:Ph1959de|Peter]] ([[Benutzer Diskussion:Ph1959de|Diskussion]]) 07:14, 21. Aug. 2015 (CEST)

== Neue Seite oder Ergänzung [erledigt]==
Mit Eurer Hilfe geht jetzt der EnOcean-FUD61NPN-Funk-Universal-Dimmaktor unidirektional bei mir.
Ich würde eine Anleitung erstellen, bin mir aber nicht sicher, ob ich das lieber als
# Ergänzung auf die existente Seite oder
# Kommentare auf die existente Seite mache oder
# eine neue Seite aufmache und wie die dann heißen soll.
Ich bitte um Vorschläge/Richtlinien<br>
--[[Benutzer:BenMarloe|BenMarloe]] ([[Benutzer Diskussion:BenMarloe|Diskussion]]) 16:48, 11. Sep. 2015 (CEST)
<hr />
:Ich denke, das kommt auf Art und Umfang der Änderungen/Ergänzungen an. Wenn das ein einzelner Abschnitt mit den Unterschieden ist, passt das sicherlich gut in [[EnOcean-FUD61NPN-Funk-Universal-Dimmaktor]], wären es Kommentare, überall auf der Seite verstreut, würde ich eine eigene Seite bevorzugen (dann bitte an den Seitennamen " (unidirektional)" anhängen). Die Kommentarseite ist für sowas eher nicht geeignet.
:Wenn's eine neue Seite wird, dann bitte auf der Seite des bidirektionalen Aktors verlinken. In jedem Fall die Bemerkung über *direktional... anpassen. --[[Benutzer:Ph1959de|Peter]] ([[Benutzer Diskussion:Ph1959de|Diskussion]]) 16:10, 12. Sep. 2015 (CEST)
<hr>
::so wird's gemacht. --[[Benutzer:BenMarloe|BenMarloe]] ([[Benutzer Diskussion:BenMarloe|Diskussion]]) 22:02, 18. Sep. 2015 (CEST)
==Extension SyntaxHighlight_GeSHi==
Ich hätte die [https://www.mediawiki.org/wiki/Extension:SyntaxHighlight_GeSHi Extension] gerne, um Code besser lesbar darzustellen. Sollte eigentlich ab MediaWiki Version 1.21 dabei sein, aber eventuell ist sie nicht aktiviert? Wen muss ich dazu anbetteln? ;)
--[[Benutzer:Drhirn|Drhirn]] ([[Benutzer Diskussion:Drhirn|Diskussion]]) 15:58, 1. Okt. 2015 (CEST)
:[[Benutzer Diskussion:Akw#Wiki-Erweiterung Syntaxhighlight|Hier]] mal nachhaken? --[[Benutzer:Ph1959de|Peter]] ([[Benutzer Diskussion:Ph1959de|Diskussion]]) 18:57, 1. Okt. 2015 (CEST)
::Hat, wie ich gerade sehe, schon jemand anderer übernommen :) --[[Benutzer:Drhirn|Drhirn]] ([[Benutzer Diskussion:Drhirn|Diskussion]]) 10:26, 5. Okt. 2015 (CEST)
::<hr />
:::Nicht verzagen ... jede Stimme zählt :-) --[[Benutzer:Ph1959de|Peter]] ([[Benutzer Diskussion:Ph1959de|Diskussion]]) 16:36, 5. Okt. 2015 (CEST)

== Vorlage "Hinweis" ==
Hallo Peter,
hast Du Dir die neue Vorlage "Hinweis" einmal angeschaut? Gibt es Vorbehalte von Deiner Seite oder kann ich die problemlos nutzen. Habe die Vorlage testweise mal in 2 Seiten eingebaut und finde sie in gewissen Situationen grds. nicht schlecht.
Gruß, --[[Benutzer:Krikan|Christian]] ([[Benutzer Diskussion:Krikan|Diskussion]]) 22:45, 6. Okt. 2015 (CEST)
<hr />
:Hallo Christian, ja, die Vorlage habe ich gesehen und mal kurz reingeschaut. Gibts von meiner Seite keine Einwände (den Kommentar "Randnotiz ... leider nur Teil der Bildschirmbreite..." finde ich etwas befremdlich, da der Name der Vorlage ja genau das verspricht, aber das tut ja der eigentlichen Sache keinen Abbruch) - ich denke, es gibt für die Vorlage sinnvolle Einsatzgebiete, ganz nach gewünschtem Effekt / Erscheinungsbild. Es unterbricht halt den Lesefluss deutlich stärker als die Randnotiz, aber wenn das gewünscht ist, dann passts ja. --[[Benutzer:Ph1959de|Peter]] ([[Benutzer Diskussion:Ph1959de|Diskussion]]) 10:14, 7. Okt. 2015 (CEST)
<hr />
::Sollten wir die Vorlage dann nicht auch [[FHEMWiki:%C3%9Cber_FHEMWiki#Vorlagen|hier]] aufnehmen? Falls ja, Du oder ich? Gruß, --[[Benutzer:Krikan|Christian]] ([[Benutzer Diskussion:Krikan|Diskussion]]) 10:30, 7. Okt. 2015 (CEST)
<hr/>
::Naja, "befremdlich" ;). Ich wollte nur erklären, warum ich extra eine neue Vorlage gemacht habe. Ich hätte natürlich auch die Vorlage "Randnotiz" um eine Option für die Breitenauswahl erweitern können. Grundsätzlich hätte die Randnotiz nämlich eh getan, was ich wollte. Aber das wäre etwas viel Arbeit geworden. --[[Benutzer:Drhirn|Drhirn]] ([[Benutzer Diskussion:Drhirn|Diskussion]]) 11:25, 23. Okt. 2015 (CEST)

== Änderung von Gliederungspunkten in Artikeln und wiki-interne Links ==
Hallo Peter,
hier [[Konfiguration]] wurde gestern ein Gliederungspunkt umbenannt. Gibt es/ Kennst Du eine einfache Möglichkeit herauszufinden, welche wiki-internen Link jetzt nicht mehr funktionieren? Bei den Spezial-Seiten finde ich dazu nichts und Google hilft mir auch nicht. Die Wiki-interne Suche ist dabei auch nicht optimal. Bisher vermeide ich aus diesem Grund auch eine Umbenennung von Gliederungspunkt. Danke und Gruß --[[Benutzer:Krikan|Christian]] ([[Benutzer Diskussion:Krikan|Diskussion]]) 09:48, 26. Okt. 2015 (CET)
<hr />
:Hallo Christian,
:ich hatte die Änderung zwar kurz angeschaut, aber gar nicht an diese (möglichen) Auswirkungen gedacht. Habe (auf die Schnelle) auch nur wenig zu diesem Thema gefunden (ausser vielleicht diese Seite in [https://en.wikipedia.org/wiki/Wikipedia:Database_reports/Broken_section_anchors/Configuration Wikipedia]).
:Vermutlich (hoffentlich?) werden wir aber nicht allzu häufig von dieser Problematik betroffen sein, für diesen aktuellen Fall sehe ich folgende mögliche Vorgehensweisen:
:* Änderung der Überschrift zurücknehmen, dafür diesen Abschnitt eine Gliederungsebene tiefer (passt dann ohnehin besser in die Seitenstruktur)
:* Verwendung von <nowiki>{{Anker|Ankertext}}</nowiki> mit der alten Überschrift, um das als zusätzlichen Anker einzufügen
:--[[Benutzer:Ph1959de|Peter]] ([[Benutzer Diskussion:Ph1959de|Diskussion]]) 11:25, 26. Okt. 2015 (CET)
<hr />
::Hallo Peter,
::habe es mit 1. Ansatz umgesetzt, da mir der 2. Weg zu umständlich und (später) fehleranfällig erscheint. Obwohl ich irgendwann mal gelernt habe, dass es niemals nur einen Gliederungs-Unterpunkt gibt (halte ich hier aber auch nicht immer ein ;-) )
::Gruß, --[[Benutzer:Krikan|Christian]] ([[Benutzer Diskussion:Krikan|Diskussion]]) 13:33, 26. Okt. 2015 (CET)

== Neuen Artikel verschieben/umbenenen ==
Hallo Peter,

ich habe meinen ersten Artikel erstellt und würde gerne den nächsten Schritt machen. Wohin muß ich verschieben und wie gehts dann weiter. (Wiki Anfänger)

Gruß [[Benutzer:Eisix|Eisix]] ([[Benutzer Diskussion:Eisix|Diskussion]]) 16:14, 25. Jan. 2016 (CET)
<hr />
:Hallo Eisix,
:# es wäre nicht nötig gewesen, den Artikel erst auf Deiner Benutzerseite zu erstellen; so viel ist hier nicht los, dass bei einem neuen Artikel gleich Konflikte entstehen; ich glaube, nur "verschieben" geht in diesem Fall nicht so gut, daher würde ich vorschlagen:
:# Du gehst auf deiner Benutzerseite auf "Bearbeiten" und
:# fügst <nowiki>[[EnOcean MwC-32...]]</nowiki> (die Details für die Namensfindung stehen auf der Kategorieseite [[:Kategorie:EnOcean Components]] oben rechts (ich glaube, "Deinen" Namen musst Du da noch etwas nachbearbeiten; im Zweifel [[Benutzer Diskussion:Krikan|Krikan]] fragen)) ein
:# Klickst auf {{Taste|Vorschau zeigen}}; daraufhin bekommst Du Deinen gewählten Seitentitel in rot in der Vorschau angezeigt; jetzt
:# öffnest Du diese "rote Seite" in einem neuen Browser-Tab
:# kopierst bzw. verschiebst den Quelltext Deiner Seite (ohne die gerade eingefügte Zeile) in das leere Editierfenster des zweiten Browser-Tabs
:# Dann noch ein paar Korrekturen (z.B. die korrekte Kategorie "EnOcean Components" verwenden); und schau Dir existierende (EnOcean-)Seiten (Gliederung!) an und übernimm das bitte entsprechend
:# Vorschau der neuen Seite anzeigen und überprüfen
:# wenn alles soweit stimmt, "Seite speichern"
:# Auf Deiner Benutzerseite kannst Du jetzt (z.B.) die Seite in (D)eine Liste der von Dir erstellten Seiten aufnehmen ... und evtl. noch ein paar Worte über Dich schreiben
:--[[Benutzer:Ph1959de|Peter]] ([[Benutzer Diskussion:Ph1959de|Diskussion]]) 18:18, 25. Jan. 2016 (CET)
<hr />
: Hallo Eisix, Hallo Peter!
: Mische mich hier mal ein: Sind die Bildrechte für BSC-MwC-32.jpeg geklärt? Falls nein, bitte Bild nicht einbinden/löschen und gegebenenfalls eigenes Foto hochladen.
: Gruß, --[[Benutzer:Krikan|Christian]] ([[Benutzer Diskussion:Krikan|Diskussion]]) 19:06, 25. Jan. 2016 (CET)
<hr />
: Hallo,
: @Peter ich wollte nicht wie ein Elefant im Porzellanladen durch die Wiki stapfen, dafür kenne ich mich damit zu wenig aus ;-)
: @Krikan guter Einwand das Bild ist von www.enocean-alliance.org wo auch die verlinkte Anleitung her ist. Eigenes Bild ist leider nicht mehr möglich da das ganze hinter einem Aquarium verbaut ist und nur mit größerem Aufwand wieder rauszuholen ist. Also nehme ich das Bild am besten wieder raus !?
:Gruß --[[Benutzer:Eisix|Eisix]] ([[Benutzer Diskussion:Eisix|Diskussion]]) 10:19, 26. Jan. 2016 (CET)

== Unterscheidung Code für DEF und .cfg ==

Hallo Peter!<BR>
habe gelesen, dass Du auf [[Ölverbrauchsanzeige_/_Betriebsstundenzähler]] den Code als .cfg-Code per Hinweis markiert hast. Bisher haben wir bei der Unterscheidung DEF,Einzeiler, aus optischen Gründen umgebrochenen Einzeiler und .cfg Code im Wiki kein wirkliches System. Es bedarf jeweils der Interpretation. Vieles ist derzeit cfg.-Code. Eigentlich wünsche ich mir, dass wir überall einen Hinweis in den Codeboxen DEF bzw. cfg einpflegen. Das dürfte aber praktisch nicht umsetzbar sein und auch hohes Fehlerpotenzial haben. Hatte auch schon einmal einen Versuch in die Richtung unternommen, aber aufgegeben.<BR>
Momentan tendiere ich dazu, auf [[Konfiguration]] einen Erläuterung einzufügen, woran man die verschiedenen Code-Varianten erkennt und die Seite -wie Du es mal geplant hattest, von allen anderen Seiten zu verlinken. Das ist mMn einfacher. Hast Du dazu eine Meinung/Idee?<BR>
Würde das auf ggfs. auf meine Todo-Liste setzen.<BR>
Gruß, --[[Benutzer:Krikan|Christian]] ([[Benutzer Diskussion:Krikan|Diskussion]]) 10:10, 16. Feb. 2016 (CET)
<hr />
:Hallo Christian, ja, so eine grundlegende Vorgehensweise fehlt uns da noch. War mir auch bewusst, ich wollte aber in diesem konkreten Fall gleich was eintragen, weil das fehlende Wissen zu diesem Thema der Auslöser für den Forenthread war. Ich behalte das Thema auch im Hinterkopf - die zündende Idee, wie man das am besten umsetzen kann fehlt mir aber leider noch. Wer immer von uns früher dazu kommt, hat gewonnen :-) --[[Benutzer:Ph1959de|Peter]] ([[Benutzer Diskussion:Ph1959de|Diskussion]]) 12:28, 16. Feb. 2016 (CET)

==Nochmal Begrüßungsseite==
Hallo Peter,

Mein Benutzerkonto wurde gerade freigeschaltet und ich habe mich gewundert, warum die Begrüßungsseite so "wikipedistisch" ist. Sollten wir da nicht mal rangehen und eine Benutzerbegrüßung schreiben, die an das fhemwiki angepasst ist?

Ein paar Grundlagen wie Bearbeitungshilfe würde ich auch aus Wikipedia einbinden, aber die Infoseite "was Wikipedia nicht ist" scheint mir irgendwie hier deplatziert...

Ich würde mich dransetzen, aber brauche dann wahrscheinlich Hinweise, wo hier im fhemwiki die "Richtlinien" und andere Infos stecken, die man in der Willkommensnachricht verlinken könnte/sollte.

Gruß, Markus --[[Benutzer:Krokofant|Krokofant]] ([[Benutzer Diskussion:Krokofant|Diskussion]]) 11:31, 5. Mär. 2016 (CET)
<hr />
:Hallo Markus, die Begrüßungs-Vorlage ist einfach aus der Situation heraus mal entstanden. Es gab viele Neuanmeldungen von Leuten, die noch keinerlei Berührung mit Wiki(media) hatten und entsprechend gedankenlos ans Werk gegangen sind. War dann nachher mehr Aufräumarbeit nötig als dass die Mitarbeit Hilfe gewesen wäre. Dazu sind ein paar Hinweise auf Fhem-Wiki-Spezifika eingeflossen ... aber ''gelesen'' wird das Ganze leider ohnehin höchst selten, wenn man manche Beiräge hier so sieht.
:Aber lass Dich nicht entmutigen, Vorschläge und aktive Mitarbeit sind natürlich herzlich willkommen.
:Fhem-spezifische Informationen sind eigentlich komplett in Über FHEMWiki gesammelt bzw. über diese Seite zu erreichen. Wenn Du Dir die Änderungshistorie der Seite anschaust, wirst Du auch feststellen, dass das eine One-(oder Two, Krikan hilft auch mit)-Man-Show ist - von einigen "kurzen Strohfeuern" mal abgesehen. --[[Benutzer:Ph1959de|Peter]] ([[Benutzer Diskussion:Ph1959de|Diskussion]]) 12:02, 5. Mär. 2016 (CET)

== Vorlage:News und Interwiki-Links ==

Hallo Peter,

danke für die Einrichtung meines Logons.
# ich habe mir mal erlaubt die [[Vorlage:News]] zu Dokumentieren und dabei die Orientierung der ersten Spalte zu ändern. Ich finde es etwas irritierend beim Lesen wenn das Datum nicht auf der ersten Zeile des folgenden Eintrags steht. Ich hoffe das ist so für euch in Ordnung, ansonsten lässt sich das jederzeit wieder ändern.<br /> >> ''Klar; sieht jetzt besser aus und Dokumentation ist immer gut; ich sehe auch sonst keine Nachteile'' --[[Benutzer:Ph1959de|Peter]] ([[Benutzer Diskussion:Ph1959de|Diskussion]]) 14:45, 21. Apr. 2016 (CEST)
# Die Seite [[Spezial:Meiste_Interwikilinks]] ist hier leer und die [https://www.mediawiki.org/wiki/Extension:Interwiki Extension:Interwiki] scheint auch nicht installiert bzw. aktiviert zu sein. Sie gehört seit V1.21 zum Installationsbündel und müsste bei der hiesigen V1.24 also schon dabei sein. Man bräuchte sie also nur in Betrieb nehmen. Links auf die Wikipedia werden im FHEMWiki offenbar explizit als ausgeschriebene URL ausgeführt. Das ist meiner Erfahrung nach ungünstig. Auch Beiträge aus dem FHEM-Forum könnte man mit Interwikilinks konsistenter handhaben. Auch die [[Vorlage:DocLink]] lässt sich vermutlich damit einfacher gestalten.<br /> >> ''Wiki-seitig dürften sich da in nächster Zeit einige Änderungen ergeben, die das mit adressieren lassen. Als ich begonnen habe, die derzeitigen Links zu setzten, ging es leider nicht anders (wurde Server-seitig nicht angeboten). Da würde ich Dich einfach noch um etwas Geduld bitten - und später gern bei Dir nachhaken, nachdem Du Dich allein mit der Frage schon als Experte geoutet/qualifiziert hast :-) '' --[[Benutzer:Ph1959de|Peter]] ([[Benutzer Diskussion:Ph1959de|Diskussion]]) 14:45, 21. Apr. 2016 (CEST)

Viele Grüße --[[Benutzer:MGu|MGu]] ([[Benutzer Diskussion:MGu|Diskussion]]) 13:06, 16. Apr. 2016 (CEST)

== Infobox Modul: Neue untergeordnete Boards Wettermodule und Kalendermodule ==
Hallo Peter!

Könntest Du bei Gelegenheit bitte die Verbindung für die Infobox zu den neuen Unterboards einpflegen. Das scheint derzeit noch nicht zu funktionieren bzw. ich habe keine Ahnung wie...<BR>
Danke und Gruß, --[[Benutzer:Krikan|Christian]] ([[Benutzer Diskussion:Krikan|Diskussion]]) 21:56, 27. Mai 2016 (CEST)
<hr/>
:Hallo Christian...
:gut versteckt (hab selbst erst wieder "suchen" müssen) befindet sich die Liste der Forenboards in der Vorlage [[:Vorlage:Link2Forum|Link2Forum]]. Muss ich gelegentlich mal in der Doku zur Vorlage [[:Vorlage:Infobox Modul|Infobox Modul]] erwähnen.
:Habe gerade die neuen Unterboards eingefügt. --[[Benutzer:Ph1959de|Peter]] ([[Benutzer Diskussion:Ph1959de|Diskussion]]) 09:38, 28. Mai 2016 (CEST)

== Bitte um Kontrolle/Meinung ==

Hallo Peter!<BR>
Könntest Du bitte einmal hier [[Benutzer_Diskussion:Krueuw]] hineinschauen -falls noch nicht gesehen- und ggf. eingreifen, falls ich falsch liege und/oder etwas vergessen habe.<BR>
Danke und Gruß, --[[Benutzer:Krikan|Christian]] ([[Benutzer Diskussion:Krikan|Diskussion]]) 15:24, 7. Aug. 2016 (CEST)
:Vermutlich ist unsere Diskussion dort überholt. [[Benutzer:ThomasRamm]] hat die Artikel eben verschoben/geaendert/zusammengefasst und mir fehlt momentan darüber der Überblick. Gruß, --[[Benutzer:Krikan|Christian]] ([[Benutzer Diskussion:Krikan|Diskussion]]) 16:50, 7. Aug. 2016 (CEST)

== Wiki Beitrag zu msg ==

Darin werden direkte Fragen gestellt, soll man auf die antworten?!?

"Bisher keine über das in der Infobox verlinkte Forenthema hinausgehenden Informationen verfügbar, auch der commandref-Eintrag ist bisher (warum eigentlich?) leer."
Ergibt sich aus dem verlinkten Forenbeitrag. Kurzfassung: https://forum.fhem.de/index.php/topic,39983.msg477338.html#msg477338

"Darüber hinaus ist die Schreibweise inkonsistent und/oder irreführend: der Befehl ist in Kleinbuchstaben einzugeben, obwohl der Modulname mit Großbuchstaben geschrieben wird."
Ergibt sich aus der Historie "Der Befehl msg ersetzt ausserdem das vormals verfügbare Modul MSG" und der aktuellen Beschränkung in FHEM, dass die Umbenennung der Datei in Kleinbuchstaben bei Bestandsinstallationen dazu führt, dass es dann sowohl 75_MSG.pm und 75_msg.pm geben würde und diese Dateien sich dann gegenseitig stören würden. Auch kann man aktuell in FHEM einen Befehl nicht genauso nennen wie ein Modul und umgekehrt, weshalb das ohnehin vorher als deprecated geführte Modul 75_MSG.pm einfach durch die Datei für den msg-Befehl ersetzt wurde. Diskussionen dazu gab es, eine Lösung diesen Konflikt zu beseitigen wurde nicht angeboten:
https://forum.fhem.de/index.php/topic,47155.msg393903.html#msg393903
https://forum.fhem.de/index.php/topic,49079.msg410453.html#msg410453

HP1000

2016-10-02T18:39:15Z

Loredo:

{{Infobox Modul
|ModPurpose=Einbindung einer HP1000 Wetterstation
|ModType=d
|ModForumArea=Heizungssteuerung/Raumklima
|ModFTopic=44022
|ModTechName=50_HP1000.pm
|ModOwner={{Link2FU|1363|Loredo}}
}}
== HP1000 ==
HP1000 ist ein Modul zum Auslesen von HP1000/WH2600 Wetterstationen von renkforce/Froggit, etc.

Funktionsweise des Moduls ist, dass in der Wetterstation eine FHEMWEB Instanz angegeben wird, an die die Wetterstation dann regelmäßig die Daten sendet.
== Konfiguration ==
Die Konfiguration des Moduls erfolgt in drei Schritten:
=== Definition einer Webinstanz für die Wetterstation ===
Zunächst muss auf einem eigenen Port eine neue FHEMWEB-Instanz angelegt werden, z.B. mit dem Namen WEBweather. Dieser muss zwingend der Name weatherstation zugewiesen werden. Dieser ist in der Firmware der Stationen fest codiert.
define WEBweather FHEMWEB 8089 global
attr WEBweather webname weatherstation
=== Definition der Wetterstation ===
Dann wird das Modul noch in Fhem definiert. Die Definition kann mit und ohne Benutzernamen und Passwort erfolgen. Wenn bei der Definition Benutzername und Passwort nicht angegeben werden, werden die von der Wetterstation gesendeten Benutzerdaten von Fhem nicht überprüft. Eine WH2600 Station erfordert im Webinterfache immer die Angabe von Benutzername und Passwort.
Definition mit Benutzername und Passwort:
define Wetterstation HP1000 Benutzer Passwort
Definition ohne Benutzername und Passwort:
define Wetterstation HP1000

=== Eingaben im Webinterface der Station ===
Dann muss der Station eingestellt werden, dass die Wetterinformationen an Fhem geschickt werden sollen. Bei einer WH2600 (Station ohne LCD Display) geschieht das im Webinterface, bei einer HP1000 direkt in den Einstellungen des LCD Displays.
Dazu unter "Weather Network" folgendes eintragen:
<pre>Remote Server => Customized
Server IP/Hostname => <Fhem-Domainname> bzw. <Fhem-IP> (siehe unten)
Server Port => Der Port der neuen Webinstanz in Fhem (im Beispiel oben 8089)
Station ID => selbst gewählter Benutzername
Password => selbst gewähltes Passwort</pre>
Zu '''Server IP/Hostname''': Hier muss entweder der Domainname angegeben werden, unter dem Fhem erreichbar ist (vollständige Domain nicht vergessen!), oder die IP. Wenn in Fhem keine Daten ankommen, ist das hier meist der Knackpunkt. Erfahrungen zeigen, dass teilweise der Domainname nicht vollständig angegeben wurde oder aber der Domainname nicht aufgelöst werden kann (vielleicht gibt es hier Probleme einzelner Stationen, bei der Konfiguration via DHCP den Nameserver-Eintrag richtig umzusetzen). Auch hat die Firmware oft einen Bug der verhindert, dass IP Adressen direkt verwendet werden können. Hier muss dann zwingend auf einen Domainnamen zurückgegriffen werden!
Einfach mal alle Möglichkeiten durchprobieren.

'''Station ID''' und '''Passwort''' müssen hier angegeben werden. Bei der Definition der Station in Fhem kann man diese angeben (dann wird geprüft, ob die berechtigte Station Daten schickt) oder weglassen (dann werden Benutzername und Passwort nicht von Fhem geprüft).

== Tipps, Tricks, Problemlösungen ==
=== FileLog ===
Das Modul definiert bei der Erstellung kein FileLog. Wenn man eines definiert, bietet sich aufgrund der Häufigkeit von Datenübertragungen und damit der Menge an übertragenen Informationen das Loggen nur des T:-Readings an:
define FileLog_WeatherStation FileLog ./log/WeatherStation-%Y.log WeatherStation:T:.*

Alternativ sei auch auf die Verwendung von DbLog verwiesen. Dort kann man mit Hilfe des DbLogInclude Attributs granularer einstellen wie oft ein Wert geloggt werden soll:
attr WeatherStation DbLogInclude windSpeed:300 windGust:300 windChill:300 temperature.*:300 humidity.*:300 luminosity:300 uv:300

Wichtig ist auch, dass für das Logging die richtigen Events ausgelöst werden. Wer die event-on-* Attribute benutzt kann diese in Kombination mit DbLogInclude z.B. so setzen:
attr event-on-update-reading temperature.*,humidity.*,windSpeed,windGust,windChill,luminosity,uv,dewpoint.*,rain.*

=== Falsch angezeigte/zu wenig Readings ===
Abhängig von der Firmwareversion und/oder dem Modell der Station kann es dazu kommen, dass teilweise nicht alle Readings oder die Readings mit den falschen Einheiten (z. B. Wingeschwindigkeit in mph, obwohl km/h konfiguriert wurde) angezeigt werden. In diesem Fall hilft es, im Webinterface der Wetterstation bei der Definition "Weather Network" den "Server Type" auf "JSP" zu stellen.

=== Keine Daten in Fhem ===
Wenn in Fhem keine Daten von der Wetterstation ankommen, liegt das häufig daran, dass FHEM nicht richtig als "Weather Network" konfiguriert wurde. Wenn die '''erforderlichen Eingaben im Webinterface''' (s. o.) der Station nicht helfen, kann man sich zum Testen per telnet mit der Wetterstation verbinden (Benutzername admin, Passwort admin). Mögliche Befehle:
<pre>help
quit
reboot
Usage: passwd
Old Password:
New Password:
Re-enter New Password:
Usage: username <user name>
Usage: ipconfig
Usage: setip <ip addr>
Usage: setmask <netmask>
Usage: setgateway <ip addr>
Usage: setdns <ip addr>
Usage: setmode <mode>
<mode>: 0: SERVER 1: CLIENT
Usage: setsrvport <port>
Usage: setdstport <port>
Usage: dhcpclient <status>
<status>: 0: disable 1: enable
Usage: connectype <protocol>
<protocol>: 0: TCP 1: UDP
Usage: transmitimer <time>
<time>: time in ms
Usage: saveconfig
Usage: accessip <index> <ip addr>
<index>: index of accessible IP
<ip addr>: accessible IP address
Usage: setaccip <mode>
<mode>: 0: disable 1: enable
Usage: setaw <cold start> <authentication fail> <ip changed> <password changed>
<cold start>: 0: Disable 1: Enable
<authentication fail>: 0: Disable 1: Enable
<ip changed>: 0: Disable 1: Enable
<password changed>: 0: Disable 1: Enable
Usage: setdsthn <Host name/IP>
Usage: tftpsrv <ip addr>
Usage: filename <file name>
Usage: dlfirmware
Usage: seteep <HEX RegStartAddr> <HEX Byte 0> <HEX Byte 1>...<HEX Byte N>
Usage: dbgmsg <mode>
<mode>: 0: Disable 1: Enable
Usage: connstatus
Usage: ping xxx.xxx.xxx.xxx
Usage: setRTC <HEX RegStartAddr> <HEX Byte 0> <HEX Byte 1>...<HEX Byte N></pre>
Am besten mit "ipconfig" sich die aktuelle Konfiguration anzeigen lassen. Mit ping kann man Verbindungen z. B. zu Fhem testen.

HP1000

2016-10-02T15:46:11Z

Loredo: /* Tipps, Tricks, Problemlösungen */

{{Infobox Modul
|ModPurpose=Einbindung einer HP1000 Wetterstation
|ModType=d
|ModForumArea=Heizungssteuerung/Raumklima
|ModFTopic=44022
|ModTechName=50_HP1000.pm
|ModOwner={{Link2FU|1363|Loredo}}
}}
== HP1000 ==
HP1000 ist ein Modul zum Auslesen von HP1000/WH2600 Wetterstationen von renkforce/Froggit, etc.

Funktionsweise des Moduls ist, dass in der Wetterstation eine FHEMWEB Instanz angegeben wird, an die die Wetterstation dann regelmäßig die Daten sendet.
== Konfiguration ==
Die Konfiguration des Moduls erfolgt in drei Schritten:
=== Definition einer Webinstanz für die Wetterstation ===
Zunächst muss auf einem eigenen Port eine neue FHEMWEB-Instanz angelegt werden, z.B. mit dem Namen WEBweather. Dieser muss zwingend der Name weatherstation zugewiesen werden. Dieser ist in der Firmware der Stationen fest codiert.
define WEBweather FHEMWEB 8089 global
attr WEBweather webname weatherstation
=== Definition der Wetterstation ===
Dann wird das Modul noch in Fhem definiert. Die Definition kann mit und ohne Benutzernamen und Passwort erfolgen. Wenn bei der Definition Benutzername und Passwort nicht angegeben werden, werden die von der Wetterstation gesendeten Benutzerdaten von Fhem nicht überprüft. Eine WH2600 Station erfordert im Webinterfache immer die Angabe von Benutzername und Passwort.
Definition mit Benutzername und Passwort:
define Wetterstation HP1000 Benutzer Passwort
Definition ohne Benutzername und Passwort:
define Wetterstation HP1000

=== Eingaben im Webinterface der Station ===
Dann muss der Station eingestellt werden, dass die Wetterinformationen an Fhem geschickt werden sollen. Bei einer WH2600 (Station ohne LCD Display) geschieht das im Webinterface, bei einer HP1000 direkt in den Einstellungen des LCD Displays.
Dazu unter "Weather Network" folgendes eintragen:
<pre>Remote Server => Customized
Server IP/Hostname => <Fhem-Domainname> bzw. <Fhem-IP> (siehe unten)
Server Port => Der Port der neuen Webinstanz in Fhem (im Beispiel oben 8089)
Station ID => selbst gewählter Benutzername
Password => selbst gewähltes Passwort</pre>
Zu '''Server IP/Hostname''': Hier muss entweder der Domainname angegeben werden, unter dem Fhem erreichbar ist (vollständige Domain nicht vergessen!), oder die IP. Wenn in Fhem keine Daten ankommen, ist das hier meist der Knackpunkt. Erfahrungen zeigen, dass teilweise der Domainname nicht vollständig angegeben wurde oder aber der Domainname nicht aufgelöst werden kann (vielleicht gibt es hier Probleme einzelner Stationen, bei der Konfiguration via DHCP den Nameserver-Eintrag richtig umzusetzen). Auch hat die Firmware oft einen Bug der verhindert, dass IP Adressen direkt verwendet werden können. Hier muss dann zwingend auf einen Domainnamen zurückgegriffen werden!
Einfach mal alle Möglichkeiten durchprobieren.

'''Station ID''' und '''Passwort''' müssen hier angegeben werden. Bei der Definition der Station in Fhem kann man diese angeben (dann wird geprüft, ob die berechtigte Station Daten schickt) oder weglassen (dann werden Benutzername und Passwort nicht von Fhem geprüft).

== Tipps, Tricks, Problemlösungen ==
=== FileLog ===
Das Modul definiert bei der Erstellung kein FileLog. Wenn man eines definiert, bietet sich aufgrund der Häufigkeit von Datenübertragungen und damit der Menge an übertragenen Informationen das Loggen nur des T:-Readings an:
define FileLog_WeatherStation FileLog ./log/WeatherStation-%Y.log WeatherStation:T:.*

Alternativ sei auch auf die Verwendung von DbLog verwiesen. Dort kann man mit Hilfe des DbLogInclude Attributs granularer einstellen wie oft ein Wert geloggt werden soll:
attr WeatherStation DbLogInclude windSpeed:300 windGust:300 windChill:300 temperature.*:300 humidity.*:300 luminosity:300 uv:300

Wichtig ist auch, dass für das Logging die richtigen Events ausgelöst werden. Wer die event-on-* Attribute benutzt kann diese in Kombination mit DbLogInclude z.B. so setzen:
attr event-on-update-reading temperature.*,humidity.*,windSpeed,windGust,windChill,luminosity,uv,dewpoint.*,rain.*

=== Falsch angezeigte/zu wenig Readings ===
Abhängig von der Firmwareversion und/oder dem Modell der Station kann es dazu kommen, dass teilweise nicht alle Readings oder die Readings mit den falschen Einheiten (z. B. Wingeschwindigkeit in mph, obwohl km/h konfiguriert wurde) angezeigt werden. In diesem Fall hilft es, im Webinterface der Wetterstation bei der Definition "Weather Network" den "Server Type" auf "JSP" zu stellen.

=== Keine Daten in Fhem ===
Wenn in Fhem keine Daten von der Wetterstation ankommen, liegt das häufig daran, dass FHEM nicht richtig als "Weather Network" konfiguriert wurde. Wenn die '''erforderlichen Eingaben im Webinterface''' (s. o.) der Station nicht helfen, kann man sich zum Testen per telnet mit der Wetterstation verbinden (Benutzername admin, Passwort admin). Mögliche Befehle:
<pre>help
quit
reboot
Usage: passwd
Old Password:
New Password:
Re-enter New Password:
Usage: username <user name>
Usage: ipconfig
Usage: setip <ip addr>
Usage: setmask <netmask>
Usage: setgateway <ip addr>
Usage: setdns <ip addr>
Usage: setmode <mode>
<mode>: 0: SERVER 1: CLIENT
Usage: setsrvport <port>
Usage: setdstport <port>
Usage: dhcpclient <status>
<status>: 0: disable 1: enable
Usage: connectype <protocol>
<protocol>: 0: TCP 1: UDP
Usage: transmitimer <time>
<time>: time in ms
Usage: saveconfig
Usage: accessip <index> <ip addr>
<index>: index of accessible IP
<ip addr>: accessible IP address
Usage: setaccip <mode>
<mode>: 0: disable 1: enable
Usage: setaw <cold start> <authentication fail> <ip changed> <password changed>
<cold start>: 0: Disable 1: Enable
<authentication fail>: 0: Disable 1: Enable
<ip changed>: 0: Disable 1: Enable
<password changed>: 0: Disable 1: Enable
Usage: setdsthn <Host name/IP>
Usage: tftpsrv <ip addr>
Usage: filename <file name>
Usage: dlfirmware
Usage: seteep <HEX RegStartAddr> <HEX Byte 0> <HEX Byte 1>...<HEX Byte N>
Usage: dbgmsg <mode>
<mode>: 0: Disable 1: Enable
Usage: connstatus
Usage: ping xxx.xxx.xxx.xxx
Usage: setRTC <HEX RegStartAddr> <HEX Byte 0> <HEX Byte 1>...<HEX Byte N></pre>
Am besten mit "ipconfig" sich die aktuelle Konfiguration anzeigen lassen. Mit ping kann man Verbindungen z. B. zu Fhem testen.

HP1000

2016-10-02T15:07:44Z

Loredo: /* Eingaben im Webinterface der Station */

{{Infobox Modul
|ModPurpose=Einbindung einer HP1000 Wetterstation
|ModType=d
|ModForumArea=Heizungssteuerung/Raumklima
|ModFTopic=44022
|ModTechName=50_HP1000.pm
|ModOwner={{Link2FU|1363|Loredo}}
}}
== HP1000 ==
HP1000 ist ein Modul zum Auslesen von HP1000/WH2600 Wetterstationen von renkforce/Froggit, etc.

Funktionsweise des Moduls ist, dass in der Wetterstation eine FHEMWEB Instanz angegeben wird, an die die Wetterstation dann regelmäßig die Daten sendet.
== Konfiguration ==
Die Konfiguration des Moduls erfolgt in drei Schritten:
=== Definition einer Webinstanz für die Wetterstation ===
Zunächst muss auf einem eigenen Port eine neue FHEMWEB-Instanz angelegt werden, z.B. mit dem Namen WEBweather. Dieser muss zwingend der Name weatherstation zugewiesen werden. Dieser ist in der Firmware der Stationen fest codiert.
define WEBweather FHEMWEB 8089 global
attr WEBweather webname weatherstation
=== Definition der Wetterstation ===
Dann wird das Modul noch in Fhem definiert. Die Definition kann mit und ohne Benutzernamen und Passwort erfolgen. Wenn bei der Definition Benutzername und Passwort nicht angegeben werden, werden die von der Wetterstation gesendeten Benutzerdaten von Fhem nicht überprüft. Eine WH2600 Station erfordert im Webinterfache immer die Angabe von Benutzername und Passwort.
Definition mit Benutzername und Passwort:
define Wetterstation HP1000 Benutzer Passwort
Definition ohne Benutzername und Passwort:
define Wetterstation HP1000

=== Eingaben im Webinterface der Station ===
Dann muss der Station eingestellt werden, dass die Wetterinformationen an Fhem geschickt werden sollen. Bei einer WH2600 (Station ohne LCD Display) geschieht das im Webinterface, bei einer HP1000 direkt in den Einstellungen des LCD Displays.
Dazu unter "Weather Network" folgendes eintragen:
<pre>Remote Server => Customized
Server IP/Hostname => <Fhem-Domainname> bzw. <Fhem-IP> (siehe unten)
Server Port => Der Port der neuen Webinstanz in Fhem (im Beispiel oben 8089)
Station ID => selbst gewählter Benutzername
Password => selbst gewähltes Passwort</pre>
Zu '''Server IP/Hostname''': Hier muss entweder der Domainname angegeben werden, unter dem Fhem erreichbar ist (vollständige Domain nicht vergessen!), oder die IP. Wenn in Fhem keine Daten ankommen, ist das hier meist der Knackpunkt. Erfahrungen zeigen, dass teilweise der Domainname nicht vollständig angegeben wurde oder aber der Domainname nicht aufgelöst werden kann (vielleicht gibt es hier Probleme einzelner Stationen, bei der Konfiguration via DHCP den Nameserver-Eintrag richtig umzusetzen). Auch hat die Firmware oft einen Bug der verhindert, dass IP Adressen direkt verwendet werden können. Hier muss dann zwingend auf einen Domainnamen zurückgegriffen werden!
Einfach mal alle Möglichkeiten durchprobieren.

'''Station ID''' und '''Passwort''' müssen hier angegeben werden. Bei der Definition der Station in Fhem kann man diese angeben (dann wird geprüft, ob die berechtigte Station Daten schickt) oder weglassen (dann werden Benutzername und Passwort nicht von Fhem geprüft).

== Tipps, Tricks, Problemlösungen ==
=== FileLog ===
Das Modul definiert bei der Erstellung kein FileLog. Wenn man eines definiert, bietet sich aufgrund der Häufigkeit von Datenübertragungen und damit der Menge an übertragenen Informationen das Loggen nur des T:-Readings an:
define FileLog_Wetterstation FileLog ./log/Wetterstation-%Y.log Wetterstation:T:.*
=== Mehr Einträge im T:-Reading ===
Das Modul liefert standardmäßig nicht alle vom Außensender verfügbaren Daten auch in der T:-Zeile. Wenn man dort - z. B. zum Loggen - alle Daten haben möchte, kann man die übrigen Daten ergänzen. Dafür editiert man die Datei 50_HP1000.pm und ergänzt Zeilen.
Im Bereich von Zeile 347 suchen:
<pre> $result = "T: " . $webArgs->{outtemp} if ( defined( $webArgs->{outtemp} ) );
$result .= " H: " . $webArgs->{outhumi}
if ( defined( $webArgs->{outhumi} ) );
$result .= " Ti: " . $webArgs->{intemp}
if ( defined( $webArgs->{intemp} ) );
$result .= " Hi: " . $webArgs->{inhumi}
if ( defined( $webArgs->{inhumi} ) );
$result .= " W: " . $webArgs->{windspeed}
if ( defined( $webArgs->{windspeed} ) );
$result .= " R: " . $webArgs->{rainrate}
if ( defined( $webArgs->{rainrate} ) );
$result .= " WD: " . $webArgs->{winddir}
if ( defined( $webArgs->{winddir} ) );
$result .= " D: " . $webArgs->{dewpoint}
if ( defined( $webArgs->{dewpoint} ) );
$result .= " P: " . $webArgs->{relbaro}
if ( defined( $webArgs->{relbaro} ) );</pre>
und dahinter folgende neue Zeilen einfügen:
<pre> $result .= " U: " . $webArgs->{UV}
if ( defined( $webArgs->{UV} ) );
$result .= " L: " . $webArgs->{light}
if ( defined( $webArgs->{light} ) );
$result .= " WC: " . $webArgs->{windchill}
if (defined($webArgs->{windchill}));
$result .= " RD: " . $webArgs->{dailyrain}
if (defined($webArgs->{dailyrain}));
$result .= " RW: " . $webArgs->{weeklyrain}
if (defined($webArgs->{weeklyrain}));
$result .= " RM: ".$webArgs->{monthlyrain}
if (defined($webArgs->{monthlyrain}));
$result .= " RY: ".$webArgs->{yearlyrain}
if (defined($webArgs->{yearlyrain}));
$result .= " WG: ".$webArgs->{windgust}
if (defined($webArgs->{windgust}));</pre>
Um zu verhindern, dass die eigenen Ergänzungen bei einem Update des Moduls überschrieben werden, dann noch 50_HP1000.pm vom automatischen Update ausnehmen:
attr global exclude_from_update 50_HP1000.pm
=== Absturz von Fhem wegen Illegal division by zero ===
Wenn HP1000 Fhem abstürzen lässt mit der Fehlermeldung
<pre>2016.10.01 08:51:00 1: PERL WARNING: Use of uninitialized value in division (/) at ./FHEM/50_HP1000.pm line 383.
Illegal division by zero at ./FHEM/50_HP1000.pm line 383.</pre>
dann hilft es, die mit + markierten Zeilen (natürlich ohne die +-Zeichen selbst!) in 50_HP1000.pm im sub HP1000_GetSum (um Zeile 400) einzufügen:
<pre> if ($avg) {
+ if (@{ $hash->{helper}{history}{$t} } > 0) {
$return = sprintf( "%.1f",
sum( @{ $hash->{helper}{history}{$t} } ) /
@{ $hash->{helper}{history}{$t} } );

Log3 $name, 5, "HP1000 $name: Average for $t: $return";
+ }
}</pre>
=== Falsch angezeigte/zu wenig Readings ===
Abhängig von der Firmwareversion und/oder dem Modell der Station kann es dazu kommen, dass teilweise nicht alle Readings oder die Readings mit den falschen Einheiten (z. B. Wingeschwindigkeit in mph, obwohl km/h konfiguriert wurde) angezeigt werden. In diesem Fall hilft es, im Webinterface der Wetterstation bei der Definition "Weather Network" den "Server Type" auf "JSP" zu stellen.
=== Keine Daten in Fhem ===
Wenn in Fhem keine Daten von der Wetterstation ankommen, liegt das häufig daran, dass FHEM nicht richtig als "Weather Network" konfiguriert wurde. Wenn die '''erforderlichen Eingaben im Webinterface''' (s. o.) der Station nicht helfen, kann man sich zum Testen per telnet mit der Wetterstation verbinden (Benutzername admin, Passwort admin). Mögliche Befehle:
<pre>help
quit
reboot
Usage: passwd
Old Password:
New Password:
Re-enter New Password:
Usage: username <user name>
Usage: ipconfig
Usage: setip <ip addr>
Usage: setmask <netmask>
Usage: setgateway <ip addr>
Usage: setdns <ip addr>
Usage: setmode <mode>
<mode>: 0: SERVER 1: CLIENT
Usage: setsrvport <port>
Usage: setdstport <port>
Usage: dhcpclient <status>
<status>: 0: disable 1: enable
Usage: connectype <protocol>
<protocol>: 0: TCP 1: UDP
Usage: transmitimer <time>
<time>: time in ms
Usage: saveconfig
Usage: accessip <index> <ip addr>
<index>: index of accessible IP
<ip addr>: accessible IP address
Usage: setaccip <mode>
<mode>: 0: disable 1: enable
Usage: setaw <cold start> <authentication fail> <ip changed> <password changed>
<cold start>: 0: Disable 1: Enable
<authentication fail>: 0: Disable 1: Enable
<ip changed>: 0: Disable 1: Enable
<password changed>: 0: Disable 1: Enable
Usage: setdsthn <Host name/IP>
Usage: tftpsrv <ip addr>
Usage: filename <file name>
Usage: dlfirmware
Usage: seteep <HEX RegStartAddr> <HEX Byte 0> <HEX Byte 1>...<HEX Byte N>
Usage: dbgmsg <mode>
<mode>: 0: Disable 1: Enable
Usage: connstatus
Usage: ping xxx.xxx.xxx.xxx
Usage: setRTC <HEX RegStartAddr> <HEX Byte 0> <HEX Byte 1>...<HEX Byte N></pre>
Am besten mit "ipconfig" sich die aktuelle Konfiguration anzeigen lassen. Mit ping kann man Verbindungen z. B. zu Fhem testen.

HP1000

2016-10-02T15:03:12Z

Loredo: /* Definition der Wetterstation */

{{Infobox Modul
|ModPurpose=Einbindung einer HP1000 Wetterstation
|ModType=d
|ModForumArea=Heizungssteuerung/Raumklima
|ModFTopic=44022
|ModTechName=50_HP1000.pm
|ModOwner={{Link2FU|1363|Loredo}}
}}
== HP1000 ==
HP1000 ist ein Modul zum Auslesen von HP1000/WH2600 Wetterstationen von renkforce/Froggit, etc.

Funktionsweise des Moduls ist, dass in der Wetterstation eine FHEMWEB Instanz angegeben wird, an die die Wetterstation dann regelmäßig die Daten sendet.
== Konfiguration ==
Die Konfiguration des Moduls erfolgt in drei Schritten:
=== Definition einer Webinstanz für die Wetterstation ===
Zunächst muss auf einem eigenen Port eine neue FHEMWEB-Instanz angelegt werden, z.B. mit dem Namen WEBweather. Dieser muss zwingend der Name weatherstation zugewiesen werden. Dieser ist in der Firmware der Stationen fest codiert.
define WEBweather FHEMWEB 8089 global
attr WEBweather webname weatherstation
=== Definition der Wetterstation ===
Dann wird das Modul noch in Fhem definiert. Die Definition kann mit und ohne Benutzernamen und Passwort erfolgen. Wenn bei der Definition Benutzername und Passwort nicht angegeben werden, werden die von der Wetterstation gesendeten Benutzerdaten von Fhem nicht überprüft. Eine WH2600 Station erfordert im Webinterfache immer die Angabe von Benutzername und Passwort.
Definition mit Benutzername und Passwort:
define Wetterstation HP1000 Benutzer Passwort
Definition ohne Benutzername und Passwort:
define Wetterstation HP1000

=== Eingaben im Webinterface der Station ===
Dann muss der Station in deren Webinterface noch gesagt werden, dass die Wetterinformationen an Fhem geschickt werden. Dazu im Webinterface unter "Weather Network" Folgendes eintragen:
<pre>Remote Server => Customzied
Server IP/Hostname => <Fhem-Domainname> bzw. <Fhem-IP> (s.u.)
Server Port => Der Port der neuen Webinstanz in Fhem (im Beispiel oben 8089)
Station ID => selbstgewählter Benutzername
Password => selbstgewähltes Passwort</pre>
Zu '''Server IP/Hostname''': Hier muss entweder der Domainname angegeben werden, unter dem Fhem erreichbar ist (vollständige Domain nicht vergessen!), oder die IP. Wenn in Fhem keine Daten ankommen, ist das hier meist der Knackpunkt. Erfahrungen zeigen, dass teilweise der Domainname nicht vollständig angegeben wurde oder aber der Domainname nicht aufgelöst werden kann (vielleicht gibt es hier Probleme einzelner Stationen, bei der Konfiguration via DHCP den Nameserver-Eintrag richtig umzusetzen). Einfach mal alle Möglichkeiten durchprobieren.

'''Station ID''' und '''Passwort''' müssen hier angegeben werden. Bei der Definition der Station in Fhem kann man diese angeben (dann wird geprüft, ob die berechtigte Station Daten schickt) oder weglassen (dann werden Benutzername und Passwort nicht von Fhem geprüft).
== Tipps, Tricks, Problemlösungen ==
=== FileLog ===
Das Modul definiert bei der Erstellung kein FileLog. Wenn man eines definiert, bietet sich aufgrund der Häufigkeit von Datenübertragungen und damit der Menge an übertragenen Informationen das Loggen nur des T:-Readings an:
define FileLog_Wetterstation FileLog ./log/Wetterstation-%Y.log Wetterstation:T:.*
=== Mehr Einträge im T:-Reading ===
Das Modul liefert standardmäßig nicht alle vom Außensender verfügbaren Daten auch in der T:-Zeile. Wenn man dort - z. B. zum Loggen - alle Daten haben möchte, kann man die übrigen Daten ergänzen. Dafür editiert man die Datei 50_HP1000.pm und ergänzt Zeilen.
Im Bereich von Zeile 347 suchen:
<pre> $result = "T: " . $webArgs->{outtemp} if ( defined( $webArgs->{outtemp} ) );
$result .= " H: " . $webArgs->{outhumi}
if ( defined( $webArgs->{outhumi} ) );
$result .= " Ti: " . $webArgs->{intemp}
if ( defined( $webArgs->{intemp} ) );
$result .= " Hi: " . $webArgs->{inhumi}
if ( defined( $webArgs->{inhumi} ) );
$result .= " W: " . $webArgs->{windspeed}
if ( defined( $webArgs->{windspeed} ) );
$result .= " R: " . $webArgs->{rainrate}
if ( defined( $webArgs->{rainrate} ) );
$result .= " WD: " . $webArgs->{winddir}
if ( defined( $webArgs->{winddir} ) );
$result .= " D: " . $webArgs->{dewpoint}
if ( defined( $webArgs->{dewpoint} ) );
$result .= " P: " . $webArgs->{relbaro}
if ( defined( $webArgs->{relbaro} ) );</pre>
und dahinter folgende neue Zeilen einfügen:
<pre> $result .= " U: " . $webArgs->{UV}
if ( defined( $webArgs->{UV} ) );
$result .= " L: " . $webArgs->{light}
if ( defined( $webArgs->{light} ) );
$result .= " WC: " . $webArgs->{windchill}
if (defined($webArgs->{windchill}));
$result .= " RD: " . $webArgs->{dailyrain}
if (defined($webArgs->{dailyrain}));
$result .= " RW: " . $webArgs->{weeklyrain}
if (defined($webArgs->{weeklyrain}));
$result .= " RM: ".$webArgs->{monthlyrain}
if (defined($webArgs->{monthlyrain}));
$result .= " RY: ".$webArgs->{yearlyrain}
if (defined($webArgs->{yearlyrain}));
$result .= " WG: ".$webArgs->{windgust}
if (defined($webArgs->{windgust}));</pre>
Um zu verhindern, dass die eigenen Ergänzungen bei einem Update des Moduls überschrieben werden, dann noch 50_HP1000.pm vom automatischen Update ausnehmen:
attr global exclude_from_update 50_HP1000.pm
=== Absturz von Fhem wegen Illegal division by zero ===
Wenn HP1000 Fhem abstürzen lässt mit der Fehlermeldung
<pre>2016.10.01 08:51:00 1: PERL WARNING: Use of uninitialized value in division (/) at ./FHEM/50_HP1000.pm line 383.
Illegal division by zero at ./FHEM/50_HP1000.pm line 383.</pre>
dann hilft es, die mit + markierten Zeilen (natürlich ohne die +-Zeichen selbst!) in 50_HP1000.pm im sub HP1000_GetSum (um Zeile 400) einzufügen:
<pre> if ($avg) {
+ if (@{ $hash->{helper}{history}{$t} } > 0) {
$return = sprintf( "%.1f",
sum( @{ $hash->{helper}{history}{$t} } ) /
@{ $hash->{helper}{history}{$t} } );

Log3 $name, 5, "HP1000 $name: Average for $t: $return";
+ }
}</pre>
=== Falsch angezeigte/zu wenig Readings ===
Abhängig von der Firmwareversion und/oder dem Modell der Station kann es dazu kommen, dass teilweise nicht alle Readings oder die Readings mit den falschen Einheiten (z. B. Wingeschwindigkeit in mph, obwohl km/h konfiguriert wurde) angezeigt werden. In diesem Fall hilft es, im Webinterface der Wetterstation bei der Definition "Weather Network" den "Server Type" auf "JSP" zu stellen.
=== Keine Daten in Fhem ===
Wenn in Fhem keine Daten von der Wetterstation ankommen, liegt das häufig daran, dass FHEM nicht richtig als "Weather Network" konfiguriert wurde. Wenn die '''erforderlichen Eingaben im Webinterface''' (s. o.) der Station nicht helfen, kann man sich zum Testen per telnet mit der Wetterstation verbinden (Benutzername admin, Passwort admin). Mögliche Befehle:
<pre>help
quit
reboot
Usage: passwd
Old Password:
New Password:
Re-enter New Password:
Usage: username <user name>
Usage: ipconfig
Usage: setip <ip addr>
Usage: setmask <netmask>
Usage: setgateway <ip addr>
Usage: setdns <ip addr>
Usage: setmode <mode>
<mode>: 0: SERVER 1: CLIENT
Usage: setsrvport <port>
Usage: setdstport <port>
Usage: dhcpclient <status>
<status>: 0: disable 1: enable
Usage: connectype <protocol>
<protocol>: 0: TCP 1: UDP
Usage: transmitimer <time>
<time>: time in ms
Usage: saveconfig
Usage: accessip <index> <ip addr>
<index>: index of accessible IP
<ip addr>: accessible IP address
Usage: setaccip <mode>
<mode>: 0: disable 1: enable
Usage: setaw <cold start> <authentication fail> <ip changed> <password changed>
<cold start>: 0: Disable 1: Enable
<authentication fail>: 0: Disable 1: Enable
<ip changed>: 0: Disable 1: Enable
<password changed>: 0: Disable 1: Enable
Usage: setdsthn <Host name/IP>
Usage: tftpsrv <ip addr>
Usage: filename <file name>
Usage: dlfirmware
Usage: seteep <HEX RegStartAddr> <HEX Byte 0> <HEX Byte 1>...<HEX Byte N>
Usage: dbgmsg <mode>
<mode>: 0: Disable 1: Enable
Usage: connstatus
Usage: ping xxx.xxx.xxx.xxx
Usage: setRTC <HEX RegStartAddr> <HEX Byte 0> <HEX Byte 1>...<HEX Byte N></pre>
Am besten mit "ipconfig" sich die aktuelle Konfiguration anzeigen lassen. Mit ping kann man Verbindungen z. B. zu Fhem testen.

DevelopmentGuidelinesAV

2016-08-21T15:14:35Z

Loredo:

== Einleitung ==
Auf dieser Seite sollen Richtlinien für AV-Module gesammelt werden damit es einfacher wird diese zusammen mit anderen Modulen wie remotecontroll oder LightScene zu verwenden. Auch Benachrichtigungen wie Sprachdurchsagen oder Einblendungen lassen sich universeller verwenden wenn sie bei allen Geräten die dies unterstützen gleich angesprochen werden.

Der Text aus dem ursprünglichen Forumsthread war folgender:

::gerade ist ja mit den tv und verstärker modulen sowie dem remotecontrol modul ziemlich schwung in den bereich audio und video geräte gekommen. zusätzlich gibt es noch eine ganze reihe älterer module wie sonor und xbmc und zwei arten itunes anzusprechen und neue module wie für die web radios oder das raspberry multiroom stehen vor der tür.

::wie wäre es sich rechtzeitig auf ein möglichst einheitiches kommando set zu verständigen damit grundlegende dinge wie play/pause/volume/next bei allen geräten einheitlich, in gleicher schreibweise und mit möglichst ähnlichen parametern funktionieren?

::das würde module wie die remotecontrol aber auch structure und lightscene deutlich einfacher und nützlicher machen und auch alternative frontends erleichtern wenn bestimmte features wie audio,video oder cover über ein einheitliches schema markiert würden.

::mein vorschlag wäre sich an das sonos modul anzulehnen weil es mir in dieser hinsicht am fortgeschrittensten erscheint und auch weitergehende features wie cover oder durchsagen anbietet.

::zu vereinheitlichen wäre dann u.a.:
::- welche kommandos zu welchem zweck
::- kommandos sollten einheitlich geschrieben werden. also z.b. immer klein oder immer mixed case.
::- parameter sollten so weit möglich den gleichen wertebereich haben. also z.b. volume immer von 0-100.
::- wenn es aus irgendeinem grund noch ein gerätespezifischer wertebereich nötig ist sollte der zusätzlich vorhanden sein.
::- cover sollten immer auf die gleiche art gelesen werden können
::- ...

Der Thread ist [http://forum.fhem.de/index.php/topic,13784.0.html hier] zu finden.

== Bezeichner ==
siehe [[DevelopmentGuidelines#Bezeichnungen|Bezeichnungen allgmein]]

== Kommandos ==

Diese Tabelle soll eine einheitliche Definition von set-Befehlen aufzeigen. Dazu zählen auch ggf. Parameter und deren Bedeutung.

{| class="wikitable sortable"
! Name !! Parameter !! Bedeutung
|-
| '''on''' || || Schaltet das Gerät ein, so dass es benutzt werden kann.
|-
| '''off''' || || Schaltet das Gerät aus.
|-
| '''play''' || || Startet das Abspielen von Medien (Video, mp3, Radio stream etc.)
|-
| '''pause''' || || Pausiert das Abspielen von Medien, stoppt es aber nicht.
|-
| '''stop''' || || Stoppt (beendet) das Abspielen von Medien.
|-
| '''volume''' || 0 - 100 || Setzt die Lautstärke auf einen prozentualen Wert.
|-
| '''volumeStraight''' || X-Y || Setzt die Lautstärke auf den absoluten Wert, so wie er vom Gerät tatsächlich verwendet wird (z.B. dB)<br><br>''Nur zu Verwenden, wenn das Gerät einen anderen Wertebereich als 0-100% intern verwendet.''
|-
| '''volumeUp''' || [0 - 100] || Erhöht die Lautstärke um einen gerätespezifischen Schritt (z.b. 5%). Wenn die Schrittweite konfigurierbar ist soll das über das Attribut volumeStep erfolgen. Optional kann das Inkrement als optionaler Parameter mit angegeben werden.
|-
| '''volumeDown''' || [0 - 100] || Verringert die Lautstärke um einen gerätespezifischen Schritt (z.b. 5%). Wenn die Schrittweite konfigurierbar ist soll das über das Attribut volumeStep erfolgen. Optional kann das Dekrement als optionaler Parameter mit angegeben werden.
|-
| '''mute''' || <nowiki>on | off | toggle</nowiki> || Aktiviert, deaktiviert oder schaltet die Mutefunktion = Lautstärke der aktuellen Ausgabe wird verringert bzw. abgschaltet (Gerätespezifisch)
|-
| '''repeat''' || <nowiki>one | all | off</nowiki> || Aktivieren der Repeatfunktion = wiederholen des aktuellen Titels/Albums
|-
| '''shuffle''' || <nowiki>on | off</nowiki> || Aktiviert oder deaktiviert die Shufflefunktion = zufällige Wiedergabe.
|-
| '''channel''' || 0 - 9999 || Schaltet auf einen absoluten Sender- oder Programmspeicherplatz (Nicht zu verwechseln mit input)
|-
| '''channelUp''' || || Springt zum nächsten Sender- oder Programmspeicherplatz.
|-
| '''channelDown''' || || Springt zum vorherigen Sender- oder Programmspeicherplatz.
|-
| '''remoteControl''' || # || Parameter ist Hersteller- und Gerätespezifisch. Funktion bei Geräten, die es erlauben die mitgelieferte Hardware Fernbedienung zu simulieren. Parameter in lowerCamelCaps (ggf. muss im Modul selber auf die Herstellerspezifische Schreibweise umcodiert werden; Alles groß- oder klein geschrieben)
|-
| '''input''' || <nowiki>z.B. hdmi[1-n] | av[1-n] | usb | airplay | server [1-n]</nowiki> || Auswahl von Hardwarekanälen (HDMI, DVB-S, PAL, DVI) oder Softwarekanälen (Airplay, IPTV, IP-Radiostream) die das zu steuernde Gerät aktiv schalten soll (zur Darstellung auf TV, Kanalwahl bei AV-Receivern etc.). Da diese Kanäle je nach Gerät und Modellreihen unterschiedliche Bezeichnungen besitzen, sollten alle möglichen Bezeichnungen in Form von lowerCamelCaps angeboten werden.
|-
| '''output''' || <nowiki>z.B. Airtunes1,Airtunes2,Intern</nowiki> || Auswahl des/der Ausgabegerätes.
|-
| '''statusRequest''' || || Den aktuellen Status des Gerätes abfragen
|-
|colspan="3"| ...
|}

== Readings ==

Diese Tabelle soll eine einheitliche Wertedefinition von Readings. Dazu zählen auch die verwendeten Werte und deren Bedeutung.

Wenn es zwischen reading und zugehörigen set eine 1:1 Beziehung gibt sollte sich der Inhalt des readings als Argument des set verwenden lassen um genau diesen dargestellten Zustand zu erreichen.

{| class="wikitable"
|-
! Name !! mögliche Werte !! Bedeutung
|-
| '''power''' || <nowiki>on|off</nowiki> || Ist das Gerät an oder aus?
|-
| '''presence''' || <nowiki>present|absent</nowiki> || Ist das Gerät aktuell ansprechbar? Sollte das Gerät aufgrund abgeschalteten Stromzufuhr, o.ä. aktuell nicht steuerbar sein, so sollte dies mit dem Wert "absent" verdeutlicht werden. In solch einem Fall sollte ein set-Befehl eine entsprechende Fehlermeldung bringen. Evtl. StatusUpdate-Timer sollten ensprechende Fehlermeldungen nur einmal im Log, etc. festhalten und Fehlermeldungen beim nächsten Status-Update entsprechend unterdrücken um so die Logfiles nicht unnötig vollzuschreiben. Auch das presence reading sollte nur dann aktualisiert werden wenn sich der Status geändert hat um am timestamp sehen zu können wann das war. event-on-change-reading ist hierzu nicht ausreichend weil nur das Event unterdrückt wird der Timestamp sich aber trotzdem ändert.
|-
| '''volume''' || 0-100 || Der prozentuale Lautstärkepegel gemessen der maximal möglichen tatsächlichen Werte.
|-
| '''volumeStraight''' || X-Y || Der tatsächliche Lautstärkepegel des Gerätes, so wie er am Gerät angezeigt/verwendet wird. <br><br>''Nur zu Verwenden, wenn das Gerät einen anderen Wertebereich als 0-100% intern verwendet.''
|-
| '''mute''' || <nowiki>on | off</nowiki> || Ist das Gerät aktuell stumm geschaltet?
|-
| '''repeat''' || <nowiki>one | all | off</nowiki> || Ist das Gerät im repeat modus?
|-
| '''shuffle''' || <nowiki>on | off</nowiki> || Ist das Gerät im shuffle modus?
|-
| '''input''' || ''aktuell gewählter Eingangskanal'' ||
|-
| '''output''' || ''aktuell gewählte(s) Ausgabegerät(e)'' ||
|-
| '''channel''' || ''aktuell gewählter Eingangskanal entsprechend dem Gerät''||
|-
| '''currentArtist''' || ''aktueller Interpret'' ||
|-
| '''currentAlbum''' || ''aktuelles Album'' ||
|-
| '''currentTitle''' || ''aktueller Titelname'' ||
|-
| '''currentMedia''' || ''"Name" der Wiedergabe"datei"'' || kann alles sein: Datei vom Filesystem, Stream aus dem Internet, m3u-URL oder was auch immer
|-
| '''playStatus''' || <nowiki>playing | paused | stopped</nowiki> ||
|-
| '''state''' || <nowiki>on | off | absent</nowiki> || Sofern das Gerät empfangsbereit ist, soll der Schaltzustand des Gerätes (Reading: power, sofern anwendbar) zurückgegeben werden. Ansonsten ist die Abwesenheit des Gerätes durch den Wert "absent" anzuzeigen.
|-
| '''stateAV''' || <nowiki><presence> | <power> | <mute> | <playStatus></nowiki> || Kombiniert den Status von bestehenden Readings zu einer logisch abhängigen Einheit nach folgendem Format: Wenn presence=absent=>absent, sonst power=off=>off, sonst mute=on=>muted, sonst playStatus!=stopped=>playStatus, sonst =>power. Das Reading gilt auch als Ersatz für das normale state Reading, wenn dieses z.B. bei Verwendung von DevIO nicht die genannten Status annimmt, sondern denen von DevIO entspricht (appeared, disappeared).
|-
|colspan="3"| ...
|}

== Implementation in Modulen ==
{{yes}} = Implementiert {{yes2}} = device spezifisch {{planed}} = Implementation geplant/in Arbeit {{no}} = Nicht implementiert/Keine Implementation geplant

{| class="wikitable"
! set-Befehl !! LGTV !! LISTENLIVE !! STV !! VIERA !! YAMAHA_AVR !! iTunes !! ENIGMA2 !! ONKYO_AVR !! Squeezebox !! PHTV !! PIONEER !! harmony !! plex
|-
| '''on''' || || || || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} ||
|-
| '''off''' || || || || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} ||
|-
| '''play''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{yes-c}}
|-
| '''pause''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{yes-c}}
|-
| '''stop''' || || || || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{yes-c}}
|-
| '''volume''' || || || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}}
|-
| '''volumeStraight''' || || || || {{no-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{planed-c}}|| {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{no-c}}
|-
| '''volumeUp''' || || || || {{yes-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{no-c}}
|-
| '''volumeDown''' || || || || {{yes-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{no-c}}
|-
| '''mute''' || || || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{no-c}}
|-
| '''repeat''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes2-c}} || {{yes-c}} || {{no-c}} || {{yes2-c}} || {{yes2-c}} || {{yes-c}}
|-
| '''shuffle''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes2-c}} || {{yes-c}} || {{no-c}} || {{yes2-c}} || {{yes2-c}} || {{yes-c}}
|-
| '''channel''' || || || || {{yes-c}} || {{no-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{no-c}}
|-
| '''channelUp''' || || || || {{yes-c}} || {{no-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{no-c}}
|-
| '''channelDown''' || || || || {{yes-c}} || {{no-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{no-c}}
|-
| '''remoteControl''' || || || || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes2-c}} || {{yes2-c}} || {{no-c}}
|-
| '''input''' || {{yes-c}} || || || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}}|| {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{no-c}}
|-
| '''output''' || || || || {{no-c}} || {{no-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{no-c}} || {{no-c}} || {{no-c}} || {{yes2-c}} || {{no-c}}
|-
| '''statusRequest''' || || {{yes-c}} || || {{yes-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{no-c}}
|-
! Reading !! LGTV !! LISTENLIVE !! STV !! VIERA !! YAMAHA_AVR !! iTunes !! ENIGMA2 !! ONKYO_AVR !! Squeezebox !! PHTV !! PIONEER !! harmony
|-
| '''power''' || || || || {{yes-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} ||
|-
| '''presence''' || || || || {{yes-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}}
|-
| '''volume''' || || || || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}}
|-
| '''volumeStraight''' || || || || {{no-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{no-c}}
|-
| '''mute''' || || || || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{planed-c}}
|-
| '''repeat''' || || || || {{no-c}} || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes2-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{no-c}} || {{planed-c}}
|-
| '''shuffle''' || || || || {{no-c}} || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes2-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{no-c}} || {{planed-c}}
|-
| '''input''' || || || || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{no-c}}
|-
| '''output''' || || || || {{no-c}} || {{no-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{no-c}} || {{no-c}} || {{no-c}} || {{no-c}} || {{no-c}}
|-
| '''channel''' || || || || {{yes-c}} || {{no-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{no-c}}
|-
| '''currentArtist''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes-c}}
|-
| '''currentAlbum''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes-c}}
|-
| '''currentTitle''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes-c}}
|-
| '''currentMedia''' || || || || {{no-c}} || {{no-c}} || {{planed-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{no-c}} ||
|-
| '''playStatus''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{planed-c}} || {{yes2-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{no-c}} ||
|-
| '''state''' || || || || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}}
|-
| '''stateAV''' || || || || {{no-c}} || {{no-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{no-c}}
|}

== Sonstiges ==
=== Wie funktioniert Cover Art? ===
Reading mit URL-Link oder als Gerätestatus???

=== Wie funktionieren Sprachdurchsagen oder Text Einblendungen? ===

Obwohl dies sehr stark davon abhängt, ob das jeweilige Gerät eine solche Funktion unterstützt, oder ob sie anderweitig (z.B. durch Google Service) umgesetzt werden können, so sollen dennoch solche Features über die folgenden Set-Kommandos angeboten werden.
{| class="wikitable"
|-
! Kommando !! Beispiel !! Beschreibung
|-
| '''sayText'''|| <pre>set ''<device>'' sayText "Anruf in Abwesenheit"</pre>
|| Dieses Kommando soll den übergebenen Text auf dem jeweiligen Device in Audio-Form wieder ausgeben. Hierbei kann auf einen Synthese-Anbieter im Internet zurückgegriffen werden, der ein solches Audiosample erzeugt, oder geräteinterne Kommandos verwendet werden, je nach dem was vorhanden und unterstützt wird.
|-
| '''showText''' || <pre>set ''<device>'' showText "Anruf in Abwesenheit"</pre>|| Dieses Kommando soll einen Text z.B. auf dem Display des Gerätes (oder Fernseher) in geeigneter Form anzeigen, sofern das Gerät eine solche Funktion unterstützt.
|-
! colspan="3"| Alternativvorschlag
|-
| '''message''' || <pre>set ''<device>'' message "Anruf in Abwesenheit" [audio|video]</pre>|| Dieses Kommando soll eine Nachricht mit dem Gerät anzeigen (video) oder abspielen (audio), sofern das Gerät eine solche Funktion unterstützt. Ohne die optionale Wiedergabe-Art oder wenn die angegebene nicht unterstützt ist über die von diesem Gerät bevorzugte Methode.
|}

=== Wie funktionieren Playlisten? ===

Sofern anwendbar, sollten diese mit dem Kommando <code>set <device> playlist XY</code> aufrufbar sein. Dabei sollten die zur Verfügung stehenden Playlists bereits bekannt sein und als möglicher Kommando-Parameter angeboten werden.

=== Wie funktionieren Zonen? ===

Jede einzelne Zone eines Gerätes wird durch ein eigenes FHEM-Device repräsentiert. Die gewünschte Zone ist als optionaler Parameter in den Definitions-Argumenten zu übergeben.

Wenn keine bestimmte Zone explizit in der Definition übergeben wird, ist die Hauptzone (Main-Zone) zu verwenden. Die zur Verfügung stehenden Zonen sollten in den Internals aufgelistet sein, mindestens jedoch in der commandref des entsprechenden Moduls.

Jede Definition sollte nur die tatsächlich möglichen Befehle, Eingänge, etc. der entsprechenden Zone anbieten.

[[Kategorie:Development]]

DevelopmentGuidelinesAV

2016-08-21T15:12:14Z

Loredo:

== Einleitung ==
Auf dieser Seite sollen Richtlinien für AV-Module gesammelt werden damit es einfacher wird diese zusammen mit anderen Modulen wie remotecontroll oder LightScene zu verwenden. Auch Benachrichtigungen wie Sprachdurchsagen oder Einblendungen lassen sich universeller verwenden wenn sie bei allen Geräten die dies unterstützen gleich angesprochen werden.

Der Text aus dem ursprünglichen Forumsthread war folgender:

::gerade ist ja mit den tv und verstärker modulen sowie dem remotecontrol modul ziemlich schwung in den bereich audio und video geräte gekommen. zusätzlich gibt es noch eine ganze reihe älterer module wie sonor und xbmc und zwei arten itunes anzusprechen und neue module wie für die web radios oder das raspberry multiroom stehen vor der tür.

::wie wäre es sich rechtzeitig auf ein möglichst einheitiches kommando set zu verständigen damit grundlegende dinge wie play/pause/volume/next bei allen geräten einheitlich, in gleicher schreibweise und mit möglichst ähnlichen parametern funktionieren?

::das würde module wie die remotecontrol aber auch structure und lightscene deutlich einfacher und nützlicher machen und auch alternative frontends erleichtern wenn bestimmte features wie audio,video oder cover über ein einheitliches schema markiert würden.

::mein vorschlag wäre sich an das sonos modul anzulehnen weil es mir in dieser hinsicht am fortgeschrittensten erscheint und auch weitergehende features wie cover oder durchsagen anbietet.

::zu vereinheitlichen wäre dann u.a.:
::- welche kommandos zu welchem zweck
::- kommandos sollten einheitlich geschrieben werden. also z.b. immer klein oder immer mixed case.
::- parameter sollten so weit möglich den gleichen wertebereich haben. also z.b. volume immer von 0-100.
::- wenn es aus irgendeinem grund noch ein gerätespezifischer wertebereich nötig ist sollte der zusätzlich vorhanden sein.
::- cover sollten immer auf die gleiche art gelesen werden können
::- ...

Der Thread ist [http://forum.fhem.de/index.php/topic,13784.0.html hier] zu finden.

== Bezeichner ==
siehe [[DevelopmentGuidelines#Bezeichnungen|Bezeichnungen allgmein]]

== Kommandos ==

Diese Tabelle soll eine einheitliche Definition von set-Befehlen aufzeigen. Dazu zählen auch ggf. Parameter und deren Bedeutung.

{| class="wikitable sortable"
! Name !! Parameter !! Bedeutung
|-
| '''on''' || || Schaltet das Gerät ein, so dass es benutzt werden kann.
|-
| '''off''' || || Schaltet das Gerät aus.
|-
| '''play''' || || Startet das Abspielen von Medien (Video, mp3, Radio stream etc.)
|-
| '''pause''' || || Pausiert das Abspielen von Medien, stoppt es aber nicht.
|-
| '''stop''' || || Stoppt (beendet) das Abspielen von Medien.
|-
| '''volume''' || 0 - 100 || Setzt die Lautstärke auf einen prozentualen Wert.
|-
| '''volumeStraight''' || X-Y || Setzt die Lautstärke auf den absoluten Wert, so wie er vom Gerät tatsächlich verwendet wird (z.B. dB)<br><br>''Nur zu Verwenden, wenn das Gerät einen anderen Wertebereich als 0-100% intern verwendet.''
|-
| '''volumeUp''' || [0 - 100] || Erhöht die Lautstärke um einen gerätespezifischen Schritt (z.b. 5%). Wenn die Schrittweite konfigurierbar ist soll das über das Attribut volumeStep erfolgen. Optional kann das Inkrement als optionaler Parameter mit angegeben werden.
|-
| '''volumeDown''' || [0 - 100] || Verringert die Lautstärke um einen gerätespezifischen Schritt (z.b. 5%). Wenn die Schrittweite konfigurierbar ist soll das über das Attribut volumeStep erfolgen. Optional kann das Dekrement als optionaler Parameter mit angegeben werden.
|-
| '''mute''' || <nowiki>on | off | toggle</nowiki> || Aktiviert, deaktiviert oder schaltet die Mutefunktion = Lautstärke der aktuellen Ausgabe wird verringert bzw. abgschaltet (Gerätespezifisch)
|-
| '''repeat''' || <nowiki>one | all | off</nowiki> || Aktivieren der Repeatfunktion = wiederholen des aktuellen Titels/Albums
|-
| '''shuffle''' || <nowiki>on | off</nowiki> || Aktiviert oder deaktiviert die Shufflefunktion = zufällige Wiedergabe.
|-
| '''channel''' || 0 - 9999 || Schaltet auf einen absoluten Sender- oder Programmspeicherplatz (Nicht zu verwechseln mit input)
|-
| '''channelUp''' || || Springt zum nächsten Sender- oder Programmspeicherplatz.
|-
| '''channelDown''' || || Springt zum vorherigen Sender- oder Programmspeicherplatz.
|-
| '''remoteControl''' || # || Parameter ist Hersteller- und Gerätespezifisch. Funktion bei Geräten, die es erlauben die mitgelieferte Hardware Fernbedienung zu simulieren. Parameter in lowerCamelCaps (ggf. muss im Modul selber auf die Herstellerspezifische Schreibweise umcodiert werden; Alles groß- oder klein geschrieben)
|-
| '''input''' || <nowiki>z.B. hdmi[1-n] | av[1-n] | usb | airplay | server [1-n]</nowiki> || Auswahl von Hardwarekanälen (HDMI, DVB-S, PAL, DVI) oder Softwarekanälen (Airplay, IPTV, IP-Radiostream) die das zu steuernde Gerät aktiv schalten soll (zur Darstellung auf TV, Kanalwahl bei AV-Receivern etc.). Da diese Kanäle je nach Gerät und Modellreihen unterschiedliche Bezeichnungen besitzen, sollten alle möglichen Bezeichnungen in Form von lowerCamelCaps angeboten werden.
|-
| '''output''' || <nowiki>z.B. Airtunes1,Airtunes2,Intern</nowiki> || Auswahl des/der Ausgabegerätes.
|-
| '''statusRequest''' || || Den aktuellen Status des Gerätes abfragen
|-
|colspan="3"| ...
|}

== Readings ==

Diese Tabelle soll eine einheitliche Wertedefinition von Readings. Dazu zählen auch die verwendeten Werte und deren Bedeutung.

Wenn es zwischen reading und zugehörigen set eine 1:1 Beziehung gibt sollte sich der Inhalt des readings als Argument des set verwenden lassen um genau diesen dargestellten Zustand zu erreichen.

{| class="wikitable"
|-
! Name !! mögliche Werte !! Bedeutung
|-
| '''power''' || <nowiki>on|off</nowiki> || Ist das Gerät an oder aus?
|-
| '''presence''' || <nowiki>present|absent</nowiki> || Ist das Gerät aktuell ansprechbar? Sollte das Gerät aufgrund abgeschalteten Stromzufuhr, o.ä. aktuell nicht steuerbar sein, so sollte dies mit dem Wert "absent" verdeutlicht werden. In solch einem Fall sollte ein set-Befehl eine entsprechende Fehlermeldung bringen. Evtl. StatusUpdate-Timer sollten ensprechende Fehlermeldungen nur einmal im Log, etc. festhalten und Fehlermeldungen beim nächsten Status-Update entsprechend unterdrücken um so die Logfiles nicht unnötig vollzuschreiben. Auch das presence reading sollte nur dann aktualisiert werden wenn sich der Status geändert hat um am timestamp sehen zu können wann das war. event-on-change-reading ist hierzu nicht ausreichend weil nur das Event unterdrückt wird der Timestamp sich aber trotzdem ändert.
|-
| '''volume''' || 0-100 || Der prozentuale Lautstärkepegel gemessen der maximal möglichen tatsächlichen Werte.
|-
| '''volumeStraight''' || X-Y || Der tatsächliche Lautstärkepegel des Gerätes, so wie er am Gerät angezeigt/verwendet wird. <br><br>''Nur zu Verwenden, wenn das Gerät einen anderen Wertebereich als 0-100% intern verwendet.''
|-
| '''mute''' || <nowiki>on | off</nowiki> || Ist das Gerät aktuell stumm geschaltet?
|-
| '''repeat''' || <nowiki>one | all | off</nowiki> || Ist das Gerät im repeat modus?
|-
| '''shuffle''' || <nowiki>on | off</nowiki> || Ist das Gerät im shuffle modus?
|-
| '''input''' || ''aktuell gewählter Eingangskanal'' ||
|-
| '''output''' || ''aktuell gewählte(s) Ausgabegerät(e)'' ||
|-
| '''channel''' || ''aktuell gewählter Eingangskanal entsprechend dem Gerät''||
|-
| '''currentArtist''' || ''aktueller Interpret'' ||
|-
| '''currentAlbum''' || ''aktuelles Album'' ||
|-
| '''currentTitle''' || ''aktueller Titelname'' ||
|-
| '''currentMedia''' || ''"Name" der Wiedergabe"datei"'' || kann alles sein: Datei vom Filesystem, Stream aus dem Internet, m3u-URL oder was auch immer
|-
| '''playStatus''' || <nowiki>playing | paused | stopped</nowiki> ||
|-
| '''state''' || <nowiki>on | off | absent</nowiki> || Sofern das Gerät empfangsbereit ist, soll der Schaltzustand des Gerätes (Reading: power, sofern anwendbar) zurückgegeben werden. Ansonsten ist die Abwesenheit des Gerätes durch den Wert "absent" anzuzeigen.
|-
| '''stateAV''' || <nowiki><presence> | <power> | <mute> | <playStatus></nowiki> || Kombiniert den Status von bestehenden Readings zu einer logisch abhängigen Einheit nach folgendem Format: Wenn presence=absent=>absent, sonst power=off=>off, sonst mute=on=>muted, sonst playStatus!=stopped=>playStatus, sonst =>power
|-
|colspan="3"| ...
|}

== Implementation in Modulen ==
{{yes}} = Implementiert {{yes2}} = device spezifisch {{planed}} = Implementation geplant/in Arbeit {{no}} = Nicht implementiert/Keine Implementation geplant

{| class="wikitable"
! set-Befehl !! LGTV !! LISTENLIVE !! STV !! VIERA !! YAMAHA_AVR !! iTunes !! ENIGMA2 !! ONKYO_AVR !! Squeezebox !! PHTV !! PIONEER !! harmony !! plex
|-
| '''on''' || || || || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} ||
|-
| '''off''' || || || || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} ||
|-
| '''play''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{yes-c}}
|-
| '''pause''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{yes-c}}
|-
| '''stop''' || || || || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{yes-c}}
|-
| '''volume''' || || || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}}
|-
| '''volumeStraight''' || || || || {{no-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{planed-c}}|| {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{no-c}}
|-
| '''volumeUp''' || || || || {{yes-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{no-c}}
|-
| '''volumeDown''' || || || || {{yes-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{no-c}}
|-
| '''mute''' || || || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{no-c}}
|-
| '''repeat''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes2-c}} || {{yes-c}} || {{no-c}} || {{yes2-c}} || {{yes2-c}} || {{yes-c}}
|-
| '''shuffle''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes2-c}} || {{yes-c}} || {{no-c}} || {{yes2-c}} || {{yes2-c}} || {{yes-c}}
|-
| '''channel''' || || || || {{yes-c}} || {{no-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{no-c}}
|-
| '''channelUp''' || || || || {{yes-c}} || {{no-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{no-c}}
|-
| '''channelDown''' || || || || {{yes-c}} || {{no-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{no-c}}
|-
| '''remoteControl''' || || || || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes2-c}} || {{yes2-c}} || {{no-c}}
|-
| '''input''' || {{yes-c}} || || || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}}|| {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{no-c}}
|-
| '''output''' || || || || {{no-c}} || {{no-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{no-c}} || {{no-c}} || {{no-c}} || {{yes2-c}} || {{no-c}}
|-
| '''statusRequest''' || || {{yes-c}} || || {{yes-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{no-c}}
|-
! Reading !! LGTV !! LISTENLIVE !! STV !! VIERA !! YAMAHA_AVR !! iTunes !! ENIGMA2 !! ONKYO_AVR !! Squeezebox !! PHTV !! PIONEER !! harmony
|-
| '''power''' || || || || {{yes-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} ||
|-
| '''presence''' || || || || {{yes-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}}
|-
| '''volume''' || || || || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}}
|-
| '''volumeStraight''' || || || || {{no-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{no-c}}
|-
| '''mute''' || || || || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{planed-c}}
|-
| '''repeat''' || || || || {{no-c}} || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes2-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{no-c}} || {{planed-c}}
|-
| '''shuffle''' || || || || {{no-c}} || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes2-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{no-c}} || {{planed-c}}
|-
| '''input''' || || || || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{no-c}}
|-
| '''output''' || || || || {{no-c}} || {{no-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{no-c}} || {{no-c}} || {{no-c}} || {{no-c}} || {{no-c}}
|-
| '''channel''' || || || || {{yes-c}} || {{no-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{no-c}}
|-
| '''currentArtist''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes-c}}
|-
| '''currentAlbum''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes-c}}
|-
| '''currentTitle''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes-c}}
|-
| '''currentMedia''' || || || || {{no-c}} || {{no-c}} || {{planed-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{no-c}} ||
|-
| '''playStatus''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{planed-c}} || {{yes2-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{no-c}} ||
|-
| '''state''' || || || || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}}
|-
| '''stateAV''' || || || || {{no-c}} || {{no-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{no-c}}
|}

== Sonstiges ==
=== Wie funktioniert Cover Art? ===
Reading mit URL-Link oder als Gerätestatus???

=== Wie funktionieren Sprachdurchsagen oder Text Einblendungen? ===

Obwohl dies sehr stark davon abhängt, ob das jeweilige Gerät eine solche Funktion unterstützt, oder ob sie anderweitig (z.B. durch Google Service) umgesetzt werden können, so sollen dennoch solche Features über die folgenden Set-Kommandos angeboten werden.
{| class="wikitable"
|-
! Kommando !! Beispiel !! Beschreibung
|-
| '''sayText'''|| <pre>set ''<device>'' sayText "Anruf in Abwesenheit"</pre>
|| Dieses Kommando soll den übergebenen Text auf dem jeweiligen Device in Audio-Form wieder ausgeben. Hierbei kann auf einen Synthese-Anbieter im Internet zurückgegriffen werden, der ein solches Audiosample erzeugt, oder geräteinterne Kommandos verwendet werden, je nach dem was vorhanden und unterstützt wird.
|-
| '''showText''' || <pre>set ''<device>'' showText "Anruf in Abwesenheit"</pre>|| Dieses Kommando soll einen Text z.B. auf dem Display des Gerätes (oder Fernseher) in geeigneter Form anzeigen, sofern das Gerät eine solche Funktion unterstützt.
|-
! colspan="3"| Alternativvorschlag
|-
| '''message''' || <pre>set ''<device>'' message "Anruf in Abwesenheit" [audio|video]</pre>|| Dieses Kommando soll eine Nachricht mit dem Gerät anzeigen (video) oder abspielen (audio), sofern das Gerät eine solche Funktion unterstützt. Ohne die optionale Wiedergabe-Art oder wenn die angegebene nicht unterstützt ist über die von diesem Gerät bevorzugte Methode.
|}

=== Wie funktionieren Playlisten? ===

Sofern anwendbar, sollten diese mit dem Kommando <code>set <device> playlist XY</code> aufrufbar sein. Dabei sollten die zur Verfügung stehenden Playlists bereits bekannt sein und als möglicher Kommando-Parameter angeboten werden.

=== Wie funktionieren Zonen? ===

Jede einzelne Zone eines Gerätes wird durch ein eigenes FHEM-Device repräsentiert. Die gewünschte Zone ist als optionaler Parameter in den Definitions-Argumenten zu übergeben.

Wenn keine bestimmte Zone explizit in der Definition übergeben wird, ist die Hauptzone (Main-Zone) zu verwenden. Die zur Verfügung stehenden Zonen sollten in den Internals aufgelistet sein, mindestens jedoch in der commandref des entsprechenden Moduls.

Jede Definition sollte nur die tatsächlich möglichen Befehle, Eingänge, etc. der entsprechenden Zone anbieten.

[[Kategorie:Development]]

DevelopmentGuidelinesAV

2016-08-21T15:02:38Z

Loredo:

== Einleitung ==
Auf dieser Seite sollen Richtlinien für AV-Module gesammelt werden damit es einfacher wird diese zusammen mit anderen Modulen wie remotecontroll oder LightScene zu verwenden. Auch Benachrichtigungen wie Sprachdurchsagen oder Einblendungen lassen sich universeller verwenden wenn sie bei allen Geräten die dies unterstützen gleich angesprochen werden.

Der Text aus dem ursprünglichen Forumsthread war folgender:

::gerade ist ja mit den tv und verstärker modulen sowie dem remotecontrol modul ziemlich schwung in den bereich audio und video geräte gekommen. zusätzlich gibt es noch eine ganze reihe älterer module wie sonor und xbmc und zwei arten itunes anzusprechen und neue module wie für die web radios oder das raspberry multiroom stehen vor der tür.

::wie wäre es sich rechtzeitig auf ein möglichst einheitiches kommando set zu verständigen damit grundlegende dinge wie play/pause/volume/next bei allen geräten einheitlich, in gleicher schreibweise und mit möglichst ähnlichen parametern funktionieren?

::das würde module wie die remotecontrol aber auch structure und lightscene deutlich einfacher und nützlicher machen und auch alternative frontends erleichtern wenn bestimmte features wie audio,video oder cover über ein einheitliches schema markiert würden.

::mein vorschlag wäre sich an das sonos modul anzulehnen weil es mir in dieser hinsicht am fortgeschrittensten erscheint und auch weitergehende features wie cover oder durchsagen anbietet.

::zu vereinheitlichen wäre dann u.a.:
::- welche kommandos zu welchem zweck
::- kommandos sollten einheitlich geschrieben werden. also z.b. immer klein oder immer mixed case.
::- parameter sollten so weit möglich den gleichen wertebereich haben. also z.b. volume immer von 0-100.
::- wenn es aus irgendeinem grund noch ein gerätespezifischer wertebereich nötig ist sollte der zusätzlich vorhanden sein.
::- cover sollten immer auf die gleiche art gelesen werden können
::- ...

Der Thread ist [http://forum.fhem.de/index.php/topic,13784.0.html hier] zu finden.

== Bezeichner ==
siehe [[DevelopmentGuidelines#Bezeichnungen|Bezeichnungen allgmein]]

== Kommandos ==

Diese Tabelle soll eine einheitliche Definition von set-Befehlen aufzeigen. Dazu zählen auch ggf. Parameter und deren Bedeutung.

{| class="wikitable sortable"
! Name !! Parameter !! Bedeutung
|-
| '''on''' || || Schaltet das Gerät ein, so dass es benutzt werden kann.
|-
| '''off''' || || Schaltet das Gerät aus.
|-
| '''play''' || || Startet das Abspielen von Medien (Video, mp3, Radio stream etc.)
|-
| '''pause''' || || Pausiert das Abspielen von Medien, stoppt es aber nicht.
|-
| '''stop''' || || Stoppt (beendet) das Abspielen von Medien.
|-
| '''volume''' || 0 - 100 || Setzt die Lautstärke auf einen prozentualen Wert.
|-
| '''volumeStraight''' || X-Y || Setzt die Lautstärke auf den absoluten Wert, so wie er vom Gerät tatsächlich verwendet wird (z.B. dB)<br><br>''Nur zu Verwenden, wenn das Gerät einen anderen Wertebereich als 0-100% intern verwendet.''
|-
| '''volumeUp''' || [0 - 100] || Erhöht die Lautstärke um einen gerätespezifischen Schritt (z.b. 5%). Wenn die Schrittweite konfigurierbar ist soll das über das Attribut volumeStep erfolgen. Optional kann das Inkrement als optionaler Parameter mit angegeben werden.
|-
| '''volumeDown''' || [0 - 100] || Verringert die Lautstärke um einen gerätespezifischen Schritt (z.b. 5%). Wenn die Schrittweite konfigurierbar ist soll das über das Attribut volumeStep erfolgen. Optional kann das Dekrement als optionaler Parameter mit angegeben werden.
|-
| '''mute''' || <nowiki>on | off | toggle</nowiki> || Aktiviert, deaktiviert oder schaltet die Mutefunktion = Lautstärke der aktuellen Ausgabe wird verringert bzw. abgschaltet (Gerätespezifisch)
|-
| '''repeat''' || <nowiki>one | all | off</nowiki> || Aktivieren der Repeatfunktion = wiederholen des aktuellen Titels/Albums
|-
| '''shuffle''' || <nowiki>on | off</nowiki> || Aktiviert oder deaktiviert die Shufflefunktion = zufällige Wiedergabe.
|-
| '''channel''' || 0 - 9999 || Schaltet auf einen absoluten Sender- oder Programmspeicherplatz (Nicht zu verwechseln mit input)
|-
| '''channelUp''' || || Springt zum nächsten Sender- oder Programmspeicherplatz.
|-
| '''channelDown''' || || Springt zum vorherigen Sender- oder Programmspeicherplatz.
|-
| '''remoteControl''' || # || Parameter ist Hersteller- und Gerätespezifisch. Funktion bei Geräten, die es erlauben die mitgelieferte Hardware Fernbedienung zu simulieren. Parameter in lowerCamelCaps (ggf. muss im Modul selber auf die Herstellerspezifische Schreibweise umcodiert werden; Alles groß- oder klein geschrieben)
|-
| '''input''' || <nowiki>z.B. hdmi[1-n] | av[1-n] | usb | airplay | server [1-n]</nowiki> || Auswahl von Hardwarekanälen (HDMI, DVB-S, PAL, DVI) oder Softwarekanälen (Airplay, IPTV, IP-Radiostream) die das zu steuernde Gerät aktiv schalten soll (zur Darstellung auf TV, Kanalwahl bei AV-Receivern etc.). Da diese Kanäle je nach Gerät und Modellreihen unterschiedliche Bezeichnungen besitzen, sollten alle möglichen Bezeichnungen in Form von lowerCamelCaps angeboten werden.
|-
| '''output''' || <nowiki>z.B. Airtunes1,Airtunes2,Intern</nowiki> || Auswahl des/der Ausgabegerätes.
|-
| '''statusRequest''' || || Den aktuellen Status des Gerätes abfragen
|-
|colspan="3"| ...
|}

== Readings ==

Diese Tabelle soll eine einheitliche Wertedefinition von Readings. Dazu zählen auch die verwendeten Werte und deren Bedeutung.

Wenn es zwischen reading und zugehörigen set eine 1:1 Beziehung gibt sollte sich der Inhalt des readings als Argument des set verwenden lassen um genau diesen dargestellten Zustand zu erreichen.

{| class="wikitable"
|-
! Name !! mögliche Werte !! Bedeutung
|-
| '''power''' || <nowiki>on|off</nowiki> || Ist das Gerät an oder aus?
|-
| '''presence''' || <nowiki>present|absent</nowiki> || Ist das Gerät aktuell ansprechbar? Sollte das Gerät aufgrund abgeschalteten Stromzufuhr, o.ä. aktuell nicht steuerbar sein, so sollte dies mit dem Wert "absent" verdeutlicht werden. In solch einem Fall sollte ein set-Befehl eine entsprechende Fehlermeldung bringen. Evtl. StatusUpdate-Timer sollten ensprechende Fehlermeldungen nur einmal im Log, etc. festhalten und Fehlermeldungen beim nächsten Status-Update entsprechend unterdrücken um so die Logfiles nicht unnötig vollzuschreiben. Auch das presence reading sollte nur dann aktualisiert werden wenn sich der Status geändert hat um am timestamp sehen zu können wann das war. event-on-change-reading ist hierzu nicht ausreichend weil nur das Event unterdrückt wird der Timestamp sich aber trotzdem ändert.
|-
| '''volume''' || 0-100 || Der prozentuale Lautstärkepegel gemessen der maximal möglichen tatsächlichen Werte.
|-
| '''volumeStraight''' || X-Y || Der tatsächliche Lautstärkepegel des Gerätes, so wie er am Gerät angezeigt/verwendet wird. <br><br>''Nur zu Verwenden, wenn das Gerät einen anderen Wertebereich als 0-100% intern verwendet.''
|-
| '''mute''' || <nowiki>on | off</nowiki> || Ist das Gerät aktuell stumm geschaltet?
|-
| '''repeat''' || <nowiki>one | all | off</nowiki> || Ist das Gerät im repeat modus?
|-
| '''shuffle''' || <nowiki>on | off</nowiki> || Ist das Gerät im shuffle modus?
|-
| '''input''' || ''aktuell gewählter Eingangskanal'' ||
|-
| '''output''' || ''aktuell gewählte(s) Ausgabegerät(e)'' ||
|-
| '''channel''' || ''aktuell gewählter Eingangskanal entsprechend dem Gerät''||
|-
| '''currentArtist''' || ''aktueller Interpret'' ||
|-
| '''currentAlbum''' || ''aktuelles Album'' ||
|-
| '''currentTitle''' || ''aktueller Titelname'' ||
|-
| '''currentMedia''' || ''"Name" der Wiedergabe"datei"'' || kann alles sein: Datei vom Filesystem, Stream aus dem Internet, m3u-URL oder was auch immer
|-
| '''playStatus''' || <nowiki>playing | paused | stopped</nowiki> ||
|-
| '''state''' || <nowiki>on | off | absent</nowiki> || Sofern das Gerät empfangsbereit ist, soll der Schaltzustand des Gerätes (Reading: power, sofern anwendbar) zurückgegeben werden. Ansonsten ist die Abwesenheit des Gerätes durch den Wert "absent" anzuzeigen.
|-
| '''stateAV''' || <nowiki><presence> | <power> | <mute> | <playStatus></nowiki> || Kombiniert den Status von bestehenden Readings zu einer logisch abhängigen Einheit nach folgendem Format: Wenn presence=absent=>absent, sonst power=off=>off, sonst mute=on=>muted, sonst playStatus!=stopped=>playStatus, sonst =>power
|-
|colspan="3"| ...
|}

== Implementation in Modulen ==
{{yes}} = Implementiert {{yes2}} = device spezifisch {{planed}} = Implementation geplant/in Arbeit {{no}} = Nicht implementiert/Keine Implementation geplant

{| class="wikitable"
! set-Befehl !! LGTV !! LISTENLIVE !! STV !! VIERA !! YAMAHA_AVR !! iTunes !! ENIGMA2 !! ONKYO_AVR !! Squeezebox !! PHTV !! PIONEER !! harmony !! plex
|-
| '''on''' || || || || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} ||
|-
| '''off''' || || || || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} ||
|-
| '''play''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{yes-c}}
|-
| '''pause''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{yes-c}}
|-
| '''stop''' || || || || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{yes-c}}
|-
| '''volume''' || || || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}}
|-
| '''volumeStraight''' || || || || {{no-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{planed-c}}|| {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{no-c}}
|-
| '''volumeUp''' || || || || {{yes-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{no-c}}
|-
| '''volumeDown''' || || || || {{yes-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{no-c}}
|-
| '''mute''' || || || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{no-c}}
|-
| '''repeat''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes2-c}} || {{yes-c}} || {{no-c}} || {{yes2-c}} || {{yes2-c}} || {{yes-c}}
|-
| '''shuffle''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes2-c}} || {{yes-c}} || {{no-c}} || {{yes2-c}} || {{yes2-c}} || {{yes-c}}
|-
| '''channel''' || || || || {{yes-c}} || {{no-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{no-c}}
|-
| '''channelUp''' || || || || {{yes-c}} || {{no-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{no-c}}
|-
| '''channelDown''' || || || || {{yes-c}} || {{no-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{no-c}}
|-
| '''remoteControl''' || || || || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes2-c}} || {{yes2-c}} || {{no-c}}
|-
| '''input''' || {{yes-c}} || || || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}}|| {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{no-c}}
|-
| '''output''' || || || || {{no-c}} || {{no-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{no-c}} || {{no-c}} || {{no-c}} || {{yes2-c}} || {{no-c}}
|-
| '''statusRequest''' || || {{yes-c}} || || {{yes-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{no-c}}
|-
! Reading !! LGTV !! LISTENLIVE !! STV !! VIERA !! YAMAHA_AVR !! iTunes !! ENIGMA2 !! ONKYO_AVR !! Squeezebox !! PHTV !! PIONEER !! harmony
|-
| '''power''' || || || || {{yes-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} ||
|-
| '''presence''' || || || || {{yes-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}}
|-
| '''volume''' || || || || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}}
|-
| '''volumeStraight''' || || || || {{no-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{no-c}}
|-
| '''mute''' || || || || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{planed-c}}
|-
| '''repeat''' || || || || {{no-c}} || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes2-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{no-c}} || {{planed-c}}
|-
| '''shuffle''' || || || || {{no-c}} || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes2-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{no-c}} || {{planed-c}}
|-
| '''input''' || || || || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{no-c}}
|-
| '''output''' || || || || {{no-c}} || {{no-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{no-c}} || {{no-c}} || {{no-c}} || {{no-c}} || {{no-c}}
|-
| '''channel''' || || || || {{yes-c}} || {{no-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{no-c}}
|-
| '''currentArtist''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes-c}}
|-
| '''currentAlbum''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes-c}}
|-
| '''currentTitle''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes-c}}
|-
| '''currentMedia''' || || || || {{no-c}} || {{no-c}} || {{planed-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{no-c}} ||
|-
| '''playStatus''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{no-c}} ||
|-
| '''state''' || || || || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}}
|-
| '''stateAV''' || || || || {{no-c}} || {{no-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{no-c}}
|}

== Sonstiges ==
=== Wie funktioniert Cover Art? ===
Reading mit URL-Link oder als Gerätestatus???

=== Wie funktionieren Sprachdurchsagen oder Text Einblendungen? ===

Obwohl dies sehr stark davon abhängt, ob das jeweilige Gerät eine solche Funktion unterstützt, oder ob sie anderweitig (z.B. durch Google Service) umgesetzt werden können, so sollen dennoch solche Features über die folgenden Set-Kommandos angeboten werden.
{| class="wikitable"
|-
! Kommando !! Beispiel !! Beschreibung
|-
| '''sayText'''|| <pre>set ''<device>'' sayText "Anruf in Abwesenheit"</pre>
|| Dieses Kommando soll den übergebenen Text auf dem jeweiligen Device in Audio-Form wieder ausgeben. Hierbei kann auf einen Synthese-Anbieter im Internet zurückgegriffen werden, der ein solches Audiosample erzeugt, oder geräteinterne Kommandos verwendet werden, je nach dem was vorhanden und unterstützt wird.
|-
| '''showText''' || <pre>set ''<device>'' showText "Anruf in Abwesenheit"</pre>|| Dieses Kommando soll einen Text z.B. auf dem Display des Gerätes (oder Fernseher) in geeigneter Form anzeigen, sofern das Gerät eine solche Funktion unterstützt.
|-
! colspan="3"| Alternativvorschlag
|-
| '''message''' || <pre>set ''<device>'' message "Anruf in Abwesenheit" [audio|video]</pre>|| Dieses Kommando soll eine Nachricht mit dem Gerät anzeigen (video) oder abspielen (audio), sofern das Gerät eine solche Funktion unterstützt. Ohne die optionale Wiedergabe-Art oder wenn die angegebene nicht unterstützt ist über die von diesem Gerät bevorzugte Methode.
|}

=== Wie funktionieren Playlisten? ===

Sofern anwendbar, sollten diese mit dem Kommando <code>set <device> playlist XY</code> aufrufbar sein. Dabei sollten die zur Verfügung stehenden Playlists bereits bekannt sein und als möglicher Kommando-Parameter angeboten werden.

=== Wie funktionieren Zonen? ===

Jede einzelne Zone eines Gerätes wird durch ein eigenes FHEM-Device repräsentiert. Die gewünschte Zone ist als optionaler Parameter in den Definitions-Argumenten zu übergeben.

Wenn keine bestimmte Zone explizit in der Definition übergeben wird, ist die Hauptzone (Main-Zone) zu verwenden. Die zur Verfügung stehenden Zonen sollten in den Internals aufgelistet sein, mindestens jedoch in der commandref des entsprechenden Moduls.

Jede Definition sollte nur die tatsächlich möglichen Befehle, Eingänge, etc. der entsprechenden Zone anbieten.

[[Kategorie:Development]]

DevelopmentGuidelinesAV

2016-08-21T14:09:21Z

Loredo:

== Einleitung ==
Auf dieser Seite sollen Richtlinien für AV-Module gesammelt werden damit es einfacher wird diese zusammen mit anderen Modulen wie remotecontroll oder LightScene zu verwenden. Auch Benachrichtigungen wie Sprachdurchsagen oder Einblendungen lassen sich universeller verwenden wenn sie bei allen Geräten die dies unterstützen gleich angesprochen werden.

Der Text aus dem ursprünglichen Forumsthread war folgender:

::gerade ist ja mit den tv und verstärker modulen sowie dem remotecontrol modul ziemlich schwung in den bereich audio und video geräte gekommen. zusätzlich gibt es noch eine ganze reihe älterer module wie sonor und xbmc und zwei arten itunes anzusprechen und neue module wie für die web radios oder das raspberry multiroom stehen vor der tür.

::wie wäre es sich rechtzeitig auf ein möglichst einheitiches kommando set zu verständigen damit grundlegende dinge wie play/pause/volume/next bei allen geräten einheitlich, in gleicher schreibweise und mit möglichst ähnlichen parametern funktionieren?

::das würde module wie die remotecontrol aber auch structure und lightscene deutlich einfacher und nützlicher machen und auch alternative frontends erleichtern wenn bestimmte features wie audio,video oder cover über ein einheitliches schema markiert würden.

::mein vorschlag wäre sich an das sonos modul anzulehnen weil es mir in dieser hinsicht am fortgeschrittensten erscheint und auch weitergehende features wie cover oder durchsagen anbietet.

::zu vereinheitlichen wäre dann u.a.:
::- welche kommandos zu welchem zweck
::- kommandos sollten einheitlich geschrieben werden. also z.b. immer klein oder immer mixed case.
::- parameter sollten so weit möglich den gleichen wertebereich haben. also z.b. volume immer von 0-100.
::- wenn es aus irgendeinem grund noch ein gerätespezifischer wertebereich nötig ist sollte der zusätzlich vorhanden sein.
::- cover sollten immer auf die gleiche art gelesen werden können
::- ...

Der Thread ist [http://forum.fhem.de/index.php/topic,13784.0.html hier] zu finden.

== Bezeichner ==
siehe [[DevelopmentGuidelines#Bezeichnungen|Bezeichnungen allgmein]]

== Kommandos ==

Diese Tabelle soll eine einheitliche Definition von set-Befehlen aufzeigen. Dazu zählen auch ggf. Parameter und deren Bedeutung.

{| class="wikitable sortable"
! Name !! Parameter !! Bedeutung
|-
| '''on''' || || Schaltet das Gerät ein, so dass es benutzt werden kann.
|-
| '''off''' || || Schaltet das Gerät aus.
|-
| '''play''' || || Startet das Abspielen von Medien (Video, mp3, Radio stream etc.)
|-
| '''pause''' || || Pausiert das Abspielen von Medien, stoppt es aber nicht.
|-
| '''stop''' || || Stoppt (beendet) das Abspielen von Medien.
|-
| '''volume''' || 0 - 100 || Setzt die Lautstärke auf einen prozentualen Wert.
|-
| '''volumeStraight''' || X-Y || Setzt die Lautstärke auf den absoluten Wert, so wie er vom Gerät tatsächlich verwendet wird (z.B. dB)<br><br>''Nur zu Verwenden, wenn das Gerät einen anderen Wertebereich als 0-100% intern verwendet.''
|-
| '''volumeUp''' || [0 - 100] || Erhöht die Lautstärke um einen gerätespezifischen Schritt (z.b. 5%). Wenn die Schrittweite konfigurierbar ist soll das über das Attribut volumeStep erfolgen. Optional kann das Inkrement als optionaler Parameter mit angegeben werden.
|-
| '''volumeDown''' || [0 - 100] || Verringert die Lautstärke um einen gerätespezifischen Schritt (z.b. 5%). Wenn die Schrittweite konfigurierbar ist soll das über das Attribut volumeStep erfolgen. Optional kann das Dekrement als optionaler Parameter mit angegeben werden.
|-
| '''mute''' || <nowiki>on | off | toggle</nowiki> || Aktiviert, deaktiviert oder schaltet die Mutefunktion = Lautstärke der aktuellen Ausgabe wird verringert bzw. abgschaltet (Gerätespezifisch)
|-
| '''repeat''' || <nowiki>one | all | off</nowiki> || Aktivieren der Repeatfunktion = wiederholen des aktuellen Titels/Albums
|-
| '''shuffle''' || <nowiki>on | off</nowiki> || Aktiviert oder deaktiviert die Shufflefunktion = zufällige Wiedergabe.
|-
| '''channel''' || 0 - 9999 || Schaltet auf einen absoluten Sender- oder Programmspeicherplatz (Nicht zu verwechseln mit input)
|-
| '''channelUp''' || || Springt zum nächsten Sender- oder Programmspeicherplatz.
|-
| '''channelDown''' || || Springt zum vorherigen Sender- oder Programmspeicherplatz.
|-
| '''remoteControl''' || # || Parameter ist Hersteller- und Gerätespezifisch. Funktion bei Geräten, die es erlauben die mitgelieferte Hardware Fernbedienung zu simulieren. Parameter in lowerCamelCaps (ggf. muss im Modul selber auf die Herstellerspezifische Schreibweise umcodiert werden; Alles groß- oder klein geschrieben)
|-
| '''input''' || <nowiki>z.B. hdmi[1-n] | av[1-n] | usb | airplay | server [1-n]</nowiki> || Auswahl von Hardwarekanälen (HDMI, DVB-S, PAL, DVI) oder Softwarekanälen (Airplay, IPTV, IP-Radiostream) die das zu steuernde Gerät aktiv schalten soll (zur Darstellung auf TV, Kanalwahl bei AV-Receivern etc.). Da diese Kanäle je nach Gerät und Modellreihen unterschiedliche Bezeichnungen besitzen, sollten alle möglichen Bezeichnungen in Form von lowerCamelCaps angeboten werden.
|-
| '''output''' || <nowiki>z.B. Airtunes1,Airtunes2,Intern</nowiki> || Auswahl des/der Ausgabegerätes.
|-
| '''statusRequest''' || || Den aktuellen Status des Gerätes abfragen
|-
|colspan="3"| ...
|}

== Readings ==

Diese Tabelle soll eine einheitliche Wertedefinition von Readings. Dazu zählen auch die verwendeten Werte und deren Bedeutung.

Wenn es zwischen reading und zugehörigen set eine 1:1 Beziehung gibt sollte sich der Inhalt des readings als Argument des set verwenden lassen um genau diesen dargestellten Zustand zu erreichen.

{| class="wikitable"
|-
! Name !! mögliche Werte !! Bedeutung
|-
| '''power''' || <nowiki>on|off</nowiki> || Ist das Gerät an oder aus?
|-
| '''presence''' || <nowiki>present|absent</nowiki> || Ist das Gerät aktuell ansprechbar? Sollte das Gerät aufgrund abgeschalteten Stromzufuhr, o.ä. aktuell nicht steuerbar sein, so sollte dies mit dem Wert "absent" verdeutlicht werden. In solch einem Fall sollte ein set-Befehl eine entsprechende Fehlermeldung bringen. Evtl. StatusUpdate-Timer sollten ensprechende Fehlermeldungen nur einmal im Log, etc. festhalten und Fehlermeldungen beim nächsten Status-Update entsprechend unterdrücken um so die Logfiles nicht unnötig vollzuschreiben. Auch das presence reading sollte nur dann aktualisiert werden wenn sich der Status geändert hat um am timestamp sehen zu können wann das war. event-on-change-reading ist hierzu nicht ausreichend weil nur das Event unterdrückt wird der Timestamp sich aber trotzdem ändert.
|-
| '''volume''' || 0-100 || Der prozentuale Lautstärkepegel gemessen der maximal möglichen tatsächlichen Werte.
|-
| '''volumeStraight''' || X-Y || Der tatsächliche Lautstärkepegel des Gerätes, so wie er am Gerät angezeigt/verwendet wird. <br><br>''Nur zu Verwenden, wenn das Gerät einen anderen Wertebereich als 0-100% intern verwendet.''
|-
| '''mute''' || <nowiki>on | off</nowiki> || Ist das Gerät aktuell stumm geschaltet?
|-
| '''repeat''' || <nowiki>one | all | off</nowiki> || Ist das Gerät im repeat modus?
|-
| '''shuffle''' || <nowiki>on | off</nowiki> || Ist das Gerät im shuffle modus?
|-
| '''input''' || ''aktuell gewählter Eingangskanal'' ||
|-
| '''output''' || ''aktuell gewählte(s) Ausgabegerät(e)'' ||
|-
| '''channel''' || ''aktuell gewählter Eingangskanal entsprechend dem Gerät''||
|-
| '''currentArtist''' || ''aktueller Interpret'' ||
|-
| '''currentAlbum''' || ''aktuelles Album'' ||
|-
| '''currentTitle''' || ''aktueller Titelname'' ||
|-
| '''currentMedia''' || ''"Name" der Wiedergabe"datei"'' || kann alles sein: Datei vom Filesystem, Stream aus dem Internet, m3u-URL oder was auch immer
|-
| '''playStatus''' || <nowiki>playing | paused | stopped</nowiki> ||
|-
| '''state''' || <nowiki>on | off | absent</nowiki> || Sofern das Gerät empfangsbereit ist, soll der Schaltzustand des Gerätes (Reading: power, sofern anwendbar) zurückgegeben werden. Ansonsten ist die Abwesenheit des Gerätes durch den Wert "absent" anzuzeigen.
|-
| '''stateAV''' || <nowiki><presence> | <power> | <mute> | <playStatus></nowiki> || Kombiniert den Status von bestehenden Readings zu einer logisch abhängigen Einheit nach folgendem Format: Wenn presence=absent=>absent, sonst power=off=>off, sonst mute=on=>muted, sonst playStatus!=stopped=>playStatus, sonst =>power
|-
|colspan="3"| ...
|}

== Implementation in Modulen ==
{{yes}} = Implementiert {{yes2}} = device spezifisch {{planed}} = Implementation geplant/in Arbeit {{no}} = Nicht implementiert/Keine Implementation geplant

{| class="wikitable"
! set-Befehl !! LGTV !! LISTENLIVE !! STV !! VIERA !! YAMAHA_AVR !! iTunes !! ENIGMA2 !! ONKYO_AVR !! Squeezebox !! PHTV !! PIONEER !! harmony !! plex
|-
| '''on''' || || || || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} ||
|-
| '''off''' || || || || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} ||
|-
| '''play''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{yes-c}}
|-
| '''pause''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{yes-c}}
|-
| '''stop''' || || || || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{yes-c}}
|-
| '''volume''' || || || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}}
|-
| '''volumeStraight''' || || || || {{no-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{planed-c}}|| {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{no-c}}
|-
| '''volumeUp''' || || || || {{yes-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{no-c}}
|-
| '''volumeDown''' || || || || {{yes-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{no-c}}
|-
| '''mute''' || || || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{no-c}}
|-
| '''repeat''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes2-c}} || {{yes-c}} || {{no-c}} || {{yes2-c}} || {{yes2-c}} || {{yes-c}}
|-
| '''shuffle''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes2-c}} || {{yes-c}} || {{no-c}} || {{yes2-c}} || {{yes2-c}} || {{yes-c}}
|-
| '''channel''' || || || || {{yes-c}} || {{no-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{no-c}}
|-
| '''channelUp''' || || || || {{yes-c}} || {{no-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{no-c}}
|-
| '''channelDown''' || || || || {{yes-c}} || {{no-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{no-c}}
|-
| '''remoteControl''' || || || || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes2-c}} || {{yes2-c}} || {{no-c}}
|-
| '''input''' || {{yes-c}} || || || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}}|| {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{no-c}}
|-
| '''output''' || || || || {{no-c}} || {{no-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{no-c}} || {{no-c}} || {{no-c}} || {{yes2-c}} || {{no-c}}
|-
| '''statusRequest''' || || {{yes-c}} || || {{yes-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{no-c}}
|-
! Reading !! LGTV !! LISTENLIVE !! STV !! VIERA !! YAMAHA_AVR !! iTunes !! ENIGMA2 !! ONKYO_AVR !! Squeezebox !! PHTV !! PIONEER !! harmony
|-
| '''power''' || || || || {{yes-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} ||
|-
| '''presence''' || || || || {{yes-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}}
|-
| '''volume''' || || || || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}}
|-
| '''volumeStraight''' || || || || {{no-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{no-c}}
|-
| '''mute''' || || || || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{planed-c}}
|-
| '''repeat''' || || || || {{no-c}} || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes2-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{no-c}} || {{planed-c}}
|-
| '''shuffle''' || || || || {{no-c}} || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes2-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{no-c}} || {{planed-c}}
|-
| '''input''' || || || || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{no-c}}
|-
| '''output''' || || || || {{no-c}} || {{no-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{no-c}} || {{no-c}} || {{no-c}} || {{no-c}} || {{no-c}}
|-
| '''channel''' || || || || {{yes-c}} || {{no-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{no-c}}
|-
| '''currentArtist''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes-c}}
|-
| '''currentAlbum''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes-c}}
|-
| '''currentTitle''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes-c}}
|-
| '''currentMedia''' || || || || {{no-c}} || {{no-c}} || {{planed-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{no-c}} ||
|-
| '''playStatus''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{no-c}} ||
|-
| '''state''' || || || || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}}
|-
| '''stateAV''' || || || || {{no-c}} || {{no-c}} || {{no-c}} || {{planed-c}} || {{yes-c}} || {{no-c}} || {{planed-c}} || {{no-c}} || {{no-c}} || {{no-c}}
|}

== Sonstiges ==
=== Wie funktioniert Cover Art? ===
Reading mit URL-Link oder als Gerätestatus???

=== Wie funktionieren Sprachdurchsagen oder Text Einblendungen? ===

Obwohl dies sehr stark davon abhängt, ob das jeweilige Gerät eine solche Funktion unterstützt, oder ob sie anderweitig (z.B. durch Google Service) umgesetzt werden können, so sollen dennoch solche Features über die folgenden Set-Kommandos angeboten werden.
{| class="wikitable"
|-
! Kommando !! Beispiel !! Beschreibung
|-
| '''sayText'''|| <pre>set ''<device>'' sayText "Anruf in Abwesenheit"</pre>
|| Dieses Kommando soll den übergebenen Text auf dem jeweiligen Device in Audio-Form wieder ausgeben. Hierbei kann auf einen Synthese-Anbieter im Internet zurückgegriffen werden, der ein solches Audiosample erzeugt, oder geräteinterne Kommandos verwendet werden, je nach dem was vorhanden und unterstützt wird.
|-
| '''showText''' || <pre>set ''<device>'' showText "Anruf in Abwesenheit"</pre>|| Dieses Kommando soll einen Text z.B. auf dem Display des Gerätes (oder Fernseher) in geeigneter Form anzeigen, sofern das Gerät eine solche Funktion unterstützt.
|-
! colspan="3"| Alternativvorschlag
|-
| '''message''' || <pre>set ''<device>'' message "Anruf in Abwesenheit" [audio|video]</pre>|| Dieses Kommando soll eine Nachricht mit dem Gerät anzeigen (video) oder abspielen (audio), sofern das Gerät eine solche Funktion unterstützt. Ohne die optionale Wiedergabe-Art oder wenn die angegebene nicht unterstützt ist über die von diesem Gerät bevorzugte Methode.
|}

=== Wie funktionieren Playlisten? ===

Sofern anwendbar, sollten diese mit dem Kommando <code>set <device> playlist XY</code> aufrufbar sein. Dabei sollten die zur Verfügung stehenden Playlists bereits bekannt sein und als möglicher Kommando-Parameter angeboten werden.

=== Wie funktionieren Zonen? ===

Jede einzelne Zone eines Gerätes wird durch ein eigenes FHEM-Device repräsentiert. Die gewünschte Zone ist als optionaler Parameter in den Definitions-Argumenten zu übergeben.

Wenn keine bestimmte Zone explizit in der Definition übergeben wird, ist die Hauptzone (Main-Zone) zu verwenden. Die zur Verfügung stehenden Zonen sollten in den Internals aufgelistet sein, mindestens jedoch in der commandref des entsprechenden Moduls.

Jede Definition sollte nur die tatsächlich möglichen Befehle, Eingänge, etc. der entsprechenden Zone anbieten.

[[Kategorie:Development]]

DevelopmentGuidelinesAV

2016-08-21T14:00:48Z

Loredo:

== Einleitung ==
Auf dieser Seite sollen Richtlinien für AV-Module gesammelt werden damit es einfacher wird diese zusammen mit anderen Modulen wie remotecontroll oder LightScene zu verwenden. Auch Benachrichtigungen wie Sprachdurchsagen oder Einblendungen lassen sich universeller verwenden wenn sie bei allen Geräten die dies unterstützen gleich angesprochen werden.

Der Text aus dem ursprünglichen Forumsthread war folgender:

::gerade ist ja mit den tv und verstärker modulen sowie dem remotecontrol modul ziemlich schwung in den bereich audio und video geräte gekommen. zusätzlich gibt es noch eine ganze reihe älterer module wie sonor und xbmc und zwei arten itunes anzusprechen und neue module wie für die web radios oder das raspberry multiroom stehen vor der tür.

::wie wäre es sich rechtzeitig auf ein möglichst einheitiches kommando set zu verständigen damit grundlegende dinge wie play/pause/volume/next bei allen geräten einheitlich, in gleicher schreibweise und mit möglichst ähnlichen parametern funktionieren?

::das würde module wie die remotecontrol aber auch structure und lightscene deutlich einfacher und nützlicher machen und auch alternative frontends erleichtern wenn bestimmte features wie audio,video oder cover über ein einheitliches schema markiert würden.

::mein vorschlag wäre sich an das sonos modul anzulehnen weil es mir in dieser hinsicht am fortgeschrittensten erscheint und auch weitergehende features wie cover oder durchsagen anbietet.

::zu vereinheitlichen wäre dann u.a.:
::- welche kommandos zu welchem zweck
::- kommandos sollten einheitlich geschrieben werden. also z.b. immer klein oder immer mixed case.
::- parameter sollten so weit möglich den gleichen wertebereich haben. also z.b. volume immer von 0-100.
::- wenn es aus irgendeinem grund noch ein gerätespezifischer wertebereich nötig ist sollte der zusätzlich vorhanden sein.
::- cover sollten immer auf die gleiche art gelesen werden können
::- ...

Der Thread ist [http://forum.fhem.de/index.php/topic,13784.0.html hier] zu finden.

== Bezeichner ==
siehe [[DevelopmentGuidelines#Bezeichnungen|Bezeichnungen allgmein]]

== Kommandos ==

Diese Tabelle soll eine einheitliche Definition von set-Befehlen aufzeigen. Dazu zählen auch ggf. Parameter und deren Bedeutung.

{| class="wikitable sortable"
! Name !! Parameter !! Bedeutung
|-
| '''on''' || || Schaltet das Gerät ein, so dass es benutzt werden kann.
|-
| '''off''' || || Schaltet das Gerät aus.
|-
| '''play''' || || Startet das Abspielen von Medien (Video, mp3, Radio stream etc.)
|-
| '''pause''' || || Pausiert das Abspielen von Medien, stoppt es aber nicht.
|-
| '''stop''' || || Stoppt (beendet) das Abspielen von Medien.
|-
| '''volume''' || 0 - 100 || Setzt die Lautstärke auf einen prozentualen Wert.
|-
| '''volumeStraight''' || X-Y || Setzt die Lautstärke auf den absoluten Wert, so wie er vom Gerät tatsächlich verwendet wird (z.B. dB)<br><br>''Nur zu Verwenden, wenn das Gerät einen anderen Wertebereich als 0-100% intern verwendet.''
|-
| '''volumeUp''' || [0 - 100] || Erhöht die Lautstärke um einen gerätespezifischen Schritt (z.b. 5%). Wenn die Schrittweite konfigurierbar ist soll das über das Attribut volumeStep erfolgen. Optional kann das Inkrement als optionaler Parameter mit angegeben werden.
|-
| '''volumeDown''' || [0 - 100] || Verringert die Lautstärke um einen gerätespezifischen Schritt (z.b. 5%). Wenn die Schrittweite konfigurierbar ist soll das über das Attribut volumeStep erfolgen. Optional kann das Dekrement als optionaler Parameter mit angegeben werden.
|-
| '''mute''' || <nowiki>on | off | toggle</nowiki> || Aktiviert, deaktiviert oder schaltet die Mutefunktion = Lautstärke der aktuellen Ausgabe wird verringert bzw. abgschaltet (Gerätespezifisch)
|-
| '''repeat''' || <nowiki>one | all | off</nowiki> || Aktivieren der Repeatfunktion = wiederholen des aktuellen Titels/Albums
|-
| '''shuffle''' || <nowiki>on | off</nowiki> || Aktiviert oder deaktiviert die Shufflefunktion = zufällige Wiedergabe.
|-
| '''channel''' || 0 - 9999 || Schaltet auf einen absoluten Sender- oder Programmspeicherplatz (Nicht zu verwechseln mit input)
|-
| '''channelUp''' || || Springt zum nächsten Sender- oder Programmspeicherplatz.
|-
| '''channelDown''' || || Springt zum vorherigen Sender- oder Programmspeicherplatz.
|-
| '''remoteControl''' || # || Parameter ist Hersteller- und Gerätespezifisch. Funktion bei Geräten, die es erlauben die mitgelieferte Hardware Fernbedienung zu simulieren. Parameter in lowerCamelCaps (ggf. muss im Modul selber auf die Herstellerspezifische Schreibweise umcodiert werden; Alles groß- oder klein geschrieben)
|-
| '''input''' || <nowiki>z.B. hdmi[1-n] | av[1-n] | usb | airplay | server [1-n]</nowiki> || Auswahl von Hardwarekanälen (HDMI, DVB-S, PAL, DVI) oder Softwarekanälen (Airplay, IPTV, IP-Radiostream) die das zu steuernde Gerät aktiv schalten soll (zur Darstellung auf TV, Kanalwahl bei AV-Receivern etc.). Da diese Kanäle je nach Gerät und Modellreihen unterschiedliche Bezeichnungen besitzen, sollten alle möglichen Bezeichnungen in Form von lowerCamelCaps angeboten werden.
|-
| '''output''' || <nowiki>z.B. Airtunes1,Airtunes2,Intern</nowiki> || Auswahl des/der Ausgabegerätes.
|-
| '''statusRequest''' || || Den aktuellen Status des Gerätes abfragen
|-
|colspan="3"| ...
|}

== Readings ==

Diese Tabelle soll eine einheitliche Wertedefinition von Readings. Dazu zählen auch die verwendeten Werte und deren Bedeutung.

Wenn es zwischen reading und zugehörigen set eine 1:1 Beziehung gibt sollte sich der Inhalt des readings als Argument des set verwenden lassen um genau diesen dargestellten Zustand zu erreichen.

{| class="wikitable"
|-
! Name !! mögliche Werte !! Bedeutung
|-
| '''power''' || <nowiki>on|off</nowiki> || Ist das Gerät an oder aus?
|-
| '''presence''' || <nowiki>present|absent</nowiki> || Ist das Gerät aktuell ansprechbar? Sollte das Gerät aufgrund abgeschalteten Stromzufuhr, o.ä. aktuell nicht steuerbar sein, so sollte dies mit dem Wert "absent" verdeutlicht werden. In solch einem Fall sollte ein set-Befehl eine entsprechende Fehlermeldung bringen. Evtl. StatusUpdate-Timer sollten ensprechende Fehlermeldungen nur einmal im Log, etc. festhalten und Fehlermeldungen beim nächsten Status-Update entsprechend unterdrücken um so die Logfiles nicht unnötig vollzuschreiben. Auch das presence reading sollte nur dann aktualisiert werden wenn sich der Status geändert hat um am timestamp sehen zu können wann das war. event-on-change-reading ist hierzu nicht ausreichend weil nur das Event unterdrückt wird der Timestamp sich aber trotzdem ändert.
|-
| '''volume''' || 0-100 || Der prozentuale Lautstärkepegel gemessen der maximal möglichen tatsächlichen Werte.
|-
| '''volumeStraight''' || X-Y || Der tatsächliche Lautstärkepegel des Gerätes, so wie er am Gerät angezeigt/verwendet wird. <br><br>''Nur zu Verwenden, wenn das Gerät einen anderen Wertebereich als 0-100% intern verwendet.''
|-
| '''mute''' || <nowiki>on | off</nowiki> || Ist das Gerät aktuell stumm geschaltet?
|-
| '''repeat''' || <nowiki>one | all | off</nowiki> || Ist das Gerät im repeat modus?
|-
| '''shuffle''' || <nowiki>on | off</nowiki> || Ist das Gerät im shuffle modus?
|-
| '''input''' || ''aktuell gewählter Eingangskanal'' ||
|-
| '''output''' || ''aktuell gewählte(s) Ausgabegerät(e)'' ||
|-
| '''channel''' || ''aktuell gewählter Eingangskanal entsprechend dem Gerät''||
|-
| '''currentArtist''' || ''aktueller Interpret'' ||
|-
| '''currentAlbum''' || ''aktuelles Album'' ||
|-
| '''currentTitle''' || ''aktueller Titelname'' ||
|-
| '''currentMedia''' || ''"Name" der Wiedergabe"datei"'' || kann alles sein: Datei vom Filesystem, Stream aus dem Internet, m3u-URL oder was auch immer
|-
| '''playStatus''' || <nowiki>playing | paused | stopped</nowiki> ||
|-
| '''state''' || <nowiki>on | off | absent</nowiki> || Sofern das Gerät empfangsbereit ist, soll der Schaltzustand des Gerätes (Reading: power, sofern anwendbar) zurückgegeben werden. Ansonsten ist die Abwesenheit des Gerätes durch den Wert "absent" anzuzeigen.
|-
| '''stateAV''' || <nowiki><presence> | <power> | <mute> | <playStatus></nowiki> || Kombiniert den Status von bestehenden Readings zu einer logisch abhängigen Einheit nach folgendem Format: Wenn presence=absent=>absent, sonst power=off=>off, sonst mute=on=>muted, sonst playStatus!=stopped=>playStatus, sonst =>power
|-
|colspan="3"| ...
|}

== Implementation in Modulen ==
{{yes}} = Implementiert {{yes2}} = device spezifisch {{planed}} = Implementation geplant/in Arbeit {{no}} = Nicht implementiert/Keine Implementation geplant

{| class="wikitable"
! set-Befehl !! LGTV !! LISTENLIVE !! STV !! VIERA !! YAMAHA_AVR !! iTunes !! ENIGMA2 !! ONKYO_AVR !! Squeezebox !! PHTV !! PIONEER !! harmony !! plex
|-
| '''on''' || || || || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} ||
|-
| '''off''' || || || || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} ||
|-
| '''play''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{yes-c}}
|-
| '''pause''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{yes-c}}
|-
| '''stop''' || || || || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{yes-c}}
|-
| '''volume''' || || || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}}
|-
| '''volumeStraight''' || || || || {{no-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{planed-c}}|| {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{no-c}}
|-
| '''volumeUp''' || || || || {{yes-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{no-c}}
|-
| '''volumeDown''' || || || || {{yes-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{no-c}}
|-
| '''mute''' || || || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{no-c}}
|-
| '''repeat''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes2-c}} || {{yes-c}} || {{no-c}} || {{yes2-c}} || {{yes2-c}} || {{yes-c}}
|-
| '''shuffle''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes2-c}} || {{yes-c}} || {{no-c}} || {{yes2-c}} || {{yes2-c}} || {{yes-c}}
|-
| '''channel''' || || || || {{yes-c}} || {{no-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{no-c}}
|-
| '''channelUp''' || || || || {{yes-c}} || {{no-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{no-c}}
|-
| '''channelDown''' || || || || {{yes-c}} || {{no-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{no-c}}
|-
| '''remoteControl''' || || || || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes2-c}} || {{yes2-c}} || {{no-c}}
|-
| '''input''' || {{yes-c}} || || || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}}|| {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{no-c}}
|-
| '''output''' || || || || {{no-c}} || {{no-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{no-c}} || {{no-c}} || {{no-c}} || {{yes2-c}} || {{no-c}}
|-
| '''statusRequest''' || || {{yes-c}} || || {{yes-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{no-c}}
|-
! Reading !! LGTV !! LISTENLIVE !! STV !! VIERA !! YAMAHA_AVR !! iTunes !! ENIGMA2 !! ONKYO_AVR !! Squeezebox !! PHTV !! PIONEER !! harmony
|-
| '''power''' || || || || {{yes-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} ||
|-
| '''presence''' || || || || {{yes-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}}
|-
| '''volume''' || || || || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}}
|-
| '''volumeStraight''' || || || || {{no-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{no-c}}
|-
| '''mute''' || || || || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{planed-c}}
|-
| '''repeat''' || || || || {{no-c}} || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes2-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{no-c}} || {{planed-c}}
|-
| '''shuffle''' || || || || {{no-c}} || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes2-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{no-c}} || {{planed-c}}
|-
| '''input''' || || || || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{no-c}}
|-
| '''output''' || || || || {{no-c}} || {{no-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{no-c}} || {{no-c}} || {{no-c}} || {{no-c}} || {{no-c}}
|-
| '''channel''' || || || || {{yes-c}} || {{no-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{no-c}}
|-
| '''currentArtist''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes-c}}
|-
| '''currentAlbum''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes-c}}
|-
| '''currentTitle''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes-c}}
|-
| '''currentMedia''' || || || || {{no-c}} || {{no-c}} || {{planed-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{no-c}} ||
|-
| '''playStatus''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{no-c}} ||
|-
| '''state''' || || || || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{yes2-c}} || {{yes-c}} || {{yes2-c}} || {{yes-c}} || {{no-c}} || {{yes-c}}
|-
| '''stateAV''' || || || || {{no-c}} || {{no-c}} || {{no-c}} || {{yes2-c}} || {{yes-c}} || {{no-c}} || {{yes2-c}} || {{no-c}} || {{no-c}} || {{no-c}}
|}

== Sonstiges ==
=== Wie funktioniert Cover Art? ===
Reading mit URL-Link oder als Gerätestatus???

=== Wie funktionieren Sprachdurchsagen oder Text Einblendungen? ===

Obwohl dies sehr stark davon abhängt, ob das jeweilige Gerät eine solche Funktion unterstützt, oder ob sie anderweitig (z.B. durch Google Service) umgesetzt werden können, so sollen dennoch solche Features über die folgenden Set-Kommandos angeboten werden.
{| class="wikitable"
|-
! Kommando !! Beispiel !! Beschreibung
|-
| '''sayText'''|| <pre>set ''<device>'' sayText "Anruf in Abwesenheit"</pre>
|| Dieses Kommando soll den übergebenen Text auf dem jeweiligen Device in Audio-Form wieder ausgeben. Hierbei kann auf einen Synthese-Anbieter im Internet zurückgegriffen werden, der ein solches Audiosample erzeugt, oder geräteinterne Kommandos verwendet werden, je nach dem was vorhanden und unterstützt wird.
|-
| '''showText''' || <pre>set ''<device>'' showText "Anruf in Abwesenheit"</pre>|| Dieses Kommando soll einen Text z.B. auf dem Display des Gerätes (oder Fernseher) in geeigneter Form anzeigen, sofern das Gerät eine solche Funktion unterstützt.
|-
! colspan="3"| Alternativvorschlag
|-
| '''message''' || <pre>set ''<device>'' message "Anruf in Abwesenheit" [audio|video]</pre>|| Dieses Kommando soll eine Nachricht mit dem Gerät anzeigen (video) oder abspielen (audio), sofern das Gerät eine solche Funktion unterstützt. Ohne die optionale Wiedergabe-Art oder wenn die angegebene nicht unterstützt ist über die von diesem Gerät bevorzugte Methode.
|}

=== Wie funktionieren Playlisten? ===

Sofern anwendbar, sollten diese mit dem Kommando <code>set <device> playlist XY</code> aufrufbar sein. Dabei sollten die zur Verfügung stehenden Playlists bereits bekannt sein und als möglicher Kommando-Parameter angeboten werden.

=== Wie funktionieren Zonen? ===

Jede einzelne Zone eines Gerätes wird durch ein eigenes FHEM-Device repräsentiert. Die gewünschte Zone ist als optionaler Parameter in den Definitions-Argumenten zu übergeben.

Wenn keine bestimmte Zone explizit in der Definition übergeben wird, ist die Hauptzone (Main-Zone) zu verwenden. Die zur Verfügung stehenden Zonen sollten in den Internals aufgelistet sein, mindestens jedoch in der commandref des entsprechenden Moduls.

Jede Definition sollte nur die tatsächlich möglichen Befehle, Eingänge, etc. der entsprechenden Zone anbieten.

[[Kategorie:Development]]

DevelopmentGuidelinesAV

2016-08-21T13:58:32Z

Loredo:

== Einleitung ==
Auf dieser Seite sollen Richtlinien für AV-Module gesammelt werden damit es einfacher wird diese zusammen mit anderen Modulen wie remotecontroll oder LightScene zu verwenden. Auch Benachrichtigungen wie Sprachdurchsagen oder Einblendungen lassen sich universeller verwenden wenn sie bei allen Geräten die dies unterstützen gleich angesprochen werden.

Der Text aus dem ursprünglichen Forumsthread war folgender:

::gerade ist ja mit den tv und verstärker modulen sowie dem remotecontrol modul ziemlich schwung in den bereich audio und video geräte gekommen. zusätzlich gibt es noch eine ganze reihe älterer module wie sonor und xbmc und zwei arten itunes anzusprechen und neue module wie für die web radios oder das raspberry multiroom stehen vor der tür.

::wie wäre es sich rechtzeitig auf ein möglichst einheitiches kommando set zu verständigen damit grundlegende dinge wie play/pause/volume/next bei allen geräten einheitlich, in gleicher schreibweise und mit möglichst ähnlichen parametern funktionieren?

::das würde module wie die remotecontrol aber auch structure und lightscene deutlich einfacher und nützlicher machen und auch alternative frontends erleichtern wenn bestimmte features wie audio,video oder cover über ein einheitliches schema markiert würden.

::mein vorschlag wäre sich an das sonos modul anzulehnen weil es mir in dieser hinsicht am fortgeschrittensten erscheint und auch weitergehende features wie cover oder durchsagen anbietet.

::zu vereinheitlichen wäre dann u.a.:
::- welche kommandos zu welchem zweck
::- kommandos sollten einheitlich geschrieben werden. also z.b. immer klein oder immer mixed case.
::- parameter sollten so weit möglich den gleichen wertebereich haben. also z.b. volume immer von 0-100.
::- wenn es aus irgendeinem grund noch ein gerätespezifischer wertebereich nötig ist sollte der zusätzlich vorhanden sein.
::- cover sollten immer auf die gleiche art gelesen werden können
::- ...

Der Thread ist [http://forum.fhem.de/index.php/topic,13784.0.html hier] zu finden.

== Bezeichner ==
siehe [[DevelopmentGuidelines#Bezeichnungen|Bezeichnungen allgmein]]

== Kommandos ==

Diese Tabelle soll eine einheitliche Definition von set-Befehlen aufzeigen. Dazu zählen auch ggf. Parameter und deren Bedeutung.

{| class="wikitable sortable"
! Name !! Parameter !! Bedeutung
|-
| '''on''' || || Schaltet das Gerät ein, so dass es benutzt werden kann.
|-
| '''off''' || || Schaltet das Gerät aus.
|-
| '''play''' || || Startet das Abspielen von Medien (Video, mp3, Radio stream etc.)
|-
| '''pause''' || || Pausiert das Abspielen von Medien, stoppt es aber nicht.
|-
| '''stop''' || || Stoppt (beendet) das Abspielen von Medien.
|-
| '''volume''' || 0 - 100 || Setzt die Lautstärke auf einen prozentualen Wert.
|-
| '''volumeStraight''' || X-Y || Setzt die Lautstärke auf den absoluten Wert, so wie er vom Gerät tatsächlich verwendet wird (z.B. dB)<br><br>''Nur zu Verwenden, wenn das Gerät einen anderen Wertebereich als 0-100% intern verwendet.''
|-
| '''volumeUp''' || [0 - 100] || Erhöht die Lautstärke um einen gerätespezifischen Schritt (z.b. 5%). Wenn die Schrittweite konfigurierbar ist soll das über das Attribut volumeStep erfolgen. Optional kann das Inkrement als optionaler Parameter mit angegeben werden.
|-
| '''volumeDown''' || [0 - 100] || Verringert die Lautstärke um einen gerätespezifischen Schritt (z.b. 5%). Wenn die Schrittweite konfigurierbar ist soll das über das Attribut volumeStep erfolgen. Optional kann das Dekrement als optionaler Parameter mit angegeben werden.
|-
| '''mute''' || <nowiki>on | off | toggle</nowiki> || Aktiviert, deaktiviert oder schaltet die Mutefunktion = Lautstärke der aktuellen Ausgabe wird verringert bzw. abgschaltet (Gerätespezifisch)
|-
| '''repeat''' || <nowiki>one | all | off</nowiki> || Aktivieren der Repeatfunktion = wiederholen des aktuellen Titels/Albums
|-
| '''shuffle''' || <nowiki>on | off</nowiki> || Aktiviert oder deaktiviert die Shufflefunktion = zufällige Wiedergabe.
|-
| '''channel''' || 0 - 9999 || Schaltet auf einen absoluten Sender- oder Programmspeicherplatz (Nicht zu verwechseln mit input)
|-
| '''channelUp''' || || Springt zum nächsten Sender- oder Programmspeicherplatz.
|-
| '''channelDown''' || || Springt zum vorherigen Sender- oder Programmspeicherplatz.
|-
| '''remoteControl''' || # || Parameter ist Hersteller- und Gerätespezifisch. Funktion bei Geräten, die es erlauben die mitgelieferte Hardware Fernbedienung zu simulieren. Parameter in lowerCamelCaps (ggf. muss im Modul selber auf die Herstellerspezifische Schreibweise umcodiert werden; Alles groß- oder klein geschrieben)
|-
| '''input''' || <nowiki>z.B. hdmi[1-n] | av[1-n] | usb | airplay | server [1-n]</nowiki> || Auswahl von Hardwarekanälen (HDMI, DVB-S, PAL, DVI) oder Softwarekanälen (Airplay, IPTV, IP-Radiostream) die das zu steuernde Gerät aktiv schalten soll (zur Darstellung auf TV, Kanalwahl bei AV-Receivern etc.). Da diese Kanäle je nach Gerät und Modellreihen unterschiedliche Bezeichnungen besitzen, sollten alle möglichen Bezeichnungen in Form von lowerCamelCaps angeboten werden.
|-
| '''output''' || <nowiki>z.B. Airtunes1,Airtunes2,Intern</nowiki> || Auswahl des/der Ausgabegerätes.
|-
| '''statusRequest''' || || Den aktuellen Status des Gerätes abfragen
|-
|colspan="3"| ...
|}

== Readings ==

Diese Tabelle soll eine einheitliche Wertedefinition von Readings. Dazu zählen auch die verwendeten Werte und deren Bedeutung.

Wenn es zwischen reading und zugehörigen set eine 1:1 Beziehung gibt sollte sich der Inhalt des readings als Argument des set verwenden lassen um genau diesen dargestellten Zustand zu erreichen.

{| class="wikitable"
|-
! Name !! mögliche Werte !! Bedeutung
|-
| '''power''' || <nowiki>on|off</nowiki> || Ist das Gerät an oder aus?
|-
| '''presence''' || <nowiki>present|absent</nowiki> || Ist das Gerät aktuell ansprechbar? Sollte das Gerät aufgrund abgeschalteten Stromzufuhr, o.ä. aktuell nicht steuerbar sein, so sollte dies mit dem Wert "absent" verdeutlicht werden. In solch einem Fall sollte ein set-Befehl eine entsprechende Fehlermeldung bringen. Evtl. StatusUpdate-Timer sollten ensprechende Fehlermeldungen nur einmal im Log, etc. festhalten und Fehlermeldungen beim nächsten Status-Update entsprechend unterdrücken um so die Logfiles nicht unnötig vollzuschreiben. Auch das presence reading sollte nur dann aktualisiert werden wenn sich der Status geändert hat um am timestamp sehen zu können wann das war. event-on-change-reading ist hierzu nicht ausreichend weil nur das Event unterdrückt wird der Timestamp sich aber trotzdem ändert.
|-
| '''volume''' || 0-100 || Der prozentuale Lautstärkepegel gemessen der maximal möglichen tatsächlichen Werte.
|-
| '''volumeStraight''' || X-Y || Der tatsächliche Lautstärkepegel des Gerätes, so wie er am Gerät angezeigt/verwendet wird. <br><br>''Nur zu Verwenden, wenn das Gerät einen anderen Wertebereich als 0-100% intern verwendet.''
|-
| '''mute''' || <nowiki>on | off</nowiki> || Ist das Gerät aktuell stumm geschaltet?
|-
| '''repeat''' || <nowiki>one | all | off</nowiki> || Ist das Gerät im repeat modus?
|-
| '''shuffle''' || <nowiki>on | off</nowiki> || Ist das Gerät im shuffle modus?
|-
| '''input''' || ''aktuell gewählter Eingangskanal'' ||
|-
| '''output''' || ''aktuell gewählte(s) Ausgabegerät(e)'' ||
|-
| '''channel''' || ''aktuell gewählter Eingangskanal entsprechend dem Gerät''||
|-
| '''currentArtist''' || ''aktueller Interpret'' ||
|-
| '''currentAlbum''' || ''aktuelles Album'' ||
|-
| '''currentTitle''' || ''aktueller Titelname'' ||
|-
| '''currentMedia''' || ''"Name" der Wiedergabe"datei"'' || kann alles sein: Datei vom Filesystem, Stream aus dem Internet, m3u-URL oder was auch immer
|-
| '''playStatus''' || <nowiki>playing | paused | stopped</nowiki> ||
|-
| '''state''' || <nowiki>on | off | absent</nowiki> || Sofern das Gerät empfangsbereit ist, soll der Schaltzustand des Gerätes (Reading: power, sofern anwendbar) zurückgegeben werden. Ansonsten ist die Abwesenheit des Gerätes durch den Wert "absent" anzuzeigen.
|-
| '''stateAV''' || <nowiki><presence> | <power> | <mute> | <playStatus></nowiki> || Kombiniert den Status von bestehenden Readings zu einer logisch abhängigen Einheit nach folgendem Format: Wenn presence=absent=>absent, sonst power=off=>off, sonst mute=on=>muted, sonst playStatus!=stopped=>playStatus, sonst =>power
|-
|colspan="3"| ...
|}

== Implementation in Modulen ==
{{yes}} = Implementiert {{yes2}} = device spezifisch {{planed}} = Implementation geplant/in Arbeit {{no}} = Nicht implementiert/Keine Implementation geplant

{| class="wikitable"
! set-Befehl !! LGTV !! LISTENLIVE !! STV !! VIERA !! YAMAHA_AVR !! iTunes !! ENIGMA2 !! ONKYO_AVR !! Squeezebox !! PHTV !! PIONEER !! harmony !! plex
|-
| '''on''' || || || || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} ||
|-
| '''off''' || || || || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} ||
|-
| '''play''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{yes-c}}
|-
| '''pause''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{yes-c}}
|-
| '''stop''' || || || || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{yes-c}}
|-
| '''volume''' || || || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}}
|-
| '''volumeStraight''' || || || || {{no-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{planed-c}}|| {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{no-c}}
|-
| '''volumeUp''' || || || || {{yes-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{no-c}}
|-
| '''volumeDown''' || || || || {{yes-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{no-c}}
|-
| '''mute''' || || || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{no-c}}
|-
| '''repeat''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes2-c}} || {{yes-c}} || {{no-c}} || {{yes2-c}} || {{yes2-c}} || {{yes-c}}
|-
| '''shuffle''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes2-c}} || {{yes-c}} || {{no-c}} || {{yes2-c}} || {{yes2-c}} || {{yes-c}}
|-
| '''channel''' || || || || {{yes-c}} || {{no-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{no-c}}
|-
| '''channelUp''' || || || || {{yes-c}} || {{no-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{no-c}}
|-
| '''channelDown''' || || || || {{yes-c}} || {{no-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{no-c}}
|-
| '''remoteControl''' || || || || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes2-c}} || {{yes2-c}} || {{no-c}}
|-
| '''input''' || {{yes-c}} || || || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}}|| {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{no-c}}
|-
| '''output''' || || || || {{no-c}} || {{no-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{no-c}} || {{no-c}} || {{no-c}} || {{yes2-c}} || {{no-c}}
|-
| '''statusRequest''' || || {{yes-c}} || || {{yes-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{no-c}}
|-
! Reading !! LGTV !! LISTENLIVE !! STV !! VIERA !! YAMAHA_AVR !! iTunes !! ENIGMA2 !! ONKYO_AVR !! Squeezebox !! PHTV !! PIONEER !! harmony
|-
| '''power''' || || || || {{yes-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} ||
|-
| '''presence''' || || || || {{yes-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}}
|-
| '''volume''' || || || || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}}
|-
| '''volumeStraight''' || || || || {{no-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{no-c}}
|-
| '''mute''' || || || || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{planed-c}}
|-
| '''repeat''' || || || || {{no-c}} || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes2-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{no-c}} || {{planed-c}}
|-
| '''shuffle''' || || || || {{no-c}} || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes2-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{no-c}} || {{planed-c}}
|-
| '''input''' || || || || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{no-c}}
|-
| '''output''' || || || || {{no-c}} || {{no-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{no-c}} || {{no-c}} || {{no-c}} || {{no-c}} || {{no-c}}
|-
| '''channel''' || || || || {{yes-c}} || {{no-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{no-c}}
|-
| '''currentArtist''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes-c}}
|-
| '''currentAlbum''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes-c}}
|-
| '''currentTitle''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes-c}}
|-
| '''currentMedia''' || || || || {{no-c}} || {{no-c}} || {{planed-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{no-c}} ||
|-
| '''playStatus''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{no-c}} ||
|-
| '''state''' || || || || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}}
|-
| '''stateAV''' || || || || {{no-c}} || {{no-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{no-c}}
|}

== Sonstiges ==
=== Wie funktioniert Cover Art? ===
Reading mit URL-Link oder als Gerätestatus???

=== Wie funktionieren Sprachdurchsagen oder Text Einblendungen? ===

Obwohl dies sehr stark davon abhängt, ob das jeweilige Gerät eine solche Funktion unterstützt, oder ob sie anderweitig (z.B. durch Google Service) umgesetzt werden können, so sollen dennoch solche Features über die folgenden Set-Kommandos angeboten werden.
{| class="wikitable"
|-
! Kommando !! Beispiel !! Beschreibung
|-
| '''sayText'''|| <pre>set ''<device>'' sayText "Anruf in Abwesenheit"</pre>
|| Dieses Kommando soll den übergebenen Text auf dem jeweiligen Device in Audio-Form wieder ausgeben. Hierbei kann auf einen Synthese-Anbieter im Internet zurückgegriffen werden, der ein solches Audiosample erzeugt, oder geräteinterne Kommandos verwendet werden, je nach dem was vorhanden und unterstützt wird.
|-
| '''showText''' || <pre>set ''<device>'' showText "Anruf in Abwesenheit"</pre>|| Dieses Kommando soll einen Text z.B. auf dem Display des Gerätes (oder Fernseher) in geeigneter Form anzeigen, sofern das Gerät eine solche Funktion unterstützt.
|-
! colspan="3"| Alternativvorschlag
|-
| '''message''' || <pre>set ''<device>'' message "Anruf in Abwesenheit" [audio|video]</pre>|| Dieses Kommando soll eine Nachricht mit dem Gerät anzeigen (video) oder abspielen (audio), sofern das Gerät eine solche Funktion unterstützt. Ohne die optionale Wiedergabe-Art oder wenn die angegebene nicht unterstützt ist über die von diesem Gerät bevorzugte Methode.
|}

=== Wie funktionieren Playlisten? ===

Sofern anwendbar, sollten diese mit dem Kommando <code>set <device> playlist XY</code> aufrufbar sein. Dabei sollten die zur Verfügung stehenden Playlists bereits bekannt sein und als möglicher Kommando-Parameter angeboten werden.

=== Wie funktionieren Zonen? ===

Jede einzelne Zone eines Gerätes wird durch ein eigenes FHEM-Device repräsentiert. Die gewünschte Zone ist als optionaler Parameter in den Definitions-Argumenten zu übergeben.

Wenn keine bestimmte Zone explizit in der Definition übergeben wird, ist die Hauptzone (Main-Zone) zu verwenden. Die zur Verfügung stehenden Zonen sollten in den Internals aufgelistet sein, mindestens jedoch in der commandref des entsprechenden Moduls.

Jede Definition sollte nur die tatsächlich möglichen Befehle, Eingänge, etc. der entsprechenden Zone anbieten.

[[Kategorie:Development]]

DevelopmentGuidelinesAV

2016-08-21T13:54:40Z

Loredo: Add stateAV definition

== Einleitung ==
Auf dieser Seite sollen Richtlinien für AV-Module gesammelt werden damit es einfacher wird diese zusammen mit anderen Modulen wie remotecontroll oder LightScene zu verwenden. Auch Benachrichtigungen wie Sprachdurchsagen oder Einblendungen lassen sich universeller verwenden wenn sie bei allen Geräten die dies unterstützen gleich angesprochen werden.

Der Text aus dem ursprünglichen Forumsthread war folgender:

::gerade ist ja mit den tv und verstärker modulen sowie dem remotecontrol modul ziemlich schwung in den bereich audio und video geräte gekommen. zusätzlich gibt es noch eine ganze reihe älterer module wie sonor und xbmc und zwei arten itunes anzusprechen und neue module wie für die web radios oder das raspberry multiroom stehen vor der tür.

::wie wäre es sich rechtzeitig auf ein möglichst einheitiches kommando set zu verständigen damit grundlegende dinge wie play/pause/volume/next bei allen geräten einheitlich, in gleicher schreibweise und mit möglichst ähnlichen parametern funktionieren?

::das würde module wie die remotecontrol aber auch structure und lightscene deutlich einfacher und nützlicher machen und auch alternative frontends erleichtern wenn bestimmte features wie audio,video oder cover über ein einheitliches schema markiert würden.

::mein vorschlag wäre sich an das sonos modul anzulehnen weil es mir in dieser hinsicht am fortgeschrittensten erscheint und auch weitergehende features wie cover oder durchsagen anbietet.

::zu vereinheitlichen wäre dann u.a.:
::- welche kommandos zu welchem zweck
::- kommandos sollten einheitlich geschrieben werden. also z.b. immer klein oder immer mixed case.
::- parameter sollten so weit möglich den gleichen wertebereich haben. also z.b. volume immer von 0-100.
::- wenn es aus irgendeinem grund noch ein gerätespezifischer wertebereich nötig ist sollte der zusätzlich vorhanden sein.
::- cover sollten immer auf die gleiche art gelesen werden können
::- ...

Der Thread ist [http://forum.fhem.de/index.php/topic,13784.0.html hier] zu finden.

== Bezeichner ==
siehe [[DevelopmentGuidelines#Bezeichnungen|Bezeichnungen allgmein]]

== Kommandos ==

Diese Tabelle soll eine einheitliche Definition von set-Befehlen aufzeigen. Dazu zählen auch ggf. Parameter und deren Bedeutung.

{| class="wikitable sortable"
! Name !! Parameter !! Bedeutung
|-
| '''on''' || || Schaltet das Gerät ein, so dass es benutzt werden kann.
|-
| '''off''' || || Schaltet das Gerät aus.
|-
| '''play''' || || Startet das Abspielen von Medien (Video, mp3, Radio stream etc.)
|-
| '''pause''' || || Pausiert das Abspielen von Medien, stoppt es aber nicht.
|-
| '''stop''' || || Stoppt (beendet) das Abspielen von Medien.
|-
| '''volume''' || 0 - 100 || Setzt die Lautstärke auf einen prozentualen Wert.
|-
| '''volumeStraight''' || X-Y || Setzt die Lautstärke auf den absoluten Wert, so wie er vom Gerät tatsächlich verwendet wird (z.B. dB)<br><br>''Nur zu Verwenden, wenn das Gerät einen anderen Wertebereich als 0-100% intern verwendet.''
|-
| '''volumeUp''' || [0 - 100] || Erhöht die Lautstärke um einen gerätespezifischen Schritt (z.b. 5%). Wenn die Schrittweite konfigurierbar ist soll das über das Attribut volumeStep erfolgen. Optional kann das Inkrement als optionaler Parameter mit angegeben werden.
|-
| '''volumeDown''' || [0 - 100] || Verringert die Lautstärke um einen gerätespezifischen Schritt (z.b. 5%). Wenn die Schrittweite konfigurierbar ist soll das über das Attribut volumeStep erfolgen. Optional kann das Dekrement als optionaler Parameter mit angegeben werden.
|-
| '''mute''' || <nowiki>on | off | toggle</nowiki> || Aktiviert, deaktiviert oder schaltet die Mutefunktion = Lautstärke der aktuellen Ausgabe wird verringert bzw. abgschaltet (Gerätespezifisch)
|-
| '''repeat''' || <nowiki>one | all | off</nowiki> || Aktivieren der Repeatfunktion = wiederholen des aktuellen Titels/Albums
|-
| '''shuffle''' || <nowiki>on | off</nowiki> || Aktiviert oder deaktiviert die Shufflefunktion = zufällige Wiedergabe.
|-
| '''channel''' || 0 - 9999 || Schaltet auf einen absoluten Sender- oder Programmspeicherplatz (Nicht zu verwechseln mit input)
|-
| '''channelUp''' || || Springt zum nächsten Sender- oder Programmspeicherplatz.
|-
| '''channelDown''' || || Springt zum vorherigen Sender- oder Programmspeicherplatz.
|-
| '''remoteControl''' || # || Parameter ist Hersteller- und Gerätespezifisch. Funktion bei Geräten, die es erlauben die mitgelieferte Hardware Fernbedienung zu simulieren. Parameter in lowerCamelCaps (ggf. muss im Modul selber auf die Herstellerspezifische Schreibweise umcodiert werden; Alles groß- oder klein geschrieben)
|-
| '''input''' || <nowiki>z.B. hdmi[1-n] | av[1-n] | usb | airplay | server [1-n]</nowiki> || Auswahl von Hardwarekanälen (HDMI, DVB-S, PAL, DVI) oder Softwarekanälen (Airplay, IPTV, IP-Radiostream) die das zu steuernde Gerät aktiv schalten soll (zur Darstellung auf TV, Kanalwahl bei AV-Receivern etc.). Da diese Kanäle je nach Gerät und Modellreihen unterschiedliche Bezeichnungen besitzen, sollten alle möglichen Bezeichnungen in Form von lowerCamelCaps angeboten werden.
|-
| '''output''' || <nowiki>z.B. Airtunes1,Airtunes2,Intern</nowiki> || Auswahl des/der Ausgabegerätes.
|-
| '''statusRequest''' || || Den aktuellen Status des Gerätes abfragen
|-
|colspan="3"| ...
|}

== Readings ==

Diese Tabelle soll eine einheitliche Wertedefinition von Readings. Dazu zählen auch die verwendeten Werte und deren Bedeutung.

Wenn es zwischen reading und zugehörigen set eine 1:1 Beziehung gibt sollte sich der Inhalt des readings als Argument des set verwenden lassen um genau diesen dargestellten Zustand zu erreichen.

{| class="wikitable"
|-
! Name !! mögliche Werte !! Bedeutung
|-
| '''power''' || <nowiki>on|off</nowiki> || Ist das Gerät an oder aus?
|-
| '''presence''' || <nowiki>present|absent</nowiki> || Ist das Gerät aktuell ansprechbar? Sollte das Gerät aufgrund abgeschalteten Stromzufuhr, o.ä. aktuell nicht steuerbar sein, so sollte dies mit dem Wert "absent" verdeutlicht werden. In solch einem Fall sollte ein set-Befehl eine entsprechende Fehlermeldung bringen. Evtl. StatusUpdate-Timer sollten ensprechende Fehlermeldungen nur einmal im Log, etc. festhalten und Fehlermeldungen beim nächsten Status-Update entsprechend unterdrücken um so die Logfiles nicht unnötig vollzuschreiben. Auch das presence reading sollte nur dann aktualisiert werden wenn sich der Status geändert hat um am timestamp sehen zu können wann das war. event-on-change-reading ist hierzu nicht ausreichend weil nur das Event unterdrückt wird der Timestamp sich aber trotzdem ändert.
|-
| '''volume''' || 0-100 || Der prozentuale Lautstärkepegel gemessen der maximal möglichen tatsächlichen Werte.
|-
| '''volumeStraight''' || X-Y || Der tatsächliche Lautstärkepegel des Gerätes, so wie er am Gerät angezeigt/verwendet wird. <br><br>''Nur zu Verwenden, wenn das Gerät einen anderen Wertebereich als 0-100% intern verwendet.''
|-
| '''mute''' || <nowiki>on | off</nowiki> || Ist das Gerät aktuell stumm geschaltet?
|-
| '''repeat''' || <nowiki>one | all | off</nowiki> || Ist das Gerät im repeat modus?
|-
| '''shuffle''' || <nowiki>on | off</nowiki> || Ist das Gerät im shuffle modus?
|-
| '''input''' || ''aktuell gewählter Eingangskanal'' ||
|-
| '''output''' || ''aktuell gewählte(s) Ausgabegerät(e)'' ||
|-
| '''channel''' || ''aktuell gewählter Eingangskanal entsprechend dem Gerät''||
|-
| '''currentArtist''' || ''aktueller Interpret'' ||
|-
| '''currentAlbum''' || ''aktuelles Album'' ||
|-
| '''currentTitle''' || ''aktueller Titelname'' ||
|-
| '''currentMedia''' || ''"Name" der Wiedergabe"datei"'' || kann alles sein: Datei vom Filesystem, Stream aus dem Internet, m3u-URL oder was auch immer
|-
| '''playStatus''' || <nowiki>playing | paused | stopped</nowiki> ||
|-
| '''state''' || <nowiki>on | off | absent</nowiki> || Sofern das Gerät empfangsbereit ist, soll der Schaltzustand des Gerätes (Reading: power, sofern anwendbar) zurückgegeben werden. Ansonsten ist die Abwesenheit des Gerätes durch den Wert "absent" anzuzeigen.
|-
| '''stateAV''' || <nowiki><presence> | <power> | <mute> | <playStatus></nowiki> || Kombiniert den Status von bestehenden Readings zu einer logisch abhängigen Einheit nach folgendem Format: Wenn presence=absent=>absent, sonst power=off=>off, sonst mute=on=>muted, sonst playStatus!=stopped=>playStatus, sonst =>power
|-
|colspan="3"| ...
|}

== Implementation in Modulen ==
{{yes}} = Implementiert {{yes2}} = device spezifisch {{planed}} = Implementation geplant/in Arbeit {{no}} = Nicht implementiert/Keine Implementation geplant

{| class="wikitable"
! set-Befehl !! LGTV !! LISTENLIVE !! STV !! VIERA !! YAMAHA_AVR !! iTunes !! ENIGMA2 !! ONKYO_AVR !! Squeezebox !! PHTV !! PIONEER !! harmony !! plex
|-
| '''on''' || || || || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} ||
|-
| '''off''' || || || || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} ||
|-
| '''play''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{yes-c}}
|-
| '''pause''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{yes-c}}
|-
| '''stop''' || || || || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{yes-c}}
|-
| '''volume''' || || || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}}
|-
| '''volumeStraight''' || || || || {{no-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{planed-c}}|| {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{no-c}}
|-
| '''volumeUp''' || || || || {{yes-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{no-c}}
|-
| '''volumeDown''' || || || || {{yes-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{no-c}}
|-
| '''mute''' || || || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{no-c}}
|-
| '''repeat''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes2-c}} || {{yes-c}} || {{no-c}} || {{yes2-c}} || {{yes2-c}} || {{yes-c}}
|-
| '''shuffle''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes2-c}} || {{yes-c}} || {{no-c}} || {{yes2-c}} || {{yes2-c}} || {{yes-c}}
|-
| '''channel''' || || || || {{yes-c}} || {{no-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{no-c}}
|-
| '''channelUp''' || || || || {{yes-c}} || {{no-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{no-c}}
|-
| '''channelDown''' || || || || {{yes-c}} || {{no-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{no-c}}
|-
| '''remoteControl''' || || || || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes2-c}} || {{yes2-c}} || {{no-c}}
|-
| '''input''' || {{yes-c}} || || || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}}|| {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{no-c}}
|-
| '''output''' || || || || {{no-c}} || {{no-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{no-c}} || {{no-c}} || {{no-c}} || {{yes2-c}} || {{no-c}}
|-
| '''statusRequest''' || || {{yes-c}} || || {{yes-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{no-c}}
|-
! Reading !! LGTV !! LISTENLIVE !! STV !! VIERA !! YAMAHA_AVR !! iTunes !! ENIGMA2 !! ONKYO_AVR !! Squeezebox !! PHTV !! PIONEER !! harmony
|-
| '''power''' || || || || {{yes-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} ||
|-
| '''presence''' || || || || {{yes-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}}
|-
| '''volume''' || || || || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}}
|-
| '''volumeStraight''' || || || || {{no-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{no-c}}
|-
| '''mute''' || || || || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{planed-c}}
|-
| '''repeat''' || || || || {{no-c}} || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes2-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{no-c}} || {{planed-c}}
|-
| '''shuffle''' || || || || {{no-c}} || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes2-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{no-c}} || {{planed-c}}
|-
| '''input''' || || || || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{no-c}}
|-
| '''output''' || || || || {{no-c}} || {{no-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{no-c}} || {{no-c}} || {{no-c}} || {{no-c}} || {{no-c}}
|-
| '''channel''' || || || || {{yes-c}} || {{no-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{no-c}}
|-
| '''currentArtist''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes-c}}
|-
| '''currentAlbum''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes-c}}
|-
| '''currentTitle''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes-c}}
|-
| '''currentMedia''' || || || || {{no-c}} || {{no-c}} || {{planed-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{no-c}} ||
|-
| '''playStatus''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{no-c}} ||
|-
| '''state''' || || || || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}}
|}

== Sonstiges ==
=== Wie funktioniert Cover Art? ===
Reading mit URL-Link oder als Gerätestatus???

=== Wie funktionieren Sprachdurchsagen oder Text Einblendungen? ===

Obwohl dies sehr stark davon abhängt, ob das jeweilige Gerät eine solche Funktion unterstützt, oder ob sie anderweitig (z.B. durch Google Service) umgesetzt werden können, so sollen dennoch solche Features über die folgenden Set-Kommandos angeboten werden.
{| class="wikitable"
|-
! Kommando !! Beispiel !! Beschreibung
|-
| '''sayText'''|| <pre>set ''<device>'' sayText "Anruf in Abwesenheit"</pre>
|| Dieses Kommando soll den übergebenen Text auf dem jeweiligen Device in Audio-Form wieder ausgeben. Hierbei kann auf einen Synthese-Anbieter im Internet zurückgegriffen werden, der ein solches Audiosample erzeugt, oder geräteinterne Kommandos verwendet werden, je nach dem was vorhanden und unterstützt wird.
|-
| '''showText''' || <pre>set ''<device>'' showText "Anruf in Abwesenheit"</pre>|| Dieses Kommando soll einen Text z.B. auf dem Display des Gerätes (oder Fernseher) in geeigneter Form anzeigen, sofern das Gerät eine solche Funktion unterstützt.
|-
! colspan="3"| Alternativvorschlag
|-
| '''message''' || <pre>set ''<device>'' message "Anruf in Abwesenheit" [audio|video]</pre>|| Dieses Kommando soll eine Nachricht mit dem Gerät anzeigen (video) oder abspielen (audio), sofern das Gerät eine solche Funktion unterstützt. Ohne die optionale Wiedergabe-Art oder wenn die angegebene nicht unterstützt ist über die von diesem Gerät bevorzugte Methode.
|}

=== Wie funktionieren Playlisten? ===

Sofern anwendbar, sollten diese mit dem Kommando <code>set <device> playlist XY</code> aufrufbar sein. Dabei sollten die zur Verfügung stehenden Playlists bereits bekannt sein und als möglicher Kommando-Parameter angeboten werden.

=== Wie funktionieren Zonen? ===

Jede einzelne Zone eines Gerätes wird durch ein eigenes FHEM-Device repräsentiert. Die gewünschte Zone ist als optionaler Parameter in den Definitions-Argumenten zu übergeben.

Wenn keine bestimmte Zone explizit in der Definition übergeben wird, ist die Hauptzone (Main-Zone) zu verwenden. Die zur Verfügung stehenden Zonen sollten in den Internals aufgelistet sein, mindestens jedoch in der commandref des entsprechenden Moduls.

Jede Definition sollte nur die tatsächlich möglichen Befehle, Eingänge, etc. der entsprechenden Zone anbieten.

[[Kategorie:Development]]

DevelopmentGuidelinesAV

2016-05-22T18:05:47Z

Loredo:

== Einleitung ==
Auf dieser Seite sollen Richtlinien für AV-Module gesammelt werden damit es einfacher wird diese zusammen mit anderen Modulen wie remotecontroll oder LightScene zu verwenden. Auch Benachrichtigungen wie Sprachdurchsagen oder Einblendungen lassen sich universeller verwenden wenn sie bei allen Geräten die dies unterstützen gleich angesprochen werden.

Der Text aus dem ursprünglichen Forumsthread war folgender:

::gerade ist ja mit den tv und verstärker modulen sowie dem remotecontrol modul ziemlich schwung in den bereich audio und video geräte gekommen. zusätzlich gibt es noch eine ganze reihe älterer module wie sonor und xbmc und zwei arten itunes anzusprechen und neue module wie für die web radios oder das raspberry multiroom stehen vor der tür.

::wie wäre es sich rechtzeitig auf ein möglichst einheitiches kommando set zu verständigen damit grundlegende dinge wie play/pause/volume/next bei allen geräten einheitlich, in gleicher schreibweise und mit möglichst ähnlichen parametern funktionieren?

::das würde module wie die remotecontrol aber auch structure und lightscene deutlich einfacher und nützlicher machen und auch alternative frontends erleichtern wenn bestimmte features wie audio,video oder cover über ein einheitliches schema markiert würden.

::mein vorschlag wäre sich an das sonos modul anzulehnen weil es mir in dieser hinsicht am fortgeschrittensten erscheint und auch weitergehende features wie cover oder durchsagen anbietet.

::zu vereinheitlichen wäre dann u.a.:
::- welche kommandos zu welchem zweck
::- kommandos sollten einheitlich geschrieben werden. also z.b. immer klein oder immer mixed case.
::- parameter sollten so weit möglich den gleichen wertebereich haben. also z.b. volume immer von 0-100.
::- wenn es aus irgendeinem grund noch ein gerätespezifischer wertebereich nötig ist sollte der zusätzlich vorhanden sein.
::- cover sollten immer auf die gleiche art gelesen werden können
::- ...

Der Thread ist [http://forum.fhem.de/index.php/topic,13784.0.html hier] zu finden.

== Bezeichner ==
siehe [[DevelopmentGuidelines#Bezeichnungen|Bezeichnungen allgmein]]

== Kommandos ==

Diese Tabelle soll eine einheitliche Definition von set-Befehlen aufzeigen. Dazu zählen auch ggf. Parameter und deren Bedeutung.

{| class="wikitable sortable"
! Name !! Parameter !! Bedeutung
|-
| '''on''' || || Schaltet das Gerät ein, so dass es benutzt werden kann.
|-
| '''off''' || || Schaltet das Gerät aus.
|-
| '''play''' || || Startet das Abspielen von Medien (Video, mp3, Radio stream etc.)
|-
| '''pause''' || || Pausiert das Abspielen von Medien, stoppt es aber nicht.
|-
| '''stop''' || || Stoppt (beendet) das Abspielen von Medien.
|-
| '''volume''' || 0 - 100 || Setzt die Lautstärke auf einen prozentualen Wert.
|-
| '''volumeStraight''' || X-Y || Setzt die Lautstärke auf den absoluten Wert, so wie er vom Gerät tatsächlich verwendet wird (z.B. dB)<br><br>''Nur zu Verwenden, wenn das Gerät einen anderen Wertebereich als 0-100% intern verwendet.''
|-
| '''volumeUp''' || [0 - 100] || Erhöht die Lautstärke um einen gerätespezifischen Schritt (z.b. 5%). Wenn die Schrittweite konfigurierbar ist soll das über das Attribut volumeStep erfolgen. Optional kann das Inkrement als optionaler Parameter mit angegeben werden.
|-
| '''volumeDown''' || [0 - 100] || Verringert die Lautstärke um einen gerätespezifischen Schritt (z.b. 5%). Wenn die Schrittweite konfigurierbar ist soll das über das Attribut volumeStep erfolgen. Optional kann das Dekrement als optionaler Parameter mit angegeben werden.
|-
| '''mute''' || <nowiki>on | off | toggle</nowiki> || Aktiviert, deaktiviert oder schaltet die Mutefunktion = Lautstärke der aktuellen Ausgabe wird verringert bzw. abgschaltet (Gerätespezifisch)
|-
| '''repeat''' || <nowiki>one | all | off</nowiki> || Aktivieren der Repeatfunktion = wiederholen des aktuellen Titels/Albums
|-
| '''shuffle''' || <nowiki>on | off</nowiki> || Aktiviert oder deaktiviert die Shufflefunktion = zufällige Wiedergabe.
|-
| '''channel''' || 0 - 9999 || Schaltet auf einen absoluten Sender- oder Programmspeicherplatz (Nicht zu verwechseln mit input)
|-
| '''channelUp''' || || Springt zum nächsten Sender- oder Programmspeicherplatz.
|-
| '''channelDown''' || || Springt zum vorherigen Sender- oder Programmspeicherplatz.
|-
| '''remoteControl''' || # || Parameter ist Hersteller- und Gerätespezifisch. Funktion bei Geräten, die es erlauben die mitgelieferte Hardware Fernbedienung zu simulieren. Parameter in lowerCamelCaps (ggf. muss im Modul selber auf die Herstellerspezifische Schreibweise umcodiert werden; Alles groß- oder klein geschrieben)
|-
| '''input''' || <nowiki>z.B. hdmi[1-n] | av[1-n] | usb | airplay | server [1-n]</nowiki> || Auswahl von Hardwarekanälen (HDMI, DVB-S, PAL, DVI) oder Softwarekanälen (Airplay, IPTV, IP-Radiostream) die das zu steuernde Gerät aktiv schalten soll (zur Darstellung auf TV, Kanalwahl bei AV-Receivern etc.). Da diese Kanäle je nach Gerät und Modellreihen unterschiedliche Bezeichnungen besitzen, sollten alle möglichen Bezeichnungen in Form von lowerCamelCaps angeboten werden.
|-
| '''output''' || <nowiki>z.B. Airtunes1,Airtunes2,Intern</nowiki> || Auswahl des/der Ausgabegerätes.
|-
| '''statusRequest''' || || Den aktuellen Status des Gerätes abfragen
|-
|colspan="3"| ...
|}

== Readings ==

Diese Tabelle soll eine einheitliche Wertedefinition von Readings. Dazu zählen auch die verwendeten Werte und deren Bedeutung.

Wenn es zwischen reading und zugehörigen set eine 1:1 Beziehung gibt sollte sich der Inhalt des readings als Argument des set verwenden lassen um genau diesen dargestellten Zustand zu erreichen.

{| class="wikitable"
|-
! Name !! mögliche Werte !! Bedeutung
|-
| '''power''' || <nowiki>on|off</nowiki> || Ist das Gerät an oder aus?
|-
| '''presence''' || <nowiki>present|absent</nowiki> || Ist das Gerät aktuell ansprechbar? Sollte das Gerät aufgrund abgeschalteten Stromzufuhr, o.ä. aktuell nicht steuerbar sein, so sollte dies mit dem Wert "absent" verdeutlicht werden. In solch einem Fall sollte ein set-Befehl eine entsprechende Fehlermeldung bringen. Evtl. StatusUpdate-Timer sollten ensprechende Fehlermeldungen nur einmal im Log, etc. festhalten und Fehlermeldungen beim nächsten Status-Update entsprechend unterdrücken um so die Logfiles nicht unnötig vollzuschreiben. Auch das presence reading sollte nur dann aktualisiert werden wenn sich der Status geändert hat um am timestamp sehen zu können wann das war. event-on-change-reading ist hierzu nicht ausreichend weil nur das Event unterdrückt wird der Timestamp sich aber trotzdem ändert.
|-
| '''volume''' || 0-100 || Der prozentuale Lautstärkepegel gemessen der maximal möglichen tatsächlichen Werte.
|-
| '''volumeStraight''' || X-Y || Der tatsächliche Lautstärkepegel des Gerätes, so wie er am Gerät angezeigt/verwendet wird. <br><br>''Nur zu Verwenden, wenn das Gerät einen anderen Wertebereich als 0-100% intern verwendet.''
|-
| '''mute''' || <nowiki>on | off</nowiki> || Ist das Gerät aktuell stumm geschaltet?
|-
| '''repeat''' || <nowiki>one | all | off</nowiki> || Ist das Gerät im repeat modus?
|-
| '''shuffle''' || <nowiki>on | off</nowiki> || Ist das Gerät im shuffle modus?
|-
| '''input''' || ''aktuell gewählter Eingangskanal'' ||
|-
| '''output''' || ''aktuell gewählte(s) Ausgabegerät(e)'' ||
|-
| '''channel''' || ''aktuell gewählter Eingangskanal entsprechend dem Gerät''||
|-
| '''currentArtist''' || ''aktueller Interpret'' ||
|-
| '''currentAlbum''' || ''aktuelles Album'' ||
|-
| '''currentTitle''' || ''aktueller Titelname'' ||
|-
| '''currentMedia''' || ''"Name" der Wiedergabe"datei"'' || kann alles sein: Datei vom Filesystem, Stream aus dem Internet, m3u-URL oder was auch immer
|-
| '''playStatus''' || <nowiki>playing | paused | stopped</nowiki> ||
|-
| '''state''' || <nowiki>on | off | absent</nowiki> || Sofern das Gerät empfangsbereit ist, soll der Schaltzustand des Gerätes (Reading: power, sofern anwendbar) zurückgegeben werden. Ansonsten ist die Abwesenheit des Gerätes durch den Wert "absent" anzuzeigen.
|-
|colspan="3"| ...
|}

== Implementation in Modulen ==
{{yes}} = Implementiert {{yes2}} = device spezifisch {{planed}} = Implementation geplant/in Arbeit {{no}} = Nicht implementiert/Keine Implementation geplant

{| class="wikitable"
! set-Befehl !! LGTV !! LISTENLIVE !! STV !! VIERA !! YAMAHA_AVR !! iTunes !! ENIGMA2 !! ONKYO_AVR !! Squeezebox !! PHTV !! PIONEER !! harmony !! plex
|-
| '''on''' || || || || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} ||
|-
| '''off''' || || || || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} ||
|-
| '''play''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{yes-c}}
|-
| '''pause''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{yes-c}}
|-
| '''stop''' || || || || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{yes-c}}
|-
| '''volume''' || || || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}}
|-
| '''volumeStraight''' || || || || {{no-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{planed-c}}|| {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{no-c}}
|-
| '''volumeUp''' || || || || {{yes-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{no-c}}
|-
| '''volumeDown''' || || || || {{yes-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{no-c}}
|-
| '''mute''' || || || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{no-c}}
|-
| '''repeat''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes2-c}} || {{yes-c}} || {{no-c}} || {{yes2-c}} || {{yes2-c}} || {{yes-c}}
|-
| '''shuffle''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes2-c}} || {{yes-c}} || {{no-c}} || {{yes2-c}} || {{yes2-c}} || {{yes-c}}
|-
| '''channel''' || || || || {{yes-c}} || {{no-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{no-c}}
|-
| '''channelUp''' || || || || {{yes-c}} || {{no-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{no-c}}
|-
| '''channelDown''' || || || || {{yes-c}} || {{no-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{no-c}}
|-
| '''remoteControl''' || || || || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes2-c}} || {{yes2-c}} || {{no-c}}
|-
| '''input''' || {{yes-c}} || || || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}}|| {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{no-c}}
|-
| '''output''' || || || || {{no-c}} || {{no-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{no-c}} || {{no-c}} || {{no-c}} || {{yes2-c}} || {{no-c}}
|-
| '''statusRequest''' || || {{yes-c}} || || {{yes-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{no-c}}
|-
! Reading !! LGTV !! LISTENLIVE !! STV !! VIERA !! YAMAHA_AVR !! iTunes !! ENIGMA2 !! ONKYO_AVR !! Squeezebox !! PHTV !! PIONEER !! harmony
|-
| '''power''' || || || || {{yes-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} ||
|-
| '''presence''' || || || || {{yes-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}}
|-
| '''volume''' || || || || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}}
|-
| '''volumeStraight''' || || || || {{no-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{no-c}}
|-
| '''mute''' || || || || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{planed-c}}
|-
| '''repeat''' || || || || {{no-c}} || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes2-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{no-c}} || {{planed-c}}
|-
| '''shuffle''' || || || || {{no-c}} || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes2-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{no-c}} || {{planed-c}}
|-
| '''input''' || || || || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{no-c}}
|-
| '''output''' || || || || {{no-c}} || {{no-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{no-c}} || {{no-c}} || {{no-c}} || {{no-c}} || {{no-c}}
|-
| '''channel''' || || || || {{yes-c}} || {{no-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{no-c}}
|-
| '''currentArtist''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes-c}}
|-
| '''currentAlbum''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes-c}}
|-
| '''currentTitle''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes-c}}
|-
| '''currentMedia''' || || || || {{no-c}} || {{no-c}} || {{planed-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{no-c}} ||
|-
| '''playStatus''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{no-c}} ||
|-
| '''state''' || || || || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}}
|}

== Sonstiges ==
=== Wie funktioniert Cover Art? ===
Reading mit URL-Link oder als Gerätestatus???

=== Wie funktionieren Sprachdurchsagen oder Text Einblendungen? ===

Obwohl dies sehr stark davon abhängt, ob das jeweilige Gerät eine solche Funktion unterstützt, oder ob sie anderweitig (z.B. durch Google Service) umgesetzt werden können, so sollen dennoch solche Features über die folgenden Set-Kommandos angeboten werden.
{| class="wikitable"
|-
! Kommando !! Beispiel !! Beschreibung
|-
| '''sayText'''|| <pre>set ''<device>'' sayText "Anruf in Abwesenheit"</pre>
|| Dieses Kommando soll den übergebenen Text auf dem jeweiligen Device in Audio-Form wieder ausgeben. Hierbei kann auf einen Synthese-Anbieter im Internet zurückgegriffen werden, der ein solches Audiosample erzeugt, oder geräteinterne Kommandos verwendet werden, je nach dem was vorhanden und unterstützt wird.
|-
| '''showText''' || <pre>set ''<device>'' showText "Anruf in Abwesenheit"</pre>|| Dieses Kommando soll einen Text z.B. auf dem Display des Gerätes (oder Fernseher) in geeigneter Form anzeigen, sofern das Gerät eine solche Funktion unterstützt.
|-
! colspan="3"| Alternativvorschlag
|-
| '''message''' || <pre>set ''<device>'' message "Anruf in Abwesenheit" [audio|video]</pre>|| Dieses Kommando soll eine Nachricht mit dem Gerät anzeigen (video) oder abspielen (audio), sofern das Gerät eine solche Funktion unterstützt. Ohne die optionale Wiedergabe-Art oder wenn die angegebene nicht unterstützt ist über die von diesem Gerät bevorzugte Methode.
|}

=== Wie funktionieren Playlisten? ===

Sofern anwendbar, sollten diese mit dem Kommando <code>set <device> playlist XY</code> aufrufbar sein. Dabei sollten die zur Verfügung stehenden Playlists bereits bekannt sein und als möglicher Kommando-Parameter angeboten werden.

=== Wie funktionieren Zonen? ===

Jede einzelne Zone eines Gerätes wird durch ein eigenes FHEM-Device repräsentiert. Die gewünschte Zone ist als optionaler Parameter in den Definitions-Argumenten zu übergeben.

Wenn keine bestimmte Zone explizit in der Definition übergeben wird, ist die Hauptzone (Main-Zone) zu verwenden. Die zur Verfügung stehenden Zonen sollten in den Internals aufgelistet sein, mindestens jedoch in der commandref des entsprechenden Moduls.

Jede Definition sollte nur die tatsächlich möglichen Befehle, Eingänge, etc. der entsprechenden Zone anbieten.

[[Kategorie:Development]]

DevelopmentGuidelinesAV

2016-05-22T17:36:23Z

Loredo: Update ONKYO

== Einleitung ==
Auf dieser Seite sollen Richtlinien für AV-Module gesammelt werden damit es einfacher wird diese zusammen mit anderen Modulen wie remotecontroll oder LightScene zu verwenden. Auch Benachrichtigungen wie Sprachdurchsagen oder Einblendungen lassen sich universeller verwenden wenn sie bei allen Geräten die dies unterstützen gleich angesprochen werden.

Der Text aus dem ursprünglichen Forumsthread war folgender:

::gerade ist ja mit den tv und verstärker modulen sowie dem remotecontrol modul ziemlich schwung in den bereich audio und video geräte gekommen. zusätzlich gibt es noch eine ganze reihe älterer module wie sonor und xbmc und zwei arten itunes anzusprechen und neue module wie für die web radios oder das raspberry multiroom stehen vor der tür.

::wie wäre es sich rechtzeitig auf ein möglichst einheitiches kommando set zu verständigen damit grundlegende dinge wie play/pause/volume/next bei allen geräten einheitlich, in gleicher schreibweise und mit möglichst ähnlichen parametern funktionieren?

::das würde module wie die remotecontrol aber auch structure und lightscene deutlich einfacher und nützlicher machen und auch alternative frontends erleichtern wenn bestimmte features wie audio,video oder cover über ein einheitliches schema markiert würden.

::mein vorschlag wäre sich an das sonos modul anzulehnen weil es mir in dieser hinsicht am fortgeschrittensten erscheint und auch weitergehende features wie cover oder durchsagen anbietet.

::zu vereinheitlichen wäre dann u.a.:
::- welche kommandos zu welchem zweck
::- kommandos sollten einheitlich geschrieben werden. also z.b. immer klein oder immer mixed case.
::- parameter sollten so weit möglich den gleichen wertebereich haben. also z.b. volume immer von 0-100.
::- wenn es aus irgendeinem grund noch ein gerätespezifischer wertebereich nötig ist sollte der zusätzlich vorhanden sein.
::- cover sollten immer auf die gleiche art gelesen werden können
::- ...

Der Thread ist [http://forum.fhem.de/index.php/topic,13784.0.html hier] zu finden.

== Bezeichner ==
siehe [[DevelopmentGuidelines#Bezeichnungen|Bezeichnungen allgmein]]

== Kommandos ==

Diese Tabelle soll eine einheitliche Definition von set-Befehlen aufzeigen. Dazu zählen auch ggf. Parameter und deren Bedeutung.

{| class="wikitable sortable"
! Name !! Parameter !! Bedeutung
|-
| '''on''' || || Schaltet das Gerät ein, so dass es benutzt werden kann.
|-
| '''off''' || || Schaltet das Gerät aus.
|-
| '''play''' || || Startet das Abspielen von Medien (Video, mp3, Radio stream etc.)
|-
| '''pause''' || || Pausiert das Abspielen von Medien, stoppt es aber nicht.
|-
| '''stop''' || || Stoppt (beendet) das Abspielen von Medien.
|-
| '''volume''' || 0 - 100 || Setzt die Lautstärke auf einen prozentualen Wert.
|-
| '''volumeStraight''' || X-Y || Setzt die Lautstärke auf den absoluten Wert, so wie er vom Gerät tatsächlich verwendet wird (z.B. dB)<br><br>''Nur zu Verwenden, wenn das Gerät einen anderen Wertebereich als 0-100% intern verwendet.''
|-
| '''volumeUp''' || [0 - 100] || Erhöht die Lautstärke um einen gerätespezifischen Schritt (z.b. 5%). Wenn die Schrittweite konfigurierbar ist soll das über das Attribut volumeStep erfolgen. Optional kann das Inkrement als optionaler Parameter mit angegeben werden.
|-
| '''volumeDown''' || [0 - 100] || Verringert die Lautstärke um einen gerätespezifischen Schritt (z.b. 5%). Wenn die Schrittweite konfigurierbar ist soll das über das Attribut volumeStep erfolgen. Optional kann das Dekrement als optionaler Parameter mit angegeben werden.
|-
| '''mute''' || <nowiki>on | off | toggle</nowiki> || Aktiviert, deaktiviert oder schaltet die Mutefunktion = Lautstärke der aktuellen Ausgabe wird verringert bzw. abgschaltet (Gerätespezifisch)
|-
| '''repeat''' || <nowiki>one | all | off</nowiki> || Aktivieren der Repeatfunktion = wiederholen des aktuellen Titels/Albums
|-
| '''shuffle''' || <nowiki>on | off</nowiki> || Aktiviert oder deaktiviert die Shufflefunktion = zufällige Wiedergabe.
|-
| '''channel''' || 0 - 9999 || Schaltet auf einen absoluten Sender- oder Programmspeicherplatz (Nicht zu verwechseln mit input)
|-
| '''channelUp''' || || Springt zum nächsten Sender- oder Programmspeicherplatz.
|-
| '''channelDown''' || || Springt zum vorherigen Sender- oder Programmspeicherplatz.
|-
| '''remoteControl''' || # || Parameter ist Hersteller- und Gerätespezifisch. Funktion bei Geräten, die es erlauben die mitgelieferte Hardware Fernbedienung zu simulieren. Parameter in lowerCamelCaps (ggf. muss im Modul selber auf die Herstellerspezifische Schreibweise umcodiert werden; Alles groß- oder klein geschrieben)
|-
| '''input''' || <nowiki>z.B. hdmi[1-n] | av[1-n] | usb | airplay | server [1-n]</nowiki> || Auswahl von Hardwarekanälen (HDMI, DVB-S, PAL, DVI) oder Softwarekanälen (Airplay, IPTV, IP-Radiostream) die das zu steuernde Gerät aktiv schalten soll (zur Darstellung auf TV, Kanalwahl bei AV-Receivern etc.). Da diese Kanäle je nach Gerät und Modellreihen unterschiedliche Bezeichnungen besitzen, sollten alle möglichen Bezeichnungen in Form von lowerCamelCaps angeboten werden.
|-
| '''output''' || <nowiki>z.B. Airtunes1,Airtunes2,Intern</nowiki> || Auswahl des/der Ausgabegerätes.
|-
| '''statusRequest''' || || Den aktuellen Status des Gerätes abfragen
|-
|colspan="3"| ...
|}

== Readings ==

Diese Tabelle soll eine einheitliche Wertedefinition von Readings. Dazu zählen auch die verwendeten Werte und deren Bedeutung.

Wenn es zwischen reading und zugehörigen set eine 1:1 Beziehung gibt sollte sich der Inhalt des readings als Argument des set verwenden lassen um genau diesen dargestellten Zustand zu erreichen.

{| class="wikitable"
|-
! Name !! mögliche Werte !! Bedeutung
|-
| '''power''' || <nowiki>on|off</nowiki> || Ist das Gerät an oder aus?
|-
| '''presence''' || <nowiki>present|absent</nowiki> || Ist das Gerät aktuell ansprechbar? Sollte das Gerät aufgrund abgeschalteten Stromzufuhr, o.ä. aktuell nicht steuerbar sein, so sollte dies mit dem Wert "absent" verdeutlicht werden. In solch einem Fall sollte ein set-Befehl eine entsprechende Fehlermeldung bringen. Evtl. StatusUpdate-Timer sollten ensprechende Fehlermeldungen nur einmal im Log, etc. festhalten und Fehlermeldungen beim nächsten Status-Update entsprechend unterdrücken um so die Logfiles nicht unnötig vollzuschreiben. Auch das presence reading sollte nur dann aktualisiert werden wenn sich der Status geändert hat um am timestamp sehen zu können wann das war. event-on-change-reading ist hierzu nicht ausreichend weil nur das Event unterdrückt wird der Timestamp sich aber trotzdem ändert.
|-
| '''volume''' || 0-100 || Der prozentuale Lautstärkepegel gemessen der maximal möglichen tatsächlichen Werte.
|-
| '''volumeStraight''' || X-Y || Der tatsächliche Lautstärkepegel des Gerätes, so wie er am Gerät angezeigt/verwendet wird. <br><br>''Nur zu Verwenden, wenn das Gerät einen anderen Wertebereich als 0-100% intern verwendet.''
|-
| '''mute''' || <nowiki>on | off</nowiki> || Ist das Gerät aktuell stumm geschaltet?
|-
| '''repeat''' || <nowiki>one | all | off</nowiki> || Ist das Gerät im repeat modus?
|-
| '''shuffle''' || <nowiki>on | off</nowiki> || Ist das Gerät im shuffle modus?
|-
| '''input''' || ''aktuell gewählter Eingangskanal'' ||
|-
| '''output''' || ''aktuell gewählte(s) Ausgabegerät(e)'' ||
|-
| '''channel''' || ''aktuell gewählter Eingangskanal entsprechend dem Gerät''||
|-
| '''currentArtist''' || ''aktueller Interpret'' ||
|-
| '''currentAlbum''' || ''aktuelles Album'' ||
|-
| '''currentTitle''' || ''aktueller Titelname'' ||
|-
| '''currentMedia''' || ''"Name" der Wiedergabe"datei"'' || kann alles sein: Datei vom Filesystem, Stream aus dem Internet, m3u-URL oder was auch immer
|-
| '''playStatus''' || <nowiki>playing | paused | stopped</nowiki> ||
|-
| '''state''' || <nowiki>on | off | absent</nowiki> || Sofern das Gerät empfangsbereit ist, soll der Schaltzustand des Gerätes (Reading: power, sofern anwendbar) zurückgegeben werden. Ansonsten ist die Abwesenheit des Gerätes durch den Wert "absent" anzuzeigen.
|-
|colspan="3"| ...
|}

== Implementation in Modulen ==
{{yes}} = Implementiert {{yes2}} = device spezifisch {{planed}} = Implementation geplant/in Arbeit {{no}} = Nicht implementiert/Keine Implementation geplant

{| class="wikitable"
! set-Befehl !! LGTV !! LISTENLIVE !! STV !! VIERA !! YAMAHA_AVR !! iTunes !! ENIGMA2 !! ONKYO_AVR !! Squeezebox !! PHTV !! PIONEER !! harmony !! plex
|-
| '''on''' || || || || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} ||
|-
| '''off''' || || || || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} ||
|-
| '''play''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{yes-c}}
|-
| '''pause''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{yes-c}}
|-
| '''stop''' || || || || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{yes-c}}
|-
| '''volume''' || || || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}}
|-
| '''volumeStraight''' || || || || {{no-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{planed-c}}|| {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{no-c}}
|-
| '''volumeUp''' || || || || {{yes-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{no-c}}
|-
| '''volumeDown''' || || || || {{yes-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{no-c}}
|-
| '''mute''' || || || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{no-c}}
|-
| '''repeat''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes2-c}} || {{yes-c}} || {{no-c}} || {{yes2-c}} || {{yes2-c}} || {{yes-c}}
|-
| '''shuffle''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes2-c}} || {{yes-c}} || {{no-c}} || {{yes2-c}} || {{yes2-c}} || {{yes-c}}
|-
| '''channel''' || || || || {{yes-c}} || {{no-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{no-c}}
|-
| '''channelUp''' || || || || {{yes-c}} || {{no-c}} || {{no-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{no-c}}
|-
| '''channelDown''' || || || || {{yes-c}} || {{no-c}} || {{no-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{no-c}}
|-
| '''remoteControl''' || || || || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes2-c}} || {{yes2-c}} || {{no-c}}
|-
| '''input''' || {{yes-c}} || || || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}}|| {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes2-c}} || {{no-c}}
|-
| '''output''' || || || || {{no-c}} || {{no-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{no-c}} || {{no-c}} || {{no-c}} || {{yes2-c}} || {{no-c}}
|-
| '''statusRequest''' || || {{yes-c}} || || {{yes-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{no-c}}
|-
! Reading !! LGTV !! LISTENLIVE !! STV !! VIERA !! YAMAHA_AVR !! iTunes !! ENIGMA2 !! ONKYO_AVR !! Squeezebox !! PHTV !! PIONEER !! harmony
|-
| '''power''' || || || || {{yes-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} ||
|-
| '''presence''' || || || || {{yes-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}}
|-
| '''volume''' || || || || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}}
|-
| '''volumeStraight''' || || || || {{no-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{no-c}}
|-
| '''mute''' || || || || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{planed-c}}
|-
| '''repeat''' || || || || {{no-c}} || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes2-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{no-c}} || {{planed-c}}
|-
| '''shuffle''' || || || || {{no-c}} || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes2-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{no-c}} || {{planed-c}}
|-
| '''input''' || || || || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{no-c}}
|-
| '''output''' || || || || {{no-c}} || {{no-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{no-c}} || {{no-c}} || {{no-c}} || {{no-c}} || {{no-c}}
|-
| '''channel''' || || || || {{yes-c}} || {{no-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{no-c}}
|-
| '''currentArtist''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes-c}}
|-
| '''currentAlbum''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes-c}}
|-
| '''currentTitle''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}} || {{no-c}} || {{yes-c}}
|-
| '''currentMedia''' || || || || {{no-c}} || {{no-c}} || {{planed-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{no-c}} ||
|-
| '''playStatus''' || || || || {{no-c}} || {{yes-c}} || {{yes-c}} || {{planed-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{no-c}} || {{no-c}} ||
|-
| '''state''' || || || || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{yes-c}} || {{no-c}} || {{yes-c}}
|}

== Sonstiges ==
=== Wie funktioniert Cover Art? ===
Reading mit URL-Link oder als Gerätestatus???

=== Wie funktionieren Sprachdurchsagen oder Text Einblendungen? ===

Obwohl dies sehr stark davon abhängt, ob das jeweilige Gerät eine solche Funktion unterstützt, oder ob sie anderweitig (z.B. durch Google Service) umgesetzt werden können, so sollen dennoch solche Features über die folgenden Set-Kommandos angeboten werden.
{| class="wikitable"
|-
! Kommando !! Beispiel !! Beschreibung
|-
| '''sayText'''|| <pre>set ''<device>'' sayText "Anruf in Abwesenheit"</pre>
|| Dieses Kommando soll den übergebenen Text auf dem jeweiligen Device in Audio-Form wieder ausgeben. Hierbei kann auf einen Synthese-Anbieter im Internet zurückgegriffen werden, der ein solches Audiosample erzeugt, oder geräteinterne Kommandos verwendet werden, je nach dem was vorhanden und unterstützt wird.
|-
| '''showText''' || <pre>set ''<device>'' showText "Anruf in Abwesenheit"</pre>|| Dieses Kommando soll einen Text z.B. auf dem Display des Gerätes (oder Fernseher) in geeigneter Form anzeigen, sofern das Gerät eine solche Funktion unterstützt.
|-
! colspan="3"| Alternativvorschlag
|-
| '''message''' || <pre>set ''<device>'' message "Anruf in Abwesenheit" [audio|video]</pre>|| Dieses Kommando soll eine Nachricht mit dem Gerät anzeigen (video) oder abspielen (audio), sofern das Gerät eine solche Funktion unterstützt. Ohne die optionale Wiedergabe-Art oder wenn die angegebene nicht unterstützt ist über die von diesem Gerät bevorzugte Methode.
|}

=== Wie funktionieren Playlisten? ===

Sofern anwendbar, sollten diese mit dem Kommando <code>set <device> playlist XY</code> aufrufbar sein. Dabei sollten die zur Verfügung stehenden Playlists bereits bekannt sein und als möglicher Kommando-Parameter angeboten werden.

=== Wie funktionieren Zonen? ===

Jede einzelne Zone eines Gerätes wird durch ein eigenes FHEM-Device repräsentiert. Die gewünschte Zone ist als optionaler Parameter in den Definitions-Argumenten zu übergeben.

Wenn keine bestimmte Zone explizit in der Definition übergeben wird, ist die Hauptzone (Main-Zone) zu verwenden. Die zur Verfügung stehenden Zonen sollten in den Internals aufgelistet sein, mindestens jedoch in der commandref des entsprechenden Moduls.

Jede Definition sollte nur die tatsächlich möglichen Befehle, Eingänge, etc. der entsprechenden Zone anbieten.

[[Kategorie:Development]]

Anwesenheitserkennung

2016-01-02T10:21:31Z

Loredo: /* GEOFANCY Modul individualisieren */

Viele Benutzer führen bereits eine eigene '''Anwesenheitserkennung''' durch. Diese basiert in den meisten Fällen auf Ping Checks oder bei [[AVM Fritz!Box|FritzBoxen]] auf dem Befehl ''ctlmgr_ctl''. Diese Lösungen können aber je nach Aufbau und Funktion FHEM massiv beeinträchtigen. Aufgrund des Aufbaus vom FHEM kann dieses dadurch für mehrere Sekunden zum völligen Stillstand gebracht werden.

In FHEM gibt es mittlerweile mehrere Module, die eine zuverlässige Anwesenheitserkennung bieten, ohne dabei FHEM bei der Ausführung zu beeinträchtigen.

Eine erweiterte Funktion der Anwesenheitserkennung ist die Standortverfolgung, die sich nicht nur auf ein oder sehr wenige mit (eigenem) WLAN versorgte Gebiete beschränkt.

== Vorüberlegungen ==
Generell gibt es mehrere Ansätze um Anwesenheitserkennung mit Handys/Smartphones durchzuführen.

* via PING Checks im gesamten WLAN
* Aktivitätsprüfung auf einer FritzBox
* Bluetooth Checks in der gesamten Wohnung
* eigene Perl-Funktion
* aktive Benachrichtigung des Smartphones, ausgelöst z.B. über Geo-Lokation/Geofence

Dabei gilt bei der Auswahl der Art darauf zu achten wie sich das jeweilige Device verhält. Aufgrund der Vielfältigkeit kann man hier keine allgemeine Vorgehensweise empfehlen. Als einfacher Start (zumindest für Nicht-Apfel Telefone) eignet sich die Ping-Überprüfung und die FritzBox-Abfrage sehr gut.

=== Randbedingungen ===
Es gibt Geräte, die ihr WLAN/Bluetooth auch im Standby ständig aktiv haben und auf Anfragen antworten können (fast alle Android-Geräte). Gerade bei Tests über WLAN kann sich das aber signifikant auf die Akku Leistung auswirken.

Andere Geräte wiederum schalten WLAN im Standby Betrieb aus, um Akkukapazität zu sparen. Bluetooth hingegen bleibt weiterhin aktiviert und kann auf Anfragen reagieren. (iPhone)

Wenn man bei einem iPhone die Funktion "über WLAN synchronisieren" aktiviert hat, so ist dies auch im Standby jederzeit pingbar, wenn der Recher auf dem iTunes zum synchroniseren läuft auch an ist. Ansonsten ist bei iPhone Geräten nur die Aktivitätsprüfung mit einer FritzBox oder das überwachen der DHCP Lease auf einer Airport Basestation wirklich zuverlässig.

Auch wenn Bluetooth aktiviert ist, so bleiben einige Mobiltelefone erst dann empfangsbereit, wenn sie bereits zu irgend einem Bluetoothgerät gekoppelt wurden. Sind diese Geräte noch nie gekoppelt worden, deaktivieren diese ihren Bluetooth Empfänger beim verlassen des Bluetooth-Menüs im Gerät (iPhone).

Hier gilt es vor allem auszuprobieren, wie stark der Akku durch eine Anwesenheitserkennung belastet wird. Entscheidend ist hier, in welchem Abstand man eine Anwesenheitserkennung durchführt. Viele Abfragen wirken sich stärker auf den Akku aus als wenige. Wenige Abfragen bieten aber keine zuverlässige und zeitnahe Erkennung.

Als Alternative, unabhängig vom WLAN und der Erkennung, ob ein Gerät dort eingebucht ist oder nicht, bzw. unabhängig von Bluetooth kann zumindest bei einem iPhone die seit iOS 7 nochmals stark verbesserte Geo-Lokation (Geofencing) genutzt werden. Die iPhone Apps [http://geofency.com/ Geofency] oder [http://geofancy.com/ Geofancy] werden über das FHEM-Modul GEOFANCY angebunden und übertragen ihren Status immer dann, wenn ein definierter Standort betreten oder verlassen wird. Gekoppelt mit entsprechenden Notify und/oder Watchdog Kommandos ist so ebenfalls eine sehr zuverlässige Anwesenheitserkennung möglich (und das nicht nur für das eigene Zuhause).

== Das PRESENCE Modul ==
Das [[PRESENCE]] Modul bietet für die Anwesenheitserkennung mehrere Varianten an. Diese sind aktuell folgende:

* '''lan-ping''' - Das Überwachen via PING Checks, die durch den FHEM Server versandt werden.
* '''fritzbox''' - Das Überwachen von Geräten auf einer FritzBox via ctlmgr_ctl (Nur auf einer FritzBox möglich)
* '''local-bluetooth''' - Das Überwachen via Bluetooth Checks, die vom FHEM Server direkt durchgeführt werden (angeschlossener Bluetooth-Stick und die Software bluez voraussgesetzt)
* '''lan-bluetooth''' - Das Überwachen von Bluetoothgeräte, über Netzwerk. Auf einer oder mehreren Maschinen im Netzwerk (z.B. [[:Kategorie:Raspberry Pi|Raspberry Pi]]) läuft ein Presence-Daemon, der nach Bluetooth-Geräten sucht. Um mehrere Presence-Daemon mit FHEM zu verbinden, gibt es den Collector-Daemon, der sich zu allen Presence-Damons im Netzwerk verbindet und das Ergebnis von allen zusammenfasst.
* '''function''' - Das Überwachen mithilfe einer selbst geschrieben Perl-Funktion, die den Anwesenheitsstatus zurückgibt (0 oder 1)
* '''shell-script''' - Das Überwachen mithilfe eines selbst geschriebenen Shell-Programms/Skript, das eine 0 oder 1 ausgibt, um den Anwesenheitsstatus mitzuteilen.

=== Ping-Überwachung von Geräten im WLAN/LAN ===
{{Randnotiz|RNText=Um diese Methode auf einer FritzBox nutzen zu können, muss FHEM mit root-Rechten laufen. Dies ist standardmäßig nicht der Fall. Bitte dazu den Wiki Artikel [[FritzBox: fhem unter root starten]] beachten.}}
Um ein Gerät via Ping zu überwachen, muss folgende Definition durchgeführt werden:
:<code>define Handy PRESENCE lan-ping 192.168.0.30</code>

Dadurch wird die IP-Addresse 192.168.0.30 alle 30 Sekunden geprüft, ob sie erreichbar ist. Wenn sie erreichbar ist, ist der Status "present" (anwesend), ansonsten "absent" (abwesend).

Der Timeout kann verändert werden, indem ein Wert (in Sekunden) an das Define anhängt wird:
:<code>define Handy PRESENCE lan-ping 192.168.0.30 '''60'''</code>

Nun würde das Handy alle 60 Sekunden geprüft werden.

Nur wenn bei einem iPhone/iPad die Funktion "über WLAN synchronisieren" aktiviert ist, ist es auch im Standby zuverlässig pingbar. Standardmäßig deaktivieren Apple-Geräte ihr WLAN im Standby-Betrieb um die Akkulaufzeit zu verlängern.

=== FritzBox: direktes Abfragen der Aktivität via ctlmgr_ctl ===
{{Randnotiz|RNText=Um diese Methode auf einer FritzBox nutzen zu können, muss FHEM mit root-Rechten laufen. Dies ist standardmäßig nicht der Fall. Bitte dazu den Wiki Artikel [[FritzBox: fhem unter root starten]] beachten.}}
Eine sehr häufige und auch zuverlässige Methode ist auf einer FritzBox die Abfrage mittels ctlmgr_ctl Befehl. Über diesen lassen sich alle Geräte abfragen ob sie aktiv sind. Ist ein Gerät aktiv, so gilt es als anwesend.

Dieser Modus kann allerdings nur in FHEM Installationen direkt auf einer FritzBox verwendet werden. Des weiteren muss FHEM unter dem User root laufen. Um ein Gerät zu überwachen, wird lediglich der Gerätename benötigt, so wie er unter dem Menüpunkt "Heimnetz" auftaucht.

Die erforderliche Definition:
:<code>define Handy PRESENCE fritzbox iPhone-4S</code>

=== Bluetooth-Überwachung von Geräten durch den FHEM Server ===
[[Datei:Bluetooth-Adresse-iPhone.png|thumb|Bluetooth-Adresse eines iPhones]]
Jenach Aufstellungsort des FHEM Servers kann es sinnvoll sein, eine Bluetooth-Überwachung direkt durch den FHEM Server durchzuführen. Hierbei gilt allerdings zu beachten, dass Bluetooth nicht für große Reichweiten gedacht ist und in den meisten Fällen keine Wände überwinden kann. Das heisst, dass in den meisten Fällen damit nur ein Raum überwacht werden kann.

Je nach Einsatzzweck kann das auch so gewollt sein. Bluetooth USB Sticks, die bereits Bluetooth 4.0 unterstützen, können höhere Reichweiten über Zimmerwände hinaus erreichen. Vorausgesetzt, das Mobilgerät unterstützt Bluetooth 4.0.

Um eine Überwachung per Bluetooth durchführen zu können, benötigt man die Bluetooth-Adresse eines Gerätes. Diese ähnelt vom Aufbau einer MAC-Adresse. Generell wird die Adresse in den Telefon-Informationen bei Smartphones angezeigt.

Um eine Anwesenheitserkennung via Bluetooth durchzuführen, wird folgende Definition in der [[Konfiguration]] benötigt:
:<code>define Handy PRESENCE local-bluetooth XX:XX:XX:XX:XX:XX</code>

=== Bluetooth-Überwachung von Geräten durch verteilte Agenten in der Wohnung (presencd/collectord) ===
[[Datei:Raspberry-Pi-mit-WLAN-und-Bluetooth-Stick.jpg|thumb|left|Raspberry Pi mit Bluetooth- und WLAN-USB-Stick]]
Um eine zuverlässige und flächendeckende Bluetooth-Anwesenheitserkennung durchzuführen, ist es unerlässlich, mehrere Bluetooth-Empfänger zu verwenden, die auf mehrere oder alle Räume verteilt sind.

Hierfür bietet sich zum Beispiel ein [[Raspberry Pi]] mit einem Mini-Bluetooth-USB-Stick und evtl. einem WLAN-USB-Stick an. Jeder Raum wird mit solch einem Raspberry ausgestattet und ist im WLAN Netz verfügbar.

Dieses Netz aus Raspberrys wird mit dem presenced (Download-Link ist in der [http://fhem.de/commandref_DE.html#PRESENCE Commandref] zum Modul enthalten) ausgestattet. Es stehen bereits entsprechende Pakete für den Raspberry zur Verfügung.

Beide Programme (presenced/collectord) sind Perl-Skripte, die als Daemon im Hintergrund laufen und auf Anfragen via Netzwerk warten. Es wird lediglich eine vollständige Perl-Grundinstallation mit Standardmodulen benötigt. Nach Installation der *.deb Pakete sollten diese noch angewiesen werden, automatisch beim Rechner-Neustart gestartet zu werden:

<pre>
sudo update-rc.d presenced defaults
sudo update-rc.d collectord defaults
</pre>

Eine detaillierte Benutzung von presenced ist in der [http://fhem.de/commandref_DE.html#PRESENCE Commandref] Beschreibung zum PRESENCE Modul enthalten.

==== Jeden Raum einzeln ansprechen (presenced) ====
Nun kann zuallererst jeder Raum einzeln angesprochen werden. Dabei ist zu beachten, dass pro Definition in der Konfiguration nur ein Gerät in einem Raum spezifisch überwacht werden kann.

Eine Definition sieht dabei folgendermaßen aus:
:<code>define Handy_Wohnzimmer PRESENCE lan-bluetooth XX:XX:XX:XX:XX:XX 192.168.0.10:5111</code>

Damit wird nun das Gerät nur im Wohnzimmer (Raspberry mit IP 192.168.0.10) überwacht.

==== Alle Räume gemeinsam ansprechen (collectord) ====
Um jedoch alle Räume gemeinsam zu verwenden, gibt es den Collector-Daemon. Dieser kennt alle presenced-Installationen im Netzwerk und führt eine koordinierte Suche nach den gewünschten Geräten durch. Sobald ein Gerät in einem Raum erkannt wurde, meldet der collectord den Status einschließlich der Angabe des Raumes, in dem das Gerät erkannt wurde.

Um alle Räume zu kennen, müssen diese mit einem Config-File dem collectord mitgeteilt werden. Dieses sieht folgendermaßen aus:

<pre>
[Schlafzimmer] # Name des Raumes (wird in FHEM als Reading angezeigt)
address=192.168.179.31 # IP-Adresse oder Hostname des presenced
port=5111 # TCP Port, der verwendet werden soll (standardmäßig Port 5111)
presence_timeout=120 # Prüfinterval, das verwendet werden soll, wenn ein Gerät anwesend ist
absence_timeout=20 # Prüfinterval, das verwendet werden soll, wenn ein Gerät abwesend ist

[Wohnzimmer]
address=192.168.179.34
port=5111
presence_timeout=180
absence_timeout=20
</pre>

Standardmäßig ist dieses Config-File unter /etc/collectord.conf zu finden. Mit dieser Konfiguration kann der Collectord gestartet werden. Es empfiehlt sich diesen mit auf dem FHEM Server zu betreiben. Die erforderliche Definition in der Fhem-Konfiguration:
:<code>define Handy PRESENCE lan-bluetooth XX:XX:XX:XX:XX:XX 127.0.0.1:5222</code>

Sobald das Handy irgendwo in der Wohnung erkannt wurde, meldet der Collectord dies sofort an FHEM und teilt den Raum mit.

Eine detaillierte Benutzung von collectord findet man in der Commandref zum PRESENCE Modul.

=== Überwachung von Geräten mit Perl-Code ===
Es ist möglich zum Überwachen von Geräten eine eigene Perl-Funktion zu verwenden die dann vom PRESENCE Modul im Hintergrund aufgerufen wird.

define <name> PRESENCE function {...} [ <check-interval> [ <present-check-interval> ] ]

Sobald die Funktion den Rückgabewert 1 hat, ist das Gerät anwesend, bei 0 abwesend.

==== Beispiel DHCP Überwachung auf Airport Basestation ====
Die hier vorgestellte Überwachung der DHCP Lease auf Airport Basestations per SNMP ist absolut robust gegenüber dem Ruhezustand von iOS und setzt keine weitere Konfiguration auf dem iPhone voraus. Das Abmelden beim Verlassen des Empfangsbereiches der Basestation geschieht mit etwa 5-10 Minuten Verzögerung und ist somit auch vor kurzzeitigen Empfangsproblemen sicher. Das nebenstehende Bild (???) verdeutlicht noch mal die Unterschiede zwischen einer IP-Basierten Ping-Überwachung und der Überwachung auf Ebene der Basestation oder FritzBox.

Bevor der folgende Code verwendet werden kann ist das Perl Modul Net:SNMP zu installieren (z. B. mit: <code>cpan install use Net::SNMP</code>).

Zuerst ist folgender Code in 99_myUtils.pl einzufügen:

<pre>
use Net::SNMP;
sub
snmpCheck($$)
{
my ($airport,$client)= @_;

my $community = "public";
my $host = $airport;
my $oid = ".1.3.6.1.2.1.3.1.1.2";
#my $oid = ".1.3.6.1.2.1.3.1.1.2.25.1.10.0.1";

my ( $session, $error ) = Net::SNMP->session(
-hostname => $host,
-community => $community,
-port => 161,
-version => 1
);

if( !defined($session) ) {
return 0;
return "Can't connect to host $host.";
}

my @snmpoids = ();

my $response = $session->get_next_request($oid);
my @nextid = keys %$response;
while ( @nextid && $nextid[0] && $nextid[0] =~ m/^$oid/ ) {
push( @snmpoids, $nextid[0] );

$response = $session->get_next_request( $nextid[0] );
@nextid = keys %$response;
}

if( !defined($response = $session->get_request( @snmpoids ) ) ) {
return 0;
}

foreach my $value (values %$response) {
return 1 if( $value eq $client )
}

return 0;
}
</pre>

Danach lässt sich das Mobilgerät so überwachen:
:<code>define iPhone PRESENCE function {snmpCheck("10.0.1.1","0x44d77429f35c")} 30 30</code>

wobei 10.0.1.1 durch die IP-Adresse der Basestation und 0x44d77429f35c durch die MAC Adresse des Geräts als HEX-Zahl ersetzt werden muss.

== Das GEOFANCY Modul ==
Das Modul ermöglicht über einen sogenannten Webhook Mechanismus (umgangssprachlich oft auch als "Push" benannt) das aktive Melden des aktuellen Standortes. Die iPhone Apps [http://geofency.com/ Geofency] und [http://geofancy.com/ Geofancy] können dann aktiv und quasi in dem Moment, wo man den Wohnbereich betritt oder verlässt, benachrichtigen. Android Nutzern können [https://play.google.com/store/apps/details?id=de.egi.geofence.geozone&hl=de EgiGeoZone Geofence] nutzen. Das geht nochmals um einiges schneller, als die Erkennung im WLAN, bei der die Anwesenheit nur in (engen) Zyklen aktiv geprüft werden muss. Gleichzeitig werden Ressourcen in FHEM geschont. Die aktuelle Implementierung im iPhone 5S mit dediziert für das Tracking zuständigem Chip ist so gut, dass der Akku ebenfalls sehr geschont wird.

=== Modul in FHEM einrichten ===
Das Modul ist mit einer einfachen Definition sofort betriebsbereit:
:<code>define geofancy GEOFANCY geo</code>

Damit nimmt FHEM unter <nowiki>http://192.168.178.1:8083/fhem/geo</nowiki> entsprechende Meldungen des iPhones entgegen. Damit das nicht nur über das lokale WLAN funktioniert, bedarf es allerdings noch einiger zusätzlicher Maßnahmen. FHEM muss vom Internet erreichbar gemacht werden, dabei sollte unbedingt an die Absicherung des Zugriffs gedacht werden.

Zunächst einmal habe ich bei mir eine eigene FHEMWEB Instanz dafür angelegt:
<pre>
define WEBhook FHEMWEB 8088 global
attr WEBhook column Alarms: Apartment: Living: Bedroom: Kitchen: Sonos: Residents: Weather: Bathroom: Logs: Statistics: DashboardRoom: System: hidden: all:
attr WEBhook hiddenroom input,detail,save,Unsorted,Everything,CUL_HM,FS20,Commandref,style,Edit files,Select style,Logfile,Floorplans,Remote doc,FileLogs,Apartment,Bathroom,Bedroom,Kitchen,Living,Residents,System,Weather,Event monitor,NEW
attr WEBhook room hidden
attr WEBhook webname webhook
</pre>

Damit ist unter der URL <nowiki>http://192.168.178.1:8088/webhook/geo</nowiki> das GEOFANCY Modul erreichbar. Ich verstecke in dieser Ansicht noch alle Räume, die ich so habe. Wer die Raumnamen allerdings kennt, kann sie trotzdem aufrufen. Die Anzeige in den Räumen kann man mit dem Attribut column und entsprechend leeren Definitionen verstecken. Nun muss man explizit den Devicenamen kennen, um noch etwas über die Konfiguration in Erfahrung bringen zu können.
Auch wenn das Security-by-Obscurity ist - ich fühle mich wohler damit.

=== Webhook weiter absichern ===
Mit Hilfe eines allowed-Devices lässt sich die FHEMWEB Instanz noch weiter absichern indem nur die tatsächlich benötigten Kommandos erlaubt werden (in diesem Fall keine) und damit alle anderen nicht erlaubten (attr,define,get,set,...) automatisch nicht mehr zur Verfügung stehen:
<pre>
define allowedWEBhook allowed
attr allowedWEBhook allowedCommands ,
attr allowedWEBhook allowedDevices ,
attr allowedWEBhook validFor WEBhook
</pre>

Außerdem ist dringend zu empfehlen, den Zugriff über TLS/SSL und HTTP Basic-Authentication weiter abzusichern. Läuft FHEM auf einem Raspberry Pi, dann empfehle ich dazu die Konfiguration eines ReverseProxy (vorzugsweise HAproxy, Pound oder Varnish, notfalls auch Nginx oder Apache); damit ist man am flexibelsten und kann auch alle FHEMWEB Instanzen direkt über einen einzigen Port (meist 443, der HTTPS Standard Port) zusammenfassen. Ich möchte hier allerdings beschreiben, wie weit man mit FHEM Bordmitteln kommt und nehme das Beispiel einer Installation auf einer Fritzbox.

Wie TLS aktiviert wird, steht in der Commandref für [[FHEMWEB]]. Um die Kommandos auf der Fritzbox ausführen zu können, muss zuerst Telnet aktiviert werden (bitte Google benutzen). Anschließend wechselt man auf der Fritzbox ins Verzeichnis /var/media/ftp/fhem und kann dann den Hinweisen aus der [http://fhem.de/commandref.html#FHEMWEB Commandref] unter dem Punkt HTTPS folgen. Letztlich fehlt noch das entsprechende Attribut:

<pre>
attr WEBhook HTTPS
</pre>

Als nächstes aktivieren wir Benutzername+Passwort für den Zugriff. Die commandref für [[allowed]] gibt auch hier unter dem Punkt basicAuth entsprechende Hinweise. Wir fügen hier einfach mal einen Benutzer "webhook" mit dem Passwort "Geofancy" hinzu, das sieht dann so aus:

<pre>
attr allowedWEBhook basicAuth { "$user:$password" eq "webhook:Geofancy" }
</pre>

Weitere Infos zur Absicherung gibt auch [[FritzBox Webzugriff absichern]].

Um zu testen, ob unsere Absicherung erfolgreich war, kann man die URL <nowiki>https://192.168.178.1:8088/webhook/geo</nowiki> aufrufen (wichtig ist, dass man jetzt https und nicht mehr http eingibt; ansonsten bekommt man keine Antwort). Eine Zertifikatswarnung kann getrost ignoriert werden, verschlüsselt wird trotzdem. Es sollte auch eine Passwort Abfrage kommen und die Eingabe der entsprechenden Daten sollte dann zu einer entsprechenden Meldung vom GEOFANCY Modul führen:

<pre>
NOK No data received, see API information on http://wiki.geofancy.com
</pre>

Das ist ok, schließlich sind wir keine App, sondern der Mensch, der nur mal eben prüfen will :-)

=== Zugriff vom Internet ermöglichen ===
Das ist je nach Fritzbox und Software Version unterschiedlich. Grundsätzlich gilt: Eine Weiterleitung des ports 8088 vom Internet auf das laufende FHEM auf Port 8088 intern ist von AVM so nicht vorgesehen.
Bei mir führte folgendes zum Erfolg:

* Einloggen per Telnet auf der Fritzbox (ich habe FritzOS 6 installiert)
* Konfiguration editieren mittels "nvi /var/flash/ar7.cfg"
* Suchen nach richtiger Zeile durch Eingabe von "/internet_forwardrules" und Enter
* Hinzufügen einer weiteren Zeile (Vorsicht, die bestehende Zeile endet mit ; und das muss in , umgeändert werden, so dass das ; schließlich am Ende der Zeile steht.

So sieht es bei mir vorher aus:
:<code>internet_forwardrules = "tcp 0.0.0.0:488 0.0.0.0:488 0";</code>
Hinterher:
:<code>internet_forwardrules = "tcp 0.0.0.0:488 0.0.0.0:488 0", "tcp 0.0.0.0:8088 0.0.0.0:8088 0";</code>

Danach mittels ":x" abspeichern und sofort per "reboot" die Box neu starten, um diese Änderungen zu aktivieren. Das ist wichtig; ansonsten zeigt die Erfahrung, dass die Änderung nicht dauerhaft erhalten bleibt und die gerade gemachten Änderungen verloren gehen.

Wer die Einstellungen zu "internet_forwardrules" bei sich nicht finden kann, hat womöglich eine andere Version als ich oder ein leicht anderes Gerät und bemüht am besten Google, was er tun kann, um das Gleiche zu erreichen. Möglicherweise tauchen die Einträge auch erst auf, wenn man mal über das Webinterface ein Forwarding eingerichtet hatte.

Hat man einen DynDNS Dienst oder myFritz auf der Fritzbox aktiviert, so kann man jetzt auch von draußen auf den Webhook zugreifen. Das kann man prüfen, indem man das iPhone aus dem WLAN ausbucht und einmal die externe Adresse eingibt, also z.B. https://meindyndns.org:8088/webhook/geo.

=== Weitere Alternativen für den Zugriff aus dem Internet ===
Als Alternative zum Port Forwarding kann man sich auch per VPN in das lokale Netzwerk einwählen. iOS bietet dazu auch eine automatische Aktivierung des VPN (VPN on Demand), wie z.B. [http://forum.loxone.com/dede/netzwerk-firewall-and-security/8121-vpn-demand-ios-8-1-1-fritz-box-kleine-how.html hier] beschrieben wird.

Auch eine Alternative ist, das Portforwarding nicht direkt an FHEM einzurichten, sondern an einem im Netzwerk laufenden Reverse-Proxy, der dann seinerseits die Anfragen an FHEM weiterleitet. Dies kann z.B. Apache, Nginx oder am besten HAproxy sein.
Letzterer ist dabei sehr flexibel, allerdings nicht unbedingt einfach zu konfigurieren. Ein paar Inspirationen diesbezüglich gibt es z.B. [https://github.com/Hoanoho/HSE/tree/develop/lib/cfg/any/stat/etc/haproxy hier] und [https://github.com/Hoanoho/HSE/tree/develop/lib/cfg/any/dyn/etc/haproxy hier]. Wer pfSense nutzt, findet [http://loredo.me/post/116633549315/geeking-out-with-haproxy-on-pfsense-the-ultimate diesen Artikel] womöglich auch interessant. Er zeigt auch, dass mit HAproxy noch weit mehr möglich ist.
Der Reverse-Proxy sollte dabei auch unbedingt der TLS Termination Point sein (TLS Offloading). Nicht nur spart man sich dann die Aktivierung von TLS in FHEM, sondern man hat auch mehr Einfluss darauf, wie TLS arbeitet (z.B. Deaktivierung von SSLv3, forcieren von TLSv1.2, nur als sicher eingestufte Cipher Suite... siehe auch Infos auf der [https://wiki.mozilla.org/Security/Server_Side_TLS Mozilla Website]).

=== Einrichten in der Geof[e|a]ncy.app ===
Hat das alles soweit geklappt, können endlich in der Geofency.app bzw. Geofancy.app am iPhone die gewünschten Bereiche definiert werden. Am Besten zuvor in den Global Settings die folgenden Einstellungen hinterlegen:

* URL: https://meindyndns.org:8088/webhook/geo
* POST (oder GET, ist egal - das FHEM Modul kann beides)
* HTTP Basic Authentication: EIN (entsprechend Username und Password eintragen)

Anfänglich ist es empfehlenswert noch "Notification on success" und "Notification on Failure" einzuschalten. Ersteres kann man ausmachen wenn man weiß, dass es soweit funktioniert. Über "Send Test-Request" kann man einmal einen Test schicken und erhält das Ergebnis entsprechend dargestellt. Es sollte sowas kommen wie
:<code>POST Success: test OK</code>. In Geofancy.app gibt es keine Rückmeldung über den Erfolg des Testrequests. In FHEM sollten sich durch den Testrequest jedoch die Readings sofort aktualisieren (Ggf. ist ein Reload der FHEMWEB-Seite nötig da zusätzliche Tabellenzeilen nicht via Longpoll ergänzt werden).

Funktioniert das soweit, kann man eine neue Lokation als sein Zuhause anlegen. Es empfiehlt sich einen ID-Namen zu setzen; dieser ist dann in FHEM als Name für die Lokation sichtbar. Für die eigene Wohnung empfiehlt sich hier "home" (da dies auch direkt vom RESIDENTS Modul so verwendet werden kann). Man kann auch Trigger für andere Standorte anlegen. FHEM weiß dann sogar, wenn ihr im Büro seid und könnte sich dabei auch unterschiedlich verhalten, als wenn ihr "auf Achse" seid. Bei letzterem ist der Status im GEOFANCY Modul "underway", was so viel heißt wie "unbekannter Aufenthaltsort".

Hinweis: Zumindest für Geofancy.app liefert ein Testrequest wohl zufällige Locations zurück. Die eigenen Location-IDs werden also nicht übergeben, selbst wenn man sich in einem Geofence befindet. Um zu testen muss man sich wohl oder übel selbst bewegen ;-).

=== GEOFANCY Modul individualisieren ===
Die im GEOFANCY Modul dargestellten Readings sind nun in etwa so, wenn ihr euch bewegt:

<pre>
Readings:
2014-01-18 14:37:42 lastDevice -
2014-01-18 14:37:42 lastDeviceUUID 51F23894-AAAA-BBBB-CCCC-0123456789AB
2014-01-18 14:37:42 state dev:51F23894-AAAA-BBBB-CCCC-0123456789AB trig:test id:home lat:48.9999 long:11.9999
</pre>

Wer genauer hinschaut sieht: Mein iPhone heißt wohl 51F23894-AAAA-BBBB-CCCC-0123456789AB.
Damit nun die Readings für mein iPhone richtig angelegt werden, muss ein Device Alias gesetzt werden. Sinnvoll erscheint mir der Vorname des Besitzers:
:<code>attr geofancy devAlias 51F23894-AAAA-BBBB-CCCC-0123456789AB:Julian</code>

Weitere Alias-Namen können mit Leerzeichen einfach angehängt werden.
Jetzt werden weitere Readings angelegt, sobald GEOFANCY entsprechende Daten vom Mobilgerät empfängt:

<pre>
Readings:
2014-01-18 14:37:42 Julian arrived home
2014-01-18 14:37:42 currLocLat_Julian 48.9999
2014-01-18 14:37:42 currLocLong_Julian 11.9999
2014-01-18 14:37:42 currLocTime_Julian 2014-01-18 14:37:42
2014-01-18 14:37:42 currLoc_Julian home
2014-01-17 19:18:23 lastArr Julian home
2014-01-17 18:41:46 lastDep Julian Office
2014-01-18 14:37:42 lastDevice Julian
2014-01-18 14:37:42 lastDeviceUUID 51F23894-AAAA-BBBB-CCCC-0123456789AB
2014-01-17 18:41:46 lastLocArr_Julian 2014-01-17 08:58:37
2014-01-17 18:41:46 lastLocDep_Julian 2014-01-17 18:41:46
2014-01-17 18:41:46 lastLocLat_Julian 48.1111
2014-01-17 18:41:46 lastLocLong_Julian 11.1111
2014-01-17 18:41:46 lastLoc_Julian Office
2014-01-18 14:37:42 state dev:Julian trig:test id:home lat:48.9999 long:11.9999
</pre>

Möchte man nun etwas bestimmtes tun, wenn man nach Hause kommt oder das Heim verlässt, kann man am Besten ein entsprechendes Notify auf das Reading currLoc_Name setzen. Ich aktualisiere lediglich zwei Dummies, durch die dann alle weiteren Notifies ausgelöst werden:

<pre>
define n_Julian.Presence notify geofancy:currLoc_Julian:.home set Julian.homestatus:FILTER=STATE!=home home
attr n_Julian.Presence room Residents
define n_Julian.absence notify geofancy:currLoc_Julian:.underway {\
if (Value("Julian.homestatus") ne "gone") {\
fhem("set Julian.homestatus:FILTER=STATE!=absent absent");;\
}\
}
define n_Julian.whereabout notify geofancy:currLoc_Julian:.* set Julian.whereabout:FILTER=STATE!=$EVTPART1 $EVTPART1
</pre>

Wer es noch einfacher möchte (bzw. auch noch mehr Features) schaut sich einmal die neue Modulfamilie aus RESIDENTS[http://fhem.de/commandref_DE.html#RESIDENTS], ROOMMATE[http://fhem.de/commandref_DE.html#ROOMMATE] und GUEST[http://fhem.de/commandref_DE.html#GUEST] an. Diese sind direkt auf GEOFANCY abgestimmt. Dabei kann das devAlias Attribut entfallen und man hinterlegt die UUID stattdessen direkt im ROOMMATE oder GUEST Device (Attribut r*_geofenceUUIDs). Das erspart es für jeden Bewohner und jedes Device zig unterschiedliche Devices der Typen Notify, DOIF oder Watchdog anlegen und pflegen zu müssen.

Wer mehr Kontrolle möchte kann natürlich bei notify, DOIF und Co. bleiben: <code>define n_rr_Julian.location notify geofancy:currLoc_Julian:.* set rr_Julian:FILTER=location!=$EVTPART1 location $EVTPART1</code>. Wobei "Julian" dabei als devAlias in GEOFANCY eingtragen wurde, rr_Julian der Name des ROOMMATE aus RESIDENTS ist. Außerdem sind die Location-IDs in der Geofency.app bzw. Geofancy.app so gewählt wurde, dass diese direkt einem ROOMMATE-Status entsprechen (also z.B. home, wayhome...).

== Beispiele für die Nutzung der Anwesenheitserkennung ==
Hier sollen Beispiele für den Nutzen von Anwesenheitserkennung aufgezeigt werden.

=== Abschalten aller Verbraucher (Licht, Musikanlage) beim Verlassen der Wohnung ===
Typisches Szenario: Man geht ausser Haus, aber hat vergessen im Bad das Licht aus zu machen. Allerdings geht man heutzutage fast garnicht mehr ohne Handy aus dem Haus.

Nun soll FHEM in der gesamten Wohnung das Licht, sowie sonstige Verbraucher ausschalten, wenn ich länger als 15 Minuten ausser Haus bin. Dazu benötigt man zuerst eine structure, die alle Verbraucher und sonstigen Devices, die das betrifft, zusammenfasst.

<pre>
define Gesamte_Wohnung structure Gesamtes_Licht Licht_Wohnzimmer Licht_Kueche LED_Kueche Licht_Bad Licht_Schlafzimmer AV_Receiver TV_Steckdose
attr Gesamte_Wohnung room Wohnung
</pre>

Nun kann man mittels eines watchdogs eine Überwachung für sein Handy anlegen:

<pre>
# Überwachen der gesamten Wohnung mittels collectord sowie presenced in jedem Raum
define Handy PRESENCE lan-bluetooth XX:XX:XX:XX:XX:XX 127.0.0.1:5222
attr Handy event-on-change-reading state # Ein Event soll nur bei der Änderung des Anwesenheitsstatus (Reading: status) erfolgen. Wichtig für den watchdog!!!

# Nach 15 Minuten Abwesenheit (Handy im Status "absent") soll die gesamte Wohnung ausgeschaltet werden.
define watchdog_Anwesenheit watchdog Handy:absent 00:15 Handy:present set Gesamte_Wohnung off ; setstate watchdog_Anwesenheit defined
attr watchdog_Anwesenheit regexp1WontReactivate 1
</pre>

[[Kategorie:Code Snippets]]
[[Kategorie:Glossary]]