Franka Simulation Server

A high-fidelity simulation server that communicates with the Franka robot's network protocol, enabling seamless switching between simulation and hardware. Runs on MuJoCo by default; Genesis is available as an optional backend.

Overview

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

Compatibility

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:

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.

Related Projects

• libfranka-python - Python bindings for libfranka
• franka-gym - Franka gym implementation

Preview Video

• Native libfranka control

• With Python

Architecture

In this repository, we only provide the simulation server backend, with a choice of physics engines behind it (MuJoCo by default, Genesis optionally).

The libfranka python bindings will become available in a separate repository.

The system consists of several key components:

1. 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)

2. Physics Simulation Backend

   • Physics-based robot simulation using MuJoCo (default) or Genesis (--physics genesis)
   • Real-time joint state computation and dynamics

3. State Management

   • Complete robot state tracking and synchronization
   • Accurate error reporting and status updates
   • Real-time state transmission (1kHz update rate)

4. Control Modes

   • Joint Position Control
   • Joint Velocity Control
   • Joint Torque Control
   • Supports seamless switching between modes

Key Features

• 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

Getting Started

Prerequisites

• Python 3.9+
• numpy==1.26.4
• mujoco>=3.2,<3.3 (the default physics backend, installed automatically)

Genesis is an optional backend (--physics genesis) — see below.

Installation

Option 1: Install from PyPI (Recommended)

The package is available on PyPI and can be installed with pip. This pulls in MuJoCo, the default physics backend:

pip install franka-sim

To also use the Genesis backend, install the genesis extra:

pip install 'franka-sim[genesis]'

Option 2: Install from Source

# Clone the repository
git clone git@github.com:BarisYazici/libfranka-sim.git

# Install the package
cd libfranka-sim/simulation
pip install -e .

Basic Usage

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 -v

Alternatively, if you installed from source, you can use:

# Start the simulation server
python -m franka_sim.run_server -v

In your application, use standard libfranka commands. The simulation will respond exactly like the real robot.

Testing in CI (no robot required)

Because the sim speaks the real wire protocol, your libfranka / franka_ros2 code can be regression-tested on every push. Three ways in — see the Testing in CI guide for details:

# GitHub Actions: start a simulated FR3, then run your tests against 127.0.0.1
- uses: BarisYazici/libfranka-sim@v1
  with:
    args: '--enforce-comm-constraints --enforce-motion-limits'

# Docker: self-contained image (models baked in, works offline)
docker run -d --network host ghcr.io/barisyazici/franka-sim
docker exec <container> franka-sim-check --timeout 30   # readiness gate

# pytest: `pip install franka-sim` ships a plugin; one server per session on a free port
def test_my_controller(franka_sim_server):
    connect_my_stack(franka_sim_server.host, franka_sim_server.port)

With --enforce-comm-constraints and --enforce-motion-limits the sim aborts motions the way the real FCI does (lost-cycle reflexes, discontinuity limits), so your error-recovery paths get exercised in CI instead of on hardware.

Gripper (Franka Hand)

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 (as on the real hand, a grasp closes the fingers until they stall
# and succeeds only if the stall width is within epsilon of the commanded one,
# so grasping thin air returns false)
python -m franka_sim.run_server -v --gripper-physics

# Disable the gripper server entirely
python -m franka_sim.run_server -v --no-gripper

# The scene holds nothing graspable, so a grasp of thin air correctly returns
# false. Put a 4 cm virtual object between the fingers (either backend) when a
# client -- franka_ros2's franka_gripper Grasp action, a pick-and-place demo --
# needs a grasp to succeed:
python -m franka_sim.run_server --gripper-object-width 0.04

Mobile duo (two arms + TMR base on one scene)

--mobile-duo serves the mobile FR3 duo: one physics scene (both arms and the TMR mobile base, physically rigid to each other) driven by three FCI bridges, one per role. libfranka clients cannot be told to use a port other than 1337, so the bridges are separated by host IP instead — each is bound to its own loopback alias with --bind ROLE=HOST, repeated once per role (left, right, base):

# Bring up the loopback aliases once per boot (Linux; 127.0.0.0/8 is all loopback)
sudo ip addr add 127.0.0.11/8 dev lo 2>/dev/null
sudo ip addr add 127.0.0.12/8 dev lo 2>/dev/null
sudo ip addr add 127.0.0.13/8 dev lo 2>/dev/null  # only needed with --spine

python -m franka_sim.run_server --mobile-duo \
  --scene-urdf /path/to/mobile_fr3_duo.urdf \
  --mesh-root  /path/to/franka_description \
  --bind left=127.0.0.11 \
  --bind right=127.0.0.12 \
  --bind base=127.0.0.10

By convention this repo uses three loopback aliases on 127.0.0.0/8, one per role, plus a fourth for the spine device:

Every bridge still listens on the standard libfranka command port (1337); override it for all three at once with --port.

Physics backend. MuJoCo is the default (--physics mujoco, or just omit the flag) and is installed as a core dependency. --physics genesis runs the same scene on Genesis instead, and needs the genesis extra: pip install 'franka-sim[genesis]'. Genesis' per-call kernel-launch overhead caps the scene at ~0.4x real time at its 2.5 ms step; MuJoCo holds 1.00x real time at a 1 ms step — the rate the FCI bridges actually serve — using about a third of one core. The protocol surface, the joint and link names, the initial pose and the reported state are identical between the two, so a client cannot tell them apart. Contacts are disabled on the MuJoCo path (the chassis' URDF collision meshes interpenetrate as authored, and nothing in this scene depends on contact: the base pose is integrated kinematically and both arms are servo-driven).

