Installing CircuitPython on Keybow 2040

In this tutorial, we'll walk you through what you'll need to do to install CircuitPython on your Keybow 2040 mini mechanical keyboard, as well as showing you where to find the CircuitPython libraries that you'll need.

Your Keybow 2040 will come with CircuitPython and the necessary libraries pre-installed, but you might find this guide useful if you want to upgrade to the latest versions, or if something goes wrong and you need to start from scratch.

What you'll need

Downloading and installing CircuitPython

We're using CircuitPython as the firmware for Keybow 2040 as HID is not yet supported in MicroPython.

First of all, go to this page and download the most recent .uf2 file - this is a customised version of CircuitPython built especially for Keybow 2040.

Screenshot showing CircuitPython download page

Whilst holding down the BOOTSEL button on your Keybow, connect it to your computer with the USB-C cable. Once you've plugged it in, it should show up as a drive called RPI-RP2. Copy the downloaded .uf2 file to this drive. After a few seconds it should show up as a drive named CIRCUITPY - it's now running CircuitPython.

This is what the CIRCUITPY drive looks like in Windows:

Screenshot showing CIRCUITPY drive in Windows

If you'd like to learn more about CircuitPython and how it works, there's a ton of information on the Adafruit site.

Downloading and installing the libraries

The next thing you'll need to do is download and install the libraries that Keybow uses. CircuitPython libraries are installed by copying files from your computer to the lib folder in the CIRCUITPY drive - super easy!

First up is the Adafruit IS31FL3731 library - this is a driver for Keybow's LED matrix controller. The easiest way to get it is via the CircuitPython Library Bundle, which you can download from this page.

Screenshot showing the CircuitPython Library Bundle download page

Once you've unzipped the file, copy the adafruit_is31fl3731 folder from the bundle's lib folder across to the lib folder on your CIRCUITPY drive.

Next, you'll need to download the Keybow 2040 library from Github. Click on the green 'Code' button at the top of the page, and select 'Download ZIP' in the dropdown - this will download the whole library, complete with examples.

Screenshot showing downloading the Keybow 2040 library from Github

Unzip the file, and copy into the lib folder on CIRCUITPY. The contents of the lib folder on your CIRCUITPY drive should now look something like this:

Screenshot showing the contents of the lib folder

Running the examples

To run one of the examples, all you need to do is rename it to and copy it to CIRCUITPY - CircuitPython will automatically detect changes and start running the code. We'd suggest trying or first.

Some of the other examples need other libraries to be installed - the ones that set up Keybow 2040 as a USB keyboard will need usb_hid installing for example. You should be able to find these libraries in the Adafruit bundle and you can install them by copying the relevant libraries to the lib folder just as before.

You can find more documentation on how to use the Keybow 2040 library to create your own custom layouts on Github.

Factory reset

If you really heck things up and want to start completely from scratch this special .uf2 file will delete all the files stored in Keybow 2040's flash memory. Once you've downloaded the file, hold down BOOTSEL whilst plugging in your USB-C cable to get into bootloader mode, then copy the uf2 to the RPI-RP2 and let it reboot. You'll need to follow the steps above to reinstall everything again afterwards.

Shopping basket

Need something for this project? You can use the links below to add products to your Pimoroni Shop basket for easy checkout.

Keybow 2040
Clicky keys £49.50
Keybow 2040
Linear (quiet) keys £49.50
Keybow 2040
Bare (no switches/keycaps) £35.40
USB-C to USB-A Cable - 1m Black
Want to checkout or change something? Click here to view your cart.


Hel Gibbons
Working her way through every job at Pimoroni, currently looking after content and curation. Likes rescuing stuff from skips, and starting revolutions. Pronouns: she/they