mqtt2.template: Contributing

[Beta-User]

Hallo zusammen!

Vorab: Dieser Thread betrifft (bislang) ausschließlich MQTT2_DEVICE, nicht MQTT_DEVICE. Beachte dazu z.B. diesen Wiki-Beitrag.

Bitte nutzt möglichst diesen Thread, wenn ihr neue (im Prinzip ausentwickelte) templates für mqtt2.template vorschlagen wollt.
Für Fehlermeldungen, Diskussionen zu Verbesserungsvorschlägen zu vorhandenen und zum Anfragen von support für neue Devices ist ein weiterer Thread gedacht, dieser hier sollte möglichst übersichtlich bleiben und sich auf das Wesentliche beschränken.

Generelle Anmerkungen zur attrTemplate-Funktion bitte hier posten.

Folgende Wünsche hätte ich:

Parameter verwenden
Ein template unterscheidet sich von einem list insbesondere dadurch, dass es ggf. benötigte Parameter aus den vorhandenen Informationen extrahiert, so dass es nicht nur auf ein konkretes Gerät (z.B. mit einer Seriennummer) paßt, sondern auf - prinzipiell - alle Geräte eines Typs oder sogar mehrerer Typen.
Wer Hilfestellung braucht, um aus einem konkret konfigurierten Gerät (=list) ein template zu machen: Es ist ok, hier einen Link auf den Beitrag mit dem list oder einen neuen Thread zu posten und um Hilfe zu bitten. Danach sollte sich hier aber wieder nur das Ergebnis finden.
Schaut euch die vorhandenen templates an, da ist schon einiges an Beispielen zu finden, auch wie man mehrere Parameter rausfindet, v.a. bei mqtt2zigbee (BASE_TOPIC und DEV_ID) und MiLight.

Eine Sonderform der Parametrierung ist die interne Weiterleitung auf bereits vorhandenen templates: Wenn es "nur" darum geht, ein bestimmtes Gerät anders oder erweitert zu konfigurieren, als ein bereits vorhandenes, kann man erst das vorhandene anwenden und dann einfach (nur) die abweichenden Attribute etc. setzen. Beispiel: A_10a_shellyplug. Dabei gilt die Regel, dass die letzte attr-Anweisung für ein bestimmtes Attribut sich am Ende tatsächlich auch im Device wiederfindet.

Defaults in der MQTT-Konfiguration der Geräte nutzen
Bitte laßt die MQTT-Einstellungen möglichst dort unverändert, wo sie sich auf den Empfang und die Auswertung in FHEM auswirken. Das betrifft z.B. den Namen des Geräts in den topics oder den Aufbau der topic-Struktur. Danach kann und darf man alles ändern, aber erst mal sollte es für andere in derselben Ausgangslage klappen!
Das gilt entsprechend für Modifikationen der firmware selbst.

Beschreibung hinzufügen
Andere freuen sich darüber, wenn ihr schreibt, für welches Gerät ihr das konkret verwendet habt und was der Zweck ist. Das muß im template einzeilig sein, längere Beschreibungen lassen sich mit "<br>" dann in der "?"-Ansicht formatieren.

Testen
Ein template kann man am z.B. testen, indem man in eine eigene template-file (idR. in /opt/fhem/FHEM/lib/AttrTemplate) anlegt (Endung: .template, Linux-konforme Zeilenumbrüche). Dann nach jeder Änderung mit "{ AttrTemplate_Initialize() }" neu einlesen, was voraussetzt, dass der user fhem die Rechte hat, die Datei auch zu lesen.

Vorschläge möglichst als diff
Ist alles fertig, könnt ihr eine Kopie der vorhandenen mqtt2.template-Datei anlegen, und euer template in die bisherige einfügen. Ein

Code: [Auswählen]

