> For the complete documentation index, see [llms.txt](https://rpicn.bsdcn.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://rpicn.bsdcn.org/pei-jian/xian-shi-qi.md).

# 显示屏

## 树莓派触摸显示屏

[树莓派触摸显示屏](https://www.raspberrypi.com/products/raspberry-pi-touch-display/)是一款 7 英寸触摸屏 LCD，适用于平板电脑、娱乐系统和信息仪表板等交互式项目。

![树莓派 7 英寸触摸显示屏](https://3761843483-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvQpIJ2H9hr4SPLGQVGEh%2Fuploads%2Fgit-blob-8b53f099b0374ae9c90b601010c36d2ced7a95ba%2Fdisplay.png?alt=media)

树莓派 7 英寸触摸显示屏

该显示屏采用金属框架背面，并附带树莓派显示转换板，且已预装金属间隔柱。你可以[在此](https://pip.raspberrypi.com/documents/RP-008246-DS)下载触摸显示屏的机械图。

> **警告**
>
> 显示屏必须安装在合适的外壳中。外壳（包括为通风或穿线预留的任何间隙）必须确保运行期间电路板的任何部分都不可触及。

## 兼容性

触摸显示屏兼容树莓派 B+ 及更高版本。

它不兼容树莓派 Zero 系列和树莓派键盘计算机，因为这些设备没有 DSI 连接器。

树莓派 5 使用尺寸不同的 DSI 连接器，但你可以使用[22 路转 15 路扁平柔性电缆](https://www.raspberrypi.com/products/display-cable/)（单独出售）将其连接到触摸显示屏。

树莓派 5 和树莓派计算模块原生支持连接最多两台触摸显示屏。

你可以将任何树莓派 B+ 及更高版本安装到触摸显示屏背面。若要安装树莓派 B 及更早型号，则需要额外的安装硬件来固定显示屏 PCB 上的间隔柱。

## 自动检测

树莓派 B+ 及更高版本的设备会自动检测触摸显示屏。

树莓派 A 和 B 也可以自动检测显示屏，但该功能默认关闭，因此你必须手动启用它。

树莓派计算模块不会自动检测 DSI 显示屏，因为它们面向工业应用，集成商可以将所有 GPIO 和接口用于自己的目的。

## 规格

本节介绍触摸显示屏的特性和能力。

### 特性

触摸显示屏具有以下特性：

* **800 × 480 像素 RGB LCD** 显示屏
* **24 位 RGB 显示屏**，可显示超过 1600 万种颜色
* **多点触控**，支持最多 10 个同时触摸点
* **屏幕键盘**，支持使用屏幕键盘代替物理键盘
* **集成供电**，直接由主机树莓派设备供电，无需单独的电源
* **背光寿命**，20,000 小时

### 显示性能

* **工业品质**，水平 140 度视角，垂直 120 度视角
* 通过 I²C 接口进行 **PWM 背光控制和电源控制**
* **对比度** 500
* **平均亮度** 250 cd/m²
* **可视区域** 154.08 × 85.92 mm
* **视角**（度）：
  * 顶部 50
  * 底部 70
  * 左侧 70
  * 右侧 70

### 电源

* **功耗** 在最大亮度下典型值为 5 V 200 mA

### 尺寸与环境

* **工作温度** -20 至 +70 摄氏度
* **存储温度** -30 至 +80 摄氏度
* **外部尺寸** 192.96 × 110.76 mm

### 硬件

触摸显示屏的包装盒包含以下物品：

* 一台触摸显示屏
* 四个间隔柱和四颗 M2.5 螺丝（已预装，可拆卸）
* 一根 15 路转 15 路扁平柔性电缆
* 四根跳线

### 连接

触摸显示屏使用以下方式连接到树莓派设备：

* **DSI 连接器**，将合适的扁平柔性电缆（FFC）连接到此接口以传输视频和触摸数据。
  * 树莓派 4 及更早版本使用随附的 15 路转 15 路 FFC。
  * 树莓派 5 和树莓派计算模块 IO 板使用树莓派标准 – Mini FFC（[单独出售](https://www.raspberrypi.com/products/display-cable/)）。
* **GPIO 排针**，随附的跳线将树莓派上的 GPIO 排针电源传输到显示屏。

## 连接到树莓派设备

请按照适用于你设备的相应步骤操作。

将设备连接到显示屏不需要任何特殊工具，但你必须准备好正确的 FFC 电缆。你还需要设备本身、其启动介质及其电源。

要将设备安装到显示屏上，请使用一把与显示屏随附的 M2.5 螺丝相匹配的十字螺丝刀。如果你不想将设备安装到显示屏上，可能需要一根更长的 FFC 电缆。

### 树莓派 B+ 及更高版本

> **警告**
>
> 开始第 1 步前，请断开树莓派的电源。

#### 第 1 步：将 FFC 连接到触摸显示屏

开始前，请检查你为树莓派型号选择了正确的扁平柔性电缆：

* 对于 **树莓派 5**，使用 **22 路转 15 路 FFC**。
* 对于所有其他树莓派型号，使用随附的 **15 路转 15 路 FFC**。

要连接 FFC：

1. 从触摸显示屏上 FFC 连接器的两侧向外滑动固定夹。
2. 将 FFC 插入触摸显示屏的 FFC 连接器，然后将固定夹滑回原位，固定电缆。

   金属触点必须朝上，背离触摸显示屏。

   如果你连接的是树莓派 5，因而使用 22 路转 15 路 FFC，那么 22 路端是电缆较小的一端。将电缆较大的一端插入触摸显示屏的 FFC 连接器。

#### 第 2 步：（可选）将树莓派安装到触摸显示屏

你可以将任何树莓派 B+ 及更高版本安装到触摸显示屏背面。

![连接到触摸显示屏的树莓派](https://3761843483-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvQpIJ2H9hr4SPLGQVGEh%2Fuploads%2Fgit-blob-b3e2151cc963e5e25a4451da9d748e02ab9abef1%2FGPIO_power-500x333.jpg?alt=media)

连接到触摸显示屏的树莓派

要将设备安装到显示屏上：

1. 将树莓派四个角的间隔柱与触摸显示屏背面的四个安装点对齐。
2. 将四颗 M2.5 螺丝（随附）插入四个角的间隔柱，并拧紧，直到树莓派固定牢靠。

#### 第 3 步：将 FFC 连接到树莓派

> **注意**
>
> 此步骤中注意不要夹住 FFC。

1. 从树莓派上 FFC 连接器的两侧向上滑动固定夹。在树莓派 4B 及更早版本上，该连接器标记为 `DISPLAY`。
2. 将 FFC 的另一端连接到树莓派上的连接器，然后将固定夹滑回原位，固定电缆。

   金属触点必须朝向以太网和 USB-A 端口。

#### 第 4 步：为显示屏供电，然后开机

> **警告**
>
> 在通电前，显示屏必须安装在外壳中，并确保电路板的任何部分都不可触及。

我们建议使用[树莓派设备的 GPIO 排针](https://rpicn.bsdcn.org/pages/urJ1nUucEQRN33QHpbue#gpio-%E5%92%8C-40-%E8%84%9A%E6%8E%92%E9%92%88)为触摸显示屏供电。

或者，你也可以使用单独的 micro USB 电源适配器直接为显示屏供电。

**连接到 GPIO 排针**

1. 在树莓派设备的 GPIO 排针上的 5 V 和 `GND` 引脚与显示屏上的 5 V 和 `GND` 引脚之间连接跳线。

   ![树莓派排针的位置](https://3761843483-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvQpIJ2H9hr4SPLGQVGEh%2Fuploads%2Fgit-blob-44f607d74dfaaf4adb75d2ff55b37c0d4add87ad%2Fpi_plugs.png?alt=media)

   树莓派排针的位置
2. 将黑色跳线的一端连接到树莓派上的引脚 6（`GND`）。
3. 将红色跳线的一端连接到引脚 4（5 V）。

   如果引脚 6 不可用，可以使用其他任意 `GND` 引脚连接黑线。

   如果引脚 4 不可用，可以使用另一个 5 V 引脚（引脚 2）连接红线。

   ![显示屏的 5 V 和 GND 引脚的位置](https://3761843483-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvQpIJ2H9hr4SPLGQVGEh%2Fuploads%2Fgit-blob-4e1fd5da9030f2360c87651eb0f1aa1a5110b15a%2Fdisplay_plugs.png?alt=media)

   显示屏的 5 V 和 `GND` 引脚的位置
4. 将黑线的另一端连接到显示屏上的 `GND` 引脚。
5. 将红线的另一端连接到显示屏上的 5 V 引脚。
6. 将树莓派连接到电源，然后开机。触摸显示屏会亮起。

**使用 micro USB 电源适配器供电**

如果你不想使用树莓派为触摸显示屏供电，可以使用 micro USB 电源适配器代替。我们建议使用[树莓派 12.5 W 电源适配器](https://www.raspberrypi.com/products/micro-usb-power-supply/)，以确保显示屏按规格运行。

> **注意**
>
> 如果你选择使用 micro USB 供电，请不要将树莓派的 GPIO 引脚连接到显示屏。

1. 插入 micro USB 电源线。

**打开树莓派电源**

1. 将启动介质连接到树莓派。
2. 将树莓派连接到电源。

   设备启动时触摸显示屏会亮起，但树莓派系统最多可能需要一分钟才会开始在屏幕上显示输出。

### 树莓派计算模块

本节假定你熟悉自己的计算模块。有关更多信息，请参阅[树莓派计算模块](https://rpicn.bsdcn.org/shu-mei-pai/ji-suan-mo-kuai-ying-jian.md)。

你可以将触摸显示屏连接到安装在 IO 板上的树莓派计算模块。为此需要一根树莓派标准 – Mini FFC（单独出售）。

开始前，请将计算模块的系统软件和固件更新到最新版本。

#### 第 1 步：在 `config.txt` 中指定显示屏

树莓派计算模块不会自动检测触摸显示屏。

通过在 `config.txt` 中添加叠加层条目，为计算模块配置它所连接的设备。默认连接是端口 `1`，但你也可以使用端口 `0`。

要完成此步骤，请将计算模块连接到显示器，或使用 SSH、Raspberry Pi Connect 的屏幕共享或远程 shell 等远程方式。

> **注意**
>
> 如果你使用的是带 eMMC 存储器的树莓派计算模块，请务必编辑 **用于启动设备的配置文件**：即存储在 eMMC 上的文件，或者在你重新配置了启动顺序后，外部启动介质上的文件。有关更多信息，请参阅 [rpiboot](https://rpicn.bsdcn.org/pages/RnzriXTa4R1zhMZCtmlf#%E5%88%B7%E5%86%99-emmc)。

要启用触摸显示屏：

1. 启动计算模块，然后打开 [`/boot/firmware/config.txt`](https://rpicn.bsdcn.org/shu-mei-pai/config.txt.md)。
   * 要将显示屏连接到 `DISP1/DSI1`，请在文件末尾添加 `dtoverlay=vc4-kms-dsi-7inch`。
   * 要将显示屏连接到 `DISP0/DSI0`，请在文件末尾添加 `dtoverlay=vc4-kms-dsi-7inch,dsi0`。
2. 如果存在 `display_auto_detect` 行，请将其删除。
3. 关闭设备电源。

#### 第 2 步：将触摸显示屏连接到计算模块 IO 板

> **重要**
>
> 在继续之前，请断开 IO 板的电源。

将触摸显示屏连接到第 1 步中选择的 IO 板端口（`DISP1/DSI1` 或 `DISP0/DSI0`）。连接好 FFC 后，设置相应的跳线，然后在显示屏与 IO 板之间连接电源线。

要连接到触摸显示屏：

1. 从触摸显示屏上 FFC 连接器的两侧向外滑动固定夹。
2. 将 FFC 的一端插入触摸显示屏的 FFC 连接器，然后将固定夹滑回原位，固定电缆。
3. 将 FFC 的另一端插入第 1 步中选择的端口，然后将固定夹滑回原位。
4. 参照下表，设置与你在第 1 步中创建的叠加层条目相对应的跳线。

   | 显示屏          | IO 板                                                     | 操作                                                  |
   | ------------ | -------------------------------------------------------- | --------------------------------------------------- |
   | `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**                                | 无需额外的跳线。                                            |
5. 将黑色跳线的一端连接到 IO 板上 GPIO 排针的引脚 6（`GND`）。
6. 将红色跳线的一端连接到 IO 板上 GPIO 排针的引脚 4（5 V）。

   ![CM4IO 板上树莓派 GPIO 排针的位置](https://3761843483-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvQpIJ2H9hr4SPLGQVGEh%2Fuploads%2Fgit-blob-62646095811d29cc61268c854cc9aecca561e395%2Fcmio4pins.png?alt=media)

   CM4IO 板上树莓派 GPIO 排针的位置
7. 将黑线的另一端连接到显示屏上的 `GND` 引脚。
8. 将红线的另一端连接到显示屏上的 5 V 引脚。

   ![显示屏的 5 V 和 GND 引脚的位置](https://3761843483-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvQpIJ2H9hr4SPLGQVGEh%2Fuploads%2Fgit-blob-4e1fd5da9030f2360c87651eb0f1aa1a5110b15a%2Fdisplay_plugs.png?alt=media)

   显示屏的 5 V 和 `GND` 引脚的位置

#### 第 3 步：打开计算模块电源

> **警告**
>
> 在通电前，显示屏必须安装在外壳中，并确保电路板的任何部分都不可触及。

要打开计算模块电源：

1. 将启动介质连接到计算模块——如果从 eMMC 启动，请跳过此步骤。
2. 将树莓派设备连接到电源。
3. 如果 IO 板有 **电源按钮**，请按下并松开它。

   设备启动时触摸显示屏会亮起，但树莓派系统最多可能需要一分钟才会开始在屏幕上显示输出。

## 故障排除

你的显示屏现在可以使用了，但如果它无法开机或没有显示任何内容，请检查以下各项：

* **DSI 连接**。检查 FFC 电缆两端是否正确就位、金属触点是否正确朝向连接处，以及是否连接到了正确的 DSI 连接器。
* **电源**。检查设备是否已开机并连接了启动介质（如需要）。如果你使用的是带电源开关的计算模块，请检查开关是否已按下。
* **GPIO 连接**。如果显示屏由你的设备供电，请检查电源线是否正确就位，并连接到显示屏和 GPIO 排针上的正确引脚。
* **micro USB 连接**。如果显示屏由 micro USB 供电，请检查连接和电源。
* **`config.txt`**。如果你使用的是计算模块，请检查第 1 步中添加到 `config.txt` 的叠加层语法。还要检查你是否指定了正确的显示屏端口，以及是否删除了文件中的 `display_auto_detect` 行。
* **EEPROM 启动顺序**。如果你使用的是带板载启动介质的计算模块，或者计算模块连接了多个驱动器，请确保你在第 1 步中编辑的 `config.txt` 文件位于你启动所用的启动介质上。

如果这些方法都没有帮助，请访问[树莓派论坛](https://forums.raspberrypi.com/viewforum.php?f=108)获取进一步帮助。

## 屏幕键盘

树莓派系统 *Bookworm* 及更高版本包含 **Squeekboard 屏幕键盘**。

使用触摸显示屏时，当你能够输入文本，该键盘会自动出现；当你无法输入文本时，它会自动消失。

对于不支持文本输入检测的应用程序，你可以通过选择任务栏右上角的键盘图标来手动显示或隐藏键盘。

要通过树莓派图形界面始终显示或始终禁用屏幕键盘：

1. 从树莓派菜单中，转到 **首选项（Preferences）> 控制中心（Control Centre）> 显示（Display）**。
2. 根据需要选择 **始终启用（Enabled always）** 或 **禁用（Disabled）**。

要通过命令行永久显示或禁用屏幕键盘：

1. 打开终端，输入 `sudo raspi-config`。
2. 切换到 `raspi-config` 的 **显示（Display）** 部分，然后选择你的键盘设置。

## 禁用显示屏

> **注意**
>
> 要撤销此操作，请使用 SSH 连接（例如 Raspberry Pi Connect 的远程访问）、HDMI 显示屏，或使用另一台连接了树莓派设备启动介质的计算机。

要在连接到树莓派时禁用显示屏：

1. 打开 `/boot/firmware/config.txt`。
2. 添加以下行 `ignore_lcd=1`。
3. 在命令行中输入 `sudo reboot` 重启。

## 禁用触摸屏

你可以禁用触摸屏，并继续将触摸显示屏作为普通显示屏使用。

要禁用触摸屏：

1. 打开 `/boot/firmware/config.txt`。
2. 添加以下行 `disable_touchscreen=1`。
3. 在命令行中输入 `sudo reboot` 重启。

## 更改显示屏方向

如果你使用的是带桌面环境的树莓派系统，可以使用树莓派控制中心应用更改触摸显示屏的方向。这样你可以独立更改多个已连接显示屏的方向。

如果你使用的是精简版树莓派系统（没有桌面环境），可以通过编辑 `/boot/firmware/cmdline.txt` 更改触摸显示屏的方向。但是，如果你连接了多个显示屏，此方法会更改所有显示屏的方向。

有四种方向可供选择：

* **正常（Normal）**（默认）。纵向。
* **向左（Left）**。显示屏顺时针旋转 90 度。
* **倒置（Inverted）**。显示屏旋转 180 度。
* **向右（Right）**。显示屏顺时针旋转 270 度。

### 使用桌面环境

要通过树莓派桌面更改显示屏方向：

1. 转到 **首选项（Preferences）> 控制中心（Control Centre）> 屏幕（Screens）**。
2. 右键单击布局编辑器中代表触摸显示屏的矩形（可能标记为 `DSI-1`）。
3. 选择 **方向（Orientation）**。
4. 在 **正常（Normal）**、**向左（Left）**、**倒置（Inverted）** 或 **向右（Right）** 之间选择，以旋转显示屏。
5. 选择 **应用（Apply）**，然后选择 **确定（OK）** 保留更改，或选择 **取消（Cancel）** 放弃更改。

### 使用内核命令行

> **注意**
>
> 无法通过 `cmdline.txt` 将 DSI 显示屏与 HDMI 显示屏分开旋转。当同时使用 DSI 和 HDMI 连接时，它们共享相同的旋转值。

要在控制台模式下通过编辑内核命令行来更改显示屏方向：

1. 打开 `/boot/firmware/cmdline.txt` 文件，其中包含树莓派系统在启动时读取的参数。
2. 在文件末尾添加以下内容，将 `<rotation-value>` 替换为顺时针旋转的度数（`0`、`90`、`180` 或 `270`）：

   ```ini
   video=DSI-1:800x480@60,rotate=<rotation-value>
   ```

   `rotate=` 设置只旋转文本模式控制台。对于直接写入 DRM 的应用程序（例如 `cvlc` 或 libcamera 应用），请使用它们自带的旋转选项（如果可用）。

## 更改显示屏亮度

1. 转到 **首选项（Preferences）> 控制中心（Control Centre）> 屏幕（Screens）**。
2. 右键单击布局编辑器中代表触摸显示屏的矩形（可能标记为 `DSI-1`）。
3. 选择 **亮度（Brightness）**。
4. 选择一个亮度级别。

   亮度级别会立即更改。

## 自定义触摸屏设置

> **注意**
>
> 仅当在非桌面环境中旋转显示屏并使用触摸输入时，才需要这些设置。

使用设备树叠加层告诉树莓派系统在启动时如何配置触摸显示屏。该叠加层名为 `vc4-kms-dsi-7inch`。

要修改启动配置中的设备树叠加层：

1. 打开 `/boot/firmware/config.txt`。
2. 将所需的设备树参数添加到 `dtoverlay` 行中，并用逗号分隔。详情请参阅设备树选项表。

### 设备树选项

`vc4-kms-dsi-7inch` 叠加层支持以下选项：

| 设备树参数           | 操作                 |
| --------------- | ------------------ |
| `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 坐标都被反转：

```ini
dtoverlay=vc4-kms-dsi-7inch,sizex=400,invx,invy
```

### 旋转触摸输入

> **警告**
>
> 通过设备树旋转触摸输入可能会与你的输入库发生冲突。请尽可能在输入库或桌面中配置触摸事件旋转。

触摸输入的旋转与显示屏本身的方向无关。

要更改触摸输入方向：

1. 打开 [`/boot/firmware/config.txt`](https://rpicn.bsdcn.org/shu-mei-pai/config.txt.md)。
2. 在文件末尾添加 `dtoverlay`。
3. 在命令行中使用 `sudo reboot` 重启。

```ini
dtoverlay=vc4-kms-dsi-7inch,invx,invy
```

然后，如果 `config.txt` 中存在以下行，请将其删除以禁用自动显示检测：

```ini
display_auto_detect=1
```
