Communication objects
Contents
1.
2.
3.
4.
5.
6.
7.

1. Introduction

In EIB/KNX, communication objects (CO) represent an actuator or sensor value.
The HS/FS requires these communication objects to create the process image and change actuator values.
Based on the term "communication object", there are also internal communication objects, which are also essential for the process image and are used as variables.

You create folders (e.g. lighting, heating) here for the functions, the internal communication objects and EIB objects (group addresses) that are to be controlled via the HS/FS. The internal communication objects are not sent by the HS/FS on the EIB and are primarily used as help variables in the logic or for control in the HS/FS, etc. The EIB objects are designated as external communication objects. To simplify matters, this information is designated as communication objects with the HS/FS (internal or external). You can create your own objects or import them from the ETS (see Import ). How many of these objects can be created in the expert is dependent on the free memory in the HS/FS.

The current values of internal communication objects are retained when the HS/FS is restarted of necessary. For this purpose, each communication object has the retentive memory mark.

EIB objects can be read out in the following variants:
- via the bus after a restart (Query during starting)
- individual (Command query)
- all (Command EIB scan)
.
To create an internal or external communication object, switch to the "Communication Objects" window. Select the "Internal" or "EIB" tab in the tab. Right-click a node in the tree view. A pull-down menu opens. Select "Create object". To ensure a better overview, you can also sort several communication objects that belong to a group into folders. These can be created like communication objects.

In the "EIB" view, you can import EIB objects using various methods. For this purpose, press the "Import" button next to the EIB objects.

2. Functions accessible by right-clicking the tree structure (left)

The functions are available in the tree structure (to the left in the window), depending on the selected element (folder, communication object).
  • Cut: This moves an element from one folder to another. The related command is: Paste. Cut objects do not change their appearance.
  • Copy
  • Insert
  • Duplicate
  • Remove
  • Convert (EIB<=>Internal): The marked communication object is converted. If an EIB object is marked, it becomes an internal object. If an internal object is marked, it becomes an EIB object.
    Note: If the marked object is located in a folder, the folder structure (the 'path') is simulated on the target page during conversion if it does not exist.
  • References: If a communication object is used in the project, its use can be displayed here.
  • Sort according to group address (only available in "EIB" view):
    Yes: Sorting occurs by group address.
    No: Sorting occurs based on the designation.
  • Create folder
  • Rename folder
  • Create object
  • Create watch address (ONLY in the "EIB" view!)
  • Create central address (listening address) (ONLY in the "EIB" view!)
Note
Empty folders are deleted when the program item is exited!

3. Function buttons in the header

  • Close: The mask is exited.
  • Import: This opens a mask for the import from the ETS (only available in "EIB" view).
  • New: This creates a new communication object.
  • Remove: The selected communication object is deleted.
  • Search: This opens the search mask.
  • Help: Opens this help function.

4. Tools menu

4.1. Import (only available in “EIB” view)

  • Import ETS print file: This opens a mask for the import from the ETS print file.
  • Import OPC file: This opens a mask for the import from the ETS-OPC file.
  • Import HSXML file: This opens a mask for the import from the ETS3-HSXTML file.
  • Import ETS4 project file: This opens a mask for the import from the ETS4 project file.
Endpoint IDs are assigned automatically during the import. These correspond to the group address of the respective communication object.
Example: The CO with GrpAdr 1/0/3 is assigned the endpoint ID CO@1_0_3.

4.2. Export

4.2.1. Export as XML structure

Communication objects can be exported to an XML file with this.
All communication objects from the current project (internal and external) are exported with all their properties.

4.2.2. Used objects as text list

Communication objects can be exported to a TXT file with this.
Only the objects used in the project currently being viewed actively (either internal or EIB) are exported.
For each communication object, each line contains the path\name and group address (if defined), separated with vertical lines ("|").
Example: System\System (after start always 1)|100/0/1

4.2.3. Used objects as CSV file

