Week 2: Workspace & Package Management

Week Overview

Understanding ROS2 Workspaces

What is a Workspace?

A ROS2 workspace is a directory structure where you organize, build, and develop ROS2 packages. It provides an isolated environment for your robotics projects.

# Navigate to home directory
cd ~

# Create workspace directory
mkdir -p ros2_ws/src

# Navigate into workspace
cd ros2_ws

# Verify structure
tree -L 2

# Source ROS2 Jazzy (underlay)
source /opt/ros/jazzy/setup.bash

# Verify ROS2 is sourced
echo $ROS_DISTRO
# Output: jazzy

# From workspace root (ros2_ws)
colcon build

# Expected output:
# Starting >>> (nothing to build yet)
# Summary: 0 packages finished

# Source the overlay
source install/setup.bash

# Or use local_setup.bash (doesn't source underlay)
# source install/local_setup.bash

Understanding ROS2 Packages

What is a Package?

A ROS2 package is the smallest unit of organization for ROS2 code. It contains:

• Source code (Python, C++, or both)
• Configuration files
• Launch files
• Message/service/action definitions
• Documentation
• Tests

my_package/
    package.xml       # Package manifest
    setup.py          # Python package setup
    setup.cfg         # Package configuration
    resource/         # Resource marker
        my_package
    my_package/       # Python module
        __init__.py
    launch/           # Launch files (optional)
    config/           # Configuration files (optional)
    test/             # Unit tests (optional)

# Navigate to src directory
cd ~/ros2_ws/src

# Create a Python package
ros2 pkg create --build-type ament_python my_robot_controller

# With dependencies
ros2 pkg create --build-type ament_python my_robot_controller \
  --dependencies rclpy std_msgs geometry_msgs

# Create with example node
ros2 pkg create --build-type ament_python my_robot_controller \
  --dependencies rclpy \
  --node-name my_first_node

<?xml version="1.0"?>
<package format="3">
  <name>my_robot_controller</name>
  <version>0.0.1</version>
  <description>My first ROS2 package</description>
  <maintainer email="student@uop.edu.jo">Student Name</maintainer>
  <license>Apache-2.0</license>

  <!-- Build dependencies -->
  <depend>rclpy</depend>
  <depend>std_msgs</depend>
  <depend>geometry_msgs</depend>

  <buildtool_depend>ament_python</buildtool_depend>

  <export>
    <build_type>ament_python</build_type>
  </export>
</package>

from setuptools import find_packages, setup

package_name = 'my_robot_controller'

setup(
    name=package_name,
    version='0.0.1',
    packages=find_packages(exclude=['test']),
    data_files=[
        ('share/ament_index/resource_index/packages',
            ['resource/' + package_name]),
        ('share/' + package_name, ['package.xml']),
    ],
    install_requires=['setuptools'],
    zip_safe=True,
    maintainer='Student Name',
    maintainer_email='student@uop.edu.jo',
    description='My first ROS2 package',
    license='Apache-2.0',
    tests_require=['pytest'],
    entry_points={
        'console_scripts': [
            'my_first_node = my_robot_controller.my_first_node:main',
        ],
    },
)

'executable_name = package_name.module_name:function_name'

Creating Your First Node

Writing a Simple Publisher Node

Create my_robot_controller/my_first_node.py:

#!/usr/bin/env python3
import rclpy
from rclpy.node import Node
from std_msgs.msg import String


class MyFirstNode(Node):
    def __init__(self):
        super().__init__('my_first_node')
        self.publisher_ = self.create_publisher(String, 'robot_news', 10)
        self.timer_ = self.create_timer(1.0, self.publish_news)
        self.counter_ = 0
        self.get_logger().info('My First Node has been started!')

    def publish_news(self):
        msg = String()
        msg.data = f'Hello ROS2! Message #{self.counter_}'
        self.publisher_.publish(msg)
        self.get_logger().info(f'Publishing: "{msg.data}"')
        self.counter_ += 1


