Flexivrdk

COMPATIBILITY

* Flexiv software package **v3.7.1**

ADD

- Expose read/write of the two pairs of digital input/output ports inside the robot's wrist connector.
- Add input parameter `network_interface_whitelist` to `rdk::Robot `constructor to allow limiting the network interface(s) that can be used for establishing connection with the robot.
- Add input parameter `properties` to `Robot::ExecutePrimitive()`.
- Add struct `JPos` to represent the customized data type JPOS in Flexiv Elements. Update examples accordingly.

CHANGE

- Remove linking to `fastcdr`, not needed.
- Use shared steps in GitHub workflow.
- Use GitHub-hosted runner for macOS workflow jobs.
- Improve resource efficiency of background communication services.
- Update README.

FIX

- Fix definition for member of `rdk::Coord` struct.
- Fix a bug that causes occasional "Failed to sync server version" error when trying to establish connection with the robot.

COMPATIBILITY

* Flexiv software package **v3.7**

ADD

- Add support to use Cartesian motion-force control modes with the Moonlight delta robot.
- Add an overload of `Robot::SetGlobalVariables()` that takes in an `std::map` instead of a long string. The old version will be deprecated.
- Add an overload of `Robot::global_variables()` that returns an `std::map` instead of a string list. The old version will be deprecated.
- Add an overload of `Robot::ExecutePrimitive()` that takes in an `std::map` instead of long sting. The old version will be deprecated.
- Add an overload of `Robot::primitive_states()` that returns an `std::map` instead of a string list. The old version will be deprecated.
- Add type alias `FlexivDataTypes` to represent a variant that holds all possible types of data exchanged with Flexiv robots using the new overloaded functions above.
- Add `utility::FlexivTypes2Str()` to convert data held in `FlexivDataTypes` to a single string.
- Add `rdk::Coord` struct to be used with `FlexivDataTypes` variant.
- Add function `Robot::SetNullSpaceObjectives()` to set weights of the three optimization objectives while computing the robot's null-space posture.
- Add API `flexiv::rdk::WorkCoord` to online update and interact with the robot's work coordinates (58, 66).
- Add enum `rdk::CoordType` to represent commonly-used reference coordinates.
- Add `Robot::operational_status()` with enum return type (67, 81).
- Add `Robot::reduced()` to check for safety system's reduced state (67).
- Add new input parameter block_until_started to `Robot::ExecutePlan()` and `Robot::ExecutePrimitive()` (76).
- Add input parameter `velocity` to `Robot::StreamCartesianMotionForce()` so users have the option to improve the robot's tracking performance at the cost of reduced robustness or vice versa.
- Add `Device::exist()` to check if the specified device exists.
- Add `Model::SyncURDF()` to cync the actual kinematic parameters of the connected robot into the template URDF (82).
- Add `RobotInfo::license_type`.
- Add external axes states to `RobotStates`.
- Add `RobotStates::ext_wrench_in_tcp_raw` and `RobotStates::ext_wrench_in_world_raw` that contain unfiltered external wrench data.
- Add C++ and Python examples for global variable functions.
- Add urgency scale to feature request template.

CHANGE

