Network API

With this function block the controller provides a simple, open interface for third-party devices and programs – for example an energy management system, Home Assistant, Node-RED, your own application or a script. Over a TCP connection the values of all variables in the address list can be read and written, either via a simple text protocol or via HTTP.

The Network API is the documented interface for third-party devices. Port 10001, which Studio and APP use to talk to the controller, is not intended for this: its protocol is encrypted, not published and may change with any version.

The block is created on a program page like any other function block; set port and protocol and transfer the project to the controller. Several Network API blocks with different ports are possible, e.g. one for the text protocol and one for HTTP.

Outputs
AC	Number of clients	Number of currently connected clients, updated every second. At most 32 connections are possible at the same time. With the HTTP protocol a connection is only open for the duration of one request, so the value is usually 0.
Parameters
	Port	TCP port on which the controller accepts connections (1 to 65535, default 9090). The port must not be used by another service of the controller, e.g. 10001 (Studio/APP), 80/443 (web interface) or 502 (Modbus slave).
	Protocol	Text (default): Persistent TCP connection, commands and responses line by line in the format `1/1/1=1`, terminated by LF (\n). Value changes are reported automatically to all connected clients. HTTP: One call per request in the format `http://192.168.1.90:9090/?1/1/0=1`. The controller replies with a normal HTTP response and then closes the connection. Value changes are not reported automatically.

See also common parameters of all function blocks.

Commands

Each command consists of an address from the address list, an equals sign and a value or a question mark.

Command	Effect	Response
`3/0/3=21.5`	Sets variable 3/0/3 to 21.5 and sends the value like a control element of the APP (see "Writing").	none (text) or empty response (HTTP)
`3/0/0=?`	Queries the current value of variable 3/0/0.	`3/0/0=21.340000`
`?`	Queries all variables of the address list.	one line per variable, finally `?=FINISHED`

Addresses: The addresses of the address list in the Studio apply, three-level in the form main group/middle group/sub group, e.g. 3/1/0. A dot is also accepted as separator (3.1.0), a two-level address (3/256) is converted as in the ETS. The controller always answers three-level with slashes. KNX group addresses are accessible as well as internal variables. An address that does not exist in the address list is ignored and noted in the controller log – there is no error response.

Values: Numbers are transferred with a dot as decimal separator. In responses they always have six decimal places, e.g. 1.000000 for on and 0.000000 for off. When writing, 1 or 21.5 is sufficient. Text variables (EIS 15 Zeichenkette) are transferred as plain text; the text itself may contain an equals sign. All other values are passed as numbers, the controller converts them into the KNX format (e.g. 2-byte float). Time, date and colour values are not supported by the Network API.

Line end: In the text protocol each command must be terminated with LF (\n), an additional CR (\r) is ignored. Every response line ends with LF. A line may be at most 1023 characters long.

Reading

A read command returns the value the controller currently holds for this variable. No telegram is sent on the KNX bus and nothing in the project is changed. The value is the last one received or sent – for a KNX address, the value of the last telegram the controller has seen on the bus.

A client that only reads sends only commands with ?. The interface itself has no read-only mode, see "Security".

Writing

A write command has the same effect as operating the value in the APP: the controller takes over the value into the variable, linked function blocks react to it, and if the address is a KNX group address a write telegram is sent on the KNX bus. For an internal variable the value stays in the controller.

The controller does not report whether an actuator has executed the command. To check this, query the feedback address of the actuator or wait for its change message in the text protocol.

Change messages (text protocol only)

With the text protocol there is no need for cyclic polling. As long as the connection exists, the controller sends every value change of a variable unsolicited to all connected clients, in the same format as a response, e.g. 3/0/0=21.400000. This applies to telegrams from the KNX bus as well as to values from function blocks, the APP or other interfaces. Values written by a client via the Network API itself are not reported back to the clients.

There is no selection of individual addresses – the client receives all changes and filters them itself. The usual approach: after connecting, send ? once to get the initial state, then only evaluate the change messages.

With the HTTP protocol no changes are reported; here polling is required.

Examples

Text protocol, e.g. with netcat (finish each input with Enter):

nc 192.168.1.90 9090
3/0/0=?
3/0/0=21.340000
3/1/1=?
3/1/1=1.000000
3/0/0=21.400000      <- change message, unsolicited

HTTP, e.g. with curl or in the browser:

curl "http://192.168.1.90:9090/?3/0/0=?"
3/0/0=21.340000

curl "http://192.168.1.90:9090/??"
1/1/0=0.000000
...
?=FINISHED

curl "http://192.168.1.90:9090/?3/0/3=21.5"

In the HTTP call, spaces and special characters must be encoded as usual (%20 for a space). Several commands in one call are separated by %0A, e.g. /?3/0/0=?%0A3/0/4=?. The response is plain text (text/plain, UTF-8).

Python, text protocol with change messages:

import socket
s = socket.create_connection(("192.168.1.90", 9090))
s.sendall(b"?\n")                        # initial state
buf = b""
while True:
    buf += s.recv(4096)
    while b"\n" in buf:
        line, buf = buf.split(b"\n", 1)
        addr, value = line.decode().split("=", 1)
        print(addr, value)

Security

The Network API has no login and no encryption. Every device that can reach the configured port can read and write all variables – and thus, via KNX addresses, also switch heating, hot water, shading or door openers. Therefore:

Only create the block if it is needed. Without a Network API block the port is closed.
Never forward the port to the internet in the router. Use a VPN for remote access.
Restrict access within the network to the devices that need it, e.g. with a firewall rule or a separate network segment.
The common parameter "Deactivate" switches the block off without deleting it – the port is then closed.

