企业官网建设流程全解析

QMK 中 Skeletyl 分体键盘的构建、烧录与配置全解

【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware

Skeletyl 是 BastardKB 系列中一款 3×5 配列的分体式（split）机械键盘，收录于 QMK 固件仓库。本文以 keyboards/bastardkb/skeletyl/readme.md 为骨架，结合仓库中该键盘的完整数据驱动配置（info.json、keyboard.json）与板级配置头文件，讲清它的双硬件版本（Blackpill / Pro Micro 兼容板）如何构建、烧录，以及矩阵、RGB、分体串口、Bootloader 与默认键位的底层实现细节。读完本文，你可以独立完成 Skeletyl 的固件构建、烧录、进 Bootloader 操作，并理解其配置文件的每一项含义。

硬件版本与硬件组成

原始文档给出的硬件支持说明为：Skeletyl 使用 BastardKB 的 Blackpill 或 Pro Micro 适配器（及兼容开发板），维护者为 Quentin Lebastard，硬件资料托管于 BastardKB 的 Skeletyl 项目。仓库中该键盘目录下确实存在两个并行的开发板变体：

• keyboards/bastardkb/skeletyl/blackpill/：基于 STM32F411CE 的 Blackpill 适配器版本；
• keyboards/bastardkb/skeletyl/promicro/：基于 Elite-C 形态开发板的版本（即 Pro Micro 兼容的 Elite-C 插座板）。

两种版本在 info.json 中共享同一份键盘级描述：

• 二极管方向为ROW2COL；
• 启用的固件特性：bootmagic、extrakey、mousekey、rgb_matrix；
• USB 描述符使用自定义 PID0x1830，设备版本 2.0.0；
• split.enabled = true，即分体键盘，左右两个半区通过串口互连。

两个变体的差异体现在各自的 keyboard.json 中：

来源文件分别为 blackpill/keyboard.json 与 promicro/keyboard.json。可以看出两版固件的矩阵完全一致（4 行 × 5 列，每半区），只是引脚映射随 MCU 更换而不同。

构建与烧录命令

原始文档给出的构建与烧录示例命令如下，在配置好 QMK 构建环境后执行：

# 构建固件 make bastardkb/skeletyl/blackpill:default make bastardkb/skeletyl/promicro:default # 构建并烧录 make bastardkb/skeletyl/blackpill:default:flash make bastardkb/skeletyl/promicro:default:flash

命令结构遵循 QMK 标准的make <keyboard>/<version>:<keymap>[:flash]形式，其中blackpill与promicro是同一键盘bastardkb/skeletyl下的两个开发板变体名，default对应 keyboards/bastardkb/skeletyl/keymaps/default/ 中的默认键位目录，flash目标会在构建完成后自动调用对应平台的烧录工具（STM32 版本走 Blackmagic Probe/OpenOCD 一类工具，Elite-C 版本走 UF2 或 CMSIS-DAP 路径）。

文档中特别指出的一点值得注意：如果你使用的是 Elite-C 兼容的开发板，可以通过底座上的引脚来设置左右手，方法在 keyboards/bastardkb/readme.md 的 "Handedness Pin on Elite-C Holder" 一节有说明（原始 readme 的相对链接即指向该处）。

矩阵结构与 LAYOUT_split_3x5_3

从 info.json 的layouts字段看，Skeletyl 的主布局是LAYOUT_split_3x5_3：每半区 3 行 × 5 列正装键加 3 个拇指键，共 18 键 × 2 = 36 键，并声明了community_layouts: ["split_3x5_3"]，即与仓库中通用社区布局split_3x5_3几何兼容。

以矩阵坐标 [行, 列] 表示的位置如下（左半区 + 右半区）：

• 行 0~2 × 列 0~4：正装区 3×5 主键区；
• 拇指区（行 3，仅占部分列）：左半区为[3,2] [3,3] [3,0]（物理位置左→右），右半区为[7,0] [7,3] [7,2]——右半区行号整体 +4（4~7），这是 QMK 分体键盘将两半区矩阵纵向拼接的惯例。

矩阵维度为 8 行（4 行/半区 × 2）× 5 列，与两份 keyboard.json 中 rows/cols 的数量一致；diode_direction: ROW2COL表示二极管阳极接行线、阴极接列线，扫描方向由行到列。

RGB 灯效：每半区 18 颗 WS2812

info.json中rgb_matrix段完整定义了灯条：

• 驱动为ws2812；
• split_count: [18, 18]：左右半区各 18 颗灯，共 36 颗；
• max_brightness: 50、sleep: true（休眠时关灯）。

layout数组把每颗灯锚定到最近的矩阵键位（matrix字段）并给出相对坐标，例如左半区灯沿键位[0,0] [0,1] ... [2,3]分布，拇指区三颗灯位于[3,2] [3,3] [3,0]，右半区对称锚定在行 4~7。flags: 4表示灯朝右、flags: 1表示朝下，供 RGB 引擎在键位间做平滑渐变插值时判断方向。

Blackpill 版本中灯条由 PWM + DMA 驱动，具体配置见 blackpill/config.h：

#define WS2812_PWM_DRIVER PWMD2 #define WS2812_PWM_CHANNEL 2 #define WS2812_PWM_PAL_MODE 1 #define WS2812_EXTERNAL_PULLUP #define WS2812_PWM_DMA_STREAM STM32_DMA1_STREAM1 #define WS2812_PWM_DMA_CHANNEL 3

