BAOS SDK v2  1.0.1
An SDK providing access to IP-BAOS devices through BAOS binary protocol version 2.x
BAOS SDK v2

1. Introduction

The BAOS Binary SDK is a C++ client implementation of the Weinzierl BAOS Binary Protocol 2.x via TCP/IP.

It currently supports the following platforms:

  • Windows
  • Linux

1.1 What is BAOS?

It is an acronym for (B)us (A)ccess and (O)bject (S)erver.

The ObjectServer is a software component, which abstracts the connection to the KNX bus. It offers defined "objects" to the client software. These objects are the server properties (called “items”), KNX datapoints (also known as “communication objects” or as “group objects”) and KNX configuration parameters.

Furthermore there are multiple ways to access the BAOS devices and the object server within. This SDK focuses on the BAOS binary protocol. This proprietary protocol, developed by Weinzierl Engineering GmbH is encapsuled in different transport protocols like FT1.2 or a variation of the KNXnet/Ip protocol.

Three object types exist in the BAOS protocol.

1.1.1 Serveritems

Provide information about the BAOS device itself, like serial number.

1.1.2 Datapoint objects

Represent KNX group objects and optional a description string for them.

1.1.3 Parameter bytes

A block of generic bytes written during an ETS download, which then can be retrieved during runtime.

1.1.4 Why do we need it?

Creating a complete KNX device requires a deep understanding of the KNX standard, a certified KNX stack and also certification of the device itself and its database. Since the KNX standard is very versatile and supports a wide variety of scenarios, it also has a fairly steep learning curve. To facilitate the connection to KNX and to relieve this burden, the BAOS products were developed. Our company provides the ready to use and KNX certified BAOS devices and if required, customization of the ETS database.

A second point is the effort required to stay up to date. Since KNX is a de-centralized system, no central controller stores the current state of the installation. So to get the latest values a devices has to be present on the bus at all times and read along any group objects related communication. Though the up to 50 telegrams per second of KNX TP is not that much compared to the giga or mega bits of ethernet, it may pose a challange to ensure processing all those telegrams. The BAOS devices relieve you of this task. Only when the client needs the current value of a datapoint, it is necessary to load it from the BAOS device. No real time read along on the client side is required.

For details refer to our website https://weinzierl.de and there on any BAOS device (like the 774) look for the documents "The world of BAOS" and "Protocol description: KNX BAOS Binary".

1.2 Supported devices

Devices supporting the Weinzierl BAOS binary protocol version 2.x via TCP/IP:

  • 771 KNX IP BAOS
  • 772 KNX IP BAOS
  • 773 KNX IP BAOS
  • 774 KNX IP BAOS
  • 777 KNX IP BAOS
  • kTux

NOTE

For devices using other transport protocols like FT1.2 or USB the previous version of the SDK can be found here: https://github.com/weinzierl-engineering/baos

This also applies to devices supporting only the version 1.x of the BAOS protocol like 770.


1.3 Requirements

  • C++17 compatible compiler (tested with VS 2019, gcc and clang)
  • CMake: Version > 3.16.0 http://www.cmake.org/

2. Contents

The SDK contains:

docs
: SDK documentation

bin/samples
: The precompiled samples

lib
: The compiled library files

include : The public header file to use in your code

priv_include : SDK internal header files. May change between releases.

samples : Source code of the samples and a project to show a possible integration in your own project

share : Cmake files for dependencies

For details about the compiler used to build the libraries and samples see the file compiler-info.txt.

3. Getting Started

3.1 Running a sample

The examples are located in the bin/samples folder. Their source code is available in samples/connection and samples/device.

Power up your BAOS device and get its IP address via your prefered method. Either by checking your DHCP server leases, getting it from the display of the device or by configuring a static IP in the ETS and using that.

The remaining document assumes the IP address 10.0.0.102 for the BAOS device.

For most examples a ETS configuration is required or at least recommended. If certain datapoints are required to run a sample they are documented in the sample file header comment.

Example

Run the command : ./01_BaosDeviceInformation 10.0.0.102 inside the /bin/samples directory

This produces an output, like this:

******************************************
01_BaosDeviceInformation sample
******************************************
Connection requested for 10.0.0.102
Serial number: 00 C5 00 00 00 00
Manufacture code device: 197
MAC address: 01 02 03 04 05 06
Max datapoints: 2000
Max parameter bytes: 250
Manufacture code app: 197
Application ID: 1803
Application version: 17
KNX bus connected: true
Programming mode: false

Under the hood this sample uses the serveritems to obtain information about the connected BAOS device.

4. API and structure

The SDK is comprised of a set of layers.

SDK structure The SDK layers

On the bottom are the platform, OS specific drivers.

Above is the platform agnostic driver, in case of TCP this driver performs the detection of packages in the stream and provides the interface for sending and receiving telegrams(byte collections).

The next layer BaosConnection handles the BAOS binary protocol v2 itself and offers a direct interface to the BAOS services.

The topmost layer the BaosDeviceabstracts the details of the BAOS protocol and manages caching and strong types.

4.1 BaosDevice class

4.1.1 Device information

Lets start with the typical task to retrieve information about a device. Consider the following code snippet:

