QMK UT47 默认键位与双控制器 LED 控制从四层布局到串口驱动源码解析【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware本篇文章围绕 QMK 固件仓库中40percentclub/ut47键盘的 default 键位方案展开完整讲解 UT47 的默认四层按键布局、通过TAB组合键触发的 LED 亮度与模式切换并深入到主控固件led_controls.c与副控制器 Arduino 程序led_controls.ino的源码层面还原一条按键动作 → 串口字节 → LED 矩阵渲染的完整调用链。读完本文你将掌握 UT47 default 键位的全部细节并理解其双控制器 UART背光架构的实现原理与构建方式。UT47 与 default 键位概述UT47 是 40percent.club 推出的一款 47 键小键盘其定位介于正交ortholinear布局与常规错位staggered布局之间既有 Planck 级别的完整功能覆盖又保留了传统键盘的按键行列错位手感。在 QMK 仓库中其硬件定义位于 keyboards/40percentclub/ut47/keyboard.json默认键位方案则是 keymaps/default/keymap.c 与其配套说明文档 keymaps/default/readme.md。从 keyboard.json 可以看到它的硬件基线主控处理器atmega32u4Arduino Pro Micro 平台Bootloader 为caterina矩阵方向COL2ROW列扫描输入、行扫描输出矩阵引脚12 列D7 E6 B4 B5 B6 B2 B3 B1 F7 F6 F5 F4、4 行D1 D0 D4 C6USB 标识VID0x4025PID0x7574默认开启特性bootmagic、mousekey、extrakey、command、nkro以及 QMK locking含 resync该键盘的矩阵规模为 4 行 × 12 列正好对应 47 个物理按键最底行包含 1.25U/2U 等异形键位。default 键位在 4×12 矩阵上定义了 4 个功能层用LAYOUT宏以逐键方式声明全部键值存放在keymaps[][MATRIX_ROWS][MATRIX_COLS]数组中。默认四层布局详解default 键位在 keymap.c 中定义了 4 层Base默认层、FN Layer 1、FN Layer 2 以及 Tab 功能层。文件开头先定义了两个便于复用的组合键宏#define LT3_TAB LT(3, KC_TAB) #define MT_RSFT_ENT MT(MOD_RSFT, KC_ENT)LT3_TAB按住时切入第 3 层Tab 功能层单击则输出Tab——这就是文档中所有TAB 组合操作的入口MT_RSFT_ENT按住时作为右 Shift单击则输出Enter放在第三行最右侧同时承担右 Shift与回车两种职责。Base 层默认层KC_ESC, KC_Q, KC_W, KC_E, KC_R, KC_T, KC_Y, KC_U, KC_I, KC_O, KC_P, KC_BSPC, LT3_TAB, KC_A, KC_S, KC_D, KC_F, KC_G, KC_H, KC_J, KC_K, KC_L, KC_SCLN, KC_QUOT, KC_LSFT, KC_Z, KC_X, KC_C, KC_V, KC_B, KC_N, KC_M, KC_COMM, KC_DOT, KC_SLSH, MT_RSFT_ENT, KC_LCTL, KC_LALT, KC_LGUI, KC_APP, MO(2), KC_SPC, MO(1), KC_LEFT, KC_DOWN, KC_UP, KC_RGHTBase 层是一套标准小配列布局第一行为 Esc 字母 Q~P Backspace第二行以LT3_TAB打头接 A~L、分号、引号第三行是左 Shift Z~?末位是 Shift/Enter 两用键底行则依次为 Ctrl、Alt、GUISuper、Menu、MO(2)层切换键、2U 空格、MO(1)层切换键以及 Left/Down/Up/Right 四个方向键。注意底行空格两侧的MO(2)与MO(1)只是临时按住切层与LT3_TAB不同它们不会在单击时产生任何字符输出只负责把键盘临时带到对应功能层。FN Layer 1数字与符号层KC_GRV, KC_1, KC_2, KC_3, KC_4, KC_5, KC_6, KC_7, KC_8, KC_9, KC_0, KC_DELETE, _______, _______, _______, _______, _______, _______, _______, KC_MINS, KC_EQL, KC_LBRC, KC_RBRC, KC_BSLS, _______, KC_F11, KC_F12, KC_F13, KC_F14, KC_F15, KC_F16, KC_F17, KC_F18, KC_F19, KC_F20, _______, _______, _______, _______, KC_CAPS, _______, _______, _______, KC_HOME, KC_PGDN, KC_PGUP, KC_END按住MO(1)Base 层空格左侧时进入本层数字行 1~0、反引号、Delete 集中在第一行第二行提供- [ ] \五个符号键第三行给出 F11~F20底行放入 Caps Lock 与 Home/PgDn/PgUp/End 编辑键。键位表中大量使用_______透明键表示这些位置继承下层键位避免重复声明。FN Layer 2符号补全层KC_TILDE, KC_EXCLAIM, KC_AT, KC_HASH, KC_DOLLAR, KC_PERCENT, KC_CIRCUMFLEX, KC_AMPERSAND, KC_ASTERISK, KC_LEFT_PAREN, KC_RIGHT_PAREN, KC_DELETE, _______, _______, _______, _______, _______, _______, _______, KC_UNDERSCORE, KC_PLUS, KC_LEFT_CURLY_BRACE, KC_RIGHT_CURLY_BRACE, KC_PIPE, _______, KC_F1, KC_F2, KC_F3, KC_F4, KC_F5, KC_F6, KC_F7, KC_F8, KC_F9, KC_F10, _______, _______, _______, _______, KC_CAPS, _______, _______, _______, KC_HOME, KC_PGDN, KC_PGUP, KC_END按住MO(2)底行 Menu 右侧进入本层与 FN Layer 1 形成互补第一行直接输出带 Shift 的符号字符~ ! # $ % ^ * ( )第二行提供_ { } |第三行是 F1~F10底行编辑键与 FN1 层一致。这样的分层设计让用户无须同时按 Shift 即可输入全部符号是小配列键盘常见的符号双态处理手法。Tab 功能层媒体与鼠标层KC_ESC, KC_CALC, KC_WHOM, KC_MAIL, KC_MYCM, _______, _______, _______, _______, _______, KC_PSCR, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, LED_TOG, LED_CHG, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, MS_LEFT, MS_DOWN, MS_UP, MS_RGHT按住LT3_TAB进入本层这也是 default 键位最具特色的部分第一行Esc、计算器KC_CALC、主页KC_WHOM、邮件KC_MAIL、我的电脑KC_MYCM等消费级媒体键以及 PrtSc第三行两个自定义键码LED_TOG切换亮度与LED_CHG切换模式即文档中TABZ、TABX的来源Z、X 恰好处在本层对应列位置底行MS_LEFT / MS_DOWN / MS_UP / MS_RGHT鼠标移动键把方向键区临时变成鼠标控制区。LED_TOG、LED_CHG并非 QMK 内置键码而是 UT47 通过 keyboard.json 中的keycodes字段{key: LED_TOG}、{key: LED_CHG}注册的自定义键码其实际处理逻辑在 led_controls.c 中实现详见下文。LED 控制亮度与模式切换default 键位说明文档给出的 LED 操作方式非常简洁本小节原样继承并展开操作功能TABZ循环切换背光亮度共 8 档TABX循环切换 LED 模式TABX可以依次经过以下模式solid常亮背光全开breathing呼吸亮度周期性起伏random随机闪烁rain雨滴随机位置点亮后逐渐衰减reactive按键反应按下位置点亮后渐隐poptang行列响应整行 整列同时点亮off关闭按键 → 串口字节的发送端实现这两个组合键之所以能控制 LED是因为 UT47 采用双控制器架构主控制器运行 QMK 固件负责键盘矩阵副控制器运行 Arduino 程序负责驱动 4×12 的 LED 矩阵。二者通过串口UART通信。发送端逻辑在 led_controls.cvoid keyboard_post_init_kb(void) { uart_init(9600); keyboard_post_init_user(); } bool process_record_kb(uint16_t keycode, keyrecord_t *record) { if (record-event.pressed) { uart_write((record-event.key.row * 16) record-event.key.col); switch (keycode) { case LED_TOG: uart_write(0x64); return false; case LED_CHG: uart_write(0x65); return false; } } return process_record_user(keycode, record); }关键点串口初始化keyboard_post_init_kb()中以9600 波特率初始化 UART与副控制器Serial1.begin(9600)对应按键坐标上报每次按键按下主控都会向副控制器发送一个字节row * 16 col把 4×12 矩阵坐标压缩成单字节编码行占高 4 位、列占低 4 位供副控制器在 reactive 模式下定位点亮位置控制字节协议LED_TOG按下时发送0x64十进制 100即亮度档位递增指令LED_CHG按下时发送0x65十进制 101即模式切换指令两者return false阻止键码继续传递保证不会在 USB 端产生多余输出Caps Lock 联动led_update_kb()在 Caps Lock 点亮时把 B0、D5 引脚拉低作为指示灯关闭时恢复输入高阻态将大写锁定状态同步到外部 LED。副控制器的模式渲染实现接收端在 led_controls.ino这是运行在第二块 Arduino 上的独立程序。其checkserial()是协议解析核心void checkserial() { if (Serial1.available() 0) { iByte Serial1.read(); if (iByte 100) { // 0x64亮度档 1 brightness; if (brightness 9) { brightness 1; } } if (iByte 101) { // 0x65模式 1 mode; } if (iByte 100) { // 普通按键坐标字节 if (mode 4) { // reactive单点点亮 byte row iByte / 16; byte col iByte % 16; leds[col][row] 18; } if (mode 5) { // poptang整行整列点亮 byte row iByte / 16; byte col iByte % 16; for (byte i 0; i 12; i) { leds[i][row] 18; } for (byte p 0; p 4; p) { leds[col][p] 18; } } } } }对照loop()中的switch (mode)可以把文档列出的模式映射到源码实现对应关系从 led_controls.ino 的 case 分支可以直接读出文档模式源码 mode 值实现要点solid0全矩阵按brightness档位常亮breathing1亮度 1→8 递增再递减模拟呼吸random2随机坐标随机亮度闪烁rain3随机雨滴落下并随时间逐级衰减reactive4按收到的按键坐标点亮该点随后渐隐poptang5按键所在行与列同时点亮形成十字交叉效果当mode超过最后一个 case 后落入default分支代码会执行mode 0回到 solid形成一个循环。关于文档中的 off关闭模式可以推断它对应的是模式循环中的终止/常灭状态——固件端并未单独实现全灭分支而是依靠循环回绕机制回到起始状态源码以 led_controls.ino 实际行为为准。亮度方面副控制器在1~9之间循环递增brightness 9时重置为 1与文档所述8 档循环在量级上一致。LED 矩阵的刷新由Timer1.initialize(25)注册的中断服务函数display()完成以 25 微秒为周期轮换扫描 12 列并根据leds[col][row]与pass的比较决定每行引脚的开关从而实现软件 PWM 亮度控制——这也是整个背光系统能流畅运行、同时不阻塞主循环的原因。构建与启用LED_ENABLE 选项与双控制器刷写需要说明的是上述串口背光逻辑是opt-in可选启用特性默认构建不会包含。启用与刷写步骤见 keyboards/40percentclub/ut47/readme.md# 不带 LED 的单控制器版本默认 make 40percentclub/ut47:default # 带 LED 的双控制器版本主控制器 make 40percentclub/ut47:default LED_ENABLEyes也可以把LED_ENABLE yes写进键盘的rules.mk使其成为默认。之所以做成选择性特性仓库说明中明确解释默认不启用是为了避免在引脚上发送串行通信防止该引脚被其他用途例如 RGB underglow占用时产生冲突。LED_ENABLEyes实际生效的机制在 post_rules.mkifeq ($(strip $(LED_ENABLE)), yes) OPT_DEFS -DLED_ENABLE SRC led_controls.c UART_DRIVER_REQUIRED yes endif即编译期追加-DLED_ENABLE宏定义、把 led_controls.c 加入构建源文件并声明依赖 QMK 的 UART 驱动UART_DRIVER_REQUIRED yes对应 drivers/uart.h 提供的uart_init/uart_write接口。主控制器固件刷好后还需要把 led_controls.ino 用 Arduino IDE 或兼容工具刷写到第二块控制器上该程序依赖 FastGPIO 与 TimerOne 两个第三方库编译前需先导入。至此主控负责按键矩阵与 USB副控负责 4×12 LED 矩阵渲染两者以 9600 波特率串口协作形成一套完整的双控制器背光系统。可选变体WS2812B RGB 版本如果不想用传统的 LED 矩阵背光UT47 还提供了一套 RGB 变体键位方案位于 keymaps/rgb/。其布局主体与 default 几乎一致但把第三行换成了一排原生的 QMK RGB 键码_______, UG_TOGG, UG_NEXT, UG_HUEU, UG_HUED, UG_SATU, UG_SATD, UG_VALU, UG_VALD, _______, _______,分别对应 RGB 开关、下一个模式、色调加减、饱和度加减、明度加减。其配套 config.h 定义了硬件参数#define WS2812_DI_PIN D3 // LED 灯带数据引脚 #define RGBLIGHT_LED_COUNT 7 // 灯带 LED 数量 #define RGBLIGHT_EFFECT_BREATHING #define RGBLIGHT_EFFECT_RAINBOW_MOOD #define RGBLIGHT_EFFECT_RAINBOW_SWIRL #define RGBLIGHT_EFFECT_SNAKE #define RGBLIGHT_EFFECT_KNIGHT #define RGBLIGHT_EFFECT_CHRISTMAS #define RGBLIGHT_EFFECT_STATIC_GRADIENT #define RGBLIGHT_EFFECT_RGB_TEST #define RGBLIGHT_EFFECT_ALTERNATING #define RGBLIGHT_EFFECT_TWINKLE并配合 rules.mk 中的RGBLIGHT_ENABLE yes启用 QMK 原生的 RGB 背光子系统WS2812B 灯带接 D3 引脚共 7 颗灯来自 40percent.club 的 GNAP underglow 方案。这也印证了仓库说明中引脚可能被 RGB 占用的顾虑——LED 矩阵方案与 RGB 方案通过不同的构建入口区分二者不会同时占用 D3。小结UT47 default 键位方案用 4 层结构把 47 颗键扩展出完整数字区、符号区、F1~F20、媒体键与鼠标控制能力而其背光系统则是理解QMK 主控 Arduino 副控协作架构的绝佳范例主控通过uart_write发送按键坐标与控制字节副控以0x64/0x65驱动亮度与模式切换并在 25 微秒中断周期内完成矩阵扫描渲染。围绕本仓库你可以进一步查阅 default 键位源码、LED 串口驱动、副控制器程序、构建开关 以及 RGB 变体按需裁剪出自己的 UT47 配置。【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考