搭配树莓派使用

硬件连接

这款产品支持两种连接方式连接到树莓派使用

方法一：通过顶针连接树莓派

方法二：通过杜邦线连接树莓派

功能引脚	BCM编码	Board物理引脚序号
TP_RST	17	11
TP_INT	4	7
TP_SCL	3	5
TP_SDA	2	3
LCD_BL	18	12
LCD_RST	27	13
LCD_DC	22	15
LCD_CS	8	24
SCLK	11	23
MOSI	10	19
MISO	9	21
GND	GND	6
VCC	5V	4

开启SPI与I2C接口

在终端输入以下语句：

sudo raspi-config nonint do_spi 0
sudo raspi-config nonint do_i2c 0

Python 环境

安装库

sudo apt-get update
sudo apt-get install python3-pip
sudo apt-get install python3-pil
sudo apt-get install python3-numpy
sudo apt-get install python3-spidev
sudo apt install python3-smbus2

下载运行示例程序

wget https://www.waveshare.net/w/upload/d/d1/3inch5_RPI_LCD_F_RPI.zip
unzip 3inch5_RPI_LCD_F_RPI.zip
cd 3inch5_RPI_LCD_F_RPI
sudo python ./main.py

Bookworm系统桌面显示

方法一：配置设备树驱动屏幕（推荐）

在终端输入

wget https://www.waveshare.net/w/upload/d/da/St7796s.zip
unzip St7796s.zip
sudo cp st7796s.bin /lib/firmware/

打开config.txt文件
```
sudo nano /boot/firmware/config.txt
```

在[all]末尾添加以下语句:

dtparam=spi=on
dtoverlay=mipi-dbi-spi,speed=48000000
dtparam=compatible=st7796s\0panel-mipi-dbi-spi
dtparam=width=320,height=480,width-mm=49,height-mm=79
dtparam=reset-gpio=27,dc-gpio=22,backlight-gpio=18
dtoverlay=goodix,addr=0x5d

重启后即可正常点亮触摸屏幕
```
sudo reboot
```

方法二：安装内核模块与 DTBO 驱动屏幕

安装驱动模块

注：Bookworm需使用官方正式版本6.6.51内核版本以及以上。

确定当前内核版本
```
uname -a
```

此命令将输出完整的内核版本信息。例如，在 Raspberry Pi 5 上执行该命令，可能会得到如下输出：

Linux raspberrypi 6.12.47+rpt-rpi-2712 #1 SMP PREEMPT Debian 1:6.12.47-1+rpt1 (2025-09-16) aarch64 GNU/Linux

这表明此系统的内核版本号是6.12.47+rpt-rpi-2712 ，使用的是64位ARM（AArch64）架构。

下载安装st7796驱动模块

# 第一步：下载并进入Waveshare-st7796s驱动文件夹
wget https://www.waveshare.net/w/upload/4/49/Waveshare-st7796s.zip
unzip Waveshare-st7796s.zip
cd Waveshare-st7796s 
# 第二步：cd到对应内核版本号文件目录
# 如上面例子则运行下面指令
cd 6.12.47/64/rpi-2712-RPi5
# 复制对应版本的st7796s.ko到当前系统
sudo cp st7796s.ko /lib/modules/$(uname -r)/kernel/drivers
# 确保模块在开机时被加载，将模块名添加到 /etc/modules 文件中：
sudo nano /etc/modules
# 在末尾添加
st7796s

终端输入以下语句，处理内核模块依赖关系:

sudo depmod -a

配置驱动设备树

cd
wget https://www.waveshare.net/w/upload/2/29/Waveshare35f.dtbo
sudo cp Waveshare35f.dtbo /boot/overlays/

对于Rpi4 & Rpi5

配置驱动文件

需要先参考此处步骤#安装驱动模块

编辑config.txt配置文件
```
sudo nano /boot/firmware/config.txt
```

注释掉双屏配置语句

在[all]末尾添加以下语句

dtparam=i2c_arm=on
dtparam=i2c_arm_baudrate=50000
dtparam=spi=on
dtoverlay=Waveshare35f,fps=60,speed=48000000,rotate=90,ts_rotate_90
hdmi_force_hotplug=1
max_usb_current=1
hdmi_group=2
hdmi_mode=87
hdmi_cvt 480 320 60 6 0 0 0
hdmi_drive=2

创建屏幕配置文件

创建98-spi-screen.conf文件

sudo nano /etc/X11/xorg.conf.d/98-spi-screen.conf

