⌨ QMK 键盘开发指南

操作： 按住 BOOTSEL 插入 USB → 出现 RPI-RP2 U 盘 → 拖 .uf2 固件进去 → 自动重启 ✅
优点： 无需安装任何驱动或工具，跨平台开箱即用。

1. Bootmagic Reset： 默认矩阵 (0,0) 按键（通常左上角）。断开 USB，按住此键再插入即可。

2. 物理按钮： RP2040 的 BOOTSEL、部分 F103 开发板的 BOOT0 跳线/按钮。

3. Keycode QK_BOOT： 键位布局中绑定，按下即进入 Bootloader（无需插拔）。建议放不常用的层避免误触。

最常见的可寻址 RGB LED，单线串联，QMK 内置完整灯效引擎（数十种预设动画）。

硬件接线： DIN → GPIO（串 100-470Ω），VDD → 5V（每颗全白 ~60mA，注意总电流），GND → 共地。建议 DIN 前加电阻、每颗旁并联 0.1μF 电容。

QMK 支持为 Caps Lock / Num Lock / Scroll Lock / 层状态等设置独立 LED 指示灯。
硬件： LED 正极 → GPIO（串 220-1KΩ 限流电阻），负极 → GND。高电平点亮。

支持 SSD1306 驱动的 128x32 / 128x64 OLED，I2C 地址通常 0x3C。可显示当前层、按键状态、自定义动画等。
硬件： SCL → I2C 时钟，SDA → I2C 数据，VCC → 3.3V/5V，GND → 共地。建议 SCL/SDA 加 4.7KΩ 上拉。

外接 I2C 存储用于保存宏、动态键位、用户配置等非易失数据，容量远超芯片内部存储（AVR 仅 1KB，多数 STM32 无内部 EEPROM）。推荐两款引脚兼容、可直接互换的 32KB 芯片：24LC256（EEPROM）与 MB85RC256V（FRAM 铁电存储）。QMK 内置 i2c 驱动，读写 API 与内部 EEPROM 完全一致，后期切换存储介质无需改业务代码。
与 OLED 共用总线： 两芯片均占用 I2C 地址 0x50-0x57（由 A0/A1/A2 引脚决定），与 OLED（0x3C）不冲突，可同挂一条 I2C 总线。

建议 SCL/SDA 加 4.7KΩ 上拉；与 OLED 同挂一条总线时共用上拉即可。

A0/A1/A2 三引脚组合出 8 个地址：全接地为 0x50，随引脚接 VCC 递增，全接 VCC 为 0x57。QMK 的 EXTERNAL_EEPROM_I2C_BASE_ADDRESS 按 8 位地址填写（7 位地址左移一位），默认值 0b10100000（= 0xA0）即对应 7 位地址 0x50。

两芯片引脚兼容、容量同为 32KB、I2C 地址一致，PCB 可直接互换。MB85RC256V 是铁电存储器，写入无需等待、寿命长，适合频繁读写配置 / 宏 / via 动态改键的场景，做动态存储时优先推荐。

QMK 内置对 EEPROM_I2C_MB85RC256V 和 EEPROM_I2C_24LC256 等芯片的预定义配置（完整列表见下方表格）。指定芯片宏后，所有参数（容量、页大小、写入时间、地址宽度等）均由驱动自动填充默认值，无需手动重复配置。唯一需要手动指定的通常是写保护引脚。

// rules.mk 必填：
EEPROM_DRIVER = i2c

// config.h 二选一（按实际焊接）：
//#define EEPROM_I2C_24LC256              // 24LC256 EEPROM（官方默认值）
#define EEPROM_I2C_MB85RC256V          // MB85RC256V FRAM（官方默认值）

// 写保护引脚（强烈建议定义，否则悬空时初始化/写入可能失败）：
#define EXTERNAL_EEPROM_WP_PIN C0        // 接 GPIO 写入，驱动会自动拉低使能

其他容量的 24LC 系列（24LC32/64/128）也可用官方预定义宏：EEPROM_I2C_24LC32A、EEPROM_I2C_24LC64、EEPROM_I2C_24LC128，以及 Cat/RM 系列。

完整文档：QMK Config Options · 源文件：drivers/eeprom/eeprom_i2c.h

通过 ADC 读取滑动电位器（或旋转电位器）的模拟电压，可实现连续参数控制，如音量推子、亮度调节、导播台推子等。
硬件： 电位器两端接 VCC 和 GND，中间抽头接 ADC GPIO。推荐 10KΩ 线性电位器（B10K）。

QMK 的 ADC 读取通过 analog 驱动实现。STM32 平台需要同时修改三个文件才能正确启用 ADC，少一步都读不到数据。

ADC 原始值会有抖动，直接使用会导致输出频繁跳变。实际应用中需要做三件事：

1. 滤波：滑动平均滤波，消除瞬时抖动
2. 映射：把 12-bit (0-4095) 映射到 7-bit MIDI (0-127)，用右移 5 位比乘除法更高效
3. 防抖：设置变化阈值，只有超过阈值才发送；同时处理端点到达

