C++

Download and Installation

The C++ SDK is distributed as pre-compiled binaries for easy integration.

Supported platforms:

  • Linux: x86_64 and aarch64
  • Windows: x86_64
  • macOS: arm64

Download: Get the binaries here

Installation: Copy the downloaded files to your C++ project and configure your build system to link against the library.

Usage Demo

We provide a demo to get yourself started with the C++ SDK.

What you'll find in the demo:

  • Wrench, Twist, IMU and Pose transformer setup and configuration
  • Static and dynamic TF entry patterns
  • Real-time loop integration examples in C++

API Description

All four transformation utilities follow the same interface pattern. Each class lives in the bota namespace and is constructed either with a path to a JSON configuration file or with a bota::BotaTfConfig struct populated in user code (see Concept for the config file structure).

Configuration Types

struct bota::Translation

User-facing translation entry: the origin frame and its [x, y, z] value. An empty origin means “not yet set” — supply the value later via the appropriate set*() method before calling update().

std::string origin

The origin frame. Must be "fixed_frame" or "moving_frame", or empty if not yet set.

std::array<double, 3> translation

Translation [x, y, z] in metres from the origin frame. Default: {0, 0, 0}.

struct bota::Rotation

User-facing rotation entry: the origin frame and a quaternion [w, x, y, z]. An empty origin means “not yet set” — supply the value later via the appropriate set*() method before calling update().

std::string origin

The origin frame. Must be "fixed_frame" or "moving_frame", or empty if not yet set.

std::array<double, 4> rotation

Unit quaternion [qw, qx, qy, qz] describing the rotation from the origin frame. Default: {1, 0, 0, 0} (identity).

struct bota::BotaTfConfig

Plain-data configuration struct that can be populated in user code and passed directly to any BotaTf* constructor.

Entries with an empty origin are treated as “not set” and must be supplied via the set*() methods before update() is called. All entries provided here remain overridable via set*() after construction.

std::string name

Human-readable name for the transformer block. Returned by name().

BotaControlBlockPolicy policy

Error-handling policy applied by update(). Default: BotaControlBlockPolicy::BestEffort.

Translation input_ref_point

Translation from the origin frame to the input reference point.

Rotation input_expr_axes

Rotation from the origin frame to the input expression axes.

Translation output_ref_point

Translation from the origin frame to the output reference point.

Rotation output_expr_axes

Rotation from the origin frame to the output expression axes.

BotaTfWrench

Transforms a 6-DOF wrench [fx, fy, fz, tx, ty, tz] between reference points and expression axes.

class bota::BotaTfWrench

Constructor and Destructor

explicit BotaTfWrench(const std::string &config_file = "")

Constructs the object. Optionally loads static TF entries from a JSON config file (section key "tf_wrench_config"). If config_file is empty, all entries must be set via the setters described below.

Parameters:

config_file – Path to the JSON configuration file.

Type config_file:

const std::string&

explicit BotaTfWrench(const BotaTfConfig &config)

Constructs the object from a bota::BotaTfConfig struct populated in user code. Entries with an empty origin must be completed via the set*() methods before update() is called.

Parameters:

config – Pre-populated configuration struct.

Type config:

const BotaTfConfig&

~BotaTfWrench()

Default destructor.

Metadata

const std::string &name() const

Returns the name specified in the JSON config or BotaTfConfig::name, or an empty string if neither was provided.

Rtype:

const std::string&

TF Setters

These can be called before or inside the RT loop to update the geometry. Each returns false (and prints a warning) if the corresponding entry was already loaded from the JSON config file or the bota::BotaTfConfig struct — preventing config / code conflicts.

bool setInputReferencePoint(const std::string &origin, const std::array<double, 3> &translation)

Sets the translation from origin to the input reference point (expressed in origin axes).

Parameters:

  • origin – "fixed_frame" or "moving_frame".

  • translation – [x, y, z] in metres from origin frame to input reference point.

Returns:

true on success; false if this entry was already loaded from config.

Rtype:

bool

bool setInputExpressionAxes(const std::string &origin, const std::array<double, 4> &rotation)

Sets the rotation from origin to the input expression axes.

