Configuring MoveIt Studio

MoveIt Studio 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 Studio, a file named .env is created in the current directory. This file stores the necessary variables to configure MoveIt Studio.

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

${HOME}/.config/moveit_studio: 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 MoveIt Studio web app. For example, the picknik_ur_site_config will be placed in ${HOME}/.config/moveit_studio/picknik_ur_site_config.

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

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

Running the Configuration Script

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

cd $HOME/moveit_studio
./moveit_studio configure

And walk through the prompts. See the script’s help text for a complete list of launch options and runnable commands with:

./moveit_studio help

Changing Configuration Packages

MoveIt Studio 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 Studio you can run the configuration utility above. Alternatively, specify an alternate configuration package at runtime:

cd $HOME/moveit_studio
./moveit_studio 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 Studio will store runtime data on a per-configuration basis in ${HOME}/.config/moveit_studio/${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_studio/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_studio/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_studio reset -c $CONFIG_PACKAGE_NAME

This will clear the contents of ${HOME}/.config/moveit_studio/${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 Studio 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 Studio Docker containers, which allows you to:

Add your own custom packages into MoveIt Studio, 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_studio 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.

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

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

Note

Your workspace will be bind mounted into the /opt/moveit_studio/user_ws folder of the MoveIt Studio 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_studio configure.