FrankaTwin

Contents

FrankaTwin#

Current version: v0.3 — package frankatwin 0.3.0, git branch v0.3. This documentation describes v0.3; what changed is in the changelog.

FrankaTwin — sim ↔ real

A 1 kHz task impedance controller for the Franka Research 3 / Panda whose simulation twin is the same controller — plus the system identification that that brings the twin’s joint-position error on a held-out run down to 28 mrad RMSE over all seven joints, 16.5× below the PhysX defaults.

  • Task impedance control, identical in sim and on the robot. osc_shm (libfranka, 1 kHz) and the IsaacLab controller are the same task-space impedance law with the same gains and damping rule — the control scheme used by sim-to-real work such as IndustReal and OmniReset.

  • System identification that closes the loop. A CMA-ES fit of 29 parameters (armature, static / dynamic / viscous friction, motor delay) drives the sim replay of real excitation runs — 3.6 mm end-effector and 28 mrad joint-position RMSE on a held-out chirp at gains the fit never saw, 5.4× and 16.5× better than the PhysX defaults.

  • Small and auditable. ~1 600 lines of C++ and ~3 300 lines of Python (excluding blanks and comments), POSIX shared memory + ZMQ in between. No ROS.

        flowchart LR
    subgraph PC["PC · your workstation"]
        C["FrankaTwinClient<br/>examples/*.py"]
    end
    subgraph NUC["NUC · PREEMPT_RT kernel"]
        D["frankatwin.daemon"]
        S[("POSIX shm<br/>/frankatwin_osc")]
        O["osc_shm<br/>C++ · 1 kHz task impedance"]
        M["move_to<br/>C++ · one-shot position control"]
        D --- S
        S --- O
        D -. "stop / start" .- O
        D -. "reset" .- M
    end
    subgraph ROBOT["Franka FR3"]
        R["FCI"]
    end
    C -- "ZMQ REQ · 5555 · ≤ 50 Hz" --> D
    D -- "ZMQ PUB · 5556 · 100 Hz" --> C
    O <== "libfranka · 1 kHz" ==> R
    M <== "libfranka" ==> R

Start with Installation, then Usage — every command is tagged NUC / PC / SIM with the machine it runs on. The reference (architecture and wire protocols, configuration, API from docstrings, data formats, troubleshooting) is in the sidebar.

Citation#

FrankaTwin was developed in support of our visual sim-to-real manipulation research. If you use FrankaTwin in your research, please cite our accompanying paper:

@misc{sun2026visualsimtoreallearningrobotic,
  title={Visual Sim-to-Real Learning for Robotic Insertion under Geometric Variations: Application to Rebar Installation},
  author={Tao Sun and Beining Han and Patrick Yin and Rui Xu and Harry He and Abhishek Gupta and Szymon Rusinkiewicz and Yi Shao},
  year={2026},
  eprint={2609.20477},
  archivePrefix={arXiv},
  primaryClass={cs.RO},
  url={https://arxiv.org/abs/2609.20477}
}

For reproducibility, you can also record the FrankaTwin version or commit used in your experimental setup.

Contents