使用教程

操作步骤

用于 Raspberry Pi 的 Raspberry Pi OS / Ubuntu / Kali 和 Retropie 系统。 当 LCD 工作于树莓派这些系统时，必须手动设置分辨率，否则会导致显示异常。

1. 请在 Raspberry Pi OS 镜像下载页面 下载最新版本的镜像
2. 将压缩文件下载到 PC 上，并解压得到 .img 文件
3. TF 卡连接到 PC，使用 Panasonic SDFormatter SD 卡格式化工具 格式化 TF 卡
4. 打开 Win32 Disk Imager 镜像烧录工具，选择第 2 步准备的系统镜像，点击 write 烧写系统镜像
5. 烧写完成后，打开 TF 卡根目录的 config.txt 文件，在 config.txt 最后加入以下代码，保存并安全弹出 TF 卡，将 TF 卡插入树莓派

hvs_priority=0x32ff
gpu_mem=256
config_hdmi_boost=10
hdmi_force_hotplug=1
hdmi_group=2
hdmi_mode=87
hdmi_drive=2
hdmi_pixel_freq_limit=268500000
#pi4：
hdmi_timings=1440 0 10 10 140 2560 0 11 2 2 0 0 0 50 0 206000000 3
#3B/ZERO 需改为下面这行 timings 配置，并屏蔽 dtoverlay=vc4-kms-v3d 或 dtoverlay=vc4-fkms-v3d
#hdmi_timings=1440 0 10 10 140 2560 0 11 2 2 0 0 0 50 0 180000000 3
disable_overscan=1
framebuffer_width=1440
framebuffer_height=2560
max_framebuffer_width=1440
max_framebuffer_height=2560
extra_transpose_buffer=2

6. 将显示屏的 TOUCH 接口连接到树莓派的 USB 接口。
7. 将显示屏的 HDMI 接口连接到树莓派的 HDMI 接口，给树莓派上电，正常等待几秒后可正常显示。

注意

1. 该屏默认是竖屏显示，为了方便使用，可以调整屏幕显示方向，参见 显示旋转
2. 当树莓派同时连接多个显示器的时候，触摸效果默认作用在主屏上，如需指定触摸到副屏，参见 树莓派指定触控屏。

显示旋转

Bookworm 系统

GUI 界面旋转

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

2. 依次点击菜单"Screen"->"HDMI-A-1"->"Touchscreen" ，勾选"Waveshare Waveshare"

3. 依次进入"Screen"->"HDMI-A-1"->"Orientation"，选择所需的旋转方向，并点击 Apply 应用设置，即可完成显示与触摸方向的同步旋转。

注意

仅 Bookworm 系统支持此方法实现“显示 + 触摸”同步旋转。Bullseye 及更早版本需分别设置显示与触摸旋转。

lite 版本显示旋转（无桌面环境）

编辑启动命令行文件：

sudo nano /boot/firmware/cmdline.txt

在 cmdline.txt 文件开头添加以下参数（以下分辨率为示例，需修改为屏幕实际分辨率）：

video=HDMI-A-1:400x1280M@60,rotate=90

可替换为：

• rotate=90：顺时针旋转 90°
• rotate=180：旋转 180°
• rotate=270：逆时针旋转 90°

注意

HDMI 与其他接口（如 DPI、DSI）共享旋转设置，无法分别单独设置

Bullseye/Buster 系统

GUI 界面旋转

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

2. 依次点击菜单 "Screen"->"HDMI-A-1"->"Orientation"，选择所需的旋转角度，并点击 Apply 应用设置

lite 版本显示旋转

1. 需要修改 /boot/cmdline.txt 文件：

sudo nano /boot/cmdline.txt

2. 在 cmdline.txt 文件开头添加以下参数（以下分辨率为示例，需修改为屏幕实际分辨率）：

video=HDMI-A-1:400x1280M@60,rotate=90

可替换为：

• rotate=90：顺时针旋转 90°
• rotate=180：旋转 180°
• rotate=270：逆时针旋转 90°

注意

HDMI 与其他接口（如 DPI、DSI）共享旋转设置，无法分别单独设置

3. 保存并重新启动

  sudo reboot

Stretch/Jessie 系统

对于较旧系统（不使用 vc4-kms-v3d 或 vc4-fkms-v3d 驱动），请按以下方式设置：

1. 编辑 config.txt 文件：

   sudo nano /boot/config.txt

2. 在文件末尾加入语句：

   display_rotate=1 #1:90；2: 180； 3: 270

3. 保存后重启树莓派即可

   sudo reboot

触摸屏旋转设置

部分屏幕可通过长按背面的 Rotate Touch 按键来旋转触摸方向，每次长按可切换一次方向。

