Control your KNX intallation via Node.js!

This is the official engine of Node-Red's node node-red-contrib-knx-ultimate

Many of you asked for a node.js release of that engine, so i decided to create this package.

If you enjoy my work developing this package, do today a kind thing for someone too. This will be the reward for my work.

CHANGELOG

• Changelog

Technology	Supported
KNX Tunnelling
KNX Routing
KNX Secure Tunnelling
KNX Secure Routing

CONNECTION SETUP

These are the properties to be passed to the connection as a JSON object {} (see the knxUltimateClientProperties variable in the exsamples)

Property	Description
ipAddr (string)	The IP of your KNX router/interface (for Routers, use "224.0.23.12")
hostProtocol (string)	"Multicast" if you're connecting to a KNX Router. "TunnelUDP" for KNX Interfaces, or "TunnelTCP" for secure KNX Interfaces (KNX Secure is not yet implemented)
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 'disable', 'error', 'warn', 'info', 'debug'
isSecureKNXEnabled (bool)	True: Enables the secure connection. Leave false until KNX-Secure has been released.
jKNXSecureKeyring (string)	Optional. ETS Keyring JSON file content. Leave blank until KNX-Secure has been released.
localIPAddress (string)	Optional. The local IP address to be used to connect to the KNX/IP Bus. Leave blank, will be automatically filled by KNXUltimate
interface (string)	Optional. Specifies the local eth interface to be used to connect to the KNX Bus.
KNXQueueSendIntervalMilliseconds	Optional. The KNX standard has a maximum transmit rate to the BUS, of about 1 telegram each 25ms (to stay safe). In case you've a lot of traffic on the BUS, you can increase this value, expressed in milliseconds. Be careful, because if you set it too high, the KNX engine could send a telegram with flag 'repeat', because the ACK from the device is coming too late.

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 examples/showDatapoints.ts file to view all datapoints in the output console.

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):

METHODS/PROPERTIES OF KNXULTIMATE

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").
. 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
.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 .

Property	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

List of events raised by KNXultimate, in proper order. For the signatures, please see the examples folder.

Event	Description
connecting	KNXUltimate is connecting to the KNX/IP Gateway. Please wait for the connected event to start sending KNX telegrams.
connected	KNXUltimate has successfully connected with the KNX/IP Gateway.
indication	KNXUltimate has received a KNX telegram, that's avaiable in te the datagram variable. Please see the examples.
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.
disconnected	The KNX connection has been disconnected.
close	The main KNXUltimate socket has been closed.
error	KNXUltimate has raised an error. The error description is provided as well.
descriptionResponse	Gather the getGatewayDescription responses. There is an example in the examples folder named gatewaydescription.ts .

LOG STREAM

KNXUltimate logging is managed by Winston logger. In case you want to intercept library logs you can use our logStram exported from default entrypoint. Example:

1import { logStream } from 'knxultimate'  
2
3logStream.on('data', (log) => {  
4    // handle log  
5    if(log.level === 'ERROR)  
6        console.log(`${log.timestamp} ${log.message}`)  
7}) 

Field	Description
timestamp	ISO formatted date (YYYY-MM-DD HH:mm:ss.SSS)
level	Log level in uppercase (ERROR, WARN, INFO, DEBUG)
label	Module name in uppercase (specified when creating logger)
message	Log message content
stack	Error stack trace (only present for errors)

Log Levels

Level	Description
disable	No logging
error	Only logs errors
warn	Logs errors and warnings
info	Logs normal operations
debug	Logs detailed information
trace	Most verbose logging level

For a complete example of logging usage, see logging.ts in the examples folder.

DECONDING THE TELEGRAMS FROM BUS

Decoding is very simple.

Just require the dptlib and use it to decode the RAW telegram

1import { dptlib } from "knxultimate";
2let dpt = dptlib.resolve("1.001");
3let 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. WARNING this sends data to your KNX BUS!
• showDatapoints - List all supported Datapoints in the output console, as well as the help code on how the payload's value is constructed, for each datapoint type. This writes nothing to the KNX BUS, you can run it safely.
• simpleSample - A simple example that shows how to connect to the KNX bus and send a telegram. WARNING this sends data to your KNX BUS!
• 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. WARNING this sends data to your KNX BUS!
• logging - Shows how to use the logging system and capture log messages.
• gatewaydescription - Discover all gateways on your network and shows the details (name, mac address, etc...).

HOW TO COLLABORATE

If you want to help us in this project, you're wellcome!

Please refer to the development page.

• Development's page

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 ?