QMK 固件中的 CannonKeys Acheron Sagittarius 键盘支持解析与构建指南【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmwareSagittarius 是 CannonKeys 与 Acheron 合作推出的一款基于 STM32F072 的机械键盘本文以其在 QMK 固件仓库中的官方支持为主线讲解该键盘的硬件配置、固件构建方法、默认键位与四编码器实现原理。读者读完可以掌握如何在本仓库中定位该键盘的完整配置、使用make编译默认固件并理解其矩阵、背光、RGB 与编码器在源码层面的工作方式。键盘基本信息与维护信息根据 keyboards/cannonkeys/sagittarius/readme.md 的官方说明键盘名称CannonKeys Acheron Sagittarius维护者Keyboard MaintainerAndrew KannanGitHub 用户名为 awkannan支持的硬件Hardware SupportedSTM32F072CBT6在 keyboards/cannonkeys/sagittarius/keyboard.json 中还可以找到更完整的元数据keyboard_nameSagittariusmanufacturerCannonKeysmaintainerawkannanprocessorSTM32F072bootloaderstm32-dfuusb.vid0xCA04usb.pid0x0001device_version0.0.1从这些配置可以看出该键盘使用 STM32F072 系列 MCU并通过 STM32 的 DFUDevice Firmware Upgrade模式进行固件烧录。构建默认固件在设置好 QMK 构建环境之后构建该键盘默认固件的命令为make cannonkeys/sagittarius:default该命令会以keyboards/cannonkeys/sagittarius目录为键盘根目录编译keymaps/default下的默认键位配置。构建环境的搭建与make用法可以参考仓库内文档构建环境搭建docs/getting_started_build_tools.mdmake 使用指南docs/getting_started_make_guide.md若你是 QMK 新手建议先阅读 docs/newbs.md 完整入门指南另外keyboards/cannonkeys/sagittarius/rules.mk 中有一行特殊配置# Wildcard to allow APM32 MCU DFU_SUFFIX_ARGS -v FFFF -p FFFF该配置为 DFU 后缀校验参数设置了通配符 VID/PIDFFFF使得固件烧录工具在生成 DFU 文件时不再强制校验特定厂商与产品 ID从而兼容 APM32 等兼容 MCU 的烧录场景。矩阵与引脚配置keyboards/cannonkeys/sagittarius/keyboard.json 中通过数据驱动方式定义了完整的矩阵列引脚colsA7, A5, A4, A3, A2, A1, A0, B5, A13, B2, B1, B0, B9, B8, B7, B6共 16 列行引脚rowsB10, B14, A8, A9, A10, C13, C14, C15, F0, F1共 10 行二极管方向diode_directionCOL2ROW即二极管方向为列到行是当前大多数现代键盘的扫描方向矩阵共 16×10 160 个扫描点而实际布局仅使用了其中一部分这与布局中的键位矩阵坐标一一对应。背光、RGB 与指示灯背光Backlight在keyboard.json中backlight: { pin: A6, levels: 6, breathing: true }背光使用 A6 引脚支持 6 级亮度调节与呼吸效果。底层 PWM 配置位于 keyboards/cannonkeys/sagittarius/config.h#define BACKLIGHT_PWM_DRIVER PWMD3 #define BACKLIGHT_PWM_CHANNEL 1 #define BACKLIGHT_PAL_MODE 1对应地keyboards/cannonkeys/sagittarius/mcuconf.h 中使能了 TIM3 的 PWM 输出#undef STM32_PWM_USE_TIM3 #define STM32_PWM_USE_TIM3 TRUERGB 灯效rgblight WS2812RGB 部分在keyboard.json中声明了 8 颗 RGB LED并启用了呼吸、彩虹流动、彩虹漩涡、贪吃蛇、骑士、圣诞、静态渐变、RGB 测试、交替与闪烁共 10 种动画效果rgblight: { led_count: 8, animations: { breathing: true, rainbow_mood: true, rainbow_swirl: true, snake: true, knight: true, christmas: true, static_gradient: true, rgb_test: true, alternating: true, twinkle: true } }WS2812 灯带通过 SPI 驱动数据引脚为 B15ws2812: { pin: B15, driver: spi }SPI 驱动的底层配置同样在 config.h#define WS2812_SPI_DRIVER SPID2 #define WS2812_SPI_MOSI_PAL_MODE 0 #define WS2812_SPI_SCK_PAL_MODE 0 #define WS2812_SPI_SCK_PIN B13并使用 mcuconf.h 使能 SPI2#undef STM32_SPI_USE_SPI2 #define STM32_SPI_USE_SPI2 TRUE同时 halconf.h 也启用了 HAL 层的 PWM 与 SPI 支持#define HAL_USE_PWM TRUE #define HAL_USE_SPI TRUE指示灯Indicatorskeyboard.json中定义了三个状态指示灯caps_lockB3num_lockB4scroll_lockA15旋转编码器四编码器与矩阵引脚复用Sagittarius 的一大特色是板上带有 4 个旋转编码器全部使用相同的引脚对B12/B11分辨率 2定义在keyboard.json中encoder: { rotary: [ {pin_a: B12, pin_b: B11, resolution: 2}, {pin_a: B12, pin_b: B11, resolution: 2}, {pin_a: B12, pin_b: B11, resolution: 2}, {pin_a: B12, pin_b: B11, resolution: 2} ] }默认键位通过 keymaps/default/rules.mk 启用编码器功能ENCODER_ENABLE yes ENCODER_MAP_ENABLE yes编码器的硬件复用原理四个编码器共用 B12/B11 引脚它们如何区分彼此答案在 keyboards/cannonkeys/sagittarius/sagittarius.c 中。该文件实现了自定义的encoder_driver_task()核心思路是复用矩阵的前 4 个行引脚B10, B14, A8, A9作为编码器的“片选”信号先把前 4 个矩阵行引脚全部设为输出逐个将第 i 个行引脚拉低、其余拉高以此选中第 i 个编码器等待ENCODER_SETTLE_PIN_STATE_DELAY_US默认 2 微秒让电平稳定调用encoder_quadrature_handle_read()读取被选中编码器的 A/B 相状态循环结束后把行引脚恢复为输入上拉回到矩阵扫描的预期状态。这意味着编码器扫描与矩阵扫描是分时复用的属于该键盘一个典型的底层硬件技巧在引脚资源有限的情况下通过行引脚分时选通扩展出 4 个编码器。编码器映射Encoder Mapkeymaps/default/keymap.c 中为每个图层定义了 4 个编码器的双向映射const uint16_t PROGMEM encoder_map[][NUM_ENCODERS][NUM_DIRECTIONS] { [0] { ENCODER_CCW_CW(MS_WHLU, MS_WHLD), ENCODER_CCW_CW(KC_VOLD, KC_VOLU), ENCODER_CCW_CW(UG_HUED, UG_HUEU), ENCODER_CCW_CW(UG_SATD, UG_SATU) }, [1] { ENCODER_CCW_CW(UG_VALD, UG_VALU), ENCODER_CCW_CW(UG_SPDD, UG_SPDU), ENCODER_CCW_CW(UG_PREV, UG_NEXT), ENCODER_CCW_CW(KC_RIGHT, KC_LEFT) }, };默认层_BASE中四个编码器分别控制鼠标滚轮、音量、RGB 色相与 RGB 饱和度功能层_FN1中则控制 RGB 亮度与速度、RGB 颜色切换上一/下一个以及左右方向键。可以看出 4 个编码器在默认固件中被分配为“媒体/鼠标控制”与“RGB 控制”两大类用途用户可以在自己的键位中按需重新映射。默认键位布局默认键位定义在 keymaps/default/keymap.c包含两个图层_BASE默认层标准 QWERTY 配列Esc 使用QK_GESC按住为 Escape、单击为反引号空格键拆分为两个KC_SPC右侧 Shift 旁边放置方向键左下角提供MO(_FN1)层切换键_FN1功能层F1F12 功能键、QK_BOOT进入 DFU 引导模式、KC_INS插入键等其余位置使用KC_TRNS透明透传。keyboard.json中的LAYOUT_default布局定义了键位的矩阵坐标与物理位置x/y 坐标、宽度 w例如第二行的1.5UTab、第三行的1.75U左 Shift、第四行的1.25U等这些数据由 QMK 数据驱动机制直接生成LAYOUT_default宏供键位引用。系统时钟与功能特性总览keyboards/cannonkeys/sagittarius/chconf.h 将 ChibiOS 系统节拍频率设为 10000 Hz并启用了 registry、等待/退出、条件变量、消息与邮箱等 RTOS 特性。keyboard.json的features段汇总了该键盘启用的核心功能features: { bootmagic: true, mousekey: true, extrakey: true, console: true, command: true, nkro: true, backlight: true, rgblight: true }此外还启用了 QMK 的锁定键特性含 resync 重同步qmk: { locking: { enabled: true, resync: true } }整体来看Sagittarius 的 QMK 支持是“数据驱动配置 少量底层 C 补丁”的典型组合绝大部分硬件描述矩阵、背光、RGB、编码器、指示灯都集中在keyboard.json而 SPI/PWM 外设复用与编码器分时选通这类无法用数据驱动表达的细节则由config.h、mcuconf.h、halconf.h和 sagittarius.c 承担。若需深入了解数据驱动配置机制可参考 docs/data_driven_config.md。【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 QMK 固件中的 CannonKeys + Acheron Sagittarius 键盘支持解析与构建指南
QMK 固件中的 CannonKeys Acheron Sagittarius 键盘支持解析与构建指南【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmwareSagittarius 是 CannonKeys 与 Acheron 合作推出的一款基于 STM32F072 的机械键盘本文以其在 QMK 固件仓库中的官方支持为主线讲解该键盘的硬件配置、固件构建方法、默认键位与四编码器实现原理。读者读完可以掌握如何在本仓库中定位该键盘的完整配置、使用make编译默认固件并理解其矩阵、背光、RGB 与编码器在源码层面的工作方式。键盘基本信息与维护信息根据 keyboards/cannonkeys/sagittarius/readme.md 的官方说明键盘名称CannonKeys Acheron Sagittarius维护者Keyboard MaintainerAndrew KannanGitHub 用户名为 awkannan支持的硬件Hardware SupportedSTM32F072CBT6在 keyboards/cannonkeys/sagittarius/keyboard.json 中还可以找到更完整的元数据keyboard_nameSagittariusmanufacturerCannonKeysmaintainerawkannanprocessorSTM32F072bootloaderstm32-dfuusb.vid0xCA04usb.pid0x0001device_version0.0.1从这些配置可以看出该键盘使用 STM32F072 系列 MCU并通过 STM32 的 DFUDevice Firmware Upgrade模式进行固件烧录。构建默认固件在设置好 QMK 构建环境之后构建该键盘默认固件的命令为make cannonkeys/sagittarius:default该命令会以keyboards/cannonkeys/sagittarius目录为键盘根目录编译keymaps/default下的默认键位配置。构建环境的搭建与make用法可以参考仓库内文档构建环境搭建docs/getting_started_build_tools.mdmake 使用指南docs/getting_started_make_guide.md若你是 QMK 新手建议先阅读 docs/newbs.md 完整入门指南另外keyboards/cannonkeys/sagittarius/rules.mk 中有一行特殊配置# Wildcard to allow APM32 MCU DFU_SUFFIX_ARGS -v FFFF -p FFFF该配置为 DFU 后缀校验参数设置了通配符 VID/PIDFFFF使得固件烧录工具在生成 DFU 文件时不再强制校验特定厂商与产品 ID从而兼容 APM32 等兼容 MCU 的烧录场景。矩阵与引脚配置keyboards/cannonkeys/sagittarius/keyboard.json 中通过数据驱动方式定义了完整的矩阵列引脚colsA7, A5, A4, A3, A2, A1, A0, B5, A13, B2, B1, B0, B9, B8, B7, B6共 16 列行引脚rowsB10, B14, A8, A9, A10, C13, C14, C15, F0, F1共 10 行二极管方向diode_directionCOL2ROW即二极管方向为列到行是当前大多数现代键盘的扫描方向矩阵共 16×10 160 个扫描点而实际布局仅使用了其中一部分这与布局中的键位矩阵坐标一一对应。背光、RGB 与指示灯背光Backlight在keyboard.json中backlight: { pin: A6, levels: 6, breathing: true }背光使用 A6 引脚支持 6 级亮度调节与呼吸效果。底层 PWM 配置位于 keyboards/cannonkeys/sagittarius/config.h#define BACKLIGHT_PWM_DRIVER PWMD3 #define BACKLIGHT_PWM_CHANNEL 1 #define BACKLIGHT_PAL_MODE 1对应地keyboards/cannonkeys/sagittarius/mcuconf.h 中使能了 TIM3 的 PWM 输出#undef STM32_PWM_USE_TIM3 #define STM32_PWM_USE_TIM3 TRUERGB 灯效rgblight WS2812RGB 部分在keyboard.json中声明了 8 颗 RGB LED并启用了呼吸、彩虹流动、彩虹漩涡、贪吃蛇、骑士、圣诞、静态渐变、RGB 测试、交替与闪烁共 10 种动画效果rgblight: { led_count: 8, animations: { breathing: true, rainbow_mood: true, rainbow_swirl: true, snake: true, knight: true, christmas: true, static_gradient: true, rgb_test: true, alternating: true, twinkle: true } }WS2812 灯带通过 SPI 驱动数据引脚为 B15ws2812: { pin: B15, driver: spi }SPI 驱动的底层配置同样在 config.h#define WS2812_SPI_DRIVER SPID2 #define WS2812_SPI_MOSI_PAL_MODE 0 #define WS2812_SPI_SCK_PAL_MODE 0 #define WS2812_SPI_SCK_PIN B13并使用 mcuconf.h 使能 SPI2#undef STM32_SPI_USE_SPI2 #define STM32_SPI_USE_SPI2 TRUE同时 halconf.h 也启用了 HAL 层的 PWM 与 SPI 支持#define HAL_USE_PWM TRUE #define HAL_USE_SPI TRUE指示灯Indicatorskeyboard.json中定义了三个状态指示灯caps_lockB3num_lockB4scroll_lockA15旋转编码器四编码器与矩阵引脚复用Sagittarius 的一大特色是板上带有 4 个旋转编码器全部使用相同的引脚对B12/B11分辨率 2定义在keyboard.json中encoder: { rotary: [ {pin_a: B12, pin_b: B11, resolution: 2}, {pin_a: B12, pin_b: B11, resolution: 2}, {pin_a: B12, pin_b: B11, resolution: 2}, {pin_a: B12, pin_b: B11, resolution: 2} ] }默认键位通过 keymaps/default/rules.mk 启用编码器功能ENCODER_ENABLE yes ENCODER_MAP_ENABLE yes编码器的硬件复用原理四个编码器共用 B12/B11 引脚它们如何区分彼此答案在 keyboards/cannonkeys/sagittarius/sagittarius.c 中。该文件实现了自定义的encoder_driver_task()核心思路是复用矩阵的前 4 个行引脚B10, B14, A8, A9作为编码器的“片选”信号先把前 4 个矩阵行引脚全部设为输出逐个将第 i 个行引脚拉低、其余拉高以此选中第 i 个编码器等待ENCODER_SETTLE_PIN_STATE_DELAY_US默认 2 微秒让电平稳定调用encoder_quadrature_handle_read()读取被选中编码器的 A/B 相状态循环结束后把行引脚恢复为输入上拉回到矩阵扫描的预期状态。这意味着编码器扫描与矩阵扫描是分时复用的属于该键盘一个典型的底层硬件技巧在引脚资源有限的情况下通过行引脚分时选通扩展出 4 个编码器。编码器映射Encoder Mapkeymaps/default/keymap.c 中为每个图层定义了 4 个编码器的双向映射const uint16_t PROGMEM encoder_map[][NUM_ENCODERS][NUM_DIRECTIONS] { [0] { ENCODER_CCW_CW(MS_WHLU, MS_WHLD), ENCODER_CCW_CW(KC_VOLD, KC_VOLU), ENCODER_CCW_CW(UG_HUED, UG_HUEU), ENCODER_CCW_CW(UG_SATD, UG_SATU) }, [1] { ENCODER_CCW_CW(UG_VALD, UG_VALU), ENCODER_CCW_CW(UG_SPDD, UG_SPDU), ENCODER_CCW_CW(UG_PREV, UG_NEXT), ENCODER_CCW_CW(KC_RIGHT, KC_LEFT) }, };默认层_BASE中四个编码器分别控制鼠标滚轮、音量、RGB 色相与 RGB 饱和度功能层_FN1中则控制 RGB 亮度与速度、RGB 颜色切换上一/下一个以及左右方向键。可以看出 4 个编码器在默认固件中被分配为“媒体/鼠标控制”与“RGB 控制”两大类用途用户可以在自己的键位中按需重新映射。默认键位布局默认键位定义在 keymaps/default/keymap.c包含两个图层_BASE默认层标准 QWERTY 配列Esc 使用QK_GESC按住为 Escape、单击为反引号空格键拆分为两个KC_SPC右侧 Shift 旁边放置方向键左下角提供MO(_FN1)层切换键_FN1功能层F1F12 功能键、QK_BOOT进入 DFU 引导模式、KC_INS插入键等其余位置使用KC_TRNS透明透传。keyboard.json中的LAYOUT_default布局定义了键位的矩阵坐标与物理位置x/y 坐标、宽度 w例如第二行的1.5UTab、第三行的1.75U左 Shift、第四行的1.25U等这些数据由 QMK 数据驱动机制直接生成LAYOUT_default宏供键位引用。系统时钟与功能特性总览keyboards/cannonkeys/sagittarius/chconf.h 将 ChibiOS 系统节拍频率设为 10000 Hz并启用了 registry、等待/退出、条件变量、消息与邮箱等 RTOS 特性。keyboard.json的features段汇总了该键盘启用的核心功能features: { bootmagic: true, mousekey: true, extrakey: true, console: true, command: true, nkro: true, backlight: true, rgblight: true }此外还启用了 QMK 的锁定键特性含 resync 重同步qmk: { locking: { enabled: true, resync: true } }整体来看Sagittarius 的 QMK 支持是“数据驱动配置 少量底层 C 补丁”的典型组合绝大部分硬件描述矩阵、背光、RGB、编码器、指示灯都集中在keyboard.json而 SPI/PWM 外设复用与编码器分时选通这类无法用数据驱动表达的细节则由config.h、mcuconf.h、halconf.h和 sagittarius.c 承担。若需深入了解数据驱动配置机制可参考 docs/data_driven_config.md。【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考