qmk / qmk_configurator

The QMK Configurator

Quantum Mechanical Keyboard Configurator

The QMK Configurator is an online tool used for easily creating firmware files for keyboards supported in qmk_firmware. The tool is located on https://config.qmk.fm.

The QMK Configurator allows simple keymap creation and saving via .json keymap files, and generates appropriate firmware files for flashing onto selected keyboards.

This project is very much a work in progress. To begin contributing, please refer to the following:

• Issues

Development

We recommend you install and use NVM to manage node versions. There is a .nvmrc file in the root of the project directory that has been tested with our dependencies.

Select node version

nvm use

Project setup

yarn install

Compiles and hot-reloads for development

yarn run dev

Compiles and minifies for production

yarn run build

Run your tests

yarn run test

Lints and fixes files

yarn run lint

Run your end-to-end tests

Start the server separatly

yarn run test:cypress

Run your end-to-end tests like CI

Start the server separatly

yarn run test:cypress:ci

Run your unit tests

yarn run test:unit

Customize configuration

See Configuration Reference.

Docker

If you don't have a webserver already and don't already have one in mind you can use docker. By default it spins up a self-contained environment.

docker run -p 8080:80 qmkfm/qmk_configurator:latest

You can specify a different backend URL by setting VUE_APP_API_URL:

docker run -e VITE_API_URL=http://localhost:8080 -p 8080:80 qmkfm/qmk_configurator:latest

If you'd like to develop locally you can use a volume to tie your local filesystem to the container:

docker run --mount type=volume,source=.,target=/qmk_configurator -p 8080:80 qmkfm/qmk_configurator:latest

Building The Docker Image

Most of the time you don't need to do this, you can use volume mounts as described above to use the pre-built image with your local tree.

If for some reason you do need to build it yourself, you can use this command:

docker build -t qmk_configurator .

This process will take a while. You may want to go make some tea or something. When it finishes you can run it with this command:

docker run -p 8080:80 qmk_configurator

Internationalization Guide

Please refer to this document

qmk_configurator's Issues

Should be able to type in keycodes

Container keycodes don't accept child keycodes

Such as LSFT and friends.

Bug: Backlight Toggle Missing

Current QMK Configurator only offers 4 Backlight modifiers. It is missing BL_BRTG as described in

https://docs.qmk.fm/features/backlight

Viewing of readme should be available

Some keyboards have caveats such as "led support not currently available" which are documented in the readme.

When using the configurator, a customer does not see this information and may incorrectly think that the configurator is at fault.

Provide a means to display the readme file to the user.

Keymap is broken for long keyboards TKL and over

It ends up being shifted too far down.

http://config.qmk.fm/#/k_type/KEYMAP

console output gets crowded/messy when switching between different keyboards

The current workaround is to do a page refresh.

Some suggestions

1. Include a button to clear the console output
2. Auto clear whenever a new board is selected
3. Improve error messages. Rather than "No default for this keyboard", specify which keyboard.

import stops working when switching keyboard

steps

1. import a keyboard from json - loads json
2. switch keyboard - loads new keyboard
3. import keyboard from json - doesn't do anything

Exporting nameless Keymaps

Exporting a keymap without a name names it as json.txt. However this file still works when you Import it back in.

When a nameless keymap is detected, we should default to the default "mine" name, and still create a mine.json.

Numpad in Keycode Selection is Missing 3

It's missing 3!!!

Thank you to isabella on the r/mk discord for reporting.

Two Click Keymapping

This request comes from notG10, one of the moderators of the Top Clack Discord.

Click and dragging can be quite strenuous. It would be great to be able to select an empty/filled spot on the keyboard representation, and then click on a keycode you want.

To be clear, this is not to get rid of the click and drag feature, but rather as another form of keycode entry.

poll compile back end and display backend status in UI

curl https://compile.clueboard.co/v1
{
"children": [
"compile",
"converters",
"keyboards"
],
"status": "running",
"version": "0.1\n"
}

Add the ability to move a group of keys between different keyboards

Scaling doesn't reset when importing keymaps on Firefox.

If on a larger board that is scaled down to fit such as the converter/ibm_terminal when importing a smaller keyboard such as the dz60 it does not scale back up. Seems to only affect firefox.

