All the code.
If you are using a premade pcb with a .json file provided such as a dz60 etc. Please load that .json file into kbfirmware.com and skip to the Keymap and Macro tips and tricks.
Basics of creating your matrix:
One of the easiest ways to do this is to simply import your KLE raw data into kbfirmware.com and have the matrix generated for you. This generally works well enough, but can sometimes be improved upon as it does not always use the smallest number of pins. My preferred method of creating my matrix is to take a screenshot of my KLE layout and simply draw the rows and columns in over the screenshot. I like doing this because I generally save a column or two compared to kbfirmware.com, and can also make some adjustments to make hand wiring easier.
Default wiring diagram for 60% layout from Keyboard-layout-editor.com via the Kbfirmware.com algorithm
Example of wiring diagram made for “easier” hand wiring and saves 1 pin
What pins are and why they are important:
Pins in this context are the number of usable digital I/O outputs on the controllers. Pins are important because they dictate the number of rows and columns you can have in a layout. For every row and column one pin needs to be used per each. So in the examples above 19 (5 rows, 14 columns) and 20 (5 rows, 15 columns) pins are used respectively. The two most popular controller options for handwire and basic custom pcbs are the pro micro and the teensy 2.0 which have 18, and 25 usable pins respectively. What this all boils down to is that having 18 or less pins saves you money, and having 26 or more pins means that you will need to either user some rather involved wiring shenanigans to reduce your pin use, or jump up in price again to the teensy ++ which has 46 usable pins, but is more expensive and not used very much.
Editing your wiring diagrams:
This is pretty straight forward on kbfirmware.com. You simply have to select the key and use the + and - buttons to change the rows or columns. The diode direction should always be “Column to Row” if you are using most pcbs or following all hand-wiring guides I have read (I use a mix of techniques in the “A Modern Handwiring Guide” and “BrownFox step by step”).
If you are using a promicro or teensy controller the ATmega32U4 will be correct setting, if you are using a different controller this might change, but most common ones used by keyboards use the ATmega32U4. For handwire builds I prefer to connect my rows and columns to the controller in a way that makes the length of wire the shortest/most direct. This part of the process is very important to document. After I connect the wires to the controller and document it, you just have to go through and use the drop down menu to change the rows and columns to their proper pin.
Pro Micro pinout
Keymap tips and tricks:
Creating a basic keymap is pretty straight forward when using kbfirmware.com, just select the layer (0 is the default/base layer) and then select the key you want to change and then you can click through the various options to find what you are looking for. If you are wondering what some of these weird looking codes are here: https://docs.qmk.fm/keycodes.html is pretty much all of them available on kbfirmware.com and some more that can be used to do some pretty advanced things.
Layers for QMK can be somewhat tricky to understand, but the basics are fairly simple and I find that the resource here: https://docs.qmk.fm/feature_advanced_keycodes.html#switching-and-toggling-layers helps most people be able to do what they are looking to do.
Macro tips and tricks:
The website makes it pretty dang easy to make your own macros and have them put on your board. You can add steps yourself or use the record function which is nice for making macros that type things such as “Omae wa mou shindeiru”. If your macro is a bit more complex or runs into issues with the record function you can use the add action button to step by step make your macro. A simple macro to lock your computer (GUI key + L) is shown below.
And after you have made your first macro, make sure to change the macro you are modifying with the arrows above.
When you are adding macros to your keymap, you go to the “FN” tab and select the M() option and it will have you select which macro you want to be bound to that button. BAM you made some simple macros.
Guide written by /u/friglesnart or friglesnart#1931
Feel free to contact me with any questions, comments, or suggestions. Thank you!
A short guide by PyroL. Free yourself from those prebaked, out-of-date and several-hundred-commits-behind tools!
All info available at https://docs.qmk.fm/
Using your favorite command-line, clone the main repo by running:
git clone https://github.com/qmk/qmk_firmware.git
If you have a fork, clone the main repo anyways, then run:
git remote add upstream [your repo link], and then you can push to your own repo and pull from origin, aka the main repo.
In QMK, a keyboard's firmware is broken up into a few important files:
- config.h defines physical and electrical properties about the board: what it's recognized as on the computer, what microcontroller pins are connected to which rows and columns, and a bit of other QMK magic can go on in this file.
- [keyboard name].h defines the physical layout of the keyboard, so that the keymap arrays can send the right keycodes to the right key events.
- You mostly don't need to touch rules.mk or [keyboard name].c
- keymaps/[keymap name]/keymap.c is where most of the editing will happen.
/* Example: Clueboard default base layer */ [_BL] = LAYOUT( F(0), KC_1, KC_2, KC_3, KC_4, KC_5, KC_6, KC_7, KC_8, KC_9, KC_0, KC_MINS, KC_EQL, KC_GRV, KC_BSPC, KC_PGUP, \ KC_TAB, KC_Q, KC_W, KC_E, KC_R, KC_T, KC_Y, KC_U, KC_I, KC_O, KC_P, KC_LBRC, KC_RBRC, KC_BSLS, KC_PGDN, \ KC_CAPS, KC_A, KC_S, KC_D, KC_F, KC_G, KC_H, KC_J, KC_K, KC_L, KC_SCLN, KC_QUOT, KC_NUHS, KC_ENT, \ KC_LSFT, KC_NUBS, KC_Z, KC_X, KC_C, KC_V, KC_B, KC_N, KC_M, KC_COMM, KC_DOT, KC_SLSH, KC_RO, KC_RSFT, KC_UP, \ KC_LCTL, KC_LGUI, KC_LALT, KC_MHEN, KC_SPC,KC_SPC, KC_HENK, KC_RALT, KC_RCTL, MO(_FL), KC_LEFT, KC_DOWN, KC_RGHT),
QMK layouts are just C arrays QMK compares to the header file that define physical properties of the board to determine what gets sent to the computer when certain key events are detected. Most keycodes are baked in to QMK, and a full list is available at https://docs.qmk.fm/#/keycodes. There are lots of exotic and surprisingly flexible and powerful keycodes that you may find useful, so I encourage you to read up!
To make the data easier to parse, most keymap files have a line break for every row on the keyboard, so you can easily edit a specific key on your keyboard without having to count it out. From there, just change the keycode to whatever you want it to be. For example, if I wanted to make Caps Lock my control key on the above layer, I would change
KC_CAPS on the 3rd row from the top to
KC_LCTRL, then reflash.