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
A data capable USB-C cable
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.
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:
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.
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.
Unzip the file, and copy
keybow2040.py into the
lib folder on CIRCUITPY. The contents of the
lib folder on your CIRCUITPY drive should now look something like this:
Running the examples
To run one of the examples, all you need to do is rename it to
code.py and copy it to CIRCUITPY - CircuitPython will automatically detect changes and start running the code. We'd suggest trying
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.
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.
Search above to find more great tutorials and guides.