#+title: QMK笔记
#+date: <2023-08-03 Thu 12:45>
#+author: thebesttv

- [[https://keebnews.com/qmk-tutorial/][QMK Tutorial: A Complete Guide (For Keyboard Nerds)]]

#+begin_src bash
  qmk new-keyboard
  qmk new-keymap -kb thebesttv/split27 -km via
  qmk compile -kb thebesttv/split27 -km via
  qmk console --bootloaders
#+end_src

* 使用 QMK 从零开始设计一个键盘的流程

1. 设计 layout:使用 [[http://www.keyboard-layout-editor.com/][KLE]] 设计。可以在键位上直接写上矩阵座标,方便之后VIA的配置。
2. 生成PCB和定位板边框:使用 [[http://builder.swillkb.com/][Plate & Case Builder]],直接把 KLE 的 raw
   data 复制过去。
   Switch Type 一般选 =t:1=​,Stabilizer Type 一般 =s:2=​。
3. 在 QMK 中添加新的键盘。
   其中 =info.json= 的 layout 的生成有两种方法:
   1. 使用 [[https://qmk.fm/converter/][Convert KLE raw to QMK info.json]] 直接把 KLE 的 raw data 转换
      为 QMK 的 layout。
   2. 不推荐:如果使用了 [[https://kbfirmware.com/][Keyboard Firmware Builder]] 的话,生成的 JSON 文件非常大,
      需要用 [[https://noroadsleft.github.io/kbf_qmk_converter/][KBFirmware JSON to QMK Parser]] 再次转换。
4. 设计 keymap

* 合宙Air32F103

UPD: 现在有了9.9的树莓派Pico,这个就没啥必要了。

使用合宙的 Air32F103 代替 STM32F103,目前选用 Air32F103CBT6,开发板9.9一个。
基于 Air32F103 的几块 QMK 键盘:
- [[https://oshwhub.com/ythfjjh/zq50][50%矮轴热插拔键盘]]
- [[https://oshwhub.com/small_da/3jian-xiao-jian-pan-kuai-su-shan][3键小键盘-快速上手版ZY-03S]]
- [[https://oshwhub.com/small_da/3jian-xiao-jian-pan-xuan-niu][3键小键盘-旋钮显示屏版ZY-03]]
用的都是 [[https://github.com/zhaqian12/qmk_firmware/tree/zhaqian][zhaqian]] 的固件和uf2bootloader。

** 烧录QMK

- [[https://www.bilibili.com/read/cv23216690/][使用国产芯片构建QMK固件(一)]]

*** 使用 STM32duino BL

- [[https://docs.qmk.fm/#/flashing?id=stm32duino][Flashing Instructions and Bootloader Information]]
  提供了刷写方法。

erase flash 再刷入链接中的 BL,然后使用命令
#+begin_src bash
  dfu-util -a 2 -d 1EAF:0003 -D <filename>
#+end_src

*** 使用 UF2 BL

- [[https://learn.adafruit.com/adafruit-hallowing/uf2-bootloader-details][UF2 Bootloader Details]]

先用串口 erase flash,然后用刷入 u2 bootloader。
刷入后,会显示一个虚拟u盘,把 cmopile 成功的 .u2 文件拖进去即可。

下一次想再次刷入固件的时候,双击 RST 即可。

* 使用 74HC65 扫描按键

需要修改 =matrix.c=​,具体见 [[https://docs.qmk.fm/#/custom_matrix?id=custom-matrix][Custom Matrix]]。

Air32F103 目前SPI好像还没有适配,所以直接 bitbang 了。

* 分体键盘

- [[https://github.com/qmk/qmk_firmware/blob/master/docs/feature_split_keyboard.md][Split Keyboard]] 通讯方式可以选择串口或者I2C。
- [[https://github.com/qmk/qmk_firmware/blob/master/docs/serial_driver.md]['serial' Driver]] 选择串口的话,可以在这里的三个驱动中选择一个。
  目前使用 USART Full-duplex。

如果使用 [[https://github.com/qmk/qmk_firmware/blob/master/docs/serial_driver.md#bitbang][Bitbang]] (soft serial),虽然只要一根线,
但在两块键盘相连接时无法连接VIA,需要切断中间的连线才能使用VIA。
而 [[https://github.com/qmk/qmk_firmware/blob/master/docs/serial_driver.md#usart-half-duplex][USART Half-duplex]] 的方法又要一个上拉电阻,不方便测试。

使用需要两根线的 [[https://github.com/qmk/qmk_firmware/blob/master/docs/serial_driver.md#usart-half-duplex][USART Full-duplex]] 方案,虽然两边需要调换线序,
不过连接VIA没有问题。

* VIA

** 固件配置

添加一个 =via= keymap。

** 配置文件

VIA的键盘配置文件在 [[https://github.com/the-via/keyboards][the-via/keyboards]] 中。
在写自己的配置文件时,可以参考别人的,如 [[https://github.com/the-via/keyboards/blob/master/v3/ergodox_ez/ergodox_ez.json][ergodox_ez/ergodox_ez.json]]。
注意:VIA现在升级到v3了,新的配置在 [[https://github.com/the-via/keyboards/tree/master/v3][v3]] 文件夹中,[[https://github.com/the-via/keyboards/tree/master/src][src]] 中都是老的。

文件位置:如,QMK中键盘在 =keyboards/thebesttv/split27= 中,
则VIA中对应配置文件位于 =v3/thebesttv/split27.json= 中。

=.json= 文件的格式如下:
#+begin_src js
  {
      "name": "Split27",                 // 键盘名称
      "vendorId": "0x1A5A",              // vid
      "productId": "0x1234",             // pid
      "matrix": {"rows": 10, "cols": 6}, // matrix大小
      "layouts": {
          "keymap":  ...  // KLE的JSON文件内容复制到这里
      }
  }
#+end_src
其中 =keymap= 的结果需要这样获取:
在 [[http://www.keyboard-layout-editor.com/][KLE]] 中把键盘对应的 layout 画出来,每个按键的 top-left legnd
上标出它在 matrix 中对应座标,其余部分留白。
每个按键都标注完后,去下方的 Raw data 一栏,选择 Download json,
然后把文件内容复制过来即可。文件内容应是大概是这个样子的(不考虑缩进):
#+begin_src js
  [
      ["0,0","0,1","0,2","0,3","0,4","0,5",{x:1},"5,0","5,1","5,2","5,3","5,4","5,5"],
      ["1,0","1,1","1,2","1,3","1,4","1,5",{x:1},"6,0","6,1","6,2","6,3","6,4","6,5"],
      ["2,0","2,1","2,2","2,3","2,4","2,5",{x:1},"7,0","7,1","7,2","7,3","7,4","7,5"],
      ["3,0","3,1","3,2","3,3","3,4","3,5",{x:1},"8,0","8,1","8,2","8,3","8,4","8,5"],
      [{x:3},"4,3","4,4","4,5",{x:1},"9,0","9,1","9,2"]
  ]
#+end_src

配置文件完成后,可以打开 [[https://usevia.app/][VIA App]],在 Settings 中,选择 Show Design Tab,
然后去 Design Tab,把配置文件上传,这样就可以正常连接键盘了。

** VIA网页端使用

如果需要添加一些复杂的 keycode,如 =MT(MOD_LCTL,KC_F)=​,
选择 Special 下的 Any,然后手动输入 keycode。

** Linux 下可能遇到的问题

Linux 下,试图 Authorize Device 时,如果 HID 列表中显示了自己的键盘,
但点击 Connect 后没有反应;再次尝试 Authorize Device,
发现列表中显示已配对,但点击还是没反应,这可能是权限问题。

判断方法:浏览器访问 =chrome://device-log/=​,查找类似 =HID "failed to open
/dev/hidraw2"= 的消息,有的话就因该是权限问题了。可以参考[[https://github.com/the-via/app/issues/91#issuecomment-1505095474][这里]]。

解决方法:[[https://wiki.archlinux.org/title/Keyboard_input#Configuration_of_VIA_compatible_keyboards][修改 udev 规则]]。