Example: AgileX robots

This example creates a MoveIt configuration for an AgileX Piper H manipulator with its gripper. It applies the generic workflow from the previous tutorial and plans from a tool center point at the center of the gripper.

Prerequisites

This example assumes ROS 2 Humble, a workspace at /home/ros/ros2_ws, and the forked AgileX arm description packages in the workspace source directory.

Build and source the robot description:

source /opt/ros/humble/setup.bash
cd /home/ros/ros2_ws
colcon build --packages-select agx_arm_urdf
source install/setup.bash
ros2 pkg prefix agx_arm_urdf

The last command should print the installed package path.

1. Add the Piper H tool center point

Open:

/home/ros/ros2_ws/src/agx_arm_urdf/piper_h/urdf/piper_h_with_gripper_description.xacro

Inside the top-level <robot> element, add an empty TCP link after the existing gripper_base_joint:

<link name="gripper_tcp"/>

<joint name="gripper_tcp_joint" type="fixed">
  <origin xyz="0 0 0.138" rpy="0 0 0"/>
  <parent link="gripper_base"/>
  <child link="gripper_tcp"/>
</joint>

The fixed joint places the planning target at the nominal grasp center without adding a degree of freedom. Verify the 0.138 metre offset against the gripper CAD or physical robot.

Validate the modified description:

xacro \
  /home/ros/ros2_ws/src/agx_arm_urdf/piper_h/urdf/piper_h_with_gripper_description.xacro \
  > /tmp/piper_h_with_gripper.urdf

check_urdf /tmp/piper_h_with_gripper.urdf

The parsed link tree should contain gripper_tcp below gripper_base.

2. Configure the planning groups

Start the assistant and load the combined Piper H description:

ros2 run moveit_setup_assistant moveit_setup_assistant

/home/ros/ros2_ws/src/agx_arm_urdf/piper_h/urdf/piper_h_with_gripper_description.xacro

Create the arm planning group with:

  • Group name: piper_h_with_gripper

  • Type: kinematic chain

  • Base link: base_link

  • Tip link: gripper_tcp

  • Kinematics solver: kdl_kinematics_plugin/KDLKinematicsPlugin

Create the gripper group with:

  • Group name: piper_h_gripper

  • Links: gripper_link, gripper_link1, and gripper_link2

Create the end effector with:

  • Name: piper_h_gripper

  • End-effector group: piper_h_gripper

  • Parent group: piper_h_with_gripper

  • Parent link: gripper_tcp

The corresponding SRDF structure is:

<group name="piper_h_with_gripper">
  <chain base_link="base_link" tip_link="gripper_tcp"/>
</group>

<end_effector
  name="piper_h_gripper"
  parent_link="gripper_tcp"
  group="piper_h_gripper"
  parent_group="piper_h_with_gripper"/>

3. Configure kinematics and controllers

Keep KDL assigned to the arm group:

piper_h_with_gripper:
  kinematics_solver: kdl_kinematics_plugin/KDLKinematicsPlugin
  kinematics_solver_search_resolution: 0.005
  kinematics_solver_timeout: 0.005

Configure a trajectory controller for the arm and a gripper action controller for piper_h_gripper. The MoveIt arm-controller entry must include the action namespace:

piper_h_with_gripper_controller:
  default: true
  action_ns: follow_joint_trajectory
  type: FollowJointTrajectory

Generate the package at:

/home/ros/ros2_ws/src/piper_h_with_gripper_moveit_config

Check that numeric values in joint_limits.yaml are floating point. For example, use 5.0 and 0.0, not 5 and 0.

4. Build and run

cd /home/ros/ros2_ws
colcon build --packages-select \
  agx_arm_urdf \
  piper_h_with_gripper_moveit_config
source install/setup.bash

ros2 launch piper_h_with_gripper_moveit_config demo.launch.py

In RViz, select piper_h_with_gripper as the planning group. The interactive marker should appear at gripper_tcp. Select piper_h_gripper when testing the gripper group; it does not have a six-dimensional IK marker.

If the marker is missing, verify the planning group in RViz, the TCP link in the SRDF, and the KDL entry in kinematics.yaml. If execution fails, confirm that moveit_controllers.yaml contains both default: true and action_ns: follow_joint_trajectory.