This guide is going to assume that you know how to use a terminal app on Linux. If you don't know how to use the command-line, you may want to try a free online course.
Open a terminal window. Commands to enter into the terminal will be formatted like this:
echo "hello, world"
You don't NEED to use Docker, but I made a Docker repository that makes it a lot easier to build and install QMK so I'm going to use that for this guide. On modern systemd-enabled distributions, you should be able to install Docker with the native package manager (sudo apt-get install docker, sudo dnf install docker, sudo pacman -S docker, etc) and then you should be able to start it with sudo systemctl start docker.
You'll also need git installed. It may already be installed for you, but if not, sudo apt-get install git or sudo dnf install git or pacman -S git... you get the idea.
Once you have a working git installation, you should clone my QMK-pearl-docker repository, like so:
git clone --recursive https://github.com/clee/qmk-pearl-docker
And then navigate into the new directory:
cd qmk-pearl-docker
As part of the git clone process above, if you followed the instructions and ran it with the --recursive option then you will have a full QMK checkout (and also a bootloadHID checkout) alongside the Dockerfile. (If you did not use the --recursive option when cloning, then you should run git submodule update --init now, before you do anything else.)
I recommend the following approach to using a custom keymap in QMK:
cp -a qmk_firmware/keyboards/pearl/keymaps/default qmk_firmware/keyboards/pearl/keymaps/custom-name
xdg-open qmk_firmware/keyboards/pearl/keymaps/custom-name/
This should open a file manager window with a file called keymap.c. Use any text editor you like (I personally prefer vim but Linux has nothing if not an abundance of text editors so go wild).
You should, of course, use another name for your keymap instead of custom-name. For example, my custom keymap is the same as my username, clee. If you change the name on your system, make sure to substitute it whenever the guide says custom-name.
Now, the fun part: I have embedded some environment variables (KEYBOARD, KEYMAP, and FLASHUTIL) in the Dockerfile. You can override them by changing the Dockerfile and rebuilding the Docker image, or you can just pass different variables to the docker run command. Yes, this means you could use this Docker setup to program any other QMK-supported keyboard; I just set these defaults to make it easier for Pearl users.
The default keymap has two layers, but you can add more if you follow the formatting, or you can start with jetpacktuxedo's keymap instead of the default (by substituting keymaps/jetpacktuxedo instead of keymaps/default in the above cp command). Some notes about the Pearl specifically:
- The first row can have two different configurations (a 2U backspace or 2x 1U keys in the same spot)
- If you use the 2U backspace, the very last keycode on the line is what will be sent when you press the key
- Otherwise, the key codes are 1:1 with the buttons across the whole first row
- The second and third rows only have a single supported configuration, and the key codes map 1:1 with the buttons on those rows
- The bottom row supports quite a few different key positions; you should be able to figure out the order of the keys by noting that the left spacebar, 6.25U/7U spacebar, and right spacebar all have separate positions on the board.
If you're making your own custom keymap with QMK, you'll want to keep the QMK documentation handy.
Some particularly useful pages in the QMK documentation are:
With advanced keycodes, for example, you could make a key send Ctrl when held, but Esc when tapped, with something like this:
CTL_T(KC_ESC)
QMK allows all kinds of incredibly advanced behavior. There's too much to cover in this guide, but here are a few pointers for faster typists. You can try adding a couple of lines to your qmk_firmware/keyboards/pearl/config.h, right before the final #endif line:
#define PERMISSIVE_HOLD
#define TAPPING_TERM 125
PERMISSIVE_HOLD is better documented in the QMK docs, and TAPPING_TERM is the number of milliseconds after which a tap turns into a hold. The QMK default is 200ms.
First, you need to build the Docker image. I would upload prebuilt images to the global Docker hub, but the Pearl is so flexible that it can be built many ways, and it's unlikely that you chose to build yours with the default layout. For now, try this (make sure you don't forget the ./ at the end! It's there to tell docker build which directory contains the Dockerfile.)
docker build -t qmk-pearl ./
And once it's built, you can run the new container image image to flash the firmware to your Pearl.
Once you are ready to test your custom keymap, you can flash it to your Pearl by putting the Pearl into bootloader mode and running the following command:
docker run -it --rm --privileged -v /dev/bus/usb:/dev/bus/usb -v ./qmk_firmware:/opt/qmk_firmware -e KEYMAP=custom-name qmk-pearl
If you edited the Dockerfile to set the KEYMAP, then you can drop the -e KEYMAP=custom-name part of the above command, since it's unnecessary, but it won't hurt anything to leave it in.
Some additional explanation of the docker arguments:
-ittells Docker that the program being run is an interactive terminal program, which means you'll see output as it happens instead of delayed. This is definitely a good idea.--rmtells Docker to delete the container after it's done with its work. Not strictly necessary, but a good idea nonetheless to prevent Docker from cluttering up your disk with a bunch of old stale containers.--privileged -v /dev/bus/usb:/dev/bus/usbis used to enable writing to USB devices from inside the Docker container; this is one way to enable this feature. You could also put your Pearl into bootloader mode and uselsusb | grep 16c0to find the bus and device number of your Pearl; it should output something likeBus 003 Device 074: ID 16c0:05df Van Ooijen Technische Informatica HID device except mice, keyboards, and joysticks. You would then, instead of--privileged -v /dev/bus/usb:/dev/bus/usb, pass--device=/dev/bus/usb/003/074(using the output from the example on my system). This is obviously more complex than the other option, but it also doesn't require your user to have special privileges, so it's more secure. Your call.-v ./qmk_firmware:/opt/qmk_firmaretells Docker to take theqmk_firmwarefolder on the host and make the same contents available in the guest at the right spot. This makes it so you don't have to rebuild the Docker image every time you change your keymap.-e KEYMAP=custom-nametells Docker to override theKEYMAPvariable from the Dockerfile with your own value. As noted above, if you already changed theKEYMAPin the Dockerfile, this argument is completely unnecessary.
- Unplug your keyboard from the computer and hold down the 'Esc' key (or whatever key you installed in the top left corner of the board).
- While holding the 'Esc' key, plug the USB cable back in. (See note below about USB)
- If you soldered the indicator LEDs in the lower-right corner of your Pearl, all three should be blinking at a steady medium pace. This means the Pearl has successfully entered bootloader mode, so it can be programmed with a new firmware image.
- You can let go of the 'Esc' key as soon as you see all three LEDs flashing.
- Run the command to flash your Pearl.
- Your Pearl should now be running QMK.
A note about USB: You may have better luck reprogramming the Pearl's firmware if you plug the cable into a USB port that is directly attached to your motherboard. Some USB hubs don't provide enough power, or they don't transfer the data with the correct timing, or other various issues; if your firmware doesn't program correctly because of a communication error, try unplugging as many USB devices as possible and plug the Pearl directly into the motherboard without any hubs or extensions and try again. (Unplug, hold Esc, replug, rerun the command to flash the Pearl.)