Franka setup

1. Select the SDK for your controllerCopy Anchor Link

Check the robot's system version in Desk Settings. Create and activate the Python environment from Install RoboAPI, then choose the matching command:

# FR3, system 5.9+
uv pip install 'roboapi[franka,gripper]==0.4.5'

# FR3, system 5.6.0
uv pip install 'roboapi[franka,gripper]==0.4.5' 'franky-control==2.0.0+libfranka.0.13.3' --index https://timschneider42.github.io/franky/whl/libfranka-0.13.3/

# Panda, system 4.2.1–4.x
uv pip install 'roboapi[franka,gripper]==0.4.5' 'franky-control==2.0.0+libfranka.0.9.2' --index https://timschneider42.github.io/franky/whl/libfranka-0.9.2/

All Franka models use the franka extra. For FR3 system 5.6.0 and Panda, keep both the explicit SDK build version and index URL in the command. Install only one SDK build per Python environment. Panda 4.x systems older than 4.2.1 require a robot system update first. The control computer needs Linux x86-64, Python 3.10–3.12, and glibc 2.28 or newer.

2. Prepare the realtime host and DeskCopy Anchor Link

Follow Franka's realtime kernel guide and allow the account running RoboAPI to use SCHED_FIFO priority 99. Log in again, then check this in the terminal that will launch RoboAPI:

ulimit -r

The result must be at least 99. An MCP client or system service must give its launch process the same scheduling permission.

Connect through the cabinet's Shop Floor interface using the official wired FCI setup. Confirm that FCI is available in Desk's system settings. Have the Desk username and password ready for roboapi init.

3. Initialize and configure the toolCopy Anchor Link

Use the flange centre as the control point, with zero TCP translation and axes aligned with the flange. Run setup and select the arm, gripper, and camera:

roboapi init

Select standard assembly data matching your hardware, or enter the mass, centre of mass, and inertia of your custom assembly. Include the complete flange-mounted gripper, camera, and adapters. Setup stores the result in the local tool configuration. See Tool load for fields.

On FR3 system 5.9+, RoboAPI applies and reads back this local load during calibration and control initialization. For FR3 system 5.6.0 and Panda, export it after setup:

roboapi export-franka-tool --output endeffector-config.json

Export reads the saved local configuration and needs no robot connection. Add -c /path/to/config.yaml for a custom configuration. Configure Desk with an administrator account:

• FR3 5.6.0: open Settings → End Effector → Mechanical Data, choose User Defined, and upload the file.
• Panda 4.x: open Admin → End Effector from the user menu, then choose User Defined. Import the file if Upload is available. Otherwise enter its mass, centre of mass, and inertia, and set the flange-to-TCP transform to identity.

If Desk is open on another computer, copy the file there first. Export does not overwrite existing files; use another path when exporting again. RoboAPI reads back the load and TCP. Correct any reported mismatch in Desk before retrying.

To export only the shipped standard assembly without local installation settings, use roboapi export-franka-tool --standard --output standard-endeffector-config.json. For deployment, use the local-load export workflow above.

4. Start and calibrateCopy Anchor Link

roboapi http

1. Open http://127.0.0.1:8080/ on the control computer. Initial preview reads state through Desk without changing brakes, FCI, or operating mode. For access from another computer, see installation.
2. If another Desk page owns control, release it there before opening Settings → Devices → Coordinate calibration.
3. Use the robot's guiding button to capture Home and A/B/C as described in Coordinate calibration. After Home, select one translation axis at a time; rotation remains constrained.
4. Return to point 1 and the Home return after C briefly use FCI, then restore Programming mode. The browser automatically saves calibration and initializes the arm and gripper.
5. Perform the optional direction checks, select Done, and send a task from the local console.

RoboAPI manages Programming / Execution mode, FCI, and brake unlocking as needed. Automatic returns and control initialization move the hardware. Keep the motion area clear.

Later starts and recoveryCopy Anchor Link

Later starts reuse saved calibration and open read-only preview. Select Enable control to initialize devices; this does not return the arm Home. Use Home when needed. Recover & Home recovers the devices and moves the arm Home.

Recalibrate when the assembly, Home, or task axes change. If Desk requires a self-test or shows a condition that FCI cannot clear, resolve it in Desk before retrying.

Control connections set contact and collision thresholds to 100 N·m per joint, 100 N Cartesian force, and 100 N·m Cartesian torque. These settings do not replace physical separation and stopping measures at the workstation.