KNX Utility

The KNX Utility application provides a graphical interface to configure a KNX I/O Server. Whenever a KNX I/O server is defined in HSYCO, the KNX Utility will appear among the applications of the manager.

Open the application and select the KNX I/O Server to be configured in the select field in the top-left corner. If only one KNX I/O Server is defined it will be automatically selected. The indicator next to the select field reports whether the selected I/O Server is currently online or offline.

The KNX Utility configures the datapoints of the I/O Server, that is the content of the knxtopo.txt file. The communication parameters, including the choice between the Tunneling and the Routing service and the KNX IP Secure settings, are configured with the options of the I/O Server. The utility, and its bus monitor, work over the transport configured there, with no further setting.

The datapoints are organized in the "Datapoints", "Lights", "Dimmers", "RGBs", "Automations" and "Thermostats" tabs.

Saving the configuration

Changes made in the tables are kept in memory until they are saved. The "Save" button at the bottom-right of the page is enabled as soon as there is something to save, and writes the new configuration to knxtopo.txt.

If the selected I/O Server is online, saving also restarts it so that the new configuration is applied, which interrupts the bus communication while it reconnects: a confirmation popup asks to proceed before committing. If the I/O Server is offline, the configuration is saved with no confirmation.

The knxtopo.txt file is also monitored continuously: if it is modified outside the utility, for example with a text editor, the tables are reloaded to show the new content of the file, and an I/O Server that is online restarts to apply it. This happens whether the utility is open or not, and for every KNX I/O Server, including the ones that are not running.

note

A change to the file always prevails over the tables. Changes made in the tables and not yet saved are lost when the file is reloaded, so avoid editing knxtopo.txt outside the utility while an editing session is in progress.

Gateway discovery

The "Discovery" button at the bottom of the page searches the network for KNXnet/IP gateways and shows what each one reports about itself. It is a survey tool: it does not change the configuration. Use it to find the address of a gateway, to check which services it offers before choosing between Tunneling and Routing, or to verify that a gateway is reachable at all. The values it reports are then entered manually in the options of the I/O Server.

The search is sent to the KNX system setup multicast group, 224.0.23.12 on port 3671, and the answers are collected for three seconds. If the selected I/O Server defines a localhost option, the search goes out on that network interface, otherwise the default interface of the host is used. Gateways on another subnet, or behind a router that does not forward multicast traffic, do not answer and are not listed. Click "Search" to repeat the search, for example after powering up a gateway.

For each gateway that answers, the table reports:

• Name: the friendly name the gateway is programmed with
• Address: IP address and port of the control endpoint of the gateway, as advertised in its answer. These are the values to use in the host and port options of the I/O Server for the Tunneling service
• Indiv. Addr.: the individual address of the gateway device
• Serial: the serial number of the device, in hexadecimal
• IP Secure: none if the gateway does not offer KNX IP Secure, supported if it offers it without requiring it, or the list of the services that can only be used in secure mode, tunneling, routing or tunneling + routing
• Slots: the number of free tunneling connections and the total number of connections the gateway can serve. A gateway with no free slots refuses new tunneling connections, even if it answers the discovery

note

Older gateways that do not implement the extended search do not report their tunneling slots, and for those the "IP Secure" column can only tell whether the feature is supported, not whether it is required.

Import an ETS4/5/6 project

To import an ETS project, click on the "Import" button at the bottom of the page to open the Import popup where you can specify some options:

• Update Matching Datapoints: Compares the existing and imported KNX Datapoints to look for address or description matches. If found, related Datapoints will be updated, non-matching imported.
• Delete Non-Matching Datapoints: Deletes any existing Datapoints that do not match any of the imported ones. It is only enabled, and only has an effect, together with Update Matching Datapoints
• Matching Keywords: Comma separated words, case-insensitive, that are looked for in the Datapoint description. If found, the related 'Read' attribute will automatically be set to 'True', otherwise to 'False'
• Delete Virtual Datapoints: If set, all defined Virtual Datapoints will be deleted
• Project Password: the password of the ETS project file, for password-protected projects. Leave it empty for unprotected projects

