[planck] Adds Sean Hunter keymap(#1706)

* Sean Hunter initial keymap

* Update old map to sync it up with new one

* Add TODO
fix a few minor things

* small doc fixes

* Minor fixups

5 files changed, 508 insertions, 0 deletions

diff --git a/keyboards/planck/keymaps/sean/Makefile b/keyboards/planck/keymaps/sean/Makefile
new file mode 100644
index 0000000000..09b127dc05
--- /dev/null
+++ b/keyboards/planck/keymaps/sean/Makefile
@@ -0,0 +1,4 @@
+ifndef QUANTUM_DIR
+	include ../../../../Makefile
+endif
+MOUSEKEY_ENABLE = yes
diff --git a/keyboards/planck/keymaps/sean/config.h b/keyboards/planck/keymaps/sean/config.h
new file mode 100644
index 0000000000..4c61581993
--- /dev/null
+++ b/keyboards/planck/keymaps/sean/config.h
@@ -0,0 +1,29 @@
+#ifndef CONFIG_USER_H
+#define CONFIG_USER_H
+
+#include "../../config.h"
+
+/*
+ * MIDI options
+ */
+
+/* Prevent use of disabled MIDI features in the keymap */
+//#define MIDI_ENABLE_STRICT 1
+
+/* enable basic MIDI features:
+   - MIDI notes can be sent when in Music mode is on
+*/
+#define MIDI_BASIC
+
+/* enable advanced MIDI features:
+   - MIDI notes can be added to the keymap
+   - Octave shift and transpose
+   - Virtual sustain, portamento, and modulation wheel
+   - etc.
+*/
+//#define MIDI_ADVANCED
+
+/* override number of MIDI tone keycodes (each octave adds 12 keycodes and allocates 12 bytes) */
+//#define MIDI_TONE_KEYCODE_OCTAVES 2
+
+#endif
\ No newline at end of file
diff --git a/keyboards/planck/keymaps/sean/keymap.c b/keyboards/planck/keymaps/sean/keymap.c
new file mode 100644
index 0000000000..d61d802b0b
--- /dev/null
+++ b/keyboards/planck/keymaps/sean/keymap.c
@@ -0,0 +1,306 @@
+// This is Sean Hunter's keymap file, customized from the canonical layout file for the Quantum project.
+// If you want to add another keyboard, that is the style you want to emulate.
+
+#include "planck.h"
+#include "action_layer.h"
+#include "eeconfig.h"
+#include "mymappings.h"
+
+extern keymap_config_t keymap_config;
+
+// Each layer gets a name for readability, which is then used in the keymap matrix below.
+
+enum planck_layers {
+  _DVRK,
+  _LOWER,
+  _RAISE,
+  _SDRK,
+  _SLWER,
+  _SRAIS,
+  _NMPD,
+  _MVMT,
+  _ADJUST
+};
+
+enum planck_keycodes {
+  DVRK = SAFE_RANGE,
+  LOWER,
+  RAISE,
+  SDRK,
+  SLWER,
+  SRAIS,
+  BACKLIT,
+  BACKTOG,
+  CUT,
+  COPY,
+  PASTE
+};
+
+const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
+
+/* Dvorak
+ * ,-----------------------------------------------------------------------------------.
+ * |   "  |   ,  |   .  |   P  |   Y  |   /  |   =  |   F  |   G  |   C  |   R  |   L  |
+ * |------+------+------+------+------+------+------+------+------+------+------+------|
+ * |   A  |   O  |   E  |   U  |   I  | ESC  | BSPC |   D  |   H  |   T  |   N  |   S  |
+ * |------+------+------+------+------+------+------+------+------+------+------+------|
+ * |   ;  |   Q  |   J  |   K  |   X  | TAB  | ENT  |   B  |   M  |   W  |   V  |   Z  |
+ * |------+------+------+------+------+------+------+------+------+------+------+------|
+ * | Sft  | Ctl  | Alt  | Gui  |Lower |    Space    |Raise |   <  |   v  |   ^  |   >  |
+ * `-----------------------------------------------------------------------------------'
+ */
+[_DVRK] = {
+  {KC_QUOT, KC_COMM, KC_DOT,  KC_P,    KC_Y,    KC_SLSH, KC_EQL,  KC_F,     KC_G,    KC_C,   KC_R,    KC_L},
+  {KC_A,    KC_O,    KC_E,    KC_U,    KC_I,    KC_ESC,  KC_BSPC, KC_D,     KC_H,    KC_T,   KC_N,    KC_S},
+  {KC_SCLN, KC_Q,    KC_J,    KC_K,    KC_X,    KC_TAB,  KC_ENT,  KC_B,     KC_M,    KC_W,   KC_V,    KC_Z},
+  {KC_LSFT, KC_LCTL, KC_LALT, KC_LGUI, LOWER,   KC_SPC,  KC_SPC,  RAISE, KC_LEFT, KC_DOWN,  KC_UP, KC_RIGHT}
+},
+
+
+/* Lower
+ * ,-----------------------------------------------------------------------------------.
+ * | F1   |  F2  |  F3  |  F4  |  F5  |  {   |  }   |  F6  |  F7  |  F8  |  F9  | F10  |
+ * |------+------+------+------+------+-------------+------+------+------+------+------|
+ * |  1   |   2  |   3  |   4  |   5  |  [   |  ]   |   6  |   7  |   8  |   9  |  0   |
+ * |------+------+------+------+------+------|------+------+------+------+------+------|
+ * |   ~  |   |  |   `  |   -  |   _  | INS  | DEL  |   (  |   )  |   +  |   =  |  \   |
+ * |------+------+------+------+------+------+------+------+------+------+------+------|
+ * | Sft  | Ctl  | Alt  | Gui  |Lower |             |Raise | Home | PgDn | PgUp | End  |
+ * `-----------------------------------------------------------------------------------'
+ */
+[_LOWER] = {
+  {KC_F1,   KC_F2,   KC_F3,   KC_F4,   KC_F5,   KC_LCBR, KC_RCBR, KC_F6,     KC_F7,    KC_F8,   KC_F9,    KC_F10},
+  {KC_1,    KC_2,    KC_3,    KC_4,    KC_5,    KC_LBRC, KC_RBRC, KC_6,      KC_7,     KC_8,    KC_9,     KC_0},
+  {KC_TILD, KC_PIPE, KC_GRV,  KC_MINS, KC_UNDS, KC_INS,  KC_DEL,  KC_LPRN,   KC_RPRN,  KC_PLUS, KC_EQL,   KC_BSLS},
+  {_______, _______, _______, _______, _______, _______, _______, _______,   KC_HOME,  KC_PGDN, KC_PGUP,  KC_END}
+},
+
+
+/* Raise
+ * ,-----------------------------------------------------------------------------------.
+ * | F11  |  F12 |  F13 |  F14 |  F15 |      |      |  F16 |  F17 |  F18 |  F19 | F20  |
+ * |------+------+------+------+------+-------------+------+------+------+------+------|
+ * |  !   |   @  |   #  |   $  |   %  |Sleep | Wake |   ^  |   &  |   *  |   (  |  )   |
+ * |------+------+------+------+------+-------------+------+------+------+------+------|
+ * | GUI1 | GUI2 | GUI3 | GUI4 | GUI5 |             | GUI6 | GUI7 | GUI8 | GUI9 |GUI10 |
+ * |------+------+------+------+------+------+------+------+------+------+------+------|
+ * | Sft  | Ctl  | Alt  | Gui  |Lower |             |Raise | Gui  | Alt  | Ctl  | Sft  |
+ * `-----------------------------------------------------------------------------------'
+ */
+[_RAISE] = {
+  { KC_F11,  KC_F12,  KC_F13,  KC_F14,  KC_F15, _______, _______,   KC_F16,  KC_F17,  KC_F18,  KC_F19,  KC_F20},
+  {KC_EXLM,   KC_AT, KC_HASH,  KC_DLR, KC_PERC, KC_SLEP, KC_WAKE,   KC_CIRC, KC_AMPR, KC_ASTR, KC_LPRN, KC_RPRN},
+  {  GUI_1,   GUI_2,   GUI_3,   GUI_4,   GUI_5, _______, _______,     GUI_6,   GUI_7,   GUI_8,   GUI_9,  GUI_10},
+  {KC_LSFT, KC_LCTL, KC_LALT, KC_LGUI,   LOWER,  KC_SPC,  KC_SPC,     RAISE, KC_RGUI, KC_RALT, KC_RCTL, KC_RSFT}
+},
+
+/* 'Software Dvorak': Designed to look like dvorak in the mapping but depend on software 
+ * dvorak (ie the OS keymapping changed to dvorak).
+ * ,-----------------------------------------------------------------------------------.
+ * |   "  |   ,  |   .  |   P  |   Y  |   /  |   =  |   F  |   G  |   C  |   R  |   L  |
+ * |------+------+------+------+------+------+------+------+------+------+------+------|
+ * |   A  |   O  |   E  |   U  |   I  | ESC  | BSPC |   D  |   H  |   T  |   N  |   S  |
+ * |------+------+------+------+------+------+------+------+------+------+------+------|
+ * |   ;  |   Q  |   J  |   K  |   X  | TAB  | ENT  |   B  |   M  |   W  |   V  |   Z  |
+ * |------+------+------+------+------+------+------+------+------+------+------+------|
+ * | Sft  | Ctl  | Alt  | Gui  |SLower|    Space    |SRaise|   <  |   v  |   ^  |   >  |
+ * `-----------------------------------------------------------------------------------'
+ */
+[_SDRK] = {
+  {DV_QUOT, DV_COMM, DV_DOT,  DV_P,    DV_Y,    DV_SLSH, DV_EQL,  DV_F,     DV_G,    DV_C,   DV_R,    DV_L},
+  {DV_A,    DV_O,    DV_E,    DV_U,    DV_I,    KC_ESC,  KC_BSPC, DV_D,     DV_H,    DV_T,   DV_N,    DV_S},
+  {DV_SCLN, DV_Q,    DV_J,    DV_K,    DV_X,    KC_TAB,  KC_ENT,  DV_B,     DV_M,    DV_W,   DV_V,    DV_Z},
+  {KC_LSFT, KC_LCTL, KC_LALT, KC_LGUI, SLWER,   KC_SPC,  KC_SPC, SRAIS, KC_LEFT, KC_DOWN,  KC_UP, KC_RIGHT}
+},
+
+
+/* 'Software dvorak lower mode':  Puts all the braces etc in the right places so it works
+ * just like the lower mode above except that it depends on the OS keymapping being set
+ * to dvorak.
+ * ,-----------------------------------------------------------------------------------.
+ * | F1   |  F2  |  F3  |  F4  |  F5  |  {   |  }   |  F6  |  F7  |  F8  |  F9  | F10  |
+ * |------+------+------+------+------+-------------+------+------+------+------+------|
+ * |  1   |   2  |   3  |   4  |   5  |  [   |  ]   |   6  |   7  |   8  |   9  |  0   |
+ * |------+------+------+------+------+------|------+------+------+------+------+------|
+ * |   ~  |   |  |   `  |   -  |   _  | INS  | DEL  |   (  |   )  |   +  |   =  |  \   |
+ * |------+------+------+------+------+------+------+------+------+------+------+------|
+ * | Sft  | Ctl  | Alt  | Gui  |SLower|             |SRaise| Home | PgDn | PgUp | End  |
+ * `-----------------------------------------------------------------------------------'
+ */
+[_SLWER] = {
+  {KC_F1,   KC_F2,   KC_F3,   KC_F4,   KC_F5,   DV_LCBR, DV_RCBR, KC_F6,     KC_F7,    KC_F8,   KC_F9,    KC_F10},
+  {DV_1,    DV_2,    DV_3,    DV_4,    DV_5,    DV_LBRC, DV_RBRC, DV_6,      DV_7,     DV_8,    DV_9,     DV_0},
+  {DV_TILD, DV_PIPE, DV_GRV,  DV_MINS, DV_UNDS, KC_INS,  KC_DEL,  DV_LPRN,   DV_RPRN,  DV_PLUS, DV_EQL,   DV_BSLS},
+  {_______, _______, _______, _______, _______, _______, _______, _______,   KC_HOME,  KC_PGDN, KC_PGUP,  KC_END}
+},
+
+
+/* 'Software dvorak raise mode'
+ * ,-----------------------------------------------------------------------------------.
+ * | F11  |  F12 |  F13 |  F14 |  F15 |      |      |  F16 |  F17 |  F18 |  F19 | F20  |
+ * |------+------+------+------+------+-------------+------+------+------+------+------|
+ * |  !   |   @  |   #  |   $  |   %  |Sleep | Wake |   ^  |   &  |   *  |   (  |  )   |
+ * |------+------+------+------+------+-------------+------+------+------+------+------|
+ * | GUI1 | GUI2 | GUI3 | GUI4 | GUI5 |             | GUI6 | GUI7 | GUI8 | GUI9 |GUI10 |
+ * |------+------+------+------+------+------+------+------+------+------+------+------|
+ * | Sft  | Ctl  | Alt  | Gui  |Lower |             |Raise | Gui  | Alt  | Ctl  | Sft  |
+ * `-----------------------------------------------------------------------------------'
+ */
+[_SRAIS] = {
+  { KC_F11,  KC_F12,  KC_F13,  KC_F14,  KC_F15, _______, _______,   KC_F16,  KC_F17,  KC_F18,  KC_F19,  KC_F20},
+  {DV_EXLM,   DV_AT, DV_HASH,  DV_DLR, DV_PERC, KC_SLEP, KC_WAKE,   DV_CIRC, DV_AMPR, DV_ASTR, DV_LPRN, DV_RPRN},
+  {  GUI_1,   GUI_2,   GUI_3,   GUI_4,   GUI_5, _______, _______,     GUI_6,   GUI_7,   GUI_8,   GUI_9,  GUI_10},
+  {KC_LSFT, KC_LCTL, KC_LALT, KC_LGUI,   SLWER,  KC_SPC,  KC_SPC,     SRAIS, KC_RGUI, KC_RALT, KC_RCTL, KC_RSFT}
+},
+
+
+/* Adjust (Lower + Raise or SLower + SRaise)
+ * ,-----------------------------------------------------------------------------------.
+ * |      | Reset|      |      |      |AGnorm|AGswap|      |      |HRevl |HReset|HMenu |
+ * |------+------+------+------+------+-------------+------+------+------+------+------|
+ * | PWR  | EJCT | CUT  | COPY |PASTE |PrScr |SysReq| CAPS | <<   |  >>  | Mute | Stop |
+ * |------+------+------+------+------+------|------+------+------+------+------+------|
+ * |DVORAK|NUMPAD| MVMT | SDRK |      |      |      |      | Next | Vol- | Vol+ | Play |
+ * |------+------+------+------+------+------+------+------+------+------+------+------|
+ * |Brite |BToggl|      |      |             |      |      | Gui  | Alt  | Ctl  | Sft  |
+ * `-----------------------------------------------------------------------------------'
+ */
+[_ADJUST] = {
+  {_______,     RESET,   _______, _______, _______, AG_NORM,   AG_SWAP, _______, _______,    HRVL,  HRESET,  HMENU},
+  { KC_PWR,   KC_EJCT,       CUT,    COPY,   PASTE, KC_PSCR, KC_SYSREQ, KC_CAPS, KC_MRWD, KC_MFFD, KC_MUTE, KC_MSTP},
+  {   DVRK, TO(_NMPD), TO(_MVMT),    SDRK, _______, _______,   _______, _______, KC_MNXT, KC_VOLD, KC_VOLU, KC_MPLY},
+  {BACKLIT,   BACKTOG,   _______, _______, _______, _______,   _______, _______, KC_RGUI, KC_RALT, KC_RCTL, KC_RSFT}
+},
+
+
+/* Numpad
+ * ,-----------------------------------------------------------------------------------.
+ * |      |      |      |      |      |      |      |NumLck|   7  |   8  |   9  |   /  |
+ * |------+------+------+------+------+------+------+------+------+------+------+------|
+ * |      |      |      |      |      |      |      |Enter |   4  |   5  |   6  |   *  |
+ * |------+------+------+------+------+------+------+------+------+------+------+------|
+ * |DVORAK|NUMPAD| MVMT | SDRK |      |      |      |      |   3  |   2  |   1  |   -  |
+ * |------+------+------+------+------+-------------+------+------+------+------+------|
+ * |      |      |      |      |      |             |      |      |   0  |   .  |   +  |
+ * `-----------------------------------------------------------------------------------'
+ */
+[_NMPD] = {
+    {XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, KC_NLCK, KC_P7,   KC_P8,   KC_P9,   KC_PSLS},
+    {XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, KC_PENT, KC_P4,   KC_P5,   KC_P6,   KC_PAST},
+    {TO(_DVRK),TO(_NMPD),TO(_MVMT),SDRK, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, KC_P1,   KC_P2,   KC_P3,   KC_PMNS},
+    {_______, _______, _______, _______, _______, _______, _______, _______, _______, KC_P0,   KC_PDOT, KC_PPLS}
+},
+
+
+/* Movement
+ * ,-----------------------------------------------------------------------------------.
+ * |MsBut2|MsWhDn|MsWhUp|MsBut1|MsBut3|      |      |      | Home | PgDn | PgUp |  End |
+ * +------+------+------+------+------+------+------+------+------+------+------+------+
+ * |Ms Lft|Ms Dn |Ms Up |Ms Rht|      |      |      |      | Left | Down |  Up  | Right|
+ * |------+------+------+------+------+------+------+------+------+------+------+------|
+ * |DVORAK|NUMPAD| MVMT | SDRK |      |      |      |      |      |      |      |      |
+ * |------+------+------+------+------+-------------+------+------+------+------+------|
+ * | Sft  | Ctl  | Alt  | Gui  |      |             |      | Gui  | Alt  | Ctl  | Sft  |
+ * `-----------------------------------------------------------------------------------'
+ */
+[_MVMT] = {
+    {KC_MB2,  KC_MWDN, KC_MWUP, KC_MB1,   KC_MB3, XXXXXXX, XXXXXXX, XXXXXXX, KC_HOME, KC_PGDN, KC_PGUP, KC_END},
+    {KC_MLFT, KC_MDN,  KC_MUP,  KC_MRGT, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, KC_LEFT, KC_DOWN, KC_UP,   KC_RGHT},
+    {TO(_DVRK),TO(_NMPD),TO(_MVMT),SDRK,XXXXXXX,XXXXXXX,XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX},
+    {KC_LSFT, KC_LCTL, KC_LALT, KC_LGUI, _______, _______, _______, _______, KC_RGUI, KC_RALT, KC_RCTL, KC_RSFT}
+},
+};
+
+
+void persistent_default_layer_set(uint16_t default_layer) {
+  eeconfig_update_default_layer(default_layer);
+  default_layer_set(default_layer);
+}
+
+bool process_record_user(uint16_t keycode, keyrecord_t *record) {
+  switch (keycode) {
+    case DVRK:
+      if (record->event.pressed) {
+        persistent_default_layer_set(1UL<<_DVRK);
+        layer_on(_DVRK);
+      }
+      return false;
+      break;
+    case LOWER:
+      if (record->event.pressed) {
+        layer_on(_LOWER);
+        update_tri_layer(_LOWER, _RAISE, _ADJUST);
+      } else {
+        layer_off(_LOWER);
+        update_tri_layer(_LOWER, _RAISE, _ADJUST);
+      }
+      return false;
+      break;
+    case RAISE:
+      if (record->event.pressed) {
+        layer_on(_RAISE);
+        update_tri_layer(_LOWER, _RAISE, _ADJUST);
+      } else {
+        layer_off(_RAISE);
+        update_tri_layer(_LOWER, _RAISE, _ADJUST);
+      }
+      return false;
+      break;
+    case SDRK:
+      if (record->event.pressed) {
+        persistent_default_layer_set(1UL<<_SDRK);
+        layer_on(_SDRK);
+      }
+      return false;
+      break;
+    case SLWER:
+      if (record->event.pressed) {
+        layer_on(_SLWER);
+        update_tri_layer(_SLWER, _SRAIS, _ADJUST);
+      } else {
+        layer_off(_SLWER);
+        update_tri_layer(_SLWER, _SRAIS, _ADJUST);
+      }
+      return false;
+      break;
+    case SRAIS:
+      if (record->event.pressed) {
+        layer_on(_SRAIS);
+        update_tri_layer(_SLWER, _SRAIS, _ADJUST);
+      } else {
+        layer_off(_SRAIS);
+        update_tri_layer(_SLWER, _SRAIS, _ADJUST);
+      }
+      return false;
+      break;
+    case BACKLIT:
+      if (record->event.pressed) {
+        register_code(KC_RSFT);
+        #ifdef BACKLIGHT_ENABLE
+          backlight_step();
+        #endif
+      } else {
+        unregister_code(KC_RSFT);
+      }
+      return false;
+      break;
+    case BACKTOG:
+      if (record->event.pressed) {
+        #ifdef BACKLIGHT_ENABLE
+          backlight_toggle();
+        #endif
+      }
+      return false;
+      break;
+    case CUT: //cut macro
+	    return MACRODOWN( DOWN(KC_LCTL), TYPE(KC_X), UP(KC_LCTL), END );
+    case COPY: // copy macro
+	    return MACRODOWN( DOWN(KC_LCTL), TYPE(KC_C), UP(KC_LCTL), END );
+    case PASTE: // paste macro
+	    return MACRODOWN( DOWN(KC_LCTL), TYPE(KC_V), UP(KC_LCTL), END );
+  }
+  return true;
+}
+
+void matrix_init_user(void) {
+}
diff --git a/keyboards/planck/keymaps/sean/mymappings.h b/keyboards/planck/keymaps/sean/mymappings.h
new file mode 100644
index 0000000000..cbb016e38d
--- /dev/null
+++ b/keyboards/planck/keymaps/sean/mymappings.h
@@ -0,0 +1,39 @@
+//Defines etc for Sean Hunter's keymap.
+
+#include "keymap_extras/keymap_dvorak.h"
+
+#define PERMISSIVE_HOLD
+
+//Special hammerspoon keys
+#define HMENU  LCTL(LSFT(KC_BSLS))
+#define HRESET LCTL(LSFT(KC_EQL))
+#define HRVL   LCTL(LSFT(KC_SLSH))
+
+//Make virtual desktops a little easier on i3 (otherwise on this keyboard they're awkward
+#define GUI_1 LGUI(KC_1)
+#define GUI_2 LGUI(KC_2)
+#define GUI_3 LGUI(KC_3)
+#define GUI_4 LGUI(KC_4)
+#define GUI_5 LGUI(KC_5)
+#define GUI_6 LGUI(KC_6)
+#define GUI_7 LGUI(KC_7)
+#define GUI_8 LGUI(KC_8)
+#define GUI_9 LGUI(KC_9)
+#define GUI_10 LGUI(KC_0)
+
+//Abbreviations for mouse keys
+#define KC_MUP KC_MS_UP
+#define KC_MDN KC_MS_DOWN
+#define KC_MLFT KC_MS_LEFT
+#define KC_MRGT KC_MS_RIGHT
+#define KC_MB1 KC_MS_BTN1
+#define KC_MB2 KC_MS_BTN2
+#define KC_MB3 KC_MS_BTN3
+#define KC_MB4 KC_MS_BTN4
+#define KC_MB5 KC_MS_BTN5
+#define KC_MWUP KC_MS_WH_UP
+#define KC_MWDN KC_MS_WH_DOWN
+
+// Fillers to make layering more clear
+#define _______ KC_TRNS
+#define XXXXXXX KC_NO
diff --git a/keyboards/planck/keymaps/sean/readme.md b/keyboards/planck/keymaps/sean/readme.md
new file mode 100644
index 0000000000..ac39d185ff
--- /dev/null
+++ b/keyboards/planck/keymaps/sean/readme.md
@@ -0,0 +1,130 @@
+# Sean Hunter's Planck Layout
+
+## Main layout
+
+Inspired by my old typematrix dvorak keyboard, with escape, tab, enter and
+backspace in the middle.  
+
+```
+ ,-----------------------------------------------------------------------------------.
+ |   "  |   ,  |   .  |   P  |   Y  |   /  |   =  |   F  |   G  |   C  |   R  |   L  |
+ |------+------+------+------+------+------+------+------+------+------+------+------|
+ |   A  |   O  |   E  |   U  |   I  | ESC  | BSPC |   D  |   H  |   T  |   N  |   S  |
+ |------+------+------+------+------+------+------+------+------+------+------+------|
+ |   ;  |   Q  |   J  |   K  |   X  | TAB  | ENT  |   B  |   M  |   W  |   V  |   Z  |
+ |------+------+------+------+------+------+------+------+------+------+------+------|
+ | Sft  | Ctl  | Alt  | Gui  |Lower |    Space    |Raise |   <  |   v  |   ^  |   >  |
+ `-----------------------------------------------------------------------------------'
+ ```
+
+## Lower
+
+With Lower, the numbers are on the home row.  Brackets and braces are down the
+centre of the keyboard when holding lower, and most other special characters,
+can be found on the row below home.  One row up are the main function keys.
+The arrow keys become `Home`, `End` and `Page Up` and `Page Down`.
+
+ ```
+ ,-----------------------------------------------------------------------------------.
+ | F1   |  F2  |  F3  |  F4  |  F5  |  {   |  }   |  F6  |  F7  |  F8  |  F9  | F10  | 
+ |------+------+------+------+------+-------------+------+------+------+------+------|
+ |  1   |   2  |   3  |   4  |   5  |  [   |  ]   |   6  |   7  |   8  |   9  |  0   |
+ |------+------+------+------+------+------|------+------+------+------+------+------|
+ |   ~  |   |  |   `  |   -  |   _  | INS  | DEL  |   (  |   )  |   +  |   =  |  \   |
+ |------+------+------+------+------+------+------+------+------+------+------+------|
+ | Sft  | Ctl  | Alt  | Gui  |Lower |             |Raise | Home | PgDn | PgUp | End  |
+ `-----------------------------------------------------------------------------------'
+```
+
+## Raise
+
+With Raise, the middle row functions as though we are holding shift and typing
+numbers.  This makes it a little easier than trying to hold lower and shift at
+the same time.  The row below home is a set of keys mapped from `Gui-1` to
+`Gui-0`.  I use these to change virtual desktops on [i3](https://i3wm.org/).  I
+also include 'right' versions of the modifier keys on here.
+
+
+ ```
+ ,-----------------------------------------------------------------------------------.
+ | F11  |  F12 |  F13 |  F14 |  F15 |      |      |  F16 |  F17 |  F18 |  F19 | F20  | 
+ |------+------+------+------+------+-------------+------+------+------+------+------|
+ |  !   |   @  |   #  |   $  |   %  |Sleep | Wake |   ^  |   &  |   *  |   (  |  )   |
+ |------+------+------+------+------+-------------+------+------+------+------+------|
+ | GUI1 | GUI2 | GUI3 | GUI4 | GUI5 |      |      | GUI6 | GUI7 | GUI8 | GUI9 |GUI10 |
+ |------+------+------+------+------+------+------+------+------+------+------+------|
+ | Sft  | Ctl  | Alt  | Gui  |Lower |             |Raise | Gui  | Alt  | Ctl  | Sft  |
+ `-----------------------------------------------------------------------------------'
+
+```
+
+## Adjust
+
+Raise and lower at the same time give an adjustment layer, which allows
+changing to the numpad and movement layer, and adjusting the backlights
+(assuming you have them - I don't yet).  I have also added various media keys
+and the all-important `Reset` key for programming the keyboard.  I've got the
+ability to swap `Alt` and `Gui` in hardware and three special keys set up for
+[hammerspoon]( http://www.hammerspoon.org/) on mac.  If I ever start using this
+keyboard seriously on mac again (I'm using it mainly on Windows and Linux atm)
+I'll write a special Mac mode and redo all my hammerspoon config to be more
+like i3 on Linux.
+
+```
+ Adjust (Lower + Raise)
+ ,-----------------------------------------------------------------------------------.
+ |      | Reset|      |      |      |AGnorm|AGswap|      |      |HRevl |HReset|HMenu |
+ |------+------+------+------+------+-------------+------+------+------+------+------|
+ | PWR  | EJCT | CUT  | COPY |PASTE |PrScr |SysReq| CAPS | <<   |  >>  | Mute | Stop |
+ |------+------+------+------+------+------|------+------+------+------+------+------|
+ |DVORAK|NUMPAD| MVMT | SDRK |      |      |      |      | Next | Vol- | Vol+ | Play |
+ |------+------+------+------+------+------+------+------+------+------+------+------|
+ |Brite |BToggl|      |      |             |      |      | Gui  | Alt  | Ctl  | Sft  |
+ `-----------------------------------------------------------------------------------'
+```
+
+## Numpad                                                                                                             
+
+I have added a numpad, although this is a little annoying at the moment as you
+have to first press `NumLock` to use.  I guess I could make a macro so as soon as
+you go into numpad mode it turns `NumLock` on.
+
+```
+ ,-----------------------------------------------------------------------------------.
+ |      |      |      |      |      |      |      |NumLck|   7  |   8  |   9  |   /  |
+ |------+------+------+------+------+------+------+------+------+------+------+------|
+ |      |      |      |      |      |      |      |Enter |   4  |   5  |   6  |   *  |
+ |------+------+------+------+------+------+------+------+------+------+------+------|
+ |DVORAK|NUMPAD| MVMT | SDRK |      |      |      |      |   3  |   2  |   1  |   -  |
+ |------+------+------+------+------+-------------+------+------+------+------+------|
+ |      |      |      |      |      |             |      |      |   0  |   .  |   +  |
+ `-----------------------------------------------------------------------------------'
+```
+
+## Movement
+
+I have added a movement layer but at present I seldom use it.
+
+```
+ ,-----------------------------------------------------------------------------------.
+ |MsBut2|MsWhDn|MsWhUp|MsBut1|MsBut3|      |      |      | Home | PgDn | PgUp |  End |
+ +------+------+------+------+------+------+------+------+------+------+------+------+
+ |Ms Lft|Ms Dn |Ms Up |Ms Rht|      |      |      |      | Left | Down |  Up  | Right|
+ |------+------+------+------+------+------+------+------+------+------+------+------|
+ |DVORAK|NUMPAD| MVMT | SDRK |      |      |      |      |      |      |      |      |
+ |------+------+------+------+------+-------------+------+------+------+------+------|
+ | Sft  | Ctl  | Alt  | Gui  |      |             |      | Gui  | Alt  | Ctl  | Sft  |
+ `-----------------------------------------------------------------------------------'
+```
+
+## Software Dvorak mode
+
+I have implemented a version of the main, lower and raise maps that works if
+the computer itself is in dvorak mode at the os level.  This allows me to work
+well on my laptop when I have to take it with me (eg to go to a meeting) and
+don't want the keyboard with me.  I simply set it in dvorak mode in the os and
+then put the keyboard into this mode.
+
+## TODO
+
+1. Actually learn to use the media keys