当前位置：首页 > ds >正文

QMK固件中LED指示灯与RGB灯详解指南

ds 2025/5/4 19:00:24

QMK固件中LED指示灯与RGB灯详解指南

前言

欢迎来到这一期关于指示灯和RGB的详细教程。在键盘定制领域，指示灯和RGB功能既是常用的视觉元素，也是设计中较为复杂的部分。本教程将深入介绍QMK固件中指示灯和RGB灯的配置方法，包括基本原理、驱动方式、物理布局以及效果实现等内容。无论您是键盘定制新手还是有经验的玩家，这篇教程都能帮助您实现丰富多彩的灯光效果。

一、指示灯基础

1.1 指示灯分类

指示灯可以分为两种类型：

普通LED指示灯：传统的发光二极管，具有正负极
RGB灯作为指示灯：利用RGB灯实现更丰富的指示效果

1.2 普通LED指示灯工作原理

普通LED指示灯是最基础的发光元件，由一个正极和一个负极组成。工作原理如下：

将LED的正极或负极连接到MCU的引脚上
通过控制MCU引脚的高低电平（高电压或零电压）
在LED形成电流回路，使LED发光

1.3 普通LED指示灯配置

普通LED指示灯的配置非常简单：

在config.h中配置数字锁定键、大写锁定键、滚动锁定键对应的引脚
指定高电平还是低电平时LED亮起
如需自定义指示灯（如Windows锁指示灯），可以自行编写相关代码

二、RGB灯基础知识

2.1 QMK中RGB功能分类

QMK固件中RGB功能分为两种：

RGB Lighting：适用于背光灯，如键盘底部缠绕的灯带，对物理位置没有严格要求
RGB Matrix：RGB矩阵，每个灯都有对应的物理位置，可实现更复杂的效果，常用于轴灯

本教程主要讲解效果更强大的RGB Matrix，而相对简单的RGB Lighting配置可参考后者进行修改适配。

2.2 RGB Matrix使用步骤

使用RGB Matrix的步骤如下：

确定RGB灯的驱动方式
配置MCU的硬件设置
设置RGB灯的矩阵物理位置
选择预设动画效果
添加自定义效果（如RGB指示灯）

三、RGB灯驱动方式

3.1 RGB灯芯片介绍

常用的RGB灯内部集成了WS2812芯片，该芯片负责将MCU发送的信号解码成对应的RGB颜色值。

3.2 主要驱动方式对比

驱动方式	优点	缺点	适用场景
BitBang (bitb)	任何引脚都可使用，配置简单	对性能消耗较高	遇到其他驱动问题时的备选方案
PWM	性能消耗小，效率高	只能用于定时器引脚，配置复杂	追求性能优化的场景
SPI	数据传输快	对引脚限制多	特定MCU和引脚配置
I²C	总线式连接	只适用于AVR主控，占用I²C资源	不推荐用于RGB驱动

实际使用中，bitb和PWM在视觉效果上几乎没有区别。建议优先使用PWM，遇到问题时切换到bitb。

3.3 PWM驱动注意事项

使用PWM驱动需注意以下几点：

PWM只能连接到带有定时器通道的引脚
需查阅芯片数据手册确认引脚复用功能
引脚复用功能中标有"TIMx_CHy"或"TMRx_CHy"的才支持PWM功能
PWM在QMK中使用DMA，但DMA通道有限，可能与其他功能冲突
某些MCU的特定引脚可能与其他功能不兼容

示例：查看F103数据手册，引脚PB8的复用功能包含"TMR4_CH3"，表示可以使用定时器4通道3的输出。

四、RGB Matrix硬件配置

4.1 基础配置项

在config.h中的基础配置：

// RGB灯信号线连接的引脚
#define RGB_DI_PIN B8
// RGB灯总数
#define DRIVER_LED_TOTAL 94

4.2 PWM驱动详细配置

如果使用PWM驱动，需在config.h中添加以下配置（以STM32F103为例）：

// 指定使用PWM驱动
#define WS2812_DRIVER PWM
// 使用的定时器
#define WS2812_PWM_DRIVER PWMD4
// 使用的通道
#define WS2812_PWM_CHANNEL 3
// DMA流（F103中与通道保持一致）
#define WS2812_DMA_STREAM 7
// DMA通道（F103中查阅手册确定）
#define WS2812_DMA_CHANNEL 7

在halconf.h或mcuconf.h中添加：

#ifndef HAL_USE_PWM
#define HAL_USE_PWM TRUE
#endif#ifndef STM32_PWM_USE_TIM4
#define STM32_PWM_USE_TIM4 TRUE
#endif

对于不同MCU，部分配置项可能有所不同，需参考芯片手册进行适配。

五、RGB Matrix物理位置配置

5.1 物理位置原理

QMK将灯光布局放置在224×64的矩形坐标系中：

左上角是(0,0)
右下角是(224,64)
每个灯都有一个明确的坐标位置

对于小键盘或非标准形状键盘，可采用选取坐标系的中间部分来避免动画变形。

5.2 RGB Matrix配置三要素

RGB Matrix配置包括三个关键部分：

按键映射部分：定义每个矩阵位置上的轴灯对应关系
物理位置部分：定义每个灯的具体坐标
分类部分：将灯分类（如轴灯、背光灯、指示灯等）

5.3 配置示例

在keymap.c中添加：

// 1. 按键映射部分 - 每个矩阵位置对应哪个灯
led_config_t g_led_config = {{// Key Matrix to LED Index{ 0,  2,  3,  4,  5,  NO_LED },{ 17, 18, 19, 20, 21, 22 },// ... 其他行},// 2. 物理位置部分 - 每个灯的坐标{// LED Index to Physical Position{ 16, 5 },  // LED 0{ 16, 5 },  // LED 1 (与LED 0在同一位置){ 32, 5 },  // LED 2// ... 其他灯的坐标},// 3. 灯光分类部分{// LED Index to FlagLED_FLAG_KEYLIGHT,     // LED 0 - 轴灯LED_FLAG_KEYLIGHT,     // LED 1LED_FLAG_UNDERGLOW,    // LED 2 - 底灯// ... 其他灯的分类}
};

确定物理位置时，建议：

绘制键盘网格图，标注每行每列的位置
根据公式计算坐标：x = 224/(列数-1) * 当前列，y = 64/(行数-1) * 当前行
按照RGB灯的连接顺序依次填写

六、RGB动画效果配置

6.1 预设动画效果

QMK提供了丰富的预设动画效果，可在config.h中启用：

// 启用循环所有颜色效果
#define ENABLE_RGB_MATRIX_CYCLE_ALL
// 从左到右的动画效果
#define ENABLE_RGB_MATRIX_CYCLE_LEFT_RIGHT
// 按键反馈效果
#define ENABLE_RGB_MATRIX_REACTIVE_SIMPLE

建议仅启用自己需要的动画效果，过多启用可能导致固件过大或切换麻烦。

6.2 自定义RGB指示灯效果

可以使用回调函数自定义RGB灯效果，例如实现Caps Lock指示灯：

bool rgb_matrix_indicators_user(void) {// 大写锁定指示灯if (host_keyboard_led_state().caps_lock) {rgb_matrix_set_color(52, 255, 0, 0); // 将Caps键的灯设为红色}// 层级指示灯 - 当切换到FN层时底灯变绿if (get_highest_layer(layer_state) == 1) { // FN层编号为1for (int i = 0; i < DRIVER_LED_TOTAL; i++) {if (g_led_config.flags[i] & LED_FLAG_UNDERGLOW) {rgb_matrix_set_color(i, 0, 255, 0); // 绿色}}}return false;
}