Hardware: Raspberry Pi 4B / 5

Screen: Osoyoo 3.5″ SPI Touchscreen (480×320)

System: Raspberry Pi OS Bookworm / Trixie (Version: 2025-10-01 and later)

Reference: https://osoyoo.com/2025/06/04/3-5spibookworm/

Purchase Links:

Table of Contents

• Step 1: Burn OS Image
• Step 2: Connect HDMI Monitor
• Step 3: Connect to Internet
• Step 4: Enable SSH
• Step 5: Get IP Address
• Step 6: Install SPI Screen
• Step 7: Power On
• Step 8: SSH Remote Access
• Step 9: Configure Driver
• Step 10: Edit config.txt
• Step 11: Auto-start Settings
• Step 12: CLI Auto-login
• Step 13: Configure Touch
• Troubleshooting

1Burn OS Image

Burn the Raspberry Pi OS (Bookworm or Trixie) with desktop to a TF card/micro SD card, and insert this card in your Raspberry Pi.

Download OS from: Raspberry Pi Official Website

2Connect HDMI Monitor

Connect Raspberry Pi to your HDMI monitor or TV. Plug a keyboard and mouse into Raspberry Pi USB ports.

3Connect to Internet

Get the Raspberry Pi connected to the Internet via WiFi or Ethernet.

For WiFi setup guide, visit: Raspberry Pi Basic Tutorial

4Enable SSH

Use a mouse to navigate:

Raspberry Pi Icon → Preferences → Control Centre → Interfaces → Enable SSH

Then close the window.

5Get IP Address

Open terminal and enter the following command to get the Raspberry Pi’s IP address:

hostname -I

6Install SPI Screen Hardware

Shut down the Raspberry Pi, remove the HDMI/TV monitor, keyboard and mouse. Then install the 3.5″ SPI screen.

7Power On

Power on the Raspberry Pi with the SPI screen installed.

8SSH Remote Access

Use an SSH tool to control Raspberry Pi remotely. We recommend PuTTY on Windows. For PuTTY setup guide: click here

1. Enter the IP address from Step 5 under “Host Name”
2. Enter 22 under “Port” (default SSH port)
3. Click “Open”
4. Login with your username and password

9Configure the Driver

Open the Raspberry Pi terminal via SSH and execute the following commands:

sudo apt-get update
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/

10Edit config.txt

sudo nano /boot/firmware/config.txt

10a. Comment out this line (add # at beginning):

#dtoverlay=vc4-kms-v3d

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

# ========== SPI Screen Configuration ==========
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

Save and exit: Press Ctrl+X, then Y, then Enter.

11Auto-start Settings

11a. Configure .bash_profile

Open or create the .bash_profile file:

sudo nano ~/.bash_profile

Add the following code:

export FRAMEBUFFER=/dev/fb1
startx 2> /tmp/xorg_errors

11b. Configure 99-fbturbo.conf (if it exists)

Check if the file exists and verify the content:

sudo nano /usr/share/X11/xorg.conf.d/99-fbturbo.conf

If it exists, ensure fbdev is set to /dev/fb0:

Section "Device"
        Identifier      "Allwinner A10/A13 FBDEV"
        Driver          "fbturbo"
        Option          "fbdev" "/dev/fb0"
        Option          "SwapbuffersWait" "true"
EndSection

12Set CLI Auto-login

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

13Configure Touch

After the desktop is working, connect via SSH and install the calibration software:

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

Create the calibration configuration file:

sudo nano /usr/share/X11/xorg.conf.d/99-calibration.conf

Add the following content:

Section "InputClass"
    Identifier "calibration"
    MatchProduct "ADS7846 Touchscreen"
    Option "Calibration" "241 3854 3885 240"
    Option "SwapAxes" "1"
EndSection

Reboot to apply touch settings:

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*

# Check if SPI overlay loaded
dmesg | grep -i osoyoo

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

# Verify Wayland is disabled (should show X11)
echo $XDG_SESSION_TYPE

Common Errors and Solutions

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

sudo raspi-config nonint do_wayland W1
sudo reboot

DISPLAY=:0 xinput_calibrator

One-Click Setup Script

Save the following as setup-spi.sh and run with:

chmod +x setup-spi.sh && ./setup-spi.sh

#!/bin/bash
echo "=== RPi4/5 + Osoyoo 3.5 SPI Screen Setup ==="

# Update system
sudo apt-get update

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

# Step 10: Edit config.txt
sudo sed -i 's/^dtoverlay=vc4-kms-v3d/#dtoverlay=vc4-kms-v3d/' /boot/firmware/config.txt
sudo sed -i 's/^dtoverlay=vc4-fkms-v3d/#dtoverlay=vc4-fkms-v3d/' /boot/firmware/config.txt

if ! grep -q "osoyoo35b" /boot/firmware/config.txt; then
    sudo tee -a /boot/firmware/config.txt > /dev/null << 'CONF' # ========== SPI Screen Configuration ========== 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 CONF fi # Step 11: Configure .bash_profile cat > ~/.bash_profile << 'EOF' export FRAMEBUFFER=/dev/fb1 startx 2> /tmp/xorg_errors
EOF

# Step 12: Set boot behaviour and switch to X11
sudo raspi-config nonint do_boot_behaviour B2
sudo raspi-config nonint do_wayland W1

# Step 13: Install touch support
sudo apt-get install -y xserver-xorg-input-evdev xinput-calibrator
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

echo "=== Setup complete. Rebooting... ==="
sleep 3
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