Software Setup

Prerequisites

• Raspberry Pi OS Bookworm or newer (recommended)
• Hardware connected per Hardware Setup
• Access to edit config.txt (via SD card or SSH)

Configuration Methods

Fresh Install (Recommended)

Steps

1. Flash Raspberry Pi OS to your SD card using Raspberry Pi Imager
2. Before first boot, mount the SD card on your computer
3. Edit config.txt in the boot partition
4. Add the overlay at the end of the file (see code block below)
5. Eject and insert the SD card into your Pi
6. Power on and wait ~30 seconds for the display to initialize

config.txt

dtoverlay=vc4-kms-v3d
dtoverlay=vc4-kms-dsi-waveshare-panel-v2,8_0_inch_a

Existing System

Steps

1. SSH into your Pi or connect a monitor temporarily
2. Edit config.txt using the command below
3. Add the overlay at the end (see config block below)
4. Save and reboot with sudo reboot

Edit command:

sudo nano /boot/firmware/config.txt

Add these lines:

dtoverlay=vc4-kms-v3d
dtoverlay=vc4-kms-dsi-waveshare-panel-v2,8_0_inch_a

Reboot:

sudo reboot

Pre-built Image

Waveshare provides pre-configured images with drivers installed:

1. Download the image from Waveshare Wiki
2. Flash to SD card using Raspberry Pi Imager
3. Insert and power on - display works immediately

DSI Port Selection

Note

Most users should use DSI1 (the default). Use DSI0 only if you have a specific reason.

Port	Config Line
DSI1 (default)	dtoverlay=vc4-kms-dsi-waveshare-panel-v2,8_0_inch_a
DSI0	dtoverlay=vc4-kms-dsi-waveshare-panel-v2,8_0_inch_a,dsi0

Backlight Control

GUI Method

1. Open Menu → Preferences → Control Center → Screens
2. Select DSI-2 (or your display)
3. Adjust the Brightness slider
4. Click Apply

Command Line

# Set brightness (0-255, where 255 is brightest)
echo 128 | sudo tee /sys/class/backlight/*/brightness

# Examples
echo 255 | sudo tee /sys/class/backlight/*/brightness  # Maximum
echo 100 | sudo tee /sys/class/backlight/*/brightness  # Medium
echo 0 | sudo tee /sys/class/backlight/*/brightness    # Off (dark)

Waveshare Brightness Tool

wget https://files.waveshare.com/wiki/common/Brightness.zip
unzip Brightness.zip
cd Brightness
sudo chmod +x install.sh
./install.sh

After installation, access via Start Menu → Accessories → Brightness.

Virtual Keyboard

Raspberry Pi OS Bookworm includes Squeekboard for on-screen keyboard:

• Appears automatically when text input is available
• Toggle manually via keyboard icon in taskbar
• Configure in Menu → Preferences → Control Centre → Display

Verification

After configuration:

1. Display should show the desktop
2. Touch should respond (may need rotation - see Touch Calibration)
3. Backlight should be adjustable

If the display remains dark, see Troubleshooting.