Franka Library for MATLAB - Reference

FrankaRobot Class

The FrankaRobot constructor initializes a connection to the Franka robot. It can be configured for two primary scenarios: connecting to a robot on a local network (Host PC) or connecting to a robot via an external AI companion computer like a Jetson.

Multiple FrankaRobot instances can be created simultaneously, each managing its own server lifecycle independently.

Local Host PC as Target PC

fr = FrankaRobot();  % Uses default robot IP (172.16.0.2)

% Or with custom robot IP
fr = FrankaRobot('RobotIP', '172.16.0.2');

% Or with a full settings object for advanced configuration
settings = FrankaRobotSettings();
settings.robot_ip = '172.16.0.2';
settings.home_configuration = [0, -pi/4, 0, -3*pi/4, 0, pi/2, pi/4];
fr = FrankaRobot('Settings', settings);

Connecting via AI Companion/NVIDIA Jetson

When using an external Target PC to control the robot, you must provide connection details for that computer, including its IP address and a username.

Warning

Before attempting to connect to the robot via an external AI companion or NVIDIA Jetson, ensure that you have copied your SSH key to the target PC, e.g with ssh-copy-id for Linux. This step is crucial for establishing an SSH connection without requiring a password each time.

fr = FrankaRobot('RobotIP', '172.16.0.2', ...
                 'Username', 'jetson_user', ...
                 'ServerIP', '192.168.1.100');

% Or with custom settings object
settings = FrankaRobotSettings();
settings.home_configuration = [0, -pi/4, 0, -3*pi/4, 0, pi/2, pi/4];
fr = FrankaRobot('RobotIP', '172.16.0.2', ...
                 'Settings', settings, ...
                 'Username', 'jetson_user', ...
                 'ServerIP', '192.168.1.100');

All constructor parameters are optional and have default values.

Parameters:

RobotIP: IP address of the Franka robot (default: ‘172.16.0.2’). Overrides Settings.robot_ip if both are provided.
Settings: FrankaRobotSettings object containing robot configuration (optional). Other settings like collision_thresholds and load_inertia can be modified at runtime.
Username: Username for the server on the AI companion (default: ‘franka’)
ServerIP: IP address of the server on the AI companion (default: ‘172.16.1.2’)
SSHPort: SSH port for server connection (default: ‘22’)
ServerPort: Server port for communication (default: ‘5001’)

Automatic Error Recovery

fr.automatic_error_recovery();

Attempts an automatic error recovery of the robot.

Get Joint Poses

jp = fr.joint_poses();

Returns a 7-element array with the current robot joint poses.

Get Robot State

rs = fr.robot_state();

Returns a struct with the current robot state.

Joint Point to Point Motion

fr.joint_point_to_point_motion(joints_target_configuration, speed_factor);

Moves the robot into a desired joint configuration.

Parameters:

joints_target_configuration: 7-element double array with target configuration
speed_factor: Scalar between 0 and 1 (default: 0.5)

Joint Trajectory Motion

fr.joint_trajectory_motion(positions);

Moves the robot based on the given desired joint trajectory.

Parameters:

positions: 7xN double array with desired joint trajectory

Warning

Make sure that the current configuration of the robot matches the initial trajectory element q(1:7,1) that is passed in the function! Additionally make sure that the given trajectory is sufficiently smooth and continuous.

Collision Thresholds

fr.setCollisionThresholds(thresholds);
thresholds = fr.getCollisionThresholds();

Sets or gets the collision thresholds for the robot.

Parameters:

thresholds: FrankaRobotCollisionThresholds object

Load Inertia

fr.setLoadInertia(loadInertia);
inertia = fr.getLoadInertia();

Sets or gets the load inertia parameters for the robot.

Parameters:

loadInertia: FrankaRobotLoadInertia object (mass, center_of_mass, inertia_matrix)

Robot Homing

result = fr.robot_homing();

Moves the robot to its home configuration using point-to-point motion.

Returns:

true if the motion was successful, false otherwise

Reset Settings

fr.resetSettings();

Resets all robot settings to their default values and applies them to the robot.

Joint Impedance

fr.setJointImpedance(K_theta);
fr.setJointImpedance();  % Uses Settings.joint_impedance_stiffness
K_theta = fr.getJointImpedance();

