RobotGuide
Hands-on/Build a six-axis arm in Gazebo from scratch and make it obey you

Hands-on 2 / 4

Build a six-axis arm in Gazebo from scratch and make it obey you

URDF → gz-sim → gz_ros2_control → MoveIt 2, one chain walked end to end, about 6 hours

6–8 h11 stepsbasic Linux commands required; a little ROS 2 exposure is enough

Math: trigonometry and matrices (math bridge T1)Coding: command line and basic LinuxHardware: a Linux computer (Ubuntu 24.04)

What you will have in hand when done

A 6-axis arm moving in Gazebo, planned and executed by MoveIt 2 to specified poses; swapping the end effector or adding an obstacle never means starting over.

This is the only chain in the robot-arm direction that you must walk through by hand. Once it works, you can bring up any unfamiliar arm model within two days — because the process is identical and only the parameters differ.

Before you start

You needVersion / notes
Ubuntu 24.04 + ROS 2 Jazzyofficial pairing
Gazebo Harmonic (gz-sim 8)ros-jazzy-ros-gz
gz_ros2_controlros-jazzy-gz-ros2-control
MoveIt 2ros-jazzy-moveit
G1 GazeboG3 ros2_controlG2 MoveIt 2

Contents

  1. Install the environment: confirm the versions pair up first
  2. Create the package: fix the directory layout now, move no files later
  3. Write the URDF: six joints plus inertial parameters, none may be skipped
  4. Add ros2_control tags: let the simulation know your joints
  5. Start Gazebo and put the robot inside
  6. Load the controllers: broadcast state first, then control trajectories
  7. Send the first trajectory: make it really move
  8. MoveIt Setup Assistant: generate the config, do not hand-write it
  9. Plan and execute in RViz
  10. Add a camera and obstacles: this is where 'engineering' begins
  11. Acceptance check: no UI, just these four commands
01

Install the environment: confirm the versions pair up first

ROS 2 Jazzy officially pairs with Gazebo Harmonic (gz-sim 8); do not install Gazebo Classic — most tutorials online will lead you astray. Four commands to install everything; verify before moving on.

terminal / code
sudo apt update
sudo apt install -y ros-jazzy-desktop ros-jazzy-ros-gz \
  ros-jazzy-ros2-control ros-jazzy-ros2-controllers \
  ros-jazzy-gz-ros2-control ros-jazzy-moveit ros-jazzy-xacro

gz sim --versions
ros2 pkg list | grep -E 'gz_ros2_control|moveit_core'

You pass when you see this

`gz sim --versions` prints 8.x; both greps produce output.

Stuck?

SymptomMost likely causeWhat to do
`gz: command not found`ros_gz was installed but not gz itself`sudo apt install -y gz-harmonic`, or launch directly with `ros2 run ros_gz_sim gz_sim`
gz is 7.x (Garden)An old version lingers in the system and PATH finds it first`sudo apt remove gz-garden` then reinstall; or just always use `ros2 run ros_gz_sim gz_sim`
02

Create the package: fix the directory layout now, move no files later

One package holds models, config and launch. Split the directories once: urdf for xacro, config for controller and MoveIt configuration, launch for startup files, worlds for scenes.

terminal / code
mkdir -p ~/arm_ws/src && cd ~/arm_ws/src
ros2 pkg create --build-type ament_cmake arm6 \
  --dependencies rclcpp urdf xacro
mkdir -p arm6/{urdf,config,launch,worlds}
cd ~/arm_ws && colcon build && source install/setup.bash

You pass when you see this

colcon build finishes without errors; `ros2 pkg prefix arm6` prints the install path.

Stuck?

SymptomMost likely causeWhat to do
`package not found`You forgot to sourceEvery new terminal needs `source ~/arm_ws/install/setup.bash`
03

Write the URDF: six joints plus inertial parameters, none may be skipped

Write only up to 'loadable by gz': base_link fixed, six revolute joints, and every link must have inertial (mass + inertia), otherwise it will drift and clip through things in gz. Approximating inertia with the box formula is enough; errors within 20% do not affect control debugging.

