GHand-ROS2

简体中文

GHand-ROS2 is a ROS 2 control stack for the GHand five-finger dexterous hand, built on the ros2_control framework. It supports Gazebo physical simulation, MoveIt 2 motion planning, and multiple real-hardware communication backends (EtherCAT, CANFD, RS485), enabling algorithm development and visualization verification without hardware.

🎬 Demo

MoveIt Motion Planning

Gazebo Simulation

✨ Features

• Multi-backend hardware drivers

  • Supports EtherCAT, CANFD, and RS485 communication.
  • Switch backend and device configuration with a single profile argument.
  • Unified hardware abstraction layer with consistent interfaces for real and mock hardware.

• ros2_control integration

  • Implements hardware_interface::SystemInterface lifecycle management.
  • Cyclic read/write of joint commands and states; supports position, velocity, and effort control modes.

• Custom broadcasters

  • joint_status_broadcaster publishes joint status and error codes.
  • tactile_broadcaster publishes tactile resultant force and distributed forces.

• Simulation and motion planning

  • Built-in Gazebo Harmonic launch files and ROS 2 Control plugin configuration.
  • Built-in MoveIt 2 configuration for trajectory planning and execution in RViz.

• Scenario-based launch

  • ghand_hardware_interface handles real / mock hardware launch.
  • ghand_gazebo handles physical simulation launch; the two are decoupled.

📖 Official Documentation

For detailed technical specifications, API reference, and tutorials, see the GHand Dexterous Hand Documentation.

📑 Table of Contents

• Features
• Official Documentation
• System Requirements
• Dependencies
• Installation
• Quick Start
• Demo
• Control Interfaces
• Directory Structure
• Open Source and Ecosystem
• Changelog
• Support and Feedback
• License

💻 System Requirements

Supported Platforms

Platform	Requirement
Operating System	Ubuntu 24.04 LTS
ROS 2	Jazzy Jalisco
Compiler	GCC 11+ (C++17 support)
Python	3.10 or newer
Simulator	Gazebo Harmonic (required for physical simulation)

🔧 Dependencies

Required Dependencies

sudo apt update
sudo apt install -y \
  ros-${ROS_DISTRO}-ros2-control \
  ros-${ROS_DISTRO}-ros2-controllers \
  ros-${ROS_DISTRO}-moveit \
  ros-${ROS_DISTRO}-joint-state-publisher-gui \
  ros-${ROS_DISTRO}-rviz2

Replace ${ROS_DISTRO} with jazzy.

Optional Hardware Dependencies

Only needed when connecting to real hardware; pure simulation development can skip these.

Backend	Dependency / Library	Notes
EtherCAT	libsoem / SOEM	Build from source; CMake auto-detects
RS485	libmodbus	System package
CANFD	ZLG CAN SDK	ZLG USB-CANFD library

📦 Installation

1. Environment Setup

# Verify ROS 2 environment
echo $ROS_DISTRO  # should output: jazzy

# Create workspace
mkdir -p <workspace>/src
cd <workspace>

Note: Replace <workspace> with your workspace path, e.g., ~/ghand-ros2.

2. Clone the Repository

# Enter workspace src directory
cd <workspace>/src

# Clone the main repository
git clone https://gitee.com/glitech/ghand-ros2.git

3. Import External Dependencies

The URDF/Xacro and STL meshes for ghand_description are provided by external repositories. Import them via ghand.repos:

cd <workspace>/src
vcs import . < ghand-ros2/ghand.repos --recursive --skip-existing

Note: If vcs is not installed, install it first:

sudo apt-get install python3-vcstool

4. Build

cd <workspace>
colcon build --symlink-install
source install/setup.bash

For mock-hardware-only builds, you can also use:

cd <workspace>
./src/ghand-ros2/build.sh
source install/setup.bash

🚀 Quick Start

Launch Simulation (No Hardware Required)

ros2 launch ghand_hardware_interface ghand.launch.py use_mock_hardware:=true

Simulation mode uses mock_components/GenericSystem and requires no hardware devices.

Launch Real Hardware

ros2 launch ghand_hardware_interface ghand.launch.py profile:=ethercat_default ifname:=enx000000000000

Replace enx000000000000 with your actual EtherCAT network interface name. Use ip link to list available interfaces.

