Raspberrypi使用教程

预安装镜像

对于新手小白，我们提供了预安装镜像方便您更快上手使用模块，你可以烧写完预安装镜像后，将TF卡插入树莓派，上电即可直接使用。

具体配置过程如下步骤。

官方系统

Bookworm系统显示配置

适用于Rpi4 & Rpi5

配置SPI显示器：
下载完系统后，将SD卡插在PC上，下载复制waveshare13.dtbo到/boot/overlays/目录
编辑config.txt配置文件：

屏蔽KMS和双屏显示，如下图

在文件最后面添加下列配置

dtparam=spi=on
dtoverlay=waveshare13
dtoverlay=audremap18
hdmi_force_hotplug=1
max_usb_current=1
hdmi_group=2
hdmi_mode=87
hdmi_cvt 480 480 60 6 0 0 0
hdmi_drive=2
display_hdmi_rotate=0

如果需要搭配棱镜使用，可以将末尾的“display_hdmi_rotate=0”改为“display_hdmi_rotate=0x10002”，详情见#参数介绍
设置CLI自动登录：

sudo raspi-config nonint do_boot_behaviour B2

Note1：确保树莓派的用户名为pi否则无法正常自动登录
切换为X11：

sudo raspi-config nonint do_wayland W1
sudo reboot

Note2：设置上述所有配置后，系统每次重启期间都会变久一点，SSH也需要等待一会儿才能进入；
下载编译安装fbcp：

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
sudo install fbcp /usr/local/bin/fbcp

设置开机自启动：

打开.bash_profile文件，如果没有.bash_profile文件则自己创建一个

sudo nano ~/.bash_profile

把以下代码加到.bash_profile文件最下面

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
    fbcp &
    startx  2> /tmp/xorg_errors
fi

上述配置重启生效

sudo reboot

适用于全系列树莓派

必须是基于bookworm-lite版本操作，64位 lite、32位 lite
配置SPI显示器：
下载完系统后，将SD卡插在PC上，下载复制waveshare13.dtbo到/boot/overlays/目录
编辑config.txt文件：

屏蔽下图对应的语句

在文件最后面添加下列配置

dtparam=spi=on
dtoverlay=waveshare13
dtoverlay=audremap18
hdmi_force_hotplug=1
max_usb_current=1
hdmi_group=2
hdmi_mode=87
hdmi_cvt 480 480 60 6 0 0 0
hdmi_drive=2
display_hdmi_rotate=0
arm_freq=1200
core_freq=500
over_voltage=2
gpu_freq=700
force_turbo=1

如果需要搭配棱镜使用，可以将“display_hdmi_rotate=0”改为“display_hdmi_rotate=0x10002”，详情见#参数介绍
下载必要的软件：

更新系统

sudo apt update && sudo apt upgrade && sudo apt full-upgrade -y

安装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

安装浏览器(可选)

sudo apt install chromium-browser -y

安装音乐播放器(可选)

sudo apt install vlc -y

安装git(可选)

sudo apt install git -y

下载编译安装fbcp：
打开树莓派终端，执行：

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
sudo install fbcp /usr/local/bin/fbcp

设置开机自启动：

打开.bash_profile文件，如果没有.bash_profile文件则自己创建一个

sudo nano ~/.bash_profile

把以下代码加到.bash_profile文件最下面

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
    fbcp &
    startx  2> /tmp/xorg_errors
fi

sudo reboot重启保存

设置CLI自动登录：

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

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

Bullseye/Buster系统显示配置

配置SPI显示器：
下载复制waveshare13.dtbo到/boot/overlays/目录

sudo cp waveshare13.dtbo /boot/overlays/

编辑config.txt文件：
屏蔽下图对应的语句

在config.txt最后加入以下代码

