REP: 108 Title: ROS Diamondback Variants Author: Ken Conley <[email protected]> Status: Active Type: Informational Content-Type: text/x-rst Created: 17-Jan-2011 Post-History: 17-Jan-2011

This REP describes the variants for the ROS Diamondback release. These new variants establish new entry points for the ROS installation process and provide organization of the ROS stack ecosystem.

ROS variants provide several roles for the ROS distributions:

• installation entry points for users
• installation entry points for robot configuration
• organize related stacks
• identity for institutions releasing stacks.

The ROS C Turtle distribution defined three main variants: base, pr2, and pr2all. These variants were originally established in the ROS Box Turtle release, when there were approximately only 30 stacks. Since then, the number of stacks has quadrupled to over 120. The number of institutions releasing stacks has also grown from one to seven. This growth, both in code and the ROS developer base, requires re-evaluation of the current variant configuration.

The growth of ROS and the related variants has also lead to the perception that ROS is bloated: users are not immediately aware that minimal configurations are possible. Similarly, effort was made during the ROS Diamondback development cycle to separate GUI dependencies into separate stacks; this enables new, lighter-weight, GUI-less variants.

Although a new user should be exposed to the wealth of libraries and tools available in ROS, we wish to make the user aware when they are choosing "bloated" configurations. GUI-less variants also enable lighter-weight "on robot" configurations, as well as easier porting of common ROS configurations to other platforms.

Finally, with the ROS distributions containing stacks from more institutions, we wish to start exploring making it easier for institutions to promote their identity and have their own configurations, such as institution-specific or robot-specific setups.

Although the rosdistro format is most closely associated with the building of Debian packages, it is actually much more general. The rosdistro format is a machine-readable specification of the software in a ROS distribution, how to access the source code for it, and the version information. The information is useful in several toolchains: build, installation, testing, and documentation. Variants play a role in most of these toolchains.

In the build toolchain, variants are used to define Debian 'metapackages'. In this regard, they can be thought of as ROS 'meta stacks': they associate libraries together. Similarly, in the installation toolchain, the variants are used as entrypoint for users.

There are two main installation toolchains: the Debian apt-get system and rosinstall. The apt-get system has a built-in model for ensuring dependencies are installed. rosinstall is currently agnostic to the code it installs: it does not know it is installing a stack, a package, or arbitrary code; it has no dependency information.

The testing toolchain is used to provide continuous integration of the software in the distribution as it is developed. Variants are currently not used here, though they may be used in the future to provide scoping for tests. ROS stacks are currently tested against every stack that depends on them. Popular stacks suffer from over-testing and also are the slowest to test as a result.

There are currently no plans to use variants in the documentation (rosdoc, wiki) toolchain. They could be used for categorization, but this is speculative.

Within the rosdistro file itself, variants also provide an organizational role. One variant can organize stacks together, while a higher-level variant can "extend" one or more variants to incorporate these stacks into its own definition.

We define three main entry points for ROS users:

• desktop-full (recommended)
• desktop
• ros-base

desktop-full provides a "batteries included" experience for users. This is the recommended installation for users as it will enable novice users to complete most entry tutorials without knowledge of the underlying library structure.

The desktop configuration is more minimal and collects the core robotics libraries and tools for users to use.

The ros-base configuration is an entry point for users wishing to use a "bare bones" configuration of ROS, such as those on embedded platforms.

Users may also choose robot-specific entry points, which simplify configuration when using ROS on a supported hardware platform. The definition of these entry points is left to the software maintainers for those robot platforms.

The rosdistro [1] format will be upgrade to support extends of multiple variants. If a variant extends another variant, it contains all of its stacks. For example:

- desktop:
    extends: [ros-full, robot, viz]

This new feature will better enable composition for higher-level variants.

Variants in Diamondback are required to be complete with respect to stack dependencies. If a variant contains stack A, and stack A depends on stack B, then stack B must be in the variant or in one of the extends variants.

Completeness can be tested with the variant_dependencies.py tool in the rosdistro package.

rosrun rosdistro variant_dependencies.py <distro>

The ros-base variant composes the ros and ros_comm stacks, which were separated as part of REP 100 [2]. This variant is not allowed to have any GUI dependencies.

- ros-base:
    stacks: [ros, ros_comm]

The ros-full variant adds the rx and documentation stacks, which provide useful tools that are not necessary for on-robot operation.

- ros-full:
    extends: ros-base
    stacks: [rx, documentation]

The robot variant is defined to be core, stable, ROS libraries for any robot hardware. It is the "general robotics" libraries of ROS. It may not contain any GUI dependencies.

- robot:
    extends: [ros-base]
    stacks: [common_msgs, common, diagnostics, driver_common,
      geometry, robot_model, executive_smach]

The capability variants organize commonly used libraries that are specific to a class of robots. We also define a simulators variant that provides an organizational role for higher-level variants. We discourage GUI dependencies in these stacks, if possible.

- mobile:
    extends: [robot]
    stacks: [navigation, slam_gmapping, laser_pipeline,
      perception_pcl]

- perception:
    stacks: [image_common, image_transport_plugins, image_pipeline,
      laser_pipeline, perception_pcl, vision_opencv]

- move-arm:
    extends: [robot, viz]
    stacks: [arm_navigation, kinematics, motion_planners,
      motion_planning_common, physics_ode, trajectory_filters,
      perception_pcl, pr2_controllers, control, pr2_mechanism,
      pr2_common]

