Configuring MoveIt Studio for a Specific Robot

Overview

MoveIt Studio uses two types of robot configuration packages:

Base config: This package defines a family of broadly-similar robots. For example, all of PickNik’s UR5e robots inherit from the same base config package.
Site config: This package contains information about a specific robot, such as kinematic calibration data, network settings, or environment information. For example, each of PickNik’s UR5e robots has its own site config package to describe the differences between each unique robot.

When the MoveIt Studio Agent is launched, it loads robot description info and system settings from a specified configuration package.

Both base and site configs are implemented as Colcon packages, meaning that you can create your own packages when developing with MoveIt Studio.

MoveIt Studio includes a few config packages you can switch between. When you install MoveIt Studio, you will have access to a workspace cloned from the moveit_studio_ws repository. You can refer to this repository while reading this document, and later on when you decide to create your own config packages.

As an example, MoveIt Studio can be configured to use an example configuration named picknik_ur_base_config from the moveit_studio_ws repo. This package describes a Universal Robots UR5e manipulator with a Robotiq 2F-85 gripper. To do this, start MoveIt Studio as follows:

./moveit_studio run picknik_ur_base_config

Or if you are directly modifying the .env file, modify it as follows:

STUDIO_CONFIG_PACKAGE=picknik_ur_base_config
STUDIO_HOST_USER_WORKSPACE=~/moveit_studio/moveit_studio_ws

In this case, since the picknik_ur_base_config package is defined in an external workspace located in ~/moveit_studio/moveit_studio_ws, it must be mounted into MoveIt Studio by setting STUDIO_HOST_USER_WORKSPACE to this path.

Note

The above steps assume MoveIt Studio was installed to the default directory, ~/moveit_studio. If you installed to a different directory, this path should change accordingly.

Creating a New Base Config Package

Each base config package contains a base_config.yaml file that contains various settings, including:

Configuration for MoveIt, ros2_control, and perception sensors.
Definitions for Objectives and Behaviors the system can execute.
URDF and SRDF files defining the geometry and kinematics of the system.

Create required package structure

The structure of a base config package will be as follows. We will be using the picknik_ur_base_config package as reference.

picknik_ur_base_config/
  config/
    control/
    moveit/
    base_config.yaml
    cameras.yaml
  description/
  launch/
  objectives/
  waypoints/
  CMakeLists.txt
  package.xml

Fill in `CMakeLists.txt`

The most important thing to do in CMakeLists.txt is to install all the package directories to the package’s installed share directory. For example:

cmake_minimum_required(VERSION 3.16.3)
project(picknik_ur_base_config)

find_package(ament_cmake REQUIRED)

install(
  DIRECTORY
    config
    description
    launch
    objectives
    waypoints
  DESTINATION
    share/${PROJECT_NAME}
)

ament_package()

Fill in `package.xml`

If your robot description includes resources from other packages, tag them as dependencies here. Following our example, which configures a UR5e arm with an Intel Realsense camera and a Robotiq gripper:

<?xml version="1.0"?>
<package format="3">
  <name>picknik_ur_base_config</name>
  <version>1.11.0</version>

  <description>Base config package for a UR5e manipulator.</description>

  <maintainer email="[email protected]">Me The Developer</maintainer>

  <license>BSD-3-Clause</license>

  <buildtool_depend>ament_cmake</buildtool_depend>

  <depend>moveit_studio_behavior</depend>
  <depend>realsense2_description</depend>
  <depend>robotiq_desscription</depend>
  <depend>ur_description</depend>

  <export>
    <build_type>ament_cmake</build_type>
  </export>
</package>

Create and populate `base_config.yaml`

This file tells the MoveIt Studio Agent how to load and initialize the robot, and is included in the config/ directory. It will contain links to other config files in the base config package that we have not discussed yet, but we will describe it first so we can use it as a map for these instructions.

Create a `.ros2_control.yaml` file

This file configures the different controllers used by the robot, and is included in the config/control/ directory. It is the same YAML file needed to set up ros2_control for your robot. Typically, this file is given a name describing the robot being controlled; in our example package, this is picknik_ur5e.ros2_control.yaml.

Create MoveIt config files

These files configure MoveIt 2 for motion planning and servo applications, and should be included in the config/moveit/ directory. They are the same files needed to configure MoveIt 2 for your robot.

The MoveIt config files supported by MoveIt Studio include:

joint_limits.yaml: Sets joint position, velocity, acceleration, and effort limits to use when planning and parameterizing robot motion.
kinematics.yaml: Configures MoveIt’s kinematics solvers. Note you can specify multiple kinematics files for different applications, for example for motion planning vs. servoing.
ompl_planning.yaml: Defines settings for MoveIt’s OMPL planners.
picknik_ur5e.srdf: Defines the robot’s planning groups and Allowed Collision Matrix (ACM).
pilz_cartesian_limits.yaml: Defines Cartesian velocity and acceleration limits for the Pilz Industrial Motion Planner.
sensors_3d.yaml: Defines how the MoveIt MoveGroup node should handle point clouds from the robot’s RGB-D cameras.
ur5e_servo.yaml: Configures settings for the MoveIt Servo server node.

