Gem Cutter Manipulator - ROS2 MoveIt Configuration

A comprehensive ROS2 workspace for a 6-DOF gem cutter manipulator robot with MoveIt motion planning framework integration. This project includes robot description (URDF), Gazebo simulation, and MoveIt configuration for motion planning and control.

Project Overview

This workspace contains three main ROS2 packages:

gem_cutter_description: Contains the robot's URDF/XACRO description files, visual materials, and RViz configuration
gem_cutter_gazebo: Gazebo simulation launch files and world definitions
gem_cutter_moveit_config: Complete MoveIt configuration package generated using MoveIt Setup Assistant

The robot is a 6-DOF manipulator designed for gem cutting operations, with the following joint configuration:

J1: Base yaw (rotation around Z-axis)
J2: Shoulder pitch (rotation around Y-axis)
J3: Elbow pitch (rotation around Y-axis)
J4: Wrist pitch (rotation around Y-axis)
J5: Wrist roll (rotation around X-axis)
J6: Tool yaw (rotation around Z-axis)

Figure 1: Gem cutter manipulator visualized in RViz with joint_state_publisher_gui for manual joint control

Project Structure

gem_cutter_manipulator/
├── build/                    # Build artifacts (generated)
├── install/                  # Installed packages (generated)
├── log/                     # Build logs (generated)
├── rebuild.sh               # Build script
├── src/
│   ├── gem_cutter_description/
│   │   ├── urdf/
│   │   │   ├── gem_cutter_arm.urdf.xacro  # Main robot URDF (XACRO)
│   │   │   ├── gem_cutter.urdf            # Plain URDF (non-XACRO)
│   │   │   └── materials.xacro            # Visual materials definition
│   │   ├── launch/
│   │   │   └── display.launch.py          # RViz visualization launch
│   │   ├── config/
│   │   │   └── rviz/
│   │   │       └── config.rviz            # RViz configuration
│   │   └── package.xml
│   ├── gem_cutter_gazebo/
│   │   ├── launch/
│   │   │   ├── sim.launch.py              # Basic Gazebo simulation
│   │   │   └── sim_with_moveit.launch.py  # Gazebo + MoveIt integration
│   │   ├── worlds/
│   │   │   └── gem_cutter_world.sdf       # Gazebo world definition
│   │   └── package.xml
│   └── gem_cutter_moveit_config/
│       ├── config/
│       │   ├── gem_cutter_arm.srdf         # Semantic Robot Description Format
│       │   ├── gem_cutter_arm.urdf.xacro   # URDF with ros2_control integration
│       │   ├── gem_cutter_arm.ros2_control.xacro  # ros2_control configuration
│       │   ├── kinematics.yaml            # Kinematics solver configuration
│       │   ├── joint_limits.yaml           # Joint velocity/acceleration limits
│       │   ├── moveit_controllers.yaml    # MoveIt controller configuration
│       │   ├── ros2_controllers.yaml       # ROS2 controller configuration
│       │   ├── initial_positions.yaml      # Initial joint positions
│       │   ├── pilz_cartesian_limits.yaml  # Pilz planner limits
│       │   └── moveit.rviz                 # MoveIt RViz configuration
│       ├── launch/
│       │   ├── demo.launch.py              # Main demo launch (MoveIt + RViz)
│       │   ├── setup_assistant.launch.py   # MoveIt Setup Assistant
│       │   ├── move_group.launch.py        # MoveIt move_group node
│       │   ├── moveit_rviz.launch.py       # MoveIt RViz visualization
│       │   ├── rsp.launch.py               # Robot State Publisher
│       │   └── spawn_controllers.launch.py # Controller spawning
│       ├── scripts/
│       │   └── spawn_scene.py              # Scene object spawner
│       └── package.xml

Prerequisites

ROS2 Distribution: Jazzy Jalisco (Ubuntu 24.04)
Required ROS2 Packages:
- moveit2
- moveit_configs_utils
- ros_gz_sim (Gazebo Sim)
- ros_gz_bridge
- xacro
- robot_state_publisher
- joint_state_publisher
- joint_state_publisher_gui
- rviz2
- controller_manager
- joint_trajectory_controller

