libfranka Documentation

pylibfranka is a Python library designed for high-level access to Franka Robotics robots. It is optimized for real-time control and seamless integration with the scientific Python ecosystem.

Key Capabilities

• Real-time Control: Supports sending torque, position, and velocity commands at a 1 kHz frequency.
• Control Modes: Provides multiple modes including Joint/Cartesian position, velocity, and torque control.
• Robot State Access: Allows reading comprehensive robot state information, such as joint positions, velocities, and torques.
• Dynamics Model: Includes tools to compute forward/inverse kinematics, mass matrix, Coriolis, and gravity.
• Gripper Control: Provides full control capabilities for the Franka Hand gripper.
• NumPy Integration: All data arrays are returned as NumPy arrays, facilitating easy use with other Python scientific libraries.

libfranka is a C++ library designed for low-level control of Franka Robotics research robots. It allows developers to interface directly with the robot hardware for research and development purposes.

Key resources for developers:

• API References: Detailed documentation of the library's functions and capabilities.
• Franka Control Interface (FCI) Documentation: Information on robot setup and utilizing specific robot features.
• Robot System Version Compatibility: A matrix to ensure the version of libfranka you are using is compatible with your specific robot system version.

libfranka provides built-in robot models that allow you to compute kinematic and dynamic parameters for any arbitrary robot state. This can be done in real-time or non-real-time (e.g., in an optimization loop).

Included models cover:

• Forward kinematics of all robot joints
• Body and zero Jacobian matrices
• Dynamic parameters: inertia matrix, Coriolis and centrifugal vector, and gravity vector.

When using an active control interface (derived from ActiveControlBase), use the readOnce() method to synchronize state reading with the control cycle. This method returns a tuple containing the current RobotState and a Duration object representing the time elapsed since the last cycle.

# Inside a control loop using an ActiveControl object
state, duration = control.readOnce()

The core interaction with the Franka robot is managed through several key classes:

• Robot: The primary interface used to connect to and control the robot.
• ActiveControlBase: Represents an active control session. Use this class to read the current robot state and write commands during a control loop.
• RobotState: Provides a complete snapshot of the robot's current state information.
• Model: Provides access to the robot's dynamics model.

All errors raised by the library inherit from the base FrankaException. When writing robust robot control code, you should catch specific exception types to differentiate between network issues, control errors, or invalid operations.

Exception Hierarchy:

• FrankaException (Base class)
  • CommandException: Errors related to sending commands.
  • ControlException: Errors occurring during active control sessions.
  • NetworkException: Connectivity or communication issues.
  • InvalidOperationException: Attempting an operation that is not allowed in the current state.
  • RealtimeException: Violations of real-time constraints.

To interact with a Franka gripper, use the following classes:

• Gripper: Maintains the network connection to the gripper, provides the current GripperState, and allows for the execution of gripper commands.
• GripperState: A data structure that describes the current state of the gripper.

The library uses a specific hierarchy to categorize errors. Understanding these allows you to implement different recovery strategies (e.g., retrying a command vs. attempting a network reconnection).

Hierarchy:

• FrankaException (Base class)
  • CommandException: Errors during command execution or invalid parameters.
  • NetworkException: Connection failures or timeouts.
  • ControlException: Errors during motion or torque control (e.g., safety violations).
  • InvalidOperationException: State-related errors (e.g., starting a loop while one is running).
  • RealtimeException: Real-time scheduling or kernel requirement failures.

The Model class in pylibfranka provides a robot dynamics model used to compute various quantities such as the mass matrix, Coriolis and centrifugal forces, gravity torques, and the Jacobian.

To obtain an instance of the Model, you must call Robot.load_model() on an existing Robot instance.

import pylibfranka

robot = pylibfranka.Robot("172.16.0.2")
model = robot.load_model()

Gripper functionality is encapsulated in two main classes:

• Gripper: The interface used to send commands to the gripper.
• GripperState: Provides information regarding the current state of the gripper.