KMK CircutPython Keyboard

Pog is an open source project that makes it easy to configure KMK (a user-friendly, feature-rich firmware for custom mechanical keyboards, built on CircuitPython) with a GUI key map editor with no code. The layout editor lets you create custom layouts and makes multi layers easy to set up.

Cute yet capable

With 48 keys in total, you can easily add multiple layers to expand your keycodes. The Pog software lets you create custom macros, strings, and even media/mouse controls. The Pog software also supports NeoPixel LEDs for basic keyboard backlighting.

This guide covers how to build and assemble the 4x12 keyboard using two NeoKey 5x6 ortho snap-apart PCBs and how to use the POG software to set up and configure the key mapping.

3D Printed Parts

Individual 3MF files for 3D printing are oriented and ready to print on FDM machines using PLA filament. Original design source may be downloaded using the links below.

CAD Assembly

The main assembly is available in Autodesk Fusion and STEP file formats. This includes all of the 3D printed parts and electronic components used in the project. Use the main assembly to create any edits, updates, or modifications. 

Build Volume

The parts require a 3D printer with a minimum build volume of 244 (X) x 92mm (Y) x 15mm (Z).

Design Source Files

The project assembly was designed in Fusion 360. Once opened in Fusion 360, It can be exported in different formats like STEP, STL and more.

Electronic components like Adafruit's boards, displays, connectors and more can be downloaded from the Adafruit CAD parts GitHub Repo.

Ortho Snap-Part PCB Prep

Start by removing the top and bottom railing bits from both sheets. Use some pliers to gently bend at the perforation until the extra material snaps off.

