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.

Hinweis: <devspec> gestattet auch die Moeglichkeit ein Geraet, oder eine Gruppe von Geraten gleichen Typs mit einem Attribut zu versehen. Siehe Beispiel 9 und 10 weiter unten. Dort wird TYPE=SVG als <devspec> angegeben und bezieht sich somit auf alle Geraete die diesem Type angehoeren. Ob das auch mit anderen Internals funktioniert habe ich noch nicht ausprobiert.

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.

Der Vollstaendigkeit halber hier noch die Optionen:

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.

Was um Gottes Willen ist eine "save -?" Liste. Als Kommando erhaelt man

Unknown command safe, try help.

Ich vermute damit hat jemand den "Save config ?" Button/Link direkt unterhalb des FHEM-Logos im FHEM-Web gemeint und wollte damit zum Ausdruck bringen, dass bei Nutzung der -silent Option von attr diese Aenderung nicht beim naechsten Aktiviren von "Save config ?" in die Config uebernommen wird (???).

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, ...

Der optionale Value [<value>] eines Attributes wird idR in der ORef angegeben.

Beispiele aus der ORef:

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

zu 1) Das Attribut <attrname>='verbose' des Geraetes mit dem Namen <devspec>='global' wird auf den Wert <value>='3' gesetzt. verbose (globales Attribut;Wertebereich) 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.

Hinweis: Falls FHEM mit der -d Koommandozeilenoption gestartet wurde (perl fhem.pl -d fhem.cfg), dann wird verbose auf 5 gesetzt und die Logs werden auf STDOUT geschrieben.

zu 2) Das Attribut <attrname>='room' des Geraetes mit dem Namen <devspec>='lamp' wird auf den Wert <value>= 'kitchen' gesetzt.

zu 3|4) dito

zu 5|6|7) Das Attribut <attrname>='event-on-update-reading', bzw. 'event-on-change-reading' des Geraetes mit dem Namen <devspec>='weatherstation' wird auf den/die Wert(e) <value>='wind,temperature,humidity', oder 'israining', oder 'israining,state' gesetzt.

ORef:

event-on-update-reading Wenn nicht gesetzt, erzeugt jede Veränderung eines "readings" ein Ereignis, welches z.B. von notify oder FileLog berücksichtigt wird. Wenn gesetzt erzeugen nur Aktualisierungen der eingetragenen "readings" ein Ereignis.

event-on-change-reading Dieses Attribut enthält eine durch Kommata getrennte Liste von "readings". Wenn gesetzt, erzeugen nur Veränderungen der gelisteten "readings" ein Ereignis. Wenn die aktualiserten Werte der gelisteten "readings" identisch sind, wird kein Ereignis generiert. Wenn hinter dem Namen eines "readings" eine :Schwelle angegeben ist, wird das Event nur getriggert wenn die Änderung grösser als diese Schwelle ist. Die unterschiedlichen Bedeutungen von event-on-update-reading und event-on-change-reading sind folgende:

   Wenn beide Attribute nicht gesetzt sind erzeugt jede Aktualisierung eines jeden "readings" eines Gerätes ein Ereignis.
   Wenn eines der Attribute gesetzt ist, erzeugen nur Updates oder änderungen von "readings" die in einem der Attribute gesetzt sind ein Ereignis.
   Wenn ein "reading" in event-on-update-reading aufgeführt ist, erzeugt eine Aktualisierung ein Ereignis unabhängig ob das "reading" auch in event-on-change-reading aufgelistet ist.

zu 8) Das Attribut <attrname>='stateFormat' des Geraetes mit dem Namen <devspec>='heating' wird auf den Wert <value>= 'Temp:measured-temp, Valve:actuator' gesetzt.

ORef:

