KO-Gateway Interface
Content
1.
Communication protocol
1.1.
Type of access
1.1.1.
Activate Websocket
1.1.2.
Compatibility mode
2.
Information for developers
2.1.
Authentication
2.2.
Starting behaviour
2.3.
Communication
2.3.1.
Group addresses Conversion
2.3.2.
Telegram to the HS/FS
2.3.3.
Telegram from HS/FS
2.4.
Plain text names of the K-objects
This interface is used for simple communication with the HS/FS using your own software. The HS/FS sends a telegram each time a K-object is changed. For this purpose the K-objects are marked individually or globally.
This interface is available in variant 1 (compatibility mode) since HS/FS-Firmware v2.2
From HS/FS-Firmware v4.7 onwards, there is variant 2: Encrypted communication via web sockets (https).

## 1.Communication protocol

### 1.1.Type of access

In order to be able to communicate with the HS/FS via the KO-Gateway interface, at least one of the two access methods must be activated in the expert (under Project settings -> Network -> KO-Gateway).

- ActivateWebsocket
- Activatecompatibility mode

For both methods a HS monitor is available as a connection to the KO-Gateway interface.

#### 1.1.1.Activate Websocket

This allows 10 simultaneous accesses to the HS/FS.
The version of HS-Monitor working with this method is a fixed component of the expert software and must be activated under the heading Master data -> Project settings -> Interface:
Either

- the option All must be activated

or

- the option User defined must be activated
  and
- the checkbox hsmonitor must be activated.

HS-Monitor is then transferred to the HS/FS and can be called up via a browser using the following URL:
`HTTPS://HS_IP/opt/hsmonitor/index.html`
IP-ADR is the IP address of the HS/FS, possibly supplemented by one of the HTTPS ports activated in the HS/FS expert under "Project settings -> Network -> Security".

#### 1.1.2.Compatibility mode

This method is available from firmware v2.2 on and enables an unencrypted connection to the HS/FS.
10 simultaneous accesses to the HS/FS are possible with this method.
The version of HS-Monitor that works with this method is a program that can be executed on Windows PCs (hsmonitor.exe, from v4.7 no longer included).
This method can be used in parallel with access via WebSockets.

## 2.Information for developers

### 2.1.Authentication

To establish the web socket connection for own software to the HS/FS, a URL must be specified. The URL to be used contains the necessary authentication and must be structured as follows:
`wss://HS_IP/cogw?authorization=AUTH`
IP-ADR is the IP address of the HS/FS, possibly supplemented by one of the HTTPS ports activated in the HS/FS Expert under "Project settings -> Network -> Security".
AUTH is the appropriate key specified in the expert under "Project settings -> Network -> KO-Gateway". It must be specified base64-coded here.
If authentication fails, no connection is 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).
Attention
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.

### 2.2.Startup behavior

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". This field can be evaluated to automatically retry after the specified time in seconds.

### 2.3.Communication

The communication with the HS/FS is done by means of data in the form of JSON structures.

#### 2.3.1.Group addresses Conversion

The group address is specified in the HS/FS expert in the form x/y/z or x/z. In the telegrams sent to the HS/FS and those coming from the HS/FS, the group address is given in a numerical format. The conversion is done as follows:
Expert -> numerical
x/y/z is converted to `GRPADR = x*2048 + y*256 + z`
x/z is converted to `GRPADR = x*2048 + z`
Numerical -> Expert
`x = GRPADR / 2048` , decimal places are ignored
`y = (GRPADR - x*2048) / 256` , decimal places are ignored
`z = (GRPADR - x*2048 - y*256)`
In its numerical form, the group address is specified in the attribute "ganum" in the XML file.

#### 2.3.2.Telegram to the HS/FS

Structure:
`{"cmd": COMMAND, "ga": GRPADR, "value": VAL, "encoding": ENCODE]}` (with cmd = 1.2)
or
`{"cmd": COMMAND, "ga": GRPADR}` (with cmd = 3,4,5,6)
`COMMAND` is an integer from 1 to 6, see table below for explanation.
`GRPADR` is the group address. It must be given numerically and can be calculated from the formats used in the Expert.
The specification of the parameters 3. ("value") and 4. ("encoding") is optional and depends on the 1. parameter "cmd". See the following table.

