Merge remote-tracking branch 'refs/remotes/jackhumbert/master'

5 files changed, 133 insertions, 7 deletions

diff --git a/doc/TMK_README.md b/doc/TMK_README.md
index 6164dacd3..e3438eda2 100644
--- a/doc/TMK_README.md
+++ b/doc/TMK_README.md
@@ -34,7 +34,7 @@ You can find some keyboard specific projects under `converter` and `keyboard` di
 * [atomic](keyboards/atomic/)                - [Atomic] Ortholinear 60% keyboard
 
 ### Ergodox EZ
-* [ergodox_ez](keyboards/ergodox_ez)         - [Ergodox_EZ] Assembled split keyboard
+* [ergodox_ez](keyboards/ergodox/ez)         - [Ergodox_EZ] Assembled split keyboard
 
 ## Other projects
 
@@ -113,7 +113,7 @@ Third party libraries like LUFA, PJRC and V-USB have their own license respectiv
 
 Build Firmware and Program Controller
 -------------------------------------
-See [doc/build.md](tmk_core/doc/build.md), or the readme in the particular keyboards/* folder.
+See [build environment setup](/readme.md#build-environment-setup), or the readme in the particular keyboards/* folder.
 
 
 
diff --git a/doc/VAGRANT_GUIDE.md b/doc/VAGRANT_GUIDE.md
index 62044b7f7..439e78da7 100644
--- a/doc/VAGRANT_GUIDE.md
+++ b/doc/VAGRANT_GUIDE.md
@@ -6,7 +6,8 @@ This project includes a Vagrantfile that will allow you to build a new firmware
 
 Using the `/Vagrantfile` in this repository requires you have [Vagrant](http://www.vagrantup.com/) as well as [VirtualBox](https://www.virtualbox.org/) (or [VMware Workstation](https://www.vmware.com/products/workstation) and [Vagrant VMware plugin](http://www.vagrantup.com/vmware) but the (paid) VMware plugin requires a licensed copy of VMware Workstation/Fusion).
 
-*COMPATIBILITY NOTICE* Certain versions of Virtualbox 5 appear to have an incompatibility with the Virtualbox extensions installed in the boxes in this Vagrantfile. If you encounter any issues with the /vagrant mount not succeeding, please upgrade your version of Virtualbox to at least 5.0.12.
+*COMPATIBILITY NOTICE* Certain versions of Virtualbox 5 appear to have an incompatibility with the Virtualbox extensions installed in the boxes in this Vagrantfile. If you encounter any issues with the /vagrant mount not succeeding, please upgrade your version of Virtualbox to at least 5.0.12. **Alternately, you can try running the following command:** `vagrant plugin install vagrant-vbguest`
+
 
 Other than having Vagrant and Virtualbox installed and possibly a restart of your computer afterwards, you can simple run a 'vagrant up' anywhere inside the folder where you checked out this project and it will start a Linux virtual machine that contains all the tools required to build this project. There is a post Vagrant startup hint that will get you off on the right foot, otherwise you can also reference the build documentation below.
 
@@ -20,7 +21,7 @@ See [/doc/keymap.md](/doc/keymap.md).
 
 ## Flashing the firmware
 
-The "easy" way to flash the firmware is using a tool from your host OS like the Teensy programming app. [ErgoDox EZ](/keyboards/ergodox_ez/readme.md) gives a great example.
+The "easy" way to flash the firmware is using a tool from your host OS like the Teensy programming app. [ErgoDox EZ](/keyboards/ergodox/readme.md) gives a great example.
 
 If you want to program via the command line you can uncomment the ['modifyvm'] lines in the Vagrantfile to enable the USB passthrough into Linux and then program using the command line tools like dfu-util/dfu-programmer or you can install the Teensy CLI version.
-	
\ No newline at end of file
+	
diff --git a/doc/basic_how_keyboards_work.md b/doc/basic_how_keyboards_work.md
new file mode 100644
index 000000000..73c3f5c5f
--- /dev/null
+++ b/doc/basic_how_keyboards_work.md
@@ -0,0 +1,96 @@
+# How keys are registered, and interpreted by computers
+
+In this file, you can will learn the concepts of how keyboards work over USB,
+and you'll be able to better understand what you can expect from changing your
+firmware directly.
+
+## Schematic view
+
+Whenever you type on 1 particular key, here is the chain of actions taking
+place:
+
+``` text
++------+         +-----+       +----------+      +----------+     +----+
+| User |-------->| Key |------>| Firmware |----->| USB wire |---->| OS |
++------+         +-----+       +----------+      +----------+     |----+
+```
+
+This scheme is a very simple view of what's going on, and more details follow
+in the next sections.
+
+## 1. You Press a Key
+
+Whenever you press a key, the firmware of your keyboard can register this event.
+It can register when the key is pressed, held and released.
+
+This usually happens with a [periodic scan of key presses with a frequency around 100 hz](https://github.com/benblazak/ergodox-firmware/blob/master/references.md#typical-keyboard-information).
+This speed often is limited by the mechanical key response time, the protocol
+to transfer those key presses (here USB HID), and by the software it is used in.
+
+## 2. What the Firmware Sends
+
+The [HID specification](http://www.usb.org/developers/hidpage/Hut1_12v2.pdf)
+tells what a keyboard can actually send through USB to have a chance to be
+properly recognised. This includes a pre-defined list of keycodes which are
+simple numbers from `0x00` to `0xE7`. The firmware assigns a keycode to each
+key of the keyboard.
+
+The firmware does not send actually letters or characters, but only keycodes.
+Thus, by modifying the firmware, you only can modify what keycode is sent over
+USB for a given key.
+
+## 3. What the Operating System Does
+
+Once the keycode reaches the operating system, a piece of software has to have
+it match an actual character thanks to a keyboard layout. For example, if your
+layout is set to QWERTY, a sample of the matching table is as follow:
+
+``` text
+| keycode | character |
+|---------+-----------|
+|    0x04 | a/A       |
+|    0x05 | b/B       |
+|    0x06 | c/C       |
+|     ... | ...       |
+|    0x1C | y/Y       |
+|    0x1D | z/Z       |
+|     ... | ...       |
+|---------+-----------|
+```
+
+## Back to the firmware
+
+As the layout is generally fixed (unless you create your own), the firmware can
+actually call a keycode by its layout name directly to ease things for you.
+
+This is exactly what is done here with `KC_A` actually representing `0x04` in
+QWERTY. The full list can be found in `keycode.txt`.
+
+## List of Characters You Can Send
+
+Putting aside shortcuts, having a limited set of keycodes mapped to a limited
+layout means that **the list of characters you can assign to a given key only
+is the ones present in the layout**.
+
+For example, this means that if you have a QWERTY US layout, and you want to
+assign 1 key to produce `€` (euro currency symbol), you are unable to do so,
+because the QWERTY US layout does not have such mapping. You could fix that by
+using a QWERTY UK layout, or a QWERTY US International.
+
+You may wonder why a keyboard layout containing all of Unicode is not devised
+then? The limited number of keycode available through USB simply disallow such
+a thing.
+
+## How to (Maybe) Enter Unicode Characters
+
+You can have the firmware send *sequences of keys* to use the [software Unicode
+Input
+Method](https://en.wikipedia.org/wiki/Unicode_input#Hexadecimal_code_input) of
+the target operating system, thus effectively entering characters independently
+of the layout defined in the OS.
+
+Yet, it does come with multiple disadvantages:
+
+ - Tied to a specific OS a a time (need recompilation when changing OS);
+ - Within a given OS, does not work in all software;
+ - Limited to a subset of Unicode on some systems.
diff --git a/doc/keycode.txt b/doc/keycode.txt
index c1134f9bf..687406fda 100644
--- a/doc/keycode.txt
+++ b/doc/keycode.txt
@@ -2,7 +2,7 @@ Keycode Symbol Table
 ====================
 Keycodes are defined in `common/keycode.h`.
 Range of 00-A4 and E0-E7 are identical with HID Usage:
-<http://www.usb.org/developers/devclass_docs/Hut1_11.pdf>
+<http://www.usb.org/developers/hidpage/Hut1_12v2.pdf>
 Virtual keycodes are defined out of above range to support special actions.
 
 
@@ -84,7 +84,7 @@ KC_PAUSE            KC_PAUS         48 Keyboard Pause1
 KC_INSERT           KC_INS          49 Keyboard Insert1
 KC_HOME                             4A Keyboard Home1
 KC_PGUP                             4B Keyboard PageUp1
-KC_DELETE           KC_DELETE       4C Keyboard Delete Forward
+KC_DELETE           KC_DEL          4C Keyboard Delete Forward
 KC_END                              4D Keyboard End1
 KC_PGDOWN           KC_PGDN         4E Keyboard PageDown1
 KC_RIGHT            KC_RGHT         4F Keyboard RightArrow1
diff --git a/doc/keymap.md b/doc/keymap.md
index d1985e567..6f2a663fc 100644
--- a/doc/keymap.md
+++ b/doc/keymap.md
@@ -455,6 +455,35 @@ Turn the backlight on and off without changing level.
 
 
 
+### 2.6 Swap-Hands Action
+The swap-hands action allows support for one-handed keyboards without requiring a separate layer. Set `ONEHAND_ENABLE` in the Makefile and define a `hand_swap_config` entry in your keymap. Now whenever the `ACTION_SWAP_HANDS` command key is pressed the keyboard is mirrored. For instance, to type "Hello, World" on QWERTY you would type `^Ge^s^s^w^c W^wr^sd`
+
+### 2.6.1 Configuration
+The configuration table is a simple 2-dimensional array to map from column/row to new column/row. Example `hand_swap_config` for Planck:
+
+```
+const keypos_t hand_swap_config[MATRIX_ROWS][MATRIX_COLS] = {
+  {{11, 0}, {10, 0}, {9, 0}, {8, 0}, {7, 0}, {6, 0}, {5, 0}, {4, 0}, {3, 0}, {2, 0}, {1, 0}, {0, 0}},
+  {{11, 1}, {10, 1}, {9, 1}, {8, 1}, {7, 1}, {6, 1}, {5, 1}, {4, 1}, {3, 1}, {2, 1}, {1, 1}, {0, 1}},
+  {{11, 2}, {10, 2}, {9, 2}, {8, 2}, {7, 2}, {6, 2}, {5, 2}, {4, 2}, {3, 2}, {2, 2}, {1, 2}, {0, 2}},
+  {{11, 3}, {10, 3}, {9, 3}, {8, 3}, {7, 3}, {6, 3}, {5, 3}, {4, 3}, {3, 3}, {2, 3}, {1, 3}, {0, 3}},
+};
+```
+
+Note that the array indices are reversed same as the matrix and the values are of type `keypos_t` which is `{col, row}` and all values are zero-based. In the example above, `hand_swap_config[2][4]` (third row, fifth column) would return {7, 2} (third row, eighth column).
+
+### 2.6.2 Advanced Swap Commands
+- **`ACTION_SWAP_HANDS()`** Swaps hands when pressed, returns to normal when released (momentary).
+- **`ACTION_SWAP_HANDS_TOGGLE()`** Toggles swap on and off with every keypress.
+- **`ACTION_SWAP_HANDS_TAP_TOGGLE()`** Toggles with a tap; momentary when held.
+- **`ACTION_SWAP_HANDS_TAP_KEY(key)`** Sends `key` with a tap; momentary swap when held.
+- **`ACTION_SWAP_HANDS_ON_OFF()`** Alias for `ACTION_SWAP_HANDS()`
+- **`ACTION_SWAP_HANDS_OFF_ON()`** Momentarily turns off swap.
+- **`ACTION_SWAP_HANDS_ON()`** Turns on swapping and leaves it on.
+- **`ACTION_SWAP_HANDS_OFF()`** Turn off swapping and leaves it off. Good for returning to a known state.
+
+
+
 ## 3. Layer switching Example
 There are some ways to switch layer with 'Layer' actions.