Compiling a blank keymap is not useful

There does not seem to be any use to compiling a blank keymap, as the resulting .hex still wouldn't get me anywhere in terms of keyboard usability.

We could use the dirty keymap checks to temporarily gray out the compile button until the keymap does indeed have at least one keycode.

alert if you have unsaved changes and navigate away

Use the dirty checking to warn user of unsaved changes. Clear the flag if they export.

layout isn't saved when we export a keyboard

This can lead to keymap being imported into the wrong layout and applied to the wrong keys.
steps to reproduce:

1. create a keymap
2. export it with some changes
3. change the layout
4. reimport the json

Since we didn't record the layout used to generate the map this can lead to some odd ui issues.

gh-pages setup for noobs

We should create documentation on how to do this, in a manner friendly to noobs, such as myself. =).

1. fork the project
2. git co gh-pages
3. rm CNAME
4. add you _config.yml
5. push to gh-pages
6. reload after about 10-15 seconds

Confirmation dialogue needed when loading default keymap

load default
This button provides no confirmation dialogue. When a user has crafted a suitable keymap, accidentally pressing the button wipes away their hard work.

When any form of keymap is present, load default should provide a yes/no confirmation dialogue to prevent such mishaps.

import layout
The same can be said with this button, but a user needs to specify a file to load, so the chances of wiping away their current keymap is much less.

Render the README instead of showing source

Currently the source is shown for the keyboard README. Many users will not understand the formatting, and most would prefer to see the rendered version.

Empty keymaps are not removed when compiling.

This is an issue as if a user randomly clicks on layers they are not using it creates an empty layer which is not removed on compile time and increases how long it takes.

MO(X) doesn't get exported/imported properly

When creating a keymap with Fn key. Placing anything in MO() results in it being set to 0 when exported and imported.

Add dirty keymap detection

• centralize all access to keymap[] via some sort of API
• add hooks to detect changes
• use keymap state to decide to show alerts when switching keymaps, layouts, keyboards, importing instead of just prompting

have status window scroll down when new messages appear.

Provide means to download .bin file

On keyboards such as the whitefox, flashing is done by doing

dfu-util -D ../../.build/whitefox_default.bin  -S mk20dx256vlh7

The QMK Configurator currently has no means to download the required .bin file.

Localisation

Setup a localisation system for strings

Provide a link to keycode reference on the page

Most people aren't familiar with QMK keycodes and sometimes the hovering over the key is completely missed, or just still not clear enough.

We should provide a link to the keycode reference on the page.

Render ISO enter keys correctly in keymap

Because they aren't rectangles, they don't render quite right.

Figure out a way to add the extra bit.

Sat+ appears twice in RGB Lighting key selection

Reset 'active' layer to 0 on loading default

If you are in the layer UI, and click load default, the active layer stays on the layer you last clicked on. It should reset to 0.

reproduce:

1. select planck keyboard
2. click layer (10)
3. load default

Symption:

layer 10 is still active but you are actually looking at layer 0.

Populate the interface from an existing keymap

Needs qmk/qmk_api#11 to be completed first.

Would be nice to have a way to save and iterate on layouts

There is a "download source" button which is maybe intended for this but currently seems to do nothing. Download source + 5 or maybe 6 could do what I'm suggesting, maybe.

Semantics: QMK Configurator != Firmware

For those new to the keyboard flashing world, the image seems to imply that QMK Configurator is the firmware when it is not.

Perhaps it should say, "A GUI for QMK open source keyboard firmware" or something of the sort.

Flash ARM boards from page

nested two-parameter keycodes fail to compile

For instance, when I put a LGui_T inside a Rctl_T keycode, the compiler comes back with an error. I think it should be impossible to put two-parameter keycodes inside another two-parameter keycode? Picture to illustrate below:

Interface for retrieving KLE raw code for a particular keyboard/keymap

Needs qmk/qmk_firmware#2621 and qmk/qmk_api#12 to be completed first

add keycode assignment by doubleclick

double click a keymap item, pop up an input dialog and allow input of a 'KC_' code with validation and possibly autocomplete.

Upload keymaps for editing

Currently, a user has to start from scratch every time the configurator is used.

