Custom Devices - extern oder in p44script implementiert

Was sind "Custom Devices"?

"Custom Devices" (kundenspezifische Geräte) sind Geräte, die sich im System (Digital Strom bei P44-DSB-xx, oder via matter-Integration) genau wie andere Geräte verhalten, aber vom/von der Anwender:in auf einfache Weise selber implementiert werden können. Auf diese Weise kann auch spezielle Hardware einfach ins Smart Home eingebunden werden, etwa über eine http-API oder (z.B. auf P44-DSB-X) über direkte Hardwareerweiterungen (RaspberryPi Shields, an GPIO angeschlossene Chips etc.).

Wie werden "Custom Devices" erstellt?

"Custom Devices" können auf zwei verschiedene Arten umgesetzt werden:

  • Ab Firmware-Version 2.6.0 direkt im P44-xx-Gerät als p44script. Diese Art externe Geräte können komplett über das Webinterface von P44-xx-Geräten erstellt werden, und sind als Teil der Gerätekonfiguration auch in den Konfigurations-Backups gesichert. p44script bietet eine Menge von komfortablen Funktionen, um verschiedene Arten von Geräten anzusteuern: von Funktionen für Zugriff auf HTTP-APIs (geturl, posturl, puturl), direkten Zugriff auf digitale (digitalio) und analoge (analogio) Ein- und Ausgänge, über Motoren mit Endschaltern und Stromüberwachung (dcmotor), bis hin zum Graphiksubsytem lrgraphics für SmartLED-Ketten ist vieles möglich. Hier sind einfach umsetzbare/erweiterbare Beispiele zu finden.

  • Schon seit Firmware 1.5.0.8 gibt es die external device API. Mit dieser kann ein externes Script oder eine Anwendung sich mit einem P44-xx-Gerät über einen TCP-Socket verbinden und auf einfache Weise Geräte ins Smarthome-System einbinden. Dieser Weg bietet sich z.B. an, um Verbindungen zwischen verschiedenen Systemen herzustellen, oder Geräte mit sehr komplexer Implementation, die den Rahmen der p44Script-Performance sprengen würden, einzubinden. Hier sind verschiedene Beispiele zu finden, wie die external device API verwendet werden kann.

Diese zwei möglichen Implementierungs-Arten funktionieren vom Konzept her fast identisch, der Unterschied besteht nur darin, wo die Implementierung läuft (innerhalb des P44-xx-Geräts als p44script, oder ausserhalb und über TCP-Socket verbunden). In beiden Fällen ist aber die Kommunikations-"Sprache" der Geräteimplementation mit dem System die gleiche, nämlich die external device API. Bei den p44script-Implementationen wird die Funktion message() verwendet, um external device API Messages zu empfangen und zu versenden. Bei ganz externen Geräten werden die Messages über TCP/IP ausgetauscht.

Gemeinsamkeiten von p44script- und externen Implementationen

  • Das Gerät wird gegenüber dem System durch die sogenannte init-Message beschrieben, die die Form eines JSON-Objekts hat.
  • In der init-Message kann zwischen einem ganz einfachen Text-Variante und einerausführlicheren JSON-Variante für die weitere Kommunikation gewählt werden. Standardmässig wird JSON verwendet, was in p44Script sehr einfach gelesen und geschrieben werden kann.
  • Die Implementation muss sich nur darum kümmern, vom System vorgegebene Ausgangswerte an die Hardware zu übermitteln und Eingangswerte an das System zu melden. Die ganze Komplexität von Szenen, Raumzuordnungen, Click-Erkennung, Dimmverhalten, Sensorwert-Filtern etc. wird vom P44-xx-Gerät erledigt.

Unterschiede zwischen p44script- und externen Implementationen

  • Bei p44script-Implementationen wird die init-Message einmalig beim Erstellen des Geräts in der Web-Oberfläche eingegeben. Bei externen Geräten muss die init-Message zu Beginn der Kommunikation (jedesmal, wenn die TCP-Verbindung neu aufgebaut wird) übermittelt werden.
  • Bei p44script-Implementationen darf die init-Message auf mehreren Zeilen geschrieben werden und kann sogar C-Style Kommentare /* ... */ enthalten. Bei externen Geräten muss die ganze init-Message auf einer einzigen Zeile und als reines JSON ohne Kommentare gesendet werden (weil das Zeilenende als Message-Trennung aufgefasst wird).
  • Bei externen Implementationen ist es möglich, mehrere Geräte über eine einzelne TCP-Verbindung laufen zu lassen; die Messages werden dann via sogenannte tags verschiedenen Geräten zugeordnet. Bei p44script-Implemnentationen gibt keinen solchen Mehrfach-Geräate-Mechanismus, und deshalb auch keine tags. Die in der folgenden Beschreibung der external device API vorkommenden Hinweise auf tag-Parameter sind deshalb für p44script-Implementationen irrelevant.
  • In p44script-Implementationen sind die messages initvdc, log und bye nicht verfügbar.

Verwendung der externen Geräte-API aus p44script-Implementationen heraus

Achtung - Unkorrigierte maschinelle Übersetzung

Diese deutsche Version des folgenden Texts ist momentan zu 100% maschinenübersetzt. Bei Unklarheiten bitte in der englischen Version (die in diesem Fall das von Hand geschriebene Original ist) nachschauen.

Erstellen von p44script-basierten Geräten

Um ein p44script-basiertes Gerät zu erstellen, verwenden Sie die Schaltfläche "+ Scripted" in der Weboberfläche des P44-xx. Sie können dann eine init-Message eingeben (Spezifikation unten), die dann sofort zum Anlegen eines Geräts verwendet wird.

Betrieb von p44script-implementierten Geräten

Das Gerät muss in ein Skript implementiert werden, das im Wesentlichen Folgendes tut

  • das Gerät initialisieren (Hardware einrichten, Parameter initialisieren usw.)

  • Wenn das Gerät Ausgänge hat, stellen Sie sicher, dass Sie einen Handler haben, der eingehende Messages verarbeitet, z.B:

on (message()) as m {
  // Message prüfen und auf Kanaländerungen usw. reagieren
  if (m.message="channel") {
    // ...aktualisieren Sie den Kanal in der Hardware
  }
}
  • Wenn das Gerät Taster, Eingänge oder Sensoren hat, stellen Sie sicher, dass Sie message(msg_to_send) verwenden, um dem System zu melden, wenn sich Eingänge ändern. Dies kann von einer permanent laufenden Hauptschleife aus geschehen (aber vergessen Sie nicht, genügend delay() einzubauen, um nicht zu viel CPU-Zeit zu verbrauchen und das gesamte Gerät zu verlangsamen!), oder von on() {...}-Handlern, die auf Eingangsereignissen oder regelmäßigem Timing basieren (z.B. mit der Funktion every()), zum Beispiel
on (every(0:05)) {
  // alle 5 Minuten, einen Sensor abfragen
  var s = getmysensorvalue()
  var m = { 'message': 'sensor', 'index':0 }
  m.value = s;
  message(m)
}
  • entweder weiterlaufen (z.B. in einer Schleife) oder true zurückgeben. Beachten Sie, dass die Rückgabe von true (oder "keep running") essentiell ist, da alle anderen Möglichkeiten, ein Skript zu beenden, als ein möglicherweise temporäres Problem behandelt wird, was bedeutet, dass das Skript neu gestartet wird. Nur wenn die Implementierungsskripte true zurückgeben, wird dies als OK-Signal behandelt, was bedeutet, dass das Gerät arbeiten kann, ohne dass ein Skript permanent läuft (d. h. nur über on(...) {}-Handler, die bei Bedarf einen Code auslösen)

Weitere Informationen finden Sie in den Beispielen.

Verwendung der externen Geräte-API über TCP-IP

