Flexiv RDK APIs  1.5
Public Member Functions | Friends | List of all members
flexiv::rdk::Robot Class Reference

Main interface with the robot, containing several function categories and background services. More...

#include <robot.hpp>

Public Member Functions

 Robot (const std::string &robot_sn)
 [Blocking] Create an instance as the main robot control interface. RDK services will initialize and connection with the robot will be established. More...
 
bool connected () const
 [Non-blocking] Whether the connection with the robot is established. More...
 
const RobotInfo info () const
 [Non-blocking] General information about the connected robot. More...
 
Mode mode () const
 [Non-blocking] Current control mode of the robot. More...
 
const RobotStates states () const
 [Non-blocking] Current states data of the robot. More...
 
bool stopped () const
 [Non-blocking] Whether the robot has come to a complete stop. More...
 
bool operational (bool verbose=true) const
 [Non-blocking] Whether the robot is ready to be operated, which requires the following conditions to be met: enabled, brakes fully released, in auto mode, no fault, and not in reduced state. More...
 
OperationalStatus operational_status () const
 [Non-blocking] Current operational status of the robot. More...
 
bool busy () const
 [Non-blocking] Whether the robot is currently executing a task. This includes any user commanded operations that requires the robot to execute. For example, plans, primitives, Cartesian and joint motions, etc. More...
 
bool fault () const
 [Non-blocking] Whether the robot is in fault state. More...
 
bool reduced () const
 [Non-blocking] Whether the robot is in reduced state. More...
 
bool recovery () const
 [Non-blocking] Whether the robot is in recovery state. More...
 
bool estop_released () const
 [Non-blocking] Whether the emergency stop is released. More...
 
bool enabling_button_pressed () const
 [Non-blocking] Whether the enabling button is pressed. More...
 
const std::vector< std::string > mu_log () const
 [Non-blocking] Get multilingual log messages of the connected robot. More...
 
void Enable ()
 [Blocking] Enable the robot, if E-stop is released and there's no fault, the robot will release brakes, and becomes operational a few seconds later. More...
 
void Brake (bool engage)
 [Blocking] Force robot brakes to engage or release during normal operation. Restrictions apply, see warning. More...
 
void SwitchMode (Mode mode)
 [Blocking] Switch to a new control mode and wait until mode transition is finished. More...
 
void Stop ()
 [Blocking] Stop the robot and transit robot mode to IDLE. More...
 
bool ClearFault (unsigned int timeout_sec=30)
 [Blocking] Try to clear minor or critical fault of the robot without a power cycle. More...
 
void RunAutoRecovery ()
 [Blocking] Run automatic recovery to bring joints that are outside the allowed position range back into allowed range. More...
 
void SetGlobalVariables (const std::map< std::string, FlexivDataTypes > &global_vars)
 [Blocking] Set values to global variables that already exist in the robot. More...
 
void SetGlobalVariables (const std::string &global_vars)
 
std::map< std::string, FlexivDataTypesglobal_variables () const
 [Blocking] Existing global variables and their current values. More...
 
const std::vector< std::string > global_variables (bool dummy)
 Unused parameter [dummy] is needed for function overloading.
 
void ExecutePlan (unsigned int index, bool continue_exec=false, bool block_until_started=true)
 [Blocking] Execute a plan by specifying its index. More...
 
void ExecutePlan (const std::string &name, bool continue_exec=false, bool block_until_started=true)
 [Blocking] Execute a plan by specifying its name. More...
 
void PausePlan (bool pause)
 [Blocking] Pause or resume the execution of the current plan. More...
 
const std::vector< std::string > plan_list () const
 [Blocking] Get a list of all available plans. More...
 
const PlanInfo plan_info () const
 [Blocking] Get detailed information about the currently executing plan. Contains information like plan name, primitive name, node name, node path, node path time period, etc. More...
 
void SetBreakpointMode (bool is_enabled)
 [Blocking] Enable or disable the breakpoint mode during plan execution. When enabled, the currently executing plan will pause at the pre-defined breakpoints. Use StepBreakpoint() to continue the execution and pause at the next breakpoint. More...
 
void StepBreakpoint ()
 [Blocking] If breakpoint mode is enabled, step to the next breakpoint. The plan execution will continue and pause at the next breakpoint. More...
 
void SetVelocityScale (unsigned int velocity_scale)
 [Blocking] Set overall velocity scale for robot motions during plan and primitive execution. More...
 
void ExecutePrimitive (const std::string &primitive_name, const std::map< std::string, FlexivDataTypes > &input_params, bool block_until_started=true)
 [Blocking] Execute a primitive by specifying its name and parameters, which can be found in the Flexiv Primitives documentation. More...
 
void ExecutePrimitive (const std::string &pt_cmd, bool block_until_started=true)
 
std::map< std::string, FlexivDataTypesprimitive_states () const
 [Blocking] State parameters of the executing primitive and their current values. More...
 
const std::vector< std::string > primitive_states (bool dummy)
 Unused parameter [dummy] is needed for function overloading.
 
void StreamJointTorque (const std::vector< double > &torques, bool enable_gravity_comp=true, bool enable_soft_limits=true)
 [Non-blocking] Continuously stream joint torque command to the robot. More...
 
void StreamJointPosition (const std::vector< double > &positions, const std::vector< double > &velocities, const std::vector< double > &accelerations)
 [Non-blocking] Continuously stream joint position, velocity, and acceleration command to the robot. The commands are tracked by either the joint impedance controller or the joint position controller, depending on the control mode. More...
 
void SendJointPosition (const std::vector< double > &positions, const std::vector< double > &velocities, const std::vector< double > &accelerations, const std::vector< double > &max_vel, const std::vector< double > &max_acc)
 [Non-blocking] Discretely send joint position, velocity, and acceleration command to the robot. The robot's internal motion generator will smoothen the discrete commands, which are tracked by either the joint impedance controller or the joint position controller, depending on the control mode. More...
 
void SetJointImpedance (const std::vector< double > &K_q, const std::vector< double > &Z_q={0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7})
 [Blocking] Set impedance properties of the robot's joint motion controller used in the joint impedance control modes. More...
 
