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

手把手教你为香橙派H3适配ST7789屏幕：FBTFT驱动移植保姆级教程（含源码解析）

news 2026/5/13 21:47:48

香橙派H3驱动ST7789屏幕全流程实战：从内核移植到GUI显示

香橙派H3作为一款高性价比的嵌入式开发板，搭配ST7789这类小型TFT屏幕，是创客和嵌入式开发者构建便携式设备的理想组合。但要让这块屏幕正常工作，需要经历内核驱动移植、设备树配置、显示参数调整等一系列技术环节。本文将用最直白的操作步骤，带你完成从零开始的完整适配过程。

1. 硬件准备与环境搭建

在开始软件配置前，确保你已备齐以下硬件组件：

香橙派H3开发板（推荐Orange Pi Zero系列）
ST7789屏幕模块（240x240或240x320分辨率）
杜邦线若干（建议使用彩色线区分功能）
USB转TTL串口模块（如CH340/CP2102用于调试）
5V电源适配器（确保供电稳定）

硬件连接示意图如下：

屏幕引脚	香橙派GPIO	功能说明
VCC	3.3V	电源正极
GND	GND	电源地
SCL	PA12	SPI时钟线
SDA	PA13	SPI数据线
RES	PA6	复位信号
DC	PA1	数据/命令选择线
CS	GND	片选（可接地）

提示：不同型号ST7789的背光控制方式可能不同，部分模块需要单独连接PWM引脚调节亮度

安装基础开发工具链：

sudo apt update sudo apt install build-essential git bison flex libssl-dev

获取香橙派官方内核源码：

git clone --depth=1 https://github.com/orangepi-xunlong/linux-orangepi cd linux-orangepi

2. 内核驱动移植与修改

ST7789属于FBTFT驱动框架支持的设备，但香橙派默认内核可能未包含该型号配置。我们需要手动添加设备信息。

2.1 修改fbtft_device.c

定位到驱动源文件：

vim drivers/staging/fbtft/fbtft_device.c

在static struct fbtft_device_display displays[]数组中添加：

{ .name = "st7789s_h3", .spi = &(struct fbtft_spi_display) { .mode = SPI_MODE_0, .bits_per_word = 8, .chip_select = 0, .max_speed_hz = 32000000 }, .gpios = (const struct fbtft_gpio []) { { "dc", 1 }, // PA1 { "reset", 6 }, // PA6 {}, }, .display = { .width = 240, .height = 240, .regwidth = 8, .buswidth = 8, .backlight = 1, .fps = 60, }, .bgr = true, .fbtftops = { .init_display = st7789v_init_display, .set_addr_win = st7789v_set_addr_win, }, },

关键参数解析：

max_speed_hz：SPI通信速率，ST7789最高支持32MHz
bgr = true：设置像素格式为BGR顺序
fps：帧率设置，过高可能导致显示异常

2.2 编写ST7789驱动文件

新建st7789s.c驱动文件：

vim drivers/staging/fbtft/st7789s.c

核心初始化函数示例：

static int init_display(struct fbtft_par *par) { /* 硬件复位序列 */ par->fbtftops.reset(par); /* 发送初始化命令序列 */ write_reg(par, 0x11); // 退出睡眠模式 mdelay(120); write_reg(par, 0x3A, 0x05); // 设置16位像素格式 write_reg(par, 0xB2, 0x0C, 0x0C, 0x00, 0x33, 0x33); // 门控控制 write_reg(par, 0xB7, 0x35); // 电压控制 write_reg(par, 0x21); // 显示反转模式 /* 设置显示区域 */ write_reg(par, 0x36, 0x00); // 内存访问控制 write_reg(par, 0x2A, 0x00, 0x00, 0x00, 0xEF); // 列地址设置 write_reg(par, 0x2B, 0x00, 0x00, 0x00, 0xEF); // 行地址设置 write_reg(par, 0x29); // 开启显示 return 0; }

寄存器配置要点：

0x36：控制显示方向（可修改0x00/0x60/0xC0/0xA0等值旋转屏幕）
0x2A/0x2B：设置实际显示区域尺寸
0x20/0x21：控制颜色反转显示

3. 内核编译与驱动加载

3.1 配置内核选项

启用FBTFT相关配置：

make menuconfig

导航至：

Device Drivers -> Staging drivers -> Support for small TFT LCD display modules -> <M> FB driver for the ST7789V LCD controller <M> FBTFT device support [*] FBTFT debugging support [*] FBTFT GPIO support

保存配置后编译内核模块：

make -j4 modules sudo make modules_install

3.2 加载驱动测试

手动加载驱动模块：

sudo modprobe fbtft_device name=st7789s_h3 rotate=90 gpios=dc:1,reset:6 speed=32000000

验证设备节点：

ls /dev/fb*

应该能看到新增的/dev/fb1设备。可以通过以下命令测试显示：

sudo apt install fbi sudo fbi -d /dev/fb1 -T 1 -noverbose -a test.png

4. 系统集成与优化配置

4.1 设备树配置（可选）

对于永久性配置，建议修改设备树：

vim arch/arm/boot/dts/sun8i-h3-orangepi-zero.dts

添加SPI节点：

&spi0 { status = "okay"; st7789v@0 { compatible = "sitronix,st7789v"; reg = <0>; spi-max-frequency = <32000000>; rotate = <90>; fps = <60>; buswidth = <8>; dc-gpios = <&pio 0 1 GPIO_ACTIVE_HIGH>; // PA1 reset-gpios = <&pio 0 6 GPIO_ACTIVE_LOW>; // PA6 debug = <0>; }; };

4.2 显示性能调优

修改帧缓冲控制参数：

sudo sh -c "echo 16 > /sys/class/graphics/fb1/bits_per_pixel" sudo sh -c "echo 1 > /sys/class/graphics/fb1/blank" sudo sh -c "echo 0 > /sys/class/graphics/fb1/blank"

4.3 开机自动加载

创建systemd服务：

sudo vim /etc/systemd/system/st7789.service

添加内容：

[Unit] Description=ST7789 Display Service [Service] ExecStart=/usr/sbin/modprobe fbtft_device name=st7789s_h3 rotate=90 gpios=dc:1,reset:6 speed=32000000 [Install] WantedBy=multi-user.target

启用服务：