添加下面参数到98-spi-screen.conf文件内

Section "Device"
    Identifier "SPI Screen"    
    Driver "fbdev"
    Option "fbdev" "/dev/fb0"
EndSection

注：整个流程操作完成之后。如果不显示。修改"/dev/fb0" 为 "/dev/fb1" 之后再重启看看

切换为X11
```
sudo raspi-config nonint do_wayland W1
```

重启生效

对于所有树莓派版本

此方法必须是基于bookworm-lite版本操作，64位 lite、32位 lite

配置驱动文件

需要先参考此处步骤#安装驱动模块

编辑config.txt配置文件
```
sudo nano /boot/firmware/config.txt
```

注释掉KMS和双屏配置语句

FBCP CLOSE

在[all]末尾添加以下语句

dtparam=i2c_arm=on
dtparam=i2c_arm_baudrate=50000
dtparam=spi=on
dtoverlay=Waveshare35f,fps=60,speed=48000000,rotate=90,ts_rotate_90
hdmi_force_hotplug=1
max_usb_current=1
hdmi_group=2
hdmi_mode=87
hdmi_cvt 480 320 60 6 0 0 0
hdmi_drive=2

下载必要的软件

安装xorg服务

sudo apt-get install --no-install-recommends xserver-xorg -y
sudo apt-get install --no-install-recommends xinit -y

- 安装桌面管理器

sudo apt install lightdm -y

- 安装树莓派官方GUI

sudo apt install raspberrypi-ui-mods -y

- 安装git

sudo apt install git -y

- 安装浏览器(可选)

sudo apt install chromium-browser -y

安装音乐播放器(可选)
```
sudo apt install vlc -y
```
下载运行驱动

打开树莓派终端，执行：

sudo apt install libraspberrypi-dev -y
sudo apt-get install unzip -y
sudo apt-get install cmake -y
sudo wget https://www.waveshare.net/w/upload/6/66/Rpi-fbcp.zip
sudo unzip ./Rpi-fbcp.zip
cd rpi-fbcp/
sudo rm -rf build
sudo mkdir -m 777 ./build
cd ./build
sudo cmake ..
sudo make -j4
sudo install fbcp /usr/local/bin/fbcp

设置自启动startx与fbcp
- 打开Bash shell文件，如果没有则自己创建一个
```
sudo nano ~/.bashrc
```

把以下代码加到文件末尾

if [ "$(cat /proc/device-tree/model | cut -d ' ' -f 3)" = "5" ]; then
    # rpi 5B configuration
    export FRAMEBUFFER=/dev/fb1
    startx  2> /tmp/xorg_errors
else
    # Non-pi5 configuration
    export FRAMEBUFFER=/dev/fb0
    startx  2> /tmp/xorg_errors
fi

- 创建并编辑一个自启动fbcp服务文件

sudo nano /etc/systemd/system/fbcp.service

在文件内添加服务配置

[Unit]
Description=Framebuffer Copy for Raspberry Pi
After=network.target

[Service]
ExecStartPre=/bin/sleep 20
ExecStart=/usr/local/bin/fbcp
Restart=always
User=root
Group=root

[Install]
WantedBy=multi-user.target

重新加载 systemd 配置

sudo systemctl daemon-reload

服务启用开机自启动

sudo systemctl enable fbcp.service

测试启动服务

sudo systemctl start fbcp.service

设置CLI自动登录

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

Note1：确保树莓派的用户名为pi否则无法正常自动登录
Note2：设置上述所有配置后，系统每次重启期间都会变久一点，SSH也需要等待一会儿才能进入；

旋转屏幕

GUI 界面旋转

1.打开"Screen Configuration"应用程序；

2.勾选上"Touchscreen"

3.进入"Screen"->"SPI-1"->"Orientation" ，勾选您需要旋转的方向，最后点击“Apply”，即可完成显示屏和触摸的同步旋转。

命令行控制桌面旋转

安装 wlr-randr 工具
```
sudo apt install wlr-randr
```
查看输出名称
```
wlr-randr
```

输出示例这里以SPI-1设备为例

执行旋转命令

 wlr-randr --output SPI-1 --transform 90
 #旋转参数可改为normal、90、180、270

调节背光

PWM调光

安装WiringPi

cd ~
git clone https://github.com/WiringPi/WiringPi.git
cd WiringPi
./build
gpio -v

安装成功会输出gpio version版本，如下所示:

手动调节显示器PWM背光

