本页总览
触摸显示屏
树莓派触摸显示屏
树莓派触摸显示屏 是一款 7 英寸触摸屏 LCD，适用于平板电脑、娱乐系统和信息仪表盘等交互式项目。
该显示屏采用金属框架背板，并预装了树莓派显示转换板和金属支座。可在此处下载触摸显示屏的机械图纸。
警告
显示屏必须安装在合适的机箱中。机箱（包括为通风或线缆入口提供的任何间隙）必须确保电路板的所有部分在操作期间无法触及。
兼容性
触摸显示屏兼容 Raspberry Pi B+ 及更高版本。
不兼容 Raspberry Pi Zero 系列或 Raspberry Pi Keyboard 电脑，因为它们没有 DSI 连接器。
Raspberry Pi 5 使用不同尺寸的 DSI 连接器，但您可以使用 22 路转 15 路扁平柔性线缆（需另购）将其连接到触摸显示屏。
Raspberry Pi 5 和 Raspberry Pi Compute Module 原生支持连接最多两个触摸显示屏。
您可以将任何 Raspberry Pi B+ 及更高版本安装到触摸显示屏背面。但安装 Raspberry Pi B 或更早版本时，需要额外的安装硬件来将支座安装到显示 PCB 上。
自动检测
Raspberry Pi B+ 及更高版本设备会自动检测触摸显示屏。
Raspberry Pi A 和 B 可以自动检测显示屏，但该功能默认关闭，因此您必须手动启用它。
Raspberry Pi Compute Module 不会自动检测 DSI 显示屏，因为它们专为工业应用设计，集成商可以将任何和所有 GPIO 及接口用于自己的目的。
规格说明
本节介绍触摸显示屏的特性和能力。
功能特性
触摸显示屏具有以下功能：
- 800 × 480px RGB LCD 显示屏
- 24 位 RGB 显示：可呈现超过 1600 万种色彩
- 多点触控：最多支持十个同时触控点
- 屏幕键盘：支持使用屏幕键盘替代物理键盘
- 集成供电：由主机树莓派设备直接供电，无需独立电源
- 背光寿命：20,000 小时
视角性能
- 工业品质：水平视角 140 度，垂直视角 120 度
- PWM 背光控制和电源控制：通过 I2C 接口
- 对比度：500
- 平均亮度：250 cd/m²
- 可视区域：154.08 × 85.92 毫米
- 视角（度）：
- 顶部 - 50
- 底部 - 70
- 左 - 70
- 右 - 70
电源
- 功耗：最大亮度时，典型值为 5V 200mA。
尺寸与环境参数
- 工作温度：-20 至 +70 摄氏度
- 存储温度：-30 至 +80 摄氏度
- 外部尺寸：192.96 × 110.76 毫米
硬件
触摸显示屏包装盒内含以下物品：
- 一块触摸显示屏
- 四个支座和四个 M2.5 螺丝（预装但可拆卸）
- 一条 15 路转 15 路扁平柔性线缆
- 四根跳线
连接方式
触摸显示屏通过以下方式连接到树莓派设备：
-
DSI 连接器。将合适的扁平柔性线缆 (FFC) 连接到此接口以传输视频和触摸数据。
- Raspberry Pi 4 及更早版本使用随附的 15 路转 15 路 FFC。
- Raspberry Pi 5 和 Raspberry Pi Compute Module IO Board 使用树莓派标准转 Mini FFC（另购）。
-
GPIO 排针。随附的跳线将电力从树莓派的 GPIO 排针传输到显示屏。
连接到树莓派设备
根据您的设备选择相应的步骤。
将设备连接到显示屏不需要特殊工具，但您必须准备好正确的 FFC 线缆。您还需要您的设备、启动介质和电源。
要将设备安装到显示屏上，请使用适合显示屏随附的 M2.5 螺丝的十字螺丝刀。如果不想将设备安装到显示屏上，您可能需要更长的 FFC 线缆。
- Raspberry Pi B+ 及更高版本
- Raspberry Pi Compute Module
Raspberry Pi B+ 及更高版本
警告
开始第 1 步之前，请断开树莓派的电源连接。
第 1 步：将 FFC 连接到触摸显示屏
开始之前，请确认您为树莓派型号准备了正确的扁平柔性线缆：
- 对于 Raspberry Pi 5，请使用 22 路转 15 路 FFC。
- 对于所有其他树莓派型号，请使用随附的 15 路转 15 路 FFC。
连接 FFC：
-
向外滑动触摸显示屏上 FFC 连接器两侧的固定夹。
-
将 FFC 插入触摸显示屏的 FFC 连接器，然后将固定夹推回原位以固定线缆。
金属触点朝上，远离触摸显示屏。
如果连接到 Raspberry Pi 5，因此使用 22 路转 15 路 FFC，则 22 路端是线缆的较小端。将线缆的较大端插入触摸显示屏的 FFC 连接器。
第 2 步：（可选）将树莓派安装到触摸显示屏
您可以将任何 Raspberry Pi B+ 及更高版本安装到触摸显示屏背面。
要将设备安装到显示屏上：
- 将树莓派的四个角支座与触摸显示屏背面的四个安装点对齐。
- 将 M2.5 螺丝（随附）插入四个角支座并拧紧，直到树莓派牢固固定。
第 3 步：将 FFC 连接到树莓派
注意
在此步骤中，请小心不要夹住 FFC。
-
向上滑动树莓派上 FFC 连接器两侧的固定夹。在 Raspberry Pi 4B 及更早版本上，此接口标记为
DISPLAY。 -
将 FFC 的另一端连接到树莓派上的端口，然后将固定夹推回原位以固定线缆。
金属触点必须朝向以太网和 USB-A 端口。
第 4 步：为显示屏供电，然后开机
警告
通电之前，显示屏必须安装在确保电路板所有部分无法触及的机箱中。
我们建议使用树莓派的 GPIO 排针为触摸显示屏供电。
或者，您也可以使用单独的微型 USB 电源直接为显示屏供电。
连接到 GPIO 排针：
-
在树莓派 GPIO 的 5V 和
GND引脚与显示屏的 5V 和GND引脚之间连接跳线。
-
将黑色跳线的一端连接到树莓派的第六针（
GND）。 -
将红色跳线的一端连接到第四针（5V）。
如果第六针不可用，请使用任何其他
GND针连接黑线。如果第四针不可用，请使用另一个 5V 针（第二针）连接红线。
-
将黑线的另一端连接到显示屏上的
GND引脚。 -
将红线的另一端连接到显示屏上的 5V 引脚。
-
将树莓派连接到电源，然后开机。触摸显示屏即会打开。
使用微型 USB 电源连接
如果不想使用树莓派为触摸显示屏供电，可以使用微型 USB 电源。我们建议使用树莓派 12.5W 电源，以确保显示屏按预期运行。
注意
如果选择使用微型 USB 供电，请不要将树莓派上的 GPIO 引脚连接到显示屏。
- 插入微型 USB 电源线。
启动树莓派
-
将启动介质连接到树莓派。
-
将树莓派连接到电源。
设备启动时，触摸显示屏即会打开，但 Raspberry Pi OS 可能需要长达一分钟的时间才能在屏幕上开始显示输出。
Raspberry Pi Compute Module
本节假设您熟悉您的 Compute Module。更多信息请参阅树莓派 Compute Module。
您可以将触摸显示屏连接到已安装到 IO Board 上的 Raspberry Pi Compute Module。这需要使用树莓派标准转 Mini FFC（另购）。
开始之前，请将 Compute Module 的系统软件和固件更新到最新版本。
第 1 步：在 config.txt 中指定显示屏
Raspberry Pi Compute Module 不会自动检测触摸显示屏。
通过向 config.txt 中添加叠加条目，将 Compute Module 配置为其所连接的设备。默认连接端口为 1，但您也可以使用端口 0。
要完成此步骤，可以将 Compute Module 连接到显示器，或使用远程方法（如 SSH 或 Raspberry Pi Connect 的屏幕共享或远程 shell）。
备注
如果您使用的是带有 eMMC 存储的 Raspberry Pi Compute Module，请确保编辑用于启动设备的配置文件：即存储在 eMMC 上的配置文件，或者如果您已重新配置启动顺序，则是外部启动介质上的配置文件。更多信息请参阅 rpiboot。
启用触摸显示屏：
- 启动 Compute Module，然后打开
/boot/firmware/config.txt。- 要将显示屏连接到
DISP1/DSI1，请在文件末尾添加dtoverlay=vc4-kms-dsi-7inch。 - 要将显示屏连接到
DISP0/DSI0，请在文件末尾添加dtoverlay=vc4-kms-dsi-7inch,dsi0。
- 要将显示屏连接到
- 删除
display_auto_detect行（如果存在）。 - 关闭设备。
第 2 步：将触摸显示屏连接到 Compute Module IO Board
重要
继续之前，请断开 IO Board 的电源连接。
将触摸显示屏连接到第 1 步中选择的 IO Board 端口（DISP1/DSI1 或 DISP0/DSI0）。连接 FFC 后，设置相应的跳线，然后连接显示屏与板之间的电源线。
连接到触摸显示屏：
- 向外滑动触摸显示屏上 FFC 连接器两侧的固定夹。
- 将 FFC 的一端插入触摸显示屏的 FFC 连接器，然后将固定夹推回原位以固定线缆。
- 将 FFC 的另一端插入第 1 步中选择的端口，然后将固定夹推回原位。
- 参考下表，设置与第 1 步中创建的叠加条目对应的跳线。
| 显示屏 | 板 | 操作 |
|---|---|---|
DISP1/DSI1 | CMIO1 或 CMIO3 板上的 CM1、CM3、CM3+ 或 CM4S | 使用跳线连接 GPIO 0 到 CD1_SDA，1 到 CD1_SCL |
DISP1/DSI1 | CM4IO 板上的 CM4 | 无需额外跳线 |
DISP1/DSI1 | CM5IO 板上的 CM5 | 在 J6 上添加跳线，如丝印所示 |
DISP0/DSI0 | CMIO1 或 CMIO3 板上的 CM1、CM3、CM3+ 或 CM4S | 使用跳线连接 GPIO 28 到 CD0_SDA，29 到 CD0_SCL |
DISP0/DSI0 | CM4IO 板上的 CM4 | 在 J6 上添加跳线，如丝印所示 |
DISP0/DSI0 | CM5IO 板上的 CM5 | 无需额外跳线 |
-
将黑色跳线的一端连接到 IO Board 上 GPIO 排针的第六针（
GND）。 -
将红色跳线的一端连接到 IO Board 上 GPIO 排针的第四针（5V）。
-
将黑线的另一端连接到显示屏上的
GND引脚。 -
将红线的另一端连接到显示屏上的 5V 引脚。
第 3 步：启动 Compute Module
警告
通电之前，显示屏必须安装在确保电路板所有部分无法触及的机箱中。
启动 Compute Module：
-
将启动介质连接到 Compute Module——如果从 eMMC 启动，请跳过此步骤。
-
将树莓派设备连接到电源。
-
如果 IO Board 有电源按钮，请按下并松开电源按钮。
设备启动时，触摸显示屏即会打开，但 Raspberry Pi OS 可能需要长达一分钟的时间才能在屏幕上开始显示输出。
故障排除
您的显示屏现在可以使用了，但如果它无法打开或不显示任何内容，请检查以下事项：
- DSI 连接。检查 FFC 线缆两端是否正确插入，金属条是否正确朝向连接点，以及是否连接到正确的 DSI 连接器。
- 电源。检查您的设备是否已通电并已连接启动介质（如需要）。如果使用带电源开关的 Compute Module，请检查开关是否已按下。
- GPIO 连接。如果显示屏由您的设备供电，请检查电源线是否正确插入，并连接到显示屏和 GPIO 排针上的正确引脚。
- 微型 USB 连接。如果显示屏通过微型 USB 供电，请检查连接和电源适配器。
config.txt。如果您使用的是 Compute Module，请检查第 1 步中添加到config.txt的叠加条目的语法。还需确认已指定正确的显示屏端口，并且已删除文件中任何display_auto_detect行。- EEPROM 启动顺序。如果您使用的是带有板载启动介质的 Compute Module，或者有多个驱动器连接到 Compute Module，请确保第 1 步中编辑的
config.txt文件位于您正在启动的启动介质上。
如果以上措施均无效，请访问树莓派论坛获取进一步帮助。
屏幕键盘
Raspberry Pi OS Bookworm 及更高版本包含 Squeekboard 屏幕键盘。
使用触摸显示屏时，该键盘会在可输入文本时自动显示，在无法输入文本时自动隐藏。
对于不支持文本输入检测的应用程序，您可以通过选择任务栏右上角的键盘图标来手动显示或隐藏键盘。
使用树莓派图形界面始终显示或始终禁用屏幕键盘：
- 从树莓派菜单中，转到 首选项 > 控制中心 > 显示。
- 根据需要选择 始终启用 或 已禁用。
使用命令行永久显示或禁用屏幕键盘：
- 打开终端，输入
sudo raspi-config。 - 导航到
raspi-config的 Display 部分，然后选择键盘设置。
禁用显示屏
备注
要撤销此操作，请使用 SSH 连接（如 Raspberry Pi Connect 的远程访问）、HDMI 显示器或另一台连接了树莓派启动介质的计算机。
连接到树莓派时禁用显示屏：
- 打开
/boot/firmware/config.txt - 添加以下行：
ignore_lcd=1 - 在命令行中输入
sudo reboot重启。
禁用触摸屏
您可以禁用触摸屏，继续将触摸显示屏作为标准屏幕使用。
禁用触摸屏：
- 打开
/boot/firmware/config.txt - 添加以下行：
disable_touchscreen=1 - 在命令行中输入
sudo reboot重启。
更改屏幕方向
如果您使用的是带桌面环境的 Raspberry Pi OS，可以使用树莓派控制中心应用程序更改触摸显示屏的方向。这使您可以独立更改多个已连接显示屏的方向。
如果您使用的是 Raspberry Pi OS Lite（无桌面环境），可以通过编辑 /boot/firmware/cmdline.txt 来更改触摸显示屏的方向。但是，如果连接了多个显示屏，此方法会同时更改所有显示屏的方向。
有四种方向可供选择：
- 正常（默认）。竖屏格式。
- 向左。显示屏顺时针旋转 90 度。
- 反转。显示屏旋转 180 度。
- 向右。显示屏顺时针旋转 270 度。
使用桌面环境
使用树莓派桌面更改显示方向：
- 转到 首选项 > 控制中心 > 屏幕。
- 右键单击布局编辑器中代表触摸显示屏的矩形（可能标记为
DSI-1）。 - 选择 方向。
- 选择 正常、向左、反转 或 向右 来旋转显示屏。
- 选择 应用，然后选择 确定 保留更改，或选择 取消 放弃更改。
使用内核命令行
备注
使用 cmdline.txt 无法将 DSI 显示屏与 HDMI 显示屏分开旋转。同时使用 DSI 和 HDMI 连接时，它们共享相同的旋转值。
通过编辑内核命令行在控制台模式下更改显示方向：
-
打开
/boot/firmware/cmdline.txt文件，其中包含 Raspberry Pi OS 启动时读取的参数。 -
在文件末尾添加以下内容，将
<rotation-value>替换为顺时针旋转的度数（0、90、180或270）：video=DSI-1:800x480@60,rotate=<rotation-value>rotate=设置仅旋转文本模式控制台。对于直接写入 DRM 的应用程序（如cvlc或 libcamera 应用程序），请使用它们自带的旋转选项（如果可用）。
更改显示屏亮度
-
转到 首选项 > 控制中心 > 屏幕。
-
右键单击布局编辑器中代表触摸显示屏的矩形（可能标记为
DSI-1）。 -
选择 亮度。
-
选择亮度级别。
亮度级别会立即更改。
自定义触摸屏设置
备注
这些设置仅在旋转显示屏并在非桌面环境中使用触摸输入时才需要。
使用设备树叠加层告诉 Raspberry Pi OS 如何在启动时配置触摸显示屏。叠加层名称为 vc4-kms-dsi-7inch。
修改启动配置中的设备树叠加层：
- 打开
/boot/firmware/config.txt。 - 将所需的设备树参数添加到
dtoverlay行中，用逗号分隔。请参阅设备树选项表了解详细信息。
设备树选项
vc4-kms-dsi-7inch 叠加层支持以下选项：
| DT参数 | 操作 |
|---|---|
sizex | 设置 X 触摸分辨率（默认为 800） |
sizey | 设置 Y 触摸分辨率（默认为 480） |
invx | 反转 X 坐标 |
invy | 反转 Y 坐标 |
swapxy | 交换 X 和 Y 坐标 |
disable_touch | 禁用触摸叠加层 |
- 布尔值（
invx、invy、swapxy和disable_touch）出现时默认为 true，但可以使用后缀=0将其设置为 false。 - 整数值（
sizex和sizey）需要一个数字，例如sizey=240。
示例
以下示例将 X 触摸分辨率设置为 400 像素，并反转 X 和 Y 坐标：
dtoverlay=vc4-kms-dsi-7inch,sizex=400,invx,invy
旋转触摸输入
警告
通过设备树旋转触摸输入可能会与输入库发生冲突。请尽可能在输入库或桌面中配置触摸事件旋转。
触摸输入的旋转与显示屏本身的方向无关。
更改触摸输入方向：
- 打开
/boot/firmware/config.txt。 - 在文件末尾添加
dtoverlay。 - 在命令行中使用
sudo reboot重启。
dtoverlay=vc4-kms-dsi-7inch,invx,invy
然后，从 config.txt 中删除以下行（如果存在），禁用自动显示检测功能：
display_auto_detect=1
中文翻译版以英文版相同知识授权方式共享：CC-BY-SA 4.0。交流 Q群：498908352