Sets or gets the impedance for each joint in the internal controller. The value is stored in Settings.joint_impedance_stiffness.

Parameters:

K_theta: 7-element array of joint stiffness values [Nm/rad]

Default values: [3000, 3000, 3000, 2500, 2500, 2000, 2000]

Cartesian Impedance

fr.setCartesianImpedance(K_x);
fr.setCartesianImpedance();  % Uses Settings.cartesian_impedance_stiffness
K_x = fr.getCartesianImpedance();

Sets or gets the Cartesian stiffness/compliance in the internal controller. The value is stored in Settings.cartesian_impedance_stiffness.

Parameters:

K_x: 6-element array for (x, y, z, roll, pitch, yaw) stiffness [N/m, N/m, N/m, Nm/rad, Nm/rad, Nm/rad]

Default values: [3000, 3000, 3000, 300, 300, 300]

End Effector Frame (NE_T_EE)

fr.setEE(NE_T_EE);
fr.setEE();  % Uses Settings.NE_T_EE
NE_T_EE = fr.getEE();

Sets or gets the transformation from nominal end effector to end effector frame. The value is stored in Settings.NE_T_EE.

Parameters:

NE_T_EE: 4x4 homogeneous transformation matrix

Default: Identity matrix (eye(4))

Stiffness Frame (EE_T_K)

fr.setK(EE_T_K);
fr.setK();  % Uses Settings.EE_T_K
EE_T_K = fr.getK();

Sets or gets the transformation from end effector frame to stiffness frame. The value is stored in Settings.EE_T_K.

Parameters:

EE_T_K: 4x4 homogeneous transformation matrix

Default: Identity matrix (eye(4))

Stop Robot

result = fr.stop();

Stops all currently running motions on the robot.

Returns:

true if successful, false otherwise

Gripper Control

The FrankaRobot class provides access to both standard and vacuum grippers through the following properties:

fr.Gripper        % Standard gripper interface
fr.VacuumGripper  % Vacuum gripper interface

See the respective gripper class documentation for available methods.

FrankaGripper Class

The FrankaGripper class is accessed through the Gripper property of a FrankaRobot instance.

Get Gripper State

state = fr.Gripper.state();

Returns a struct with the current gripper state.

Gripper Homing

result = fr.Gripper.homing();

Performs gripper homing. Returns true if successful.

Grasp Object

result = fr.Gripper.grasp(width, speed, force, epsilon_inner, epsilon_outer);

Grasps an object with the specified width.

Parameters:

width: Target width in meters.
speed: Speed of the motion (default: 0.1).
force: Grasping force in N (default: 50).
epsilon_inner: Inner epsilon for grasping (default: 0.1).
epsilon_outer: Outer epsilon for grasping (default: 0.1).

Returns:

true if grasping was successful, false otherwise.

Move Gripper

result = fr.Gripper.move(width, speed);

Moves the gripper to a specific width.

Parameters:

width: Target width in meters.
speed: Speed of the motion (default: 0.1).

Returns:

true if motion was successful, false otherwise.

Stop Gripper

result = fr.Gripper.stop();

Stops the gripper motion. Returns true if successful.

FrankaVacuumGripper Class

The FrankaVacuumGripper class is accessed through the VacuumGripper property of a FrankaRobot instance.

Get Vacuum Gripper State

state = fr.VacuumGripper.state();

Returns a struct with the current vacuum gripper state, including vacuum level and part presence.

Apply Vacuum

result = fr.VacuumGripper.vacuum(control_point, timeout, profile);

Applies vacuum to the gripper.

Parameters:

control_point: Vacuum control point (default: 0).
timeout: Timeout in milliseconds (default: 5000).
profile: Production setup profile (default: 0).

Returns:

true if vacuum was successfully applied, false otherwise.

Drop Off

result = fr.VacuumGripper.dropOff(timeout);

Drops off the currently held object.

Parameters:

timeout: Timeout in milliseconds (default: 5000).

Returns:

true if drop off was successful, false otherwise.

Stop Vacuum Gripper

result = fr.VacuumGripper.stop();

Stops the vacuum gripper. Returns true if successful.