kmk_firmware/docs/config_and_keymap.md

Configuring KMK

KMK is configured through a rather large plain-old-Python class called KeyboardConfig. Subclasses of this configuration exist which pre-fill defaults for various known keyboards (for example, many Keebio keyboards are supported through our ItsyBitsy to ProMicro pinout adapter). This class is the main interface between end users and the inner workings of KMK. Let's dive in!

• Edit or create a file called main.py on your CIRCUITPY drive. You can also keep this file on your computer (perhaps under user_keymaps - please feel free to submit a pull request with your layout definitions!) and copy it over (either manually or, if you're adept with developer tooling and/or a command line, our Makefile). It's definitely recommended to keep a backup of your configuration somewhere that isn't the microcontroller itself - MCUs die, CircuitPython may run into corruption bugs, or you might just have bad luck and delete the wrong file some day.

• Import the KeyboardConfig object for your keyboard from kmk.boards (or, if handwiring your keyboard, import KeyboardConfig from kmk.keyboard_config).

• Assign a KeyboardConfig instance to a variable (ex. keyboard = KeyboardConfig() - note the parentheses)

• Make sure this KeyboardConfig instance is actually run at the end of the file with a block such as the following:

if __name__ == '__main__':
    keyboard.go()

• Assign pins and your diode orientation (only necessary on handwire keyboards), for example:

from kmk.matrix import DiodeOrientation

col_pins = (P.SCK, P.MOSI, P.MISO, P.RX, P.TX, P.D4)
row_pins = (P.D10, P.D11, P.D12, P.D13, P.D9, P.D6, P.D5, P.SCL)
rollover_cols_every_rows = 4
diode_orientation = DiodeOrientation.COLUMNS

The pins should be based on whatever CircuitPython calls pins on your particular board. You can find these in the REPL on your CircuitPython device:

import board
print(dir(board))

Note: rollover_cols_every_rows is only supported with DiodeOrientation.COLUMNS, not DiodeOrientation.ROWS. It is used for boards such as the Planck Rev6 which reuse column pins to simulate a 4x12 matrix in the form of an 8x6 matrix

• Import the global list of key definitions with from kmk.keys import KC. You can either print this out in the REPL as we did with board above, or simply look at our Key documentation. We've tried to keep that listing reasonably up to date, but if it feels like something is missing, you may need to read through kmk/keys.py (and then open a ticket to tell us our docs are out of date, or open a PR and fix the docs yourself!)

• Define a keymap, which is, in Python terms, a List of Lists of Key objects. A very simple keymap, for a keyboard with just two physical keys on a single layer, may look like this:

keyboard.keymap = [[KC.A, KC.B]]

You can further define a bunch of other stuff:

• debug_enabled which will spew a ton of debugging information to the serial console. This is very rarely needed, but can provide very valuable information if you need to open an issue.

• unicode_mode from kmk.consts.UnicodeMode, which defines the default operating system implementation to use for unicode sequences (see examples below, or unicode.md. This can be changed after boot with a key (see keycodes.md)

• tap_time which defines how long KC.TT and KC.LT will wait before considering a key "held" (see keycodes.md)

• leader_dictionary, which defines leader sequences (see leader.md), defined as tuples of keycode objects (or you can use kmk.keycodes.generate_leader_dictionary_seq with a string)

We also support unicode sequences (emojis, emoticons, umlauted letters, whatever) if your operating system and system setup do! See unicode.md for details.

Here's a giant example of all the above. This is my personal 4x12 matrix layout running on a Planck Rev6 PCB, with a Feather M4 Express wired up to the outer matrix pins (in somewhat of a "spider" setup), utilizing most of the above features - it's one of the "kitchen sink tester" definitions we use on the KMK Core team.