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 oder HTTP
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 HTTP/S-Aufruf abgerufen bzw. verändert werden. Jedes HS-Objekt bekommt dazu einen eindeutigen Schlüssel (ID) im Experten zugewiesen. Über eine Abfrage können alle zur Verfügung stehenden HS-Objekte über HTTP/S oder Websocket abgerufen werden.
Als Alternative zum Zugriff über HTTP/S 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 (HTTP/S/WebSocket) unterstützt:

- Kommunikationsobjekte
- Datenarchive
- Meldungsarchive
- Szenen
- Sequenzen
- Kameras
- Kameraarchive
- Universal-Zeitschaltuhren
- Urlaubskalender

### 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:

Code | Bedeutung
--- | ---
0 | Alles in Ordnung.
400 | Ungültige Anfrage (Forbidden).
403 | Zugriff verweigert (Bad Request).
404 | Das angefragte HS-Objekt existiert in dem aufgerufenen Kontext nicht.
500 | Beim Erzeugen der Antwort ist im Server ein Fehler aufgetreten.
901 | Der angegebene Schlüssel ist ungültig.
902 | reserviert
903 | Die Objekt-Parameter sind ungültig.
904 | Das 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 / HTTP
  Der Zugriff auf den HS/FS erfolgt per HTTP/S 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 oder HTTP

Hinweis
Der Zugriff kann per HTTPS oder per HTTP erfolgen. In beschreibenden Texten wird dies durch die Angabe "HTTP/S" gekennzeichnet. In allen Beispiel-URLs wird `"https:\\..."` verwendet, es ist jedoch ebenfalls "`http:\\...`" möglich!

### 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 als Authentifizierung den Benutzername und das Passwort (getrennt durch einen Doppelpunkt) in Base64 kodiert.

#### 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 HTTP/S gibt es die folgenden Kommandos:

- call
  Methoden-Aufruf eines HS-Objekts.
- select
  Abfrage einer Liste von HS-Objekten.

#### 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.
  - key: Objektschlüssel des HS-Objekts.
  - method: Name der aufgerufenen Methode.
- 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:

- code: Statuscode.
- type: Typ der Anfrage. In diesem Fall immer select.
- data: Objekt das die Daten der Antwort enthält.
  - items: Array der HS-Objekte auf die die Anfrage zutrifft.
    - key: Objektschlüssel des HS-Objekts.
    - caption: Bezeichnung des HS-Objekts.
    - meta (optional): Metadaten des HS-Objekts, wenn bei der Anfrage Metadaten angefordert wurden.
    - code: Statuscode.

##### 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 als Authentifizierung den Benutzername und das Passwort (getrennt durch einen Doppelpunkt) in Base64 kodiert.

#### 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:

- Kommandos:
  - call
    Methoden-Aufruf eines HS-Objekts.
  - select
    Abfrage einer Liste von HS-Objekten.
  - subscribe
    Abonnieren von HS-Objekten.
  - unsubscribe
    Auflösen eines Abonnements.
- Ereignisse:
  - push
    Wird bei Änderung eines HS-Objekts ausgelöst, wenn dieses abonniert wurde.

#### 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.
  - items: Array der HS-Objekte, auf die die Anfrage zutrifft.
    - key: Objektschlüssel des HS-Objekts.
    - caption: Bezeichnung des HS-Objekts.
    - meta (optional): Metadaten des HS-Objekts, wenn bei der Anfrage Metadaten angefordert wurden.
    - code: Statuscode.

##### 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.
  - items: Array von Antwortobjekten auf die Anfrage.
    - key: Objektschlüssel des HS-Objekts.
    - code: Statuscode.
    - data (optional): Daten des abonnierten HS-Objekts. Abhängig vom Objekttyp.

##### 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.
  - items: Array von Antwortobjekten auf die Anfrage.
    - key: Objektschlüssel des HS-Objekts.
    - code: Statuscode.

##### 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.
  - key: Objektschlüssel des abonnierten HS-Objekts.
- 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 HTTP/S: `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 HTTP/S zur Verfügung.

###### 8.3.2.3.1.Parameter

- pic_id: ID des Bilds.

### 8.4.Kommunikationsobjekte

Präfix: CO
Hinweis
Bei der Erzeugung oder zur Anpassung von K-Objekten kann der Datenabgleich (Export und Re-Import als '.csv'-Datei, siehe Online-Hilfe zu den Kommunikationsobjekten) zu Hilfe genommen werden.

#### 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:

  ID | Datenformat
  --- | ---
  1 | 1 Bit
  2 | 8 Bit (0..100)
  3 | 8 Bit (RTR)
  4 | 16 Bit (Gleitkomma)
  5 | 2 Bit
  9 | 4 Byte
  10 | 8 Bit (unsigned) oder Dali
  11 | 8 Bit (signed)
  12 | 16 Bit (unsigned)
  13 | 16 Bit (signed)
  14 | 32 Bit (unsigned) oder Sammelrückmeldeobjekt
  15 | 32 Bit (signed)
  16 | 4 Bit
  17 | 3 Byte
  20 | 3 Byte (Zeit)
  21 | 3 Byte (Datum)
  22 | 14 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 HTTP/S: `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:

- items: Array mit Ereignisobjekten.

##### 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:

- event_id: ID (Nummer) des Ereignisses.

###### 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

- event_id: ID (Nummer) des Ereignisses.

###### 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.