Remove the 5th row from the two sheets using pliers to create two sets of 4x6 PCBs that look like the image below in the wiring section. (That's 4 rows, 6 columns).

Clean the edges from the top and bottom of the PCB using sandpaper or a metal file.

Wire PCBs

Start by wiring up the two 4x6 PCBs together. Use short wires, about 1 inch (25mm), connect the ROW, VIN, Ground(GND) and NeoPixel data OUT/IN pins.

Wiring The KB2040

Place the KB2040 microcontroller in the center above two 4x6 PCBs. Create wires with appropriate lengths for VIN and GND pins from right side PCB to the KB2040. Solder the wires to the pins. Then, solder the VIN wire to the RAW pin and GND to GND.

Create a wire with an appropriate length for the first NeoPixel LED (the top right) to connect to the MOSI pin on the KB2040. Solder the wire from the NeoPixel Data In pin to the MOSI pin on the KB2040.

Create four wires, with varying lengths, to connect the rows to the accompanying pins on the KB2040. Solder the wires, going from top to bottom, to the D6, D7, D8 and D9 pins respectively.

Create 6 wires, with varying length, to connect the columns on the right-half PCB to the accompanying pins on the KB2040. Solder the wires, going from left to right, A3, A2, A1, A0, CLK, and MISO pins.

Create 6 more wires, in varying lengths, to connect the columns on the left-half PCB to the accompanying pins on the KB2040. Solder the wires, going from left to right, TX, RX, D2, D3, D4, and D5 pins.

Install KB2040 Holder

Orient the KB2040 with the 3D printed holder. Then, insert the board at an angle so the edge of the PCB fits under the corner clips.

Slightly flex the holder to allow the other side of the PCB to fit under the clips.

Install NeoKey Mount

Orient the NeoKey PCBs with the 3D printed mount. Slide the mount in between the KB2040 mount and the NeoKey PCBs.

Line up the KB2040 holder mounting holes with the accompanying holes on the NeoKey mount.

Insert and fasten 2x M3 x 4mm long machine screws to secure the KB2040 holder to the NeoKey mount.

Installing NeoKey PCBs

Flip the assembly over and position the two NeoKey PCBs so the mounting holes are lined up with the various mounting points on the 3D printed mount.

Ensure various wires are positioned away from any of the mounting holes.

Fasten & Secure NeoKey PCBs

While holding the NeoKey PCBs in place, insert and fasten the M3 x 6mm machine screws.

Reference the assembly photo to cross check where the 10x M3 screws are needed to be fastened.

Check Wiring

Flip the assembly over and double check the wires are not being obstructed and clear from any pinching or kinking.

Install Bottom

Orient the bottom half of the case with the NeoKey PCB assembly.

Insert the NeoKey PCB assembly into the bottom half of the case with the mounting holes lined up.

Secure PCB Mount to Bottom

Insert and fasten M3x8mm long machine screws to secure the NeoKey PCB mount to the bottom half of the enclosure.

Installing Switches to Key Plate

Get the 3D printed key plate and 48x mechanical key switches ready to install. Orient the key plate with the NeoKey PCB (the center tab faces away from KB2040's USB port).

Start by inserting switches on each corner of the key plate by snapping them into the plate. Make sure they're in the correct orientation (LED slots facing down).

Then, insert four more switches spaced apart like in the assembly photo.

Install Key Plate to NeoKey PCBs

Orient the key plate with the NeoKey PCBs and place it over the PCB.

Gently press down the various switches, ensuring the pins are fitting neatly into their respected sockets. 

Proceed with the switch installation by snapping switches into place, one by one, ensuring the pins are seating correctly into the key sockets.

Install Key Caps

Gather up your desired key caps to get ready to install them onto the mechanical key switches.

Pull up your key map to reference the placement of the key caps.

Firmly press the key caps onto the stems of the key switches to install them.

Installed Key Caps

Take a moment to review each key switch, making sure they match your key mapping.

If you find a key is misplaced, use a key puller to remove the key cap.

Install Top

Orient the top cover with bottom half of the case so the snap fit nubs match.

Firmly press the two parts together to snap fit them closed.

USB, Reset & Boot

Connect your keyboard to your computer using a data and power USB-C cable.

The bottom of the enclosure features button tabs for accessing the boot and reset buttons on the KB2040. The square shaped button is BOOT while the circular one is the RESET button.

Download POG V2.2.0

Click the link below to open the POG github repo in your web browser.

Locate the desktop application appropriate for your computers operating system and download the asset.

Setup New Keyboard

Click New Keyboard button to start the setup process.

Select your CIRCUITPY drive

Click on CIRCUITPY and click continue.

On the setup method page, click on the USB serial port button and then click on Manual Setup.

Initial Keyboard Setup

On the next page, click INSTALL KMK and wait for the KMK checkmark to appear. In the background, POG will automatically download the latest version of KMK to your CIRCUITPY drive.

Click NEXT when KMK is finished installing.

Name Your Keyboard

On this page, you will enter the name and any additional meta data you want to associate to your keyboard.

Click NEXT when you're ready to proceed.

Matrix Setup

On the Matrix page, choose normal for keyboard type, matrix for matrix method and enter 12 for matrix width, and 4 for matrix height. Scroll down to see a visual preview of your keyboard layout.

Click NEXT when ready.

Pin Setup

On the pins page, select board for Pin Prefix. Select ROW2COL under the Diode Direction. Then, enter the following pins for the rows and columns.

Row Pins (4)

• D6
• D7
• D8
• D9

Column Pins (12)

• A3
• A2
• A1
• A0
• SCK
• MISO
• D0
• D1
• D2
• D3
• D4
• D5

Double check all of the pins are correctly entered. Click NEXT when ready.

Coordmap Setup

On the Coordmap setup page, click on the FLASH COORDMAP FINDER TO KEYBOARD button.

Then, click on the text area and follow the guide instructions on the page.

Click NEXT when ready.

Finish Initial Setup

Review your keyboard layout making sure the key numbers look correct.

Click FINISH SETUP when ready.

Mapping Keys

After the initial setup is complete, you can start mapping keys to your keyboard.

In the keymap section, you'll see a visualization of your keyboard layout. Click on a key in the layout to highlight it, then you can click on a keycode in the QWERTY section to map it.

Click the gear icon to reveal settings for Auto-select next key.

For media control keycodes, select App/Media/Mouse in the lower menu to show additional keycodes.

Adding Layers

You can add an extra layer to your keymap by clicking on the ADD LAYER button in the upper menu.

Click on the gear icon next to the newly added layer to add name and optionally assign a color. 

Click on the "0" layer and choose a key to toggle the second layer using the MO(1) keycode under Layers in the lower menu. This will allow you to hold down that selected key and press the corresponding key. For example. If press and hold down on the lowest far left key and then press Q, it will type out a 1.

Adding RGB Backlighting

You can turn on the NeoPixel LEDs on your keyboard.

In the side menu, click on RGB to and check Enable RGB. Then, enter board.MOSI in the RGB Pin section. Enter 48 in the Number of LEDs.

Choose your desired mode under the Animation Mode. Then, choose your preferred color by clicking on the colored box to open a color picker.

You have the option to toggle the LEDs on/off and adjust the hue using keys by choosing from the RGB menu under the Keymap page.