Bookworm 系统（命令行方式）

如果使用图形界面进行旋转，可以在屏幕布局编辑器窗口中勾选“Touchscreen”来同步触摸旋转。屏幕旋转方法请参考前面的介绍。命令行旋转方法请参考以下文字：

1. 创建 udev 规则文件：

   sudo nano /etc/udev/rules.d/99-waveshare-touch.rules

2. 添加所需旋转角度对应的内容（根据需要取消注释）：

   #90°：
   ENV{ID_INPUT_TOUCHSCREEN}=="1", ENV{LIBINPUT_CALIBRATION_MATRIX}="0 -1 1 1 0 0"
   
   #180°：
   #ENV{ID_INPUT_TOUCHSCREEN}=="1", ENV{LIBINPUT_CALIBRATION_MATRIX}="-1 0 1 0 -1 1"
   
   #270°：
   #ENV{ID_INPUT_TOUCHSCREEN}=="1", ENV{LIBINPUT_CALIBRATION_MATRIX}="0 1 0 -1 0 1"

3. 保存并重启

   sudo reboot

Bullseye/Buster 系统

1. 安装 libinput

   sudo apt-get install xserver-xorg-input-libinput

• 如果你安装的是 Ubuntu 系统，或者是 Jetson Nano。安装指令为

  sudo apt install xserver-xorg-input-synaptics

2. 在 /etc/X11/ 下创建 xorg.conf.d 目录（如果该目录已存在，这直接进行第 3 步）

   sudo mkdir /etc/X11/xorg.conf.d

3. 复制 40-libinput-conf 文件到刚刚创建的目录下

   sudo cp /usr/share/X11/xorg.conf.d/40-libinput.conf /etc/X11/xorg.conf.d/

4. 编辑该文件

   sudo nano /etc/X11/xorg.conf.d/40-libinput.conf
   #找到 touchscreen 的部分，在里面添加对应的旋转角度指令，然后保存即可
   #90°Right 触摸旋转：
   Option "CalibrationMatrix" "0 1 0 -1 0 1 0 0 1"
   #180° Inverted 触摸旋转：
   #Option "CalibrationMatrix" "-1 0 1 0 -1 1 0 0 1"
   #270° Left 旋转：
   #Option "CalibrationMatrix" "0 -1 1 1 0 0 0 0 1"
   类似下图位置：

5. 重启树莓派

   sudo reboot

完成以上步骤后触摸将会进行旋转。

使用触摸屏虚拟键盘

从 Raspberry Pi OS Bookworm 版本开始，系统默认集成了 Squeekboard 屏幕键盘。 当连接触摸显示屏时，在可以输入文字的情况下，屏幕键盘会自动显示；而在无法输入文字的情况下，它会自动隐藏。 对于不支持自动检测文字输入的应用程序，可以使用任务栏最右侧的键盘图标手动显示或隐藏屏幕键盘。

你也可以通过“Raspberry Pi Configuration”中的“Display”选项栏目，或通过 raspi-config 中的“Display”部分，来设置屏幕键盘的显示或隐藏。

信息

在 Raspberry Pi OS 的 Bookworm 之前的版本中，请使用 matchbox-keyboard。如果你使用的是 wayfire 桌面合成器，请使用 wvkbd。

触摸模式选择

Bookworm 系统支持两种触控模式，可在 Screen Configuration > Touchscreen 菜单中切换：

1. Mouse Emulation（默认）

   单击 = 鼠标左键功能
   长按 = 鼠标右键功能
   支持双击
   不支持滑动页面和多点触摸功能

注意

此模式适合需要鼠标操作的场景，如双击打开文件管理器，长按实现右键功能。

2. Multitouch

   支持多点触摸功能
   支持滑动页面
   不支持双击和长按右键功能

注意

此模式适合触控优化场景，如网页浏览、滚动列表。

树莓派指定触控屏

1. 在树莓派终端输入 xrandr，查看主屏所在的 HDMI-ID（大部分是 HDMI-1）；

2. 在树莓派终端输入 xinput，查看主屏所在的触摸 ID（有 2 个触摸 ID，如果不知道哪个是主屏，可以都试一下）；

3. 运行指令：xinput map-to-output <touch ID> <HDMI-ID>

（把 ID 值对应后运行指令即可指定触摸到主屏上，如：xinput map-to-output 7 HDMI-1 )

4. 由于每次开机都需要重新输入指令，可以将此指令添加到开机自启中去：

sudo nano /etc/xdg/lxsession/LXDE-pi/autostart

添加：xinput map-to-output 7 HDMI-1（记得改成自己对应 ID)，然后重启即可。