[GUIDE] Waveshare 11.9"/7.9" HDMI LCD Display Configuration for Volumio 4

Help and Support Guides
1

Waveshare HDMI display configuration guide for Volumio OS

Supported hardware

Waveshare HDMI displays

  • 11.9 inch HDMI LCD - Native resolution 320x1480 (portrait)
  • 7.9 inch HDMI LCD - Native resolution 400x1280 (portrait)

Note: These are generic HDMI displays compatible with any device supporting custom HDMI timings. This guide specifically covers configuration for Raspberry Pi running Volumio OS.

Configuration tested on

  • Raspberry Pi 4B+ - All scenarios tested and verified
  • Raspberry Pi 5 - All scenarios tested and verified

Operating system

  • Volumio OS (Debian Bookworm-based)

Plymouth theme requirement

  • volumio-adaptive - Required for proper boot splash rotation
  • See References section for installation source and community discussion

Why this specific theme is required:

Portrait-native displays like the Waveshare panels expose a fundamental Linux kernel limitation: the DRM (Direct Rendering Manager) subsystem assumes all displays are landscape-oriented. When rotation parameters are applied to portrait-native panels, the kernel’s rotation logic produces inconsistent or wrong orientations because it calculates rotation from a landscape baseline that doesn’t match the panel’s actual native orientation.

The volumio-adaptive theme solves this by using pre-rotated sequences instead of runtime rotation. This bypasses both the kernel’s broken rotation logic and Plymouth’s text rotation limitations, ensuring the boot splash displays correctly regardless of the display’s native orientation.

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)
hdmi_timings 320 0 80 16 32 1480 0 16 4 12 0 0 0 60 0 42000000 3 400 0 220 32 110 1280 0 10 10 10 0 0 0 60 0 59400000 3
max_framebuffer_height 1480 (required) Not needed
video= parameter video=HDMI-A-1:320x1480M@60,rotate=90 video=HDMI-A-1:400x1280M@60,rotate=90
plymouth= parameter plymouth=90 plymouth=90
Expected fbset output mode "1480x320" mode "1280x400"

Important notes:

  • Both displays use rotate=90 in video= parameter for landscape orientation
  • Both displays use plymouth=90 to enable volumio-adaptive theme rotation
  • 11.9 inch display requires max_framebuffer_height=1480 parameter
  • 7.9 inch display does NOT need max_framebuffer_height parameter
  • HDMI rotation (90 degrees) differs from DSI rotation (270 degrees) but achieves same physical orientation

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 HDMI 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
max_framebuffer_height=1480
hdmi_group=2
hdmi_mode=87
hdmi_timings=320 0 80 16 32 1480 0 16 4 12 0 0 0 60 0 42000000 3
[all]
#### Touch Display rotation setting below: do not alter ####
display_lcd_rotate=1
display_hdmi_rotate=1

Add to end of /boot/cmdline.txt:

video=HDMI-A-1:320x1480M@60,rotate=90 plymouth=90

Expected fbset output:

mode "1480x320"

Example 2: Raspberry Pi 5 with 11.9 inch HDMI display (Scenario 1)

Complete /boot/userconfig.txt:

# Add your custom config.txt options to this file, which will be preserved during updates
max_framebuffer_height=1480
hdmi_group=2
hdmi_mode=87
hdmi_timings=320 0 80 16 32 1480 0 16 4 12 0 0 0 60 0 42000000 3

#### Touch Display rotation setting below: do not alter ####
display_lcd_rotate=1
display_hdmi_rotate=1

Add to end of /boot/cmdline.txt:

video=HDMI-A-1:320x1480M@60,rotate=90 plymouth=90

Expected fbset output:

mode "1480x320"

Example 3: Raspberry Pi 4B+ with 7.9 inch HDMI 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
hdmi_group=2
hdmi_mode=87
hdmi_timings=400 0 220 32 110 1280 0 10 10 10 0 0 0 60 0 59400000 3
[all]
#### Touch Display rotation setting below: do not alter ####
display_lcd_rotate=1
display_hdmi_rotate=1

Add to end of /boot/cmdline.txt:

video=HDMI-A-1:400x1280M@60,rotate=90 plymouth=90

