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

Templates sind ein Weg, die Register der HM RF Devices zu setzen, zu kontrollieren und zu replizieren. Warum braucht man nun Templates? Register lassen sich doch einfach ohne Templates setzen. Warum sich damit befassen? Nun, die Gründe sind vielfältig - und eigentlich unabdingbar für alle, die ein geordnetes System verwalten wollen.

Register ohne Template - Schwachstellen

Register werden, wie bekannt, remanent in den HM-Devices gespeichert (also im Flash-Speicher). FHEM hat eine Kopie dieser Daten welche über getConfig aufgefrischt werden können. Setzt man nun in einem Device ein Register ist dies erst einmal erledigt. Nun kann sich das Register verändern bzw muss überprüft werden, wenn

• das Device ausgetauscht wird
• das Device reseted wird - kommt auch einmal vor
• ein FW bug oder ein HW Defekt vorliegt
• das Schreiben der Registerwerte nicht erfolgreich war

Weiter ist es praktisch die gewünschten Settings, also das eingestellte Verhalten

• zu verifizieren
• zu kopieren

ohne sich einzelne Registerzu merken oder wieder herzuleiten.

Anzumerken ist, dass die Nutzung von Templates das Bedienen der Register nicht abschaltet oder übersteuert sondern nur ergänzt.

Templates heben das Bedienen der Register von der Assembler-Ebene auf eine Hochsprachen-Ebene. Nicht ohne Grund erfolgt die erste Bedienung der Register in der eq3-CCU über einen ähnlichen Mechanismus. Register werden nur im Expert mode sichtbar.

Was bieten Templates

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 Ist-Registerwerte verwaltet, lebt man erst grundsätzlich in einer fragilen Welt. Eine Soll-Wert Verwaltung der Register erfolgt nur bei Verwendung von Templates.

Funktionen für Einsteiger

Nicht-Experten sollten primär Templates nutzen - um Funktionen zu realisieren. Der Anwender holt sich ein Template und kopiert es in sein System. Nun kann er

• die Funktion nutzen. Es muss die Register nicht verstehen
• Die Funktion nutzen, testen und die Register evaluieren und daran zu lernen
• Die Funktion erweitern, modifizieren und an seine Bedürfnisse anpassen

Verwalten von Funktionen statt Registern

Als Experten kann man evtl. 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 und repliziert.

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 Template ändern und diese Änderungen allen Devices zu Gute kommen lassen. Auf einmal.

Funktionen parametrieren

Der Anwender hat typisch den Wunsch, eine Funktion zu relaisieren, aber einen Parameter will er bei jeder Anwendung anpassen. So will ich typischerweise, dass nach einem ON-Trigger immer eine automatische Abschaltung eingestellt wird, was das Vergessen des Ausschaltes verhindern soll. Die Anschaltzeit ist aber im Wohnzimmer eher 6h, im Treppenhaus aber 2h und bei einem Bewegungsmelder 10min.

Hier kann man nun immer das gleiche Template nutzen. Die Abschaltzeit wird separat eingestellt und ist per Kommando modifizierbar. Weiter ist sie in den Readings sichtbar.

Anwendungsbeispiel Lichtschalter

Grundsätzlich sind Lichtschalter erst einmal einfach: An/Aus Was kann man schon "templaten"?

Ich habe diverse Lichter und einige zugehörige Schalter. Da meine Fernbedienungen nur eine endliche Anzahl Knöpfe haben muss ich mir ein Konzept überlegen. Nutzen kann ich bei einem Wippschalter 2 Buttons (Knöpfe) und unterscheide bei jedem langer oder kurzer Druck. Bei Schaltern benötige ich demnach Templates für On, Off, Toggle. Nun kann ich jeder Paarung Aktor/Sensor und hier Long/Short eine Funktion zuweisen.

Nun nutze ich Buttons um bei pressLong das Licht 1 zu toggeln, bei PressShort toggelt es Licht 2.

Was programmiert ist kann man in HmInfo ermitteln über

• get hm peerUsg

Wie das erstellt wird, wird weiter unten erklärt

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 folgende 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 Schalter und Dimmer bei denen 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 Motiondetector (also den Schaltern) stellt man ein, wann diese reagieren sollen und wie lange diese brennen sollen.

Template Verwaltung

Templates werden zusammen mit Registern verwaltet. Man benötigt demnach HMinfo. Sowohl die Templatedefinition als auch die Templatezuweisung 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 eigene 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 vorhandener Programmierung erstellen

Aufgabe ist es, aus einem existierenden, programmierten 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 um die Anschaltzeit variabel zu steuern. 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

bei Bedarf können weitere Register verändert werde.
Nun sind wir fertig. Möglich, aber nicht notwendig 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.

Verwaltung und Überblick

Nun hat man Templates definiert und Instanziiert. Wie soll man den Überblick behalten? HMtemplate ist ein Editor - also nicht wirklich hierfür geeignet. HMinfo macht die Verwaltung.

Template Überblick

Will man sehen, was man so an Templates nutzt kann man eine Überscht unterschedliche sortiert ausgeben lassen - in HMinfo (hm).

 get hm templateUsgG sortTemplate
 get hm templateUsgG sortPeer
 get hm templateUsgG all

Sowie eine Liste von Registerlisten, welche noch kein Template nutzen (noch in Bau!!)

 get hm templateUsgG noTmpl

