RDK X5 适配 DFRobot 5寸 DSI 触摸屏实战记录

HonestQiao · 2026 年3 月 20 日 15:13

前言：从 HDMI 到 DSI 的探索之路

作为一名从 RDK X3 时代就开始接触地平线开发板的老用户，拿到 RDK X5 后的第一件事自然是点亮屏幕。和之前一样，我先用 HDMI 接显示器，一切顺利——系统启动、桌面显示、跑几个 AI Demo 都没问题。

但作为一个嵌入式项目，拖着 HDMI 显示器总不是个事儿。手边正好有一块 DFRobot DFR0550-V1 5寸 DSI 触摸屏（800×480 分辨率），这是之前给树莓派买的，想着 DSI 接口应该是通用的，插上应该就能用。

结果可想而知：白屏。

查了一下官方文档，RDK X5 支持的 DSI 屏幕列表里有 2.8寸、3.4寸、4.3寸、7寸、7.9寸、8寸、10.1寸……唯独没有 5寸。官方论坛也没有人分享过 5寸屏的适配经验。

好吧，既然没有现成的方案，那就自己动手。这篇文章记录了我从零开始适配这块 5寸 DSI 屏的完整过程，包括驱动的选择、设备树的编写、背光控制的实现和显示比例修正。

一、硬件介绍

1.1 RDK X5 的显示接口

RDK X5 提供了两种视频输出方式：

HDMI：标准接口，即插即用，最高支持 1080P60
MIPI DSI：22PIN 排针接口，需要专用排线连接

重要限制：RDK X5 的 DSI 和 HDMI 不能同时使用，硬件上只能二选一。系统默认启用 HDMI，使用 DSI 需要手动切换。

1.2 DFRobot DFR0550-V1 屏幕规格

参数	规格
型号	DFR0550-V1
尺寸	5.0 英寸
分辨率	800×480
显示技术	IPS 全贴合
亮度	550cd/㎡
触控	5点电容触控
接口	树莓派 DSI 15PIN
供电	3.3V（由 DSI 接口供电）

这块屏幕原本是面向树莓派设计的，特点是免驱动——在树莓派上只需在 config.txt 里加一行配置即可。但 RDK X5 使用的地平线 X5 芯片，驱动架构完全不同，需要自行适配。

注意：这块屏有V1和V2两个版本，使用上没有差异。

1.3 硬件连接

在连接前，通过 RDK X5grfh文档，可以了解到屏幕所用的具体接口为14：
开发板接口说明

一开始我没注意，以为类似树莓派5，直接使用了接口5，但是无法点亮。

后来，直接使用树莓派5兼容的DSI屏幕连接线连接到接口14，就可以把 DFRobot DFR0550-V1 5寸 DSI 触摸屏直接连接到 RDK X5开发板上：
硬件连接图

供电方面，这块屏幕通过 DSI 接口的 3.3V 引脚供电，无需额外接线。静态工作电流约 700mA，建议 RDK X5 使用 5V/5A 电源适配器。

二、问题发现：为什么插上不亮？

2.1 初次尝试

按照官方文档切换 DSI 的方法：

# 切换 DSI 显示
sudo mv /etc/X11/xorg.conf.d/xorg_dsi_ignore.conf /etc/X11/xorg.conf.d/xorg_dsi_ignore.conf.disable
sudo mv /etc/X11/xorg.conf.d/xorg_hdmi_ignore.conf.disable /etc/X11/xorg.conf.d/xorg_hdmi_ignore.conf

然后尝试加载官方 4.3寸屏的 overlay：

echo "dtoverlay=dsi-waveshare-panel-overlay-4_3_inch" | sudo tee -a /boot/config.txt
sudo reboot

结果：白屏，背光也不亮。

2.2 排查过程

首先检查设备树是否加载：

ls /proc/device-tree/soc/disp_apb/mipi_dsi0@3e060000/

发现节点存在，但屏幕无显示。查看内核日志：

