ROS 2 package

ROS 2 package – definition

A ROS 2 package is the smallest standard unit of software organisation, build, installation, dependency declaration, and distribution in the Robot Operating System 2 ecosystem. A package groups source code, configuration files, launch files, interface definitions, tests, and metadata required to provide a specific robot function.

In mobile robotics, a ROS 2 package commonly implements one bounded function of a UGV software stack. Examples include differential-drive control, LiDAR acquisition, IMU filtering, robot description publishing, navigation configuration, or camera-based perception. A package is not necessarily one executable. It can install several nodes, libraries, launch files, parameters, and custom message definitions.

ROS 2 packages use a package.xml manifest. The manifest declares the package name, version, license, maintainer, build tool, and dependencies. ROS 2 commonly uses package manifest format 3, specified by REP-149. Package naming conventions are described in REP-144.

How a ROS 2 package is structured

A package must contain enough metadata for ROS 2 build tools to resolve dependencies and install its resources into a workspace. The exact file layout depends on whether the package is built with CMake or Python tooling.

For C++ packages, the standard build type is ament_cmake. For Python packages, it is usually ament_python. Both build types are supported by colcon, the standard command-line build tool used in ROS 2 workspaces.

File or directory	Purpose
`package.xml`	Package metadata and dependency declarations.
`CMakeLists.txt`	Build instructions for an `ament_cmake` package.
`setup.py` / `setup.cfg`	Installation configuration and executable entry points for an `ament_python` package.
`src/`	C++ source code, libraries, and node implementations.
`launch/`	Launch files, often written in Python, that start and configure multiple ROS 2 nodes.
`config/`	YAML parameter files, including sensor and navigation settings.
`msg/`, `srv/`, `action/`	Custom ROS interfaces, generated during the build process when the package is configured as an interface package.

A package becomes discoverable after it is built and its workspace setup file is sourced. ROS 2 locates installed package resources through the ament resource index rather than by searching arbitrary source directories.

Package dependencies and interfaces

Dependency declarations are functional requirements, not only documentation. They allow build tools and dependency-management tools to determine which packages must be present before compilation, testing, or runtime execution.

A typical UGV package can declare several dependency categories in package.xml.

buildtool_depend identifies a build tool, usually ament_cmake or ament_python.
build_depend identifies dependencies required while compiling source code.
exec_depend identifies dependencies needed when the installed package runs.
test_depend identifies test frameworks and linting tools.
depend can replace separate build and execution declarations when both apply.

The following manifest fragment defines a C++ package that subscribes to laser scans and publishes velocity commands. The message types are defined by the sensor_msgs and geometry_msgs interface packages.

<package format="3">
  <name>ugv_obstacle_controller</name>
  <version>0.1.0</version>
  <description>Velocity control from 2D LiDAR data.</description>
  <maintainer email="[email protected]">Robotics Team</maintainer>
  <license>Apache-2.0</license>

  <buildtool_depend>ament_cmake</buildtool_depend>
  <depend>rclcpp</depend>
  <depend>sensor_msgs</depend>
  <depend>geometry_msgs</depend>

  <export>
    <build_type>ament_cmake</build_type>
  </export>
</package>

ROS 2 packages on Leo Rover and Raph Rover

On Leo Rover, packages can run on an onboard computer, commonly a Raspberry Pi, or on an external computer connected to the robot network. ROS 2 compatibility depends on the installed software image and the ROS 2 distribution supported by the manufacturer. Its four-wheel skid-steer drive architecture requires software components that publish suitable motion commands, commonly using the geometry_msgs/msg/Twist message type on a velocity command topic.

A practical Leo Rover workspace can separate hardware, perception, and autonomy functions into packages. This limits coupling between components and makes it possible to replace one sensor driver without rewriting the navigation configuration.

A base driver package publishes wheel odometry and accepts velocity commands.
A LiDAR package publishes sensor_msgs/msg/LaserScan data.
An IMU package publishes sensor_msgs/msg/Imu measurements.
A robot description package installs URDF/Xacro files and launch configuration for publishing robot transforms.
A navigation package installs Nav2 parameters, maps, behaviour trees, and launch files.

Raph Rover follows the same ROS 2 package model. Depending on the configuration, its larger payload capacity can support more demanding sensor sets or onboard compute hardware. Package boundaries remain useful when integrating RTK GNSS, 3D LiDAR, stereo cameras, or GPU-based perception nodes. The package itself does not define sensor rate, map resolution, or control frequency. These values are runtime parameters and must be selected according to the sensor specification, CPU capacity, network latency, and rover dynamics.

Building and running a package

A ROS 2 workspace normally uses src, build, install, and log directories. The command below builds only one package and overlays its installation on the current terminal environment.

cd ~/ros2_ws
colcon build --packages-select ugv_obstacle_controller
source install/setup.bash
ros2 pkg executables ugv_obstacle_controller
ros2 run ugv_obstacle_controller obstacle_controller

Launch files are normally installed with the package so that operators can start a repeatable rover configuration without manually invoking every node. Parameters should be kept outside compiled code where calibration or deployment-specific values are expected to change.

obstacle_controller:
  ros__parameters:
    scan_topic: /scan
    cmd_vel_topic: /cmd_vel
    stop_distance_m: 0.60
    control_rate_hz: 20.0

ROS 1 and ROS 2 differences

ROS 1 also uses packages and a package.xml manifest, but ROS 2 packages are built around ament, colcon, DDS-based middleware, and the ROS 2 client libraries such as rclcpp and rclpy. ROS 1 packages often use catkin, roscpp, and rospy. Direct reuse usually requires porting build files, APIs, launch files, and parameter handling.

Source: ROS 2 documentation – About packages; REP-149 – Package Manifest Format 3; REP-144 – ROS Package Naming.