Joints Manipulation


Manipulating joints is crucial for applications involving robotic arms or other joint systems such as legged locomotion. O3DE supports control of joint systems with ROS through packages such as ros2_controllers , and through integration with MoveIt2 .

Supported features

With manipulation components, you can:

  • Publish JointState ROS messages automatically with JointsManipulationComponent.
  • Control joint systems through FollowJointTrajectory ROS action.
  • Control systems based on articulations as well as hinge and prismatic joints.
  • Extend interfaces for developers to implement your own control components through JointsManipulationRequests and JointsPositionControllerRequests.
  • Use manipulation components in multi-robot scenarios.


Manipulation components only work with single degree of freedom joints.

Components and their interactions

Movement of joints is handled through a set of interfaces and components that implement them.

Move joints towards desired positions.
JointsManipulationRequestsJointsManipulationComponentHold and publish joints state information, relay commands to controllers.
JointsTrajectoryRequestsJointsTrajectoryComponentHost action server for trajectory commands, control trajectory through a sequence of positions.

Simulating joint systems

Start quickly with Manipulation Template

If your goal is to simulate a robotic arm, the quickest way to start is to create a project from Manipulation Template.

If you followed the steps of project configuration, your environment variables for O3DE_HOME and PROJECT_PATH will be set, and the templates registered. Create a new project with the following command:

${O3DE_HOME}/scripts/ create-project --project-path $PROJECT_PATH --template-name Ros2RoboticManipulationTemplate

The template comes with a couple of examples which you can run following its README .

Configure your robot

Import the robot

Once your project is up, use the robot import feature to load your robot of choice into O3DE. Make sure that the checkbox Use articulation for joints and rigid bodies is checked on the last page of the importer. Using articulations is strongly recommended for stable simulation of robotic arms and other joint systems.

Add necessary components

If the import proceeded without issues, open the root entity of your newly created prefab and add three new components:

  • JointsArticulationControllerComponent to control the robot`s movement.
  • JointsTrajectoryComponent to listen for the MoveIt trajectory messages.
  • JointsManipulationEditorComponent which publishes joint_states and sets the initial position.

Enable motors in joints

Enable motors on all joints and set motor force limit, stiffness and damping values. Joints with motors enabled will keep their set position.

Set initial positions and topic name

  • In the JointsManipulationEditorComponent, add initial positions for all joints. Joint names can be found in the prefabs entities inside the ROS2FrameComponent joint name. The initial positions are in radians.
  • In the JointsTrajectoryComponent, set the topic for controlling the trajectory. Typically, this topic name ends with joint_trajectory_controller, but should be same as in your MoveIt configuration files.

Start the simulation

Start the simulation and see as the robot sets itself into its initial position. If something is not right, check the O3DE console for logs, which include all joint names. The robot is now ready for being controlled using MoveIt.

Running with MoveIt2


Install moveIt packages for your ROS distribution:

sudo apt install ros-${ROS_DISTRO}-moveit ros-${ROS_DISTRO}-moveit-resources

Following that, prepare MoveIt launch files. This can be achieved by creating the files manually, using configuration provided with your robot, or using the MoveIt Setup Assistant .

You can see two examples in the Manipulation Template .

Finally, run the launch file and control your simulated joint system with MoveIt.


GrippersSimulating robotic grippers in O3DE