Expert - Communication object gateway interface

This interface is used for easy communication with the HS/FS using one's own software. Whenever a communication object is changed, the HS/FS sends a telegram. To this end, the communication objects are indicated individually or globally.

This interface is available in variant 1 (compatibility mode) from HS/FS firmware v2.2.

Variant 2 is available from HS/FS firmware v4.7: Encrypted communication via WebSockets (https).

1.Communication protocol

1.1.Type of access

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

Activate WebSocket
Activate compatibility mode

An HS Monitor is available for both methods as a connection to the communication object gateway interface.

Activate 1.1.1.WebSocket

This enables 10 concurrent accesses to the HS/FS.

The version of HS Monitor working with this method is an integral part of the Expert software and must be activated in the section Master data -> Project settings -> Interface:

Either

the option All must be activated

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

HS Monitor is then also transferred to the HS/FS and can be called up using a browser via the following URL:

HTTPS://HS_IP/opt/hsmonitor/index.html

IP-ADR is the IP address of the HS/FS, if necessary, supplemented by an HTTPS port activated in HS/FS Expert under "Project settings -> Network -> Security".

1.1.2.Compatibility mode

This method is available from firmware v2.2 and enables an unencrypted connection with the HS/FS.
10 concurrent accesses to the HS/FS are possible using this method.

The version of HS Monitor working with this method is a program that can be run on Windows PCs (hsmonitor.exe, from v4.7 no longer included in delivery).
This method can used in parallel with access via WebSockets.

2.Information for developers

2.1.Authentication

A URL must be specified for establishing the WebSocket connection for one's own software to the HS/FS. 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, if necessary, supplemented by an HTTPS port activated in HS/FS Expert under "Project settings -> Network -> Security".

AUTH is the corresponding code specified in Expert under "Project settings -> Network -> Communication object gateway". Base64-coded must be specified here.

If 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 responds with status code 400 (Bad Request).

Important

After failed authentication the IP address of the client is locked for 5 seconds. In this time the device always returns status code 503 to requests.

2.2.Start-up behaviour

When the device starts, the HTTP server is already available before completion of initialisation. In this time the device always returns status code 503 to all requests. The response also contains the HTTP header "Retry After". This field can be evaluated in order to automatically start a new attempt after the specified time in seconds.

2.3.Communication

Communication with the HS/FS is carried out using data in the form of JSON structures.

2.3.1.Group address conversion

The group address is specified in HS/FS Expert in the form x/y/z or x/z. The group address is specified in a numeric format in telegrams sent to the HS/FS and telegrams coming from the HS/FS. The conversion is carried out 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

Numeric -> 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 numeric 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]} (with cmd = 1,2)

or

{"cmd": COMMAND, "ga": GRPADR} (with cmd = 3,4,5,6)

COMMAND is an integer of 1 to 6. See the following table for an explanation.

GRPADR is the group address. It must be specified numerically and can be calculated from the formats used in Expert.

The specification of the 3rd parameter "value" is optional and depends on the 1st. See the following table.

`COMMAND`	Description	`VAL`
1	Set value absolute	Float or Text, depending on the communication object in question. A text must be specified base64-coded!
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 the HS/FS

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

Initialisation
Initialisation complete
Subsequent telegram

2.3.3.1.Initialisation

After a restart, this telegram is sent for every communication object communicated via the communication object gateway.

Structure:
{"cmd": 2, "ga": GRPADR, "value": VAL]}

GRPADR is the group address. It must be specified numerically and can be calculated from the formats used in Expert.

VAL can be an integer or a string. If it is a string, it is base64-coded.

2.3.3.2.Initialisation complete

This telegram is sent by the HS/FS if initialisation of all communication objects communicated via the communication object gateway is completed after a restart.

Structure:
{"cmd": 2}

2.3.3.3.Subsequent telegram

This telegram is sent if a value was assigned to the specified communication object. This also happens if the former value matches the new value of the communication object.

Structure:
{"cmd": 1, "ga": GRPADR, "value": VAL]}

GRPADR is the group address. It must be specified numerically and can be calculated from the formats used in Expert.

VAL can be an integer or a string. If it is a string, it is base64-coded.

2.4.Name of the communication objects in plain text

The names of the communication objects can be called up via the following URL as an XML file.

HTTPS://HS_IP/opt/sys/cobjects.xml

IP-ADR is the IP address of the HS/FS, if necessary, supplemented by an HTTPS port activated in 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 the fields are edited in HS/FS Expert in the program item communication objects. More information in the fields can be found in the HS/FS Expert online help on communication objects.

Attribute	Description
id	Unique number of communication object
used	1 = Communication object is used in the project. 0 = not used.
type	Type of communication object "internal" = internal communication object "eib" = EIB communication object
path	Folder in which the communication object is stored in the HS/FS Expert.
fmt	Data format 1 Plain text (texts are located 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 = retentive in the HS/FS 0 = not retentive
init	Initialisation value
min	Minimum value
max	Maximum value
step	Step size
list	List
ga	Group address as entered in HS/FS Expert
ganum	Group address (numerical)
cogws	Send communication object gateway
cogwr	Receive communication object gateway
scan	1 = Query during starting 0 = Don't query during starting
sbc	1 = Send by Change 0 = no Send by Change
read	1 = can be read out 0 = cannot be read out
transmit	1 = Transfer 0 = Do not transfer