dmesg | grep -i dsi

发现驱动加载了，但初始化失败。这时候意识到一个问题：不同尺寸的 DSI 屏，驱动 IC 可能完全不同。

DFRobot 这款 5寸屏使用的是 ILI9881C 驱动 IC（后来查资料确认），而官方 4.3寸屏用的是其他型号。直接套用官方 overlay 是不行的。

三、技术调研：Linux DRM 与 Device Tree Overlay

3.1 显示子系统架构

在深入适配之前，需要理解 Linux 的显示架构：

用户空间 (X11/Wayland)
    ↓
DRM (Direct Rendering Manager) - 内核子系统
    ↓
MIPI DSI 驱动
    ↓
面板驱动 (Panel Driver)
    ↓
硬件 (DSI 控制器 + 面板)

RDK X5 的 X5 芯片内置了 MIPI DSI 控制器，内核中已经提供了 mipi_dsi 驱动。我们只需要提供正确的面板驱动配置。

3.2 Device Tree Overlay 机制

Device Tree（设备树）是描述硬件配置的树形数据结构。Overlay 允许在运行时动态修改设备树，而不需要重新编译内核。

设备树编译器：dtc（Device Tree Compiler）

# 编译 dts → dtbo
dtc -I dts -O dtb -o xxx.dtbo xxx.dts

3.3 关键问题：选哪个驱动？

在 RDK X5 的内核中，搜索可用的 DSI 面板驱动：

find /lib/modules -name "*.ko" | xargs grep -l "panel"

发现地平线提供了一系列面板驱动，包括：

jc-050hd134：5寸 720×1280 竖屏
wh-cm480：5寸 800×480 横屏
ili9881c：通用 ILI9881C 驱动

这里的关键发现：wh-cm480 的分辨率正好是 800×480，与 DFRobot 屏幕匹配！

为什么不能用 jc-050hd134？因为它的默认分辨率是 720×1280（竖屏），如果强行使用会导致画面压缩变形。

四、驱动分析：wh-cm480 vs jc-050hd134

4.1 驱动差异对比

驱动名称	分辨率	方向	适用屏幕
jc-050hd134	720×1280	竖屏	5寸 720P 竖屏
wh-cm480	800×480	横屏	5寸 480P 横屏
ili9881c	可配置	可配置	通用 ILI9881C

DFRobot DFR0550-V1 虽然是 ILI9881C 驱动 IC，但其初始化时序与 wh-cm480 兼容。经过实测，wh-cm480 可以正确点亮这块屏幕。

4.2 设备树配置关键点

编写 dsi-dfrobot-v1.dts：

/dts-v1/;
/plugin/;

/ {
    fragment@0 {
        target = <&mipi_dsi0>;
        __overlay__ {
            status = "okay";
            ports {
                port@1 {
                    reg = <1>;
                    mipi_dsi_out: endpoint {
                        remote-endpoint = <&panel_in>;
                    };
                };
            };
            dsi_panel0@0 {
                compatible = "wh-cm480";  // 关键：使用 wh-cm480 驱动
                reg = <0>;
                port {
                    panel_in: endpoint {
                        remote-endpoint = <&mipi_dsi_out>;
                    };
                };
            };
        };
    };
};

核心就是指定 compatible = "wh-cm480"，让内核加载正确的面板驱动。

五、适配方案：dsi_5in 配置详解

5.1 完整配置架构

适配一个 DSI 屏需要处理四个层面：

内核层：Device Tree Overlay（dts/dtbo）
显示层：X11 分辨率配置（xprofile）
背光层：背光控制（rc.local）
触控层：电容触控驱动（ft5406）

5.2 Device Tree Overlay 详解

完整的 dsi-dfrobot-v1.dts：

/dts-v1/;
/plugin/;

