Chapter 2: The ROS 2 Development Environment

2.1From Map to City

By the time you finished Chapter 1, you had ARCHO's architectural map in your head: you knew what a Node was, what a Topic was, when to use a Service, and when to use an Action. But a map, by itself, never moves a robot. Now it's time to actually enter the city: open a folder on your own system, write a Python file, and for the first time see the word Node — which until now was just an abstract concept — become a real, living process that you can see in the terminal, stop, and run again.

This chapter has three stops: first we learn what a Workspace is and why every project needs one; then we move into Package, the smallest buildable unit in ROS 2; and finally we read the ARCHO team's first real Node line by line, build it, and run it on the system.

2.2Workspace — The Project's Factory

The problem: a messy folder called Desktop

Imagine it's the ARCHO team's first day of writing code. One team member, without much thought, dumps everything straight onto the Desktop: camera.cpp, main.py, lidar_driver.cpp, motor.py, map.yaml. A week later, nobody knows which file belongs to which part of the robot, which version is the latest, or which one should even be compiled. This is exactly the wall every team runs into, sooner or later, without a clear folder structure.

The solution is simple: create a main folder and keep everything organized inside it. ROS 2 has formalized exactly this idea under the name Workspace.

A fully set-up Workspace ends up with four folders inside it. This is what it looks like once everything has been created and built at least once:

archo_ws/
├── src/
├── build/
├── install/
└── log/

This is a diagram of a folder structure, not something you type into a terminal. You do not create all four of these folders yourself. In fact, only one of them is yours to make — the other three are generated automatically. Here's the split:

Step 1 — Create the Workspace yourself

You create only the src folder. Everything else appears later, on its own. Run this in your terminal:

mkdir creates a directory; -p also creates any missing parent folders along the way (here, archo_ws itself, before creating src inside it) and does not complain if the folder already exists. ~ is your home directory. At this point, your Workspace looks like this:

archo_ws/
└── src/

That's it — no build, install, or log yet, because nothing has been built.

Step 2 — Let colcon generate the rest

Once there's at least one Package inside src (you'll create one in the next section), running the build tool from inside archo_ws:

colcon build

automatically creates build/, install/, and log/ for you. You never create these three by hand, and you should not normally edit files inside them — they get regenerated every time you build. This is covered in more detail once you build your first Package later in this chapter.

Now let's check your own system

Right now, since you've only created the folder and haven't built anything yet, your Workspace should still look empty inside src:

In the next section you'll create your first Package inside src, and later in this chapter you'll run colcon build for the first time — that's the moment build, install, and log will appear next to src, matching the four-folder diagram shown earlier.

2.3Package — The Organized Unit of Code

If the Workspace is the factory, a Package is one of the units inside that factory. A real robot like ARCHO usually has several independent Packages, not one giant folder:

archo_ws/
└── src/
    ├── archo_description   # Physical model and URDF
    ├── archo_bringup       # Launches the whole system
    ├── archo_control       # Motor and motion control
    ├── archo_navigation     # Nav2 configuration and path planning
    ├── archo_sensors       # Camera, LiDAR, IMU drivers
    └── archo_interfaces    # Custom Message/Service/Action definitions

None of these folders exist on your system yet — you haven't created a single Package so far, and ROS 2 does not create them for you automatically. A Package is created with the ros2 pkg create command. Let's create the ARCHO team's first Package, archo_bringup, as a Python Package:

Run this from inside ~/archo_ws/src — that's where every Package lives. ros2 pkg create generates a new folder named after the Package, already containing the standard files a Python ROS 2 Package needs (package.xml, setup.py, and so on). You do not create those files by hand; the command does. Now go into the Package and look at its structure:

ROS Package
└── Python Module
    └── ROS Nodes

Important Package Files

To figure out whether a Package was built with Python or C++, just check this:

grep build_type package.xml
# <build_type>ament_python</build_type>   → Python
# <build_type>ament_cmake</build_type>    → usually C++

2.4Your First Real Node — Line by Line

ros2 pkg create did not write any Node code for us — it only generated the empty scaffolding (folders and boilerplate files). We still have to write the Node ourselves. Create a new file at ~/archo_ws/src/archo_bringup/archo_bringup/simple_node.py with the content shown below, then open setup.py and add one line inside entry_points so ROS 2 knows this file contains a runnable Node:

entry_points={
    'console_scripts': [
        'simple_node = archo_bringup.simple_node:main',
    ],
},

This one line carries three important messages you should be able to unpack separately:

Now let's open the contents of simple_node.py:

import rclpy
from rclpy.node import Node


