Troubleshooting

Troubleshooting#

Device or Port Missing#

handumi-setup-ports
lsusb
ls /dev/ttyACM* /dev/ttyUSB*

Reconnect one device at a time. Log out and back in after serial-group changes.

Adapter visible in lsusb but no serial port exists

Common Feetech adapters use the CH341 driver. Check the running kernel and installed module tree:

uname -r
modinfo ch341
ls /usr/lib/modules/$(uname -r)

If the module tree does not match the running kernel, reboot after the system update, reconnect the adapter, and rerun handumi-setup-ports.

Quest Does Not Stream#

Keep HandUMI Quest App in the foreground, confirm both devices share a network, update quest_ip in configs/rig.yaml, and wake both controllers.

PICO Does Not Stream#

Confirm the PC service and headset stream are running. For USB, check:

adb devices
adb reverse --list

Gripper Width Is Wrong#

Confirm side/port mappings, home at mid-travel, then recalibrate:

handumi-home-servos
handumi-calibrate-grippers calibrate

If left/right motion is swapped, correct the mapping in configs/rig.yaml; do not compensate by reversing calibration values. If a camera appears twice, test the first /dev/video* node associated with that physical device.

Recording Is Rejected#

Inspect meta/handumi_quality.json. The common causes are tracking loss, stale cameras, synchronization errors, frozen poses, large motion jumps, or an episode that is too short.

Replay Prints a CUPTI Traceback#

If JAX reports Unable to load cuPTI but replay continues, force the supported CPU path for the command:

JAX_PLATFORMS=cpu uv run handumi-replay-in-sim \
  --dataset-root outputs/20260714_224135 \
  --robot openarmv1 \
  --episode 0

This warning concerns optional CUDA profiling libraries, not the dataset or robot IK.

Viser Shows Trajectories but No Robot#

Messages such as Can't find meshes/visual/base_link.glb mean the URDF loaded but its visual asset paths did not resolve. Restart replay after updating the checkout. TRLC-DK1 meshes must exist under:

assets/trlc-dk1/meshes/visual/
assets/trlc-dk1/meshes/collision/

Run this check from the repository root:

JAX_PLATFORMS=cpu uv run python -c \
  "from handumi.robots.registry import load_embodiment; u=load_embodiment('trlc_dk1').load_urdf(load_meshes=True); print(len(u.scene.geometry))"

The current GLB assets expand to hundreds of internal submeshes; a nonzero count without Can't find messages confirms that the visuals loaded.

Piper CAN Is Down or BUS-OFF#

This applies only to physical Piper teleoperation. Check robot power and wiring, then follow the CAN checks in Piper Hardware Setup.

Piper Real Arms Do Not Start#

Test simulation first, verify both controllers are tracked, confirm CAN is up, and use --side right for the first hardware check. See First real teleoperation for the complete startup sequence.