From daacf9bd9551c5bd284ef90d7ce7e4e10b93aefb Mon Sep 17 00:00:00 2001 From: Jan Hanca Date: Fri, 19 Jan 2024 11:21:53 +0100 Subject: [PATCH 1/2] add sdformat model control plugin description Signed-off-by: Jan Hanca --- .../robotics/importing-robot/_index.md | 2 +- .../importing-robot/sdformat-plugins.md | 38 +++++++++++++++++++ .../importing-robot/sdformat-sensors.md | 2 +- 3 files changed, 40 insertions(+), 2 deletions(-) create mode 100644 content/docs/user-guide/interactivity/robotics/importing-robot/sdformat-plugins.md diff --git a/content/docs/user-guide/interactivity/robotics/importing-robot/_index.md b/content/docs/user-guide/interactivity/robotics/importing-robot/_index.md index a3d65bc50ff..8b68eeed18a 100644 --- a/content/docs/user-guide/interactivity/robotics/importing-robot/_index.md +++ b/content/docs/user-guide/interactivity/robotics/importing-robot/_index.md @@ -151,4 +151,4 @@ Use the Robot Importer to re-import URDF files. In some cases, assets (mesh file ### Details -Details about supported SDFormat sensors are available in the [SDFormat sub-page](./sdformat-sensors.md) \ No newline at end of file +Details about supported SDFormat sensors are available in the [SDFormat sensors sub-page](./sdformat-sensors.md). Additional information about SDFormat model plugins are given in the [SDFormat plugins sub-page](./sdformat-plugins.md). \ No newline at end of file diff --git a/content/docs/user-guide/interactivity/robotics/importing-robot/sdformat-plugins.md b/content/docs/user-guide/interactivity/robotics/importing-robot/sdformat-plugins.md new file mode 100644 index 00000000000..d2e01f44391 --- /dev/null +++ b/content/docs/user-guide/interactivity/robotics/importing-robot/sdformat-plugins.md @@ -0,0 +1,38 @@ +--- +linkTitle: SDFormat plugins +title: SDFormat plugins +description: Detailed description of support of SDFormat plugins 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/). + +SDFormat standard allows the extension of the functionality of the imported robot by adding _plugins_ to the description. The same description can be incorporated into URDF and XACRO files using `` tag. Technically, such a plugin is a dynamically loaded chunk of code that can extend _world_, _model_, or _sensor_ description. Currently, only _models'_ and _sensors'_ _plugins_ are supported. Please refer to [SDformat sensors page](./sdformat-sensors.md) to learn more about sensors' _plugins_. + +## Plugin import architecture + +_Plugin_ 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 _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. + +The matching between the _hooks_ and the robot description is done based on the plugins' names. This way you can override the default behavior of the Robot Importer using your specific implementation connected with the specific name. + +### Default model plugins + +Two _hooks_ to extend the _models_ are predefined in Robot Importer. They simplify the import, however, due to differences between O3DE and Gazebo, some manual tuning of O3DE components is required to make the robot drivable. For models with _articulations_ enabled consider changing _Force Limit Value_, _Stiffness Value_, and _Damping Value_ in _Motor Configuration_ of wheel links. Finally, make sure the inertia and the mass of each link is configured correctly. Similarly, _Force Limit Value_ in _Motor Configuration_ of wheel joints is a key parameter when importing a robot without _articulation links_. + +#### O3DE Skid Steering Robot Control + +_ROS2SkidSteeringModel_ is a pre-defined _hook_ used to map `libgazebo_ros_skid_steer_drive.so` and `libgazebo_ros_diff_drive.so` SDFormat plugins in either ROS or ROS 2 formats into a number O3DE components. In particular, it creates _ROS2RobotControlComponent_, and _SkidSteeringModelComponent_ O3DE components in a base link of the robot alongside _WheelControllerComponent_ components in wheels. + +#### O3DE Ackermann Robot Control + +_ROS2AckermannModel_ is a pre-defined hook used to map `libgazebo_ros_ackermann_drive.so` SDFormat plugin into a number of O3DE components. In particular, it creates _ROS2RobotControlComponent_, and _SkidSteeringModelComponent_ O3DE components in a base link of the robot alongside _WheelControllerComponent_ components in wheels. + +If you decide to use articulations in your imported robot, you might need to enable motor in articulation links of your steering joints manually. Moreover, your import will fail when steering joints in SDFormat description are defined as _Universal Joints_, which are currently not supported in O3DE. + +### 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. The scheme for adding hooks for models' plugins is alike the scheme for extending sensor support described in detail in [SDformat sensors page](./sdformat-sensors.md). The only difference is that plugins for models require `ROS2::SDFormat::ModelPluginImporterHook` structure registered under `ModelPluginImporterHooks` attribute tag. + + 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 index 867bc8017c4..bf9fc9ce4f5 100644 --- a/content/docs/user-guide/interactivity/robotics/importing-robot/sdformat-sensors.md +++ b/content/docs/user-guide/interactivity/robotics/importing-robot/sdformat-sensors.md @@ -43,7 +43,7 @@ First, you need to declare `ROS2::SDFormat::SensorImporterHook` structure that c * 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: +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_mygps_sensor.so` in O3DE can look as follows: ```cpp ROS2::SDFormat::SensorImporterHook ROS2SensorHooks::MyGNSSSensor() From 6a52d6e197e3a08a145155bcf8d1b57a9f4c5ba5 Mon Sep 17 00:00:00 2001 From: Jan Hanca Date: Mon, 4 Mar 2024 14:41:58 +0100 Subject: [PATCH 2/2] Applying code review suggestions Co-authored-by: moudgils <47460854+moudgils@users.noreply.github.com> Signed-off-by: Jan Hanca --- .../user-guide/interactivity/robotics/importing-robot/_index.md | 2 +- .../interactivity/robotics/importing-robot/sdformat-plugins.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/content/docs/user-guide/interactivity/robotics/importing-robot/_index.md b/content/docs/user-guide/interactivity/robotics/importing-robot/_index.md index 8b68eeed18a..dd1b43eb268 100644 --- a/content/docs/user-guide/interactivity/robotics/importing-robot/_index.md +++ b/content/docs/user-guide/interactivity/robotics/importing-robot/_index.md @@ -27,7 +27,7 @@ Robot models are typically available in packages that include the robot descript 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. +- Allows you 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. diff --git a/content/docs/user-guide/interactivity/robotics/importing-robot/sdformat-plugins.md b/content/docs/user-guide/interactivity/robotics/importing-robot/sdformat-plugins.md index d2e01f44391..696d8f405a8 100644 --- a/content/docs/user-guide/interactivity/robotics/importing-robot/sdformat-plugins.md +++ b/content/docs/user-guide/interactivity/robotics/importing-robot/sdformat-plugins.md @@ -9,7 +9,7 @@ weight: 100 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/). -SDFormat standard allows the extension of the functionality of the imported robot by adding _plugins_ to the description. The same description can be incorporated into URDF and XACRO files using `` tag. Technically, such a plugin is a dynamically loaded chunk of code that can extend _world_, _model_, or _sensor_ description. Currently, only _models'_ and _sensors'_ _plugins_ are supported. Please refer to [SDformat sensors page](./sdformat-sensors.md) to learn more about sensors' _plugins_. +SDFormat standard allows the extension of the functionality of the imported robot by adding _plugins_ to the description. The same description can be incorporated into URDF and XACRO files using `` tag. Technically, such a plugin is a dynamically loaded chunk of code that can extend _world_, _model_, or _sensor_ description. Currently, only _models_, _sensors_ and _plugins_ are supported. Please refer to [SDformat sensors page](./sdformat-sensors.md) to learn more about _sensors_ and _plugins_. ## Plugin import architecture