ros_gz 项目模板指南

本指南介绍如何使用 ros_gz_project_template 为 ROS 2 和 Gazebo 项目创建结构化的工作空间（推荐做法），或改进现有工作空间。该模板提供一致的布局、自动化的构建流程，以及与 ROS 2 和 Gazebo 的集成，可帮助你专注于开发机器人应用。

安装步骤

如果是新建项目，请创建工作空间，或进入现有项目的源码目录：
Terminal window
```
mkdir -p ~/project_ws/src
cd ~/project_ws/src
```
直接使用 ros_gz_project_template 模板，在 GitHub 上创建项目仓库。

或者先克隆模板仓库：
Terminal window
```
vcs import --input https://raw.githubusercontent.com/gazebosim/ros_gz_project_template/main/template_workspace.yaml
```
将克隆下来的仓库文件夹重命名为你期望的项目名称：
Terminal window
```
mv ros_gz_project_template your_project_name
```

包结构

此时，你的项目中会有以下包：

ros_gz_example_application —— 存放 ROS 2 相关的代码和配置，即控制、规划或任何高层算法所在的包。
```
├── CMakeLists.txt
├── package.xml
├── src
    └── ...
```
ros_gz_example_bringup —— 存放 launch 文件和高层工具、ROS 与 Gazebo 之间的通信桥接。任何机器人或硬件相关的配置都在这里。
```
├── config
│   ├── ros_gz_example_bridge.yaml
│   └── diff_drive.rviz
├── launch
    └── diff_drive.launch.py
```

ros_gz_example_description —— 存放仿真系统的 SDF 描述以及任何其他仿真资源。

├── hooks
│   └── ros_gz_example_description.dsv.in
├── models
    ├── diff_drive
        ├── model.config
        └── model.sdf

ros_gz_example_gazebo —— 存放 Gazebo 相关的代码和配置，即用户自定义 world 和自定义系统插件（system plugin）所在的位置。

├── include
│   └── ros_gz_example_gazebo
│       ├── BasicSystem.hh
│       └── FullSystem.hh
├── src
│   ├── BasicSystem.cc
│   └── FullSystem.cc
├── worlds
        └── diff_drive.sdf

访问仿真资源

仿真资源包括模型或机器人描述（URDF 或 SDF）、用于可视化机器人不同部件的网格（mesh）和材质文件，以及最终将所有这些元素编译到一个仿真 world SDF 中的产物。Gazebo 提供了几种不同的机制来定位这些资源，它首先在 GZ_SIM_RESOURCE_PATH 环境变量中搜索，详见 gz-sim API 中关于查找资源的文档。

ROS 和 Gazebo 在解析 URI 方面存在差异：ROS 侧可以处理 package:// URI，而 SDFormat 默认只支持 model://。如今 libsdformat 可以将 package:// 转换为 model:// URI。因此，通过“安装” models 目录并把模型路径导出到环境中，即可加载现有的仿真资源。

这可以通过 colcon 环境钩子（ROS 包提供的 shell 脚本）在 DSV 文件中自动完成。每当 source 工作空间中的 setup 文件时，这些环境钩子也会被一并 source。参见此示例：它将模型的共享路径前置添加到 GZ_SIM_RESOURCE_PATH 中，使 Gazebo 能够通过 model:// URI 从 ROS 包加载模型。

开发

选择一种 ROS 和 Gazebo 组合

注意：如果在 ROS 2 中使用某个特定且不受支持的 Gazebo 版本，可能需要设置 GZ_VERSION 环境变量，例如：
Terminal window
```
export GZ_VERSION=jetty
```

安装依赖

cd ~/project_ws
source /opt/ros/<ROS_DISTRO>/setup.bash
sudo rosdep init
rosdep update
rosdep install --from-paths src --ignore-src -r -i -y --rosdistro <ROS_DISTRO>

修改

浏览 src/your_project_name 目录，添加或修改与项目相关的包。根据应用场景，有两种主要的机制可以集成 ROS 2 和 Gazebo：
1. 使用 ros_gz_bridge 在 ROS 2 和 Gazebo 之间动态连接 topic（本模板中已作为示例演示）
2. 直接在 Gazebo 系统插件中嵌入 ROS 2
主要考虑因素是 ROS 与 Gazebo 之间需要多深的集成。使用 bridge 可以保持依赖分离，Gazebo 系统无需了解 ROS。而直接嵌入 ROS 2 node 则允许在 Gazebo 插件中访问 EntityComponentManager。

构建

cd ~/project_ws
colcon build --cmake-args -DBUILD_TESTING=ON

使用

source 工作空间
Terminal window
```
. ~/project_ws/install/setup.sh
```
启动仿真并在 RViz 中可视化：

要可视化你的机器人模型以及 ROS 2 node 生成的数据，请打开一个新终端并启动：
Terminal window
```
ros2 launch ros_gz_example_bringup diff_drive.launch.py
```

ROSCon 2022

推荐观看 ROSCon 2022 上题为 ROS 2 and Gazebo Integration Best Practices（ROS 2 与 Gazebo 集成最佳实践）的演讲，了解从长期积累的经验和成功部署中总结出的仿真与 ROS 2 集成最佳实践。该演讲还将介绍一些技巧和方法，帮助你更轻松地迁移到最新版本。