Version:

Icon of a magnifying glass.

IN THIS ARTICLE

ROS 2 项目配置

要求

O3DE ROS 2 Gem 已分别在搭载 Ubuntu 22.04 和 24.04 的 ROS 2 Humble 及 ROS 2 Jazzy 版本上完成测试。

Important:
ROS 2 Gem 不适用于 Windows。

本指南假设您已安装 ROS 2 的 desktop 版本。否则，某些软件包可能缺失。同时假设您已成功安装 O3DE 或从源代码检出 O3DE。 请访问 指南，了解如何从源代码构建 O3DE。

设置

ROS 2 生态系统

获取您的 ROS 2 工作区

要使用 ROS 2 Gem 构建或运行项目，您必须在控制台中 source your ROS 2 workspace 。确保 ROS 2 始终是来源的最好方法是将以下行添加到~/.profile文件中：

source /opt/ros/<distro>/setup.bash

将 <distro> 替换为 ROS 2 分配名称(例如 humble)。 然后，您必须注销并从 Ubuntu 登录，更改才能生效。

自定义软件包

Gem 完全支持 工作区叠加 。 在 ROS 2 安装的基础上获取您的工作区以包含自定义软件包。

Gem 附带了许多已包含和链接的 ROS 2 包，但您可能希望在项目中包含其他包。 为此，在你的项目的Gem/CMakeLists.txt中使用 target_depends_on_ros2 功能:

target_depends_on_ros2_packages(<your_target> <ros_package1> <ros_package2>)

使用多个 ROS 版本

如果您安装了多个 ROS 2 版本，请确保您 source 是您想要使用的那个。您可以通过检查ROS_DISTRO环境变量 （echo $ROS_DISTRO） 的值来检查控制台中的版本来源。

如果项目之前是使用其他 ROS 版本构建的，您当前需要重新构建项目。

需要额外的 ROS 2 软件包

  • gazebo_msgs: ros-${ROS_DISTRO}-gazebo-msgs
    • gazebo_msgs 用于机器人生成（不依赖于 Gazebo）。
  • Ackermann messages: ros-${ROS_DISTRO}-ackermann-msgs
  • Control messages ros-${ROS_DISTRO}-control-msgs
  • XACRO ros-${ROS_DISTRO}-xacro
  • Vision msgs ros-${ROS_DISTRO}-vision-msgs

如果选择了 ROS 2 发行版的desktop安装，则其他所有内容都应该在那里。

使用这个有用的命令来安装：

sudo apt install ros-${ROS_DISTRO}-ackermann-msgs ros-${ROS_DISTRO}-control-msgs ros-${ROS_DISTRO}-nav-msgs ros-${ROS_DISTRO}-xacro ros-${ROS_DISTRO}-vision-msgs
Note:
您可能需要安装 gazebo_msgs 包才能使用某些功能，例如机器人的动态生成和接触传感器。不过，该包并非 ROS2 Gem 运行的必需组件。在 ROS 2 Jazzy 版本中，gazebo_msgs 包已被弃用，且自 ROS 2 Kilted 版本起将不再提供。

克隆 Gem 存储库

要在任何 O3DE 项目中使用 ROS2 Gem，您需要将其注册到 O3DE 中。同样地，若要使用 ROS2Sensors、ROS2Controllers 以及资产的 Gems 功能，也需分别注册这些组件。它们位于 o3de/o3de-extras 存储库中。将 GitHub 仓库克隆至本地机器：

git clone https://github.com/o3de/o3de-extras

为方便起见，请设置几个环境变量： O3DE_HOME到 O3DE 所在的位置 和 O3DE_EXTRAS_HOME 添加到克隆的 o3de-extras 存储库的路径中，例如：

export O3DE_HOME=${HOME}/o3de
export O3DE_EXTRAS_HOME=${HOME}/o3de-extras

若尚未启用，请开启 Git 大文件存储（LFS）。资源 Gems 通过 LFS 存储大型文件。

cd ${O3DE_EXTRAS_HOME}
git lfs install && git lfs pull

注册机器人项目模板和Gems

机器人项目模板可以帮助您快速启动仿真项目。我们建议您注册机器人项目模板 Gem 及其资产 Gem，这些 Gem 是使用o3de-extras存储库下载的。

${O3DE_HOME}/scripts/o3de.sh register --all-gems-path ${O3DE_EXTRAS_HOME}/Gems/
${O3DE_HOME}/scripts/o3de.sh register --all-templates-path ${O3DE_EXTRAS_HOME}/Templates/

有关更多信息，请参阅 添加和删除 Gem 和 注册 Gem。

创建一个新的机器人模拟项目

机器人项目模板

工程模板是塑造初始工程的有用工具。 使用模板创建时，新项目可以从特定配置开始。包括某些已启用的 Gem 和起始关卡。

机器人项目模板旨在帮助您快速开始使用 ROS 2 在 O3DE 中模拟机器人。

ROS 2 项目模板

机器人有三个模板：

  • Ros2ProjectTemplate: 一个仓库模板，包含一台差速驱动机器人，以及一个C++示例，展示如何在O3DE中使用ROS 2功能。
  • Ros2FleetRobotTemplate:一个配备差速驱动机器人的仓库模板，易于定制和扩展（多机器人）。
  • Ros2RoboticManipulationTemplate: 一个用于机器人操作的模板，包含机械臂和一组可抓取的物体。

有关模板的更多详细信息，请参阅 概述。

使用模板创建新项目

要使用模板创建项目，您可以使用 GUI 或命令行。 最快的方法是运行以下命令 (调整 PROJECT_NAME, PROJECT_PATH 和您想要的模板):

export PROJECT_NAME=MySimulationProject
export PROJECT_PATH=${HOME}/projects/${PROJECT_NAME}
${O3DE_HOME}/scripts/o3de.sh create-project --project-path $PROJECT_PATH --template-path ${O3DE_EXTRAS_HOME}/Templates/Ros2ProjectTemplate

有关更多信息，请参阅 项目创建

构建

ROS 2 Gem 是在启用 ROS 2 Gem 的情况下构建 O3DE 项目时构建的。

在构建之前，请确保 source your ROS 2 workspace 。

为方便起见，下面是一个参数化 CMake 调用的示例：

cd $PROJECT_PATH
cmake -B build/linux -G "Ninja Multi-Config" -DLY_DISABLE_TEST_MODULES=ON -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -DLY_STRIP_DEBUG_SYMBOLS=ON
cmake --build build/linux --config profile --target ${PROJECT_NAME} Editor ${PROJECT_NAME}.Assets ${PROJECT_NAME}.GameLauncher
Note:

在版本 24.09.0 之前，PhysX 5 是实验性的，并在引擎的源代码编译过程中进行编译。 如果您使用的是版本 23.10.3 或更早版本，则需要指定一个附加标志：-DAZ_USE_PHYSX5:BOOL=ON :

cmake -B build/linux -G "Ninja Multi-Config" -DLY_DISABLE_TEST_MODULES=ON -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -DLY_STRIP_DEBUG_SYMBOLS=ON -DAZ_USE_PHYSX5:BOOL=ON

在 O3DE 编辑器中启动您的项目

构建项目后，运行以下命令以启动 Editor：

${PROJECT_PATH}/build/linux/bin/profile/Editor

您也可以使用 GameLauncher 在不启动编辑器的情况下运行项目。GameLauncher 作为构建流程的一部分生成，位于与编辑器相同的目录中。

${PROJECT_PATH}/build/linux/bin/profile/${PROJECT_NAME}.GameLauncher