Get IP Address Raspberry Pi Headless: Build an OLED Network Monitor

The Headless IP Problem: Why You Need a Hardware Display

If you need to get the IP address of a Raspberry Pi via the terminal, the fastest software method is running hostname -I or ip -4 addr show. But when you are running a headless setup—no monitor, no keyboard, and SSH is failing because you don't know the IP to connect to in the first place—software commands are useless.

The ultimate bench workaround for embedded engineers and home-lab builders is a dedicated hardware IP display. By wiring a cheap I2C OLED to the Pi's GPIO header and running a background Python script, the Pi will boot up and physically display its assigned IPv4 address on the screen. This guide walks through building this exact tool on the current Raspberry Pi 5 (4GB), handling modern NetworkManager configurations, and debugging the inevitable network errors.

Project Spec Sheet & Parts List

This build targets the Raspberry Pi 5 (4GB variant) running Raspberry Pi OS (64-bit, Bookworm or newer). The Pi 5 maintains the standard 40-pin header layout for I2C, making it backward-compatible with standard OLED modules.

Wiring the I2C OLED to the Pi 5

The SSD1306 communicates over I2C. On the Raspberry Pi 5, the primary I2C bus (I2C1) is mapped to GPIO 2 (SDA) and GPIO 3 (SCL). Because the Pi 5 operates at 3.3V logic, the Adafruit 3.3V OLED is a direct plug-and-play match without needing logic level shifters.

Pin Mapping Table

The Python Script: Fetching and Displaying the IP

Raspberry Pi OS transitioned to NetworkManager as the default network backend. Older tutorials relying on dhcpcd.conf or ifconfig parsing will fail on modern images. The most robust way to get the active IP address in Python is to open a dummy UDP socket to an external route and read the local socket name. This bypasses interface-name guessing (like eth0 vs enp1s0).

Prerequisites: Enable I2C via sudo raspi-config (Interface Options > I2C), then install the display libraries:
sudo apt update && sudo apt install python3-pil python3-smbus
pip3 install luma.oled

Complete Compilable Code

#!/usr/bin/env python3
"""
Raspberry Pi 5 Headless IP Monitor
Target: Raspberry Pi 5 (4GB) / Raspberry Pi OS (64-bit)
Hardware: SSD1306 128x64 I2C OLED on I2C Bus 1 (Pins 3 & 5)
"""

import socket
import time
import sys
from luma.core.interface.serial import i2c
from luma.core.render import canvas
from luma.oled.device import ssd1306
from PIL import ImageFont

# --- HARDWARE PIN & BUS DEFINITIONS ---
# I2C Bus 1 corresponds to physical pins 3 (SDA) and 5 (SCL)
I2C_PORT = 1
I2C_ADDRESS = 0x3C  # Standard for Adafruit SSD1306

try:
    serial = i2c(port=I2C_PORT, address=I2C_ADDRESS)
    device = ssd1306(serial, rotate=0)
except Exception as e:
    print(f"[FATAL] I2C Initialization failed: {e}")
    print("Check wiring and ensure I2C is enabled in raspi-config.")
    sys.exit(1)

# Load default font (fallback to DejaVu if available)
try:
    font = ImageFont.truetype('/usr/share/fonts/truetype/dejavu/DejaVuSans-Bold.ttf', 16)
    font_small = ImageFont.truetype('/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf', 12)
except IOError:
    font = ImageFont.load_default()
    font_small = font

def get_active_ip():
    """Fetches the primary IPv4 address using a dummy UDP socket."""
    s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
    s.settimeout(0)
    try:
        # Connect to a public DNS root; no traffic is actually sent
        s.connect(('8.8.8.8', 80))
        ip_address = s.getsockname()[0]
    except OSError as e:
        # Catch specific network unreachable errors
        raise e
    finally:
        s.close()
    return ip_address

def display_text(line1, line2):
    """Renders text to the OLED buffer."""
    with canvas(device) as draw:
        draw.text((0, 0), line1, font=font_small, fill='white')
        draw.text((0, 20), line2, font=font, fill='white')