terminal / code
cat > ~/arm_ws/src/arm6/urdf/arm6.urdf.xacro <<'EOF'
<?xml version="1.0"?>
<robot name="arm6" xmlns:xacro="http://ros.org/wiki/xacro">
  <xacro:property name="PI" value="3.14159265358979"/>

  <link name="base_link">
    <visual><geometry><cylinder radius="0.08" length="0.06"/></geometry></visual>
    <collision><geometry><cylinder radius="0.08" length="0.06"/></geometry></collision>
    <inertial><mass value="2.0"/>
      <inertia ixx="0.0060" iyy="0.0060" izz="0.0064" ixy="0" ixz="0" iyz="0"/>
    </inertial>
  </link>

  <!-- link1: vertical segment 0.15 m -->
  <joint name="j1" type="revolute">
    <parent link="base_link"/><child link="link1"/>
    <origin xyz="0 0 0.06" rpy="0 0 0"/>
    <axis xyz="0 0 1"/>
    <limit lower="-3.14" upper="3.14" effort="80" velocity="2.0"/>
    <dynamics damping="1.0" friction="0.5"/>
  </joint>
  <link name="link1">
    <visual><origin xyz="0 0 0.075"/><geometry><cylinder radius="0.05" length="0.15"/></geometry></visual>
    <collision><origin xyz="0 0 0.075"/><geometry><cylinder radius="0.05" length="0.15"/></geometry></collision>
    <inertial><origin xyz="0 0 0.075"/><mass value="1.5"/>
      <inertia ixx="0.0036" iyy="0.0036" izz="0.0019" ixy="0" ixz="0" iyz="0"/>
    </inertial>
  </link>

  <!-- link2: upper arm 0.45 m -->
  <joint name="j2" type="revolute">
    <parent link="link1"/><child link="link2"/>
    <origin xyz="0 0 0.15" rpy="0 0 0"/>
    <axis xyz="0 1 0"/>
    <limit lower="-2.0" upper="2.0" effort="120" velocity="1.8"/>
    <dynamics damping="1.2" friction="0.6"/>
  </joint>
  <link name="link2">
    <visual><origin xyz="0 0 0.225"/><geometry><box size="0.06 0.06 0.45"/></geometry></visual>
    <collision><origin xyz="0 0 0.225"/><geometry><box size="0.06 0.06 0.45"/></geometry></collision>
    <inertial><origin xyz="0 0 0.225"/><mass value="3.0"/>
      <inertia ixx="0.0513" iyy="0.0513" izz="0.0018" ixy="0" ixz="0" iyz="0"/>
    </inertial>
  </link>

  <!-- link3: forearm 0.40 m -->
  <joint name="j3" type="revolute">
    <parent link="link2"/><child link="link3"/>
    <origin xyz="0 0 0.45" rpy="0 0 0"/>
    <axis xyz="0 1 0"/>
    <limit lower="-2.6" upper="2.6" effort="80" velocity="2.2"/>
    <dynamics damping="0.9" friction="0.4"/>
  </joint>
  <link name="link3">
    <visual><origin xyz="0 0 0.20"/><geometry><box size="0.05 0.05 0.40"/></geometry></visual>
    <collision><origin xyz="0 0 0.20"/><geometry><box size="0.05 0.05 0.40"/></geometry></collision>
    <inertial><origin xyz="0 0 0.20"/><mass value="2.0"/>
      <inertia ixx="0.0270" iyy="0.0270" izz="0.00083" ixy="0" ixz="0" iyz="0"/>
    </inertial>
  </link>

  <!-- wrist, three axes: j4 about z, j5 about y, j6 about z -->
  <joint name="j4" type="revolute">
    <parent link="link3"/><child link="link4"/>
    <origin xyz="0 0 0.40" rpy="0 0 0"/><axis xyz="0 0 1"/>
    <limit lower="-3.14" upper="3.14" effort="30" velocity="3.0"/>
  </joint>
  <link name="link4">
    <visual><origin xyz="0 0 0.04"/><geometry><cylinder radius="0.04" length="0.08"/></geometry></visual>
    <collision><origin xyz="0 0 0.04"/><geometry><cylinder radius="0.04" length="0.08"/></geometry></collision>
    <inertial><origin xyz="0 0 0.04"/><mass value="1.2"/>
      <inertia ixx="0.0011" iyy="0.0011" izz="0.0010" ixy="0" ixz="0" iyz="0"/>
    </inertial>
  </link>

  <joint name="j5" type="revolute">
    <parent link="link4"/><child link="link5"/>
    <origin xyz="0 0 0.08" rpy="0 0 0"/><axis xyz="0 1 0"/>
    <limit lower="-2.2" upper="2.2" effort="20" velocity="3.0"/>
  </joint>
  <link name="link5">
    <visual><origin xyz="0 0 0.03"/><geometry><cylinder radius="0.035" length="0.06"/></geometry></visual>
    <collision><origin xyz="0 0 0.03"/><geometry><cylinder radius="0.035" length="0.06"/></geometry></collision>
    <inertial><origin xyz="0 0 0.03"/><mass value="0.8"/>
      <inertia ixx="0.0005" iyy="0.0005" izz="0.0005" ixy="0" ixz="0" iyz="0"/>
    </inertial>
  </link>

  <joint name="j6" type="revolute">
    <parent link="link5"/><child link="tool0"/>
    <origin xyz="0 0 0.06" rpy="0 0 0"/><axis xyz="0 0 1"/>
    <limit lower="-3.14" upper="3.14" effort="10" velocity="3.0"/>
  </joint>
  <link name="tool0">
    <visual><geometry><sphere radius="0.015"/></geometry></visual>
    <collision><geometry><sphere radius="0.015"/></geometry></collision>
    <inertial><mass value="0.3"/>
      <inertia ixx="2.7e-5" iyy="2.7e-5" izz="2.7e-5" ixy="0" ixz="0" iyz="0"/>
    </inertial>
  </link>