void StreamCartesianMotionForce (const std::array< double, kPoseSize > &pose, const std::array< double, kCartDoF > &wrench={}, const std::array< double, kCartDoF > &velocity={}, const std::array< double, kCartDoF > &acceleration={})
 [Non-blocking] Continuously stream Cartesian motion and/or force command for the robot to track using its unified motion-force controller, which allows doing force control in zero or more Cartesian axes and motion control in the rest axes. More...
 
void SendCartesianMotionForce (const std::array< double, kPoseSize > &pose, const std::array< double, kCartDoF > &wrench={}, double max_linear_vel=0.5, double max_angular_vel=1.0, double max_linear_acc=2.0, double max_angular_acc=5.0)
 [Non-blocking] Discretely send Cartesian motion and/or force command for the robot to track using its unified motion-force controller, which allows doing force control in zero or more Cartesian axes and motion control in the rest axes. The robot's internal motion generator will smoothen the discrete commands. More...
 
void SetCartesianImpedance (const std::array< double, kCartDoF > &K_x, const std::array< double, kCartDoF > &Z_x={0.7, 0.7, 0.7, 0.7, 0.7, 0.7})
 [Blocking] Set impedance properties of the robot's Cartesian motion controller used in the Cartesian motion-force control modes. More...
 
void SetMaxContactWrench (const std::array< double, kCartDoF > &max_wrench)
 [Blocking] Set maximum contact wrench for the motion control part of the Cartesian motion-force control modes. The controller will regulate its output to maintain contact wrench (force and moment) with the environment under the set values. More...
 
void SetNullSpacePosture (const std::vector< double > &ref_positions)
 [Blocking] Set reference joint positions for the null-space posture control module used in the Cartesian motion-force control modes. More...
 
void SetNullSpaceObjectives (double linear_manipulability=0.0, double angular_manipulability=0.0, double ref_positions_tracking=0.5)
 [Blocking] Set weights of the three optimization objectives while computing the robot's null-space posture. Change the weights to optimize robot performance for different use cases. More...
 
void SetForceControlAxis (const std::array< bool, kCartDoF > &enabled_axes, const std::array< double, kCartDoF/2 > &max_linear_vel={1.0, 1.0, 1.0})
 [Blocking] Set Cartesian axes to enable force control while in the Cartesian motion-force control modes. Axes not enabled for force control will be motion-controlled. More...
 
void SetForceControlFrame (CoordType root_coord, const std::array< double, kPoseSize > &T_in_root={0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0})
 [Blocking] Set reference frame for force control while in the Cartesian motion-force control modes. The force control frame is defined by specifying its transformation with regard to the root coordinate. More...
 
void SetPassiveForceControl (bool is_enabled)
 [Blocking] Enable or disable passive force control for the Cartesian motion-force control modes. When enabled, an open-loop force controller will be used to feed forward the target wrench, i.e. passive force control. When disabled, a closed-loop force controller will be used to track the target wrench, i.e. active force control. More...
 
void SetDigitalOutputs (const std::vector< unsigned int > &port_idx, const std::vector< bool > &values)
 [Blocking] Set one or more digital output port(s) on the control box. More...
 
void WriteDigitalOutput (const std::vector< unsigned int > &port_idx, const std::vector< bool > &values)
 
const std::array< bool, kIOPorts > digital_inputs ()
 [Non-blocking] Current reading of all digital input ports on the control box. More...
 
const std::array< bool, kIOPorts > ReadDigitalInput ()
 

Friends

class Device
 
class FileIO
 
class Gripper
 
class Model
 
class Tool
 
class WorkCoord
 

Detailed Description

Main interface with the robot, containing several function categories and background services.

Definition at line 24 of file robot.hpp.

Constructor & Destructor Documentation

◆ Robot()

flexiv::rdk::Robot::Robot ( const std::string &  robot_sn)

[Blocking] Create an instance as the main robot control interface. RDK services will initialize and connection with the robot will be established.

Parameters
[in]robot_snSerial number of the robot to connect. The accepted formats are: "Rizon 4s-123456" and "Rizon4s-123456".
Exceptions
std::invalid_argumentif the format of [robot_sn] is invalid.
std::runtime_errorif the initialization sequence failed.
std::logic_errorif the connected robot does not have a valid RDK license; or this RDK library version is incompatible with the connected robot; or model of the connected robot is not supported.
Warning
This constructor blocks until the initialization sequence is successfully finished and connection with the robot is established.

Member Function Documentation

◆ Brake()

void flexiv::rdk::Robot::Brake ( bool  engage)

[Blocking] Force robot brakes to engage or release during normal operation. Restrictions apply, see warning.

Parameters
[in]engageTrue: engage brakes; false: release brakes.
Exceptions
std::logic_errorif the connected robot is not a medical one or the robot is moving.
std::runtime_errorif failed to engage/release the brakes.
Note
This function blocks until the brakes are successfully engaged/released.
Warning
This function is accessible only if a) the connected robot is a medical one AND b) the robot is not moving.

◆ busy()

bool flexiv::rdk::Robot::busy ( ) const

[Non-blocking] Whether the robot is currently executing a task. This includes any user commanded operations that requires the robot to execute. For example, plans, primitives, Cartesian and joint motions, etc.

Returns
True: busy; false: idle.
Warning
Some exceptions exist for primitives, see ExecutePrimitive() for more details.

◆ ClearFault()

bool flexiv::rdk::Robot::ClearFault ( unsigned int  timeout_sec = 30)

[Blocking] Try to clear minor or critical fault of the robot without a power cycle.

Parameters
[in]timeout_secMaximum time in seconds to wait for the fault to be successfully cleared. Normally, a minor fault should take no more than 3 seconds to clear, and a critical fault should take no more than 30 seconds to clear.
Returns
True: successfully cleared fault; false: failed to clear fault.
Exceptions
std::runtime_errorif failed to deliver the request to the connected robot.
Note
This function blocks until the fault is successfully cleared or [timeout_sec] has elapsed.
Warning
Clearing a critical fault through this function without a power cycle requires a dedicated device, which may not be installed in older robot models.

◆ connected()

bool flexiv::rdk::Robot::connected ( ) const

[Non-blocking] Whether the connection with the robot is established.

Returns
True: connected; false: disconnected.

◆ digital_inputs()

const std::array<bool, kIOPorts> flexiv::rdk::Robot::digital_inputs ( )

[Non-blocking] Current reading of all digital input ports on the control box.

Returns
A boolean array whose index corresponds to that of the digital input ports. True: port high; false: port low.

◆ Enable()

void flexiv::rdk::Robot::Enable ( )

[Blocking] Enable the robot, if E-stop is released and there's no fault, the robot will release brakes, and becomes operational a few seconds later.

Exceptions
std::logic_errorif the robot is not connected.
std::runtime_errorif failed to deliver the request to the connected robot.
Note
This function blocks until the request is successfully delivered.

◆ enabling_button_pressed()

bool flexiv::rdk::Robot::enabling_button_pressed ( ) const

[Non-blocking] Whether the enabling button is pressed.

Returns
True: pressed; false: released.

◆ estop_released()

bool flexiv::rdk::Robot::estop_released ( ) const

[Non-blocking] Whether the emergency stop is released.

Returns
True: released; false: pressed.

◆ ExecutePlan() [1/2]

void flexiv::rdk::Robot::ExecutePlan ( const std::string &  name,
bool  continue_exec = false,
bool  block_until_started = true 
)

[Blocking] Execute a plan by specifying its name.

Parameters
[in]nameName of the plan to execute, can be obtained via plan_list().
[in]continue_execWhether to continue executing the plan when the RDK program is closed or the connection is lost.
[in]block_until_startedWhether to wait for the commanded plan to finish loading and start execution before the function returns. Depending on the amount of computation needed to get the plan ready, the loading process typically takes no more than 200 ms.
Exceptions
std::logic_errorif robot is not in an applicable control mode.
std::runtime_errorif failed to deliver the request to the connected robot.
Note
Applicable control modes: NRT_PLAN_EXECUTION.
This function blocks until the request is successfully delivered if [block_until_started] is disabled, or until the plan has started execution if [block_until_started] is enabled.
busy() can be used to check if the plan has finished.

◆ ExecutePlan() [2/2]

void flexiv::rdk::Robot::ExecutePlan ( unsigned int  index,
bool  continue_exec = false,
bool  block_until_started = true 
)

[Blocking] Execute a plan by specifying its index.

Parameters
[in]indexIndex of the plan to execute, can be obtained via plan_list().
[in]continue_execWhether to continue executing the plan when the RDK program is closed or the connection is lost.
[in]block_until_startedWhether to wait for the commanded plan to finish loading and start execution before the function returns. Depending on the amount of computation needed to get the plan ready, the loading process typically takes no more than 200 ms.
Exceptions
std::invalid_argumentif [index] is outside the valid range.
std::logic_errorif robot is not in an applicable control mode.
std::runtime_errorif failed to deliver the request to the connected robot.
Note
Applicable control modes: NRT_PLAN_EXECUTION.
This function blocks until the request is successfully delivered if [block_until_started] is disabled, or until the plan has started execution if [block_until_started] is enabled.
busy() can be used to check if the plan has finished.

◆ ExecutePrimitive()

void flexiv::rdk::Robot::ExecutePrimitive ( const std::string &  primitive_name,
const std::map< std::string, FlexivDataTypes > &  input_params,
bool  block_until_started = true 
)

[Blocking] Execute a primitive by specifying its name and parameters, which can be found in the Flexiv Primitives documentation.

Parameters
[in]primitive_namePrimitive name. For example, "Home", "MoveL", "ZeroFTSensor", etc.
[in]input_paramsA map of {input_parameter_name, input_parameter_value(s)}. Use int 1 and 0 to represent booleans. For example, {{"target", rdk::Coord({0.65, -0.3, 0.2}, {180, 0, 180}, {"WORLD", "WORLD_ORIGIN"})}, {"vel", 0.6}, {"zoneRadius", "Z50"}}.
[in]block_until_startedWhether to wait for the commanded primitive to finish loading and start execution before the function returns. Depending on the amount of computation needed to get the primitive ready, the loading process typically takes no more than 200 ms.
Exceptions
std::length_errorif [input_params] is too long to transmit in one request.
std::logic_errorif robot is not in an applicable control mode.
std::runtime_errorif failed to deliver the request to the connected robot.
Note
Applicable control modes: NRT_PRIMITIVE_EXECUTION.
This function blocks until the request is successfully delivered if [block_until_started] is disabled, or until the primitive has started execution if [block_until_started] is enabled.
Warning
The primitive input parameters may not use SI units, please refer to the Flexiv Primitives documentation for exact unit definition.
Most primitives won't exit by themselves and require users to explicitly trigger transitions based on specific primitive states. In such case, busy() will stay true even if it seems everything is done for that primitive.

◆ fault()

bool flexiv::rdk::Robot::fault ( ) const

[Non-blocking] Whether the robot is in fault state.

Returns
True: robot has fault; false: robot normal.

◆ global_variables()

std::map<std::string, FlexivDataTypes> flexiv::rdk::Robot::global_variables ( ) const

[Blocking] Existing global variables and their current values.

Returns
A map of {global_var_name, global_var_value(s)}. Booleans are represented by int 1 and 0. For example, {{"camera_offset", {0.1, -0.2, 0.3}}, {"start_plan", 1}}.
Exceptions
std::runtime_errorif failed to get a reply from the connected robot.
Note
This function blocks until a reply is received.
See also
SetGlobalVariables().

◆ info()

const RobotInfo flexiv::rdk::Robot::info ( ) const

[Non-blocking] General information about the connected robot.

Returns
RobotInfo value copy.

◆ mode()

Mode flexiv::rdk::Robot::mode ( ) const

[Non-blocking] Current control mode of the robot.

Returns
flexiv::rdk::Mode enum.

◆ mu_log()

const std::vector<std::string> flexiv::rdk::Robot::mu_log ( ) const

[Non-blocking] Get multilingual log messages of the connected robot.

Returns
Robot log messages stored since the last successful instantiation of this class. Each element in the string list corresponds to one message with timestamp and log level added. New message is pushed to the back of the vector.
Note
Possible log level tags are: [info], [warning], [error], and [critical].
Warning
Messages before the last successful instantiation of this class are not available.

◆ operational()

bool flexiv::rdk::Robot::operational ( bool  verbose = true) const

[Non-blocking] Whether the robot is ready to be operated, which requires the following conditions to be met: enabled, brakes fully released, in auto mode, no fault, and not in reduced state.