// 12-bit → 7-bit 映射：右移 5 位（4096 >> 5 = 128），比乘除法快得多
uint8_t midi_val = (uint8_t)(adc_val >> 5);

// 如果电位器安装方向与 MIDI 值方向相反，用反转：
uint8_t midi_val = 0x7F - (uint8_t)(adc_val >> 5);

把滑动电位器做成导播台 MIDI 推子：推动电位器时，实时发送对应通道的 MIDI CC 消息。相比机械编码器，电位器推子能直接定位到任意位置，更接近真实调音台的手感。

核心思路： 在 matrix_scan_user() 中周期性读取 ADC → 滑动平均滤波 → 阈值防抖 + 端点检测 → 右移映射到 0-127 → 发送 MIDI CC。需要配合 4.7 章节的 MIDI_ADVANCED 和 extern MidiDevice midi_device;。

以下代码来自实际 10 通道导播台固件，用结构体管理每个推子的全部状态（滤波缓冲区、当前值、上次发送值、CC 编号），比平行数组更清晰、更易扩展。

#include QMK_KEYBOARD_H
extern MidiDevice midi_device;

#define FILTER_WINDOW_SIZE 8       // 滑动平均滤波窗口大小
#define NUM_SLIDERS 10             // 推子数量
#define ADCVar 30                  // 变化阈值（12-bit 下推荐 20-40）

// 用结构体管理每个推子的所有数据
typedef struct {
    uint16_t adcReadings[FILTER_WINDOW_SIZE]; // 独立的滤波缓冲区
    uint8_t  readingIndex;
    uint32_t readingSum;
    uint16_t filteredValue;
    uint16_t lastSentValue;
    uint8_t  midiControlNumber;   // 为该推子指定 MIDI CC 编号
} SliderChannel;

// 初始化推子数组，每个推子指定不同的 CC 编号
SliderChannel sliders[NUM_SLIDERS] = {
    { {0}, 0, 0, 0, 0, 0x0A },    // CC#10
    { {0}, 0, 0, 0, 0, 0x09 },    // CC#9
    { {0}, 0, 0, 0, 0, 0x08 },    // CC#8
    { {0}, 0, 0, 0, 0, 0x07 },    // CC#7（主音量）
    { {0}, 0, 0, 0, 0, 0x06 },    // CC#6
    { {0}, 0, 0, 0, 0, 0x05 },    // CC#5
    { {0}, 0, 0, 0, 0, 0x04 },    // CC#4
    { {0}, 0, 0, 0, 0, 0x03 },    // CC#3
    { {0}, 0, 0, 0, 0, 0x02 },    // CC#2
    { {0}, 0, 0, 0, 0, 0x01 }     // CC#1
};

// 对应的 ADC 引脚数组
const uint32_t adcPins[NUM_SLIDERS] = { A0, A1, A2, A3, A4, A5, A6, A7, B0, B1 };

// 滑动平均滤波：维护一个环形缓冲区，O(1) 更新
uint16_t movingAverageFilter(SliderChannel* channel, uint16_t newReading) {
    channel->readingSum = channel->readingSum
                        - channel->adcReadings[channel->readingIndex]
                        + newReading;
    channel->adcReadings[channel->readingIndex] = newReading;
    channel->readingIndex = (channel->readingIndex + 1) % FILTER_WINDOW_SIZE;
    return (uint16_t)(channel->readingSum / FILTER_WINDOW_SIZE);
}

// 防抖判断：变化超过阈值 OR 到达端点（解决推到底/顶时抖动发不出信号）
int shouldSendMIDI(SliderChannel* channel) {
    uint16_t change = abs(channel->filteredValue - channel->lastSentValue);

    // 主要条件：变化超过阈值
    if (change >= ADCVar) return 1;

    // 辅助条件：确保能到达端点，但避免端点附近微小抖动反复发送
    // 只有上次值离端点较远、当前值非常接近端点时才触发
    if (channel->filteredValue < 5 && channel->lastSentValue > 10) return 1;     // 接近 0
    if (channel->filteredValue > 4090 && channel->lastSentValue < 4080) return 1; // 接近 4095

    return 0;
}

void slider(void) {
    for (int i = 0; i < NUM_SLIDERS; i++) {
        // 1. 读取并滤波（每个通道独立滤波器）
        uint16_t rawValue = analogReadPin(adcPins[i]);
        sliders[i].filteredValue = movingAverageFilter(&sliders[i], rawValue);

        // 2. 判断是否需要发送
        if (shouldSendMIDI(&sliders[i])) {
            // 3. 右移 5 位映射到 0-127，0x7F- 反转方向
            uint8_t midiValue = 0x7F - (sliders[i].filteredValue >> 5);
            // 4. 发送到通道 3（索引 2）
            midi_send_cc(&midi_device, 2, sliders[i].midiControlNumber, midiValue);
            sliders[i].lastSentValue = sliders[i].filteredValue;
        }
    }
}

void matrix_scan_user(void) {
    slider();
}