</robot>
EOF
xacro ~/arm_ws/src/arm6/urdf/arm6.urdf.xacro > /tmp/arm6.urdf
echo $?

You pass when you see this

The last command prints 0, and /tmp/arm6.urdf contains 7 links and 6 joints.

Stuck?

SymptomMost likely causeWhat to do
xacro reports `Invalid parameter`xacro uses an attribute before it is definedAttributes must be declared at the very top; <xacro:property> before the first reference
The arm slumps and flops over in gzSome link is missing inertialEvery link needs <inertial>; an empty one is treated as zero mass
04

Add ros2_control tags: let the simulation know your joints

Append two blocks at the end of the xacro: one declaring the command/state interface of each joint, and one attaching the gz_ros2_control plugin and pointing to the controller configuration file. A misspelled plugin name is the most common failure point.

terminal / code
cat >> ~/arm_ws/src/arm6/urdf/arm6.urdf.xacro <<'EOF'

  <ros2_control name="arm6_system" type="system">
    <hardware>
      <plugin>gz_ros2_control/GazeboSimSystem</plugin>
    </hardware>
    <xacro:macro name="jif" params="jname">
      <joint name="${jname}">
        <command_interface name="position"/>
        <state_interface name="position"/>
        <state_interface name="velocity"/>
        <state_interface name="effort"/>
      </joint>
    </xacro:macro>
    <xacro:jif jname="j1"/><xacro:jif jname="j2"/><xacro:jif jname="j3"/>
    <xacro:jif jname="j4"/><xacro:jif jname="j5"/><xacro:jif jname="j6"/>
  </ros2_control>

  <gazebo>
    <plugin filename="gz_ros2_control-system"
            name="gz_ros2_control::GazeboSimROS2ControlPlugin">
      <parameters>$(find arm6)/config/controllers.yaml</parameters>
    </plugin>
  </gazebo>

</robot>
EOF

cat > ~/arm_ws/src/arm6/config/controllers.yaml <<'EOF'
controller_manager:
  ros__parameters:
    update_rate: 500
    joint_state_broadcaster:
      type: joint_state_broadcaster/JointStateBroadcaster
    arm_controller:
      type: joint_trajectory_controller/JointTrajectoryController

arm_controller:
  ros__parameters:
    joints: [j1, j2, j3, j4, j5, j6]
    command_interfaces: [position]
    state_interfaces: [position, velocity]
    allow_partial_joints_goal: false
    constraints:
      goal_time: 0.5
EOF

You pass when you see this

Both files exist; the xacro still expands (`xacro ... | wc -l` produces output).

