Configuring a Custom Robot

Overview

MoveIt Studio uses robot configuration packages to specify all parameters necessary for launching the application. When the MoveIt Studio Agent is launched, it loads robot description info and system settings from a specified configuration package. These configuration packages are implemented as ROS 2 packages, meaning that you can create your own packages when developing with MoveIt Studio.

Importantly, configuration packages can inherit from each other. This enables users to create parent configuration packages that might define a family of broadly-similar robots defined in child configuration packages.

For example, as shown in the diagram below, all of PickNik’s UR5e robots inherit from the same base configuration package. Different instantiations of the UR5e robot will inherit, override, or add additional parameters on top of their parent’s config to describe the differences between each unique robot. These packages may contain information about a specific robot, such as kinematic calibration data, network settings, or environment information.

graph TB Base[picknik_ur_base_config] --> Site[picknik_ur_site_config] Base --> Mock[picknik_ur_mock_hw_config] Site --> Gazebo[picknik_ur_gazebo_config] Site --> Picknik[Other PickNik configs]

MoveIt Studio includes a few configuration packages you can switch between. When you install MoveIt Studio, the configuration packages above are installed by default in 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 configuration 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 -c 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 Configuration Package from Scratch

Each configuration package contains a config/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 the package will be as follows. We will be using the picknik_ur_base_config package as reference.

picknik_ur_base_config/
  config/
    control/
    moveit/
    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 configuration 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 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 configuration files in the 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. A generic example of a cameras.yaml file can be found below.

cameras:
  external_camera:
    video_device: "/dev/video0"
    camera_name: "web_camera"
    type: "usb_camera"
    use: True
    io_method: "mmap"
    frame_id: "world_external_web_camera"
    pixel_format: "yuyv"
    framerate: 10.0
    image_width: 640
    image_height: 480
    topic: "web_camera/image_raw"

To find the actual device ID for the video_device parameter, run v4l2-ctl –list-devices from the command line.

The framerate, image_width, and image_height parameters can be modified to adjust the properties of the streamed video. The topic parameter sets which ROS topic the images will be published onto.

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 configuration 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/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/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 an Inherited Robot Configuration Package

Any configuration package can be specialized to contain unique information about a specific robot through an inherited configuration package. This is useful for managing site or group specific variations of a common robot configuration.

Inherited configuration packages are structured in the same way as any other. The config.yaml file names the configuration 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 from the parent’s configuration package.

Create required package structure

The structure of a configuration 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/
    config.yaml
  CMakeLists.txt
  package.xml

Create and populate config.yaml

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

To set which parent configuration package will be used, set the value of the based_on_package key to the name of the configuration package to inherit from. 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 config.yaml.

The other contents of config.yaml will depend on how the values in the parent configuration package’s config.yaml need to be customized for a particular robot.

A common pattern is to use a different URDF xacro file for the config than the one in the parent configuration package. To do this, create a new URDF xacro file in a directory within the configuration package, then override the package name and relative path to the URDF xacro file in config.yaml. Another common pattern is to add to the list of Objectives and Behaviors available in the config/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"

Using Custom Grippers for Grasp Previews

MoveIt Studio defaults to using a Robotiq 2F-85 gripper for grasp previews. This can be overridden by setting the web_ui_gripper parameter in your description files to specify a standalone gripper URDF to use in previews.

For example, to include the default from the picknik_ur_base_config in the moveit_studio_ws repository, add the following to your description package:

<xacro:attribute name="web_ui_gripper" value="package://picknik_ur_base_config/description/robotiq_2f_85_gripper.urdf" />