即 WS2812 数据（keyboard.json 中为 A1 脚，复用到 TIM2/PWMD2 通道 2），使用 DMA 搬运避免 CPU 逐位等待，并声明外部上拉（WS2812_EXTERNAL_PULLUP），这是因为 Blackpill 适配器的电平/驱动能力需要板载上拉配合。对应的定时器使能在 blackpill/mcuconf.h 中开启（STM32_PWM_USE_TIM2），HAL 层 PWM/串口/SPI 驱动在 blackpill/halconf.h 中统一打开。Promicro 版本的 WS2812 则直接接 D3（keyboard.json 指定），走 Elite-C 开发板的通用 WS2812 引脚实现。

分体串口与左右手识别

分体键盘的左右半区必须交换扫描数据。两个版本的实现不同：

Blackpill 版本：keyboard.json 指定split.serial.driver = usart、引脚A9，split.handedness.pin = A3——左右半区插同一份固件时，用 A3 的输入电平区分左右手，串口用 USART1（在 mcuconf.h 中使能STM32_SERIAL_USE_USART1）。

Promicro（Elite-C）版本：keyboard.json 只给出split.serial.pin = D2，没有配置 handedness 引脚。原始 readme 在此处的提示正是关键：使用 Elite-C 兼容板时，可改用底座 F1 引脚来识别左右手。按 keyboards/bastardkb/readme.md 的说明，BastardKB 的 Elite-C 底座支持“引脚定左右手”，前提是所用 Elite-C 兼容开发板引出了底部 5 个引脚并安装了相应电阻，然后在键位目录中自行添加：

# rules.mk PIN_COMPATIBLE = elite_c

// config.h #pragma once #define SPLIT_HAND_PIN F1 #define SPLIT_HAND_PIN_LOW_IS_LEFT

PIN_COMPATIBLE = elite_c让构建系统把 F1 等 Elite-C 引脚名解析到对应开发板；SPLIT_HAND_PIN_LOW_IS_LEFT表示 F1 读到低电平时当前半区按左手处理。这套“引脚定左右手”方案让用户左右半区可以刷同一份固件、互换时自动纠正，而不必区分 left/right 固件。

Blackpill 版的外置 SPI EEPROM

Blackpill（STM32F411CE）Flash 有限，因此该版本额外挂了一颗 SPI EEPROM 存放 QMK 运行时数据（键位、编码器校准、RGB 配置等）。相关配置链条完整可见：

• blackpill/keyboard.json："eeprom": {"driver": "spi"}；
• blackpill/config.h：SPI1 信号线定义——SCK=A5、MOSI=A7、MISO=A6（均为 PAL 模式 5），片选EXTERNAL_EEPROM_SPI_SLAVE_SELECT_PIN = A4；
• blackpill/mcuconf.h：STM32_SPI_USE_SPI1 = TRUE。

这也解释了默认键位里为何有EE_CLR（EEPROM 恢复出厂）键，详见下文。

进入 Bootloader 的三种方式

原始文档 “Bootloader” 一节列出的三种方式完整继承如下：

1. Bootmagic reset：按住矩阵 (0,0) 位置的键再插入键盘——即左半区 Q 键（布局左上角）。此能力由 info.json 中bootmagic: true特性支持；
2. 物理复位按键：短按适配器 PCB 背面的 reset 按钮；
3. 键位法：若布局中映射了QK_BOOT键，直接按下即可。

Skeletyl 的默认键位中确实映射了QK_BOOT（见下一节第 3 层），因此三种方式对本键盘均可用。

默认键位解析

默认键位采用 JSON 键位描述，见 keyboards/bastardkb/skeletyl/keymaps/default/keymap.json，声明布局为LAYOUT_split_3x5_3，共三层：

• Layer 0（QWERTY 基础层）：标准 QWERTY 键位；拇指区为KC_LGUI, MO(1), KC_SPC | KC_ENT, MO(2), KC_RALT，拇指中键分别切换到第 1、2 层；
• Layer 1（数字/符号层）：上排 1-0 数字，中行符号（! @ # $ % 等），其余_______透传下层；
• Layer 2（系统/RGB 层）：左拇指区放置QK_BOOT（进 Bootloader）与EE_CLR（清空 EEPROM，对应 Blackpill 外置 SPI EEPROM 的复位用途）；右拇指区集中了 RGB 矩阵控制码RM_VALU / RM_HUEU / RM_SATU / RM_NEXT / RM_TOGG（上排）与RM_VALD / RM_HUED / RM_SATD / RM_PREV（下排），可直接在键盘上调节亮度、色相、饱和度并切换/开关灯效——这正与 info.json 启用的rgb_matrix特性对应。

小结

Skeletyl 在 QMK 中是一个典型的数据驱动 + 双开发板变体键盘：info.json 定义共享的矩阵几何、RGB 与 USB 描述，两个 keyboard.json 分别把矩阵、串口、灯条引脚落到blackpill_f411与elite_c开发板，Blackpill 版再用 config.h、mcuconf.h 补齐 WS2812 DMA、SPI EEPROM 等 STM32 外设细节。构建烧录只需两条make bastardkb/skeletyl/<版本>:default[:flash]命令；Elite-C 用户还能通过底座 F1 引脚实现“同固件识别左右手”。以上信息均可在keyboards/bastardkb/skeletyl/目录及其上级 keyboards/bastardkb/readme.md 中逐项核对。

【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware