1. 功能库不是复制粘贴:一块 2.13 寸墨水屏从 ZET6 搬到 C8T6 的真实成本
手上只有一块 STM32F103C8T6 最小系统板和一块 2.13 寸墨水屏模块,厂商给的却是一份跑在 ZET6 上的完整工程——LCD、OLED、FreeRTOS、演示图片数组、串口调试全在里面。多数人的第一反应是把墨水屏那几个 .c 文件复制进自己的工程,编译通过,下载进去,屏幕一动不动,调试器一挂上就是 HardFault。问题往往不在 SSD1680 驱动库写错了,而在于这份例程依赖的那套 STM32 标准外设库功能库,是按大容量器件的中断向量表组织起来的。这篇把这条搬运路完整走一遍:怎么分清哪些文件是必须留的功能库、哪些只是演示包袱,启动文件怎么换,模拟 SPI 怎么接,以及那几个几乎一定会翻车的地方。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 先拆开厂商例程:哪些是功能库,哪些是演示包袱
2.1 一份典型例程里其实叠着三层东西
厂商给的工程目录看起来是一堆平铺的 .c 文件,但按职责拆,它至少叠了三层。最底下是芯片级的功能库,也就是 STM32 标准外设库,它把 RCC、GPIO、SPI、USART 这些外设的寄存器访问封装成函数,驱动库的所有引脚操作最终都落到这一层。中间是板级驱动库,2.13 寸墨水屏的 epd_2in13_v2.c 这类文件就属于这一层,它负责 SSD1680 的上电时序、命令写入、RAM 数据搬运和刷新触发。最上面是演示层,包括演示图片数组、OLED 驱动、FreeRTOS 内核、串口打印例程,它们和屏幕能不能亮没有任何关系。
分层的意义在于:三层的删除风险完全不同。演示层删掉只是少几个花哨功能,板级驱动库删掉屏幕就不会动,芯片级功能库删掉整个工程都编不过。很多人移植失败,是因为把三层的文件混在一个目录里按名字判断去留,看见 spi.c 觉得"我用模拟 SPI 就删掉",结果驱动库里某个函数还在引用它,链接阶段才报错,回头又要一个个补。
| 分层 | 代表文件 | 职责 | 去留判断 |
|---|---|---|---|
| 芯片级功能库 | stm32f10x_gpio.c、stm32f10x_rcc.c、stm32f10x_spi.c |
寄存器封装,被驱动库直接调用 | 按驱动库实际引用保留,不是越多越好 |
| 板级驱动库 | epd_2in13_v2.c/.h、epd_2in13_v1.c/.h、epd_2in13_v2_3c.c/.h |
SSD1680 命令时序、显存搬运、刷新 | 先全留,确认屏型号后再删多余的一份 |
| 演示层 | 图片数组、OLED 驱动、FreeRTOS 内核、串口演示代码 | 展示效果、多任务调度 | 直接删,删完先确认没有源文件引用 |
2.2 三个问题决定一个文件该不该留
第一个问题:这段代码是否被中断向量表或启动文件绑定?被绑定意味着它不是"删了就少个功能",而是"删了连中断都进不来",这类文件必须跟着启动文件一起换,不能单独裁。
第二个问题:它吃多少 Flash?C8T6 的 Flash 只有 64K,官方例程光演示图片数组动辄几十 KB,裁剪后代码占用只有十几 KB。这个差距不是优化技巧,而是能不能装下的问题。所以判断顺序应该是先看体积,再看功能——一个几十 KB 的图片数组,价值再高也留不住。
第三个问题:它是不是阻塞主循环?墨水屏一段完整的刷新流程从写 RAM 到刷新结束至少要几百毫秒,这个时间尺度决定了它和实时任务天然不合。FreeRTOS 直接删掉,不是因为用不上,而是因为屏幕刷新本身就是阻塞式的,把它塞进任务里只会让移植复杂度上升,对初学者是负担。
这三个问题问完,通常能砍掉一半以上的文件。砍完别急着编译,先把目录按职责重排一遍,后面出问题才知道该看哪个文件夹。
2.3 动手:把工程按功能分层重排
裁剪的原则很简单:只保留标准外设库的 RCC、GPIO、SysTick 相关源文件,以及墨水屏的 .c/.h 文件。FreeRTOS 直接删掉。我一般会把整个项目按下面这个结构组织,每个文件只负责一件事,出了问题能快速定位是功能库层、驱动库层还是应用层的问题。
text复制stm32f103c8t6_epd/
├── Core/
│ ├── main.c /* 主流程:初始化、显示、睡眠 */
│ ├── delay.c/.h /* 基于 SysTick 的毫秒/微秒延时 */
│ ├── gpio.c/.h /* 引脚初始化,含 JTAG 关闭 */
│ └── usart.c/.h /* 可选:调试串口输出 */
├── Drivers/
│ ├── stm32f10x_gpio.c
│ ├── stm32f10x_rcc.c
│ └── stm32f10x_spi.c /* 未使用,保留备用 */
└── EPD/
├── epd_2in13_v2.c/.h /* 黑白屏 V2 驱动 */
├── epd_2in13_v1.c/.h /* 老款黑白屏驱动 */
└── epd_2in13_v2_3c.c/.h /* 三色屏驱动 */
这个结构的关键点在于:Core 放的是"工程自己的东西",Drivers 放的是芯片级功能库,EPD 放的是板级驱动库。以后换一块屏,只动 EPD;换一颗芯片,只动 Drivers 和启动文件;改业务逻辑,只动 Core。三者的边界清楚了,才谈得上复用。
stm32f10x_spi.c 这一项可以保留也可以删除。如果确定用模拟 SPI,删除之后还能省一点点 Flash;但保留它不影响编译,也不占运行开销,我倾向于先留着,等驱动库跑通、确认没有任何一处引用之后再删。EPD 目录下三份驱动先全部留着,等确认手上这块屏到底是 V2 黑白、V1 老款还是三色版本,再把另外两份移出工程——屏型号搞错的表现是刷新出乱码或者整屏反色,那时候如果只剩一份驱动,你会怀疑是时序问题,实际上是拿错了库。
提示:裁剪阶段不要一边删文件一边改驱动代码。先把目录重排、把明显无关的演示层移出去,编译一次确认干净,再动驱动库里的内容,两次改动混在一起,报错就说不清是谁引起的。
3. 换启动文件不是改个文件名:功能库与中断向量表的绑定
3.1 hd 和 md 的差别到底在哪
ZET6 属于大容量产品,官方例程里的启动文件是 startup_stm32f10x_hd.s;C8T6 属于中容量产品,对应的启动文件是 startup_stm32f10x_md.s。这两个文件的名字差两个字母,内容差的是一整套中断向量表:大容量器件的向量表里多出一批外设中断入口,位置编号和中容量器件并不完全对齐。
混用的后果不是"某个中断不响应"这么温和的描述,而是 HardFault 或者程序直接跑飞。原因很直接:启动文件在复位后会把向量表搬到 Flash 起始处,功能库里的中断服务函数按名字链接到对应的向量槽位,槽位一旦错位,一个本该由 SysTick 触发的中断可能跳进一个空的或错误的入口,CPU 取到非法指令就进 HardFault。这类故障的迷惑性在于它和你的驱动代码毫无关系,你改一百遍 SSD1680 的初始化时序也不会好。
3.2 换启动文件时要同步改的三处
第一处是启动文件本身。把 startup_stm32f10x_hd.s 从工程里移除,加入 startup_stm32f10x_md.s,并在工程配置的启动文件列表里确认只剩一份。两份同时存在时,链接器可能挑错的那一份,症状和没换一模一样。
第二处是全局宏定义。标准外设库靠 STM32F10X_MD 这类宏来决定包含哪些外设定义、条件编译哪段代码。工程里如果还留着 STM32F10X_HD,功能库会按大容量器件的寄存器布局去访问,即使启动文件换对了,外设访问依然可能落到不存在的地址上。这一处最容易漏,因为编译不报错,运行时才出问题。
第三处是器件型号与 Flash 容量相关的配置。工程选项里的器件型号要选到 C8T6 对应的中容量条目,链接时使用的容量参数也要跟着改。这三处改完,先编译一次看有没有重复定义或者找不到符号的报错,再下载。
c复制/* Core/main.c 里最前面确认工程使用的是哪套宏 */
#if !defined(STM32F10X_MD)
#error "全局宏必须是 STM32F10X_MD,否则功能库会按大容量器件布局访问寄存器"
#endif
这段预处理检查没有任何运行开销,作用是把"宏定义漏改"这种只在运行时才暴露的错误提前到编译阶段。STM32F10X_MD 这个宏名对应中容量产品线,是标准外设库自己约定的名字,不要自己另起一个。工程里如果同时定义了 STM32F10X_HD 和 STM32F10X_MD,这段检查不会报错,所以改完宏之后要手工在工程配置里翻一遍,确认旧的那个已经删掉。
3.3 功能库最底层的两个假设:时钟和 SysTick
标准外设库有一批函数默认你已经把系统时钟配好,比如 RCC_GetClocksFreq 会去读寄存器推算当前频率,SystemCoreClock 这个全局变量由 system_stm32f10x.c 在启动阶段写一次。如果工程里的时钟初始化被裁掉了,或者外部晶振的宏和实际板子不一致,SystemCoreClock 就是个错值,所有基于它计算的延时、波特率、SPI 分频全部偏移。
延时是第二个假设。墨水屏驱动库里的上电时序、复位脉宽、命令间等待,几乎全部靠毫秒级延时撑起来,所以 delay.c 必须最先跑通。我一般只用 SysTick 做延时源,不占用任何定时器外设,这样驱动库和业务代码不会抢同一个定时器。
c复制/* Core/delay.c:只用 SysTick,不占定时器外设 */
static volatile uint32_t s_tick_ms;
void SysTick_Handler(void)
{
if (s_tick_ms) {
s_tick_ms--;
}
}
void delay_init(void)
{
/* 重装值 = SystemCoreClock / 1000 - 1,1ms 一次中断 */
SysTick_Config(SystemCoreClock / 1000);
}
void delay_ms(uint32_t ms)
{
s_tick_ms = ms;
while (s_tick_ms) {
__NOP();
}
}
SysTick_Config 的入参是两次中断之间的计数个数,用 SystemCoreClock / 1000 得到的就是 1ms 对应的计数值,所以这里不要写死一个常数,主频一变延时就会整体偏。s_tick_ms 必须是 volatile,否则开优化后 while 循环可能被编译器优化成死循环。另外要注意:这个延时是忙等,精度够用但会占 CPU,墨水屏刷新本来就是阻塞流程,这样写没有额外损失;如果以后要在延时期间做别的事,就得换成状态机而不是加长忙等。
延时跑通之后有个快速自检方法:让一个空闲引脚在 delay_ms(100) 前后翻转,用逻辑分析仪或者示波器看周期是不是 100ms 上下。这一步花十分钟,能省掉后面怀疑驱动库时序的几个小时。
4. 把功能库裁到最小:RCC + GPIO + SysTick + 一份 SSD1680 驱动
4.1 标准外设库里哪几个 .c 必须留
裁剪到最小集合之后,Drivers 目录里通常只剩三个文件:stm32f10x_rcc.c 负责时钟使能和复位,stm32f10x_gpio.c 负责引脚模式配置和电平读写,stm32f10x_spi.c 视你是否用硬件 SPI 而定。misc.c 如果驱动库里用到中断优先级配置就得留,纯轮询的墨水屏驱动一般用不到 NVIC,可以不进工程——但删之前先在驱动库源码里搜一遍有没有 NVIC_ 开头的调用。
判断"必须留"的方法不是看文件名,而是看链接结果。先把可疑文件移出工程,编译一次,链接器报 undefined symbol 的时候会明确告诉你哪个函数缺定义,那个函数所在的 .c 就得留下。这个流程比凭经验列清单可靠,因为不同版本的驱动库引用关系并不一样。
还有一类容易忽略的依赖:core_cm3.h 和 system_stm32f10x.c。它们不属于外设库的 .c 文件列表,但 SystemCoreClock、__NOP()、SysTick 的寄存器定义全部来自这里。删掉它们,前面那套延时和宏检查全部失效。
4.2 墨水屏驱动库的三层:谁该改,谁不该动
一份能用的 SSD1680 驱动库内部也是分层的。最底下是硬件抽象,负责 CS、DC、RST、BUSY 四根控制线和 SCK、MOSI 两根数据线的电平操作;中间是控制器寄存器层,按 SSD1680 的命令表写入命令字节和参数字节;最上面是应用接口,对外通常只暴露初始化、清屏、整帧刷新、睡眠这几类动作。
移植时该改的只有最底下的硬件抽象层。控制器寄存器层和上面的接口层一个字都不要动——那部分是厂商对着数据手册写出来的时序,你改一个等待时间就可能让屏幕进入异常状态,而且这种错误不会立刻表现出来,可能刷十几次才花屏。判断边界的方法:凡是出现 GPIO_SetBits、GPIO_ResetBits 的地方属于抽象层,可以改;凡是出现命令字面量(比如上电、软复位、写 RAM 这类操作码)的地方属于寄存器层,不动。
实际做法是把引脚定义全部收进一个头文件,比如 epd_port.h,抽象层的 .c 只引用宏名,不出现具体端口。换板子的时候只改这一个头文件,驱动库本体保持原样,下次再移植还能直接复用。
c复制/* EPD/epd_port.h:所有接线只在这一个文件里定义 */
#define EPD_CS_PORT GPIOB
#define EPD_CS_PIN GPIO_Pin_x /* 按实际接线填 */
#define EPD_DC_PORT GPIOB
#define EPD_DC_PIN GPIO_Pin_x
#define EPD_RST_PORT GPIOB
#define EPD_RST_PIN GPIO_Pin_x
#define EPD_BUSY_PORT GPIOB
#define EPD_BUSY_PIN GPIO_Pin_x
#define EPD_SCK_PORT GPIOB
#define EPD_SCK_PIN GPIO_Pin_x
#define EPD_MOSI_PORT GPIOB
#define EPD_MOSI_PIN GPIO_Pin_x
把这些宏单独抽出来,除了换板子方便,还有一个好处:BUSY 引脚的读取在驱动库里通常是一个带超时的轮询循环,如果 BUSY 接错或者没接,表现是刷新函数一直不返回。有了集中定义,排查时第一眼就能确认 BUSY 到底配成了输入还是输出、上拉有没有开。这一步是墨水屏移植里最常见的低级错误来源。
4.3 模拟 SPI 还是硬件 SPI
材料里 stm32f10x_spi.c 标了"未使用,保留备用",说明原作者走的是模拟 SPI。这两种方式在墨水屏场景下的差别比想象中小,因为瓶颈根本不在 SPI 速率上——一次完整刷新要几百毫秒,其中绝大部分时间花在屏幕内部的驱动波形上,SPI 传那几百字节显存的时间可以忽略。
| 对比项 | 模拟 SPI | 硬件 SPI |
|---|---|---|
| 占用引脚 | SCK、MOSI 两根,可任意选 | 固定的 SPI 复用引脚,受重映射限制 |
| 代码量 | 一个位操作函数,十几行 | 需要初始化 SPI 外设、配分频和模式 |
| 速率 | 低,但对墨水屏够用 | 高,但在这类屏上没有实际收益 |
| 调试难度 | 引脚电平常量可测,逻辑分析仪直接看 | 需要确认 CPOL/CPHA 和位序 |
| 与其他外设冲突 | 无 | 与同复用组的其他功能冲突 |
选模拟 SPI 的核心理由是可测。刷新不动的时候,你可以用万用表或者逻辑分析仪直接量 SCK 有没有跳变、CS 有没有拉低,问题定位到"根本没发数据"还是"发了但屏幕没响应"。硬件 SPI 一旦模式配错,波形看起来也是"有数据在动",反而更难判断。
c复制/* EPD/epd_port.c:模拟 SPI 写一个字节,高位先出 */
void epd_spi_write_byte(uint8_t dat)
{
uint8_t i;
for (i = 0; i < 8; i++) {
if (dat & 0x80) {
GPIO_SetBits(EPD_MOSI_PORT, EPD_MOSI_PIN);
} else {
GPIO_ResetBits(EPD_MOSI_PORT, EPD_MOSI_PIN);
}
dat <<= 1;
GPIO_ResetBits(EPD_SCK_PORT, EPD_SCK_PIN); /* 先拉低 */
GPIO_SetBits(EPD_SCK_PORT, EPD_SCK_PIN); /* 上升沿采样 */
}
}
这个函数的参数只有待发送的一个字节,时序上靠"先置数据、再产生上升沿"来保证从机在上升沿采样到稳定电平。SSD1680 是高位先出的,所以循环里判断的是 0x80 而不是 0x01,写反了的表现是整屏花屏但不会报错。循环里没有加延时,因为 C8T6 的 GPIO 翻转速度远低于 SSD1680 能接受的 SPI 上限,加延时反而会让刷屏变慢。如果板上走线比较长、出现偶发花屏,再在两次翻转之间插一两个 __NOP() 试试。
5. 避坑:四个会让人怀疑驱动库写错了的现象
5.1 现象:编译通过,下载后不跑,一挂调试器就 HardFault
现象很典型:程序下载进去,屏幕毫无反应,接上调试器点运行,立刻停在 HardFault 处理函数里,反汇编窗口的地址落在中断向量表附近。
原因基本只有一个:启动文件和器件容量不匹配。工程里还留着 startup_stm32f10x_hd.s,而芯片是 C8T6 这种中容量器件,两套中断向量表的入口编号对不上,复位后取到的第一条指令或者第一个中断入口就是错的。全局宏 STM32F10X_HD 没删干净也会造成同一类后果——启动文件换对了,功能库仍按大容量器件的寄存器布局访问。
解决顺序是固定的:先确认工程里只剩 startup_stm32f10x_md.s 一份启动文件,再确认全局宏只剩 STM32F10X_MD,然后全量重新编译(不是增量编译),最后再下载。顺序反过来做,你会在两个都错的情况下改一个、测一个,永远测不通。
5.2 现象:程序能跑,但 SWD 再也连不上
现象是第一次下载成功,程序也在跑,屏幕会刷新,但下一次想连调试器时提示目标无法连接,必须按住复位或者用 Boot 方式才能恢复。
原因是 gpio.c 里那段 JTAG 关闭的代码。C8T6 的 SWD 引脚和 JTAG 的部分引脚是复用的,为了把复用引脚腾出来给墨水屏用,驱动里会关掉 JTAG。这段代码本身没问题,问题出在关闭的时机和范围:如果把 SWD 也一起关了,或者关闭动作执行得太早、在调试器建立连接之前就生效,下次上电就没有调试通道了。材料里把这段放在 gpio.c 里是有道理的,它属于引脚初始化的一部分,必须在驱动库操作引脚之前完成。
解决方式是只关 JTAG、保留 SWD,并且把这段配置放在 main 里其他外设初始化之后、屏幕初始化之前。另外养成一个习惯:每次改完引脚配置,先用一个最简单的点灯程序验证还能不能连上调试器,再继续写业务。这个习惯救过我很多次,因为一旦调试通道没了,后面所有问题的排查成本都会翻倍。
5.3 现象:编译过了,下载后卡在启动阶段或者屏幕只亮一半
现象是编译没有任何警告,下载后程序像是卡在某个地方不动,或者屏幕能初始化但刷新到一半就停住。
先看 Flash 占用。C8T6 只有 64K,官方例程里那些演示图片数组动辄几十 KB,裁剪后代码占用应该只有十几 KB。如果编译输出显示占用超过 50K,第一件事就是查是不是把演示图片数组带进来了,或者链接脚本里还引用着那批常量。这个数字不是绝对红线,但它是一个非常明确的信号:你的裁剪没裁干净。
另一种可能是栈不够。驱动库里如果有大的局部数组(比如整帧显存的临时缓冲),默认栈大小可能撑不住,表现是进入函数后跑飞或者数据被踩。解决方式是把这类大缓冲改成静态全局变量,或者直接在工程配置里把栈调大,两种都行,但要知道自己在改什么。
5.4 现象:刷新一次要几百毫秒,喂狗和低功耗全乱
现象是每刷一次屏,主循环就停顿几百毫秒,如果工程里开了看门狗,会直接被复位;如果做了低功耗休眠,唤醒时序和刷新时序对不上。
原因是墨水屏的刷新本身就是阻塞式的,从写 RAM 到刷新结束至少要几百毫秒,这段时间里驱动库在轮询 BUSY 引脚,CPU 做不了别的事。材料里删掉 FreeRTOS 正是这个原因:把一个几百毫秒的阻塞流程塞进任务里,只会让调度变得更难分析,并不会让它变快。
解决有三条路,按代价从低到高:一是把刷新安排在不需要喂狗的时间窗里,刷新前手动喂一次,刷新后立刻再喂一次;二是把刷新拆成"写 RAM"和"触发刷新"两步,写 RAM 阶段可以被其他逻辑打断,只有触发之后才进入真正的长等待;三是把 BUSY 轮询改成中断或者状态机,但这需要驱动库支持,多数厂商库不提供这个接口,改起来要动寄存器层,风险不小。我一般选第二条,因为它不改驱动库本体。
注意:不要用"缩短延时"来提速。驱动库里的等待时间是按 SSD1680 的上电和刷新时序留的余量,改短了可能前一两次正常,温度一变就开始花屏,这种问题极难复现。
6. 验证驱动库真的在跑:三个可观测点与模板化收尾
6.1 三个可观测点,比盯着屏幕靠谱
第一个点是引脚电平。刷新开始时用逻辑分析仪抓 CS、DC、SCK 三根线,正常应该是 CS 拉低、DC 按命令和数据交替翻转、SCK 成串脉冲。如果 CS 一直是高,说明驱动库根本没被调用;如果 SCK 有脉冲但 DC 不变,说明命令和数据写混了。这一步能把"驱动库没跑"和"驱动库跑了但屏幕没响应"分开。
第二个点是 BUSY 引脚。初始化之后 BUSY 应该被屏幕拉到一个确定电平,刷新期间翻转,结束后回到稳定状态。如果 BUSY 一直是同一个电平,先查是不是配成了输出模式,或者上拉电阻没焊。
第三个点是串口日志。在驱动库的初始化和刷新前后各打一行,确认流程走到了哪一步。串口输出比点灯信息量大,而且不占额外引脚。
6.2 抽成模板的三条规矩
第一条,epd_port.h 里只放引脚宏,不放任何逻辑,保证换板子只改一个文件。第二条,延时函数独立成 delay.c,不依赖任何定时器外设,保证驱动库可以整块搬走。第三条,工程目录按 Core、Drivers、EPD 三层固定下来,新项目直接复制这三层,改完引脚宏就能跑。
我现在每次拿到一份新的外设例程,都强制先做一遍目录分层和启动文件核对,再看驱动代码。这个习惯是被 HardFault 逼出来的:那次排查花了一整天,最后发现只是启动文件没换。从那以后我每次移植都强制走一遍"启动文件、全局宏、目录分层"这三步,希望帮到你。
