AttrTemplate

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.

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

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.