This documentation is for a prerelease version of O3DE. Click here to switch to the latest release, or select a version from the dropdown.

Version:

Icon of a magnifying glass.
  Edit on GitHub

IN THIS ARTICLE

SDFormat plugins

Introduction

Robots described in either SDFormat , URDF , or 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.

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 <gazebo> 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 to learn more about sensors and plugins.

Plugin import architecture

Plugin import, i.e. the mapping between Gazebo description and O3DE components, is based on the O3DE reflection system. 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. The only difference is that plugins for models require ROS2::SDFormat::ModelPluginImporterHook structure registered under ModelPluginImporterHooks attribute tag.