Generating --scene-urdf. scripts/generate_mobile_duo_urdf.sh <franka_description_dir> <output.urdf> runs the upstream xacro with the options this server expects (hand:=false, explicit robot_types, no ROS 2 control/Gazebo) from a sourced ROS 2 Jazzy environment. It asserts the franka_description checkout is pinned to the exact sha the mesh paths and joint names were generated against, and refuses to run otherwise — a different checkout can silently rename meshes or joints out from under the sim.

The fake spine device. The duo's prismatic lift (franka_spine_vertical_joint) is driven by a separate REST device on real hardware, not by libfranka. --spine runs a fake version of that device in-process (franka_sim.mobile.spine_stub) and shares its motion model with the scene, so a REST move visibly raises the lift (and everything mounted on it — the head and both arms) in the viewer:

python -m franka_sim.run_server --mobile-duo \
  --scene-urdf /path/to/mobile_fr3_duo.urdf --mesh-root /path/to/franka_description \
  --bind left=127.0.0.11 --bind right=127.0.0.12 --bind base=127.0.0.10 \
  --spine

The spine stub also runs standalone via the run-franka-spine-stub console script (installed with the package), useful for exercising just the REST device without a physics scene:

run-franka-spine-stub --host 127.0.0.13 --port 443

Cartesian-velocity protocol mode. The TMR base has no joint interface, so it is driven by libfranka's kCartesianVelocity motion generator: the client's commanded body-frame twist (O_dP_EE_c) is routed straight to the base's swerve inverse kinematics instead of to a joint position/velocity/ torque path.

Environment variables.

Troubleshooting

If you're running the Genesis backend (--physics genesis) and encounter issues related to missing asset files, make sure you have the genesis extra installed with the correct version of genesis-world:

pip install 'franka-sim[genesis]'

The simulator automatically uses the assets provided by the Genesis package, so no additional asset files are needed. Note that genesis-world==0.2.1 also needs libigl<2.6 (newer libigl changes igl.signed_distance's return arity); install that pin alongside the extra if Genesis import fails with an unpacking error.

Configuration

Switching Between Simulation and Hardware

To switch between simulation and hardware:

1. Update the robot IP address in your application:

   • Use localhost or 127.0.0.1 for simulation
   • Use the real robot's IP for hardware

2. No other changes needed - your application code remains identical

Development Status

What the simulator implements today, checked against the real robot's own clients rather than against a spec:

• libfranka v10 wire protocol: Connect, 1 kHz float RobotState, GetRobotModel (URDF), Move / StopMove / SetCollisionBehavior / AutomaticErrorRecovery
• All joint interfaces: joint position, joint velocity, torque (external controller), with q_d/dq_d echoed as the robot does
• Cartesian interfaces: Cartesian pose and Cartesian velocity, with and without elbow (exercised by franka_ros2's cartesian_pose, cartesian_velocity, cartesian_orientation and cartesian_elbow example controllers)
• Physics backends: MuJoCo (default, FR3 from MuJoCo Menagerie) and Genesis
• Gripper / Franka Hand server on 1338: kinematic by default, physics-simulated fingers with --gripper-physics, --no-gripper to disable
• Automatic error recovery, so franka_hardware / franka_ros2 can activate and recover on their own
• Motion-limit checks with the robot's error names: joint/Cartesian velocity, acceleration and jerk discontinuities, torque rate, elbow limit / sign / start-elbow, self-collision avoidance (MuJoCo contact margin, per link pair) — logged always, enforced as reflex aborts with --enforce-motion-limits
• The joint side of the Cartesian generators: every commanded pose is solved to joint space and its joint velocity / acceleration steps judged per joint (cartesian_motion_generator_joint_velocity_discontinuity / ..._joint_acceleration_discontinuity), against the simulated robot's own tables — the FER's when serving FCI v5 (calibrated against a real Panda), the FR3's published limits when serving v10 (not yet confirmed against an FR3) — --joint-discontinuity-scale / FRANKA_SIM_JOINT_DISCONTINUITY_SCALE to re-tune
• Communication-constraint checks: lost-cycle extrapolation and communication_constraints_violation with --enforce-comm-constraints
• Visualization (MuJoCo viewer, --vis) that never teleports the robot: a stalled render slows the simulation instead of bursting physics steps
• CI-first packaging: Docker image, GitHub Action (BarisYazici/libfranka-sim@v1), pytest plugin, franka-sim-check
• Verified against Franka's own hardware smoke suite in franka_ros2 (jazzy): 47/47 on the simulator, permissive and with motion limits enforced
• Contact-force reflexes (cartesian_reflex / joint_reflex from SetCollisionBehavior thresholds): the arm has no external-force estimate yet
• Reflex state persisting across client reconnects (the sim resets on disconnect; the robot stays in reflex until recovery)

Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests to our repository.

License

This project is licensed under the Apache License Version 2.0 - see the LICENSE file for details.

Acknowledgments

• Franka Robotics GmbH for the original libfranka implementation
• The Genesis Simulator team for the physics engine