- simulators:
    extends: [robot]
    stacks: [simulator_stage, simulator_gazebo, physics_ode,
      visualization_common, rx]

- viz:
    extends: [robot]
    stacks: [visualization_common, visualization, rx, image_common, laser_pipeline,
      executive_smach_visualization, diagnostics_monitors]

The desktop variants are main entry points for users. The desktop-full is a "batteries included" experience for users and attempts to collect stable, well-documented libraries. These libraries may be specific to certain classes of robots, such as mobile robots, though they are not specific to a particular robot. The desktop variant is more minimal and only provides the stacks in the robot variant, plus visualization and debugging tools. Both of these variants contain tutorials for the stacks they provide.

- desktop:
    extends: [ros-full, robot, viz]
    stacks: [ros_tutorials, common_tutorials, geometry_tutorials,
      visualization_tutorials]
- desktop-full:
    extends: [desktop, mobile, perception, simulators]

This REP also proposes the addition of institution-specific variants. Institution-specific variants must have the name of the institution to clearly identify them. The best practice recommendation is to use the name of the institution's ros-pkg repository, e.g. "wg-ros-pkg".

An institution is not required to have a variant, and they are mainly provided for convenience and identity.

Robot-specific variants may be defined. These robot-specific variants may be used to define both on-robot and off-robot (developer/end-user) configurations. At the time of this document, it is expected there will be variants for the Willow Garage PR2 and Fraunhofer IPA Care-O-bot, though more may be added during the Diamondback lifecycle.

For the sake of best practices, we enumerate the PR2-specific variants below, though their specific contents are not considered within the scope of this REP.

- pr2-base:
    extends: [mobile, perception, move-arm]
    stacks: [control, object_manipulation, robot_calibration, point_cloud_perception,
      pr2_common, pr2_controllers, pr2_mechanism, web_interface, pr2_calibration,
      pr2_navigation, pr2_kinematics, pr2_arm_navigation, pr2_object_manipulation,
      pr2_tabletop_manipulation_apps, ros_realtime, tabletop_object_perception, sql_database,
      geometry_experimental]
- pr2:
    extends: [pr2-base]
    stacks: [pr2_robot, pr2_ethercat_drivers, pr2_power_drivers, camera_drivers, imu_drivers,
      joystick_drivers, laser_drivers, linux_networking, sound_drivers, wifi_drivers]
- pr2-desktop:
    extends: [desktop-full, pr2-base]
    stacks: [pr2_gui, pr2_simulator, pr2_power_drivers, pr2_ethercat_drivers, geometry_visualization]
- pr2-applications:
    extends: [pr2, viz]
    stacks: [pr2_apps, pr2_common_actions, pr2_doors, pr2_navigation_apps, pr2_plugs,
      pr2_self_test, navigation_experimental]

Variant completeness is currently necessary due to rosinstall. As rosinstall is not aware of stack dependencies, it does not compute the transitive closure of dependencies for a stack. We anticipate upgrading rosinstall or the rosinstall-generation tools to compute this dependency information. This completeness constraint can be relaxed after this occurs.

The variants have been defined to enable on-robot vs. off-robot configurations. The main distinction between these configurations is the inclusion of GUI tools, which can be very heavyweight and unnecessary on the robot itself. Also, we have found it desirable to remove GUI tools from robots to prevent users from accidentally running them there.

Tutorials are included in the desktop variants to provide a seamless experience for new users. In the past, new users have been confused by the extra steps necessary for installing tutorials.

The C Turtle variants attempted to include most stacks within a variant. A notable example of this was the very inclusive pr2all variant. The pr2all variant was very volatile as its name implied that any PR2-related stack had to be added to it. This instability creates confusion for both developers and end users. For Diamondback, we have attempted to exclude unstable stacks from variants as it is simple to install these stacks separately.

Similarly, several stacks, such as driver stacks, have little value as drivers are tied to a specific hardware platform. We instead recommend that driver stacks only be included in variants that are robot specific.

C Turtle used the term base for general robotics libraries. We have chosen to abandon this term as the base variant had grown to contain many stacks, both GUI and non-GUI, as well as drivers. There is no equivalent variant in the Diamondback that contains the same set of stacks. For example, drivers are now only included in robot-specific variants.

There is a now a variant called robot, which has a similar semantic role but is far more limited in scope than the base variant. The robot variant contains stacks that are broadly useful robotics libraries, such as coordinate transform libraries and higher-level ROS concepts, like actions. Hardware-specific robot libraries and tools, such as GUI displays, have been moved to other variants. The goal of the robot variant is to remain small as it defines a minimum footprint of libraries for using ROS for robotics. Thus, it is also serves as a useful target to support when porting ROS to other platforms.

The variant has been removed as the PR2 software ecosystem is now too large for it to be easily defined. It was also frequently being used in non-PR2 configurations as it was often used to deploy more general research libraries.

The rosdistro format will be upgraded to support extends of multiple variants. As a result, old rosdistro libraries will not be able to read the new format. This is not expected to have a big impact as there are a limited number of rosdistro files. The Box Turtle release will no longer be supported after the Diamondback release, so there will be no effort to upgrade its separate toolchain.

This document has been placed in the public domain.