The OpenZen API is implemented using a pure CAPI to guarantee ABI stability. On top
of this we provide a modern C++ wrapper to simplify API interactions and allow RAII.
The C++ wrapper consists of three classes:
zen::ZenSensorComponent. The client allows listing, obtaining and releasing of
sensors; as well as waiting for and polling events. The sensor - obtained through the
client - provides methods for executing, retrieving and updating properties of the
core sensor; in addition to updating firmware and IAP. Additionally, it offers
information about and access to the sensor components it houses. Each sensor component
in turn provides methods for executing, retrieving and updating the component’s properties.
Examples of sensor components are an IMU, GPS and temperature sensor.
The C++ API is contained in the file
OpenZen.h and has support for C++14 and C++17.
By default, the C++14 API will be used. If your project uses C++17 for compilation, the
C++17 API will be automatically used. You can also force the usage of the C++17 API by
defining the preprocessor variable
The C++14 and C++17 APIs have the same method names but the C++17 uses more convenient
return types via the std::optional class.
A complete example of the C++ API usage can be found at this example source file.
Initialisation and Cleanup¶
In your application, you can create any numbers of clients to manage the sensors that
you want to communicate with. When a new client is created, the OpenZen backend needs
to connect to subsystems, which can result in failure. To initialize a client, call
zen::make_client() function that returns an
std::pair containing a potential ZenError
and ZenClient instance. Before you use the returned ZenClient class instance check
whether the returned error equals
std::pair<ZenError, ZenClient> make_client() noexcept
A ZenClient instance is automatically destructed when it goes out of scope. If you
want to terminate the client’s event queue prior to this, call the
function. This could be the case in multi-threaded systems.
Every ZenClient instance contains its own event queue which accumulates events
from all sensors that were obtained on that client. Events can either be polled
ZenClient::pollNextEvent or waited for using
The only way to terminate a client that is waiting for an event, is by destroying
the client or preemptively calling