ROS 2 workspace

ROS 2 workspace – definition

A ROS 2 workspace is a directory structure used to organize, build, install, and source one or more ROS 2 packages. It provides the local development environment in which source code, interface definitions, launch files, configuration files, and package metadata are compiled or interpreted as a consistent software set.

In ROS 2, a workspace is commonly built with colcon, the command-line build tool documented by ROS. A standard workspace contains a src/ directory for package source code. After a build, colcon creates build/, install/, and log/ directories. The resulting installation space is sourced to make packages, executables, launch files, message definitions, and environment hooks available in the current shell.

For mobile robotics and unmanned ground vehicles (UGVs), a ROS 2 workspace is the integration boundary between the robot base, sensor drivers, state estimation, perception, navigation, and mission-specific applications. A Leo Rover or Raph Rover deployment can use separate workspaces for hardware drivers, robot description files, navigation configuration, and experimental algorithms. This separation improves reproducibility and makes dependency management explicit.

Workspace structure and build artifacts

The conventional ROS 2 workspace layout is based on source, build, install, and log spaces. Build, install, and log artifacts should normally not be version-controlled. Build outputs depend on the target operating system, compiler, ROS 2 distribution, package dependencies, and build options.

Directory	Purpose	Typical contents
`src/`	Source space	ROS 2 packages, Git repositories, `package.xml`, `CMakeLists.txt`, Python setup files
`build/`	Build space	CMake cache files, generated code, intermediate object files
`install/`	Install space	Executables, shared libraries, package indexes, launch files, environment setup scripts
`log/`	Build logs	Per-package build, test, and command logs generated by `colcon`

A typical workspace is initialized as follows. The command assumes that a ROS 2 underlay, such as ROS 2 Humble, has already been installed and sourced.

source /opt/ros/humble/setup.bash

mkdir -p ~/ugv_ws/src
cd ~/ugv_ws

colcon build --symlink-install
source install/setup.bash

The --symlink-install option is useful during development. For supported package types, it allows changes to selected non-compiled resources, such as Python modules or launch files, to be reflected without copying all files into the install space. Its behavior depends on package type and build configuration.

Underlays, overlays, and package resolution

ROS 2 supports layered environments. An installed ROS 2 distribution is usually the underlay. A locally built workspace becomes an overlay after its setup script is sourced. Packages in the overlay can extend or override packages available in the underlay.

The sourcing order is technically important. The underlay must be sourced before building an overlay, and the overlay must be sourced after the underlay when running nodes from the local workspace.

source /opt/ros/humble/setup.bash
source ~/ugv_ws/install/setup.bash

ros2 pkg prefix rover_bringup
ros2 launch rover_bringup navigation.launch.py

Overlay workspaces are useful when a UGV project requires a modified driver, a patched navigation package, or a custom robot description. However, overriding a package can introduce ABI, API, or runtime compatibility problems. ROS 2 documentation recommends understanding override behavior, especially for packages that expose C++ headers, Python modules, or generated interfaces.

Package metadata and build systems

Every ROS 2 package contains a package.xml manifest. The manifest declares the package name, version, license, maintainers, and dependency categories. Package manifests follow the ROS package format defined by REP-149. ROS 2 packages commonly use the ament_cmake build system for C++ or ament_python for Python.

A mobile robot workspace commonly groups packages by system responsibility. This makes the hardware-to-application dependency chain easier to inspect and test.

rover_description – URDF/Xacro model, frames, meshes, and robot-state publication.
rover_bringup – launch files that start base drivers, sensors, transforms, and diagnostics.
rover_navigation – Nav2 parameters, costmap configuration, behavior trees, and map files.
rover_perception – LiDAR, camera, IMU, GNSS/RTK, or computer vision processing nodes.
rover_interfaces – custom ROS 2 messages, services, and actions when standard interfaces are insufficient.

Use on Leo Rover and Raph Rover

Leo Rover can be integrated with ROS 2 and uses a four-wheel differential-drive base. ROS 2 distribution compatibility depends on the operating-system image and the rover packages used. A workspace for Leo Rover can contain the base integration, a URDF model with base_link and sensor frames, and configuration for odometry, IMU fusion, SLAM, or Nav2. The rover is not autonomous out of the box. Autonomous operation requires an integrated navigation stack, valid transforms, sensor drivers, localization or SLAM, and safety logic appropriate to the deployment.

For example, a Leo Rover research workspace may build a LiDAR driver, an EKF configuration based on robot_localization, and a Nav2 bringup package. The workspace should define consistent frame names such as map, odom, base_link, and sensor-specific frames. TF2 timestamp consistency is critical because navigation and sensor fusion depend on time-aligned transforms.

Raph Rover can use the same ROS 2 workspace model. A separate overlay is often appropriate when a deployment uses platform-specific motor controllers, power monitoring, GNSS receivers, or perception hardware. The application-level packages can remain shared if topic interfaces, coordinate frames, and robot kinematics are defined consistently.

Key operational considerations

A ROS 2 workspace does not define a fixed topic frequency, map update rate, sensor resolution, or navigation performance. Those values are properties of individual nodes, hardware drivers, QoS policies, CPU resources, and network conditions. Engineers should record them in package configuration and validate them with ROS 2 introspection tools.

Use ros2 pkg list and ros2 pkg prefix <package> to verify package discovery.
Use ros2 node list, ros2 topic list, and ros2 topic hz <topic> to inspect the running graph.
Run colcon test and colcon test-result --verbose before deploying changes to a rover.
Pin repository revisions and ROS 2 distribution versions in documentation, Dockerfiles, or CI pipelines.

Normative references and standards

The following primary sources define the package, build, and distribution concepts used in a ROS 2 workspace.