Compiling/flashing TMK on my phone

PinePhone running Mobian

PinePhone Braveheart edition running Mobian. It's a little slower than compiling on a Raspberry Pi 3, otherwise the process is the same. The final community edition of the PinePhone is on pre-order.

PB-GHERKIN Raspberry Pi Pico KMK

KMK running on the RP2040

I used the same modified PB-Gherkin I used for testing the ESP32-S2 to test KMK on the new Raspberry Pi Pico. There is a Beta version of CircuitPython available. The brand new Pico will go into bootloader mode when first plugged in. Just copy the UF2 file to the RPI-RP2 drive that shows up.

There is a detailed guide to CircuitPython on the Raspberry Pi Pico on Adafruit.

There is one modification needed due to the deprecation of the pulseio.PWMout. Change pulseio to pwmio in these two locations in the led.py file 1 2. To do this you will need to download the current files instead of the release file (which is compiled and not editable). Unzip the file and copy the kmk folder and the boot.py file to the root of the CIRCUITPY drive. Then edit the led.py file in the kmk folder.

I used the same config file as for the ESP32-S2, only modifying the pin definitions.

I made a Gherkin PCB just for the Raspberry Pi Pico, the PiPi Gherkin.

PB-GHERKIN ESP32-S2 KMK

KMK running on the ESP32-S2

I soldered some pin headers on a PB-Gherkin so that I could connect it to a ESP32-S2 SAOLA-WROVER dev board. These boards are cheap at $8 from Amazon or Digikey. The only real downside is the physical size and the USB HID requires a separate USB pigtail. The micro USB connector on the board is only for serial, useful for the initial flashing of CircuitPython, but not much else.

I modified the config file for the PCA10059. I had to change the pin definitions for the new board. I also commented out the section that rearranges the switches, this PCB is not flipped upside-down.

PB-GHERKIN PCA10059 KMK

Gherkin running KMK on a PCA10059

It is possible to replace the Pro Micro on a PB-Gherkin with a PCA10059. The PCA10059 is running KMK firmware.

The PB-Gherkin PCB is flipped so that the "Pro Micro" would be mounted face up.

The PCA10059 is aligned with the bottom of the Pro Micro footprint, the two ground pins are skipped. The 6 column pins and 5 row pins match up with GPIO pins on the PCA10059.

There are pins that should not be soldered to the PCB (red X). They could cause shorts on those GPIO pins.

The green arrow points to the square pad, pin 1 on the Pro Micro footprint.

I had to use 14mm spacers to accommodate the thick USB extension plug. It is a tight fit, 15mm would be better.

KMK config

The KMK CircuitPython config file is here. It uses the unmodified KMK release files and only needs the Adafruit BLE library. I duplicated the original TMK Gherkin keymap as much as possible.

The PB-Gherkin PCB flipped the way it is (opposite of a normal Gherkin) rearranges the matrix. KMK has a method for rearrange the logical location of the switches with the physical positions.

It is also possible to enable BLE. The PCA10059 lacks any battery circuitry so this is only really useful for experimentation.

PCA10059 running KMK firmware

Cheap way to try out KMK firmware

The PCA10059 is a USB stick with the NRF52840 chip on it. Digikey and Mouser have them in stock for $10. It is very bare bones and is designed to be powered directly from the USB port and uses the built in voltage regulator to provide the 3.3v running voltage. To run KMK you must first install CircuitPython.

There is currently a bug in CircuitPython on the PCA10059 that causes file corruption. It is being worked on.

The process is fairly involved. If you have a Raspberry Pi you can do it without buying a dedicated programmer. I followed the very complete instructions on Rototron.info. The only difference is that I used an old Raspberry Pi 1 (first generation) instead of a Raspberry Pi 3 as in their example.

The only changes to the process are to the config file. I commented out the lines for Raspberry Pi 3 and uncommented the ones for Raspberry Pi 1. I also dropped the adapter_khz to 100. I don't know if this was necessary but it worked fine for me.

The connections were identical to the example. I soldered header pins to the PCA10059 and inserted it into a breadboard. I used a USB extension cable to connect it to the Pi.

I ran all the commands remotely through a SSH connection.

The Raspberry Pi 1 has a problem with resetting when a USB device is hot plugged. You should power it down before making connections.

Heed the warning about resetting the PCA10059 before attempting to flash the bootloader. If you don't flash the bootloader immediately after erasing it you may lose the connection to the Pi and will need to use a level shifter to regain access to program it.

The flash process takes about 30 seconds. It will sit seeming to do nothing for most of this time. Just wait.

After you have flashed the bootloader you will need to install the latest CircuitPython for the PCA10059. https://circuitpython.org/board/pca10059/

Then install the latest KMK release. https://cdn.kmkfw.io/kmk-latest.zip

Instructions here

KMK Setup

I wanted to use the built in SW1 (the white button on the top of the board) for a simple 1 key keyboard. The problem is that KMK is setup in the reverse of how most keyboard matrices are setup and it pulls the input high when pressed, instead of pulling low. The SW1 being connected to ground did not register.

I modified matrix.py to invert the logic. My modified matrix.py is here.

Line 83 pull up instead of down.

Line 104 set output False instead of True.

Line 118 add 'not' to invert reading of pin.

Line 144 set output True instead of False.

I made a very simple code.py keymap that has a single key output of the letter 'A'.

The col pins don't do anything, since SW1 is connected to ground. But they do make the RGB LED light up to show the matrix scanning. There is also a limitation that you can not define a single row or column, you need at least two. So I added a P1_10 as a second non existent row.

It also wants the Adafruit BLE library, even though it does not use BLE. You can find this in the latest library archive from here. Copy the entire 'adafruit_ble' folder to the lib folder on the PCA10059.

The PCA10059 has 15 GPIO pins along the edges and a few more on tiny pads on the bottom. 15 are enough for a small macropad or even a Gherkin. It lacks any battery circuitry so a wireless BLE keypad is not likely without additional circuitry.

Adafruit QT PY

Tiny MCU with the same footprint as the XIAO

The Adafruit QT PY is built off an ARM M0 core just like the XIAO. The pinout is compatible with the XIAO and most Arduino code will run without modification.

The main difference is that the QT PY has a built in RGB LED, a reset button, and a spot for a 2MB SPI flash chip. On the XIAO you have to short two tiny pads to reset it.

The optional SPI chip makes this a much more capable CircuitPython device. The 8 pin SOIC chip is available at Digikey GD25Q16CTIGR.

The QT PY is currently $6 from Adafruit or Digikey. It is listed as a "Limited Time" price.

The XIAO (left) has a metal can covering the components. The QT PY (right) has an additional connector for I2C devices.

The bottom of the QT PY is where the optional 2MB SPI flash chip is soldered. I soldered diodes legs to make them socketable.