Install dependencies:

sudo apt update
sudo apt install ros-jazzy-moveit2 \
                 ros-jazzy-moveit-configs-utils \
                 ros-jazzy-ros-gz-sim \
                 ros-jazzy-ros-gz-bridge \
                 ros-jazzy-xacro \
                 ros-jazzy-robot-state-publisher \
                 ros-jazzy-joint-state-publisher \
                 ros-jazzy-joint-state-publisher-gui \
                 ros-jazzy-rviz2 \
                 ros-jazzy-controller-manager \
                 ros-jazzy-joint-trajectory-controller

Building the Workspace

Using the Rebuild Script (Recommended)

The rebuild.sh script automates the entire build process:

cd ~/development/ros/gem_cutter_manipulator
./rebuild.sh

What rebuild.sh does:

Cleans previous build artifacts (build/, install/, log/)
Sources ROS2 Jazzy base installation
Builds the workspace using colcon build --symlink-install
Sources the workspace overlay
Sets up Gazebo resource paths

Manual Build Process

# 1. Source ROS2 base
source /opt/ros/jazzy/setup.bash

# 2. Navigate to workspace
cd ~/development/ros/gem_cutter_manipulator

# 3. Build workspace
colcon build --symlink-install

# 4. Source workspace overlay
source install/setup.bash

# 5. Set Gazebo resource path (optional, for simulation)
export GZ_SIM_RESOURCE_PATH="${GZ_SIM_RESOURCE_PATH:+$GZ_SIM_RESOURCE_PATH:}$(ros2 pkg prefix gem_cutter_description)/share"

Note: The --symlink-install flag creates symbolic links instead of copying files, allowing you to edit source files without rebuilding.

Major Files Explained

1. URDF Files

`src/gem_cutter_description/urdf/gem_cutter_arm.urdf.xacro`

Purpose: Main robot description file using XACRO macros
Key Features:
- Defines all 6 joints and 7 links (base_link + 6 links)
- Includes inertial properties (mass, inertia tensors)
- Visual and collision geometries
- Joint limits, dynamics (damping, friction)
- Supports prefix argument for multi-robot scenarios
Structure:
- Base link: 9cm × 8.4cm plate
- Link 1: Pedestal with shoulder servo block
- Link 2: Upper arm (purple)
- Link 3: Forearm (light blueish green)
- Link 4: Wrist pitch link (green)
- Link 5: Roll body with offset fin (light blue)
- Link 6: Tool mount and end effector

`src/gem_cutter_description/urdf/materials.xacro`

Purpose: Defines visual materials/colors for RViz visualization
Materials: gray, purple, light_blueish_green, green, light_blue, tool_silver, marker_red

2. MoveIt Configuration Files

`src/gem_cutter_moveit_config/config/gem_cutter_arm.srdf`

Purpose: Semantic Robot Description Format - extends URDF with MoveIt-specific information
Key Sections:
- Groups: Defines planning groups (e.g., gem_cutter group includes all arm links/joints)
- Group States: Named poses (home, pose1, pose2)
- End Effector: Defines ee_tool as end effector
- Virtual Joint: Connects robot to world frame
- Disabled Collisions: Optimizes collision checking by disabling unnecessary checks

`src/gem_cutter_moveit_config/config/kinematics.yaml`

Purpose: Configures the kinematics solver

Configuration:

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

Solver: KDL (Kinematics and Dynamics Library) - see Kinematics Solver section

`src/gem_cutter_moveit_config/config/joint_limits.yaml`

Purpose: Defines velocity and acceleration limits for each joint
Key Parameters:
- default_velocity_scaling_factor: 0.5 (50% of max velocity)
- default_acceleration_scaling_factor: 0.5 (50% of max acceleration)
- Per-joint limits for safety and realistic motion

`src/gem_cutter_moveit_config/config/moveit_controllers.yaml`

Purpose: Configures MoveIt's controller manager
Controller: gem_cutter_controller (FollowJointTrajectory action)

`src/gem_cutter_moveit_config/config/ros2_controllers.yaml`

Purpose: ROS2 controller configuration for ros2_control
Controller Type: joint_trajectory_controller/JointTrajectoryController
Update Rate: 100 Hz
Interfaces: Position command, position/velocity state