gpio -g mode 18 pwm      	#占用管脚为PWM管脚
gpio pwmc 100   		#设置 PWM 时钟分频器
gpio -g pwm 18 0         	#最暗
gpio -g pwm 18 1023      	#最亮
gpio -g mode 18 out      	#释放为输出

pinctrl调光

设置亮屏
```
sudo pinctrl set 18 op dh
```
设置息屏
```
sudo pinctrl set 18 op dl
```

Bullseye系统桌面显示

安装驱动模块

注：Bullseye需使用官方正式版本6.1.21内核版本以及以上。

确定当前内核版本
```
uname -a
```

此命令将输出完整的内核版本信息。例如，在 Raspberry Pi 5 上执行该命令，可能会得到如下输出：

Linux raspberrypi 6.1.21-v8+ #1642 SMP PREEMPT Mon Apr  3 17:24:16 BST 2023 aarch64 GNU/Linux

这表明此系统的内核版本号是6.1.21 ，使用的是64位ARM（AArch64）架构。

下载安装st7796驱动模块

# 第一步：下载并进入Waveshare-st7796s驱动文件夹
wget https://www.waveshare.net/w/upload/4/49/Waveshare-st7796s.zip
unzip Waveshare-st7796s.zip
cd Waveshare-st7796s 
# 第二步：cd到对应内核版本号文件目录
# 如上面例子则运行下面指令
cd 6.1.21/64/
# 复制对应版本的st7796s.ko到当前系统
sudo cp st7796s.ko /lib/modules/$(uname -r)/kernel/drivers
# 确保模块在开机时被加载，将模块名添加到 /etc/modules 文件中：
sudo nano /etc/modules
# 在末尾添加
st7796s

终端输入以下语句，处理内核模块依赖关系:

sudo depmod -a

配置驱动设备树

cd
wget https://www.waveshare.net/w/upload/2/29/Waveshare35f.dtbo
sudo cp Waveshare35f.dtbo /boot/overlays/

配置驱动文件

需要先参考此处步骤#安装驱动模块

编辑config.txt配置文件
```
sudo nano /boot/config.txt
```

注释掉KMS和双屏配置语句

FBCP CLOSE

在[all]末尾添加以下语句

dtparam=i2c_arm=on
dtparam=i2c_arm_baudrate=50000
dtparam=spi=on
dtoverlay=Waveshare35f,fps=60,speed=48000000,rotate=90,ts_rotate_90
hdmi_force_hotplug=1
max_usb_current=1
hdmi_group=2
hdmi_mode=87
hdmi_cvt 480 320 60 6 0 0 0
hdmi_drive=2

下载运行驱动

打开树莓派终端，执行：

sudo apt install libraspberrypi-dev -y
sudo apt-get install unzip -y
sudo apt-get install cmake -y
sudo wget https://www.waveshare.net/w/upload/6/66/Rpi-fbcp.zip
sudo unzip ./Rpi-fbcp.zip
cd rpi-fbcp/
sudo rm -rf build
sudo mkdir -m 777 ./build
cd ./build
sudo cmake ..
sudo make -j4
sudo install fbcp /usr/local/bin/fbcp

设置自启动fbcp

打开rc.local文件
```
sudo nano /etc/rc.local
```

把以下代码加到exit 0前，注意一定要添加"&" 后台运行，否则可能会出现系统不能启动的情况。

sleep 20
fbcp &

重启后生效

文档反馈

硬件连接​

方法一：通过顶针连接树莓派​

方法二：通过杜邦线连接树莓派​

开启SPI与I2C接口​

Python 环境​

Bookworm系统桌面显示​

方法一：配置设备树驱动屏幕（推荐）​

方法二：安装内核模块与 DTBO 驱动屏幕​

安装驱动模块​

对于Rpi4 & Rpi5​

对于所有树莓派版本​

旋转屏幕​

调节背光​

Bullseye系统桌面显示​

安装驱动模块​

配置驱动文件​

下载运行驱动​

设置自启动fbcp​

硬件连接

方法一：通过顶针连接树莓派

方法二：通过杜邦线连接树莓派

开启SPI与I2C接口

Python 环境

Bookworm系统桌面显示

方法一：配置设备树驱动屏幕（推荐）

方法二：安装内核模块与 DTBO 驱动屏幕

安装驱动模块

对于Rpi4 & Rpi5

对于所有树莓派版本

旋转屏幕

调节背光

Bullseye系统桌面显示

安装驱动模块

配置驱动文件

下载运行驱动

设置自启动fbcp