Parameters:

  • origin – "fixed_frame" or "moving_frame".

  • rotation – [qw, qx, qy, qz] unit quaternion rotation from origin frame to input expression axes.

Returns:

true on success; false if this entry was already loaded from config.

Rtype:

bool

bool setOutputReferencePoint(const std::string &origin, const std::array<double, 3> &translation)

Sets the translation from origin to the output reference point (expressed in origin axes).

Parameters:

  • origin – "fixed_frame" or "moving_frame".

  • translation – [x, y, z] in metres from origin frame to output reference point.

Returns:

true on success; false if this entry was already loaded from config.

Rtype:

bool

bool setOutputExpressionAxes(const std::string &origin, const std::array<double, 4> &rotation)

Sets the rotation from origin to the output expression axes.

Parameters:

  • origin – "fixed_frame" or "moving_frame".

  • rotation – [qw, qx, qy, qz] unit quaternion rotation from origin frame to output expression axes.

Returns:

true on success; false if this entry was already loaded from config.

Rtype:

bool

Dynamic TF

void setFixedToMovingFrameTf(const std::array<double, 7> &tf)

Pushes the current fixed-to-moving-frame transform. Must be called every loop iteration when any TF entry uses "moving_frame". Cannot be set via the JSON config or bota::BotaTfConfig.

Parameters:

tf – [tx, ty, tz, qw, qx, qy, qz] — translation (metres) followed by unit quaternion.

Transform

BotaControlReturnCode update(const std::array<double, 6> &wrench_in, std::array<double, 6> &wrench_out)

Transforms the input wrench and writes the result to wrench_out.

Parameters:

  • wrench_in – Input wrench [fx, fy, fz, tx, ty, tz] at the input reference point, expressed in the input expression axes.

  • wrench_out – Output wrench [fx, fy, fz, tx, ty, tz] at the output reference point, expressed in the output expression axes.

Returns:

BotaControlReturnCode::OK on success, or a warning/error code according to the configured policy.

Rtype:

BotaControlReturnCode

BotaTfPose

Transforms a 7-DOF pose [px, py, pz, qw, qx, qy, qz] between reference points and expression axes. Uses config key "tf_pose_config".

The pose always describes position and orientation relative to the base (fixed) frame. The reference point is the end point for which the pose is computed; the base is always the implicit starting point.

  • Position [px, py, pz]: position of the reference point in the base frame, expressed in the output expression axes.

  • Orientation [qw, qx, qy, qz]: orientation of the moving body relative to the output expression axes (Eigen convention: q * v_moving = v_expressed).

Note

BotaTfPose does not have a setFixedToMovingFrameTf() method. The orientation of the moving frame is encoded directly in the input pose quaternion, so no separate dynamic TF call is needed each loop iteration.

class bota::BotaTfPose

Constructor and Destructor

explicit BotaTfPose(const std::string &config_file = "")

Constructs the transformer. Optionally loads static TF entries from "tf_pose_config".

Parameters:

config_file – Path to the JSON configuration file.

Type config_file:

const std::string&

explicit BotaTfPose(const BotaTfConfig &config)

Constructs the transformer from a bota::BotaTfConfig struct populated in user code.

Parameters:

config – Pre-populated configuration struct.

Type config:

const BotaTfConfig&

~BotaTfPose()

Metadata

const std::string &name() const

Returns the name specified in the JSON config or BotaTfConfig::name, or an empty string if neither was provided.

Rtype:

const std::string&

TF Setters

These can be called before or inside the RT loop to update the geometry. Each returns false (and prints a warning) if the corresponding entry was already loaded from config.

bool setInputReferencePoint(const std::string &origin, const std::array<double, 3> &translation)
Parameters:

  • origin – "fixed_frame" or "moving_frame".

  • translation – [x, y, z] in metres from origin frame to input reference point.

Returns:

true on success; false if this entry was already loaded from config.

Rtype:

bool

bool setInputExpressionAxes(const std::string &origin, const std::array<double, 4> &rotation)
Parameters:

  • origin – "fixed_frame" or "moving_frame".

  • rotation – [qw, qx, qy, qz] unit quaternion.

Returns:

true on success; false if this entry was already loaded from config.

