 Please ask about problems and questions regarding this tutorial on answers.ros.org. Don't forget to include in your question the link to this page, the versions of your OS & ROS, and also add appropriate tags. |
Working with ROS-Industrial Robot Support Packages
Description: This tutorial will provide an overview of the files and directories that make up a ROS-Industrial robot support package and show how to make proper use of the functionality provided by such packages.Keywords: industrial, urdf, launchfiles, meshes, models, variants
Tutorial Level: INTERMEDIATE
Contents
Overview
This page provides information on how to efficiently work with ROS-Industrial Robot Support Packages.
The purpose and structure of these support packages is similar to the typical robot description packages that can be found in ROS (such as the pr2_description package). However, to deal with the typically more established product range, the potentially large number of variants of robot models, and to exploit the more structured naming employed by industrial robot manufacturers, these packages are named and organised slightly different from their ROS counterparts. Using these packages is also similarly slightly different.
The following sections will focus on the two main types of artefacts packaged by robot support packages: launch files and xacro macros. The former are used to interact with the industrial controller, inspection of the models and state visualisation, while the latter provide urdf models of the supported robot variants.
Note: all of the examples on this page are based on the Fanuc M-10iA (as m10ia). For other robots and manufacturers, just replace every occurence of fanuc_m10ia with the appropriate names. For the Motoman MH5 for instance, this would become motoman_mh5.
Structure of Robot Support Packages
All official support packages in ROS-Industrial share a common file and directory layout, across all models and all manufacturers. This was done to be able to efficiently work with those packages, as standardising naming and file locations removes a significant amount of guess work and the need to frequently look-up where artefacts are stored or how they are named.
The following listing shows the top level directory layout for a robot support package (again, this example is for the Fanuc M-10iA):
fanuc_m10ia_support ├─config ├─launch ├─meshes ├─test └─urdf
Briefly, config may contain files storing information such as joint names, RViz configurations, or any other model specific configuration. launch stores the set of launch files common to all support packages (see the next section). The meshes directory stores all the 3D meshes referenced in the urdfs used for visualisation and collision detection. Each support package also contains a set of standardised (roslaunch) tests, which can be found in the test directory. Those tests typically check the launch files in launch for errors, but may include other tests as well. Lastly, all urdfs and xacros are stored in the urdf directory.
Using the provided launch files
All ROS-Industrial robot support packages contain the following launch files, one set per robot variant:
fanuc_m10ia_support ├─.. ├─launch │ ├─.. │ ├─load_m10ia.launch │ ├─test_m10ia.launch │ ├─robot_state_visualize_m10ia.launch │ ├─robot_interface_(streaming|download)_m10ia.launch │ └─.. └─..
load_m10ia.launch
The load_m10ia.launch file simply uploads the urdf of this specific model to the robot_description parameter on the parameter server. It is recommended that users include this launch file in their own launch files, instead of loading the urdf or calling xacro directly. Not all models may have a simple, or single, urdf or xacro to load, and this launch file hides those details behind a simple interface.
test_m10ia.launch
The test_m10ia.launch file allows users to inspect and verify the urdf in RViz. It automatically loads the appropriate urdf (by including load_m10ia.launch), and starts the joint_state_publisher and robot_state_publisher nodes to allow users to interact with the model. This launch file does not need access to any real hardware.
robot_state_visualize_m10ia.launch
The robot_state_visualize_m10ia.launch allows users to visualise the current state of a real (or simulated) robot in RViz. It does this by starting the relevant nodes from the appropriate ROS-Industrial robot driver package, providing them with any parameters they might need to correctly interface with this specific model (in this case a Fanuc M-10iA), and by starting RViz and the robot_state_publisher node.
This launch file obviously requires access to real (or simulated) hardware, and has (at least) one required argument: the ip address of the industrial controller. The controller must already be running the appropriate ROS-Industrial server programs.
robot_interface_streaming_m10ia.launch
The last file, robot_interface_streaming_m10ia.launch, starts all ROS nodes required for setting up a full bi-directional connection between ROS and the industrial controller. Both state reporting and trajectory relay nodes are started (see Industrial Robot Client - Design). In most cases, this launch file is a wrapper around a similar file provided by the ROS-Industrial driver package for the controller, but with any additional information the driver might need to correctly interface with a specific model (again, in this case the M-10iA).
This launch file requires access to real (or simulated) hardware, and has (at least) one required argument: the ip address of the industrial controller. The controller must already be running the appropriate ROS-Industrial server programs.
Streaming or downloading
Two main versions of the robot_interface launch file exist: streaming and download, which correspond to the two main ways in which ROS-Industrial robot drivers interact with their server components running on the industrial controller (see the Generic Implementation subpage of the Industrial Robot Client package for more information). Both typically accept the same arguments, but this depends on the specific needs of the involved nodes. There are currently no robot driver packages that support both streaming and downloading, so all official support packages will contain only one of the two variants of the launch files.
Additional arguments
Both the robot_state_visualize and the robot_interface_streaming launch file may in some cases accept (or require) additional arguments. As an example, the Fanuc ROS-Industrial driver requires an endianness swap to be performed on any data it receives or transmits, but only if connecting to a real controller. Connections to simulated controllers do not need this swapping, so all robot_state_visualize and robot_interface_streaming launch files for Fanuc manipulators accept a use_bswap parameter that allow the user to configure this behaviour. In the absence of documentation on the wiki, it is best to check the launch file directly for information on additional parameters.
Example: starting the streaming interface
As an example, the following roslaunch invocation starts the ROS-Industrial Fanuc driver, with appropriate settings for interfacing with the M-10iA, attached to a controller at 10.10.0.100:
roslaunch fanuc_m10ia_support robot_interface_streaming_m10ia.launch robot_ip:=10.10.0.100
For the same M-10iA, but now simulated using Roboguide on a Windows PC at 10.10.0.120:
roslaunch fanuc_m10ia_support robot_interface_streaming_m10ia.launch robot_ip:=10.10.0.120 use_bswap:=false
Note the use of the additional bswap argument.
Example: including the streaming interface
As an additional example, the following launch file extract (from a typical ROS-Industrial moveit_planning_execution.launch file created in the Create a MoveIt Package for an Industrial Robot tutorial), shows how to start the driver for a particular model as part of a larger launch file:
In this particular example, the driver launch file is only loaded when the sim argument is false (so when a real robot is used). Both the robot_ip and use_bswap arguments are passed on to robot_interface_streaming_m10ia.launch from the top level launch file.
Using the provided xacros
In addition to standardised launch files, all Robot Support Packages also include a set of standardised xacro files: a macro definition, and a file providing a default instantiation of the main macro.
Those xacros are often based on the Create a URDF for an Industrial Robot tutorial, and follow a common convention for robot, joint and link names. See the Naming section further down on this page for more information about naming of (and in) xacros.
Every package will always include at least the following files, one set per robot variant:
fanuc_m10ia_support ├─.. └─urdf ├─.. ├─m10ia_macro.xacro ├─m10ia.xacro ├─m10ia.urdf └─..
m10ia_macro.xacro
The m10ia_macro.xacro file defines the main xacro macro for this specific robot model variant. This file does not constitute a complete urdf: it contains only the macro definition. Users may include this file in other derived or composite xacros to add instances of the modelled manipulator to the scene.
All ROS-Industrial robot macros accept a prefix parameter, the value of which is prepended to all links and joints that are part of the kinematic structure. This prefix should be used to avoid collisions between multiple instances of the same macro, or between other urdf structures making use of the same link or joint names.
m10ia.xacro
This m10ia.xacro is a top-level xacro file that instantiates a single instance of the robot modelled by the associated xacro macro in an otherwise empty scene. This is a default convenience xacro, which is not meant for inclusion in other xacros (use m10ia_macro.xacro for that). The prefix parameter is set to "" (the empty string).
This file is loaded by the load_m10ia.launch file discussed earlier and is also used for creating the m10ia.urdf file.
m10ia.urdf
m10ia.urdf is an export of the m10ia.xacro file, after conversion by the xacro tool. As such, it contains the exact same kinematic structure as m10ia_macro.xacro.
It may be used with ROS packages / tooling that is not capable of loading xacros directly, or in cases where depending on or making use of xacro is undesirable. As a complete urdf, it cannot be included in other files, and should be treated as a top-level urdf.
Naming
Naming of all xacros in the urdf directory follows a standardised naming scheme. This also influences the names of the macros defined in the files.
Files in the urdf directory do not include the manufacturer's name as part of their filename. As the full package name is part of the path specifying their location, adding an additional prefix would be redundant.
The names of the macros do include the manufacturer's name. This is done to avoid name clashes with identically named macros defined in other files, as well as to increase recognisability of the macros in complex xacros.
Standardised links / frames
In addition to the normal kinematic chain, robot model urdfs contain three extra, standardised, frames. These are the base, flange and the tool0 frame. These frames have proven convenient when working with industrial robot controllers.
The base frame is coincident with, and has the same orientation as, the base frame as defined by the industrial controller (ie: the origin of its main Cartesian coordinate system). Its purpose is to allow users to transform points into the Cartesian base frame of the robot. Some vendor-specific names for this frame are World Frame (Fanuc), $ROBROOT (KUKA).
The tool0 frame is coincident with, and has the same orientation as, the default tool frame as defined by the industrial controller. Its purpose is to facilitate transforming points into the Cartesian tool frame of the robot. The tool0 frame matches an unconfigured, or all-zeros tool frame. This frame must not be edited. Additional tool frames should be defined as children of flange (or for some robots, of the last link that is part of the kinematic chain). Some vendor-specific names for this frame are Tool Frame (Fanuc), $TOOL (KUKA).
The flange frame is the frame that should be used to attach EEF models to the main kinematic chain of the robot. In contrast to tool0, this frame will always be oriented according to REP 103, with x+ pointing forward. This makes attaching EEF models straightfoward, as no additional rotations should be needed to align the EEF model with the robot flange link. Note that flange does not have any geometry assigned to it, it's an empty frame. This frame must also not be edited.
See the Create a URDF for an Industrial Robot tutorial, section Additional/Standard Frames for more information on other frames, their definition and uses.
Example: adding an end-effector to a robot
As an example, the following shows how to attach an end-effector model (found in a fictional my_eef_description package) to the flange link of the xacro of the M-10iA (from the fanuc_m10ia_support package). The concepts shown here can be used to create arbitrarily complex scenes.
1 <?xml version="1.0"?>
2 <robot xmlns:xacro="http://wiki.ros.org/xacro">
3 <!-- include macros for M-10iA and the eef model -->
4 <xacro:include filename="$(find fanuc_m10ia_support)/urdf/m10ia_macro.xacro"/>
5 <xacro:include filename="$(find my_eef_description)/urdf/my_eef_macro.xacro" />
6
7 <!-- create the robot + eef combo itself as a macro -->
8 <xacro:macro name="fanuc_m10ia_with_eef" params="prefix">
9
10 <!-- instantiate M-10iA and eef model -->
11 <xacro:fanuc_m10ia prefix="${prefix}robot_" />
12 <xacro:my_eef prefix="${prefix}eef_" />
13
14 <!-- attach eef to M-10iA model -->
15 <!-- Note: this assumes that the 'my_eef' macro defines a 'base_link'
16 link which is the start of it's kinematic chain (if any) -->
17 <joint name="${prefix}robot_flange-${prefix}eef_base_link" type="fixed">
18 <origin xyz="0 0 0" rpy="0 0 0" />
19 <parent link="${prefix}robot_flange" />
20 <child link="${prefix}eef_base_link" />
21 </joint>
22
23 </xacro:macro>
24 </robot>
By wrapping the new composite structure itself in a macro, it can be instantiated in much the same way as the original M-10iA macro.
Users are also encouraged to store such composite xacros in stand-alone packages, complete with the set of launch files described in the Using the provided launch files section, and a top-level xacro file as described in Using the provided xacros.
Conclusion
This concludes this tutorial. For an overview of all other ROS-Industrial tutorials, please see Industrial/Tutorials.
