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.

File and directory layout for robot support repositories (Implementation Notes)

Status

This page is unfinished.

Introduction

text.

Motivation

See this post on a related discussion (discourse.ros.org#18443).

Example(s)

The Fanuc stack has recently been re-organised and implements most of the suggestions described on this page and can be taken as an example of the suggested layout. Please refer to ros-industrial/fanuc at the ROS Industrial GitHub project.

Terminology

Overview of names and concepts used on this page.

• Model: model name of a manipulator. This can refer to a family or series of manipulators. Example: Motoman SH or Fanuc M-16iB.

• Variant: one specific variant of a manipulator within a family or series. Example: SH5 or M-16iB/20.

General

Follow ROS naming conventions

Idea
See Naming ROS Resources. In short: no spaces (use underscores, but sparingly), no capitals. Also, no slashes, dashes or other punctuation. Example: the Fanuc M-430iA/2F becomes m430ia2f in a package name.

Rationale
Impose a measure of consistency on names of artefacts, and in doing so, make them easier to find as their names are easier to guess or deduce. Additionally, all ROS tools expect packages to follow these conventions, making ROS Industrial packages proper citizens of the ROS ecosystem.

Prefix all packages with the name of the manufacturer

Idea
Example: fanuc_m10ia_support. For variant specific packages, suffix the variant after the model name. Example: fanuc_m430ia2f_moveit_config.

Rationale
Prefixing all packages with the manufacturers name will cause them to be easily found in listings (ROS wiki, OS package managers, rospack find, roslaunch fanuc_X .., etc), easily filtered and prevents name clashes with other packages. Additionally, the prefix immediately identifies a package as being part of the ROS Industrial support for that manufacturer.

One support package per manipulator family

Idea
Whenever possible, store all files for variants of one specific manipulator family in the same support package. Example: fanuc_m430ia_support contains launch files, meshes and urdfs for all supported variants of the M-430iA (/2F and /2P). Note the difference with 'normal' ROS practices, where a separate _description and _bringup package for each robot is customary.

Rationale
Creating one package per family keeps the number of packages manageable, while still maintaining a level of orthogonality between them. Separate packages per variant would result in a (very) large number of small packages, while a single large package for all supported variants would result in frequent re-releases.

Layout

text.

Overview

MFG
├── MFG_METAPACKAGE
├── MFG_resources
├── MFG_driver
├── MFG_VARIANT_A1_arm_navigation
├── MFG_VARIANT_B1_moveit_config
├── MFG_VARIANT_B2_moveit_config
├── MFG_MODEL_A_support
├── MFG_MODEL_B_support
└── [..]

Metapackage

This package is identical to all other ROS catkin meta-packages. The package name should be identical to the name of the stack. All other packages in the stack should be listed as <run_depends> of the meta-package. See also metapackages on the catkin wiki page.

MFG_METAPACKAGE
├── CMakeLists.txt
└── package.xml

Resources

May contain various artefacts (urdf, xacro, meshes, text files) that are of use to other packages within the repository. Examples of this are common colour and material definitions, shared (workcell) meshes or textures.

MFG_resources
├── meshes
│   └── [..]
├── urdf
│   ├── common_X.xacro
│   └── [..]
├── [..]
├── CMakeLists.txt
└── package.xml

Driver

Main package containing nodes required for interfacing with supported manipulators. May also contain code that is to be run on the controller of the manipulator (if required). In case the default industrial_robot_client nodes are insufficient, this package should also contain specialised (subclassed) versions.

In addition, this package should contain the base launchfiles for starting all ROS Industrial required nodes, with any required robot specific parameters.

If sufficiently different, controller-specific suffixes could be used. Example: motoman_fs100_driver.

MFG_driver
├── include
│   └── [..]
├── launch
│   ├── motion_(streaming|download)_interface.launch
│   ├── robot_interface_(streaming|download).launch
│   ├── robot_state.launch
│   └── [..]
├── src
│   └── [..]
├── [..]
├── CMakeLists.txt
└── package.xml

Arm Navigation

This is just an example for legacy arm_navigation packages. See the section on MoveIt Configurations for a non-deprecated variant-specific package.

MFG_VARIANT_arm_navigation
├── config
├── launch
├── CMakeLists.txt
└── package.xml

MoveIt Configuration

Similar to other variant-specific packages.

MFG_VARIANT_moveit_config
├── config
├── launch
├── CMakeLists.txt
└── package.xml

Support

Main package which adds support for a specific family of manipulators. Contains config files, launchfiles, meshes (collision and detailed), urdfs and any other needed files - for all supported variants.

Additionally, the support package may contain functionality (nodes) that is too specialised to be included in industrial_robot_client, but necessary for model specific support. Examples of such nodes could be filtering or transform nodes that process incoming data from a manipulator before passing it on to the other ROS Industrial components.

In all cases, care should be taken to ensure that the external interface (topics and / or services) of such support packages does not leak, ie: it should be identical to (or at least compatible with) all other support packages.

MFG_MODEL_support
├── config
│   ├── joint_names_VARIANT_B1.yaml
│   └── [..]
├── launch
│   ├── load_VARIANT_B1.launch
│   ├── robot_interface_streaming_VARIANT_B1.launch
│   ├── robot_state_visualize_VARIANT_B1.launch
│   ├── test_VARIANT_B1.launch
│   └── [..]
├── meshes
│   ├── VARIANT_B1
│   │   ├── collision
│   │   │   ├── link_1.stl
│   │   │   ├── link_2.stl
│   │   │   └── [..]
│   │   └── visual
│   │       ├── link_1.stl
│   │       └── [..]
│   ├── VARIANT_B2
│   │   └── [..]
│   └─── [..]
├── urdf
│   ├── VARIANT_B1.urdf
│   ├── VARIANT_B1.xacro
│   ├── VARIANT_B1_macro.xacro
│   └── [..]
├── CMakeLists.txt
└── package.xml

Notes

text.