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).
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
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 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
- 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:
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".
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.
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:
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).
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
x/z is converted to
Numerical -> Expert
In its numerical form, the group address is specified in the attribute "ganum" in the XML file.
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 ignoredy = (GRPADR - x*2048) / 256
, decimal places are ignoredz = (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:
or
The specification of the parameters 3. ("value") and 4. ("encoding") is optional and depends on the 1. parameter "cmd". See the following table.
{"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:
2.3.3.1.Initialisation
This telegram is sent after a restart for each K-object communicated via the KO gateway.
Structure:
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:
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:
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.
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:
Data structure of the XML file (example):
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 |
fmtex | Data format 2 integer |
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 |