Um externe Geräte zu hosten, muss vdcd mit der Option --externaldevices gestartet werden, wobei eine Port-Nummer oder ein absoluter Unix-Socket-Pfad für die Geräte-Implementationen angegeben werden muss, zu der eine Verbindung hergestellt werden soll. Aus Sicherheitsgründen wird empfohlen, die Skripte und Programme, die Geräte implementieren, auf demselben Gerät wie vdcd selbst auszuführen. Für Entwicklungszwecke kann jedoch die Befehlszeilenoption --externalnonlocal angegeben werden, um Geräte-API-Verbindungen von nicht-lokalen Clients zu ermöglichen.

Die plan44.ch Digital Strom-Produkte P44-DSB-xx und P44-DSB-xx unterstützen die externe Geräte-API ab der Version 1.5.0.8. Mehrere Geräte, die sich eine einzige Verbindung teilen, werden ab Version 1.5.2.0 unterstützt. 'Single devices" sind ab 1.6.0.2 unterstützt. Die externenal device API ist jedoch standardmäßig nur für P44-DSB-Geräte aktiv, die für "Testing"/Beta freigegeben sind (auf Anfrage erhältlich), oder für Geräte, bei denen userlevel auf 1 oder höher gesetzt ist (Standard für Produktionsgeräte ist 0, kann auf Anfrage über den Remote-Support auf 1 gesetzt werden). Im freien "P44-DSB-X" plan44.ch-Image für RaspberryPi ist die external device API immer aktiviert. Standardmäßig verwendet vdcd den Port 8999 für die external device API.

Betrieb von über TCP-IP angeschlossenen externen Geräten

Jede Implementationen eines externen Geräts muss

  • eine Verbindung zu dem TCP-Port oder Unix-Socket öffnen, der mit der vdcd-Kommandozeilenoption --externaldevices angegeben wurde (Standard ist Port 8999).
  • optional eine initvdc-Message senden, um Daten auf vdc-Ebene anzupassen (wie vdc-Modellname und Symbol)
  • eine init-Message senden, die die Eigenschaften des Geräts deklariert (Angabe von Ausgängen, Eingängen, Namen, Standard-Gruppenzugehörigkeit usw.). Die init-Message verwendet die JSON-Syntax. In einer Geräteimplementierung wird jedoch keine JSON-Unterstützung benötigt, da in der init-Message angegeben werden kann, dass ein extrem einfaches Textprotokoll für die Kommunikation über die init-Message selbst hinaus verwendet werden soll. Und die init-Message ist normalerweise eine konstante Zeichenkette, die mit jeder Programmiersprache einfach gesendet werden kann. (Beachten Sie, dass für Single Devices, die komplexe Aktionen und Ereignisse haben, und für einige erweiterte Funktionen wie Ausgangsübergangszeiten nur die JSON-Syntax unterstützt wird).
  • Geben Sie eine Schleife ein und warten Sie auf Messages vom vdcd, die Änderungen am Ausgangskanal anzeigen, oder senden Sie Message an den vdcd, die Änderungen am Eingang anzeigen.
  • Wenn die Verbindung geschlossen wird (aufgrund eines Fehlers oder wenn vdcd sie explizit schließt), sollte die Geräteimplementierung neu gestartet werden, siehe erster Aufzählungspunkt. Dies kann innerhalb der Geräteimplementierung selbst erreicht werden, oder indem man die Geräteimplementierung als Daemon unter der Kontrolle eines Daemon-Supervisors wie runit oder procd oder systemd laufen lässt, die Daemons neu starten, wenn sie beendet werden.
  • Ab Version 1.5.2.0 können mehrere Geräte auf derselben TCP-Verbindung angelegt werden. Um sie zu unterscheiden, muss jedem von ihnen in der init-Message ein tag zugewiesen werden, das dann in allen weiteren Messages an/von diesem Gerät verwendet werden muss/will.

Message-Format über TCP/IP

Messages bestehen aus Strings, die durch ein einzelnes LF-Zeichen (0x0A) getrennt sind. Die init-Message muss immer im JSON-Format sein. Weitere Messages sind entweder JSON oder einfache Text-Messages, abhängig von der protocol Option in der init-Message (siehe unten).

Initvdc-Message (nur für externe Geräte über TCP/IP)

Die optionale initvdc-Message kann von einer externen Geräteimplementierung gesendet werden, um einige vdc-globale Parameter zu setzen:

Feld Typ Beschreibung
message string identifiziert den Messagetyp, muss initvdc für die initvdc-Message sein
modelname optionale Zeichenfolge eine Zeichenfolge, die das vdc-Modell beschreibt. Dies wird vom dSS als "HW Info" angezeigt. Standardmäßig hat der vdc einen Modellnamen wie "P44-DSB-X external"
modelVersion optionale Zeichenkette eine Zeichenkette mit Versionsinformationen über das Hardwaregerät, das den Zugriff auf einen Gerätebus/ein Netzwerk wie eine KNX-Bridge regelt.
iconname optionale Zeichenkette eine Zeichenkette, die verwendet wird, um einen Dateinamen des anzuzeigenden Symbols für die vdc zu konstruieren.Standard für iconname ist "vdc_ext".
configurl optionale Zeichenkette eine URL, die im Kontextmenü des vdc im dSS-Konfigurator angezeigt wird (d. h. der Inhalt der vdc-Eigenschaft "configURL" in der vDC-API).Wenn nicht angegeben, wird dies standardmäßig die Standard-URL des vdchosts (falls vorhanden).
alwaysVisible optional boolesch wenn auf true gesetzt, meldet sich der vdc beim vDC-API-Client, auch wenn er (noch) keine Geräte enthält.
name optionaler String der Standardname, den der externe vDC im Digital Strom-System haben wird. Beachten Sie, dass dieser vom Benutzer über die dSS-Web-Oberfläche geändert werden kann.

Senden der Init-Message über TCP/IP

Die init-Message wird von einer externen Geräteimplementierung als erste Message nach dem Öffnen der Socket-Verbindung gesendet. Sie muss als ein einzeiliges JSON-Objekt formatiert werden.

Um mehrere Geräte zu initialisieren, die sich dieselbe Verbindung teilen, können mehrere init-Messages in einem JSON-Array zusammengefasst werden. Dies ist insbesondere erforderlich, um mehrere Geräte zu erstellen, die über die einfache Text-API kommunizieren sollen - denn nach der ersten Message wird das Protokoll auf einfachen Text umgestellt und würde keine weiteren JSON-Init-Messages zulassen.

Eine einfache Init-Message für einen Lichtdimmer könnte wie folgt aussehen (in einer einzigen Zeile):

{'message': 'init','protocol':'simple','output':'light','name':'ext dimmer','uniqueid':'myUniqueID1234'}

Eine init-Message für zwei Lichtdimmer an der gleichen Verbindung könnte so aussehen (in einer Zeile):

[{'message': 'init', 'tag':'A', 'protocol':'simple', 'output':'light', 'name':'ext dimmer A', 'uniqueid':'myUniqueID1234_A'}, {'message': 'init', 'tag':'B', 'protocol':'simple', 'output':'light', 'name':'ext dimmer B', 'uniqueid':'myUniqueID1234_B'}]

Weitere Informationen finden Sie in den Beispielen.

Externe Geräte-API-Spezifikation

Der Rest dieses Dokuments spezifiziert das externe Geräte-API-Protokoll und gilt sowohl für p44script-implementierte Geräte (bei denen Messages über die Funktion message() ausgetauscht werden) als auch für extern laufende Implenmentationen, die über TCP/IP kommunizieren.

Struktur der Init-Message

Die folgenden Tabellen beschreiben alle möglichen Felder des JSON-Objekts der init-Message:

