Controlling KNX from uOS
This guide explains how to pull data from KNX’s protocol so you can control it directly from uOS.
Please note: this guide assumes you have access and knowledge of ETS6, and your own KNX/Weinzierl gateway. In this guide we are using a BAOS 774 gateway, but you may have a different one, so refer to this site for more Weinzierl product knowledge.
What this guide will cover:
- How to control KNX devices in your home.
- How to add that API into uOS.
Important: you must have the gateway IP address first
You can get the IP address of your gateway by:
- Use a network scanner application like Fing on your mobile phone to scan your network.
- You can also get the IP address from the properties tab of the device in KNX’s ETS.
For the purposes of this guide we are going to pretend that your Weinzierl gateway is on IP address 192.168.1.15 and your uOS device (MHUB, MZMA or Zone Processor) is on 192.168.1.196. We will use this to illustrate all examples moving forward.
What a typical BAOS API command looks like
http://192.168.1.15/baos/SetDatapointValue?Datapoint=2&Format=DPT1&Length=1&Value=false
The above command will trigger our BAOS gateway to send a telegram to datapoint 2, which will switch off our light.
Understanding what the variables in the API above mean:
http://192.168.1.15
The command starts with http:// as it can be sent over a URL, followed by the IP address of your KNX/Weinzierl gateway.
/baos/
This is the device type of a Weinzierl device.
SetDatapointValue?Datapoint=2
Here we are setting this command to send to our KNX data point to two.
&Format=DPT1
This is the sub data point, and sets the rules of which values are allowed.
&Length=1&Value=false
This is the length of the data point type, and the value is boolean therefore setting it on or off.
Testing your APIs
We recommend that you test every API before you enter them into uOS. All IP based APIs all have different requirements when it comes to testing but the KNX API is great because it can be tested on your browser.
To test your API, open a web browser and enter the full API (including http://192.168.1.15) in the URL window and hit enter.
If the KNX device responds as you expected then your API is working and you can proceed adding it into uOS.
If it doesn’t work then try the following:
- Make sure the IP address is correct.
- Make sure that you do not have any typos.
- Ensure that your IDs are correct and that you’re observing the correct device.
- Make sure that the structure of the API matches our example no spaces, no special characters, data is in the correct case (often lowercase).
How to add your APIs into uControl
Need more help with the API? Get in touch.
All HDA staff are able to help with any API questions you might have including any advanced features. Get in touch for help or assistance.