DOIFtools: Unterschied zwischen den Versionen

Aus FHEMWiki
 
(106 dazwischenliegende Versionen desselben Benutzers werden nicht angezeigt)
Zeile 5: Zeile 5:
|ModTechName=98_DOIFtools.pm
|ModTechName=98_DOIFtools.pm
|ModOwner=Ellert}}
|ModOwner=Ellert}}
{{Baustelle}}
 
[[DOIFtools]] ist ein Modul zum [[DOIF]], das Benutzern dessen Handhabung erleichtern soll.   
[[Datei:Helper doiftools.png|50px|bottom]] ist ein Modul zum [[DOIF]], das Benutzern dessen Handhabung erleichtern soll.   


== Features / Funktionen ==
== Features / Funktionen ==
Das Modul '''DOIFtools''' enthält Funktionen zur Unterstützung des Benutzers im Umgang mit [[DOIF]]:
Das Modul '''DOIFtools''' enthält Funktionen zur Unterstützung des Benutzers im Umgang mit [[DOIF]]:


* erstellen von readingsGroup Definitionen, zur Beschriftung von Frontendelementen.
* erstellen von readingsGroup Definitionen, zur Beschriftung von Frontendelementen.
* erstellen eines Debug-Logfiles, in dem mehrere DOIF und Geräte, auf die in ihnen verwiesen wird, geloggt werden.
* erstellen eines Debug-Logfiles, in dem mehrere DOIF und zugehörige Geräte geloggt werden.
* optionales DOIF-Listing bei jeder Status und Wait-Timer Aktualisierung im Debug-Logfile.
* Navigation zwischen den DOIF-Listings im Logfile, wenn es über DOIFtools geöffnet wird.
* erstellen von userReadings in DOIF-Geräten zur Anzeige des realen Datums bei Wochentag behafteten Timern.
* erstellen von userReadings in DOIF-Geräten zur Anzeige des realen Datums bei Wochentag behafteten Timern.
* löschen von benutzerdefinierten Readings in DOIF-Definitionen über eine Mehrfachauswahl.
* löschen von benutzerdefinierten Readings in DOIF-Definitionen über eine Mehrfachauswahl.
* erfassen statistischer Daten über Events.
* erfassen statistischer Daten über Events.
* Begrenzung der Datenerfassungsdauer.
* erstellen eines Statistikreports.
* erstellen eines Statistikreports.
* Liste aller DOIF-Definitionen in probably associated with.
* Liste aller DOIF-Definitionen in probably associated with.
Zeile 21: Zeile 25:
* Zugriff aus DOIFtools auf vorhandene DOIFtoolsLog-Logdateien.
* Zugriff aus DOIFtools auf vorhandene DOIFtoolsLog-Logdateien.
* einblenden des Event-Monitor in der Detailansicht.
* einblenden des Event-Monitor in der Detailansicht.
* ermöglicht den Zugriff auf den Event Monitor in der Detailansicht von DOIF.
* prüfen der DOIF Definitionen mit Empfehlungen.
* erstellen eigener Shortcuts
* erstellen eines FHEM-Menüeintrag per Attribut
* anzeigen der laufenden "wait_timer"
== Bedienungsanleitung ==


Das Modul kann hier heruntergeladen werden: {{Link2Forum|Topic=63938|LinkText=Forenthread}}
=== Definition ===
Es kann nur eine Definition (Instanz) je FHEM-Installation angelegt werden.


== Bedienungsanleitung ==
Die Definition wird beim Anlegen des [[Gerät|Gerätes]] mit den Namen der vorhandenen DOIF-Definitionen ergänzt und im Betrieb aktualisiert.
<pre>define DOIFtools DOIFtools</pre>
 
Im Folgenden wird davon ausgegangen, dass eine DOIFtools Instanz mit dem Namen '''DOIFtools''' existiert.
 
==== Definitionsvorschlag zum Import über [[DOIF/Import_von_Code_Snippets|Raw definition]] ====
 
<pre>
defmod DOIFtools DOIFtools
attr DOIFtools DOIFtoolsEventMonitorInDOIF 1
attr DOIFtools DOIFtoolsExecuteDefinition 1
attr DOIFtools DOIFtoolsExecuteSave 1
attr DOIFtools DOIFtoolsMyShortcuts ##My Shortcuts:,,list DOIFtools,fhem?cmd=list DOIFtools,remove_DOIFtoolsLog,fhem?cmd=delete DOIFtoolsLog;%22rm ./log/DOIFtoolsLog*.log%22,SubsInPackageDOIF,fhem?cmd=get DOIFtools subsInPackageDOIF
attr DOIFtools DOIFtoolsMenuEntry 1
attr global language DE
save
</pre>
 
=== Ansicht gestalten ===
[[Datei:doiftools_cockpit_bes.png|800px]]
 
==== Moduleigene Shortcuts ====
Die moduleigenen Shortcuts '''A''' können ausgeblendet werden.
<pre>attr DOIFtools DOIFtoolsHideModulShortcuts 1</pre>
 
