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

QMK自定义4*4键盘固件创建教程：最新架构详解

java 2025/5/13 12:13:47

QMK自定义4*4键盘固件创建教程：最新架构详解

前言

通过本教程，你将学习如何在QMK框架下创建自己的键盘固件。QMK是一个强大的开源键盘固件框架，广泛用于DIY机械键盘的制作。本文将详细介绍最新架构下所需创建的文件及其功能。

准备工作

在开始之前，我们需要理解QMK架构中必须创建的几个核心文件：

info.json：键盘的基本信息配置
config.h：硬件和功能的配置头文件
rules.mk：编译选项和功能开关
<keyboard_name>.c：键盘的主要C源文件
<keyboard_name>.h：键盘矩阵定义的头文件

接下来，我们将一步步实现这些文件的创建。

实操步骤

1. 创建键盘目录

首先导航到QMK固件的keyboards目录：

keyboards目录

2. 创建自定义键盘文件夹

在keyboards目录下创建一个新的文件夹，使用你自定义的键盘名称（本例中使用"despacito0o"）：

创建新文件夹

文件夹创建完成

3. 打开IDE并开始编辑

使用VSCode打开刚创建的文件夹（可以直接将文件夹拖到VSCode图标上）：

打开VSCode

4. 创建rules.mk文件

首先创建rules.mk文件，这是编译选项和功能开关的配置文件：

创建rules.mk

rules.mk示例

在rules.mk文件中写入以下内容：

MCU = STM32F103          # 主控型号，使用的是 STM32F103 微控制器
BOOTLOADER = stm32duino  # 启动加载器类型，使用 stm32duino 引导程序
NKRO_ENABLE = yes        # 启用 NKRO (N-Key Rollover)，支持多键同时按下
EXTRAKEY_ENABLE = yes    # 启用额外按键功能，例如媒体键(用键盘控制音量大小等)
# LTO_ENABLE = yes        # 是否启用链接时优化 (Link Time Optimization)，暂时不需要注释掉

rules.mk文件说明

rules.mk文件是QMK的顶级Makefile，用于设置关于MCU的信息以及启用/禁用特定功能。主要包含：

构建选项：指定默认文件夹、固件格式等
功能开关：通过设置yes/no来启用或禁用功能
MCU选项：设置微控制器类型、时钟频率等
编译优化：如LTO_ENABLE可显著减少编译大小

5. 创建键盘头文件

接下来创建键盘的.h头文件（使用你的键盘名称）：

创建头文件

在头文件中添加以下内容：

#pragma once // 防止头文件被重复包含#include "quantum.h" // 包含 QMK 的核心头文件

键盘头文件说明

该头文件用于定义键盘的矩阵布局。应至少定义一个C宏，将数组转换为代表键盘物理开关矩阵的矩阵。如果你的键盘可以构建多种布局，则应定义多个宏。

对于单一布局，应使用LAYOUT宏
对于多布局键盘，应有一个支持所有可能开关位置的基本布局LAYOUT_all，以及其他特定布局如LAYOUT_ansi、LAYOUT_iso等

6. 创建键盘C源文件

创建键盘的主C源文件（使用你的键盘名称）：

创建C源文件

添加以下内容：

#include "Despacito0o.h" // 包含键盘的头文件(使用你自定义的名称)

7. 创建config.h文件

创建config.h配置文件：

创建config.h

添加以下内容：

#pragma once // 防止头文件被重复包含#define MATRIX_ROWS 4 // 定义矩阵的行数
#define MATRIX_COLS 4 // 定义矩阵的列数
#define MATRIX_ROW_PINS {B3, A1 , A2 , A3} // 定义行引脚
#define MATRIX_COL_PINS {A4, A15, A14, A8} // 定义列引脚
#define DIODE_DIRECTION COL2ROW // 定义二极管方向为列到行

config.h文件说明

config.h是最先被包含的C头文件，其中设置的变量会在整个项目中持续存在。主要配置内容包括：

硬件选项：VID/PID、设备版本、厂商信息等
矩阵配置：行列数、引脚定义、二极管方向等
功能配置：背光、音频、RGB灯效、防抖等
键盘行为：按键触发时间、组合键设置等

8. 创建键盘映射文件

创建键盘映射的文件结构：先创建keymaps文件夹，然后在其中创建default文件夹，最后在default文件夹中创建keymap.c文件：

创建keymap.c

在keymap.c中添加以下内容：

#include  QMK_KEYBOARD_Hconst uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {[0] = LAYOUT(MI_B2  , KC_Q   , KC_W,  MI_C3  ,  // 第一行按键映射MI_F2  , MI_G2  , MI_A2, MI_OCTU, // 第二行按键映射MI_C2  , MI_D2  , MI_E2, MI_OCTD, // 第三行按键映射KC_PSLS, MI_OCTD, MO(1), KC_PENT  // 第四行按键映射，包含层切换按键MO(1)),[1] = LAYOUT(QK_BOOT, KC_P8 , RGB_MOD, RGB_TOG, // 第二层第一行：包含重启引导和RGB控制KC_P4  , KC_G  , KC_A   , KC_PAST, // 第二层第二行KC_P1  , KC_P2 , KC_P3  , KC_PMNS, // 第二层第三行KC_PSLS, KC_P0 , KC_PDOT, KC_PENT  // 第二层第四行)
};

9. 创建键盘JSON配置文件

最后，创建一个keyboard.json文件（注意JSON文件中不能有注释）：

创建keyboard.json

添加以下内容：

{"keyboard_name": "Despacito0o", "manufacturer": "Despacito0o", "usb": {"vid": "0x1564", "pid": "0x8456", "device_version": "0.0.1" },"layouts": {"LAYOUT": {"layout": [{"matrix": [0, 0], "x": 0, "y": 0}, {"matrix": [0, 1], "x": 1, "y": 0}, {"matrix": [0, 2], "x": 2, "y": 0}, {"matrix": [0, 3], "x": 3, "y": 0}, {"matrix": [1, 0], "x": 0, "y": 1}, {"matrix": [1, 1], "x": 1, "y": 1}, {"matrix": [1, 2], "x": 2, "y": 1}, {"matrix": [1, 3], "x": 3, "y": 1}, {"matrix": [2, 0], "x": 0, "y": 2}, {"matrix": [2, 1], "x": 1, "y": 2}, {"matrix": [2, 2], "x": 2, "y": 2}, {"matrix": [2, 3], "x": 3, "y": 2}, {"matrix": [3, 0], "x": 0, "y": 3}, {"matrix": [3, 1], "x": 1, "y": 3}, {"matrix": [3, 2], "x": 2, "y": 3}, {"matrix": [3, 3], "x": 3, "y": 3}  ]}}
}