//
//  Licensed to the Apache Software Foundation (ASF) under one or more
//  contributor license agreements.  See the NOTICE file distributed with
//  this work for additional information regarding copyright ownership.
//  The ASF licenses this file to You under the Apache License, Version 2.0
//  (the "License"); you may not use this file except in compliance with
//  the License.  You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
//  Unless required by applicable law or agreed to in writing, software
//  distributed under the License is distributed on an "AS IS" BASIS,
//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
//  See the License for the specific language governing permissions and
//  limitations under the License.
//
:imagesdir: ../../images/users/protocols
:icons: font

== KNXnet/IP

=== Connection String Options

[cols="2,2a,5a"]
|===
|Name |Value |Description

|Code
2+|`knxnet-ip`

|Name
2+|KNXnet/IP Protocol

|Maven Dependency
2+|
----
<dependency>
  <groupId>org.apache.plc4x</groupId>
  <artifactId>plc4j-driver-knxnetip</artifactId>
  <version>{current-last-released-version}</version>
</dependency>
----

|Default Transport:
2+| `udp`

|Compatible Transports:
2+| - `udp` (Default Port: 3671)
//- `raw-socket`
- `pcap-replay`

3+|Supported Operations

|
| `write`
| Only supported with `tcp` transport.

|
| `subscribe`
|

3+|Options

|
| `knxproj-file-path`
| Path to the `knxproj` file. The default KNXnet/IP protocol doesn't provide all the information needed to be able to fully decode the messages. For this the user needs to provide the project file created in the KNX IDE `ETS5` to provide the missing information. Only if this file is provided, will the driver be able to decode the data entirely. If this parameter is omitted, only raw KNX payload will be returned.
NOTE: This setting is currently only supported in the Java implementation

|
| `group-address-num-levels` (3)
| KNX Addresses can be encoded in multiple ways. Which encoding is used, is too not provided by the protocol itself so it has to be provided externally:

- 3 Levels: {main-group (5 bit)}/{middle-group (3 bit)}/{sub-group (8 bit)}
- 2 Levels: {main-group (5 bit)}/{sub-group (11 bit)}
- 1 Level: {sub-group (16 bit)}

The default is 3 levels. If the `knxproj-file-path` this information is provided by the file.

|
| `connection-type`
| Type of connection used to communicate. Possible values are:

- 'LINK_LAYER' (default): The client becomes a participant of the KNX bus and gets it's own individual KNX address.
- 'RAW': The client gets unmanaged access to the bus (be careful with this)
- 'BUSMONITOR': The client operates as a busmonitor where he can't actively participate on the bus. Only one 'BUSMONITOR' connection is allowed at the same time on a KNXnet/IP gateway.

|===

=== Individual Resource Address Format

KNX Addresses usually have one of the following structures:

- 3-level Address: `{main-group(0-15)}`/`{middle-group(0-15)}`/`{sub-group(0-255)}`
- 2-level Address: `{main-group(0-15)}`/`{sub-group(0-4095)}`
- 1-level Address: `{sub-group(0-65535)}`

Depending on the `group-address-type` configured in the connection string or defined in the knxproj-file configured by the `knxproj-file-path` connection string parameter, the corresponding address pattern has to be used.

However, when subscribing for events, each segment allows using of the wildcard character `*`.
If the addresses used in the KNX installation are structured, this way it is possible to, for example (depending on the scheme used):

- Collect all information for a given level of your building: `1/*/*`
- Collect all information for a given room: `2/4/*`
- Collect all information about heating in all rooms: `*/*/50`

NOTE: Don't use wildcards when explicitly reading or writing data, this is only supported when subscribing to events.