Ik begon op de kop af een jaar geleden met mijn toetsenbord-avontuur met de aanschaf van een Keychron K2, en toen was ik al bewust van het ontbreken van software om dat toetsenbord anders dan standaard in te stellen. Ik had echter wel dat specifieke model uitgekozen op de mogelijke toekomstige ondersteuning van de QMK-firmware, waarmee wél alles in te regelen is zoals ik dat zou willen.
Die toekomst is afgelopen weekend begonnen. Opgepast, hier gaat nerderij gepleegd worden.
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-groep1.
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 usual2. 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 gezet3. 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 bricken4. 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"5... 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.

-
Ik heb een fikse hekel aan Discord, maar voor deze groep en de Budgetkeebs-groep tolereer ik het. Nood breekt wet. ↩
-
Kwestie van
python3 -m pip install --user qmk && qmk setup
, als je geluk hebt. Als je geen geluk hebt, krijg je hopelijk genoeg informatie in de foutmelding om een oplossing te vinden... ↩ -
"Naar de bootloader booten", als je van de saaie terminologie houdt. ↩
-
Iets met een bootloader en dat die op de minder krachtige versie corrupt kan raken of dat je die overschrijft, of zo, ik weet er het fijne niet van, en voor mij is dat verder ook niet relevant. Als je op die manier je toetsenbord verkloot, schijnt het allemaal nog wel te redden te zijn, maar dan wordt het geavanceerde shit met solderen en seriële verbindingen en zo. Te vermijden. ↩
-
Je gebruikt dan een aantal toetsen op je home row zowel als "de gewone toets" als als "mod". In mijn geval:
f
enj
zijn gewoon f en j als ik ze kort indruk, maar als ik ze iets langer ingedrukt houd, zijn zeShift
.f+k
wordt dan dus alsShift+k
vertaald, dus krijg je eenK
. Op diezelfde manier zijnd
enk
tevensCtrl
,s
enl
tevensAlt
, ena
en;
tevensGUI
(Windows/Meta/Command, afhankelijk van het OS). Home row mods hebben als voordeel dat je veel minder met je handen aan het bewegen en reiken bent om bij mods te komen; normaal komen die veel meer op grotere bewegingen aan, nu verlaat je de home row niet. Ergonomisch! ↩