当前位置：首页 > news >正文

告别fbtft！在香橙派Zero上为1.3寸ST7789V屏幕编译TinyDRM驱动（附完整设备树配置）

news 2026/4/23 12:14:33

香橙派Zero的ST7789V屏幕驱动升级指南：从fbtft迁移到TinyDRM

在嵌入式Linux开发中，TFT屏幕驱动一直是个令人头疼的问题。特别是当你拿到一块1.3寸的ST7789V屏幕，按照网上教程使用fbtft驱动时，却发现新内核不再支持——这种经历我太熟悉了。去年我在一个智能家居项目中使用香橙派Zero时，就遇到了完全相同的困境。经过几天的折腾和源码研究，终于成功迁移到了更现代的TinyDRM驱动，不仅解决了兼容性问题，还获得了DRM框架带来的诸多优势。

1. 为什么需要从fbtft迁移到TinyDRM

fbtft驱动曾经是嵌入式Linux连接小型TFT屏幕的标配解决方案，但随着内核版本的更新，它的局限性越来越明显。我在5.15内核上尝试编译fbtft时，遇到了无数兼容性问题，最终发现原作者已经转向开发更现代的TinyDRM驱动。

TinyDRM相比fbtft的核心优势：

按需刷新：只在用户空间请求时才刷新屏幕，显著降低功耗
局部更新：可以只刷新屏幕的部分区域，而非强制全屏刷新
动态电源管理：仅在屏幕使用时才供电，而非一直保持开启状态
高级图形特性：支持双缓冲、页面翻转等避免图像撕裂的技术
GPU加速：可与现代图形渲染管线集成

注意：TinyDRM只支持符合MIPI-DCS标准命令集的显示控制器。验证你的ST7789V是否兼容，可以检查0x2A、0x2B、0x2C命令是否分别对应行地址设置、列地址设置和显存写入操作。

2. 开发环境准备与驱动编译

我的测试平台是香橙派Zero运行Armbian系统（内核5.15.y）。以下是完整的配置流程：

2.1 安装必要工具链

sudo apt update sudo apt install linux-headers-current-sunxi build-essential git make

如果找不到匹配的内核头文件，你可能需要从源码编译（后文会介绍）。但建议先尝试官方仓库的版本，因为从源码编译会耗费大量时间。

2.2 获取并编译TinyDRM驱动

创建一个工作目录并准备驱动源码：

mkdir ~/st7789v-driver && cd ~/st7789v-driver wget https://example.com/st7789v.c # 替换为实际驱动源码URL

接着创建Makefile：

obj-m += st7789v.o all: make -C /lib/modules/$(shell uname -r)/build M=$(PWD) modules clean: make -C /lib/modules/$(shell uname -r)/build M=$(PWD) clean

编译驱动模块：

make -j$(nproc)

成功编译后，你会得到st7789v.ko文件。将其安装到系统模块目录：

sudo cp st7789v.ko /lib/modules/$(uname -r)/kernel/drivers/gpu/drm/tiny/ sudo depmod -a

3. 设备树配置与硬件连接

正确的设备树配置是驱动工作的关键。以下是我的香橙派Zero配置经验。

3.1 设备树覆盖文件配置

创建st7789v.dts文件：

/dts-v1/; /plugin/; / { compatible = "allwinner,sun8i-h3"; fragment@0 { target = <&spi1>; __overlay__ { status = "okay"; spidev@0 { status = "disabled"; }; spidev@1 { status = "disabled"; }; }; }; fragment@1 { target = <&spi1>; __overlay__ { #address-cells = <1>; #size-cells = <0>; display@0 { compatible = "sitronix,st7789v_240x240"; reg = <0>; spi-max-frequency = <40000000>; dc-gpios = <&pio 0 19 GPIO_ACTIVE_HIGH>; reset-gpios = <&pio 0 18 GPIO_ACTIVE_LOW>; rotation = <0>; }; }; }; };

应用设备树覆盖：

sudo armbian-add-overlay st7789v.dts

3.2 硬件连接参考

ST7789V引脚	香橙派Zero引脚	备注
VCC	3.3V	电源正极
GND	GND	电源地
SCL	PA14 (SPI1_CLK)	SPI时钟线
SDA	PA15 (SPI1_MOSI)	SPI数据线
RES	PG6	复位信号
DC	PG7	数据/命令选择线
CS	PA13或GND	片选，可接地常使能

4. 驱动调试与常见问题解决

在实际部署过程中，我遇到了几个典型问题，以下是解决方案：

4.1 屏幕无显示或花屏

可能原因：

SPI时钟频率过高
初始化序列不正确
电源不稳定

解决方案：

尝试降低spi-max-frequency（如改为20000000）
检查驱动中的初始化序列是否匹配你的屏幕型号
确保电源供应充足，必要时增加电容滤波

4.2 旋转方向不正确

修改设备树中的rotation参数：

0：默认方向
90：顺时针旋转90度
180：旋转180度
270：顺时针旋转270度

4.3 性能优化技巧

# 提高SPI总线优先级 sudo nice -n -20 ./your_display_app

在驱动源码中，可以调整以下参数提升性能：

增加spi-max-frequency
优化屏幕刷新区域计算
使用双缓冲技术

5. TinyDRM驱动的高级应用

掌握了基础配置后，我们可以探索TinyDRM更强大的功能。

5.1 与Qt/Wayland集成

现代图形界面框架可以直接利用DRM接口。以Qt为例，启动参数中添加：

export QT_QPA_PLATFORM=drm ./your_qt_app -platform drm

5.2 多屏幕管理

当系统连接多个屏幕时，可以通过DRM_DEVICE环境变量指定设备：

export DRM_DEVICE=/dev/dri/card1 ./your_app

5.3 自定义色彩模式

在驱动源码中，可以修改像素格式：

mipi_dbi_command(dbi, MIPI_DCS_SET_PIXEL_FORMAT, 0x55); // 16-bit RGB565

可选格式包括：

0x55：RGB565
0x66：RGB666
0x77：RGB888

6. 内核源码编译方案（备用）

虽然不推荐，但当预编译模块不可用时，你需要从内核源码编译：

git clone --depth=1 https://github.com/armbian/linux cd linux make ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- sunxi_defconfig make ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- menuconfig

在配置界面中，导航到：

Device Drivers → Graphics support → DRM support for Sitronix ST7789V display panels

选择M编译为模块。

编译并安装模块：

make ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- modules_prepare make ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- M=drivers/gpu/drm/tiny modules sudo cp drivers/gpu/drm/tiny/st7789v.ko /lib/modules/$(uname -r)/kernel/drivers/gpu/drm/tiny/ sudo depmod -a