![\"KNX](\"img/logo-supervibe.png\"){kind=logo}
\n\n \n
\n ![\"KNX](\"img/readmemain.png\")
\n
\n![](\"https://raw.githubusercontent.com/Supergiovane/KNXUltimate/master/img/KNX_CERTI_MARK_RGB.jpg\")
\n![](\"https://raw.githubusercontent.com/Supergiovane/KNXUltimate/master/img/knxsecure.png\")
\nAuthorized KNX logo by KNX Association*\n
examples/showDatapoints.ts file to view all datapoints in the output console.
\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 <= 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 <= 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| .getCurrentItemHandledByTheQueue() | Returns the sequence number awaiting a tunnelling ACK, or `undefined` when none is pending. Retained for compatibility with Node-RED queue diagnostics; calling it does not change the queue or ACK state. |\n\n### writeRaw notes\n\n`writeRaw(GA, payloadBuffer, bitlength)` sends a GroupValue_Write with a raw APDU payload.\n\n- Use `bitlength <= 6` for \"6-bit\" payloads (the value is encoded into the low APCI bits, so `payloadBuffer` should be 1 byte and `<= 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 <= 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 available in the **datagram** variable. Please see the examples. |\n| ackReceived | Reports `(packet, success)` for a tunnelling request. `success` is `true` after a matching successful gateway ACK, or `false` after two retries without a successful ACK. On retry exhaustion, `TunnelUDP` closes the tunnel and emits `error` and `disconnected`; `autoReconnect` reconnects when enabled. |\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 `logStream` exported from default entrypoint. Example:\n```typescript\nimport { logStream } from 'knxultimate' \n\nlogStream.on('data', (log) => { \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| message | Log message content |\n| stack | Error stack trace (only present for errors) |\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', () => console.log('✓ Plain tunnelling connected'))\nclient.on('error', (e) => console.error('Error:', e.message))\nclient.on('disconnected', (reason) => console.log('Disconnected:', reason))\n\nclient.on('indication', (packet) => {\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) => {\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} ->`, 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', () => console.log('✓ Plain multicast ready'))\nclient.on('error', (e) => console.error('Error:', e.message))\nclient.on('indication', (packet) => {\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
\n\n