grasp_synergy_adapter

A ROS 2 adapter for controlling multi-finger hands through predefined grasp synergies. Each grasp exposes a JointTrajectoryController-compatible topic and action interface with a single normalized coordinate:

• 0.0: preparation posture
• 1.0: final grasp posture

What it does

Grasp profiles define piecewise-linear paths through joint space. The adapter converts normalized commands into joint trajectories, preserves intermediate knots during opening and closing, and projects measured joint feedback onto the selected grasp path.

Grasp command: profile + normalized coordinate
                      │
                      ▼
           grasp_synergy_adapter
                      │
                      ▼
      ros2_control JointTrajectoryController
                      │
                      ▼
                 Robot hand

The adapter runs as a regular ROS 2 node, not a ros2_control controller or hardware interface. Run one instance per physical hand or downstream controller.

Installation

Supported platform: ROS 2 Jazzy on Ubuntu 24.04.

Binary packages are not yet published. Build from source:

mkdir -p ~/ros2_ws/src
git clone https://github.com/shkwon98/grasp_synergy_adapter.git \
  ~/ros2_ws/src/grasp_synergy_adapter

cd ~/ros2_ws
source /opt/ros/jazzy/setup.bash
rosdep install --from-paths src --ignore-src -r -y
colcon build --packages-select grasp_synergy_adapter
source install/setup.bash

Quick start

1. Define a grasp profile

Save the following as grasp_profiles.yaml, replacing the joint names and positions with values appropriate for your hand:

/**/grasp_synergy_adapter:
  ros__parameters:
    synergy_joint: synergy
    joints: [finger_a_joint, finger_b_joint]
    state_timeout_sec: 0.5
    grasp_names: [pinch]

    grasps:
      pinch:
        knot_names: [pre_grasp, intermediate, grasp]
        knots:
          pre_grasp:
            coordinate: 0.0
            positions: [0.0, 0.0]
          intermediate:
            coordinate: 0.5
            positions: [0.8, 0.4]
          grasp:
            coordinate: 1.0
            positions: [1.0, 1.0]

Each positions array follows the order of joints. Use radians for revolute joints and metres for prismatic joints. Adjacent knots must describe different physical poses.

To configure additional grasps, add their names to grasp_names and provide matching blocks under grasps. Each profile gets its own topic and action endpoints at startup.

See config/example.yaml for the annotated schema.

2. Start the adapter

With your hand’s JointTrajectoryController running, start the adapter and remap all three downstream endpoints. This example uses /hand_controller:

```bash ros2 run grasp_synergy_adapter grasp_synergy_adapter
–ros-args
–params-file /absolute/path/to/grasp_profiles.yaml
-r target/joint_trajectory:=/hand_controller/joint_trajectory \

File truncated at 100 lines see the full file

Changelog for package grasp_synergy_adapter

Forthcoming

• Add configurable grasp profiles with piecewise-linear synergy knots.
• Expose standard JointTrajectory and FollowJointTrajectory endpoints per grasp.
• Forward commands to a remappable downstream JointTrajectoryController.
• Relay normalized action feedback, results, and cancellation.
• Contributors: Sunghyun Kwon