dtparam=spi=on
dtoverlay=waveshare13
dtoverlay=audremap18
hdmi_force_hotplug=1
max_usb_current=1
hdmi_group=2
hdmi_mode=87
hdmi_cvt 480 480 60 6 0 0 0
hdmi_drive=2
display_hdmi_rotate=0
#arm_freq=1200
#core_freq=500
#over_voltage=2
#gpu_freq=700
#force_turbo=1

如果需要搭配棱镜使用，可以将“display_hdmi_rotate=0”改为“display_hdmi_rotate=0x10002”，详情见#参数介绍
下载运行驱动：
打开树莓派终端，执行：

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 mkdir -m 777 ./build
cd build
sudo cmake ..
sudo make -j8
sudo install fbcp /usr/local/bin/fbcp
sudo ./fbcp

设置开机自启动：

sudo cp ~/rpi-fbcp/build/fbcp /usr/local/bin/fbcp
sudo nano /etc/rc.local

在 exit 0 前面添加 fbcp&。注意一定要添加"&" 后台运行，否则可能会出现系统不能启动的情况。

随后需要进行重启

sudo reboot

重启后即可正常显示

音频配置

1.下载复制audremap18.dtbo到/boot/overlays/目录

sudo cp audremap18.dtbo /boot/overlays/

2.编辑config.txt配置文件

在文件最后面添加下列配置

dtoverlay=audremap18

3.切换音频输出

sudo raspi-config

依次选择System Options --> Audio --> Headphones -->Ok

4.重启生效

sudo reboot

5.音频输出测试

方法一：在指令行CLI测试；

vlc xxx.mp3

如果没有安装vlc则

sudo apt-get install vlc

方法二：在图形界面GUI测试；

鼠标双击xxx.mp3文件默认打开vlc播放，如果没有安装vlc则需要安装

sudo apt-get install vlc

按键配置

运行按键测试Demo

sudo wget https://www.waveshare.net/w/upload/f/fe/Button_press_detector.zip
sudo unzip ./Button_press_detector.zip
sudo python3 ~/Desktop/button_press_detector.py

Retropie系统

注：此系统不支持在Pi5上使用。

方法一：使用预装驱动的镜像（推荐）

搭配树莓派Zero/Zero 2W使用，建议直接使用#预安装镜像

方法二：安装驱动

下载系统

1. 将TF卡连接到PC，下载并使用Raspberry Pi Imager进行烧录对应系统镜像。

2. 镜像烧写完成后，打开TF卡根目录的config.txt文件，在config.txt末尾加入以下代码，保存并安全弹出TF卡。

hdmi_force_hotplug=1

3. 烧写完成后，将HDMI显示器接入到树莓派上，启动树莓派，进入系统后按键盘的F4，进入终端。（也可通过网络登录到终端控制界面）

配置WIFI

在终端输入raspi-config打开系统配置界面，选择System Options -> Wireless LAN

选择国家，这里我选择了CN China。

输入WIFI名称。

输入WIFI密码，重启保存。

运行fbcp移植程序

cd ~
wget https://www.waveshare.net/w/upload/1/18/Gamepi13_fbcp.zip
unzip Gamepi13_fbcp.zip
cd Gamepi13_fbcp/build
sudo chmod +x *
sudo ./fbcp-ili9341

等待几秒后1.3寸屏幕即可正常显示

设置用户界面尺寸

更改 LCD 显示分辨率

sudo nano /boot/config.txt

添加以下代码

hdmi_force_hotplug=1
hdmi_group=2
hdmi_mode=1
hdmi_mode=87
hdmi_cvt 480 480 60 6 0 0 0
#display_rotate=0
avoid_warnings=1

重启保存

sudo reboot

如果需要搭配棱镜使用，可以将“display_rotate=0”改为“display_rotate=0x10002”，详情见#参数介绍

设置开机自启动

sudo nano /etc/rc.local

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

sudo /home/pi/fbcp-ili9341/build/fbcp-ili9341 &

配置操作杆

打开树莓派终端，输入以下指令进入配置界面