- Allow `Robot::SetGlobalVariables()` to be called in any control mode instead of only in `NRT_PLAN_EXECUTION` mode.
- Change `Robot::SetCartesianImpedance()` to blocking, and the robot will not reset to nominal Cartesian impedance upon re-entering the applicable control modes; the setting will persist.
- Remove `Robot::ResetCartesianImpedance()`, the user has enough info to reset the impedance using `Robot::SetCartesianImpedance()`.
- Change `Robot::SetJointImpedance()` to blocking, and the robot will not reset to nominal joint impedance upon re-entering the applicable control modes; the setting will persist.
- Remove `Robot::ResetJointImpedance()`, the user has enough info to reset the impedance using `Robot::SetJointImpedance()`.
- Change `Robot::SetMaxContactWrench()` to blocking, and the robot will not reset to disable contact wrench regulation upon re-entering the applicable control modes; the setting will persist.
- Remove `Robot::ResetMaxContactWrench()`, the user has enough info to disable contact wrench regulation using `Robot::SetMaxContactWrench()`.
- Change `Robot::SetNullSpacePosture()` to blocking.
- Remove `Robot::ResetNullSpacePosture()`, the user has enough info to reset to initial reference positions using `Robot::SetNullSpacePosture()`.
- Change `Robot::SetForceControlAxis()` to blocking, and allow it to be called when in motion force-control modes.
- Change `Robot::SetForceControlFrame()` to blocking, and allow it to be called when in motion force-control modes.
- Support setting a user-defined arbitrary force control frame with regard to either WORLD or TCP frame using `Robot::SetForceControlFrame()` (78).
- Change `Robot::SetPassiveForceControl()` to blocking.
- Flip the force command direction in motion-force control modes to make the behavior consistent with Flexiv Elements.
- Throw exception in `Tool::Add()`, `Tool::Switch()`, `Tool::Update()`, `Tool::Remove()`, and `Tool::params()` if the specified tool does not exist.
- Throw exception in `Device::Enable()`, `Device::Disable()`, and `Device::Command()` if the specified device does not exist.
- Throw exception in `Device::Command()` if the commanded device is not enabled.
- `Device::Command()` uses variant to represent command values.
- Remove mandatory blocking of `Gripper::Init()`, user needs to implement the wait accordingly.
- Change `enum Mode` to scoped `enum class Mode`.
- Use `Robot::SetDigitalOutputs()` to deprecate `WriteDigitalOutput()`.
- Use `Robot::digital_inputs()` to deprecate `ReadDigitalInput()`.
- Remove `utility::ParsePtStates()`, no longer needed.
- The "Home" primitive now does not terminate by itself, thus change termination check condition from `busy() == false` to `reachedTarget == true`.
- Update warning doc of `Robot::ExecutePrimitive()` about primitives' self-termination.
- Internal plans (those not created by user) now cannot be resumed from pause due to safety concerns.
- Remove input parameter `trailing_space` from `utility::Vec2Str()` and `Arr2Str()`.
- Change the term "preferred positions" to "reference positions" to be consistent with Flexiv Elements.
- Decrease the nominal rotation stiffness from 3000 to 1500 Nm/rad for Rizon 4 variants and from 6000 to 3000 Nm/rad for Rizon 10 varients due to stability concerns.
- Remove excessive prints.
- Update API usages in examples.
- Update website links.

FIX

- Fix `cmake/FlexivInstallLibrary.cmake` that exports the wrong project version.
- Specify `-DCMAKE_PREFIX_PATH` in thirdparty build scripts so they don't accidentally link to existing dependencies in system path.
- Fix connection loss with the robot when network condition is bad.
- Fix the issue where spdlog's log level is not reset when the construction of `rdk::Robot` is incomplete.

NOTE

This release note is based on changes since v1.3. If you are switching from v0.x to v1.x for the first time, you might want to review all release notes since the v1.0 pre-release,

COMPATIBILITY

* Flexiv software package **v3.6**

ADD

- Add sub-namespace: `flexiv::` now becomes `flexiv::rdk::`.
- Add support for Rizon medical model `Rizon4M`.
- Add support for the force-controlled delta robot `Moonlight`.
- Add support of `flexiv::rdk::Model` API for Python RDK. Add `intermediate5_robot_dynamics.py` example accordingly.
- Add installation of Python RDK libraries to the user site packages path, using CMake. Remove `sys.path.insert()` from Python examples accordingly.
- Add `RobotInfo::K_q_nom`, nominal motion stiffness of the joint impedance control modes of the connected robot.
- Add `RobotInfo::model_name`, model name of the connected robot, e.g. Rizon4, Rizon10, Moonlight, etc.
- Add `RobotInfo::DoF`, joint-space degrees of freedom of the connected robot. Remove `kJointDOF` constant accordingly. The joint DoF now varies according to the model of the connected robot. Update examples accordingly.
- Add real-time joint impedance (`RT_JOINT_IMPEDANCE`) and non-real-time joint impedance (`NRT_JOINT_IMPEDANCE`) control modes. Add `intermediate2_realtime_joint_impedance_control.cpp` and `intermediate2_non_realtime_joint_impedance_control.py` examples accordingly.
- Add `Robot::SetJointImpedance()` and `Robot::ResetJointImpedance()` that sets and resets stiffness and damping ratio of the robot's joint motion controller used in the joint impedance control modes.
- Add `Robot::Brake()` to force engaging or releasing robot brakes during normal operation. Only available to the medical model.
- Add `Model::reachable()` to check reachability of a given Cartesian pose and return the corresponding IK solution if reachable.
- Add error code prefix to Robot Log messages.
- Add new dependency `spdlog` to replace the `flexiv::Log` API. Update examples and tests accordingly.
- Add new C++ example to show how to change logging behavior of RDK client, as well as how to log to file.
- Add input parameter `separator` to `utility::Arr2Str()`.
- Add `utility::Vec2Str()`.

