Piper Hardware Setup

Piper Hardware Setup#

This procedure prepares two physical AgileX Piper arms for HandUMI real teleoperation. Complete the robot-independent HandUMI Setup and Calibration first.

Safety and prerequisites#

Before connecting or commanding the arms:

  • Clear the complete arm workspace and keep the emergency stop reachable.

  • Power both arms, but stop every other process that may use their CAN buses.

  • Install the Piper backend with uv sync --extra piper.

  • Connect one USB-to-CAN adapter per arm.

  • Verify tracking and motion mapping in simulation before enabling hardware.

Install and map the CAN adapters#

Run the guided hardware setup:

uv sync --extra piper
handumi setup --robot piper --device meta \
  --skip-feetech-map --skip-feetech-calibration

The wizard maps the right Piper adapter first and the left adapter second. It stores the machine-local result under robots.piper.can in configs/rig.yaml. Follow the prompts to disconnect and reconnect adapters so that each physical side is identified correctly.

Use --skip-can-map only after verifying an existing mapping. Rerun the wizard whenever adapters, USB ports, or arm assignments change.

Verify CAN and troubleshoot the mapping#

Check that both arms are powered, both adapters are present, and no other process owns the CAN interfaces. If an interface is down or bus-off, stop teleoperation, inspect power and wiring, and rerun the guided setup from the previous section.

Do not continue to real motion until the wizard identifies both physical sides and communication is stable.

Calibrate the Piper gripper closed positions#

Calibrate each Piper gripper before the first real teleoperation, after replacing a gripper, or whenever a physically closed gripper reports a non-zero or negative position. From the repository, run:

uv run handumi calibrate piper-grippers

The command connects both Piper controllers but does not send arm-joint targets. For each side, it disables only that gripper motor and continuously prints its raw feedback. Close the gripper gently and consistently against its physical stop, then press Enter. The value visible at that instant becomes the logical opening=0.0 for that side; it is measured during the procedure and is not hardcoded.

To calibrate only one side:

uv run handumi calibrate piper-grippers --side left
uv run handumi calibrate piper-grippers --side right

The per-machine result is stored outside the repository at ~/.cache/handumi/piper_grippers.yaml (or under $XDG_CACHE_HOME when set). Teleoperation uses the captured value both to normalize physical feedback and as the closed command target. For example, if the captured raw value is -3000 um, subsequent diagnostics report it as calibrated 0.000 mm and a normalized opening of 0.000000, while retaining -3000 um as the raw value.

You can verify both grippers without running arm teleoperation:

uv run python tests/real/test_piper_gripper_diagnostic.py

With each gripper physically closed, expect estado=CERRADO, Piper=0.000000, and calibrado=0.000 mm. Press Ctrl+C to stop the monitor.

First real teleoperation#

Start with simulation and the same robot profile:

handumi teleop --device meta --robot piper

After tracking, calibration, and simulated motion behave correctly, validate one physical arm first:

handumi teleop-real --device meta --robot piper --side right

Keep the emergency stop reachable and confirm that the right controller moves only the right arm. Stop and correct the CAN mapping if the wrong side moves. Validate the left side separately before enabling both arms:

handumi teleop-real --device meta --robot piper --side left
handumi teleop-real --device meta --robot piper --side both

For shared controls, safety behavior, and tracking semantics, continue with Physical Robot Teleoperation. For common failures, see Troubleshooting.