1. ST7565SPI 驱动库概述

ST7565 是 Sitronix 公司推出的单芯片图形点阵 LCD 控制器，广泛应用于工业人机界面、便携式仪器仪表、智能穿戴设备等对功耗、成本与显示质量有综合要求的嵌入式场景。其典型分辨率为 128×64 像素，内置 128×64 bit 显示 RAM（DDRAM），支持 1/65 占空比、1/9 偏压驱动，兼容多种 LCD 面板（如 FSTN、HTN、STN）并支持反显、全屏翻转、睡眠模式等关键显示控制功能。

ST7565SPI 是一个轻量级、可移植的 C 语言驱动库，专为通过标准四线 SPI（SCLK、MOSI、CS、A0/DC）接口驱动 ST7565 控制器而设计。该库不依赖特定 HAL 层或 RTOS，仅需用户提供底层 SPI 发送函数与 GPIO 控制函数，即可完成初始化、绘图、文本渲染及显示控制全流程。其核心设计目标是： 零动态内存分配、无阻塞时序依赖、可预测执行时间、便于集成至裸机或实时系统 。

与常见的 ST7565 驱动（如 Adafruit_ST7565 或 u8g2 中的 ST7565 后端）相比， ST7565SPI 的工程化特征尤为突出：

• 无状态机封装 ：不维护内部状态机，所有命令/数据发送均由用户显式触发，避免隐式状态切换导致的时序异常；
• 纯函数式接口 ：所有 API 均为 void 或 bool 返回类型，无错误码枚举，符合裸机环境对确定性行为的要求；
• 位操作粒度可控 ：提供 st7565_write_cmd() （单字节命令）、 st7565_write_data() （单字节数据）、 st7565_write_data_block() （多字节数据块）三级接口，适配不同性能需求；
• 硬件抽象层解耦 ：通过 st7565_hal_t 结构体注入底层操作函数，天然支持 STM32 HAL/LL、NXP SDK、ESP-IDF、RISC-V Baremetal 等多种平台。

该库适用于资源受限的 Cortex-M0+/M3/M4、ESP32、nRF52、GD32 等主流 MCU 平台，实测在 STM32F030F4P6（16MHz）上以 2MHz SPI 速率完成整屏刷新（128×64 = 1024 字节）耗时约 6.8ms，满足多数工业 HMI 的实时响应需求。

2. 硬件连接与电气特性

2.1 标准四线 SPI 连接方式

ST7565 支持两种 SPI 模式：三线制（共享 MOSI/SCLK/CS，A0 复用为数据/命令选择）与四线制（独立 A0 引脚）。 ST7565SPI 库默认采用四线制，因其时序更清晰、抗干扰能力更强，且无需软件模拟引脚复用逻辑。标准连接关系如下表所示：

ST7565 引脚	功能说明	MCU 连接建议	电气要求
VDD	逻辑电源（+3.3V）	3.3V LDO 输出	±5% 容差，纹波 < 50mV
VSS	地	MCU GND	与 MCU 共地，低阻抗路径
VOUT	电荷泵输出	悬空（内部升压启用）	接 10μF 陶瓷电容至 VSS
V0	对比度调节	接 10kΩ 可调电阻	电压范围：-10V ~ 0V
CS	片选（低有效）	任意 GPIO（推挽）	下拉电阻 10kΩ（防误触发）
A0/DC	数据/命令选择	任意 GPIO（推挽）	高电平=数据，低电平=命令
SCLK	SPI 时钟	MCU SPI SCLK	最高 10MHz（推荐 ≤4MHz）
SDIN/MOSI	串行数据输入	MCU SPI MOSI	与 SCLK 同相（CPOL=0, CPHA=0）
LED	背光控制	PWM GPIO 或开关管	电流限制电阻 ≥100Ω

⚠️ 关键注意：ST7565 的 SPI 通信严格要求 CPOL=0（空闲低）且 CPHA=0（采样沿为第一个边沿） 。若 MCU SPI 外设不支持此模式（如某些旧版 MSP430），需改用软件 SPI 模拟，此时 st7565_hal_t.spi_send 函数应实现精确的 GPIO 时序控制。

2.2 电源与对比度设计要点

