C++ API

Hand-written reference for the C++ headers under include/flexiv/pdk/ of an installed flexiv_pdk (cpp/include/flexiv/pdk/ in the source repository). Generated headers follow the proto paths: messages in .pb.h (for example flexiv/pdk/workcell/workcell_service.pb.h) and stubs in .grpc.pb.h. Namespaces follow the proto packages (flexiv::pdk::workcell), with two exceptions to note:

SurfaceFinishService and its requests are in flexiv::pdk::surface_finish::generator, not surface_finish.
MeshOperationService and its requests are in flexiv::pdk, not flexiv::pdk::mesh_operation.

CMake

find_package(flexiv_pdk REQUIRED)
target_link_libraries(my_app PRIVATE flexiv::flexiv_pdk)     # plain CMake
ament_target_dependencies(my_node PUBLIC flexiv_pdk)        # ROS 2

The target requires C++17 and brings in Eigen3, gRPC and Protobuf. See Install for C++.

Client

#include <flexiv/pdk/client.hpp>

template<typename ServiceT> class ServiceClient

Thin holder for a generated stub.

std::unique_ptr<typename ServiceT::Stub> stub

class Client

Owns the gRPC channel and lazily creates service clients. Not copyable or movable.

explicit Client(const std::string &target = "localhost:50052"): Create an insecure channel to target.

explicit Client(std::shared_ptr<grpc::Channel> channel): Use an existing channel. Throws std::invalid_argument if null.

VersionServiceClient &version()

LogServiceClient &log()

FrameServiceClient &frame()

SceneEventServiceClient &scene_event()

WorkcellServiceClient &workcell()

CollisionServiceClient &collision()

ComponentsServiceClient &system_config()

StateServiceClient &system_state()

SystemServiceClient &system()

KinematicsServiceClient &kinematics()

SurfaceFinishServiceClient &surface_finish()

ConfigServiceClient &config()

LicenseServiceClient &license()

PointToPointPathServiceClient &point_to_point_path()

MeshOperationServiceClient &mesh_operation()

CameraServiceClient &camera()

ReconstructionServiceClient &reconstruction(): Service accessors; thread-safe. Throw std::runtime_error after close().

class LicenseServiceClient : public ServiceClient<license::LicenseService>

Returned by Client::license(), with a helper for installing license files.

grpc::Status InstallFile(const std::string &path, license::SaveResponse *response, const std::string &file_name = ""): Install the .lic file Flexiv sent back; takes effect immediately. The file is read on this machine and its contents sent, base64-encoded unless it already is. file_name defaults to the file’s own name, or to the license id when that name is not a plain one. Check response->status() as with any other call. Throws std::runtime_error if the file cannot be read or is empty.

bool CheckVersion(std::string *message = nullptr): Ask the server whether this client works with it: same major and minor version. Returns false when the versions differ or the server cannot be reached. If message is not null, it is set to why not, or to the server version.

std::shared_ptr<grpc::Channel> channel() const: The channel; use it to create your own stubs, for example with custom call options. Returns null after close().

void close(): Release the channel. Every accessor called afterwards throws. Do not use service client references or stubs obtained before the call.

Session

#include <flexiv/pdk/session.hpp>

class Session

Bundles a client and a watch::Subscriber. Must outlive every component it is passed to; its destructor stops all subscriptions it created.

explicit Session(std::shared_ptr<Client> client): client may be null (offline mode).

Client *client()

std::shared_ptr<Client> client_ptr() const

watch::Subscriber &watch()

Watch

#include <flexiv/pdk/watch/subscriber.hpp>

class Subscriber

Opens server-streaming RPCs as background subscriptions. Not copyable.

template<typename EventT> Subscription Subscribe(ReaderOpener<EventT> open, EventCallback<EventT> on_event, Options options = {}): open is std::function<std::unique_ptr<grpc::ClientReaderInterface<EventT>>(grpc::ClientContext*)> and is called again on every reconnect. on_event is std::function<void(const EventT&)>.

void StopAll()

class Subscription

Move-only handle. The watch runs while the handle is alive; discarding it ends the watch.

void reset(): Cancel the stream and block until delivery has stopped.

bool active() const noexcept

explicit operator bool() const noexcept: True while the watch runs. False once it is stopped, or once it gives up because reconnect is off or max_retries is used up.

struct Options

std::shared_ptr<Executor> executor

bool reconnect = true

std::chrono::milliseconds backoff_initial = 500ms

std::chrono::milliseconds backoff_max = 10000ms

double backoff_factor = 2.0

int max_retries = -1

class Executor

Decides which thread runs callbacks. Implement it to forward to a UI thread.

virtual void Post(std::function<void()> fn) = 0

class InlineExecutor : public Executor : Runs callbacks immediately on the watch thread.

Eigen conversions

#include <flexiv/pdk/spatial/eigen_conversion.hpp>

Eigen::Vector3d ToEigen(const Vector3 &v)

Vector3 ToProto(const Eigen::Vector3d &v)

Eigen::Quaterniond ToEigen(const Quaternion &q)

Quaternion ToProto(const Eigen::Quaterniond &q)

Eigen::Isometry3d ToEigen(const SE3Pose &p)

SE3Pose ToProto(const Eigen::Isometry3d &p)

Eigen::VectorXd ToEigen(const google::protobuf::RepeatedField<double> &v)

google::protobuf::RepeatedField<double> ToProto(const Eigen::VectorXd &v)

std::pair<Eigen::VectorXd, Eigen::VectorXd> ToEigen(const JointWaypoint &waypoint): Returns (position, velocity).

JointWaypoint ToProto(const Eigen::VectorXd &joint_position, const Eigen::VectorXd &joint_velocity)

template<typename Derived> Vector3 ToProto(const Eigen::MatrixBase<Derived> &v): For a fixed-size 3-vector expression, such as Isometry3d::translation().

template<typename Derived> google::protobuf::RepeatedField<double> ToProto(const Eigen::MatrixBase<Derived> &v): For a dynamic-size column-vector expression, such as VectorXd::head().

An all-zero (unset) Quaternion converts to the identity rotation.

#include <flexiv/pdk/physics/eigen_conversion.hpp>

Eigen::Matrix3d ToEigen(const Inertia &I)

Inertia ToProto(const Eigen::Matrix3d &I)