Stuck?

SymptomMost likely causeWhat to do
After launch, `No hardware components found`The class name inside the plugin tag is wrongThe hardware plugin is `gz_ros2_control/GazeboSimSystem`, the system plugin is `gz_ros2_control::GazeboSimROS2ControlPlugin`; the two differ
The controllers load but the joints do not movecommand_interface is velocity while the controller sends positionThe two must match; check the available column of `ros2 control list_hardware_interfaces`
05

Start Gazebo and put the robot inside

Start an empty world first, then use create to turn the URDF into a simulation object. Keep the world empty at first; add props beyond the ground plane only after it runs.

terminal / code
# terminal 1
ros2 run ros_gz_sim gz_sim -- -r -v 3 empty.sdf

# terminal 2 (run after the gz window appears)
ros2 run ros_gz_sim create -file /tmp/arm6.urdf -name arm6 -z 0.02

# terminal 3
ros2 topic list | grep -E 'clock|joint_states'
ros2 topic echo /joint_states --once

You pass when you see this

A standing six-axis arm appears in the gz window; all six joint positions in /joint_states have values (about 0).

Stuck?

SymptomMost likely causeWhat to do
The arm floats in the air or sinks into the groundcreate's -z is missing, or base_link's origin is not at the bottomAdd `-z 0.03`; or raise base_link's geometry origin to z=0.03
No /joint_statesThe gz_ros2_control plugin was not loadedCheck whether the gz terminal printed `Loaded plugin`; if not, the <gazebo> block was dropped from the URDF by xacro
06

Load the controllers: broadcast state first, then control trajectories

The two controllers have an order: joint_state_broadcaster must come up first, otherwise JTC gets no feedback. Bring them up one by one with spawner, and check whether the update period overruns.

terminal / code
ros2 run controller_manager spawner joint_state_broadcaster \
  --controller-manager /controller_manager
ros2 run controller_manager spawner arm_controller \
  --controller-manager /controller_manager

ros2 control list_controllers
ros2 control list_hardware_interfaces

You pass when you see this

Both controllers are `active`; the position/velocity/effort interfaces of all six joints are in the available column.

Stuck?

SymptomMost likely causeWhat to do
`Controller manager not available`The plugin did not come up in the simulationConfirm the gz side printed the controller_manager initialization log; if not, the plugin parameter path is wrong ($(find arm6) was not resolved)
JTC reports `No state interface` at startupThe state_interface names do not match the URDFJTC's state_interfaces must be a subset of what the URDF declares
07

Send the first trajectory: make it really move

No code; send a 3-second trajectory directly via an action. If this step passes, the 'plan — control — execute' channel works; MoveIt afterwards is just a different upstream.

terminal / code
ros2 action send_goal /arm_controller/follow_joint_trajectory \
  control_msgs/action/FollowJointTrajectory "{
    trajectory: {
      joint_names: [j1,j2,j3,j4,j5,j6],
      points: [
        {positions: [0.0, -0.4, 0.8, 0.0, 0.6, 0.0], time_from_start: {sec: 3}}
      ]
    }
  }" --feedback

You pass when you see this

The arm moves smoothly to the target pose within 3 seconds, the action returns SUCCEEDED, and there is no overshoot or jitter.

Stuck?

SymptomMost likely causeWhat to do
The motion arrives but stutters along the wayupdate_rate is 500 but gz's physics step / RTF cannot keep upWatch the RTF in the gz terminal; below 0.9, delete unrelated models from the world or run headless with `-s`
Returns INVALID_GOALThe number of positions in a trajectory point does not match the number of joints6 joints require exactly 6 numbers; one missing rejects the whole goal
08

MoveIt Setup Assistant: generate the config, do not hand-write it

This step does only four things: load the URDF, generate the self-collision matrix, build the planning group (the chain from base_link to tool0), and pick the IK plugin. Everything else stays default; get it running before optimizing.

terminal / code
ros2 launch moveit_setup_assistant setup_assistant.launch.py

You pass when you see this

All four steps turn green in the UI, and it finally generates ~/arm_ws/src/arm6_moveit_config containing the SRDF and launch files.

Stuck?

