# Franka FR3：franka_ros2 安装、FCI 实时内核与 MoveIt 2 规划

> 原文链接：https://robotics.hellobike.com/tutorials/franka-ros2-fci-moveit-setup
> 频道：tutorials | 更新日期：2026-10-22 | 标签：Franka FR3, franka_ros2, ROS 2 humble, MoveIt 2, FCI, real-time kernel
> 核心摘要：本文按官方 README 整理 franka_ros2 本机安装流程，并用 FR3 的 MoveIt 2 dummy hardware 启动验证；同时汇总 FCI 通信实时内核、Docker 与控制器运行注意事项。

# Franka FR3：franka_ros2 安装、FCI 实时内核与 MoveIt 2 规划

> 本文依据以下官方文档整理：[raw.githubusercontent.com/frankarobotics/franka_ros2/humble/](https://raw.githubusercontent.com/frankarobotics/franka_ros2/humble/README.md)。命令与版本以文档当前版本为准。

## 前置条件

- franka_ros2 is built upon ROS 2 humble
- 选择安装 ros-humble-desktop 或 ros-humble-ros-base
- 安装 ros-dev-tools
- franka_ros2 is not officially supported on Windows
- 与机器人通信时，A real-time kernel is essential
- 若使用 Docker，文档推荐 Docker；遇到 UDP receive timeout error 时 avoid using Docker Desktop

## 1. 安装 ROS 2 humble 与开发工具

franka_ros2 基于 ROS 2 humble。先在本机选择 Desktop 或 Bare Bones 其一安装；Desktop 包含 Rviz and Gazebo，Bare Bones 只包含核心 ROS 2 libraries。随后安装 Development Tools，并在需要时 source 环境。

```bash
## replace <YOUR CHOICE> with either ros-humble-desktop or ros-humble-ros-base
sudo apt install <YOUR CHOICE>
```

```bash
sudo apt install ros-dev-tools
```

```bash
source /opt/ros/humble/setup.sh
```

## 2. 创建 ROS 2 工作空间并克隆 franka_ros2

创建工作空间时，文档要求进入 ~/franka_ros2_ws，而不是进入 src。随后把 franka_ros2 仓库克隆到 src 目录，后续依赖导入、rosdep 与 colcon build 都在该工作空间根目录执行。

```bash
mkdir -p ~/franka_ros2_ws/src
cd ~/franka_ros2_ws  # not into src
```

```bash
git clone https://github.com/frankarobotics/franka_ros2.git src
```

## 3. 导入依赖、安装项目依赖并构建

仓库包含 dependency.repos，用于克隆 Franka ROS 2 所需依赖。导入后用 rosdep 检测并安装项目依赖，最后用 Release 配置构建；--symlink-install 用于减少磁盘占用并便于开发。

```bash
vcs import src < src/dependency.repos --recursive --skip-existing
```

```bash
rosdep install --from-paths src --ignore-src --rosdistro humble -y
```

```bash
## use the --symlinks option to reduce disk usage, and facilitate development.
colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTS=OFF
```

## 4. 加载工作空间环境并运行构建测试

构建完成后，需要让当前 shell 识别新构建 ROS 2 workspace 里的 packages and dependencies。之后可运行 colcon test 测试构建；文档提示 franka_ros2 仍在开发中，因此 Warnings can be expected。

```bash
## Adjust environment to recognize packages and dependencies in your newly built ROS 2 workspace.
source install/setup.sh
```

```bash
colcon test
```

## 5. 启动 FR3 MoveIt 2 dummy hardware 示例

没有机器人时，可用 dummy hardware 验证安装是否可用。FR3 示例通过 franka_fr3_moveit_config 启动 MoveIt。可用 load_gripper 激活或关闭末端执行器，用 ee_id 选择 end-effector；默认启用 Franka Hand。

```bash
ros2 launch franka_fr3_moveit_config moveit.launch.py robot_ip:=dont-care use_fake_hardware:=true
```

## 6. 运行示例控制器或为多机器人指定控制器

运行示例控制器前，先在 franka.config.yaml 中加入所需配置，然后指定 controller_name。控制器可从 controllers.yaml 中选择；多机器人时可用 controller_names 指定多个控制器，少于机器人数量时仅第一个会用于所有机器人。

```bash
ros2 launch franka_bringup example.launch.py controller_name:=your_desired_controller
```

```bash
ros2 launch franka_bringup example.launch.py controller_names:="cartesian_elbow_example_controller,joint_impedance_example_controller,cartesian_velocity_example_controller"
```

## 验证是否跑通

确认 colcon build 完成后执行 source install/setup.sh，并运行 colcon test。无机器人验证时执行 ros2 launch franka_fr3_moveit_config moveit.launch.py robot_ip:=dont-care use_fake_hardware:=true；该命令用于启动 dummy hardware 的 MoveIt 示例。文档说明 franka_ros2 under development，Warnings can be expected。

## 文档里点名的注意事项

- franka_ros2 is not officially supported on Windows.
- This package is in rapid development. Users should expect breaking changes.
- 如果使用 namespace，需要使用 argument namespace，并在 moveit.rviz 的 Move Group Namespace 中手动写入 namespace。
- 遇到 libfranka: UDP receive: Timeout error 时，avoid using Docker Desktop；Docker Desktop may not provide the necessary real-time capabilities required for reliable communication with the robot.
- A real-time kernel is essential to ensure proper communication and to prevent timeout issues.
- If less controllers than the number of robots are specified, only the first controller would be used for all the robots.

## 相关 SDK 条目

- [franka_ros2](/sdks/frankarobotics-franka-ros2)

## 原始参考来源 (Sources)

- [raw.githubusercontent.com/frankarobotics/franka_ros2/humble/README.md](https://raw.githubusercontent.com/frankarobotics/franka_ros2/humble/README.md)