def main(args=None):
    rclpy.init(args=args)
    node = MyFirstNode()

    try:
        rclpy.spin(node)
    except KeyboardInterrupt:
        pass
    finally:
        node.destroy_node()
        rclpy.shutdown()


if __name__ == '__main__':
    main()

Code Explanation

import rclpy                    # ROS2 Python client library
from rclpy.node import Node     # Base node class
from std_msgs.msg import String # String message type

self.publisher_ = self.create_publisher(
    String,         # Message type
    'robot_news',   # Topic name
    10              # Queue size
)

self.timer_ = self.create_timer(
    1.0,                    # Timer period in seconds
    self.publish_news       # Callback function
)

Building and Running Your Package

Building the Package

# Navigate to workspace root
cd ~/ros2_ws

# Build all packages
colcon build

# Build specific package
colcon build --packages-select my_robot_controller

# Build with symlink install (faster for Python)
colcon build --packages-select my_robot_controller --symlink-install

Sourcing the Workspace

# Source the overlay
source ~/ros2_ws/install/setup.bash

# Verify package is available
ros2 pkg list | grep my_robot_controller

Running Your Node

# Run the node
ros2 run my_robot_controller my_first_node

# Expected output:
# [INFO] [my_first_node]: My First Node has been started!
# [INFO] [my_first_node]: Publishing: "Hello ROS2! Message #0"
# [INFO] [my_first_node]: Publishing: "Hello ROS2! Message #1"

Testing the Node

Open a new terminal and:

# Source workspace
source ~/ros2_ws/install/setup.bash

# List topics
ros2 topic list

# Echo the topic
ros2 topic echo /robot_news

# Get topic info
ros2 topic info /robot_news

# Check publishing rate
ros2 topic hz /robot_news

Package Dependencies

Types of Dependencies

Common ROS2 Dependencies

• rclpy: ROS2 Python client library (always needed)
• std_msgs: Standard messages (String, Int, Float, etc.)
• geometry_msgs: Geometric messages (Pose, Twist, Transform)
• sensor_msgs: Sensor messages (Image, LaserScan, Imu)
• nav_msgs: Navigation messages (Odometry, Path)
• tf2_ros: Transform library

Colcon Build System

Understanding Colcon

Colcon (collective construction) is the build system for ROS2. It:

• Builds multiple packages in correct order
• Handles dependencies automatically
• Supports parallel builds
• Works with different build types (CMake, Python)
• Provides testing integration

Colcon Commands Reference

# Build all packages
colcon build

# Build specific package
colcon build --packages-select package_name

# Build up to specific package
colcon build --packages-up-to package_name

# Clean build
colcon build --cmake-clean-cache

# Test packages
colcon test

# Show test results
colcon test-result --all

# List packages
colcon list

Best Practices

# 1. Create/modify code
# 2. Build
colcon build --symlink-install
# 3. Source
source install/setup.bash
# 4. Test
ros2 run my_package my_node
# 5. Commit
git add . && git commit

Troubleshooting

# Error: Package 'my_package' not found

# Solution 1: Build the package
cd ~/ros2_ws
colcon build --packages-select my_package

# Solution 2: Source workspace
source ~/ros2_ws/install/setup.bash

# Solution 3: Check package name
ros2 pkg list | grep my_package

# Error: Executable 'my_node' not found

# Solution: Check setup.py entry_points
# Make sure the executable is listed in console_scripts

# Error: ModuleNotFoundError

# Solution 1: Ensure __init__.py exists
touch ~/ros2_ws/src/my_package/my_package/__init__.py

# Solution 2: Rebuild package
colcon build --packages-select my_package --symlink-install

# Error: Package 'std_msgs' not found

# Solution 1: Add to package.xml
<depend>std_msgs</depend>

# Solution 2: Install missing package
sudo apt install ros-jazzy-std-msgs

# Solution 3: Update rosdep
rosdep update
rosdep install --from-paths src --ignore-src -r -y

Week 2 Project: Robot Controller Package

Requirements

Bonus Challenges

Grading Rubric

Resources & References