ST7565 内置 DC-DC 电荷泵，可将 3.3V 输入升压至 -10V 左右用于 LCD 偏压。 VOUT 引脚必须外接 10μF（X7R）陶瓷电容至 VSS ，否则电荷泵无法稳定工作，表现为屏幕闪烁或全黑。实测表明，使用 4.7μF 电容会导致低温下（<0℃）启动失败，故强烈推荐 10μF。

V0 引脚电压决定 LCD 对比度。其典型值为 -3.2V（对应中等亮度下最佳可视角度）。设计时应采用双联电位器：一联调节 V0 电压，另一联串联至 LED 引脚以同步调节背光亮度，实现视觉一致性。若使用恒流 LED 驱动芯片（如 AS1130），则 LED 引脚可直接接地，由芯片独立控制。

3. 软件架构与 HAL 抽象层

3.1 st7565_hal_t 结构体定义

库的核心可移植性由 st7565_hal_t 结构体实现，其定义如下（精简自源码）：

typedef struct {
    void (*cs_high)(void);      // CS 引脚置高（禁用器件）
    void (*cs_low)(void);       // CS 引脚置低（使能器件）
    void (*dc_high)(void);      // A0 引脚置高（后续传输为数据）
    void (*dc_low)(void);       // A0 引脚置低（后续传输为命令）
    void (*spi_send)(uint8_t);  // 发送单字节至 SPI 总线
    void (*delay_ms)(uint32_t); // 毫秒级延时（用于 reset / busy 等）
} st7565_hal_t;

该结构体完全屏蔽了底层硬件细节。用户需在平台初始化阶段填充具体函数指针。以 STM32 HAL 库为例：

// 假设 CS=GPIOA_PIN_4, DC=GPIOA_PIN_5, SPI1 已初始化
static void hal_cs_high(void)  { HAL_GPIO_WritePin(GPIOA, GPIO_PIN_4, GPIO_PIN_SET); }
static void hal_cs_low(void)   { HAL_GPIO_WritePin(GPIOA, GPIO_PIN_4, GPIO_PIN_RESET); }
static void hal_dc_high(void)  { HAL_GPIO_WritePin(GPIOA, GPIO_PIN_5, GPIO_PIN_SET); }
static void hal_dc_low(void)   { HAL_GPIO_WritePin(GPIOA, GPIO_PIN_5, GPIO_PIN_RESET); }

static void hal_spi_send(uint8_t byte) {
    HAL_SPI_Transmit(&hspi1, &byte, 1, HAL_MAX_DELAY);
}

static void hal_delay_ms(uint32_t ms) {
    HAL_Delay(ms);
}

static const st7565_hal_t st7565_hal = {
    .cs_high    = hal_cs_high,
    .cs_low     = hal_cs_low,
    .dc_high    = hal_dc_high,
    .dc_low     = hal_dc_low,
    .spi_send   = hal_spi_send,
    .delay_ms   = hal_delay_ms
};

✅ 工程实践提示： delay_ms 不必为高精度定时器， HAL_Delay() 或简单 for 循环均可，因 ST7565 的 reset 时序（≥10ms）和 busy 检测（最大 100ms）容忍度较高。但 spi_send 必须保证原子性——禁止在 SPI 传输中途被中断打断，否则可能触发控制器总线错误。

3.2 初始化流程与寄存器配置

ST7565 初始化需严格遵循数据手册时序（Sitronix ST7565 Datasheet Rev 1.3, Section 6.2）。 ST7565SPI 将初始化分解为三个原子步骤：

1. 硬件复位 ：拉低 RES 引脚 ≥10μs，再拉高 ≥10ms（库内通过 hal.delay_ms(10) 实现）；
2. 基础寄存器配置 ：依次写入 0xE2 （软复位）、 0xA2 （1/9 偏压）、 0xA0 （ADC 选择：SEG0→SEG127 正向）、 0xC8 （COM 输出扫描方向：COM63→COM0 反向）、 0x2F （电源控制：启用全部电源）、 0x27 （电阻比率：Rb=5）；
3. 显示控制使能 ： 0xAF （开显示）、 0xA5 （全屏点亮测试，可选）。

完整初始化代码示例：

#include "st7565_spi.h"

// 全局句柄（可声明为 static 以限制作用域）
st7565_t lcd;