def main():
    print("Starting IP Monitor...")
    display_text('BOOTING...', 'ACQUIRING IP')
    
    while True:
        try:
            current_ip = get_active_ip()
            display_text('Pi 5 IP Addr:', current_ip)
            time.sleep(10) # Poll every 10 seconds
            
        except OSError as e:
            # Handle exact error string for network failures
            error_str = str(e)
            if 'Network is unreachable' in error_str or 'Errno 101' in error_str:
                display_text('ERROR 101:', 'NO NETWORK LINK')
                print(f"[WARN] {error_str} - Waiting for DHCP...")
            else:
                display_text('NET ERROR:', error_str[:16])
                print(f"[ERROR] Unexpected OS Error: {error_str}")
            time.sleep(5)
            
        except KeyboardInterrupt:
            device.cleanup()
            print("Monitor stopped.")
            sys.exit(0)

if __name__ == '__main__':
    main()

Debugging: When the Network or I2C Fails

Embedded networking is notoriously fragile. When your script crashes or displays an error, you need a systematic decision path. Below are the exact error strings you will encounter and how to fix them.

Error 1: OSError: [Errno 101] Network is unreachable

This is the most common error when the script tries to fetch the IP but the Pi hasn't established a route to the gateway.

• Cause 1 (Most Likely): The Ethernet cable is unplugged, or the Wi-Fi SSID/password in NetworkManager is incorrect.
• Cause 2: The DHCP server on your router is exhausted or ignoring the Pi's MAC address.
• Cause 3: The network interface is administratively DOWN.

Error 2: FileNotFoundError: [Errno 2] No such file or directory (During I2C Init)

This occurs at the serial = i2c(...) line.

• Cause 1: I2C is disabled in the OS. Run sudo raspi-config and enable it.
• Cause 2: You are running the script as a standard user without i2c group permissions. Run sudo usermod -aG i2c $USER and reboot.

Extending and Simplifying the Build

Once the baseline IP monitor is running, you can adapt it to your specific lab environment.

How to Simplify: Assign a Static IP

If you are tired of the IP changing and just want a permanent address for SSH, bypass the DHCP dance entirely. Since modern Raspberry Pi OS uses NetworkManager, use the terminal UI:
sudo nmtui
Select 'Edit a connection', choose your interface, and change IPv4 Configuration from 'Automatic' to 'Manual'. Set your desired IP (e.g., 192.168.1.50/24) and Gateway. The Python script will now instantly display this static IP on boot without waiting for a DHCP lease.

How to Extend: Add CPU Telemetry

The Pi 5 runs significantly hotter than the Pi 4. You can extend the Python script to alternate the OLED display every 5 seconds between the IP address and the SoC temperature. Read the thermal zone directly from the Linux sysfs:
temp = open('/sys/class/thermal/thermal_zone0/temp').read()
Divide by 1000 to get Celsius. This turns your simple IP tool into a full headless dashboard.

Frequently Asked Questions

How do I get the IP address of my Raspberry Pi without a monitor?

If you don't have an OLED wired up, you can find the Pi's IP address from your router's admin panel by looking at the DHCP client list for a hostname like raspberrypi. Alternatively, if you are on the same local network, use a network scanner like Nmap or the free mobile app Fing to scan your subnet (e.g., nmap -sn 192.168.1.0/24) and look for the Raspberry Pi Foundation's MAC address OUI (usually starting with b8:27:eb or dc:a6:32).

Why does my Raspberry Pi keep changing its IP address on my network?

By default, the Pi requests a dynamic IP via DHCP. When the router's DHCP lease time expires, or if the Pi reboots and the router assigns addresses on a first-come-first-served basis, the Pi may get a new IP. To fix this, either configure a 'DHCP Reservation' on your router (binding the Pi's MAC address to a specific IP) or set a static IP directly on the Pi using nmtui as described in the simplification section above.

How can I find my Raspberry Pi IP address from my Windows PC?

Open Windows Command Prompt or PowerShell and ping the Pi's default mDNS hostname: ping raspberrypi.local. Windows 10 and 11 support mDNS (Multicast DNS) natively. If the Pi is on the same VLAN and responding to multicast, the command will resolve the hostname and print the current IPv4 address directly in the terminal output, saving you from logging into your router.