DEXTEROUS MANIPULATION

The world of dexterous hands.

Compare hardware. Discover applications. Share what works. An open reference and community for dexterous manipulation.

RUKA-v2

ruka-hand-v2

A later RUKA design with wrist and finger-abduction capabilities and accompanying control tools.

What you can explore

Inspect the revised mechanism, encoder or motion-capture workflows and calibration instructions.

Before you use it

This is a different hardware revision from the original RUKA. Do not mix its motor configuration, parts or calibration files with the earlier design.

Original contributors

Xinqi Liu, Ruoxi Hu and RUKA-v2 collaborators

License / access: Code: MIT · data, models and dependencies may have separate terms

Original code & documentation

FROM REFERENCE TO FIRST EXPERIMENT

RUKA-v2: check the software and calibration before moving the hand

INPUTUSB configuration, motor mapping and calibrated encoder endpoints
OUTPUTConfiguration checks, then supervised hardware control
Environment
Python 3.10 / Dynamixel control / optional learning submodules
Embodiment
RUKA-v2 tendon-driven hand; build-specific left/right calibration

What you need

Clone the official repository with submodules and use its ruka_hand environment. Start with file inspection while the hand is disconnected. The controller connects to the serial port and writes motor settings during construction, so creating Hand(...) is not a read-only check.

First useful check

Compare the script flags and calibration paths with the source at your pinned commit, then inspect the files without importing the hardware controller.

A small first experiment

  1. Capture the software revision

    Use the upstream installation sequence and retain the main and submodule revisions. Keep this installation separate from other robot-control environments. A cloned submodule is not proof that its hardware, data or checkpoints are configured.

    git clone --recurse-submodules https://github.com/ruka-hand-v2/RUKA-v2
    cd RUKA-v2
    git rev-parse HEAD
    git submodule status
    conda env create -f environment.yml
    conda activate ruka_hand
    python -m pip install -r requirements.txt
    python -m pip install -e .
    Repository installation →
  2. Verify side, port and motor mapping offline

    Inspect ruka_hand/utils/constants.py. The active finger-to-motor map is labeled for the right v2 hand; left-v2 and v1 maps appear separately in comments. Setting the USB side alone does not establish that every mapping matches a left-hand build. The checked-in USB paths are examples, not your device identifiers.

    Side and port constants →
  3. Check the calibration file format

    At the reviewed commit, both calibrate_motors.py and Hand load/save endpoints under curl_limits/, despite the README mentioning motor_limits/. Run this original read-only checker from the repository root after obtaining calibration files for the exact build. Equal endpoints are flagged for review, not automatically replaced.

    from pathlib import Path
    import numpy as np
    
    side = "right"  # change explicitly for the build being inspected
    root = Path("curl_limits")
    limits = {}
    for kind in ("curl", "tension"):
        path = root / f"{side}_{kind}_limits.npy"
        values = np.load(path, allow_pickle=False)
        if values.shape != (16,):
            raise ValueError(f"{path}: expected 16 motor values, got {values.shape}")
        if not np.isfinite(values).all():
            raise ValueError(f"{path}: contains non-finite values")
        if ((values < 0) | (values > 4095) | (values != np.floor(values))).any():
            raise ValueError(f"{path}: expected integer encoder values in 0..4095")
        limits[kind] = values
        print(path, "format OK")
    unchanged = np.flatnonzero(limits["curl"] == limits["tension"])
    print("Equal endpoint indices to review:", unchanged.tolist())
    print("Format check only; does not validate tendon tension or safe motion")
    Actual calibration loading path →
  4. Use the exact flags when commissioning is ready

    The reset script accepts --hand_type (underscore); the calibrator accepts --hand-type (hyphen). Reset repeats movement toward the tensioned position; calibration also drives motors. Read the scripts and assembly procedure first, verify the build-specific endpoints and stopping method, and perform supervised commissioning before teleoperation.

    Reset parser and repeated-motion loop →
  5. Separate optional teleoperation and learning paths

    The webcam script teleop_mediapipe.py selects camera index 1 and creates its retargeting controller before main(). It sends commands to the hand; it is not a camera-only preview. Review camera selection, calibration and controller side before use. The encoder instructions and BAKU/Franka workflows need their own hardware and data setup.

    Optional workflows and upstream documentation →
  6. Keep the hardware and software evidence together

    Use the RUKA-v2 hand record for hardware context, then record your serial-port mapping, calibration provenance, firmware and a first supervised observation log. A simulation model or successful package import cannot substitute for this record.

    RUKA-v2 hardware record →

What to record

  • Main/submodule revisions, exact hand side and calibration source are written down.
  • Both endpoint arrays pass the format check; their physical validity is separately established for the build.
Common problems and what to check
Reset rejects --hand-type
The reviewed reset parser uses --hand_type. Calibration uses the hyphenated form; inspect the exact script when updating versions.
Calibrated files appear to be ignored
Check curl_limits/<side>_curl_limits.npy and <side>_tension_limits.npy, the actual source paths. The controller has fallback values; do not treat a successful startup as proof that your files loaded.
A left-hand selection still behaves incorrectly
Review the active finger-to-motor map as well as USB_PORTS; the mapping is not automatically selected by side in the reviewed constants file.
A quick connection check moves hardware
Hand construction connects and configures motors. Use static file checks first, and follow the build commissioning procedure before invoking control scripts.

Where it stops

The reviewed README and code differ on some flags and paths. This guide identifies those differences; it is not a tested commissioning procedure for a particular build. Physical assembly, tendon setup and control limits need the hardware documentation and supervision.

Public documentation and source reviewed; no hardware or benchmark reproduction · reviewed 2026-10-24. Record the exact source revision when reproducing it.

Keep exploring

RUKA

A tendon-driven research hand with design, calibration and control resources.

MIDAS Hand API

Python control, homing and tactile-sensor tools for the MIDAS hand.

Editorial reference · checked 2026-10-24

Start a discussion

Published posts are public. First contributions are reviewed. Only share material you have permission to disclose.

Report a post