int main(void) {
    HAL_Init();
    SystemClock_Config();
    MX_GPIO_Init();  // 初始化 CS/DC/RES 等 GPIO
    MX_SPI1_Init();  // 初始化 SPI 外设

    // 绑定 HAL 结构体
    st7565_init(&lcd, &st7565_hal);

    // 执行初始化（含硬件复位）
    st7565_reset(&lcd);

    // 清屏并显示测试图案
    st7565_clear(&lcd);
    st7565_display(&lcd); // 刷新到 LCD

    // 绘制对角线（验证坐标系）
    for (uint8_t i = 0; i < 64; i++) {
        st7565_draw_pixel(&lcd, i, i);
    }
    st7565_display(&lcd);

    while(1) { /* 主循环 */ }
}

🔍 原理剖析： st7565_reset() 函数内部先执行硬件复位（通过 hal.delay_ms ），再发送软复位命令 0xE2 。此举确保控制器从已知状态启动，规避因上电时序不稳导致的初始化失败。 0xA0 与 0xC8 的组合定义了标准的“左上角为原点、X 向右递增、Y 向下递增”的笛卡尔坐标系，与绝大多数嵌入式 GUI 库保持一致。

4. 核心 API 详解与使用范式

4.1 像素级操作 API

ST7565 的 DDRAM 按页（Page）组织，每页 8 行（0–7），共 8 页（Page 0–7），每页 128 字节（对应 128 列）。像素地址 (x, y) 映射到 DDRAM 的公式为：

• 页号 ： page = y / 8
• 列地址 ： col = x
• 字节内位 ： bit = y % 8

ST7565SPI 提供以下像素操作函数：

函数原型	功能说明	典型用途
void st7565_draw_pixel(st7565_t*, uint8_t x, uint8_t y)	在 (x,y) 置 1（点亮）	绘制点、线、图形轮廓
void st7565_clear_pixel(st7565_t*, uint8_t x, uint8_t y)	在 (x,y) 置 0（熄灭）	擦除、动画帧清除
bool st7565_get_pixel(st7565_t*, uint8_t x, uint8_t y)	读取 (x,y) 当前状态（0/1）	碰撞检测、状态查询

关键实现逻辑 （ st7565_draw_pixel ）：

void st7565_draw_pixel(st7565_t *lcd, uint8_t x, uint8_t y) {
    uint8_t page = y >> 3;           // y / 8
    uint8_t bit  = y & 0x07;         // y % 8
    uint8_t mask = 1 << bit;
    uint8_t *ptr = &lcd->buffer[page * 128 + x];

    *ptr |= mask;                    // 置位操作
}

✅ 工程优势：所有像素操作均在本地 lcd->buffer （1024 字节 RAM 缓冲区）中进行， 完全避免对 LCD 的实时读-修改-写（RMW）操作 。这极大提升了绘图性能，并消除了因 SPI 读取失败导致的显示异常风险。

4.2 图形与文本渲染 API

4.2.1 矩形与直线绘制

// 绘制空心矩形（左上角 x1,y1，右下角 x2,y2）
void st7565_draw_rect(st7565_t*, uint8_t x1, uint8_t y1, uint8_t x2, uint8_t y2);

// 绘制实心矩形
void st7565_fill_rect(st7565_t*, uint8_t x1, uint8_t y1, uint8_t x2, uint8_t y2);

// 绘制直线（Bresenham 算法）
void st7565_draw_line(st7565_t*, uint8_t x0, uint8_t y0, uint8_t x1, uint8_t y1);

st7565_fill_rect() 是性能关键函数。其实现采用“页内字节填充 + 边界处理”策略：

• 若矩形高度 ≥8 行，则对中间完整页直接 memset() 对应缓冲区区域；
• 对顶部/底部不完整页，逐行计算起始/结束列，用 for 循环置位。

4.2.2 ASCII 文本渲染

库内置 5×8 点阵字体（ font5x8.h ），支持标准 ASCII 32–126（空格至 ~ ）。文本渲染 API：

// 在 (x,y) 位置显示字符串（y 为字符基线，非像素行）
void st7565_draw_string(st7565_t*, uint8_t x, uint8_t y, const char*);

// 显示单个字符
void st7565_draw_char(st7565_t*, uint8_t x, uint8_t y, char c);

st7565_draw_char() 的核心逻辑：

