QMK op een Keychron K2

SonixQMK

Ik noemde eerder al eens het SonixQMK-project, en in de afgelopen maanden zijn daar wat vorderingen geweest. Het is nu mogelijk om op de meeste Keychron K-modellen (let wel: niet de K Pro-modellen!) en alle C-modellen de QMK-firmware te draaien, mét behoud van Bluetooth-functionaliteit.

Intussen was Bluetooth voor mij wel een beetje een must-have geworden — het werkt goed en snel, geen gedoe met slechte verbindingen zoals je wel eens hoort, en de accu van het toetsenbord houdt het weken uit — er is geen reden om minder gesleep met draadjes niet te waarderen.

De ondersteuning voor Bluetooth is momenteel nog wel een beetje experimenteel. Ik kan je aanraden om er niet zomaar een beetje mee te gaan zitten frutten, maar eerst even lid te worden van de Discord-groep¹.

Firmware brouwen

Voor het bouwen van de firmware gebruik je dus QMK nodig. In plaats van de gewone fork van QMK moet je een fork van de fork gebruiken, en daar dan nog een specifieke branch binnen.

# ergens binnen een directory, ik gebruik zelf ~/git/
git clone "https://github.com/1Conan/qmk_firmware/ 1Conan-qmk_firmware"
cd 1Conan-qmk_firmware
git checkout iton_bt_testing

QMK heeft ook nog de nodige software nodig om firmware te kunnen bouwen en flashen. Omdat ik Tumbleweed draai, zijn bepaalde dingen natuurlijk weer nét even anders dan waar de gemiddelde handleiding vanuit gaat; dat komt meestal niet veel verder dan Ubuntu, en misschien Arch. Ik installeerde de volgende software:

sudo zypper addrepo https://download.opensuse.org/repositories/CrossToolchain:avr/openSUSE_Tumbleweed/CrossToolchain:avr.repo
sudo zypper ref
sudo zypper in -y avr-libc avrdude clang \
    cross-arm-binutils cross-arm-none-gcc12 \
    cross-arm-none-gcc8 cross-arm-none-newlib-devel \
    cross-avr-binutils cross-avr-gcc8 \
    dfu-programmer dfu-util \
    gcc make python3-pip
    unzip wget zip

Verder is het optuigen van de QMK-omgeving dan business as usual². In principe installeer en gebruik je wel de gewone QMK, maar de firmware bouw je binnen die branch van die fork.

Daarna kun je eventueel nog wat aanpassingen gaan maken in de keymap en configuratie (kom ik nog op terug), en je bouwt een firmware op de normale manier, in mijn geval voor een K2:

qmk compile -kb keychron/k2/rgb -km ansi

...waarna je na wat functioneel gepruttel als het goed is in .build/ een .bin-bestand hebt met de naam van je toetsenbord en keymap erin. In mijn geval is dat dus .build/keychron_k2_rgb_ansi_ansi.bin.

Protip: kopieer die, als je eenmaal een goed werkende versie hebt, zodat je eventueel makkelijk kunt teruggrijpen op die versie als je eens iets hebt veranderd en het wordt een puinhoop.

Firmware flashen

Vervolgens moet je die firmware op je toetsenbord krijgen. Daar is een grafisch ding voor, maar die werkt bij mij voor geen meter, en er is een command-line tool die werkt als een speer. Ophalen en bouwen dan maar:

# wel even zeker weten dat je niet meer in de QMK-directory zit!
git clone --recursive https://github.com/SonixQMK/SonixFlasherC
cd SonixFlasherC
make sonixflasher 

Als je daar zonder kleerscheuren doorheen komt, kun je de verse firmware naar je toetsenbord drukken. Daarvoor moet het toetsenbord eerst in een speciale "ik sta nu klaar om een firmware te ontvangen"-stand worden gezet³. Keychron heeft daarvoor op de meeste van hun modellen twee contactjes onder de spatiebalk gemaakt; als je je toetsenbord uitzet, en daarna aanzet terwijl je die contactjes met elkaar verbindt, kom je in de bootloader terecht en kun je flashen (je herkent die modus doordat je verlichting niet aangaat).

Nou hebben de RGB-borden van Keychron een net iets andere MCU dan de wit-licht-borden van Keychron; die op de RGB-borden is iets krachtiger, en is ook eigeniljk niet te bricken⁴. Het verschil brengt verder met zich mee, dat je je firmware niet gelijk aan het begin van je toetsenbord moet zetten, maar met een zogenaamde offset. Ik heb daar niet mee te maken, en ik ga me daar dan ook niet aan branden. De documentatie van SonixQMK heeft daar wel meer informatie over.

Goed, ik druk mijn K2 dus naar de bootloader en start dan het flash-proces (de waardes achter --vidpid gelden voor alle toetsenborden met een 24xB-chip, waaronder mijn toetsenbord, andere chips hebben andere waardes!):

sudo ./sonixflasher --vidpid 0c45/7040 \
  --file ~/pad/naar/1Conan-qmk_firmware/.build/keychron_k2_rgb_ansi_ansi.bin

