Setting Up Raspberry Pi for ROS 2 With Docker - a Headless Configuration Guide

In this guide, I'll walk you through how I set up my Raspberry Pi 4 to run ROS 2 inside Docker containers without needing a monitor or keyboard. This headless setup has become my go-to approach for robotics projects where I want to remotely access and control the Pi.

What you'll need

Before we start, here's what I used for this setup:

1. Raspberry Pi 4 (I recommend the 4GB or 8GB model)
2. MicroSD card (I used a 32 GB class 10, but go bigger if you can)
3. Power supply for the Pi 4
4. A computer with an SD card reader
5. Android device (for finding the Pi's IP address)
6. Stable internet connection

Rather than repeating the basic installation steps here, I'll direct you to follow the official Raspberry Pi documentation: Installing the Operating System

Here's what I do differently for this setup:

1. I always choose Raspberry Pi OS Lite (64-bit) - no desktop environment means more resources for our containers
2. During the imaging process with the Raspberry Pi Imager, make sure to:
3. Enable SSH in the advanced options (crucial for headless access)
4. Set up my username and password
5. Configure my WiFi credentials
6. Set up my locale settings

I prefer the 64-bit Lite version because:

1. It gives me better performance with containerized applications
2. Uses less memory without the desktop environment
3. Works perfectly with Docker and ROS 2 containers
4. Feels more like a proper server setup

Once I've flashed the SD Card:

1. I insert it into my Raspberry Pi 4
2. Connect the power supply and let it boot
3. Wait about 2-3 minutes for the initial setup to complete
4. The Pi automatically connects to my configured WiFi network

Since I'm running the Pi headless, I need to find out what IP address my Pi has been assigned. I use my Android phone for this.

My Android Network scanning approach:

1. I installed a network scanner application on my Android device. My favorites are:
2. WOM WiFi by Network Scanner (easy-to-use)
3. Network Scanner by First Row (simple and reliable)
4. Fing by Fing Limited (feature-rich)
5. I make sure my phone is on the same WiFi network as my Pi
6. I run a network scan (using WOM WiFi) and look for:
7. Hostname: "raspberrypi" (or whatever custom name I set)
8. Manufacturer: "Raspberry Pi Foundation"
9. MAC addresses startign with B8:27:EB, DC:A6:32 or E4:5F:01
10. I note down the IP address (something like 192.168.1.100)

Pro tip: I usually see my Pi appear in the scan within 1-2 minutes of booting. If it doesn't show up immediately, I wait a bit and scan again.

Now comes the fun part - connecting to my Pi remotely!

From my Linux host machine (same for Mac machine)

I open Terminal and use the command:

For example:

From my Windows machine

I can open Command Prompt or PowerShell and type:

What happens on First Connection

1. I see a message about host authenticity:

1. I type yes and hit Enter
2. I enter the password I set during the OS installation
3. Success! I see my Pi's command prompt:

Once I'm connected, here's what I always do first:

Update Everything

I grab a coffee while this runs - it usually takes a few minutes.

Configure Additional Interfaces

I navigate through the menu to enable what I need:

1. I2C (for sensors I might connect later)
2. SPI (for various devices)
3. Camera (if I plan to use the Pi camera)

For detailed information about all the configuration options available in raspi-config, check out the official documentation: Raspberry Pi Configuration

Install my Essential Tools

These are the tools I can't live without when working on Pi projects.

Increasing Swap Space

For 4GB Pi models, I always increase the swap space:

I change CONF_SWAPSIZE=100 to CONF_SWAPSIZE=1024, then:

Memory Split Configuration

I go to Advanced Options -> Memory Split and set it to 16 since I'm not using graphics.

Getting Docker Installed

I use the official Docker Installation script:

Adding myself to the Docker Group

This lets me run Docker commands without sudo:

Starting Docker Services

Testing my Installation

I log out and back in, then test:

When I see "Hello from Docker!" I know everything's working perfectly.

For managing multi-container applications:

I verify it worked:

One of my favorite ways to work with the Pi is through VS Code's Remote Explorer extension. This gives me a full IDE experience while the code actually runs on the Pi.

Installing the Remote SSH Extension

1. I open VS Code on my Computer
2. Go to the Extensions panel (Ctrl + Shift + X)
3. Search for "Remote-SSH" by Microsoft
4. Install the extension

Connecting to my Pi

1. I press Ctrl + Shift + P to open the command palette
2. Type "Remote-SSH: Connect to Host"
3. Enter my Pi's SSH connection: my-username@pi-ip-address (e.g., pi@192.168.1.100)
4. VS Code opens a new window connected to my Pi

What I get with this setup

1. Full file explorer of my Pi's filesystem
2. Integrated terminal running directly on the Pi
3. Code editing with Intellisense and syntax highlighting
4. Extension support for Python, Docker, and ROS development
5. Git integration for version control

Pro tip: I can install extensions directly on the Pi through VS Code's interface. I usually install Python, Docker, and ROS Extensions for the best development experience.

For a comprehensive guide on VS Code extensions specifically for ROS development, check out this detailed article: Exploration of VS Code extensions for a ROS Developer.

SSH won't connect

1. I double-check that my Pi is actually powered ON and the LED is active
2. I run another network scan to confirm the IP address
3. I verify SSH is enabled by checking /boot/ssh exists
4. I try connecting with verbose output: ssh -v my-username@pi-ip-address

VS Code Remote Connection Issues

1. I make sure the SSH connection works first in the terminal
2. I check that the Remote-SSH extension is properly installed
3. I try restarting VS Code and reconnecting
4. I verify my SSH config doesn't have conflicting entries

Network Issues

1. I verify that my network credentials are correct
2. If all else fails, I connect via Ethernet for the initial setup

Performance problems

1. I monitor resources with htop to see what's eating CPU/memory
2. I consider switching to an SSD via USB 3.0 for better performance
3. I make sure my Pi has adequate cooling for long-running tasks

My Raspberry Pi 4 is now ready for serious ROS 2 development! In the next article, I'll show you how to build and run ROS 2 Docker containers specifically optimized for the Pi.

We'll cover:

1. Creating custom ROS 2 Docker images for ARM64 architecture
2. Setting up Docker Compose files for robotics projects
3. Optimizing containers for Pi's resource constraints

My Final Thoughts

This headless setup with VS Code remote development has become my standard approach for Pi-based projects. The combination of Raspberry Pi OS Lite, Docker, and VS Code's remote capabilities gives me a lightweight yet powerful development environment that I can access from anywhere on my network.

The best part? I get the full desktop IDE experience while keeping the Pi running efficiently without a desktop environment. This setup provides the perfect foundation for the ROS 2 Docker containers we'll build in the next article.