diff -u <original> <eure Kopie> > ~/mqtt2.template.<hinweis>.patch ausführen, dann liegt im home-Verzeichnis eures users die neue Datei, die ihr nach Durchsicht dann hier anfügen könnt.
Wäre dabei schön, wenn gleich eine sinnvolle Einordnung in das Nummernsystem drin wäre.
(EDIT: Die Sortierung erfolgt neurdings über "order:", nicht mehr über den template-Namen)
Der erste Buchstabe steht für eine Hauptgruppe.
- A ist reserviert für ESP-Derivate (aktuell Shelly und Tasmota),
- B-M für Kaufgeräte, die nativ MQTT sprechen
- L-Z für eher seltene Geräte oder auch ESP-firmwares, z.B. X90_esp_milight_hub_bridge
Die zweite Angabe wäre dann ein bestimmter Grundtyp ggf. mit einer oder mehreren Varianten. Orientiert euch einfach an dem, was da ist und macht einen Vorschlag.
Aber selbstredend ist es auch ok, wenn ihr nur eine Datei liefert, die ausschließlich euer Device enthält.

Viel Spaß beim Entwickeln und Anwenden!

Beta-User

EDIT:
links zu diversen template-Threads
- zigbee2mqtt: https://forum.fhem.de/index.php/topic,91394.0.html
- tasmota: https://forum.fhem.de/index.php/topic,94434.0.html
- tasmota-shutter: https://forum.fhem.de/index.php/topic,98366.0.html
- shelly: https://forum.fhem.de/index.php/topic,94060.0.html
- eBus: https://forum.fhem.de/index.php/topic,97989.0.html
- MiLight@sidoh-Bridge: https://forum.fhem.de/index.php/topic,86932.0.html

[torte]

Hallo zusammen

für den Shelly2 als Rolladen Schalter habe ich dieses Template erzeugt

Code: [Auswählen]

# shelly2 using original firmware.
name:A_11b_shelly2_roller
filter:TYPE=MQTT2_DEVICE
desc:shelly2 using original firmware. <br>NOTE: shelly2 roller operated
par:DEVNAME;Shelly2 name in the topic;{ AttrVal("DEVICE","readingList","") =~ m,shellies/([^/]*)/, ? $1 : undef }
attr DEVICE comment shelly2 roller operated
attr DEVICE setList \
  open:noArg shellies/DEVNAME/roller/0/command open\
  close:noArg shellies/DEVNAME/roller/0/command close\
  stop:noArg shellies/DEVNAME/roller/0/command stop\
  pos:slider,0,1,100 shellies/DEVNAME/roller/0/command/pos $EVTPART1
attr DEVICE readingList shellies/DEVNAME/roller/0/pos:.* state\
  shellies/DEVNAME/status/0/rollers:.* power
attr DEVICE devStateIcon 0:fts_shutter_100@green 100:fts_shutter_10@white 9\d.*:fts_shutter_10 8\d.*:fts_shutter_20 7\d.*:fts_shutter_30 6\d.*:fts_shutter_40 5\d.*:fts_shutter_50 4\d.*:fts_shutter_60 3\d.*:fts_shutter_70 2\d.*:fts_shutter_80 1\d.*:fts_shutter_90 0\d.*:fts_shutter_100
attr DEVICE model A_11b_shelly2


Bin mir aber nicht sicher bei dem Namen den ich ausgesucht habe und ob das attr für devStateIcon reinkommen darf.
Gleichzeitig habe ich einen Slider eingerichtet für die Position des Rollos in Prozent, weiß nicht ob das nötig ist, ich find es ganz praktisch.
Hoffe das auch sonst alles richtig ist, bei meinen shellys ist jedenfalls okay so.

Grüße
Torte

[Beta-User]

Danke, hab's eingecheckt!

Anmerkungen:
- Den Namen fand ich ok. Dieser sollte halt aussagefähig sein und sich irgendwie sinnvoll ins Umfeld einfügen. Allerdings sollte "model" dem Namen entsprechen: damit soll es leichter sein festzustellen, welches template angewandt wurde, falls jemand mal Probleme hat.
- Das devStateIcon ist im Prinzip auch völlig ok, allerdings macht eine Farbgebung je nach gewähltem Hintergrund mal mehr, mal weniger Freude (so jedenfalls mein bisheriger Eindruck); die Farbangaben habe ich daher rausgemacht, lasse mich da aber gerne auch vom Gegenteil überzeugen.
- die Descr. darf gerne auch kurze Hinweise zum "doing" enthalten. Ich habe jetzt mal präventiv einen kurzen Hinweis eingebaut, dass (irgendwelche ?) settings zuerst anzupassen seien. Bitte um Rückmeldung, ob dem so ist bzw. wie/wo man dazu eingreifen sollte (wenn es nicht "selbsterklärend" ist).