`src/gem_cutter_moveit_config/config/gem_cutter_arm.ros2_control.xacro`

Purpose: Defines ros2_control hardware interface
Hardware Plugin: mock_components/GenericSystem (for simulation/testing)
Joints: All 6 joints with position command and position/velocity state interfaces

3. Launch Files

`src/gem_cutter_moveit_config/launch/demo.launch.py`

Purpose: Main demo launch file - starts MoveIt with RViz
What it launches:
- MoveIt move_group node
- Robot State Publisher
- RViz with MoveIt plugin
- Scene spawner (adds collision objects after 2 seconds)

`src/gem_cutter_moveit_config/launch/setup_assistant.launch.py`

Purpose: Launches MoveIt Setup Assistant GUI for reconfiguring MoveIt
Usage: See Running Major Commands

`src/gem_cutter_gazebo/launch/sim_with_moveit.launch.py`

Purpose: Integrates Gazebo simulation with MoveIt
What it launches:
- Gazebo simulation
- Robot State Publisher
- MoveIt move_group
- RViz with MoveIt plugin
- Clock bridge (Gazebo → ROS2)

Running Major Commands

1. Generate URDF from XACRO

Before using MoveIt Setup Assistant, you need to generate a plain URDF file:

# Source workspace
source ~/development/ros/gem_cutter_manipulator/install/setup.bash

# Generate URDF
ros2 run xacro xacro \
  $(ros2 pkg prefix gem_cutter_description)/share/gem_cutter_description/urdf/gem_cutter_arm.urdf.xacro \
  > /tmp/gem_cutter_arm.urdf

Purpose: MoveIt Setup Assistant requires a plain URDF file (not XACRO). This command processes the XACRO file and outputs a complete URDF.

2. Launch MoveIt Setup Assistant

# Source workspace
source ~/development/ros/gem_cutter_manipulator/install/setup.bash

# Launch Setup Assistant
ros2 launch gem_cutter_moveit_config setup_assistant.launch.py

Purpose: Opens the MoveIt Setup Assistant GUI for:

Reconfiguring planning groups
Adjusting collision checking
Setting up end effectors
Configuring kinematics solvers
Defining group states (named poses)

Note: The configuration is already set up, but you can use this to modify it.

Figure 2: MoveIt Setup Assistant GUI showing the gem_cutter planning group configuration

3. Rebuild the Workspace

cd ~/development/ros/gem_cutter_manipulator
./rebuild.sh

Purpose: Clean rebuild of the entire workspace. Use this after:

Modifying URDF files
Changing MoveIt configuration
Adding new packages

4. Launch MoveIt Demo

# Source workspace
source ~/development/ros/gem_cutter_manipulator/install/setup.bash

# Launch demo
ros2 launch gem_cutter_moveit_config demo.launch.py

What happens:

Starts MoveIt move_group node
Launches RViz with MoveIt plugin
After 2 seconds, spawns scene objects (ground plane, gem stand, gem)
You can interactively plan and execute motions

In RViz, you can:

Use "Planning" tab to plan motions
Use "Motion Planning" plugin to drag end effector
Execute planned trajectories
View collision objects

Figure 4: ROS2 node graph showing the communication structure between nodes when running the MoveIt demo

5. Visualize Robot in RViz (without MoveIt)

source ~/development/ros/gem_cutter_manipulator/install/setup.bash
ros2 launch gem_cutter_description display.launch.py

Purpose: Simple visualization with joint_state_publisher_gui for manual joint control.

6. Launch Gazebo Simulation with MoveIt

source ~/development/ros/gem_cutter_manipulator/install/setup.bash
ros2 launch gem_cutter_gazebo sim_with_moveit.launch.py

Purpose: Runs Gazebo simulation integrated with MoveIt for realistic physics simulation.

Figure 3: Gem cutter manipulator in Gazebo simulation environment

7. Launch Gazebo Simulation Only

source ~/development/ros/gem_cutter_manipulator/install/setup.bash
ros2 launch gem_cutter_gazebo sim.launch.py