Communication objects can be exported to a CSV file with this.
Only the objects used in the project currently being viewed actively (either internal or EIB) are exported.
Each line contains the name of the communication object enclosed in quotation marks and the group address separated by a semicolon (";"). A header with column names is created.
This file can then be imported in ETS3 in the "Group addresses" view.
Example: "System (after start always 1)"100/0/1
Warning
This file cannot be re-imported to the Expert! For more information, see Export as CSV and Synchronise/import CSV file.

4.3. Data calibration

This enables mass changes to communication objects using an external program.
An internally unique ID is used here which is assigned to each communication object automatically and invisibly for the user when creating the communication object. Details on this topic are contained in the following descriptions on exporting and importing/synchronisation.

4.3.1. File structure

1stline: Headers
2nd-nth line: Data; 1 line for each communication object

Each line contains the fields: ID, Text, Format, Default, Min, Max, Step, List, GrpAdr, Scan, Change, Read, Transmit, and Ret. See the following table for more details.
The individual values are enclosed in quotation marks and separated by semicolons when they are exported from the Expert.
Note
After editing the CSV file with programs such as "Microsoft Excel" or "LibreOffice Calc", the file is saved without quotation marks. This does not matter when re-importing to the HS/FS Expert!
However, in these cases please ensure that semicolons are used as separating characters when saving the file and that the file is not opened for editing when it is being imported to the Expert.
Field name Description
ID Unique identification number of the CO for the Expert.
IS ONLY ASSIGNED BY EXPERT!!!
To create a new CO, the value "0" (zero, as a number) must be used. (see example below this table)
Text Path and name of the CO Only letters and digits can be used, as well as underscores and hyphens.
Syntax: [[Path]\][CO]

Explanation:
[[Path]\] (optional): [directory name_1]\[directory name_2]\...[directory name_n]\
[CO] (mandatory): Name of the communication object.
If a path is specified, it will be shown as a tree structure in the Expert.

Example 1:
A communication object named "Wind speed (east)" is to be created in a folder called "East side", which is located in a folder called "Outdoors":
East side\Outdoors\Wind speed(east)

Example 2:
A communication object called "Brightness" (without folder structure) is to be created:
Brightness
Format Abbreviation for the data type of the communication object, values from 0 to 15 (see Format code)
Default Init. value
Min Min. value
Max Max. value
Step Step size
List List
GrpAdr Group address
Scan Query during starting (only EIB CO)
Change Only send in case of change (only EIB CO)
Read Read flag (only EIB CO)
Transmit Transfer flag (only EIB CO)
Ret Retentive memory
COGW read Receive communication object gateway
COGW write Send communication object gateway
Endpoint ID Endpoint ID without the prefix "CO@".
Endpoint Description Description of the endpoint
Endpoint Tags Tags
Endpoint read User groups that are allowed to read out this communication object via endpoints.

The number in the ".csv" file is calculated as follows:
Total( (2 to the power of UGN) * Status)
UGN: User group number as a sequential number starting with 0
Status: Activated = 1, Deactivated = 0

Example: From a total of 16 user groups, the first, third and fourth are activated:
 2^0 * 1 + 2^1 * 0 + 2^2 * 1 + 2^3 * 1 + 2^4 * 0 + ... + 2^15 * 0
=   1    +    0    +    4    +    8    +    0    + ... +     0    = 13
Endpoint write User groups that are allowed to write this communication object via endpoints.
Calculation the same as for "Read endpoints".

4.3.2. Export as CSV

Communication objects can be exported to a CSV file with this.
All communication objects of the view currently active (either internally or EIB) are exported.
With an export, each data record contains all data of the communication object including a unique ID. The CSV file created with the export can be changed with an external program and then reimported.
Example: "5";"System\System (after start always 1)";0;"0";"0";"1";"0";"";"";0;0;0;0;0;0;0;"";"";"";1;1

4.3.3. Synchronise/import CSV file

