New Beamspring QMK firmware

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

Table of Contents

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,

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 looking 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 then 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.