Documentation HomeServer URL endpoints (HTTP/WebSocket)
Content
Note
The JavaScript API is available for easier use of the URLEndpoints interface. This is documented separately and is suitable for all those who wish to use the URLEndpoints interface via JavaScript (e.g. via application in the browser/app).

1.Introduction

HS-objects (HomeServer objects) can be retrieved or modified via a URL by HTTP/S call. Each HS-Object is assigned a unique key (ID) in the expert. Via a query all available HS-objects can be retrieved via HTTP/S or Websocket.
As an alternative to access via HTTP/S, the HS objects are also available via a connection via WebSocket (WS). With this connection, all HS objects, except cameras, can also be subscribed to.

2.Authentication

The authentication takes place via HTTP authentication (basic authentication). If the authentication fails, no connection is established and the HS/FS answers with status code 403 (Forbidden). If the request is not complete, the HS/FS replies with status code 400 (Bad Request).
After authentication fails, the IP address of the client is blocked for 5 seconds. During this time, the machine always returns the status code 503 in response to requests.

3.Starting behaviour

When the machine starts, the HTTP server is available before initialization is completed. During this time, the machine returns the status code 503 to all requests. In addition, the response contains the HTTP header "Retry-After". The client should evaluate this field and retry after the specified time in seconds.

4.Requirements

The requirements for using the URL endpoints are
  • HomeServer/FacilityServer from firmware version 4.7
  • HS/FS Expert from version 4.7

5.Overview

5.2.Metadata

Metadata can be queried for each HS object. These contain information on the respective HS object. The available metadata depends on the respective type of HS object.

The following metadata are available for all objects:
  • ID: ID unique within the object type.
  • internal ID: unique key, is automatically assigned in the HS/FS Expert.
  • Designation: The designation of the object.
  • Description (optional): A detailed description of the respective object.
  • Tags (optional): A list of keywords separated by commas.
The metadata listed above are configured in the HS/FS expert.
The internal ID cannot be seen or changed in the expert. It is supplied with the metadata query.

Furthermore, each HS object can have additional specific metadata.

5.3.User rights

Access to the end points is configured user-specifically in the HS/FS Expert User Management. The rights are assigned separately for "read" and "write". There are 16 groups each available.

5.4.Object key

To be identifiable, each HS object has two unique object keys(ID and internal ID). The ID consists of a prefix that defines the object type and an object ID that is unique within the object type.

5.4.1.Prefix

The prefix for each object type (not changeable) is specified. It consists of an abbreviation of two letters.

5.4.2.ID

The ID can be specified in the HS/FS Expert for the respective object.
Upper/lower case is ignored.
When used as an object key, it must be appended to the prefix followed by an'@' character.

5.4.3.Internal ID

The internal ID is assigned automatically, is a number and cannot be changed. When used as an object key, it must be appended to the prefix followed by a ':' (colon).

5.4.4.Example

A communication object (prefix CO) with the ID 1_1_1 and the internal ID 47 can be addressed via the following two object keys:
  • CO@1_1_1 (Use of the ID)
  • CO:47 (Using the internal ID)

5.5.Status codes

Status codes are always present in the response packets from the HS/FS:
CodeMeaning
0Everything is fine.
400Invalid request (Forbidden).
403Access denied (Bad Request).
404The requested HS-Object does not exist in the called context.
500An error occurred in the server when generating the response.
901The specified key is invalid.
902reserved
903The object parameters are invalid.
904The object is not subscribed.

5.6.Access to endpoints

The firmware offers two possibilities to retrieve and change the HS objects:
  • HTTPS / HTTP
    The HS/FS is accessed via HTTP/S by calling URLs from the client.
  • WebSocket
    The client opens a WebSocket to the HS/FS and can communicate via this standing connection.
    To facilitate the use of the WebSocket in applications, the URL endpoints JavaScript API is provided.

6.Access via HTTPS or HTTP

Note
Access can be made by HTTPS or HTTP. In descriptive texts, this is indicated by "HTTP/S". In all example URLs "https:\\..." is used, but "http:\\..." is also possible!

6.1.Authentication

Authentication can be performed using HTTP (Basic Authentication) or parameter authentication. If the authentication fails, the HS/FS responds with status code 403 (Forbidden). If the request is not complete, the HS/FS responds with status code 400 (Bad Request).

6.1.1.HTTP authentication (Basic Authentication)

The client sends authentication to the HS/FS with the authorization header in the form User Name:Password Base64-encoded. The exact procedure can be found in RFC 2617.

6.1.2.Authentication via parameters (Base64-encoded)

The parameter authorization is appended to the query string of the URL. This contains the user name and password (separated by a colon) encoded in Base64 as authentication.

6.1.3.Example - Parameter authentication (Base64 encoded)

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

6.1.4.Authentication via parameters (plain text)

The parameters user (user name) and pw (password) are appended to the query string of the URL in plain text.

6.1.5.Example - Authentication via parameter (plain text)

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