Communication objects can be imported from a CSV file with this.
The specified data format of the CSV file is described in the File structure.
For each communication object contained in the CSV file, the same communication object is searched for in the Expert using the unique ID and overwritten with the data from the CSV file!

Data records with ID not equal to 0 (zero):
If an ID listed in the CSV file is not found in the Expert, the entry in the CSV file will be ignored for this communication object during the import.

Data records with ID equal to 0 (zero):
Data records in the CSV file with an ID of 0 (as a number) are re-created in the Expert during the import. The Expert automatically assigns unique IDs for these communication objects.
Example of creating a 1-bit CO: "0";"My new CO";0;"0";"0";"1";"0";"";"101/0/1";0;0;0;0;0;0;0;"";"";"";1;1
Note
To obtain a sample file in the valid format, simply use the Export as CSV function. There must already be at least one communication object in the current view.

4.4. Jump to group address (F2)

You can jump directly to the desired communication object in the project by entering a group address.

4.5. Search (F3)

This opens the search mask.

4.6. Assign group addresses (only available in "Internal" view)

Select a start address from the combination box. All internal communication objects, which have not yet been assigned an address, receive a new group address and a corresponding endpoint ID, starting with the one selected.
In the process, the right-hand number is increased first, then the middle number and then the left-hand number. For information regarding the valid range, please see: Group address.
Example: The CO with GrpAdr 100/0/3 is assigned the endpoint ID CO@100_0_3.
Note
Please note that it is not possible to distinguish between manually and automatically assigned numbers when automatically removing group addresses!

4.7. Remove group addresses (only available in "Internal" view)

Select a start address from the combination box. The group address is removed for all internal communication objects with a group address greater than or equal to the one selected. It is not possible to distinguish between group addresses entered manually or generated automatically!
In this case, the following applies (example): The group address 101/0/1 is higher than the group address 100/7/254. For all communication objects whose group address is within the selected range, the endpoint ID is also removed if it is the same as the group address!
Example:
a) CO with GrpAdr 100/0/3 and endpoint ID CO@100_0_3 => endpoint ID is removed.
b) CO with GrpAdr 100/0/4 and endpoint ID CO@my_endpoint => endpoint ID is not removed.
Note
Please remember that xxx/yy is only a different way of writing xxx/0/yy.

4.8. Clean up communication objects:

Only the objects not used in the project currently being viewed actively (either internally or EIB) are removed.

5. Tabs

5.1. Data

Designation

This designation is used to refer to the object in the HS/FS Expert. The designation is also used in the EIB monitor.
The endpoint interface can be used to search for communication objects for which a word in the designation starts with the search term used there.

Data type

The data format of the object is specified here. The following data formats are available:
HS data type code Data type Description
0 1-bit switch/bli (0..1/EIS 1,2,7)
1 8-bit (0..100%/EIS 6)
2 8-bit (RTC status)
3 16-bit (-671088,64..670760,96/EIS 5)
4 8-bit (0..255/EIS 2.6)
5 8-bit (-128..127)
6 16-bit (0..65535/EIS 10)
7 16-bit (-32768..32767/EIS 10)
8 32-bit (0..4294967295/EIS 11)
9 32-bit (-2147483648..2147483647/EIS 11)
10 14-byte Text
11 Time (EIS 3)
12 Date (EIS 4)
13 4-bit (Dimming)
14 4-byte (EIS 9/IEE floating decimal value)
15 2-bit restraint (EIS 8)
16 Dali error status (see also logic nodes)
17 Group feedback object (see also logic nodes)
18 3-byte (0..16777215)
Note
The HS data type code is an internal characteristic for the Expert, HS/FS and data import/export.
Note
Communication objects of the 14-byte data type can contain up to 30,000 bytes (characters) in the HS/FS. The length of the communication object is not limited to 14 bytes until it is sent on the EIB. If the 14-byte communication objects are retentive, the size is limited to 10,000 bytes (characters) when saving.

Retentive memory

