KO-Gateway Interface
Content
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).
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.

COMMANDDescriptionVAL
1Set value absoluteFloat 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"}
2Set value relativeFloat
3Step+is not specified
4Step-is not specified
5List+is not specified
6List-is not specified

2.3.3.Telegram from HS/FS

3 different types of telegrams can be sent from the HS/FS:
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.
AttributeDescription
idUnique number of the communication object
used1 = Communication object is used in the project.
0 = not used.
typeType of communication object

"internal" = internal communication object
"eib" = KNX communication object
pathFolder in which the communication object is stored in the HS/FS Expert.
fmtData 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
fmtexData format 2

integer
number
text
date
time
unknown
nameName of the communication object
rem1 = remanent in HS/FS
0 = not remanent
initInit value
minMinimum value
maxMaximum value
stepStep size
listList
gaGroup address as recorded in the HS/FS expert
ganumGroup address (numeric)
cogwsSend KO Gateway
cogwrReceive KO Gateway
scan1 = Query at startup
0 = Do not query at startup
sbc1 = Send by Change
0 = no Send by Change
read1 = readable
0 = not readable
transmit1 = Transfer
0 = not transmitted