CHANGE

- Change header file extension from `.h` to `.hpp` to prevent C++ IntelliSense tool from mistaking certain system headers for RDK headers.
- To accommodate the newly added support of the Moonlight delta robot, change joint-space variables in `RobotInfo` and `RobotStates` data structures from fixed-size arrays to dynamic-size vectors. Also change input arrays of `Robot::StreamJointTorque()`, `Robot::StreamJointPosition()`, `Robot::SendJointPosition()`, `Robot::SetJointImpedance()`, `Robot::SetNullSpacePosture()`, and `Model::Update()` to vectors. Update examples accordingly.
- Rename `RobotInfo::nominal_K` to `RobotInfo::K_x_nom`.
- Update function documentation of `Robot::StreamJointPosition()` and `Robot::SendJointPosition()` to include joint impedance control modes.
- Change `Robot::SetCartesianStiffness()` to `Robot::SetCartesianImpedance()` and `Robot::ResetCartesianStiffness()` to `Robot::ResetCartesianImpedance()`. Cartesian motion damping ratio is added as a new input parameter. Update examples accordingly.
- Rename `kCartDOF` to `kCartDoF`. Update examples accordingly.
- Update `Robot::ClearFault()` to support clearing critical robot faults, if the hardware for hot-reset is installed.
- Increase nominal Cartesian stiffness of Rizon 4 series from [10000-1000] to [10000-2500], and Rizon 10 series from [20000-2000] to [20000-6000].
- Greatly reduce blocking time of `Robot::ExecutePrimitive()`, `Robot::ExecutePlan()`, `Robot::SwitchMode()`, and `Tool::` functions.
- Use pip installed `spdlog` in Python examples.
- Merge `PrintDescription()` to `main()` in all examples.
- Change `maxVel=` to `vel=` in primitive execution examples.
- Use f-string formatting in Python examples.
- Upgrade `doc/Doxyfile.in`.
- Improve function documentations.
- Improve README.
- Improve dependencies build script.

FIX

- Fix `Robot::global_variables()` does not return updated values if called immediately after `Robot::SetGlobalVariables()`.
- Fix a bug where re-switching control mode before sending commands is not enforced after disconnected then reconnected with the robot.
- Fix a bug in `test/test_dynamics_engine.cpp`.
- Fix keyboard interruption handling for Python examples.
- Fix compatibility issue with Eigen for Python 3.12 libraries.

COMPATIBILITY

* Internal pre-release

ADD

- Add new API `flexiv::Device` for general device control over RDK.
- Add `Robot::mu_log()` to access the multilingual log messages of the connected robot; remove `Robot::getErrorMessage()` accordingly.
- Add `Robot::SetVelocityScale()` as a standalone function to change velocity scale during plan/primitive execution; remove `velocity_scale` input parameter from `Robot::ExecutePlan()` and `Robot::ExecutePrimitive()` accordingly.
- Add input parameter `acceleration` to `Robot::StreamCartesianMotionForce()` to feed-forward target TCP acceleration.
- Add input parameters `max_linear_acc` and `max_angular_acc` to `Robot::SendCartesianMotionForce()`.
- Provide explicit default values to input parameters of `Robot::SendCartesianMotionForce()`.
- Add bool return to `Robot::ClearFault()` to indicate whether the fault is cleared successfully; update usage in examples accordingly.
- Add `Gripper::moving()` to replace `GripperStates::isMoving`.
- Add `Gripper::Init()` to manually trigger gripper initialization; update gripper control examples accordingly.
- Add string names array `kModeNames` for robot control modes.
- Add more supported formats for robot SN input when constructing `flexiv::Robot`.

CHANGE

