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 only. Device discovery is not yet supported.
Dependencies
The architecture of the KNX connector makes use of the JKNXC (Java interface which is modeled on the JDBC API. FIN leverages the JKNXC infrastructure for using various KNX Java drivers. The JKNXC interface is implemented by all FIN JKNXC drivers, therefore anyone who needs a customized KNX driver can simply implement the JKNXC interface.
These are the main dependencies for the KNX connector:
Another prerequisite is the units.props file which should be placed under \etc\knx. This file is responsible for translating the KNX DPTs into Haystack types.
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 (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 FIN System Integrator Apps -> DB Builder -> Connectors -> Knx -> Projects, click on the Upload button and select a *knxproj file.
In the same view, the options of Replace and Delete are available to 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 KnxConn is the connector Uri. Additionally you can opt to provide a *knxproj file or not.
The FIN Knx connector URI also has an enhanced version where a KNX Group Address can be appended it, i.e. knx-calimero://192.168.1.100:3671/2/0/3. Additionally, the appended group address can have wildcards, like 2/1/* or 1/*/5, which would allow for similar/identical functionalities to operate on a batch of group addresses instead of a single one.
Test out theconnector using the knxPing Axon function:
read(knxConn).knxPing
or by 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, 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.
Besides the FIN Discover view, learning can calso be done using the KnxLearn Axon function as following:
read(knxConn).knxLearn
which returns a Grid of all discovered data points on that KnxConn.
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.
Specifying the DPT
You can specify the data point type in the following formats. Refer to the KNX specification available at www.knx.org.
1.009 (close/open encoding)
DPST-1-9 (close/open encoding)
DPT-1 (generic boolean, no subtype)
DPST-4-1[0] (retrieves the increase/decrease encoding bit of the generic DPST-4-1 data point type, which is an 8-bit encoding)
4 or 4-xxx (generic DPST-4-xxx type)
4.001 (DPT subtype)
4.009.0 (first part of the DPST-4-9 DPT)
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.
Reading and Writing
Reading and writing 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.
AXON funcs exposed by KnxExt
The following Axon funcs can be used to interface with the KnxExt:
Backend funcs:
Usage: |
|
Usage: |
|
Usage: |
|
Usage: |
|
Usage: |
|
Usage: |
|
Usage: |
|
Usage: |
|
Usage: |
|
Frontend funcs:
Usage: |
|
Usage: |
|
Usage: |
|
Usage: |
|
Usage: |
|
Usage: |
|