1. 项目概述Adafruit ST7735 和 ST7789 库是一个面向嵌入式平台尤其是 Arduino 生态的轻量级图形驱动库专为基于 Sitronix ST7735、ST7789 及 ST7796S 显示控制器的彩色 TFT 液晶模组设计。该库并非仅适配单一型号而是通过统一抽象层兼容多款 Adafruit 官方出品的 SPI 接口 TFT 显示模块包括Adafruit 1.8 TFT Breakout带 microSD 卡槽——产品编号 358Adafruit 1.8 TFT Shield ——产品编号 802Adafruit 1.44 TFT Breakout ——产品编号 2088Adafruit 原装 1.8 TFT 面板无 PCB——产品编号 618这些模组均采用 4 线或 5 线 SPISerial Peripheral Interface总线进行通信硬件资源占用极低仅需 4 根信号线即可完成基本显示控制SCLK、MOSI、CS、DC复位引脚RST为可选配置。这种精简接口设计使其特别适用于资源受限的 MCU 平台如 ATmega328P、ESP32、nRF52840、RP2040 等在智能穿戴设备、传感器节点、教学实验板及小型 HMI 系统中具有广泛适用性。该库由 Limor FriedLadyada主导开发由 Adafruit Industries 开源维护采用 MIT 许可证发布。其核心价值不仅在于功能实现更在于工程实践层面的成熟度所有驱动逻辑均经过量产硬件验证配套完整 wiring diagram 与教程并深度集成于 Arduino IDE 生态。开发者无需深入研究 ST77xx 系列寄存器手册即可快速实现像素级绘图、文字渲染、图像显示等操作。值得注意的是本库不直接提供底层图形原语实现而是作为显示控制器驱动层Display Driver Layer与上层图形抽象库Adafruit_GFX构成标准分层架构Adafruit_GFX负责drawPixel()、drawLine()、fillRect()、drawString()等通用绘图 API 的算法实现与坐标映射Adafruit_ST7735/ST7789则负责将 GFX 层发出的像素数据流通过 SPI 总线准确写入 ST77xx 控制器的GRAMGraphics RAM并管理初始化序列、睡眠/唤醒、方向旋转、Gamma 校准等硬件相关状态。这种职责分离设计极大提升了代码复用性——同一份Adafruit_GFX应用代码只需更换底层驱动实例如Adafruit_ST7735→Adafruit_ILI9341即可无缝迁移至其他 TFT 平台。2. 硬件接口与电气特性2.1 SPI 通信协议栈ST7735/ST7789 控制器严格遵循 Motorola SPI 模式 0CPOL0, CPHA0空闲时钟为低电平CPOL0数据在 SCLK 上升沿采样CPHA0最高支持 15 MHz SPI 时钟频率ST7789 支持更高但受 MCU GPIO 翻转能力与走线阻抗限制实际推荐 ≤10 MHz。SPI 信号定义如下表所示引脚名功能说明电气要求备注SCLK串行时钟输入3.3V LVTTL主机输出控制数据同步节奏MOSI主机输出 / 从机输入3.3V LVTTL所有命令与数据均由此线单向传输CS片选信号Chip Select低电平有效必须为每个显示模组独占不可与其他 SPI 设备共用DC数据/命令选择Data/Command3.3V LVTTL关键控制引脚DCHIGH 表示 MOSI 数据为显存像素值DCLOW 表示 MOSI 数据为寄存器地址或命令参数RST硬件复位Reset低电平有效可软件模拟通过reset()函数拉低再释放但硬件直连更可靠尤其在冷启动时⚠️关键设计警示DC 引脚是区分“发送命令”与“发送显存数据”的唯一机制。若 DC 电平错误将导致控制器误将像素数据解析为非法寄存器写入引发屏幕花屏、黑屏或初始化失败。在 PCB 布局中DC 线应与 SCLK/MOSI 同层等长走线避免信号偏移。2.2 电源与电平匹配VCC典型工作电压为 3.3V绝对最大值 3.6V严禁接入 5V多数 Adafruit 模块内置 LDO但输入仍需稳定 3.3V。LED / LED-背光供电引脚。LED 接 3.3V 或 PWM 可调压源用于亮度控制LED- 接地。部分模组如 1.44背光电流达 80mA需确保电源能持续输出 ≥100mA。电平转换若 MCU 为 5V 系统如经典 Arduino Uno ATmega328P必须使用双向电平转换器如 TXB0104处理 SCLK/MOSI/CS/DC/RST 信号。直接连接将永久损坏 TFT 模组的 I/O 单元。2.3 典型连接拓扑以 Arduino Uno 为例Arduino Uno ST7735/ST7789 Module --------------------------------------- D13 (SCK) → SCLK D11 (MOSI) → MOSI D10 → CS (Chip Select) D9 → DC (Data/Command) D8 → RST (Reset, optional but recommended) GND → GND 3.3V → VCC 3.3V → LED (or PWM pin via current-limiting resistor) GND → LED-✅工程实践建议在setup()中执行pinMode(RST, OUTPUT); digitalWrite(RST, HIGH); delay(100); digitalWrite(RST, LOW); delay(50); digitalWrite(RST, HIGH); delay(150);可确保控制器完成 Power-on ResetPOR时序比依赖内部上电复位更可靠。3. 软件架构与核心 API 解析3.1 类继承关系与初始化流程库主体由两个核心类构成均继承自Adafruit_GFX抽象基类class Adafruit_ST7735 : public Adafruit_GFX { ... }; class Adafruit_ST7789 : public Adafruit_GFX { ... };二者共享同一套初始化框架但针对不同控制器的寄存器配置序列Initialization Sequence独立实现。初始化函数签名如下// ST7735 初始化含硬件复位 void Adafruit_ST7735::initR(uint8_t options); // ST7789 初始化支持不同尺寸变体 void Adafruit_ST7789::init(uint8_t options);options参数为位掩码用于指定物理屏参数选项宏含义典型应用INITR_GREENTAB使用绿色系 Gamma 表适用于 Adafruit 1.8 green tab产品编号 358/618INITR_REDTAB使用红色系 Gamma 表适用于 Adafruit 1.44 red tab产品编号 2088INITR_BLACKTAB使用黑色系 Gamma 表适用于 Adafruit 1.8 black tab产品编号 802源码级洞察initR()内部按精确时序调用writecommand()与writedata()函数依次写入 ST7735 的 20 个关键寄存器如SWRESET,SLPOUT,COLMOD,MADCTL,INVOFF,DISPON。例如MADCTLMemory Access Control寄存器决定屏幕坐标映射方式0x00正常0x60横屏COLMODColor Mode设定为0x0516-bit RGB 5-6-5。3.2 关键 API 函数详解3.2.1 显存控制类函数原型功能说明工程要点void setRotation(uint8_t r)设置屏幕旋转角度0~3对应 0°/90°/180°/270°修改MADCTL寄存器并重新计算WIDTH/HEIGHT调用后需重绘全部内容void invertDisplay(bool i)开启/关闭屏幕色彩反转写入INVON/INVOFF命令常用于提升 OLED 类比视觉效果void setAddrWindow(uint16_t x0, uint16_t y0, uint16_t x1, uint16_t y1)设置GRAM写入窗口裁剪区域性能关键限定后续pushColors()作用范围避免全屏刷写x1/y1 为包含边界void pushColors(uint16_t *data, uint16_t len, bool first)高速批量写入 RGB565 像素数据firsttrue时自动调用setAddrWindow(0,0,_width-1,_height-1)len为像素数非字节数3.2.2 图形绘制类继承自 Adafruit_GFX函数原型功能说明底层行为void drawPixel(int16_t x, int16_t y, uint16_t color)绘制单点调用setAddrWindow(x,y,x,y)pushColors(color,1,true)void fillScreen(uint16_t color)全屏填充调用setAddrWindow(0,0,_width-1,_height-1)pushColors()循环写入void drawBitmap(int16_t x, int16_t y, const uint8_t *bitmap, int16_t w, int16_t h, uint16_t color)绘制单色位图逐行解码 bitmap对每个 bit 调用drawPixel()性能优化提示pushColors()是吞吐量瓶颈。在 STM32 HAL 平台可替换为HAL_SPI_Transmit()DMA 模式在 ESP32启用spi_device_transmit()的双缓冲机制可提升 30% 帧率。3.3 内存模型与帧缓冲策略ST77xx 系列控制器采用GRAMGraphics RAM架构控制器内部集成一块与屏幕分辨率等大的显存如 1.8 128×160 屏需 128×160×2 40KB RAM。Adafruit_ST7735/ST7789库不维护本地帧缓冲Frame Buffer所有绘图操作均实时通过 SPI 写入 GRAM。此设计优势在于零内存开销对 RAM 2KB 的 MCU 至关重要显存状态与屏幕显示严格一致无缓存一致性问题。劣势在于频繁小区域更新如刷新单个字符效率低下每次需重置窗口传输无法实现离屏渲染Off-screen rendering或双缓冲Double Buffering。工程变通方案若需双缓冲在外部 SRAM如 IS61LV25616AL或 MCU 大容量 RAM如 ESP32 PSRAM中分配uint16_t fb[WIDTH*HEIGHT]用memcpy()pushColors()实现整帧推送。示例// 假设 fb 为已渲染完毕的帧缓冲 tft.setAddrWindow(0, 0, tft.width()-1, tft.height()-1); tft.pushColors(fb, tft.width() * tft.height(), true);4. 典型应用场景与代码实现4.1 基础初始化与文本显示Arduino#include Adafruit_GFX.h #include Adafruit_ST7735.h #include SPI.h // 引脚定义适配 Adafruit 1.8 Breakout #define TFT_CS 10 #define TFT_DC 9 #define TFT_RST 8 Adafruit_ST7735 tft Adafruit_ST7735(TFT_CS, TFT_DC, TFT_RST); void setup() { Serial.begin(115200); tft.initR(INITR_GREENTAB); // 初始化 ST7735green tab tft.fillScreen(ST77XX_BLACK); tft.setTextColor(ST77XX_WHITE); tft.setTextSize(2); tft.setCursor(0, 0); tft.println(Adafruit ST7735); tft.println(Hello World!); } void loop() { // 无操作静态显示 }4.2 实时传感器数据显示FreeRTOS 集成在 ESP32 上结合 FreeRTOS实现传感器数据刷新与 UI 渲染分离#include freertos/FreeRTOS.h #include freertos/task.h #include driver/gpio.h #include esp_adc/adc_oneshot.h QueueHandle_t display_queue; // 任务读取 ADC 值并发送到显示队列 void sensor_task(void *pvParameters) { adc_oneshot_unit_handle_t adc_handle; adc_oneshot_unit_init_cfg_t init_config { .unit_id ADC_UNIT_1 }; adc_oneshot_unit_new_handle(init_config, adc_handle); adc_oneshot_chan_cfg_t channel_config { .atten ADC_BITWIDTH_12, .bit_width ADC_BITWIDTH_12 }; adc_oneshot_chan_handle_t channel_handle; adc_oneshot_channel_init(adc_handle, ADC_CHANNEL_0, channel_handle); while(1) { int raw; adc_oneshot_channel_read(channel_handle, raw, portMAX_DELAY); float voltage (raw * 3.3f) / 4095.0f; xQueueSend(display_queue, voltage, portMAX_DELAY); vTaskDelay(500 / portTICK_PERIOD_MS); } } // 任务从队列获取数据并刷新屏幕 void display_task(void *pvParameters) { float voltage; tft.setRotation(2); // 横屏 tft.fillScreen(ST77XX_BLACK); while(1) { if(xQueueReceive(display_queue, voltage, portMAX_DELAY) pdTRUE) { tft.fillRect(0, 0, 120, 20, ST77XX_BLACK); // 清除旧值区域 tft.setCursor(0, 0); tft.setTextColor(ST77XX_GREEN); tft.setTextSize(2); tft.printf(V: %.2fV, voltage); } } } void app_main() { display_queue xQueueCreate(5, sizeof(float)); xTaskCreate(sensor_task, sensor, 2048, NULL, 5, NULL); xTaskCreate(display_task, display, 4096, NULL, 5, NULL); }4.3 图像资源嵌入与显示 PROGMEM 优化将 128×128 像素的 RGB565 图片转换为 C 数组存储于 Flash# 使用 ImageMagick 转换 PNG 为 RGB565 C 数组 convert image.png -depth 8 -resize 128x128\! -colorspace sRGB \ -separate -combine -depth 16 -normalize -colorspace RGB \ -format 0x%04x, txt:- | tr \n | sed s/ $// image.hC 代码中调用#include image.h // 包含 const uint16_t image_data[16384] void show_logo() { tft.setAddrWindow(0, 0, 127, 127); tft.pushColors((uint16_t*)image_data, 128*128, true); }✅Flash 存储优势PROGMEM关键字Arduino或const __attribute__((section(.flash_rodata)))ESP-IDF确保图像数据驻留 Flash不占用宝贵 RAM。5. 常见问题诊断与调试技巧5.1 屏幕无反应/白屏检查 RST 时序用示波器观测 RST 引脚确认是否执行了 ≥10ms 低电平脉冲验证 SPI 通信用逻辑分析仪捕获 SCLK/MOSI确认SWRESET0x01命令被正确发送确认 DC 电平在发送0x01时DC 必须为 LOW在发送像素数据时DC 必须为 HIGH。5.2 花屏/错位检查 MADCTL 设置setRotation()是否匹配物理屏方向尝试tft.setRotation(0)强制归零验证 COLOR MODECOLMOD寄存器是否设为0x0516-bit若误设为0x0312-bit会导致每像素少传 2bit排查 CS 释放时机确保每次 SPI 事务结束前digitalWrite(CS, HIGH)避免多条命令粘连。5.3 刷新闪烁禁用 DISPON/DISPOFF 切换避免在fillScreen()前后插入displaysOff()/displayOn()使用fillScreen()替代fillRect()前者直接写入 GRAM 全域后者可能触发多次窗口设置。6. 与主流 MCU 平台的适配要点6.1 STM32HAL 库替换SPI.transfer()为HAL_SPI_Transmit()启用SPI_MODE_MASTER与SPI_PHASE_1EDGE在Adafruit_ST7735.cpp中重载spiwrite()函数使用HAL_SPI_Transmit_DMA()实现零拷贝注意CS引脚需配置为GPIO_MODE_OUTPUT_PP并在begin()中初始化为 HIGH。6.2 ESP32IDF使用spi_bus_add_device()注册 SPI 设备spi_device_transmit()发送命令启用SPI_DEVICE_HALFDUPLEX模式ST77xx 为单工DC引脚可通过spi_device_interface_config_t::command_bits 8交由硬件自动控制减少 GPIO 切换开销。6.3 RP2040PIO利用 PIO 状态机实现 16-bit 并行模拟超频至 20MHz替代 SPI 提升 3× 带宽需修改底层writecommand()为 PIO 程序加载 pio_sm_put_blocking()。终极验证步骤在setup()末尾添加tft.drawPixel(0,0,ST77XX_RED); tft.drawPixel(tft.width()-1,tft.height()-1,ST77XX_BLUE);。若左上角与右下角正确点亮红蓝点则证明硬件连接、SPI 时序、GRAM 地址映射全部正确可进入高级开发阶段。