raspi_headless_setup.md

Raspberry Pi Headless Setup Guide

Prerequisites

• Raspberry Pi (tested on Pi 3A+)
• MicroSD card (minimum 8GB recommended)
• SD card reader
• Linux computer for setup
• WiFi network (2.4GHz for Pi 3A+)

Step 1: Install Raspberry Pi Imager

On Fedora:

sudo dnf install rpi-imager

On Debian/Ubuntu:

sudo apt install rpi-imager

Or download from the official Raspberry Pi website.

Step 2: Flash and Configure with Raspberry Pi Imager

1. Launch Raspberry Pi Imager
2. Click "Choose Device" and select your Raspberry Pi model (e.g., Raspberry Pi 3)
3. Click "Choose OS" and select "Raspberry Pi OS (other)" then "Raspberry Pi OS Lite (32-bit)" or your preferred OS
4. Click "Choose Storage" and select your SD card
5. Click the settings button (gear icon) or press Ctrl+Shift+X to open OS Customization
6. Configure the following settings:
   • Enable "Set hostname" (default: raspberrypi)
   • Enable "Set username and password"
     • Username: pi (or your choice)
     • Password: raspberry (or your choice)
   • Enable "Configure wireless LAN"
     • SSID: Your WiFi network name
     • Password: Your WiFi password
     • Wireless LAN country: CY (or your country code)
   • Enable "Set locale settings"
     • Time zone: Europe/Nicosia (or your timezone)
     • Keyboard layout: us (or your layout)
   • Navigate to the "Services" tab
   • Enable "Enable SSH"
   • Select "Use password authentication"
7. Click "Save"
8. Click "Write" and confirm
9. Wait for the writing and verification process to complete

Step 3: First Boot

1. Remove the SD card from your computer
2. Insert the SD card into your Raspberry Pi
3. Power on the device
4. Wait 2-5 minutes for first boot and network connection
5. The green LED should blink (SD card activity) and red LED should be solid (power)

Note: First boot may take up to 5 minutes depending on SD card speed and model.

Step 4: Connect via SSH

Try connecting using the hostname:

ssh pi@raspberrypi.local

If hostname resolution doesn't work, find the IP address by scanning your network:

# Adjust network range to match your network
sudo nmap -sn 192.168.1.0/24

Then connect using the IP address:

ssh pi@<IP_ADDRESS>

Enter the password you configured in Raspberry Pi Imager.

Important: If you used the default password, change it immediately after first login:

passwd

Step 5: System Update and Package Installation

Update the system:

sudo apt update && sudo apt full-upgrade -y

Install essential packages:

sudo apt install cmake git htop curl -y

Step 6: Install Custom Packages

If you have custom .deb packages, transfer them via SCP from your local machine:

scp your-package.deb pi@raspberrypi.local:~/

Install the package on the Pi:

sudo dpkg -i ~/your-package.deb

# If there are dependency issues, fix them with:
sudo apt-get install -f

Troubleshooting

Pi doesn't connect to WiFi

• Verify WiFi credentials were entered correctly in Raspberry Pi Imager
• Ensure your WiFi network is 2.4GHz (Pi 3A+ does not support 5GHz)
• Check that your router is working and in range
• Wait up to 5 minutes on first boot

Cannot find Pi on network

• Check router's connected devices list for "raspberrypi"
• Use nmap to scan your network: sudo nmap -sn 192.168.1.0/24
• Try connecting via Ethernet cable instead
• Ensure SSH was enabled in Raspberry Pi Imager settings

SSH connection refused

• Verify SSH was enabled in Raspberry Pi Imager OS Customization
• Check that the Pi has successfully booted (green LED activity)
• Ensure you're on the same network as the Pi
• Try pinging the Pi: ping raspberrypi.local

Hostname resolution fails

• Use IP address instead of hostname
• Install avahi-daemon on your Linux machine: sudo apt install avahi-daemon
• Try adding .local to the hostname: raspberrypi.local

Notes

• Raspberry Pi OS Bookworm and newer (including Trixie) require WiFi configuration through Raspberry Pi Imager
• The legacy wpa_supplicant.conf method no longer works on these versions
• Always use the official Raspberry Pi Imager for the most reliable setup
• For security, change default passwords immediately after first login
• Consider setting up SSH keys for passwordless authentication after initial setup