QMK 固件中的 Binepad NEOKNOB KN01多功能旋钮设备的构建、配列与编码器实现全解【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmwareBinepad NEOKNOB KN01 是一款单键多功能旋钮设备它可以旋转、按压还可以在按压的同时旋转。本文以 QMK 固件仓库中该键盘的官方文档与配置为骨架结合keyboards/binepad/kn01/下的真实配置和底层编码器/Bootmagic 驱动源码完整讲解 KN01 的构建烧录流程、逐层编码器映射encoder_map配置以及旋钮背后的正交编码器解码原理读完后可独立完成此类编码器类小设备的 QMK 开发。一、设备概览一台“一个键”的设备KN01 文档定义了这台设备的三种交互形态旋转rotate、按压press、按压时旋转rotate while pressed。这三种形态分别对应三类输入源编码器encoder负责旋转与“按压时旋转”两种行为由ENCODER_ENABLE驱动解码键矩阵key matrix负责按压行为KN01 只有一个矩阵开关组合映射文档给出的默认配列中“按压时旋转”通过LTlayer tap把按键行为与编码器所在层联动实现。1.1 keyboard.json 中的硬件事实boards 定义文件 keyboards/binepad/kn01/keyboard.json 是 QMK 数据驱动的键盘描述KN01 的关键字段如下配置项取值含义processorSTM32F103主控为 STM32F103 系列 ARM MCUbootloaderstm32duino使用 STM32 DFU 官方引导加载器刷机时进入 DFU 模式matrix_pinscols: [A15],rows: [A8]单行单列键矩阵仅 1 个物理按键diode_directionCOL2ROW二极管方向为“列到行”encoder.rotarypin_a: B3,pin_b: B4旋转编码器 A/B 相引脚featuresbootmagic、encoder、extrakey、mousekey启用的固件特性usb.vid/usb.pid0x4249/0x4040该设备的 USB 厂商号/产品号layoutsLAYOUT_ortho_1x1布局为 1×1 ortho占位 2×2几个值得注意的点单键设备也走完整的矩阵扫描A8行与A15列构成 1×1 矩阵QMK 的通用矩阵扫描器无需特判即可工作bootmagic: true是“按住旋钮再插 USB 进 DFU”这一刷机方式的固件基础见第四节extrakey与mousekey的开启解释了默认配列为什么能使用KC_VOLD多媒体音量键和MS_WHLU/MS_WHLD鼠标滚轮这类非普通字母键码community_layouts: [ortho_1x1]表明该布局与 QMK 社区标准 ortho_1x1 布局兼容方便在 Web 配列工具中直接渲染。维护者信息maintainer 为 Binpad与硬件销售渠道均记载于 readme.md。二、构建与烧录文档给出的两条核心命令在配置好 QMK 构建环境之后# 编译默认配列固件 make binepad/kn01:default # 编译并烧录 make binepad/kn01:default:flash其中binepad/kn01即仓库内 keyboards/binepad/kn01/ 的路径default对应 keymaps/default/keymap.json 这个数据驱动配列。由于bootloader配置为stm32duino烧录流程为先进入 STM32 DFU 模式三种进入方式见第四节设备以 USB DFU 设备呈现随后 make 目标调用dfu-util完成写 Flash。固件的 USB 标识为 VID0x4249/ PID0x4040device_version1.0.0在 Linux 下可据此编写 udev 规则匹配该设备。构建环境搭建可参考 QMK 官方文档中的 build tools 与 make guide 章节见仓库文档 getting_started_make_guide.md初学者入口为 newbs 指南。三、默认配列一个按键如何同时承担音量与滚轮3.1 keymap.json 的完整配置KN01 的默认配列采用 JSON 数据驱动格式完整内容见 keyboards/binepad/kn01/keymaps/default/keymap.json其结构可拆为四部分{ config: { features: { encoder_map: true } }, encoders: [ [ { ccw: KC_VOLD, cw: KC_VOLU } ], [ { ccw: MS_WHLD, cw: MS_WHLU } ] ], layers: [ [LT(1, KC_MUTE)], [_______] ], layout: LAYOUT_ortho_1x1, version: 1 }config.features.encoder_map: true启用逐层编码器映射。开启后encoders数组按层组织每个层的每个编码器条目独立指定顺时针cw与逆时针ccw行为layers[0]唯一键位为LT(1, KC_MUTE)—— 单击触发KC_MUTE静音/取消静音同时按住时切换到 Layer 1layers[1]占位符_______即 Layer 1 上不覆盖任何普通按键但编码器映射仍然生效组合效果松手旋转 → 调节音量KC_VOLU/KC_VOLD按住旋钮旋转 → 滚动鼠标滚轮MS_WHLU/MS_WHLD。这正是文档所说 “rotated, pressed, and rotated while pressed” 的第三种形态的落地方式。3.2 逐层编码器映射的底层机制encoder_map特性对应固件宏ENCODER_MAP_ENABLE。从 quantum/action_layer.c 源码结构看QMK 在获取“当前层的编码器动作”时区分两种路径未启用ENCODER_MAP_ENABLE时对所有层复用编码器默认映射启用后各层可以携带独立的编码器键码表当前活动层切换后同一物理旋钮的 cw/ccw 行为随之改变。ENCODER_MAP_ENABLE同时影响 quantum/action.c 中与换边swap hands相关的编码器处理逻辑。这也解释了为什么 Layer 1 的_______不占用任何键位却依然能“拦截”旋转输入——旋钮行为根本不经过按键矩阵而是由编码器映射层直接分发的。四、编码器驱动旋钮旋转如何变成事件4.1 正交解码原理旋钮由标准正交quadrature编码器构成A/B 两相引脚KN01 上为B3/B4随旋转以 90° 相位差翻转。QMK 的默认编码器驱动实现在 drivers/encoder/encoder_quadrature.c引脚初始化encoder_quadrature.c#L42-L55默认实现将 A/B 相配置为带内部上拉的输入gpio_set_pin_input_high随后encoder_wait_pullup_charge()等待 100µs 让上拉电容充电稳定避免首读抖动状态机encoder_quadrature.c#L70-L73每个编码器维护一个 4 位状态encoder_state记录最近两次 A/B 组合配合查表encoder_LUT[16]得到 ±1/0 的方向增量即经典的 Gray 码正交解码分辨率encoder_quadrature.c#L20-L22ENCODER_RESOLUTION默认值为 4意味着积累 4 个增量1 个完整电码周期才通过encoder_queue_event()向上层报一次ENCODER_CLOCKWISE/ENCODER_COUNTER_CLOCKWISE事件从而抑制单次误触发方向翻转定义ENCODER_DIRECTION_FLIP可整体交换 cw/ccw 语义encoder_quadrature.c#L63-L69适配物理安装方向轮询encoder_quadrature.c#L207-L211encoder_driver_task()在主循环中周期性读取全部编码器引脚并推进状态机。4.2 与 keymap.json 的衔接驱动上报的 cw/ccw 事件被动作层查表为键码默认分辨率下每转一格触发一次KC_VOLU或KC_VOLD对应keymap.json中encoders[0]的定义。若用户觉得步进太粗或太细可在配列的rules.mk中通过ENCODER_RESOLUTION调整——这是文档未展开、但源码直接支持的调参入口。五、三种进入引导加载器Bootloader的方式KN01 文档 列出的三种进 Bootloader 方式Bootmagic reset按住旋钮不松手同时插入 USB 线物理复位键短按 PCB 底面的复位按钮布局中的键码若配列中存在映射到QK_BOOT的键按下即可。5.1 Bootmagic 的源码实现方式 1 由 quantum/bootmagic/bootmagic.c 支撑keyboard.json中features.bootmagic: true使能了它。调用链如下固件启动后quantum/keyboard.c#L443 在初始化阶段调用bootmagic()bootmagic_scan()bootmagic.c#L63-L72检查bootmagic_should_reset()——即上电时第一矩阵键KN01 上就是旋钮本身是否处于按下状态判定为真时调用bootmagic_reset_eeprom()bootmagic.c#L35清空 EEPROM 后复位微控制器在复位窗口内由 DFU 固件接管设备以stm32duinoSTM32 DFU身份枚举等待make ...:flash写入。5.2 QK_BOOT 键码方式 3 依赖 QMK 内置的QK_BOOT键码按下时固件直接复位进入 DFU 模式。KN01 默认配列并未占用它唯一键位给了LT(1, KC_MUTE)但若把keymap.json中的键改为QK_BOOT或增加一个映射即可获得纯软件方式的进 Bootloader 手段——对只有单键的设备而言尤其实用因为物理复位键方式 2位于 PCB 底部日常操作不便。六、小结与扩展方向KN01 虽小却覆盖了 QMK 中一类典型“非键盘”设备的完整链路数据驱动的 keyboard.json 声明硬件、keymap.json 声明逐层行为、编码器驱动完成物理解码、Bootmagic/DFU 保证刷机可达。基于此可以做三类常见扩展用ENCODER_RESOLUTION调整旋转步进粒度用ENCODER_DIRECTION_FLIP修正安装方向导致的旋转方向相反在更多层中定义不同的encoders条目把同一个旋钮在语音/媒体/导航等场景间复用——这正是encoder_map特性设计的目标用法。【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考