A Raspberry Pi DSI display connects through the dedicated MIPI DSI ribbon cable port on the Pi board and delivers a cleaner, lower-latency connection than HDMI for touchscreen applications and embedded builds. The Official Raspberry Pi 7-inch Touchscreen requires zero configuration on Bookworm. Third-party DSI displays require the correct dtoverlay entry in /boot/firmware/config.txt. This guide covers both paths, the correct rotation method on Bookworm, touchscreen calibration, and the most common failure points.
Last tested: Raspberry Pi OS Bookworm 64-bit | May 3, 2026 | Raspberry Pi 4 Model B (4GB) | Official 7-inch Touchscreen V2 | Raspberry Pi OS Bookworm kernel 6.6
Key Takeaways
- The config.txt path on Bookworm is
/boot/firmware/config.txt, not/boot/config.txt. The old path still exists as a symlink on some installs but editing it directly is unreliable. Always use the full Bookworm path. - Screen rotation on Bookworm with the KMS driver (
vc4-kms-v3d) does not usedisplay_rotate. That parameter only works with the legacy driver. On Bookworm, rotation is set in the dtoverlay line or viawlr-randr/xrandrat the desktop level depending on whether you are running Wayland or X11. - Pi Zero 2 W has a DSI port and works with the Official 7-inch Touchscreen. Original Pi Zero does not have a DSI port. Pi 5 has two DSI ports (DSI0 and DSI1) and requires specifying which port the display is connected to in the overlay.
Raspberry Pi DSI Display: Choosing the Right Screen
The DSI interface delivers video data over a dedicated ribbon cable port, separate from HDMI. It uses less CPU than HDMI on framebuffer-intensive workloads and supports touch data over a secondary I2C connection on the same cable assembly. There are two distinct categories of DSI display for the Pi, and they have different setup requirements.
Official Raspberry Pi Touchscreen (7-inch V1 or V2): Plug-and-play on Bookworm. No config.txt changes required. The display is detected automatically, touch works out of the box, and the correct driver is included in the kernel. This is the correct choice if you want a reliable, zero-configuration embedded display.
Third-party DSI displays (Waveshare, Elecrow, Pimoroni, others): Require a dtoverlay entry in /boot/firmware/config.txt and sometimes a custom driver package. The specific overlay depends on the display controller chip. Most vendors provide documentation for Bookworm. Use the vendor’s instructions as the primary reference and this guide for the Bookworm-specific corrections.
Connecting the Display
Power off the Pi completely before connecting or disconnecting any DSI display. The DSI port is not hot-pluggable.
Locate the DSI port on your Pi board. On Pi 4 there is one port labelled DSI (between the USB ports and the camera port). On Pi 5 there are two ports: DSI0 (near the USB-C power port) and DSI1 (near the camera ports). The Official Touchscreen connects to DSI1 on Pi 5.
Open the DSI connector latch by pulling the two tabs outward. Insert the FPC ribbon cable with the metal contacts facing toward the Pi board (away from you if the board is flat on a surface). Press the latch back in. The cable should be seated straight with no angle. A poorly seated cable is the most common cause of no display on first boot.
The Official Touchscreen also has a 4-pin power/I2C connector that runs from the display board to the Pi GPIO header. Connect the red wire to pin 4 (5V), the black wire to pin 6 (GND), the green wire to pin 3 (GPIO2/SDA), and the blue wire to pin 5 (GPIO3/SCL). Third-party displays vary. Check the vendor wiring diagram for your specific model.
Official Touchscreen Setup on Bookworm
The Official Raspberry Pi Touchscreen requires no config.txt changes on Bookworm. Boot the Pi with the display connected and it initialises automatically. The display comes up at 800×480 with touch input active.
Verify the display is detected after boot:
cat /sys/class/drm/card*/card*-DSI-*/statusExpected result: Returns connected. If it returns disconnected, the cable is not seated correctly. Power off, reseat the cable, and reboot.
For Pi 5 with the Official Touchscreen on DSI1, add this line to /boot/firmware/config.txt if the display does not come up automatically:
sudo nano /boot/firmware/config.txtdtoverlay=vc4-kms-dsi-7inchsudo rebootThird-Party DSI Display Setup on Bookworm
Third-party displays require a dtoverlay entry matching their controller chip. The vendor documentation specifies which overlay to use. The general pattern for adding it to /boot/firmware/config.txt:
sudo nano /boot/firmware/config.txtAdd the overlay line in the [all] section, not the [pi4] or [pi5] sections unless the display is model-specific. Example for a Waveshare 5-inch DSI display using the ILI9881C controller:
dtoverlay=vc4-kms-v3d
dtoverlay=ili9881c,touchSome vendor packages install the overlay automatically via a shell script. If the vendor provides an install script for Bookworm, use it. Verify what it adds to config.txt afterward:
tail -20 /boot/firmware/config.txtExpected result: The overlay line matching your display appears in the output. Reboot and check display status with the cat /sys/class/drm/ command from the previous section.
If the vendor documentation refers to /boot/config.txt, mentally substitute /boot/firmware/config.txt. The old path does not work reliably on Bookworm.
Screen Rotation on Bookworm
The display_rotate parameter in config.txt only works with the legacy KMS driver. Bookworm uses vc4-kms-v3d (full KMS) by default. On this driver, display_rotate is silently ignored. Use one of the following methods instead.
Rotation via dtoverlay (preferred for Official Touchscreen)
Add the rotate parameter to the overlay line in /boot/firmware/config.txt:
# 0 = normal, 90 = 90 degrees clockwise, 180 = inverted, 270 = 90 degrees counter-clockwise
dtoverlay=vc4-kms-dsi-7inch,rotate=90Rotation via wlr-randr (Wayland desktop)
If you are running Raspberry Pi OS with the Wayland desktop (the default on Bookworm with desktop), use wlr-randr:
sudo apt install wlr-randr -y
wlr-randr --output DSI-1 --transform 90To make the rotation persistent, add the command to ~/.config/wayfire.ini or your session autostart file.
Rotation via xrandr (X11 desktop)
If you are running X11 (set via sudo raspi-config under Advanced Options):
xrandr --output DSI-1 --rotate rightValid values: normal, left, right, inverted. To persist, add to /etc/xdg/autostart/ or your .xinitrc.
Touchscreen Calibration
The Official Touchscreen is calibrated from the factory. Touch input registers correctly without any software calibration step. If touch coordinates are offset after rotation, install libinput-tools and check the reported touch coordinates:
sudo apt install libinput-tools -y
sudo libinput debug-events --device /dev/input/event0Touch the screen in a known location and compare the reported coordinates to what you expect. For the Official Touchscreen, if coordinates are rotated relative to the display, add the transformation matrix to the libinput configuration:
sudo nano /etc/udev/rules.d/98-touchscreen-cal.rules# 90-degree clockwise rotation matrix
ENV{LIBINPUT_CALIBRATION_MATRIX}="0 1 0 -1 0 1 0 0 1"The transformation matrices for each rotation:
- 90 degrees CW:
0 1 0 -1 0 1 0 0 1 - 180 degrees:
-1 0 1 0 -1 1 0 0 1 - 270 degrees CW:
0 -1 1 1 0 0 0 0 1
sudo udevadm control --reload-rules && sudo udevadm triggerTroubleshooting
Display shows nothing on boot
Power off completely and reseat the FPC cable. The connector latch must click closed. If the cable is even slightly skewed in the connector the display will not initialise. Check that the 4-pin power connector is fully seated on both ends (Official Touchscreen only). Run cat /sys/class/drm/card*/card*-DSI-*/status after boot to confirm whether the driver sees the panel.
Backlight is on but screen is white or shows noise
The backlight initialising separately from the panel data is usually a timing issue between the overlay and the panel. Confirm the correct overlay is in /boot/firmware/config.txt and not in the legacy /boot/config.txt. For third-party displays, confirm you are using the Bookworm-specific driver version from the vendor, not an older Bullseye package.
Touch input is not working
Confirm the I2C touch controller is detected:
sudo apt install i2c-tools -y
sudo i2cdetect -y 1The Official Touchscreen touch controller (FT5406) appears at address 0x38. If it does not appear, the 4-pin connector is not seated or a wire is reversed. Check pin assignments against the Official Touchscreen documentation.
Display works on Pi 4 but not Pi 5
The Pi 5 requires specifying the DSI port in the overlay. The Official Touchscreen must be connected to DSI1 on Pi 5 (the port nearest the camera connectors). Add dtoverlay=vc4-kms-dsi-7inch explicitly to config.txt. Third-party displays may need ,dsi1 appended to their overlay line. Check the vendor’s Pi 5 documentation as the overlay syntax changed between Pi 4 and Pi 5.
FAQ
Can I run two DSI displays on a Pi 5?
Yes. The Pi 5 has DSI0 and DSI1 ports and supports two displays simultaneously. Each needs its own overlay entry in config.txt with the port specified. The combined power draw from two displays plus the Pi 5 under load can approach the limits of a 27W supply, so use the official 27W USB-C supply rather than a lighter adapter. See Raspberry Pi Accessories for verified power supply options.
Can I use a DSI display and HDMI at the same time?
Yes. The DSI display and HDMI output operate independently on Pi 4 and Pi 5. Both are active by default after boot. The desktop spans or mirrors across both depending on your display manager settings. On Wayland, use wlr-randr to configure the layout. On X11, use xrandr.
Does the Official Touchscreen work with Raspberry Pi OS Lite?
Yes, the display initialises and the framebuffer is available on Lite. There is no desktop or touch input handling by default on Lite since there is no display manager. For kiosk or single-application builds on Lite, use a framebuffer application like fbi for images or a minimal Wayland compositor like cage for a single fullscreen application with touch support. See Python Raspberry Pi for building a kiosk application in Python.
What is the difference between DSI V1 and V2 touchscreens?
The Official Raspberry Pi Touchscreen V2 (released 2024) improves on V1 with a higher brightness panel, updated touch controller, and better Pi 5 compatibility. V2 uses the same 800×480 resolution as V1 but with improved colour accuracy and a slimmer bezel. Both work on Bookworm without config.txt changes. V2 is the current model in production. V1 units still work correctly on all supported Pi models.
Why does my third-party display work on Bullseye but not Bookworm?
Bookworm changed the default KMS driver from legacy to full KMS (vc4-kms-v3d). Some third-party display drivers were written for the legacy driver and have not been updated. Check whether your vendor has released a Bookworm-compatible driver package. If not, you can force the legacy driver by replacing dtoverlay=vc4-kms-v3d with dtoverlay=vc4-fkms-v3d in config.txt, though this is not recommended for new builds as the legacy driver is deprecated.
References
- https://www.raspberrypi.com/documentation/accessories/display.html
- https://www.raspberrypi.com/documentation/computers/config_txt.html
- https://github.com/raspberrypi/linux/blob/rpi-6.6.y/arch/arm/boot/dts/overlays/README
About the Author
Chuck Wilson has been programming and building with computers since the Tandy 1000 era. His professional background includes CAD drafting, manufacturing line programming, and custom computer design. He runs PidiyLab in retirement, documenting Raspberry Pi and homelab projects that he actually deploys and maintains on real hardware. Every article on this site reflects hands-on testing on specific hardware and OS versions, not theoretical walkthroughs.
Last tested hardware: Raspberry Pi 4 Model B (4GB), Official Raspberry Pi 7-inch Touchscreen V2. Last tested OS: Raspberry Pi OS Bookworm 64-bit, kernel 6.6.