Purpose: Basic Gazebo simulation without MoveIt integration.

Robot Description (URDF)

Physical Hardware Setup

Figure 5: Physical assembly showing the Raspberry Pi controller, power supply, and the 5-DOF manipulator arm.

URDF Structure

The robot is defined using URDF (Unified Robot Description Format) with XACRO macros for parameterization.

Joint Configuration

Joint	Name	Type	Axis	Limits (rad)	Effort	Velocity
J1	`joint1_base_yaw`	Revolute	Z (0,0,1)	±π	2.0 N⋅m	2.0 rad/s
J2	`joint2_shoulder_pitch`	Revolute	Y (0,1,0)	-1.25 to 1.35	2.0 N⋅m	2.0 rad/s
J3	`joint3_elbow_pitch`	Revolute	Y (0,1,0)	±2.10	2.0 N⋅m	2.0 rad/s
J4	`joint4_wrist_pitch`	Revolute	Y (0,1,0)	±1.70	1.5 N⋅m	2.5 rad/s
J5	`joint5_wrist_roll`	Revolute	X (1,0,0)	±π	1.0 N⋅m	4.0 rad/s
J6	`joint6_tool_yaw`	Revolute	Z (0,0,1)	±π	0.8 N⋅m	4.0 rad/s

Link Chain

base_link
  └── joint1_base_yaw (Z-axis rotation)
      └── link1_pedestal
          └── joint2_shoulder_pitch (Y-axis rotation)
              └── link2_upper_arm
                  └── joint3_elbow_pitch (Y-axis rotation)
                      └── link3_forearm
                          └── joint4_wrist_pitch (Y-axis rotation)
                              └── link4_wrist_pitch_link
                                  └── joint5_wrist_roll (X-axis rotation)
                                      └── link5_roll_body
                                          └── joint6_tool_yaw (Z-axis rotation)
                                              └── tool_mount
                                                  └── ee_fixed (fixed joint)
                                                      └── ee_tool (end effector)

Coordinate Frames

The robot follows REP-103 convention:

X: Forward
Y: Left
Z: Up

Physical Properties

Each link includes:

Inertial properties: Mass, center of mass, inertia tensor
Visual geometry: For visualization in RViz/Gazebo
Collision geometry: For collision checking (can be simplified)

Key Design Features

Base Plate: 9cm × 8.4cm rectangular base
Pedestal: Cylindrical pedestal with shoulder servo block
Upper Arm: 11cm long link (purple)
Forearm: 10cm long link (light blueish green)
Wrist: Compact wrist assembly with pitch and roll
End Effector: Fixed tool (cutter/screwdriver style) ~3.3cm long

MoveIt Configuration

What is MoveIt?

MoveIt is a motion planning framework for ROS that provides:

Motion Planning: Path planning algorithms (OMPL planners)
Kinematics: Forward/inverse kinematics solvers
Collision Checking: Self-collision and environment collision detection
Trajectory Execution: Controller integration for executing planned paths
Visualization: RViz integration for interactive planning

Configuration Components

1. Planning Groups (`gem_cutter_arm.srdf`)

The gem_cutter planning group includes:

All 7 links (base_link through ee_tool)
All 6 revolute joints
Virtual joint connecting to world frame

2. End Effector

Name: ee_tool
Parent Link: tool_mount
Planning Group: gem_cutter

3. Virtual Joint

Name: virtual_joint
Type: Fixed
Parent Frame: world
Child Link: base_link

This connects the robot to a fixed world frame, allowing MoveIt to plan motions relative to the world.

4. Disabled Collisions

MoveIt disables collision checking between:

Adjacent links (always in contact)
Links that never collide (optimization)
Example: ee_tool and link3_forearm (never collide)

5. Group States (Named Poses)

Predefined poses:

home: All joints at 0
pose1: Extended pose
pose2: Different extended pose with rotation

Planning Pipeline

MoveIt uses OMPL (Open Motion Planning Library) planners:

Default Planner: RRTConnect
Planning Time: Configurable (default ~5 seconds)
Planning Attempts: Multiple attempts if first fails

Controller Integration

MoveIt communicates with controllers via:

Action Interface: FollowJointTrajectory action
Controller: gem_cutter_controller
Trajectory Execution: Monitors execution and handles errors

Kinematics Solver (KDL)

What is KDL?

KDL (Kinematics and Dynamics Library) is a C++ library that provides:

Forward kinematics (joint angles → end effector pose)
Inverse kinematics (end effector pose → joint angles)
Jacobian computation
Dynamics computations

KDL Kinematics Plugin

MoveIt uses kdl_kinematics_plugin/KDLKinematicsPlugin which:

Implements MoveIt's kinematics plugin interface
Uses KDL's numerical inverse kinematics solver
Supports 6-DOF manipulators (like this robot)

Configuration (`kinematics.yaml`)

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

Parameters:

kinematics_solver: Plugin name
kinematics_solver_search_resolution: 0.005 rad (~0.29°) - discretization for IK search
kinematics_solver_timeout: 0.005 seconds - timeout per IK attempt

How KDL IK Works

Numerical Method: Uses iterative numerical optimization (not analytical)
Seed State: Requires initial joint configuration (seed)
Search: Explores joint space around seed to find solution
Resolution: Smaller resolution = more accurate but slower
Timeout: If no solution found within timeout, returns failure

Advantages of KDL

General: Works for any robot configuration
No Closed-Form Required: Doesn't need analytical IK solution
Well-Tested: Mature, widely-used library
ROS Integration: Native ROS support

Limitations

Slower: Numerical methods are slower than analytical IK
No Guarantee: May not find solution even if one exists
Local Minima: Can get stuck in local minima
Seed Dependent: Quality depends on seed configuration

Alternative Solvers

For this 6-DOF robot, you could also use:

TRAC-IK: Faster, more robust IK solver
Analytical IK: If closed-form solution exists (rare for 6-DOF)

Arm Configuration Details

Joint Limits Explained

Joint 1 (Base Yaw)

Range: ±π radians (±180°)
Purpose: Full rotation for workspace coverage
Limitation: None (full rotation)

Joint 2 (Shoulder Pitch)

Range: -1.25 to 1.35 radians (~-72° to +77°)
Purpose: Prevents upper arm from hitting pedestal/base
Limitation: Asymmetric limits prevent collision with base structure

Joint 3 (Elbow Pitch)

Range: ±2.10 radians (±120°)
Purpose: Allows large fold/unfold motions
Limitation: Prevents extreme back-bending that could cause self-collision

Joint 4 (Wrist Pitch)

Range: ±1.70 radians (±97°)
Purpose: Tool orientation control
Limitation: Prevents tool from colliding with forearm

Joint 5 (Wrist Roll)

Range: ±π radians (±180°)
Purpose: Tool roll orientation
Limitation: None (full rotation)

Joint 6 (Tool Yaw)

Range: ±π radians (±180°)
Purpose: Final tool orientation
Limitation: None (full rotation)

Dynamics Parameters

Each joint includes dynamics:

Damping: Friction-like resistance (0.05-0.25)
Friction: Static friction (0.05-0.10)

Higher damping/friction values make motion more realistic but require more effort.

Workspace Analysis

Reach: Approximately 0.25-0.30 meters from base

Base to shoulder: ~0.065 m
Upper arm: 0.11 m
Forearm: 0.10 m
Wrist + tool: ~0.07 m
Total: ~0.35 m theoretical, ~0.25-0.30 m practical

Workspace Shape: Spherical shell (due to J1 full rotation)

Mass Distribution

Total robot mass: ~1.22 kg

Base: 0.35 kg
Link 1: 0.25 kg
Link 2: 0.22 kg
Link 3: 0.18 kg
Link 4: 0.10 kg
Link 5: 0.09 kg
Tool mount: 0.03 kg
End effector: 0.05 kg

Inertia Properties

Each link includes inertia tensor (6 values: Ixx, Iyy, Izz, Ixy, Ixz, Iyz):

Base: Largest inertia (0.0008 Izz)
Upper arm: Significant inertia (0.00045 Iyy, Izz)
End effector: Smallest inertia (0.000005)

These values affect:

Motion dynamics
Torque requirements
Collision response

Usage Examples

Example 1: Visualize Robot Model

