{"id":42850256,"url":"https://github.com/supergiovane/knxultimate","last_synced_at":"2026-02-18T12:01:24.779Z","repository":{"id":38795073,"uuid":"456427950","full_name":"Supergiovane/KNXUltimate","owner":"Supergiovane","description":"KNX IP Protocol implementation for node.js","archived":false,"fork":false,"pushed_at":"2026-01-30T10:13:36.000Z","size":9278,"stargazers_count":37,"open_issues_count":0,"forks_count":12,"subscribers_count":6,"default_branch":"main","last_synced_at":"2026-01-31T02:15:18.539Z","etag":null,"topics":["iot","knx","nodejs"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Supergiovane.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2022-02-07T08:59:38.000Z","updated_at":"2026-01-30T10:13:40.000Z","dependencies_parsed_at":"2024-05-28T14:33:31.135Z","dependency_job_id":"6a267dcc-e621-4ca7-9346-a0eef8a87299","html_url":"https://github.com/Supergiovane/KNXUltimate","commit_stats":{"total_commits":93,"total_committers":2,"mean_commits":46.5,"dds":"0.043010752688172005","last_synced_commit":"6852548ea5cff6c02891999f27baa41701967022"},"previous_names":[],"tags_count":61,"template":false,"template_full_name":null,"purl":"pkg:github/Supergiovane/KNXUltimate","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Supergiovane%2FKNXUltimate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Supergiovane%2FKNXUltimate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Supergiovane%2FKNXUltimate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Supergiovane%2FKNXUltimate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Supergiovane","download_url":"https://codeload.github.com/Supergiovane/KNXUltimate/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Supergiovane%2FKNXUltimate/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29578143,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-18T08:38:15.585Z","status":"ssl_error","status_checked_at":"2026-02-18T08:38:14.917Z","response_time":162,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["iot","knx","nodejs"],"created_at":"2026-01-30T12:02:18.590Z","updated_at":"2026-02-18T12:01:24.772Z","avatar_url":"https://github.com/Supergiovane.png","language":"TypeScript","funding_links":["https://www.paypal.com/donate/?hosted_button_id=S8SKPUBSPK758"],"categories":[],"sub_categories":[],"readme":"![Logo](img/logo-big.png)\n\n[![CI](https://github.com/Supergiovane/KNXUltimate/actions/workflows/ci.yml/badge.svg)](https://github.com/Supergiovane/KNXUltimate/actions/workflows/ci.yml)\n[![NPM version][npm-version-image]][npm-url]\n[![NPM downloads per month][npm-downloads-month-image]][npm-url]\n[![NPM downloads total][npm-downloads-total-image]][npm-url]\n[![MIT License][license-image]][license-url]\n[![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://standardjs.com)\n[![Youtube][youtube-image]][youtube-url]\n\nKNX protocol implementation for Node.js, support KNX/IP Tunneling/Routing, KNX/IP Secure and Data Secure, FT1.2/KBerry TP plain KNXas well as full secure KNX stack. \n\nThis is the official engine of Node-Red's node [node-red-contrib-knx-ultimate](https://flows.nodered.org/node/node-red-contrib-knx-ultimate)  \n\n\u003cbr/\u003e\n\n```bash\n  npm i knxultimate\n```\n\n\n![Logo](img/readmemain.png)\n\n\n\u003cp align='center'\u003e\n\u003cimg width=\"110px\" src=\"https://raw.githubusercontent.com/Supergiovane/KNXUltimate/master/img/KNX_CERTI_MARK_RGB.jpg\" \u003e\u003c/br\u003e\u003c/br\u003e\u003c/br\u003e\n\u003cimg width=\"100px\" src=\"https://raw.githubusercontent.com/Supergiovane/KNXUltimate/master/img/knxsecure.png\" \u003e\u003c/br\u003e\u003c/br\u003e\n\u003cspan style=\"font-size:0.5em;color:grey;\"\u003eAuthorized KNX logo by KNX Association*\u003c/span\u003e\n\u003c/p\u003e\n\n\n## CHANGELOG\n\n- [Changelog](https://github.com/Supergiovane/knxultimate/blob/master/CHANGELOG.md)\n\n  \n\n| Technology            | Supported                                                            |\n| --------------------- | -------------------------------------------------------------------- |\n| KNX IP Full Stack  | ![](https://placehold.co/200x20/green/white?text=YES)                |\n| KNX IP Secure Full stack | ![](https://placehold.co/200x20/green/white?text=YES)         |\n| KNX TP Serial FT1.2/KBERRY/BAOS | ![](https://placehold.co/200x20/green/white?text=YES) |\n| KNX TP Secure Full stack| ![](https://placehold.co/200x20/green/white?text=YES) |\n\n\nPlease subscribe to my channel, to learn how to use it [![Youtube][youtube-image]][youtube-url]  \n\n [![Donate via PayPal](https://raw.githubusercontent.com/Supergiovane/node-red-contrib-knx-ultimate/master/img/CodiceQR.png)](https://www.paypal.com/donate/?hosted_button_id=S8SKPUBSPK758)\n\n## CONNECTION SETUP\n\nThese are the properties you can pass to `KNXClient` (see examples for full usage):\n\n| Property                         | Applies to                         | Description |\n| -------------------------------- | ---------------------------------- | ----------- |\n| `hostProtocol` (string)          | all                                | One of: `\"TunnelUDP\"` (plain tunnelling via UDP), `\"Multicast\"` (plain routing via multicast 224.0.23.12), `\"TunnelTCP\"` (KNX/IP Secure tunnelling over TCP), `\"SerialFT12\"` (direct TP/FT1.2 serial interface such as `/dev/ttyAMA0`). |\n| `ipAddr` (string)                | all                                | KNX/IP peer address. Use `\"224.0.23.12\"` for routing (multicast), or the interface/router IP for tunnelling. |\n| `ipPort` (number/string)         | all                                | KNX/IP port. Default `3671`. |\n| `physAddr` (string) Optional             | all                                | Source IA on bus (e.g. `\"1.1.200\"`). Multicast: required. TunnelUDP: used as cEMI source. TunnelTCP (secure): ignored as bus source — the gateway assigns the tunnel IA; Data Secure uses the interface IA from ETS for authentication. |\n| `loglevel` (string)              | all                                | One of: `disable`, `error`, `warn`, `info`, `debug`, `trace`. |\n| `localIPAddress` (string)        | all                                | Optional. Binds the local UDP/TCP socket to a specific local interface IP. Useful with multiple NICs. |\n| `interface` (string)             | all                                | Optional. Local interface name to select the NIC (alternative to `localIPAddress`). |\n| `serialInterface` (object)       | SerialFT12                         | Serial port settings used when `hostProtocol === 'SerialFT12'`. Supports `path` (default `/dev/ttyAMA0`), `baudRate` (default 19200), `dataBits`, `stopBits`, `parity` (`'even'` by default), `rtscts`, `dtr`, `timeoutMs`, `lock` (forwarded to `serialport`), and `isKBERRY` (default `true`, enable Weinzierl KBerry/BAOS initialisation). |\n| `KNXQueueSendIntervalMilliseconds` (number) | all              | Optional. Inter‑telegram delay in ms. Default ~25ms. Don’t go below 20ms. |\n| `suppress_ack_ldatareq` (bool)   | tunnelling (UDP/TCP)               | Optional. Avoid requesting/handling L_DATA_REQ bus ACK in tunnelling. Leave `false` unless your interface needs it. |\n| `theGatewayIsKNXVirtual` (bool)  | tunnelling                         | Optional. Special handling for ETS KNX Virtual (adds `localIPAddress` to tunnel endpoint). Default `false`. |\n| `isSecureKNXEnabled` (bool)      | IP secure, serial Data Secure      | Enable KNX/IP Secure. With `TunnelTCP`: session handshake + Secure Wrapper. With `Multicast`: secure routing (Secure Wrapper, timer sync). With `SerialFT12`: enable KNX Data Secure on TP (group keys only, no IP wrapper). |\n| `secureTunnelConfig` (object)    | secure tunnelling, routing, serial | KNX Secure configuration. For `TunnelTCP`/routing it drives both tunnel auth and Data Secure; for `SerialFT12` only the keyring fields (`knxkeys_file_path` or `knxkeys_buffer`, plus `knxkeys_password`) are used to load group keys for Data Secure on TP. |\n| `secureRoutingWaitForTimer` (bool)| secure routing (multicast)        | Optional. Wait for first timer sync (0955/0950) before sending. Default `true`. |\n\n### Serial FT1.2 (TP) mode / KBerry (see below how to setup the RPi and KBERRY)\n\nChoose `hostProtocol: 'SerialFT12'` to connect directly to KNX TP via a serial FT1.2 interface. This mode is primarily designed and tested for **Weinzierl KBerry / BAOS** modules running in Link Layer (`cEMI`) mode over FT1.2. Configure the serial line via the `serialInterface` option; by default `/dev/ttyAMA0`, 19200 baud, 8E1, DTR on, RTS/CTS off are used.\n\nThis transport supports KNX Data Secure on TP: set `isSecureKNXEnabled: true` and provide an ETS keyring via `secureTunnelConfig.knxkeys_file_path` (or `secureTunnelConfig.knxkeys_buffer`) plus `secureTunnelConfig.knxkeys_password`. Verified with **Weinzierl KBerry / BAOS** modules; leave `serialInterface.isKBERRY` at its default `true` to run their FT1.2 init sequence automatically.\n\nList all available serial devices before connecting:\n\n```ts\nimport KNXClient from 'knxultimate'\n\nasync function connectSerial() {\n  const ports = await KNXClient.listSerialInterfaces()\n  ports.forEach((p) =\u003e console.log('Serial port:', p.path))\n\n  const client = new KNXClient({\n    hostProtocol: 'SerialFT12',\n    serialInterface: {\n      path: '/dev/ttyAMA0',\n      baudRate: 19200,\n      dataBits: 8,\n      stopBits: 1,\n      parity: 'even',\n      // KBerry / BAOS helpers:\n      isKBERRY: true,   // default\n      lock: false,      // optional, useful on macOS\n    },\n    physAddr: '15.15.255', // source IA on the bus\n    loglevel: 'info',\n    // Optional: enable KNX Data Secure on TP using an ETS keyring\n    isSecureKNXEnabled: true,\n    secureTunnelConfig: {\n      knxkeys_file_path: '/path/to/Project.knxkeys',\n      // Alternatively: knxkeys_buffer: fs.readFileSync('/path/to/Project.knxkeys'),\n      knxkeys_password: 'your-ets-password',\n      // tunnel* fields are ignored in SerialFT12 mode (no IP tunnel auth); only group keys are used.\n    },\n  })\n\n  client.on('connected', () =\u003e console.log('Serial FT1.2 ready'))\n  client.on('indication', (packet) =\u003e console.log('Telegram:', packet))\n  client.Connect()\n}\n```\n\nRemember to configure the physical address (`physAddr`) that ETS assigns to your TP interface; the serial transport uses that IA on the bus. In KBerry mode (`isKBERRY: true`) the driver automatically:\n\n- Sends an FT1.2 reset\n- Switches the BAOS communication mode to Link Layer (`cEMI`)\n- Enables indication sending\n- Sets the Address Table length to 0 (no GA filter, all group telegrams are forwarded)\n- If `isSecureKNXEnabled: true` and an ETS keyring is configured in `secureTunnelConfig`, loads group keys and applies **KNX Data Secure** on TP for those Group Addresses (cEMI `L_Data.req` / `L_Data.ind` are encrypted/decrypted end‑to‑end). No IP Secure wrapper is used on the serial line; only the APDU is protected.\n## SUPPORTED DATAPOINTS\n\nFor each Datapoint, there is a sample on how to format the payload (telegram) to be passed.\u003cbr/\u003e\n\nFor example, pass a *true* for datapoint \"1.001\", or *{ red: 125, green: 0, blue: 0 }* for datapoint \"232.600\".\u003cbr/\u003e\n\nIt support a massive number of Datapoints. Please run the \u003ccode\u003eexamples/showDatapoints.ts\u003c/code\u003e file to view all datapoints in the output console.\u003cbr/\u003e\n\nBe aware, that the descriptions you'll see, are taken from Node-Red KNX-Ultimate node, so there is more code than you need here. Please take only the *msg.payload* part in consideration.\u003cbr/\u003e\n\nYou should see something like this in the console window (the **msg.payload** is what you need to pass as payload):\n\n\u003cimg src='https://raw.githubusercontent.com/Supergiovane/knxultimate/master/img/dpt.png' width='60%'\u003e\n\n## METHODS/PROPERTIES OF KNXULTIMATE\n\n| Method                             | Description                                                                                          |\n| ---------------------------------- | ---------------------------------------------------------------------------------------------------- |\n| .Connect()                         | Connects to the KNX Gateway                                                                          |\n| .Disconnect()                      | Gracefully disconnects from the KNX Gateway                                                          |\n| .write (GA, payload, datapoint)    | Sends a WRITE telegram to the BUS. **GA** is the group address (for example \"0/0/1\"), **payload** is the value you want to send (for example true), **datapoint** is a string representing the datapoint (for example \"5.001\") |\n| .writeRaw (GA, payload, bitlength) | Sends a WRITE telegram to the BUS. **GA** is the group address (for example \"0/0/1\"), **payload** is the raw buffer you want to send, **bitlength** is the payload length in bits (used especially for payloads \u003c= 6 bits) |\n| .respond (GA, payload, datapoint)  | Sends a RESPONSE telegram to the BUS. **GA** is the group address (for example \"0/0/1\"), **payload** is the value you want to send (for example true), **datapoint** is a string representing the datapoint (for example \"5.001\") |\n| .respondRaw (GA, payload, bitlength) | Sends a RESPONSE telegram to the BUS. **GA** is the group address (for example \"0/0/1\"), **payload** is the raw buffer you want to send, **bitlength** is the payload length in bits (used especially for payloads \u003c= 6 bits) |\n| .read (GA)                         | Sends a READ telegram to the BUS. **GA** is the group address (for example \"0/0/1\").                 |\n| . discover()                        | Sends a discover request on the KNX default multicast port and returns the results as an array. This is an async method. See the example in the **examples** folder |\n| .getGatewayDescription()           | Sends a gateway description request. It works after an established connection. The async results will be sent to the *descriptionResponse* event. There is an example in the **examples** folder named **gatewaydescription.ts** . |\n\n### writeRaw notes\n\n`writeRaw(GA, payloadBuffer, bitlength)` sends a GroupValue_Write with a raw APDU payload.\n\n- Use `bitlength \u003c= 6` for \"6-bit\" payloads (the value is encoded into the low APCI bits, so `payloadBuffer` should be 1 byte and `\u003c= 0x3f`).\n- For normal datapoints, you can build `(payloadBuffer, bitlength)` with `dptlib.populateAPDU(...)` and pass them to `writeRaw`.\n- See `examples/writeRaw.ts`.\n\n### respondRaw notes\n\n`respondRaw(GA, payloadBuffer, bitlength)` sends a GroupValue_Response with a raw APDU payload.\n\n- Payload rules are the same as `writeRaw` (including `bitlength \u003c= 6` handling).\n- See `examples/respondRaw.ts`.\n\n| Property       | Description                                                                                          |\n| -------------- | ---------------------------------------------------------------------------------------------------- |\n| .isConnected() | Returns **true** if you the client is connected to the KNX Gateway Router/Interface, **false** if not connected. |\n| .clearToSend   | **true** if you can send a telegram, **false** if the client is still waiting for the last telegram's ACK or whenever the client cannot temporary send the telegram. In tunneling mode, you could also refer to the event **KNXClientEvents.ackReceived**, that is fired everytime a telegram has been succesfully acknowledge or not acknowledge. See the sample.js file. |\n| .channelID     | The actual Channel ID. Only defined after a successfull connection                                   |\n\n## EVENTS\n\nList of events raised by KNXultimate, in proper order. For the signatures, please see the **examples** folder.\n\n| Event        | Description                                                                                          |\n| ------------ | ---------------------------------------------------------------------------------------------------- |\n| connecting   | KNXUltimate is connecting to the KNX/IP Gateway. Please wait for the *connected* event to start sending KNX telegrams. |\n| connected    | KNXUltimate has successfully connected with the KNX/IP Gateway.                                      |\n| indication   | KNXUltimate has received a KNX telegram, that's avaiable in te the **datagram** variable. Please see the examples. |\n| ackReceived  | Ack telegram from KNX/IP Gateway has been received. This confirms that the telegram sent by KNXUltimate has reached the KNX/IP Gateway successfully. |\n| disconnected | The KNX connection has been disconnected.                                                            |\n| close        | The main KNXUltimate socket has been closed.                                                         |\n| error        | KNXUltimate has raised an error. The error description is provided as well.                         |\n| descriptionResponse | Gather the *getGatewayDescription* responses. There is an example in the **examples** folder named **gatewaydescription.ts** . |\n\n## LOG STREAM\n\n\nKNXUltimate logging is managed by [Winston](https://github.com/winstonjs/winston) logger. In case you want to intercept library logs you can use our `logStram` exported from default entrypoint. Example:\n```typescript\nimport { logStream } from 'knxultimate'  \n\nlogStream.on('data', (log) =\u003e {  \n    // handle log  \n    if(log.level === 'ERROR)  \n        console.log(`${log.timestamp} ${log.message}`)  \n}) \n```\n\n| Field                          | Description                                                   |\n| ------------------------------ | ------------------------------------------------------------- |\n| timestamp                      | ISO formatted date (YYYY-MM-DD HH:mm:ss.SSS)                  |\n| level                          | Log level in uppercase (ERROR, WARN, INFO, DEBUG)             |\n| label                          | Module name in uppercase (specified when creating logger)      |\n\n## Plain KNX: Quick Examples\n\nBelow are short, progressively richer examples to connect in plain (non‑secure) KNX and listen or interact with the bus. Copy/paste inline; no extra files are created.\n\n### 1) Minimal tunnelling (UDP) listener\n\n```ts\nimport KNXClient from 'knxultimate'\n\nconst client = new KNXClient({\n  hostProtocol: 'TunnelUDP',\n  ipAddr: '192.168.1.117',  // your KNX/IP interface IP\n  ipPort: 3671,\n  loglevel: 'info',\n})\n\nclient.on('connected', () =\u003e console.log('✓ Plain tunnelling connected'))\nclient.on('error', (e) =\u003e console.error('Error:', e.message))\nclient.on('disconnected', (reason) =\u003e console.log('Disconnected:', reason))\n\nclient.on('indication', (packet) =\u003e {\n  const cemi = packet?.cEMIMessage\n  if (!cemi) return\n  const src = cemi.srcAddress?.toString?.()\n  const dst = cemi.dstAddress?.toString?.()\n  const isWrite = cemi.npdu?.isGroupWrite\n  const isResp = cemi.npdu?.isGroupResponse\n  const raw: Buffer | undefined = cemi.npdu?.dataValue\n  console.log('indication', { src, dst, isWrite, isResp, raw: raw?.toString('hex') })\n})\n\nclient.Connect()\n```\n\n### 2) Decode a boolean datapoint (1.001)\n\n```ts\nimport KNXClient, { KNXClientEvents } from 'knxultimate'\nimport { dptlib } from 'knxultimate'\n\nconst client = new KNXClient({ hostProtocol: 'TunnelUDP', ipAddr: '192.168.1.117', ipPort: 3671 })\n\nclient.on(KNXClientEvents.indication, (packet) =\u003e {\n  const cemi = packet?.cEMIMessage\n  if (!cemi?.npdu) return\n  const dst = cemi.dstAddress?.toString?.()\n  const raw: Buffer | undefined = cemi.npdu?.dataValue\n  if (!dst || !raw) return\n  if (dst === '0/1/25') { // for example: a status GA known to be 1.001\n    const cfg = dptlib.resolve('1.001')\n    const value = dptlib.fromBuffer(raw, cfg)\n    console.log(`dst=${dst} -\u003e`, value)\n  }\n})\n\nclient.Connect()\n```\n\n### 3) Plain routing (Multicast) listener\n\n```ts\nimport KNXClient from 'knxultimate'\n\nconst client = new KNXClient({\n  hostProtocol: 'Multicast',\n  ipAddr: '224.0.23.12',\n  ipPort: 3671,\n  physAddr: '1.1.200',   // set your device IA for routing\n  loglevel: 'info',\n})\n\nclient.on('connected', () =\u003e console.log('✓ Plain multicast ready'))\nclient.on('error', (e) =\u003e console.error('Error:', e.message))\nclient.on('indication', (packet) =\u003e {\n  const cemi = packet?.cEMIMessage\n  if (!cemi?.npdu) return\n  const dst = cemi.dstAddress?.toString?.()\n  const raw: Buffer | undefined = cemi.npdu?.dataValue\n  console.log('routing ind', { dst, raw: raw?.toString('hex') })\n})\n\nclient.Connect()\n```\n\n### 4) Write and then READ a status (plain)\n\n```ts\nimport KNXClient from 'knxultimate'\nimport { dptlib } from 'knxultimate'\n\nconst client = new KNXClient({ hostProtocol: 'TunnelUDP', ipAddr: '192.168.1.117', ipPort: 3671 })\n\nfunction waitForStatus(ga: string, timeoutMs = 3000): Promise\u003cnumber\u003e {\n  return new Promise((resolve, reject) =\u003e {\n    const t = setTimeout(() =\u003e { client.off('indication', onInd); reject(new Error('Timeout')) }, timeoutMs)\n    const onInd = (packet: any) =\u003e {\n      const cemi = packet?.cEMIMessage\n      if (!cemi || cemi.dstAddress?.toString?.() !== ga) return\n      const npdu = cemi.npdu\n      if (!(npdu?.isGroupResponse || npdu?.isGroupWrite)) return\n      const raw: Buffer = npdu?.dataValue ?? Buffer.alloc(1, 0)\n      const bit = (raw.readUInt8(0) ?? 0) \u0026 0x01\n      clearTimeout(t)\n      client.off('indication', onInd)\n      resolve(bit)\n    }\n    client.on('indication', onInd)\n  })\n}\n\nasync function main() {\n  client.Connect()\n  await new Promise\u003cvoid\u003e((res) =\u003e client.once('connected', () =\u003e res()))\n  // Write ON\tn\n  client.write('0/1/1', true, '1.001')\n  // Read status\n  client.read('0/1/25')\n  const val = await waitForStatus('0/1/25', 3000)\n  console.log('Status:', val ? 'ON' : 'OFF')\n}\n\nmain().catch(console.error)\n```\n\n## KNX/IP Secure: Quick Examples\n\nBelow are progressively richer examples to connect to a KNX/IP Secure gateway and listen for telegrams with decrypted payloads. These are meant to be copy‑pasted inline (no files are added under `examples/`). All snippets assume TypeScript/Node 18+.\n\nImportant notes\n- The client emits the full datagram on `indication`, and its `cEMIMessage` is already plain (decrypted) when keys are available in your ETS keyring.\n- Never commit your `.knxkeys` file. Keep its path/password in environment variables or local config.\n- Alternative to `knxkeys_file_path`: pass the raw keyring bytes via `secureTunnelConfig.knxkeys_buffer` (still requires `knxkeys_password`).\n- Secure TCP tunnel auto‑select: if `secureTunnelConfig.tunnelInterfaceIndividualAddress` is omitted or empty, the client tries all interfaces found in the ETS keyring until authentication and connect succeed, then proceeds and keeps the tunnel open. The chosen IA is exposed on `client._options.secureTunnelConfig.tunnelInterfaceIndividualAddress` after connect.\n\n### 1) Minimal secure tunnelling (TCP) listener\n\n```ts\nimport KNXClient, { SecureConfig } from 'knxultimate'\n\n// 1) Configure ETS keyring + the interface IA used in your project\nconst secureCfg: SecureConfig = {\n  // tunnelInterfaceIndividualAddress: '1.1.254',   // Optional: omit to auto‑select a free tunnel\n  knxkeys_file_path: process.env.KNX_KEYS_PATH || '/path/to/Project.knxkeys',\n  knxkeys_password: process.env.KNX_KEYS_PASSWORD || 'your-ets-password',\n}\n\n// 2) Create a KNX/IP Secure TCP client\nconst client = new KNXClient({\n  hostProtocol: 'TunnelTCP',\n  ipAddr: '192.168.1.4',\n  ipPort: 3671,\n  isSecureKNXEnabled: true,\n  secureTunnelConfig: secureCfg,\n  loglevel: 'info',\n})\n\nclient.on('connected', () =\u003e console.log('✓ Secure tunnel connected'))\nclient.on('error', (e) =\u003e console.error('Error:', e.message))\nclient.on('disconnected', (reason) =\u003e console.log('Disconnected:', reason))\n\n// 3) Listen: cEMI payload is already decrypted when Data Secure is used\nclient.on('indication', (packet) =\u003e {\n  const cemi = packet?.cEMIMessage\n  if (!cemi) return\n  const dst = cemi.dstAddress?.toString?.()\n  const src = cemi.srcAddress?.toString?.()\n  const isWrite = cemi.npdu?.isGroupWrite\n  const isResp = cemi.npdu?.isGroupResponse\n  const raw: Buffer | undefined = cemi.npdu?.dataValue\n  console.log('indication', { src, dst, isWrite, isResp, raw: raw?.toString('hex') })\n})\n\nasync function main() {\n  client.Connect()\n  await new Promise\u003cvoid\u003e((res) =\u003e client.once('connected', () =\u003e res()))\n  console.log('Listening… Press Ctrl+C to exit')\n}\n\nmain().catch(console.error)\n```\n\n### 1b) Secure tunnelling with only tunnel password\n\nWhen you do not have access to the ETS keyring you can still negotiate KNX/IP Secure by providing the tunnel IA and password directly. This gives you encrypted tunnelling, while Data Secure and secure multicast stay disabled. The user ID defaults to `2`, which is the standard KNX Secure tunnel account.\n\n```ts\nimport KNXClient, { SecureConfig } from 'knxultimate'\n\nconst tunnelPassword = process.env.KNX_TUNNEL_PASSWORD\nif (!tunnelPassword) {\n  throw new Error('Set KNX_TUNNEL_PASSWORD with your secure tunnel password')\n}\n\nconst secureCfg: SecureConfig = {\n  tunnelInterfaceIndividualAddress: '1.1.254',\n  tunnelUserPassword: tunnelPassword,\n  tunnelUserId: 2, // Replace with your tunnel user ID from ETS (number or numeric string)\n}\n\nconst client = new KNXClient({\n  hostProtocol: 'TunnelTCP',\n  ipAddr: '192.168.1.4',\n  ipPort: 3671,\n  isSecureKNXEnabled: true,\n  secureTunnelConfig: secureCfg,\n})\n\nclient.on('connected', () =\u003e console.log('✓ Secure tunnel connected (manual password)'))\nclient.on('error', (e) =\u003e console.error('Error:', e.message))\n\nclient.Connect()\n```\n\n\u003e **Note:** ETS assigns a dedicated `tunnelUserId` to each secure tunnel. Set `secureTunnelConfig.tunnelUserId` (number or numeric string) together with the password, otherwise the gateway replies with `Secure Session Status = 1` and the connection is closed.\n\n### Secure workflow recap\n\n- **KNX IP Tunnelling Secure** protects the TCP channel. The gateway authenticates a tunnel user by ID + password during the `Secure Session Authenticate (0x0953)` step. Provide the password either from the keyring (`secureTunnelConfig.knxkeys_*`) or manually via `secureTunnelConfig.tunnelUserPassword`; in both cases the `tunnelUserId` must match the ETS commissioning data.\n- **KNX Data Secure** protects group-address telegrams. It relies on group keys stored in the ETS keyring, so a `.knxkeys` file plus its password are mandatory whenever you need encrypted group communication.\n- **Supported combinations**\n  - *Keyring only*: set `knxkeys_file_path` (or `knxkeys_buffer`) + `knxkeys_password` and omit `tunnelUserPassword`. Both the tunnel password and the group keys are loaded from the keyring.\n- *Manual tunnel password only*: set both `tunnelUserPassword` and `tunnelUserId` without a keyring. The IP channel is secured, but Data Secure stays disabled because no group keys are present.\n  - *Keyring + manual password*: provide the keyring for Data Secure and override the tunnelling password with `tunnelUserPassword` (useful when the ETS export does not include the tunnel password). Ensure `knxkeys_*` and `tunnelUserPassword` are both configured.\n- To retrieve the tunnel user ID/password pair, open the secure tunnelling interface in ETS (or inspect the `.knxkeys` entry). Default ETS IDs are typically small integers (e.g. `2`, `3`, …) but may differ per installation.\n\n### 2) Decode datapoints (boolean 1.001) from decrypted payloads\n\n```ts\nimport KNXClient, { SecureConfig } from 'knxultimate'\nimport { dptlib } from 'knxultimate'\n\nconst secureCfg: SecureConfig = {\n  // tunnelInterfaceIndividualAddress: '1.1.254',   // Optional (auto‑select if omitted)\n  knxkeys_file_path: process.env.KNX_KEYS_PATH || '/path/to/Project.knxkeys',\n  knxkeys_password: process.env.KNX_KEYS_PASSWORD || 'your-ets-password',\n}\n\nconst client = new KNXClient({\n  hostProtocol: 'TunnelTCP',\n  ipAddr: '192.168.1.4',\n  ipPort: 3671,\n  isSecureKNXEnabled: true,\n  secureTunnelConfig: secureCfg,\n  loglevel: 'info',\n})\n\nclient.on('indication', (packet) =\u003e {\n  const cemi = packet?.cEMIMessage\n  if (!cemi?.npdu) return\n  const dst = cemi.dstAddress?.toString?.()\n  const raw: Buffer | undefined = cemi.npdu?.dataValue\n  if (!dst || !raw) return\n\n  // Example: decode boolean status for GA 1/1/2 as DPT 1.001\n  if (dst === '1/1/2') {\n    const cfg = dptlib.resolve('1.001')\n    const value = dptlib.fromBuffer(raw, cfg)\n    console.log(`dst=${dst} -\u003e`, value)\n  }\n})\n\nclient.Connect()\n```\n\n### 3) Secure routing (multicast) listener\n\nFor routers supporting KNX Secure routing (multicast 224.0.23.12). The ETS keyring must include the Backbone key; the client will automatically use it to decrypt SecureWrapper frames and present decrypted cEMI payloads.\n\n```ts\nimport KNXClient, { SecureConfig } from 'knxultimate'\n\nconst secureCfg: SecureConfig = {\n  knxkeys_file_path: process.env.KNX_KEYS_PATH || '/path/to/Project.knxkeys',\n  knxkeys_password: process.env.KNX_KEYS_PASSWORD || 'your-ets-password',\n}\n\nconst client = new KNXClient({\n  hostProtocol: 'Multicast',\n  ipAddr: '224.0.23.12',\n  ipPort: 3671,\n  physAddr: '1.1.250',   // your device IA used as source on bus\n  isSecureKNXEnabled: true,\n  secureTunnelConfig: secureCfg,\n  loglevel: 'info',\n})\n\nclient.on('connected', () =\u003e console.log('✓ Secure multicast ready'))\nclient.on('error', (e) =\u003e console.error('Error:', e.message))\nclient.on('indication', (packet) =\u003e {\n  const cemi = packet?.cEMIMessage\n  if (!cemi?.npdu) return\n  const dst = cemi.dstAddress?.toString?.()\n  const raw: Buffer | undefined = cemi.npdu?.dataValue\n  console.log('routing ind', { dst, raw: raw?.toString('hex') })\n})\n\nclient.Connect()\n```\n\n### 4) Send a READ and get a decrypted status\n\n```ts\nimport KNXClient, { SecureConfig } from 'knxultimate'\nimport { dptlib } from 'knxultimate'\n\nconst secureCfg: SecureConfig = {\n  tunnelInterfaceIndividualAddress: '1.1.254',\n  knxkeys_file_path: process.env.KNX_KEYS_PATH || '/path/to/Project.knxkeys',\n  knxkeys_password: process.env.KNX_KEYS_PASSWORD || 'your-ets-password',\n}\n\nconst client = new KNXClient({\n  hostProtocol: 'TunnelTCP',\n  ipAddr: '192.168.1.4',\n  ipPort: 3671,\n  isSecureKNXEnabled: true,\n  secureTunnelConfig: secureCfg,\n})\n\nfunction waitForStatus(ga: string, timeoutMs = 5000): Promise\u003cnumber\u003e {\n  return new Promise((resolve, reject) =\u003e {\n    const t = setTimeout(() =\u003e {\n      client.off('indication', onInd)\n      reject(new Error('Timeout waiting for status'))\n    }, timeoutMs)\n    const onInd = (packet: any) =\u003e {\n      const cemi = packet?.cEMIMessage\n      if (!cemi || cemi.dstAddress?.toString?.() !== ga) return\n      const npdu = cemi.npdu\n      const isResp = npdu?.isGroupResponse\n      const isWrite = npdu?.isGroupWrite\n      if (!(isResp || isWrite)) return\n      const raw: Buffer = npdu?.dataValue ?? Buffer.alloc(1, 0)\n      const bit = (raw.readUInt8(0) ?? 0) \u0026 0x01\n      clearTimeout(t)\n      client.off('indication', onInd)\n      resolve(bit)\n    }\n    client.on('indication', onInd)\n  })\n}\n\nasync function main() {\n  client.Connect()\n  await new Promise\u003cvoid\u003e((res) =\u003e client.once('connected', () =\u003e res()))\n  // Example: query a status GA and decode as boolean 1.001\n  const statusGA = '1/1/2'\n  client.read(statusGA)\n  const val = await waitForStatus(statusGA, 5000)\n  console.log(`Status on ${statusGA}:`, val ? 'ON' : 'OFF')\n}\n\nmain().catch(console.error)\n```\n\nTips\n- For tunnelling (TCP), the source IA is assigned by the gateway. For routing (multicast), set `physAddr` in options.\n- If you see decrypted payloads as null, verify that the GA has a Data Secure key in your `.knxkeys` and that the ETS keyring and password are correct.\n| message                        | Log message content                                           |\n| stack                          | Error stack trace (only present for errors)                   |\n\n### Log Levels\n\n| Level                          | Description                                                   |\n| ------------------------------ | ------------------------------------------------------------- |\n| disable                        | No logging                                                    |\n| error                          | Only logs errors                                             |\n| warn                          | Logs errors and warnings                                      |\n| info                          | Logs normal operations                                        |\n| debug                         | Logs detailed information                                     |\n| trace                         | Most verbose logging level                                    |\n\nFor a complete example of logging usage, see [logging.ts](./examples/logging.ts) in the examples folder.\n\n## DECONDING THE TELEGRAMS FROM BUS\n\nDecoding is very simple.\n\nJust require the dptlib and use it to decode the RAW telegram\n\n```javascript\nimport { dptlib } from \"knxultimate\";\nlet dpt = dptlib.resolve(\"1.001\");\nlet jsValue = dptlib.fromBuffer(RAW VALUE (SEE SAMPLES), dpt); // THIS IS THE DECODED VALUE\n```\n\n## EXAMPLES\n\nAll examples live in the [examples](./examples/) folder. You can run them directly with TypeScript via esbuild-register (no build step needed).\n\n- Generic command: `node -r esbuild-register -e \"require('./examples/\u003cfile\u003e.ts')\"`\n- For secure samples, npm scripts are available:\n  - `npm run example:secure:tunnel` (secure tunnelling TCP)\n  - `npm run example:secure:multicast` (secure routing multicast)\n\n### KNX/IP Tunnelling Server (UDP)\n\nBesides the `KNXClient`, this package also includes a small KNXnet/IP **tunnelling server** implementation, useful to accept connections from third-party KNX/IP tunnelling clients and bridge them via Node-RED (or your own glue code).\n\n- API: `KNXIPTunnelServer` (exported from the main entrypoint).\n- Output: emits `rawTelegram` events formatted like the Node-RED `knxUltimateMultiRouting` RAW messages (`payload.knx.*`), so you can reuse existing Filter logic.\n- Example: `examples/bridgeTunnelToNodeRedMsg.ts` (prints JSON to stdout).\n\nExamples overview:\n\n- **Recommended starting point → [template](./examples/template.ts):** well-commented skeleton showing how to configure plain vs secure connections, wire up core events, and encode/decode datapoint payloads. Use this file as a base for new scripts.\n\n- [sample](./examples/sample.ts): Full walkthrough — connect, read/write, decode values. Warning: sends telegrams to your KNX BUS.\n- [simpleSample](./examples/simpleSample.ts): Minimal connect + single write. Warning: sends telegrams.\n- [test-toggle](./examples/test-toggle.ts): Interactive ON/OFF toggle from CLI. Warning: sends telegrams.\n- [disconnection](./examples/disconnection.ts): Demonstrates clean disconnects and error handling.\n- [logging](./examples/logging.ts): Shows how to attach to the log stream and change log levels.\n- [monitorBusMinimal](./examples/monitorBusMinimal.ts): Minimal listener that connects and prints incoming telegrams. Warning: connects to the bus but does not send telegrams.\n- [showDatapoints](./examples/showDatapoints.ts): Lists supported datapoints and shows how payloads are built. Safe: does not send to the bus.\n- [datapointBasics](./examples/datapointBasics.ts): Demonstrates encoding and decoding a few datapoint values locally. Safe.\n- [discovery](./examples/discovery.ts): Discovers KNX/IP interfaces/routers (SEARCH_REQUEST). Safe.\n- [discoverInterfacesSimple](./examples/discoverInterfacesSimple.ts): Uses `discoverInterfaces()` to print a concise summary of each gateway. Safe.\n- Run: `node -r esbuild-register -e \"require('./examples/discoverInterfacesSimple.ts')\" [iface] [timeoutMs]`\n- [gatewaydescription](./examples/gatewaydescription.ts): Requests and prints extended gateway information. Safe.\n- [samplePlainTunnelUPD](./examples/samplePlainTunnelUPD.ts): Plain KNX/IP tunnelling over UDP (`hostProtocol: 'TunnelUDP'`). ON/OFF + status read via a KNX interface.\n  - Run: `node -r esbuild-register -e \"require('./examples/samplePlainTunnelUPD.ts')\"`\n- [samplePlainMulticast](./examples/samplePlainMulticast.ts): Plain KNX routing over multicast (`hostProtocol: 'Multicast'`). Uses RoutingIndication with cEMI L_DATA_REQ. ON/OFF + status read via a KNX router (no secure).\n  - Run: `node -r esbuild-register -e \"require('./examples/samplePlainMulticast.ts')\"`\n- [sampleSecureTunnelTCP](./examples/sampleSecureTunnelTCP.ts): KNX/IP Secure tunnelling over TCP (`hostProtocol: 'TunnelTCP'` + `isSecureKNXEnabled: true`). Performs session handshake + Secure Wrapper. Applies Data Secure for GA present in the ETS keyring. ON/OFF + status read.\n  - Requires: set `.knxkeys` path + password in the example file. Optionally omit `tunnelInterfaceIndividualAddress` to auto‑select a free tunnel from the keyring.\n  - Run: `npm run example:secure:tunnel` or `node -r esbuild-register -e \"require('./examples/sampleSecureTunnelTCP.ts')\"`\n- [sampleSecureTunnelTCPNoDataSecure](./examples/sampleSecureTunnelTCPNoDataSecure.ts): KNX/IP Secure tunnelling over TCP using only the manual tunnel password/ID (no keyring, Data Secure disabled). Demonstrates secure channel establishment when group keys are unavailable.\n  - Configure: set `tunnelInterfaceIndividualAddress`, `tunnelUserPassword`, and `tunnelUserId` in the file.\n  - Run: `node -r esbuild-register -e \"require('./examples/sampleSecureTunnelTCPNoDataSecure.ts')\"`\n- [sampleSecureMulticast](./examples/sampleSecureMulticast.ts): KNX/IP Secure routing over multicast (`hostProtocol: 'Multicast'` + `isSecureKNXEnabled: true`). Synchronizes timer via 0x0955, wraps frames in Secure Wrapper, and applies Data Secure per GA. ON/OFF + status read.\n  - Requires: set `.knxkeys` path + password in the example file.\n  - Run: `npm run example:secure:multicast` or `node -r esbuild-register -e \"require('./examples/sampleSecureMulticast.ts')\"`\n- [dumpKeyringCredentials](./examples/dumpKeyringCredentials.ts): Loads a `.knxkeys` file, decrypts all stored tunnel passwords, authentication codes, device credentials, group keys, and backbone keys, and prints them to the console. Safe.\n  - Run: `node -r esbuild-register -e \"require('./examples/dumpKeyringCredentials.ts')\" [path/to/keyring.knxkeys] [ets-password]`\n- [bridgeTunnelToNodeRedMsg](./examples/bridgeTunnelToNodeRedMsg.ts): Starts a KNX/IP tunnelling (UDP) server and prints **Node-RED MultiRouting RAW** messages to stdout (ready to be fed into the existing Filter/MultiRouting nodes).\n  - Run: `npm run example:bridge:noderedmsg` (then point a tunnelling client to this host:3671)\n\n### Discovery details\n\n- Functions: `KNXClient.discover()`, `KNXClient.discoverDetailed()`, `KNXClient.discoverInterfaces()`.\n- Default port: if a KNX interface does not advertise a port in the `SEARCH_RESPONSE` HPAI (missing or zero), discovery uses `3671` as the port.\n- Each helper now fires both multicast and unicast search bursts concurrently on every selected NIC so interfaces that only answer one transport are still found.\n- Return formats:\n- `discover()` → strings formatted as `ip:port:name:ia:Security:Transport`; highlights whether the result is plain/secure and which transport to use.\n  - Example: `192.168.1.4:3671:MyGW:1.1.1:Secure KNX:TCP`, `224.0.23.12:3671:MyRouter:1.1.0:Plain KNX:Multicast`.\n- `discoverDetailed()` → strings formatted as `ip:port:name:ia:service1,service2:type`; focuses on human-readable service families (`routing`, `tunnelling`, etc.) and whether the entry corresponds to tunnelling or routing.\n- `discoverInterfaces()` → array of objects `{ ip, port, name, ia, services, type, transport }`, giving parsed fields and an inferred transport, with `services` exposed as an array of service names.\n\nExample usage\n```ts\nimport KNXClient from 'knxultimate'\n\n// Simple list with security + transport\nconst list = await KNXClient.discover(5000)\nfor (const entry of list) {\n  const [ip, port, name, ia, security, transport] = entry.split(':')\n  console.log({ ip, port, name, ia, security, transport })\n}\n\n// Detailed strings\nconst detailed = await KNXClient.discoverDetailed(5000)\n// ip:port:name:ia:service1,service2:type\n\n// Structured objects\nconst objects = await KNXClient.discoverInterfaces(5000)\n// [{ ip, port, name, ia, services, type, transport }, ...]\n```\n\n### Source Individual Address (IA): UDP vs TCP\n\n- TunnelUDP: uses `physAddr` as the source IA on the bus.\n- TunnelTCP (secure): after a successful connect, uses the tunnel-assigned IA as the cEMI source on the bus; the Data Secure authentication, however, uses the interface IA from the ETS keyring (not the dynamic tunnel IA).\n- Tips for UDP tunnelling:\n  - If your interface times out on L_DATA_REQ ACK, try `suppress_ack_ldatareq: true`.\n  - With multiple NICs, set `localIPAddress` (or `interface`) to bind the correct local interface.\n\n### KNX IP Secure (tunnelling \u0026 routing) and Data Secure\n\n`KNXClient` supports KNX/IP Secure and Data Secure.\n\n- Requirements: KNX Secure router/interface and ETS keyring (`.knxkeys`). For `TunnelTCP`, the interface IA is optional — if omitted, the client auto‑selects a usable tunnel from the keyring.\n- Data Secure: Group Addresses present in the keyring are encrypted end‑to‑end; GA not present remain plain.\n- Modes:\n  - `TunnelTCP` + `isSecureKNXEnabled: true` → secure session (Secure Wrapper) + Data Secure per GA.\n  - `Multicast` + `isSecureKNXEnabled: true` → secure routing (Secure Wrapper over multicast with timer synchronization via 0x0955) + Data Secure per GA.\n\nRouting (Multicast) specifics\n- Outgoing frames are injected as `L_DATA_IND` when using routing (both plain and secure). This mirrors ETS and xKNX behavior and ensures devices react correctly to injected telegrams. Do not use `L_DATA_REQ` for routing injection.\n- Secure routing needs a synchronized timer. By default the client waits until the timer is authenticated before sending. Additionally, on secure multicast startup the client proactively sends a `TimerNotify (0x0955)` once, so the timer can authenticate immediately even if the router doesn’t broadcast it right away. Plain multicast is unaffected.\n- Option: `secureRoutingWaitForTimer` (default `true`) controls gating of outgoing frames until the timer is authenticated.\n\nAuthorized senders (Data Secure, secure routing)\n- When sending to a Data Secure Group Address over routing, KNX routers enforce an “authorized senders” list per GA. If your current `physAddr` is not authorized for that GA, the router will drop the telegram.\n- The client automatically avoids this problem by selecting an allowed sender IA for each secure GA based on the ETS keyring. If the configured `physAddr` is not in the GA’s Senders list, the library overrides the source IA with one that is authorized for that GA (taken from the keyring’s Senders for that GA) before building the Secure APDU.\n- Prerequisites: your `.knxkeys` (ETS Project Keyring) must include the target GA and its Senders list. If no Senders are present for that GA in the keyring, the client keeps `physAddr` and the router may still drop the frame as unauthorized.\n- This behavior is automatic whenever `hostProtocol: 'Multicast'` and `isSecureKNXEnabled: true` and the GA is protected by a Data Secure key in the keyring. No additional option is required.\n\nMixed secure/plain on one instance\n- A single `KNXClient` instance can handle Data Secure and plain Group Addresses at the same time. Data Secure is applied per‑GA: if a GA has a key in the ETS keyring, the APDU is encrypted; if not, the APDU stays plain.\n- Secure routing (multicast): when `isSecureKNXEnabled: true`, all routing frames are transported inside the KNX/IP Secure Wrapper (`0x0950`). “Plain” APDUs still travel inside that wrapper. This allows mixing secure and plain GA on the same instance. If you also need to emit non‑wrapped plain routing frames simultaneously, run a second `KNXClient` with `isSecureKNXEnabled: false`.\n- Secure tunnelling (TCP): the tunnel is always wrapped (Secure Wrapper). APDU encryption (Data Secure) remains per‑GA; GA without keys remain plain.\n- Receive path: with secure enabled, the client decrypts `0x0950` frames and forwards the inner plain cEMI; it also accepts non‑wrapped routing frames if present on the bus. The `indication` event always exposes a plain (decrypted) cEMI when keys are available.\n\nTroubleshooting (routing)\n- If an actuator doesn’t react to writes sent over routing, verify that your app injects `L_DATA_IND` (not `L_DATA_REQ`). From version 5.0.0‑beta the library automatically uses `L_DATA_IND` for multicast writes/reads/responses.\n- For secure routing, ensure your ETS keyring contains a Backbone key and that the target Group Addresses are present with keys (Data Secure). You can list them with the example `examples/listSecureGroups.ts`.\n\nBehavior when fields are unset\n- secureTunnelConfig.tunnelInterfaceIndividualAddress (TunnelTCP): if omitted/empty, the client auto‑selects a tunnel from the ETS keyring and retries interfaces until authentication and connect succeed. The chosen IA is exposed runtime in `client._options.secureTunnelConfig.tunnelInterfaceIndividualAddress` after connect.\n- physAddr:\n  - Multicast: must be provided; it’s your node’s source IA on the bus.\n  - TunnelUDP: optional; used as cEMI source if set.\n  - TunnelTCP: optional and ignored for the bus source (gateway provides the tunnel IA); Data Secure signs as the interface IA from the keyring.\n\nSecure TCP auto‑selection details\n- IA selection: the client runs discovery for `ipAddr:ipPort`, reads the gateway “Host” IA, and selects keyring interfaces whose `Host` matches it. Candidates are sorted descending (e.g. …255, …254, …253). If no match by `Host`, it falls back to all keyring interfaces of type `Tunneling`.\n- Single‑NIC discovery: when `options.interface` is empty/undefined, discovery is executed only on the local NIC that shares the same subnet of `ipAddr` (no scan across all OS interfaces).\n- Timeouts: detailed discovery runs ~3s on the chosen NIC; if nothing is found, a lightweight simple discovery runs ~5s on the same NIC and is adapted to the detailed format.\n- Logging: look for lines starting with “Secure TCP:” to follow selection steps (discovered Host IA, candidates, chosen IA).\n- Override: set `secureTunnelConfig.tunnelInterfaceIndividualAddress` and/or `interface` explicitly to skip the auto‑selection.\n\n\u003cdiv style=\"background:#e9f7e9;border:1px solid #c8e6c8;border-radius:10px;padding:14px 16px;margin:16px 0;\"\u003e\n\n\n### Using KNX Ultimate with kBerry on Raspberry Pi 3 (UART / FT1.2)\n\nThis guide explains how to connect a **kBerry** KNX interface directly\nto a **Raspberry Pi 3** and use it with **KNX Ultimate** over the\n**hardware UART** (`ttyAMA0`) using the **FT1.2 (TPUART)** protocol.\n\n\u003e This procedure is tested with Raspberry Pi OS Bookworm on a  \n\u003e Raspberry Pi 3 and has been written on November, 25, 2025.\n\n## 1. Prerequisites\n\n- Raspberry Pi 3 (Model B or B+)\n- Raspberry Pi OS (Bookworm recommended)\n- kBerry KNX interface mounted on the GPIO header\n- Node-RED with KNX Ultimate installed\n- Basic terminal access (SSH or local console)\n\n## 2. Wiring / Hardware Overview\n\nThe kBerry uses the Raspberry Pi's primary UART:\n\n- **TX / RX**: GPIO14 (TXD) and GPIO15 (RXD)\n- **GND**: A common ground between Raspberry Pi and kBerry\n- **Power**: Provided via the GPIO header\n\nMake sure the kBerry is properly seated on the Raspberry Pi GPIO header\nand that no other HAT is conflicting with those pins.\n\n## 3. Disable Bluetooth and Enable the Hardware UART\n\n### 3.1 Edit the correct config file (Bookworm)\n\n```bash\nsudo nano /boot/firmware/config.txt\n```\n\nAdd:\n\n```ini\nenable_uart=1\ndtoverlay=pi3-disable-bt\n```\n\n### 3.2 Disable ModemManager\n\n```bash\nsudo systemctl disable --now ModemManager\n```\n\n### 3.3 Disable Bluetooth service\n\n```bash\nsudo systemctl disable --now bluetooth.service\n```\n\n## 4. Disable Serial Login Console / Enable Hardware UART\n\n```bash\nsudo raspi-config\n```\n\n- Disable login shell on serial → **No**\n- Enable serial hardware → **Yes**\n\nReboot.\n\n## 5. Verify UART\n\n```bash\nls -l /dev/serial0\nls -l /dev/ttyAMA0\ndmesg | grep tty\n```\n\nExpected:\n\n    /dev/serial0 -\u003e ttyAMA0\n    /dev/ttyAMA0 exists\n\n## 6. Add Node-RED User to dialout\n\n```bash\nsudo usermod -aG dialout nodered\nsudo reboot\n```\n\n## 7. Configure KNX Ultimate\n\n- **Interface type**: Serial FT1.2 / TPUART\n- **Serial port**: `/dev/ttyAMA0`\n- **Baud rate**: 19200\n- **Data bits**: 8\n- **Parity**: Even\n- **Stop bits**: 1\n\n## 9. Troubleshooting\n\n### No `/dev/ttyAMA0`\n\n- Check `/boot/firmware/config.txt` entries\n- Reboot\n- Re-check `dmesg`\n\n### `/dev/serial0` → `ttyS0`\n\n- `dtoverlay=pi3-disable-bt` not applied\n- Re-check config file path\n- Reboot\n\n### Serial cannot be opened\n\n- Ensure user is in `dialout`\n- Check that no other program uses `/dev/ttyAMA0`\n\n---\n\nDone.\n\u003c/div\u003e\n\n\n## HOW TO COLLABORATE\n\nIf you want to help us in this project, you're wellcome!  \n\nPlease refer to the development page.\n\n- [Development's page](https://github.com/Supergiovane/knxultimate/blob/master/DEVELOPMENT.md)\n\n\u003cbr/\u003e\n\n## SUGGESTION\n\n\u003e\n\n\u003e Why not to try Node-Red \u003chttps://nodered.org\u003e and the awesome KNX-Ultimate node \u003chttps://flows.nodered.org/node/node-red-contrib-knx-ultimate\u003e ?\n\n\u003cbr/\u003e\n\n\u003cimg src='https://raw.githubusercontent.com/Supergiovane/knxultimate/master/img/nodered.png' width='90%'\u003e\n\n\u003cbr/\u003e\n\u003cbr/\u003e\n\n![Logo](https://raw.githubusercontent.com/Supergiovane/node-red-contrib-knx-ultimate/master/img/wiki/flags/madeinitaly.png)\n\n[license-image]: https://img.shields.io/badge/license-MIT-blue.svg\n\n[license-url]: https://github.com/Supergiovane/knxultimate/master/LICENSE\n\n[npm-url]: https://npmjs.org/package/knxultimate\n\n[npm-version-image]: https://img.shields.io/npm/v/knxultimate.svg\n\n[npm-downloads-month-image]: https://img.shields.io/npm/dm/knxultimate.svg\n\n[npm-downloads-total-image]: https://img.shields.io/npm/dt/knxultimate.svg\n\n[youtube-image]: https://img.shields.io/badge/Visit%20me-Youtube-red\n\n[youtube-url]: https://www.youtube.com/channel/UCA9RsLps1IthT7fDSeUbRZw/playlists\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsupergiovane%2Fknxultimate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsupergiovane%2Fknxultimate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsupergiovane%2Fknxultimate/lists"}