AttrTemplate: Unterschied zwischen den Versionen
Maista (Diskussion | Beiträge) K (Tippfehler) |
|||
(18 dazwischenliegende Versionen von 4 Benutzern werden nicht angezeigt) | |||
Zeile 15: | Zeile 15: | ||
==Einführung== | ==Einführung== | ||
Ziel von ''attrTemplate'' ist es, den Nutzer bei der Konfiguration von Geräten zu unterstützen, indem vorrangig entsprechende [[Attribute]] gesetzt werden. Grundsätzlich ist es jedoch auch möglich, beliebige FHEM-Befehle oder Perl-Code im Rahmen von attrTemplate auszulösen. | Ziel von ''attrTemplate'' ist es, den Nutzer bei der Konfiguration von Geräten zu unterstützen, indem vorrangig entsprechende [[Attribute]] gesetzt werden. Grundsätzlich ist es jedoch auch möglich, beliebige FHEM-Befehle oder Perl-Code im Rahmen von attrTemplate auszulösen. | ||
Teilt man entsprechende ''templates'', sollte jedoch deutlich darauf hingewiesen werden, wenn ein | Teilt man entsprechende ''templates'', sollte jedoch deutlich darauf hingewiesen werden, wenn ein Template etwas anderes tut als nur Attribute zu setzen, also insbesondere dauerhafte Konfigurationsänderungen in der Hardware selbst vorzunehmen. | ||
Um Ihnen die Auswahl zu erleichtern, kann | Um Ihnen die Auswahl zu erleichtern, kann | ||
* mit <code>set <Device-Name> attrTemplate ?</code> eine Liste der vorhandenen Templates samt kurzer Beschreibung aufgerufen werden. | * mit <code>set <Device-Name> attrTemplate ?</code> eine Liste der vorhandenen Templates samt kurzer Beschreibung aufgerufen werden. | ||
* in der Detailansicht der Geräte über das Dropdownfeld ein ''template'' ausgewählt werden | * in der Detailansicht der Geräte über das Dropdownfeld ein ''template'' ausgewählt werden. Nun erhält man unmittelbar unter dem ''set''-Befehl ebenfalls entsprechende weitere Informationen sowie den Code des ''template'' angezeigt, der bei Drücken auf ''set'' ausgeführt wird. | ||
Hat man ein passendes ''template'' gefunden, wird mit <code>set <Device-Name> attrTemplate <template_name></code> angewendet, wodurch die entsprechenden, in dem ''template'' hinterlegten Kommandos ausgeführt werden. | Hat man ein passendes ''template'' gefunden, wird mit <code>set <Device-Name> attrTemplate <template_name></code> angewendet, wodurch die entsprechenden, in dem ''template'' hinterlegten Kommandos ausgeführt werden. | ||
{{Hinweis|Vor allem, wenn man ''attrTemplate'' für die Konfiguration von [[MQTT2_DEVICE]] verwendet, sollte man die '''default'''-Einstellungen für die Topic-Strukturen etc. nicht am Gerät ändern, da andernfalls die Automatismen ggf. nicht greifen und z.B. passende attrTemplate für das Device gar nicht angezeigt werden.}} | |||
== Syntax == | == Syntax == | ||
{{Link2Forum|Topic=104804|Message=988100|LinkText=Hier}} hat Rudolf König die Syntax erläutert, die in den attrTemplate-Dateien verwendet werden | {{Link2Forum|Topic=104804|Message=988100|LinkText=Hier}} und {{Link2Forum|Topic=99195|Message=925952|LinkText=hier}} hat Rudolf König die Syntax erläutert, die in den attrTemplate-Dateien verwendet werden können: | ||
* leere Zeilen werden ignoriert | * leere Zeilen werden ignoriert | ||
* Zeilen die mit # anfangen sind Kommentare (s.u. ''desc:'') | * Zeilen die mit # anfangen sind Kommentare (s.u. ''desc:'') | ||
* Zeilen, die mit einem der folgenden Schlüsselwörter beginnen, werden speziell interpretiert: ''name: filter: prereq: par: desc: farewell: order:'' | * Zeilen, die mit einem der folgenden Schlüsselwörter beginnen, werden speziell interpretiert: ''name: filter: prereq: option: par: desc: farewell: order:'' | ||
** '''name:''' Name des Templates, markiert gleichzeitig das Ende des vorherigen Templates | ** '''name:''' Name des Templates, markiert gleichzeitig das Ende des vorherigen Templates | ||
** '''filter:''' devspec2array Ausdruck, der beschreibt, für welche Geräte dieses Template anwendbar ist. Wird erst beim "set ?" ausgeführt. | ** '''filter:''' devspec2array Ausdruck, der beschreibt, für welche Geräte dieses Template anwendbar ist. Wird erst beim "set ?" ausgeführt. | ||
** '''prereq:''' ist entweder ein Perl-Ausdruck {}, oder ein ''devspec2array'', was genau ein Gerät spezifiziert. | ** '''prereq:''' ist entweder ein Perl-Ausdruck {}, oder ein ''devspec2array'', was genau ein Gerät spezifiziert. Falls mindestens ein prereq existiert, was nicht zutrifft, wird das betroffene Template aus dem Speicher entfernt. Die Auswertung erfolgt beim FHEM Start oder bei {AttrTemplate_Initialize()} | ||
** '''par:''' kann mehrfach vorkommen, Syntax: <code>par:< | ** '''option:''' Syntax entspricht prereq, wird jedoch beim Einlesen des template Files ausgeführt. Falls nicht wahr ist, werden die darauffolgenden Zeilen des Template nicht ausgeführt. Ist für sowas wie "setze zusätzlich Attribut XY falls die Installation HomeAssistant kennt" gedacht. | ||
** '''par:''' kann mehrfach vorkommen, Syntax: <code>par:<ParameterName>;<Kommentar>;<Perl-Code></code>. ''Perl-Code'' versucht den Wert zu finden, falls nicht möglich (''return undef''), wird ein Dialog mit "Replace" angezeigt (bzw. Usage:... im telnet). ''ParameterName'' wird in jeder Befehlzeile ersetzt mit dem Wert. Zusätzlich: ''DEVICE'' wird mit dem Namen des Gerätes ersetzt, wird ''DEVICE'' (z.B. für Modulnamen) als Text benötigt, muß es ''escaped'' werden (z.B. MQTT2_\DEVICE). | |||
** '''pardefault:''' Wie '''par:''', allerdings wird ein ggf. ermittelter Wert nicht automatisch übernommen, sondern als Vorgabe in einem Dialogfeld zur Bestätigung (bzw. Änderung) durch den User angezeigt. | |||
** '''desc:''' Kommentar fuer <code>set attrTemplate help ?</code>. Die letzte Zeile mit # vor ''name:'' wird als ''desc:'' interpretiert, falls kein ''desc:'' vorhanden ist. | ** '''desc:''' Kommentar fuer <code>set attrTemplate help ?</code>. Die letzte Zeile mit # vor ''name:'' wird als ''desc:'' interpretiert, falls kein ''desc:'' vorhanden ist. | ||
** '''farewell:''' wird zum Schluss als Dialog (oder Text in telnet) angezeigt, falls beim Anwenden der Befehle kein Fehler aufgetreten ist. | ** '''farewell:''' wird zum Schluss als Dialog (oder Text in telnet) angezeigt, falls beim Anwenden der Befehle kein Fehler aufgetreten ist. | ||
** '''order:''' bestimmt die Reihenfolge, in der die Templates im [[FHEMWEB|Webfrontend]] angezeigt werden; falls nicht vorhanden, wird ''name:'' genommen. | ** '''order:''' bestimmt die Reihenfolge, in der die Templates im [[FHEMWEB|Webfrontend]] angezeigt werden; falls nicht vorhanden, wird ''name:'' genommen. | ||
** '''loop:''' ermöglicht es, die zwischen ''loop:<parameter-name>:<wert1>:<wert2>:....'' und ''loop:END'' stehenden Zeilen wiederholt auszuführen und dabei bei jedem Durchlauf die als ''<parameter-name>'' bezeichnete Variable durch die darauffolgende Werteliste (getrennt per Doppelpunkt) zu ersetzen. | |||
* alle anderen Zeilen werden als auszuführende Befehle interpretiert, wenn man <code>set <Device-Name> attrTemplate TemplateName</code> ausführt. | * alle anderen Zeilen werden als auszuführende Befehle interpretiert, wenn man <code>set <Device-Name> attrTemplate TemplateName</code> ausführt. | ||
==Eigene | ==Eigene Templates entwickeln== | ||
Wer plant, mehrere gleichartige Geräte anzulegen, aber andere Einstellungen zu wählen, als sie in den vorhandenen | Wer plant, mehrere gleichartige Geräte anzulegen, aber andere Einstellungen zu wählen, als sie in den vorhandenen Templates enthalten sind, kann hierfür ebenfalls die attrTemplate-Funktion mit eigenen Templates nutzen. Hierfür können die vorhandenen Templates der im Unterverzeichnis ''fhem/FHEM/lib/AttrTemplate'' zu findenden Dateien als Basis dienen. Ihre Templates speichern Sie einfach als neue Datei mit der Endung ''.template'' im selben Verzeichnis (auf Linux-konforme Zeilenumbrüche achten) und lesen diese mit <code>{ AttrTemplate_Initialize() }</code> neu ein. Danach können Sie diese direkt verwenden. | ||
Haben Sie ein Template erstellt und möchten dieses teilen, erstellen Sie einfach einen Beitrag im entsprechenden Forenbereichen, für manche Module existieren auch spezielle Threads (siehe Linkliste unten) | |||
=== Sprachsteuerung === | |||
Zur Einbindung von Sprachsteuerungslösungen ([[Siri|Siri,]] [[Alexa]] und [[Google Assistant FHEM Connect|gassistant]]) gibt es eine Reihe zentraler attrTemplates, die meist direkt aus anderen attrTemplates heraus aufgerufen werden. Es ist auch möglich, diese attrTemplate direkt aufzurufen, z.B. wenn man erst später eine Spracherkennungslösung eingebunden hat. Wegen der Namen der templates sollte man dazu direkt die betreffende attrTemplate-file ''[https://svn.fhem.de/trac/browser/trunk/fhem/FHEM/lib/AttrTemplate/speechrecogn.template speechrecogn.template]'' konsultieren, die Beschreibung, welches template für welche Funktionalität gedacht ist sowie eventuelle Parameter sind jeweils hinter dem ''desc:'' zu finden. | |||
=== Spezielle Fragen zur Entwicklung neuer Templates === | |||
* Ersetzungen von Schlüsselbegriffen, die durch den AttrTemplate-Code aufgelöst bzw. durch entsprechende andere Werte ersetzt werden, (insbesondere von ''DEVICE'') kann man verhindern, indem man diese ''escaped''. Beispiel: Um im Ergebnis ein "MQTT2_DEVICE" zu erzielen, muß "MQTT2_\DEVICE" geschrieben werden. | |||
==Warum finde ich das Template xyz nicht?== | |||
In den dropdown-Auswahllisten entsprechender Geräte werden teils deutlich weniger Möglichkeiten angeboten, als in den attrTemplate-files aufgeführt sind. Gesteuert wird dies durch die bereits oben genannten Ausdrücke ''filter'' und ''prereq'': | |||
=== filter === | |||
''filter'' bewirkt, dass das template schlicht nicht in der Auswahlliste erscheint, aber an sich geladen ist und über die Kommandozeile auch angewendet werden kann. Allerdings müssen Sie in diesen Fällen damit rechnen, dass mindestens einzelne Elemente zur Ausführung des template-Code nicht vorhanden sind, und Sie diese Parameter über ein Dialogfeld eingeben müssen. | |||
Geladene attrTemplate werden angezeigt, wenn man | |||
:<code>set <device> attrTemplate ?</code> | |||
ausführt. | |||
In der Regel ist es zu empfehlen, die in filter abgefragten Daten händisch einzupflegen, also z.B. bei einem Tasmota-MQTT2_DEVICE wenigstens das "LWT"-readingsList-Element anzugeben. | |||
=== prereq === | |||
Trifft ein ''prereq'' nicht zu, wird das betreffende Template gar nicht geladen. Es erscheint dann weder bei Aufruf des "?", noch kann es über die Kommandozeile ausgeführt werden. In der Regel macht es auch wenig Sinn, ein template ausführen zu wollen, dessen Voraussetzungen nicht gegeben sind, etwa weil (noch) kein passendes Bridge-Gerät definiert ist. | |||
=== Deaktivierung über ''global'' === | |||
Darüber hinaus kann das Modul insgesamt über folgende Einstellung deaktiviert werden: | |||
<syntaxhighlight lang="perl"> | |||
attr global disableFeatures attrTemplate | |||
</syntaxhighlight> | |||
Dann werden insgesamt keine attrTemplates mehr geladen. | |||
==Links== | ==Links== |
Aktuelle Version vom 26. Juni 2024, 15:56 Uhr
AttrTemplate | |
---|---|
Zweck / Funktion | |
Hilfsmodul bzw. Befehl, das/der die Einrichtung von Geräten erleichtern kann | |
Allgemein | |
Typ | Befehl |
Details | |
Dokumentation | EN / DE |
Support (Forum) | Automatisierung |
Modulname | AttrTemplate.pm |
Ersteller | rudolfkoenig (Forum / Wiki) |
Wichtig: sofern vorhanden, gilt im Zweifel immer die (englische) Beschreibung in der commandref! |
AttrTemplate ist ein Hilfsmodul, mit dessen Hilfe Geräte auf einfache Weise mit einer passenden Konfiguration versehen lassen.
Das Modul AttrTemplate ist indirekt Bestandteil der SetExtensions, das Modul kann von Modulautoren aber auch ohne diese mit in beliebige (Geräte-) Module mit eingebaut werden. Über diesen Mechanismus ist der Befehl attrTemplate in einer Vielzahl von Modulen verfügbar.
Einführung
Ziel von attrTemplate ist es, den Nutzer bei der Konfiguration von Geräten zu unterstützen, indem vorrangig entsprechende Attribute gesetzt werden. Grundsätzlich ist es jedoch auch möglich, beliebige FHEM-Befehle oder Perl-Code im Rahmen von attrTemplate auszulösen. Teilt man entsprechende templates, sollte jedoch deutlich darauf hingewiesen werden, wenn ein Template etwas anderes tut als nur Attribute zu setzen, also insbesondere dauerhafte Konfigurationsänderungen in der Hardware selbst vorzunehmen.
Um Ihnen die Auswahl zu erleichtern, kann
- mit
set <Device-Name> attrTemplate ?
eine Liste der vorhandenen Templates samt kurzer Beschreibung aufgerufen werden. - in der Detailansicht der Geräte über das Dropdownfeld ein template ausgewählt werden. Nun erhält man unmittelbar unter dem set-Befehl ebenfalls entsprechende weitere Informationen sowie den Code des template angezeigt, der bei Drücken auf set ausgeführt wird.
Hat man ein passendes template gefunden, wird mit set <Device-Name> attrTemplate <template_name>
angewendet, wodurch die entsprechenden, in dem template hinterlegten Kommandos ausgeführt werden.
![Info blue.png](/w/images/thumb/7/7e/Info_blue.png/40px-Info_blue.png)
Syntax
Hier und hier hat Rudolf König die Syntax erläutert, die in den attrTemplate-Dateien verwendet werden können:
- leere Zeilen werden ignoriert
- Zeilen die mit # anfangen sind Kommentare (s.u. desc:)
- Zeilen, die mit einem der folgenden Schlüsselwörter beginnen, werden speziell interpretiert: name: filter: prereq: option: par: desc: farewell: order:
- name: Name des Templates, markiert gleichzeitig das Ende des vorherigen Templates
- filter: devspec2array Ausdruck, der beschreibt, für welche Geräte dieses Template anwendbar ist. Wird erst beim "set ?" ausgeführt.
- prereq: ist entweder ein Perl-Ausdruck {}, oder ein devspec2array, was genau ein Gerät spezifiziert. Falls mindestens ein prereq existiert, was nicht zutrifft, wird das betroffene Template aus dem Speicher entfernt. Die Auswertung erfolgt beim FHEM Start oder bei {AttrTemplate_Initialize()}
- option: Syntax entspricht prereq, wird jedoch beim Einlesen des template Files ausgeführt. Falls nicht wahr ist, werden die darauffolgenden Zeilen des Template nicht ausgeführt. Ist für sowas wie "setze zusätzlich Attribut XY falls die Installation HomeAssistant kennt" gedacht.
- par: kann mehrfach vorkommen, Syntax:
par:<ParameterName>;<Kommentar>;<Perl-Code>
. Perl-Code versucht den Wert zu finden, falls nicht möglich (return undef), wird ein Dialog mit "Replace" angezeigt (bzw. Usage:... im telnet). ParameterName wird in jeder Befehlzeile ersetzt mit dem Wert. Zusätzlich: DEVICE wird mit dem Namen des Gerätes ersetzt, wird DEVICE (z.B. für Modulnamen) als Text benötigt, muß es escaped werden (z.B. MQTT2_\DEVICE). - pardefault: Wie par:, allerdings wird ein ggf. ermittelter Wert nicht automatisch übernommen, sondern als Vorgabe in einem Dialogfeld zur Bestätigung (bzw. Änderung) durch den User angezeigt.
- desc: Kommentar fuer
set attrTemplate help ?
. Die letzte Zeile mit # vor name: wird als desc: interpretiert, falls kein desc: vorhanden ist. - farewell: wird zum Schluss als Dialog (oder Text in telnet) angezeigt, falls beim Anwenden der Befehle kein Fehler aufgetreten ist.
- order: bestimmt die Reihenfolge, in der die Templates im Webfrontend angezeigt werden; falls nicht vorhanden, wird name: genommen.
- loop: ermöglicht es, die zwischen loop:<parameter-name>:<wert1>:<wert2>:.... und loop:END stehenden Zeilen wiederholt auszuführen und dabei bei jedem Durchlauf die als <parameter-name> bezeichnete Variable durch die darauffolgende Werteliste (getrennt per Doppelpunkt) zu ersetzen.
- alle anderen Zeilen werden als auszuführende Befehle interpretiert, wenn man
set <Device-Name> attrTemplate TemplateName
ausführt.
Eigene Templates entwickeln
Wer plant, mehrere gleichartige Geräte anzulegen, aber andere Einstellungen zu wählen, als sie in den vorhandenen Templates enthalten sind, kann hierfür ebenfalls die attrTemplate-Funktion mit eigenen Templates nutzen. Hierfür können die vorhandenen Templates der im Unterverzeichnis fhem/FHEM/lib/AttrTemplate zu findenden Dateien als Basis dienen. Ihre Templates speichern Sie einfach als neue Datei mit der Endung .template im selben Verzeichnis (auf Linux-konforme Zeilenumbrüche achten) und lesen diese mit { AttrTemplate_Initialize() }
neu ein. Danach können Sie diese direkt verwenden.
Haben Sie ein Template erstellt und möchten dieses teilen, erstellen Sie einfach einen Beitrag im entsprechenden Forenbereichen, für manche Module existieren auch spezielle Threads (siehe Linkliste unten)
Sprachsteuerung
Zur Einbindung von Sprachsteuerungslösungen (Siri, Alexa und gassistant) gibt es eine Reihe zentraler attrTemplates, die meist direkt aus anderen attrTemplates heraus aufgerufen werden. Es ist auch möglich, diese attrTemplate direkt aufzurufen, z.B. wenn man erst später eine Spracherkennungslösung eingebunden hat. Wegen der Namen der templates sollte man dazu direkt die betreffende attrTemplate-file speechrecogn.template konsultieren, die Beschreibung, welches template für welche Funktionalität gedacht ist sowie eventuelle Parameter sind jeweils hinter dem desc: zu finden.
Spezielle Fragen zur Entwicklung neuer Templates
- Ersetzungen von Schlüsselbegriffen, die durch den AttrTemplate-Code aufgelöst bzw. durch entsprechende andere Werte ersetzt werden, (insbesondere von DEVICE) kann man verhindern, indem man diese escaped. Beispiel: Um im Ergebnis ein "MQTT2_DEVICE" zu erzielen, muß "MQTT2_\DEVICE" geschrieben werden.
Warum finde ich das Template xyz nicht?
In den dropdown-Auswahllisten entsprechender Geräte werden teils deutlich weniger Möglichkeiten angeboten, als in den attrTemplate-files aufgeführt sind. Gesteuert wird dies durch die bereits oben genannten Ausdrücke filter und prereq:
filter
filter bewirkt, dass das template schlicht nicht in der Auswahlliste erscheint, aber an sich geladen ist und über die Kommandozeile auch angewendet werden kann. Allerdings müssen Sie in diesen Fällen damit rechnen, dass mindestens einzelne Elemente zur Ausführung des template-Code nicht vorhanden sind, und Sie diese Parameter über ein Dialogfeld eingeben müssen.
Geladene attrTemplate werden angezeigt, wenn man
set <device> attrTemplate ?
ausführt.
In der Regel ist es zu empfehlen, die in filter abgefragten Daten händisch einzupflegen, also z.B. bei einem Tasmota-MQTT2_DEVICE wenigstens das "LWT"-readingsList-Element anzugeben.
prereq
Trifft ein prereq nicht zu, wird das betreffende Template gar nicht geladen. Es erscheint dann weder bei Aufruf des "?", noch kann es über die Kommandozeile ausgeführt werden. In der Regel macht es auch wenig Sinn, ein template ausführen zu wollen, dessen Voraussetzungen nicht gegeben sind, etwa weil (noch) kein passendes Bridge-Gerät definiert ist.
Deaktivierung über global
Darüber hinaus kann das Modul insgesamt über folgende Einstellung deaktiviert werden:
attr global disableFeatures attrTemplate
Dann werden insgesamt keine attrTemplates mehr geladen.
Links
- Ankündigung des Moduls im Forum
- Wiki zu attrTemplate und MQTT2_DEVICE - enthält auch Links zu speziellen Threads für bestimmte Device-Typen
- Thread für getestete Vorschläge (MQTT2_DEVICE).
- Thread für Fragen und Anregungen (MQTT2_DEVICE).
- Thread für HTTPMOD.