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

Contributing

Bug reports and focused pull requests are welcome. Open an issue before a large change so its scope and interface impact can be agreed on first.

Development

Use ROS 2 Jazzy on Ubuntu 24.04. From the workspace root:

source /opt/ros/jazzy/setup.bash
rosdep install --from-paths src --ignore-src -r -y
colcon build --packages-select grasp_synergy_adapter
colcon test --packages-select grasp_synergy_adapter --event-handlers console_direct+
colcon test-result --test-result-base build/grasp_synergy_adapter --verbose

Keep changes narrowly scoped. New or changed behavior must include a regression test and corresponding documentation. Run clang-format on changed C++ files and keep the existing CMake formatting.

Pull requests

• Explain the problem and the behavior changed by the pull request.
• Note any ROS interface, parameter, configuration, or compatibility impact.
• Keep commits reviewable and free of generated build artifacts.
• Resolve test, lint, and documentation-build failures before requesting review.

Contributions are accepted under the Apache License 2.0.