KNX Bus

Use the "hkknx" package to get access to the KNX bus.

The “hkknx” package is available for communication with the KNX bus. This package provides functions to send values to a group address, read them and respond to read requests.

You can find out how to use the “hkknx” package in the following examples. You can try these examples yourself by copying and pasting the code into a new script using the web interface. Then click Run to run the script.

Send Telegram

In the following example, 1 bit is sent to the group address 0/0/1 using the function GroupWrite.

1// Import the hkknx package.
2var hkknx = import("hkknx")
3
4// Write a bool value *true* to 0/0/1.
5// Behind the scenes the value is converted to the bit *1*.
6var err = hkknx.GroupWrite(true, "0/0/1")
7if err != nil {
8     println(err)
9}

With the GroupWrite function, data can be sent not only to one but also to several group addresses. For this purpose, the group addresses are separated by a comma. This means that bit 1 can be sent to the group addresses 0/0/1, 0/0/2 and 0/0/3.

1var hkknx = import("hkknx")
2
3// Write a bool value *true* to 0/0/1, 0/0/2, 0/0/3.
4var err = hkknx.GroupWrite(true, "0/0/1", "0/0/2", "0/0/3")
5if err != nil {
6     println(err)
7}

In the previous examples only one bit (i.e. 0 or 1) was sent. Integer and floating point numbers must be encoded into bytes before sending. The conversion of a value into bytes depends on the KNX data type. The hkknx package contains functions that can be used for conversion.

For example, to send the value 50% as data type 5.004 (DPST-5-4) to the KNX bus, the function DPT5004 is used.

1var hkknx = import("hkknx")
2
3// Send 50%
4hkknx.GroupWrite(hkknx.DPT5004(50), "0/0/2")

Since each data type has a different encoding, it is important to use the correct data type. Otherwise there may be inaccuracies and, as a result, unexpected errors. For example, with the data type 5.001 it is not possible to send the value 21%. However, with the data type 5.004 it does.

1var hkknx = import("hkknx")
2
3// DPT 5.001 has a resolution of 0.4%.
4// Therefore a value of 21% cannot be represented.
5println(hkknx.DPT5001(21)) // "20.8%"
6
7// DPT 5.004 has a resolution of 1%.
8println(hkknx.DPT5004(21)) // "21%"

If you are unclear, the official documentation of the KNX data types will help.

Read Group Address

The GroupRead function is used to read the value from a group address. This function returns the bytes received or an error if the reading was not successful.

1var hkknx = import("hkknx")
2
3// Read the value from 0/1/1.
4var buf, err = hkknx.GroupRead("0/1/1")
5if err != nil {
6     println(err)
7} else {
8     println(buf)
9}

Depending on the data type, the bytes received represent a different value. To do this, use the Parse...([]byte) functions from the hkknx package.

1var hkknx = import("hkknx")
2
3buf = []byte{0xFF}
4println(hkknx.ParseDPT5001(buf)) // 100
5println(hkknx.ParseDPT5003(buf)) // 360
6println(hkknx.ParseDPT5004(buf)) // 255

If a boolean value is read, then you can use the function GroupReadBool. This function directly converts the received bit into a boolean value.

1var hkknx = import("hkknx")
2
3// Read a bool value from 0/1/1.
4var val, err = hkknx.GroupReadBool("0/1/1")
5if err != nil {
6     println(err)
7} else {
8     println(val) // "true" or "false"
9}

Read Telegram

A script can also receive read telegrams and respond to them with a response telegram. The function GroupReadNotify is used for this. This function provides a channel, which delivers incoming read telegrams.

In the following example, a read telegram for the group address 0/1/1 is waited in a loop. Then the answer is 1 bit.

 1var hkknx = import("hkknx")
 2
 3// Declare a channel which delivers group read telegrams.
 4var ch = hkknx.GroupReadNotify("0/1/1")
 5
 6for {
 7     // Wait for read telegram to arrive.
 8     <-ch
 9     // Respond with the value *true*.
10     hkknx.GroupResponse(true, "0/1/1")
11}

In addition to communication with the KNX bus, the “hkknx” package provides additional functions. The documentation of all functions is here.