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

# 显示屏

## 树莓派触摸显示屏

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

![树莓派 7 英寸触摸显示屏](https://1423291173-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCOxpD6RTIfF28SyASLTE%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://1423291173-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCOxpD6RTIfF28SyASLTE%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://book.bsdcn.org/pages/TsWdG4jHE0j0eN6cdgH0#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://1423291173-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCOxpD6RTIfF28SyASLTE%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://1423291173-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCOxpD6RTIfF28SyASLTE%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://book.bsdcn.org/rpicn/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://book.bsdcn.org/pages/rnnR0Ga5BYwaZ45uT4aw#%E5%88%B7%E5%86%99-emmc)。

要启用触摸显示屏：

1. 启动计算模块，然后打开 [`/boot/firmware/config.txt`](https://book.bsdcn.org/rpicn/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://1423291173-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCOxpD6RTIfF28SyASLTE%2Fuploads%2Fgit-blob-62646095811d29cc61268c854cc9aecca561e395%2Fcmio4pins.png?alt=media)

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

   ![显示屏的 5 V 和 GND 引脚的位置](https://1423291173-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCOxpD6RTIfF28SyASLTE%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://book.bsdcn.org/rpicn/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
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://book.bsdcn.org/rpicn/pei-jian/xian-shi-qi.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
