Dokumentation HomeServer URL-Endpoints (HTTP/WebSocket)
Zurück / Vor | Suchen | Hilfe / Dokumentation HomeServer URL-Endpoints (HTTP/WebSocket)
Inhalt
1.
Einleitung
2.
Authentifizierung
3.
Startverhalten
4.
Voraussetzungen
5.
Überblick
5.1.
Unterstützte HS-Objekte
5.2.
Metadaten
5.3.
Benutzerrechte
5.4.
Objektschlüssel
5.5.
Statuscodes
5.6.
Zugriffsmöglichkeiten auf Endpoints
6.
Zugriff über HTTPS
6.1.
Authentifizierung
6.2.
Kommunikation/Nachrichten zwischen HS/FS und Client
7.
Zugriff über Websocket
7.1.
Verbindungsaufbau
7.2.
Authentifizierung
7.3.
Kommunikation/Nachrichten zwischen HS/FS und Client
8.
HS-Objekte
8.1.
Datenarchive
8.2.
Kameraarchive
8.3.
Kameras
8.4.
Kommunikationsobjekte
8.5.
Meldungsarchive
8.6.
Sequenzen
8.7.
Szenen
8.8.
Universal-Zeitschaltuhren
8.9.
Urlaubskalender
Hinweis
Zur erleichterten Nutzung der URLEndpoints Schnittstelle liegt die JavaScript API vor. Diese ist gesondert dokumentiert und eignet sich für alle, die die URLEndpoints Schnittstelle per JavaScript (also z.B. per Anwendung im Browser/App) nutzen möchten.

1.Einleitung

HS-Objekte (HomeServer-Objekte) können über eine URL per HTTPS-Aufruf abgerufen bzw. verändert werden. Jedes HS-Objekt bekommt dazu einen eindeutigen Schlüssel (ID) im Experten zugewiesen.
Als Alternative zum Zugriff über HTTPS stehen die HS-Objekte ebenfalls über eine Verbindung per WebSocket (WS) zur Verfügung. Bei dieser Verbindung können auch alle HS-Objekte, außer Kameras, abonniert werden.

2.Authentifizierung

Die Authentifizierung findet per HTTP-Authentifizierung (Basic Authentication) statt. Schlägt die Authentifizierung fehl, findet kein Aufbau einer stehenden Verbindung statt und der HS/FS antwortet mit Statuscode 403 (Forbidden). Ist die Anfrage nicht vollständig, antwortet der HS/FS mit Statuscode 400 (Bad Request).
Nach fehlgeschlagener Authentifizierung ist die IP-Adresse des Clients für 5 Sekunden gesperrt. In dieser Zeit liefert das Gerät auf Anfragen immer den Statuscode 503 zurück.

3.Startverhalten

Wenn das Gerät startet, ist der HTTP-Server bereits vor Abschluss der Initialisierung verfügbar. In dieser Zeit liefert das Gerät den Statuscode 503 auf alle Anfragen. Zusätzlich enthält die Antwort den HTTP-Header "Retry-After". Der Client sollte dieses Feld auswerten und nach der angegebenen Zeit in Sekunden einen erneuten Versuch starten.

4.Voraussetzungen

Die Voraussetzungen für die Nutzung der URL-Endpoints sind:
  • HomeServer/FacilityServer ab Firmware Version 4.7
  • HS/FS-Experte ab Version 4.7

5.Überblick

5.1.Unterstützte HS-Objekte

Die folgenden HS-Objekte werden durch URL-Endpoints (HTTPS/WebSocket) unterstützt:

5.2.Metadaten

Zu jedem HS-Objekt können Metadaten abgefragt werden. Diese enthalten Informationen zum jeweiligen HS-Objekt. Die verfügbaren Metadaten hängen vom jeweiligen Typ des HS-Objekts ab.

Folgende Metadaten stehen bei allen Objekten zur Verfügung:
  • ID: Innerhalb des Objekttyps eindeutige ID.
  • interne ID: eindeutiger Schlüssel, wird im HS/FS-Experte automatisch vergeben.
  • Bezeichnung: Die Bezeichnung des Objekts.
  • Beschreibung (optional): Eine detaillierte Beschreibung des jeweiligen Objekts.
  • Tags (optional): Eine durch Kommata getrennte Liste von Schlüsselwörtern.
Die oben aufgeführten Metadaten werden im HS/FS-Experte konfiguriert.
Die interne ID ist im Experten nicht sicht- und änderbar. Bei der Metadatenabfrage wird diese mitgeliefert.

Weiterhin kann jedes HS-Objekt zusätzliche spezifische Metadaten besitzen.

5.3.Benutzerrechte

Der Zugriff auf die Endpunkte wird in der Benutzerverwaltung des HS/FS-Experte benutzerspezifisch konfiguriert. Die Rechte werden für "lesen" und "schreiben" separat vergeben. Es stehen jeweils 16 Gruppen zur Verfügung.

5.4.Objektschlüssel

Um identifizierbar zu sein, verfügt jedes HS-Objekt über zwei eindeutige Objektschlüssel (ID und interne ID). Die ID besteht aus einem Präfix, der den Objekttyp definiert, und einer innerhalb des Objekttyps eindeutigen Objekt-ID.

5.4.1.Präfix

Das Präfix für jeden Objekt-Typ (nicht änderbar) festgelegt. Er besteht aus einem Kürzel aus zwei Buchstaben.

5.4.2.ID

Die ID kann im HS/FS-Experte für das jeweilige Objekt festgelegt werden.
Groß-/Klein-Schreibung wird ignoriert.
Bei Verwendung als Objektschlüssel muss sie an den von einem '@'-Zeichen gefolgten Präfix angehängt werden.

5.4.3.Interne ID

Die interne ID wird automatisch vergeben, ist eine Nummer und kann nicht geändert werden. Bei Verwendung als Objektschlüssel muss sie an den von einem ':' (Doppelpunkt) gefolgten Präfix angehängt werden.

5.4.4.Beispiel

Ein Kommunikationsobjekt (Präfix CO) mit der ID 1_1_1 und der internen ID 47 kann über folgende zwei Objektschlüssel angesprochen werden:
  • CO@1_1_1 (Verwendung der ID)
  • CO:47 (Verwendung der internen ID)

5.5.Statuscodes

In den Antwortpaketen vom HS/FS sind immer Statuscodes vorhanden:
CodeBedeutung
0Alles in Ordnung.
400Ungültige Anfrage (Forbidden).
403Zugriff verweigert (Bad Request).
404Das angefragte HS-Objekt existiert in dem aufgerufenen Kontext nicht.
500Beim Erzeugen der Antwort ist im Server ein Fehler aufgetreten.
901Der angegebene Schlüssel ist ungültig.
902reserviert
903Die Objekt-Parameter sind ungültig.
904Das Objekt ist nicht abonniert.

5.6.Zugriffsmöglichkeiten auf Endpoints

Um die HS-Objekte abzurufen und zu verändern bietet die Firmware zwei Möglichkeiten:
  • HTTPS
    Der Zugriff auf den HS/FS erfolgt per HTTPS durch das Aufrufen von URLs durch den Client.
  • WebSocket
    Der Client öffnet einen WebSocket zum HS/FS und kann über diese stehende Verbindung kommunizieren.
    Um die Nutzung des WebSocket in Anwendungen zu erleichtern, wird die URL-Endpoints JavaScript API bereitgestellt.

6.Zugriff über HTTPS

6.1.Authentifizierung

Die Authentifizierung kann per HTTP-Authentifizierung (Basic Authentication) oder Parameter stattfinden. Schlägt die Authentifizierung fehl, antwortet der HS/FS mit Statuscode 403 (Forbidden). Ist die Anfrage nicht vollständig antwortet der HS/FS mit Statuscode 400 (Bad Request).

6.1.1.HTTP-Authentifizierung (Basic Authentication)

