πŸ—ƒοΈHome Directory Magic

gayatri kumargayatri kumar
6 min read

🧱 Why Do We Need a Workspace?

Think of our robotsβ€”MayorBot, DoorBot, ChatterBot... Imagine they each live somewhere in Robot Town. But where do their files live?

Just like City Hall maintains a master cabinet where each robot has its folder, ROS2 uses a workspace to group, build, and run these bots as a team.


πŸ›οΈ Real-Life Analogy

  • Workspace = Filing Cabinet in City Hall πŸ›οΈ

  • Package = One folder for a citizen robot (like a record for MayorBot)

  • Source Folder = A shelf inside the cabinet where all robots' files are kept

  • Build & Install Folders = Assembly and action stations for robot teams


πŸ—‚οΈ ROS2 Workspace Layout

Here's how our current town is laid out in your system:

robot_town_ws/              ← Filing cabinet (Workspace)
β”œβ”€β”€ src/                    ← Blueprints and designs (Source code of packages)
β”‚   β”œβ”€β”€ mayor_bot/
β”‚   β”œβ”€β”€ door_bot/
β”‚   β”œβ”€β”€ chatter_bot/
β”‚   β”œβ”€β”€ weather_bot/
β”‚   β”œβ”€β”€ umbrella_bot/
β”‚   β”œβ”€β”€ mood_bot/
β”‚   └── guard_bot/
β”œβ”€β”€ build/                  ← Workshop where bots are assembled
β”œβ”€β”€ install/                ← Deployment shelf (ready-to-run bots)
└── log/                    ← All logs and construction records

This folder is created automatically when you run colcon build. You only have to create the src/ manually!


πŸ“¦ Creating a Clean Workspace

Let’s walk through building a brand-new City Hall!

βœ… Step 1: Create the cabinet (workspace)

mkdir -p ~/robot_town_ws/src
cd ~/robot_town_ws

βœ… Step 2: Add a citizen (package)

cd ~/robot_town_ws/src
ros2 pkg create --build-type ament_python --node-name time_bot time_bot

You now have a folder time_bot inside src/.


πŸ”§ What's in a Package?

Let’s open the time_bot folder and peek inside:

time_bot/
β”œβ”€β”€ package.xml       ← Declaration: What this bot/package is
β”œβ”€β”€ setup.py          ← Installation script
β”œβ”€β”€ resource/
β”‚   └── time_bot      ← Empty file needed for ament indexing
└── time_bot/
    └── __init__.py   ← Where we’ll write the bot’s code

Let’s rename __init__.py to something meaningful, like clock.py, and write a quick script in Part 2.


πŸ› οΈ colcon build – Your Town Assembler

When you run this:

cd ~/robot_town_ws
colcon build

ROS2 will:

  1. Visit each package in src/

  2. Build and assemble them into build/ and install/

  3. Update launch paths and executables

This is like printing official ID cards and building instructions for each bot!


πŸ§™β€β™‚οΈ setup.bash – The Town Spellbook

Running:

source install/setup.bash

...tells the terminal:

β€œHey! I live in Robot Town now. I know the paths to all my bots.”

If you skip this, your shell will forget where to find ros2 run chatter_bot speak.

Always source setup.bash after building or when opening a new terminal window.


πŸ“¦ Multiple Packages in One Workspace

You can have as many bots/packages as you want inside one workspace:

robot_town_ws/
└── src/
    β”œβ”€β”€ mayor_bot/
    β”œβ”€β”€ door_bot/
    └── new_bot/

This keeps everything tidy and lets you build or run bots together.


πŸ”„ Can I Have Multiple Workspaces?

Yes! Each workspace is a separate cabinet.

Example:

~/robot_town_ws/         ← Your main workspace
~/robot_lab_ws/          ← For experiments
~/robot_sandbox_ws/      ← For messy temporary bots

Each time, just:

cd ~/robot_lab_ws
source install/setup.bash

That activates the workspace you’re in. You can chain them too β€” we’ll explore that later!


🧠 TL;DR Summary

ConceptMeaning (Robot Town)
WorkspaceCity Hall's filing cabinet
src/Where each robot's files live
build/Workshop for compiling stuff
install/Deployment zone (ready-to-run)
setup.bashThe spell that tells terminal where bots are

πŸ“¦ Recap: Where We Left Off

We created a workspace: robot_town_ws/, and added several bots (packages) into its src/ folder:

