franka_desk

Python client for the Franka Desk REST API. Automates the web-UI steps required before libfranka / franka_ros2 can connect to a Franka Research robot: taking the control token, unlocking the joints, and activating the FCI (Franka Control Interface).

Installation

pip install franka_desk

Requires Python ≥ 3.11 and requests. For local development:

pip install -e ".[dev]"   # editable install with pytest + responses

Usage

from franka_desk import FrankaDeskClient

# Context manager: brings the robot up on enter, tears it down on exit.
with FrankaDeskClient("https://<robot-ip>", "<username>", "<password>") as client:
    # FCI is active and joints are unlocked here — connect libfranka / franka_ros2.
    ...
# On exit: FCI deactivated, joints locked, control token released.

Or drive the lifecycle manually:

client = FrankaDeskClient("https://<robot-ip>", "<username>", "<password>")
client.bring_up()      # take token, wait until ready, unlock joints, activate FCI
# ... run your control loop ...
client.tear_down()     # deactivate FCI, lock joints, release token

Individual operations (take_control_token, unlock_joints, activate_fci, reboot, get_system_state, …) are also exposed for finer control.

Errors

All failures raise a subclass of FrankaDeskError, so you can catch broadly or narrowly:

• AuthenticationError — wrong username/password.
• UserStopEngaged — the user/emergency stop is pressed (joints can't unlock).
• TokenUnavailable / TokenExpired — the control token is held elsewhere or stale.
• FrankaConnectionError / ServiceUnavailable / OperationError — transport / 5xx / operation failures.

ROS 2 integration

The franka_desk_bringup package wraps this client in a ROS 2 node (fci_activator) that activates the FCI on startup and publishes the robot's readiness.