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.

Das eigenen Konzept

Für die Verknüpfung von HM Entities muss man 2 Ebenen unterschieden, Architektur und Verhalten.

Architektur

Beim Erstellen der Architektur legt man fest, welche Entities untereinander verknüpft werden. Dies geschieht durch peeren. Templates unterstützen nicht die Architektur. Es ist demnach notwendig die Peerings durchzuführen bevor an ein Template darauf anwenden kann.

Verhalten

Hier kommen die Templates zum Tragen. Mit Templates definiert man die Register der Entities und somit das Verhalten und die Reaktion der Entites bspw auf Trigger von Sensoren.

Welchen templateTyp brauche ich

Wie in Granularität beschrieben kann man insbesondere beim Peerverhalten templates für short, long oder both ertellen. Nutzt man short/long braucht man weniger Templates (Basics sind on/off/ignore/toggle) muss allerdings mehr Templates zuweisen, als Reaktion auf short UND long.
Bei both braucht man mehr Templates (OnOff/OnIgnore/OffIgnore/IgnoreOff/ToggleIgnore/...) braucht aber nur die Hälfte der Zuweisungen zu den realen Entities.

Welche Parameter muss ich einstellen

Bei der Erstellung eine Templates werden dessen Parameter durch Attribute vorgegeben. Durch set save wird dann das Template schlussendlich definiert. Folgende Parameter/Attribute werden genutzt:

• tpl_description: ist ein Freitext welcher beschreiben soll, was das Template macht und wie es parametriert wird
• tpl_params: hier werden evtl Parameter definiert mit welchen die Instanziierung des Templates angepasst werden kann. Bspw. könnte die Einschaltzeit variable gestalltet werden. Bei einem Dimmer könnt man den Level und die Rampe eingeben, also 2 Parameter. Man vergibt also, ":" getrennt, eine Liste von Paramtern. Die Namen sind frei wählbar.
  

timeOn:ramp würde 2 Parameter definieren, welche später in den Registern genutzt werden können

• tpl_type: definiert den Typ. Diesen muss man zuerst festlegen. Es konnte peer-Short,peer-Long,peer-Both oder basic sein. Nach der Auswahl des Typs kann man die Entity (source) wählen. Es alle Entities angeboten, welche entsprechende Registersätze zu Verfügung stellen.
• tpl_source: legt bei der Definition eines Templates fest, von welcher Entity die Register für die Vorlage genutzt werden sollen. Ein Browser-Refresh könnte notwendig sein um die Auswahlliste upzudaten
• tpl_peer: muss man auswählen, so man einen "peer" typ gewählt hat. An Browser-refresh denken.
• Reg_xxx: An Browser-refresh denken. Hat man nun die Vorlage ausgewählt und den Refresh gemach werden nun Register als Attribute angeboten.
  

Zunächst sollte man Registerattribute löschen, welche man für das Template nicht benötigt. Achtung: eine Option gelöschte Registerattribute wieder nachzutragen ist nicht vorgesehen. So schlimm ist es allerdings nicht - man muss halt noch einmal alle Lesen und von Vorne löschen.

Sinnvoll kann es sein, die Condition Table Register komplett zu eliminieren wenn man Reaktionen auf Taster definieren will. Will man ignore definieren, also keine Reaktion bspw auf long, dann kann man alles löschen bis auf ActionType usw.

Sinnvoll ist es, nur notwendige Register der Funktion zu bearbeiten, da sonst die Anwendung des Templates eingeschränkt wird.

Es sollten aber alle Register der Funktion enthalten sein, da die Prüfung auch nur diese berücksichtigt und bei einem Umprogrammieren nicht klar ist, was vorher in einem Register gestanden ist.

Register Werte setzen

Nun das eigentliche - das setzen der Registerinhalte. Dies wird begrenzt unterstützt. Sollte das Register durch literals definiert werden erscheint beim Setzen eine drop-down Liste mit den Optionen.
Nicht unterstützt wird das Setzen von Werten. Es gibt aktuell keine Option, hier eine Hilfe einzublenden. Die Wertebereiche sind dem regList der Entity zu entnehmen.
Eine weitere Besonderheit ist die Granularität der Werte. Insbesondere durch das Float Format einiger Werte sind nicht alle Werte möglich. Trägt man bspw eine Ontime von 10000 ein wird dies erst einmal akzeptiert. Allerdings wird der Wert beim Schreiben umgerechnet in den nächstmöglichen (welcher 9600 ist). Bei der Prüfung der Template Anwendung wird der Unterschied angemerkt. Am Einfachsten wird nun das Template angepasst und alles ist gut.

Nun tpl_params. Diese muss man anstelle des Registerwerts einsetzen. Hat man bspw
tpl_params timeOn:rampTime
definiert setzt man in das Register OnTime den Wert timeOn ein. Und eben das Rampenregiste den Wert rampTime. Der Wert wird dann beim Template Instanziieren - also Anwenden - durch den Individuellen ersetzt.

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 erstellen und bearbeiten

Templates kann man erstellen, in dem man die Register einer Entity nimmt und bearbeitet. Auch das Kopieren und Bearbeiten eines vorhandenen Templates ist möglich. Und man kann Templates exportieren/importieren.

Template aus Device

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 Varianten speichern

Ist man beim Erstellen von Templates kann man mti saveAs das Template als neues unter einem anderen Namen sichern.

Template editieren

Mit Edit kann man die Werte der Register ändern oder vorhandene Register aus dem Template entfernen. Ein Hinzufügen von Registern wird nicht unterstützt. Hier fehlt die Referenz um anzubieten, was möglich ist.

Template kopieren

Dies wird ebenfalls mit edit erreicht. Das Template wird mit saveAs unter einem neuen Namen gespeichert.

Template export-import

Will man Templates exportieren nutzt man

 get ht <templatename>

Es wird ein kommando ausgegeben welches man in die Kommandozeile pasten kann, was dann der import ist.
Dies kann man nutzen um Templates zu tauschen. Hat man ein gutes oder komplexes Template kann man dies der Allgemeinheit zu Verfügung stellen.
Im besten Fall muss der User sich nicht mehr um Register kümmern, da komfortable Templates das besser abdecken.

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.