thanhndv212/figaroh-plus/figaroh-start

FIGAROH Workspace — Start Here

_Arguments: say what you want to do (calibrate a robot, identify dynamics, generate optimal configs/trajectories, onboard a new robot, just get it running) and, if you have one, the robot name._

Paths. $FIGAROH_WS is the workspace root — the directory holding the

figaroh and figaroh-examples repos side by side. Set it once per shell:

export FIGAROH_WS="$(cd /path/to/your/workspace && pwd)".

When to Use

• The user says "set up FIGAROH", "how do I run this", "where do I start".
• A task is named (calibration / identification / optimal / new robot) but the

package, directory, config, or env is not yet established.

• You are about to cd or import and are not certain which of the two repos owns

the thing you need.

Run this skill's Orientation section, then hand off to the setup skill named in Dispatch. Do not start editing files before Dispatch — the most common failure in this workspace is doing correct work in the wrong repo.

Orientation — the two repos

Workspace root: $FIGAROH_WS/

These two are the whole picture. If the workspace directory happens to hold other checkouts, they are unrelated to FIGAROH — this skill set assumes and touches only figaroh/ and figaroh-examples/.

The two-repo rule. FIGAROH is one library plus one example repo, side by side. figaroh-examples imports figaroh from ../figaroh via an editable install — there is no vendored copy. After changing library code, re-run pip install -e . in figaroh/ (only needed if metadata/entry points changed; editable src picks up edits live).

Orientation — directories inside figaroh-examples

figaroh-examples/
  examples/<robot>/        # ← run scripts from HERE, never from repo root
    calibration.py         # entry points (not every robot has all of them)
    identification.py
    optimal_config.py
    optimal_trajectory.py
    update_model.py
    config/                # *_unified_config.yaml (current) + legacy *_config.yaml
    data/                  # CSV measurements in, .npz results out
    urdf/                  # the robot's URDF(s)
    utils/<robot>_tools.py # robot-specific subclasses of figaroh Base* classes
    results/runs/…         # timestamped archived runs
  models/                  # shared ROS description packages (meshes) — read-only
  examples/templates/      # base/manipulator/humanoid config templates
  validate.py              # the quality gate: tests + all example scripts

Two path facts every script depends on, and that break everything when violated:

1. Scripts use relative paths (config/x.yaml, urdf/x.urdf), so the working

directory must be examples/<robot>/.

1. Meshes resolve via package_dirs="../../models", which is only correct from

examples/<robot>/.

Orientation — what exists today

UR10 is the reference implementation. When you need a working example of anything, read examples/ur10/ first; examples/tiago/ second (it has the most scripts).

Dispatch

Beyond setup, this skill set hands off to the repos themselves: re-run with --verbose and work from the traceback when something breaks mid-run; library algorithms live in figaroh/src/figaroh/; the example suite and integration tests run from figaroh-examples/validate.py; packaging, CI, and docs live in figaroh/. Each repo's AGENTS.md and README.md carry the conventions for that work.

Always run figaroh-setup-env before any of the task setup skills unless a figaroh import has already succeeded in this session.

Fastest path to a working run (verify the toolbox before touching the user's robot)

conda activate figaroh-dev
cd $FIGAROH_WS/figaroh-examples/examples/ur10
python calibration.py --calibrate-only --no-plot

If that prints post-calibration RMSE, the toolbox is healthy and any later failure is in the user's model, config, or data — not the install. Use this as the bisect point.

Hard rules

• Conda env `figaroh-dev` is mandatory for every command in figaroh/ and

figaroh-examples/. It is defined by figaroh/environment.yml (Python 3.12) and is the only supported source of cyipopt. Ignore figaroh-examples/environment.yml — it names a figaroh-examples env that nobody uses.

• Never run example scripts from the repo root. cd examples/<robot> first.
• Never edit `figaroh-examples/models/`. Those are upstream ROS description

packages, mesh assets only.

• Write new configs in the unified format (tasks.<task>.* with extends:), not

the legacy flat format. Legacy is auto-detected for backward compatibility only.

• `examples/shared/` does not exist and is gitignored. Never import

examples.shared.*.

• The library uses the NullHandler logging pattern — never add print/root logging to

figaroh/src/. Example scripts may print freely.