Der Client sendet die Authentifizierung mit dem Authorization-Header in der Form Benutzername:Passwort Base64-codiert an den HS/FS. Der genaue Ablauf des Verfahrens kann dem RFC 2617 entnommen werden.

6.1.2.Authentifizierung über Parameter (Base64-codiert)

Dem Query String der URL wird der Parameter authorization angehängt. Dieser enthält die Authentifizierung in der Form Benutzername+Passwort Base64-codiert.

6.1.3.Beispiel - Authentifizierung über Parameter (Base64-codiert)

https://192.168.0.11/endpoints/call?key=CO@1_1_1&method=get&authorization=BASE64(USERNAME+PASSWORD)

6.1.4.Authentifizierung über Parameter (Klartext)

Dem Query String der URL werden die Parameter user (Benutzername) und pw (Passwort) im Klartext angehängt.

6.1.5.Beispiel - Authentifizierung über Parameter (Klartext)

https://192.168.0.11/endpoints/call?key=CO@1_1_1&method=get&user=USERNAME&pw=PASSWORD

6.2.Kommunikation/Nachrichten zwischen HS/FS und Client

Beim Zugriff per HTTPS gibt es die folgenden Kommandos:

6.2.1.Methoden-Aufruf (call)

Aufruf einer Methode eines HS-Objekts.
6.2.1.1.Aufbau der HTTP-Anfrage an den HomeServer/FacilityServer
Der Pfad der URL lautet /endpoints/call. An diesen Pfad wird ein Query String angehängt. Der Query String enthält den Objektschlüssel des HS-Objekts (key). Außerdem noch den Namen (method) und ggf. die jeweiligen Parameter der aufgerufenen Methode.
Die HTTP-Anfragemethode ist GET.
6.2.1.2.Beispiel - HTTP-Anfrage um den Wert eines Kommunikationsobjekts abzurufen
GET /endpoints/call?key=CO@1_1_1&method=get HTTP/1.1\r\n
Host: 192.168.0.11\r\n
Authorization: Basic YmVpc3BpZWw6cHc=\r\n
\r\n
6.2.1.3.Aufbau der Antwort des HomeServer/FacilityServer
Der HS/FS antwortet mit einer JSON Struktur im Nachrichtenrumpf/Body.
Folgende Felder sind in der JSON Struktur enthalten:
  • code: Statuscode.
  • type: Typ der Anfrage. In diesem Fall immer call.
  • request: Objekt mit Informationen zur Anfrage.
  • data (optional): Datenobjekt mit zurückgelieferten Werten der Methode. Ist nicht bei allen Methoden vorhanden.
6.2.1.4.Beispiel - Antwort auf die obige HTTP-Anfrage
HTTP/1.1 200 OK\r\n
Content-type: application/json\r\n
\r\n
{
  "code": 0,
  "type": "call",
  "request": {
    "key": "CO@1_1_1",
    "method": "get"
  },
  "data": {
    "value": 1.0
  }
}

6.2.2.Abfrage von Objektschlüsseln (select)

Abfrage einer Liste von HS-Objekten anhand bestimmter Merkmale.
6.2.2.1.Aufbau der HTTP-Anfrage an den HomeServer/FacilityServer
Der Pfad der URL lautet /endpoints/select. An diesen Pfad wird ein Query String angehängt. Der Query String enthält folgende Parameter:
  • key: Objektschlüssel durch den die Ergebnismenge eingegrenzt wird. Durch Angabe eines Sterns kann nach einer beliebigen ID gesucht werden:
    • CO@* liefert alle K.-Objekte mit Schlüssel.
    • CO:* liefert alle K.-Objekte.
    • CO@abc* liefert alle K.-Objekte deren ID mit abc beginnt.
  • tags (optional): Eine mit Leerzeichen (Achtung: muss als "+" codiert werden) getrennte Liste von Strings. Die Begriffe werden in den Tags des HS-Objekts gesucht. Der Suchbegriff muss übereinstimmen. Mehrere Begriffe werden UND-verknüpft.
  • search (optional): Eine mit Leerzeichen (Achtung: muss als "+" codiert werden) getrennte Liste von Suchbegriffen. Die Suchbegriffe werden in der Bezeichnung und der Beschreibung eines Objekts gesucht. Mehrere Suchbegriffe werden UND-verknüpft.
  • from (optional): Startposition in der Ergebnismenge (Standardwert: 0).
  • count (optional): Anzahl an Elementen, die maximal ausgeliefert werden (Standardwert: 1000).
  • meta (optional): Wenn true werden die Metadaten der HS-Objekte mit ausgeliefert (Standardwert: false).
6.2.2.2.Beispiel - Abfrage aller Kommunikationsobjekte mit zwei bestimmten Tags
GET /endpoints/select?key=CO:%2A&tags=BM+light HTTP/1.1\r\n
Host: 192.168.0.11\r\n
Authorization: Basic YmVpc3BpZWw6cHc=\r\n
\r\n
6.2.2.3.Aufbau der Antwort des HomeServer/FacilityServer
Der HS/FS antwortet mit einer JSON Struktur im Nachrichtenrumpf/Body.
Folgende Felder sind in der JSON Struktur enthalten:
6.2.2.4.Beispiel - Antwort auf die obige HTTP-Anfrage
HTTP/1.1 200 OK\r\n
Content-type: application/json\r\n
\r\n
{
  "code": 0,
  "type": "select",
  "data": {
    "items": [
      {
        "code": 0,
        "key": "CO@1_1_1",
        "caption": "BM floor light"
      },
      {
        "code": 0,
        "key": "CO@2_1_1",
        "caption": "BM LR light"
      }
    ]
  }
}

7.Zugriff über Websocket

Über die stehende Websocket Verbindung werden die Daten im JSON Format ausgetauscht.

7.1.Verbindungsaufbau

Der Client baut eine WebSocket-Verbindung (Protokoll-Version 13/RFC 6455) zum Endpunkt /endpoints/ws auf.

7.1.1.Beispiel - URL

wss://192.168.0.11/endpoints/ws

7.2.Authentifizierung

Die Authentifizierung kann per HTTP-Authentifizierung (Basic Authentication) oder Parameter stattfinden. Schlägt die Authentifizierung fehl, findet kein Aufbau einer stehenden Verbindung statt und der HS/FS antwortet mit Statuscode 403 (Forbidden). Ist die Anfrage nicht vollständig antwortet der HS/FS mit Statuscode 400 (Bad Request).

7.2.1.HTTP-Authentifizierung (Basic Authentication)

Der Client sendet die Authentifizierung mit dem Authorization-Header in der Form Benutzername:Passwort Base64-codiert an den HS/FS. Der genaue Ablauf des Verfahrens kann dem RFC 2617 entnommen werden.

7.2.2.Beispiel - HTTP-Authentifizierung (Basic Authentication)

GET /endpoints/ws HTTP/1.1\r\n
Host: 192.168.0.11\r\n
Upgrade: websocket\r\n
Authorization: Basic YmVpc3BpZWw6cHc=\r\n
Sec-WebSocket-Version: 13\r\n
Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==\r\n
\r\n

7.2.3.Authentifizierung über Parameter

Dem Query String der URL wird der Parameter authorization angehängt. Dieser enthält die Authentifizierung in der Form Benutzername+Passwort Base64-codiert.

7.2.4.Beispiel - HTTP-Authentifizierung (Basic Authentication)

GET /endpoints/ws?authorization=BASE64(USERNAME+PASSWORD) HTTP/1.1\r\n
Host: 192.168.0.11\r\n
Upgrade: websocket\r\n
Sec-WebSocket-Version: 13\r\n
Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==\r\n
\r\n

7.3.Kommunikation/Nachrichten zwischen HS/FS und Client

Beim Zugriff per Websocket gibt es die folgenden Kommandos und Ereignisse:

7.3.1.Methoden-Aufruf (call)

