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 iframe-viewport key was introduced in MoveIt Pro 9.4, replacing the earlier enable_ros_bridge key. The accompanying web_bridge_url field is now retired and migration-only: it is ignored and must not be used to configure a bridge. 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). Enabling the bridge grants access only through the trusted parent-frame postMessage transport. Legacy web_bridge_url values are ignored.

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 whose HTML ships inside a robot configuration package. A
  # root-relative URL is served same-origin by MoveIt Pro's own web server,
  # so it needs no hardcoded host or IP and works from any client. Files under
  # a package's `share/` directory are reachable at
  # `/api/packages/<package>/<path>`.
  - name: Status Pane
    url: /api/packages/my_robot_config/web/status.html
  # A pane that needs ROS traffic through MoveIt Pro's trusted parent-frame
  # bridge. Set `enable_web_bridge` to `true`; the pane uses the parent
  # `postMessage` API and receives no rosbridge URL or bearer token.
  - name: Diagnostics Viewer
    url: https://diagnostics.example.com/viewer
    enable_web_bridge: true

A viewport url may be an absolute http(s):// URL or a same-origin path served by the MoveIt Pro web server. Prefer a root-relative path beginning with / (e.g. /api/packages/<package>/<path>): served on the same origin as the UI, it carries no host or port and remains valid across machines. Document-relative paths (./, ../) also pass validation, but they resolve against the current app URL rather than your package, so they usually will not reach your file — use a root-relative / path instead. Protocol-relative (//host) and other schemes (javascript:, data:) are rejected.

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

Connection Compatibility Admission

Before the frontend opens its ROS transport, it sends an authenticated POST /compatibility request. The frontend key must authorize this endpoint as well as GET /frontend-settings; a 401 or 403 prevents connection and is reported as frontend-key guidance. The frontend and backend must also use the same MoveIt Pro release and a mutually supported protocol epoch.

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 or non-boolean enable_web_bridge) is logged and dropped on its own. Legacy web_bridge_url values are ignored and normalized to null, even if malformed.

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 written back from the UI today. referenceFrame can be changed from the UI via the Fixed Frame submenu of the 3D view's View menu, but that selection is session-only and resets on reload. Changing the persistent default, along with other top-level keys (nav2PlanTopic, etc.), still requires hand-editing the file.