尧图网站建设 
QMK 固件实战AbstractKB Ellipse 默认键位解析3 旋钮 3 按键的 RGB 旋钮键盘【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware本文以 QMK Firmware 仓库中 AbstractKB EllipseRev1小键盘的默认键位说明为主线完整剖析这套用于出厂测试的 6 键位 3 旋钮布局每个按键与旋钮如何映射为标准字母键码、中间旋钮如何通过 RGB 色相旋转检验 LED 硬件、旋钮按下如何切换背光开关并下沉到encoder 驱动与 RGB 灯光库的源码层讲清encoder_update_user回调、rgblight_*_noeeprom系列函数的工作机制。读完你可以理解并改写任何一款多旋钮 QMK 键盘的默认键位包括自定义旋钮动作与 RGB 控制。一、Ellipse 硬件与默认键位设计意图Ellipse 是 AbstractKB 出品的一块旋钮比按键还多的迷你小键盘一块 PCB 上集成了3 个旋转编码器Knob和 3 颗 MX 兼容轴体。其 Rev1 的完整硬件描述位于键盘 readme 与rev1/keyboard.json。默认键位default keymap的定位非常明确——在键盘组装完成后对硬件做基本功能测试。其策略是每个按键、每个旋钮都输出一个互不相同的标准字母键码通过实际打字即可确认矩阵扫描与编码器方向是否正常中间那颗旋钮则专门用于验证 RGB LED 的色相调节按下时关闭 RGB形成键码正确性 RGB 硬件两条独立的验证链路。该键盘的固件目标为atmega32u4使用atmel-dfu引导加载程序由 keyboard.json 数据驱动配置生成。二、键位表逐键解读默认键位定义在 keymaps/default/keymap.c 中const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] { [0] LAYOUT( /* Base */ KC_A, UG_TOGG, KC_C, KC_X, KC_Y, KC_Z ) };对应 keyboard.json 中的LAYOUT布局3 列 × 2 行键位分配如下位置键码作用上排左KC_A输出字母 A上排中UG_TOGG切换 RGB 背光开/关对应 readme 所述按下关闭 RGB上排右KC_C输出字母 C下排左KC_X输出字母 X下排中KC_Y输出字母 Y下排右KC_Z输出字母 Z其中UG_TOGG是 QMK 预定义的用户区背光切换键码其定义位于 quantum/keycodes.hUG_TOGG QK_UNDERGLOW_TOGGLE。按下该键会在 RGB 开/关两种状态间切换由于 keyboard.json 中rgblight.sleep设为trueRGB 灯在休眠时也会自动熄灭这与 readme 中按下中间键关闭 RGB LED的测试描述一致——通过打字与按灯即可快速判断矩阵与 LED 通路是否正常。三、三个旋钮的编码器回调每个旋钮输出不同字母Ellipse 的 3 个旋钮行为完全由用户级回调encoder_update_user决定bool encoder_update_user(uint8_t index, bool clockwise) { if (index 0) { /* First encoder */ if (clockwise) { tap_code(KC_O); } else { tap_code(KC_P); } } else if (index 1) { /* Second encoder */ if (clockwise) { rgblight_increase_hue_noeeprom(); } else { rgblight_decrease_hue_noeeprom(); } } else if (index 2) { if (clockwise) { tap_code(KC_M); } else { tap_code(KC_R); } } return true; }各旋钮映射汇总旋钮 index顺时针clockwisetrue逆时针clockwisefalse用途0KC_OKC_P验证旋钮 A 方向与矩阵读数1色相 8rgblight_increase_hue_noeeprom色相 -8rgblight_decrease_hue_noeeprom验证 RGB 色相调节2KC_MKC_R验证旋钮 C 方向与矩阵读数注意这里使用tap_code()触发单个键码只发送按下→抬起一次适合旋钮这类非驻留输入。三个旋钮各自输出不同的字母对O/P、无字母、M/R旋钮 1 则专司 RGB 色相测试这样无论哪颗旋钮损坏都能被精确定位。四、源码原理编码器回调为何在 keymap 中生效encoder_update_user能在键位文件里直接生效依赖 quantum/encoder.c 提供的弱符号weak symbol机制__attribute__((weak)) bool encoder_update_user(uint8_t index, bool clockwise) { return true; } __attribute__((weak)) bool encoder_update_kb(uint8_t index, bool clockwise) { bool res encoder_update_user(index, clockwise); ... }默认实现返回true不产生任何副作用用户在 keymap 中提供同名强符号实现后链接器自动以用户版本覆盖弱符号从而接管旋钮逻辑encoder_update_kb会先调用encoder_update_user若返回值为真再执行默认行为——未定义EXTRAKEY_ENABLE/MOUSEKEY_ENABLE时默认发送KC_PGDN/KC_PGUP定义EXTRAKEY_ENABLE时默认发送KC_VOLU/KC_VOLD。Ellipse 在 keyboard.json 中开启了extrakey同时自己在回调里返回true因此两个旋钮既执行自定义字母键码又叠加默认音量键行为这正是该键位旋转出字 音量可调双重效果的来源。此外编码器事件通过内部 FIFO 队列encoder_queue_event/encoder_dequeue_event见 quantum/encoder.c逐事件分发多个旋钮并发旋转也不会丢失方向信息。硬件侧三颗旋钮分别挂在 B2/B1、B3/B7、D5/B4 三组引脚上且 keyboard.json 中resolution: 2表示每 2 个脉冲计为一次有效旋转起到硬件抖动抑制的作用。五、源码原理RGB 色相调节的 noeeprom 变体中间旋钮调用的rgblight_increase_hue_noeeprom()/rgblight_decrease_hue_noeeprom()定义于 quantum/rgblight/rgblight.cvoid rgblight_increase_hue_helper(bool write_to_eeprom) { uint8_t hue rgblight_config.hue RGBLIGHT_HUE_STEP; rgblight_sethsv_eeprom_helper(hue, rgblight_config.sat, rgblight_config.val, write_to_eeprom); } void rgblight_increase_hue_noeeprom(void) { rgblight_increase_hue_helper(false); }要点如下色相每次步进RGBLIGHT_HUE_STEP默认值为8见 quantum/rgblight/rgblight.h同样可覆盖的还有RGBLIGHT_SAT_STEP 17、RGBLIGHT_VAL_STEP 17write_to_eeprom参数为false时只改当前内存配置、不写入 EEPROM因此断电重启后色相恢复到上次保存的值——适合测试场景避免反复旋钮把 EEPROM 写穿EEPROM 有写入寿命限制带 EEPROM 写回的版本是rgblight_increase_hue()/rgblight_decrease_hue()中间旋钮通过色相Hue的连续增减驱动 keyboard.json 中led_count: 3的 WS2812 灯珠引脚 E6旋转时肉眼可见颜色沿色环循环变化从而一次验证编码器读数正确 RGB 驱动正常两项硬件。六、矩阵、灯光与编译烧录配置Ellipse Rev1 的完整底层配置集中在 rev1/keyboard.json核心字段如下配置项值说明processoratmega32u4主控芯片bootloaderatmel-dfu引导方式对应:dfu烧录目标matrix_pins.colsF0, B6, B53 列引脚matrix_pins.rowsD3, C72 行引脚diode_directionCOL2ROW二极管方向encoder.rotary3 组{pin_a, pin_b, resolution: 2}旋钮 A/B/C 引脚与分辨率rgblight.led_count3WS2812 灯珠数量ws2812.pinE6灯带数据引脚featuresencoder、extrakey、rgblight等按需裁剪的固件功能编译并烧录该键盘默认键位按键盘 readme 给出的命令make abstract/ellipse/rev1:default:dfuQMK 构建系统会从keyboards/abstract/ellipse/rev1/keyboard.json数据驱动生成矩阵、编码器与 RGB 配置再与keymaps/default/keymap.c中的键位和回调一起编译最后通过 DFU 协议写入主控。注意Rev1 已知存在两个固件层面的小问题——背光呼吸breathing模式不可用以及post_init_user钩子不会被调用见 键盘 readme自定义固件时应避免依赖这两个特性。七、如何基于这套键位做二次定制默认键位是一份极佳的旋钮键盘模板改造成常见用法时只需替换键位表与encoder_update_user旋钮调音量把旋钮 0 的回调改为tap_code(KC_VOLU)/tap_code(KC_VOLD)需启用extrakey旋钮翻页改为tap_code(KC_PGDN)/tap_code(KC_PGUP)中间旋钮改亮度/饱和度将rgblight_*_hue_noeeprom()换成rgblight_increase_val_noeeprom()/rgblight_increase_sat_noeeprom()等系列函数实现均位于 quantum/rgblight/rgblight.c需要保存设置改用不带noeeprom后缀的版本如rgblight_increase_hue()代价是每次旋转都会写 EEPROM。总体而言Ellipse 默认键位以每个输入源输出唯一键码的朴素策略把按键矩阵、三路编码器方向、RGB 色相链路全部纳入一次快速自检流程理解这份键位背后的encoder_update_user弱符号回调与rgblight_*_noeeprom内存态控制也就掌握了 QMK 多旋钮键盘定制与调试的核心手法。【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 QMK 固件实战：AbstractKB Ellipse 默认键位解析（3 旋钮 + 3 按键的 RGB 旋钮键盘）
QMK 固件实战AbstractKB Ellipse 默认键位解析3 旋钮 3 按键的 RGB 旋钮键盘【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware本文以 QMK Firmware 仓库中 AbstractKB EllipseRev1小键盘的默认键位说明为主线完整剖析这套用于出厂测试的 6 键位 3 旋钮布局每个按键与旋钮如何映射为标准字母键码、中间旋钮如何通过 RGB 色相旋转检验 LED 硬件、旋钮按下如何切换背光开关并下沉到encoder 驱动与 RGB 灯光库的源码层讲清encoder_update_user回调、rgblight_*_noeeprom系列函数的工作机制。读完你可以理解并改写任何一款多旋钮 QMK 键盘的默认键位包括自定义旋钮动作与 RGB 控制。一、Ellipse 硬件与默认键位设计意图Ellipse 是 AbstractKB 出品的一块旋钮比按键还多的迷你小键盘一块 PCB 上集成了3 个旋转编码器Knob和 3 颗 MX 兼容轴体。其 Rev1 的完整硬件描述位于键盘 readme 与rev1/keyboard.json。默认键位default keymap的定位非常明确——在键盘组装完成后对硬件做基本功能测试。其策略是每个按键、每个旋钮都输出一个互不相同的标准字母键码通过实际打字即可确认矩阵扫描与编码器方向是否正常中间那颗旋钮则专门用于验证 RGB LED 的色相调节按下时关闭 RGB形成键码正确性 RGB 硬件两条独立的验证链路。该键盘的固件目标为atmega32u4使用atmel-dfu引导加载程序由 keyboard.json 数据驱动配置生成。二、键位表逐键解读默认键位定义在 keymaps/default/keymap.c 中const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] { [0] LAYOUT( /* Base */ KC_A, UG_TOGG, KC_C, KC_X, KC_Y, KC_Z ) };对应 keyboard.json 中的LAYOUT布局3 列 × 2 行键位分配如下位置键码作用上排左KC_A输出字母 A上排中UG_TOGG切换 RGB 背光开/关对应 readme 所述按下关闭 RGB上排右KC_C输出字母 C下排左KC_X输出字母 X下排中KC_Y输出字母 Y下排右KC_Z输出字母 Z其中UG_TOGG是 QMK 预定义的用户区背光切换键码其定义位于 quantum/keycodes.hUG_TOGG QK_UNDERGLOW_TOGGLE。按下该键会在 RGB 开/关两种状态间切换由于 keyboard.json 中rgblight.sleep设为trueRGB 灯在休眠时也会自动熄灭这与 readme 中按下中间键关闭 RGB LED的测试描述一致——通过打字与按灯即可快速判断矩阵与 LED 通路是否正常。三、三个旋钮的编码器回调每个旋钮输出不同字母Ellipse 的 3 个旋钮行为完全由用户级回调encoder_update_user决定bool encoder_update_user(uint8_t index, bool clockwise) { if (index 0) { /* First encoder */ if (clockwise) { tap_code(KC_O); } else { tap_code(KC_P); } } else if (index 1) { /* Second encoder */ if (clockwise) { rgblight_increase_hue_noeeprom(); } else { rgblight_decrease_hue_noeeprom(); } } else if (index 2) { if (clockwise) { tap_code(KC_M); } else { tap_code(KC_R); } } return true; }各旋钮映射汇总旋钮 index顺时针clockwisetrue逆时针clockwisefalse用途0KC_OKC_P验证旋钮 A 方向与矩阵读数1色相 8rgblight_increase_hue_noeeprom色相 -8rgblight_decrease_hue_noeeprom验证 RGB 色相调节2KC_MKC_R验证旋钮 C 方向与矩阵读数注意这里使用tap_code()触发单个键码只发送按下→抬起一次适合旋钮这类非驻留输入。三个旋钮各自输出不同的字母对O/P、无字母、M/R旋钮 1 则专司 RGB 色相测试这样无论哪颗旋钮损坏都能被精确定位。四、源码原理编码器回调为何在 keymap 中生效encoder_update_user能在键位文件里直接生效依赖 quantum/encoder.c 提供的弱符号weak symbol机制__attribute__((weak)) bool encoder_update_user(uint8_t index, bool clockwise) { return true; } __attribute__((weak)) bool encoder_update_kb(uint8_t index, bool clockwise) { bool res encoder_update_user(index, clockwise); ... }默认实现返回true不产生任何副作用用户在 keymap 中提供同名强符号实现后链接器自动以用户版本覆盖弱符号从而接管旋钮逻辑encoder_update_kb会先调用encoder_update_user若返回值为真再执行默认行为——未定义EXTRAKEY_ENABLE/MOUSEKEY_ENABLE时默认发送KC_PGDN/KC_PGUP定义EXTRAKEY_ENABLE时默认发送KC_VOLU/KC_VOLD。Ellipse 在 keyboard.json 中开启了extrakey同时自己在回调里返回true因此两个旋钮既执行自定义字母键码又叠加默认音量键行为这正是该键位旋转出字 音量可调双重效果的来源。此外编码器事件通过内部 FIFO 队列encoder_queue_event/encoder_dequeue_event见 quantum/encoder.c逐事件分发多个旋钮并发旋转也不会丢失方向信息。硬件侧三颗旋钮分别挂在 B2/B1、B3/B7、D5/B4 三组引脚上且 keyboard.json 中resolution: 2表示每 2 个脉冲计为一次有效旋转起到硬件抖动抑制的作用。五、源码原理RGB 色相调节的 noeeprom 变体中间旋钮调用的rgblight_increase_hue_noeeprom()/rgblight_decrease_hue_noeeprom()定义于 quantum/rgblight/rgblight.cvoid rgblight_increase_hue_helper(bool write_to_eeprom) { uint8_t hue rgblight_config.hue RGBLIGHT_HUE_STEP; rgblight_sethsv_eeprom_helper(hue, rgblight_config.sat, rgblight_config.val, write_to_eeprom); } void rgblight_increase_hue_noeeprom(void) { rgblight_increase_hue_helper(false); }要点如下色相每次步进RGBLIGHT_HUE_STEP默认值为8见 quantum/rgblight/rgblight.h同样可覆盖的还有RGBLIGHT_SAT_STEP 17、RGBLIGHT_VAL_STEP 17write_to_eeprom参数为false时只改当前内存配置、不写入 EEPROM因此断电重启后色相恢复到上次保存的值——适合测试场景避免反复旋钮把 EEPROM 写穿EEPROM 有写入寿命限制带 EEPROM 写回的版本是rgblight_increase_hue()/rgblight_decrease_hue()中间旋钮通过色相Hue的连续增减驱动 keyboard.json 中led_count: 3的 WS2812 灯珠引脚 E6旋转时肉眼可见颜色沿色环循环变化从而一次验证编码器读数正确 RGB 驱动正常两项硬件。六、矩阵、灯光与编译烧录配置Ellipse Rev1 的完整底层配置集中在 rev1/keyboard.json核心字段如下配置项值说明processoratmega32u4主控芯片bootloaderatmel-dfu引导方式对应:dfu烧录目标matrix_pins.colsF0, B6, B53 列引脚matrix_pins.rowsD3, C72 行引脚diode_directionCOL2ROW二极管方向encoder.rotary3 组{pin_a, pin_b, resolution: 2}旋钮 A/B/C 引脚与分辨率rgblight.led_count3WS2812 灯珠数量ws2812.pinE6灯带数据引脚featuresencoder、extrakey、rgblight等按需裁剪的固件功能编译并烧录该键盘默认键位按键盘 readme 给出的命令make abstract/ellipse/rev1:default:dfuQMK 构建系统会从keyboards/abstract/ellipse/rev1/keyboard.json数据驱动生成矩阵、编码器与 RGB 配置再与keymaps/default/keymap.c中的键位和回调一起编译最后通过 DFU 协议写入主控。注意Rev1 已知存在两个固件层面的小问题——背光呼吸breathing模式不可用以及post_init_user钩子不会被调用见 键盘 readme自定义固件时应避免依赖这两个特性。七、如何基于这套键位做二次定制默认键位是一份极佳的旋钮键盘模板改造成常见用法时只需替换键位表与encoder_update_user旋钮调音量把旋钮 0 的回调改为tap_code(KC_VOLU)/tap_code(KC_VOLD)需启用extrakey旋钮翻页改为tap_code(KC_PGDN)/tap_code(KC_PGUP)中间旋钮改亮度/饱和度将rgblight_*_hue_noeeprom()换成rgblight_increase_val_noeeprom()/rgblight_increase_sat_noeeprom()等系列函数实现均位于 quantum/rgblight/rgblight.c需要保存设置改用不带noeeprom后缀的版本如rgblight_increase_hue()代价是每次旋转都会写 EEPROM。总体而言Ellipse 默认键位以每个输入源输出唯一键码的朴素策略把按键矩阵、三路编码器方向、RGB 色相链路全部纳入一次快速自检流程理解这份键位背后的encoder_update_user弱符号回调与rgblight_*_noeeprom内存态控制也就掌握了 QMK 多旋钮键盘定制与调试的核心手法。【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考