Overview

The KNX connector is part of the KnxExt and it implements connector support for the KNX protocol. It follows the standard connector model:

Connectors: used to configure a JKNXC connection to a KNX access point (typically an IP interface)
Functions: provide access to read/write/learn from within your Axon scripts

Current support

Currently KnxExt supports the KNXNet/IP version of the KNX protocol. Reading and writing is supported via tunneling.

It doesn’t support KNX Secure.

Importing an ETS project (*.knxproj)

The startup point to any KNX configuration is defining the KNX topology of one or several installations using the ETS tool, which can be downloaded from the KNX Association website (http://www.knx.org ).

Here’s a sample project opened in ETS, showing the network topology, group addresses and the diagnostics/monitoring views:

After creating and configuring a KNX project, a *.knxproj file will be available and can be imported into FIN.

To upload a *.knxproj file into a FIN project, go to DB Builder -> Connectors -> Knx -> Projects, click on the Upload button and select a *knxproj file. If a password‑protected project is selected, an “Unlock project” prompt will appear to enter the password. Otherwise, the project uploads or replaces correctly without additional steps.

Files with special characters (available for server only)

If your .knxproj file contains special characters, you can enable custom encoding by running knxEnableCustomEncoding(true) from Folio > Launch, then restart the FIN service to prevent errors.

In the same view, there are options to Replace or Delete the uploaded *knxproj file. When uploading a *knxproj file into a FIN project, that file is available for all Knx connectors created under that FIN project.

Creating a KNX connector

The mandatory requirement to create a KNX connector is the connector Host field. Additionally you can opt to provide a *knxproj file or not.

The connector Host accepts the following format:

[IP]:[port]

where:

IP – the IP address of the KNX interface/gateway device used to access the KNX network
port - default for KNX is 3671

KNX supports two IP communication types, which can be selected by checking either radio button next to “Schema”.

These types are:

Routing (multicast)
- Host should be 224.0.23.12:3671
  Note: Currently this is not fully supported on edge devices like F200.
Tunneling (unicast)
- Uses a specific device IP address
- Standard port remains 3671 unless otherwise configured

Local address specifies which local network interface the connector should bind to when communicating with the KNX network.

KNX IP Comm. Configuration: Multicast

KNX communication over IP via multicast features indirect communication between FIN and multiple devices, intermediated by a number of broadcasting “phantom nodes” with a dummy IP that exists only to relay the message to all devices within range that have been set to listen for its specific broadcast signal. Because the broadcasted information is hidden from most devices, this method of communication is useful for multi-device setups that require extra security.

Configuring the KNX Individual Address

By default, the KNX connector in FIN uses the individual address 0.0.0. This address can now be customized using the function knxUpdateIndividualAddress().

Function Syntax: knxUpdateIndividualAddress(conn, addr)

Parameters:

conn: Reference to the KNX connection object.
addr: Desired KNX individual address in string format (e.g., "1.1.0").

Example: knxUpdateIndividualAddress(@id_of_connector, "1.1.0")

KNX IP Comm. Configuration: Tunneling

KNX communication over IP via tunneling features direct communication between FIN and a device. Useful for a single device or serial networks.

You can test out your connector using the connector UI under the Equip Tree accessible from the DB Builder app.

If trying to establish connection to an endpoint using NAT (Network Address Translation), add the knxUseNat marker tag to the connector record. NAT usage without extra safety measures is not recommended. Port forwarding provides universal access to a local IP network and KNX system. Any Internet user can discover the open port on a static public IP address and can, for example, access the KNX network via ETS. It is recommended to connect to the endpoint via VPN and to change the default KNX port (3671) to one from the unreserved range (50000-60000).

Learning data points from an imported *.knxproj

From the KnxConn view, discover the data points from the chosen *knxproj. Before learning a data point as a point in FIN, you have the ability to first edit its definition in the knxproj file by using the Edit Datapoint button in the point discovery interface.

This can be used for datapoints that don’t originally come with a data point type assigned from the knxproj, to configure if they are readable and/or writable or if need to change some of the point information before adding it to the equip.

Once done, select the points to add into the Equip Tree by clicking Add/Add all or drag and drop the point(s) under an equip.

Note

When editing a data point the changes are made on the imported knxproj file, therefore all other KnxConns using that *knxproj file will be impacted.

When building you project, make sure all GroupAddresses have the DataPointType field configured, as it is necessary for the proper conversion of data on the FIN side.
A project with missing DataPointType could not be fully discovered and only show some of the points.

Translating KNX DPTs into Haystack types

The KNX standard comes with a complex system of data point typing, which the *.knxproj parser inside the knx.pod translates into the FIN/Haystack data types.

Supported DPTs

Full list and examples found here: https://finproducts.atlassian.net/wiki/spaces/FINFramework/pages/34310815752

#	DPT	Name	Wire Size	Kind	Subtypes	Multipart

#	DPT	Name	Wire Size	Kind	Subtypes	Multipart
1	DPT-1	1-Bit Boolean	1 bit	`Bool`	23	No
2	DPT-2	1-Bit Controlled	2 bits	`Str`	12	Yes (2 parts)
3	DPT-3	3-Bit Controlled Step	4 bits	`Str`	2	Yes (2 parts)
4	DPT-5	8-Bit Unsigned Value	8 bits	`Number`	6	No
5	DPT-6	8-Bit Signed Value	8 bits	`Number`	3	No
6	DPT-7	2-Byte Unsigned Value	16 bits	`Number`	11	No
7	DPT-9	2-Byte Float	16 bits	`Number`	28	No
8	DPT-10	Time of Day	24 bits	`Str`	1	Yes (6 parts)
9	DPT-11	Date	24 bits	`Str`	1	Yes (6 parts)
10	DPT-19	Date and Time	56 bits	`Str`	1	Yes (20 parts)
11	DPT-20	1-Byte Enumeration	8 bits	`Str`	60	No
12	DPT-219	Alarm Info	32 bits	`Str`	1	Yes (13 parts)

Units

Units translation from KNX to Haystack is done via the units.props file found under /etc/sys/. In case your *.knxproj file defines a non-standard KNX unit, you can add it to the units.props file or change an already existing binding in that file. A FIN restart is required after altering this file.

If you are getting an “Unit not mapped” error, see KNX error: Unit not mapped

Custom units

There are some KNX projects that have custom units that are not available or part of our default KNX units list, these custom units can be added through the Unit Bindings window. There could be units that are named differently than the norm, which would also need to be added as a custom unit.

To get to the Unit Bindings window, expand the Knx tree under Connectors.

In the Unit Bindings window on the right, the user will find the below options:

Add - This will allow the user to add new custom units.
Edit - This will allow the user to edit any existing custom unit that was added.
Delete - This will allow the user to delete any existing custom unit that was added.
Import - This will allow the user to import a knx custom units list (.props file) into a project.
Export - This will allow the user to export a copy of their custom units.
Show Default - This will show the user a list of all default KNX units. Any unit without the check mark in the Default column means it is a custom one.

Add

When adding a new custom unit, the user will select the Add button.

The user will be presented with the below fields:

Key - this is where the user will type in the custom unit found in the knxproj that doesn’t exist in our KNX unit library.
Existing Unit - this option allows the user to pick from existing units found in our KNX unit library that would match their custom unit name represents. For example, if the knxproj has a unit defined as “kwh” instead of the standard “kWh”, which is found in our default KNX unit library (found in the “Show defaults” button), the user can use this option to map their “kwh” unit to the “kWh” standard unit.
Custom Unit - this option allows the user to add a custom unit that is not found in our default KNX unit library so that it can be read properly.

Existing Unit

If the user selects to add an existing unit, then they can select the quantity and symbol for the new unit to add.

Key = the unit name in the knxproj.

Custom Unit

If the user selects to add a custom unit, then they can select the name, quantity, scale and offset for the new custom unit to add.

Key = the unit name in the knxproj.

Names = Provide a name of the custom unit. It should be a descriptive summary of the unit using words separated by underbar such as "miles_per_hour". Multiple can be added and separated by comma.

Reading and Writing

Reading and writing the same objects on KNX can be performed on the same group address or on dedicated group addresses independently. For example, reading a batch of switches/binary outputs is done with the 1/1/* group addresses, while writing to these channels is performed with the 1/0/* group addresses, or they both reading and writing can be performed on the same group address.

Tuning

There is a KNX tag called knxThrottle that can be used to control the frequency of the data reads. This tag is applied on the connector record.

knxThrottle (number - duration) - If not present, it falls back to 100m/s. Value of 0 is acceptable which removes the throttle.

KNX Watchdog — Device Connectivity Monitoring

The KNX Watchdog is a background polling system built into the KNX connector that continuously checks the connectivity of KNX devices on the bus. It detects when devices go offline or return online, raises or clears alarms via the FIN AlarmEngine, and provides cached status through Axon functions all with zero manual intervention once configured.

Key Features

Periodic device polling with configurable frequency and batch size
Alarm integration for automatic fault/normal transitions via AlarmEngine
Router‑aware mode pings IP routers first and skips device checks if their router is offline
Restart‑safe prevents duplicate alarms after application or connector restart
First‑poll delay to reduce traffic during system initialization
Thread‑safe all state managed on the ConnActor thread

Quick Start

1. Enable the Watchdog (Axon)

// Enable with defaults: 5min frequency, batch size 10, router-aware = true
knxWatchdogEnable(@myKnxConn)

// Custom: 10min frequency, batch size 20, router-aware = true
knxWatchdogEnable(@myKnxConn, 10min, 20, true)

// Custom: 5min frequency, batch size 10, router-aware = false
knxWatchdogEnable(@myKnxConn, 5min, null, false)

2. Check Device Status

Cached Status

knxWatchdogStatus(@myKnxConn)

Live Ping (TEST ONLY — generates bus traffic)

knxDeviceStatus(@myKnxConn)

3. Disable the Watchdog

knxWatchdogDisable(@myKnxConn)

Configuration

Connector Tags

Tag	Type	Default	Description

Tag	Type	Default	Description
`knxWatchdogEnabled`	Marker	—	Enables the watchdog polling loop
`knxWatchdogFreq`	Number	5min	Polling interval (minimum: 5min)
`knxWatchdogBatchSize`	Number	10	Number of devices checked per cycle (minimum: 1)
`knxRouter`	Marker	—	Enables router‑aware mode

Note: These tags are created and managed automatically by knxWatchdogEnable() and persist across application restarts.

Device Tags (Auto‑Created)

Tag	Type	Description

Tag	Type	Description
`knxDevice`	Marker	Indicates a KNX device record
`knxIndividualAddr`	Str	Device’s KNX individual address (e.g., `"1.1.2"`)
`knxConnRef`	Ref	Reference to the parent KNX connector
`inAlarm`	Str	Present when the device has an active fault alarm

Axon Function Reference

knxDeviceStatus(conn, router, timeout)

TEST ONLY — Generates live bus traffic

Pings KNX devices in real time. Routers are always checked first. If a router is unreachable, its bus devices are marked "unreachable (router down)".

knxDeviceStatus(@conn) // All devices, 30sec timeout
knxDeviceStatus(@conn, "1.1.0") // Filter by router line
knxDeviceStatus(@conn, null, 15sec) // All devices, custom timeout
knxDeviceStatus(@conn, "1.1.0", 10sec) // Router filter + timeout

Returns:
A grid with: individualAddr, dis, status, isRouter, checkedAt

knxWatchdogStatus(conn)

Returns cached status from the Watchdog — no bus traffic.

knxWatchdogStatus(@conn)

Returns:
A grid with: individualAddr, dis, status, isRouter, lastChecked

knxWatchdogEnable(conn, freq, batchSize, routerAware)

Enables or updates Watchdog configuration.

Parameters

Parameter	Type	Default	Min	Description

Parameter	Type	Default	Min	Description
`conn`	Ref	—	—	Connector reference
`freq`	Number	5min	5min	Poll interval
`batchSize`	Number	10	1	Devices per cycle
`routerAware`	Bool	true	—	Enable router‑aware mode

Examples

knxWatchdogEnable(@conn) // Defaults
knxWatchdogEnable(@conn, 10min, 50, true) // Large deployment
knxWatchdogEnable(@conn, 5min, null, false) // No router awareness

knxWatchdogDisable(conn)

Disables the watchdog and removes related tags.

knxWatchdogDisable(@conn)

KNX Connector