Virtuelle Geräte
Ab Version 2 des CCU-Jacks werden virtuelle Geräte in der CCU unterstützt. Diese bieten eine nahtlose Integration in die Bedien- und Beobachtungsoberfläche der CCU und können in CCU-Programmen wie reale Geräte abgefragt und gesteuert werden. Dadurch wird der Logik-Schicht der CCU (ReGaHss) selbst ermöglicht, Daten aus Fremdsystemen oder -geräten abzufragen oder an diese zu übertragen.
Achtung: Virtuelle Geräte funktionieren nur dann, wenn der CCU-Jack als Add-On auf der CCU installiert wurde. Eine neue Geräteschnittstelle wird zur Projektierung der CCU hinzugefügt. Der Hersteller der CCU kann unter Umständen Support-Leistungen ablehnen. Dies betrifft generell jede zusätzlich installierte Software auf der CCU.
Virtuelle Geräte müssen als erstes in der Konfiguration des CCU-Jacks aktiviert werden. Danach ist ein Neustart der CCU erforderlich. Virtuelle Geräte werden dann über die Web-UI des CCU-Jacks angelegt und auch die gewünschten Kanäle hinzugefügt. Neu angelegte Geräte erscheinen direkt im Geräte-Posteingang der CCU. Spezifische Einstellungen der Geräte können dann in der CCU vorgenommen werden (Einstellungen → Geräte → Gerät auswählen → Einstellen).
Achtung: Wenn noch virtuelle Geräte auf der CCU angelegt sind, und der CCU-Jack deinstalliert und erneut installiert wird, so werden die vorhandenen virtuellen Geräte gelöscht. Die vorhandene Konfigurationsdatei ccu-jack.cfg mit den virtuellen Geräten wird in diesem Fall durch eine leere ersetzt. Um den CCU-Jack zu aktualisieren, die neue Version einfach über die bereits vorhandene Version installieren. Dadurch wird die vorhandene Konfigurationsdatei übernommen.
Der CCU-Jack bietet die Möglichkeit virtuelle Geräte aus bis zu 32 beliebigen Kanalfunktionen zusammenzustellen. Dadurch können alle Funktionen und Messwerte eines Fremdgerätes in einem Gerät auf der CCU nachgebildet werden.
Im Folgenden sind die unterstützten virtuellen Geräte beschrieben. Spezifische Einstellungen der Geräte können in der CCU vorgenommen werden (Einstellungen → Geräte → Gerät auswählen → Einstellen).
Hinweis:
Durch einen Fehler in der Web-UI der CCU können zwar die Zeichen ' und " (einfaches und doppeltes Hochkomma) in Werten von Text-Parametern (z.B. SHORT_PAYLOAD) angegeben werden, beim Anzeigen dieser Zeichen werden sie aber fälschlicherweise als HTML-Entitäten (' und ") kodiert. Bei einem erneuten Setzen werden die HTML-Entitäten durch den CCU-Jack automatisch zurückgewandelt. Zudem dürfen in Text-Parametern zurzeit nur ASCII-Zeichen verwendet werden. Beispielsweise sind die Zeichen üöäÜÖÄß nicht zulässig.
Statische Geräte besitzen keine interne Logik und keine Einstellmöglichkeiten. Sie dienen dazu, zusätzliche Datenpunkte zu erschaffen, die über die MQTT- und REST-API des CCU-Jacks angesprochen werden können. Gleichzeitig können sie nahtlos in CCU-Programmen verwendet werden.
| Kanaltyp | Ab Version | Funktion |
|---|---|---|
| Taster | 2.0.11 | Taster (wie die virtuellen Taster in der CCU) |
| Schaltaktor | 2.0.11 | Schaltaktor (wie HM-LC-Sw1-Pl) |
| Analogeingang | 2.0.11 | Analogeingang (wie HmIP-MIO16-PCB Kanal 1, aber der Eingang kann zusätzlich von der CCU oder von extern gesetzt werden) |
| Tür-/Fensterkontakt | 2.0.47 | Tür-/Fensterkontakt (wie HM-Sec-SC-2) |
| Dimmer | 2.0.62 | Dimmer (wie HM-LC-Dim1TPBU-FM) |
| Temperatursensor | 2.5.0 | Temperatursensor (wie HmIP-STHO) |
| Leistungsmessung / Stromzähler | 2.6.1 | Leistungsmessung / Stromzähler (wie HM-ES-PMSw1) |
Der CCU-Jack enthält einen vollwertigen MQTT-Server, über den generell Datenpunkte der CCU gelesen und gesetzt werden können. Allerdings kann der MQTT-Server auch von beliebigen anderen MQTT-Clients zum Datenaustausch untereinander verwendet werden. Viele Geräte bzw. Geräte-Firmwares (siehe unten) können als MQTT-Client konfiguriert werden und sich dann mit dem MQTT-Server des CCU-Jacks verbinden.
MQTT-Geräte senden bei Zustandsänderungen (z.B. Tastendruck, Schalten eines Aktors) frei konfigurierbare Nachrichten (MQTT-Payload) auf frei konfigurierbaren MQTT-Topics. Zudem können MQTT-Geräte Topics abonnieren und bei eingehenden Nachrichten ihren eigenen Zustand anpassen (z.B. Rückmeldungen von Schaltaktoren, Messwerte).
Durch die weite Verbreitung des MQTT-Protokolls können eine Vielzahl an Geräten einfach an die CCU angebunden und in die CCU-Automatisierung integriert werden. Im Folgenden sind einige Beispiele aufgelistet:
- DeLock WLAN-Steckdosen
- Shelly
- Geräte-Firmwares mit MQTT-Unterstützung
In der MQTT-Konfiguration der Geräte muss die CCU als MQTT-Server (bzw. Broker) eingetragen werden. Der MQTT-Port 1883 bzw. 8883 muss in der CCU-Firewall freigegeben sein. Die MQTT-Payload wird als Text in UTF-8-Kodierung behandelt. Auf der Diagnose-Seite des CCU-Jacks werden eventuelle Konfigurationsfehler angezeigt.
| Kanaltyp | Ab Version | Funktion |
|---|---|---|
| MQTT Sendetaster | 2.0.31 | Taster zum Senden von beliebigen MQTT-Nachrichten |
| MQTT Empfangstaster | 2.0.31 | Taster zum Empfangen von beliebigen MQTT-Nachrichten |
| MQTT Schaltaktor | 2.0.31 | Schaltaktor zum Senden von MQTT-Nachrichten beim Ein- und Aussschalten |
| MQTT Schaltaktor mit Rückmeldung | 2.0.31 | Zusätzlich wird der Status des Schaltaktors durch empfangene MQTT-Nachrichten aktualisiert. |
| MQTT Analogwertempfänger | 2.0.31 | Ein Zahlenwert wird aus der MQTT-Nachricht extrahiert und als Analogwert zur Verfügung gestellt. |
| MQTT Fenster-/Türkontakt | 2.0.47 | Fenster-/Türkontakt zum Empfangen von MQTT-Nachrichten |
| MQTT Dimmer | 2.0.62 | Dimmer zum Senden und Empfangen von MQTT-Nachrichten mit einem Dimmwert (wie HM-LC-Dim1TPBU-FM) |
| MQTT Temperatursensor | 2.5.0 | Temperatursensor (wie HmIP-STHO) |
| MQTT Leistungsmessung / Stromzähler | 2.7.0 | Leistungsmessung / Stromzähler (wie HM-ES-PMSw1) |
Der MQTT-Sendetaster sendet konfigurierbare MQTT-Nachrichten.
Liste der Einstellungsparameter:
| Name | Bedeutung |
|---|---|
| SHORT_TOPIC | MQTT-Topic für einen kurzen Tastendruck |
| SHORT_PAYLOAD | MQTT-Payload für einen kurzen Tastendruck |
| SHORT_RETAIN | Der MQTT-Server soll die zuletzt gesendete Nachricht speichern. |
| LONG_TOPIC | s.o., für langen Tastendruck |
| LONG_PAYLOAD | s.o., für langen Tastendruck |
| LONG_RETAIN | s.o., für langen Tastendruck |
Der MQTT-Empfangstaster löst einen Tastendruck beim Empfang einer MQTT-Nachricht aus.
Liste der Einstellungsparameter:
| Name | Bedeutung |
|---|---|
| SHORT_TOPIC | MQTT-Topic für einen kurzen Tastendruck. Die Platzhalter + und # werden unterstützt. |
| SHORT_PATTERN | Prüfmuster für die MQTT-Payload (abhängig von SHORT_MATCHER) |
| SHORT_MATCHER | Vergleichsfunktion für die Überprüfung der Payload mit dem Prüfmuster (EXACT: Die Payload muss dem Prüfmuster entsprechen; CONTAINS: In der Payload muss das Prüfmuster enthalten sein; REGEXP: Das Prüfmuster ist ein regulärer Ausdruck, der zutreffen muss.) |
| LONG_TOPIC | s.o., für langen Tastendruck |
| LONG_PATTERN | s.o., für langen Tastendruck |
| LONG_MATCHER | s.o., für langen Tastendruck |
Für reguläre Ausdrücke werden die üblichen Operatoren und Zeichenklassen unterstützt. Weitere Informationen sind in der Spezifikation zu finden.
MQTT-Schaltaktor sendet beim Ein- oder Ausschalten jeweils eine MQTT-Nachricht.
Liste der Einstellungsparameter:
| Name | Bedeutung |
|---|---|
| TOPIC | MQTT-Topic für das Ein- oder Ausschalten |
| RETAIN | Der MQTT-Server soll die zuletzt gesendete Nachricht speichern. |
| ON_PAYLOAD | MQTT-Payload für das Einschalten |
| OFF_PAYLOAD | MQTT-Payload für das Ausschalten |
MQTT-Schaltaktor sendet ebenfalls beim Ein- oder Ausschalten jeweils eine MQTT-Nachricht. Der Zustand wird aber erst aktualisiert, wenn eine Rückmeldung vom MQTT-Gerät eingeht.
Liste der Einstellungsparameter:
| Name | Bedeutung |
|---|---|
| COMMAND_TOPIC | MQTT-Topic für das Ein- oder Ausschalten |
| RETAIN | Der MQTT-Server soll die zuletzt gesendete Nachricht speichern. |
| ON_PAYLOAD | MQTT-Payload für das Einschalten |
| OFF_PAYLOAD | MQTT-Payload für das Ausschalten |
| FEEDBACK_TOPIC | MQTT-Topic für die Rückmeldung. Die Platzhalter + und # werden unterstützt. |
| MATCHER | Vergleichsfunktion für die Überprüfung der Payload mit dem Prüfmuster (EXACT: Die Payload muss dem Prüfmuster entsprechen; CONTAINS: In der Payload muss das Prüfmuster enthalten sein; REGEXP: Das Prüfmuster ist ein regulärer Ausdruck, der zutreffen muss.) |
| ON_PATTERN | Prüfmuster für die MQTT-Payload für den eingeschalteten Zustand (abhängig von MATCHER) |
| OFF_PATTERN | Prüfmuster für die MQTT-Payload für den ausgeschalteten Zustand (abhängig von MATCHER) |
Für reguläre Ausdrücke werden die üblichen Operatoren und Zeichenklassen unterstützt. Weitere Informationen sind in der Spezifikation zu finden.
Der MQTT-Analogwertempfänger extrahiert aus der MQTT-Payload eine als Text übertragene Zahl und stellt sie als Analogwert der CCU zur Verfügung. Diese kann optional ein . (Punkt) als Dezimaltrennzeichen enthalten. Falls die Zahl nicht extrahiert werden kann, so wird der Status des Analogwerts auf Überlauf gesetzt.
Liste der Einstellungsparameter:
| Name | Bedeutung |
|---|---|
| TOPIC | MQTT-Topic für die zu empfangenden Nachrichten. Die Platzhalter + und # werden unterstützt. |
| PATTERN | Suchmuster für den Zahlenwert in der MQTT-Payload (abhängig von EXTRACTOR) |
| EXTRACTOR | Methode für die Extraktion des Zahlenwertes (AFTER: Der nächstliegende Zahlenwert hinter dem Suchmuster wird verwendet; BEFORE: Der nächstliegende Zahlenwert vor dem Suchmuster wird verwendet; REGEXP: Das Suchmuster ist ein regulärer Ausdruck. Der Zahlenwert befindet sich in der Gruppe mit der Nummer REGEXP_GROUP; ALL: Die ganze MQTT-Payload wird als Zahlenwert interpretiert; TEMPLATE: Eine Vorlage im Parameter PATTERN dient zur Abbildung der MQTT-Payload auf einen Zahlenwert.) |
| REGEXP_GROUP | Nummer der zu verwendenden Gruppe des regulären Ausdrucks, wenn EXTRACTOR auf REGEXP gesetzt ist. |
Beispiele:
| EXTRACTOR | PATTERN | REGEXP_GROUP | MQTT-Payload | Extrahierter Zahlenwert | Bemerkungen |
|---|---|---|---|---|---|
| BEFORE | cm |
0 | 100 l 52 cm | 52,0 | REGEXP_GROUP ist egal. |
| AFTER | Vcc |
0 | { "Vcc": 3.3, "Version": 2.2 } | 3,3 | REGEXP_GROUP ist egal. |
| REGEXP | (\S+) (\S+) (\S+) |
1 | 123 543.31 21.3 | 123,0 | 1. Zahl wird extrahiert. |
| REGEXP | (\S+) (\S+) (\S+) |
2 | 123 543.31 21.3 | 543,31 | 2. Zahl wird extrahiert. |
| ALL | 0 | -7. | -7,0 | REGEXP_GROUP und PATTERN sind egal. | |
| TEMPLATE | {{(parseJSON .).a.b.c}} |
0 | {"a":{"b":{"c":55.5}}} | 55,5 | REGEXP_GROUP ist egal. |
Für reguläre Ausdrücke werden die üblichen Operatoren und Zeichenklassen unterstützt. Weitere Informationen sind in der Spezifikation zu finden.
Das Extrahieren von Werten aus der MQTT-Payload mit Hilfe der TEMPLATE-Methode ist weiter unten beschrieben.
Der Zustand des virtuellen Fenster-/Türkontakts wird aktualisiert, wenn eine Nachricht vom MQTT-Gerät empfangen wird.
Liste der Einstellungsparameter:
| Name | Bedeutung |
|---|---|
| TOPIC | MQTT-Topic für die Statusmeldungen. Die Platzhalter + und # werden unterstützt. |
| MATCHER | Vergleichsfunktion für die Überprüfung der Payload mit dem Prüfmuster (EXACT: Die Payload muss dem Prüfmuster entsprechen; CONTAINS: In der Payload muss das Prüfmuster enthalten sein; REGEXP: Das Prüfmuster ist ein regulärer Ausdruck, der zutreffen muss.) |
| OPEN_PATTERN | Prüfmuster für die MQTT-Payload für den geöffneten Zustand (abhängig von MATCHER) |
| CLOSED_PATTERN | Prüfmuster für die MQTT-Payload für den geschossenen Zustand (abhängig von MATCHER) |
Mit dem MQTT-Dimmer kann ein Analogwert/Zahlenwert per MQTT gesendet werden. Der Wertebereich kann mit den Einstellungsparametern RANGE_MIN und RANGE_MAX angepasst werden. Die Parameter COMMAND_TOPIC, RETAIN und TEMPLATE enthalten die nötigen Informationen zum Senden der MQTT-Nachricht. Durch die (optionale) Angabe der Parameter FEEDBACK_TOPIC, PATTERN, EXTRACTOR und REGEXP_GROUP kann der gespeicherte Wert in der CCU durch das MQTT-Gerät auch aktualisiert werden.
Liste der Einstellungsparameter:
| Name | Bedeutung |
|---|---|
| RANGE_MIN | Gerätewert für Dimmwert 0% |
| RANGE_MAX | Gerätewert für Dimmwert 100% |
| COMMAND_TOPIC | MQTT-Topic für das Setzen des Dimmwertes |
| RETAIN | Der MQTT-Server soll die zuletzt gesendete Nachricht speichern. |
| TEMPLATE | Vorlage für die Erstellung der MQTT-Payload |
| FEEDBACK_TOPIC | MQTT-Topic für die Rückmeldung des tatsächlichen Dimmwerts. Die Platzhalter + und # werden unterstützt. (Optional) |
| PATTERN | siehe MQTT Analogwertempfänger (Optional) |
| EXTRACTOR | siehe MQTT Analogwertempfänger (Optional) |
| REGEXP_GROUP | siehe MQTT Analogwertempfänger (Optional) |
Im Kanalparameter TEMPLATE wird die Vorlage für die Erstellung der MQTT-Payload angegeben. In den folgenden Beispielen wird ein zu sendender Dimmwert von 55,5% und RANGE_MIN=0 und RANGE_MAX=100,0 angenommen.
| TEMPLATE | Ausgabe |
|---|---|
{{.}} |
55.5 |
{{.|round}} |
56 |
{"brightness":{{.}}} |
{"brightness":55.5} |
Die Generierung der Payload mit Hilfe des TEMPLATE-Parameters ist weiter unten näher beschrieben.
Die Konfiguration erfolgt analog zu dem MQTT-Analogwertempfänger.
Die Konfiguration erfolgt analog zu dem MQTT-Analogwertempfänger.
Mit Hilfe von Vorlagen bzw. Templates kann aus einem Zahlenwert eine MQTT-Payload generiert werden (z.B. als Ausgabe für den MQTT-Dimmer) oder eine MQTT-Payload in eine Zahl umgewandelt werden (z.B. als Eingabe für den MQTT-Analogwertempfänger). Funktionsweise und Aufbau der Templates sind in der zugehörigen Entwicklerdokumentation beschrieben.
Eine Vorlage bzw. ein Template wandelt den Eingangswert in einen Text um. Der resultierende Text ist entweder eine zu sendende MQTT-Payload oder eine aus einer empfangenen MQTT-Payload extrahierte Zahl. In der Vorlage müssen Ausdrücke, die eine Verarbeitung vornehmen, in {{ und }} eingeschlossen werden. Der Eingangswert wird durch einen alleinstehenden Punkt . repräsentiert.
Die Verarbeitung der Vorlage {{ div (index (parseJSON .) "1.8.0") 1000 }} läuft folgendermaßen ab:
- Der Eingangswert wird in ein JSON-Objekt umgewandelt.
- Von dem JSON-Objekt wird die Eigenschaft
1.8.0ausgewählt. - Der Wert der Eigenschaft wird durch 1000 dividiert.
Die Auswertungsreihenfolge der Funktionen ist also von der innersten Klammer zur äußersten. Aus dem Eingangswert {"1.8.0":625026,"2.8.0":2195717} wird so die Zahl 625,026 extrahiert.
Folgende zusätzliche Funktionen stehen zur Verfügung:
| Funktion | Argumente | Beschreibung | ab Version |
|---|---|---|---|
round |
Zahl | Die Zahl wird zur nächstliegenden Ganzzahl gerundet. | |
parseJSON |
Text | Der Text wird in ein JSON-Objekt umgewandelt. | |
contains |
Text Suchtext | Es wird geprüft, ob der Suchtext im Text enthalten ist. | v2.2.1 |
fields |
Text | Der Text wird anhand der Leerräume zerlegt. | v2.2.1 |
split |
Text Trenntext | Der Text wird anhand des Trenntextes zerlegt. | v2.2.1 |
toLower |
Text | Der Text wird in Kleinbuchstaben umgewandelt. | v2.2.1 |
toUpper |
Text | Der Text wird in Großbuchstaben umgewandelt. | v2.2.1 |
trimSpace |
Text | Leerraum vor und hinter dem Text wird entfernt. | v2.2.1 |
add |
a b | a und b werden addiert. | v2.7.0 |
sub |
a b | b wird von a subtrahiert. | v2.7.0 |
mul |
a b | a und b werden multipliziert. | v2.7.0 |
div |
a b | a wird durch b dividiert. | v2.7.0 |
mapRange |
inMin inMax outMin outMax Wert | Der Wert wird vom Wertebereich inMin/inMax auf den Wertebereich outMin/outMax abgebildet. | v2.7.0 |
Der alleinstehende Punkt im Template repräsentiert den auszugebenen Wert.
Beispiele:
| Template | Eingabe | Ausgabe |
|---|---|---|
| {{if eq . 0.0}}{"turn":"off"}{{else}}{"brightness":{{.}},"turn":"on"}{{end}} | 0,0 | {"turn":"off"} |
| wie oben | 42,0 | {"brightness":42,"turn":"on"} |
| {{.}} | 55,5 | 55.5 |
| {{.|round}} | 55,5 | 56 |
| {"brightness":{{.}}} | 55,5 | {"brightness":55.5} |
Für das Einlesen eines Wertes aus der MQTT-Payload muss das konfigurierte Template eine Zahl (optional mit Punkt und Nachkommastellen) generieren. Der alleinstehende Punkt im Template repräsentiert den Inhalt der empfangenen MQTT-Nachricht.
Beispiele:
| Template | Eingabe | Ausgabe |
|---|---|---|
| {{with parseJSON .}}{{if .ison}}{{.brightness}}{{else}}0{{end}}{{end}} | {"brightness":21,"ison":false} | 0,0 |
| wie oben | {"brightness":42,"ison":true} | 42,0 |
| {{if contains . "b"}}1{{else}}0{{end}} | abc | 1,0 |
| wie oben | def | 0,0 |
| {{index (fields .) 1 }} | 1 2 3 | 2,0 |
| {{index (split . ",") 2 }} | 1,2,3 | 3,0 |
| {{if eq (toLower .) "abc"}}1{{else}}0{{end}} | aBC | 1,0 |
| {{if eq (toUpper .) "ABC"}}1{{else}}0{{end}} | Abc | 1,0 |
| {{if eq (trimSpace .) "abc"}}1{{else}}0{{end}} | Leerraum abc Leerraum | 1,0 |
| {{slice . 0 2}}{{slice . 3 5}} | 14:23 | 1423,0 |
| wie oben | 00:01 | 1,0 |
| {{ mul (parseJSON .).ENERGY.Total 1000 }} | {"ENERGY":{"Total":0.12}} | 120,0 |
| {{ mapRange -10 10 0 100 . }} | 5.0 | 75,0 |
| {{ div (index (parseJSON .) "1.8.0") 1000 }} | {"1.8.0":625026,"2.8.0":2195717} | 625,026 |
Autor dieses Handbuchs ist Mathias Dzionsko. Dieses Handbuch steht unter folgender Lizenz:
