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.

Install QMK on your computer

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!

Windows-based systems

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:

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:

Finish setting up the qmk environment

Check that the qmk command is working for you by asking it to report its version:

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.

Switching back to CircuitPython or Arduino

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 qmk flash)

Parts

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.