Yes, save communication object retentively.
Note
If this attribute is used, "Query during starting" is not possible. Communication objects of type time, date or 4-bit (dimming) cannot be saved retentively.
Note
The retentive data are read in during system start and immediately written to the communication object and sent on the EIB if applicable. More detailed information on the system start and processing of the logic/communication objects can be found in a separate document.

Init. value

When the HS/FS is started, this value is set and decimal places are rounded off if necessary.
This value is set if it is not or cannot be read out of the EIB object via the bus.
To ensure that the HS/FS reads the value from the EIB when starting, the "Query during starting" option (see below) must be set in this communication object!
This value is used in the so-called process image.

Min. value, max. value

These two values set the minimum/maximum values that are output on the EIB by the HS/FS (regarding the object currently selected).
These limits are automatically specified according to the data type when an object is created, but they can be modified, given that: "Min. value" and "Max. value" cannot be exceeded.
This range is independent of the value of the actuator/sensor on the EIB.
Among other things, programming errors that write smaller/larger values to the object than intended can be globally suppressed here.
In all cases in which the object would be assigned a value greater than "Max. value”, the object would be set to "Max. value” instead.
In all cases in which the object would be assigned a value less than “Min. value”, the object would be set to "Min value” instead.

Step size

This constant is used by a command. The actuator can be increased or decreased by the constant with this command.
For example, a dimmer can be increased or decreased by 17%; the initial value is the current value of the actuator.

List

A list of values is compiled here. The actuator is adjusted based on the values specified in the lists, e.g. "10,28,68,95"; the initial value is the current value of the actuator. Assuming this, the next value in the list is used. These constants are used by a command. In the previous example, a dimmer jumps from 0% to 10%, then to 28% etc. If the dimmer is at 80% and the value is reduced according to the list, the value drops to 68%.
Note
The list must be sorted in ascending order.

Group address

The group address is recorded here.
The two-digit and three-digit syntax is possible.

The valid ranges for external (EIB) communication objects are:
  • 2-digit specification: 0-15 / 0-2047
  • 3-digit specification: 0-15 / 0-7 / 0-255
The valid ranges for internal communication objects are:
  • 2-digit specification: 100-199 / 0-2047
  • 3-digit specification: 100-199 / 0-7 / 0-255
Group addresses are always unique within a project.
They may be issued only once.
Any non-number, e.g. blank spaces, can be used to separate the numbers.
Every non-number is automatically converted to "/" here.
Note
Internal communication objects require only one group address if they are to be recorded in the EIB monitor or evaluated via the communication object gateway.

Query during starting (only in EIB view)

Yes: The HS/FS reads the value of the EIB object from the EIB after a restart. Note here that the read flag with the ETS must be set for this object. Each EIB object that does not respond delays starting by several seconds! This option should be checked precisely, as a high bus load is generated during starting (see also Project/EIB). This option affects the formation of the process image.
Note
This attribute cannot be used with the retentive attribute!
Note
If the project is transferred without scanning, this setting is ignored.

Only send in case of change

Yes: Sends the value of the actuator on the EIB if it has changed in the HS/FS. (Only if "transfer flag" was set for currently selected object). This option is used to minimise the telegram load.
No: Default setting; sending the value is triggered by a command.
Note
If this option is used, the "Query during starting" option (see above) should also be used in this communication object. This allows many "misunderstandings" to be avoided.

Read flag

Yes: The value can be exported from the HS/FS by another EIB device.
No: Default setting

Transfer flag

Yes: Default setting; all telegrams generated by or via the HS/FS are sent on the bus (refers to object currently selected).
No: No telegrams are sent by the HS/FS on the EIB.
Note
The value changes are shown in the EIB monitor of the HS/FS.

Receive communication object gateway

Yes: This communication object can be changed via the Project/Communication object gateway from the outside.

Send communication object gateway

Yes: If a telegram is generated, the value of this communication object is sent via the Project/Communication object gateway.

5.2. Endpoint