Aufruf einer Methode eines HS-Objekts.
7.3.1.1.Aufbau der Anfrage an den HomeServer/FacilityServer (JSON Struktur)
  • type: Typ der Anfrage. In diesem Fall immer call.
  • param: Objekt das die Parameter zum Aufruf der Methode enthält.
    • key: Objektschlüssel des HS-Objekts das aufgerufen wird.
    • method: Name der Methode die aufgerufen wird.
    • context (optional): Der angegebene Kontext wird der Antwort hinzugefügt.
Weitere Parameter sind abhängig von der aufzurufenden Methode.
7.3.1.2.Beispiel - Wert eines K.-Objekts abfragen
{
  "type": "call",
  "param": {
    "key": "CO@WindowBathroomState",
    "method": "get",
    "context": "my_context"
  }
}
7.3.1.3.Aufbau der Antwort vom HomeServer/FacilityServer (JSON Struktur)
  • code: Statuscode.
  • type: Typ der Anfrage. In diesem Fall immer call.
  • request: Objekt mit Informationen zur Anfrage.
    • key: Objektschlüssel des HS-Objekts.
    • method: Name der aufgerufenen Methode.
    • context (optional): Wenn in der Anfrage der Kontext angegeben wurde, wird er hier zurückgeliefert.
  • data (optional): Datenobjekt mit zurückgelieferten Werten der Methode. Ist nicht bei allen Methoden vorhanden.
7.3.1.4.Beispiel - Antwort auf die obige Anfrage
{
  "code": 0,
  "type": "call",
  "request": {
    "key": "CO@WindowBathroomState",
    "method": "get",
    "context": "my_context"
 },
  "data": {
    "value": 1.0
  }
}

7.3.2.Abfrage von Objekt-Schlüsseln (select)

7.3.2.1.Aufbau der Anfrage an den HomeServer/FacilityServer (JSON Struktur)
  • type: Typ der Anfrage. In diesem Fall immer select.
  • param: Objekt, das die Parameter der Abfrage enthält.
    • key: Objektschlüssel, durch den die Ergebnismenge eingegrenzt wird. Durch Angabe eines Sterns kann nach einer beliebigen ID gesucht werden:
      • CO@* liefert alle K.-Objekte mit Schlüssel.
      • CO:* liefert alle K.-Objekte.
      • CO@abc* liefert alle K.-Objekte deren ID mit abc beginnt.
    • tags (optional): Ein Array von Strings. Die Begriffe werden in den Tags des HS-Objekts gesucht. Der Suchbegriff muss übereinstimmen. Mehrere Begriffe werden UND-verknüpft.
    • search (optional): Ein Array von Suchbegriffen. Die Suchbegriffe werden in der Bezeichnung und der Beschreibung eines Objekts gesucht. Mehrere Suchbegriffe werden UND-verknüpft.
    • from (optional): Startposition in der Ergebnismenge (Standardwert: 0).
    • count (optional): Anzahl an Elementen, die maximal ausgeliefert werden (Standardwert: 1000).
    • meta (optional): Wenn true, werden die Metadaten der HS-Objekte mit ausgeliefert (Standardwert: false).
    • context (optional): Der angegebene Kontext wird der Antwort hinzugefügt.
7.3.2.2.Beispiel - Abfrage aller Szenen mit dem in der Bezeichnung oder Beschreibung vorkommenden Suchbegriff "light"
{
  "type": "select",
  "param": {
    "key": "SC@*",
    "search": ["light"],
    "context": "my_context"
  }
}
7.3.2.3.Aufbau der Antwort vom HomeServer/FacilityServer (JSON Struktur)
  • code: Statuscode.
  • type: Typ der Anfrage. In diesem Fall immer select.
  • request: Objekt mit Informationen zur Anfrage.
    • context (optional): Wenn in der Anfrage der Kontext angegeben wurde, wird er hier zurückgeliefert.
  • data: Objekt, das die Daten der Antwort enthält.
7.3.2.4.Beispiel - Antwort auf die obige Anfrage
{
  "code": 0,
  "type": "select",
  "request": {
      "context": "my_context"
  },
  "data": {
    "items": [{
      "key": "SC@lsev",
      "caption": "Lightscene Livingroom evening",
      "code": 0
    }, {
      "key": "SC@lsmo",
      "caption": "Lightscene Livingroom morning",
      "code": 0
    }]
  }
}

7.3.3.Abonnieren von HS-Objekten (subscribe)

7.3.3.1.Aufbau der Anfrage an den HomeServer/FacilityServer (JSON Struktur)
  • type: Typ der Anfrage. In diesem Fall immer subscribe.
  • param: Objekt, das die Parameter der Abfrage enthält.
    • keys: Array von Objektschlüsseln aller zu abonnierenden HS-Objekte. Durch Angabe eines Sterns können mehrere HS-Objekte mit einem Objektschlüssel abonniert werden:
      • CO@* abonniert alle K.-Objekte mit Schlüssel.
      • CO:* abonniert alle K.-Objekte.
      • CO@abc* abonniert alle K.-Objekte deren ID mit abc beginnt.
      • SC:123 abonniert die Szene mit der internen ID 123
    • context (optional): Der angegebene Kontext wird der Antwort hinzugefügt.
7.3.3.2.Beispiel - Abonnieren
{
  "type": "subscribe",
  "param": {
    "keys": ["CO@1_1_1", "CO@2_1_1", "CO@DOES_NOT_EXIST"],
    "context": "my_context"
  }
}
7.3.3.3.Aufbau der Antwort vom HomeServer/FacilityServer (JSON Struktur)
  • code: Statuscode.
  • type: Typ der Anfrage. In diesem Fall immer subscribe.
  • request: Objekt mit Informationen zur Anfrage.
    • context (optional): Wenn in der Anfrage der Kontext angegeben wurde, wird er hier zurückgeliefert.
  • data: Objekt, das die Daten der Antwort enthält.
7.3.3.4.Beispiel - Antwort auf die obige Anfrage
{
  "code": 0,
  "type": "subscribe",
  "request": {
    "context": "my_context"
  },
  "data": {
    "items": [{
      "code": 0,
      "key": "CO@1_1_1",
      "data": {
       "value": 12.0
      }
    }, {
      "code": 0,
      "key": "CO@2_1_1",
      "data": {
       "value": 0.0
      }
    }, {
      "code": 404,
      "key": "CO@DOES_NOT_EXIST"
    }]
  }
}

7.3.4.Abonnement kündigen (unsubscribe)

7.3.4.1.Aufbau der Anfrage an den HomeServer/FacilityServer (JSON Struktur)
  • type: Typ der Anfrage. In diesem Fall immer unsubscribe.
  • param: Objekt, das die Parameter der Abfrage enthält.
    • keys: Array von Objektschlüsseln aller nicht weiter zu abonnierenden HS-Objekte. Durch Angabe eines Sterns kann bei mehreren HS-Objekten mit einem Objektschlüssel das Abonnement gekündigt werden:
      • CO@* kündigt das Abonnement für alle K.-Objekte mit Schlüssel.
      • CO:* kündigt das Abonnement für alle K.-Objekte.
      • CO@abc* kündigt das Abonnement für alle K.-Objekte deren ID mit abc beginnt.
      • SC:123 kündigt das Abonnement für die Szene mit der internen ID 123
    • context (optional): Der angegebene Kontext wird der Antwort hinzugefügt.
7.3.4.2.Beispiel - Kündigung eines Abonnements
{
  "type": "unsubscribe",
  "param": {
    "keys": ["CO@1_1_1", "CO@NOT_SUBSCRIBED"],
    "context": "my_context"
  }
}
7.3.4.3.Aufbau der Antwort vom HomeServer/FacilityServer (JSON Struktur)
  • code: Statuscode.
  • type: Typ der Anfrage. In diesem Fall immer unsubscribe.
  • request: Objekt mit Informationen zur Anfrage.
    • context (optional): Wenn in der Anfrage der Kontext angegeben wurde, wird er hier zurückgeliefert.
  • data: Objekt, das die Daten der Antwort enthält.