Parameters
[in]verboseWhether to print warning message indicating why the robot is not operational when this function returns false.
Returns
True: operational (operational_status() == READY); false: not operational.
Warning
The robot won't execute any user command until it's ready to be operated.

◆ operational_status()

OperationalStatus flexiv::rdk::Robot::operational_status ( ) const

[Non-blocking] Current operational status of the robot.

Returns
OperationalStatus enum.

◆ PausePlan()

void flexiv::rdk::Robot::PausePlan ( bool  pause)

[Blocking] Pause or resume the execution of the current plan.

Parameters
[in]pauseTrue: pause plan; false: resume plan.
Exceptions
std::logic_errorif robot is not in an applicable control mode.
std::runtime_errorif failed to deliver the request to the connected robot.
Note
Applicable control modes: NRT_PLAN_EXECUTION.
This function blocks until the request is successfully delivered.
Warning
Internal plans (not created by user) cannot be resumed due to safety concerns.

◆ plan_info()

const PlanInfo flexiv::rdk::Robot::plan_info ( ) const

[Blocking] Get detailed information about the currently executing plan. Contains information like plan name, primitive name, node name, node path, node path time period, etc.

Returns
PlanInfo data struct.
Exceptions
std::logic_errorif robot is not in an applicable control mode.
std::runtime_errorif failed to get a reply from the connected robot.
Note
Applicable control modes: NRT_PLAN_EXECUTION.
This function blocks until a reply is received.

◆ plan_list()

const std::vector<std::string> flexiv::rdk::Robot::plan_list ( ) const

[Blocking] Get a list of all available plans.

Returns
Available plans in the format of a string list.
Exceptions
std::runtime_errorif failed to get a reply from the connected robot.
Note
This function blocks until a reply is received.

◆ primitive_states()

std::map<std::string, FlexivDataTypes> flexiv::rdk::Robot::primitive_states ( ) const

[Blocking] State parameters of the executing primitive and their current values.

Returns
A map of {pt_state_name, pt_state_value(s)}. Booleans are represented by int 1 and 0. For example, {{"reachedTarget", 1}, {"timePeriod", 5.6}, {"forceOffset", {0.1, 0.2, -1.3}}}.
Exceptions
std::runtime_errorif failed to get a reply from the connected robot.
Note
This function blocks until a reply is received.

◆ recovery()

bool flexiv::rdk::Robot::recovery ( ) const

[Non-blocking] Whether the robot is in recovery state.

Returns
True: in recovery state; false: not in recovery state.
Note
Use RunAutoRecovery() to execute automatic recovery operation.
Recovery state
The robot will enter recovery state if it needs to recover from joint position limit violation (a critical system fault that requires a recovery operation, during which the joints that moved outside the allowed position range will need to move very slowly back into the allowed range). Please refer to the robot user manual for more details about system recovery state.

◆ reduced()

bool flexiv::rdk::Robot::reduced ( ) const

[Non-blocking] Whether the robot is in reduced state.

Returns
True: in reduced state; false: not in reduced state.
Reduced state
The robot will enter reduced state if a) the safety input for reduced state goes low or b) robot TCP passes through any safety plane. The safety limits are lowered in reduced state compared to normal state. Specific values for the safety limits can be configured in Flexiv Elements under Settings -> Safety Configuration. Please refer to the robot user manual for more details about system reduced state.

◆ RunAutoRecovery()

void flexiv::rdk::Robot::RunAutoRecovery ( )

[Blocking] Run automatic recovery to bring joints that are outside the allowed position range back into allowed range.

Exceptions
std::runtime_errorif failed to enter automatic recovery mode.
Note
Refer to user manual for more details.
This function blocks until the automatic recovery process is finished.
See also
recovery().

◆ SendCartesianMotionForce()

void flexiv::rdk::Robot::SendCartesianMotionForce ( const std::array< double, kPoseSize > &  pose,
const std::array< double, kCartDoF > &  wrench = {},
double  max_linear_vel = 0.5,
double  max_angular_vel = 1.0,
double  max_linear_acc = 2.0,
double  max_angular_acc = 5.0 
)

[Non-blocking] Discretely send Cartesian motion and/or force command for the robot to track using its unified motion-force controller, which allows doing force control in zero or more Cartesian axes and motion control in the rest axes. The robot's internal motion generator will smoothen the discrete commands.

Parameters
[in]poseTarget TCP pose in world frame: \( {^{O}T_{TCP}}_{d} \in \mathbb{R}^{7 \times 1} \). Consists of \( \mathbb{R}^{3 \times 1} \) position and \( \mathbb{R}^{4 \times 1} \) quaternion: \( [x, y, z, q_w, q_x, q_y, q_z]^T \). Unit: \( [m]:[] \).
[in]wrenchTarget TCP wrench (force and moment) in the force control reference frame (configured by SetForceControlFrame()): \( ^{0}F_d \in \mathbb{R}^{6 \times 1} \). The robot will track the target wrench using an explicit force controller. Consists of \( \mathbb{R}^{3 \times 1} \) force and \( \mathbb{R}^{3 \times 1} \) moment: \( [f_x, f_y, f_z, m_x, m_y, m_z]^T \). Unit: \( [N]:[Nm] \).
[in]max_linear_velMaximum Cartesian linear velocity when moving to the target pose. A safe value is provided as default. Unit: \( [m/s] \).
[in]max_angular_velMaximum Cartesian angular velocity when moving to the target pose. A safe value is provided as default. Unit: \( [rad/s] \).
[in]max_linear_accMaximum Cartesian linear acceleration when moving to the target pose. A safe value is provided as default. Unit: \( [m/s^2] \).
[in]max_angular_accMaximum Cartesian angular acceleration when moving to the target pose. A safe value is provided as default. Unit: \( [rad/s^2] \).
Exceptions
std::invalid_argumentif any of the last 4 input parameters is negative.
std::logic_errorif robot is not in an applicable control mode.
Note
Applicable control modes: NRT_CARTESIAN_MOTION_FORCE.
Warning
Same as Flexiv Elements, the target wrench is expressed as wrench sensed at TCP instead of wrench exerted by TCP. E.g. commanding f_z = +5 N will make the end-effector move towards -Z direction, so that upon contact, the sensed force will be +5 N.
How to achieve pure motion control?
Use SetForceControlAxis() to disable force control for all Cartesian axes to achieve pure motion control. This function does pure motion control by default.
How to achieve pure force control?
Use SetForceControlAxis() to enable force control for all Cartesian axes to achieve pure force control, active or passive.
How to achieve unified motion-force control?
Use SetForceControlAxis() to enable force control for one or more Cartesian axes and leave the rest axes motion-controlled, then provide target pose for the motion-controlled axes and target wrench for the force-controlled axes.
See also
SetCartesianImpedance(), SetMaxContactWrench(), SetNullSpacePosture(), SetForceControlAxis(), SetForceControlFrame(), SetPassiveForceControl().

