Configuring a Custom Robot

MoveIt Pro uses robot configuration packages to specify all parameters necessary for launching the application. When the MoveIt Pro 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 Pro.

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.

MoveIt Pro includes a few configuration packages you can switch between. When you install MoveIt Pro, the configuration packages above are installed by default in a workspace cloned from the moveit_studio_ur_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 Pro can be configured to use an example configuration named picknik_ur_base_config from the moveit_studio_ur_ws repo. This package describes a Universal Robots UR5e manipulator with a Robotiq 2F-85 gripper. To do this, start MoveIt Pro as follows:

moveit_pro run -c picknik_ur_base_config

In this case, since the picknik_ur_base_config package is defined in an external workspace located in ~/moveit_pro/moveit_studio_ur_ws, it must be mounted into MoveIt Pro by setting the user workspace to this path using moveit_pro configure.

note

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

1. Create the ROS 2 Package

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
  description/
  launch/
  objectives/
  waypoints/
  CMakeLists.txt
  package.xml

Fill in package.xml

If your configuration requires resources from other packages or is inheriting from another config, tag them as dependencies here. Below is an example with dependencies for configuring 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>3.0.0</version>

  <description>Base configuration package for Picknik's UR robot arms</description>

  <maintainer email="[email protected]">MoveIt Pro Maintainer</maintainer>

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

  <buildtool_depend>ament_cmake</buildtool_depend>

  <exec_depend>admittance_controller</exec_depend>
  <exec_depend>kinematics_interface_kdl</exec_depend>
  <exec_depend>moveit_planners_stomp</exec_depend>
  <exec_depend>moveit_ros_perception</exec_depend>
  <exec_depend>moveit_studio_agent</exec_depend>
  <exec_depend>moveit_studio_behavior</exec_depend>
  <exec_depend>moveit_studio_ur_pstop_manager</exec_depend>
  <exec_depend>picknik_accessories</exec_depend>
  <exec_depend>realsense2_description</exec_depend>
  <exec_depend>realsense2_camera</exec_depend>
  <exec_depend>robotiq_description</exec_depend>
  <exec_depend>robotiq_driver</exec_depend>
  <exec_depend>robotiq_controllers</exec_depend>
  <exec_depend>trac_ik_kinematics_plugin</exec_depend>
  <exec_depend>ur_description</exec_depend>
  <exec_depend>ur_robot_driver</exec_depend>

  <test_depend>ament_lint_auto</test_depend>

  <test_depend>ament_clang_format</test_depend>
  <test_depend>ament_clang_tidy</test_depend>
  <test_depend>ament_cmake_copyright</test_depend>
  <test_depend>picknik_ament_copyright</test_depend>
  <test_depend>ament_flake8</test_depend>

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

Fill in CMakeLists.txt

The CMakeLists.txt defines the install targets for all the shared package artifacts. If your configuration requires other packages or is inheriting from another config package, include them as find_package requirements here. The example below installs all the populated subdirectories to the package's share directory:

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()

2. Create and populate a config.yaml file

Each configuration package requires a config/config.yaml file that defines various settings, including:

• URDF and SRDF files defining the setup's robot description and semantics.
• Configuration for robot drivers, controllers, and sensors
• Configuration for the MoveIt instance
• Definitions for MoveIt Pro Objectives and Behaviors

The config/config.yaml tells the MoveIt Pro Agent precisely what resources to load and how to configure them at runtime. The following sections describe how to prepare the resources and configure the config for MoveIt Pro to launch successfully.

Configuring Robot Description and Semantics

The MoveIt Pro config requires the robot_description property to point to the robot description and semantics files using the urdf and srdf keys. For the urdf key, either a XACRO or URDF file can be used. If a XACRO file is used, the corresponding URDF file is generated with each launch. Optional XACRO arguments can be defined using the urdf_params key. URDF or XACRO files are typically placed in the description folder of a configuration package, the SRDF file is commonly placed inside config/moveit/. However, it is also possible to point to an existing MoveIt configuration or other ROS 2 packages.

