(FHEM) Attribute

Allgemeines

Diese Seite ist eine kommentierte Ausfuehrung der FHEM Referenz (commandref_DE.html), nachfolgend 'ORef' genannt.

Ausloeser fuer diese Seite war die Anpassung meiner RollladenIcons (KNX) und der damit verbundenen Notwendigkeit sich mit den Attributen eventMap, devStateIcon, devStateFormat, etc. auseinanderzusetzen.

Nun zum Thema

Alle Geräte haben/besitzen Attribute. (Anmerkung: Ausnahmen bestaetigen die Regel ;-))

Das Wort Attribut meint allgemein eine charakteristische Eigenschaft, oder ein Wesensmerkmal.

Eine Liste der gesetzten Attribute sieht man bei Nutzung von FHEMWEB in der "Device Overview" (Detailansicht eines Gerätes) im Abschnitt "Attributes" (roter Rahmen). Darüber befindet sich in dieser Darstellung (gelber Rahmen) ein Button "attr", eine Auswahlliste mit allen fuer dieses Geraet moeglichen/zulaessigen Attribute und ein Eingabefeld. Durch Druecken des Buttons "attr" wird das in der Liste ausgewaehlte Attribut auf den "Wert" des Eingabefeldes gesetzt.

Nebenbemerkung: Laesst man das Eingabefeld (faelschlicherweise) leer, so wird scheinbar standardmaeszig eine 1 (Defaultwert) angenommen. Hier die entsprechende Passage der ORef: value ist optional, und ist 1 falls nicht spezifiziert

Über die Console (telnet) lassen sich die Attribute mittels 'attr' setzen, mit 'displayattr' anzeigen und mit 'deleteattr' loeschen/entfernen.

attr [-a|-r|-silent] <devspec> <attrname> [<value>]

Dieser Befehl setzt ein Attribut für ein Gerät welches mit define oder defmod definiert wurde.

Syntax: Wie schon zu Beginn erwaehnt, wird sich bei der Syntax-Schreibweise scheinbar an der BNF orientiert (?). Ob die ORef hierbei beschreibungskonsitent ist, werde ich weiterhin pruefen.

Die Syntax-Schreibweise heiszt fuer "attr" uebersetzt im Einzelnen:

• Zu Beginn des Kommandos stehen die Buchstaben a t t r
• gefolgt von einem Leerzeichen
• evtl. gefolgt von einer der 3 moeglichen Optionen -a, -r, -silent
• gefolgt von einem Leerzeichen
• gefolgt von einem Geraetenamen
• gefolgt von einem Leerzeichen
• gefolgt von einem Attributnamen
• gefolgt von einem Leerzeichen
• und evtl. gefolgt von einem Wert

Die eckige Klammer [] bedeutet, dass der Inhalt beim Anwenden des Befehls weggelassen werden kann/darf. Der Hochstrich | (hier 2 Stueck) heiszt einfach nur 'oder' und bedeutet hier, dass einer der 3 Werte/Optionen auf den Befehl "attr" folgen darf, oder auch auch keiner (siehe Bedeutung eckige Klammern). Die spitzen Klammern <> kennzeichnen eine Variable. Eine Variable hat vollstaendigerweise neben dem Namen auch noch einen Typ und einen Wertebereich. Beides ist in dieser Definition nicht angegeben. Abgesehen davon gibt es idR auch Vorschriften zum Bilden von gueltigen Variablennamen. Aber der Reihe nach.

Fuer alle 3 folgenden Variablen "<devspec> <attrname> [<value>]" gilt allgemein:

Bei den zulaessigen Zeichen fuer einen Geretenamen (fuer Attributnamen muss ich noch suchen) schreibt das Einsteiger-PDF:

Gerätenamen dürfen neben Punkt und Unterstrich keine Sonderzeichen enthalten. 

Und jetzt geht's schon wieder los. In der ORef nix gefunden. (Wer hat was gefunden? -> Kommentar). Bei einer Suche ueber Google landet man im Forum. Grrrrrr! Wiederspruechliche Aussagen.

Invalid characters in name (not A-Za-z0-9.:_)

DoppelGrrrrr!

Allein im notify gilt Doppelpunkt als Trennzeichen und das kommt vom Meister selbst, daher verbietet es sich schon fast von selbst Doppelpunkt im Namen zu verwenden, auch wenn es (womöglich als Altlast) erlaubt ist.

Die lowerCamelCase-Notation der Attributnamen scheint nicht durchgaengig: z.B. listenonly, oldreadings, ...

Beispiele:

   attr global verbose 3
   attr lamp room kitchen
   attr lamp group lights
   attr lamp loglevel 6
   attr weatherstation event-on-update-reading wind,temperature,humidity
   attr weatherstation event-on-change-reading israining
   attr weatherstation event-on-change-reading israining,state
   attr heating stateFormat Temp:measured-temp, Valve:actuator
   attr -a TYPE=SVG room ,SvgRoom
   attr -r TYPE=SVG room ,SvgRoom

Hinweis: Sie können auch Ihre eigenen Attribute definieren, um sie in anderen Applikationen anzuwenden. Geben Sie "<attr <name> ?" ein, um eine Liste verfügbarer Attribute anzuzeigen. Siehe den Abschnitt über Geräte-Spezifikation für Details der <devspec>.

Gerätespezifische Attribute sind in der Beschreibung zum jeweiligen Gerät aufgeführt. Nach der Durchführung das globale Ereignis "ATTR" wird generiert. Falls die Option -a spezifiziert ist, dann wird value zum aktuellen Wert hinzugefügt. Achtung: falls value nicht mit einem Komma (,) anfängt, dann wird es mit einem Leerzeichen angehängt. Mit der -r Option kann man Teile eines Attributes wieder entfernen. Mit der silent Option wird der Befehl nicht in die "save -?" Liste eingetragen.

