GitHub Workflow Status

libfranka-rs

libfranka-rs is an unofficial port of libfranka written in Rust. This library can interact with research versions of Franka Emika Robots. The library aims to provide researchers the possibility to experiment with Rust within a real-time robotics application.

ALWAYS HAVE THE USER STOP BUTTON AT HAND WHILE CONTROLLING THE ROBOT!

Features

Real-time control of the robot
A libfranka-like API
Usage with Preempt_RT or stock Linux kernel
Usage of the gripper
Usage of the robot model
Download the robot model for offline usage
Ports of the libfranka examples to help you to get started
The functionality of the example_commons is directly part of the library, so you do not have to copy these files to your project
Direct Conversions from nalgebra (Eigen3 equivalent) types into libfranka control types (JointPositions, CartesianPose, ...)
Proper error handling with Result types

TODO:

Usage of the Model for anything else but Linux x86_64

Not supported:

Windows (macOS could maybe work, but I have not tested it)
Vacuum Grippers (we do not have those, so I cannot test them)

Example

A small example for controlling joint positions. You can find more in the examples folder.

use franka::{FrankaResult, JointPositions, MotionFinished, Robot, RobotState};
use std::f64::consts::PI;
use std::time::Duration;
fn main() -> FrankaResult<()> {
  let mut robot = Robot::new("robotik-bs.de", None, None)?;
  robot.set_default_behavior()?;
  println!("WARNING: This example will move the robot! Please make sure to have the user stop button at hand!");
  println!("Press Enter to continue...");
  std::io::stdin().read_line(&mut String::new()).unwrap();

  // Set additional parameters always before the control loop, NEVER in the control loop!
  // Set collision behavior.
  robot.set_collision_behavior(
      [20.0, 20.0, 18.0, 18.0, 16.0, 14.0, 12.0],
      [20.0, 20.0, 18.0, 18.0, 16.0, 14.0, 12.0],
      [20.0, 20.0, 18.0, 18.0, 16.0, 14.0, 12.0],
      [20.0, 20.0, 18.0, 18.0, 16.0, 14.0, 12.0],
      [20.0, 20.0, 20.0, 25.0, 25.0, 25.0],
      [20.0, 20.0, 20.0, 25.0, 25.0, 25.0],
      [20.0, 20.0, 20.0, 25.0, 25.0, 25.0],
      [20.0, 20.0, 20.0, 25.0, 25.0, 25.0],
  )?;

  let q_goal = [0., -PI / 4., 0., -3. * PI / 4., 0., PI / 2., PI / 4.];
  robot.joint_motion(0.5, &q_goal)?;
  println!("Finished moving to initial joint configuration.");
  let mut initial_position = JointPositions::new([0.0, 1.0, 2.0, 3.0, 4.0, 5.0, 6.0]);
  let mut time = 0.;
  let callback = |state: &RobotState, time_step: &Duration| -> JointPositions {
      time += time_step.as_secs_f64();
      if time == 0. {
          initial_position.q = state.q_d;
      }
      let mut out = JointPositions::new(initial_position.q);
      let delta_angle = PI / 8. * (1. - f64::cos(PI / 2.5 * time));
      out.q[3] += delta_angle;
      out.q[4] += delta_angle;
      out.q[6] += delta_angle;
      if time >= 5.0 {
          println!("Finished motion, shutting down example");
          return out.motion_finished();
      }
      out
  };
  robot.control_joint_positions(callback, None, None, None)
}

How to get started

As it is a straight port, you may find the Franka Control Interface Documentation helpful.

With zero Rust knowledge

If this is your first time using Rust, I recommend reading the Rust Book.

If you have Rust installed and just want to play with the examples, you can also run:

cargo install libfranka-rs --examples
generate_joint_position_motion <ip_of_your_robot>

If you are already familiar with the original libfranka examples. I suggest you take a look at the examples folder. The examples that are named like an original libfranka example are ports that stay as close to the original as possible, hoping that it makes your introduction into the Rust world as smooth as possible.

With zero libfranka knowledge

The Franka Control Interface Documentation also includes a setup guide. You can skip the installation of libfranka as you will be using libfranka-rs. Take a look at the Documentation and the examples folder. You should run the communication_test example to verify that your setup is correct.

How to use libfranka-rs

If you want to use libfranka-rs in your project, you have to add

libfranka-rs = 0.8

to your Cargo.toml file. libfranka-rs version numbers are structured as MAJOR.MINOR.PATCH. The Major and Minor versions match the original libfranka version numbers. That means for 0.8, your robot has to be at least on Firmware 4.0.0. Older firmware versions are not supported by libfranka-rs. You can find more information about system updates here.

Bugs and Merge Requests

This work is part of my master thesis. You can open issues as you like. However, please refrain from opening merge requests until my master thesis is over (5th of July 2021).

Licence

Licensed under the EUPL, Version 1.2 or – as soon they will be approved by the European Commission - subsequent versions of the EUPL (the "Licence");

You may not use this work except in compliance with the Licence. You may obtain a copy of the Licence at:

https://joinup.ec.europa.eu/software/page/eupl

Unless required by applicable law or agreed to in writing, software distributed under the Licence is distributed on an "AS IS" basis WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

See the Licence for the specific language governing permissions and limitations under the Licence.

libfranka-rs 0.8.0-alpha