Config.txt Reference

Required Configuration

Add these lines to /boot/firmware/config.txt (or /boot/config.txt on older systems):

config.txt

# Enable KMS video driver (required)
dtoverlay=vc4-kms-v3d

# Enable 8-DSI-TOUCH-A display on DSI1
dtoverlay=vc4-kms-dsi-waveshare-panel-v2,8_0_inch_a

DSI Port Selection

Configuration	Description
8_0_inch_a	Default, uses DSI1
8_0_inch_a,dsi0	Use DSI0 instead

Using DSI0

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

Note

Most users should use DSI1 (the default). Use DSI0 only for specific configurations like dual-display setups.

Display Rotation (cmdline.txt)

For headless/Lite systems, add to /boot/firmware/cmdline.txt:

# Add at the BEGINNING of the line
video=DSI-1:800x1280e,rotate=90

Option	Effect
rotate=0	Portrait (default)
rotate=90	Landscape left
rotate=180	Portrait inverted
rotate=270	Landscape right

Caution

This only affects display output. Touch rotation requires a separate udev rule - see Touch Calibration.

Related Overlays

Other Waveshare DSI Displays

# 2.8" DSI
dtoverlay=vc4-kms-dsi-waveshare-panel-v2,2_8_inch

# 4.3" DSI
dtoverlay=vc4-kms-dsi-waveshare-panel-v2,4_3_inch

# 7.9" DSI
dtoverlay=vc4-kms-dsi-waveshare-panel-v2,7_9_inch

# 8" DSI (this display)
dtoverlay=vc4-kms-dsi-waveshare-panel-v2,8_0_inch_a

# 10.1" DSI
dtoverlay=vc4-kms-dsi-waveshare-panel-v2,10_1_inch

Video Memory (Legacy)

On older systems, you may need to increase GPU memory:

# Not typically needed on Pi 4/5 with KMS
gpu_mem=128

HDMI Alongside DSI

You can use HDMI and DSI simultaneously:

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

# HDMI settings (if needed)
# hdmi_group=2
# hdmi_mode=82

Note

When using both displays, they share the same rotation setting and cannot be rotated independently.

Debugging

If the display doesn’t work, check the kernel log:

# View boot messages
dmesg | grep -i dsi

# Check loaded overlays
vcdbg log msg 2>&1 | grep -i overlay

Complete Example

/boot/firmware/config.txt

# Core settings
arm_64bit=1
kernel=kernel8.img

# Enable KMS driver
dtoverlay=vc4-kms-v3d

# Waveshare 8" DSI display
dtoverlay=vc4-kms-dsi-waveshare-panel-v2,8_0_inch_a

# Optional: Disable Bluetooth if not needed
# dtoverlay=disable-bt

# Optional: Overclock (Pi 4)
# over_voltage=6
# arm_freq=2000

File Locations

OS Version	Config Location
Bookworm+	/boot/firmware/config.txt
Bullseye	/boot/config.txt
Legacy	/boot/config.txt

Always verify the correct path for your OS version.