◆ SendJointPosition()

void flexiv::rdk::Robot::SendJointPosition ( const std::vector< double > &  positions,
const std::vector< double > &  velocities,
const std::vector< double > &  accelerations,
const std::vector< double > &  max_vel,
const std::vector< double > &  max_acc 
)

[Non-blocking] Discretely send joint position, velocity, and acceleration command to the robot. The robot's internal motion generator will smoothen the discrete commands, which are tracked by either the joint impedance controller or the joint position controller, depending on the control mode.

Parameters
[in]positionsTarget joint positions: \( q_d \in \mathbb{R}^{n \times 1} \). Unit: \( [rad] \).
[in]velocitiesTarget joint velocities: \( \dot{q}_d \in \mathbb{R}^{n \times 1} \). Each joint will maintain this amount of velocity when it reaches the target position. Unit: \( [rad/s] \).
[in]accelerationsTarget joint accelerations: \( \ddot{q}_d \in \mathbb{R}^{n \times 1} \). Each joint will maintain this amount of acceleration when it reaches the target position. Unit: \( [rad/s^2] \).
[in]max_velMaximum joint velocities for the planned trajectory: \( \dot{q}_{max} \in \mathbb{R}^{n \times 1} \). Unit: \( [rad/s] \).
[in]max_accMaximum joint accelerations for the planned trajectory: \( \ddot{q}_{max} \in \mathbb{R}^{n \times 1} \). Unit: \( [rad/s^2] \).
Exceptions
std::invalid_argumentif size of any input vector does not match robot DoF.
std::logic_errorif robot is not in an applicable control mode.
Note
Applicable control modes: NRT_JOINT_IMPEDANCE, NRT_JOINT_POSITION.
Warning
Calling this function a second time while the motion from the previous call is still ongoing will trigger an online re-planning of the joint trajectory, such that the previous command is aborted and the new command starts to execute.
See also
SetJointImpedance().

◆ SetBreakpointMode()

void flexiv::rdk::Robot::SetBreakpointMode ( bool  is_enabled)

[Blocking] Enable or disable the breakpoint mode during plan execution. When enabled, the currently executing plan will pause at the pre-defined breakpoints. Use StepBreakpoint() to continue the execution and pause at the next breakpoint.

Parameters
[in]is_enabledTrue: enable; false: disable. By default, breakpoint mode is disabled.
Exceptions
std::logic_errorif robot is not in an applicable control mode.
std::runtime_errorif failed to deliver the request to the connected robot.
Note
Applicable control modes: NRT_PLAN_EXECUTION.
This function blocks until the request is successfully delivered.

◆ SetCartesianImpedance()

void flexiv::rdk::Robot::SetCartesianImpedance ( const std::array< double, kCartDoF > &  K_x,
const std::array< double, kCartDoF > &  Z_x = {0.7, 0.7, 0.7, 0.7, 0.7, 0.7} 
)

[Blocking] Set impedance properties of the robot's Cartesian motion controller used in the Cartesian motion-force control modes.

Parameters
[in]K_xCartesian motion stiffness: \( K_x \in \mathbb{R}^{6 \times 1} \). Setting motion stiffness of a motion-controlled Cartesian axis to 0 will make this axis free-floating. Consists of \( \mathbb{R}^{3 \times 1} \) linear stiffness and \( \mathbb{R}^{3 \times 1} \) angular stiffness: \( [k_x, k_y, k_z, k_{Rx}, k_{Ry}, k_{Rz}]^T \). Valid range: [0, RobotInfo::K_x_nom]. Unit: \( [N/m]:[Nm/rad] \).
[in]Z_xCartesian motion damping ratio: \( Z_x \in \mathbb{R}^{6 \times 1} \). Consists of \( \mathbb{R}^{3 \times 1} \) linear damping ratio and \( \mathbb{R}^{3 \times 1} \) angular damping ratio: \( [\zeta_x, \zeta_y, \zeta_z, \zeta_{Rx}, \zeta_{Ry}, \zeta_{Rz}]^T \). Valid range: [0.3, 0.8]. The nominal (safe) value is provided as default.
Exceptions
std::invalid_argumentif [K_x] or [Z_x] contains any value outside the valid range.
std::logic_errorif robot is not in an applicable control mode.
Note
Applicable control modes: RT_CARTESIAN_MOTION_FORCE, NRT_CARTESIAN_MOTION_FORCE.
This function blocks until the request is successfully delivered.
Warning
Changing damping ratio [Z_x] to a non-nominal value may lead to performance and stability issues, please use with caution.

◆ SetDigitalOutputs()

void flexiv::rdk::Robot::SetDigitalOutputs ( const std::vector< unsigned int > &  port_idx,
const std::vector< bool > &  values 
)

[Blocking] Set one or more digital output port(s) on the control box.

Parameters
[in]port_idxIndex of port(s) to set, can be a single port or multiple ports. E.g. {0, 5, 7, 15} or {1, 3, 10} or {8}. Valid range of the index number is [0–15].
[in]valuesCorresponding values to set to the specified ports. True: set port high, false: set port low. Vector size must match the size of port_idx.
Exceptions
std::invalid_argumentif [port_idx] contains any index number outside the valid range.
std::length_errorif the two input vectors have different sizes.
std::runtime_errorif failed to deliver the request to the connected robot.
Note
This function blocks until the request is successfully delivered.

◆ SetForceControlAxis()

void flexiv::rdk::Robot::SetForceControlAxis ( const std::array< bool, kCartDoF > &  enabled_axes,
const std::array< double, kCartDoF/2 > &  max_linear_vel = {1.0, 1.0, 1.0} 
)

[Blocking] Set Cartesian axes to enable force control while in the Cartesian motion-force control modes. Axes not enabled for force control will be motion-controlled.

