Overview

Save Subscribe
circuitpython_20191206_152537a.jpg
Image credit: keyhive.xyz

In this guide, you'll learn how to set up your Navi10 macropad to use KMK firmware. You'll use the Navi10, designed by /u/emdarcher, and the new Adafruit KB2040, to build a macropad that you'll put KMK firmware on and will also learn how to remap it and create your own configuration.

What is KMK?

KMK is a feature-rich and beginner-friendly firmware for computer keyboards written and configured in CircuitPython.

What is the Navi10?

Navi10 is a simple PCB kit meant to help people that miss their navigation cluster or just want a simple macropad.

The PCB comes with a built in diode bender and written instructions on how to build it.

Designed by /u/emdarcher

circuitpython_IMG_1916.jpg

Parts

Navi10 Kit

Navi10 is a simple PCB kit meant to help people that miss their navigation cluster or just want a simple macropad.

$15.00

Angled shot of short black microcontroller.
A wild Kee Boar appears! It’s a shiny KB2040! An Arduino Pro Micro-shaped board for Keebs with RP2040. (#keeblife 4 evah) A lot of folks like using Adafruit...
$8.95
In Stock
Add to Cart
USB Type A to Type C Cable - approx 1 meter / 3 ft long
As technology changes and adapts, so does Adafruit. This  USB Type A to Type C cable will help you with the transition to USB C, even if you're still...
$4.95
In Stock
Add to Cart

Installing CircuitPython

CircuitPython is a derivative of MicroPython designed to simplify experimentation and education on low-cost microcontrollers. It makes it easier than ever to get prototyping by requiring no upfront desktop software downloads. Simply copy and edit files on the CIRCUITPY drive to iterate.

CircuitPython Quickstart

Follow this step-by-step to quickly get CircuitPython running on your board.

Click the link above to download the latest CircuitPython UF2 file.

Save it wherever is convenient for you.

adafruit_products_KeeBoar_boot_reset.jpg

To enter the bootloader, hold down the BOOT/BOOTSEL button (highlighted in red above), and while continuing to hold it (don't let go!), press and release the reset button (highlighted in blue above). Continue to hold the BOOT/BOOTSEL button until the RPI-RP2 drive appears!

If the drive does not appear, release all the buttons, and then repeat the process above.

You can also start with your board unplugged from USB, press and hold the BOOTSEL button (highlighted in red above), continue to hold it while plugging it into USB, and wait for the drive to appear before releasing the button.

A lot of people end up using charge-only USB cables and it is very frustrating! Make sure you have a USB cable you know is good for data sync.

You will see a new disk drive appear called RPI-RP2.

 

Drag the adafruit_circuitpython_etc.uf2 file to RPI-RP2.

The RPI-RP2 drive will disappear and a new disk drive called CIRCUITPY will appear.

That's it, you're done! :)

Safe Mode

You want to edit your code.py or modify the files on your CIRCUITPY drive, but find that you can't. Perhaps your board has gotten into a state where CIRCUITPY is read-only. You may have turned off the CIRCUITPY drive altogether. Whatever the reason, safe mode can help.

Safe mode in CircuitPython does not run any user code on startup, and disables auto-reload. This means a few things. First, safe mode bypasses any code in boot.py (where you can set CIRCUITPY read-only or turn it off completely). Second, it does not run the code in code.py. And finally, it does not automatically soft-reload when data is written to the CIRCUITPY drive.

Therefore, whatever you may have done to put your board in a non-interactive state, safe mode gives you the opportunity to correct it without losing all of the data on the CIRCUITPY drive.

Entering Safe Mode

To enter safe mode when using CircuitPython, plug in your board or hit reset (highlighted in red above). Immediately after the board starts up or resets, it waits 1000ms. On some boards, the onboard status LED (highlighted in green above) will blink yellow during that time. If you press reset during that 1000ms, the board will start up in safe mode. It can be difficult to react to the yellow LED, so you may want to think of it simply as a slow double click of the reset button. (Remember, a fast double click of reset enters the bootloader.)

In Safe Mode

If you successfully enter safe mode on CircuitPython, the LED will intermittently blink yellow three times.

If you connect to the serial console, you'll find the following message.

Copy Text 
Auto-reload is off.
Running in safe mode! Not running saved code.

CircuitPython is in safe mode because you pressed the reset button during boot. Press again to exit safe mode.

Press any key to enter the REPL. Use CTRL-D to reload.

You can now edit the contents of the CIRCUITPY drive. Remember, your code will not run until you press the reset button, or unplug and plug in your board, to get out of safe mode.

Flash Resetting UF2

If your board ever gets into a really weird state and doesn't even show up as a disk drive when installing CircuitPython, try loading this 'nuke' UF2 which will do a 'deep clean' on your Flash Memory. You will lose all the files on the board, but at least you'll be able to revive it! After loading this UF2, follow the steps above to re-install CircuitPython.

Assembly

The bottom plate has most of the assembly instructions on it, but since this guide is using the KB2040, the instructions have been slightly edited.

circuitpython_IMG_1852.jpg

Modified assembly instructions:

Diode and Resistor Lead Bending Tool:

Center your component in the cutout rectangle and align leads with the notches. Then, whiile holding the component leads against the PCB, bend the lead ends into the notches to an angle of 90°.

BOM:
U0: [Adafruit KB2040]
J0, J1: 12 Pin Headers (usually come with Pro Micro)
D0-D9: Switching Diodes (ex. 1N4148)
D10: 3mm LED
R0: 1k Ohm Resistor
K0-K9: Cherry MX compatible or Alps Keyswitches
12x M2 screws
6x M2 spacers

Build Steps:

1. Solder the Diodes and Resistor:
- Use the Lead Bending Tool above to bend the leads
- Solder the Diodes with the marked side of the diode oriented with the markings on the silkscreen.

2. Solder the LED:
- Anode (positive) lead is usually longer than the Cathode (negative) lead.
- Positive side is marked with a '+' on bottom of the PCB, make sure to solder the Anode (positive) lead in that hole.

3. Solder the [KB2040] Headers:
- On bottom side of PCB, place headers in the correct rows (middle for Micro USB [or USB-C on KB2040], outer for Mini USB model)
- Hold these in place while flipping over the PCB, and place on a flat surface, keeping them as straight as possible while soldering. Placing the [KB2040] on them loosely can help with alignment.
- Solder the header pins to the pads on the top side of the PCB.

4. Solder the Switches:
- Place the Switches in their locations on the top of the PCB.
- Flip over the PCB and solder the Switch leads to the pads on the back of the PCB.
- After soldering, clip the leads on K1 and K4 shorter to prevent them from touching the Pro Micro.

5. Solder the [KB2040]:
- Place the [KB2040] on the headers, flipped with the chip-side facing the PCB and the USB port protruding slightly over the PCB edge.
- Solder the [KB2040] to the headers and then clip the ends of the headers short.

*Optional: Solder a Piezo Buzzer to the 'Buzzer' Pads for audio output

[6]. Connect top and bottom PCBs with the M2 Screws and Spacers.

This is a diode bender. I didn't realize this until after building it, so you definitely don't need to use it, but it makes things much easier. 

After you're done, it should look something like this. I used ALPS SKCM Orange switches, which don't have the same fixing posts as some MX-style switches do. My advice for getting them straight would be to solder them in then heat up one pin at a time and rotate or move the switch a little bit at a time until it's straight.

As far as keycaps go, I took the nav cluster off of my Apple Extended Keyboard II, but you can use anything you want so long as it fits on the switches.

Setting Up KMK

After having installed KMK on the previous page, you're going to want to click 'Download Project Bundle' on the file below. Unzip the file, copy kb.py to your CIRCUITPY drive and rename main.py to code.py and copy it to the CIRCUITPY drive as well.

Download Project Bundle
Copy Code 
# SPDX-FileCopyrightText: 2022 Eva Herrada for Adafruit Industries
# SPDX-License-Identifier: MIT

import board
import digitalio

from kmk.kmk_keyboard import KMKKeyboard as _KMKKeyboard
from kmk.matrix import DiodeOrientation


class KMKKeyboard(_KMKKeyboard):
    led = digitalio.DigitalInOut(board.D9)
    led.direction = digitalio.Direction.OUTPUT
    led.value = False
    row_pins = (board.D10, board.MOSI, board.MISO, board.D8)
    col_pins = (
        board.D4,
        board.D7,
        board.SCK,
    )
    diode_orientation = DiodeOrientation.COLUMNS
    i2c = board.I2C
View on GitHub

After you've copied everything over, your CIRCUITPY drive should look something like this.

circuitpython_Navi10.png

Key Mapping

There are 3 different keymaps available in the files. The default one is just the nav cluster, which is the four arrow keys and the 6 nav keys. There is also a keymap designed to give you a few keys to navigate i3 quicker (you'll probably have to edit this one since I use COLEMAK as well). The third keymap is for media control.

If you want to have a specific one be the main one, move it to the top of the keyboard.keymap list in code.py. For example, if I wanted to have the media keys be active, I would edit code.py to look like this:

circuitpython_Screenshot_2022-01-10_12-46-02.png

At this point, the keyboard should just work when you hit the keys. Feel free to mess around with the key maps. KMK has some good documentation on this process.

circuitpython_IMG_1918.jpg

This guide was first published on Jan 11, 2022. It was last updated on Jan 11, 2022.