After selecting these options, click "Next" and drag and drop a ".knxproj" file or select one using the prompt.

The Import procedure will start, and after some seconds the status should be successful or in error state.

By clicking next, if Update Matching Datapoints or Delete Non-Matching Datapoints were selected, a preview of the Datapoints that will be imported is shown, in the "New", "Delete", "Update", "No DPT" and "Skip" tabs, each tab reporting how many Datapoints it contains. It is possible, from the "New" table, to deselect Datapoints to exclude them from the import. The "No DPT" table stores all Datapoint whose DPT is missing; they are created with DPT 1 unless another type is chosen. By clicking the "DPT" cell, it is possible to in-line edit the DPT type directly before import. When done, press "Confirm" to import all selected Datapoints.

At the end, this procedure will create a datapoint for each imported one, with the corresponding DPT Type and attributes.

Datapoints

A datapoint is the equivalent of a Group of the KNX framework. New datapoints can be added employing the import procedure described above or manually, by clicking on the "+" button int the table footer in the "Datapoints" tab. To modify the attributes of a datapoint click on the 'Edit' button for the corresponding item.

Attributes

• Address: this is the KNX group address corresponding to this datapoint ranging from 0/0/1 to 31/7/255. It must be unique for each defined datapoint, and it can't be changed after the datapoint is created
• DPT: the DPT type used to format the datapoint value. The DPT types from 1 to 30, and the DPT types 232, 245 and 251, are supported: see Supported Datapoint types and values. It can't be changed when the datapoint is used by a virtual datapoint
• DPT Sub.: the DPT Sub type used to format the datapoint value. It only sets the unit and the value range
• ID (Alias): the ID to assign to the corresponding datapoint of the KNX I/O Server. It can be any unique string without spaces and without the :, ; and = characters, and it can't start with autom., dimmer., rgb., light. or thermo., which are reserved for the virtual datapoints
• Description: a textual description of the datapoint. It will be visible in the Project Editor when configuring GUI objects
• Priority: KNX priority to be used when sending frames to this group (low, normal or urgent)
• Read: check this option if the status of this group has to be read at HSYCO start-up. Turn it off for write-only objects and for devices that do not answer read requests

Virtual datapoints

KNX lights, dimmers, RGB lights, automations (e.g. blinds) and thermostats need a set of datapoints for control and feedback. It is possible to create a virtual datapoint that links these datapoints so to be treated as a single one which, in turn, can be directly associated to an object in the Web User Interface.

Light

---

To add a "light" virtual datapoint select the "Lights" tab and click on the "+" button in the bottom bar of the table.

Attributes

• ID: an identification number for this datapoint. It will be used to compose the ID of the corresponding datapoint of the KNX I/O Server (e.g. if ID is set to 1 the corresponding datapoint will be 'light.1')
• Description: a textual description of the datapoint. It will be visible in the Project Editor when configuring GUI objects
• On Value: specifies if the 'on' state for this light is represented by a value of '1' or '0'
• Status Feedback (DPT 1): datapoint representing the on/off feedback. Leave it empty if the light has no status object; the light will then show as unknown until it is switched
• Switch Command (DPT 1): datapoint to be addressed when sending on/off commands. Leave it empty for a status-only light that can't be controlled from HSYCO

Dimmer

---

To add a "dimmer" virtual datapoint select the "Dimmers" tab and click on the "+" button in the bottom bar of the table.

Attributes

• ID: an identification number for this datapoint. It will be used to compose the ID of the corresponding datapoint of the KNX I/O Server (e.g. if ID is set to 1 the corresponding datapoint will be 'dimmer.1')
• Description: a textual description of the datapoint. It will be visible in the Project Editor when configuring GUI objects
• On Value: specifies if the 'on' state for this dimmer is represented by a value of '1' or '0'
• Relative Dimming Step: the step size sent to the Step command datapoint (if defined) while a dim button is held: 1 is the coarsest (the full range in one step), 7 the finest (1/64 of the range)
• Dimming Curve: enable this option if the dimmer has a timed dimming curve. The buttons connected to this datapoint will show an animated slider when a new brightness level is set.
• Full Travel Time (s): this option is available only if 'Dimming Curve' is enabled. It is the number of seconds the dimmer takes to go from 0 to 100%. If set to 'Auto' the trip time of the dimming curve will be automatically calculated and adjusted by HSYCO; otherwise it is possible to specify a fixed trip time in seconds.

