QMK异形机械键盘

设计目的

设计一把符合自己使用习惯的键盘。根据自己的使用习惯和需求针对性设计一把属于自己的键盘。他可能配列奇奇怪怪、可能高度与众不同、可能按键功能也不按常理，但无论他再怎么奇怪他也是针对你自己需求专门设计的结构和功能。这可能就是客制化的魅力。

详细制作教程参考附件

设计需求

1. 配列自定义

2. 炫酷RGB

3. 按键可在线自定义

4. 按键支持宏定义等炫酷功能

5. 支持热插拔

6. TypeC接口

硬件选型

主控：STM32F103/APM32F103

灯珠：WS2812B(6028反贴4脚)

轴座：凯华

软件开发

QMK固件

Vial

硬件设计

主控

考虑到支持Vial固件和支持多种灯效的原因，主控芯片选择性能较强的32位单片机。国产APM32F103CBT6。

APM32的最小系统比较简单，只需要必要的供电、时钟以及复位按键。

需要注意的是在制作完成时烧录固件程序时，采用bootloader，为了每次更新固件不需要重新烧录bootloader,需将boot0接地。非常重要

电源

考虑到键盘体积小的情况，选用的LDO芯片尽量外围电路少和体积小

设计采用RT9193芯片。

TypeC

采用主流的TypeC接口，方便连接。

因为键盘是通过USB与电脑通信，根据设计需求需要将USB_D+通过1.5k电阻进行上拉。

为什么一定要上拉，而且是1.5k？

解释参考网络：

USB主机是如何检测到，到插入的设备呢？在USB集线器的每个下游端口的D+ D-上，分别接了一个15K的下拉电阻到地，这样，当集线器的端口悬空没有设备插入时，输入端就被这两个下拉电阻拉到了低电平，而在USB的设备端，在D+或者D-上接了一个1.5K的上拉电阻到3.3V的电源，1.5K的上拉电阻是接在D+还是D-上，有设备的速度来决定，对于全速设备和高速设备，上拉电阻是接在D+上的，而低速设备的上拉电阻则是接在D-上。

当设备插入到集线器时，接了上拉电阻的那条数据线的电压由1.5K的上拉和15K的下拉分压决定，结果大概在3V（3.3/1.5+15）* 1.5=3V），这对于集线器的接收端来说，是一个高电平信号，集线器检测到这个状态后，它就报告给USB主控制器，这样就检测到设备的插入了，集线器根据检测到的被拉高的数据线是D+还是D-来判断插入的是什么速度类型的设备，USB高速设备先是被识别为全速设备，然后通过集线器和设备的通信确认，再切换到高速设备，在高速模式下，是电流传输模式，这时要将D+上的上拉电阻断开。

这个如果这个1.5K是其他值，那么D+/D-上拉分压之后的电平就会发生变化，如果再遇到电压纹波，那么就有可能不会被检测到，这个就是1.5K的由来。

按键

按键采用热插拔形式，使用的是凯华热插拔轴座。

键盘的按键连接一般分为两种形式

1.矩阵连接

2.独立连接

本次目标为设计一把小配列键盘，并且AMP32的I/O口数量足够，因此采用独立连接的形式，用此种方法可以省去二极管降低成本。

 

灯光

采用WS2812B(6028反贴4脚)

通过PWM信号进行驱动。灯珠之间相互串联，在设计时记得将信号输入引脚接入单片机能输出PWM信号的引脚。

烧录

不要忘记预留程序烧录引脚。推荐使用ST-LINK进行烧录。

 

键盘固件设计

针对一开始的键盘需求，没有采用自己编程开发的形式，而是选择开源的键盘固件QMK。

并且使用VIAL而不是VIA。这也是为什么芯片性能选好一点的原因。

QMK Firmware

注意因为用到的是VIAL因此需要下载对应VIAL分支下的代码，而不是主仓库代码。

vial_qmk源码

VIAL教程

QMK的网站有详细的说明，支持多种键盘，支持旋钮、屏幕等功能。本次设计只用到最基本的按键功能。因为是小配列，实用为主。

开发环境

1. 首先需要安装    QMK MSYS软件。

   QMK有维护一套基于MSYS2的软件包，所有命令行程序和依赖都是齐备的。通过 QMK MSYS 快捷命令可以快速启动开发环境。

2. 然后需要获取QMK源码，因某些原因，请自行解决网络问题。

   源码

   获取源码过程中，因源码工程里面含有许多子模块，并不推荐通过git一个个单独下载子模块。注意在github网页端直接打包下载ZIP的方式也会导致子模块下载不全。

   推荐使用github的桌面端软件，进行下载，此下载方式无需考虑子模块的影响。

3. 获取源码后，通过QMK MSYS进行测试你的开发环境,例如下面代码

   qmk compile -kb clueboard/66/rev3 -km default

   当看到没有报错，并且成功生成了.hex文件后，表面环境搭建完成，可以进行后续开发

   Linking: .build/clueboard_66_rev3_default.elf                                                       [OK]
   Creating load file for flashing: .build/clueboard_66_rev3_default.hex                               [OK]
   Copying clueboard_66_rev3_default.hex to qmk_firmware folder                                        [OK]
   Checking file size of clueboard_66_rev3_default.hex                                                 [OK]
   * The firmware size is fine - 26356/28672 (2316 bytes free)

代码编写

使用任意代码编辑器打开QMK源码

QMK工程结构如下：

我们仅关心keyboards文件夹下内容，里面包含许多其他人开发的键盘，我们也可以拿来参考。

