## for a custom note with links: ## note = ## for the canned note of "This tutorial assumes that you have completed the previous tutorials:" just add the links ## note.0= ## descriptive title for the tutorial ## title = Working with ROS-Industrial Robot Support Packages ## multi-line description to be displayed in search ## 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. ## the next tutorial description (optional) ## next = ## links to next tutorial (optional) ## next.0.link= ## next.1.link= ## what level user is this tutorial for ## level= IntermediateCategory ## keywords = industrial, urdf, launchfiles, meshes, models, variants #################################### <> <> == 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 [[roslaunch/XML|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 [[urdf]]s and [[xacro]]s 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 [[https://github.com/ros-industrial/fanuc/blob/indigo-devel/fanuc_m10ia_support/launch/load_m10ia.launch|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 [[https://github.com/ros-industrial/fanuc/blob/indigo-devel/fanuc_m10ia_support/launch/test_m10ia.launch|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 [[https://github.com/ros-industrial/fanuc/blob/indigo-devel/fanuc_m10ia_support/launch/robot_state_visualize_m10ia.launch|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, [[https://github.com/ros-industrial/fanuc/blob/indigo-devel/fanuc_m10ia_support/launch/robot_interface_streaming_m10ia.launch|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|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 [[industrial_robot_client/generic_implementation|Generic Implementation]] subpage of the [[industrial_robot_client|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 [[http://wiki.ros.org/Industrial/Tutorials/Create_a_MoveIt_Pkg_for_an_Industrial_Robot|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: {{{#!highlight xml ... ... }}} 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 [[Industrial/Tutorials/Create a URDF for an Industrial Robot|Create a URDF for an Industrial Robot]] tutorial, and follow a common convention for robot, joint and link names. See the [[#Naming|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 [[https://github.com/ros-industrial/fanuc/blob/indigo-devel/fanuc_m10ia_support/urdf/m10ia_macro.xacro|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 [[https://github.com/ros-industrial/fanuc/blob/indigo-devel/fanuc_m10ia_support/urdf/m10ia.xacro|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'''<
> [[https://github.com/ros-industrial/fanuc/blob/indigo-devel/fanuc_m10ia_support/urdf/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 [[http://www.ros.org/reps/rep-0103.html#chirality|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 [[Industrial/Tutorials/Create a URDF for an Industrial Robot|Create a URDF for an Industrial Robot]] tutorial, section [[Industrial/Tutorials/Create a URDF for an Industrial Robot#Additional.2BAC8-Standard_Frames|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. {{{#!highlight xml }}} 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|Using the provided launch files]] section, and a top-level xacro file as described in [[#Using_the_provided_xacros|Using the provided xacros]]. == Conclusion == This concludes this tutorial. For an overview of all other ROS-Industrial tutorials, please see [[Industrial/Tutorials]].