Hardware: Raspberry Pi 3B/3B+

Screen: Osoyoo 3.5″ SPI Touchscreen

System: Raspberry Pi OS Trixie (64-bit)

Reference: Original Tutorial (RPi4/5)

Table of Contents

• Step 1: System Preparation
• Step 2: Install SPI Screen Driver
• Step 3: Install Required X11 Packages
• Step 4: Edit config.txt
• Step 5: Switch to X11 and Set Auto-login
• Step 6: Fix X Server Permissions
• Step 7: Disable Conflicting Configs
• Step 8: Create X11 fbdev Configuration
• Step 9: Configure .bash_profile
• Step 10: First Reboot
• Step 11: Configure Touch
• RPi3 vs RPi4/5 Differences
• Troubleshooting

1System Preparation

First boot with HDMI monitor, complete initial setup (username: pi), enable SSH.

sudo apt-get update
sudo apt-get upgrade -y

2Install SPI Screen Driver

sudo apt-get install unzip cmake -y
cd ~
sudo wget https://osoyoo.com/driver/osoyoo35b.zip
sudo unzip ./osoyoo35b.zip
sudo cp osoyoo35b.dtbo /boot/overlays/

3Install Required X11 Packages (RPi3-specific)

sudo apt-get install xserver-xorg-video-fbdev xserver-xorg-legacy -y

Package explanations:

• xserver-xorg-video-fbdev – fbdev display driver (replaces fbturbo)
• xserver-xorg-legacy – Enables Xwrapper.config permissions

4Edit config.txt

sudo nano /boot/firmware/config.txt