robot_town_ws/
└── src/
    β”œβ”€β”€ mayor_bot/
    β”œβ”€β”€ door_bot/
    β”œβ”€β”€ chatter_bot/
    β”œβ”€β”€ weather_bot/
    β”œβ”€β”€ umbrella_bot/
    β”œβ”€β”€ mood_bot/
    β”œβ”€β”€ guard_bot/
    └── time_bot/       ← Our new addition

Let’s now:

  1. Write the TimeBot code

  2. Build the entire town again

  3. Test everything is in place

  4. Understand how this scales with more bots


πŸ› οΈ Step 1: TimeBot Code (Logging Current Time)

Go to the file robot_town_ws/src/time_bot/time_bot/clock.py

touch robot_town_ws/src/time_bot/time_bot/clock.py
chmod +x robot_town_ws/src/time_bot/time_bot/clock.py

Paste this into clock.py:

import rclpy
from rclpy.node import Node
from datetime import datetime

class TimeBot(Node):
    def __init__(self):
        super().__init__('time_bot')
        self.create_timer(2.0, self.tell_time)  # Every 2 seconds

    def tell_time(self):
        now = datetime.now().strftime("%H:%M:%S")
        self.get_logger().info(f"The time is {now}")

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

⏰ This bot announces the current time every 2 seconds. Think of it as the town's official clock tower ringing!


πŸ“„ Step 2: Update setup.py

Go to: robot_town_ws/src/time_bot/setup.py
Update the entry_points section like this:

entry_points={
    'console_scripts': [
        'clock = time_bot.clock:main',
    ],
},

This tells ROS2: "If someone runs ros2 run time_bot clock, start the main() function in clock.py."


πŸ—οΈ Step 3: Build the Entire Town

Now we’ll use colcon to build all bots at once!

cd ~/robot_town_ws
colcon build

You’ll see something like:

Starting >>> time_bot
Finished <<< time_bot
...
Summary: 8 packages finished

Now activate the workspace:

source install/setup.bash

βœ… Don't forget: every new terminal needs this line or your bots won’t be found.


πŸ€– Step 4: Run TimeBot!

ros2 run time_bot clock

Output:

[INFO] [time_bot]: The time is 15:12:03
[INFO] [time_bot]: The time is 15:12:05

πŸŽ‰ Your City Hall clock is ticking!


πŸ“ Folder Review: What Happened After Build?

After colcon build, 3 new folders appeared:

robot_town_ws/
β”œβ”€β”€ build/      ← Temporary compiled files
β”œβ”€β”€ install/    ← Installed packages, executables, paths
β”œβ”€β”€ log/        ← Logs of build actions

These are like:

  • πŸ› οΈ build/ β†’ The robot parts

  • πŸ“¦ install/ β†’ Fully assembled, ready-to-run bots

  • πŸ““ log/ β†’ Diary of the assembly process


πŸ” Adding More Bots

Let’s say you want to add a new bot: music_bot

You just:

cd ~/robot_town_ws/src
ros2 pkg create --build-type ament_python --node-name sing music_bot

...write the code, update setup.py, then:

cd ~/robot_town_ws
colcon build
source install/setup.bash

No need to create a new workspace β€” just drop it in src/ and build again!


πŸ§ͺ Mini Project Challenge: Master Workspace Organizer

Your task:

  • Organize all bots (MayorBot, ChatterBot, etc.) inside one workspace

  • Run any bot from this unified setup using ros2 run

  • Ensure each has a clean folder and setup

Bonus:

  • Create a bot like cleaning_bot that logs every 10 seconds: "Checking cabinet integrity..."

🧠 TL;DR Recap

ConceptWhat it Means in Robot Town
src/All robot folders (packages)
colcon buildAssembles every robot
setup.bashActivates your workspace
entry_pointsDefines run commands for each bot
One workspaceCan hold many packages

πŸš€ What’s Next: Powering Bots Up Together (Launch Files)

Imagine waking up all the bots in Robot Town with a single sunrise alarm! Next, we’ll learn how to start multiple bots at once using launch files.
With one command, you’ll launch bots like TrafficBot and LightBot togetherβ€”making Robot Town buzz with activity! πŸŒ…πŸ€–βš‘

Get ready to make your robots work together

10
Subscribe to my newsletter

Read articles from gayatri kumar directly inside your inbox. Subscribe to the newsletter, and don't miss out.

Written by

gayatri kumar
gayatri kumar