简介本资源是一份基于emWin图形库实现的嵌入式全功能软键盘组件面向嵌入式开发工程师及GUI初学者解决在无操作系统或RTOS环境下为MCU设备快速集成字符输入界面的核心需求。压缩包共2个文件1个C源码文件、1个头文件总大小仅4KB轻量紧凑其中Keyboard.c封装了键盘布局、按键响应与字符输入逻辑Keyboard.h定义了控件接口、结构体及配置常量适配480×272分辨率显示屏含输入窗口与完整按键映射可直接用于设置菜单、登录界面等交互场景。已有569人学习下载资源代码结构清晰、注释完备无需额外依赖即可编译运行是理解emWin控件定制机制、掌握嵌入式UI事件处理与屏幕刷新流程的典型实践范例。1. EMWIN 键盘组件不是插件而是嵌入式 GUI 中必须重写的交互层你在 STM32F407 Segger EMWIN 5.32 工程里拖进一个Keyboard.c文件编译通过、界面弹出——但按下任意键无响应WM_KEY_ENTERED消息永远不触发。这不是配置漏了而是你误把“键盘”当成 EMWIN 自带控件EMWIN 官方库根本不提供可直接调用的软键盘或物理键盘驱动模块。所有Keyboard.rar包里流传的Keyboard.c/h本质是开发者为特定硬件如 4×4 矩阵键盘、USB HID 键盘、SPI 触摸屏外挂按键手动实现的 WM 消息桥接层。它要完成三件事扫描硬件按键状态 → 转换为 EMWIN 可识别的KEY_xxx常量 → 通过WM_SendMessage()注入到目标窗口。适合正在移植矩阵键盘到 EMWIN 的嵌入式工程师尤其当你已跑通GUI_Init()和WM_Init()却卡在“按钮能画出来、按不动”的阶段。本文不讲原理图设计只聚焦如何让KEY_SPACE真正触发WM_KEY_PRESSED回调。2. 从 Keyboard.rar 解包到 EMWIN 键盘消息链路的完整映射Keyboard.rar是国内嵌入式社区长期流传的 EMWIN 键盘适配压缩包内含Keyboard.c、Keyboard.h、keyboard_bg.bmp等文件。它并非 Segger 官方发布而是基于 EMWIN 5.20–5.38 版本反向工程的实践封装。其核心价值在于将硬件扫描逻辑与 EMWIN 消息循环解耦你只需修改KEYBOARD_Scan()函数读取 GPIO 状态其余消息构造、焦点管理、字符映射均由Keyboard.c内部完成。下面拆解其工作流并给出可立即验证的最小化改造路径。2.1 Keyboard.rar 的真实结构与依赖关系Keyboard.rar解压后典型目录结构如下/Keyboard/ ├── Keyboard.h // 定义 KEYBOARD_CONFIG 结构体、KEY_xxx 枚举、API 函数声明 ├── Keyboard.c // 主实现扫描、去抖、消息发送、背景绘制 ├── keyboard_bg.bmp // 16 色 BMP 格式软键盘背景图需用 GUI_DrawBitmap() 加载 └── demo_main.c // 示例在 WM_CreateWindow() 后调用 KEYBOARD_Create()提示keyboard_bg.bmp必须为 16 色4bpp、尺寸严格匹配KEYBOARD_WIDTH/HEIGHT宏定义默认 320×240否则GUI_DrawBitmap()报错GUI_ERR_INVALID_PARAM。使用 GIMP 导出时选择「索引颜色 → 最大 16 种」并勾选「写入颜色表」。Keyboard.h中最关键的定义是KEYBOARD_CONFIG结构体它决定了硬件连接方式typedef struct { GUI_COLOR BkColor; // 背景色当无 BMP 图时生效 int xSize; // 键盘宽度像素 int ySize; // 键盘高度像素 int KeyWidth; // 单键宽度像素 int KeyHeight; // 单键高度像素 void (*pfScan)(U16*); // 扫描函数指针填入 U16 数组bit0~bit15 对应 KEY_0~KEY_15 } KEYBOARD_CONFIG;注意pfScan参数类型为U16*—— 这意味着它期望你传入一个 16 位掩码数组每个 bit 表示一个键是否按下。这与常见 4×4 矩阵键盘的 16 键布局天然匹配。2.2 在 STM32 HAL 库中实现 pfScan以 4×4 矩阵键盘为例假设你的矩阵键盘接在 STM32F407 的 GPIOA行和 GPIOB列采用标准行列反转法扫描。以下代码可直接替换Keyboard.c中的KEYBOARD_ScanDefault()函数#include stm32f4xx_hal.h #include Keyboard.h // 行线PA0~PA3列线PB0~PB3 #define ROW_PORT GPIOA #define COL_PORT GPIOB #define ROW_PIN(x) (1U (x)) // PA00x0001, PA10x0002... #define COL_PIN(x) (1U (x)) // PB00x0001, PB10x0002... static void _SetRowOutput(uint8_t row) { HAL_GPIO_WritePin(ROW_PORT, ROW_PIN(0), GPIO_PIN_SET); HAL_GPIO_WritePin(ROW_PORT, ROW_PIN(1), GPIO_PIN_SET); HAL_GPIO_WritePin(ROW_PORT, ROW_PIN(2), GPIO_PIN_SET); HAL_GPIO_WritePin(ROW_PORT, ROW_PIN(3), GPIO_PIN_SET); HAL_GPIO_WritePin(ROW_PORT, ROW_PIN(row), GPIO_PIN_RESET); } static uint8_t _ReadCol(void) { uint8_t col 0; if (HAL_GPIO_ReadPin(COL_PORT, COL_PIN(0)) GPIO_PIN_RESET) col | 0x01; if (HAL_GPIO_ReadPin(COL_PORT, COL_PIN(1)) GPIO_PIN_RESET) col | 0x02; if (HAL_GPIO_ReadPin(COL_PORT, COL_PIN(2)) GPIO_PIN_RESET) col | 0x04; if (HAL_GPIO_ReadPin(COL_PORT, COL_PIN(3)) GPIO_PIN_RESET) col | 0x08; return col; } void KEYBOARD_ScanMatrix(U16* pKeys) { static uint16_t last_state 0; uint16_t current 0; uint8_t row, col; for (row 0; row 4; row) { _SetRowOutput(row); HAL_Delay(1); // 去抖延时 col _ReadCol(); if (col) { // col 的 bit0~bit3 对应列 0~3row 为行号计算键索引row*4 col_bit_pos for (uint8_t bit 0; bit 4; bit) { if (col (1 bit)) { uint8_t key_index row * 4 bit; current | (1U key_index); } } } } // 简单边沿检测仅在按键按下瞬间置位避免长按重复触发 uint16_t edges current (~last_state); *pKeys edges; last_state current; }参数说明与关键点HAL_Delay(1)是硬件去抖最低要求若按键机械抖动严重可增至HAL_Delay(5)但会降低响应速度edges current (~last_state)实现下降沿触发确保每个按键只产生一次KEY_xxx消息符合 EMWIN 消息模型key_index计算必须与KEYBOARD.h中KEY_0到KEY_15的顺序严格一致默认KEY_0对应左上角键此函数返回的是 16 位掩码Keyboard.c内部会自动将其转换为WM_KEY_PRESSED消息并发送给当前焦点窗口。2.3 将 Keyboard 绑定到 EMWIN 窗口必须显式设置焦点EMWIN 键盘消息不会自动广播它只发给当前具有输入焦点的窗口。这是新手最常忽略的环节。你需要在创建窗口后显式调用WM_SetFocus(hWin)并确保该窗口支持键盘输入// 在你的主窗口回调函数中添加 KEY 消息处理 static void _cbMain(WM_MESSAGE * pMsg) { switch (pMsg-MsgId) { case WM_KEY: { WM_KEY_INFO* pInfo (WM_KEY_INFO*)pMsg-Data.p; if (pInfo-Key KEY_SPACE) { GUI_DispStringAt(SPACE PRESSED!, 10, 100); } } break; default: WM_DefaultProc(pMsg); } } // 创建窗口后立即设焦点 hMainWin WM_CreateWindowAsChild(0, 0, 800, 480, hParent, WM_CF_SHOW, _cbMain, 0); WM_SetFocus(hMainWin); // 关键无此句Keyboard 消息永不送达 // 创建键盘实例需先初始化 EMWIN KEYBOARD_CONFIG Config {0}; Config.xSize 320; Config.ySize 240; Config.KeyWidth 80; Config.KeyHeight 60; Config.BkColor GUI_BLACK; Config.pfScan KEYBOARD_ScanMatrix; // 指向你实现的扫描函数 hKeyboard KEYBOARD_Create(Config, 0, 240, 320, 240); // 坐标 (0,240) 避开主窗口注意KEYBOARD_Create()返回的hKeyboard是一个普通 WM 窗口句柄它本身不接收WM_KEY消息——它的作用只是周期性调用pfScan并转发按键事件。真正的消息接收者是你用WM_SetFocus()指定的那个窗口。3. Keyboard.c 的三大必调参数与消息路由机制解析Keyboard.c的行为由三个宏和一个全局变量控制它们直接决定按键是否被识别、如何映射、是否触发重复。修改这些参数前必须理解其在 EMWIN 消息链路中的位置硬件扫描 → KEYBOARD_Scan() → KEYBOARD__SendKey() → WM_SendMessage(hFocus, WM_KEY, ...)。任何一环断开键盘即失效。3.1 KEYBOARD_POLL_PERIOD决定扫描频率的毫秒级定时器Keyboard.c使用WM_SetTimer()创建一个周期性扫描定时器默认周期为KEYBOARD_POLL_PERIOD通常定义为50。这意味着每 50ms 调用一次pfScan函数读取硬件状态。// 在 Keyboard.c 开头查找并修改此宏 #ifndef KEYBOARD_POLL_PERIOD #define KEYBOARD_POLL_PERIOD 50 // 单位毫秒 #endif参数影响分析值响应速度CPU 占用适用场景20极快20ms 延迟高50Hz 中断触摸屏外挂硬按键要求实时反馈50平衡推荐中等大多数矩阵键盘、USB HID 键盘100明显延迟低低功耗模式按键不频繁的工业 HMI验证方法在KEYBOARD_ScanMatrix()开头添加GUI_DispDecAt(HAL_GetTick(), 10, 50, 3);观察刷新频率是否与KEYBOARD_POLL_PERIOD一致。若不一致检查WM_SetTimer()是否被其他定时器抢占。3.2 KEYBOARD_KEY_MAP将硬件键码映射为 EMWIN 标准键值KEYBOARD_KEY_MAP是一个静态数组定义了KEY_0到KEY_15如何转换为KEY_xxx常量如KEY_A,KEY_0,KEY_ENTER。默认映射为数字键盘布局static const U16 _aKeyMap[16] { KEY_0, KEY_1, KEY_2, KEY_3, KEY_4, KEY_5, KEY_6, KEY_7, KEY_8, KEY_9, KEY_STAR, KEY_HASH, KEY_ENTER, KEY_ESC, KEY_BACKSPACE, KEY_SPACE };修改示例将左上角键KEY_0映射为KEY_F1static const U16 _aKeyMap[16] { KEY_F1, KEY_1, KEY_2, KEY_3, // 修改第一项 KEY_4, KEY_5, KEY_6, KEY_7, KEY_8, KEY_9, KEY_STAR, KEY_HASH, KEY_ENTER, KEY_ESC, KEY_BACKSPACE, KEY_SPACE };关键约束所有KEY_xxx常量必须来自GUI.hEMWIN 5.32 中定义约 120 个标准键KEY_F1~KEY_F12、KEY_CTRL、KEY_SHIFT等修饰键不会自动触发组合逻辑EMWIN 不处理键修饰状态需在WM_KEY回调中自行判断若映射了KEY_TAB需确保目标窗口支持 Tab 导航即WM_SetCreateFlags(WM_CF_FOCUSABLE)。3.3 KEYBOARD_REPEAT_ENABLE 与 KEYBOARD_REPEAT_DELAY长按重复发送开关当用户长按某个键时Keyboard.c默认启用重复发送机制。其行为由两个参数控制#define KEYBOARD_REPEAT_ENABLE 1 // 1启用长按重复0禁用 #define KEYBOARD_REPEAT_DELAY 500 // 首次重复延迟ms #define KEYBOARD_REPEAT_PERIOD 80 // 后续重复间隔ms工作流程按下键 → 立即发送WM_KEYKeyState KEY_STATE_PRESSED持续按下 ≥KEYBOARD_REPEAT_DELAY→ 发送第二次WM_KEY此后每KEYBOARD_REPEAT_PERIODms 发送一次直到松开松开 → 发送WM_KEYKeyState KEY_STATE_RELEASED。排查长按失效检查KEYBOARD_REPEAT_ENABLE是否为1在KEYBOARD__SendKey()函数中添加日志GUI_DispStringAt(REPEAT, 10, 150);确认是否进入重复分支若KEYBOARD_REPEAT_DELAY设为0会导致首次重复立即触发可能被 UI 逻辑忽略。4. 调试 Keyboard 消息流的四步验证法从硬件到应用层当键盘“看起来正常但没反应”问题往往分布在消息链路的不同层级。不要盲目改代码按以下顺序逐层验证每步耗时不超过 2 分钟4.1 硬件层验证用万用表确认 GPIO 电平变化这是最常被跳过的步骤。用万用表测量矩阵键盘行线如 PA0在按下键时是否从高电平3.3V变为低电平0V若无变化检查 GPIO 初始化GPIO_MODE_OUTPUT_PP/GPIO_MODE_INPUT_PU设置是否正确若变化但不稳定增加硬件去抖电容100nF 并联在按键两端若所有行线始终为高确认HAL_GPIO_WritePin()调用是否被优化掉加__IO修饰符或关闭编译器优化。4.2 扫描层验证在 KEYBOARD_ScanMatrix() 中打印原始键码在KEYBOARD_ScanMatrix()函数末尾插入调试输出GUI_DispDecAt(*pKeys, 10, 200, 4); // 显示 16 位掩码的十进制值按下左上角键 → 应显示1bit0 置位按下右下角键 → 应显示32768bit15 置位若显示0说明pfScan未正确读取硬件回到第 4.1 步若显示655350xFFFF说明所有键被同时识别检查行列线是否接反或短路。4.3 消息层验证拦截 WM_KEY 消息确认是否送达在目标窗口的回调函数_cbMain()中添加全量消息日志case WM_KEY: { WM_KEY_INFO* pInfo (WM_KEY_INFO*)pMsg-Data.p; char buf[32]; sprintf(buf, KEY:0x%04X STATE:%d, pInfo-Key, pInfo-KeyState); GUI_DispStringAt(buf, 10, 250); } break;按下键 → 屏幕显示KEY:0x0020 STATE:1KEY_SPACE的十六进制值为0x0020若无显示确认WM_SetFocus(hMainWin)已执行且hMainWin未被其他窗口遮挡若显示KEY:0x0000说明KEYBOARD_KEY_MAP映射错误返回了无效键值。4.4 应用层验证检查 WM_KEY 回调是否被 WM_DefaultProc() 吞掉EMWIN 的WM_DefaultProc()会处理部分标准消息如WM_PAINT但不会处理WM_KEY。如果你的回调函数末尾写了default: WM_DefaultProc(pMsg); // ❌ 错误这会导致 WM_KEY 被忽略必须改为default: WM_DefaultProc(pMsg); break; // ✅ 确保 break 存在防止 fall-through更安全的写法是显式处理所有已知消息避免default分支case WM_KEY: // 处理逻辑 break; case WM_PAINT: // 绘制逻辑 break; // ... 其他 case default: WM_DefaultProc(pMsg); break;5. 在 EMWIN 中实现虚拟键盘与物理键盘共存的双输入通道实际项目中你常需要同时支持触摸屏软键盘KEYBOARD_Create()和 USB HID 物理键盘如狼蛛 F87。二者不能简单叠加因为 EMWIN 的WM_SetFocus()只能指向一个窗口而物理键盘事件默认发往系统焦点软键盘则主动发送消息。解决方案是建立统一的消息分发中心让两种输入源都通过同一接口注入。5.1 物理键盘接入基于 USB Host 的 HID 解析STM32F407 通过 USB OTG FS 接入 HID 键盘需启用USBD_HID类。关键步骤是解析 HID 报文中的KEYCODE字段// 在 USBD_HID_EventCallback() 中处理 void USBD_HID_EventCallback(USBD_HandleTypeDef *pdev, uint8_t event) { if (event USBD_HID_EVENT_DATA_RECEIVED) { uint8_t *pBuf hUsbDeviceFS.pClassData; // pBuf[2] 是第一个按键码HID 协议规定 if (pBuf[2] ! 0) { U16 emwin_key _HIDToEMWINKey(pBuf[2]); if (emwin_key) { // 直接模拟 Keyboard.c 的发送逻辑 WM_KEY_INFO KeyInfo {0}; KeyInfo.Key emwin_key; KeyInfo.KeyState KEY_STATE_PRESSED; WM_SendMessageNoPara(WM_GetFocussedWindow(), WM_KEY); // 注意此处需自行维护 KeyStateHID 不提供释放事件 } } } } U16 _HIDToEMWINKey(uint8_t hid_code) { static const U16 _HIDMap[128] {0}; // 填充 HID Usage ID 到 EMWIN KEY_xxx 的映射表 if (hid_code 128) return _HIDMap[hid_code]; return 0; }注意HID 键盘报文不包含按键释放事件需用定时器检测pBuf[2]变为0后发送KEY_STATE_RELEASED否则长按会卡死。5.2 统一消息分发创建 KEYBOARD_DISPATCHER 管理双通道定义一个全局分发器屏蔽底层差异typedef enum { INPUT_SOURCE_PHYSICAL, INPUT_SOURCE_VIRTUAL } INPUT_SOURCE; void KEYBOARD_Dispatch(U16 emwin_key, U8 key_state, INPUT_SOURCE src) { static WM_HWIN hLastFocus 0; static U8 last_key 0; // 防止重复发送相同键HID 可能连续上报 if (emwin_key last_key key_state KEY_STATE_PRESSED) return; last_key emwin_key; WM_HWIN hFocus WM_GetFocussedWindow(); if (hFocus 0) return; WM_KEY_INFO Info {0}; Info.Key emwin_key; Info.KeyState key_state; WM_SendMessage(hFocus, WM_KEY, (int)Info); }然后在KEYBOARD_ScanMatrix()和USBD_HID_EventCallback()中均调用KEYBOARD_Dispatch(key, KEY_STATE_PRESSED, src)彻底解耦输入源与业务逻辑。5.3 键盘布局动态切换用 GUI_PID_STATE_CHANGED 实现模式切换用户可能需要在“数字键盘”和“QWERTY 键盘”间切换。利用 EMWIN 的触摸 PID 事件在软键盘上添加切换按钮case WM_TOUCH: { WM_PID_STATE_CHANGED_INFO* pInfo (WM_PID_STATE_CHANGED_INFO*)pMsg-Data.p; if (pInfo-Pressed) { if (_IsInRect(pInfo-x, pInfo-y, 280, 0, 40, 40)) { // 右上角切换按钮区域 _bQwertyMode !_bQwertyMode; KEYBOARD_Invalidate(); // 触发重绘 } } } break;在KEYBOARD__Paint()中根据_bQwertyMode加载不同keyboard_bg.bmp并更新KEYBOARD_KEY_MAP数组实现零重启切换。最后验证技巧在KEYBOARD_Dispatch()开头添加GUI_SetColor(GUI_RED); GUI_DispStringAt(PHYSICAL, 10, 300);按下物理键盘时红字出现点击软键盘时消失——证明双通道已隔离且可控。本文还有配套的精品资源点击获取