Die zou als het goed is na een seconde of wat je toetsenbord moeten vinden en de firmware ernaartoe moeten sturen; na een seconde of 5 is dat allemaal wel gedaan, en herstart je toetsenbord; je ziet dan een stuk RGB-verlichting.

Gefeliciteerd, je gebruikt nu QMK.

Wat mist er nog

De ondersteuning is, zoals eerder gezegd, nog wat experimenteel. Dat brengt af en toe gekkigheidjes met zich mee.

• Een enkele keer gaat het toetsenbord even over de hobbel en blijft een bepaalde toets "hangen". Dat is opgelost als ik het toetsenbord uit- en weer aanzet, en tot nu toe is het me nog maar één keer gebeurd, maar het schijnt wel eens voor te komen.
• Momenteel wordt het schrijven naar de EEPROM in het toetsenbord nog niet ondersteund, waardoor instellingen in de verlichting (met name "staat die aan of uit") niet worden onthouden — elke keer als ik het toetsenbord aanzet, begint-ie met de RGB-kots aan en in de eerste stand. Gelukkig is het makkelijk genoeg uit te zetten, en ook de standaard firmware van Keychron zette de verlichting aan bij het inschakelen van het toetsenbord.
• Het schijnt dat de slaapstand nog niet helemaal is geïmplementeerd, wat betekent dat ik sneller dan voorheen weer verbinding heb met de laptop als ik die uit slaap haal (yay), maar dat (vermoedelijk) de accu van het toetsenbord sneller leeg is (nog geen last van gehad, maar toch).

Ik heb er alle vertrouwen in dat de onvolkomenheden mettertijd worden weggepoetst, en tot die tijd zijn het geen show-stoppers.

Mappings en configuratie

Allereerst: bepaalde mappings zijn nu anders; verbinden met Bluetooth-profielen gaat nu met fn+Q/W/E (in plaats van 1/2/3), en je hebt er fn+Esc bij gekregen om direct naar bootloader te komen, zonder gehannes met spatiebalken.

Belangrijkste reden waarvoor ik QMK wilde draaien, en wat ik tot nu toe deels met KMonad heb kunnen opvangen, is de waanzinnige hoeveelheid configuratie. Een belangrijk (maar lang niet het enige) onderdeel is het her-indelen van bepaalde toetsen. Dat groeide al snel uit tot een laag voor beweging (met Caps Lock ingedrukt veranderen hjkl in cursortoetsen, zoals ik dat in Vim ook gewend ben) en, als je dan toch bezig bent, een numeriek eiland (dus m,. wordt 123, jkl wordt 456, en uio wordt 789, met nog wat toetsen eromheen voor 0 en zo).

En toen ontdekte ik "home row mods"⁵... Ik schreef daar destijds over:

Interessanter is dat ik nu home row mods gebruik; na een week nog steeds een beetje wennen, hoewel het steeds natuurlijker gaat, en ik af en toe home row mods probeer te gebruiken als ik het toetsenbord aan mijn telefoon heb hangen...

Dat is het enige echte nadeel aan KMonad: het werkt aan de computerkant, niet aan de toetsenbordkant. Dus wel op de computer, maar niet op mijn telefoon. QMK verplaatst die mappings naar mijn toetsenbord, waardoor ze op elk apparaat werken waar ik het aan koppel, of dat nou een laptop of een telefoon is.

Bijkomend voordeel: bepaalde dingen die KMonad niet helemaal, of helemaal niet, lijkt te ondersteunen, werken in QMK beter. Ook de homerow-mods werken nu beter dan dat ze onder KMonad deden. Waar ik voorheen meer moest pielen met de precieze timing, en dan nog steeds af en toe een misser had (dus een letter die als mod werd geïnterpreteerd, of andersom), lijk ik dat nu veel minder te hebben. Vermoedelijk hangt dat samen met het instellen van PERMISSIVE_HOLD en IGNORE_MOD_TAP_INTERRUPT; de tapping term is nu voor alle toetsen 200ms, iets dat ik in KMonad per toets een beetje had aangepast.

Ik ben behoorlijk blij dat QMK nu werkt. Los van het feit dat ik nu mijn toetsenbord consistent op verschillende apparaten kan gebruiken, is het een mooie gelegenheid om überhaupt met QMK te leren werken, iets dat ongetwijfeld van pas gaat komen wanneer ik een Corne ga bouwen — die draait er immers ook mee. Verder ben ik overigens nog steeds wel blij met KMonad; niet alleen is het een mooi opstapje geweest naar het pielen met QMK-keymappings, ik gebruik het ook nog steeds voor het ingebouwde toetsenbord van de laptop zélf, waarop immers geen QMK geïnstalleerd kan worden.

Een plaatje van knopjes

Voor de volledigheid een afbeelding van hoe mijn mapping er nu uitziet — Caps Lock ingedrukt houden activeert de gele "move"-laag, de linker Alt de witte "numbers"-laag.