Introduction

Scripts are programs that are created via the integrated web interface. The HomeKit bridge for KNX runs the scripts automatically as soon as there is access to the KNX network.

Scripts contain statements that are executed one after the other. These instructions (program code) must correspond to a certain notation (syntax).

There are also pre-built packages available for a script. A package contains frequently used functions and calculations. For example, the hkknx package is used to receive and send telegrams from the KNX bus. You can find a list of all available packages below.

Syntax

The scripting language is based on the Go programming language.

Hello Word

The following program code calls the function println to write the text “Hello World” to the log.

1println("Hello World")

Values

1println("Home" + "Kit") // "HomeKit"
2
3println("1+1=", 1+1) // "1+1=2"
4println("7/3=", 7/3) // "7/3= 2.3333333333333335"
5
6println(true && false) // false
7println(true || false) // true
8println(!true) // false

Variables

var declares one or more variables

1// Variables
2var a = "string"
3println(a) // "string"
4
5var b, c = 1, 2
6println(b, c) // "1 2"
7
8var d = true
9println(d) // "true"

The short form also works without var.

1e = 4
2println(e) // "4"

Loops

 1var i = 1
 2for i <= 3 {
 3println(i) // "1", "2", "3"
 4i = i + 1
 5}
 6
 7for {
 8     println("loop") // "loop"
 9     break // stop the loop
10}

If/Else

 1if 7%2 == 0 {
 2     println("7 is even")
 3} else {
 4     println("7 is uneven") // 7 is uneven
 5}
 6if 8%4 == 0 {
 7     println("8 is dividable by 4") // 8 is dividable by 4
 8}
 9
10var num = 9
11if num < 0 {
12     println(num, "is negative")
13} else if num < 10 {
14     println(num, "has 1 digit") // 9 has 1 digit
15} else {
16println(num, "has multiple digits")
17}

Switch

 1var i = 2
 2printf("Write %d as ", i)
 3switch i {
 4case 1:
 5     println("one")
 6case 2:
 7     println("two")
 8case 3:
 9     println("three")
10}

Since the scripting language is very similar to the Go programming language, you can also learn the scripting language by reading Go code examples. Go by Example has a lot of good examples. And on the Go-Playground website you can test Go directly in the browser.

Create Script

The following example shows how to create and run a script in the HomeKit bridge for KNX.

The logic shown in this script is actually quite simple. The script synchronizes the values from the group address 0/0/1 with the group address 0/0/2. This means that if the value 1 (or 0) is sent to the group address 0/0/1 via the KNX bus, then the script also sends the value to the group address 0/0/2.

Flowchart

The following flowchart shows the logic again graphically.

After the script starts, a for loop is created. The loop waits until values from the group address 0/0/1 are received. The received value is then sent to the group address 0/0/2. After sending, it jumps back to the beginning of the for loop.

As you can see, there is no end to the script - the statements within the for loop are executed over and over again. This concept is very important especially for programming logic that is executed over and over again.

Programming

To create a new script, go to the Script tab in the web interface and create a new script. A new page opens. The name of the script can now be entered in the input field provided - e.g. First script.

Below the input field for the name there is an area to enter the script code. There you can enter the following script code.

 1// Import the hkknx package.
 2var hkknx = import("hkknx")
 3
 4// Define the variable *ch*. This variable returns
 5// boolean values sent to the group address 0/0/1 with
 6// sent in a group write telegram.
 7ch = hkknx.GroupWriteBoolNotify("0/0/1")
 8
 9for {
10     // Wait until *ch* returns a value. The value will
11     // cached in the *value* variable.
12     value = <-ch
13    
14     // Output the received value via the log.
15     println(value)
16    
17     // Send the received value with a
18     // Group write telegram to 0/0/2.
19     hkknx.GroupWrite(value, "0/0/2")
20}

Now save the script.

Testing

Once the script has been saved, it is initially inactive and will not be executed yet. To test the script, click Run. The script is now started and runs until it is ends. You can end the script by clicking Exit.

Now wait until a value is received from the group address 0/0/1. When this happens, the println(value) statement prints either true or false to the log. So you have successfully received and cached a value.

Activate

In order for the script to be executed automatically when the HomeKit bridge for KNX starts, it must be activated. To do this, click on the Scripts tab to see all scripts. Then select the checkbox in the Active column for your script. As soon as the script is running, the activity display will be visible in the Status column.