Skip to content

Commit

Permalink
Reference the new location for documentation (#314)
Browse files Browse the repository at this point in the history 
* Refrence the new location for documentation
* Update Gems/ROS2/README.md

Signed-off-by: Artur Kamieniecki <artur.kamieniecki@robotec.ai>
Signed-off-by: Adam Dąbrowski <adam.dabrowski@robotec.ai>
Signed-off-by: Artur Kamieniecki <130671280+arturkamieniecki@users.noreply.github.com>
Co-authored-by: Adam Dąbrowski <adam.dabrowski@robotec.ai>
Co-authored-by: Steve Pham <82231385+spham-amzn@users.noreply.github.com>
  • Loading branch information
@arturkamieniecki @adamdbrw @spham-amzn
3 people authored May 15, 2023
1 parent fa68288 commit 295030f
Showing 1 changed file with 17 additions and 72 deletions.
89 changes: 17 additions & 72 deletions Gems/ROS2/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,36 +1,8 @@
# O3DE ROS2 Gem

This Gem enables users to develop robotic simulations through ROS2 tools and components.
With the ROS2 Gem you can develop robotic simulations with [ROS (Robot Operating System) 2](https://www.ros.org/) in Open 3D Engine (O3DE).

## Requirements

* Ubuntu 20.04 or 22.04. Other Ubuntu versions and Linux distros could also work as long as they can support ROS 2.
* [O3DE](https://www.o3de.org/) development branch. The Gem does not work with a release version of O3DE yet.
* Modern version of ROS 2. This instruction assumes that the `desktop` version is installed. Otherwise some packages might be missing. We support and tested with:
* [ROS 2 Galactic](https://docs.ros.org/en/galactic/Installation.html) with Ubuntu 20.04.
* [ROS 2 Humble](https://docs.ros.org/en/humble/Installation.html) with Ubuntu 22.04.

#### Additional ros packages required

Once the desired version of ROS 2 is installed, you will need to install additional ROS 2 packages.
Before running the following commands, make sure that the ROS 2 environment is setup. Replace \<distro\> with the ROS 2 distribution name (galactic, humble, ..) below and run the following command:
```
source /opt/ros/<distro>/setup.bash
```

* gazebo_msgs: `sudo apt install ros-${ROS_DISTRO}-gazebo-msgs`
* Ackermann messages: `sudo apt install ros-${ROS_DISTRO}-ackermann-msgs`
* Control messages: `sudo apt install ros-${ROS_DISTRO}-control-msgs`
* Control toolbox `sudo apt install ros-${ROS_DISTRO}-control-toolbox`
* Xacro (XML Macros) `sudo apt install ros-${ROS_DISTRO}-xacro`

If a `desktop` installation of ROS 2 distro was selected, everything else should be there.

Use this helpful command to install:

```
sudo apt install ros-${ROS_DISTRO}-ackermann-msgs ros-${ROS_DISTRO}-control-toolbox ros-${ROS_DISTRO}-nav-msgs ros-${ROS_DISTRO}-gazebo-msgs ros-${ROS_DISTRO}-control-msgs
```
Access the the whole ROS2 Gem documentation by clicking [here](https://www.o3de.org/docs/user-guide/interactivity/robotics/). Other sections in this README link to specific parts of the provided documentation.

## Features

Expand All @@ -52,61 +24,34 @@ sudo apt install ros-${ROS_DISTRO}-ackermann-msgs ros-${ROS_DISTRO}-control-tool

For a "feel" of these features, see an [example project](#example-project) which uses this Gem to run navigation stack.

## Clone this repository
## Example project

You can test the O3DE ROS2 Gem with the [Robot Vacuum](https://github.com/o3de/RobotVacuumSample) project. It will allow you to run a robot navigation simulation. All necessary assets are included.

Clone the o3de-extras repository from Github:
## Installation

```
git clone https://github.com/o3de/o3de-extras.git
```
Refer to [this part of the documentation](https://www.o3de.org/docs/user-guide/interactivity/robotics/project-configuration/) to configure your project with the ROS2 Gem.

## Building

The Gem is built through building a project which uses it. Make sure to
[source your ros2 workspace](https://docs.ros.org/en/rolling/Tutorials/Configuring-ROS2-Environment.html#source-the-setup-files)
before building.
## Learn about ROS2 Gem

## Adding Gem to your project
Visit [this part of the documentation](https://www.o3de.org/docs/user-guide/interactivity/robotics/concepts-and-components-overview/) to learn about the ROS2 Gems Concepts and Structure. Additionally you can learn about ROS 2 Concepts [here](https://docs.ros.org/en/humble/Concepts.html).

To use this Gem in your project, you need to register the Gem with O3DE. First, clone this repository. Then,
in o3de folder:
```
scripts/o3de.sh register --gem-path <PATH_TO_CLONED_O3DE_EXTRAS>/Gems/ROS2
scripts/o3de.sh enable-gem -gn ROS2 -pp <PATH_TO_YOUR_PROJECT>
```
## How to create your own robotic simulation

## Example project
Refer [here](https://www.o3de.org/docs/user-guide/interactivity/robotics/creating-robotic-simulation/) to access a list of steps guiding you through the creation of your own simulation.

You can test O3DE ROS2 Gem with the [Robot Vacuum](https://github.com/o3de/RobotVacuumSample) project.
It will allow you to run robot navigation. All necessary assets are included.
## Importing robots

## User Guides
Access [this part](https://www.o3de.org/docs/user-guide/interactivity/robotics/importing-robot/) of the documentation to learn about importing robots from common formats such as the [Unified Robot Description Format (URDF)](http://wiki.ros.org/urdf).

Follow the [ROS 2 Gem User Guide](docs/guides/ros2-gem.md) to understand its concepts and components.
## Troubleshooting

If you plan on contributing please follow the [Pull Request Publishing](docs/guides/pr_publishing.md) guide. For those using the Clion IDE we advise to follow the [Development in Clion](docs/guides/development_in_clion.md) guide.
If you have any problems with the ROS2 Gem, visit [here](https://www.o3de.org/docs/user-guide/interactivity/robotics/troubleshooting/) for troubleshooting guides and suggestions.

## How to create your own robotic simulation
## User Guides

>This section is to be detailed.
Once you are set up and familiar with the example project, consider the following steps:
1. [Create a new O3DE project](https://www.o3de.org/docs/welcome-guide/create/) with [this Gem enabled](#adding-gem-to-your-project).
2. Create or import Assets for your robots and environment.
1. You can use formats supported by O3DE.
2. You can import your robot from URDF.
3. Imported models might require some adjustments to be simulation-ready.
3. Determine which sensors you need to simulate.
1. Some sensors are already implemented in this Gem.
1. They might require specialization (implementation specific for particular models).
2. You might want to consider tradeoffs between performance and realism in each case.
2. Use ROS2SensorComponent as a base class if you are implementing a new sensor.
4. Develop necessary sensors and their prefabs.
5. Consider developing additional abstraction to handle spawning and despawning robots.
1. This would also be a valuable contribution to the Gem.
6. Develop your scene and simulation scenario, placing Assets and configuring Components.

Enjoy simulation with some of many [ROS2 packages](https://index.ros.org/packages/#humble) and projects in [ROS2 ecosystem](https://project-awesome.org/fkromer/awesome-ros2).
If you plan on contributing please follow the [Pull Request Publishing](docs/guides/pr_publishing.md) guide. For those using the Clion IDE we advise to follow the [Development in Clion](docs/guides/development_in_clion.md) guide.

## Acknowledgements

Expand Down

0 comments on commit 295030f

Please sign in to comment.