6.2.Communication/messages between HS/FS and client

When accessing via HTTP/S the following commands are available:

6.2.1.Method call (call)

Calling a method of an HS object.
6.2.1.1.Structure of the HTTP request to the HomeServer/FacilityServer
The path of the URL is /endpoints/call. A query string is appended to this path. The query string contains the object key of the HS object(key). In addition, the name(method) and, if necessary, the respective parameters of the called method.
The HTTP request method is GET.
6.2.1.2.Example - HTTP request to retrieve the value of a communication object
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.Structure of the HomeServer/FacilityServer response
The HS/FS answers with a JSON structure in the message body.
The following fields are included in the JSON structure:
  • code: Status code.
  • type: Type of request. In this case always call.
  • request: Object with information about the request.
  • data (optional): data object with returned values of the method. Is not available for all methods.
6.2.1.4.Example - response to the above HTTP request
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.Query of object keys (select)

Query a list of HS objects according to certain characteristics.
6.2.2.1.Structure of the HTTP request to the HomeServer/FacilityServer
The path of the URL is /endpoints/select. A query string is appended to this path. The query string contains the following parameters:
  • key: Object key by which the result set is limited. By entering an asterisk any ID can be searched for:
    • CO@* returns all knockout objects with a key.
    • CO:* returns all knockout objects.
    • CO@abc* returns all knockout objects whose ID starts with abc.
  • tags (optional): A list of strings separated by spaces(note: must be encoded as "+"). The terms are searched in the tags of the HS object. The search term must match. Several terms are linked with AND.
  • search (optional): A list of search terms separated by spaces (caution: must be coded as "+"). The search terms are searched in the name and description of an object. Several search terms are combined with AND.
  • from (optional): Starting position in the result set (default value: 0).
  • count (optional): maximum number of elements that are delivered (default value: 1000).
  • meta (optional): If true, the meta data of the HS objects are delivered with the result set (default value: false).
6.2.2.2.Example - Querying all communication objects with two specific 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.Structure of the HomeServer/FacilityServer response
The HS/FS responds with a JSON structure in the message body.
The following fields are included in the JSON structure:
6.2.2.4.Example - response to the above HTTP request
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.Access via Websocket

The data is exchanged in JSON format via the established web socket connection.

7.1.Connection establishment

The client establishes a WebSocket connection(protocol version 13/RFC 6455) to the /endpoints/ws endpoint.

7.1.1.Example - URL

wss://192.168.0.11/endpoints/ws

7.2.Authentication

Authentication can be performed using HTTP (Basic Authentication) or parameter authentication. If the authentication fails, a connection is not established and the HS/FS responds with status code 403 (Forbidden). If the request is not complete, the HS/FS answers with status code 400 (Bad Request).

7.2.1.HTTP-Authentication (Basic Authentication)

The client sends authentication to the HS/FS with the authorization header in the form User Name:Password Base64-encoded. The exact procedure can be found in RFC 2617.

