franky.Desk¶

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

Bases: BaseDesk

Robot web session for the current Franka Desk API (v1).

Uses HTTP Basic authentication on every request. Compatible with FR3 on System 5+ firmware. For older firmware, use DeskWebSession.

__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.

disable_fci()¶: Disable the Franka Control Interface (FCI). Requires control over the robot.

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

execute_self_test()¶: Execute the safety self-test and wait for it to finish. Requires control over the robot.

get_fci_status() → str¶: Return the current status of the Franka Control Interface (FCI).

get_recovery_status() → dict | None¶: Return the active recovery descriptor, or None if no recovery is needed.

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.

reboot() → None¶: Initiate a system reboot. Closes all open connections.

recover() → None¶

Attempt to clear an active recoverable safety error.

Handles errors that can be confirmed programmatically (LifetimeStatusExceeded, SelfTestsElapsed, GenericJointError, SafetyError, SafeInputUnacknowledged, SafetyRuleViolation). Raises DeskError for errors that require physical joint movement (JointPositionError, JointLimitViolation). Does nothing if no recovery is needed.

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.

set_mode_execution()¶: Set the operating mode to Execution. Requires control over the robot.

shutdown() → None¶: Initiate a system shutdown.

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.

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.