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 (MSVC 2019 and MSVC 2022)
  • 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:

  • Contact point and slip detector setup and configuration
  • Contact detection, contact localisation and slip detection
  • Real-time loop integration examples in C++

API Description

All types live in the bota namespace. BotaContactPoint and BotaSlipDetector use a PIMPL pattern for implementation encapsulation, and are constructed either with a path to a JSON configuration file or with a configuration struct populated in user code (see Concept for the configuration structure).

Note

The two blocks are meant to be chained: the slip detector consumes the contact wrench produced by the contact point block, not the raw input wrench.

Contact Point

Estimates the point of application of a measured wrench [fx, fy, fz, tx, ty, tz] on a known contact surface.

Configuration Types

enum struct bota::ContactGeometryType

Shape of the surface the contact point lies on.

enumerator PLANE

Plane parallel to the xy-plane of the wrench frame, offset by dz along +z.

struct bota::ContactGeometry

Geometry of the contact surface, expressed in the frame the wrench is measured in.

ContactGeometry()

Default constructor. Equivalent to a plane through the origin.

ContactGeometry(ContactGeometryType type = ContactGeometryType::PLANE, double dz = 0.0)

Constructs the geometry from a surface type and its parameter.

ContactGeometryType type

Contact surface type. Default: ContactGeometryType::PLANE.

double dz

[m] Plane offset along +z. Used when type is PLANE. Must be finite. Default: 0.0.

struct bota::BotaContactPointConfig

Plain-data configuration struct that can be populated in user code and passed directly to the BotaContactPoint constructor. Every field has a usable default.

std::string name

Human-readable name for the block. Optional, and returned by name() only when the block was configured from a JSON file.

BotaControlBlockPolicy policy

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

ContactGeometry geometry

Contact surface the line of action of the wrench is intersected with.

double force_threshold

[N] Force threshold. Applied to \(\lVert \mathbf{f} \rVert\) it decides whether a contact is reported at all; applied to \(\lvert f_z \rvert\) it decides whether the contact can be localised. Must be finite and greater than zero. Default: 0.3.

BotaContactPoint

class bota::BotaContactPoint

Constructor and Destructor

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

Constructs the block from a JSON config file (section key "contact_point_config"). If config_file is empty, the block starts from the defaults and must be configured via the setters below.

Parameters:

config_file – Path to the JSON configuration file (may be empty).

explicit BotaContactPoint(const BotaContactPointConfig &config)

Constructs the block from a configuration struct populated in user code. Every value remains overridable via the setters below.

Parameters:

config – Fully or partially populated configuration struct.

~BotaContactPoint()

Note

The class is move-only: it provides a move constructor and a move assignment operator, but cannot be copied. Store it by value or in a std::unique_ptr, and move it when ownership needs to change.

Configuration Methods

bool setGeometry(const ContactGeometry &geometry)

Sets the contact surface geometry.

Parameters:

geometry – The contact surface.

Returns:

false when the value came from a JSON config, which cannot be overridden from code, or when the geometry is invalid. true otherwise.

bool setForceThreshold(double force_threshold)

[N] Sets the force threshold.

Parameters:

force_threshold – Must be finite and greater than zero.

Returns:

false when the value came from a JSON config, which cannot be overridden from code, or when the value is invalid. true otherwise.

Runtime Update Method

BotaControlReturnCode update(const std::array<double, 6> &wrench, std::array<double, 3> &contact_point)

Computes the contact point of the given wrench and writes the result into contact_point in place.

Parameters:

  • wrench – Input wrench [fx, fy, fz, tx, ty, tz] in N and Nm.

  • contact_point – Output contact point [x, y, z] in m, written in place.

Returns:

A return code indicating the status of the update operation.

Returns OK both when a contact point was computed and when no contact is present; use inContact() to tell the two apart. The contact point is zeroed on every non-OK outcome, so a caller that only checks the return code never sees a stale position.

Query Methods

bool inContact() const
Returns:

true when the last update() found a force above the configured threshold.

double contactForceMagnitude() const
Returns:

[N] Force magnitude \(\lVert \mathbf{f} \rVert\) seen by the last update().