SymptomMost likely causeWhat to do
The self-collision matrix generates 0 samplesLink names in the URDF do not match, or the model has no inertiaFirst confirm `check_urdf /tmp/arm6.urdf` passes
tool0 cannot be foundThe planning group's tip was not chosen as the last link of the chainChoose Kinematic Chain as the group type, base_link as base, tool0 as tip
09

Plan and execute in RViz

Start move_group, RViz and the gz simulation from before at the same time. Drag the end effector to a target in RViz and click Plan & Execute — with a correct configuration, the arm in gz moves along.

terminal / code
ros2 launch arm6_moveit_config demo.launch.py \
  use_sim_time:=true
# if demo.launch ships fake controllers, open another terminal and swap them for gz's arm_controller
ros2 control list_controllers

You pass when you see this

RViz plans a colored trajectory; after Execute the arm in gz moves in sync and the end effector reaches the target pose.

Stuck?

SymptomMost likely causeWhat to do
Planning succeeds but nothing moves in gzMoveIt is connected to the fake controllers instead of arm_controllerRename moveit's controller to arm_controller, or turn off the fake-execution launch parameter
Planning always fails (0 solutions)The KDL IK plugin has no solution at that poseInstall `ros-jazzy-trac-ik-kinematics-plugin`, switch to TRAC-IK in the SRDF, and try again
Execution times out halfwaygoal_time is too tight or the actuators cannot keep upRelax JTC's constraints.goal_time, and check the trajectory's velocity limits
10

Add a camera and obstacles: this is where 'engineering' begins

Planning in an empty scene does not count. Add a box and a depth camera so MoveIt's planning scene has real obstacles, then plan again.

terminal / code
# add a box in the world (or generate one temporarily with gz service)
ros2 run ros_gz_sim create -world empty \
  -name box -x 0.5 -y 0.2 -z 0.15 \
  -geometry 'box' -size 0.2,0.2,0.3 -static

# add a depth camera in the URDF (gz-sensors plugin)
# then bridge the point cloud into ROS 2
ros2 run ros_gz_bridge parameter_bridge \
  /depth/points@sensor_msgs/msg/PointCloud2[gz.msgs.PointCloudPacked

You pass when you see this

The box and the point cloud are visible in RViz, and the end effector reaches the target around the box; remove the box and it can go straight.

Stuck?

SymptomMost likely causeWhat to do
The point cloud is misaligned in RVizThe camera link's tf is not publishedAdd robot_state_publisher, or add a static_transform_publisher
MoveIt cannot see the boxThe planning scene has no octomap hookup or collision object addedFirst add a CollisionObject manually to verify the chain, then connect the point cloud
11

Acceptance check: no UI, just these four commands

Close RViz and reproduce it from the command line. Only when you can judge the system state without a UI have you really learned it.

terminal / code
ros2 control list_controllers                 # both active
ros2 topic hz /joint_states                   # close to 500 Hz
ros2 topic echo /controller_manager/... 2>/dev/null | head -3   # no overrun
ros2 service call /compute_ik moveit_msgs/srv/GetPositionIK \
  '{ik_request: {group_name: arm, ik_link_name: tool0}}'

You pass when you see this

All four run through, and you can explain why overrun is 0 — because read()/write() contains no allocation, no printing, no waiting.

Stuck?

SymptomMost likely causeWhat to do
joint_states is only around 100 Hzgz's physics step or update_rate does not match expectationsupdate_rate is the controller frequency; gz's max_step_size sets the ceiling; the two must match

Acceptance checklist

Without looking at notes or chat history, complete each item below on your own — only then is the tutorial really done.

Keep learning

G1 Gazebo and simulation engineeringG2 MoveIt 2Next: train a grasping policy

Other tutorials

From zero to your first Python script: terminal lesson one

For anyone who has never installed an environment or opened a terminal, this is the first step up. No Linux, no GPU, nothing to buy throughout — just an ordinary laptop.

1–2 h

Train a grasping policy from scratch: MuJoCo + SAC + HER

First get the arm to reach the target, then learn to pick it up. Training runs with a single command, about 5 hours

5–6 h

Isaac Lab parallel training: 4096 environments at once

From environment setup to exporting a deployable policy, about 4 hours (excluding training time)

4 h + training