Rtype:

bool

bool setOutputReferencePoint(const std::string &origin, const std::array<double, 3> &translation)
Parameters:

  • origin – "fixed_frame" or "moving_frame".

  • translation – [x, y, z] in metres from origin frame to output reference point.

Returns:

true on success; false if this entry was already loaded from config.

Rtype:

bool

bool setOutputExpressionAxes(const std::string &origin, const std::array<double, 4> &rotation)
Parameters:

  • origin – "fixed_frame" or "moving_frame".

  • rotation – [qw, qx, qy, qz] unit quaternion.

Returns:

true on success; false if this entry was already loaded from config.

Rtype:

bool

Transform

BotaControlReturnCode update(const std::array<double, 7> &pose_in, std::array<double, 7> &pose_out)

Transforms the input pose and writes the result to pose_out.

Parameters:

  • pose_in – Input pose [px, py, pz, qw, qx, qy, qz].

  • pose_out – Output pose [px, py, pz, qw, qx, qy, qz].

Returns:

BotaControlReturnCode::OK on success, or a warning/error code according to the configured policy.

Rtype:

BotaControlReturnCode

BotaTfTwist

Transforms a 6-DOF twist [vx, vy, vz, wx, wy, wz] between reference points and expression axes. The interface is identical to BotaTfWrench — only the config key ("tf_twist_config") and the signal semantics differ.

class bota::BotaTfTwist

Constructor and Destructor

explicit BotaTfTwist(const std::string &config_file = "")

Constructs the transformer. Optionally loads static TF entries from "tf_twist_config".

Parameters:

config_file – Path to the JSON configuration file.

Type config_file:

const std::string&

explicit BotaTfTwist(const BotaTfConfig &config)

Constructs the transformer from a bota::BotaTfConfig struct populated in user code.

Parameters:

config – Pre-populated configuration struct.

Type config:

const BotaTfConfig&

~BotaTfTwist()

Metadata

const std::string &name() const

Returns the name specified in the JSON config or BotaTfConfig::name, or an empty string if neither was provided.

Rtype:

const std::string&

TF Setters

These can be called before or inside the RT loop to update the geometry. Each returns false (and prints a warning) if the corresponding entry was already loaded from config.

bool setInputReferencePoint(const std::string &origin, const std::array<double, 3> &translation)
Parameters:

  • origin – "fixed_frame" or "moving_frame".

  • translation – [x, y, z] in metres from origin frame to input reference point.

Returns:

true on success; false if this entry was already loaded from config.

Rtype:

bool

bool setInputExpressionAxes(const std::string &origin, const std::array<double, 4> &rotation)
Parameters:

  • origin – "fixed_frame" or "moving_frame".

  • rotation – [qw, qx, qy, qz] unit quaternion.

Returns:

true on success; false if this entry was already loaded from config.

Rtype:

bool

bool setOutputReferencePoint(const std::string &origin, const std::array<double, 3> &translation)
Parameters:

  • origin – "fixed_frame" or "moving_frame".

  • translation – [x, y, z] in metres from origin frame to output reference point.

Returns:

true on success; false if this entry was already loaded from config.

Rtype:

bool

bool setOutputExpressionAxes(const std::string &origin, const std::array<double, 4> &rotation)
Parameters:

  • origin – "fixed_frame" or "moving_frame".

  • rotation – [qw, qx, qy, qz] unit quaternion.

Returns:

true on success; false if this entry was already loaded from config.

Rtype:

bool

Dynamic TF

void setFixedToMovingFrameTf(const std::array<double, 7> &tf)

Pushes the current fixed-to-moving-frame transform. Must be called every loop iteration when any TF entry uses "moving_frame". Cannot be set via the JSON config or bota::BotaTfConfig.

Parameters:

tf – [tx, ty, tz, qw, qx, qy, qz] — translation (metres) followed by unit quaternion.

Transform

BotaControlReturnCode update(const std::array<double, 6> &twist_in, std::array<double, 6> &twist_out)

Transforms the input twist and writes the result to twist_out.

Parameters:

  • twist_in – Input twist [vx, vy, vz, wx, wy, wz].

  • twist_out – Output twist [vx, vy, vz, wx, wy, wz].

