BAOS SDK v2
1.0.1
An SDK providing access to IP-BAOS devices through BAOS binary protocol version 2.x
|
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:
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.
Provide information about the BAOS device itself, like serial number.
Represent KNX group objects and optional a description string for them.
A block of generic bytes written during an ETS download, which then can be retrieved during runtime.
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".
Devices supporting the Weinzierl BAOS binary protocol version 2.x via TCP/IP:
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.
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
.
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.
Run the command : ./01_BaosDeviceInformation 10.0.0.102
inside the /bin/samples
directory
This produces an output, like this:
Under the hood this sample uses the serveritems to obtain information about the connected BAOS device.
The SDK is comprised of a set of layers.
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.
Lets start with the typical task to retrieve information about a device. Consider the following code snippet:
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.
Retrieve the runtime information of the device and use the current value of the programming mode to toggle it.
Commonly the next step is getting information about the configured datapoints.
Now we know what datapoints are configured, their type, communication flags and optional their description string, as set in the ETS.
The recommended way of working with datapoint values is
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.
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.
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.
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
.
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
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.
Use the SDK as part of your project or install it somewhere on your system like '/usr/local/'.
Under samples\project
there is a simple example project which uses this library.
To build it :
samples\project
folder.// YOUR IP ADDRESS HERE
in main.cpp
and adapt it to your BAOS device ip address.cmake -G "Unix Makefiles" ../
cmake --build .
./sampleBaosProject
If you want to setup your own project this sample may be used as a template.