Configure Frontend Settings

Required Version

This feature will not be released until MoveIt Pro version 9.3.

MoveIt Pro ships the frontend with a set of sensible built-in defaults — for example, the 3D Visualizer's reference frame is world and Nav2 path visualization subscribes to /plan. Each deployment can override these values without modifying frontend source by supplying a small YAML file at startup.

This guide walks through:

• The settings the frontend currently exposes
• Where to put the override file
• How precedence works between the CLI flag and the config-package convention

Available Settings

Only fields that differ from the defaults need to be present in the file — unspecified keys keep their default values. Unknown keys are logged in the browser console and ignored, so a typo like referenceframe does not break the rest of the file but is still easy to spot from startup logs. A single field with an invalid value falls back to its default while every other override in the same file still applies.

Setting	Default	Purpose
referenceFrame	"world"	TF frame the 3D Visualizer renders relative to.
nav2PlanTopic	"/plan"	Topic the Nav2 path overlay subscribes to. Custom planners may publish elsewhere.
iframeViewports	[]	Saved iframe viewport entries (name + url).

File Format

The file is a YAML mapping containing only the keys you want to override. Comments are encouraged — record why a value differs from the default so the next person to touch the file has the context:

# Our mobile-base setup uses `map` as the global TF root.
referenceFrame: map

# Custom planner publishes its smoothed path on a non-default topic.
nav2PlanTopic: /custom_planner/plan

iframeViewports:
  - name: Robot Camera
    url: https://camera.example.com/stream

An empty file (or a file containing only comments) is also valid and means "use all defaults."

Two Ways to Provide the File

There are two delivery mechanisms, with the CLI flag taking precedence:

Option 1 — CLI flag (highest precedence)

Pass an absolute or relative path to moveit_pro run:

moveit_pro run -c lab_sim --frontend-settings ./my_frontend_settings.yaml

The CLI bind-mounts that file into the container and surfaces it to the REST API, which serves it to the frontend at startup. Useful when you want to test multiple configurations against the same robot configuration package.

Option 2 — Config package convention (fallback)

If --frontend-settings is not passed, MoveIt Pro looks for a file at:

<your_config_package>/config/frontend_settings.yaml

This is the recommended location for overrides that should always apply to a particular deployment. The file is part of your robot configuration package and ships with it. No extra CLI flags or environment variables are required.

If neither source supplies a file, the frontend uses its built-in defaults.

Resolution Order

1. --frontend-settings <path> (CLI flag)
2. <config_package>/config/frontend_settings.yaml
3. Built-in defaults

Validation

The frontend validates each field independently and is tolerant by design, so one bad value never disables every other override:

• Unknown top-level keys: logged in the browser console and ignored. The rest of the file still applies.
• A field whose value fails validation (e.g. nav2PlanTopic that does not start with /, an iframeViewports[].url that is not a syntactically valid URL): logged and replaced with that field's default. Other fields in the file are unaffected.

If the YAML itself cannot be parsed, or the file exists but cannot be read, the REST API responds with HTTP 500 and the frontend falls back to the built-in defaults for every field.

Caveats

• Settings are read once at frontend startup. To pick up changes after editing the file, refresh the browser tab (or restart the stack).
• The override file is read-only inside the container. The frontend does not yet provide a UI to edit settings; this guide covers the file-based workflow only.