Returns:

BotaControlReturnCode::OK on success, or a warning/error code according to the configured policy.

Rtype:

BotaControlReturnCode

BotaTfImu

Transforms a 6-DOF IMU signal [ax, ay, az, wx, wy, wz] (linear acceleration + angular velocity) between reference points and expression axes, accounting for the centripetal acceleration term when the reference point changes.

Physics:

  • Angular velocity ω: identical at every point on a rigid body — only the expression axes change:

    \[\omega_\text{out} = R_{\text{out} \leftarrow \text{fixed}}\; \omega_\text{fixed}\]

  • Linear acceleration a: varies with reference point due to the centripetal term. The angular acceleration term (α × r) is not included because it is not directly measured by an IMU:

    \[a_\text{out} = R_{\text{out} \leftarrow \text{fixed}} \bigl(R_{\text{fixed} \leftarrow \text{in}}\, a_\text{in} + \omega_\text{fixed} \times (\omega_\text{fixed} \times (p_\text{out} - p_\text{in}))\bigr)\]

The interface is identical to BotaTfWrench — only the config key ("tf_imu_config") and the signal semantics differ.

class bota::BotaTfImu

Constructor and Destructor

explicit BotaTfImu(const std::string &config_file = "")

Constructs the transformer. Optionally loads static TF entries from "tf_imu_config".

Parameters:

config_file – Path to the JSON configuration file.

Type config_file:

const std::string&

explicit BotaTfImu(const BotaTfConfig &config)

Constructs the transformer from a bota::BotaTfConfig struct populated in user code.

Parameters:

config – Pre-populated configuration struct.

Type config:

const BotaTfConfig&

~BotaTfImu()

Metadata

const std::string &name() const

Returns the name specified in the JSON config or BotaTfConfig::name, or an empty string if neither was provided.

Rtype:

const std::string&

TF Setters

These can be called before or inside the RT loop to update the geometry. Each returns false (and prints a warning) if the corresponding entry was already loaded from config.

bool setInputReferencePoint(const std::string &origin, const std::array<double, 3> &translation)
Parameters:

  • origin – "fixed_frame" or "moving_frame".

  • translation – [x, y, z] in metres from origin frame to input reference point.

Returns:

true on success; false if this entry was already loaded from config.

Rtype:

bool

bool setInputExpressionAxes(const std::string &origin, const std::array<double, 4> &rotation)
Parameters:

  • origin – "fixed_frame" or "moving_frame".

  • rotation – [qw, qx, qy, qz] unit quaternion.

Returns:

true on success; false if this entry was already loaded from config.

Rtype:

bool

bool setOutputReferencePoint(const std::string &origin, const std::array<double, 3> &translation)
Parameters:

  • origin – "fixed_frame" or "moving_frame".

  • translation – [x, y, z] in metres from origin frame to output reference point.

Returns:

true on success; false if this entry was already loaded from config.

Rtype:

bool

bool setOutputExpressionAxes(const std::string &origin, const std::array<double, 4> &rotation)
Parameters:

  • origin – "fixed_frame" or "moving_frame".

  • rotation – [qw, qx, qy, qz] unit quaternion.

Returns:

true on success; false if this entry was already loaded from config.

Rtype:

bool

Dynamic TF

void setFixedToMovingFrameTf(const std::array<double, 7> &tf)

Pushes the current fixed-to-moving-frame transform. Must be called every loop iteration when any TF entry uses "moving_frame". Cannot be set via the JSON config or bota::BotaTfConfig.

Parameters:

tf – [tx, ty, tz, qw, qx, qy, qz] — translation (metres) followed by unit quaternion.

Transform

BotaControlReturnCode update(const std::array<double, 6> &imu_in, std::array<double, 6> &imu_out)

Transforms the input IMU signal and writes the result to imu_out.

Parameters:

  • imu_in – Input IMU signal [ax, ay, az, wx, wy, wz] (m/s² and rad/s).

  • imu_out – Output IMU signal [ax, ay, az, wx, wy, wz].

Returns:

BotaControlReturnCode::OK on success, or a warning/error code according to the configured policy.

Rtype:

BotaControlReturnCode