A high-fidelity Genesis simulation server that communicates with the Franka robot's network protocol, enabling seamless switching between simulation and hardware.
The Franka Simulation Server provides a drop-in replacement for the real Franka robot, implementing the complete libfranka network protocol. This allows developers to:
- Test and debug robot controllers in simulation before deployment
- Develop applications that work identically on both simulation and hardware
- Validate error handling and safety features
- Experiment with different control strategies risk-free
franka_sim implements the latest libfranka wire protocol — robot server version 10.
In this protocol the robot model is built client-side: during connection the client
fetches the robot URDF via the GetRobotModel command and builds its own Pinocchio model.
The server therefore just serves a valid URDF (a hand-less FR3 arm by default) instead of a
precompiled model library.
You need a libfranka version that speaks server protocol 10:
| libfranka Version | Robot System Version | Robot/Gripper Server |
|---|---|---|
| >= 0.18.0 | >= 5.9.0 | 10 / 3 ✅ supported |
| >= 0.15.0 | >= 5.7.2 | 9 / 3 — not supported |
See the Franka software compatibility matrix
for the full list. Older libfranka releases (server version 9 and below) use a different wire
format — double-based RobotState and server-side LoadModelLibrary instead of GetRobotModel —
and are not compatible with this server.
- libfranka-python - Python bindings for libfranka
- franka-gym - Franka gym implementation
- Native libfranka control
- With Python
In this repository, we only provide the simulation server backend with Genesis connection.
The libfranka python bindings will become available in a separate repository.
The system consists of several key components:
-
libfranka Interface Layer
- Implements the standard Franka robot network protocol
- Handles TCP command interface and UDP state updates
- Targets the latest libfranka wire protocol (robot server version 10)
-
Genesis Simulation Backend
- Physics-based robot simulation using the Genesis engine
- Real-time joint state computation and dynamics
-
State Management
- Complete robot state tracking and synchronization
- Accurate error reporting and status updates
- Real-time state transmission (1kHz update rate)
-
Control Modes
- Joint Position Control
- Joint Velocity Control
- Joint Torque Control
- Supports seamless switching between modes
- Protocol Compatibility: Full implementation of the Franka robot network protocol
- Real-time Simulation: High-frequency state updates and control (1kHz)
- Multiple Control Modes: Supports position, velocity, and torque control
- Error Handling: Replicates real robot error states and recovery
- Python 3.9+
- genesis-world==0.2.1
- numpy==1.26.4
- numba==0.60.0
The package is available on PyPI and can be installed with pip:
pip install franka-sim# Clone the repository
git clone git@github.com:BarisYazici/libfranka-sim.git
# Install the package
cd libfranka-sim/simulation
pip install -e .After installation, you can run the server using the command-line executable:
# Start the server without visualization
run-franka-sim-server
# Start the server with visualization
run-franka-sim-server -vAlternatively, if you installed from source, you can use:
# Start the simulation server
python -m franka_sim.run_server -vIn your application, use standard libfranka commands. The simulation will respond exactly like the real robot.
The gripper server (libfranka gripper protocol, TCP port 1338) runs by default alongside
the arm. Drive it with the standard franka::Gripper client (homing / move / grasp / stop).
# Arm + gripper, kinematic hand (no mesh; width tracked analytically, CI-friendly)
python -m franka_sim.run_server -v
# Arm + gripper, physics-backed Franka Hand: the hand mesh is loaded and the
# finger DOFs are simulated, so homing/move/grasp visibly move the fingers in
# the viewer (grasp succeeds on a finger-position stall against an object)
python -m franka_sim.run_server -v --gripper-physics
# Disable the gripper server entirely
python -m franka_sim.run_server -v --no-gripper| Flag | Gripper backend | Hand in viewer |
|---|---|---|
| (default) | FrankaHandSim (kinematic) |
no |
--gripper-physics |
GenesisFrankaHand (physics) |
yes, fingers move |
--no-gripper |
none (arm only) | no |
If you encounter issues related to missing asset files, make sure you have the correct version of genesis-world installed:
pip install genesis-world==0.2.1The simulator now automatically uses the assets provided by the Genesis package, so no additional asset files are needed.
To switch between simulation and hardware:
-
Update the robot IP address in your application:
- Use
localhostor127.0.0.1for simulation - Use the real robot's IP for hardware
- Use
-
No other changes needed - your application code remains identical
The simulation server currently implements all major features of the Franka robot:
- Complete network protocol implementation
- All joint interfaces
- Real-time state updates
- Visualization support
- Genesis connection
- libfranka python bindings
- v10 wire protocol (Connect, float-based RobotState, GetRobotModel/URDF)
- Robot model via URDF (client-side Pinocchio through GetRobotModel)
- Gripper simulation / Franka Hand (kinematic + Genesis physics,
--gripper-physics) - Automatic error recovery (so
franka_hardware/ franka_ros2 can activate) - Advanced collision detection (in progress)
- Cartesian interfaces (planned)
Contributions are welcome! Please read our contributing guidelines and submit pull requests to our repository.
This project is licensed under the Apache License Version 2.0 - see the LICENSE file for details.
- Franka Robotics GmbH for the original libfranka implementation
- The Genesis Simulator team for the physics engine