Metadata-Version: 2.4
Name: franka_desk
Version: 0.1.0
Summary: Python client for the Franka Desk REST API (FCI, joints, safety, configuration)
License: MIT
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: responses>=0.23; extra == "dev"

# franka_desk

Python client for the [Franka Desk](https://franka.de) 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

```bash
pip install franka_desk
```

Requires Python ≥ 3.11 and `requests`. For local development:

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

## Usage

```python
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:

```python
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`](../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.
