diff --git a/content/docs/user-guide/_index.md b/content/docs/user-guide/_index.md index f48f097c556..a7ed4dab5d1 100644 --- a/content/docs/user-guide/_index.md +++ b/content/docs/user-guide/_index.md @@ -14,15 +14,15 @@ Welcome to the O3DE User Guide! This documentation contains information and guid Read about [the features provided by Open 3D Engine](/docs/welcome-guide/features-intro). -| Documentation | Details | -|--------------------------------------|---------| -| [Assets](assets/) | Learn about O3DE's asset management tools and pipeline. | -| [Build](build/) | Learn how to use the CMake generator with O3DE projects to generate IDE projects and build them. | -| [Components](components/) | Learn about the components that add functionality to your entities in O3DE. | -| [Editor](editor/) | Learn how to use the O3DE Editor. | -| [Settings Registry](settings/) | Learn how to use the Settings Registry to maintain settings and configurations for O3DE applications and tools. | -| [Gems](gems/) | Learn about the Gems that extend O3DE.| -| [Interactivity](interactivity/) | Learn how to implement player navigation controls and other world interaction methods. | +| Documentation | Details | +|--------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------| +| [Assets](assets/) | Learn about O3DE's asset management tools and pipeline. | +| [Build](build/) | Learn how to use the CMake generator with O3DE projects to generate IDE projects and build them. | +| [Components](components/) | Learn about the components that add functionality to your entities in O3DE. | +| [Editor](editor/) | Learn how to use the O3DE Editor. | +| [Settings Registry](settings/) | Learn how to use the Settings Registry to maintain settings and configurations for O3DE applications and tools. | +| [Gems](gems/) | Learn about the Gems that extend O3DE. | +| [Interactivity](interactivity/) | Learn how to simulate robots, implement player navigation controls and other world interaction methods. | | [Networking](networking/) | Learn about the low-level networking stack in O3DE and the multiplayer framework that uses it to provide multiplayer features in games and simulations. | | [Packaging](packaging/) | Learn how to package your O3DE-based product for release. | | [Programming](programming/) | Learn about core engine programming concepts in O3DE. | diff --git a/content/docs/user-guide/gems/reference/robotics/ros2.md b/content/docs/user-guide/gems/reference/robotics/ros2.md index 35f0fad1e0e..5633e8e7ba9 100644 --- a/content/docs/user-guide/gems/reference/robotics/ros2.md +++ b/content/docs/user-guide/gems/reference/robotics/ros2.md @@ -5,7 +5,7 @@ description: The ROS 2 Gem helps build robotic simulations with Robot Operating toc: true --- - + The **ROS 2 Gem** uses the [Robot Operating System (ROS)](https://docs.ros.org/en/rolling/index.html) to enable robotic simulation in **Open 3D Engine (O3DE)**. The ROS 2 Gem has the following features: @@ -14,10 +14,11 @@ robotic simulation in **Open 3D Engine (O3DE)**. The ROS 2 Gem has the following * 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. + * Custom messages, services, and actions just work! * 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. + * Are abstracted through the Sensor Component Base, 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 (3D and 2D), Camera (including Depth channel), IMU, Odometry, GNSS, and Contact. * Utilities for automated handling of: * Simulation time: - publishing `/clock`, with support for non-real time. * Computing and publishing of transformation frames (`/tf`, `/tf_static`). @@ -27,11 +28,16 @@ robotic simulation in **Open 3D Engine (O3DE)**. The ROS 2 Gem has the following * Robot Control Component: * Provides a quick-to-use method of controlling your robot. * Includes support for Twist and AckermannDrive message interfaces. +* Manipulation and Grippers: + * Support for robot arms and other joint systems. + * Configurable components, easy to integrate with MoveIt2. + * Finger and vacuum gripper. * 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. +* Robot Importer + * Allows robot imports from the URDF, SDFormat and XACRO. + * Supports sensor plugins, creating sensor components in O3DE on import. ## Related topics diff --git a/content/docs/user-guide/interactivity/_index.md b/content/docs/user-guide/interactivity/_index.md index de9d275a094..18415dc1b1b 100644 --- a/content/docs/user-guide/interactivity/_index.md +++ b/content/docs/user-guide/interactivity/_index.md @@ -3,11 +3,12 @@ title: Interactivity and simulation weight: 800 --- -| Topic | Description | -| - | - | -| [Physics](physics) | Simulate physics interactions in O3DE using NVIDIA PhysX for collisions and rigid bodies, and NVIDIA Cloth to simulate cloth. | -| [Prefabs](prefabs) | Learn about O3DE's prefab system. | -| [Audio](audio) | Control audio and sound effects in your game. | -| [Input](input) | Allow player input such as key presses and mouse clicks, to create an interactive experience in O3DE. | -| [User interface](user-interface) | Create a user interface in your game such as with images, text, buttons, menus, scroll boxes, and heads-up displays (HUDs). | -| [Navigation and pathfinding](navigation-and-pathfinding) | Create a navigation mesh and find walkable paths between entities and positions. | +| Topic | Description | +|----------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [Physics](physics) | Simulate physics interactions in O3DE using NVIDIA PhysX for collisions and rigid bodies, and NVIDIA Cloth to simulate cloth. | +| [Robotics](robotics) | Create robotic simulations integrated with Robot Operating System (ROS) 2 in O3DE. | +| [Prefabs](prefabs) | Learn about O3DE's prefab system. | +| [Audio](audio) | Control audio and sound effects in your game. | +| [Input](input) | Allow player input such as key presses and mouse clicks, to create an interactive experience in O3DE. | +| [User interface](user-interface) | Create a user interface in your game such as with images, text, buttons, menus, scroll boxes, and heads-up displays (HUDs). | +| [Navigation and pathfinding](navigation-and-pathfinding) | Create a navigation mesh and find walkable paths between entities and positions. | diff --git a/content/docs/user-guide/interactivity/robotics/_index.md b/content/docs/user-guide/interactivity/robotics/_index.md index 36042933baf..7aca5f96eaf 100644 --- a/content/docs/user-guide/interactivity/robotics/_index.md +++ b/content/docs/user-guide/interactivity/robotics/_index.md @@ -8,12 +8,12 @@ description: Learn how to create robotics simulation in Open 3D Engine (O3DE) wi 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. | -| [Importing robots](importing-robot.md) | Learn how to import robots using URDF/XACRO importer. | +| [Importing robots](importing-robot) | Learn how to import robots using Robot Importer. | | [Grippers](grippers.md) | Documentation of robotic grippers feature. | | [Joints Manipulation](joints-manipulation.md) | Joints manipulation, such as with robotic manipulator arms. | | [Deploying simulation](deploying-simulation.md) | Building standalone simulation. | @@ -23,7 +23,7 @@ These Gems provide various O3DE components such as sensors, robot control and st ## 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/interactivity/robotics/class-diagram.md b/content/docs/user-guide/interactivity/robotics/class-diagram.md deleted file mode 100644 index ec09077b201..00000000000 --- a/content/docs/user-guide/interactivity/robotics/class-diagram.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -linkTitle: Class Diagram -title: ROS 2 Gem Details -description: Class Diagram for ROS 2 Gem in Open 3D Engine (O3DE). -toc: true ---- - -# Diagram of classes - -Some classes with relationships and functions are presented on this diagram. Specific sensor classes (e.g. Lidar) are -not included. Some classes are presented in sub-diagrams: -![classes diagram](/images/user-guide/gems/ros2/diagram_ros2_gem.svg) -![Vehicle Dynamics](/images/user-guide/gems/ros2/ROSVehicleDynamics.svg) 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 index 9b5e21a1997..9c389910474 100644 --- a/content/docs/user-guide/interactivity/robotics/concepts-and-components-overview.md +++ b/content/docs/user-guide/interactivity/robotics/concepts-and-components-overview.md @@ -42,7 +42,9 @@ Note that QoS class is a simple wrapper to [`rclcpp::QoS`](https://docs.ros.org/ - `ROS2GNSSSensorComponent` - `ROS2IMUSensorComponent` - `ROS2LidarSensorComponent` + - `ROS2Lidar2DSensorComponent` - `ROS2OdometrySensorComponent` + - `ROS2ContactSensorComponent` - __Robot control__ - `AckermannControlComponent` - `RigidBodyTwistControlComponent` @@ -62,8 +64,6 @@ Note that QoS class is a simple wrapper to [`rclcpp::QoS`](https://docs.ros.org/ - `JointsArticulationControllerComponent` - `JointsPIDControllerComponent` -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. @@ -72,13 +72,13 @@ 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`. +Sensors acquire data from the simulated environment and publish it to ROS 2 domain. Sensor components derive from `ROS2SensorComponentBase`. - Each sensor has a configuration, including one or more Publishers. -- Sensors publish at a given rate (frequency). +- Sensors publish at a given rate (frequency), using one of two event sources: frame update or physics scene simulation events. - 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`. +If your sensor is not supported by the provided sensor components, you will most likely need to create a new component deriving from `ROS2SensorComponentBase`. 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). @@ -162,13 +162,3 @@ All used services types are defined in the **gazebo_msgs** package. ``` 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/importing-robot.md b/content/docs/user-guide/interactivity/robotics/importing-robot.md deleted file mode 100644 index 10c75901acc..00000000000 --- a/content/docs/user-guide/interactivity/robotics/importing-robot.md +++ /dev/null @@ -1,127 +0,0 @@ ---- -linkTitle: Importing robot -title: Importing robots -description: Importing robots from URDF with ROS 2 Gem in Open 3D Engine (O3DE). -weight: 450 -toc: true ---- - -[ROS 2 Gem](/docs/user-guide/gems/reference/robotics/ros2/) for **Open 3D Engine (O3DE)** includes a **Robot Importer** tool that imports URDF and XACRO formats, robot descriptions, to the ROS 2 ecosystem. - -## About URDF and XACRO formats - -URDF and XACRO are robot description standards used widely in the ROS ecosystem. - -[Unified Robot Description Format (URDF)](http://wiki.ros.org/urdf) is an XML-based file format that describes the physical characteristics of a robot in a structured and standardized way. It includes information about the robot's joints, links, sensors, and other components, as well as their properties such as mass, inertia, and geometry. - -[XML Macros (XACRO)](http://wiki.ros.org/xacro) is a macro language that simplifies the creation and maintenance of URDF files. XACRO allows you to generate URDF files using XML macros. In XACRO, you can define parameters and include files, which is useful to change and iterate on robot models. You can also expand and reuse XACRO across multiple robot models. - -URDF/XACRO files contain complete robot descriptions, including references to external geometry files. While you can define primitive geometries directly within the URDF/XACRO file, it's common practice to use external mesh files, in formats such as DAE (Collada) or STL, to represent the visual and collision shapes of the robot. -Robot models are typically available in packages that include the URDF/XACRO file and additional geometry files that contain visualizations and collision shapes, either as primitive geometries or external mesh files. These packages may be distributed as ROS workspaces, which are more straightforward to use in ROS applications. - - -## Introduction to Robot Importer - -Import robots into your O3DE simulation project using the Robot Importer that's included in the ROS 2 Gem. Robot Importer has the following features: - -- Guides you through the import process step by step. -- Reads URDF and XACRO files. -- Copies all required mesh files to the `Assets` folder of your O3DE project. -- Creates a prefab with a multi-body structure using articulations or classic rigid bodies and joints components. - -## Importing a robot into your simulation project - - -### Prerequisite - -Before you can use robot description files in a ROS package, you must first build a workspace with the package and its dependencies. This ensures that Robot Importer can find all the required files. - -To build, create a workspace and run `colcon build`. - -For more information, refer to the robot description package's documentation, which is often included in the GitHub repository's README file. - -### Loading the robot definition file with Robot Importer - -1. Load your project and select a level in O3DE Editor. - -2. Launch Robot Importer from the Editor by doing either of the following: - - Select **Main Menu > Tools > Robot Importer** - - Select the **Robot Importer** icon in the toolbar - - ![Robot Importer](/images/user-guide/gems/ros2/URDF_importer_button.png) - -3. Read the information page in the Robot Importer. Then select **Next**. - -4. Load a URDF file by doing the following: - - - Select a URDF or XACRO file to import by clicking on the **[...]** button. - - (Optional) Enable the checkbox if you want the importer to copy meshes into the O3DE project `Assets` folder. If disabled, the importer tries to find matching meshes in the project asset library. CRC comparison verifies the identity of meshes. - - Click **Next**. - - ![Robot Importer](/images/user-guide/gems/ros2/URDF_importer_load_file.png) - -5. (Optional) If the selected XACRO file contains parameters, set the parameters' values. To edit parameters, **double-click** on the value. When you're finished, click **Next**. - - ![Robot Importer](/images/user-guide/gems/ros2/URDF_importer_XACRO_parameters.png) - - {{< note >}} -How you set the parameters depends on the XACRO project that you are importing. For a successful import, refer to the XACRO project's documentation. - -If your XACRO project fails to import, you will see a message with the output of the ROS 2 XACRO executable, similar to the following. - -![Robot Importer](/images/user-guide/gems/ros2/URDF_importer_fail.png) - {{< /note >}} - -### Processing robot assets - -After the the XACRO and URDF file loads, Robot Importer displays a table with a list of all the mesh files (assets) used in the model. Each row of the table describes one asset, with information divided into the following columns: - -- **URDF mesh path** - Relative file path of the mesh, as defined in the URDF file. -- **Resolved mesh from URDF** - Absolute file path of the mesh located in your filesystem. -- **Product asset** - Relative file path of the generated product asset (`*.azmodel` or `*.pxmesh`) in your O3DE project's `Cache` directory. -- **Source asset** - Relative file path of the source asset in your O3DE project's `Assets` directory. -- **Type** - The type of the asset, either `visual` or `collider`. - - Assets that loaded successfully have a green checkmark, whereas assets that failed to load are marked red. - -To see additional information about each asset, **double-click** its row. This opens the O3DE Asset Processor, which shows import details. This information is especially helpful to troubleshoot assets that failed to import. - -Click **Next** when finished. - -![Robot Importer](/images/user-guide/gems/ros2/URDF_importer_mesh_list.png) - -**What to do if there are problems with importing assets?** - -If the **Source asset** field is marked as failed, then Robot Importer could not find a reference to the mesh file in the file system. In such a situation, ensure that the robot's description package is built and sourced correctly. - -If the **Product asset** field is marked as failed, then the Asset Builder could not build the product asset. Refer to the Asset Processor output or the log files in the `/user/log` directory - -You can either resolve the issues now or after you finish using Robot Importer: -- To resolve, click **Back** and resolve problems with the mesh files. Then click **Next** to retry import. -- To resolve later, click **Next** and finish URDF import. Then add the missing meshes in the O3DE Editor. - -### Creating a robot prefab - -1. Create a prefab by doing the following: - - - Enter a prefab name. - - (Optional) Enable the checkbox if you want to base the robot physics on articulations or classic rigid bodies and joints structure. - - Click **Create Prefab**. - - ![Robot Importer](/images/user-guide/gems/ros2/URDF_importer_prefab_creation.png) - - {{< note >}} -**Use articulation for joints and rigid bodies** depends on the robot structure and simulation requirements. In general, articulations are more stable and computational efficient, but have some limitations. The 2 main limtations are: -- Articulations are only available in PhysX 5. By default, O3DE is built with PhysX 4. -- Articulations only support tree-structures natively. Closed loops are not allowed. - -We recommend to use articulations in robotic simulation whenever possible. For more details, refer to [Articulations](https://nvidia-omniverse.github.io/PhysX/physx/5.1.3/docs/Articulations.html) in NVIDIA PhysX 5 documentation. - {{< /note >}} - -1. After creating a prefab, review a summary of the generated entities. - - ![Robot Importer](/images/user-guide/gems/ros2/URDF_importer_summary.png) - -### Re-importing robots - -Use the Robot Importer to re-import URDF files. In some cases, assets (mesh files) don't update if they were previously imported correctly. To work around this and do a complete re-import, delete the assets from your project by using the Asset Browser or in the directory. diff --git a/content/docs/user-guide/interactivity/robotics/importing-robot/_index.md b/content/docs/user-guide/interactivity/robotics/importing-robot/_index.md new file mode 100644 index 00000000000..a3d65bc50ff --- /dev/null +++ b/content/docs/user-guide/interactivity/robotics/importing-robot/_index.md @@ -0,0 +1,154 @@ +--- +linkTitle: Importing robot +title: Importing robots +description: Importing robots from description file with ROS 2 Gem in Open 3D Engine (O3DE). +weight: 450 +toc: true +--- + +[ROS 2 Gem](/docs/user-guide/gems/reference/robotics/ros2/) for **Open 3D Engine (O3DE)** includes a **Robot Importer** tool that imports robots' descriptions used in the ROS 2 ecosystem. + +## About supported robot description formats + +SDFormat, URDF, and XACRO are widely used robot description standards within the ROS (Robot Operating System) ecosystem. + +[SDFormat](http://sdformat.org/) is an XML-based file format used to describe objects and environments for robot simulations. Originally developed for the [Gazebo](https://gazebosim.org/home) simulator, SDFormat has evolved into a comprehensive standard that covers all aspects of simulation, including static and dynamic objects, visual materials, and physics properties. + +[Unified Robot Description Format (URDF)](http://wiki.ros.org/urdf) is an XML-based file format that describes the physical characteristics of a robot in a structured and standardized way. It includes information about the robot's joints, links, sensors, and other components, as well as their properties such as mass, inertia, and geometry. + +[XML Macros (XACRO)](http://wiki.ros.org/xacro) is a macro language that simplifies the creation and maintenance of URDF files. XACRO allows you to generate URDF files using XML macros. In XACRO, you can define parameters and include files, which is useful to change and iterate on robot models. You can also expand and reuse XACRO across multiple robot models. + +URDF, XACRO, and SDFormat files contain complete robot descriptions, including references to external geometry files. While you can define primitive geometries directly within the robot description file, it is a common practice to use external mesh files, in formats such as DAE (Collada) or STL, to represent the visual and collision shapes of the robot. + +Robot models are typically available in packages that include the robot description file and additional geometry files with visualizations and collision shapes, either as primitive geometries or external mesh files. These packages may be distributed as ROS workspaces, which are more straightforward to use in ROS applications. + +## Introduction to Robot Importer + +Import robots into your O3DE simulation project using the Robot Importer that's included in the ROS 2 Gem. Robot Importer has the following features: + +- Guides you through the import process step by step. +- Allows to change parameters of the import, including search paths for assets. +- Reads SDFormat, URDF and XACRO files. +- Copies all required assets files to the `Assets` folder of your O3DE project. +- Creates a prefab with a multi-body structure using articulations or classic rigid bodies and joints components. + +## Importing a robot into your simulation project + +### Prerequisite + +Depending on a content of robot description files, you might need to build a ROS workspace with the package and its dependencies. This ensures that Robot Importer can find all the required files. In some cases, it is possible to append paths used by the Robot Importer in the Wizard instead, and to skip the build of a ROS workspace completely. + +To build, create a workspace and run `colcon build`. Do not forget to source ROS 2 workspace before launching the O3DE Editor. + +For more information, refer to the robot description package's documentation, which is often included in the GitHub repository's README file. + +### Loading the robot definition file with Robot Importer + +1. Load your project and select a level in O3DE Editor. + +2. Launch Robot Importer from the Editor by doing either of the following: + - Select **Main Menu > Tools > Robot Importer** + - Select the **Robot Importer** icon in the toolbar + + ![Robot Importer](/images/user-guide/gems/ros2/URDF_importer_button.png) + +3. Read the information page in the Robot Importer. Then select **Next**. + +4. Load a description file by doing the following: + + - Select an SDFormat, URDF, or XACRO file to import by clicking on the **[...]** button. + - A number of options are available to modify the behavior of the importer: + * Use Articulations - Determines whether PhysX articulation components should be used for joints and rigid bodies. + * Preserve URDF fixed joint - When set, preserves any fixed joints found when importing a URDF file. This prevents the joint reduction logic in libsdformat from merging links of those joints. + * Fix URDF to be compatible with libsdformat - It allows you to import some URDFs or XACRO files that are not fully compatible. With this feature enabled, Robot Importer will try to adjust the URDF code to be compatible. + * Path Resolvers - SDFormat, URDF, and XACRO files are almost always referencing some other files (like meshes, and textures). This feature allows you to give a hint to Robot Importer where to find those assets. + This feature can be useful, in an advanced situation like importing legacy files or trying to import ROS 1 packages. \ + **Important** This feature does not affect the XACRO parsing, since the XACRO bundled with ROS 2 installation is used at this moment. + * Use `AMENT_PREFIX_PATH` - Uses the [AMENT_PREFIX_PATH](https://design.ros2.org/articles/ament.html) environment variable to locate asset references. It is a default behavior for ROS 2 description packages. + * Prefix Replacement - This is a map that allows you to determine paths for the Path Resolvers, described earlier. + - Click **Next**. + + ![Robot Importer](/images/user-guide/gems/ros2/URDF_importer_load_file.png) + +5. (Optional) If you are importing an XACRO file which file contains parameters, set the parameters' values. To edit parameters, **double-click** on the value. When you're finished, click **Next**. + + ![Robot Importer](/images/user-guide/gems/ros2/URDF_importer_XACRO_parameters.png) + + {{< note >}} +How you set the parameters depends on the XACRO project that you are importing. For a successful import, refer to the XACRO project's documentation. + +If your XACRO project fails to import, you will see a message with the output of the ROS 2 XACRO executable, similar to the following. + +![Robot Importer](/images/user-guide/gems/ros2/URDF_importer_fail.png) + {{< /note >}} + +6. (Optional) If the XACRO or URDF contains some missing information will be adjusted automatically. +This feature is available if you enable the option 'Fix URDF to be compatible with libsdformat' in point 4. +Currently, some common problems are resolved: + - missing inertia matrices, masses are added with the default values, + - Robot Importer changes names to have joint names unique. +After this automatic adjustment, you can take a look into the changes that were made, and go through the modified URDF. +![Robot Importer](/images/user-guide/gems/ros2/URDF_fixing_result.png) + + {{< note >}} + Option 'Fix URDF to be compatible with libsdformat' allows you to successfully import URDF files that are not compatible with simulation, but please remember to adjust the resulting prefab. + {{< /note >}} + +### Processing robot assets + +After the the description file loads, Robot Importer displays a table with a list of all the assets used in the model. +Each row of the table describes one asset, with information divided into the following columns: + +- **URDF/SDF mesh path** - Relative file path of the mesh, as defined in the URDF file. +- **Resolved mesh from URDF/SDF** - Absolute file path of the mesh located in your filesystem. +- **Product asset** - Relative file path of the generated product asset (e.g. `*.azmodel`, `*.pxmesh`) in your O3DE project's `Cache` directory. +- **Source asset** - Relative file path of the source asset in your O3DE project's `Assets` directory. +- **Type** - The type of the asset. + + Assets that loaded successfully have a green checkmark, whereas assets that failed to load are marked red. + +To see additional information about each asset, **double-click** its row. This opens the O3DE Asset Processor, which shows import details. This information is especially helpful to troubleshoot assets that failed to import. + +Click **Next** when finished. + +![Robot Importer](/images/user-guide/gems/ros2/URDF_importer_mesh_list.png) + +**What to do if there are problems with importing assets?** + +If the **Source asset** field is marked as failed, then Robot Importer cannot find a reference to the mesh file in the file system. +In such a situation, ensure that the robot's description package is built and sourced correctly. +You can try to give a custom way to resolve prefixes in Point 4. + +If the **Product asset** field is marked as failed, then the Asset Builder cannot build the product asset. +Refer to the Asset Processor output or the log files in the `/user/log` directory. + +You can either resolve the issues now or after you finish using Robot Importer: +- To resolve, click **Back** and resolve problems with the mesh files. Then click **Next** to retry the import. +- To resolve later, click **Next** and finish URDF import. Then add the missing meshes in the O3DE Editor. + +### Creating a robot prefab + +1. Create a prefab by doing the following: + + - Enter a prefab name. + - (Optional) Select a spawn position. + If there are spawn points added to the scene, you can choose one in the drop-down menu. + - Click **Create Prefab**. + + ![Robot Importer](/images/user-guide/gems/ros2/URDF_importer_prefab_creation.png) + +2. After creating a prefab, review a summary of the generated entities. + + ![Robot Importer](/images/user-guide/gems/ros2/URDF_importer_summary.png) + +3. Finally, there is a prefab in the scene. You can add one or more [sensors](/docs/user-guide/interactivity/robotics/concepts-and-components-overview/#sensors) or mobilize robot with [ROS 2 Vehicle Dynamics](/docs/user-guide/interactivity/robotics/vehicle-dynamics/) or using [Joint Manipulation](/docs/user-guide/interactivity/robotics/joints-manipulation/). + + ![Robot Importer](/images/user-guide/gems/ros2/URDF_result.png) + +### Re-importing robots + +Use the Robot Importer to re-import URDF files. In some cases, assets (mesh files) don't update if they were previously imported correctly. To work around this and do a complete re-import, delete the assets from your project by using the Asset Browser or in the directory. + +### Details + +Details about supported SDFormat sensors are available in the [SDFormat sub-page](./sdformat-sensors.md) \ No newline at end of file diff --git a/content/docs/user-guide/interactivity/robotics/importing-robot/sdformat-sensors.md b/content/docs/user-guide/interactivity/robotics/importing-robot/sdformat-sensors.md new file mode 100644 index 00000000000..867bc8017c4 --- /dev/null +++ b/content/docs/user-guide/interactivity/robotics/importing-robot/sdformat-sensors.md @@ -0,0 +1,95 @@ +--- +linkTitle: SDFormat sensors +title: SDFormat sensors +description: Detailed description of support of SDFormat sensors in Robot Importer. +weight: 100 +--- + +## Introduction + +Robots described in either [SDFormat](http://sdformat.org/), [URDF](http://wiki.ros.org/urdf), or [XACRO](http://wiki.ros.org/xacro) format, can be imported into your O3DE simulation project using the Robot Importer. The tool creates O3DE entities and components that model a robot. You can find more details about Robot Importer in the [documentation](/docs/user-guide/interactivity/robotics/importing-robot/). + +Similarly, the robots' [sensors](http://sdformat.org/spec?ver=1.10&elem=sensor) are imported from the description files into O3DE using ROS 2 sensor components available in [ROS 2 Gem](/docs/user-guide/gems/reference/robotics/ros2/). Note, that the sensor's description can be stored directly in SDFormat files or using `` tag in URDF and XACRO files. + +## Sensor import architecture + +Sensor import, i.e. the mapping between Gazebo description and O3DE components, is based on the O3DE [reflection system](/docs/user-guide/programming/components/reflection/reflecting-for-serialization/). In particular, O3DE components that are designed to mirror the behavior of SDFormat sensors and/or plugins are registered using a specialized attribute tag. The import structure, called _hook_, implements the conversion scheme between the robot description parameters and O3DE data. The Robot Importer finds all active _hooks_ and checks, if any of them can be used to import SDFormat data. The mapping is extendable, allowing you to add your _hooks_ and map them to existing SDFormat data. + +It is important to note, that implementation of sensors in [ROS 2 Gem](/docs/user-guide/gems/reference/robotics/ros2/) exposes ROS 2 communication interfaces by design, which makes it comparable to Gazebo sensor plugins. Therefore, you do not have to define a Gazebo sensor plugin if you want to make ROS 2 topics available. On the other hand, both sensor and plugin names must match the _hook's_ definition to be added to O3DE representation of the robot if the plugin definition exists in the robot description file. This way you can override the default behavior of the Robot Importer with your specific implementation of the same sensor. + +### SDF sensor tag mappings + +Four basic sensors' _hooks_ are predefined in Robot Importer. These can be summarized as follows: + +| _Hook_ name | Supported SDFormat sensors | Supported SDFormat plugins | O3DE sensor component | +| ------------------ | -------------------------- | ----------------------------- | --------------------------- | +| _CameraSensorHook_ | `camera_sensor` | `libgazebo_ros_camera` | `ROS2CameraSensorComponent` | +| | `depth_camera` | `libgazebo_ros_depth_camera` | | +| | `rgbd_camera` | `libgazebo_ros_openni_kinect` | | +| _GNSSSensorHook_ | `gps`, `navsat` | `libgazebo_ros_gps_sensor` | `ROS2GNSSSensor` | +| _ImuSensorHook_ | `imu` | `libgazebo_ros_imu_sensor` | `ROS2ImuSensorComponent` | +| _LidarSensorHook_ | `lidar`, `ray` | `libgazebo_ros_ray_sensor` | `ROS2LidarSensorComponent` | +| | `gpu_lidar`, `gpu_ray` | `libgazebo_ros_laser` | _see information below_ | + +GPU implementation of ray/lidar sensors is not included in ROS 2 Gem and requires additional [O3DE RGL Gem](https://github.com/RobotecAI/o3de-rgl-gem). GPU sensors are mapped during the import to run on a CPU if this Gem is not available. + +### Extending default mapping + +You can extend the default mapping by implementing additional _hooks_ and registering them in the system based on the _SerializeContext_ reflection system. Typically, this consists of three tasks. + +First, you need to declare `ROS2::SDFormat::SensorImporterHook` structure that consists of the following: +* set of SDFormat sensors associated with your import scheme +* set of plugin names associated with your import scheme +* set of the supported parameters in the input robot description (used for import verbose only) +* registered callback function that is invoked by Robot Importer when _hook's_ definition matches the input data + +The registered callback function creates a number of O3DE components that are necessary to simulate a particular sensor. Additionally, it parses the robot description file to read certain processing parameters and lists the supported sensors and plugins. Your sample implementation for `sdf::SensorType::NAVSAT` that implements `libgazebo_myps_sensor.so` in O3DE can look as follows: + +```cpp +ROS2::SDFormat::SensorImporterHook ROS2SensorHooks::MyGNSSSensor() +{ + ROS2::SDFormat::SensorImporterHook importerHook; + importerHook.m_sensorTypes = AZStd::unordered_set{ sdf::SensorType::NAVSAT }; + importerHook.m_supportedSensorParams = AZStd::unordered_set{ ">update_rate", ">my_parameter" }; + importerHook.m_pluginNames = AZStd::unordered_set{ "libgazebo_mygps_sensor.so" }; + importerHook.m_sdfSensorToComponentCallback = [](AZ::Entity& entity, const sdf::Sensor& sdfSensor) + -> ROS2::SDFormat::SensorImporterHook::ConvertSensorOutcome + { + if (!sdfSensor.NavSatSensor()) + { + return AZ::Failure(AZStd::string("Failed to read parsed SDFormat data of %s NavSat sensor", sdfSensor.Name().c_str())); + } + const float myUpdateRate = sdfSensor.UpdateRate(); + const float myParameter = sdfSensor.Element()->Get("my_parameter", 1.0f).first; + if (Utils::CreateComponent(entity, myUpdateRate, myParameter)) + { + return AZ::Success(); + } + else + { + return AZ::Failure(AZStd::string("Failed to create NavSat MyO3DEEditorComponent.")); + } + }; + + return importerHook; +} +``` + +Your second task is to implement your desired simulation behavior in an O3DE component, which would be created by the Robot Importer. Finally, you need to define and register your _hook_ via the _SerializeContext_ reflection system using `SensorImporterHooks` attribute tag. This allows the Robot Importer to find and add your _hook_ to the mapping. The registration can be done in any O3DE editor component and multiple _hooks_ can be registered at once. For simplicity, you might want to add the registration directly to your O3DE component. A sample code implementing the registration scheme can be as follows: +```cpp +void MyO3DEEditorComponent::Reflect(AZ::ReflectContext* context) +{ + if (auto serializeContext = azrtti_cast(context)) + { + const ROS2::SDFormat::SensorImporterHook& myImporterHook = CreateMyHook(); + const ROS2::SDFormat::SensorImporterHook& anotherImporterHook = CreateAnotherHook(); + serializeContext->Class() + ->Attribute( + "SensorImporterHooks", + ROS2::SDFormat::SensorImporterHooksStorage{ AZStd::move(myImporterHook), AZStd::move(anotherImporterHook) }); + } + // more reflection code goes here +} +``` + + diff --git a/content/docs/user-guide/interactivity/robotics/overview.md b/content/docs/user-guide/interactivity/robotics/overview.md index afdfdd34767..24181545219 100644 --- a/content/docs/user-guide/interactivity/robotics/overview.md +++ b/content/docs/user-guide/interactivity/robotics/overview.md @@ -39,4 +39,4 @@ There are three templates for robotics: 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. - +- [Automated Fulfillment Center](https://github.com/RobotecAI/ROSCon2023Demo): robotic arms and Autonomous Mobile Robots working on palletization and intra-logistics. diff --git a/content/docs/user-guide/interactivity/robotics/project-configuration.md b/content/docs/user-guide/interactivity/robotics/project-configuration.md index cb061bbb6f5..482ca376f08 100644 --- a/content/docs/user-guide/interactivity/robotics/project-configuration.md +++ b/content/docs/user-guide/interactivity/robotics/project-configuration.md @@ -60,7 +60,7 @@ If a `desktop` installation of ROS 2 distro was selected, everything else should 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 +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}-xacro ``` ### Clone the Gem repository @@ -122,11 +122,13 @@ Robotic project templates are designed to help you to quickly start simulating r #### ROS 2 Project Templates -There are two templates for robotics: +There are three templates for robotics: - [ROS 2 project template](https://github.com/o3de/o3de-extras/tree/development/Templates/Ros2ProjectTemplate): - A versatile, lightweight template that is good for a starting project and includes a robot with differential drive. - [Warehouse project template](https://github.com/o3de/o3de-extras/tree/development/Templates/Ros2FleetRobotTemplate): - A photorealistic warehouse with a Proteus robot, easy to customize and scale up (multi-robot). +- [Manipulation project template](https://github.com/o3de/o3de-extras/tree/development/Templates/Ros2RoboticManipulationTemplate): + - Includes two levels with robotic manipulator arms: one focused on palletization, the other one on R&D. :bulb: The template repositories also include examples that you can try out by following their README files. @@ -166,4 +168,4 @@ Once your project is built, run the following command to start the Editor: ```shell ${PROJECT_PATH}/build/linux/bin/profile/Editor -``` \ No newline at end of file +``` diff --git a/static/images/user-guide/gems/ros2/URDF_fixing_result.png b/static/images/user-guide/gems/ros2/URDF_fixing_result.png new file mode 100644 index 00000000000..3f5a6e42ee3 Binary files /dev/null and b/static/images/user-guide/gems/ros2/URDF_fixing_result.png differ diff --git a/static/images/user-guide/gems/ros2/URDF_importer_fail.png b/static/images/user-guide/gems/ros2/URDF_importer_fail.png index c8296c35db3..e184bf06247 100644 Binary files a/static/images/user-guide/gems/ros2/URDF_importer_fail.png and b/static/images/user-guide/gems/ros2/URDF_importer_fail.png differ diff --git a/static/images/user-guide/gems/ros2/URDF_importer_load_file.png b/static/images/user-guide/gems/ros2/URDF_importer_load_file.png index 59cf3cadc04..3610ca8ab33 100644 Binary files a/static/images/user-guide/gems/ros2/URDF_importer_load_file.png and b/static/images/user-guide/gems/ros2/URDF_importer_load_file.png differ diff --git a/static/images/user-guide/gems/ros2/URDF_importer_mesh_list.png b/static/images/user-guide/gems/ros2/URDF_importer_mesh_list.png index c5f6ed29116..8a56ef9f1ff 100644 Binary files a/static/images/user-guide/gems/ros2/URDF_importer_mesh_list.png and b/static/images/user-guide/gems/ros2/URDF_importer_mesh_list.png differ diff --git a/static/images/user-guide/gems/ros2/URDF_importer_prefab_creation.png b/static/images/user-guide/gems/ros2/URDF_importer_prefab_creation.png index 5a3b5af8159..10f8bf23db9 100644 Binary files a/static/images/user-guide/gems/ros2/URDF_importer_prefab_creation.png and b/static/images/user-guide/gems/ros2/URDF_importer_prefab_creation.png differ diff --git a/static/images/user-guide/gems/ros2/URDF_importer_summary.png b/static/images/user-guide/gems/ros2/URDF_importer_summary.png index 670b0ce7dd0..040b758fb1c 100644 Binary files a/static/images/user-guide/gems/ros2/URDF_importer_summary.png and b/static/images/user-guide/gems/ros2/URDF_importer_summary.png differ diff --git a/static/images/user-guide/gems/ros2/URDF_result.png b/static/images/user-guide/gems/ros2/URDF_result.png new file mode 100644 index 00000000000..d843ef39020 Binary files /dev/null and b/static/images/user-guide/gems/ros2/URDF_result.png differ