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

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:

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:

Button-Objekt im Feld buttons der Init-Message

Input-Objekt im Feld inputs der Init-Message

Sensor-Objekt im Feld sensors der Init-Message

Action-Objekt im Feld actions der Init-Message

Standardaction-Objekt im Feld standardactions der Init-Message

Configuration-Objekt im Feld configurations der Init-Message

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

State-Objekt im Feld states der Init-Message

Event-Objekt im Feld events der Init-Message

Property-Objekt im Feld properties der Init-Message

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

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.

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

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

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.

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