changelog KNX Custom Commands

[K.Drozynski 131]

To extend the functionality of KNX integration, we added the ability to send custom commands to KNX network, and to register your own listener to handle reports from the devices. This allows you to control devices that may not be fully supported by the default KNX integration, or to implement specific behaviors that are unique to your setup. The easiest way to handle this is to do it with a QuickApp. Be aware that this functionality is at a testing stage. It may not be fully stable yet, and also the API may change in the future.

Sending Custom Commands

You can send custom commands to the KNX network by calling the sendCommand action on the KNX integration device (ID 9). This action takes three parameters:

• The group address to which you want to send the command (e.g. "0/2/0").
• DPT of the value you want to send (e.g. "5.001" for DPT_Scaling).
• The value you want to send. The encoding depends on the DPT you are using.

A few simple examples of how to send different DPTs:

-- DPT 1.001 (DPT_Switch): function QuickApp:turnOn()     hub.call(9, "sendCommand", "0/2/0", "\"1.001\"", true)     self:debug("binary switch turned on")     self:updateProperty("value", true) end   function QuickApp:turnOff()     hub.call(9, "sendCommand", "0/2/0", "\"1.001\"", false)     self:debug("binary switch turned off")     self:updateProperty("value", false) end

-- DPT 5.001 (DPT_Scaling): -- Representation of open/close mapping to percentage may differ based on the device you're integrating.   function QuickApp:open()     hub.call(9, "sendCommand", "0/2/0", "\"5.001\"", 0)     self:debug("roller shutter opened")     self:updateProperty("value", 99) end   function QuickApp:close()     hub.call(9, "sendCommand", "0/2/0", "\"5.001\"", 100)     self:debug("roller shutter closed")     self:updateProperty("value", 0) end

-- 232.600 (Colour_RGB)   function QuickApp:setPresetColor()     local r = 0     local g = 74     local b = 147           local payload = {r, g, b}     hub.call(9, "sendCommand", "2/0/16", "232.600", payload)           self:updateProperty("colorComponents", {red=r, green=g, blue=b})    end

Since we're using device actions to send KNX commands, you can send them in whatever way you want. You can use QuickApps, but you can also use scenes, or direct REST API calls (POST /api/devices/9/action/sendCommand).

Listener registration

By registering a listener, you can receive updates from the group address and handle them in your QuickApp. This is useful for monitoring device states or reacting to specific events. For now there is no way to register to a specific group address, so you will receive all updates from the KNX network. You can then filter them in your code to react only to the relevant ones.

A callback can be registered by calling the registerListener action on the KNX integration device (ID 9). This action takes one argument:

• The callback URL (an action in your QuickApp) that will be called when there is an update from the KNX network. The URL should be in the format /api/devices/<quick app id>/action/{callback name} e.g. /api/devices/123/action/myCallback.

The provided callback will be called with the group address and the value of the update whenever there is an update from the KNX network. Here is an example of how to handle this in a QuickApp:

function QuickApp:onInit()     -- Register a listener for KNX updates.     -- ID 9 is a device that represents the KNX integration. Don't change it.     -- "registerListener" is the action to register a listener. Don't change it.     -- 3rd parameter is the callback URL (an action), that will be called when there is an update from the KNX network. You can choose any action you want, just make sure to handle it in your QuickApp. In this example we will call "myCallback" action.     local callbackURL= "/api/devices/" .. tostring(self.id) .. "/action/myCallback"     self:debug("Register KNX callback:",  callbackURL)     hub.call(9, "registerListener", callbackURL)       self:debug("KNX QA started") end   -- Callback function to handle KNX updates. The address and value parameters will contain the group address and the value of the update. function QuickApp:myCallback(address, value)     self:debug("address:", address, "value:", json.encode(value)) end

Debugging

You can change the log level of the KNX integration to "debug" or "trace" in order to see more information about the KNX communication itself and about the communication exchanged between the KNX integration and your QuickApp. To do so, just go to the KNX settings in the web interface, and change the system log level in the network communication section.