# Terminal 1: Launch visualization
source install/setup.bash
ros2 launch gem_cutter_description display.launch.py

# In RViz:
# - Use joint_state_publisher_gui to move joints
# - Robot model updates in real-time

The visualization shows the robot model with all 6 joints controllable via the joint_state_publisher_gui (see Figure 1 above).

Example 2: Plan and Execute Motion

# Terminal 1: Launch MoveIt demo
source install/setup.bash
ros2 launch gem_cutter_moveit_config demo.launch.py

# In RViz Motion Planning plugin:
# 1. Click "Planning" tab
# 2. Select "gem_cutter" planning group
# 3. Drag end effector to desired pose
# 4. Click "Plan" button
# 5. Review planned path (green line)
# 6. Click "Execute" to execute trajectory

Example 3: Use Named Poses

# After launching demo.launch.py
# In RViz Motion Planning plugin:
# 1. Go to "Planning" tab
# 2. Select "gem_cutter" group
# 3. Under "Query" section, select named state:
#    - "home" (all zeros)
#    - "pose1" (extended pose)
#    - "pose2" (rotated extended pose)
# 4. Click "Plan and Execute"

Example 4: Programmatic Motion Planning

Create a Python script to plan motions programmatically:

#!/usr/bin/env python3
import rclpy
from rclpy.node import Node
from moveit_msgs.msg import MoveItErrorCodes
from moveit_msgs.srv import GetMotionPlan
from geometry_msgs.msg import Pose

class MoveItPlanner(Node):
    def __init__(self):
        super().__init__('moveit_planner')
        self.plan_client = self.create_client(
            GetMotionPlan, 
            '/plan_kinematic_path'
        )
    
    def plan_to_pose(self, target_pose: Pose):
        # Create planning request
        request = GetMotionPlan.Request()
        request.motion_plan_request.group_name = "gem_cutter"
        request.motion_plan_request.num_planning_attempts = 10
        request.motion_plan_request.allowed_planning_time = 5.0
        
        # Set target pose
        request.motion_plan_request.goal_constraints[0].position_constraints[0].constraint_region.primitive_poses[0] = target_pose
        
        # Send request
        future = self.plan_client.call_async(request)
        rclpy.spin_until_future_complete(self, future)
        
        return future.result()

# Usage
if __name__ == '__main__':
    rclpy.init()
    planner = MoveItPlanner()
    # ... create target pose ...
    result = planner.plan_to_pose(target_pose)
    rclpy.shutdown()

Example 5: Gazebo Simulation

# Terminal 1: Launch Gazebo + MoveIt
source install/setup.bash
ros2 launch gem_cutter_gazebo sim_with_moveit.launch.py

# This launches:
# - Gazebo with physics simulation
# - Robot model in Gazebo
# - MoveIt planning
# - RViz visualization

# You can now plan motions that respect physics!

The Gazebo simulation provides realistic physics-based motion (see Figure 3 above).

Troubleshooting

Issue: MoveIt can't find robot description

Solution:

# Make sure workspace is sourced
source install/setup.bash

# Verify robot description is available
ros2 param get /robot_state_publisher robot_description

Issue: Planning fails

Possible causes:

Target pose unreachable
Collision with environment
Self-collision
IK solver timeout too short

Solutions:

Check target pose is within workspace
Increase kinematics_solver_timeout in kinematics.yaml
Increase planning time in RViz
Check collision objects in scene

Issue: Controllers not found

Solution:

# Check if controllers are loaded
ros2 control list_controllers

# If not, spawn them manually
ros2 launch gem_cutter_moveit_config spawn_controllers.launch.py

Issue: Gazebo robot doesn't move

Solution:

Ensure ros2_control is properly configured
Check controller manager is running
Verify joint state publisher is publishing

Additional Resources

License

gem_cutter_description: Apache-2.0
gem_cutter_gazebo: Apache-2.0
gem_cutter_moveit_config: BSD-3-Clause

Maintainer

Nihara Randini (shniharard@gmail.com)

Version

Workspace: Current
MoveIt Config: 0.3.0
ROS2: Jazzy Jalisco

Name		Name	Last commit message	Last commit date
DoF-5_ros_arm		DoF-5_ros_arm
images		images
readme		readme
src		src
.gitignore		.gitignore
ANGLE_CALIBRATION_GUIDE.md		ANGLE_CALIBRATION_GUIDE.md
README.md		README.md
TROUBLESHOOTING.md		TROUBLESHOOTING.md
rebuild.sh		rebuild.sh
test_serial.py		test_serial.py
tmp.txt		tmp.txt

Latest commit

History

Folders and files

Repository files navigation

Gem Cutter Manipulator - ROS2 MoveIt Configuration

Table of Contents

Project Overview

Project Structure

Prerequisites

Building the Workspace

Using the Rebuild Script (Recommended)

Manual Build Process

Major Files Explained

1. URDF Files

src/gem_cutter_description/urdf/gem_cutter_arm.urdf.xacro

src/gem_cutter_description/urdf/materials.xacro

2. MoveIt Configuration Files

src/gem_cutter_moveit_config/config/gem_cutter_arm.srdf

src/gem_cutter_moveit_config/config/kinematics.yaml

src/gem_cutter_moveit_config/config/joint_limits.yaml

src/gem_cutter_moveit_config/config/moveit_controllers.yaml

src/gem_cutter_moveit_config/config/ros2_controllers.yaml

src/gem_cutter_moveit_config/config/gem_cutter_arm.ros2_control.xacro

3. Launch Files

src/gem_cutter_moveit_config/launch/demo.launch.py

src/gem_cutter_moveit_config/launch/setup_assistant.launch.py

src/gem_cutter_gazebo/launch/sim_with_moveit.launch.py

Running Major Commands

1. Generate URDF from XACRO

2. Launch MoveIt Setup Assistant

3. Rebuild the Workspace

4. Launch MoveIt Demo

5. Visualize Robot in RViz (without MoveIt)

6. Launch Gazebo Simulation with MoveIt

7. Launch Gazebo Simulation Only

Robot Description (URDF)

Physical Hardware Setup

URDF Structure

Joint Configuration

Link Chain

Coordinate Frames

Physical Properties

Key Design Features

MoveIt Configuration

What is MoveIt?

Configuration Components

1. Planning Groups (gem_cutter_arm.srdf)

2. End Effector

3. Virtual Joint

4. Disabled Collisions

5. Group States (Named Poses)

Planning Pipeline

Controller Integration

Kinematics Solver (KDL)

What is KDL?

KDL Kinematics Plugin

Configuration (kinematics.yaml)

How KDL IK Works

Advantages of KDL

Limitations

Alternative Solvers

Arm Configuration Details

Joint Limits Explained

Joint 1 (Base Yaw)

Joint 2 (Shoulder Pitch)

Joint 3 (Elbow Pitch)

Joint 4 (Wrist Pitch)

Joint 5 (Wrist Roll)

Joint 6 (Tool Yaw)

Dynamics Parameters

Workspace Analysis

Mass Distribution

Inertia Properties

Usage Examples

Example 1: Visualize Robot Model

Example 2: Plan and Execute Motion

Example 3: Use Named Poses

Example 4: Programmatic Motion Planning

Example 5: Gazebo Simulation

Troubleshooting

`src/gem_cutter_description/urdf/gem_cutter_arm.urdf.xacro`

`src/gem_cutter_description/urdf/materials.xacro`

`src/gem_cutter_moveit_config/config/gem_cutter_arm.srdf`

`src/gem_cutter_moveit_config/config/kinematics.yaml`

`src/gem_cutter_moveit_config/config/joint_limits.yaml`

`src/gem_cutter_moveit_config/config/moveit_controllers.yaml`

`src/gem_cutter_moveit_config/config/ros2_controllers.yaml`

`src/gem_cutter_moveit_config/config/gem_cutter_arm.ros2_control.xacro`

`src/gem_cutter_moveit_config/launch/demo.launch.py`

`src/gem_cutter_moveit_config/launch/setup_assistant.launch.py`

`src/gem_cutter_gazebo/launch/sim_with_moveit.launch.py`

1. Planning Groups (`gem_cutter_arm.srdf`)

Configuration (`kinematics.yaml`)