Configuring MoveIt Pro

MoveIt Pro is designed to switch between various configuration packages. A configuration package is a description of the system, including

The robot(s) being operated and the environment.

Configuration files describing sensors, actuators, controllers, and MoveIt settings for motion planning.

The available set of Objectives, Behaviors, and Waypoints for that specific configuration.

For more details, refer to Configuring a Custom Robot.

Configuration Files and Folders

When you download MoveIt Pro, a file named .env is created in the current directory. This file stores the necessary variables to configure MoveIt Pro.

Additionally, launching MoveIt Pro creates a few important folders on your system:

${HOME}/.config/moveit_pro: Contains files specific to configuration packages in subfolders named after each individual package. This includes any new Objectives and Waypoints, or changes to existing ones, as you use the web app. For example, the picknik_ur_site_config will be placed in ${HOME}/.config/moveit_pro/picknik_ur_site_config.

${HOME}/.local/share/moveit_pro: Contains persistent MoveIt Pro data, such as authentication data and meshes to be rendered in the UI.

${HOME}/.ros/log_moveit_pro: Contains saved logs from previous runs of MoveIt Pro.

Note

All of the files in your configuration package’s objectives directory will be copied into the ${HOME}/.config/moveit_pro/${CONFIG_PACKAGE_NAME}/objectives directory.

Running the Configuration Script

The moveit_pro utility script includes a tool to modify many configurable parameters in a step by step manner. To start the configuration utility, run:

moveit_pro configure

You will be prompted with the following options:

Please enter ROS domain ID Set your ROS domain ID to be unique within your network

Please enter MoveIt Pro configuration package Choose a configuration package to use

Please enter MoveIt Pro Docker tag/version Select your MoveIt Pro version

Please enter User workspace path Specify the location of your configuration packages

Please enter MoveIt Pro license key Licenses are issued at the time of purchase

Do you want to replicate the localhost DDS configuration? If you want to override the MoveIt Pro Docker container’s DDS configuration you can choose to use the host configuration.

Warning

MoveIt Pro uses CycloneDDS by default. Unless you have specific DDS requirements, we suggest using our default configuration. ROS2 communication between the MoveIt Pro Docker container and the system host is best achieved using our recommended DDS configuration found here.

See the script’s help text for a complete list of launch options and runnable commands with:

moveit_pro help

Changing Configuration Packages

MoveIt Pro will start by default with the picknik_ur_mock_hw_config configuration package, which describes a simulated UR5e robot on a stationary base.

To change the configuration used when launching MoveIt Pro you can run the configuration utility above. Alternatively, specify an alternate configuration package at runtime:

moveit_pro run -c my_config_package

For example, to switch from the default configuration to a UR5e Gazebo configuration, you can change the configuration name to picknik_ur_gazebo_config at launch time.

Saving and Configuration Changes

As mentioned above, MoveIt Pro will store runtime data on a per-configuration basis in ${HOME}/.config/moveit_pro/${CONFIG_PACKAGE_NAME}, where ${CONFIG_PACKAGE_NAME} is the name of the configuration package you are using, such as picknik_ur_site_config.

When building or modifying Objectives and Waypoints for a given system, those changes are persisted in the configuration folder. To save any modified work to your user workspace or git repo, you must copy the data out of the .config folder and into your configuration package. For example, to save Waypoint updates for the package named picknik_ur_site_config to ${USER_WS}/src/ directory, run,

cp $HOME/.config/moveit_pro/picknik_ur_site_config/waypoints.yaml $USER_WS/src/picknik_ur_site_config/waypoints/

The same is true for modified Objective XML files, though the file locations on disk are slightly different,

cp $HOME/.config/moveit_pro/picknik_ur_site_config/objectives/<Objective> $USER_WS/src/picknik_ur_site_config/objectives/

Resetting Configuration Changes

In some instances, it may be useful to reset changes to the .config folder back to the defaults for the configuration package. The launch utility provides a function reset, that can be used to reset the configuration data for a given package:

moveit_pro reset -c $CONFIG_PACKAGE_NAME

This will clear the contents of ${HOME}/.config/moveit_pro/${CONFIG_PACKAGE_NAME} so that they are restored from the package defaults on the next launch. Again, in this case ${CONFIG_PACKAGE_NAME} is the name of the configuration package you are using.

Note

When resetting, any in progress changes will be lost! Be sure to back up and save any required Objectives, Waypoints, etc. prior to removing those contents.

Mounting a User Workspace

Because MoveIt Pro uses a Docker based solution, not all files generated by the software are immediately available on your host system.

You can choose to mount a user workspace into the MoveIt Pro Docker containers, which allows you to:

Add your own custom packages into MoveIt Pro, including custom robot configuration or Behavior packages.

Ensure that Behavior packages generated when you Making a Hello World Behavior in the web app are available on your host file system.

To mount a user workspace, run moveit_pro configure and follow the prompts.

Note that the user workspace folder must:

Be a valid Colcon workspace. This means that the folder must contain a src subdirectory, which in turn contains Colcon packages.
Contain a Dockerfile at the workspace root to enable Creating Docker Overlay images.

For example, you can mount a folder located at ~/moveit_studio_ws into MoveIt Pro and use its packages if it has the following structure.

~/moveit_studio_ws
   + --- Dockerfile
   + --- src/
          + --- my_package_1/
          + --- my_package_2/

Note

Your workspace will be bind mounted into the ${HOME}/user_ws folder of the MoveIt Pro containers.

Setting STUDIO_HOST_USER_WORKSPACE=~/moveit_studio_ws in your .env file is equivalent to specifying ~/moveit_studio_ws as the workspace you want to mount when running moveit_pro configure.