QMK固件旋钮编码器（Rotary Encoder）完全指南
QMK固件旋钮编码器（Rotary Encoder）完全指南
一、旋钮编码器简介
旋钮编码器是一种可旋转的输入设备，常用于音量调节、光标移动等交互场景。在自定义键盘中，它可以大大提升操作效率和用户体验。QMK固件原生支持EC11等常见的旋钮编码器，本文将详细介绍如何在自定义键盘中配置和使用旋钮编码器。
二、硬件连接
旋钮编码器的硬件连接非常简单：
- 编码器的A和B引脚直接连接到MCU的GPIO引脚
- 编码器的C/公共引脚接地（GND）
三、启用编码器功能
在QMK中，有两种方式启用编码器功能：
3.1 传统方式（rules.mk）
在rules.mk文件中添加：
ENCODER_ENABLE = yes
3.2 推荐方式（info.json）
QMK的发展趋势是使用info.json配置，所以建议在info.json文件的features部分添加：
{
"features": {
"encoder": true
}
}
四、配置编码器引脚
4.1 传统方式（config.h）
在config.h中定义编码器引脚：
#define ENCODER_A_PINS { B12 }
#define ENCODER_B_PINS { B13 }
4.2 推荐方式（info.json）
在info.json中配置：
{
"encoders": {
"rotary": [
{
"pin_a": "A9",
"pin_b": "A10",
"resolution": 4
}
]
}
}
这里的配置说明：
pin_a和pin_b：对应编码器的A和B引脚连接到MCU的哪个引脚resolution：指主控收到多少个脉冲触发一次动作，通常EC11编码器填4即可
如果有多个编码器，可以在rotary数组中添加多组配置。
五、编码器映射功能配置
有两种方式配置编码器的功能：编码器映射（Encoder Map）和回调函数（Callback）。建议使用编码器映射方式，因为它可读性更好，并且与VIA/VIAL兼容。
5.1 启用编码器映射
在键盘布局目录下的rules.mk中添加：
ENCODER_MAP_ENABLE = yes
5.2 配置编码器映射
在keymap.c中添加编码器映射配置：
#if defined(ENCODER_MAP_ENABLE)
const uint16_t PROGMEM encoder_map[][NUM_ENCODERS][NUM_DIRECTIONS] = {
[0] = { ENCODER_CCW_CW(KC_VOLD, KC_VOLU) }, // 基础层：逆时针降低音量，顺时针增加音量
[1] = { ENCODER_CCW_CW(KC_LEFT, KC_RIGHT) }, // 第一层：逆时针左方向键，顺时针右方向键
};
#endif
说明：
[0]、[1]表示键盘的不同层ENCODER_CCW_CW中的两个参数分别是逆时针旋转和顺时针旋转的功能- 如果有多个编码器，可以在每层的花括号中用逗号分隔添加更多配置
六、高级配置选项
6.1 调整分辨率
可以在config.h中调整编码器分辨率：
#define ENCODER_RESOLUTION 4
也可以为每个编码器单独设置分辨率：
#define ENCODER_RESOLUTIONS { 4, 2 }
6.2 反转旋转方向
如果编码器旋转方向不符合预期，可以在config.h中添加：
#define ENCODER_DIRECTION_FLIP
6.3 设置默认位置
对于4×编码器，如果在改变方向时跳过脉冲，可以设置默认位置：
#define ENCODER_DEFAULT_POS 0x3
6.4 分体键盘配置
分体键盘的左右两侧可以使用不同的编码器配置：
#define ENCODER_A_PINS_RIGHT { B12 }
#define ENCODER_B_PINS_RIGHT { B13 }
#define ENCODER_RESOLUTIONS_RIGHT { 4 }
七、多编码器共享引脚
在某些情况下，可以让多个编码器共享引脚以节省GPIO资源：
#define ENCODER_A_PINS { B1, B1 }
#define ENCODER_B_PINS { B2, B3 }
这种配置允许使用3个引脚支持2个编码器，但要注意：
- 必须使用带有止动点(Detent)的编码器
- 不能同时转动共享引脚的两个编码器
甚至可以使用三个引脚支持三个编码器：
#define ENCODER_A_PINS { B1, B1, B2 }
#define ENCODER_B_PINS { B2, B3, B3 }
但此时同时旋转共享引脚的编码器可能会产生不正确的输出。
八、回调函数方式（可选）
如果不使用编码器映射，也可以通过回调函数配置编码器：
在keymap.c中：
bool encoder_update_user(uint8_t index, bool clockwise) {
if (index == 0) { // 第一个编码器
if (clockwise) {
tap_code(KC_PGDN);
} else {
tap_code(KC_PGUP);
}
} else if (index == 1) { // 第二个编码器
if (clockwise) {
rgb_matrix_increase_hue();
} else {
rgb_matrix_decrease_hue();
}
}
return false; // 返回false会覆盖键盘级函数
}
九、常见问题与故障排查
- 编码器不响应：检查A、B引脚连接和定义是否正确
- 旋转方向反了：交换A、B引脚定义或使用
ENCODER_DIRECTION_FLIP - 旋转不平滑：调整
ENCODER_RESOLUTION值 - 变更配置后不生效：记得重新编译并刷写固件
十、实用编码器功能推荐
- 音量控制：
KC_VOLU/KC_VOLD - 滚动页面：
KC_PGUP/KC_PGDN - 媒体控制：
KC_MNXT/KC_MPRV - RGB控制：
RGB_HUI/RGB_HUD - 缩放控制：
KC_WH_U/KC_WH_D配合按键修饰符
总结
旋钮编码器是提升自定义键盘功能性的绝佳方式，通过QMK固件可以轻松配置各种实用功能。希望本指南能帮助你在自己的键盘项目中顺利使用旋钮编码器！
参考资料：
- QMK官方文档-编码器
- EC11编码器数据手册