Expected fbset output:

mode "1280x400"

Example 4: Raspberry Pi 5 with 7.9 inch HDMI display (Scenario 1)

Complete /boot/userconfig.txt:

# Add your custom config.txt options to this file, which will be preserved during updates
hdmi_group=2
hdmi_mode=87
hdmi_timings=400 0 220 32 110 1280 0 10 10 10 0 0 0 60 0 59400000 3

#### Touch Display rotation setting below: do not alter ####
display_lcd_rotate=1
display_hdmi_rotate=1

Add to end of /boot/cmdline.txt:

video=HDMI-A-1:400x1280M@60,rotate=90 plymouth=90

Expected fbset output:

mode "1280x400"

Physical orientation (90-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 90-degree rotation:

  • Display top edge: Aligned with GPIO header (Pi top edge)
  • Display bottom edge: Aligned with USB-C/HDMI ports (Pi bottom edge)

Why 90 degrees (not 270): HDMI displays use different rotation conventions than DSI displays. A 90-degree rotation on HDMI achieves the same physical landscape orientation as 270-degree rotation on DSI.

Configuration scenarios overview

Scenario Audio output Additional HDMI port Use case
1 HDMI display audio N/A Display audio through built-in speakers
2 I2S DAC N/A High-quality audio via DAC, display on HDMI
3 HDMI port 1 audio Audio only Soundbar/AVR on second HDMI port
4 Dual HDMI Secondary display Display + secondary video output

Note: HDMI display scenarios differ from DSI scenarios because the display itself uses HDMI port 0 for video+audio. Additional audio configurations use HDMI port 1 or I2S DAC.

Common base configuration

Raspberry Pi 4B+

All scenarios share this base configuration in /boot/userconfig.txt:

[pi4]
dtoverlay=vc4-kms-v3d-pi4
<INSERT max_framebuffer_height IF 11.9 INCH>
hdmi_group=2
hdmi_mode=87
<INSERT DISPLAY-SPECIFIC hdmi_timings FROM TABLE>
[all]
#### Touch Display rotation setting below: do not alter ####
display_lcd_rotate=1
display_hdmi_rotate=1

Add scenario-specific parameters below this base.

Raspberry Pi 5

All scenarios use this simplified configuration in /boot/userconfig.txt:

<INSERT max_framebuffer_height IF 11.9 INCH>
hdmi_group=2
hdmi_mode=87
<INSERT DISPLAY-SPECIFIC hdmi_timings FROM TABLE>

#### Touch Display rotation setting below: do not alter ####
display_lcd_rotate=1
display_hdmi_rotate=1

Key differences for Pi 5:

  • No section markers ([pi4], [all]) needed
  • No vc4-kms-v3d overlay (handled automatically by volumioconfig.txt)

Add scenario-specific parameters below this base.

cmdline.txt configuration

For all scenarios on both Pi 4B+ and Pi 5:

Add the display-specific parameters from the table to the END of /boot/cmdline.txt:

<INSERT DISPLAY-SPECIFIC video= PARAMETER FROM TABLE> plymouth=90

Space-separate from previous parameters.

Example for 11.9 inch display:

... use_kmsg=no video=HDMI-A-1:320x1480M@60,rotate=90 plymouth=90

Example for 7.9 inch display:

... use_kmsg=no video=HDMI-A-1:400x1280M@60,rotate=90 plymouth=90

Scenario 1: HDMI display only

Purpose

Display on HDMI with audio through display’s built-in speakers (if available).

Configuration

Use the complete example configurations provided above (Examples 1-4) based on your Pi model and display size. No additional parameters needed.

Expected results

  • fbset shows display-specific resolution (see parameter table)
  • Display shows correctly rotated landscape video
  • Plymouth boot splash displays with correct rotation (via volumio-adaptive theme)
  • Console properly rotated to landscape
  • Audio output available through HDMI display (if speakers present)

Scenario 2: HDMI display + I2S DAC

Purpose

Video on HDMI display, high-quality audio through external I2S DAC.

Configuration

Use base configuration for your Pi model and display size from examples above.

DAC Configuration via Volumio UI:

Do NOT add DAC overlays to userconfig.txt. Configure your I2S DAC through Volumio’s web interface:

  1. Open Volumio web UI (http://volumio.local)
  2. Navigate to: Settings → Playback Options
  3. Under Output Device, select your I2S DAC from the dropdown
  4. Click Save
  5. Volumio will automatically add the correct DAC overlay to /boot/config.txt
  6. Reboot when prompted

Important: Volumio manages DAC configuration in /boot/config.txt (system file). User modifications should only go in /boot/userconfig.txt.

Expected results

  • Display shows correctly rotated landscape video
  • I2S DAC active for audio output (configured via Volumio UI)
  • Plymouth boot splash displays with correct rotation
  • Console properly rotated to landscape

Scenario 3: HDMI display + HDMI port 1 audio

Purpose

Video on primary HDMI display (port 0), audio extracted from second HDMI port (port 1) for soundbar/AVR.

Configuration

Raspberry Pi 4B+

/boot/userconfig.txt - Add to base configuration:

[pi4]
dtoverlay=vc4-kms-v3d-pi4
<INSERT max_framebuffer_height IF 11.9 INCH>
hdmi_group=2
hdmi_mode=87
<INSERT DISPLAY-SPECIFIC hdmi_timings FROM TABLE>
hdmi_force_hotplug:1=1
hdmi_drive:1=2
hdmi_ignore_edid:1=0xa5000080
[all]
#### Touch Display rotation setting below: do not alter ####
display_lcd_rotate=1
display_hdmi_rotate=1

Raspberry Pi 5

/boot/userconfig.txt - Add to base configuration:

<INSERT max_framebuffer_height IF 11.9 INCH>
hdmi_group=2
hdmi_mode=87
<INSERT DISPLAY-SPECIFIC hdmi_timings FROM TABLE>
hdmi_force_hotplug:1=1
hdmi_drive:1=2
hdmi_ignore_edid:1=0xa5000080

#### Touch Display rotation setting below: do not alter ####
display_lcd_rotate=1
display_hdmi_rotate=1

Both Pi 4B+ and Pi 5

/boot/cmdline.txt - Add to end:

<INSERT DISPLAY-SPECIFIC video= PARAMETER FROM TABLE> video=HDMI-A-2:d plymouth=90

Example for 11.9 inch display:

... use_kmsg=no video=HDMI-A-1:320x1480M@60,rotate=90 video=HDMI-A-2:d plymouth=90

Expected results

  • Display shows correctly rotated landscape video on HDMI port 0
  • HDMI-A-2 (port 1) video disabled but audio active
  • Plymouth displays with correct rotation
  • Audio available to soundbar/AVR connected to HDMI port 1

Scenario 4: HDMI display + secondary video output

Purpose

Primary display on HDMI port 0 (Waveshare display), secondary display on HDMI port 1.

Configuration

Raspberry Pi 4B+

/boot/userconfig.txt:

[pi4]
dtoverlay=vc4-kms-v3d-pi4
<INSERT max_framebuffer_height IF 11.9 INCH>
hdmi_group=2
hdmi_mode=87
<INSERT DISPLAY-SPECIFIC hdmi_timings FROM TABLE>
hdmi_force_hotplug:1=1
hdmi_drive:1=2
[all]
#### Touch Display rotation setting below: do not alter ####
display_lcd_rotate=1
display_hdmi_rotate=1

Raspberry Pi 5

/boot/userconfig.txt:

<INSERT max_framebuffer_height IF 11.9 INCH>
hdmi_group=2
hdmi_mode=87
<INSERT DISPLAY-SPECIFIC hdmi_timings FROM TABLE>
hdmi_force_hotplug:1=1
hdmi_drive:1=2

#### Touch Display rotation setting below: do not alter ####
display_lcd_rotate=1
display_hdmi_rotate=1

Both Pi 4B+ and Pi 5

/boot/cmdline.txt - Add to end:

<INSERT DISPLAY-SPECIFIC video= PARAMETER FROM TABLE> video=HDMI-A-2:1920x1080@60 plymouth=90

Adjust secondary display resolution as needed (example shows 1080p).

Expected results

  • Primary Waveshare display shows correctly rotated landscape video
  • Secondary HDMI display active with specified resolution
  • Plymouth displays on primary display with correct rotation
  • Volumio UI appears on primary display by default

Note: Without X11 (touch display plugin disabled), secondary display will show console output only. Enable touch display plugin for dual display support with Volumio UI.

Parameter reference

HDMI display parameters

Parameter Function
hdmi_group=2 Enables DMT (Display Monitor Timings) mode for custom resolutions
hdmi_mode=87 Activates custom HDMI timing mode
hdmi_timings=... Defines custom display timing parameters for portrait resolution
max_framebuffer_height=1480 Sets framebuffer height (required for 11.9 inch display)
display_lcd_rotate=1 Enables 90-degree rotation for LCD interface
display_hdmi_rotate=1 Enables 90-degree rotation for HDMI output
video=HDMI-A-1:<resolution>,rotate=90 Kernel-level framebuffer rotation for console
plymouth=90 Triggers volumio-adaptive theme to use 90-degree rotated images

Secondary HDMI audio parameters

Parameter Function
hdmi_force_hotplug:1=1 Keeps HDMI port 1 active
hdmi_drive:1=2 Forces HDMI audio mode (not DVI) on port 1
hdmi_ignore_edid:1=0xa5000080 Ignores display detection on port 1 (audio-only mode)
video=HDMI-A-2:d Kernel-level disable of HDMI-A-2 video output

Audio parameters

Parameter Function
dtoverlay=<dac-name> Loads specific I2S DAC driver overlay (via Volumio UI)

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 1):

... video=HDMI-A-1:320x1480M@60,rotate=90 plymouth=90

Expected output for 7.9 inch (Scenario 3):

... video=HDMI-A-1:400x1280M@60,rotate=90 video=HDMI-A-2:d plymouth=90

Check HDMI configuration

vcgencmd get_config int | grep hdmi

Expected output (varies by scenario):

hdmi_group=2
hdmi_mode=87
display_hdmi_rotate=1
display_lcd_rotate=1

Check display devices

ls /sys/class/drm/

Expected output (single display):

card0  card0-HDMI-A-1  ...

Expected output (dual display):

card0  card0-HDMI-A-1  card0-HDMI-A-2  ...

Troubleshooting

Issue: Framebuffer shows wrong resolution

Symptoms:

fbset
mode "320x1480"  # Wrong - not rotated

Causes:

  1. Missing or incorrect hdmi_timings
  2. Missing display rotation parameters
  3. Incorrect video= parameter in cmdline.txt

Solution:

  1. Verify hdmi_timings matches your display size from parameter table
  2. Check display_lcd_rotate=1 and display_hdmi_rotate=1 are present
  3. Ensure correct video= parameter with rotate=90 is in cmdline.txt
  4. Verify 11.9 inch display has max_framebuffer_height=1480

Issue: Plymouth boot splash not rotated

Symptoms:

  • Boot splash appears in portrait orientation
  • Plymouth displays but sideways

Solution:

  • Ensure plymouth=90 parameter is in cmdline.txt
  • Verify volumio-adaptive Plymouth theme is installed
  • Check plymouth theme selection: plymouth-set-default-theme
  • Install volumio-adaptive theme if missing (see references section)

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=HDMI-A-1:... parameter with rotate=90 to cmdline.txt
  • Verify display_hdmi_rotate=1 is in userconfig.txt
  • Both parameters are required for complete rotation

Issue: 11.9 inch display shows corrupted framebuffer

Symptoms:

  • Screen shows partial or distorted image
  • Wrong geometry reported by fbset

Solution:

  • Add max_framebuffer_height=1480 to userconfig.txt
  • This parameter is REQUIRED for 11.9 inch display
  • 7.9 inch display does NOT need this parameter

Issue: Secondary HDMI audio not working (Scenario 3)

Symptoms:

  • No audio output from HDMI port 1
  • Volumio doesn’t list HDMI 1 as audio output option

Solution:

  1. Verify hdmi_drive:1=2 is set (forces audio mode)
  2. Check HDMI cable supports audio (not all do)
  3. Verify soundbar/AVR is set to correct HDMI input
  4. Check Volumio audio output settings in web interface
  5. Ensure video=HDMI-A-2:d is in cmdline.txt to disable video

Issue: Display not detected

Symptoms:

  • No output on HDMI display
  • System boots but display stays black

Solution:

  1. Verify HDMI cable is connected to port 0 (closest to USB-C power)
  2. Check hdmi_group and hdmi_mode are set correctly
  3. Verify hdmi_timings match your display size exactly
  4. Test with different HDMI cable
  5. Try removing custom timings temporarily to test basic HDMI output

Notes and best practices

Important warnings

  1. Never edit /boot/config.txt directly - Always use /boot/userconfig.txt for custom settings
  2. cmdline.txt is a single line - All parameters must be on one line, space-separated
  3. plymouth=90 parameter required - Without this, boot splash will not rotate correctly
  4. 11.9 inch needs max_framebuffer_height - This parameter is mandatory for 11.9 inch display
  5. Use correct hdmi_timings - Wrong timings will prevent display from working
  6. Primary display uses HDMI port 0 - Always connect Waveshare display to port closest to USB-C power
  7. Configure DACs via Volumio UI - Never manually add DAC overlays to userconfig.txt
  8. volumio-adaptive theme required - Standard Plymouth themes will not rotate correctly

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

Configuration testing workflow

  1. Identify your display size (11.9 inch or 7.9 inch)
  2. Reference the parameter table for display-specific values
  3. Use complete example configurations as starting point
  4. Make changes to configuration files using correct parameters
  5. Verify syntax (no typos, proper spacing)
  6. Reboot system
  7. Run verification commands
  8. Check Plymouth during boot for correct rotation
  9. Verify console rotation
  10. Test audio output if configured
  11. Document working configuration

HDMI timings explained

The hdmi_timings parameter defines custom display timing in this format:

<h_active_pixels> <h_sync_polarity> <h_front_porch> <h_sync_pulse> <h_back_porch> 
<v_active_lines> <v_sync_polarity> <v_front_porch> <v_sync_pulse> <v_back_porch> 
<v_sync_offset_a> <v_sync_offset_b> <pixel_rep> <frame_rate> <interlaced> 
<pixel_freq> <aspect_ratio>

For 11.9 inch (320x1480):

320 0 80 16 32 1480 0 16 4 12 0 0 0 60 0 42000000 3

For 7.9 inch (400x1280):

400 0 220 32 110 1280 0 10 10 10 0 0 0 60 0 59400000 3

Do not modify these values unless you understand HDMI timing specifications.

Rotation angles reference

Rotation Native portrait Landscape result Use case
0 Portrait mode N/A - portrait Not recommended
90 Portrait → Landscape GPIO header at top This guide uses 90
180 Portrait upside down N/A - portrait Not recommended
270 Portrait → Landscape GPIO header at bottom Alternative orientation

This guide uses 90-degree rotation for landscape display with GPIO header at top, matching DSI guide physical orientation.

Why plymouth=90 parameter?

The plymouth=90 kernel parameter triggers the volumio-adaptive Plymouth theme’s pre-rotated image selection mechanism:

  1. Init script reads kernel command line during boot
  2. Detects plymouth=90 parameter
  3. Patches theme to use 90-degree pre-rotated image sequence
  4. Plymouth renders correctly rotated boot splash using pre-rotated images

Without this parameter, Plymouth will use the default (0-degree) image set and the display will appear sideways during boot.

Technical background: This approach was necessary because portrait-native displays expose a Linux kernel limitation where rotation parameters produce inconsistent results. The volumio-adaptive theme bypasses runtime rotation entirely by using pre-rotated image sets, solving both the kernel’s broken rotation logic and Plymouth’s text rotation clipping issues on portrait displays. See Plymouth theme requirement section above for detailed explanation.

Difference from DSI displays

Aspect HDMI displays (this guide) DSI displays
Connection HDMI port 0 DSI ribbon cable
Rotation angle 90 degrees 270 degrees
Custom timings hdmi_timings required dtoverlay handles timing
Display detection Automatic via EDID Driver-based
Physical result Same landscape orientation Same landscape orientation

Both achieve the same physical mounting orientation but use different rotation values due to hardware differences.

References

Kind Regards,