Package Summary
Tags | No category tags. |
Version | 0.15.0 |
License | Apache 2.0 |
Build type | CMAKE |
Use | RECOMMENDED |
Repository Summary
Checkout URI | https://github.com/frankaemika/libfranka.git |
VCS Type | git |
VCS Version | main |
Last Updated | 2024-09-13 |
Dev Status | DEVELOPED |
CI status | No Continuous Integration |
Released | RELEASED |
Tags | No category tags. |
Contributing |
Help Wanted (0)
Good First Issues (0) Pull Requests to Review (0) |
Package Description
Additional Links
Maintainers
- Franka Robotics GmbH
Authors
- Franka Robotics GmbH
libfranka: C++ Library for Franka Robotics Research Robots
libfranka is a C++ library that provides low-level control of Franka Robotics research robots. The generated API documentation offers an overview of its capabilities, while the Franka Control Interface (FCI) documentation provides more information on setting up the robot and utilizing its features and functionalities.
To find the appropriate version to use, please refer to the Compatibility Matrix.
Key Features
- Low-level control: Access precise motion control for research robots.
- Real-time communication: Interact with the robot in real-time.
Getting Started
1. System Requirements
Before using libfranka, ensure your system meets the following requirements:
- Operating System: Linux with PREEMPT_RT patched kernel (Ubuntu 16.04 or later, Ubuntu 22.04 recommended)
- Compiler: GCC 7 or later
- CMake: Version 3.10 or later
- Robot: Franka Robotics robot with FCI feature installed
2. Installing dependencies
sudo apt-get update
sudo apt-get install -y \
build-essential \
cmake \
git \
libpoco-dev \
libeigen3-dev \
dpkg
To use libfranka version 0.14.0
or later, you will need to install pinocchio and some more dependencies:
sudo apt-get install -y \
liburdfdom-headers-dev \
libconsole-bridge-dev \
libtinyxml2-dev
sudo apt-get install -qqy lsb-release curl
mkdir -p /etc/apt/keyrings
curl http://robotpkg.openrobots.org/packages/debian/robotpkg.asc \
| sudo tee /etc/apt/keyrings/robotpkg.asc
echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/robotpkg.asc] http://robotpkg.openrobots.org/packages/debian/pub $(lsb_release -cs) robotpkg" \
| sudo tee /etc/apt/sources.list.d/robotpkg.list
sudo apt-get update \
&& sudo apt-get install -qqy robotpkg-pinocchio
3. Building and Installation from Source
Before building and installing from source, please uninstall existing installations of libfranka to avoid conflicts:
sudo apt remove "*libfranka*"
Clone the Repository
You can clone the repository and choose the version you need by selecting a specific tag:
# Clone the repository
git clone --recursive https://github.com/frankaemika/libfranka.git
cd libfranka
# List available tags
git tag -l
# Checkout a specific tag (e.g., 0.14.1)
git checkout 0.14.1
# Update submodules
git submodule update
# Create a build directory and navigate to it
mkdir build
cd build
# Configure the project and build
cmake -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTS=OFF ..
cmake --build .
Installing libfranka as a Debian Package (Optional but recommended)
Building a Debian package is optional but recommended for easier installation and management. In the build folder, execute:
cpack -G DEB
This command creates a Debian package named libfranka-
sudo dpkg -i libfranka*.deb
Installing via a Debian package simplifies the process compared to building from source every time. Additionally the package integrates better with system tools and package managers, which can help manage updates and dependencies more effectively.
4. Usage
After installation, check the Minimum System and Network Requirements for network settings, the Operating System and PC Configuration for system setup, and the Getting Started Manual for initial steps. Once configured, you can control the robot using the example applications provided in the examples folder.
To run a sample program, navigate to the build folder and execute the following command:
./examples/communication_test <robot-ip>
License
libfranka
is licensed under the Apache 2.0 license.
CHANGELOG
UNRELEASED
Requires Franka Research 3 system version >= 5.8.0
- Joint/Cartesian Pose velocity and acceleration errors are minimized.
- Joint position and cartesian pose examples can now start from the initial q or O_T_EE
-
Joint position and cartesian pose low-pass filters are fixed to use the same command in the first package.
-
Important: The flags
fci_joint_motion_generator_position_limits_violation_flag
andfci_cartesian_motion_generator_joint_position_limits_violation_flag
are now always set to false and will be deprecated in future releases. They will be replaced byjoint_position_limits_violation
.
0.14.1 - 2024-09-06
- Added doxygen generation
0.14.0 - 2024-03-26
Requires Franka Research 3 system version >= 5.7.0
- Compute dynamic robot parameters with Pinocchio library.
0.13.5 - 2024-09-06
- Updated doxygen generation
0.13.4 - 2024-09-05
Requires Franka Research 3 system version >= 5.5.0
- Added package.xml for ros humble release
0.13.3 - 2024-01-18
Requires Franka Research 3 system version >= 5.5.0
- Bump libfranka-common version compatible with 5.5.0
- Delete the temporary-workaround max-path-pose deviation. Fixed in the system image.
0.13.2 - 2023-12-04
- Hotfix: (temporary-workaround) for max-path-pose-deviation in ExternalMode for active control.
0.13.1 - 2023-11-30
- Hotfix: (temporary-workaround) for max-path-pose-deviation in ExternalMode for callback based control.
0.13.0 - 2023-11-16
- Add abstract ActiveControlBase class for the ActiveControllers to implement.
- BREAKING Fix function naming errors in robot class.
- BREAKING ActiveController initializer functions return ActiveControlBase
0.12.1 - 2023-09-20
- Fix install common/include typo
0.12.0 - 2023-09-14
Requires Franka Research 3 system version >= 5.2.0
- BREAKING ActiveControl serves now as base class for ActiveTorqueControl, that implements the torque control functionality
- ActiveMotionGenerator class introduced to support external control loops for JointPositions, JointVelocities, CartesianPose and CartesianVelocities
0.11.0 - 2023-08-16
Requires Franka Research 3 system version >= 5.2.0
- BREAKING Instead of using constants, velocity limits in rate-limiter are computed based on the current desired joint position.
- Allow external control loops by the introduction of the ActiveControl read-write-interface for torque-control
0.10.0 - 2022-09-02
Requires Franka Research 3 system version >= 5.2.0
- BREAKING Remove getVirtualWall and setFilters commands
- BREAKING Disable rate-limiter by default
-
BREAKING Adapt rate limiting values in
rate_limiting.h
for FR3 robot
0.9.2 - 2022-08-31
Requires Panda system version >= 4.2.1
- Revert usage of
set_version_from_git
in CMakeLists.txt, using hardcoded values instead
0.9.1 - 2022-08-26
Requires Panda system version >= 4.2.1
- Use orthonormalized rotations in
cartesianLowpassFilter
,limitRate
andcartesian_impedance_control
example - Support building libfranka from outside the library, so the debian package name can be set externally.
- Check if GitHub remote is always in sync
- Bug fixes in
rate_limiting_tests.cpp
- Make column names in
logToCSV
unique, separated them by state & cmd - Improve error messages including current
RobotMode
information
0.9.0 - 2022-03-25
Requires Panda system version >= 4.2.1
-
BREAKING Add
O_ddP_O
base acceleration to robot state, hardcoded to{0, 0, -9.81}
. -
BREAKING New
base_acceleration_initialization_timeout
,base_acceleration_invalid_reading
cartesian_spline_motion_generator_violation
andjoint_via_motion_generator_planning_joint_limit_violation
reflexes. - Adjust network error messages. Distinguish between problems resulting from:
- a wrong network configuration. A message is shown after a timeout of 60 seconds.
- a missing FCI feature or a blocked port due to Single Point of Control. An immediate error response is shown.
- Changed signature of
franka::Model::gravity
to useO_ddP_O
in the robot state.
0.8.0 - 2020-04-29
Requires Panda system version >= 4.0.0
-
BREAKING Change behavior of
franka::Robot::setEE
. Previously, this method would set the flange-to-end-effector transformationF_T_EE
. This has been split up into two transformations:F_T_NE
, only settable in Desk, andNE_T_EE
, which can be set inlibfranka
withsetEE
and defaults to the identity transformation. - Add
F_T_NE
andNE_T_EE
tofranka::RobotState
. - Add support for the cobot pump with
franka::VacuumGripper
. - CPack: Add conflict with
ros-melodic-libfranka
. - Fix missing include for Windows (#55).
0.7.1 - 2019-07-08
Requires Panda system version >= 3.0.0
Changed
- Fix compilation error on ARM.
0.7.0 - 2019-07-05
Requires Panda system version >= 3.0.0
Added
- Add support for using
franka::Model
on Linux ARM and ARM64 (requires Panda system version >= 3.1.0). - Add Cartesian low-pass filter in
lowpass_filter.h
. - Add
control_tools.h
with helper functions for writing control loops.
Changed
-
BREAKING Rename
franka::CartesianPose::hasValidElbow()
tofranka::CartesianPose::hasElbow()
. -
BREAKING Throw
std::invalid_argument
infranka::Robot::control
if NaN or infinity values are returned from a control callback. -
BREAKING Throw
std::invalid_argument
in low-pass filter and rate limiting functions if invalid values are given as function parameters. - BREAKING Do not throw exceptions in constructors of control types anymore.
- Take arguments by value in
franka::MotionFinished
. - Bug fixes in
communication_test.cpp
. - Export requirements for C++ features as CMake target compile features.
0.6.0 - 2019-02-06
Requires Panda system version >= 3.0.0
- Added support for Ubuntu 18.04 (Bionic).
- EXPERIMENTAL Added support for Windows.
- Added support for using
franka::Model
on Linux and Windows x86 and x64. - Bugfix for aborting gripper commands with
franka::Gripper::stop()
. - Improved documentation for
franka::Robot::setCollisionBehavior
.
0.5.0 - 2018-08-08
Requires Panda system version >= 1.3.0
Motion and control interfaces
- BREAKING Added low-pass filter for all realtime interfaces with default cutoff frequency of 100 Hz
-
DEPRECATED
franka::Robot::setFilters
in favor offranka::lowpassFilter
- Fixed description of log record entries
Library
- Added
lowpass_filter.h
to public interface
Examples
- Added
communication_test.cpp
to evaluate network performance.
0.4.0 - 2018-06-21
Requires Panda system version >= 1.3.0
Motion and control interfaces
-
BREAKING Added rate limiting of commanded values as an option in the control loop and as
a helper function. Rate limiting is activated by default, this could change the behavior of
existing programs. Only works when filters (
franka::Robot::setFilters
) are deactivated. - Added
joint_move_in_wrong_direction
error tofranka::RobotState
- Added first and second derivatives of last commanded signals to
franka::RobotState
Library
- Added
rate_limiting.h
to public interface - Removed unnecessary CMake script from installation
0.3.0 - 2018-02-22
Requires Panda system version >= 1.2.0
Motion and control interfaces
- Added optional
epsilon
parameters tofranka::Gripper::grasp
Examples
- Set default collision behavior, impedances, and filter frequencies
- Removed command line parameters to simplify usage
- Fixed locking bug in
joint_impedance_control
Library
-
BREAKING Changed signatures and added overloads in
franka::Model
- Added additional variables to installed CMake config
- Updated
SOVERSION
to include minor version number - Added conflict with
ros-kinetic-libfranka
to Debian packaging - Minor fixes and improvements for API documentation
- Fixed build errors on Clang 5.0
- Fixed test errors for Poco >= 1.8.0
0.2.0 - 2018-01-29
Requires Panda system version >= 1.1.0
Motion and control interfaces
- Improved external torque tracking behavior.
- Fixed discontinuities in commanding orientation changes via the cartesian pose interface.
- Added
joint_p2p_insufficient_torque_for_planning
,tau_j_range_violation
, andinstability_detected
errors tofranka::RobotState
- Added
tau_J_d
,m_ee
,F_x_Cee
,I_ee
,m_total
,F_x_Ctotal
,I_total
,theta
anddtheta
tofranka::RobotState
- Added
setFilter
command tofranka::Robot
- Added support for commanding elbow positions for Cartesian motions.
- Added stiffness frame
K
tofranka::Model
-
BREAKING Replaced
p_min
andp_max
offranka::VirtualWallCuboid
withobject_world_size
Error handling
- WARNING Not all robot errors can be recovered using the guiding button on the robot anymore. To manually recover from such errors, please use the Franka DESK web interface.
- Added logs to
ControlException
and improved exception messages. - Fail earlier (by throwing exception) if any of the commanded values are
NaN
orinfinity
.
Examples
- Added saturation to joint velocity, joint position, and joint impedance examples.
- Changed examples to read initial states inside control loops (after controller switching).
- Examples first move to an initial joint position.
- Added new cartesian impedance and force control examples.
- Lowered grasping force in
grasp_object
example
Library
- BREAKING New build-time dependency on Eigen3.
- Changed thread priority to the maximum allowed value.
- Prepare for the removal of the socket-init in the default constructor in POCO releases >= 1.8.0.
- Removed unnecessary public dependencies for libfranka.
- CI: Run linter on examples
- Docu: Use SVG instead of MathML for math rendering in API documentation to support Chrome.
0.1.0 - 2017-09-15
- Initial release