using namespace wz::baos;
ip::BaosIp4Device baosDevice("10.0.0.102");
const DeviceStaticInfo staticInfo = baosDevice.getStaticInfo();

First an BaosIp4Device object is created and the ip, of the BAOS device is given as constructor parameter.

There are three structures of device information that can be obtained.

The first is the static info as shown in the example above. It contains all the fields which never change, during normal operations, on a device, like serial number, hardware type etc.

The second structure contains fields which may change if the configuration of the device is changed, either via ETS download or per request from a BAOS client. It is assumed that after the configruation of the device this information does not change anymore.

The third block are fields that commonly change during the runtime of the device, like programming mode or KNX bus connection state.

Now that we have retrieved the information about the device lets try to change some of it.

// .. continue the code of the snippet above
const DeviceRuntimeInfo runtimeInfo = baosDevice.getRuntimeInfo();
baosDevice.setBoolServerItem(protocol::ServerItemId::ProgrammingMode, !runtimeInfo.programmingMode); // toggle the programming mode

Retrieve the runtime information of the device and use the current value of the programming mode to toggle it.

4.1.2 Datapoint configuration

Commonly the next step is getting information about the configured datapoints.

using namespace wz::baos;
ip::BaosIp4Device baosDevice("10.0.0.102");
const DeviceStaticInfo staticInfo = baosDevice.getStaticInfo();
DatapointConfigurations configurations = baosDevice.getAllDpConfigurations();

Now we know what datapoints are configured, their type, communication flags and optional their description string, as set in the ETS.

4.1.3 Datapoint values

The recommended way of working with datapoint values is

  1. to enable the indication sending in the ETS(it is enabled by default),
  2. read the by the BAOS device seen values (valid ones) at the beginning and
  3. stay updated via indications.
using namespace wz::baos;
ip::BaosIp4Device baosDevice("10.0.0.102");
const DeviceStaticInfo staticInfo = baosDevice.getStaticInfo();
const DatapointConfigurations configurations = baosDevice.getAllDpConfigurations();
const DatapointValues values = baosDevice.getAllDpValuesRaw();
baosDevice.registerDPValueCallback(
[](const DatapointValues& values)
{
// Do something with the values
});

NOTE

Indication callback functions are always invoked in the thread context of the BaosIndicationSender, so no heavy workload should be performed in the callback.


With these basic building blocks you are able to get information from the BAOS device, its configuration and work with datapoints and their values. For more details take a look at the samples/device folder.

4.1.4 Configuring the BaosDevice class

Detecting device capabilities

For most use cases everything should work out of the box but sometimes it is necessary to adapt the behavior.

As mentioned above the first step is retrieving information about the device.

A different strategy to achieve this may be used. For details on them see 10_ClassConfig sample.

Caching

To minimize the traffic between the SDK and the BAOS device, the BaosDevice class implements caching. Most functions have a reload parameter which defaults to false. If set to true is will bypass the cache. The cache allows quick access to the datapoint values and will be updated through indications.

One specialty of the datapoint value cache is that is only stores valid datapoint values. So what does valid mean in this context?

Lets consider the following example. In the KNX installation there is a push button connected to an switching actuator which in turn powers a light. Depending on the configuration the default value for the actuator may be On or Off. If the BAOS device is added to the already running installation or it took more time to boot up than the other two devices, is has no way of knowing if the light is currently turned on or not. So the BAOS device considers the value for the datapoint invalid until it receives a value from the KNX bus. Since those invalid, or you may say undefined datapoints values, contain no real information about the state of the KNX installation. Therefore the BaosDevice class only works with valid datapoints by default.

The cache will be filled by calling one of the "all" functions like getAllDpConfigurations, getAllParameterBytes , getAllDpValuesRaw. The config info functions getStaticInfo, getConfigInfo , getRuntimeInfo all implicitly call the protected function getAllServerItems to fill the serveritem cache.

4.2 BaosConnection class

One layer below resides the BaosConnection class. If more direct control and access to the raw bytes is required this is the entry point to use. It is a thin wrapper around the BAOS binary services and allows direct use of them. There is no caching, no block reading and no mapping to strong types. If you are in need for this approach look at the samples under samples/connection.

4.3 Logging

Under the hood the SDK uses the great logging framework https://github.com/gabime/spdlog. Currently all output is visible at the console. The SDK wide log level can be set with setBaosLogLevel

5. Documentation

The main documentation is directly written in the code. The SDK contains a prebuild version of the documentation in the docs/doxygen_html folder. The entrypoint is the index.html inside it.

6. Integration into your own project

Use the SDK as part of your project or install it somewhere on your system like '/usr/local/'.

6.1 Use SDK in your project

6.1.2 Setup your project

Under samples\project there is a simple example project which uses this library.

To build it :

  1. Switch into the samples\project folder.
  1. Create a build directory
    mkdir build
    cd build
  1. Find the line ending with // YOUR IP ADDRESS HERE in main.cpp and adapt it to your BAOS device ip address.
  1. Configure with cmake cmake -G "Unix Makefiles" ../
  1. Build with cmake --build .
  1. After successfull build execute sample with ./sampleBaosProject

If you want to setup your own project this sample may be used as a template.