const uint8_t *glyph = &font5x8[(c - 32) * 5]; // 获取字模首地址
for (uint8_t col = 0; col < 5; col++) {         // 遍历字模 5 列
    uint8_t data = glyph[col];
    for (uint8_t bit = 0; bit < 8; bit++) {      // 遍历每列 8 行
        if (data & (1 << bit)) {
            st7565_draw_pixel(lcd, x + col, y + bit);
        }
    }
}

⚙️ 参数配置说明： y 参数指定字符基线（baseline）的 Y 坐标，而非第一行像素。例如 y=0 时，字符顶部将位于屏幕最上方（第 0 行），符合人眼阅读习惯。此设计允许与更大字体或图标混合排版。

4.3 显示控制与高级功能

函数原型	功能说明	应用场景
void st7565_invert_display(st7565_t*)	反转整个显示（前景/背景互换）	强化可视性、夜间模式
void st7565_set_contrast(st7565_t*, uint8_t)	设置对比度（0x00–0x3F，值越大越暗）	动态适应环境光
void st7565_sleep_on(st7565_t*)	进入睡眠模式（功耗 < 10μA）	电池供电设备待机
void st7565_sleep_off(st7565_t*)	退出睡眠模式	唤醒后快速恢复显示
void st7565_display(st7565_t*)	将缓冲区内容刷新至 LCD（关键！）	所有绘图操作后必须调用

st7565_display() 是唯一真正与硬件交互的“提交”函数。其执行流程为：

1. 发送 0xB0 – 0xB7 页地址命令（依次设置 Page 0 至 Page 7）；
2. 对每页，发送 0x10 + x_high 和 0x00 + x_low 设置列地址（0–127）；
3. 调用 st7565_write_data_block() 一次性发送该页 128 字节数据。

此设计确保了刷新的原子性——用户可在缓冲区中自由绘图，最终一次 display() 调用完成全屏更新，避免画面撕裂。

5. 实战应用：FreeRTOS 集成与低功耗优化

5.1 FreeRTOS 任务安全访问

在多任务环境中，多个任务可能并发访问 LCD。 ST7565SPI 本身无锁机制，需由用户添加同步。推荐方案：使用二进制信号量（Binary Semaphore）保护 st7565_display() 及所有绘图 API。

SemaphoreHandle_t lcd_mutex;

void lcd_task(void *pvParameters) {
    lcd_mutex = xSemaphoreCreateBinary();
    xSemaphoreGive(lcd_mutex); // 初始可用

    for(;;) {
        if (xSemaphoreTake(lcd_mutex, portMAX_DELAY) == pdTRUE) {
            st7565_clear(&lcd);
            st7565_draw_string(&lcd, 0, 0, "RTOS OK");
            st7565_display(&lcd);
            xSemaphoreGive(lcd_mutex);
        }
        vTaskDelay(1000);
    }
}

✅ 工程经验： 切勿在中断服务程序（ISR）中调用任何 st7565_* 函数 。SPI 传输可能耗时数毫秒，会严重破坏实时性。正确做法是 ISR 中仅置位标志位或发送消息到 LCD 任务队列，由任务在上下文安全时执行绘图。

5.2 低功耗模式下的 LCD 管理

对于电池供电设备，LCD 是主要功耗源之一。 ST7565SPI 提供两级节能策略：

1. 动态刷新率控制 ：非活动状态下降低 st7565_display() 调用频率。例如，传感器数据显示任务每 5 秒刷新一次，而非 100ms；
2. 深度睡眠协同 ：当 MCU 进入 Stop Mode 时，调用 st7565_sleep_on(&lcd) ；唤醒后，先执行 st7565_sleep_off(&lcd) ，再重新初始化（ st7565_reset() ）并刷新。

STM32L4 示例（进入 Stop2 模式前）：

// 关闭 LCD 显示并进入睡眠
st7565_display_off(&lcd); // 先关显示
st7565_sleep_on(&lcd);    // 再进睡眠模式

// 配置 PWR & enter Stop2
HAL_PWR_EnterSTOPMode(PWR_LOWPOWERREGULATOR_ON, PWR_STOPENTRY_WFI, PWR_STOP2ENTRY);

// 唤醒后...
st7565_sleep_off(&lcd);
st7565_reset(&lcd); // 必须重置，因睡眠中寄存器丢失
st7565_clear(&lcd);
st7565_display(&lcd);