cd RetroPie-Setup/
sudo ./retropie_setup.sh

安装好驱动程序后，编辑mk_arcade_joystick_rpi.conf文件

sudo nano /etc/modprobe.d/mk_arcade_joystick_rpi.conf

注释掉原有语句，将以下操纵杆配置添加到此文件

options mk_arcade_joystick_rpi map=5 gpio=5,6,16,13,26,19,21,20,15,12,14,23

重新启动以重新映射您的按键后，Gamepad 即可工作

音频配置教程

将 audremap18.dtbo 下载到您的pi

wget https://www.waveshare.net/w/upload/9/90/Audremap18.dtbo
sudo cp Audremap18.dtbo /boot/overlays/

编辑config.txt

sudo nano /boot/config.txt

在末尾添加以下代码，启用gpio18作为pwm音频引脚

dtoverlay=audremap18，pins_18_19

重启后，您需要添加本地音频

输入sudo raspi-config选择System Options -> Audio -> Headphones

转到 Retropie 菜单

选择->Audio->Headphones,重启保存声音功能即可正常使用。

添加游戏

由于大部分游戏容量很大，在添加游戏前，我们先进行文件系统扩展。

在Retropie 菜单界面选择RASPI-CONFIG

选择7 Advanced Options -> A1 Expand Filesystem，回车-》Finish。(这个过程需要接上USB键盘进行操作)

选择Ok，对系统进行重启。重启后，文件系统扩展完成。

准备好相应的游戏ROMs。

这里推荐一个非常酷的网站：http://coolrom.com/

你可以通过PC机，在里面下载各种游戏ROMs。比如我们要玩Sony Playstation游戏，可以选择

在里面找到你想玩的游戏，进行下载即可。例如：http://coolrom.com/roms/psx/39719/Tekken_3.php

点击此处进行下载。

把下载好的文件解压，得到以下的ROMs

更新ROMs

网线接到树莓派上（树莓派需要和你的PC机在同一个局域网）。在RetroPie列表下找到SHOW IP，按"A"，可以查到当前树莓派的IP。如下图：

在你的PC机上，打开相应的IP，如下图：

把ROMs复制到相关的目录即可，如下图：

之后在模拟器选择界面，按"Start"->QUIT->RESTART EMULATIONSTATION，按"A"确定。重启模拟器之后即可看到新加入的游戏。

那么就开启你的复古游戏机之旅吧！

参数介绍

通过在 config.txt 文件中设置 display_hdmi_rotate 参数，您可以调整 HDMI 显示器的方向，包括旋转和翻转。
以下是参数的具体说明：

display_hdmi_rotate	结果
0	无旋转（默认方向）
1	顺时针旋转90度
2	顺时针旋转180度
3	顺时针旋转270度
0x10000	水平翻转
0x20000	垂直翻转

您还可以通过组合设置实现更复杂的效果。例如：

180 度旋转 + 水平和垂直翻转 = 0x20000 + 0x10000 + 2 = 0x30002

如果您设置 display_hdmi_rotate=1（90 度）或 display_hdmi_rotate=3（270 度），系统会使用额外的 GPU 内存来完成图像旋转。

对于 GPU 内存设置为 16MB 的设备，这些选项可能无法正常工作。可以修改 config.txt 文件中的 gpu_mem 参数来增加 GPU 内存分配。

gpu_mem=64

导航菜单

模板: RPI for gamepi13

目录

Raspberrypi使用教程

预安装镜像

官方系统

Bookworm系统显示配置

适用于Rpi4 & Rpi5

适用于全系列树莓派

Bullseye/Buster系统显示配置

音频配置

按键配置

Retropie系统

方法一：使用预装驱动的镜像（推荐）

方法二：安装驱动

下载系统

配置WIFI

运行fbcp移植程序

设置用户界面尺寸

设置开机自启动

配置操作杆

音频配置教程

添加游戏

参数介绍