Parameters
[in]enabled_axesFlags to enable/disable force control for certain Cartesian axes in the force control reference frame (configured by SetForceControlFrame()). The axis order is \( [X, Y, Z, Rx, Ry, Rz] \).
[in]max_linear_velFor linear Cartesian axes that are enabled for force control, limit the moving velocity to these values as a protection mechanism in case of contact loss. The axis order is \( [X, Y, Z] \). Valid range: [0.005, 2.0]. Unit: \( [m/s] \).
Exceptions
std::invalid_argumentif [max_linear_vel] contains any value outside the valid range.
std::logic_errorif robot is not in an applicable control mode.
std::runtime_errorif failed to deliver the request to the connected robot.
Note
Applicable control modes: RT_CARTESIAN_MOTION_FORCE, NRT_CARTESIAN_MOTION_FORCE.
This function blocks until the request is successfully delivered.
If not set, force control is disabled for all Cartesian axes by default.
Warning
The maximum linear velocity protection for force control axes is only effective under active force control (i.e. passive force control disabled), see SetPassiveForceControl().

◆ SetForceControlFrame()

void flexiv::rdk::Robot::SetForceControlFrame ( CoordType  root_coord,
const std::array< double, kPoseSize > &  T_in_root = {0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0} 
)

[Blocking] Set reference frame for force control while in the Cartesian motion-force control modes. The force control frame is defined by specifying its transformation with regard to the root coordinate.

Parameters
[in]root_coordReference coordinate of [T_in_root].
[in]T_in_rootTransformation from [root_coord] to the user-defined force control frame: \( ^{root}T_{force} \in \mathbb{R}^{7 \times 1} \). Consists of \( \mathbb{R}^{3 \times 1} \) position and \( \mathbb{R}^{4 \times 1} \) quaternion: \( [x, y, z, q_w, q_x, q_y, q_z]^T \). Unit: \( [m]:[] \). If root coordinate is a fixed one (e.g. WORLD), then the force control frame will also be fixed; if root coordinate is a moving one (e.g. TCP), then the force control frame will also be moving with the root coordinate. An identity transformation is provided as default.
Exceptions
std::logic_errorif robot is not in an applicable control mode.
std::runtime_errorif failed to deliver the request to the connected robot.
Note
Applicable control modes: RT_CARTESIAN_MOTION_FORCE, NRT_CARTESIAN_MOTION_FORCE.
This function blocks until the request is successfully delivered.
If not set, the robot will use WORLD origin as the force control frame by default.
Force control frame
In Cartesian motion-force control modes, the reference frame of motion control is always the world frame, but the reference frame of force control can be an arbitrary one. While the world frame is the commonly used global coordinate, the current TCP frame is a dynamic local coordinate whose transformation with regard to the world frame changes as the robot TCP moves. When using world frame with no transformation as the force control frame, the force-controlled axes and motion-controlled axes are guaranteed to be orthogonal. Otherwise, the force-controlled axes and motion-controlled axes are NOT guaranteed to be orthogonal because different reference frames are used. In this case, it's recommended but not required to set the target pose such that the actual robot motion direction(s) are orthogonal to force direction(s). If they are not orthogonal, the motion control's vector component(s) in the force direction(s) will be eliminated.

◆ SetGlobalVariables()

void flexiv::rdk::Robot::SetGlobalVariables ( const std::map< std::string, FlexivDataTypes > &  global_vars)

[Blocking] Set values to global variables that already exist in the robot.

Parameters
[in]global_varsA map of {global_var_name, global_var_value(s)}. Use int 1 and 0 to represent booleans. For example, {{"camera_offset", {0.1, -0.2, 0.3}}, {"start_plan", 1}}.
Exceptions
std::length_errorif [global_vars] is empty or too long to transmit in one request.
std::logic_errorif any of the specified global variables does not exist.
std::runtime_errorif failed to deliver the request to the connected robot.
Note
This function blocks until the global variables are successfully set.
Warning
The specified global variables need to be created first using Flexiv Elements.
See also
global_variables().

◆ SetJointImpedance()

void flexiv::rdk::Robot::SetJointImpedance ( const std::vector< double > &  K_q,
const std::vector< double > &  Z_q = {0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7} 
)

[Blocking] Set impedance properties of the robot's joint motion controller used in the joint impedance control modes.

Parameters
[in]K_qJoint motion stiffness: \( K_q \in \mathbb{R}^{n \times 1} \). Setting motion stiffness of a joint axis to 0 will make this axis free-floating. Valid range: [0, RobotInfo::K_q_nom]. Unit: \( [Nm/rad] \).
[in]Z_qJoint motion damping ratio: \( Z_q \in \mathbb{R}^{n \times 1} \). Valid range: [0.3, 0.8]. The nominal (safe) value is provided as default.
Exceptions
std::invalid_argumentif [K_q] or [Z_q] contains any value outside the valid range or size of any input vector does not match robot DoF.
std::logic_errorif robot is not in an applicable control mode.
Note
Applicable control modes: RT_JOINT_IMPEDANCE, NRT_JOINT_IMPEDANCE.
This function blocks until the request is successfully delivered.
Warning
Changing damping ratio [Z_q] to a non-nominal value may lead to performance and stability issues, please use with caution.

◆ SetMaxContactWrench()

void flexiv::rdk::Robot::SetMaxContactWrench ( const std::array< double, kCartDoF > &  max_wrench)

[Blocking] Set maximum contact wrench for the motion control part of the Cartesian motion-force control modes. The controller will regulate its output to maintain contact wrench (force and moment) with the environment under the set values.

Parameters
[in]max_wrenchMaximum contact wrench (force and moment): \( F_max \in \mathbb{R}^{6 \times 1} \). Consists of \( \mathbb{R}^{3 \times 1} \) maximum force and \( \mathbb{R}^{3 \times 1} \) maximum moment: \( [f_x, f_y, f_z, m_x, m_y, m_z]^T \). Unit: \( [N]:[Nm] \).
Exceptions
std::invalid_argumentif [max_wrench] contains any negative value.
std::logic_errorif robot is not in an applicable control mode.
Note
The maximum contact wrench regulation only applies to the motion control part.
Applicable control modes: RT_CARTESIAN_MOTION_FORCE, NRT_CARTESIAN_MOTION_FORCE.
This function blocks until the request is successfully delivered.
Warning
The maximum contact wrench regulation cannot be enabled if any of the rotational Cartesian axes is enabled for moment control.

