简介：这份工程资料面向已具备STM32基础、希望进阶掌握图形界面与实时系统协同开发的嵌入式学习者，围绕STM32F429 DISC1开发板，给出STemwin图形库与FreeRTOS操作系统的移植示例，并用GUIbuilder设计两个按钮，通过按钮事件控制LED亮灭。资源包共530个文件，约18.26MB，以h头文件、c源文件、o目标文件、d依赖文件及crf编译中间文件为主，同时包含uvproj工程、sct分散加载、hex与map等构建产物，便于直接打开工程、对照编译链路和移植配置进行复现。该资料已有966人学习，价值在于把LCD与触摸驱动适配、FreeRTOS任务调度、GUI事件回调与硬件控制串成完整实践链；包内还包含多种GUI控件与对话框演示源码，可对照学习界面组织、事件绑定及竖屏布局调整，适合课程设计、毕业设计及嵌入式GUI入门项目借鉴。
1. 版本先定死：STM32F429I-DISC1 上 STemWin 与 FreeRTOS 的这套组合
在 STM32F429I-DISC1 上把 STemWin、FreeRTOS、GUIBuilder 三个东西凑到一块，最先让人卡住的其实不是代码写错，而是显存和版本这两件事在开始写代码之前就没定下来。这块板子自带 8MB SDRAM，还配了一块 240x320 的并口屏，看上去条件很充足；可 STemWin 的显存要从 SDRAM 里划，emWin 自己的堆也从 SDRAM 里划，FreeRTOS 的堆又留在内部 SRAM 里，而 LTDC 一开就会不停地把 SDRAM 读出来刷新屏幕，这三项内存一旦分错，GUI_Init 就会直接返回 1，串口上连一行有用的日志都没有，只能对着黑屏推断原因。这套环境适合已经能点亮屏幕、想继续往 GUI 界面加交互的人，也适合接手别人工程、看到一堆 GUI_X_OS.c 却不敢改动的人。这一篇我会按“把工程骨架立起来、再把 STemWin 移植进来、最后用 GUIBuilder 生成带两个按钮的界面”这个顺序讲，参数都给出可以照抄的取值。
2. 工程骨架先立住：CubeMX 里把 SDRAM、LTDC、DMA2D 和 FreeRTOS 一次配齐
这一章的目标很明确：在写任何一行 GUI 代码之前，先让屏幕稳定刷出一块纯色。很多人的做法是先移植 emWin，等 GUI_Init 报错再回头查硬件，结果排错范围被拉得很大，光是把问题定位到具体环节就要花掉半天时间。我的习惯是先用 CubeMX 生成一版不带任何 GUI 的裸机工程，确认 SDRAM 读写正常、LTDC 能稳定刷屏，再往上加东西。
2.1 SDRAM 控制器：先确认显存这块区域能不能正常读写
DISC1 上那颗 SDRAM 挂在 FMC 的 Bank 1，映射到 0xC0000000，容量 8MB，16 位数据宽度，12 位行地址、8 位列地址、4 个 Bank。这个容量对于 240x320 的 RGB565 单缓冲来说绰绰有余：一帧只有 240×320×2 = 150KB，但别忘了后面还要给 emWin 划 1MB 的堆，加起来也就 1.2MB，剩下的空间可以用来做双缓冲，或者存字库。
CubeMX 里 FMC 的参数按这张表填，这些值是我在 180MHz 主频、SDRAM 时钟 90MHz 下反复验证过能稳定跑的一组：
| 参数 | 取值 | 说明 |
|---|---|---|
| SDRAM Bank | Bank 1 | 基址 0xC0000000 |
| Row Bits Number | 12 | 对应 4096 行 |
| Column Bits Number | 8 | 对应 256 列 |
| Data Width | 16 bit | 半字访问 |
| CAS Latency | 3 | 90MHz 下用 3 比较稳 |
| Write Protection | Disabled | 显存需要可写 |
| Clock Period | 90 MHz | HCLK/2 |
时序参数在 CubeMX 的 SDRAM Timing 页里按周期数填，不要直接填纳秒：
/* FMC SDRAM 时序，单位是 SDRAM 时钟周期（90MHz，约 11.1ns） */ hsdram1.Init.LoadToActiveDelay = 2; /* tMRD，最小 2 周期 */ hsdram1.Init.ExitSelfRefreshDelay = 7; /* tXSR，退出自刷新后要等够 */ hsdram1.Init.SelfRefreshTime = 4; /* tRAS，最小 4 周期 */ hsdram1.Init.RowCycleDelay = 7; /* tRC，60ns 按 7 周期算比较保险 */ hsdram1.Init.WriteRecoveryTime = 2; /* tWR */ hsdram1.Init.RPDelay = 2; /* tRP */ hsdram1.Init.RCDDelay = 2; /* tRCD */这几个数字中RowCycleDelay最容易填小。填成 5 或 6 的时候，刷屏可能看起来正常，但一旦 emWin 开始大面积重绘，屏幕上就会偶尔冒出几条彩色雪花，这种偶发问题最难查。我一般宁可按 7 填，损失的那点带宽对 240x320 的界面来说完全感觉不到。
生成代码之后，先写一个验证函数，往 0xC0000000 开始的位置按半字写入递增数据再读回来比对：
/* 上电后第一件事：确认 SDRAM 每一个字节都能读写 */ static uint8_t SDRAM_Test(void) { volatile uint16_t *p = (volatile uint16_t *)0xC0000000; uint32_t i; for (i = 0; i < 0x400000; i++) { /* 8MB / 2，按半字遍历 */ p[i] = (uint16_t)i; } for (i = 0; i < 0x400000; i++) { if (p[i] != (uint16_t)i) { return 1; /* 返回 1 说明数据线或时序有问题 */ } } return 0; }这个测试跑一遍大概几百毫秒，放在MX_FMC_Init()之后、LTDC 初始化之前。如果它返回 1，就别再往下做了，先去查焊接和时序，硬件的读写都不稳定，GUI 层面上无论怎么调都是白费。
2.2 LTDC 与 ILI9341 时序：像素时钟必须按刷新率反算回来
屏是 240x320，RGB565 接口，LTDC 这边要配的是同步信号宽度、前后沿和像素时钟。总行周期 = 240 + HSYNC + HBP + HFP，总帧周期 = 320 + VSYNC + VBP + VFP。很多人习惯直接填厂商给的示例值，却忘了像素时钟要和刷新率匹配：时钟太高屏幕会闪，太低会出现肉眼可见的撕裂。
| 参数 | 取值 |
|---|---|
| HSYNC Width | 10 |
| Horizontal Back Porch | 20 |
| Horizontal Front Porch | 10 |
| VSYNC Width | 2 |
| Vertical Back Porch | 2 |
| Vertical Front Porch | 4 |
| 像素时钟 | 约 5.5 MHz |
按 60Hz 反算：总行 280，总帧 328，280 × 328 × 60 ≈ 5.5MHz。这个值在 CubeMX 的 LTDC 时钟树里不好直接配出来，常见做法是把 PLLSAI 的 N 和 R 调到接近值，实测不闪就行，不必精确到小数点。图层配置里颜色格式选 RGB565，显存地址指向 0xC0000000，也就是刚才验证过的那块。
/* LTDC 图层 0：单层 240x320，RGB565，帧缓冲直接落 SDRAM 起始 */ hltdc.Init.HorizontalSync = 9; /* 寄存器里填值减 1 */ hltdc.Init.VerticalSync = 1; hltdc.Init.AccumulatedHBP = 29; /* HSYNC + HBP - 1 */ hltdc.Init.AccumulatedVBP = 3; hltdc.Init.AccumulatedActiveW = 269; /* 加 240 像素宽 - 1 */ hltdc.Init.AccumulatedActiveH = 323; hltdc.Init.TotalWidth = 279; /* 总行 - 1 */ hltdc.Init.TotalHeigh = 327; /* 总帧 - 1 */ hltdc.LayerCfg[0].WindowX0 = 0; hltdc.LayerCfg[0].WindowX1 = 240; hltdc.LayerCfg[0].WindowY0 = 0; hltdc.LayerCfg[0].WindowY1 = 320; hltdc.LayerCfg[0].PixelFormat = LTDC_PIXEL_FORMAT_RGB565; hltdc.LayerCfg[0].FBStartAdress = 0xC0000000;寄存器里的值是“实际值减 1”，这一点 CubeMX 已经帮你做了，但我还是建议对着参考手册核一遍AccumulatedHBP和TotalWidth，这两个填错的直接后果就是画面整体偏左或者右边多出一条竖带。
2.3 FreeRTOS 任务划分与栈：GUI 和 LED 不能挤在同一个栈上
FreeRTOS 这边我一般只建三个任务：GUI 任务、LED 任务、一个空闲的监控任务（用来打印栈水位，调完可以删）。GUI 任务的栈要给足，因为 emWin 内部有递归调用，还要存窗口对象和字体信息，512 个字（2KB）是下限，我习惯给到 768 个字。
/* GUI 任务：初始化 emWin 并持续喂执行器 */ #define GUI_TASK_STACK_WORDS 768 #define GUI_TASK_PRIO (tskIDLE_PRIORITY + 3) /* LED 任务：只等通知，不碰任何 GUI 接口 */ #define LED_TASK_STACK_WORDS 128 #define LED_TASK_PRIO (tskIDLE_PRIORITY + 2) static TaskHandle_t hGuiTask = NULL; static TaskHandle_t hLedTask = NULL; void App_TasksCreate(void) { BaseType_t ret; ret = xTaskCreate(GuiTask, "GUI", GUI_TASK_STACK_WORDS, NULL, GUI_TASK_PRIO, &hGuiTask); configASSERT(ret == pdPASS); ret = xTaskCreate(LedTask, "LED", LED_TASK_STACK_WORDS, NULL, LED_TASK_PRIO, &hLedTask); configASSERT(ret == pdPASS); }创建任务时把句柄存到全局变量里是有意为之，因为按钮回调里要靠它给 LED 任务发通知。优先级方面，GUI 任务给高一点是常见做法：emWin 的重绘是流水线式的，一旦被别的任务抢走 CPU，界面上就会出现拖动窗口时卡顿、按钮按下去半天不响应的情况。
堆的大小在FreeRTOSConfig.h里由configTOTAL_HEAP_SIZE决定，F429 有 192KB 主 SRAM，去掉栈、全局变量和 DMA 缓冲区，留给 FreeRTOS 堆的通常在 40～64KB。这个值不要设得太大，设成 100KB 以上，链接阶段可能看不出来，运行时一创建任务就vApplicationMallocFailedHook。
2.4 时基和中断优先级：HAL 的 SysTick 必须让给 FreeRTOS
这是很多人遇到的第一个隐蔽问题。CubeMX 默认把 HAL 的时基源设成 SysTick，而 FreeRTOS 的调度心跳也走 SysTick。两者一起用，HAL_Delay()的计数值会被调度器打断，表现出来就是初始化阶段里随机的超时失败，比如 SDRAM 的等待循环、LCD 的上电延时，明明代码没改，换个编译选项又好了，很容易让人误以为是别的问题。
在 CubeMX 的SYS页面把 Timebase Source 从 SysTick 改成 TIM6，生成代码之后HAL_InitTick()会自动改用 TIM6 计数，FreeRTOS 独占 SysTick，两边互不干扰。
中断优先级也要一起设定。Cortex-M4 上有 4 位优先级，configPRIO_BITS填 4，然后：
| 中断 | 抢占优先级 | 说明 |
|---|---|---|
| SysTick（FreeRTOS） | 15 | 最低，允许被外设打断 |
| TIM6（HAL 时基） | 15 | 和调度器同级 |
| LTDC | 6 | 用于行中断，可关 |
| DMA2D | 7 | 传输完成回调 |
| USART1 | 8 | 调试打印 |
configMAX_SYSCALL_INTERRUPT_PRIORITY设成 5，也就是说数值小于 5 的中断不能调用 FreeRTOS 的 API。这条规则在 GUI 里同样适用：如果 LTDC 的行中断里想调用xSemaphoreGiveFromISR，优先级必须排在 5 之后。
3. 移植 STemWin：GUI_X_OS.c 里三处必须改的实现
骨架立住之后，才轮到把 STemWin 挂进来。STemWin 是随 STM32CubeF4 固件包一起分发的，解压后位于Middlewares/ST/STemWin，里面有Lib、Config、Inc三个目录。库是预编译的.a文件，按编译器分目录，Keil、IAR、GCC 各用各的，选项字节跑偏了不会报“找不到库”，而是链接时报一堆GUI_Init未定义。
3.1 目录结构一次摆对：把库和配置分开放
我习惯在工程根目录下建一个Middlewares/ST/STemWin，然后按下面的结构摆：
# 工程根目录下的中间件布局 Middlewares/ST/STemWin/ ├── Config/ # 需要自己改的配置，跟着工程走 │ ├── GUIConf.c │ ├── GUIConf.h │ ├── GUIDRV_Template.c │ ├── LCDConf.c │ └── GUI_X_OS.c ├── Inc/ # emWin 头文件，一般不改 │ ├── GUI.h │ ├── WM.h │ └── ... └── Lib/ └── STemWin540_CM4_Keil.a # 按编译器选，别混用Config目录放在工程自己的版本控制里，Lib和Inc直接从固件包拷过来不要修改，以后升级固件包时只需要替换这两个目录，不会把改动弄丢。
库的选择要说一句：M4 内核加 FPU 的版本和不带 FPU 的版本是分开的，DISC1 上的 F429 带单精度 FPU，但 FreeRTOS 的任务上下文切换默认不保存 FPU 寄存器，除非开了configENABLE_FPU。稳妥的做法是先选不带 FPU 的库，界面跑通之后想上浮点运算再换，换的时候记得同步检查__FPU_USED这个宏。
3.2 GUIConf.c 与 LCDConf.c：显存地址、颜色深度、堆大小
这两个文件决定了 emWin 能用多少内存、往哪儿画。先看 GUIConf：
/* GUIConf.h：只改这几个宏，其余保持默认 */ #define GUI_NUMBYTES (1024 * 1024) /* emWin 动态堆，1MB 起步 */ #define GUI_BLOCKSIZE 0x80 /* 内存块粒度，128 字节 */ #define GUI_SUPPORT_TOUCH 0 /* DISC1 没有触摸，关掉省空间 */ #define GUI_SUPPORT_MOUSE 0 #define GUI_WINSUPPORT 1 /* 用窗口管理器就必须开 */ #define GUI_SUPPORT_MEMDEV 0 /* 先不开，省显存也省堆 */GUI_NUMBYTES和实际使用的数组必须一致，这个数组在GUIConf.c里定义。默认它是static U32 aMemory[...]，直接放在内部 SRAM 里。1MB 的数组往 192KB 的 SRAM 里塞，链接器会直接报 region overflow；就算你把GUI_NUMBYTES改成 64KB 勉强塞进去，界面上一开窗口就会提示内存不足。正确的做法是把它移到 SDRAM：
/* 把 emWin 的堆数组钉到 .sdram 段，地址从 0xC0100000 开始 */ #define GUI_NUMBYTES (1024 * 1024) U32 aMemory[GUI_NUMBYTES / 4] __attribute__((section(".sdram"))); void GUI_X_Config(void) { GUI_ALLOC_AssignMemory(aMemory, GUI_NUMBYTES); GUI_ALLOC_SetAvBlockSize(GUI_BLOCKSIZE); }链接脚本里补一段，把.sdram段定位到 SDRAM 的第二个 MB 区，避开前面 150KB 的帧缓冲：
/* 链接脚本片段：SDRAM 分区，显存和 emWin 堆各占各的 */ MEMORY { FLASH (rx) : ORIGIN = 0x08000000, LENGTH = 2048K RAM (rwx) : ORIGIN = 0x20000000, LENGTH = 192K SDRAM (rwx) : ORIGIN = 0xC0100000, LENGTH = 7M } SECTIONS { .sdram (NOLOAD) : { . = ALIGN(4); *(.sdram) . = ALIGN(4); } > SDRAM }NOLOAD这个关键字不能少，否则链接器会生成一段初始化数据，启动时把 1MB 的零从 Flash 拷贝到 SDRAM，启动时间凭空多出好几百毫秒。用 Keil 的话对应的是.sct文件里加一个RW_IRAM3 0xC0100000 UNINIT的执行域，原理一样。
LCDConf.c 这边配的是颜色转换和显存驱动：
/* LCDConf.c：告诉 emWin 屏幕多大、用什么颜色格式、显存在哪 */ #define XSIZE_PHYS 240 #define YSIZE_PHYS 320 #define COLOR_CONVERSION GUICC_M565 /* RGB565 */ #define DISPLAY_DRIVER GUIDRV_LIN_16 /* 线性显存，16bpp */ #define NUM_BUFFERS 1 /* 先用单缓冲，稳定后再开双缓冲 */ #define GUI_VRAM_ADDR 0xC0000000 void LCD_X_Config(void) { GUI_DEVICE_CreateAndLink(DISPLAY_DRIVER, COLOR_CONVERSION, 0, 0); LCD_SetSizeEx(0, XSIZE_PHYS, YSIZE_PHYS); LCD_SetVSizeEx(0, XSIZE_PHYS, YSIZE_PHYS); LCD_SetVRAMAddrEx(0, (void *)GUI_VRAM_ADDR); }单缓冲在静态界面下完全够用，但它有一个代价：每次重绘时屏幕会短暂闪一下，因为 emWin 是直接往正在被 LTDC 扫描的那块内存里写。界面稳定之后如果想开启双缓冲，NUM_BUFFERS改 2，同时在链接脚本里预留第二块 150KB 的空间，emWin 会自动做翻页。
3.3 GUI_X_OS.c：互斥量、延时和空闲实现的三处改法
这个文件是 emWin 和 RTOS 之间的接口层，原版给的是裸机版本，GUI_X_Delay是个空循环。接 FreeRTOS 的时候要改的地方不多，但每一处都不能漏。
/* GUI_X_OS.c：emWin 与 FreeRTOS 的对接层 */ #include "GUI.h" #include "FreeRTOS.h" #include "semphr.h" #include "task.h" static SemaphoreHandle_t xGuiSemaphore = NULL; /* GUI_Init 内部会调用它，所以互斥量必须在这里建好 */ void GUI_X_InitOS(void) { xGuiSemaphore = xSemaphoreCreateMutex(); configASSERT(xGuiSemaphore != NULL); } void GUI_X_Lock(void) { /* 递归场景由 emWin 自己保证，这里用普通互斥量即可 */ xSemaphoreTake(xGuiSemaphore, portMAX_DELAY); } void GUI_X_Unlock(void) { xSemaphoreGive(xGuiSemaphore); } /* emWin 的时间基准，单位 ms，直接用调度器的 tick 换算 */ U32 GUI_X_GetTime(void) { return (U32)(xTaskGetTickCount() * portTICK_PERIOD_MS); } /* GUI_Delay 最终落到这里，必须真正让出 CPU */ void GUI_X_Delay(int Period) { if (Period > 0) { vTaskDelay(pdMS_TO_TICKS(Period)); } } /* 执行器空闲时的钩子，给个让出动作避免死循环占满 CPU */ void GUI_X_ExecIdle(void) { taskYIELD(); } /* 日志和错误钩子，调试阶段让它落到串口，量产可以关掉 */ void GUI_X_Log(const char *s) { (void)s; } void GUI_X_ErrorOut(const char *s){ (void)s; }GUI_X_Delay里那个if (Period > 0)的判断不是多余的。vTaskDelay(0)在 FreeRTOS 里的语义是“主动让出一次”，如果 emWin 内部有地方传 0 进来，会变成高频的上下文切换，整个系统的响应都会被拖慢。加上判断之后，传 0 就什么都不做。
GUI_X_GetTime的返回值要和GUI_X_Delay的单位保持一致，都按毫秒。如果portTICK_PERIOD_MS是 1，直接返回 tick 也行；如果为了省电把 tick 频率降到 100Hz，那这里就必须乘上 10，否则 emWin 里所有带超时的动画和窗口滚动都会慢十倍。
3.4 启动顺序：CRC 时钟和 GUI_Init 返回值是两个绕不开的前提
STM32 上的 STemWin 库在初始化时会做一次硬件校验，用的是芯片自带的 CRC 外设。如果 CRC 的时钟没开，GUI_Init要么返回 1，要么直接卡在某个内部循环里，而且没有任何提示。这个问题的隐蔽之处在于：CubeMX 默认不会自动打开 CRC，你得手动在RCC页面勾上 CRC 或者自己写一行使能。
/* main.c 里 GUI 初始化之前的准备动作 */ int main(void) { HAL_Init(); SystemClock_Config(); MX_GPIO_Init(); MX_DMA_Init(); MX_FMC_Init(); MX_LTDC_Init(); MX_DMA2D_Init(); MX_USART1_UART_Init(); __HAL_RCC_CRC_CLK_ENABLE(); /* 少了这一行，GUI_Init 会返回 1 */ App_TasksCreate(); /* 里面创建 GUI 任务，GUI_Init 在任务里做 */ vTaskStartScheduler(); while (1) { } }GUI_Init放在 GUI 任务里而不是main里，是为了让互斥量在调度器启动之后创建才有意义。调用的地方要判断返回值：
static void GuiTask(void *pvParameters) { int r; r = GUI_Init(); if (r != 0) { /* 返回值非 0 时，99% 是 CRC 时钟、堆内存或显存地址三者之一 */ printf("GUI_Init failed: %d\r\n", r); for (;;) { vTaskDelay(pdMS_TO_TICKS(1000)); } } CreateWindow(); /* GUIBuilder 导出的入口，下一章接上 */ for (;;) { GUI_Delay(10); /* 内部会调 GUI_Exec 处理重绘 */ } }循环里只写GUI_Delay(10)就够了，它内部已经包含GUI_Exec()。再手动加一句GUI_Exec()属于重复调用，虽然不会出错，但会让重绘的节奏变得不可控。10ms 这个值对应 100Hz 的界面刷新节拍，肉眼看着是连续的，CPU 占用也不算高。
4. GUIBuilder 出图：两个按钮的界面生成与代码落地
到这一步屏幕应该已经能刷出纯色了。接下来用 GUIBuilder 画界面。这个工具是 emWin 自带的，随库一起发布，界面上就那么几个控件，拖两个按钮、设一下坐标、导出 C 文件，活儿不重，重的是导出之后怎么和 FreeRTOS 的线程模型接上。
4.1 竖屏 240x320 下画两个按钮：坐标和字体的取舍
新建一个 Dialog，尺寸设成 240x320，背景色选GUI_BLACK或者深灰，这样在 LCD 上看起来对比度高一些。拖两个 BUTTON 上去，第一个放左上区域，第二个放它下面：
| 控件 | 名称 | X | Y | 宽 | 高 | 字体 |
|---|---|---|---|---|---|---|
| BUTTON | btLedOn | 40 | 90 | 160 | 50 | GUI_FONT_16B_ASCII |
| BUTTON | btLedOff | 40 | 170 | 160 | 50 | GUI_FONT_16B_ASCII |
字体这一项要克制。emWin 的字体是按点阵存的，一个 16 点阵的 ASCII 字体大概占 3～5KB Flash，看着不多，但 GUIBuilder 默认会给你挂上GUI_FONT_24B_1这种大字体，两个按钮加上标题，十几种字号一起进来，Flash 很快就会被占掉几十 KB。240x320 的屏幕用 16 点阵已经足够清楚，中文显示另外再说，需要的话单独加一个GUI_FONT_ZH_16之类的字库，别指望 ASCII 字体里能显示中文。
控件的 ID 在 GUIBuilder 的属性栏里能看到，默认是GUI_ID_BUTTON0和GUI_ID_BUTTON1。这两个名字会在回调里用来区分是谁被按了，导出之前确认一下，改名字比改代码省事。
4.2 导出的 WindowDLG.c 怎么塞进工程
点 File → Save As，存成WindowDLG.c，会同时生成一个WindowDLG.h。导出的文件里有三段东西：资源表、CreateWindow()入口、_cbDialog()回调。资源表里存的是控件的位置和初始属性，CreateWindow()负责把整个 Dialog 建出来，回调负责处理消息。
/* WindowDLG.c 里导出的骨架，只列关键部分 */ #include "DIALOG.h" #include "WindowDLG.h" /* 资源表：GUIBuilder 根据你拖的控件自动生成，别手改 */ static const GUI_WIDGET_CREATE_INFO _aDialogCreate[] = { { WINDOW_CreateIndirect, "MainWindow", 0, 0, 0, 240, 320, 0, 0 }, { BUTTON_CreateIndirect, "LED ON", GUI_ID_BUTTON0, 40, 90, 160, 50, 0, 0 }, { BUTTON_CreateIndirect, "LED OFF", GUI_ID_BUTTON1, 40, 170, 160, 50, 0, 0 }, }; static void _cbDialog(WM_MESSAGE * pMsg) { switch (pMsg->MsgId) { case WM_INIT_DIALOG: /* 界面建好之后的初始化，设字体、设初始文字都在这里 */ break; case WM_NOTIFY_PARENT: /* 按钮事件在这一支里处理，下一节展开 */ break; default: WM_DefaultProc(pMsg); break; } } WM_HWIN CreateWindow(void) { WM_HWIN hWin = GUI_CreateDialogBox(_aDialogCreate, GUI_COUNTOF(_aDialogCreate), &_cbDialog, WM_HBKWIN, 0, 0); return hWin; }工程里把WindowDLG.c加进编译列表，WindowDLG.h加到包含路径。有一个细节要注意：GUIBuilder 生成的代码默认假设你在裸机环境里跑，WM_INIT_DIALOG分支里不会有任何阻塞调用，这一点正好符合 FreeRTOS 的要求，别自己往里加延时。
GUI_CreateDialogBox的最后一个参数是父窗口句柄，传WM_HBKWIN表示以桌面为父窗口。如果后面要做多界面切换，这里改成传一个自定义的父句柄就行，界面会嵌在父窗口里而不是全屏铺开。
4.3 按钮回调里点灯：用任务通知把 GUI 线程和 LED 线程拆开
这是整篇文章里最容易写错的一段。直觉上的写法是在WM_NOTIFY_PARENT分支里直接HAL_GPIO_TogglePin()，能跑，但两个隐患立刻跟着来了：一是 GUI 线程的优先级最高，在它里面做硬件操作会拖慢重绘；二是如果以后 LED 要点亮后延时再灭，在回调里加vTaskDelay等于把整个 GUI 线程挂住，界面会直接卡死。
正确的拆法是回调里只发一个通知，LED 任务收到通知之后再去做实际的动作。
/* WindowDLG.c 里处理按钮消息的那一支 */ extern TaskHandle_t hLedTask; /* LED 任务的句柄，在任务创建时存下来的 */ case WM_NOTIFY_PARENT: { int id = WM_GetId(pMsg->hWinSrc); int evt = pMsg->Data.v; if (evt == WM_NOTIFICATION_RELEASED) { /* 松手才触发，避免按住连续响应 */ if (id == GUI_ID_BUTTON0) { xTaskNotifyGive(hLedTask); /* 通知 LED 任务：开灯 */ } else if (id == GUI_ID_BUTTON1) { xTaskNotifyGive(hLedTask); /* 同一个通知，靠后续逻辑区分 */ } } break; }WM_NOTIFICATION_RELEASED和WM_NOTIFICATION_CLICKED的区别要分清。CLICKED在按下的瞬间就触发，手指抖一下可能会连发好几次；RELEASED在松手时触发，一次按下加松手只算一次，对按钮控制 LED 这种场景更合适。
LED 任务这一侧：
/* LED 任务：阻塞等通知，收到之后做真正的硬件操作 */ static void LedTask(void *pvParameters) { uint32_t notifyCnt; uint8_t ledState = 0; for (;;) { /* 无限等待，直到 GUI 线程给出一个通知 */ notifyCnt = ulTaskNotifyTake(pdTRUE, portMAX_DELAY); if (notifyCnt > 0) { ledState = !ledState; /* 两个按钮共用一个翻转逻辑 */ if (ledState) { BSP_LED_On(LED3); /* DISC1 上 LED3 是 PG13 */ } else { BSP_LED_Off(LED3); } } } }ulTaskNotifyTake的第一个参数传pdTRUE表示取走通知时清零计数，第二个参数portMAX_DELAY表示一直阻塞。这样做的好处是 LED 任务在没人按按钮时完全不占 CPU，调度器根本不会把它调起来。
如果两个按钮要做不同的事，把方法换一下就行：定义一个全局的事件组，两个按钮各自置不同的位，LED 任务等事件组。事件组比任务通知多占一点内存，但可读性好，按钮数量多了之后维护起来更清爽。
4.4 按钮按下的手感：重绘时机和去抖的处理
GUIBuilder 生成的按钮默认没有按下效果，因为背景色和按下色都取的系统默认值。在WM_INIT_DIALOG里给两个按钮设一下颜色，按下去的时候能看到明显变化，操作就有了反馈：
case WM_INIT_DIALOG: { WM_HWIN hBtn; hBtn = WM_GetDialogItem(pMsg->hWin, GUI_ID_BUTTON0); BUTTON_SetText(hBtn, "LED ON"); BUTTON_SetFont(hBtn, &GUI_Font16B_ASCII); BUTTON_SetBkColor(hBtn, BUTTON_CI_UNPRESSED, GUI_DARKGRAY); BUTTON_SetBkColor(hBtn, BUTTON_CI_PRESSED, GUI_LIGHTGRAY); hBtn = WM_GetDialogItem(pMsg->hWin, GUI_ID_BUTTON1); BUTTON_SetText(hBtn, "LED OFF"); BUTTON_SetFont(hBtn, &GUI_Font16B_ASCII); BUTTON_SetBkColor(hBtn, BUTTON_CI_UNPRESSED, GUI_DARKGRAY); BUTTON_SetBkColor(hBtn, BUTTON_CI_PRESSED, GUI_LIGHTGRAY); break; }BUTTON_CI_UNPRESSED和BUTTON_CI_PRESSED这两个索引是按钮控件专用的，分别对应松开态和按下态。改这两个颜色不会触发整屏重绘，emWin 只会把按钮那一块区域标为无效，所以按下去的反应很快。
去抖方面，电阻屏和机械按键才需要考虑，DISC1 上没有触摸，按钮是 GUI 画的，本身不存在接触抖动的问题。真正需要注意的是连续快速点击：如果用户一秒点五次，LED 任务会被唤醒五次，灯的状态跟着翻五次，看起来就是全乱套。可以在 LED 任务里加一个最小间隔判断，两次动作之间间隔小于 50ms 的直接丢弃：
/* LED 任务里加一个时间窗，过滤掉连点 */ static TickType_t lastTick = 0; TickType_t now = xTaskGetTickCount(); if ((now - lastTick) < pdMS_TO_TICKS(50)) { continue; /* 间隔太短，视为抖动，丢掉这次 */ } lastTick = now;5. 排查与避坑：移植 STemWin 时我遇到的五个典型问题
下面这几条都是我在不同板子上真实遇到过的，每一条都按“现象、原因、解决”来写。
第一条：GUI_Init 返回 1，串口没有任何输出
现象是程序跑起来，屏幕黑的，用调试器看GUI_Init()的返回值是 1，串口没有打印任何东西。原因基本都是 CRC 外设时钟没开，STemWin 初始化时会用硬件 CRC 校验库的完整性，时钟没使能时校验直接失败。
解决：在GUI_Init()之前加__HAL_RCC_CRC_CLK_ENABLE();，或者在 CubeMX 的 RCC 配置里把 CRC 勾上。加完之后再跑，返回值应该是 0。
第二条：GUI_Init 还是返回 1，但这次串口有输出
现象是串口上能看到GUI: Not enough memory之类的字样，GUI_Init返回 1。原因是GUI_NUMBYTES设了 1MB，但aMemory数组没有真正放到 SDRAM 里，链接器把它塞进了内部 SRAM，实际可用空间远小于声明值。
解决：确认aMemory数组带了__attribute__((section(".sdram")))，并在 map 文件里查一下它的实际地址是不是落在 0xC0100000 附近。Keil 用户的.sct文件里要有UNINIT的执行域，否则链接器会警告段放不下。
第三条：屏幕有背光但全黑，或者满屏雪花噪点
现象是屏幕背光亮着，但内容一直是黑的；或者能看到一些彩色噪点，内容模模糊糊。原因有两个方向：一是 LTDC 的像素时钟配得太高，SDRAM 的带宽吃不消；二是 SDRAM 的时序参数填小了一两个周期，平时看不出来，一旦 LTDC 开始高频读取显存就暴露了。
解决：先把RowCycleDelay和RPDelay各加 1 周期，再把像素时钟降到 5MHz 附近试一次。如果雪花消失，就说明是时序问题，慢慢往上回调找到稳定点。另外确认SDRAM_Test在 LTDC 初始化之前跑通过了，硬件读写本身就不可靠的话，先解决硬件问题。
第四条：一进 main 就 HardFault，或者跑几秒钟死机
现象是程序下载进去，跑一小会儿就进HardFault_Handler，用调试器看栈指针已经越过 0x20030000。原因是configTOTAL_HEAP_SIZE设得太大，加上 GUI 任务的 2KB 栈和几个缓冲区，内部 SRAM 被占满，栈溢出之后覆盖了相邻的变量。
解决：把configTOTAL_HEAP_SIZE降到 48KB 左右试一次，同时在FreeRTOSConfig.h里打开configCHECK_FOR_STACK_OVERFLOW设为 2，实现vApplicationStackOverflowHook，把出问题的任务名打印出来。另外确认GUI_NUMBYTES的那 1MB 确实在 SDRAM 里，没占着 SRAM 的位置。
第五条：按钮点几次就没反应，或者点了之后整个界面卡住
现象是开始点两下还正常，点三五次之后按钮就变僵硬，界面不再刷新；或者按下按钮之后 LED 亮了，但界面从此不再响应。原因是在 GUI 回调里调用了GUI_Delay()或者GUI_Exec()。GUI_Delay内部会尝试获取互斥量，而回调本身已经在锁的保护下执行，同一个任务重复获取普通互斥量就是死锁。
解决：回调里只做状态记录和通知发送，任何延时、等待、刷新的动作都交给 GUI 任务的主循环。如果确实需要在按钮之后弹一个动画，用WM_CreateTimer创建定时器，让 emWin 自己在主循环里驱动，不要在回调里手写延时。
6. 装完怎么验证：从第一帧到按钮压测的完整检查
界面能亮不等于装好了，我一般按下面的顺序走一遍验证，每一步都有明确的通过标准，免得后面出问题时不知道是哪一层不达标。
第一步验证显存和驱动。在 GUI 任务里GUI_Init()成功之后，先做一个纯色填充和清屏的测试：
/* 上电自检：确认 emWin 能真正控制显存，不只是返回成功 */ static void GuiSelfTest(void) { GUI_SetBkColor(GUI_BLACK); GUI_Clear(); GUI_SetColor(GUI_WHITE); GUI_SetFont(&GUI_Font16B_ASCII); GUI_DispStringHCenterAt("STemWin Ready", 120, 40); /* 画一个边框，正好贴着屏幕边缘，用来检查时序是否对齐 */ GUI_SetColor(GUI_GREEN); GUI_DrawRect(0, 0, 239, 319); GUI_Delay(500); /* 停半秒让人看清，然后清掉 */ GUI_Clear(); }通过标准：文字在屏幕水平居中，绿色边框四条边都在可视区域内，不会出现右边缺一条或者下边被裁掉。如果边框右边看不到，基本可以确定TotalWidth或AccumulatedHBP差了几个像素。
第二步验证内存。在GUI_Init()之后调用GUI_ALLOC_GetNumFreeBytes()，把剩余堆打印出来：
/* 打印 emWin 堆的剩余量，创建窗口前后各来一次，差值就是界面的开销 */ printf("emWin free before: %lu\r\n", GUI_ALLOC_GetNumFreeBytes()); CreateWindow(); printf("emWin free after : %lu\r\n", GUI_ALLOC_GetNumFreeBytes());通过标准：创建窗口前后的差值在几十 KB 这个量级，剩余量还有几百 KB。如果差值是几 MB，说明GUI_NUMBYTES设得离谱，或者某个控件反复创建没有释放。
第三步验证任务栈水位。监控任务里定期打印：
/* 运行 5 分钟后打印一次，看 GUI 任务的栈还剩多少 */ printf("GUI stack high water: %u words\r\n", uxTaskGetStackHighWaterMark(hGuiTask));通过标准：剩余量大于 100 个字。如果只剩几十个字，说明GUI_TASK_STACK_WORDS给少了，把 768 加到 1024 再观察。
第四步是按钮压测。这一步最能暴露问题。用调试器写一个脚本，或者干脆手动快速点，两个按钮交替点，每个点 100 次以上，观察三点：
| 观察项 | 通过标准 | 不通过说明 |
|---|---|---|
| LED 翻转次数 | 和点击次数一致，不漏不多 | 任务通知被覆盖或回调没进 |
| 界面刷新 | 始终流畅，无卡顿 | 回调里做了阻塞操作 |
| 内存剩余 | 压测前后基本不变 | 每次点击都在泄漏内存 |
压测跑完之后再看一眼GUI_ALLOC_GetNumFreeBytes()的返回值，如果比压测前少了几十 KB 还没涨回来，那就是回调里创建了没有释放的对象，这种泄漏在短时间演示里看不出来，跑一晚上必挂。
最后一步是长时间跑。让它连续运行半小时，界面上的两个按钮各被点过几百次，同时用串口每隔十秒打印一次栈水位和堆剩余。真正稳定的工程，这两个数字在半小时里应该是平的，如果曲线是锯齿状往下走，那就还有地方在漏。
从那以后我每次移植 STemWin，不管多急，都强制先跑一遍 SDRAM 读写测试，再跑一遍纯色填充，最后才允许自己往上面加窗口。这两个看起来“多余”的步骤加起来不到一分钟，却能省掉后面几个小时的盲猜。希望帮到你。
本文还有配套的精品资源，点击获取