class SimpleNode(Node):
    def __init__(self):
        super().__init__('simple_node')
        self.get_logger().info('Hello from ARCHO — first node alive!')


def main(args=None):
    rclpy.init(args=args)
    node = SimpleNode()
    rclpy.spin(node)
    node.destroy_node()
    rclpy.shutdown()


if __name__ == '__main__':
    main()

Now let's go through it line by line — the way an experienced engineer would review a new teammate's code.

import rclpy

rclpy is the core ROS 2 library for Python — short for ROS Client Library for Python. Its C++ counterpart is called rclcpp. Without rclpy, your Python program is just an ordinary script with no way to connect to the ROS 2 network.

from rclpy.node import Node

Here we import the ready-made Node class — the same class we discussed in Chapter 1. This class already provides capabilities like creating Publishers, Subscribers, Services, Actions, Parameters, Timers, and Loggers; we simply inherit from it.

class SimpleNode(Node): and super().__init__('simple_node')

There's an important distinction here that a lot of beginners mix up: SimpleNode is the Python class name, but simple_node (inside super().__init__) is the name this Node is known by on the ROS 2 network. That's why, when you later run ros2 node list, you'll see /simple_node, not SimpleNode.

self.get_logger().info(...)

This line prints a message using ROS's built-in logging system. You could use Python's print() instead, but the Logger has several advantages: it shows the Node's name, marks the message's severity level, timestamps it, and lets you follow the messages on the /rosout Topic as well.

The main() Function — The Heart of Execution

The order of the five lines inside main() matters a great deal, and this same pattern always repeats:

And finally, at the end of the file, if __name__ == '__main__': main() is just a standard Python idiom: if this file is run directly (not through ros2 run), main() still gets called.

2.5Building and Running with colcon

When a file inside src changes, ROS still doesn't know about the installed version yet. We need to build the Workspace from the root:

cd ~/archo_ws
colcon build --packages-select archo_bringup

After building, you need to "activate" the Workspace so the terminal knows where these Packages live:

source install/setup.bash

Now run the Node:

The Node stays running after printing the message — this is normal, because rclpy.spin(node) is still executing. Press Ctrl+C to stop it.

2.6Observing a Node from Outside

This section covers one of the important habits you should build from the very start: check every Node you run from a second terminal as well. Keep the first terminal open (the Node is still running), open a second terminal, and:

source /opt/ros/jazzy/setup.bash
cd ~/archo_ws
source install/setup.bash
ros2 node list

You should see /simple_node. For more complete information:

ros2 node info /simple_node

The output shows a list of this Node's Subscribers, Publishers, Service Servers and Clients, and Action Servers and Clients — for now, they're all empty, since this Node only prints a message. But you'll probably see two internal ROS Topics as well: /parameter_events and /rosout.

ros2 topic echo /rosout

2.7Chapter 2 Summary

You've walked the whole path so far: you created a Workspace, found a Package inside it and dissected it, read ARCHO's first real Node line by line, built it with colcon build, ran it with ros2 run, and inspected it live from a second terminal. This was the first time you touched Chapter 1's abstract concepts on your own real system.

Connection to the Main Project

ARCHO Project now has its first Package and first real Node — it still only prints a "hello" message, but the Workspace and Package infrastructure is ready for us to turn this quiet Node into a real Publisher in the next chapter.

What the Next Chapter Adds

In Chapter 3, we'll turn this same simple_node into a Publisher that publishes a Message on a real Topic every second, and build a separate Subscriber to receive it. For the first time, you'll see with your own eyes two independent Nodes — exactly as described in Chapter 1 — talking to each other.

Chapter 2 Glossary

Workspace

The main folder holding all the Packages, build files, and outputs of a ROS 2 project.

Package

The smallest organized, buildable unit in ROS 2; can contain Nodes, Launch files, Parameters, and more.

colcon

The official ROS 2 build tool that compiles and installs the Packages inside src.

rclpy

The ROS 2 client library for Python; the bridge between a Python program and the ROS 2 network.

spin()

The function that keeps a Node alive and waiting for ROS events (Messages, Services, Timers, Actions).

Logger

ROS's built-in logging system, which publishes messages on the /rosout Topic in addition to printing them in the terminal.

entry_points

The part of setup.py that links a Node's runnable name to its file and main function.

Common Chapter 2 Mistakes — Summary

• Forgetting source install/setup.bash after opening a new terminal.
• Confusing the Python class name (SimpleNode) with the ROS network Node name (simple_node).
• Removing rclpy.spin() and being surprised the Node shuts down immediately.
• Building the entire Workspace with a plain colcon build instead of --packages-select on large projects, wasting a lot of time.