◆ SetNullSpaceObjectives()

void flexiv::rdk::Robot::SetNullSpaceObjectives ( double  linear_manipulability = 0.0,
double  angular_manipulability = 0.0,
double  ref_positions_tracking = 0.5 
)

[Blocking] Set weights of the three optimization objectives while computing the robot's null-space posture. Change the weights to optimize robot performance for different use cases.

Parameters
[in]linear_manipulabilityIncrease this weight to improve the robot's capability to translate freely in Cartesian space, i.e. a broader range of potential translation movements. Valid range: [0.0, 1.0].
[in]angular_manipulabilityIncrease this weight to improve the robot's capability to rotate freely in Cartesian space, i.e. a broader range of potential rotation movements. Valid range: [0.0, 1.0].
[in]ref_positions_trackingIncrease this weight to make the robot track closer to the reference joint positions specified using SetNullSpacePosture(). Valid range: [0.1, 1.0].
Exceptions
std::invalid_argumentif any of the input parameters is outside its valid range.
std::logic_errorif robot is not in an applicable control mode.
std::runtime_errorif failed to deliver the request to the connected robot.
Note
The default value is provided for each parameter.
Applicable control modes: RT_CARTESIAN_MOTION_FORCE, NRT_CARTESIAN_MOTION_FORCE.
This function blocks until the request is successfully delivered.
Warning
The optimization weights will be automatically reset to the provided default values upon re-entering the applicable control modes.

◆ SetNullSpacePosture()

void flexiv::rdk::Robot::SetNullSpacePosture ( const std::vector< double > &  ref_positions)

[Blocking] Set reference joint positions for the null-space posture control module used in the Cartesian motion-force control modes.

Parameters
[in]ref_positionsReference joint positions for the null-space posture control: \( q_{ns} \in \mathbb{R}^{n \times 1} \). Valid range: [RobotInfo::q_min, RobotInfo::q_max]. Unit: \( [rad] \).
Exceptions
std::invalid_argumentif [ref_positions] contains any value outside the valid range or size of any input vector does not match robot DoF.
std::logic_errorif robot is not in an applicable control mode.
Note
Applicable control modes: RT_CARTESIAN_MOTION_FORCE, NRT_CARTESIAN_MOTION_FORCE.
This function blocks until the request is successfully delivered.
Warning
The reference joint positions will be automatically reset to the robot's current joint positions upon re-entering the applicable control modes.
Null-space posture control
Similar to human arm, a robotic arm with redundant joint-space degree(s) of freedom (DoF > 6) can change its overall posture without affecting the ongoing primary task. This is achieved through a technique called "null-space control". After the reference joint positions of a desired robot posture are set using this function, the robot's null-space control module will try to pull the arm as close to this posture as possible without affecting the primary Cartesian motion-force control task.

◆ SetPassiveForceControl()

void flexiv::rdk::Robot::SetPassiveForceControl ( bool  is_enabled)

[Blocking] Enable or disable passive force control for the Cartesian motion-force control modes. When enabled, an open-loop force controller will be used to feed forward the target wrench, i.e. passive force control. When disabled, a closed-loop force controller will be used to track the target wrench, i.e. active force control.

Parameters
[in]is_enabledTrue: enable; false: disable. By default, passive force control is disabled and active force control is used.
Exceptions
std::logic_errorif robot is not in an applicable control mode.
std::runtime_errorif failed to deliver the request to the connected robot.
Note
Applicable control modes: IDLE.
This function blocks until the request is successfully delivered.
If not set, the passive force control is disabled by default.
Difference between active and passive force control
Active force control uses a feedback loop to reduce the error between target wrench and measured wrench. This method results in better force tracking performance, but at the cost of additional Cartesian damping which could potentially decrease motion tracking performance. On the other hand, passive force control simply feeds forward the target wrench. This methods results in worse force tracking performance, but is more robust and does not introduce additional Cartesian damping. The choice of active or passive force control depends on the actual application.

◆ SetVelocityScale()

void flexiv::rdk::Robot::SetVelocityScale ( unsigned int  velocity_scale)

[Blocking] Set overall velocity scale for robot motions during plan and primitive execution.

Parameters
[in]velocity_scalePercentage scale to adjust the overall velocity of robot motions. Valid range: [0, 100]. Setting to 100 means to move with 100% of specified motion velocity, and 0 means not moving at all.
Exceptions
std::invalid_argumentif [velocity_scale] is outside the valid range.
std::logic_errorif robot is not in an applicable control mode.
std::runtime_errorif failed to deliver the request to the connected robot.
Note
Applicable control modes: NRT_PLAN_EXECUTION, NRT_PRIMITIVE_EXECUTION.
This function blocks until the request is successfully delivered.

◆ states()

const RobotStates flexiv::rdk::Robot::states ( ) const

[Non-blocking] Current states data of the robot.

Returns
RobotStates value copy.
Note
Real-time (RT).

◆ StepBreakpoint()

void flexiv::rdk::Robot::StepBreakpoint ( )

[Blocking] If breakpoint mode is enabled, step to the next breakpoint. The plan execution will continue and pause at the next breakpoint.

Exceptions
std::logic_errorif robot is not in an applicable control mode.
std::runtime_errorif failed to deliver the request to the connected robot.
Note
Applicable control modes: NRT_PLAN_EXECUTION.
This function blocks until the request is successfully delivered.
Use PlanInfo::waiting_for_step to check if the plan is currently waiting for user signal to step the breakpoint.

◆ Stop()

void flexiv::rdk::Robot::Stop ( )

[Blocking] Stop the robot and transit robot mode to IDLE.

Exceptions
std::runtime_errorif failed to stop the robot.
Note
This function blocks until the robot comes to a complete stop.

◆ stopped()

bool flexiv::rdk::Robot::stopped ( ) const

[Non-blocking] Whether the robot has come to a complete stop.

Returns
True: stopped; false: still moving.

◆ StreamCartesianMotionForce()

void flexiv::rdk::Robot::StreamCartesianMotionForce ( const std::array< double, kPoseSize > &  pose,
const std::array< double, kCartDoF > &  wrench = {},
const std::array< double, kCartDoF > &  velocity = {},
const std::array< double, kCartDoF > &  acceleration = {} 
)

