Read my keymap setting at https://github.com/LdBeth/QMKBEAMS.

Table of Contents

 • 1. Introduction
 • 2. Why not use Vial
 • 3. Setup QMK environment
 • 4. A dive into the xwhatis firmware
     □ 4.1. On the dynamic macro
     □ 4.2. How to flash firmware
 • 5. A deeper dive into the xwhatis firmware

1. Introduction

I got my beamspring reproduction from Model F Labs. The keyboard controller is
xwhatsit which is the same controller used with other Model F reproductions,
although in the future they are planning to switch to RP2040 based Leyden Jar
in the future, due to unable to restock xwhatsit, despite ATMega32u2 has much
lower end spec.

Given that xwhatsit is the only thing we can play with right now, let's see
what we can do with it. Well it has only 1kb SRAM and 1kb EEPROM, although the
flash memory is plenty if you trim the unnecessary QMK features.

The firmware provided on the website is based on an older fork of QMK on http:/
/purdea.ro/qmk_firmware, the git commit shows it forked since 2020. The
build.sh scripts shows the Vial firmware is built by patching the pandrew files
into ff5d361 revision of Vial's fork of QMK. Which is now unfortunately been
considered “too old” by Vial's configurator to support newer features.

2. Why not use Vial

Because Vial stores the keyboard layout into the 1kb EEPROM to be configurable
without reflash the firmware, the storage space is rather limited for the
macros. My experiment turns out, if code the macro using QMK directly, the
flash memory has plenty of room for all the nonsense memes I want to fit into
the keymap.

Besides, to unlock the true power of QMK, program QMK directly from C is
necessary.

3. Setup QMK environment

I have used a fresh WSL environment using Void Linux's roofts image. Besides
what the QMK documentation suggests to install Python and the qmk command line,

 • You will need to create a Python venv, as the newer package manage policy
   forbids using pip to install packages into system wide Python environment.

 • You will have to install some missing HID/USB libraries to make the qmk
   command work.

 • You will need make to build keyboard firmware.

 • You will have to setup sudo for current user account to have qmk setup
   install the GCC for you.

4. A dive into the xwhatis firmware

✎︎
This is not a complete tutorial

You'll have to learn things on you own by reading appropriate documentation.

⚡︎
Learn how to put the controller into bootloader mode

Before proceeding, you should be aware that flashing the wrong firmware can
soft brick your keyboard controller, and you'll have to open the backlid of the
keyboard to be able to access the PROG pin to be able to flash the firmware
again.

After you get the firmware working, you may assign a key on the keyboard to
enter bootloader mode so you don't need to open the backlid every time.

The real interesting part from pandrew firmware is under the keyboards/xwhatsit
/brand_new_model_f/. And for the model I have it is beamspring_full/. Although
I know you are probably here look for a quick way to build your own QMK
firmware, I suggest you go through the build.sh and create a working "old" Vial
firmware to get you familiarize with the QMK building process, and they try
build the QMK firmware without Vial using the old QMK source, and maybe add a
few customization.

⚡︎
You are using an old version of QMK

Please do not rely on the online documentation since they are too new. You
should only refer to the QMK documentation in the source tree.

And if you find that already gives what you want, you can just stop here with a
customized QMK firmware, since the newer version cannot give more advantages
unless you really care to use the new features, which is probably why the
pandrew fork has been out of sync for that long time.

⚡︎
The pandrew util for Vial provided by Model F Lab may no long work

Depends on if you build from the pandrew fork or patched Vial, also the
interface RAW HID is used to implement that so if you disable that feature it
would no longer work, and you won't able to use that to turn on bootloader mode
for your keyboard.

Since that requires to learn the communication protocol used for the util, I
never bothered to fix that in mine fork.

4.1. On the dynamic macro

Many claims enabling the dynamic macro in QMK would brick their Model F
keyboard. It is because the macro buffer is allocated on the SRAM which is only
1kb in total, and the capacitance sensing needs a lot of stack space to
calibrate the keypress at boot so if there is not enough RAM the keyboard would
brick.

After disable unused features, and optimized the SRAM allocation in the code,
you can try define DYNAMIC_MACRO_SIZE to be a lower level, a safe bet is 40
which is already useful enough.

4.2. How to flash firmware

That is a good question, you can modify the scripts provided on the Mode F Labs
website to flash firmware for you, given if you already have that setup, just
remember to remove the EEPROM line if you only use plain QMK.

5. A deeper dive into the xwhatis firmware

Now you really want the fancy QMK features like deferred execution, what it
costs to port the pandrew firmware to latest QMK version?

The answer is, nothing, at least none of the features I can test does not work
with latest QMK source tree.

Most of the heavy lifting including USB protocol, MCU bootloader, debouncing
are already handled by QMK, the firmware only handles the capacitive sensing,
and the raw HID protocol I already decided to drop.

They only headache is, QMK dropped many of the config.h definitions in favor of
keyboard.json. For most of things qmk lint would tell you what to do. There is
only one thing very tricky to do which is create the keymap with matrix
description, you will need to make something like this:

  |    "layouts": {
  |        "LAYOUT_fullsize_ansi": {
  |            "layout": [
  |                {"matrix": [3, 0], "x": 0, "y": 0},
5 |                {"matrix": [3, 1], "x": 2, "y": 0},
  |                {"matrix": [1, 1], "x": 3, "y": 0},
  |                {"matrix": [3, 10], "x": 4, "y": 0},
  |                {"matrix": [3, 15], "x": 5, "y": 0},
  |                {"matrix": [3, 14], "x": 6.5, "y": 0},
10 |                {"matrix": [3, 13], "x": 7.5, "y": 0},
  |...

Actually, a good source of that information can be find from the vial.json
provided in the prebuilt firmware package. Only the last few lines are
redundant.

  |        "keymap": [
  |            ["3,0",{"x":1},"3,1","1,1","3,10","3,15",{"x":0.5},...
  |            [{"y":0.5},"1,0","0,1","0,10","1,10","1,15","0,15",...
  |            [{"w":1.5},"2,0","2,1","7,1","2,10","2,15","2,14",...
5 |            [{"w":1.75},"7,0","5,1","5,10","7,15","5,15","7,14",...
  |            [{"w":2.25},"4,0","4,10","4,15","5,14","4,14","4,13",...
  |            [{"w":1.25},"6,0",{"w":1.25},"6,1",{"w":1.25},"6,10",..
  |            [{"y":0.25,"x":15.25},"7,7\n\n\n0,1","7,6\n\n\n0,1",...
  |            [{"x":15.25},"4,6\n\n\n0,1",{"x":1},"5,5\n\n\n0,1"]
10 |        ]

This matrix information is used by QMK to generate the C macro for keyboard
layout, corresponding to LAYOUT_all in the old firmware.

They rest would be just some keycode naming/header file path changes.

You are viewing proxied material from sdf.org. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.