Communication objects can be accessed via the endpoint interface of the HS/FS.
A description of the call parameters can be found here.
Note
Instead of the communication object used in all call examples in the table below, you can, of course, use any communication object.

Placeholders are specified in UPPER CASE.

5.2.1. Methods

Method Description/Call
meta Call the communication object’s meta data.
https://HS_IP/endpoints/call?key=CO@100_2_3&method=meta&user=USER&pw=PWD
get Call the current value.
https://HS_IP/endpoints/call?key=CO@100_2_3&method=get&user=USER&pw=PWD
set Set a value. (Value=7)
https://HS_IP/endpoints/call?key=CO@100_2_3&method=set&value=7&user=USER&pw=PWD
toggle Switch between 0 and the specified value. (Value=1)
https://HS_IP/endpoints/call?key=CO@100_2_3&method=toggle&value=1&user=USER&pw=PWD
add Add a value. (Value=25)
https://HS_IP/endpoints/call?key=CO@100_2_3&method=add&value=25&user=USER&pw=PWD
offset_plus Increase the current value by one step.
https://HS_IP/endpoints/call?key=CO@100_2_3&method=offset_plus&user=USER&pw=PWD
offset_minus Decrease the current value by one step.
https://HS_IP/endpoints/call?key=CO@100_2_3&method=offset_minus&user=USER&pw=PWD
list_next Set the value of the communication object to the next higher value in the list.
https://HS_IP/endpoints/call?key=CO@100_2_3&method=list_next&user=USER&pw=PWD
list_prev Set the value of the communication object to the next lower value in the list.
https://HS_IP/endpoints/call?key=CO@100_2_3&method=list_prev&user=USER&pw=PWD

5.2.2. Fields

ID
The value entered here, together with the fixed prefix "CO", which connects the ID via the '@’ character, forms the unique object key of the endpoint.
Permitted characters include: A-Z, a-z, 0-9, hyphen ("-") and underscore ("_")!
If a group address is assigned for the communication object, the ID is also assigned automatically, whereby forward slashes ("/") are replaced by underscores ("_").
Description
A meaningful description of the communication object.
The endpoint interface can be used to search for communication objects for which a word from the description starts with the search term used there.
Tags
A list of terms, separated by commas (“,”).
The endpoint interface can be used to search for communication objects for which single tag is a complete match for the search term used there.
Permitted characters include: A-Z, a-z, 0-9, hyphen ("-") and underscore ("_")!
User groups
Warning
This item is only available if user groups have been activated!
User groups can be authorised to access this communication object via the endpoint interface with read (left column) and/or write (right column) access.

6. Watch address

Each communication object can be assigned any number of watch addresses (watch objects). If one of the watch objects changed on the bus or in the HS/FS, the value of the EIB object the watch address is assigned to is queried on the bus.
For example, dimming objects and switching objects for the brightness value of a dimmer are entered here.

Background: Watch objects arose from the need to have the HS/FS display the correct brightness value (%) (i.e. the current status). If a 1-bit or 4-bit telegram is transmitted with a push button sensor in the building, the brightness value changes. However, it is not updated by normal (older) dimming actuators. For this reason, switching and dimming are appended as a watch group address to the brightness value used for display in the HS/FS. If something happens there, the communication object (brightness value) is queried on the bus.

If a modern dimming actuator has a feedback object for the brightness value, then watch group addresses can be dispensed with.
Note
Can be reached by right-clicking a communication object in the "EIB" view.

7. Central address

Each communication object can be assigned any number of central addresses (central objects). When one of the central addresses (with value) is received by the HS/FS, all EIB objects which were assigned this central address are set to the value of the central object.

Example: There is a "LIGHT ground floor" object and 20 further "Light switch" objects for individual rooms on the ground floor.
If the "LIGHT ground floor" object is now set to "OFF", all 20 "Light switch" objects on the ground floor which were assigned "LIGHT ground floor" as a central address are also set to "OFF".
Note
Can be reached by right-clicking a communication object in the "EIB" view.