Skip to content

StarArm102 Robotic Arm - ROS2 MoveIt Guide

StarArm102 Manipulator - ROS2 MoveIt Guide

StarArm102 Robotic Arm

📋 Table of Contents

🔧 System Requirements

System Information

No LSB modules are available.

Distributor ID: Ubuntu
Description:    Ubuntu 22.04.5 LTS
Release:        22.04
Codename:       Jammy
ROS2:           Humble

📦 Installation Guide

1️⃣ Install ROS2 Humble

Chinese Guide:
ROS2 Humble Installation Guide

English Guide:
ROS2 Humble Installation

2️⃣ Install MoveIt2

sudo apt install ros-humble-moveit*

3️⃣ Install the Servo SDK library

sudo pip install pyserial
sudo pip install fashionstar-uart-sdk

4️⃣ Clone the StarArm102 packages

cd ~/
git clone https://github.com/servodevelop/Star-Arm-102.git
cd ~/Star-Arm-102/ROS2_HUMBLE
colcon build
echo "source ~/Star-Arm-102/ROS2_HUMBLE/install/setup.bash" >> ~/.bashrc
source ~/.bashrc

Note

After compilation, run source / source to make the environment variables take effect.

📦 Package Overview

Package Description
robo_driver Robotic arm hardware driver node responsible for communicating with the servo
stararm102_description URDF model description files for the robotic arm
stararm102_gazebo Gazebo simulation environment configuration
stararm102_moveit_config MoveIt2 motion planning configuration
stararm102_controller Robotic arm controller node
arm_moveit_read End-effector pose reading demo node
arm_moveit_write End-effector pose writing demo node
arm_read_pose Real-time pose reading node
ros2_bag_recorder Teaching trajectory recording and playback
robo_interfaces Custom ROS2 interface definitions

🚀 MoveIt2 Quick Start

🎮 Using the Virtual Robotic Arm

Launch RViz2 for path planning and visualized control of the virtual robotic arm.

Launch command:

ros2 launch stararm102_moveit_config demo.launch.py

After startup, you can do the following in the RViz2 interface:

  • Use the Motion Planning panel for path planning.
  • Drag the interactive markers to position the end effector.
  • Select a Planning Group to control different joint groups.
  • Click Plan to preview the planned path.
  • Click Execute to run the planned trajectory.

🦾 Using the Real Robotic Arm

Connect the real robotic arm and perform actual control.

Terminal 1: Launch the arm hardware driver

Important

After the driver starts, the arm will move to its zero position. Make sure there are no obstacles nearby.

ros2 launch stararm102_moveit_config driver.launch.py

Terminal 2: Launch MoveIt2

ros2 launch stararm102_moveit_config actual_robot_demo.launch.py

✅ At this point, you can control the real robotic arm from the virtual robotic arm.

📐 End-Effector Pose Read/Write Demo

This example shows how to read and write the pose information of the robotic arm end effector.

Terminal 3: Launch the pose read/write demo

ros2 launch stararm102_moveit_config moveit_write_read.launch.py

This example will:

  • Display the current end-effector pose (position and orientation) in real time.
  • Demonstrate how to set a target pose and execute the motion.
  • Output joint angles and Cartesian coordinate information.

📡 Pose Topic Publisher Demo

Send a target pose through a ROS2 topic to control the robotic arm.

Terminal 4: Launch the pose topic publisher

# 运行话题发布节点
ros2 run arm_moveit_write topic_publisher

This node continuously publishes target poses to a topic, and MoveIt2 receives them to drive the robotic arm to the target position.

🎯 MoveIt2-Gazebo Simulation Demo

Test robotic arm control in the Gazebo physics simulation environment.

Tip

  • After closing the Gazebo GUI, it is recommended to fully terminate it with pkill -9 -f gazebo
  • Before running this demo, close all other running nodes

Install Gazebo

sudo apt install gazebo
sudo apt install ros-humble-moveit*
sudo apt install -y ros-humble-gazebo-ros-pkgs ros-humble-gazebo-ros

Terminal 1: Launch the Gazebo GUI

ros2 launch stararm102_gazebo stararm102_gazebo.launch.py

After Gazebo starts, you will see the StarArm102 robotic arm inside the simulation environment.

Terminal 2: Launch the MoveIt2 interface

ros2 launch stararm102_moveit_config gazebo_demo.launch.py

✅ You can now plan paths in RViz2, and the robotic arm will execute the motion inside Gazebo.

🎓 Robotic Arm Teaching Mode

Record and replay the robotic arm trajectory.

Tip

  • If you need to re-record a trajectory, delete the record-test folder or create a new recording folder such as record-test1
  • In teaching mode, the arm driver needs to be unlocked

Terminal 1: Launch the arm hardware driver in teaching mode

ros2 run robo_driver driver --ros-args -p lock:='disable'

Important

Setting lock:='disable' unlocks the joints, allowing you to manually drag the robotic arm for teaching.

Terminal 2: Record the arm trajectory

Press Enter once to start recording, then press Enter again to stop. Use the dataset parameter to specify the save path.

ros2 run ros2_bag_recorder bag_recorder --ros-args -p dataset:=star/record-test

Steps:

  1. Run the command and press Enter to start recording.
  2. Manually drag the robotic arm to the target position.
  3. Press Enter again when finished.
  4. The trajectory data will be saved to the star/record-test folder.
ros2 bag play ./star/record-test

The robotic arm will automatically replay the recorded trajectory.

📊 Joint Configuration

StarArm102 uses a 6-DOF robotic arm plus a rotating gripper:

Joint Type Angle Range Description
Joint1 revolute -130° ~ 130° Base rotation
Joint2 revolute -90° ~ 90° Shoulder pitch
Joint3 revolute -90° ~ 90° Elbow pitch
Joint4 revolute -90° ~ 90° Wrist rotation
Joint5 revolute -90° ~ 90° Wrist pitch
Joint6 revolute -130° ~ 130° Wrist yaw
joint7_left revolute -90° ~ 90° Rotating gripper (active)
joint7_right revolute -90° ~ 90° Rotating gripper (linked)

📝 Rotating gripper note: joint7_right is the mimic joint and automatically mirrors joint7_left in reverse.

❓ FAQ

RViz2 screen flickering

If the RViz2 window flickers, try the following command:

export QT_AUTO_SCREEN_SCALE_FACTOR=0

Then restart RViz2.

Gazebo fails to start

If Gazebo fails to start, first check whether there are leftover processes:

killall -9 gazebo gzserver gzclient 2>/dev/null || true

Then run the launch command again.

Build errors

If you encounter build errors, make sure that:

  1. All dependencies are installed: sudo apt install ros-humble-moveit*
  2. The ROS2 environment has been sourced correctly: source /opt/ros/humble/setup.bash
  3. You are building in the correct directory: cd ~/Star-Arm-102/ROS2_HUMBLE

The robotic arm cannot connect

If the robotic arm cannot connect, check:

  1. Whether the USB serial port connection is working properly
  2. Whether the serial port permissions are correct: sudo chmod 666 /dev/ttyUSB0
  3. Whether the servo SDK has been installed correctly

Teaching trajectory playback is abnormal

If the robotic arm behaves abnormally during teaching trajectory playback:

  1. Check whether the URDF configuration is correct.
  2. Confirm the mimic configuration of joint7_left and joint7_right.
  3. Check whether the joint_states topic data is correct.

📞 Technical Support

If you run into any issues, please visit:

  • GitHub repository: Star-Arm-102
  • Submit an Issue for support
**StarArm102 - Making robotic arm control simpler** *StarArm102 - Making robot arm control simpler*