7.2.2.Example - HTTP (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.Authentication via parameters

The parameter authorization is appended to the query string of the URL. This contains the user name and password (separated by a colon) encoded in Base64 as authentication.

7.2.4.Example - HTTP (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.Communication/messages between HS/FS and client

When accessing via web socket the following commands and events are available:

7.3.1.Method call (call)

Calling a method of an HS object.
7.3.1.1.Structure of the request to the HomeServer/FacilityServer (JSON structure)
  • type: Type of request. In this case always call.
  • param: Object which contains the parameters for calling the method.
    • key: Object key of the HS object that is called.
    • method: Name of the method that is called.
    • context (optional): The given context is added to the response.
Further parameters depend on the method to be called.
7.3.1.2.Example - Getting the value of a K. object
{
  "type": "call",
  "param": {
    "key": "CO@WindowBathroomState",
    "method": "get",
    "context": "my_context"
  }
}
7.3.1.3.Structure of the response from HomeServer/FacilityServer (JSON structure)
  • code: Status code.
  • type: Type of request. In this case always call.
  • request: Object containing information about the request.
    • key: Object key of the HS object.
    • method: Name of the called method.
    • context (optional): If the context was specified in the request, it is returned here.
  • data (optional): Data object with returned values of the method. Is not available for all methods.
7.3.1.4.Example - Answer to the above request
{
  "code": 0,
  "type": "call",
  "request": {
    "key": "CO@WindowBathroomState",
    "method": "get",
    "context": "my_context"
 },
  "data": {
    "value": 1.0
  }
}

7.3.2.Query of object keys (select)

7.3.2.1.Structure of the request to the HomeServer/FacilityServer (JSON structure)
  • type: Type of request. In this case always select.
  • param: Object containing the parameters of the request.
    • key: object key by which the result set is delimited. By specifying an asterisk you can search for any ID:
      • CO@* returns all K. objects with a key.
      • CO:* returns all knockout objects.
      • CO@abc* returns all knockout objects whose ID starts with abc.
    • tags (optional): An array of strings. The terms are searched in the tags of the HS object. The search term must match. Multiple terms are ANDed.
    • search (optional): An array of search terms. The search terms are searched in the name and description of an object. Several search terms are combined with AND.
    • from (optional): Starting position in the result set (default value: 0).
    • count (optional): maximum number of elements that are delivered (default value: 1000).
    • meta (optional): If true, the meta data of the HS objects are delivered with the result set (default value: false).
    • context (optional): The specified context is added to the response.
7.3.2.2.Example - Query all scenes with the search term"light" occurring in the name or description
{
  "type": "select",
  "param": {
    "key": "SC@*",
    "search": ["light"],
    "context": "my_context"
  }
}
7.3.2.3.Structure of the response from HomeServer/FacilityServer (JSON structure)
  • code: Status code.
  • type: Type of request. In this case always select.
  • request: Object containing information about the request.
    • context (optional): If the context was specified in the request, it is returned here.
  • data: Object containing the data of the response.
7.3.2.4.Example - Response to the above request
{
  "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.Subscribing to HS-Objects (subscribe)

7.3.3.1.Structure of the request to the HomeServer/FacilityServer (JSON structure)
  • type: Type of request. In this case always subscribe.
  • param: Object containing the parameters of the query.
    • keys: Array of object keys of all HS-objects to be subscribed. By specifying an asterisk several HS-objects can be subscribed to with one object key:
      • CO@* subscribes to all K. objects with key.
      • CO:* subscribes to all K. objects.
      • CO@abc* subscribes to all K. objects whose ID starts with abc.
      • SC:123 subscribes to the scene with the internal ID 123
    • context (optional): The specified context is added to the answer.
7.3.3.2.Example - Subscribe
{
  "type": "subscribe",
  "param": {
    "keys": ["CO@1_1_1", "CO@2_1_1", "CO@DOES_NOT_EXIST"],
    "context": "my_context"
  }
}
7.3.3.3.Structure of the response from HomeServer/FacilityServer (JSON structure)
  • code: Status code.
  • type: Type of request. In this case always subscribe.
  • request: Object containing information about the request.
    • context (optional): If the context was specified in the request, it is returned here.
  • data: Object containing the data of the response.
7.3.3.4.Example - Answer to the above request
{
  "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.Cancel subscription (unsubscribe)

7.3.4.1.Structure of the request to the HomeServer/FacilityServer (JSON structure)
  • type: Type of request. In this case always unsubscribe.
  • param: Object containing the parameters of the request.
    • keys: Array of object keys of all HS-objects which are not to be subscribed to any further. By specifying an asterisk the subscription can be cancelled for several HS objects with one object key:
      • CO@* cancels the subscription for all K. objects with key.
      • CO:* cancels the subscription for all K. objects.
      • CO@abc* cancels the subscription for all K.O. objects whose ID starts with abc.
      • SC:123 cancels the subscription for the scene with the internal ID 123
    • context (optional): The specified context is added to the answer.
7.3.4.2.Example - Canceling a subscription
{
  "type": "unsubscribe",
  "param": {
    "keys": ["CO@1_1_1", "CO@NOT_SUBSCRIBED"],
    "context": "my_context"
  }
}
7.3.4.3.Structure of the response from HomeServer/FacilityServer (JSON structure)
  • code: Status code.
  • type: Type of request. In this case always unsubscribe.
  • request: Object containing information about the request.
    • context (optional): If the context was specified in the request, it is returned here.
  • data: Object containing the data of the response.
7.3.4.4.Example - Answer to the above request
{
  "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.Change in value (push)

If an HS object is subscribed to and the HS object changes during the HS/FS runtime, a packet is sent from the HomeServer/FacilityServer.
7.3.5.1.Structure of the packet from HomeServer/FacilityServer (JSON structure)
  • code: Status code.
  • type: Type of the message. In this case always push.
  • subscription: Object containing information about the subscription.
  • data: Data of the subscribed HS object. Depending on the object type.
7.3.5.2.Example - Notification of a change in value of a subscription
{
  "code": 0,
  "type": "push",
  "subscription": {
    "key": "CO@1_1_1"
  },
  "data": {
    "value": 1.0
  }
}

8.HS-Objects

8.1.Data archives

Prefix: DA

8.1.1.Subscription

8.1.1.1.Data object when subscribing
none
8.1.1.2.Data object when adding an entry to the archive
The data object has the following fields:
  • first: Unix timestamp (in seconds, milliseconds as comma value) of the oldest entry in the data archive.
  • last: Unix timestamp (in seconds, milliseconds as comma value) of the youngest entry in the data archive.
  • count: Number of entries in the data archive.

8.1.2.Methods

8.1.2.1.Method: meta
Retrieval of metadata from a data archive.
8.1.2.1.1.Parameters
This method requires no parameters.
8.1.2.1.2.Answer
The data object in the HS/FS reply has the following fields:
  • keys: Array with the two object key( s) of the data archive.
  • caption: Name of the data archive.
  • description: Description of the data archive.
  • tags: Array of tags for the data archive.
  • size: Maximum size of the ring buffer of the data archive.
  • stat: object containing information about the content of the data archive. It has the following fields:
    • first: Unix timestamp (in seconds, milliseconds as comma value) of the oldest entry in the data archive.
    • last: Unix timestamp (in seconds, milliseconds as comma value) of the most recent entry in the data archive.
    • count: Number of entries in the data archive.
  • cols: Array of column objects. Each column object represents one column in the data archive. A column object has the following fields:
    • idx: Index of the column.
    • key: Key of the column.
    • text: Name of the column.
8.1.2.2.Method: get
Retrieval of data from a data archive.
8.1.2.2.1.Parameters
  • startat: Start time from which the data should be delivered, as string. The format of the string is YYMMDDHHMM. (YY = year; MM = month; DD = day; HH = hours; MM = minutes; e.g. 1607030805 = 3.7.2016 8:05 hrs)
  • cnt: Number of data blocks to be delivered.
  • size: Size of a data block in minutes. (For example with the parameters cnt = 24 and size = 60 the answer would deliver 24 entries over a total period of 24 hours)
  • cols: Array of columns to be retrieved. The column can be specified either by its key or its index. The index must be preceded by a hash (#). (For example, the parameter cols = ["#1", "#2", "#4"] returns columns 1, 2, and 4 of the archive. cols = ["DEBIT", "CREDIT"] returns the columns with the keys DEBIT and CREDIT)
8.1.2.2.2.Answer
The data object in the HS/FS response has the following fields:
  • columns: object that contains all requested columns. The column keys serve as fields.
    • Column key: object containing information about a column. It has the following fields:
      • sum: Array of sums of all values recorded in the respective (block) period.
      • cnt: Array of the numbers of values from which the sum was formed.
      • min: Array of minimum values recorded in the respective (block) time period.
      • max: Array of maximum values recorded in the respective (block) time period.
      • error: With a value greater than zero, indicates that an error has occurred in the calculation of the archive data. E.g. if no data is available for the requested period.
8.1.2.2.3.Example
Request HTTP/S:

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

Request WebSocket:

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

Reply:

{
  "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.Camera archives

Prefix: CA

8.2.1.Subscription

8.2.1.1.Data object when subscribing
none
8.2.1.2.Data object when adding an entry to the camera archive
The data object has the following fields:
  • first:
    Unix timestamp (in seconds, milliseconds as decimal value) of the oldest image in the camera archive.
  • last:
    Unix timestamp (in seconds, milliseconds as decimal value) of the most recent image in the camera archive.
  • count:
    Number of images in the camera archive.
  • pic_id:
    ID of the added image. Required for a retrieval using get_picture or get_picture_raw.

8.2.2.Methods

8.2.2.1.Method: meta
Retrieval of metadata of a camera archive.
8.2.2.1.1.Parameters
This method requires no parameters.
8.2.2.1.2.Answer
The data object in the HS/FS reply has the following fields:
  • keys: Array with the two object key( s) of the camera archive.
  • caption: Name of the camera archive.
  • description: Description of the camera archive.
  • tags: Array of tags for the camera archive.
  • size: Maximum size of the ring buffer of the camera archive.
  • size_in_bytes: Maximum size of the camera archive in bytes.
  • space: Size of the images archived in the camera archive in bytes.
  • stat: Object that contains information about the contents of the camera archive. It has the following fields:
    • first: Unix timestamp (in seconds, milliseconds as comma value) of the oldest image in the camera archive.
    • last: Unix timestamp (in seconds, milliseconds as decimal value) of the most recent image in the camera archive.
    • count: Number of images in the camera archive.
8.2.2.2.Method: get_list
Retrieve the entries of a camera archive.
8.2.2.2.1.Parameters
This method requires no parameters.
8.2.2.2.2.Answer
The data object in the HS/FS reply has the following fields:
  • items: Array with one object for each entry in the camera archive. An object has the following fields:
    • ts: Unix timestamp (in seconds, milliseconds as decimal value) of the entry.
    • pic_id: ID of the image. Required for a retrieval using get_picture or get_picture_raw
8.2.2.3.Method: get_picture
Provides an archived camera image.
8.2.2.3.1.Parameters
  • pic_id: ID of the image.
8.2.2.3.2.Answer
The data object in the HS/FS reply has the following fields:
  • encoding: Always base64.
  • content-type: The mime-type of the bid. Always image/jpeg.
  • content: The binary data of the image, encoded using the method specified under encoding(base64).
8.2.2.4.Method: get_picture_raw
Returns an archived camera image as a binary blob. This method is only available via HTTP.
8.2.2.4.1.Parameters
  • pic_id: ID of the image.

8.3.Cameras

Prefix: CP

8.3.1.Subscription

Not possible.

8.3.2.Methods

8.3.2.1.Method: meta
Retrieve metadata of a camera.
8.3.2.1.1.Parameters
This method requires no parameters.
8.3.2.1.2.Answer
The data object in the HS/CMS reply has the following fields:
  • keys: Array with the two object keys of the camera.
  • caption: Name of the camera.
  • description: description of the camera.
  • tags: array of tags related to the camera.
  • host: address of the camera.
  • port: IP port of the camera.
  • path: path under which the image is retrieved.
  • width: Width of the image defined in the HS/FS Expert.
  • height: Height of the image defined in the HS/FS expert.
8.3.2.2.Method: get_picture
Returns the current camera image.
8.3.2.2.1.Parameters
This method requires no parameters.
8.3.2.2.2.Answer
The data object in the HS/CMS reply has the following fields:
  • encoding: Always base64.
  • content-type: The mime-type of the bid. Always image/jpeg.
  • content: The binary data of the image, encoded using the method specified under encoding(base64).
8.3.2.3.Method: get_picture_raw
Returns the current camera image as a binary blob. This method is only available via HTTP/S.
8.3.2.3.1.Parameters
  • pic_id: ID of the image.

8.4.Communication objects

Prefix: CO
Note
For the creation or adaptation of K-objects the data synchronisation (export and re-import as '.csv' file, see online help for the communication objects) can be helpful.

8.4.1.Subscription

8.4.1.1.Data object when subscribing
The data object has the following field:
  • value: Value of the K. object. Depending on the type of the K. object, this is a string or a number.
8.4.1.2.Data object when changing the value of a communication object
The data object has the following field:
  • value: Value of the K. object. Depending on the type of the K. object, this is a string or a number.

8.4.2.Methods

8.4.2.1.Method: meta
Retrieve metadata of a K. object.
8.4.2.1.1.Parameters
This method requires no parameters.
8.4.2.1.2.Answer
The data object in the HS/CMS reply has the following fields:
  • keys: Array with the two object key(s) of the K. object
  • caption: Name of the K. object.
  • description: Description of the knockout object.
  • tags: Array of tags for the knockout object.
  • format: Data format of the K-object as ID. The following data formats are possible:
    IDData format
    11 bit
    28 bits (0..100)
    38 bits (RTR)
    416 bit (floating point)
    52 bits
    94 bytes
    108 Bit (unsigned) or Dali
    118 bit (signed)
    1216 bit (unsigned)
    1316 bit (signed)
    1432 bit (unsigned) or collective feedback object
    1532 bit (signed)
    164 bits
    173 bytes
    203 bytes (time)
    213 bytes (date)
    2214 bytes (string)
  • minValue: Minimum permissible value. Has the value 0 if format is 14 bytes.
  • maxValue: Maximum permissible value. Has the value 0, if format is 14 b ytes.
  • list: Array of values. With the methods list_prev and list_next the K. object can be set to the individual values. Not set if format is 14 b ytes.
  • offset: Value to change the value step by step using the methods offset_plus and offset_minus. Has the value 0 if format is 14 b ytes.
  • grpadr: Group address (e.g. 1/1/1) as defined in the HS/FS expert.
8.4.2.2.Method: get
Recall the current value of a knockout object.
8.4.2.2.1.Parameters
This method requires no parameters.
8.4.2.2.2.Answer
The data object in the HS/CMS reply has the following fields:
  • value: Value of the K. object. Depending on the type of the K. object, this is a string encoded in Base64 format ( 14-byte text for the type) or a number.
8.4.2.2.3.Example - Retrieving a 14-byte text K object. The current value is "Abc123XYZ".
Request HTTP/S:

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

Request WebSocket:

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

Response:

{
  "code": 0,
  "type": "call",
  "request": {
    "method": "get",
    "key": "CO@text"
  },
  "data": {
    "value": "QWJjMTIzWFla"
  }
}
8.4.2.3.Method: set
Set the value of a K. object.
8.4.2.3.1.Parameters
  • value: Value to which the K. object is set. Depending on the type of the K. object, this must be a string (for type 14-byte text) or a number.
  • encoding (optional): If the K. object is of type 14-byte text, you can specify here how the transmitted string (parameter value) is encoded. If this parameter is missing, the string must be encoded in Base64 format. Alternatively, the encoding ascii can be selected.
8.4.2.3.2.Answer
A data object is not present in the HS/FS reply.
8.4.2.4.Method: toggle
Switch the value of a knockout object between 0 and the specified value. This method is not allowed for 14-byte (string) type K. objects.
8.4.2.4.1.Parameters
  • value: Value used to switch the value of the K. object.
8.4.2.4.2.Reply
A data object is not present in the HS/FS reply.
8.4.2.5.Method: add
Increasing the value of a knockout object by the specified value. This method is not allowed for 14-byte (string) type K. objects.
8.4.2.5.1.Parameters
  • value: Value by which the value of the K. object is increased.
8.4.2.5.2.Answer
A data object is not present in the HS/FS reply.
8.4.2.6.Method: offset_plus
Increasing the value of a knockout object by the respective step size. This method is not allowed for 14-byte (string) type K. objects.
8.4.2.6.1.Parameters
This method requires no parameters.
8.4.2.6.2.Answer
A data object is not present in the HS/FS reply.
8.4.2.7.Method: offset_minus
Decrease the value of a knockout object by the respective step size. This method is not allowed for 14-byte (string) type K. objects.
8.4.2.7.1.Parameters
This method requires no parameters.
8.4.2.7.2.Answer
A data object is not present in the HS/FS reply.
8.4.2.8.Method: list_next
Set the value of the K object to the next largest value in the list. This method is not permitted for K. objects of type 14 bytes (string).
8.4.2.8.1.Parameters
This method requires no parameters.
8.4.2.8.2.Answer
A data object is not present in the HS/FS reply.
8.4.2.9.Method: list_prev
Set the value of the K-object to the next lower value in the list. This method is not allowed for K. objects of type 14 bytes (string).
8.4.2.9.1.Parameters
This method requires no parameters.
8.4.2.9.2.Answer
A data object is not present in the HS/FS reply.

8.5.Message archives

Prefix: MA

8.5.1.Subscription

8.5.1.1.Data object when subscribing
None.
8.5.1.2.Data object when adding an entry to the archive
The data object has the following field:
  • first: Unix timestamp (in seconds, milliseconds as comma value) of the oldest entry in the message archive.
  • last: Unix timestamp (in seconds, milliseconds as comma value) of the youngest entry in the message archive.
  • count: Number of entries in the message archive.
  • token: Abbreviation of the added entry defined in the expert.
  • text: Text of the added entry defined in the expert.

8.5.2.Methods

8.5.2.1.Method: meta
Retrieval of metadata of a message archive.
8.5.2.1.1.Parameters
This method requires no parameters.
8.5.2.1.2.Answer
The data object in the HS/CMS reply has the following fields:
  • keys: Array with the two object key( s) of the data archive.
  • caption: Name of the data archive.
  • description: Description of the data archive.
  • tags: Array of tags for the data archive.
  • size: Maximum size of the ring buffer of the data archive.
  • tokens: Array of all possible abbreviations (messages).
8.5.2.2.Method: get
Retrieve messages from a message archive.
8.5.2.2.1.Parameters
  • count: Number of data blocks to be delivered.
8.5.2.2.2.Answer
The data object in the HS/CMS reply has the following fields:
  • items: Array with objects. One object corresponds to one entry in the message archive. The number of entries depends on the parameter count. An object has the following fields:
    • ts: Unix timestamp of the entry (in seconds, milliseconds as decimal value).
    • token: Abbreviation of the entry defined in the expert.
    • text: Text of the entry defined in the expert.

8.6.Sequences

Prefix: SQ

8.6.1.Subscription

8.6.1.1.Data object when subscribing
None.
8.6.1.2.Data object when the sequence has started, stopped or expired
The data object has the following field:
  • ts: Unix timestamp (in seconds, milliseconds as decimal value).
  • running: true, if the sequence is running, otherwise false.

8.6.2.Methods

8.6.2.1.Method: meta
Retrieval of metadata of a sequence.
8.6.2.1.1.Parameters
This method requires no parameters.
8.6.2.1.2.Answer
The data object in the HS/CMS reply has the following fields:
  • keys: Array with the two object key( s) of the sequence.
  • caption: Name of the sequence.
  • description: Description of the sequence.
  • tags: Array of tags for the sequence.
  • restart: If true, the sequence can be restarted during the execution.
8.6.2.2.Method: get_state
Returns the current state of a sequence.
8.6.2.2.1.Parameters
This method requires no parameters.
8.6.2.2.2.Answer
The data object in the HS/CMS reply has the following fields:
  • running: true, if the sequence is running, otherwise false.
8.6.2.3.Method: start
Starts a sequence.
8.6.2.3.1.Parameters
This method requires no parameters.
8.6.2.3.2.Answer
A data object is not present in the HS/FS reply.
8.6.2.4.Method: stop
Stops a sequence.
8.6.2.4.1.Parameters
This method requires no parameters.
8.6.2.4.2.Answer
A data object is not present in the HS/FS reply.

8.7.Scenes

Prefix: SC

8.7.1.Subscription

8.7.1.1.Data object when subscribing
None.
8.7.1.2.Data object when the scene is taught in
The data object has the following fields:
  • ts: Unix timestamp (in seconds, milliseconds as decimal value).
  • modified: true, if the scene was newly taught.

8.7.2.Methods

8.7.2.1.Method: meta
Retrieve metadata of a scene.
8.7.2.1.1.Parameters
This method requires no parameters.
8.7.2.1.2.Answer
The data object in the HS/CMS reply has the following fields:
  • keys: Array with the two object key(s) of the scene.
  • caption: Name of the scene.
  • description: Description of the scene.
  • tags: array of tags for the scene.
  • actors: Array of object keys of the knockout objects contained in the scene.
8.7.2.2.Method: get_items
Returns all actuators contained in a scene.
8.7.2.2.1.Parameters
This method requires no parameters.
8.7.2.2.2.Answer
The data object in the HS/FS reply is an array of actuator objects. Each of these objects has the following fields:
  • key: Object key of the used K. object.
  • value: Value stored in the scene.
  • learn: true, if the value can be changed by learning.
8.7.2.3.Method: learn
Re-learn a scene.
8.7.2.3.1.Parameters
This method requires no parameters.
8.7.2.3.2.Answer
A data object is not present in the HS/FS reply.
8.7.2.4.Method: call
Calls up a scene.
8.7.2.4.1.Parameters
This method requires no parameters.
8.7.2.4.2.Answer
A data object is not present in the HS/FS reply.
8.7.2.5.Method: offset_plus
Increase the values of all knockout objects in a scene by the respective step size.
8.7.2.5.1.Parameters
This method requires no parameters.
8.7.2.5.2.Answer
A data object is not present in the HS/FS reply.
8.7.2.6.Method: offset_minus
Reduce the values of all knockout objects in a scene by the respective step size.
8.7.2.6.1.Parameters
This method requires no parameters.
8.7.2.6.2.Answer
A data object is not present in the HS/FS reply.
8.7.2.7.Method: list_next
Set the value of all K-objects present in a scene to the next higher value in the respective list.
8.7.2.7.1.Parameters
This method requires no parameters.
8.7.2.7.2.Answer
A data object is not present in the HS/FS reply.
8.7.2.8.Method: list_prev
Set the value of all K-objects present in a scene to the next lower value in the respective list.
8.7.2.8.1.Parameters
This method requires no parameters.
8.7.2.8.2.Answer
A data object is not present in the HS/FS reply.

8.8.Universal time switches

Prefix: TI

8.8.1.Subscription

8.8.1.1.Data object when subscribing
None.
8.8.1.2.Data object if the time switch has been changed
The data object has the following fields:
  • ts: Unix timestamp (in seconds, milliseconds as decimal value) of the change.
  • active: true, if the timer is active, otherwise false.
  • modified: true, if the timer was modified (i.e. an event was created, modified or deleted).

8.8.2.Methods

8.8.2.1.Method: meta
Retrieving metadata of a universal time switch.
8.8.2.1.1.Parameters
This method requires no parameters.
8.8.2.1.2.Answer
The data object in the HS/FS reply has the following fields:
  • keys: Array with the two object key( s) of the time switch.
  • caption: Name of the time switch.
  • description: Description of the timer.
  • tags: array of tags for the time switch.
  • actions: Array of actions stored in the timer. Each action is represented by an object. This object has the following fields:
    • id: ID of the action.
    • text: name of the action
    • commands: Number of stored commands.
8.8.2.2.Method: get_state
Returns the current status of a universal time switch.
8.8.2.2.1.Parameters
This method requires no parameters.
8.8.2.2.2.Answer
The data object in the HS/FS reply has the following field:
  • active: true, if the timer is activated, otherwise false.
8.8.2.3.Method: set_active
Activates a universal time switch.
8.8.2.3.1.Parameters
This method requires no parameters.
8.8.2.3.2.Answer
A data object is not present in the HS/FS reply.
8.8.2.4.Method: set_inactive
Deactivates a universal time switch.
8.8.2.4.1.Parameters
This method requires no parameters.
8.8.2.4.2.Answer
A data object is not present in the HS/FS reply.
8.8.2.5.Method: get_events
Provides a list of all events of a universal timer.
8.8.2.5.1.Parameters
This method requires no parameters.
8.8.2.5.2.Answer
The data object in the HS/FS reply has the following fields:
8.8.2.6.Method: add_event
Adds an event to a timer.
8.8.2.6.1.Parameters
This method requires the fields of an event object as parameters.
8.8.2.6.2.Answer
A data object is not present in the HS/FS reply.
8.8.2.7.Method: set_event
Modifies an existing event.
8.8.2.7.1.Parameters
This method requires the fields of an event object as parameters. It also has the following parameter:
  • event_id: ID (number) of the event.
8.8.2.7.2.Reply
A data object is not present in the HS/FS reply.
8.8.2.8.Method: del_event
Deletes an existing event.
8.8.2.8.1.Parameters
  • event_id: ID (number) of the event.
8.8.2.8.2.Reply
A data object is not present in the HS/FS reply.
8.8.2.9.Method: simulate
Simulates the calculation of the switching times of a universal time switch for the next days. This function is only available for URL endpoints.
8.8.2.9.1.Parameters
  • days: Number of days to be calculated. This can be a maximum of 28 days.
8.8.2.9.2.Answer
The data object in the HS/CMS response has the following fields:
  • items: Array with the calculated switching times for the specified days. A switch time object has the following fields:
    • event_id: ID (number) of the event.
    • ts: Unix timestamp (in seconds, milliseconds as a comma value) at which the event is triggered (time HS/FS). The time can still be influenced by the field random.
    • random: Time range in minutes in which the event can be triggered. The time is then in the range between ts - (random * 60) and ts + (random * 60).

8.8.3.Event object

The event object has the following fields:
  • date_type: Indicates whether the date of the event is determined by a weekday(date_type=1), a period(date_type=2) or an individual date(date_type=3).
  • weekdays: Array with activated weekdays. (0=Monday, 1=Tuesday, ..., 6=Sunday)
    Only exists if date_type=1 (weekday).
  • date1: First day on which the event is to be triggered, as string. The format of the string is YYMMDD (YY = year; MM = month; DD = day; e.g. 160703 = 3.7.2016)
    Only exists if date_type=2 (period).
  • date2: Last day on which the event is to be triggered, as string. The format of the string is YYMMDD (YY = year; MM = month; DD = day; e.g. 160703 = 3.7.2016)
    Only exists if date_type=2 (period).
  • day: Day (1-31) on which the event is to be triggered. If the field is not present, the event is triggered on any day when the month and year match.
    Only exists if date_type=3 (single date).
  • month: Month (1-12) in which the event should be triggered. If the field is not present, the event will be triggered every month when the day and year coincide.
    Only exists if date_type=3 (individual date).
  • year: Year (0-99 corresponds to 2000 to 2099) in which the event should be triggered. If the field is not present, the event will be triggered in every year where the day and month match.
    Only exists if date_type=3 (individual date).
  • time_type: Specifies whether the event should be triggered at a specific time(time_type=1) or depending on sunrise(time_type=2) or sunset(time_type=3).
  • time: time as string. The format of the string is HHMM. (HH = hours; MM = minutes; e.g. 0700 = 7:00 o'clock)
    Is only present if time_type=1 (time of day).
  • offset: Number of minutes in which the event should be triggered before (negative value) or after sunrise/sunset.
    Only available if time_type=2 (sunrise) or time_type=3 (sunset).
  • random: Max. Number in minutes that are randomly added or subtracted from the triggering time of the event.
  • filter: Determines if an event should always be triggered(filter=0), only on normal days (no holiday, no holiday day)(filter=1), only on holidays(filter=2), only on holiday days(filter=3) or never(filter=4).
  • action: ID of the action to be triggered. All actions defined in the timer are transmitted when the metadata are retrieved.
8.8.3.1.Examples
An event is added to the timer with the object key TI@UZSU1. This executes the action with the ID 1 on working days (Monday-Friday) at 12:00 noon if there is no public holiday or holiday day:
{
  "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
  }
}

An event is added to the timer with the object key TI@UZSU1. This executes the action with the ID 1 every Saturday and Sunday between 9:30 and 10:30:
{
  "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
  }
}

An event is added to the timer with the object key TI@UZSU1. This will execute the action with the ID 1 every day in April 2016, one hour after sunrise:
{
  "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.Holiday calendar

Prefix: VC

8.9.1.Subscription

8.9.1.1.Data object when subscribing or changing the calendar
The data object has the following fields:
  • active: true, if the calendar is activated, otherwise false.
  • from: Start of the period as string. The format of the string is YYYYMMDD (YYYY = year; MM = month; DD = day; e.g. 20160703 = 3.7.2016)
  • to: End of the period as string. The format of the string is YYYYMMDD (YYYY = year; MM = month; DD = day; e.g. 20160703 = 3.7.2016).

8.9.2.9.2. Methods

8.9.2.1.Method: meta
Retrieval of metadata of a holiday calendar.
8.9.2.1.1.Parameters
This method requires no parameters.
8.9.2.1.2.Answer
The data object in the HS/FS response has the following fields:
  • keys: Array with the two object key( s) of the holiday calendar.
  • caption: Name of the holiday calendar.
  • description: Description of the holiday calendar.
  • tags: array of tags for the holiday calendar.
8.9.2.2.Method: get
Returns the current status of a holiday calendar.
8.9.2.2.1.Parameters
This method requires no parameters.
8.9.2.2.2.Answer
The data object in the HS/FS response has the following fields:
  • active: true, if the calendar is activated, otherwise false.
  • from: Start of the period as string. The format of the string is YYYYMMDD (YYYY = year; MM = month; DD = day; e.g. 20160703 = 3.7.2016)
  • to: End of the period as string. The format of the string is YYYYMMDD (YYYY = year; MM = month; DD = day; e.g. 20160703 = 3.7.2016).
8.9.2.3.Method: set
Setting a holiday calendar.
8.9.2.3.1.Parameters
  • active: true enables the calendar. false disables the calendar.
  • from: Start of the period as string. The format of the string is YYYYMMDD (YYYY = year; MM = month; DD = day; e.g. 20160703 = 3.7.2016).
  • to: End of the period as string. The format of the string is YYYYMMDD (YYYY = year; MM = month; DD = day; e.g. 20160703 = 3.7.2016).
8.9.2.3.2.Answer
A data object is not present in the HS/FS reply.