VEAP Dienste

Beschreibung der VEAP-Dienste/REST-API

Für den Zugriff auf die Datenpunkte wird das Very Easy Automation Protocol vom CCU-Jack implementiert.

Mit dem Kommandozeilenwerkzeug CURL, das praktisch für alle Betriebssysteme und Plattformen verfügbar ist, können alle VEAP-Dienste (z.B. Datenpunkte lesen und setzen) des CCU-Jacks genutzt werden. Die Beschreibung ist auf einer eigenen Seite zu finden.

Die Abbildung der CCU-Datentypen auf JSON ist ebenfalls auf einer eigenen Seite zu finden.

Vereinfachter Zugriff

Für HTTP-Clients mit eingeschränkter Funktionalität, werden zusätzlich folgende Vereinfachungen unterstützt:

Das Schreiben eines Datenpunktes kann zusätzlich durch ein HTTP-GET mit dem URL-Parameter writepv erfolgen.

Beispiele:

Die nötigen Datenpunktadressen können über den Navigator des CCU-Jacks ermittelt werden.

GET /number_datapoint/~pv?writepv=123.456
GET /boolean_datapoint/~pv?writepv=true
GET /string_datapoint/~pv?writepv="ABC+abc"

(Hinweis: In URL-Parametern das Pluszeichen für ein Leerzeichen verwenden.)

Zudem kann der aktuelle Datenpunktwert als reiner Text abgefragt werden, sodass eine Dekodierung von JSON nicht mehr nötig ist. Der Zeitstempel und der Status werden in diesem Fall nicht zurückgegeben.

Beispiele:

Anfrage	Ergebnis
GET /number_datapoint/~pv?format=simple	123.456
GET /boolean_datapoint/~pv?format=simple	true
GET /string_datapoint/~pv?format=simple	ABC abc

ExgData-Dienst

(ab V2.2.0)

Mit Hilfe des ExgData-Dienstes ("exchange data") ist es möglich mehrere Anfragen zum Setzen und Lesen von Datenpunkten zu bündeln. Der Dienst ist unter dem Pfad /~exgdata mit der HTTP-Methode PUT erreichbar.

Die Parameter für den ExgData-Dienst werden als JSON-Objekt übergeben. Es können beliebig viele (auch 0) Datenpunkte gesetzt werden, und beliebig viele (auch 0) andere oder die gleichen Datenpunkte gelesen werden. Das Setzen wird als erstes ausgeführt, danach erfolgt das Lesen. Der Prozesswert ist im VEAP-Protokoll beschrieben. Der Aufbau insgesamt ist aus folgender Beispiel-Anfrage ersichtlich:

Beispiel-Anfrage:

HTTP PUT /~exgdata
{
    "writePVs": [
        {
            "path": "/sysvar/9215",
            "pv": {
                "v": 300.0
            }
        },
        {
            "path": "/invalid",
            "pv": {
                "v": 42
            }
        },
        {
            "path": "/sysvar/9375",
            "pv": {
                "v": "invalid"
            }
        },
        {
            "path": "/device/000xxxxxxxxxxx/3/STATE",
            "pv": {
                "v": true,
                "t": 1653076800000,
                "s": 0
            }
        }
    ],
    "readPaths": [
        "/virtdev/JACK000003/7/VOLTAGE",
        "/sysvar/9215",
        "/invalid",
        "/",
        "/~vendor/statistics/responseBytes/"
    ]
}

Exakt zu jedem Schreibeintrag und zu jedem Leseeintrag in der Anfrage enthält die Antwort ein Ergebnis.

Ein erfolgreiches Schreiben eines Eintrags wird durch eine null signalisiert. Im Fehlerfall wird ein Fehlerobjekt mit den Eigenschaften code und optional message zurückgegeben. code enthält den HTTP-Statuscode der entsprechenden Einzelabfrage (s.a. Signalisierung von Fehlern im VEAP-Protokoll).

Ein erfolgreiches Lesen liefert ein JSON-Objekt mit der Eigenschaft pv mit dem Prozesswert zurück. Im Fehlerfall enthält das Objekt die Eigenschaft error mit einem Fehlerobjekt. Das Fehlerobjekt enthält wieder die Eigenschaften code und optional message.

