Step-By-Step Guide To Setting up QMK for the Planck on macOS
(Part 1 of Step-By-Step Guide To Configuring Your Planck Using QMK, VIA and Vial on macOS)
To configure QMK there is no getting away from some CLI action, so let’s get started with the main firmware first, and then let’s explore Via and Vial (Part 2 and 3). Looks like there are no clean shortcuts.
Let’s start with the official Complete Newbs Guide.
We are basically going to build a new (custom/homebrew) keyboard firmware from the source code. Our Planck came with qmk firmware preinstalled, and now we are going to build our own so we can customize it to our liking.
I am going to assume that you have some programming experience but if you don’t I think you will still be able to follow along nicely.
Part 1 Environment setup
Official documentation at: Setup Your Environment.
1.1 Install a text editor
If you don’t already have a favorite text editor you will have to install one. Sublime, Atom, VS code are all great (and free!) choices.
1.2 Install Homebrew
You will need to install Homebrew. What does homebrew do? It “installs the stuff you need that Apple (or your Linux system) didn’t.”
Installation is super easy:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"1.3 Install the QMK tooling
Install the qmk toolbox. The toolbox is a “graphical program for Windows and macOS that allows you to both program and debug your custom keyboard.”
My guess is that the toolbox is going to make our lives easier, so I am going to opt to install it even though it is optional according to the docs.
Let’s see if the installation is simple.
Option A: Installing the binary
For those not comfortable with coding of if homebrew is just not your thing you can always Download and install the binary directly.
Option B: Installing via homebrew
For those familiar with homebrew, Homebrew-Cask is an extension that allows the installation of GUI applications (such as Google Chrome or Atom).
brew tap homebrew/cask-drivers
brew install --cask qmk-toolboxAnd the command to upgrade, if you ever need it:
brew cask upgrade qmk-toolbox1.4 Install the QMK CLI
Per the docs:
The QMK CLI makes building and working with QMK keyboards easier. We have provided a number of commands to simplify and streamline tasks such as obtaining and compiling the QMK firmware, creating keymaps, and more.
Install the QMK CLI by running:
brew install qmk/qmk/qmk1.5 Setup Git for QMK
Git comes installed by default on most Mac and Linux machines.
Follow the instructions How to Use GitHub with QMK to get your fork of the repo at qmk/qmk_firmware under your own github account. This will prepare your local qmk repo with the remote origin already pointing to your own github url.
You don’t have to clone the repo locally (the next QMK setup will do it for you), but if you want to you can go ahead:
git clone --recurse-submodules https://github.com/<github_username>/qmk_firmware.git1.6 Run QMK Setup
Once you have installed QMK you will have to set it up.
qmk setupOr better yet if you followed the git setup
qmk setup <github_username>/qmk_firmwareIf you care where the firmware folder will be installed (or are just as obsessive-compulsive as I am) then use:
qmk setup <github_username>/qmk_firmware -H <folder>You will get some prompts. In most cases, you want to accept the default options.
☒ Could not find qmk_firmware!
Would you like to clone <github_username>/qmk_firmware to '<folder>/qmk_firmware'? [y/n] y
Cloning into '<folder>/qmk_firmware'...
[...]
Ψ Successfully cloned https://github.com/<github_username>/qmk_firmware to <folder>/qmk_firmware!
Ψ Added https://github.com/qmk/qmk_firmware as remote upstream.
Would you like to set '<folder>/qmk_firmware' as your QMK home? [y/n]
[...]
☒ Can't find arm-none-eabi-gcc in your path.
☒ Can't find avr-gcc in your path.
Would you like to install dependencies? [Y/n] y
[...]
Ψ QMK is ready to go
Success!
If at a later time you want to move the installation folder you can do it following the instructions by using the cli configuration to edit the variable user.qmk_home.
To read the configuration value you can do:
qmk config user.qmk_homeAnd to set it to a new value:
qmk config user.qmk_home=<new folder>1.7 Validate the setup
To validate the installation and setup let’s generate qmk firmware with a default keymap.
qmk compile -kb <keyboard> -km defaultYou can find a list of valid keyboards on github Included Keyboards.
For instance for our Planck keyboard we would use:
qmk compile -kb planck/rev6_drop -km defaultAt the end of the compilation (which should take less than a minute), you’ll get something like this:
Creating binary load file for flashing: .build/planck_rev6_drop_default.bin [OK]
Creating load file for flashing: .build/planck_rev6_drop_default.hex [OK]
Size after:
text data bss dec hex filename
0 51240 0 51240 c828 .build/planck_rev6_drop_default.hex
Copying planck_rev6_drop_default.bin to qmk_firmware folder [OK]
(Firmware size check does not yet support cortex-m4 microprocessors; skipping.)The .build folder inside qmk_firmware should show the following new files:
planck_rev6_drop_default.bin
planck_rev6_drop_default.elf
planck_rev6_drop_default.hex
planck_rev6_drop_default.map1.8 Setup your keyboard defaults
Ok, I haven’t lost you yet? We are almost there…
To make future development easier, set your default keyboard to whatever you have from the list of included keyboards.
qmk config user.keyboard=planck/rev6_dropGive your default keymap name. QMK recommends most people use their GitHub username:
qmk config user.keymap=<github_username>Your configurations are saved to /Users/<username>/Library/Application Support/qmk/qmk.ini
Now that the defaults are set you can compile your keyboard simply like this.
qmk compileDon’t run this command yet, though since you need to create your first keymap first to get it to run.
That’s it! We are done setting things up!
Part 2 Building the firmware
Official documentation at: Building Your First Firmware.
2.1 Create a new keymap
To create a new keymap run the following command. A copy of the default QMK keymap will be generated for you with the name used for config user.keymap that you should have configured in Part 1.
qmk new-keymapHere is the output:
Ψ <username> keymap directory created in: <folder>/qmk_firmware/keyboards/planck/keymaps/<github_username>
Ψ Compile a firmware with your new keymap by typing:
qmk compile -kb planck/rev6_drop -km <github_username>Make a note of the new folder where the keymap is stored. In the case above that is <folder>/qmk_firmware/keyboards/planck/keymaps/<github_username>. This is the place where you will go edit your new keymap.
2.2 Locate your keymap files
As we mentioned before in my case this is located at <folder>/qmk_firmware/keyboards/planck/keymaps/<github_username>. If you didn’t save this location in the previous step look for the keymap in the keyboard family you used and search for your username.
Here are the contents of this folder:
config.h
keymap.c
readme.md
rules.mkThe file keymap.c contains the layout and behavior of your keyboard.
Around lines 40-50 the layouts section starts. It would display ASCII representation of the layers like this:
/* Qwerty
* ,-----------------------------------------------------------------------------------.
* | Tab | Q | W | E | R | T | Y | U | I | O | P | Bksp |
* |------+------+------+------+------+------+------+------+------+------+------+------|
* | Esc | A | S | D | F | G | H | J | K | L | ; | " |
* |------+------+------+------+------+------+------+------+------+------+------+------|
* | Shift| Z | X | C | V | B | N | M | , | . | / |Enter |
* |------+------+------+------+------+------+------+------+------+------+------+------|
* | Brite| Ctrl | Alt | GUI |Lower | Space |Raise | Left | Down | Up |Right |
* `-----------------------------------------------------------------------------------'
*/Here is where you will be doing your edits to add or remove layers, keys, behaviors, etc.
You can read further about how to Customize The Layout To Your Liking
2.3 Test the compilation
If you have your keymap defaults setup you can now compile simply by doing:
qmk compileYou might see output like this:
Creating binary load file for flashing: .build/planck_rev6_drop_<github_username>.bin [OK]
Creating load file for flashing: .build/planck_rev6_drop_<github_username>.hex [OK]
Size after:
text data bss dec hex filename
0 51240 0 51240 c828 .build/planck_rev6_drop_<github_username>.hex
Copying planck_rev6_drop_<github_username>.bin to qmk_firmware folder [OK]
(Firmware size check does not yet support cortex-m4 microprocessors; skipping.)Here are the generated files:
planck_rev6_drop_<github_username>.bin
planck_rev6_drop_<github_username>.elf
planck_rev6_drop_<github_username>.hex
planck_rev6_drop_<github_username>.mapPart 3 Flashing the firmware
Official documentation at: Flashing Firmware
3.1 Enter bootloader mode
In the case of a Planck keyboard, this is accomplished by the key combo raise+lower+q, or pressing the reset button on the bottom of the board. The Planck should play the reset sound and the LEDs should turn off.
YMMV with your keyboard. Check QMK’s instructions to Put Your Keyboard into DFU (Bootloader) Mode if you are having trouble.
Open QMK Toolbox
If you have QMK Toolbox open you should see something along these lines:
*** DFU device connected: Atmel Corp. ATmega32U4 (03EB:2FF4:0000)
*** HID console connected: OLKB Planck (FEED:6060:0006)
*** HID console disconnected: OLKB Planck (FEED:6060:0006)
*** STM32 DFU device connected: STMicroelectronics STM32 BOOTLOADER (0483:DF11:2200)3.2 Open Your Keymap Firmware with QMK Toolbox
Open the firmware file in QMK Toolbox. It can be found in the root /qmk_firmware/ folder:
The firmware file follows this naming format:
<keyboard_name>_<keymap_name>.{bin,hex}in my case:
planck_rev6_drop_<github_username>.bin3.3 Flash Your Keyboard with QMK Toolbox
Click the Flash button in QMK Toolbox.
Here is my output in all its glory:
*** Attempting to flash, please don't remove device
>>> dfu-util -a 0 -d 0483:DF11 -s 0x8000000:leave -D <folder>/qmk_firmware/planck_rev6_drop_username.bin
dfu-util 0.10
Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc.
Copyright 2010-2020 Tormod Volden and Stefan Schmidt
This program is Free Software and has ABSOLUTELY NO WARRANTY
Please report bugs to http://sourceforge.net/p/dfu-util/tickets/
Opening DFU capable USB device...
ID 0483:df11
Run-time device DFU version 011a
Claiming USB DFU Interface...
Setting Alternate Setting #0 ...
Determining device status: state = dfuERROR, status = 10
dfuERROR, clearing status
Determining device status: state = dfuIDLE, status = 0
dfuIDLE, continuing
DFU mode device DFU version 011a
Device returned transfer size 2048
DfuSe interface name: "Internal Flash "
Downloading element to address = 0x08000000, size = 51244
Erase [ ] 0% 0 bytes
Erase [ ] 3% 2048 bytes
Erase [= ] 7% 4096 bytes
Erase [== ] 11% 6144 bytes
Erase [=== ] 15% 8192 bytes
Erase [==== ] 19% 10240 bytes
Erase [===== ] 23% 12288 bytes
Erase [====== ] 27% 14336 bytes
Erase [======= ] 31% 16384 bytes
Erase [======== ] 35% 18432 bytes
Erase [========= ] 39% 20480 bytes
Erase [========== ] 43% 22528 bytes
Erase [=========== ] 47% 24576 bytes
Erase [============ ] 51% 26624 bytes
Erase [============= ] 55% 28672 bytes
Erase [============== ] 59% 30720 bytes
Erase [=============== ] 63% 32768 bytes
Erase [================ ] 67% 34816 bytes
Erase [================= ] 71% 36864 bytes
Erase [================== ] 75% 38912 bytes
Erase [=================== ] 79% 40960 bytes
Erase [==================== ] 83% 43008 bytes
Erase [===================== ] 87% 45056 bytes
Erase [====================== ] 91% 47104 bytes
Erase [======================= ] 95% 49152 bytes
Erase [======================== ] 99% 51200 bytes
Erase [=========================] 100% 51244 bytes
Erase done.
Download [ ] 0% 0 bytes
Download [= ] 7% 4096 bytes
Download [== ] 11% 6144 bytes
Download [=== ] 15% 8192 bytes
Download [==== ] 19% 10240 bytes
Download [===== ] 23% 12288 bytes
Download [====== ] 27% 14336 bytes
Download [======= ] 31% 16384 bytes
Download [======== ] 35% 18432 bytes
Download [========= ] 39% 20480 bytes
Download [========== ] 43% 22528 bytes
Download [=========== ] 47% 24576 bytes
Download [============ ] 51% 26624 bytes
Download [============= ] 55% 28672 bytes
Download [============== ] 59% 30720 bytes
Download [=============== ] 63% 32768 bytes
Download [================ ] 67% 34816 bytes
Download [================= ] 71% 36864 bytes
Download [================== ] 75% 38912 bytes
Download [=================== ] 79% 40960 bytes
Download [==================== ] 83% 43008 bytes
Download [===================== ] 87% 45056 bytes
Download [====================== ] 91% 47104 bytes
Download [======================= ] 95% 49152 bytes
Download [======================== ] 99% 51200 bytes
Download [=========================] 100% 51244 bytes
Download done.
File downloaded successfully
Transitioning to dfuMANIFEST state
*** STM32 DFU device disconnected: STMicroelectronics STM32 BOOTLOADER (0483:DF11:2200)
*** HID console connected: Drop Planck (03A8:A4F9:0006)3.4 Flash Your Keyboard from the command line
You can also flash your keyboard from the terminal like this:
qmk flashYou are done! You are set up to edit your keymap and flash your changes to your keyboard.
Enjoy! 🍾