From f402e6faa9a149058aa8f7c7aded70714b8e3002 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Adam=20D=C4=85browski?= Date: Mon, 20 Mar 2023 20:04:13 +0100 Subject: [PATCH] Restructuring ROS 2 Gem docs (#2266) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * First step towards the new structure. Some information updated Signed-off-by: Adam Dabrowski * restructuring, update Signed-off-by: Adam Dabrowski * added api reference link Signed-off-by: Adam Dabrowski * Applied review comments. Signed-off-by: Adam Dabrowski * Adjusted inactive links. Signed-off-by: Michał Pełka * Commented out in-progress sections. Signed-off-by: Michał Pełka * Apply suggestions from code review Co-authored-by: Wojtek <125894910+wojtek-robotecai@users.noreply.github.com> Signed-off-by: Michał Pełka * Further adjustments to review. Signed-off-by: Michał Pełka * Adjusted to the review. Signed-off-by: Adam Dabrowski Co-authored by: Channele Mosquera * added class diagram link Signed-off-by: Adam Dabrowski --------- Signed-off-by: Adam Dabrowski Signed-off-by: Michał Pełka Signed-off-by: Michał Pełka Co-authored-by: Michał Pełka Co-authored-by: Michał Pełka Co-authored-by: Wojtek <125894910+wojtek-robotecai@users.noreply.github.com> --- .../docs/user-guide/gems/reference/_index.md | 2 +- .../gems/reference/robotics/ros2.md | 42 ++++ .../user-guide/gems/reference/ros2/_index.md | 124 ---------- .../reference/ros2/ros2-gem-user-guide.md | 219 ------------------ .../interactivity/robotics/_index.md | 26 +++ .../robotics/class-diagram.md} | 4 +- .../concepts-and-components-overview.md | 151 ++++++++++++ .../robotics/creating-robotic-simulation.md | 37 +++ .../interactivity/robotics/overview.md | 38 +++ .../robotics/project-configuration.md | 87 +++++++ .../robotics/vehicle-dynamics.md | 78 +++++++ 11 files changed, 462 insertions(+), 346 deletions(-) create mode 100644 content/docs/user-guide/gems/reference/robotics/ros2.md delete mode 100644 content/docs/user-guide/gems/reference/ros2/_index.md delete mode 100644 content/docs/user-guide/gems/reference/ros2/ros2-gem-user-guide.md create mode 100644 content/docs/user-guide/interactivity/robotics/_index.md rename content/docs/user-guide/{gems/reference/ros2/class_diagram.md => interactivity/robotics/class-diagram.md} (80%) create mode 100644 content/docs/user-guide/interactivity/robotics/concepts-and-components-overview.md create mode 100644 content/docs/user-guide/interactivity/robotics/creating-robotic-simulation.md create mode 100644 content/docs/user-guide/interactivity/robotics/overview.md create mode 100644 content/docs/user-guide/interactivity/robotics/project-configuration.md create mode 100644 content/docs/user-guide/interactivity/robotics/vehicle-dynamics.md diff --git a/content/docs/user-guide/gems/reference/_index.md b/content/docs/user-guide/gems/reference/_index.md index d82830a2c42..884f5319f41 100644 --- a/content/docs/user-guide/gems/reference/_index.md +++ b/content/docs/user-guide/gems/reference/_index.md @@ -155,7 +155,7 @@ toc: true | Gem | Description | | - | - | -| [ROS 2](./ros2/) | The ROS 2 Gem provides integration with the [Robot Operating System (ROS) 2](https://docs.ros.org/en/rolling/index.html) library and enables design of simulation of robotics systems. | +| [ROS 2](./robotics/ros2.md) | The ROS 2 Gem provides integration with the [Robot Operating System (ROS) 2](https://docs.ros.org/en/rolling/index.html) library and enables the design of the simulation of robotics systems. | ## Script diff --git a/content/docs/user-guide/gems/reference/robotics/ros2.md b/content/docs/user-guide/gems/reference/robotics/ros2.md new file mode 100644 index 00000000000..9b327f7677a --- /dev/null +++ b/content/docs/user-guide/gems/reference/robotics/ros2.md @@ -0,0 +1,42 @@ +--- +linkTitle: ROS 2 +title: ROS 2 Gem +description: The ROS 2 Gem helps build robotic simulations with Robot Operating System (ROS) 2 in Open 3D Engine (O3DE). +toc: true +--- + + + +The **ROS 2 Gem** uses the [Robot Operating System (ROS)](https://docs.ros.org/en/rolling/index.htmml) to enable +robotic simulation in **Open 3D Engine (O3DE)**. The ROS 2 Gem has the following features: + +* Direct and natural support of the ROS 2 ecosystem: + * Does not use any bridges to communicate between ROS and O3DE. A simulation node will function as any other ROS 2 node. + * Enables you to directly include ROS 2 headers and write ROS 2 code in O3DE. + * Having no bridge improves communication performance. + * Provides an easy way to include ROS 2 dependencies. +* Sensors: + * Are abstracted through the Sensor Component, which takes care of the publishing of sensor data and common settings such as frequency. + * Features several types of configurable, extendable sensors such as Lidar, Camera (including Depth channel), IMU, and GNSS. +* Utilities for automated handling of: + * Simulation time: - publishing `/clock`, with support for non-real time. + * Computing and publishing of transformation frames (`/tf`, `/tf_static`). + * Namespaces- allowing multi-robot simulation in O3DE by default! + * Validation for topic and namespace names. + * Dynamic spawning of robots through ROS 2 services. +* Robot Control Component: + * Provides a quick-to-use method of controlling your robot. + * Includes support for Twist and AckermannDrive message interfaces. +* Vehicle dynamics: + * Ackermann Steering subscribes to the message of type [AckermannDrive](http://docs.ros.org/en/api/ackermann_msgs/html/msg/AckermannDrive.html). + * Differential drive subscribes to the message of type [Twist](http://docs.ros.org/en/noetic/api/geometry_msgs/html/msg/Twist.html). +* URDF/XACRO (experimental). + * Allows robot imports from the URDF format. + +## Related topics + +| Topic | Description | +|-------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------| +| [Robotics in O3DE](/docs/user-guide/interactivity/robotics) | Learn about robotics in O3DE, including Gems, Templates and demos to help you get started. | +| [ROS 2 Gem Concepts and Structure](/docs/user-guide/interactivity/robotics/concepts-and-components-overview.md) | Overview of the concepts and structure of the ROS 2 Gem, including an overview of its components | +| [ROS 2 Gem API reference](/docs/api/gems/ros2) | Generated documentation for ROS 2 Gem's API reference. | diff --git a/content/docs/user-guide/gems/reference/ros2/_index.md b/content/docs/user-guide/gems/reference/ros2/_index.md deleted file mode 100644 index 6abd1542f27..00000000000 --- a/content/docs/user-guide/gems/reference/ros2/_index.md +++ /dev/null @@ -1,124 +0,0 @@ ---- -linkTitle: ROS 2 -title: ROS 2 Gem -description: The ROS 2 Gem helps build robotic simulations with Robot Operating System (ROS) 2 in Open 3D Engine (O3DE). -toc: true ---- - - - -The **ROS 2** Gem provides integration with the [Robot Operating System (ROS) 2](https://docs.ros.org/en/rolling/index.html) library and enables design of simulation of robotics systems. - -## Requirements - -* Ubuntu 20.04 or 22.04. - Other Ubuntu versions and Linux distributions can also work as long as they support ROS 2. - **The O3DE ROS 2 Gem is not available for Windows.** -* [O3DE built from source on Linux](/docs/welcome-guide/setup/setup-from-github/building-linux). **The ROS 2 Gem does not work with a release version of O3DE yet**. -* The [latest version](https://docs.ros.org/en/rolling/Releases.html) of ROS 2. This instruction assumes that the `desktop` version is installed. Otherwise, some packages might be missing. The O3DE ROS 2 has been 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 - -#### Source your ROS 2 workspace - -To build or run projects using ROS 2 Gem, you must [source your ROS 2 workspace](https://docs.ros.org/en/humble/Tutorials/Beginner-CLI-Tools/Configuring-ROS2-Environment.html) in your console. The best way to ensure that ROS 2 is sourced at all times is by adding the following line to the `~/.profile` file: -``` -source /opt/ros//setup.bash -``` -Replace `` with the ROS 2 distribution name (`galactic`, `humble`, and so on). -Then, you must log out and log in from Ubuntu for the change to take effect. -#### Additional ROS 2 packages required - -* gazebo_msgs: `sudo apt install ros-${ROS_DISTRO}-gazebo-msgs` -* Ackermann messages: `sudo apt install ros-${ROS_DISTRO}-ackermann-msgs` -* Control toolbox `sudo apt install ros-${ROS_DISTRO}-control-toolbox` -* XACRO `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 -``` - -## Features - -* Direct and natural support of ROS 2 ecosystem: - * No bridges. Your simulation node will function as any other ROS 2 node. - * This is also good for performance - * Easy way to include ROS 2 dependencies. -* Sensors: - * Sensor Component serves as a handy abstraction. - * Example implementations of Lidar, Camera, IMU sensors. - * Including a few Assets and prefabs which are ready to use. -* Automated handling of: - * Simulation time, publishing `/clock` supporting non-real time. - * Publishing of transformation frames (`/tf`, `/tf_static`). - * Validation for topic and namespace names. -* Robot Control Component: - * A quick to use method of controlling your robot with Twist messages. - * Can be used with custom LUA scripting. -* Vehicle dynamics: - * Ackermann Steering, subscribes to message of type [AckermannDrive](http://docs.ros.org/en/api/ackermann_msgs/html/msg/AckermannDrive.html). - * Differential drive, subscribes to message of type [Twist](http://docs.ros.org/en/noetic/api/geometry_msgs/html/msg/Twist.html). -* URDF/XACRO (experimental). - - -For a "feel" of these features, see an [example project](https://github.com/o3de/RobotVacuumSample) which uses this Gem to run navigation stack. - -## Clone this repository - -The ROS 2 Gem lives in the [`o3de/o3de-extras`](https://github.com/o3de/o3de-extras) repository. Clone the GitHub repository to your machine: - -``` -git clone https://github.com/o3de/o3de-extras -``` - -## Adding Gem to your project - -To use the ROS 2 Gem in your O3DE project, you need to register the Gem with O3DE. Then, you can enable the Gem in your project. Run the following commands from the O3DE folder: -``` -scripts/o3de.sh register --gem-path /Gems/ROS2 -scripts/o3de.sh enable-gem -gn ROS2 -pp -``` - -For more information, refer to [Adding and Removing Gems](/docs/user-guide/project-config/add-remove-gems/) and [Registering Gems](/docs/user-guide/project-config/register-gems/). - - -## Building - -The ROS 2 Gem is built when you build an O3DE project and enable the ROS 2 Gem. For more information, refer to [Project Creation](/docs/welcome-guide/create/) and [Adding and Removing Gems in a Project](/docs/user-guide/project-config/add-remove-gems/). Make sure to [source your ROS 2 workspace](#source-your-ros-2-workspace) before building. - -## Example project - -You can test O3DE ROS 2 Gem with the [Robot Vacuum Sample](https://github.com/o3de/RobotVacuumSample) project. This project allows you to run robot navigation. All necessary assets are included. - -## User Guides - -Follow the [O3DE ROS2 Gem User Guide](ros2-gem-user-guide.md) to understand its concepts and components. For additional developer's documentation, check the [Gem documentation](https://github.com/o3de/o3de-extras/blob/development/Gems/ROS2/docs/guides/development_in_clion.md) and [Open 3D Engine Contributor guide](/docs/contributing) - -## How to create your own robotic simulation - ->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](/docs/welcome-guide/create/) -2. [Register ROS 2 Gem](#adding-gem-to-your-project) and other useful Gems to created project. -Follow [Registering Gems to a Project](/docs/user-guide/project-config/register-gems/) guide. -3. 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/XACRO. - 3. Imported models might require some adjustments to be simulation-ready. - 4. Mobilize robot with Vehicle Dynamics controllers. -4. 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 like to consider tradeoffs between performance and realism in each case. - 2. Use `ROS2SensorComponent` as a base class if you are implementing a new sensor. Follow [Contribution to Source Code](docs/contributing/to-code/) guide. -5. Develop necessary sensors and their prefabs. -6. Consider developing additional abstraction to handle spawning and despawning robots. - 1. This would also be a valuable contribution to the Gem. -7. Develop your scene and simulation scenario, placing Assets and configuring components. - -Enjoy simulation with some of many [ROS 2 packages](https://index.ros.org/packages/#humble) and projects in [ROS 2 ecosystem](https://project-awesome.org/fkromer/awesome-ros2). diff --git a/content/docs/user-guide/gems/reference/ros2/ros2-gem-user-guide.md b/content/docs/user-guide/gems/reference/ros2/ros2-gem-user-guide.md deleted file mode 100644 index 29186681b18..00000000000 --- a/content/docs/user-guide/gems/reference/ros2/ros2-gem-user-guide.md +++ /dev/null @@ -1,219 +0,0 @@ ---- -linkTitle: Guide -title: O3DE ROS 2 Gem Details -description: User guide to develop ROS 2 enabled simulation -toc: true ---- - -The ROS 2 Gem helps to build robotic simulations with [ROS 2 / Robot Operating System](https://www.ros.org/). -An example of usage can be seen at [Robot Vacuum Sample](https://github.com/o3de/RobotVacuumSample). -The ROS 2 Gem contains a number of components that gives you a set of tools for robotic simulation. -Components allow you to: -- add locomotion to robotics platforms ([Vehicle Dynamics](#vehicle-model)), -- simulate sensors ([Sensors](#sensors)), -- provide tools to interact with simulation (e.g. [Robot Control](#robot-control), [Spawner](#spawner)). - -## Components overview - -- __Central Singleton__ - - ROS2SystemComponent -- __Core abstractions__ - - ROS2FrameComponent - - ROS2SensorComponent -- __Sensors__ - - ROS2CameraSensorComponent - - ROS2GNSSSensorComponent - - ROS2IMUSensorComponent - - ROS2LidarSensorComponent - - ROS2OdometrySensorComponent -- __Robot control__ - - AckermannControlComponent - - RigidBodyTwistControlComponent - - SkidSteeringControlComponent -- __Spawner__ - - ROS2SpawnerComponent - - ROS2SpawnPointComponent -- __Vehicle dynamics__ - - AckermannVehicleModelComponent - - SkidSteeringModelComponent - - WheelControllerComponent -- __Robot Import (URDF) system component__ - - ROS2RobotImporterSystemComponent - -## The Gem and ROS 2 ecosystem - -### Supported Platforms and versions - -The Gem is currently Linux-only and is being tested with ROS 2 Humble on Ubuntu 22.04 as well as ROS 2 Galactic with Ubuntu 20.04. - -It is intended to support any modern ROS 2 version, following these priorities: - -- The most recent LTS version (e.g. in June 2022, [ROS 2 Humble](https://docs.ros.org/en/humble/Installation.html)). -- The most recent non-LTS version ([ROS 2 Galactic](https://docs.ros.org/en/galactic/Installation.html)). -- The always-fresh [ROS 2 Rolling](https://docs.ros.org/en/rolling/Installation.html). -- Older versions. - -Currently tested and validated versions / platforms will be detailed in the [project repository](https://github.com/o3de/o3de-extras/tree/development/Gems/ROS2). - -**Currently, the O3DE ROS 2 Gem is not available for Windows.** - -If you have multiple versions installed, make sure you [source](https://docs.ros.org/en/humble/Tutorials/Workspace/Creating-A-Workspace.html#source-the-overlay) the one you would like to use. You can check which version is sourced in your console by checking the value of `ROS_DISTRO` environment variable (`echo $ROS_DISTRO`). - -### ROS 2 Concepts - -Please refer to [ROS 2 Concepts documentation](https://docs.ros.org/en/humble/Concepts.html). - -### Structure and Communication - -The Gem creates a [ROS 2 node](https://docs.ros.org/en/humble/Tutorials/Understanding-ROS2-Nodes.html) which is directly a part of the ROS 2 ecosystem. As such, your simulation will not use any bridges to communicate and is subject to configuration through settings such as Environment Variables. It is truly a part of the ecosystem. - -Note that the simulation node is handled through `ROS2SystemComponent` - a singleton. However, you are free to create and use your own nodes if you need more than one. - -Typically, you will be creating publishers and subscriptions. This is done through [rclcpp API](https://docs.ros2.org/humble/api/rclcpp/classrclcpp_1_1Node.html). Example: - -``` -auto ros2Node = ROS2Interface::Get()->GetNode(); -AZStd::string fullTopic = ROS2Names::GetNamespacedName(GetNamespace(), m_MyTopic); -m_myPublisher = ros2Node->create_publisher(fullTopic.data(), QoS()); -``` - -Note that QoS class is a simple wrapper to [`rclcpp::QoS`](https://docs.ros.org/en/humble/p/rclcpp/generated/classrclcpp_1_1QoS.html). - -### Frames - -`ROS2FrameComponent` is a representation of an interesting physical part of the robot. It handles spatio-temporal relationship between this part and other frames of reference. It also encapsulates namespaces, which help to distinguish between different robots and different parts of the robot, such in the case of multiple identical sensors on one robot. - -All Sensors and the Robot Control component require `ROS2FrameComponent`. - -### Sensors - -Sensors are components deriving from `ROS2SensorComponent`. They acquire data from the simulated environment and publish it to ROS 2 domain. - -- Each sensor has a configuration, including one or more Publishers. -- Sensors publish at a given rate (frequency). -- Some sensors can be visualized. - -If you intend to add your own sensor, it might be useful to look at how sensors already provided within the O3DE ROS2 Gem are implemented. - -Sensors can be fall into one of two categories: -- sensors which replicate real devices to some degree of realism. -- ground truth "sensors", which can be useful for development and machine learning. - -### Robot Control - -The Gem comes with `ROS2RobotControlComponent`, which you can use to move your robot through: - -- [Twist](https://github.com/ros2/common_interfaces/blob/master/geometry_msgs/msg/Twist.msg) messages. -- [AckermannDrive](https://index.ros.org/p/ackermann_msgs/#humble) - The component subscribes to these command messages on a configured topic. The topic is "cmd_vel" by default, in a namespace as dictated by ROS2Frame. - -To make use of received command messages, use either `AckermannControlComponent`, `RigidBodyTwistControlComponent` or `SkidSteeringControlComponent` , depending on steering type. You can also implement your own control component or use LUA scripting to handle these commands. Unless scripting is used, control components should translate ROS 2 commands to events on `VehicleInputControlBus`. These events will be handled by a [`VehicleModelComponent`](#vehicle-model) if it is present. You can use tools such as [rqt_robot_steering](https://index.ros.org/p/rqt_robot_steering/) to move your robot with Twist messages. `RobotControl` is suitable to use with [ROS 2 navigation stack](https://navigation.ros.org/). It is possible to implement your own control mechanisms with this Component. - -### Vehicle Model - -`VehicleModelComponent` serves the purpose of converting inputs such as target velocity, steering or acceleration to physical forces on parts of a vehicle (robot). `VehicleModel` has a `VehicleConfiguration` which is used to define axles, parametrize and assign wheels. The model requires a `WheelControllerComponent` present in each wheel entity. It also uses an implementation of `DriveModel`, which converts vehicle inputs to forces acting on steering elements and wheels. - -#### Wheel Controller - -A wheel controller is a controller that should be attached to the vehicle's wheel. The wheel entity should have PhysX Hinge Joint attached. The Joint controller should have: - - `Motor Configuration / Use Motor` enabled, - - `Motor Configuration / Force Limit Value` set to a desirable value. - -![PhysX Joint](/images/user-guide/gems/ros2/physx_joint.png) - -The wheel controller has the following parameters shown below. - -![Wheel Controller](/images/user-guide/gems/ros2/wheelController.png) -| Parameter Name | Description | -|------------------------------|----------------------------------------------------------------------------------| -| `Steering Entity` | The entity that has a PhysX Hinge Joint that changes the direction of the wheel. | -| `Scale of steering axis` | Allows the user to change the ratio or / and direction of wheel steering. | - -#### Ackermann Drive Model - -The implementation of `AckermannDriveModel` uses [PID controllers](https://en.wikipedia.org/wiki/PID_controller) from [control_toolbox](https://github.com/ros-controls/control_toolbox) package. The model computes velocities or forces in the joints of the vehicle and applies it accordingly to commanded velocity. - -![AckermannModel](/images/user-guide/gems/ros2/ackermanModel.png) - -Parameters of the model are exposed to the user via `AckermannVehicleModelComponent`: -| Parameter Name | Description | -|------------------------------------------------|--------------------------------------------------------------------------| -| `DriveModel / Axles ` | List of axles of the vehicle. | -| `DriveModel / Axles / Axle Wheels ` | List of wheels in axis. | -| `DriveModel / Axles / Is it a steering` | If it is enabled the Ackermann Drive Model will apply a steering angle. | -| `DriveModel / Axles / Is it a drive` | If it is enabled the Ackermann Drive Model will apply drive force. | -| `DriveModel / Axles / Track` | Distance between front and rear axis. | -| `DriveModel / Axles / Wheelbase` | Distance between left and right wheel. | -| `DriveModel / Steering PID / P` | Proportional gain of PID controller for steering servo. | -| `DriveModel / Steering PID / I` | Integral gain of PID controller for steering servo. | -| `DriveModel / Steering PID / D` | Derivative gain of PID controller for steering servo. | -| `DriveModel / Steering PID / IMin` | Minimum integration impact of PID. | -| `DriveModel / Steering PID / IMax` | Maximum integration impact of PID. | -| `DriveModel / Steering PID / AntiWindUp` | Prevents integral wind-up in PID. | -| `DriveModel / Steering PID / OutputLimit` | Clamps output to maximum value. | -| `DriveModel / Vehicles Limits / Speed limit ` | Maximum achievable linear speed in meters per second. | -| `DriveModel / Vehicles Limits / Steering limit`| Maximum achievable steering angle. | - -#### Skid Steering Drive Model -The model computes velocities in the joints of the vehicle and applies it accordinlgy to commanded velocity and configuration. - -![SkidSteeringModel](/images/user-guide/gems/ros2/skidSteeringModel.png) -Parameters of the model are exposed to the user via `AckermannVehicleModelComponent`: -| Parameter Name | Description | -|------------------------------------------------------|--------------------------------------------------------------------| -| `DriveModel / Axles ` | List of axles of the vehicle. | -| `DriveModel / Axles / Axle Wheels ` | List of wheels in axis. | -| `DriveModel / Axles / Is it a steering` | It is ignored in this model. | -| `DriveModel / Axles / Is it a drive` | If it is enabled, the Skid Steering Drive Model will apply velocities to the axis' wheels.| -| `DriveModel / Axles / Track` | Distance between front and rear axis. | -| `DriveModel / Axles / Wheelbase` | Distance between left and right wheel. | -| `DriveModel / Vehicles Limits / Linear speed limit ` | Maximum achievable linear speed in meters per second. | -| `DriveModel / Vehicles Limits / Angular speed limit` | Maximum achievable angular speed in radians per second. | - #### Manual control - -The `VehicleModel` will handle input events with names "steering" and "accelerate". This means you can add an [InputComponent](/docs/user-guide/components/reference/gameplay/input/) to the same entity and define an input map for your input devices (such as keyboard or a game pad) to control the vehicle manually. - -You can use tools such as [rqt_robot_steering](https://index.ros.org/p/rqt_robot_steering/) to move your robot with Twist messages. `RobotControl` is suitable to use with [ROS 2 navigation stack](https://navigation.ros.org/). - -It is possible to implement your own control mechanisms with this Component. - -### Spawner - -`ROS2SpawnerComponent` handles spawning entities during simulation. Available spawnables have to be set up as the component's field before the simulation. User is able to define named spawn points inside the Editor. This can be done by adding `ROS2SpawnPointComponent` to a child entity of an entity with `ROS2SpawnerComponent`. During the simulation user can access names of available spawnables and request spawning using ros2 services. The names of services are `/get_available_spawnable_names` and `/spawn_entity` respectivly. GetWorldProperties.srv and SpawnEntity.srv types are used to handle these features. In order to request defined spawn points names user can use `/get_spawn_points_names` service with GetWorldProperties.srv type. Detailed information about specific spawn point (e.g. pose) can be accessed using `/get_spawn_point_info` service with GetModelState.srv type. All used services types are defined in gazebo_msgs package. - -- **Spawning**: The spawnable name must be passed in `request.name` and the position of entity in `request.initial_pose`. - - Example call: - ``` - ros2 service call /spawn_entity gazebo_msgs/srv/SpawnEntity '{name: 'robot', initial_pose: {position:{ x: 4, y: 4, z: 0.2}, orientation: {x: 0.0, y: 0.0, z: 0.0, w:.0}}} - ``` -- Spawning in defined spawn point: spawnable name should be passed in request.name and the name of the spawn point in request.xml - - example call: `ros2 service call /spawn_entity gazebo_msgs/srv/SpawnEntity '{name: 'robot', xml: 'spawn_spot'}'` -- Available spawnable names access: names of available spawnables are sent in response.model_names - - example call: `ros2 service call /get_available_spawnable_names gazebo_msgs/srv/GetWorldProperties` -- Defined spawn points' names access: names of defined points are sent in response.model_names - - example call: `ros2 service call /get_spawn_points_names gazebo_msgs/srv/GetWorldProperties` -- Detailed spawn point info access: spawn point name should be passed in request.model_name. Defined pose is sent in response.pose. - - example call: `ros2 service call /get_spawn_point_info gazebo_msgs/srv/GetModelState '{model_name: 'spawn_spot'}'` - -## Handling custom ROS 2 dependencies - -The ROS 2 Gem will respect your choice of [__sourced__](https://docs.ros.org/en/humble/Tutorials/Workspace/Creating-A-Workspace.html#source-the-overlay) ROS 2 environment. The Gem comes with a number of ROS 2 packages already included and linked, but you might want to include additional packages in your project. To do so, use the `target_depends_on_ros2` function in your project's `Gem/CMakeLists.txt`: - -``` -target_depends_on_ros2_packages( ) -``` - -in your project's `Gem/CMakeLists.txt`. - -### Example - -It could be the case that you need to create new type of sensor publishing a custom message. - -Lets assume your project is called `MyProject`, the custom message package is called `my_sensor_msgs` and ROS 2 workspace `my_ros2_ws`. Take following steps: - -1. Build your ROS 2 message package in a workspace as you normally would (e.g. `~/projects/my_ros2_ws`) -2. Source the overlay: `source ~/projects/my_ros2_ws/install/setup.bash`. -3. Put `target_depends_on_ros2_packages(MyProject my_sensor_msgs)` in your `Gem/CMakeLists.txt` file. -4. You can now build `MyProject` and use the new messages. - -Remember to __always have your ROS 2 overlay sourced__ when building and running the project as sourcing provides visibility of ROS 2 package paths. diff --git a/content/docs/user-guide/interactivity/robotics/_index.md b/content/docs/user-guide/interactivity/robotics/_index.md new file mode 100644 index 00000000000..2e690abcd4b --- /dev/null +++ b/content/docs/user-guide/interactivity/robotics/_index.md @@ -0,0 +1,26 @@ +--- +linkTitle: Robotics +title: Robotics +description: Learn how to create robotics simulation in Open 3D Engine (O3DE) with ROS 2. +--- + +**Open 3D Engine (O3DE)** supports robotics simulation through a dedicated [ROS 2 Gem]((/docs/user-guide/gems/reference/robotics/ros2)) and additional extended Gems. +These Gems provide various O3DE components such as sensors, robot control and steering, manipulator arms, and support for importing robots from common formats. + +| Topic | Description | +|------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------| +| [Overview](overview.md) | Overview of Gems, Templates and demos for robotics in O3DE. | +| [ROS 2 Project Configuration](project-configuration.md) | Learn how to configure, build and run a project with the ROS 2 Gem. | +| [ROS 2 Concepts and Structure](concepts-and-components-overview.md) | Overview of concepts and structure of the ROS 2 Gem, including an overview of its components. | +| [Creating robotic simulation](creating-robotic-simulation.md) | High-level steps to create a robotic simulation with O3DE. | + +## Related topics + +| Topic | Description | +|----------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------| +| [ROS 2 Gem reference](/docs/user-guide/gems/reference/robotics/ros2) | Gem reference documentation for ROS 2 Gem. | +| [Setting up CLion IDE](https://github.com/o3de/o3de-extras/blob/development/Gems/ROS2/docs/guides/development_in_clion.md) | CLion IDE project setup to support the ROS 2 Gem. | +| [Open 3D Engine Contributor guide](/docs/contributing) | Read this guide if you wish to contribute to the ROS 2 Gem. | + + + diff --git a/content/docs/user-guide/gems/reference/ros2/class_diagram.md b/content/docs/user-guide/interactivity/robotics/class-diagram.md similarity index 80% rename from content/docs/user-guide/gems/reference/ros2/class_diagram.md rename to content/docs/user-guide/interactivity/robotics/class-diagram.md index fc4d7d537c3..ec09077b201 100644 --- a/content/docs/user-guide/gems/reference/ros2/class_diagram.md +++ b/content/docs/user-guide/interactivity/robotics/class-diagram.md @@ -1,7 +1,7 @@ --- linkTitle: Class Diagram -title: O3DE ROS 2 Gem Details -description: User guide to develop ROS 2 enabled simulation +title: ROS 2 Gem Details +description: Class Diagram for ROS 2 Gem in Open 3D Engine (O3DE). toc: true --- diff --git a/content/docs/user-guide/interactivity/robotics/concepts-and-components-overview.md b/content/docs/user-guide/interactivity/robotics/concepts-and-components-overview.md new file mode 100644 index 00000000000..752f9c49e96 --- /dev/null +++ b/content/docs/user-guide/interactivity/robotics/concepts-and-components-overview.md @@ -0,0 +1,151 @@ +--- +linkTitle: Concepts and Structure +title: ROS 2 Concepts and Structure +description: Understanding basic concepts and structure of the ROS 2 Gem in Open 3D Engine (O3DE). +weight: 300 +toc: true +--- + +This topic describes the underlying concepts and structure of the [ROS 2 Gem](/docs/user-guide/gems/reference/robotics/ros2/) in **Open 3D Engine (O3DE)**. +You will learn about how ROS 2 and O3DE communicate, and how ROS 2 components interface with each other to perform various functions in a robotics simulation. + +## ROS 2 Concepts + +For a quick introduction to ROS 2 concepts, please refer to [ROS 2 Concepts documentation](https://docs.ros.org/en/humble/Concepts.html). + +## Structure and Communication + +The Gem creates a [ROS 2 node](https://docs.ros.org/en/humble/Tutorials/Understanding-ROS2-Nodes.html) which is directly a part of the ROS 2 ecosystem. As such, your simulation will not use any bridges to communicate and is subject to configuration through settings such as Environment Variables. It is truly a part of the ecosystem. + +Note that the simulation node is handled through `ROS2SystemComponent` - a singleton. However, you are free to create and use your own nodes if you need more than one. + +Typically, you will be creating publishers and subscriptions in order to communicate with the ROS 2 ecosystem using common topics. +This is done through [rclcpp API](https://docs.ros.org/en/humble/p/rclcpp/generated/classrclcpp_1_1Node.html#classrclcpp_1_1Node). Example: + +``` +auto ros2Node = ROS2Interface::Get()->GetNode(); +AZStd::string fullTopic = ROS2Names::GetNamespacedName(GetNamespace(), m_MyTopic); +m_myPublisher = ros2Node->create_publisher(fullTopic.data(), QoS()); +``` + +Note that QoS class is a simple wrapper to [`rclcpp::QoS`](https://docs.ros.org/en/humble/p/rclcpp/generated/classrclcpp_1_1QoS.html). + +## Components overview + +- __Central Singleton__ + - `ROS2SystemComponent` +- __Core abstractions__ + - `ROS2FrameComponent` + - `ROS2SensorComponent` +- __Sensors__ + - `ROS2CameraSensorComponent` + - `ROS2GNSSSensorComponent` + - `ROS2IMUSensorComponent` + - `ROS2LidarSensorComponent` + - `ROS2OdometrySensorComponent` +- __Robot control__ + - `AckermannControlComponent` + - `RigidBodyTwistControlComponent` + - `SkidSteeringControlComponent` +- __Spawner__ + - `ROS2SpawnerComponent` + - `ROS2SpawnPointComponent` +- __Vehicle dynamics__ + - `AckermannVehicleModelComponent` + - `SkidSteeringModelComponent` + - `WheelControllerComponent` +- __Robot Import (URDF) system component__ + - `ROS2RobotImporterSystemComponent` + +See the [class diagram](/docs/user-guide/interactivity/robotics/class-diagram/) to understand how components are connected. + +### Frames + +`ROS2FrameComponent` is a representation of an interesting physical part of the robot. It handles the spatio-temporal relationship between this part and other frames of reference. It also encapsulates namespaces, which help to distinguish between different robots and different parts of the robot, such as in the case of multiple identical sensors on one robot. + +All Sensors and the Robot Control components require `ROS2FrameComponent`. + +### Sensors + +Sensors acquire data from the simulated environment and publish it to ROS 2 domain. Sensor components derive from `ROS2SensorComponent`. + +- Each sensor has a configuration, including one or more Publishers. +- Sensors publish at a given rate (frequency). +- Some sensors can be visualized. + +If your sensor is not supported by the provided sensor components, you will most likely need to create a new component deriving from `ROS2SensorComponent`. +When developing a new sensor, it is useful to look at how sensors that are already provided within the ROS2 Gem are implemented. +Consider adding your new sensor as a separate Gem. A good example of such sensor Gem is the [RGL Gem](https://github.com/RobotecAI/o3de-rgl-gem). + +### Robot Control + +The Gem comes with `ROS2RobotControlComponent`, which you can use to move your robot through: + +- [Twist](https://github.com/ros2/common_interfaces/blob/master/geometry_msgs/msg/Twist.msg) messages +- [AckermannDrive](https://github.com/ros-drivers/ackermann_msgs/blob/master/msg/AckermannDrive.msg) + +The component subscribes to these command messages on a configured topic. The topic is `cmd_vel` by default, in a namespace as dictated by __ROS2Frame__. + +To make use of received command messages, use either `AckermannControlComponent`, `RigidBodyTwistControlComponent`, or `SkidSteeringControlComponent`, depending on the steering type. +You can also implement your own control component or use Lua scripting to handle these commands. +Unless scripting is used, control components should translate ROS 2 commands to events on `VehicleInputControlBus`. +These events will be handled by a [`VehicleModelComponent`](#vehicle-model) if it is present. +You can use tools such as [rqt_robot_steering](https://index.ros.org/p/rqt_robot_steering/) to move your robot with Twist messages. +`RobotControl` is suitable to use with [ROS 2 navigation stack](https://navigation.ros.org/). +It is possible to implement your own control mechanisms with this component. + +### Vehicle Model + +`VehicleModelComponent` serves the purpose of converting inputs such as target velocity, steering or acceleration to physical forces on parts of a vehicle (robot). `VehicleModel` has a `VehicleConfiguration` which is used to define axles, parametrize and assign wheels. The model requires a `WheelControllerComponent` present in each wheel entity. It also uses an implementation of `DriveModel`, which converts vehicle inputs to forces acting on steering elements and wheels. + +### Vehicle Dynamics + +See the [Vehicle Dynamics](vehicle-dynamics.md) section. + +### Spawner + +`ROS2SpawnerComponent` handles spawning entities during a simulation. +Before the simulation, you must set up as the component's available spawnables and define the named spawn points in the component's properties via the **O3DE Editor**. +This can be done by adding `ROS2SpawnPointComponent` to a child entity of an entity with `ROS2SpawnerComponent`. +During the simulation you can access the names of available spawnables and request spawning by using ROS 2 services. +The names of services are `/get_available_spawnable_names` and `/spawn_entity` respectivly. +GetWorldProperties.srv and SpawnEntity.srv types are used to handle these features. +In order to request the defined spawn point names, you can use the `/get_spawn_points_names` service with the `GetWorldProperties.srv` type. +Detailed information about specific spawn point, such as pose, can be accessed using the `/get_spawn_point_info` service with the `GetModelState.srv` type. +All used services types are defined in the **gazebo_msgs** package. + +- **Spawning**: To spawn, you must pass in the spawnable name into `request.name` and the position of entity into `request.initial_pose`. + - Example call: + ``` + ros2 service call /spawn_entity gazebo_msgs/srv/SpawnEntity '{name: 'robot', initial_pose: {position:{ x: 4, y: 4, z: 0.2}, orientation: {x: 0.0, y: 0.0, z: 0.0, w:.0}}} + ``` +- **Spawning in defined spawn point**: Pass in a spawnable into `request.name` and the name of the spawn point into `request.xml`. + - Example call: + ``` + ros2 service call /spawn_entity gazebo_msgs/srv/SpawnEntity '{name: 'robot', xml: 'spawn_spot'}' + ``` +- **Available spawnable names access**: Send the names of available spawnables into `response.model_names`. + - Example call: + ``` + ros2 service call /get_available_spawnable_names gazebo_msgs/srv/GetWorldProperties + ``` +- **Defined spawn points' names access**: Send the names of defined points into `response.model_names` + - Example call: + ``` + ros2 service call /get_spawn_points_names gazebo_msgs/srv/GetWorldProperties + ``` +- **Detailed spawn point info access**: Pass in the spawn point name into `request.model_name` and the defined pose into `response.pose`. + - Example call: + ``` + ros2 service call /get_spawn_point_info gazebo_msgs/srv/GetModelState '{model_name: 'spawn_spot'}' + ``` + +## Related topics + +| Topic | Description | +|-----------------------------------------------|----------------------------------| +| [ROS 2 Gem class diagram](class-diagram.md) | Class diagram for the ROS 2 Gem. | + + + + diff --git a/content/docs/user-guide/interactivity/robotics/creating-robotic-simulation.md b/content/docs/user-guide/interactivity/robotics/creating-robotic-simulation.md new file mode 100644 index 00000000000..50ef5d6c18b --- /dev/null +++ b/content/docs/user-guide/interactivity/robotics/creating-robotic-simulation.md @@ -0,0 +1,37 @@ +--- +linkTitle: Creating a Robotic Simulation +title: Creating a Robotic Simulation +description: A step-by-step process on how to create a robotic simulation using the ROS 2 Gem in Open 3D Engine (O3DE). +weight: 400 +toc: true +--- + +## How to create your own robotic simulation + + + +Once you are set up and familiar with the [example project](/docs/user-guide/interactivity/robotics/overview/#demos), consider the following steps: +1. [Create a new O3DE project](/docs/welcome-guide/create/) + 1. It is best to use one of [Project Templates](/docs/user-guide/interactivity/robotics/overview/#templates) for robotics to start quickly. +2. [Registering ROS2 Gem for your Project](/docs/user-guide/project-config/register-gems/) guide. +3. 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/XACRO. + 3. Imported models might require some adjustments to be simulation-ready. + 4. Mobilize robot with Vehicle Dynamics controllers. +4. 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 like to consider tradeoffs between performance and realism in each case. + 2. Use `ROS2SensorComponent` as a base class if you are implementing a new sensor. +5. Develop necessary sensors and their prefabs. +7. Develop your scene and simulation scenario, placing Assets and configuring components. +8. Run the simulation with your ROS 2 robot stack. You can build quickly one with some of many [ROS 2 packages](https://index.ros.org/packages/#humble) and projects in [ROS 2 ecosystem](https://project-awesome.org/fkromer/awesome-ros2). + + diff --git a/content/docs/user-guide/interactivity/robotics/overview.md b/content/docs/user-guide/interactivity/robotics/overview.md new file mode 100644 index 00000000000..0cce2208f1d --- /dev/null +++ b/content/docs/user-guide/interactivity/robotics/overview.md @@ -0,0 +1,38 @@ +--- +linkTitle: Overview +title: Robotics Overview +description: An overview of concepts, Gems, templates and demos for robotics in Open 3D Engine (O3DE). +weight: 100 +--- + +The ROS 2 Gem helps to build robotic simulations with [ROS 2 / Robot Operating System](https://www.ros.org/). + +The ROS 2 Gem contains a number of components to build robotic simulations, such as sensors, +controllers of different types of drives, manipulator arms, and dynamic spawning of robots. It also comes with plenty of utilities. + +## Gems + +There are several Gems to power robotic simulations with **Open 3D Engine (O3DE)**. +- [ROS 2 Gem](/docs/user-guide/gems/reference/robotics/ros2), the central and the most important one. It provides most features and other robotics Gems depend on it. +- Project Templates for Robotics and connected Asset Gems. These provide a good starting point for simulation development and a set of assets to use. +- 3rd party Gems: + - [Robotec GPU Lidar (RGL) Gem](https://github.com/RobotecAI/o3de-rgl-gem) - GPU accelerated LIDAR simulation in O3DE using CUDA. + +## Templates + +There are two templates for robotics: +- [ROS 2 project template](https://github.com/o3de/o3de-extras/tree/development/Templates/Ros2ProjectTemplate): + - A simple interior scene with ROSBot XL robot: + - It is the most lightweight and basic robotic project template. + - The project starts with a differential drive (skid steering) robot. +- [Warehouse project template](https://github.com/o3de/o3de-extras/tree/development/Templates/Ros2FleetRobotTemplate): + - A photorealistic warehouse with a Proteus robot. + - Easily customizable, extendable environment. + - It is easy to add more robots using the included spawning component. + +## Demos + +There are open-source project demonstrating what can be done with the ROS 2 Gem: +- [Robot Vacuum Sample](https://github.com/o3de/RobotVacuumSample): a robot vacuum navigating in a beautiful apartment: +- [Robot Harvesting Sample](https://github.com/o3de/ROSConDemo): agricultural robots orchestrated through ROS 2 to pick apples in a scenic orchard. + diff --git a/content/docs/user-guide/interactivity/robotics/project-configuration.md b/content/docs/user-guide/interactivity/robotics/project-configuration.md new file mode 100644 index 00000000000..6b00a7af55c --- /dev/null +++ b/content/docs/user-guide/interactivity/robotics/project-configuration.md @@ -0,0 +1,87 @@ +--- +linkTitle: Project Configuration +title: ROS 2 Project Configuration +description: How to install dependencies and build a project with the ROS 2 Gem in Open 3D Engine (O3DE). +weight: 200 +toc: true +--- + +## Requirements + +* Ubuntu 22.04 or 20.04. Other Ubuntu versions and Linux distributions can also work as long as they support ROS 2. + {{< important >}} + The ROS 2 Gem is not available for Windows. + {{< /important >}} +* [O3DE built from source on Linux](/docs/welcome-guide/setup/setup-from-github/building-linux). +* The [latest released version](https://docs.ros.org/en/rolling/Releases.html#list-of-distributions ) of ROS 2. This instruction assumes that the `desktop` version is installed. Otherwise, some packages might be missing. The O3DE ROS 2 has been tested with: + * [ROS 2 Humble](https://docs.ros.org/en/humble/Installation.html) with Ubuntu 22.04. + * [ROS 2 Galactic](https://docs.ros.org/en/galactic/Installation.html) with Ubuntu 20.04. + +## Setting up + +### ROS 2 ecosystem + +#### Source your ROS 2 workspace + +To build or run projects using ROS 2 Gem, you must [source your ROS 2 workspace](https://docs.ros.org/en/humble/Tutorials/Beginner-CLI-Tools/Configuring-ROS2-Environment.html) in your console. The best way to ensure that ROS 2 is sourced at all times is by adding the following line to the `~/.profile` file: +``` +source /opt/ros//setup.bash +``` +Replace `` with the ROS 2 distribution name (`humble`, `galactic`, and so on). +Then, you must log out and log in from Ubuntu for the change to take effect. + +#### Custom packages + +The Gem fully supports [workspace overlaying](https://docs.ros.org/en/humble/Tutorials/Beginner-Client-Libraries/Creating-A-Workspace/Creating-A-Workspace.html#source-the-overlay). +Source your workspace on top of the ROS 2 installation to include custom packages. + +The Gem comes with a number of ROS 2 packages already included and linked, but you might want to include additional packages in your project. +To do so, use the `target_depends_on_ros2` function in your project's `Gem/CMakeLists.txt`: + +``` +target_depends_on_ros2_packages( ) +``` + +#### Working with multiple ROS versions + +If you have multiple ROS 2 versions installed, make sure you [source](https://docs.ros.org/en/humble/Tutorials/Workspace/Creating-A-Workspace.html#source-the-overlay) the one you would like to use. You can check which version is sourced in your console by checking the value of `ROS_DISTRO` environment variable (`echo $ROS_DISTRO`). + +> You currently need to rebuild your project if it was previously built with another ROS version. + +### Additional ROS 2 packages required + +* gazebo_msgs: `ros-${ROS_DISTRO}-gazebo-msgs` + * gazebo_msgs are used for robot spawning (no dependency on Gazebo). +* Ackermann messages: `ros-${ROS_DISTRO}-ackermann-msgs` +* Control toolbox `ros-${ROS_DISTRO}-control-toolbox` +* XACRO `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 +``` + +### Clone this repository + +The ROS 2 Gem lives in the [`o3de/o3de-extras`](https://github.com/o3de/o3de-extras) repository. Clone the GitHub repository to your machine: + +``` +git clone https://github.com/o3de/o3de-extras +``` + +### Adding Gem to your project + +To use the ROS 2 Gem in your O3DE project, you need to register the Gem with O3DE. Then, you can enable the Gem in your project. Run the following commands from the O3DE folder: +``` +scripts/o3de.sh register --gem-path /Gems/ROS2 +scripts/o3de.sh enable-gem -gn ROS2 -pp +``` + +For more information, refer to [Adding and Removing Gems](/docs/user-guide/project-config/add-remove-gems/) and [Registering Gems](/docs/user-guide/project-config/register-gems/). + +### Building + +The ROS 2 Gem is built when you build an O3DE project and enable the ROS 2 Gem. For more information, refer to [Project Creation](/docs/welcome-guide/create/) and [Adding and Removing Gems in a Project](/docs/user-guide/project-config/add-remove-gems/). Make sure to [source your ROS 2 workspace](#source-your-ros-2-workspace) before building. diff --git a/content/docs/user-guide/interactivity/robotics/vehicle-dynamics.md b/content/docs/user-guide/interactivity/robotics/vehicle-dynamics.md new file mode 100644 index 00000000000..5fe879fb184 --- /dev/null +++ b/content/docs/user-guide/interactivity/robotics/vehicle-dynamics.md @@ -0,0 +1,78 @@ +--- +linkTitle: Vehicle Dynamics +title: ROS 2 Vehicle Dynamics +description: Understanding basic concepts and structure of the ROS 2 Gem's vehicle dynamics in Open 3D Engine (O3DE). +toc: true +--- + +## Vehicle Model + +**VehicleModelComponent** serves the purpose of converting inputs such as target velocity, steering or acceleration to physical forces on parts of a vehicle (robot). **VehicleModel** has a **VehicleConfiguration** which is used to define axles, parametrize and assign wheels. The model requires a **WheelControllerComponent** present in each wheel entity. It also uses an implementation of **DriveModel**, which converts vehicle inputs to forces acting on steering elements and wheels. + +### Wheel Controller + +A wheel controller is a controller that should be attached to the vehicle's wheel. The wheel entity should have PhysX Hinge Joint attached. The Joint controller should have: + - **Motor Configuration / Use Motor** enabled, + - **Motor Configuration / Force Limit Value** set to a desirable value. + +![PhysX Joint](/images/user-guide/gems/ros2/physx_joint.png) + +The wheel controller has the following parameters shown below. + +![Wheel Controller](/images/user-guide/gems/ros2/wheelController.png) + +| Parameter Name | Description | +|------------------------------|----------------------------------------------------------------------------------| +| **Steering Entity** | The entity that has a PhysX Hinge Joint that changes the direction of the wheel. | +| **Scale of steering axis** | Allows the user to change the ratio or / and direction of wheel steering. | + +### Ackermann Drive Model + +The implementation of **AckermannDriveModel** uses [PID controllers](https://en.wikipedia.org/wiki/PID_controller) from [control_toolbox](https://github.com/ros-controls/control_toolbox) package. The model computes velocities or forces in the joints of the vehicle and applies it accordingly to commanded velocity. + +![AckermannModel](/images/user-guide/gems/ros2/ackermanModel.png) + +Parameters of the model are exposed to the user via **AckermannVehicleModelComponent**: + +| Parameter Name | Description | +|---------------------------------------------------|--------------------------------------------------------------------------| +| **DriveModel / Axles** | List of axles of the vehicle. | +| **DriveModel / Axles / Axle Wheels** | List of wheels in axis. | +| **DriveModel / Axles / Is it a steering** | If it is enabled the Ackermann Drive Model will apply a steering angle. | +| **DriveModel / Axles / Is it a drive** | If it is enabled the Ackermann Drive Model will apply drive force. | +| **DriveModel / Axles / Track** | Distance between front and rear axis. | +| **DriveModel / Axles / Wheelbase** | Distance between left and right wheel. | +| **DriveModel / Steering PID / P** | Proportional gain of PID controller for steering servo. | +| **DriveModel / Steering PID / I** | Integral gain of PID controller for steering servo. | +| **DriveModel / Steering PID / D** | Derivative gain of PID controller for steering servo. | +| **DriveModel / Steering PID / IMin** | Minimum integration impact of PID. | +| **DriveModel / Steering PID / IMax** | Maximum integration impact of PID. | +| **DriveModel / Steering PID / AntiWindUp** | Prevents integral wind-up in PID. | +| **DriveModel / Steering PID / OutputLimit** | Clamps output to maximum value. | +| **DriveModel / Vehicles Limits / Speed limit** | Maximum achievable linear speed in meters per second. | +| **DriveModel / Vehicles Limits / Steering limit** | Maximum achievable steering angle. | + +### Skid Steering Drive Model +The model computes velocities in the joints of the vehicle and applies it accordingly to commanded velocity and configuration. + +![SkidSteeringModel](/images/user-guide/gems/ros2/skidSteeringModel.png) +Parameters of the model are exposed to the user via **AckermannVehicleModelComponent**: + +| Parameter Name | Description | +|--------------------------------------------------------|--------------------------------------------------------------------| +| **DriveModel / Axles** | List of axles of the vehicle. | +| **DriveModel / Axles / Axle Wheels** | List of wheels in axis. | +| **DriveModel / Axles / Is it a steering** | It is ignored in this model. | +| **DriveModel / Axles / Is it a drive** | If it is enabled, the Skid Steering Drive Model will apply velocities to the axis' wheels.| +| **DriveModel / Axles / Track** | Distance between front and rear axis. | +| **DriveModel / Axles / Wheelbase** | Distance between left and right wheel. | +| **DriveModel / Vehicles Limits / Linear speed limit** | Maximum achievable linear speed in meters per second. | +| **DriveModel / Vehicles Limits / Angular speed limit** | Maximum achievable angular speed in radians per second. | + +### Manual control + +The **VehicleModel** will handle input events with names "steering" and "accelerate". This means you can add an [InputComponent](/docs/user-guide/components/reference/gameplay/input/) to the same entity and define an input map for your input devices (such as a keyboard or a gamepad) to control the vehicle manually. + +You can use tools such as [rqt_robot_steering](https://index.ros.org/p/rqt_robot_steering/) to move your robot with Twist messages. **RobotControl** is suitable to use with [ROS 2 navigation stack](https://navigation.ros.org/). + +It is possible to implement your own control mechanisms with this component.