Feld Typ Beschreibung
message string identifiziert den Messagetyp, muss init für die init-Message sein
protocol optionaler String Kann auf simple gesetzt werden, um das einfache Textprotokoll für die gesamte weitere Kommunikation über die init-Message hinaus zu verwenden. Wenn auf json (Standard) gesetzt, sind alle weiteren API-Kommunikationen JSON-Messages.
Hinweis: protocol kann nur in der ersten init-Message angegeben werden und wird ignoriert, wenn es in den nachfolgenden init-Messages vorhanden ist.
Hinweis: Single Devices (solche, die actions, events, properties oder states verwenden) müssen das JSON-Protokoll verwenden.
tag optionale Zeichenkette Wenn mehrere Geräte an der gleichen Verbindung erstellt werden, muss jedem Gerät ein tag zugewiesen werden. Das Tag darf kein '=' oder ':' enthalten. Das tag wird verwendet, um das Gerät in der weiteren Kommunikation zu identifizieren.
uniqueid String (optional für p44script-Geräte, erforderlich für externe API-Geräte) Dieser String ist optional für p44script-implementierte Geräte, aber erforderlich für externe API-Geräte. Um das Gerät global zu identifizieren, verwenden Sie eine UUID-Zeichenkette (XXXXXXXX-XXXXXX-XXXXXX-XXXXXXXXXXXXXXXX) oder eine gültige 34-stellige Digital Strom-dSUID. Um das Gerät eindeutig unter allen anderen Geräten in derselben vdcd zu identifizieren, verwenden Sie eine beliebige andere Zeichenkette. Ab Firmware 2.7: Wenn die uniqueid die Form einer URN wie schema:hardwareID hat, zeigt der dSS den Teil hardwareID an, der innerhalb des schema global eindeutig sein muss (als Beispiel könnte das Endgerät eine Mac-Adresse haben, dann wäre eine eindeutige ID in der Form macaddress:xx:xx:xx:xx:xx sinnvoll. Wenn das Gerät ein eigenes ID-Schema hat, wäre etwas wie "typeofid:xxxx" sinnvoll).
subdeviceindex optionale ganze Zahl Dies kann verwendet werden, um mehrere Geräte mit derselben Basis-dSUID zu erstellen (d. h. dieselbe eindeutige ID, die in der Init-Message übergeben wird), was für zusammengesetzte Geräte wie Fan-Coil-Einheiten empfohlen wird, die ein Heiz-/Kühl-Untergerät und ein Lüfter-Untergerät haben, oder für mehrere Tasten, die zu 2-Wege-Tasten kombiniert werden können.
colorclass optionale Ganzzahl definiert die Farbklasse des Geräts (wenn nicht angegeben, wird eine Standardfarbe von group und/oder output abgeleitet)
  • 1: gelb/hell
  • 2: Grau/Schatten
  • 3: Blau/Klima
  • 4: Cyan/Audio
  • 5: Magenta/Video
  • 6: Rot/Sicherheit
  • 7: Grün/Zugang
  • 8: Schwarz/Joker
  • 9: Weiß/Einzelgerät
group optionale Ganzzahl definiert die Gruppe des Geräteausgangs (wenn nicht angegeben, bestimmt der Typ output eine Standardgruppe)
  • 1: gelb/Licht,
  • 2: grau/Schatten
  • 3: blau/Heizung
  • 4: cyan/Audio
  • 5: magenta/Video
  • 6: rot/Sicherheit
  • 7: grün/Zugang
  • 8: schwarz/variabel
  • 9: blau/Kühlung
  • 10: blau/Lüftung
  • 11: blau/Fenster
  • 12: blau/Umluft
  • 48: Raumtemperaturregelung
  • 49: Raumlüftungsregelung
output optionaler String Definiert die Art des Ausgangs:
  • light: Dimmerausgang mit Lichtverhalten
  • colorlight: 6-Kanal Vollfarb-Licht (Helligkeit, Farbton, Sättigung, colortemp, cieX, cieY).
  • ctlight: 2-Kanal abstimmbares Weißlicht mit nur 2 Kanälen (Helligkeit, colortemp), die in der vDC-API offengelegt werden.
  • movinglight: Farblicht mit zusätzlichen X- und Y-Positionskanälen.
  • heatingvalve: 0..100% Heizungsventil.
  • ventilation: Gerät mit Luftstromintensität, Luftstromrichtung und Jalousiepositionskanälen, entsprechend der ds-ventilation Spezifikation. Siehe auch Feld kind.
  • fancoilunit: Gerät mit 0..100% Ventilatorausgangskanal, empfängt Soll- und aktuelle Raumtemperaturwerte über control-Message zur Regelung.
  • shadow: Gerät vom Typ Jalousie mit Positions- und Winkelkanal. Siehe auch Felder move und kind.
  • action: Nur für Einzelgeräte: Damit wird eine Szenentabelle mit Szenen erstellt, die ein Befehlsfeld haben, mit dem den Szenen Geräteaktionen zugewiesen werden können.
  • basic: einfacher/generischer Ausgang. Standardmäßig hat er einen Bereich von 0..100% und ist für das Ein- und Ausschalten konfiguriert, was z.B. für Relaisausgänge geeignet ist. Mit channelid kann eine eigene ID angegeben werden
    Wenn auch dimmed oder positional gesetzt ist, wird der basic Ausgang zu einem benutzerdefinierten Ausgang mit konfigurierbaren Eigenschaften:
    • min: Minimalwert (Standard=0)
    • max: Maximalwert (Standard=100)
    • resolution: Hardwareauflösung (Standard=1)
    • unit: Maßeinheit (Standard=keine)
    • channelname: benutzerdefinierter Kanalname (Standard=channelid)
Voreinstellung ist: kein Ausgang.
kind optionaler String für shadow und ventilation Ausgangstyp Definiert die Art des Geräts.
Für shadow:
  • roller: einfaches Rollo, keine Winkel
  • sun: Sonnenschutz
  • jalousie: Jalousie mit Lamellenwinkelsteuerung
Für ventilation:
  • ventilation: Zuluft/Abluft
  • recirculation: Luft(um)zirkulation innerhalb von Räumen
