Franka 部署
为 FR3 或 Panda 选择 SDK，配置实时控制机、Desk 与末端工具。
1. 按控制器系统选择 SDK
在 Desk Settings 查看机器人系统版本，在软件安装中创建并激活 Python 环境，再选择对应命令：
| 控制器系统 | 安装选项 | SDK |
|---|---|---|
| FR3，5.9+ | franka,gripper | franky-control 2.x |
| FR3，5.6.0 | franka,gripper | 对应 libfranka 0.13.3 的构建 |
| Panda，4.2.1–4.x | franka,gripper | 对应 libfranka 0.9.2 的构建 |
# FR3，系统 5.9+
uv pip install 'roboapi[franka,gripper]==0.4.5'# FR3，系统 5.6.0
uv pip install 'roboapi[franka,gripper]==0.4.5' 'franky-control==2.0.0+libfranka.0.13.3' --index https://timschneider42.github.io/franky/whl/libfranka-0.13.3/# Panda，系统 4.2.1–4.x
uv pip install 'roboapi[franka,gripper]==0.4.5' 'franky-control==2.0.0+libfranka.0.9.2' --index https://timschneider42.github.io/franky/whl/libfranka-0.9.2/所有 Franka 机型统一使用 franka 安装选项。FR3 系统 5.6.0 和 Panda 的命令同时指定 SDK 构建版本与下载索引，不要省略这两项。每个 Python 环境只安装一种 SDK。早于 4.2.1 的 Panda 4.x 系统需先升级机器人系统。控制电脑需运行 Linux x86-64、Python 3.10–3.12，并提供 glibc 2.28 或更新版本。
2. 准备实时控制电脑和 Desk
按 Franka 官方说明配置实时内核，并允许启动账户使用 SCHED_FIFO 优先级 99。重新登录后，在启动 RoboAPI 的终端检查：
ulimit -r结果应至少为 99。通过 MCP 客户端或系统服务启动时，启动进程同样需要这项调度权限。
通过控制箱的 Shop Floor 接口建立有线 FCI 连接，确认 Desk 系统设置中 FCI 可用。准备好 Desk 用户名和密码，供 roboapi init 使用。
3. 初始化并配置末端工具
控制点是法兰中心，TCP 平移为零，坐标轴与法兰对齐。先运行初始化向导，选择机械臂、夹爪与相机：
roboapi init在末端装配选项中，选择与你的硬件匹配的标准装配，或填写自定义装配的质量、质心和惯量。数据覆盖法兰上的完整夹爪、相机与适配件，并保存到本地配置的 tool 部分。字段含义见工具负载。
FR3 系统 5.9+ 会在标定与控制初始化时应用本地配置的工具参数并读取核对。FR3 系统 5.6.0 和 Panda 在初始化后导出配置：
roboapi export-franka-tool --output endeffector-config.json导出读取已保存的本地配置，不需要连接机器人。使用自定义配置位置时，加上 -c /path/to/config.yaml。用管理员账户在 Desk 配置：
- FR3 5.6.0：打开 Settings → End Effector → Mechanical Data，选择 User Defined，上传文件。
- Panda 4.x：打开用户菜单中的 Admin → End Effector，选择 User Defined。页面提供 Upload 时导入文件；否则按文件填写质量、质心和惯量，并将法兰到 TCP 的变换设为单位变换。
如果 Desk 在另一台电脑打开，先将文件复制到该电脑。导出命令不会覆盖已有文件，再次导出时选择其他路径。RoboAPI 会读取并核对实际负载与 TCP；收到不一致提示时，修正 Desk 设置后重试。
仅需导出随包的标准装配数据时，可使用 roboapi export-franka-tool --standard --output standard-endeffector-config.json，无需本地安装配置。正常部署使用上面的本地负载导出流程。
4. 启动并标定
roboapi http- 在控制电脑打开
http://127.0.0.1:8080/。初次预览通过 Desk 读取状态，不改变刹车、FCI 或操作模式。从其他电脑访问的方法见安装指南。 - 如其他 Desk 页面占用控制权，先在那里释放控制权，再进入 设置 → 设备 → 坐标标定。
- 按坐标标定用本体引导按钮采集初始位置与 A/B/C。采集初始位置后，每次选择一个平移轴进行引导，旋转保持约束。
- 返回第1点和采 C 后返回初始位置会短暂启用 FCI，返回完成后恢复 Programming 模式。网页随后自动保存标定，初始化机械臂和夹爪。
- 按需完成方向试动，选择 完成，进入本地控制台发送任务。
RoboAPI 按操作需要处理 Programming / Execution 模式、FCI 和刹车解锁；自动返回和控制初始化会使设备运动。保持运动区域畅通。
再次运行与恢复
再次启动时沿用已保存的标定，先进入只读预览。选择 启用控制 初始化设备；这一步不会自动回到初始位置。需要返回时使用 初始位置；恢复并返回初始位置 会恢复设备并移动到初始位置。
改变装配、初始位置或任务坐标轴后重新标定。Desk 出现需完成的自检或无法通过 FCI 清除的条件时，先在 Desk 处理，再重试。
控制连接的接触／碰撞阈值为每个关节 100 N·m、笛卡尔力 100 N、力矩 100 N·m。这些设置不替代现场隔离和停止措施。