Building QMK for a repro Model F Keyboard

Inspiration & My layout

The layout I chose is mostly a combination of these three keyboards:

My custom F77 keyboard layout

What is QMK

QMK is a project that provides firmware and tools to configure that firmware, for many different keyboards, using many different keyboard controllers.

For the repro Model F77, the project website discusses some alternatives. xwhatsit was used before they switched to QMK, and Via/Vial is a fork of QMK that allows online changing of layouts without reflashing.

Since the QMK is what the keyboard came with, I am sticking with that because it seems likely to have the best support.

The F77 Ellipse project has no official support in the QMK firmware - the closest they have is a fork of QMK maintained by someone called pandrew.

Alternatives to QMK

There are two other firmware projects discussed on the official site – xwhatsit and via(l). xwhatsit has been deprecated, and the sense I got was that Vial is still not as stable as vanilla QMK. Vial has more features than QMK, but as any seasoned programmer knows, more features are not always better - especially when they come at the expense of stability.

I don’t plan to switch layouts often and therefore I don’t mind reflashing each time, so I went with vanilla QMK.

Prerequisite tools

I’m not sure if the QMK cli tool is strictly necessary but I used it to streamline configuration. To build my own firmware I followed the instructions on the QMK site.

Install the QMK cli tool

I found this in the arch pacman repo.

sudo pacman -Syu qmk

You can use it to clone the qmk repo but it just calls out to git clone anyway. I did use it to create a new keymap config

Install a sane C build environment

This is beyond the scope of this article but on debian this would be apt-get install build-essential. On arch, it’s pacman -S base-devel

Install dfu-programmer flashing tool

The keyboard runs on an atmega32u2 with a bootloader that allows in-circuit debugging and flashing. We can use dfu-programmer from the arch repository.

sudo pacman -Syu dfu-programmer

Obtain the source code

I needed to do a bit of leg work to get a source tree I could build. The F77 project essentially forked QMK and added the required code for the F77 board to their fork. If their fork was up to date I would’ve used it but since I wanted the latest QMK and the F77 changes, I had to combine the F77 changes with the official QMK code and build the resulting combined source tree.

Hopefully in the future this work gets merged upstream.

Clone the official QMK repo

You can use their tool like this: qmk clone or if you’re familiar with git you can simply do:

git clone https://github.com/qmk/qmk_firmware

This will check out a copy of the latest master branch of QMK but does not include the firmware for this keyboard.

Clone the specific QMK files for this keyboard

As far as I can tell, xwhatsit is the name of an Atmel-based keyboard controller. This is confusing as the firmware that previously shipped on this controller was also called xwhatsit, but now the QMK firmware is used even though the controller is still called xwhatsit.

A fork of QMK containing the xwhatsit keyboard profile - also referred to as the ‘pandrew’ firmware - can be cloned as follows:

git clone http://purdea.ro/qmk_firmware/

Lift n shift the subdir keyboards/xwhatsit/brand_new_model_f/f77 from pandrew to the vanilla QMK repo.

Configure the source

Use the QMK config tool to make a new keyboard layout file

My github username is tabell. Replace this with your own keymap name (as far as I can tell there’s no reason it needs to be a github username)

1
2
3

qmk config user.keyboard=xwhatsit/brand_new_model_f/f77
qmk config user.keymap=tabell
qmk new-keymap

This will create a new directory in keyboards/xwhatsit/brand_new_model_f/f77/keymaps/ containing three files. readme.md and config.h are boilerplate. The one you need to edit is keymap.c

Edit the layout file

This is my layout. The only thing not handled by the pandrew precompiled firmware is the meta/alt swap.

The meta modifiers are called GUI here - KC_LGUI and KC_RGUI. These are the Windows keys on Windows or the Command key on Mac. Some people on Linux put a Tux keycap there.

The reason there are three layouts is because QMK supports layers. There is a key on the base layer that acts as a modifier to take you to layer 2.

Note: the formatting is purely cosmetic - at the end of the day it’s still simply an ordered array. This means if you accidentally insert a key, every key after it will be off-by-one.

