Configure Frontend Settings

Required Version

This feature requires MoveIt Pro version 9.3 or newer.

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

Requires MoveIt Pro 9.4 or later

The enable_web_bridge / web_bridge_url iframe-viewport keys were introduced in MoveIt Pro 9.4, replacing the earlier enable_ros_bridge / rosbridge_url keys. On 9.4 and later, configuration files using the old key names must be updated.

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, optional enable_web_bridge, optional web_bridge_url). web_bridge_url defaults to MoveIt Pro's own WebSocket bridge when enable_web_bridge is true.

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
  # A pane that needs to talk to ROS through MoveIt Pro's WebSocket bridge.
  # Set `enable_web_bridge` to `true`. `web_bridge_url` is optional:
  # omit it to use the same endpoint the rest of the frontend connects to;
  # set it to point at a different WebSocket endpoint.
  - name: Diagnostics Viewer
    url: https://diagnostics.example.com/viewer
    enable_web_bridge: true

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

Custom View Panes are scoped to the active robot configuration

The Custom View Panes list is stored per robot configuration. Both YAML-declared entries and panes added via the in-app modal live in the active config's bucket. Switching the active robot_config swaps to that config's own pane list; switching back restores it. On first load under a given config, YAML-declared viewports are merged into the list by name, so user edits to a YAML-seeded pane survive across reloads.

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 — User edits via the UI (write-back)

Clicking Done in the Custom View Panes modal persists the current iframeViewports list to:

~/.config/moveit_pro/<active_config_package>/frontend_settings.yaml

This user-state location survives colcon build (unlike a file in install/share). The same path is read back on the next launch, so panes added via the UI persist without hand-editing YAML.

Option 3 — Config package convention (shipped defaults)

If neither of the above supplies a value, MoveIt Pro reads the file shipped inside the active robot configuration package at:

<your_config_package>/config/frontend_settings.yaml

This is the right place for deployment-wide defaults that should always apply. The file is part of your robot configuration package and ships with it. The loader picks one file at a time — the first source in the resolution order that exists wins, and its contents are used as-is. There is no per-key merge across sources, so if the user-state file from Option 2 exists, the shipped file is ignored entirely on that launch (and vice versa).

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

Resolution Order

1. --frontend-settings <path> (CLI flag)
2. ~/.config/moveit_pro/<active_config_package>/frontend_settings.yaml (written by the UI on Done)
3. <config_package>/config/frontend_settings.yaml (shipped defaults)
4. 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 top-level field whose value fails validation (e.g. nav2PlanTopic that does not start with /): logged and replaced with that field's default. Other top-level fields are unaffected.
• Within iframeViewports, a single invalid entry (bad url, non-boolean enable_web_bridge, malformed web_bridge_url, etc.) drops the entire iframeViewports array back to empty — not just that one entry. The intent is to keep deployment YAML "all-or-nothing" so a typo in one viewport doesn't silently ship a half-configured pane list. Other top-level fields (referenceFrame, nav2PlanTopic) still apply.

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 (whether by hand or by clicking Done in the Custom View Panes modal), refresh the browser tab (or restart the stack).
• Only the iframeViewports list is editable from the UI today. Other top-level keys (referenceFrame, nav2PlanTopic, etc.) still require hand-editing the file — write-back preserves them but the UI does not expose them.