Add a camera config file

This file, typically found in config/cameras.yaml, tells MoveIt Studio which camera driver nodes to launch and how they relate to the sensor hardware associated with the robot.

Add robot description xacro files

The xacro file is parsed at runtime to generate a URDF file describing robot kinematics and geometry. It can also include environment information, such as static obstacles (tables, walls, etc.) that are known ahead of time. These files are typically placed in the description folder of a config package.

Add robot and driver launch files

These launch files, usually found in the launch folder, define nodes specific to this robot that should be launched with the other Agent nodes at system startup. You can specify different launch files for simulation vs. hardware environments, which are controlled by the hardware.simulated option in config/base_config.yaml.

Add Objective and Behavior XML files

The objectives directory contains XML Objective definition files that define the Objectives which the robot can run. This directory also contains the files standard_tree_nodes_model.xml and tree_nodes_model.xml, which provide the necessary metadata needed to display Objectives and Behaviors in the MoveIt Studio web app.

Below is an example of including Objectives and Behaviors in your package by adding the following sections of the config/base_config.yaml file:

objectives:
  # List of plugins for loading custom Behaviors.
  behavior_loader_plugins:
    # This plugin will load the core MoveIt Studio Behaviors.
    # Add additional plugin loaders as needed.
    core:
      - "moveit_studio::behaviors::CoreBehaviorsLoader"
  # Specify source folder for objectives
  objective_library_paths:
    core:
      package_name: "picknik_ur_base_config"
      relative_path: "objectives"

Add a waypoints file

The waypoints/waypoints.yaml file defines a set of named robot joint states that the Agent can retrieve and plan to during an Objective. This file can be edited during runtime if the Agent saves a new waypoint for a particular robot state.

It replaces the named robot states commonly included in the robot’s SRDF file.

Creating a New Site Config Package

A base config package can be specialized to contain unique information about a specific robot through a site config package. This is useful for managing site-specific variations of a common robot configuration.

Site config packages are structured in the same way as base config packages, except that they contain a site_config.yaml file in place of a base_config.yaml file. The site_config.yaml file names a base config package to modify, through the based_on_package key, and provides the ability to override values for a subset of config settings that will be used at runtime instead of the values in the base config package.

Create required package structure

The structure of a site config package will be as follows. We will be using the picknik_ur_site_config package from the moveit_studio_ws repo as reference.

my_site_config_package/
  config/
    site_config.yaml
  CMakeLists.txt
  package.xml

Create and populate `site_config.yaml`

The config/site_config.yaml file points to a robot base config package and provides new values for a subset of the values in the base config package’s base_config.yaml file.

To set which base config package will be used, set the value of the based_on_package key to the name of the base config package. For example, if picknik_ur_site_config will be a specialization of picknik_ur_base_config, add based_on_package: "picknik_ur_base_config" to site_config.yaml.

The other contents of site_config.yaml will depend on how the values in base_config.yaml need to be customized for a particular robot.

A common pattern is to use a different URDF xacro file for the site config than the one in the base config package. To do this, create a new URDF xacro file in a directory within the site config package, then override the package name and relative path to the URDF xacro file in site_config.yaml. Another common pattern is to add to the list of Objectives and Behaviors available in the config/site_config.yaml file. For example:

# Extend the basic Universal Robots configuration
based_on_package: picknik_ur_base_config

hardware:
  robot_description:
    urdf:
      package: "picknik_ur_site_config"
      path: "description/my_customized_robot.xacro"

objectives:
  behavior_loader_plugins:
    # You must use a unique key for each Behavior plugin.
    # The picknik_ur_base_config uses "core"
    custom_behaviors:
      package_name: "my_custom_behaviors::MyCustomBehaviorsLoader"
  objective_library_paths:
    # You must use a unique key for each package.
    # The picknik_ur_base_config uses "core"
    custom_objectives:
      package_name: "picknik_ur_site_config"
      relative_path: "objectives"

Configuring MoveIt Studio for a Specific Robot

Overview

Creating a New Base Config Package

Create required package structure

Fill in CMakeLists.txt

Fill in package.xml

Create and populate base_config.yaml

Create a .ros2_control.yaml file

Create MoveIt config files

Add a camera config file

Add robot description xacro files

Add robot and driver launch files

Add Objective and Behavior XML files

Add a waypoints file

Creating a New Site Config Package

Create required package structure

Create and populate site_config.yaml

Fill in `CMakeLists.txt`

Fill in `package.xml`

Create and populate `base_config.yaml`

Create a `.ros2_control.yaml` file

Create and populate `site_config.yaml`