stateFormat Ändert den Gerätestatus, dies ist z.Bsp. in der Ausgabe des list Kommandos zu sehen, oder in der Raumübersicht von FHEMWEB. Falls nicht gesetzt, dann wird das state Reading übernommen. Sonst werden alle Wörter im Wert des Attributes durch das entsprechende Reading des Gerätes ersetzt (soweit vorhanden). Falls der Wert in {} eingeschlossen ist, dann wird es als Perl Ausdruck ausgewertet. Die Auswertung passiert bei jeder Änderung eines Readings. Die hier beschriebene "set magic" wird auch angewendet.

Das ist leider ein Beispiel fuer solche "KreuzundQuerSaetze". Besser vielleicht: Das stateFormat-Attribut erlaubt eine fuer den Nutzer besser lesbare Anzeige des STATE eines Geraetes. Alle Werte-Paare neuerStateName:readingStateName sind durch Komma getrennt.

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.

Attribute

Wenn man in FHEMWEB eine spezifische Attributliste als Dropdown-Liste oeffnet findet man etwas abweichende Attributbezeichnngen: Diese sind gegliedert in:

device-spezifische Attribute
FHEMWEB
framework
global userattr

In 'framework' findet man z. B. alias, comment, .... womit eigentlich die globalen Attribute gemeint sind.

Globale Attribute

Diese Attribute besitzen alle Geräte (Devices).

Mit

list global

erhaelt man folgende Ausgabe:

Internals:
  DEF        no definition
  FD         3
  NAME       global
  NR         1
  STATE      no definition
  TYPE       Global
  currentlogfile /var/log/fhem/fhem-2023-09.log
  eventCount 1
  logfile    /var/log/fhem/fhem-%Y-%m.log

Attributes:

  alias      global
  autoload_undefined_devices 1
  autosave   0
  configfile /fhem_cfg/fhem.conf
  logfile    /var/log/fhem/fhem-%Y-%m.log
  modpath    /opt/fhem
  motd       SecurityCheck:
 WEB is not password protected
 WEBtablet is not password protected
 MQTT is not password protected
 WEBphone is not password protected
 telnetPort is not password protected

Protect this FHEM installation by defining an allowed device with define allowed allowed
You can disable this message with attr global motd none

  statefile  /var/log/fhem/fhem.save
  updateInBackground 1
  userattr   DbLogExclude DbLogInclude DbLogValueFn:textField-long alias_UGVD cmdIcon devStateIcon devStateIcon:textField-long devStateStyle dummy fp_EG fp_FP icon sortby webCmd webCmdLabel:textField-long widgetOverride yaf_1 yaf_2
  verbose    5
  version    fhem.pl:27055/2023-01-14

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 getrennten 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:textField). 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.

Gerätespezifische Attribute

FHEMWEB

cmdIcon
devStateIcon
devStateStyle
icon
sortby
webCmd
webCmdLabel
widgetOverride

cmdIcon

devStateIcon

Nach dem Update von 6.0 auf 6.2 und dem Wechsel vom TUL auf knxd funktierten meine Icons der Rollladensteuerung nicht mehr. Anstelle der Rollladen-Icons (Shutter) waren die default on/off-Lampen-Icons zu sehen.

devStateIcon 0:fts_shutter_0 3:fts_shutter_100 2:fts_shutter 1:fts_shutter_updown

eventMap /on g3:Stop/off g2:Auf/on g2:Ab

Die Defintion der KNX-Devices wie folgt

DEF 2/4/2:dpt1.008 2/0/10:dpt1.008 2/1/10:dpt1.008

KNX Gruppenadressen main/middle/sub:

2/4/2 Fahrt
2/0/10 Auf/Ab
2/1/10 Halt

Datentyp:

Switch EIS 1 DPT 1.yyy Schalten [0] = Aus | UNWAHR / [1] = Ein | WAHR 1 Bit 1-bit

1.008 DPT_UpDown 1 bit Boolean 0 = up, 1 = down

devStateStyle

icon

sortby

webCmd

webCmdLabel

widgetOverride

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.

Die automatische Aktualisierung der Kommentare aktivieren.

(FHEM) Attribute

Inhaltsverzeichnis