`COMMAND` | Description | `VAL`
--- | --- | ---
1 | Set value absolute | Float or text, depending on the respective K-object. A text can be base64 encoded if required (e.g. if it contains binary data). For this purpose the additional field "encoding" must be specified and set with the value "base64". FOR EXAMPLE `{"cmd": 1, "ga": 204854, "value": "YmVpc3BpZWw=", "encoding": "base64"}`
2 | Set value relative | Float
3 | Step+ | is not specified
4 | Step- | is not specified
5 | List+ | is not specified
6 | List- | is not specified

#### 2.3.3.Telegram from HS/FS

3 different types of telegrams can be sent from the HS/FS:

- Initialisation
- Initialisation completed
- Follow-up telegram

##### 2.3.3.1.Initialisation

This telegram is sent after a restart for each K-object communicated via the KO gateway.
Structure:
`{"cmd": 2, "ga": GRPADR, "value": VAL]}`
`GRPADR` is the group address. It must be given numerically and can be calculated from the formats used in the Expert.
`VAL` can be an integer or a string. If it is a string, it is base64 encoded.

##### 2.3.3.2.Initialisation completed

This telegram is sent by the HS/FS if the initialisation of all K objects communicated via the KO gateway is completed after a restart.
Structure:
`{"cmd": 2}`

##### 2.3.3.3.Follow-up telegram

This telegram is sent when a value has been assigned to the specified K-object. This happens even if the previous value matches the new value of the K-object.
Structure:
`{"cmd": 1, "ga": GRPADR, "value": VAL]}`
`GRPADR` is the group address. It must be given numerically and can be calculated from the formats used in the Expert.
`VAL` can be an integer or a string. If it is a string, it is base64 encoded.

### 2.4.Plain text names of the K-objects

The names of the communication objects can be retrieved as XML file via the following URL.
`HTTPS://HS_IP/opt/sys/cobjects.xml`
IP-ADR is the IP address of the HS/FS, possibly supplemented by one of the HTTPS ports activated in the HS/FS expert under "Project settings -> Network -> Security".
Example: `HTTPS://192.168.0.11:443/opt/sys/cobjects.xml`
Data structure of the XML file (example):
`<cobject
id="911"
used="0"
type="eib"
path="01 Lighting\2nd Floor\"
fmt="EIS1+EIS2+EIS7_1BIT"
fmtex="integer"
name="FL02 Light"
rem="0"
init="0"
min="0"
max="1"
step="0"
list=""
ga="1/2/1"
ganum="2561"
cogws="1"
cogwr="0"
scan="1"
sbc="1"
read="0"
transmit="1"
/>`
All fields are edited in the HS/FS Expert in the programme item Communication objects. Further information on the fields can be taken from the online help of the HS/FS expert on the communication objects.

Attribute | Description
--- | ---
id | Unique number of the communication object
used | 1 = Communication object is used in the project. 0 = not used.
type | Type of communication object "internal" = internal communication object "eib" = KNX communication object
path | Folder in which the communication object is stored in the HS/FS Expert.
fmt | Data format 1 Plain text (texts are in the file minmax.txt in the expert subdirectory "/dat") `EIS1+EIS2+EIS7_1BIT EIS6_8BIT NONEIS_8BIT_RTR EIS5_16BIT EIS2+EIS6_8BIT EIS?_8BIT EIS10_16BIT_UNSIGNED EIS10_16BIT_SIGNED EIS11_32BIT_UNSIGNED EIS11_32BIT_SIGNED EIS?_14BYTE EIS3_3BYTE_TIME EIS4_3BYTE_DATE EIS?_4BIT EIS9_4BYTE EIS8_2BIT EIS?_DALI EIS?_SRO EIS?_3BYTE`
fmtex | Data format 2 `integer number text date time unknown`
name | Name of the communication object
rem | 1 = remanent in HS/FS 0 = not remanent
init | Init value
min | Minimum value
max | Maximum value
step | Step size
list | List
ga | Group address as recorded in the HS/FS expert
ganum | Group address (numeric)
cogws | Send KO Gateway
cogwr | Receive KO Gateway
scan | 1 = Query at startup 0 = Do not query at startup
sbc | 1 = Send by Change 0 = no Send by Change
read | 1 = readable 0 = not readable
transmit | 1 = Transfer 0 = not transmitted