[原创] 【RDK X5 ROS机器人AI开发板】RDK X5 适配 DFRobot 5寸 DSI 触摸屏实战记录

HonestQiao 2026-3-14 12:48 楼主

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

## 前言：从 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：
![开发板接口说明](/data/attachment/forum/202603/14/124642vnry8dildgjmglpl.jpg.thumb.jpg?rand=4516.24673842666)

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

后来，直接使用树莓派5兼容的DSI屏幕连接线连接到接口14，就可以把 **DFRobot DFR0550-V1** 5寸 DSI 触摸屏 直接连接到 RDK X5开发板上：
![硬件连接图](/data/attachment/forum/202603/14/123850a5v7lws99lfvsw26.jpg.thumb.jpg?rand=887.4573084306559)

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

---

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

### 2.1 初次尝试

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

```bash
# 切换 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：

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

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

### 2.2 排查过程

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

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

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

```bash
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）

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

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

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

```bash
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-cm480vsjc-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
/dts-v1/;
/plugin/;

/ {
  fragment@0 {
  target = <&mipi_dsi0>;
  __overlay__ {
    status = "okay";
    ports {
      port<a href="https://m.eeworld.com.cn/bbs/home.php?mod=space&uid=490" target="_blank">@1</a> {
      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 屏需要处理四个层面：

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

### 5.2 Device Tree Overlay 详解

完整的 `dsi-dfrobot-v1.dts`：

```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` 中配置：

```bash
#!/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 接口：

```bash
# 背光设备路径
/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` 中添加开机自动开启背光：

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

---

## 六、安装步骤

### 6.1 一键安装（推荐）

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

```bash
cd dsi_5in
sudo ./install.sh
sudo reboot
```

脚本会自动完成：
1. 编译 dts 为 dtbo
2. 复制到 `/boot/overlays/`
3. 修改 `/boot/config.txt` 添加 overlay
4. 配置 `/etc/rc.local` 背光自启
5. 配置 `~/.xprofile` 显示修正

### 6.2 手动安装

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

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

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

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

**步骤 2：配置启动 overlay**

```bash
sudo nano /boot/config.txt
```

添加：
```
dtoverlay=dsi-dfrobot-v1
```

**步骤 3：配置背光自启**

```bash
sudo nano /etc/rc.local
```

添加（在 `exit 0` 之前）：
```bash
echo 200 > /sys/class/backlight/panel_backlight/brightness
```

**步骤 4：配置 X11 显示**

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

**步骤 5：重启**

```bash
sudo reboot
```

### 6.3 切换显示

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

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

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

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

---

## 七、踩坑记录

### 7.1 白屏无显示

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

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

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

### 7.2 显示比例失真

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

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

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

### 7.3 触控不工作

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

**排查**：
```bash
# 检查 I2C 设备
sudo i2cdetect -y 3
```

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

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

### 7.4 与 HDMI 冲突

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

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

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

---

## 八、效果验证

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

![DSI显示效果](/data/attachment/forum/202603/14/124137qlaoz38a6u3unoh3.jpg.thumb.jpg?rand=8757.943346913728)

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

# 查看触控设备
xinput list

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

测试背光调节：
```bash
# 最暗
sudo ./set-backlight.sh 0

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

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

---

## 九、开源分享

完整的适配方案已整理在 GitHub 上 [HonestQiao/rdk-x5-dsi-5inch: RDK X5适配树莓派5寸触摸屏](https://github.com/HonestQiao/rdk-x5-dsi-5inch)：

```bash
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 的工作机制。几个关键收获：

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

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

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

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

---

## 参考链接

- DFRobot 5寸屏 Wiki：https://wiki.dfrobot.com.cn/_SKU_DFR0550-V2_5_inch_DSI_Touchsrceen_with_Optical_Bonding_for_Raspberry_Pi
- RDK X5 官方文档：https://developer.d-robotics.cc/rdk_doc
- 地平线开发者社区：https://developer.d-robotics.cc/