Basic QMK custom keyboard (with Ubuntu, Arduino Pro Micro)

After getting QMK to work, I thought it would be useful to document how I got it to work. This is starting from zero, using a Ubuntu live booting USB drive.


I’m using a basic Pro Micro dev board. It uses the ATMEGA 32u4, and supports USB natively, which is what we need. When getting these, make sure to get Micro-USB (otherwise you have the chonky mini-USB), and the 5V/16MHz version. There are tons of these on Aliexpress, Ebay, locally, etc. They cost around $5-10.

For testing, I’m just using 3 simple push-buttons on a breadboard.


(Made on DigiKey’s scheme-it - this link likely won’t work for you though)

The wiring is:

  • one side of all buttons is connected together to pin 4 (PD4) on the board
  • the other side of the buttons goes to pins 5, 6, 7 (PC6, PD7, PE6). We need the “PX#” numbering for the configuration later on (it’s how the pins are labeled on the chip).
  • that’s it.

For more complex layouts with multiple rows, you will need to additionally use diodes after the button, to the “row” wire. For smaller layouts, this is fine though.

Software setup

Starting from Windows 10, I installed Rufus & burned a Ubuntu USB drive following this guide.

Reboot, and you’re almost in Ubuntu. If you use “Try Ubuntu” in the installer menu, you get a live installation running from the USB drive. The installation resets when you reboot, so don’t reboot :-). Or install a real Ubuntu somewhere.

In Ubuntu, open Firefox and get back to this guide :-). Then open a terminal window for the rest.

  1. Update everything, install some things (click “Y” as needed here)
$ sudo apt update && sudo apt upgrade # Get up to date

$ sudo add-apt-repository universe # Universe repository needed for pip3
$ sudo snap install --classic code # installs Visual Studio Code as an editor

$ sudo apt install -y git python3-pip # installs git & Python / pip3

Now, following the QMK guide, do these:

$ python3 -m pip install --user qmk # install QMK

$ PATH=/home/ubuntu/.local/bin:$PATH # Add the QMK to the path

$ qmk setup # run the QMK setup (answer as needed)

# QMK is ready! Let's try it out
$ cd ~/qmk_firmware

# let's compile a random keyboard to try out
$ qmk compile -kb clueboard/66/rev3 -km default 

Keyboard settings

There’s a script util/ which sets up a basic 5-button keyboard for you. We only need 3 buttons, but we can leave the rest in there.

$ util/ # create a new basic keyboard
# pick a name, use "avr" as type, add your Name. 

You now have a basic keyboard set up. Let’s make changes for our device.

$ code keyboards/00test/ & # open editor

For our sample 3-key keyboard, we’re going to need to make some changes to the default files. For simplicity sakes, you can also keep things as-is, and act like a 5-key keyboard.

Open the file config.h and make the following changes:


#define MATRIX_ROW_PINS { D0, D5 }
#define MATRIX_COL_PINS { F1, F0, B0 }


#define MATRIX_ROW_PINS { D4, D5 }
#define MATRIX_COL_PINS { C6, D7, E6 }

(We don’t actually use D5, it doesn’t cause problems to leave it. The numbering here is the PX# labeling from the beginning, just without the P)

Now open and change:


BOOTLOADER = atmel-dfu


BOOTLOADER = caterina

Save both files, then see if it works :-)

$ make 00test:default:flash

At some point, you’ll see the request to reset the controller:

Detecting USB port, reset your controller now....

… for that, just connect the RESET pin to the GND pin (they’re right next to each other, you can use a screwdriver). It’ll continue quickly:

Device /dev/ttyACM0 has appeared; assuming it is the controller.
Waiting for /dev/ttyACM0 to become writable.

Connecting to programmer: .
(lots of stuff)

avrdude: verifying ...
avrdude: 16296 bytes of flash verified

avrdude: safemode: Fuses OK (E:FD, H:D8, L:FF)

avrdude done.  Thank you.

… congratulations, you now have a keyboard!

Try the keys. 1 Won’t work (it’s the mode switch), the other 2 should show either “1” or “a”. Clicking the mode-switch together with the others will input “” or “QMK is the best thing ever!”

If all worked out, you should be all set.

Keep in mind if you’re using the USB stick in the “try Ubuntu” mode, once you reboot all changes will be removed. Don’t use this mode if you want to make something, only use it if you need a clean setup to try out.

Comments / questions

There's currently no commenting functionality here. If you'd like to comment, please use Twitter and @me there. Thanks!

Tweet about this - and/or - search for latest comments / top comments

Related pages