Beispiel-Antwort:

{
    "writeErrors": [
        null,
        {
            "code": 404,
            "message": "Item not found at /: invalid"
        },
        {
            "code": 500,
            "message": "Writing of object 9375 failed: Invalid type for BOOL/ALARM/ACTION: \"invalid\""
        },
        null
    ],
    "readResults": [
        {
            "pv": {
                "ts": 1653076860000,
                "v": 18.57,
                "s": 0
            }
        },
        {
            "pv": {
                "ts": 1653076860000,
                "v": 300,
                "s": 0
            }
        },
        {
            "error": {
                "code": 404,
                "message": "Item not found at /: invalid"
            }
        },
        {
            "error": {
                "code": 405,
                "message": "Reading PV not supported: /"
            }
        },
        {
            "pv": {
                "ts": 1653076860000,
                "v": 174433,
                "s": 0
            }
        }
    ]
}

Query-Dienst

(ab V2.4.0)

Mit Hilfe des Query-Dienstes ist es möglich VEAP-Objekte anhand von Pfadmasken zu suchen. Der Dienst ist unter dem Pfad /~query mit der HTTP-Methode GET erreichbar. Mit dem URL-Parameter ~path wird die Pfadsuchmaske angegeben. Dieser Parameter kann ein- oder mehrfach vorkommen. Groß- und Kleinschreibung sind relevant bei der Suche. Die besondere Bedeutung von Zeichen (z.B. *) kann mit einem rückwärtigen Schrägstrich \ genommen werden, z.B. \* such nach einem *.

Folgende Platzhalter sind in der Pfadsuchmaske zulässig:

Platzhalter	Bedeutung
*	Eine beliebige Anzahl von beliebigen Zeichen (außer /)
?	Ein beliebiges Zeichen (außer /)
[ Zeichenbereich ]	Ein Zeichen aus dem Zeichenbereich

In Zeichenbereichen können einzelne Zeichen angegeben werden (z.B. [ABC]) oder Von-Bis-Bereiche (z.B: [A-C]). Ein Zeichenbereich kann auch umgekehrt werden (z.B. [^A]). Dann treffen alle Zeichen zu, die nicht im Zeichenbereich angegeben sind.

Beispiele:

URL-Parameter	Bedeutung
/~query?~path=/device/*	Alle Geräte der CCU auflisten.
/~query?~path=/device/*&~path=/virtdev/*	Alle Geräte der CCU und die virtuellen des CCU-Jacks auflisten.
/~query?~path=/device/*&~path=/device/*/*	Alle Geräte und Kanäle der CCU auflisten.
/~query?~path=/device/*/*/BRIGHTNESS	Alle BRIGHTNESS-Datenpunkte aller Geräte der CCU auflisten.
/~query?~path=/device/\**	Alle Geräte, deren Seriennummern mit * beginnen (z.B. Gruppen), auflisten.
/~query?~path=/device/[0-9]*	Alle Geräte, deren Seriennummern mit einer Zahl beginnen (z.B. HmIP-Geräte), auflisten.

Die Rückgabe ist ein JSON-Array mit den gefundenen Objekten. Zu jedem Objekt wird die Eigenschaft ~path hinzugefügt, die die Objektadresse enthält.

Beispiel-Rückgabe:

[
  {
    "control": "",
    "default": 0,
    "flags": 1,
    "id": "BRIGHTNESS",
    "identifier": "BRIGHTNESS",
    "maximum": 255,
    "minimum": 0,
    "mqttStatusTopic": "device/status/GEQxxxxxx/1/BRIGHTNESS",
    "operations": 5,
    "special": [],
    "tabOrder": 0,
    "title": "Bewegung Garage - BRIGHTNESS",
    "type": "INTEGER",
    "unit": "",
    "~links": [
      {
        "rel": "channel",
        "href": "..",
        "title": "Bewegung Garage"
      },
      {
        "rel": "~service",
        "href": "~pv",
        "title": "PV Service"
      }
    ],
    "~path": "/device/GEQxxxxxx/1/BRIGHTNESS"
  },
  ...
]