跳到主要内容

树莓派使用

硬件连接​

注意

连接前请断开电源，确保 DSI 排线方向连接无误。仅通过 DSI 排线供电不足，必须通过顶针接口或 Type-C 接口额外提供 5 V 电源，二者选择其一。

插拔 DSI 连接器时请轻柔操作，避免用力过大或倾斜插拔，以免造成连接器损坏或接触不良。

Raspberry Pi 5​

  1. 使用适配的 22PIN DSI 排线，将屏幕 DSI 接口连接到 Raspberry Pi 5 的 CAM/DISP1 接口。
  2. 按下图安装树莓派并连接供电，核对供电触点及 5 V、GND 极性。
  3. 确认触摸接口选择开关置于 I2C0，检查连接后再接通树莓派电源。

10.1inch DSI LCD (E) 连接 Raspberry Pi 5

Raspberry Pi 4B / 3B+ / 3A+​

  1. 使用适配树莓派 15PIN DSI 接口的排线，将屏幕 DSI 接口连接到主板 DSI 接口。
  2. 按下图安装主板并核对供电连接，将触摸接口选择开关置于 I2C0。
  3. 检查排线方向和供电极性后，再接通树莓派电源。

10.1inch DSI LCD (E) 连接 Raspberry Pi 4B

10.1inch DSI LCD (E) 连接 Raspberry Pi 3B+

软件设置​

烧录系统​

  1. 安装 Raspberry Pi Imager 镜像烧录工具。
  2. 写入会覆盖目标卡上的数据。确认目标 Micro SD 卡后，选择对应树莓派型号及 Raspberry Pi OS Trixie 或 Bookworm 桌面系统，完成烧录。
  3. 启动树莓派并连接网络，按下一节说明更新内核后，再配置屏幕。

以下动图演示 Raspberry Pi Imager 的烧录流程，系统版本按上述要求选择。

Raspberry Pi Imager 系统烧录流程演示

更新内核​

当前官方系统的内核版本为 6.18.50，屏幕驱动需在 6.18.55 之后的内核版本中才能调用。配置 config.txt 前，先在树莓派终端执行以下命令更新内核：

sudo apt-get update
sudo rpi-update pulls/7662

DSI lane 配置​

只添加与主板和实际接口对应的一组屏幕配置。若文件中已有 dtoverlay=vc4-kms-v3d，保留一条即可。

Raspberry Pi 4B / 3B+ / 3A+：2 lane​

dtoverlay=vc4-kms-v3d
dtoverlay=vc4-kms-dsi-waveshare-panel,10_1_inchE_2lane

Raspberry Pi 5 / CM5 / CM4 / CM3+ / CM3：4 lane​

以下默认启用 DSI1。若连接 DSI0，将 DSI1 对应行注释，并取消最后一行的注释。

dtoverlay=vc4-kms-v3d
#DSI1 Use
dtoverlay=vc4-kms-dsi-waveshare-panel,10_1_inchE_4lane
#DSI0 Use
#dtoverlay=vc4-kms-dsi-waveshare-panel,10_1_inchE_4lane,dsi0

保存配置后，执行 sudo reboot 重启树莓派，使内核更新和屏幕配置生效，再检查显示及触摸功能。

调节背光亮度​

图形界面调光​

以下步骤以 Trixie 系统为例：

  1. 点击左上角菜单，依次进入 "Preferences" > "Control Center"，选择 "Screens"

    DSI 屏幕调光

  2. 进入 "Screen" > 实际连接的 DSI 显示器 > "Brightness"，勾选并调整所需的背光亮度，最后点击 Apply 保存设置。截图中的 DSI 编号仅作示例。

    DSI 屏幕调光

使用微雪背光调节应用程序​

wget https://www.waveshare.net/w/upload/f/f4/Brightness.zip
unzip Brightness.zip
cd Brightness
sudo chmod +x install.sh
./install.sh

安装完成后，可以在开始菜单 > "Accessories" > "Brightness" 打开该程序，如下图：

DSI 屏幕调光

使用终端调节背光亮度​

 echo X | sudo tee /sys/class/backlight/*/brightness

其中 X 表示 0~255 中的任意数字。0 表示背光最暗，255 表示背光最亮。例如：

echo 100 | sudo tee /sys/class/backlight/*/brightness
echo 0 | sudo tee /sys/class/backlight/*/brightness
echo 255 | sudo tee /sys/class/backlight/*/brightness

GUI 界面旋转​

Trixie 显示旋转​

以下步骤以 Trixie 系统为例：

  1. 点击左上角菜单，依次进入 "Preferences" > "Control Center"，选择 "Screens"

    DSI 屏幕旋转

  2. 进入 "Screen" > 实际连接的 DSI 显示器 > "Touchscreen"，勾选对应的 Goodix Capacitive TouchScreen。设备名称中的总线编号以系统识别结果为准。

    DSI 屏幕旋转

  3. 在同一 DSI 显示器的 Orientation 中选择所需旋转方向，最后点击 Apply 完成显示和触摸同步旋转。

    DSI 屏幕旋转

lite 版本显示旋转​

sudo nano /boot/firmware/cmdline.txt

在 cmdline.txt 文件原有内容后追加一条对应角度的显示旋转指令，以空格分隔，整个文件保持为一行，保存重启后生效。以下指令使用本屏的原生分辨率 1920 × 1200，不要同时添加多个角度。

  • 旋转指令

    # 显示旋转 90 度
    video=DSI-1:1920x1200e,rotate=90

    # 显示旋转 270 度
    video=DSI-1:1920x1200e,rotate=270

    # 显示旋转 180 度
    video=DSI-1:1920x1200e,rotate=180
警告
  1. 如果是使用 Pi5/CM5，以实际识别到的 DSI 显示器编号为准，例如"DSI-2"。
  2. 无法使用 cmdline.txt 将 DSI 显示器与 HDMI 显示器分开旋转。当您同时使用 DSI 和 HDMI 时，它们共享相同的旋转值。

触摸旋转​

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

  1. 创建触摸旋转规则文件 /etc/udev/rules.d/99-waveshare-touch.rules。

    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"

    # 触摸旋转 270 度
    ENV{ID_INPUT_TOUCHSCREEN}=="1", ENV{LIBINPUT_CALIBRATION_MATRIX}="0 1 0 -1 0 1"

    # 触摸旋转 180 度
    ENV{ID_INPUT_TOUCHSCREEN}=="1", ENV{LIBINPUT_CALIBRATION_MATRIX}="-1 0 1 0 -1 1"

  3. 保存退出后，在终端执行重启命令，不要将该命令写入规则文件。

    sudo reboot

触摸模式选择​

DSI 屏幕触摸模式选择

  1. Mouse Emulation（默认）

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

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

  2. Multitouch

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

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

使用触摸屏虚拟键盘​

  • 系统会在可输入文字时自动弹出，在不可输入文字时自动隐藏。

  • 也可以通过任务栏右上角的键盘图标手动显示或隐藏

    DSI 屏幕虚拟键盘

    你也可以通过左上角菜单 "Preferences" > "Control Centre" > "Display" 来永久设置屏幕键盘的显示或隐藏。

    DSI 屏幕虚拟键盘