QMK 生态中的 EC 电容键盘 EC ThecaSTM32 构建、刷写与模拟矩阵深度解析【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmwareEC Theca 是键盘制作者 cipulot、config.h、三个官方键位以及共享的 EC 矩阵实现源码完整讲解从环境准备、编译、刷写到引导加载器进入方式的全流程并深入剖析 EC 键盘特有的 ADC 模拟扫描与触发阈值机制帮助你在拿到 PCB 后即可完成固件编译与烧录并理解其底层工作原理。键盘硬件与固件规格概览根据 keyboard.jsonEC Theca 的核心规格如下项目取值厂商manufacturerCipulot键盘名keyboard_nameEC Theca维护者maintainerCipulot主控processorSTM32F401ARM Cortex-M4 系列引导加载器bootloaderstm32-dfuUSB VID / PID0x6369/0x6B7E设备版本device_version0.0.1矩阵方向diode_directionCOL2ROW键位布局TKL ANSI / TKL ANSI Tsangan / TKL ANSI WKLLAYOUT_tkl_ansi_wkl固件层面启用的特性features包括console调试控制台、extrakey媒体/系统键扩展、mousekey鼠标键、nkro全键无冲同时显式关闭了bootmagic构建时开启了 LTO 链接优化build.lto true并启用了锁定键状态重同步qmk.locking.resync。此外 config.h 中定义了DYNAMIC_KEYMAP_LAYER_COUNT 3动态键映射 3 层与EECONFIG_KB_DATA_SIZE 201为 EC 专属配置保留 201 字节的 EEPROM 数据块。值得注意的是与普通机械键盘的简单行列扫描不同EC Theca 是静电容键盘其矩阵扫描逻辑并非由 QMK 默认代码完成而是通过CUSTOM_MATRIX lite走自定义矩阵路径这部分将在后文单独展开。构建环境准备在编译之前需要先完成 QMK 固件构建环境的搭建。仓库 docs 目录下提供了完整的入门指引首次接触 QMK 的用户建议从 Complete Newbs Guide 开始其中包含环境搭建、首次编译到刷写的完整流程更详细的构建工具安装步骤可参考 Getting Started 介绍Make 命令的完整用法见 Make 指令指南。环境就绪后即可在仓库根目录下对 EC Theca 执行编译。编译固件make 命令与产物官方 README 给出的默认键位编译命令为make cipulot/ec_theca:default其中cipulot/ec_theca是键盘在仓库中的目标路径对应keyboards/cipulot/ec_theca/default是键位名对应 keymaps/default/。构建产物默认输出到build/目录编译完成后即可得到可刷写的固件文件。由于keyboard.json声明了bootloader: stm32-dfuQMK 会为 STM32F401 主控生成 DFU 刷写流程所需的固件镜像。除默认键位外官方还提供了另外两套键位详见下文“配列与官方键位”小节编译时替换键位名即可例如make cipulot/ec_theca:tkl_ansi_tsangan make cipulot/ec_theca:tkl_ansi_tsangan_wkl刷写固件与进入引导加载器官方 README 提供的刷写命令为make cipulot/ec_theca:default:flash该命令会在编译完成后自动调用与stm32-dfu引导加载器配套的烧录工具如dfu-util完成固件写入。刷写前需要让键盘进入引导加载器模式。进入引导加载器有两种官方方式物理复位推荐首选短接 PCB 顶部裸露的复位焊盘README 中表述为 Long short the exposed pads on the top of the PCB即对 PCB 顶部露出的焊盘进行短接键盘随即进入 DFU 模式等待刷写。键码复位如果当前键位中映射了QK_BOOT键码按下该键即可直接进入引导加载器。默认键位的第二层layer 1的第一个键就是QK_BOOT位于KC_ESC的上方Fn 层见 keymaps/default/keymap.c。也就是说按住MO(1)再按下 Esc 位置即可触发复位无需打开外壳短接焊盘。配列与官方键位EC Theca 在 keyboard.json 中定义了三种 TKL 配列并在layout_aliases中提供了别名映射LAYOUT_tkl_ansi标准 TKL ANSI 配列87 键也是默认键位使用的配列LAYOUT_tkl_ansi_tsanganTsangan 风格底排左右各 1.5U、中间 7U 空格等并存在别名LAYOUT_tkl_ansi_tsangan_wklLAYOUT_tkl_ansi_wklWKLWinKeyless无 Win 键风格去掉了底排的 GUI 键位别名LAYOUT_all也会映射到此配列。layout_aliases的写法意味着用户既可以使用完整名称如LAYOUT_tkl_ansi_tsangan_wkl也可以使用兼容别名如LAYOUT_all来编写键位QMK 的数据驱动配置系统会在构建时自动完成映射。仓库共内置三套官方键位键位目录使用配列说明keymaps/default/LAYOUT_tkl_ansi标准 ANSI TKL第二层提供QK_BOOT与NK_TOGGNKRO 开关keymaps/tkl_ansi_tsangan/LAYOUT_tkl_ansi_tsanganTsangan 底排变体键位功能与默认一致keymaps/tkl_ansi_tsangan_wkl/LAYOUT_tkl_ansi_wklWKL 变体第二层同样提供QK_BOOT/NK_TOGG三套键位的功能层设计一致第 0 层为标准 87 键键位字母区、F 区、编辑键区与方向键第 1 层为功能层通过MO(1)临时激活仅定义QK_BOOT进入引导加载器与NK_TOGG切换 NKRO两个实用功能其余位置均为_______透明透传上一层。这种“Fn 层放复位键”的写法是许多 QMK 键盘刷机便捷性的体现——配合上文提到的键码复位方式几乎不需要开壳。深入底层EC 电容矩阵与 ADC 模拟扫描这是 EC Theca 与普通机械键盘最本质的区别所在也是理解这块板子的关键。共享实现位于 keyboards/cipulot/common/由 common_cipulot.mk 引入CUSTOM_MATRIX lite ANALOG_DRIVER_REQUIRED yes VPATH keyboards/cipulot/common SRC matrix.c ec_board.c ec_switch_matrix.c即EC Theca 不使用 QMK 的默认 GPIO 行列扫描而是以lite自定义矩阵方式接入并强制要求启用模拟ADC驱动。matrix.c负责矩阵调度ec_switch_matrix.c实现逐键的电容采样ec_board.c负责 EEPROM 中的 EC 配置读写与开机初始化。模拟多路复用器AMUX扩展列扫描由于 TKL 键盘的列数较多单颗 MCU 的 ADC 引脚不够用EC Theca 采用模拟多路复用器AMUX扩展列通道。相关定义集中在 config.h#define AMUX_COUNT 2 // 两颗多路复用器 #define AMUX_MAX_COLS_COUNT 8 // 每颗最大 8 通道 #define AMUX_EN_PINS { C13, C14 } // 使能引脚 #define AMUX_SEL_PINS { B7, B8, B9 } // 3 条选择线 #define AMUX_COL_CHANNELS_SIZES { 8, 8 } #define AMUX_0_COL_CHANNELS { 3, 0, 1, 2, 6, 5, 7, 4 } #define AMUX_1_COL_CHANNELS AMUX_0_COL_CHANNELS矩阵规模为 6 行 × 16 列MATRIX_ROWS 6、MATRIX_COLS 16其中 16 列由两颗 8 通道 AMUX 分担AMUX_SEL_PINS提供 2³8 个选择状态AMUX_x_COL_CHANNELS定义了列号到复用器通道的映射顺序。此外还有DISCHARGE_PIN B1放电引脚与ANALOG_PORT A3ADC 采样引脚对应 ADC 采样前对电容放电、采样时读取电压的经典 EC 扫描流程。为启用 STM32 的 ADC1halconf.h 设置了HAL_USE_ADC TRUEmcuconf.h 打开STM32_ADC_USE_ADC1。触发模式与阈值配置EEPROM 持久化静电容键盘通过电容变化量判断按键按下因此“何时触发”取决于阈值设置。EC Theca 在 config.h 中提供了两套可配置的触发模式及其默认值Mode 0固定阈值模式以固定的绝对 ADC 读数作为触发/释放边界默认触发阈值DEFAULT_MODE_0_ACTUATION_LEVEL 550、释放阈值DEFAULT_MODE_0_RELEASE_LEVEL 500Mode 1动态偏移模式从初始死区偏移DEFAULT_MODE_1_INITIAL_DEADZONE_OFFSET默认取 Mode 0 的触发阈值 550出发结合触发偏移DEFAULT_MODE_1_ACTUATION_OFFSET 70与释放偏移DEFAULT_MODE_1_RELEASE_OFFSET 70动态计算触发点辅助参数DEFAULT_EXTREMUM 102312 位 ADC 满量程参考、NOISE_FLOOR_THRESHOLD 50、EXPECTED_NOISE_FLOOR 0、BOTTOMING_CALIBRATION_THRESHOLD 50、DEFAULT_NOISE_FLOOR_SAMPLING_COUNT 30噪声底采样次数、DEFAULT_BOTTOMING_READING 1023触底读数以及DEFAULT_CALIBRATION_STARTER true。从 ec_board.c 的源码结构看这些配置在首次初始化eeconfig_init_kb时写入 EEPROM开机时keyboard_post_init_kb再读回运行时结构体实现“配置可持久化、掉电不丢失”。同时 common_cipulot.mk 中VIA_ENABLE分支会额外编译 via_ec.c表明该系列板子预留了通过 VIA 在运行时调整触发阈值等 EC 参数的软件通道——具体暴露哪些参数以 VIA 端定义为准。这套“ADC 采样 AMUX 扩列 阈值判定 EEPROM 持久化”的实现就是 EC Theca 与机械轴键盘在固件层面最核心的差异所在。理解config.h中这些宏的含义对后续自行调校手感如改触发点或排查“按键不触发/误触发”问题非常有帮助。小结与故障排查提示EC Theca 的日常使用流程可以概括为三步搭建 QMK 构建环境 →make cipulot/ec_theca:default编译 → 短接顶部焊盘或按QK_BOOT进入 DFU 后make cipulot/ec_theca:default:flash刷写。若刷写后按键行为异常可优先检查是否误用了非官方配列务必使用LAYOUT_tkl_ansi系列三个配列之一其余键位定义会因矩阵坐标不匹配而失效是否修改过 config.h 中的阈值宏Mode 0 触发阈值 550 是官方校准值改动后可能需要配合触底校准流程重新标定是否正常进入 DFU 模式STM32F401 的 DFU 需要在上电复位瞬间处于引导状态物理短接焊盘是最可靠的进入方式。对于想继续深挖的读者推荐依次阅读 keyboards/cipulot/common/ec_switch_matrix.c逐键采样与去抖、matrix.c扫描调度以及 config.h全部可调参数即可完整掌握这款 EC TKL 在 QMK 下的工作方式。【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考