面向 Rust 的 ROS 2

简介

这是一组项目（包括 rclrs 客户端库、代码生成器、示例等），让开发者能够使用 Rust 编写 ROS 2 应用程序。

功能与限制

当前功能包括：

• 消息生成，支持所有 ROS 消息类型
• 发布者和订阅者（包括异步变体）
• 租借消息（零拷贝消息）
• 动态消息处理（运行时消息内省与操作）
• 可调节的 QoS 设置
• 客户端和服务（包括异步变体）
• 动作（支持异步的动作服务器和客户端）
• 定时器（重复、一次性以及惰性定时器）
• 参数（必选、可选和只读，并支持参数服务）
• 日志记录，提供符合 ROS 的日志工具并支持 rosout
• 图查询（主题/节点发现、端点信息）
• 保护条件与等待集
• 时钟与时间 API（包括时间源）
• 用于在回调之间管理共享状态的 Worker 模式
• 用于协调节点执行的 Executor 模式

然而，仍有一些功能缺失，请参阅 问题列表 查看概览。我们非常欢迎你 参与贡献！

由于客户端库仍在快速演进，目前不提供稳定性保证。

安装

前置条件

首先，安装 Rust 及所需的系统依赖项：

# Install Rust (see https://rustup.rs/)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Install required system packages
sudo apt install -y git libclang-dev python3-pip python3-vcstool

# Install colcon plugins for Rust
pip install --break-system-packages colcon-cargo colcon-ros-cargo

由于 rclrs 中存在一个问题（https://github.com/ros2-rust/ros2_rust/issues/557），作为临时解决方案，需要安装以下两个包：

# Install workaround packages
sudo apt install -y ros-$ROS_DISTRO-example-interfaces
sudo apt install -y ros-$ROS_DISTRO-test-msgs

所有 ROS 发行版

rclrs 已在 crates.io 发布，你可以直接将其添加到项目中：

[dependencies]
rclrs = "0.7"

由于各 ROS 2 发行版与 rclrs 的集成程度不同，如需构建并运行示例，请遵循相应章节。

ROS 2 Lyrical Luth 和 Rolling

运行示例时，请安装 test_msgs 和 example_interfaces 包，将示例仓库克隆到工作区，然后构建：

sudo apt install -y ros-rolling-example-interfaces ros-rolling-test-msgs
mkdir -p workspace/src && cd workspace
git clone https://github.com/ros2-rust/examples.git src/examples

暂时（截至 2025-01-21），包含代码生成器的 rosidl_rust 仓库也需要克隆：

mkdir -p workspace/src && cd workspace
git clone https://github.com/ros2-rust/rosidl_rust.git src/rosidl_rust

一旦更新版本的生成器随下一次 ROS 2 同步发布，上述命令即可移除。

构建工作空间：

. /opt/ros/rolling/setup.sh  # Or source your ROS 2 installation
colcon build

ROS 2 Kilted Kaiju

对于 ROS 2 Kilted，请将 ROS 2 消息包克隆到你的工作空间：

mkdir -p workspace/src && cd workspace
git clone -b kilted https://github.com/ros2/common_interfaces.git src/common_interfaces
git clone -b kilted https://github.com/ros2/example_interfaces.git src/example_interfaces
git clone -b kilted https://github.com/ros2/rcl_interfaces.git src/rcl_interfaces
git clone -b kilted https://github.com/ros2/rosidl_core.git src/rosidl_core
git clone -b kilted https://github.com/ros2/rosidl_defaults.git src/rosidl_defaults
git clone -b kilted https://github.com/ros2/unique_identifier_msgs.git src/unique_identifier_msgs

截至 2025-01-21，暂时还需要克隆包含代码生成器的 rosidl_rust 仓库：

git clone https://github.com/ros2-rust/rosidl_rust.git src/rosidl_rust

上述命令可在生成器的更新版本随下一个 ROS 2 sync 发布后移除。

构建工作空间：

. /opt/ros/kilted/setup.sh
colcon build

ROS 2 Jazzy Jalisco

对于 ROS 2 Jazzy，你需要将代码生成器和消息包克隆到你的工作区：

mkdir -p workspace/src && cd workspace
git clone -b jazzy https://github.com/ros2/common_interfaces.git src/common_interfaces
git clone -b jazzy https://github.com/ros2/example_interfaces.git src/example_interfaces
git clone -b jazzy https://github.com/ros2/rcl_interfaces.git src/rcl_interfaces
git clone -b jazzy https://github.com/ros2/rosidl_core.git src/rosidl_core
git clone -b jazzy https://github.com/ros2/rosidl_defaults.git src/rosidl_defaults
git clone -b jazzy https://github.com/ros2/unique_identifier_msgs.git src/unique_identifier_msgs
git clone https://github.com/ros2-rust/rosidl_rust.git src/rosidl_rust
git clone https://github.com/ros2-rust/examples.git src/examples

构建工作区：

. /opt/ros/jazzy/setup.sh
colcon build

ROS 2 Humble Hawksbill

在使用 ROS 2 Humble 时，需要将代码生成器和消息包克隆到工作区：

mkdir -p workspace/src && cd workspace
git clone -b humble https://github.com/ros2/common_interfaces.git src/common_interfaces
git clone -b humble https://github.com/ros2/example_interfaces.git src/example_interfaces
git clone -b humble https://github.com/ros2/rcl_interfaces.git src/rcl_interfaces
git clone -b humble https://github.com/ros2/rosidl_core.git src/rosidl_core
git clone -b humble https://github.com/ros2/rosidl_defaults.git src/rosidl_defaults
git clone -b humble https://github.com/ros2/unique_identifier_msgs.git src/unique_identifier_msgs
git clone https://github.com/ros2-rust/rosidl_rust.git src/rosidl_rust
git clone https://github.com/ros2-rust/examples.git src/examples

构建工作空间：

. /opt/ros/humble/setup.sh
colcon build

运行示例

构建完成后，source 你的工作空间并运行示例：

# In a new terminal (or tmux window)
. ./install/setup.sh
ros2 run examples_rclrs_minimal_pub_sub minimal_publisher
# In a new terminal (or tmux window)
. ./install/setup.sh
ros2 run examples_rclrs_minimal_pub_sub minimal_subscriber

或：

# In a new terminal (or tmux window)
. ./install/setup.sh
ros2 launch examples_rclrs_minimal_pub_sub minimal_pub_sub.launch.xml

对于详细的构建说明以及额外的设置选项，请参阅深入指南。

AI 政策

生成式工具可用于项目的贡献创作，但须满足以下条件：

• 任何贡献可以全部或部分由一个或多个生成式工具的输出构成。
• 在任何贡献中使用生成式工具时，必须在提交贡献时披露。
• 披露必须以确保其存续期与贡献本身相同或更长的方式予以记录。

对于源代码贡献，你应在所有源代码部分由生成式工具生成的提交的提交信息中添加披露声明。

Assisted-by: AGENT_NAME:MODEL_VERSION [TOOL1] [TOOL2]

请在 PR 描述中提供类似的披露声明。

有关更多详细信息，请参阅项目的 AI 政策。

更多文档

• 使用 rclrs 编写你的第一个节点的教程
• 贡献者指南