机械旋转编码器（EC11 系列）通过两路脉冲检测旋转方向和步数，常用于音量调节、菜单滚动。QMK 支持最多 4 个编码器。
硬件： A → GPIO_A，B → GPIO_B，C → GND。A/B 需启用内部上拉。按下中键作为一个独立按键。

QMK 内置 MIDI 设备驱动，键盘插上 USB 后会被操作系统识别为标准 USB MIDI 类设备，可直接控制各类 DAW 或导播台（如 vMix、OBS Studio 配合 MIDI 插件、ATEM 切换台、Stream Deck 替代方案等），无需额外硬件或转换器。

推荐方式：默认只使用自定义 MIDI 信号。即在 process_record_user() 中通过 midi_send_* API 手动发送目标 MIDI 消息，而不是使用 MI_* 基础键码。这样能把任意 MIDI 事件（Note On/Off、CC 控制变化、Pitch Bend 等）自由绑定到任意矩阵按键或机械编码器旋钮，实现导播场景下的：

• 按键：触发切换、播放/暂停、推杆上推/下推等离散动作
• 旋钮/推子：连续调节音量、推子位置、过渡进度、亮度等参数

按下发送 Note On 触发镜头切换，松开发送 Note Off 结束。导播场景中常用 Note 编号对应不同镜头 / 通道。

// 声明 QMK 全局 MIDI 设备实例（自定义信号必需）
extern MidiDevice midi_device;

enum custom_keycodes {
    CAM1 = SAFE_RANGE,   // 镜头 1
    CAM2,                // 镜头 2
};

bool process_record_user(uint16_t keycode, keyrecord_t *record) {
    switch (keycode) {
        case CAM1:
            if (record->event.pressed) {
                // 按下：通道 1 发送 Note 60 (C3)，力度 127
                midi_send_noteon(&midi_device, 0, 60, 127);
            } else {
                // 松开：发送 Note Off 结束
                midi_send_noteoff(&midi_device, 0, 60, 0);
            }
            return false;
        case CAM2:
            if (record->event.pressed) {
                midi_send_noteon(&midi_device, 0, 61, 127);
            } else {
                midi_send_noteoff(&midi_device, 0, 61, 0);
            }
            return false;
    }
    return true;
}

用循环批量定义 8 个按键，每个对应一个 Note 编号。适合导播台的多通道切换、PGM/PVW 切换、快捷键组等场景。

// 8 路通道切换：Note 60-67 对应通道 1-8
enum custom_keycodes {
    CHAN1 = SAFE_RANGE,
    CHAN2, CHAN3, CHAN4,
    CHAN5, CHAN6, CHAN7, CHAN8,
};

bool process_record_user(uint16_t keycode, keyrecord_t *record) {
    // 计算偏移：CHAN1=0, CHAN2=1, ..., CHAN8=7
    if (keycode >= CHAN1 && keycode <= CHAN8) {
        uint8_t offset = keycode - CHAN1;       // 0-7
        uint8_t note   = 60 + offset;            // 60-67
        if (record->event.pressed) {
            midi_send_noteon(&midi_device, 0, note, 127);
        } else {
            midi_send_noteoff(&midi_device, 0, note, 0);
        }
        return false;
    }
    return true;
}

机械编码器旋转时连续发送 CC 消息，模拟导播台推子的连续调节。CC 7 是标准 MIDI 主音量。

// 单个旋钮控制通道 1 主音量（CC 7）
static uint8_t chan1_volume = 64;   // 当前音量值（0-127）

bool encoder_update_user(uint8_t index, bool clockwise) {
    if (index == 0) { // 第一个编码器
        if (clockwise) {
            chan1_volume = (chan1_volume < 127) ? chan1_volume + 1 : 127;
        } else {
            chan1_volume = (chan1_volume > 0) ? chan1_volume - 1 : 0;
        }
        // 发送 CC 7（主音量）到通道 1
        midi_send_cc(&midi_device, 0, 7, chan1_volume);
    }
    return false;
}

用数组管理多个推子的当前值，编码器索引对应不同通道。适合导播台的多路混音推子组。

// 4 路推子：编码器 0-3 分别控制通道 1-4 的音量（CC 7）
static uint8_t fader_values[4] = {64, 64, 64, 64};

bool encoder_update_user(uint8_t index, bool clockwise) {
    if (index < 4) { // 只处理前 4 个编码器
        if (clockwise) {
            fader_values[index] = (fader_values[index] < 127) ? fader_values[index] + 1 : 127;
        } else {
            fader_values[index] = (fader_values[index] > 0) ? fader_values[index] - 1 : 0;
        }
        // 发送 CC 7（主音量）到对应通道（index 0-3 对应通道 1-4）
        midi_send_cc(&midi_device, index, 7, fader_values[index]);
    }
    return false;
}

扩展思路： 实际导播台常需要不同 CC 编号控制不同参数（如 CC 7=音量、CC 10=声像、CC 74=滤波器截止）。可把 fader_values 改为二维数组 fader_values[4][N]，每个编码器同时控制多个参数。