Shared configurations in KNX IoT add-on

The KNX IoT add-on provides a set of Kconfig options that are shared across all of its samples.

Use these options to enable the KNX IoT stack, set the device identity, control commissioning behavior, select the board user interface layout, and tune the runtime and logging of the shared KNX integration library.

Configuration options

CONFIG_KNX_IOT_ADD_ON

(bool) KNX IoT stack

Enable the KNX IoT add-on. This brings in the third-party KNX IoT stack (libknx) together with the add-on’s shared KNX integration library under subsys/knx/.

CONFIG_KNX_ETS_COMMISSIONING

(bool) ETS commissioning

Configure the device from ETS over Thread.

CONFIG_KNX_HARDCODED_COMMISSIONING

(bool) Hardcoded commissioning

Apply a fixed KNX configuration on boot.

CONFIG_KNX_HARDCODED_IDENTITY_FIXED

(bool) Fixed identity

Use KNX_SERIAL_NUMBER and the Individual Address of the device’s hardcoded preset. Every device of the setup needs its own build.

CONFIG_KNX_HARDCODED_IDENTITY_HWINFO

(bool) Identity derived from the hardware device ID

Keep the manufacturer ID (the first four characters) of KNX_SERIAL_NUMBER and fill the remaining eight characters with 32 bits of the hardware device ID. The Individual Address is derived from the same bits, so one build serves every device of a role.

CONFIG_KNX_IOT_PASSWORD

(string) KNX IoT SPAKE2+ password

Password used to generate the SPAKE2+ verifier record at build time. The generated record, is used by the stack during authentication. The sample keeps the password in the image so its shell can print the onboarding QR code.

CONFIG_KNX_SERIAL_NUMBER

(string) KNX serial number

KNX serial number of the device: 12 lower-case hexadecimal characters, starting with the manufacturer ID. ETS identifies devices by serial number, so each device commissioned in the same ETS project needs a unique value. The serial number also forms the onboarding QR code and the DNS-SD hostname.

CONFIG_KNX_PROGRAMMING_MODE_AUTOSTART

(bool) Automatically enable programming mode for uncommissioned devices

Enable KNX programming mode after an uncommissioned device joins the Thread network. Programming mode is automatically disabled after the configured timeout or when ETS clears it.

CONFIG_KNX_PROGRAMMING_MODE_AUTOSTART_TIMEOUT_MINUTES

(int) Programming mode autostart timeout (minutes)

Maximum time an uncommissioned device remains discoverable in KNX programming mode after it joins the Thread network.

CONFIG_KNX_THREAD_PRIORITY

(int) KNX event-loop thread priority

Scheduling priority of the KNX worker thread that runs the stack event loop (oc_main_poll). A preemptible (positive) priority is the usual choice so networking and system work can run alongside it. The thread’s stack size is taken from KNX_THREAD_STACK_SIZE.

CONFIG_KNX_THREAD_STACK_SIZE

(int) KNX event-loop thread stack size

Stack size of the KNX worker thread that runs the stack event loop (oc_main_poll). The loop reaches into the stack’s CoAP and OSCORE paths, whose buffers dominate the requirement.

CONFIG_KNX_THREAD_FACTORY_RESET_SRP_TIMEOUT_SECONDS

(int) SRP removal timeout before Thread factory reset (seconds)

Maximum time to wait for the SRP server to confirm removal of the device’s host registration and key lease before erasing OpenThread persistent state. The factory reset continues after the timeout.

CONFIG_KNX_READ_ON_INIT_RESPONSE_TIMEOUT_MS

(int) Read-on-init response timeout (milliseconds)

Time to wait for the responses after the last read-on-init request, for group objects with the Read on Init (I) flag. After timeout datapoints without a response are read again, or reported as not received.

CONFIG_KNX_READ_ON_INIT_RETRIES

(int) Read-on-init retries

Number of times the read-on-init requests are sent again when a response is missing after KNX_READ_ON_INIT_RESPONSE_TIMEOUT_MS.

CONFIG_KNX_VERBOSE_STACK_LOGS

(bool) Verbose libknx stack logging

When enabled, libknx logs at DEBUG level and stack PRINT output is routed to Zephyr logging.

