Uses of Variants

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.

End-user entry points

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.

rosdistro format

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.

Variant completeness

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>

Variants

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

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

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

- 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]

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

- 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]

Completeness of Variants

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.

On-robot vs. off-robot

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

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.

Removal of stacks from variants

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.

robot vs. base

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.

pr2all

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.