Merge branch 'master' of https://github.com/jackhumbert/tmk_keyboard into audio

85 files changed, 30696 insertions, 4438 deletions

diff --git a/.gitignore b/.gitignore
index bae2658b00..49eb2d5587 100644
--- a/.gitignore
+++ b/.gitignore
@@ -12,3 +12,4 @@ tags
 *~
 build/
 *.bak
+.vagrant/
diff --git a/HAND-WIRE.md b/HAND-WIRE.md
new file mode 100644
index 0000000000..3f4d75b272
--- /dev/null
+++ b/HAND-WIRE.md
@@ -0,0 +1,323 @@
+# Quantum Hand-wiring Guide
+
+Parts list:
+* *x* keyswitches (MX, Matias, Gateron, etc)
+* *x* diodes
+* Keyboard plate (metal, plastic, cardboard, etc)
+* Wire (strained for wiring to the Teensy, anything for the rows/columns)
+* Soldering iron set at 600ºF or 315ºC (if temperature-controlled)
+* Resin-cored solder (leaded or lead-free)
+* Adequate ventilation/a fan
+* Tweezers (optional)
+* Wire cutters/snippers
+
+## How the matrix works (why we need diodes)
+
+The microcontroller (in this case, the Teensy 2.0) 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.
+
+## The actual hand-wiring
+
+### Getting things in place
+
+When starting this, you should have all of your stabilisers and keyswitches already installed (and optionally keycaps). If you're using a Cherry-type stabiliser (plate-mounted only, obviously), you'll need to install that before your keyswitches. If you're using Costar ones, you can installed them afterwards.
+
+To make things easier on yourself, make sure all of the keyswitches are oriented the same way (if they can be - not all layouts support this). Despite this, it's important to remember that the contacts on the keyswitches are completely symmetrical. We'll be using the keyswitch's left side contact for wiring the rows, and the right side one for wiring the columns. 
+
+Get your soldering iron heated-up and collect the rest of the materials from the part list at the beginning of the guide. Place your keyboard so that the bottoms of the keyswitches are accessible - it may be a good idea to place it on a cloth to protect your keyswitches/keycaps.
+
+Before continuing, plan out where you're going to place your Teensy. If you're working with a board that has a large (6.25u) spacebar, it may be a good idea to place it in-between switches against the plate. Otherwise, you may want to trim some of the leads on the keyswitches where you plan on putting it - this will make it a little harder to solder the wire/diodes, but give you more room to place the Teensy.
+
+### Preparing the diodes
+
+It's a little easier to solder the diodes in place if you bend them at a 90º angle immediately after the black line - this will help to make sure you put them on the right way (direction matters), and in the correct position. The diodes will look like this when bent (with longer leads):
+
+       ┌─────┬─┐
+    ───┤     │ ├─┐
+       └─────┴─┘ │
+                 │
+
+We'll be using the long lead at the bent end to connect it to the elbow (bent part) of the next diode, creating the row.
+
+### 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 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.
+
+The smoke that the rosin releases is harmful, so be careful not to breath it or get it in your eyes/face.
+
+After soldering things in place, it may be helpful to blow on the joint to push the smoke away from your face, and cool the solder quicker. You should see the solder develop a matte (not shiney) surface as it solidifies. Keep in mind that it will still be very hot afterwards, and will take a couple minutes to be cool to touch. Blow on it will accelerate this process.
+
+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
+
+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. 
+
+If you're using stranded wire, it's probably easiest to just use a lot of small wires to connect each keyswitch along the column. It's possible to use one and melt through the insulation, but this isn't recommended, will produce even more harmful fumes, and can ruin your soldering iron.
+
+Before beginning to solder, it helps to have your wire pre-bent (if using single-cored), or at least have an idea of how you're going to route the column (especially if you're making a staggered board). Where you go in particular doesn't matter too much, as we'll be basing our keymap definitions on how it was wired - just make sure every key in a particular row is in a unique column, and that they're in order from left to right.
+
+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.
+
+### Wiring things to the Teensy
+
+Now that the matrix itself is complete, it's time to connect what you've done to the Teensy. You'll be needing the number of pins equal to your number of columns + your number of rows. 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 are: GND, VCC, AREF, and RST - all the others are usable and accessible in the firmware.
+
+Place the Teensy where you plan to put it - you'll have to cut wires to length in the next step, and you'll want to make sure they reach.
+
+Starting with the first column on the right side, measure out how much wire you'll need to connect it to the first pin on the Teensy - it helps to pick a side that you'll be able to work down, to keep the wires from overlapping too much. It may help to leave a little bit of slack so things aren't too tight. Cut the piece of wire, and solder it to the Teensy, and then the column - you can solder it anywhere along the column, but it may be easiest at the keyswitch. Just be sure the wire doesn't separate from the keyswitch when soldering.
+
+As you move from column to column, it'll be helpful to write the locations of the pins down. We'll use this data to setup the matrix in the future.
+
+When you're done with the columns, start with the rows in the same process, from top to bottom, and write them all down. Again, 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.
+
+As you move along, be sure that the Teensy is staying in place - recutting and soldering the wires is a pain!
+
+### Getting some basic firmware set-up
+
+From here, you should have a working keyboard with the correct firmware. Before we attach the Teensy permanently to the keyboard, let's quickly get some firmware loaded onto the Teensy so we can test each keyswitch.
+
+To start out, download [the firmware](https://github.com/jackhumbert/qmk_firmware/) - we'll be using my (Jack's) fork of TMK called QMK/Quantum. 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/).
+
+The first thing we're going to do is create a new project using the script in the root directory of the firmware. In your terminal, run this command with `<project_name>` replaced by the name of your project - it'll need to be different from any other project in the `keyboard/` folder:
+
+    ./new_project.sh <project_name>
+
+You'll want to navigate to the `keyboard/<project_name>/` folder by typing, like the print-out from the script specifies:
+
+    cd keyboard/<project_name>
+
+#### config.h
+
+The first thing we're going to want to modify is the `config.h` file. On line 32 and 33, you'll see `MATRIX_ROWS` and `MATRIX_COLS` - set both these variables to however many rows and columns you have on your keyboard.
+
+On line 38 and 39 you'll see the `COLS` and `ROWS` definitions - this is where you'll enter the pins you used, in order (left-to-right when looking at the top of the keyboard, but right-to-left when looking at the bottom).
+
+There are some other variables that you'll be able to modify (lines 23-29), but it's not necessary to do that now (or ever, really).
+
+#### \<project_name\>.h
+
+The next file you'll want to look at is `<project_name>.h`. You're going to want to rewrite the `KEYMAP` 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, s