Setup Guide

Prerequisites

There are no prerequisites for this module.

Installation

There are two ways to install the desired module components: through the Kit Manager or manually.

Automated Installation

The Kit Manager is a utility that enables you to automatically install a component or a group of components by executing a predefined install script. To use the Kit Manager to install a component:

Go to the Runtime Text Console and make sure the Kit Manager bundle is running on your SDK.
Use the kitman command group to initiate the installation. For example, type
kitman.i "<kit_ID>"

The following scripts are available:

KNX (found in the knx.txt file) - Installs the KNX Core bundles together with all available KNX drivers: USB, Serial port, IP and FT1.2
KNX DA Support (found in the knx-da.txt file) - Adds the Device Access support through the DA API for the KNX module.
KNX DA HDM Support (found in the knx-da-hdm.txt file) - Adds the Device Access through the HDM API support for the KNX module.
KNX DA Config (found in the knx-da-config.txt file) - Installs the ETS configuration tool support for controlling KNX devices via the Functional Items Manager.
DA HDM Config (found in the knx-da-hdm-config.txt file) - Installs the ETS configuration tool support for controlling KNX devices via the Home Device Manager (HDM).

Manual Installation

To take advantage of the module's core functionalities as well as install all available drivers, do the following steps:

Install and start the module's dependencies:
kitman.i "Peripheral"

kitman.i "Comm (javax.comm) Bundle"
Set the bundle's base location:
set mbs.bundles.base=../../../bundles/
Install and start the core KNX bundles:
fw.i -s -l -f com.prosyst.mbs.knx.driver.api.jar

fw.i -s -l -f com.prosyst.mbs.knx.driver.ip.jar
Install and start the bundles for the drivers:
- For Windows x86 based systems install and start the following bundle:
  fw.i -f com.prosyst.mbs.knx.driver.usb-natives.win_x86.jar
- For Windows x64 based systems install and start the following bundle:
  fw.i -f com.prosyst.mbs.knx.driver.usb-natives.win_x86_64.jar
Install the remaining driver bundles:
fw.i -s -l -f com.prosyst.mbs.knx.driver.usb.jar

fw.i -s -l -f com.prosyst.mbs.knx.driver.ft12.jar

fw.i -s -f -l com.prosyst.mbs.knx.driver.commands.jar

To use the Device Access support for the KNX module, do the following steps:

Install and start the module's dependencies:
kitman.i "ConfigTree"

kitman.i "Device Access"
Install and start the core KNX files:
kitman.i "KNX"
Set the bundle's base location:
set mbs.bundles.base=../../../bundles/
Install the remaining needed bundles:
fw.i -s -f com.prosyst.mbs.knx.da.hdm.adapter.api.jar

fw.i -s -f com.prosyst.mbs.knx.da.hdm.dc.api.jar

fw.i -s -f com.prosyst.mbs.knx.da.items.api.jar

fw.i -s -l -f com.prosyst.mbs.knx.da.items.provider.jar

fw.i -s -l -f com.prosyst.mbs.knx.da.hdm.adapter.jar

To use the HDM integration support for the KNX module, do the following steps:

Install and start the module's dependencies:
kitman.i "ConfigTree"

kitman.i "Device Access HDM"
Install and start the core KNX files:
kitman.i "KNX"
Set the bundle's base location:
set mbs.bundles.base=../../../bundles/
Install the remaining needed bundles:
fw.i -s -f com.prosyst.mbs.knx.da.hdm.adapter.api.jar

fw.i -s -f com.prosyst.mbs.knx.da.hdm.dc.api.jar

fw.i -s -f com.prosyst.mbs.knx.da.items.api.jar

fw.i -s -l -f com.prosyst.mbs.knx.da.hdm.dco.provider.jar

fw.i -s -l -f com.prosyst.mbs.knx.da.hdm.adapter.jar

To take advantage of the ETS configuration tool support for controlling KNX devices via the Functional Items Manager, do the following steps:

Install and start the module's dependencies:
kitman.i "Web Services JSON RPC Provider Bundles"

kitman.i "Web Console"
Install the needed KNX bundles:
kitman.i "KNX DA Support"

kitman.i "KNX DA HDM Support"
Cnfigure and restart the DA Core bundles:
config.update mbs.da.core.apis {da.api=true,hdm.api=true}

fw.restart com.prosyst.mbs.da.core
Set the bundle's base location:
set mbs.bundles.base=../../../bundles/
Install the remaining needed bundles:
fw.i -s -f -l com.prosyst.mbs.knx.da.hdm.jsonrpc.jar

fw.i -s -f -l com.prosyst.mbs.knx.da.hdm.webconsole.jar

Configuring the KNX Module

The KNX Driver Bundles registers a Managed Service Factories under the name "KNX <transmission_medium> Driver Configuration". The dictionary of a configuration produced from the factory contains settings for connecting to the KNX network via a specific transmission medium. For information on how to set it, refer to Changing Settings.

The below section outlines how to connect to the KNX network via USB, Serial Port, IP network or FT1.2 protocol. For more information on Managing Bundle's Configurations, refer to the section Working with Web Console.

For USB Connections

Connect your Home Gateway to a KNX USB interface and do the following:

Activate the USB drivers by installing the USB driver bundle that corresponds to your OS and CPU architecture.
Check the Vendor ID (VID) and Product ID (PID) property numbers of the USB device that is connected.

This step can be done automatically by the Peripheral Admin if there is a peripheral descriptor for the KNX USB controller.
Set the hexadecimal numbers as values to the vendor_id (Vendor ID) and product_id (Product ID) configuration properties of the driver's configuration and check the Auto Connect checkbox (set the auto_connect property to true).

Available Configuration Properties

Parameter	ID	PID/FPID	Type	Default	Description
Vendor ID	vendor_id	mbs.knx.datalink.usb.fpid	String		The USB Vendor ID as HEX string (no leading 0x).
Product ID	product_id	mbs.knx.datalink.usb.fpid	String		The USB Product ID as HEX string (no leading 0x).
Enable Group Cache	group_cache_enabled	mbs.knx.datalink.usb.fpid	Boolean	false	Setting this property true will enable group cache. This means, that all group data write/response requests are cached internally and the value is returned when read request is made.
Clean Group Cache On Disconnect	group_cache_clean_on_disconnect	mbs.knx.datalink.usb.fpid	Boolean	true	Setting this property true will clean group cache when data link is disconnected.
Auto Connect	auto_connect	mbs.knx.datalink.usb.fpid	Boolean	true	Set this property true, to force the driver connect on startup. By default this property is false, and the driver connects on the first request to the bus.
Reset On Connect	reset_on_connect	mbs.knx.datalink.usb.fpid	Boolean	true	Set this property false, in order not to force the USB interface reset on driver connect.
Acknowledgement timeout	ack_timeout	mbs.knx.datalink.usb.fpid	Int	2000	Default acknowledge timeout.
Errors to reconnect	errors_to_reconnect	mbs.knx.datalink.usb.fpid	Int	0	The amount of consecutive send / confirmation errors which will forces reconnection, 0 or negative values disables reconnect.
Individual Address	individual_address	mbs.knx.datalink.usb.fpid	String	0	This is Individual Address of data link that will be set as source address for all outgoing frames.

For TCP/UDP Connections

Connect your Home Gateway and your KNX IP router to a common IP network and do the following:

Activate the serial port drivers by installing the KNX IP Driver com.prosyst.mbs.knx.driver.ip.jar) bundle.
Check the IP address of the KNX IP router.
Set it as a value to the remote.host (Remote Host) configuration property of the driver's configuration and set the auto_connect (Auto Connect) property to true.

Available Configuration Properties

Parameter	ID	PID/FPID	Type	Default	Description
Bind Host	bind.host	mbs.knx.datalink.ip.fpid	String		The local host address, to which the KNX/IP driver should bind to.
Bind Port	bind.port	mbs.knx.datalink.ip.fpid	Int	0	The local port, to which the KNX/IP driver should bind to.
Remote Host	remote.host	mbs.knx.datalink.ip.fpid	String		The remote host address, to which the KNX/IP driver should connect to. If not set - automatic discovery will be used.
Remote Port	remote.port	mbs.knx.datalink.ip.fpid	Int	3671	The remote port, to which the KNX/IP driver should connect to. If not set - automatic discovery will be used.
Protocol Type	protocol	mbs.knx.datalink.ip.fpid	Int	UDP(1)	The protocol type. Default value is UDP(1). Possible values are UDP(1) or TCP(2).
Enable Group Cache	group_cache_enabled	mbs.knx.datalink.ip.fpid	Boolean	false	Setting this property true will enable group cache. This means, that all group data write/response requests are cached internally and the value is returned when read request is made. Default value is false.
Clean Group Cache On Disconnect	group_cache_clean_on_disconnect	mbs.knx.datalink.ip.fpid	Boolean	true	Setting this property true will clean group cache when data link is disconnected.
Auto Connect	auto_connect	mbs.knx.datalink.ip.fpid	Boolean	false	Set this property true, to force the driver connect on statup. By default this property is false, and the driver connects on the first request to the bus.
Acknowledgement timeout	ack_timeout	mbs.knx.datalink.ip.fpid	Int	2000	Default acknowledge timeout.
Errors to reconnect	errors_to_reconnect	mbs.knx.datalink.ip.fpid	Int	0	The amount of consecutive send / confirmation errors which will forces reconnection, 0 or negative values disables reconnect.
Individual Address	individual_address	mbs.knx.datalink.ip.fpid	String	0	This is Individual Address of data link that will be set as source address for all outgoing frames.

For Connections through FT1.2

Connect your Home Gateway to a KNX serial interface and do the following:

Check the name of the serial port your coordinator is connected to.
Set the name of the serial port as a value of the port (Port) configuration property of the driver's configuration and set the auto_connect (Auto Connect) property to true.
For Windows enter the name of the occupied Serial Port. For example: COM1.

For Linux enter the full path to the file which represents the occupied Serial Port. For example: /dev/ttyUSB0.

Available Configuration Properties

Parameter	ID	PID/FPID	Type	Default	Description
Port	port	mbs.knx.datalink.ft12.fpid	String	COM1	Port on which to start a FT1.2 driver
Baudrate	baudrate	mbs.knx.datalink.ft12.fpid	Int	19200	Baudrate for serial port communication.
DataBits	dataBits	mbs.knx.datalink.ft12.fpid	Int	8	Data bits for serial port communication.
StopBits	stopBits	mbs.knx.datalink.ft12.fpid	Int	1	Stop bits for serial port communication, default 1.
Parity	parity	mbs.knx.datalink.ft12.fpid	Int	EVEN(2)	Parity for serial port communication. Default value is Even(2). Other possible values are NONE(0), ODD(1), MARK(3), SPACE(4).
Flow Control	flowControl	mbs.knx.datalink.ft12.fpid	Int	0	Flow control for serial port communication, default NONE.
EMI Type	emiType	mbs.knx.datalink.ft12.fpid	Int	EMI2 (513)	Supported EMI type of the FT1.2 controller. Default value is EMI(2). Other possible values are EMI1 (257), EMI2 (513), EMI (1025)
Enable Group Cache	group_cache_enabled	mbs.knx.datalink.ft12.fpid	Boolean	false	Setting this property true will enable group cache. This means, that all group data write/response requests are cached internally and the value is returned when read request is made.
Clean Group Cache On Disconnect	group_cache_clean_on_disconnect	mbs.knx.datalink.ft12.fpid	Boolean	true	Setting this property true will clean group cache when data link is disconnected. Default value is true.
Auto Connect	auto_connect	mbs.knx.datalink.ft12.fpid	Boolean	false	Set this property true, to force the driver connect on statup. By default this property is false, and the driver connects on the first request to the bus.
Acknowledgement timeout	ack_timeout	mbs.knx.datalink.ft12.fpid	Int	1000	Default acknowledge timeout.
Errors to reconnect	errors_to_reconnect	mbs.knx.datalink.ft12.fpid	Int	0	The amount of consecutive send / confirmation errors which will forces reconnection, 0 or negative values disables reconnect.
Individual Address	individual_address	mbs.knx.datalink.ft12.fpid	String	0	This is Individual Address of data link that will be set as source address for all outgoing frames.

System Properties

A description of the KNX system properties.

Property	Default Value	Description
mbssh.hdm.knx.debug	false	Enables debug log level for KNX DA HDM adapter.
mbssh.hdm.knx.console	false	Enables printing on console of log messages from KNX DA HDM adapter
mbssh.hdm.knx.pingInterval	60000	Interval in milliseconds, how often the KNX DA HDM adapter will try to connect the KNX device using its individual address, in order to determine its ONLINE/OFFLINE status. Set to 0 or negative to disable device ping.
mbssh.hdm.knx.skipFlagsChecking	false	When a group-address frame is received from the KNX bus, the KNX DA HDM adapter will forward the frame to datapoints with matching datapoint flags. Setting this property to true, allows forwarding to all datapoints without checking their flags.

Troubleshooting

No troubleshooting information is available for this module.