HomeMatic Templates

HMtemplate
Zweck / Funktion
templates bedienen und verwalten
Allgemein
Typ	Hilfsmodul
Details
Dokumentation	EN / DE
Support (Forum)	HomeMatic
Modulname	98_HMtemplate.pm
Ersteller	martinp876 (martinp876 / Wiki)
Wichtig: sofern vorhanden, gilt im Zweifel immer die (englische) Beschreibung in der commandref!

Templates sind Vorlagen im Allgemeinen. Hier werden Vorlagen zur Programmierung der Register von HM Devices behandelt.

Warum Templates

Die Frage, warum man Register nicht einfach setzt sondern Templates nutzen sollte kommt immer wieder auf. Schliesslich sind wie alle Spezialisten... Die Wahrheit allerdings bildet das nicht ab. Den auch den Spezialisten sei angeraten, Templates zu nutzen. Ja, warum den, was bieten Templates? Hierzu muss man verstehen wir FHEM, HM, Devices, Kanäle und peers zusammen hängen.

Wie schon im Einsteigerdoc beschrieben hat ein HM Device remanente Register welche von FHEM gesetzt werden können und die Funktions- und Arbeitsweise definieren. FHEM selbst hat bestenfalls eine Kopie dieser Daten.

soll-Register Verwaltung

Da FHEM nur eine Kopie der Registerwerte verwaltet lebt man erst einmal in einer fragilen Welt. Registerwerte können sich ändern durch:

• Reset des Device
• Batteriefehler
• inkorrektes Schreiben und Übertragungsfehler
• Austausch eines Device

Nach Lesen der Device Register hat FHEM einen neue Kopie - dies muss aber nicht den Wunschregistern entsprechen. Templates sind eine Ansammlung von Wunschregister. Somit können unterschiedliche Mechanismen genutzt werden, das System zu verwalten, prüfen und korrigieren.

Funktionen für Einsteiger

Nicht-Experten sollten primär Templates nutzen - um Funktionen zu realisieren, und wenn gewünscht, Experten zu werden. Templares kann man einfach austauschen und dann anwenden.

Verwalten von Funktionen statt Registern

Als Experten kann man sicher die Register zeilsicher setzen. Wirklich? Wenn man sich eine clevere Lösung ausgedacht hat und sie reproduzieren will kann man einfach noch einmal nachdenken, nachlesen,... und schon hat man es wieder. Oder man hat ein Template definiert das man einfach nutzt.

Lernen aus Templates

Templates sind nicht verschlüsselt. Hat oder bekommt man ein Template kann man die dort gesetzten Register einfach einsehen - und wenn man will verstehen was gemacht wurde.

Globales Anpassen aller Devices

Hat man festgestellt, dass eine Funktion sub-optimal ist kann man das Temlate ändern und diese Änderungen allen Devices zu gute kommen lassen. Auf einmal.

Grundsätzliches zum Template

Templates (hier) ist nun also eine Sammlung von Registern welche in einem Device gesetzt werden können.

Template Granularität

Man kann nicht alle Register eines Device in einem Template abbilden. Das wäre technisch komplex und macht auch von der Anwendung her keinen Sinn.

• Aus Sicht der Funktion sollte man Templates nach deren Funktionen zusammenfassen.
• Aus Sicht des Devices sollte man Templates nach der Struktur des Device zusammenstellen.
• Die Implementierung erlaubt es, templates für jedes Register einzeln zu erstellen.
  
• Weniger Templates erhöhen die Übersichtlichkeit

Die technische Lösung legt folgenden Templates nahe

1. Alle Register eines Kanals oder Device - ausgenommen peer abhängige Register
2. Alle Register eines Kanals eines Peers für short oder long
3. Alle Register eines Kanals eines Peers nur für short
4. Alle Register eines Kanals eines Peers nur für long

Ob man 2. oder die Kombination aus 3. und 4. nutzt ist Geschmackssache.
Ein typischer Einsatz sind Schaltern und Dimmer bei welchen man die Aktionen der Peers festlegen will.

usecase Template Granularität Dimmer

Mit Peer1 soll bei short ein und bei long ausgeschaltet werden

Mit Peer2 soll bei short getoggelt und bei long nicht geschaltet werden

Mit Peer3 soll bei short nicht geschaltet und bei long getoggelt werden

Mit Peer4 ist ein MotionDetector welcher bei short und einer bestimmten Helligkeit einschaltet, timed. Allerdings sollen Aktionen der anderen Peers oder der Zentrale das Licht dauer-ein schalten.

Template Flexibilität

