16. ROS2-URDF Modeling Simulation
16.1 Virtual Machine Installation and Import
16.1.1 Virtual Machine Software Installation
VMware Installation
A virtual machine allows us to run other operating systems within our current operating system. In this section, we will demonstrate the installation process using VMware Workstation as an example:
(1) Unzip the virtual machine software package located under the “Configuration File -> VMware” path.
(2) After unzipping, locate the virtual machine folder and double-click the executable file (with the “.exe” extension).
(3) Follow the on-screen instructions to complete the installation of the virtual machine.
(4) VMware Workstation offers 30-day free trial. After 30-day trial, you can purchase a license key to activate this software. If you need free resource, please contact us via email.
Starting Local VMware Services
(1) On your computer, press the WIN+R keys to open the Run window. Then, type control and press Enter to open the Control Panel.
(2) Click on Administrative Tools and then double-click on Services.
(3) Locate the VMware-related services as shown in the image below.
(4) Right-click on the Start button and select it to start all VMware-related services.
VirtualBox Installation
(1) Open the software installation package in the same directory and click Next.
(2) Modify the installation path if needed, then click Next.
(3) No changes needed, just click Next.
(4) Confirm the installation and click Start Installation.
(5) Once the installation is complete, click Finish.
16.1.2 Virtual System Image Import
(1) In the software interface, click on Open Virtual Machine.
(2) Locate the required virtual machine file in the same directory, and open it.
(3) Select a storage path and click Import. Wait for the import to complete.
(4) Once the import is finished, you can start using the virtual machine.
16.1.3 Virtual Machine Settings
(1) Locate the virtual machine you just imported and click Edit Virtual Machine Settings.
(2) Click on Network Adapter and select Bridged Mode.
(3) Click on Display and uncheck the Accelerate 3D Graphics option.
Enabling the “Accelerate 3D Graphics” option can negatively affect virtual machine performance and may cause lag during simulation.
16.2 Configuration
It is normal for the virtual machine to take a longer time to start for the first time.
The virtual machine interface is as below:
16.2.1 Package Import (Performed on Virtual Machine)
(1) Start the virtual machine. Click the system desktop icon 
to open the command-line terminal.
(2) Click the Home icon 
on the desktop to enter the Home directory.
(3) Locate the Simulations compressed file in the same directory. Drag the compressed file into the Home directory of the virtual machine.
Only drag one file at a time.
(4) Right-click in the Home directory and select Open in terminal to open the terminal.
(5) Enter the following command to create a directory:
mkdir -p ~/ros2_ws/src
(6) Execute the following commands to extract the source files and enter the source directory:
unzip ~/simulations.zip
mv ~/simulations ~/ros2_ws/src/simulations
If prompted to replace files, type A and press Enter.
(7) Run the following command to compile the packages and wait for the process to finish:
cd ~/ros2_ws && colcon build --symlink-install
(8) Run the following command to replace the .typerc file:
mv /home/ubuntu/.typerc ~/ros2_ws/.typerc
(9) Check if the file move was successful by running:
cd ~/ros2_ws/ && ls -a
(10) Enter the command to set up automatic loading of the configuration file:
echo "source ~/ros2_ws/install/setup.bash">~/.bashrc
echo "source ~/ros2_ws/.typerc">~/.bashrc
(11) To update the settings, reload the configuration file using:
source ~/.bashrc
16.2.2 Network Configuration (Performed in Robot System Desktop)
To ensure proper communication between the virtual machine and the robot during future operations, we need to configure the device’s network settings.
(1) Start the robot and open a terminal 
on the desktop.
(2) Enter the following command to configure the WiFi file:
cd ~/wifi_manager && gedit wifi_conf.py
(3) Modify the configuration to LAN mode and enter the WiFi name and password
(4) Press Ctrl+S to save and close the file.
(5) For subsequent connections, ensure that the device and virtual machine are on the same network segment. You can check this by running the following command in the terminal:
ifconfig
In this example, both the virtual machine and the robot are on the 192.168.11 network segment, allowing for normal communication.
Common connection methods:
(1) Via Router (Recommended): Connect the computer and Jetson board to the same router using an Ethernet cable.
(2) Via Local Area Network (LAN) (Recommended): Configure the STA (station) mode on the WiFi, then connect both the robot and computer to the same WiFi network (or mobile hotspot).
(3) Direct Connection (Not Recommended): Set the robot to AP (Access Point) mode, then connect the computer directly to the robot’s WiFi.
16.2.3 Device ID Configuration (To Be Performed on the Virtual Machine)
In the previous section, we configured the network environment. However, for the virtual machine and the robot to communicate on the same network, they must have matching ID numbers. Below are the steps to configure the ID:
(1) Start the robot and open a terminal from the desktop.
(2) The terminal will display the device’s DOMAIN_ID, as shown below:
For example, if the DOMAIN_ID is 23, we will configure the virtual machine accordingly.
(3) Start the virtual machine and open a terminal from the desktop.
(4) Enter the following command to open the configuration file:
gedit ~/ros2_ws/.typerc
(5) Change the ID to 23 as shown in the image below. Then, select the appropriate configuration based on your camera version and comment out the other option.
(GEMINI: Depth Camera; USB_CAM: Monocular Camera)
(6) Press Ctrl+S to save the changes and close the file.
(7) Close the current terminal, then open a new terminal. You will observe that the ID has been successfully updated to 23.
16.3 URDF Model
This tutorial is based on configuration and simulation within a virtual machine. If the virtual machine is not yet installed, please first refer to Section 16.1 Virtual Machine Installation and Configuration to complete the installation.
16.3.1 URDF Model Introduction
The Unified Robot Description Format (URDF) is an XML file format widely used in ROS (Robot Operating System) to comprehensively describe all components of a robot.
Robots are typically composed of multiple links and joints. A link is defined as a rigid object with certain physical properties, while a joint connects two links and constrains their relative motion.
By connecting links with joints and imposing motion restrictions, a kinematic model is formed. The URDF file specifies the relationships between joints and links, their inertial properties, geometric characteristics, and collision models.
16.3.2 Comparison between Xacro and URDF Model
The URDF model serves as a description file for simple robot models, offering a clear and easily understandable structure. However, when it comes to describing complex robot structures, using URDF alone can result in lengthy and unclear descriptions.
To address this limitation, the xacro model extends the capabilities of URDF while maintaining its core features. The xacro format provides a more advanced approach to describe robot structures. It greatly improves code reusability and helps avoid excessive description length.
For instance, when describing the two legs of a humanoid robot, the URDF model would require separate descriptions for each leg. On the other hand, the xacro model allows for describing a single leg and reusing that description for the other leg, resulting in a more concise and efficient representation.
16.3.3 Install URDF Dependency
The URDF and Xacro models are already pre-installed in the virtual machine, so there is no need for users to reinstall them. This section is for informational purposes only.
(1) Run the following command and press Enter to update the package information:
sudo apt update
(2) Run the following command and press Enter to install the URDF dependencies:
sudo apt-get install ros-humble-urdf
When the output matches the image below, the installation is successful:
(3) Run the following command and press Enter to install the Xacro model extension for URDF:
sudo apt-get install ros-humble-xacro
When the output matches the image below, the installation is successful:
16.3.4 URDF Model Basic Syntax
XML Basic Syntax
The URDF model is written using XML standard.
Elements:
An element can be defined as desired using the following formula:
<element>
</element>
Properties:
Properties are included within elements to define characteristics and parameters. Please refer to the following formula to define an element with properties:
<element
property_1="property value1"
property_2="property value2">
</element>
Comments:
Comments have no impact on the definition of other properties and elements. Please use the following formula to define a comment:
Link
The Link element describes the visual and physical properties of the robot’s rigid component. The following tags are commonly used to define the motion of a link:
<visual>: Describe the appearance of the link, such as size, color and shape.
<inertial>: Describe the inertia parameters of the link, which will used in dynamics calculation.
<collision>: Describe the collision inertia property of the link
Each tag contains the corresponding child tag. The functions of the tags are listed below.
| Tag | Function |
|---|---|
| origin | Describe the pose of the link. It contains two parameters, including xyz and rpy. Xyz describes the pose of the link in the simulated map. Rpy describes the pose of the link in the simulated map. |
| mess | Describe the mess of the link |
| inertia | Describe the inertia of the link. As the inertia matrix is symmetrical, these six parameters need to be input, ixx, ixy, ixz, iyy, iyz and izz, as properties. These parameters can be calculated. |
| geometry | Describe the shape of the link. It uses mesh parameter to load texture file, and em[ploys filename parameters to load the path for texture file. It has three child tags, namely box, cylinder and sphere. |
| material | Describe the material of the link. The parameter name is the required filed. The tag color can be used to change the color and transparency of the link. |
Joint
The Joint tag describes the kinematic and dynamic properties of the robot’s joints, including the joint’s range of motion, target positions, and speed limitations. In terms of motion style, joints can be categorized into six types.
The following tags will be used to write joint motion.
<parent_link>: Parent link
<child_link>: Child link
<calibration>: Calibrate the joint angle
<dynamics>: Describes some physical properties of motion
<limit>: Describes some limitations of the motion
The function of each tag is listed below. Each tag involves one or several child tags.
| Tag | Function |
|---|---|
| origin | Describe the pose of the parent link. It involves two parameters, including xyz and rpy. Both xyz and rpy describe the pose of the link in simulated map. |
| axis | Control the child link to rotate around any axis of the parent link. |
| limit | The motion of the child link is constrained using the lower and upper properties, which define the limits of rotation for the child link. The effort properties restrict the allowable force range applied during rotation (values: positive and negative; units: N). The velocity properties confine the rotational speed, measured in meters per second (m/s). |
| mimic | Describe the relationship between joints. |
| safety_controller | Describes the parameters of the safety controller used for protecting the joint motion of the robot. |
Robot Tag
The complete top tags of a robot, including the <link> and <joint> tags, must be enclosed within the <robot> tag. The format is as follows:
<robot name="name of robot">
<link>......</link>
<link>......</link>
<joint>......</joint>
<joint>......</joint>
</robot>
gazebo Tag
This tag is used in conjunction with the Gazebo simulator. Within this tag, you can define simulation parameters and import Gazebo plugins, as well as specify Gazebo’s physical properties, and more.
<gazebo refernce="link1">
<material>Gazebo/Black</material>
</gazebo>
Write Simple URDF Model
(1) Name the model of the robot
To start writing the URDF model, we need to set the name of the robot following this format: <robot name="robot model name">. Lastly, input </robot> at the end to represent that the model is written successfully.
<?xml version="1.0"?>
<robot name="pan_tilt">
</robot>
(2) Set links
① To write the first link and use indentation to indicate that it is part of the currently set model. Set the name of the link using the following format: <link name="link name">. Finally, conclude with </link> to indicate the successful completion of the link definition.
<link name="base_link">
</link>
② Write the link description and use indentation to indicate that it is part of the currently set link, and conclude with </visual>.
<visual>
</visual>
③ The <geometry> tag is employed to define the shape of a link. Once the description is complete, include </geometry>. Within the <geometry> tag, indentation is used to specify the detailed description of the link’s shape. The following example demonstrates a link with a cylindrical shape: <cylinder length="0.01" radius="0.2"/>. In this instance, length="0.01" signifies a length of 0.01 meters for the link, while radius="0.2" denotes a radius of 0.2 meters, resulting in a cylindrical shape.
<geometry>
<cylinder length="0.01" radius="0.2"/>
</geometry>
④ The <origin> tag is utilized to specify the position of a link, with indentation used to indicate the detailed description of the link’s position. The following example demonstrates the position of a link: <origin rpy="0 0 0" xyz="0 0 0" />. In this example, rpy represents the roll, pitch, and yaw angles of the link, while xyz represents the coordinates of the link’s position. This particular example indicates that the link is positioned at the origin of the coordinate system.
<origin rpy="0 0 0" xyz="0 0 0" />
⑤ The <material> tag is used to define the visual appearance of a link, with indentation used to specify the detailed description of the link’s color. To start describing the color, include <material>, and end with </material> when the description is complete. The following example demonstrates setting a link color to yellow: <color rgba="1 1 0 1" />. In this example, rgba="1 1 0 1" represents the color threshold for achieving a yellow color.
<material name="yellow">
<color rgba="1 1 0 1" />
</material>
(3) Set joint
① To write the first joint, use indentation to indicate that the joint belongs to the current model being set. Then, specify the name and type of the joint as follows: <joint name="joint name" type="joint type">. Finally, include </joint> to indicate the completion of the joint definition.
To learn about the type of the joint, please refer to joint
<joint name="pan_joint" type="revolute">
</joint>
② Write the description section for the connection between the link and the joint. Use indentation to indicate that it is part of the currently defined joint. The parent parameter and child parameter should be set using the following format: <parent link="parent link"/>, and <child link="child link" />. With the parent link serving as the pivot, the joint rotates the child link.
<parent link="base link" />
<child link="pan_link" />
③ <origin> describes the position of the joint using indention. This example describes the position of the joint: <origin xyz="0 0 0.1" />. xyz is the coordinate of the joint.
<origin xyz="0 0 0 1" />
④ <axis> describes the position of the joint adopting indention. <axis xyz="0 0 1" /> describes one posture of a joint. xyz specifies the pose of the joint.
<axis xyz="0 0 1" />
⑤ <limit> imposes restrictions on the joint using indention. The below picture The <limit> tag is used to restrict the motion of a joint, with indentation indicating the specific description of the joint angle limitations. The following example describes a joint with a maximum force limit of 300 Newtons, an upper limit of 3.14 radians, and a lower limit of -3.14 radians. The settings are defined as follows: effort="joint force (N)", velocity="joint motion speed", lower="lower limit in radians", upper="upper limit in radians".
<limit effort="300" velocity="0.1" lower="-3.14" upper="3.14" />
⑥ <dynamics> describes the dynamics of the joint using indention. <dynamics damping="50" friction="1" /> describes dynamics parameters of a joint.
<dynamics damping="50" friction="1" />
The complete codes are as below.
<?xml version="1.0" encoding="utf-8"?>
<robot name="arm" xmlns:xacro="http://ros.org/wiki/xacro">
<xacro:property name="M_PI" value="3.1415926535897931"/>
<link
name="link1">
<inertial>
<origin
xyz="9.55287669839149E-05 0.000953445773182543 0.0181622223429797"
rpy="0 0 0" />
<mass
value="0.018996290781889" />
<inertia
ixx="3.52401713486466E-06"
ixy="-9.57766622211234E-11"
ixz="1.77834467690429E-11"
iyy="2.92480468671507E-06"
iyz="2.27263787135776E-08"
izz="2.43231516201483E-06" />
</inertial>
<visual>
<origin xyz="0.0 0.0 0.0535" rpy="0.0 0.0 0.0"/>
<geometry>
<mesh filename="file://$(find jetarm_6dof_description)/meshes/jetarm_6dof/JetArm_6DOF_LINK1_GREEN.STL" scale="0.001 0.001 0.001"/>
</geometry>
<material name="jetarm_green">
<color rgba="${jetarm_green}"/>
</material>
</visual>
<visual>
<origin
xyz="0 0 0.053"
rpy="0 0 0" />
<geometry>
<mesh
filename="file://$(find jetarm_6dof_description)/meshes/jetarm_6dof/JetArm_6DOF_LINK1_BLACK.STL" scale="0.001 0.001 0.001"/>
</geometry>
<material name="jetarm_black">
<color rgba="${jetarm_black}"/>
</material>
</visual>
<collision>
<origin
xyz="0 0 0"
rpy="0 0 0" />
<geometry>
<mesh
filename="file://$(find jetarm_6dof_description)/meshes/jetarm_6dof/JetArm_6DOF_LINK1.STL" />
</geometry>
</collision>
</link>
<link
name="link2">
<inertial>
<origin
xyz="0.000156299570425157 -0.000455113699913916 0.0717727028511975"
rpy="0 0 0" />
<mass
value="0.0329250074531705" />
<inertia
ixx="3.91620966174037E-05"
ixy="-5.45461883923424E-11"
ixz="-1.84994427464167E-07"
iyy="3.08453562297899E-05"
iyz="3.5881427402197E-09"
izz="1.15081900975983E-05" />
</inertial>
<visual>
<origin
xyz="0 0 0"
rpy="0 0 0" />
<geometry>
<mesh
filename="file://$(find jetarm_6dof_description)/meshes/jetarm_6dof/link2.STL" />
</geometry>
<material name="jetarm_green">
<color rgba="${jetarm_green}"/>
</material>
</visual>
<collision>
<origin
xyz="0 0 0"
rpy="0 0 0" />
<geometry>
<mesh
filename="file://$(find jetarm_6dof_description)/meshes/jetarm_6dof/link2_collision.stl" />
</geometry>
</collision>
</link>
<joint
name="joint2"
type="revolute">
<origin
xyz="0 0 0.054048012164686"
rpy="0 0 0" />
<parent
link="link1" />
<child
link="link2" />
<axis
xyz="0 -1 0" />
<limit
lower="-2.09"
upper="2.09"
effort="1000"
velocity="10" />
</joint>
<link
name="link3">
<inertial>
<origin
xyz="0.000128456440925698 -0.000761424622733717 0.071772743785429"
rpy="0 0 0" />
<mass
value="0.0329250074463074" />
<inertia
ixx="3.91621699579612E-05"
ixy="-5.40097530558062E-11"
ixz="-1.73786652512013E-07"
iyy="3.08451969920239E-05"
iyz="3.63874236522223E-09"
izz="1.15078234912494E-05" />
</inertial>
<visual>
<origin
xyz="0 0 0"
rpy="0 0 0" />
<geometry>
<mesh
filename="file://$(find jetarm_6dof_description)/meshes/jetarm_6dof/link3.STL" />
</geometry>
<material name="jetarm_green">
<color rgba="${jetarm_green}"/>
</material>
</visual>
<collision>
<origin
xyz="0 0 0"
rpy="0 0 0" />
<geometry>
<mesh
filename="file://$(find jetarm_6dof_description)/meshes/jetarm_6dof/link3_collision.stl" />
</geometry>
</collision>
</link>
<joint
name="joint3"
type="revolute">
<origin
xyz="0 0 0.134416446394797"
rpy="0 0 0" />
<parent
link="link2" />
<child
link="link3" />
<axis
xyz="0 -1 0" />
<limit
lower="-2.09"
upper="2.09"
effort="1000"
velocity="10" />
</joint>
<link
name="link4">
<inertial>
<origin
xyz="-0.000261855576526311 0.000239368359066633 0.0220971301535388"
rpy="0 0 0" />
<mass
value="0.00959141779390409" />
<inertia
ixx="7.94977139591732E-06"
ixy="-8.29446018776969E-10"
ixz="5.6880898756802E-08"
iyy="4.29063067361656E-06"
iyz="-1.84622131688891E-10"
izz="5.33833388813501E-06" />
</inertial>
<visual>
<origin
xyz="0 0 0"
rpy="0 0 0" />
<geometry>
<mesh
filename="file://$(find jetarm_6dof_description)/meshes/jetarm_6dof/link4.STL" />
</geometry>
<material name="jetarm_green">
<color rgba="${jetarm_green}"/>
</material>
</visual>
<collision>
<origin
xyz="0 0 0"
rpy="0 0 0" />
<geometry>
<mesh
filename="file://$(find jetarm_6dof_description)/meshes/jetarm_6dof/link4_collision.stl" />
</geometry>
</collision>
</link>
<joint
name="joint4"
type="revolute">
<origin
xyz="0 0 0.134444631186569"
rpy="0 0 0" />
<parent
link="link3" />
<child
link="link4" />
<axis
xyz="0 -1 0" />
<limit
lower="-2.09"
upper="2.09"
effort="1000"
velocity="10" />
</joint>
<link
name="servo_link2">
<inertial>
<origin
xyz="0.00829457691057159 0.000114732113040695 -0.0125525321145837"
rpy="0 0 0" />
<mass
value="0.00701021225113507" />
<inertia
ixx="6.10646998888003E-07"
ixy="1.66839713815154E-09"
ixz="-2.07626862362467E-08"
iyy="9.477990166652E-07"
iyz="5.12927100881908E-09"
izz="1.44691449724265E-06" />
</inertial>
<visual>
<origin
xyz="0 0 0"
rpy="0 0 0" />
<geometry>
<mesh
filename="file://$(find jetarm_6dof_description)/meshes/jetarm_6dof/servo_link2.STL" />
</geometry>
<material name="jetarm_black">
<color rgba="${jetarm_black}"/>
</material>
</visual>
<collision>
<origin
xyz="0 0 0"
rpy="0 0 0" />
<geometry>
<mesh
filename="file://$(find jetarm_6dof_description)/meshes/jetarm_6dof/servo_link2_collision.stl" />
</geometry>
</collision>
</link>
<joint
name="servo_joint2"
type="fixed">
<origin
xyz="0 0 0.0544833339503674"
rpy="0 0 0" />
<parent
link="link4" />
<child
link="servo_link2" />
<axis
xyz="0 0 0" />
</joint>
<link
name="link5">
<inertial>
<origin
xyz="-5.40141895711381E-05 -8.30141354428709E-06 0.00351551092860852"
rpy="0 0 0" />
<mass
value="0.00101775298619909" />
<inertia
ixx="2.35834256739382E-08"
ixy="-1.92177809145012E-12"
ixz="-3.88572739181837E-12"
iyy="2.35740360938003E-08"
iyz="-1.1228386368903E-13"
izz="4.40224050991292E-08" />
</inertial>
<visual>
<origin
xyz="0 0 0"
rpy="0 0 0" />
<geometry>
<mesh
filename="file://$(find jetarm_6dof_description)/meshes/jetarm_6dof/link5.STL" />
</geometry>
<material name="jetarm_black">
<color rgba="${jetarm_black}"/>
</material>
</visual>
<collision>
<origin
xyz="0 0 0"
rpy="0 0 0" />
<geometry>
<mesh
filename="file://$(find jetarm_6dof_description)/meshes/jetarm_6dof/link5.STL" />
</geometry>
</collision>
</link>
<joint
name="joint5"
type="revolute">
<origin
xyz="0 0 0"
rpy="0 0 0" />
<parent
link="servo_link2" />
<child
link="link5" />
<axis
xyz="0 0 -1" />
<limit
lower="-2.09"
upper="2.09"
effort="1000"
velocity="10" />
</joint>
<link
name="gripper_servo_link">
<inertial>
<origin
xyz="0.0145481835889059 -0.00315257290321308 0.0253492053712461"
rpy="0 0 0" />
<mass
value="0.0174988490314194" />
<inertia
ixx="4.12615692688456E-06"
ixy="-2.75102939068049E-08"
ixz="-7.61180742281118E-09"
iyy="1.57023365316943E-06"
iyz="2.2563082379695E-08"
izz="3.2612101868791E-06" />
</inertial>
<visual>
<origin
xyz="0 0 0"
rpy="0 0 0" />
<geometry>
<mesh
filename="file://$(find jetarm_6dof_description)/meshes/jetarm_6dof/gripper_link.STL" />
</geometry>
<material name="jetarm_black">
<color rgba="${jetarm_black}"/>
</material>
</visual>
<collision>
<origin
xyz="0 0 0"
rpy="0 0 0" />
<geometry>
<mesh
filename="file://$(find jetarm_6dof_description)/meshes/jetarm_6dof/gripper_link_collision.stl" />
</geometry>
</collision>
</link>
<joint
name="gripper_servo_joint"
type="fixed">
<origin
xyz="0 0 0.0054388"
rpy="0 0 0" />
<parent
link="link5" />
<child
link="gripper_servo_link" />
<axis
xyz="0 0 0" />
</joint>
<!-- end effector link -->
<link name="end_effector_link" />
<joint name="end_effector_joint" type="fixed">
<origin xyz="0 0 0.08" rpy="0 0 0"/>
<parent link="link5"/>
<child link="end_effector_link"/>
</joint>
</robot>
16.4 ROS Robot URDF Model Instructions
16.4.1 Preparation
To understand the URDF model, you can refer to the “16.3.4 URDF Model Basic Syntax”. This section provides a brief analysis of the robot model code and component models.
16.4.2 Viewing the Robot Model Code
(1) Start the virtual machine and click the icon 
to open the command-line terminal.
(2) Enter the following command and press Enter to navigate to the startup program directory:
cd ros2_ws/src/simulations/jetarm_6dof_description/urdf/
(3) Enter the following command to open the robot simulation model file:
vim jetarm_6dof_robot.urdf.xacro
(4) Find the code section shown in the image below:
<?xml version="1.0" encoding="utf-8"?>
<robot xmlns:xacro="http://www.ros.org/wiki/xacro" name="jetarm_6dof">
<xacro:arg name="prefix" default=""/>
<xacro:arg name="camera_type" default="GEMINI"/>
<xacro:property name="camera_type" value="$(env CAMERA_TYPE)"/>
<!-- Import jetarm macro -->
<xacro:include filename="$(find jetarm_6dof_description)/urdf/jetarm_6dof_description.urdf.xacro"/>
<xacro:include filename="$(find jetarm_6dof_description)/urdf/arm.urdf.xacro"/>
<xacro:include filename="$(find jetarm_6dof_description)/urdf/connect.urdf.xacro"/>
<xacro:include filename="$(find jetarm_6dof_description)/urdf/gripper.urdf.xacro"/>
<xacro:if value="${camera_type == 'GEMINI'}">
<xacro:include filename="$(find jetarm_6dof_description)/urdf/depth_camera.urdf.xacro"/>
</xacro:if>
<xacro:if value="${camera_type == 'USB_CAM'}">
<xacro:include filename="$(find jetarm_6dof_description)/urdf/usb_cam.urdf.xacro"/>
</xacro:if>
<!-- Import Rviz colors -->
<xacro:include filename="$(find jetarm_6dof_description)/urdf/materials.xacro"/>
<!-- Import jetarm ros_control description -->
<xacro:include filename="$(find jetarm_6dof_description)/gazebo/jetarm.gazebo.xacro" />
<xacro:include filename="$(find jetarm_6dof_description)/gazebo/jetarm.transmission.xacro" />
<!-- Used for fixing robot -->
<link name="$(arg prefix)world"/>
<gazebo reference="$(arg prefix)world">
<static>true</static>
</gazebo>
<xacro:jetarm_6dof parent="$(arg prefix)world" prefix="$(arg prefix)" camera_type="$(arg camera_type)">
<origin xyz="0 0 0" rpy="0 0 0"/>
</xacro:jetarm_6dof>
<xacro:jetarm_gazebo prefix="$(arg prefix)"></xacro:jetarm_gazebo>
<xacro:jetarm_gazeboo_transmission prefix="$(arg prefix)"></xacro:jetarm_gazeboo_transmission>
<!-- <xacro:jetarm_ros2_control name="jetarm" prefix="$(arg prefix)" /> -->
</robot>
Multiple URDF models are called to form the complete robot.
| File Name | Device |
|---|---|
| materials | Color |
| arm | Robot arm |
| gripper | Gripper |
| jetarm_6dof_description | Base |
| usb_cam | Monocular camera |
| depth_camera | Depth camera |
16.4.3 Brief Analysis of the Robot’s Main Model
Open a new command line, and enter the command to load the robot model file, which contains descriptions of the various components of the robot model.
vim arm.urdf.xacro
<?xml version="1.0" encoding="utf-8"?>
<robot name="arm" xmlns:xacro="<http://ros.org/wiki/xacro>">
This is the beginning of the URDF file. It specifies the XML version and encoding, and defines a robot model named “arm”. The xmlns:xacro namespace is used here to enable the use of Xacro macros for generating the URDF.
This line of code defines a Xacro property named “M_PI” and sets its value to the mathematical constant π (pi).
<xacro:property name="M_PI" value="3.1415926535897931"/>
A link named “link1” is defined here.
<link name="link1"/>
This section describes some features of the robot, such as its mass, inertia matrix, appearance, and shape.
<link name="link1">
<inertial>
<origin xyz="..." rpy="..." />
<mass value="..." />
<inertia ixx="..." iyy="..." izz="..." ... />
</inertial>
<visual>
<geometry>
<mesh filename="..." scale="0.001 0.001 0.001" />
</geometry>
<material name="jetarm_green">
<color rgba="\${jetarm_green}" />
</material>
</visual>
<collision>
<geometry>
<mesh filename="..." />
</geometry>
</collision>
</link>
First, the following code defines a joint named “joint2” with the type “revolute”, indicating that this is a rotational joint. This joint connects a parent link named “link1” and a child link named “link2”.
<joint name="joint2" type="revolute">
<origin xyz="..." rpy="..." />
<parent link="link1" />
<child link="link2" />
<axis xyz="0 -1 0" />
<limit lower="-2.09" upper="2.09" effort="1000" velocity="10" />
</joint>
The joint’s position (origin) is specified using the xyz attribute.
Next, the code continues to define multiple links and joints in the same manner:
<link
name="link2">
<inertial>
<origin
xyz="0.000156299570425157 -0.000455113699913916 0.0717727028511975"
rpy="0 0 0" />
<mass
value="0.0329250074531705" />
<inertia
ixx="3.91620966174037E-05"
ixy="-5.45461883923424E-11"
ixz="-1.84994427464167E-07"
iyy="3.08453562297899E-05"
iyz="3.5881427402197E-09"
izz="1.15081900975983E-05" />
</inertial>
<visual>
<origin
xyz="0 0 0"
rpy="0 0 0" />
<geometry>
<mesh
filename="file://$(find jetarm_6dof_description)/meshes/jetarm_6dof/link2.STL" />
</geometry>
<material name="jetarm_green">
<color rgba="${jetarm_green}"/>
</material>
</visual>
<collision>
<origin
xyz="0 0 0"
rpy="0 0 0" />
<geometry>
<mesh
filename="file://$(find jetarm_6dof_description)/meshes/jetarm_6dof/link2_collision.stl" />
</geometry>
</collision>
</link>
<joint
name="joint2"
type="revolute">
<origin
xyz="0 0 0.054048012164686"
rpy="0 0 0" />
<parent
link="link1" />
<child
link="link2" />
<axis
xyz="0 -1 0" />
<limit
lower="-2.09"
upper="2.09"
effort="1000"
velocity="10" />
</joint>
<link
name="link3">
<inertial>
<origin
xyz="0.000128456440925698 -0.000761424622733717 0.071772743785429"
rpy="0 0 0" />
<mass
value="0.0329250074463074" />
<inertia
ixx="3.91621699579612E-05"
ixy="-5.40097530558062E-11"
ixz="-1.73786652512013E-07"
iyy="3.08451969920239E-05"
iyz="3.63874236522223E-09"
izz="1.15078234912494E-05" />
</inertial>
<visual>
<origin
xyz="0 0 0"
rpy="0 0 0" />
<geometry>
<mesh
filename="file://$(find jetarm_6dof_description)/meshes/jetarm_6dof/link3.STL" />
</geometry>
<material name="jetarm_green">
<color rgba="${jetarm_green}"/>
</material>
</visual>
<collision>
<origin
xyz="0 0 0"
rpy="0 0 0" />
<geometry>
<mesh
filename="file://$(find jetarm_6dof_description)/meshes/jetarm_6dof/link3_collision.stl" />
</geometry>
</collision>
</link>
<joint
name="joint3"
type="revolute">
<origin
xyz="0 0 0.134416446394797"
rpy="0 0 0" />
<parent
link="link2" />
<child
link="link3" />
<axis
xyz="0 -1 0" />
<limit
lower="-2.09"
upper="2.09"
effort="1000"
velocity="10" />
</joint>
<link
name="link4">
<inertial>
<origin
xyz="-0.000261855576526311 0.000239368359066633 0.0220971301535388"
rpy="0 0 0" />
<mass
value="0.00959141779390409" />
<inertia
ixx="7.94977139591732E-06"
ixy="-8.29446018776969E-10"
ixz="5.6880898756802E-08"
iyy="4.29063067361656E-06"
iyz="-1.84622131688891E-10"
izz="5.33833388813501E-06" />
</inertial>
<visual>
<origin
xyz="0 0 0"
rpy="0 0 0" />
<geometry>
<mesh
filename="file://$(find jetarm_6dof_description)/meshes/jetarm_6dof/link4.STL" />
</geometry>
<material name="jetarm_green">
<color rgba="${jetarm_green}"/>
</material>
</visual>
<collision>
<origin
xyz="0 0 0"
rpy="0 0 0" />
<geometry>
<mesh
filename="file://$(find jetarm_6dof_description)/meshes/jetarm_6dof/link4_collision.stl" />
</geometry>
</collision>
</link>
<joint
name="joint4"
type="revolute">
<origin
xyz="0 0 0.134444631186569"
rpy="0 0 0" />
<parent
link="link3" />
<child
link="link4" />
<axis
xyz="0 -1 0" />
<limit
lower="-2.09"
upper="2.09"
effort="1000"
velocity="10" />
</joint>
<link
name="servo_link2">
<inertial>
<origin
xyz="0.00829457691057159 0.000114732113040695 -0.0125525321145837"
rpy="0 0 0" />
<mass
value="0.00701021225113507" />
<inertia
ixx="6.10646998888003E-07"
ixy="1.66839713815154E-09"
ixz="-2.07626862362467E-08"
iyy="9.477990166652E-07"
iyz="5.12927100881908E-09"
izz="1.44691449724265E-06" />
</inertial>
<visual>
<origin
xyz="0 0 0"
rpy="0 0 0" />
<geometry>
<mesh
filename="file://$(find jetarm_6dof_description)/meshes/jetarm_6dof/servo_link2.STL" />
</geometry>
<material name="jetarm_black">
<color rgba="${jetarm_black}"/>
</material>
</visual>
<collision>
<origin
xyz="0 0 0"
rpy="0 0 0" />
<geometry>
<mesh
filename="file://$(find jetarm_6dof_description)/meshes/jetarm_6dof/servo_link2_collision.stl" />
</geometry>
</collision>
</link>
<joint
name="servo_joint2"
type="fixed">
<origin
xyz="0 0 0.0544833339503674"
rpy="0 0 0" />
<parent
link="link4" />
<child
link="servo_link2" />
<axis
xyz="0 0 0" />
</joint>
<link
name="link5">
<inertial>
<origin
xyz="-5.40141895711381E-05 -8.30141354428709E-06 0.00351551092860852"
rpy="0 0 0" />
<mass
value="0.00101775298619909" />
<inertia
ixx="2.35834256739382E-08"
ixy="-1.92177809145012E-12"
ixz="-3.88572739181837E-12"
iyy="2.35740360938003E-08"
iyz="-1.1228386368903E-13"
izz="4.40224050991292E-08" />
</inertial>
<visual>
<origin
xyz="0 0 0"
rpy="0 0 0" />
<geometry>
<mesh
filename="file://$(find jetarm_6dof_description)/meshes/jetarm_6dof/link5.STL" />
</geometry>
<material name="jetarm_black">
<color rgba="${jetarm_black}"/>
</material>
</visual>
<collision>
<origin
xyz="0 0 0"
rpy="0 0 0" />
<geometry>
<mesh
filename="file://$(find jetarm_6dof_description)/meshes/jetarm_6dof/link5.STL" />
</geometry>
</collision>
</link>
<joint
name="joint5"
type="revolute">
<origin
xyz="0 0 0"
rpy="0 0 0" />
<parent
link="servo_link2" />
<child
link="link5" />
<axis
xyz="0 0 -1" />
<limit
lower="-2.09"
upper="2.09"
effort="1000"
velocity="10" />
</joint>
<link
name="gripper_servo_link">
<inertial>
<origin
xyz="0.0145481835889059 -0.00315257290321308 0.0253492053712461"
rpy="0 0 0" />
<mass
value="0.0174988490314194" />
<inertia
ixx="4.12615692688456E-06"
ixy="-2.75102939068049E-08"
ixz="-7.61180742281118E-09"
iyy="1.57023365316943E-06"
iyz="2.2563082379695E-08"
izz="3.2612101868791E-06" />
</inertial>
<visual>
<origin
xyz="0 0 0"
rpy="0 0 0" />
<geometry>
<mesh
filename="file://$(find jetarm_6dof_description)/meshes/jetarm_6dof/gripper_link.STL" />
</geometry>
<material name="jetarm_black">
<color rgba="${jetarm_black}"/>
</material>
</visual>
<collision>
<origin
xyz="0 0 0"
rpy="0 0 0" />
<geometry>
<mesh
filename="file://$(find jetarm_6dof_description)/meshes/jetarm_6dof/gripper_link_collision.stl" />
</geometry>
</collision>
</link>
<joint
name="gripper_servo_joint"
type="fixed">
<origin
xyz="0 0 0.0054388"
rpy="0 0 0" />
<parent
link="link5" />
<child
link="gripper_servo_link" />
<axis
xyz="0 0 0" />
</joint>
<!-- end effector link -->
<link name="end_effector_link" />
<joint name="end_effector_joint" type="fixed">
<origin xyz="0 0 0.08" rpy="0 0 0"/>
<parent link="link5"/>
<child link="end_effector_link"/>
</joint>
16.5 MoveIt2 Simulation
16.5.1 MoveIt2 Kinematics Design
Kinematics Introduction
Kinematics is a branch of mechanics that describes and studies the changes in the position of an object over time from a geometric perspective, without involving the physical properties of the object or the forces applied to it. In robotics, forward kinematics and inverse kinematics are two methods used to solve the motion of robots.
Forward Kinematics involves determining the position and orientation of the end effector by knowing the values of the joint variables. In other words, it calculates the final position and orientation of the robot based on the angles of the servos.
Inverse Kinematics involves determining the required joint variables to achieve a desired position and orientation of the end effector. In this case, it calculates the angles that the servos need to rotate to achieve the final position and orientation of the robot.
Inverse Kinematics Analysis
(1) Geometric Method
For a robotic arm, the geometric method involves determining the rotation angles of each joint after specifying the position and orientation of the end effector. Since the 3D motion of a robotic arm is quite complex, we simplify the model by removing the rotational joint of the lower platform. This allows us to analyze the kinematics in a 2D plane.
Inverse kinematics analysis generally involves extensive matrix computations, making the process complex and computationally intensive, which can make implementation challenging. To better suit our needs, we use the geometric method for analyzing the robotic arm.
We simplify the model of the robotic arm by removing the base platform and actuator section, resulting in the main body of the arm. From the diagram above, we can see that the coordinates (x, y) of the end effector P are composed of three parts: (x1 + x2 + x3, y1 + y2 + y3).
In the diagram, θ1, θ2, and θ3 are the joint angles of the servos that we need to calculate, and α is the angle between the gripper and the horizontal plane. From the diagram, it is clear that the angle of the gripper from the top view, α, is equal to θ1 + θ2 + θ3. Using this, we can derive the following equation:
Where x and y are provided by the user, and l1, l2, and l3 are the inherent properties of the robotic arm’s structure.
To simplify the calculations, we process the known parts and consider them as a whole:
Substituting m and n into the existing equation and simplifying, we get:
By solving this equation, we obtain:
This result corresponds to the quadratic formula for solving a single-variable equation, where:
From this, we can calculate the angle of θ1, and similarly, we can calculate θ2. With all three servo angles determined, we can then control the servos based on these angles to achieve the desired position.
DH Modelling
(1) Introduction
The DH Parameter Table (Denavit-Hartenberg Parameter Table) is a standardized method used to describe the relative position and orientation of robotic arm joints and links. It uses four parameters to represent the relationship between each pair of adjacent joints. These four DH parameters have very clear physical meanings, as described below:
① Link Length: The length of the common normal between the axes of two adjacent joints (the rotation axis for rotational joints, the translation axis for prismatic joints).
② Link Twist: The angle by which the axis of one joint is rotated around the common normal relative to the axis of the adjacent joint.
③ Link Offset: The distance along the axis of a joint between the common normal of the current joint and the common normal of the next joint.
④ Joint Angle: The angle of rotation around the joint axis between the common normal of the current joint and the common normal of the next joint.
⑤ While these definitions might seem complex, they become much clearer when viewed in the context of coordinate systems.
First, you should focus on the two most important “lines”:
- The axis of a joint (axis).
- The common normal between the axis of one joint and the axis of the adjacent joint (common normal).
In the DH parameter system, we define the axis as the z-axis, and the common normal as the x-axis, where the direction of the x-axis is from the current joint to the next joint.
However, these two rules alone are not enough to fully determine the coordinate system of each joint. Let’s now go over the detailed steps for determining the coordinate system.
In applications such as robotic arm simulations, we may use other methods to establish coordinate systems. However, understanding the method described here is crucial for grasping the mathematical expressions of robotic arms and for understanding the subsequent analyses.
The diagram below shows two typical robot joints. Although these joints and links may not resemble any specific joints or links from real robots, they are quite common and can easily represent any joint in a real robot.
This revision simplifies and clarifies the explanation, making it easier for users to understand the concepts and how they relate to the coordinate system in robotic arms.
(2) Determine Coordinate System
There are generally several steps involved in determining the coordinate system:
To model a robot using the DH (Denavit-Hartenberg) notation, the first step is to assign a reference coordinate system to each joint. For each joint, both the Z-axis and the X-axis must be specified.
① Defining the Z-axis:
For a rotational joint, the Z-axis is aligned with the direction of rotation according to the right-hand rule. The joint variable is the rotation angle around the Z-axis. For a prismatic joint (sliding joint), the Z-axis aligns with the direction of linear motion. The joint variable is the length of travel along the Z-axis.
② Defining the X-axis:
When the X-axis is specified and two joints are neither parallel nor intersecting, the Z-axes usually form skew lines. However, there is always a common perpendicular — the shortest line between the two skew lines — which is orthogonal to both. The local reference coordinate system’s X-axis is defined along the direction of this common perpendicular. If aₙ represents the common perpendicular between Zₙ and Zₙ₋₁, then the direction of Xₙ will be along aₙ.
③ Special Cases:
- When the Z-axes of two joints are parallel, there are infinitely many common normal lines. In this case, one can choose the common normal that is collinear with the common normal of the previous joint, simplifying the model.
- When the Z-axes of two joints intersect, there is no common normal. In this case, the X-axis can be defined along the line perpendicular to the plane formed by the two axes, simplifying the model.
Once the coordinate system is assigned to each joint, the model can be represented as shown in the diagram below:
After determining the coordinate system, we can represent the four parameters more simply:
Link Length li: Defined as the distance along the positive Xi-1 axis from Z i-1 axis to Zi.
Link Twist ai: Defined as the angle of rotation along the positive direction Xi-1 (using the left-hand or right-hand rule?) between Zi-1 and Zi.
Joint Offset di: Defined as the distance along the positive Zi - 1 axis from Xi - 1 axis to the Xi.
Joint θi: Defined as the rotational angle between two axes, measured in the positive direction (using the left-hand or right-hand rule).
Joint θi: Defined as the rotational angle between Xi-1 and Xi along the positive direction Zi-1, using the right-hand rule (or left-hand rule, depending on the convention).
This tutorial uses a virtual machine as an example for configuration and learning. If the virtual machine is not yet installed, please follow the instructions in section 1, “Virtual Machine Installation and Configuration”, to install it before proceeding with the tutorial.
16.5.2 MoveIt2 Configuration
MoveIt2 Introduction
MoveIt2 is an open-source robotic motion planning framework specifically designed for ROS 2. It enables complex motion control and path planning for robots and serves as the ROS 2 version of MoveIt, a highly popular motion planning framework in ROS.
Compared to MoveIt1, MoveIt2 offers enhanced support for real-time control, thanks to improvements in ROS 2. These advancements allow for more precise and reliable robot motion control. By adopting DDS (Data Distribution Service) as its communication middleware, ROS 2 enables MoveIt2 to achieve more flexible and efficient data transmission.
MoveIt2 provides a user-friendly platform for developing advanced robotic applications, evaluating new robot designs, and integrating robotic solutions into various architectures. It is widely applied across industries, commercial ventures, research, and other fields, making it one of the most popular open-source robotic software solutions available today.
Additionally, MoveIt2 offers a suite of robust plugins and tools for the quick configuration of robotic arm control. It also provides a wealth of APIs, enabling users to easily perform secondary development on MoveIt2 modules and create innovative applications.
Confirm Robot Configuration
(1) Start the virtual machine. Click on 
on the system desktop to open the command line terminal.
(2) Enter the following command to open the configuration file:
gedit ros2_ws/.typerc
(3) Modify the section highlighted in red in the image below to the JETARM_ADVANCED version. After making the changes, press Ctrl+S to save and close the file.
(4) Return to the terminal and enter the following command to update the environment configuration:
source ~/.bashrc
Launching the Configuration Program
When entering commands, ensure case sensitivity is strictly observed. You can use the Tab key to auto-complete keywords.
(1) Start the virtual machine. Click the icon 
on the system desktop to open the terminal command line.
(2) Execute the following command to launch the MoveIt2 setup assistant.
ros2 launch moveit_setup_assistant setup_assistant.launch.py
(3) Click Edit Existing MoveIt2 Configuration Package to begin editing an existing configuration package.
(4) Click Browse and navigate to the following directory: home/ubuntu/ros2_ws/src/robot_moveIt_config; Select the folder and click Open.
(5) Click Load Files and wait for the files to load.
Once the progress reaches 100%, the robot model will appear on the right side, indicating a successful load.
(6) Adjust settings for options such as Virtual Joints and Robot Pose in the left-hand menu.
Reconfiguring will overwrite previous settings. Errors during this process may result in functionality issues.
Configuration Introduction
(1) Self-Collisions
The default collision matrix generator scans all joints of the robot. This custom collision matrix can safely disable specific collision checks, thereby reducing the processing time for motion planning.
Sampling Density:
Sampling density refers to the number of random joint configurations sampled to check for collisions. Higher density increases computation time. The default value is 10,000 collision checks.
(2) Virtual joints
Virtual joints are primarily used to connect the robot to a simulation environment. In this step, a virtual joint is defined to link the base_footprint frame to the world_frame.
(3) Planning Groups
Joint groups are used to define the various joint components required to assemble the robot.
(4) Robot Poses
Define custom pose names for the robot and specify the joint groups involved in achieving each pose.
(5) End Effectors
End effector (robot arm’s gripper)
(6) Passive Joints
Defining unused joints. Specify which joints are available and which are disabled, based on the robot’s configuration.
(7) ros2_control URDF Modifications
Configure the URDF file required for the simulation.
(8) ROS2 Controllers
Using the ROS2 Controllers panel, you can add simulated controllers for the joints. This enables MoveIt2 to simulate the motion of the robotic arm.
(9) Author Information
Provide the author’s details for documentation purposes.
(10) Movelt controllers
Configure the controller for executing trajectories in Movelt
(11) Configuration Files
① Factory Configuration
The factory configuration is pre-set, and no reconfiguration is required. If reconfiguration is needed, ensure to save the original program and compare it before making modifications.
② Generating Configuration Files
After confirming the file path, click Generate Package to generate the configuration package.
16.5.3 MoveIt2 Control
In this section, MoveIt2 will be used to plan the path and control the simulation model and robotic arm to move along the path to the specified position.
Start MoveIt2 Tool
(1) Start a new command-line terminal, and run the following command to launch the MoveIt2 tool.
ros2 launch robot_moveit_config demo.launch.py
(2) Program Interface Overview
The program interface is shown in the image below:
Position 1: RViz Toolbar
Position 2: MoveIt Debugging Area
Position 3: Simulation Model Adjustment Area
Control Instructions
(1) In the MoveIt2 Debugging Area, find and click the Planning section.
(2) In the Simulation Model Adjustment Area, you will see arrows in red, green, and blue colors. Click and drag the arrows to adjust the robotic arm’s pose. In the robot’s first-person view:
Green represents the X-axis, with the positive direction pointing to the robot’s left.
Red represents the Y-axis, with the positive direction pointing to the robot’s front.
Blue represents the Z-axis, with the positive direction pointing upwards from the robot.
(3) Besides adjusting the pose using the arrows, you can also adjust individual joints directly. Click the triangle icon on the right and find the Joints panel.
(4) Drag the sliders for the corresponding joints to adjust their angles individually.
(5) After successfully planning the robotic arm’s motion path, the new position will be highlighted in orange. If the new position causes a collision with other parts of the robot, it will be marked in red. You must adjust the configuration to avoid collisions; otherwise, the motion cannot be executed.
Orange (Executable State) is shown in the following image.
For example, if the robotic arm is planned to be in the position shown in the image, it will collide with the depth camera, turning the state red (Non-executable).
(6) After planning the path, return to the Planning section and click the Plan option. The simulation model will display the motion path from the original position to the newly planned position.
(7) Then, click the Execute option to make both the simulation model and robotic arm follow the planned motion path.
(8) Alternatively, you can click Plan & Execute, where the robotic arm will first display the new planned motion path and then execute the movement.
(9) To close this mode, press Ctrl+C in the terminal. If the process fails to stop, try again.
16.5.4 MoveIt2 Random Movement
In this section, MoveIt2 will be used to plan a path and control the simulation model and the real robotic arm to move to random positions.
Launching the MoveIt2 Tool
(1) Start a new command line terminal. Enter the following command to launch the MoveIt2 tool:
ros2 launch robot_moveit_config demo.launch.py
(2) The program interface is shown below:
Position 1: RViz Toolbar
Position 2: MoveIt Debugging Area
Position 3: Simulation Model Adjustment Area
Control Instructions
(1) In the MoveIt2 Debugging Area, locate and click the Planning section.
(2) In the Simulation Model Adjustment Area, there are arrows in green, red, and blue colors. From the robot’s first-person perspective:
Green represents the X-axis, with the positive direction pointing to the robot’s left.
Red represents the Y-axis, with the positive direction pointing to the robot’s front.
Blue represents the Z-axis, with the positive direction pointing upwards from the robot.
(3) In the Query category, click the dropdown menu under Planning Group and select the joint group (servo group) you wish to control. For example, the default selection is the arm group.
(4) Click the dropdown menu under Goal State and choose the desired target position.
(5) The parameter list in the dropdown menu is as follows:
random valid: A valid random position where no collisions will occur.
random: A random position that may potentially result in a collision.
current: The current position.
same as start: The same as the starting position.
previous: The previous target position.
home and p1 are the default positions set by the program.
(6) To avoid the possibility of collisions, select random valid to randomly generate a valid target position. Each time you click this option, a new target position will be randomly generated and displayed in the simulation model.
(7) Click Plan & Execute, and both the simulation model and robotic arm will perform the motion simultaneously. The simulation model will show the newly planned movement path, and the robotic arm will execute the motion.
(8) To exit this mode, press Ctrl+C in the terminal. If the process fails to stop, try again.
16.5.5 MoveIt2 Cartesian Path
Overview of MoveIt2 Cartesian Path
Cartesian path planning is a method of trajectory planning where the robot’s end effector moves within Cartesian space.
In MoveIt2, Cartesian path planning allows you to specify the starting and target positions of the robot’s end effector, and generates a smooth path for the end effector to move from the starting position to the target position.
(1) Cartesian Coordinate System
The Cartesian coordinate system is a general term for both orthogonal and skewed coordinate systems. It consists of two axes intersecting at the origin, forming a planar affine coordinate system. If the measurement units along both axes are equal, it is called a Cartesian coordinate system.
If the two axes are perpendicular to each other, it is known as a Cartesian orthogonal coordinate system; otherwise, it is called a Cartesian skew coordinate system.
In most cases when describing spatial position, velocity, and acceleration, we use the Cartesian coordinate system. When referring to rotations around an axis, the positive direction is determined by the right-hand rule, as shown in the diagram below:
(2) Cartesian Path Analysis
Cartesian path planning can be divided into point-to-point Cartesian path planning and continuous Cartesian path planning based on the nature of the path. This involves predefining the robot’s target points or target paths and using kinematic calculations to determine the joint-level trajectory, allowing the robot to follow the desired path.
In joint space (the space composed of all joint vectors), the movement of the robot’s axes is controlled individually. Each axis moves independently through interpolation, without affecting the other axes. The trajectory between two points taken by the robot’s end effector is an arbitrary curve.
However, in some cases, the shape of the end effector’s trajectory needs to be a straight line or arc, for example. In these cases, Cartesian path planning is used to add constraints on the shape of the trajectory.
Important: Before starting, ensure that there is enough space around the robot for movement. Keep a safe distance from the robot during operation to avoid injury from collisions with the robotic arm. Also, make sure to bend the antenna backward to prevent damage to the antenna during the robot’s movement.
This section will add Cartesian path constraints to the path planning, restricting both the simulation model and the real robotic arm to perform linear motion.
(3) Cartesian Path Planning Steps
① Set Up the Motion Group: First, specify the motion group in MoveIt2. A motion group is a set of robot joints used to define the robot’s degrees of freedom and controllable parts. By defining the motion group, you can limit the degrees of freedom in the planning process, allowing for better control over the robot’s movement.
② Set Path Constraints (Optional): If you need to constrain the robot’s motion path, such as keeping a specific joint’s orientation fixed, you can set path constraints. These constraints ensure that certain conditions are met during the planning process.
③ Specify the Start and Goal Poses: Define the robot’s motion goal by specifying the start and goal poses of the robot’s end effector. These poses can be described using the robot’s coordinate system.
④ Perform Path Planning: By calling MoveIt2’s path planning interface, the robot’s Cartesian path can be generated. MoveIt2 will plan the path based on the robot model, constraints, and target poses, resulting in a smooth trajectory.
⑤ Execute the Path: Finally, the generated path can be sent to the robot controller to execute the motion. The robot will move step-by-step along the planned path to reach the target pose.
Launch MoveIt2 Tool
(1) Open a new command-line terminal, and run the following command to launch the MoveIt2 tool.
ros2 launch robot_moveit_config demo.launch.py
(2) The program interface is shown in the figure below:
Position 1: RVIZ Toolbar
Position 2: MoveIt2 Debug Area
Position 3: Simulation Model Adjustment Area
(3) Locate the Planning section, and tick Use Cartesian Path to enable Cartesian path planning.
(4) Next, use the mouse to drag the arrows in the “Simulation Model Adjustment Area” to plan the robot arm’s path. From the robot’s perspective, the green arrow represents the X-axis, with the positive direction to the robot’s left; the red arrow represents the Y-axis, with the positive direction to the robot’s front; and the blue arrow represents the Z-axis, with the positive direction upwards from the robot.
(5) Once the planning is complete, click Plan & Execute. The simulation model will execute the action and attempt to linearly move the end effector in Cartesian space. If the action cannot be performed within the Cartesian path constraints, it will display a failure message.
(6) To exit this mode, press Ctrl+C in the terminal. If it fails to close, please try again.
16.5.6 MoveIt2 Collision Detection
MoveIt2 Collision Detection Explanation
MoveIt2’s collision detection is a critical feature that uses the robot’s motion planning path and information about surrounding objects to detect potential collisions. This ensures that the robot does not collide with any objects in its environment while performing its movements.
(1) Collision Detection Configuration Overview
In MoveIt2, collision detection is configured using the CollisionWorld object in the planning scene. The collision detection in this configuration primarily uses the FCL (Flexible Collision Library) package, which is a key C++ library in MoveIt2.
(2) Collision Object Introduction
MoveIt2 supports collision detection for various types of objects, including:
① Meshes
② Basic Shapes – such as cuboids, cylinders, cones, spheres, and planes.
③ Octomap – Octomap objects can be directly used for collision detection.
(3) Allowed Collision Matrix (ACM)
The Allowed Collision Matrix (ACM) encodes a binary value indicating whether collision detection is required between objects (which may be on the robot or in the robot’s environment).
If the value corresponding to two objects in the ACM is set to 1, it means collision detection between these objects is not required. Otherwise, collision detection will be performed.
In this section, a collision model will be added to demonstrate the effect of collision detection for both the simulation model and the real robot arm.
This section will introduce a collision model to demonstrate the collision detection effects between the simulation model and the real robotic arm.
(4) Collision Detection Steps
① Robot Description: First, provide a geometric and kinematic description of the robot, typically using a URDF (Unified Robot Description Format) file to describe the robot’s structure and connectivity. This description includes information about the robot’s joints, links, collision bodies, and sensors.
② Environment Modeling: Model the environment surrounding the robot, including the geometric shape and location of obstacles. These obstacles can be either static or dynamic.
③ Motion Planning: Using MoveIt2’s motion planner, specify the robot’s starting and target poses, and generate the robot’s motion trajectory.
④ Collision Detection: MoveIt2 will perform collision detection for each pose along the generated trajectory. It uses both the robot model and the environment model to check for potential collisions between the robot and obstacles.
⑤ Collision Avoidance: If collisions are detected, MoveIt2 will adjust the robot’s pose or path to avoid them. The system will re-plan the robot’s motion trajectory until it finds a collision-free path.
Launch MoveIt2 Tool
(1) Start a new command-line terminal. Execute the following command to initiate the MoveIt2 tool.
ros2 launch robot_moveit_config demo.launch.py
(2) The program interface is shown in the image below:
Position 1: RVIZ Toolbar
Position 2: MoveIt Debug Area
Position 3: Simulation Model Adjustment Area
(3) In the Simulation Model Adjustment Area, there are arrows in three colors: green, red, and blue. Click and drag the arrows to adjust the robot arm’s posture. From the robot’s perspective, the green arrow represents the X-axis (positive direction is to the left of the robot), the red arrow represents the Y-axis (positive direction is in front of the robot), and the blue arrow represents the Z-axis (positive direction is above the robot).
After planning the path, the new position will be highlighted in orange, as shown in the image below:
(4) Once the robot arm’s path is planned, click the Scene Objects section to add a collision model.
(5) The section is divided into 4 areas, as described below:
(6) Click the Box dropdown menu and select a collision model. Here, we will use the Sphere model as an example.
(7) Click the plus icon to add the currently selected collision model.
The model will be placed at the robot’s base by default, as shown in the image below:
(8) Use the slider to adjust the size of the collision model. It is recommended to shrink it to about 50% of the original size.
(9) Drag the 3D arrows on the sphere to move the collision model between the start and target positions to test the collision detection effect.
(10) Click the Planning section and check the Collision-aware IK option to enable the collision detection for the model.
(11) Next, click Plan & Execute to begin moving along the planned path. When the following prompt appears, select Yes.
(12) After confirming, the robot arm will plan the movement path, avoiding any obstacles along the way to prevent collisions.
(13) If you wish to exit this mode, press Ctrl+C in the terminal. If it doesn’t close successfully, please try again.
16.5.7 MoveIt2 Scene Design
When using MoveIt2 for scene design, you can create a virtual environment that includes the robot, obstacles, and target positions. This scene can be used for tasks such as motion planning, collision detection, and path optimization.
Scene Design Steps
(1) Robot Description: The robot’s structure, connections, and joint limits are typically defined using a URDF (Unified Robot Description Format) file. This description includes the robot’s geometry, kinematic parameters, and sensor information.
(2) Obstacle Modeling: During scene design, obstacles can be added to simulate the robot’s environment. These obstacles can be static, such as walls, tables, or boxes, or dynamic, such as moving objects or other robots.
(3) Target Position Setup: You can specify the robot’s target position or desired pose within the scene. These target positions could be specific locations the robot needs to reach or tasks to perform, such as grasping an object or completing a specific action.
(4) Motion Planning: Using MoveIt2’s motion planner, you can plan the robot’s path. By defining the robot’s starting and target positions, MoveIt2 calculates a smooth trajectory to move the robot from the start to the target.
(5) Collision Detection: During motion planning, MoveIt2 performs collision detection to ensure the robot does not collide with obstacles during movement. If a collision is detected, MoveIt2 will replan the path to avoid the obstacle and find a viable route.
Introduction to the Rviz Plugin
Rviz is a 3D visualization platform in the ROS system and one of the key plugins for MoveIt2. It enables the graphical display of external information and allows the publishing of control messages to the monitored objects.
Using the MoveIt2 Rviz plugin, users can set up a virtual environment (scene), interactively configure the robot’s starting and target states, test various motion planning algorithms, and visualize the results.
In this section, we will explain how to add object models to the scene.
Launch MoveIt2 Tool
(1) Open a new terminal window and enter the following command to launch the MoveIt2 tool.
ros2 launch robot_moveit_config demo.launch.py
(2) The program interface will appear as shown in the image below:
Position 1: RVIZ Toolbar
Position 2: MoveIt Debugging Area
Position 3: Simulation Model Adjustment Area
After planning the path, the new position will be highlighted in orange, as shown in the image below.
(3) In the debugging area, locate the Scene Objects section to add scene object models.
(4) This section is divided into 4 areas, as shown below.
(5) In the “Custom Models” section, select the required basic model. Here, we use the cube model as an example.
(6) Above the model selection, adjust the initial size of the object model in meters, as shown below.
(7) After adjusting, click the “+” button to add the currently configured object model to the scene.
(8) Once added, the model list will be updated with the newly added model, which will appear at the center of the scene (i.e., the robot’s center).
(9) In the simulation model adjustment area, there are arrows in red, green, and blue colors. Click and drag these arrows to adjust the robot’s pose. In the robot’s first-person view:
Green Arrow: X-axis direction, positive direction is to the left of the robot.
Red Arrow: Y-axis direction, positive direction is in front of the robot.
Blue Arrow: Z-axis direction, positive direction is above the robot.
(10) In addition to using arrow dragging, you can also make adjustments in the “Position and Size” adjustment area.
Position: Adjust the object’s position on the X, Y, and Z axes.
Rotation: Adjust the object’s angle along the X, Y, and Z axes.
Scale: Adjust the object’s size by dragging the slider.
(11) After making adjustments, click Publish to send the model’s topic message. MoveIt2 will automatically subscribe to this message.
(12) To prevent object models from colliding, go to the Planning section and check the Collision-aware IK box to enable collision detection for the model.
(14) If you wish to close this feature, press Ctrl+C in the terminal. If the closing fails, please try again.
16.5.8 MoveIt2 Trajectory Planning
Introduction to the Trajectory Planner
(1) Open Motion Planning Library (OMPL)
OMPL is an open-source motion planning library based on sampling methods (written in C++). Most of the algorithms in OMPL are derived from RRT and RPM, such as RRTStar and RRT-Connect.
Due to its modular design, support for front-end GUIs, and stable updates, OMPL has become the most widely used motion planning software (OMPL is the default for ROS).
The sampling-based planning method does not consider the dimensionality of the planning target, avoiding the “curse of dimensionality”. This makes it highly effective for path planning in high-dimensional spaces and complex constraint environments, which is a key reason OMPL is applicable to MoveIt2 robotic arm control.
For an N-degree-of-freedom robotic arm motion planning problem, OMPL can plan a trajectory for the end effector within the robot’s joint space. This trajectory consists of M arrays (with M control points), each with N dimensions (representing the joint sequence for each control point). The robotic arm will follow this trajectory without colliding with obstacles in the environment.
(2) Industrial Motion Planner (Pilz)
The Pilz industrial motion planner is a deterministic generator designed for circular and linear motion. It also supports combining multiple motion segments using MoveIt2 functionality.
(3) Stochastic Trajectory Optimization for Motion Planning (STOMP)
STOMP is an optimization-based motion planner built upon the PI^2 algorithm. It is capable of planning smooth trajectories for robotic arms, avoiding obstacles, and optimizing constraints. This algorithm does not require gradients, allowing it to optimize any terms in the cost function.
(4) Search-Based Planning Library (SBPL)
The SBPL is a collection of general-purpose motion planners that use search-based methods to discretize space.
(5) Covariant Hamiltonian Optimization for Motion Planning (CHOMP)
CHOMP is an innovative gradient-based trajectory optimization program that simplifies many common motion planning problems and makes them trainable.
Most high-dimensional motion planners divide the trajectory generation process into two distinct stages: planning and optimization. In contrast, CHOMP uses covariant gradients and function gradients during the optimization stage to design a motion planning algorithm entirely based on trajectory optimization.
Given an infeasible initial trajectory, CHOMP quickly responds to the surrounding environment to avoid collisions while optimizing dynamic parameters like joint velocity and acceleration. This algorithm can rapidly converge to a smooth, collision-free trajectory, allowing the robot to efficiently execute the path.
Before starting, ensure there is enough workspace around the robot. Maintain a safe distance during operation to prevent the robotic arm from colliding with your body. Also, bend the antenna backward to prevent it from being damaged by the robot’s movement.
This section integrates the OMPL and CHOMP planners. By default, the OMPL planner is used. Below, we will demonstrate how to switch to and use the CHOMP planner.
Start MoveIt2 Tool
(1) Open a new command-line terminal. Launch MoveIt2 Tool: Enter the following command to launch the MoveIt2 tool:
ros2 launch robot_moveit_config demo.launch.py
(2) The program interface is displayed as shown below:
Position 1: RVIZ Toolbar
Position 2: MoveIt2 Debugging Area
Position 3: Simulation Model Adjustment Area
(3) Adjust Robot Pose: In the simulation model adjustment area, there are red, green, and blue arrows. Click and drag the arrows to adjust the robotic arm’s pose. The robot is viewed from its first-person perspective, with:
Green: X-axis (positive direction is to the left of the robot)
Red: Y-axis (positive direction is in front of the robot)
Blue: Z-axis (positive direction is above the robot)
(4) Adjust Individual Joints: In addition to adjusting the pose with the arrows, you can directly adjust the individual joints. Click the triangle icon on the right side, then find and click the Joints panel.
(5) Fine-tune Joint Angles: Drag the corresponding sliders to adjust the angles of the individual joints.
(6) Path Planning and Collision Detection: After successfully planning the robotic arm’s movement path, the new position will be indicated in orange. If there is a collision with other parts of the robot, the position will be marked in red. In this case, you need to adjust the pose to avoid collisions, or the action cannot be executed.
Orange indicates an executable position, as shown below:
(7) Visualize the Motion Path: In the RVIZ toolbar, click Motion Planning and Planned Path, then check the Show Trail option. This will display the visual trail of each frame of the robotic arm’s movement.
(8) Demonstrate the Movement Path: Return to the Planning section, and click the Plan button. The simulation model will demonstrate the path from the original position to the newly planned position.
(9) Execute the Planned Path: After observing the demonstration, uncheck the Show Trail option. Then, click the Execute button. The simulation model and the robot will simultaneously execute the planned motion.
(10) To close this mode, press Ctrl+C in the terminal. If the shutdown fails, try again.
16.5.9 Simulation and Robotic Arm Synchronization
In this section, we will plan a motion trajectory in the simulation and execute it to synchronize the real robotic arm’s movements.
(1) Important Notes
① Network Requirements: The virtual machine and the robot must be on the same network segment and able to communicate with each other in order to control the robot. Otherwise, only simulation is possible, and the robot will not execute the planned movements.
② Safety Precautions: Before starting, ensure there is enough space around the robot for movement. Maintain a safe distance from the robot during execution to prevent any collisions between the robotic arm and your body that could cause injury.
Starting Robot Services
(1) Start the Robot: Click on the system desktop icon to open the command terminal, then enter the command to disable the auto-start service:
sudo systemctl stop start_app_node.service
(2) Start the Robot Chassis Control Node: This node is responsible for enabling synchronization between the simulation and the real robotic arm.
ros2 launch sdk jetarm_sdk.launch.py
Starting Services on the Virtual Machine
(1) Start the Virtual Machine: Click the system desktop icon to open the command terminal.
(2) Start MoveIt2 Tool: Open a new terminal and enter the following command to launch MoveIt2:
ros2 launch robot_moveit_config demo.launch.py
(3) Control Robotic Arm Movement: Use the slider to adjust the motion planning for the robotic arm, then click Plan & Execute. The simulated robotic arm and the real robotic arm will execute the action synchronously.
Note: In practice, the software execution of actions may appear slower, which is normal!
16.6 Gazebo Simulation
This tutorial uses a virtual machine as an example for configuration and learning. If you have not installed a virtual machine, refer to section 1. Virtual Machine Installation and Configuration for installation instructions before proceeding.
16.6.1 Introduction to Gazebo
To simulate a realistic virtual physical environment where robots can perform tasks more effectively, we use a simulation software: Gazebo.
Gazebo is standalone software and is the most commonly used simulation tool in the ROS ecosystem. It provides:
High-fidelity physical simulation conditions.
A comprehensive set of sensor models.
A user-friendly interactive interface.
These features enable robots to function effectively even in complex environments.
Gazebo supports URDF and SDF file formats for describing simulation environments. The robot models use the URDF format. Additionally, Gazebo provides many pre-built model modules that can be used directly.
16.6.2 Gazebo GUI Introduction
The simulation software interface is as below:
The specific functions of each position are detailed in the table below:
| Name | Function |
|---|---|
| Tool bar (1) | Provides commonly used options for interacting with the simulator. |
| Menu bar (2) | Configures or modifies simulation parameters and offers interaction features. |
| Action Bar(3) | Allows manipulation of models and adjustment of parameters. |
| Timestamp (4) | Controls the time in the virtual environment. |
| Scene (5) | The main part of the simulator where the simulation models are displayed. |
For more information about Gazebo, please visit the official website: [http://gazebosim.org/](http://gazebosim.org/).
Gazebo Learning Resources
Gazebo Official Website: [https://gazebosim.org/](https://gazebosim.org/)
Gazebo Tutorials: [https://gazebosim.org/tutorials](https://gazebosim.org/tutorials)
Gazebo GitHub Repository: [https://github.com/osrf/gazebo](https://github.com/osrf/gazebo)
Gazebo Answers Forum: [http://answers.gazebosim.org/](http://answers.gazebosim.org/)
16.6.3 Gazebo xacro Model Visualization
To better understand the robot’s model and structure, you can use Gazebo for visualization. Follow these steps:
Start the Simulation
Command inputs are case-sensitive. Use the Tab key for auto-completion of keywords.
(1) Start the virtual machine. Click-on the system desktop icon 
to execute the command-line terminal.
(2) Execute the command below to access the configuration file.
gedit ros2_ws/.typerc
(3) Fill in the corresponding parameters based on your machine type. After completing the entry, press Ctrl+S to save and close the file.
Different machine types correspond to different simulation models!
(4) Return to the terminal and enter the following command to update the environment configuration:
source ~/.bashrc
(5) Enter the following command to open the Gazebo simulation model:
ros2 launch robot_gazebo worlds.launch.py
(6) To close the currently running program in the terminal window, press the shortcut Ctrl+C.
Introduction to Shortcuts and Tools
Here, we will introduce some commonly used shortcuts and tools in Gazebo, using mouse controls as examples:
(1) Mouse Shortcuts
Left Mouse Button:
Drag the Map: Press and hold the left mouse button on the map to drag it.
Select Target: Click on a model to select it.
(2) Middle Mouse Button or Shift + Left Mouse Button:
Press and hold while moving the mouse to rotate the view around the current target position.
(3) Right Mouse Button or Mouse Wheel:
Hold the right mouse button or scroll the wheel to zoom in and out, focusing on the point under the cursor.
Toolbar Tools
We’ll explain a few tools from the toolbar using the following example:
(4) Selection tool 
: This is Gazebo’s default tool, used to select models.
(5) Move Tool 
: Use this tool to select a model and drag the three axes to control its movement.
(6) Rotate Tool 
: Use this tool to select a model and drag the three axes to control its rotation.
For more information about Gazebo, visit the official website: http://gazebosim.org/
16.6.4 Gazebo and MoveIt2 Simulation Integration
Enable Simulation Service
(1) Start the virtual machine. Click-on to initiate the command-line terminal.
(2) Execute the following command to initiate the integration of the Gazebo and MoveIt2.
ros2 launch robot_gazebo worlds.launch.py moveit_unite:=true
(3) Enter the following command to start the MoveIt2.
ros2 launch robot_moveit_config demo.launch.py use_sim_time:=true use_gazebo:=true
Operation
(1) Robot Arm Control
The MoveIt2 interface is shown below:
Position 1: RVIZ toolbar
Position 2: MoveIt2 Debugging Area
Position 3: Simulation Model Adjustment Area
(2) In the MoveIt2 Debugging Area, find and click on the Planning section.
(3) In the Simulation Model Adjustment Area, there are three colored arrows: red, green, and blue. Click and drag the arrows to adjust the robotic arm’s orientation. From the robot’s perspective:
Green represents the X-axis (positive direction is to the left of the robot).
Red represents the Y-axis (positive direction is in front of the robot).
Blue represents the Z-axis (positive direction is above the robot).
(4) After successfully planning the arm’s motion path, the new position will be highlighted in orange. If the new position causes a collision with other parts of the robot, it will be marked in red. In this case, you need to adjust the position to avoid the collision; otherwise, the action cannot be executed.
Orange indicates an executable state, as shown below:
For example, if the robotic arm is positioned as shown in the image, it will collide with the depth camera, turning red (non-executable state) as shown below:
(5) Once the path is planned, return to the Planning section and click Plan. The simulation model will demonstrate the movement path from the original position to the newly planned position.
(6) Next, click Execute to make both the simulation model and the robotic arm follow the planned path.
(7) Alternatively, click Plan & Execute, and the robotic arm will first display the newly planned movement path, then execute the motion.
(8) You can also observe that the path planned in MoveIt2 is synchronized with the Gazebo interface.
Gripper Control
(1) To control the gripper movement, select gripper in the Planning Group.
(2) Drag the r joint to control the gripper’s rotation.
(3) Once the motion trajectory is planned, return to Planning and click Plan & Execute to execute the movement.