There are QMK configurator sites you can use to visualize a potential layout but I’m not sure which ones work correctly with Ellipse F77 layouts and there’s a warning on the official site not to use some of them, so I won’t link any particular one here.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
    /* Base */
    [_BASE] = LAYOUT_ansi_hhkb_split_shift_split_backspace(
        KC_ESC, KC_1, KC_2, KC_3, KC_4, KC_5, KC_6, KC_7, KC_8, KC_9, KC_0, KC_MINS, KC_EQL, KC_BSLS, KC_GRV,    KC_PSCR,   KC_SLCK, KC_PAUS,
        KC_TAB,    KC_Q, KC_W, KC_E, KC_R, KC_T, KC_Y, KC_U, KC_I, KC_O, KC_P, KC_LBRC, KC_RBRC, KC_BSPC,        KC_INSERT, KC_HOME, KC_PGUP,
        KC_LCTRL,     KC_A, KC_S, KC_D, KC_F, KC_G, KC_H, KC_J, KC_K, KC_L, KC_SCLN, KC_QUOT, KC_ENT,            KC_DELETE, KC_END,  KC_PGDN,
        KC_LSFT,         KC_Z, KC_X, KC_C, KC_V, KC_B, KC_N, KC_M, KC_COMM, KC_DOT, KC_SLSH, KC_RSFT, MO(_FN),   KC_NO,     KC_UP,   KC_NO,
        KC_CAPS, KC_LALT, KC_LGUI,                      KC_SPC,                  KC_RGUI, KC_RALT, KC_RCTRL,     KC_LEFT,   KC_DOWN, KC_RIGHT
    ),
    [_FN] = LAYOUT_ansi_hhkb_split_shift_split_backspace(
        KC_GRV, KC_F1, KC_F2, KC_F3, KC_F4, KC_F5, KC_F6, KC_F7, KC_F8,   KC_F9, KC_F10,    KC_F11, KC_F12, KC_INS, KC_DEL,    KC_P7,   KC_P8,   KC_P9,
        KC_NO,      KC_NO, KC_NO, KC_NO, KC_NO, KC_NO, KC_NO, KC_NO, KC_PSCR, KC_SLCK, KC_PAUS, KC_UP, KC_NO, KC_DEL,          KC_P4,   KC_P5,   KC_P6,
        _______,     KC_VOLD, KC_VOLU, KC_MUTE, KC_EJCT, KC_NO, KC_PAST, KC_PSLS, KC_HOME, KC_PGUP, KC_LEFT, KC_RIGHT, KC_NO,  KC_P1,   KC_P2,   KC_P3,
        _______,         KC_NO, KC_NO, KC_NO, KC_NO, KC_NO, KC_PPLS, KC_PMNS, KC_END, KC_PGDN, KC_DOWN, _______, _______,      KC_P0,   KC_UP,   KC_PDOT,
        _______, KC_NO, _______,                             MO(_FN2),                           _______, KC_NO, _______,      KC_LEFT, KC_DOWN, KC_RIGHT
    ),
    [_FN2] = LAYOUT_ansi_hhkb_split_shift_split_backspace(
        _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______,    _______, _______, _______,
        _______,     _______, _______, EEPROM_RESET, RESET, _______, _______, _______, _______, _______, _______, _______, _______, _______,      _______, _______, _______,
        _______,         _______, _______, DEBUG, _______, _______, _______, _______, _______, _______, _______, _______, _______,                _______, _______, _______,
        _______,             _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______,          _______, _______, _______,
        _______, _______, _______,                             _______,                                       _______, _______, _______,          _______, _______, _______
    )
};

Compiling

You should now be able to build your keymap with make

make xwhatsit/brand_new_model_f/f77/wcass:tabell

This will produce output similar to the following:

QMK Firmware 0.17.0
Making xwhatsit/brand_new_model_f/f77/wcass with keymap tabell

avr-gcc (GCC) 12.1.0
Copyright (C) 2022 Free Software Foundation, Inc.
This is free software; see the source for copying conditions.  There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

Size before:
   text	   data	    bss	    dec	    hex	filename
      0	  20944	      0	  20944	   51d0	xwhatsit_brand_new_model_f_f77_wcass_tabell.hex

Compiling: quantum/command.c                                                                        [OK]
Linking: .build/xwhatsit_brand_new_model_f_f77_wcass_tabell.elf                                     [OK]
Creating load file for flashing: .build/xwhatsit_brand_new_model_f_f77_wcass_tabell.hex             [OK]
Copying xwhatsit_brand_new_model_f_f77_wcass_tabell.hex to qmk_firmware folder                      [OK]
Checking file size of xwhatsit_brand_new_model_f_f77_wcass_tabell.hex                               [OK]
 * The firmware size is fine - 20944/28672 (73%, 7728 bytes free)

Flashing

The final build artifact is a .hex file. You can flash it using dfu-programmer or any other flashing tool (Ellipse recommends a Windows GUI tool called Flip - I have not used this).

These are the steps I followed in June 2022. As this keyboard and it’s firmware are a work in progress, these steps will likely change in the future and this page may not be updated.

I was able to put the keyboard into bootloader mode using Fn + Space + R. If you monitor dmesg -w you will see the USB keyboard unplug itself and a completely different device appear on your system. There is a hardware method to enter bootloader mode that requires opening the case and physically shorting some pads on the board so hopefully that won’t be necessary.

Put your keyboard into bootloader mode

I like to watch the output of dmesg while doing this. You will see your keyboard unplug itself and the bootloader device attach.

Hold Fn + Space and press R.

Note: This special key combo is part of the keymap so if you overwrite it when modifying the keymap or flash a bad image, you will need to physically open the keyboard to get back into bootloader mode.

This will be a pain in the ass and is therefore not recommended.

Erase the old image and flash the new one

dfu-programmer atmega32u2 erase
dfu-programmer atmega32u2 flash .build/xwhatsit_brand_new_model_f_f77_wcass_tabell.hex

If these steps both succeed, congratulations. You can unplug and replug the board, or just use the bootloader to soft reboot it as follows: dfu-programmer atmega32u2 launch

Review of F77 keyboard

I may move this into it’s own post at some point. For now here are my thoughts

Cons

• The price is high and the wait is long (over a year) with no updates on your place in line
• Support will be on par with a typical open source project - a bunch of people doing it for free in their spare time. You will be asked to search forum threads for answers and any expectation of support will be met with indignation.
• You will need to install the keycaps yourself. If things don’t work you will need to troubleshoot and do repairs yourself. You will be expected to purchase tools and spare parts
• If you choose any nonstandard layout you will need to flash firmware yourself. If you are already a firmware engineer like myself this will only be a few hours of work

Pros

• There is no other keyboard like this available. The keyboard itself is a joy to type on - both the feel of the springs buckling on each keypress and the distinctive (and loud) clacking sound. It’s comfortable and accurate and very mechanically satisfying.

Summary

This is a great keyboard if you’re willing to put in a bit of work and are experienced with low level software / electronics. Don’t expect it to arrive assembled and working out of the box. Overall I’d say I spent 6-8 hours between when it arrived and when it was ready to be my daily driver.

I’m happy with it now and I plan to keep it, however I feel like the web site uses some deceptive marketing tactics which left a bad taste in my mouth after I realized what I had ordered wasn’t exactly what I thought.