Feedback datapoints:

• Level Feedback (DPT 5): datapoint representing the dimming level feedback, 0 to 255
• On/Off Feedback (DPT 1): datapoint representing the on/off feedback. Leave it empty when the dimmer only reports the level

Command datapoints:

• Level Command (DPT 5): datapoint to be addressed when sending a dimming level command, 0 to 255. It is also used to switch the dimmer when no On/Off command datapoint is set
• On/Off Command (DPT 1): datapoint to be addressed when sending an on/off command. Leave it empty to switch with the level datapoint instead
• Step Command (DPT 3): datapoint to be addressed when sending a step command, generally DPT 3.007 (control dimming). Leave it empty to dim by sending absolute levels instead

RGB

---

To add a "RGB" virtual datapoint select the "RGBs" tab and click on the "+" button in the bottom bar of the table.

Attributes

• ID: an identification number for this datapoint. It will be used to compose the ID of the corresponding datapoint of the KNX I/O Server (e.g. if ID is set to 1 the corresponding datapoint will be 'rgb.1')
• Description: a textual description of the datapoint. It will be visible in the Project Editor when configuring GUI objects
• On Value: specifies if the 'on' state for this light is represented by a value of '1' or '0'

Feedback datapoints:

• Colour Feedback (DPT 232): datapoint representing the RGB color feedback
• On/Off Feedback (DPT 1): datapoint representing the on/off feedback. Leave it empty when the light only reports the colour; black is then treated as off

Command datapoints:

• Colour Command (DPT 232): datapoint to be addressed when sending an RGB color command. It is also used to switch the light when no On/Off command datapoint is set, sending white for on and black for off
• On/Off Command (DPT 1): datapoint to be addressed when sending an on/off command. Leave it empty to switch with the colour datapoint instead

Automation

---

To add an "automation" virtual datapoint select the "Automations" tab and click on the "+" button in the bottom bar of the table.

Attributes

• ID: an identification number for this datapoint. It will be used to compose the ID of the corresponding datapoint of the KNX I/O Server (e.g. if ID is set to 1 the corresponding datapoint will be 'autom.1')
• Description: a textual description of the datapoint. It will be visible in the Project Editor when configuring GUI objects
• Up Value: specifies if the 'up' direction for this automation is represented by a value of '1' or '0'. The opposite value moves down
• Closed Value: specifies if the 'closed' state for this automation is represented by a value of '255' or '0' of the position feedback
• Use Position: specifies wether to use percentage values or not for the read values of the datapoint of the KNX I/O Server. If position is used a button linked to the datapoint will have a slider to control and visualize the position of the automation
• Full Travel Time (s): shown only when 'Use Position' is enabled, specifies the trip time (in seconds) from position close to open, used to animate the position between feedback telegrams. Leave the field blank to have the trip time automatically calculated from the observed movement

Feedback datapoints:

• Position Feedback (DPT 5): datapoint representing the position feedback, 0 to 255. Without 'Use Position' it is only read as open or closed
• Up/Down Feedback (DPT 1): datapoint the automation reports the direction of the last movement to
• Moving Feedback (DPT 1): datapoint that is 1 while the automation is traveling and 0 when it stops
• Upper Limit Feedback (DPT 1): datapoint that is 1 when the automation has reached the fully open position
• Lower Limit Feedback (DPT 1): datapoint that is 1 when the automation has reached the fully closed position

Command datapoints:

• Up/Down Command (DPT 1): datapoint to be addressed when sending an up/down command. Leave it empty to move the automation by sending fully open or fully closed on the position datapoint
• Stop Command (DPT 1): datapoint to be addressed when sending a stop command. Without it the automation can only be sent to its end positions
• Position Command (DPT 5): datapoint to be addressed when sending a position command, 0 to 255. It is required to drive the automation to a percentage