CONFIG_KNX_UI_LAYOUT_DK

(bool) Development kit (four LEDs, four buttons)

Dedicated status LEDs for Thread and KNX, a dedicated button for Thread actions and for KNX actions, two application buttons and LEDs.

CONFIG_KNX_UI_LAYOUT_SINGLE_BUTTON_RGB

(bool) Single button and RGB LED

One RGB LED shows the current commissioning stage in a different colour, and one button performs the action relevant to that stage. The devicetree must provide the knx-ui-rgb-led alias pointing to a leds-group-multicolor node, and the sw0 alias for the button.

KNX IoT stack configuration options

The KNX IoT stack provides the following Kconfig options for tuning its protocol support, table sizes, networking, security, and logging.

CONFIG_KNXIOT_LIB

(bool) KNX-IoT Point API Stack

Enable the KNX-IoT Point API protocol stack.

CONFIG_KNXIOT_MBEDTLS_BUILTIN

(bool) Use stack-bundled Mbed TLS

Corresponds to CMake: CONFIG_KNXIOT_MBEDTLS_BUILTIN. Set to n to use the Mbed TLS module provided by Zephyr.

CONFIG_KNXIOT_TINYCBOR_BUILTIN

(bool) Use stack-bundled TinyCBOR

Corresponds to CMake: CONFIG_KNXIOT_TINYCBOR_BUILTIN. TinyCBOR was dropped as a Zephyr module in Zephyr 4.x (replaced by zcbor). Set to n only if a separate external TinyCBOR module is provided in the west workspace.

CONFIG_KNXIOT_CLIENT

(bool) KNX-IoT client mode support

Corresponds to CMake: OC_CLIENT.

CONFIG_KNXIOT_SERVER

(bool) KNX-IoT server mode support

Corresponds to CMake: OC_SERVER.

CONFIG_KNXIOT_PUBLISHER_TABLE

(bool) Publisher table (Group Publisher Table) support

Corresponds to CMake: OC_PUBLISHER_TABLE_ENABLED. Enables the Group Publisher Table (GPT), which allows the device to participate in table-managed KNX S-mode group communication and to receive group messages. Disable for plain senders that only transmit S-mode messages without table-based management.

CONFIG_KNXIOT_ECHO_RING_SIZE

(int) OSCORE multicast echo ring size

Number of retained OSCORE multicast messages and echo responder records. The value must be a power of two.

CONFIG_KNXIOT_GOT_MAX_ENTRIES

(int) Group Object Table (GOT) max entries

Corresponds to CMake: KNX_GOT_MAX_ENTRIES. Maximum number of entries in the Group Object Table. Each entry maps one group object (a data point on this device) to a group address and data type. Size this to the total number of group objects the device exposes across all channels and functions.

CONFIG_KNXIOT_GPT_MAX_ENTRIES

(int) Group Publisher Table (GPT) max entries

Corresponds to CMake: KNX_GPT_MAX_ENTRIES. Maximum number of entries in the Group Publisher Table. Each entry defines a group object this device publishes (sends) S-mode messages for. Size this to the number of group objects the device actively sends.

CONFIG_KNXIOT_GRT_MAX_ENTRIES

(int) Group Recipient Table (GRT) max entries

Corresponds to CMake: KNX_GRT_MAX_ENTRIES. Maximum number of entries in the Group Recipient Table. Each entry defines a group address this device subscribes to (receives S-mode messages from). Size this to the number of group objects the device listens to.

CONFIG_KNXIOT_SEC_MAX_ENTRIES

(int) Access Token Table max entries

Corresponds to CMake: KNX_SEC_MAX_ENTRIES. Maximum number of entries in the Access Token (AT) table. Each entry holds a security token granting a management client access rights to this device. Size this to the maximum number of management clients (e.g., ETS, MaC tools) that may be simultaneously authorised.

CONFIG_KNXIOT_PAGE_SIZE

(int) Server default page size

Corresponds to CMake: KNX_PAGE_SIZE. Number of entries returned per page in paginated CoAP responses to management requests (e.g., table read-out by ETS or MaC). Reduce if CoAP response payloads exceed the network MTU.

