grc_meta

setup

scripted setup

mkdir -p ws/src
git clone git@github.com:secorolab/grc_meta.git ws/src/grc_meta
ros_distro=jazzy
ws/src/grc_meta/script-setup ws "$ros_distro"

For a ROS Docker image or a machine without GitHub SSH configured, use HTTPS repository URLs:

GRC_GIT_TRANSPORT=https ws/src/grc_meta/script-setup ws "$ros_distro"

The setup script requires an existing ROS 2 distro at /opt/ros/$ros_distro. It checks for the required non-ROS system packages and, if any are missing, prints the apt-get install line and exits so you can install them (the only step needing sudo) and rerun. It then imports the workspace repositories, creates .venv, installs the Python workspace packages, builds STSTv4 (pinned, run against StringTemplate 4.3.4), runs colcon build, and writes ws/setup-grc.<ext> (.zsh when $SHELL is zsh, .bash otherwise).

Modes:

Flag	What it does
(none)	Full setup: import, fast-forward, rosdep, venv, stst, build, verify
--ff	Fast-forward repos and submodules only (skip rosdep/venv/stst/build)
--build	Rebuild only (skip import/ff/submodules — assumes already set up)

Example — fast-forward existing repos without rebuilding:

ws/src/grc_meta/script-setup --ff ws "$ros_distro"

Example — rebuild after pulling:

ws/src/grc_meta/script-setup --build ws "$ros_distro"

Run a model with script-run. It reads the workspace from $GRC_WS, which the generated setup-grc.<ext> exports (along with GRC_SCRIPT_SETUP and GRC_SCRIPT_RUN), so once the env is sourced you can invoke it from anywhere:

source ws/setup-grc.bash        # or .zsh
script-run pick_place_single
script-run admittance_arc_single
"$GRC_SCRIPT_RUN" pick_place_single   # by exported path, from any directory

Without a sourced env, set GRC_WS inline:

GRC_WS=ws ws/src/grc_meta/script-run pick_place_single

To run without a display (e.g. in CI), use --headless, which steps the simulation and FSM without opening a window. It runs until the FSM reaches S_DONE; STEPS=<n> (default 45000) is the safety cap on how long it waits:

GRC_WS=ws ws/src/grc_meta/script-run --headless pick_place_single

script-run runs make run MODEL=<model>, so each run is cataloged through REC and written as a self-contained archive under ws/src/bdd_collab_bhv_cpp/models/runs/<run-id>/. The model is a required positional argument. Set DIR=<path>, RUN_ID=<id>, or RUN_DIR=<path> to control where generated artifacts and run archives are written.

docker

script-docker builds a dev image from the Dockerfile (a ROS 2 base with the required system packages preinstalled) and runs it with the host display and GPU forwarded, so the MuJoCo GUI renders on your screen. It auto-detects X11 vs Wayland (and sets DISPLAY/WAYLAND_DISPLAY/XDG_RUNTIME_DIR accordingly) and NVIDIA (--gpus all) vs Intel/AMD (/dev/dri).

# from this grc_meta checkout; ROS_DISTRO defaults to lyrical
ws/src/grc_meta/script-docker            # build image + interactive shell

# then inside the container:
GRC_GIT_TRANSPORT=https /grc_meta/script-setup ws lyrical
GRC_WS=ws /grc_meta/script-run

workspace

mkdir -p ws/src
cd ws/src
git clone git@github.com:secorolab/grc_meta.git
vcs import < grc_meta/grc_meta.repos

colcon setup

cd ~/ws
cp src/grc_meta/colcon.meta .
cp src/grc_meta/colcon_defaults.yaml .

build

cd ~/ws
colcon build