 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)
Description: How to organise files and directories within a robot support repositoryKeywords: industrial repository package layout files driver template
Tutorial Level: ADVANCED
Contents
Status
![/!\](/moin_static197/rostheme/img/alert.png "/!\"){kind=small}
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.