[Beta-User]

@torte:
Habe eben noch ein paar kleine Änderungen vorgenommen, die m.E. zur besseren Kompabilität mit AutoShuttersControl zweckmäßig sind. Für den Fall, dass du das auch nutzt, wäre es nett, du würdest dir das kurz ansehen. Weitere Diskussion dann ggf. separat bzw. im "Anregungen..."-Thread.

[luke666s]

Hallo,
ich hätte ein Template für die Xiaomi Zigbee Tür/Fenster Sensoren. getestet mit den Aquara und den Mijia Sensoren. Solange das reading "contact" ist müssten aber auch Sensoren von anderen Herstellern funktionieren

Code: [Auswählen]

name:L_06_zigbee2mqtt_XiaomiContactSensor
filter:TYPE=MQTT2_DEVICE
par:BASE_TOPIC;base topic as set in configuration.yaml of the zigbee2mqtt bridge in the topics;{ AttrVal("DEVICE","readingList","") =~ m,([^/]+)[/].*:, ? $1 : undef }
par:DEV_ID;name of the device in the zigbee2mqtt bridge;{ AttrVal("DEVICE","readingList","") =~ m,[^/]+[/](.*):, ? $1 : undef }
attr DEVICE stateFormat contact
attr DEVICE devStateIcon open:fts_window_1w_open@red close:fts_window_1w@green
attr DEVICE genericDeviceType contact
attr DEVICE eventMap true:close false:open
attr DEVICE readingList BASE_TOPIC/DEV_ID:.* { json2nameValue($EVENT) }
deletereading DEVICE .*
attr DEVICE model L_06_zigbee2mqtt_XiaomiContactSensor
Viel Spass damit

[Beta-User]

@luke666s: Danke, hab's mit kleinen Änderungen eingecheckt:

- Xiaomi raus, ich gehe auch davon aus, dass die Abstraktion bereits auf der zigbee2mqtt-Ebene erfolgt und daher auch andere Hersteller/Modelle passen würden=> findet sich jetzt in der desc, mit welchen Modellen getestet- genricDeviceType ist homekit-spezifisch und würde bei Leuten (wie mir), die das nicht haben zu Fehlern führen (ich sollte das wohl in den ersten Beitrag als Hinweis aufnehmen...).

[luke666s]

hier noch der Xiaomi Aquara Temp/Hum/Hpa sensor... ich hoffe mal der ist generisch, von den Readings sieht es gut aus....  das Template ist es auf jeden Fall

Code: [Auswählen]

name:L_07_zigbee2mqtt_TempHumHpaSensor
desc: Temp/hum/hpa sensor via zigbee2mqtt <br>Tested with: Xiaomi Aquara WSDCGQ11LM Temperature Humidity Sensor
filter:TYPE=MQTT2_DEVICE
par:BASE_TOPIC;base topic as set in configuration.yaml of the zigbee2mqtt bridge in the topics;{ AttrVal("DEVICE","readingList","") =~ m,([^/]+)[/].*:, ? $1 : undef }
par:DEV_ID;name of the device in the zigbee2mqtt bridge;{ AttrVal("DEVICE","readingList","") =~ m,[^/]+[/](.*):, ? $1 : undef }
attr DEVICE stateFormat {sprintf ("Temperature: %.1f°C Humidity: %.1f%% Pressure: %.1fhpa", ReadingsVal($name,"temperature",0), ReadingsVal($name,"humidity",0), ReadingsVal($name,"pressure",0)) }
attr DEVICE readingList BASE_TOPIC/DEV_ID:.* { json2nameValue($EVENT) }
deletereading DEVICE .*
attr DEVICE model L_07_TempHumHpa_TempSensor
cheers

[Beta-User]

....und eingecheckt, Danke!

[Intruder1956]

Hallo,
kann es sein, das das Template L_01_zigbee2mqtt_bridge einen Fehler hat.
z.b. folgende Zeile

Code: [Auswählen]

zigbee2mqtt/bridge/log:.*\"type\".\"devices\".\"message\".* devices\

Ich frage deshalb weil nach dem

Code: [Auswählen]

igbee2mqtt/bridge/log:.*\ im Editor  fhem.cfg  oder beim editieren von attr readinglist, alles in grün angezeigt wird.

Gruß Werner