4a. Comment out these lines (add # at beginning):

#dtoverlay=vc4-kms-v3d
#dtoverlay=vc4-fkms-v3d
#display_auto_detect=1

4b. Add the following at the END of the file:

# ========== SPI Screen Configuration ==========
gpu_mem=64
display_auto_detect=0
disable_fw_kms_setup=1
max_framebuffers=2

dtparam=spi=on
dtoverlay=osoyoo35b:speed=20000000
hdmi_force_hotplug=1
max_usb_current=1
hdmi_group=2
hdmi_mode=1
hdmi_mode=87
hdmi_cvt 480 320 60 6 0 0 0
hdmi_drive=2
display_rotate=2

5Switch to X11 and Set CLI Auto-login

sudo raspi-config nonint do_boot_behaviour B2
sudo raspi-config nonint do_wayland W1

6Fix X Server Permissions (RPi3-specific)

sudo tee /etc/X11/Xwrapper.config > /dev/null << 'EOF'
allowed_users=anybody
needs_root_rights=yes
EOF

7Disable Conflicting X11 Config Files

# Disable modesetting/kms config
sudo mv /usr/share/X11/xorg.conf.d/20-noglamor.conf \
        /usr/share/X11/xorg.conf.d/20-noglamor.conf.bak 2>/dev/null

# Remove fbturbo config
sudo rm -f /usr/share/X11/xorg.conf.d/99-fbturbo.conf

8Create X11 fbdev Configuration

sudo nano /etc/X11/xorg.conf.d/99-fbdev.conf

Add the following content:

Section "ServerLayout"
    Identifier "SPI Layout"
    Screen "SPI Screen"
EndSection

Section "Device"
    Identifier "SPI Display"
    Driver "fbdev"
    Option "fbdev" "/dev/fb1"
    Option "ShadowFB" "on"
EndSection

Section "Monitor"
    Identifier "SPI Monitor"
EndSection

Section "Screen"
    Identifier "SPI Screen"
    Monitor "SPI Monitor"
    Device "SPI Display"
    DefaultDepth 16
    SubSection "Display"
        Depth 16
        Modes "480x320"
        Virtual 480 320
    EndSubSection
EndSection

9Configure .bash_profile

cat > ~/.bash_profile << 'EOF' export FRAMEBUFFER=/dev/fb1 startx 2> /tmp/xorg_errors
EOF

10First Reboot

sudo reboot

11Configure Touch

After successful reboot, connect via SSH:

sudo apt-get install xserver-xorg-input-evdev xinput-calibrator -y
sudo cp -rf /usr/share/X11/xorg.conf.d/10-evdev.conf \
            /usr/share/X11/xorg.conf.d/45-evdev.conf

sudo tee /usr/share/X11/xorg.conf.d/99-calibration.conf > /dev/null << 'EOF'
Section "InputClass"
    Identifier "calibration"
    MatchProduct "ADS7846 Touchscreen"
    Option "Calibration" "241 3854 3885 240"
    Option "SwapAxes" "1"
EndSection
EOF

sudo reboot

Diagnostic Commands

If screen is stuck at boot page or showing white screen, run these commands via SSH:

# Check X Server errors
cat /tmp/xorg_errors

# Check X log
cat ~/.local/share/xorg/Xorg.0.log

# Check framebuffer devices
ls -l /dev/fb*
dmesg | grep -i fb1

# Verify Xwrapper.config (no leading spaces!)
cat /etc/X11/Xwrapper.config

# Verify xserver-xorg-legacy is installed
dpkg -l | grep xserver-xorg-legacy

Common Errors and Solutions

sudo apt-get install xserver-xorg-legacy -y
sudo tee /etc/X11/Xwrapper.config > /dev/null << 'EOF'
allowed_users=anybody
needs_root_rights=yes
EOF

sudo raspi-config nonint do_boot_behaviour B2

# Check if fb1 exists
ls -l /dev/fb*

# Check if SPI overlay loaded
dmesg | grep osoyoo

# Verify config.txt changes
cat /boot/firmware/config.txt | grep -E "(kms|spi|osoyoo)"

DISPLAY=:0 xinput_calibrator

Quick Fix Script

If you need to start over, run this one-click fix script:

#!/bin/bash
# RPi3 SPI Screen Quick Fix

# Install required packages
sudo apt-get install xserver-xorg-video-fbdev xserver-xorg-legacy -y

# Fix Xwrapper.config
sudo tee /etc/X11/Xwrapper.config > /dev/null << 'EOF' allowed_users=anybody needs_root_rights=yes EOF # Disable conflicting configs sudo mv /usr/share/X11/xorg.conf.d/20-noglamor.conf \ /usr/share/X11/xorg.conf.d/20-noglamor.conf.bak 2>/dev/null
sudo rm -f /usr/share/X11/xorg.conf.d/99-fbturbo.conf

# Create fbdev config
sudo mkdir -p /etc/X11/xorg.conf.d
sudo tee /etc/X11/xorg.conf.d/99-fbdev.conf > /dev/null << 'EOF' Section "ServerLayout" Identifier "SPI Layout" Screen "SPI Screen" EndSection Section "Device" Identifier "SPI Display" Driver "fbdev" Option "fbdev" "/dev/fb1" Option "ShadowFB" "on" EndSection Section "Monitor" Identifier "SPI Monitor" EndSection Section "Screen" Identifier "SPI Screen" Monitor "SPI Monitor" Device "SPI Display" DefaultDepth 16 SubSection "Display" Depth 16 Modes "480x320" Virtual 480 320 EndSubSection EndSection EOF # Set boot behaviour sudo raspi-config nonint do_boot_behaviour B2 sudo raspi-config nonint do_wayland W1 # Configure .bash_profile cat > ~/.bash_profile << 'EOF' export FRAMEBUFFER=/dev/fb1 startx 2> /tmp/xorg_errors
EOF

echo "Fix complete. Please reboot: sudo reboot"

Choose the tutorial that matches your Raspberry Pi model and OS version:

Not sure which to choose?
• Check your Pi model: cat /proc/device-tree/model
• Check your OS version: cat /etc/os-release

Need help or have feedback? Submit a ticket and our team will get back to you within 1-2 working
days. We appreciate your patience!

Working Time: 9 AM – 6 PM GMT+8 (Monday – Friday)

Contact Us: [email protected]

© 2026 Osoyoo | osoyoo.com

Last updated: 2026-02-10