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
RUKA-v2: check the software and calibration before moving the hand
- 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
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.
Repository installation →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 .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 →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.
Actual calibration loading path →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")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 →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 →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.
Keep exploring
RUKA
A tendon-driven research hand with design, calibration and control resources.
ORCA Hand Hardware
CAD, printable parts and assembly resources for ORCA hand variants.
MIDAS Hand API
Python control, homing and tactile-sensor tools for the MIDAS hand.
Editorial reference · checked 2026-10-24