Love mechanical keyboards? You're among friends. Friends who want to show you how to use QMK with the great RP2040 microcontroller from Raspberry Pi. Support for this was added in July 2022 to the develop branch by the QMK community.
If you don't care to set up your computer to compile QMK, each example also includes a .uf2 file that you can download and immediately start using on a compatible RP2040 board, no software installation required.
Each kind of operating system has different steps for this, and if you run into trouble check the official instructions from qmk for more information and troubleshooting info!
For Windows, the best practice is to install "QMK WSL" following the official instructions. If you prefer, you can install the older "QMK MSYS" instead, but in general QMK WSL is faster and more reliable for compiling QMK code.
Heading 3 Delete Cancel Save
Debian-based systems including Ubuntu
For Debian-based Linux distributions (including Ubuntu and Raspberry Pi OS), install git and pip using the package manager and then install the qmk command:
sudo apt install -y git python3-pip python3 -mpip install --user qmk
For macOS systems
For macOS, you will need to install Homebrew. Follow the instructions on https://brew.sh. Then, install the
qmk command using brew:
brew install qmk/qmk/qmk
Check that the
qmk command is working for you by asking it to report its version:
$ qmk --version 1.1.0
Next, for any kind of system, run
Answer "y" when asked to clone the firmware and install dependencies. Depending on your system, this may also prompt you for your password to install additional operating system packages.
Once this is done, you will have the
qmk command available, and an up to date copy of the source code in qmk_firmware folder within your home folder. The following pages of this guide show how to build and install a firmware.
Your RP2040 is fully reprogrammable through the RPI-RP2 bootloader, but automatic reset to upload from the Arduino environment does not work when the board has a QMK firmware installed. Instead, you need to manually access the bootloader. For more details on how to access the bootloader, check the guide for your particular board. Here are some general instructions:
- If a RESET button is available, double click it. This works only when the firmware is correctly functioning. If it doesn't work, use one of the below methods.
- If a RESET button is available, hold down the BOOT button and click RESET once.
- Hold down the BOOT button while plugging in the device
Once your computer has recognized the RPI-RP2 bootloader, you can either drag a new UF2 to the drive (CircuitPython, QMK, or Arduino) or initiate the build and upload of a firmware (Arduino or
Ready to get down to business? Pick up some compatible hardware, then continue to one of the other pages in this guide to flash the QMK firmware to your RP2040 board, and learn more about how to modify and customize QMK along the way. If you don't feel like compiling software right now, we've also provided a .uf2 file for each example so you can load it on your board right away.