7.3.4.4.Beispiel - Antwort auf die obige Anfrage
{
  "code": 0,
  "type": "unsubscribe",
  "request": {
    "context": "my_context"
  },
  "data": {
    "items": [{
      "code": 0,
      "key": "CO@1_1_1"
    }, {
      "code": 903,
      "key": "CO@NOT_SUBSCRIBED"
    }]
  }
}

7.3.5.Wertänderung (push)

Wenn ein HS-Objekt abonniert wurde und sich das HS-Objekt während der Laufzeit des HS/FS ändert, wird ein Paket vom HomeServer/FacilityServer gesendet.
7.3.5.1.Aufbau des Pakets vom HomeServer/FacilityServer (JSON Struktur)
  • code: Statuscode.
  • type: Typ der Nachricht. In diesem Fall immer push.
  • subscription: Objekt mit Informationen zum Abonnement.
  • data: Daten des abonnierten HS-Objekts. Abhängig vom Objekttyp.
7.3.5.2.Beispiel - Mitteilung einer Wertänderung bei einem Abonnement
{
  "code": 0,
  "type": "push",
  "subscription": {
    "key": "CO@1_1_1"
  },
  "data": {
    "value": 1.0
  }
}

8.HS-Objekte

8.1.Datenarchive

Präfix: DA

8.1.1.Abonnement

8.1.1.1.Datenobjekt beim Abonnieren
keines
8.1.1.2.Datenobjekt beim Hinzufügen eines Eintrags in das Archiv
Das Datenobjekt hat folgende Felder:
  • first: Unix-Zeitstempel (in Sekunden, Millisekunden als Kommawert) des ältesten Eintrags im Datenarchiv.
  • last: Unix-Zeitstempel (in Sekunden, Millisekunden als Kommawert) des jüngsten Eintrags im Datenarchiv.
  • count: Anzahl der Einträge im Datenarchiv.

8.1.2.Methoden

8.1.2.1.Methode: meta
Abruf von Metadaten eines Datenarchivs.
8.1.2.1.1.Parameter
Diese Methode benötigt keine Parameter.
8.1.2.1.2.Antwort
Das Datenobjekt in der Antwort des HS/FS hat folgende Felder:
  • keys: Array mit dem/den beiden Objektschlüssel(n) des Datenarchivs.
  • caption: Bezeichnung des Datenarchivs.
  • description: Beschreibung des Datenarchivs.
  • tags: Array von Tags zum Datenarchiv.
  • size: Maximale Größe des Ringpuffers des Datenarchivs.
  • stat: Objekt, das Informationen über den Inhalt des Datenarchivs enthält. Es hat folgende Felder:
    • first: Unix-Zeitstempel (in Sekunden, Millisekunden als Kommawert) des ältesten Eintrags im Datenarchiv.
    • last: Unix-Zeitstempel (in Sekunden, Millisekunden als Kommawert) des jüngsten Eintrags im Datenarchiv.
    • count: Anzahl der Einträge im Datenarchiv.
  • cols: Array von Spaltenobjekten. Jedes Spaltenobjekt repräsentiert eine Spalte im Datenarchiv. Ein Spaltenobjekt hat folgende Felder:
    • idx: Index der Spalte.
    • key: Schlüssel der Spalte.
    • text: Bezeichnung der Spalte.
