FHEMWiki - Benutzerbeiträge [de]

DOIF/uiTable Schnelleinstieg

2026-04-07T16:27:40Z

Ansgru: /* Die Tabellendefinition */

[[Datei:UiTable state state.jpg|950x950px|rechts|Webansicht bestehend aus mehreren DOIF/uiTable-Definitionen]]
An dieser Stelle wird das DOIF-Web-Interface erklärt, welches über das DOIF-Attribut '''uiTable''' realisiert wurde.

Abhängig von der Art der Funktion können in einer tabellarischen Darstellung FHEM-Geräte visualisiert und über die Web-Oberfläche bedient werden. Eventbasierte Änderungen visualisierter Readings werden unmittelbar in der Web-Ansicht aktualisiert. Eine erstellte Tabelle erscheint unterhalb der Statuszeile eines DOIF-Devices. Das uiTable-Attribut kann in bereits bestehenden DOIFs oder in funktionslosen DOIFs, wie in den unteren Beispielen, als reines WEB-Interface erstellt werden. In der obigen Abbildung ist ein Statusbildschirm aus mehreren Spalten mit mehreren DOIF/uiTable-Definitionen aufgebaut worden.<br>

Die Darstellungsmöglichkeiten werden anhand von Beispielen insb. mit Hilfe bereits im DOIF-Modul vordefinierter uiTable-Funktionen aufgezeigt. Diese Perlfunktionen sind in einem eigenen Package namens 'ui_Table' definiert worden. Mit Hilfe dieser Funktionen lassen sich recht einfach, ohne tiefere HTML/CSS-Kenntnisse, eigene Übersichten definieren. Im Anschluss werden typische '''[[DOIF/uiTable Schnelleinstieg#Anwendungsbeispiele|Anwendungsbeispiele]]''' aufgezeigt.

Die folgenden Beispieldefinitionen arbeiten mit konkreten Geräten und Readings, sie können als RAW-Definition [https://wiki.fhem.de/wiki/Import_von_Code_Snippets] ins eigene System übernommen werden, dazu müssen die Gerätenamen, Readings, ggf. auch Icons den existierenden Namen des eigenen Systems angepasst werden. Zum Ausprobieren der Beispiele können statt echter Geräte auch Dummys benutzt werden.

Es gibt ebenfalls das Attribut '''uiState''', welches die gleiche Syntax wie uiTable nutzt. Die definierte Tabelle erscheint im Gegensatz zu uiTable jedoch im Status des DOIF-Devices. uiState und uiTable können gleichzeitig in einem DOIF-Device definiert werden.

== Aufbau des uiTable-Attributs ==
Im uiTable-Attribut wird in erster Linie die zu visualisierende Tabelle definiert. Optional können zuvor ein Perlblock sowie Templates definiert werden.
{{Randnotiz|RNText='''Aufbau des Attributs'''
* das uiTable-Attribut besteht aus drei Bereichen:
* [[DOIF/uiTable Schnelleinstieg#Der Perlblock|Perlblock]]
* [[DOIF/uiTable Schnelleinstieg#uiTable-Templates|Templates-Definitionen]]
* [[DOIF/uiTable Schnelleinstieg#Die Tabellendefinition|Tabellendefinition]]
}}
'''Aufbaustruktur'''
<syntaxhighlight lang="perl">
{
<Perlblock, optional>
}

<Templates-Definitionen, optional>

<Tabellendefinition>
</syntaxhighlight>
=== Der Perlblock ===
Der Perlblock dient dazu, das Layout der Tabelle zu beeinflussen sowie eigene uiTable-Funktionen zu definieren. Hier wird insb. das Package definiert, welches für die Tabellendefinition gilt. Ebenfalls können CSS-Variablen sowie Steuerungsattribute gesetzt werden. Der Perlblock beginnt und endet mit einer geschweiften Klammer.

==== CSS-Variablen und Steuerungsattribute ====
Mit Hilfe von CSS-Variablen kann das Layout der Tabelle beeinflusst werden. Die Steuerungsattribute beeinflussen die Statuszeile sowie die Detailansicht des DOIF-Moduls.
{{Randnotiz|RNText='''CSS-Variablen und Steuerungsattribute'''
*Das Layout der gesamten Tabelle wird beeinflusst über die Variablendefinition: '''$TABLE="<CSS-Attribute der Tabelle>"'''
*Spaltenformatierungen werden beeinflusst mit Hilfe der Variablendefinition: '''$TC{<Zellenbereich für Spalten>}="<CSS-Attribute der Spalten>"'''
*Zeilenformatierungen werden beeinflusst mit Hilfe der Variablendefinition: '''$TR{Zeilenbereich}="<CSS-Attribute der Zeilen>"'''
*einzelne Zellen werden beeinflusst mit Hilfe der Variablen: '''$TD{<Zellenbereich für Zeilen>}{<Zellenbereich für Spalten>}="<CSS-Attribute der Zellen>"'''
*für Zellen-, Spalten- und Zeilen-Bereich gilt: '''<Zahl><nowiki>|</nowiki><kommagetrennte Aufzählung><nowiki>|</nowiki><Bereich von..bis>'''
*Der Status in der Statuszeile des DOIFs wird ausgeblendet mit '''$SHOWNOSTATE=1'''
*Die Gerätezeile des DOIFs wird ausgeblendet mit '''$SHOWNODEVICELINE = "<regex room>"'''
*Die Tabelle des DOIFs wird ausgeblendet mit '''$SHOWNOUITABLE = "<regex room>"'''
*Die Detailansicht wird umorganisiert mit '''$ATTRIBUTESFIRST=1'''
}}
'''Bespieldefinition'''
<syntaxhighlight lang="perl">
defmod di_bsp_layout DOIF ##
attr di_bsp_layout uiTable { ## Beginn des Perlblocks\
## CSS-Variablen\
\
## Die Tabelle soll ein Hintergrundbild der Größe 300x300 Pixel haben\
$TABLE = "width:300px;; height:300px;; background-image:url(/fhem/www/pgm2/images/Grundriss.png);; background-size: 300px 300px;;";;\
\
## die Zelle der ersten Zeile und der ersten Spalte soll rechts eine Rahmenlinie haben\
$TD{0}{0} = "style='border-right-style:solid;; border-right-width:10px'";;\
\
## Die erste Zeile soll aus der Klasse 'odd' sein und fett-Schrift haben\
$TR{0} = "class='odd' style='font-weight:bold'";;\
\
## die Spalten 2 bis 6 sollen zentriert sein\
$TC{1..5} = "align='center'";;\
\
## die Spalten 2, 4 und 5 sollen zentriert sein\
$TC{1,3,5} = "align='center'";;\
\
## die letzte Spalte der Tabelle soll fett sein\
$TC{last} = "style='font-weight:bold'";;\
\
\## Steuerungsattribute\
\
\## Ausblenden des Status in der Statuszeile\
$SHOWNOSTATE=1;;\
\
## Die Gerätezeile wird ausgeblendet in allen Räumen\
$SHOWNODEVICELINE = '.*';;\
\
## Die Tabelle wird im Raum info ausgeblendet\
$SHOWNOUITABLE = '^info$';;\
\
## Die Detailansicht wird umorganisiert, hilfreich beim Editieren längerer uiTable-Definitionen\
$ATTRIBUTESFIRST = 1;;\
} ## Ende des Perlblocks
</syntaxhighlight>

=== Die Tabellendefinition ===
==== Einfache Tabellendefinition ohne Funktionen ====
{{Randnotiz|RNText='''Tabellendefinition'''
* eine Tabelle wird aus Zellen zusammengebaut
* mehrere Zellen werden mit <nowiki>|</nowiki> von einander getrennt, sie bilden eine Tabellenzeile
* eine neue Tabellenzeile beginnt mit einer neuen Zeile in der Tabellendefinition
* eine Tabellenzeile kann auch in mehreren Zeilen definiert werden, diese müssen dann mit <nowiki>|</nowiki> enden
* Texte werden in Anführungszeichen angegeben
* Text kann mit Befehlen etc. durch einen Punkt verknüpft werden
* Readings werden in der Form [<device>:<reading>] angegeben
* Kommentare beginnen mit ## und enden mit Zeilenende
* Events eines definierten Readings, führen sofort zu Aktualisierung seines Inhalts in der visualisierten Tabelle
}}
'''<big>Beispieldefinition</big>'''
<syntaxhighlight lang="perl">
defmod ui_Table_definition DOIF ##
attr ui_Table_definition uiTable { ## Perlblock für globale Tabellendefinitionen\
\
$TC{1..2}="align='center'" ## zentrierte Ausrichtung der zweiten und dritten Spalte\
\
}\
\
## Tabellendefinition\
\
"Warmwasser"|"Vorlauf"|"Rücklauf" ## erste Tabellenzeile\
## zweite Tabellenzeile\
[T_Warmwasserspeicher:temperature]| ## Zeile wird fortgesetzt, da sie mit | endet\
[T_Vorlauf:temperature]| ## Zeile wird fortgesetzt, da sie mit | endet\
[T_Ruecklauf:temperature]
</syntaxhighlight>

''Ergebnis der Beispieldefinition in der Webansicht:''
[[Datei:UiTable Definition.png|mini|ohne]]

==== Tabellendefinition mit Berechnungen ====
{{Randnotiz|RNText='''Zellenauswertung'''
* jede Zelle der Tabelle wird über Perl ausgewertet
* Readingangaben der Form [<device>:<reading>] werden in eine Perlfunktion übersetzt
* das Ergebnis des ausgewerteten Perlausdrucks wird ausgegeben
* in einer Zelle können beliebige Perlfunktionen genutzt werden
* Texte oder Funktionen können mit Punkt aneinander gehängt werden
* mit Komma werden Texte oder Werte untereinander dargestellt
* wird eine Zeile mit < abgeschlossen, so wird die aktuelle Tabelle abgeschlossen, die nächste Zeile beginnt in einer neuen Tabelle
* in einer Berechnung sollte ein Trigger in Form einer Readingangabe [<device>:<reading>] vorkommen, sonst wäre das Ergebnis statisch und würde sich nicht ändern
}}
'''<big>Beispieldefinition</big>'''
<syntaxhighlight lang="perl">
defmod di_uiTable_calc DOIF ##
attr di_uiTable_calc uiTable ## Tabellendefinition\
"Differenz"|[T_Ruecklauf:temperature]-[T_Vorlauf:temperature]\
"Minimum"|minNum([TH_WZ_HM:measured-temp],[TH_Keller_HM:measured-temp])\
"Durchschnitt"|([T_Ruecklauf:temperature]+[T_Vorlauf:temperature])/2
</syntaxhighlight>

''Ergebnis der Beispieldefinition in der Webansicht:''
[[Datei:UiTable calc.png|mini|ohne]]

== Vordefinierte uiTable-Funktionen ==
Typische Widgets bzw. Styles wurden als Perl-Funktionen im package ui_Table für eine einfache Tabellendefinition programmiert. Im folgenden wird näher auf die einzelnen uiTable-Funktionen eingegangen.

=== FHEM-Widgets mit der Funktion '''widget''' ===
Alle in FHEM vorhanden Widgets können mit Hilfe der Perlfunktion '''widget''' genutzt werden. Bei häufiger Nutzung eines bestimmten Widgets bietet sich alternativ die Definition einer uiTable-Funktion (Typ 3) mit dem jeweiligen Widget an, siehe: [[DOIF/uiTable Schnelleinstieg#Eigene uiTable-Funktionen programmieren|uiTable-Funktion]]
{{Randnotiz|RNText=Funktion '''widget'''
<syntaxhighlight lang="perl">
widget(<Reading>,$fhem_widget,$set)

Reading # [<device>:<reading>]
$fhem_widget # Angabe des FHEM-Widgets
$set # optional, undef zum Setzen beliebiger Readings (entspricht setreading), "set" wenn das Reading per set-Befehl gesetzt wird (siehe Attribut ReadingList), "set <Befehl>", wenn sich der Befehl vom Reading unterscheidet, default undef
</syntaxhighlight>

'''nützliche Links'''
* [[FHEMWEB/Widgets|Fhem-Widgets]]
* Fhem-Widgets als [[DOIF/uiTable Schnelleinstieg#Eigene uiTable-Funktionen programmieren|uiTable-Funktion]]
}}
'''<big>Beispieldefinition</big>'''
<syntaxhighlight lang="perl">
defmod di_uiTable_widget DOIF ##
attr di_uiTable_widget uiTable ## FHEM-Widgets mit Hilfe der WID-Funktion\
{package ui_Table}\
"Widget"\
"Select"| widget([uhr:wochentag],"select,Montag,Dienstag,Mittwoch,Donnerstag,Freitag,Samstag,Sonntag")\
"Selectnumbers"| widget([motor:spannung],"selectnumbers,0,0.5,12,1,lin")\
"Slider"| widget([bla:wert],"slider,0,5,100,1")\
"Colorpicker RGB"| widget([Lampe:farbe],"colorpicker,RGB")\
"Colorpicker HSV"| widget([Lampe:farbe],"colorpicker,HSV")\
"Colorpicker CT"| widget([Lampe:waerme],"colorpicker,CT,2000,10,6500")\
"Colorpicker HUE"| widget([Lampe:farbe],"colorpicker,HUE,0,1,359")\
"Colorpicker BRI"| widget([Lampe:helligkeit],"colorpicker,BRI,0,1,100")\
"Time"| widget([start:zeit],"time")\
</syntaxhighlight>
''Ergebnis der Beispieldefinition in der Webansicht:''
[[Datei:UiTable WID.png|mini|ohne]]

=== SVG-uiTable-Funktionen ===
SVG-uiTable-Funktionen sind skalierbare Widgets, die auf SVG-Elementen basieren. Diese Funktionen befinden sich im Namensraum '''ui_Table''', daher muss vor deren Nutzung der Namensraum im Perlblock mit '''package ui_Table''' festgelegt werden (siehe Beispiele unten). Funktionen aus dem Namensraum '''main''' - das ist der Standard-Namensraum in FHEM - müssen in diesem Fall mit vorangestelltem Namensraum angegeben werden: '''main::<perlfunction>''' oder kürzer '''::<perlfunction>'''.

==== '''ring'''-Funktionen ====
===== Farbskalierte Temperaturanzeige mit Hilfe der SVG-Funktionen '''temp_ring/temp_mring''' =====
Die Farbe der dargestellten Temperatur ist abhängig vom Temperaturwert. Die Helligkeit der Farbgebung ist einstellbar. Bei der '''temp_mring'''-SVG-Funktion wird der Ring einfarbig dargestellt.

Farbskalierung der '''temp_ring'''-SVG-Funktion:
[[Datei:Farbskalierung temp_ring_scaling.png|600px|ohne]]

Farbskalierung der '''temp_mring'''-SVG-Funktion:
[[Datei:Farbskalierung temp_mring_scaling.png|600px|ohne]]

{{Randnotiz|RNText=SVG-uiTable-Funktion '''temp_ring/temp_mring'''
<syntaxhighlight lang="perl">
temp_ring/temp_mring ($temp_value,$temp_min,$temp_max,$sizeHalf, $lightring,$lightnumber,$decFont)

$temp_value # Temperatur
$temp_min, # minimale Temperatur, optional, default=-20
$temp_max, # maximale Temperatur, optional, default=60
$sizeHalf # "<size>,<half ring>" size: Größe der Grafik, optional, default = 80, half ring: 1 für Halbring
$lightring, # Helligkeit des Ringes (0-100), optional, default=50
$lightnumber # Helligkeit der Zahl (0-100), optional, default=50
$decFont # "<Anzahl der Nachkommastellen>,<Schrift-SVG-Attribute Wert>,<Schrift-SVG-Attribute Einheit>", optional
</syntaxhighlight>
}}
'''<big>Beispieldefinition</big>'''
<syntaxhighlight lang="perl">
defmod di_temp_ring DOIF ##
attr di_temp_ring uiTable {package ui_Table}\
"außen (standard)"|temp_ring([Aussensensor:temperature])\
"Warmwasser (größer,aufgehellt,Normalschrift)" |temp_mring([vaillant:WWSpeicher],15,70,110,90,100,"1,font-weight:normal")\
"Vorlauf (größer)"| temp_mring([ESPEasy_ESP_Temp_Vorlauf:Temperature],15,45,100)
</syntaxhighlight>
''Ergebnis der Beispieldefinition in der Webansicht:''
[[Datei:temp_ring_bsp.png|ohne|mini]]

===== Farbskalierte Feuchtigkeitsanzeige mit Hilfe der SVG-Funktionen '''hum_ring/hum_mring''' =====
Die Farbe der dargestellten Feuchtigkeit ist abhängig vom Feuchtigkeitswert. Die Helligkeit der Farbgebung ist einstellbar. Bei der '''hum_mring'''-SVG-Funktion wird der Ring einfarbig dargestellt.

Farbskalierung der '''hum_ring'''-SVG-Funktion:
[[Datei:Farbskalierung hum_ring_scaling.png|600px|ohne]]

Farbskalierung der '''hum_mring'''-SVG-Funktion:
[[Datei:Farbskalierung hum_mring_scaling.png|600px|ohne]]

{{Randnotiz|RNText=SVG-uiTable-Funktion '''hum_ring/hum_mring'''
<syntaxhighlight lang="perl">
hum_ring/hum_mring ($hum_value,$sizeHalf,$lightring,$lightnumber,$decFont)
$hum_value # Feuchtigkeit
$sizeHalf # "<size>,<half ring>" size: Größe der Grafik, optional, default = 80, half ring: 1 für Halbring
$lightring # Helligkeit des Ringes (0-100), optional, default=50
$lightnumber # Helligkeit der Zahl (0-100), optional, default=50
$decFont # "<Anzahl der Nachkommastellen>,<Schrift-SVG-Attribute Wert>,<Schrift-SVG-Attribute Einheit>", optional
</syntaxhighlight>
}}
'''<big>Beispieldefinition</big>'''
<syntaxhighlight lang="perl">
defmod di_hum_ring DOIF ##
attr di_hum_ring room test2
attr di_hum_ring uiTable {package ui_Table}\
"klein ohne Farbverlauf"|hum_mring([Aussensensor:humidity],60)\
"normal groß mit Farbverlauf"|hum_ring([Aussensensor:humidity])\
"groß ohne Farbverlauf aufgehellt"|hum_mring([Aussensensor:humidity],100,80)
</syntaxhighlight>
''Ergebnis der Beispieldefinition in der Webansicht:''
[[Datei:hum_ring_bsp.png|ohne|mini]]

===== Farbskalierte Anzeige eines Zahlenwertes mit Hilfe der universellen SVG-Funktion '''ring''' =====
Die Farbe des dargestellten Wertes kann abhängig vom Wert bestimmt werden. Dabei wird die Farbe mit Anleihen aus dem [https://de.wikipedia.org/wiki/HSV-Farbraum HSV-Farbraum] bestimmt. Dieser Farbraum benötigt eigentlich drei Werte, wobei die erste den Farbton (hue) bestimmt; hier wird nur dieser Wert verwendet (Sättigung und Hellwert sind nicht einstellbar). Der Farbton geht von rot (hue-Wert = 0) über gelb (hue-Wert = 60), dann grün (hue-Wert = 120) und blau (hue-Wert = 240) zurück zu rot (hue-Wert = 360), siehe dazu auch die [https://de.wikipedia.org/wiki/HSV-Farbraum#/media/Datei:HueScale.svg Farbtontafel] auf der Wikipedia-Seite.
Die unten $colorRef genannte Funktion kann zum Beispiel in der Tabelle selbst definiert werden, beispielsweise kann man in dem device &onoff_hue verwenden, wenn man es vorab definiert (siehe [https://forum.fhem.de/index.php/topic,120088.msg1204341.html#msg1204341 Link zum Forum]):<blockquote><syntaxhighlight lang="perl">
attr <ui device Name> {
package ui_Table;
sub onoff_hue {
my($irgendeinVariablenname)=@_;
return ($irgendeinVariablenname == 0 ? 240 : 0);
}
## Tabellendefinition
...
}
</syntaxhighlight></blockquote>{{Randnotiz|RNText=SVG-uiTable-Funktion '''ring'''
<syntaxhighlight lang="perl">
ring ($value,$min,$max,$minColor,$maxColor,$desc, $sizeHalf,$colorRef,$decFontUnit,$model,$lightness)

$value # darzustellender Wert
$min # minimaler Wert, optional, default=0
$max # maximaler Wert, optional, default=100
$minColor # Farbe (hue: 0-360) des kleinsten Wertes, optional, default = undef
$maxColor # Farbe (hue: 0-360) des maximalen Wertes, optional, default = undef
$desc # Beschreibung des Wertes, optional, default = undef
$sizeHalf # "<size>,<half ring>" size: Größe der Grafik, optional, default = 100, half ring: 1 für Halbring
$colorRef # Referenz auf eine Funktion, die zu einem Wert einen Farbwert (hue: 0-360) bestimmt, oder eine Referenz auf eine Arrayliste mit Grenzwerten und Farben, optional, default = undef
$decFontUnit # "<Anzahl der Nachkommastellen>,<Schrift-SVG-Attribute Wert>,<Schrift-SVG-Attribute Einheit>,<Einheit hinter dem Zahlenwert>", optional
$model # '<color gradient>,<min/max>,<inner ring>,<pointer>,<mode>'
# <color gradient>: "gradient" (undef),"nogradient" (1)
# <min/max>: Style-SVG-Attribute oder "nominmaxvalue" (undef), "minmaxvalue" (1)
# <inner ring>: Style-SVG-Attribute oder "innerring" (1), "noinnerring" (undef)
# <pointer>: Breite des Zeigers in Pixel, "nopointer" (undef)
# <mode>: "minmax" (undef), "negzeropos" (1), "zeronegpos" (2)
# alle Parameter sind optional, default keine Angaben: ',,,,,,'
$lightness # Helligkeit einzelner Elemente (0-100) "<ring>,<inner ring>,<minMax>,<unit>,<value>", optional, default: "50,50,50,40,50"
</syntaxhighlight>
Wird '''$colorFunc''' nicht angegeben, so wird der Farbwert zwischen '''$minColor''' und '''$maxColor''' linear interpoliert
}}

'''<big>Beispieldefinition</big>'''
<syntaxhighlight lang="perl">
defmod di_ring DOIF (1)
attr di_ring room test20,test5
attr di_ring uiTable {package ui_Table;; \
$SHOWNOSTATE=1}\
## von 0 bis 20 in Farben von grün (hue:120) bis rot (hue:0)\
"Umlaufmenge"|ring([heating:pump],0,20,120,0,"l/min",100)\
\
## von 0 bis 3 in Farben von rot (hue:0) bis türkis (hue:180), eine Nachkommastelle, Schriftgröße 170%\
## Innenring mit Min-, Max-Beschriftung\
"Wasserdruck"|ring([heating:pressure],0,3,0,180,"bar",100,undef,"1,font-size:170%,fill:silver;;font-size:50%","0,1,1")\
\
## Temperaturdarstellung, entspricht dem Funktionsaufruf:\
## temp_ring ([outdoor:temperature],-20,60,100,"1,font-weight:normal;;font-size:140%")\
## Eine Nachkommastelle, Normalschrift, Schriftgröße 140%\
"Temperatur"|ring([outdoor:temperature,-20,60,undef,undef,"°C",100,\&temp_hue,"1,font-weight:normal;;font-size:140%")\
\
## Lufdruck als Halbring\
"Luftdruck"|ring([weather:barometer],970,1045,30,90,"hPa","100,1",undef,0)\
\
## Co2 als Halbring, Farbgebung als Array mit drei Bereichen, Innenring mit Zeiger\
"Co2"|ring([livingroom:co2],400,1200,undef,undef,'ppm',"100,1",[(600,120,1000,60,1200,0)],0,'0,0,1,5')
</syntaxhighlight>
''Ergebnis der Beispieldefinition in der Webansicht:''
[[Datei:ring_bsp.png|ohne|mini]]

===== Farbskalierte Temperatur- und Feuchtigkeitsanzeige mit Hilfe der SVG-Funktion '''temp_hum_ring''' =====
Die Farbe ist jeweils abhängig vom dargestellten Temperatur- bzw. Feuchtigkeitswert. Die Helligkeit der Farbgebung ist einstellbar:
[[Datei:Farbskalierung temp_hum_ring_scaling.png|600px|ohne]]

{{Randnotiz|RNText=SVG-uiTable-Funktion '''temp_hum_ring'''
<syntaxhighlight lang="perl">
temp_hum_ring ($temp_value,$hum_value,$temp_min,$temp_max,$size, $lightring,$lightnumber,$decFontTemp,$decFontHum)

$temp_value # Temperatur
$hum_value # Feuchtigkeit
$temp_min # minimale Temperatur, optional, default=-20
$temp_max # maximale Temperatur, optional, default=60
$size # Größe der Grafik, optional, default=90
$lightring # Helligkeit des Ringes (0-100), optional, default=50
$lightnumber # Helligkeit der Zahl (0-100), optional, default=50
$decFontTemp # Temperatur: "<Anzahl der Nachkommastellen>,<Schrift-SVG-Attribute Wert>,<Schrift-SVG-Attribute Einheit>", optional
$decFontHum # Feuchtigkeit: "<Anzahl der Nachkommastellen>,<Schrift-SVG-Attribute Wert>,<Schrift-SVG-Attribute Einheit>", optional
</syntaxhighlight>
}}
'''<big>Beispieldefinition</big>'''
<syntaxhighlight lang="perl">
defmod di_temp_hum_ring DOIF ##
attr di_temp_hum_ring uiTable {package ui_Table}\
\
"klein"|temp_hum_ring([Aussensensor:temperature],[Aussensensor:humidity],undef,undef,60)\
"normal"|temp_hum_ring([Aussensensor:temperature],[Aussensensor:humidity])\
"größer, aufgehellt"|temp_hum_ring([Aussensensor:temperature],[Aussensensor:humidity],undef,undef,100,undef,80)\
"größer, Ring aufgehellt, Normalschrift"|temp_hum_ring([Aussensensor:temperature],[Aussensensor:humidity],undef,undef,100,80,50,"1,font-weight:normal","0,font-weight:normal")
</syntaxhighlight>
''Ergebnis der Beispieldefinition in der Webansicht:''
[[Datei:temp_hum_ring_bsp.png|ohne|mini]]

===== Farbskalierte Anzeige von zwei Temperaturwerten mit Hilfe der SVG-Funktion '''temp_temp_ring''' =====
Die Farbe ist jeweils abhängig vom dargestellten Temperaturwert. Die Helligkeit der Farbgebung ist einstellbar:
[[Datei:Farbskalierung temp_temp_ring_scaling.png|600px|ohne]]

{{Randnotiz|RNText=SVG-uiTable-Funktion '''temp_temp_ring'''
<syntaxhighlight lang="perl">
temp_temp_ring ($temp1_value,$temp2_value,$temp_min,$temp_max,$size, $lightring,$lightnumber,$decFontTemp1,$decFontTemp2)

$temp1_value # erster Temperaturwert
$temp2_value # zweiter Temperaturwert
$temp_min # minimale Temperatur, optional, default=-20
$temp_max # maximale Temperatur, optional, default=60
$size # Größe der Grafik, optional, default=90
$lightring # Helligkeit des Ringes (0-100), optional, default=50
$lightnumber # Helligkeit der Zahl (0-100), optional, default=50
$decFontTemp1 # Temperatur1: "<Anzahl der Nachkommastellen>,<Schrift-SVG-Attribute Wert>,<Schrift-SVG-Attribute Einheit>", optional
$decFontTemp2 # Temperatur2: "<Anzahl der Nachkommastellen>,<Schrift-SVG-Attribute Wert>,<Schrift-SVG-Attribute Einheit>", optional
</syntaxhighlight>
}}
'''<big>Beispieldefinition</big>'''
<syntaxhighlight lang="perl">
defmod di_temp_temp_ring DOIF ##
attr di_temp_temp_ring uiTable {package ui_Table}\
"klein, Ring augehellt"|temp_temp_ring([Vorlauf:Temperature],[Ruecklauf:Temperature],15,60,60,80,50)\
"normal"|temp_temp_ring([Vorlauf:Temperature],[Ruecklauf:Temperature],15,60)\
"groß, Zahlen aufgehellt"|temp_temp_ring([Vorlauf:Temperature],[Ruecklauf:Temperature],15,60,100,undef,80)
</syntaxhighlight>
''Ergebnis der Beispieldefinition in der Webansicht:''
[[Datei:temp_hum_temp_bsp.png|ohne|mini]]

<br>
<br>
<br>
===== Farbskalierte Anzeige von zwei Zahlenwerten mit Hilfe der universellen SVG-Funktion '''ring2''' =====
Die Farbe der dargestellten Werte kann abhängig vom Wert bestimmt werden.
{{Randnotiz|RNText=SVG-uiTable-Funktion '''ring2'''
<syntaxhighlight lang="perl">
ring2 ($value1,$min1,$max1,$minColor1,$maxColor1,$desc1,$size,$colorFunc1,$decFont1, $value2,$min2,$max2,$minColor2,$maxColor2,$desc2,$colorFunc2,$decFont2, $lightness,$icon,$model)

$value1 # darzustellender Wert1
$min1 # minimaler Wert, optional, default=0
$max1 # maximaler Wert, optional, default=100
$minColor1 # Farbe (hue: 0-360) des kleinsten Wertes, optional, default = undef
$maxColor1 # Farbe (hue: 0-360) des maximalen Wertes, optional, default = undef
$desc1 # Beschreibung des Wertes, optional, default = undef
$size # Größe der Grafik, optional, default = 100
$colorFunc1 # Funktion, die zu einem Wert einen Farbwert (hue: 0-360) bestimmt, optional, default = undef
$decFontUnit1 # "<Anzahl der Nachkommastellen>,<Schrift-SVG-Attribute Wert>,<Schrift-SVG-Attribute Einheit>,<Einheit hinter dem Zahlenwert>", optional
$value2 # darzustellender Wert2
...
$decFontUnit2 # "<Anzahl der Nachkommastellen>,<Schrift-SVG-Attribute Wert>,<Schrift-SVG-Attribute Einheit>,<Einheit hinter dem Zahlenwert>", optional
$lightness # Helligkeit einzelner Elemente (0-100) "<ring>,<inner ring>,<minMax>,<unit>,<value>,<icon>", optional, default: "50,50,50,40,50,40"
$model # '<color gradient>,<min/max>,<inner ring>,<pointer>,<mode>'
# <color gradient>: "gradient" (undef),"nogradient" (1)
# <min/max>: Style-SVG-Attribute oder "nominmaxvalue" (undef), "minmaxvalue" (1)
# <inner ring>: Style-SVG-Attribute oder "innerring" (1), "noinnerring" (undef)
# <pointer>: Breite des Zeigers in Pixel, "nopointer" (undef)
# <mode>: "minmax" (undef), "negzeropos" (1), "zeronegpos" (2)
# alle Parameter sind optional, default keine Angaben: ',,,,,,'

Argumente für den zweiten Wert entsprechend den Argumenten des ersten Wertes
</syntaxhighlight>
Wird '''$colorFunc...''' nicht angegeben, so wird der Farbwert zwischen '''$minColor...''' und '''$maxColor...''' linear interpoliert
}}

'''<big>Beispieldefinition</big>'''
<syntaxhighlight lang="perl">
defmod di_ring2 DOIF ##
attr di_ring2 uiTable {package ui_Table;;}\
## Leistungsaufnahme von 0 kW bis 3,6 kW in Farben von grün (hue:120) bis rot (hue:0)\
## Kapazität von 0 % bis 100 % V in Farben von rot (hue:0) bis grün (hue:120)\
"Wallbox"| ring2([tesla:Leistung],0,3.6,120,0,"kW",undef,undef,"1,font-weight:normal",[tesla:Kapazitaet],0,100,0,120,"%",undef,"0,font-weight:normal")\
\
## Stromstärke von 0 A bis 2 A in Farben von grün (hue:120) bis rot (hue:0)\
## Spannung von 1 V bis 1.5 V in Farben von rot (hue:0) bis grün (hue:120)\
## 3 Nachkommastellen, Normalschrift, Schriftgröße 80% \
"Akku"| ring2([akku:Strom],0,2,120,0,"A",undef,undef,"3,font-weight:normal;;font-size:80%",[akku:Spannung],1,1.5,0,120,"V",undef,"3,font-weight:normal;;font-size:80%")
</syntaxhighlight>

''Ergebnis der Beispieldefinition in der Webansicht:''
[[Datei:ring2_bsp.png|ohne|mini]]

'''<big>Beispieldefinition Innenring, Farb-Array, Ringmodi</big>'''
<syntaxhighlight lang="perl">
defmod di_solar DOIF {}
attr di_solar uiTable {package ui_Table}\
"Farb-Array, ringMode 1"|\
ring2([zaehler:Produktion],-20,30,undef,undef,"PV kWh",130,[(-10,0,-0.001,30,10,60,30,90)],"2",[test:Bezug],-20,30,undef,undef,"Bezug",[(-10,0,-0.001,30,10,60,30,90)],"2",undef,undef,"0,1,1,0,1")\
"Farbe linear, ringMode 1"|\
ring2([zeahler:Produktion],-20,30,0,120,"PV kWh",130,undef,"2",[test:Bezug],-20,30,0,120,"Bezug",undef,"2",undef,undef,"0,1,1,0,1")\
"Farbe linear, ringMode 2"|\
ring2([zaehler:Produktion],0,30,60,120,"PV kWh",130,undef,"2",[test:Bezug],-20,0,0,120,"Bezug",undef,"2",undef,undef,"0,,,0,2")
</syntaxhighlight>
''Ergebnis der Beispieldefinition in der Webansicht:''
[[Datei:ring2_ringMode.png|ohne|mini]]

<br clear="all">

==== '''icon_ring'''-Funktionen ====
===== Farbskalierte Temperaturanzeige mit einem Icon mit Hilfe der SVG-Funktionen '''icon_temp_ring/icon_temp_mring''' =====
Diese Funktionen basieren auf den obigen temp_ring-Funktionen, zusätzlich wird ein SVG-Icon dargestellt. Die Farbe des Icons kann mit @ an den Iconnamen angehängt werden, ansonsten wird die Farbe der Temperatur für das Icon verwendet. Die Größe des Icons kann skaliert werden, ebenso kann die Positionen des Icons verschoben werden.

{{Randnotiz|RNText=SVG-uiTable-Funktion '''icon_temp_ring/icon_temp_mring'''
<syntaxhighlight lang="perl">
icon_temp_ring/icon_temp_mring ($icon,$temp_value,$temp_min,$temp_max,$size,$lightring,$lightnumber,$decFont)

$icon # "Iconname\@Farbe,Skalierungsfaktor,x-Position,y-Position,Rotation", \@Farbe, Skalierungsfaktor, x-Position, y-Position, Rotation (0-360) sind optional
$temp_value # Temperatur
$temp_min, # minimale Temperatur, optional, default=-20
$temp_max, # maximale Temperatur, optional, default=60
$size, # Größe der Grafik, optional, default=80
$lightring, # Helligkeit des Ringes (0-100), optional, default=50
$lightnumber # Helligkeit der Zahl (0-100), optional, default=50
$decFont # "<Anzahl der Nachkommastellen>,<Schrift-SVG-Attribute Wert>,<Schrift-SVG-Attribute Einheit>", optional
</syntaxhighlight>
}}
'''<big>Beispieldefinition</big>'''
<syntaxhighlight lang="perl">
defmod di_Heizung_temp DOIF ##
attr di_Heizung_temp uiTable {\
package ui_Table;;\
}\
\
icon_temp_ring("temp_outside",[vaillant:Aussentemp],-15,40)|\
icon_temp_mring(([vaillant:Flame] eq "off"?"sani_boiler_temp\@white":"sani_boiler_temp\@Darkorange"),[vaillant:Vorlauf],15,70)|\
icon_temp_mring(([vaillant:Pumpenstatus] eq "4" ? "sani_buffer_temp_down\@Darkorange" : "sani_buffer_temp_down\@white"),[vaillant:WWSpeicher],15,70)|\
icon_temp_mring(([Zirk] eq "off"?"sani_pump\@white":"sani_pump\@Darkorange"),[ESPEasy_ESP_Temp_Zirkulation:Temperature],15,70)|\
icon_temp_mring(([vaillant:Pumpenstatus] eq "on" ? "sani_floor_heating\@Darkorange" : "sani_floor_heating_neutral\@white"),[ESPEasy_ESP_Temp_Vorlauf:Temperature],15,70)|\
icon_temp_mring("sani_floor_heating_neutral\@white",[ESPEasy_ESP_Temp_Keller_Ruecklauf:Temperature],15,70)|""

</syntaxhighlight>
''Ergebnis der Beispieldefinition in der Webansicht:''
[[Datei:icon_temp_ring_bsp.png|ohne|mini]]

===== Farbskalierte Feuchtigkeitsanzeige mit einem Icon mit Hilfe der SVG-Funktionen '''icon_hum_ring/icon_hum_mring''' =====
Diese Funktionen basieren auf den obigen hum_ring-Funktionen, zusätzlich wird ein SVG-Icon dargestellt. Die Farbe des Icons kann mit @ an den Iconnamen angehängt werden, ansonsten wird die Farbe der Feuchtigkeit für das Icon verwendet. Die Größe des Icons kann skaliert werden, ebenso kann die Positionen des Icons verschoben werden.
{{Randnotiz|RNText=SVG-uiTable-Funktion '''icon_hum_ring/icon_hum_mring'''
<syntaxhighlight lang="perl">
icon_hum_ring/icon_hum_mring ($icon,$hum_value,$size,$lightring,$lightnumber,$decFont)

$icon # "Iconname\@Farbe,Skalierungsfaktor,x-Position,y-Position,Rotation", \@Farbe, Skalierungsfaktor, x-Position, y-Position, Rotation sind optional
$hum_value # Feuchtigkeit
$size # Größe der Grafik, optional, default=80
$lightring # Helligkeit des Ringes (0-100), optional, default=50
$lightnumber # Helligkeit der Zahl (0-100), optional, default=50
$decFont # "<Anzahl der Nachkommastellen>,<Schrift-SVG-Attribute Wert>,<Schrift-SVG-Attribute Einheit>", optional
</syntaxhighlight>
}}

'''<big>Beispieldefinition</big>'''
<syntaxhighlight lang="perl">
defmod di_icon_hum_ring DOIF ##
attr di_icon_hum_ring room test5
attr di_icon_hum_ring uiTable {package ui_Table}\
"klein ohne Farbverlauf"|icon_hum_mring("weather_humidity",[Aussensensor:humidity],60)\
"normal groß mit Farbverlauf"|icon_hum_ring("weather_humidity",[Aussensensor:humidity])\
"groß ohne Farbverlauf aufgehellt"|icon_hum_mring("weather_humidity",[Aussensensor:humidity],100,80)
</syntaxhighlight>
''Ergebnis der Beispieldefinition in der Webansicht:''
[[Datei:icon_hum_ring_bsp.png|ohne|mini]]

===== Farbskalierte Anzeige eines Icons mit einem Zahlenwert mit Hilfe der universellen SVG-Funktion '''icon_ring/icon_mring/icon_uring''' =====
Diese Funktionen basieren auf der universellen ring-Funktion. Die Farbe des dargestellten Icons und des Wertes kann abhängig vom Wert bestimmt werden. Die Funktion '''icon_ring''' stellt den Farbring mit Farbverlauf dar, die Funktion '''icon_mring''' stellt den Farbring einfarbig dar. Die universelle Funktion '''icon_uring''' kann über den Parameter '''$model''' das Erscheinungsbild der Grafik verändern.

{{Randnotiz|RNText=SVG-uiTable-Funktion '''icon_ring/icon_mring/icon_uring'''
<syntaxhighlight lang="perl">
icon_ring ($icon,$value,$min,$max,$minColor,$maxColor, $unit,$decFont,$size,$colorRef,$lightness,$model)

icon_mring ($icon,$value,$min,$max,$minColor,$maxColor, $unit,$decFont,$size,$colorRef,$lightness)

icon_uring ($model,$icon,$value,$min,$max,$minColor,$maxColor, $unit,$decFont,$size,$colorRef,$lightness)

$icon # "Iconname\@Farbe,Skalierungsfaktor,x-Position,y-Position,Rotation", \@Farbe, Skalierungsfaktor, x-Position, y-Position, Rotation sind optional
$value # darzustellender Wert
$min # minimaler Wert, optional, default=0
$max # maximaler Wert, optional, default=100
$minColor # Farbe (hue: 0-360) des kleinsten Wertes, optional, default = undef
$maxColor # Farbe (hue: 0-360) des maximalen Wertes, optional, default = undef
$unit # Einheit des Wertes, optional, default = undef
$decFont # "<Anzahl der Nachkommastellen>,<Style-SVG-Attribute Wert>,<Style-SVG-Attribute Einheit>", optional
$size # Größe der Grafik, optional, default = 100
$colorRef # Referenz auf eine Funktion, die zu einem Wert einen Farbwert (hue: 0-360) bestimmt, oder eine Referenz auf eine Arrayliste mit Grenzwerten und Farben, optional, default = undef
$lightness # Helligkeit einzelner Elemente (0-100) "<ring>,<inner ring>,<minMax>,<unit>,<value>,<icon>", optional, default: "50,50,50,40,50,40"
$model # '<color gradient>,<min/max>,<inner ring>,<pointer>,<mode>'
# <color gradient>: "gradient" (undef),"nogradient" (1)
# <min/max>: Style-SVG-Attribute oder "nominmaxvalue" (undef), "minmaxvalue" (1)
# <inner ring>: Style-SVG-Attribute oder "innerring" (1), "noinnerring" (undef)
# <pointer>: Breite des Zeigers in Pixel, "nopointer" (undef)
# <mode>: "minmax" (undef), "negzeropos" (1), "zeronegpos" (2)
# alle Parameter sind optional, default keine Angaben: ',,,,,,'
</syntaxhighlight>
Wird '''$colorRef''' nicht angegeben, so wird der Farbwert zwischen '''$minColor''' und '''$maxColor''' linear interpoliert
}}

'''<big>Beispieldefinition</big>'''
<syntaxhighlight lang="perl">
defmod di_icon_ring DOIF ##
attr di_icon_ring uiTable {package ui_Table}\
\
icon_ring ('sani_floor_heating_neutral',[Heizenergie:Vortag_hc],0,150,120,0,'kWh')|\
icon_mring ('fuel',[Tankstelle:Diesel],1.10,1.30,120,0,'€',2)|\
icon_uring ('0,1,1',"air",[ESPEasy_Eingang_CO2:PPM],400,1200,undef,undef,'ppm',0,100,[(600,120,1000,60,1200,0)])|\
icon_uring ('0,1','Zisterne',([Wasserzisterne]/3.4),0,100,0,120,'%',0)##/\
\
icon_uring ('1,1,0,8',"measure_water_meter",[Wasserverbrauch:heute],0,600,120,0,'l',0)|\
icon_uring ('0,fill:white,opacity:0.4',([vaillant:Pumpenstatus] eq '4' ? 'sani_buffer_temp_down@Darkorange' : 'sani_buffer_temp_down@white'),[vaillant:Umlaufmenge],0,20,120,0,'l/min')|\
icon_uring('0,1,1,4','weather_barometric_pressure',[vaillant:Wasserdruck],0,3,undef,undef,'bar',1,100,[(0.8,0,1,60,1.5,120,1.7,60,3,0)])|\
icon_uring('0,opacity:0.8,1,6','sani_water_tap',[vaillant:HwcHours_hoursum2_value],0,2000,120,0,'h',0)
</syntaxhighlight>
''Ergebnis der Beispieldefinition in der Webansicht:''
[[Datei:icon_ring_bsp.png|ohne|mini]]
<br clear="all">

===== Farbskalierte Temperatur- und Feuchtigkeitsanzeige mit einem Icon mit Hilfe der SVG-Funktion '''icon_temp_hum_ring''' =====
Die Farbe ist jeweils abhängig vom dargestellten Temperatur- bzw. Feuchtigkeitswert. Die Helligkeit der Farbgebung ist einstellbar:

{{Randnotiz|RNText=SVG-uiTable-Funktion '''icon_temp_hum_ring'''
<syntaxhighlight lang="perl">
icon_temp_hum_ring ($icon,$temp_value,$hum_value,$temp_min,$temp_max,$size, $lightring,$lightnumber,$decFontTemp,$decFontHum)

$icon # "Iconname\@Farbe,Skalierungsfaktor,x-Position,y-Position,Rotation", \@Farbe, Skalierungsfaktor, x-Position, y-Position, Rotation sind optional
$temp_value # Temperatur
$hum_value # Feuchtigkeit
$temp_min # minimale Temperatur, optional, default=-20
$temp_max # maximale Temperatur, optional, default=60
$size # Größe der Grafik, optional, default=90
$lightring # Helligkeit des Ringes (0-100), optional, default=50
$lightnumber # Helligkeit der Zahl (0-100), optional, default=50
$decFontTemp # Temperatur: "<Anzahl der Nachkommastellen>,<Schrift-SVG-Attribute Wert>,<Schrift-SVG-Attribute Einheit>", optional
$decFontHum # Feuchtigkeit: "<Anzahl der Nachkommastellen>,<Schrift-SVG-Attribute Wert>,<Schrift-SVG-Attribute Einheit>", optional
</syntaxhighlight>
}}
'''<big>Beispieldefinition</big>'''
<syntaxhighlight lang="perl">
defmod di_icon_temp_hum_ring DOIF ##
attr di_icon_temp_hum_ring uiTable {package ui_Table}\
\
"normal"|icon_temp_hum_ring("temp_outside",[Aussensensor:temperature],[Aussensensor:humidity])\
"mit Normalschrift"|icon_temp_hum_ring("temp_outside",[Aussensensor:temperature],[Aussensensor:humidity], undef,undef,undef,undef,undef,"1,font-weight:normal","0,font-weight:normal")\
"größer aufgehellt"|icon_temp_hum_ring("temp_outside",[Aussensensor:temperature],[Aussensensor:humidity], undef,undef,120,undef,80)
</syntaxhighlight>
''Ergebnis der Beispieldefinition in der Webansicht:''
[[Datei:icon_temp_hum_ring.png|ohne|mini]]

===== Farbskalierte Anzeige von zwei Temperaturwerten mit einem Icon mit Hilfe der SVG-Funktion '''icon_temp_temp_ring''' =====
Die Farbe ist jeweils abhängig vom dargestellten Temperaturwert. Die Helligkeit der Farbgebung ist einstellbar:

{{Randnotiz|RNText=SVG-uiTable-Funktion '''icon_temp_temp_ring'''
<syntaxhighlight lang="perl">
icon_temp_temp_ring ($icon,$temp1_value,$temp2_value,$temp_min,$temp_max,$size, $lightring,$lightnumber,$decFontTemp1,$decFontTemp2)

$icon # "Iconname\@Farbe,Skalierungsfaktor,x-Position,y-Position,Rotation", \@Farbe, Skalierungsfaktor, x-Position, y-Position, Rotation sind optional
$temp1_value # erster Temperaturwert
$temp2_value # zweiter Temperaturwert
$temp_min # minimale Temperatur, optional, default=-20
$temp_max # maximale Temperatur, optional, default=60
$size # Größe der Grafik, optional, default=90
$lightring # Helligkeit des Ringes (0-100), optional, default=50
$lightnumber # Helligkeit der Zahl (0-100), optional, default=50
$decFontTemp1 # Temperatur1: "<Anzahl der Nachkommastellen>,<Schrift-SVG-Attribute Wert>,<Schrift-SVG-Attribute Einheit>", optional
$decFontTemp2 # Temperatur2: "<Anzahl der Nachkommastellen>,<Schrift-SVG-Attribute Wert>,<Schrift-SVG-Attribute Einheit>", optional
</syntaxhighlight>
}}
'''<big>Beispieldefinition</big>'''
<syntaxhighlight lang="perl">
defmod di_icon_temp_temp_ring DOIF ##
attr di_icon_temp_temp_ring uiTable {package ui_Table}\
## Größe 120%\
"FB-Heizung"|icon_temp_temp_ring(([vaillant:Pumpenstatus] eq "on" ? "sani_floor_heating\@Darkorange" : "sani_floor_heating_neutral\@white"),[ESPEasy_ESP_Temp_Vorlauf:Temperature],[ESPEasy_ESP_Temp_Keller_Ruecklauf:Temperature],15,70,120)\
\
## Größe 120%, Normalschrift\
"Temperatur","Taupunkt"|icon_temp_temp_ring("temp_outside",[Aussensensor:temperature],[Aussensensor:dewpoint],undef,undef,120,undef,undef,"1,font-weight:normal","1,font-weight:normal")
</syntaxhighlight>
''Ergebnis der Beispieldefinition in der Webansicht:''
[[Datei:icon_temp_temp_ring.png|ohne|mini]]

===== Farbskalierte Anzeige von zwei Zahlenwerten mit einem Icon mit Hilfe der universellen SVG-Funktion '''icon_ring2''' =====
Die Farbe der dargestellten Werte kann abhängig vom Wert bestimmt werden.

{{Randnotiz|RNText=SVG-uiTable-Funktion '''icon_ring2'''
<syntaxhighlight lang="perl">
icon_ring2 ($icon,$value1,$min1,$max1,$minColor1,$maxColor1,$desc1,$size,$colorFunc1,$decFont1, $value2,$min2,$max2,$minColor2,$maxColor2,$desc2,$colorFunc2,$decFont2,$lightnesss,$model)

$icon # "Iconname\@Farbe,Skalierungsfaktor,x-Position,y-Position,Rotation", \@Farbe, Skalierungsfaktor, x-Position, y-Position, Rotation sind optional
$value1 # darzustellender Wert1
$min1 # minimaler Wert, optional, default=0
$max1 # maximaler Wert, optional, default=100
$minColor1 # Farbe (hue: 0-360) des kleinsten Wertes, optional, default = undef
$maxColor1 # Farbe (hue: 0-360) des maximalen Wertes, optional, default = undef
$desc1 # Beschreibung des Wertes, optional, default = undef
$size # Größe der Grafik, optional, default = 100
$colorFunc1 # Funktion, die zu einem Wert einen Farbwert (hue: 0-360) bestimmt, optional, default = undef
$decFont1 # "<Anzahl der Nachkommastellen>,<Schrift-SVG-Attribute Wert>,<Schrift-SVG-Attribute Einheit>","<Einheit hinter dem Zahlenwert>" optional
$value2 ## darzustellender Wert2
...
$desc2 # Beschreibung des Wertes, optional, default = undef
$colorFunc2 # Funktion, die zu einem Wert einen Farbwert (hue: 0-360) bestimmt, optional, default = undef
$decFont2 # "<Anzahl der Nachkommastellen>,<Schrift-SVG-Attribute Wert>,<Schrift-SVG-Attribute Einheit>","<Einheit hinter dem Zahlenwert>" optional
$lightness # Helligkeit einzelner Elemente (0-100) "<ring>,<inner ring>,<minMax>,<unit>,<value>,<icon>", optional, default: "50,50,50,40,50,40"
$model # '<color gradient>,<min/max>,<inner ring>,<pointer>,<mode>'
# <color gradient>: "gradient" (undef),"nogradient" (1)
# <min/max>: Style-SVG-Attribute oder "nominmaxvalue" (undef), "minmaxvalue" (1)
# <inner ring>: Style-SVG-Attribute oder "innerring" (1), "noinnerring" (undef)
# <pointer>: Breite des Zeigers in Pixel, "nopointer" (undef)
# <mode>: "minmax" (undef), "negzeropos" (1), "zeronegpos" (2)
# alle Parameter sind optional, default keine Angaben: ',,,,,,'
Argumente für den zweiten Wert entsprechend den Argumenten des ersten Wertes
</syntaxhighlight>
Wird '''$colorFunc...''' nicht angegeben, so wird der Farbwert zwischen '''$minColor...''' und '''$maxColor...''' linear interpoliert.

Bei der Farbangabe des Icons beim Übergabeparameter $icon wird mit '''\@colorVal2''' das Icon mit der Farbe des zweiten Wertes eingefärbt. Bei keiner Farbangabe oder '''\@colorVal1''' wird das Icon mit der Farbe des ersten Wertes eingefärbt. Ansonsten gilt die allgemeine FHEM-Syntax für Farbgebung von Icons angehängt mit '''\@'''.
}}
'''<big>Beispieldefinition</big>'''
<syntaxhighlight lang="perl">
defmod di_icon_ring2 DOIF ##
attr di_icon_ring2 uiTable {package ui_Table;;\
\
sub himmelsrichtung {\
my ($richtung)=@_;;\
my $element=int($richtung/22.5);;\##/
my @h=(qw"N NNO NO ONO O OSO SO SSO S SSW SW WSW W WNW NW NNW");;\
return($h[$element]);;\
}\
}\
"Wallbox"| icon_ring2("car,1.5,0,-3",[tesla:Leistung],0,3.6,120,0,"kW",120,undef,"1,font-weight:normal",[tesla:Kapazitaet],0,100,0,120,"%",undef,"0,font-weight:normal")\
\
"Wind"|icon_ring2(([Wind:Geschwindigkeit]>0 ? "wind":"no_wind").",1,0,0,".[Wind:Richtung],[Wind:Geschwindigkeit],0,50,120,0,"km/h",120,undef,1,[Wind:Richtung],361,361,220,220,([Wind:Geschwindigkeit]>0?himmelsrichtung([Wind:Richtung]):"--"),undef,0)\
\
"Strom"|icon_ring2([zaehler:l-Produktion] > 0 ? "sani_solar\@colorVal1":"fa_bolt\@colorVal2",[zaehler:l-Produktion],0,3.6,20,120,"PV kW",150,undef,"1,,font-size:50%;fill:white",[zaehler:l-Bezug,0],0,2,120,0,"Netz kW",undef,"1,,font-size:50%;fill:white")
</syntaxhighlight>
''Ergebnis der Beispieldefinition in der Webansicht:''
[[Datei:icon_ring2.png|ohne|mini]]

==== '''bar'''-Funktionen ====
===== Farbskalierte Anzeige der Temperatur in Balkenform mit Hilfe der SVG-Funktionen '''temp_bar/temp_mbar''' =====
Die Farbe der dargestellten Temperatur ist abhängig vom Temperaturwert. Die Helligkeit der Farbgebung ist einstellbar. Bei der '''temp_mbar'''-SVG-Funktion wird der Balken einfarbig dargestellt.

Farbskalierung der '''temp_bar'''-SVG-Funktion:
[[Datei:Farbskalierung temp_bar_scaling.png|600px|ohne]]

Farbskalierung der '''temp_mbar'''-SVG-Funktion:
[[Datei:Farbskalierung temp_mbar_scaling.png|600px|ohne]]

{{Randnotiz|RNText=SVG-uiTable-Funktion '''temp_bar/temp_mbar'''
<syntaxhighlight lang="perl">
temp_bar/temp_mbar ($temp_value,$temp_min,$temp_max, $header,$width,$height,$size, $light,$lightnumber,$decFont)

$temp_value # Temperaturwert
$temp_min # minimale Temperatur, optional, default=-20
$temp_max # maximale Temperatur, optional, default=60
$header # Überschrift, optional, default= undef (keine)
$width # Breite der Grafik, optional, default=63
$height # Höhe der Grafik, optional, default=60
$size # Größe der Grafik, optional, default=100
$light # Helligkeit der Grafik (0-100), optional, default=50
$lightnumber # Helligkeit der Zahl (0-100), optional, default=50
$decFont # "<Anzahl der Nachkommastellen>,<Schrift-SVG-Attribute Wert>,<Schrift-SVG-Attribute Einheit>", optional, default = 1
</syntaxhighlight>
}}
'''<big>Beispieldefinition</big>'''
<syntaxhighlight lang="perl">
defmod di_temp_bar DOIF ##
attr di_temp_bar uiTable {package ui_Table}\
"standard"|temp_bar([Aussensensor:temperature])\
"heller"|temp_bar([Aussensensor:temperature],undef,undef,undef,undef,undef,undef,80)\
"monochrom"|temp_mbar([Aussensensor:temperature])\
"kleiner"|temp_bar([Aussensensor:temperature],undef,undef,undef,undef,undef,80)\
"mit Überschrift"|temp_bar([Aussensensor:temperature],undef,undef,"Außen")\
"hoch"|temp_bar([Aussensensor:temperature],undef,undef,undef,undef,100)
</syntaxhighlight>
''Ergebnis der Beispieldefinition in der Webansicht:''
[[Datei:temp_bar_bsp.png|ohne|mini]]

===== Farbskalierte Anzeige der Feuchtigkeit in Balkenform mit Hilfe der SVG-Funktionen '''hum_bar/hum_mbar''' =====
Die Farbe der dargestellten Feuchtigkeit ist abhängig vom Feuchtigkeitswert. Die Helligkeit der Farbgebung ist einstellbar. Bei der '''hum_mbar'''-SVG-Funktion wird der Balken einfarbig dargestellt.

Farbskalierung der '''hum_bar'''-SVG-Funktion:
[[Datei:Farbskalierung hum_bar_scaling.png|600px|ohne]]

Farbskalierung der '''hum_mbar'''-SVG-Funktion:
[[Datei:Farbskalierung hum_mbar_scaling.png|600px|ohne]]

{{Randnotiz|RNText=SVG-uiTable-Funktion '''hum_bar/hum_mbar'''
<syntaxhighlight lang="perl">
hum_bar/hum_mbar ($hum_value,$header,$width,$height,$size, $light,$lightnumber,$decFont)

$hum_value # Feuchtigkeitswert
$header # Überschrift, optional, default = undef (keine)
$width # Breite der Grafik, optional, default=63
$height # Höhe der Grafik, optional, default=80
$size # Größe der Grafik, optional, default=100
$light # Helligkeit des der Grafik (0-100), optional, default=50
$lightnumber # Helligkeit der Zahl (0-100), optional, default=50
$decFont # "<Anzahl der Nachkommastellen>,<Schrift-SVG-Attribute Wert>,<Schrift-SVG-Attribute Einheit>", optional, default = 0
</syntaxhighlight>
}}
'''<big>Beispieldefinition</big>'''
<syntaxhighlight lang="perl">
defmod di_hum_bar DOIF ##
attr di_hum_bar uiTable {package ui_Table}\
"standard"|hum_bar([Aussensensor:humidity])\
"heller"|hum_bar([Aussensensor:humidity],undef,undef,undef,undef,80)\
"monochrom"|hum_mbar([Aussensensor:humidity])\
"kleiner"|hum_bar([Aussensensor:humidity],undef,undef,undef,80)\
"mit Überschrift"|hum_bar([Aussensensor:humidity],"Außen")\
"hoch"|hum_bar([Aussensensor:humidity],undef,undef,100)
</syntaxhighlight>
''Ergebnis der Beispieldefinition in der Webansicht:''
[[Datei:hum_bar_bsp.png|ohne|mini]]

===== Farbskalierte Anzeige eines Zahlenwertes mit Hilfe der universellen SVG-Funktion '''bar''' =====
Die Farbe des dargestellten Wertes kann abhängig vom Wert bestimmt werden.
{{Randnotiz|RNText=SVG-uiTable-Funktion '''bar'''
<syntaxhighlight lang="perl">
bar ($value,$min,$max,$header,$minColor,$maxColor,$unit,$width, $height,$size,$colorFunc,$decFont,$gradient,$light,$lightnumber)

$value # darzustellender Wert
$min # minimaler Wert, optional, default=0
$max # maximaler Wert, optional, default=100
$header # Überschrift, optional, default = undef (keine)
$minColor # Farbe (hue: 0-360) des kleinsten Wertes, optional, default = undef
$maxColor # Farbe (hue: 0-360) des maximalen Wertes, optional, default = undef
$unit # Einheit des Wertes, optional, default = undef
$width # Breite der Grafik, optional, default = 63
$height # Höhe der Grafik, optional, default = 60
$size # Größe der Grafik, optional, default = 100
$colorFunc # Funktion, die zu einem Wert einen Farbwert (hue: 0-360) bestimmt, optional, default = undef
$decFont # "<Anzahl der Nachkommastellen>,<Schrift-SVG-Attribute Wert>,<Schrift-SVG-Attribute Einheit>", optional, default = 1
$gradient # Farbverlauf, optional, undef mit Farbverlauf, 1 ohne Farbverlauf, default = undef
$light # Helligkeit der Grafik (light:0-100), optional, default=50
$lightnumber # Helligkeit der Zahl (light:0-100), optional, default=50
</syntaxhighlight>
Wird '''$colorFunc''' nicht angegeben, so wird der Farbwert zwischen '''$minColor''' und '''$maxColor''' linear interpoliert
}}
'''<big>Beispieldefinition</big>'''
<syntaxhighlight lang="perl">
{package ui_Table}
defmod di_bar DOIF ##
attr di_bar uiTable {package ui_Table}\
## von 0 bis 20 in Farben von grün (hue:120) bis rot (hue:0)\
"Umlaufmenge"|bar([heizung:Umlaufmenge],0,20,"Umlauf",120,0,"l/min")\
\
## von 0 bis 3 in Farben von rot (hue:0) bis türkis (hue:180)\
"Wasserdruck"|bar([heizung:Wasserdruck],0,3,undef,0,180,"bar"undef,70,undef,undef,"1,font-size:130%;;font-weight:normal")\
\
## Temperaturdarstellung, entspricht dem Funktionsaufruf:\
## temp_bar ([Aussensensor:temperature],-20,60)\
"Temperatur"|bar([Aussensensor:temperature],-20,60,undef,undef,undef,"°C",undef,undef,undef,\&temp_hue)
</syntaxhighlight>
''Ergebnis der Beispieldefinition in der Webansicht:''
[[Datei:bar_bsp.png|ohne|mini]]

==== '''icon_bar'''-Funktionen ====
===== Farbskalierte Anzeige der Temperatur in Balkenform mit Hilfe der SVG-Funktion '''icon_temp_bar/icon_temp_mbar''' =====
Die Farbe der dargestellten Temperatur ist abhängig vom Temperaturwert. Die Helligkeit der Farbgebung ist einstellbar. Bei der '''icon_temp_mbar'''-SVG-Funktion wird der Balken einfarbig dargestellt.

{{Randnotiz|RNText=SVG-uiTable-Funktion '''icon_temp_bar/icon_temp_mbar'''
<syntaxhighlight lang="perl">
icon_temp_bar/icon_temp_mbar ($icon,$temp_value,$temp_min,$temp_max, $header,$width,$height,$size,$light,$lightnumber,$decFont)

$icon # "Iconname\@Farbe,Skalierungsfaktor,x-Position,y-Position", \@Farbe, Skalierungsfaktor, x-Position, y-Position sind optional
$temp_value # Temperaturwert
$temp_min # minimale Temperatur, optional, default=-20
$temp_max # maximale Temperatur, optional, default=60
$header # Überschrift, optional, default= undef (keine)
$width # Breite der Grafik, optional, default=63
$height # Höhe der Grafik, optional, default=75
$size # Größe der Grafik, optional, default=100
$light # Helligkeit der Grafik (0-100), optional, default=50
$lightnumber # Helligkeit der Zahl (0-100), optional, default=50
$decFont # "<Anzahl der Nachkommastellen>,<Schrift-SVG-Attribute Wert>,<Schrift-SVG-Attribute Einheit>", optional, default = 1
</syntaxhighlight>
}}
'''<big>Beispieldefinition</big>'''
<syntaxhighlight lang="perl">
defmod di_icon_temp_bar DOIF ##
attr di_icon_temp_bar room test10
attr di_icon_temp_bar uiTable {package ui_Table}\
"standard"|icon_temp_bar("temp_outside",[Aussensensor:temperature])\
"heller"|icon_temp_bar("temp_outside",[Aussensensor:temperature],undef,undef,undef,undef,undef,undef,80)\
"monochrom"|icon_temp_mbar("temp_outside",[Aussensensor:temperature])\
"kleiner"|icon_temp_bar("temp_outside",[Aussensensor:temperature],undef,undef,undef,undef,undef,80)\
"mit Überschrift"|icon_temp_bar("temp_outside",[Aussensensor:temperature],undef,undef,"Außen")\
"hoch"|icon_temp_bar("temp_outside",[Aussensensor:temperature],undef,undef,undef,undef,100)
</syntaxhighlight>
''Ergebnis der Beispieldefinition in der Webansicht:''
[[Datei:icon_temp_bar_bsp.png|ohne|mini]]

===== Farbskalierte Anzeige der Feuchtigkeit in Balkenform mit Hilfe der SVG-Funktionen '''icon_hum_bar/icon_hum_mbar''' =====
Die Farbe der dargestellten Feuchtigkeit ist abhängig vom Feuchtigkeitswert. Die Helligkeit der Farbgebung ist einstellbar. Bei der '''icon_hum_mbar'''-SVG-Funktion wird der Balken einfarbig dargestellt.

{{Randnotiz|RNText=SVG-uiTable-Funktion '''icon_hum_bar/icon_hum_mbar'''
<syntaxhighlight lang="perl">
icon_hum_bar/icon_hum_mbar ($icon,$hum_value,$header,$width,$height,$size, $light,$lightnumber,$decFont)

$icon # "Iconname\@Farbe,Skalierungsfaktor,x-Position,y-Position", \@Farbe, Skalierungsfaktor, x-Position, y-Position sind optional
$hum_value # Temperaturwert
$header # Überschrift, optional, default = undef (keine)
$width # Breite der Grafik, optional, default=63
$height # Höhe der Grafik, optional, default=75
$size # Größe der Grafik, optional, default=100
$light # Helligkeit des der Grafik (0-100), optional, default=50
$lightnumber # Helligkeit der Zahl (0-100), optional, default=50
$decFont # "<Anzahl der Nachkommastellen>,<Schrift-SVG-Attribute Wert>,<Schrift-SVG-Attribute Einheit>", optional, default = 1
</syntaxhighlight>
}}
'''<big>Beispieldefinition</big>'''
<syntaxhighlight lang="perl">
defmod di_icon_hum_bar DOIF ##
attr di_icon_hum_bar uiTable {package ui_Table}\
"standard"|icon_hum_bar("temperature_humidity",[Aussensensor:humidity])\
"heller"|icon_hum_bar("temperature_humidity",[Aussensensor:humidity],undef,undef,undef,undef,80)\
"monochrom"|icon_hum_mbar("temperature_humidity",[Aussensensor:humidity])\
"kleiner"|icon_hum_bar("temperature_humidity",[Aussensensor:humidity],undef,undef,undef,80)\
"mit Überschrift"|icon_hum_bar("temperature_humidity",[Aussensensor:humidity],"Außen")\
"hoch"|icon_hum_bar("temperature_humidity",[Aussensensor:humidity],undef,undef,100)
</syntaxhighlight>
''Ergebnis der Beispieldefinition in der Webansicht:''
[[Datei:icon_hum_bar_bsp.png|ohne|mini]]

===== Farbskalierte Anzeige eines Zahlenwertes mit Hilfe der universellen SVG-Funktionen '''icon_bar/icon_mbar''' =====
Die Farbe des dargestellten Wertes und des Icons kann abhängig vom Wert bestimmt werden. Bei der '''icon_mbar'''-SVG-Funktion wird der Balken einfarbig dargestellt.

{{Randnotiz|RNText=SVG-uiTable-Funktion '''icon_bar/icon_mbar'''
<syntaxhighlight lang="perl">
icon_bar ($icon,$value,$min,$max,$minColor,$maxColor,$unit,$decfont,$header,$width,$height,$size, $colorFunc,$light,$lightnumber)

$icon # "Iconname\@Farbe,Skalierungsfaktor,x-Position,y-Position,Rotation", \@Farbe, Skalierungsfaktor, x-Position, y-Position, Rotation (0-360) sind optional
$value # darzustellender Wert
$min # minimaler Wert, optional, default=0
$max # maximaler Wert, optional, default=100
$header # Überschrift, optional, default = undef (keine)
$minColor # Farbe (hue: 0-360) des kleinsten Wertes, optional, default = undef
$maxColor # Farbe (hue: 0-360) des maximalen Wertes, optional, default = undef
$unit # Einheit des Wertes, optional, default = undef
$decFont # "<Anzahl der Nachkommastellen>,<Schrift-SVG-Attribute Wert>,<Schrift-SVG-Attribute Einheit>", optional, default = 1
$width # Breite der Grafik, optional, default = 63
$height # Höhe der Grafik, optional, default = 75
$size # Größe der Grafik, optional, default = 100
$colorFunc # Funktion, die zu einem Wert einen Farbwert (hue: 0-360) bestimmt, optional, default = undef
$light # Helligkeit der Grafik (light:0-100), optional, default=50
$lightnumber # Helligkeit der Zahl (light:0-100), optional, default=50
</syntaxhighlight>
Wird '''$colorFunc''' nicht angegeben, so wird der Farbwert zwischen '''$minColor''' und '''$maxColor''' linear interpoliert
}}
'''<big>Beispieldefinition</big>'''
<syntaxhighlight lang="perl">
defmod di_icon_bar_bsp DOIF ##
attr di_icon_bar_bsp uiTable {package ui_Table;;\
}\
icon_bar ("fuel",[Tankstelle:Diesel],1.10,1.30,120,0,"€",2)|\
icon_bar ("air",[ESPEasy_Eingang_CO2:PPM],400,1200,120,0,"ppm",0)|\
icon_bar ("Zisterne",([Wasserzisterne]/3.4),0,100,0,120,"%",0)|\
icon_bar (([vaillant:Pumpenstatus] eq "off" ? "sani_buffer_temp_down\@Darkorange" : "sani_buffer_temp_down\@white"),[vaillant:Umlaufmenge],0,20,120,0,"l/min")\
icon_bar ("measure_water_meter",[Wasserverbrauch:heute],0,600,120,0,"l",0)|\
icon_bar ("weather_barometric_pressure",[vaillant:Wasserdruck],0,3,0,180,"bar")|\
icon_bar ("sani_water_tap",[vaillant:HwcHours_hoursum2_value],0,2000,120,0,"h",0)|\
icon_bar ("sani_floor_heating_neutral",[Heizenergie:Vortag_hc],0,150,120,0,"kWh")
</syntaxhighlight>
''Ergebnis der Beispieldefinition in der Webansicht:''
[[Datei:icon_bar_bsp.png|ohne|mini]]
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>

==== Anzeige eines Werteverlaufs und des aktuellen Wertes mit Hilfe der SVG-Funktion '''card''' ====
Es wird der aktuelle Wert eines Readings, sein zeitlicher Verlauf sowie der maximale und minimale Wert in Form einer Informationskarte visualisiert. Das Erscheinungsbild kann über zahlreiche Parameter individualisiert werden. Die Besonderheit ist das Argument '''<collect type>''' bei der Angabe des Readings der Form '''[<Device>:<Reading>:<collect type]'''. Dadurch werden Daten des Readings im DOIF-Modul gesammelt und für die Erzeugung eines Graphen zur Verfügung gestellt - es sind keine weiteren Definitionen erforderlich. Dabei wird besonders sparsam mit der Datensammlung umgegangen. Die gesammelten Daten werden über den FHEM-Befehl '''save''' in versteckten Readings des jeweiligen DOIF-Moduls gespeichert.

{{Randnotiz|RNText=SVG-uiTable-Funktion '''card'''
<syntaxhighlight lang="perl">
card ($collect,$header,$icon,$min,$max,$minColor,$maxColor, $desc,$colorRef,$decFontUnit,$prop,$ringModel,$lightness, $collect2,$min2,$max2,$minColor2,$maxColor2,$desc2,$func2,$decFontUnit2)

$collect/$collect2
# Angabe eines Readings oder eines Arrays mit mehreren Readings der Form [<Device>:<Reading>:<collect type>:<output>], mit Hilfe des Argumentes <collect type> wird das Modul angewiesen Daten des Readings über einen bestimmten Zeitraum zu sammeln. Sollen Werte aus einem Array nur im Ring angezeigt werden und nicht Diagramm visualisiert werden, so wird das <collect type> nicht angegeben. Dabei können pro Wert eigene ring-Formatierungen vorgenommen werden. Mindestens ein Reading muss mit <collect type> angegeben werden.

<collect type>
# Darstellung kontinuierlicher Daten als Linie
col<number><timeFormat>
# <timeFormat>: d Tage, w Wochen, ohne Angabe des Zeitformates wird <Anzahl> in Stunden interpretiert.
# Beispiele: col (entspricht col24), col1, col12, col1d, col3d, col1w, col4w, col52w usw.

# Darstellung eines Wertes als Säule eines bestimmten Zeitraum (Stunde, Tag, Monat, Jahr)
bar/barAvg<number><period><timeOffset>
# <number>: Anzahl der Perioden
# <period>: Art der Periode: day, week, month, year, decade
# bei day werden 24 Stunden als Balken dargestellt,
# bei week werden 7 Tage (Mo bis So) der Woche dargestellt,
# bei month werden bis 31 Tage des Monats dargestellt,
# bei year werden 12 Monate des Jahres dargestellt,
# bei decade werden 10 Jahre eines Jahrzehnts (Dekade) dargestellt.
# <timeOffset>: Zeitverschiebung in Sekunden (positive Zahlen in die Zukunft, neg. Zahlen in die Vergangenheit)
# Anmerkung: Im optimalen Fall wird im angegebenen Zeitraum (Stunde (Periode day), Tag (Periode week oder month), Monat (Periode year), Jahr (Periode decade)) nur ein Wert per Event geliefert, werden mehrere Events geliefert, so wird der letzte Wert des Zeitraum übernommen. Bei barAvg werden wird dagegen der Mittelwert der gelieferten Daten einer Periode gebildet.

<output>
# Der Wert des Readings kann über den optionalen output-Parameter mit Hilfe von Perl verändert werden
# Beispiel, der Wert on des Readings soll auf 1 abgebildet werden, sonst auf 0: $_ eq "on" ? 1 : 0

$header # "<Überschrifttext,<Style-SVG-Text-Attribute>", optional
$icon # "Iconname\@Farbe,Skalierungsfaktor,x-Position,y-Position,Rotation", \@Farbe, Skalierungsfaktor, x-Position, y-Position, Rotation sind optional
$min # minimaler Wert, optional, default=0
$max # maximaler Wert, optional, default=100
$minColor # Farbe (hue: 0-360) des kleinsten Wertes, optional, default = 0 (rot)
$maxColor # Farbe (hue: 0-360) des maximalen Wertes, optional, default = 120 (grün)
$desc
# Beschreibung des Wertes, optional, default = undef, falls unter $collect ein Array für mehrere Readings angegeben wurde, so werden hier als Array die entsprechenden Beschreibungen angegeben, zusätzlich kann kommagetrennt pro Einheit Farbe des Graphen angegeben werden

$colorRef
# Referenz auf eine Funktion, die zu einem Wert einen Farbwert (hue: 0-360) bestimmt, oder eine Referenz auf eine Arrayliste mit Grenzwerten und Farben, optional, default = undef

$decFontUnit
# "<Anzahl der Nachkommastellen>,<Style-SVG-Attribute Wert>,<Style-SVG-Attribute Einheit>,<Einheit hinter dem Zahlenwert>", optional

$prop
# Eigenschaft von card: "<size>,<y-scaling>,<steps>,<footer>,<color_y_scale>,<ring>,<width>", optional

# <size>: Größe der der Karte, default = 130,
# <y-scaling>: "fixedscaling" (1), "autoscaling" (undef)
# <steps>: "steps" (1),"nosteps" (undef)
# <footer>: "footer" (undef),"nofooter" (1)
# <color_y_scale>: "ycolor" (undef), "noycolor" (1)
# <ring>: "ring" (undef), "noring" (0), "halfring" (1)
# <width>: Breite der Karte, default: 160

$ringModel
# '<color gradient>,<min/max>,<inner ring>,<pointer>,<mode>'

# <color gradient>: "gradient" (undef),"nogradient" (1)
# <min/max>: Style-SVG-Attribute oder "nominmaxvalue" (undef), "minmaxvalue" (1)
# <inner ring>: Style-SVG-Attribute oder "innerring" (1), "noinnerring" (undef)
# <pointer>: Breite des Zeigers in Pixel, "nopointer" (undef)
# <mode>: "minmax" (undef), "negzeropos" (1), "zeronegpos" (2)
# alle Parameter sind optional, default keine Angaben: ',,,,,,'

$lightness
# Helligkeit einzelner Elemente (0-100) "<ring>,<inner ring>,<minMax>,<unit>,<value>,<icon>", optional, default: "50,50,50,40,50,40"

$collect2 # optionale Angaben für ein zweites Reading
$min # restliche Parameter
$max # entsprechen der Syntax
... # des ersten Sensors
$decFontUnit2 #
</syntaxhighlight>
Wird '''$colorRef''' nicht angegeben, so wird der Farbwert zwischen '''$minColor''' und '''$maxColor''' linear interpoliert
Werden mehrere Readings angegeben, so müssen sie alle die gleiche Zeitspanne besitzen (Zeitangabe bei col)

'''nützliche Links'''
* Anwendungsbeispiel [[DOIF/uiTable_Schnelleinstieg#Visualisierung:_Wetterstation|Wetterstation]]
* Anwendungsbeispiel [[DOIF/uiTable_Schnelleinstieg#Visualisierung:_aktueller_Spritpreis|Spritpreise]]
* Anwendungsbeispiel [[DOIF/uiTable_Schnelleinstieg#Visualisierung_und_Steuerung:_Heiztherme|Heiztherme]]
* svg-Funktion [[DOIF/uiTable_Schnelleinstieg#Farbskalierte_Anzeige_eines_Icons_mit_einem_Zahlenwert_mit_Hilfe_der_universellen_SVG-Funktion_icon_ring.2Ficon_mring.2Ficon_uring|icon_ring]]
}}

=====<big>Darstellung kontinuierlicher Daten als Linie</big>=====
Es folgen einige Beispiele für die Darstellung von Readings mit Hilfe des Darstellungstyps '''col''', deren Werte sich per Event kontinuierlich verändern.

======<big>Darstellung eines Readingwertes</big>======
<syntaxhighlight lang="perl">
defmod di_collect DOIF ##
attr di_collect uiTable {package ui_Table;;}\
card([Aussensensor:temperature:col12],"Außen","temp_outside",-10,45,undef,undef,"°C",\&temp_hue,undef)|\
card([Tankstelle:Diesel:col12],"Sprit,fill:darkorange","fuel","1.00","1.40",120,0,"Diesel €",undef,"2",",,1")\
card([zaehler:l-Produktion:col12],undef,[zaehler:l-Produktion] > 0 ? "sani_solar\@colorVal1":"fa_bolt\@colorVal2",0,3.6,30,60,"PV kW",undef,"1,,font-size:50%")|\
card([ESPEasy_Eingang_CO2:PPM:col12],undef,"air",400,1200,120,0,"ppm",[600,120,1000,60,1200,0],0,undef,'0,1,1',"50,35,45,35,50,35")
</syntaxhighlight>

''Ergebnis der Beispieldefinition in der Webansicht:''
[[Datei:svgcard.png|ohne|mini]]

======<big>Anpassung des Layouts</big>======
<syntaxhighlight lang="perl">
defmod di_cards DOIF {}
attr di_cards uiTable {package ui_Table;;}\
"Standard"|\
card([Aussensensor:temperature:col],undef,"temp_outside",-10,50,undef,undef,"°C",\&temp_hue,"1","130")\
"mit Halbring"|\
card([Aussensensor:temperature:col],"Außen","temp_outside",-10,50,undef,undef,"°C",\&temp_hue,"1","130,,,,,1")\
"mit Halbring","ohne Fußzeile","Breite 110"|\
card([Aussensensor:temperature:col],"Außen","temp_outside",-10,50,undef,undef,"°C",\&temp_hue,"1","130,,,1,,1,110")\
"Standard","Breite 200"|\
card([Aussensensor:temperature:col],"Außen","temp_outside",-10,50,undef,undef,"°C",\&temp_hue,"1","130,,,,,,200")
</syntaxhighlight>

''Ergebnis der Beispieldefinition in der Webansicht:''
[[Datei:di_card_variations.png|ohne|mini]]

======<big>Darstellung zwei Readingwerte mit unterschiedlichen Einheiten</big>======
<syntaxhighlight lang="perl">
defmod di_cards DOIF {}
attr di_cards uiTable {package ui_Table;;}\
"Standard"|\
card([Aussensensor:temperature:col],"Außen","temp_outside",-10,60,undef,undef,"°C",\&temp_hue,"1","130,,,,",undef,undef,[outsensor:humidity:col],0,100,undef,undef,"%",\&hum_hue,"0")\
"ohne Header"|\
card([Aussensensor:temperature:col],undef,"temp_outside",-10,60,undef,undef,"°C",\&temp_hue,"1","130,,,,",undef,undef,[outsensor:humidity:col],0,100,undef,undef,"%",\&hum_hue,"0")\
"ohne Header","ohne Fußzeile"|card([Aussensensor:temperature:col],undef,"temp_outside",-10,60,undef,undef,"°C",\&temp_hue,"1","130,,,1,",undef,undef,[outsensor:humidity:col],0,100,undef,undef,"%",\&hum_hue,"0")\
"Als Halbring"|\
card([Aussensensor:temperature:col],"Außen","temp_outside",-10,60,undef,undef,"°C",\&temp_hue,"1","130,,,,,1",undef,undef,[outsensor:humidity:col],0,100,undef,undef,"%",\&hum_hue,"0")\
"ohne Fußzeile"|\
card([Aussensensor:temperature:col],"Außen","temp_outside",-10,60,undef,undef,"°C",\&temp_hue,"1","130,,,1,,1",undef,undef,[outsensor:humidity:col],0,100,undef,undef,"%",\&hum_hue,"0")
</syntaxhighlight>

''Ergebnis der Beispieldefinition in der Webansicht:''
[[Datei:di_card_collect2.png|ohne|mini]]

======<big>Darstellung mehrerer Readingwerte mit gleicher Einheit</big>======

<syntaxhighlight lang="perl">
defmod Sprit DOIF ##
attr Sprit uiTable {package ui_Table;;}\
card([[Tankstelle:SuperE5:col3d],[Tankstelle:Diesel:col3d]],undef,"fuel\@silver",1.40,1.9,120,0,["E10","Diesel"],undef,"2,,fill:silver, €","130,autoscaling,steps,footer,ycolor,ring,200",undef,undef)
</syntaxhighlight>

''Ergebnis der Beispieldefinition in der Webansicht:''
[[Datei:di_Sprit2.png|ohne|mini]]

<syntaxhighlight lang="perl">
defmod PV DOIF {}
attr PV DOIF_Readings l_Eigenv: [zaehler:l-Produktion]-[zaehler:l-Lieferung],\
Eigenv:[zaehler:Produktion]-[zaehler:Lieferung],\
l_Verbrauch: [zaehler:l-Bezug,0]+[$SELF:l_Eigenv,0],\
Verbrauch:[zaehler:Bezug]+[$SELF:Eigenv],\
l_Bezug:-[zaehler:l-Bezug]
attr PV uiTable {\
package ui_Table;;\
$SHOWNOSTATE=1;;\
}\
card([[zaehler:l-Produktion:col],[$SELF:l_Eigenv:col],[$SELF:l_Bezug:col]],"kW","fa_bolt\@silver",-3.6,3.6,0,90,["Solar","Eigen.","Bezug"],[(-1,0,0,30,1,60,3.6,90)],"2","167,,1,,,1",",,1,6")
</syntaxhighlight>

''Ergebnis der Beispieldefinition in der Webansicht:''
[[Datei:di_card_energie.png|ohne|mini]]

======<big>Darstellung mehrerer Readingwerte mit einfarbigen Graphen</big>======

<syntaxhighlight lang="perl">
defmod di_heating DOIF {}
attr di_heating uiTable {\
package ui_Table;;\
}\
card([[ESPEasy_ESP_Temp_Vorlauf:Temperature:col],[ESPEasy_ESP_Temp_Keller_Ruecklauf:Temperature:col]],"Umwälzpumpe",([vaillant:Pumpenstatus] eq "on" ? "sani_floor_heating\@Darkorange" : "sani_floor_heating_neutral\@white"),15,70,undef,undef,["Vor. °C,red","Rück. °C,#287afc"],\&temp_hue,undef,",,1,,1")
</syntaxhighlight>

''Ergebnis der Beispieldefinition in der Webansicht:''
[[Datei:di_card_pump.png|ohne|mini]]

======<big>Darstellung mehrere Readingwerte mit und ohne Verlaufvisualisierung</big>======
{{Randnotiz|RNText='''card mit Zusatzinformationen, die nicht im Plot erscheinen'''
*Die col-Angabe kann bei Readingsangaben ausgelassen werden, dann werden die Daten dieses Readings nicht gesammelt und erscheinen nur in den Ringen in der Kopfzeile, nicht aber im Hauptring, nicht im Plot und nicht in der Fußzeile. Mindestens ein Reading einer card muss col-Angaben beinhalten.
*Für collect bzw. collect2 können beliebig viele Werte angegeben werden.
*In card gibt es nur einen Hauptring mit einem Wert oder als Doppelring mit zwei Werten, alle weiteren Werte landen als Halbringe in der Kopfzeile. Wenn eine 1 beim Parameter hring angegeben wird, so werden alle Werte als Halbring in der Kopfzeile dargestellt, es gibt dann keinen Hauptring.
*Die ersten beiden Werte mit col-Angaben aus collect werden im Doppelring angezeigt, alle weiteren landen in Halbringen in der Kopfzeile; wenn collect nur einen Wert hat und collect2 mehrere, dann wird der erste Wert von collect und der erste Wert von collect2 im Doppelring angezeigt, die restlichen von collect2 landen in Halbringen der Kopfzeile.
*Bei einer Card mit Standardbreite können maximal 6 Werte angezeigt werden. Zwei im Doppelring und vier in Halbringen in der Kopfzeile. Möchte man mehr als 6 Werte anzeigen, dann muss man die Breite von card vergrößern, damit mehr als vier Halbringe in der Kopfzeile Platz finden.
}}

<syntaxhighlight lang="perl">
defmod di_energie DOIF {}
attr di_energie uiTable {\
package ui_Table;;\
}\
card([[$SELF:power_pv:144col1d],[$SELF:power_fc:144col1d]],"","fa_bolt\@silver",-3.6,3.6,0,90,["PV","Netz"],[(-1,0,-0.01,30,1,60,3.6,90)],"2,,fill:silver, kW","130,,1,0,1","1,,1,0,negzeropos",undef, [[di_counter_new:MQTT2_DVES_C58DCB.total_pv.day],[di_counter_new:MQTT2_DVES_C58DCB.total_c.day],[di_counter_new:MQTT2_DVES_C58DCB.total_f.day]],-25,25,0,90,["PV","Bezug","Einsp."],[(-10,0,-0.01,30,10,60,25,90)],"1,,fill:silver, kWh")
</syntaxhighlight>

''Ergebnis der Beispieldefinition in der Webansicht:''
[[Datei:di_card_energie2.png|ohne|mini]]
<br>
<br>
<br>
<br>
{{Randnotiz|RNText='''card mit Zusatzinformationen, die nicht im Plot erscheinen mit eigenen Formatierungsangaben zum Ring'''

Sollen Zusatzinformationen, die nicht im Plot erscheinen, in der Kopfzeile mit eigenen Formatierungsangaben im Ring dargestellt werden, dann können sie beim $collect/$collec2-Parameter als Array mit zusätzlichen Parametern angegeben werden. Diese Angaben übersteuern die Formatierungsangaben, die für den Hauptring gelten. Die Bedeutung der Parameter entspricht der der card-Parameter.

<syntaxhighlight lang="perl">
Syntax für $collect/$collect2
[...,[[<Device>:<Reading>],$min,$max,$minColor,$maxColor,$desc, $colorRef,$decFontUnit,$ringModel],...]
</syntaxhighlight>

*Beschreibung der Parameter siehe card-Funktion
}}
<syntaxhighlight lang="perl">
defmod di_gas DOIF {}
attr di_gas uiTable {\
package ui_Table;;\
}\
card([[di_counter:gas.day:col1w],[[di_counter:gas.month],0,250,90,0,"Monat","","0,,fill:silver, m³"],[[di_counter:gas.year],0,1500,90,0,"Jahr","","0,,fill:silver, m³"]],"Gas", undef,0,10,90,0,"Tag", undef,"1,,fill:silver, m³","130,1,1,0,1,halfring,180")\
\
card([[di_counter:gas.last_day:bar2month-300],[[di_counter:gas.last_month],0,250,90,0,"letzter","","0,,fill:silver, m³"],[[di_counter:gas.month],0,250,90,0,"Monat","","0,,fill:silver, m³"]],"Gasverbrauch", undef,0,10,90,0,"Tag", undef,"2,,fill:silver, m³","130,1,1,0,1,noring,180")
</syntaxhighlight>

''Ergebnis der Beispieldefinition in der Webansicht:''
[[Datei:di_card_gas.png|ohne|mini]]

<syntaxhighlight lang="perl">
defmod di_wetter DOIF {}
attr di_wetter uiTable {\
package ui_Table;;\
}\
card([Aussen:temperature:col1d],"","temp_outside\@silver",-10,50,undef,undef,"Temp.",\&temp_hue,"1,,fill:silver,°C","130,autoscaling,nosteps,footer,ycolor,ring,200",undef,undef,[[Aussen:humidity:col1d],[[Wetter:WindboeenKm],0,30,90,30,"Wind","","1,,fill:silver, km/h",",,,0"],[[Wetter:LuftdruckHpa],980,1047,30,90,"Luftdr.","","0,,fill:silver, hPa",",,,0"],[[Wetter:RegenGesamtMm],0,50,180,270,"Regen","","1,,fill:silver, mm",",,,0"]],0,100,undef,undef,"Feuchte",\&hum_hue,"0,,fill:silver, %")
</syntaxhighlight>

''Ergebnis der Beispieldefinition in der Webansicht:''
[[Datei:di_card_wetter.png|ohne|mini]]

======<big>Anwendungsbeispiele mit card</big>======
<syntaxhighlight lang="perl">
defmod Aktuell DOIF {}
attr Aktuell alias Übersicht
attr Aktuell uiTable {package ui_Table;;\
\
## $TABLE='vertical-align:top';;\
$TC{0..1} = "style='vertical-align:top'"\
$TABLE='text-align:center;;';;\
## $SHOWNOSTATE=1;;\
}\
## $prop: "<size>,<y-scaling>,<steps>,<noFooter>,<noColor>,<hring>,<width>"\
::sunrise_abs(),::sunset_abs()|"<div class='doifclock'style='font-size:25pt;;color:silver'>wait</div>"<\
style([wetter_com_broich:Ansage],[wetter_com_broich:Ansage] eq "Kein Niederschlag in Sicht" ? "silver":"red")<\
\
card([MQTT2_zigbee_0x048727fffee80c78:temperature:col1d],"","temp_outside\@silver",-10,50,undef,undef,"Temp.",\&temp_hue,"1,,fill:silver,°C","130,,,0,1,,200",undef,undef,[[MQTT2_zigbee_0x048727fffee80c78:humidity:col1d],[[Wetter:WindboeenKm],0,30,90,30,"Wind","","1,,fill:silver, km/h",",,,0"],[[Wetter:LuftdruckHpa],980,1047,30,90,"Luftdr.","","0,,fill:silver, hPa",",,,0"],[[Wetter:RegenGesamtMm],0,10,180,270,"Regen","","1,,fill:silver, mm",",,,0"]],0,100,undef,undef,"Feuchte",\&hum_hue,"0,,fill:silver, %")|\
\
card([[MQTT2_DVES_C58DCB:power_pv:144col1d],[MQTT2_DVES_C58DCB:power_fc:144col1d]],"","fa_bolt\@silver",-3.6,3.6,0,90,["PV","Netz"],[(-1,0,-0.01,30,1,60,3.6,90)],"2,,fill:silver, kW","130,,1,0,1,,200","1,,1,0,negzeropos",undef, [[[di_counter_new:MQTT2_DVES_C58DCB.total_pv.day],0,30,60,90,"PV",[(10,60,30,90)]],[[di_counter_new:MQTT2_DVES_C58DCB.total_f.day],0,30,60,90,"Einsp.",[(10,60,30,90)]],[[di_counter_new:MQTT2_DVES_C58DCB.total_c_positiv.day],0,10,30,0,"Bezug",[(3.3,30,10,0)]],[[di_counter_new:MQTT2_DVES_C58DCB.total_consum.day],0,15,30,0,"Verbr.",[(5,30,15,0)]]],0,10,30,0,["","","",""],[(3,30,10,0)],"1,,fill:silver, kWh") \
\
card([di_counter_new:MQTT2_DVES_C58DCB.total_w.last_day:col4w],undef,"measure_water_meter\@silver",0,600,120,0,"Verbr.",undef,"0,,fill:silver, l","130,autoscaling,1,0,1,,200",undef,undef,[Wasserzisterne:Stand:col4w],0,100,240,180,"Zisterne",undef,"0,,fill:silver, %") |\
\
card([[Tankstelle:SuperE5:col3d],[Tankstelle:Diesel:col3d]],undef,"fuel\@silver",1.40,1.9,120,0,["E10","Diesel"],undef,"2,,fill:silver, €","130,autoscaling,1,0,1,,200",undef,undef)\
\
\
card([[di_counter_new:MQTT2_DVES_C58DCB.total_pv.last_day:bar2month-300],[di_counter_new:MQTT2_DVES_C58DCB.total_c.last_day:bar2month-300]],"Strom",undef,-25,25,0,90,["PV","Bezug"],[(-10,0,-0.01,30,10,60,25,90)],"1,,fill:silver, kWh","130,autoscaling,steps,footer,noycolor,halfring,200","1,,1,0,1",undef) |\
\
card([[di_counter_new:MQTT2_DVES_C58DCB.total_gas.last_day:bar2month-300],\
[[di_counter_new:MQTT2_DVES_C58DCB.total_gas.last_day],0,10,90,0,"gestern","","2,,fill:silver, m³"],\
[[di_counter_new:MQTT2_DVES_C58DCB.total_gas.day],0,10,90,0,"heute","","2,,fill:silver, m³"],[[di_counter_new:MQTT2_DVES_C58DCB.total_gas.month],0,250,90,0,"Monat","","1,,fill:silver, m³"]],"Gas",undef,0,10,90,0,"m³",undef,"2,,fill:silver, m³","130,autoscaling,1,0,1,nohalfring,200",undef,undef)\
\
card([di_tibber:tibber],"Tibber",undef,0,40,90,0,"Cent",undef,"1",",autoscaling,,,noycolor,halfring,200")|\
\
card([[di_counter_new:di_tibber.costsSum.last_day:bar2month-300],[[di_counter_new:di_tibber.costsSum.last_day],0,3,90,0,"gestern","","2,,, €"],[[di_counter_new:di_tibber.costsSum.day],0,3,90,0,"heute","","2,,, €"],[[di_counter_new:di_tibber.costsSum.month],0,80,90,0,"Monat","","2,,, €"]],"Tibber",undef,0,3,90,0,"Euro",undef,"2,,, €","130,autoscaling,,footer,noycolor,nohalfring,200","0,0,0,0,2") \
\
\
card([[MQTT2_sbfspot:PDC1:144col1d],[MQTT2_sbfspot:PDC2:144col1d]],"PV Leistung",undef,0,3300,40,100,["PDC1,yellow","PDC2,#FF5F1F"],undef,"0,,fill:silver, W","130,autoscaling,steps,footer,noycolor,halfring,200","1,,1,0,1",undef)|\
\
card([[MQTT2_sbfspot:IDC1:144col1d],[MQTT2_sbfspot:IDC2:144col1d]],"PV Strom",undef,0,8.5,40,100,["IDC1,yellow","IDC2,#FF5F1F"],undef,"3,,, A","130,autoscaling,steps,footer,noycolor,halfring,200","1,,1,0,1",undef)
</syntaxhighlight>

''Ergebnis der Beispieldefinition in der Webansicht:''
[[Datei:di_card_uebersicht.png|ohne|500px]]

=====<big>Darstellung fortlaufender Daten als Säulen</big>=====
Die Darstellung von fortlaufenden Daten kann mit Hilfe von Säulendiagrammen über den Darstellungstyp '''bar''' oder '''barAvg''' erfolgen. Werden die Reading-Werte innerhalb der definierten Periode öfters geschrieben, so wird bei der Angabe '''bar''' der letzte Wert des jeweiligen Zeitraums übernommen, bei der Angabe '''barAvg''' wird dagegen der Mittelwert der Werte gebildet und als Säule dargestellt. Die Werte der aktuellen Periode werden in hellen Farben dargestellt, die der vorherigen Perioden sind abgedunkelt. Der aktuelle Tag wird im Diagramm gekennzeichnet. Ebenso wird der minimale, maximale und der durchschnittlicher Wert errechnet und im Diagramm per Symbol bzw. Linie gekennzeichnet.
======<big>Energieverbrauch verschiedener Zeiträume</big>======
{{Randnotiz|RNText='''nützliche Links'''
* [https://wiki.fhem.de/wiki/DOIF/uiTable_Schnelleinstieg#Anzeige_eines_Werteverlaufs_und_des_aktuellen_Wertes_mit_Hilfe_der_SVG-Funktion_card siehe Syntax zu bar/barAvg beim card-Parameter <collect type>]
* [https://wiki.fhem.de/wiki/DOIF/Automatisierung#Tages-.2C_Monats-_und_Jahresstatistik_f.C3.BCr_Strom-.2C_Gas-.2C_Wasserz.C3.A4hler_und_andere_Z.C3.A4hler siehe Statistik zu Zählerdaten mit Visualisierung]
}}
<syntaxhighlight lang="perl">
defmod di_energie DOIF {}
attr di_energie uiTable {package ui_Table}\
"Darstellung eines Monats"|"Darstellung eines Jahres"|"Darstellung einer Dekade"\
card([di_counter_new:MQTT2_DVES_C58DCB.total_gas.last_day:bar1month],"Gas in m³ pro Tag",undef,0,10,90,0,"m³",undef,"1","130,1,1,0,1,0,200")|\
card([di_counter_new:MQTT2_DVES_C58DCB.total_gas.last_month:bar1year],"Gas in m³ pro Monat",undef,0,100,90,0,"m³",undef,"0","130,1,1,0,1,0,200")|\
card([di_counter_new:MQTT2_DVES_C58DCB.total_gas.last_year:bar1decade],"Gas in m³ pro Jahr",undef,0,20000,90,0,"m³",undef,"0","130,1,1,0,1,0,200")\
"Darstellung einer Woche"|"Darstellung zwei Wochen"|"Darstellung vier Wochen"\
card([di_counter_new:MQTT2_DVES_C58DCB.total_gas.last_day:bar1week],"Gas in m³ pro Tag",undef,0,10,90,0,"m³",undef,"1","130,1,1,0,1,0,200")|\
card([di_counter_new:MQTT2_DVES_C58DCB.total_gas.last_day:bar2week],"Gas in m³ pro Tag",undef,0,10,90,0,"m³",undef,"1","130,1,1,0,1,0,200")|\
card([di_counter_new:MQTT2_DVES_C58DCB.total_gas.last_day:bar4week],"Gas in m³ pro Tag",undef,0,10,90,0,"m³",undef,"1","130,1,1,0,1,0,200")\
"Darstellung von zwei Werten"|"Darstellung mit Halbringen"|"Darstellung von zwei Monaten"\
card([[di_counter_new:MQTT2_DVES_C58DCB.total_pv.last_day:bar1month],[di_counter_new:MQTT2_DVES_C58DCB.total_c.last_day:bar1month]],"Elektrizität in kWh pro Tag",undef,-15,15,0,90,["Ertrag","Bezug"],undef,"1","130,1,1,0,1,0,200","0,0,0,0,2")|\
card([[di_counter_new:MQTT2_DVES_C58DCB.total_pv.last_day:bar1month],[di_counter_new:MQTT2_DVES_C58DCB.total_c.last_day:bar1month]],"kWh pro Tag",undef,-15,15,0,90,["Ertrag","Bezug"],undef,"1","130,1,1,0,1,halfring,200")|\
card([[di_counter_new:MQTT2_DVES_C58DCB.total_pv.last_day:bar2month],[di_counter_new:MQTT2_DVES_C58DCB.total_c.last_day:bar2month]],"kWh pro Tag",undef,-15,15,0,90,["Ertrag","Bezug"],undef,"1","130,1,1,0,1,halfring,200")
</syntaxhighlight>
''Ergebnis der Beispieldefinition in der Webansicht:''
[[Datei:di_energie_bar.png|ohne|800px]]

=====<big>Import, Änderung und Löschung von Diagrammdaten</big>=====
{{Randnotiz|RNText='''card-data-Funktionen'''

Gesammelte card-Daten löschen.
<syntaxhighlight lang="perl">
DOIF_delete_card_data (<card device>,<reading device>,<reading>,<col/bar specification>)
</syntaxhighlight>

Daten aus einer Logdatei oder einer Liste übernehmen. Vorhandene card-Daten werden zuvor gelöscht.
<syntaxhighlight lang="perl">
DOIF_set_card_data (<card device>,<reading device>,<reading>,<col/bar specification>,<time offset>,<data list>)
</syntaxhighlight>

Daten aus einer Logdatei oder einer Liste übernehmen. Vorhandene card-Daten werden zuvor nicht gelöscht.
<syntaxhighlight lang="perl">
DOIF_modify_card_data (<card device>,<reading device>,<reading>,<col/bar specification>,<time offset>,<data list>)
</syntaxhighlight>
<syntaxhighlight lang="perl">
#<card device> DOIF-Device, wo die Definition der zu sammelnden Daten vorgenommen wurde
#<reading device> Device des Readings
#<reading> Readingname
#<col/bar specification> die dazugehörige Spezifikation des collect Typs, z. B. "col1w", "bar1month" usw.
#<time offset> Angabe in Sekunden.
Der Zeitstempel der Daten wird zeitlich (positiv - in die Zukunft, negativ - in die Vergangenheit) verschoben. Damit kann man erreichen, dass Daten, die nach Mitternacht entstanden sind, dem Tag zuvor zugeordnet werden (negative Sekundenangabe).
#<data list> Liste von Datensätzen, die importiert werden sollen
das Format eines Datensatzes ist:
#YYYY.MM.DD_HH:MM:SS<separator><value>, mit
#<separator> Leerzeichen oder Semikolon
#<value> Zahl
#ebenfalls ist das deutsche Zeitformat erlaubt
#DD.MM.YYYY HH:MM:SS
Die Datensätze können durch Komma oder Zeilenumbruch (newline) voneinander getrennt werden. Werden Zahlen mit Komma statt mit Punkt angegeben, so müssen die Datensätze durch Zeilenumbrüche getrennt werden.
Bei Datumsangaben kann der Tag und der Monat weggelassen werden, ebenfalls können Zeitangaben weggelassen werden.
Beispiel: "2023.02.21_15:01 10,2023.02.21 20,2023 15" oder "15.02.2023 15:01 10,21.02.2023 20,2023 15"
Die Liste kann ebenfalls von einer Funktion geliefert werden, wie z. B. Filelog oder DOIF_get_file_data.
</syntaxhighlight>
}}
Die Daten der zu visualisierenden Readings werden event-gesteuert im DOIF-Device gesammelt und in versteckten Readings gespeichert. Bei Neudefinition von card oder nach einem Systemcrash kann es sinnvoll sein, vorhandene Daten aus dem Log oder einer Liste für die Visualisierung zu übernehmen. Ebenfalls können gesammelte Daten gelöscht oder einzeln modifiziert werden. All das lässt sich mit den card-data-Funktionen umsetzen.

'''Beispiele'''

Ausgangssituation: Im DOIF-Device '''di_pv''' werden Daten mit Angabe '''[energie:pv:col4w]''' über card-Funktion visualisiert.

Löschen der visualisierten Daten:
<syntaxhighlight lang="perl">
DOIF_delete_card_data ("di_pv","energie","pv","col4w")
</syntaxhighlight>

Übernehmen von Daten eines bestimmten Zeitraums aus dem Log namens '''pv.energie.log''', dort wurden die Daten des Readings '''pv''' geloggt:

<syntaxhighlight lang="perl">
DOIF_set_card_data ("di_pv","energie","pv","col4w",0,fhem("get pv.energie.log - - 2022-11-01 2023-02-03 4:pv"))
</syntaxhighlight>

get-Filelog-Syntax bitte in der Dokumentation zu Filelog entnehmen.

Statt Log-Daten können ebenfalls Daten in einer kommagetrennten Liste angegeben übernommen werden.

Es sollen zwei Datensätze übernommen werden:

<syntaxhighlight lang="perl">
DOIF_modify_card_data ("di_pv","energie","pv","col4w",0,"2023.02.04_11:00 10,2023.02.04_11:02 5.6")
</syntaxhighlight>

Eine Liste aus einer Datei, z. B. aus einer csv-Excel-Datei, kann mit der Funktion '''DOIF_get_file_data (<file>)''' übernommen werden. Dabei ist es unerheblich, ob die Daten im deutschen oder im internationalen Zeitformat vorliegen, ebenso wird das Kommazeichen statt Punkt bei Zahlen erkannt.

Ausgangssituation: Die Datei ''gas_jan.csv'' wurde in das log-Verzeichnis kopiert. Sie beinhaltet u.a. folgende Datensätze (Nachkommastellen wurden mit Komma getrennt):

<syntaxhighlight lang="perl">
2023;4,142
02.01.2023 00:01:00;5,159
03.01.2023 00:01;3,170
04.01.2023;5,420
</syntaxhighlight>

Der Import der Daten:

<syntaxhighlight lang="perl">
DOIF_set_card_data ("di_pv","energie","pv","col4w",0,DOIF_get_file_data("./log/gas_jan.csv")))
</syntaxhighlight>

=====<big>card im Status des Originaldevices</big>=====
Soll im Status des Originaldevices eine Visualisierung mit Hilfe der card-Funktion vorgenommen werden, so kann wie folgt vorgegangen werden.

Definition eines DOIF-Devices mit dem Attribut DOIF_Readings zum Sammeln der zu visualisierenden Daten.

Beispieldefintion für fünf Readings aus unterschiedlichen Devices:

<syntaxhighlight lang="perl">
defmod di_collect DOIF {}
attr di_collect DOIF_Readings temperature:[Aussen:temperature:col2d],\
humidity:[Aussen:humidity:col2d],\
co2:[MQTT2_DVES_D90D08:MHZ19B_CarbonDioxide:col2d],\
SuperE5:[Tankstelle:SuperE5:col3d],\
Diesel:[Tankstelle:Diesel:col3d],\
full:[GasInStorageDE:full:bar1month]
</syntaxhighlight>

Im ursprünglichen Device wird jeweils über das Attribut devStateIcon der Aufruf von card vorgenommen:

<syntaxhighlight lang="perl">
defmod Aussen CUL_WS 5
attr Aussen alias Schuppen
attr Aussen devStateIcon {ui_Table::card(ReadingsVal("di_collect","temperature",""),undef,"temp_outside\@silver",-10,50,undef,undef,"°C",\&ui_Table::temp_hue,"1,,fill:silver","130,,,0,1,,",undef,undef,ReadingsVal("di_collect","humidity",""),0,100,undef,undef,"%",\&ui_Table::hum_hue,"0,,fill:silver")}

defmod GasInStorageDE JsonMod https://agsi.gie.eu/api?country=de&date=now
attr GasInStorageDE comment Status: \
E - Estimated - Geschätzt\
C - Confirm - Bestätigt
attr GasInStorageDE devStateIcon {ui_Table::card(ReadingsVal("di_collect","full",""),undef,"",0,100,0,120,"full in %",undef,"1",",fixedscaling,,,,halfring")}
attr GasInStorageDE httpHeader x-key: 08154711
attr GasInStorageDE interval 0 6 * * *
attr GasInStorageDE readingList single(jsonPath('$.gas_day'), 'gas_Day', 'N/A');;\
single(jsonPath('$.data.0.gasInStorage'), 'gasInStorage', 'N/A');;\
single(jsonPath('$.data.0.consumption'), 'consumption', 'N/A');;\
single(jsonPath('$.data.0.consumptionFull'), 'consumptionFull', 'N/A');;\
single(jsonPath('$.data.0.injection'), 'injection', 'N/A');;\
single(jsonPath('$.data.0.withdrawal'), 'withdrawal', 'N/A');;\
single(jsonPath('$.data.0.workingGasVolume'), 'workingGasVolume', 'N/A');;\
single(jsonPath('$.data.0.injectionCapacity'), 'injectionCapacity', 'N/A');;\
single(jsonPath('$.data.0.withdrawalCapacity'), 'withdrawalCapacity', 'N/A');;\
single(jsonPath('$.data.0.status'), 'status', 'N/A');;\
single(jsonPath('$.data.0.trend'), 'trend', 'N/A');;\
single(jsonPath('$.data.0.full'), 'full', 'N/A');;

defmod Tankstelle HTTPMOD http://www.clever-tanken.de/tankstelle_details/24198 300
attr Tankstelle devStateIcon {ui_Table::card([ReadingsVal("di_collect","SuperE5",""),ReadingsVal("di_collect","Diesel","")],undef,"fuel\@silver","1.50","2.00",120,0,["E10","Diesel"],undef,"2,,fill:silver","130,1,1,0,1",undef,undef)}
attr Tankstelle enableControlSet 1
attr Tankstelle event-on-change-reading .*
attr Tankstelle reading01Name Diesel
attr Tankstelle reading01Regex "current-price-1">(\d.\d{2})
attr Tankstelle reading02Name SuperE5
attr Tankstelle reading02Regex "current-price-2">(\d.\d{2})
attr Tankstelle timeout 10

defmod MQTT2_DVES_D90D08 MQTT2_DEVICE DVES_D90D08
attr MQTT2_DVES_D90D08 devStateIcon {ui_Table::card(ReadingsVal("di_collect","co2",""),undef,"air\@silver",400,1200,120,0,"ppm",[(600,120,1000,60,1200,0)],"0,,fill:silver","130,autoscaling,nosteps,footer,noycolor",'nogradient,nominmaxvalue,innerring,nopointer,minmax')}
</syntaxhighlight>

Die Visualisierung wird automatisch aktualisiert. Mit Hilfe dieser Vorgehensweise lassen sich cards über den Status des jeweiligen Devices oder den direkten Aufruf der card-Funktion auch in anderen Frontends wie z. B. Floorplan oder TabletUI darstellen.

''Ergebnis der Beispieldefinition in der Webansicht:''
[[Datei:card_im_Status.png|ohne|mini]]

====<big>3d-Balkendarstellung mehrerer Zahlenwerten mit Hilfe der universellen SVG-Funktion '''cylinder/cylinder_s''' </big> ====
Es können mehrere Zahlenwerte mit Legende farbig in Balkenform visualisiert werden. Negative Werte werden als Balken nach unten dargestellt, positive nach oben, der Nullpunkt wird automatisch berechnet. Bei cylinder_s werden die Balken aufeinander gestapelt.
{{Randnotiz|RNText=SVG-uiTable-Funktion '''cylinder/cylinder_s'''
<syntaxhighlight lang="perl">
cylinder/cylinder_s ($header,$min,$max,$unit,$width,$height,$size,$dec,($value1,$color1,$text1),($value2,$color2,$text2),...

$header # Überschrift
$min # minimaler Wert, optional, default = 0
$max # maximaler Wert, optional, default = 100
$unit # Einheit des Wertes, optional, default = undef
$width # Breite der Grafik, optional, default = wird bei Beschriftungen automatisch angepasst
$height # Höhe der Grafik, optional, default = wird automatisch berechnet
$size # Größe der Grafik, optional, default = 100
$dec # Anzahl der Nachkommastellen, optional, default=1
$value1 # erster Zahlenwert
$color1 # HSL-Farbe des ersten Balkens: "<hue>.<saturation>.<lightness>" (hue:0-360,saturation:0-100,lightness:0-100), saturation (default:100) und lightness (default:50) sind optional
$text1 # Beschriftung des Zahlenwertes in der Legende, optional, default = undef
$value2 # zweiter Zahlenwert, optional
$color2 # HSL-Farbe des zweiten Balkens: "<hue>.<saturation>.<lightness>" (hue:0-360,saturation:0-100,lightness:0-100), saturation (default:100) und lightness (default:50) sind optional
$text2 # Beschriftung des Zahlenwertes in der Legende, optional, default = undef
...
Es können weitere Zahlenwerte jeweils mit Farbe und Beschriftung optional angegeben werden
</syntaxhighlight>
}}
=====<big>cylinder mit verschiedenen Layouts</big>=====
<syntaxhighlight lang="perl">
defmod di_cylinder DOIF ##
attr di_cylinder room Test,wiki
attr di_cylinder uiTable {package ui_Table}\
"normal"|cylinder("",0,100,"%",80,undef,undef,0,[Wasserzisterne:state],200,undef)\
\
"mit Überschrift"|cylinder("Zisterne",0,100,"%",80,undef,undef,0,[Wasserzisterne:state],200,undef)\
\
"kleiner"|cylinder("Zisterne",0,100,"%",80,undef,80,0,[Wasserzisterne:state],200,undef)\
\
"hoch"|cylinder("Zisterne",0,100,"%",undef,100,undef,0,[Wasserzisterne:state],200,undef)\
\
"mit Beschriftung"|cylinder("Zisterne",0,100,"%",undef,100,undef,0,[Wasserzisterne:state],200,"Wasserstand")\
\
"mit mehreren Informationen"|cylinder("Energie",-20,30,"kWh",undef,undef,undef,1,[zaehler:Bezug],0,"Bezug",[zaehler:Produktion],60,"Produktion",[zaehler:Eigenverbrauch],30,"Eigenverbrauch")\
\
"mit hellen Farben"| cylinder("Tag",0,100,"kWh",undef,undef,undef,1,[Heizenergie:Tagesverbrauch_hc]/100000,"30.100.70","letzter",[Heizenergie:heute_hc]/100000,"60.100.70","aktuell")
</syntaxhighlight>
''Ergebnis der Beispieldefinition in der Webansicht:''
[[Datei:cylinder_bsp.png|ohne|mini]]

=====<big>Gestapelte Werte mit cylinder_s</big>=====
Gegenüberstellung cylinder und cylinder_s
[[Datei:cylinder_s.png|ohne|mini]]

====<big>Balkendarstellung mehrerer Zahlenwerte mit Hilfe der universellen SVG-Funktion '''cylinder_bars''' </big>====
Es können mehrere Zahlenwerte mit Legende farbig in Balkenform visualisiert werden. Negative Werte werden als Balken nach unten dargestellt, positive nach oben, der Nullpunkt wird automatisch berechnet. Die '''cylinder_bars'''-SVG-Funkton besitzt die gleichen Argumente, wie die obige '''cylinder'''-SVG-Funktion, mehrerer Balken werden jedoch nicht übereinander, sondern nebeneinander dargestellt.
{{Randnotiz|RNText=SVG-uiTable-Funktion '''cylinder_bars'''
<syntaxhighlight lang="perl">
cylinder_bars ($header,$min,$max,$unit,$width,$height,$size,$dec,($value1,$color1,$text1),($value2,$color2,$text2),...

$header # Überschrift
$min # minimaler Wert, optional, default = 0
$max # maximaler Wert, optional, default = 100
$unit # Einheit des Wertes, optional, default = undef
$width # Breite der Grafik, optional, default = wird bei Beschriftungen automatisch angepasst
$height # Höhe der Grafik, optional, default = wird automatisch berechnet
$size # Größe der Grafik, optional, default = 100
$dec # Anzahl der Nachkommastellen, optional, default=1
$value1 # erster Zahlenwert
$color1 # HSL-Farbe des ersten Balkens: "<hue>.<saturation>.<lightness>" (hue:0-360,saturation:0-100,lightness:0-100), saturation (default:100) und lightness (default:50) sind optional
$text1 # Beschriftung des Zahlenwertes in der Legende, optional, default = undef
$value2 # zweiter Zahlenwert, optional
$color2 # HSL-Farbe des zweiten Balkens: "<hue>.<saturation>.<lightness>" (hue:0-360,saturation:0-100,lightness:0-100), saturation (default:100) und lightness (default:50) sind optional
$text2 # Beschriftung des Zahlenwertes in der Legende, optional, default = undef
...
Es können weitere Zahlenwerte jeweils mit Farbe und Beschriftung optional angegeben werden
</syntaxhighlight>
* [https://wiki.fhem.de/wiki/DOIF/uiTable_Schnelleinstieg#Darstellung_fortlaufender_Daten_als_S.C3.A4ulen siehe auch card bar]
}}
'''<big>Beispieldefinition</big>'''
<syntaxhighlight lang="perl">
defmod di_wasserverbrauch DOIF ##
attr di_wasserverbrauch uiTable {package ui_Table;;}\
cylinder_bars("Monat",0,15,"m³",undef,undef,undef,1,[Wasserverbrauch:monatsdurchschnitt],30,"Durchschnitt",[Wasserverbrauch:monatsverbrauch]/1000,220,"letzter",[Wasserverbrauch:monat]/1000,180,"aktuell")\
\
cylinder_bars("Monat",0,15,"m³",undef,undef,undef,1,[Wasserverbrauch:jan],30,"Januar",[Wasserverbrauch:feb],220,"Februar",[Wasserverbrauch:mrz],180,"März",[Wasserverbrauch:apr],30,"April",[Wasserverbrauch:mai],220,"Mai",[Wasserverbrauch:jun],180,"Juni",[Wasserverbrauch:jul],30,"Juli",[Wasserverbrauch:aug],220,"August",[Wasserverbrauch:sep],180,"September",[Wasserverbrauch:okt],30,"Oktober",[Wasserverbrauch:nov],220,"November",[Wasserverbrauch:dez],180,"Dezember")
</syntaxhighlight>
''Ergebnis der Beispieldefinition in der Webansicht:''
[[Datei:cylinder_bars_bsp.png|ohne|mini]]

====<big>SVG-Grafiken beim Überstreichen mit dem Mauszeiger vergrößern</big>====
Eine SVG-Grafik lässt sich beim Überstreichen mit dem Mauszeiger vergrößert darstellen. Dazu kann die hover-HTML-Eigenschaft genutzt werden.

Im Css-Attribut des FHEMWEB-Devices wird für diesen Zweck folgende Zeile eingefügt:

<syntaxhighlight lang="perl">
svg:hover {transition: transform 0.3s ease; transform: scale(2.0); transform-origin: 0 0;z-index: 9999; position:relative}
</syntaxhighlight>

Sollen nur bestimmte SVG-Grafiken vergrößert werden, so muss deren Klasse angegeben werden. Mögliche Klassen sind: DOIF_card, DOIF_ring, DOIF_bar, DOIF_cylinder.

Es sollen nur Cards vergrößert werden:

<syntaxhighlight lang="perl">
.DOIF_card:hover {transition: transform 0.3s ease; transform: scale(2.0); transform-origin: 0 0;z-index: 9999; position:relative}
</syntaxhighlight>

Es können ebenfalls mehrere Klassen mit Komma angegeben werden. Cards und Ringe sollen vergrößert werden:

<syntaxhighlight lang="perl">
.DOIF_card:hover,.DOIF_ring:hover {transition: transform 0.3s ease; transform: scale(2.0); transform-origin: 0 0;z-index: 9999; position:relative}
</syntaxhighlight>

Da es sich um eine allgemeingültige CSS-Definition handelt, können mit CSS-Kenntnissen durch Anpassung der Definition ebenfalls auch andere Transformationen der Grafiken vorgenommen werden.

Auf Tablets und Smartphones wird im Browser die hover-Eigenschaft oft durch Antippen der Grafik ausgelöst.

''Ergebnis der Beispieldefinition in der Webansicht eines PCs:''
[[Datei:hover.gif|ohne]]

=== Einfache uiTable-Funktionen ===
==== Farbskalierte Temperaturanzeige mit Hilfe der Funktion '''temp''' ====
Die Farbe der dargestellten Temperatur ist abhängig vom Temperaturwert:
[[Datei:Farbskalierung temp.png|600px|ohne]]
{{Randnotiz|RNText=uiTable-Funktion '''temp'''
<syntaxhighlight lang="perl">
temp ($temp,$size,$icon)

$temp # Temperatur
$size # Schriftgröße in Pixel (pt), optional
$icon # Icon, welches vorangestellt wird, optional
</syntaxhighlight>
}}
'''<big>Beispieldefinition</big>'''
<syntaxhighlight lang="perl">
defmod di_uiTable_temp DOIF ##
attr di_uiTable_temp uiTable {\
package ui_Table;; ## Package für uiTable-Funktionen\
$TC{0..2}="align='center'";; ## zentrierte Darstellung aller Tabellenspalten\
}\
## Tabellendefinition\
\
"Aussen"|"Bad"|"Warmwasser" ## mit | werden Tabellenzellen voneinander getrennt \
temp([Aussensensor:temperature])| ## Anzeige des Readings 'temperature' des Gerätes 'Aussensensor' \
temp([TH_Bad_HM:measured-temp],24,"temp_temperature")| ## Schriftgröße 24pt, mit Icon namens temp_temperature\
temp([T_Warmwasserspeicher:temperature:d1],20) ## Schriftgröße 20pt
</syntaxhighlight>
''Ergebnis der Beispieldefinition in der Webansicht:''
[[Datei:Temp.png|ohne|mini]]

==== Farbskalierte Feuchtigkeitsanzeige mit Hilfe der Funktion '''hum''' ====
Die Farbe der dargestellten Feuchtigkeit ist abhängig vom Feuchtigkeitswert:
[[Datei:Farbskalierung hum.png|350px|ohne]]
{{Randnotiz|RNText=uiTable-Funktion '''hum'''
<syntaxhighlight lang="perl">
hum ($hum,$size,$icon)

$hum # Feuchtigkeit
$size # Schriftgröße in Pixel (pt), optional
$icon # Icon, welches vorangestellt wird, optional
</syntaxhighlight>
}}
'''<big>Beispieldefinition</big>'''
<syntaxhighlight lang="perl">
defmod di_uiTable_hum DOIF ##
attr di_uiTable_hum uiTable {\
package ui_Table;;\
$TC{1}="align='center'";; ## zweite Spalte der Tabelle zentriert\
}\
## Tabellendefinition \
\
## Anzeige des Readings 'humidity' des Thermostats 'TH_Bad_HM' \
"Bad"|hum ([TH_Bad_HM:humidity])\
\
## Feuchtigkeit in Größe 10pt mit Temperatur in einer Tabellenzelle\
"Aussen"|temp ([Aussensensor:temperature]),hum ([Aussensensor:humidity],10)\
\
## Feuchtigkeit in Größe 26pt mit Icon namens 'temperature_humidity'\
"Keller"|hum ([TH_Keller_HM:humidity],26,"temperature_humidity")
</syntaxhighlight>
''Ergebnis der Beispieldefinition in der Webansicht:''
[[Datei:UiTable Funktion hum.png|ohne|mini]]

==== Textformatierungen mit Hilfe der Funktion '''style''' ====
Texte werden in Farbe, Größe und Schriftart statisch oder dynamisch formatiert.
{{Randnotiz|RNText=uiTable-Funktion '''style'''
<syntaxhighlight lang="perl">
style ($text,$color,$font_size,$font_weight)

$text # anzuzeigender Text
$color # CSS color, optional
$font_size # Schriftgröße in Pixel (pt), optional
$font_weight # CSS Schriftart, optional
</syntaxhighlight>
Mögliche Werte für '''''color''''' und '''''font_weight''''' können in einschlägiger Dokumentation zu CSS nachgeschlagen werden
}}
'''<big>Beispieldefinition</big>'''
<syntaxhighlight lang="perl">
defmod di_uiTable_style DOIF ##
attr di_uiTable_style uiTable {\
package ui_Table;;\
}\
## Tabellendefinition\
\
## statische Farbgebung, Größe, Schriftart \
style("Montag","orange")\
style("Dienstag","red",14)\
style("Mittwoch","#00FFFF",20)\
style("Donnerstag","blue",23,"bold")\
\
## dynamische Farbgebung abhängig vom Zustand des Gerätes 'Alarm'\
style("Alarm",([Alarm:state] eq "on" ? "red":"green"))\
\
## dynamische Farbgebung des Zustands des Gerätes 'Alarm'\
style([Alarm:state],([Alarm:state] eq "on" ? "red":"green"))\
\
## variabler Text abhängig vom Zustand des Gerätes 'Alarm'\
style(([Alarm:state] eq "on" ? "Alarm aktiv":"Alarm deaktiviert"),"red")
</syntaxhighlight>
''Ergebnis der Beispieldefinition in der Webansicht:''
[[Datei:Style.png|ohne|mini]]

==== Icon-Darstellung mit Hilfe der Funktion '''ICON''' ====
Mit Hilfe der Funktion '''ICON''' kann ein FHEM-Icon dargestellt werden
{{Randnotiz|RNText=uiTable-Funktion '''ICON'''
<syntaxhighlight lang="perl">
ICON ($icon)

$icon # Icon mit Farbgebung
</syntaxhighlight>

'''ICON''' benutzt die Funktion [[DevelopmentFHEMWEB-API#FW_makeImage|FW_makeImage]]

'''nützliche Links'''
* [[DOIF/uiTable Schnelleinstieg#hsv-Funktion für Farbskalierungen|hsv-Funktion]]
}}
'''<big>Beispieldefinition</big>'''
<syntaxhighlight lang="perl">
defmod di_Table_ICON DOIF ##
attr di_Table_ICON uiTable {\
package ui_Table;;\
}\
## Tabellendefinition\
ICON("temp_frost") | ## Icon ohne Einfärbung\
ICON("temp_frost\@blue") | ## Icon in CSS-Farbe blau\
ICON("temp_frost\@#8A2BE2") | ## Icon in CSS-Farbe #8A2BE2\
ICON("temp_frost\@".([Aussensensor:temperature] > 0 ? "orange":"blue"))| ## Icon in CSS-Farbe orange über Null Grad, sonst in CSS-Farbe blau\
ICON("temp_frost\@".hsv ([Aussensensor:temperature],-20,40,320,0)) ## Icon in Farbskalierung von violett (-20 °C) bis rot (40 °C) mit Hilfe der Funktion hsv
</syntaxhighlight>
''Ergebnis der Beispieldefinition in der Webansicht:''
[[Datei:UiTable_IC.png|mini|ohne]]

==== Icon-Darstellung mit Text mit Hilfe der Funktion '''icon_label''' ====
Mit Hilfe der Funktion '''icon_label''' kann ein FHEM-Icon mit einem angehängten Text/Wert dargestellt werden.
{{Randnotiz|RNText=uiTable-Funktion '''icon_label'''
<syntaxhighlight lang="perl">
icon_label ($icon,$text,$color,$color_bg,$pos_left,$pos_top)
$icon # FHEM-Icon mit Farboption
$text # dargestellter Text
$color # Farbe des Textes, optional
$color # Hintergrundfarbe des Textes, optional
$pos_left # horizontale Position des Textes in px, default -5, optional
$pos_top # vertikale Position des Textes in px, default -8, optional
</syntaxhighlight>

'''Anwendungsbeispiele'''
* [[DOIF/uiTable Schnelleinstieg#Anzahl der Tage bis zur Abfall-Entsorgung|Abfall]]
* [[DOIF/uiTable Schnelleinstieg#Visualisierung: aktueller Spritpreis|Sprit]]
}}
'''<big>Beispieldefinition</big>'''
<syntaxhighlight lang="perl">
defmod di_uiTable_icon_label DOIF ##
attr di_uiTable_icon_label uiTable { package ui_Table;;\
}\
\
icon_label("fuel",[Tankstelle:Diesel])|\
icon_label("fuel",[Tankstelle:Diesel],"red")|\
icon_label("fuel\@blue",[Tankstelle:Diesel],"blue","#999999")|\
icon_label("fuel\@red",[Tankstelle:Diesel],"red","white",-10)|\
icon_label("fuel",[Tankstelle:Diesel],"white","red",-5,8)\

</syntaxhighlight>
''Ergebnis der Beispieldefinition in der Webansicht:''
[[Datei:UiTable_icon_label.png|mini|ohne]]

==== Visualisierung eines Gerätes mit Hilfe der Funktion '''icon''' ====
Der Zustand eines Gerätes/Readings wird mit Hilfe eines Icons dargestellt.
{{Randnotiz|RNText=uiTable-Funktion '''icon'''
<syntaxhighlight lang="perl">
icon ($value,$icon_off,$icon_on,$state_off,$state_on)

$value # Wert
$icon_off # Icon für den Wert off, default "off"
$icon_on # Icon für den Wert on, default Icon für Wert 'off' in Farbe 'DarkOrange', sonst Icon 'on', wenn $icon_off nicht definiert ist
$state_off # Wert zugehörig zum Icon off, default "off"
$state_on # Wert zugehörig zum Icon on, default "on"
</syntaxhighlight>
}}
'''<big>Beispieldefinition</big>'''
<syntaxhighlight lang="perl">
defmod di_uiTable_icon DOIF ##
attr di_uiTable_icon uiTable {\
package ui_Table;;\
}\
## Tabellendefinition\
\
## Standard-Icon off/on für Standardwert off/on \
"Lampe"|icon([Lampe:state]) ## entspricht icon([Lampe:state],"off","on","off","on")\
\
## Icon für Zustand 'off' ist 'hue_room_hallway', für Zustand 'on' 'hue_room_hallway\@DarkOrange'\
"Flur"|icon([Lampeflur:state],"hue_room_hallway") ## entspricht icon([Lampeflur:state],"hue_room_hallway","hue_room_hallway\DarkOrange","off","on")\
\
## Icon für Zustand 'off' ist 'status_away_2', für Zustand 'on' 'status_available\@DarkOrange'\
"Anwesenheit"|icon([Anwesenheit:state],"status_away_2","status_available\@DarkOrange") \
\
## Icon für Zustand 'closed' ist "status_locked", für Zustand 'open' 'status_open\@DarkOrange'\
"Haus"|icon([Schloss:state],"status_locked","status_open\@DarkOrange","closed","open")
</syntaxhighlight>
''Ergebnis der Beispieldefinition in der Webansicht:''
[[Datei:UiTable icon.png|mini|ohne]]

==== Schaltbares Icon mit Hilfe der Funktion '''switch''' ====
Der Zustand eines Gerätes/Readings wird mit Hilfe eines Icons dargestellt, er kann über die WEB-Oberfläche durch Anklicken geschaltet werden. Damit der Zustand des Gerätes geschaltet werden kann, muss das Gerät den set-Befehl unterstützen.

{{Randnotiz|RNText=uiTable-Funktion '''switch'''
<syntaxhighlight lang="perl">
switch ($value,$icon_off,$icon_on,$state_off,$state_on)

$value # [<device>:<reading>]
$icon_off # Icon für den Wert off, default "off"
$icon_on # Icon für den Wert on, default Icon für Wert 'off' in Farbe 'DarkOrange', sonst Icon 'on', wenn $icon_off nicht definiert ist
$state_off # Wert zugehörig zum Icon off, default "off"
$state_on # Wert zugehörig zum Icon on, default "on"
</syntaxhighlight>
}}

'''<big>Beispieldefinition</big>'''
<syntaxhighlight lang="perl">
defmod di_uiTable_switch DOIF ##
attr di_uiTable_switch uiTable {\
package ui_Table;;\
}\
## schaltbares Icons in der Webansicht \
switch([Lampe:state]) | \
switch([Lampeflur:state],"hue_room_hallway") |\
switch([Anwesenheit:state],"status_away_2","status_available\@DarkOrange")|\
switch([Haus:state],"status_locked","status_open\@DarkOrange","closed","open")\
</syntaxhighlight>
''Ergebnis der Beispieldefinition in der Webansicht:''
[[Datei:UiTable switch.png|mini|ohne]]

==== Rollladen: Visualisierung und Steuerung mit Hilfe der Funktion '''shutter''' ====
Die aktuelle Position des Rollladens (0 % - 100 %) wird über Icons visualisiert. Das Anklicken eines Symbols steuert den Rollladen auf die entsprechende Position. Prozentwerte zwischen zwei Icon-Werten werden dem nächsthöheren Icon-Wert zugeordnet.
{{Randnotiz|RNText=uiTable-Funktion '''shutter'''
<syntaxhighlight lang="perl">
shutter ($value,$color,$type)

$value # [<device>:<reading>]
$color # Farbe der aktuellen Rollladenposition, vorangestelltes @ verändert die Farbe des Icons, ohne @ wird der Hintergrund des Icons eingefärbt, default ist @DarkOrange
$type # optional, Anzahl der Symbole 2 bis 6, 3 ist default
</syntaxhighlight>

* [[DOIF/uiTable Schnelleinstieg#Visualisierung und Steuerung von Rollläden|Anwendungsbeispiel]]
}}
'''<big>Beispieldefinition</big>'''
<syntaxhighlight lang="perl">
defmod ui_Table_shutter DOIF ##
attr ui_Table_shutter uiTable {\
package ui_Table;;\
}\
shutter([R_Keller:pct],"\@yellow",2) ## zwei Symbole für 0 % und 100 %\
shutter([R_Wohnzimmer_S:pct]) ## entspricht shutter ([R_Wohnzimmer_S:pct],"\@DarkOrange",3) \
shutter([R_Wohnzimmer_W1:pct],"blue",4) ## vier Symbole \
shutter([R_Wohnzimmer_W2:pct],"\@red",5) ## fünf Symbole\
shutter([R_Wohnzimmer_W3:pct],"red",6 ## sechs Symbole)
</syntaxhighlight>
''Ergebnis der Beispieldefinition in der Webansicht:''
[[Datei:UiTable shutter.png|mini|ohne]]

==== Helligkeit: Visualisierung und Steuerung mit Hilfe der Funktion '''dimmer''' ====
Die aktuelle Helligkeit (0 % - 100 %) wird über Icons visualisiert. Das Anklicken eines Icons bestimmt die Helligkeit der Leuchte. Prozentwerte zwischen zwei Icon-Werten werden dem nächsthöheren Icon-Wert zugeordnet.
{{Randnotiz|RNText=uiTable-Funktion '''dimmer'''
<syntaxhighlight lang="perl">
dimmer ($value,$color,$type)

$value # [<device>:<reading>]
$color # Farbe der aktuellen Helligkeit, vorangestelltes @ verändert die Farbe des Icons, ohne @ wird der Hintergrund des Icons eingefärbt, default ist @DarkOrange
$type # Anzahl der Symbole 2 bis 7, 3 ist default
</syntaxhighlight>
}}

'''<big>Beispieldefinition</big>'''
<syntaxhighlight lang="perl">
defmod di_uiTable_dimmer DOIF ##
attr di_uiTable_dimmer uiTable {\
package ui_Table;;\
}\
dimmer([Strauch3:pct],"\@yellow",2)\
dimmer([Strauch3:pct]) ## entspricht dimmer([Strauch3:pct],"\@DarkOrange",3) \
dimmer([Strauch3:pct],"blue",4)\
dimmer([Strauch3:pct],"\@red",5)\
dimmer([Strauch3:pct],"red",6)\
dimmer([Strauch3:pct],"DarkOrange",7)

</syntaxhighlight>
''Ergebnis der Beispieldefinition in der Webansicht:''
[[Datei:UiTable dimmer.png|mini|ohne]]

==== Vorgabetemperatur eines Thermostats mit Hilfe der Funktion '''temp_knob''' ====
Die aktuelle Vorgabetemperatur eines Thermostats wird über ein Icons visualisiert. Durch Anklicken des Ringes wird die Vorgabetemperatur verändert.
{{Randnotiz|RNText=uiTable-Funktion '''temp_knob'''
<syntaxhighlight lang="perl">
temp_knob ($value,$color,$set)

$value # [<device>:<reading>]
$color # Farbe der voreingestellten Temperatur, default "Darkorange"
$set # set-Befehl, default "set", sonst muss "set <Readingname>" angegeben werden, falls sich das Reading vom set-Befehl vom angezeigten Reading unterscheidet, wie beim THRESHOLD-Modul
</syntaxhighlight>
}}

'''<big>Beispieldefinition</big>'''
<syntaxhighlight lang="perl">
defmod ui_Table_temp_knob DOIF ##
attr ui_Table_temp_knob uiTable {\
package ui_Table;;\
}\
\
## HM-EU-Thermostat, angezeigt wird das Reading "desired-temp", geschaltet wird über "set desired-temp" \
"Dachgeschoss"|temp_knob([TH_DG_HM:desired-temp]) ## entspricht temp_knob([TH_DG_HM:desired-temp],"Darkorange","set") \
\
## HM-EU-Thermostat Temperaturanzeige in gelb \
"Wohnzimmer"|temp_knob([TH_WZ_HM:desired-temp],"yellow") \
\
## Beim THRESHOLD-Modul wird das Reading "desired_value" angezeigt, geändert wird die Temperatur per "set desired" \
"Küche"|temp_knob([TH_Kueche:desired_value],"red","set desired")
</syntaxhighlight>
''Ergebnis der Beispieldefinition in der Webansicht:''
[[Datei:UiTable temp knob.png|mini|ohne]]

== uiTable-'''Templates''' ==
Die Definition einer oder mehrere Zellen kann zu einem Template zusammengefasst werden. Durch die Nutzung von Templates kann die Definition einer Tabelle erheblich vereinfacht werden. Insb. bei gleichartigen Zellen/Zeilen für verschiedene Geräte/Readings braucht eine aufwendige Definition nicht immer wieder wiederholt werden, sondern kann jeweils mit dem Aufruf eines zuvor definierten Templates realisiert werden.
{{Randnotiz|RNText='''Templates'''
* Die Definition von Templates muss vor der Tabellendefinition vorgenommen werden
* Eine Template-Definition beginnt mit dem Schlüsselwort '''DEF'''
* Der Template-Name muss mit '''TPL_''' beginnen
* '''Template-Definition'''-Syntax
<syntaxhighlight lang="perl">
DEF TPL_<Template-Name>(<Zellendefinition mit Platzhaltern: $1,$2,...>)
</syntaxhighlight>
* Templates-Definitionen können in externe Dateien ausgelagert werden
* Templates-Definitionen können per IMPORT-Befehl aus externen Dateien importiert werden
* '''Template-Import'''-Syntax
<syntaxhighlight lang="perl">
IMPORT <Pfad mit Dateinamen>
</syntaxhighlight>
* Innerhalb einer Tabellendefinition können zuvor definierte oder importierte Templates mehrfach genutzt werden
* '''Template-Aufruf'''-Syntax
<syntaxhighlight lang="perl">
TPL_<Template-Name>(<Übergabeparameter für $1>,<Übergabeparameter für $2>,...)
</syntaxhighlight>
}}
'''<big>Beispieldefinition</big>'''
<syntaxhighlight lang="perl">
defmod ui_Table_Template DOIF ##
attr ui_Table_Template uiTable {\
package ui_Table;;\
$TC{1..3}="align='center'";; ## Spalten 1 bis 3 werden zentriert\
}\
\
## Template-Definitionen beginnen vor der Tabellendefinition\
\
## Das Template TPL_raum stellt eine Tabellenzeile dar, die mit Hilfe von uiTable-Funktionen mehrere Tabellenzellen definiert\
DEF TPL_raum ("$1" | temp([TH_$2_HM:measured-temp]),hum([TH_$2_HM:humidity]) | switch([H_$2:state],"fa_off") | temp_knob([TH_$2_HM:desired-temp]))\
\
## Tabellendefinition\
\
## pro Tabellenzeile wird ein Raum mit Hilfe des oben definierten Templates "TPL_raum" dargestellt\
"Raum"|"Temp./Feuchte"|"Ventil"|"Vorgabetemp."\
TPL_raum (Dachgeschoss,DG) ## der Übergabeparameter "Dachgeschoss" wird im Template "TPL_raum" anstelle von $1 eingesetzt, "DG" wird anstelle von $2 eingesetzt\
TPL_raum (Bad,Bad)\
TPL_raum (Kinderzimmer ost,Kz_o)\
TPL_raum (Kinderzimmer west,Kz_w)\
TPL_raum (Wohnzimmer,WZ)\
TPL_raum (Keller,Keller)

</syntaxhighlight>
''Ergebnis der Beispieldefinition in der Webansicht:''
[[Datei:UiTable Templates.png|mini|ohne]]

== Eigene uiTable-Funktionen programmieren ==
Für die eigenen Bedürfnisse können eigene uiTable-Funktionen programmiert werden. In der Datei [https://svn.fhem.de/trac/browser/trunk/fhem/contrib/DOIF/uiTable.tpl contrib/DOIF/uiTable.tpl] befinden sich alle intern definierten uiTable-Funktion aus dem package ui_Table als Kopie. Diese Funktionen können als Inspiration für eigene Entwicklung dienen.
{{Randnotiz|RNText='''uiTable-Funktionen'''
* Es gibt drei Arten von uiTable-Funktionen, sie werden intern anhand der Rückgabewerte unterschieden
* uiTable-Funktionen vom Typ 1: '''HTML''', ein Rückgabewert
<syntaxhighlight lang="perl">
return(<HTML-code>)
</syntaxhighlight>
* uiTable-Funktionen vom Typ 2: '''Style''' (entspricht der '''STY'''-Funktion), zwei Rückgabewerte
<syntaxhighlight lang="perl">
return(<value>,<CSS-style>)
</syntaxhighlight>
* uiTable-Funktionen vom Typ 3: '''Widget''' (entspricht der '''WID'''-Funktion), vier Rückgabewerte
<syntaxhighlight lang="perl">
return (<value>,<>,<FHEM-widget>,<set-command: "" or "set" or "set <Readingname>">)
</syntaxhighlight>
* uiTable-Funktionen sind reine Perlfunktionen
* uiTable-Funktionen sollten im eigenen Package definiert werden, sonst könnten bestehende Perlfunktionen im System überschrieben werden
* uiTable-Funktionen können in Template-Dateien ausgelagert werden und über IMPORT-Befehl importiert werden, siehe Templates
}}

'''<big>Beispieldefinition</big>'''
<syntaxhighlight lang="perl">
defmod di_uiTable_function DOIF ##
attr di_uiTable_function uiTable {\
package my_uiTable;; ## eigenes Package mit selbstdefinierten Funktionen\
\
## uiTable-Funktion vom Typ "HTML", Rückgabewert: (HTML-code)\
\
sub clock { ## Anzeige aktueller Uhrzeit mit Datum\
## Voraussetzung: contrib/DOIF/doifclock.js muss ins www/pgm2-Verzeichnis kopiert werden\
## Attribut setzen in der Webinstanz: attr <WEB-Instanz> JavaScripts pgm2/doifclock.js \
my ($color,$size)=@_;;\
$color="darkorange" if (!defined ($color));; ## $color ist optional, default Darkorange\
$size="20" if (!defined ($size));; ## $size ist optional, default 20pt\
return("<div class='doifclock'style='font-weight:bold;;font-size:".$size."pt;;color:".$color.";;'>error</div>")\
}\
\
## uiTable-Funktion vom Typ Style, Rückgabewerte (Wert,CSS-style)\
\
sub red_green { ## Farbige Skalierung von Zahlen mit Hilfe der DOIF_hsv-Funktion: von 0 - rot bis 10 - grün\
my ($value)=@_;;\
return ($value." KW", ## Wert/Text\
"font-weight:bold;;color:".::DOIF_hsv ($value,0,10,0,120,70,100) ## CSS-Style\
);;\
} \
\
## uiTable-Funktion vom Typ Widget, Rückgabewerte (Wert,Leer,FHEM-Widget,set-Befehl)\
\
sub slider { ## FHEM-Widget Slider, weitere FHEM-Widgets siehe: https://wiki.fhem.de/wiki/FHEMWEB/Widgets\
my ($value,$set)=@_;;\
$set="" if (!defined $set);;\
return ($value, ## Zahlenwert\
"", ## leer\
"slider,0,0.5,100,1", ## FHEM-Widget\
$set ## set-Befehl des FHEM-Widgets\
) \
}\
\
}\
\
## Tabellendefinition\
\
"Uhrzeit/Datum"\
clock("yellow",30) ## obige Funktion clock\
"Dimmer"\
slider([Wohnzimmer:pct]) ## obige Funktion slider\
"Leistung"\
red_green([Leistung:state]) ## obige Funktion red_green
</syntaxhighlight>

''Ergebnis der Beispieldefinition in der Webansicht:''
[[Datei:UiTable-functions.png|mini|ohne]]

== Package-Konzept, Auslagerung eigener Funktionen, der '''IMPORT'''-Befehl==
uiTable arbeitet mit Packages. In einem Package sind definierte Funktionen gekapselt, sie kollidieren nicht mit bereits definierten Funktionen in FHEM.
{{Randnotiz|RNText='''Package'''
* das für die Definition der Tabelle gültige Package wird im Perlblock des uiTable-Attributes angegeben
* interne uiTable-Funktionen befinden sich im Package '''ui_Table'''
* ohne eine Angabe eines Package befindet man sich im Package '''main'''
* Funktionen außerhalb des gültigen Package müssen mit <package-Name>::<Funktion> angegeben werden
* externe uiTable-Funktionen können per IMPORT-Befehl importiert werden
}}
=== Tabellendefinition im Package main ===
<syntaxhighlight lang="perl">
defmod beispiel1 DOIF ##
attr beispiel1 uiTable ## keine Package-Definition im Perlblock\
\
## Tabellendefinition befindet sich im Package main\
\
## Funktionen aus dem main-Package können unmittelbar angegeben werden\
FW_makeImage("scene_day")\
\
## Funktionen aus dem ui_Table-Package müssen mit vorangestelltem Package angegeben werden\
ui_Table::temp ([Aussensensor:tempaerature])
</syntaxhighlight>

=== Tabellendefinition im Package ui_Table ===
<syntaxhighlight lang="perl">
defmod beispiel2 DOIF ##
attr beispiel2 uiTable {\
package ui_Table; ## Package-Angabe im Perlblock\
}\
\
## Tabellendefinition befindet sich im Package ui_Table\
\
## Funktionen aus dem main-Package müssen mit vorangestelltem package angegeben werden, der Name main kann weggelassen werden\
::FW_makeImage("scene_day")\
\
## Funktionen aus dem ui_Table-Package können direkt angegeben werden\
temp ([Aussensensor:temperature])
</syntaxhighlight>

=== Eigene uiTable-Funktionen im eigenen Package ===
Diese Art der Definition bietet sich dann an, wenn man eine eigene uiTable-Funktion nur in einem DOIF nutzen möchte.
<syntaxhighlight lang="perl">
defmod beispiel3 DOIF ##
attr beispiel3 uiTable {\
package $SELF;; ## Package-Name ist der Name des DOIF-Moduls, dadurch ist der Package-Name eindeutig\
sub scene_day { ## eigene Funktion befindet sich im eigenen Package beispiel3\
return (::FW_makeImage("scene_day"));;\
}\
}\
## Tabellendefinition befindet sich im Package beispiel3\
\
## Funktionen aus dem main-Package müssen mit vorangestelltem Package angegeben werden (der Name main kann weggelassen werden)\
::FW_makeImage("scene_day")\
\
## interne Funktionen aus dem ui_Table-Package müssen mit vorangestelltem Package ui_Table angegeben werden\
ui_Table::temp ([Aussensensor:temperature])\
\
## eigene Funktionen können direkt angegeben werden\
scene_day()
</syntaxhighlight>

=== Eigene ausgelagerte uiTable-Funktionen ===
Möchte man das ui_Table-Package um eigene Funktionen erweitern, die man in verschiedenen DOIFs nutzen möchte, so sollte man diese in eine eigene Datei auslagern, die man mit dem IMPORT-Befehl vor der Definition der Tabelle importieren kann.

Ausgelagerte Funktion in einer eigenen Datei z. B. my_uiTable.tpl:

<syntaxhighlight lang="perl">
{ ## Inhalt der Datei my_uiTable.tpl
package ui_Table; ## das aktuelle Package ist ui_Table
sub scene_day { ## eigene Funktion wird zum Package ui_Table hinzugefügt
return (::FW_makeImage("scene_day"));
}
## die Datei kann alle Funktionen beinhalten, die man in diversen DOIFs nutzen möchte
}
</syntaxhighlight>

<syntaxhighlight lang="perl">
defmod beispiel4 DOIF ##
attr beispiel4 uiTable ##\
\
IMPORT ./contrib/DOIF/my_uiTable.tpl ## nach dem Import befindet man sich in Package ui_Table erweitert um eigene Funktionen\
\
## Tabellendefinition befindet sich im Package ui_Table\
\
## Funktionen aus dem main-Package müssen mit vorangestelltem Package angegeben werden (der Name main kann weggelassen werden)\
::FW_makeImage("scene_day")\
\
## interne uiTable-Funktionen aus dem ui_Table-Package können direkt angegeben werden\
temp ([Aussensensor:temperature])\
\
## eigene Funktionen können direkt angegeben werden, da man sich bereits im Package uiTable befinden\
scene_day()\
</syntaxhighlight>

== '''hsv'''-Funktion für Farbskalierungen==
Mit Hilfe der hsv-Funktion können Texte, Werte oder Icons abhängig vom Wert eingefärbt werden. Es wird durch Vorgabe von Farbsättigung (saturation) und Helligkeit (lightness), linear ein Farbton für einen bestimmten Wert errechnet. Den Farbwert HUE (0 - 360) für den kleinsten sowie größten Wert kann man mit Hilfe eines Color-Pickers bestimmen. Der Rückgabewert ist ein Farbwert in der CSS-Notation.
{{Randnotiz|RNText='''hsv-Funktion für Farbskalierungen'''
<syntaxhighlight lang="perl">
hsv ($value,$min_value,$max_value,$min_hue,$max_hue,$saturation,$lightness)
$value # Wert, Reading
$min_value # der kleinste Wert, dieser entspricht dem Farbwert $min_hue
$max_value # der größte Wert, dieser entspricht dem Farbwert $max_hue
$min_hue # Farbwert für den kleinsten Wert $min_value
$max_hue # Farbwert für den größten Wert $max_value
$saturation # Farbsättigung, default 100, optional
$lightness # Farbhelligkeit, default 100, optional
</syntaxhighlight>
Die Funktion befindet sich im ui_Table-Package
}}

'''<big>Beispieldefinition</big>'''

<syntaxhighlight lang="perl">
defmod di_uiTable_hsv DOIF ##
attr di_uiTable_hsv uiTable {\
package ui_Table;;\
## eigene uiTable-Funktionen vom Typ 1 mit einem Rückgabewert als HTML-Code\
\
sub bat_icon { ## färbt das Icon 'measure_battery_100' abhängig vom Wert mit Hilfe der Funktion hsv \
my ($value)=@_;;\
return(ICON("measure_battery_100\@".hsv($value,0,100,0,120,100,100)))\
}\
\
sub bat_icon2 {## zusätzlich zum Farbwert wird ein entsprechendes Icon bestimmt\
my($val)=@_;;\
my $icon;;\
if ($val==0) {\
$icon="measure_battery_0";;\
} elsif ($val<=25) {\
$icon="measure_battery_25";;\
} elsif ($val<=50) {\
$icon="measure_battery_50";;\
} elsif ($val<=75) {\
$icon="measure_battery_75";;\
} else {\
$icon="measure_battery_100";;\
}\
\
my $output=ICON("$icon\@".hsv ($val,0,100,0,120,90,100));;\
return($output);;\
}\
}\
\
## Tabellendefinition\
\
## eingefärbtes Icon 0 % entspricht rot (HSV-Wert 0), 100 % entspricht grün (HSV-Wert 120) mit Direktangabe\
1|ICON("measure_battery_100\@".hsv([bat:level],0,100,0,120,100,100))\
\
## gleiche Funktionalität mit Hilfe der oben definierten Funktion bat_icon \
2|bat_icon([bat:level])\
\
## Icon mit Hilfe der oben definierten Funktion bat_icon2\
3|bat_icon2([bat:level])\
\
## Beispiel für die Farbskaliereung von 0 bis 100 % mit der obigen Funktion bat_icon\
4|bat_icon(0)|bat_icon(10)|bat_icon(20)|bat_icon(30)|bat_icon(40)|bat_icon(50)|bat_icon(60)|bat_icon(70)|bat_icon(80)|bat_icon(90)|bat_icon(100)\
\
## Beispiel für die Farbskaliereung von 0 bis 100 % mit der obigen Funktion bat_icon2\
5|bat_icon2(0)|bat_icon2(10)|bat_icon2(20)|bat_icon2(30)|bat_icon2(40)|bat_icon2(50)|bat_icon2(60)|bat_icon2(70)|bat_icon2(80)|bat_icon2(90)|bat_icon2(100)
</syntaxhighlight>

''Ergebnis der Beispieldefinition in der Webansicht:''
[[Datei:UiTable DOIF hsv.png|mini|ohne]]

== Eine for-Schleife mit Hilfe des '''FOR'''-Befehls ==
Mit Hilfe des '''FOR'''-Befehls können über eine Schleife aus einer Liste mit Elementen mehrere Tabellenzellen definiert werden. Die Elementenliste (Array) kann über eine Funktion bestimmt werden. Auf diese Weise kann z. B. eine Tabelle für mehrere Geräte einfach definiert werden.
{{Randnotiz|RNText='''FOR-Befehl'''
* Der FOR-Befehl entspricht einer foreach-Schleife in Perl
* Syntax: '''FOR (<Array>,<Zellendefinitionen>)'''<br>'''<Array>''' eine gültige Angabe eines Arrays oder eine Perlfunktion, die ein Array liefert<br>'''<Zellendefinitionen>''' Definition einer oder mehrerer Zellen, die Angabe $_ wird durch das jeweilige Element des Arrays ersetzt
*'''nützliche Links'''
**{{Link2CmdRef|Anker=DOIF_aggregation|Lang=de|Label=DOIF Aggregationsfunktionen mit Perlfunktion AggrDoIf}}
**[[DevelopmentModuleAPI#devspec2array|devspec2array]]
}}
'''<big>Beispieldefinitionen</big>'''
<syntaxhighlight lang="perl">
defmod di_for DOIF ##
attr di_for uiTable \
## Temperaturen aller Geräte, die mit 'T' beginnen und ein Reading 'temperature' haben, sollen in einer Tabelle visualisiert werden\
FOR(::AggrDoIf('@','^T_','temperature'),"$_"|temp([$_:temperature:d2]))
</syntaxhighlight>
''Ergebnis der Beispieldefinition in der Webansicht:''
[[Datei:UiTable-FOR-temperature.png|200px|ohne]]

<syntaxhighlight lang="perl">
defmod di_for DOIF ##
attr di_for uiTable \
## Anzeige des Batteriestatus aller Geräte, bei denen das Wort 'Fenster' vorkommt, die das Readings 'battery' haben\
FOR(::AggrDoIf('@','Fenster','battery'),"$_"|bat([$_:battery]))
</syntaxhighlight>
''Ergebnis der Beispieldefinition in der Webansicht:''
[[Datei:UiTable-FOR-battery.png|200px|ohne]]

<syntaxhighlight lang="perl">
defmod di_for DOIF ##
attr di_for uiTable \
## Anzeige des Status aller Geräte im System vom Typ 'HMS'\
FOR(::devspec2array("TYPE=HMS"),"$_"|[$_])
</syntaxhighlight>
''Ergebnis der Beispieldefinition in der Webansicht:''
[[Datei:UiTable-FOR-HMS.png|300px|ohne]]

<syntaxhighlight lang="perl">
defmod di_for DOIF ##
attr di_for uiTable \
## Elemente einer kommagetrennten Liste sollen jeweils in einer Tabellenzelle in einer Tabellenzeile angezeigt werden\
FOR(split(",","Mo,Di,Mi,Do,Fr,Sa,So"),ui_Table::style("$_","Darkorange")|)
</syntaxhighlight>
''Ergebnis der Beispieldefinition in der Webansicht:''
[[Datei:UiTable-FOR-split.png|300px|ohne]]

<syntaxhighlight lang="perl">
defmod di_for DOIF ##
attr di_for uiTable \
## Durch Leerzeichen getrennte Zeichenketten sollen jeweils in einer Tabellenzelle in einer Tabellenzeile angezeigt werden\
FOR(qw/Montag Dienstag Mittwoch Donnerstag Freitag/,"$_"|)
</syntaxhighlight>
''Ergebnis der Beispieldefinition in der Webansicht:''
[[Datei:UiTable-FOR-qw.png|300px|ohne]]

<syntaxhighlight lang="perl">
defmod di_for DOIF ##
attr di_for uiTable \
## das Templates TPL_raum, soll vier mal aufgerufen werden: TPL_raum(1), TPL_raum(2)...\
## das Templates TPL_raum muss vorher definiert worden sein\
FOR(1..4,TPL_raum($_))
</syntaxhighlight>

''Ergebnis der Beispieldefinition in der Webansicht:''
[[Datei:UiTable-FOR TPL raum.png|600px|ohne]]

== '''Anwendungsbeispiele''' ==
=== '' Visualisierung und Steuerung von '''Rollläden''''' ===
{{Randnotiz|RNText='''nützliche Links'''
* {{Link2CmdRef|Anker=DOIF_Zeitsteuerung_mit_Zeitintervallen|Lang=de|Label=Zeitsteuerung}}
* uiTable-Funktion [[DOIF/uiTable Schnelleinstieg#Rollladen: Visualisierung und Steuerung mit Hilfe der Funktion shutter|shutter]]
* uiTable-Funktion [[DOIF/uiTable Schnelleinstieg#Textformatierungen mit Hilfe der Funktion style|style]]
* [[DOIF/uiTable Schnelleinstieg#uiTable-Templates|Templates]]
}}
Im folgenden Beispiel werden Rollläden morgens hochgefahren, ebenso wird die Position aller Rollläden visualisiert. Durch Anklicken eines Icons wird der Rollladen auf die entsprechende Position bewegt.

<syntaxhighlight lang="perl">
defmod DI_Rollladen DOIF (([Dunkelheit] eq "off" and [06:25-09:00|8]) or [09:00|7]) \
((set R_W_S,R_W_W[1-3] on)) ## Hochfahren der Rollläden im Erdgeschoss morgens\
DOELSEIF ([Dunkelheit] eq "on")
attr DI_Rollladen cmdState oben|unten
attr DI_Rollladen devStateIcon unten:status_night oben:scene_day
attr DI_Rollladen icon fts_shutter_automatic
attr DI_Rollladen uiTable {\
package ui_Table;;\
}\
\
## Template für ein Fenster\
DEF TPL_shutter("$1"|shutter([$1:pct]))\
\
## Tabellendefinition\
\
style("Dachgeschoss","Darkorange")|""\
TPL_shutter(R_Dachboden)\
style("erstes Geschoss","Darkorange")|""\
TPL_shutter(R_Bad)\
TPL_shutter(R_Kinderzimmer1_O)\
TPL_shutter(R_Kinderzimmer1_S)\
TPL_shutter(R_Kinderzimmer2_S)\
TPL_shutter(R_Kinderzimmer2_W1)\
TPL_shutter(R_Kinderzimmer2_W2)\
style("Erdgeschoss","Darkorange")|""\
TPL_shutter(R_Kueche)\
TPL_shutter(R_W_S)\
TPL_shutter(R_W_W1)\
TPL_shutter(R_W_W2)\
TPL_shutter(R_W_W3)\
style("Keller","Darkorange")|""\
TPL_shutter(R_Keller)\
</syntaxhighlight>
''Ergebnis des Anwendungsbeispiels in der Webansicht:''
[[Datei:UiTable Rollladen.png|mini|ohne]]

=== ''Anzahl der Tage bis zur '''Abfall-Entsorgung''''' ===
{{Randnotiz|RNText='''nützliche Links'''
* FHEM-Modul [[Calendar]]
* ui_Table Funktion [[DOIF/uiTable Schnelleinstieg#Icon-Darstellung mit Text mit Hilfe der Funktion icon_label|icon_label]]
}}
Mit Hilfe des Kalender-Moduls werden die verbleibenden Tage bis zur Abfall-Entsorgung der jeweiligen Tonne berechnet und mit Hilfe von uiTable visualisiert. Wenn der Tag der Entsorgung bevorsteht, wird er farbig gekennzeichnet. Vorausgesetzt wird die Definition des Kalenders namens 'cal' mit Hilfe des Moduls [[Calendar]]. Dieser muss die Termine der Abfallentsorgung der Tonnen beinhalten. Im Beispiel wird nach Stichwörtern: "Altpapier", "Restmüll", "Bio", "Gelbe" und "Grünabfuhr" im Kalender gesucht.
<syntaxhighlight lang="perl">
defmod Abfall DOIF subs {\
## Hier reicht es den Kalender-Eintrag anzupassen\
## Kalender-Eintrag, Reading, icon \
push @{$_sc},["Altpapier","altpapier","Abfalltonne-Recycling-Logo\@blue"];;\
push @{$_sc},["Restmüll","restmuell","Abfalltonne\@gray"];;\
push @{$_sc},["Bio","bio","Abfalltonne-Recycling-Logo\@green"];;\
push @{$_sc},["Gelbe","gelbe_tonne","Abfalltonne-Recycling-Logo\@yellow"];;\
push @{$_sc},["Grünabfuhr","gruenschnitt","Gartenabfall\@green"];;\
\
sub days \
{\
my ($event,$reading)=@_;;\
my $days=fhem('get cal events timeFormat:"%j" filter:field(summary)=~"'.$event.'" limit:count=1,from=0 format:custom="$T1"',1);;\
my $date=fhem('get cal events timeFormat:"%a. %d.%m." filter:field(summary)=~"'.$event.'" limit:count=1,from=0 format:custom="$T1"',1);;\
my $diff;;\
if (defined($days) and $days ne "") {\
my $now=::strftime ('%j', localtime());;\
my $year=::strftime ('%Y', localtime());;\
$diff=$days-$now;;\
if ($diff < 0) {\
$diff+=(365+($year % 4 eq 0 and $year % 100 ne 0 or $year % 400 eq 0 ? 1: 0));;\
}\
} else {\
$date="";;\
$diff="N/A"\
}\
set_Reading($reading."_date",$date);;\
set_Reading($reading,$diff,1);;\
}\
sub update\
{\
for (my $i=0;;$i < @{$_sc};;$i++) {\
days($_sc[$i][0],$_sc[$i][1]);;\
}\
}\
}\
init{[00:00];;set_Exec("Timer",60,'update()');;}\
update{update()}
attr Abfall room wiki->abfall
attr Abfall uiTable {\
package ui_Table;;\
$TABLE="text-align:center";;\
$SHOWNOSTATE=1;;\
sub ic\
{\
my ($icon,$days)=@_;;\
icon_label($icon,$days,"white",$days eq "N/A" ? "blue" : $days > 1 ? "#606060" : "red")\
}\
}\
\
DEF TPL_Tonne (style([$SELF:$1_date],"",8),ic ('$2',[$SELF:$1]))\
\
FOR (@{$_sc},TPL_Tonne($_$2,$_$3)|)
</syntaxhighlight>

''Ergebnis der Beispieldefinition in der Webansicht:''
[[Datei:Anwendungsbeispiel Abfall.png|mini|ohne]]

=== ''Visualisierung: '''offene Fenster''''' ===
{{Randnotiz|RNText='''nützliche Links'''
* Attribut {{Link2CmdRef|Anker=DOIF_DOIF_Readings|Lang=de|Label=DOIF_Readings}}
* DOIF-{{Link2CmdRef|Anker=DOIF_aggregation|Lang=de|Label=Aggregationsfunktionen}}
* uiTable-Funktion [[DOIF/uiTable Schnelleinstieg#Icon-Darstellung mit Hilfe der Funktion icon|icon]]
}}
Alle offenen Fenster werden aufgelistet und mit entsprechendem Icon visualisiert.
<syntaxhighlight lang="perl">
defmod di_uiTable_windows DOIF ## Visualisierung offener Fenster, Fenster-Devices enden mit "Fenster" im Namen
attr di_uiTable_windows DOIF_Readings windows:[@as(<br>)"Fenster$":state:"open","keine"]
attr di_uiTable_windows uiTable {package ui_Table;;}\
icon([$SELF:windows],"fts_window_1w_open\@DarkOrange","fts_window_1w",".*","keine")|[$SELF:windows]
</syntaxhighlight>

''Ergebnis der Beispieldefinition in der Webansicht:''
[[Datei:UiTable windows closed.png|mini|ohne]]
[[Datei:UiTable windows open.png|mini|ohne]]

=== ''Visualisierung: '''aktuelle Wetterlage''''' ===
{{Randnotiz|RNText='''nützliche Links'''
* DWD [https://www.dwd.de/DE/Home/home_node.html Homepage]
* Regenradar [https://www.dwd.de/DE/wetter/wetterundklima_vorort/_node.html Radarfilm BRD]
* aktuelles Wetter [https://www.dwd.de/DE/wetter/wetterundklima_vorort/nordrhein-westfalen/nrw_node.html NRW]
* Wetteronline [https://www.wetteronline.de/wetter-widget eignes Widget]
}}
Regenrader animiert, aktuelle Temperatur und Feuchte vom Sensor, aktuelle Wetterlage sowie Wettervorhersage der nächsten Tage. Über entsprechende Weblinks werden Bilder aus dem WWW in der Tabelle visualisiert. Im Gegensatz zu lokalen Sensoren, muss für die Aktualisierung der WWW-Elemente in der jeweiligen Webinstanz (FHEMWEB) das refresh-Attribut gesetzt werden.

<syntaxhighlight lang="perl">
defmod di_uiTable_wetter DOIF ##
attr di_uiTable_wetter uiTable {\
package ui_Table;;\
$TC{1}="align='center'";;\
}\
## das Attribut 'refresh' der Webinstanz für ein Wandtablet wurde auf 900 gesetzt, damit die Bilder alle 15 Minuten aktualisiert werden \
## Tabellendefinition\
\
## Regenradar BRD\
'<img src="https://www.dwd.de/DWD/wetter/radar/radfilm_brd_akt.gif" height="365px" width="365px">'|\
\
## Aktuelle Temperatur und Feuchtigkeit vom lokalen sensor\
temp([Aussensensor:temperature],40),hum ([Aussensensor:humidity],30),\
\
## aktuelle Wetterlage NRW\
"<img src ='https://www.dwd.de/DE/wetter/wetterundklima_vorort/nordrhein-westfalen/_functions/bildgalerie/wetter_aktuell.jpg?view=nasImage&nn=561200' height='255px' width='255px'>"|\
\
## Wettervorhersage\
"<iframe marginheight='0' marginwidth='0' scrolling='no' width='300' height='365' name='FC3' style='border:1px solid;;border-color:#00537f;;' src='https://api.wetteronline.de/wetterwidget?gid=x0677&modeid=FC3&seourl=juelich&locationname=Jülich&lang=de'></iframe>"\
</syntaxhighlight>

''Ergebnis der Beispieldefinition in der Webansicht:''
[[Datei:UiTable wetter.png|600px|links]]
<br clear="all">

=== ''Visualisierung: '''Wetterstation''''' ===
{{Randnotiz|RNText='''nützliche Links'''
* Wunderground [https://wunderground.com/ Homepage]
* svg-Funktion [https://wiki.fhem.de/wiki/DOIF/uiTable_Schnelleinstieg#Anzeige_eines_Werteverlaufs_und_des_aktuellen_Wertes_mit_Hilfe_der_SVG-Funktion_card card]
* svg-Funktionen [https://wiki.fhem.de/wiki/DOIF/uiTable_Schnelleinstieg#icon_ring-Funktionen icon_ring]
}}
Die vorgestellte Lösung funktioniert ohne Anmeldung beim Wetterdienst und ohne Nutzung von API.
Über den Wetterdienst: https://www.wunderground.com/ werden sehr viele private Wifi-Wetterstationen eingebunden. Das kann man sich zunutze machen, indem man zunächst in seiner Umgebung nach Wetterstationen des Dienstes sucht - oft findet man im Umkreis von wenigen Kilometern schon einige Stationen, die rege Wetterdaten liefern. Danach definiert man über HTTPMOD seine Station und visualisiert diese anschließend.

Definition einer Station in der Nachbarschaft. <StationsID> muss gegen die korrekte Stationsnummer ersetzt werden.
<syntaxhighlight lang="perl">
defmod Wetter HTTPMOD https://www.wunderground.com/dashboard/pws/<StationsID>
attr Wetter enableControlSet 1
attr Wetter reading01Name Wind
attr Wetter reading01Regex stationID(?!.*stationID).*windspeedAvg":([\d+\.]+)
attr Wetter reading02Name Windboeen
attr Wetter reading02Regex stationID(?!.*stationID).*windgustAvg":([\d+\.]+)
attr Wetter reading03Name Windrichtung
attr Wetter reading03Regex stationID(?!.*stationID).*winddirAvg":([\d+\.]+)
attr Wetter reading04Name Regen
attr Wetter reading04Regex stationID(?!.*stationID).*precipRate":([\d+\.]+)
attr Wetter reading05Name RegenGesamt
attr Wetter reading05Regex stationID(?!.*stationID).*precipTotal":([\d+\.]+)
attr Wetter reading06Name Temperatur
attr Wetter reading06Regex stationID(?!.*stationID).*tempAvg":([\d+\.]+)
attr Wetter reading07Name Feuchtigkeit
attr Wetter reading07Regex stationID(?!.*stationID).*humidityAvg":([\d+\.]+)
attr Wetter reading08Name UV
attr Wetter reading08Regex stationID(?!.*stationID).*uvHigh":([\d+\.]+)
attr Wetter reading09Name Luftdruck
attr Wetter reading09Regex stationID(?!.*stationID).*pressureMin":([\d+\.]+)
attr Wetter reading10Name TemperaturGefuehlt
attr Wetter reading10Regex stationID(?!.*stationID).*windchillAvg":([\d+\.]+)
attr Wetter reading11Name TaupunktTemp
attr Wetter reading11Regex stationID(?!.*stationID).*dewptAvg":([\d+\.]+)
attr Wetter reading12Name Sonnenstrahlung
attr Wetter reading12Regex stationID(?!.*stationID).*solarRadiationHigh":([\d+\.]+)
attr Wetter room Wetter
attr Wetter timeout 10
attr Wetter userReadings WindKm {sprintf("%1.1f",ReadingsVal($name,"Wind",0)*1.60934)},\
WindboeenKm {sprintf("%1.1f",ReadingsVal($name,"Windboeen",0)*1.60934)},\
WindrichtungGrad {ReadingsVal($name,"Windrichtung",0)-180},\
RegenMm {ReadingsVal($name,"Regen",0)*25.4},\
RegenGesamtMm {ReadingsVal($name,"RegenGesamt",0)*25.4},\
TemperaturC {sprintf("%1.1f",(ReadingsVal($name,"Temperatur",0)-32)*5/9)},\
TaupunktTempC {sprintf("%1.1f",(ReadingsVal($name,"TaupunktTemp",0)-32)*5/9)},\
LuftdruckHpa {sprintf("%d",ReadingsVal($name,"Luftdruck",0)*33.8639)},\
TemperaturGefuehltC {sprintf("%1.1f",(ReadingsVal($name,"TemperaturGefuehlt",0)-32)*5/9)}
</syntaxhighlight>

Nun erfolgt die Visualisierung der Daten.

<syntaxhighlight lang="perl">
defmod di_Wetter_ring DOIF ##
attr di_Wetter_ring uiTable {package ui_Table;;}\
\
icon_temp_hum_ring("temp_outside",[Wetter:TemperaturC],[Wetter:Feuchtigkeit],undef,undef,150)|\
icon_temp_ring ("temp_windchill",[Wetter:TemperaturGefuehltC],undef,undef,150) |\
icon_temp_ring ("temperature_humidity",[Wetter:TaupunktTempC],undef,undef,150) |\
icon_ring2([Wetter:WindKm] > 0 ? "wind".",1,0,0,".[Wetter:WindrichtungGrad]:"no_wind",[Wetter:WindKm],0,50,120,0,"km/h",150,undef,1,[Wetter:WindboeenKm],0,50,120,0,"km/h",undef,1) |\
icon_ring2("weather_rain_gauge",[Wetter:RegenMm],0,10,180,270,"mm/h",150,undef,1,[Wetter:RegenGesamtMm],0,50,180,270,"mm",undef,1)|\
icon_ring2("sani_solar",[Wetter:UV],0,10,100,30,"UV",150,undef,0,[Wetter:Sonnenstrahlung],0,1000,100,30,"Watt/m²",undef,0)|\
icon_ring ("weather_barometric_pressure",[Wetter:LuftdruckHpa],980,1047,0,120,"hPa",0,150)
</syntaxhighlight>

''Ergebnis der Beispieldefinition in der Webansicht:''
[[Datei:UiTable ringwetter.png|600px|links]]
<br clear="all">

Hier ein Beispiel der Visualisierung mit Verlauf der letzten drei Tage mit Hilfe der svg-Funktion '''card''':

<syntaxhighlight lang="perl">
defmod di_Wetter DOIF ##
attr di_Wetter icon weather_wind
attr di_Wetter uiTable {package ui_Table;;}\
## card ($collect,$header,$icon,$min,$max,$minColor,$maxColor,$unit,$func,$decfont,$size,$model,$lightness)\
\
card([Wetter:TemperaturC:col3d],"Außentemperatur","temp_outside",-10,60,undef,undef,"°C",\&temp_hue)|\
card([Wetter:TemperaturGefuehltC:col3d],"gefühlte Temperatur","temp_windchill",-10,60,undef,undef,"°C",\&temp_hue)|\
card([Wetter:TaupunktTempC:col3d],"Taupunkttemperatur","temperature_humidity",-10,60,undef,undef,"°C",\&temp_hue)|\
card([Wetter:Feuchtigkeit:col3d],"Außenfeuchtigkeit","temperature_humidity",0,100,undef,undef,"%",\&hum_hue)|\
card([Wetter:WindKm:col3d],"Wind",[Wetter:WindKm] > 0 ? "wind".",1,0,0,".[Wetter:WindrichtungGrad]:"no_wind",0,30,90,30,"km/h",undef,1)\
card([Wetter:WindboeenKm:col3d],"Windböen","weather_wind",0,30,90,30,"km/h",undef,1)|\
card([Wetter:RegenMm:col3d],"Regen","weather_rain_gauge",0,10,180,270,"mm/h")|\
card([Wetter:RegenGesamtMm:col3d],"Regengesamt","weather_rain_gauge",0,50,180,270,"mm")|\
##card([Wetter:UV:col3d],"UV-Strahlung","sani_solar",0,7,100,30,"UV",undef,0)|\
card([Wetter:Sonnenstrahlung:col3d],"Sonnenstrahlung","sani_solar",0,1000,30,90,"Watt/m²",undef,0)|\
card([Wetter:LuftdruckHpa:col3d],"Luftdruck","weather_barometric_pressure",980,1047,30,90,"hPa",undef,0)
</syntaxhighlight>

''Ergebnis der Beispieldefinition in der Webansicht:''
[[Datei:UiTable svgwetter.png|800px|links]]
<br clear="all">

Ohne Angabe der Überschrift (undef für $header setzen) lässt sich eine kompaktere Darstellung erzielen:

[[Datei:UiTable svgwetteroh.png|800px|links]]

<br clear="all">

=== ''Visualisierung: '''aktueller Spritpreis''''' ===
{{Randnotiz|RNText='''nützliche Links'''
* svg-Funktion [[DOIF/uiTable_Schnelleinstieg#ring-Funktionen|ring]]
* svg-Funktion [[DOIF/uiTable_Schnelleinstieg#Anzeige_eines_Werteverlaufs_und_des_aktuellen_Wertes_mit_Hilfe_der_SVG-Funktion_card|card]]
* Tankstelle bestimmen [https://www.clever-tanken.de/ Clever tanken]
* Modul [[HTTPMOD]]
}}
Der aktuelle Spritpreis einer Tankstelle wird ermittelt und mit seinem zeitlichen Verlauf visualisiert.

Zunächst wird ein HTTPMOD-Modul für den aktuellen Spritpreis definiert, dabei ist <Stations-ID> durch die ID der Tankstelle zu ersetzen.

<syntaxhighlight lang="perl">
defmod Tankstelle HTTPMOD http://www.clever-tanken.de/tankstelle_details/<Stations-ID> 300
attr Tankstelle devStateIcon {ui_Table::ring(ReadingsVal("$name","Diesel",0),1.00,1.40,120,0,"Diesel",90,undef,2)." ".ui_Table::ring(ReadingsVal("$name","SuperE5",0),1.10,1.60,120,0,"E5",90,undef,2)}
attr Tankstelle enableControlSet 1
attr Tankstelle event-on-change-reading .*
attr Tankstelle group Spritpreise
attr Tankstelle reading01Name Diesel
attr Tankstelle reading01Regex "current-price-1">(\d.\d{2})
attr Tankstelle reading02Name SuperE5
attr Tankstelle reading02Regex "current-price-2">(\d.\d{2})
attr Tankstelle room Spritpreise
attr Tankstelle timeout 10
</syntaxhighlight>

''Ergebnis der Beispieldefinition in der Webansicht:''
[[Datei:Di uiTable Tankstelle.png|ohne|mini]]

Visualisierung der Preisentwicklung der letzten 24 Stunden:

<syntaxhighlight lang="perl">
defmod sprit DOIF ##
attr sprit uiTable {package ui_Table;;}\
card([[Tankstelle:SuperE5:col3d],[Tankstelle:Diesel:col3d]],undef,"fuel\@silver",1.40,1.9,120,0,["E10","Diesel"],undef,"2,,fill:silver, €","130,autoscaling,steps,footer,ycolor,ring,200",undef,undef)
</syntaxhighlight>

''Ergebnis der Beispieldefinition in der Webansicht:''
[[Datei:Di uiTable sprit.png|ohne|mini]]

=== ''Visualisierung: '''aktuelle Corona-7-Tage-Inzidenz''''' ===
{{Randnotiz|RNText='''nützliche Links'''
* svg-Funktion [[DOIF/uiTable_Schnelleinstieg#ring-Funktionen|ring]]
* svg-Funktion [[DOIF/uiTable_Schnelleinstieg#Anzeige_eines_Werteverlaufs_und_des_aktuellen_Wertes_mit_Hilfe_der_SVG-Funktion_card|card]]
* Modul [[JsonMod]]
}}
Die aktuellen Inzidenzwerte werden vom RKI ausgelesen und deren Verlauf visualisiert.

Zunächst wird ein JsonMod Device für das Auslesen der Inzidenzzahlen definiert. Die gewünschten Regionen müssen für eigene Bedürfnisse angepasst werden.

<syntaxhighlight lang="perl">
defmod RKI7 JsonMod https://services7.arcgis.com/mOBPykOjAyBO2ZKk/arcgis/rest/services/RKI_Landkreisdaten/FeatureServer/0/query?where=1%3D1&outFields=last_update,cases7_per_100k,BEZ,BEM,GEN,BL,county&returnGeometry=false&outSR=4326&f=json
attr RKI7 readingList multi(jsonPath("\$.features[?(\@.attributes.GEN in ['Städteregion Aachen', 'Düren', 'Heinsberg'])]"), property('attributes.GEN'), sprintf('%.1f', property('attributes.cases7_per_100k')));;
</syntaxhighlight>

Visualisierung der Inzidenzzahlen der letzten sieben Tage:

<syntaxhighlight lang="perl">
defmod di_corona DOIF ##
attr di_corona uiTable {package ui_Table}\
card([RKI7:Duren:col1w],"Düren","coronavirus",0,200,120,0,"Fälle")|\
card([RKI7:Heinsberg:col1w],"Heinsberg","coronavirus",0,200,120,0,"Fälle")|\
card([RKI7:Stadteregion_Aachen:col1w],"Aachen","coronavirus",0,200,120,0,"Fälle")
</syntaxhighlight>

''Ergebnis der Beispieldefinition in der Webansicht:''
[[Datei:uiTable_Inzidenz.png|600px|links]]

<br clear="all">

=== '' Visualisierung und Steuerung: '''Heiztherme''''' ===
Im folgenden Beispiel wurde eine Heiztherme über einen ebus-Adapter in FHEM eingebunden. Die Heizungsdaten werden über MQTT ausgelesen und anschließend visualisiert. Die vorgestellten Visualisierungsbeispiele können ebenso im funktionslosen DOIF mit Hilfe des uiTable-Attriutes auf bereits existierende Readings des eigenen Systems angewendet werden.

{{Randnotiz|RNText='''nützliche Links'''
* svg-Funktion [[DOIF/uiTable_Schnelleinstieg#icon_ring-Funktionen|icon_ring]]
* svg-Funktion [[DOIF/uiTable_Schnelleinstieg#Anzeige_eines_Werteverlaufs_und_des_aktuellen_Wertes_mit_Hilfe_der_SVG-Funktion_card|card]]
* Commandref [https://fhem.de/commandref_DE.html#DOIF_Perl_Modus DOIF Perl-Modus]
* ebus-Adapter [https://ebusd.de/ ebusd]
* ebus-Wiki [[EBUS|ebus]]
}}
Definition eines DOIF-Devices zur Steuerung der Therme und Visualisierung der Daten. Es werden Readings und Befehle genutzt, die durch den MQTT2-Server zur Verfügung gestellt werden. Einzelne Heizungswerte werden in bestimmten Intervallen über den publish-Befehl ausgelesen. Die Temperaturen der Zirkulation, des Vorlaufs und des Rücklaufs werden außerhalb der Therme mit 1-wire-Temperatursensoren über WLAN-ESP-Easy ausgelesen. Die Definition des Layouts über das Attribut uiTable ist unabhängig vom Auslesen der Werte, sie bezieht sich lediglich auf vorhandene Readings, die visualisiert werden sollen. Das Layout kann ebenso auf Readings aus anderen Devices der eigenen FHEM-Umgebung anpasst werden.

<syntaxhighlight lang="perl">
defmod di_vaillant DOIF ##{[+00:01];;foreach (qw(FanSpeed Flame PumpPower Storageloadpump PrimaryCircuitFlowrate FlowTempDesired PumpHours HcHours HcPumpStarts)) {fhem_set("MQTT2_FHEM_Server publish ebusd/bai/$_/get")}}\
\
{[+[1]:01];;foreach (qw(PrEnergySumHc1 PrEnergySumHwc1 HcHours HwcHours z1OpMode WaterPressure z1NightTemp z1DayTemp Hc1HeatCurve HwcLockTime HolidayStartPeriod HolidayEndPeriod)) {fhem_set("MQTT2_FHEM_Server publish ebusd/bai/$_/get")}\
}\
\
{[+00:00:30];;foreach (qw(Flame PrimaryCircuitFlowrate)) {fhem_set("MQTT2_FHEM_Server publish ebusd/bai/$_/get")}}\
\
{[00:01];;foreach (qw(FanHours HcStarts HwcStarts )) {fhem_set("MQTT2_FHEM_Server publish ebusd/bai/$_/get")}\
set_Reading("gesamt_hc",int([?vaillant:PrEnergySumHc1_0_value]/10000)/10,0);;\
set_Reading("gesamt_hwc",int([?vaillant:PrEnergySumHwc1_0_value]/10000)/10,0);;\
set_Reading("diff_hc",0,1);;\
set_Reading("diff_hwc",0,1);;\
set_Reading("diff_h",0,1)\
}\
\
{if ([00:05|WE]) {fhem_set("MQTT2_FHEM_Server publish ebusd/700/BankHolidayStartPeriod/set $mday.$month.$year");;fhem_set("MQTT2_FHEM_Server publish ebusd/700/BankHolidayEndPeriod/set $mday.$month.$year")}}\
\
Timer {\
fhem_set "MQTT2_FHEM_Server publish ebusd/700/z1Timer.Monday/set 04:00;;09:00;;13:00;;22:00;;-:-;;-:-"\
fhem_set "MQTT2_FHEM_Server publish ebusd/700/z1Timer.Tuesday/set 04:00;;09:00;;13:00;;22:00;;-:-;;-:-"\
fhem_set "MQTT2_FHEM_Server publish ebusd/700/z1Timer.Wednesday/set 04:00;;09:00;;13:00;;22:00;;-:-;;-:-"\
fhem_set "MQTT2_FHEM_Server publish ebusd/700/z1Timer.Thursday/set 04:00;;09:00;;13:00;;22:00;;-:-;;-:-"\
fhem_set "MQTT2_FHEM_Server publish ebusd/700/z1Timer.Friday/set 04:00;;09:00;;13:00;;22:00;;-:-;;-:-"\
fhem_set "MQTT2_FHEM_Server publish ebusd/700/z1Timer.Sunday/set 05:00;;10:00;;12:00;;22:30;;-:-;;-:-"\
fhem_set "MQTT2_FHEM_Server publish ebusd/700/z1Timer.Saturday/set 05:00;;10:00;;12:00;;22:30;;-:-;;-:-"\
}\
\
diff {\
set_Reading("diff_hc",int(([vaillant:PrEnergySumHc1_0_value]/100000-get_Reading("gesamt_hc",0))*10)/10,1);;\
set_Reading("diff_hwc",int(([vaillant:PrEnergySumHwc1_0_value]/100000-get_Reading("gesamt_hwc",0))*10)/10,1);;\
set_Reading("diff_h",get_Reading("diff_hc")+get_Reading("diff_hwc"),1);;\
}\
\

attr di_vaillant event-on-change-reading .*
attr di_vaillant room Ebus
attr di_vaillant uiTable {\
package ui_Table;;\
$TABLE='text-align:center;;';;\
$SHOWNODEVICELINE = "test9|Damian";;\
}\
icon_temp_ring("temp_outside",[vaillant:Aussentemp],-15,40,130)|\
icon_temp_mring(([vaillant:Flame] eq "off"?"sani_boiler_temp\@white":"sani_boiler_temp\@Darkorange"),[vaillant:Vorlauf],15,70,130)|\
icon_temp_mring(([vaillant:Pumpenstatus] eq "4" ? "sani_buffer_temp_down\@Darkorange" : "sani_buffer_temp_down\@white"),[vaillant:WWSpeicher],15,70,130)|\
icon_uring("0,0,1","weather_barometric_pressure",[vaillant:Wasserdruck],0,3,undef,undef,"bar",1,130,[(0.8,0,1,60,1.5,120,1.7,60,3,0)],"50,35")|\
icon_ring("sani_floor_heating_neutral",[vaillant:HcHours_hoursum2_value],0,10000,120,0,"h",0,130)|\
icon_ring("sani_water_tap",[vaillant:HwcHours_hoursum2_value],0,2000,120,0,"h",0,130)|\
\
icon_ring("time_graph",[vaillant:HeizKennlinie],0.4,1,120,0,"HK",1,130)|\
icon_temp_mring("scene_day\@yellow",[vaillant:TagSolltemp],undef,undef,130)|\
icon_temp_mring("scene_night\@#3464eb",[vaillant:NachtSolltemp],undef,undef,130)\
""|""|""|""|""|""|widget([vaillant:HeizKennlinie],"selectnumbers,0.4,.1,1,1,lin","set")|widget([vaillant:TagSolltemp],"selectnumbers,15,1,25,1,lin","set")|widget([vaillant:NachtSolltemp],"selectnumbers,15,1,25,1,lin","set")<\
\
card([vaillant:Aussentemp:col],"Außentemperatur","temp_outside",-15,35,undef,undef,"°C",\&temp_hue)|\
card([vaillant:WWSpeicher:col],"WW-Speicher",([vaillant:Pumpenstatus] eq "4" ? "sani_buffer_temp_down\@Darkorange" : "sani_buffer_temp_down\@white"),15,70,undef,undef,"°C",\&temp_hue)|\
card([ESPEasy_ESP_Temp_Vorlauf:Temperature:col],"Vorlauf",([vaillant:Pumpenstatus] eq "on" ? "sani_floor_heating\@Darkorange" : "sani_floor_heating_neutral\@white"),15,70,undef,undef,"°C",\&temp_hue)|\
card([$SELF:diff_hc:col],"Energie Heizung","sani_floor_heating_neutral",0,100,120,0,"kWh",undef,1)\
card([vaillant:Umlaufmenge:col],"Umlaufmenge","sani_pump",0,20,120,0,"l/min")|\
card([ESPEasy_ESP_Temp_Zirkulation:Temperature:col],"Zirkulation",([Zirk] eq "off"?"sani_pump\@white":"sani_pump\@Darkorange"),15,70,undef,undef,"°C",\&temp_hue)|\
card([ESPEasy_ESP_Temp_Keller_Ruecklauf:Temperature:col],"Rücklauf","sani_floor_heating_neutral\@wite",15,70,undef,undef,"°C",\&temp_hue)|\
card([$SELF:diff_hwc:col],"Energie Warmwasser","sani_water_tap",0,15,120,0,"kWh",undef,1)
</syntaxhighlight>

''Ergebnis der Beispieldefinition in der Webansicht:''
[[Datei:Di uiTable Heizung.png|800px|links]]

<br clear="all">

=== ''Visualisierung: '''Anwesenheitsstatus''''' ===
{{Randnotiz|RNText='''nützliche Links'''
* [[FRITZBOX|FritzBox-Modul]]
* ui_Table Funktion [[DOIF/uiTable Schnelleinstieg#Icon-Darstellung mit Text mit Hilfe der Funktion icon_label|icon_label]]
*[[DOIF/uiTable Schnelleinstieg#uiTable-Templates|uiTable-Templates]]
}}
Die aktuelle Anwesenheit von Heimbewohnern wird visualisiert.<br><br>
Zunächst wird mit Hilfe des Moduls [[FRITZBOX]] ein Device namens ''FritzBox'' erstellt. Dort werden die eingebuchten Smartphones der Bewohner mit Ihren MAC-Adressen in Readings abgelegt. Die folgende Definition wertet aus, ob die angegebenen MAC-Adressen als Readings vorhanden sind und erstellt für jeden Bewohner ein Reading mit den Zuständen on/off. Diese Readings werden dann über das Attribut uiTable visualisiert. Die anwesenden Personen werden farblich markiert. Die Namen der Personen sowie die MAC-Adressen sind fiktiv und müssen den eigenen Angaben entsprechend angepasst werden.

<syntaxhighlight lang="perl">
defmod myHome DOIF {\
set_Reading_Begin;;\
set_Reading_Update("Ernie",[FritzBox:mac_12_34_E0_00_CD_E4] ? "on":"off");;\
set_Reading_Update("Bert", [FritzBox:mac_02_08_02_07_30_E3] ? "on":"off");;\
set_Reading_Update("Grobi", [FritzBox:mac_00_08_01_0B_00_E7] ? "on":"off");; \
set_Reading_Update("Kermit", [FritzBox:mac_01_30_A9_72_02_E3] ? "on":"off");; \
set_Reading_End(1);;\
}
attr myHome checkReadingEvent 0
attr myHome uiTable {\
package ui_Table;;\
$SHOWNOSTATE=1;;\
$TC{0..4}="align='center'";;\
}\
## Template-Definition für die Visualisierung eines Bewohners mit Hilfe des Icons fa__508\
DEF TPL_person (icon_label([$SELF:$1] eq "on" ? "fa__508\@DarkOrange":"fa__508","$1","#e67e00","white",-10))\
\
## Darstellung der Bewohner mit Hilfe des obigen Templates\
TPL_person(Ernie)|TPL_person(Bert)|TPL_person(Grobi)|TPL_person(Kermit)
</syntaxhighlight>

''Ergebnis der Beispieldefinition in der Webansicht:''
[[Datei:UiTable myHome.png|ohne|mini]]

=== Weiterführende Links ===
* [[DOIF/Perl-Modus]]
* [[DOIF/Automatisierung]]

== Weiterführende Links ==
* Weitere Beispiele für Fortgeschrittene, siehe "[[DOIF/uiTable|uiTable mit FHEM-Widgets und Styles]]"

[[Kategorie:FHEM Frontends]]
[[Kategorie:HOWTOS]]
[[Kategorie:Code Snippets]]

Mehrere USB-Geräte einbinden

2024-03-31T08:47:38Z

Ansgru: /* FreeBSD */

== Problembeschreibung ==
Nutzt man an einem FHEM-Server mehrere USB-Geräte, insbesondere als [[Interface|Interface]], ist es wichtig, diese so einzubinden, dass sie von FHEM jeweils korrekt angesprochen werden. Hierzu ist eine eindeutige Addressierung im USB-System erforderlich.
{{Hinweis|Sofern neben FHEM noch weitere Dienste auf der Server-Hardware aktiv sind, die auf Hardware an USB-Schnittstellen zugreift (z.B. ein HM-IP-USB-Stick für eine virtualisierte CCUx oder ConBee-Dongles für deconz bzw. USB-Dongles für zigbee2mqtt betr. ZigBee), empfiehlt es sich, auch bei diesen Diensten nach Möglichkeiten zu forschen, die von diesen angesprochenen USB-Geräte auch von deren Seite eindeutig zu adressieren.}}

== Linux ==
=== Hintergrund ===
In einem Linux-System erfolgt die Einbindung zunächst häufig über allgemeine Standardpfade wie ''/dev/ttyUSB0'' oder ''/dev/ttyACM0''. Steckt man im laufenden Betrieb ein weiteres Interface ein, erscheint dieses ohne Neustart des Rechners erst einmal unter dem nächsten freien Standardpfad, also z.B. ''/dev/ttyUSB1''. Allerdings kann es sein, dass die Zuordnung beim nächsten Systemstart genau umgekehrt ist, sich also das Gerät, das unter ''/dev/ttyUSB1'' zu finden war, nunmehr unter ''/dev/ttyUSB0'' zu erreichen ist. Hierdurch funktionieren die Geräte nicht mehr, wenn sie in FHEM über diese allgemeinen Schnittstellenbezeichnungen in der DEF eingebunden waren. Dies gilt vor allem dann, wenn diese völlig unterschiedliche Funktionen haben, andere Baud-Raten verwenden oder andere Initialisierungscodes erwarten.

Ensprechendes gilt, wenn die Geräte später entfernt werden und/oder danach ggf. an einem anderen USB-Port verwendet.

Da die Geräte im Verlauf der Einbindung in das USB-System einige Informationen austauschen, gibt es mehrere Möglichkeiten, dieses unerwünschte Verhalten zu unterbinden.

=== Nutzen der Serial ID ===
Um dies zu umgehen, kann man sie über ihre Serial-ID in FHEM einbinden.

Dieser Befehl zeigt die Serial-ID:

:<code>ls -l /dev/serial/by-id</code>

Hier die Beispielausgabe eines CUL868, JeeLink, RFXtrx und eines CUL433

user@xxxx:~# ls -l /dev/serial/by-id
lrwxrwxrwx 1 root root 13 Jan 9 23:34 usb-busware.de_CUL868-if00 -> ../../ttyACM0
lrwxrwxrwx 1 root root 13 Jan 9 13:26 usb-FTDI_FT232R_USB_UART_A901RQ9F-if00-port0-> ../../ttyUSB0
lrwxrwxrwx 1 root root 13 Jan 9 13:26 usb-RFXCOM_RFXtrx433_A1WZWL5Y-if00-port0-> ../../ttyUSB1
lrwxrwxrwx 1 root root 13 Jan 9 21:29 usb-busware.de_CUL433-if00 -> ../../ttyACM1

Damit lässt sich folgende Definition erstellen:

z.B. für einen CUL868

:<code>define CUL868 CUL /dev/serial/by-id/usb-busware.de_CUL868-if00@9600 1134</code>

oder einen JeeLink

:<code>define Jeelink JeeLink /dev/serial/by-id/usb-FTDI_FT232R_USB_UART_A901RQ9F-if00-port0@57600</code>

{{Hinweis|Nutzt man die "by-id"-Methode, empfiehlt es sich, dies für alle USB-Geräte zu verwenden. Ist man gezwungen, "by-path" zu verwenden, sollte man letzteres auf die problematischen Geräte beschränken und eindeutige Geräte weiter mit "by-id" addressieren.}}

=== Problemfälle: by-id ===
Bei CULs von Busware lassen sich nur CUL433 und CUL868 unterscheiden. Zwei CUL868 haben z.B. immer die gleiche Serial-ID. Entsprechendes gilt, wenn man mehrere Produkte mit gleicher "by-id"-Kennung nutzt. Dies betrifft z.B. Arduino-Nano-Klone mit CHG340/CHG341 USB-Serial-Wandler (/dev/serial/by-id/usb-1a86_USB2.0-Serial-if00-port0), [[CP2102|CP2102-Wandler]] (10c4:ea60) oder Prolific-Produkte.
Lösungsansätze sind weiter unten aufgeführt, man kann in solchen Fällen jedoch auch die problematischen Geräte über die Angaben einbinden, welche man über :<code>ls -l /dev/serial/by-path</code> erhält.
Das Vorgehen entspricht im Übrigen dem für "by-id".

=== udev-Rules ===
Man kann mittels udev-Rules auch die Angaben zur Serial-ID und/oder der ''py-path'' dazu nutzen, den jeweiligen Geräten einen eindeutigen Namen zuzuweisen.
Detaillierte Erläuterungen zu udev:
* [https://wiki.debian.org/udev https://wiki.debian.org/udev]
* [https://wiki.ubuntuusers.de/udev/ https://wiki.ubuntuusers.de/udev/]
* [https://wiki.archlinux.de/title/Udev https://wiki.archlinux.de/title/Udev]

== Windows ==
Links zur Anbindung von USB-COM-Port-Geräten
* [https://www.uhlenbrock.de/de_DE/service/faq/software/I23A3243-001.htm!ArcEntryInfo=0004.18.I23A3243&NewServerName=zeta COM-PORT Einstellungen unter Windows 10 ändern - bebilderte Anleitung]
* [http://heise.de/-2150736 Nicht angeschlossene Geräte unter Windows loswerden]
* [https://www.uwe-sieber.de/comportman.html ComPortMan - Windows-Dienst zur Kontrolle über die Zuordnung von COM-Ports]
* [https://www.ftdichip.com/Support/Documents/AppNotes/AN_132_Re-Assigning_COM_Port_Numbers_Using_Registry.pdf FTDI Application Note Re-Assigning COM Port Numbers Using the Windows Registry]

== FreeBSD ==
=== Hintergrund ===
USB zu seriell Adapter (z.B. für RS485/Modbus, Arduinos etc) tauchen unter FreeBSD als ''/dev/cuaU*'' Geräte auf. Das macht es schwierig, sie in FHEM einzubinden da sich beim Umstecken etc. der Gerätename ändern kann und dann der Adapter z.B. nicht mehr unter ''cuaU0'' sondern unter ''cuaU1'' etc. zu finden ist.
=== Nutzen der Serial ID ===
Unter Linux haben die Adapter eine eindeutige Kennung (z.B. als ''/dev/serial/by-id/usb-FTDI_FT232R_USB_UART_A10KVD0Q-if00-port0''). In FreeBSD kann man das wie folgt nachbauen:

> cat /usr/local/etc/devd/rs485.conf
attach 1000 {
match "sernum" "AB0LHFXT|AB0MG4RO|A10KVD0Q";
action "ln -sf /dev/cua$ttyname /dev/waveshare_$sernum && ln -sf /dev/cua$ttyname.lock /dev/waveshare_$sernum.lock && ln -sf /dev/cua$ttyname.init /dev/waveshare_$sernum.init";
};

notify 1000 {
match "sernum" "AB0LHFXT|AB0MG4RO|A10KVD0Q";
match "type" "DETACH";
match "subsystem" "DEVICE";
action "rm /dev/waveshare_$sernum && rm /dev/waveshare_$sernum.init && rm /dev/waveshare_$sernum.lock";
};

In diesem Beispiel sind die Adapter mit Seriennummer AB0LHFXT, AB0MG4RO oder A10KVD0Q eindeutig als ''/dev/waveshare_'''Seriennummer''''' ansprechbar und lassen sich entsprechend in FHEM einbinden.

Die Seriennummer (oder zur Not auch der USB Pfad für Adapter, die keine Seriennummer haben (wie z.B. CH340 Chips)) lässt sich mit
:<code>usbconfig -d ugen1.11 dump_all_desc</code>
herausfinden wenn das Gerät bereits eingesteckt ist oder aber mit einem laufenden
:<code>cat /var/run/devd.pipe </code>
und dann einem anschliessen des Gerätes.

=== ECMD ===
Regelmässiges Abfragen scheinen dazu zu führen, dass FHEM hängt.

== Hilfsmittel ==
=== CUL-firmware modifizieren ===
Für Original CULs sowie Klone auf ATMega32U4-Basis kann man die Kennung im Quellcode der culfw ändern, unter der sich der Microkontroller später im USB-System anmeldet.

=== FTDI-Chips ===
FTDI-Wandler sollten eigentlich von Hause aus mit einer eindeutigen Seriennummer versehen sein. Sollte dies nicht der Fall sein, kann man dies nachholen. FTDI bietet hierzu ein Tool an, unter Linux kann man hierfür [http://rtr.ca/ft232r/ ft232r_prog] verwenden. Allerdings kann es insbesondere bei der Windows-Software von FTDI zu Problemen kommen, wenn es sich um einen geklonten Chip handelt.

=== CP2102 ===
Für Linux ist [http://cp210x-program.sourceforge.net/ hier] ein in Python-Tool verfügbar.
Beispiel für die gleichzeitige Nutzung von drei Modulen (eines davon mit bereits geänderter Kennung - dieses wird in "by-id" gelistet, das andere (noch) nicht):

lsusb
Bus 002 Device 017: ID 10c4:ea60 Cygnal Integrated Products, Inc. CP210x UART Bridge / myAVR mySmartUSB light
Bus 002 Device 015: ID 10c4:ea60 Cygnal Integrated Products, Inc. CP210x UART Bridge / myAVR mySmartUSB light
Bus 002 Device 016: ID 10c4:ea60 Cygnal Integrated Products, Inc. CP210x UART Bridge / myAVR mySmartUSB light

ls -l /dev/serial/by-path
lrwxrwxrwx 1 root root 13 Jun 9 16:33 pci-0000:00:1d.0-usb-0:1.1.2:1.0-port0 -> ../../ttyUSB2
lrwxrwxrwx 1 root root 13 Jun 9 16:33 pci-0000:00:1d.0-usb-0:1.1.3:1.0-port0 -> ../../ttyUSB0
lrwxrwxrwx 1 root root 13 Jun 9 16:33 pci-0000:00:1d.0-usb-0:1.1.4:1.0-port0 -> ../../ttyUSB1

ls -l /dev/serial/by-id
lrwxrwxrwx 1 root root 13 Jun 9 16:33 usb-Silicon_Labs_CP2102_USB_to_UART_Bridge_Controller_0001-if00-port0 -> ../../ttyUSB2
lrwxrwxrwx 1 root root 13 Jun 9 16:33 usb-Silicon_Labs_Multi_TTL_RS485_0003-if00-port0 -> ../../ttyUSB0
{{Hinweis|Dabei sollte nicht die VID oder PID verändert werden, Änderungen der Seriennummer oder der Produktkennung (product-string) sind jedoch gefahrlos möglich, ebenso die der Herstellerkennung (vendor-string), die allerdings ein --force-eeprom erfordert (Linux).}}

== Links ==
<references />
[[Kategorie:FAQ]]
[[Kategorie:Other Components]]
[[Kategorie:FHEM-Verwendung]]

Mehrere USB-Geräte einbinden

2024-03-31T08:42:33Z

Ansgru: Hinzufügen FreeBSD

== Problembeschreibung ==
Nutzt man an einem FHEM-Server mehrere USB-Geräte, insbesondere als [[Interface|Interface]], ist es wichtig, diese so einzubinden, dass sie von FHEM jeweils korrekt angesprochen werden. Hierzu ist eine eindeutige Addressierung im USB-System erforderlich.
{{Hinweis|Sofern neben FHEM noch weitere Dienste auf der Server-Hardware aktiv sind, die auf Hardware an USB-Schnittstellen zugreift (z.B. ein HM-IP-USB-Stick für eine virtualisierte CCUx oder ConBee-Dongles für deconz bzw. USB-Dongles für zigbee2mqtt betr. ZigBee), empfiehlt es sich, auch bei diesen Diensten nach Möglichkeiten zu forschen, die von diesen angesprochenen USB-Geräte auch von deren Seite eindeutig zu adressieren.}}

== Linux ==
=== Hintergrund ===
In einem Linux-System erfolgt die Einbindung zunächst häufig über allgemeine Standardpfade wie ''/dev/ttyUSB0'' oder ''/dev/ttyACM0''. Steckt man im laufenden Betrieb ein weiteres Interface ein, erscheint dieses ohne Neustart des Rechners erst einmal unter dem nächsten freien Standardpfad, also z.B. ''/dev/ttyUSB1''. Allerdings kann es sein, dass die Zuordnung beim nächsten Systemstart genau umgekehrt ist, sich also das Gerät, das unter ''/dev/ttyUSB1'' zu finden war, nunmehr unter ''/dev/ttyUSB0'' zu erreichen ist. Hierdurch funktionieren die Geräte nicht mehr, wenn sie in FHEM über diese allgemeinen Schnittstellenbezeichnungen in der DEF eingebunden waren. Dies gilt vor allem dann, wenn diese völlig unterschiedliche Funktionen haben, andere Baud-Raten verwenden oder andere Initialisierungscodes erwarten.

Ensprechendes gilt, wenn die Geräte später entfernt werden und/oder danach ggf. an einem anderen USB-Port verwendet.

Da die Geräte im Verlauf der Einbindung in das USB-System einige Informationen austauschen, gibt es mehrere Möglichkeiten, dieses unerwünschte Verhalten zu unterbinden.

=== Nutzen der Serial ID ===
Um dies zu umgehen, kann man sie über ihre Serial-ID in FHEM einbinden.

Dieser Befehl zeigt die Serial-ID:

:<code>ls -l /dev/serial/by-id</code>

Hier die Beispielausgabe eines CUL868, JeeLink, RFXtrx und eines CUL433

user@xxxx:~# ls -l /dev/serial/by-id
lrwxrwxrwx 1 root root 13 Jan 9 23:34 usb-busware.de_CUL868-if00 -> ../../ttyACM0
lrwxrwxrwx 1 root root 13 Jan 9 13:26 usb-FTDI_FT232R_USB_UART_A901RQ9F-if00-port0-> ../../ttyUSB0
lrwxrwxrwx 1 root root 13 Jan 9 13:26 usb-RFXCOM_RFXtrx433_A1WZWL5Y-if00-port0-> ../../ttyUSB1
lrwxrwxrwx 1 root root 13 Jan 9 21:29 usb-busware.de_CUL433-if00 -> ../../ttyACM1

Damit lässt sich folgende Definition erstellen:

z.B. für einen CUL868

:<code>define CUL868 CUL /dev/serial/by-id/usb-busware.de_CUL868-if00@9600 1134</code>

oder einen JeeLink

:<code>define Jeelink JeeLink /dev/serial/by-id/usb-FTDI_FT232R_USB_UART_A901RQ9F-if00-port0@57600</code>

{{Hinweis|Nutzt man die "by-id"-Methode, empfiehlt es sich, dies für alle USB-Geräte zu verwenden. Ist man gezwungen, "by-path" zu verwenden, sollte man letzteres auf die problematischen Geräte beschränken und eindeutige Geräte weiter mit "by-id" addressieren.}}

=== Problemfälle: by-id ===
Bei CULs von Busware lassen sich nur CUL433 und CUL868 unterscheiden. Zwei CUL868 haben z.B. immer die gleiche Serial-ID. Entsprechendes gilt, wenn man mehrere Produkte mit gleicher "by-id"-Kennung nutzt. Dies betrifft z.B. Arduino-Nano-Klone mit CHG340/CHG341 USB-Serial-Wandler (/dev/serial/by-id/usb-1a86_USB2.0-Serial-if00-port0), [[CP2102|CP2102-Wandler]] (10c4:ea60) oder Prolific-Produkte.
Lösungsansätze sind weiter unten aufgeführt, man kann in solchen Fällen jedoch auch die problematischen Geräte über die Angaben einbinden, welche man über :<code>ls -l /dev/serial/by-path</code> erhält.
Das Vorgehen entspricht im Übrigen dem für "by-id".

=== udev-Rules ===
Man kann mittels udev-Rules auch die Angaben zur Serial-ID und/oder der ''py-path'' dazu nutzen, den jeweiligen Geräten einen eindeutigen Namen zuzuweisen.
Detaillierte Erläuterungen zu udev:
* [https://wiki.debian.org/udev https://wiki.debian.org/udev]
* [https://wiki.ubuntuusers.de/udev/ https://wiki.ubuntuusers.de/udev/]
* [https://wiki.archlinux.de/title/Udev https://wiki.archlinux.de/title/Udev]

== Windows ==
Links zur Anbindung von USB-COM-Port-Geräten
* [https://www.uhlenbrock.de/de_DE/service/faq/software/I23A3243-001.htm!ArcEntryInfo=0004.18.I23A3243&NewServerName=zeta COM-PORT Einstellungen unter Windows 10 ändern - bebilderte Anleitung]
* [http://heise.de/-2150736 Nicht angeschlossene Geräte unter Windows loswerden]
* [https://www.uwe-sieber.de/comportman.html ComPortMan - Windows-Dienst zur Kontrolle über die Zuordnung von COM-Ports]
* [https://www.ftdichip.com/Support/Documents/AppNotes/AN_132_Re-Assigning_COM_Port_Numbers_Using_Registry.pdf FTDI Application Note Re-Assigning COM Port Numbers Using the Windows Registry]

== FreeBSD ==
=== Hintergrund ===
USB zu seriell Adapter (z.B. für RS485/Modbus, Arduinos etc) tauchen unter FreeBSD als ''/dev/cuaU*'' Geräte auf. Das macht es schwierig, sie in FHEM einzubinden da sich beim Umstecken etc. der Gerätename ändern kann und dann der Adapter z.B. nicht mehr unter ''cuaU0'' sondern unter ''cuaU1'' etc. zu finden ist.
=== Nutzen der Serial ID ===
Unter Linux haben die Adapter eine eindeutige Kennung (z.B. als ''/dev/serial/by-id/usb-FTDI_FT232R_USB_UART_A10KVD0Q-if00-port0''). In FreeBSD kann man das wie folgt nachbauen:

> cat /usr/local/etc/devd/rs485.conf
attach 1000 {
match "sernum" "AB0LHFXT|AB0MG4RO|A10KVD0Q";
action "ln -sf /dev/cua$ttyname /dev/waveshare_$sernum && ln -sf /dev/cua$ttyname.lock /dev/waveshare_$sernum.lock && ln -sf /dev/cua$ttyname.init /dev/waveshare_$sernum.init";
};

notify 1000 {
match "sernum" "AB0LHFXT|AB0MG4RO|A10KVD0Q";
match "type" "DETACH";
match "subsystem" "DEVICE";
action "rm /dev/waveshare_$sernum && rm /dev/waveshare_$sernum.init && rm /dev/waveshare_$sernum.lock";
};

In diesem Beispiel sind die Adapter mit Seriennummer AB0LHFXT, AB0MG4RO oder A10KVD0Q eindeutig als ''/dev/waveshare_'''Seriennummer''''' ansprechbar und lassen sich entsprechend in FHEM einbinden.

Die Seriennummer (oder zur Not auch der USB Pfad für Adapter, die keine Seriennummer haben (wie z.B. CH340 Chips)) lässt sich mit
:<code>usbconfig -d ugen1.11 dump_all_desc</code>
herausfinden wenn das Gerät bereits eingesteckt ist oder aber mit einem laufenden
:<code>cat /var/run/devd.pipe </code>
und dann einem anschliessen des Gerätes.

== Hilfsmittel ==
=== CUL-firmware modifizieren ===
Für Original CULs sowie Klone auf ATMega32U4-Basis kann man die Kennung im Quellcode der culfw ändern, unter der sich der Microkontroller später im USB-System anmeldet.

=== FTDI-Chips ===
FTDI-Wandler sollten eigentlich von Hause aus mit einer eindeutigen Seriennummer versehen sein. Sollte dies nicht der Fall sein, kann man dies nachholen. FTDI bietet hierzu ein Tool an, unter Linux kann man hierfür [http://rtr.ca/ft232r/ ft232r_prog] verwenden. Allerdings kann es insbesondere bei der Windows-Software von FTDI zu Problemen kommen, wenn es sich um einen geklonten Chip handelt.

=== CP2102 ===
Für Linux ist [http://cp210x-program.sourceforge.net/ hier] ein in Python-Tool verfügbar.
Beispiel für die gleichzeitige Nutzung von drei Modulen (eines davon mit bereits geänderter Kennung - dieses wird in "by-id" gelistet, das andere (noch) nicht):

lsusb
Bus 002 Device 017: ID 10c4:ea60 Cygnal Integrated Products, Inc. CP210x UART Bridge / myAVR mySmartUSB light
Bus 002 Device 015: ID 10c4:ea60 Cygnal Integrated Products, Inc. CP210x UART Bridge / myAVR mySmartUSB light
Bus 002 Device 016: ID 10c4:ea60 Cygnal Integrated Products, Inc. CP210x UART Bridge / myAVR mySmartUSB light

ls -l /dev/serial/by-path
lrwxrwxrwx 1 root root 13 Jun 9 16:33 pci-0000:00:1d.0-usb-0:1.1.2:1.0-port0 -> ../../ttyUSB2
lrwxrwxrwx 1 root root 13 Jun 9 16:33 pci-0000:00:1d.0-usb-0:1.1.3:1.0-port0 -> ../../ttyUSB0
lrwxrwxrwx 1 root root 13 Jun 9 16:33 pci-0000:00:1d.0-usb-0:1.1.4:1.0-port0 -> ../../ttyUSB1

ls -l /dev/serial/by-id
lrwxrwxrwx 1 root root 13 Jun 9 16:33 usb-Silicon_Labs_CP2102_USB_to_UART_Bridge_Controller_0001-if00-port0 -> ../../ttyUSB2
lrwxrwxrwx 1 root root 13 Jun 9 16:33 usb-Silicon_Labs_Multi_TTL_RS485_0003-if00-port0 -> ../../ttyUSB0
{{Hinweis|Dabei sollte nicht die VID oder PID verändert werden, Änderungen der Seriennummer oder der Produktkennung (product-string) sind jedoch gefahrlos möglich, ebenso die der Herstellerkennung (vendor-string), die allerdings ein --force-eeprom erfordert (Linux).}}

== Links ==
<references />
[[Kategorie:FAQ]]
[[Kategorie:Other Components]]
[[Kategorie:FHEM-Verwendung]]

Gleitende Mittelwerte berechnen und loggen

2022-07-19T07:13:13Z

Ansgru: Formatierung

Für verschiedene Wettersensoren ist es oftmals wünschenswert, gleitende Mittelwerte (fälschlich auch als "relative" Mittelwerte bezeichnet) über ein bestimmtes Zeitfenster auszugeben oder in den Logs zu speichern und zu plotten. Beispiele:
* Die momentanen Winddaten eines KS300 sind oft stark schwankend. Hier wäre ein Mittelwert z.B. der letzten 2-3 Stunden interessant.
* Für die Außentemperatur ist anhand eines Mittelwertes der letzten 24 Stunden evtl. ein gewisser Trend der generellen Entwicklung der Temperatur ableitbar.

Mit Modulen wie ''rain'' oder ''average'' ist konzeptbedingt nur ein Mittelwert von fixen Zeiträumen (aktueller Tag, Monat, etc.) möglich.

Im Nachfolgenden werden deshalb zwei Programme vorgestellt, die solche gleitenden Mittelwerte bereitstellen. Beide Programme werden in die Datei [[99 myUtils anlegen|99_MyUtils.pm]] eingetragen und dann von FHEM aufgerufen. Das erste Programm macht dies für beliebige Readings beliebiger Devices, das zweite Programm greift auf beliebige [[FileLog|File-]] oder [[DbLog|DbLogs]] zurück.

== Gleitender Mittelwert für beliebige Readings ==
=== Subroutine movingAverage in 99_MyUtils anlegen ===
Zuerst muss die Subroutine ''movingAverage'' in die 99_MyUtils übernommen werden. Wenn noch nicht vorhanden, sollte die Datei dann so aussehen:

<nowiki>package main;
use strict;
use warnings;
sub
MyUtils_Initialize($$)
{
my ($hash) = @_;
}
###############################################################################
#
# Moving average
#
# Aufruf: movingAverage(devicename,readingname,zeitspanne in s)
#
###############################################################################

sub movingAverage($$$){
my ($name,$reading,$avtime) = @_;
my $hash = $defs{$name};
my @new = my ($val,$time) = ($hash->{READINGS}{$reading}{VAL},$hash->{READINGS}{$reading}{TIME});
my ($cyear, $cmonth, $cday, $chour, $cmin, $csec) = $time =~ /(\d+)-(\d+)-(\d+)\s(\d+):(\d+):(\d+)/;
my $ctime = $csec+60*$cmin+3600*$chour;
my $num;
my $arr;
#-- initialize if requested
if( ($avtime eq "-1") ){
$hash->{READINGS}{$reading}{"history"}=undef;
}
#-- test for existence
if( !$hash->{READINGS}{$reading}{"history"}){
#Log 1,"ARRAY CREATED";
push(@{$hash->{READINGS}{$reading}{"history"}},\@new);
$num = 1;
$arr=\@{$hash->{READINGS}{$reading}{"history"}};
} else {
$num = int(@{$hash->{READINGS}{$reading}{"history"}});
$arr=\@{$hash->{READINGS}{$reading}{"history"}};
my $starttime = $arr->[0][1];
my ($syear, $smonth, $sday, $shour, $smin, $ssec) = $starttime =~ /(\d+)-(\d+)-(\d+)\s(\d+):(\d+):(\d+)/;
my $stime = $ssec+60*$smin+3600*$shour;
#-- correct for daybreak
$stime-=86400
if( $stime > $ctime);
if( ($num < 25)&&( ($ctime-$stime)<$avtime) ){
#Log 1,"ARRAY has $num elements, adding another one";
push(@{$hash->{READINGS}{$reading}{"history"}},\@new);
}else{
shift(@{$hash->{READINGS}{$reading}{"history"}});
push(@{$hash->{READINGS}{$reading}{"history"}},\@new);
}
}
#-- output and average
my $average = 0;
for(my $i=0;$i<$num;$i++){
$average+=$arr->[$i][0];
Log 4,"[$name moving average] Value = ".$arr->[$i][0]." Time = ".$arr->[$i][1];
}
$average=sprintf( "%5.3f", $average/$num);
#--average
Log 4,"[$name moving average] calculated over $num values is $average";
return $average;
}

1;</nowiki>

=== Funktion movingAverage() aufrufen und nutzen ===
Bei jedem Aufruf schiebt die obige Funktion den gegenwärtigen Wert sowie den Zeitpunkt eines Readings (zweiter Parameter) ans Ende eines Arrays (maximal 25 Einträge) und wirft dafür den ersten Eintrag heraus. Die Anzahl der Einträge im Array wird so gewählt, dass die Zeitpunkte der Readings größer oder gleich der gewünschten Zeitspanne für die Mittelung sind. Über diese Werte wird dann gemittelt und der Wert zurückgegeben.

Zur Anwendung empfiehlt sich, dem gewünschten Device ein userReading zu geben:
:<code>attr devicename userReadings readingname.av {movingAverage("devicename","readingname",zeitspanne)}</code>

Dieses wird dann automatisch bei jedem neuen Wert des Readings mit dem neuen gleitenden Mittelwert über die vergangene Zeitspanne gefüllt.

Beispiel: Das Reading "pressure" des Devices "A.OWB" wird alle 5 Minuten aktualisiert. Das Device bekommt nun ein userReading:
:<code>attr A.OWB userReadings pressure.av {movingAverage("A.OWB","pressure",1800)}</code>

Dieses schreibt bei jeder Aktualisierung von "pressure" einen neuen Eintrag in sein Array - allerdings maximal sechs Werte, dann wird immer der älteste Eintrag gelöscht. Damit ist sichergestellt, dass diese mindestens 1800 Sekunden abdecken - also sechs Einträge.

== Gleitender Mittelwert aus Log-Dateien ==
=== Subroutine myAverage() in 99_MyUtils anlegen ===
Zuerst muss die Subroutine myAverage in die 99_MyUtils übernommen werden. Wenn noch nicht vorhanden, sollte die Datei dann so aussehen:

package main;
use strict;
use warnings;
sub
MyUtils_Initialize($$)
{
my ($hash) = @_;
}
##########################################################
# myAverage
# berechnet den Mittelwert aus LogFiles über einen beliebigen Zeitraum
sub
myAverage($$$)
{
my ($offset,$logfile,$cspec) = @_;
my $period_s = strftime "%Y-%m-%d\x5f%H:%M:%S", localtime(time-$offset);
my $period_e = strftime "%Y-%m-%d\x5f%H:%M:%S", localtime;
my $oll = $attr{global}{verbose};
$attr{global}{verbose} = 0;
my @logdata = split("\n", fhem("get $logfile - - $period_s $period_e $cspec"));
$attr{global}{verbose} = $oll;
my ($cnt, $cum, $avg) = (0)x3;
foreach (@logdata){
my @line = split(" ", $_);
if(defined $line[1] && $line[1] ne ""){
$cnt += 1;
$cum += $line[1];
}
}
if("$cnt" > 0){$avg = sprintf("%0.1f", $cum/$cnt)};
Log 4, ("myAverage: File: $logfile, Field: $cspec, Period: $period_s bis $period_e, Count: $cnt, Cum: $cum, Average: $avg");
return $avg;
}
##########################################################
1;

=== Funktion myAverage() aufrufen und nutzen ===
Jetzt kann die Funktion <code>myAverage(<offset>, <logfile>, <column-spec>)</code> ganz normal auf der FHEM-Konsole (telnet localhost 7072) genutzt werden. Hier z.B. die Ausgabe des Mittelwertes des Windsensors, eines KS300, über die letzten drei Stunden (Angabe in 3*3600s) oder der Temperaturmittelwert der letzten 24 Stunden.

Mit FileLog:

<nowiki>fhem> {myAverage("10800", "FileLog_KS300", "8:::")}
6.3
fhem> {myAverage("86400", "FileLog_KS300", "4:::")}
-2.7
fhem></nowiki>

Mit DbLog:

<nowiki>fhem> {myAverage("10800", "myDbLog", "KS300:wind::")}
5.9
fhem> {myAverage("86400", "myDbLog", "KS300:temperature::")}
-2.7
fhem></nowiki>

Ähnlich ist die Verwendung in perl-Code in der [[Konfiguration|fhem.cfg]]:

<nowiki>my $avg = myAverage("10800", "FileLog_KS300", "8:::");;\</nowiki>
Ein [[notify]], welches bei jedem neuen Sensorwert die Mitteltemperatur der letzten 24 Stunden als Event "average-temp xy" ins Logfile schreibt, sieht dann wie folgt aus:

<nowiki>define KS300_T_notify notify KS300:temperature.* {\
fhem('trigger KS300 average-temp: '.myAverage("86400", "FileLog_KS300", "4:::"));;\
}</nowiki>


Analog dazu wäre mit den Winddaten zu verfahren.

== Gleitender Mittelwert und Minimum und Maximum aus Log-Dateien ==

Manchmal interessieren einem auch Minimum und Maximum Werte über einen bestimmten Zeitraum, die Funktion ''myAverage'' kann einfach entsprechend abgeändert werden:

=== Subroutine avgMinMaxAusLog() in 99_MyUtils anlegen ===

# Berechnet den Mittelwert, Minimum und Maximum aus LogFiles über einen beliebigen Zeitraum
# Args: $offset = Offset in Sekunden
# $logfile = LogFile, z.B. DbLog Device
# $cspec = column-spec, siehe https://fhem.de/commandref_DE.html#DbLog -> get
sub avgMinMaxAusLog($$$) {
my($offset, $logfile, $cspec) = @_;
my $period_s = strftime "%Y-%m-%d\x5f%H:%M:%S", localtime(time - $offset);
my $period_e = strftime "%Y-%m-%d\x5f%H:%M:%S", localtime;
my $oll = $attr { global } { verbose };
$attr { global } { verbose } = 0;
my @logdata = split("\n", fhem("get $logfile - - $period_s $period_e $cspec"));
$attr { global } { verbose } = $oll;
my ($cnt, $cum, $avg, $min, $max) = (0)x5;
foreach(@logdata) {
my @line = split(" ", $_);
if (defined $line[1] && $line[1] ne "") {
$cnt += 1;
$cum += $line[1];
# Beim ersten Eintrag min/max setzen
if ($cnt == 1) {
$min = $line[1];
$max = $line[1];
# Bei den darauffolgenden Einträgen $min/max ermitteln
} else {
if ($line[1] < $min) { $min = $line[1]; }
if ($line[1] > $max) { $max = $line[1]; }
}
}
}
if ("$cnt" > 0) {
$avg = sprintf("%0.1f", $cum / $cnt)
};
Log 4, ("avgMinMaxAusLog: File: $logfile, Field: $cspec, Period: $period_s bis $period_e, Count: $cnt, Cum: $cum, Average: $avg, Minimum: $min, Maximum: $max");
return ($avg, $min, $max);
}

Anwendung wie oben. Statt nur dem Mittelwert wird eine Liste zurückgeliefert mit Mittelwert, Minimum und Maximum. Verwendung z.B. wie folgt:

<nowiki>my ($avg, $min, $max) = myAverage("10800", "FileLog_KS300", "8:::");;\</nowiki>

== Eigenes Filelog und Plot ==
==== Definitionen ====
Ich schreibe ein komplett eigenes Logfile und lasse über eine spezielle gplot-Definition die Temperatur- und Winddaten loggen und plotten.

<nowiki>define KS300_W dummy
define KS300_W_notify notify KS300:wind.* {\
my $avg = myAverage("10800", "FileLog_KS300", "8:::");;\
my $event = sprintf("Wc: %0.1f Wd: %0.1f Wm: %0.1f Wlh: %0.1f", ReadingsVal("KS300","wind","0"), ReadingsVal("KS300","W_avg_day","0"), ReadingsVal("KS300","W_avg_month","0"), $avg);;\
Log 2, ("K300_W: Event: $event");;\
fhem("trigger KS300_W data: $event");;\
fhem("trigger KS300 average-wind: $avg");;\
}
define FileLog_KS300_W FileLog ./log/KS300_W-%Y.log KS300_W.*
attr FileLog_KS300_W logtype text
attr FileLog_KS300_W room Logs
define KS300_TH dummy
define KS300_TH_notify notify KS300:temperature.* {\
my $avg = myAverage("86400", "FileLog_KS300", "4:::");;\
my $event = sprintf("Tc: %0.1f Hc: %0.1f Tavg: %0.1f", ReadingsVal("KS300","temperature","0"), ReadingsVal("KS300","humidity","0"), $avg);;\
Log 2, ("K300_TH: Event: $event");;\
fhem("trigger KS300_TH data: $event");;\
fhem('trigger KS300 average-temp: '.$avg);;\
}
define FileLog_KS300_TH FileLog ./log/KS300_TH-%Y.log KS300_TH.*
attr FileLog_KS300_TH logtype text
attr FileLog_KS300_TH room Logs</nowiki>
Die Definitionen für die Plots schauen so aus:

<nowiki>define weblink_KS300_W weblink fileplot FileLog_KS300_W:ks300_wind:CURRENT
attr weblink_KS300_W label "Wind - Min: $data{min1}, Max: $data{max1}, Last: $data{currval1}"
attr weblink_KS300_W room Dachterasse
define weblink_KS300_TH weblink fileplot FileLog_KS300_TH:ks300_temphum:CURRENT
attr weblink_KS300_TH label "Temperatur/Feuchte - Min: $data{min1}, Max: $data{max1}, Last: $data{currval1}"
attr weblink_KS300_TH room Dachterasse
define weblink_KS300_R weblink fileplot FileLog_KS300:ks300_rain10:CURRENT
attr weblink_KS300_R label "Regen - Min: $data{min1}, Max: $data{max1}, Last: $data{currval1}"
attr weblink_KS300_R room Dachterasse</nowiki>

==== Angepasste gplot-Dateien ====
Nun noch die speziellen gplot-Dateien.
ks300_wind.gplot

<nowiki>############################
# Display the wind values of a KS300.
# Corresponding FileLog definition:
# define <filelogname> FileLog ./log/KS300_W-%Y.log KS300_W.*
set terminal png transparent size <SIZE> crop
set output '<OUT>.png'
set xdata time
set timefmt "%Y-%m-%d_%H:%M:%S"
set xlabel " "
set ytics nomirror
#set y2tics
set ytics
set title '<L1>'
set grid xtics ytics
set yrange [0:]
set y2range [0:]
set ylabel "Wind (aktuell) [km/h]"
set y2label "Wind (gemittelt) [km/h]"
set format y2 "%0.1f"
#FileLog 5:Wc\x3a:0:
#FileLog 11:Wlh\x3a:0:
plot "<IN>" using 1:5 ls l7fill axes x1y1 title 'Wind (aktuell)' with lines,\
"<IN>" using 1:11 ls l5 axes x1y2 title 'Wind (3h-Mittel)' with steps,\</nowiki>

ks300_temphum.gplot

<nowiki>############################
# Display the Temperature und Humidity values of a KS300.
# Corresponding FileLog definition:
# define <filelogname> FileLog ./log/KS300_TH-%Y.log KS300_TH.*
set terminal png transparent size <SIZE> crop
set output '<OUT>.png'
set xdata time
set timefmt "%Y-%m-%d_%H:%M:%S"
set xlabel " "
set ytics nomirror
set y2tics
#set ytics
set title '<L1>'
set grid xtics y2tics
set y2label "Temperatur [°C]"
set ylabel "Luftfeuchte [%]"
#FileLog 5:Tc\x3a:0:
#FileLog 9:Tavg\x3a:0:
#FileLog 7:Hc\x3a:0:
plot "<IN>" using 1:5 axes x1y2 ls l0 title 'Temperatur' with lines,\
"<IN>" using 1:9 axes x1y2 ls l10 title 'Temperatur (24h-Mittel)' with lines,\
"<IN>" using 1:7 axes x1y1 ls l2fill title 'Luftfeuchte' with lines</nowiki>
Den Plot für den Regen habe ich noch um Punkt-Plots für den israining-Status erweitert, so dass Punkte bei "yes" geplottet werden.

ks300_rain10.gplot

<nowiki>############################
# Display the Rain values of a KS300.
# Corresponding FileLog definition:
# define <filelogname> FileLog ./log/KS300-%Y.log KS300:T:.*
set terminal png transparent size <SIZE> crop
set output '<OUT>.png'
set xdata time
set timefmt "%Y-%m-%d_%H:%M:%S"
set xlabel " "
set ytics nomirror
#set y2tics
set ytics
set title '<L1>'
set grid xtics ytics
set y2range [0.5:1.5]
set y2tics ("" 0, "Regen" 1)
set pointsize 7
set ylabel "Regen (l/m²)"
set yrange [0:]
# Computing Rain/h and Rain/d values by accumulating the changes.
#FileLog 10:IR\x3a:0:delta-h
#FileLog 10:IR\x3a:0:delta-d
#FileLog 12:IR:0:$fld[11]=~"yes"?1:0
plot "<grep -v avg_ <IN> | perl -ane '\
@a = split(\"[_:]\", $F[0]);\
if(defined($lh) && $lh ne $a[1])\
{ printf(\"${ld}_$lh:30:00 %f\n\", $hv); $hv = 0; }\
if($lv) { $hv += ($F[9]-$lv); }\
$lh = $a[1]; $ld = $a[0]; $lv = $F[9];\
END { printf(\"${ld}_$lh:30:00 %f\n\", $hv) }'"\
using 1:2 axes x1y1 ls l1fill title 'Regen pro Stunde' with histeps,\
"<grep -v avg_ <IN> | perl -ane '\
@a = split(\"[_]\", $F[0]);\
if(defined($ld) && $ld ne $a[0]) {\
printf(\"${ld}_12:00:00 %f\n\", $dv); $dv = 0; }\
if($lv) { $dv += ($F[9]-$lv); }\
$ld = $a[0]; $lv = $F[9];\
END {printf(\"${ld}_12:00:00 %f\n\", $dv)}'"\
using 1:2 axes x1y1 ls l7 title 'Regen pro Tag' with histeps
"<grep -v avg_ <IN> | awk '{print $1, $12==\"yes\"? 1 : 0; }'"\
using 1:2 axes x1y2 ls l11fill title 'Regen aktuell' with points</nowiki>
Eventuell müssen in den gplots noch die Linienstile/Farben den eigenen Bedürfnissen angepasst werden. Ich verwende hier eigene Farben und Füllungen.

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

Gleitende Mittelwerte berechnen und loggen

2022-07-19T07:11:40Z

Ansgru: Ergänzt um erweiterte Funktion mit Min/Max Werten

Für verschiedene Wettersensoren ist es oftmals wünschenswert, gleitende Mittelwerte (fälschlich auch als "relative" Mittelwerte bezeichnet) über ein bestimmtes Zeitfenster auszugeben oder in den Logs zu speichern und zu plotten. Beispiele:
* Die momentanen Winddaten eines KS300 sind oft stark schwankend. Hier wäre ein Mittelwert z.B. der letzten 2-3 Stunden interessant.
* Für die Außentemperatur ist anhand eines Mittelwertes der letzten 24 Stunden evtl. ein gewisser Trend der generellen Entwicklung der Temperatur ableitbar.

Mit Modulen wie ''rain'' oder ''average'' ist konzeptbedingt nur ein Mittelwert von fixen Zeiträumen (aktueller Tag, Monat, etc.) möglich.

Im Nachfolgenden werden deshalb zwei Programme vorgestellt, die solche gleitenden Mittelwerte bereitstellen. Beide Programme werden in die Datei [[99 myUtils anlegen|99_MyUtils.pm]] eingetragen und dann von FHEM aufgerufen. Das erste Programm macht dies für beliebige Readings beliebiger Devices, das zweite Programm greift auf beliebige [[FileLog|File-]] oder [[DbLog|DbLogs]] zurück.

== Gleitender Mittelwert für beliebige Readings ==
=== Subroutine movingAverage in 99_MyUtils anlegen ===
Zuerst muss die Subroutine ''movingAverage'' in die 99_MyUtils übernommen werden. Wenn noch nicht vorhanden, sollte die Datei dann so aussehen:

<nowiki>package main;
use strict;
use warnings;
sub
MyUtils_Initialize($$)
{
my ($hash) = @_;
}
###############################################################################
#
# Moving average
#
# Aufruf: movingAverage(devicename,readingname,zeitspanne in s)
#
###############################################################################

sub movingAverage($$$){
my ($name,$reading,$avtime) = @_;
my $hash = $defs{$name};
my @new = my ($val,$time) = ($hash->{READINGS}{$reading}{VAL},$hash->{READINGS}{$reading}{TIME});
my ($cyear, $cmonth, $cday, $chour, $cmin, $csec) = $time =~ /(\d+)-(\d+)-(\d+)\s(\d+):(\d+):(\d+)/;
my $ctime = $csec+60*$cmin+3600*$chour;
my $num;
my $arr;
#-- initialize if requested
if( ($avtime eq "-1") ){
$hash->{READINGS}{$reading}{"history"}=undef;
}
#-- test for existence
if( !$hash->{READINGS}{$reading}{"history"}){
#Log 1,"ARRAY CREATED";
push(@{$hash->{READINGS}{$reading}{"history"}},\@new);
$num = 1;
$arr=\@{$hash->{READINGS}{$reading}{"history"}};
} else {
$num = int(@{$hash->{READINGS}{$reading}{"history"}});
$arr=\@{$hash->{READINGS}{$reading}{"history"}};
my $starttime = $arr->[0][1];
my ($syear, $smonth, $sday, $shour, $smin, $ssec) = $starttime =~ /(\d+)-(\d+)-(\d+)\s(\d+):(\d+):(\d+)/;
my $stime = $ssec+60*$smin+3600*$shour;
#-- correct for daybreak
$stime-=86400
if( $stime > $ctime);
if( ($num < 25)&&( ($ctime-$stime)<$avtime) ){
#Log 1,"ARRAY has $num elements, adding another one";
push(@{$hash->{READINGS}{$reading}{"history"}},\@new);
}else{
shift(@{$hash->{READINGS}{$reading}{"history"}});
push(@{$hash->{READINGS}{$reading}{"history"}},\@new);
}
}
#-- output and average
my $average = 0;
for(my $i=0;$i<$num;$i++){
$average+=$arr->[$i][0];
Log 4,"[$name moving average] Value = ".$arr->[$i][0]." Time = ".$arr->[$i][1];
}
$average=sprintf( "%5.3f", $average/$num);
#--average
Log 4,"[$name moving average] calculated over $num values is $average";
return $average;
}

1;</nowiki>

=== Funktion movingAverage() aufrufen und nutzen ===
Bei jedem Aufruf schiebt die obige Funktion den gegenwärtigen Wert sowie den Zeitpunkt eines Readings (zweiter Parameter) ans Ende eines Arrays (maximal 25 Einträge) und wirft dafür den ersten Eintrag heraus. Die Anzahl der Einträge im Array wird so gewählt, dass die Zeitpunkte der Readings größer oder gleich der gewünschten Zeitspanne für die Mittelung sind. Über diese Werte wird dann gemittelt und der Wert zurückgegeben.

Zur Anwendung empfiehlt sich, dem gewünschten Device ein userReading zu geben:
:<code>attr devicename userReadings readingname.av {movingAverage("devicename","readingname",zeitspanne)}</code>

Dieses wird dann automatisch bei jedem neuen Wert des Readings mit dem neuen gleitenden Mittelwert über die vergangene Zeitspanne gefüllt.

Beispiel: Das Reading "pressure" des Devices "A.OWB" wird alle 5 Minuten aktualisiert. Das Device bekommt nun ein userReading:
:<code>attr A.OWB userReadings pressure.av {movingAverage("A.OWB","pressure",1800)}</code>

Dieses schreibt bei jeder Aktualisierung von "pressure" einen neuen Eintrag in sein Array - allerdings maximal sechs Werte, dann wird immer der älteste Eintrag gelöscht. Damit ist sichergestellt, dass diese mindestens 1800 Sekunden abdecken - also sechs Einträge.

== Gleitender Mittelwert aus Log-Dateien ==
=== Subroutine myAverage() in 99_MyUtils anlegen ===
Zuerst muss die Subroutine myAverage in die 99_MyUtils übernommen werden. Wenn noch nicht vorhanden, sollte die Datei dann so aussehen:

package main;
use strict;
use warnings;
sub
MyUtils_Initialize($$)
{
my ($hash) = @_;
}
##########################################################
# myAverage
# berechnet den Mittelwert aus LogFiles über einen beliebigen Zeitraum
sub
myAverage($$$)
{
my ($offset,$logfile,$cspec) = @_;
my $period_s = strftime "%Y-%m-%d\x5f%H:%M:%S", localtime(time-$offset);
my $period_e = strftime "%Y-%m-%d\x5f%H:%M:%S", localtime;
my $oll = $attr{global}{verbose};
$attr{global}{verbose} = 0;
my @logdata = split("\n", fhem("get $logfile - - $period_s $period_e $cspec"));
$attr{global}{verbose} = $oll;
my ($cnt, $cum, $avg) = (0)x3;
foreach (@logdata){
my @line = split(" ", $_);
if(defined $line[1] && $line[1] ne ""){
$cnt += 1;
$cum += $line[1];
}
}
if("$cnt" > 0){$avg = sprintf("%0.1f", $cum/$cnt)};
Log 4, ("myAverage: File: $logfile, Field: $cspec, Period: $period_s bis $period_e, Count: $cnt, Cum: $cum, Average: $avg");
return $avg;
}
##########################################################
1;

=== Funktion myAverage() aufrufen und nutzen ===
Jetzt kann die Funktion <code>myAverage(<offset>, <logfile>, <column-spec>)</code> ganz normal auf der FHEM-Konsole (telnet localhost 7072) genutzt werden. Hier z.B. die Ausgabe des Mittelwertes des Windsensors, eines KS300, über die letzten drei Stunden (Angabe in 3*3600s) oder der Temperaturmittelwert der letzten 24 Stunden.

Mit FileLog:

<nowiki>fhem> {myAverage("10800", "FileLog_KS300", "8:::")}
6.3
fhem> {myAverage("86400", "FileLog_KS300", "4:::")}
-2.7
fhem></nowiki>

Mit DbLog:

<nowiki>fhem> {myAverage("10800", "myDbLog", "KS300:wind::")}
5.9
fhem> {myAverage("86400", "myDbLog", "KS300:temperature::")}
-2.7
fhem></nowiki>

Ähnlich ist die Verwendung in perl-Code in der [[Konfiguration|fhem.cfg]]:

<nowiki>my $avg = myAverage("10800", "FileLog_KS300", "8:::");;\</nowiki>
Ein [[notify]], welches bei jedem neuen Sensorwert die Mitteltemperatur der letzten 24 Stunden als Event "average-temp xy" ins Logfile schreibt, sieht dann wie folgt aus:

<nowiki>define KS300_T_notify notify KS300:temperature.* {\
fhem('trigger KS300 average-temp: '.myAverage("86400", "FileLog_KS300", "4:::"));;\
}</nowiki>


Analog dazu wäre mit den Winddaten zu verfahren.

== Gleitender Mittelwert und Minimum und Maximum aus Log-Dateien ==

Manchmal interessieren einem auch Minimum und Maximum Werte über einen bestimmten Zeitraum, die Funktion ''myAverage'' kann einfach entsprechend abgeändert werden:

# Berechnet den Mittelwert, Minimum und Maximum aus LogFiles über einen beliebigen Zeitraum
# Args: $offset = Offset in Sekunden
# $logfile = LogFile, z.B. DbLog Device
# $cspec = column-spec, siehe https://fhem.de/commandref_DE.html#DbLog -> get
sub avgMinMaxAusLog($$$) {
my($offset, $logfile, $cspec) = @_;
my $period_s = strftime "%Y-%m-%d\x5f%H:%M:%S", localtime(time - $offset);
my $period_e = strftime "%Y-%m-%d\x5f%H:%M:%S", localtime;
my $oll = $attr { global } { verbose };
$attr { global } { verbose } = 0;
my @logdata = split("\n", fhem("get $logfile - - $period_s $period_e $cspec"));
$attr { global } { verbose } = $oll;
my ($cnt, $cum, $avg, $min, $max) = (0)x5;
foreach(@logdata) {
my @line = split(" ", $_);
if (defined $line[1] && $line[1] ne "") {
$cnt += 1;
$cum += $line[1];
# Beim ersten Eintrag min/max setzen
if ($cnt == 1) {
$min = $line[1];
$max = $line[1];
# Bei den darauffolgenden Einträgen $min/max ermitteln
} else {
if ($line[1] < $min) { $min = $line[1]; }
if ($line[1] > $max) { $max = $line[1]; }
}
}
}
if ("$cnt" > 0) {
$avg = sprintf("%0.1f", $cum / $cnt)
};
Log 4, ("avgMinMaxAusLog: File: $logfile, Field: $cspec, Period: $period_s bis $period_e, Count: $cnt, Cum: $cum, Average: $avg, Minimum: $min, Maximum: $max");
return ($avg, $min, $max);
}

Anwendung wie oben. Statt nur dem Mittelwert wird eine Liste zurückgeliefert mit Mittelwert, Minimum und Maximum. Verwendung z.B. wie folgt:

<nowiki>my ($avg, $min, $max) = myAverage("10800", "FileLog_KS300", "8:::");;\</nowiki>

=== Subroutine avgMinMaxAusLog() in 99_MyUtils anlegen ===

=== Eigenes Filelog und Plot ===
==== Definitionen ====
Ich schreibe ein komplett eigenes Logfile und lasse über eine spezielle gplot-Definition die Temperatur- und Winddaten loggen und plotten.

<nowiki>define KS300_W dummy
define KS300_W_notify notify KS300:wind.* {\
my $avg = myAverage("10800", "FileLog_KS300", "8:::");;\
my $event = sprintf("Wc: %0.1f Wd: %0.1f Wm: %0.1f Wlh: %0.1f", ReadingsVal("KS300","wind","0"), ReadingsVal("KS300","W_avg_day","0"), ReadingsVal("KS300","W_avg_month","0"), $avg);;\
Log 2, ("K300_W: Event: $event");;\
fhem("trigger KS300_W data: $event");;\
fhem("trigger KS300 average-wind: $avg");;\
}
define FileLog_KS300_W FileLog ./log/KS300_W-%Y.log KS300_W.*
attr FileLog_KS300_W logtype text
attr FileLog_KS300_W room Logs
define KS300_TH dummy
define KS300_TH_notify notify KS300:temperature.* {\
my $avg = myAverage("86400", "FileLog_KS300", "4:::");;\
my $event = sprintf("Tc: %0.1f Hc: %0.1f Tavg: %0.1f", ReadingsVal("KS300","temperature","0"), ReadingsVal("KS300","humidity","0"), $avg);;\
Log 2, ("K300_TH: Event: $event");;\
fhem("trigger KS300_TH data: $event");;\
fhem('trigger KS300 average-temp: '.$avg);;\
}
define FileLog_KS300_TH FileLog ./log/KS300_TH-%Y.log KS300_TH.*
attr FileLog_KS300_TH logtype text
attr FileLog_KS300_TH room Logs</nowiki>
Die Definitionen für die Plots schauen so aus:

<nowiki>define weblink_KS300_W weblink fileplot FileLog_KS300_W:ks300_wind:CURRENT
attr weblink_KS300_W label "Wind - Min: $data{min1}, Max: $data{max1}, Last: $data{currval1}"
attr weblink_KS300_W room Dachterasse
define weblink_KS300_TH weblink fileplot FileLog_KS300_TH:ks300_temphum:CURRENT
attr weblink_KS300_TH label "Temperatur/Feuchte - Min: $data{min1}, Max: $data{max1}, Last: $data{currval1}"
attr weblink_KS300_TH room Dachterasse
define weblink_KS300_R weblink fileplot FileLog_KS300:ks300_rain10:CURRENT
attr weblink_KS300_R label "Regen - Min: $data{min1}, Max: $data{max1}, Last: $data{currval1}"
attr weblink_KS300_R room Dachterasse</nowiki>

==== Angepasste gplot-Dateien ====
Nun noch die speziellen gplot-Dateien.
ks300_wind.gplot

<nowiki>############################
# Display the wind values of a KS300.
# Corresponding FileLog definition:
# define <filelogname> FileLog ./log/KS300_W-%Y.log KS300_W.*
set terminal png transparent size <SIZE> crop
set output '<OUT>.png'
set xdata time
set timefmt "%Y-%m-%d_%H:%M:%S"
set xlabel " "
set ytics nomirror
#set y2tics
set ytics
set title '<L1>'
set grid xtics ytics
set yrange [0:]
set y2range [0:]
set ylabel "Wind (aktuell) [km/h]"
set y2label "Wind (gemittelt) [km/h]"
set format y2 "%0.1f"
#FileLog 5:Wc\x3a:0:
#FileLog 11:Wlh\x3a:0:
plot "<IN>" using 1:5 ls l7fill axes x1y1 title 'Wind (aktuell)' with lines,\
"<IN>" using 1:11 ls l5 axes x1y2 title 'Wind (3h-Mittel)' with steps,\</nowiki>

ks300_temphum.gplot

<nowiki>############################
# Display the Temperature und Humidity values of a KS300.
# Corresponding FileLog definition:
# define <filelogname> FileLog ./log/KS300_TH-%Y.log KS300_TH.*
set terminal png transparent size <SIZE> crop
set output '<OUT>.png'
set xdata time
set timefmt "%Y-%m-%d_%H:%M:%S"
set xlabel " "
set ytics nomirror
set y2tics
#set ytics
set title '<L1>'
set grid xtics y2tics
set y2label "Temperatur [°C]"
set ylabel "Luftfeuchte [%]"
#FileLog 5:Tc\x3a:0:
#FileLog 9:Tavg\x3a:0:
#FileLog 7:Hc\x3a:0:
plot "<IN>" using 1:5 axes x1y2 ls l0 title 'Temperatur' with lines,\
"<IN>" using 1:9 axes x1y2 ls l10 title 'Temperatur (24h-Mittel)' with lines,\
"<IN>" using 1:7 axes x1y1 ls l2fill title 'Luftfeuchte' with lines</nowiki>
Den Plot für den Regen habe ich noch um Punkt-Plots für den israining-Status erweitert, so dass Punkte bei "yes" geplottet werden.

ks300_rain10.gplot

<nowiki>############################
# Display the Rain values of a KS300.
# Corresponding FileLog definition:
# define <filelogname> FileLog ./log/KS300-%Y.log KS300:T:.*
set terminal png transparent size <SIZE> crop
set output '<OUT>.png'
set xdata time
set timefmt "%Y-%m-%d_%H:%M:%S"
set xlabel " "
set ytics nomirror
#set y2tics
set ytics
set title '<L1>'
set grid xtics ytics
set y2range [0.5:1.5]
set y2tics ("" 0, "Regen" 1)
set pointsize 7
set ylabel "Regen (l/m²)"
set yrange [0:]
# Computing Rain/h and Rain/d values by accumulating the changes.
#FileLog 10:IR\x3a:0:delta-h
#FileLog 10:IR\x3a:0:delta-d
#FileLog 12:IR:0:$fld[11]=~"yes"?1:0
plot "<grep -v avg_ <IN> | perl -ane '\
@a = split(\"[_:]\", $F[0]);\
if(defined($lh) && $lh ne $a[1])\
{ printf(\"${ld}_$lh:30:00 %f\n\", $hv); $hv = 0; }\
if($lv) { $hv += ($F[9]-$lv); }\
$lh = $a[1]; $ld = $a[0]; $lv = $F[9];\
END { printf(\"${ld}_$lh:30:00 %f\n\", $hv) }'"\
using 1:2 axes x1y1 ls l1fill title 'Regen pro Stunde' with histeps,\
"<grep -v avg_ <IN> | perl -ane '\
@a = split(\"[_]\", $F[0]);\
if(defined($ld) && $ld ne $a[0]) {\
printf(\"${ld}_12:00:00 %f\n\", $dv); $dv = 0; }\
if($lv) { $dv += ($F[9]-$lv); }\
$ld = $a[0]; $lv = $F[9];\
END {printf(\"${ld}_12:00:00 %f\n\", $dv)}'"\
using 1:2 axes x1y1 ls l7 title 'Regen pro Tag' with histeps
"<grep -v avg_ <IN> | awk '{print $1, $12==\"yes\"? 1 : 0; }'"\
using 1:2 axes x1y2 ls l11fill title 'Regen aktuell' with points</nowiki>
Eventuell müssen in den gplots noch die Linienstile/Farben den eigenen Bedürfnissen angepasst werden. Ich verwende hier eigene Farben und Füllungen.

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

Gleitende Mittelwerte berechnen und loggen

2022-07-19T07:07:50Z

Ansgru: Hochkomma um "$line[1]" entfernt

Für verschiedene Wettersensoren ist es oftmals wünschenswert, gleitende Mittelwerte (fälschlich auch als "relative" Mittelwerte bezeichnet) über ein bestimmtes Zeitfenster auszugeben oder in den Logs zu speichern und zu plotten. Beispiele:
* Die momentanen Winddaten eines KS300 sind oft stark schwankend. Hier wäre ein Mittelwert z.B. der letzten 2-3 Stunden interessant.
* Für die Außentemperatur ist anhand eines Mittelwertes der letzten 24 Stunden evtl. ein gewisser Trend der generellen Entwicklung der Temperatur ableitbar.

Mit Modulen wie ''rain'' oder ''average'' ist konzeptbedingt nur ein Mittelwert von fixen Zeiträumen (aktueller Tag, Monat, etc.) möglich.

Im Nachfolgenden werden deshalb zwei Programme vorgestellt, die solche gleitenden Mittelwerte bereitstellen. Beide Programme werden in die Datei [[99 myUtils anlegen|99_MyUtils.pm]] eingetragen und dann von FHEM aufgerufen. Das erste Programm macht dies für beliebige Readings beliebiger Devices, das zweite Programm greift auf beliebige [[FileLog|File-]] oder [[DbLog|DbLogs]] zurück.

== Gleitender Mittelwert für beliebige Readings ==
=== Subroutine movingAverage in 99_MyUtils anlegen ===
Zuerst muss die Subroutine ''movingAverage'' in die 99_MyUtils übernommen werden. Wenn noch nicht vorhanden, sollte die Datei dann so aussehen:

<nowiki>package main;
use strict;
use warnings;
sub
MyUtils_Initialize($$)
{
my ($hash) = @_;
}
###############################################################################
#
# Moving average
#
# Aufruf: movingAverage(devicename,readingname,zeitspanne in s)
#
###############################################################################

sub movingAverage($$$){
my ($name,$reading,$avtime) = @_;
my $hash = $defs{$name};
my @new = my ($val,$time) = ($hash->{READINGS}{$reading}{VAL},$hash->{READINGS}{$reading}{TIME});
my ($cyear, $cmonth, $cday, $chour, $cmin, $csec) = $time =~ /(\d+)-(\d+)-(\d+)\s(\d+):(\d+):(\d+)/;
my $ctime = $csec+60*$cmin+3600*$chour;
my $num;
my $arr;
#-- initialize if requested
if( ($avtime eq "-1") ){
$hash->{READINGS}{$reading}{"history"}=undef;
}
#-- test for existence
if( !$hash->{READINGS}{$reading}{"history"}){
#Log 1,"ARRAY CREATED";
push(@{$hash->{READINGS}{$reading}{"history"}},\@new);
$num = 1;
$arr=\@{$hash->{READINGS}{$reading}{"history"}};
} else {
$num = int(@{$hash->{READINGS}{$reading}{"history"}});
$arr=\@{$hash->{READINGS}{$reading}{"history"}};
my $starttime = $arr->[0][1];
my ($syear, $smonth, $sday, $shour, $smin, $ssec) = $starttime =~ /(\d+)-(\d+)-(\d+)\s(\d+):(\d+):(\d+)/;
my $stime = $ssec+60*$smin+3600*$shour;
#-- correct for daybreak
$stime-=86400
if( $stime > $ctime);
if( ($num < 25)&&( ($ctime-$stime)<$avtime) ){
#Log 1,"ARRAY has $num elements, adding another one";
push(@{$hash->{READINGS}{$reading}{"history"}},\@new);
}else{
shift(@{$hash->{READINGS}{$reading}{"history"}});
push(@{$hash->{READINGS}{$reading}{"history"}},\@new);
}
}
#-- output and average
my $average = 0;
for(my $i=0;$i<$num;$i++){
$average+=$arr->[$i][0];
Log 4,"[$name moving average] Value = ".$arr->[$i][0]." Time = ".$arr->[$i][1];
}
$average=sprintf( "%5.3f", $average/$num);
#--average
Log 4,"[$name moving average] calculated over $num values is $average";
return $average;
}

1;</nowiki>

=== Funktion movingAverage() aufrufen und nutzen ===
Bei jedem Aufruf schiebt die obige Funktion den gegenwärtigen Wert sowie den Zeitpunkt eines Readings (zweiter Parameter) ans Ende eines Arrays (maximal 25 Einträge) und wirft dafür den ersten Eintrag heraus. Die Anzahl der Einträge im Array wird so gewählt, dass die Zeitpunkte der Readings größer oder gleich der gewünschten Zeitspanne für die Mittelung sind. Über diese Werte wird dann gemittelt und der Wert zurückgegeben.

Zur Anwendung empfiehlt sich, dem gewünschten Device ein userReading zu geben:
:<code>attr devicename userReadings readingname.av {movingAverage("devicename","readingname",zeitspanne)}</code>

Dieses wird dann automatisch bei jedem neuen Wert des Readings mit dem neuen gleitenden Mittelwert über die vergangene Zeitspanne gefüllt.

Beispiel: Das Reading "pressure" des Devices "A.OWB" wird alle 5 Minuten aktualisiert. Das Device bekommt nun ein userReading:
:<code>attr A.OWB userReadings pressure.av {movingAverage("A.OWB","pressure",1800)}</code>

Dieses schreibt bei jeder Aktualisierung von "pressure" einen neuen Eintrag in sein Array - allerdings maximal sechs Werte, dann wird immer der älteste Eintrag gelöscht. Damit ist sichergestellt, dass diese mindestens 1800 Sekunden abdecken - also sechs Einträge.

== Gleitender Mittelwert aus Log-Dateien ==
=== Subroutine myAverage() in 99_MyUtils anlegen ===
Zuerst muss die Subroutine myAverage in die 99_MyUtils übernommen werden. Wenn noch nicht vorhanden, sollte die Datei dann so aussehen:

package main;
use strict;
use warnings;
sub
MyUtils_Initialize($$)
{
my ($hash) = @_;
}
##########################################################
# myAverage
# berechnet den Mittelwert aus LogFiles über einen beliebigen Zeitraum
sub
myAverage($$$)
{
my ($offset,$logfile,$cspec) = @_;
my $period_s = strftime "%Y-%m-%d\x5f%H:%M:%S", localtime(time-$offset);
my $period_e = strftime "%Y-%m-%d\x5f%H:%M:%S", localtime;
my $oll = $attr{global}{verbose};
$attr{global}{verbose} = 0;
my @logdata = split("\n", fhem("get $logfile - - $period_s $period_e $cspec"));
$attr{global}{verbose} = $oll;
my ($cnt, $cum, $avg) = (0)x3;
foreach (@logdata){
my @line = split(" ", $_);
if(defined $line[1] && $line[1] ne ""){
$cnt += 1;
$cum += $line[1];
}
}
if("$cnt" > 0){$avg = sprintf("%0.1f", $cum/$cnt)};
Log 4, ("myAverage: File: $logfile, Field: $cspec, Period: $period_s bis $period_e, Count: $cnt, Cum: $cum, Average: $avg");
return $avg;
}
##########################################################
1;

=== Funktion myAverage() aufrufen und nutzen ===
Jetzt kann die Funktion <code>myAverage(<offset>, <logfile>, <column-spec>)</code> ganz normal auf der FHEM-Konsole (telnet localhost 7072) genutzt werden. Hier z.B. die Ausgabe des Mittelwertes des Windsensors, eines KS300, über die letzten drei Stunden (Angabe in 3*3600s) oder der Temperaturmittelwert der letzten 24 Stunden.

Mit FileLog:

<nowiki>fhem> {myAverage("10800", "FileLog_KS300", "8:::")}
6.3
fhem> {myAverage("86400", "FileLog_KS300", "4:::")}
-2.7
fhem></nowiki>

Mit DbLog:

<nowiki>fhem> {myAverage("10800", "myDbLog", "KS300:wind::")}
5.9
fhem> {myAverage("86400", "myDbLog", "KS300:temperature::")}
-2.7
fhem></nowiki>

Ähnlich ist die Verwendung in perl-Code in der [[Konfiguration|fhem.cfg]]:

<nowiki>my $avg = myAverage("10800", "FileLog_KS300", "8:::");;\</nowiki>
Ein [[notify]], welches bei jedem neuen Sensorwert die Mitteltemperatur der letzten 24 Stunden als Event "average-temp xy" ins Logfile schreibt, sieht dann wie folgt aus:

<nowiki>define KS300_T_notify notify KS300:temperature.* {\
fhem('trigger KS300 average-temp: '.myAverage("86400", "FileLog_KS300", "4:::"));;\
}</nowiki>


Analog dazu wäre mit den Winddaten zu verfahren.

=== Eigenes Filelog und Plot ===
==== Definitionen ====
Ich schreibe ein komplett eigenes Logfile und lasse über eine spezielle gplot-Definition die Temperatur- und Winddaten loggen und plotten.

<nowiki>define KS300_W dummy
define KS300_W_notify notify KS300:wind.* {\
my $avg = myAverage("10800", "FileLog_KS300", "8:::");;\
my $event = sprintf("Wc: %0.1f Wd: %0.1f Wm: %0.1f Wlh: %0.1f", ReadingsVal("KS300","wind","0"), ReadingsVal("KS300","W_avg_day","0"), ReadingsVal("KS300","W_avg_month","0"), $avg);;\
Log 2, ("K300_W: Event: $event");;\
fhem("trigger KS300_W data: $event");;\
fhem("trigger KS300 average-wind: $avg");;\
}
define FileLog_KS300_W FileLog ./log/KS300_W-%Y.log KS300_W.*
attr FileLog_KS300_W logtype text
attr FileLog_KS300_W room Logs
define KS300_TH dummy
define KS300_TH_notify notify KS300:temperature.* {\
my $avg = myAverage("86400", "FileLog_KS300", "4:::");;\
my $event = sprintf("Tc: %0.1f Hc: %0.1f Tavg: %0.1f", ReadingsVal("KS300","temperature","0"), ReadingsVal("KS300","humidity","0"), $avg);;\
Log 2, ("K300_TH: Event: $event");;\
fhem("trigger KS300_TH data: $event");;\
fhem('trigger KS300 average-temp: '.$avg);;\
}
define FileLog_KS300_TH FileLog ./log/KS300_TH-%Y.log KS300_TH.*
attr FileLog_KS300_TH logtype text
attr FileLog_KS300_TH room Logs</nowiki>
Die Definitionen für die Plots schauen so aus:

<nowiki>define weblink_KS300_W weblink fileplot FileLog_KS300_W:ks300_wind:CURRENT
attr weblink_KS300_W label "Wind - Min: $data{min1}, Max: $data{max1}, Last: $data{currval1}"
attr weblink_KS300_W room Dachterasse
define weblink_KS300_TH weblink fileplot FileLog_KS300_TH:ks300_temphum:CURRENT
attr weblink_KS300_TH label "Temperatur/Feuchte - Min: $data{min1}, Max: $data{max1}, Last: $data{currval1}"
attr weblink_KS300_TH room Dachterasse
define weblink_KS300_R weblink fileplot FileLog_KS300:ks300_rain10:CURRENT
attr weblink_KS300_R label "Regen - Min: $data{min1}, Max: $data{max1}, Last: $data{currval1}"
attr weblink_KS300_R room Dachterasse</nowiki>

==== Angepasste gplot-Dateien ====
Nun noch die speziellen gplot-Dateien.
ks300_wind.gplot

<nowiki>############################
# Display the wind values of a KS300.
# Corresponding FileLog definition:
# define <filelogname> FileLog ./log/KS300_W-%Y.log KS300_W.*
set terminal png transparent size <SIZE> crop
set output '<OUT>.png'
set xdata time
set timefmt "%Y-%m-%d_%H:%M:%S"
set xlabel " "
set ytics nomirror
#set y2tics
set ytics
set title '<L1>'
set grid xtics ytics
set yrange [0:]
set y2range [0:]
set ylabel "Wind (aktuell) [km/h]"
set y2label "Wind (gemittelt) [km/h]"
set format y2 "%0.1f"
#FileLog 5:Wc\x3a:0:
#FileLog 11:Wlh\x3a:0:
plot "<IN>" using 1:5 ls l7fill axes x1y1 title 'Wind (aktuell)' with lines,\
"<IN>" using 1:11 ls l5 axes x1y2 title 'Wind (3h-Mittel)' with steps,\</nowiki>

ks300_temphum.gplot

<nowiki>############################
# Display the Temperature und Humidity values of a KS300.
# Corresponding FileLog definition:
# define <filelogname> FileLog ./log/KS300_TH-%Y.log KS300_TH.*
set terminal png transparent size <SIZE> crop
set output '<OUT>.png'
set xdata time
set timefmt "%Y-%m-%d_%H:%M:%S"
set xlabel " "
set ytics nomirror
set y2tics
#set ytics
set title '<L1>'
set grid xtics y2tics
set y2label "Temperatur [°C]"
set ylabel "Luftfeuchte [%]"
#FileLog 5:Tc\x3a:0:
#FileLog 9:Tavg\x3a:0:
#FileLog 7:Hc\x3a:0:
plot "<IN>" using 1:5 axes x1y2 ls l0 title 'Temperatur' with lines,\
"<IN>" using 1:9 axes x1y2 ls l10 title 'Temperatur (24h-Mittel)' with lines,\
"<IN>" using 1:7 axes x1y1 ls l2fill title 'Luftfeuchte' with lines</nowiki>
Den Plot für den Regen habe ich noch um Punkt-Plots für den israining-Status erweitert, so dass Punkte bei "yes" geplottet werden.

ks300_rain10.gplot

<nowiki>############################
# Display the Rain values of a KS300.
# Corresponding FileLog definition:
# define <filelogname> FileLog ./log/KS300-%Y.log KS300:T:.*
set terminal png transparent size <SIZE> crop
set output '<OUT>.png'
set xdata time
set timefmt "%Y-%m-%d_%H:%M:%S"
set xlabel " "
set ytics nomirror
#set y2tics
set ytics
set title '<L1>'
set grid xtics ytics
set y2range [0.5:1.5]
set y2tics ("" 0, "Regen" 1)
set pointsize 7
set ylabel "Regen (l/m²)"
set yrange [0:]
# Computing Rain/h and Rain/d values by accumulating the changes.
#FileLog 10:IR\x3a:0:delta-h
#FileLog 10:IR\x3a:0:delta-d
#FileLog 12:IR:0:$fld[11]=~"yes"?1:0
plot "<grep -v avg_ <IN> | perl -ane '\
@a = split(\"[_:]\", $F[0]);\
if(defined($lh) && $lh ne $a[1])\
{ printf(\"${ld}_$lh:30:00 %f\n\", $hv); $hv = 0; }\
if($lv) { $hv += ($F[9]-$lv); }\
$lh = $a[1]; $ld = $a[0]; $lv = $F[9];\
END { printf(\"${ld}_$lh:30:00 %f\n\", $hv) }'"\
using 1:2 axes x1y1 ls l1fill title 'Regen pro Stunde' with histeps,\
"<grep -v avg_ <IN> | perl -ane '\
@a = split(\"[_]\", $F[0]);\
if(defined($ld) && $ld ne $a[0]) {\
printf(\"${ld}_12:00:00 %f\n\", $dv); $dv = 0; }\
if($lv) { $dv += ($F[9]-$lv); }\
$ld = $a[0]; $lv = $F[9];\
END {printf(\"${ld}_12:00:00 %f\n\", $dv)}'"\
using 1:2 axes x1y1 ls l7 title 'Regen pro Tag' with histeps
"<grep -v avg_ <IN> | awk '{print $1, $12==\"yes\"? 1 : 0; }'"\
using 1:2 axes x1y2 ls l11fill title 'Regen aktuell' with points</nowiki>
Eventuell müssen in den gplots noch die Linienstile/Farben den eigenen Bedürfnissen angepasst werden. Ich verwende hier eigene Farben und Füllungen.

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

Modbus

2022-01-25T07:28:18Z

Ansgru: /* Set-Commands */

{{Infobox Modul
|ModPurpose=Library or physical device to extract information from devices with a Modbus interface or send information to such devices
|ModType=d
|ModCmdRef=Modbus
|ModForumArea=Sonstiges
|ModTechName=98_Modbus.pm
|ModOwner=StefanStrobel ({{Link2FU|3960|Forum}} / [[Benutzer:StefanStrobel|Wiki]])
}}

Modbus defines a physical modbus interface and library functions to be called from other logical modules / devices.
This low level module takes care of the communication with modbus devices and provides Get, Set and cyclic polling of Readings as well as formatting and input validation functions.

The logical device modules for individual machines only need to define the supported modbus function codes and objects of the machine with the modbus interface in data structures. These data structures are then used by this low level module to implement Set, Get and automatic updating of readings in a given interval.

The Modbus module supports Modbus RTU over serial / RS485 lines as well as Modbus TCP and Modbus RTU over TCP. It defines read / write functions for Modbus holding registers, input registers, coils and discrete inputs.

See [[ModbusAttr]] if you don't want to use a library to develop your own module and if you are looking for a generic Modbus Module instead that can be configured with attributes.

== Availability ==
The module has been checked in.

== Prerequisites ==
This module requires the Device::SerialPort or Win32::SerialPort module if you want to communicate with modbus devices over a serial line.

== Define of a modbus interface device for serial communication ==
<pre>
define <name> Modbus <device>
</pre>

A define of a physical device based on this module is only necessary if a shared physical device like a RS485 USB adapter is used.
In the case of Modbus TCP this module will be used as a library for other modules that define all the data objects and no define of the base module is needed.

Example:
<pre>
define ModBusLine Modbus /dev/ttyUSB1@9600
</pre>

In this example the module opens the given serial interface and other logical modules like [[ModbusAttr]] or [[ModbusSET]] can access several Modbus devices connected to this bus concurrently.

== Set-Commands ==
this low level device module doesn't provide set commands for itself but implements set
for logical device modules that make use of this module as a library. See [[ModbusSET]] for example.

== Get-Commands ==
this low level device module doesn't provide get commands for itself but implements get
for logical device modules that make use of this module as a library.

== Attributes ==
;do_not_notify
;readingFnAttributes

;queueDelay
:modify the delay used when sending requests to the device from the internal queue, defaults to 1 second

;queueMax
:max length of the send queue, defaults to 100<br>

;clientSwitchDelay
:defines a delay that is always enforced between the last read from the bus and the next send to the bus
:for all connected devices, but only if the next send goes to a different device than the last one

;dropQueueDoubles
:prevents new request to be queued if the same request is already in the send queue

;skipGarbage
:if set to 1 this attribute will enhance the way the module treats Modbus response frames (RTU over serial lines)
:that look as if they have a wrong Modbus id as their first byte.
:If skipGarbage is set to 1 then the module will skip all bytes until a byte with the expected modbus id is seen.
:Under normal circumstances this behavior should not do any harm and lead to more robustness.
:However since it changes the original behavior of this module it has to be turned on explicitely.
:For Modbus ASCII it skips bytes until the expected starting byte ":" is seen.

;profileInterval
:if set to something non zero it is the time period in seconds for which the module will create bus usage statistics.
:Please note that this number should be at least twice as big as the interval used for requesting values in logical devices
:that use this physical device
:The bus usage statistics create the following readings:
:* Profiler_Delay_sum
::seconds used as delays to implement the defined sendDelay and commDelay
:*Profiler_Fhem_sum
::seconds spend processing in the module
:*Profiler_Idle_sum
::idle time
:*Profiler_Read_sum
::seconds spent reading and validating the data read
:*Profiler_Send_sum
::seconds spent preparing and sending data
:*Profiler_Wait_sum
::seconds waiting for a response to a request
:*Statistics_Requests
::number of requests sent
:*Statistics_Timeouts
::timeouts encountered

== Writing modules for devices using this module as a library ==

Writing a module for a physical device with modbus interface is easy when you use the 98_Modbus.pm module as a library.
To use this module as a library for other fhem modules you only have to define a data structure that defines the mapping between modbus data objects (holding registers, input registers, coils or discrete inputs) and fhem readings.
Additionally the module needs to contain a few <code>package</code> and <code>use</code> statements and an initialize function at the beginning, that assigns a few special variables to point to functions of the Modbus base module.

The most easy way to start is to use [[ModbusAttr]] to define all objects and data types and then issue a set saveAsModule command which creates a new module automatically.

Example for a module that is called ModbusSET:
<pre>
package main;
use strict;
use warnings;

sub ModbusSET_Initialize($)
{
my ($modHash) = @_;
LoadModule "Modbus";
require "$attr{global}{modpath}/FHEM/DevIo.pm";

$modHash->{parseInfo} = \%SET10parseInfo; # defines registers, inputs, coils etc. for this Modbus Device
$modHash->{deviceInfo} = \%SET10deviceInfo; # defines properties of the device, defaults and supported function codes

ModbusLD_Initialize($modHash); # Generic function of the Modbus module does the rest

$modHash->{AttrList} = $modHash->{AttrList} . " " . # Standard Attributes like IODEv etc
$modHash->{ObjAttrList} . " " . # Attributes to add or overwrite parseInfo definitions
$modHash->{DevAttrList}; # Attributes to add or overwrite devInfo definitions

}
</pre>

The name of the initialize-Function has to match the name of the module. In the above example this is <code>ModbusSET_Initialize</code>. Most of the steps needed in an initialize function are provided by the library function <code>ModbusLD_Initialize</code>. This function tells fhem to use the library functions for <code>define</code>, <code>set</code>, <code>get</code> and other typical functions in a module. See [[DevelopmentModuleIntro]] for more background information on writing fhem modules if you are curious.

=== Introduction to the parseInfo structure ===

Typically the data structure to map between data objects of the modbus device and fhem readings is named <code>parseInfo</code> with a part of the name of the module itself as prefix. In the example of the module 98_ModbusSET.pm which uses Modbus.pm to implement a module for SET Silent 10 heat pumps, the structure is called <code>SET10parseInfo</code>.

This strucure contains keys with values that directly correspond to attributes which can be used with the module ModbusAttr so it is advisable to prototype a new module with ModbusAttr and then translate the attributes to entries in the parseInfo structure. The values in the parseInfo structure can later still be overwritten / extended with the attributes documented in ModbusAttr.

As an example a very simple definition of a parseInfo structure for a heat pump could look like this:

<pre>
my %XYparseInfo = (
"h256" => { reading => "Temp_Wasser_Ein", # name of the reading for this value
},
"h258" => { reading => "Temp_Wasser_Aus",
},
"h770" => { reading => "Temp_Soll",
min => 10, # input validation for set: min value
max => 32, # input validation for set: max value
set => 1, # this value can be set
}
);
</pre>

the corresponding attributes for ModbusAttr for prototyping or overwriting values would be obj-h256-reading, obj-h258-reading, obj-h770-reading, obj-h770-min and so on.

This parseInfo structure would be the main part of the module and map from holding register 256 to a fhem reading named Temp_Wasser_Ein, holding register 258 to Temp_Wasser_Aus and 770 to Temp_Soll.

All readings will be read from the device in an interval that the user can specify when he issues the define command for your module.
The meaning of <code>set => 1</code> is that the holding register 770 can also be written to with a set command. FHEM will check that the value written is not smaller than 10 and not bigger than 32 as specified above.

More complex example:
<pre>
my %SET10parseInfo = (
"h256" => { reading => "Temp_Wasser_Ein", # name of the reading for this value
name => "Pb1", # internal name of this register in the hardware doc
expr => '$val / 10', # conversion of raw value to visible value
len => 1,
},
"h770" => { reading => "Temp_Soll",
name => "ST03",
expr => '$val / 10', # convert raw value to readable temp
setexpr => '$val * 10', # expression to convert a set value to the internal value
min => 10, # input validation for set: min value
max => 32, # input validation for set: max value
hint => "8,10,20,25,28,29,30,30.5,31,31.5,32",
set => 1, # this value can be set
},
"h771" => { reading => "Hysterese", # Hex Adr 303
name => "ST04",
expr => '$val / 10',
setexpr => '$val * 10',
poll => "x10", # only poll every 10th iteration.
min => 0.5,
max => 3,
set => 1,
},
"h777" => { reading => "Hyst_Mode", # Hex Adr 0309
name => "ST10",
map => "0:mittig, 1:oberhalb, 2:unterhalb",
poll => "once", # only poll once (or after a set)
set => 1,
},
"i800" => { reading => "Voltage", # Input register
unpack => "f>", # this value is a float
len => 2, # the float occupies two input registers, 800 and 801
},
);
</pre>

There are many more options that can be specified for each data object / reading. If these options are not specified, the base module assumes defaults that typically make sense. However if you want to modify the defaults, you can either define explicit values in the parseInfo structure or you can define another data structure typically called deviceInfo.

=== Introduction to the deviceInfo structure ===

The deviceInfo structure is completely optional. If you don't define it in your module, the base module takes default values that work in ost cases. If you only want to override a few of the defaults, you can just define them and leave other options or sections out.
A simple device info structure that modifies some defaults could look like this:

<pre>
my %SET10deviceInfo = (
"timing" => {
timeout => 3, # timeout is 3 seconds /default would be 2
commDelay => 0.7, # wait 0.7 seconds before sending after receiving
sendDelay => 0.7, # wait at least 0.7 seconds for another send
},
"c" => {
read => 1, # function code 1 to read coils (this could be omitted because it is the default anyways
write => 5, # dito
},
"h" => {
read => 3,
write => 6,
defLen => 1, # default legth is 1 object
combine => 5,
defShowGet => 1,
defUnpack => "s>", # default data format is a signed 16 bit integer for holding registers
},
);
</pre>

The deviceInfo structure contains five optional parts. Timing defines timing values and the remaining parts define settings or defaults for coils (c), discrete inputs (d), input registers (i) and holding registers (h).

for each modbus object type you can change what function code should be used to read or write to the object. This is completely optional and if nothing is specified, the base module assumes function codes 1,2,3 and 4 for reading as well as 5 and 6 for writing which works for many modbus devices. If you prefer to use function code 16 for writing to holding registers, you can specify "write => 16" in the "h" part.

=== usage of a module created this way ===

a logical module written this way will have a define command that can work in two ways.
If your module would be called ModbusSET and it is using a serial line connection (Modbus RTU over RS485 oer over RS232):

<pre>
define <iodevice> Modbus /dev/device@baudrate
define <name> ModbusSET <Id> <Interval> </code>
</pre>

In this case, a physical serial interface device is defined first using the Modbus module. Then a device based on your module (ModbusSET in the example) is defined for each physical modbus device connected to the serial line. For a RS485 bus, several devices with different Ids can be connected to the same bus.

Example:
<pre>
define ModbusRS485 Modbus /dev/rs485@9600
define PWP ModbusAttr 5 60
</pre>

this defines the device and it will use the readings that you coded in the parseInfo data structure.

Alternatively your module would also support Modbus TCP or Modbus RTU over TCP with the following define syntax:

<pre>
define <name> ModbusAttr <Id> <Interval> <Address:Port> <RTU|TCP>
</pre>
In this case no serial interface device is necessary and your module connects to the modbus device directly via TCP using either Modbus TCP or Modbus RTU over TCP.

Example:
<pre>
define PWP ModbusAttr 1 30 192.168.1.115:502 TCP
</pre>

=== General information about data objects ===

Modbus devices can use many different ways to encode values in their data objects. A temperature might be stored multiplied with 10 as a 16 bit integer value in one holding register so you have to read the integer and divide it by 10 to get the real temperature value back. It might also be stored as a 32 bit float data type that spans two adjacent input registers.
The modbus base module implements a very generic way to handle different encodings without real programming: It lets you define the Perl unpack code to convert a raw data string to a Perl value, a Perl expression to do further computation and a length in data objects.

This way a temperature stored in a 16 bit signed integer as the value multiplied by 10 can be described with the unpack code "s>" and the expression "$val / 10". A float value spanning 2 registers would be described with an unpack code "f>" and a len of 2. No expression is needed in this case. See Perldoc on the pack function for a detailed explation of pack and unpack codes.

The idea here is that you should be able to define any mapping, encoding, transformation or formatting of data objects without programming by simpy describing them.

=== most important options in parseInfo ===

Most options here are optional and can be used if there is a need but they can also be omitted. If most readings require the same options and the option is different from the default, it is also possible to define a different default per modbus data object type in another data structure (see deviceInfo).
For a list of all options please refer to the attributes documentation of the module ModbusAttr. The attributes there can be translated to parseInfo or deviceInfo keys as shown above.

;reading
:name of the reading to be used in FHEM e.g. Temp_Wasser_ein

;expr
:perl expression to convert a string after it has been read. The original value is in $val e.g. $val / 10

;map
:a map string to convert an value from the device to a more readable output string or to convert a user input to the machine representation e.g. "0:mittig, 1:oberhalb, 2:unterhalb"

;format
:a format string for sprintf to format a value read, e.g. %.1f

;len
:number of Registers this value spans, can be 2 for a 32 bit float which is stored in 2 registers

;unpack
:defines the translation between data in the module and in the communication frame see the documentation of the perl pack function for details. example: "n" for an unsigned 16 bit value or "f>" for a float that is stored in two registers or "s>" for signed 16 bit integer in big endian format

;showget
:can be set to 1 to allow a FHEM get command to read this value from the device. All defined objects can be used in a get command that is issued on the command line. This parameter only controls if fhemweb will offer a get command for the object.

;poll
:defines if this value is included in the read that the module does every defined interval this can be changed by a user with an attribute

;polldelay
:if a value should not be read in each iteration (after interval has passed), this value can be set to an explicit time in seconds. The update function will then verify if this delay has elapsed since the last read of this object. If not, the read is skipped.

;set
:can be set to 1 to allow writing this value with a FHEM set-command

;min
:min value for input validation in a set command. If the user issues e.g. set Device Temp_Soll 10, FHEM will check if the given value 10 is bigger or equal the defined min and smaller or equal the defined max.

;max
:max value for input validation in a set command

;hint
:string for fhemweb to create a selection or slider

;setexpr
:per expression to convert an input string to the machine format before writing this is typically the reverse of the above expr, e.g. $val * 10

;name
:optional internal name of the value in the modbus documentation of the physical device, e.g. pb1

=== most important options in deviceInfo ===

Keys in the timing section:

;timeout
:how long to wait for a response from the device, can be overwritten by attribute timeout in logical device. Defaults to two seconds if this is not specified

;commDelay
:minimal delay in secounds between two communications e.g. a read a the next write, can be overwritten with attribute commDelay if added to AttrList in _Initialize below defaults to 0.1 seconds if not specified

;sendDelay
:minimal delay in seconds between two sends, can be overwritten with the attribute sendDelay if added to AttrList in _Initialize function below. Defaults to 0.1 seconds if not specified

Keys per object type (c = coil, d = discrete input, i = input register, h = holding register)

;read
:function code to use for reading this object type (e.g. 3 for holding registers) defaults to function codes 1-4 depending on the object types if nothing else is specified (3 to read holding register, 1 to read coils and so on)

;write
:function code to use for writing this object type (e.g. 6 or 16 for holding registers) defaults to function codes 5 and 6 depending on the object types if nothing else is specified (6 to read holding register, 5 to write coils and so on)

;defLen
:default len for objects using this type (e.g. can be set to 2 if the device mainly provides float values that span 2 registers (2 times 16 Bit) can be overwritten in parseInfo per reading by specifying the key "len" defaults to 1 if not specified

;defFormat
:format string to do sprintf with the value can be overwritten in parseInfo per reading by specifying the key "format" if no format is specified here and none in parseInfo, the the reading is set without further formatting (which is typically fine)

;defUnpack
:default pack / unpack code to convert raw values, e.g. "n" for a 16 bit integer or "f>" for a big endian float can be overwritten in parseInfo per reading by specifying the key "unpack" if not specified here and not in parseInfo, then the raw value is interpreted as "n" which is 16 bit unsigned integer in big endian format

;defPoll
:defines that objects of this type should be polled by default unless specified otherwise in parseInfo or by attributes can be overwritten in parseInfo per reading by specifying the key defaultpoll if not specified here or in parseInfo, the object is not polled

;defShowGet
:defines that FHEMweb shows a Get option (by returning it as reslut to get ?) for objects of this type can be overwritten in parseInfo per reading by specifying the key showget defaults to 0.

;combine
:max number of registers that the device is willing to deliver in one read request. The modbus application layer protocol specification allows for more than 100 but most devices limit this to 5, 10 or some other number. This option defaults to 1 if not specified.

For an example of a full module that is based on the mechanisms described here see 98_ModbusSET.pm.

=== Attributes of your module ===

a module based on the base module / library 98_Modbus.pm can also allow the end user to modify properties of each reading if you want to allow it. All you have to do is to offer an attribute by adding its name to the variable $modHash->{AttrList} in your initialize function.

If for example you want to allow the user to modify the maximum value for the reading Temp_Soll, you can add "Temp_Soll-max " to this variable and the user can then set this attribute. The attribute takes precedence over the max potentially already defined in your parseInfo structure.

There are two ways that the base module accepts such readings. One is the reading name followed by "-" and the option to override, the alternative syntax is "obj-" followed by the first letter of an object type (c/d/h/i) and a decimal address just like the main key of an object in the parseInfo structure.

Instead of allowing the attribute Temp_Soll-max for the max value of reading Temp_Soll which corresponds to holding register 770, you can alternatively add the attribute name "obj-h770-min " to $modHash->{AttrList}.

If the user is allowd to specify such attributes solely depends on the contents of the $modHash->{AttrList} variable. All the processing is already built into the base module.

If you want to allow the user the override the formatting of readings then you can add "obj-[cdih][1-9][0-9]*-format " as a regular expression that allows format specifications for all possible data objects.

The module 98_ModbusAttr for example is also based on 98_Modbus.pm and allows all possible attributes so the user can completely define his device with attributes and without a parseInfo or deviceInfo structure.

In the same way you can allow the user to override the device specific options and defaults with attributes that start with "dev-", followed by the section of the deviceInfo and the name of the option. If you want to allow the user to modify the function code to be used for writing holding registers, you can add the attribute "obj-h-write " and the user can then set this attribute to 6 or 16 as he prefers.
It is up to the module author to decide if this makes sense.

An assignment that allows most options to the user could be:

<pre>
$modHash->{AttrList} = $modHash->{AttrList} . " " .
"obj-[cdih][1-9][0-9]*-reading " .
"obj-[cdih][1-9][0-9]*-name " .
"obj-[cdih][1-9][0-9]*-set " .
"obj-[cdih][1-9][0-9]*-min " .
"obj-[cdih][1-9][0-9]*-max " .
"obj-[cdih][1-9][0-9]*-hint " .
"obj-[cdih][1-9][0-9]*-expr " .
"obj-[cdih][1-9][0-9]*-map " .
"obj-[cdih][1-9][0-9]*-setexpr " .
"obj-[cdih][1-9][0-9]*-format " .
"obj-[cdih][1-9][0-9]*-len " .
"obj-[cdih][1-9][0-9]*-unpack " .
"obj-[cdih][1-9][0-9]*-showget " .

"obj-[cdih][1-9][0-9]*-poll " .
"obj-[cdih][1-9][0-9]*-polldelay " .
"poll-.* " .
"polldelay-.* " .

"dev-([cdih]-)*read " .
"dev-([cdih]-)*write " .
"dev-([cdih]-)*combine " .
"dev-([cdih]-)*defLen " .
"dev-([cdih]-)*defFormat " .
"dev-([cdih]-)*defUnpack " .
"dev-([cdih]-)*defPoll " .
"dev-([cdih]-)*defShowGet " .
"dev-timing-timeout " .
"dev-timing-sendDelay " .
"dev-timing-commDelay ";
}
</pre>

== Examples for logical device modules that use this base module ==
;[http://forum.fhem.de/index.php/topic,25315.60.html SDM220M]
;[http://forum.fhem.de/index.php/topic,25315.60.html SDM630M]
:modules for energy meters from B+G E-Tech & EASTON written by Roger
;[http://forum.fhem.de/index.php/topic,25315.45.html UMG103]
;[http://forum.fhem.de/index.php/topic,25315.45.html UMG604]
:modules for the UMG103 and UMG604 meters from Janitza
;[[ModbusSET]]
:module for the set silent heat pumps from Schmidt Energie Technik
;[[ModbusAttr]]
:generic modbus device module where the data objects, addresses, display formats, function codes and other things can be configured using FHEM attributes similar to HTTPMOD [[Kategorie:Interfaces]]

ArduCounter

2021-09-29T19:44:24Z

Ansgru: /* Text zu Intervallen angepasst (siehe https://forum.fhem.de/index.php/topic,19285.msg1175877.html#msg1175877)*/

{{Infobox Modul
|ModPurpose=Count pulses, measure time between pulses and convert this to readings for e.g. power consumption of Energy meters or water meters
|ModType=d
|ModCmdRef=ArduCounter
|ModForumArea=Sonstiges
|ModFTopic=19285
|ModTechName=98_ArduCounter.pm
|ModOwner=StefanStrobel ({{Link2FU|3960|Forum}} / [[Benutzer:StefanStrobel|Wiki]])
}}

This module implements an Interface to an Arduino, ESP8266 or ESP32 based counter for pulses on any input pin of an Arduino Uno, Nano, Jeenode,
NodeMCU, Wemos D1, TTGO T-Display or similar device.
[[Datei:Wasserzaehler.jpg|mini|Wasserzähler mit Laserabtastung auf Basis ArduCounter mit ESP32]]
[[Datei:TTGO.png|mini|ArduCounter auf einem ESP32]]
[[Datei:ArduCounter_ESP_i.jpg|mini|ArduCounter mit Reflexlichtschranke auf einem ESP8266]]
[[Datei:ArduCounter_ESP2.jpg|mini|ArduCounter mit Reflexlichtschranke auf einem ESP8266]]
[[Datei:ArduCounter_Wifi.PNG|mini|ArduCounter Wifi-Konfiguration per WifiManager]]

The device connects to Fhem either through USB / serial or via Wifi / TCP if an ESP board is used.
ArduCounter does not only count pulses but also measure pulse lenghts and the time between pulses so it can filter noise / bounces
and gives better power/flow (Watts or liters/second) readings than systems that just count in fixed time intervals.
The number of pulses per kWh or liter is defineable and counters continue even when Fhem or the device restarts
so you don't need additional user readings to make such calculations
The typical use case is an S0-Interface on an energy meter or water meter, but also reflection light barriers
to monitor old ferraris counters or analog water meters are supported
Counters are configured with attributes that define which GPIO pins should count pulses and in which intervals the board should report the current counts.
The sketch that works with this module uses pin change interrupts so it can efficiently count pulses on all available input pins.
The module has been tested with 14 inputs of an Arduino Uno counting in parallel and pulses as short as 3 milliseconds.
The module creates readings for pulse counts, consumption and optionally also a pin history with pulse lengths and gaps of the last pulses.
If an ESP8266 or ESP32 is used, the device can be flashed and configured over Wifi (it opens its own temporary Hotspot / SSID for configuration
so you can set which existing SSID to connect to and which password to use). For TTGO T-Display boards (ESP32 with TFT display)
the local display on the device itself can also display Wifi status and current consumption.

== Prerequisites ==

This module requires an Arduino Uno, Nano, Jeenode, NodeMCU, Wemos D1, TTGO T-Display or similar device based on an Atmel 328p, ESP8266 or ESP32
running the ArduCounter sketch provided with this module
In order to flash an arduino board with the corresponding ArduCounter firmware from within Fhem, avrdude needs to be installed.
To flash ESP32 or ESP8266 boards form within Fhem, Python and the scripts esptool.py / espota.py need to be installed.
For old ferraris counters a reflection light barrier which in the simpest case can consist of a photo transistor (connected to an anlalog input of the Arduino / ESP)
and an led or a laser module (connected to a digital output), both with a resistor in line are needed.
To drive a laser module with 5V, another transistor is typically needed to switch 5V from a 3.3V GPIO output.

== Define ==

<code>define <name> ArduCounter <device></code>
or
<code>define <name> ArduCounter <ip:port></code>

<device> specifies the serial port to communicate with the Arduino.
<ip:port> specifies the ip address and tcp port to communicate with an esp8266 / ESP32 where port is typically 80.

The name of the serial device depends on your distribution and serial adapter.
You can also specify a baudrate for serial connections if the device name contains the @ character, e.g.: /dev/ttyUSB0@115200
The default baudrate of the ArduCounter firmware is 115200 since sketch version 4 and used to be 38400 since sketch version 1.4
The latest version of this module will however try different baudrates automatically if communication with the counting device seems not possible.

Example:

<code>define AC ArduCounter /dev/ttyUSB2@115200</code>
<code>define AC ArduCounter 192.168.1.134:80</code>

== Configuration of ArduCounter digital counters ==

Specify the pins where impulses should be counted e.g. as <code>attr AC pinX falling pullup min 25</code>
The X in pinX can be an Arduino / ESP GPIO pin number with or without the letter D e.g. pin4, pinD5, pin6, pinD7 ...
After the pin you can use the keywords falling or rising to define if a logical one / 5V (rising) or a logical zero / 0V (falling) should be treated as pulse.
The optional keyword pullup activates the pullup resistor for the given Pin.
The last argument is also optional but recommended and specifies a minimal pulse length in milliseconds.
An energy meter with S0 interface is typically connected to GND and an input pin like D4.
The S0 pulse then pulls the input down to 0V.
Since the minimal pulse lenght of an S0 interface is specified to be 30ms, the typical configuration for an s0 interface is
<code>attr AC pinX falling pullup min 25</code>
Specifying a minimal pulse length is recommended since it filters bouncing of reed contacts or other noise.
The keyword <code>min</code> before <code>25</code> is optional.

Example:
<pre>
define AC ArduCounter /dev/ttyUSB2
attr AC pulsesPerUnit 1000
attr AC interval 60 300
attr AC pinD4 falling pullup min 5
attr AC pinD5 falling pullup min 25
attr AC pinD6 rising
</pre>

This defines a counter that is connected to Fhem via serial line ttyUSB2 with three counters connected to the GPIO pins D4, D5 and D5.
D4 and D5 have their pullup resistors activated and the impulses draw the pins to zero.
For D4 and D5 the board measures the time in milliseconds between the falling edge and the rising edge.
If this time is longer than the specified 5 (or 25 for pin D5) milliseconds then the impulse is counted.
If the time is shorter then this impulse is regarded as noise and added to a separate reject counter.
For pin D6 the board uses a default minimal length of 2ms and counts every time when the signal changes from 1 (rising pulse) back to 0.

== Configuration of ArduCounter analog counters ==

This module and the corresponding ArduCounter sketch can be used to read water meters or old analog ferraris energy counters.
Therefore a reflection light barrier needs to be connected to the board. This might simply consist of an infra red photo transistor
(connected to an analog input) and an infra red led (connected to a digital output), both with a resistor in line.
The idea comes from Martin Kompf (https://www.kompf.de/tech/emeir.html) and has been adopted for ArduCounter to support
old ferraris energy counters or water meters.
The configuration is then similar to the one for digital counters:
<pre>
define WaterMeter ArduCounter 192.168.1.110:80
attr ACF pinA0 rising pullup min 4 analog out 27 threshold 120,220
attr ACF interval 5,60,2,15,10,3
attr ACF pulsesPerUnit 35
attr ACF stateFormat {sprintf("%.3f l/min", ReadingsVal($name,"powerA0",0))}
</pre>
In this case an analog GPIO pin is used as input and the normal configuration parameters are followed by the keyword
<code>analog out</code> or simply <code>out</code>, the gpio number of a GPIO output that connects a light source and the thresholds
that decide when an analog input value is regarded as "low" or "high".

In the example an ESP32 is used via Wifi connection. GPIO pin A0 is used as analog input and is connected to a photo transistor that senses the intensity of light.
GPIO 27 is used as LED output and switched on/off in a high frequency. On GPIO A0 the reflected light is measured
and the difference in a measurement between when the LED is off and when the LED is on is compared to the thresholds defined in the pinA0-attribute.
When the measured light difference is above <code>220</code>, then a pulse starts (since <code>rising</code> is specified).
When the measured difference is below <code>120</code> then the pulse ends.

The attribute <code>interval</code> has the following meaning in the above example:
The device reports the current counts and the time difference beween the first and the last pulse if at least 2 pulses have been counted
and if they are more than 15 milliseconds apart form each other. If not, then the device continues counting.
If after 60 seconds these conditions are stil not met, then the device will report the current count anyways and use the current time as the end of the interval.
The last two numbers of the <code>interval</code> attribute define that the device will read the analog input 3 times and then work with the average.
Between each analog measurement series there will be a delay of 10 milliseconds.

The attribute <code>pulsesPerUnit 35</code> defines that 35 pulses correspond to one unit (e.g. liter) and the reading <code>calcCounterA0</code>
is increased by the reported raw counts divided by 35.
To find out the right analog thresholds you can set the attribute <code>enableHistory</code> to 1 which will ask the firmware of your counting board
to report the average difference measurements before they are compared to a threshold.
The ArduCounter module will count how often each value is reported and you can then query these analog level counts with <code>get levels</code>.
After a few measuremets the result of <code>get levels</code> might look like this:

<pre>
observed levels from analog input:
94: 21
95: 79
96: 6
97: 2
98: 3
99: 2
100: 2
101: 1
102: 3
105: 2
106: 1
108: 2
109: 1
110: 1
112: 1
113: 3
115: 4
116: 9
117: 14
118: 71
119: 103
120: 118
121: 155
122: 159
123: 143
124: 147
125: 158
126: 198
127: 249
128: 220
129: 230
130: 201
131: 140
132: 147
133: 153
134: 141
135: 119
136: 105
137: 109
138: 114
139: 83
140: 33
141: 14
142: 1
</pre>

This shows the measured values together with the frequency how often the individual value has been measured.
It is obvious that most measurements result in values between 120 and 135, very few values are betweem 96 and 115
and another peak is around the value 95.
It means that in the example of a ferraris energy counter, when the red mark of the ferraris disc is under the sensor,
the value is around 95 and while when the blank disc is under the sensor, the value is typically between 120 and 135.
So a good upper threshold would be 120 and a good lower threshold would be for example 96.

== Set-Commands ==

;raw
:send the value to the board so you can directly talk to the sketch using its commands.
:This is not needed for normal operation but might be useful sometimes for debugging

;flash [<file>]
:flashes the ArduCounter firmware from the subdirectory FHEM/firmware onto the device.
:Normally you can just specify <code>set myDevice flash</code>. The parameter <file> is optional and allows specifying an alternative firmware file.
:The attribute flashCommand can be used to override which command is executed.
:If the attribute flashCommand is not specified then the module selects an appropriate command depending on the board type
:(set with the attribute <code>board</code>) and depending on the connection (serial or Wifi).
:For an arduino NANO for example the module would execute avrdude (which has to be installed of course)
:and flash the connected arduino with the updated hex file
:(by default it looks for ArduCounter.hex in the FHEM/firmware subdirectory).
:For an Arduino UNO for example the default is <code>avrdude -p atmega328P -c arduino -P [PORT] -D -U flash:w:[HEXFILE] 2>[LOGFILE]</code>
:For an Arduino Nano based counter <code>-b 57600</code> is added.
:For an ESP32 connected via Wifi, the module would call espota.py which will upload the firmware over the air.
:If the attribute flashCommand is not specified for an ESP32 based board connected via serial line, then the module uses the command

:<syntaxhighlight lang="bash" xstyle="width:80%;">
esptool.py --chip esp32 --port [PORT] --baud 460800 --before default_reset --after hard_reset write_flash -z --flash_mode dio --flash_freq 40m --flash_size detect
0x1000 FHEM/firmware/ArduCounter_ESP32_bootloader_dio_40m.bin 0x8000 FHEM/firmware/ArduCounter_ESP32_partitions.bin 0xe000 FHEM/firmware/ArduCounter_ESP32_boot_app0.bin
0x10000 FHEM/firmware/ArduCounter_ESP32_firmware.bin >[LOGFILE] 2>&1
</syntaxhighlight>

:for example which flashes the whole ESP32 with all the partitions. For over the air flashing it would use
:<syntaxhighlight lang="bash" xstyle="width:80%;">
espota.py -i[IP] -p [NETPORT] -f [BINFILE] 2>[LOGFILE]
</syntaxhighlight>
:Of course esptool.py or espota.py as well as python would need to be installed on the system.

;resetWifi
:reset Wifi settings of the counting device so the Wifi Manager will come up after the next reset to select a wireless network and enter the Wifi passphrase.

;reset
:sends a command to the device which causes a hardware reset or reinitialize and reset of the internal counters of the board.
:The module then reopens the counting device and resends the attribute configuration / definition of the pins.

;saveConfig
:stores the current interval, analog threshold and pin configuration in the EEPROM of the counter device so it will automatically be retrieved after a reset.

;enable
:sets the attribute disable to 0

;disable
sets the attribute disable to 1

;reconnect
:closes the tcp connection to an ESP based counter board that is conected via TCP/IP and reopen the connection

;clearLevels
:clears the statistics for analog levels. This is only relevant if you use the board to read via a reflective light barrier
:and you want to set the thresholds according to the statistics.

;clearCounters <pin>
:resets all the counter readings for the specified pin to 0

;counter <pin>, <value>
:set the calcCounter reading for the specified pin to the given value

;clearHistory
:deletes all the cached pin history entries

== Get-Commands ==

;info
:send a command to the Arduino board to get current counts.
:This is not needed for normal operation but might be useful sometimes for debugging

;levels
:show the count for the measured levels if an analog pin is used to measure e.g. the red mark of a ferraris counter disc. This is useful for setting the thresholds for analog :measurements.

;history <pin>
:shows details regarding all the level changes that the counter device (Arduino or ESP) has detected and how they were used (counted or rejected)
:If get history is issued with a pin name (e.g. get history D5) then only the history entries concerning D5 will be shown.
:This information is sent from the device to Fhem if the attribute <code>enableHistory</code> is set to 1.
:The maximum number of lines that the Arducounter module stores in a ring buffer is defined by the attribute maxHist and defaults to 1000.

== Attributes ==

;do_not_notify
;readingFnAttributes

;pin[AD]?[0-9]+<rising|falling> [<pullup>] [min] <min length> [[analog] out <out pin> [threshold] <min, max>]
:Define a GPIO pin of the Arduino or ESP board as input. This attribute expects for digital inputs either
:<code>rising</code> or <code>falling</code>, followed by an optional <code>pullup</code> and the optional keyword <code>min</code>
:and an optional number as minimal length of pulses and gaps between pulses.
:The counter device will track rising and falling edges of each impulse and measure the length of a pulse in milliseconds.
:The minimal length specified here is the minimal duration of a pulse and a pause before a pulse. If one is too small,
:the pulse is not counted but added to a separate reject counter.
:Example:
:<syntaxhighlight lang="perl" xstyle="width:80%;">
attr MyCounter pinD4 falling pullup 25
</syntaxhighlight>
:For analog inputs with connected reflective light barries, you have to add <code>analog out</code>
:and the GPIO pin number of the pin where the light source (LED or laser) is connected, the keyword <code>threshold</code>
:followed by the lower and upper threshold separated by a komma.
:Example:
:<syntaxhighlight lang="perl" xstyle="width:80%;">
attr MyCounter pinA0 rising pullup min 3 analog out 27 threshold 120,220
</syntaxhighlight>

;interval <normal> <max> [<min> <min count> [<analog interval> <analog samples>]]
:Defines the parameters that affect the way counting and reporting works. This Attribute expects at least two and a maximum of six numbers as value. The first is the normal interval, the second the maximal interval, the third is a minimal interval and the fourth is a minimal pulse count. The last two numbers are only needed for counting with reflective light barriers. They specify the delay between the measurements and the number of samples for each measurement. The normal use case (where the normal interval is smaller than the maximum interval) would be where the Arduino board just counts and remembers the time between the first impulse and the last impulse for each pin.After the normal interval has elapsed the Arduino board reports the count and time for those pins where impulses were encountered.This means that even though the normal interval might be 10 seconds, the reported time difference can be different because impulses are observed by start and end point. The Power (e.g. for energy meters) is then calculated based of the counted impulses and the time difference between the first and the last impulse.For the next interval, the starting time will be the time of the last impulse in the previous reporting period and the time difference will be taken up to the last impulse before the reporting interval has elapsed. The second, third and fourth numbers (maximum, minimal interval and minimal count) exist for edge cases where the pulse frequency is very low and the reporting time is comparatively short: For example if the normal interval (first number) is 60 seconds but there is only one impulse every 90 seconds you will have spikes in your power readings (where there should be none).This can be avoided by choosing the max/min/min count numbers wisely: If impulses occur less frequently than the normal interval readings will be prolonged until max interval is reached. If however the last max interval has had no pulses, a new max interval has just started and right after it started an impuls occurs this would again cause spikes the way Arducounter works. To prevent those spikes from happening use <min> / <min count>. They make sure, that more than <min count> impulses and less than <min> time between impulses must have occured for the impulses to be considered as part of a normal interval (=a steady flow of impulses). If however it's just a single impulse which comes at an "akward" moment as mentioned before it won't be considered during a normal interval unless other impulses follow. Instead the normal interval will be prolonged until max interval is reached.
:A reasonable example would be:<syntaxhighlight lang="perl" xstyle="width:80%;">
attr myCounter interval 60 600 5 2
</syntaxhighlight>If this is seems too complicated and you prefer a simple and constant reporting interval, then you can set the normal interval and the mximum interval to the same number.This changes the operation mode of the counter to just count during this normal and maximum interval and report the count. In this case the reported time difference is always the reporting interval and not the measured time between the real impulses.
:For analog sampling the last two numbers define the delay in milliseconds between analog measurements and the number of samples that will be taken as one mesurement.

;pulsesPerUnit <number>
:specify the number of pulses that the meter is giving out per unit that sould be displayed (e.g. per kWh energy consumed).
:For many S0 counters this is 1000, for old ferraris counters this is 75 (rounds per kWh).
:This attribute used to be called pulsesPerKWh and this name still works but the new name should be used preferably since the old one could be removed in future versions.
:Example:
:<syntaxhighlight lang="perl" xstyle="width:80%;">
attr myCounter pulsesPerUnit 75
</syntaxhighlight>

;readingPulsesPerUnit[AD]?[0-9]+ <number>
:is the same as pulsesPerUnit but specified per GPIO pin individually in case you have multiple counters with different settings at the same time
:This attribute used to be called readingPulsesPerKWh[AD]?[0-9]+ and this name still works but the new name should be used preferably
:since the old one could be removed in future versions.
:
:Example:
:<syntaxhighlight lang="perl" xstyle="width:80%;">
attr myCounter readingPulsesPerUnitA7 75
attr myCounter readingPulsesPerUnitD4 1000
</syntaxhighlight>

;readingFlowUnitTime[AD]?[0-9]+ <time>
:specified the time period in seconds which is used as the basis for calculating the current flow or power for the given pin.
:If the counter e.g. counts liters and you want to see the flow in liters per minute, then you have to set this attribute to 60.
:If you count kWh and you want to see the current power in kW, then specify 3600 (one hour).
:Since this attribute is just used for multiplying the consumption per second, you can also use it to get watts
:instead of kW by using 3600000 instead of 3600.

;flowUnitTime <time>
:like readingFlowUnitTimeXX but applies to all pins that have no explicit readingFlowUnitTimeXX attribute.

;readingNameCount[AD]?[0-9]+ <new name>
:Change the name of the counter reading pinX to something more meaningful.
:Example:
:<syntaxhighlight lang="perl" xstyle="width:80%;">
attr myCounter readingNameCountD4 CounterHaus_internal
</syntaxhighlight>

;readingNameLongCount[AD]?[0-9]+ <new name>
:Change the name of the long counter reading longX to something more meaningful.
:Example:
:<syntaxhighlight lang="perl" xstyle="width:80%;">
attr myCounter readingNameLongCountD4 CounterHaus_long
</syntaxhighlight>

;readingNameInterpolatedCount[AD]?[0-9]+ <new name>
:Change the name of the interpolated long counter reading InterpolatedlongX to something more meaningful.
:Example:
:<syntaxhighlight lang="perl" xstyle="width:80%;">
attr myCounter readingNameInterpolatedCountD4 CounterHaus_interpolated
</syntaxhighlight>

;readingNameCalcCount[AD]?[0-9]+ <new name>
:Change the name of the real unit counter reading CalcCounterX to something more meaningful.
:Example:
:<syntaxhighlight lang="perl" xstyle="width:80%;">
attr myCounter readingNameCalcCountD4 CounterHaus_kWh
</syntaxhighlight>

;readingNamePower[AD]?[0-9]+ <new name>
:Change the name of the power reading powerX to something more meaningful.
:Example:
:<syntaxhighlight lang="perl" xstyle="width:80%;">
attr myCounter readingNamePowerD4 PowerHaus_kW
</syntaxhighlight>

;readingStartTime[AD]?[0-9]+ [0|1]
:Allow the reading time stamp to be set to the beginning of measuring intervals.
:This is a hack where the timestamp of readings is artificially set to a past time and may have side effects
:so avoid it unless you fully understand how Fhem works with readings and their time.

;verboseReadings[AD]?[0-9]+ [0|1]
:create the additional readings lastMsg and pinHistory for each pin
:if verboseReafings is set to 1 for the specified pin.
:If set to -1 then the internal counter, the long counter and interpolated long counter readings will be hidden.
:Example:
:<syntaxhighlight lang="perl" xstyle="width:80%;">
attr myCounter verboseReadingsD4 1
</syntaxhighlight>

;enableHistory [0|1]
:tells the counting device to record the individual time of each change at each GPIO pin and send it to Fhem.
:This information is cached on the Fhem side and can be viewed with the command <code>get history</code>
:The optput of <code>get history</code> will look like this:
:<syntaxhighlight lang="perl" xstyle="width:80%;">
seq 12627 2020-03-22 20:39:54 Pin D5 0.080 seconds at 0 -> pulse counted
seq 12628 2020-03-22 20:39:55 Pin D5 1.697 seconds at 1 -> gap
seq 12629 2020-03-22 20:39:56 Pin D5 0.080 seconds at 0 -> pulse counted
seq 12630 2020-03-22 20:39:56 Pin D5 1.694 seconds at 1 -> gap
seq 12631 2020-03-22 20:39:58 Pin D5 0.081 seconds at 0 -> pulse counted
seq 12632 2020-03-22 20:39:58 Pin D5 1.693 seconds at 1 -> gap
seq 12633 2020-03-22 20:40:00 Pin D5 0.081 seconds at 0 -> pulse counted
seq 12634 2020-03-22 20:40:00 Pin D5 1.696 seconds at 1 -> gap
seq 12635 2020-03-22 20:40:02 Pin D5 0.081 seconds at 0 -> pulse counted
seq 12636 2020-03-22 20:40:02 Pin D5 1.699 seconds at 1 -> gap
seq 12637 2020-03-22 20:40:03 Pin D5 0.079 seconds at 0 -> pulse counted
seq 12638 2020-03-22 20:40:03 Pin D5 1.700 seconds at 1 -> gap
seq 12639 2020-03-22 20:40:05 Pin D5 0.080 seconds at 0 -> pulse counted
seq 12642 2020-03-22 20:40:05 Pin D5 1.699 seconds at 1 -> gap
seq 12643 2020-03-22 20:40:07 Pin D5 0.080 seconds at 0 -> pulse counted
seq 12644 2020-03-22 20:40:07 Pin D5 1.698 seconds at 1 -> gap
</syntaxhighlight>

;enableSerialEcho [0|1]
:tells the counting device to show diagnostic data over the serial line when connected via TCP

;enablePinDebug [0|1]
:tells the counting device to show every level change of the defined input pins over the serial line or via TCP

;enableAnalogDebug [0|1]
:tells the counting device to show every analog measurement of the defined analog input pins over the serial line or via TCP

;enableDevTime [0|1]
:tells the counting device to show its internal millis timer so a drift between the devices time and fhem time can be calculated and logged

;maxHist <max entries>
:specifies how many pin history lines hould be buffered for "get history".
:This attribute defaults to 1000.

;analogThresholds
:this Attribute is outdated. Please specify the analog thresholds for reflective light barrier input with the attribute "pin..."

;flashCommand <new shell command>
:overrides the default command to flash the firmware via Wifi (OTA) or serial line. It is recommended to not define this attribute.
:Example:
:<syntaxhighlight lang="perl" xstyle="width:80%;">
attr myCounter flashCommand avrdude -p atmega328P -c arduino -b 57600 -P [PORT] -D -U flash:w:[HEXFILE] 2>[LOGFILE]
</syntaxhighlight>
:<code> [PORT]</code> is automatically replaced with the serial port for this device as it is specified in the <code>define</code> command.
:<code> [HEXFILE]</code> or <code>[BINFILE]</code> are synonyms and are both automatically replaced with the firmware file appropriate for the device.
:For ESP32 boards <code>[HEXFILE]</code> would be replaced by ArduCounter-8266.bin for example.
:<code> [LOGFILE]</code> is automatically replaced ArduCounterFlash.log in the fhem log subdirectory.
:<code> [NETPORT]</code> is automatically replaced by the tcp port number used for OTA flashing.
:For ESP32 this usually is 3232 and for 8266 Bords it is 8266.

;keepAliveDelay <delay>
:defines an interval in which the module sends keepalive messages to a counter device that is conected via tcp.
:This attribute is ignored if the device is connected via serial port.
:If the device doesn't reply within a defined timeout then the module closes and tries to reopen the connection.
:The module tells the device when to expect the next keepalive message and the device will also close the tcp connection if it doesn't see a keepalive message within the delay :multiplied by 3
:The delay defaults to 10 seconds.
:Example:
:<syntaxhighlight lang="perl" xstyle="width:80%;">
attr myCounter keepAliveDelay 30
</syntaxhighlight>

;keepAliveTimeout <seconds>
:defines the timeout when wainting for a keealive reply (see keepAliveDelay)
:The timeout defaults to 2 seconds.
:Example:
:<syntaxhighlight lang="perl" xstyle="width:80%;">
attr myCounter keepAliveTimeout 3
</syntaxhighlight>

;keepAliveRetries <max number of retries>
:defines how often sending a keepalive is retried before the connection is closed and reopened.
:It defaults to 2.
:Example:
:<syntaxhighlight lang="perl" xstyle="width:80%;">
attr myCounter keepAliveRetries 3
</syntaxhighlight>

;nextOpenDelay <delay>
:defines the time in seconds that the module waits before retrying to open a disconnected tcp connection.
:This defaults to 60 seconds.
:Example:
:<syntaxhighlight lang="perl" xstyle="width:80%;">
attr myCounter nextOpenDelay 20
</syntaxhighlight>

;openTimeout <timeout>
:defines the timeout in seconds after which tcp open gives up trying to establish a connection to the counter device.
:This timeout defaults to 3 seconds.
:Example:
:<syntaxhighlight lang="perl" xstyle="width:80%;">
attr myCounter openTimeout 5
</syntaxhighlight>

;silentReconnect [0|1]
:if set to 1, then it will set the loglevel for "disconnected" and "reappeared" messages to 4 instead of 3
:Example:
:<syntaxhighlight lang="perl" xstyle="width:80%;">
attr myCounter silentReconnect 1
</syntaxhighlight>

;deviceDisplay <pin> <unit> <flowUnit>
:controls the unit strings that a local display on the counting device will show.
:Example:
:<syntaxhighlight lang="perl" xstyle="width:80%;">
attr myCounter deviceDisplay 36,l,l/m
attr myCounter deviceDisplay 36,kWh,kW
</syntaxhighlight>

;disable [0|1]
:if set to 1 then the module is disabled and closes the connection to a counter device.

;factor
:Define a multiplicator for calculating the power from the impulse count and the time between the first and the last impulse.
:This attribute is outdated and unintuitive so you should avoid it.
:Instead you should specify the attribute pulsesPerUnit or readingPulsesPerUnit[0-9]+ (where [0-9]+ stands for the pin number).

;readingFactor[AD]?[0-9]+
:Override the factor attribute for this individual pin.
:Just like the attribute factor, this is a rather cumbersome way to specify the pulses per kWh.
:Instead it is advised to use the attribute pulsesPerUnit or readingPulsesPerUnit[0-9]+ (where [0-9]+ stands for the pin number).

;devVerbose
:this attribute is outdated and has been replaced with the attributes
:<nowiki><syntaxhighlight lang="perl" xstyle="width:80%;">enableHistory, enableSerialEcho, enablePinDebug, enableAnalogDebug, enableDevTime<syntaxhighlight lang="perl" xstyle="width:80%;"></nowiki>

== Readings / Events ==

The module creates at least the following readings and events for each defined pin:

;calcCounter.*
:This is recommended reading for counting units based on the pulses and the attribute pulsesPerUnit. It is similar to interpolated long count
:which keeps on counting up after fhem restarts but this counter will take the pulses per Unit attribute into the calculation und thus does not
:count pulses but real Units (kWh, liters or some other unit that is applicable)
:The name of this reading can be changed with the attribute readingNameCalcCount[AD]?[0-9]+ where [AD]?[0-9]+ stands for the pin description e.g. D4.
: Another reading with the same name but ending in _i (e.g. calcCounterD4_i) will show how many kWh (or other units) of the above value is interpolated.

;pin.* e.g. pinD4
:the current internal count at this pin (internal to the Arduino / ESP device, starts at 0 when the device restarts).
:The name of this reading can be changed with the attribute readingNameCount[AD]?[0-9]+ where [AD]?[0-9]+ stands for the pin description e.g. D4

;long.* e.g. longD5
:long count which keeps on counting up after fhem restarts whereas the pin.* count is only a temporary internal count that starts at 0 when the arduino board starts.
:The name of this reading can be changed with the attribute readingNameLongCount[AD]?[0-9]+ where [AD]?[0-9]+ stands for the pin description e.g. D4

;interpolatedLong.*
:like long.* but when the Arduino restarts the potentially missed pulses are interpolated based on the pulse rate before the restart and after the restart.
:The name of this reading can be changed with the attribute readingNameInterpolatedCount[AD]?[0-9]+ where [AD]?[0-9]+ stands for the pin description e.g. D4

;reject.*
:counts rejected pulses that are shorter than the specified minimal pulse length.

;power.*
:the current calculated power / flow at this pin.
:The name of this reading can be changed with the attribute readingNamePower[AD]?[0-9]+ where [AD]?[0-9]+ stands for the pin description e.g. D4.
:This reading depends on the attributes pulsesPerUnit as well as readingFlowUnitTime or flowUnitTime for calculation

;pinHistory.*
:shows detailed information of the last pulses. This is only available when a minimal pulse length is specified for this pin. Also the total number of impulses recorded here is :limited to 20 for all pins together. The output looks like -36/7:0C, -29/7:1G, -22/8:0C, -14/7:1G, -7/7:0C, 0/7:1G
:The first number is the relative time in milliseconds when the input level changed, followed by the length in milliseconds, the level and the internal action.
:-36/7:0C for example means that 36 milliseconds before the reporting started, the input changed to 0V, stayed there for 7 milliseconds and this was counted.

;countDiff.*
:delta of the current count to the last reported one. This is used together with timeDiff.* to calculate the power consumption.

;timeDiff.*
:time difference between the first pulse in the current observation interval and the last one. Used togehter with countDiff to calculate the power consumption.

;seq.*
:internal sequence number of the last report from the board to Fhem.

;runTime.*
:this reading will only be created when the attribute runTime[AD]?[0-9]+ is set for a given pin.
:It contains the time in seconds that the consumption / flow observed at the specified pin has not ben zero.
:If a water meter which outputs 10 impulses per liter on its digital output is for example connected to GPIO pin D6,
:then if the attribute runTimeD6 is set to 1, the reading runTimeD6 will show for how many seconds the water has been flowing without a stop longer than the
:observation interval specifie in the interval-attribute. This is helpful when you want to create alerts in case someone forgot to close a water tap. [[Kategorie:Other Components]] [[Kategorie:Energieverbrauchsmessung]]