【兆易创新GD32VW553开发板试用】编写ILI9341 SPI TFT 驱动

引言

在RTT的官方文档中提供了一个TFT屏幕驱动 ，不过为了学习RTT驱动程序的编写，我还是决定自己写一个试试。这个例子参考了GD32官方提供的裸机示例“GD32VW553H_EVAL_Demo_SuitesProjects9_SPI_LCD”。

本文档记录在 gd32vw553h-eval BSP 工程中添加 ILI9341 SPI TFT LCD 驱动的方法。

开发过程

1. 驱动文件位置

驱动作为板级扩展模块放在：

board/port/ili9341/

包含文件：

board/port/ili9341/SConscript
board/port/ili9341/ili9341.c
board/port/ili9341/ili9341.h

其中：

文件	作用
SConscript	在 BSP_USING_ILI9341 打开时编译驱动
ili9341.c	ILI9341 初始化、SPI 写命令/数据、画点、填充、测试命令
ili9341.h	对外接口和 RGB565 常用颜色定义

2. Kconfig 菜单

在 board/Kconfig 的 Board extended module Drivers 菜单下加入：

menuconfig BSP_USING_ILI9341
    bool "Enable ILI9341 SPI TFT LCD"
    default n
    select BSP_USING_GPIO
    select BSP_USING_SPI
    select BSP_USING_SPI0
    select RT_USING_PIN
    select RT_USING_SPI

启用后可配置：

配置项	默认值	说明
ILI9341_SPI_BUS_NAME	"spi0"	使用的 SPI 总线
ILI9341_SPI_DEVICE_NAME	"lcd0"	注册到 SPI 总线上的设备名
ILI9341_SPI_MAX_HZ	40000000	SPI 最大频率，底层会按 APB 时钟选择不超过该值的分频
ILI9341_WIDTH	240	屏幕宽度
ILI9341_HEIGHT	320	屏幕高度
ILI9341_ROTATION	0	显示方向，取值 0..3
ILI9341_CS_PIN	12	CS 引脚编号
ILI9341_DC_PIN	29	DC 引脚编号
ILI9341_RST_PIN	28	RST 引脚编号
ILI9341_BL_PIN	18	背光引脚编号
ILI9341_AUTO_INIT	y	系统启动时自动初始化 LCD

3. 引脚连接

按照显示屏的原理图：

当前 BSP 的 SPI0 硬件引脚由 libraries/gd32_drivers/drv_spi.c 固定：

信号	GD32VW553H 引脚
SCK	PA11
MISO	PA10
MOSI	PA9

ILI9341 常见接线：

ILI9341 信号	默认 pin number	默认 GPIO
CS	12	PA12
DC	29	PB13
RST	28	PB12
BL	18	PB2
SCK	固定	PA11
MISO	固定	PA10
MOSI	固定	PA9
VCC	–	3.3V
GND	–	GND

pin number 规则：

PA0 = 0,  PA1 = 1,  ... PA15 = 15
PB0 = 16, PB1 = 17, ... PB15 = 31
PC0 = 32, PC1 = 33, ...

如果实际接线不同，需要在 menuconfig 中修改 CS/DC/RST/BL 对应的 pin number。

4. 启用驱动

进入 BSP 目录：

cd /d D:rt-threadbspgd32risc-vgd32vw553h-eval

启动配置：

menuconfig.exe

配置路径：

Hardware Drivers Config
  Board extended module Drivers
    Enable ILI9341 SPI TFT LCD

启用后保存配置。确认 .config 中包含类似内容：

CONFIG_RT_USING_SPI=y
CONFIG_BSP_USING_GPIO=y
CONFIG_BSP_USING_SPI=y
CONFIG_BSP_USING_SPI0=y
CONFIG_BSP_USING_ILI9341=y
CONFIG_ILI9341_SPI_BUS_NAME="spi0"
CONFIG_ILI9341_SPI_DEVICE_NAME="lcd0"

驱动按官方裸机例程使用 SPI Mode 3，并手动控制 CS，避免每个命令/数据字节之间自动释放 CS。

如果工程使用串口控制台，还需要确认 UART0 已启用：

CONFIG_BSP_USING_UART=y
CONFIG_BSP_USING_UART0=y

5. 编译验证

执行：

scons -j%NUMBER_OF_PROCESSORS%

编译时应能看到：

CC buildboardportili9341ili9341.o
LINK rtthread.elf

生成文件：

rtthread.elf
rtthread.bin

6. 运行测试

烧录固件后，在 msh 中执行：

ili9341_test

测试命令会依次填充红、绿、蓝、白、黑。

如果屏幕无显示，优先检查：

1. CS/DC/RST/BL 引脚编号是否和实际接线一致。
2. SPI0 的 SCK/MOSI 是否接到屏幕对应引脚。
3. 屏幕供电是否为 3.3V，GND 是否共地。
4. 背光 BL 是否需要高电平点亮。
5. SPI 频率是否过高，可将 ILI9341_SPI_MAX_HZ 降到 8000000 或 12000000 测试。

7. 驱动接口

当前驱动提供基础绘图接口：

rt_err_t ili9341_init(void);
void ili9341_fill(rt_uint16_t color);
void ili9341_fill_rect(rt_uint16_t x, rt_uint16_t y,
                       rt_uint16_t w, rt_uint16_t h,
                       rt_uint16_t color);
void ili9341_draw_point(rt_uint16_t x, rt_uint16_t y,
                        rt_uint16_t color);

常用颜色定义在 ili9341.h：

ILI9341_COLOR_BLACK
ILI9341_COLOR_WHITE
ILI9341_COLOR_RED
ILI9341_COLOR_GREEN
ILI9341_COLOR_BLUE
ILI9341_COLOR_YELLOW
ILI9341_COLOR_CYAN
ILI9341_COLOR_MAGENTA

总结

后续如果需要接入 LVGL 或 RT-Thread graphic 标准设备，可以在当前 SPI 刷屏接口基础上继续封装 framebuffer 或 rt_device_graphic_ops。