dimmable optional boolesch Hiermit kann der Betriebsmodus eines Geräts zwischen kontinuierlich dimmbar (true) oder ein/aus (false) eingestellt werden. Bitte beachten, dass dies nicht für alle Ausgangstypen sinnvoll ist. Alle Ausgangstypen haben eine Standardbetriebsart. Diese Option ist am sinnvollsten für den generischen Ausgangstyp basic
positional optional boolesch Mit dieser Option kann die Betriebsart eines Geräts auf positional gesetzt werden (ähnlich wie bei dimmbar, aber nicht zur Steuerung einer Intensität, sondern einer physischen Position, z. B. einer Jalousie, eines Fenstermotors usw.). Bitte beachten, dass dies nicht für alle Ausgangstypen sinnvoll ist. Alle Ausgangstypen haben eine Standardbetriebsart. Diese Option ist am sinnvollsten für den allgemeinen Ausgangstyp basic
endcontacts optionales Boolean für den Ausgangstyp shadow Wenn auf true gesetzt, muss die Geräteimplementierung das Erreichen der oberen und unteren Position melden, indem der Kanalwert auf 100 bzw. 0 aktualisiert wird (unter Verwendung der Message "channel"). Andernfalls verwendet das Shadow-Verhalten die Bewegungszeiteinstellungen, um die tatsächlichen Positionen allein aus dem Timing abzuleiten.
move optional boolesch Wenn auf true gesetzt, muss das Gerät die "move"- oder "MV"-Message (siehe unten) unterstützen, die vom Gerät ausgegeben wird, um eine Bewegung (Erhöhung, Verringerung) des Ausgangswertes zu starten oder zu stoppen. Die relative "move"-Semantik kann für jalousieartige Geräte nützlicher sein als absolute Kanalausgangswerte. Voreinstellung ist false (keine "move"-Semantik)
sync optional boolesch wenn auf true gesetzt, muss das Gerät die Message "sync" unterstützen und auf "sync" mit der Message "synced" antworten. "sync" wird vom vdcd ausgegeben, wenn er die aktuellen Ausgangswerte wissen muss (z. B. für eine saveScene-Operation). "synced" wird vom Gerät gesendet, wenn aktualisierte Ausgangskanalwerte an den vdcd gesendet wurden.Voreinstellung ist false (keine Ausgangswert-Sync-Anforderungen)
controlvalues optional boolean Wenn auf true gesetzt, werden Steuerwerte (z. B. Raumtemperatursoll- und -istwerte) mit der "control"/CTRL-Message an das externe Gerät weitergeleitet.
scenecommands optional boolean Wenn auf true gesetzt, sendet der vDC die "scenecommand"/SCMD-Message an Geräte für einige spezielle Szenenbefehle, die über das Ändern von Kanalwerten hinaus zusätzliche Semantik haben können.
groups optionales Array von Ganzzahlen kann verwendet werden, um die Zugehörigkeit zu einer oder mehreren Ausgangsgruppen explizite anzugeben. Dies überschreibt alle anderen aus colorclass, group und output abgeleitete Gruppenzugehörigkeit. Die Gruppennummern sind dieselben wie bei group, s. oben.
hardwarename optionale Zeichenkette eine Zeichenkette, die den Typ der Ausgangshardware beschreibt, z. B. "Dimmer" oder "Relais" usw. Standard ist die in output angegebene Zeichenkette.
modelname optionale Zeichenfolge eine Zeichenfolge, die das Gerätemodell beschreibt. Dies wird vom dSS als "HW Info" angezeigt.
modelversion optionale Zeichenkette eine Zeichenkette, die die Firmware-Version des Geräts beschreibt. Diese wird vom dSS als "Firmware Version" angezeigt. Wenn diese Zeichenkette leer ist, wird stattdessen die Softwareversion des vdc-Hosts verwendet (die die vdc-seitige Implementierungsversion des Geräts darstellt).
vendorname optionaler String der Herstellername
oemmodelguid optionaler String die GUID, die zur Identifikation von Geräten (insbesondere: Einzelgeräten) in der Digital Strom-Server-seitigen Datenbank verwendet wird, um erweiterte Informationen bereitzustellen. Üblicherweise ist dies eine GS1-formatierte GTIN wie:'gs1:(01)76543210123'
iconname optionale Zeichenkette eine Zeichenkette, die als Basis verwendet wird, um einen Dateinamen des anzuzeigenden Icons für das Gerät zu konstruieren. vdcd wird zuerst versuchen, ein Icon mit dem Namen "iconname_groupcolor" zu laden (wobei groupcolor die Farbe des Gerätes ist). Wenn eine solche Datei nicht existiert, versucht vdcd, "iconname_other" zu laden. Der Standardwert für iconname ist "ext" bei externen devices und "scpt" bei scripted devices.
configurl optionale Zeichenkette eine URL, die im Kontextmenü des Geräts im dSS-Konfigurator angezeigt wird (d. h. der Inhalt der Geräteeigenschaft "configURL" in der vDC-API).Wenn nicht angegeben, wird standardmäßig die Standard-URL des vdchost verwendet (falls vorhanden).
typeidentifier optionale Zeichenkette ein Bezeichner, der den (Hardware-Implementierungs-)Typ dieses Geräts angibt. Standardmäßig ist er einfach "extern". Dieser Bezeichner wird in Digital Strom nicht verwendet, aber er wird als "x-p44-deviceType" für die lokale Web-UI offengelegt, und er wird verwendet, um typspezifische Szenentabellen/Eigenschaften aus .csv-Dateien zu laden.
deviceclass optionale Zeichenkette eine Geräteklasse, die dazu dient, funktional gleichwertige Einzelgeräte (Waschmaschinen, Wasserkocher, Backöfen, etc.) zu gruppieren. Diese muss mit einer von Digital Strom definierten Geräteklasse übereinstimmen, und das Gerät muss die für diese Klasse angegebenen Aktionen/Zustände/Ereignisse/Eigenschaften bieten.
deviceclassversion optionale Ganzzahl eine Versionsnummer für die Geräteklasse.
name optionaler String der Standardname, den das Gerät im Digital Strom-System hat. Beachten Sie, dass dieser vom Benutzer über die dSS-Web-Oberfläche geändert werden kann.
buttons optionales Array von Objekten Definiert die Tasten des Geräts. Siehe Tabelle unten für Felder in den Tastenobjekten
inputs optionales Array von Objekten Definiert die Binäreingänge des Geräts. Felder in den Eingangsobjekten siehe Tabelle unten
sensors optionales Array von Objekten Definiert die Sensoren des Geräts. Felder in den Sensorobjekten siehe Tabelle unten
configurations optionales Objekt mit benannten Konfigurationen Definiert die für dieses Gerät möglichen Gerätekonfigurationen (z. B. Zwei-Wege-Taster vs. zwei separate Ein-Wege-Taster). Das Objekt configurations kann 1..n configuration-Objekte enthalten, siehe Tabelle unten
currentConfigId string Bei Geräten mit mehreren Konfigurationen (siehe oben) muss dieses Feld die ID der aktuellen Konfiguration enthalten.
actions optionales Objekt, das benannte Aktionen enthält Definiert die Geräteaktionen des Geräts (für 'Single Devices'). Das actions-Objekt kann 1..n action-Objekte enthalten, siehe Tabelle unten
dynamicactions optionales Objekt, das dynamische Aktionen nach ihrer ID enthält Definiert einen initialen Satz dynamischer Aktionen des Geräts (für 'Einzel'-Geräte). Das dynamicactions Objekt kann 1..n dynamicaction Objekte enthalten, siehe Tabelle unten. Beachten Sie, dass dynamische Aktionen (im Gegensatz zu normalen Aktionen) auch während des Gerätebetriebs mit der Message dynamicAction hinzugefügt, geändert und gelöscht werden können, siehe unten.
standardactions optionales Objekt, das Standard-Aktionen nach ihrer ID enthält Definiert die Standard-Aktionen des Geräts (für 'Single Devices'). Das standardactions Objekt kann 1..n standardaction Objekte enthalten, siehe Tabelle unten.
autoaddstandardactions optional boolean Wenn auf true gesetzt, wird automatisch eine Standardaktion für jede definierte action erstellt, wobei der Name der Aktion mit "std" vorangestellt wird.
noconfirmaction optionaler boolescher Wert Kann auf true gesetzt werden, wenn die Geräteimplementierung den Abschluss einer Aktion nicht bestätigen möchte
states optionales Objekt, das Zustände nach ihrer ID enthält Definiert die Zustände des Geräts (für 'Single Devices'). Das states Objekt kann 1..n state Objekte enthalten, siehe Tabelle unten
events optionales Objekt, das Ereignisse nach ihrer ID enthält Definiert die Ereignisse des Geräts (für 'Single Devices'). Das events Objekt kann 1..n event Objekte enthalten, siehe Tabelle unten
properties optionales Objekt, das Eigenschaften nach ihrer ID enthält Definiert die Geräteeigenschaften des Geräts (für 'Single Devices'). Das properties Objekt kann 1..n property Objekte enthalten, siehe Tabelle unten

Button-Objekt im Feld buttons der Init-Message

