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=90in video= parameter for landscape orientation - Both displays use
plymouth=90to enable volumio-adaptive theme rotation - 11.9 inch display requires
max_framebuffer_height=1480parameter - 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
fbsetshows 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:
- 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.
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:
- Missing or incorrect hdmi_timings
- Missing display rotation parameters
- Incorrect video= parameter in cmdline.txt
Solution:
- Verify hdmi_timings matches your display size from parameter table
- Check display_lcd_rotate=1 and display_hdmi_rotate=1 are present
- Ensure correct video= parameter with rotate=90 is in cmdline.txt
- 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=90parameter 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 withrotate=90to 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=1480to 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:
- Verify
hdmi_drive:1=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
- Ensure
video=HDMI-A-2:dis in cmdline.txt to disable video
Issue: Display not detected
Symptoms:
- No output on HDMI display
- System boots but display stays black
Solution:
- Verify HDMI cable is connected to port 0 (closest to USB-C power)
- Check hdmi_group and hdmi_mode are set correctly
- Verify hdmi_timings match your display size exactly
- Test with different HDMI cable
- Try removing custom timings temporarily to test basic HDMI output
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
- plymouth=90 parameter required - Without this, boot splash will not rotate correctly
- 11.9 inch needs max_framebuffer_height - This parameter is mandatory for 11.9 inch display
- Use correct hdmi_timings - Wrong timings will prevent display from working
- Primary display uses HDMI port 0 - Always connect Waveshare display to port closest to USB-C power
- Configure DACs via Volumio UI - Never manually add DAC overlays to userconfig.txt
- 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
- Identify your display size (11.9 inch or 7.9 inch)
- Reference the parameter table for display-specific values
- Use complete example configurations as starting point
- Make changes to configuration files using correct parameters
- Verify syntax (no typos, proper spacing)
- Reboot system
- Run verification commands
- Check Plymouth during boot for correct rotation
- Verify console rotation
- Test audio output if configured
- 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:
- Init script reads kernel command line during boot
- Detects
plymouth=90parameter - Patches theme to use 90-degree pre-rotated image sequence
- 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
- Waveshare 11.9" HDMI LCD Wiki: https://www.waveshare.com/wiki/11.9inch_HDMI_LCD
- Waveshare 7.9" HDMI LCD Wiki: https://www.waveshare.com/wiki/7.9inch_HDMI_LCD
- volumio-adaptive Plymouth theme: GitHub - foonerd/volumio-plymouth-adaptive: Dynamic boot splash and UI themes for Volumio on Raspberry Pi. Adapts to rotated displays without requiring initramfs rebuilds.
- Community discussion: Portrait Display Rotation Issues: Why It's Broken (Kernel + Plymouth)
- Raspberry Pi configuration documentation: https://www.raspberrypi.com/documentation/computers/config_txt.html
- Raspberry Pi HDMI timings: https://www.raspberrypi.com/documentation/computers/config_txt.html#hdmi-timings
- Volumio documentation: https://volumio.com/en/documentation/
Kind Regards,