[OdfFhem]

Da die Einträge in der readingList wie gewünscht ihren Dienst verrichten, vermute ich, dass es "lediglich" Interpretationsprobleme mit den maskierten Hochkommata im Editor gibt.

[Beta-User]

Vorab @Intruder1956: das ist m.E. der falsche Ort für diese Frage!

Für Fehlermeldungen, Diskussionen zu Verbesserungsvorschlägen zu vorhandenen ist ein weiterer Thread gedacht, dieser hier sollte möglichst übersichtlich bleiben und sich auf das Wesentliche beschränken.

Und da es bei deiner Frage auch "nur" darum geht, dass ein _verändertes_ Attribut irgendwie im Editor "komisch" aussieht, ist es eigentlich m.E. gar keine Frage zu den templates, sondern gehört in einen separaten Thread.

Wen es interessiert: Die templates bearbeite ich vor dem Hochladen ins svn ausschließlich mit Kate unter einem Linux-System, fürs Testen kopiere ich das meistens blockweise auf der Konsole auf meinen FHEM-Server, das ganze mit ssh und mc als Editor.... Wer da Verbesserungsvorschläge hat, darf die gerne in dem anderen Thread loswerden.

[Intruder1956]

soll ich es hier löschen ??

[luke666s]

hab hier noch ne Kleinigkeit....

Code: [Auswählen]

name:L_08_zigbee2mqtt_Human_Motion_Sensor
desc: Temp/hum/hpa sensor via zigbee2mqtt <br>Tested with: Xiaomi Aquara RTCGQ11LM Human Motion Sensor
filter:TYPE=MQTT2_DEVICE
par:BASE_TOPIC;base topic as set in configuration.yaml of the zigbee2mqtt bridge in the topics;{ AttrVal("DEVICE","readingList","") =~ m,([^/]+)[/].*:, ? $1 : undef }
par:DEV_ID;name of the device in the zigbee2mqtt bridge;{ AttrVal("DEVICE","readingList","") =~ m,[^/]+[/](.*):, ? $1 : undef }
attr DEVICE stateFormat Motion: occupancy Luminance: illuminance
attr DEVICE readingList BASE_TOPIC/DEV_ID:.* { json2nameValue($EVENT) }
deletereading DEVICE .*
attr DEVICE model L_08_Human_Motion_TempSensor


Code: [Auswählen]

name:L_09_zigbee2mqtt_Motion_Sensor
desc: Temp/hum/hpa sensor via zigbee2mqtt <br>Tested with: Xiaomi Aquara DJT11LM Smart Motion Sensor
filter:TYPE=MQTT2_DEVICE
par:BASE_TOPIC;base topic as set in configuration.yaml of the zigbee2mqtt bridge in the topics;{ AttrVal("DEVICE","readingList","") =~ m,([^/]+)[/].*:, ? $1 : undef }
par:DEV_ID;name of the device in the zigbee2mqtt bridge;{ AttrVal("DEVICE","readingList","") =~ m,[^/]+[/](.*):, ? $1 : undef }
attr DEVICE stateFormat Motion: action X: angle_x Y: angle_y Z: angle_z
attr DEVICE readingList BASE_TOPIC/DEV_ID:.* { json2nameValue($EVENT) }
deletereading DEVICE .*
attr DEVICE model L_09_Motion_Sensor


Code: [Auswählen]

name:L_10_zigbee2mqtt_Water_Leak_Sensor
desc: Temp/hum/hpa sensor via zigbee2mqtt <br>Tested with: Xiaomi Aquara SJCGQ11LM Water Leak Sensor
filter:TYPE=MQTT2_DEVICE
par:BASE_TOPIC;base topic as set in configuration.yaml of the zigbee2mqtt bridge in the topics;{ AttrVal("DEVICE","readingList","") =~ m,([^/]+)[/].*:, ? $1 : undef }
par:DEV_ID;name of the device in the zigbee2mqtt bridge;{ AttrVal("DEVICE","readingList","") =~ m,[^/]+[/](.*):, ? $1 : undef }
attr DEVICE stateFormat Leak: water_leak
attr DEVICE readingList BASE_TOPIC/DEV_ID:.* { json2nameValue($EVENT) }
deletereading DEVICE .*
attr DEVICE model L_10_Water_Leak_Sensor