/ {
    fragment@0 {
        target = <&mipi_dsi0>;
        __overlay__ {
            status = "okay";
            ports {
                port@1 {
                    reg = <1>;
                    mipi_dsi_out: endpoint {
                        remote-endpoint = <&panel_in>;
                    };
                };
            };
            dsi_panel0@0 {
                compatible = "wh-cm480";
                reg = <0>;
                port {
                    panel_in: endpoint {
                        remote-endpoint = <&mipi_dsi_out>;
                    };
                };
            };
        };
    };
    fragment@1 {
        target = <&i2c3>;
        __overlay__ {
            ft5406@38 {
                compatible = "ft5406";
                reg = <0x38>;
            };
            hbx3_bl@45 {
                compatible = "hobot_bl_controller";
                reg = <0x45>;
            };
        };
    };
};

关键点解析：

fragment@0：配置 MIPI DSI 控制器，绑定 wh-cm480 面板
fragment@1：配置 I2C3 总线上的两个设备：
- ft5406@38：电容触控芯片，I2C 地址 0x38
- hbx3_bl@45：背光控制器，I2C 地址 0x45

5.3 显示比例修正

这里有一个坑：虽然面板物理分辨率是 800×480，但实际像素不是正方形。如果不做修正，画面会横向压缩。

在 ~/.xprofile 中配置：

#!/bin/bash
sleep 1

# 关闭 HDMI
xrandr --output HDMI-1 --off

# 设置 DSI，横向拉伸 1.067 倍修正比例
xrandr --output DSI-1 --mode 800x480 --scale 1.067x1.0 --primary

# 开启背光
echo 200 > /sys/class/backlight/panel_backlight/brightness

比例计算：

原始分辨率：800×480
拉伸系数：1.067
有效显示分辨率：854×480（接近 16:9 标准比例）

5.4 背光控制

RDK X5 的背光通过 PWM 控制，内核提供了 sysfs 接口：

# 背光设备路径
/sys/class/backlight/panel_backlight/

# 设置亮度（0-255）
echo 200 > /sys/class/backlight/panel_backlight/brightness

# 查看当前亮度
cat /sys/class/backlight/panel_backlight/brightness

在 /etc/rc.local 中添加开机自动开启背光：

#!/bin/bash -e
echo 200 > /sys/class/backlight/panel_backlight/brightness
exit 0

六、安装步骤

6.1 一键安装（推荐）

我已经整理好了完整的安装脚本：

cd dsi_5in
sudo ./install.sh
sudo reboot

脚本会自动完成：

编译 dts 为 dtbo
复制到 /boot/overlays/
修改 /boot/config.txt 添加 overlay
配置 /etc/rc.local 背光自启
配置 ~/.xprofile 显示修正

6.2 手动安装

如果想知道每一步在做什么，可以手动安装：

步骤 1：编译并安装设备树

# 编译
dtc -I dts -O dtb -o dsi-dfrobot-v1.dtbo dsi-dfrobot-v1.dts

# 安装
sudo cp dsi-dfrobot-v1.dtbo /boot/overlays/

步骤 2：配置启动 overlay

sudo nano /boot/config.txt

添加：

dtoverlay=dsi-dfrobot-v1

步骤 3：配置背光自启

sudo nano /etc/rc.local

添加（在 exit 0 之前）：

echo 200 > /sys/class/backlight/panel_backlight/brightness

步骤 4：配置 X11 显示

cp xprofile ~/.xprofile
chmod +x ~/.xprofile

步骤 5：重启

sudo reboot

6.3 切换显示

由于 RDK X5 不能同时使用 DSI 和 HDMI，提供了快速切换脚本：

# 切换到 5寸 DSI 屏
./switch-to-dsi.sh

# 切换到 HDMI
./switch-to-hdmi.sh

# 调整背光亮度（0-255）
./set-backlight.sh 200

七、踩坑记录

7.1 白屏无显示

现象：重启后屏幕完全白屏，背光也不亮。

排查：

检查 overlay 是否加载：ls /proc/device-tree/soc/disp_apb/mipi_dsi0@3e060000/
检查驱动是否匹配：dmesg | grep -i "wh-cm480"
检查背光设备是否存在：ls /sys/class/backlight/

