[Keyboard] Add splitkb.com's Aurora Sweep (#18691)

7 files changed, 410 insertions, 0 deletions

diff --git a/keyboards/splitkb/aurora/sweep/keymaps/debug/config.h b/keyboards/splitkb/aurora/sweep/keymaps/debug/config.h
new file mode 100644
index 0000000000..9e639dbc35
--- /dev/null
+++ b/keyboards/splitkb/aurora/sweep/keymaps/debug/config.h
@@ -0,0 +1,21 @@
+/* Copyright 2022 splitkb.com <support@splitkb.com>
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#pragma once
+
+#ifdef RGBLIGHT_ENABLE
+#   define RGBLIGHT_EFFECT_BREATHING
+#endif
diff --git a/keyboards/splitkb/aurora/sweep/keymaps/debug/keymap.c b/keyboards/splitkb/aurora/sweep/keymaps/debug/keymap.c
new file mode 100644
index 0000000000..5bdc5f2b42
--- /dev/null
+++ b/keyboards/splitkb/aurora/sweep/keymaps/debug/keymap.c
@@ -0,0 +1,77 @@
+/* Copyright 2022 splitkb.com <support@splitkb.com>
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#include QMK_KEYBOARD_H
+
+enum layers {
+    _DEFAULT = 0,
+};
+
+const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
+    [_DEFAULT] = LAYOUT(
+        KC_A, KC_B, KC_C, KC_D, KC_E,     S(KC_E), S(KC_D), S(KC_C), S(KC_B), S(KC_A),
+        KC_F, KC_G, KC_H, KC_I, KC_J,     S(KC_J), S(KC_I), S(KC_H), S(KC_G), S(KC_F),
+        KC_K, KC_L, KC_M, KC_N, KC_O,     S(KC_O), S(KC_N), S(KC_M), S(KC_L), S(KC_K),
+                          KC_P, KC_Q,     S(KC_Q), S(KC_P)
+    )
+};
+
+#ifdef RGBLIGHT_ENABLE
+void keyboard_post_init_user(void) {
+  rgblight_enable_noeeprom(); // enables RGB, without saving settings
+  rgblight_sethsv_noeeprom(HSV_RED); // sets the color to red without saving
+  rgblight_mode_noeeprom(RGBLIGHT_MODE_BREATHING + 3); // sets mode to Fast breathing without saving
+}
+#endif
+
+#ifdef ENCODER_ENABLE
+bool encoder_update_user(uint8_t index, bool clockwise) {
+    // 0 and 1 are left-half encoders
+    // 2 and 3 are right-half encoders
+    if (index == 0) {
+        tap_code(KC_0);
+    } else if (index == 1) {
+        tap_code(KC_1);
+    } else if (index == 2) {
+        tap_code(KC_2);
+    } else if (index == 3) {
+        tap_code(KC_3);
+    }
+
+    if (clockwise) {
+        tap_code16(KC_PLUS);
+    } else {
+        tap_code(KC_MINUS);
+    }
+
+    return false;
+}
+#endif
+
+#ifdef OLED_ENABLE
+bool oled_task_user(void) {
+    // A 128x32 OLED rotated 90 degrees is 5 characters wide and 16 characters tall
+    // This example string should fill that neatly
+    const char *text = PSTR("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ123456789!@#$%^&*()[]{}-=_+?");
+
+    if (is_keyboard_master()) {
+        oled_write_P(text, false);
+    } else {
+        oled_write_P(text, false);
+    }
+    return false;
+}
+#endif
diff --git a/keyboards/splitkb/aurora/sweep/keymaps/debug/readme.md b/keyboards/splitkb/aurora/sweep/keymaps/debug/readme.md
new file mode 100644
index 0000000000..6d4d5aaff6
--- /dev/null
+++ b/keyboards/splitkb/aurora/sweep/keymaps/debug/readme.md
@@ -0,0 +1,25 @@
+# Aurora Sweep's Debug Keymap
+
+Due to the complex layer setup, the default keymap for the Aurora Sweep is relatively hard to debug.
+This debug keymap should make that a lot easier.
+
+## Keys
+
+![Keys](https://raw.githubusercontent.com/splitkb/qmk_firmware/assets/aurora/sweep/keymaps/debug/keys.png)
+
+The left side uses lowercase letters, the right side uses uppercase ones.
+
+## Encoders
+
+Encoders output a number of 0 to 3, depending on the installed position.
+These correspond to the index used for custom encoder code.
+
+The number is followed by either a `+` or a `-`, depending on the direction turned.
+
+## LEDs
+
+Both underglow and per-key RGB should be fading between red and off.
+
+## OLEDs
+
+Both the primary and secondary side should be filled with characters.
diff --git a/keyboards/splitkb/aurora/sweep/keymaps/debug/rules.mk b/keyboards/splitkb/aurora/sweep/keymaps/debug/rules.mk
new file mode 100644
index 0000000000..066675cb48
--- /dev/null
+++ b/keyboards/splitkb/aurora/sweep/keymaps/debug/rules.mk
@@ -0,0 +1,18 @@
+# Copyright 2022 splitkb.com <support@splitkb.com>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+ENCODER_ENABLE = yes
+OLED_ENABLE = yes
+RGBLIGHT_ENABLE = yes
diff --git a/keyboards/splitkb/aurora/sweep/keymaps/default/config.h b/keyboards/splitkb/aurora/sweep/keymaps/default/config.h
new file mode 100644
index 0000000000..b35ec79511
--- /dev/null
+++ b/keyboards/splitkb/aurora/sweep/keymaps/default/config.h
@@ -0,0 +1,34 @@
+/* Copyright 2022 splitkb.com <support@splitkb.com>
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#pragma once
+
+// Not yet available in `keymap.json` format
+#ifdef RGB_MATRIX_ENABLE
+#    define RGB_DISABLE_WHEN_USB_SUSPENDED
+#    define RGB_MATRIX_KEYPRESSES
+#    define ENABLE_RGB_MATRIX_SOLID_REACTIVE_SIMPLE
+#    define ENABLE_RGB_MATRIX_SOLID_SPLASH
+#    define ENABLE_RGB_MATRIX_RAINBOW_BEACON 
+#endif
+
+// Not yet available in `keymap.json` format
+#ifdef MOUSEKEY_ENABLE
+     // The default is 100
+#    define MOUSEKEY_WHEEL_INTERVAL 50
+     // The default is 40
+#    define MOUSEKEY_WHEEL_TIME_TO_MAX 100
+#endif
\ No newline at end of file
diff --git a/keyboards/splitkb/aurora/sweep/keymaps/default/keymap.json b/keyboards/splitkb/aurora/sweep/keymaps/default/keymap.json
new file mode 100644
index 0000000000..0af1244c1f
--- /dev/null
+++ b/keyboards/splitkb/aurora/sweep/keymaps/default/keymap.json
@@ -0,0 +1,93 @@
+{
+    "keyboard": "splitkb/aurora/sweep",
+    "keymap": "default",
+    "version": 1,
+    "layout": "LAYOUT",
+    "layers": [
+        [
+            "KC_Q"        , "KC_W"        , "KC_E"           , "KC_R"          , "KC_T"          , "KC_Y"          , "KC_U"        , "KC_I"           , "KC_O"          , "KC_P",
+            "LSFT_T(KC_A)", "LT(5,KC_S)"  , "LT(1,KC_D)"     , "LT(3,KC_F)"    , "KC_G"          , "KC_H"          , "LT(4,KC_J)"  , "LT(2,KC_K)"     , "LT(6,KC_L)"    , "LSFT_T(KC_SCLN)",
+            "KC_Z"        , "LCTL_T(KC_X)", "LALT_T(KC_C)"   , "KC_V"          , "KC_B"          , "KC_N"          , "KC_M"        , "LALT_T(KC_COMM)", "LCTL_T(KC_DOT)", "KC_SLSH",
+                                                               "KC_P0"         , "KC_BSPC"       , "LT(7,KC_SPC)"  , "KC_P1"
+        ],
+        [
+            "RGB_TOG"     , "RGB_MOD"     , "RGB_HUI"        , "RGB_SAI"       , "RGB_VAI"       , "RGB_SPI"       , "KC_BTN1"     , "KC_WH_U"        , "KC_BTN2"       , "KC_TRNS",
+            "KC_TRNS"     , "KC_BTN2"     , "KC_NO"          , "KC_BTN1"       , "KC_TRNS"       , "KC_TRNS"       , "KC_MS_L"     , "KC_MS_D"        , "KC_MS_U"       , "KC_MS_R",
+            "KC_TRNS"     , "RGB_RMOD"    , "RGB_HUD"        , "RGB_SAD"       , "RGB_VAD"       , "RGB_SPD"       , "KC_WH_L"     , "KC_WH_D"        , "KC_WH_R"       , "KC_TRNS",
+                                                               "KC_TRNS"       , "KC_TRNS"       , "KC_TRNS"       , "KC_TRNS"
+        ],
+        [
+            "KC_TRNS"     , "KC_TRNS"     , "KC_PGUP"        , "KC_TRNS"       , "KC_TRNS"       , "KC_TRNS"       , "KC_TRNS"     , "KC_TRNS"        , "KC_TRNS"       , "KC_TRNS",
+            "KC_LEFT"     , "KC_UP"       , "KC_DOWN"        , "KC_RGHT"       , "KC_TRNS"       , "KC_TRNS"       , "KC_LGUI"     , "KC_NO"          , "LCTL(KC_LALT)" , "LCA(KC_LSFT)",
+            "KC_TRNS"     , "KC_HOME"     , "KC_PGDN"        , "KC_END"        , "KC_TRNS"       , "KC_TRNS"       , "KC_TRNS"     , "KC_TRNS"        , "KC_TRNS"       , "KC_TRNS",
+                                                               "KC_TRNS"       , "KC_TRNS"       , "KC_TRNS"       , "KC_TRNS"
+        ],
+        [
+            "KC_TRNS"     , "KC_TRNS"     , "KC_TRNS"        , "KC_TRNS"       , "KC_TRNS"       , "KC_TRNS"       , "KC_UNDS"     , "KC_PIPE"        , "KC_QUOT"       , "KC_TRNS",
+            "KC_CIRC"     , "KC_ASTR"     , "KC_AMPR"        , "KC_NO"         , "KC_TRNS"       , "KC_HASH"       , "KC_TILD"     , "KC_SLSH"        , "KC_DQUO"       , "KC_DLR",
+            "KC_TRNS"     , "KC_TRNS"     , "KC_TRNS"        , "KC_TRNS"       , "KC_TRNS"       , "KC_TRNS"       , "KC_MINS"     , "KC_BSLS"        , "KC_GRV"        , "KC_TRNS",
+                                                               "RGB_RMOD"      , "KC_TRNS"       , "KC_TRNS"       , "RGB_MOD"
+        ],
+        [
+            "KC_TRNS"     , "KC_COLN"     , "KC_LT"          , "KC_GT"         , "KC_SCLN"       , "KC_TRNS"       , "KC_TRNS"     , "KC_TRNS"        , "KC_TRNS"       , "KC_TRNS",
+            "KC_LCBR"     , "KC_RCBR"     , "KC_LPRN"        , "KC_RPRN"       , "KC_AT"         , "KC_TRNS"       , "KC_NO"       , "KC_EQL"         , "KC_PLUS"       , "KC_PERC",
+            "KC_TRNS"     , "KC_EXLM"     , "KC_LBRC"        , "KC_RBRC"       , "KC_TRNS"       , "KC_TRNS"       , "KC_TRNS"     , "KC_TRNS"        , "KC_TRNS"       , "KC_TRNS",
+                                                               "KC_VOLD"       , "KC_TRNS"       , "KC_TRNS"       , "KC_VOLU"
+        ],
+        [
+            "KC_TRNS"     , "KC_TRNS"     , "KC_TRNS"        , "KC_TRNS"       , "KC_TRNS"       , "KC_TRNS"       , "KC_F7"       , "KC_F8"          , "KC_F9"         , "KC_F10",
+            "KC_TRNS"     , "KC_NO"       , "LCTL(KC_LALT)"  , "KC_TRNS"       , "KC_TRNS"       , "KC_TRNS"       , "KC_F4"       , "KC_F5"          , "KC_F6"         , "KC_F11",
+            "KC_TRNS"     , "KC_TRNS"     , "KC_TRNS"        , "KC_TRNS"       , "KC_TRNS"       , "KC_TRNS"       , "KC_F1"       , "KC_F2"          , "KC_F3"         , "KC_F12",
+                                                               "KC_TRNS"       , "KC_TRNS"       , "KC_TRNS"       , "KC_TRNS"
+        ],
+        [
+            "KC_PSLS"     , "KC_7"        , "KC_8"           , "KC_9"          , "KC_PPLS"       , "KC_TRNS"       , "KC_TRNS"     , "KC_TRNS"        , "KC_TRNS"       , "KC_TRNS",
+            "KC_0"        , "KC_1"        , "KC_2"           , "KC_3"          , "KC_PMNS"       , "KC_TRNS"       , "KC_TRNS"     , "KC_TRNS"        , "KC_NO"         , "KC_TRNS",
+            "KC_PAST"     , "KC_4"        , "KC_5"           , "KC_6"          , "KC_PEQL"       , "KC_TRNS"       , "KC_TRNS"     , "KC_TRNS"        , "KC_TRNS"       , "KC_TRNS",
+                                                               "KC_TRNS"       , "KC_TRNS"       , "KC_TRNS"       , "KC_TRNS"
+        ],
+        [
+            "KC_TRNS"     , "KC_TRNS"     , "KC_COLN"        , "KC_ESC"        , "KC_TRNS"       , "KC_TRNS"       , "KC_TRNS"     , "KC_TRNS"        , "KC_TRNS"       , "KC_DEL",
+            "KC_TRNS"     , "KC_PERC"     , "KC_SLSH"        , "KC_ENT"        , "KC_TRNS"       , "DF(1)"         , "KC_LGUI"     , "KC_TRNS"        , "KC_TRNS"       , "KC_TRNS",
+            "KC_TRNS"     , "KC_TRNS"     , "KC_TRNS"        , "KC_EXLM"       , "KC_TRNS"       , "DF(0)"         , "KC_TRNS"     , "RALT_T(KC_COMM)", "RCTL_T(KC_DOT)", "QK_BOOT",
+                                                               "KC_TRNS"       , "KC_TAB"        , "KC_NO"         , "KC_TRNS"
+        ]
+    ],
+    "config": {
+        "features": {
+            "oled": true,
+            "rgb_matrix": true,
+            "rgblight": false
+        },
+        "encoder": {
+            "enabled": true
+        },
+        "rgblight": {
+            "hue_steps": 8,
+            "saturation_steps": 8,
+            "brightness_steps": 8,
+            "sleep": true
+        }
+    },
+    "mouse_key": {
+        "enabled": true,
+        // Set the mouse settings to a comfortable speed/accuracy trade-off,
+        // assuming a screen refresh rate of 60 Htz or higher
+        // The default is 50. This makes the mouse ~3 times faster and more accurate
+        "interval": 16,
+        // The default is 20. Since we made the mouse about 3 times faster with the previous setting,
+        // give it more time to accelerate to max speed to retain precise control over short distances.
+        "time_to_max": 40,
+        // The default is 300. Let's try and make this as low as possible while keeping the cursor responsive
+        "delay": 100,
+        // It makes sense to use the same delay for the mouseweel
+        "wheel_delay": 100
+    },
+    // Pick good defaults for enabling homerow modifiers
+    "tapping": {
+        "term": 200,
+        "permissive_hold": true,
+        "ignore_mod_tap_interrupt": true,
+        "force_hold": true
+    }
+}
diff --git a/keyboards/splitkb/aurora/sweep/keymaps/default/readme.md b/keyboards/splitkb/aurora/sweep/keymaps/default/readme.md
new file mode 100644
index 0000000000..535580f9a7
--- /dev/null
+++ b/keyboards/splitkb/aurora/sweep/keymaps/default/readme.md
@@ -0,0 +1,142 @@
+# Aurora Sweep's Default Keymap
+_This keymap is a copy of the [Ferris default keymap](https://github.com/qmk/qmk_firmware/tree/master/keyboards/ferris/keymaps/default), with the addition of RGB modifier keys._
+
+A usable default keymap for the Ferris keyboard
+===============================================
+
+Keymaps in general are quite personal, so it is difficult to come up with a default that will suit every user.
+
+This keymap makes heavy use of keys behaving differently when tapped and held, so that all the keys one may need remain accessible despite the low number of thumb keys.
+
+It comes with a number of layers to give access to most of the keys one may need on a keyboard. It is not meant to be the best possible keymap, but rather a good base on which to build a keymap that works for you.
+
+This is not the only way to make 34 keys a comfortable typing experience, but it is one way to do so. If you don't already know of a better way, this may be as good a starting point as any :)
+
+Note that this keymap was built from the perspective that it is OK to take a steep learning curve if it results in a keymap that is easier to use in the long run. This means that it may take more effort to learn this keymap than some alternatives. "Easy to use" was assessed against the workflow of the author, so your mileage may vary on some of the details.
+
+What do all these layers do?
+----------------------------
+
+### Layer 0: Base layer
+
+![Layer 0](https://raw.githubusercontent.com/splitkb/qmk_firmware/assets/aurora/sweep/keymaps/default/layer0.png)
+
+On tapping the keys, our base layer is qwerty with space on the right homing thumb and backspace on the left homing thumb.
+
+In this layer, the non-homing-thumb positions have 0 and 1. I recommend modifying this to some frequently accessed shortcut such as copy/paste, previous/next tab or anything that makes most sense in your own workflow. O and 1 are place-holders and make it easy to troubleshoot that all keys are working properly before soldering in the switches.
+The reason I recommend convenience shortcuts instead of more commonly used keys like tab or meta is that unhoming of the thumbs was a frequent source of typos for me when I used more than one thumb key frequently in the context of typing.
+
+Despite being missing on this layer, "meta", "tab", "esc" and such are accessible from any other layer: see Layer 7.
+
+The behaviour of some keys differ when held:
+* Both homing pinkies behave as shift.
+* Both bottom-row ring fingers behave as ctrl.
+* Both bottom-row middle fingers behave as alt.
+
+* The homing left ring finger gives access to the Function keys layer
+* The homing right ring finger gives access to the Numbers layer
+* The homing left middle finger gives access to the Mouse layer
+* The homing right middle finger gives access to the Navigation layer
+* The homing left index finger gives access to the Right symbols layer
+* The homing right index finger gives access to the Left symbols layer
+* The homing right thumb gives access to the Always accessible layer
+
+### Layer 1: Mouse
+
+![Layer 1](https://raw.githubusercontent.com/splitkb/qmk_firmware/assets/aurora/sweep/keymaps/default/layer1.png)
+
+Layer 1 is a mouse layer: it can be used one-handed or two-handed. The most common way to use it is two handed, with left and right click on the homerow of the left hand and directions on the homerow of the right hand.
+Scrolling is available on the right hand with mid finger up and down for vertical scroll and index and ring finger down for horizontal scroll.
+On the right hand, left click and right click are also available with index and ring finger up to allow one handed operation. This can be particularly handy when enabling the mouse layer permanently (no need to hold the left middle finger), which can be done from Layer 7.
+
+**Addition**: The Aurora Sweep allows the RGB settings to be modified on this layer. This is an extra feature over the default Ferris / Sweep keymap.
+
+### Layer 2: Navigation
+
+![Layer 2](https://raw.githubusercontent.com/splitkb/qmk_firmware/assets/aurora/sweep/keymaps/default/layer2.png)
+
+The navigation layer somewhat mirrors the mouse layer. It is accessed by holding the right middle finger and gives access to arrow keys on the left homerow. Page up and down, Home and End mirror the vertical scrolling and horizontal scrolling on the mouse layer.
+
+On the right hand, in addition to ctrl and alt which are available through transparency, ctrl + alt, ctrl + alt + shift and meta are accessible on the homerow to enable common shortcuts in some window managers. This part is quite workflow dependent, so make sure to adapt it to your own workflow as appropriate.
+
+### Layer 3: Right symbols
+
+![Layer 3](https://raw.githubusercontent.com/splitkb/qmk_firmware/assets/aurora/sweep/keymaps/default/layer3.png)
+
+When holding down the left index, one may access about half of the symbols. The pinkies store `^` and `$` symbols that represent begin and end in vim. The left homerow hosts `*` and `&`, symbols which are related in the way that they represent some form of indirection in programming languages such as rust. On the right hand, most symbols used when navigating the command line are stored together, organized by columns of related symbols. 
+
+### Layer 4: Left symbols
+
+![Layer 4](https://raw.githubusercontent.com/splitkb/qmk_firmware/assets/aurora/sweep/keymaps/default/layer4.png)
+
+When holding down the right index, one may access the other symbols. On the left hand, most of the different brackets are laid out. The most frequent ones (round brackets and curly brackets) get a spot on the homerow. The rest of the layer hosts the remaining symbols that are easier to access here than on any other layers.
+
+### Layer 5: Function keys
+
+![Layer 5](https://raw.githubusercontent.com/splitkb/qmk_firmware/assets/aurora/sweep/keymaps/default/layer5.png)
+
+By holding down the left ring finger, one may access the function keys, roughly in a numpad layout.
+This means that alt+F4 is easy to type, with F4 being on the homerow.
+There is a shortcut for ctrl+alt on the left hand to enable convenient switching between virtual terminals on Linux.
+
+### Layer 6: Numbers
+
+![Layer 6](https://raw.githubusercontent.com/splitkb/qmk_firmware/assets/aurora/sweep/keymaps/default/layer6.png)
+
+The number layer is accessed by holding the right ring finger. It hosts the numbers and some duplicated symbols that are commonly accessed next to numbers, such as mathematical operators.
+The number are layed out similarly to a numpad, but with the middle row and the homerow swapped so that the most used numbers: 0, 1, 2 and 3 are all available in homing positions. 
+
+### Layer 7: Always accessible
+
+![Layer 7](https://raw.githubusercontent.com/splitkb/qmk_firmware/assets/aurora/sweep/keymaps/default/layer7.png)
+
+Layer 7 is accessed by holding the right homing thumb down. Because this position is left transparent from every other layer, this layer is always accessible.
+It gives access to some essential keys that would typically be accessed on a thumb cluster or pinkies, such as meta, enter, tab, esc and delete.
+
+As the layer hosting esc, we duplicated some symbols here to allow for fast navigation in vim. For instance, esc, :, w, q can be done in a single roll.
+
+Where is the keymap.c?
+----------------------
+
+The keymap.c file is not published to the repository. It is generated from `keymap.json` by the build system.
+
+This avoids duplicating information and allow users to edit their keymap from the qmk configurator web interface.
+
+How do I edit and update the keymap?
+------------------------------------
+
+The `keymap.json` file is generated from the qmk configurator interface and formatted for better readability in the context of the Ferris keyboard.
+
+To edit it, you may:
+* Edit it directly from a text editor.
+* Edit it from the qmk configurator.
+
+If you decide to use the latter workflow, here are the steps to follow:
+
+* From the qmk configurator, hit the "import QMK keymap json file" button (it has a drawing with an up arrow on it).
+* Browse to the location of your keymap (for example, `<your qmk repo>/keyboards/splitkb/aurora/sweep/keymaps/default/keymap.json`)
+* Perform any modification to the keymap in the web UI
+* Export the keymap to your downloads folder, by hitting the "Export QMK keymap json file" button (it has a drawing with a down arrow on it)
+* Replace your original keymap with the one you just downloaded
+
+I want to do more than the configurator supports!
+-------------------------------------------------
+
+While the `json` format is easy to use, it does lack certain functionality - most notably custom OLED or encoder behaviour.
+
+To add this, you need to convert it to the `c` format. Do keep in mind that this is generally a one-way operation.
+
+First, from the root of your qmk repo, move to your keymap folder
+
+```bash
+cd ./keymaps/splitkb/aurora/corne/my_personal_keymap
+```
+
+Next, convert your `keymap.json` to a `keymap.c`
+
+```bash
+qmk json2c -o keymap.c keymap.json
+```
+
+You can add custom C code to the newly generated `keymap.c` file. Do note that you have to use **either** a C file **or** a JSON file - you cannot do both!  
+**If a JSON file is present, the C file is ignored.**