std::array<double, 6> contactWrench() const
Returns:

The wrench of the last update() moved to the contact point: the input forces, and the residual torsion about the contact normal. This is the input expected by BotaSlipDetector.

std::string name() const
Returns:

Name of the block as specified in the JSON config. Empty when the block was configured from code only.

Important

Check the return code and inContact() before using the point. A return code of OK with inContact() == false means the sensor is untouched, and the contact point has been zeroed accordingly.

Slip Detector

Compares the wrench at the contact point against the friction limits of the contact, and reports whether the contact is slipping.

Configuration Types

struct bota::ContactFrictionCoefficients

Friction coefficients of the contact pair, i.e. of the tool material against the object material.

ContactFrictionCoefficients()

Default constructor.

ContactFrictionCoefficients(double linear, double torsional)

Constructs the coefficients from their two values.

double linear

Linear friction coefficient, dimensionless. The tangential-to-normal force ratio above which the contact is declared to be slipping. Must be finite and greater than zero.

double torsional

[m] Torsional friction coefficient. The torsion-to-normal-force ratio above which the contact is declared to be slipping. Must be finite and greater than zero.

struct bota::BotaSlipDetectorConfig

Plain-data configuration struct that can be populated in user code and passed directly to the BotaSlipDetector constructor. Every field has a usable default.

std::string name

Human-readable name for the block. Optional, and returned by name() only when the block was configured from a JSON file.

BotaControlBlockPolicy policy

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

ContactFrictionCoefficients friction_coefficients

Friction limits the measured ratios are compared against.

double force_threshold

[N] Force threshold. Below it the contact is considered released and no slip verdict is produced. Must be finite and greater than zero. Default: 0.3.

BotaSlipDetector

class bota::BotaSlipDetector

Constructor and Destructor

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

Constructs the block from a JSON config file (section key "slip_detector_config"). If config_file is empty, the block starts from the defaults and must be configured via the setters below.

Parameters:

config_file – Path to the JSON configuration file (may be empty).

explicit BotaSlipDetector(const BotaSlipDetectorConfig &config)

Constructs the block from a configuration struct populated in user code. Every value remains overridable via the setters below.

Parameters:

config – Fully or partially populated configuration struct.

~BotaSlipDetector()

Note

The class is move-only, exactly like BotaContactPoint.

Configuration Methods

bool setFrictionCoefficients(const ContactFrictionCoefficients &friction_coefficients)

Sets the friction limits of the contact pair.

Parameters:

friction_coefficients – The linear and torsional coefficients.

Returns:

false when the value came from a JSON config, which cannot be overridden from code, or when a coefficient is invalid. true otherwise.

bool setForceThreshold(double force_threshold)

[N] Sets the force threshold.

Parameters:

force_threshold – Must be finite and greater than zero.

Returns:

false when the value came from a JSON config, which cannot be overridden from code, or when the value is invalid. true otherwise.

Runtime Update Method

BotaControlReturnCode update(const std::array<double, 6> &contact_wrench, std::array<double, 4> &slip_status)

Evaluates both friction conditions for the given contact wrench and writes the result into slip_status in place.

Parameters:

  • contact_wrench – The wrench at the contact point, as returned by BotaContactPoint::contactWrench(), in N and Nm. Its z axis is the contact normal.

  • slip_status – Output [is_linear_slipping, is_torsional_slipping, linear_slip_ratio, torsional_slip_ratio], written in place. The two flags are 0.0 or 1.0; the linear ratio is dimensionless and the torsional ratio is in m.

Returns:

A return code indicating the status of the update operation.

Returns OK both when a verdict was produced and when no contact is present; use inContact() to tell the two apart. slip_status is zeroed on every non-OK outcome and whenever no contact is present.

Query Methods

bool inContact() const
Returns:

true when the last update() found a force above the configured threshold.

std::string name() const
Returns:

Name of the block as specified in the JSON config. Empty when the block was configured from code only.

Important

Prefer the ratios over the flags in a control loop. The flags tell you the contact has already given way; the ratios tell you how much margin is left before it does.