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

MoveIt Pro 10.0

The web_bridge_url pane field was removed. Delete it and use only enable_web_bridge; a pane entry that retains the removed field is invalid.

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 application's developer 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). Bridge-eligible panes can request ROS access through the parent-frame postMessage transport. Browser backend-local panes do not receive the bridge.

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://robot.example.com:8443/camera
  # A pane whose HTML ships inside a robot configuration package. A
  # backend-local URL needs no hardcoded host or IP. Only files under the
  # package's `web/` directory are accepted.
  - 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 direct bridge URL or bearer token.
  - name: Diagnostics Viewer
    url: https://robot.example.com:8731/diagnostics
    enable_web_bridge: true

In the desktop app, an absolute viewport url may use the app or connected-Runtime hostname. In a browser deployment, it must use the application hostname. Both environments also accept these backend-local paths:

• /api/packages/<package>/web/<file>
• /joint-states-monitor-example.html

An absolute pane with enable_web_bridge: true must use HTTPS. Browser backend-local panes run with an opaque origin and do not receive ROS access, even when that field is enabled.

Document-relative (./, ../), protocol-relative (//host), credentialed, and non-HTTP URLs are rejected. See Create Custom View Panes for the complete policy.

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 the MoveIt Pro Runtime 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 application's developer 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.

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 when the UI starts. To pick up changes after editing the file (whether by hand or by clicking Done in the Custom View Panes modal), restart the desktop app or refresh MoveIt Pro Cloud.
• 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.