解决：发现是背光控制器没有正确初始化，需要在 dts 中添加 hbx3_bl@45 节点。

7.2 显示比例失真

现象：画面横向压缩，圆形变椭圆。

原因：800×480 的物理分辨率像素不是正方形，直接显示会导致比例失真。

解决：使用 xrandr --scale 1.067x1.0 横向拉伸修正。

7.3 触控不工作

现象：显示正常，但触控无响应。

排查：

# 检查 I2C 设备
sudo i2cdetect -y 3

应该看到 0x38（ft5406 触控）和 0x45（背光控制）两个地址。

解决：确保 dts 中正确配置了 ft5406@38 节点，且内核编译了 ft5406 驱动模块。

7.4 与 HDMI 冲突

现象：DSI 有显示，但 HDMI 接上后两个都不亮。

原因：RDK X5 硬件限制，只能同时驱动一个显示输出。

解决：使用 xrandr 切换，或修改 xorg 配置禁用其中一个。

八、效果验证

安装完成后，重启系统，如果一切正常，你应该能看到：

DSI显示效果

测试触控：

# 安装触控测试工具
sudo apt-get install xinput-evtest

# 查看触控设备
xinput list

# 测试触控事件
xinput test <设备ID>

测试背光调节：

# 最暗
sudo ./set-backlight.sh 0

# 最亮
sudo ./set-backlight.sh 255

# 适中
sudo ./set-backlight.sh 200

九、开源分享

完整的适配方案已整理在 GitHub 上 HonestQiao/rdk-x5-dsi-5inch: RDK X5适配树莓派5寸触摸屏：

git clone https://github.com/HonestQiao/rdk-x5-dsi-5inch

包含：

dsi-dfrobot-v1.dts：设备树 overlay 源码
install.sh：一键安装脚本
switch-to-dsi.sh / switch-to-hdmi.sh：显示切换脚本
set-backlight.sh：背光调节脚本

文件清单

dsi_5in/
├── dsi-dfrobot-v1.dts      # 设备树源码
├── dsi-dfrobot-v1.dtbo     # 编译后的二进制
├── install.sh              # 一键安装脚本
├── switch-to-dsi.sh        # 切换到DSI屏
├── switch-to-hdmi.sh       # 切换到HDMI
├── set-backlight.sh        # 背光调节
├── xprofile                # X11配置模板
├── rc.local                # 开机配置模板
└── README.md               # 详细文档

十、总结

通过这次适配，我深入理解了 Linux DRM 子系统和 Device Tree 的工作机制。几个关键收获：

驱动选择很重要：wh-cm480 比 jc-050hd134 更适合 800×480 的屏幕
比例修正不能少：800×480 需要横向拉伸 1.067 倍才能正确显示
背光控制要到位：需要在 dts 中配置 hbx3_bl 节点，否则屏幕不亮
触控驱动要匹配：ft5406 的 I2C 地址是 0x38，确保内核有驱动

DFRobot 这块 5寸屏性价比很高（约 200 元），800×480 分辨率对于嵌入式项目来说足够用，550cd/㎡的亮度在户外也能看清。相比官方支持的屏幕，这块 5寸屏尺寸适中，既不会太小看不清，也不会太大占地方。

下一步计划是接入 MIPI 摄像头，在这块 5寸屏上实现 AI 物体检测，让这块小屏幕发挥更大作用。

希望这篇文章能帮助到其他想在 RDK X5 上用 5寸屏的朋友。

参考链接

DFRobot 5寸屏 Wiki：DFRobot_5寸树莓派DSI屏幕
RDK X5 官方文档：D-Robotics RDK套件 | RDK DOC
地平线开发者社区：https://developer.d-robotics.cc/
RDK X5 MIPI摄像头+AI检测+MIPI屏幕调试踩坑实录 - 电子工程世界: https://bbs.eeworld.com.cn/thread-1344144-1-1.html