knxultimate

Control your KNX intallation via Node.js!

This is the official engine of Node-Red node KNX-Ultimate (https://flows.nodered.org/node/node-red-contrib-knx-ultimate) I had many users asking for a node.js release of that engine, so here is it. The node will be KNX Secure compatible. I'm already working on that.

CHANGELOG

• Changelog
• Developer's changelog

Properties to be passed to the connection(see the knxUltimateClientProperties variable below)

Property	Description
ipAddr (string)	The IP of your KNX router/interface (for Routers, use "224.0.23.12")
ipPort (string)	The port, default is "3671"
physAddr (string)	The physical address to be identified in the KNX bus
suppress_ack_ldatareq (bool)	Avoid sending/receive the ACK telegram. Leave false. If you encounter issues with old interface, set it to true
loglevel (string)	The log level. "info", "error", "debug" or "trace"
localEchoInTunneling (bool)	Leave true forever. This is used only in Node-Red KNX-Ultimate node
hostProtocol (string)	"Multicast" if you're connecting to a KNX Router. "TunnelUDP" for KNX Interfaces, or "TunnelTCP" for secure KNX Interfaces (not yet implemented)
isSecureKNXEnabled (bool)	True: Enables the secure connection. Leave false until KNX-Secure has been released.
jKNXSecureKeyring (string)	ETS Keyring JSON file content (leave blank until KNX-Secure has been released)
localIPAddress (string)	The local IP address to be used to connect to the KNX/IP Bus. Leave blank, will be automatically filled by KNXUltimate
interface (string)	Specifies the local eth interface to be used to connect to the KNX Bus.

Supported Datapoints

For each Datapoint, there is a sample on how to format the payload (telegram) to be passed.
For example, pass a true for datapoint "1.001", or { red: 125, green: 0, blue: 0 } for datapoint "232.600".
It support a massive number of Datapoints. Please run the sample.js file to view all datapoints in the console window.
Be 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.
You should see something like this in the console window (the msg.payload is what you need to pass as payload):

CONTROL THE CLIENT

Method	Description
.Connect()	Connects to the KNX Gateway
.Disconnect()	Gracefully disconnects from the KNX Gateway
.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")
.writeRaw (GA, payload, datapoint)	Sends a WRITE telegram to the BUS. GA is the group address (for example "0/0/1"), payload is the buffer you want to send, datapoint is a string representing the datapoint (for example "5.001")
.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")
.read (GA)	Sends a READ telegram to the BUS. GA is the group address (for example "0/0/1").

Properties	Description
.isConnected()	Returns true if you the client is connected to the KNX Gateway Router/Interface, false if not connected.
.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.
.channelID	The actual Channel ID. Only defined after a successfull connection

EVENTS

Please see the sample.js file. This sample contains all events triggered by KNXUltimate.

DECONDING THE TELEGRAMS FROM BUS

Decoding is very simple. Just require the dptlib and use it to decode the RAW telegram

import { dptlib } from "knxultimate";
let dpt = dptlib.resolve("1.001");
let jsValue = dptlib.fromBuffer(RAW VALUE (SEE SAMPLES), dpt); // THIS IS THE DECODED VALUE

Examples

You can find all examples in the examples folder:

• sample - A full featured example that shows how to connect to the KNX bus and send/receive telegrams.
• simpleSample - A simple example that shows how to connect to the KNX bus and send a telegram.
• discovery - A simple example that shows how to discover KNX devices on the network.
• test-toggle - An interactive example that shows how to toggle a switch on/off.
• sampleSecure - A full featured example that shows how to connect to the KNX bus and send/receive telegrams in secure mode.

SUGGESTION

Why not to try Node-Red https://nodered.org and the awesome KNX-Ultimate node https://flows.nodered.org/node/node-red-contrib-knx-ultimate ?

Changelog

2.1.2 (2024-04-24)

Bug Fixes

• refactor method names and added js docs (#19) (432db89)
• wrong overload of discovery method (a41b65c)