-
-
-
-
## Parts list
You will need: (where *x* is the number of keys on your planned keyboard)
@@ -141,29 +32,29 @@ Start by installing the switches and stabilisers in the plate. Depending on the
If you are following a pre-existing handwire guide (e.g. for the keyboards in the [handwire firmware section](https://github.com/qmk/qmk_firmware/tree/master/keyboards/handwired) you can skip this step, just ensure you wire the matrix as described.
-What you want to achieve is one leg from each switch being attached to the corresponding switches next to it (rows) and the other leg being attached to the switches above and below it (columns) and a diode to one of the legs, mosy commonly this will be the leg attached to the rows, and the diode will face away from it (Column to Row) i.e. with the wire furthest from the black line on the diode connected to the switch (as current will only travel in one direction through a diode)
+What you want to achieve is one leg from each switch being attached to the corresponding switches next to it (rows) and the other leg being attached to the switches above and below it (columns) and a diode to one of the legs, mosy commonly this will be the leg attached to the rows, and the diode will face away from it (Column to Row) i.e. with the wire furthest from the black line on the diode connected to the switch (as current will only travel in one direction through a diode).
It is fairly simple to plan for an ortholinear keyboard (like a Planck).
-
+
Image from [RoastPotatoes' "How to hand wire a Planck"](https://blog.roastpotatoes.co/guide/2015/11/04/how-to-handwire-a-planck/)
But the larger and more complicated your keyboard, the more complex the matrix. [Keyboard Firmware Builder](https://kbfirmware.com/) can help you plan your matrix layout (shown here with a basic fullsize ISO keyboard imported from [Keyboard Layout Editor](http://www.keyboard-layout-editor.com).
- Bear in mind that the number of rows plus the number of columns can not exceed the number of I/O pins on your controller. So the fullsize matrix shown above would be possible on a Proton C or Teensy++, but not on a regular Teensy or Pro Micro
+Bear in mind that the number of rows plus the number of columns can not exceed the number of I/O pins on your controller. So the fullsize matrix shown above would be possible on a Proton C or Teensy++, but not on a regular Teensy or Pro Micro.
-#### Common Microcontroller Boards
+### Common Microcontroller Boards
| Board | Controller | # I/O | Pinout |
| :------------ |:-------------:| ------:| ------ |
-| Pro Micro* | ATmega32u4 | 20 | [link](https://learn.sparkfun.com/tutorials/pro-micro--fio-v3-hookup-guide/hardware-overview-pro-micro#Teensy++_2.0) |
+| Pro Micro* | ATmega32u4 | 20 | [link](https://learn.sparkfun.com/tutorials/pro-micro--fio-v3-hookup-guide/hardware-overview-pro-micro#Teensy++_2.0) |
| Teensy 2.0 | ATmega32u4 | 25 | [link](https://www.pjrc.com/teensy/pinout.html) |
| [QMK Proton C](https://qmk.fm/proton-c/) | STM32F303xC | 36 | [link 1](https://i.imgur.com/RhtrAlc.png), [2](https://deskthority.net/wiki/QMK_Proton_C) |
| Teensy++ 2.0 | AT90USB1286 | 46 | [link](https://www.pjrc.com/teensy/pinout.html#Teensy_2.0) |
-*Elite C is essentially the same as a pro micro with a USB-C instead of Micro-USB
+*Elite C is essentially the same as a Pro Micro with a USB-C instead of Micro-USB
There are also a number of boards designed specifically for handwiring that mount directly to a small number of switches and offer pinouts for the rest. Though these are generally more expensive and may be more difficult to get hold of.
@@ -204,7 +95,7 @@ If you are planning a split keyboard (e.g. Dactyl) each half will require a cont
There are a lot of soldering guides and tips available elsewhere but here are some of the most useful and relevant for hand wiring:
-To ensure a strong solder joint you want a good amount of contact between the solder and the 2 peices of metal you are connecting, a good way of doing this (though not required) is looping around pins or twisting wires together before applying solder.
+To ensure a strong solder joint you want a good amount of contact between the solder and the two pieces of metal you are connecting. A good way of doing this (though not required) is looping around pins or twisting wires together before applying solder.
Click for details
- -Without a matrix circuit each switch would require its own wire directly to the controller. - -Simply put, when the circuit is arranged in rows and columns, if a key is pressed, a column wire makes contact with a row wire and completes a circuit. The keyboard controller detects this closed circuit and registers it as a key press. - -The microcontroller will be setup up via the firmware to send a logical 1 to the columns, one at a time, and read from the rows, all at once - this process is called matrix scanning. The matrix is a bunch of open switches that, by default, don't allow any current to pass through - the firmware will read this as no keys being pressed. As soon as you press one key down, the logical 1 that was coming from the column the keyswitch is attached to gets passed through the switch and to the corresponding row - check out the following 2x2 example: - - Column 0 being scanned Column 1 being scanned - x x - col0 col1 col0 col1 - | | | | - row0 ---(key0)---(key1) row0 ---(key0)---(key1) - | | | | - row1 ---(key2)---(key3) row1 ---(key2)---(key3) - -The `x` represents that the column/row associated has a value of 1, or is HIGH. Here, we see that no keys are being pressed, so no rows get an `x`. For one keyswitch, keep in mind that one side of the contacts is connected to its row, and the other, its column. - -When we press `key0`, `col0` gets connected to `row0`, so the values that the firmware receives for that row is `0b01` (the `0b` here means that this is a bit value, meaning all of the following digits are bits - 0 or 1 - and represent the keys in that column). We'll use this notation to show when a keyswitch has been pressed, to show that the column and row are being connected: - - Column 0 being scanned Column 1 being scanned - x x - col0 col1 col0 col1 - | | | | - x row0 ---(-+-0)---(key1) row0 ---(-+-0)---(key1) - | | | | - row1 ---(key2)---(key3) row1 ---(key2)---(key3) - -We can now see that `row0` has an `x`, so has the value of 1. As a whole, the data the firmware receives when `key0` is pressed is - - col0: 0b01 - col1: 0b00 - │└row0 - └row1 - -A problem arises when you start pressing more than one key at a time. Looking at our matrix again, it should become pretty obvious: - - Column 0 being scanned Column 1 being scanned - x x - col0 col1 col0 col1 - | | | | - x row0 ---(-+-0)---(-+-1) x row0 ---(-+-0)---(-+-1) - | | | | - x row1 ---(key2)---(-+-3) x row1 ---(key2)---(-+-3) - - Remember that this ^ is still connected to row1 - -The data we get from that is: - - col0: 0b11 - col1: 0b11 - │└row0 - └row1 - -Which isn't accurate, since we only have 3 keys pressed down, not all 4. This behavior is called ghosting, and only happens in odd scenarios like this, but can be much more common on a bigger keyboard. The way we can get around this is by placing a diode after the keyswitch, but before it connects to its row. A diode only allows current to pass through one way, which will protect our other columns/rows from being activated in the previous example. We'll represent a dioded matrix like this; - - Column 0 being scanned Column 1 being scanned - x x - col0 col1 col0 col1 - │ │ | │ - (key0) (key1) (key0) (key1) - ! │ ! │ ! | ! │ - row0 ─────┴────────┘ │ row0 ─────┴────────┘ │ - │ │ | │ - (key2) (key3) (key2) (key3) - ! ! ! ! - row1 ─────┴────────┘ row1 ─────┴────────┘ - -In practical applications, the black line of the diode will be placed facing the row, and away from the keyswitch - the `!` in this case is the diode, where the gap represents the black line. A good way to remember this is to think of this symbol: `>|` - -Now when we press the three keys, invoking what would be a ghosting scenario: - - Column 0 being scanned Column 1 being scanned - x x - col0 col1 col0 col1 - │ │ │ │ - (┌─┤0) (┌─┤1) (┌─┤0) (┌─┤1) - ! │ ! │ ! │ ! │ - x row0 ─────┴────────┘ │ x row0 ─────┴────────┘ │ - │ │ │ │ - (key2) (┌─┘3) (key2) (┌─┘3) - ! ! ! ! - row1 ─────┴────────┘ x row1 ─────┴────────┘ - -Things act as they should! Which will get us the following data: - - col0: 0b01 - col1: 0b11 - │└row0 - └row1 - -The firmware can then use this correct data to detect what it should do, and eventually, what signals it needs to send to the OS. - -Further reading: -- [Wikipedia article](https://en.wikipedia.org/wiki/Keyboard_matrix_circuit) -- [Deskthority article](https://deskthority.net/wiki/Keyboard_matrix) -- [Keyboard Matrix Help by Dave Dribin (2000)](https://www.dribin.org/dave/keyboard/one_html/) -- [How Key Matrices Works by PCBheaven](http://pcbheaven.com/wikipages/How_Key_Matrices_Works/) (animated examples) -- [How keyboards work - QMK documentation](how_keyboards_work.md) - -
@@ -220,24 +111,11 @@ When you come to apply the solder, hold the soldering iron against the two surfa
Don't hold the iron on the solder/joint longer than necessary. Heat will be conducted through the surfaces and can damage components (melt switch housings etc.). Also, solder contains flux, which aids in ["wetting"](https://en.m.wikipedia.org/wiki/Wetting). The longer heat is applied to the solder the more flux will evaporate meaning you may end up with a bad solder joint with peaks which, apart from looking bad, may also increase the risk of electrical shorts.
-The following collapsible section describes in detail how to solder rows using the bent diode technique and columns using short lengths of wire.
-
-
-
-
-
-# Wiring up the controller
+## Wiring up the controller
Now that the matrix itself is complete, it's time to connect what you've done to the microcontroller board.
@@ -280,15 +149,16 @@ Place the microcontroller where you want it to be located, give thought to mount
Find the pinout/documentation for your microcontroller board ([links here](#common-microcontroller-boards)) and make a note of all the digital I/O pins on it (note that on some controllers, like the teensy, analogue I/O can double as digital) as these are the pins you want to connect your wires to.
-Click for details
+#### Soldering the Diodes -## Soldering the Diodes +Starting at the top-left switch, place the diode (with tweezers if you have them) on the switch so that the diode itself is vertically aligned, and the black line is facing toward you. The input lead of the diode should be touching the left contact on the switch, and the bent, output end should be facing to the right and resting on the switch there, like this: -Starting at the top-left switch, place the diode (with tweezers if you have them) on the switch so that the diode itself is vertically aligned, and the black line is facing toward you. The straight end of the diode should be touching the left contact on the switch, and the bent end should be facing to the right and resting on the switch there, like this: - -``` - │o - ┌┴┐ o - │ │ O - ├─┤ - └┬┘ - └───────────── -``` + Letting the diode rest, grab your solder, and touch both it and the soldering iron to the left contact at the same time - the rosin in the solder should make it easy for the solder to flow over both the diode and the keyswitch contact. The diode may move a little, and if it does, carefully position it back it place by grabbing the bent end of the diode - the other end will become hot very quickly. If you find that it's moving too much, using needle-nose pliers of some sort may help to keep the diode still when soldering. @@ -247,20 +125,13 @@ After soldering things in place, it may be helpful to blow on the joint to push When the first diode is complete, the next one will need to be soldered to both the keyswitch, and the previous diode at the new elbow. That will look something like this: -``` - │o │o - ┌┴┐ o ┌┴┐ o - │ │ O │ │ O - ├─┤ ├─┤ - └┬┘ └┬┘ - └────────────────┴───────────── -``` + After completing a row, use the wire cutters to trim the excess wire from the tops of the diodes, and from the right side on the final switch. This process will need to completed for each row you have. When all of the diodes are completely soldered, it's a good idea to quickly inspect each one to ensure that your solder joints are solid and sturdy - repairing things after this is possible, but more difficult. -## Soldering the Columns +#### Soldering the Columns You'll have some options in the next process - it's a good idea to insulate the column wires (since the diodes aren't), but if you're careful enough, you can use exposed wires for the columns - it's not recommended, though. If you're using single-cored wire, stripping the plastic off of the whole wire and feeding it back on is probably the best option, but can be difficult depending on the size and materials. You'll want to leave parts of the wire exposed where you're going to be solder it onto the keyswitch. @@ -270,9 +141,7 @@ Before beginning to solder, it helps to have your wire pre-bent (if using single If you're not using any insulation, you can try to keep the column wires elevated, and solder them near the tips of the keyswitch contacts - if the wires are sturdy enough, they won't short out to the row wiring an diodes. -
+----
-
+----
+
Cut wires to the length of the distance from the a point on each column/row to the controller. You can solder anywhere along the row, as long as it's after the diode - soldering before the diode (on the keyswitch side) will cause that row not to work.
@@ -301,150 +171,32 @@ As you solder the wires to the controller make a note of which row/column is goi
As you move along, be sure that the controller is staying in place - recutting and soldering the wires is a pain!
-
-# Getting Some Basic Firmware Set Up
+## Getting Some Basic Firmware Set Up
From here, you should have a working keyboard once you program a firmware.
Simple firmware can be created easily using the [Keyboard Firmware Builder](https://kbfirmware.com/) website. Recreate your layout using [Keyboard Layout Editor](http://www.keyboard-layout-editor.com), import it and recreate the matrix (if not already done as part of [planning the matrix](#planning-the-matrix).
-Go through the rest of the tabs, assigning keys until you get to the last one where you can compile and download your firmware. The .hex file can be flashed straight onto your keyboard, and the .zip of source files can be modified for advanced functionality and compiled locally using the method described in the collapsable section below, or using the more comprehensive [getting started guide.](newbs_getting_started)
+Go through the rest of the tabs, assigning keys until you get to the last one where you can compile and download your firmware. The .hex file can be flashed straight onto your keyboard, and the .zip of source files can be modified for advanced functionality and compiled locally using the method described in [Building Your First Firmware](newbs_building_firmware?id=build-your-firmware).
+The source given by Keyboard Firmware Builder is QMK, but is based on a version of QMK from early 2017. To compile the code from your .zip file in a modern version of QMK Firmware, you'll need to open the .zip and follow these instructions:
-Specific instructions for the Teensy 2.0
+### Specific instructions for the Teensy 2.0 - There are some pins on the Teensy that are special, like D6 (the LED on the chip), or some of the UART, SPI, I2C, or PWM channels, but only avoid those if you're planning something in addition to a keyboard. If you're unsure about wanting to add something later, you should have enough pins in total to avoid a couple. +There are some pins on the Teensy that are special, like D6 (the LED on the chip), or some of the UART, SPI, I2C, or PWM channels, but only avoid those if you're planning something in addition to a keyboard. If you're unsure about wanting to add something later, you should have enough pins in total to avoid a couple. The pins you'll absolutely have to avoid, as with any controller, are: GND, VCC, AREF, and RST - all the others are usable and accessible in the firmware. -
-
-/` folder by typing, like the print-out from the script specifies:
-
-```
-cd keyboards/
-```
-
-### `config.h`
-
-The first thing you're going to want to modify is the `config.h` file. Find `MATRIX_ROWS` and `MATRIX_COLS` and change their definitions to match the dimensions of your keyboard's matrix.
-
-Farther down are `MATRIX_ROW_PINS` and `MATRIX_COL_PINS`. Change their definitions to match how you wired up your matrix (looking from the top of the keyboard, the rows run top-to-bottom and the columns run left-to-right). Likewise, change the definition of `UNUSED_PINS` to match the pins you did not use (this will save power).
-
-### `.h`
-
-The next file you'll want to look at is `.h`. You're going to want to rewrite the `LAYOUT` definition - the format and syntax here is extremely important, so pay attention to how things are setup. The first half of the definition are considered the arguments - this is the format that you'll be following in your keymap later on, so you'll want to have as many k*xy* variables here as you do keys. The second half is the part that the firmware actually looks at, and will contain gaps depending on how you wired your matrix.
-
-We'll dive into how this will work with the following example. Say we have a keyboard like this:
-
-```
- ┌───┬───┬───┐
- │ │ │ │
- ├───┴─┬─┴───┤
- │ │ │
- └─────┴─────┘
-```
-
-This can be described by saying the top row is 3 1u keys, and the bottom row is 2 1.5u keys. The difference between the two rows is important, because the bottom row has an unused column spot (3 v 2). Let's say that this is how we wired the columns:
-
-```
- ┌───┬───┬───┐
- │ ┋ │ ┋ │ ┋ │
- ├─┋─┴─┬─┴─┋─┤
- │ ┋ │ ┋ │
- └─────┴─────┘
-```
-
-The middle column is unused on the bottom row in this example. Our `LAYOUT` definition would look like this:
-
-```
- #define LAYOUT( \
- k00, k01, k02, \
- k10, k11, \
- ) \
- { \
- { k00, k01, k02 }, \
- { k10, KC_NO, k11 }, \
- }
-```
-
-Notice how the top half is spaced to resemble our physical layout - this helps us understand which keys are associated with which columns. The bottom half uses the keycode `KC_NO` where there is no keyswitch wired in. It's easiest to keep the bottom half aligned in a grid to help us make sense of how the firmware actually sees the wiring.
-
-Let's say that instead, we wired our keyboard like this (a fair thing to do):
-
-```
- ┌───┬───┬───┐
- │ ┋ │ ┋│ ┋ │
- ├─┋─┴─┬┋┴───┤
- │ ┋ │┋ │
- └─────┴─────┘
-```
-
-This would require our `LAYOUT` definition to look like this:
-
-```
- #define LAYOUT( \
- k00, k01, k02, \
- k10, k11, \
- ) \
- { \
- { k00, k01, k02 }, \
- { k10, k11, KC_NO }, \
+1. Extract the `kb` folder to `qmk_firmware/keyboards/handwired/`.
+2. Open the extracted `kb` folder, then proceed to the `keymaps/default/` folder, and open `keymap.c`.
+3. Locate and delete the `action_get_macro` code block:
+ ```
+ const macro_t *action_get_macro(keyrecord_t *record, uint8_t id, uint8_t opt) {
+ ...
+ return MACRO_NONE;
}
-```
-
-Notice how the `k11` and `KC_NO` switched places to represent the wiring, and the unused final column on the bottom row. Sometimes it'll make more sense to put a keyswitch on a particular column, but in the end, it won't matter, as long as all of them are accounted for. You can use this process to write out the `LAYOUT` for your entire keyboard - be sure to remember that your keyboard is actually backwards when looking at the underside of it.
-
-### `keymaps//default.c`
-
-This is the actual keymap for your keyboard, and the main place you'll make changes as you perfect your layout. `default.c` is the file that gets pull by default when typing `make`, but you can make other files as well, and specify them by typing `make handwired/:`, which will pull `keymaps//keymap.c`.
-
-The basis of a keymap is its layers - by default, layer 0 is active. You can activate other layers, the highest of which will be referenced first. Let's start with our base layer.
-
-Using our previous example, let's say we want to create the following layout:
-
-```
- ┌───┬───┬───┐
- │ A │ 1 │ H │
- ├───┴─┬─┴───┤
- │ TAB │ SPC │
- └─────┴─────┘
-```
-
-This can be accomplished by using the following `keymaps` definition:
-
-```
-const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
- [0] = LAYOUT( /* Base */
- KC_A, KC_1, KC_H, \
- KC_TAB, KC_SPC \
- ),
-};
-```
-
-Note that the layout of the keycodes is similar to the physical layout of our keyboard - this make it much easier to see what's going on. A lot of the keycodes should be fairly obvious, but for a full list of them, check out [Keycodes](keycodes.md) - there are also a lot of aliases to condense your keymap file.
-
-It's also important to use the `LAYOUT` function we defined earlier - this is what allows the firmware to associate our intended readable keymap with the actual wiring.
-
-## Compiling Your Firmware
-
-After you've written out your entire keymap, you're ready to get the firmware compiled and onto your Teensy. Before compiling, you'll need to get your [development environment set-up](getting_started_build_tools.md) - you can skip the dfu-programmer instructions, but you'll need to download and install the [Teensy Loader](https://www.pjrc.com/teensy/loader.html) to get the firmware on your Teensy.
-
-Once everything is installed, running `make` in the terminal should get you some output, and eventually a `.hex` file in that folder. If you're having trouble with this step, see the end of the guide for the trouble-shooting section.
-
-Once you have your `.hex` file, open up the Teensy loader application, and click the file icon. From here, navigate to your `QMK/keyboards//` folder, and select the `.hex` file. Plug in your keyboard and press the button on the Teensy - you should see the LED on the device turn off once you do. The Teensy Loader app will change a little, and the buttons should be clickable - click the download button (down arrow), and then the reset button (right arrow), and your keyboard should be ready to go!
-
-
+ ```
+4. Save and close `keymap.c`.
## Flashing the Firmware
-Install [QMK toolbox](https://github.com/qmk/qmk_toolbox).
+Install [QMK Toolbox](https://github.com/qmk/qmk_toolbox).
-
+
Under "Local File" navigate to your newly created .hex file. Under "Microcontroller", select the corresponding one for your controller board (common ones available [here](#common-microcontroller-boards)).
@@ -453,20 +205,20 @@ Plug in your keyboard and press the reset button (or short the Reset and Ground
## Testing Your Firmware
-Use a website such as [keyboard tester](https://www.keyboardtester.com/tester.html)/[keyboard checker](http://keyboardchecker.com/) or just open a text editor and try typing - you should get the characters that you put into your keymap. Test each key, and make a note of the ones that aren't working. Here's a quick trouble-shooting guide for non-working keys:
+Use a website such as [QMK Configurator's Keyboard Tester](https://config.qmk.fm/#/test), [Keyboard Tester](https://www.keyboardtester.com/tester.html), or [Keyboard Checker](http://keyboardchecker.com/) or just open a text editor and try typing - you should get the characters that you put into your keymap. Test each key, and make a note of the ones that aren't working. Here's a quick trouble-shooting guide for non-working keys:
-0. Flip the keyboard back over and short the keyswitch's contacts with a piece wire - this will eliminate the possibility of the keyswitch being bad and needing to be replaced.
-1. Check the solder points on the keyswitch - these need to be plump and whole. If you touch it with a moderate amount of force and it comes apart, it's not strong enough.
-2. Check the solder joints on the diode - if the diode is loose, part of your row may register, while the other may not.
-3. Check the solder joints on the columns - if your column wiring is loose, part or all of the column may not work.
-4. Check the solder joints on both sides of the wires going to/from the Teensy - the wires need to be fully soldered and connect to both sides.
-5. Check the `Creating and compiling your firmware locally (command line method)
- -To start out, download [the firmware](https://github.com/qmk/qmk_firmware/) - We'll be doing a lot from the Terminal/command prompt, so get that open, along with a decent text editor like [Sublime Text](http://www.sublimetext.com/) (paid) or [Visual Studio Code](https://code.visualstudio.com) (free). - -The first thing we're going to do is create a new keyboard. In your terminal, run this command, which will ask you some questions and generate a basic keyboard project: - -``` -./util/new_keyboard.sh -``` - -You'll want to navigate to the `keyboards/
-# איך להפוך לשותף של QMK
-
-שותף של QMK הוא יצרן מקלדות או מעצב שמעוניין בלעזור ל-QMK לגדול ולתמוך במקלד(ו)ת שלהם, ולעודד את המשתמשים והצרכנים להוסיף יכולות, רעיונות ומיפויים. אנחנו תמיד מחפשים עוד מקלדות ומשתפי פעולה, אבל אנחנו מבקשים שיעמדו בדרישות הבאות:
-
-* **קיום לוח PCB למכירה.** לצערינו, יש יותר מידי הסתבכויות ובעיות עם מקלדות המחווטות ידנית.
-* **תחזוק המקלדת ב-QMK.** זה אולי רק ידרוש הגדרה בסיסית כדי לגרום למקלדת לעבוד, אבל זה גם יכול לכלול התאמה של שינויים בקוד הליבה של QMK שיכול לשבור קוד ייחודי שלכם.
-* **אישור ומיזוג Pull Requests של מיפויי מקלדת עבור המקלדת** אנחנו רוצים לעודד משתמשים לתרום את מיפויי המקלדת שלהם לאחרים כדי לעזור לאחרים להתחיל ליצור את שלהם.
-
-אם אתם עומדים בדרישות הללו, שלחו לנו מייל לכתובת hello@qmk.fm עם מבוא וקישורים עבור המקלדת שלכם.
-
\ No newline at end of file
diff --git a/docs/how_a_matrix_works.md b/docs/how_a_matrix_works.md
new file mode 100644
index 000000000000..df7d164cbbbc
--- /dev/null
+++ b/docs/how_a_matrix_works.md
@@ -0,0 +1,99 @@
+# How a Keyboard Matrix Works
+
+Keyboard switch matrices are arranged in rows and columns. Without a matrix circuit, each switch would require its own wire directly to the controller.
+
+When the circuit is arranged in rows and columns, if a key is pressed, a column wire makes contact with a row wire and completes a circuit. The keyboard controller detects this closed circuit and registers it as a key press.
+
+The microcontroller will be set up via the firmware to send a logical 1 to the columns, one at a time, and read from the rows, all at once - this process is called matrix scanning. The matrix is a bunch of open switches that, by default, don't allow any current to pass through - the firmware will read this as no keys being pressed. As soon as you press one key down, the logical 1 that was coming from the column the keyswitch is attached to gets passed through the switch and to the corresponding row - check out the following 2x2 example:
+
+ Column 0 being scanned Column 1 being scanned
+ x x
+ col0 col1 col0 col1
+ | | | |
+ row0 ---(key0)---(key1) row0 ---(key0)---(key1)
+ | | | |
+ row1 ---(key2)---(key3) row1 ---(key2)---(key3)
+
+The `x` represents that the column/row associated has a value of 1, or is HIGH. Here, we see that no keys are being pressed, so no rows get an `x`. For one keyswitch, keep in mind that one side of the contacts is connected to its row, and the other, its column.
+
+When we press `key0`, `col0` gets connected to `row0`, so the values that the firmware receives for that row is `0b01` (the `0b` here means that this is a bit value, meaning all of the following digits are bits - 0 or 1 - and represent the keys in that column). We'll use this notation to show when a keyswitch has been pressed, to show that the column and row are being connected:
+
+ Column 0 being scanned Column 1 being scanned
+ x x
+ col0 col1 col0 col1
+ | | | |
+ x row0 ---(-+-0)---(key1) row0 ---(-+-0)---(key1)
+ | | | |
+ row1 ---(key2)---(key3) row1 ---(key2)---(key3)
+
+We can now see that `row0` has an `x`, so has the value of 1. As a whole, the data the firmware receives when `key0` is pressed is:
+
+ col0: 0b01
+ col1: 0b00
+ │└row0
+ └row1
+
+A problem arises when you start pressing more than one key at a time. Looking at our matrix again, it should become pretty obvious:
+
+ Column 0 being scanned Column 1 being scanned
+ x x
+ col0 col1 col0 col1
+ | | | |
+ x row0 ---(-+-0)---(-+-1) x row0 ---(-+-0)---(-+-1)
+ | | | |
+ x row1 ---(key2)---(-+-3) x row1 ---(key2)---(-+-3)
+
+ Remember that this ^ is still connected to row1
+
+The data we get from that is:
+
+ col0: 0b11
+ col1: 0b11
+ │└row0
+ └row1
+
+Which isn't accurate, since we only have 3 keys pressed down, not all 4. This behavior is called ghosting, and only happens in odd scenarios like this, but can be much more common on a bigger keyboard. The way we can get around this is by placing a diode after the keyswitch, but before it connects to its row. A diode only allows current to pass through one way, which will protect our other columns/rows from being activated in the previous example. We'll represent a dioded matrix like this;
+
+ Column 0 being scanned Column 1 being scanned
+ x x
+ col0 col1 col0 col1
+ │ │ | │
+ (key0) (key1) (key0) (key1)
+ ! │ ! │ ! | ! │
+ row0 ─────┴────────┘ │ row0 ─────┴────────┘ │
+ │ │ | │
+ (key2) (key3) (key2) (key3)
+ ! ! ! !
+ row1 ─────┴────────┘ row1 ─────┴────────┘
+
+In practical applications, the black line of the diode will be placed facing the row, and away from the keyswitch - the `!` in this case is the diode, where the gap represents the black line. A good way to remember this is to think of this symbol: `>|`
+
+Now when we press the three keys, invoking what would be a ghosting scenario:
+
+ Column 0 being scanned Column 1 being scanned
+ x x
+ col0 col1 col0 col1
+ │ │ │ │
+ (┌─┤0) (┌─┤1) (┌─┤0) (┌─┤1)
+ ! │ ! │ ! │ ! │
+ x row0 ─────┴────────┘ │ x row0 ─────┴────────┘ │
+ │ │ │ │
+ (key2) (┌─┘3) (key2) (┌─┘3)
+ ! ! ! !
+ row1 ─────┴────────┘ x row1 ─────┴────────┘
+
+Things act as they should! Which will get us the following data:
+
+ col0: 0b01
+ col1: 0b11
+ │└row0
+ └row1
+
+The firmware can then use this correct data to detect what it should do, and eventually, what signals it needs to send to the OS.
+
+Further reading:
+- [Wikipedia article](https://en.wikipedia.org/wiki/Keyboard_matrix_circuit)
+- [Deskthority article](https://deskthority.net/wiki/Keyboard_matrix)
+- [Keyboard Matrix Help by Dave Dribin (2000)](https://www.dribin.org/dave/keyboard/one_html/)
+- [How Key Matrices Works by PCBheaven](http://pcbheaven.com/wikipages/How_Key_Matrices_Works/) (animated examples)
+- [How keyboards work - QMK documentation](how_keyboards_work.md)
diff --git a/docs/i2c_driver.md b/docs/i2c_driver.md
index d5c340edce73..d28a20fa16a5 100644
--- a/docs/i2c_driver.md
+++ b/docs/i2c_driver.md
@@ -1,33 +1,46 @@
-# I2C Master Driver
+# I2C Master Driver :id=i2c-master-driver
The I2C Master drivers used in QMK have a set of common functions to allow portability between MCUs.
-## Available functions
+## An important note on I2C Addresses :id=note-on-i2c-addresses
+
+All of the addresses expected by this driver should be pushed to the upper 7 bits of the address byte. Setting
+the lower bit (indicating read/write) will be done by the respective functions. Almost all I2C addresses listed
+on datasheets and the internet will be represented as 7 bits occupying the lower 7 bits and will need to be
+shifted to the left (more significant) by one bit. This is easy to do via the bitwise shift operator `<< 1`.
+
+You can either do this on each call to the functions below, or once in your definition of the address. For example if your device has an address of `0x18`:
+
+`#define MY_I2C_ADDRESS (0x18 << 1)`
+
+See https://www.robot-electronics.co.uk/i2c-tutorial for more information about I2C addressing and other technical details.
+
+## Available functions :id=available-functions
|Function |Description |
|------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|`void i2c_init(void);` |Initializes the I2C driver. This function should be called once before any transaction is initiated. |
-|`uint8_t i2c_start(uint8_t address, uint16_t timeout);` |Starts an I2C transaction. Address is the 7-bit slave address without the direction bit. |
-|`uint8_t i2c_transmit(uint8_t address, uint8_t* data, uint16_t length, uint16_t timeout);` |Transmit data over I2C. Address is the 7-bit slave address without the direction. Returns status of transaction. |
-|`uint8_t i2c_receive(uint8_t address, uint8_t* data, uint16_t length, uint16_t timeout);` |Receive data over I2C. Address is the 7-bit slave address without the direction. Saves number of bytes specified by `length` in `data` array. Returns status of transaction. |
-|`uint8_t i2c_writeReg(uint8_t devaddr, uint8_t regaddr, uint8_t* data, uint16_t length, uint16_t timeout);` |Same as the `i2c_transmit` function but `regaddr` sets where in the slave the data will be written. |
-|`uint8_t i2c_readReg(uint8_t devaddr, uint8_t regaddr, uint8_t* data, uint16_t length, uint16_t timeout);` |Same as the `i2c_receive` function but `regaddr` sets from where in the slave the data will be read. |
-|`uint8_t i2c_stop(void);` |Ends an I2C transaction. |
+|`i2c_status_t i2c_start(uint8_t address, uint16_t timeout);` |Starts an I2C transaction. Address is the 7-bit slave address without the direction bit. |
+|`i2c_status_t i2c_transmit(uint8_t address, uint8_t* data, uint16_t length, uint16_t timeout);` |Transmit data over I2C. Address is the 7-bit slave address without the direction. Returns status of transaction. |
+|`i2c_status_t i2c_receive(uint8_t address, uint8_t* data, uint16_t length, uint16_t timeout);` |Receive data over I2C. Address is the 7-bit slave address without the direction. Saves number of bytes specified by `length` in `data` array. Returns status of transaction. |
+|`i2c_status_t i2c_writeReg(uint8_t devaddr, uint8_t regaddr, uint8_t* data, uint16_t length, uint16_t timeout);` |Same as the `i2c_transmit` function but `regaddr` sets where in the slave the data will be written. |
+|`i2c_status_t i2c_readReg(uint8_t devaddr, uint8_t regaddr, uint8_t* data, uint16_t length, uint16_t timeout);` |Same as the `i2c_receive` function but `regaddr` sets from where in the slave the data will be read. |
+|`i2c_status_t i2c_stop(void);` |Ends an I2C transaction. |
-### Function Return
+### Function Return :id=function-return
All the above functions, except `void i2c_init(void);` return the following truth table:
-|Return Value |Description |
-|---------------|---------------------------------------------------|
-|0 |Operation executed successfully. |
-|-1 |Operation failed. |
-|-2 |Operation timed out. |
+|Return Constant |Value|Description |
+|--------------------|-----|--------------------------------|
+|`I2C_STATUS_SUCCESS`|0 |Operation executed successfully.|
+|`I2C_STATUS_ERROR` |-1 |Operation failed. |
+|`I2C_STATUS_TIMEOUT`|-2 |Operation timed out. |
-## AVR
+## AVR :id=avr
-### Configuration
+### Configuration :id=avr-configuration
The following defines can be used to configure the I2C master driver.
@@ -37,12 +50,12 @@ The following defines can be used to configure the I2C master driver.
AVRs usually have set GPIO which turn into I2C pins, therefore no further configuration is required.
-## ARM
+## ARM :id=arm
For ARM the Chibios I2C HAL driver is under the hood.
This section assumes an STM32 MCU.
-### Configuration
+### Configuration :id=arm-configuration
The configuration for ARM MCUs can be quite complex as often there are multiple I2C drivers which can be assigned to a variety of ports.
@@ -77,7 +90,7 @@ The ChibiOS I2C driver configuration depends on STM32 MCU:
STM32F1xx, STM32F2xx, STM32F4xx, STM32L0xx and STM32L1xx use I2Cv1;
STM32F0xx, STM32F3xx, STM32F7xx and STM32L4xx use I2Cv2;
-#### I2Cv1
+#### I2Cv1 :id=i2cv1
STM32 MCUs allow for different clock and duty parameters when configuring I2Cv1. These can be modified using the following parameters, using