==== Benutzerdefinierte Shortcuts ====
Eigene Shortcuts '''B''' können erstellt werden, es gilt die Syntax für [https://fhem.de/commandref_DE.html#menuEntries menuEntries].
 
Wenn der Shortcut-Name mit <code>##</code> beginnt werden die nachfolgenden Zeichen bis zum Komma als HTML interpretiert, der Befehl bleibt dann leer.
<pre>attr DOIFtools DOIFtoolsMyShortcuts &lt;Shortcut-Name,Befehl&gt;, ...</pre>
 
===== Beispiel =====
Legt den Befehl <code>list DOIFtools</code> als Shortcut an.
<pre>attr DOIFtools DOIFtoolsMyShortcuts ##<br>My Shortcuts:,,list DOIFtools,fhem?cmd=list DOIFtools</pre>
 
==== Set und Get Shortcuts ====
Die Shortcuts für Set- und Get-Befehle '''C''' können ausgeblendet werden.
<pre>attr DOIFtools DOIFtoolsHideGetSet 1</pre>
 
==== Lookup-Fenster in DOIFtools abschalten ====
Wenn sich kein Lookup-Fenster beim Überfahren der Links im Abschnitt ''probably associated with'' der Detailansicht öffen soll, kann es abgeschaltet werden.
<pre>attr DOIFtools DOIFtoolsNoLookUp 1</pre>
 
==== Lookup-Fenster in DOIF abschalten ====
Wenn sich kein Lookup-Fenster beim Überfahren der Links im Abschnitt ''probably associated with'' der Detailansicht öffen soll, kann es abgeschaltet werden.
<pre>attr DOIFtools DOIFtoolsNoLookUpInDOIF 1</pre>
 
===== Beispiel Lookup-Fenster =====
[[Datei:lookup_assoc.png|800px]]
 
=== Sprache für die Ausgabe von checkDOIF, doStatistics, usw. festlegen ===
 
Die Sprache der Datenausgabe des Moduls wird durch das globale Attribut '''language''' bestimmt.
 
Deutsch wird auf folgende Weise eingestellt
<pre>attr global language DE</pre>
 
=== Menüeintrag anlegen ===
Für den schnellen Zugriff auf DOIFtools kann ein Menüeintrag angelegt werden.
<pre>attr DOIFtools DOIFtoolsMenuEntry 1</pre>


=== Erstellen eines Debug-Logfile===
=== Erstellen eines Debug-Logfile===
Ein FileLog-Gerät kann per Get-Befehl erstellt werden.
<pre>get DOIFtools DOIF_to_Log <Liste der gleichzeitig zu loggenden DOIF></pre>
Bei der Fehlersuche in einem DOIF wird nur dieses DOIF ausgewählt. Wenn voneinander abhängige DOIF untersucht werden sollen, dann müssen alle abhängigen DOIF ausgewählt werden.
Es werden alle in der Definition erkannten Geräte und die wahrscheinlich verbundenen Geräte geloggt.
Die [[FileLog]]-Definition wird angezeigt und kann verwendet werden, um sie mit [[DOIF/Import_von_Code_Snippets|Raw definition]] zu importieren.
Wenn das Attribut '''DOIFtoolsExecuteDefinition''' gesetzt ist, wird der Code der Definition ausgeführt und das FileLog-Gerät erstellt.
<pre>attr DOIFtools DOIFtoolsExecuteDefinition 1</pre>
Wenn die Definition auch automatisch gespeichert werden soll, muss das Attribut '''DOIFtoolsExecuteSave''' gesetzt werden.
<pre>attr DOIFtools DOIFtoolsExecuteSave 1</pre>
==== Listings in DOIFtoolsLog einschliessen ====
Wenn mehr Informationen zum Finden eines Fehlers benötigt werden, kann ein DOIF [[List|Listing]] zugeschaltet werden.
[[List|Listing]] werden erzeugt, wenn im DOIF ein Statuswechsel stattfindet oder ein Wait-Timer aktualisiert wird.
Wenn das Logfile, das die Listings enthält, aus der Detailansicht von DOIFtools geöffnet wird, kann im Logfile zu den Listings navigiert werden.
<pre>set DOIFtools specialLog 1</pre>
[[Event#Beschr.C3.A4nken_von_Events|Events einschränkende Attribute]] sollten, soweit die Funktion nicht beeinträchtigt wird, in den zu loggenden DOIF abgeschaltet werden.
==== Pfad zur DOIFtoolsLog Datei ====
Die Logdatei wird im Standardpfad <code>./log/</code> abgelegt.
Wenn das globale Attribut '''logdir''' gesetzt ist, wird dieser Pfad verwendet.
Ist das Attribut '''DOIFtoolsLogDir''' gesetzt, wird dieser Pfad verwendet. Die Pfadangabe muss mit <code>/</code> abgeschlossen werden.


=== Erstellen einer ReadingsGroup für ein DOIF ===
=== Erstellen einer ReadingsGroup für ein DOIF ===
Wenn in einem DOIF [[Readings]] als Eingabeelemente verwendet werden, erscheint keine Beschschriftung für diese Elemente.
Mit einer [[readingsGroup|Readingsgroup]] können Eingabeelemente beschriftet werden.
DOIFtools kann eine entsprechende [[readingsGroup|Readingsgroup]] für DOIF erstellen, siehe [[DOIF/Ein-_und_Ausgabe_in_FHEMWEB_und_Tablet-UI_am_Beispiel_einer_Schaltuhr#FHEMWEB|Beispiel]].
DOIFtools benutzt das Attribut '''[http://fhem.de/commandref_DE.html#DOIF_setList__readingList readingList] des DOIF, um die [[Readings]] zu ermitteln, die in der [[readingsGroup|Readingsgroup]] verwendet werden.'''
<pre>get DOIFtools readingsGroup_for <Liste der DOIF, für die eine readingsGroup estellt werden soll></pre>
Der Get-Befehl bericksichtigt die Attribute '''[[DOIFtools#Erstellen_eines_Debug-Logfile|DOIFtoolsExecuteDefinition]]''' und '''[[DOIFtools#Erstellen_eines_Debug-Logfile|DOIFtoolsExecuteSave]]'''.


=== Erstellen von UserReadings für Timer mit Wochentageinschränkung ===
=== Erstellen von UserReadings für Timer mit Wochentageinschränkung ===
Durch einen Wochentag eingeschränkte Timer werden im DOIF nicht mit dem Auslösedatum angezeigt.
Wenn das Auslösedatum benötigt wird, kann dies über das Attribut '''[[userReadings]]''', das im DOIF gesetzt werden muss, berechnet werden. Einträge in einer [https://fhem.de/commandref_DE.html#holiday holiday-Datei] werden für die nächsten 7 Tage berücksichtigt, falls im Attribut [https://fhem.de/commandref_DE.html#holiday2we holiday2we] eine holiday-Datei angegeben ist.
<pre>get userReading_nextTimer_for <Liste der DOIF in denen userReadings gesetzt werden sollen></pre>
Bestehende userReadings werden nicht überschrieben, es wird eine manuelle Änderung vorgeschlagen.
Nachdem Löschen der DOIFtools-Definition steht die Funktion zur Berechnung der userReadings zur Berechnung des tatsächlichen Auslösedatums nicht mehr zur Verfügung.
==== Beispiel ====
Am 5.1.2017 um 8 Uhr, einem Donnerstag (|4), zeigt DOIF einen Timer <code>[12:00|3]</code> (mittwochs) mit dem Datum 05.01.2017 an.
[[Datei:realdate_mit_mark.png|none|600px|DOIF mit userReadings und tatsächlichem Auslösedatum]]
Das echte Auslösedatum ist der 11.01.2017 (Mittwoch), das wird durch '''[[userReadings]]''' berechnet.
=== Löschen von Readings ===
FHEM stellt einen Befehl zum Löschen von Readings bereit. Name und Readingname kann durch einen regulären Ausdruck angegeben werden.
Werden die regulären Ausdrücke ungenau formuliert, können Readings unbeabsichtigt gelöscht werden.


=== Löschen benutzerdefinierter Readings ===
Die nachstehenden Methoden sollen das Risiko mindern.
<pre>deletereading <name> <readingname></pre>
 
==== Löschen benutzerdefinierter Readings im DOIF ====
Etwas komfortabler können Readings im DOIF gelöscht werden. Die Methode verringert die Gefahr moduleigene Readings zu löschen.
Zuerst muss das DOIF gesetzt werden in dem Readings gelöscht werden sollen.
<pre>set DOIFtools targetDOIF <Name eines DOIF></pre>
 
Dann können die Readings ausgewählt werden, die zu löschen sind.
<pre>set DOIFtools deleteReadingsInTargetDOIF <Liste der zu löschenden benutzerdefinierten Readings></pre>
{{Hinweis|Die Methode in DOIFtools verhindert, dass Readings gelöscht werden, die vom DOIF-Modul genutzt werden.}}
 
==== Löschen von Readings in anderen Geräten ====
 
Zuerst muss der Gerätename gesetzt werden in dem Readings gelöscht werden sollen.
<pre>set DOIFtools targetDevice <Name eines Gerätes></pre>
 
Dann können die Readings ausgewählt werden, die zu löschen sind.
<pre>set DOIFtools deleteReadingsInTargetDevice <Liste der zu löschenden Readings></pre>
{{Hinweis|Die Methode in DOIFtools verhindert '''nicht''', dass Readings gelöscht werden, die vom Modul benötigt werden.
 
Beachte den Hinweis unter '''[https://fhem.de/commandref_DE.html#deletereading deletereading]'''}}
 
=== Icon für DOIF setzen ===
 
In den ausgewählten DOIF wird das Attribut '''icon''' auf '''helper_doif''' gesetzt.
<pre>get DOIFtools SetAttrIconForDOIF <Liste der ausgewählten DOIF-Namen></pre>
Der Get-Befehl berücksichtigt das Attribut '''[[DOIFtools#Erstellen_eines_Debug-Logfile|DOIFtoolsExecuteSave]]'''.


=== Erfassen und Auswerten von Statistikdaten ===
=== Erfassen und Auswerten von Statistikdaten ===


Um eine Statistik zu erstellen, müssen zuerst Daten erfasst werden.
Um eine Statistik zu erstellen, müssen zuerst Daten erfasst werden. Die Event-Zähler werden als Readings angezeigt. Die Readings-Namen beginnen mit <code>stat_</code>. Bei einer hohen Zahl von Gerätenamen wird die Detailansicht sehr lang, daher können die Readings ausgeblendet werden:
<pre>attr DOIFtoolsHideStatReadings 1</pre>
{{Hinweis|Das Setzen oder Ändern des Attributes löscht die bereits erfassten Daten und stopt die Datenerfassung. Daher sollte das Attribut vor Beginn der Datenerfassung gesetzt werden.}}


Zuerst sind die Modultypen festzulegen, die bei der Datenerfassunberücksichtigt werden.
Zuerst sind die Modultypen festzulegen, die bei der Datenerfassunberücksichtigt werden.
<pre>set DOIFtools statisticsTYPEs <Auswahlliste</pre>
<pre>set DOIFtools statisticsTYPEs <Auswahlliste</pre>
Danach wird die Datenerfassung gestartet.
Danach wird die Datenerfassung gestartet.
<pre>set doStatistics enabled</pre>
<pre>set DOIFtools doStatistics enabled</pre>
Die Datenerfassung kann unterbrochen werden.
Die Datenerfassung kann unterbrochen werden.
<pre>set doStatistics disabled</pre>
<pre>set DOIFtools doStatistics disabled</pre>
Auch eine Zeitspanne, die im Attribut [http://fhem.de/commandref_DE.html#disabledForIntervals disabledForIntervals] gesetzt ist, unterbricht die Datenerfassung.
Die Zeitdauer der Datenerfassung kann gesetzt werden
 
<pre>set DOIFtools recording_target_duration <Auswahlliste|ganzzahliger Wert in Stunden></pre>
Auch eine Zeitspanne, die im Attribut [http://fhem.de/commandref_DE.html#disabledForIntervals '''disabledForIntervals'''] gesetzt ist, unterbricht die Datenerfassung.


==== Erfasste Daten löschen ====
Die erfassten Daten können gelöscht werden.
Die erfassten Daten können gelöscht werden.
<pre>set doStatistics deleted</pre>
<pre>set DOIFtools doStatistics deleted</pre>


==== Erfasste Daten loggen vor dem Löschen ====
Die erfassten Daten können vor dem Löschen geloggt werden.
Wenn das Attribut '''DOIFtoolsEventOnDeleted''' gesetzt ist, werden für alle ''stat_'' Readings Events erzeugt. Damit können die erfassten Daten über ein Log-Gerät ([[DbLog]], [[FileLog]]) archiviert werden.
<pre>attr  DOIFtools DOIFtoolsEventOnDeleted 1</pre>


====Event-Report erstellen ====
Nach und während der Datenerfassung können die vorhandenen Daten ausgewertet und als Bericht dargestellt werden.
Nach und während der Datenerfassung können die vorhandenen Daten ausgewertet und als Bericht dargestellt werden.
<pre>get statisticsReport</pre>
<pre>get DOIFtools statisticsReport</pre>
===== Filtern der Datenauswertung =====
Die im Bericht auszuwertenden Geräte können über einen Filter eingeschränkt werden. Der Filter ist ein [[regulärer Ausdruck]] auf den Gerätenamen, der vorgegebene Filter ist <code>.*</code> für alle über das Attribut '''statisticsTYPEs''' ausgewählten Geräte.
<pre>set DOIFtools statisticsDeviceFilterRegex <Filter-Regexp></pre>
Die Auswertung kann auch über die Event-Rate gefiltert werden. Ein Gerät wird nur dann in die Auswertung einbezogen, wenn seine Event-Rate größer oder gleich des Wertes im Reading '''statisticsShowRate_ge''' ist.
<pre>set DOIFtools statisticsShowRate_ge <Ganzzahl für die Event-Rate></pre>


==== Bewertung des Ergebnisses der Datenauswertung ====
==== Bewertung des Ergebnisses der Datenauswertung ====
Hinsichtlich der Systemauslastung ist hohe Event-Rate schlechter zu bewerten als eine niedrige Rate.
Hinsichtlich der Systemauslastung ist hohe Event-Rate schlechter zu bewerten als eine niedrige Rate.


== Bekannte Probleme ==
Eine hohe Event-Rate und ein nicht gesetztes ''event-on...'' Attribut kann auf Handlungsbedarf hinweisen.
Zum Erstellen des [[regulärer Ausdruck|regulären Ausdrucks]] der [[FileLog|FileLog-Definition]] werden keine [[regulärer Ausdruck|regulären Ausdrücke]]  der zu loggenden [[DOIF|DOIF-Geräte]] ausgewertet.
 
===== Beispiel eines Event-Reports =====
In dem Beispiel ist eine hohe Event-Rate markiert, für ein Gerät ohne Event-Beschränkung.
[[Datei:eventreport.png|none|600px|Beispiel Report]]
 
==== Andere Tools zur Performanceanalyse ====
* [[apptime]], {{Link2CmdRef|Lang=en|Anker=apptime}}
* [[perfmon]]
* [[freezemon]], {{Link2CmdRef|Lang=de|Anker=freezemon}}
 
=== Zugriff auf den Event-Monitor in der Detailansicht von DOIFtools ===
 
Über den Link '''toggle''' wird der Event-Monitor ein- und ausgeschaltet.
 
==== Eine neue DOIF-Definition mit DOIF-Operanden aus einer Eventzeile erzeugen ====
 
* Event-Monitor anzeigen
* eine Event-Zeile vollständig markieren
* einen Operanden auswählen
* ggf. die Definitionszeile ändern
* den Knopf {{Taste|Execute Definition}} betätigen
Es öffnet sich die Detailansicht des neuen [[Gerät|Gerätes]], dort können weitere Ergänzungen erfolgen.
 
=== Zugriff auf den Event-Monitor in der Detailansicht des DOIF ===
 
Der Zugriff auf den Event-Monitor in der Detailansicht des DOIF wird ermöglicht, wenn in DOIFtools das Attribut '''eventMonitorInDOIF''' gesetzt wird.
<pre>attr DOIFtools DOIFtoolsEventMonitorInDOIF 1</pre>
 
==== Event-Monitor im DOIF direkt vor den Readings anzeigen ====
 
Zum Beobachten der Reaktion des DOIF auf Events ist es hilfreich den Event-Monitor und die Readings des DOIF dicht beieinander anzuzeigen.
Daher kann der Event-Monitor vor die Readings verschoben werden.
<pre>attr DOIFtools DOIFtoolsEMbeforeReadings 1</pre>
 
===== Beispiel: in der Detailansicht geöffneter Event-Monitor =====
 
Geöffneter Event-Monitor in der DOIF Detailansicht.
 
In der linken Ansicht wird der Eventmonitor über den Internals angezeigt, in der rechten Ansicht über  den Readings.
[[Datei:EMinDOIFKomp.png|none|600px|Geöffneter Event-Monitor in der DOIF Detailansicht]]
 
==== DOIF-Operanden aus einer Eventzeile erzeugen  und in den DEF-Editor einfügen ====
Wenn im DOIF oder in DOIFtools eine Event-Zeile markiert wird, werden verschiedene DOIF-Operatoren vorgeschlagen, die zeigen, wie das Event in eine DOIF-Definition eingebunden werden kann. In der Eingabezeile des Dialogs kann der Operator angepasst werden. Beim Betätigen des Knopfes {{Taste|Open DEF-Editor}} wird der Inhalt der Eingabezeile des Dialogs in die Zwischenablage kopiert. Danach wird der DEF-Editor der aktuellen Detailansicht geöffnet. Mit {{Taste|Strg-v}} wird der Inhalt der Zwischenablage an der Cursor-Position eingefügt.
 
===== Beispiel: Verwendungsvorschlag zur Nutzung eines Events als DOIF-Operanden =====
 
[[Datei:EventMonitorKomp.png|none|600px|Event mit Verwendungsvorschlag]]
 
=== DOIF Prüfung und Empfehlungen ===
DOIFtools kann die DOIF-Definitionen auf besimmte Schreibweisen prüfen und Empfehlungen geben.
<pre>get DOIFtools checkDOIF</pre>
 
=== Laufende Wait-Timer anzeigen ===
In manchen Situationen ist es störend, wenn bei einem Neustart ein laufender Wait-Timer abgebrochen wird.
Um das bei einem manuellen Neustart zu berücksichtigen, kann man sich die laufenden Wait-Timer anzeigen lassen. Nachrichtlich werden laufende [[Blocking Call|Blocking Calls]] angezeigt.
<pre>get DOIFtools runningTimerInDOIF</pre>
 
=== Farbtabellen erzeugen ===
Mit den folgenden Befehlen lassen sich für einen Wertebereich schrittweise interpolierte Farbnummern und RGB-Werte zu den einzelnen Schrittwerten anzeigen.
 
==== Lineare Interpolation ====
Mit den nachstehenden Befehl wird eine linear interpolierte Reihe von Farbwerten erzeugt.
<pre>get DOIFtools linearColorGradient <start color>,<end color>,<minimal value>,<maximal value>,<step width></pre>
 
==== Modellabhängige Interpolation ====
Mit den nachstehenden Befehl wird eine modellbedingte interpolierte Reihe von Farbwerten erzeugt.
<pre>get DOIFtools modelColorGradient <minimal value>,<middle value>,<maximal value>,<step width>,<color model></pre>
Gültige Werte für '''color model''' sind 0, 1, 2 oder ein Array aus fünf RGB-Farbwerten.
 
Zur Interpolation wird eine [[Color#Farbskala_mit_Color::pahColor|Farbskala mit Color::pahColor]] erzeugt.
 
==== Interpolation über HUE ====
Mit den nachstehenden Befehl wird eine über den HUE-Wert interpolierte Reihe von Farbwerten erzeugt.
<pre>get DOIFtools hsvColorGradient <start HUE>,<end HUE>,<minimal value>,<maximal value>,<step width>,<saturation>,<lightness></pre>
Gültige Werte für '''HUE''' von <code>0-360</code>, für '''saturation'''  und '''lightness''' <code>0-100</code>.
 
Zur Interpolation wird eine [[Color|Farbskala mit Color::hsv2color]] erzeugt.
 
==== Beispiele ====
 
<pre>get DOIFtools linearColorGradient #0000FF,#FF0000,7,30,1</pre>
erzeugt einen linearen Farbübergang von Blau nach Rot.
 
[[Datei:linearer_farbgradient.png|none|500px|Linearer Farbgradient]]
 
<pre>get DOIFtools modelColorGradient 7,20,30,1,0</pre>
erzeugt einen modellbedingten einen Farbübergang für das eingebaute Modell 0.
<pre>get DOIFtools modelColorGradient 0,50,100,5,[255,255,0,127,255,0,0,255,0,0,255,255,0,127,255]</pre>
erzeugt einen modellbedingten einen Farbübergang für für ein eigenes Modell <code>0,50,100,5,[255,255,0,127,255,0,0,255,0,0,255,255,0,127,255]</code>.
 
[[Datei:modellbedingter_farbgradient.png|none|500px|Modellbedingter Farbgradient]]
 
<pre>get DOIFtools hsvColorGradient 240,360,7,30,1,80,80</pre>
erzeugt über den HUE-Wert einen Farbübergang von Blau nach Rot.
 
[[Datei:hsv_farbgradient.png|none|500px|Linearer Farbgradient]]
 
=== MODEL Perl: Anzeige benutzerdeklarierter Subs im Package DOIF ===
Die Funktion dient zum Auffinden von selbstdefinierten Subs. Wenn die Subs in einem Gerät definiert wurden, wird ein Link zu dem Gerät angezeigt.
 
<pre>get DOIFtools subsInPackageDOIF</pre>
 
== Bekannte Probleme/Einschränkungen/Hinweise ==
* Zum Erstellen des [[regulärer Ausdruck|regulären Ausdrucks]] der [[FileLog|FileLog-Definition]] werden keine [[regulärer Ausdruck|regulären Ausdrücke]]  aus den zu loggenden [[DOIF|DOIF-Geräte]] ausgewertet.
* Beim Erzeugen eines DOIF-Operanden aus einem [[Event]] des [[Event monitor|Eventmonitors]] wird der erste Begriff nach dem [[Gerätename|Gerätenamen]], dem unmittelbar ein Doppelpunkt folgt, als [[Readings|Reading]] interpretiert.


== Links ==
== Links ==
* [[DOIF]]
* [[DOIF]]
* [[Event]]
* [[event-on-change-reading]]
* [[event-on-update-reading]]
* {{Link2Forum|Topic=63938|LinkText=Forenthread}}
* {{Link2Forum|Topic=63938|LinkText=Forenthread}}
* https://blog.chanoa.de/fhem-performance

Aktuelle Version vom 16. August 2020, 13:37 Uhr

DOIFtools
Zweck / Funktion
unterstützende Funktionen zur besseren Handhabung von DOIF
Allgemein
Typ Hilfsmodul
Details
Dokumentation EN / DE
Support (Forum) Automatisierung/DOIF
Modulname 98_DOIFtools.pm
Ersteller Ellert
Wichtig: sofern vorhanden, gilt im Zweifel immer die (englische) Beschreibung in der commandref!


Helper doiftools.png ist ein Modul zum DOIF, das Benutzern dessen Handhabung erleichtern soll.

Features / Funktionen

Das Modul DOIFtools enthält Funktionen zur Unterstützung des Benutzers im Umgang mit DOIF:

  • erstellen von readingsGroup Definitionen, zur Beschriftung von Frontendelementen.
  • erstellen eines Debug-Logfiles, in dem mehrere DOIF und zugehörige Geräte geloggt werden.
  • optionales DOIF-Listing bei jeder Status und Wait-Timer Aktualisierung im Debug-Logfile.
  • Navigation zwischen den DOIF-Listings im Logfile, wenn es über DOIFtools geöffnet wird.
  • erstellen von userReadings in DOIF-Geräten zur Anzeige des realen Datums bei Wochentag behafteten Timern.
  • löschen von benutzerdefinierten Readings in DOIF-Definitionen über eine Mehrfachauswahl.
  • erfassen statistischer Daten über Events.
  • Begrenzung der Datenerfassungsdauer.
  • erstellen eines Statistikreports.
  • Liste aller DOIF-Definitionen in probably associated with.
  • Zugriff auf DOIFtools aus jeder DOIF-Definition über die Liste in probably associated with.
  • Zugriff aus DOIFtools auf vorhandene DOIFtoolsLog-Logdateien.
  • einblenden des Event-Monitor in der Detailansicht.
  • ermöglicht den Zugriff auf den Event Monitor in der Detailansicht von DOIF.
  • prüfen der DOIF Definitionen mit Empfehlungen.
  • erstellen eigener Shortcuts
  • erstellen eines FHEM-Menüeintrag per Attribut
  • anzeigen der laufenden "wait_timer"

Bedienungsanleitung

Definition

Es kann nur eine Definition (Instanz) je FHEM-Installation angelegt werden.

Die Definition wird beim Anlegen des Gerätes mit den Namen der vorhandenen DOIF-Definitionen ergänzt und im Betrieb aktualisiert. 

define DOIFtools DOIFtools

Im Folgenden wird davon ausgegangen, dass eine DOIFtools Instanz mit dem Namen DOIFtools existiert.

Definitionsvorschlag zum Import über Raw definition

defmod DOIFtools DOIFtools
attr DOIFtools DOIFtoolsEventMonitorInDOIF 1
attr DOIFtools DOIFtoolsExecuteDefinition 1
attr DOIFtools DOIFtoolsExecuteSave 1
attr DOIFtools DOIFtoolsMyShortcuts ##My Shortcuts:,,list DOIFtools,fhem?cmd=list DOIFtools,remove_DOIFtoolsLog,fhem?cmd=delete DOIFtoolsLog;%22rm ./log/DOIFtoolsLog*.log%22,SubsInPackageDOIF,fhem?cmd=get DOIFtools subsInPackageDOIF
attr DOIFtools DOIFtoolsMenuEntry 1
attr global language DE
save

Ansicht gestalten

Doiftools cockpit bes.png

Moduleigene Shortcuts

Die moduleigenen Shortcuts A können ausgeblendet werden. 

attr DOIFtools DOIFtoolsHideModulShortcuts 1

Benutzerdefinierte Shortcuts

Eigene Shortcuts B können erstellt werden, es gilt die Syntax für menuEntries.

Wenn der Shortcut-Name mit ## beginnt werden die nachfolgenden Zeichen bis zum Komma als HTML interpretiert, der Befehl bleibt dann leer. 

attr DOIFtools DOIFtoolsMyShortcuts <Shortcut-Name,Befehl>, ...
Beispiel

Legt den Befehl list DOIFtools als Shortcut an. 

attr DOIFtools DOIFtoolsMyShortcuts ##<br>My Shortcuts:,,list DOIFtools,fhem?cmd=list DOIFtools

Set und Get Shortcuts

Die Shortcuts für Set- und Get-Befehle C können ausgeblendet werden. 

attr DOIFtools DOIFtoolsHideGetSet 1

Lookup-Fenster in DOIFtools abschalten

Wenn sich kein Lookup-Fenster beim Überfahren der Links im Abschnitt probably associated with der Detailansicht öffen soll, kann es abgeschaltet werden. 

attr DOIFtools DOIFtoolsNoLookUp 1

Lookup-Fenster in DOIF abschalten

Wenn sich kein Lookup-Fenster beim Überfahren der Links im Abschnitt probably associated with der Detailansicht öffen soll, kann es abgeschaltet werden. 

attr DOIFtools DOIFtoolsNoLookUpInDOIF 1
Beispiel Lookup-Fenster

Lookup assoc.png

Sprache für die Ausgabe von checkDOIF, doStatistics, usw. festlegen

Die Sprache der Datenausgabe des Moduls wird durch das globale Attribut language bestimmt.

Deutsch wird auf folgende Weise eingestellt 

attr global language DE

Menüeintrag anlegen

Für den schnellen Zugriff auf DOIFtools kann ein Menüeintrag angelegt werden. 

attr DOIFtools DOIFtoolsMenuEntry 1

Erstellen eines Debug-Logfile

Ein FileLog-Gerät kann per Get-Befehl erstellt werden. 

get DOIFtools DOIF_to_Log <Liste der gleichzeitig zu loggenden DOIF>

Bei der Fehlersuche in einem DOIF wird nur dieses DOIF ausgewählt. Wenn voneinander abhängige DOIF untersucht werden sollen, dann müssen alle abhängigen DOIF ausgewählt werden.

Es werden alle in der Definition erkannten Geräte und die wahrscheinlich verbundenen Geräte geloggt.

Die FileLog-Definition wird angezeigt und kann verwendet werden, um sie mit Raw definition zu importieren.

Wenn das Attribut DOIFtoolsExecuteDefinition gesetzt ist, wird der Code der Definition ausgeführt und das FileLog-Gerät erstellt. 

attr DOIFtools DOIFtoolsExecuteDefinition 1

Wenn die Definition auch automatisch gespeichert werden soll, muss das Attribut DOIFtoolsExecuteSave gesetzt werden. 

attr DOIFtools DOIFtoolsExecuteSave 1

Listings in DOIFtoolsLog einschliessen

Wenn mehr Informationen zum Finden eines Fehlers benötigt werden, kann ein DOIF Listing zugeschaltet werden.

Listing werden erzeugt, wenn im DOIF ein Statuswechsel stattfindet oder ein Wait-Timer aktualisiert wird.

Wenn das Logfile, das die Listings enthält, aus der Detailansicht von DOIFtools geöffnet wird, kann im Logfile zu den Listings navigiert werden. 

set DOIFtools specialLog 1

Events einschränkende Attribute sollten, soweit die Funktion nicht beeinträchtigt wird, in den zu loggenden DOIF abgeschaltet werden.

Pfad zur DOIFtoolsLog Datei

Die Logdatei wird im Standardpfad ./log/ abgelegt. Wenn das globale Attribut logdir gesetzt ist, wird dieser Pfad verwendet. Ist das Attribut DOIFtoolsLogDir gesetzt, wird dieser Pfad verwendet. Die Pfadangabe muss mit / abgeschlossen werden.

Erstellen einer ReadingsGroup für ein DOIF

Wenn in einem DOIF Readings als Eingabeelemente verwendet werden, erscheint keine Beschschriftung für diese Elemente. Mit einer Readingsgroup können Eingabeelemente beschriftet werden. DOIFtools kann eine entsprechende Readingsgroup für DOIF erstellen, siehe Beispiel.

DOIFtools benutzt das Attribut readingList des DOIF, um die Readings zu ermitteln, die in der Readingsgroup verwendet werden. 

get DOIFtools readingsGroup_for <Liste der DOIF, für die eine readingsGroup estellt werden soll>

Der Get-Befehl bericksichtigt die Attribute DOIFtoolsExecuteDefinition und DOIFtoolsExecuteSave.

Erstellen von UserReadings für Timer mit Wochentageinschränkung

Durch einen Wochentag eingeschränkte Timer werden im DOIF nicht mit dem Auslösedatum angezeigt. Wenn das Auslösedatum benötigt wird, kann dies über das Attribut userReadings, das im DOIF gesetzt werden muss, berechnet werden. Einträge in einer holiday-Datei werden für die nächsten 7 Tage berücksichtigt, falls im Attribut holiday2we eine holiday-Datei angegeben ist. 

get userReading_nextTimer_for <Liste der DOIF in denen userReadings gesetzt werden sollen>

Bestehende userReadings werden nicht überschrieben, es wird eine manuelle Änderung vorgeschlagen.

Nachdem Löschen der DOIFtools-Definition steht die Funktion zur Berechnung der userReadings zur Berechnung des tatsächlichen Auslösedatums nicht mehr zur Verfügung.

Beispiel

Am 5.1.2017 um 8 Uhr, einem Donnerstag (|4), zeigt DOIF einen Timer [12:00|3] (mittwochs) mit dem Datum 05.01.2017 an.

DOIF mit userReadings und tatsächlichem Auslösedatum

Das echte Auslösedatum ist der 11.01.2017 (Mittwoch), das wird durch userReadings berechnet.

Löschen von Readings

FHEM stellt einen Befehl zum Löschen von Readings bereit. Name und Readingname kann durch einen regulären Ausdruck angegeben werden. Werden die regulären Ausdrücke ungenau formuliert, können Readings unbeabsichtigt gelöscht werden.

Die nachstehenden Methoden sollen das Risiko mindern. 

deletereading <name> <readingname>

Löschen benutzerdefinierter Readings im DOIF

Etwas komfortabler können Readings im DOIF gelöscht werden. Die Methode verringert die Gefahr moduleigene Readings zu löschen. Zuerst muss das DOIF gesetzt werden in dem Readings gelöscht werden sollen. 

set DOIFtools targetDOIF <Name eines DOIF>

Dann können die Readings ausgewählt werden, die zu löschen sind. 

set DOIFtools deleteReadingsInTargetDOIF <Liste der zu löschenden benutzerdefinierten Readings>
Info blue.png
Die Methode in DOIFtools verhindert, dass Readings gelöscht werden, die vom DOIF-Modul genutzt werden.


Löschen von Readings in anderen Geräten

Zuerst muss der Gerätename gesetzt werden in dem Readings gelöscht werden sollen. 

set DOIFtools targetDevice <Name eines Gerätes>

Dann können die Readings ausgewählt werden, die zu löschen sind. 

set DOIFtools deleteReadingsInTargetDevice <Liste der zu löschenden Readings>
Info blue.png
Die Methode in DOIFtools verhindert nicht, dass Readings gelöscht werden, die vom Modul benötigt werden. Beachte den Hinweis unter deletereading


Icon für DOIF setzen

In den ausgewählten DOIF wird das Attribut icon auf helper_doif gesetzt. 

get DOIFtools SetAttrIconForDOIF <Liste der ausgewählten DOIF-Namen>

Der Get-Befehl berücksichtigt das Attribut DOIFtoolsExecuteSave.

Erfassen und Auswerten von Statistikdaten

Um eine Statistik zu erstellen, müssen zuerst Daten erfasst werden. Die Event-Zähler werden als Readings angezeigt. Die Readings-Namen beginnen mit stat_. Bei einer hohen Zahl von Gerätenamen wird die Detailansicht sehr lang, daher können die Readings ausgeblendet werden: 

attr DOIFtoolsHideStatReadings 1
Info blue.png
Das Setzen oder Ändern des Attributes löscht die bereits erfassten Daten und stopt die Datenerfassung. Daher sollte das Attribut vor Beginn der Datenerfassung gesetzt werden.


Zuerst sind die Modultypen festzulegen, die bei der Datenerfassunberücksichtigt werden. 

set DOIFtools statisticsTYPEs <Auswahlliste

Danach wird die Datenerfassung gestartet. 

set DOIFtools doStatistics enabled

Die Datenerfassung kann unterbrochen werden. 

set DOIFtools doStatistics disabled

Die Zeitdauer der Datenerfassung kann gesetzt werden 

set DOIFtools recording_target_duration <Auswahlliste|ganzzahliger Wert in Stunden>

Auch eine Zeitspanne, die im Attribut disabledForIntervals gesetzt ist, unterbricht die Datenerfassung.

Erfasste Daten löschen

Die erfassten Daten können gelöscht werden. 

set DOIFtools doStatistics deleted

Erfasste Daten loggen vor dem Löschen

Die erfassten Daten können vor dem Löschen geloggt werden. Wenn das Attribut DOIFtoolsEventOnDeleted gesetzt ist, werden für alle stat_ Readings Events erzeugt. Damit können die erfassten Daten über ein Log-Gerät (DbLog, FileLog) archiviert werden. 

attr  DOIFtools DOIFtoolsEventOnDeleted 1

Event-Report erstellen

Nach und während der Datenerfassung können die vorhandenen Daten ausgewertet und als Bericht dargestellt werden. 

get DOIFtools statisticsReport
Filtern der Datenauswertung

Die im Bericht auszuwertenden Geräte können über einen Filter eingeschränkt werden. Der Filter ist ein regulärer Ausdruck auf den Gerätenamen, der vorgegebene Filter ist .* für alle über das Attribut statisticsTYPEs ausgewählten Geräte. 

set DOIFtools statisticsDeviceFilterRegex <Filter-Regexp>

Die Auswertung kann auch über die Event-Rate gefiltert werden. Ein Gerät wird nur dann in die Auswertung einbezogen, wenn seine Event-Rate größer oder gleich des Wertes im Reading statisticsShowRate_ge ist. 

set DOIFtools statisticsShowRate_ge <Ganzzahl für die Event-Rate>

Bewertung des Ergebnisses der Datenauswertung

Hinsichtlich der Systemauslastung ist hohe Event-Rate schlechter zu bewerten als eine niedrige Rate.

Eine hohe Event-Rate und ein nicht gesetztes event-on... Attribut kann auf Handlungsbedarf hinweisen.

Beispiel eines Event-Reports

In dem Beispiel ist eine hohe Event-Rate markiert, für ein Gerät ohne Event-Beschränkung.

Beispiel Report

Andere Tools zur Performanceanalyse

Zugriff auf den Event-Monitor in der Detailansicht von DOIFtools

Über den Link toggle wird der Event-Monitor ein- und ausgeschaltet.

Eine neue DOIF-Definition mit DOIF-Operanden aus einer Eventzeile erzeugen

  • Event-Monitor anzeigen
  • eine Event-Zeile vollständig markieren
  • einen Operanden auswählen
  • ggf. die Definitionszeile ändern
  • den Knopf Execute Definition betätigen

Es öffnet sich die Detailansicht des neuen Gerätes, dort können weitere Ergänzungen erfolgen.

Zugriff auf den Event-Monitor in der Detailansicht des DOIF

Der Zugriff auf den Event-Monitor in der Detailansicht des DOIF wird ermöglicht, wenn in DOIFtools das Attribut eventMonitorInDOIF gesetzt wird. 

attr DOIFtools DOIFtoolsEventMonitorInDOIF 1

Event-Monitor im DOIF direkt vor den Readings anzeigen

Zum Beobachten der Reaktion des DOIF auf Events ist es hilfreich den Event-Monitor und die Readings des DOIF dicht beieinander anzuzeigen. Daher kann der Event-Monitor vor die Readings verschoben werden. 

attr DOIFtools DOIFtoolsEMbeforeReadings 1
Beispiel: in der Detailansicht geöffneter Event-Monitor

Geöffneter Event-Monitor in der DOIF Detailansicht.

In der linken Ansicht wird der Eventmonitor über den Internals angezeigt, in der rechten Ansicht über den Readings.

Geöffneter Event-Monitor in der DOIF Detailansicht

DOIF-Operanden aus einer Eventzeile erzeugen und in den DEF-Editor einfügen

Wenn im DOIF oder in DOIFtools eine Event-Zeile markiert wird, werden verschiedene DOIF-Operatoren vorgeschlagen, die zeigen, wie das Event in eine DOIF-Definition eingebunden werden kann. In der Eingabezeile des Dialogs kann der Operator angepasst werden. Beim Betätigen des Knopfes Open DEF-Editor wird der Inhalt der Eingabezeile des Dialogs in die Zwischenablage kopiert. Danach wird der DEF-Editor der aktuellen Detailansicht geöffnet. Mit Strg-v wird der Inhalt der Zwischenablage an der Cursor-Position eingefügt.

Beispiel: Verwendungsvorschlag zur Nutzung eines Events als DOIF-Operanden
Event mit Verwendungsvorschlag

DOIF Prüfung und Empfehlungen

DOIFtools kann die DOIF-Definitionen auf besimmte Schreibweisen prüfen und Empfehlungen geben. 

get DOIFtools checkDOIF

Laufende Wait-Timer anzeigen

In manchen Situationen ist es störend, wenn bei einem Neustart ein laufender Wait-Timer abgebrochen wird. Um das bei einem manuellen Neustart zu berücksichtigen, kann man sich die laufenden Wait-Timer anzeigen lassen. Nachrichtlich werden laufende Blocking Calls angezeigt. 

get DOIFtools runningTimerInDOIF

Farbtabellen erzeugen

Mit den folgenden Befehlen lassen sich für einen Wertebereich schrittweise interpolierte Farbnummern und RGB-Werte zu den einzelnen Schrittwerten anzeigen.

Lineare Interpolation

Mit den nachstehenden Befehl wird eine linear interpolierte Reihe von Farbwerten erzeugt. 

get DOIFtools linearColorGradient <start color>,<end color>,<minimal value>,<maximal value>,<step width>

Modellabhängige Interpolation

Mit den nachstehenden Befehl wird eine modellbedingte interpolierte Reihe von Farbwerten erzeugt. 

get DOIFtools modelColorGradient <minimal value>,<middle value>,<maximal value>,<step width>,<color model>

Gültige Werte für color model sind 0, 1, 2 oder ein Array aus fünf RGB-Farbwerten.

Zur Interpolation wird eine Farbskala mit Color::pahColor erzeugt.

Interpolation über HUE

Mit den nachstehenden Befehl wird eine über den HUE-Wert interpolierte Reihe von Farbwerten erzeugt. 

get DOIFtools hsvColorGradient <start HUE>,<end HUE>,<minimal value>,<maximal value>,<step width>,<saturation>,<lightness>

Gültige Werte für HUE von 0-360, für saturation und lightness 0-100.

Zur Interpolation wird eine Farbskala mit Color::hsv2color erzeugt.

Beispiele

get DOIFtools linearColorGradient #0000FF,#FF0000,7,30,1

erzeugt einen linearen Farbübergang von Blau nach Rot.

Linearer Farbgradient
get DOIFtools modelColorGradient 7,20,30,1,0

erzeugt einen modellbedingten einen Farbübergang für das eingebaute Modell 0. 

get DOIFtools modelColorGradient 0,50,100,5,[255,255,0,127,255,0,0,255,0,0,255,255,0,127,255]

erzeugt einen modellbedingten einen Farbübergang für für ein eigenes Modell 0,50,100,5,[255,255,0,127,255,0,0,255,0,0,255,255,0,127,255].

Modellbedingter Farbgradient
get DOIFtools hsvColorGradient 240,360,7,30,1,80,80

erzeugt über den HUE-Wert einen Farbübergang von Blau nach Rot.

Linearer Farbgradient

MODEL Perl: Anzeige benutzerdeklarierter Subs im Package DOIF

Die Funktion dient zum Auffinden von selbstdefinierten Subs. Wenn die Subs in einem Gerät definiert wurden, wird ein Link zu dem Gerät angezeigt. 

get DOIFtools subsInPackageDOIF

Bekannte Probleme/Einschränkungen/Hinweise

Links

Abgerufen von „http://wiki.fhem.de/w/index.php?title=DOIFtools&oldid=33681“