Code: [Auswählen]

name:L_11_zigbee2mqtt_Light_Switch
desc: Temp/hum/hpa sensor via zigbee2mqtt <br>Tested with: Xiaomi Aquara WXKG02LM 2btn Smart Light Switch
filter:TYPE=MQTT2_DEVICE
par:BASE_TOPIC;base topic as set in configuration.yaml of the zigbee2mqtt bridge in the topics;{ AttrVal("DEVICE","readingList","") =~ m,([^/]+)[/].*:, ? $1 : undef }
par:DEV_ID;name of the device in the zigbee2mqtt bridge;{ AttrVal("DEVICE","readingList","") =~ m,[^/]+[/](.*):, ? $1 : undef }
attr DEVICE stateFormat click
attr DEVICE readingList BASE_TOPIC/DEV_ID:.* { json2nameValue($EVENT) }
deletereading DEVICE .*
attr DEVICE model L_11_Light_Switch
cheers....

[Beta-User]

hab hier noch ne Kleinigkeit....

Sehen mustergültig aus & sind eingecheckt, viel Spaß allen damit!

[luke666s]

Hier mal ein Template für den Magichome RGB(W) Controller -> https://github.com/arendst/Sonoff-Tasmota/wiki/MagicHome-LED-strip-controller
Zumindest bei den von mir verwendeten LED strips musste ich im Tasmota "Arilux LC-01" als Gerät auswählen...

DISCLAIMER: es existieren mindestens 2 Varianten vom RGB controller! Ich habe beide getestet, hatte aber mit der alten Variante (mit aufgelöteten ESP) das Problem, dass sie sich (nacht dem ersten umflashen auf tasmota 6.4.1) zwar wie die neue über POWER steuern liess aber mir nur ein POWER1 reading zurück gab und kein POWER reading, sich aber im Gegenzug auch nicht über POWER1 steuern ließ... Ein zusätzlicher factory reset hatte geholfen.... Die neue mit integriertem ESP hatte dieses Problem nicht. Hier war cmnd und reading gleich (POWER). Evt war das nur ein Einzelfall ich wollte es aber erwähnen...

Weiterhin habe ich es statt A_05 A_05a genannt, falls noch jemand den passenden RGBW also A_05b hinzufügen will

Code: [Auswählen]

name:A_05a_tasmota_rgb_led_controller
filter:TYPE=MQTT2_DEVICE
desc:Tasmota RGB controller tested with RGB variant of Magichome, arilux LC-01 ,etc... -> https://github.com/arendst/Sonoff-Tasmota/wiki/MagicHome-LED-strip-controller
par:DEVNAME;ESP's name in the topic;{ AttrVal("DEVICE","readingList","") =~ m,tele/([^/]*)/, ? $1 : undef }
attr DEVICE setList\
  off:noArg cmnd/DEVNAME/POWER 0\
  on:noArg cmnd/DEVNAME/POWER 1\
  toggle:noArg cmnd/DEVNAME/POWER 2\
  rgb:colorpicker,RGB cmnd/DEVNAME/COLOR
attr DEVICE readingList \
  tele/DEVNAME/LWT:.* LWT\
  stat/DEVNAME/POWER:.* POWER\
  tele/DEVNAME/STATE:.* { json2nameValue($EVENT) }\
  stat/DEVNAME/RESULT:.* { json2nameValue($EVENT) }\
  tele/DEVNAME/INFO.:.* { json2nameValue($EVENT) }
attr DEVICE userReadings rgb /stat/DEVNAME/COLOR
deletereading DEVICE .*
attr DEVICE autocreate 0
attr DEVICE devStateIcon {Color::devStateIcon($name,"rgb","rgb","state")}
attr DEVICE stateFormat POWER
attr DEVICE webCmd on:off:rgb
attr DEVICE icon light_control
attr DEVICE userReadings rgb {ReadingsVal($name,'Color','0')}
attr DEVICE webCmd rgb:rgb ff0000:rgb 00ff00:rgb 0000ff:toggle:on:off
attr DEVICE model A_05a_tasmota_rgb_led_controller
sollte jemand das hombridgeMapping brauchen....

Code: [Auswählen]

attr DEVICE homebridgeMapping Hue=Color,max=100,factor=3.6,cmd=color,cmds=0:color+100,On=POWERcheers