Globale Attribute

Diese Attribute besitzen alle Geräte (Devices).

alias

Wird in FHEMWEB benutzt, um ein en anderen Namen für ein Gerät anzuzeigen z.B. wenn Sonderzeichen/Leerzeichen nicht in der Gerätedefinition verwendet werden können.

comment

Fügt einen beliebigen Kommentar hinzu.

eventMap

Ersetze Event Namen und setze Argumente. Der Wert dieses Attributes besteht aus einer Liste von durch Leerzeichen getrennte Werten. Jeder Wert ist ein durch Doppelpunkt getrenntes Paar. Der erste Teil stellt den "alten" Wert, der zweite Teil den "neuen" Wert dar. Wenn der erste Wert ein Slash (/) oder ein Komma (,) ist, dann wird nicht durch Leerzeichen sondern durch das vorgestellte Zeichen getrennt. Optional kann man auch ein widgetOverride angeben (angehängt nach einem Doppelpunkt (z.Bsp. on-for-timer:OnFor:texField). Die Voreinstellung ist :noArg, um das Input Feld bei cmdList zu vermeiden. Beispiele:

   attr store eventMap on:open off:closed
   attr store eventMap /on-for-timer 10:open/off:closed/
   set store open 

Die explizite Variante dieses Attributes hat folgenden Syntax:

   attr store eventMap { dev=>{'on'=>'open'}, usr=>{'open'=>'on'} }
   attr store eventMap { dev=>{'^on(-for-timer)?(.*)'=>'open$2'}, usr=>{'^open(.*)'=>'on$1'}, fw=>{'^open(.*)'=>'open'} } 

Diese Variante muss dann verwendet werden, falls das Mapping nicht symmetrisch ist. Der erste Teil (dev) spezifiziert dabei die Richtung Gerät zu Benutzer, d.h. falls das Gerät on 100 oder on-for-timer 100 meldet, dann wird der Benutzer open 100 zu sehen bekommen. Der zweite Teil (usr) spezifiziert die Richtung Benutzer zu Gerät, d.h. wenn man "set XX open 100" eingibt, dann wird das Kommando "on 100" an das Gerät gesendet. In beiden Fällen wird der Schlüssel zuerst direkt, und dann als Regexp mit dem Wert verglichen. Falls man Regexps mit Wildcards im usr Teil verwendet, dann muss man den fw Teil mit dem exakt gleichen Schlüsseln ausfüllen, damit FHEMWEB in der Detail-Ansicht den set-Auswahl richtig anzeigen kann.

genericDisplayType

Wird von bestimmten Frontends (aber nicht FHEMWEB) verwendet, um für das Gerät passende Voreinstellungen (Bild/Befehle/etc) anzubieten. Z.Zt werden folgende Werte unterstützt: switch,outlet,light,blind,speaker,thermostat

group

Gerätegruppen. FHEMWEB zeigt Geräte die in die gleiche Gruppe gehören auch in einer gemeinsamen Box an. Ein Gerät kann zu mehr als einer Gruppe gehören. In diesem Fall müssen die entsprechenden Gruppen durch Kommata getrennt eingetragen werden. Wenn dieses Attribut nicht gesetzt ist, wird der in der Gerätegruppe gesetzte Gerätetyp verwendet.

room

Filtert/gruppiert Geräte. Ein Gerät kann zu mehr als einem Raum zugeordnet werden. In diesem Fall müssen die Raumzuordnungen durch Kommata getrennt angegeben werden. Geräte, die dem Raum mit der Bezeichnung "hidden" zugeordnet werden, erscheinen nicht auf der Webseite. Mit -> werden Räume strukturiert, z.Bsp. OG->Schlafzimmer

showtime

Wird im FHEMWEB verwendet, um die Zeit der letzten Aktivität anstelle des Status in der Gesamtansicht anzuzeigen. Nützlich z.B. für FS20 PIRI Geräte.

suppressReading

Wird verwendet, um nicht gewollte Readings zu entfernen. Der Wert ist ein Regular Expression, ergänzt mit ^ und $. Wird nur in Ausnahmefällen benötigt.

verbose

Setzt den Schwellwert für die Logfile-Meldungen. Mögliche Werte sind:

   0 - Server start/stop
   1 - Fehlermeldungen oder unbekannte Pakete
   2 - bedeutende Ereigbisse/Alarme.
   3 - ausgesendete Kommandos werden gelogged.
   4 - von den einzelnen Geräten empfangene Daten.
   5 - Fehlersuche.

Der für die global Instanz gesetzte Wert gilt als Voreinstellung für die Instanzen, die dieses Attribut nicht gesetzt haben.

Lokale Attribute

Diese Attribute besitzen nur ganz bestimmte Geraeteklassen.

Eigene Attribute

Manche Geräte (wie FHEMWEB) definieren automatisch neue globale Attribute bei der ersten Definition eines Gerätes dieses Typs.

Sie können den Befehl

attr global userattr <attributelist>

für das Gerät global verwenden, um neue globale Attribute zu deklarieren, und

attr <devicespec> userattr <attributelist>,

um neue lokale Attribute für bestimmte individuelle Geräte gemäß devspec zu deklarieren. <attributelist> ist eine durch Leerzeichen getrennte Liste, die die Namen der zusätzlichen Attribute enthält. In der Dokumentation zum Befehl attr sind Beispiele.

Seien Sie vorsichtig und überschreiben Sie keine zusätzlichen globale Attribute, die bereits zuvor durch Sie selbst oder ein Gerät definiert wurden. attr global userattr <attributelist> sollte so früh wie möglich in der Konfiguration erscheinen.