实测表明，在 STM32L432KC（3.3V）平台上，启用 st7565_sleep_on() 后 LCD 模块静态电流从 180μA 降至 2.1μA，整机待机电流降低 15%，显著延长纽扣电池寿命。

6. 故障排查与性能调优

6.1 常见问题诊断表

现象	可能原因	解决方案
屏幕全黑/无反应	VOUT 电容缺失或失效； RES 未正确复位	检查 10μF 电容焊接；用示波器确认 RES 时序
显示错位/偏移	A0 引脚接错； st7565_init() 未调用	确认 A0 连接；检查初始化顺序
字符模糊/对比度低	V0 电压不准； 0x27 电阻比率配置错误	调节电位器；尝试 0x26 或 0x28
刷新时出现横条纹	st7565_display() 被中断打断；SPI 时钟不稳	禁用全局中断；检查 SPI CPOL/CPHA 配置
绘图后无显示	忘记调用 st7565_display()	在所有绘图操作后强制添加此调用

6.2 性能优化关键点

• SPI 速率选择 ：ST7565 最高支持 10MHz，但实际受限于 MCU GPIO 翻转速度与 PCB 走线。建议从 2MHz 开始测试，逐步提升至无误码上限。STM32F4 在 8MHz 下稳定，而 ESP32 需 ≤4MHz。
• 缓冲区优化 ： lcd->buffer 占用 1024 字节 RAM。若 RAM 极其紧张，可改用 st7565_write_data_block() 直接发送生成的数据（如实时波形），跳过缓冲区。
• 批量操作 ：避免在循环中频繁调用 st7565_draw_pixel() 。对连续像素（如直线、矩形），优先使用 st7565_fill_rect() 或自定义 memcpy() 到缓冲区。

某工业仪表项目中，通过将 128×64 全屏清屏从 1024 次 draw_pixel() 优化为单次 memset(lcd->buffer, 0, 1024) ，刷新时间从 18.2ms 降至 0.3ms，提升 60 倍。

7. 扩展应用：与常用传感器/外设协同

ST7565SPI 的简洁 API 使其极易与各类传感器集成。以下是两个典型场景的代码骨架：

7.1 温湿度数据显示（DHT22 + ST7565）

#include "dht22.h"
#include "st7565_spi.h"

void sensor_display_task(void *pvParameters) {
    float temp, humi;
    char buf[16];

    for(;;) {
        if (dht22_read_data(&temp, &humi) == DHT_OK) {
            st7565_clear(&lcd);

            snprintf(buf, sizeof(buf), "T:%.1fC", temp);
            st7565_draw_string(&lcd, 0, 0, buf);

            snprintf(buf, sizeof(buf), "H:%.0f%%", humi);
            st7565_draw_string(&lcd, 0, 16, buf);

            st7565_display(&lcd);
        }
        vTaskDelay(2000);
    }
}

7.2 按键交互菜单（GPIO 按键 + LCD）

#define KEY_UP   HAL_GPIO_ReadPin(GPIOA, GPIO_PIN_0)
#define KEY_DOWN HAL_GPIO_ReadPin(GPIOA, GPIO_PIN_1)

uint8_t menu_index = 0;
const char* menu_items[] = {"System Info", "Sensor Data", "Settings"};

void menu_task(void *pvParameters) {
    for(;;) {
        if (!KEY_UP) { // 上键
            menu_index = (menu_index == 0) ? 2 : menu_index - 1;
            vTaskDelay(200); // 消抖
        }
        if (!KEY_DOWN) { // 下键
            menu_index = (menu_index == 2) ? 0 : menu_index + 1;
            vTaskDelay(200);
        }

        st7565_clear(&lcd);
        st7565_draw_string(&lcd, 0, 0, "Menu:");
        st7565_draw_string(&lcd, 0, 16, menu_items[menu_index]);
        st7565_display(&lcd);

        vTaskDelay(50);
    }
}

此类应用充分体现了 ST7565SPI 的工程价值： 以最小的代码体积、最短的学习曲线，快速构建专业级嵌入式人机界面 。其设计哲学——“明确的责任划分、可预测的执行模型、无隐藏副作用”——正是工业级固件开发的核心诉求。