8.1.2.2.Methode: get
Abruf von Daten eines Datenarchivs.
8.1.2.2.1.Parameter
  • startat: Startzeitpunkt, ab dem die Daten geliefert werden sollen, als String. Das Format des Strings lautet YYMMDDHHMM. (YY = Jahr; MM = Monat; DD = Tag; HH = Stunden; MM = Minuten; z.B. 1607030805 = 3.7.2016 8:05 Uhr)
  • cnt: Anzahl der Datenblöcke, die ausgeliefert werden sollen.
  • size: Größe eines Datenblocks in Minuten. (Zum Beispiel mit den Parametern cnt = 24 und size = 60 würde die Antwort 24 Einträge über einen Gesamt-Zeitraum von 24 Stunden liefern.)
  • cols: Array von Spalten, die abgerufen werden sollen. Die Spalte kann entweder über ihren Schlüssel oder ihren Index angegeben werden. Dem Index muss eine Raute (#) vorangestellt sein. (Beispielsweise liefert der Parameter cols = ["#1", "#2", "#4"] die Spalten 1, 2 und 4 des Archivs. cols = ["DEBIT", "CREDIT"] liefert die Spalten mit den Schlüsseln DEBIT und CREDIT.)
8.1.2.2.2.Antwort
Das Datenobjekt in der Antwort des HS/FS hat folgende Felder:
  • columns: Objekt, das alle angeforderten Spalten enthält. Als Felder dienen die Spaltenschlüssel.
    • Spaltenschlüssel: Objekt, das Informationen zu einer Spalten enthält. Es hat folgende Felder:
      • sum: Array von Summen aller Werte, die in dem jeweiligen (Block-)Zeitraum aufgezeichnet wurden.
      • cnt: Array von den Anzahlen der Werte, aus denen die Summe gebildet wurde.
      • min: Array von Minimalwerten, die in dem jeweiligen (Block-) Zeitraum aufgezeichnet wurden.
      • max: Array von Maximalwerten, die in dem jeweiligen (Block-) Zeitraum aufgezeichnet wurden.
      • error: Zeigt mit einem Wert größer Null an, dass bei der Berechnung der Archivdaten ein Fehler aufgetreten ist. Z.B. wenn für den angefragten Zeitraum keine Daten vorhanden sind.
8.1.2.2.3.Beispiel
Anfrage HTTPS:

https://192.168.0.11/endpoints/call?key=DA@arch_temp&method=get&startat=1601010000&cnt=3&size=60&cols=CREDIT+DEBIT
Anfrage WebSocket:

{
  "type": "call",
  "param": {
    "key": "DA@arch_temp",
    "method": "get",
    "startat": "1601010000",
    "cnt": 3,
    "size": 60,
    "cols": ["CREDIT", "DEBIT"]
  }
}
Antwort:

{
  "code": 0,
  "type": "call",
  "request": {
    "method": "get",
    "key": "DA@arch_temp"
  },
  "data": {
    "columns": {
      "CREDIT": {
        "sum": [31, 32, 30],
        "cnt": [2, 2, 2],
        "min": [15, 16, 14],
        "max": [16, 16, 16],
        "error": 0
      },
      "DEBIT": {
        "sum": [34, 34, 34],
        "cnt": [2, 2, 2],
        "min": [17, 17, 17],
        "max": [17, 17, 17],
        "error": 0
      }
    }
  }
}

8.2.Kameraarchive

Präfix: CA

8.2.1.Abonnement

8.2.1.1.Datenobjekt beim Abonnieren
keines
8.2.1.2.Datenobjekt beim Hinzufügen eines Eintrags in das Kameraarchiv
Das Datenobjekt hat folgende Felder:
  • first:
    Unix-Zeitstempel (in Sekunden, Millisekunden als Kommawert) des ältesten Bilds im Kameraarchiv.
  • last:
    Unix-Zeitstempel (in Sekunden, Millisekunden als Kommawert) des jüngsten Bilds im Kameraarchiv.
  • count:
    Anzahl der Bilder im Kameraarchiv.
  • pic_id:
    ID des hinzugefügten Bilds. Wird für einen Abruf mittels get_picture oder get_picture_raw benötigt.

8.2.2.Methoden

8.2.2.1.Methode: meta
Abruf von Metadaten eines Kameraarchivs.
8.2.2.1.1.Parameter
Diese Methode benötigt keine Parameter.
8.2.2.1.2.Antwort
Das Datenobjekt in der Antwort des HS/FS hat folgende Felder:
  • keys: Array mit dem/den beiden Objektschlüssel(n) des Kameraarchivs.
  • caption: Bezeichnung des Kameraarchivs.
  • description: Beschreibung des Kameraarchivs.
  • tags: Array von Tags zum Kameraarchivs.
  • size: Maximale Größe des Ringpuffers des Kameraarchivs.
  • size_in_bytes: Maximale Größe des Kameraarchivs in Bytes.
  • space: Größe der im Kameraarchiv archivierten Bilder in Bytes.
  • stat: Objekt, das Informationen über den Inhalt des Kameraarchivs enthält. Es hat folgende Felder:
    • first: Unix-Zeitstempel (in Sekunden, Millisekunden als Kommawert) des ältesten Bilds im Kameraarchivs.
    • last: Unix-Zeitstempel (in Sekunden, Millisekunden als Kommawert) des jüngsten Bilds im Kameraarchivs.
    • count: Anzahl der Bilder im Kameraarchiv.
8.2.2.2.Methode: get_list
Abruf der Einträge eines Kameraarchivs.
8.2.2.2.1.Parameter
Diese Methode benötigt keine Parameter.
8.2.2.2.2.Antwort
Das Datenobjekt in der Antwort des HS/FS hat folgende Felder:
  • items: Array mit einem Objekt für jeden Eintrag im Kameraarchiv. Ein Objekt hat folgende Felder:
    • ts: Unix-Zeitstempel (in Sekunden, Millisekunden als Kommawert) des Eintrags.
    • pic_id: ID des Bilds. Wird für einen Abruf mittels get_picture oder get_picture_raw benötigt
8.2.2.3.Methode: get_picture
Liefert ein archiviertes Kamerabild.
8.2.2.3.1.Parameter
  • pic_id: ID des Bilds.
8.2.2.3.2.Antwort
Das Datenobjekt in der Antwort des HS/FS hat folgende Felder:
  • encoding: Immer base64.
  • content-type: Der mime-type des Bids. Immer image/jpeg.
  • content: Die Binärdaten des Bilds, kodiert mit dem unter encoding angegebenen Verfahren (base64).
8.2.2.4.Methode: get_picture_raw
Liefert ein archiviertes Kamerabild als Binär-Blob. Die Methode steht nur über HTTP zur Verfügung.
8.2.2.4.1.Parameter
  • pic_id: ID des Bilds.

8.3.Kameras

Präfix: CP

8.3.1.Abonnement

Nicht möglich.

8.3.2.Methoden

8.3.2.1.Methode: meta
Abruf von Metadaten einer Kamera.
8.3.2.1.1.Parameter
Diese Methode benötigt keine Parameter.
8.3.2.1.2.Antwort
Das Datenobjekt in der Antwort des HS/FS hat folgende Felder:
  • keys: Array mit dem/den beiden Objektschlüssel(n) der Kamera.
  • caption: Bezeichnung der Kamera.
  • description: Beschreibung der Kamera.
  • tags: Array von Tags zur Kamera.
  • host: Adresse der Kamera.
  • port: IP-Port der Kamera.
  • path: Pfad unter der das Bild abgerufen wird.
  • width: Im HS/FS-Experte definierte Breite des Bilds.
  • height: Im HS/FS-Experte definierte Höhe des Bilds.
8.3.2.2.Methode: get_picture
Liefert das aktuelle Kamerabild.
8.3.2.2.1.Parameter
Diese Methode benötigt keine Parameter.
8.3.2.2.2.Antwort
Das Datenobjekt in der Antwort des HS/FS hat folgende Felder:
  • encoding: Immer base64.
  • content-type: Der mime-type des Bids. Immer image/jpeg.
  • content: Die Binärdaten des Bilds, kodiert mit dem unter encoding angegebenen Verfahren (base64).
8.3.2.3.Methode: get_picture_raw
Liefert das aktuelle Kamerabild als Binär-Blob. Die Methode steht nur über HTTPS zur Verfügung.
8.3.2.3.1.Parameter
  • pic_id: ID des Bilds.

8.4.Kommunikationsobjekte

Präfix: CO

8.4.1.Abonnement

8.4.1.1.Datenobjekt beim Abonnieren
Das Datenobjekt hat folgendes Feld:
  • value: Wert des K.-Objekts. Abhängig vom Typ des K.-Objekts ist dies ein String oder eine Zahl.
8.4.1.2.Datenobjekt bei Änderung des Wertes eines Kommunikationsobjekts
Das Datenobjekt hat folgendes Feld:
  • value: Wert des K.-Objekts. Abhängig vom Typ des K.-Objekts ist dies ein String oder eine Zahl.

8.4.2.Methoden

8.4.2.1.Methode: meta
Abruf von Metadaten eines K.-Objekts.
8.4.2.1.1.Parameter
Diese Methode benötigt keine Parameter.
8.4.2.1.2.Antwort
Das Datenobjekt in der Antwort des HS/FS hat folgende Felder:
  • keys: Array mit dem/den beiden Objektschlüssel(n) des K.-Objekts.
  • caption: Bezeichnung des K.-Objekts.
  • description: Beschreibung des K.-Objekts.
  • tags: Array von Tags zum K.-Objekts.
  • format: Datenformat des K-Objekts als ID. Folgende Datenformate sind möglich:
    IDDatenformat
    11 Bit
    28 Bit (0..100)
    38 Bit (RTR)
    416 Bit (Gleitkomma)
    52 Bit
    94 Byte
    108 Bit (unsigned) oder Dali
    118 Bit (signed)
    1216 Bit (unsigned)
    1316 Bit (signed)
    1432 Bit (unsigned) oder Sammelrückmeldeobjekt
    1532 Bit (signed)
    164 Bit
    173 Byte
    203 Byte (Zeit)
    213 Byte (Datum)
    2214 Byte (String)
  • minValue: Minimal zulässiger Wert. Hat den Wert 0, wenn Format 14 Byte ist.
  • maxValue: Maximal zulässiger Wert. Hat den Wert 0, wenn Format 14 Byte ist.
  • list: Array von Werten. Mit den Methoden list_prev und list_next kann das K.-Objekt auf die einzelnen Werte gesetzt werden. Nicht gesetzt, wenn das Format 14 Byte ist.
  • offset: Wert zur schrittweisen Veränderung des Werts mit Hilfe der Methoden offset_plus und offset_minus. Hat den Wert 0, wenn Format 14 Byte ist.
  • grpadr: Gruppenadresse (z.B. 1/1/1) entsprechend der Definition im HS/FS-Experte.
8.4.2.2.Methode: get
Abruf des aktuellen Werts eines K.-Objekts.
8.4.2.2.1.Parameter
Diese Methode benötigt keine Parameter.
8.4.2.2.2.Antwort
Das Datenobjekt in der Antwort des HS/FS hat folgende Felder:
  • value: Wert des K.-Objekts. Abhängig vom Typ des K.-Objekts ist dies ein im Format Base64 kodierter String (beim Typ 14-Byte Text) oder eine Zahl.
8.4.2.2.3.Beispiel - Abruf eines K.-Objekts vom Typ 14-Byte Text. Der aktuelle Wert (value) ist "Abc123XYZ".
Anfrage HTTPS:

https://192.168.0.11/endpoints/call?key=CO@text&method=get
Anfrage WebSocket:

{
  "type": "call",
  "param": {
    "key": "CO@text",
    "method": "get"
  }
}
Antwort:

{
  "code": 0,
  "type": "call",
  "request": {
    "method": "get",
    "key": "CO@text"
  },
  "data": {
    "value": "QWJjMTIzWFla"
  }
}
8.4.2.3.Methode: set
Setzen des Werts eines K.-Objekts.
8.4.2.3.1.Parameter
  • value: Wert, auf den das K.-Objekt gesetzt wird. Abhängig vom Typ des K.-Objekts muss dies ein String (beim Typ 14-Byte Text) oder eine Zahl sein.
  • encoding (optional): Hat das K.-Objekt den Typ 14-Byte Text, kann hier angegeben werden, wie der übermittelte String (Parameter value) kodiert wird. Fehlt dieser Parameter, muss der String im Format Base64 kodiert sein. Alternativ kann auch als Kodierung ascii gewählt werden.
8.4.2.3.2.Antwort
Ein Datenobjekt ist in der Antwort des HS/FS nicht vorhanden.
8.4.2.4.Methode: toggle
Umschalten des Werts eines K.-Objekts zwischen 0 und dem angegeben Wert. Diese Methode ist nicht zulässig bei K.-Objekten vom Typ 14 Byte (String).
8.4.2.4.1.Parameter
  • value: Wert, mit dem der Wert des K.-Objekts umgeschaltet wird.
8.4.2.4.2.Antwort
Ein Datenobjekt ist in der Antwort des HS/FS nicht vorhanden.
8.4.2.5.Methode: add
Erhöhen des Werts eines K.-Objekts um den angegeben Wert. Diese Methode ist nicht zulässig bei K.-Objekten vom Typ 14 Byte (String).
8.4.2.5.1.Parameter
  • value: Wert, um den der Wert des K.-Objekt erhöht wird.
8.4.2.5.2.Antwort
Ein Datenobjekt ist in der Antwort des HS/FS nicht vorhanden.
8.4.2.6.Methode: offset_plus
Erhöhen des Werts eines K.-Objekts um die jeweilige Schrittgröße. Diese Methode ist nicht zulässig bei K.-Objekten vom Typ 14 Byte (String).
8.4.2.6.1.Parameter
Diese Methode benötigt keine Parameter.
8.4.2.6.2.Antwort
Ein Datenobjekt ist in der Antwort des HS/FS nicht vorhanden.
8.4.2.7.Methode: offset_minus
Vermindern des Werts eines K.-Objekts um die jeweilige Schrittgröße. Diese Methode ist nicht zulässig bei K.-Objekten vom Typ 14 Byte (String).
8.4.2.7.1.Parameter
Diese Methode benötigt keine Parameter.
8.4.2.7.2.Antwort
Ein Datenobjekt ist in der Antwort des HS/FS nicht vorhanden.
8.4.2.8.Methode: list_next
Den Wert des K-Objekts auf den nächst-größeren Wert in der Liste setzen. Diese Methode ist nicht zulässig bei K.-Objekten vom Typ 14 Byte (String).
8.4.2.8.1.Parameter
Diese Methode benötigt keine Parameter.
8.4.2.8.2.Antwort
Ein Datenobjekt ist in der Antwort des HS/FS nicht vorhanden.
8.4.2.9.Methode: list_prev
Den Wert des K-Objekts auf den nächst-kleineren Wert in der Liste setzen. Diese Methode ist nicht zulässig bei K.-Objekten vom Typ 14 Byte (String).
8.4.2.9.1.Parameter
Diese Methode benötigt keine Parameter.
8.4.2.9.2.Antwort
Ein Datenobjekt ist in der Antwort des HS/FS nicht vorhanden.

8.5.Meldungsarchive

Präfix: MA

8.5.1.Abonnement

8.5.1.1.Datenobjekt beim Abonnieren
Keines.
8.5.1.2.Datenobjekt beim Hinzufügen eines Eintrags in das Archiv
Das Datenobjekt hat folgendes Feld:
  • first: Unix-Zeitstempel (in Sekunden, Millisekunden als Kommawert) des ältesten Eintrags im Meldungsarchiv.
  • last: Unix-Zeitstempel (in Sekunden, Millisekunden als Kommawert) des jüngsten Eintrags im Meldungsarchiv.
  • count: Anzahl der Einträge im Meldungsarchiv.
  • token: Im Experte definiertes Kürzel des hinzugefügten Eintrags.
  • text: Im Experte definierter Text des hinzugefügten Eintrags.

8.5.2.Methoden

8.5.2.1.Methode: meta
Abruf von Metadaten eines Meldungsarchivs.
8.5.2.1.1.Parameter
Diese Methode benötigt keine Parameter.
8.5.2.1.2.Antwort
Das Datenobjekt in der Antwort des HS/FS hat folgende Felder:
  • keys: Array mit dem/den beiden Objektschlüssel(n) des Datenarchivs.
  • caption: Bezeichnung des Datenarchivs.
  • description: Beschreibung des Datenarchivs.
  • tags: Array von Tags zum Datenarchiv.
  • size: Maximale Größe des Ringpuffers des Datenarchivs.
  • tokens: Array aller möglichen Kürzel (Meldungen).
8.5.2.2.Methode: get
Abruf von Meldungen eines Meldungsarchivs.
8.5.2.2.1.Parameter
  • count: Anzahl der Datenblöcke, die ausgeliefert werden sollen.
8.5.2.2.2.Antwort
Das Datenobjekt in der Antwort des HS/FS hat folgende Felder:
  • items: Array mit Objekten. Ein Objekt entspricht einem Eintrag im Meldungsarchiv. Die Anzahl der Einträge ist abhängig vom Parameter count. Ein Objekt hat folgende Felder:
    • ts: Unix-Zeitstempel des Eintrags (in Sekunden, Millisekunden als Kommawert).
    • token: Im Experte definiertes Kürzel des Eintrags.
    • text: Im Experte definierter Text des Eintrags.

8.6.Sequenzen

Präfix: SQ

8.6.1.Abonnement

8.6.1.1.Datenobjekt beim Abonnieren
Keines.
8.6.1.2.Datenobjekt wenn die Sequenz gestartet, gestoppt oder abgelaufen ist
Das Datenobjekt hat folgendes Feld:
  • ts: Unix-Zeitstempel (in Sekunden, Millisekunden als Kommawert).
  • running: true, wenn die Sequenz läuft, ansonsten false.

8.6.2.Methoden

8.6.2.1.Methode: meta
Abruf von Metadaten einer Sequenz.
8.6.2.1.1.Parameter
Diese Methode benötigt keine Parameter.
8.6.2.1.2.Antwort
Das Datenobjekt in der Antwort des HS/FS hat folgende Felder:
  • keys: Array mit dem/den beiden Objektschlüssel(n) der Sequenz.
  • caption: Bezeichnung der Sequenz.
  • description: Beschreibung der Sequenz.
  • tags: Array von Tags zur Sequenz.
  • restart: Wenn true, kann die Sequenz während des Ablaufs neu gestartet werden.
8.6.2.2.Methode: get_state
Liefert den aktuellen Zustand einer Sequenz.
8.6.2.2.1.Parameter
Diese Methode benötigt keine Parameter.
8.6.2.2.2.Antwort
Das Datenobjekt in der Antwort des HS/FS hat folgendes Feld:
  • running: true, wenn die Sequenz läuft, ansonsten false.
8.6.2.3.Methode: start
Startet eine Sequenz.
8.6.2.3.1.Parameter
Diese Methode benötigt keine Parameter.
8.6.2.3.2.Antwort
Ein Datenobjekt ist in der Antwort des HS/FS nicht vorhanden.
8.6.2.4.Methode: stop
Stoppt eine Sequenz.
8.6.2.4.1.Parameter
Diese Methode benötigt keine Parameter.
8.6.2.4.2.Antwort
Ein Datenobjekt ist in der Antwort des HS/FS nicht vorhanden.

8.7.Szenen

Präfix: SC

8.7.1.Abonnement

8.7.1.1.Datenobjekt beim Abonnieren
Keines.
8.7.1.2.Datenobjekt wenn die Szene eingelernt wird
Das Datenobjekt hat folgende Felder:
  • ts: Unix-Zeitstempel (in Sekunden, Millisekunden als Kommawert).
  • modified: true, wenn die Szene neu eingelernt wurde.

8.7.2.Methoden

8.7.2.1.Methode: meta
Abruf von Metadaten einer Szene.
8.7.2.1.1.Parameter
Diese Methode benötigt keine Parameter.
8.7.2.1.2.Antwort
Das Datenobjekt in der Antwort des HS/FS hat folgende Felder:
  • keys: Array mit dem/den beiden Objektschlüssel(n) der Szene.
  • caption: Bezeichnung der Szene.
  • description: Beschreibung der Szene.
  • tags: Array von Tags zur Szene.
  • actors: Array von Objektschlüsseln der in der Szene enthaltenen K.-Objekte.
8.7.2.2.Methode: get_items
Liefert alle in einer Szene enthaltenen Aktoren.
8.7.2.2.1.Parameter
Diese Methode benötigt keine Parameter.
8.7.2.2.2.Antwort
Das Datenobjekt in der Antwort des HS/FS ist ein Array von Aktorobjekten. Jedes dieser Objekte hat folgende Felder:
  • key: Objektschlüssel des verwendeten K.-Objekts.
  • value: In der Szene gespeicherter Wert.
  • learn: true, wenn der Wert durch Lernen verändert werden kann.
8.7.2.3.Methode: learn
Lernt eine Szene neu ein.
8.7.2.3.1.Parameter
Diese Methode benötigt keine Parameter.
8.7.2.3.2.Antwort
Ein Datenobjekt ist in der Antwort des HS/FS nicht vorhanden.
8.7.2.4.Methode: call
Ruft eine Szene ab.
8.7.2.4.1.Parameter
Diese Methode benötigt keine Parameter.
8.7.2.4.2.Antwort
Ein Datenobjekt ist in der Antwort des HS/FS nicht vorhanden.
8.7.2.5.Methode: offset_plus
Erhöhen der Werte aller in einer Szene vorhandenen K.-Objekte um die jeweilige Schrittgröße.
8.7.2.5.1.Parameter
Diese Methode benötigt keine Parameter.
8.7.2.5.2.Antwort
Ein Datenobjekt ist in der Antwort des HS/FS nicht vorhanden.
8.7.2.6.Methode: offset_minus
Vermindern der Werte aller in einer Szene vorhandenen K.-Objekte um die jeweilige Schrittgröße.
8.7.2.6.1.Parameter
Diese Methode benötigt keine Parameter.
8.7.2.6.2.Antwort
Ein Datenobjekt ist in der Antwort des HS/FS nicht vorhanden.
8.7.2.7.Methode: list_next
Den Wert aller in einer Szene vorhandenen K-Objekte auf den nächst-größeren Wert in der jeweiligen Liste setzen.
8.7.2.7.1.Parameter
Diese Methode benötigt keine Parameter.
8.7.2.7.2.Antwort
Ein Datenobjekt ist in der Antwort des HS/FS nicht vorhanden.
8.7.2.8.Methode: list_prev
Den Wert aller in einer Szene vorhandenen K-Objekte auf den nächst-kleineren Wert in der jeweiligen Liste setzen.
8.7.2.8.1.Parameter
Diese Methode benötigt keine Parameter.
8.7.2.8.2.Antwort
Ein Datenobjekt ist in der Antwort des HS/FS nicht vorhanden.

8.8.Universal-Zeitschaltuhren

Präfix: TI

8.8.1.Abonnement

8.8.1.1.Datenobjekt beim Abonnieren
Keines.
8.8.1.2.Datenobjekt wenn die Zeitschaltuhr verändert wurde
Das Datenobjekt hat folgende Felder:
  • ts: Unix-Zeitstempel (in Sekunden, Millisekunden als Kommawert) der Änderung.
  • active: true, wenn die Zeitschaltuhr aktiv ist, ansonsten false.
  • modified: true, wenn wenn die Zeitschaltuhr verändert (d.h. ein Ereignis angelegt, geändert oder gelöscht) wurde.

8.8.2.Methoden

8.8.2.1.Methode: meta
Abruf von Metadaten einer Universal-Zeitschaltuhr.
8.8.2.1.1.Parameter
Diese Methode benötigt keine Parameter.
8.8.2.1.2.Antwort
Das Datenobjekt in der Antwort des HS/FS hat folgende Felder:
  • keys: Array mit dem/den beiden Objektschlüssel(n) der Zeitschaltuhr.
  • caption: Bezeichnung der Zeitschaltuhr.
  • description: Beschreibung der Zeitschaltuhr.
  • tags: Array von Tags zur Zeitschaltuhr.
  • actions: Array der in der Zeitschaltuhr hinterlegten Aktionen. Jede Aktion wird durch ein Objekt repräsentiert. Dieses hat folgende Felder:
    • id: ID der Aktion.
    • text: Bezeichnung der Aktion
    • commands: Anzahl der hinterlegten Befehle.
8.8.2.2.Methode: get_state
Liefert den aktuellen Zustand einer Universal-Zeitschaltuhr.
8.8.2.2.1.Parameter
Diese Methode benötigt keine Parameter.
8.8.2.2.2.Antwort
Das Datenobjekt in der Antwort des HS/FS hat folgendes Feld:
  • active: true, wenn die Zeitschaltuhr aktiviert ist, ansonsten false.
8.8.2.3.Methode: set_active
Aktiviert eine Universal-Zeitschaltuhr.
8.8.2.3.1.Parameter
Diese Methode benötigt keine Parameter.
8.8.2.3.2.Antwort
Ein Datenobjekt ist in der Antwort des HS/FS nicht vorhanden.
8.8.2.4.Methode: set_inactive
Deaktiviert eine Universal-Zeitschaltuhr.
8.8.2.4.1.Parameter
Diese Methode benötigt keine Parameter.
8.8.2.4.2.Antwort
Ein Datenobjekt ist in der Antwort des HS/FS nicht vorhanden.
8.8.2.5.Methode: get_events
Liefert eine Auflistung aller Ereignisse einer Universal-Zeitschaltuhr.
8.8.2.5.1.Parameter
Diese Methode benötigt keine Parameter.
8.8.2.5.2.Antwort
Das Datenobjekt in der Antwort des HS/FS hat folgende Felder:
8.8.2.6.Methode: add_event
Fügt einer Zeitschaltuhr ein Ereignis hinzu.
8.8.2.6.1.Parameter
Diese Methode benötigt als Parameter die Felder eines Ereignisobjekts.
8.8.2.6.2.Antwort
Ein Datenobjekt ist in der Antwort des HS/FS nicht vorhanden.
8.8.2.7.Methode: set_event
Modifiziert ein bestehendes Ereignis.
8.8.2.7.1.Parameter
Diese Methode benötigt als Parameter die Felder eines Ereignisobjekts. Außerdem hat sie noch folgenden Parameter:
8.8.2.7.2.Antwort
Ein Datenobjekt ist in der Antwort des HS/FS nicht vorhanden.
8.8.2.8.Methode: del_event
Löscht ein bestehendes Ereignis.
8.8.2.8.1.Parameter
8.8.2.8.2.Antwort
Ein Datenobjekt ist in der Antwort des HS/FS nicht vorhanden.
8.8.2.9.Methode: simulate
Simuliert die Berechnung der Schaltzeitpunkte einer Universal-Zeitschaltuhr für die nächsten Tage. Diese Funktion steht nur für URL-Endpoints zur Verfügung.
8.8.2.9.1.Parameter
  • days: Anzahl der Tage, die berechnet werden sollen. Dies können maximal 28 Tage sein.
8.8.2.9.2.Antwort
Das Datenobjekt in der Antwort des HS/FS hat folgende Felder:
  • items: Array mit den berechneten Schaltzeitpunkten für die angegebenen Tage. Ein Schaltzeitpunktobjekt hat folgende Felder:
    • event_id: ID (Nummer) des Ereignisses.
    • ts: Unix-Zeitstempel (in Sekunden, Millisekunden als Kommawert), an dem das Ereignis ausgelöst wird (Uhrzeit HS/FS). Der Zeitpunkt kann durch das Feld random noch beeinflusst werden.
    • random: Zeitbereich in Minuten, in dem das Ereignis ausgelöst werden kann. Der Zeitpunkt liegt dann im Bereich zwischen ts - (random * 60) und ts + (random * 60).

8.8.3.Ereignisobjekt

Das Ereignisobjekt hat folgende Felder:
  • date_type: Gibt an, ob das Datum des Ereignisses durch einen Wochentag (date_type=1), einen Zeitraum (date_type=2) oder ein Einzeldatum (date_type=3) bestimmt wird.
  • weekdays: Array mit aktivierten Wochentagen. (0=Montag, 1=Dienstag,..., 6=Sonntag)
    Ist nur vorhanden, wenn date_type=1 (Wochentag) ist.
  • date1: Erster Tag, an dem das Ereignis ausgelöst werden soll, als String. Das Format des Strings lautet YYMMDD (YY = Jahr; MM = Monat; DD = Tag; z.B. 160703 = 3.7.2016)
    Ist nur vorhanden, wenn date_type=2 (Zeitraum) ist.
  • date2: Letzter Tag, an dem das Ereignis ausgelöst werden soll, als String. Das Format des Strings lautet YYMMDD (YY = Jahr; MM = Monat; DD = Tag; z.B. 160703 = 3.7.2016)
    Ist nur vorhanden, wenn date_type=2 (Zeitraum) ist.
  • day: Tag (1-31), an dem das Ereignis ausgelöst werden soll. Ist das Feld nicht vorhanden, wird an jedem Tag ausgelöst, an dem der Monat und das Jahr übereinstimmen.
    Ist nur vorhanden, wenn date_type=3 (Einzeldatum) ist.
  • month: Monat (1-12), in dem das Ereignis ausgelöst werden soll. Ist das Feld nicht vorhanden, wird in jedem Monat ausgelöst, in dem der Tag und das Jahr übereinstimmen.
    Ist nur vorhanden, wenn date_type=3 (Einzeldatum) ist.
  • year: Jahr (0-99 entspricht 2000 bis 2099), in dem das Ereignis ausgelöst werden soll. Ist das Feld nicht vorhanden, wird in jedem Jahr ausgelöst, in dem der Tag und und der Monat übereinstimmen.
    Ist nur vorhanden, wenn date_type=3 (Einzeldatum) ist.
  • time_type: Gibt an, ob das Ereignis zu einer bestimmten Uhrzeit (time_type=1) oder abhängig von Sonnenaufgang (time_type=2) oder Sonnenuntergang (time_type=3) ausgelöst werden soll.
  • time: Uhrzeit als als String. Das Format des Strings lautet HHMM. (HH = Stunden; MM = Minuten; z.B. 0700 = 7:00 Uhr)
    Ist nur vorhanden, wenn time_type=1 (Uhrzeit) ist.
  • offset: Anzahl in Minuten, in dem das Ereignis vor (negativer Wert), oder nach dem Sonnenaufgang/Sonnenuntergang ausgelöst werden soll.
    Ist nur vorhanden wenn time_type=2 (Sonnenaufgang) oder time_type=3 (Sonnenuntergang) ist.
  • random: Max. Anzahl in Minuten, die dem Auslösezeitpunkt des Ereignisses zufällig zugefügt oder abgezogen werden.
  • filter: Bestimmt, ob ein Ereignis immer (filter=0), nur an normalen Tagen (kein Feiertag, kein Urlaubstag) (filter=1), nur an Feiertagen (filter=2), nur an Urlaubstagen (filter=3) oder nie (filter=4) ausgelöst werden soll.
  • action: ID der Aktion, die ausgelöst werden soll. Alle in der Zeitschaltuhr definierten Aktionen werden beim Abruf der Metadaten übermittelt.
8.8.3.1.Beispiele
Der Zeitschaltuhr mit dem Objektschlüssel TI@UZSU1 wird ein Ereignis hinzugefügt. Dieses führt die Aktion mit der ID 1 an Werktagen (Montag-Freitag), wenn kein Feiertag oder Urlaubstag ist, um 12:00 Uhr aus:
{
  "type": "call",
  "param": {
    "key": "TI@UZSU1",
    "method": "add_event",
    "date_type": 1,
    "weekdays": [0, 1, 2, 3, 4],
    "time_type": 1,
    "time": "1200",
    "filter": 1,
    "action": 1
  }
}

Der Zeitschaltuhr mit dem Objektschlüssel TI@UZSU1 wird ein Ereignis hinzugefügt. Dieses führt die Aktion mit der ID 1 jeden Samstag und Sonntag zwischen 9:30 Uhr und 10:30 Uhr aus:
{
  "type": "call",
  "param": {
    "key": "TI@UZSU1",
    "method": "add_event",
    "date_type": 1,
    "weekdays": [5, 6],
    "time_type": 1,
    "time": "1000",
    "random": 30,
    "filter": 0,
    "action": 1
  }
}

Der Zeitschaltuhr mit dem Objektschlüssel TI@UZSU1 wird ein Ereignis hinzugefügt. Dieses führt die Aktion mit der ID 1 jeden Tag im April 2016, jeweils eine Stunde nach Sonnenaufgang, aus:
{
  "type": "call",
  "param": {
    "key": "TI@UZSU1",
    "method": "add_event",
    "date_type": 2,
    "date1": "160401",
    "date2": "160430",
    "time_type": 2,
    "offset": 60,
    "filter": 0,
    "action": 1
  }
}

8.9.Urlaubskalender

Präfix: VC

8.9.1.Abonnement

8.9.1.1.Datenobjekt beim Abonnieren oder wenn der Kalender geändert wird
Das Datenobjekt hat folgende Felder:
  • active: true, wenn der Kalender aktiviert ist, ansonsten false.
  • from: Start des Zeitraums als String. Das Format des Strings lautet YYYYMMDD (YYYY = Jahr; MM = Monat; DD = Tag; z.B. 20160703 = 3.7.2016).
  • to: Ende des Zeitraums als String. Das Format des Strings lautet YYYYMMDD (YYYY = Jahr; MM = Monat; DD = Tag; z.B. 20160703 = 3.7.2016).

8.9.2.Methoden

8.9.2.1.Methode: meta
Abruf von Metadaten eines Urlaubskalenders.
8.9.2.1.1.Parameter
Diese Methode benötigt keine Parameter.
8.9.2.1.2.Antwort
Das Datenobjekt in der Antwort des HS/FS hat folgendes Felder:
  • keys: Array mit dem/den beiden Objektschlüssel(n) des Urlaubskalenders.
  • caption: Bezeichnung des Urlaubskalenders.
  • description: Beschreibung des Urlaubskalenders.
  • tags: Array von Tags zum Urlaubskalender.
8.9.2.2.Methode: get
Liefert den aktuellen Zustand eines Urlaubskalenders.
8.9.2.2.1.Parameter
Diese Methode benötigt keine Parameter.
8.9.2.2.2.Antwort
Das Datenobjekt in der Antwort des HS/FS hat folgende Felder:
  • active: true, wenn der Kalender aktiviert ist, ansonsten false.
  • from: Start des Zeitraums als String. Das Format des Strings lautet YYYYMMDD (YYYY = Jahr; MM = Monat; DD = Tag; z.B. 20160703 = 3.7.2016).
  • to: Ende des Zeitraums als String. Das Format des Strings lautet YYYYMMDD (YYYY = Jahr; MM = Monat; DD = Tag; z.B. 20160703 = 3.7.2016).
8.9.2.3.Methode: set
Setzen eines Urlaubskalenders.
8.9.2.3.1.Parameter
  • active: true aktiviert den Kalender. false deaktiviert den Kalender.
  • from: Start des Zeitraums als String. Das Format des Strings lautet YYYYMMDD (YYYY = Jahr; MM = Monat; DD = Tag; z.B. 20160703 = 3.7.2016).
  • to: Ende des Zeitraums als String. Das Format des Strings lautet YYYYMMDD (YYYY = Jahr; MM = Monat; DD = Tag; z.B. 20160703 = 3.7.2016).
8.9.2.3.2.Antwort
Ein Datenobjekt ist in der Antwort des HS/FS nicht vorhanden.