Limits

At most 32 simultaneous connections per block. Further connections are only accepted once a slot is free again (after 10 seconds at the latest).
A client that does not accept data within 5 seconds is disconnected.
An HTTP request must arrive completely within 5 seconds.
There is no fixed minimum interval. With the text protocol, cyclic polling is unnecessary. When polling via HTTP, an interval of 5 to 60 seconds is sufficient for states and temperatures. Querying all variables with ? generates a lot of traffic in large projects and should not run every second.
Every write command to a KNX address generates a telegram on the bus. Therefore only write values on change, not cyclically – a KNX bus only copes with a few dozen telegrams per second.

Frequently asked questions on connecting third-party systems

Which interface is intended for a third-party system?

For reading and writing variables, this Network API is the open, documented interface. In addition there are MQTT addresses I/O (variables as MQTT topics, e.g. for Home Assistant, ioBroker or Node-RED) and the Modbus TCP slave. Port 10001 belongs to Studio and APP; its protocol is not published and not released for third-party systems.

All these interfaces are function blocks. They only become active once they have been created in the project and the project has been transferred to the controller – none of them can be switched on without a transfer. Therefore always start from the project version currently running in the controller (see "Project with an older Studio" below).

Does the Network API need a licence or activation?

No. The Network API does not require a licence option of its own; it is available on every controller that runs a program.

How does a third-party system log in?

Not at all – there is no user, no password and no encryption. Anyone who can reach the port has access. Protection must be provided by the network, see "Security".

Is read-only access possible?

Read commands (…=? and ?) change nothing and send no KNX telegram. However, there is no way to block write access: whether only reading takes place is up to the third-party system. Only a command with a value (3/1/0=1) writes.

Are there push messages on value changes?

Yes, with the text protocol all changes are sent automatically, see "Change messages". With HTTP, polling is required.

Are there test tools or examples?

netcat, curl or a browser are sufficient for testing, see "Examples". To try out a third-party system safely, start by only reading. Invalid commands and addresses missing from the address list are noted in the controller log.

Which KNX data type applies to a variable?

The data types in the Studio are named after the old EIS numbering, not after the KNX DPT number, and they are shown in German in every language. The number in the name is therefore not the DPT main number:

Studio	KNX DPT
EIS 1: Bit schalten (Bit)	DPT 1 (1 bit)
EIS 5: Fließkomma (2 Byte)	DPT 9 (2-byte float, e.g. 9.001 temperature)
EIS 6: Relativ Wert 0-100% (1 Byte)	DPT 5.001
EIS 9: Fließkomma (4 Byte)	DPT 14
EIS 10: Zähler Wert 16 Bit (2 Byte)	DPT 7 (unsigned) or DPT 8
EIS 11: Zähler Wert 32 Bit (4 Byte)	DPT 12 (unsigned) or DPT 13
EIS 14: Zähler Wert (1 Byte)	DPT 5 (unsigned) or DPT 6
EIS 15: Zeichenkette (14/255 Byte)	DPT 16

Via the Network API the byte encoding does not matter: values are transferred as plain-text numbers (21.500000), the controller converts them into the KNX format. The DPT is only needed if a third-party system listens directly on the KNX bus.

Can addresses and data types be exported?

Yes, in the Studio via "Edit – Addresses ODBC Export", either all or only the selected addresses. Available formats are the XML format of the ETS group address export (name, address, DPT) and the ESF format (text file with group names, address, comment and data type). Links to function blocks and control elements are not exported.

Can the controller's KNX interface be used as a KNXnet/IP interface?

Controllers with a built-in KNX interface include an internal KNX IP gateway. As long as it is switched off, UDP port 3671 cannot be reached. It is switched on in the Studio under "Control – Services" or in the web interface. In the KNX interface block the type "KNX-IP Gateway onboard" must be set for this.

KNXnet/IP tunnelling via UDP, port 3671; the gateway is found by the interface search. Routing only if "Router function" is switched on in the KNX interface block.
Several tunnel connections at the same time are possible. The number results from "Phys. address count" in the KNX interface block: the first address is given to the controller, the second to the gateway, the rest to the tunnel connections – one of which is used by the controller itself. With the default of 4, exactly one connection remains free, e.g. for the ETS. For an additional third-party system, increase the count (up to 8).
The individual address of a tunnel connection is assigned from this range; it cannot be set individually.
The gateway is intended for programming with the ETS. It is third-party software; KNX IP Secure is not supported. A third-party system on the tunnel sees and sends telegrams directly on the bus, bypassing the controller – it must not disturb the installation any more than an additional KNX device would.

If you only want to read values or control individual functions, the Network API or MQTT is usually the better choice: the third-party system then works with the same variables as the controller, including internal variables that never reach the bus.

Can the Modbus TCP slave be used for a third-party system?

Yes. Create a Modbus TCP slave block and link the variables that are to be available as registers to its inputs. Port 502 is only open once such a block exists in the project. Register assignment and function codes are described in the help of the block.

Project with an older Studio: "Unknown function block"

If the Studio shows "Unknown function block" when opening a project, the Studio is older than the project and does not know this block yet. These are not customer-specific blocks.

Do not save or transfer the project in this state – when saving, the unknown block is permanently replaced by a comment and is then missing from the program.
Install the current Studio. "Control – Control information" shows which version runs in the controller; the Studio should have at least this version.
Before any change, save a copy of the project (File – Save as), only then create the new block and transfer the project.