Skip to content

Troubleshooting ​

An attachment does not fit ​

Print one cell and one attachment base using the same material and profile. Check for elephant's foot, warping, or excess material before modifying the CAD. If sanding is required, apply it consistently and record it.

A threaded component binds ​

Remove stringing and debris, then test the matching calibration piece. Keep the part aligned with the thread axis and do not force initial engagement. Record sanding or lubrication because either can change task resistance.

An attachment moves during a trial ​

Stop if continuation is unsafe. Preserve the trial result, describe the displacement in notes, and reseat the attachment before continuing. For repeated release, verify cell tolerances and mounting orientation.

A printed part breaks ​

Record the trial as it occurred. Photograph the damage when useful, replace the component with the same print profile, and note the replacement. Do not substitute an unreported rerun.

Completion time appears as a date ​

Format the spreadsheet column as a plain number and enter decimal seconds without units. Use 12.9, not 12.9 s or a clock value.

Failed trials have no time ​

This is expected. completion_time_s is only populated for successful trials. Use outcome=timeout for a trial that reaches the time limit.

Simulation geometry loads at the wrong scale ​

Verify the asset units and the loader's unit conversion. Check both visual and collision geometry before changing the global scene scale.

A simulation joint moves in the wrong direction ​

Inspect the joint axis, parent-child order, and initial pose. Compare the full motion with the physical mechanism, not only the rendered rest configuration.

Simulation contact is unstable ​

Begin with one environment and a conservative timestep. Inspect collision geometry, penetration at reset, solver settings, drive gains, and mass ratios. The supplied physical properties are nominal. Identify them for the printed mechanism when studying sim-to-real correspondence.

An Isaac Lab asset cannot be found ​

The simulation repository uses Git submodules. From the repository root, initialize or update them with:

bash
git submodule update --init --recursive

This initializes the pinned dependencies, including HiveBoard assets, Isaac Lab, cuRobo, and the DynaArm description. Newton USD files also need to be generated locally. Check them with:

bash
uv run python scripts/generate_newton_usd.py --verify-only

Follow the asset-generation instructions to create missing files. ANYmal has an additional robot-assembly generator. The --skip-conversion option cannot replace conversion on a fresh clone.

An Isaac Lab task is not registered ​

List all registered tasks without launching the simulator:

bash
uv run python scripts/record_all_envs.py --all --list

Use the exact Isaac-HiveBoard-* identifier printed by the script. Robot tokens are case-sensitive, including Anymal. Light-bulb tasks provide both Lamp-v0 and Lamp-Play-v0 variants for Spot, Franka, and ANYmal. The current Franka ball-valve task uses Franka-BallValve, replacing the earlier Franka-LeverValve identifier.

If imports fail after updating the repository, run git submodule update --init --recursive and uv sync --python 3.12 from its root. Continue using uv run for subsequent commands.

The command editor does not open in the browser ​

Start the editor with an explicit port, for example uv run python scripts/command_edit.py --port 9080, and open http://localhost:9080 on the computer running it. Use the address printed by the editor if a different port was selected. See command editing for the complete workflow.

A simulation recording is missing ​

For batch recording, check summary.json and the per-task logs under videos/environments/<timestamp>/. Confirm that ffmpeg and ffprobe are on PATH. The default batch selection includes only -Play environments, including light bulb. Use --task to select one task explicitly, or --all to include all variants. See batch recording.

HiveBoard documentation