CreOS C++ Client library

The CreOS Client library is used to interact with Avular robots.

Getting started

To get started with the CreOS Client library, you need to first install the library as described in the Installation section. After that, you can add the following to your CMakeLists.txt file to link the library to your CMake target:

find_package(creos_client REQUIRED)
add_executable(creos_hello_world main.cpp)
target_link_libraries(creos_hello_world PRIVATE creos::client)

After that, you can start using the library by including the main header file, and creating an instance of the Client class:

#include <creos/client.hpp>
int main() {
    try {
        // Connect to the robot
        creos::Client client{};

The Client class is the main class of the CreOS Client library. It enables communication with the CreOS Agent running on the robot. You can supply the host address of the robot to the constructor, as well as a port number to connect to. You can also set the CREOS_HOST and CREOS_PORT environment variables to set the default host and port.

Interfaces

The Client provides multiple interface handles, each of which exposing a subset of the connected robot's functionality. The following interfaces are available:

Sensors	The interface for retrieving sensor data from an Avular robot.
Power Management	The interface for querying and managing the power state of an Avular robot.
Setpoint Control	The interface for sending control setpoints to an Avular robot.
Transforms	The interface for retrieving information about the relationships between different coordinate frames used within an Avular robot.
System Info	The interface for retrieving general system information of an Avular robot.
Diagnostics	The interface for retrieving diagnostic information from an Avular robot.

More details about each interface can be found in the documentation of their respective interface class.

Interface functions

Each interface provides a set of functions to interact with the Data Sinks, Data Sources, and Callables provided by the robot. These signatures of these functions follow common patterns, based on the type of interaction they provide. The patterns are as follows, where * is a wildcard:

Concept	Function name pattern	Description
Data Sinks	publish*	These functions take the data to send as their only argument. If somehow the publication of the data fails, these functions will throw a creos::PublicationError.
Data Sources	subscribe*	All these functions take a callback function as an argument, which will be called when new data is available. The data is passed to the callback function as its first and only argument. Some Data Sources provide multiple data streams, e.g. the IMU interface provides data from multiple IMUs. In these cases, the function will take an additional *id argument to specify which data stream to subscribe to. If the subscription fails, these functions will throw a creos::SubscriptionError.
	get*	Convenience functions used to pull information once from Data Sources. They return the data that was pulled. These functions also take an optional timeout_ms argument, which can be used to time out the request if no data is not received within the specified amount of milliseconds. If the timeout is reached, these functions will throw a creos::TimeoutError.
Callables	*	These functions take the callable's required arguments as their arguments, and return the callable's return value. These functions also take an optional timeout_ms argument, which can be used to time out the request if the callable does not complete within the specified amount of milliseconds. If the timeout is reached, these functions will throw a creos::TimeoutError.

All of these functions use message types as provided in the creos_messages namespace for passing around data.

Compatibility

Not all robots support all interfaces; if the robot you are a connecting to does not support an interface, the Client will provide a nullptr reference when you request the interface. Some specific Data Sinks, Data Sources, and Callables may also not be supported by the robot. In these cases, their respective functions will throw an creos::UnsupportedError.