Server Functions
Top-level functions for robot lifecycle management, available as aiofranka.unlock(), aiofranka.lock(), etc.
- aiofranka.server.unlock(ip=None, *, username=None, password=None, protocol='https')[source]
Unlock the robot joints (open brakes) and activate FCI.
The control token is kept (saved to disk) so FCI stays active. Call lock() to deactivate FCI, lock joints, and release the token.
If a server is running, this is a no-op (robot is already unlocked).
- aiofranka.server.lock(ip=None, *, username=None, password=None, protocol='https')[source]
Deactivate FCI, lock the robot joints (close brakes), and release the control token.
If a saved token exists (from a previous unlock()), it is reused. If a server is running, raises RuntimeError — use stop() instead.
- aiofranka.server.start(ip=None, *, foreground=False, unlock=True, username=None, password=None, protocol='https', lock_on_error=False, timeout=60.0)[source]
Start the aiofranka server from a Python script.
When ip, username, or password are not provided, values are read from ~/.aiofranka/config.json (same config the CLI uses). If no config exists, the user is prompted interactively.
- Parameters:
ip (str) – Robot IP address (default: from config or 172.16.0.2).
foreground (bool) – If True, blocks and runs in the current process.
unlock (bool) – Auto-unlock joints and activate FCI.
username (str) – Franka Desk web UI username (default: from config, or prompts).
password (str) – Franka Desk web UI password (default: from config, or prompts).
protocol (str) – “http” or “https”.
lock_on_error (bool) – If True, lock joints when the server dies due to a control error. If False (default), joints are left unlocked on error so you can recover.
timeout (float) – Seconds to wait for the server to become ready (ignored if foreground).
- Returns:
The server PID (0 if foreground, since it blocks).
- Raises:
RuntimeError – If the server fails to start within the timeout or encounters an error.
- Return type:
- aiofranka.server.stop(ip=None, *, timeout=30.0)[source]
Stop the aiofranka server from a Python script.
- Parameters:
- Raises:
RuntimeError – If no server is running or it fails to stop in time.
- Return type:
None
- aiofranka.server.set_configuration(ip=None, *, mass=None, com=None, inertia=None, translation=None, rotation=None, ee_name=None, username=None, password=None, protocol='https')[source]
Set end-effector configuration on the robot via the Franka Desk API.
Uses the saved control token from a previous unlock(). Only the parameters you provide are updated; omitted parameters are left unchanged.
- Parameters:
ip (str) – Robot IP address (default: from config or 172.16.0.2).
mass (float) – End-effector mass in kg.
inertia (list[float]) – Inertia matrix as [x11, x12, x13, x22, x23, x33] in kg*m^2.
translation (list[float]) – F_T_EE translation [x, y, z] in meters.
rotation (list[float]) – F_T_EE rotation [roll, pitch, yaw] in radians.
ee_name (str) – End-effector name (default: current or “custom”).
username (str) – Franka Desk web UI username.
password (str) – Franka Desk web UI password.
protocol (str) – “http” or “https”.
- Returns:
The updated configuration from the robot.
- Return type:
- Raises:
RuntimeError – If no saved token exists and token cannot be acquired, or if the configuration update fails.
Example
>>> import aiofranka >>> aiofranka.unlock("172.16.0.2") >>> aiofranka.set_configuration(mass=0.5, com=[0, 0, 0.05]) >>> aiofranka.lock("172.16.0.2")