Waveshare DSI display configuration guide for Volumio OS
Supported hardware
Raspberry Pi models
- Raspberry Pi 4B+ - Tested with all scenarios
- Raspberry Pi 5 - Tested with all scenarios
Waveshare DSI displays
- 11.9 inch DSI LCD - Native resolution 320x1480 (portrait)
- 7.9 inch DSI LCD - Native resolution 400x1280 (portrait)
Operating system
- Volumio OS 4 (Debian Bookworm-based)
Display-specific parameters reference
All configurations require display-specific parameters. Use this table to determine correct values for your display.
Parameter table by display size
| Parameter | 11.9 inch display | 7.9 inch display |
|---|---|---|
| Native resolution | 320x1480 (portrait) | 400x1280 (portrait) |
| Rotated resolution | 1480x320 (landscape) | 1280x400 (landscape) |
| dtoverlay line | dtoverlay=vc4-kms-dsi-waveshare-panel,11_9_inch,rotation=270 |
dtoverlay=vc4-kms-dsi-waveshare-panel,7_9_inch,rotation=270 |
| video= parameter | video=DSI-1:320x1480@60,rotate=270 |
video=DSI-1:400x1280e,rotate=270 |
| Expected fbset output | mode "1480x320" |
mode "1280x400" |
Important notes:
- Both displays use
rotation=270in dtoverlay for landscape orientation - 7.9 inch display requires “e” flag in video= parameter:
400x1280e - 11.9 inch display does NOT use “e” flag:
320x1480@60
Complete example configurations
This section provides complete, ready-to-use configuration files for common setups. Choose the example matching your hardware and copy the entire configuration.
Example 1: Raspberry Pi 4B+ with 11.9 inch display (Scenario 1)
Complete /boot/userconfig.txt:
# Add your custom config.txt options to this file, which will be preserved during updates
[pi4]
dtoverlay=vc4-kms-v3d-pi4
dtoverlay=vc4-kms-dsi-waveshare-panel,11_9_inch,rotation=270
hdmi_force_hotplug=0
disable_overscan=1
dtparam=audio=off
[all]
Add to end of /boot/cmdline.txt:
video=DSI-1:320x1480@60,rotate=270
Expected fbset output:
mode "1480x320"
Example 2: Raspberry Pi 5 with 11.9 inch display (Scenario 1)
Complete /boot/userconfig.txt:
# Add your custom config.txt options to this file, which will be preserved during updates
dtoverlay=vc4-kms-dsi-waveshare-panel,11_9_inch,rotation=270
hdmi_force_hotplug=0
hdmi_drive=2
disable_overscan=1
Add to end of /boot/cmdline.txt:
video=DSI-1:320x1480@60,rotate=270
Expected fbset output:
mode "1480x320"
Example 3: Raspberry Pi 4B+ with 7.9 inch display (Scenario 1)
Complete /boot/userconfig.txt:
# Add your custom config.txt options to this file, which will be preserved during updates
[pi4]
dtoverlay=vc4-kms-v3d-pi4
dtoverlay=vc4-kms-dsi-waveshare-panel,7_9_inch,rotation=270
hdmi_force_hotplug=0
disable_overscan=1
dtparam=audio=off
[all]
Add to end of /boot/cmdline.txt:
video=DSI-1:400x1280e,rotate=270
Note: The “e” flag is required for 7.9 inch display.
Expected fbset output:
mode "1280x400"
Example 4: Raspberry Pi 5 with 7.9 inch display (Scenario 1)
Complete /boot/userconfig.txt:
# Add your custom config.txt options to this file, which will be preserved during updates
dtoverlay=vc4-kms-dsi-waveshare-panel,7_9_inch,rotation=270
hdmi_force_hotplug=0
hdmi_drive=2
disable_overscan=1
Add to end of /boot/cmdline.txt:
video=DSI-1:400x1280e,rotate=270
Note: The “e” flag is required for 7.9 inch display.
Expected fbset output:
mode "1280x400"
Example 5: Raspberry Pi 4B+ with 11.9 inch + HDMI port 0 audio (Scenario 3)
Complete /boot/userconfig.txt:
# Add your custom config.txt options to this file, which will be preserved during updates
[pi4]
dtoverlay=vc4-kms-v3d-pi4
dtoverlay=vc4-kms-dsi-waveshare-panel,11_9_inch,rotation=270
hdmi_force_hotplug:0=1
hdmi_drive:0=2
hdmi_ignore_edid:0=0xa5000080
disable_overscan=1
[all]
Add to end of /boot/cmdline.txt:
video=DSI-1:320x1480@60,rotate=270 video=HDMI-A-1:d
Expected result: Display on DSI, audio from HDMI port 0
Example 6: Raspberry Pi 5 with 7.9 inch + both HDMI ports audio (Scenario 5)
Complete /boot/userconfig.txt:
# Add your custom config.txt options to this file, which will be preserved during updates
dtoverlay=vc4-kms-dsi-waveshare-panel,7_9_inch,rotation=270
hdmi_force_hotplug:0=1
hdmi_force_hotplug:1=1
hdmi_drive:0=2
hdmi_drive:1=2
hdmi_ignore_edid:0=0xa5000080
hdmi_ignore_edid:1=0xa5000080
disable_overscan=1
Add to end of /boot/cmdline.txt:
video=DSI-1:400x1280e,rotate=270 video=HDMI-A-1:d video=HDMI-A-2:d
Expected result: Display on DSI, audio from both HDMI ports (Volumio uses one)
Physical orientation (270-degree rotation)
Raspberry Pi 4B+ and Pi 5 mounting (when viewing from screen side):
- Bottom edge: USB-C power port, HDMI ports
- Left edge: USB ports, Ethernet/LAN port
- Top edge: GPIO header
- Right edge: SD card slot (micro SD on Pi 4B+, full size SD on Pi 5)
Note: When mounting the Pi from behind (looking at the back of the display), left and right edges are reversed from this description.
Display orientation with 270-degree rotation:
- Display top edge: Aligned with GPIO header (Pi top edge)
- Display bottom edge: Aligned with USB-C/HDMI ports (Pi bottom edge)
Raspberry Pi 4B+ and Pi 5 mounting (when viewing from screen side):
- Bottom edge: USB-C power port, HDMI ports
- Left edge: USB ports, Ethernet/LAN port
- Top edge: GPIO header
- Right edge: SD card slot (micro SD on Pi 4B+, full size SD on Pi 5)
Note: When mounting the Pi from behind (looking at the back of the display), left and right edges are reversed from this description.
Display orientation with 270-degree rotation:
- Display top edge: Aligned with GPIO header (Pi top edge)
- Display bottom edge: Aligned with USB-C/HDMI ports (Pi bottom edge)
Configuration scenarios overview
| Scenario | Audio output | HDMI port 0 | HDMI port 1 | Use case |
|---|---|---|---|---|
| 1 | None/Disabled | Disabled | Disabled | Minimal setup, no audio |
| 2 | I2S DAC | Disabled | Disabled | High-quality audio via DAC |
| 3 | HDMI audio | Audio only | Disabled | Soundbar/AVR on HDMI 0 |
| 4 | HDMI audio | Disabled | Audio only | Soundbar/AVR on HDMI 1 |
| 5 | HDMI audio | Audio only | Audio only | Dual audio output capability |
Common base configuration
Raspberry Pi 4B+
All scenarios share this base configuration in /boot/userconfig.txt:
[pi4]
dtoverlay=vc4-kms-v3d-pi4
<INSERT DISPLAY-SPECIFIC dtoverlay LINE FROM TABLE>
disable_overscan=1
Add scenario-specific parameters below this base.
Raspberry Pi 5
All scenarios use this simplified configuration in /boot/userconfig.txt:
<INSERT DISPLAY-SPECIFIC dtoverlay LINE FROM TABLE>
hdmi_force_hotplug=0
hdmi_drive=2
disable_overscan=1
Key differences for Pi 5:
- No section markers ([pi4], [all]) needed
- No vc4-kms-v3d overlay (handled automatically by volumioconfig.txt)
- Simplified HDMI configuration
Add scenario-specific parameters below this base.
cmdline.txt configuration
For all scenarios on both Pi 4B+ and Pi 5:
Add the display-specific video= parameter from the table to the END of /boot/cmdline.txt:
<INSERT DISPLAY-SPECIFIC video= PARAMETER FROM TABLE>
Space-separate from previous parameters.
Example for 11.9 inch display:
... use_kmsg=no video=DSI-1:320x1480@60,rotate=270
Example for 7.9 inch display:
... use_kmsg=no video=DSI-1:400x1280e,rotate=270
Scenario 1: DSI only (no audio)
Purpose
Minimal configuration for display only, all audio outputs disabled.
Configuration
Raspberry Pi 4B+
/boot/userconfig.txt:
[pi4]
dtoverlay=vc4-kms-v3d-pi4
<INSERT DISPLAY-SPECIFIC dtoverlay LINE FROM TABLE>
hdmi_force_hotplug=0
disable_overscan=1
dtparam=audio=off
[all]
Raspberry Pi 5
/boot/userconfig.txt:
<INSERT DISPLAY-SPECIFIC dtoverlay LINE FROM TABLE>
hdmi_force_hotplug=0
hdmi_drive=2
disable_overscan=1
Both Pi 4B+ and Pi 5
/boot/cmdline.txt:
- Add to the END of the existing single line:
<INSERT DISPLAY-SPECIFIC video= PARAMETER FROM TABLE> - Space-separate from previous parameters
Expected results
fbsetshows display-specific resolution (see parameter table)- No HDMI interference
- Plymouth displays correctly on DSI with landscape rotation
- Console properly rotated to landscape
- No audio outputs active
Scenario 2: DSI + I2S DAC
Purpose
High-quality audio through external I2S DAC while maintaining DSI display.
Configuration
Raspberry Pi 4B+
/boot/userconfig.txt:
[pi4]
dtoverlay=vc4-kms-v3d-pi4
<INSERT DISPLAY-SPECIFIC dtoverlay LINE FROM TABLE>
hdmi_force_hotplug=0
disable_overscan=1
dtparam=audio=off
[all]
Raspberry Pi 5
/boot/userconfig.txt:
<INSERT DISPLAY-SPECIFIC dtoverlay LINE FROM TABLE>
hdmi_force_hotplug=0
hdmi_drive=2
disable_overscan=1
Both Pi 4B+ and Pi 5
/boot/cmdline.txt:
- Add to the END of the existing single line:
<INSERT DISPLAY-SPECIFIC video= PARAMETER FROM TABLE> - Space-separate from previous parameters
DAC Configuration via Volumio UI:
Do NOT add DAC overlays to userconfig.txt. Configure your I2S DAC through Volumio’s web interface:
- Open Volumio web UI (http://volumio.local)
- Navigate to: Settings → Playback Options
- Under Output Device, select your I2S DAC from the dropdown
- Click Save
- Volumio will automatically add the correct DAC overlay to
/boot/config.txt - Reboot when prompted
Important: Volumio manages DAC configuration in /boot/config.txt (system file). User modifications should only go in /boot/userconfig.txt. The two files work together - config.txt is managed by Volumio, userconfig.txt is for user customizations like display settings.
Expected results
fbsetshows display-specific resolution (see parameter table)- I2S DAC active for audio output (configured via Volumio UI)
- Plymouth displays correctly on DSI with landscape rotation
- Console properly rotated to landscape
- HDMI audio disabled
Scenario 3: DSI + HDMI port 0 audio
Purpose
Extract audio from HDMI port 0 (closer to USB-C power) while disabling video output.
Configuration
Raspberry Pi 4B+
/boot/userconfig.txt:
[pi4]
dtoverlay=vc4-kms-v3d-pi4
<INSERT DISPLAY-SPECIFIC dtoverlay LINE FROM TABLE>
hdmi_force_hotplug:0=1
hdmi_drive:0=2
hdmi_ignore_edid:0=0xa5000080
disable_overscan=1
[all]
Raspberry Pi 5
/boot/userconfig.txt:
<INSERT DISPLAY-SPECIFIC dtoverlay LINE FROM TABLE>
hdmi_force_hotplug:0=1
hdmi_drive:0=2
hdmi_ignore_edid:0=0xa5000080
disable_overscan=1
Both Pi 4B+ and Pi 5
/boot/cmdline.txt:
- Add to the END of the existing single line:
<INSERT DISPLAY-SPECIFIC video= PARAMETER FROM TABLE> video=HDMI-A-1:d - Space-separate from previous parameters
Example for 11.9 inch display:
... use_kmsg=no video=DSI-1:320x1480@60,rotate=270 video=HDMI-A-1:d
Expected results
fbsetshows display-specific resolution (see parameter table)- HDMI-A-1 video disabled but audio active
- Plymouth displays correctly on DSI with landscape rotation
- Console properly rotated to landscape
- HDMI audio available to soundbar/AVR connected to port 0
Scenario 4: DSI + HDMI port 1 audio
Purpose
Extract audio from HDMI port 1 (farther from USB-C power) while disabling video output.
Configuration
Raspberry Pi 4B+
/boot/userconfig.txt:
[pi4]
dtoverlay=vc4-kms-v3d-pi4
<INSERT DISPLAY-SPECIFIC dtoverlay LINE FROM TABLE>
hdmi_force_hotplug:1=1
hdmi_drive:1=2
hdmi_ignore_edid:1=0xa5000080
disable_overscan=1
[all]
Raspberry Pi 5
/boot/userconfig.txt:
<INSERT DISPLAY-SPECIFIC dtoverlay LINE FROM TABLE>
hdmi_force_hotplug:1=1
hdmi_drive:1=2
hdmi_ignore_edid:1=0xa5000080
disable_overscan=1
Both Pi 4B+ and Pi 5
/boot/cmdline.txt:
- Add to the END of the existing single line:
<INSERT DISPLAY-SPECIFIC video= PARAMETER FROM TABLE> video=HDMI-A-2:d - Space-separate from previous parameters
Example for 11.9 inch display:
... use_kmsg=no video=DSI-1:320x1480@60,rotate=270 video=HDMI-A-2:d
Expected results
fbsetshows display-specific resolution (see parameter table)- HDMI-A-2 video disabled but audio active
- Plymouth displays correctly on DSI with landscape rotation
- Console properly rotated to landscape
- HDMI audio available to soundbar/AVR connected to port 1
Scenario 5: DSI + both HDMI ports audio
Purpose
Extract audio from both HDMI ports simultaneously while disabling video output.
Configuration
Raspberry Pi 4B+
/boot/userconfig.txt:
[pi4]
dtoverlay=vc4-kms-v3d-pi4
<INSERT DISPLAY-SPECIFIC dtoverlay LINE FROM TABLE>
hdmi_force_hotplug:0=1
hdmi_force_hotplug:1=1
hdmi_drive:0=2
hdmi_drive:1=2
hdmi_ignore_edid:0=0xa5000080
hdmi_ignore_edid:1=0xa5000080
disable_overscan=1
[all]
Raspberry Pi 5
/boot/userconfig.txt:
<INSERT DISPLAY-SPECIFIC dtoverlay LINE FROM TABLE>
hdmi_force_hotplug:0=1
hdmi_force_hotplug:1=1
hdmi_drive:0=2
hdmi_drive:1=2
hdmi_ignore_edid:0=0xa5000080
hdmi_ignore_edid:1=0xa5000080
disable_overscan=1
Both Pi 4B+ and Pi 5
/boot/cmdline.txt:
- Add to the END of the existing single line:
<INSERT DISPLAY-SPECIFIC video= PARAMETER FROM TABLE> video=HDMI-A-1:d video=HDMI-A-2:d - Space-separate from previous parameters
Example for 11.9 inch display:
... use_kmsg=no video=DSI-1:320x1480@60,rotate=270 video=HDMI-A-1:d video=HDMI-A-2:d
Expected results
fbsetshows display-specific resolution (see parameter table)- Both HDMI video outputs disabled but audio active on both ports
- Plymouth displays correctly on DSI with landscape rotation
- Console properly rotated to landscape
- HDMI audio available on both ports (Volumio will default to one)
Parameter reference
Display parameters
| Parameter | Function |
|---|---|
dtoverlay=vc4-kms-v3d-pi4 |
Enables VC4 KMS display driver for Pi 4 (Pi 4B+ only) |
dtoverlay=vc4-kms-dsi-waveshare-panel,<size>,rotation=270 |
Loads Waveshare DSI panel driver with 270-degree rotation |
video=DSI-1:<resolution>,rotate=270 |
Kernel-level framebuffer rotation for console |
disable_overscan=1 |
Prevents display area reduction (no black borders) |
HDMI audio parameters
| Parameter | Function |
|---|---|
hdmi_force_hotplug:N=1 |
Keeps HDMI port N active (0=first port, 1=second port) |
hdmi_drive:N=2 |
Forces HDMI audio mode (not DVI) on port N |
hdmi_ignore_edid:N=0xa5000080 |
Ignores display detection on port N (audio-only mode) |
video=HDMI-A-N:d |
Kernel-level disable of HDMI-A-N video output |
Audio parameters
| Parameter | Function |
|---|---|
dtparam=audio=off |
Disables onboard 3.5mm audio jack (Pi 4B+ only) |
dtoverlay=<dac-name> |
Loads specific I2S DAC driver overlay |
Verification commands
After rebooting with new configuration, verify setup with these commands:
Check framebuffer resolution
fbset
Expected output for 11.9 inch display:
mode "1480x320"
geometry 1480 320 1480 320 16
Expected output for 7.9 inch display:
mode "1280x400"
geometry 1280 400 1280 400 16
Check kernel command line
cat /proc/cmdline | grep video
Expected output for 11.9 inch (Scenario 3):
... video=DSI-1:320x1480@60,rotate=270 video=HDMI-A-1:d
Expected output for 7.9 inch (Scenario 3):
... video=DSI-1:400x1280e,rotate=270 video=HDMI-A-1:d
Check DSI display status
cat /sys/class/drm/card1-DSI-1/modes
cat /sys/class/drm/card1-DSI-1/status
Expected output for 11.9 inch:
320x1480
connected
Expected output for 7.9 inch:
400x1280
connected
Check HDMI configuration
vcgencmd get_config int | grep hdmi
Expected output (Scenario 3):
hdmi_drive:0=2
hdmi_force_hotplug:0=1
Check display devices
ls /sys/class/drm/
Expected output:
card0 card0-HDMI-A-1 card0-HDMI-A-2 card1 card1-DSI-1 ...
Troubleshooting
Issue: Framebuffer shows wrong resolution
Symptoms:
fbset
mode "320x480" # Wrong for 11.9 inch
mode "400x480" # Wrong for 7.9 inch
Causes:
- HDMI parameters injected by firmware before DSI configuration
- Conflicting video= parameters in cmdline.txt
- Missing video=DSI-1 rotation parameter
- Wrong display-specific parameters used
Solution:
- Verify
hdmi_force_hotplug=0in userconfig.txt (or proper port-specific settings) - Check
/proc/cmdlinefor unexpectedvideo=HDMIparameters - Ensure correct display-specific video= parameter from table is in cmdline.txt
- Verify video=DSI-1 parameter appears BEFORE any HDMI parameters
- Double-check you’re using parameters for the correct display size
Issue: Console in portrait mode despite rotation
Symptoms:
- Plymouth displays correctly rotated
- Console text appears in portrait orientation
- Login prompt sideways
Solution:
- Add display-specific
video=DSI-1:...parameter to cmdline.txt - This parameter rotates the framebuffer/console layer
- dtoverlay rotation alone only affects panel hardware, not console
- Verify you’re using the correct video= parameter for your display size
Issue: 7.9 inch display not working
Symptoms:
- Black screen or no output
- fbset shows wrong resolution
Solution:
- Verify video= parameter includes “e” flag:
video=DSI-1:400x1280e,rotate=270 - The “e” flag is required for 7.9 inch display
- 11.9 inch display does NOT use “e” flag
Issue: HDMI audio not working
Symptoms:
- No audio output from HDMI-connected device
- Volumio doesn’t list HDMI as audio output option
Solution:
- Verify
hdmi_drive:N=2is set (forces audio mode) - Check HDMI cable supports audio (not all do)
- Verify soundbar/AVR is set to correct HDMI input
- Check Volumio audio output settings in web interface
Issue: Plymouth not displaying during boot
Symptoms:
- Black screen during boot
- Boot messages appear but no Plymouth splash
Solution:
- Verify DSI display is detected:
cat /sys/class/drm/card1-DSI-1/status - Check Plymouth is enabled:
plymouth --ping - Review initramfs Plymouth script:
/scripts/init-premount/plymouth - Check kernel messages:
dmesg | grep -i plymouth
Issue: Display corruption or multiple segments
Symptoms:
- Screen shows multiple copies of content
- Distorted or rotated incorrectly
Solution:
- Ensure dtoverlay rotation matches video= rotation (both 270 degrees)
- Never use different rotation values in dtoverlay vs video= parameter
- Check for duplicate rotation specifications
- Verify using correct display-specific parameters
Notes and best practices
Important warnings
- Never edit
/boot/config.txtdirectly - Always use/boot/userconfig.txtfor custom settings - cmdline.txt is a single line - All parameters must be on one line, space-separated
- Rotation values must match - dtoverlay rotation and video= rotation must be identical
- DSI parameter goes first - Place video=DSI-1 before any HDMI parameters in cmdline.txt
- Use correct display parameters - 11.9 inch and 7.9 inch require different parameters
- 7.9 inch needs “e” flag - video= parameter must include “e”:
400x1280e - Firmware interference - hdmi_force_hotplug triggers automatic HDMI detection
- Configure DACs via Volumio UI - Never manually add DAC overlays to userconfig.txt; use Settings → Playback Options instead
File preservation
These files are preserved during Volumio updates:
/boot/userconfig.txt- User configuration for display and custom hardware (safe to edit)/boot/cmdline.txt- Kernel parameters (safe to edit)
These files are managed by Volumio:
/boot/config.txt- System configuration managed by Volumio (do not edit directly)/boot/volumioconfig.txt- Volumio base config (do not edit)
Important distinction:
/boot/config.txt- Volumio writes system settings here (DAC configuration, base hardware settings)/boot/userconfig.txt- User adds custom settings here (display configuration, additional hardware)- Both files are processed together at boot
- Settings in userconfig.txt supplement (not replace) config.txt
- Never manually add DAC overlays to userconfig.txt - use Volumio UI instead
Configuration testing workflow
- Identify your display size (11.9 inch or 7.9 inch)
- Reference the parameter table for display-specific values
- Make changes to configuration files using correct parameters
- Verify syntax (no typos, proper spacing)
- Reboot system
- Run verification commands
- Check Plymouth during boot
- Verify console rotation
- Test audio output if configured
- Document working configuration
Rotation angles reference
| Rotation | Native portrait | Landscape result | Display top edge aligns with |
|---|---|---|---|
| 0 | Native portrait | Portrait mode | N/A - portrait mode |
| 90 | Native portrait | Landscape | SD card slot (Pi right edge) |
| 180 | Native portrait | Portrait upside down | N/A - portrait upside down |
| 270 | Native portrait | Landscape | GPIO header (Pi top edge) |
This guide uses 270-degree rotation for landscape display with GPIO header at top.
Why both dtoverlay and video= rotation?
- dtoverlay rotation: Rotates panel at hardware/driver level
- video= rotation: Rotates framebuffer/console layer at kernel level
- Both required: Panel needs hardware rotation, console needs framebuffer rotation
- Values must match: Using different rotation values causes display corruption
References
- Waveshare 11.9" DSI LCD Wiki: https://www.waveshare.com/wiki/11.9inch_DSI_LCD
- Waveshare 7.9" DSI LCD Wiki: https://www.waveshare.com/wiki/7.9inch_DSI_LCD
- Raspberry Pi configuration documentation: https://www.raspberrypi.com/documentation/computers/config_txt.html
- Volumio documentation: https://volumio.com/en/documentation/
- Linux kernel video mode documentation: modedb default video mode support — The Linux Kernel documentation
Kind Regards,