CONFIG_KNX_UNICAST_PORT

(int) IPv6 unicast port for KNX S-mode messages

Corresponds to CMake: KNX_UNICAST_PORT. IPv6 unicast port used for sending and receiving unicast CoAP messages and KNX S-mode messages (clause 2.6.3.1, COAP_DEFAULT_PORT). The chosen port is used for all unicast traffic. Set to 0 to let the OS assign an ephemeral port.

CONFIG_KNX_MULTICAST_SCOPE

(int) IPv6 multicast scope for KNX S-mode messages

Corresponds to CMake: KNX_MULTICAST_SCOPE. This is the IPv6 multicast scope used for sending and receiving KNX S-mode messages. Scope 2 (link-local) is appropriate for isolated single-segment networks or when the router blocks site-local multicast. Scope 5 (site-local) is the default for routed deployments.

CONFIG_KNX_READ_ON_INIT_DELAY_MS

(int) Read-on-init inter-request delay (milliseconds)

Corresponds to CMake: KNX_READ_ON_INIT_DELAY_MILLISECONDS. Delay in milliseconds between consecutive S-mode read requests sent during the read-on-init sequence at device startup. Group objects with the INIT flag set are read one at a time with this delay between each request to avoid flooding the network. Increase on slow or congested networks such as Thread.

CONFIG_KNX_RESET_PROCESS_TIME_S

(int) KNX reset process time (seconds)

Corresponds to CMake: KNX_RESPONSE_TIME_SECONDS. Maximum time in seconds for the device to complete a KNX reset. This value is sent in the reset response to management clients (e.g., EITT, MaC) so they know how long to wait before issuing follow-up requests while the device is resetting locally.

CONFIG_KNXIOT_TLS_PKI

(bool) TLS PKI support

Corresponds to CMake: OC_PKI_ENABLED.

CONFIG_KNXIOT_TEST_CONTROL

(bool) Test-control endpoints (/test/restart, /test/factory-reset, /test/trigger)

Compiles api/oc_test_control.c and defines KNX_TEST_CONTROL for all targets. Registers the non-standard /test/* CoAP endpoints used by the Python runtime conformance suite (tests/runtime) to automate operator actions normally done by hand in the EITT GUI: soft restart, factory reset, and sensor trigger. The application must call oc_test_control_register() when this is set (the EITT demo app does so under #ifdef KNX_TEST_CONTROL). Off by default. The EITT demo enables it via CONFIG_KNXIOT_TEST_CONTROL=y in its prj.conf. Leave off for lssb/lsab and any production build.

CONFIG_KNXIOT_LOG_LEVEL

(int) KNX-IoT stack log level

Follows the Zephyr log level convention (CONFIG_<MODULE>_LOG_LEVEL). Corresponds to CMake: OC_PRINT_ENABLED (level > 0) / OC_DEBUG_ENABLED (level 4). 0 = OFF - no logging 1 = ERR - errors only 2 = WRN - warnings and errors 3 = INF - informational (default) 4 = DBG - debug (only available when KNXIOT_DEBUG=y)

CONFIG_KNXIOT_DEBUG

(bool) Enable debug logging (level 4)

Unlocks log level 4 (DBG) for KNXIOT_LOG_LEVEL. Corresponds to CMake: OC_DEBUG_ENABLED.

CONFIG_KNXIOT_DEBUG_OSCORE

(bool) OSCORE debug output

Corresponds to CMake: OC_DEBUG_OSCORE_ENABLED.

CONFIG_KNXIOT_LOG_HEXDUMP_DBG

(bool) Enable OC_LOGbytes() hex output

When enabled, OC_LOGbytes() and OC_LOGbytes_OSCORE() print byte buffers as lowercase hex (“xx xx …”), 32 bytes per line. Buffers of 16 bytes or fewer fit on a single line. When disabled (default), OC_LOGbytes() is a no-op on Zephyr.

CONFIG_KNXIOT_LOG_CAST_64_BIT_INTS

(bool) Cast 64-bit integers in log output

Corresponds to CMake: KNX_LOG_CAST_64_BIT_INTS_ENABLED.