在实际客制化键盘项目中单色LED灯效和单色OLED屏幕已经不能满足玩家对个性化和信息展示的深度需求。当一把键盘同时集成了可编程的点阵屏和全彩TFT屏幕时它就不再仅仅是输入工具而成为了一个高度可定制化的桌面信息中心和交互终端。LEOBOG AMG65正是这样一款面向硬核玩家的客制化套件其双屏设计——一块用于显示系统状态或动画的点阵屏加上一块可显示丰富图文信息的TFT彩屏——将客制化的可能性提升到了新的维度。对于开发者、极客和资深玩家而言这意味着你需要掌握从硬件驱动、图形库调用到自定义逻辑编写的一系列技能。本文将以LEOBOG AMG65或其类似的双屏客制化方案为背景带你从零理解如何为这类键盘编程包括环境搭建、固件编译、双屏驱动、图形绘制以及按键映射与宏定义的深度定制。你将学习到如何将一块ESP32或类似微控制器与点阵屏、TFT屏协同工作并编写出属于自己的个性化固件。1. 理解客制化键盘的双屏架构与核心组件在开始动手之前必须厘清这类键盘的硬件架构和软件栈。这决定了后续开发环境的配置和代码编写的方向。1.1 硬件架构解析主控、点阵屏与TFT屏典型的双屏客制化键盘如概念中的AMG65其核心硬件通常包含三部分主控微控制器MCU这是键盘的大脑负责扫描按键矩阵、处理USB HID通信、驱动两块屏幕并执行用户逻辑。常见的选择是ESP32-S3、RP2040或STM32系列。ESP32-S3因其强大的处理能力、丰富的IO口和内置蓝牙/Wi-Fi而备受青睐适合处理复杂的图形和网络功能。点阵屏LED Matrix通常由多个8x8的LED点阵模块拼接而成例如4个模块组成16x32的点阵屏。它通过行列扫描方式驱动用于显示简单的图标、动画、系统状态如Caps Lock、Num Lock或自定义像素画。通信接口常见为SPI或I2C。TFT彩屏TFT LCD一块小尺寸如1.14寸、1.3寸的彩色液晶屏分辨率常见为240x135或240x240。它通过SPI接口与主控通信可以显示丰富的色彩、图片、文字和图表。常用的驱动芯片是ST7789或ILI9341。这三者通过PCB连接主控的GPIO引脚分别连接到按键矩阵、点阵屏的驱动芯片和TFT屏的驱动芯片。1.2 软件栈与固件框架选择为这样的硬件编写固件我们不会从零开始写USB HID驱动和屏幕驱动而是依赖于成熟的客制化键盘固件框架。目前主流的选择是QMK Firmware最老牌、生态最完善的键盘固件框架支持海量MCU和硬件。其对复杂屏幕尤其是TFT屏的原生支持在不断完善中但需要较多的底层配置和移植工作。KMK (CircuitPython)基于CircuitPython使用Python编写固件开发体验友好易于快速原型开发对屏幕驱动有较好的库支持。ZMK专注于无线蓝牙键盘的固件对ESP32等支持良好但其图形子系统相对较新对复杂TFT屏的支持可能需要社区方案。对于涉及双屏特别是TFT彩屏的复杂项目QMK因其强大的底层控制能力和庞大的社区资源通常是深度客制化的首选。本文将主要围绕QMK框架展开因为它能提供最彻底的控制权。2. 搭建QMK开发环境与准备项目在编写任何代码之前一个正确配置的本地开发环境是必不可少的。2.1 安装QMK MSYSWindows或配置QMK环境macOS/LinuxQMK官方推荐使用QMK MSYS来管理Windows下的开发环境它集成了编译所需的工具链。下载安装访问QMK官方文档下载并安装QMK MSYS。初始化打开QMK MSYS终端运行以下命令来克隆QMK固件仓库并安装依赖qmk setup此命令会引导你完成初始设置通常选择默认选项即可。它会将固件源码克隆到~/qmk_firmware在MSYS的家目录下。对于macOS和Linux用户可以通过包管理器如Homebrew, apt安装依赖然后直接克隆仓库。2.2 为你的键盘创建项目结构QMK的每个键盘都有一个对应的目录。我们需要为“AMG65”创建一个新的键盘定义。进入QMK目录cd ~/qmk_firmware创建键盘目录和关键文件 QMK的键盘按“厂商”和“型号”组织。我们可以创建一个新厂商或使用现有厂商如leobog。mkdir -p keyboards/leobog/amg65 cd keyboards/leobog/amg65创建必要的配置文件rules.mk 启用或禁用功能如RGB灯光、屏幕驱动。config.h 硬件引脚定义、功能配置。amg65.c 键盘初始化、屏幕初始化等自定义代码。keymaps/default/keymap.c 默认键位定义。info.json VIA/VIAL等可视化配置工具使用的布局描述文件可选但推荐。3. 硬件引脚定义与双屏驱动配置这是最关键的一步需要根据你的实际PCB原理图将主控的GPIO引脚正确映射到各个硬件组件。3.1 定义按键矩阵在config.h中首先定义按键矩阵的行和列。假设AMG65是65%配列有一个6x15的矩阵。// config.h #pragma once #define MATRIX_ROWS 6 #define MATRIX_COLS 15 // 定义行和列对应的GPIO引脚编号需要根据原理图修改 #define MATRIX_ROW_PINS { GP0, GP1, GP2, GP3, GP4, GP5 } #define MATRIX_COL_PINS { GP6, GP7, GP8, GP9, GP10, GP11, GP12, GP13, GP14, GP15, GP16, GP17, GP18, GP19, GP20 }注意GPIO编号如GP0是RP2040的命名方式。如果使用ESP32-S3则需要使用其对应的GPIO数字如GPIO_NUM_1。务必查阅你的主控芯片数据手册和键盘PCB原理图。3.2 配置点阵屏驱动QMK通过LED_MATRIX功能来驱动点阵屏。首先在rules.mk中启用它# rules.mk LED_MATRIX_ENABLE yes LED_MATRIX_DRIVER IS31FL3731 # 示例驱动芯片需根据实际芯片修改常见的点阵屏驱动芯片还有IS31FL3733、IS31FL3737或软件扫描的CUSTOM。然后在config.h中配置引脚和布局// config.h #ifdef LED_MATRIX_ENABLE #define LED_MATRIX_LED_COUNT 128 // 假设是16x32点阵共512个LED这里需要精确计算。128是示例。 #define LED_MATRIX_ROWS 16 // 点阵屏物理行数 #define LED_MATRIX_COLS 32 // 点阵屏物理列数 // 定义驱动芯片的I2C地址和引脚如果是I2C接口 #define IS31FL3731_I2C_ADDRESS_1 IS31FL3731_I2C_ADDRESS_GND #define I2C1_SCL_PIN GP22 #define I2C1_SDA_PIN GP23 #endif3.3 配置TFT彩屏驱动TFT彩屏的驱动相对复杂QMK没有完全内置的通用TFT驱动但可以通过GRAPHICS_ENABLE和自定义graphics.c文件或者利用社区驱动如lib/glcdfont.c和自定义绘图函数来实现。一种更直接的方法是使用QMK的OLED_DRIVER功能并对其进行“魔改”以驱动SPI TFT屏或者直接编写底层SPI通信代码。这里以集成Adafruit_ST7789库的思路为例需要在QMK环境中手动添加该库。首先在rules.mk中启用SPI和自定义功能# rules.mk SPI_ENABLE yes CUSTOM_MATRIX yes # 如果矩阵扫描也需要自定义 SRC amg65.c tft_display.c # 添加自定义源文件然后创建tft_display.c和tft_display.h文件实现基于SPI的ST7789初始化、画点、画图、显示文本等函数。你需要根据屏幕数据手册编写底层spi_transmit命令。在config.h中定义TFT屏的SPI引脚// config.h #define TFT_SPI_DRIVER SPID1 // 使用哪个SPI外设 #define TFT_SPI_SCK_PIN GP26 #define TFT_SPI_MOSI_PIN GP27 #define TFT_SPI_MISO_PIN GP28 // 如果只写可不接 #define TFT_DC_PIN GP21 // 数据/命令选择引脚 #define TFT_CS_PIN GP20 // 片选引脚 #define TFT_RST_PIN GP19 // 复位引脚3.4 键盘初始化与屏幕启动在amg65.c文件的keyboard_post_init_user()函数中初始化你的屏幕。// amg65.c #include “tft_display.h” #include “led_matrix.h” void keyboard_post_init_user(void) { // 初始化点阵屏 led_matrix_init(); // 执行点阵屏的默认效果可选 led_matrix_set_suspend_state(false); // 初始化TFT彩屏 tft_init(); // 在TFT屏上显示启动画面或默认信息 tft_draw_string(10, 10, “AMG65 Ready”, COLOR_WHITE, COLOR_BLACK); }4. 实现双屏的图形化显示逻辑硬件驱动起来后核心挑战在于如何组织代码让两块屏幕协同显示有用的、可自定义的信息。4.1 设计显示内容分区一个合理的双屏显示方案是点阵屏负责显示实时、高频更新的简单状态信息。键盘层Layer指示。Caps Lock, Num Lock, Scroll Lock状态。WPM每分钟击键数。简单的动画如呼吸灯、流动效果。TFT彩屏负责显示复杂、信息量大的静态或低频更新内容。当前键盘布局的键位图。系统监控信息CPU占用率、内存使用量、网络状态——需要主机端配合。自定义图片或GIF动画。音乐播放器信息需要与操作系统通信。4.2 编写点阵屏效果QMK的LED_MATRIX功能提供了多种内置效果如呼吸、光谱循环、波浪。你可以在config.h中启用它们也可以自定义效果。自定义点阵屏动画需要在led_matrix_kb.inc或led_matrix_user.inc文件中实现led_matrix_indicators_kb()或led_matrix_indicators_user()函数。// 在 led_matrix_user.inc 或类似文件中 bool led_matrix_indicators_user(void) { // 根据键盘层改变点阵屏颜色 switch(get_highest_layer(layer_state)) { case 1: led_matrix_set_color_all(0, 255, 0); // 层1绿色 break; case 2: led_matrix_set_color_all(0, 0, 255); // 层2蓝色 break; default: led_matrix_set_color_all(255, 0, 0); // 默认层红色 break; } // 在特定位置如右下角显示Caps Lock状态 if (host_keyboard_led_state().caps_lock) { led_matrix_set_color(INDEX_OF_CAPS_LOCK_LED, 255, 255, 255); // 白色 } return false; // 返回false允许其他效果继续运行 }INDEX_OF_CAPS_LOCK_LED需要你根据点阵屏的LED布局映射表来计算这是点阵屏编程中最繁琐的部分之一。4.3 编写TFT屏显示程序在tft_display.c中你需要实现一系列高级绘图函数。例如显示当前层键位图// tft_display.c void tft_draw_layer_bitmap(uint8_t layer) { tft_fill_screen(COLOR_BLACK); // 清屏 // 假设有一个预定义的键位图位图数组 const uint16_t (*layer_bitmap)[TFT_WIDTH] get_layer_bitmap(layer); for (int y 0; y TFT_HEIGHT; y) { for (int x 0; x TFT_WIDTH; x) { tft_draw_pixel(x, y, layer_bitmap[y][x]); } } // 在顶部显示层名称 char layer_str[20]; snprintf(layer_str, sizeof(layer_str), “Layer: %d”, layer); tft_draw_string(5, 5, layer_str, COLOR_CYAN, COLOR_BLACK); }然后在键位图的layer_state_set_user()回调中调用此函数// 在 keymap.c 中 layer_state_t layer_state_set_user(layer_state_t state) { uint8_t layer get_highest_layer(state); tft_draw_layer_bitmap(layer); // 切换层时更新TFT显示 return state; }5. 编译、烧录固件与功能验证代码编写完成后需要编译成二进制文件并烧录到键盘主控中。5.1 编译固件在QMK MSYS终端中进入你的键盘目录并执行编译命令cd ~/qmk_firmware qmk compile -kb leobog/amg65 -km default如果一切配置正确编译成功后会在终端输出信息并在qmk_firmware目录下生成leobog_amg65_default.uf2对于RP2040或.bin对于ESP32等格式的固件文件。5.2 烧录固件烧录方式取决于主控芯片RP2040通常支持UF2引导模式。按住键盘上的“BOOT”或“RESET”键或通过短路PCB上的触点同时插入USB线键盘会作为一个U盘出现。将生成的.uf2文件拖入该U盘即可完成烧录。ESP32-S3需要使用esptool.py通过串口进行烧录。你需要安装CP210x或CH340等USB转串口芯片的驱动并使用以下命令端口和文件路径需替换esptool.py --chip esp32s3 --port COM3 --baud 921600 write_flash 0x0 leobog_amg65_default.bin烧录前ESP32通常需要进入下载模式拉低GPIO0并复位。5.3 功能验证清单烧录完成后重新插拔键盘按以下清单验证基础输入键盘是否能被操作系统识别所有按键按下是否都能输出正确字符点阵屏通电后点阵屏是否亮起是否显示了默认效果如光谱循环切换键盘层如Fn1时点阵屏颜色或图案是否变化按下Caps Lock键对应的LED状态是否改变TFT彩屏TFT屏是否成功点亮并显示初始化信息如“AMG65 Ready”切换键盘层时TFT屏上的键位图是否相应更新双屏联动测试一个复杂场景例如触发一个宏命令观察点阵屏是否播放特定动画同时TFT屏是否显示命令执行状态。6. 常见问题排查与调试在开发过程中你几乎一定会遇到各种问题。以下是按优先级排序的排查路径。6.1 键盘无输入或按键错乱问题现象可能原因检查方式处理建议所有按键无反应1. 固件未正确烧录。2. USB数据线或端口问题。3. 主控芯片损坏或虚焊。1. 检查设备管理器/系统信息中是否识别到键盘如“HID Keyboard Device”。2. 换线、换端口测试。3. 重新烧录一个最简单的测试固件如QMK示例。确保进入正确的烧录模式使用可靠的USB线。检查PCB有无短路、断路。部分按键无反应或错乱1. 按键矩阵定义错误行/列引脚颠倒或错误。2. 二极管方向焊反对于有二极管的设计。3.info.json或keymap.c中的键位定义与物理布局不匹配。1. 使用QMK的qmk console命令按下故障按键查看终端输出的矩阵坐标。2. 对照原理图用万用表蜂鸣档检查矩阵电路。仔细核对config.h中的MATRIX_ROW_PINS和MATRIX_COL_PINS与PCB原理图。使用qmk info -kb keyboard检查布局。6.2 点阵屏不亮或显示异常问题现象可能原因检查方式处理建议点阵屏完全不亮1. 电源未接通VCC/GND。2. I2C/SPI引脚接错或配置错误。3. 驱动芯片型号配置错误LED_MATRIX_DRIVER。1. 用万用表测量点阵屏模块供电电压。2. 使用逻辑分析仪或示波器检查I2C/SPI线上是否有信号。3. 检查rules.mk和config.h中的相关配置。确认I2C1_SCL_PIN和I2C1_SDA_PIN定义正确。尝试降低I2C时钟速度#define I2C1_CLOCK_SPEED 400000。部分LED常亮、闪烁或颜色错误1. LED索引映射错误g_led_config.matrix_co。2. 驱动芯片的扫描模式配置不当。1. 编写一个简单的测试程序依次点亮每一个LED观察实际点亮的位置。2. 查阅驱动芯片数据手册确认扫描模式如8x8, 16x8。在config.h中仔细定义LED_MATRIX_LED_COUNT,LED_MATRIX_ROWS,LED_MATRIX_COLS并正确填充g_led_config结构体。6.3 TFT彩屏白屏、花屏或通信失败问题现象可能原因检查方式处理建议屏幕白屏或背光亮但无显示1. 初始化序列错误或时序不对。2. 复位RST引脚未正确控制。3. 数据/命令DC引脚控制错误。1. 在tft_init()函数开始和每个步骤后通过GPIO翻转一个测试引脚用示波器查看执行时间。2. 确认RST引脚有正确的上电复位脉冲拉低10ms再拉高。逐行核对屏幕驱动芯片如ST7789数据手册中的初始化命令和参数。确保SPI时钟极性CPOL和相位CPHA设置正确。屏幕显示花屏、错位1. 显存GRAM的写入窗口X, Y坐标设置错误。2. 颜色格式RGB565 vs RGB888不匹配。3. SPI时钟速度过快导致数据出错。1. 编写一个简单的测试只画一个纯色矩形或一条对角线看是否正确显示。2. 检查tft_draw_pixel函数中颜色数据的组装方式。降低SPI时钟频率。确认TFT_WIDTH和TFT_HEIGHT定义与屏幕物理分辨率一致。仔细实现设置窗口set_window函数。6.4 固件编译错误“未定义的引用”错误通常是因为在rules.mk中启用了某个功能如OLED_ENABLE yes但没有提供对应的驱动文件或者在SRC中漏掉了自定义的.c文件。检查rules.mk和文件包含关系。内存不足错误双屏、复杂的图形和动画会消耗大量Flash和RAM。如果使用RP2040可以尝试在rules.mk中启用链接时优化LTO_ENABLE yes。如果使用ESP32可以调整分区表或优化代码减少全局变量和大的缓冲区。7. 进阶优化与生产环境考量当基本功能跑通后可以从以下方面提升项目的完成度和可靠性。7.1 性能优化双缓冲与局部刷新TFT屏全屏刷新速度较慢。可以引入帧缓冲区framebuffer在内存中完成绘图然后一次性刷新到屏幕。对于只变化部分区域的内容如WPM数字只刷新局部区域。异步更新将屏幕刷新逻辑放在定时器中断或独立任务中如果使用RTOS避免阻塞主循环导致按键响应延迟。效果优化点阵屏的复杂动画可能占用大量CPU。使用预计算的查找表LUT或简化算法。7.2 增加实用功能VIA/VIAL支持在info.json中正确定义键盘布局和功能即可获得实时改键的图形化界面支持极大提升易用性。系统状态同步通过Raw HID或Vial协议编写一个运行在电脑端的小程序如用Python将CPU温度、音量、音乐播放信息等发送给键盘并在TFT屏上显示。无线功能如果主控是ESP32-S3可以启用蓝牙实现无线连接和显示电池电量。7.3 生产环境稳定性建议错误处理在屏幕初始化、SPI/I2C通信函数中加入重试机制和超时判断。如果通信失败应记录错误如通过点阵屏显示错误代码并尝试恢复而不是死锁。功耗管理对于无线场景在键盘无操作一段时间后自动降低屏幕亮度或关闭屏幕以节省电量。固件升级DFU实现通过USB或无线进行固件升级的功能避免每次更新都要拆开键盘进入引导模式。版本与配置分离将用户配置如RGB颜色、屏幕主题存储在EEPROM或Flash的独立区域使其在固件升级后得以保留。从一块空白的PCB到一把拥有灵动点阵屏和绚丽彩屏的个性化键盘整个过程是对嵌入式开发、硬件交互和图形编程的综合实践。成功的关键在于耐心仔细阅读数据手册、逐行调试硬件通信、分模块验证功能。建议先从驱动单块屏幕开始成功后再集成第二块最后才实现复杂的联动逻辑。当你看到自定义的动画在点阵屏上流转实时的系统信息在彩屏上清晰展现时这份成就感正是客制化键盘的核心魅力所在。下一步你可以探索更复杂的图形UI、与操作系统的深度集成甚至是将键盘作为物联网设备的一个节点。
)
