Table of Contents |
---|
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:
knxExt.pod
: J2-owned library that implements the KNX connector. Interfaces only with knx.pod.Can use the connector Uri to allow user-defined drivers
Ensure that knxExt.pod is present in lib/fan/.
knx.pod
: encapsulates the JKNXC interface (jknxc.jar)Holds the *knxproj parser and the KnxLink definition
Ensure that knx.pod is present in lib/fan/
jknxc-[driver]
: a custom implementation of the JKNXC interface.The FIN implementation of JKNXC is based on the Open Source Calimero library, therefore the name of this dependency is jknxc-calimero.jar which bundles the jknxc.jar and calimero-core-x.x.jar
Ensure that jknxc-[driver] is present in lib/java/ext/
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.
It doesn’t support password protected projects. The password would have to be removed in order to be able to use it in FIN.
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 FIN System Integrator Apps -> DB Builder -> Connectors -> Knx -> Projects, click on the Upload button and select a *knxproj file.
In the same view, the there are options of to Replace and or Deleteare 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 connector URI has the following format:
knx-
calimero://[IP]:[port]/
where:
IP – the IP address of the KNX interface/gateway device we use to access the KNX network
port - default for KNX is 3671
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 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
Besides the FIN Discover view, learning can calso be done using the KnxLearn Axon function as following:
read(knxConn).knxLearn
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 http://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.
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.
AXON funcs exposed by KnxExt
The following Axon funcsTuning
There is a KNX tag called knxThrottle
that can be used to interface with the KnxExt:
Backend funcs:
Usage: knxPing(knxConn)
knxPing
: performs an async ping on a given connector.
Usage: knxSyncCur(knxConn)
knxSyncCur
: asynchronously synchronize current values for given list of proxy points
Usage: knxLearn(knxConn, null)
knxLearn
: synchronous learn read on the given connector.
Usage: knxLearn()
knxFindProjectFiles
: searches for *.knxproj files in the following places: \var\proj\[proj_name]\io, \var\proj\[proj_name]\data\knx, inside the pods(uploads what it finds into FIN and tags it as knxProjFile), file records with knxProjFile tag
Usage: knxDeleteProjectFiles(fileList)
knxDeleteProjectFiles
: deletes *knxproj files from the FIN project
Usage: knxReplaceProjectFile(dictOriginalFile, dictReplacementFile)
knxReplaceProjectFile
: replaces a *.knxproj file in the current project with another one
Usage: knxUpdateDataPoints(knxConn, dictListOfPoints)
knxUpdateDataPoints
: writes changes performed on data points back to the *.knxproj used on a KnxConn
Usage: knxGetDataPoint(knxConn, pointUri)
knxGetDataPoint
: returns data for a specific data point
Usage: knxGetDataTypes(knxConn, intDptFormatDepthLevel, strDptId)
knxGetDataTypes
: returns the data point types found in the knx_master.xml which is bundled in the *knxproj file assigned to a KnxConn
Frontend funcs:
Usage: finFormReplaceKnxProj(selectedKnxProjFile)
finFormReplaceKnxProj
: gets called when an uploaded *.knxProj is selected in the Projects view and the Replace *knxproj button is pressed invoking the Replace message box
Usage: finFormUploadKnxProj()
finFormUploadKnxProj
: gets called when the Upload *knxproj button is pressed and invokes the Upload message box
Usage: finFormConfirmKnxProj(targetRec, dictListKnxProjFiles)
finFormConfirmKnxProj
: gets called when creating the drop-down used to select the *knxproj in the Add/Edit a KnxConn message box
Usage: finFormAddEditKnxConn(flagAddOrEdit, recId)
finFormAddEditKnxConn
: gets invoked when adding/editing a KnxConn
Usage: finFormSelectKnxConnEdit()
finFormSelectKnxConnEdit
: gets invoked when selecting a KnxConn in the Equip Tree and pressing the Edit button in the bottom left of the window
Usage: finFormEditKnxDiscoverySettings(listDataPoints, knxConn)
finFormEditKnxDiscoverySettings
: gets invoked when the Apply button on the Edit Data Point settings form is pressed
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.