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_pro_example_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_pro_example_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_pro_example_ws
, it must be mounted into MoveIt Pro by setting the user workspace to this path using moveit_pro configure
.
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_pro_example_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 lab_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 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:
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'splanning_group_name
parameter. - Part of the group you specify in your SRDF's
end_effector
tag'sgroup
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:
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"