Display Setup and Testing

Time: 15 min | Prerequisites: SSH Login | Theory companion: Graphics Stack reference

How to identify, enable, and verify the display connected to your Raspberry Pi. Use this page to get your display working before starting the graphics tutorials.

Learning Objectives

By the end of this page you will be able to:

Identify which display interface you have (HDMI, DSI, or SPI)
Enable the correct kernel driver and verify the display device
Run a basic test to confirm the display is working
Choose the right tutorial path for your display type

1. Which Display Do You Have?

Connection	What It Looks Like	Typical Size	Device
HDMI	Micro-HDMI cable to external monitor	7"–27"	`/dev/fb0` or `/dev/dri/card0`
DSI	Flat ribbon cable to the "DISPLAY" port on the Pi	3.5"–10"	`/dev/dri/card0` (same as HDMI)
SPI	HAT plugged onto the 40-pin GPIO header, or wires to GPIO pins	1.3"–3.5"	`/dev/fb1` (separate from HDMI)

Note

If you are using the lab's HDMI monitor, no special setup is needed — it works out of the box. Skip to Step 3: Verify.

2. Enable Your Display

HDMI (Default)

HDMI works without configuration on Raspberry Pi OS. If the monitor shows a desktop or a text console on boot, you are ready.

Troubleshooting:

# Check which HDMI port is active (Pi 4 has two micro-HDMI ports)
cat /sys/class/graphics/fb0/virtual_size

# If display is blank, force HDMI output in config.txt
sudo nano /boot/firmware/config.txt
# Uncomment or add: hdmi_force_hotplug=1
# Save and reboot

DSI (Ribbon Cable)

DSI panels are auto-detected on most Pi models. Connect the ribbon cable to the "DISPLAY" port (not "CAMERA") and reboot.

# Verify DSI is detected
dmesg | grep -i dsi

If the panel stays dark, you may need a device tree overlay. See the DSI Display tutorial for panel-specific setup.

SPI (HAT or Wired)

SPI displays need a device tree overlay to tell the kernel which controller IC the display uses. This varies by display model.

# 1. Enable SPI
sudo raspi-config nonint do_spi 0

# 2. Add the overlay for your display (example for Waveshare 3.5" ILI9486)
sudo nano /boot/firmware/config.txt
# Add: dtoverlay=waveshare35a

# 3. Reboot and verify
sudo reboot
ls /dev/fb1   # SPI display appears as fb1 (fb0 is HDMI)

See the SPI Display tutorial for the complete setup procedure, including touch calibration.

3. Verify Your Display

Run these checks to confirm your display is working:

Check framebuffer devices

ls -l /dev/fb*

You see	Meaning
`/dev/fb0`	HDMI or DSI framebuffer (primary display)
`/dev/fb0` + `/dev/fb1`	HDMI/DSI + SPI display (two displays)
Nothing	No framebuffer — display may use DRM-only path

Check DRM devices

ls -l /dev/dri/ 2>/dev/null

You see	Meaning
`card0`, `renderD128`	DRM/KMS is enabled — modern graphics path available
Nothing	DRM not enabled — framebuffer-only path (see below)

Quick display test

# Write random colors to the framebuffer (fastest sanity check)
sudo cat /dev/urandom > /dev/fb0
# You should see colored noise on the display. Press Ctrl+C to stop.

# Restore the console
sudo chvt 2 && sudo chvt 1

If you see noise on the screen, the display is working. Proceed to the tutorials.

4. Framebuffer vs DRM/KMS Mode

Your Pi may be running in one of two graphics modes:

	Framebuffer only	DRM/KMS enabled
Device	`/dev/fb0`	`/dev/dri/card0` + `/dev/fb0` (compat)
VSync / page flip	No	Yes
Mode enumeration	`fbset`, sysfs	`modetest`, EDID
Config needed	Nothing (default on some images)	`dtoverlay=vc4-kms-v3d` in config.txt
Tutorials that work	Framebuffer Basics, SPI Display	All graphics tutorials

To enable DRM/KMS (if not already enabled):

# Check current status
ls /dev/dri/ 2>/dev/null && echo "KMS enabled" || echo "KMS not enabled"

# Enable KMS
sudo nano /boot/firmware/config.txt
# Find and uncomment (or add):
#   dtoverlay=vc4-kms-v3d
# Save, then reboot

sudo reboot

# Verify after reboot
ls /dev/dri/

Warning

Enabling KMS may change display behavior (resolution auto-detection, console font size). If the display goes blank after reboot, connect a serial console or remove the overlay line from config.txt on another computer.

5. Display Comparison

	HDMI	DSI	SPI
Bandwidth	5.9 Gbps	1.5 Gbps (2 lanes)	50 Mbps
Typical resolution	1920×1080	800×480	320×240
Rendering path	GPU scan-out	GPU scan-out	CPU → SPI bus
Max FPS	60+	60	10–20
Touch input	None (external USB)	I2C capacitive	SPI resistive
Setup complexity	Plug and play	Ribbon cable + auto-detect	Overlay + calibration
Cost	$50–200 (monitor)	$20–50 (panel)	$5–15 (module)
Best for	Development, dashboards	Portable products, kiosks	Tiny status displays

Tutorial Path

Choose your path based on your display:

                    ┌───────────────────────────┐
                    │  Framebuffer Basics        │ ← Start here (all displays)
                    │  (mmap, pixel formats)     │
                    └─────────────┬─────────────┘
                                  │
                    ┌─────────────┼─────────────┐
                    ▼             ▼             ▼
            ┌──────────┐  ┌──────────┐  ┌──────────┐
            │ DRM/KMS  │  │ SPI      │  │ DSI      │
            │ Test     │  │ Display  │  │ Display  │
            │ (HDMI)   │  │ (HAT)    │  │ (ribbon) │
            └────┬─────┘  └──────────┘  └──────────┘
                 │
                 ▼
          ┌────────────┐
          │ SDL2 / Qt  │ ← Higher-level graphics
          │ Tutorials  │
          └────────────┘

Display	Start with	Then
HDMI monitor	Framebuffer Basics → DRM/KMS Test	SDL2, Qt
DSI panel	Framebuffer Basics → DSI Display	SDL2
SPI HAT	Framebuffer Basics → SPI Display	Level Display

Back to Course Overview