Feld Typ Beschreibung
id optionaler String string id, eindeutig innerhalb des Geräts, um die Schaltfläche über die vDC-API zu referenzieren.
buttonid optionale Ganzzahl Hinweis: Dieses Feld kann auch als "id " gesetzt werden für Abwärtskompatibilität mit früheren Versionen dieser API. Identifiziert die Hardwaretaste, zu der dieser Tasteneingang gehört. Bei Zwei- oder Mehrwegetasten gibt es mehrere Tastendefinitionen mit der gleichen "id". Der Standardwert ist 0.
buttontype optionale Ganzzahl Definiert den Typ der Taste:
  • 0: Art der Taste, die nicht durch die Gerätehardware definiert ist
  • 1: Einfachtaste
  • 2: Zwei-Wege-Taste oder -Wippe (Hinweis: Wenn Sie dies verwenden, muss die erste Taste das Abwärts-Element und die zweite Taste das Aufwärts-Element sein.
  • 3: 4-Wege-Navigationsknopf
  • 4: 4-Wege-Navigationsknopf mit Mitteltaste
  • 5: 8-Wege-Navigationsknopf mit Mitteltaste
  • 6: Ein-Aus-SchalterStandardwert ist 1 (einfacher Druckknopf)
element optionale Ganzzahl Legt fest, welches Element einer Mehrelementtaste durch diesen Tasteneingang repräsentiert wird:
  • 0: Mittelelement / Einzeltaste
  • 1: unten, für 2,4,8-Wege
  • 2: oben, für 2,4,8-Wege
  • 3: links, für 2,4,8-Wege
  • 4: rechts, für 2,4,8-Wege
  • 5: oben links, für 8-Wege
  • 6: unten links, für 8-Wege
  • 7: oben rechts, für 8-Wege
  • 8: unten rechts, für 8-WegeDefault ist 0 (einzelne Taste)
group optionale Ganzzahl definiert die Primärfarbe (Gruppe) der Taste:
  • 1: gelb/hell,
  • 2: grau/Schatten
  • 3: blau/Heizung
  • 4: cyan/Audio
  • 5: magenta/Video
  • 6: rot/Sicherheit
  • 7: grün/Zugang
  • 8: schwarz/variabel
  • 9: blau/Kühlung
  • 10: blau/Lüftung
  • 11: blau/Fenster
  • 48: RaumtemperaturregelungVorgabe ist die primäre Gerätegruppe
combinables optionale Ganzzahl wenn auf ein Vielfaches von 2 gesetzt, zeigt dies an, dass es weitere Geräte mit gleicher uniqueid aber unterschiedlichem subdeviceindex gibt, die zu Zweiwegetasten kombiniert werden können. In diesem Fall darf jedes der kombinierbaren Geräte nur eine einzige Taste haben, und der Subdeviceindex muss im Bereich n..n+combinable-1 liegen, wobei n=subdeviceindex MOD combinable
localbutton optional boolean Wenn auf true gesetzt, fungiert diese Taste als lokale Taste für das Gerät (schaltet und dimmt den Ausgang direkt)
hardwarename optionale Zeichenkette eine Zeichenkette, die das Tastenelement beschreibt, z. B. "auf" oder "ab" usw. Standard ist "button_idX_elY" wobei X die buttonid und Y das element ist

Input-Objekt im Feld inputs der Init-Message

Feld Typ Beschreibung
id optionaler String string id, eindeutig innerhalb des Geräts, um den Binäreingang über die vDC-API zu referenzieren.
inputtype optionale Ganzzahl Definiert den Typ des Eingangs:
  • 0: keine Systemfunktion
  • 1: Anwesenheit
  • 2: Licht
  • 3: Anwesenheit bei Dunkelheit
  • 4: Dämmerung
  • 5: Bewegung
  • 6: Bewegung bei Dunkelheit
  • 7: Rauch
  • 8: Wind
  • 9: Regen
  • 10: Sonneneinstrahlung (Sonnenlicht über Schwellenwert)
  • 11: Thermostat (Temperatur unter dem vom Benutzer eingestellten Schwellenwert)
  • 12: Gerät hat schwache Batterie
  • 13: Fenster ist geschlossen
  • 14: Tür ist geschlossen
  • 15: Fenstergriff (0=geschlossen, 1=offen, 2=gekippt)
  • 16: Garagentor ist geschlossen
  • 17: Schutz vor zu viel Sonnenlicht
  • 19: Heizsystem aktiviert
  • 20: Heizsystem umschalten
  • 21: noch nicht alle Funktionen bereit
  • 22: Störung/braucht Wartung; kann nicht betrieben werden
  • 23: braucht bald Service; momentan noch funktionsfähig
Standardwert ist 0 (keine Systemfunktion)
usage optionale Ganzzahl Definiert die Verwendung:
  • 0: undefiniert
  • 1: Raum (innen)
  • 2: außen
  • 3: Benutzerinteraktion
Standardwert ist 0 (undefiniert)
group optionale Ganzzahl definiert die primäre Farbe (Gruppe) des Eingangs:
  • 1: gelb/licht,
  • 2: grau/Schatten
  • 3: blau/Heizung
  • 4: cyan/Audio
  • 5: magenta/Video
  • 6: rot/Sicherheit
  • 7: grün/Zugang
  • 8: schwarz/JokerStandard ist die primäre Gerätegruppe
updateinterval optional double definiert das erwartete Aktualisierungsintervall dieses Eingangs, d. h. wie oft der aktuelle Zustand vom Gerät gemeldet wird. Der Standardwert ist 0, d. h. kein festes Intervall
alivesigninterval optional double legt fest, nach welcher Zeit ohne Aktualisierung des Eingangsstatus der Eingang als offline/ungültig betrachtet werden soll, in Sekunden. Standardwert ist 0 (bedeutet: keine garantierten Alive-Meldungen)
hardwarename optionaler String ein String, der den Eingang beschreibt, z. B. "Türkontakt" oder "Glasbruch" usw. Standard ist "input_tyX" wobei X der numerische inputtype ist

Sensor-Objekt im Feld sensors der Init-Message

Feld Typ Beschreibung
id optionaler String string id, eindeutig innerhalb des Geräts, um den Sensor über die vDC-API zu referenzieren.
sensortype optionale Ganzzahl Definiert den Typ des Sensors:
  • 0: undefiniert
  • 1: Temperatur in Grad Celsius
  • 2: relative Luftfeuchtigkeit in %
  • 3: Beleuchtungsstärke in Lux
  • 4: Höhe der Versorgungsspannung in Volt
  • 5: CO (Kohlenmonoxid)-Konzentration in ppm
  • 6: Radon-Aktivität in Bq/m
  • 7: Gasart Sensor
  • 8: Staub, Partikel <10µm in μg/m3
  • 9: Staub, Partikel <2.5µm in μg/m3
  • 10: Staub, Partikel <1µm in μg/m3
  • 11: Raumbediengerät Sollwert, 0..1
  • 12: Ventilatorgeschwindigkeit, 0.. 1 (0=aus, <0=auto)
  • 13: Windgeschwindigkeit in m/s
  • 14: Leistung in W
  • 15: Elektrischer Strom in A
  • 16: Energie in kWh
  • 17: Stromverbrauch in VA
  • 18: Luftdruck in hPa
  • 19: Windrichtung in Grad
  • 20: Schalldruckpegel in dB
  • 21: Niederschlag in mm/m2
  • 22: CO2 (Kohlendioxid)-Konzentration in ppm
  • 23: Böengeschwindigkeit in m/S
  • 24: Böenrichtung in Grad
  • 25: Erzeugte Leistung in W
  • 26: Erzeugte Energie in kWh
  • 27: Wassermenge in Litern
  • 28: Wasserdurchfluss in Litern/Minute
  • 29: Länge in Metern
  • 30: Masse in Gramm
  • 31: Zeit in Sekunden
  • 32: Wert in Prozent
  • 33: Geschwindigkeit in Prozent/Sek
Standardwert ist 0 (undefiniert)
usage optionale Ganzzahl Definiert die Verwendung:
  • 0: undefiniert
  • 1: Raum (drinnen)
  • 2: draußen
  • 3: Benutzerinteraktion
Standardwert ist 0 (undefiniert)
group optionale Ganzzahl definiert die primäre Farbe (Gruppe) des Sensors:
  • 1: gelb/licht,
  • 2: grau/Schatten
  • 3: blau/Heizung
  • 4: cyan/Audio
  • 5: magenta/Video
  • 6: rot/Sicherheit
  • 7: grün/Zugang
  • 0: schwarz/JokerVorgabe ist die primäre Gerätegruppe
updateinterval optional double definiert die zeitliche Präzision des Sensors, d. h. wie schnell er relevante Änderungen meldet. Für Sensoren mit einem regelmäßigen Polling-Mechanismus ist dies tatsächlich das erwartete Aktualisierungsintervall. Für Sensoren, die nur aktualisieren, wenn eine Änderung erkannt wird, gibt dies die zeitliche Genauigkeit der Aktualisierung an.Standardwert ist 5 Sekunden
alivesigninterval optional double definiert, nach welcher Zeit ohne Sensoraktualisierung der Sensor als offline/ungültig betrachtet werden soll, in Sekunden.Standardwert ist 0 (bedeutet: keine garantierten Alive-Meldungen)
changesonlyinterval optional double definiert das minimale Zeitintervall zwischen dem erneuten Melden desselben Sensorwerts, in Sekunden.Standardwert ist 5 Minuten (300 Sekunden)Beachten Sie, dass dieser Wert nur ein Standardwert ist, der für neue Geräte verwendet wird. Die vDC-API erlaubt es, diesen Wert später zu ändern.
hardwarename optionale Zeichenfolge eine Zeichenfolge, die den Sensor beschreibt, z. B. "Innentemperatur" oder "Wasserstand" usw. Standard ist "sensor_tyX" wobei X der numerische sensortype ist
min optional double minimaler Wert, Standardwert ist 0
max optional double maximaler Wert, Standardwert ist 100
resolution optional double Sensorauflösung, Standardwert ist 1

Action-Objekt im Feld actions der Init-Message

Feld Typ Beschreibung
description optionaler String Beschreibungstext (für Logs und Debugging) der Aktion
params optionales Objekt definiert die Parameter der Geräteaktion

Standardaction-Objekt im Feld standardactions der Init-Message

Feld Typ Beschreibung
action string Name der Aktion, auf der diese Standardaktion basiert
title optionaler String Titeltext für die Standardaktion
params optionales Objekt definiert die Parameter, die beim Aufruf von action verwendet werden sollen

Configuration-Objekt im Feld configurations der Init-Message

Feld Typ Beschreibung
id string Konfigurations-ID
description string Beschreibungstext für die Konfiguration

Dynamicaction-Objekt im Feld dynamicactions der init-Message und in der dynamicAction-Message

Feld Typ Beschreibung
title string Der Titel (geräteseitiger, benutzerspezifischer String in Benutzersprache) für die dynamische Aktion
description optionaler String Beschreibungstext (für Logs und Debugging) der Aktion
params optionales Objekt definiert die Parameter der Geräteaktion

State-Objekt im Feld states der Init-Message

Feld Typ Beschreibung
description optionaler String Beschreibungstext (für Logs und Debugging) des Zustands
type, siunit, min, max... fields Definition des Zustands, siehe Wertebeschreibungsfelder unten

Event-Objekt im Feld events der Init-Message

Feld Typ Beschreibung
description optionaler String Beschreibungstext (für Logs und Debugging) des Zustands
type, siunit, min, max... fields Definition des Zustands, siehe Wertebeschreibungsfelder unten

Property-Objekt im Feld properties der Init-Message

Feld Typ Beschreibung
readonly optional boolesch kann gesetzt werden, um die Eigenschaft schreibgeschützt zu machen (von der vDC-API-Seite - die Geräteimplementierung kann updateProperty verwenden, um den Wert zu aktualisieren/zu pushen)
type, siunit, min, max... Felder Definition der Eigenschaft, siehe Wertebeschreibungsfelder unten

Wertbeschreibungsfelder (für Aktionsparameter, Zustände, Eigenschaften)

Feld Typ Beschreibung
type String muss eines von "numeric", "integer", "boolean", "enumeration" oder "string" sein
siunit optionaler String definiert die SI-Einheit des numerischen Typs
default optionaler Double-Wert Standardwert je nach Typ (nicht bei Aufzählungen)
min optionaler Double-Wert Minimalwert für numerische und Integer-Typen
max optionaler Double-Wert Minimalwert für numerische und Integer-Typen
resolution optionaler Double-Wert Auflösung für numerische Typen
values Array von Strings mögliche Werte für Aufzählungstyp, Standardwert mit vorangestelltem Ausrufezeichen (!).

Messages von vdcd an Gerät(e)

vdcd sendet (abhängig von den in der init-Meldung gewählten Eigenschaften) die in der folgenden Tabelle aufgeführten Meldungen.

Wenn Geräte mit einem tag erstellt wurden (was erforderlich ist, wenn mehrere Geräte an einer einzigen Verbindung erstellt werden), enthalten alle JSON-Protokoll-Messages das Feld tag, und allen einfachen Textprotokoll-Messages wird tag plus ein Doppelpunkt vorangestellt.

JSON-Protokoll Einfaches Protokoll Beschreibung
{ 'message': 'status', 'status': s, 'errorcode':e, 'errormessage': m, 'errordomain':d, 'tag': t } OK
oder
`ERROR= m
Status für init message.If ok, s ist die Zeichenkette "ok" im JSON-Protokoll. m ist eine textuelle Fehlermeldung e ist der vdcd-interne Fehlercode d ist die vdcd-interne Fehlerdomäne t ist das Tag (nur vorhanden, wenn das Gerät mit einem Tag in der init-Message erstellt wurde)
{ 'message': 'channel','index': i ,'id':id ,'type':ty,'value': v, 'transition': ttime, 'dimming': dim, 'tag':t} C i = v
oder mit Tag:
t :C i = v
Ausgangskanalindex i hat seinen Wert auf v geändert.v ist ein Doppelwert. Die Geräteimplementierung sollte den neuen Kanalwert an den Ausgang des Geräts weiterleiten. Die JSON-Variante dieser Message meldet zusätzlich die Übergangszeit als ttime (in Sekunden), ein boolesches dim-Flag, das angibt, ob die Ausgangsänderung auf Dimmen zurückzuführen ist, den Namen/idstring des Kanals als id und den Kanaltyp als ty:
  • 0: undefiniert
  • 1: Helligkeit für Leuchten
  • 2: Farbton für farbige Leuchten
  • 3: Sättigung für farbige Leuchten
  • 4: Farbtemperatur für Leuchten mit variablem Weißpunkt
  • 5: X im CIE-Farbmodell für farbige Leuchten
  • 6: Y im CIE-Farbmodell für Farblichter
  • 7: Beschattungsposition (Jalousien, außen)
  • 8: Beschattungsposition (Vorhänge, innen)
  • 9: Beschattungswinkel (Jalousien, außen)
  • 10: Beschattungswinkel (Vorhänge, innen)
  • 11: Durchlässigkeit (Smart Glass)
  • 12: Luftstromintensität
  • 13: Luftstromrichtung (0=undefiniert, 1=Zufuhr/abwärts, 2=Abfuhr/aufwärts)
  • 14: Position der Luftstromklappe
  • 15: Position der Lüftungsjalousie
t ist das Tag (nur vorhanden, wenn das Gerät mit einem Tag in der init-Message erstellt wurde)
{ 'message': 'move', 'index': i, 'direction': d, 'tag': t } MV i = d
oder mit Tag:
t :MV i = d
Wenn die init-Message move=true angegeben hat, kann der vdcd das Starten oder Stoppen der Bewegung von Kanal i wie folgt anfordern:
  • 0: Bewegung stoppen
  • 1: Bewegung starten, um den Kanalwert zu erhöhen
  • -1: Bewegung starten, um den Kanalwert zu verringern
t ist das Tag (nur vorhanden, wenn das Gerät mit einem Tag in der init-Message erstellt wurde)
{ 'message': 'control', 'name': n, 'value':v, 'tag': t } CTRL. n = v
oder mit Tag:
t :CTRL. n = v
Wenn in der init-Message controlvalues=true angegeben wurde, leitet der vdcd die für das Gerät empfangenen Steuerwerte weiter. n ist der Name des Steuerwerts (z. B. "heatingLevel", "TemperatureZone", "TemperatureSetPoint" usw.) v ist ein Doppelwert t ist das Tag (nur vorhanden, wenn das Gerät mit einem Tag in der init-Message erstellt wurde)
{ 'message': 'sync', 'tag': t } SYNC
oder mit Tag:
t :SYNC
Wenn die init-Message sync=true angegeben hat, kann der vdcd die Aktualisierung der Ausgangskanalwerte durch Senden von sync anfordern. Es wird erwartet, dass das Gerät die Kanalwerte aktualisiert (unter Verwendung der "channel"/"C"-Message, siehe unten) und dann die synced-Message sendet. Hinweis: Das Gerät kann auch selbst eine Reihe von Kanalaktualisierungen ankündigen, indem es sync sendet, siehe unten. t ist das Tag (nur vorhanden, wenn das Gerät mit einem Tag in der init-Message erstellt wurde)
{ 'message': 'scenecommand', 'cmd': c, 'tag': t } SCMD=c
oder mit Tag:
t :SCMD= c
Wenn in der init-Message scenecommands=true angegeben wurde, sendet der vdcd diese Message für einige "spezielle" Szenenaufrufe, da die Semantik aller Szenenaufrufe nicht vollständig durch Kanalwertänderungen allein dargestellt werden kann. Derzeit kann c einer der folgenden Werte sein:
  • OFF
  • SLOW_OFF
  • MIN
  • MAX
  • INC
  • DEC
  • STOP
  • CLIMATE_ENABLE
  • CLIMATE_DISABLE
  • CLIMATE_HEATING
  • CLIMATE_COOLING
  • CLIMATE_PASSIVE_COOLING
Hinweis dass in den meisten Fällen die Szenenbefehle bereits auf der vDC-Ebene in Kanalwertänderungen übersetzt werden (z. z. B. MIN, MAX), so dass es in der Regel nicht notwendig ist, etwas auf der Geräteebene zu tun. STOP ist eine bemerkenswerte Ausnahme für Geräte, die viel Zeit benötigen, um Werte zu übernehmen (z. B. Jalousien). Diese sollten auf den STOPP-Szenenbefehl reagieren, indem sie die Bewegung sofort stoppen und dann die Istposition über "Kanal"/C-Messages zurücksynchronisieren.

Operationen, die sich auf mehrere Gerätekonfigurationen beziehen, sind nur im JSON-Protokoll wie folgt verfügbar:

JSON-Protokoll Beschreibung
{ 'message': 'setConfiguration', 'id': configid , 'tag': t } Das Gerät wird zu der Konfiguration angefordert, die durch die ID configid identifiziert wird. Die Geräteimplementierung MUSS alle von der Konfigurationsänderung betroffenen Geräte trennen (unter Verwendung der Message bye) und dann das/die Gerät(e) mit neuen init-Messages wieder verbinden, die die neue Konfiguration (Anzahl der Tasten, Sensoren usw.) beschreiben und configid im Feld currentConfigId enthalten.

Operationen, die sich auf 'Single Devices' beziehen, sind nur im JSON-Protokoll wie folgt verfügbar:

JSON-Protokoll Beschreibung
{ 'message': 'invokeAction', 'action': a, 'params': p, 'tag': t } Die Aktion a wurde mit den Parametern p aufgerufen. Die Geräteimplementierung muss die Aktion ausführen und anschließend eine confirmAction-Message zurückgeben (es sei denn, das Bestätigen von Aktionen ist durch Einfügen des Feldes noconfirmaction in der init-Message deaktiviert) t ist das Tag (nur vorhanden, wenn das Gerät mit einem Tag in der init-\Message erstellt wurde)
{ 'message': 'setProperty', 'property': p, 'value': v, 'tag': t } Die Eigenschaft p wurde auf den Wert v geändert. Die Geräteimplementierung sollte ihren internen Wert für diese Eigenschaft aktualisieren.

Messages von Gerät(en) an vdcd

Das/die Gerät(e) kann/können (je nach den in der init-Meldung gewählten Eigenschaften) die in der folgenden Tabelle aufgeführten Meldungen senden.

Wenn Geräte mit einem tag erstellt wurden (was erforderlich ist, wenn mehrere Geräte an einer einzigen Verbindung erstellt werden), müssen alle JSON-Protokoll-Messages das Feld tag enthalten, und allen einfachen Textprotokoll-Messages muss tag plus ein Doppelpunkt vorangestellt werden, um das Gerät zu identifizieren.

JSON-Protokoll Einfaches Protokoll Beschreibung
{ 'message': 'bye', 'tag': t } BYE
oder mit Tag:
t :BYE
Das Gerät kann diese Message senden, um die Verbindung zum vdcd zu trennen, z. B. wenn es feststellt, dass seine Hardware nicht mehr erreichbar ist. Einfaches Schließen der Socket-Verbindung hat den gleichen Effekt wie das Senden von bye (im Falle mehrerer getaggter Geräte ist das Schließen des Sockets wie das Senden von bye an jedes Gerät) t ist das Tag (wird nur benötigt, wenn das Gerät mit einem Tag in der init-Message erstellt wurde)
{ 'message': 'log', 'level': n , 'text':logmessage, 'tag': t } L n = logmessage
oder mit tag:
t :L n = logmessage
Das Gerät kann eine logmessage an das vdcd-Log senden. n ist der Log-Level (standardmäßig werden Level über 5 nicht im Log angezeigt - 7=debug, 6=info, 5=notice, 4=warning, 3=error, 2=critical, 1=alert, 0=emergency) t ist das Tag (wird nur benötigt, wenn das Gerät mit einem Tag in der init-Message erstellt wurde)
{ 'message': 'channel', 'index': i, 'type': ty ,'id':id, 'value': v ,'tag':t} C i = v
oder mit Tag:
t :C i = v
Das Gerät sollte diese Message senden, wenn sein Ausgangskanal mit dem Index i (oder mit dem Namen id oder mit dem Typ ty , siehe unten) seinen Wert auf v aus einem anderen Grund als dem Empfang einer channel-Message geändert hat (z. B. nach der Initialisierung oder bei Geräten, die direkt gesteuert werden können). Geräte, die Ausgangsänderungen nicht sofort erkennen können, können in der init-Message sync=true angeben, so dass der vdcd die Aktualisierung der Ausgangskanalwerte durch Senden von sync nur dann anfordert, wenn diese Werte tatsächlich benötigt werden.Die JSON-Variante dieser Message erlaubt zusätzlich die Auswahl des Kanals nach Name/idstring id oder Typ ty (anstelle des Index i ). t ist das Tag (wird nur benötigt, wenn das Gerät mit einem Tag in der init-Message erstellt wurde)
{ 'message': 'channel_progress', 'index': i, 'type': ty ,'id':id, 'value': v , 'tag':t} P i = v
oder mit Tag:
t :P i = v
Das Gerät kann diese Nachricht optional senden, um den Fortschritt eines Hardware-Übergangs (z. B. einer fahrenden Jalousie) für seinen Ausgangskanal mit Index i (oder mit dem Namen id oder dem Typ ty , siehe unten) zu melden. Die JSON-Variante dieser Nachricht ermöglicht zusätzlich die Auswahl des Kanals nach Name/idstring id oder Typ ty (anstelle von Index i ). t ist der Tag (nur erforderlich, wenn das Gerät mit einem Tag in der init-Nachricht erstellt wurde)
{ 'message': 'button', 'index': i, 'id':id, 'value': v, 'tag':t} B i = v
oder mit Tag:
t :B i = v
Das Gerät soll diese Message senden, wenn sich der Zustand seiner Taste am Index i (oder mit dem Namen id , siehe unten) geändert hat. Wenn die Taste gedrückt wurde, muss v auf 1 gesetzt werden, wenn die Taste losgelassen wurde, muss v auf 0 gesetzt werden.
Um einen Tastendruck+Loslassen mit einer einzigen Message zu simulieren, setzen Sie v auf die Druckdauer in Millisekunden.
Um direkt einen einfachen, doppel- dreifach- oder vierfachclick zu simulieren, kann für v -1, -2, -3, oder -4 übergeben werden, sowie -11 für den Beginn des Gedrückthaltens der Taste und -10 für das Loslassen der Taste. Beachten Sie, dass direkte Klicks (negative Werte) und die Meldung des Tastenzustands (positive Werte) nicht für dieselbe Taste gemischt verwendet werden sollten!
t ist das Tag (wird nur benötigt, wenn das Gerät mit einem Tag in der init-Message erstellt wurde)Die JSON-Variante dieser Message ermöglicht die Auswahl der Taste über den Namen/idstring id (anstelle des Index i ).
{ 'message': 'input','index': i , 'id':id,'value': v, 'tag':t } I i = v
oder mit tag:
t :I i = v
Das Gerät sollte diese Message senden, wenn sich der Zustand seines Eingangs bei Index i (oder namens id , siehe unten) geändert hat. Wenn der Eingang auf aktiv gewechselt hat, muss v auf 1 gesetzt werden, wenn der Eingang auf inaktiv gewechselt hat, muss v auf 0 gesetzt werden. Um explizit zu signalisieren, dass der Wert zu diesem Zeitpunkt unbekannt/nicht verfügbar ist, setzen Sie v auf den String undefined (simple) oder auf den NULL-Wert (JSON). t ist der Tag (wird nur benötigt, wenn das Gerät mit einem Tag in der init-Meldung erstellt wurde). Die JSON-Variante dieser Meldung ermöglicht die Auswahl des Eingangs über den Namen/idstring id (anstelle des Index i ).
{ 'message': 'sensor', 'index': i, 'id':id, 'value': v , 'tag':t } S i = v
oder mit tag:
t :S i = v
Das Gerät sollte diese Message senden, wenn sich der Wert seines Sensors bei Index i (oder mit dem Namen id , siehe unten) geändert hat. v ist der neue Wert (double) und sollte innerhalb des mit min und max in der init-Message angegebenen Bereichs liegen. Um explizit zu signalisieren, dass der Wert zu diesem Zeitpunkt unbekannt/nicht verfügbar ist, setzen Sie v auf den String undefined (simple) oder auf den NULL-Wert (JSON). t ist das Tag (wird nur benötigt, wenn das Gerät mit einem Tag in der init-Meldung erstellt wurde). Die JSON-Variante dieser Meldung ermöglicht die Auswahl des Sensors über den Namen/idstring id (anstelle des Index i ).
{ 'message': 'sync', 'tag': t } SYNC
oder mit Tag:
t:SYNC
Das Gerät kann diese Message senden, um anzukündigen, dass es die Werte mehrerer Ausgangskanäle aktualisieren und die Aktualisierung durch Senden von synced abschließen wird. t ist das Tag (nur erforderlich, wenn das Gerät mit einem Tag in der init Nachricht erstellt wurde)
{ 'message': 'synced', 'tag': t } SYNCED
oder mit Tag:
t :SYNCED
Das Gerät muss diese Message senden, nachdem es sync empfangen und die Ausgangskanalwerte aktualisiert hat. t ist das Tag (wird nur benötigt, wenn das Gerät mit einem Tag in der init-Message erstellt wurde)

Einige speziellere Operationen, z.B. die, die sich auf 'Single Devices' beziehen, sind nur im JSON-Protokoll wie folgt verfügbar:

JSON-Protokoll Beschreibung
{ 'message': 'opstate', 'level': lvl , 'text':txt } Setzt den operation state (Betriebszustand) des Geräts. lvl ist der "Gesundheits"-Level, von -1 (unbekannt) über 0 (schlecht) bis 100 (perfekt). txt ist ein kurzes Stichwort zum Betriebszustand, wie z.B. "Low Bat". Es kann auch nur eine der beiden Informationen angegeben werden. t ist das Tag (nur vorhanden, wenn das Gerät mit einem Tag in der init-Message erstellt wurde)
{ 'message': 'channel_config', 'index': i, 'type': ty ,'id':id, 'min': min, 'max': max , 'tag':t} Das Gerät kann diese Nachricht optional senden, um dynamisch min/max Werte für den Ausgabekanal mit dem Index i, oder mit dem Namen id oder dem Typ ty zu konfigurieren. Bitte beachten - der Ausgang muss vom Typ basic und dimmbar oder positional sein, damit er konfiguriert werden kann. t ist der Tag (nur erforderlich, wenn das Gerät mit einem Tag in der init Nachricht erstellt wurde)
{ 'message': 'confirmAction', 'action': a , 'errorcode':ec, 'errortext': et , 'tag':t } Sofern das Bestätigen von Aktionen nicht durch Einfügen des Feldes noconfirmaction in der init-Message deaktiviert ist, muss das Gerät diese Message senden, um die Ausführung (oder den Misserfolg) der zuvor aufgerufenen Aktion a zu bestätigen. Es kann einen Statuscode in ec zurückgeben, der 0 für eine erfolgreiche Ausführung oder ein anderer Wert sein muss, der einen Fehler anzeigt. et kann verwendet werden, um einen Fehlertext zu liefern. t ist das Tag (nur vorhanden, wenn das Gerät mit einem Tag in der init-Message erstellt wurde)
{ 'message': 'updateProperty', 'property': p, 'value':v,'push':push,'tag': t } Das Gerät kann diese Message senden, um den Wert v der Eigenschaft p zu aktualisieren, wie aus der vdc-API ersichtlich ist.Wenn der optionale boolesche Wert push gesetzt ist, wird die Änderung der Eigenschaft auch stromaufwärts gepusht.Beachten Sie, dass es möglich ist, nur den aktuellen Eigenschaftswert zu pushen, ohne den Wert zu ändern, indem value weggelassen und nur push angegeben wird. t ist das Tag (nur vorhanden, wenn das Gerät mit einem Tag in der init-Message erstellt wurde)
{ 'message': 'pushNotification', 'statechange':{ s:v }, 'events':[e1,e2,...], 'tag': t } Das Feld statechange ist ein optionales Objekt, das einem Zustand s einen neuen Wert v zuordnet, das Feld events ist ein optionales Array von Ereignis-IDs ( e1,e2,... ), die zusammen mit der Zustandsänderung gepusht werden sollen (oder für sich selbst, wenn das Feld statechange fehlt). t ist das Tag (nur vorhanden, wenn das Gerät mit einem Tag in der init-Message erstellt wurde)
{ 'message': 'dynamicAction', 'changes': { id:actiondesc, ... }, 'tag': t } Das Gerät kann diese Message verwenden, um dynamische Aktionen hinzuzufügen, zu ändern oder zu entfernen, während das Gerät bereits in Betrieb ist.Das Feld changes ist ein JSON-Objekt, das eine oder mehrere Aktionen enthält, die durch ihre id identifiziert und durch eine actiondesc beschrieben werden (gleiches Format wie dynamicAction in der init-Message, siehe oben). Wenn eine dynamische Aktion entfernt werden soll, übergeben Sie null für actiondesc. t ist das Tag (nur vorhanden, wenn das Gerät mit einem Tag in der init-Message erstellt wurde)