Display Fix for Trixie

Overview

When installing or upgrading to Debian 13 (Trixie) 64-bit on a Raspberry Pi 5 inside a Waveshare Industrial HMI enclosure, the built-in screen and touch interface may fail to initialize on boot.

While the external HDMI ports will continue to output a signal, the internal display remains blank. This occurs because Trixie's newer kernel and Wayland graphics stack do not automatically detect the internal MIPI DSI connection without explicitly defining the hardware overlay in the boot configuration.

Prerequisites

• Raspberry Pi 5 mounted in the Waveshare HMI enclosure.

• An external HDMI monitor and keyboard (for configuration).

• Root / Sudo access to the device.

Solution: Configuring the DSI Overlay

The Waveshare display interfaces with the Raspberry Pi via the internal DSI port. To wake up the screen, touch digitizer, and front-facing camera, you must add the proprietary device tree overlays (dtoverlay) to the Pi's boot configuration file.

Step 1: Access the Boot Configuration

Connect your external HDMI monitor and boot the device. Open a terminal and edit the firmware configuration file:

sudo nano /boot/firmware/config.txt

Note: On older versions of Raspberry Pi OS, this file was located at /boot/config.txt. On Debian Bookworm and Trixie, it is strictly located in the /boot/firmware/ directory.

Step 2: Add the Waveshare Overlays

Scroll to the bottom of the config.txt file and append the specific overlay for your screen size.

For the 8.0-inch Display:

# Enable Waveshare 8-inch DSI Panel
dtoverlay=vc4-kms-dsi-waveshare-panel,8_0_inch,dsi0

For the 10.1-inch Display:

# Enable Waveshare 10.1-inch DSI Panel
dtoverlay=vc4-kms-dsi-waveshare-panel,10_1_inch,dsi0

Step 3: Enable the Internal Camera (Optional)

If your HMI unit features the built-in 5MP front camera, add the following line just below your display overlay:

# Enable built-in front camera
dtoverlay=ov5647

Step 4: Save and Reboot

Save your changes (Ctrl+O, Enter) and exit the nano editor (Ctrl+X). Reboot the system to apply the new kernel mode settings:

sudo reboot

Troubleshooting

"No such file or directory" for the .dtbo file: If the screen still does not turn on, verify that the Trixie image includes the necessary compiled overlay file by running:

ls /boot/firmware/overlays/vc4-kms-dsi-waveshare-panel.dtbo

If the file is missing (common in generic Debian arm64 images), you will need to manually download the .dtbo file from the Waveshare GitHub repository and place it in the /boot/firmware/overlays/ directory before rebooting.