Templates sind starr... und können parametriert werden. Also semistarr. Was jetzt? Nun man kann Templates mir bis zu 9 Parametern versehen. Sinnvoll sind wohl eher bis zu 3.
Beispiele sind:

• Treppenhausschaltern - mit einem Parameter kann man Einschaltdauer je Instanziierung festlegen. Sinnvoll könnte eine Treppenhausschaltung generell sein, nicht nur im Treppenhaus. Man kann generell alle Lichter nach ein paar Stunden ausschalten.
• Heizungstemplate - Boosttime: Man kann allen RTs das gleiche Template geben - allerdings kann man z.B. die Boosttime indivituell einstellen.
• MotionDetector Clients: Bei den Peers des Modtion detector (also den Schaltern) stellt man ein, dann diese reagieren sollen und wie lange diese brennen sollen.

Template Verwaltung

Templates werden zusammen mit Registern verwaltet. Man benötigt demnach HMinfo. Sowohl die Template definition alsauch die Template Zuweisung werden im File zusammen mit den gelesenen Registern gesichert. Nach einem Einlesen dieses Files werden auch die Templates und deren Zuordnung neu erstellt.

Template Editieren

Die aktuell einfachste Möglichkeit ein Template zu modifizieren ist, HMtemplate zu nutzen. HMtemplate ist ein Editor. Für den Betrieb wird es nicht genutzt.

Getting started

Was muss man also tun? Wenn man noch nichts eingerichtet hat:

 define hm HMinfo
 attr hm autoArchive 1
 attr hm autoLoadArchive 1_load
 attr hm configFilename regConfig.cfg
 define ht HMtemplate

Template aus Device erstellen

Aufgabe ist es, aus einem existierenden Device ein Template zu erstellen. Wir haben device myDev Channel myChan Channel gepeert mit myChanPeer.
Der Kanal ist ein Schalter und wir wollen einen Parameter im Template nutzen: Die Anschaltzeit soll bei der Nutzung des Templates variabel eingesetzt werden. Wir werden also den Parameter timeOn nutzen. Das Template soll my1stTmpl genannt werden. Weiter soll das gesamte Verhalten des myChanPeer definiert werden, also short UND long.

 set ht define my1stTmpl
 attr ht tpl_param timeOn # name des Parameters - hier nur einer
 attr ht tpl_description "mein erstes Template"
 attr ht tpl_type peer-both
 <refresh browser>    # select liste der attribute wird neu eingelesen
 attr ht tpl_source myChan
 <refresh browser>    # select liste der attribute wird neu eingelesen
 attr ht tpl_peer myChanPeer
 <refresh browser>    # select liste der attribute wird neu eingelesen
 attr ht Reg_shOnTime timeOn # setzen des parameters

nun können weitere Register verändert werde. Sinnvoll ist es, unnötige Register aus dem Template zu entfernen. Dies sind in diesem Fall bspw. alle Ct register. Das Attribut des Registers wird einfach gelöscht.

 set ht save
 set ht dismiss

Template einem Kanal zuweisen

Jetzt haben wir ein Template welches long und short eines Kanals kontrollieren soll. Dies wollen wir jetzt anwenden auf unsere Kanal/Peer Kompinationen "sw1/peer1", "sw1/peer2", "sw2/peer1" und "sw2/peer3". Für alle benötigen wir unterschiedliche Abschaltzeiten (warum? eure Sache).

 set ht select my1stTmpl
 attr ht entity sw1
 <refresh browser>
 attr ht ePeer peer1
 attr ht tpl_param_timeOn 30
 set ht apply
 attr ht ePeer peer2
 attr ht tpl_param_timeOn 180
 set ht apply

 attr ht entity sw2
 <refresh browser>
 attr ht ePeer peer1
 attr ht tpl_param_timeOn 70
 set ht apply

 attr ht ePeer peer3
 attr ht tpl_param_timeOn 1000
 set ht apply

 set ht dismiss

Die Register der Entities werden passend in das Device geschrieben.

Template editieren

Nun soll das Template grundsätzlich modfiziert werden.

 set ht edit my1stTmpl
 attr ht Reg_<name> <value>
 attr ht Reg_<name2> <value2>
 attr ht Reg_<name3> <value3>
 set ht save

Template kopieren und editieren

Nun soll das Template grundsätzlich modfiziert werden.

 set ht select my1stTmpl
 attr ht Reg_<name> <value>
 attr ht Reg_<name2> <value2>
 attr ht Reg_<name3> <value3>
 set ht saveAs my2ndTmpl

Template weitergeben

Will man Templates weitergeben geht das mit

 get ht my1stTmpl

Das Kommando kann dann direkt in die Kommandozeile kopiert werden und das Template ist definiert.