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.

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

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_pro/moveit_studio_ur_ws

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 STUDIO_HOST_USER_WORKSPACE to this path.

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

1. 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: ""

Note: Coordinate Convention for Grasp Link

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
• 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.

Note: 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"/>

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.
# Override-able by setting the $MOCK_HARDWARE environment variable to 'True'.
# This allows users to switch between mock and real hardware using the same configuration.
# [Required]
simulated: ${MOCK_HARDWARE:-true}

# The robot's IP address.
# [Required]
ip: "0.0.0.0"

# 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"
hardware_launch_file:
  package: "moveit_studio_agent"
  path: "launch/blank.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"

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 Sensors

This file, typically found in config/cameras.yaml, tells MoveIt Pro 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.

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"

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.

The Waypoint control mode requires Move to Joint State Objective.

The IMarker control mode requires the following objectives:

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

The Pose Jog control mode requires the following objectives:

• Open Gripper Objective.
• Close Gripper Objective.

The Joints Jog control mode requires the following objectives:

• 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.

Note

The user needs to modify the parameter settings in all of the above objectives as needed.