[Non-blocking] Continuously stream Cartesian motion and/or force command for the robot to track using its unified motion-force controller, which allows doing force control in zero or more Cartesian axes and motion control in the rest axes.

Parameters
[in]poseTarget TCP pose in world frame: \( {^{O}T_{TCP}}_{d} \in \mathbb{R}^{7 \times 1} \). Consists of \( \mathbb{R}^{3 \times 1} \) position and \( \mathbb{R}^{4 \times 1} \) quaternion: \( [x, y, z, q_w, q_x, q_y, q_z]^T \). Unit: \( [m]:[] \).
[in]wrenchTarget TCP wrench (force and moment) in the force control reference frame (configured by SetForceControlFrame()): \( ^{0}F_d \in \mathbb{R}^{6 \times 1} \). The robot will track the target wrench using an explicit force controller. Consists of \( \mathbb{R}^{3 \times 1} \) force and \( \mathbb{R}^{3 \times 1} \) moment: \( [f_x, f_y, f_z, m_x, m_y, m_z]^T \). Unit: \( [N]:[Nm] \).
[in]velocityTarget TCP velocity (linear and angular) in world frame: \( ^{0}\dot{x}_d \in \mathbb{R}^{6 \times 1} \). Providing properly calculated target velocity can improve the robot's overall tracking performance at the cost of reduced robustness. Leaving this input 0 can maximize robustness at the cost of reduced tracking performance. Consists of \( \mathbb{R}^{3 \times 1} \) linear and \( \mathbb{R}^{3 \times 1} \) angular velocity. Unit: \( [m/s]:[rad/s] \).
[in]accelerationTarget TCP acceleration (linear and angular) in world frame: \( ^{0}\ddot{x}_d \in \mathbb{R}^{6 \times 1} \). Feeding forward target acceleration can improve the robot's tracking performance for highly dynamic motions, but it's also okay to leave this input 0. Consists of \( \mathbb{R}^{3 \times 1} \) linear and \( \mathbb{R}^{3 \times 1} \) angular acceleration. Unit: \( [m/s^2]:[rad/s^2] \).
Exceptions
std::logic_errorif robot is not in an applicable control mode.
std::runtime_errorif number of timeliness failures has reached limit.
Note
Applicable control modes: RT_CARTESIAN_MOTION_FORCE.
Real-time (RT).
Warning
Always stream smooth and continuous motion commands to avoid sudden movements. The force commands don't need to be continuous.
Same as Flexiv Elements, the target wrench is expressed as wrench sensed at TCP instead of wrench exerted by TCP. E.g. commanding f_z = +5 N will make the end-effector move towards -Z direction, so that upon contact, the sensed force will be +5 N.
How to achieve pure motion control?
Use SetForceControlAxis() to disable force control for all Cartesian axes to achieve pure motion control. This function does pure motion control by default.
How to achieve pure force control?
Use SetForceControlAxis() to enable force control for all Cartesian axes to achieve pure force control, active or passive.
How to achieve unified motion-force control?
Use SetForceControlAxis() to enable force control for one or more Cartesian axes and leave the rest axes motion-controlled, then provide target pose for the motion-controlled axes and target wrench for the force-controlled axes.
See also
SetCartesianImpedance(), SetMaxContactWrench(), SetNullSpacePosture(), SetForceControlAxis(), SetForceControlFrame(), SetPassiveForceControl().

◆ StreamJointPosition()

void flexiv::rdk::Robot::StreamJointPosition ( const std::vector< double > &  positions,
const std::vector< double > &  velocities,
const std::vector< double > &  accelerations 
)

[Non-blocking] Continuously stream joint position, velocity, and acceleration command to the robot. The commands are tracked by either the joint impedance controller or the joint position controller, depending on the control mode.

Parameters
[in]positionsTarget joint positions: \( q_d \in \mathbb{R}^{n \times 1} \). Unit: \( [rad] \).
[in]velocitiesTarget joint velocities: \( \dot{q}_d \in \mathbb{R}^{n \times 1} \). Unit: \( [rad/s] \).
[in]accelerationsTarget joint accelerations: \( \ddot{q}_d \in \mathbb{R}^{n \times 1} \). Unit: \( [rad/s^2] \).
Exceptions
std::invalid_argumentif size of any input vector does not match robot DoF.
std::logic_errorif robot is not in an applicable control mode.
std::runtime_errorif number of timeliness failures has reached limit.
Note
Applicable control modes: RT_JOINT_IMPEDANCE, RT_JOINT_POSITION.
Real-time (RT).
Warning
Always stream smooth and continuous commands to avoid sudden movements.
See also
SetJointImpedance().

◆ StreamJointTorque()

void flexiv::rdk::Robot::StreamJointTorque ( const std::vector< double > &  torques,
bool  enable_gravity_comp = true,
bool  enable_soft_limits = true 
)

[Non-blocking] Continuously stream joint torque command to the robot.

Parameters
[in]torquesTarget joint torques: \( {\tau_J}_d \in \mathbb{R}^{n \times 1} \). Unit: \( [Nm] \).
[in]enable_gravity_compEnable/disable robot gravity compensation.
[in]enable_soft_limitsEnable/disable soft limits to keep the joints from moving outside allowed position range, which will trigger a safety fault that requires recovery operation.
Exceptions
std::invalid_argumentif size of any input vector does not match robot DoF.
std::logic_errorif robot is not in an applicable control mode.
std::runtime_errorif number of timeliness failures has reached limit.
Note
Applicable control modes: RT_JOINT_TORQUE.
Real-time (RT).
Warning
Always stream smooth and continuous commands to avoid sudden movements.

◆ SwitchMode()

void flexiv::rdk::Robot::SwitchMode ( Mode  mode)

[Blocking] Switch to a new control mode and wait until mode transition is finished.

Parameters
[in]modeflexiv::rdk::Mode enum.
Exceptions
std::invalid_argumentif the requested mode is invalid or unlicensed.
std::logic_errorif robot is in an unknown control mode or is not operational.
std::runtime_errorif failed to transit the robot into the specified control mode after several attempts.
Note
This function blocks until the robot has successfully transited into the specified control mode.
Warning
If the robot is still moving when this function is called, it will automatically stop then make the mode transition.

The documentation for this class was generated from the following file: