franky.BaseDesk

class franky.BaseDesk(hostname: str, username: str, password: str, token_storage: bool | str | PathLike = False)

Bases: ABC

Base class for sessions with the Franka Desk web interface.

The Desk classes allow controlling robot functions that are otherwise only available through the Franka Desk web interface, such as unlocking the brakes, enabling the FCI, or reacting to Pilot button presses.

Parameters:

  • hostname – Hostname or IP address of the robot.

  • username – Username to log into Franka Desk.

  • password – Password to log into Franka Desk.

  • token_storage – Whether and where to persist control tokens.

__init__(hostname: str, username: str, password: str, token_storage: bool | str | PathLike = False)
close()

Release control if held, and close the connection to Franka Desk.

abstractmethod enable_fci()

Enable the Franka Control Interface (FCI). Requires control over the robot.

abstractmethod execute_self_test()

Execute the safety self-test and wait for it to finish. Requires control over the robot.

abstractmethod lock_brakes()

Lock the joint brakes. Requires control over the robot.

open(timeout: float = 30.0)

Open the connection to Franka Desk and log in.

Instead of calling this method directly, the session can also be used as a context manager.

Parameters:

timeout – Connection timeout [s].

poll_buttons(timeout: float | None = 0.0) → list[PilotButtonEvent]

Poll for Pilot button events, returning all currently available.

Parameters:

timeout – Maximum seconds to wait for the first event. 0.0 (default) returns immediately with any buffered events. None blocks until at least one event is available. After the first event arrives, any additional buffered events are drained without waiting.

Returns:

List of button events, or an empty list if none arrived within the timeout.

release_control()

Release control over the robot, allowing other users to take it.

send_api_request(path: str, headers: dict[str, str] | None = None, content: dict[str, Any] | None = None, content_encoding: Literal['json', 'x-www-form-urlencoded'] = 'json', method: Literal['GET', 'POST', 'DELETE'] = 'POST', response_encoding: Literal['json', 'text'] | None = None) → Any

Send a request to the Franka web API and parse the response.

Parameters:

  • path – Path of the API endpoint, e.g. “/api/system”.

  • headers – Additional HTTP headers. Overrides the content-type header derived from content_encoding if set.

  • content – Request payload, encoded according to content_encoding.

  • content_encoding – How to encode the payload.

  • method – HTTP method to use.

  • response_encoding – How to decode the response. If None, it is derived from the response content type.

Returns:

The parsed response, or None if the response is empty.

Raises:

FrankaAPIError – If the API returns an error response.

send_control_api_request(path: str, headers: dict[str, str] | None = None, content: dict[str, Any] | None = None, content_encoding: Literal['json', 'x-www-form-urlencoded'] = 'json', method: Literal['GET', 'POST', 'DELETE'] = 'POST', response_encoding: Literal['json', 'text'] | None = None) → Any

Send a request that requires control over the robot to the Franka web API.

Same as send_api_request, but includes the control token in the request. Requires take_control to have been called first.

send_raw_api_request(path: str, headers: dict[str, str] | None = None, body: Any | None = None, method: Literal['GET', 'POST', 'DELETE'] = 'POST') → bytes

Send a request with a raw body to the Franka web API and return the raw response.

send_raw_control_api_request(path: str, headers: dict[str, str] | None = None, body: Any | None = None, method: Literal['GET', 'POST', 'DELETE'] = 'POST') → bytes

Send a raw request that requires control over the robot to the Franka web API.

Same as send_raw_api_request, but includes the control token in the request. Requires take_control to have been called first.

abstractmethod set_mode_execution()

Set the operating mode to Execution. Requires control over the robot.

take_control(wait_timeout: float = 30.0, force: bool = False)

Obtain exclusive control over the robot.

Control is required for all operations that change the state of the robot, such as unlocking the brakes or enabling the FCI.

Parameters:

  • wait_timeout – Maximum time to wait for control to be granted [s].

  • force – Whether to take control even if another user currently holds it. Depending on the API version, forcibly taking control may require pressing a physical button on the robot within the timeout.

Raises:

TakeControlTimeoutError – If control was not granted within the timeout.

abstractmethod unlock_brakes()

Unlock the joint brakes. Requires control over the robot.

property brake_state: BrakeState

The current state of the joint brakes.

property client: HTTPSConnection

The underlying HTTPS connection to the robot.

property control_token: str | None

The current control token, or None if this session does not hold control.

property control_token_id: str | NoTokenIdType | None

The ID of the current control token, or None if this session does not hold control.

Is NO_TOKEN_ID on API versions that grant control without reporting a token ID.

property has_control

Whether this session currently holds control over the robot.

property hostname: str

Hostname or IP address of the robot.

property is_open: bool

Whether the session is currently open.

property operating_mode: OperatingMode

The current operating mode of the robot.

property password: str

Password used to log into Franka Desk.

property system_status: dict[str, Any]

The system status as reported by the Franka web API.

property username: str

Username used to log into Franka Desk.