给嵌入式新手的ST7789驱动避坑指南：从SPI模式到RGB565显示的完整配置流程
给嵌入式新手的ST7789驱动避坑指南：从SPI模式到RGB565显示的完整配置流程
第一次接触ST7789液晶驱动芯片时，面对厚厚的数据手册和复杂的时序图，很多嵌入式新手都会感到无从下手。本文将带你一步步拆解ST7789的驱动过程，从SPI模式配置到RGB565显示实现，避开那些让初学者头疼的"坑"。
1. 理解ST7789的基本工作原理
ST7789是一款常见的TFT液晶驱动芯片，支持262K色显示，最大分辨率可达240x320。它通过SPI接口与主控芯片通信，采用RGB565色彩格式（16位/像素）进行数据传输。
关键特性：
- 支持3线/4线SPI接口
- 内置显存（GRAM）
- 可编程显示方向
- 低功耗模式
提示：在开始编码前，建议先通读数据手册的"Features"章节，对芯片能力有个整体认识。
2. SPI接口配置：模式与时序
ST7789通常使用4线SPI接口（SCK, MOSI, DC, CS），其中DC线用于区分命令和数据。这是第一个容易出错的地方——SPI模式必须与芯片要求严格匹配。
根据数据手册，ST7789的SPI时序要求：
- CPOL = 0（空闲时SCK为低电平）
- CPHA = 0（数据在第一个边沿采样）
在STM32 HAL库中的配置示例：
hspi1.Instance = SPI1; hspi1.Init.Mode = SPI_MODE_MASTER; hspi1.Init.Direction = SPI_DIRECTION_2LINES; hspi1.Init.DataSize = SPI_DATASIZE_8BIT; hspi1.Init.CLKPolarity = SPI_POLARITY_LOW; // CPOL=0 hspi1.Init.CLKPhase = SPI_PHASE_1EDGE; // CPHA=0 hspi1.Init.NSS = SPI_NSS_SOFT; hspi1.Init.BaudRatePrescaler = SPI_BAUDRATEPRESCALER_4; hspi1.Init.FirstBit = SPI_FIRSTBIT_MSB; hspi1.Init.TIMode = SPI_TIMODE_DISABLE; hspi1.Init.CRCCalculation = SPI_CRCCALCULATION_DISABLE; hspi1.Init.CRCPolynomial = 10;常见问题排查：
- 屏幕无反应：检查SPI时钟极性/相位设置
- 显示乱码：确认数据位序（MSB/LSB）
- 通信失败：验证GPIO引脚配置是否正确
3. 关键寄存器配置详解
ST7789通过一系列命令寄存器控制显示行为，以下是几个最关键的配置项：
3.1 显示方向控制（0x36）
这个寄存器控制屏幕的旋转和镜像：
#define MADCTL_MY 0x80 // 行地址顺序 #define MADCTL_MX 0x40 // 列地址顺序 #define MADCTL_MV 0x20 // 行列交换 #define MADCTL_ML 0x10 // 垂直刷新顺序 #define MADCTL_RGB 0x00 // RGB顺序 #define MADCTL_BGR 0x08 // BGR顺序 // 正常方向，RGB格式 uint8_t madctl = MADCTL_RGB; LCD_WriteCmd(0x36); LCD_WriteData(&madctl, 1);3.2 像素格式设置（0x3A）
ST7789支持多种像素格式，对于RGB565显示：
// 设置16位/像素，RGB565格式 uint8_t pixel_format = 0x55; // 0x55对应RGB565 LCD_WriteCmd(0x3A); LCD_WriteData(&pixel_format, 1);3.3 显示开关控制
芯片上电后需要依次发送：
- 退出睡眠模式（0x11）
- 打开显示（0x29）
// 退出睡眠模式 LCD_WriteCmd(0x11); HAL_Delay(120); // 需要等待120ms // 打开显示 LCD_WriteCmd(0x29);4. 显存操作与图像显示
ST7789内置了一块GRAM（图形内存），我们需要通过特定命令来操作它。
4.1 设置显示窗口
在写入像素数据前，必须先定义写入区域：
void LCD_SetWindow(uint16_t x0, uint16_t y0, uint16_t x1, uint16_t y1) { LCD_WriteCmd(0x2A); // 列地址设置 LCD_WriteData((uint8_t*)&x0, 2); LCD_WriteData((uint8_t*)&x1, 2); LCD_WriteCmd(0x2B); // 行地址设置 LCD_WriteData((uint8_t*)&y0, 2); LCD_WriteData((uint8_t*)&y1, 2); LCD_WriteCmd(0x2C); // 内存写入 }4.2 填充颜色
清屏函数示例：
void LCD_Fill(uint16_t color) { LCD_SetWindow(0, 0, LCD_WIDTH-1, LCD_HEIGHT-1); uint32_t total_pixels = LCD_WIDTH * LCD_HEIGHT; for(uint32_t i=0; i<total_pixels; i++) { LCD_WriteData((uint8_t*)&color, 2); } }4.3 显示图像
显示一张240x320的RGB565图像：
void LCD_ShowImage(uint16_t x, uint16_t y, uint16_t width, uint16_t height, const uint8_t *img) { LCD_SetWindow(x, y, x+width-1, y+height-1); LCD_WriteData(img, width*height*2); // 每个像素2字节 }5. 常见问题与调试技巧
5.1 显示颜色不正确
可能原因：
- 像素格式设置错误（检查0x3A命令）
- 颜色顺序错误（RGB/BGR配置）
- 数据传输位序错误（MSB/LSB）
5.2 显示偏移或错位
解决方法：
- 检查显示窗口设置是否正确
- 确认行列地址参数顺序
- 调整偏移量（某些屏幕需要）
5.3 SPI通信失败
调试步骤：
- 用逻辑分析仪抓取SPI波形
- 检查时钟频率是否过高
- 验证CS和DC信号时序
6. 性能优化建议
- 使用DMA传输：大幅提高图像刷新速度
HAL_SPI_Transmit_DMA(&hspi1, buffer, length);双缓冲机制：减少屏幕闪烁
局部刷新：只更新变化区域
合理设置SPI时钟：平衡速度与稳定性
在STM32F4上，使用硬件SPI+DMA，刷新全屏（240x320）可以做到约30fps的性能。如果发现显示有撕裂现象，可以考虑在垂直消隐期间更新显存。
7. 进阶功能探索
掌握了基础显示后，可以尝试ST7789的更多功能：
- 局部刷新：通过设置小窗口提高刷新效率
- 睡眠模式：降低功耗
- gamma校正：改善显示效果
- 撕裂效应控制：用于视频同步
例如，实现垂直滚动：
void LCD_SetScroll(uint16_t top, uint16_t scroll_lines, uint16_t bottom) { LCD_WriteCmd(0x33); LCD_WriteData((uint8_t*)&top, 2); LCD_WriteData((uint8_t*)&scroll_lines, 2); LCD_WriteData((uint8_t*)&bottom, 2); }调试ST7789时，逻辑分析仪是最得力的工具。通过观察实际的SPI波形，可以快速定位是配置问题还是时序问题。另外，建议将常用操作封装成函数库，方便后续项目复用。