It would be good if a user were allowed to upload an existing keymap for editing either as something they were working on before, or a default keymap provided by QMK as a good starting point. On 60%s it's not an issue, but on TKLs, the click and drag approach even for edits becomes tiresome.

click to deselect a selected keymap key

Interface for previewing info.json code

When importing keymap it does not set the keymap to dirty.

Feature: Song Selection/Creation

There are some keyboards with built in speakers that allow people to program songs.

It would be cool to have a tab in QMK Configurator that would allow song selection of default songs, or even a mini web app that would allow a user to create their own song through the website.

Support for ARM keyboards like K-Type and Whitefox

Please add support for the Input Club keyboards, for example K-Type and Whitefox.
#72 Advises that ARM keyboard support is not ready and has been removed.

tkc1800 layout

The layout is broken in the configurator.

https://config.qmk.fm/#/tkc1800/KEYMAP

Change event not triggered when loading the same keymap in chrome.

keymap not reloading if the same file is loaded a second time in chrome.

Keymap presentation is broken for very tall keyboards

It looks like it is assumed that a keymap will be no taller than the layer picker.

limit the size of the layout dropdown

https://config.qmk.fm/#/clueboard/60/LAYOUT_60_ansi_split_bs_rshift causes it to push all the UI elements off to the next row. Limit the size of the layout drop down in CSS.

Unchangeable shortcuts: Control+Backspace deletes a word. Alt+Backspace undo.

I'm compiling the ORG60 firmware and the control+backspace shortcut is very frustrating.

Support for alternate saving methods

It'd be great if there would be other saving methods like saving as a github gist like keyboard-layout-editor does or save in the browser like here.

Looks terrific, fails to compile for Input Club K-Type Keyboard

I created a base layer only, by clicking a key, then pressing the physical key on the keyboard.
I set the fn key to me MO1. This was done on macOS with chrome as the browser.

I exported the resulting json file (which I can provide if needed).

I pressed compile. Which failed with the output. pasted below.

Input Club K-Type

Firmware for custom keyboard PCB with TKL Key Layout

Keyboard Maintainer: Kaleb Elwert
Hardware Supported: Input Club K-Type
Hardware Availability: Input Club, Massdrop

Make example for this keyboard (after setting up your build environment):

make k_type:default

See build environment setup then the make instructions for more information.

• Sorry there is no default for the k_type keyboard... yet!
• Sending k_type:K-type-base-layer with KEYMAP
• Received job_id: 6e241c26-734d-4a85-8564-e5a0f45eaabb
• Running . . . . . . . . . . . . . .
• Finished:
  QMK Firmware 0.6.18
  �
  Some git sub-modules are out of date or modified, please consider runnning:�
  make git-submodule
  You can ignore this warning if you are not compiling any ChibiOS keyboards,
  or if you have modified the ChibiOS libraries yourself.

�

tmk_core/chibios.mk:38: lib/chibios-contrib/os/common/startup/ARMCMx/compilers/GCC/mk/startup_k20x7.mk: No such file or directory
tmk_core/chibios.mk:40: lib/chibios/os/hal/hal.mk: No such file or directory
tmk_core/chibios.mk:46: lib/chibios-contrib/os/hal/ports/KINETIS/K20x/platform.mk: No such file or directory
tmk_core/chibios.mk:79: lib/chibios/os/hal/osal/rt/osal.mk: No such file or directory
tmk_core/chibios.mk:81: lib/chibios/os/rt/rt.mk: No such file or directory
tmk_core/chibios.mk:87: lib/chibios/os/common/ports/ARMCMx/compilers/GCC/mk/port_v7m.mk: No such file or directory
tmk_core/chibios.mk:89: lib/chibios/os/hal/lib/streams/streams.mk: No such file or directory
makek'. Stop.
Makefile:534: recipe for target 'k_type:K-type-base-layer' failed
make: *** [k_type:K-type-base-layer] Error 1
�ake finished with errors

Consider changing naming of Download/Import Layout

The opposite of Download is Upload
The opposite of Import is Export.

I would suggest using Download/Upload as those terms are more familiar to non native English speakers.

We're also not exactly downloading/uploading a layout, but rather a keymap.