Thermostat

---

To add an "thermostat" virtual datapoint select the "Thermostats" tab and click on the "+" button in the bottom bar.

Attributes

• ID: an identification number for this datapoint. It will be used to compose the ID of the corresponding datapoint of the KNX I/O Server (e.g. if ID is set to 1 the corresponding datapoint will be 'thermo.1')
• Description: a textual description of the datapoint. It will be visible in the Project Editor when configuring GUI objects
• Unit: The temperature unit to show on the associated tempmini Web object: C, F or K. The values received from the bus are displayed as they are, they are not converted

Feedback datapoints:

• Setpoint Feedback (DPT 9): datapoint representing the temperature setpoint feedback
• Setpoint Mode Feedback (DPT 5): datapoint representing the setpoint mode of the thermostat (e.g. "comfort", "stand-by", ...)
• Room Temperature Feedback (DPT 9): datapoint representing the measured temperature
• Heating/Cooling Feedback (DPT 1): datapoint representing the season the thermostat is in, 1 for heating (winter) and 0 for cooling (summer)
• Heating Demand Feedback (DPT 5): datapoint representing the heating level feedback. Any value other than 0 lights up the heating indicator
• Cooling Demand Feedback (DPT 5): datapoint representing the cooling level feedback. Any value other than 0 lights up the cooling indicator

Command datapoints:

• Setpoint Command (DPT 9): datapoint to be addressed when sending a temperature setpoint command. Leave it empty for a display-only thermostat
• Setpoint Mode Command (DPT 5): datapoint to be addressed when sending a command to change the setpoint mode

The setpoint modes of a thermostat default to 'comfort', 'stand-by' and 'night', corresponding to the values 1, 2 and 3 of the setpoint mode datapoints. To use a different set of modes, or different values, edit the setpoint.mode.values and setpoint.mode.labels attributes of the thermostat directly in the knxtopo.txt file.

note

These two attributes are not editable in the KNX Utility, but they are preserved: they are kept when the thermostat, other thermostats or other datapoints are edited from the utility.

KNX Bus Monitor

The KNX Utility provides an interface for monitoring the KNX bus which is useful for testing purposes and helps detect the underlying KNX framework structure if unknown. To access the monitor, click on the "Monitor" button in the bottom-left corner and enable the monitor mode by clicking on the "Start" button. The monitor and its read, write and scan functions require the selected I/O Server to be online.

When the monitor is started, the bottom bar reports the individual address the gateway assigned to the tunnel connection and the number of free and total tunneling connections the gateway can serve, when the gateway makes this information available.

Whenever a frame is detected on the bus, it will be listed in the central panel, most recent first. The last 1000 frames are kept; the "Clear" button empties the list.

For each frame the following data will be reported:

• The time when the frame has been detected
• The destination group address the frame was sent to (with corresponding ID and description if a datapoint with that address is defined)
• The individual address of the device which generated the frame (souce)
• Hexadecimal representation of the user data contained in the frame (with the value formatted according to the DPT of the datapoint, if defined)

Clicking on a row copies its group address to the "Address" field of the read and write tools.

Using the read and write functions you can respectively recall the value currently assigned to a specific group address or write a value to it (if allowed by the KNX framework settings). When reading or writing, the DPT field must be specified so that the value can be interpreted accordingly. The value to be written or shown after a reading, is expressed as a value formatted for the specified DPT. When DPT 18 is selected, the value and the scene number are entered in two separate fields.

For details on how a value is formatted for a specific DPT see Supported Datapoint types and values.

The "Scan" button in the top right corner lets you send consecutive read requests to a set of group addresses. Specify the address range using the fields "From" and "To", press "Scan" and wait until the scanning procedure is complete to analyze the received responses. A progress bar shows the address being probed and how many addresses answered; the responses are also listed in the frames table. At the end, the number of responding group addresses is reported next to the progress bar, and the list of their addresses is written to the log. To interrupt the scanning press the "Stop" button.