Eine Liste der Verfügbaren Templates erhält man mit

 get hm templateList all

und die Register eines Templates mit

 get hm templateList <templateName>
 oder
 set ht select  <templateName>

Template prüfen

Templates werden auf korrekte Implementierung in der Entity anhand eines Vergleichs der gelesenen Registern mit den gewünschten Regitern geprüft. Es ist also notwendig, dass die Registerwerte in der FHEM Kopie aktuell sind. Dann reicht ein

 get hm configCheck

Sollte es zu Unstimmigkeiten kommen werden mit

 set hm templateExe

alle Unstimmigkeiten überschrieben. Klar, wie immer, muss FHEM warten, bis ein Device angesprochen werden kann (Übertragungsmode) und dass die IOs nicht überlastet werden. Die Gefahr einer Überlast ist gering wenn man nicht gleich alles überschreiben will.
Wie immer ist es hilfreich den Status der Übertragung im Blick zu haben:

 get hm protoEvents

Wenn zu viel passiert ist und man protoEvents aufräumen muss dann (Achtung: es werden alle ausstehenden Kommandos gelöscht und müssen neu aktiviert werden!)

 set hm clearG msgEvents

Template löschen

 set ht delete <tempateName>

Achtung: vorher müssen alle Referenzen des Templates entfernt worden sein.

Templates in den Entites

Ist eine Entity mit einem Template verknüpft wird dies in den Readings angezeigt. Dies kann man sichtbar machen - und eine Anzeige von Registern in den Readings sollte dann nicht mehr notwendig sein. Empfohlen wird, den expoer mode auf rein Templates umzustellen

 attr TYPE=CUL_HM:FILTER=DEF=......:FILTER=subType!=virtual expert 12_templOnly
 deleteattr TYPE=CUL_HM:FILTER=DEF=........    expert
 deleteattr TYPE=CUL_HM:FILTER=subType=virtual expert

Beispiele und Ideen

Neben den typischen Templates für Schalter kann (sollte) man auch bspw für RTs einsetzen. Temperaturlisten sind nicht im Angebot. Hier gibt es bereits andere Verfahren, die besser passen. Allerdings experimentiere ich bei meinen RTs mit den Regelparametern und will diese dann generell setzen. Alle RTs (bei mir) sollen die gleiche Regelung haben. Ich nutze 3 Templates für meine RTs

• HeatDefDev: Das Device des RT wird auf Standartwerte gesetzt. Hier nutze ich einen Parameter um die Tasten zu sperren. Dies brauche ich nicht bei allen RTs sondern nur bei denen, welche ich mit einem TC gepeert habe. Hier ist eine Lokale Änderung am TC vorzunehmen.
• HeatDefault:Die Standart-Regelung. Auch hier habe ich Parameter vorgesehen. Die Devices sind identisch... bis auf die Boostzeit und die maximals Ventilöffnung. Je nach Hk begrenze ich ValveMax - hängt von den baulichen Gegebenheiten ab. Boost nutze ich im Bad zum Entfeuchten.
• HeatRemote: mein guteNacht Knopf macht auch vor RTs nicht halt. Ich habe an einer Fernbedienung einen Button mit allen Lichtern und RTs im Wohnbereich gekoppelt. Beim Drücken wird das Licht abgeschaltet und die Heizung gedrosselt - z.B., wenn ich als letzter ins Bett gehe. Daher brauche ich einen Parameter Temperatur um das individuell je RT einzustellen.

 set hm templateDef HeatDefDev BtnLock "Default RT Device register" globalBtnLock:off localResDis:off modusBtnLock:off backOnTime:10 cyclicInfoMsg:on lowBatLimitRT:2.1 burstRx:on cyclicInfoMsgDis:0 btnLock:p0
 set hm templateDef HeatDefault boost:valveMax "myDefault RT settings, enter boostTime and valveMax" regAdaptive:offDeter reguIntI:20 nightTemp:17 tempOffset:0.0K dayTemp:21 reguIntPstart:5 reguExtI:20 showWeekday:off reguExtP:25 reguIntP:25 tempMax:30.5 tempMin:4.5 valveMaxPos:p1 valveOffsetRt:0 modePrioManu:all daylightSaveTime:on boostPos:30 decalcWeekday:Sat showInfo:time decalcTime:11:00 btnNoBckLight:off reguExtPstart:5 noMinMax4Manu:off modePrioParty:all valveErrPos:15 boostPeriod:p0
 set hm templateDef HeatRemote temp "heatRemote set temperature" CtrlRc:autoAndTemp TempRC:p0

In der Übersicht für 2 RTs ergibt ein get hm templateUsg

 haEss               |0              |HeatDefDev|BtnLock:off 
 haEss_Clima         |0              |HeatDefault|boost:5 valveMax:15 
 haEss_remote        |FB8_1:short    |HeatRemote|temp:13 
 haEss_remote        |FB8_5:long     |HeatRemote|temp:13 
 haEss_remote        |FB8_5:short    |HeatRemote|temp:19 
 haLnge              |0              |HeatDefDev|BtnLock:off 
 haLnge_Clima        |0              |HeatDefault|boost:5 valveMax:15 
 haLnge_remote       |FB8_1:short    |HeatRemote|temp:13 
 haLnge_remote       |FB8_5:long     |HeatRemote|temp:13 
 haLnge_remote       |FB8_5:short    |HeatRemote|temp:19