- Update format requirement of input parameter with ARRAY_COORD type for `Robot::ExecutePrimitive()`.
- Adopt the [Google C++ Style Guide](https://google.github.io/styleguide/cppguide.html#Naming) globally.
- Increase nominal Cartesian stiffness of Rizon 4/4s from 6000/400 to 10000/1000, Rizon 10/10s from 12000/1200 to 20000/2000.
- Replace `Robot::getRobotStates()` with `Robot::states()` direct accessor.
- Replace `Robot::getMode()` with `Robot::mode()` direct accessor.
- Replace `Robot::getPlanNameList()` with `Robot::plan_list()` direct accessor.
- Replace `Robot::getPlanInfo()` with `Robot::plan_info()` direct accessor.
- Replace `Robot::getGlobalVariables()` with `Robot::global_variables()` direct accessor.
- Replace `Robot::getPrimitiveStates()` with `Robot::primitive_states()` direct accessor.
- Rename `Gripper::getGripperStates()` to `Gripper::states()`.
- Rename `Tool::switchTo()` to `Tool::Switch()`.
- Rename `Tool::getToolList()` to `Tool::list()`.
- Rename `Tool::getCurrentToolName()` to `Tool::name()`.
- Rename `Tool::getToolParams()` to `Tool::params()`; add function overload for `Tool::getCurrentToolParams()`.
- Rename functions in `flexiv::Model` to math symbol representations.
- Revert Windows action runner version to 2022 as the MSVC compatibility issue is fixed. Remove temporary warning from README accordingly.
- Remove `RobotInfo::qHome`.
- Improve API docs.
- Update examples and tests with new function naming.
- Bump supported Python version from 3.8/3.10 to 3.10/3.12.
- Update `.gitignore`.
- Update Windows compilation toolkit requirement in README.

FIX

- Fix singularity bug under `NRT_CARTESIAN_MOTION_FORCE` control mode (42).
- Fix data corruption when requesting primitive states (47).
- Fix discontinuous null-space posture transition (45).
- Fix robot tool update examples.
- Fix control mode mismatch bug in real-time control modes.
- Upgrade Fast-DDS version to v2.6.7, this fixed the compatibility issue with MSVC v143 (Visual Studio 2022).
- Remove incorrect comment from `basics3_primitive_execution.py`.

COMPATIBILITY

* Internal pre-release

ADD

- Add API access of `flexiv::Model` to Windows.
- Add new API `flexiv::Tool` to online update the robot tools. Add C++ and Python examples.
- Add `ToolParams` data struct to `Data.hpp`.
- Add new API `flexiv::FileIO` to do file transfer with the robot.
- Add `Robot::setBreakpointMode()` and `Robot::stepBreakpoint()` to do breakpoint control when executing plans.
- Add `PlanInfo::waitingForStep` variable to indicate breakpoint status.
- Add more generic Cartesian motion-force control modes `RT/NRT_CARTESIAN_MOTION_FORCE` to replace the old ones which are `RT/NRT_CARTESIAN_MOTION_FORCE_TCP` and `RT/NRT_CARTESIAN_MOTION_FORCE_BASE`.
- Add functions to configure force control parameters for the new Cartesian motion-force control modes: `Robot::setForceControlAxis()`, `Robot::setForceControlFrame()`, and `Robot::setPassiveForceControl()`.
- Add behavior description to the function doc of `Robot::sendJointPosition()`.
- Add input parameter `continueExec` to `Robot::executePlan()` to specify whether to continue executing the plan when the RDK program is closed or the connection is lost. Set this parameter to true in the plan execution examples.
- Add `Robot::isEnablingButtonPressed()` to check if the enabling button on the robot motion bar is pressed.
- Add `Robot::getErrorMessage()` to get error message if the robot is in fault state.
- Add `Model::reload()` to sync the latest robot model and tool model data from the connected robot.
- Add `Scheduler::minPriority()` to get the OS' minimum available priority for user tasks.
- Add check on user-specified task priority against the OS' minimum available priority to `Scheduler::addTask()`.
- Add [Blocking] or [Non-blocking] tag to function doc.
- Overload `Gripper::getGripperStates()` with a variant that directly returns `GripperStates` data struct.
- Overload `Robot::getRobotStates()` with a variant that directly returns `RobotStates` data struct.
- Add GitHub workflow for macOS build.

CHANGE

- Split RDK license to Standard license and Professional license. The standard license provides access to essential and non-real-time functionalities such as reading robot states, sending plan/primitive commands, etc. The professional license provides access to everything included with the standard license, plus robot dynamics and real-time functionalities such as joint torque/position streaming, Cartesian motion/force streaming, etc.
- Change `Robot::streamCartesianMotionForce()` and `Robot::sendCartesianMotionForce()` to use the same controller as `MoveHybrid` primitive. Update Cartesian motion-force control examples accordingly.
- Change `Robot::getPlanInfo()` to return `PlanInfo` data struct directly.
- Change the term "base" to "world" when referring to the robot's global coordinate.
- Change `RobotStates::extWrenchInBase` to `RobotStates::extWrenchInWorld`.
- Make the effect of `Robot::setNullSpacePosture()` persistent: not resetting preferred joint positions to nominal when switching modes.
- Remove input parameter `isBlocking` from `Scheduler::start()`, the user should implement their own blocking from the calling thread if needed. Update examples accordingly.
- Remove check on elapsed waiting time of `Robot::isOperational()` from the examples.
- Remove `RobotStates::camPose`: the ownership of camera pose is transferred to Noema AI system.
- Merge `test_dynamics_with_tool` into `test_dynamics_engine`.
- Improve function docs.
- Remove Ubuntu 18.04 from supported OS list.
- Rename C++ libs to the same pattern as the Python libs.
- Format Python examples using Black Formatter.
- Update MSVC compatible version in README.

FIX

- Fix a root link bug in `flexiv::Model`.
- Fix memory leak of `flexiv::Scheduler`.
- Fix initial timer fluctuation of `flexiv::Scheduler`.
- Fix `Robot::runAutoRecovery()`.

COMPATIBILITY

* Internal pre-release

ADD

- Add [Blocking] and [Non-blocking] tag to doc of all `flexiv::Robot` functions.
- Add `maxLinearVel` and `maxAngularVel` input parameters to `Robot::sendCartesianMotionForce()`.
- Add `Robot::resetCartesianStiffness()` to replace the default parameter of `Robot::setCartesianStiffness()`.
- Add `Robot::resetNullSpacePosture()` to replace the default parameter of `Robot::setNullSpacePosture()`.
- Add `Robot::setMaxContactWrench()` and `Robot::resetMaxContactWrench()` for Cartesian motion-force control modes to maintain the contact wrench under the specified limit.
- Add script argument to `thirdparty/build_and_install_dependencies.sh` to specify number of parallel compilation jobs.
- Add automatic print of info, warning, error, and critical error messages that are also displayed on Flexiv Elements.

CHANGE

- Replace dynamic-sized vectors with fixed-sized array for most functions and data structures. Update examples accordingly.
- Remove `flexiv::Exception`, replace with `std::exception`. Update examples accordingly.
- Change `Robot::setMode()` to block for the actual time used by the robot to decelerate and come to a complete stop.
- Replace `Robot::startAutoRecovery()` to with `Robot::runAutoRecovery()`, which blocks until the auto recovery process is finished. Update examples accordingly.
- Increase joint position auto recovery distance from 5 degrees to 10 degrees.
- Rewrite `Robot::writeDigitalOutput()` to allow writing to one or multiple digital output ports in a single function call.
- Change `Robot::readDigitalInput()` from non-real-time blocking to real-time non-blocking, change to read values from all digital input ports at once.
- Increase maximum allowed input string size from 5 Kb to 10 Kb for `Robot::executePrimitive()` and `Robot::setGlobalVariables()`.
- Bump CMake minimum required version to 3.18.6.
- Remove explicit linking to `librt`.
- Specify C++17 as one target property for examples.
- Remove setting `CMAKE_CXX_STANDARD` globally.
- Decrease control mode switching time from 1 second to 100 ms plus any additional time needed to decelerate the robot.

FIX

- Remove incorrect function doc from `Robot::executePrimitive()`.
- Fix auto recovery.
- Fix a potential race condition between DDS entities.
- Fix occasional false negative returned by `Robot::isBusy()`.
- Fix occasional delivery delay of real-time motion commands.
- Fix an issue where plan and primitive will lose the gripper control after a function from `flexiv::Gripper` is called.