KNXnet/IP server for KNX IP, KNX (RF) USB, FT1.2, and TP-UART
OTHER License
A KNXnet/IP server for running your own KNXnet/IP server in software. The minimum required runtime environment is JDK 17 (java.base).
The Calimero KNXnet/IP server requires calimero-core
and calimero-device
.
Optional dependencies, required for serial communication:
serial-native
(with its JNI libraries), or calimero-rxtx
for using any RXTX descendant/compatible library on your platform.calimero-usb
(and its transitive closure).Pre-built Docker images for running the server are available on Docker Hub. These snapshots might be ahead of the latest release but in general not less stable than releases.
Note that for KNX IP Secure a keyfile or an ETS keyring (*.knxkeys) is required, see section below.
Note, running gradle build (e.g., ./gradlew build
) will create build/distributions/calimero-server-*.tar/.zip, which contains a directly executable script and all required dependencies.
Before trying the examples below with a configuration, make sure the configuration is appropriate for your KNX setup!
On the terminal, a running server instance can be stopped by typing "stop".
./gradlew run --args resources/server-config.xml
mvn exec:java -Dexec.args=resources/server-config.xml
Make sure all required jar
packages are available, and any referenced files in the folder resources
are found (e.g., copy them into the current working directory)
# Either, assuming all jar dependencies are located in the current working directory
java -cp "./*" io.calimero.server.Launcher server-config.xml
# Or, a minimal working example with explicit references to jars (adjust as required)
java -cp "calimero-server-3.0-SNAPSHOT.jar:calimero-core-3.0-SNAPSHOT.jar:calimero-device-3.0-SNAPSHOT.jar" io.calimero.server.Launcher server-config.xml
A working example of an XML server configuration can be found here.
Description of the supported XML elements and attributes:
<knxServer name="knx-server" friendlyName="My KNXnet/IP Server">
(required): specifies the server ID (for logging etc.) and the KNXnet/IP friendly name (for discovery & self-description)
name="knx-server"
: Attribute to specify the internal name of the server (mainly for logging, naming, debugging purposes)friendlyName="My KNXnet/IP Server"
: Attribute to specify a custom name (max. 30 characters). Will be displayed in e.g. ETS.appData="/path/to/app/dir"
(optional): base directory to load/save server application data, by default this is the empty path. The path might start with ~, expanded to the Java system property "user.home". The server's interface object server (IOS) data is stored in this directory between restarts. The <serviceContainer>
attributes keyfile
and keyring
are resolved against this directory if they contain a relative path.<discovery listenNetIf="all" outgoingNetIf="all" activate="true"/>
(optional attributes): the network interfaces to listen for KNXnet/IP discovery requests, as well as the network interfaces to answer requests, e.g., "all"
, "any"
, or "lo,eth0,eth1"
. The attribute activate
allows to disable KNXnet/IP discovery & self-description. If disabled, any received discovery or descriptions request will be ignored.
<serviceContainer>
(1..*): specify a server service container, i.e., the client-side endpoint for a KNX subnet. Attributes:
activate
: enable/disable the service container, to load/ignore that container during server startuprouting
: if true
activate KNX IP routing, if false
routing is disablednetworkMonitoring
: serve tunneling connection on KNX busmonitor layer (set true
) or deny such connection requests (set false
)udpPort
(optional): UDP port of the control endpoint to listen for incoming connection requests of that service container, defaults to KNXnet/IP standard port "3671". Use different ports if more than one service container is deployed.listenNetIf
(optional): network adapter to listen for connection requests, e.g., "any"
or "eth1"
, defaults to host default network adapter. any
- the first available (non-loopback) network adapter is chosen depending on your OS network setup (or localhost setting).reuseCtrlEP
(optional): use the KNXnet/IP control endpoint (UDP/IP) for tunneling connections, false
by default. If reuse is enabled (set true
), no list of additional KNX individual addresses is required (see below). Per the KNX standard, reuse is only possible if the control endpoint's individual address is not yet assigned to a connection, and if KNXnet/IP routing is not activated. This implies that by reusing the control endpoint, at most 1 connection can be established at a time to a service container.keyfile="~/.knx/keyfile"
(required for KNX IP Secure): path to a keyfile containing the KNX IP Secure keys, alternatively specify a keyring
. See below for the keyfile layout.keyring="/path/to/keyring.knxkeys"
(required for KNX IP Secure): path to a keyring exported from ETS containing the KNX IP Secure keys. The keyfile typically contains the password to decrypt the keyring, otherwise the server will try to query the keyring password from the system console during startup.securedServices
(optional): specify a set of required KNXnet/IP secure services. Supported values are a combination of devmgmt
, tunneling
, and routing
. A value of optional
configures secured services, but clients can also use unsecure communication. If this attribute is not used, by default the server requires KNXnet/IP secure services as supplied by a keyring/keyfile.<knxAddress type="individual">7.1.0</knxAddress>
: the individual address of the service container (has to match the KNX subnet!)
type="individual"
: indicates a device address.x.y.z
: Address of the service container, will be visible in e.g. ETS-tool. If routing is activated, requires a coupler/backbone address (x.y.0
or x.0.0
).<disruptionBuffer expirationTimeout="30" udpPort="5555-5559" />
: When disruptionBuffer
is activated, missed KNX subnet frames due to a disrupted client link will be replayed when the client connection is reestablished.
expirationTimeout="30"
: Attribute allows to specify the time in seconds how long the server will keep frames before discarding them after a connection was disrupted.udpPort="5555-5559"
: The disruption buffer is only available for clients which connect via the specified (client-side) UDP port range. All other clients are ignored.<routing>224.0.23.12</routing>
(optional): the multicast setup used by the service container for KNX IP (Secure) routing, defaults to the IP multicast address 224.0.23.12. (If the routing
attribute of the service container is set to false
, this setting has no effect.)
Optional attributes for secure routing:
latencyTolerance="1000"
: time window for accepting secure multicasts (in milliseconds), depends on the max. end-to-end network latency<unixSocket>/path/to/unix/socket</unixSocket>
accept client connections over Unix domain sockets, server socket binds to the specified file-system path
<knxSubnet>
settings of the KNX subnet the service container shall communicate with. The knxSubnet
element text contains identifiers specific to the KNX subnet interface type, i.e., IP address[:port] for IP-based interfaces, or USB interface name/ID for KNX USB interfaces, constructor arguments for user-supplied network links, .... Attributes:
type
: interface type to the KNX subnet, one of:
udp
: the KNX subnet is connected via a UDP KNXnet/IP tunneling connectiontcp
: the KNX subnet is connected via a TCP KNXnet/IP tunneling connectionknxip
: the KNX subnet is connected via KNX IP or KNXnet/IP routingusb
: connect to subnet via a USB device, if the device name/ID is left empty, the first USB device found will be usedft12
: use a FT1.2 protocol connection with EMI2 format (specify the format
attribute for cEMI exchange format)tpuart
: use a TP-UART adapter to connect to a KNX TP1 networkvirtual
: run KNX subnet and enable the connection of virtual and real devicesemulate
: emulates the behaviour of a KNX subnet for process communication. KNX datapoints may be specified in an accompanying datapoint XML file.user
: own programmed connections may be added heremedium
(optional): KNX transmission medium, one of "tp1" (default), "pl110", "knxip", "rf"
tp1
: Twisted pair (transmission with 9600 Baud as specified in the KNX standard)pl110
: use power-line to connectknxip
: access via Ethernetrf
: Wireless connection via 868 MHzformat
(optional): useful for knx interfaces which support different exchange formats; recognized values are "" (default), "baos", or "cemi"knxAddress
(optional): override the knx source address used in a frame dispatched to the knx subnet, used for knx interfaces which expect a specific address (e.g., "0.0.0")netif
(tunneling only, optional): server network interface for tunneling to KNX subnetuseNat
(UDP tunneling only, optional): use network address translation (NAT)listenNetIf
(KNX IP only): network interface for KNX IP communication with the KNX subnetdomainAddress
(open media only): domain address for power-line or RF transmission mediumclass
(user-supplied KNX subnet type only): class name of a user-supplied KNXNetworkLink to use for subnet communication<datapoints ref="resources/datapointMap.xml" />
(only applies to subnet emulation, i.e., type=emulate
): External file to describe the KNX datapoints to be used in the emulated network.
ref
: relative path to XML file<groupAddressFilter>
: Contains a (possibly empty) list of KNX group addresses, which represents the server group address filter applied to messages for that service container. An empty filter list does not filter any messages. Only messages with their group address in the filter list will be forwarded.
<additionalAddresses>
: Contains a (possibly empty) list of KNX individual addresses, which are assigned to KNXnet/IP tunneling connections. An individual address has to match the KNX subnet (area, line), otherwise it will not be used! If no additional addresses are provided, the service container individual address is used, and the maximum of open tunneling connections at a time is limited to 1.
<tunnelingUsers>
(optional, only required for KNX IP secure tunneling if no keyring is used): contains a mapping of KNX IP Secure user IDs to permitted tunneling addresses.
<user id="id">
: a user ID in the integer range [1..127], with <knxAddress>
elements listing the permitted individual addresses assigned to client-side tunneling connections of that user.
<knxAddress type="individual">x.y.z</knxAddress>
: additional address entry<timeServer>
: Cyclically transmit date (DPT 11.001), time (DPT 10.001), or date+time (DPT 19.001) information on
the KNX subnet and server-side. The date/time datapoints are configured using <datapoint stateBased="true" ...>
elements. Time-server values are sent secured if the datapoint destination is in the keyring.
Turn a PL110 USB interface into a KNXnet/IP server, the USB interface name matches 'busch-jaeger'
<knxSubnet type="usb" medium="pl110" domainAddress="6f">busch-jaeger</knxSubnet>
Use the KNXnet/IP server to communicate with a KNX IP network
<knxSubnet type="knxip" listenNetIf="eth4">224.0.23.12</knxSubnet>
Load a user-supplied KNXNetworkLink class to communicate with the KNX subnet (the element text is parsed into constructor arguments of type String, using separators ',' and '|')
<knxSubnet type="user-supplied" class="my.knx.SubnetLink">o1,i2|i4</knxSubnet>
Provide a KNXnet/IP server for a KNX RF USB connection, using the USB vendor:product ID
<knxSubnet type="usb" medium="rf" domainAddress="000000004b01">0409:005a</knxSubnet>
Running the server with KNX IP Secure requires a keyring (*.knxkeys) exported from ETS, or a keyfile. A keyfile contains
Example keyfile:
// group key is a 16 byte hex value
group.key=BEEF5A1ADBEEF5A1ADBEEF5A1ADBEEF5
// device key is a 16 byte hex value
device.key=0102030405060708090a0b0c0d0e0f10
// for secure unicast, specify at least user 1 & 2 (max. 127); user 1 is used for management access
// user pwd or key, key is a 16 byte hex value (empty value means default setup key)
user[1].key=
user[2].key=d6da71bd89f7e8426250fe5657da900c
user[3].pwd=Joshua
user[4].key=...
Keyfile holding the keyring password:
keyring.pwd=Joshua
The KNXnet/IP server startup code is in Launcher.java
, a Java Runnable
which also loads the server configuration (use the server-config.xml
configuration template located in the folder resources
). The launcher expects a URI or file name pointing to the XML server configuration.
To run the KNXnet/IP server and gateway directly in Java code, see the implementation and Javadoc of Launcher.java
.
Calimero KNXnet/IP server uses the System.Logger. Bind any desired logging frameworks of your choice.