Welcome to franka_emulator 1.0.1!

Here you will find a C++ library that replaces and behaves like libfranka with one exception - the robot is virtual! It has similar C++ and CMake API and is created to give developers a possibility to write programs for Panda robot without having it.

Contents

1. Welcome to Franka Emulator
2. Contents
3. Usage
4. Requirements
5. Building
6. Installation
7. Documentation
8. Contributors

Usage

Usage franka_emulator is supposed to be very similar to usage of libfranka. Simplest C++ program reads:

#include <franka_emulator/robot.h>
int main()
{
	franka_emulator::Robot robot("<IP>");
}

While typical CMakeLists.txt usage looks like:

find_package(FrankaEmulator 1.0.0 REQUIRED)
add_executable(example example.cpp)
target_link_libraries(example PRIVATE Franka::FrankaEmulator)

And that's it, further changes are needed. And is that is not enough, you can add -DFRANKA_EMULATOR_IMITATE=true to cmake options to eliminate even these differences!

The simulation itself can be launched with:

./franka_emulator.sh <IP>

Where <IP> is the same string that needs to be passed to franka_emulator::Robot to make it connected to the simulation. The string is arbitrary (but without slashes) as it is not an actual IP address. Actually, the emulator does not use sockets at all.

Requirements

The library requires:

• Gazebo (Standalone or as part of ROS)
• Eigen
• pinocchio (set with -Dpinocchio_DIR=/absolute_path_to_pinocchio or as part of ROS)
• libfranka (optionally) (set with -DFranka_DIR=/absolute_path_to_libfranka/build or as part of ROS)
• Google Test (optionally)
• Doxygen (optionally)
• CMake >= 3.4.0
• C++11 compatible compiler
• Fully preemptable Linux kernel (optionally)

Building

The library can be built with CMake using the following commands:

mkdir build
cd build
cmake .. #-DFRANKA_EMULATOR_IMITATE=true
cmake --build .

Installation

Step 1: Getting real-time permission This can be done in various ways. As an example, the following commands will allow everyone to execute any real-time commands:

sudo -s
echo * - rtprio 99       >> /etc/security/limits.conf
echo * - priority 99     >> /etc/security/limits.conf
echo * - memlock 102400  >> /etc/security/limits.conf
exit

Reboot for changes to take place. You also may read this for more secure options.

Optional step 2: Installing franka_emulator Although the emulator can be run without installation, it can be installed with the commands:

cd build
sudo cmake --install .
sudo ldconfig

Note that if FRANKA_EMULATOR_IMITATE is true, the library will conflict with libfranka. In that case, installing both the emulator and the library will lead to undefined behavior.

Optional step 3: Installing real-time kernel It is said that the fully preemptive kernel can do priority boosting with semaphores, which might increase the emulator's performance (because the library uses semaphores a lot). Note that real-time kernel might cause system instability (and may not). You will alwaus be able to roll back to generic kernel.

For Debian: sudo apt-get install linux-image-rt-amd64 (assuming you have a x86_64 machine, proceed here if not)

For Arch: yay -S linux-rt-lts (assuming you use yay, proceed here to see other options)

For Ubuntu: Try using sudo ./install_rt.sh - it should download, compile and install the kernel along with systemd-boot. Improvise if the script fails.

Documentation

As the library has the same API as libfranka, you may use official wiki. However, you also can generate documentation with Doxygen using doxygen command. Generated documentation contains information of how the emulator's behavior differs from that of original libfranka (look for [Emulator] sections).

Contributors

• Kyrylo Sovailo
• Original libfranka is owned by Franka Emika GmbH
• Models from model directory were initially generated with Gazebo from ROS package franka_description