Revo-Retargeting

ROS 2 Humble workspace for using MANUS gloves to teleoperate BrainCo Revo2 and Revo3 hands.

If you only use one hand model, finish "Shared Setup" first, then follow the Revo2 or Revo3 section.

Shared Setup

Python 3.10 is recommended:

conda create -n revo_retargeting python=3.10 -y
conda activate revo_retargeting
python -m pip install -r requirements.txt

Source ROS in each new terminal:

source /opt/ros/humble/setup.bash

The Revo2 / Revo3 startup scripts prefer tmux split panes in interactive terminals, so driver, MANUS publisher, and retarget logs stay separated. Press Ctrl-b d to detach, and stop the whole group with tmux kill-session -t <session>. To temporarily use the old single-terminal output:

REVO_USE_TMUX=0 ./scripts/teleop.sh revo2 right

Revo2 Quick Start

Revo2 uses ros2_control and velocity control. Install the ROS2 control packages first:

sudo apt-get install -y ros-humble-ros2-control ros-humble-ros2-controllers ros-humble-xacro ros-humble-robot-state-publisher

Build Revo2:

python -m colcon build --symlink-install --packages-select \
  manus_ros2_msgs manus_ros2 \
  revo2_description revo2_driver revo2_retarget
source install/setup.bash

Smoke-test the retarget node with simulated MANUS input:

./scripts/sim_retarget.sh revo2 right

Start real teleoperation with one hand first:

./scripts/teleop.sh revo2 right

After one hand is confirmed, run both:

./scripts/teleop.sh revo2 both

Start only the Revo2 driver:

./scripts/start_driver.sh revo2 right

Before using real Revo2 hardware, confirm the velocity controller is active and JointState feedback is fresh:

ros2 control list_controllers -c /revo2_right/controller_manager
ros2 topic echo /revo2_right/revo2_joint_state/joint_states --once

Revo3 Quick Start

Revo3 uses the Stark SDK control path. Build Revo3:

python -m colcon build --symlink-install --packages-select \
  manus_ros2_msgs manus_ros2 \
  revo3_description ros2_stark_interfaces ros2_stark_controller revo3_retarget
source install/setup.bash

Smoke-test the retarget node with simulated MANUS input:

./scripts/sim_retarget.sh revo3 right

Start real teleoperation with one hand first:

./scripts/teleop.sh revo3 right

After one hand is confirmed, run both:

./scripts/teleop.sh revo3 both

Start only the Revo3 driver:

./scripts/start_driver.sh revo3 right

Before using real Revo3 hardware, confirm the serial port, slave ID, and bc-stark-sdk environment. Configuration files:

src/ros2_stark_controller/config/params_left.yaml
src/ros2_stark_controller/config/params_right.yaml

Common Commands

Build everything:

python -m colcon build --symlink-install
source install/setup.bash

Check dependencies:

./scripts/check_system_deps.sh revo2
./scripts/check_system_deps.sh revo3

Calibrate MANUS:

./scripts/calibrate_manus.sh right
./scripts/calibrate_manus.sh left

Runtime Shape

MANUS input:

MANUS SDK / manus_ros2
  -> /manus_glove_0, /manus_glove_1

Revo2:

revo2_retarget
  -> /revo2_left/right/joint_forward_vel_controller/commands
  <- /revo2_left/right/revo2_joint_state/joint_states

Revo2 stops sending velocity commands when feedback is stale.

Revo3:

revo3_retarget
  -> /revo3/left|right/set_motor_multi
  -> ros2_stark_controller

Packages

Shared:

src/manus_ros2_msgs        MANUS ROS 2 messages
src/manus_ros2             MANUS SDK bridge

Revo2:

src/revo2_retarget   Revo2 retarget and velocity output
src/revo2_driver           Revo2 ros2_control hardware driver
src/revo2_description      Revo2 URDF/xacro/meshes

Revo3:

src/revo3_retarget   Revo3 retarget node
src/revo3_description      Revo3 MuJoCo XML and meshes
src/ros2_stark_controller  Revo3 Stark SDK hardware node
src/ros2_stark_interfaces  Revo3 command/status interfaces