在keyboards文件夹下建立如下文件结构

default文件夹

在该文件夹下建立keymap.c文件

#include QMK_KEYBOARD_H
#include "quantum.h"

const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
    [0] = LAYOUT(
        KC_P7,   KC_P8,   KC_P9,   KC_BSPC,   KC_P4,   KC_P5,   KC_P6,   KC_NUM,   KC_P2,   KC_P1
    ),
};

主要内容填入你想要的默认键值。键值可以先随便填，最后可以通过VIAL软件修改

VIAL文件夹

该文件夹下主要完成对VIAL的支持工作。详细教程可参考上面官方文档。

config.h

主要需要配置键盘的UID。

生成的 ID 对于键盘类型和型号的固件来说是唯一的； 对于每个单独的键盘或编译的固件来说，它不需要是唯一的。 从 vial-qmk 的根目录运行 python3 util/vial_generate_keyboard_uid.py为了生成唯一的小瓶键盘 ID。

须确保电脑有python环境。

#pragma once

#define VIAL_KEYBOARD_UID {0x9A, 0x27, 0xBD, 0x85, 0x42, 0xBD, 0x97, 0x56}

keymap.c

该文件同上

rules.mk

该文件用于在规则下启动VIAL

VIA_ENABLE = yes
VIAL_ENABLE = yes
VIAL_INSECURE = yes
VIALRGB_ENABLE = yes

vial.json

创建 Vial 端口的第一步是准备键盘定义，它是描述键盘布局的 JSON 文件。

按照一下模板填写对应内容即可

{
    "lighting": "vialrgbe",
    "matrix": {
        "rows": 4,
        "cols": 4
    },
    "layouts": {    
        "keymap":
    }
}

keymap的内容需要回到键盘设计网站。在空白键盘上填入对应坐标。填完如下图

然后复制Raw data中的内容，填入即可

config.h

配置灯珠数量，DMA通道等一系列相关配置。具体配置可以参考手册。

// Copyright 2023 HiryKun (@HiryKun)
// SPDX-License-Identifier: GPL-2.0-or-later

#pragma once

#define BOOTMAGIC_LITE_ROW 0
#define BOOTMAGIC_LITE_COLUMN 3

#define WS2812_PWM_DRIVER PWMD2
#define WS2812_PWM_CHANNEL 4
#define WS2812_DMA_STREAM STM32_DMA1_STREAM2
#define WS2812_DMA_CHANNEL 2
#define RGB_MATRIX_LED_COUNT 15
#define RGB_MATRIX_FRAMEBUFFER_EFFECTS
#define RGB_MATRIX_KEYPRESSES

#define NO_USB_STARTUP_CHECK

halconf.h

进行STM32功能的开启。

#define HAL_USE_PWM TRUE
#define HAL_USE_PAL TRUE

#define STM32_HAS_USB  TRUE

#include_next 

info.json

键盘主要的配置

1. 对应按键和单片机引脚的物理连接。写成矩阵的形式，没有按键的地方用NO_PIN补全。

      "matrix_pins": {
          "direct":[
              ["B14","B15","B5","B3"],
              ["B13","B12","B1","A7"],
              ["B0","NO_PIN","NO_PIN","NO_PIN"],
              ["A6","NO_PIN","NO_PIN","NO_PIN"]
          ]
      },

2. 键盘布局的定义。布局应该与前面设计的布局一致。

   "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,"h": 2},
                  {"matrix": [2, 0],"x": 0,"y": 2,"w": 2},
                  {"matrix": [3, 0],"x": 0,"y": 3,"h": 2}
              ]
          }
      }

3. RGB相关配置

   灯效配置,将你想开启的灯效在这填写。

   灯效越多，固件体积越大，因此一开始选用性能好点的单片机。

   "animations": {
              "alphas_mods": true,
              "gradient_up_down": true,
              "gradient_left_right": true,
              "breathing": true,
              "band_sat": true,
              "band_val": true,
              "band_pinwheel_sat": true,
              "band_pinwheel_val": true,
              "band_spiral_sat": true,
              "band_spiral_val": true,
              "cycle_all": true,
   
          }

   灯珠位置的编写。具体方法请参考文档

   "center_point": [32,32],
          "layout": [
              {"flags": 4, "matrix": [1,0], "x": 0, "y": 0},
              {"flags": 4, "matrix": [1,1], "x": 21, "y": 0},
              {"flags": 4, "matrix": [1,2], "x": 43, "y": 0},
              {"flags": 4, "matrix": [1,3], "x": 64, "y": 0},
              {"flags": 4, "matrix": [2,3], "x": 64, "y": 21},
              {"flags": 4, "matrix": [2,2], "x": 43, "y": 21},
              {"flags": 4, "matrix": [2,1], "x": 21, "y": 21},
              {"flags": 4, "matrix": [2,0], "x": 0, "y": 21},
              {"flags": 4, "matrix": [3,0], "x": 0, "y": 43},
              {"flags": 4, "matrix": [3,1], "x": 21, "y": 43}
   
          ]

   RGB驱动信号输出引脚

    "ws2812": {
          "driver": "pwm",
          "pin": "A3"
      }

mcuconf.h

主要开启STM32需要用到的外设

#include_next 

#undef STM32_PWM_USE_TIM2
#define STM32_PWM_USE_TIM2 TRUE

#undef STM32_PWM_USE_TIM1
#define STM32_PWM_USE_TIM1 TRUE

到此键盘固件基础功能代码已经实现，通过QMK MSYS编译后即可生成.BIN 和.HEX格式的固件。