Available communication profiles are located at ghand_hardware/ghand_hardware_interface/config/profiles/ and include ethercat_default, rs485_left, rs485_right, canfd_usb, zqwl_canfd_left, and zqwl_canfd_right.

Launch MoveIt 2

ros2 launch ghand_moveit_config moveit.launch.py

For EtherCAT real hardware, also provide ifname:

ros2 launch ghand_moveit_config moveit.launch.py use_sim:=false profile:=ethercat_default ifname:=enx000000000000

Launch Gazebo Simulation

ros2 launch ghand_gazebo ghand_gazebo.launch.py

After launch, you can plan trajectories in RViz using the MotionPlanning plugin; trajectories are sent to the joint_trajectory_controller running in Gazebo.

🎮 Control Interfaces

Topic Interfaces

• Joint States: /joint_states (sensor_msgs/JointState)
• Joint Status / Error Codes: /joint_status_broadcaster/joint_status (hand_msgs/JointStatus)
• Tactile Feedback: /tactile_broadcaster/tactile_data (hand_msgs/TactileData)
• Trajectory Commands: /joint_trajectory_controller/joint_trajectory (trajectory_msgs/JointTrajectory)

Action Interfaces

• Trajectory Execution: /joint_trajectory_controller/follow_joint_trajectory (control_msgs/action/FollowJointTrajectory)

Control Examples

Start the hardware or simulation first:

# mock hardware
ros2 launch ghand_hardware_interface ghand.launch.py use_mock_hardware:=true

# or Gazebo simulation
ros2 launch ghand_gazebo ghand_gazebo.launch.py

Open Palm

ros2 topic pub --once /joint_trajectory_controller/joint_trajectory \
  trajectory_msgs/msg/JointTrajectory \
  '{
    joint_names: ["thumb_mcp", "thumb_tmc_fe", "thumb_tmc_aa", "thumb_tmc_ps",
                  "index_pip", "index_mcp", "index_mcp_aa",
                  "middle_pip", "middle_mcp",
                  "ring_pip", "ring_mcp",
                  "little_pip", "little_mcp"],
    points: [{
      positions: [0.0, 0.0, 0.349, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0],
      time_from_start: {sec: 1}
    }]
  }'

Make Fist

ros2 topic pub --once /joint_trajectory_controller/joint_trajectory \
  trajectory_msgs/msg/JointTrajectory \
  '{
    joint_names: ["thumb_mcp", "thumb_tmc_fe", "thumb_tmc_aa", "thumb_tmc_ps",
                  "index_pip", "index_mcp", "index_mcp_aa",
                  "middle_pip", "middle_mcp",
                  "ring_pip", "ring_mcp",
                  "little_pip", "little_mcp"],
    points: [{
      positions: [0.5, 0.0, 0.349, 0.5, 1.2, 1.2, 0.0, 1.2, 1.2, 1.2, 1.2, 1.2, 1.2],
      time_from_start: {sec: 2}
    }]
  }'

Monitoring and Debugging

# List all running nodes
ros2 node list

# List all controllers
ros2 control list_controllers

# List all topics
ros2 topic list

# Monitor joint states
ros2 topic echo /joint_states

📁 Directory Structure

GHand-Ros2/
├── ghand_hardware/
│   ├── ghand_hardware_interface/   # Hardware interface and comm drivers
│   ├── hand_controllers/           # Custom broadcasters
│   └── hand_msgs/                  # Custom message types
├── ghand_moveit_config/            # MoveIt 2 configuration
├── ghand_gazebo/                   # Gazebo physical simulation
├── ghand_description/              # Robot description model
├── CHANGELOG.md                    # Version history
├── LICENSE                         # Apache License 2.0
├── README.md                       # This file
└── README_CN.md                    # Chinese README

🌐 Open Source and Ecosystem Resources

• GLI Open Source Center: GLI SDK GitHub Organization
• Official Documentation: GHand Dexterous Hand Documentation
• C++ SDK: GHand-Cpp-SDK
• Python SDK: GHand-Python-SDK

📋 Changelog

See CHANGELOG.md.

📞 Support and Feedback

• 📋 Technical support: For project-related questions, please open an Issue in this repository.
• 📧 General inquiries: support@glitech.com

📄 License

This project is open-sourced under the Apache License 2.0.

Copyright © 2026 GHand ROS2 Maintainers.