Below is a simplified example from the picknik_ur_base_config.

# Parameters used to configure the robot description through XACRO.
# A URDF and SRDF are both required.
# [Required]
robot_description:
  urdf:
    package: "picknik_ur_base_config"
    path: "description/picknik_ur.xacro"
  srdf:
    package: "picknik_ur_base_config"
    path: "config/moveit/picknik_ur.srdf"

  # Specify any additional parameters required for the URDF and SRDF.
  # Many of these are specific to the UR descriptions packages, and can be customized as needed.
  # [Optional]
  urdf_params:
    - name: "picknik_ur5e"
    - prefix: ""

Configuring Grasp Preview

MoveIt Pro uses the following convention for grasping frames when assembling many of its built in Behaviors to manipulate objects. It is required to add a frame to your robot's end effector with the following orientation.

• Positive X points to the robots left and is parallel to the direction the fingers move
• Positive Y points up towards the top of the gripper (from the wrist camera's perspective, if present)
• Positive Z points out of the gripper

By default, we use the frame name grasp_link, but you can rename it as needed, so long as your Behaviors specify the correct frame name.

Configuring UI Grasp Previews

MoveIt Pro uses the group defined as the end_effector element in the config's SRDF file for previewing grasp poses. When creating a custom config, make sure you define an end_effector element in your SRDF.

For example, the end-effector in the picknik_ur_base_config of the moveit_studio_ur_ws repository, is defined in the SRDF file like this:

<end_effector name="moveit_ee" parent_link="tool0" group="gripper"/>

The group attribute specifies the move group containing the joints, links and/or chains that pertain to your end effector. We recommend using chains when creating this group as opposed to links in order to avoid discrepancies when specifying these fields. You can see an example of this in the arm_on_rail_sim example configuration.

Configuring Teleoperation

MoveIt Pro provides access to simple control modes to move your robot. The different control modes are described in the Teleoperate Robot tutorial

A Teleoperate Objective needs to be added in the custom config for the Teleoperate modes to work. Consider the Teleoperate Objective in MoveIt Pro's default config as reference. The teleoperate Objective uses the Request Teleoperation Objective as a subtree and hence this Objective should also be added to the custom config.

The Request Teleoperation SubTree can be added to other objectives that require hybrid autonomous/manual modes, remote recovery fallbacks, etc.

note

Note that the teleoperation Objectives below use Behaviors requiring parameters such as, but not limited to:

• controller_names
• planning_group_name
• planner_interface

When making these Objectives, make sure to check the values you specify correspond to the definitions in your ros2_control.yaml, SRDF, XACRO/URDF, etc files.

Waypoints

The Waypoint control mode requires the following objectives and updated parameters:

• Move to Joint State Objective.

IMarker

The IMarker control mode requires the following objectives and updated parameters:

• Move to Pose Objective.
• Wait for Trajectory Approval if User Available to preview the trajectory before execution.

IMarker also requires the proper setup of your servo yaml config file, as it will reference the active planning group of the servo server (e.g. move_group_name: manipulator) to use the tip frame of the gripper planning group.

In the Move To Pose Objective in the SetupMTCMoveToPose Behavior, the ik_frame link you specify must be:

• Part of the group you specify via the SetupMTCMoveToPose Behavior's planning_group_name parameter.
• Part of the group you specify in your SRDF's end_effector tag's group field.
• Part of the servo server's active planning group (e.g. move_group_name: manipulator)

Pose Jog

The Pose Jog control mode requires the following objectives and updated parameters:

• Open Gripper Objective.
• Close Gripper Objective.

Joints Jogs

The Joints Jog control mode requires the following objectives and updated parameters:

• Open Gripper and Close Gripper (which is also used by the Pose Jog mode)
• Interpolate to Joint State Objective to move the robot using the joint sliders.

Joint jog also requires the proper setup of your servo yaml config file, as it will reference the active planning group of the servo server (e.g. move_group_name: manipulator) to populate the list of joints to create sliders for.

In order for Joint Jog Teloperation to function properly, parameters for MoveIt Servo (listed in your project's servo config yaml ie. ur5e_servo.yaml) will require specification of the following topics:

• cartesian_command_in_topic: defined as ~/delta_twist_cmds
• joint_command_in_topic: defined as ~/delta_joint_cmds

Configuring Robot Drivers and Controllers

The MoveIt Pro config supports specifying the robot's runtime configuration, including hardware drivers, simulation backends and controllers.

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.

# Set simulated to false if you are using this as a configuration for real hardware.
# This allows users to switch between mock and real hardware by changing a single 
# parameter with config inheritance.
# [Required]
simulated: True

# Specify additional launch files for running the robot with real hardware.
# [Optional, defaults to a blank launch file if not specified]
robot_driver_persist_launch_file:
  package: "picknik_ur_base_config"
  path: "launch/robot_drivers_to_persist.launch.py"

# Specify any additional launch files for running the robot in simulation mode.
# Used when hardware.simulated is True.
# [Optional, defaults to a blank launch file if not specified]
simulated_robot_driver_persist_launch_file:
  package: "picknik_ur_base_config"
  path: "launch/sim/robot_drivers_to_persist_sim.launch.py"
simulated_hardware_launch_file:
  package: "moveit_studio_agent"
  path: "launch/blank.launch.py"

The robot_driver_persist_launch_file and simulated_robot_driver_persist_launch_file are intended to launch robot drivers (and other processes) that are expected to stay active the entire time MoveIt Pro is running.

For example, if you are using MoveIt Pro with a mobile manipulator, the robot_driver_persist_launch_file and simulated_robot_driver_persist_launch_file can be used to launch Nav2 via the launch file.

The simulated_hardware_launch_file can be used to launch a process which simulates your hardware, such as Gazebo.

Configure ROS 2 Control

MoveIt Pro can be configured to bring up the ROS 2 control node and controllers with each launch, using the launch_control_node and ros2_control properties.

For that, it's first required to prepare a ROS 2 configuration file 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, placed inside config/control/.

The launch_control_node option, the ros2_control configuration file setting and controller initialization is shown in the example below.

# If the MoveIt Pro Agent should launch the ros2 controller node.
# [Optional, default=True]
launch_control_node: True

# Configuration for launching ros2_control processes.
# [Required, if using ros2_control]
ros2_control:
  config:
    package: "picknik_ur_base_config"
    path: "config/control/picknik_ur.ros2_control.yaml"

  # MoveIt Pro will load and activate these controllers at start up to ensure they are available.
  # If not specified, it is up to the user to ensure the appropriate controllers are active and available
  # for running the application.
  # [Optional, default=[]]
  controllers_active_at_startup:
    - "force_torque_sensor_broadcaster"
    - "robotiq_gripper_controller"
    - "joint_state_broadcaster"
    - "servo_controller"
    - "io_and_status_controller"
    - "robotiq_activation_controller"
  # Load but do not start these controllers so they can be activated later if needed.
  # [Optional, default=[]]
  controllers_inactive_at_startup:
    - "joint_trajectory_controller"
    - "admittance_controller_open_door"
    - "joint_trajectory_controller_chained_open_door"
  # Any controllers here will not be spawned by MoveIt Pro.
  # [Optional, default=[]]
  controllers_not_managed: []
  # Optionally configure remapping rules to let multiple controllers receive commands on the same topic.
  # [Optional, default=[]]
  controller_shared_topics: []

Configuring MoveIt Runtime

The config package allows configuring any of the MoveIt runtime properties using the same yaml files obtained from the MoveIt Setup Assistant. However, instead of depending on a MoveIt config package, the yaml files need to be added to the configuration package's config/moveit/ subdirectory.

The config files supported by MoveIt Pro 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.
• 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.

All MoveIt config files can be configured using the moveit_params property as shown below:

# Configuration files for MoveIt.
# For more information, refer to https://moveit.picknik.ai/main/doc/how_to_guides/moveit_configuration/moveit_configuration_tutorial.html
# [Required]
moveit_params:
  # Used by the Waypoint Manager to save joint states from this joint group.
  joint_group_name: "manipulator"

  ompl_planning:
    package: "picknik_ur_base_config"
    path: "config/moveit/ompl_planning.yaml"
  stomp_planning:
    package: "picknik_ur_base_config"
    path: "config/moveit/stomp_planning.yaml"
  pilz_planning:
    package: "picknik_ur_base_config"
    path: "config/moveit/pilz_industrial_motion_planner_planning.yaml"
  kinematics:
    package: "picknik_ur_base_config"
    path: "config/moveit/trac_ik_kinematics_distance.yaml"
  servo:
    package: "picknik_ur_base_config"
    path: "config/moveit/ur_servo.yaml"
  sensors_3d:
    package: "picknik_ur_base_config"
    path: "config/moveit/sensors_3d.yaml"
  servo_kinematics:
    package: "picknik_ur_base_config"
    path: "config/moveit/trac_ik_kinematics_speed.yaml"
  joint_limits:
    package: "picknik_ur_base_config"
    path: "config/moveit/joint_limits.yaml"
  pilz_cartesian_limits:
    package: "picknik_ur_base_config"
    path: "config/moveit/pilz_cartesian_limits.yaml"

  publish:
    planning_scene: True
    geometry_updates: True
    state_updates: True
    transforms_updates: True

  trajectory_execution:
    manage_controllers: True
    allowed_execution_duration_scaling: 2.0
    allowed_goal_duration_margin: 5.0
    allowed_start_tolerance: 0.01

Configuring Camera And Other Sensors

All ROS compatible hardware sensors, such as cameras and LIDAR, should be have an associated launch file in the launch directory. These launch files define nodes specific to hardware along with the launch arguments for the specific site configuration. For example, many site configurations may reuse the Intel Realsense camera launch file, however, each config's launch file will uniquely specify the camera's serial number as a launch argument. All sensor specific launch file files should be added to the top level launch file agent_bridge.launch.xml.

A typical launch top level launch file with added cameras is illustrated below.

<?xml version="1.0" encoding="UTF-8"?>
<launch>
    <include file="$(find-pkg-share moveit_studio_agent)/launch/studio_agent_bridge.launch.xml"/>
    <include file="$(find-pkg-share moveit_studio_rest_api)/launch/rest_api.launch.xml"/>
    <include file="$(find-pkg-share my_hw_pkg)/launch/cameras.launch.xml">
        <arg name="arg1" value="foo"/>
        <arg name="arg2" value="bar"/>
    </include>
</launch>

Configuring Objectives and Behaviors

The objectives directory contains XML Objective definition files that define the Objectives which the robot can run. It also contains an autogenerated tree_nodes_model.xml file, which provides the necessary metadata needed to display Objectives and Behaviors in the MoveIt Studio Developer Tool.

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 Pro 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"

Configuring predefined Waypoints

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 replaces the named group states commonly included in the robot's SRDF file. Waypoints can be saved and edited during runtime, as explained further in Configuring MoveIt Pro.

Configuration Package Inheritance

Any configuration package can be inherited from and specialized using additional parameters and configuration artifacts. This is useful for sharing common objectives or robot setups between different hardware deployments.

An inherited configuration package defines the parent package name using the based_on_package parameter inside the config.yaml. All other properties in the config.yaml and all configuration artifacts will then default to the parent's configuration, but they may be overridden in the child's config.yaml.

A minimal package structure will only include the following files.

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

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 define additional Objectives and Behaviors available in the config/config.yaml file.

The config.yaml below shows an example inheritance configuration with overrides for hardware and objectives:

# 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"