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’ filenames. This way you can override the default behavior of the Robot Importer using your specific implementation connected with the specific filename.

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.

You might need to enable motor in joints (or 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.

O3DE Joint State Publisher

ROS2JointStatePublisherModel is a pre-defined hook used to map libgazebo_ros_joint_state_publisher.so SDFormat plugin into the JointsManipulationEditorComponent in O3DE. The component is added to the base link of the robot alongside either JointsArticulationControllerComponent or JointsPIDControllerComponent depending on whether you decide to use articulations in your imported robot.

Note that, as the namespace policy in O3DE differs from Gazebo, this hook won’t change the namespace on which joint states are published whether or not you specified it in the SDFormat file. Similarly, you won’t be able to specify the names of the joints to be published; O3DE JointsManipulationEditorComponent will publish the states of each joint either way.

O3DE Joint Pose Trajectory

ROS2JointPoseTrajectoryModel is a pre-defined hook used to map libgazebo_ros_joint_pose_trajectory.so SDFormat plugin into the JointsTrajectoryComponent in O3DE. The component is added to the base link of the robot alongside JointsManipulationEditorComponent and either JointsArticulationControllerComponent or JointsPIDControllerComponent depending on whether you decide to use articulations in your imported robot. Similarly to Joint State Publisher hook, namespace remapping won’t be parsed here.

If you plan on importing both Joint State Publisher and Joint Pose Trajectory in one SDFormat file, Joint State Publisher might not get imported because of the order in which plugins are listed in your file. If that happens, JointsManipulationEditorComponent will be added anyway, but parameters of created component might differ from those specified in your robot description. Information about it will be visible in the Robot Importer summary window. For now, there are two ways to resolve this issue:

1. Make sure that libgazebo_ros_joint_state_publisher.so plugin is listed before libgazebo_ros_joint_pose_trajectory.so in your SDFormat file. If not, you can change their order manually by simply swapping their descriptions (including headlines as well as plugin parameters) using copy-paste.
2. After performing succesful import of your SDFormat file (excluding libgazebo_ros_joint_state_publisher.so), go to the base link of your model and manually adjust parameters of the JointsManipulationEditorComponent. Note that since this O3DE component serves not only for publishing joint states, but also for actions like setting joints start positions, you might encounter more parameters avilable than just those that define the way your joint states will be published. The parameters that you might need to adjust are all visible under the Joint State Publisher section.

After preforming successful import, you might need to enable motor in joints (or articulation links) of your joints manually in order to be able to adjust their trajectory.

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.