Remove build option firmware size impacts (#6947)

* Update rules.mk template to remove build option size impacts

* Add rules.mk cleaning script

* Update all rules.mk files to remove build option firmware size impact messages

* Remove references to feature filesize in documentation

* Revert "Update all rules.mk files to remove build option firmware size impact messages"

This reverts commit 7cfe70976bcc223bf47c960b2e6af8596df80a32.

* Fix regex in cleanup script and exclude keymaps/ directories

* Update quantum/template/avr/rules.mk

Fixed missing tabs/spaces.

Co-Authored-By: fauxpark <fauxpark@gmail.com>

.clang-format

@@ -1,4 +1,4 @@
----
+---
 BasedOnStyle: Google
 AlignAfterOpenBracket: Align
 AlignConsecutiveAssignments: 'true'

.clang_complete

@@ -0,0 +1,24 @@
+
+-I.
+-I./drivers
+-I./drivers/avr
+-I./keyboards/ergodox_ez
+-I./keyboards/ergodox_ez/keymaps/vim
+-I./lib
+-I./lib/lufa
+-I./quantum
+-I./quantum/api
+-I./quantum/audio
+-I./quantum/keymap_extras
+-I./quantum/process_keycode
+-I./quantum/serial_link
+-I./quantum/template
+-I./quantum/tools
+-I./quantum/visualizer
+-I./tmk_core
+-I./tmk_core/common
+-I./tmk_core/common/debug.h
+-I./tmk_core/protocol
+-I./tmk_core/protocol/lufa
+-I./util
+-DQMK_KEYBOARD=\"$(KEYBOARD)\" -DQMK_KEYMAP=\"$(KEYMAP)\"

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,34 @@
+<!--- Provide a general summary of your changes in the title above. -->
+
+<!--- This template is entirely optional and can be removed, but is here to help both you and us. -->
+<!--- Anything on lines wrapped in comments like these will not show up in the final text. -->
+
+## Description
+
+<!--- Describe your changes in detail here. -->
+
+## Types of Changes
+
+<!--- What types of changes does your code introduce? Put an `x` in all the boxes that apply. -->
+- [ ] Core
+- [ ] Bugfix
+- [ ] New feature
+- [ ] Enhancement/optimization
+- [ ] Keyboard (addition or update)
+- [ ] Keymap/layout/userspace (addition or update)
+- [ ] Documentation
+
+## Issues Fixed or Closed by This PR
+
+* 
+
+## Checklist
+
+<!--- Go over all the following points, and put an `x` in all the boxes that apply. -->
+<!--- If you're unsure about any of these, don't hesitate to ask. We're here to help! -->
+- [ ] My code follows the code style of this project.
+- [ ] My change requires a change to the documentation.
+- [ ] I have updated the documentation accordingly.
+- [ ] I have read the [**CONTRIBUTING** document](https://docs.qmk.fm/#/contributing).
+- [ ] I have added tests to cover my changes.
+- [ ] I have tested the changes and verified that they work and don't break anything (as well as I can manage).

.gitignore

@@ -24,16 +24,20 @@ quantum/version.h
 .idea/
 CMakeLists.txt
 cmake-build-debug
-.clang_complete
 doxygen/
 .DS_Store
 /util/wsl_downloaded
 /util/win_downloaded
-/users/
-/layouts/
 /keyboards/*/Makefile
-!/keyboards/ergodox_ez/
-!/keyboards/planck/
+/keyboards/*/*/Makefile
+/keyboards/*/*/*/Makefile
+/keyboards/*/*/*/*/Makefile
+/keyboards/*/*/*/*/*/Makefile
+/keyboards/*/keymaps/Makefile
+/keyboards/*/*/keymaps/Makefile
+/keyboards/*/*/*/keymaps/Makefile
+/keyboards/*/*/*/*/keymaps/Makefile
+/keyboards/*/*/*/*/*/keymaps/Makefile
 
 # Eclipse/PyCharm/Other IDE Settings
 .cproject
@@ -43,12 +47,14 @@ doxygen/
 *.iml
 .browse.VC.db*
 *.stackdump
+util/Win_Check_Output.txt
 # Let these ones be user specific, since we have so many different configurations
 .vscode/c_cpp_properties.json
 .vscode/launch.json
 .vscode/tasks.json
 .vscode/last.sql
 .vscode/temp.sql
+.vscode/ipch/
 .stfolder
 .tags
 
@@ -57,6 +63,9 @@ doxygen/
 *.jpg
 *.gif
 
+# Do not ignore MiniDox left/right hand eeprom files
+!keyboards/minidox/*.eep
+
 # things travis sees
 secrets.tar
 id_rsa_*
@@ -64,9 +73,3 @@ id_rsa_*
 
 # python things
 __pycache__
-
-# prerequisites for updating ChibiOS
-/util/fmpp*
-
-# Allow to exist but don't include it in the repo
-user_song_list.h

.gitmodules

@@ -1,24 +1,16 @@
 [submodule "lib/chibios"]
 	path = lib/chibios
 	url = https://github.com/qmk/ChibiOS
-	branch = master
 [submodule "lib/chibios-contrib"]
 	path = lib/chibios-contrib
 	url = https://github.com/qmk/ChibiOS-Contrib
-	branch = master
+	branch = k-type-fix
 [submodule "lib/ugfx"]
 	path = lib/ugfx
 	url = https://github.com/qmk/uGFX
-	branch = master
 [submodule "lib/googletest"]
 	path = lib/googletest
-	url = https://github.com/qmk/googletest
+	url = https://github.com/google/googletest
 [submodule "lib/lufa"]
 	path = lib/lufa
-	url = https://github.com/zsa/lufa
-[submodule "lib/vusb"]
-	path = lib/vusb
-	url = https://github.com/qmk/v-usb
-[submodule "lib/printf"]
-	path = lib/printf
-	url = https://github.com/qmk/printf
+	url = https://github.com/qmk/lufa

.travis.yml

@@ -1,6 +1,5 @@
 os: linux
 dist: trusty
-sudo: required
 group: edge
 language: c
 branches:
@@ -19,6 +18,7 @@ script:
   - git rev-parse --short HEAD
   - bash util/travis_test.sh
   - bash util/travis_build.sh
+  - bash util/travis_docs.sh
 addons:
   apt:
     packages:
@@ -26,3 +26,12 @@ addons:
     - diffutils
     - dos2unix
     - doxygen
+after_script:
+  bash util/travis_compiled_push.sh
+notifications:
+  webhooks:
+    urls:
+      - https://webhooks.gitter.im/e/afce403d65f143dfac09
+    on_success: always  # options: [always|never|change] default: always
+    on_failure: always  # options: [always|never|change] default: always
+    on_start: never     # options: [always|never|change] default: always

.vscode/extensions.json

@@ -0,0 +1,11 @@
+// Suggested extensions
+{
+  "recommendations": [
+    "EditorConfig.EditorConfig",
+    "xaver.clang-format",
+    "ms-vscode.cpptools",
+    "bierner.github-markdown-preview",
+    "donjayamanne.git-extension-pack",
+    "CoenraadS.bracket-pair-colorizer-2"
+  ]
+}

.vscode/settings.json

@@ -0,0 +1,19 @@
+// Place your settings in this file to overwrite default and user settings.
+{
+    // Unofficially, QMK uses spaces for indentation
+    "editor.insertSpaces": true,
+    // Configure glob patterns for excluding files and folders.
+    "files.exclude": {
+        "**/.build": true,
+        "**/*.hex": true
+    },
+    "files.associations": {
+      "*.h": "c",
+      "*.c": "c",
+      "*.cpp": "cpp",
+      "*.hpp": "cpp",
+      "xstddef": "c",
+      "type_traits": "c",
+      "utility": "c"
+    }
+}

CODE_OF_CONDUCT.md

@@ -8,8 +8,17 @@ Our users, contributors, and collaborators are expected to treat each other with
 
 * The use of sexualized language or imagery
 * Unwelcome advances, sexual or otherwise
+* Deliberate intimidation, stalking, or following
 * Insults or derogatory comments, or personal or political attacks
 * Publishing others’ private information without explicit permission
+* Sustained disruption of talks or other events
 * Other conduct which could reasonably be considered inappropriate in a professional setting
+* Advocating for, or encouraging, any of the above behaviour
 
-If someone is violating this Code of Conduct you may email hello@qmk.fm to bring your concern to the Members. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. 
+# Reporting
+
+If someone is violating this Code of Conduct, please email hello@qmk.fm or reach out to one of the Collaborators to bring it to our attention. All complaints will be reviewed and investigated.
+
+QMK will seek to use the least punitive means available to resolve an issue. If the circumstances require asking an offender to leave, we will do that.
+
+Reports will be taken and kept in strict confidence. You will not be required to confront an offender directly.

Dockerfile

@@ -4,4 +4,4 @@ VOLUME /qmk_firmware
 WORKDIR /qmk_firmware
 COPY . .
 
-CMD make all:all
+CMD make all:default

Makefile

@@ -29,9 +29,6 @@ $(info QMK Firmware $(QMK_VERSION))
 endif
 endif
 
-# avoid 'Entering|Leaving directory' messages
-MAKEFLAGS += --no-print-directory
-
 ON_ERROR := error_occurred=1
 
 BREAK_ON_ERRORS = no
@@ -292,8 +289,8 @@ define PARSE_RULE
         $$(info |  QMK's make format recently changed to use folder locations and colons:)
         $$(info |     make project_folder:keymap[:target])
         $$(info |  Examples:)
-        $$(info |     make planck/ez:default:flash)
-        $$(info |     make planck/ez:default)
+        $$(info |     make planck/rev4:default:dfu)
+        $$(info |     make planck:default)
         $$(info |)
     endif
 endef
@@ -557,16 +554,14 @@ endef
 %:
 	# Check if we have the CMP tool installed
 	cmp $(ROOT_DIR)/Makefile $(ROOT_DIR)/Makefile >/dev/null 2>&1; if [ $$? -gt 0 ]; then printf "$(MSG_NO_CMP)"; exit 1; fi;
-	# Ensure that bin/qmk works. This will be a failing check after the next develop merge on 2020 Aug 29.
-	if ! bin/qmk hello 1> /dev/null 2>&1; then printf "$(MSG_PYTHON_MISSING)"; fi
+	# Ensure that python3 is installed. This check can be removed after python is used in more places.
+	if ! python3 --version 1> /dev/null 2>&1; then printf "$(MSG_PYTHON_MISSING)"; fi
 	# Check if the submodules are dirty, and display a warning if they are
 ifndef SKIP_GIT
-	if [ ! -e lib/chibios ]; then git submodule sync lib/chibios && git submodule update --depth 50 --init lib/chibios; fi
-	if [ ! -e lib/chibios-contrib ]; then git submodule sync lib/chibios-contrib && git submodule update --depth 50 --init lib/chibios-contrib; fi
-	if [ ! -e lib/ugfx ]; then git submodule sync lib/ugfx && git submodule update --depth 50 --init lib/ugfx; fi
-	if [ ! -e lib/lufa ]; then git submodule sync lib/lufa && git submodule update --depth 50 --init lib/lufa; fi
-	if [ ! -e lib/vusb ]; then git submodule sync lib/vusb && git submodule update --depth 50 --init lib/vusb; fi
-	if [ ! -e lib/printf ]; then git submodule sync lib/printf && git submodule update --depth 50 --init lib/printf; fi
+	if [ ! -e lib/chibios ]; then git submodule sync lib/chibios && git submodule update --depth 1 --init lib/chibios; fi
+	if [ ! -e lib/chibios-contrib ]; then git submodule sync lib/chibios-contrib && git submodule update --depth 1 --init lib/chibios-contrib; fi
+	if [ ! -e lib/ugfx ]; then git submodule sync lib/ugfx && git submodule update --depth 1 --init lib/ugfx; fi
+	if [ ! -e lib/lufa ]; then git submodule sync lib/lufa && git submodule update --depth 1 --init lib/lufa; fi
 	git submodule status --recursive 2>/dev/null | \
 	while IFS= read -r x; do \
 		case "$$x" in \
@@ -623,19 +618,13 @@ endif
 # Generate the version.h file
 ifndef SKIP_GIT
     GIT_VERSION := $(shell git describe --abbrev=6 --dirty --always --tags 2>/dev/null || date +"%Y-%m-%d-%H:%M:%S")
-    CHIBIOS_VERSION := $(shell cd lib/chibios && git describe --abbrev=6 --dirty --always --tags 2>/dev/null || date +"%Y-%m-%d-%H:%M:%S")
-    CHIBIOS_CONTRIB_VERSION := $(shell cd lib/chibios-contrib && git describe --abbrev=6 --dirty --always --tags 2>/dev/null || date +"%Y-%m-%d-%H:%M:%S")
 else
     GIT_VERSION := NA
-    CHIBIOS_VERSION := NA
-    CHIBIOS_CONTRIB_VERSION := NA
 endif
 ifndef SKIP_VERSION
 BUILD_DATE := $(shell date +"%Y-%m-%d-%H:%M:%S")
 $(shell echo '#define QMK_VERSION "$(GIT_VERSION)"' > $(ROOT_DIR)/quantum/version.h)
 $(shell echo '#define QMK_BUILDDATE "$(BUILD_DATE)"' >> $(ROOT_DIR)/quantum/version.h)
-$(shell echo '#define CHIBIOS_VERSION "$(CHIBIOS_VERSION)"' >> $(ROOT_DIR)/quantum/version.h)
-$(shell echo '#define CHIBIOS_CONTRIB_VERSION "$(CHIBIOS_CONTRIB_VERSION)"' >> $(ROOT_DIR)/quantum/version.h)
 else
 BUILD_DATE := NA
 endif

Vagrantfile

@@ -7,6 +7,8 @@ Vagrant.configure(2) do |config|
 
   # VMware/Virtualbox ( and also Hyperv/Parallels) 64 bit
   config.vm.box = "generic/debian9"
+  
+  config.vm.synced_folder '.', '/vagrant'
 
   # This section allows you to customize the Virtualbox VM
   # settings, ie showing the GUI or upping the memory
@@ -86,8 +88,8 @@ Vagrant.configure(2) do |config|
      make <keyboard>:default
 
   Examples:
-     make planck/ez:default:flash
-     make planck/ez:default
+     make planck/rev4:default:dfu
+     make planck:default
 
   EOT
 end

bin/qmk

@@ -2,60 +2,46 @@
 """CLI wrapper for running QMK commands.
 """
 import os
+import subprocess
 import sys
 from importlib.util import find_spec
-from pathlib import Path
+from time import strftime
 
 # Add the QMK python libs to our path
-script_dir = Path(os.path.realpath(__file__)).parent
-qmk_dir = script_dir.parent
-python_lib_dir = Path(qmk_dir / 'lib' / 'python').resolve()
-sys.path.append(str(python_lib_dir))
+script_dir = os.path.dirname(os.path.realpath(__file__))
+qmk_dir = os.path.abspath(os.path.join(script_dir, '..'))
+python_lib_dir = os.path.abspath(os.path.join(qmk_dir, 'lib', 'python'))
+sys.path.append(python_lib_dir)
 
-
-def _check_modules(requirements):
-    """ Check if the modules in the given requirements.txt are available.
-    """
-    with Path(qmk_dir / requirements).open() as fd:
-        for line in fd.readlines():
-            line = line.strip().replace('<', '=').replace('>', '=')
-
-            if len(line) == 0 or line[0] == '#' or line.startswith('-r'):
-                continue
-
-            if '#' in line:
-                line = line.split('#')[0]
-
-            module = dict()
-            module['name'] = module['import'] = line.split('=')[0] if '=' in line else line
-
-            # Not every module is importable by its own name.
-            if module['name'] == "pep8-naming":
-                module['import'] = "pep8ext_naming"
-
-            if not find_spec(module['import']):
-                print('Could not find module %s!' % module['name'])
-                print('Please run `python3 -m pip install -r %s` to install required python dependencies.' % (qmk_dir / requirements,))
-                if developer:
-                    print('You can also turn off developer mode: qmk config user.developer=None')
-                print()
-                exit(255)
-
-
-developer = False
 # Make sure our modules have been setup
-_check_modules('requirements.txt')
+with open(os.path.join(qmk_dir, 'requirements.txt'), 'r') as fd:
+    for line in fd.readlines():
+        line = line.strip().replace('<', '=').replace('>', '=')
+
+        if line[0] == '#':
+            continue
+
+        if '#' in line:
+            line = line.split('#')[0]
+
+        module = line.split('=')[0] if '=' in line else line
+        if not find_spec(module):
+            print('Could not find module %s!', module)
+            print('Please run `pip3 install -r requirements.txt` to install the python dependencies.')
+            exit(255)
+
+# Figure out our version
+# TODO(skullydazed/anyone): Find a method that doesn't involve git. This is slow in docker and on windows.
+command = ['git', 'describe', '--abbrev=6', '--dirty', '--always', '--tags']
+result = subprocess.run(command, universal_newlines=True, stdout=subprocess.PIPE, stderr=subprocess.STDOUT)
+
+if result.returncode == 0:
+    os.environ['QMK_VERSION'] = result.stdout.strip()
+else:
+    os.environ['QMK_VERSION'] = 'nogit-' + strftime('%Y-%m-%d-%H:%M:%S') + '-dirty'
 
 # Setup the CLI
-import milc  # noqa
-
-# For developers additional modules are needed
-if milc.cli.config.user.developer:
-    # Do not run the check for 'config',
-    # so users can turn off developer mode
-    if len(sys.argv) == 1 or (len(sys.argv) > 1 and 'config' != sys.argv[1]):
-        developer = True
-        _check_modules('requirements-dev.txt')
+import milc
 
 milc.EMOJI_LOGLEVELS['INFO'] = '{fg_blue}Ψ{style_reset_all}'
 
@@ -75,7 +61,7 @@ def main():
     os.chdir(qmk_dir)
 
     # Import the subcommands
-    import qmk.cli  # noqa
+    import qmk.cli
 
     # Execute
     return_code = milc.cli()

bootloader.mk

@@ -82,13 +82,6 @@ ifeq ($(strip $(BOOTLOADER)), USBasp)
     OPT_DEFS += -DBOOTLOADER_USBASP
     BOOTLOADER_SIZE = 4096
 endif
-ifeq ($(strip $(BOOTLOADER)), lufa-ms)
-    # DO NOT USE THIS BOOTLOADER IN NEW PROJECTS!
-    # It is extremely prone to bricking, and is only included to support existing boards.
-    OPT_DEFS += -DBOOTLOADER_MS
-    BOOTLOADER_SIZE = 6144
-    FIRMWARE_FORMAT = bin
-endif
 
 ifdef BOOTLOADER_SIZE
     OPT_DEFS += -DBOOTLOADER_SIZE=$(strip $(BOOTLOADER_SIZE))

build_json.mk

@@ -21,11 +21,7 @@ else ifneq ("$(wildcard $(MAIN_KEYMAP_PATH_1)/keymap.json)","")
     KEYMAP_PATH := $(MAIN_KEYMAP_PATH_1)
 endif
 
-# Load the keymap-level rules.mk if exists
-ifneq ("$(wildcard $(KEYMAP_PATH))", "")
-    -include $(KEYMAP_PATH)/rules.mk
-endif
-
 # Generate the keymap.c
-$(KEYBOARD_OUTPUT)/src/keymap.c: $(KEYMAP_JSON)
-	bin/qmk json2c --quiet --output $(KEYMAP_C) $(KEYMAP_JSON)
+ifneq ("$(KEYMAP_JSON)","")
+    _ = $(shell test -e $(KEYMAP_C) || bin/qmk json-keymap $(KEYMAP_JSON) -o $(KEYMAP_C))
+endif

build_keyboard.mk

@@ -231,19 +231,44 @@ endif
 # We can assume a ChibiOS target When MCU_FAMILY is defined since it's
 # not used for LUFA
 ifdef MCU_FAMILY
-    PLATFORM=CHIBIOS
-    PLATFORM_KEY=chibios
     FIRMWARE_FORMAT?=bin
+    PLATFORM=CHIBIOS
 else ifdef ARM_ATSAM
     PLATFORM=ARM_ATSAM
-    PLATFORM_KEY=arm_atsam
     FIRMWARE_FORMAT=bin
 else
     PLATFORM=AVR
-    PLATFORM_KEY=avr
     FIRMWARE_FORMAT?=hex
 endif
 
+ifeq ($(PLATFORM),CHIBIOS)
+    include $(TMK_PATH)/chibios.mk
+    OPT_OS = chibios
+    ifneq ("$(wildcard $(KEYBOARD_PATH_5)/bootloader_defs.h)","")
+        OPT_DEFS += -include $(KEYBOARD_PATH_5)/bootloader_defs.h
+     else ifneq ("$(wildcard $(KEYBOARD_PATH_5)/boards/$(BOARD)/bootloader_defs.h)","")
+        OPT_DEFS += -include $(KEYBOARD_PATH_5)/boards/$(BOARD)/bootloader_defs.h
+    else ifneq ("$(wildcard $(KEYBOARD_PATH_4)/bootloader_defs.h)","")
+        OPT_DEFS += -include $(KEYBOARD_PATH_4)/bootloader_defs.h
+     else ifneq ("$(wildcard $(KEYBOARD_PATH_4)/boards/$(BOARD)/bootloader_defs.h)","")
+        OPT_DEFS += -include $(KEYBOARD_PATH_4)/boards/$(BOARD)/bootloader_defs.h
+    else ifneq ("$(wildcard $(KEYBOARD_PATH_3)/bootloader_defs.h)","")
+        OPT_DEFS += -include $(KEYBOARD_PATH_3)/bootloader_defs.h
+     else ifneq ("$(wildcard $(KEYBOARD_PATH_3)/boards/$(BOARD)/bootloader_defs.h)","")
+        OPT_DEFS += -include $(KEYBOARD_PATH_3)/boards/$(BOARD)/bootloader_defs.h
+    else ifneq ("$(wildcard $(KEYBOARD_PATH_2)/bootloader_defs.h)","")
+        OPT_DEFS += -include $(KEYBOARD_PATH_2)/bootloader_defs.h
+     else ifneq ("$(wildcard $(KEYBOARD_PATH_2)/boards/$(BOARD)/bootloader_defs.h)","")
+        OPT_DEFS += -include $(KEYBOARD_PATH_2)/boards/$(BOARD)/bootloader_defs.h
+    else ifneq ("$(wildcard $(KEYBOARD_PATH_1)/bootloader_defs.h)","")
+        OPT_DEFS += -include $(KEYBOARD_PATH_1)/bootloader_defs.h
+     else ifneq ("$(wildcard $(KEYBOARD_PATH_1)/boards/$(BOARD)/bootloader_defs.h)","")
+        OPT_DEFS += -include $(KEYBOARD_PATH_1)/boards/$(BOARD)/bootloader_defs.h
+    else ifneq ("$(wildcard $(TOP_DIR)/drivers/boards/$(BOARD)/bootloader_defs.h)","")
+        OPT_DEFS += -include $(TOP_DIR)/drivers/boards/$(BOARD)/bootloader_defs.h
+    endif
+endif
+
 # Find all of the config.h files and add them to our CONFIG_H define.
 CONFIG_H :=
 ifneq ("$(wildcard $(KEYBOARD_PATH_5)/config.h)","")
@@ -279,6 +304,11 @@ ifneq ("$(wildcard $(KEYBOARD_PATH_5)/post_config.h)","")
     POST_CONFIG_H += $(KEYBOARD_PATH_5)/post_config.h
 endif
 
+# Save the defines and includes here, so we don't include any keymap specific ones
+PROJECT_DEFS := $(OPT_DEFS)
+PROJECT_INC := $(VPATH) $(EXTRAINCDIRS) $(KEYBOARD_PATHS)
+PROJECT_CONFIG := $(CONFIG_H)
+
 # Userspace setup and definitions
 ifeq ("$(USER_NAME)","")
     USER_NAME := $(KEYMAP)
@@ -309,9 +339,9 @@ SRC += $(KEYBOARD_SRC) \
 
 # Search Path
 VPATH += $(KEYMAP_PATH)
+VPATH += $(USER_PATH)
 VPATH += $(KEYBOARD_PATHS)
 VPATH += $(COMMON_VPATH)
-VPATH += $(USER_PATH)
 
 include common_features.mk
 include $(TMK_PATH)/protocol.mk
@@ -324,17 +354,23 @@ SRC += $(TMK_COMMON_SRC)
 OPT_DEFS += $(TMK_COMMON_DEFS)
 EXTRALDFLAGS += $(TMK_COMMON_LDFLAGS)
 
-include $(TMK_PATH)/$(PLATFORM_KEY).mk
-ifneq ($(strip $(PROTOCOL)),)
-    include $(TMK_PATH)/protocol/$(strip $(shell echo $(PROTOCOL) | tr '[:upper:]' '[:lower:]')).mk
+ifeq ($(PLATFORM),AVR)
+ifeq ($(strip $(PROTOCOL)), VUSB)
+    include $(TMK_PATH)/protocol/vusb.mk
 else
-    include $(TMK_PATH)/protocol/$(PLATFORM_KEY).mk
+    include $(TMK_PATH)/protocol/lufa.mk
+endif
+    include $(TMK_PATH)/avr.mk
 endif
 
-# TODO: remove this bodge?
-PROJECT_DEFS := $(OPT_DEFS)
-PROJECT_INC := $(VPATH) $(EXTRAINCDIRS) $(KEYBOARD_PATHS)
-PROJECT_CONFIG := $(CONFIG_H)
+ifeq ($(PLATFORM),ARM_ATSAM)
+    include $(TMK_PATH)/arm_atsam.mk
+    include $(TMK_PATH)/protocol/arm_atsam.mk
+endif
+
+ifeq ($(PLATFORM),CHIBIOS)
+    include $(TMK_PATH)/protocol/chibios.mk
+endif
 
 ifeq ($(strip $(VISUALIZER_ENABLE)), yes)
     VISUALIZER_DIR = $(QUANTUM_DIR)/visualizer

build_layout.mk

@@ -3,14 +3,8 @@ LAYOUTS_REPOS := $(patsubst %/,%,$(sort $(dir $(wildcard $(LAYOUTS_PATH)/*/))))
 
 define SEARCH_LAYOUTS_REPO
     LAYOUT_KEYMAP_PATH := $$(LAYOUTS_REPO)/$$(LAYOUT)/$$(KEYMAP)
-    LAYOUT_KEYMAP_JSON := $$(LAYOUT_KEYMAP_PATH)/keymap.json
     LAYOUT_KEYMAP_C := $$(LAYOUT_KEYMAP_PATH)/keymap.c
-    ifneq ("$$(wildcard $$(LAYOUT_KEYMAP_JSON))","")
-        -include $$(LAYOUT_KEYMAP_PATH)/rules.mk
-        KEYMAP_C := $(KEYBOARD_OUTPUT)/src/keymap.c
-        KEYMAP_JSON := $$(LAYOUT_KEYMAP_JSON)
-        KEYMAP_PATH := $$(LAYOUT_KEYMAP_PATH)
-    else ifneq ("$$(wildcard $$(LAYOUT_KEYMAP_C))","")
+    ifneq ("$$(wildcard $$(LAYOUT_KEYMAP_C))","")
         -include $$(LAYOUT_KEYMAP_PATH)/rules.mk
         KEYMAP_C := $$(LAYOUT_KEYMAP_C)
         KEYMAP_PATH := $$(LAYOUT_KEYMAP_PATH)
@@ -30,7 +24,4 @@ ifneq ($(FORCE_LAYOUT),)
     endif
 endif
 
-$(foreach LAYOUT,$(LAYOUTS),$(eval $(call SEARCH_LAYOUTS)))
-
-# Use rule from build_json.mk, but update prerequisite in case KEYMAP_JSON was updated
-$(KEYBOARD_OUTPUT)/src/keymap.c: $(KEYMAP_JSON)
+$(foreach LAYOUT,$(LAYOUTS),$(eval $(call SEARCH_LAYOUTS)))

build_test.mk

@@ -41,7 +41,6 @@ all: elf
 
 VPATH += $(COMMON_VPATH)
 PLATFORM:=TEST
-PLATFORM_KEY:=test
 
 ifneq ($(filter $(FULL_TESTS),$(TEST)),)
 include tests/$(TEST)/rules.mk

common_features.mk

@@ -13,45 +13,55 @@
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
+SERIAL_DIR := $(QUANTUM_DIR)/serial_link
 SERIAL_PATH := $(QUANTUM_PATH)/serial_link
-
-QUANTUM_SRC += \
-    $(QUANTUM_DIR)/quantum.c \
-    $(QUANTUM_DIR)/keymap_common.c \
-    $(QUANTUM_DIR)/keycode_config.c
+SERIAL_SRC := $(wildcard $(SERIAL_PATH)/protocol/*.c)
+SERIAL_SRC += $(wildcard $(SERIAL_PATH)/system/*.c)
+SERIAL_DEFS += -DSERIAL_LINK_ENABLE
+COMMON_VPATH += $(SERIAL_PATH)
 
 ifeq ($(strip $(API_SYSEX_ENABLE)), yes)
     OPT_DEFS += -DAPI_SYSEX_ENABLE
-    OPT_DEFS += -DAPI_ENABLE
-    MIDI_ENABLE=yes
     SRC += $(QUANTUM_DIR)/api/api_sysex.c
+    OPT_DEFS += -DAPI_ENABLE
     SRC += $(QUANTUM_DIR)/api.c
+    MIDI_ENABLE=yes
 endif
 
+MUSIC_ENABLE := 0
+
 ifeq ($(strip $(AUDIO_ENABLE)), yes)
     OPT_DEFS += -DAUDIO_ENABLE
-    MUSIC_ENABLE = yes
+    MUSIC_ENABLE := 1
     SRC += $(QUANTUM_DIR)/process_keycode/process_audio.c
     SRC += $(QUANTUM_DIR)/process_keycode/process_clicky.c
-    SRC += $(QUANTUM_DIR)/audio/audio_$(PLATFORM_KEY).c
+    ifeq ($(PLATFORM),AVR)
+        SRC += $(QUANTUM_DIR)/audio/audio.c
+    else
+        SRC += $(QUANTUM_DIR)/audio/audio_arm.c
+    endif
     SRC += $(QUANTUM_DIR)/audio/voices.c
     SRC += $(QUANTUM_DIR)/audio/luts.c
 endif
 
 ifeq ($(strip $(MIDI_ENABLE)), yes)
     OPT_DEFS += -DMIDI_ENABLE
-    MUSIC_ENABLE = yes
+    MUSIC_ENABLE := 1
     SRC += $(QUANTUM_DIR)/process_keycode/process_midi.c
 endif
 
-MUSIC_ENABLE ?= no
-ifeq ($(MUSIC_ENABLE), yes)
+ifeq ($(MUSIC_ENABLE), 1)
     SRC += $(QUANTUM_DIR)/process_keycode/process_music.c
 endif
 
+ifeq ($(strip $(COMBO_ENABLE)), yes)
+    OPT_DEFS += -DCOMBO_ENABLE
+    SRC += $(QUANTUM_DIR)/process_keycode/process_combo.c
+endif
+
 ifeq ($(strip $(STENO_ENABLE)), yes)
     OPT_DEFS += -DSTENO_ENABLE
-    VIRTSER_ENABLE ?= yes
+    VIRTSER_ENABLE := yes
     SRC += $(QUANTUM_DIR)/process_keycode/process_steno.c
 endif
 
@@ -70,64 +80,26 @@ ifeq ($(strip $(POINTING_DEVICE_ENABLE)), yes)
     SRC += $(QUANTUM_DIR)/pointing_device.c
 endif
 
-VALID_EEPROM_DRIVER_TYPES := vendor custom transient i2c spi
-EEPROM_DRIVER ?= vendor
-ifeq ($(filter $(EEPROM_DRIVER),$(VALID_EEPROM_DRIVER_TYPES)),)
-  $(error EEPROM_DRIVER="$(EEPROM_DRIVER)" is not a valid EEPROM driver)
-else
-  OPT_DEFS += -DEEPROM_ENABLE
-  ifeq ($(strip $(EEPROM_DRIVER)), custom)
-    OPT_DEFS += -DEEPROM_DRIVER -DEEPROM_CUSTOM
-    COMMON_VPATH += $(DRIVER_PATH)/eeprom
-    SRC += eeprom_driver.c
-  else ifeq ($(strip $(EEPROM_DRIVER)), i2c)
-    OPT_DEFS += -DEEPROM_DRIVER -DEEPROM_I2C
-    COMMON_VPATH += $(DRIVER_PATH)/eeprom
-    QUANTUM_LIB_SRC += i2c_master.c
-    SRC += eeprom_driver.c eeprom_i2c.c
-  else ifeq ($(strip $(EEPROM_DRIVER)), spi)
-    OPT_DEFS += -DEEPROM_DRIVER -DEEPROM_SPI
-    COMMON_VPATH += $(DRIVER_PATH)/eeprom
-    QUANTUM_LIB_SRC += spi_master.c
-    SRC += eeprom_driver.c eeprom_spi.c
-  else ifeq ($(strip $(EEPROM_DRIVER)), transient)
-    OPT_DEFS += -DEEPROM_DRIVER -DEEPROM_TRANSIENT
-    COMMON_VPATH += $(DRIVER_PATH)/eeprom
-    SRC += eeprom_driver.c eeprom_transient.c
-  else ifeq ($(strip $(EEPROM_DRIVER)), vendor)
-    OPT_DEFS += -DEEPROM_VENDOR
-    ifeq ($(PLATFORM),AVR)
-      # Automatically provided by avr-libc, nothing required
-    else ifeq ($(PLATFORM),CHIBIOS)
-      ifeq ($(MCU_SERIES), STM32F3xx)
-        SRC += $(PLATFORM_COMMON_DIR)/eeprom_stm32.c
-        SRC += $(PLATFORM_COMMON_DIR)/flash_stm32.c
-        OPT_DEFS += -DEEPROM_EMU_STM32F303xC
-        OPT_DEFS += -DSTM32_EEPROM_ENABLE
-      else ifeq ($(MCU_SERIES), STM32F1xx)
-        SRC += $(PLATFORM_COMMON_DIR)/eeprom_stm32.c
-        SRC += $(PLATFORM_COMMON_DIR)/flash_stm32.c
-        OPT_DEFS += -DEEPROM_EMU_STM32F103xB
-        OPT_DEFS += -DSTM32_EEPROM_ENABLE
-      else ifeq ($(MCU_SERIES)_$(MCU_LDSCRIPT), STM32F0xx_STM32F072xB)
-        SRC += $(PLATFORM_COMMON_DIR)/eeprom_stm32.c
-        SRC += $(PLATFORM_COMMON_DIR)/flash_stm32.c
-        OPT_DEFS += -DEEPROM_EMU_STM32F072xB
-        OPT_DEFS += -DSTM32_EEPROM_ENABLE
-      else ifneq ($(filter $(MCU_SERIES),STM32L0xx STM32L1xx),)
-        OPT_DEFS += -DEEPROM_DRIVER
-        COMMON_VPATH += $(DRIVER_PATH)/eeprom
-        SRC += eeprom_driver.c eeprom_stm32_L0_L1.c
-      else
-        # This will effectively work the same as "transient" if not supported by the chip
-        SRC += $(PLATFORM_COMMON_DIR)/eeprom_teensy.c
-      endif
-    else ifeq ($(PLATFORM),ARM_ATSAM)
-      SRC += $(PLATFORM_COMMON_DIR)/eeprom.c
-    else ifeq ($(PLATFORM),TEST)
-      SRC += $(PLATFORM_COMMON_DIR)/eeprom.c
-    endif
-  endif
+ifeq ($(strip $(UCIS_ENABLE)), yes)
+    OPT_DEFS += -DUCIS_ENABLE
+    UNICODE_COMMON = yes
+    SRC += $(QUANTUM_DIR)/process_keycode/process_ucis.c
+endif
+
+ifeq ($(strip $(UNICODEMAP_ENABLE)), yes)
+    OPT_DEFS += -DUNICODEMAP_ENABLE
+    UNICODE_COMMON = yes
+    SRC += $(QUANTUM_DIR)/process_keycode/process_unicodemap.c
+endif
+
+ifeq ($(strip $(UNICODE_ENABLE)), yes)
+    OPT_DEFS += -DUNICODE_ENABLE
+    UNICODE_COMMON = yes
+    SRC += $(QUANTUM_DIR)/process_keycode/process_unicode.c
+endif
+
+ifeq ($(strip $(UNICODE_COMMON)), yes)
+    SRC += $(QUANTUM_DIR)/process_keycode/process_unicode_common.c
 endif
 
 ifeq ($(strip $(RGBLIGHT_ENABLE)), yes)
@@ -135,25 +107,23 @@ ifeq ($(strip $(RGBLIGHT_ENABLE)), yes)
     OPT_DEFS += -DRGBLIGHT_ENABLE
     SRC += $(QUANTUM_DIR)/color.c
     SRC += $(QUANTUM_DIR)/rgblight.c
-    CIE1931_CURVE := yes
-    RGB_KEYCODES_ENABLE := yes
+    CIE1931_CURVE = yes
+    LED_BREATHING_TABLE = yes
     ifeq ($(strip $(RGBLIGHT_CUSTOM_DRIVER)), yes)
         OPT_DEFS += -DRGBLIGHT_CUSTOM_DRIVER
     else
-        WS2812_DRIVER_REQUIRED := yes
+        SRC += ws2812.c
     endif
 endif
 
-VALID_MATRIX_TYPES := yes IS31FL3731 IS31FL3733 IS31FL3737 IS31FL3741 WS2812 custom
+VALID_MATRIX_TYPES := yes IS31FL3731 IS31FL3733 IS31FL3737 WS2812 custom
 
 LED_MATRIX_ENABLE ?= no
 ifneq ($(strip $(LED_MATRIX_ENABLE)), no)
     ifeq ($(filter $(LED_MATRIX_ENABLE),$(VALID_MATRIX_TYPES)),)
         $(error LED_MATRIX_ENABLE="$(LED_MATRIX_ENABLE)" is not a valid matrix type)
     else
-        BACKLIGHT_ENABLE = yes
-        BACKLIGHT_DRIVER = custom
-        OPT_DEFS += -DLED_MATRIX_ENABLE
+        OPT_DEFS += -DLED_MATRIX_ENABLE -DBACKLIGHT_ENABLE -DBACKLIGHT_CUSTOM_DRIVER
         SRC += $(QUANTUM_DIR)/led_matrix.c
         SRC += $(QUANTUM_DIR)/led_matrix_drivers.c
     endif
@@ -176,12 +146,11 @@ endif
     SRC += $(QUANTUM_DIR)/color.c
     SRC += $(QUANTUM_DIR)/rgb_matrix.c
     SRC += $(QUANTUM_DIR)/rgb_matrix_drivers.c
-    CIE1931_CURVE := yes
-    RGB_KEYCODES_ENABLE := yes
+    CIE1931_CURVE = yes
 endif
 
 ifeq ($(strip $(RGB_MATRIX_ENABLE)), yes)
-	RGB_MATRIX_ENABLE := IS31FL3731
+	RGB_MATRIX_ENABLE = IS31FL3731
 endif
 
 ifeq ($(strip $(RGB_MATRIX_ENABLE)), IS31FL3731)
@@ -205,16 +174,9 @@ ifeq ($(strip $(RGB_MATRIX_ENABLE)), IS31FL3737)
     QUANTUM_LIB_SRC += i2c_master.c
 endif
 
-ifeq ($(strip $(RGB_MATRIX_ENABLE)), IS31FL3741)
-    OPT_DEFS += -DIS31FL3741 -DSTM32_I2C -DHAL_USE_I2C=TRUE
-    COMMON_VPATH += $(DRIVER_PATH)/issi
-    SRC += is31fl3741.c
-    QUANTUM_LIB_SRC += i2c_master.c
-endif
-
 ifeq ($(strip $(RGB_MATRIX_ENABLE)), WS2812)
     OPT_DEFS += -DWS2812
-    WS2812_DRIVER_REQUIRED := yes
+    SRC += ws2812.c
 endif
 
 ifeq ($(strip $(RGB_MATRIX_CUSTOM_KB)), yes)
@@ -225,8 +187,14 @@ ifeq ($(strip $(RGB_MATRIX_CUSTOM_USER)), yes)
     OPT_DEFS += -DRGB_MATRIX_CUSTOM_USER
 endif
 
-ifeq ($(strip $(RGB_KEYCODES_ENABLE)), yes)
-    SRC += $(QUANTUM_DIR)/process_keycode/process_rgb.c
+ifeq ($(strip $(TAP_DANCE_ENABLE)), yes)
+    OPT_DEFS += -DTAP_DANCE_ENABLE
+    SRC += $(QUANTUM_DIR)/process_keycode/process_tap_dance.c
+endif
+
+ifeq ($(strip $(KEY_LOCK_ENABLE)), yes)
+    OPT_DEFS += -DKEY_LOCK_ENABLE
+    SRC += $(QUANTUM_DIR)/process_keycode/process_key_lock.c
 endif
 
 ifeq ($(strip $(PRINTING_ENABLE)), yes)
@@ -235,12 +203,15 @@ ifeq ($(strip $(PRINTING_ENABLE)), yes)
     SRC += $(TMK_DIR)/protocol/serial_uart.c
 endif
 
-ifeq ($(strip $(SERIAL_LINK_ENABLE)), yes)
-    SERIAL_SRC := $(wildcard $(SERIAL_PATH)/protocol/*.c)
-    SERIAL_SRC += $(wildcard $(SERIAL_PATH)/system/*.c)
-    SERIAL_DEFS += -DSERIAL_LINK_ENABLE
-    COMMON_VPATH += $(SERIAL_PATH)
+ifeq ($(strip $(AUTO_SHIFT_ENABLE)), yes)
+    OPT_DEFS += -DAUTO_SHIFT_ENABLE
+    SRC += $(QUANTUM_DIR)/process_keycode/process_auto_shift.c
+    ifeq ($(strip $(AUTO_SHIFT_MODIFIERS)), yes)
+        OPT_DEFS += -DAUTO_SHIFT_MODIFIERS
+    endif
+endif
 
+ifeq ($(strip $(SERIAL_LINK_ENABLE)), yes)
     SRC += $(patsubst $(QUANTUM_PATH)/%,%,$(SERIAL_SRC))
     OPT_DEFS += $(SERIAL_DEFS)
     VAPTH += $(SERIAL_PATH)
@@ -255,73 +226,50 @@ endif
 endif
 
 ifeq ($(strip $(LCD_ENABLE)), yes)
-    CIE1931_CURVE := yes
+    CIE1931_CURVE = yes
 endif
 
 # backward compat
 ifeq ($(strip $(BACKLIGHT_CUSTOM_DRIVER)), yes)
-    BACKLIGHT_DRIVER := custom
+    BACKLIGHT_ENABLE = custom
 endif
 
-VALID_BACKLIGHT_TYPES := pwm software custom
+VALID_BACKLIGHT_TYPES := yes custom
 
 BACKLIGHT_ENABLE ?= no
-BACKLIGHT_DRIVER ?= pwm
-ifeq ($(strip $(BACKLIGHT_ENABLE)), yes)
-    ifeq ($(filter $(BACKLIGHT_DRIVER),$(VALID_BACKLIGHT_TYPES)),)
-        $(error BACKLIGHT_DRIVER="$(BACKLIGHT_DRIVER)" is not a valid backlight type)
+ifneq ($(strip $(BACKLIGHT_ENABLE)), no)
+    ifeq ($(filter $(BACKLIGHT_ENABLE),$(VALID_BACKLIGHT_TYPES)),)
+        $(error BACKLIGHT_ENABLE="$(BACKLIGHT_ENABLE)" is not a valid backlight type)
     endif
 
     ifeq ($(strip $(VISUALIZER_ENABLE)), yes)
-        CIE1931_CURVE := yes
+        CIE1931_CURVE = yes
     endif
 
+
     COMMON_VPATH += $(QUANTUM_DIR)/backlight
     SRC += $(QUANTUM_DIR)/backlight/backlight.c
-    SRC += $(QUANTUM_DIR)/process_keycode/process_backlight.c
     OPT_DEFS += -DBACKLIGHT_ENABLE
 
-    ifeq ($(strip $(BACKLIGHT_DRIVER)), custom)
+    ifeq ($(strip $(BACKLIGHT_ENABLE)), custom)
         OPT_DEFS += -DBACKLIGHT_CUSTOM_DRIVER
+    endif
+
+    ifeq ($(PLATFORM),AVR)
+        SRC += $(QUANTUM_DIR)/backlight/backlight_avr.c
     else
-        SRC += $(QUANTUM_DIR)/backlight/backlight_driver_common.c
-        ifeq ($(strip $(BACKLIGHT_DRIVER)), pwm)
-            SRC += $(QUANTUM_DIR)/backlight/backlight_$(PLATFORM_KEY).c
-        else
-            SRC += $(QUANTUM_DIR)/backlight/backlight_$(strip $(BACKLIGHT_DRIVER)).c
-        endif
+        SRC += $(QUANTUM_DIR)/backlight/backlight_arm.c
     endif
 endif
 
-VALID_WS2812_DRIVER_TYPES := bitbang pwm spi i2c
-
-WS2812_DRIVER ?= bitbang
-ifeq ($(strip $(WS2812_DRIVER_REQUIRED)), yes)
-    ifeq ($(filter $(WS2812_DRIVER),$(VALID_WS2812_DRIVER_TYPES)),)
-        $(error WS2812_DRIVER="$(WS2812_DRIVER)" is not a valid WS2812 driver)
-    endif
-
-    OPT_DEFS += -DWS2812_DRIVER_$(strip $(shell echo $(WS2812_DRIVER) | tr '[:lower:]' '[:upper:]'))
-
-    ifeq ($(strip $(WS2812_DRIVER)), bitbang)
-        SRC += ws2812.c
-    else
-        SRC += ws2812_$(strip $(WS2812_DRIVER)).c
-    endif
-
-    # add extra deps
-    ifeq ($(strip $(WS2812_DRIVER)), i2c)
-        QUANTUM_LIB_SRC += i2c_master.c
-    endif
-endif
-
-ifeq ($(strip $(VISUALIZER_ENABLE)), yes)
-    CIE1931_CURVE := yes
-endif
-
 ifeq ($(strip $(CIE1931_CURVE)), yes)
     OPT_DEFS += -DUSE_CIE1931_CURVE
-    LED_TABLES := yes
+    LED_TABLES = yes
+endif
+
+ifeq ($(strip $(LED_BREATHING_TABLE)), yes)
+    OPT_DEFS += -DUSE_LED_BREATHING_TABLE
+    LED_TABLES = yes
 endif
 
 ifeq ($(strip $(LED_TABLES)), yes)
@@ -338,65 +286,62 @@ ifeq ($(strip $(USB_HID_ENABLE)), yes)
     include $(TMK_DIR)/protocol/usb_hid.mk
 endif
 
-ifeq ($(strip $(WPM_ENABLE)), yes)
-    SRC += $(QUANTUM_DIR)/wpm.c
-    OPT_DEFS += -DWPM_ENABLE
-endif
-
 ifeq ($(strip $(ENCODER_ENABLE)), yes)
     SRC += $(QUANTUM_DIR)/encoder.c
     OPT_DEFS += -DENCODER_ENABLE
 endif
 
+HAPTIC_ENABLE ?= no
+ifneq ($(strip $(HAPTIC_ENABLE)),no)
+	COMMON_VPATH += $(DRIVER_PATH)/haptic
+	SRC += haptic.c
+	OPT_DEFS += -DHAPTIC_ENABLE
+endif
+
+ifneq ($(filter DRV2605L, $(HAPTIC_ENABLE)), )
+    SRC += DRV2605L.c
+    QUANTUM_LIB_SRC += i2c_master.c
+    OPT_DEFS += -DDRV2605L
+endif
+
+ifneq ($(filter SOLENOID, $(HAPTIC_ENABLE)), )
+    SRC += solenoid.c
+    OPT_DEFS += -DSOLENOID_ENABLE
+endif
+
+ifeq ($(strip $(HD44780_ENABLE)), yes)
+    SRC += drivers/avr/hd44780.c
+    OPT_DEFS += -DHD44780_ENABLE
+endif
+
 ifeq ($(strip $(VELOCIKEY_ENABLE)), yes)
     OPT_DEFS += -DVELOCIKEY_ENABLE
     SRC += $(QUANTUM_DIR)/velocikey.c
 endif
 
-ifeq ($(strip $(ORYX_ENABLE)), yes)
-    WEBUSB_ENABLE := yes
-    SRC += $(QUANTUM_DIR)/oryx.c
-    OPT_DEFS += -DORYX_ENABLE
-endif
-
-ifeq ($(strip $(VIA_ENABLE)), yes)
-    DYNAMIC_KEYMAP_ENABLE := yes
-    RAW_ENABLE := yes
-    BOOTMAGIC_ENABLE := lite
-    SRC += $(QUANTUM_DIR)/via.c
-    OPT_DEFS += -DVIA_ENABLE
-endif
-
 ifeq ($(strip $(DYNAMIC_KEYMAP_ENABLE)), yes)
     OPT_DEFS += -DDYNAMIC_KEYMAP_ENABLE
     SRC += $(QUANTUM_DIR)/dynamic_keymap.c
 endif
 
-ifeq ($(strip $(DIP_SWITCH_ENABLE)), yes)
-    OPT_DEFS += -DDIP_SWITCH_ENABLE
-    SRC += $(QUANTUM_DIR)/dip_switch.c
+ifeq ($(strip $(LEADER_ENABLE)), yes)
+  SRC += $(QUANTUM_DIR)/process_keycode/process_leader.c
+  OPT_DEFS += -DLEADER_ENABLE
 endif
 
-VALID_CUSTOM_MATRIX_TYPES:= yes lite no
+include $(DRIVER_PATH)/qwiic/qwiic.mk
 
-CUSTOM_MATRIX ?= no
+QUANTUM_SRC:= \
+    $(QUANTUM_DIR)/quantum.c \
+    $(QUANTUM_DIR)/keymap_common.c \
+    $(QUANTUM_DIR)/keycode_config.c
 
+# Include the standard or split matrix code if needed
 ifneq ($(strip $(CUSTOM_MATRIX)), yes)
-    ifeq ($(filter $(CUSTOM_MATRIX),$(VALID_CUSTOM_MATRIX_TYPES)),)
-        $(error CUSTOM_MATRIX="$(CUSTOM_MATRIX)" is not a valid custom matrix type)
-    endif
-
-    # Include common stuff for all non custom matrix users
-    QUANTUM_SRC += $(QUANTUM_DIR)/matrix_common.c
-
-    # if 'lite' then skip the actual matrix implementation
-    ifneq ($(strip $(CUSTOM_MATRIX)), lite)
-        # Include the standard or split matrix code if needed
-        ifeq ($(strip $(SPLIT_KEYBOARD)), yes)
-            QUANTUM_SRC += $(QUANTUM_DIR)/split_common/matrix.c
-        else
-            QUANTUM_SRC += $(QUANTUM_DIR)/matrix.c
-        endif
+    ifeq ($(strip $(SPLIT_KEYBOARD)), yes)
+        QUANTUM_SRC += $(QUANTUM_DIR)/split_common/matrix.c
+    else
+        QUANTUM_SRC += $(QUANTUM_DIR)/matrix.c
     endif
 endif
 
@@ -419,44 +364,13 @@ ifeq ($(strip $(SPLIT_KEYBOARD)), yes)
         QUANTUM_SRC += $(QUANTUM_DIR)/split_common/transport.c
         # Functions added via QUANTUM_LIB_SRC are only included in the final binary if they're called.
         # Unused functions are pruned away, which is why we can add multiple drivers here without bloat.
-        ifeq ($(PLATFORM),AVR)
-            QUANTUM_LIB_SRC += i2c_master.c \
-                               i2c_slave.c
-        endif
-
-        SERIAL_DRIVER ?= bitbang
-        ifeq ($(strip $(SERIAL_DRIVER)), bitbang)
-            QUANTUM_LIB_SRC += serial.c
-        else
-            QUANTUM_LIB_SRC += serial_$(strip $(SERIAL_DRIVER)).c
-        endif
+        QUANTUM_LIB_SRC += $(QUANTUM_DIR)/split_common/serial.c \
+                           i2c_master.c \
+                           i2c_slave.c
     endif
     COMMON_VPATH += $(QUANTUM_PATH)/split_common
 endif
 
-HAPTIC_ENABLE ?= no
-ifneq ($(strip $(HAPTIC_ENABLE)),no)
-    COMMON_VPATH += $(DRIVER_PATH)/haptic
-    SRC += haptic.c
-    OPT_DEFS += -DHAPTIC_ENABLE
-endif
-
-ifneq ($(filter DRV2605L, $(HAPTIC_ENABLE)), )
-    SRC += DRV2605L.c
-    QUANTUM_LIB_SRC += i2c_master.c
-    OPT_DEFS += -DDRV2605L
-endif
-
-ifneq ($(filter SOLENOID, $(HAPTIC_ENABLE)), )
-    SRC += solenoid.c
-    OPT_DEFS += -DSOLENOID_ENABLE
-endif
-
-ifeq ($(strip $(HD44780_ENABLE)), yes)
-    SRC += drivers/avr/hd44780.c
-    OPT_DEFS += -DHD44780_ENABLE
-endif
-
 ifeq ($(strip $(OLED_DRIVER_ENABLE)), yes)
     OPT_DEFS += -DOLED_DRIVER_ENABLE
     COMMON_VPATH += $(DRIVER_PATH)/oled
@@ -464,133 +378,14 @@ ifeq ($(strip $(OLED_DRIVER_ENABLE)), yes)
     SRC += oled_driver.c
 endif
 
-include $(DRIVER_PATH)/qwiic/qwiic.mk
-
-ifeq ($(strip $(UCIS_ENABLE)), yes)
-    OPT_DEFS += -DUCIS_ENABLE
-    UNICODE_COMMON := yes
-    SRC += $(QUANTUM_DIR)/process_keycode/process_ucis.c
-endif
-
-ifeq ($(strip $(UNICODEMAP_ENABLE)), yes)
-    OPT_DEFS += -DUNICODEMAP_ENABLE
-    UNICODE_COMMON := yes
-    SRC += $(QUANTUM_DIR)/process_keycode/process_unicodemap.c
-endif
-
-ifeq ($(strip $(UNICODE_ENABLE)), yes)
-    OPT_DEFS += -DUNICODE_ENABLE
-    UNICODE_COMMON := yes
-    SRC += $(QUANTUM_DIR)/process_keycode/process_unicode.c
-endif
-
-ifeq ($(strip $(UNICODE_COMMON)), yes)
-    SRC += $(QUANTUM_DIR)/process_keycode/process_unicode_common.c
-endif
-
 SPACE_CADET_ENABLE ?= yes
 ifeq ($(strip $(SPACE_CADET_ENABLE)), yes)
-    SRC += $(QUANTUM_DIR)/process_keycode/process_space_cadet.c
-    OPT_DEFS += -DSPACE_CADET_ENABLE
+  SRC += $(QUANTUM_DIR)/process_keycode/process_space_cadet.c
+  OPT_DEFS += -DSPACE_CADET_ENABLE
 endif
 
-MAGIC_ENABLE ?= yes
-ifeq ($(strip $(MAGIC_ENABLE)), yes)
-    SRC += $(QUANTUM_DIR)/process_keycode/process_magic.c
-    OPT_DEFS += -DMAGIC_KEYCODE_ENABLE
-endif
 
 ifeq ($(strip $(DIP_SWITCH_ENABLE)), yes)
   SRC += $(QUANTUM_DIR)/dip_switch.c
   OPT_DEFS += -DDIP_SWITCH_ENABLE
 endif
-
-VALID_EEPROM_DRIVER_TYPES := vendor custom transient i2c
-EEPROM_DRIVER ?= vendor
-ifeq ($(filter $(EEPROM_DRIVER),$(VALID_EEPROM_DRIVER_TYPES)),)
-  $(error EEPROM_DRIVER="$(EEPROM_DRIVER)" is not a valid EEPROM driver)
-else
-  OPT_DEFS += -DEEPROM_ENABLE
-  ifeq ($(strip $(EEPROM_DRIVER)), custom)
-    OPT_DEFS += -DEEPROM_DRIVER -DEEPROM_CUSTOM
-    COMMON_VPATH += $(DRIVER_PATH)/eeprom
-    SRC += eeprom_driver.c
-  else ifeq ($(strip $(EEPROM_DRIVER)), i2c)
-    OPT_DEFS += -DEEPROM_DRIVER -DEEPROM_I2C
-    COMMON_VPATH += $(DRIVER_PATH)/eeprom
-    QUANTUM_LIB_SRC += i2c_master.c
-    SRC += eeprom_driver.c eeprom_i2c.c
-  else ifeq ($(strip $(EEPROM_DRIVER)), transient)
-    OPT_DEFS += -DEEPROM_DRIVER -DEEPROM_TRANSIENT
-    COMMON_VPATH += $(DRIVER_PATH)/eeprom
-    SRC += eeprom_driver.c eeprom_transient.c
-  else ifeq ($(strip $(EEPROM_DRIVER)), vendor)
-    OPT_DEFS += -DEEPROM_VENDOR
-    ifeq ($(PLATFORM),AVR)
-      # Automatically provided by avr-libc, nothing required
-    else ifeq ($(PLATFORM),CHIBIOS)
-      ifeq ($(MCU_SERIES), STM32F3xx)
-        SRC += $(PLATFORM_COMMON_DIR)/eeprom_stm32.c
-        SRC += $(PLATFORM_COMMON_DIR)/flash_stm32.c
-        OPT_DEFS += -DEEPROM_EMU_STM32F303xC
-        OPT_DEFS += -DSTM32_EEPROM_ENABLE
-      else ifeq ($(MCU_SERIES), STM32F1xx)
-        SRC += $(PLATFORM_COMMON_DIR)/eeprom_stm32.c
-        SRC += $(PLATFORM_COMMON_DIR)/flash_stm32.c
-        OPT_DEFS += -DEEPROM_EMU_STM32F103xB
-        OPT_DEFS += -DSTM32_EEPROM_ENABLE
-      else ifeq ($(MCU_SERIES)_$(MCU_LDSCRIPT), STM32F0xx_STM32F072xB)
-        SRC += $(PLATFORM_COMMON_DIR)/eeprom_stm32.c
-        SRC += $(PLATFORM_COMMON_DIR)/flash_stm32.c
-        OPT_DEFS += -DEEPROM_EMU_STM32F072xB
-        OPT_DEFS += -DSTM32_EEPROM_ENABLE
-      else
-        # This will effectively work the same as "transient" if not supported by the chip
-        SRC += $(PLATFORM_COMMON_DIR)/eeprom_teensy.c
-      endif
-    else ifeq ($(PLATFORM),ARM_ATSAM)
-      SRC += $(PLATFORM_COMMON_DIR)/eeprom.c
-    else ifeq ($(PLATFORM),TEST)
-      SRC += $(PLATFORM_COMMON_DIR)/eeprom.c
-    endif
-  endif
-endif
-
-GRAVE_ESC_ENABLE ?= yes
-ifeq ($(strip $(GRAVE_ESC_ENABLE)), yes)
-    SRC += $(QUANTUM_DIR)/process_keycode/process_grave_esc.c
-    OPT_DEFS += -DGRAVE_ESC_ENABLE
-endif
-
-ifeq ($(strip $(DYNAMIC_MACRO_ENABLE)), yes)
-    SRC += $(QUANTUM_DIR)/process_keycode/process_dynamic_macro.c
-    OPT_DEFS += -DDYNAMIC_MACRO_ENABLE
-endif
-
-ifeq ($(strip $(COMBO_ENABLE)), yes)
-    SRC += $(QUANTUM_DIR)/process_keycode/process_combo.c
-    OPT_DEFS += -DCOMBO_ENABLE
-endif
-
-ifeq ($(strip $(TAP_DANCE_ENABLE)), yes)
-    SRC += $(QUANTUM_DIR)/process_keycode/process_tap_dance.c
-    OPT_DEFS += -DTAP_DANCE_ENABLE
-endif
-
-ifeq ($(strip $(KEY_LOCK_ENABLE)), yes)
-    SRC += $(QUANTUM_DIR)/process_keycode/process_key_lock.c
-    OPT_DEFS += -DKEY_LOCK_ENABLE
-endif
-
-ifeq ($(strip $(LEADER_ENABLE)), yes)
-    SRC += $(QUANTUM_DIR)/process_keycode/process_leader.c
-    OPT_DEFS += -DLEADER_ENABLE
-endif
-
-ifeq ($(strip $(AUTO_SHIFT_ENABLE)), yes)
-    SRC += $(QUANTUM_DIR)/process_keycode/process_auto_shift.c
-    OPT_DEFS += -DAUTO_SHIFT_ENABLE
-    ifeq ($(strip $(AUTO_SHIFT_MODIFIERS)), yes)
-        OPT_DEFS += -DAUTO_SHIFT_MODIFIERS
-    endif
-endif

docs/CNAME

@@ -0,0 +1 @@
+docs.qmk.fm

docs/ChangeLog/20190830.md

@@ -0,0 +1,53 @@
+# QMK Breaking Change - 2019 Aug 30
+
+Four times a year QMK runs a process for merging Breaking Changes. A Breaking Change is any change which modifies how QMK behaves in a way that is incompatible or potentially dangerous. We limit these changes to 4 times per year so that users can have confidence that updating their QMK tree will not break their keymaps.
+
+This document marks the inaugural Breaking Change merge. A list of changes follows.
+
+## Core code formatting with clang-format
+
+* All core files (`drivers/`, `quantum/`, `tests/`, and `tmk_core/`) have been formatted with clang-format
+* A travis process to reformat PR's on merge has been instituted
+* You can use the new CLI command `qmk cformat` to format before submitting your PR if you wish.
+
+## LUFA USB descriptor cleanup
+
+* Some code cleanups related to the USB HID descriptors on AVR keyboards, to make them easier to read and understand
+* More information: see https://github.com/qmk/qmk_firmware/pull/4871
+* No behaviour changes anticipated and no keymaps modified
+
+## Migrating `ACTION_LAYER_MOMENTARY()` entries in `fn_actions` to `MO()` keycodes
+
+* `fn_actions` is deprecated, and its functionality has been superseded by direct keycodes and `process_record_user()`
+* The end result of removing this obsolete feature should result in a decent reduction in firmware size and code complexity
+* All keymaps affected are recommended to switch away from `fn_actions` in favour of the [custom keycode](https://docs.qmk.fm/#/custom_quantum_functions) and [macro](https://docs.qmk.fm/#/feature_macros) features
+
+## Update Atreus to current code conventions
+
+* Duplicate include guards have bypassed the expected header processing behavior
+* All keymaps affected are recommended to remove duplication of `<keyboard>/config.h` to `<keyboard>/keymaps/<user>/config.h` and only provide overrides at the keymap level
+
+## Backport changes to keymap language files from ZSA fork
+
+* Fixes an issue in the `keymap_br_abnt2.h` file that includes the wrong source (`keymap_common.h` instead of `keymap.h`)
+* Updates the `keymap_swedish.h` file to be specific to swedish, and not just "nordic" in general. 
+* Any keymaps using this will need to remove `NO_*` and replace it with `SE_*`. 
+
+## Update repo to use LUFA as a git submodule
+
+* `/lib/LUFA` removed from the repo
+* LUFA set as a submodule, pointing to qmk/lufa
+* This should allow more flexibility with LUFA, and allow us to keep the sub-module up to date, a lot more easily.  It was ~2 years out of date with no easy path to fix that.  This prevents that from being an issue in the future
+  
+## Migrating `ACTION_BACKLIGHT_*()` entries in `fn_actions` to `BL_` keycodes
+
+* `fn_actions` is deprecated, and its functionality has been superseded by direct keycodes and `process_record_user()`
+* All keymaps using these actions have had the relevant `KC_FN*` keys replaced with the equivalent `BL_*` keys
+* If you currently use `KC_FN*` you will need to replace `fn_actions` with the [custom keycode](https://docs.qmk.fm/#/custom_quantum_functions) and [macro](https://docs.qmk.fm/#/feature_macros) features
+
+## Remove `KC_DELT` alias in favor of `KC_DEL`
+
+* `KC_DELT` was a redundant, undocumented alias for `KC_DELETE`
+* It has been removed and all its uses replaced with the more common `KC_DEL` alias
+* Around 90 keymaps (mostly for ErgoDox boards) have been modified as a result
+

docs/README.md

@@ -0,0 +1,32 @@
+# Quantum Mechanical Keyboard Firmware
+
+[![Current Version](https://img.shields.io/github/tag/qmk/qmk_firmware.svg)](https://github.com/qmk/qmk_firmware/tags)
+[![Build Status](https://travis-ci.org/qmk/qmk_firmware.svg?branch=master)](https://travis-ci.org/qmk/qmk_firmware)
+[![Discord](https://img.shields.io/discord/440868230475677696.svg)](https://discord.gg/Uq7gcHh)
+[![Docs Status](https://img.shields.io/badge/docs-ready-orange.svg)](https://docs.qmk.fm)
+[![GitHub contributors](https://img.shields.io/github/contributors/qmk/qmk_firmware.svg)](https://github.com/qmk/qmk_firmware/pulse/monthly)
+[![GitHub forks](https://img.shields.io/github/forks/qmk/qmk_firmware.svg?style=social&label=Fork)](https://github.com/qmk/qmk_firmware/)
+
+## What is QMK Firmware?
+
+QMK (*Quantum Mechanical Keyboard*) is an open source community that maintains QMK Firmware, QMK Toolbox, qmk.fm, and these docs. QMK Firmware is a keyboard firmware based on the [tmk\_keyboard](http://github.com/tmk/tmk_keyboard) with some useful features for Atmel AVR controllers, and more specifically, the [OLKB product line](http://olkb.com), the [ErgoDox EZ](http://www.ergodox-ez.com) keyboard, and the [Clueboard product line](http://clueboard.co/). It has also been ported to ARM chips using ChibiOS. You can use it to power your own hand-wired or custom keyboard PCB.
+
+## How to Get It
+
+If you plan on contributing a keymap, keyboard, or features to QMK, the easiest thing to do is [fork the repo through Github](https://github.com/qmk/qmk_firmware#fork-destination-box), and clone your repo locally to make your changes, push them, then open a [Pull Request](https://github.com/qmk/qmk_firmware/pulls) from your fork.
+
+Otherwise, you can either download it directly ([zip](https://github.com/qmk/qmk_firmware/zipball/master), [tar](https://github.com/qmk/qmk_firmware/tarball/master)), or clone it via git (`git@github.com:qmk/qmk_firmware.git`), or https (`https://github.com/qmk/qmk_firmware.git`).
+
+## How to Compile
+
+Before you are able to compile, you'll need to [install an environment](getting_started_build_tools.md) for AVR or/and ARM development. Once that is complete, you'll use the `make` command to build a keyboard and keymap with the following notation:
+
+    make planck/rev4:default
+
+This would build the `rev4` revision of the `planck` with the `default` keymap. Not all keyboards have revisions (also called subprojects or folders), in which case, it can be omitted:
+
+    make preonic:default
+
+## How to Customize
+
+QMK has lots of [features](features.md) to explore, and a good deal of [reference documentation](http://docs.qmk.fm) to dig through. Most features are taken advantage of by modifying your [keymap](keymap.md), and changing the [keycodes](keycodes.md).

docs/_langs.md

@@ -0,0 +1,4 @@
+- Translations
+  - [:uk: English](/)
+  - [:cn: 中文](/zh-cn/)
+  - [:fr: Français](/fr-fr/)

docs/_summary.md

@@ -0,0 +1,121 @@
+* [Complete Newbs Guide](newbs.md)
+  * [Getting Started](newbs_getting_started.md)
+  * [Building Your First Firmware](newbs_building_firmware.md)
+  * [Flashing Firmware](newbs_flashing.md)
+  * [Testing and Debugging](newbs_testing_debugging.md)
+  * [Git Best Practices](newbs_best_practices.md)
+  * [Learning Resources](newbs_learn_more_resources.md)
+
+* [QMK Basics](README.md)
+  * [QMK Introduction](getting_started_introduction.md)
+  * [QMK CLI](cli.md)
+  * [QMK CLI Config](cli_configuration.md)
+  * [Contributing to QMK](contributing.md)
+  * [How to Use Github](getting_started_github.md)
+  * [Getting Help](getting_started_getting_help.md)
+
+* [Breaking Changes](breaking_changes.md)
+  * [2019 Aug 30](ChangeLog/20190830.md)
+
+* [FAQ](faq.md)
+  * [General FAQ](faq_general.md)
+  * [Build/Compile QMK](faq_build.md)
+  * [Debugging/Troubleshooting QMK](faq_debug.md)
+  * [Keymap](faq_keymap.md)
+  * [Driver Installation with Zadig](driver_installation_zadig.md)
+
+* Detailed Guides
+  * [Install Build Tools](getting_started_build_tools.md)
+  * [Vagrant Guide](getting_started_vagrant.md)
+  * [Build/Compile Instructions](getting_started_make_guide.md)
+  * [Flashing Firmware](flashing.md)
+  * [Customizing Functionality](custom_quantum_functions.md)
+  * [Keymap Overview](keymap.md)
+
+* [Hardware](hardware.md)
+  * [AVR Processors](hardware_avr.md)
+  * [Drivers](hardware_drivers.md)
+
+* Reference
+  * [Keyboard Guidelines](hardware_keyboard_guidelines.md)
+  * [Config Options](config_options.md)
+  * [Keycodes](keycodes.md)
+  * [Coding Conventions - C](coding_conventions_c.md)
+  * [Coding Conventions - Python](coding_conventions_python.md)
+  * [Documentation Best Practices](documentation_best_practices.md)
+  * [Documentation Templates](documentation_templates.md)
+  * [Glossary](reference_glossary.md)
+  * [Unit Testing](unit_testing.md)
+  * [Useful Functions](ref_functions.md)
+  * [Configurator Support](reference_configurator_support.md)
+  * [info.json Format](reference_info_json.md)
+  * [Python CLI Development](cli_development.md)
+
+* [Features](features.md)
+  * [Basic Keycodes](keycodes_basic.md)
+  * [US ANSI Shifted Keys](keycodes_us_ansi_shifted.md)
+  * [Quantum Keycodes](quantum_keycodes.md)
+  * [Advanced Keycodes](feature_advanced_keycodes.md)
+  * [Audio](feature_audio.md)
+  * [Auto Shift](feature_auto_shift.md)
+  * [Backlight](feature_backlight.md)
+  * [Bluetooth](feature_bluetooth.md)
+  * [Bootmagic](feature_bootmagic.md)
+  * [Combos](feature_combo.md)
+  * [Command](feature_command.md)
+  * [Debounce API](feature_debounce_type.md)
+  * [DIP Switch](feature_dip_switch.md)
+  * [Dynamic Macros](feature_dynamic_macros.md)
+  * [Encoders](feature_encoders.md)
+  * [Grave Escape](feature_grave_esc.md)
+  * [Haptic Feedback](feature_haptic_feedback.md)
+  * [HD44780 LCD Controller](feature_hd44780.md)
+  * [Key Lock](feature_key_lock.md)
+  * [Layouts](feature_layouts.md)
+  * [Leader Key](feature_leader_key.md)
+  * [LED Matrix](feature_led_matrix.md)
+  * [Macros](feature_macros.md)
+  * [Mouse Keys](feature_mouse_keys.md)
+  * [OLED Driver](feature_oled_driver.md)
+  * [One Shot Keys](feature_advanced_keycodes.md#one-shot-keys)
+  * [Pointing Device](feature_pointing_device.md)
+  * [PS/2 Mouse](feature_ps2_mouse.md)
+  * [RGB Lighting](feature_rgblight.md)
+  * [RGB Matrix](feature_rgb_matrix.md)
+  * [Space Cadet](feature_space_cadet.md)
+  * [Split Keyboard](feature_split_keyboard.md)
+  * [Stenography](feature_stenography.md)
+  * [Swap Hands](feature_swap_hands.md)
+  * [Tap Dance](feature_tap_dance.md)
+  * [Terminal](feature_terminal.md)
+  * [Thermal Printer](feature_thermal_printer.md)
+  * [Unicode](feature_unicode.md)
+  * [Userspace](feature_userspace.md)
+  * [Velocikey](feature_velocikey.md)
+
+* For Makers and Modders
+  * [Hand Wiring Guide](hand_wire.md)
+  * [ISP Flashing Guide](isp_flashing_guide.md)
+  * [ARM Debugging Guide](arm_debugging.md)
+  * [I2C Driver](i2c_driver.md)
+  * [GPIO Controls](internals_gpio_control.md)
+  * [Proton C Conversion](proton_c_conversion.md)
+
+* For a Deeper Understanding
+  * [How Keyboards Work](how_keyboards_work.md)
+  * [Understanding QMK](understanding_qmk.md)
+
+* Other Topics
+  * [Using Eclipse with QMK](other_eclipse.md)
+  * [Using VSCode with QMK](other_vscode.md)
+  * [Support](support.md)
+  * [How to add translations](translating.md)
+
+* QMK Internals (In Progress)
+  * [Defines](internals_defines.md)
+  * [Input Callback Reg](internals_input_callback_reg.md)
+  * [Midi Device](internals_midi_device.md)
+  * [Midi Device Setup Process](internals_midi_device_setup_process.md)
+  * [Midi Util](internals_midi_util.md)
+  * [Send Functions](internals_send_functions.md)
+  * [Sysex Tools](internals_sysex_tools.md)

docs/arm_debugging.md

@@ -0,0 +1,87 @@
+# ARM Debugging usign Eclipse
+
+This page describes how to setup debugging for ARM MCUs using an SWD adapter and open-source/free tools. In this guide we will install GNU MCU Eclipse IDE for C/C++ Developers and OpenOCD together with all the necessary dependencies.
+
+This guide is catered towards advance users and assumes you can compile an ARM compatible keyboard on your machine using the MAKE flow.
+
+## Installing the software
+
+The main objective here is to get the MCU Eclipse IDE correctly installed on our machine. The necessary instructions are derived from [this](https://gnu-mcu-eclipse.github.io/install/) install guide.
+
+### The xPack Manager
+
+This tool is a software package manager and it is used to help us get the necessary dependencies.
+
+XPM runs using Node.js so grab that from [here](https://nodejs.org/en/). After installation, open a terminal and type `npm -v`. A reply with the version number means that the installation was successful.
+
+XPM installation instructions can be found [here](https://www.npmjs.com/package/xpm) and are OS specific. Entering `xpm --version` to your terminal should return the software version.
+
+### The ARM Toolchain
+
+Using XPM it is very easy to install the ARM toolchain. Enter the command `xpm install --global @gnu-mcu-eclipse/arm-none-eabi-gcc`.
+
+### Windows build tools
+
+If you are using windows you need to install this!
+
+`xpm install --global @gnu-mcu-eclipse/windows-build-tools`
+
+### Programmer/Debugger Drivers
+
+Now it's time to install your programmer's drivers. This tutorial was made using an ST-Link v2 which you can get from almost anywhere.
+If you have an ST-Link the drivers can be found [here](https://www.st.com/en/development-tools/stsw-link009.html) otherwise consult the manufacturer of your tool.
+
+### OpenOCD
+
+This dependency allows SWD access from GDB and it is essential for debugging. Run `xpm install --global @gnu-mcu-eclipse/openocd`.
+
+### Java
+
+Java is needed by Eclipse so please download it from [here](https://www.oracle.com/technetwork/java/javase/downloads/index.html).
+
+### GNU MCU Eclipse IDE
+
+Now its finally time to install the IDE. Use the Release page [here](https://github.com/gnu-mcu-eclipse/org.eclipse.epp.packages/releases/) to get the latest version.
+
+## Configuring Eclipse
+
+Open up the Eclipse IDE we just downloaded. To import our QMK directory select File -> Import -> C/C++ -> Existing code as Makefile Project. Select next and use Browse to select your QMK folder. In the tool-chain list select ARM Cross GCC and select Finish.
+
+Now you can see the QMK folder on the left hand side. Right click it and select Properties. On the left hand side, expand MCU and select ARM Toolchain Paths. Press xPack and OK. Repeat for OpenOCD Path  and if you are on windows for Build Tool Path. Select Apply and Close.
+
+Now its time to install the necessary MCU packages. Go to Packs perspective by selecting Window -> Open Perspective -> Others -> Packs. Now select the yellow refresh symbol next to the Packs tab. This will take a long time as it is requesting the MCU definitions from various places. If some of the links fail you can probably select Ignore.
+
+When this finishes you must find the MCU which we will be building/debugging for. In this example I will be using the STM32F3 series MCUs. On the left, select STMicroelectonics -> STM32F3 Series. On the middle window we can see the pack. Right click and select Install. Once that is done we can go back to the default perspective, Window -> Open Perspective -> Others -> C/C++.
+
+We need to let eclipse know the device we intent to build QMK on. Right click on the QMK folder -> Properties -> C/C++ Build -> Settings. Select the Devices tab and under devices select the appropriate variant of your MCU. For my example it is STM32F303CC
+
+While we are here let's setup the build command as well. Select C/C++ Build and then the Behavior tab. On the build command, replace `all` with your necessary make command. For example for a rev6 Planck with the default keymap this would be `planck/rev6:default`. Select Apply and Close.
+
+## Building
+
+If you have setup everything correctly pressing the hammer button should build the firmware for you and a .bin file should appear.
+
+## Debugging
+
+### Connecting the Debugger
+
+ARM MCUs use the Single Wire Debug (SWD) protocol which comprises of the clock (SWCLK) signal and the data (SWDIO) signal. Connecting this two wires and ground should be enough to allow full manipulation of the MCU. Here we assume that the keyboard will be powered though USB. The RESET signal is not necessary as we can manually assert it using the reset button. For a more advance setup, the SWO signal can be used which pipes printf and scanf asynchronously to the host but for our setup we will ignore it.
+
+NOTE: Make sure the SWCLK and SWDIO pins are not used in the matrix of your keyboard. If they are you can temporarily switch them for some other pins.
+
+### Configuring the Debugger
+
+Right click on your QMK folder, select Debug As -> Debug Configuration. Here double click on GDB OpenOCD Debugging. Select the debugger tab and enter the configuration necessary for your MCU. This might take some fiddling and googleing to find out. The default script for the STM32F3 is called stm32f3discovery.cfg. To let OpenOCD know, in the Config options enter `-f board/stm32f3discovery.cfg`.
+
+NOTE: In my case this configuration script requires editing to disable the reset assertion. The locations of the scripts can be found in the actual executable field usually under the path `openocd/version/.content/scripts/board`. Here I edited `reset_config srst_only` to `reset_config none`.
+
+Select Apply and Close.
+
+### Running the Debugger.
+
+Reset your keyboard.
+
+Press the bug icon and if all goes well you should soon find yourself in the debug perspective. Here the program counter will pause at the beginning of the main function and way for you to press Play. Most of the features of all debuggers work on ARM MCUs but for exact details google is your friend!
+
+
+Happy debugging!

docs/becoming_a_qmk_collaborator.md

@@ -0,0 +1,9 @@
+# Becoming a QMK Collaborator
+
+A QMK collaborator is a keyboard maker or designer that is interested in helping QMK grow and fully support their keyboard(s), and encouraging their users and customers to submit features, ideas, and keymaps. We're always looking to add more keyboards and collaborators, but we ask that they fulfill these requirements:
+
+* **Have a PCB available for sale.** Unfortunately there's just too much variation and complications with handwired keyboards.
+* **Maintain your keyboard in QMK.** This may just require an initial setup to get your keyboard working, but it could also include accommodating changes made to QMK's core that might break or render any custom code redundant.
+* **Approve and merge keymap pull requests for your keyboard.** We like to encourage users to contribute their keymaps for others to see and work from when creating their own.
+
+If you feel you meet these requirements, shoot us an email at hello@qmk.fm with an introduction and some links to your keyboard!

docs/breaking_changes.md

@@ -0,0 +1,107 @@
+# Breaking Changes
+
+This document describes QMK's Breaking Change process. A Breaking Change is any change which modifies how QMK behaves in a way that in incompatible or potentially dangerous. We limit these changes so that users can have confidence that updating their QMK tree will not break their keymaps.
+
+The breaking change period is when we will merge PR's that change QMK in dangerous or unexpected ways. There is a built-in period of testing so we are confident that any problems caused are rare or unable to be predicted.
+
+## What has been included in past Breaking Changes?
+
+* [2019 Aug 30](ChangeLog/20190830.md)
+
+## When is the next Breaking Change?
+
+The next Breaking Change is scheduled for Nov 29.
+
+### Important Dates
+
+* [x] 2019 Sep 21 - `future` is created. It will be rebased weekly.
+* [ ] 2019 Nov 01 - `future` closed to new PR's.
+* [ ] 2019 Nov 01 - Call for testers.
+* [ ] 2019 Nov 27 - `master` is locked, no PR's merged.
+* [ ] 2019 Nov 29 - Merge `future` to `master`.
+* [ ] 2019 Nov 30 - `master` is unlocked. PR's can be merged again.
+
+## What changes will be included?
+
+To see a list of breaking change candidates you can look at the [`breaking_change` label](https://github.com/qmk/qmk_firmware/pulls?q=is%3Aopen+label%3Abreaking_change+is%3Apr). New changes might be added between now and when `future` is closed, and a PR with that label applied is not guaranteed to be merged.
+
+If you want your breaking change to be included in this round you need to create a PR with the `breaking_change` label and have it accepted before `future` closes. After `future` closes no new breaking changes will be accepted.
+
+Criteria for acceptance:
+
+* PR is complete and ready to merge
+* PR has a ChangeLog
+
+# Checklists
+
+This section documents various processes we use when running the Breaking Changes process.
+
+## Rebase `future` from `master`
+
+This is run every Friday while `future` is open.
+
+Process:
+
+```
+cd qmk_firmware
+git checkout master
+git pull --ff-only
+git checkout future
+git rebase master
+git push --force
+```
+
+## Creating the `future` branch
+
+This happens immediately after the previous `future` branch is merged.
+
+* `qmk_firmware` git commands
+    * [ ] `git checkout master`
+    * [ ] `git pull --ff-only`
+    * [ ] `git checkout -b future`
+    * [ ] Edit `readme.md`
+        * [ ] Add a big notice at the top that this is a testing branch.
+        * [ ] Include a link to this document
+    * [ ] `git commit -m 'Branch point for <DATE> Breaking Change'`
+    * [ ] `git tag breakpoint_<YYYY>_<MM>_<DD>`
+    * [ ] `git tag <next_version>` # Prevent the breakpoint tag from confusing version incrementing
+    * [ ] `git push origin future`
+    * [ ] `git push --tags`
+
+## 4 Weeks Before Merge
+
+* `future` is now closed to new PR's, only fixes for current PR's may be merged
+* Post call for testers
+    * [ ] Discord
+    * [ ] GitHub PR
+    * [ ] https://reddit.com/r/olkb
+
+## 1 Week Before Merge
+
+* Announce that master will be closed from <2 Days Before> to <Day of Merge>
+    * [ ] Discord
+    * [ ] GitHub PR
+    * [ ] https://reddit.com/r/olkb
+
+## 2 Days Before Merge
+
+* Announce that master is closed for 2 days
+    * [ ] Discord
+    * [ ] GitHub PR
+    * [ ] https://reddit.com/r/olkb
+
+## Day Of Merge
+
+* `qmk_firmware` git commands
+    * [ ] `git checkout future`
+    * [ ] `git pull --ff-only`
+    * [ ] `git rebase origin/master`
+    * [ ] Edit `readme.md`
+        * [ ] Remove the notes about `future`
+    * [ ] Roll up the ChangeLog into one file.
+    * [ ] `git commit -m 'Merge point for <DATE> Breaking Change'`
+    * [ ] `git push origin future`
+* Github Actions
+    * [ ] Create a PR for `future`
+    * [ ] Make sure travis comes back clean
+    * [ ] Merge `future` PR

docs/cli.md

@@ -0,0 +1,166 @@
+# QMK CLI
+
+This page describes how to setup and use the QMK CLI.
+
+# Overview
+
+The QMK CLI makes building and working with QMK keyboards easier. We have provided a number of commands to simplify and streamline tasks such as obtaining and compiling the QMK firmware, creating keymaps, and more.
+
+* [Global CLI](#global-cli)
+* [Local CLI](#local-cli)
+* [CLI Commands](#cli-commands)
+
+# Requirements
+
+The CLI requires Python 3.5 or greater. We try to keep the number of requirements small but you will also need to install the packages listed in [`requirements.txt`](https://github.com/qmk/qmk_firmware/blob/master/requirements.txt).
+
+# Global CLI
+
+QMK provides an installable CLI that can be used to setup your QMK build environment, work with QMK, and which makes working with multiple copies of `qmk_firmware` easier. We recommend installing and updating this periodically.
+
+## Install Using Homebrew (macOS, some Linux)
+
+If you have installed [Homebrew](https://brew.sh) you can tap and install QMK:
+
+```
+brew tap qmk/qmk
+brew install qmk
+export QMK_HOME='~/qmk_firmware' # Optional, set the location for `qmk_firmware`
+qmk setup  # This will clone `qmk/qmk_firmware` and optionally set up your build environment
+```
+
+## Install Using easy_install or pip
+
+If your system is not listed above you can install QMK manually. First ensure that you have python 3.5 (or later) installed and have installed pip. Then install QMK with this command:
+
+```
+pip3 install qmk
+export QMK_HOME='~/qmk_firmware' # Optional, set the location for `qmk_firmware`
+qmk setup  # This will clone `qmk/qmk_firmware` and optionally set up your build environment
+```
+
+## Packaging For Other Operating Systems
+
+We are looking for people to create and maintain a `qmk` package for more operating systems. If you would like to create a package for your OS please follow these guidelines:
+
+* Follow best practices for your OS when they conflict with these guidelines
+    * Document why in a comment when you do deviate
+* Install using a virtualenv
+* Instruct the user to set the environment variable `QMK_HOME` to have the firmware source checked out somewhere other than `~/qmk_firmware`.
+
+# Local CLI
+
+If you do not want to use the global CLI there is a local CLI bundled with `qmk_firmware`. You can find it in `qmk_firmware/bin/qmk`. You can run the `qmk` command from any directory and it will always operate on that copy of `qmk_firmware`.
+
+**Example**:
+
+```
+$ ~/qmk_firmware/bin/qmk hello
+Ψ Hello, World!
+```
+
+## Local CLI Limitations
+
+There are some limitations to the local CLI compared to the global CLI:
+
+* The local CLI does not support `qmk setup` or `qmk clone`
+* The local CLI always operates on the same `qmk_firmware` tree, even if you have multiple repositories cloned.
+* The local CLI does not run in a virtualenv, so it's possible that dependencies will conflict
+
+# CLI Commands
+
+## `qmk compile`
+
+This command allows you to compile firmware from any directory. You can compile JSON exports from <https://config.qmk.fm> or compile keymaps in the repo.
+
+**Usage for Configurator Exports**:
+
+```
+qmk compile <configuratorExport.json>
+```
+
+**Usage for Keymaps**:
+
+```
+qmk compile -kb <keyboard_name> -km <keymap_name>
+```
+
+## `qmk cformat`
+
+This command formats C code using clang-format. Run it with no arguments to format all core code, or pass filenames on the command line to run it on specific files.
+
+**Usage**:
+
+```
+qmk cformat [file1] [file2] [...] [fileN]
+```
+
+## `qmk config`
+
+This command lets you configure the behavior of QMK. For the full `qmk config` documentation see [CLI Configuration](cli_configuration.md).
+
+**Usage**:
+
+```
+qmk config [-ro] [config_token1] [config_token2] [...] [config_tokenN]
+```
+
+## `qmk docs`
+
+This command starts a local HTTP server which you can use for browsing or improving the docs. Default port is 8936.
+
+**Usage**:
+
+```
+qmk docs [-p PORT]
+```
+
+## `qmk doctor`
+
+This command examines your environment and alerts you to potential build or flash problems.
+
+**Usage**:
+
+```
+qmk doctor
+```
+
+## `qmk list_keyboards`
+
+This command lists all the keyboards currently defined in `qmk_firmware`
+
+**Usage**:
+
+```
+qmk list_keyboards
+```
+
+## `qmk new-keymap`
+
+This command creates a new keymap based on a keyboard's existing default keymap.
+
+**Usage**:
+
+```
+qmk new-keymap [-kb KEYBOARD] [-km KEYMAP]
+```
+
+## `qmk pyformat`
+
+This command formats python code in `qmk_firmware`.
+
+**Usage**:
+
+```
+qmk pyformat
+```
+
+## `qmk pytest`
+
+This command runs the python test suite. If you make changes to python code you should ensure this runs successfully.
+
+**Usage**:
+
+```
+qmk pytest
+```

docs/cli_configuration.md

@@ -0,0 +1,121 @@
+# QMK CLI Configuration
+
+This document explains how `qmk config` works.
+
+# Introduction
+
+Configuration for QMK CLI is a key/value system. Each key consists of a subcommand and an argument name separated by a period. This allows for a straightforward and direct translation between config keys and the arguments they set.
+
+## Simple Example
+
+As an example let's look at the command `qmk compile --keyboard clueboard/66/rev4 --keymap default`.
+
+There are two command line arguments that could be read from configuration instead:
+
+* `compile.keyboard`
+* `compile.keymap`
+
+Let's set these now:
+
+```
+$ qmk config compile.keyboard=clueboard/66/rev4 compile.keymap=default
+compile.keyboard: None -> clueboard/66/rev4
+compile.keymap: None -> default
+Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini'
+```
+
+Now I can run `qmk compile` without specifying my keyboard and keymap each time.
+
+## Setting User Defaults
+
+Sometimes you want to share a setting between multiple commands. For example, multiple commands take the argument `--keyboard`. Rather than setting this value for every command you can set a user value which will be used by any command that takes that argument.
+
+Example:
+
+```
+$ qmk config user.keyboard=clueboard/66/rev4 user.keymap=default
+user.keyboard: None -> clueboard/66/rev4
+user.keymap: None -> default
+Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini'
+```
+
+# CLI Documentation (`qmk config`)
+
+The `qmk config` command is used to interact with the underlying configuration. When run with no argument it shows the current configuration. When arguments are supplied they are assumed to be configuration tokens, which are strings containing no spaces with the following form:
+
+    <subcommand|general|default>[.<key>][=<value>]
+
+## Setting Configuration Values
+
+You can set configuration values by putting an equal sign (=) into your config key. The key must always be the full `<section>.<key>` form.
+
+Example:
+
+```
+$ qmk config default.keymap=default
+default.keymap: None -> default
+Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini'
+```
+
+## Reading Configuration Values
+
+You can read configuration values for the entire configuration, a single key, or for an entire section. You can also specify multiple keys to display more than one value.
+
+### Entire Configuration Example
+
+    qmk config
+
+### Whole Section Example
+
+    qmk config compile
+
+### Single Key Example
+
+    qmk config compile.keyboard
+
+### Multiple Keys Example
+
+    qmk config user compile.keyboard compile.keymap
+
+## Deleting Configuration Values
+
+You can delete a configuration value by setting it to the special string `None`.
+
+Example:
+
+```
+$ qmk config default.keymap=None
+default.keymap: default -> None
+Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini'
+```
+
+## Multiple Operations
+
+You can combine multiple read and write operations into a single command. They will be executed and displayed in order:
+
+```
+$ qmk config compile default.keymap=default compile.keymap=None
+compile.keymap=skully
+compile.keyboard=clueboard/66_hotswap/gen1
+default.keymap: None -> default
+compile.keymap: skully -> None
+Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini'
+```
+
+# User Configuration Options
+
+| Key | Default Value | Description |
+|-----|---------------|-------------|
+| user.keyboard | None | The keyboard path (Example: `clueboard/66/rev4`) |
+| user.keymap | None | The keymap name (Example: `default`) |
+| user.name | None | The user's github username. |
+
+# All Configuration Options
+
+| Key | Default Value | Description |
+|-----|---------------|-------------|
+| compile.keyboard | None | The keyboard path (Example: `clueboard/66/rev4`) |
+| compile.keymap | None | The keymap name (Example: `default`) |
+| hello.name | None | The name to greet when run. |
+| new_keyboard.keyboard | None | The keyboard path (Example: `clueboard/66/rev4`) |
+| new_keyboard.keymap | None | The keymap name (Example: `default`) |

docs/cli_development.md

@@ -0,0 +1,175 @@
+# QMK CLI Development
+
+This document has useful information for developers wishing to write new `qmk` subcommands.
+
+# Overview
+
+The QMK CLI operates using the subcommand pattern made famous by git. The main `qmk` script is simply there to setup the environment and pick the correct entrypoint to run. Each subcommand is a self-contained module with an entrypoint (decorated by `@cli.subcommand()`) that performs some action and returns a shell returncode, or None.
+
+# Subcommands
+
+[MILC](https://github.com/clueboard/milc) is the CLI framework `qmk` uses to handle argument parsing, configuration, logging, and many other features. It lets you focus on writing your tool without wasting your time writing glue code.
+
+Subcommands in the local CLI are always found in `qmk_firmware/lib/python/qmk/cli`.
+
+Let's start by looking at an example subcommand. This is `lib/python/qmk/cli/hello.py`:
+
+```python
+"""QMK Python Hello World
+
+This is an example QMK CLI script.
+"""
+from milc import cli
+
+
+@cli.argument('-n', '--name', default='World', help='Name to greet.')
+@cli.subcommand('QMK Hello World.')
+def hello(cli):
+    """Log a friendly greeting.
+    """
+    cli.log.info('Hello, %s!', cli.config.hello.name)
+```
+
+First we import the `cli` object from `milc`. This is how we interact with the user and control the script's behavior. We use `@cli.argument()` to define a command line flag, `--name`. This also creates a configuration variable named `hello.name` (and the corresponding `user.name`) which the user can set so they don't have to specify the argument. The `cli.subcommand()` decorator designates this function as a subcommand. The name of the subcommand will be taken from the name of the function.
+
+Once inside our function we find a typical "Hello, World!" program. We use `cli.log` to access the underlying [Logger Object](https://docs.python.org/3.5/library/logging.html#logger-objects), whose behavior is user controllable. We also access the value for name supplied by the user as `cli.config.hello.name`. The value for `cli.config.hello.name` will be determined by looking at the `--name` argument supplied by the user, if not provided it will use the value in the `qmk.ini` config file, and if neither of those is provided it will fall back to the default supplied in the `cli.argument()` decorator.
+
+# User Interaction
+
+MILC and the QMK CLI have several nice tools for interacting with the user. Using these standard tools will allow you to colorize your text for easier interactions, and allow the user to control when and how that information is displayed and stored.
+
+## Printing Text
+
+There are two main methods for outputting text in a subcommand- `cli.log` and `cli.echo()`. They operate in similar ways but you should prefer to use `cli.log.info()` for most general purpose printing.
+
+You can use special tokens to colorize your text, to make it easier to understand the output of your program. See [Colorizing Text](#colorizing-text) below.
+
+Both of these methods support built-in string formatting using python's [printf style string format operations](https://docs.python.org/3.5/library/stdtypes.html#old-string-formatting). You can use tokens such as `%s` and `%d` within your text strings then pass the values as arguments. See our Hello, World program above for an example.
+
+You should never use the format operator (`%`) directly, always pass values as arguments.
+
+### Logging (`cli.log`)
+
+The `cli.log` object gives you access to a [Logger Object](https://docs.python.org/3.5/library/logging.html#logger-objects). We have configured our log output to show the user a nice emoji for each log level (or the log level name if their terminal does not support unicode.) This way the user can tell at a glance which messages are most important when something goes wrong.
+
+The default log level is `INFO`. If the user runs `qmk -v <subcommand>` the default log level will be set to `DEBUG`.
+
+| Function | Emoji |
+|----------|-------|
+| cli.log.critical | `{bg_red}{fg_white}¬_¬{style_reset_all}` |
+| cli.log.error | `{fg_red}☒{style_reset_all}` |
+| cli.log.warning | `{fg_yellow}⚠{style_reset_all}` |
+| cli.log.info | `{fg_blue}Ψ{style_reset_all}` |
+| cli.log.debug | `{fg_cyan}☐{style_reset_all}` |
+| cli.log.notset | `{style_reset_all}¯\\_(o_o)_/¯` |
+
+### Printing (`cli.echo`)
+
+Sometimes you simply need to print text outside of the log system. This is appropriate if you are outputting fixed data or writing out something that should never be logged. Most of the time you should prefer `cli.log.info()` over `cli.echo`.
+
+### Colorizing Text
+
+You can colorize the output of your text by including color tokens within text. Use color to highlight, not to convey information. Remember that the user can disable color, and your subcommand should still be usable if they do.
+
+You should generally avoid setting the background color, unless it's integral to what you are doing. Remember that users have a lot of preferences when it comes to their terminal color, so you should pick colors that work well against both black and white backgrounds.
+
+Colors prefixed with 'fg' will affect the foreground (text) color. Colors prefixed with 'bg' will affect the background color.
+
+| Color | Background | Extended Background | Foreground | Extended Foreground|
+|-------|------------|---------------------|------------|--------------------|
+| Black | {bg_black} | {bg_lightblack_ex} | {fg_black} | {fg_lightblack_ex} |
+| Blue | {bg_blue} | {bg_lightblue_ex} | {fg_blue} | {fg_lightblue_ex} |
+| Cyan | {bg_cyan} | {bg_lightcyan_ex} | {fg_cyan} | {fg_lightcyan_ex} |
+| Green | {bg_green} | {bg_lightgreen_ex} | {fg_green} | {fg_lightgreen_ex} |
+| Magenta | {bg_magenta} | {bg_lightmagenta_ex} | {fg_magenta} | {fg_lightmagenta_ex} |
+| Red | {bg_red} | {bg_lightred_ex} | {fg_red} | {fg_lightred_ex} |
+| White | {bg_white} | {bg_lightwhite_ex} | {fg_white} | {fg_lightwhite_ex} |
+| Yellow | {bg_yellow} | {bg_lightyellow_ex} | {fg_yellow} | {fg_lightyellow_ex} |
+
+There are also control sequences that can be used to change the behavior of
+ANSI output:
+
+| Control Sequences | Description |
+|-------------------|-------------|
+| {style_bright} | Make the text brighter |
+| {style_dim} | Make the text dimmer |
+| {style_normal} | Make the text normal (neither `{style_bright}` nor `{style_dim}`) |
+| {style_reset_all} | Reset all text attributes to default. (This is automatically added to the end of every string.) |
+| {bg_reset} | Reset the background color to the user's default |
+| {fg_reset} | Reset the foreground color to the user's default |
+
+# Arguments and Configuration
+
+QMK handles the details of argument parsing and configuration for you. When you add a new argument it is automatically incorporated into the config tree based on your subcommand's name and the long name of the argument. You can access this configuration in `cli.config`, using either attribute-style access (`cli.config.<subcommand>.<argument>`) or dictionary-style access (`cli.config['<subcommand>']['<argument>']`).
+
+Under the hood QMK uses [ConfigParser](https://docs.python.org/3/library/configparser.html) to store configurations. This gives us an easy and straightforward way to represent the configuration in a human-editable way. We have wrapped access to this configuration to provide some nicities that ConfigParser does not normally have.
+
+## Reading Configuration Values
+
+You can interact with `cli.config` in all the ways you'd normally expect. For example the `qmk compile` command gets the keyboard name from `cli.config.compile.keyboard`. It does not need to know whether that value came from the command line, an environment variable, or the configuration file.
+
+Iteration is also supported:
+
+```
+for section in cli.config:
+    for key in cli.config[section]:
+        cli.log.info('%s.%s: %s', section, key, cli.config[section][key])
+```
+
+## Setting Configuration Values
+
+You can set configuration values in the usual ways.
+
+Dictionary style:
+
+```
+cli.config['<section>']['<key>'] = <value>
+```
+
+Attribute style:
+
+```
+cli.config.<section>.<key> = <value>
+```
+
+## Deleting Configuration Values
+
+You can delete configuration values in the usual ways.
+
+Dictionary style:
+
+```
+del(cli.config['<section>']['<key>'])
+```
+
+Attribute style:
+
+```
+del(cli.config.<section>.<key>)
+```
+
+## Writing The Configuration File
+
+The configuration is not written out when it is changed. Most commands do not need to do this. We prefer to have the user change their configuration deliberitely using `qmk config`.
+
+You can use `cli.save_config()` to write out the configuration.
+
+## Excluding Arguments From Configuration
+
+Some arguments should not be propagated to the configuration file. These can be excluded by adding `arg_only=True` when creating the argument.
+
+Example:
+
+```
+@cli.argument('-o', '--output', arg_only=True, help='File to write to')
+@cli.argument('filename', arg_only=True, help='Configurator JSON file')
+@cli.subcommand('Create a keymap.c from a QMK Configurator export.')
+def json_keymap(cli):
+    pass
+```
+
+You will only be able to access these arguments using `cli.args`. For example:
+
+```
+cli.log.info('Reading from %s and writing to %s', cli.args.filename, cli.args.output)
+```

docs/coding_conventions_c.md

@@ -0,0 +1,58 @@
+# Coding Conventions (C)
+
+Most of our style is pretty easy to pick up on, but right now it's not entirely consistent. You should match the style of the code surrounding your change, but if that code is inconsistent or unclear use the following guidelines:
+
+* We indent using four (4) spaces (soft tabs)
+* We use a modified One True Brace Style
+  * Opening Brace: At the end of the same line as the statement that opens the block
+  * Closing Brace: Lined up with the first character of the statement that opens the block
+  * Else If: Place the closing brace at the beginning of the line and the next opening brace at the end of the same line.
+  * Optional Braces: Always include optional braces.
+    * Good: if (condition) { return false; }
+    * Bad: if (condition) return false;
+* We encourage use of C style comments: `/* */`
+  * Think of them as a story describing the feature
+  * Use them liberally to explain why particular decisions were made.
+  * Do not write obvious comments
+  * If you not sure if a comment is obvious, go ahead and include it.
+* In general we don't wrap lines, they can be as long as needed. If you do choose to wrap lines please do not wrap any wider than 76 columns.
+* We use `#pragma once` at the start of header files rather than old-style include guards (`#ifndef THIS_FILE_H`, `#define THIS_FILE_H`, ..., `#endif`)
+* We accept both forms of preprocessor if's: `#ifdef DEFINED` and `#if defined(DEFINED)`
+  * If you are not sure which to prefer use the `#if defined(DEFINED)` form.
+  * Do not change existing code from one style to the other, except when moving to a multiple condition `#if`.
+  * Do not put whitespace between `#` and `if`.
+  * When deciding how (or if) to indent directives keep these points in mind:
+    * Readability is more important than consistency.
+    * Follow the file's existing style. If the file is mixed follow the style that makes sense for the section you are modifying.
+    * When choosing to indent you can follow the indention level of the surrounding C code, or preprocessor directives can have their own indent level. Choose the style that best communicates the intent of your code.
+
+Here is an example for easy reference:
+
+```c
+/* Enums for foo */
+enum foo_state {
+    FOO_BAR,
+    FOO_BAZ,
+};
+
+/* Returns a value */
+int foo(void) {
+    if (some_condition) {
+        return FOO_BAR;
+    } else {
+        return -1;
+    }
+}
+```
+
+# Auto-formatting with clang-format
+
+[Clang-format](https://clang.llvm.org/docs/ClangFormat.html) is part of LLVM and can automatically format your code for you, because ain't nobody got time to do it manually. We supply a configuration file for it that applies most of the coding conventions listed above. It will only change whitespace and newlines, so you will still have to remember to include optional braces yourself.
+
+Use the [full LLVM installer](http://llvm.org/builds/) to get clang-format on Windows, or use `sudo apt install clang-format` on Ubuntu.
+
+If you run it from the command-line, pass `-style=file` as an option and it will automatically find the .clang-format configuration file in the QMK root directory.
+
+If you use VSCode, the standard C/C++ plugin supports clang-format, alternatively there is a [separate extension](https://marketplace.visualstudio.com/items?itemName=LLVMExtensions.ClangFormat) for it.
+
+Some things (like LAYOUT macros) are destroyed by clang-format, so either don't run it on those files, or wrap the sensitive code in `// clang-format off` and `// clang-format on`.

docs/coding_conventions_python.md

@@ -0,0 +1,314 @@
+# Coding Conventions (Python)
+
+Most of our style follows PEP8 with some local modifications to make things less nit-picky. 
+
+* We target Python 3.5 for compatability with all supported platforms.
+* We indent using four (4) spaces (soft tabs)
+* We encourage liberal use of comments
+  * Think of them as a story describing the feature
+  * Use them liberally to explain why particular decisions were made.
+  * Do not write obvious comments
+  * If you not sure if a comment is obvious, go ahead and include it.
+* We require useful docstrings for all functions.
+* In general we don't wrap lines, they can be as long as needed. If you do choose to wrap lines please do not wrap any wider than 76 columns.
+* Some of our practices conflict with the wider python community to make our codebase more approachable to non-pythonistas.
+
+# YAPF
+
+You can use [yapf](https://github.com/google/yapf) to style your code. We provide a config in [setup.cfg](setup.cfg).
+
+# Imports
+
+We don't have a hard and fast rule for when to use `import ...` vs `from ... import ...`. Understandability and maintainability is our ultimate goal.
+
+Generally we prefer to import specific function and class names from a module to keep code shorter and easier to understand. Sometimes this results in a name that is ambiguous, and in such cases we prefer to import the module instead. You should avoid using the "as" keyword when importing, unless you are importing a compatability module.
+
+Imports should be one line per module. We group import statements together using the standard python rules- system, 3rd party, local.
+
+Do not use `from foo import *`. Supply a list of objects you want to import instead, or import the whole module.
+
+## Import Examples
+
+Good:
+
+```
+from qmk import effects
+
+effects.echo()
+```
+
+Bad:
+
+```
+from qmk.effects import echo
+
+echo()  # It's unclear where echo comes from
+```
+
+Good:
+
+```
+from qmk.keymap import compile_firmware
+
+compile_firmware()
+```
+
+OK, but the above is better:
+
+```
+import qmk.keymap
+
+qmk.keymap.compile_firmware()
+```
+
+# Statements
+
+One statement per line.
+
+Even when allowed (EG `if foo: bar`) we do not combine 2 statements onto a single line.
+
+# Naming
+
+`module_name`, `package_name`, `ClassName`, `method_name`, `ExceptionName`, `function_name`, `GLOBAL_CONSTANT_NAME`, `global_var_name`, `instance_var_name`, `function_parameter_name`, `local_var_name`.
+
+Function names, variable names, and filenames should be descriptive; eschew abbreviation. In particular, do not use abbreviations that are ambiguous or unfamiliar to readers outside your project, and do not abbreviate by deleting letters within a word.
+
+Always use a .py filename extension. Never use dashes.
+
+## Names to Avoid
+
+* single character names except for counters or iterators. You may use "e" as an exception identifier in try/except statements.
+* dashes (-) in any package/module name
+* __double_leading_and_trailing_underscore__ names (reserved by Python)
+
+# Docstrings
+
+To maintain consistency with our docstrings we've set out the following guidelines.
+
+* Use markdown formatting
+* Always use triple-dquote docstrings with at least one linebreak: `"""\n"""`
+* First line is a short (< 70 char) description of what the function does
+* If you need more in your docstring leave a blank line between the description and the rest.
+* Start indented lines at the same indent level as the opening triple-dquote
+* Document all function arguments using the format described below
+* If present, Args:, Returns:, and Raises: should be the last three things in the docstring, separated by a blank line each.
+
+## Simple docstring example
+
+```
+def my_awesome_function():
+    """Return the number of seconds since 1970 Jan 1 00:00 UTC.
+    """
+    return int(time.time())
+```
+
+## Complex docstring example
+
+```
+def my_awesome_function():
+    """Return the number of seconds since 1970 Jan 1 00:00 UTC.
+
+    This function always returns an integer number of seconds.
+    """
+    return int(time.time())
+```
+
+## Function arguments docstring example
+
+```
+def my_awesome_function(start=None, offset=0):
+    """Return the number of seconds since 1970 Jan 1 00:00 UTC.
+
+    This function always returns an integer number of seconds.
+
+
+    Args:
+        start
+            The time to start at instead of 1970 Jan 1 00:00 UTC
+
+        offset
+            Return an answer that has this number of seconds subtracted first
+
+    Returns:
+        An integer describing a number of seconds.
+
+    Raises:
+        ValueError
+            When `start` or `offset` are not positive numbers
+    """
+    if start < 0 or offset < 0:
+        raise ValueError('start and offset must be positive numbers.')
+
+    if not start:
+        start = time.time()
+
+    return int(start - offset)
+```
+
+# Exceptions
+
+Exceptions are used to handle exceptional situations. They should not be used for flow control. This is a break from the python norm of "ask for forgiveness." If you are catching an exception it should be to handle a situation that is unusual.
+
+If you use a catch-all exception for any reason you must log the exception and stacktrace using cli.log.
+
+Make your try/except blocks as short as possible. If you need a lot of try statements you may need to restructure your code.
+
+# Tuples
+
+When defining one-item tuples always include a trailing comma so that it is obvious you are using a tuple. Do not rely on implicit one-item tuple unpacking. Better still use a list which is unambiguous.
+
+This is particularly important when using the printf-style format strings that are commonly used.
+
+# Lists and Dictionaries
+
+We have configured YAPF to differentiate between sequence styles with a trailing comma. When a trailing comma is omitted YAPF will format the sequence as a single line. When a trailing comma is included YAPF will format the sequence with one item per line.
+
+You should generally prefer to keep short definition on a single line. Break out to multiple lines sooner rather than later to aid readability and maintainability.
+
+# Parentheses
+
+Avoid excessive parentheses, but do use parentheses to make code easier to understand. Do not use them in return statements unless you are explicitly returning a tuple, or it is part of a math expression.
+
+# Format Strings
+
+We generally prefer printf-style format strings. Example:
+
+```
+name = 'World'
+print('Hello, %s!' % (name,))
+```
+
+This style is used by the logging module, which we make use of extensively, and we have adopted it in other places for consistency. It is also more familiar to C programmers, who are a big part of our casual audience.
+
+Our included CLI module has support for using these without using the percent (%) operator. Look at `cli.echo()` and the various `cli.log` functions (EG, `cli.log.info()`) for more details.
+
+# Comprehensions & Generator Expressions
+
+We encourage the liberal use of comprehensions and generators, but do not let them get too complex. If you need complexity fall back to a for loop that is easier to understand.
+
+# Lambdas
+
+OK to use but probably should be avoided. With comprehensions and generators the need for lambdas is not as strong as it once was.
+
+# Conditional Expressions
+
+OK in variable assignment, but otherwise should be avoided.
+
+Conditional expressions are if statements that are in line with code. For example:
+
+```
+x = 1 if cond else 2
+```
+
+It's generally not a good idea to use these as function arguments, sequence items, etc. It's too easy to overlook.
+
+# Default Argument Values
+
+Encouraged, but values must be immutable objects.
+
+When specifying default values in argument lists always be careful to specify objects that can't be modified in place. If you use a mutable object the changes you make will persist between calls, which is usually not what you want. Even if that is what you intend to do it is confusing for others and will hinder understanding.
+
+Bad:
+
+```
+def my_func(foo={}):
+    pass
+```
+
+Good:
+
+```
+def my_func(foo=None):
+    if not foo:
+        foo = {}
+```
+
+# Properties
+
+Always use properties instead of getter and setter functions.
+
+```
+class Foo(object):
+    def __init__(self):
+        self._bar = None
+
+    @property
+    def bar(self):
+        return self._bar
+
+    @bar.setter
+    def bar(self, bar):
+        self._bar = bar
+```
+
+# True/False Evaluations
+
+You should generally prefer the implicit True/False evaluation in if statements, rather than checking equivalency.
+
+Bad:
+
+```
+if foo == True:
+    pass
+
+if bar == False:
+    pass
+```
+
+Good:
+
+```
+if foo:
+    pass
+
+if not bar:
+    pass
+```
+
+# Decorators
+
+Use when appropriate. Try to avoid too much magic unless it helps with understanding.
+
+# Threading and Multiprocessing
+
+Should be avoided. If you need this you will have to make a strong case before we merge your code.
+
+# Power Features
+
+Python is an extremely flexible language and gives you many fancy features such as custom metaclasses, access to bytecode, on-the-fly compilation, dynamic inheritance, object reparenting, import hacks, reflection, modification of system internals, etc.
+
+Don't use these.
+
+Performance is not a critical concern for us, and code understandability is. We want our codebase to be approachable by someone who only has a day or two to play with it. These features generally come with a cost to easy understanding, and we would prefer to have code that can be readily understood over faster or more compact code.
+
+Note that some standard library modules use these techniques and it is ok to make use of those modules. But please keep readability and understandability in mind when using them.
+
+# Type Annotated Code
+
+For now we are not using any type annotation system, and would prefer that code remain unannotated. We may revisit this in the future.
+
+# Function length
+
+Prefer small and focused functions.
+
+We recognize that long functions are sometimes appropriate, so no hard limit is placed on function length. If a function exceeds about 40 lines, think about whether it can be broken up without harming the structure of the program.
+
+Even if your long function works perfectly now, someone modifying it in a few months may add new behavior. This could result in bugs that are hard to find. Keeping your functions short and simple makes it easier for other people to read and modify your code.
+
+You could find long and complicated functions when working with some code. Do not be intimidated by modifying existing code: if working with such a function proves to be difficult, you find that errors are hard to debug, or you want to use a piece of it in several different contexts, consider breaking up the function into smaller and more manageable pieces.
+
+# FIXMEs
+
+It is OK to leave FIXMEs in code. Why? Encouraging people to at least document parts of code that need to be thought out more (or that are confusing) is better than leaving this code undocumented.
+
+All FIXMEs should be formatted like:
+
+```
+FIXME(username): Revisit this code when the frob feature is done.
+```
+
+...where username is your GitHub username.
+
+# Unit Tests
+
+These are good. We should have some one day.

docs/compatible_microcontrollers.md

@@ -0,0 +1,25 @@
+# Atmel AVR
+
+QMK should run on any Atmel AVR processor with enough Flash. It has been tested on the following:
+
+* ATmega32U4 ([PJRC Teensy 2.0](http://www.pjrc.com/teensy/))
+* AT90USB1286 ([PJRC Teensy++ 2.0](http://www.pjrc.com/teensy/))
+* AT90USB1287 ([Atmel USBKEY](http://www.atmel.com/tools/AT90USBKEY.aspx))
+* ATmega168P with using [V-USB](http://www.obdev.at/products/vusb/index.html)
+* ATmega328P with using [V-USB](http://www.obdev.at/products/vusb/index.html)
+* ATmega32U2
+* AT90USB1286, 646, 647 should work
+* AT90USB162 testing...
+
+NOTE: To enable full features of firmware you'll need 32KB flash size.
+
+Please add any tested microcontrollers to this list.
+
+# ARM
+
+You can also use any ARM processor that [ChibiOS](http://www.chibios.org) supports. The following processors have been tested:
+
+* [Kinetis MKL26Z64](http://www.nxp.com/products/microcontrollers-and-processors/arm-processors/kinetis-cortex-m-mcus/l-series-ultra-low-power-m0-plus/kinetis-kl2x-48-mhz-usb-ultra-low-power-microcontrollers-mcus-based-on-arm-cortex-m0-plus-core:KL2x)
+* [Kinetis MK20DX128](http://www.nxp.com/assets/documents/data/en/data-sheets/K20P64M50SF0.pdf)
+* [Kinetis MK20DX128](http://www.nxp.com/assets/documents/data/en/data-sheets/K20P64M50SF0.pdf)
+* [Kinetis MK20DX256](http://www.nxp.com/products/microcontrollers-and-processors/arm-processors/kinetis-cortex-m-mcus/k-series-performance-m4/k2x-usb/kinetis-k20-72-mhz-full-speed-usb-mixed-signal-integration-microcontrollers-mcus-based-on-arm-cortex-m4-core:K20_72)

docs/config_options.md

@@ -0,0 +1,380 @@
+# Configuring QMK
+
+QMK is nearly infinitely configurable. Wherever possible we err on the side of allowing users to customize their keyboard, even at the expense of code size. That level of flexibility makes for a daunting configuration experience, however.
+
+There are two main types of configuration files in QMK- `config.h` and `rules.mk`. These files exist at various levels in QMK and all files of the same type are combined to build the final configuration. The levels, from lowest priority to highest priority, are:
+
+* QMK Default
+* Keyboard
+* Folders (Up to 5 levels deep)
+* Keymap
+
+## QMK Default
+
+Every available setting in QMK has a default. If that setting is not set at the Keyboard, Folder, or Keymap level this is the setting that will be used.
+
+## Keyboard
+
+This level contains config options that should apply to the whole keyboard. Some settings won't change in revisions, or most keymaps. Other settings are merely defaults for this keyboard and can be overridden by folders and/or keymaps.
+
+## Folders
+
+Some keyboards have folders and sub-folders to allow for different hardware configurations. Most keyboards only go 1 folder deep, but QMK supports structures up to 5 folders deep. Each folder can have its own `config.h` and `rules.mk` files that are incorporated into the final configuration.
+
+## Keymap
+
+This level contains all of the options for that particular keymap. If you wish to override a previous declaration, you can use `#undef <variable>` to undefine it, where you can then redefine it without an error.
+
+# The `config.h` File
+
+This is a C header file that is one of the first things included, and will persist over the whole project (if included). Lots of variables can be set here and accessed elsewhere. The `config.h` file shouldn't be including other `config.h` files, or anything besides this:
+
+    #include "config_common.h"
+
+
+## Hardware Options
+* `#define VENDOR_ID 0x1234`
+  * defines your VID, and for most DIY projects, can be whatever you want
+* `#define PRODUCT_ID 0x5678`
+  * defines your PID, and for most DIY projects, can be whatever you want
+* `#define DEVICE_VER 0`
+  * defines the device version (often used for revisions)
+* `#define MANUFACTURER Me`
+  * generally who/whatever brand produced the board
+* `#define PRODUCT Board`
+  * the name of the keyboard
+* `#define DESCRIPTION a keyboard`
+  * a short description of what the keyboard is
+* `#define MATRIX_ROWS 5`
+  * the number of rows in your keyboard's matrix
+* `#define MATRIX_COLS 15`
+  * the number of columns in your keyboard's matrix
+* `#define MATRIX_ROW_PINS { D0, D5, B5, B6 }`
+  * pins of the rows, from top to bottom
+* `#define MATRIX_COL_PINS { F1, F0, B0, C7, F4, F5, F6, F7, D4, D6, B4, D7 }`
+  * pins of the columns, from left to right
+* `#define UNUSED_PINS { D1, D2, D3, B1, B2, B3 }`
+  * pins unused by the keyboard for reference
+* `#define MATRIX_HAS_GHOST`
+  * define is matrix has ghost (unlikely)
+* `#define DIODE_DIRECTION COL2ROW`
+  * COL2ROW or ROW2COL - how your matrix is configured. COL2ROW means the black mark on your diode is facing to the rows, and between the switch and the rows.
+* `#define DIRECT_PINS { { F1, F0, B0, C7 }, { F4, F5, F6, F7 } }`
+  * pins mapped to rows and columns, from left to right. Defines a matrix where each switch is connected to a separate pin and ground.
+* `#define AUDIO_VOICES`
+  * turns on the alternate audio voices (to cycle through)
+* `#define C4_AUDIO`
+  * enables audio on pin C4
+* `#define C5_AUDIO`
+  * enables audio on pin C5
+* `#define C6_AUDIO`
+  * enables audio on pin C6
+* `#define B5_AUDIO`
+  * enables audio on pin B5 (duophony is enables if one of B[5-7]\_AUDIO is enabled along with one of C[4-6]\_AUDIO)
+* `#define B6_AUDIO`
+  * enables audio on pin B6 (duophony is enables if one of B[5-7]\_AUDIO is enabled along with one of C[4-6]\_AUDIO)
+* `#define B7_AUDIO`
+  * enables audio on pin B7 (duophony is enables if one of B[5-7]\_AUDIO is enabled along with one of C[4-6]\_AUDIO)
+* `#define BACKLIGHT_PIN B7`
+  * pin of the backlight
+* `#define BACKLIGHT_LEVELS 3`
+  * number of levels your backlight will have (maximum 15 excluding off)
+* `#define BACKLIGHT_BREATHING`
+  * enables backlight breathing
+* `#define BREATHING_PERIOD 6`
+  * the length of one backlight "breath" in seconds
+* `#define DEBOUNCE 5`
+  * the delay when reading the value of the pin (5 is default)
+* `#define LOCKING_SUPPORT_ENABLE`
+  * mechanical locking support. Use KC_LCAP, KC_LNUM or KC_LSCR instead in keymap
+* `#define LOCKING_RESYNC_ENABLE`
+  * tries to keep switch state consistent with keyboard LED state
+* `#define IS_COMMAND() (get_mods() == MOD_MASK_SHIFT)`
+  * key combination that allows the use of magic commands (useful for debugging)
+* `#define USB_MAX_POWER_CONSUMPTION 500`
+  * sets the maximum power (in mA) over USB for the device (default: 500)
+* `#define USB_POLLING_INTERVAL_MS 10`
+  * sets the USB polling rate in milliseconds for the keyboard, mouse, and shared (NKRO/media keys) interfaces
+* `#define F_SCL 100000L`
+  * sets the I2C clock rate speed for keyboards using I2C. The default is `400000L`, except for keyboards using `split_common`, where the default is `100000L`.
+
+## Features That Can Be Disabled
+
+If you define these options you will disable the associated feature, which can save on code size.
+
+* `#define NO_DEBUG`
+  * disable debugging
+* `#define NO_PRINT`
+  * disable printing/debugging using hid_listen
+* `#define NO_ACTION_LAYER`
+  * disable layers
+* `#define NO_ACTION_TAPPING`
+  * disable tap dance and other tapping features
+* `#define NO_ACTION_ONESHOT`
+  * disable one-shot modifiers
+* `#define NO_ACTION_MACRO`
+  * disable old style macro handling: MACRO() & action_get_macro
+* `#define NO_ACTION_FUNCTION`
+  * disable calling of action_function() from the fn_actions array (deprecated)
+
+## Features That Can Be Enabled
+
+If you define these options you will enable the associated feature, which may increase your code size.
+
+* `#define FORCE_NKRO`
+  * NKRO by default requires to be turned on, this forces it on during keyboard startup regardless of EEPROM setting. NKRO can still be turned off but will be turned on again if the keyboard reboots.
+* `#define STRICT_LAYER_RELEASE`
+  * force a key release to be evaluated using the current layer stack instead of remembering which layer it came from (used for advanced cases)
+
+## Behaviors That Can Be Configured
+
+* `#define TAPPING_TERM 200`
+  * how long before a tap becomes a hold, if set above 500, a key tapped during the tapping term will turn it into a hold too
+* `#define TAPPING_TERM_PER_KEY`
+  * enables handling for per key `TAPPING_TERM` settings
+* `#define RETRO_TAPPING`
+  * tap anyway, even after TAPPING_TERM, if there was no other key interruption between press and release
+  * See [Retro Tapping](feature_advanced_keycodes.md#retro-tapping) for details
+* `#define TAPPING_TOGGLE 2`
+  * how many taps before triggering the toggle
+* `#define PERMISSIVE_HOLD`
+  * makes tap and hold keys trigger the hold if another key is pressed before releasing, even if it hasn't hit the `TAPPING_TERM`
+  * See [Permissive Hold](feature_advanced_keycodes.md#permissive-hold) for details
+* `#define IGNORE_MOD_TAP_INTERRUPT`
+  * makes it possible to do rolling combos (zx) with keys that convert to other keys on hold, by enforcing the `TAPPING_TERM` for both keys.
+  * See [Mod tap interrupt](feature_advanced_keycodes.md#ignore-mod-tap-interrupt) for details
+* `#define TAPPING_FORCE_HOLD`
+  * makes it possible to use a dual role key as modifier shortly after having been tapped
+  * See [Hold after tap](feature_advanced_keycodes.md#tapping-force-hold)
+  * Breaks any Tap Toggle functionality (`TT` or the One Shot Tap Toggle)
+* `#define LEADER_TIMEOUT 300`
+  * how long before the leader key times out
+    * If you're having issues finishing the sequence before it times out, you may need to increase the timeout setting. Or you may want to enable the `LEADER_PER_KEY_TIMING` option, which resets the timeout after each key is tapped.
+* `#define LEADER_PER_KEY_TIMING`
+  * sets the timer for leader key chords to run on each key press rather than overall
+* `#define LEADER_KEY_STRICT_KEY_PROCESSING`
+  * Disables keycode filtering for Mod-Tap and Layer-Tap keycodes. Eg, if you enable this, you would need to specify `MT(MOD_CTL, KC_A)` if you want to use `KC_A`.
+* `#define ONESHOT_TIMEOUT 300`
+  * how long before oneshot times out
+* `#define ONESHOT_TAP_TOGGLE 2`
+  * how many taps before oneshot toggle is triggered
+* `#define QMK_KEYS_PER_SCAN 4`
+  * Allows sending more than one key per scan. By default, only one key event gets
+    sent via `process_record()` per scan. This has little impact on most typing, but
+    if you're doing a lot of chords, or your scan rate is slow to begin with, you can
+    have some delay in processing key events. Each press and release is a separate
+    event. For a keyboard with 1ms or so scan times, even a very fast typist isn't
+    going to produce the 500 keystrokes a second needed to actually get more than a
+    few ms of delay from this. But if you're doing chording on something with 3-4ms
+    scan times? You probably want this.
+* `#define COMBO_COUNT 2`
+  * Set this to the number of combos that you're using in the [Combo](feature_combo.md) feature.
+* `#define COMBO_TERM 200`
+  * how long for the Combo keys to be detected. Defaults to `TAPPING_TERM` if not defined.
+* `#define TAP_CODE_DELAY 100`
+  * Sets the delay between `register_code` and `unregister_code`, if you're having issues with it registering properly (common on VUSB boards). The value is in milliseconds.
+* `#define TAP_HOLD_CAPS_DELAY 80`
+  * Sets the delay for Tap Hold keys (`LT`, `MT`) when using `KC_CAPSLOCK` keycode, as this has some special handling on MacOS.  The value is in milliseconds, and defaults to 80 ms if not defined. For macOS, you may want to set this to 200 or higher.
+
+## RGB Light Configuration
+
+* `#define RGB_DI_PIN D7`
+  * pin the DI on the WS2812 is hooked-up to
+* `#define RGBLIGHT_ANIMATIONS`
+  * run RGB animations
+* `#define RGBLED_NUM 12`
+  * number of LEDs
+* `#define RGBLIGHT_SPLIT`
+  * Needed if both halves of the board have RGB LEDs wired directly to the RGB output pin on the controllers instead of passing the output of the left half to the input of the right half
+* `#define RGBLED_SPLIT { 6, 6 }`
+  * number of LEDs connected that are directly wired to `RGB_DI_PIN` on each half of a split keyboard
+  * First value indicates number of LEDs for left half, second value is for the right half
+  * When RGBLED_SPLIT is defined, RGBLIGHT_SPLIT is implicitly defined.
+* `#define RGBLIGHT_HUE_STEP 12`
+  * units to step when in/decreasing hue
+* `#define RGBLIGHT_SAT_STEP 25`
+  * units to step when in/decreasing saturation
+* `#define RGBLIGHT_VAL_STEP 12`
+  * units to step when in/decreasing value (brightness)
+* `#define RGBW_BB_TWI`
+  * bit-bangs TWI to EZ RGBW LEDs (only required for Ergodox EZ)
+
+## Mouse Key Options
+
+* `#define MOUSEKEY_INTERVAL 20`
+* `#define MOUSEKEY_DELAY 0`
+* `#define MOUSEKEY_TIME_TO_MAX 60`
+* `#define MOUSEKEY_MAX_SPEED 7`
+* `#define MOUSEKEY_WHEEL_DELAY 0`
+
+## Split Keyboard Options
+
+Split Keyboard specific options, make sure you have 'SPLIT_KEYBOARD = yes' in your rules.mk
+
+* `SPLIT_TRANSPORT = custom`
+  * Allows replacing the standard split communication routines with a custom one. ARM based split keyboards must use this at present.
+
+### Setting Handedness
+
+One thing to remember, the side that the USB port is plugged into is always the master half. The side not plugged into USB is the slave.
+
+There are a few different ways to set handedness for split keyboards (listed in order of precedence):
+
+1. Set `SPLIT_HAND_PIN`: Reads a pin to determine handedness. If pin is high, it's the left side, if low, the half is determined to be the right side
+2. Set `EE_HANDS` and flash `eeprom-lefthand.eep`/`eeprom-righthand.eep` to each half
+   * For boards with DFU bootloader you can use `:dfu-split-left`/`:dfu-split-right` to flash these EEPROM files
+   * For boards with Caterina bootloader (like stock Pro Micros), use `:avrdude-split-left`/`:avrdude-split-right`
+   * For boards with ARM DFU bootloader (like Proton C), use `:dfu-util-split-left`/`:dfu-util-split-right`
+3. Set `MASTER_RIGHT`: Half that is plugged into the USB port is determined to be the master and right half (inverse of the default)
+4. Default: The side that is plugged into the USB port is the master half and is assumed to be the left half. The slave side is the right half
+
+#### Defines for handedness
+
+* `#define SPLIT_HAND_PIN B7`
+  * For using high/low pin to determine handedness, low = right hand, high = left hand. Replace `B7` with the pin you are using. This is optional, and if you leave `SPLIT_HAND_PIN` undefined, then you can still use the EE_HANDS method or MASTER_LEFT / MASTER_RIGHT defines like the stock Let's Split uses.
+
+* `#define EE_HANDS` (only works if `SPLIT_HAND_PIN` is not defined)
+  * Reads the handedness value stored in the EEPROM after `eeprom-lefthand.eep`/`eeprom-righthand.eep` has been flashed to their respective halves.
+
+* `#define MASTER_RIGHT`
+  * Master half is defined to be the right half.
+
+### Other Options
+
+* `#define USE_I2C`
+  * For using I2C instead of Serial (defaults to serial)
+
+* `#define SOFT_SERIAL_PIN D0`
+  * When using serial, define this. `D0` or `D1`,`D2`,`D3`,`E6`.
+
+* `#define MATRIX_ROW_PINS_RIGHT { <row pins> }`
+* `#define MATRIX_COL_PINS_RIGHT { <col pins> }`
+  * If you want to specify a different pinout for the right half than the left half, you can define `MATRIX_ROW_PINS_RIGHT`/`MATRIX_COL_PINS_RIGHT`. Currently, the size of `MATRIX_ROW_PINS` must be the same as `MATRIX_ROW_PINS_RIGHT` and likewise for the definition of columns.
+
+* `#define DIRECT_PINS_RIGHT { { F1, F0, B0, C7 }, { F4, F5, F6, F7 } }`
+  * If you want to specify a different direct pinout for the right half than the left half, you can define `DIRECT_PINS_RIGHT`. Currently, the size of `DIRECT_PINS` must be the same as `DIRECT_PINS_RIGHT`.
+
+* `#define RGBLED_SPLIT { 6, 6 }`
+  * See [RGB Light Configuration](#rgb-light-configuration)
+
+* `#define SELECT_SOFT_SERIAL_SPEED <speed>` (default speed is 1)
+  * Sets the protocol speed when using serial communication
+  * Speeds:
+    * 0: about 189kbps (Experimental only)
+    * 1: about 137kbps (default)
+    * 2: about 75kbps
+    * 3: about 39kbps
+    * 4: about 26kbps
+    * 5: about 20kbps
+
+* `#define SPLIT_USB_DETECT`
+  * Detect (with timeout) USB connection when delegating master/slave
+  * Default behavior for ARM
+  * Required for AVR Teensy
+
+* `#define SPLIT_USB_TIMEOUT 2500`
+  * Maximum timeout when detecting master/slave when using `SPLIT_USB_DETECT`
+
+# The `rules.mk` File
+
+This is a [make](https://www.gnu.org/software/make/manual/make.html) file that is included by the top-level `Makefile`. It is used to set some information about the MCU that we will be compiling for as well as enabling and disabling certain features.
+
+## Build Options
+
+* `DEFAULT_FOLDER`
+  * Used to specify a default folder when a keyboard has more than one sub-folder.
+* `FIRMWARE_FORMAT`
+  * Defines which format (bin, hex) is copied to the root `qmk_firmware` folder after building.
+* `SRC`
+  * Used to add files to the compilation/linking list.
+* `LAYOUTS`
+  * A list of [layouts](feature_layouts.md) this keyboard supports.
+
+## AVR MCU Options
+* `MCU = atmega32u4`
+* `F_CPU = 16000000`
+* `ARCH = AVR8`
+* `F_USB = $(F_CPU)`
+* `OPT_DEFS += -DINTERRUPT_CONTROL_ENDPOINT`
+* `BOOTLOADER = atmel-dfu` with the following options:
+  * `atmel-dfu`
+  * `lufa-dfu`
+  * `qmk-dfu`
+  * `halfkay`
+  * `caterina`
+  * `bootloadHID`
+  * `USBasp`
+
+## Feature Options
+
+Use these to enable or disable building certain features. The more you have enabled the bigger your firmware will be, and you run the risk of building a firmware too large for your MCU.
+
+* `BOOTMAGIC_ENABLE`
+  * Virtual DIP switch configuration
+* `MOUSEKEY_ENABLE`
+  * Mouse keys
+* `EXTRAKEY_ENABLE`
+  * Audio control and System control
+* `CONSOLE_ENABLE`
+  * Console for debug
+* `COMMAND_ENABLE`
+  * Commands for debug and configuration
+* `COMBO_ENABLE`
+  * Key combo feature
+* `NKRO_ENABLE`
+  * USB N-Key Rollover - if this doesn't work, see here: https://github.com/tmk/tmk_keyboard/wiki/FAQ#nkro-doesnt-work
+* `AUDIO_ENABLE`
+  * Enable the audio subsystem.
+* `RGBLIGHT_ENABLE`
+  * Enable keyboard underlight functionality
+* `LEADER_ENABLE`
+  * Enable leader key chording
+* `MIDI_ENABLE`
+  * MIDI controls
+* `UNICODE_ENABLE`
+  * Unicode
+* `BLUETOOTH_ENABLE`
+  * Legacy option to Enable Bluetooth with the Adafruit EZ-Key HID. See BLUETOOTH
+* `BLUETOOTH`
+  * Current options are AdafruitEzKey, AdafruitBLE, RN42
+* `SPLIT_KEYBOARD`
+  * Enables split keyboard support (dual MCU like the let's split and bakingpy's boards) and includes all necessary files located at quantum/split_common
+* `CUSTOM_MATRIX`
+  * Allows replacing the standard matrix scanning routine with a custom one.
+* `DEBOUNCE_TYPE`
+  * Allows replacing the standard key debouncing routine with an alternative or custom one.
+* `WAIT_FOR_USB`
+  * Forces the keyboard to wait for a USB connection to be established before it starts up
+* `NO_USB_STARTUP_CHECK`
+  * Disables usb suspend check after keyboard startup. Usually the keyboard waits for the host to wake it up before any tasks are performed. This is useful for split keyboards as one half will not get a wakeup call but must send commands to the master.
+* `LINK_TIME_OPTIMIZATION_ENABLE`
+  = Enables Link Time Optimization (`LTO`) when compiling the keyboard.  This makes the process take longer, but can significantly reduce the compiled size (and since the firmware is small, the added time is not noticable).  However, this will automatically disable the old Macros and Functions features automatically, as these break when `LTO` is enabled.  It does this by automatically defining `NO_ACTION_MACRO` and `NO_ACTION_FUNCTION`
+
+## USB Endpoint Limitations
+
+In order to provide services over USB, QMK has to use USB endpoints.
+These are a finite resource: each microcontroller has only a certain number.
+This limits what features can be enabled together.
+If the available endpoints are exceeded, a build error is thrown.
+
+The following features can require separate endpoints:
+
+* `MOUSEKEY_ENABLE`
+* `EXTRAKEY_ENABLE`
+* `CONSOLE_ENABLE`
+* `NKRO_ENABLE`
+* `MIDI_ENABLE`
+* `RAW_ENABLE`
+* `VIRTSER_ENABLE`
+
+In order to improve utilisation of the endpoints, the HID features can be combined to use a single endpoint.
+By default, `MOUSEKEY`, `EXTRAKEY`, and `NKRO` are combined into a single endpoint.
+
+The base keyboard functionality can also be combined into the endpoint,
+by setting `KEYBOARD_SHARED_EP = yes`.
+This frees up one more endpoint,
+but it can prevent the keyboard working in some BIOSes,
+as they do not implement Boot Keyboard protocol switching.
+
+Combining the mouse also breaks Boot Mouse compatibility.
+The mouse can be uncombined by setting `MOUSE_SHARED_EP = no` if this functionality is required.

docs/contributing.md

@@ -0,0 +1,156 @@
+# How to Contribute
+
+👍🎉 First off, thanks for taking the time to read this and contribute! 🎉👍
+
+Third-party contributions help us grow and improve QMK. We want to make the pull request and contribution process useful and easy for both contributors and maintainers. To this end we've put together some guidelines for contributors to help your pull request be accepted without major changes.
+
+* [Project Overview](#project-overview)
+* [Coding Conventions](#coding-conventions)
+* [General Guidelines](#general-guidelines)
+* [What does the Code of Conduct mean for me?](#what-does-the-code-of-conduct-mean-for-me)
+
+## I Don't Want to Read This Whole Thing! I Just Have a Question!
+
+If you'd like to ask questions about QMK you can do so on the [OLKB Subreddit](https://reddit.com/r/olkb) or on [Discord](https://discord.gg/Uq7gcHh).
+
+Please keep these things in mind:
+
+* It may take several hours for someone to respond to your question. Please be patient!
+* Everyone involved with QMK is donating their time and energy. We don't get paid to work on or answer questions about QMK.
+* Try to ask your question so it's as easy to answer as possible. If you're not sure how to do that these are some good guides:
+  * https://opensource.com/life/16/10/how-ask-technical-questions
+  * http://www.catb.org/esr/faqs/smart-questions.html
+
+# Project Overview
+
+QMK is largely written in C, with specific features and parts written in C++. It targets embedded processors found in keyboards, particularly AVR ([LUFA](http://www.fourwalledcubicle.com/LUFA.php)) and ARM ([ChibiOS](http://www.chibios.com)). If you are already well versed in Arduino programming you'll find a lot of the concepts and limitations familiar. Prior experience with Arduino is not required to successfully contribute to QMK.
+
+<!-- FIXME: We should include a list of resources for learning C here. -->
+
+# Where Can I Go for Help?
+
+If you need help you can [open an issue](https://github.com/qmk/qmk_firmware/issues) or [chat on Discord](https://discord.gg/Uq7gcHh).
+
+# How Do I Make a Contribution?
+
+Never made an open source contribution before? Wondering how contributions work in QMK? Here's a quick rundown!
+
+0. Sign up for a [GitHub](https://github.com) account.
+1. Put together a keymap to contribute, [find an issue](https://github.com/qmk/qmk_firmware/issues) you are interested in addressing, or [a feature](https://github.com/qmk/qmk_firmware/issues?q=is%3Aopen+is%3Aissue+label%3Afeature) you would like to add.
+2. Fork the repository associated with the issue to your GitHub account. This means that you will have a copy of the repository under `your-GitHub-username/qmk_firmware`.
+3. Clone the repository to your local machine using `git clone https://github.com/github-username/repository-name.git`.
+4. If you're working on a new feature consider opening an issue to talk with us about the work you're about to undertake.
+5. Create a new branch for your fix using `git checkout -b branch-name-here`.
+6. Make the appropriate changes for the issue you are trying to address or the feature that you want to add.
+7. Use `git add insert-paths-of-changed-files-here` to add the file contents of the changed files to the "snapshot" git uses to manage the state of the project, also known as the index.
+8. Use `git commit -m "Insert a short message of the changes made here"` to store the contents of the index with a descriptive message.
+9. Push the changes to your repository on GitHub using `git push origin branch-name-here`.
+10. Submit a pull request to [QMK Firmware](https://github.com/qmk/qmk_firmware/pull/new/master).
+11. Title the pull request with a short description of the changes made and the issue or bug number associated with your change. For example, you can title an issue like so "Added more log outputting to resolve #4352".
+12. In the description of the pull request explain the changes that you made, any issues you think exist with the pull request you made, and any questions you have for the maintainer. It's OK if your pull request is not perfect (no pull request is), the reviewer will be able to help you fix any problems and improve it!
+13. Wait for the pull request to be reviewed by a maintainer.
+14. Make changes to the pull request if the reviewing maintainer recommends them.
+15. Celebrate your success after your pull request is merged!
+
+# Coding Conventions
+
+Most of our style is pretty easy to pick up on. If you are familiar with either C or Python you should not have too much trouble with our local styles.
+
+* [Coding Conventions - C](coding_conventions_c.md)
+* [Coding Conventions - Python](coding_conventions_python.md)
+
+# General Guidelines
+
+We have a few different types of changes in QMK, each requiring a different level of rigor. We'd like you to keep the following guidelines in mind no matter what type of change you're making.
+
+* Separate PRs into logical units. For example, do not submit one PR covering two separate features, instead submit a separate PR for each feature.
+* Check for unnecessary whitespace with `git diff --check` before committing.
+* Make sure your code change actually compiles.
+  * Keymaps: Make sure that `make keyboard:your_new_keymap` does not return any errors.
+  * Keyboards: Make sure that `make keyboard:all` does not return any errors.
+  * Core: Make sure that `make all` does not return any errors.
+* Make sure commit messages are understandable on their own. You should put a short description (no more than 70 characters) on the first line, the second line should be empty, and on the 3rd and later lines you should describe your commit in detail, if required. Example:
+
+```
+Adjust the fronzlebop for the kerpleplork
+
+The kerpleplork was intermittently failing with error code 23. The root cause was the fronzlebop setting, which causes the kerpleplork to activate every N iterations.
+
+Limited experimentation on the devices I have available shows that 7 is high enough to avoid confusing the kerpleplork, but I'd like to get some feedback from people with ARM devices to be sure.
+```
+
+!> **IMPORTANT:** If you would like to contribute a bugfix or improvement to user code, such as non-default keymaps, userspace and layouts, be sure to tag the original submitter of the code in your PR. Many users, regardless of skill level with Git and GitHub, may be confused or frustrated at their code being modified without their knowledge.
+
+## Documentation
+
+Documentation is one of the easiest ways to get started contributing to QMK. Finding places where the documentation is wrong or incomplete and fixing those is easy! We also very badly need someone to edit our documentation, so if you have editing skills but aren't sure where or how to jump in please [reach out for help](#where-can-i-go-for-help)!
+
+You'll find all our documentation in the `qmk_firmware/docs` directory, or if you'd rather use a web based workflow you can click "Suggest An Edit" at the top of each page on http://docs.qmk.fm/.
+
+When providing code examples in your documentation, try to observe naming conventions used elsewhere in the docs. For example, standardizing enums as `my_layers` or `my_keycodes` for consistency:
+
+```c
+enum my_layers {
+  _FIRST_LAYER,
+  _SECOND_LAYER
+};
+
+enum my_keycodes {
+  FIRST_LAYER = SAFE_RANGE,
+  SECOND_LAYER
+};
+```
+
+## Keymaps
+
+Most first-time QMK contributors start with their personal keymaps. We try to keep keymap standards pretty casual (keymaps, after all, reflect the personality of their creators) but we do ask that you follow these guidelines to make it easier for others to discover and learn from your keymap.
+
+* Write a `readme.md` using [the template](documentation_templates.md).
+* All Keymap PR's are squashed, so if you care about how your commits are squashed you should do it yourself
+* Do not lump features in with keymap PR's. Submit the feature first and then a second PR for the keymap.
+* Do not include `Makefile`s in your keymap folder (they're no longer used)
+* Update copyrights in file headers (look for `%YOUR_NAME%`)
+
+## Keyboards
+
+Keyboards are the raison d'être for QMK. Some keyboards are community maintained, while others are maintained by the people responsible for making a particular keyboard. The `readme.md` should tell you who maintains a particular keyboard. If you have questions relating to a particular keyboard you can [Open An Issue](https://github.com/qmk/qmk_firmware/issues) and tag the maintainer in your question.
+
+We also ask that you follow these guidelines:
+
+* Write a `readme.md` using [the template](documentation_templates.md).
+* Keep the number of commits reasonable or we will squash your PR
+* Do not lump core features in with new keyboards. Submit the feature first and then submit a separate PR for the keyboard.
+* Name `.c`/`.h` file after the immediate parent folder, eg `/keyboards/<kb1>/<kb2>/<kb2>.[ch]`
+* Do not include `Makefile`s in your keyboard folder (they're no longer used)
+* Update copyrights in file headers (look for `%YOUR_NAME%`)
+
+## Quantum/TMK Core
+
+Before you put a lot of work into building your new feature you should make sure you are implementing it in the best way. You can get a basic understanding of QMK by reading [Understanding QMK](understanding_qmk.md), which will take you on a tour of the QMK program flow. From here you should talk to us to get a sense of the best way to implement your idea. There are two main ways to do this:
+
+* [Chat on Discord](https://discord.gg/Uq7gcHh)
+* [Open an Issue](https://github.com/qmk/qmk_firmware/issues/new)
+
+Feature and Bug Fix PR's affect all keyboards. We are also in the process of restructuring QMK. For this reason it is especially important for significant changes to be discussed before implementation has happened. If you open a PR without talking to us first please be prepared to do some significant rework if your choices do not mesh well with our planned direction.
+
+Here are some things to keep in mind when working on your feature or bug fix.
+
+* **Disabled by default** - memory is a pretty limited on most chips QMK supports, and it's important that current keymaps aren't broken, so please allow your feature to be turned **on**, rather than being turned off. If you think it should be on by default, or reduces the size of the code, please talk with us about it.
+* **Compile locally before submitting** - hopefully this one is obvious, but things need to compile! Our Travis system will catch any issues, but it's generally faster for you to compile a few keyboards locally instead of waiting for the results to come back.
+* **Consider revisions and different chip-bases** - there are several keyboards that have revisions that allow for slightly different configurations, and even different chip-bases. Try to make a feature supported in ARM and AVR, or automatically disabled on platforms it doesn't work on.
+* **Explain your feature** - Document it in `docs/`, either as a new file or as part of an existing file. If you don't document it other people won't be able to benefit from your hard work.
+
+We also ask that you follow these guidelines:
+
+* Keep the number of commits reasonable or we will squash your PR
+* Do not lump keyboards or keymaps in with core changes. Submit your core changes first.
+* Write [Unit Tests](unit_testing.md) for your feature
+* Follow the style of the file you are editing. If the style is unclear or there are mixed styles you should conform to the [coding conventions](#coding-conventions) above.
+
+## Refactoring
+
+To maintain a clear vision of how things are laid out in QMK we try to plan out refactors in-depth and have a collaborator make the changes. If you have an idea for refactoring, or suggestions, [open an issue](https://github.com/qmk/qmk_firmware/issues), we'd love to talk about how QMK can be improved.
+
+# What Does the Code of Conduct Mean for Me?
+
+Our [Code of Conduct](https://github.com/qmk/qmk_firmware/blob/master/CODE_OF_CONDUCT.md) means that you are responsible for treating everyone on the project with respect and courtesy regardless of their identity. If you are the victim of any inappropriate behavior or comments as described in our Code of Conduct, we are here for you and will do the best to ensure that the abuser is reprimanded appropriately, per our code.

docs/custom_quantum_functions.md

@@ -0,0 +1,491 @@
+# How to Customize Your Keyboard's Behavior
+
+For a lot of people a custom keyboard is about more than sending button presses to your computer. You want to be able to do things that are more complex than simple button presses and macros. QMK has hooks that allow you to inject code, override functionality, and otherwise customize how your keyboard behaves in different situations.
+
+This page does not assume any special knowledge about QMK, but reading [Understanding QMK](understanding_qmk.md) will help you understand what is going on at a more fundamental level.
+
+## A Word on Core vs Keyboards vs Keymap
+
+We have structured QMK as a hierarchy:
+
+* Core (`_quantum`)
+  * Keyboard/Revision (`_kb`)
+    * Keymap (`_user`)
+
+Each of the functions described below can be defined with a `_kb()` suffix or a `_user()` suffix. We intend for you to use the `_kb()` suffix at the Keyboard/Revision level, while the `_user()` suffix should be used at the Keymap level.
+
+When defining functions at the Keyboard/Revision level it is important that your `_kb()` implementation call `_user()` before executing anything else- otherwise the keymap level function will never be called.
+
+# Custom Keycodes
+
+By far the most common task is to change the behavior of an existing keycode or to create a new keycode. From a code standpoint the mechanism for each is very similar.
+
+## Defining a New Keycode
+
+The first step to creating your own custom keycode(s) is to enumerate them. This means both naming them and assigning a unique number to that keycode. Rather than limit custom keycodes to a fixed range of numbers QMK provides the `SAFE_RANGE` macro. You can use `SAFE_RANGE` when enumerating your custom keycodes to guarantee that you get a unique number.
+
+
+Here is an example of enumerating 2 keycodes. After adding this block to your `keymap.c` you will be able to use `FOO` and `BAR` inside your keymap.
+
+```c
+enum my_keycodes {
+  FOO = SAFE_RANGE,
+  BAR
+};
+```
+
+## Programming the Behavior of Any Keycode
+
+When you want to override the behavior of an existing key, or define the behavior for a new key, you should use the `process_record_kb()` and `process_record_user()` functions. These are called by QMK during key processing before the actual key event is handled. If these functions return `true` QMK will process the keycodes as usual. That can be handy for extending the functionality of a key rather than replacing it. If these functions return `false` QMK will skip the normal key handling, and it will be up to you to send any key up or down events that are required.
+
+These function are called every time a key is pressed or released.
+
+### Example `process_record_user()` Implementation
+
+This example does two things. It defines the behavior for a custom keycode called `FOO`, and it supplements our Enter key by playing a tone whenever it is pressed.
+
+```c
+bool process_record_user(uint16_t keycode, keyrecord_t *record) {
+  switch (keycode) {
+    case FOO:
+      if (record->event.pressed) {
+        // Do something when pressed
+      } else {
+        // Do something else when release
+      }
+      return false; // Skip all further processing of this key
+    case KC_ENTER:
+      // Play a tone when enter is pressed
+      if (record->event.pressed) {
+        PLAY_NOTE_ARRAY(tone_qwerty);
+      }
+      return true; // Let QMK send the enter press/release events
+    default:
+      return true; // Process all other keycodes normally
+  }
+}
+```
+
+### `process_record_*` Function Documentation
+
+* Keyboard/Revision: `bool process_record_kb(uint16_t keycode, keyrecord_t *record)`
+* Keymap: `bool process_record_user(uint16_t keycode, keyrecord_t *record)`
+
+The `keycode` argument is whatever is defined in your keymap, eg `MO(1)`, `KC_L`, etc. You should use a `switch...case` block to handle these events.
+
+The `record` argument contains information about the actual press:
+
+```c
+keyrecord_t record {
+  keyevent_t event {
+    keypos_t key {
+      uint8_t col
+      uint8_t row
+    }
+    bool     pressed
+    uint16_t time
+  }
+}
+```
+
+# LED Control
+
+QMK provides methods to read the 5 LEDs defined as part of the HID spec:
+
+* `USB_LED_NUM_LOCK`
+* `USB_LED_CAPS_LOCK`
+* `USB_LED_SCROLL_LOCK`
+* `USB_LED_COMPOSE`
+* `USB_LED_KANA`
+
+These five constants correspond to the positional bits of the host LED state.
+There are two ways to get the host LED state:
+
+* by implementing `led_set_user()`
+* by calling `host_keyboard_leds()`
+
+## `led_set_user()`
+
+This function will be called when the state of one of those 5 LEDs changes. It receives the LED state as a parameter.
+Use the `IS_LED_ON(usb_led, led_name)` and `IS_LED_OFF(usb_led, led_name)` macros to check the LED status.
+
+!> `host_keyboard_leds()` may already reflect a new value before `led_set_user()` is called.
+
+### Example `led_set_user()` Implementation
+
+```c
+void led_set_user(uint8_t usb_led) {
+    if (IS_LED_ON(usb_led, USB_LED_NUM_LOCK)) {
+        writePinLow(B0);
+    } else {
+        writePinHigh(B0);
+    }
+    if (IS_LED_ON(usb_led, USB_LED_CAPS_LOCK)) {
+        writePinLow(B1);
+    } else {
+        writePinHigh(B1);
+    }
+    if (IS_LED_ON(usb_led, USB_LED_SCROLL_LOCK)) {
+        writePinLow(B2);
+    } else {
+        writePinHigh(B2);
+    }
+    if (IS_LED_ON(usb_led, USB_LED_COMPOSE)) {
+        writePinLow(B3);
+    } else {
+        writePinHigh(B3);
+    }
+    if (IS_LED_ON(usb_led, USB_LED_KANA)) {
+        writePinLow(B4);
+    } else {
+        writePinHigh(B4);
+    }
+}
+```
+
+### `led_set_*` Function Documentation
+
+* Keyboard/Revision: `void led_set_kb(uint8_t usb_led)`
+* Keymap: `void led_set_user(uint8_t usb_led)`
+
+## `host_keyboard_leds()`
+
+Call this function to get the last received LED state. This is useful for reading the LED state outside `led_set_*`, e.g. in [`matrix_scan_user()`](#matrix-scanning-code).
+For convenience, you can use the `IS_HOST_LED_ON(led_name)` and `IS_HOST_LED_OFF(led_name)` macros instead of calling and checking `host_keyboard_leds()` directly.
+
+## Setting Physical LED State
+
+Some keyboard implementations provide convenience methods for setting the state of the physical LEDs.
+
+### Ergodox Boards
+
+The Ergodox implementations provide `ergodox_right_led_1`/`2`/`3_on`/`off()` to turn individual LEDs on or off, as well as `ergodox_right_led_on`/`off(uint8_t led)` to turn them on or off by their index.
+
+In addition, it is possible to specify the brightness level of all LEDs with `ergodox_led_all_set(uint8_t n)`; of individual LEDs with `ergodox_right_led_1`/`2`/`3_set(uint8_t n)`; or by index with `ergodox_right_led_set(uint8_t led, uint8_t n)`.
+
+Ergodox boards also define `LED_BRIGHTNESS_LO` for the lowest brightness and `LED_BRIGHTNESS_HI` for the highest brightness (which is the default).
+
+# Keyboard Initialization Code
+
+There are several steps in the keyboard initialization process.  Depending on what you want to do, it will influence which function you should use.
+
+These are the three main initialization functions, listed in the order that they're called.
+
+* `keyboard_pre_init_*` - Happens before most anything is started. Good for hardware setup that you want running very early.
+* `matrix_init_*` - Happens midway through the firmware's startup process. Hardware is initialized, but features may not be yet.
+* `keyboard_post_init_*` - Happens at the end of the firmware's startup process. This is where you'd want to put "customization" code, for the most part.
+
+!> For most people, the `keyboard_post_init_user` function is what you want to call.  For instance, this is where you want to set up things for RGB Underglow.
+
+## Keyboard Pre Initialization code
+
+This runs very early during startup, even before the USB has been started. 
+
+Shortly after this, the matrix is initialized.
+
+For most users, this shouldn't be used, as it's primarily for hardware oriented initialization. 
+
+However, if you have hardware stuff that you need initialized, this is the best place for it (such as initializing LED pins).
+
+### Example `keyboard_pre_init_user()` Implementation
+
+This example, at the keyboard level, sets up B0, B1, B2, B3, and B4 as LED pins.
+
+```c
+void keyboard_pre_init_user(void) {
+  // Call the keyboard pre init code.
+
+  // Set our LED pins as output
+  setPinOutput(B0);
+  setPinOutput(B1);
+  setPinOutput(B2);
+  setPinOutput(B3);
+  setPinOutput(B4);
+}
+```
+
+### `keyboard_pre_init_*` Function Documentation
+
+* Keyboard/Revision: `void keyboard_pre_init_kb(void)`
+* Keymap: `void keyboard_pre_init_user(void)`
+
+## Matrix Initialization Code
+
+This is called when the matrix is initialized, and after some of the hardware has been set up, but before many of the features have been initialized. 
+
+This is useful for setting up stuff that you may need elsewhere, but isn't hardware related nor is dependant on where it's started. 
+
+
+### `matrix_init_*` Function Documentation
+
+* Keyboard/Revision: `void matrix_init_kb(void)`
+* Keymap: `void matrix_init_user(void)`
+
+
+## Keyboard Post Initialization code
+
+This is ran as the very last task in the keyboard initialization process. This is useful if you want to make changes to certain features, as they should be initialized by this point.
+
+
+### Example `keyboard_post_init_user()` Implementation
+
+This example, running after everything else has initialized, sets up the rgb underglow configuration.
+
+```c
+void keyboard_post_init_user(void) {
+  // Call the post init code.
+  rgblight_enable_noeeprom(); // enables Rgb, without saving settings
+  rgblight_sethsv_noeeprom(180, 255, 255); // sets the color to teal/cyan without saving
+  rgblight_mode_noeeprom(RGBLIGHT_MODE_BREATHING + 3); // sets mode to Fast breathing without saving
+}
+```
+
+### `keyboard_post_init_*` Function Documentation
+
+* Keyboard/Revision: `void keyboard_post_init_kb(void)`
+* Keymap: `void keyboard_post_init_user(void)`
+
+# Matrix Scanning Code
+
+Whenever possible you should customize your keyboard by using `process_record_*()` and hooking into events that way, to ensure that your code does not have a negative performance impact on your keyboard. However, in rare cases it is necessary to hook into the matrix scanning. Be extremely careful with the performance of code in these functions, as it will be called at least 10 times per second.
+
+### Example `matrix_scan_*` Implementation
+
+This example has been deliberately omitted. You should understand enough about QMK internals to write this without an example before hooking into such a performance sensitive area. If you need help please [open an issue](https://github.com/qmk/qmk_firmware/issues/new) or [chat with us on Discord](https://discord.gg/Uq7gcHh).
+
+### `matrix_scan_*` Function Documentation
+
+* Keyboard/Revision: `void matrix_scan_kb(void)`
+* Keymap: `void matrix_scan_user(void)`
+
+This function gets called at every matrix scan, which is basically as often as the MCU can handle. Be careful what you put here, as it will get run a lot.
+
+You should use this function if you need custom matrix scanning code. It can also be used for custom status output (such as LEDs or a display) or other functionality that you want to trigger regularly even when the user isn't typing.
+
+
+# Keyboard Idling/Wake Code
+
+If the board supports it, it can be "idled", by stopping a number of functions.  A good example of this is RGB lights or backlights.   This can save on power consumption, or may be better behavior for your keyboard.
+
+This is controlled by two functions: `suspend_power_down_*` and `suspend_wakeup_init_*`, which are called when the system board is idled and when it wakes up, respectively.
+
+
+### Example suspend_power_down_user() and suspend_wakeup_init_user() Implementation
+
+
+```c
+void suspend_power_down_user(void) {
+    rgb_matrix_set_suspend_state(true);
+}
+
+void suspend_wakeup_init_user(void) {
+    rgb_matrix_set_suspend_state(false);
+}
+```
+
+### Keyboard suspend/wake  Function Documentation
+
+* Keyboard/Revision: `void suspend_power_down_kb(void)` and `void suspend_wakeup_init_user(void)`
+* Keymap: `void suspend_power_down_kb(void)` and `void suspend_wakeup_init_user(void)`
+
+# Layer Change Code
+
+This runs code every time that the layers get changed.  This can be useful for layer indication, or custom layer handling.
+
+### Example `layer_state_set_*` Implementation
+
+This example shows how to set the [RGB Underglow](feature_rgblight.md) lights based on the layer, using the Planck as an example
+
+```c
+layer_state_t layer_state_set_user(layer_state_t state) {
+    switch (get_highest_layer(state)) {
+    case _RAISE:
+        rgblight_setrgb (0x00,  0x00, 0xFF);
+        break;
+    case _LOWER:
+        rgblight_setrgb (0xFF,  0x00, 0x00);
+        break;
+    case _PLOVER:
+        rgblight_setrgb (0x00,  0xFF, 0x00);
+        break;
+    case _ADJUST:
+        rgblight_setrgb (0x7A,  0x00, 0xFF);
+        break;
+    default: //  for any other layers, or the default layer
+        rgblight_setrgb (0x00,  0xFF, 0xFF);
+        break;
+    }
+  return state;
+}
+```
+### `layer_state_set_*` Function Documentation
+
+* Keyboard/Revision: `layer_state_t layer_state_set_kb(layer_state_t state)`
+* Keymap: `layer_state_t layer_state_set_user(layer_state_t state)`
+
+
+The `state` is the bitmask of the active layers, as explained in the [Keymap Overview](keymap.md#keymap-layer-status)
+
+
+# Persistent Configuration (EEPROM)
+
+This allows you to configure persistent settings for your keyboard.  These settings are stored in the EEPROM of your controller, and are retained even after power loss. The settings can be read with `eeconfig_read_kb` and `eeconfig_read_user`, and can be written to using `eeconfig_update_kb` and `eeconfig_update_user`. This is useful for features that you want to be able to toggle (like toggling rgb layer indication).  Additionally, you can use `eeconfig_init_kb` and `eeconfig_init_user` to set the default values for the EEPROM. 
+
+The complicated part here, is that there are a bunch of ways that you can store and access data via EEPROM, and there is no "correct" way to do this.  However, you only have a DWORD (4 bytes) for each function.
+
+Keep in mind that EEPROM has a limited number of writes. While this is very high, it's not the only thing writing to the EEPROM, and if you write too often, you can potentially drastically shorten the life of your MCU.
+
+* If you don't understand the example, then you may want to avoid using this feature, as it is rather complicated. 
+
+### Example Implementation
+
+This is an example of how to add settings, and read and write it. We're using the user keymap for the example here.  This is a complex function, and has a lot going on.  In fact, it uses a lot of the above functions to work! 
+
+
+In your keymap.c file, add this to the top:
+```c
+typedef union {
+  uint32_t raw;
+  struct {
+    bool     rgb_layer_change :1;
+  };
+} user_config_t;
+
+user_config_t user_config;
+```
+
+This sets up a 32 bit structure that we can store settings with in memory, and write to the EEPROM. Using this removes the need to define variables, since they're defined in this structure. Remember that `bool` (boolean) values use 1 bit, `uint8_t` uses 8 bits, `uint16_t` uses up 16 bits.  You can mix and match, but changing the order can cause issues, as it will change the values that are read and written. 
+
+We're using `rgb_layer_change`, for the `layer_state_set_*` function, and use `keyboard_post_init_user` and `process_record_user` to configure everything. 
+
+Now, using the `keyboard_post_init_user` code above, you want to add `eeconfig_read_user()` to it, to populate the structure you've just created. And you can then immediately use this structure to control functionality in your keymap.  And It should look like: 
+```c
+void keyboard_post_init_user(void) {
+  // Call the keymap level matrix init.
+
+  // Read the user config from EEPROM
+  user_config.raw = eeconfig_read_user();
+
+  // Set default layer, if enabled
+  if (user_config.rgb_layer_change) {
+    rgblight_enable_noeeprom();
+    rgblight_sethsv_noeeprom_cyan(); 
+    rgblight_mode_noeeprom(1);
+  }
+}
+```
+The above function will use the EEPROM config immediately after reading it, to set the default layer's RGB color. The "raw" value of it is converted in a usable structure based on the "union" that you created above. 
+
+```c
+layer_state_t layer_state_set_user(layer_state_t state) {
+    switch (get_highest_layer(state)) {
+    case _RAISE:
+        if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_magenta(); rgblight_mode_noeeprom(1); }
+        break;
+    case _LOWER:
+        if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_red(); rgblight_mode_noeeprom(1); }
+        break;
+    case _PLOVER:
+        if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_green(); rgblight_mode_noeeprom(1); }
+        break;
+    case _ADJUST:
+        if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_white(); rgblight_mode_noeeprom(1); }
+        break;
+    default: //  for any other layers, or the default layer
+        if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_cyan(); rgblight_mode_noeeprom(1); }
+        break;
+    }
+  return state;
+}
+```
+This will cause the RGB underglow to be changed ONLY if the value was enabled.  Now to configure this value, create a new keycode for `process_record_user` called `RGB_LYR`. Additionally, we want to make sure that if you use the normal RGB codes, that it turns off  Using the example above, make it look this:
+```c
+
+bool process_record_user(uint16_t keycode, keyrecord_t *record) {
+  switch (keycode) {
+    case FOO:
+      if (record->event.pressed) {
+        // Do something when pressed
+      } else {
+        // Do something else when release
+      }
+      return false; // Skip all further processing of this key
+    case KC_ENTER:
+        // Play a tone when enter is pressed
+        if (record->event.pressed) {
+            PLAY_NOTE_ARRAY(tone_qwerty);
+        }
+        return true; // Let QMK send the enter press/release events
+    case RGB_LYR:  // This allows me to use underglow as layer indication, or as normal
+        if (record->event.pressed) { 
+            user_config.rgb_layer_change ^= 1; // Toggles the status
+            eeconfig_update_user(user_config.raw); // Writes the new status to EEPROM
+            if (user_config.rgb_layer_change) { // if layer state indication is enabled, 
+                layer_state_set(layer_state);   // then immediately update the layer color
+            }
+        }
+        return false; break;
+    case RGB_MODE_FORWARD ... RGB_MODE_GRADIENT: // For any of the RGB codes (see quantum_keycodes.h, L400 for reference)
+        if (record->event.pressed) { //This disables layer indication, as it's assumed that if you're changing this ... you want that disabled
+            if (user_config.rgb_layer_change) {        // only if this is enabled 
+                user_config.rgb_layer_change = false;  // disable it, and 
+                eeconfig_update_user(user_config.raw); // write the setings to EEPROM
+            }
+        }
+        return true; break;
+    default:
+      return true; // Process all other keycodes normally
+  }
+}
+```
+And lastly, you want to add the `eeconfig_init_user` function, so that when the EEPROM is reset, you can specify default values, and even custom actions. To force an EEPROM reset, use the `EEP_RST` keycode or [Bootmagic](feature_bootmagic.md) functionallity. For example, if you want to set rgb layer indication by default, and save the default valued. 
+
+```c
+void eeconfig_init_user(void) {  // EEPROM is getting reset! 
+  user_config.raw = 0;
+  user_config.rgb_layer_change = true; // We want this enabled by default
+  eeconfig_update_user(user_config.raw); // Write default value to EEPROM now
+
+  // use the non noeeprom versions, to write these values to EEPROM too
+  rgblight_enable(); // Enable RGB by default
+  rgblight_sethsv_cyan();  // Set it to CYAN by default
+  rgblight_mode(1); // set to solid by default
+}
+```
+
+And you're done.  The RGB layer indication will only work if you want it to. And it will be saved, even after unplugging the board. And if you use any of the RGB codes, it will disable the layer indication, so that it stays on the mode and color that you set it to. 
+
+### 'EECONFIG' Function Documentation
+
+* Keyboard/Revision: `void eeconfig_init_kb(void)`, `uint32_t eeconfig_read_kb(void)` and `void eeconfig_update_kb(uint32_t val)`
+* Keymap: `void eeconfig_init_user(void)`, `uint32_t eeconfig_read_user(void)` and `void eeconfig_update_user(uint32_t val)`
+
+The `val` is the value of the data that you want to write to EEPROM.  And the `eeconfig_read_*` function return a 32 bit (DWORD) value from the EEPROM. 
+
+# Custom Tapping Term
+
+By default, the tapping term is defined globally, and is not configurable by key.  For most users, this is perfectly fine.  But in come cases, dual function keys would be greatly improved by different timeouts than `LT` keys, or because some keys may be easier to hold than others.  Instead of using custom key codes for each, this allows for per key configurable `TAPPING_TERM`.
+
+To enable this functionality, you need to add `#define TAPPING_TERM_PER_KEY` to your `config.h`, first.  
+
+
+## Example `get_tapping_term` Implementation
+
+To change the `TAPPING TERM` based on the keycode, you'd want to add something like the following to your `keymap.c` file: 
+
+```c
+uint16_t get_tapping_term(uint16_t keycode) {
+  switch (keycode) {
+    case SFT_T(KC_SPC):
+      return TAPPING_TERM + 1250;
+    case LT(1, KC_GRV):
+      return 130;
+    default:
+      return TAPPING_TERM;
+  }
+}
+```
+
+### `get_tapping_term` Function Documentation
+
+Unlike many of the other functions here, there isn't a need (or even reason) to have a quantum or keyboard level function. Only a user level function is useful here, so no need to mark it as such.

docs/documentation_best_practices.md

@@ -0,0 +1,64 @@
+# Documentation Best Practices
+
+This page exists to document best practices when writing documentation for QMK. Following these guidelines will help to keep a consistent tone and style, which will in turn help other people more easily understand QMK.
+
+# Page Opening
+
+Your documentation page should generally start with an H1 heading, followed by a 1 paragraph description of what the user will find on this page. Keep in mind that this heading and paragraph will sit next to the Table of Contents, so keep the heading short and avoid long strings with no whitespace.
+
+Example:
+
+```
+# My Page Title
+
+This page covers my super cool feature. You can use this feature to make coffee, squeeze fresh oj, and have an egg mcmuffin and hashbrowns delivered from your local macca's by drone.
+```
+
+# Headings
+
+Your page should generally have multiple "H1" headings. Only H1 and H2 headings will included in the Table of Contents, so plan them out appropriately. Excess width should be avoided in H1 and H2 headings to prevent the Table of Contents from getting too wide.
+
+# Styled Hint Blocks
+
+You can have styled hint blocks drawn around text to draw attention to it.
+
+### Important
+
+```
+!> This is important
+```
+
+Renders as:
+
+!> This is important
+
+### General Tips
+
+```
+?> This is a helpful tip.
+```
+
+Renders as:
+
+?> This is a helpful tip.
+
+
+# Documenting Features
+
+If you create a new feature for QMK, create a documentation page for it. It doesn't have to be very long, a few sentences describing your feature and a table listing any relevant keycodes is enough. Here is a basic template:
+
+```markdown
+# My Cool Feature
+
+This page describes my cool feature. You can use my cool feature to make coffee and order cream and sugar to be delivered via drone.
+
+## My Cool Feature Keycodes
+
+|Long Name|Short Name|Description|
+|---------|----------|-----------|
+|KC_COFFEE||Make Coffee|
+|KC_CREAM||Order Cream|
+|KC_SUGAR||Order Sugar|
+```
+
+Place your documentation into `docs/feature_<my_cool_feature>.md`, and add that file to the appropriate place in `docs/_sidebar.md`. If you have added any keycodes be sure to add them to `docs/keycodes.md` with a link back to your feature page.

docs/documentation_templates.md

@@ -0,0 +1,42 @@
+# Documentation Templates
+
+This page documents the templates you should use when submitting new Keymaps and Keyboards to QMK.
+
+## Keymap `readme.md` Template
+
+Most keymaps have an image depicting the layout. You can use [Keyboard Layout Editor](http://keyboard-layout-editor.com) to create an image. Upload it to [Imgur](http://imgur.com) or another hosting service, please do not include images in your Pull Request.
+
+Below the image you should write a short description to help people understand your keymap.
+
+```
+![Clueboard Layout Image](http://i.imgur.com/7Capi8W.png)
+
+# Default Clueboard Layout
+
+This is the default layout that comes flashed on every Clueboard. For the most
+part it's a straightforward and easy to follow layout. The only unusual key is
+the key in the upper left, which sends Escape normally, but Grave when any of
+the Ctrl, Alt, or GUI modifiers are held down.
+```
+
+## Keyboard `readme.md` Template
+
+```
+# Planck
+
+![Planck](http://i.imgur.com/q2M3uEU.jpg)
+
+A compact 40% (12x4) ortholinear keyboard kit made and sold by OLKB and Massdrop. [More info on qmk.fm](http://qmk.fm/planck/)
+
+Keyboard Maintainer: [Jack Humbert](https://github.com/jackhumbert)  
+Hardware Supported: Planck PCB rev1, rev2, rev3, rev4, Teensy 2.0  
+Hardware Availability: [OLKB.com](https://olkb.com), [Massdrop](https://www.massdrop.com/buy/planck-mechanical-keyboard?mode=guest_open)
+
+Make example for this keyboard (after setting up your build environment):
+
+    make planck/rev4:default
+
+See the [build environment setup](https://docs.qmk.fm/#/getting_started_build_tools) and the [make instructions](https://docs.qmk.fm/#/getting_started_make_guide) for more information. Brand new to QMK? Start with our [Complete Newbs Guide](https://docs.qmk.fm/#/newbs).
+```
+
+There needs to be two spaces at the end of the `Keyboard Maintainer` and `Hardware Supported` lines for it to render correctly with Markdown.

docs/driver_installation_zadig.md

@@ -0,0 +1,46 @@
+# Bootloader Driver Installation with Zadig
+
+QMK presents itself to the host as a regular HID keyboard device, and as such requires no special drivers. However, in order to flash your keyboard on Windows, the bootloader device that appears when you reset the board often *does*.
+
+There are two notable exceptions: the Caterina bootloader, usually seen on Pro Micros, and the Halfkay bootloader shipped with PJRC Teensys, appear as a serial port and a generic HID device respectively, and so do not require a driver.
+
+We recommend the use of the [Zadig](https://zadig.akeo.ie/) utility. If you have set up the development environment with Msys2 or WSL, the `qmk_install.sh` script will have asked if you want it to install the drivers for you.
+
+## Installation
+
+Put your keyboard into bootloader mode, either by hitting the `RESET` keycode (which may be on a different layer), or by pressing the reset switch that's usually located on the underside of the board. If your keyboard has neither, try holding Escape or Space+`B` as you plug it in (see the [Bootmagic](feature_bootmagic.md) docs for more details). Some boards use [Command](feature_command.md) instead of Bootmagic; in this case, you can enter bootloader mode by hitting Left Shift+Right Shift+`B` or Left Shift+Right Shift+Escape at any point while the keyboard is plugged in.
+Some keyboards may have specific instructions for entering the bootloader. For example, the [Bootmagic Lite](feature_bootmagic.md#bootmagic-lite) key (default: Escape) might be on a different key, e.g. Left Control; or the magic combination for Command (default: Left Shift+Right Shift) might require you to hold something else, e.g. Left Control+Right Control. Refer to the board's README file if you are unsure.
+
+To put a device in bootloader mode with USBaspLoader, tap the `RESET` button while holding down the `BOOT` button.
+Alternatively, hold `BOOT` while inserting the USB cable.
+
+Zadig will automatically detect the bootloader device. You may sometimes need to check **Options → List All Devices**.
+
+ - For keyboards with Atmel AVR MCUs, the bootloader will be named something similar to `ATm32U4DFU`, and have a Vendor ID of `03EB`.
+ - USBasp bootloaders will appear as `USBasp`, with a VID/PID of `16C0:05DC`.
+ - AVR keyboards flashed with the QMK-DFU bootloader will be named `<keyboard name> Bootloader` and will also have the VID `03EB`.
+ - For most ARM keyboards, it will be called `STM32 BOOTLOADER`, and have a VID/PID of `0483:DF11`.
+
+!> If Zadig lists one or more devices with the `HidUsb` driver, your keyboard is probably not in bootloader mode. The arrow will be colored orange and you will be asked to confirm modifying a system driver. **Do not** proceed if this is the case!
+
+If the arrow appears green, select the driver, and click **Install Driver**. The `libusb-win32` driver will usually work for AVR, and `WinUSB` for ARM, but if you still cannot flash the board, try installing a different driver from the list. For flashing a USBaspLoader device via command line with msys2, the `libusbk` driver is recommended, otherwise `libusb-win32` will work fine if you are using QMK Toolbox for flashing.
+
+![Zadig with a bootloader driver correctly installed](https://i.imgur.com/b8VgXzx.png)
+
+Finally, unplug and replug the keyboard to make sure the new driver has been loaded. If you are using the QMK Toolbox to flash, exit and restart it too, as it can sometimes fail to recognize the driver change.
+
+## Recovering from Installation to Wrong Device
+
+If you find that you can no longer type with the keyboard, you may have installed the driver onto the keyboard itself instead of the bootloader. You can easily confirm this in Zadig - a healthy keyboard has the `HidUsb` driver installed on all of its interfaces:
+
+![A healthy keyboard as seen by Zadig](https://i.imgur.com/Hx0E5kC.png)
+
+Open the Device Manager and look for a device that looks like your keyboard.
+
+![The board with the wrong driver installed, in Device Manager](https://i.imgur.com/L3wvX8f.png)
+
+Right-click it and hit **Uninstall device**. Make sure to tick **Delete the driver software for this device** first.
+
+![The Device Uninstall dialog, with the "delete driver" checkbox ticked](https://i.imgur.com/aEs2RuA.png)
+
+Click **Action → Scan for hardware changes**. At this point, you should be able to type again. Double check in Zadig that the keyboard device(s) are using the `HidUsb` driver. If so, you're all done, and your board should be functional again!

docs/faq.md

@@ -0,0 +1,6 @@
+# Frequently Asked Questions
+
+* [General](faq_general.md)
+* [Building or Compiling QMK](faq_build.md)
+* [Debugging and Troubleshooting QMK](faq_debug.md)
+* [Keymap](faq_keymap.md)

docs/faq_build.md

@@ -0,0 +1,174 @@
+# Frequently Asked Build Questions
+
+This page covers questions about building QMK. If you haven't yet done so, you should read the [Build Environment Setup](getting_started_build_tools.md) and [Make Instructions](getting_started_make_guide.md) guides.
+
+## Can't Program on Linux
+You will need proper permissions to operate a device. For Linux users, see the instructions regarding `udev` rules, below. If you have issues with `udev`, a work-around is to use the `sudo` command. If you are not familiar with this command, check its manual with `man sudo` or [see this webpage](https://linux.die.net/man/8/sudo).
+
+An example of using `sudo`, when your controller is ATMega32u4:
+
+    $ sudo dfu-programmer atmega32u4 erase --force
+    $ sudo dfu-programmer atmega32u4 flash your.hex
+    $ sudo dfu-programmer atmega32u4 reset
+
+or just:
+
+    $ sudo make <keyboard>:<keymap>:dfu
+
+Note that running `make` with `sudo` is generally ***not*** a good idea, and you should use one of the former methods, if possible.
+
+### Linux `udev` Rules
+On Linux, you'll need proper privileges to access the MCU. You can either use
+`sudo` when flashing firmware, or place these files in `/etc/udev/rules.d/`. Once added run the following:
+```console
+sudo udevadm control --reload-rules
+sudo udevadm trigger
+```
+
+**/etc/udev/rules.d/50-atmel-dfu.rules:**
+```
+# Atmel ATMega32U4
+SUBSYSTEMS=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2ff4", MODE:="0666"
+# Atmel USBKEY AT90USB1287
+SUBSYSTEMS=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2ffb", MODE:="0666"
+# Atmel ATMega32U2
+SUBSYSTEMS=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2ff0", MODE:="0666"
+```
+
+**/etc/udev/rules.d/52-tmk-keyboard.rules:**
+```
+# tmk keyboard products     https://github.com/tmk/tmk_keyboard
+SUBSYSTEMS=="usb", ATTRS{idVendor}=="feed", MODE:="0666"
+```
+**/etc/udev/rules.d/54-input-club-keyboard.rules:**
+
+```
+# Input Club keyboard bootloader
+SUBSYSTEMS=="usb", ATTRS{idVendor}=="1c11", MODE:="0666"
+```
+
+**/etc/udev/rules.d/55-catalina.rules:**
+```
+# ModemManager should ignore the following devices
+ATTRS{idVendor}=="2a03", ENV{ID_MM_DEVICE_IGNORE}="1"
+ATTRS{idVendor}=="2341", ENV{ID_MM_DEVICE_IGNORE}="1"
+```
+
+**Note:** ModemManager filtering only works when not in strict mode, the following commands can update that settings:
+```console
+sudo sed -i 's/--filter-policy=strict/--filter-policy=default/' /lib/systemd/system/ModemManager.service
+sudo systemctl daemon-reload
+sudo systemctl restart ModemManager
+```
+
+**/etc/udev/rules.d/56-dfu-util.rules:**
+```
+# stm32duino
+SUBSYSTEMS=="usb", ATTRS{idVendor}=="1eaf", ATTRS{idProduct}=="0003", MODE:="0666"
+# Generic stm32
+SUBSYSTEMS=="usb", ATTRS{idVendor}=="0483", ATTRS{idProduct}=="df11", MODE:="0666"
+```
+
+### Serial device is not detected in bootloader mode on Linux
+Make sure your kernel has appropriate support for your device. If your device uses USB ACM, such as
+Pro Micro (Atmega32u4), make sure to include `CONFIG_USB_ACM=y`. Other devices may require `USB_SERIAL` and any of its sub options.
+
+## Unknown Device for DFU Bootloader
+
+Issues encountered when flashing keyboards on Windows are most often due to having the wrong drivers installed for the bootloader, or none at all.
+
+Re-running the QMK installation script (`./util/qmk_install.sh` from the `qmk_firmware` directory in MSYS2 or WSL) or reinstalling the QMK Toolbox may fix the issue. Alternatively, you can download and run the [`qmk_driver_installer`](https://github.com/qmk/qmk_driver_installer) package manually.
+
+If that doesn't work, then you may need to download and run Zadig. See [Bootloader Driver Installation with Zadig](driver_installation_zadig.md) for more detailed information.
+
+## WINAVR is Obsolete
+It is no longer recommended and may cause some problem.
+See [TMK Issue #99](https://github.com/tmk/tmk_keyboard/issues/99).
+
+## USB VID and PID
+You can use any ID you want with editing `config.h`. Using any presumably unused ID will be no problem in fact except for very low chance of collision with other product.
+
+Most boards in QMK use `0xFEED` as the vendor ID. You should look through other keyboards to make sure you pick a unique Product ID.
+
+Also see this.
+https://github.com/tmk/tmk_keyboard/issues/150
+
+You can buy a really unique VID:PID here. I don't think you need this for personal use.
+- http://www.obdev.at/products/vusb/license.html
+- http://www.mcselec.com/index.php?page=shop.product_details&flypage=shop.flypage&product_id=92&option=com_phpshop&Itemid=1
+
+## Cortex: `cstddef: No such file or directory`
+GCC 4.8 of Ubuntu 14.04 had this problem and had to update to 4.9 with this PPA.
+https://launchpad.net/~terry.guo/+archive/ubuntu/gcc-arm-embedded
+
+https://github.com/tmk/tmk_keyboard/issues/212
+https://github.com/tmk/tmk_keyboard/wiki/mbed-cortex-porting#compile-error-cstddef
+https://developer.mbed.org/forum/mbed/topic/5205/
+
+## `clock_prescale_set` and `clock_div_1` Not Available
+Your toolchain is too old to support the MCU. For example WinAVR 20100110 doesn't support ATMega32u2.
+
+```
+Compiling C: ../../tmk_core/protocol/lufa/lufa.c
+avr-gcc -c -mmcu=atmega32u2 -gdwarf-2 -DF_CPU=16000000UL -DINTERRUPT_CONTROL_ENDPOINT -DBOOTLOADER_SIZE=4096 -DF_USB=16000000UL -DARCH=ARCH_AVR8 -DUSB_DEVICE_ONLY -DUSE_FLASH_DESCRIPTORS -DUSE_STATIC_OPTIONS="(USB_DEVICE_OPT_FULLSPEED | USB_OPT_REG_ENABLED | USB_OPT_AUTO_PLL)" -DFIXED_CONTROL_ENDPOINT_SIZE=8  -DFIXED_NUM_CONFIGURATIONS=1 -DPROTOCOL_LUFA -DEXTRAKEY_ENABLE -DCONSOLE_ENABLE -DCOMMAND_ENABLE -DVERSION=unknown -Os -funsigned-char -funsigned-bitfields -ffunction-sections -fdata-sections -fno-inline-small-functions -fpack-struct -fshort-enums -fno-strict-aliasing -Wall -Wstrict-prototypes -Wa,-adhlns=obj_alps64/protocol/lufa/lufa.lst -I. -I../../tmk_core -I../../tmk_core/protocol/lufa -I../../tmk_core/protocol/lufa/LUFA-git -I../../tmk_core/common -std=gnu99 -include config.h -MMD -MP -MF .dep/obj_alps64_protocol_lufa_lufa.o.d  ../../tmk_core/protocol/lufa/lufa.c -o obj_alps64/protocol/lufa/lufa.o
+../../tmk_core/protocol/lufa/lufa.c: In function 'setup_mcu':
+../../tmk_core/protocol/lufa/lufa.c:575: warning: implicit declaration of function 'clock_prescale_set'
+../../tmk_core/protocol/lufa/lufa.c:575: error: 'clock_div_1' undeclared (first use in this function)
+../../tmk_core/protocol/lufa/lufa.c:575: error: (Each undeclared identifier is reported only once
+../../tmk_core/protocol/lufa/lufa.c:575: error: for each function it appears in.)
+make: *** [obj_alps64/protocol/lufa/lufa.o] Error 1
+```
+
+
+## BOOTLOADER_SIZE for AVR
+Note that Teensy2.0++ bootloader size is 2048byte. Some Makefiles may have wrong comment.
+
+```
+# Boot Section Size in *bytes*
+#   Teensy halfKay   512
+#   Teensy++ halfKay 2048
+#   Atmel DFU loader 4096       (TMK Alt Controller)
+#   LUFA bootloader  4096
+#   USBaspLoader     2048
+OPT_DEFS += -DBOOTLOADER_SIZE=2048
+```
+
+## `avr-gcc: internal compiler error: Abort trap: 6 (program cc1)` on MacOS
+This is an issue with updating on brew, causing symlinks that avr-gcc depend on getting mangled.
+
+The solution is to remove and reinstall all affected modules.
+
+```
+brew rm avr-gcc
+brew rm dfu-programmer
+brew rm dfu-util
+brew rm gcc-arm-none-eabi
+brew rm avrdude
+brew install avr-gcc
+brew install dfu-programmer
+brew install dfu-util
+brew install gcc-arm-none-eabi
+brew install avrdude
+```
+
+### avr-gcc 8.1 and LUFA
+
+If you updated your avr-gcc to above 7 you may see errors involving LUFA. For example:
+
+`lib/lufa/LUFA/Drivers/USB/Class/Device/AudioClassDevice.h:380:5: error: 'const' attribute on function returning 'void'`
+
+For now, you need to rollback avr-gcc to 7 in brew.
+
+```
+brew uninstall --force avr-gcc
+brew install avr-gcc@8
+brew link --force avr-gcc@8
+```
+
+### I just flashed my keyboard and it does nothing/keypresses don't register - it's also ARM (rev6 planck, clueboard 60, hs60v2, etc...) (Feb 2019)
+Due to how EEPROM works on ARM based chips, saved settings may no longer be valid.  This affects the default layers, and *may*, under certain circumstances we are still figuring out, make the keyboard unusable.  Resetting the EEPROM will correct this.
+
+[Planck rev6 reset EEPROM](https://cdn.discordapp.com/attachments/473506116718952450/539284620861243409/planck_rev6_default.bin) can be used to force an eeprom reset. After flashing this image, flash your normal firmware again which should restore your keyboard to _normal_ working order.
+[Preonic rev3 reset EEPROM](https://cdn.discordapp.com/attachments/473506116718952450/537849497313738762/preonic_rev3_default.bin)
+
+If bootmagic is enabled in any form, you should be able to do this too (see [Bootmagic docs](feature_bootmagic.md) and keyboard info for specifics on how to do this).

docs/faq_debug.md

@@ -0,0 +1,237 @@
+# Debugging FAQ
+
+This page details various common questions people have about troubleshooting their keyboards.
+
+# Debug Console
+
+## `hid_listen` Can't Recognize Device
+When debug console of your device is not ready you will see like this:
+
+```
+Waiting for device:.........
+```
+
+once the device is plugged in then *hid_listen* finds it you will get this message:
+
+```
+Waiting for new device:.........................
+Listening:
+```
+
+If you can't get this 'Listening:' message try building with `CONSOLE_ENABLE=yes` in [Makefile]
+
+You may need privilege to access the device on OS like Linux.
+- try `sudo hid_listen`
+
+## Can't Get Message on Console
+Check:
+- *hid_listen* finds your device. See above.
+- Enable debug with pressing **Magic**+d. See [Magic Commands](https://github.com/tmk/tmk_keyboard#magic-commands).
+- set `debug_enable=true` usually in `matrix_init()` in **matrix.c**.
+- try using 'print' function instead of debug print. See **common/print.h**.
+- disconnect other devices with console function. See [Issue #97](https://github.com/tmk/tmk_keyboard/issues/97).
+
+## Linux or UNIX Like System Requires Super User Privilege
+Just use 'sudo' to execute *hid_listen* with privilege.
+```
+$ sudo hid_listen
+```
+
+Or add an *udev rule* for TMK devices with placing a file in rules directory. The directory may vary on each system.
+
+File: /etc/udev/rules.d/52-tmk-keyboard.rules(in case of Ubuntu)
+```
+# tmk keyboard products     https://github.com/tmk/tmk_keyboard
+SUBSYSTEMS=="usb", ATTRS{idVendor}=="feed", MODE:="0666"
+```
+
+***
+
+# Miscellaneous
+## Safety Considerations
+
+You probably don't want to "brick" your keyboard, making it impossible
+to rewrite firmware onto it.  Here are some of the parameters to show
+what things are (and likely aren't) too risky.
+
+- If your keyboard map does not include RESET, then, to get into DFU
+  mode, you will need to press the reset button on the PCB, which
+  requires unscrewing the bottom.
+- Messing with tmk_core / common files might make the keyboard
+  inoperable
+- Too large a .hex file is trouble; `make dfu` will erase the block,
+  test the size (oops, wrong order!), which errors out, failing to
+  flash the keyboard, leaving it in DFU mode.
+  - To this end, note that the maximum .hex file size on Planck is
+    7000h (28672 decimal)
+
+```
+Linking: .build/planck_rev4_cbbrowne.elf                                                            [OK]
+Creating load file for Flash: .build/planck_rev4_cbbrowne.hex                                       [OK]
+
+Size after:
+   text    data     bss     dec     hex filename
+      0   22396       0   22396    577c planck_rev4_cbbrowne.hex
+```
+
+  - The above file is of size 22396/577ch, which is less than
+    28672/7000h
+  - As long as you have a suitable alternative .hex file around, you
+    can retry, loading that one
+  - Some of the options you might specify in your keyboard's Makefile
+    consume extra memory; watch out for BOOTMAGIC_ENABLE,
+    MOUSEKEY_ENABLE, EXTRAKEY_ENABLE, CONSOLE_ENABLE, API_SYSEX_ENABLE
+- DFU tools do /not/ allow you to write into the bootloader (unless
+  you throw in extra fruit salad of options), so there is little risk
+  there.
+- EEPROM has around a 100000 write cycle.  You shouldn't rewrite the
+  firmware repeatedly and continually; that'll burn the EEPROM
+  eventually.
+
+## NKRO Doesn't work
+First you have to compile firmware with this build option `NKRO_ENABLE` in **Makefile**.
+
+Try `Magic` **N** command(`LShift+RShift+N` by default) when **NKRO** still doesn't work. You can use this command to toggle between **NKRO** and **6KRO** mode temporarily. In some situations **NKRO** doesn't work you need to switch to **6KRO** mode, in particular when you are in BIOS.
+
+If your firmware built with `BOOTMAGIC_ENABLE` you need to turn its switch on by `BootMagic` **N** command(`Space+N` by default). This setting is stored in EEPROM and kept over power cycles.
+
+https://github.com/tmk/tmk_keyboard#boot-magic-configuration---virtual-dip-switch
+
+
+## TrackPoint Needs Reset Circuit (PS/2 Mouse Support)
+Without reset circuit you will have inconsistent result due to improper initialize of the hardware. See circuit schematic of TPM754.
+
+- http://geekhack.org/index.php?topic=50176.msg1127447#msg1127447
+- http://www.mikrocontroller.net/attachment/52583/tpm754.pdf
+
+
+## Can't Read Column of Matrix Beyond 16
+Use `1UL<<16` instead of `1<<16` in `read_cols()` in [matrix.h] when your columns goes beyond 16.
+
+In C `1` means one of [int] type which is [16 bit] in case of AVR so you can't shift left more than 15. You will get unexpected zero when you say `1<<16`. You have to use [unsigned long] type with `1UL`.
+
+http://deskthority.net/workshop-f7/rebuilding-and-redesigning-a-classic-thinkpad-keyboard-t6181-60.html#p146279
+
+
+## Bootloader Jump Doesn't Work
+Properly configure bootloader size in **Makefile**. With wrong section size bootloader won't probably start with **Magic command** and **Boot Magic**.
+```
+# Size of Bootloaders in bytes:
+#   Atmel DFU loader(ATmega32U4)   4096
+#   Atmel DFU loader(AT90USB128)   8192
+#   LUFA bootloader(ATmega32U4)    4096
+#   Arduino Caterina(ATmega32U4)   4096
+#   USBaspLoader(ATmega***)        2048
+#   Teensy   halfKay(ATmega32U4)   512
+#   Teensy++ halfKay(AT90USB128)   2048
+OPT_DEFS += -DBOOTLOADER_SIZE=4096
+```
+AVR Boot section size are defined by setting **BOOTSZ** fuse in fact. Consult with your MCU datasheet.
+Note that **Word**(2 bytes) size and address are used in datasheet while TMK uses **Byte**.
+
+AVR Boot section is located at end of Flash memory like the followings.
+```
+byte     Atmel/LUFA(ATMega32u4)          byte     Atmel(AT90SUB1286)
+0x0000   +---------------+               0x00000  +---------------+
+         |               |                        |               |
+         |               |                        |               |
+         |  Application  |                        |  Application  |
+         |               |                        |               |
+         =               =                        =               =
+         |               | 32KB-4KB               |               | 128KB-8KB
+0x6000   +---------------+               0x1E000  +---------------+
+         |  Bootloader   | 4KB                    |  Bootloader   | 8KB
+0x7FFF   +---------------+               0x1FFFF  +---------------+
+
+
+byte     Teensy(ATMega32u4)              byte     Teensy++(AT90SUB1286)
+0x0000   +---------------+               0x00000  +---------------+
+         |               |                        |               |
+         |               |                        |               |
+         |  Application  |                        |  Application  |
+         |               |                        |               |
+         =               =                        =               =
+         |               | 32KB-512B              |               | 128KB-2KB
+0x7E00   +---------------+               0x1FC00  +---------------+
+         |  Bootloader   | 512B                   |  Bootloader   | 2KB
+0x7FFF   +---------------+               0x1FFFF  +---------------+
+```
+
+And see this discussion for further reference.
+https://github.com/tmk/tmk_keyboard/issues/179
+
+If you are using a TeensyUSB, there is a [known bug](https://github.com/qmk/qmk_firmware/issues/164) in which the hardware reset button prevents the RESET key from working. Unplugging the keyboard and plugging it back in should resolve the problem.
+
+## Special Extra Key Doesn't Work (System, Audio Control Keys)
+You need to define `EXTRAKEY_ENABLE` in `rules.mk` to use them in QMK.
+
+```
+EXTRAKEY_ENABLE = yes          # Audio control and System control
+```
+
+## Wakeup from Sleep Doesn't Work
+
+In Windows check `Allow this device to wake the computer` setting in Power **Management property** tab of **Device Manager**. Also check BIOS setting.
+
+Pressing any key during sleep should wake host.
+
+## Using Arduino?
+
+**Note that Arduino pin naming is different from actual chip.** For example, Arduino pin `D0` is not `PD0`. Check circuit with its schematics yourself.
+
+- http://arduino.cc/en/uploads/Main/arduino-leonardo-schematic_3b.pdf
+- http://arduino.cc/en/uploads/Main/arduino-micro-schematic.pdf
+
+Arduino Leonardo and micro have **ATMega32U4** and can be used for TMK, though Arduino bootloader may be a problem.
+
+## Enabling JTAG
+
+By default, the JTAG debugging interface is disabled as soon as the keyboard starts up. JTAG-capable MCUs come from the factory with the `JTAGEN` fuse set, and it takes over certain pins of the MCU that the board may be using for the switch matrix, LEDs, etc.
+
+If you would like to keep JTAG enabled, just add the following to your `config.h`:
+
+```c
+#define NO_JTAG_DISABLE
+```
+
+## Adding LED Indicators of Lock Keys
+You need your own LED indicators for CapsLock, ScrollLock and NumLock? See this post.
+
+http://deskthority.net/workshop-f7/tmk-keyboard-firmware-collection-t4478-120.html#p191560
+
+## Program Arduino Micro/Leonardo
+Push reset button and then run command like this within 8 seconds.
+
+```
+avrdude -patmega32u4 -cavr109 -b57600 -Uflash:w:adb_usb.hex -P/dev/ttyACM0
+```
+
+Device name will vary depending on your system.
+
+http://arduino.cc/en/Main/ArduinoBoardMicro
+https://geekhack.org/index.php?topic=14290.msg1563867#msg1563867
+
+
+## USB 3 Compatibility
+I heard some people have a problem with USB 3 port, try USB 2 port.
+
+
+## Mac Compatibility
+### OS X 10.11 and Hub
+https://geekhack.org/index.php?topic=14290.msg1884034#msg1884034
+
+
+## Problem on BIOS (UEFI)/Resume (Sleep & Wake)/Power Cycles
+Some people reported their keyboard stops working on BIOS and/or after resume(power cycles).
+
+As of now root of its cause is not clear but some build options seem to be related. In Makefile try to disable those options like `CONSOLE_ENABLE`, `NKRO_ENABLE`, `SLEEP_LED_ENABLE` and/or others.
+
+https://github.com/tmk/tmk_keyboard/issues/266
+https://geekhack.org/index.php?topic=41989.msg1967778#msg1967778
+
+
+
+## FLIP Doesn't Work
+### `AtLibUsbDfu.dll` Not Found
+Remove current driver and reinstall one FLIP provides from DeviceManager.
+http://imgur.com/a/bnwzy

docs/faq_general.md

@@ -0,0 +1,15 @@
+# Frequently Asked Questions
+
+## What is QMK?
+
+[QMK](https://github.com/qmk), short for Quantum Mechanical Keyboard, is a group of people building tools for custom keyboards. We started with the [QMK firmware](https://github.com/qmk/qmk_firmware), a heavily modified fork of [TMK](https://github.com/tmk/tmk_keyboard).
+
+## What Differences Are There Between QMK and TMK?
+
+TMK was originally designed and implemented by [Jun Wako](https://github.com/tmk). QMK started as [Jack Humbert](https://github.com/jackhumbert)'s fork of TMK for the Planck. After a while Jack's fork had diverged quite a bit from TMK, and in 2015 Jack decided to rename his fork to QMK.
+
+From a technical standpoint QMK builds upon TMK by adding several new features. Most notably QMK has expanded the number of available keycodes and uses these to implement advanced features like `S()`, `LCTL()`, and `MO()`. You can see a complete list of these keycodes in [Keycodes](keycodes.md).
+
+From a project and community management standpoint TMK maintains all the officially supported keyboards by himself, with a bit of community support. Separate community maintained forks exist or can be created for other keyboards. Only a few keymaps are provided by default, so users typically don't share keymaps with each other. QMK encourages sharing of both keyboards and keymaps through a centrally managed repository, accepting all pull requests that follow the quality standards. These are mostly community maintained, but the QMK team also helps when necessary.
+
+Both approaches have their merits and their drawbacks, and code flows freely between TMK and QMK when it makes sense.

docs/faq_keymap.md

@@ -0,0 +1,213 @@
+# Keymap FAQ
+
+This page covers questions people often have about keymaps. If you haven't you should read [Keymap Overview](keymap.md) first.
+
+## What Keycodes Can I Use?
+See [Keycodes](keycodes.md) for an index of keycodes available to you. These link to more extensive documentation when available.
+
+Keycodes are actually defined in [common/keycode.h](https://github.com/qmk/qmk_firmware/blob/master/tmk_core/common/keycode.h).
+
+## What Are the Default Keycodes?
+
+There are 3 standard keyboard layouts in use around the world- ANSI, ISO, and JIS. North America primarily uses ANSI, Europe and Africa primarily use ISO, and Japan uses JIS. Regions not mentioned typically use either ANSI or ISO. The keycodes corresponding to these layouts are shown here:
+
+<!-- Source for this image: http://www.keyboard-layout-editor.com/#/gists/bf431647d1001cff5eff20ae55621e9a -->
+![Keyboard Layout Image](https://i.imgur.com/5wsh5wM.png)
+
+## Some Of My Keys Are Swapped Or Not Working
+
+QMK has two features, Bootmagic and Command, which allow you to change the behavior of your keyboard on the fly. This includes, but is not limited to, swapping Ctrl/Caps, disabling Gui, swapping Alt/Gui, swapping Backspace/Backslash, disabling all keys, and other behavioral modifications. 
+
+As a quick fix try holding down `Space`+`Backspace` while you plug in your keyboard. This will reset the stored settings on your keyboard, returning those keys to normal operation. If that doesn't work look here:
+
+* [Bootmagic](feature_bootmagic.md)
+* [Command](feature_command.md) 
+
+## The Menu Key Isn't Working
+
+The key found on most modern keyboards that is located between `KC_RGUI` and `KC_RCTL` is actually called `KC_APP`. This is because when that key was invented there was already a key named `MENU` in the relevant standards, so MS chose to call that the `APP` key.
+
+## `KC_SYSREQ` Isn't Working
+Use keycode for Print Screen(`KC_PSCREEN` or `KC_PSCR`) instead of `KC_SYSREQ`. Key combination of 'Alt + Print Screen' is recognized as 'System request'.
+
+See [issue #168](https://github.com/tmk/tmk_keyboard/issues/168) and
+* http://en.wikipedia.org/wiki/Magic_SysRq_key
+* http://en.wikipedia.org/wiki/System_request
+
+## Power Keys Aren't Working
+
+Somewhat confusingly, there are two "Power" keycodes in QMK: `KC_POWER` in the Keyboard/Keypad HID usage page, and `KC_SYSTEM_POWER` (or `KC_PWR`) in the Consumer page.
+
+The former is only recognized on macOS, while the latter, `KC_SLEP` and `KC_WAKE` are supported by all three major operating systems, so it is recommended to use those instead. Under Windows, these keys take effect immediately, however on macOS they must be held down until a dialog appears.
+
+## One Shot Modifier
+Solves my personal 'the' problem. I often got 'the' or 'THe' wrongly instead of 'The'.  One Shot Shift mitigates this for me.
+https://github.com/tmk/tmk_keyboard/issues/67
+
+## Modifier/Layer Stuck
+Modifier keys or layers can be stuck unless layer switching is configured properly.
+For Modifier keys and layer actions you have to place `KC_TRANS` on same position of destination layer to  unregister the modifier key or return to previous layer on release event.
+
+* https://github.com/tmk/tmk_core/blob/master/doc/keymap.md#31-momentary-switching
+* http://geekhack.org/index.php?topic=57008.msg1492604#msg1492604
+* https://github.com/tmk/tmk_keyboard/issues/248
+
+
+## Mechanical Lock Switch Support
+
+This feature is for *mechanical lock switch* like [this Alps one](http://deskthority.net/wiki/Alps_SKCL_Lock). You can enable it by adding this to your `config.h`:
+
+```
+#define LOCKING_SUPPORT_ENABLE
+#define LOCKING_RESYNC_ENABLE
+```
+
+After enabling this feature use keycodes `KC_LCAP`, `KC_LNUM` and `KC_LSCR` in your keymap instead.
+
+Old vintage mechanical keyboards occasionally have lock switches but modern ones don't have. ***You don't need this feature in most case and just use keycodes `KC_CAPS`, `KC_NLCK` and `KC_SLCK`.***
+
+## Input Special Characters Other Than ASCII like Cédille 'Ç'
+NO UNIVERSAL METHOD TO INPUT THOSE WORKS OVER ALL SYSTEMS. You have to define **MACRO** in way specific to your OS or layout.
+
+See this post for example **MACRO** code.
+
+http://deskthority.net/workshop-f7/tmk-keyboard-firmware-collection-t4478-120.html#p195620
+
+On **Windows** you can use `AltGr` key or **Alt code**.
+* http://en.wikipedia.org/wiki/AltGr_key
+* http://en.wikipedia.org/wiki/Alt_code
+
+On **Mac** OS defines `Option` key combinations.
+* http://en.wikipedia.org/wiki/Option_key#Alternative_keyboard_input
+
+On **Xorg** you can use `compose` key, instead.
+* http://en.wikipedia.org/wiki/Compose_key
+
+And see this for **Unicode** input.
+* http://en.wikipedia.org/wiki/Unicode_input
+
+## `Fn` Key on macOS
+
+Unlike most Fn keys, the one on Apple keyboards actually has its own keycode... sort of. It takes the place of the sixth keycode in a basic 6KRO HID report -- so an Apple keyboard is in fact only 5KRO.
+
+It is technically possible to get QMK to send this key. However, doing so requires modification of the report format to add the state of the Fn key.
+Even worse, it is not recognized unless the keyboard's VID and PID match that of a real Apple keyboard. The legal issues that official QMK support for this feature may create mean it is unlikely to happen.
+
+See [this issue](https://github.com/qmk/qmk_firmware/issues/2179) for detailed information.
+
+
+## Media Control Keys in Mac OSX
+#### KC_MNXT and KC_MPRV Does Not Work on Mac
+Use `KC_MFFD`(`KC_MEDIA_FAST_FORWARD`) and `KC_MRWD`(`KC_MEDIA_REWIND`) instead of `KC_MNXT` and `KC_MPRV`.
+See https://github.com/tmk/tmk_keyboard/issues/195
+
+
+## Keys Supported in Mac OSX?
+You can know which keycodes are supported in OSX from this source code.
+
+`usb_2_adb_keymap` array maps Keyboard/Keypad Page usages to ADB scancodes(OSX internal keycodes).
+
+https://opensource.apple.com/source/IOHIDFamily/IOHIDFamily-606.1.7/IOHIDFamily/Cosmo_USB2ADB.c
+
+And `IOHIDConsumer::dispatchConsumerEvent` handles Consumer page usages.
+
+https://opensource.apple.com/source/IOHIDFamily/IOHIDFamily-606.1.7/IOHIDFamily/IOHIDConsumer.cpp
+
+
+## JIS Keys in Mac OSX
+Japanese JIS keyboard specific keys like `無変換(Muhenkan)`, `変換(Henkan)`, `ひらがな(hiragana)` are not recognized on OSX. You can use **Seil** to enable those keys, try following options.
+
+* Enable NFER Key on PC keyboard
+* Enable XFER Key on PC keyboard
+* Enable KATAKANA Key on PC keyboard
+
+https://pqrs.org/osx/karabiner/seil.html
+
+
+## RN-42 Bluetooth Doesn't Work with Karabiner
+Karabiner - Keymapping tool on Mac OSX - ignores inputs from RN-42 module by default. You have to enable this option to make Karabiner working with your keyboard.
+https://github.com/tekezo/Karabiner/issues/403#issuecomment-102559237
+
+See these for the detail of this problem.
+https://github.com/tmk/tmk_keyboard/issues/213
+https://github.com/tekezo/Karabiner/issues/403
+
+
+## Esc and <code>&#96;</code> on a Single Key
+
+See the [Grave Escape](feature_grave_esc.md) feature.
+
+## Arrow on Right Modifier Keys with Dual-Role
+This turns right modifier keys into arrow keys when the keys are tapped while still modifiers when the keys are hold. In TMK the dual-role function is dubbed **TAP**.
+```
+
+#include "keymap_common.h"
+
+
+/* Arrow keys on right modifier keys with TMK dual role feature
+ *
+ *  https://github.com/tmk/tmk_core/blob/master/doc/keymap.md#213-modifier-with-tap-keydual-role
+ *  https://en.wikipedia.org/wiki/Modifier_key#Dual-role_keys
+ */
+const uint8_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
+    /* 0: qwerty */
+    [0] = LAYOUT( \
+        ESC, 1,   2,   3,   4,   5,   6,   7,   8,   9,   0,   MINS,EQL, NUHS,BSPC, \
+        TAB, Q,   W,   E,   R,   T,   Y,   U,   I,   O,   P,   LBRC,RBRC,BSLS, \
+        LCTL,A,   S,   D,   F,   G,   H,   J,   K,   L,   SCLN,QUOT,ENT,  \
+        LSFT,NUBS,Z,   X,   C,   V,   B,   N,   M,   COMM,DOT, SLSH,FN0, ESC, \
+        FN4, LGUI,LALT,          SPC,                     APP, FN2, FN1, FN3),
+    [1] = LAYOUT( \
+        GRV, F1,  F2,  F3,  F4,  F5,  F6,  F7,  F8,  F9,  F10, F11, F12, TRNS,TRNS, \
+        TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,\
+        TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS, \
+        TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,FN5, TRNS, \
+        TRNS,TRNS,TRNS,          TRNS,                    TRNS,FN7, FN6, FN8),
+};
+
+const uint16_t PROGMEM fn_actions[] = {
+    [0] = ACTION_MODS_TAP_KEY(MOD_RSFT, KC_UP),
+    [1] = ACTION_MODS_TAP_KEY(MOD_RGUI, KC_DOWN),
+    [2] = ACTION_MODS_TAP_KEY(MOD_RALT, KC_LEFT),
+    [3] = ACTION_MODS_TAP_KEY(MOD_RCTL, KC_RIGHT),
+    [4] = ACTION_LAYER_MOMENTARY(1),
+    [5] = ACTION_MODS_TAP_KEY(MOD_RSFT, KC_PGUP),
+    [6] = ACTION_MODS_TAP_KEY(MOD_RGUI, KC_PGDN),
+    [7] = ACTION_MODS_TAP_KEY(MOD_RALT, KC_HOME),
+    [8] = ACTION_MODS_TAP_KEY(MOD_RCTL, KC_END),
+};
+
+```
+
+Dual-role key: https://en.wikipedia.org/wiki/Modifier_key#Dual-role_keys
+
+
+## Eject on Mac OSX
+`KC_EJCT` keycode works on OSX. https://github.com/tmk/tmk_keyboard/issues/250
+It seems Windows 10 ignores the code and Linux/Xorg recognizes but has no mapping by default.
+
+Not sure what keycode Eject is on genuine Apple keyboard actually. HHKB uses `F20` for Eject key(`Fn+f`) on Mac mode but this is not same as Apple Eject keycode probably.
+
+
+## What's `weak_mods` and `real_mods` in `action_util.c`
+___TO BE IMPROVED___
+
+real_mods is intended to retains state of real/physical modifier key state, while
+weak_mods retains state of virtual or temporary modifiers which should not affect state real modifier key.
+
+Let's say you hold down physical left shift key and type ACTION_MODS_KEY(LSHIFT, KC_A),
+
+with weak_mods,
+* (1) hold down left shift: real_mods |= MOD_BIT(LSHIFT)
+* (2) press ACTION_MODS_KEY(LSHIFT, KC_A): weak_mods |= MOD_BIT(LSHIFT)
+* (3) release ACTION_MODS_KEY(LSHIFT, KC_A): weak_mods &= ~MOD_BIT(LSHIFT)
+real_mods still keeps modifier state.
+
+without weak mods,
+* (1) hold down left shift: real_mods |= MOD_BIT(LSHIFT)
+* (2) press ACTION_MODS_KEY(LSHIFT, KC_A): real_mods |= MOD_BIT(LSHIFT)
+* (3) release ACTION_MODS_KEY(LSHIFT, KC_A): real_mods &= ~MOD_BIT(LSHIFT)
+here real_mods lost state for 'physical left shift'.
+
+weak_mods is ORed with real_mods when keyboard report is sent.
+https://github.com/tmk/tmk_core/blob/master/common/action_util.c#L57

docs/feature_advanced_keycodes.md

@@ -0,0 +1,328 @@
+# Advanced Keycodes
+
+Your keymap can include keycodes that are more advanced than normal, for example keys that switch layers or send modifiers when held, but send regular keycodes when tapped. This page documents the functions that are available to you.
+
+## Assigning Custom Names
+
+People often define custom names using `#define`. For example:
+
+```c
+#define FN_CAPS LT(_FL, KC_CAPSLOCK)
+#define ALT_TAB LALT(KC_TAB)
+```
+
+This will allow you to use `FN_CAPS` and `ALT_TAB` in your keymap, keeping it more readable.
+
+## Caveats
+
+Currently, `LT()` and `MT()` are limited to the [Basic Keycode set](keycodes_basic.md), meaning you can't use keycodes like `LCTL()`, `KC_TILD`, or anything greater than `0xFF`. Modifiers specified as part of a Layer Tap or Mod Tap's keycode will be ignored. If you need to apply modifiers to your tapped keycode, [Tap Dance](https://github.com/qmk/qmk_firmware/blob/master/docs/feature_tap_dance.md#example-5-using-tap-dance-for-advanced-mod-tap-and-layer-tap-keys) can be used to accomplish this.
+
+Additionally, if at least one right-handed modifier is specified in a Mod Tap or Layer Tap, it will cause all modifiers specified to become right-handed, so it is not possible to mix and match the two.
+
+# Switching and Toggling Layers
+
+These functions allow you to activate layers in various ways. Note that layers are not generally independent layouts -- multiple layers can be activated at once, and it's typical for layers to use `KC_TRNS` to allow keypresses to pass through to lower layers. For a detailed explanation of layers, see [Keymap Overview](keymap.md#keymap-and-layers). When using momentary layer switching with MO(), LM(), TT(), or LT(), make sure to leave the key on the above layers transparent or it may not work as intended.
+
+* `DF(layer)` - switches the default layer. The default layer is the always-active base layer that other layers stack on top of. See below for more about the default layer. This might be used to switch from QWERTY to Dvorak layout. (Note that this is a temporary switch that only persists until the keyboard loses power. To modify the default layer in a persistent way requires deeper customization, such as calling the `set_single_persistent_default_layer` function inside of [process_record_user](custom_quantum_functions.md#programming-the-behavior-of-any-keycode).)
+* `MO(layer)` - momentarily activates *layer*. As soon as you let go of the key, the layer is deactivated. 
+* `LM(layer, mod)` - Momentarily activates *layer* (like `MO`), but with modifier(s) *mod* active. Only supports layers 0-15 and the left modifiers: `MOD_LCTL`, `MOD_LSFT`, `MOD_LALT`, `MOD_LGUI` (note the use of `MOD_` constants instead of `KC_`). These modifiers can be combined using bitwise OR, e.g. `LM(_RAISE, MOD_LCTL | MOD_LALT)`.
+* `LT(layer, kc)` - momentarily activates *layer* when held, and sends *kc* when tapped. Only supports layers 0-15.
+* `OSL(layer)` - momentarily activates *layer* until the next key is pressed. See [One Shot Keys](#one-shot-keys) for details and additional functionality.
+* `TG(layer)` - toggles *layer*, activating it if it's inactive and vice versa
+* `TO(layer)` - activates *layer* and de-activates all other layers (except your default layer). This function is special, because instead of just adding/removing one layer to your active layer stack, it will completely replace your current active layers, uniquely allowing you to replace higher layers with a lower one. This is activated on keydown (as soon as the key is pressed).
+* `TT(layer)` - Layer Tap-Toggle. If you hold the key down, *layer* is activated, and then is de-activated when you let go (like `MO`). If you repeatedly tap it, the layer will be toggled on or off (like `TG`). It needs 5 taps by default, but you can change this by defining `TAPPING_TOGGLE` -- for example, `#define TAPPING_TOGGLE 2` to toggle on just two taps.
+
+# Working with Layers
+
+Care must be taken when switching layers, it's possible to lock yourself into a layer with no way to deactivate that layer (without unplugging your keyboard.) We've created some guidelines to help users avoid the most common problems.
+
+## Beginners
+
+If you are just getting started with QMK you will want to keep everything simple. Follow these guidelines when setting up your layers:
+
+* Setup layer 0 as your default, "base" layer. This is your normal typing layer, and could be whatever layout you want (qwerty, dvorak, colemak, etc.). It's important to set this as the lowest layer since it will typically have most or all of the keyboard's keys defined, so would block other layers from having any effect if it were above them (i.e., had a higher layer number). 
+* Arrange your layers in a "tree" layout, with layer 0 as the root. Do not try to enter the same layer from more than one other layer.
+* In a layer's keymap, only reference higher-numbered layers. Because layers are processed from the highest-numbered (topmost) active layer down, modifying the state of lower layers can be tricky and error-prone.
+
+## Intermediate Users
+
+Sometimes you need more than one base layer. For example, if you want to switch between QWERTY and Dvorak, switch between layouts for different countries, or switch your layout for different videogames. Your base layers should always be the lowest numbered layers. When you have multiple base layers you should always treat them as mutually exclusive. When one base layer is on the others are off.
+
+## Advanced Users
+
+Once you have a good feel for how layers work and what you can do, you can get more creative. The rules listed in the beginner section will help you be successful by avoiding some of the tricker details but they can be constraining, especially for ultra-compact keyboard users. Understanding how layers work will allow you to use them in more advanced ways.
+
+Layers stack on top of each other in numerical order. When determining what a keypress does, QMK scans the layers from the top down, stopping when it reaches the first active layer that is not set to `KC_TRNS`. As a result if you activate a layer that is numerically lower than your current layer, and your current layer (or another layer that is active and higher than your target layer) has something other than `KC_TRNS`, that is the key that will be sent, not the key on the layer you just activated. This is the cause of most people's "why doesn't my layer get switched" problem.
+
+Sometimes, you might want to switch between layers in a macro or as part of a tap dance routine. `layer_on` activates a layer, and `layer_off` deactivates it. More layer-related functions can be found in [action_layer.h](https://github.com/qmk/qmk_firmware/blob/master/tmk_core/common/action_layer.h).
+
+# Modifier Keys
+
+These allow you to combine a modifier with a keycode. When pressed, the keydown event for the modifier, then `kc` will be sent. On release, the keyup event for `kc`, then the modifier will be sent.
+
+|Key       |Aliases                        |Description                                         |
+|----------|-------------------------------|----------------------------------------------------|
+|`LCTL(kc)`|`C(kc)`                        |Hold Left Control and press `kc`                    |
+|`LSFT(kc)`|`S(kc)`                        |Hold Left Shift and press `kc`                      |
+|`LALT(kc)`|`A(kc)`                        |Hold Left Alt and press `kc`                        |
+|`LGUI(kc)`|`G(kc)`, `LCMD(kc)`, `LWIN(kc)`|Hold Left GUI and press `kc`                        |
+|`RCTL(kc)`|                               |Hold Right Control and press `kc`                   |
+|`RSFT(kc)`|                               |Hold Right Shift and press `kc`                     |
+|`RALT(kc)`|`ALGR(kc)`                     |Hold Right Alt and press `kc`                       |
+|`RGUI(kc)`|`RCMD(kc)`, `LWIN(kc)`         |Hold Right GUI and press `kc`                       |
+|`SGUI(kc)`|`SCMD(kc)`, `SWIN(kc)`         |Hold Left Shift and GUI and press `kc`              |
+|`LCA(kc)` |                               |Hold Left Control and Alt and press `kc`            |
+|`LCAG(kc)`|                               |Hold Left Control, Alt and GUI and press `kc`       |
+|`MEH(kc)` |                               |Hold Left Control, Shift and Alt and press `kc`     |
+|`HYPR(kc)`|                               |Hold Left Control, Shift, Alt and GUI and press `kc`|
+
+You can also chain them, for example `LCTL(LALT(KC_DEL))` makes a key that sends Control+Alt+Delete with a single keypress.
+
+# Mod-Tap
+
+The Mod-Tap key `MT(mod, kc)` acts like a modifier when held, and a regular keycode when tapped. In other words, you can have a key that sends Escape when you tap it, but functions as a Control or Shift key when you hold it down.
+
+The modifiers this keycode and `OSM()` accept are prefixed with `MOD_`, not `KC_`:
+
+|Modifier  |Description                             |
+|----------|----------------------------------------|
+|`MOD_LCTL`|Left Control                            |
+|`MOD_LSFT`|Left Shift                              |
+|`MOD_LALT`|Left Alt                                |
+|`MOD_LGUI`|Left GUI (Windows/Command/Meta key)     |
+|`MOD_RCTL`|Right Control                           |
+|`MOD_RSFT`|Right Shift                             |
+|`MOD_RALT`|Right Alt (AltGr)                       |
+|`MOD_RGUI`|Right GUI (Windows/Command/Meta key)    |
+|`MOD_HYPR`|Hyper (Left Control, Shift, Alt and GUI)|
+|`MOD_MEH` |Meh (Left Control, Shift, and Alt)      |
+
+You can combine these by ORing them together like so:
+
+```c
+MT(MOD_LCTL | MOD_LSFT, KC_ESC)
+```
+
+This key would activate Left Control and Left Shift when held, and send Escape when tapped.
+
+For convenience, QMK includes some Mod-Tap shortcuts to make common combinations more compact in your keymap:
+
+|Key         |Aliases                                                          |Description                                            |
+|------------|-----------------------------------------------------------------|-------------------------------------------------------|
+|`LCTL_T(kc)`|`CTL_T(kc)`                                                      |Left Control when held, `kc` when tapped               |
+|`LSFT_T(kc)`|`SFT_T(kc)`                                                      |Left Shift when held, `kc` when tapped                 |
+|`LALT_T(kc)`|`ALT_T(kc)`                                                      |Left Alt when held, `kc` when tapped                   |
+|`LGUI_T(kc)`|`LCMD_T(kc)`, `LWIN_T(kc)`, `GUI_T(kc)`, `CMD_T(kc)`, `WIN_T(kc)`|Left GUI when held, `kc` when tapped                   |
+|`RCTL_T(kc)`|                                                                 |Right Control when held, `kc` when tapped              |
+|`RSFT_T(kc)`|                                                                 |Right Shift when held, `kc` when tapped                |
+|`RALT_T(kc)`|`ALGR_T(kc)`                                                     |Right Alt when held, `kc` when tapped                  |
+|`RGUI_T(kc)`|`RCMD_T(kc)`, `RWIN_T(kc)`                                       |Right GUI when held, `kc` when tapped                  |
+|`SGUI_T(kc)`|`SCMD_T(kc)`, `SWIN_T(kc)`                                       |Left Shift and GUI when held, `kc` when tapped         |
+|`LCA_T(kc)` |                                                                 |Left Control and Alt when held, `kc` when tapped       |
+|`LCAG_T(kc)`|                                                                 |Left Control, Alt and GUI when held, `kc` when tapped  |
+|`RCAG_T(kc)`|                                                                 |Right Control, Alt and GUI when held, `kc` when tapped |
+|`C_S_T(kc)` |                                                                 |Left Control and Shift when held, `kc` when tapped     |
+|`MEH_T(kc)` |                                                                 |Left Control, Shift and Alt when held, `kc` when tapped|
+|`HYPR_T(kc)`|`ALL_T(kc)`                                                      |Left Control, Shift, Alt and GUI when held, `kc` when tapped - more info [here](http://brettterpstra.com/2012/12/08/a-useful-caps-lock-key/)|
+
+## Caveats
+
+Unfortunately, these keycodes cannot be used in Mod-Taps or Layer-Taps, since any modifiers specified in the keycode are ignored.
+
+Additionally, you may run into issues when using Remote Desktop Connection on Windows. Because these codes send shift very fast, Remote Desktop may miss the codes.
+
+To fix this, open Remote Desktop Connection, click on "Show Options", open the the "Local Resources" tab. In the keyboard section, change the drop down to "On this Computer". This will fix the issue, and allow the characters to work correctly.
+
+# One Shot Keys
+
+One shot keys are keys that remain active until the next key is pressed, and then are released. This allows you to type keyboard combinations without pressing more than one key at a time. These keys are usually called "Sticky keys" or "Dead keys".
+
+For example, if you define a key as `OSM(MOD_LSFT)`, you can type a capital A character by first pressing and releasing shift, and then pressing and releasing A. Your computer will see the shift key being held the moment shift is pressed, and it will see the shift key being released immediately after A is released.
+
+One shot keys also work as normal modifiers. If you hold down a one shot key and type other keys, your one shot will be released immediately after you let go of the key.
+
+Additionally, hitting keys five times in a short period will lock that key. This applies for both One Shot Modifiers and One Shot Layers, and is controlled by the `ONESHOT_TAP_TOGGLE` define.
+
+You can control the behavior of one shot keys by defining these in `config.h`:
+
+```c
+#define ONESHOT_TAP_TOGGLE 5  /* Tapping this number of times holds the key until tapped once again. */
+#define ONESHOT_TIMEOUT 5000  /* Time (in ms) before the one shot key is released */
+```
+
+* `OSM(mod)` - Momentarily hold down *mod*. You must use the `MOD_*` keycodes as shown in [Mod Tap](#mod-tap), not the `KC_*` codes.
+* `OSL(layer)` - momentary switch to *layer*.
+
+Sometimes, you want to activate a one-shot key as part of a macro or tap dance routine.  
+
+For one shot layers, you need to call `set_oneshot_layer(LAYER, ONESHOT_START)` on key down, and `set_oneshot_layer(ONESHOT_PRESSED)` on key up. If you want to cancel the oneshot, call `reset_oneshot_layer()`.
+
+For one shot mods, you need to call `set_oneshot_mods(MOD)` to set it, or `clear_oneshot_mods()` to cancel it.
+
+!> If you're having issues with OSM translating over Remote Desktop Connection, this can be fixed by opening the settings, going to the "Local Resources" tap, and in the keyboard section, change the drop down to "On this Computer".  This will fix the issue and allow OSM to function properly over Remote Desktop.
+
+## Callbacks
+
+When you'd like to perform custom logic when pressing a one shot key, there are several callbacks you can choose to implement. You could indicate changes in one shot keys by flashing an LED or making a sound, for example.
+
+There is a callback for `OSM(mod)`. It is called whenever the state of any one shot modifier key is changed: when it toggles on, but also when it is toggled off. You can use it like this:
+
+```c
+void oneshot_mods_changed_user(uint8_t mods) {
+  if (mods & MOD_MASK_SHIFT) {
+    println("Oneshot mods SHIFT");
+  }
+  if (mods & MOD_MASK_CTRL) {
+    println("Oneshot mods CTRL");
+  }
+  if (mods & MOD_MASK_ALT) {
+    println("Oneshot mods ALT");
+  }
+  if (mods & MOD_MASK_GUI) {
+    println("Oneshot mods GUI");
+  }
+  if (!mods) {
+    println("Oneshot mods off");
+  }
+}
+```
+
+The `mods` argument contains the active mods after the change, so it reflects the current state.
+
+When you use One Shot Tap Toggle (by adding `#define ONESHOT_TAP_TOGGLE 2` in your `config.h` file), you may lock a modifier key by pressing it the specified amount of times. There's a callback for that, too:
+
+```c
+void oneshot_locked_mods_changed_user(uint8_t mods) {
+  if (mods & MOD_MASK_SHIFT) {
+    println("Oneshot locked mods SHIFT");
+  }
+  if (mods & MOD_MASK_CTRL) {
+    println("Oneshot locked mods CTRL");
+  }
+  if (mods & MOD_MASK_ALT) {
+    println("Oneshot locked mods ALT");
+  }
+  if (mods & MOD_MASK_GUI) {
+    println("Oneshot locked mods GUI");
+  }
+  if (!mods) {
+    println("Oneshot locked mods off");
+  }
+}
+```
+
+Last, there is also a callback for the `OSL(layer)` one shot key:
+
+```c
+void oneshot_layer_changed_user(uint8_t layer) {
+  if (layer == 1) {
+    println("Oneshot layer 1 on");
+  }
+  if (!layer) {
+    println("Oneshot layer off");
+  }
+}
+```
+
+If any one shot layer is switched off, `layer` will be zero. When you're looking to do something on any layer change instead of one shot layer changes, `layer_state_set_user` is a better callback to use.
+
+If you are making your own keyboard, there are also `_kb` equivalent functions:
+
+```c
+void oneshot_locked_mods_changed_kb(uint8_t mods);
+void oneshot_mods_changed_kb(uint8_t mods);
+void oneshot_layer_changed_kb(uint8_t layer);
+```
+
+As with any callback, be sure to call the `_user` variant to allow for further customizability.
+
+# Tap-Hold Configuration Options
+
+While Tap-Hold options are fantastic, they are not without their issues.  We have tried to configure them with reasonal defaults, but that may still cause issues for some people. 
+
+These options let you modify the behavior of the Tap-Hold keys.
+
+## Permissive Hold
+
+As of [PR#1359](https://github.com/qmk/qmk_firmware/pull/1359/), there is a new `config.h` option:
+
+```c
+#define PERMISSIVE_HOLD
+```
+
+This makes tap and hold keys (like Mod Tap) work better for fast typist, or for high `TAPPING_TERM` settings. 
+
+If you press a Mod Tap key, tap another key (press and release) and then release the Mod Tap key, all within the tapping term, it will output the "tapping" function for both keys.
+
+For Instance:
+
+- `SFT_T(KC_A)` Down
+- `KC_X` Down
+- `KC_X` Up
+- `SFT_T(KC_A)` Up
+
+Normally, if you do all this within the `TAPPING_TERM` (default: 200ms) this will be registered as `ax` by the firmware and host system. With permissive hold enabled, this modifies how this is handled by considering the Mod Tap keys as a Mod if another key is tapped, and would registered as `X` (`SHIFT`+`x`). 
+
+?> If you have `Ignore Mod Tap Interrupt` enabled, as well, this will modify how both work. The regular key has the modifier added if the first key is released first or if both keys are held longer than the `TAPPING_TERM`.
+
+## Ignore Mod Tap Interrupt
+
+To enable this setting, add this to your `config.h`:
+
+```c
+#define IGNORE_MOD_TAP_INTERRUPT
+```
+
+Similar to Permissive Hold, this alters how the firmware processes input for fast typist. If you press a Mod Tap key, press another key, release the Mod Tap key, and then release the normal key, it would normally output the "tapping" function for both keys. This may not be desirable for rolling combo keys. 
+
+Setting `Ignore Mod Tap Interrupt` requires  holding both keys for the `TAPPING_TERM` to trigger the hold function (the mod).
+
+For Instance:
+
+- `SFT_T(KC_A)` Down
+- `KC_X` Down
+- `SFT_T(KC_A)` Up
+- `KC_X` Up
+
+Normally, this would send `X` (`SHIFT`+`x`). With `Ignore Mod Tap Interrupt` enabled, holding both keys are required for the `TAPPING_TERM` to register the hold action. A quick tap will output `ax` in this case, while a hold on both will still output `X`  (`SHIFT`+`x`).
+
+
+?> __Note__: This only concerns modifiers and not layer switching keys.
+
+?> If you have `Permissive Hold` enabled, as well, this will modify how both work. The regular key has the modifier added if the first key is released first or if both keys are held longer than the `TAPPING_TERM`.
+
+## Tapping Force Hold
+
+To enable `tapping force hold`, add the following to your `config.h`: 
+
+```c
+#define TAPPING_FORCE_HOLD
+```
+
+When the user holds a key after tap, this repeats the tapped key rather to hold a modifier key.  This allows to use auto repeat for the tapped key.  
+
+Example:
+
+- SFT_T(KC_A) Down
+- SFT_T(KC_A) Up
+- SFT_T(KC_A) Down
+- wait more than tapping term...
+- SFT_T(KC_A) Up
+
+With default settings, `a` will be sent on the first release, then `a` will be sent on the second press allowing the computer to trigger its auto repeat function.
+
+With `TAPPING_FORCE_HOLD`, the second press will be interpreted as a Shift, allowing to use it as a modifier shortly after having used it as a tap.
+
+!> `TAPPING_FORCE_HOLD` will break anything that uses tapping toggles (Such as the `TT` layer keycode, and the One Shot Tapping Toggle).
+
+## Retro Tapping
+
+To enable `retro tapping`, add the following to your `config.h`: 
+
+```c
+#define RETRO_TAPPING
+```
+
+Holding and releasing a dual function key without pressing another key will result in nothing happening. With retro tapping enabled, releasing the key without pressing another will send the original keycode even if it is outside the tapping term.
+
+For instance, holding and releasing `LT(2, KC_SPACE)` without hitting another key will result in nothing happening. With this enabled, it will send `KC_SPACE` instead.

docs/feature_audio.md

@@ -0,0 +1,323 @@
+# Audio
+
+Your keyboard can make sounds! If you've got a Planck, Preonic, or basically any AVR keyboard that allows access to certain PWM-capable pins, you can hook up a simple speaker and make it beep. You can use those beeps to indicate layer transitions, modifiers, special keys, or just to play some funky 8bit tunes.
+
+Up to two simultaneous audio voices are supported, one driven by timer 1 and another driven by timer 3.  The following pins can be defined as audio outputs in config.h:
+
+Timer 1:
+`#define B5_AUDIO`
+`#define B6_AUDIO`
+`#define B7_AUDIO`
+
+Timer 3:
+`#define C4_AUDIO`
+`#define C5_AUDIO`
+`#define C6_AUDIO`
+
+If you add `AUDIO_ENABLE = yes` to your `rules.mk`, there's a couple different sounds that will automatically be enabled without any other configuration:
+
+```
+STARTUP_SONG // plays when the keyboard starts up (audio.c)
+GOODBYE_SONG // plays when you press the RESET key (quantum.c)
+AG_NORM_SONG // plays when you press AG_NORM (quantum.c)
+AG_SWAP_SONG // plays when you press AG_SWAP (quantum.c)
+CG_NORM_SONG // plays when you press CG_NORM (quantum.c)
+CG_SWAP_SONG // plays when you press CG_SWAP (quantum.c)
+MUSIC_ON_SONG // plays when music mode is activated (process_music.c)
+MUSIC_OFF_SONG // plays when music mode is deactivated (process_music.c)
+CHROMATIC_SONG // plays when the chromatic music mode is selected (process_music.c)
+GUITAR_SONG // plays when the guitar music mode is selected (process_music.c)
+VIOLIN_SONG // plays when the violin music mode is selected (process_music.c)
+MAJOR_SONG // plays when the major music mode is selected (process_music.c)
+```
+
+You can override the default songs by doing something like this in your `config.h`:
+
+```c
+#ifdef AUDIO_ENABLE
+  #define STARTUP_SONG SONG(STARTUP_SOUND)
+#endif
+```
+
+A full list of sounds can be found in [quantum/audio/song_list.h](https://github.com/qmk/qmk_firmware/blob/master/quantum/audio/song_list.h) - feel free to add your own to this list! All available notes can be seen in [quantum/audio/musical_notes.h](https://github.com/qmk/qmk_firmware/blob/master/quantum/audio/musical_notes.h).
+
+To play a custom sound at a particular time, you can define a song like this (near the top of the file):
+
+```c
+float my_song[][2] = SONG(QWERTY_SOUND);
+```
+
+And then play your song like this:
+
+```c
+PLAY_SONG(my_song);
+```
+
+Alternatively, you can play it in a loop like this:
+
+```c
+PLAY_LOOP(my_song);
+```
+
+It's advised that you wrap all audio features in `#ifdef AUDIO_ENABLE` / `#endif` to avoid causing problems when audio isn't built into the keyboard.
+
+The available keycodes for audio are: 
+
+* `AU_ON` - Turn Audio Feature on
+* `AU_OFF` - Turn Audio Feature off
+* `AU_TOG` - Toggle Audio Feature state
+
+!> These keycodes turn all of the audio functionality on and off.  Turning it off means that audio feedback, audio clicky, music mode, etc. are disabled, completely. 
+
+## ARM Audio Volume
+
+For ARM devices, you can adjust the DAC sample values. If your board is too loud for you or your coworkers, you can set the max using `DAC_SAMPLE_MAX` in your `config.h`:
+
+```c
+#define DAC_SAMPLE_MAX 65535U
+```
+
+## Music Mode
+
+The music mode maps your columns to a chromatic scale, and your rows to octaves. This works best with ortholinear keyboards, but can be made to work with others. All keycodes less than `0xFF` get blocked, so you won't type while playing notes - if you have special keys/mods, those will still work. A work-around for this is to jump to a different layer with KC_NOs before (or after) enabling music mode.
+
+Recording is experimental due to some memory issues - if you experience some weird behavior, unplugging/replugging your keyboard will fix things.
+
+Keycodes available:
+
+* `MU_ON` - Turn music mode on
+* `MU_OFF` - Turn music mode off
+* `MU_TOG` - Toggle music mode
+* `MU_MOD` - Cycle through the music modes:
+  * `CHROMATIC_MODE` - Chromatic scale, row changes the octave
+  * `GUITAR_MODE` - Chromatic scale, but the row changes the string (+5 st)
+  * `VIOLIN_MODE` - Chromatic scale, but the row changes the string (+7 st)
+  * `MAJOR_MODE` - Major scale
+
+In music mode, the following keycodes work differently, and don't pass through:
+
+* `LCTL` - start a recording
+* `LALT` - stop recording/stop playing
+* `LGUI` - play recording
+* `KC_UP` - speed-up playback
+* `KC_DOWN` - slow-down playback
+
+The pitch standard (`PITCH_STANDARD_A`) is 440.0f by default - to change this, add something like this to your `config.h`:
+
+    #define PITCH_STANDARD_A 432.0f
+
+You can completely disable Music Mode as well. This is useful, if you're pressed for space on your controller.  To disable it, add this to your `config.h`:
+
+    #define NO_MUSIC_MODE
+
+### Music Mask
+
+By default, `MUSIC_MASK` is set to `keycode < 0xFF` which means keycodes less than `0xFF` are turned into notes, and don't output anything. You can change this by defining this in your `config.h` like this:
+
+    #define MUSIC_MASK keycode != KC_NO
+
+Which will capture all keycodes - be careful, this will get you stuck in music mode until you restart your keyboard!
+
+For a more advanced way to control which keycodes should still be processed, you can use `music_mask_kb(keycode)` in `<keyboard>.c` and `music_mask_user(keycode)` in your `keymap.c`:
+
+    bool music_mask_user(uint16_t keycode) {
+      switch (keycode) {
+        case RAISE:
+        case LOWER:
+          return false;
+        default:
+          return true;
+      }
+    }
+
+Things that return false are not part of the mask, and are always processed.
+
+### Music Map
+
+By default, the Music Mode uses the columns and row to determine the scale for the keys. For a board that uses a rectangular matrix that matches the keyboard layout, this is just fine.  However, for boards that use a more complicated matrix (such as the Planck Rev6, or many split keyboards) this would result in a very skewed experience.  
+
+However, the Music Map option allows you to remap the scaling for the music mode, so it fits the layout, and is more natural. 
+
+To enable this feature, add `#define MUSIC_MAP` to your `config.h` file, and then you will want to add a `uint8_t music_map` to your keyboard's `c` file, or your `keymap.c`.
+
+```c
+const uint8_t music_map[MATRIX_ROWS][MATRIX_COLS] = LAYOUT_ortho_4x12(
+	36, 37, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47,
+	24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35,
+	12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23,
+	 0,  1,  2,  3,  4,  5,  6,  7,  8,  9, 10, 11
+);
+```
+
+You will want to use whichever `LAYOUT` macro that your keyboard uses here.  This maps it to the correct key location.  Start in  the bottom left of the keyboard layout, and  move to the right, and then upwards.  Fill in all the entries until you have a complete matrix.  
+
+You can look at the [Planck Keyboard](https://github.com/qmk/qmk_firmware/blob/e9ace1487887c1f8b4a7e8e6d87c322988bec9ce/keyboards/planck/planck.c#L24-L29) as an example of how to implement this. 
+
+## Audio Click
+
+This adds a click sound each time you hit a button, to simulate click sounds from the keyboard. And the sounds are slightly different for each keypress, so it doesn't sound like a single long note, if you type rapidly. 
+
+* `CK_TOGG` - Toggles the status (will play sound if enabled)
+* `CK_ON` - Turns on Audio Click (plays sound)
+* `CK_OFF` - Turns off Audio Click (doesn't play sound)
+* `CK_RST` - Resets the frequency to the default state (plays sound at default frequency)
+* `CK_UP` - Increases the frequency of the clicks (plays sound at new frequency)
+* `CK_DOWN` - Decreases the frequency of the clicks (plays sound at new frequency)
+
+
+The feature is disabled by default, to save space.  To enable it, add this to your `config.h`:
+
+    #define AUDIO_CLICKY
+
+
+You can configure the default, min and max frequencies, the stepping and built in randomness by defining these values: 
+
+| Option | Default Value | Description |
+|--------|---------------|-------------|
+| `AUDIO_CLICKY_FREQ_DEFAULT` | 440.0f | Sets the default/starting audio frequency for the clicky sounds. |
+| `AUDIO_CLICKY_FREQ_MIN` | 65.0f | Sets the lowest frequency (under 60f are a bit buggy). |
+| `AUDIO_CLICKY_FREQ_MAX` | 1500.0f | Sets the the highest frequency. Too high may result in coworkers attacking you. |
+| `AUDIO_CLICKY_FREQ_FACTOR` | 1.18921f| Sets the stepping of UP/DOWN key codes.  This is a multiplicative factor.  The default steps the frequency up/down by a musical minor third.  |
+| `AUDIO_CLICKY_FREQ_RANDOMNESS`     |  0.05f |  Sets a factor of randomness for the clicks, Setting this to `0f` will make each click identical, and `1.0f` will make this sound much like the 90's computer screen scrolling/typing effect. | 
+| `AUDIO_CLICKY_DELAY_DURATION` | 1 | An integer note duration where 1 is 1/16th of the tempo, or a sixty-fourth note (see `quantum/audio/musical_notes.h` for implementation details). The main clicky effect will be delayed by this duration.  Adjusting this to values around 6-12 will help compensate for loud switches. |
+
+
+
+
+## MIDI Functionality
+
+This is still a WIP, but check out `quantum/process_keycode/process_midi.c` to see what's happening. Enable from the Makefile.
+
+
+## Audio Keycodes
+
+|Key             |Aliases  |Description                       |
+|----------------|---------|----------------------------------|
+|`AU_ON`         |         |Audio mode on                     |
+|`AU_OFF`        |         |Audio mode off                    |
+|`AU_TOG`        |         |Toggles Audio mode                |
+|`CLICKY_TOGGLE` |`CK_TOGG`|Toggles Audio clicky mode         |
+|`CLICKY_UP`     |`CK_UP`  |Increases frequency of the clicks |
+|`CLICKY_DOWN`   |`CK_DOWN`|Decreases frequency of the clicks |
+|`CLICKY_RESET`  |`CK_RST` |Resets frequency to default       |
+|`MU_ON`         |         |Turns on Music Mode               |
+|`MU_OFF`        |         |Turns off Music Mode              |
+|`MU_TOG`        |         |Toggles Music Mode                |
+|`MU_MOD`        |         |Cycles through the music modes    |
+
+<!-- FIXME: this formatting needs work
+
+## Audio
+
+```c
+#ifdef AUDIO_ENABLE
+    AU_ON,
+    AU_OFF,
+    AU_TOG,
+
+    #ifdef FAUXCLICKY_ENABLE
+        FC_ON,
+        FC_OFF,
+        FC_TOG,
+    #endif
+
+    // Music mode on/off/toggle
+    MU_ON,
+    MU_OFF,
+    MU_TOG,
+
+    // Music voice iterate
+    MUV_IN,
+    MUV_DE,
+#endif
+```
+
+### Midi
+
+#if !MIDI_ENABLE_STRICT || (defined(MIDI_ENABLE) && defined(MIDI_BASIC))
+    MI_ON,  // send midi notes when music mode is enabled
+    MI_OFF, // don't send midi notes when music mode is enabled
+#endif
+
+MIDI_TONE_MIN,
+MIDI_TONE_MAX
+
+MI_C = MIDI_TONE_MIN,
+MI_Cs,
+MI_Db = MI_Cs,
+MI_D,
+MI_Ds,
+MI_Eb = MI_Ds,
+MI_E,
+MI_F,
+MI_Fs,
+MI_Gb = MI_Fs,
+MI_G,
+MI_Gs,
+MI_Ab = MI_Gs,
+MI_A,
+MI_As,
+MI_Bb = MI_As,
+MI_B,
+
+MIDI_TONE_KEYCODE_OCTAVES > 1
+
+where x = 1-5:
+MI_C_x,
+MI_Cs_x,
+MI_Db_x = MI_Cs_x,
+MI_D_x,
+MI_Ds_x,
+MI_Eb_x = MI_Ds_x,
+MI_E_x,
+MI_F_x,
+MI_Fs_x,
+MI_Gb_x = MI_Fs_x,
+MI_G_x,
+MI_Gs_x,
+MI_Ab_x = MI_Gs_x,
+MI_A_x,
+MI_As_x,
+MI_Bb_x = MI_As_x,
+MI_B_x,
+
+MI_OCT_Nx 1-2
+MI_OCT_x 0-7
+MIDI_OCTAVE_MIN = MI_OCT_N2,
+MIDI_OCTAVE_MAX = MI_OCT_7,
+MI_OCTD, // octave down
+MI_OCTU, // octave up
+
+MI_TRNS_Nx 1-6
+MI_TRNS_x 0-6
+MIDI_TRANSPOSE_MIN = MI_TRNS_N6,
+MIDI_TRANSPOSE_MAX = MI_TRNS_6,
+MI_TRNSD, // transpose down
+MI_TRNSU, // transpose up
+
+MI_VEL_x 1-10
+MIDI_VELOCITY_MIN = MI_VEL_1,
+MIDI_VELOCITY_MAX = MI_VEL_9,
+MI_VELD, // velocity down
+MI_VELU, // velocity up
+
+MI_CHx 1-16
+MIDI_CHANNEL_MIN = MI_CH1
+MIDI_CHANNEL_MAX = MI_CH16,
+MI_CHD, // previous channel
+MI_CHU, // next channel
+
+MI_ALLOFF, // all notes off
+
+MI_SUS, // sustain
+MI_PORT, // portamento
+MI_SOST, // sostenuto
+MI_SOFT, // soft pedal
+MI_LEG,  // legato
+
+MI_MOD, // modulation
+MI_MODSD, // decrease modulation speed
+MI_MODSU, // increase modulation speed
+#endif // MIDI_ADVANCED
+
+-->

docs/feature_auto_shift.md

@@ -0,0 +1,167 @@
+# Auto Shift: Why Do We Need a Shift Key?
+
+Tap a key and you get its character. Tap a key, but hold it *slightly* longer
+and you get its shifted state. Voilà! No shift key needed!
+
+## Why Auto Shift?
+
+Many people suffer from various forms of RSI. A common cause is stretching your
+fingers repetitively long distances. For us on the keyboard, the pinky does that
+all too often when reaching for the shift key. Auto Shift looks to alleviate that
+problem.
+
+## How Does It Work?
+
+When you tap a key, it stays depressed for a short period of time before it is
+then released. This depressed time is a different length for everyone. Auto Shift
+defines a constant `AUTO_SHIFT_TIMEOUT` which is typically set to twice your
+normal pressed state time. When you press a key, a timer starts and then stops
+when you release the key. If the time depressed is greater than or equal to the
+`AUTO_SHIFT_TIMEOUT`, then a shifted version of the key is emitted. If the time
+is less than the `AUTO_SHIFT_TIMEOUT` time, then the normal state is emitted.
+
+## Are There Limitations to Auto Shift?
+
+Yes, unfortunately.
+
+1. Key repeat will cease to work. For example, before if you wanted 20 'a'
+   characters, you could press and hold the 'a' key for a second or two. This no
+   longer works with Auto Shift because it is timing your depressed time instead
+   of emitting a depressed key state to your operating system.
+2. You will have characters that are shifted when you did not intend on shifting, and
+   other characters you wanted shifted, but were not. This simply comes down to
+   practice. As we get in a hurry, we think we have hit the key long enough
+   for a shifted version, but we did not. On the other hand, we may think we are
+   tapping the keys, but really we have held it for a little longer than
+   anticipated.
+
+## How Do I Enable Auto Shift?
+
+Add to your `rules.mk` in the keymap folder:
+
+    AUTO_SHIFT_ENABLE = yes
+
+If no `rules.mk` exists, you can create one.
+
+Then compile and install your new firmware with Auto Key enabled! That's it!
+
+## Modifiers
+
+By default, Auto Shift is disabled for any key press that is accompanied by one or more
+modifiers. Thus, Ctrl+A that you hold for a really long time is not the same
+as Ctrl+Shift+A.
+
+You can re-enable Auto Shift for modifiers by adding another rule to your `rules.mk`
+
+    AUTO_SHIFT_MODIFIERS = yes
+
+In which case, Ctrl+A held past the `AUTO_SHIFT_TIMEOUT` will be sent as Ctrl+Shift+A
+
+## Configuring Auto Shift
+
+If desired, there is some configuration that can be done to change the
+behavior of Auto Shift. This is done by setting various variables the
+`config.h` file located in your keymap folder. If no `config.h` file exists, you can create one.
+
+A sample is
+
+    #ifndef CONFIG_USER_H
+    #define CONFIG_USER_H
+
+    #include "../../config.h"
+
+    #define AUTO_SHIFT_TIMEOUT 150
+    #define NO_AUTO_SHIFT_SPECIAL
+
+    #endif
+
+### AUTO_SHIFT_TIMEOUT (Value in ms)
+
+This controls how long you have to hold a key before you get the shifted state.
+Obviously, this is different for everyone. For the common person, a setting of
+135 to 150 works great. However, one should start with a value of at least 175, which
+is the default value. Then work down from there. The idea is to have the shortest time required to get the shifted state without having false positives.
+
+Play with this value until things are perfect. Many find that all will work well
+at a given value, but one or two keys will still emit the shifted state on
+occasion. This is simply due to habit and holding some keys a little longer
+than others. Once you find this value, work on tapping your problem keys a little
+quicker than normal and you will be set.
+
+?> Auto Shift has three special keys that can help you get this value right very quick. See "Auto Shift Setup" for more details!
+
+### NO_AUTO_SHIFT_SPECIAL (simple define)
+
+Do not Auto Shift special keys, which include -\_, =+, [{, ]}, ;:, '", ,<, .>,
+and /?
+
+### NO_AUTO_SHIFT_NUMERIC (simple define)
+
+Do not Auto Shift numeric keys, zero through nine.
+
+### NO_AUTO_SHIFT_ALPHA (simple define)
+
+Do not Auto Shift alpha characters, which include A through Z.
+
+## Using Auto Shift Setup
+
+This will enable you to define three keys temporarily to increase, decrease and report your `AUTO_SHIFT_TIMEOUT`.
+
+### Setup
+
+Map three keys temporarily in your keymap:
+
+| Key Name | Description                                         |
+|----------|-----------------------------------------------------|
+| KC_ASDN  | Lower the Auto Shift timeout variable (down)        |
+| KC_ASUP  | Raise the Auto Shift timeout variable (up)          |
+| KC_ASRP  | Report your current Auto Shift timeout value        |
+| KC_ASON  | Turns on the Auto Shift Function                    |
+| KC_ASOFF | Turns off the Auto Shift Function                   |
+| KC_ASTG  | Toggles the state of the Auto Shift feature         |
+
+Compile and upload your new firmware.
+
+### Use
+
+It is important to note that during these tests, you should be typing
+completely normal and with no intention of shifted keys.
+
+1. Type multiple sentences of alphabetical letters.
+2. Observe any upper case letters.
+3. If there are none, press the key you have mapped to `KC_ASDN` to decrease
+   time Auto Shift timeout value and go back to step 1.
+4. If there are some upper case letters, decide if you need to work on tapping
+   those keys with less down time, or if you need to increase the timeout.
+5. If you decide to increase the timeout, press the key you have mapped to
+   `KC_ASUP` and go back to step 1.
+6. Once you are happy with your results, press the key you have mapped to
+   `KC_ASRP`. The keyboard will type by itself the value of your
+   `AUTO_SHIFT_TIMEOUT`.
+7. Update `AUTO_SHIFT_TIMEOUT` in your `config.h` with the value reported.
+8. Remove `AUTO_SHIFT_SETUP` from your `config.h`.
+9. Remove the key bindings `KC_ASDN`, `KC_ASUP` and `KC_ASRP`.
+10. Compile and upload your new firmware.
+
+#### An Example Run
+
+    hello world. my name is john doe. i am a computer programmer playing with
+    keyboards right now.
+
+    [PRESS KC_ASDN quite a few times]
+
+    heLLo woRLd. mY nAMe is JOHn dOE. i AM A compUTeR proGRaMMER PlAYiNG witH
+    KEYboArDS RiGHT NOw.
+
+    [PRESS KC_ASUP a few times]
+
+    hello world. my name is john Doe. i am a computer programmer playing with
+    keyboarDs right now.
+
+    [PRESS KC_ASRP]
+
+    115
+
+The keyboard typed `115` which represents your current `AUTO_SHIFT_TIMEOUT`
+value. You are now set! Practice on the *D* key a little bit that showed up
+in the testing and you'll be golden.

docs/feature_backlight.md

@@ -0,0 +1,159 @@
+# Backlighting
+
+Many keyboards support backlit keys by way of individual LEDs placed through or underneath the keyswitches. This feature is distinct from both the [RGB underglow](feature_rgblight.md) and [RGB matrix](feature_rgb_matrix.md) features as it usually allows for only a single colour per switch, though you can obviously install multiple different single coloured LEDs on a keyboard.
+
+QMK is able to control the brightness of these LEDs by switching them on and off rapidly in a certain ratio, a technique known as *Pulse Width Modulation*, or PWM. By altering the duty cycle of the PWM signal, it creates the illusion of dimming.
+
+The MCU can only supply so much current to its GPIO pins. Instead of powering the backlight directly from the MCU, the backlight pin is connected to a transistor or MOSFET that switches the power to the LEDs.
+
+## Usage
+
+Most keyboards have backlighting enabled by default if they support it, but if it is not working for you, check that your `rules.mk` includes the following:
+
+```make
+BACKLIGHT_ENABLE = yes
+```
+
+## Keycodes
+Once enabled the following keycodes below can be used to change the backlight level.
+
+|Key      |Description                               |
+|---------|------------------------------------------|
+|`BL_TOGG`|Turn the backlight on or off              |
+|`BL_STEP`|Cycle through backlight levels            |
+|`BL_ON`  |Set the backlight to max brightness       |
+|`BL_OFF` |Turn the backlight off                    |
+|`BL_INC` |Increase the backlight level              |
+|`BL_DEC` |Decrease the backlight level              |
+|`BL_BRTG`|Toggle backlight breathing                |
+
+## AVR driver
+
+### Caveats
+
+Hardware PWM is supported according to the following table:
+
+|Backlight Pin|AT90USB64/128|ATmega16/32U4|ATmega16/32U2|ATmega32A|ATmega328P|
+|-------------|-------------|-------------|-------------|---------|----------|
+|`B1`         |             |             |             |         |Timer 1   |
+|`B2`         |             |             |             |         |Timer 1   |
+|`B5`         |Timer 1      |Timer 1      |             |         |          |
+|`B6`         |Timer 1      |Timer 1      |             |         |          |
+|`B7`         |Timer 1      |Timer 1      |Timer 1      |         |          |
+|`C4`         |Timer 3      |             |             |         |          |
+|`C5`         |Timer 3      |             |Timer 1      |         |          |
+|`C6`         |Timer 3      |Timer 3      |Timer 1      |         |          |
+|`D4`         |             |             |             |Timer 1  |          |
+|`D5`         |             |             |             |Timer 1  |          |
+
+All other pins will use software PWM. If the [Audio](feature_audio.md) feature is disabled or only using one timer, the backlight PWM can be triggered by a hardware timer:
+
+|Audio Pin|Audio Timer|Software PWM Timer|
+|---------|-----------|------------------|
+|`C4`     |Timer 3    |Timer 1           |
+|`C5`     |Timer 3    |Timer 1           |
+|`C6`     |Timer 3    |Timer 1           |
+|`B5`     |Timer 1    |Timer 3           |
+|`B6`     |Timer 1    |Timer 3           |
+|`B7`     |Timer 1    |Timer 3           |
+
+When both timers are in use for Audio, the backlight PWM will not use a hardware timer, but will instead be triggered during the matrix scan. In this case, breathing is not supported, and the backlight might flicker, because the PWM computation may not be called with enough timing precision.
+
+### AVR Configuration
+
+To change the behavior of the backlighting, `#define` these in your `config.h`:
+
+|Define               |Default      |Description                                                                                                  |
+|---------------------|-------------|-------------------------------------------------------------------------------------------------------------|
+|`BACKLIGHT_PIN`      |`B7`         |The pin that controls the LEDs. Unless you are designing your own keyboard, you shouldn't need to change this|
+|`BACKLIGHT_PINS`     |*Not defined*|experimental: see below for more information                                                                 |
+|`BACKLIGHT_LEVELS`   |`3`          |The number of brightness levels (maximum 31 excluding off)                                                   |
+|`BACKLIGHT_CAPS_LOCK`|*Not defined*|Enable Caps Lock indicator using backlight (for keyboards without dedicated LED)                             |
+|`BACKLIGHT_BREATHING`|*Not defined*|Enable backlight breathing, if supported                                                                     |
+|`BREATHING_PERIOD`   |`6`          |The length of one backlight "breath" in seconds                                                              |
+|`BACKLIGHT_ON_STATE` |`0`          |The state of the backlight pin when the backlight is "on" - `1` for high, `0` for low                        |
+
+### Backlight On State
+
+Most backlight circuits are driven by an N-channel MOSFET or NPN transistor. This means that to turn the transistor *on* and light the LEDs, you must drive the backlight pin, connected to the gate or base, *high*.
+Sometimes, however, a P-channel MOSFET, or a PNP transistor is used. In this case, when the transistor is on, the pin is driven *low* instead.
+
+This functionality is configured at the keyboard level with the `BACKLIGHT_ON_STATE` define.
+
+### Multiple backlight pins
+
+Most keyboards have only one backlight pin which control all backlight LEDs (especially if the backlight is connected to an hardware PWM pin).
+In software PWM, it is possible to define multiple backlight pins. All those pins will be turned on and off at the same time during the PWM duty cycle.
+This feature allows to set for instance the Caps Lock LED (or any other controllable LED) brightness at the same level as the other LEDs of the backlight. This is useful if you have mapped LCTRL in place of Caps Lock and you need the Caps Lock LED to be part of the backlight instead of being activated when Caps Lock is on.
+
+To activate multiple backlight pins, you need to add something like this to your user `config.h`:
+
+```c
+#define BACKLIGHT_LED_COUNT 2
+#undef BACKLIGHT_PIN
+#define BACKLIGHT_PINS { F5, B2 }
+```
+
+### Hardware PWM Implementation
+
+When using the supported pins for backlighting, QMK will use a hardware timer configured to output a PWM signal. This timer will count up to `ICRx` (by default `0xFFFF`) before resetting to 0.
+The desired brightness is calculated and stored in the `OCRxx` register. When the counter reaches this value, the backlight pin will go low, and is pulled high again when the counter resets.
+In this way `OCRxx` essentially controls the duty cycle of the LEDs, and thus the brightness, where `0x0000` is completely off and `0xFFFF` is completely on.
+
+The breathing effect is achieved by registering an interrupt handler for `TIMER1_OVF_vect` that is called whenever the counter resets, roughly 244 times per second.
+In this handler, the value of an incrementing counter is mapped onto a precomputed brightness curve. To turn off breathing, the interrupt handler is simply disabled, and the brightness reset to the level stored in EEPROM.
+
+### Software PWM Implementation
+
+When `BACKLIGHT_PIN` is not set to a hardware backlight pin, QMK will use a hardware timer configured to trigger software interrupts. This time will count up to `ICRx` (by default `0xFFFF`) before resetting to 0.
+When resetting to 0, the CPU will fire an OVF (overflow) interrupt that will turn the LEDs on, starting the duty cycle.
+The desired brightness is calculated and stored in the `OCRxx` register. When the counter reaches this value, the CPU will fire a Compare Output match interrupt, which will turn the LEDs off.
+In this way `OCRxx` essentially controls the duty cycle of the LEDs, and thus the brightness, where `0x0000` is completely off and `0xFFFF` is completely on.
+
+The breathing effect is the same as in the hardware PWM implementation.
+
+## ARM Driver
+
+### Caveats
+
+Currently only hardware PWM is supported, and does not provide automatic configuration.
+
+?> STMF072 support is being investigated.
+
+### ARM Configuration
+
+To change the behavior of the backlighting, `#define` these in your `config.h`:
+
+|Define                  |Default      |Description                                                                                                  |
+|------------------------|-------------|-------------------------------------------------------------------------------------------------------------|
+|`BACKLIGHT_PIN`         |`B7`         |The pin that controls the LEDs. Unless you are designing your own keyboard, you shouldn't need to change this|
+|`BACKLIGHT_PWM_DRIVER`  |`PWMD4`      |The PWM driver to use, see ST datasheets for pin to PWM timer mapping. Unless you are designing your own keyboard, you shouldn't need to change this|
+|`BACKLIGHT_PWM_CHANNEL` |`3`          |The PWM channel to use, see ST datasheets for pin to PWM channel mapping. Unless you are designing your own keyboard, you shouldn't need to change this|
+|`BACKLIGHT_PAL_MODE`    |`2`          |The pin alternative function to use, see ST datasheets for pin AF mapping. Unless you are designing your own keyboard, you shouldn't need to change this|
+|`BACKLIGHT_LEVELS`      |`3`          |The number of brightness levels (maximum 31 excluding off)                                                   |
+|`BACKLIGHT_CAPS_LOCK`   |*Not defined*|Enable Caps Lock indicator using backlight (for keyboards without dedicated LED)                             |
+|`BACKLIGHT_BREATHING`   |*Not defined*|Enable backlight breathing, if supported                                                                     |
+|`BREATHING_PERIOD`      |`6`          |The length of one backlight "breath" in seconds                                                              |
+
+## Backlight Functions
+
+|Function  |Description                                                |
+|----------|-----------------------------------------------------------|
+|`backlight_toggle()`    |Turn the backlight on or off                 |
+|`backlight_enable()`    |Turn the backlight on                        |
+|`backlight_disable()`   |Turn the backlight off                       |
+|`backlight_step()`      |Cycle through backlight levels               |
+|`backlight_increase()`  |Increase the backlight level                 |
+|`backlight_decrease()`  |Decrease the backlight level                 |
+|`backlight_level(x)`    |Sets the backlight level, from 0 to          |
+|                        |`BACKLIGHT_LEVELS`                           |
+|`get_backlight_level()` |Return the current backlight level           |
+|`is_backlight_enabled()`|Return whether the backlight is currently on |
+
+### Backlight Breathing Functions
+
+|Function  |Description                                               |
+|----------|----------------------------------------------------------|
+|`breathing_toggle()`  |Turn the backlight breathing on or off        |
+|`breathing_enable()`  |Turns on backlight breathing                  |
+|`breathing_disable()` |Turns off backlight breathing                 |

docs/feature_bluetooth.md

@@ -0,0 +1,47 @@
+# Bluetooth
+
+## Bluetooth Known Supported Hardware
+
+Currently Bluetooth support is limited to AVR based chips. For Bluetooth 2.1 Qmk has support for RN-42 HID Firmware and Bluefruit EZ Key the later of which is not produced anymore. For more recent BLE protocols currently only the Adafruit Bluefruit SPI friend is directly supported. BLE is needed to connect to iOS devices. Note iOS does not support Mouse Input.
+
+|Board                                                           |Bluetooth Protocol          |Connection Type |Rules.mk                   |Bluetooth Chip|
+|----------------------------------------------------------------|----------------------------|----------------|---------------------------|--------------|
+|[Adafruit EzKey HID]("https://www.adafruit.com/product/1535")   |Bluetooth Classic           | UART           | BLUETOOTH = AdafruitEZKey |              |
+|Rover Networks RN-42 (Sparkfun Bluesmirf)                       |Bluetooth Classic           | UART           | BLUETOOTH = RN42          | RN-42        |
+|[Bluefruit LE SPI Friend](https://www.adafruit.com/product/2633)|Bluetooth Low Energy        | SPI            | BLUETOOTH = AdafruitBLE   | nRF5182      |
+
+Not Supported Yet but possible:
+* [Bluefruit LE UART Friend](https://www.adafruit.com/product/2479). [Possible tmk implementation found in](https://github.com/tmk/tmk_keyboard/issues/514)
+* HC-05 boards flashed with RN-42 firmware. They apparently both use the CSR BC417 Chip. Flashing it with RN-42 firmware gives it HID capability.
+* [Sparkfun Bluetooth mate](https://www.sparkfun.com/products/14839)
+* HM-13 based boards
+
+### Adafruit BLE SPI Friend
+Currently The only bluetooth chipset supported by QMK is the Adafruit Bluefruit SPI Friend. It's a Nordic nRF5182 based chip running Adafruit's custom firmware. Data is transmitted via Adafruit's SDEP over Hardware SPI. The [Feather 32u4 Bluefruit LE](https://www.adafruit.com/product/2829) is supported as it's an AVR mcu connected via SPI to the Nordic BLE chip with Adafruit firmware. If Building a custom board with the SPI friend it would be easiest to just use the pin selection that the 32u4 feather uses but you can change the pins in the config.h options with the following defines:
+* #define AdafruitBleResetPin D4
+* #define AdafruitBleCSPin    B4
+* #define AdafruitBleIRQPin   E6
+
+A Bluefruit UART friend can be converted to an SPI friend, however this [requires](https://github.com/qmk/qmk_firmware/issues/2274) some reflashing and soldering directly to the MDBT40 chip.
+
+## Adafruit EZ-Key hid
+This requires [some hardware changes](https://www.reddit.com/r/MechanicalKeyboards/comments/3psx0q/the_planck_keyboard_with_bluetooth_guide_and/?ref=search_posts), but can be enabled via the Makefile. The firmware will still output characters via USB, so be aware of this when charging via a computer. It would make sense to have a switch on the Bluefruit to turn it off at will.
+
+
+<!-- FIXME: Document bluetooth support more completely. -->
+## Bluetooth Rules.mk Options
+Use only one of these
+* BLUETOOTH_ENABLE = yes (Legacy Option)
+* BLUETOOTH = RN42
+* BLUETOOTH = AdafruitEZKey
+* BLUETOOTH = AdafruitBLE
+
+## Bluetooth Keycodes
+
+This is used when multiple keyboard outputs can be selected. Currently this only allows for switching between USB and Bluetooth on keyboards that support both.
+
+|Name      |Description                                   |
+|----------|----------------------------------------------|
+|`OUT_AUTO`|Automatically switch between USB and Bluetooth|
+|`OUT_USB` |USB only                                      |
+|`OUT_BT`  |Bluetooth only                                |

docs/feature_bootmagic.md

@@ -0,0 +1,166 @@
+# Bootmagic
+
+There are three separate but related features that allow you to change the behavior of your keyboard without reflashing. While each of them have similar functionality, it is accessed in different ways depending on how your keyboard is configured.
+
+**Bootmagic** is a system for configuring your keyboard while it initializes. To trigger a Bootmagic command, hold down the Bootmagic key and one or more command keys.
+
+**Bootmagic Keycodes** are prefixed with `MAGIC_`, and allow you to access the Bootmagic functionality *after* your keyboard has initialized. To use the keycodes, assign them to your keymap as you would any other keycode.
+
+**Command**, formerly known as **Magic**, is another feature that allows you to control different aspects of your keyboard. While it shares some functionality with Bootmagic, it also allows you to do things that Bootmagic does not, such as printing version information to the console. For more information, see [Command](feature_command.md).
+
+On some keyboards Bootmagic is disabled by default. If this is the case, it must be explicitly enabled in your `rules.mk` with:
+
+```make
+BOOTMAGIC_ENABLE = full
+```
+
+?> You may see `yes` being used in place of `full`, and this is okay. However, `yes` is deprecated, and ideally `full` (or `lite`) should be used instead.
+
+Additionally, you can use [Bootmagic Lite](#bootmagic-lite) (a scaled down, very basic version of Bootmagic) by adding the following to your `rules.mk` file:
+
+```make
+BOOTMAGIC_ENABLE = lite
+```
+
+## Hotkeys
+
+Hold down the Bootmagic key (Space by default) and the desired hotkey while plugging in your keyboard. For example, holding Space+`B` should cause it to enter the bootloader.
+
+|Hotkey            |Description                                  |
+|------------------|---------------------------------------------|
+|Escape            |Ignore Bootmagic configuration in EEPROM     |
+|`B`               |Enter the bootloader                         |
+|`D`               |Toggle debugging over serial                 |
+|`X`               |Toggle key matrix debugging                  |
+|`K`               |Toggle keyboard debugging                    |
+|`M`               |Toggle mouse debugging                       |
+|`L`               |Set "Left Hand" for EE_HANDS handedness      |
+|`R`               |Set "Right Hand" for EE_HANDS handedness     |
+|Backspace         |Clear the EEPROM                             |
+|Caps Lock         |Toggle treating Caps Lock as Left Control    |
+|Left Control      |Toggle swapping Caps Lock and Left Control   |
+|Left Alt          |Toggle swapping Left Alt and Left GUI        |
+|Right Alt         |Toggle swapping Right Alt and Right GUI      |
+|Left GUI          |Toggle the GUI keys (useful when gaming)     |
+|<code>&#96;</code>|Toggle swapping <code>&#96;</code> and Escape|
+|`\`               |Toggle swapping `\` and Backspace            |
+|`N`               |Toggle N-Key Rollover (NKRO)                 |
+|`0`               |Make layer 0 the default layer               |
+|`1`               |Make layer 1 the default layer               |
+|`2`               |Make layer 2 the default layer               |
+|`3`               |Make layer 3 the default layer               |
+|`4`               |Make layer 4 the default layer               |
+|`5`               |Make layer 5 the default layer               |
+|`6`               |Make layer 6 the default layer               |
+|`7`               |Make layer 7 the default layer               |
+
+## Keycodes
+
+|Keycode                           |Aliases  |Description                               |
+|----------------------------------|---------|------------------------------------------|
+|`MAGIC_CAPSLOCK_TO_CONTROL`       |         |Treat Caps Lock as Left Control           |
+|`MAGIC_UNCAPSLOCK_TO_CONTROL`     |         |Stop treating Caps Lock as Left Control   |
+|`MAGIC_HOST_NKRO`                 |         |Force N-Key Rollover (NKRO) on            |
+|`MAGIC_UNHOST_NKRO`               |         |Force NKRO off                            |
+|`MAGIC_TOGGLE_NKRO`               |         |Turn NKRO on or off                       |
+|`MAGIC_NO_GUI`                    |         |Disable the GUI keys (useful when gaming) |
+|`MAGIC_UNNO_GUI`                  |         |Enable the GUI keys                       |
+|`MAGIC_SWAP_ALT_GUI`              |`AG_SWAP`|Swap Alt and GUI on both sides (for macOS)|
+|`MAGIC_UNSWAP_ALT_GUI`            |`AG_NORM`|Unswap Alt and GUI                        |
+|`MAGIC_TOGGLE_ALT_GUI`            |`AG_TOGG`|Toggle Alt and GUI swap                   |
+|`MAGIC_SWAP_CTL_GUI`              |`CG_SWAP`|Swap Ctrl and GUI on both sides (for macOS)|
+|`MAGIC_UNSWAP_CTL_GUI`            |`CG_NORM`|Unswap Ctrl and GUI                       |
+|`MAGIC_TOGGLE_CTL_GUI`            |`CG_TOGG`|Toggle Ctrl and GUI swap                  |
+|`MAGIC_SWAP_BACKSLASH_BACKSPACE`  |         |Swap `\` and Backspace                    |
+|`MAGIC_UNSWAP_BACKSLASH_BACKSPACE`|         |Unswap `\` and Backspace                  |
+|`MAGIC_SWAP_CONTROL_CAPSLOCK`     |         |Swap Left Control and Caps Lock           |
+|`MAGIC_UNSWAP_CONTROL_CAPSLOCK`   |         |Unswap Left Control and Caps Lock         |
+|`MAGIC_SWAP_GRAVE_ESC`            |         |Swap <code>&#96;</code> and Escape        |
+|`MAGIC_UNSWAP_GRAVE_ESC`          |         |Unswap <code>&#96;</code> and Escape      |
+|`MAGIC_SWAP_LALT_LGUI`            |         |Swap Left Alt and Left GUI                |
+|`MAGIC_UNSWAP_LALT_LGUI`          |         |Unswap Left Alt and Left GUI              |
+|`MAGIC_SWAP_RALT_RGUI`            |         |Swap Right Alt and Right GUI              |
+|`MAGIC_UNSWAP_RALT_RGUI`          |         |Unswap Right Alt and Right GUI            |
+|`MAGIC_SWAP_LCTL_LGUI`            |         |Swap Left Control and Left GUI            |
+|`MAGIC_UNSWAP_LCTL_LGUI`          |         |Unswap Left Control and Left GUI          |
+|`MAGIC_SWAP_RCTL_RGUI`            |         |Swap Right Control and Right GUI          |
+|`MAGIC_UNSWAP_RCTL_RGUI`          |         |Unswap Right Control and Right GUI        |
+|`MAGIC_EE_HANDS_LEFT`             |         |Set "Left Hand" for EE_HANDS handedness   |
+|`MAGIC_EE_HANDS_RIGHT`            |         |Set "Right Hand" for EE_HANDS handedness  |
+
+## Configuration
+
+If you would like to change the hotkey assignments for Bootmagic, `#define` these in your `config.h` at either the keyboard or keymap level.
+
+|Define                                  |Default      |Description                                        |
+|----------------------------------------|-------------|---------------------------------------------------|
+|`BOOTMAGIC_KEY_SALT`                    |`KC_SPACE`   |The Bootmagic key                                  |
+|`BOOTMAGIC_KEY_SKIP`                    |`KC_ESC`     |Ignore Bootmagic configuration in EEPROM           |
+|`BOOTMAGIC_KEY_EEPROM_CLEAR`            |`KC_BSPACE`  |Clear the EEPROM configuration                     |
+|`BOOTMAGIC_KEY_BOOTLOADER`              |`KC_B`       |Enter the bootloader                               |
+|`BOOTMAGIC_KEY_DEBUG_ENABLE`            |`KC_D`       |Toggle debugging over serial                       |
+|`BOOTMAGIC_KEY_DEBUG_MATRIX`            |`KC_X`       |Toggle matrix debugging                            |
+|`BOOTMAGIC_KEY_DEBUG_KEYBOARD`          |`KC_K`       |Toggle keyboard debugging                          |
+|`BOOTMAGIC_KEY_DEBUG_MOUSE`             |`KC_M`       |Toggle mouse debugging                             |
+|`BOOTMAGIC_KEY_EE_HANDS_LEFT`           |`KC_L`       |Set "Left Hand" for EE_HANDS handedness            |
+|`BOOTMAGIC_KEY_EE_HANDS_RIGHT`          |`KC_R`       |Set "Right Hand" for EE_HANDS handedness           |
+|`BOOTMAGIC_KEY_SWAP_CONTROL_CAPSLOCK`   |`KC_LCTRL`   |Swap Left Control and Caps Lock                    |
+|`BOOTMAGIC_KEY_CAPSLOCK_TO_CONTROL`     |`KC_CAPSLOCK`|Toggle treating Caps Lock as Left Control          |
+|`BOOTMAGIC_KEY_SWAP_LALT_LGUI`          |`KC_LALT`    |Toggle swapping Left Alt and Left GUI (for macOS)  |
+|`BOOTMAGIC_KEY_SWAP_RALT_RGUI`          |`KC_RALT`    |Toggle swapping Right Alt and Right GUI (for macOS)|
+|`BOOTMAGIC_KEY_NO_GUI`                  |`KC_LGUI`    |Toggle the GUI keys (useful when gaming)           |
+|`BOOTMAGIC_KEY_SWAP_GRAVE_ESC`          |`KC_GRAVE`   |Toggle swapping <code>&#96;</code> and Escape      |
+|`BOOTMAGIC_KEY_SWAP_BACKSLASH_BACKSPACE`|`KC_BSLASH`  |Toggle swapping `\` and Backspace                  |
+|`BOOTMAGIC_HOST_NKRO`                   |`KC_N`       |Toggle N-Key Rollover (NKRO)                       |
+|`BOOTMAGIC_KEY_DEFAULT_LAYER_0`         |`KC_0`       |Make layer 0 the default layer                     |
+|`BOOTMAGIC_KEY_DEFAULT_LAYER_1`         |`KC_1`       |Make layer 1 the default layer                     |
+|`BOOTMAGIC_KEY_DEFAULT_LAYER_2`         |`KC_2`       |Make layer 2 the default layer                     |
+|`BOOTMAGIC_KEY_DEFAULT_LAYER_3`         |`KC_3`       |Make layer 3 the default layer                     |
+|`BOOTMAGIC_KEY_DEFAULT_LAYER_4`         |`KC_4`       |Make layer 4 the default layer                     |
+|`BOOTMAGIC_KEY_DEFAULT_LAYER_5`         |`KC_5`       |Make layer 5 the default layer                     |
+|`BOOTMAGIC_KEY_DEFAULT_LAYER_6`         |`KC_6`       |Make layer 6 the default layer                     |
+|`BOOTMAGIC_KEY_DEFAULT_LAYER_7`         |`KC_7`       |Make layer 7 the default layer                     |
+
+# Bootmagic Lite
+
+In addition to the full blown Bootmagic feature, is the Bootmagic Lite feature that only handles jumping into the bootloader.  This is great for boards that don't have a physical reset button but you need a way to jump into the bootloader, and don't want to deal with the headache that Bootmagic can cause.
+
+To enable this version of Bootmagic, you need to enable it in your `rules.mk` with:
+
+```make
+BOOTMAGIC_ENABLE = lite
+```
+
+Additionally, you may want to specify which key to use.  This is especially useful for keyboards that have unusual matrices.  To do so, you need to specify the row and column of the key that you want to use. Add these entries to your `config.h` file:
+
+```c
+#define BOOTMAGIC_LITE_ROW 0
+#define BOOTMAGIC_LITE_COLUMN 1
+```
+
+By default, these are set to 0 and 0, which is usually the "ESC" key on a majority of keyboards.
+
+And to trigger the bootloader, you hold this key down when plugging the keyboard in. Just the single key.
+
+!> Using bootmagic lite will **always reset** the EEPROM, so you will lose any settings that have been saved.
+
+## Advanced Bootmagic Lite
+
+The `bootmagic_lite` function is defined weakly, so that you can replace this in your code, if you need.  A great example of this is the Zeal60 boards that have some additional handling needed.
+
+To replace the function, all you need to do is add something like this to your code:
+
+```c
+void bootmagic_lite(void) {
+    matrix_scan();
+    wait_ms(DEBOUNCE * 2);
+    matrix_scan();
+
+    if (matrix_get_row(BOOTMAGIC_LITE_ROW) & (1 << BOOTMAGIC_LITE_COLUMN)) {
+      // Jump to bootloader.
+      bootloader_jump();
+    }
+}
+```
+
+You can additional feature here. For instance, resetting the eeprom or requiring additional keys to be pressed to trigger bootmagic.  Keep in mind that `bootmagic_lite` is called before a majority of features are initialized in the firmware.

docs/feature_combo.md

@@ -0,0 +1,103 @@
+# Combos
+
+The Combo feature is a chording type solution for adding custom actions.  It lets you hit multiple keys at once and produce a different effect.  For instance, hitting `A` and `S` within the tapping term would hit `ESC` instead, or have it perform even more complex tasks.
+
+To enable this feature, you need to add `COMBO_ENABLE = yes` to your `rules.mk`.
+
+Additionally, in your `config.h`, you'll need to specify the number of combos that you'll be using, by adding `#define COMBO_COUNT 1` (replacing 1 with the number that you're using).
+<!-- At this time, this is necessary -->
+
+Also, by default, the tapping term for the Combos is set to the same value as `TAPPING_TERM` (200 by default on most boards). But you can specify a different value by defining it in your `config.h`.  For instance: `#define COMBO_TERM 300` would set the time out period for combos to 300ms.
+
+Then, your `keymap.c` file, you'll need to define a sequence of keys, terminated with `COMBO_END`, and a structure to list the combination of keys, and it's resulting action.
+
+```c
+const uint16_t PROGMEM test_combo[] = {KC_A, KC_B, COMBO_END};
+combo_t key_combos[COMBO_COUNT] = {COMBO(test_combo, KC_ESC)};
+```
+
+This will send "Escape" if you hit the A and B keys.
+
+!> This method only supports [basic keycodes](keycodes_basic.md). See the examples for more control.
+
+## Examples
+
+If you want to add a list, then you'd use something like this:
+
+```c
+enum combos {
+  AB_ESC,
+  JK_TAB
+};
+
+const uint16_t PROGMEM ab_combo[] = {KC_A, KC_B, COMBO_END};
+const uint16_t PROGMEM jk_combo[] = {KC_J, KC_K, COMBO_END};
+
+combo_t key_combos[COMBO_COUNT] = {
+  [AB_ESC] = COMBO(ab_combo, KC_ESC),
+  [JK_TAB] = COMBO(jk_combo, KC_TAB)
+};
+```
+
+For a more complicated implementation, you can use the `process_combo_event` function to add custom handling.
+
+```c
+enum combo_events {
+  ZC_COPY,
+  XV_PASTE
+};
+
+const uint16_t PROGMEM copy_combo[] = {KC_Z, KC_C, COMBO_END};
+const uint16_t PROGMEM paste_combo[] = {KC_X, KC_V, COMBO_END};
+
+combo_t key_combos[COMBO_COUNT] = {
+  [ZC_COPY] = COMBO_ACTION(copy_combo),
+  [XV_PASTE] = COMBO_ACTION(paste_combo),
+};
+
+void process_combo_event(uint8_t combo_index, bool pressed) {
+  switch(combo_index) {
+    case ZC_COPY:
+      if (pressed) {
+        tap_code16(LCTL(KC_C));
+      }
+      break;
+    case XV_PASTE:
+      if (pressed) {
+        tap_code16(LCTL(KC_V));
+      }
+      break;
+  }
+}
+```
+
+This will send Ctrl+C if you hit Z and C, and Ctrl+V if you hit X and V.  But you could change this to do stuff like change layers, play sounds, or change settings.
+
+## Additional Configuration
+
+If you're using long combos, or even longer combos, you may run into issues with this, as the structure may not be large enough to accommodate what you're doing.
+
+In this case, you can add either `#define EXTRA_LONG_COMBOS` or `#define EXTRA_EXTRA_LONG_COMBOS` in your `config.h` file.
+
+You may also be able to enable action keys by defining `COMBO_ALLOW_ACTION_KEYS`.
+
+## Keycodes 
+
+You can enable, disable and toggle the Combo feature on the fly.  This is useful if you need to disable them temporarily, such as for a game. 
+
+|Keycode   |Description                      |
+|----------|---------------------------------|
+|`CMB_ON`  |Turns on Combo feature           |
+|`CMB_OFF` |Turns off Combo feature          |
+|`CMB_TOG` |Toggles Combo feature on and off |
+
+## User callbacks
+
+In addition to the keycodes, there are a few functions that you can use to set the status, or check it:
+
+|Function   |Description                                                         |
+|-----------|--------------------------------------------------------------------|
+| `combo_enable()`     | Enables the combo feature                               |
+| `combo_disable()`    | Disables the combo feature, and clears the combo buffer |
+| `combo_toggle()`     | Toggles the state of the combo feature                  |
+| `is_combo_enabled()` | Returns the status of the combo feature state (true or false) |

docs/feature_command.md

@@ -0,0 +1,51 @@
+# Command
+
+Command, formerly known as Magic, is a way to change your keyboard's behavior without having to flash or unplug it to use [Bootmagic](feature_bootmagic.md). There is a lot of overlap between this functionality and the [Bootmagic Keycodes](feature_bootmagic.md#keycodes). Wherever possible we encourage you to use that feature instead of Command.
+
+On some keyboards Command is disabled by default. If this is the case, it must be explicitly enabled in your `rules.mk`:
+
+```make
+COMMAND_ENABLE = yes
+```
+
+## Usage
+
+To use Command, hold down the key combination defined by the `IS_COMMAND()` macro. By default this is Left Shift+Right Shift. Then, press the key corresponding to the command you want. For example, to output the current QMK version to the QMK Toolbox console, press Left Shift+Right Shift+`V`.
+
+## Configuration
+
+If you would like to change the key assignments for Command, `#define` these in your `config.h` at either the keyboard or keymap level. All keycode assignments here must omit the `KC_` prefix.
+
+|Define                              |Default                         |Description                                     |
+|------------------------------------|--------------------------------|------------------------------------------------|
+|`IS_COMMAND()`                      |`(get_mods() == MOD_MASK_SHIFT)`|The key combination to activate Command         |
+|`MAGIC_KEY_SWITCH_LAYER_WITH_FKEYS` |`true`                          |Set default layer with the Function row         |
+|`MAGIC_KEY_SWITCH_LAYER_WITH_NKEYS` |`true`                          |Set default layer with the number keys          |
+|`MAGIC_KEY_SWITCH_LAYER_WITH_CUSTOM`|`false`                         |Set default layer with `MAGIC_KEY_LAYER0..9`    |
+|`MAGIC_KEY_DEBUG`                   |`D`                             |Toggle debugging over serial                    |
+|`MAGIC_KEY_DEBUG_MATRIX`            |`X`                             |Toggle key matrix debugging                     |
+|`MAGIC_KEY_DEBUG_KBD`               |`K`                             |Toggle keyboard debugging                       |
+|`MAGIC_KEY_DEBUG_MOUSE`             |`M`                             |Toggle mouse debugging                          |
+|`MAGIC_KEY_CONSOLE`                 |`C`                             |Enable the Command console                      |
+|`MAGIC_KEY_VERSION`                 |`V`                             |Print the running QMK version to the console    |
+|`MAGIC_KEY_STATUS`                  |`S`                             |Print the current keyboard status to the console|
+|`MAGIC_KEY_HELP`                    |`H`                             |Print Command help to the console               |
+|`MAGIC_KEY_HELP_ALT`                |`SLASH`                         |Print Command help to the console (alternate)   |
+|`MAGIC_KEY_LAYER0`                  |`0`                             |Make layer 0 the default layer                  |
+|`MAGIC_KEY_LAYER0_ALT`              |`GRAVE`                         |Make layer 0 the default layer (alternate)      |
+|`MAGIC_KEY_LAYER1`                  |`1`                             |Make layer 1 the default layer                  |
+|`MAGIC_KEY_LAYER2`                  |`2`                             |Make layer 2 the default layer                  |
+|`MAGIC_KEY_LAYER3`                  |`3`                             |Make layer 3 the default layer                  |
+|`MAGIC_KEY_LAYER4`                  |`4`                             |Make layer 4 the default layer                  |
+|`MAGIC_KEY_LAYER5`                  |`5`                             |Make layer 5 the default layer                  |
+|`MAGIC_KEY_LAYER6`                  |`6`                             |Make layer 6 the default layer                  |
+|`MAGIC_KEY_LAYER7`                  |`7`                             |Make layer 7 the default layer                  |
+|`MAGIC_KEY_LAYER8`                  |`8`                             |Make layer 8 the default layer                  |
+|`MAGIC_KEY_LAYER9`                  |`9`                             |Make layer 9 the default layer                  |
+|`MAGIC_KEY_BOOTLOADER`              |`B`                             |Jump to bootloader                              |
+|`MAGIC_KEY_BOOTLOADER_ALT`          |`ESC`                           |Jump to bootloader (alternate)                  |
+|`MAGIC_KEY_LOCK`                    |`CAPS`                          |Lock the keyboard so nothing can be typed       |
+|`MAGIC_KEY_EEPROM`                  |`E`                             |Print stored EEPROM config to the console       |
+|`MAGIC_KEY_EEPROM_CLEAR`            |`BSPACE`                        |Clear the EEPROM                                |
+|`MAGIC_KEY_NKRO`                    |`N`                             |Toggle N-Key Rollover (NKRO)                    |
+|`MAGIC_KEY_SLEEP_LED`               |`Z`                             |Toggle LED when computer is sleeping            |

docs/feature_debounce_type.md

@@ -0,0 +1,42 @@
+# Debounce algorithm
+
+QMK supports multiple debounce algorithms through its debounce API.
+
+The logic for which debounce method called is below. It checks various defines that you have set in rules.mk
+
+```
+DEBOUNCE_DIR:= $(QUANTUM_DIR)/debounce
+DEBOUNCE_TYPE?= sym_g
+ifneq ($(strip $(DEBOUNCE_TYPE)), custom)
+    QUANTUM_SRC += $(DEBOUNCE_DIR)/$(strip $(DEBOUNCE_TYPE)).c
+endif
+```
+
+# Debounce selection
+
+| DEBOUNCE_TYPE    | Description                                          | What else is needed           |
+| -------------    | ---------------------------------------------------  | ----------------------------- |
+| Not defined      | Use the default algorithm, currently sym_g           | Nothing                       |
+| custom           | Use your own debounce.c                              | ```SRC += debounce.c``` add your own debounce.c and implement necessary functions |
+| anything_else    | Use another algorithm from quantum/debounce/*        | Nothing                       |
+
+**Regarding split keyboards**:
+The debounce code is compatible with split keyboards.
+
+# Use your own debouncing code
+* Set ```DEBOUNCE_TYPE = custom ```.
+* Add ```SRC += debounce.c```
+* Add your own ```debounce.c```. Look at current implementations in ```quantum/debounce``` for examples.
+* Debouncing occurs after every raw matrix scan.
+* Use num_rows rather than MATRIX_ROWS, so that split keyboards are supported correctly.
+
+# Changing between included debouncing methods
+You can either use your own code, by including your own debounce.c, or switch to another included one.
+Included debounce methods are:
+* eager_pr - debouncing per row. On any state change, response is immediate, followed by locking the row ```DEBOUNCE_DELAY``` milliseconds of no further input for that row. 
+For use in keyboards where refreshing ```NUM_KEYS``` 8-bit counters is computationally expensive / low scan rate, and fingers usually only hit one row at a time. This could be
+appropriate for the ErgoDox models; the matrix is rotated 90°, and hence its "rows" are really columns, and each finger only hits a single "row" at a time in normal use.
+* eager_pk - debouncing per key. On any state change, response is immediate, followed by ```DEBOUNCE_DELAY``` milliseconds of no further input for that key
+* sym_g - debouncing per keyboard. On any state change, a global timer is set. When ```DEBOUNCE_DELAY``` milliseconds of no changes has occured, all input changes are pushed.
+
+

docs/feature_dip_switch.md

@@ -0,0 +1,90 @@
+# DIP Switches
+
+DIP switches are supported by adding this to your `rules.mk`:
+
+    DIP_SWITCH_ENABLE = yes
+
+and this to your `config.h`:
+
+```c
+#define DIP_SWITCH_PINS { B14, A15, A10, B9 }
+```
+
+## Callbacks
+
+The callback functions can be inserted into your `<keyboard>.c`:
+
+```c
+void dip_switch_update_kb(uint8_t index, bool active) { 
+    dip_switch_update_user(index, active); 
+}
+```
+
+
+or `keymap.c`:
+
+```c
+void dip_switch_update_user(uint8_t index, bool active) { 
+    switch (index) {
+        case 0:
+            if(active) { audio_on(); } else { audio_off(); }
+            break;
+        case 1:
+            if(active) { clicky_on(); } else { clicky_off(); }
+            break;
+        case 2:
+            if(active) { music_on(); } else { music_off(); }
+            break;
+        case 3:
+            if (active) {
+                #ifdef AUDIO_ENABLE
+                    PLAY_SONG(plover_song);
+                #endif
+                layer_on(_PLOVER);
+            } else {
+                #ifdef AUDIO_ENABLE
+                    PLAY_SONG(plover_gb_song);
+                #endif
+                layer_off(_PLOVER);
+            }
+            break;
+    }
+}
+```
+
+Additionally, we support bit mask functions which allow for more complex handling. 
+
+
+```c
+void dip_switch_update_mask_kb(uint32_t state) { 
+    dip_switch_update_mask_user(state); 
+}
+```
+
+
+or `keymap.c`:
+
+```c
+void dip_switch_update_mask_user(uint32_t state) { 
+    if (state & (1UL<<0) && state & (1UL<<1)) {
+        layer_on(_ADJUST); // C on esc
+    } else {
+        layer_off(_ADJUST);
+    }
+    if (state & (1UL<<0)) {
+        layer_on(_TEST_A); // A on ESC
+    } else {
+        layer_off(_TEST_A);
+    }
+    if (state & (1UL<<1)) {
+        layer_on(_TEST_B); // B on esc
+    } else {
+        layer_off(_TEST_B);
+    }
+}
+```
+
+
+## Hardware
+
+One side of the DIP switch should be wired directly to the pin on the MCU, and the other side to ground.  It should not matter which side is connected to which, as it should be functionally the same. 

docs/feature_dynamic_macros.md

@@ -0,0 +1,63 @@
+# Dynamic Macros: Record and Replay Macros in Runtime
+
+QMK supports temporary macros created on the fly. We call these Dynamic Macros. They are defined by the user from the keyboard and are lost when the keyboard is unplugged or otherwise rebooted.
+
+You can store one or two macros and they may have a combined total of 128 keypresses. You can increase this size at the cost of RAM.
+
+To enable them, first add a new element to the end of your `keycodes` enum — `DYNAMIC_MACRO_RANGE`:
+
+```c
+enum keycodes {
+	QWERTY = SAFE_RANGE,
+	COLEMAK,
+	DVORAK,
+	PLOVER,
+	LOWER,
+	RAISE,
+	BACKLIT,
+	EXT_PLV,
+	DYNAMIC_MACRO_RANGE,
+};
+```
+
+Your `keycodes` enum may have a slightly different name. You must add `DYNAMIC_MACRO_RANGE` as the last element because `dynamic_macros.h` will add some more keycodes after it.
+
+Below it, include the `dynamic_macro.h` header:
+
+```c
+	#include "dynamic_macro.h"`
+```
+
+Add the following keys to your keymap:
+
+* `DYN_REC_START1` — start recording the macro 1,
+* `DYN_REC_START2` — start recording the macro 2,
+* `DYN_MACRO_PLAY1` — replay the macro 1,
+* `DYN_MACRO_PLAY2` — replay the macro 2,
+* `DYN_REC_STOP` — finish the macro that is currently being recorded.
+
+Add the following code to the very beginning of your `process_record_user()` function:
+
+```c
+	if (!process_record_dynamic_macro(keycode, record)) {
+		return false;
+	}
+```
+
+That should be everything necessary. To start recording the macro, press either `DYN_REC_START1` or `DYN_REC_START2`. To finish the recording, press the `DYN_REC_STOP` layer button. To replay the macro, press either `DYN_MACRO_PLAY1` or `DYN_MACRO_PLAY2`.
+
+Note that it's possible to replay a macro as part of a macro. It's ok to replay macro 2 while recording macro 1 and vice versa but never create recursive macros i.e. macro 1 that replays macro 1. If you do so and the keyboard will get unresponsive, unplug the keyboard and plug it again.
+
+For users of the earlier versions of dynamic macros: It is still possible to finish the macro recording using just the layer modifier used to access the dynamic macro keys, without a dedicated `DYN_REC_STOP` key. If you want this behavior back, use the following snippet instead of the one above:
+
+```c
+	uint16_t macro_kc = (keycode == MO(_DYN) ? DYN_REC_STOP : keycode);
+
+	if (!process_record_dynamic_macro(macro_kc, record)) {
+		return false;
+	}
+```
+
+If the LEDs start blinking during the recording with each keypress, it means there is no more space for the macro in the macro buffer. To fit the macro in, either make the other macro shorter (they share the same buffer) or increase the buffer size by setting the `DYNAMIC_MACRO_SIZE` preprocessor macro (default value: 128; please read the comments for it in the header).
+
+For the details about the internals of the dynamic macros, please read the comments in the `dynamic_macro.h` header.

docs/feature_encoders.md

@@ -0,0 +1,60 @@
+# Encoders
+
+Basic encoders are supported by adding this to your `rules.mk`:
+
+    ENCODER_ENABLE = yes
+
+and this to your `config.h`:
+
+    #define ENCODERS_PAD_A { B12 }
+    #define ENCODERS_PAD_B { B13 }
+
+Each PAD_A/B variable defines an array so multiple encoders can be defined, e.g.:
+
+    #define ENCODERS_PAD_A { encoder1a, encoder2a }
+    #define ENCODERS_PAD_B { encoder1b, encoder2b }
+
+If your encoder's clockwise directions are incorrect, you can swap the A & B pad definitions.
+
+Additionally, the resolution can be specified in the same file (the default & suggested is 4):
+
+    #define ENCODER_RESOLUTION 4
+
+## Split Keyboards
+
+If you are using different pinouts for the encoders on each half of a split keyboard, you can define the pinout for the right half like this:
+
+```c
+#define ENCODERS_PAD_A_RIGHT { encoder1a, encoder2a }
+#define ENCODERS_PAD_B_RIGHT { encoder1b, encoder2b }
+```
+
+## Callbacks
+
+The callback functions can be inserted into your `<keyboard>.c`:
+
+    void encoder_update_kb(uint8_t index, bool clockwise) {
+        encoder_update_user(index, clockwise);
+    }
+
+or `keymap.c`:
+
+    void encoder_update_user(uint8_t index, bool clockwise) {
+      if (index == 0) { /* First encoder */
+        if (clockwise) {
+          tap_code(KC_PGDN);
+        } else {
+          tap_code(KC_PGUP);
+        }
+      } else if (index == 1) { /* Second encoder */  
+        if (clockwise) {
+          tap_code(KC_UP);
+        } else {
+          tap_code(KC_DOWN);
+        }
+      }
+    }
+
+## Hardware
+
+The A an B lines of the encoders should be wired directly to the MCU, and the C/common lines should be wired to ground.

docs/feature_grave_esc.md

@@ -0,0 +1,32 @@
+# Grave Escape
+
+If you're using a 60% keyboard, or any other layout with no F-row, you will have noticed that there is no dedicated Escape key. Grave Escape is a feature that allows you to share the grave key (<code>&#96;</code> and `~`) with Escape.
+
+## Usage
+
+Replace the `KC_GRAVE` key in your keymap (usually to the left of the `1` key) with `KC_GESC`. Most of the time this key will output `KC_ESC` when pressed. However, when Shift or GUI are held down it will output `KC_GRV` instead.
+
+## What Your OS Sees
+
+If Mary presses GESC on her keyboard, the OS will see an KC_ESC character. Now if Mary holds Shift down and presses GESC it will output `~`, or a shifted backtick. Now if she holds GUI/CMD/WIN, it will output a simple <code>&#96;</code> character.
+
+## Keycodes
+
+|Key      |Aliases    |Description                                                       |
+|---------|-----------|------------------------------------------------------------------|
+|`KC_GESC`|`GRAVE_ESC`|Escape when pressed, <code>&#96;</code> when Shift or GUI are held|
+
+### Caveats
+
+On macOS, Command+<code>&#96;</code> is by default mapped to "Move focus to next window" so it will not output a backtick. Additionally, Terminal always recognises this shortcut to cycle between windows, even if the shortcut is changed in the Keyboard preferences.
+
+## Configuration
+
+There are several possible key combinations this will break, among them Control+Shift+Escape on Windows and Command+Option+Escape on macOS. To work around this, you can `#define` these options in your `config.h`:
+
+|Define                    |Description                              |
+|--------------------------|-----------------------------------------|
+|`GRAVE_ESC_ALT_OVERRIDE`  |Always send Escape if Alt is pressed     |
+|`GRAVE_ESC_CTRL_OVERRIDE` |Always send Escape if Control is pressed |
+|`GRAVE_ESC_GUI_OVERRIDE`  |Always send Escape if GUI is pressed     |
+|`GRAVE_ESC_SHIFT_OVERRIDE`|Always send Escape if Shift is pressed   |

docs/feature_haptic_feedback.md

@@ -0,0 +1,154 @@
+# Haptic Feedback
+
+## Haptic feedback rules.mk options
+
+The following options are currently available for haptic feedback in `rule.mk`:
+
+`HAPTIC_ENABLE += DRV2605L`
+
+`HAPTIC_ENABLE += SOLENOID`
+
+## Known Supported Hardware
+
+| Name               | Description                                     |
+|--------------------|-------------------------------------------------|
+| [LV061228B-L65-A](https://www.digikey.com/product-detail/en/jinlong-machinery-electronics-inc/LV061228B-L65-A/1670-1050-ND/7732325) | z-axis 2v LRA |
+| [Mini Motor Disc](https://www.adafruit.com/product/1201)  | small 2-5v ERM |
+
+## Haptic Keycodes
+
+Not all keycodes below will work depending on which haptic mechanism you have chosen.
+
+| Name      | Description                                           |
+|-----------|-------------------------------------------------------|
+|`HPT_ON`   | Turn haptic feedback on                               |
+|`HPT_OFF`  | Turn haptic feedback on                               |
+|`HPT_TOG`  | Toggle haptic feedback on/off                         |
+|`HPT_RST`  | Reset haptic feedback config to default               |
+|`HPT_FBK`  | Toggle feedback to occur on keypress, release or both |
+|`HPT_BUZ`  | Toggle solenoid buzz on/off                           |
+|`HPT_MODI` | Go to next DRV2605L waveform                          |
+|`HPT_MODD` | Go to previous DRV2605L waveform                      |
+|`HPT_CONT` | Toggle continuous haptic mode on/off                  |
+|`HPT_CONI` | Increase DRV2605L continous haptic strength           |
+|`HPT_COND` | Decrease DRV2605L continous haptic strength           |
+|`HPT_DWLI` | Increase Solenoid dwell time                          |
+|`HPT_DWLD` | Decrease Solenoid dwell time                          |
+
+### Solenoids
+
+First you will need a build a circuit to drive the solenoid through a mosfet as most MCU will not be able to provide the current needed to drive the coil in the solenoid.
+
+[Wiring diagram provided by Adafruit](https://playground.arduino.cc/uploads/Learning/solenoid_driver.pdf)
+
+Select a pin that has PWM for the signal pin
+
+```
+#define SOLENOID_PIN *pin*
+```
+
+Beware that some pins may be powered during bootloader (ie. A13 on the STM32F303 chip) and will result in the solenoid kept in the on state through the whole flashing process. This may overheat and damage the solenoid. If you find that the pin the solenoid is connected to is triggering the solenoid during bootloader/DFU, select another pin.
+
+### DRV2605L
+
+DRV2605L is controlled over i2c protocol, and has to be connected to the SDA and SCL pins, these varies depending on the MCU in use.
+
+#### Feedback motor setup
+
+This driver supports 2 different feedback motors. Set the following in your `config.h` based on which motor you have selected.
+
+##### ERM
+
+Eccentric Rotating Mass vibration motors (ERM) is motor with a off-set weight attached so when drive signal is attached, the off-set weight spins and causes a sinusoidal wave that translate into vibrations.
+
+```
+#define FB_ERM_LRA 0
+#define FB_BRAKEFACTOR 3 /* For 1x:0, 2x:1, 3x:2, 4x:3, 6x:4, 8x:5, 16x:6, Disable Braking:7 */
+#define FB_LOOPGAIN 1 /* For  Low:0, Medium:1, High:2, Very High:3 */
+
+/* Please refer to your datasheet for the optimal setting for your specific motor. */
+#define RATED_VOLTAGE 3
+#define V_PEAK 5
+```
+##### LRA
+
+Linear resonant actuators (LRA, also know as a linear vibrator) works different from a ERM. A LRA has a weight and magnet suspended by springs and a voice coil. When the drive signal is applied, the weight would be vibrate on a single axis (side to side or up and down). Since the weight is attached to a spring, there is a resonance effect at a specific frequency. This frequency is where the LRA will operate the most efficiently. Refer to the motor's datasheet for the recommanded range for this frequency.
+
+``` 
+#define FB_ERM_LRA 1
+#define FB_BRAKEFACTOR 3 /* For 1x:0, 2x:1, 3x:2, 4x:3, 6x:4, 8x:5, 16x:6, Disable Braking:7 */
+#define FB_LOOPGAIN 1 /* For  Low:0, Medium:1, High:2, Very High:3 */
+
+/* Please refer to your datasheet for the optimal setting for your specific motor. */
+#define RATED_VOLTAGE 2
+#define V_PEAK 2.8
+#define V_RMS 2.0 
+#define V_PEAK 2.1
+#define F_LRA 205 /* resonance freq */
+```
+
+#### DRV2605L waveform library
+
+DRV2605L comes with preloaded library of various waveform sequences that can be called and played. If writing a macro, these waveforms can be played using `DRV_pulse(*sequence name or number*)`
+
+List of waveform sequences from the datasheet:
+
+|seq# | Sequence name          |seq# | Sequence name                  |seq# |Sequence name                           |
+|-----|---------------------|-----|-----------------------------------|-----|--------------------------------------|
+| 1   | strong_click 		| 43  | lg_dblclick_med_60                | 85  | transition_rampup_med_smooth2        |
+| 2   | strong_click_60 	| 44  | lg_dblsharp_tick                  | 86  | transition_rampup_short_smooth1      |
+| 3   | strong_click_30 	| 45  | lg_dblsharp_tick_80               | 87  | transition_rampup_short_smooth2      |
+| 4   | sharp_click 		| 46  | lg_dblsharp_tick_60               | 88  | transition_rampup_long_sharp1        |
+| 5   | sharp_click_60      | 47  | buzz                              | 89  | transition_rampup_long_sharp2        |
+| 6   | sharp_click_30      | 48  | buzz_80				              | 90  | transition_rampup_med_sharp1         |
+| 7   | soft_bump           | 49  | buzz_60		                      | 91  | transition_rampup_med_sharp2         |
+| 8   | soft_bump_60        | 50  | buzz_40				              | 92  | transition_rampup_short_sharp1       |
+| 9   | soft_bump_30        | 51  | buzz_20				              | 93  | transition_rampup_short_sharp2       |
+| 10  | dbl_click           | 52  | pulsing_strong                    | 94  | transition_rampdown_long_smooth1_50  |
+| 11  | dbl_click_60        | 53  | pulsing_strong_80                 | 95  | transition_rampdown_long_smooth2_50  |
+| 12  | trp_click           | 54  | pulsing_medium                    | 96  | transition_rampdown_med_smooth1_50   |
+| 13  | soft_fuzz           | 55  | pulsing_medium_80                 | 97  | transition_rampdown_med_smooth2_50   |
+| 14  | strong_buzz         | 56  | pulsing_sharp                     | 98  | transition_rampdown_short_smooth1_50 |
+| 15  | alert_750ms         | 57  | pulsing_sharp_80                  | 99  | transition_rampdown_short_smooth2_50 |
+| 16  | alert_1000ms        | 58  | transition_click	              | 100 | transition_rampdown_long_sharp1_50   |
+| 17  | strong_click1       | 59  | transition_click_80               | 101 | transition_rampdown_long_sharp2_50   |
+| 18  | strong_click2_80    | 60  | transition_click_60	              | 102 | transition_rampdown_med_sharp1_50    |
+| 19  | strong_click3_60    | 61  | transition_click_40	              | 103 | transition_rampdown_med_sharp2_50    |
+| 20  | strong_click4_30    | 62  | transition_click_20	              | 104 | transition_rampdown_short_sharp1_50  |
+| 21  | medium_click1       | 63  | transition_click_10	              | 105 | transition_rampdown_short_sharp2_50  |
+| 22  | medium_click2_80    | 64  | transition_hum                    | 106 | transition_rampup_long_smooth1_50    |
+| 23  | medium_click3_60    | 65  | transition_hum_80                 | 107 | transition_rampup_long_smooth2_50    |
+| 24  | sharp_tick1         | 66  | transition_hum_60                 | 108 | transition_rampup_med_smooth1_50     |
+| 25  | sharp_tick2_80      | 67  | transition_hum_40                 | 109 | transition_rampup_med_smooth2_50     |
+| 26  | sharp_tick3_60      | 68  | transition_hum_20                 | 110 | transition_rampup_short_smooth1_50   |
+| 27  | sh_dblclick_str     | 69  | transition_hum_10                 | 111 | transition_rampup_short_smooth2_50   |
+| 28  | sh_dblclick_str_80  | 70  | transition_rampdown_long_smooth1  | 112 | transition_rampup_long_sharp1_50     |
+| 29  | sh_dblclick_str_60  | 71  | transition_rampdown_long_smooth2  | 113 | transition_rampup_long_sharp2_50     |
+| 30  | sh_dblclick_str_30  | 72  | transition_rampdown_med_smooth1   | 114 | transition_rampup_med_sharp1_50      |
+| 31  | sh_dblclick_med     | 73  | transition_rampdown_med_smooth2   | 115 | transition_rampup_med_sharp2_50      |
+| 32  | sh_dblclick_med_80  | 74  | transition_rampdown_short_smooth1 | 116 | transition_rampup_short_sharp1_50    |
+| 33  | sh_dblclick_med_60  | 75  | transition_rampdown_short_smooth2 | 117 | transition_rampup_short_sharp2_50    |
+| 34  | sh_dblsharp_tick    | 76  | transition_rampdown_long_sharp1   | 118 | long_buzz_for_programmatic_stopping  |
+| 35  | sh_dblsharp_tick_80 | 77  | transition_rampdown_long_sharp2   | 119 | smooth_hum1_50                       |
+| 36  | sh_dblsharp_tick_60 | 78  | transition_rampdown_med_sharp1    | 120 | smooth_hum2_40                       |
+| 37  | lg_dblclick_str     | 79  | transition_rampdown_med_sharp2    | 121 | smooth_hum3_30                       |
+| 38  | lg_dblclick_str_80  | 80  | transition_rampdown_short_sharp1  | 122 | smooth_hum4_20                       |
+| 39  | lg_dblclick_str_60  | 81  | transition_rampdown_short_sharp2  | 123 | smooth_hum5_10                       |
+| 40  | lg_dblclick_str_30  | 82  | transition_rampup_long_smooth1    |     |                                      |
+| 41  | lg_dblclick_med     | 83  | transition_rampup_long_smooth2    |     |                                      |
+| 42  | lg_dblclick_med_80  | 84  | transition_rampup_med_smooth1     |     |                                      |
+### Optional DRV2605L defines
+
+```
+#define DRV_GREETING *sequence name or number*
+```
+If haptic feedback is enabled, the keyboard will vibrate to a specific sqeuence during startup. That can be selected using the following define:
+
+```
+#define DRV_MODE_DEFAULT *sequence name or number*
+```
+This will set what sequence HPT_RST will set as the active mode. If not defined, mode will be set to 1 when HPT_RST is pressed.
+
+### DRV2605L Continuous Haptic Mode
+
+This mode sets continuous haptic feedback with the option to increase or decrease strength. 

docs/feature_hd44780.md

@@ -0,0 +1,57 @@
+# HD44780 LCD Displays
+
+This is an integration of Peter Fleury's LCD library. This page will explain the basics. [For in depth documentation visit his page.](http://homepage.hispeed.ch/peterfleury/doxygen/avr-gcc-libraries/group__pfleury__lcd.html)
+
+You can enable support for HD44780 Displays by setting the `HD44780_ENABLE` flag in your keyboards `rules.mk` to yes.
+
+## Configuration
+
+You will need to configure the pins used by your display, and its number of lines and columns in your keyboard's `config.h`.
+
+
+Uncomment the section labled HD44780 and change the parameters as needed.
+````
+/*
+ * HD44780 LCD Display Configuration
+ */
+
+#define LCD_LINES           2     //< number of visible lines of the display
+#define LCD_DISP_LENGTH    16     //< visibles characters per line of the display
+#define LCD_IO_MODE      1            //< 0: memory mapped mode, 1: IO port mode
+#if LCD_IO_MODE
+#define LCD_PORT         PORTB        //< port for the LCD lines
+#define LCD_DATA0_PORT   LCD_PORT     //< port for 4bit data bit 0
+#define LCD_DATA1_PORT   LCD_PORT     //< port for 4bit data bit 1
+#define LCD_DATA2_PORT   LCD_PORT     //< port for 4bit data bit 2
+#define LCD_DATA3_PORT   LCD_PORT     //< port for 4bit data bit 3
+#define LCD_DATA0_PIN    4            //< pin for 4bit data bit 0
+#define LCD_DATA1_PIN    5            //< pin for 4bit data bit 1
+#define LCD_DATA2_PIN    6            //< pin for 4bit data bit 2
+#define LCD_DATA3_PIN    7            //< pin for 4bit data bit 3
+#define LCD_RS_PORT      LCD_PORT     //< port for RS line        
+#define LCD_RS_PIN       3            //< pin  for RS line        
+#define LCD_RW_PORT      LCD_PORT     //< port for RW line        
+#define LCD_RW_PIN       2            //< pin  for RW line        
+#define LCD_E_PORT       LCD_PORT     //< port for Enable line     
+#define LCD_E_PIN        1            //< pin  for Enable line    
+#endif
+````
+
+Should you need to configure other properties you can copy them from `quantum/hd44780.h` and set them in your `config.h`
+
+## Usage
+
+To initialize your display, call `lcd_init()` with one of these parameters:
+````
+LCD_DISP_OFF             : display off
+LCD_DISP_ON              : display on, cursor off
+LCD_DISP_ON_CURSOR       : display on, cursor on
+LCD_DISP_ON_CURSOR_BLINK : display on, cursor on flashing
+````
+This is best done in your keyboards `matrix_init_kb` or your keymaps `matrix_init_user`.  
+It is advised to clear the display before use.  
+To do so call `lcd_clrsrc()`.
+
+To now print something to your Display you first call `lcd_gotoxy(column, line)`. To go to the start of the first line you would call `lcd_gotoxy(0, 0)` and then print a string with `lcd_puts("example string")`.
+
+There are more methods available to control the display. [For in depth documentation please visit the linked page.](http://homepage.hispeed.ch/peterfleury/doxygen/avr-gcc-libraries/group__pfleury__lcd.html)

docs/feature_key_lock.md

@@ -0,0 +1,22 @@
+# Key Lock
+
+Sometimes you may find yourself needing to hold down a specific key for a long period of time. Key Lock holds down the next key you press for you. Press it again, and it will be released.
+
+Let's say you need to type in ALL CAPS for a few sentences. Hit `KC_LOCK`, and then Shift. Now, Shift will be considered held until you tap it again. You can think of Key Lock as Caps Lock, but supercharged.
+
+## Usage
+
+First, enable Key Lock by setting `KEY_LOCK_ENABLE = yes` in your `rules.mk`. Then pick a key in your keymap and assign it the keycode `KC_LOCK`.
+
+## Keycodes
+
+|Keycode  |Description                                                   |
+|---------|--------------------------------------------------------------|
+|`KC_LOCK`|Hold down the next key pressed, until the key is pressed again|
+
+## Caveats
+
+Key Lock is only able to hold standard action keys and [One Shot modifier](feature_advanced_keycodes.md#one-shot-keys) keys (for example, if you have your Shift defined as `OSM(KC_LSFT)`).
+This does not include any of the QMK special functions (except One Shot modifiers), or shifted versions of keys such as `KC_LPRN`. If it's in the [Basic Keycodes](keycodes_basic.md) list, it can be held.
+
+Switching layers will not cancel the Key Lock.

docs/feature_layouts.md

@@ -0,0 +1,109 @@
+# Layouts: Using a Keymap with Multiple Keyboards
+
+The `layouts/` folder contains different physical key layouts that can apply to different keyboards.
+
+```
+layouts/
++ default/
+| + 60_ansi/
+| | + readme.md
+| | + layout.json
+| | + a_good_keymap/
+| | | + keymap.c
+| | | + readme.md
+| | | + config.h
+| | | + rules.mk
+| | + <keymap folder>/
+| | + ...
+| + <layout folder>/
++ community/
+| + <layout folder>/
+| + ...
+```
+
+The `layouts/default/` and `layouts/community/` are two examples of layout "repositories" - currently `default` will contain all of the information concerning the layout, and one default keymap named `default_<layout>`, for users to use as a reference. `community` contains all of the community keymaps, with the eventual goal of being split-off into a separate repo for users to clone into `layouts/`. QMK searches through all folders in `layouts/`, so it's possible to have multiple repositories here.
+
+Each layout folder is named (`[a-z0-9_]`) after the physical aspects of the layout, in the most generic way possible, and contains a `readme.md` with the layout to be defined by the keyboard:
+
+```md
+# 60_ansi
+
+   LAYOUT_60_ansi
+```
+
+New names should try to stick to the standards set by existing layouts, and can be discussed in the PR/Issue.
+
+## Supporting a Layout
+
+For a keyboard to support a layout, the variable must be defined in it's `<keyboard>.h`, and match the number of arguments/keys (and preferably the physical layout):
+
+    #define LAYOUT_60_ansi KEYMAP_ANSI
+
+The name of the layout must match this regex: `[a-z0-9_]+`
+
+The folder name must be added to the keyboard's `rules.mk`:
+
+    LAYOUTS = 60_ansi
+
+`LAYOUTS` can be set in any keyboard folder level's `rules.mk`:
+
+    LAYOUTS = 60_iso
+
+but the `LAYOUT_<layout>` variable must be defined in `<folder>.h` as well.
+
+## Building a Keymap
+
+You should be able to build the keyboard keymap with a command in this format:
+
+    make <keyboard>:<layout>
+
+### Conflicting layouts
+When a keyboard supports multiple layout options,
+
+    LAYOUTS = ortho_4x4 ortho_4x12
+
+And a layout exists for both options,
+```
+layouts/
++ community/
+| + ortho_4x4/
+| | + <layout>/
+| | | + ...
+| + ortho_4x12/
+| | + <layout>/
+| | | + ...
+| + ...
+```
+
+The FORCE_LAYOUT argument can be used to specify which layout to build
+
+    make <keyboard>:<layout> FORCE_LAYOUT=ortho_4x4
+    make <keyboard>:<layout> FORCE_LAYOUT=ortho_4x12
+
+## Tips for Making Layouts Keyboard-Agnostic
+
+### Includes
+
+Instead of using `#include "planck.h"`, you can use this line to include whatever `<keyboard>.h` (`<folder>.h` should not be included here) file that is being compiled:
+
+    #include QMK_KEYBOARD_H
+
+If you want to keep some keyboard-specific code, you can use these variables to escape it with an `#ifdef` statement:
+
+* `KEYBOARD_<folder1>_<folder2>`
+
+For example:
+
+```c
+#ifdef KEYBOARD_planck
+    #ifdef KEYBOARD_planck_rev4
+        planck_rev4_function();
+    #endif
+#endif
+```
+
+Note that the names are lowercase and match the folder/file names for the keyboard/revision exactly.
+
+### Keymaps
+
+In order to support both split and non-split keyboards with the same layout, you need to use the keyboard agnostic `LAYOUT_<layout name>` macro in your keymap. For instance, in order for a Let's Split and Planck to share the same layout file, you need to use `LAYOUT_ortho_4x12` instead of `LAYOUT_planck_grid` or just `{}` for a C array.

docs/feature_leader_key.md

@@ -0,0 +1,146 @@
+# The Leader Key: A New Kind of Modifier
+
+If you've ever used Vim, you know what a Leader key is. If not, you're about to discover a wonderful concept. :) Instead of hitting Alt+Shift+W for example (holding down three keys at the same time), what if you could hit a _sequence_ of keys instead? So you'd hit our special modifier (the Leader key), followed by W and then C (just a rapid succession of keys), and something would happen.
+
+That's what `KC_LEAD` does. Here's an example:
+
+1. Pick a key on your keyboard you want to use as the Leader key. Assign it the keycode `KC_LEAD`. This key would be dedicated just for this -- it's a single action key, can't be used for anything else.
+2. Include the line `#define LEADER_TIMEOUT 300` in your `config.h`. This sets the timeout for the `KC_LEAD` key.  Specifically, when you press the `KC_LEAD` key, you only have a certain amount of time to complete the Leader Key sequence.  The `300` here sets that to 300ms, and you can increase this value to give you more time to hit the sequence. But any keys pressed during this timeout are intercepted and not sent, so you may want to keep this value low. .  
+   * By default, this timeout is how long after pressing `KC_LEAD` to complete your entire sequence. This may be very low for some people. So you may want to increase this timeout.  Optionally, you may want to enable the `LEADER_PER_KEY_TIMING` option, which resets the timeout after each key is tapped.  This allows you to maintain a low value here, but still be able to use the longer sequences.   To enable this option, add `#define LEADER_PER_KEY_TIMING` to your `config.h`.
+3. Within your `matrix_scan_user` function, add something like this:
+
+```c
+LEADER_EXTERNS();
+
+void matrix_scan_user(void) {
+  LEADER_DICTIONARY() {
+    leading = false;
+    leader_end();
+
+    SEQ_ONE_KEY(KC_F) {
+      // Anything you can do in a macro.
+      SEND_STRING("QMK is awesome.");
+    }
+    SEQ_TWO_KEYS(KC_D, KC_D) {
+      SEND_STRING(SS_LCTRL("a")SS_LCTRL("c"));
+    }
+    SEQ_THREE_KEYS(KC_D, KC_D, KC_S) {
+      SEND_STRING("https://start.duckduckgo.com"SS_TAP(X_ENTER));
+    }
+    SEQ_TWO_KEYS(KC_A, KC_S) {
+      register_code(KC_LGUI);
+      register_code(KC_S);
+      unregister_code(KC_S);
+      unregister_code(KC_LGUI);
+    }
+  }
+}
+```
+
+As you can see, you have a few function. You can use `SEQ_ONE_KEY` for single-key sequences (Leader followed by just one key), and `SEQ_TWO_KEYS`, `SEQ_THREE_KEYS` up to `SEQ_FIVE_KEYS` for longer sequences.
+
+Each of these accepts one or more keycodes as arguments. This is an important point: You can use keycodes from **any layer on your keyboard**. That layer would need to be active for the leader macro to fire, obviously.
+
+## Adding Leader Key Support in the `rules.mk`
+
+To add support for Leader Key you simply need to add a single line to your keymap's `rules.mk`:
+
+```make
+LEADER_ENABLE = yes
+```
+
+## Per Key Timing on Leader keys
+
+Rather than relying on an incredibly high timeout for long leader key strings or those of us without 200wpm typing skills, we can enable per key timing to ensure that each key pressed provides us with more time to finish our stroke. This is incredibly helpful with leader key emulation of tap dance (read: multiple taps of the same key like C, C, C).
+
+In order to enable this, place this in your `config.h`:
+```c
+#define LEADER_PER_KEY_TIMING
+```
+
+After this, it's recommended that you lower your `LEADER_TIMEOUT` to something less that 300ms.
+
+```c
+#define LEADER_TIMEOUT 250
+```
+
+Now, something like this won't seem impossible to do without a 1000MS leader key timeout:
+
+```c
+SEQ_THREE_KEYS(KC_C, KC_C, KC_C) {
+  SEND_STRING("Per key timing is great!!!");
+}
+```
+
+## Strict Key Processing
+
+By default, the Leader Key feature will filter the keycode out of [`Mod-Tap`](feature_advanced_keycodes.md#mod-tap) and [`Layer Tap`](feature_advanced_keycodes.md#switching-and-toggling-layers) functions when checking for the Leader sequences. That means if you're using `LT(3, KC_A)`, it will pick this up as `KC_A` for the sequence, rather than `LT(3, KC_A)`, giving a more expected behavior for newer users.
+
+While, this may be fine for most, if you want to specify the whole keycode (eg, `LT(3, KC_A)` from the example above) in the sequence, you can enable this by added `#define LEADER_KEY_STRICT_KEY_PROCESSING` to your `config.h` file.  This well then disable the filtering, and you'll need to specify the whole keycode.
+
+## Customization 
+
+The Leader Key feature has some additional customization to how the Leader Key feature works.  It has two functions that can be called at certain parts of the process.  Namely `leader_start()` and `leader_end()`.
+
+The `leader_start()` function is called when you tap the `KC_LEAD` key, and the `leader_end()` function is called when either the leader sequence is completed, or the leader timeout is hit. 
+
+You can add these functions to your code (`keymap.c` usually) to add feedback to the Leader sequences (such as beeping or playing music).
+
+```c
+void leader_start(void) {
+  // sequence started
+}
+
+void leader_end(void) {
+  // sequence ended (no success/failuer detection)
+}
+```
+
+### Example
+
+This example will play the Mario "One Up" sound when you hit `KC_LEAD` to start the Leader Sequence, and will play "All Star" if it completes successfully or "Rick Roll" you if it fails. 
+
+```c
+bool did_leader_succeed;
+#ifdef AUDIO_ENABLE
+float leader_start[][2] = SONG(ONE_UP_SOUND );
+float leader_succeed[][2] = SONG(ALL_STAR);
+float leader_fail[][2] = SONG(RICK_ROLL);
+#endif
+LEADER_EXTERNS();
+
+void matrix_scan_user(void) {
+  LEADER_DICTIONARY() {
+    did_leader_succeed = leading = false;
+
+    SEQ_ONE_KEY(KC_E) {
+      // Anything you can do in a macro.
+      SEND_STRING(SS_LCTRL(SS_LSFT("t")));
+      did_leader_succeed = true;
+    } else 
+    SEQ_TWO_KEYS(KC_E, KC_D) {
+      SEND_STRING(SS_LGUI("r")"cmd"SS_TAP(KC_ENTER)SS_LCTRL("c"));
+      did_leader_succeed = true;
+    }
+    leader_end();
+  }
+}
+
+void leader_start(void) {
+#ifdef AUDIO_ENABLE
+    PLAY_SONG(leader_start);
+#endif
+}
+
+void leader_end(void) {
+  if (did_leader_succeed) {
+#ifdef AUDIO_ENABLE
+    PLAY_SONG(leader_succeed);
+#endif
+  } else {
+#ifdef AUDIO_ENABLE
+    PLAY_SONG(leader_fail);
+#endif
+  }
+}
+```

docs/feature_led_matrix.md

@@ -0,0 +1,90 @@
+# LED Matrix Lighting
+
+This feature allows you to use LED matrices driven by external drivers. It hooks into the backlight system so you can use the same keycodes as backlighting to control it.
+
+If you want to use RGB LED's you should use the [RGB Matrix Subsystem](feature_rgb_matrix.md) instead.
+
+## Driver configuration
+
+### IS31FL3731
+
+There is basic support for addressable LED matrix lighting with the I2C IS31FL3731 RGB controller. To enable it, add this to your `rules.mk`:
+
+    LED_MATRIX_ENABLE = IS31FL3731
+    
+You can use between 1 and 4 IS31FL3731 IC's. Do not specify `LED_DRIVER_ADDR_<N>` defines for IC's that are not present on your keyboard. You can define the following items in `config.h`:
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `ISSI_TIMEOUT` | (Optional) How long to wait for i2c messages | 100 |
+| `ISSI_PERSISTENCE` | (Optional) Retry failed messages this many times | 0 |
+| `LED_DRIVER_COUNT` | (Required) How many LED driver IC's are present | |
+| `LED_DRIVER_LED_COUNT` | (Required) How many LED lights are present across all drivers | |
+| `LED_DRIVER_ADDR_1` | (Required) Address for the first LED driver | |
+| `LED_DRIVER_ADDR_2` | (Optional) Address for the second LED driver | |
+| `LED_DRIVER_ADDR_3` | (Optional) Address for the third LED driver | |
+| `LED_DRIVER_ADDR_4` | (Optional) Address for the fourth LED driver | |
+
+Here is an example using 2 drivers.
+
+	// This is a 7-bit address, that gets left-shifted and bit 0
+	// set to 0 for write, 1 for read (as per I2C protocol)
+	// The address will vary depending on your wiring:
+	// 0b1110100 AD <-> GND
+	// 0b1110111 AD <-> VCC
+	// 0b1110101 AD <-> SCL
+	// 0b1110110 AD <-> SDA
+	#define LED_DRIVER_ADDR_1 0b1110100
+	#define LED_DRIVER_ADDR_2 0b1110110
+
+	#define LED_DRIVER_COUNT 2
+	#define LED_DRIVER_1_LED_COUNT 25
+	#define LED_DRIVER_2_LED_COUNT 24
+	#define LED_DRIVER_LED_COUNT LED_DRIVER_1_LED_TOTAL + LED_DRIVER_2_LED_TOTAL
+
+Currently only 2 drivers are supported, but it would be trivial to support all 4 combinations.
+
+Define these arrays listing all the LEDs in your `<keyboard>.c`:
+
+	const is31_led g_is31_leds[DRIVER_LED_TOTAL] = {
+	/* Refer to IS31 manual for these locations
+	 *   driver
+	 *   |  LED address
+	 *   |  | */
+	    {0, C3_3},
+	    ....
+	}
+
+Where `Cx_y` is the location of the LED in the matrix defined by [the datasheet](http://www.issi.com/WW/pdf/31FL3731.pdf) and the header file `drivers/issi/is31fl3731-simple.h`. The `driver` is the index of the driver you defined in your `config.h` (`0`, `1`, `2`, or `3` ).
+
+## Keycodes
+
+All LED matrix keycodes are currently shared with the [backlight system](feature_backlight.md).
+
+## LED Matrix Effects
+
+Currently no LED matrix effects have been created.
+
+## Custom layer effects
+
+Custom layer effects can be done by defining this in your `<keyboard>.c`:
+
+    void led_matrix_indicators_kb(void) {
+        led_matrix_set_index_value(index, value);
+    }
+
+A similar function works in the keymap as `led_matrix_indicators_user`.
+
+## Suspended state
+
+To use the suspend feature, add this to your `<keyboard>.c`:
+
+	void suspend_power_down_kb(void)
+	{
+	    led_matrix_set_suspend_state(true);
+	}
+
+	void suspend_wakeup_init_kb(void)
+	{
+	    led_matrix_set_suspend_state(false);
+	}

docs/feature_macros.md

@@ -0,0 +1,339 @@
+# Macros
+
+Macros allow you to send multiple keystrokes when pressing just one key. QMK has a number of ways to define and use macros. These can do anything you want: type common phrases for you, copypasta, repetitive game movements, or even help you code.
+
+!> **Security Note**: While it is possible to use macros to send passwords, credit card numbers, and other sensitive information it is a supremely bad idea to do so. Anyone who gets a hold of your keyboard will be able to access that information by opening a text editor.
+
+## The New Way: `SEND_STRING()` & `process_record_user`
+
+Sometimes you just want a key to type out words or phrases. For the most common situations we've provided `SEND_STRING()`, which will type out your string (i.e. a sequence of characters) for you. All ASCII characters that are easily translated to a keycode are supported (e.g. `\n\t`).
+
+Here is an example `keymap.c` for a two-key keyboard:
+
+```c
+enum custom_keycodes {
+  QMKBEST = SAFE_RANGE,
+};
+
+bool process_record_user(uint16_t keycode, keyrecord_t *record) {
+  switch (keycode) {
+    case QMKBEST:
+      if (record->event.pressed) {
+        // when keycode QMKBEST is pressed
+        SEND_STRING("QMK is the best thing ever!");
+      } else {
+        // when keycode QMKBEST is released
+      }
+      break;
+
+  }
+  return true;
+};
+
+const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
+  [0] = {
+    {QMKBEST, KC_ESC}
+  }
+};
+```
+
+What happens here is this:
+We first define a new custom keycode in the range not occupied by any other keycodes.
+Then we use the `process_record_user` function, which is called whenever a key is pressed or released, to check if our custom keycode has been activated.
+If yes, we send the string `"QMK is the best thing ever!"` to the computer via the `SEND_STRING` macro (this is a C preprocessor macro, not to be confused with QMK macros).
+We return `true` to indicate to the caller that the key press we just processed should continue to be processed as normal (as we didn't replace or alter the functionality).
+Finally, we define the keymap so that the first button activates our macro and the second button is just an escape button.
+
+You might want to add more than one macro.
+You can do that by adding another keycode and adding another case to the switch statement, like so:
+
+```c
+enum custom_keycodes {
+  QMKBEST = SAFE_RANGE,
+  QMKURL,
+  MY_OTHER_MACRO
+};
+
+bool process_record_user(uint16_t keycode, keyrecord_t *record) {
+  switch (keycode) {
+    case QMKBEST:
+      if (record->event.pressed) {
+        // when keycode QMKBEST is pressed
+        SEND_STRING("QMK is the best thing ever!");
+      } else {
+        // when keycode QMKBEST is released
+      }
+      break;
+    case QMKURL:
+      if (record->event.pressed) {
+        // when keycode QMKURL is pressed
+        SEND_STRING("https://qmk.fm/" SS_TAP(X_ENTER));
+      } else {
+        // when keycode QMKURL is released
+      }
+      break;
+    case MY_OTHER_MACRO:
+      if (record->event.pressed) {
+                SEND_STRING(SS_LCTRL("ac")); // selects all and copies
+      }
+      break;
+  }
+  return true;
+};
+
+const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
+  [0] = {
+    {MY_CUSTOM_MACRO, MY_OTHER_MACRO}
+  }
+};
+```
+
+### TAP, DOWN and UP
+
+You may want to use keys in your macros that you can't write down, such as `Ctrl` or `Home`.
+You can send arbitrary keycodes by wrapping them in:
+
+* `SS_TAP()` presses and releases a key.
+* `SS_DOWN()` presses (but does not release) a key.
+* `SS_UP()` releases a key.
+
+For example:
+
+    SEND_STRING(SS_TAP(X_HOME));
+
+Would tap `KC_HOME` - note how the prefix is now `X_`, and not `KC_`. You can also combine this with other strings, like this:
+
+    SEND_STRING("VE"SS_TAP(X_HOME)"LO");
+
+Which would send "VE" followed by a `KC_HOME` tap, and "LO" (spelling "LOVE" if on a newline).
+
+There's also a couple of mod shortcuts you can use:
+
+* `SS_LCTRL(string)`
+* `SS_LGUI(string)`
+* `SS_LALT(string)`
+* `SS_LSFT(string)`
+* `SS_RALT(string)`
+
+These press the respective modifier, send the supplied string and then release the modifier.
+They can be used like this:
+
+    SEND_STRING(SS_LCTRL("a"));
+
+Which would send LCTRL+a (LCTRL down, a, LCTRL up) - notice that they take strings (eg `"k"`), and not the `X_K` keycodes.
+
+### Alternative Keymaps
+
+By default, it assumes a US keymap with a QWERTY layout; if you want to change that (e.g. if your OS uses software Colemak), include this somewhere in your keymap:
+
+    #include <sendstring_colemak.h>
+
+### Strings in Memory
+
+If for some reason you're manipulating strings and need to print out something you just generated (instead of being a literal, constant string), you can use `send_string()`, like this:
+
+```c
+char my_str[4] = "ok.";
+send_string(my_str);
+```
+
+The shortcuts defined above won't work with `send_string()`, but you can separate things out to different lines if needed:
+
+```c
+char my_str[4] = "ok.";
+SEND_STRING("I said: ");
+send_string(my_str);
+SEND_STRING(".."SS_TAP(X_END));
+```
+
+
+## Advanced Macro Functions
+
+There are some functions you may find useful in macro-writing. Keep in mind that while you can write some fairly advanced code within a macro, if your functionality gets too complex you may want to define a custom keycode instead. Macros are meant to be simple.
+
+### `record->event.pressed`
+
+This is a boolean value that can be tested to see if the switch is being pressed or released. An example of this is
+
+```c
+    if (record->event.pressed) {
+        // on keydown
+    } else {
+        // on keyup
+    }
+```
+
+### `register_code(<kc>);`
+
+This sends the `<kc>` keydown event to the computer. Some examples would be `KC_ESC`, `KC_C`, `KC_4`, and even modifiers such as `KC_LSFT` and `KC_LGUI`.
+
+### `unregister_code(<kc>);`
+
+Parallel to `register_code` function, this sends the `<kc>` keyup event to the computer. If you don't use this, the key will be held down until it's sent.
+
+### `tap_code(<kc>);`
+
+This will send `register_code(<kc>)` and then `unregister_code(<kc>)`. This is useful if you want to send both the press and release events ("tap" the key, rather than hold it).
+
+If you're having issues with taps (un)registering, you can add a delay between the register and unregister events by setting `#define TAP_CODE_DELAY 100` in your `config.h` file. The value is in milliseconds.
+
+### `register_code16(<kc>);`, `unregister_code16(<kc>);` and `tap_code16(<kc>);`
+
+These functions work similar to their regular counterparts, but allow you to use modded keycodes (with Shift, Alt, Control, and/or GUI applied to them).
+
+Eg, you could use `register_code16(S(KC_5));` instead of registering the mod, then registering the keycode.
+
+### `clear_keyboard();`
+
+This will clear all mods and keys currently pressed.
+
+### `clear_mods();`
+
+This will clear all mods currently pressed.
+
+### `clear_keyboard_but_mods();`
+
+This will clear all keys besides the mods currently pressed.
+
+## Advanced Example: 
+
+### Super ALT↯TAB
+
+This macro will register `KC_LALT` and tap `KC_TAB`, then wait for 1000ms. If the key is tapped again, it will send another `KC_TAB`; if there is no tap, `KC_LALT` will be unregistered, thus allowing you to cycle through windows. 
+
+```c
+bool is_alt_tab_active = false;    # ADD this near the begining of keymap.c
+uint16_t alt_tab_timer = 0;        # we will be using them soon.
+
+enum custom_keycodes {             # Make sure have the awesome keycode ready
+  ALT_TAB = SAFE_RANGE,
+};
+
+bool process_record_user(uint16_t keycode, keyrecord_t *record) {
+  switch (keycode) {               # This will do most of the grunt work with the keycodes.
+    case ALT_TAB:
+      if (record->event.pressed) {
+        if (!is_alt_tab_active) {
+          is_alt_tab_active = true;
+          register_code(KC_LALT);
+        } 
+        alt_tab_timer = timer_read();
+        register_code(KC_TAB);
+      } else {
+        unregister_code(KC_TAB);
+      }
+      break;
+  }
+  return true;
+}
+
+void matrix_scan_user(void) {     # The very important timer. 
+  if (is_alt_tab_active) {
+    if (timer_elapsed(alt_tab_timer) > 1000) {
+      unregister_code(KC_LALT);
+      is_alt_tab_active = false;
+    }
+  }
+}
+```
+
+---
+
+##  **(DEPRECATED)** The Old Way: `MACRO()` & `action_get_macro`
+
+!> This is inherited from TMK, and hasn't been updated - it's recommended that you use `SEND_STRING` and `process_record_user` instead.
+
+By default QMK assumes you don't have any macros. To define your macros you create an `action_get_macro()` function. For example:
+
+```c
+const macro_t *action_get_macro(keyrecord_t *record, uint8_t id, uint8_t opt) {
+    if (record->event.pressed) {
+        switch(id) {
+            case 0:
+                return MACRO(D(LSFT), T(H), U(LSFT), T(I), D(LSFT), T(1), U(LSFT), END);
+            case 1:
+                return MACRO(D(LSFT), T(B), U(LSFT), T(Y), T(E), D(LSFT), T(1), U(LSFT), END);
+        }
+    }
+    return MACRO_NONE;
+};
+```
+
+This defines two macros which will be run when the key they are assigned to is pressed. If instead you'd like them to run when the key is released you can change the if statement:
+
+    if (!record->event.pressed) {
+
+### Macro Commands
+
+A macro can include the following commands:
+
+* I() change interval of stroke in milliseconds.
+* D() press key.
+* U() release key.
+* T() type key(press and release).
+* W() wait (milliseconds).
+* END end mark.
+
+### Mapping a Macro to a Key
+
+Use the `M()` function within your keymap to call a macro. For example, here is the keymap for a 2-key keyboard:
+
+```c
+const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
+    [0] = LAYOUT(
+        M(0), M(1)
+    ),
+};
+
+const macro_t *action_get_macro(keyrecord_t *record, uint8_t id, uint8_t opt) {
+    if (record->event.pressed) {
+        switch(id) {
+            case 0:
+                return MACRO(D(LSFT), T(H), U(LSFT), T(I), D(LSFT), T(1), U(LSFT), END);
+            case 1:
+                return MACRO(D(LSFT), T(B), U(LSFT), T(Y), T(E), D(LSFT), T(1), U(LSFT), END);
+        }
+    }
+    return MACRO_NONE;
+};
+```
+
+When you press the key on the left it will type "Hi!" and when you press the key on the right it will type "Bye!".
+
+### Naming Your Macros
+
+If you have a bunch of macros you want to refer to from your keymap while keeping the keymap easily readable you can name them using `#define` at the top of your file.
+
+```c
+#define M_HI M(0)
+#define M_BYE M(1)
+
+const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
+    [0] = LAYOUT(
+        M_HI, M_BYE
+    ),
+};
+```
+
+
+## Advanced Example: 
+
+### Single-Key Copy/Paste
+
+This example defines a macro which sends `Ctrl-C` when pressed down, and `Ctrl-V` when released.
+
+```c
+const macro_t *action_get_macro(keyrecord_t *record, uint8_t id, uint8_t opt) {
+    switch(id) {
+        case 0: {
+            if (record->event.pressed) {
+                return MACRO( D(LCTL), T(C), U(LCTL), END  );
+            } else {
+                return MACRO( D(LCTL), T(V), U(LCTL), END  );
+            }
+            break;
+        }
+    }
+    return MACRO_NONE;
+};
+```

docs/feature_mouse_keys.md

@@ -0,0 +1,119 @@
+# Mouse keys
+
+Mouse keys is a feature that allows you to emulate a mouse using your keyboard. You can move the pointer at different speeds, press 5 buttons and scroll in 8 directions.
+
+## Adding mouse keys to your keyboard
+
+To use mouse keys, you must at least enable mouse keys support and map mouse actions to keys on your keyboard.
+
+### Enabling mouse keys
+
+To enable mouse keys, add the following line to your keymap’s `rules.mk`:
+
+```c
+MOUSEKEY_ENABLE = yes
+```
+
+### Mapping mouse actions
+
+In your keymap you can use the following keycodes to map key presses to mouse actions:
+
+|Key             |Aliases  |Description      |
+|----------------|---------|-----------------|
+|`KC_MS_UP`      |`KC_MS_U`|Move cursor up   |
+|`KC_MS_DOWN`    |`KC_MS_D`|Move cursor down |
+|`KC_MS_LEFT`    |`KC_MS_L`|Move cursor left |
+|`KC_MS_RIGHT`   |`KC_MS_R`|Move cursor right|
+|`KC_MS_BTN1`    |`KC_BTN1`|Press button 1   |
+|`KC_MS_BTN2`    |`KC_BTN2`|Press button 2   |
+|`KC_MS_BTN3`    |`KC_BTN3`|Press button 3   |
+|`KC_MS_BTN4`    |`KC_BTN4`|Press button 4   |
+|`KC_MS_BTN5`    |`KC_BTN5`|Press button 5   |
+|`KC_MS_WH_UP`   |`KC_WH_U`|Move wheel up    |
+|`KC_MS_WH_DOWN` |`KC_WH_D`|Move wheel down  |
+|`KC_MS_WH_LEFT` |`KC_WH_L`|Move wheel left  |
+|`KC_MS_WH_RIGHT`|`KC_WH_R`|Move wheel right |
+|`KC_MS_ACCEL0`  |`KC_ACL0`|Set speed to 0   |
+|`KC_MS_ACCEL1`  |`KC_ACL1`|Set speed to 1   |
+|`KC_MS_ACCEL2`  |`KC_ACL2`|Set speed to 2   |
+
+## Configuring mouse keys
+
+Mouse keys supports two different modes to move the cursor:
+
+* **Accelerated (default):** Holding movement keys accelerates the cursor until it reaches its maximum speed.
+* **Constant:** Holding movement keys moves the cursor at constant speeds.
+
+The same principle applies to scrolling.
+
+Configuration options that are times, intervals or delays are given in milliseconds. Scroll speed is given as multiples of the default scroll step. For example, a scroll speed of 8 means that each scroll action covers 8 times the length of the default scroll step as defined by your operating system or application.
+
+### Accelerated mode
+
+This is the default mode. You can adjust the cursor and scrolling acceleration using the following settings in your keymap’s `config.h` file:
+
+|Define                      |Default|Description                                              |
+|----------------------------|-------|---------------------------------------------------------|
+|`MOUSEKEY_DELAY`            |300    |Delay between pressing a movement key and cursor movement|
+|`MOUSEKEY_INTERVAL`         |50     |Time between cursor movements                            |
+|`MOUSEKEY_MAX_SPEED`        |10     |Maximum cursor speed at which acceleration stops         |
+|`MOUSEKEY_TIME_TO_MAX`      |20     |Time until maximum cursor speed is reached               |
+|`MOUSEKEY_WHEEL_MAX_SPEED`  |8      |Maximum number of scroll steps per scroll action         |
+|`MOUSEKEY_WHEEL_TIME_TO_MAX`|40     |Time until maximum scroll speed is reached               |
+
+Tips:
+
+* Setting `MOUSEKEY_DELAY` too low makes the cursor unresponsive. Setting it too high makes small movements difficult.
+* For smoother cursor movements, lower the value of `MOUSEKEY_INTERVAL`. If the refresh rate of your display is 60Hz, you could set it to `16` (1/60). As this raises the cursor speed significantly, you may want to lower `MOUSEKEY_MAX_SPEED`.
+* Setting `MOUSEKEY_TIME_TO_MAX` or `MOUSEKEY_WHEEL_TIME_TO_MAX` to `0` will disable acceleration for the cursor or scrolling respectively. This way you can make one of them constant while keeping the other accelerated, which is not possible in constant speed mode.
+
+Cursor acceleration uses the same algorithm as the X Window System MouseKeysAccel feature. You can read more about it [on Wikipedia](https://en.wikipedia.org/wiki/Mouse_keys).
+
+### Constant mode
+
+In this mode you can define multiple different speeds for both the cursor and the mouse wheel. There is no acceleration. `KC_ACL0`, `KC_ACL1` and `KC_ACL2` change the cursor and scroll speed to their respective setting.
+
+You can choose whether speed selection is momentary or tap-to-select:
+
+* **Momentary:** The chosen speed is only active while you hold the respective key. When the key is raised, mouse keys returns to the unmodified speed.
+* **Tap-to-select:** The chosen speed is activated when you press the respective key and remains active even after the key has been raised. The default speed is that of `KC_ACL1`. There is no unmodified speed.
+
+The default speeds from slowest to fastest are as follows:
+
+* **Momentary:** `KC_ACL0` < `KC_ACL1` < *unmodified* < `KC_ACL2`
+* **Tap-to-select:** `KC_ACL0` < `KC_ACL1` < `KC_ACL2`
+
+To use constant speed mode, you must at least define `MK_3_SPEED` in your keymap’s `config.h` file:
+
+```c
+#define MK_3_SPEED
+```
+
+To enable momentary mode, also define `MK_MOMENTARY_ACCEL`:
+
+```c
+#define MK_MOMENTARY_ACCEL
+```
+
+Use the following settings if you want to adjust cursor movement or scrolling:
+
+|Define               |Default      |Description                                |
+|---------------------|-------------|-------------------------------------------|
+|`MK_3_SPEED`         |*Not defined*|Enable constant cursor speeds              |
+|`MK_MOMENTARY_ACCEL` |*Not defined*|Enable momentary speed selection           |
+|`MK_C_OFFSET_UNMOD`  |16           |Cursor offset per movement (unmodified)    |
+|`MK_C_INTERVAL_UNMOD`|16           |Time between cursor movements (unmodified) |
+|`MK_C_OFFSET_0`      |1            |Cursor offset per movement (`KC_ACL0`)     |
+|`MK_C_INTERVAL_0`    |32           |Time between cursor movements (`KC_ACL0`)  |
+|`MK_C_OFFSET_1`      |4            |Cursor offset per movement (`KC_ACL1`)     |
+|`MK_C_INTERVAL_1`    |16           |Time between cursor movements (`KC_ACL1`)  |
+|`MK_C_OFFSET_2`      |32           |Cursor offset per movement (`KC_ACL2`)     |
+|`MK_C_INTERVAL_2`    |16           |Time between cursor movements (`KC_ACL2`)  |
+|`MK_W_OFFSET_UNMOD`  |1            |Scroll steps per scroll action (unmodified)|
+|`MK_W_INTERVAL_UNMOD`|40           |Time between scroll steps (unmodified)     |
+|`MK_W_OFFSET_0`      |1            |Scroll steps per scroll action (`KC_ACL0`) |
+|`MK_W_INTERVAL_0`    |360          |Time between scroll steps (`KC_ACL0`)      |
+|`MK_W_OFFSET_1`      |1            |Scroll steps per scroll action (`KC_ACL1`) |
+|`MK_W_INTERVAL_1`    |120          |Time between scroll steps (`KC_ACL1`)      |
+|`MK_W_OFFSET_2`      |1            |Scroll steps per scroll action (`KC_ACL2`) |
+|`MK_W_INTERVAL_2`    |20           |Time between scroll steps (`KC_ACL2`)      |

docs/feature_oled_driver.md

@@ -0,0 +1,291 @@
+# OLED Driver
+
+## OLED Supported Hardware
+
+OLED modules using SSD1306 or SH1106 driver ICs, communicating over I2C.
+Tested combinations:
+
+| IC driver |   Size | Keyboard Platform | Notes                    |
+|-----------|--------|-------------------|--------------------------|
+| SSD1306   | 128x32 | AVR               | Primary support          |
+| SSD1306   | 128x64 | AVR               | Verified working         |
+| SSD1306   | 128x32 | ARM               |                          |
+| SH1106    | 128x64 | AVR               | No rotation or scrolling |
+
+Hardware configurations using ARM-based microcontrollers or different sizes of OLED modules may be compatible, but are untested.
+
+!> Warning: This OLED Driver currently uses the new i2c_master driver from split common code. If your split keyboard uses I2C to communicate between sides, this driver could cause an address conflict (serial is fine). Please contact your keyboard vendor and ask them to migrate to the latest split common code to fix this. In addition, the display timeout system to reduce OLED burn-in also uses split common to detect keypresses, so you will need to implement custom timeout logic for non-split common keyboards.
+
+## Usage
+
+To enable the OLED feature, there are three steps. First, when compiling your keyboard, you'll need to set `OLED_DRIVER_ENABLE=yes` in `rules.mk`, e.g.:
+
+```
+OLED_DRIVER_ENABLE = yes
+```
+
+This enables the feature and the `OLED_DRIVER_ENABLE` define. Then in your `keymap.c` file, you will need to implement the user task call, e.g:
+
+```C++
+#ifdef OLED_DRIVER_ENABLE
+void oled_task_user(void) {
+  // Host Keyboard Layer Status
+  oled_write_P(PSTR("Layer: "), false);
+  switch (get_highest_layer(layer_state)) {
+    case _QWERTY:
+      oled_write_P(PSTR("Default\n"), false);
+      break;
+    case _FN:
+      oled_write_P(PSTR("FN\n"), false);
+      break;
+    case _ADJ:
+      oled_write_P(PSTR("ADJ\n"), false);
+      break;
+    default:
+      // Or use the write_ln shortcut over adding '\n' to the end of your string
+      oled_write_ln_P(PSTR("Undefined"), false);
+  }
+
+  // Host Keyboard LED Status
+  uint8_t led_usb_state = host_keyboard_leds();
+  oled_write_P(led_usb_state & (1<<USB_LED_NUM_LOCK) ? PSTR("NUMLCK ") : PSTR("       "), false);
+  oled_write_P(led_usb_state & (1<<USB_LED_CAPS_LOCK) ? PSTR("CAPLCK ") : PSTR("       "), false);
+  oled_write_P(led_usb_state & (1<<USB_LED_SCROLL_LOCK) ? PSTR("SCRLCK ") : PSTR("       "), false);
+}
+#endif
+```
+
+## Logo Example
+
+In the default font, ranges in the font file are reserved for a QMK Logo. To Render this logo to the oled screen, use the following code example:
+
+```C++
+static void render_logo(void) {
+  static const char PROGMEM qmk_logo[] = {
+    0x80,0x81,0x82,0x83,0x84,0x85,0x86,0x87,0x88,0x89,0x8a,0x8b,0x8c,0x8d,0x8e,0x8f,0x90,0x91,0x92,0x93,0x94,
+    0xa0,0xa1,0xa2,0xa3,0xa4,0xa5,0xa6,0xa7,0xa8,0xa9,0xaa,0xab,0xac,0xad,0xae,0xaf,0xb0,0xb1,0xb2,0xb3,0xb4,
+    0xc0,0xc1,0xc2,0xc3,0xc4,0xc5,0xc6,0xc7,0xc8,0xc9,0xca,0xcb,0xcc,0xcd,0xce,0xcf,0xd0,0xd1,0xd2,0xd3,0xd4,0};
+
+  oled_write_P(qmk_logo, false);
+}
+```
+
+## Other Examples
+
+In split keyboards, it is very common to have two OLED displays that each render different content and oriented flipped differently. You can do this by switching which content to render by using the return from `is_keyboard_master()` or `is_keyboard_left()` found in `split_util.h`, e.g:
+
+```C++
+#ifdef OLED_DRIVER_ENABLE
+oled_rotation_t oled_init_user(oled_rotation_t rotation) {
+  if (!is_keyboard_master())
+    return OLED_ROTATION_180;  // flips the display 180 degrees if offhand
+  return rotation;
+}
+
+void oled_task_user(void) {
+  if (is_keyboard_master()) {
+    render_status();     // Renders the current keyboard state (layer, lock, caps, scroll, etc)
+  } else {
+    render_logo();       // Renders a statuc logo
+    oled_scroll_left();  // Turns on scrolling
+  }
+}
+#endif
+```
+
+
+ ## Basic Configuration
+
+| Define                     | Default           | Description                                                                                                                |
+|----------------------------|-------------------|----------------------------------------------------------------------------------------------------------------------------|
+| `OLED_DISPLAY_ADDRESS`     | `0x3C`            | The i2c address of the OLED Display                                                                                        |
+| `OLED_FONT_H`              | `"glcdfont.c"`    | The font code file to use for custom fonts                                                                                 |
+| `OLED_FONT_START`          | `0`               | The starting characer index for custom fonts                                                                               |
+| `OLED_FONT_END`            | `224`             | The ending characer index for custom fonts                                                                                 |
+| `OLED_FONT_WIDTH`          | `6`               | The font width                                                                                                             |
+| `OLED_FONT_HEIGHT`         | `8`               | The font height (untested)                                                                                                 |
+| `OLED_TIMEOUT`             | `60000`           | Turns off the OLED screen after 60000ms of keyboard inactivity. Helps reduce OLED Burn-in. Set to 0 to disable.            |
+| `OLED_SCROLL_TIMEOUT`      | `0`               | Scrolls the OLED screen after 0ms of OLED inactivity. Helps reduce OLED Burn-in. Set to 0 to disable.                      |
+| `OLED_SCROLL_TIMEOUT_RIGHT`| *Not defined*     | Scroll timeout direction is right when defined, left when undefined.                                                       |
+| `OLED_IC`                  | `OLED_IC_SSD1306` | Set to `OLED_IC_SH1106` if you're using the SH1106 OLED controller.                                                        |
+| `OLED_COLUMN_OFFSET`       | `0`               | (SH1106 only.) Shift output to the right this many pixels.<br />Useful for 128x64 displays centered on a 132x64 SH1106 IC. |
+
+ ## 128x64 & Custom sized OLED Displays
+
+ The default display size for this feature is 128x32 and all necessary defines are precalculated with that in mind. We have added a define, `OLED_DISPLAY_128X64`, to switch all the values to be used in a 128x64 display, as well as added a custom define, `OLED_DISPLAY_CUSTOM`, that allows you to provide the necessary values to the driver.
+
+|Define                 |Default        |Description                                                      |
+|-----------------------|---------------|-----------------------------------------------------------------|
+|`OLED_DISPLAY_128X64`  |*Not defined*  |Changes the display defines for use with 128x64 displays.        |
+|`OLED_DISPLAY_CUSTOM`  |*Not defined*  |Changes the display defines for use with custom displays.<br />Requires user to implement the below defines. |
+|`OLED_DISPLAY_WIDTH`   |`128`          |The width of the OLED display.                                   |
+|`OLED_DISPLAY_HEIGHT`  |`32`           |The height of the OLED display.                                  |
+|`OLED_MATRIX_SIZE`     |`512`          |The local buffer size to allocate.<br />`(OLED_DISPLAY_HEIGHT / 8 * OLED_DISPLAY_WIDTH)`. |
+|`OLED_BLOCK_TYPE`      |`uint16_t`     |The unsigned integer type to use for dirty rendering. |
+|`OLED_BLOCK_COUNT`     |`16`           |The number of blocks the display is divided into for dirty rendering.<br />`(sizeof(OLED_BLOCK_TYPE) * 8)`. |
+|`OLED_BLOCK_SIZE`      |`32`           |The size of each block for dirty rendering<br />`(OLED_MATRIX_SIZE / OLED_BLOCK_COUNT)`. |
+|`OLED_COM_PINS`        |`COM_PINS_SEQ` |How the SSD1306 chip maps it's memory to display.<br />Options are `COM_PINS_SEQ`, `COM_PINS_ALT`, `COM_PINS_SEQ_LR`, & `COM_PINS_ALT_LR`. |
+|`OLED_SOURCE_MAP`      |`{ 0, ... N }` |Precalculated source array to use for mapping source buffer to target OLED memory in 90 degree rendering.         |
+|`OLED_TARGET_MAP`      |`{ 24, ... N }`|Precalculated target array to use for mapping source buffer to target OLED memory in 90 degree rendering.         |
+
+
+### 90 Degree Rotation - Technical Mumbo Jumbo 
+
+!> Rotation is unsupported on the SH1106.
+
+```C
+// OLED Rotation enum values are flags
+typedef enum {
+    OLED_ROTATION_0   = 0,
+    OLED_ROTATION_90  = 1,
+    OLED_ROTATION_180 = 2,
+    OLED_ROTATION_270 = 3, // OLED_ROTATION_90 | OLED_ROTATION_180
+} oled_rotation_t;
+```
+
+ OLED displays driven by SSD1306 drivers only natively support in hard ware 0 degree and 180 degree rendering. This feature is done in software and not free. Using this feature will increase the time to calculate what data to send over i2c to the OLED. If you are strapped for cycles, this can cause keycodes to not register. In testing however, the rendering time on an `atmega32u4` board only went from 2ms to 5ms and keycodes not registering was only noticed once we hit 15ms. 
+ 
+ 90 Degree Rotated Rendering is achieved by using bitwise operations to rotate each 8 block of memory and uses two precalculated arrays to remap buffer memory to OLED memory. The memory map defines are precalculated for remap performance and are calculated based on the OLED Height, Width, and Block Size. For example, in the 128x32 implementation with a `uint8_t` block type, we have a 64 byte block size. This gives us eight 8 byte blocks that need to be rotated and rendered. The OLED renders horizontally two 8 byte blocks before moving down a page, e.g:
+
+|   |   |   |   |   |   |
+|---|---|---|---|---|---|
+| 0 | 1 |   |   |   |   |
+| 2 | 3 |   |   |   |   |
+| 4 | 5 |   |   |   |   |
+| 6 | 7 |   |   |   |   |
+
+However the local buffer is stored as if it was Height x Width display instead of Width x Height, e.g:
+
+|   |   |   |   |   |   |
+|---|---|---|---|---|---|
+| 3 | 7 |   |   |   |   |
+| 2 | 6 |   |   |   |   |
+| 1 | 5 |   |   |   |   |
+| 0 | 4 |   |   |   |   |
+
+So those precalculated arrays just index the memory offsets in the order in which each one iterates its data.
+
+## OLED API
+
+```C++
+// OLED Rotation enum values are flags
+typedef enum {
+    OLED_ROTATION_0   = 0,
+    OLED_ROTATION_90  = 1,
+    OLED_ROTATION_180 = 2,
+    OLED_ROTATION_270 = 3, // OLED_ROTATION_90 | OLED_ROTATION_180
+} oled_rotation_t;
+
+// Initialize the OLED display, rotating the rendered output based on the define passed in.
+// Returns true if the OLED was initialized successfully
+bool oled_init(oled_rotation_t rotation);
+
+// Called at the start of oled_init, weak function overridable by the user
+// rotation - the value passed into oled_init
+// Return new oled_rotation_t if you want to override default rotation
+oled_rotation_t oled_init_user(oled_rotation_t rotation);
+
+// Clears the display buffer, resets cursor position to 0, and sets the buffer to dirty for rendering
+void oled_clear(void);
+
+// Renders the dirty chunks of the buffer to OLED display
+void oled_render(void);
+
+// Moves cursor to character position indicated by column and line, wraps if out of bounds
+// Max column denoted by 'oled_max_chars()' and max lines by 'oled_max_lines()' functions
+void oled_set_cursor(uint8_t col, uint8_t line);
+
+// Advances the cursor to the next page, writing ' ' if true
+// Wraps to the begining when out of bounds
+void oled_advance_page(bool clearPageRemainder);
+
+// Moves the cursor forward 1 character length
+// Advance page if there is not enough room for the next character
+// Wraps to the begining when out of bounds
+void oled_advance_char(void);
+
+// Writes a single character to the buffer at current cursor position
+// Advances the cursor while writing, inverts the pixels if true
+// Main handler that writes character data to the display buffer
+void oled_write_char(const char data, bool invert);
+
+// Writes a string to the buffer at current cursor position
+// Advances the cursor while writing, inverts the pixels if true
+void oled_write(const char *data, bool invert);
+
+// Writes a string to the buffer at current cursor position
+// Advances the cursor while writing, inverts the pixels if true
+// Advances the cursor to the next page, wiring ' ' to the remainder of the current page
+void oled_write_ln(const char *data, bool invert);
+
+// Writes a PROGMEM string to the buffer at current cursor position
+// Advances the cursor while writing, inverts the pixels if true
+// Remapped to call 'void oled_write(const char *data, bool invert);' on ARM
+void oled_write_P(const char *data, bool invert);
+
+// Writes a PROGMEM string to the buffer at current cursor position
+// Advances the cursor while writing, inverts the pixels if true
+// Advances the cursor to the next page, wiring ' ' to the remainder of the current page
+// Remapped to call 'void oled_write_ln(const char *data, bool invert);' on ARM
+void oled_write_ln_P(const char *data, bool invert);
+
+// Can be used to manually turn on the screen if it is off
+// Returns true if the screen was on or turns on
+bool oled_on(void);
+
+// Can be used to manually turn off the screen if it is on
+// Returns true if the screen was off or turns off
+bool oled_off(void);
+
+// Basically it's oled_render, but with timeout management and oled_task_user calling!
+void oled_task(void);
+
+// Called at the start of oled_task, weak function overridable by the user
+void oled_task_user(void);
+
+// Scrolls the entire display right
+// Returns true if the screen was scrolling or starts scrolling
+// NOTE: display contents cannot be changed while scrolling
+bool oled_scroll_right(void);
+
+// Scrolls the entire display left
+// Returns true if the screen was scrolling or starts scrolling
+// NOTE: display contents cannot be changed while scrolling
+bool oled_scroll_left(void);
+
+// Turns off display scrolling
+// Returns true if the screen was not scrolling or stops scrolling
+bool oled_scroll_off(void);
+
+// Returns the maximum number of characters that will fit on a line
+uint8_t oled_max_chars(void);
+
+// Returns the maximum number of lines that will fit on the OLED
+uint8_t oled_max_lines(void);
+```
+
+!> Scrolling and rotation are unsupported on the SH1106.
+
+## SSD1306.h driver conversion guide
+
+|Old API                    |Recommended New API                |
+|---------------------------|-----------------------------------|
+|`struct CharacterMatrix`   |*removed - delete all references*  |
+|`iota_gfx_init`            |`oled_init`                        |
+|`iota_gfx_on`              |`oled_on`                          |
+|`iota_gfx_off`             |`oled_off`                         |
+|`iota_gfx_flush`           |`oled_render`                      |
+|`iota_gfx_write_char`      |`oled_write_char`                  |
+|`iota_gfx_write`           |`oled_write`                       |
+|`iota_gfx_write_P`         |`oled_write_P`                     |
+|`iota_gfx_clear_screen`    |`oled_clear`                       |
+|`matrix_clear`             |*removed - delete all references*  |
+|`matrix_write_char_inner`  |`oled_write_char`                  |
+|`matrix_write_char`        |`oled_write_char`                  |
+|`matrix_write`             |`oled_write`                       |
+|`matrix_write_ln`          |`oled_write_ln`                    |
+|`matrix_write_P`           |`oled_write_P`                     |
+|`matrix_write_ln_P`        |`oled_write_ln_P`                  |
+|`matrix_render`            |`oled_render`                      |
+|`iota_gfx_task`            |`oled_task`                        |
+|`iota_gfx_task_user`       |`oled_task_user`                   |

docs/feature_pointing_device.md

@@ -0,0 +1,47 @@
+## Pointing Device
+
+Pointing Device is a generic name for a feature intended to be generic: moving the system pointer around.  There are certainly other options for it - like mousekeys - but this aims to be easily modifiable and lightweight.  You can implement custom keys to control functionality, or you can gather information from other peripherals and insert it directly here - let QMK handle the processing for you.
+
+To enable Pointing Device, uncomment the following line in your rules.mk:
+
+```
+POINTING_DEVICE_ENABLE = yes
+```
+
+To manipulate the mouse report, you can use the following functions:
+
+* `pointing_device_get_report()` - Returns the current report_mouse_t that represents the information sent to the host computer
+* `pointing_device_set_report(report_mouse_t newMouseReport)` - Overrides and saves the report_mouse_t to be sent to the host computer
+
+Keep in mind that a report_mouse_t (here "mouseReport") has the following properties:
+
+* `mouseReport.x` - this is a signed int from -127 to 127 (not 128, this is defined in USB HID spec) representing movement (+ to the right, - to the left) on the x axis.
+* `mouseReport.y` - this is a signed int from -127 to 127 (not 128, this is defined in USB HID spec) representing movement (+ upward, - downward) on the y axis.
+* `mouseReport.v` - this is a signed int from -127 to 127 (not 128, this is defined in USB HID spec) representing vertical scrolling (+ upward, - downward).
+* `mouseReport.h` - this is a signed int from -127 to 127 (not 128, this is defined in USB HID spec) representing horizontal scrolling (+ right, - left).
+* `mouseReport.buttons` - this is a uint8_t in which the last 5 bits are used.  These bits represent the mouse button state - bit 3 is mouse button 5, and bit 7 is mouse button 1.
+
+When the mouse report is sent, the x, y, v, and h values are set to 0 (this is done in "pointing_device_send()", which can be overridden to avoid this behavior).  This way, button states persist, but movement will only occur once.  For further customization, both `pointing_device_init` and `pointing_device_task` can be overridden.
+
+In the following example, a custom key is used to click the mouse and scroll 127 units vertically and horizontally, then undo all of that when released - because that's a totally useful function.  Listen, this is an example:
+
+```
+case MS_SPECIAL:
+	report_mouse_t currentReport = pointing_device_get_report();
+    if (record->event.pressed)
+    {
+        currentReport.v = 127;
+		currentReport.h = 127;
+		currentReport.buttons |= MOUSE_BTN1; //this is defined in report.h
+    }
+    else
+    {
+        currentReport.v = -127;
+        currentReport.h = -127;
+        currentReport.buttons &= ~MOUSE_BTN1;
+    }
+	pointing_device_set_report(currentReport);
+    break;
+```
+
+Recall that the mouse report is set to zero (except the buttons) whenever it is sent, so the scrolling would only occur once in each case.

docs/feature_ps2_mouse.md

@@ -0,0 +1,276 @@
+## PS/2 Mouse Support
+
+Its possible to hook up a PS/2 mouse (for example touchpads or trackpoints) to your keyboard as a composite device.
+
+To hook up a Trackpoint, you need to obtain a Trackpoint module (i.e. harvest from a Thinkpad keyboard), identify the function of each pin of the module, and make the necessary circuitry between controller and Trackpoint module. For more information, please refer to [Trackpoint Hardware](https://deskthority.net/wiki/TrackPoint_Hardware) page on Deskthority Wiki.
+
+There are three available modes for hooking up PS/2 devices: USART (best), interrupts (better) or busywait (not recommended).
+
+### The Cirtuitry between Trackpoint and Controller
+
+To get the things working, a 4.7K drag is needed between the two lines DATA and CLK and the line 5+. 
+
+```
+
+          DATA ----------+--------- PIN
+                         |
+                        4.7K
+                         |
+MODULE    5+  --------+--+--------- PWR   CONTROLLER
+                      |
+                     4.7K
+                      |    
+          CLK   ------+------------ PIN
+```
+
+
+### Busywait Version
+
+Note: This is not recommended, you may encounter jerky movement or unsent inputs. Please use interrupt or USART version if possible.
+
+In rules.mk:
+
+```
+PS2_MOUSE_ENABLE = yes
+PS2_USE_BUSYWAIT = yes
+```
+
+In your keyboard config.h:
+
+```
+#ifdef PS2_USE_BUSYWAIT
+#   define PS2_CLOCK_PORT  PORTD
+#   define PS2_CLOCK_PIN   PIND
+#   define PS2_CLOCK_DDR   DDRD
+#   define PS2_CLOCK_BIT   1
+#   define PS2_DATA_PORT   PORTD
+#   define PS2_DATA_PIN    PIND
+#   define PS2_DATA_DDR    DDRD
+#   define PS2_DATA_BIT    2
+#endif
+```
+
+### Interrupt Version
+
+The following example uses D2 for clock and D5 for data. You can use any INT or PCINT pin for clock, and any pin for data.
+
+In rules.mk:
+
+```
+PS2_MOUSE_ENABLE = yes
+PS2_USE_INT = yes
+```
+
+In your keyboard config.h:
+
+```
+#ifdef PS2_USE_INT
+#define PS2_CLOCK_PORT  PORTD
+#define PS2_CLOCK_PIN   PIND
+#define PS2_CLOCK_DDR   DDRD
+#define PS2_CLOCK_BIT   2
+#define PS2_DATA_PORT   PORTD
+#define PS2_DATA_PIN    PIND
+#define PS2_DATA_DDR    DDRD
+#define PS2_DATA_BIT    5
+
+#define PS2_INT_INIT()  do {    \
+    EICRA |= ((1<<ISC21) |      \
+              (0<<ISC20));      \
+} while (0)
+#define PS2_INT_ON()  do {      \
+    EIMSK |= (1<<INT2);         \
+} while (0)
+#define PS2_INT_OFF() do {      \
+    EIMSK &= ~(1<<INT2);        \
+} while (0)
+#define PS2_INT_VECT   INT2_vect
+#endif
+```
+
+### USART Version
+
+To use USART on the ATMega32u4, you have to use PD5 for clock and PD2 for data. If one of those are unavailable, you need to use interrupt version.
+
+In rules.mk:
+
+```
+PS2_MOUSE_ENABLE = yes
+PS2_USE_USART = yes
+```
+
+In your keyboard config.h:
+
+```
+#ifdef PS2_USE_USART
+#define PS2_CLOCK_PORT  PORTD
+#define PS2_CLOCK_PIN   PIND
+#define PS2_CLOCK_DDR   DDRD
+#define PS2_CLOCK_BIT   5
+#define PS2_DATA_PORT   PORTD
+#define PS2_DATA_PIN    PIND
+#define PS2_DATA_DDR    DDRD
+#define PS2_DATA_BIT    2
+
+/* synchronous, odd parity, 1-bit stop, 8-bit data, sample at falling edge */
+/* set DDR of CLOCK as input to be slave */
+#define PS2_USART_INIT() do {   \
+    PS2_CLOCK_DDR &= ~(1<<PS2_CLOCK_BIT);   \
+    PS2_DATA_DDR &= ~(1<<PS2_DATA_BIT);     \
+    UCSR1C = ((1 << UMSEL10) |  \
+              (3 << UPM10)   |  \
+              (0 << USBS1)   |  \
+              (3 << UCSZ10)  |  \
+              (0 << UCPOL1));   \
+    UCSR1A = 0;                 \
+    UBRR1H = 0;                 \
+    UBRR1L = 0;                 \
+} while (0)
+#define PS2_USART_RX_INT_ON() do {  \
+    UCSR1B = ((1 << RXCIE1) |       \
+              (1 << RXEN1));        \
+} while (0)
+#define PS2_USART_RX_POLL_ON() do { \
+    UCSR1B = (1 << RXEN1);          \
+} while (0)
+#define PS2_USART_OFF() do {    \
+    UCSR1C = 0;                 \
+    UCSR1B &= ~((1 << RXEN1) |  \
+                (1 << TXEN1));  \
+} while (0)
+#define PS2_USART_RX_READY      (UCSR1A & (1<<RXC1))
+#define PS2_USART_RX_DATA       UDR1
+#define PS2_USART_ERROR         (UCSR1A & ((1<<FE1) | (1<<DOR1) | (1<<UPE1)))
+#define PS2_USART_RX_VECT       USART1_RX_vect
+#endif
+```
+
+### Additional Settings
+
+#### PS/2 Mouse Features
+
+These enable settings supported by the PS/2 mouse protocol.
+
+```
+/* Use remote mode instead of the default stream mode (see link) */
+#define PS2_MOUSE_USE_REMOTE_MODE
+
+/* Enable the scrollwheel or scroll gesture on your mouse or touchpad */
+#define PS2_MOUSE_ENABLE_SCROLLING
+
+/* Some mice will need a scroll mask to be configured. The default is 0xFF. */
+#define PS2_MOUSE_SCROLL_MASK 0x0F
+
+/* Applies a transformation to the movement before sending to the host (see link) */
+#define PS2_MOUSE_USE_2_1_SCALING
+
+/* The time to wait after initializing the ps2 host */
+#define PS2_MOUSE_INIT_DELAY 1000 /* Default */
+```
+
+You can also call the following functions from ps2_mouse.h
+
+```
+void ps2_mouse_disable_data_reporting(void);
+
+void ps2_mouse_enable_data_reporting(void);
+
+void ps2_mouse_set_remote_mode(void);
+
+void ps2_mouse_set_stream_mode(void);
+
+void ps2_mouse_set_scaling_2_1(void);
+
+void ps2_mouse_set_scaling_1_1(void);
+
+void ps2_mouse_set_resolution(ps2_mouse_resolution_t resolution);
+
+void ps2_mouse_set_sample_rate(ps2_mouse_sample_rate_t sample_rate);
+```
+
+#### Fine Control
+
+Use the following defines to change the sensitivity and speed of the mouse.
+Note: you can also use `ps2_mouse_set_resolution` for the same effect (not supported on most touchpads).
+
+```
+#define PS2_MOUSE_X_MULTIPLIER 3
+#define PS2_MOUSE_Y_MULTIPLIER 3
+#define PS2_MOUSE_V_MULTIPLIER 1
+```
+
+#### Scroll Button
+
+If you're using a trackpoint, you will likely want to be able to use it for scrolling.
+It's possible to enable a "scroll button/s" that when pressed will cause the mouse to scroll instead of moving.
+To enable the feature, you must set a scroll button mask as follows:
+
+```
+#define PS2_MOUSE_SCROLL_BTN_MASK (1<<PS2_MOUSE_BUTTON_MIDDLE) /* Default */
+```
+
+To disable the scroll button feature:
+
+```
+#define PS2_MOUSE_SCROLL_BTN_MASK 0
+```
+
+The available buttons are:
+
+```
+#define PS2_MOUSE_BTN_LEFT      0
+#define PS2_MOUSE_BTN_RIGHT     1
+#define PS2_MOUSE_BTN_MIDDLE    2
+```
+
+You can also combine buttons in the mask by `|`ing them together.
+
+Once you've configured your scroll button mask, you must configure the scroll button send interval.
+This is the interval before which if the scroll buttons were released they would be sent to the host.
+After this interval, they will cause the mouse to scroll and will not be sent.
+
+```
+#define PS2_MOUSE_SCROLL_BTN_SEND 300 /* Default */
+```
+
+To disable sending the scroll buttons:
+```
+#define PS2_MOUSE_SCROLL_BTN_SEND 0
+```
+
+Fine control over the scrolling is supported with the following defines:
+
+```
+#define PS2_MOUSE_SCROLL_DIVISOR_H 2
+#define PS2_MOUSE_SCROLL_DIVISOR_V 2
+```
+
+#### Invert Mouse and Scroll Axes
+
+To invert the X and Y axes you can put:
+
+```
+#define PS2_MOUSE_INVERT_X
+#define PS2_MOUSE_INVERT_Y
+```
+
+into config.h.
+
+To reverse the scroll axes you can put:
+
+```
+#define PS2_MOUSE_INVERT_H
+#define PS2_MOUSE_INVERT_V
+```
+
+into config.h.
+
+#### Debug Settings
+
+To debug the mouse, add `debug_mouse = true` or enable via bootmagic.
+
+```
+/* To debug the mouse reports */
+#define PS2_MOUSE_DEBUG_HID
+#define PS2_MOUSE_DEBUG_RAW
+```

docs/feature_rgb_matrix.md

@@ -0,0 +1,404 @@
+# RGB Matrix Lighting
+
+This feature allows you to use RGB LED matrices driven by external drivers. It hooks into the RGBLIGHT system so you can use the same keycodes as RGBLIGHT to control it.
+
+If you want to use single color LED's you should use the [LED Matrix Subsystem](feature_led_matrix.md) instead.
+
+## Driver configuration
+---
+### IS31FL3731
+
+There is basic support for addressable RGB matrix lighting with the I2C IS31FL3731 RGB controller. To enable it, add this to your `rules.mk`:
+
+```C
+RGB_MATRIX_ENABLE = IS31FL3731
+```
+
+Configure the hardware via your `config.h`:
+
+```C
+// This is a 7-bit address, that gets left-shifted and bit 0
+// set to 0 for write, 1 for read (as per I2C protocol)
+// The address will vary depending on your wiring:
+// 0b1110100 AD <-> GND
+// 0b1110111 AD <-> VCC
+// 0b1110101 AD <-> SCL
+// 0b1110110 AD <-> SDA
+#define DRIVER_ADDR_1 0b1110100
+#define DRIVER_ADDR_2 0b1110110
+
+#define DRIVER_COUNT 2
+#define DRIVER_1_LED_TOTAL 25
+#define DRIVER_2_LED_TOTAL 24
+#define DRIVER_LED_TOTAL (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL)
+```
+
+!> Note the parentheses, this is so when `DRIVER_LED_TOTAL` is used in code and expanded, the values are added together before any additional math is applied to them. As an example, `rand() % (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL)` will give very different results than `rand() % DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL`.
+
+Currently only 2 drivers are supported, but it would be trivial to support all 4 combinations.
+
+Define these arrays listing all the LEDs in your `<keyboard>.c`:
+
+```C
+const is31_led g_is31_leds[DRIVER_LED_TOTAL] = {
+/* Refer to IS31 manual for these locations
+ *   driver
+ *   |  R location
+ *   |  |      G location
+ *   |  |      |      B location
+ *   |  |      |      | */
+    {0, C1_3,  C2_3,  C3_3},
+    ....
+}
+```
+
+Where `Cx_y` is the location of the LED in the matrix defined by [the datasheet](http://www.issi.com/WW/pdf/31FL3731.pdf) and the header file `drivers/issi/is31fl3731.h`. The `driver` is the index of the driver you defined in your `config.h` (`0` or `1` right now).
+
+---
+###  IS31FL3733/IS31FL3737
+
+!> For the IS31FL3737, replace all instances of `IS31FL3733` below with `IS31FL3737`.
+
+There is basic support for addressable RGB matrix lighting with the I2C IS31FL3733 RGB controller. To enable it, add this to your `rules.mk`:
+
+```C
+RGB_MATRIX_ENABLE = IS31FL3733
+```
+
+Configure the hardware via your `config.h`:
+
+```C
+// This is a 7-bit address, that gets left-shifted and bit 0
+// set to 0 for write, 1 for read (as per I2C protocol)
+// The address will vary depending on your wiring:
+// 00 <-> GND
+// 01 <-> SCL
+// 10 <-> SDA
+// 11 <-> VCC
+// ADDR1 represents A1:A0 of the 7-bit address.
+// ADDR2 represents A3:A2 of the 7-bit address.
+// The result is: 0b101(ADDR2)(ADDR1)
+#define DRIVER_ADDR_1 0b1010000
+#define DRIVER_ADDR_2 0b1010000 // this is here for compliancy reasons.
+
+#define DRIVER_COUNT 2
+#define DRIVER_1_LED_TOTAL 64
+#define DRIVER_LED_TOTAL DRIVER_1_LED_TOTAL
+```
+
+Currently only a single drivers is supported, but it would be trivial to support all 4 combinations. For now define `DRIVER_ADDR_2` as `DRIVER_ADDR_1`
+
+Define these arrays listing all the LEDs in your `<keyboard>.c`:
+
+```C
+const is31_led g_is31_leds[DRIVER_LED_TOTAL] = {
+/* Refer to IS31 manual for these locations
+ *   driver
+ *   |  R location
+ *   |  |       G location
+ *   |  |       |       B location
+ *   |  |       |       | */
+    {0, B_1,    A_1,    C_1},
+    ....
+}
+```
+
+Where `X_Y` is the location of the LED in the matrix defined by [the datasheet](http://www.issi.com/WW/pdf/31FL3733.pdf) and the header file `drivers/issi/is31fl3733.h`. The `driver` is the index of the driver you defined in your `config.h` (Only `0` right now).
+
+---
+
+### WS2812 (AVR only)
+
+There is basic support for addressable RGB matrix lighting with a WS2811/WS2812{a,b,c} addressable LED strand. To enable it, add this to your `rules.mk`:
+
+```C
+RGB_MATRIX_ENABLE = WS2812
+```
+
+Configure the hardware via your `config.h`:
+
+```C
+// The pin connected to the data pin of the LEDs
+#define RGB_DI_PIN D7
+// The number of LEDs connected
+#define DRIVER_LED_TOTAL 70
+```
+
+---
+
+From this point forward the configuration is the same for all the drivers. The `led_config_t` struct provides a key electrical matrix to led index lookup table, what the physical position of each LED is on the board, and what type of key or usage the LED if the LED represents. Here is a brief example:
+
+```C
+const led_config_t g_led_config = { {
+  // Key Matrix to LED Index
+  {   5, NO_LED, NO_LED,   0 },
+  { NO_LED, NO_LED, NO_LED, NO_LED },
+  {   4, NO_LED, NO_LED,   1 },
+  {   3, NO_LED, NO_LED,   2 }
+}, {
+  // LED Index to Physical Position
+  { 188,  16 }, { 187,  48 }, { 149,  64 }, { 112,  64 }, {  37,  48 }, {  38,  16 }
+}, {
+  // LED Index to Flag
+  1, 4, 4, 4, 4, 1
+} };
+```
+
+The first part, `// Key Matrix to LED Index`, tells the system what key this LED represents by using the key's electrical matrix row & col. The second part, `// LED Index to Physical Position` represents the LED's physical `{ x, y }` position on the keyboard. The default expected range of values for `{ x, y }` is the inclusive range `{ 0..224, 0..64 }`. This default expected range is due to effects that calculate the center of the keyboard for their animations. The easiest way to calculate these positions is imagine your keyboard is a grid, and the top left of the keyboard represents `{ x, y }` coordinate `{ 0, 0 }` and the bottom right of your keyboard represents `{ 224, 64 }`. Using this as a basis, you can use the following formula to calculate the physical position:
+
+```C
+x = 224 / (NUMBER_OF_COLS - 1) * COL_POSITION
+y =  64 / (NUMBER_OF_ROWS - 1) * ROW_POSITION
+```
+
+Where NUMBER_OF_COLS, NUMBER_OF_ROWS, COL_POSITION, & ROW_POSITION are all based on the physical layout of your keyboard, not the electrical layout. 
+
+As mentioned earlier, the center of the keyboard by default is expected to be `{ 112, 32 }`, but this can be changed if you want to more accurately calculate the LED's physical `{ x, y }` positions. Keyboard designers can implement `#define RGB_MATRIX_CENTER { 112, 32 }` in their config.h file with the new center point of the keyboard, or where they want it to be allowing more possibilities for the `{ x, y }` values. Do note that the maximum value for x or y is 255, and the recommended maximum is 224 as this gives animations runoff room before they reset.
+
+`// LED Index to Flag` is a bitmask, whether or not a certain LEDs is of a certain type. It is recommended that LEDs are set to only 1 type.
+
+## Flags
+
+|Define                              |Description                                |
+|------------------------------------|-------------------------------------------|
+|`#define HAS_FLAGS(bits, flags)`    |Returns true if `bits` has all `flags` set.|
+|`#define HAS_ANY_FLAGS(bits, flags)`|Returns true if `bits` has any `flags` set.|
+|`#define LED_FLAG_NONE      0x00`   |If this LED has no flags.                  |
+|`#define LED_FLAG_ALL       0xFF`   |If this LED has all flags.                 |
+|`#define LED_FLAG_MODIFIER  0x01`   |If the Key for this LED is a modifier.     |
+|`#define LED_FLAG_UNDERGLOW 0x02`   |If the LED is for underglow.               |
+|`#define LED_FLAG_KEYLIGHT  0x04`   |If the LED is for key backlight.           |
+
+## Keycodes
+
+All RGB keycodes are currently shared with the RGBLIGHT system:
+
+* `RGB_TOG` - toggle
+* `RGB_MOD` - cycle through modes
+* `RGB_HUI` - increase hue
+* `RGB_HUD` - decrease hue
+* `RGB_SAI` - increase saturation
+* `RGB_SAD` - decrease saturation
+* `RGB_VAI` - increase value
+* `RGB_VAD` - decrease value
+* `RGB_SPI` - increase speed effect (no EEPROM support)
+* `RGB_SPD` - decrease speed effect (no EEPROM support)
+* `RGB_MODE_*` keycodes will generally work, but are not currently mapped to the correct effects for the RGB Matrix system
+
+## RGB Matrix Effects
+
+All effects have been configured to support current configuration values (Hue, Saturation, Value, & Speed) unless otherwise noted below. These are the effects that are currently available:
+
+```C
+enum rgb_matrix_effects {
+    RGB_MATRIX_NONE = 0,
+    RGB_MATRIX_SOLID_COLOR = 1,     // Static single hue, no speed support
+    RGB_MATRIX_ALPHAS_MODS,         // Static dual hue, speed is hue for secondary hue
+    RGB_MATRIX_GRADIENT_UP_DOWN,    // Static gradient top to bottom, speed controls how much gradient changes
+    RGB_MATRIX_BREATHING,           // Single hue brightness cycling animation
+    RGB_MATRIX_BAND_SAT,        // Single hue band fading saturation scrolling left to right
+    RGB_MATRIX_BAND_VAL,        // Single hue band fading brightness scrolling left to right
+    RGB_MATRIX_BAND_PINWHEEL_SAT,   // Single hue 3 blade spinning pinwheel fades saturation
+    RGB_MATRIX_BAND_PINWHEEL_VAL,   // Single hue 3 blade spinning pinwheel fades brightness
+    RGB_MATRIX_BAND_SPIRAL_SAT,     // Single hue spinning spiral fades saturation
+    RGB_MATRIX_BAND_SPIRAL_VAL,     // Single hue spinning spiral fades brightness
+    RGB_MATRIX_CYCLE_ALL,           // Full keyboard solid hue cycling through full gradient
+    RGB_MATRIX_CYCLE_LEFT_RIGHT,    // Full gradient scrolling left to right
+    RGB_MATRIX_CYCLE_UP_DOWN,       // Full gradient scrolling top to bottom
+    RGB_MATRIX_CYCLE_OUT_IN,        // Full gradient scrolling out to in
+    RGB_MATRIX_CYCLE_OUT_IN_DUAL,   // Full dual gradients scrolling out to in
+    RGB_MATRIX_RAINBOW_MOVING_CHEVRON,  // Full gradent Chevron shapped scrolling left to right
+    RGB_MATRIX_CYCLE_PINWHEEL,      // Full gradient spinning pinwheel around center of keyboard
+    RGB_MATRIX_CYCLE_SPIRAL,        // Full gradient spinning spiral around center of keyboard
+    RGB_MATRIX_DUAL_BEACON,         // Full gradient spinning around center of keyboard
+    RGB_MATRIX_RAINBOW_BEACON,      // Full tighter gradient spinning around center of keyboard
+    RGB_MATRIX_RAINBOW_PINWHEELS,   // Full dual gradients spinning two halfs of keyboard
+    RGB_MATRIX_RAINDROPS,           // Randomly changes a single key's hue
+    RGB_MATRIX_JELLYBEAN_RAINDROPS, // Randomly changes a single key's hue and saturation
+#if define(RGB_MATRIX_FRAMEBUFFER_EFFECTS)
+    RGB_MATRIX_TYPING_HEATMAP,      // How hot is your WPM!
+    RGB_MATRIX_DIGITAL_RAIN,        // That famous computer simulation
+#endif
+#if defined(RGB_MATRIX_KEYPRESSES) || defined(RGB_MATRIX_KEYRELEASES)
+    RGB_MATRIX_SOLID_REACTIVE_SIMPLE,   // Pulses keys hit to hue & value then fades value out
+    RGB_MATRIX_SOLID_REACTIVE,      // Static single hue, pulses keys hit to shifted hue then fades to current hue
+    RGB_MATRIX_SOLID_REACTIVE_WIDE       // Hue & value pulse near a single key hit then fades value out
+    RGB_MATRIX_SOLID_REACTIVE_MULTIWIDE  // Hue & value pulse near multiple key hits then fades value out
+    RGB_MATRIX_SOLID_REACTIVE_CROSS      // Hue & value pulse the same column and row of a single key hit then fades value out
+    RGB_MATRIX_SOLID_REACTIVE_MULTICROSS // Hue & value pulse the same column and row of multiple key hits then fades value out
+    RGB_MATRIX_SOLID_REACTIVE_NEXUS      // Hue & value pulse away on the same column and row of a single key hit then fades value out
+    RGB_MATRIX_SOLID_REACTIVE_MULTINEXUS // Hue & value pulse away on the same column and row of multiple key hits then fades value out
+    RGB_MATRIX_SPLASH,              // Full gradient & value pulse away from a single key hit then fades value out
+    RGB_MATRIX_MULTISPLASH,         // Full gradient & value pulse away from multiple key hits then fades value out
+    RGB_MATRIX_SOLID_SPLASH,        // Hue & value pulse away from a single key hit then fades value out
+    RGB_MATRIX_SOLID_MULTISPLASH,   // Hue & value pulse away from multiple key hits then fades value out
+#endif
+    RGB_MATRIX_EFFECT_MAX
+};
+```
+
+You can disable a single effect by defining `DISABLE_[EFFECT_NAME]` in your `config.h`:
+
+
+|Define                                                 |Description                                    |
+|-------------------------------------------------------|-----------------------------------------------|
+|`#define DISABLE_RGB_MATRIX_ALPHAS_MODS`               |Disables `RGB_MATRIX_ALPHAS_MODS`              |
+|`#define DISABLE_RGB_MATRIX_GRADIENT_UP_DOWN`          |Disables `RGB_MATRIX_GRADIENT_UP_DOWN`         |
+|`#define DISABLE_RGB_MATRIX_BREATHING`                 |Disables `RGB_MATRIX_BREATHING`                |
+|`#define DISABLE_RGB_MATRIX_BAND_SAT`                  |Disables `RGB_MATRIX_BAND_SAT`                 |
+|`#define DISABLE_RGB_MATRIX_BAND_VAL`                  |Disables `RGB_MATRIX_BAND_VAL`                 |
+|`#define DISABLE_RGB_MATRIX_BAND_PINWHEEL_SAT`         |Disables `RGB_MATRIX_BAND_PINWHEEL_SAT`        |
+|`#define DISABLE_RGB_MATRIX_BAND_PINWHEEL_VAL`         |Disables `RGB_MATRIX_BAND_PINWHEEL_VAL`        |
+|`#define DISABLE_RGB_MATRIX_BAND_SPIRAL_SAT`           |Disables `RGB_MATRIX_BAND_SPIRAL_SAT`          |
+|`#define DISABLE_RGB_MATRIX_BAND_SPIRAL_VAL`           |Disables `RGB_MATRIX_BAND_SPIRAL_VAL`          |
+|`#define DISABLE_RGB_MATRIX_CYCLE_ALL`                 |Disables `RGB_MATRIX_CYCLE_ALL`                |
+|`#define DISABLE_RGB_MATRIX_CYCLE_LEFT_RIGHT`          |Disables `RGB_MATRIX_CYCLE_LEFT_RIGHT`         |
+|`#define DISABLE_RGB_MATRIX_CYCLE_UP_DOWN`             |Disables `RGB_MATRIX_CYCLE_UP_DOWN`            |
+|`#define DISABLE_RGB_MATRIX_CYCLE_OUT_IN`              |Disables `RGB_MATRIX_CYCLE_OUT_IN`             |
+|`#define DISABLE_RGB_MATRIX_CYCLE_OUT_IN_DUAL`         |Disables `RGB_MATRIX_CYCLE_OUT_IN_DUAL`        |
+|`#define DISABLE_RGB_MATRIX_RAINBOW_MOVING_CHEVRON`    |Disables `RGB_MATRIX_RAINBOW_MOVING_CHEVRON`   |
+|`#define DISABLE_RGB_MATRIX_DUAL_BEACON`               |Disables `RGB_MATRIX_DUAL_BEACON`              |
+|`#define DISABLE_RGB_MATRIX_CYCLE_PINWHEEL`            |Disables `RGB_MATRIX_CYCLE_PINWHEEL`           |
+|`#define DISABLE_RGB_MATRIX_CYCLE_SPIRAL`              |Disables `RGB_MATRIX_CYCLE_SPIRAL`             |
+|`#define DISABLE_RGB_MATRIX_RAINBOW_BEACON`            |Disables `RGB_MATRIX_RAINBOW_BEACON`           |
+|`#define DISABLE_RGB_MATRIX_RAINBOW_PINWHEELS`         |Disables `RGB_MATRIX_RAINBOW_PINWHEELS`        |
+|`#define DISABLE_RGB_MATRIX_RAINDROPS`                 |Disables `RGB_MATRIX_RAINDROPS`                |
+|`#define DISABLE_RGB_MATRIX_JELLYBEAN_RAINDROPS`       |Disables `RGB_MATRIX_JELLYBEAN_RAINDROPS`      |
+|`#define DISABLE_RGB_MATRIX_TYPING_HEATMAP`            |Disables `RGB_MATRIX_TYPING_HEATMAP`           |
+|`#define DISABLE_RGB_MATRIX_DIGITAL_RAIN`              |Disables `RGB_MATRIX_DIGITAL_RAIN`             |
+|`#define DISABLE_RGB_MATRIX_SOLID_REACTIVE`            |Disables `RGB_MATRIX_SOLID_REACTIVE`           |
+|`#define DISABLE_RGB_MATRIX_SOLID_REACTIVE_SIMPLE`     |Disables `RGB_MATRIX_SOLID_REACTIVE_SIMPLE`    |
+|`#define DISABLE_RGB_MATRIX_SOLID_REACTIVE_WIDE`       |Disables `RGB_MATRIX_SOLID_REACTIVE_WIDE`      |
+|`#define DISABLE_RGB_MATRIX_SOLID_REACTIVE_MULTIWIDE`  |Disables `RGB_MATRIX_SOLID_REACTIVE_MULTIWIDE` |
+|`#define DISABLE_RGB_MATRIX_SOLID_REACTIVE_CROSS`      |Disables `RGB_MATRIX_SOLID_REACTIVE_CROSS`     |
+|`#define DISABLE_RGB_MATRIX_SOLID_REACTIVE_MULTICROSS` |Disables `RGB_MATRIX_SOLID_REACTIVE_MULTICROSS`|
+|`#define DISABLE_RGB_MATRIX_SOLID_REACTIVE_NEXUS`      |Disables `RGB_MATRIX_SOLID_REACTIVE_NEXUS`     |
+|`#define DISABLE_RGB_MATRIX_SOLID_REACTIVE_MULTINEXUS` |Disables `RGB_MATRIX_SOLID_REACTIVE_MULTINEXUS`|
+|`#define DISABLE_RGB_MATRIX_SPLASH`                    |Disables `RGB_MATRIX_SPLASH`                   |
+|`#define DISABLE_RGB_MATRIX_MULTISPLASH`               |Disables `RGB_MATRIX_MULTISPLASH`              |
+|`#define DISABLE_RGB_MATRIX_SOLID_SPLASH`              |Disables `RGB_MATRIX_SOLID_SPLASH`             |
+|`#define DISABLE_RGB_MATRIX_SOLID_MULTISPLASH`         |Disables `RGB_MATRIX_SOLID_MULTISPLASH`        |
+
+
+## Custom RGB Matrix Effects
+
+By setting `RGB_MATRIX_CUSTOM_USER` (and/or `RGB_MATRIX_CUSTOM_KB`) in `rule.mk`, new effects can be defined directly from userspace, without having to edit any QMK core files.
+
+To declare new effects, create a new `rgb_matrix_user/kb.inc` that looks something like this:
+
+`rgb_matrix_user.inc` should go in the root of the keymap directory.
+`rgb_matrix_kb.inc` should go in the root of the keyboard directory.
+
+```C
+// !!! DO NOT ADD #pragma once !!! //
+
+// Step 1.
+// Declare custom effects using the RGB_MATRIX_EFFECT macro
+// (note the lack of semicolon after the macro!)
+RGB_MATRIX_EFFECT(my_cool_effect)
+RGB_MATRIX_EFFECT(my_cool_effect2)
+
+// Step 2.
+// Define effects inside the `RGB_MATRIX_CUSTOM_EFFECT_IMPLS` ifdef block
+#ifdef RGB_MATRIX_CUSTOM_EFFECT_IMPLS
+
+// e.g: A simple effect, self-contained within a single method
+static bool my_cool_effect(effect_params_t* params) {
+  RGB_MATRIX_USE_LIMITS(led_min, led_max);
+  for (uint8_t i = led_min; i < led_max; i++) {
+    rgb_matrix_set_color(i, 0xff, 0xff, 0x00);
+  }
+  return led_max < DRIVER_LED_TOTAL;
+}
+
+// e.g: A more complex effect, relying on external methods and state, with
+// dedicated init and run methods
+static uint8_t some_global_state;
+static void my_cool_effect2_complex_init(effect_params_t* params) {
+  some_global_state = 1;
+}
+static bool my_cool_effect2_complex_run(effect_params_t* params) {
+  RGB_MATRIX_USE_LIMITS(led_min, led_max);
+  for (uint8_t i = led_min; i < led_max; i++) {
+    rgb_matrix_set_color(i, 0xff, some_global_state++, 0xff);
+  }
+
+  return led_max < DRIVER_LED_TOTAL;
+}
+static bool my_cool_effect2(effect_params_t* params) {
+  if (params->init) my_cool_effect2_complex_init(params);
+  return my_cool_effect2_complex_run(params);
+}
+
+#endif // RGB_MATRIX_CUSTOM_EFFECT_IMPLS
+```
+
+For inspiration and examples, check out the built-in effects under `quantum/rgb_matrix_animation/`
+
+
+## Colors
+
+These are shorthands to popular colors. The `RGB` ones can be passed to the `setrgb` functions, while the `HSV` ones to the `sethsv` functions.
+
+|RGB                |HSV                |
+|-------------------|-------------------|
+|`RGB_WHITE`        |`HSV_WHITE`        |
+|`RGB_RED`          |`HSV_RED`          |
+|`RGB_CORAL`        |`HSV_CORAL`        |
+|`RGB_ORANGE`       |`HSV_ORANGE`       |
+|`RGB_GOLDENROD`    |`HSV_GOLDENROD`    |
+|`RGB_GOLD`         |`HSV_GOLD`         |
+|`RGB_YELLOW`       |`HSV_YELLOW`       |
+|`RGB_CHARTREUSE`   |`HSV_CHARTREUSE`   |
+|`RGB_GREEN`        |`HSV_GREEN`        |
+|`RGB_SPRINGGREEN`  |`HSV_SPRINGGREEN`  |
+|`RGB_TURQUOISE`    |`HSV_TURQUOISE`    |
+|`RGB_TEAL`         |`HSV_TEAL`         |
+|`RGB_CYAN`         |`HSV_CYAN`         |
+|`RGB_AZURE`        |`HSV_AZURE`        |
+|`RGB_BLUE`         |`HSV_BLUE`         |
+|`RGB_PURPLE`       |`HSV_PURPLE`       |
+|`RGB_MAGENTA`      |`HSV_MAGENTA`      |
+|`RGB_PINK`         |`HSV_PINK`         |
+
+These are defined in [`rgblight_list.h`](https://github.com/qmk/qmk_firmware/blob/master/quantum/rgblight_list.h). Feel free to add to this list!
+
+
+## Additional `config.h` Options
+
+```C
+#define RGB_MATRIX_KEYPRESSES // reacts to keypresses
+#define RGB_MATRIX_KEYRELEASES // reacts to keyreleases (instead of keypresses)
+#define RGB_DISABLE_AFTER_TIMEOUT 0 // number of ticks to wait until disabling effects
+#define RGB_DISABLE_WHEN_USB_SUSPENDED false // turn off effects when suspended
+#define RGB_MATRIX_LED_PROCESS_LIMIT (DRIVER_LED_TOTAL + 4) / 5 // limits the number of LEDs to process in an animation per task run (increases keyboard responsiveness)
+#define RGB_MATRIX_LED_FLUSH_LIMIT 16 // limits in milliseconds how frequently an animation will update the LEDs. 16 (16ms) is equivalent to limiting to 60fps (increases keyboard responsiveness)
+#define RGB_MATRIX_MAXIMUM_BRIGHTNESS 200 // limits maximum brightness of LEDs to 200 out of 255. If not defined maximum brightness is set to 255
+#define RGB_MATRIX_STARTUP_MODE RGB_MATRIX_CYCLE_LEFT_RIGHT // Sets the default mode, if none has been set
+```
+
+## EEPROM storage
+
+The EEPROM for it is currently shared with the RGBLIGHT system (it's generally assumed only one RGB would be used at a time), but could be configured to use its own 32bit address with:
+
+```C
+#define EECONFIG_RGB_MATRIX (uint32_t *)28
+```
+
+Where `28` is an unused index from `eeconfig.h`.
+
+## Suspended state
+
+To use the suspend feature, add this to your `<keyboard>.c`:
+
+```C
+void suspend_power_down_kb(void)
+{
+    rgb_matrix_set_suspend_state(true);
+}
+
+void suspend_wakeup_init_kb(void)
+{
+    rgb_matrix_set_suspend_state(false);
+}
+```

docs/feature_rgblight.md

@@ -0,0 +1,385 @@
+# RGB Lighting
+
+QMK has the ability to control RGB LEDs attached to your keyboard. This is commonly called *underglow*, due to the LEDs often being mounted on the bottom of the keyboard, producing a nice diffused effect when combined with a translucent case.
+
+![Planck with RGB Underglow](https://raw.githubusercontent.com/qmk/qmk_firmware/3774a7fcdab5544fc787f4c200be05fcd417e31f/keyboards/planck/keymaps/yang/planck-with-rgb-underglow.jpg)
+
+Some keyboards come with RGB LEDs preinstalled. Others must have them installed after the fact. See the [Hardware Modification](#hardware-modification) section for information on adding RGB lighting to your keyboard.
+
+Currently QMK supports the following addressable LEDs on AVR microcontrollers (however, the white LED in RGBW variants is not supported):
+
+ * WS2811, WS2812, WS2812B, WS2812C, etc.
+ * SK6812, SK6812MINI, SK6805
+
+These LEDs are called "addressable" because instead of using a wire per color, each LED contains a small microchip that understands a special protocol sent over a single wire. The chip passes on the remaining data to the next LED, allowing them to be chained together. In this way, you can easily control the color of the individual LEDs.
+
+## Usage
+
+On keyboards with onboard RGB LEDs, it is usually enabled by default. If it is not working for you, check that your `rules.mk` includes the following:
+
+```make
+RGBLIGHT_ENABLE = yes
+```
+
+At minimum you must define the data pin your LED strip is connected to, and the number of LEDs in the strip, in your `config.h`. If your keyboard has onboard RGB LEDs, and you are simply creating a keymap, you usually won't need to modify these.
+
+|Define         |Description                                                                                              |
+|---------------|---------------------------------------------------------------------------------------------------------|
+|`RGB_DI_PIN`   |The pin connected to the data pin of the LEDs                                                            |
+|`RGBLED_NUM`   |The number of LEDs connected                                                                             |
+|`RGBLED_SPLIT` |(Optional) For split keyboards, the number of LEDs connected on each half directly wired to `RGB_DI_PIN` |
+
+Then you should be able to use the keycodes below to change the RGB lighting to your liking.
+
+### Color Selection
+
+QMK uses [Hue, Saturation, and Value](https://en.wikipedia.org/wiki/HSL_and_HSV) to select colors rather than RGB. The color wheel below demonstrates how this works.
+
+<img src="gitbook/images/color-wheel.svg" alt="HSV Color Wheel" width="250"/>
+
+Changing the **Hue** cycles around the circle.<br>
+Changing the **Saturation** moves between the inner and outer sections of the wheel, affecting the intensity of the color.<br>
+Changing the **Value** sets the overall brightness.<br>
+
+## Keycodes
+
+|Key                |Aliases   |Description                                                         |
+|-------------------|----------|--------------------------------------------------------------------|
+|`RGB_TOG`          |          |Toggle RGB lighting on or off                                       |
+|`RGB_MODE_FORWARD` |`RGB_MOD` |Cycle through modes, reverse direction when Shift is held           |
+|`RGB_MODE_REVERSE` |`RGB_RMOD`|Cycle through modes in reverse, forward direction when Shift is held|
+|`RGB_HUI`          |          |Increase hue                                                        |
+|`RGB_HUD`          |          |Decrease hue                                                        |
+|`RGB_SAI`          |          |Increase saturation                                                 |
+|`RGB_SAD`          |          |Decrease saturation                                                 |
+|`RGB_VAI`          |          |Increase value (brightness)                                         |
+|`RGB_VAD`          |          |Decrease value (brightness)                                         |
+|`RGB_MODE_PLAIN`   |`RGB_M_P `|Static (no animation) mode                                          |
+|`RGB_MODE_BREATHE` |`RGB_M_B` |Breathing animation mode                                            |
+|`RGB_MODE_RAINBOW` |`RGB_M_R` |Rainbow animation mode                                              |
+|`RGB_MODE_SWIRL`   |`RGB_M_SW`|Swirl animation mode                                                |
+|`RGB_MODE_SNAKE`   |`RGB_M_SN`|Snake animation mode                                                |
+|`RGB_MODE_KNIGHT`  |`RGB_M_K` |"Knight Rider" animation mode                                       |
+|`RGB_MODE_XMAS`    |`RGB_M_X` |Christmas animation mode                                            |
+|`RGB_MODE_GRADIENT`|`RGB_M_G` |Static gradient animation mode                                      |
+|`RGB_MODE_RGBTEST` |`RGB_M_T` |Red, Green, Blue test animation mode                                |
+
+## Configuration
+
+Your RGB lighting can be configured by placing these `#define`s in your `config.h`:
+
+|Define               |Default      |Description                                                                  |
+|---------------------|-------------|-----------------------------------------------------------------------------|
+|`RGBLIGHT_HUE_STEP`  |`10`         |The number of steps to cycle through the hue by                              |
+|`RGBLIGHT_SAT_STEP`  |`17`         |The number of steps to increment the saturation by                           |
+|`RGBLIGHT_VAL_STEP`  |`17`         |The number of steps to increment the brightness by                           |
+|`RGBLIGHT_LIMIT_VAL` |`255`        |The maximum brightness level                                                 |
+|`RGBLIGHT_SLEEP`     |*Not defined*|If defined, the RGB lighting will be switched off when the host goes to sleep|
+|`RGBLIGHT_SPLIT`     |*Not defined*|If defined, synchronization functionality for split keyboards is added|
+
+## Effects and Animations
+
+Not only can this lighting be whatever color you want,
+if `RGBLIGHT_EFFECT_xxxx` or `RGBLIGHT_ANIMATIONS` is defined, you also have a number of animation modes at your disposal:
+
+|Mode number symbol           |Additional number  |Description                            |
+|-----------------------------|-------------------|---------------------------------------|
+|`RGBLIGHT_MODE_STATIC_LIGHT` | *None*            |Solid color (this mode is always enabled) |
+|`RGBLIGHT_MODE_BREATHING`    | 0,1,2,3           |Solid color breathing                  |
+|`RGBLIGHT_MODE_RAINBOW_MOOD` | 0,1,2             |Cycling rainbow                        |
+|`RGBLIGHT_MODE_RAINBOW_SWIRL`| 0,1,2,3,4,5       |Swirling rainbow                       |
+|`RGBLIGHT_MODE_SNAKE`        | 0,1,2,3,4,5       |Snake                                  |
+|`RGBLIGHT_MODE_KNIGHT`       | 0,1,2             |Knight                                 |
+|`RGBLIGHT_MODE_CHRISTMAS`    | *None*            |Christmas                              |
+|`RGBLIGHT_MODE_STATIC_GRADIENT`| 0,1,..,9        |Static gradient                        |
+|`RGBLIGHT_MODE_RGB_TEST`     | *None*            |RGB Test                               |
+|`RGBLIGHT_MODE_ALTERNATING`  | *None*            |Alternating                            |
+
+Check out [this video](https://youtube.com/watch?v=VKrpPAHlisY) for a demonstration.
+
+Note: For versions older than 0.6.117, The mode numbers were written directly. In `quantum/rgblight.h` there is a contrast table between the old mode number and the current symbol.
+
+### Effect and Animation Toggles
+
+Use these defines to add or remove animations from the firmware. When you are running low on flash space, it can be helpful to disable animations you are not using.
+
+|Define                              |Default      |Description                                                                          |
+|------------------------------------|-------------|-------------------------------------------------------------------------------------|
+|`RGBLIGHT_ANIMATIONS`               |*Not defined*|Enable all additional animation modes.                                   |
+|`RGBLIGHT_EFFECT_ALTERNATING`       |*Not defined*|Enable alternating animation mode.                                       |
+|`RGBLIGHT_EFFECT_BREATHING`         |*Not defined*|Enable breathing animation mode.                                         |
+|`RGBLIGHT_EFFECT_CHRISTMAS`         |*Not defined*|Enable christmas animation mode.                                         |
+|`RGBLIGHT_EFFECT_KNIGHT`            |*Not defined*|Enable knight animation mode.                                            |
+|`RGBLIGHT_EFFECT_RAINBOW_MOOD`      |*Not defined*|Enable rainbow mood animation mode.                                      |
+|`RGBLIGHT_EFFECT_RAINBOW_SWIRL`     |*Not defined*|Enable rainbow swirl animation mode.                                     |
+|`RGBLIGHT_EFFECT_RGB_TEST`          |*Not defined*|Enable RGB test animation mode.                                          |
+|`RGBLIGHT_EFFECT_SNAKE`             |*Not defined*|Enable snake animation mode.                                             |
+|`RGBLIGHT_EFFECT_STATIC_GRADIENT`   |*Not defined*|Enable static gradient mode.                                             |
+
+### Effect and Animation Settings
+
+The following options are used to tweak the various animations:
+
+|Define                              |Default      |Description                                                                          |
+|------------------------------------|-------------|-------------------------------------------------------------------------------------|
+|`RGBLIGHT_EFFECT_BREATHE_CENTER`    |*Not defined*|If defined, used to calculate the curve for the breathing animation. Valid values are 1.0 to 2.7 |
+|`RGBLIGHT_EFFECT_BREATHE_MAX`       |`255`        |The maximum brightness for the breathing mode. Valid values are 1 to 255             |
+|`RGBLIGHT_EFFECT_CHRISTMAS_INTERVAL`|`1000`       |How long to wait between light changes for the "Christmas" animation, in milliseconds|
+|`RGBLIGHT_EFFECT_CHRISTMAS_STEP`    |`2`          |The number of LEDs to group the red/green colors by for the "Christmas" animation    |
+|`RGBLIGHT_EFFECT_KNIGHT_LED_NUM`    |`RGBLED_NUM` |The number of LEDs to have the "Knight" animation travel                             |
+|`RGBLIGHT_EFFECT_KNIGHT_LENGTH`     |`3`          |The number of LEDs to light up for the "Knight" animation                            |
+|`RGBLIGHT_EFFECT_KNIGHT_OFFSET`     |`0`          |The number of LEDs to start the "Knight" animation from the start of the strip by    |
+|`RGBLIGHT_RAINBOW_SWIRL_RANGE`      |`255`        |Range adjustment for the rainbow swirl effect to get different swirls                |
+|`RGBLIGHT_EFFECT_SNAKE_LENGTH`      |`4`          |The number of LEDs to light up for the "Snake" animation                             |
+
+### Example Usage to Reduce Memory Footprint
+  1. Remove `RGBLIGHT_ANIMATIONS` from `config.h`.
+  1. Selectively add the animations you want to enable. The following would enable two animations and save about 4KiB:
+
+```diff
+ #undef RGBLED_NUM
+-#define RGBLIGHT_ANIMATIONS
++#define RGBLIGHT_EFFECT_STATIC_GRADIENT
++#define RGBLIGHT_EFFECT_RAINBOW_SWIRL
+ #define RGBLED_NUM 12
+ #define RGBLIGHT_HUE_STEP 8
+ #define RGBLIGHT_SAT_STEP 8
+```
+
+### Animation Speed
+
+You can also modify the speeds that the different modes animate at:
+
+Here is a quick demo on Youtube (with NPKC KC60) (https://www.youtube.com/watch?v=VKrpPAHlisY).
+
+```c
+// How long (in milliseconds) to wait between animation steps for each of the "Solid color breathing" animations
+const uint8_t RGBLED_BREATHING_INTERVALS[] PROGMEM = {30, 20, 10, 5};
+
+// How long (in milliseconds) to wait between animation steps for each of the "Cycling rainbow" animations
+const uint8_t RGBLED_RAINBOW_MOOD_INTERVALS[] PROGMEM = {120, 60, 30};
+
+// How long (in milliseconds) to wait between animation steps for each of the "Swirling rainbow" animations
+const uint8_t RGBLED_RAINBOW_SWIRL_INTERVALS[] PROGMEM = {100, 50, 20};
+
+// How long (in milliseconds) to wait between animation steps for each of the "Snake" animations
+const uint8_t RGBLED_SNAKE_INTERVALS[] PROGMEM = {100, 50, 20};
+
+// How long (in milliseconds) to wait between animation steps for each of the "Knight" animations
+const uint8_t RGBLED_KNIGHT_INTERVALS[] PROGMEM = {127, 63, 31};
+
+// These control which hues are selected for each of the "Static gradient" modes
+const uint8_t RGBLED_GRADIENT_RANGES[] PROGMEM = {255, 170, 127, 85, 64};
+```
+
+## Functions
+
+If you need to change your RGB lighting in code, for example in a macro to change the color whenever you switch layers, QMK provides a set of functions to assist you. See [`rgblight.h`](https://github.com/qmk/qmk_firmware/blob/master/quantum/rgblight.h) for the full list, but the most commonly used functions include:
+
+### Utility Functions
+|Function                                    |Description                                                        |
+|--------------------------------------------|-------------------------------------------------------------------|
+|`sethsv(hue, sat, val, ledbuf)`             |Set ledbuf to the given HSV value                                  |
+|`sethsv_raw(hue, sat, val, ledbuf)`         |Set ledbuf to the given HSV value without RGBLIGHT_LIMIT_VAL check |
+|`setrgb(r, g, b, ledbuf)`                   |Set ledbuf to the given RGB value where `r`/`g`/`b`                |
+
+### Low level Functions
+|Function                                    |Description                                |
+|--------------------------------------------|-------------------------------------------|
+|`rgblight_set()`                            |Flash out led buffers to LEDs              |
+|`rgblight_set_clipping_range(pos, num)`     |Set clipping Range. see [Clipping Range](#clipping-range) |
+
+Example:
+```c
+sethsv(HSV_WHITE, (LED_TYPE *)&led[0]); // led 0
+sethsv(HSV_RED,   (LED_TYPE *)&led[1]); // led 1
+sethsv(HSV_GREEN, (LED_TYPE *)&led[2]); // led 2
+rgblight_set(); // Utility functions do not call rgblight_set() automatically, so they need to be called explicitly.
+```
+
+### Effects and Animations Functions
+#### effect range setting
+|Function                                    |Description       |
+|--------------------------------------------|------------------|
+|`rgblight_set_effect_range(pos, num)`       |Set Effects Range |
+
+#### direct operation
+|Function                                    |Description  |
+|--------------------------------------------|-------------|
+|`rgblight_setrgb_at(r, g, b, index)`          |Set a single LED to the given RGB value, where `r`/`g`/`b` are between 0 and 255 and `index` is between 0 and `RGBLED_NUM` (not written to EEPROM) |
+|`rgblight_sethsv_at(h, s, v, index)`          |Set a single LED to the given HSV value, where `h`/`s`/`v` are between 0 and 255, and `index` is between 0 and `RGBLED_NUM` (not written to EEPROM) |
+|`rgblight_setrgb_range(r, g, b, start, end)`|Set a continuous range of LEDs to the given RGB value, where `r`/`g`/`b` are between 0 and 255 and `start`(included) and `stop`(excluded) are between 0 and `RGBLED_NUM` (not written to EEPROM)|
+|`rgblight_sethsv_range(h, s, v, start, end)`|Set a continuous range of LEDs to the given HSV value, where `h`/`s`/`v` are between 0 and 255, and `start`(included) and `stop`(excluded) are between 0 and `RGBLED_NUM` (not written to EEPROM)|
+|`rgblight_setrgb(r, g, b)`                  |Set effect range LEDs to the given RGB value where `r`/`g`/`b` are between 0 and 255 (not written to EEPROM) |
+|`rgblight_setrgb_master(r, g, b)`           |Set the LEDs on the master side  to the given RGB value, where `r`/`g`/`b` are between 0 and 255 (not written to EEPROM) |
+|`rgblight_setrgb_slave(r, g, b)`            |Set the LEDs on the slave side  to the given RGB value, where `r`/`g`/`b` are between 0 and 255 (not written to EEPROM) |
+|`rgblight_sethsv_master(h, s, v)`           |Set the LEDs on the master side to the given HSV value, where `h`/`s`/`v` are between 0 and 255 (not written to EEPROM) |
+|`rgblight_sethsv_slave(h, s, v)`            |Set the LEDs on the slave side to the given HSV value, where `h`/`s`/`v` are between 0 and 255 (not written to EEPROM) |
+
+Example:
+```c
+rgblight_sethsv(HSV_WHITE, 0); // led 0
+rgblight_sethsv(HSV_RED,   1); // led 1
+rgblight_sethsv(HSV_GREEN, 2); // led 2
+// The above functions automatically calls rgblight_set(), so there is no need to call it explicitly.
+// Note that it is inefficient to call repeatedly.
+```
+
+#### effect mode change
+|Function                                    |Description  |
+|--------------------------------------------|-------------|
+|`rgblight_mode(x)`                          |Set the mode, if RGB animations are enabled |
+|`rgblight_mode_noeeprom(x)`                 |Set the mode, if RGB animations are enabled (not written to EEPROM) |
+|`rgblight_step()`                           |Change the mode to the next RGB animation in the list of enabled RGB animations |
+|`rgblight_step_noeeprom()`                  |Change the mode to the next RGB animation in the list of enabled RGB animations (not written to EEPROM) |
+|`rgblight_step_reverse()`                   |Change the mode to the previous RGB animation in the list of enabled RGB animations |
+|`rgblight_step_reverse_noeeprom()`          |Change the mode to the previous RGB animation in the list of enabled RGB animations (not written to EEPROM) |
+
+#### effects mode disable/enable
+|Function                                    |Description  |
+|--------------------------------------------|-------------|
+|`rgblight_toggle()`                         |Toggle effect range LEDs between on and off |
+|`rgblight_toggle_noeeprom()`                |Toggle effect range LEDs between on and off (not written to EEPROM) |
+|`rgblight_enable()`                         |Turn effect range LEDs on, based on their previous state |
+|`rgblight_enable_noeeprom()`                |Turn effect range LEDs on, based on their previous state (not written to EEPROM) |
+|`rgblight_disable()`                        |Turn effect range LEDs off |
+|`rgblight_disable_noeeprom()`               |Turn effect range LEDs off (not written to EEPROM) |
+
+#### hue, sat, val change
+|Function                                    |Description  |
+|--------------------------------------------|-------------|
+|`rgblight_increase_hue()`                   |Increase the hue for effect range LEDs. This wraps around at maximum hue |
+|`rgblight_increase_hue_noeeprom()`          |Increase the hue for effect range LEDs. This wraps around at maximum hue (not written to EEPROM) |
+|`rgblight_decrease_hue()`                   |Decrease the hue for effect range LEDs. This wraps around at minimum hue |
+|`rgblight_decrease_hue_noeeprom()`          |Decrease the hue for effect range LEDs. This wraps around at minimum hue (not written to EEPROM) |
+|`rgblight_increase_sat()`                   |Increase the saturation for effect range LEDs. This wraps around at maximum saturation |
+|`rgblight_increase_sat_noeeprom()`          |Increase the saturation for effect range LEDs. This wraps around at maximum saturation (not written to EEPROM) |
+|`rgblight_decrease_sat()`                   |Decrease the saturation for effect range LEDs. This wraps around at minimum saturation |
+|`rgblight_decrease_sat_noeeprom()`          |Decrease the saturation for effect range LEDs. This wraps around at minimum saturation (not written to EEPROM) |
+|`rgblight_increase_val()`                   |Increase the value for effect range LEDs. This wraps around at maximum value |
+|`rgblight_increase_val_noeeprom()`          |Increase the value for effect range LEDs. This wraps around at maximum value (not written to EEPROM) |
+|`rgblight_decrease_val()`                   |Decrease the value for effect range LEDs. This wraps around at minimum value |
+|`rgblight_decrease_val_noeeprom()`          |Decrease the value for effect range LEDs. This wraps around at minimum value (not written to EEPROM) |
+|`rgblight_sethsv(h, s, v)`                  |Set effect range LEDs to the given HSV value where `h`/`s`/`v` are between 0 and 255 |
+|`rgblight_sethsv_noeeprom(h, s, v)`         |Set effect range LEDs to the given HSV value where `h`/`s`/`v` are between 0 and 255 (not written to EEPROM) |
+
+#### query
+|Function               |Description      |
+|-----------------------|-----------------|
+|`rgblight_get_mode()`  |Get current mode |
+|`rgblight_get_hue()`   |Get current hue  |
+|`rgblight_get_sat()`   |Get current sat  |
+|`rgblight_get_val()`   |Get current val  |
+
+## Colors
+
+These are shorthands to popular colors. The `RGB` ones can be passed to the `setrgb` functions, while the `HSV` ones to the `sethsv` functions.
+
+|RGB                |HSV                |
+|-------------------|-------------------|
+|`RGB_WHITE`        |`HSV_WHITE`        |
+|`RGB_RED`          |`HSV_RED`          |
+|`RGB_CORAL`        |`HSV_CORAL`        |
+|`RGB_ORANGE`       |`HSV_ORANGE`       |
+|`RGB_GOLDENROD`    |`HSV_GOLDENROD`    |
+|`RGB_GOLD`         |`HSV_GOLD`         |
+|`RGB_YELLOW`       |`HSV_YELLOW`       |
+|`RGB_CHARTREUSE`   |`HSV_CHARTREUSE`   |
+|`RGB_GREEN`        |`HSV_GREEN`        |
+|`RGB_SPRINGGREEN`  |`HSV_SPRINGGREEN`  |
+|`RGB_TURQUOISE`    |`HSV_TURQUOISE`    |
+|`RGB_TEAL`         |`HSV_TEAL`         |
+|`RGB_CYAN`         |`HSV_CYAN`         |
+|`RGB_AZURE`        |`HSV_AZURE`        |
+|`RGB_BLUE`         |`HSV_BLUE`         |
+|`RGB_PURPLE`       |`HSV_PURPLE`       |
+|`RGB_MAGENTA`      |`HSV_MAGENTA`      |
+|`RGB_PINK`         |`HSV_PINK`         |
+
+```c
+rgblight_setrgb(RGB_ORANGE);
+rgblight_sethsv_noeeprom(HSV_GREEN);
+rgblight_setrgb_at(RGB_GOLD, 3);
+rgblight_sethsv_range(HSV_WHITE, 0, 6);
+```
+
+These are defined in [`rgblight_list.h`](https://github.com/qmk/qmk_firmware/blob/master/quantum/rgblight_list.h). Feel free to add to this list!
+
+
+## Changing the order of the LEDs
+
+If you want to make the logical order of LEDs different from the electrical connection order, you can do this by defining the `RGBLIGHT_LED_MAP` macro in your `config.h`.
+
+Normally, the contents of the LED buffer are output to the LEDs in the same order.
+<img src="https://user-images.githubusercontent.com/2170248/55743718-01866c80-5a6e-11e9-8134-25419928327a.JPG" alt="simple dicrect" width="50%"/>
+
+By defining `RGBLIGHT_LED_MAP` as in the example below, you can specify the LED with addressing in reverse order of the electrical connection order.
+
+```c
+// config.h
+
+#define RGBLED_NUM 4
+#define RGBLIGHT_LED_MAP { 3, 2, 1, 0 }
+
+```
+<img src="https://user-images.githubusercontent.com/2170248/55743725-08ad7a80-5a6e-11e9-83ed-126a2b0209fc.JPG" alt="simple mapped" width="50%"/>
+
+For keyboards that use the RGB LEDs as a backlight for each key, you can also define it as in the example below.
+
+```c
+// config.h
+
+#define RGBLED_NUM 30
+
+/* RGB LED Conversion macro from physical array to electric array */
+#define LED_LAYOUT( \
+    L00, L01, L02, L03, L04, L05,  \
+    L10, L11, L12, L13, L14, L15,  \
+    L20, L21, L22, L23, L24, L25,  \
+    L30, L31, L32, L33, L34, L35,  \
+    L40, L41, L42, L43, L44, L45 ) \
+  { \
+    L05, L04, L03, L02, L01, L00,   \
+    L10, L11, L12, L13, L14, L15,   \
+    L25, L24, L23, L22, L21, L20,   \
+    L30, L31, L32, L33, L34, L35,   \
+    L46, L45, L44, L43, L42, L41    \
+  }
+
+/* RGB LED logical order map */
+/* Top->Bottom, Right->Left */
+#define RGBLIGHT_LED_MAP LED_LAYOUT( \
+  25, 20, 15, 10,  5,  0,       \
+  26, 21, 16, 11,  6,  1,       \
+  27, 22, 17, 12,  7,  2,       \
+  28, 23, 18, 13,  8,  3,       \
+  29, 24, 19, 14,  9,  4 )
+
+```
+## Clipping Range
+
+Using the `rgblight_set_clipping_range()` function, you can prepare more buffers than the actual number of LEDs, and output some of the buffers to the LEDs. This is useful if you want the split keyboard to treat left and right LEDs as logically contiguous.
+
+You can set the Clipping Range by executing the following code.
+
+```c
+// some soruce
+  rgblight_set_clipping_range(3, 4);
+```
+<img src="https://user-images.githubusercontent.com/2170248/55743785-2bd82a00-5a6e-11e9-9d4b-1b4ffaf4932b.JPG" alt="clip direct" width="70%"/>
+
+In addition to setting the Clipping Range, you can use `RGBLIGHT_LED_MAP` together.
+
+```c
+// config.h
+#define RGBLED_NUM 8
+#define RGBLIGHT_LED_MAP { 7, 6, 5, 4, 3, 2, 1, 0 }
+
+// some soruce
+  rgblight_set_clipping_range(3, 4);
+```
+<img src="https://user-images.githubusercontent.com/2170248/55743747-119e4c00-5a6e-11e9-91e5-013203ffae8a.JPG" alt="clip mapped" width="70%"/>
+
+## Hardware Modification
+
+If your keyboard lacks onboard underglow LEDs, you may often be able to solder on an RGB LED strip yourself. You will need to find an unused pin to wire to the data pin of your LED strip. Some keyboards may break out unused pins from the MCU to make soldering easier. The other two pins, VCC and GND, must also be connected to the appropriate power pins.

docs/feature_space_cadet.md

@@ -0,0 +1,60 @@
+# Space Cadet: The Future, Built In
+
+Steve Losh described the [Space Cadet Shift](http://stevelosh.com/blog/2012/10/a-modern-space-cadet/) quite well. Essentially, when you tap Left Shift on its own, you get an opening parenthesis; tap Right Shift on its own and you get the closing one. When held, the Shift keys function as normal. Yes, it's as cool as it sounds, and now even cooler supporting Control and Alt as well!
+
+## Usage
+
+Firstly, in your keymap, do one of the following:
+- Replace the Left Shift key with `KC_LSPO` (Left Shift, Parenthesis Open), and Right Shift with `KC_RSPC` (Right Shift, Parenthesis Close).
+- Replace the Left Control key with `KC_LCPO` (Left Control, Parenthesis Open), and Right Control with `KC_RCPC` (Right Control, Parenthesis Close).
+- Replace the Left Alt key with `KC_LAPO` (Left Alt, Parenthesis Open), and Right Alt with `KC_RAPC` (Right Alt, Parenthesis Close).
+- Replace any Shift key in your keymap with `KC_SFTENT` (Right Shift, Enter).
+
+## Keycodes
+
+|Keycode    |Description                                |
+|-----------|-------------------------------------------|
+|`KC_LSPO`  |Left Shift when held, `(` when tapped      |
+|`KC_RSPC`  |Right Shift when held, `)` when tapped     |
+|`KC_LCPO`  |Left Control when held, `(` when tapped    |
+|`KC_RCPC`  |Right Control when held, `)` when tapped   |
+|`KC_LAPO`  |Left Alt when held, `(` when tapped        |
+|`KC_RAPC`  |Right Alt when held, `)` when tapped       |
+|`KC_SFTENT`|Right Shift when held, Enter when tapped   |
+
+## Caveats
+
+Space Cadet's functionality can conflict with the default Command functionality when both Shift keys are held at the same time. See the [Command feature](feature_command.md) for info on how to change it, or make sure that Command is disabled in your `rules.mk` with:
+
+```make
+COMMAND_ENABLE = no
+```
+
+## Configuration
+
+By default Space Cadet assumes a US ANSI layout, but if your layout uses different keys for parentheses, you can redefine them in your `config.h`. In addition, you can redefine the modifier to send on tap, or even send no modifier at all. The new configuration defines bundle all options up into a single define of 3 key codes in this order: the `Modifier` when held or when used with other keys, the `Tap Modifer` sent when tapped (no modifier if `KC_TRNS`), finally the `Keycode` sent when tapped. Now keep in mind, mods from other keys will still apply to the `Keycode` if say `KC_RSFT` is held while tapping `KC_LSPO` key with `KC_TRNS` as the `Tap Modifer`.
+
+|Define          |Default                        |Description                                                                      |
+|----------------|-------------------------------|---------------------------------------------------------------------------------|
+|`LSPO_KEYS`     |`KC_LSFT, LSPO_MOD, LSPO_KEY`  |Send `KC_LSFT` when held, the mod and  key defined by `LSPO_MOD` and `LSPO_KEY`. |
+|`RSPC_KEYS`     |`KC_RSFT, RSPC_MOD, RSPC_KEY`  |Send `KC_RSFT` when held, the mod and  key defined by `RSPC_MOD` and `RSPC_KEY`. |
+|`LCPO_KEYS`     |`KC_LCTL, KC_LSFT, KC_9`       |Send `KC_LCTL` when held, the mod `KC_LSFT` with the key `KC_9` when tapped.     |
+|`RCPC_KEYS`     |`KC_RCTL, KC_RSFT, KC_0`       |Send `KC_RCTL` when held, the mod `KC_RSFT` with the key `KC_0` when tapped.     |
+|`LAPO_KEYS`     |`KC_LALT, KC_LSFT, KC_9`       |Send `KC_LALT` when held, the mod `KC_LSFT` with the key `KC_9` when tapped.     |
+|`RAPC_KEYS`     |`KC_RALT, KC_RSFT, KC_0`       |Send `KC_RALT` when held, the mod `KC_RSFT` with the key `KC_0` when tapped.     |
+|`SFTENT_KEYS`   |`KC_RSFT, KC_TRNS, SFTENT_KEY` |Send `KC_RSFT` when held, no mod with the key `SFTENT_KEY` when tapped.          |
+|`SPACE_CADET_MODIFIER_CARRYOVER`   |*Not defined* |Store current modifiers before the hold mod is pressed and use them with the tap mod and keycode. Useful for when you frequently release a modifier before triggering Space Cadet.  |
+
+
+## Obsolete Configuration
+
+These defines are used in the above defines internally to support backwards compatibility, so you may continue to use them, however the above defines open up a larger range of flexibility than before. As an example, say you want to not send any modifier when you tap just `KC_LSPO`, with the old defines you had an all or nothing choice of using the `DISABLE_SPACE_CADET_MODIFIER` define. Now you can define that key as: `#define LSPO_KEYS KC_LSFT, KC_TRNS, KC_9`. This tells the system to set Left Shift if held or used with other keys, then on tap send no modifier (transparent) with the `KC_9`.
+
+|Define                        |Default      |Description                                                       |
+|------------------------------|-------------|------------------------------------------------------------------|
+|`LSPO_KEY`                    |`KC_9`       |The keycode to send when Left Shift is tapped                     |
+|`RSPC_KEY`                    |`KC_0`       |The keycode to send when Right Shift is tapped                    |
+|`LSPO_MOD`                    |`KC_LSFT`    |The modifier to apply to `LSPO_KEY`                               |
+|`RSPC_MOD`                    |`KC_RSFT`    |The modifier to apply to `RSPC_KEY`                               |
+|`SFTENT_KEY`                  |`KC_ENT`     |The keycode to send when the Shift key is tapped                  |
+|`DISABLE_SPACE_CADET_MODIFIER`|*Not defined*|If defined, prevent the Space Cadet from applying a modifier      |

docs/feature_split_keyboard.md

@@ -0,0 +1,211 @@
+# Split Keyboard 
+
+Many keyboards in the QMK Firmware repo are "split" keyboards. They use two controllers—one plugging into USB, and the second connected by a serial or an I<sup>2</sup>C connection over a TRRS or similar cable. 
+
+Split keyboards can have a lot of benefits, but there is some additional work needed to get them enabled.  
+
+QMK Firmware has a generic implementation that is usable by any board, as well as numerous board specific implementations. 
+
+For this, we will mostly be talking about the generic implementation used by the Let's Split and other keyboards. 
+
+!> ARM is not yet supported for Split Keyboards.  Progress is being made, but we are not quite there, yet. 
+
+
+## Hardware Configuration
+
+This assumes that you're using two Pro Micro-compatible controllers, and are using TRRS jacks to connect to two halves. 
+
+### Required Hardware
+
+Apart from diodes and key switches for the keyboard matrix in each half, you will need 2x TRRS sockets and 1x TRRS cable.
+
+Alternatively, you can use any sort of cable and socket that has at least 3 wires. 
+
+If you want to use I<sup>2</sup>C to communicate between halves, you will need a cable with at least 4 wires and 2x 4.7kΩ pull-up resistors.
+
+#### Considerations 
+
+The most commonly used connection is a TRRS cable and jacks.  These provide 4 wires, making them very useful for split keyboards, and are easy to find. 
+
+However, since one of the wires carries VCC, this means that the boards are not hot pluggable. You should always disconnect the board from USB before unplugging and plugging in TRRS cables, or you can short the controller, or worse. 
+
+Another option is to use phone cables (as in, old school RJ-11/RJ-14 cables). Make sure that you use one that actually supports 4 wires/lanes.  
+
+However, USB cables, SATA cables, and even just 4 wires have been known to be used for communication between the controllers. 
+
+!> Using USB cables for communication between the controllers works just fine, but the connector could be mistaken for a normal USB connection and potentially short out the keyboard, depending on how it's wired.  For this reason, they are not recommended for connecting split keyboards.  
+
+### Serial Wiring
+
+The 3 wires of the TRS/TRRS cable need to connect GND, VCC, and D0 (aka PDO or pin 3) between the two Pro Micros. 
+
+?> Note that the pin used here is actually set by `SOFT_SERIAL_PIN` below.
+
+![serial wiring](https://i.imgur.com/C3D1GAQ.png)
+
+### I<sup>2</sup>C Wiring
+
+The 4 wires of the TRRS cable need to connect GND, VCC, and SCL and SDA (aka PD0/pin 3 and PD1/pin 2, respectively) between the two Pro Micros. 
+
+The pull-up resistors may be placed on either half. It is also possible to use 4 resistors and have the pull-ups in both halves, but this is unnecessary in simple use cases.
+
+![I2C wiring](https://i.imgur.com/Hbzhc6E.png)
+
+## Firmware Configuration
+
+To enable the split keyboard feature, add the following to your `rules.mk`: 
+
+```make
+SPLIT_KEYBOARD = yes
+```
+
+If you're using a custom transport (communication method), then you will also need to add: 
+
+```make
+SPLIT_TRANSPORT = custom
+```
+
+### Setting Handedness
+
+By default, the firmware does not know which side is which; it needs some help to determine that. There are several ways to do this, listed in order of precedence.
+
+#### Handedness by Pin
+
+You can configure the firmware to read a pin on the controller to determine handedness.  To do this, add the following to your `config.h` file:
+
+```c
+#define SPLIT_HAND_PIN B7
+```
+
+This will read the specified pin. If it's high, then the controller assumes it is the left hand, and if it's low, it's assumed to be the right side. 
+
+#### Handedness by EEPROM
+
+This method sets the keyboard's handedness by setting a flag in the persistent storage (`EEPROM`).  This is checked when the controller first starts up, and determines what half the keyboard is, and how to orient the keyboard layout. 
+
+
+To enable this method, add the following to your `config.h` file: 
+
+```c
+#define EE_HANDS
+```
+
+However, you'll have to flash the EEPROM files for the correct hand to each controller.  You can do this manually, or there are targets for avrdude and dfu to do this, while flashing the firmware: 
+
+* `:avrdude-split-left`
+* `:avrdude-split-right`
+* `:dfu-split-left`
+* `:dfu-split-right`
+* `:dfu-util-split-left`
+* `:dfu-util-split-right`
+
+This setting is not changed when re-initializing the EEPROM using the `EEP_RST` key, or using the `eeconfig_init()` function.  However, if you reset the EEPROM outside of the firmware's built in options (such as flashing a file that overwrites the `EEPROM`, like how the [QMK Toolbox]()'s "Reset EEPROM" button works), you'll need to re-flash the controller with the `EEPROM` files. 
+
+You can find the `EEPROM` files in the QMK firmware repo, [here](https://github.com/qmk/qmk_firmware/tree/master/quantum/split_common). 
+
+#### Handedness by `#define`
+
+You can set the handedness at compile time.  This is done by adding the following to your `config.h` file:
+
+```c
+#define MASTER_RIGHT
+```
+
+or 
+
+```c
+#define MASTER_LEFT
+```
+
+If neither are defined, the handedness defaults to `MASTER_LEFT`.
+
+
+### Communication Options
+
+Because not every split keyboard is identical, there are a number of additional options that can be configured in your `config.h` file.
+
+```c
+#define USE_I2C
+```
+
+This enables I<sup>2</sup>C support for split keyboards. This isn't strictly for communication, but can be used for OLED or other I<sup>2</sup>C-based devices. 
+
+```c
+#define SOFT_SERIAL_PIN D0
+```
+
+This sets the pin to be used for serial communication. If you're not using serial, you shouldn't need to define this.  
+
+However, if you are using serial and I<sup>2</sup>C on the board, you will need to set this, and to something other than D0 and D1 (as these are used for I<sup>2</sup>C communication).
+
+```c
+#define SELECT_SOFT_SERIAL_SPEED {#}`
+```
+
+If you're having issues with serial communication, you can change this value, as it controls the communication speed for serial.  The default is 1, and the possible values are:
+
+* **`0`**: about 189kbps (Experimental only)
+* **`1`**: about 137kbps (default)
+* **`2`**: about 75kbps
+* **`3`**: about 39kbps
+* **`4`**: about 26kbps
+* **`5`**: about 20kbps
+
+###  Hardware Configuration Options
+
+There are some settings that you may need to configure, based on how the hardware is set up. 
+
+```c
+#define MATRIX_ROW_PINS_RIGHT { <row pins> }
+#define MATRIX_COL_PINS_RIGHT { <col pins> }
+```
+
+This allows you to specify a different set of pins for the matrix on the right side.  This is useful if you have a board with differently-shaped halves that requires a different configuration (such as Keebio's Quefrency).
+
+```c
+#define DIRECT_PINS_RIGHT { { F1, F0, B0, C7 }, { F4, F5, F6, F7 } }
+```
+
+This allows you to specify a different set of direct pins for the right side.
+
+```c
+#define ENCODERS_PAD_A_RIGHT { encoder1a, encoder2a }
+#define ENCODERS_PAD_B_RIGHT { encoder1b, encoder2b }
+```
+
+This allows you to specify a different set of encoder pins for the right side.
+
+```c
+#define RGBLIGHT_SPLIT
+```
+
+This option enables synchronization of the RGB Light modes between the controllers of the split keyboard.  This is for keyboards that have RGB LEDs that are directly wired to the controller (that is, they are not using the "extra data" option on the TRRS cable).
+
+```c
+#define RGBLED_SPLIT { 6, 6 }
+```
+
+This sets how many LEDs are directly connected to each controller.  The first number is the left side, and the second number is the right side.  
+
+?> This setting implies that `RGBLIGHT_SPLIT` is enabled, and will forcibly enable it, if it's not.
+
+
+```c
+#define SPLIT_USB_DETECT
+```
+This option changes the startup behavior to detect an active USB connection when delegating master/slave. If this operation times out, then the half is assume to be a slave. This is the default behavior for ARM, and required for AVR Teensy boards (due to hardware limitations).
+
+?> This setting will stop the ability to demo using battery packs.
+
+```c
+#define SPLIT_USB_TIMEOUT 2500
+```
+This sets the maximum timeout when detecting master/slave when using `SPLIT_USB_DETECT`.
+
+## Additional Resources
+
+Nicinabox has a [very nice and detailed guide](https://github.com/nicinabox/lets-split-guide) for the Let's Split keyboard, that covers most everything you need to know, including troubleshooting information. 
+
+However, the RGB Light section is out of date, as it was written long before the RGB Split code was added to QMK Firmware. Instead, wire each strip up directly to the controller.
+
+<!-- I may port this information later, but for now ... it's very nice, and covers everything -->

docs/feature_stenography.md

@@ -0,0 +1,132 @@
+# Stenography in QMK
+
+[Stenography](https://en.wikipedia.org/wiki/Stenotype) is a method of writing most often used by court reports, closed-captioning, and real-time transcription for the deaf. In stenography words are chorded syllable by syllable with a mixture of spelling, phonetic, and shortcut (briefs) strokes. Professional stenographers can reach 200-300 WPM without any of the strain usually found in standard typing and with far fewer errors (>99.9% accuracy).
+
+The [Open Steno Project](http://www.openstenoproject.org/) has built an open-source program called Plover that provides real-time translation of steno strokes into words and commands. It has an established dictionary and supports
+
+## Plover with QWERTY Keyboard
+
+Plover can work with any standard QWERTY keyboard, although it is more efficient if the keyboard supports NKRO (n-key rollover) to allow Plover to see all the pressed keys at once. An example keymap for Plover can be found in `planck/keymaps/default`. Switching to the `PLOVER` layer adjusts the position of the keyboard to support the number bar.
+
+To use Plover with QMK just enable NKRO and optionally adjust your layout if you have anything other than a standard layout. You may also want to purchase some steno-friendly keycaps to make it easier to hit multiple keys.
+
+## Plover with Steno Protocol
+
+Plover also understands the language of several steno machines. QMK can speak a couple of these languages, TX Bolt and GeminiPR. An example layout can be found in `planck/keymaps/steno`.
+
+When QMK speaks to Plover over a steno protocol Plover will not use the keyboard as input. This means that you can switch back and forth between a standard keyboard and your steno keyboard, or even switch layers from Plover to standard and back without needing to activate/deactivate Plover.
+
+In this mode Plover expects to speak with a steno machine over a serial port so QMK will present itself to the operating system as a virtual serial port in addition to a keyboard. By default QMK will speak the TX Bolt protocol but can be switched to GeminiPR; the last protocol used is stored in non-volatile memory so QMK will use the same protocol on restart.
+
+> Note: Due to hardware limitations you may not be able to run both a virtual serial port and mouse emulation at the same time.
+
+### TX Bolt
+
+TX Bolt communicates the status of 24 keys over a very simple protocol in variable-sized (1-5 byte) packets.
+
+### GeminiPR
+
+GeminiPR encodes 42 keys into a 6-byte packet. While TX Bolt contains everything that is necessary for standard stenography, GeminiPR opens up many more options, including supporting non-English theories.
+
+## Configuring QMK for Steno
+
+Firstly, enable steno in your keymap's Makefile. You may also need disable mousekeys, extra keys, or another USB endpoint to prevent conflicts. The builtin USB stack for some processors only supports a certain number of USB endpoints and the virtual serial port needed for steno fills 3 of them.
+
+```Makefile
+STENO_ENABLE = yes
+MOUSEKEY_ENABLE = no
+```
+
+In your keymap create a new layer for Plover. You will need to include `keymap_steno.h`. See `planck/keymaps/steno/keymap.c` for an example. Remember to create a key to switch to the layer as well as a key for exiting the layer. If you would like to switch modes on the fly you can use the keycodes `QK_STENO_BOLT` and `QK_STENO_GEMINI`. If you only want to use one of the protocols you may set it up in your initialization function:
+
+```C
+void matrix_init_user() {
+  steno_set_mode(STENO_MODE_GEMINI); // or STENO_MODE_BOLT
+}
+```
+
+Once you have your keyboard flashed launch Plover. Click the 'Configure...' button. In the 'Machine' tab select the Stenotype Machine that corresponds to your desired protocol. Click the 'Configure...' button on this tab and enter the serial port or click 'Scan'. Baud rate is fine at 9600 (although you should be able to set as high as 115200 with no issues). Use the default settings for everything else (Data Bits: 8, Stop Bits: 1, Parity: N, no flow control).
+
+On the display tab click 'Open stroke display'. With Plover disabled you should be able to hit keys on your keyboard and see them show up in the stroke display window. Use this to make sure you have set up your keymap correctly. You are now ready to steno!
+
+## Learning Stenography
+
+* [Learn Plover!](https://sites.google.com/site/ploverdoc/)
+* [QWERTY Steno](http://qwertysteno.com/Home/)
+* [Steno Jig](https://joshuagrams.github.io/steno-jig/)
+* More resources at the Plover [Learning Stenography](https://github.com/openstenoproject/plover/wiki/Learning-Stenography) wiki
+
+## Interfacing with the code
+
+The steno code has three interceptible hooks. If you define these functions, they will be called at certain points in processing; if they return true, processing continues, otherwise it's assumed you handled things.
+
+```C
+bool send_steno_chord_user(steno_mode_t mode, uint8_t chord[6]);
+```
+
+This function is called when a chord is about to be sent. Mode will be one of `STENO_MODE_BOLT` or `STENO_MODE_GEMINI`. This represents the actual chord that would be sent via whichever protocol. You can modify the chord provided to alter what gets sent. Remember to return true if you want the regular sending process to happen.
+
+```C
+bool process_steno_user(uint16_t keycode, keyrecord_t *record) { return true; }
+```
+
+This function is called when a keypress has come in, before it is processed. The keycode should be one of `QK_STENO_BOLT`, `QK_STENO_GEMINI`, or one of the `STN_*` key values.
+
+```C
+bool postprocess_steno_user(uint16_t keycode, keyrecord_t *record, steno_mode_t mode, uint8_t chord[6], int8_t pressed);
+```
+
+This function is called after a key has been processed, but before any decision about whether or not to send a chord. If `IS_PRESSED(record->event)` is false, and `pressed` is 0 or 1, the chord will be sent shortly, but has not yet been sent. This is where to put hooks for things like, say, live displays of steno chords or keys.
+
+
+## Keycode Reference
+
+As defined in `keymap_steno.h`.
+
+> Note: TX Bolt does not support the full set of keys. The TX Bolt implementation in QMK will map the GeminiPR keys to the nearest TX Bolt key so that one key map will work for both.
+
+|GeminiPR|TX Bolt|Steno Key|
+|--------|-------|-----------|
+|`STN_N1`|`STN_NUM`|Number bar #1|
+|`STN_N2`|`STN_NUM`|Number bar #2|
+|`STN_N3`|`STN_NUM`|Number bar #3|
+|`STN_N4`|`STN_NUM`|Number bar #4|
+|`STN_N5`|`STN_NUM`|Number bar #5|
+|`STN_N6`|`STN_NUM`|Number bar #6|
+|`STN_N7`|`STN_NUM`|Number bar #7|
+|`STN_N8`|`STN_NUM`|Number bar #8|
+|`STN_N9`|`STN_NUM`|Number bar #9|
+|`STN_NA`|`STN_NUM`|Number bar #A|
+|`STN_NB`|`STN_NUM`|Number bar #B|
+|`STN_NC`|`STN_NUM`|Number bar #C|
+|`STN_S1`|`STN_SL`| `S-` upper|
+|`STN_S2`|`STN_SL`| `S-` lower|
+|`STN_TL`|`STN_TL`| `T-`|
+|`STN_KL`|`STN_KL`| `K-`|
+|`STN_PL`|`STN_PL`| `P-`|
+|`STN_WL`|`STN_WL`| `W-`|
+|`STN_HL`|`STN_HL`| `H-`|
+|`STN_RL`|`STN_RL`| `R-`|
+|`STN_A`|`STN_A`| `A` vowel|
+|`STN_O`|`STN_O`| `O` vowel|
+|`STN_ST1`|`STN_STR`| `*` upper-left |
+|`STN_ST2`|`STN_STR`| `*` lower-left|
+|`STN_ST3`|`STN_STR`| `*` upper-right|
+|`STN_ST4`|`STN_STR`| `*` lower-right|
+|`STN_E`|`STN_E`| `E` vowel|
+|`STN_U`|`STN_U`| `U` vowel|
+|`STN_FR`|`STN_FR`| `-F`|
+|`STN_PR`|`STN_PR`| `-P`|
+|`STN_RR`|`STN_RR`| `-R`|
+|`STN_BR`|`STN_BR`| `-B`|
+|`STN_LR`|`STN_LR`| `-L`|
+|`STN_GR`|`STN_GR`| `-G`|
+|`STN_TR`|`STN_TR`| `-T`|
+|`STN_SR`|`STN_SR`| `-S`|
+|`STN_DR`|`STN_DR`| `-D`|
+|`STN_ZR`|`STN_ZR`| `-Z`|
+|`STN_FN`|| (GeminiPR only)|
+|`STN_RES1`||(GeminiPR only)|
+|`STN_RES2`||(GeminiPR only)|
+|`STN_PWR`||(GeminiPR only)|
+

docs/feature_swap_hands.md

@@ -0,0 +1,30 @@
+# Swap-Hands Action
+
+The swap-hands action allows support for one-handed typing without requiring a separate layer. Set `SWAP_HANDS_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`
+
+## 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:
+
+```C
+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). Yes, this is confusing.
+
+## Swap Keycodes
+
+|Key        |Description                                                              |
+|-----------|-------------------------------------------------------------------------|
+|`SH_T(key)`|Sends `key` with a tap; momentary swap when held.                        |
+|`SH_ON`    |Turns on swapping and leaves it on.                                      |
+|`SH_OFF`   |Turn off swapping and leaves it off. Good for returning to a known state.|
+|`SH_MON`   |Swaps hands when pressed, returns to normal when released (momentary).   |
+|`SH_MOFF`  |Momentarily turns off swap.                                              |
+|`SH_TG`    |Toggles swap on and off with every key press.                            |
+|`SH_TT`    |Toggles with a tap; momentary when held.                                 |

docs/feature_tap_dance.md

@@ -0,0 +1,520 @@
+# Tap Dance: A Single Key Can Do 3, 5, or 100 Different Things
+
+## Introduction
+Hit the semicolon key once, send a semicolon. Hit it twice, rapidly -- send a colon. Hit it three times, and your keyboard's LEDs do a wild dance. That's just one example of what Tap Dance can do. It's one of the nicest community-contributed features in the firmware, conceived and created by [algernon](https://github.com/algernon) in [#451](https://github.com/qmk/qmk_firmware/pull/451). Here's how algernon describes the feature:
+
+With this feature one can specify keys that behave differently, based on the amount of times they have been tapped, and when interrupted, they get handled before the interrupter.
+
+## Explanatory Comparison with `ACTION_FUNCTION_TAP`
+`ACTION_FUNCTION_TAP` can offer similar functionality to Tap Dance, but it's worth noting some important differences. To do this, let's explore a certain setup! We want one key to send `Space` on single-tap, but `Enter` on double-tap.
+
+With `ACTION_FUNCTION_TAP`, it is quite a rain-dance to set this up, and has the problem that when the sequence is interrupted, the interrupting key will be sent first. Thus, `SPC a` will result in `a SPC` being sent, if `SPC` and `a` are both typed within `TAPPING_TERM`. With the Tap Dance feature, that'll come out correctly as `SPC a` (even if both `SPC` and `a` are typed within the `TAPPING_TERM`.
+
+To achieve this correct handling of interrupts, the implementation of Tap Dance hooks into two parts of the system: `process_record_quantum()`, and the matrix scan. These two parts are explained below, but for now the point to note is that we need the latter to be able to time out a tap sequence even when a key is not being pressed. That way, `SPC` alone will time out and register after `TAPPING_TERM` time.
+
+## How to Use Tap Dance
+But enough of the generalities; lets look at how to actually use Tap Dance!
+
+First, you will need `TAP_DANCE_ENABLE=yes` in your `rules.mk`, because the feature is disabled by default. This adds a little less than 1k to the firmware size. 
+
+Optionally, you might want to set a custom `TAPPING_TERM` time by adding something like this in you `config.h`:
+
+```
+#define TAPPING_TERM 175
+```
+
+The `TAPPING_TERM` time is the maximum time allowed between taps of your Tap Dance key, and is measured in milliseconds. For example, if you used the above `#define` statement and set up a Tap Dance key that sends `Space` on single-tap and `Enter` on double-tap, then this key will send `ENT` only if you tap this key twice in less than 175ms. If you tap the key, wait more than 175ms, and tap the key again you'll end up sending `SPC SPC` instead. 
+
+Next, you will want to define some tap-dance keys, which is easiest to do with the `TD()` macro, that - similar to `F()` - takes a number, which will later be used as an index into the `tap_dance_actions` array. 
+
+After this, you'll want to use the `tap_dance_actions` array to specify what actions shall be taken when a tap-dance key is in action. Currently, there are five possible options:
+
+* `ACTION_TAP_DANCE_DOUBLE(kc1, kc2)`: Sends the `kc1` keycode when tapped once, `kc2` otherwise. When the key is held, the appropriate keycode is registered: `kc1` when pressed and held, `kc2` when tapped once, then pressed and held.
+* `ACTION_TAP_DANCE_LAYER_MOVE(kc, layer)`: Sends the `kc` keycode when tapped once, or moves to `layer`. (this functions like the `TO` layer keycode).
+    * This is the same as `ACTION_TAP_DANCE_DUAL_ROLE`, but renamed to something that is clearer about its functionality.  Both names will work.
+* `ACTION_TAP_DANCE_LAYER_TOGGLE(kc, layer)`: Sends the `kc` keycode when tapped once, or toggles the state of `layer`. (this functions like the `TG` layer keycode).
+* `ACTION_TAP_DANCE_FN(fn)`: Calls the specified function - defined in the user keymap - with the final tap count of the tap dance action.
+* `ACTION_TAP_DANCE_FN_ADVANCED(on_each_tap_fn, on_dance_finished_fn, on_dance_reset_fn)`: Calls the first specified function - defined in the user keymap - on every tap, the second function when the dance action finishes (like the previous option), and the last function when the tap dance action resets.
+* `ACTION_TAP_DANCE_FN_ADVANCED_TIME(on_each_tap_fn, on_dance_finished_fn, on_dance_reset_fn, tap_specific_tapping_term)`: This functions identically to the `ACTION_TAP_DANCE_FN_ADVANCED` function, but uses a custom tapping term for it, instead of the predefined `TAPPING_TERM`.
+
+The first option is enough for a lot of cases, that just want dual roles. For example, `ACTION_TAP_DANCE_DOUBLE(KC_SPC, KC_ENT)` will result in `Space` being sent on single-tap, `Enter` otherwise. 
+
+!> Keep in mind that only [basic keycodes](keycodes_basic.md) are supported here. Custom keycodes are not supported.
+
+Similar to the first option, the second option is good for simple layer-switching cases.
+
+For more complicated cases, use the third or fourth options (examples of each are listed below). 
+
+Finally, the fifth option is particularly useful if your non-Tap-Dance keys start behaving weirdly after adding the code for your Tap Dance keys. The likely problem is that you changed the `TAPPING_TERM` time to make your Tap Dance keys easier for you to use, and that this has changed the way your other keys handle interrupts.
+
+## Implementation Details
+Well, that's the bulk of it! You should now be able to work through the examples below, and to develop your own Tap Dance functionality. But if you want a deeper understanding of what's going on behind the scenes, then read on for the explanation of how it all works!
+
+The main entry point is `process_tap_dance()`, called from `process_record_quantum()`, which is run for every keypress, and our handler gets to run early. This function checks whether the key pressed is a tap-dance key. If it is not, and a tap-dance was in action, we handle that first, and enqueue the newly pressed key. If it is a tap-dance key, then we check if it is the same as the already active one (if there's one active, that is). If it is not, we fire off the old one first, then register the new one. If it was the same, we increment the counter and reset the timer.
+
+This means that you have `TAPPING_TERM` time to tap the key again; you do not have to input all the taps within a single `TAPPING_TERM` timeframe. This allows for longer tap counts, with minimal impact on responsiveness.
+
+Our next stop is `matrix_scan_tap_dance()`. This handles the timeout of tap-dance keys.
+
+For the sake of flexibility, tap-dance actions can be either a pair of keycodes, or a user function. The latter allows one to handle higher tap counts, or do extra things, like blink the LEDs, fiddle with the backlighting, and so on. This is accomplished by using an union, and some clever macros.
+
+# Examples
+
+## Simple Example
+
+Here's a simple example for a single definition:
+
+1. In your `rules.mk`, add `TAP_DANCE_ENABLE = yes`
+2. In your `config.h` (which you can copy from `qmk_firmware/keyboards/planck/config.h` to your keymap directory), add `#define TAPPING_TERM 200`
+3. In your `keymap.c` file, define the variables and definitions, then add to your keymap:
+
+```c
+//Tap Dance Declarations
+enum {
+  TD_ESC_CAPS = 0
+};
+
+//Tap Dance Definitions
+qk_tap_dance_action_t tap_dance_actions[] = {
+  //Tap once for Esc, twice for Caps Lock
+  [TD_ESC_CAPS]  = ACTION_TAP_DANCE_DOUBLE(KC_ESC, KC_CAPS)
+// Other declarations would go here, separated by commas, if you have them
+};
+
+//In Layer declaration, add tap dance item in place of a key code
+TD(TD_ESC_CAPS)
+```
+
+## Complex Examples
+
+This section details several complex tap dance examples.
+All the enums used in the examples are declared like this:
+
+```c
+// Enums defined for all examples:
+enum {
+ CT_SE = 0,
+ CT_CLN,
+ CT_EGG,
+ CT_FLSH,
+ X_TAP_DANCE
+};
+```
+### Example 1: Send `:` on Single Tap, `;` on Double Tap
+```c
+void dance_cln_finished (qk_tap_dance_state_t *state, void *user_data) {
+  if (state->count == 1) {
+    register_code (KC_RSFT);
+    register_code (KC_SCLN);
+  } else {
+    register_code (KC_SCLN);
+  }
+}
+
+void dance_cln_reset (qk_tap_dance_state_t *state, void *user_data) {
+  if (state->count == 1) {
+    unregister_code (KC_RSFT);
+    unregister_code (KC_SCLN);
+  } else {
+    unregister_code (KC_SCLN);
+  }
+}
+
+//All tap dance functions would go here. Only showing this one.
+qk_tap_dance_action_t tap_dance_actions[] = {
+ [CT_CLN] = ACTION_TAP_DANCE_FN_ADVANCED (NULL, dance_cln_finished, dance_cln_reset)
+};
+```
+### Example 2: Send "Safety Dance!" After 100 Taps
+```c
+void dance_egg (qk_tap_dance_state_t *state, void *user_data) {
+  if (state->count >= 100) {
+    SEND_STRING ("Safety dance!");
+    reset_tap_dance (state);
+  }
+}
+
+qk_tap_dance_action_t tap_dance_actions[] = {
+ [CT_EGG] = ACTION_TAP_DANCE_FN (dance_egg)
+};
+```
+
+### Example 3: Turn LED Lights On Then Off, One at a Time
+
+```c
+// on each tap, light up one led, from right to left
+// on the forth tap, turn them off from right to left
+void dance_flsh_each(qk_tap_dance_state_t *state, void *user_data) {
+  switch (state->count) {
+  case 1:
+    ergodox_right_led_3_on();
+    break;
+  case 2:
+    ergodox_right_led_2_on();
+    break;
+  case 3:
+    ergodox_right_led_1_on();
+    break;
+  case 4:
+    ergodox_right_led_3_off();
+    _delay_ms(50);
+    ergodox_right_led_2_off();
+    _delay_ms(50);
+    ergodox_right_led_1_off();
+  }
+}
+
+// on the fourth tap, set the keyboard on flash state
+void dance_flsh_finished(qk_tap_dance_state_t *state, void *user_data) {
+  if (state->count >= 4) {
+    reset_keyboard();
+    reset_tap_dance(state);
+  }
+}
+
+// if the flash state didn't happen, then turn off LEDs, left to right
+void dance_flsh_reset(qk_tap_dance_state_t *state, void *user_data) {
+  ergodox_right_led_1_off();
+  _delay_ms(50);
+  ergodox_right_led_2_off();
+  _delay_ms(50);
+  ergodox_right_led_3_off();
+}
+
+//All tap dances now put together. Example 3 is "CT_FLASH"
+qk_tap_dance_action_t tap_dance_actions[] = {
+  [CT_SE]  = ACTION_TAP_DANCE_DOUBLE (KC_SPC, KC_ENT)
+ ,[CT_CLN] = ACTION_TAP_DANCE_FN_ADVANCED (NULL, dance_cln_finished, dance_cln_reset)
+ ,[CT_EGG] = ACTION_TAP_DANCE_FN (dance_egg)
+ ,[CT_FLSH] = ACTION_TAP_DANCE_FN_ADVANCED (dance_flsh_each, dance_flsh_finished, dance_flsh_reset)
+};
+```
+
+### Example 4: 'Quad Function Tap-Dance'
+
+By [DanielGGordon](https://github.com/danielggordon)
+
+Allow one key to have 4 (or more) functions, depending on number of presses, and if the key is held or tapped.
+Below is a specific example:
+*  Tap = Send `x`
+*  Hold = Send `Control`
+*  Double Tap = Send `Escape`
+*  Double Tap and Hold = Send `Alt`
+
+## Setup
+
+You will need a few things that can be used for 'Quad Function Tap-Dance'. 
+
+You'll need to add these to the top of your `keymap.c` file, before your keymap. 
+
+```c
+typedef struct {
+  bool is_press_action;
+  int state;
+} tap;
+
+enum {
+  SINGLE_TAP = 1,
+  SINGLE_HOLD = 2,
+  DOUBLE_TAP = 3,
+  DOUBLE_HOLD = 4,
+  DOUBLE_SINGLE_TAP = 5, //send two single taps
+  TRIPLE_TAP = 6,
+  TRIPLE_HOLD = 7
+};
+
+//Tap dance enums
+enum {
+  X_CTL = 0,
+  SOME_OTHER_DANCE
+};
+
+int cur_dance (qk_tap_dance_state_t *state);
+
+//for the x tap dance. Put it here so it can be used in any keymap
+void x_finished (qk_tap_dance_state_t *state, void *user_data);
+void x_reset (qk_tap_dance_state_t *state, void *user_data);
+
+```
+
+Now, at the bottom of your `keymap.c` file, you'll need to add the following: 
+
+```c
+/* Return an integer that corresponds to what kind of tap dance should be executed.
+ *
+ * How to figure out tap dance state: interrupted and pressed.
+ *
+ * Interrupted: If the state of a dance dance is "interrupted", that means that another key has been hit
+ *  under the tapping term. This is typically indicitive that you are trying to "tap" the key.
+ *
+ * Pressed: Whether or not the key is still being pressed. If this value is true, that means the tapping term
+ *  has ended, but the key is still being pressed down. This generally means the key is being "held".
+ *
+ * One thing that is currenlty not possible with qmk software in regards to tap dance is to mimic the "permissive hold"
+ *  feature. In general, advanced tap dances do not work well if they are used with commonly typed letters.
+ *  For example "A". Tap dances are best used on non-letter keys that are not hit while typing letters.
+ *
+ * Good places to put an advanced tap dance:
+ *  z,q,x,j,k,v,b, any function key, home/end, comma, semi-colon
+ *
+ * Criteria for "good placement" of a tap dance key:
+ *  Not a key that is hit frequently in a sentence
+ *  Not a key that is used frequently to double tap, for example 'tab' is often double tapped in a terminal, or
+ *    in a web form. So 'tab' would be a poor choice for a tap dance.
+ *  Letters used in common words as a double. For example 'p' in 'pepper'. If a tap dance function existed on the
+ *    letter 'p', the word 'pepper' would be quite frustating to type.
+ *
+ * For the third point, there does exist the 'DOUBLE_SINGLE_TAP', however this is not fully tested
+ *
+ */
+int cur_dance (qk_tap_dance_state_t *state) {
+  if (state->count == 1) {
+    if (state->interrupted || !state->pressed)  return SINGLE_TAP;
+    //key has not been interrupted, but they key is still held. Means you want to send a 'HOLD'.
+    else return SINGLE_HOLD;
+  }
+  else if (state->count == 2) {
+    /*
+     * DOUBLE_SINGLE_TAP is to distinguish between typing "pepper", and actually wanting a double tap
+     * action when hitting 'pp'. Suggested use case for this return value is when you want to send two
+     * keystrokes of the key, and not the 'double tap' action/macro.
+    */
+    if (state->interrupted) return DOUBLE_SINGLE_TAP;
+    else if (state->pressed) return DOUBLE_HOLD;
+    else return DOUBLE_TAP;
+  }
+  //Assumes no one is trying to type the same letter three times (at least not quickly).
+  //If your tap dance key is 'KC_W', and you want to type "www." quickly - then you will need to add
+  //an exception here to return a 'TRIPLE_SINGLE_TAP', and define that enum just like 'DOUBLE_SINGLE_TAP'
+  if (state->count == 3) {
+    if (state->interrupted || !state->pressed)  return TRIPLE_TAP;
+    else return TRIPLE_HOLD;
+  }
+  else return 8; //magic number. At some point this method will expand to work for more presses
+}
+
+//instanalize an instance of 'tap' for the 'x' tap dance.
+static tap xtap_state = {
+  .is_press_action = true,
+  .state = 0
+};
+
+void x_finished (qk_tap_dance_state_t *state, void *user_data) {
+  xtap_state.state = cur_dance(state);
+  switch (xtap_state.state) {
+    case SINGLE_TAP: register_code(KC_X); break;
+    case SINGLE_HOLD: register_code(KC_LCTRL); break;
+    case DOUBLE_TAP: register_code(KC_ESC); break;
+    case DOUBLE_HOLD: register_code(KC_LALT); break;
+    case DOUBLE_SINGLE_TAP: register_code(KC_X); unregister_code(KC_X); register_code(KC_X);
+    //Last case is for fast typing. Assuming your key is `f`:
+    //For example, when typing the word `buffer`, and you want to make sure that you send `ff` and not `Esc`.
+    //In order to type `ff` when typing fast, the next character will have to be hit within the `TAPPING_TERM`, which by default is 200ms.
+  }
+}
+
+void x_reset (qk_tap_dance_state_t *state, void *user_data) {
+  switch (xtap_state.state) {
+    case SINGLE_TAP: unregister_code(KC_X); break;
+    case SINGLE_HOLD: unregister_code(KC_LCTRL); break;
+    case DOUBLE_TAP: unregister_code(KC_ESC); break;
+    case DOUBLE_HOLD: unregister_code(KC_LALT);
+    case DOUBLE_SINGLE_TAP: unregister_code(KC_X);
+  }
+  xtap_state.state = 0;
+}
+
+qk_tap_dance_action_t tap_dance_actions[] = {
+  [X_CTL]     = ACTION_TAP_DANCE_FN_ADVANCED(NULL,x_finished, x_reset)
+};
+```
+
+And then simply use `TD(X_CTL)` anywhere in your keymap.
+
+If you want to implement this in your userspace, then you may want to check out how [DanielGGordon](https://github.com/qmk/qmk_firmware/tree/master/users/gordon) has implemented this in their userspace.
+
+### Example 5: Using tap dance for advanced mod-tap and layer-tap keys
+
+Tap dance can be used to emulate `MT()` and `LT()` behavior when the tapped code is not a basic keycode. This is useful to send tapped keycodes that normally require `Shift`, such as parentheses or curly braces—or other modified keycodes, such as `Control + X`.
+
+Below your layers and custom keycodes, add the following:
+
+```c
+// tapdance keycodes
+enum td_keycodes {
+  ALT_LP // Our example key: `LALT` when held, `(` when tapped. Add additional keycodes for each tapdance.
+};
+
+// define a type containing as many tapdance states as you need
+typedef enum {
+  SINGLE_TAP,
+  SINGLE_HOLD,
+  DOUBLE_SINGLE_TAP
+} td_state_t;
+
+// create a global instance of the tapdance state type
+static td_state_t td_state;
+
+// declare your tapdance functions:
+
+// function to determine the current tapdance state
+int cur_dance (qk_tap_dance_state_t *state);
+
+// `finished` and `reset` functions for each tapdance keycode
+void altlp_finished (qk_tap_dance_state_t *state, void *user_data);
+void altlp_reset (qk_tap_dance_state_t *state, void *user_data);
+```
+
+Below your `LAYOUT`, define each of the tapdance functions:
+
+```c
+// determine the tapdance state to return
+int cur_dance (qk_tap_dance_state_t *state) {
+  if (state->count == 1) {
+    if (state->interrupted || !state->pressed) { return SINGLE_TAP; }
+    else { return SINGLE_HOLD; }
+  }
+  if (state->count == 2) { return DOUBLE_SINGLE_TAP; }
+  else { return 3; } // any number higher than the maximum state value you return above
+}
+ 
+// handle the possible states for each tapdance keycode you define:
+
+void altlp_finished (qk_tap_dance_state_t *state, void *user_data) {
+  td_state = cur_dance(state);
+  switch (td_state) {
+    case SINGLE_TAP:
+      register_code16(KC_LPRN);
+      break;
+    case SINGLE_HOLD:
+      register_mods(MOD_BIT(KC_LALT)); // for a layer-tap key, use `layer_on(_MY_LAYER)` here
+      break;
+    case DOUBLE_SINGLE_TAP: // allow nesting of 2 parens `((` within tapping term
+      tap_code16(KC_LPRN);
+      register_code16(KC_LPRN);
+  }
+}
+
+void altlp_reset (qk_tap_dance_state_t *state, void *user_data) {
+  switch (td_state) {
+    case SINGLE_TAP:
+      unregister_code16(KC_LPRN);
+      break;
+    case SINGLE_HOLD:
+      unregister_mods(MOD_BIT(KC_LALT)); // for a layer-tap key, use `layer_off(_MY_LAYER)` here
+      break;
+    case DOUBLE_SINGLE_TAP:
+      unregister_code16(KC_LPRN);
+  }
+}
+
+// define `ACTION_TAP_DANCE_FN_ADVANCED()` for each tapdance keycode, passing in `finished` and `reset` functions
+qk_tap_dance_action_t tap_dance_actions[] = {
+  [ALT_LP] = ACTION_TAP_DANCE_FN_ADVANCED(NULL, altlp_finished, altlp_reset)
+};
+```
+
+Wrap each tapdance keycode in `TD()` when including it in your keymap, e.g. `TD(ALT_LP)`.
+
+### Example 6: Using tap dance for momentary-layer-switch and layer-toggle keys
+
+Tap Dance can be used to mimic MO(layer) and TG(layer) functionality. For this example, we will set up a key to function as `KC_QUOT` on single-tap, as `MO(_MY_LAYER)` on single-hold, and `TG(_MY_LAYER)` on double-tap.
+
+The first step is to include the following code towards the beginning of your `keymap.c`:
+
+```c
+typedef struct {
+  bool is_press_action;
+  int state;
+} tap;
+
+//Define a type for as many tap dance states as you need
+enum {
+  SINGLE_TAP = 1,
+  SINGLE_HOLD = 2,
+  DOUBLE_TAP = 3
+};
+
+enum {
+  QUOT_LAYR = 0     //Our custom tap dance key; add any other tap dance keys to this enum 
+};
+
+//Declare the functions to be used with your tap dance key(s)
+
+//Function associated with all tap dances
+int cur_dance (qk_tap_dance_state_t *state);
+
+//Functions associated with individual tap dances
+void ql_finished (qk_tap_dance_state_t *state, void *user_data);
+void ql_reset (qk_tap_dance_state_t *state, void *user_data);
+```
+
+Towards the bottom of your `keymap.c`, include the following code:
+
+```c
+//Determine the current tap dance state
+int cur_dance (qk_tap_dance_state_t *state) {
+  if (state->count == 1) {
+    if (!state->pressed) {
+      return SINGLE_TAP;
+    } else {
+      return SINGLE_HOLD;
+    }
+  } else if (state->count == 2) {
+    return DOUBLE_TAP;
+  }
+  else return 8;
+}
+
+//Initialize tap structure associated with example tap dance key
+static tap ql_tap_state = {
+  .is_press_action = true,
+  .state = 0
+};
+
+//Functions that control what our tap dance key does
+void ql_finished (qk_tap_dance_state_t *state, void *user_data) {
+  ql_tap_state.state = cur_dance(state);
+  switch (ql_tap_state.state) {
+    case SINGLE_TAP: 
+      tap_code(KC_QUOT); 
+      break;
+    case SINGLE_HOLD: 
+      layer_on(_MY_LAYER); 
+      break;
+    case DOUBLE_TAP: 
+      //check to see if the layer is already set
+      if (layer_state_is(_MY_LAYER)) {
+        //if already set, then switch it off
+        layer_off(_MY_LAYER);
+      } else { 
+        //if not already set, then switch the layer on
+        layer_on(_MY_LAYER);
+      }
+      break;
+  }
+}
+
+void ql_reset (qk_tap_dance_state_t *state, void *user_data) {
+  //if the key was held down and now is released then switch off the layer
+  if (ql_tap_state.state==SINGLE_HOLD) {
+    layer_off(_MY_LAYER);
+  }
+  ql_tap_state.state = 0;
+}
+
+//Associate our tap dance key with its functionality
+qk_tap_dance_action_t tap_dance_actions[] = {
+  [QUOT_LAYR] = ACTION_TAP_DANCE_FN_ADVANCED_TIME(NULL, ql_finished, ql_reset, 275)
+};
+```
+
+The above code is similar to that used in previous examples. The one point to note is that we need to be able to check which layers are active at any time so we can toggle them if needed. To do this we use the `layer_state_is( layer )` function which returns `true` if the given `layer` is active.
+
+The use of `cur_dance()` and `ql_tap_state` mirrors the above examples.
+
+The `case:SINGLE_TAP` in `ql_finished` is similar to the above examples. The `case:SINGLE_HOLD` works in conjunction with `ql_reset()` to switch to `_MY_LAYER` while the tap dance key is held, and to switch away from `_MY_LAYER` when the key is released. This mirrors the use of `MO(_MY_LAYER)`. The `case:DOUBLE_TAP` works by checking whether `_MY_LAYER` is the active layer, and toggling it on or off accordingly. This mirrors the use of `TG(_MY_LAYER)`.
+
+`tap_dance_actions[]` works similar to the above examples. Note that I used `ACTION_TAP_DANCE_FN_ADVANCED_TIME()` instead of `ACTION_TAP_DANCE_FN_ADVANCED()`. This is because I like my `TAPPING_TERM` to be short (~175ms) for my non-tap-dance keys but find that this is too quick for me to reliably complete tap dance actions - thus the increased time of 275ms here.
+
+Finally, to get this tap dance key working, be sure to include `TD(QUOT_LAYR)` in your `keymaps[]`.

docs/feature_terminal.md

@@ -0,0 +1,107 @@
+# Terminal
+
+> This feature is currently *huge*, and should probably only be put on boards with a lot of memory, or for fun.
+
+The terminal feature is a command-line-like interface designed to communicate through a text editor with keystrokes. It's beneficial to turn off auto-indent features in your editor.
+
+To enable, stick this in your `rules.mk` or `Makefile`:
+
+    TERMINAL_ENABLE = yes
+
+And use the `TERM_ON` and `TERM_OFF` keycodes to turn it on or off.
+
+When enabled, a `> ` prompt will appear, where you'll be able to type, backspace (a bell will ding if you reach the beginning and audio is enabled), and hit enter to send the command. Arrow keys are currently disabled so it doesn't get confused. Moving your cursor around with the mouse is discouraged.
+
+`#define TERMINAL_HELP` enables some other output helpers that aren't really needed with this page.
+
+Pressing "up" and "down" will allow you to cycle through the past 5 commands entered.
+
+## Future Ideas
+
+* Keyboard/user-extensible commands
+* Smaller footprint
+* Arrow key support
+* Command history - Done
+* SD card support
+* LCD support for buffer display
+* Keycode -> name string LUT
+* Layer status
+* *Analog/digital port read/write*
+* RGB mode stuff
+* Macro definitions
+* EEPROM read/write
+* Audio control
+
+## Current Commands
+
+### `about`
+
+Prints out the current version of QMK with a build date:
+
+```
+> about
+QMK Firmware
+  v0.5.115-7-g80ed73-dirty
+  Built: 2017-08-29-20:24:44
+```
+
+
+### `print-buffer`
+
+Outputs the last 5 commands entered
+
+```
+> print-buffer
+0. print-buffer
+1. help
+2. about
+3. keymap 0
+4. help
+5. flush-buffer
+```
+
+### `flush-buffer`
+
+Clears command buffer
+```
+> flush-buffer
+Buffer cleared!
+```
+
+
+### `help`
+
+
+Prints out the available commands:
+
+```
+> help
+commands available:
+  about help keycode keymap exit print-buffer flush-buffer
+```
+
+### `keycode <layer> <row> <col>`
+
+Prints out the keycode value of a certain layer, row, and column:
+
+```
+> keycode 0 1 0
+0x29 (41)
+```
+
+### `keymap <layer>`
+
+Prints out the entire keymap for a certain layer
+
+```
+> keymap 0
+0x002b, 0x0014, 0x001a, 0x0008, 0x0015, 0x0017, 0x001c, 0x0018, 0x000c, 0x0012, 0x0013, 0x002a,
+0x0029, 0x0004, 0x0016, 0x0007, 0x0009, 0x000a, 0x000b, 0x000d, 0x000e, 0x000f, 0x0033, 0x0034,
+0x00e1, 0x001d, 0x001b, 0x0006, 0x0019, 0x0005, 0x0011, 0x0010, 0x0036, 0x0037, 0x0038, 0x0028,
+0x5cd6, 0x00e0, 0x00e2, 0x00e3, 0x5cd4, 0x002c, 0x002c, 0x5cd5, 0x0050, 0x0051, 0x0052, 0x004f,
+>
+```
+
+### `exit`
+
+Exits the terminal - same as `TERM_OFF`.

docs/feature_thermal_printer.md

@@ -0,0 +1,10 @@
+# Thermal Printer
+
+<!-- FIXME: Describe thermal printers support here. -->
+
+## Thermal Printer Keycodes
+
+|Key        |Description                             |
+|-----------|----------------------------------------|
+|`PRINT_ON` |Start printing everything the user types|
+|`PRINT_OFF`|Stop printing everything the user types |

docs/feature_unicode.md

@@ -0,0 +1,233 @@
+# Unicode Support
+
+Unicode characters can be input straight from your keyboard! There are some limitations, however.
+
+QMK has three different methods for enabling Unicode input and defining keycodes:
+
+## Basic Unicode
+
+This method supports Unicode code points up to `0x7FFF`. This covers characters for most modern languages, as well as symbols, but it doesn't cover emoji.
+
+Add the following to your `rules.mk`:
+
+```make
+UNICODE_ENABLE = yes
+```
+
+Then add `UC(c)` keycodes to your keymap, where _c_ is the code point (preferably in hexadecimal, up to 4 digits long). For example: `UC(0x45B)`, `UC(0x30C4)`.
+
+## Unicode Map
+
+This method supports all possible code points (up to `0x10FFFF`); however, you need to maintain a separate mapping table in your keymap file, which may contain at most 16384 entries.
+
+Add the following to your `rules.mk`:
+
+```make
+UNICODEMAP_ENABLE = yes
+```
+
+Then add `X(i)` keycodes to your keymap, where _i_ is an array index into the mapping table:
+
+```c
+enum unicode_names {
+    BANG,
+    IRONY,
+    SNEK
+};
+
+const uint32_t PROGMEM unicode_map[] = {
+    [BANG]  = 0x203D,  // ‽
+    [IRONY] = 0x2E2E,  // ⸮
+    [SNEK]  = 0x1F40D, // 🐍
+};
+```
+
+Then you can use `X(BANG)`, `X(SNEK)` etc. in your keymap.
+
+### Lower and Upper Case
+
+Characters often come in lower and upper case pairs, such as å and Å. To make inputting these characters easier, you can use `XP(i, j)` in your keymap, where _i_ and _j_ are the mapping table indices of the lower and upper case character, respectively. If you're holding down Shift or have Caps Lock turned on when you press the key, the second (upper case) character will be inserted; otherwise, the first (lower case) version will appear.
+
+This is most useful when creating a keymap for an international layout with special characters. Instead of having to put the lower and upper case versions of a character on separate keys, you can have them both on the same key by using `XP()`. This helps blend Unicode keys in with regular alphas.
+
+Due to keycode size constraints, _i_ and _j_ can each only refer to one of the first 128 characters in your `unicode_map`. In other words, 0 ≤ _i_ ≤ 127 and 0 ≤ _j_ ≤ 127. This is enough for most use cases, but if you'd like to customize the index calculation, you can override the [`unicodemap_index()`](https://github.com/qmk/qmk_firmware/blob/71f640d47ee12c862c798e1f56392853c7b1c1a8/quantum/process_keycode/process_unicodemap.c#L40) function. This also allows you to, say, check Ctrl instead of Shift/Caps.
+
+## UCIS
+
+This method also supports all possible code points. As with the Unicode Map method, you need to maintain a mapping table in your keymap file. However, there are no built-in keycodes for this feature — you have to create a custom keycode or function that invokes this functionality.
+
+Add the following to your `rules.mk`:
+
+```make
+UCIS_ENABLE = yes
+```
+
+Then define a table like this in your keymap file:
+
+```c
+const qk_ucis_symbol_t ucis_symbol_table[] = UCIS_TABLE(
+    UCIS_SYM("poop", 0x1F4A9), // 💩
+    UCIS_SYM("rofl", 0x1F923), // 🤣
+    UCIS_SYM("kiss", 0x1F619)  // 😙
+);
+```
+
+To use it, call `qk_ucis_start()`. Then, type the mnemonic for the character (such as "rofl"), and hit Space or Enter. QMK should erase the "rofl" text and insert the laughing emoji.
+
+### Customization
+
+There are several functions that you can define in your keymap to customize the functionality of this feature.
+
+* `void qk_ucis_start_user(void)` – This runs when you call the "start" function, and can be used to provide feedback. By default, it types out a keyboard emoji.
+* `void qk_ucis_success(uint8_t symbol_index)` – This runs when the input has matched something and has completed. By default, it doesn't do anything.
+* `void qk_ucis_symbol_fallback (void)` – This runs when the input doesn't match anything. By default, it falls back to trying that input as a Unicode code.
+
+You can find the default implementations of these functions in [`process_ucis.c`](https://github.com/qmk/qmk_firmware/blob/master/quantum/process_keycode/process_ucis.c).
+
+## Input Modes
+
+Unicode input in QMK works by inputting a sequence of characters to the OS, sort of like a macro. Unfortunately, the way this is done differs for each platform. Specifically, each platform requires a different combination of keys to trigger Unicode input. Therefore, a corresponding input mode has to be set in QMK.
+
+The following input modes are available:
+
+* **`UC_OSX`**: macOS built-in Unicode hex input. Supports code points up to `0xFFFF` (`0x10FFFF` with Unicode Map).
+
+  To enable, go to _System Preferences > Keyboard > Input Sources_, add _Unicode Hex Input_ to the list (it's under _Other_), then activate it from the input dropdown in the Menu Bar.
+  By default, this mode uses the left Option key (`KC_LALT`) for Unicode input, but this can be changed by defining [`UNICODE_KEY_OSX`](#input-key-configuration) with another keycode.
+
+  !> Using the _Unicode Hex Input_ input source may disable some Option based shortcuts, such as Option + Left Arrow and Option + Right Arrow.
+
+* **`UC_LNX`**: Linux built-in IBus Unicode input. Supports code points up to `0x10FFFF` (all possible code points).
+
+  Enabled by default and works almost anywhere on IBus-enabled distros. Without IBus, this mode works under GTK apps, but rarely anywhere else.
+  By default, this mode uses Ctrl+Shift+U (`LCTL(LSFT(KC_U))`) to start Unicode input, but this can be changed by defining [`UNICODE_KEY_LNX`](#input-key-configuration) with another keycode. This might be required for IBus versions ≥1.5.15, where Ctrl+Shift+U behavior is consolidated into Ctrl+Shift+E.
+
+* **`UC_WIN`**: _(not recommended)_ Windows built-in hex numpad Unicode input. Supports code points up to `0xFFFF`.
+
+  To enable, create a registry key under `HKEY_CURRENT_USER\Control Panel\Input Method\EnableHexNumpad` of type `REG_SZ` called `EnableHexNumpad` and set its value to `1`. This can be done from the Command Prompt by running `reg add "HKCU\Control Panel\Input Method" -v EnableHexNumpad -t REG_SZ -d 1` with administrator privileges. Reboot afterwards.
+  This mode is not recommended because of reliability and compatibility issues; use the `UC_WINC` mode instead.
+
+* **`UC_BSD`**: _(non implemented)_ Unicode input under BSD. Not implemented at this time. If you're a BSD user and want to help add support for it, please [open an issue on GitHub](https://github.com/qmk/qmk_firmware/issues).
+
+* **`UC_WINC`**: Windows Unicode input using [WinCompose](https://github.com/samhocevar/wincompose). As of v0.9.0, supports code points up to `0x10FFFF` (all possible code points).
+
+  To enable, install the [latest release](https://github.com/samhocevar/wincompose/releases/latest). Once installed, WinCompose will automatically run on startup. Works reliably under all version of Windows supported by the app.
+  By default, this mode uses right Alt (`KC_RALT`) as the Compose key, but this can be changed in the WinCompose settings and by defining [`UNICODE_KEY_WINC`](#input-key-configuration) with another keycode.
+
+### Switching Input Modes
+
+There are two ways to set the input mode for Unicode: by keycode or by function. Keep in mind that both methods write to persistent storage (EEPROM), and are loaded each time the keyboard starts. So once you've set it the first time, you don't need to set it again unless you want to change it, or you've reset the EEPROM settings.
+
+You can switch the input mode at any time by using one of the following keycodes. The easiest way is to add the ones you use to your keymap.
+
+|Keycode               |Alias    |Input Mode  |Description                                                   |
+|----------------------|---------|------------|--------------------------------------------------------------|
+|`UNICODE_MODE_FORWARD`|`UC_MOD` |Next in list|[Cycle](#input-mode-cycling) through selected modes           |
+|`UNICODE_MODE_REVERSE`|`UC_RMOD`|Prev in list|[Cycle](#input-mode-cycling) through selected modes in reverse|
+|`UNICODE_MODE_OSX`    |`UC_M_OS`|`UC_OSX`    |Switch to macOS input                                         |
+|`UNICODE_MODE_LNX`    |`UC_M_LN`|`UC_LNX`    |Switch to Linux input                                         |
+|`UNICODE_MODE_WIN`    |`UC_M_WI`|`UC_WIN`    |Switch to Windows input                                       |
+|`UNICODE_MODE_BSD`    |`UC_M_BS`|`UC_BSD`    |Switch to BSD input (not implemented)                         |
+|`UNICODE_MODE_WINC`   |`UC_M_WC`|`UC_WINC`   |Switch to Windows input using WinCompose                      |
+
+You can also switch the input mode by calling `set_unicode_input_mode(x)` in your code, where _x_ is one of the above input mode constants (e.g. `UC_LNX`). Since the function only needs to be called once, it's recommended that you do it in `eeconfig_init_user()` (or a similar function). For example:
+
+```c
+void eeconfig_init_user(void) {
+    set_unicode_input_mode(UC_LNX);
+}
+```
+
+### Audio Feedback
+
+If you have the [Audio feature](feature_audio.md) enabled on the board, you can set melodies to be played when you press the above keys. That way you can have some audio feedback when switching input modes.
+
+For instance, you can add these definitions to your `config.h` file:
+
+```c
+#define UNICODE_SONG_OSX  COIN_SOUND
+#define UNICODE_SONG_LNX  UNICODE_LINUX
+#define UNICODE_SONG_BSD  MARIO_GAMEOVER
+#define UNICODE_SONG_WIN  UNICODE_WINDOWS
+#define UNICODE_SONG_WINC UNICODE_WINDOWS
+```
+
+### Additional Customization
+
+Because Unicode is a large and versatile feature, there are a number of options you can customize to make it work better on your system.
+
+#### Start and Finish Input Functions
+
+The functions for starting and finishing Unicode input on your platform can be overridden locally. Possible uses include customizing input mode behavior if you don't use the default keys, or adding extra visual/audio feedback to Unicode input.
+
+* `void unicode_input_start(void)` – This sends the initial sequence that tells your platform to enter Unicode input mode. For example, it presses Ctrl+Shift+U on Linux and holds the Option key on macOS.
+* `void unicode_input_finish(void)` – This is called to exit Unicode input mode, for example by pressing Space or releasing the Option key.
+
+You can find the default implementations of these functions in [`process_unicode_common.c`](https://github.com/qmk/qmk_firmware/blob/master/quantum/process_keycode/process_unicode_common.c).
+
+#### Input Key Configuration
+
+You can customize the keys used to trigger Unicode input for macOS, Linux and WinCompose by adding corresponding defines to your `config.h`. The default values match the platforms' default settings, so you shouldn't need to change this unless Unicode input isn't working, or you want to use a different key (e.g. in order to free up left or right Alt).
+
+|Define            |Type      |Default           |Example                                    |
+|------------------|----------|------------------|-------------------------------------------|
+|`UNICODE_KEY_OSX` |`uint8_t` |`KC_LALT`         |`#define UNICODE_KEY_OSX  KC_RALT`         |
+|`UNICODE_KEY_LNX` |`uint16_t`|`LCTL(LSFT(KC_U))`|`#define UNICODE_KEY_LNX  LCTL(LSFT(KC_E))`|
+|`UNICODE_KEY_WINC`|`uint8_t` |`KC_RALT`         |`#define UNICODE_KEY_WINC KC_RGUI`         |
+
+#### Input Mode Cycling
+
+You can choose which input modes are available for cycling through. By default, this is disabled. If you want to enable it, limiting it to just the modes you use makes sense. Note that the values in the list are comma-delimited.
+
+```c
+#define UNICODE_SELECTED_MODES UC_OSX, UC_LNX, UC_WIN, UC_WINC
+```
+
+You can cycle through the selected modes by using the `UC_MOD`/`UC_RMOD` keycodes, or by calling `cycle_unicode_input_mode(offset)` in your code (`offset` is how many modes to move forward by, so +1 corresponds to `UC_MOD`).
+
+By default, when the keyboard boots, it will initialize the input mode to the last one you used. You can disable this and make it start with the first mode in the list every time by adding the following to your `config.h`:
+
+```c
+#define UNICODE_CYCLE_PERSIST false
+```
+
+!> Using `UNICODE_SELECTED_MODES` means you don't have to initially set the input mode in `matrix_init_user()` (or a similar function); the Unicode system will do that for you on startup. This has the added benefit of avoiding unnecessary writes to EEPROM.
+
+## `send_unicode_hex_string`
+
+To type multiple characters for things like (ノಠ痊ಠ)ノ彡┻━┻, you can use `send_unicode_hex_string()` much like `SEND_STRING()` except you would use hex values separate by spaces.
+For example, the table flip seen above would be `send_unicode_hex_string("0028 30CE 0CA0 75CA 0CA0 0029 30CE 5F61 253B 2501 253B")`
+
+There are many ways to get a hex code, but an easy one is [this site](https://r12a.github.io/app-conversion/). Just make sure to convert to hexadecimal, and that is your string.
+
+## Additional Language Support
+
+In `quantum/keymap_extras/`, you'll see various language files - these work the same way as the alternative layout ones do. Most are defined by their two letter country/language code followed by an underscore and a 4-letter abbreviation of its name. `FR_UGRV` which will result in a `ù` when using a software-implemented AZERTY layout. It's currently difficult to send such characters in just the firmware.
+
+## International Characters on Windows
+
+### AutoHotkey allows Windows users to create custom hotkeys among others.
+
+The method does not require Unicode support in the keyboard itself but depends instead of [AutoHotkey](https://autohotkey.com) running in the background.
+
+First you need to select a modifier combination that is not in use by any of your programs.
+CtrlAltWin is not used very widely and should therefore be perfect for this.
+There is a macro defined for a mod-tab combo `LCAG_T`.
+Add this mod-tab combo to a key on your keyboard, e.g.: `LCAG_T(KC_TAB)`.
+This makes the key behave like a tab key if pressed and released immediately but changes it to the modifier if used with another key.
+
+In the default script of AutoHotkey you can define custom hotkeys.
+
+    <^<!<#a::Send, ä
+    <^<!<#<+a::Send, Ä
+
+The hotkeys above are for the combination CtrlAltGui and CtrlAltGuiShift plus the letter a.
+AutoHotkey inserts the Text right of `Send, ` when this combination is pressed.
+
+### US International
+
+If you enable the US International layout on the system, it will use punctuation to accent the characters.
+
+For instance, typing "`a" will result in à.
+
+You can find details on how to enable this [here](https://support.microsoft.com/en-us/help/17424/windows-change-keyboard-layout).

docs/feature_userspace.md

@@ -0,0 +1,251 @@
+# Userspace: Sharing Code Between Keymaps
+
+If you use more than one keyboard with a similar keymap, you might see the benefit in being able to share code between them. Create your own folder in `users/` named the same as your keymap (ideally your github username, `<name>`) with the following structure:
+
+* `/users/<name>/` (added to the path automatically)
+  * `readme.md` (optional, recommended)
+  * `rules.mk` (included automatically)
+  * `config.h` (included automatically)
+  * `<name>.h` (optional)
+  * `<name>.c` (optional)
+  * `cool_rgb_stuff.c` (optional)
+  * `cool_rgb_stuff.h` (optional)
+
+
+All this only happens when you build a keymap named `<name>`, like this:
+
+    make planck:<name>
+
+For example,
+
+    make planck:jack
+
+Will include the `/users/jack/` folder in the path, along with `/users/jack/rules.mk`.  
+
+!> This `name` can be [overridden](#override-default-userspace), if needed.  
+
+## `Rules.mk`
+
+The `rules.mk` is one of the two files that gets processed automatically.  This is how you add additional source files (such as  `<name>.c`) will be added when compiling.
+
+It's highly recommended that you use `<name>.c` as the default source file to be added. And to add it, you need to add it the SRC in `rules.mk` like this:
+
+    SRC += <name>.c
+
+Additional files may be added in the same way - it's recommended you have one named `<name>`.c/.h to start off with, though. 
+
+The `/users/<name>/rules.mk` file will be included in the build _after_ the `rules.mk` from your keymap. This allows you to have features in your userspace `rules.mk` that depend on individual QMK features that may or may not be available on a specific keyboard. 
+
+For example, if you have RGB control features shared between all your keyboards that support RGB lighting, you can add support for that if the RGBLIGHT feature is enabled:
+```make
+ifeq ($(strip $(RGBLIGHT_ENABLE)), yes)
+  # Include my fancy rgb functions source here
+  SRC += cool_rgb_stuff.c
+endif
+```
+
+Alternatively, you can `define RGB_ENABLE` in your keymap's `rules.mk` and then check for the variable in your userspace's `rules.mk` like this:
+```make
+ifdef RGB_ENABLE
+  # Include my fancy rgb functions source here
+  SRC += cool_rgb_stuff.c
+endif
+```
+
+### Override default userspace
+
+By default the userspace used will be the same as the keymap name. In some situations this isn't desirable. For instance, if you use the [layout](feature_layouts.md) feature you can't use the same name for different keymaps (e.g. ANSI and ISO). You can name your layouts `mylayout-ansi` and `mylayout-iso` and add the following line to your layout's `rules.mk`:
+
+```
+USER_NAME := mylayout
+```
+
+This is also useful if you have multiple different keyboards with different features physically present on the board (such as one with RGB Lights, and one with Audio, or different number of LEDs, or connected to a different PIN on the controller).
+
+## Configuration Options (`config.h`)
+
+Additionally, `config.h` here will be processed like the same file in your keymap folder.  This is handled separately from the `<name>.h` file.
+
+The reason for this, is that `<name>.h` won't be added in time to add settings (such as `#define TAPPING_TERM 100`), and including the `<name.h>` file in any `config.h` files will result in compile issues.
+
+!>You should use the `config.h` for [configuration options](config_options.md), and the `<name>.h` file for user or keymap specific settings (such as the enum for layer or keycodes)
+
+
+## Readme (`readme.md`)
+
+Please include authorship (your name, github username, email), and optionally [a license that's GPL compatible](https://www.gnu.org/licenses/license-list.html#GPLCompatibleLicenses).
+
+You can use this as a template: 
+```
+Copyright <year> <name> <email> @<github_username>
+
+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/>.
+```
+
+You'd want to replace the year, name, email and github username with your info. 
+
+Additionally, this is a good place to document your code, if you wish to share it with others. 
+
+# Examples
+
+For a brief example, checkout [`/users/_example/`](https://github.com/qmk/qmk_firmware/tree/master/users/drashna).  
+For a more complicated example, checkout [`/users/drashna/`](https://github.com/qmk/qmk_firmware/tree/master/users/drashna)'s userspace.
+
+
+## Customized Functions
+
+QMK has a bunch of [functions](custom_quantum_functions.md) that have [`_quantum`, `_kb`, and `_user` versions](custom_quantum_functions.md#a-word-on-core-vs-keyboards-vs-keymap) that you can use.  You will pretty much always want to use the user version of these functions.  But the problem is that if you use them in your userspace, then you don't have a version that you can use in your keymap. 
+
+However, you can actually add support for keymap version, so that you can use it in both your userspace and your keymap! 
+
+
+For instance, let's look at the `layer_state_set_user()` function.  You can enable the [Tri Layer State](ref_functions.md#olkb-tri-layers) functionality on all of your boards, while also retaining the Tri Layer functionality in your `keymap.c` files. 
+
+In your `<name.c>` file, you'd want to add this: 
+```c
+__attribute__ ((weak))
+layer_state_t layer_state_set_keymap (layer_state_t state) {
+  return state;
+}
+
+layer_state_t layer_state_set_user (layer_state_t state) {
+  state = update_tri_layer_state(state, 2, 3, 5);
+  return layer_state_set_keymap (state);
+}
+```
+The `__attribute__ ((weak))` part tells the compiler that this is a placeholder function that can then be replaced by a version in your `keymap.c`.  That way, you don't need to add it to your `keymap.c`, but if you do, you won't get any conflicts because the function is the same name. 
+
+The `_keymap` part here doesn't matter, it just needs to be something other than `_quantum`, `_kb`, or `_user`, since those are already in use. So you could use `layer_state_set_mine`, `layer_state_set_fn`, or anything else.
+
+You can see a list of this and other common functions in [`template.c`](https://github.com/qmk/qmk_firmware/blob/master/users/drashna/template.c) in [`users/drashna`](https://github.com/qmk/qmk_firmware/tree/master/users/drashna).
+
+## Custom Features
+
+Since the Userspace feature can support a staggering number of boards, you may have boards that you want to enable certain functionality for, but not for others. And you can actually create "features" that you can enable or disable in your own userspace.  
+
+For instance, if you wanted to have a bunch of macros available, but only on certain boards (to save space), you could "hide" them being a `#ifdef MACROS_ENABLED`, and then enable it per board.  To do this, add this to your rules.mk
+```make
+ifeq ($(strip $(MACROS_ENABLED)), yes)
+    OPT_DEFS += -DMACROS_ENABLED
+endif
+```
+The `OPT_DEFS` setting causes `MACROS_ENABLED` to be defined for your keyboards (note the `-D` in front of the name), and you could use `#ifdef MACROS_ENABLED` to check the status in your c/h files, and handle that code based on that. 
+
+Then you add `MACROS_ENABLED = yes` to the `rules.mk` for you keymap to enable this feature and the code in your userspace.
+
+And in your `process_record_user` function, you'd do something like this: 
+```c
+bool process_record_user(uint16_t keycode, keyrecord_t *record) {
+  switch (keycode) {
+#ifdef MACROS_ENABLED
+  case MACRO1:
+    if (!record->event.pressed) {
+      SEND_STRING("This is macro 1!");
+    }
+    break;
+  case MACRO2:
+    if (!record->event.pressed) {
+      SEND_STRING("This is macro 2!");
+    }
+    break;
+#endif
+  }
+  return true;
+}
+```
+
+
+## Consolidated Macros
+
+If you wanted to consolidate macros and other functions into your userspace for all of your keymaps, you can do that.  This builds upon the [Customized Functions](#customized-functions) example above. This lets you maintain a bunch of macros that are shared between the different keyboards, and allow for keyboard specific macros, too. 
+
+First, you'd want to go through all of your `keymap.c` files and replace `process_record_user` with `process_record_keymap` instead.   This way, you can still use keyboard specific codes on those boards, and use your custom "global" keycodes as well.   You'll also want to replace `SAFE_RANGE` with `NEW_SAFE_RANGE` so that you wont have any overlapping keycodes
+
+Then add `#include <name.h>` to all of your keymap.c files.  This allows you to use these new keycodes without having to redefine them in each keymap.
+
+Once you've done that, you'll want to set the keycode definitions that you need to the `<name>.h`  file. For instance:
+```c
+#pragma once
+
+#include "quantum.h"
+#include "action.h"
+#include "version.h"
+
+// Define all of
+enum custom_keycodes {
+  KC_MAKE = SAFE_RANGE,
+  NEW_SAFE_RANGE  //use "NEW_SAFE_RANGE" for keymap specific codes
+};
+```
+
+Now you want to create the `<name>.c` file, and add this content to it:
+
+```c
+#include "<name>.h"
+
+__attribute__ ((weak))
+bool process_record_keymap(uint16_t keycode, keyrecord_t *record) {
+  return true;
+}
+
+bool process_record_user(uint16_t keycode, keyrecord_t *record) {
+  switch (keycode) {
+    case KC_MAKE:  // Compiles the firmware, and adds the flash command based on keyboard bootloader
+            if (!record->event.pressed) {
+            uint8_t temp_mod = get_mods();
+            uint8_t temp_osm = get_oneshot_mods();
+            clear_mods(); clear_oneshot_mods();
+            SEND_STRING("make " QMK_KEYBOARD ":" QMK_KEYMAP);
+    #ifndef FLASH_BOOTLOADER
+            if ( (temp_mod | temp_osm) & MOD_MASK_SHIFT ) 
+    #endif
+            { // 
+                #if defined(__arm__)  // only run for ARM boards
+                    SEND_STRING(":dfu-util");
+                #elif defined(BOOTLOADER_DFU) // only run for DFU boards
+                    SEND_STRING(":dfu");
+                #elif defined(BOOTLOADER_HALFKAY) // only run for teensy boards
+                    SEND_STRING(":teensy");
+                #elif defined(BOOTLOADER_CATERINA) // only run for Pro Micros
+                    SEND_STRING(":avrdude");
+                #endif // bootloader options
+            }
+            if ( (temp_mod | temp_osm) & MOD_MASK_CTRL) { 
+                SEND_STRING(" -j8 --output-sync"); 
+            }
+            SEND_STRING(SS_TAP(X_ENTER));
+            set_mods(temp_mod);
+        }
+        break;
+
+  }
+  return process_record_keymap(keycode, record);
+}
+```
+
+For boards that may not have a shift button (such as on a macro pad), we need a way to always include the bootloader option.  To do that, add the following to the `rules.mk` in your userspace folder: 
+
+```make 
+ifeq ($(strip $(FLASH_BOOTLOADER)), yes)
+    OPT_DEFS += -DFLASH_BOOTLOADER
+endif
+```
+
+This will add a new `KC_MAKE` keycode that can be used in any of your keymaps.  And this keycode will output `make <keyboard>:<keymap>`, making frequent compiling easier.  And this will work with any keyboard and any keymap as it will output the current boards info, so that you don't have to type this out every time.
+
+Also, holding `shift` will add the appropriate flashing command (`:dfu`, `:teensy`, `:avrdude`, `:dfu-util`) for a majority of keyboards.  Holding `control` will add some commands that will speed up compiling time by processing multiple files at once. 
+
+And for the boards that lack a shift key, or that you want to always attempt the flashing part, you can add `FLASH_BOOTLOADER = yes` to the `rules.mk` of that keymap.
+
+?> This should flash the newly compiled firmware automatically, using the correct utility, based on the bootloader settings (or default to just generating the HEX file). However, it should be noted that this may not work on all systems. AVRDUDE doesn't work on WSL, namely. And this doesn't support BootloadHID or mdloader. 

docs/feature_velocikey.md

@@ -0,0 +1,30 @@
+# Velocikey
+
+Velocikey is a feature that lets you control the speed of lighting effects (like the Rainbow Swirl effect) with the speed of your typing. The faster you type, the faster the lights will go!
+
+## Usage
+For Velocikey to take effect, there are two steps. First, when compiling your keyboard, you'll need to set `VELOCIKEY_ENABLE=yes` in `rules.mk`, e.g.:
+
+```
+BOOTMAGIC_ENABLE = no
+MOUSEKEY_ENABLE = no
+STENO_ENABLE = no
+EXTRAKEY_ENABLE = yes
+VELOCIKEY_ENABLE = yes
+```
+
+Then, while using your keyboard, you need to also turn it on with the VLK_TOG keycode, which toggles the feature on and off.
+
+The following light effects will all be controlled by Velocikey when it is enabled:
+ - RGB Breathing
+ - RGB Rainbow Mood
+ - RGB Rainbow Swirl
+ - RGB Snake
+ - RGB Knight
+
+Support for LED breathing effects is planned but not available yet.
+
+ As long as Velocikey is enabled, it will control the speed regardless of any other speed setting that your RGB lights are currently on.
+
+ ## Configuration
+ Velocikey doesn't currently support any configuration via keyboard settings. If you want to adjust something like the speed increase or decay rate, you would need to edit `velocikey.c` and adjust the values there to achieve the kinds of speeds that you like.

docs/features.md

@@ -0,0 +1,42 @@
+# QMK Features
+
+QMK has a staggering number of features for building your keyboard. It can take some time to understand all of them and determine which one will achieve your goal.
+
+
+* [Advanced Keycodes](feature_advanced_keycodes.md) - Change layers, dual-action keys, and more. Go beyond typing simple characters.
+* [Audio](feature_audio.md) - Connect a speaker to your keyboard for audio feedback, midi support, and music mode.
+* [Auto Shift](feature_auto_shift.md) - Tap for the normal key, hold slightly longer for its shifted state.
+* [Backlight](feature_backlight.md) - LED lighting support for your keyboard.
+* [Bluetooth](feature_bluetooth.md) - BlueTooth support for your keyboard.
+* [Bootmagic](feature_bootmagic.md) - Adjust the behavior of your keyboard using hotkeys.
+* [Combos](feature_combo.md) - Custom actions for multiple key holds.
+* [Command](feature_command.md) - Runtime version of bootmagic (Formerly known as "Magic").
+* [Debounce API](feature_debounce_type.md) - Customization of debouncing algorithms, and the ability to add more/custom debouncing. 
+* [DIP Switch](feature_dip_switch.md) - Toggle switches for customizing board function.
+* [Dynamic Macros](feature_dynamic_macros.md) - Record and playback macros from the keyboard itself.
+* [Encoders](feature_encoders.md) - Rotary encoders! 
+* [Grave Escape](feature_grave_esc.md) - Lets you use a single key for Esc and Grave. 
+* [Haptic Feedback](feature_haptic_feedback.md) - Add haptic feedback drivers to your board.
+* [HD44780 LCD Display](feature_hd44780.md) - Support for LCD character displays using the HD44780 standard.
+* [Key Lock](feature_key_lock.md) - Lock a key in the "down" state.
+* [Layouts](feature_layouts.md) - Use one keymap with any keyboard that supports your layout.
+* [Leader Key](feature_leader_key.md) - Tap the leader key followed by a sequence to trigger custom behavior.
+* [LED Matrix](feature_led_matrix.md) - LED Matrix single color lights for per key lighting (Single Color, not RGB).
+* [Macros](feature_macros.md) - Send multiple key presses when pressing only one physical key.
+* [Mouse keys](feature_mouse_keys.md) - Control your mouse pointer from your keyboard.
+* [OLED Driver](feature_oled_driver.md) - Add OLED screens to your keyboard.
+* [One Shot Keys](feature_advanced_keycodes.md#one-shot-keys) - Sticky Keys, lets you hit a key rather than holding it.
+* [Pointing Device](feature_pointing_device.md) - Framework for connecting your custom pointing device to your keyboard.
+* [PS2 Mouse](feature_ps2_mouse.md) - Driver for connecting a PS/2 mouse directly to your keyboard.
+* [RGB Light](feature_rgblight.md) - RGB lighting for your keyboard.
+* [RGB Matrix](feature_rgb_matrix.md) - RGB Matrix lights for per key lighting.
+* [Space Cadet](feature_space_cadet.md) - Use your left/right shift keys to type parenthesis and brackets.
+* [Split Keyboard](feature_split_keyboard.md) 
+* [Stenography](feature_stenography.md) - Put your keyboard into Plover mode for stenography use.
+* [Swap Hands](feature_swap_hands.md) - Mirror your keyboard for one handed usage.
+* [Tap Dance](feature_tap_dance.md) - Make a single key do as many things as you want.
+* [Terminal](feature_terminal.md) - CLI interface to the internals of your keyboard.
+* [Thermal Printer](feature_thermal_printer.md) - Connect a thermal printer to your keyboard to be able to toggle on a printed log of everything you type.
+* [Unicode](feature_unicode.md) - Unicode input support.
+* [Userspace](feature_userspace.md) - Share code between different keymaps and keyboards.
+* [Velocikey](feature_velocikey.md) - Allows changes in RGB animation speed based on WPM/Typing speed.

docs/flashing.md

@@ -0,0 +1,237 @@
+# Flashing Instructions and Bootloader Information
+
+There are quite a few different types of bootloaders that keyboards use, and just about all of the use a different flashing method. Luckily, projects like the [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) aim to be compatible with all the different types without having to think about it much, but this article will describe the different types of bootloaders, and available methods for flashing them.
+
+If you have a bootloader selected with the `BOOTLOADER` variable in your `rules.mk`, QMK will automatically calculate if your .hex file is the right size to be flashed to the device, and output the total size in bytes (along with the max). To run this process manually, compile with the target `check-size`, eg `make planck/rev4:default:check-size`.
+
+## DFU
+
+Atmel's DFU bootloader comes on all atmega32u4 chips by default, and is used by many keyboards that have their own ICs on their PCBs (Older OLKB boards, Clueboards). Some keyboards may also use LUFA's DFU bootloader (or QMK's fork) (Newer OLKB boards) that adds in additional features specific to that hardware.
+
+To ensure compatibility with the DFU bootloader, make sure this block is present your `rules.mk` (optionally with `lufa-dfu` or `qmk-dfu` instead):
+
+```make
+# Bootloader selection
+#   Teensy       halfkay
+#   Pro Micro    caterina
+#   Atmel DFU    atmel-dfu
+#   LUFA DFU     lufa-dfu
+#   QMK DFU      qmk-dfu
+#   ATmega32A    bootloadHID
+#   ATmega328P   USBasp
+BOOTLOADER = atmel-dfu
+```
+
+Compatible flashers:
+
+* [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) (recommended GUI)
+* [dfu-programmer](https://github.com/dfu-programmer/dfu-programmer) / `:dfu` in QMK (recommended command line)
+* [Atmel's Flip](http://www.microchip.com/developmenttools/productdetails.aspx?partno=flip) (not recommended)
+
+Flashing sequence:
+
+1. Press the `RESET` keycode, or tap the RESET button (or short RST to GND).
+2. Wait for the OS to detect the device
+3. Erase the memory (may be done automatically)
+4. Flash a .hex file
+5. Reset the device into application mode (may be done automatically)
+
+or:
+
+    make <keyboard>:<keymap>:dfu
+
+### QMK DFU
+
+QMK has a fork of the LUFA DFU bootloader that allows for a simple matrix scan for exiting the bootloader and returning to the application, as well as flashing an LED/making a ticking noise with a speaker when things are happening. To enable these features, use this block in your `config.h` (The key that exits the bootloader needs to be hooked-up to the INPUT and OUTPUT defined here):
+
+    #define QMK_ESC_OUTPUT F1 // usually COL
+    #define QMK_ESC_INPUT D5 // usually ROW
+    #define QMK_LED E6
+    #define QMK_SPEAKER C6
+
+The Manufacturer and Product names are automatically pulled from your `config.h`, and "Bootloader" is added to the product.
+
+To generate this bootloader, use the `bootloader` target, eg `make planck/rev4:default:bootloader`.
+
+To generate a production-ready .hex file (containing the application and the bootloader), use the `production` target, eg `make planck/rev4:default:production`.
+
+### DFU commands
+
+There are a number of DFU commands that you can use to flash firmware to a DFU device:
+
+* `:dfu` - This is the normal option and waits until a DFU device is available, and then flashes the firmware. This will check every 5 seconds, to see if a DFU device has appeared.
+* `:dfu-ee` - This flashes an `eep` file instead of the normal hex.  This is uncommon. 
+* `:dfu-split-left` - This flashes the normal firmware, just like the default option (`:dfu`). However, this also flashes the "Left Side" EEPROM file for split keyboards. _This is ideal for Elite C based split keyboards._
+* `:dfu-split-right` - This flashes the normal firmware, just like the default option (`:dfu`). However, this also flashes the "Right Side" EEPROM file for split keyboards. _This is ideal for Elite C based split keyboards._
+
+## Caterina
+
+Arduino boards and their clones use the [Caterina bootloader](https://github.com/arduino/ArduinoCore-avr/tree/master/bootloaders/caterina) (any keyboard built with a Pro Micro, or clone), and uses the avr109 protocol to communicate through virtual serial. Bootloaders like [A-Star](https://www.pololu.com/docs/0J61/9) are based on Caterina.
+
+To ensure compatibility with the Caterina bootloader, make sure this block is present your `rules.mk`:
+
+```make
+# Bootloader selection
+#   Teensy       halfkay
+#   Pro Micro    caterina
+#   Atmel DFU    atmel-dfu
+#   LUFA DFU     lufa-dfu
+#   QMK DFU      qmk-dfu
+#   ATmega32A    bootloadHID
+#   ATmega328P   USBasp
+BOOTLOADER = caterina
+```
+
+Compatible flashers:
+
+* [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) (recommended GUI)
+* [avrdude](http://www.nongnu.org/avrdude/) with avr109 / `:avrdude` (recommended command line)
+* [AVRDUDESS](https://github.com/zkemble/AVRDUDESS)
+
+Flashing sequence:
+
+1. Press the `RESET` keycode, or short RST to GND quickly (you only have 7 seconds to flash once it enters)
+2. Wait for the OS to detect the device
+3. Flash a .hex file
+4. Wait for the device to reset automatically
+
+or
+
+    make <keyboard>:<keymap>:avrdude
+
+or if you want to flash multiple boards, use the following command
+
+    make <keyboard>:<keymap>:avrdude-loop
+
+When you're done flashing boards, you'll need to hit Ctrl + C or whatever the correct keystroke is for your operating system to break the loop.
+
+
+## Halfkay
+
+Halfkay is a super-slim protocol developed by PJRC that uses HID, and come on all Teensys (namely the 2.0).
+
+To ensure compatibility with the Halfkay bootloader, make sure this block is present your `rules.mk`:
+
+```make
+# Bootloader selection
+#   Teensy       halfkay
+#   Pro Micro    caterina
+#   Atmel DFU    atmel-dfu
+#   LUFA DFU     lufa-dfu
+#   QMK DFU      qmk-dfu
+#   ATmega32A    bootloadHID
+#   ATmega328P   USBasp
+BOOTLOADER = halfkay
+```
+
+Compatible flashers:
+
+* [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) (recommended GUI)
+* [Teensy Loader](https://www.pjrc.com/teensy/loader.html)
+* [Teensy Loader Command Line](https://www.pjrc.com/teensy/loader_cli.html) (recommended command line)
+
+Flashing sequence:
+
+1. Press the `RESET` keycode, or short RST to GND quickly (you only have 7 seconds to flash once it enters)
+2. Wait for the OS to detect the device
+3. Flash a .hex file
+4. Reset the device into application mode (may be done automatically)
+
+## USBasploader
+
+USBasploader is a bootloader developed by matrixstorm. It is used in some non-USB AVR chips such as the ATmega328P, which run V-USB.
+
+To ensure compatibility with the USBasploader bootloader, make sure this block is present in your `rules.mk`:
+
+```make
+# Bootloader selection
+#   Teensy       halfkay
+#   Pro Micro    caterina
+#   Atmel DFU    atmel-dfu
+#   LUFA DFU     lufa-dfu
+#   QMK DFU      qmk-dfu
+#   ATmega32A    bootloadHID
+#   ATmega328P   USBasp
+BOOTLOADER = USBasp
+```
+
+Compatible flashers:
+
+* [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) (recommended GUI)
+* [avrdude](http://www.nongnu.org/avrdude/) with the `usbasp` programmer
+* [AVRDUDESS](https://github.com/zkemble/AVRDUDESS)
+
+Flashing sequence:
+
+1. Press the `RESET` keycode, or keep the boot pin shorted to GND while quickly shorting RST to GND
+2. Wait for the OS to detect the device
+3. Flash a .hex file
+4. Reset the device into application mode (may be done automatically)
+
+## BootloadHID
+
+BootloadHID is a USB bootloader for AVR microcontrollers. The uploader tool requires no kernel level driver on Windows and can therefore be run without installing any DLLs.
+
+To ensure compatibility with the bootloadHID bootloader, make sure this block is present your `rules.mk`:
+
+```make
+# Bootloader selection
+#   Teensy       halfkay
+#   Pro Micro    caterina
+#   Atmel DFU    atmel-dfu
+#   LUFA DFU     lufa-dfu
+#   QMK DFU      qmk-dfu
+#   ATmega32A    bootloadHID
+#   ATmega328P   USBasp
+BOOTLOADER = bootloadHID
+```
+
+Compatible flashers:
+
+* [HIDBootFlash](http://vusb.wikidot.com/project:hidbootflash) (recommended Windows GUI)
+* [bootloadhid Command Line](https://www.obdev.at/products/vusb/bootloadhid.html) / `:BootloadHID` in QMK (recommended command line)
+
+Flashing sequence:
+
+1. Enter the bootloader using any of the following methods:
+    * Tap the `RESET` keycode (may not work on all devices)
+    * Hold the salt key while plugging the keyboard in (usually documented within keyboard readme) 
+2. Wait for the OS to detect the device
+3. Flash a .hex file
+4. Reset the device into application mode (may be done automatically)
+
+or:
+
+    make <keyboard>:<keymap>:bootloadHID
+
+## STM32
+
+All STM32 chips come preloaded with a factory bootloader that cannot be modified nor deleted. Some STM32 chips have bootloaders that do not come with USB programming (e.g. STM32F103) but the process is still the same.
+
+At the moment, no `BOOTLOADER` variable is needed on `rules.mk` for STM32.
+
+Compatible flashers:
+
+* [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) (recommended GUI)
+* [dfu-util](https://github.com/Stefan-Schmidt/dfu-util) / `:dfu-util` (recommended command line)
+
+Flashing sequence:
+
+1. Enter the bootloader using any of the following methods:
+    * Tap the `RESET` keycode (may not work on STM32F042 devices)
+    * If a reset circuit is present, tap the RESET button
+    * Otherwise, you need to bridge BOOT0 to VCC (via BOOT0 button or bridge), short RESET to GND (via RESET button or bridge), and then let go of the BOOT0 bridge
+2. Wait for the OS to detect the device
+3. Flash a .bin file
+    * You will receive a warning about the DFU signature; Just ignore it
+4. Reset the device into application mode (may be done automatically)
+    * If you are building from command line (e.g. `make planck/rev6:default:dfu-util`), make sure that `:leave` is passed to the `DFU_ARGS` variable inside your `rules.mk` (e.g. `DFU_ARGS = -d 0483:df11 -a 0 -s 0x08000000:leave`) so that your device resets after flashing
+
+### STM32 Commands
+
+There are a number of DFU commands that you can use to flash firmware to a STM32 device:
+
+* `:dfu-util` - The default command for flashing to STM32 devices.
+* `:dfu-util-split-left` - This flashes the normal firmware, just like the default option (`:dfu-util`). However, this also configures the "Left Side" EEPROM setting for split keyboards.
+* `:dfu-util-split-right` - This flashes the normal firmware, just like the default option (`:dfu-util`). However, this also configures the "Right Side" EEPROM setting for split keyboards.
+* `:st-link-cli` - This allows you to flash the firmware via ST-LINK's CLI utility, rather than dfu-util. 

docs/flashing_bootloadhid.md

@@ -0,0 +1,70 @@
+# BootloadHID Flashing Instructions and Bootloader Information
+
+ps2avr(GB) boards use an ATmega32A microcontroller and a different bootloader. It is not flashable using the regular QMK methods.
+
+General flashing sequence:
+
+1. Enter the bootloader using any of the following methods:
+    * Tap the `RESET` keycode (may not work on all devices)
+    * Hold the salt key while plugging the keyboard in (usually documented within keyboard readme) 
+2. Wait for the OS to detect the device
+3. Flash a .hex file
+4. Reset the device into application mode (may be done automatically)
+
+## bootloadHID Flashing Target
+
+Using the QMK installation script, detailed [here](newbs_getting_started.md), the required bootloadHID tools should be automatically installed.
+
+To flash via the command line, use the target `:bootloadHID` by executing the following command:
+
+    make <keyboard>:<keymap>:bootloadHID
+
+## GUI Flashing
+
+### Windows
+1. Download [HIDBootFlash](http://vusb.wikidot.com/project:hidbootflash).
+2. Place your keyboard into reset. 
+3. Ensure the configured VendorID is `16c0` and ProductID is `05df`
+4. Press the `Find Device` button and ensure that your keyboard is found.
+5. Press the `Open .hex File` button and locate the `.hex` file you created.
+6. Press the `Flash Device` button and wait for the process to complete.
+
+## Command Line Flashing
+
+1. Place your keyboard into reset. 
+2. Flash the board by typing `bootloadHID -r` followed by the path to your `.hex` file.
+
+### Windows Manual Installation
+For MSYS2:
+1. Download the BootloadHID firmware package from https://www.obdev.at/downloads/vusb/bootloadHID.2012-12-08.tar.gz.
+2. Extract contents using a compatible tool, for example 7-Zip.
+3. Add to the MSYS path by copying `commandline/bootloadHID.exe` from the extracted archive to your MSYS2 installation, typically `C:\msys64\usr\bin`.
+
+For native Windows flashing, the `bootloadHID.exe` can be used outside of the MSYS2 environment.
+
+### Linux Manual Installation
+1. Install libusb development dependency:
+    ```bash
+    # This depends on OS - for Debian the following works
+    sudo apt-get install libusb-dev
+    ```
+2. Download the BootloadHID firmware package:
+    ```
+    wget https://www.obdev.at/downloads/vusb/bootloadHID.2012-12-08.tar.gz -O - | tar -xz -C /tmp
+    ```
+3. Build the bootloadHID executable:
+    ```
+    cd /tmp/bootloadHID.2012-12-08/commandline/
+    make
+    sudo cp bootloadHID /usr/local/bin
+    ```
+
+### MacOS Manual Installation
+1. Install Homebrew by typing the following:
+    ```
+    /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
+    ```
+2. Install the following packages:
+    ```
+    brew install --HEAD https://raw.githubusercontent.com/robertgzr/homebrew-tap/master/bootloadhid.rb
+    ```

docs/fr-FR/ChangeLog/20190830.md

@@ -0,0 +1,52 @@
+# QMK Breaking Change - 30 août 2019
+
+Quatre fois par an, QMK lance un processus pour fusionner les Breaking Changes. Un Breaking Change est un changement qui modifie la manière dont QMK fonctionne introduisant des incompatibilités ou des comportements dangereux. Nous n'effectuons ces changements que 4 fois par an afin que les utilisateurs n'aient pas peur de casser leurs keymaps en mettant à jour leur version de QMK.
+
+Ce document présente les fusions de Breaking Change. Voici la liste des changements.
+
+## Formattage de code Core avec clang-format
+
+* Tous les fichiers core (`drivers/`, `quantum/`, `tests/`, et `tmk_core/`) seront formattés avec clang-format
+* Un processus travis pour reformatter les PRs lors de la fusion a été mis en place
+* Vous pouvez utiliser la nouvelle commande CLI `qmk cformat` afin de formatter avant de soumettre votre PR si vous le souhaitez.
+
+## Nettoyage des descripteurs LUFA USB
+
+* Nettoyage du code lié aux descripteurs USB HID sur les claviers AVR, afin de les rendre plus simple à lire et compréhensibles
+* Plus d'information:  https://github.com/qmk/qmk_firmware/pull/4871
+* Normalement pas de changement de fonctionnement et aucune keymap modifiée.
+
+## Migration des entrées de `ACTION_LAYER_MOMENTARY()` dans `fn_actions` vers des keycodes `MO()`
+
+* `fn_actions` est déprécié, et ses fonctionnalités ont été remplacées par des keycodes directs et `process_record_user()`
+* Supprimer cette fonctionnalité obsolète devrait aboutir à une réduction importante de la taille du firmware et de la complexité du code
+* Il est recommandé que toutes les keymaps affectées remplacent `fn_actions` vers les fonctionnalités de [keycode custom](https://docs.qmk.fm/#/custom_quantum_functions) et [macro](https://docs.qmk.fm/#/feature_macros)
+
+## Mise à jour Atreus vers les conventions de codage courantes
+
+* Les doublons include guards ont contourné le comportement de traitement des headers attendu
+* Il est recommandé pour toutes les keymaps affectées de supprimer le doublon de `<keyboard>/config.h` et `<keyboard>/keymaps/<user>/config.h` et de ne garder que des surcharges au niveau keymap
+
+## Récupération des changements de fichier keymap langage de la fork ZSA
+
+* Corrige une issue dans le fichier `keymap_br_abnt2.h` qui inclut la mauvaise souce (`keymap_common.h` au lieu de `keymap.h`)
+* Met à jour le fichier `keymap_swedish.h` afin d'être spécifique au suédois et plus "nordique" en général.
+* Toutes les keymaps qui utilisent ceci devront supprimer `NO_*` et le remplacer par `SE_*`.
+
+## Mise à jour du repo afin d'utiliser LUFA comme un sous-module git
+
+* `/lib/LUFA` supprimé du dépôt
+* LUFA, définis comme un sous-module, pointe vers qmk/lufa
+* Ceci devrait ajouter plus de flexibilité vers LUFA, et nous permet de garder le sous-module à jour bien plus facilement. Il avait environ 2 ans de retard, sans manière simple de corriger. Ce changement devrait simplifier la mise à jour dans le futur.
+
+## Migration des entrées `ACTION_BACKLIGHT_*()` dans `fn_actions` vers des keycodes `BL_`
+
+* `fn_actions` est déprécié, et ses fonctionnalités ont été remplacées par des keycodes directs et `process_record_user()`
+* Toutes les keymaps utilisant ces actions doivent avoir les clés `KC_FN*` remplacées par les clés `BL_*` équivalentes
+* Si vous utilisez actuellement `KC_FN*` vous devrez remplacer `fn_actions` avec les fonctionnalités de [keycode custom](https://docs.qmk.fm/#/custom_quantum_functions) et [macro](https://docs.qmk.fm/#/feature_macros)
+
+## Remplacer l'alias `KC_DELT` par `KC_DEL`
+
+* `KC_DELT` était un alias redondant et non documenté pour `KC_DELETE`
+* Il a été supprimé et toutes ses utilisations ont été remplacées par l'alias plus courant `KC_DEL`
+* Environ 90 keymaps (surtout des boards ErgoDox) ont été modifiées à cette fin

docs/fr-FR/README.md

@@ -0,0 +1,32 @@
+# Quantum Mechanical Keyboard Firmware
+
+[![Version courante](https://img.shields.io/github/tag/qmk/qmk_firmware.svg)](https://github.com/qmk/qmk_firmware/tags)
+[![Statut du build](https://travis-ci.org/qmk/qmk_firmware.svg?branch=master)](https://travis-ci.org/qmk/qmk_firmware)
+[![Discord](https://img.shields.io/discord/440868230475677696.svg)](https://discord.gg/Uq7gcHh)
+[![Statut de la doc](https://img.shields.io/badge/docs-ready-orange.svg)](https://docs.qmk.fm)
+[![Contributeurs Github](https://img.shields.io/github/contributors/qmk/qmk_firmware.svg)](https://github.com/qmk/qmk_firmware/pulse/monthly)
+[![Forks Github](https://img.shields.io/github/forks/qmk/qmk_firmware.svg?style=social&label=Fork)](https://github.com/qmk/qmk_firmware/)
+
+## Qu'est ce que QMK Firmware ?
+
+QMK (*Quantum Mechanical Keyboard*) est une communauté open source qui maintient le firmware QMK, la QMK Toolbox (*Boite à outil*), qmk.fm et leurs documentations. QMK Firmware est un firmware dédié aux claviers qui est basé sur [tmk\_keyboard](http://github.com/tmk/tmk_keyboard). Il offre des fonctionnalités très utiles pour les contrôleurs Atmel AVR, et, plus spécifiquement pour [les produits d'OLKB](http://olkb.com), le clavier [ErgoDox EZ](http://www.ergodox-ez.com), et pour les [produits Clueboard](http://clueboard.co/). Il prend désormais aussi en charge les processeurs ARM qui utilisent ChibiOS. Vous pouvez l'utiliser pour contrôler un clavier personnalisé soudé à la main ou alors sur un clavier avec un PCB personnalisé.
+
+## Comment l'obtenir
+
+Si vous souhaitez contribuer à une disposition de clavier (keymap), ou à des fonctionnalités de QMK alors le plus simple est de [forker le dépôt avec Github](https://github.com/qmk/qmk_firmware#fork-destination-box) puis cloner le dépôt localement pour y faire des changements. Vous pourrez pousser vos changements sur github puis ouvrir un [Pull Request](https://github.com/qmk/qmk_firmware/pulls) depuis votre fork Github.
+
+Sinon, vous pouvez aussi le télécharger directement en ([zip](https://github.com/qmk/qmk_firmware/zipball/master), [tar](https://github.com/qmk/qmk_firmware/tarball/master)), ou le cloner avec git en ssh (`git@github.com:qmk/qmk_firmware.git`), ou https (`https://github.com/qmk/qmk_firmware.git`).
+
+## Comment le compiler
+
+Avant d'être prêt à compiler vous allez devoir [installer un environnement](getting_started_build_tools.md) pour les développements AVR et/ou ARM. Une fois ceci fait, vous pourrez utiliser la commande `make` pour compiler le clavier et la disposition avec une commande de ce type :
+
+    make planck/rev4:default
+
+Cette commande compilera la révision `rev4` du clavier `planck` avec la disposition `default`. Notez que tous les claviers n'ont pas forcément de révisions (aussi appelées sous-projects ou dossiers, ou en en Anglais « subprojects » ou « folder »). Cette option peut donc être omise :
+
+    make preonic:default
+
+## Comment le personnaliser
+
+QMK a beaucoup de [fonctionnalités](features.md) à explorer, et [une documentation](http://docs.qmk.fm) très abondante que vous pourrez parcourir. La plupart des fonctionnalités vous permettrons de modifier vos [dispositions](keymap.md) (keymaps) et de changer [les codes de caractères](keycodes.md) (keycodes).

docs/fr-FR/_summary.md

@@ -0,0 +1,125 @@
+**En Français**
+
+* [Guide pour débutant complet](fr-FR/newbs.md)
+  * [Pour débuter](fr-FR/newbs_getting_started.md)
+  * [Compiler son premier firmware](fr-FR/newbs_building_firmware.md)
+  * [Flasher le Firmware](fr-FR/newbs_flashing.md)
+  * [Test et Débuggage](fr-FR/newbs_testing_debugging.md)
+  * [Bonnes pratiques Git](fr-FR/newbs_best_practices.md)
+  * [Ressources d'apprentissage](fr-FR/newbs_learn_more_resources.md)
+
+* [Les bases de QMK](fr-FR/README.md)
+  * [Indroduction à QMK](fr-FR/getting_started_introduction.md)
+  * [QMK CLI](fr-FR/cli.md)
+  * [Configuration de la CLI QMK](fr-FR/cli_configuration.md)
+  * [Contribuer à QMK](fr-FR/contributing.md)
+  * [Comment utiliser GitHub](fr-FR/getting_started_github.md)
+  * [Trouver de l'aide](fr-FR/getting_started_getting_help.md)
+
+* [Breaking changes](fr-FR/breaking_changes.md)
+  * [30 août 2019](fr-FR/ChangeLog/20190830.md)
+
+**En Anglais**
+
+* [FAQ](faq.md)
+  * [FAQ Générale](faq_general.md)
+  * [Compiler QMK](faq_build.md)
+  * [Débugguer / Dépanner QMK](faq_debug.md)
+  * [Keymap / Disposition](faq_keymap.md)
+  * [Installer les drivers avec Zadig](driver_installation_zadig.md)
+
+* Guides détaillés
+  * [Installation des outils de compilation](getting_started_build_tools.md)
+  * [Guide Vagrant](getting_started_vagrant.md)
+  * [Commandes de compilations](getting_started_make_guide.md)
+  * [Flasher les firmwares](fr-fr/flashing.md)
+  * [Personnaliser les fonctionnalités](custom_quantum_functions.md)
+  * [Aperçu des fonctionnalités des dispositions](keymap.md)
+
+* [Hardware](hardware.md)
+  * [Processeurs AVR](hardware_avr.md)
+  * [Pilotes / Drivers](hardware_drivers.md)
+
+* Réferences
+  * [Lignes de conduite des claviers](hardware_keyboard_guidelines.md)
+  * [Options de configurations](config_options.md)
+  * [Keycodes / Codes des caractères](keycodes.md)
+  * [Conventions de codage - C](coding_conventions_c.md)
+  * [Conventions de codage - Python](coding_conventions_python.md)
+  * [Meilleurs pratiques sur la documentation](documentation_best_practices.md)
+  * [Modèles de documentation](documentation_templates.md)
+  * [Glossaire](reference_glossary.md)
+  * [Tests unitaires](unit_testing.md)
+  * [Fonctions utiles](ref_functions.md)
+  * [Support de configuration](reference_configurator_support.md)
+  * [Format du fichier info.json](reference_info_json.md)
+  * [Développer la CLI en Python](cli_development.md)
+
+* [Fonctionnalités](features.md)
+  * [Keycodes basiques](keycodes_basic.md)
+  * [Touches utilisées avec Shift (US ANSI)](keycodes_us_ansi_shifted.md)
+  * [Keycodes quantiques](quantum_keycodes.md)
+  * [Keycodes avancés](feature_advanced_keycodes.md)
+  * [Fonctionnalités audio](feature_audio.md)
+  * [Majuscule automatique](feature_auto_shift.md)
+  * [Rétroéclairage](feature_backlight.md)
+  * [Bluetooth](feature_bluetooth.md)
+  * [Bootmagic](feature_bootmagic.md)
+  * [Combos](feature_combo.md)
+  * [Commande](feature_command.md)
+  * [API anti-rebond](feature_debounce_type.md)
+  * [DIP Switch](feature_dip_switch.md)
+  * [Macros dynamiques](feature_dynamic_macros.md)
+  * [Interrupteurs rotatifs](feature_encoders.md)
+  * [Grave Escape](feature_grave_esc.md)
+  * [Retour haptique](feature_haptic_feedback.md)
+  * [Contrôleur LCD HD44780](feature_hd44780.md)
+  * [Touche à verrou / Lock-key](feature_key_lock.md)
+  * [Dispositions / layouts](feature_layouts.md)
+  * [Touche leader](feature_leader_key.md)
+  * [Matrice LED](feature_led_matrix.md)
+  * [Macros](feature_macros.md)
+  * [Boutons de souris](feature_mouse_keys.md)
+  * [Pilotes / Drivers OLED](feature_oled_driver.md)
+  * [Touche one-shot](feature_advanced_keycodes.md#one-shot-keys)
+  * [Périphériques de pointage](feature_pointing_device.md)
+  * [Souris PS/2](feature_ps2_mouse.md)
+  * [Éclairage RGB](feature_rgblight.md)
+  * [Matrice RGB](feature_rgb_matrix.md)
+  * [Space Cadet](feature_space_cadet.md)
+  * [Claviers scindés / splittés](feature_split_keyboard.md)
+  * [Stenographie](feature_stenography.md)
+  * [Inversion des mains](feature_swap_hands.md)
+  * [Tap Dance](feature_tap_dance.md)
+  * [Terminale](feature_terminal.md)
+  * [Imprimante thermique](feature_thermal_printer.md)
+  * [Caractères unicodes](feature_unicode.md)
+  * [Dossier utilisateur](feature_userspace.md)
+  * [Velocikey](feature_velocikey.md)
+
+* Pour les makers et les bricoleurs
+  * [Guide des claviers soudés à la main](hand_wire.md)
+  * [Guide de flash de l’ISP](isp_flashing_guide.md)
+  * [Guide du débogage ARM](arm_debugging.md)
+  * [Drivers i2c](i2c_driver.md)
+  * [Contrôles des GPIO](internals_gpio_control.md)
+  * [Conversion en Proton C](proton_c_conversion.md)
+
+* Pour aller plus loin
+  * [Comment fonctionnent les claviers](how_keyboards_work.md)
+  * [Comprendre QMK](understanding_qmk.md)
+
+* Autres sujets
+  * [Utiliser Eclipse avec QMK](other_eclipse.md)
+  * [Utiliser VSCode avec QMK](other_vscode.md)
+  * [Support](support.md)
+  * [Comment ajouter des traductions](translating.md)
+
+* À l’intérieur de QMK (En cours de documentation)
+  * [Définitions](internals_defines.md)
+  * [Input Callback Reg](internals_input_callback_reg.md)
+  * [Appareils Midi](internals_midi_device.md)
+  * [Installation d’un appareil Midi](internals_midi_device_setup_process.md)
+  * [Utilitaires Midi](internals_midi_util.md)
+  * [Fonctions Midi](internals_send_functions.md)
+  * [Outils Sysex](internals_sysex_tools.md)

docs/fr-FR/breaking_changes.md

@@ -0,0 +1,107 @@
+# Breaking changes
+
+Ce document décrit le processus de QMK pour la gestion des breaking changes. Un breaking change est un changement qui modifie la manière dont QMK fonctionne introduisant des incompatibilités ou des comportements dangereux. Nous limitons ces changements afin que les utilisateurs n'aient pas peur de casser leurs keymaps en mettant à jour leur version de QMK.
+
+La période de breaking change est quand nous allons fusionner un PR qui change QMK d'une manière dangereuse ou inattendue. Il y a une période interne de test afin de nous assurer que les problèmes résiduels sont rares ou impossible à prévoir.
+
+## Qu'est-ce qui a été inclus dans des Breaking Changes précédents?
+
+* [30 août 2019](ChangeLog/20190830.md)
+
+## Quand va être le prochain Breaking Change?
+
+Le prochain Breaking Change est planifié pour le 29 novembre.
+
+### Dates importantes
+
+* [x] 21 septembre 2019 - `future` est créé. Il va être rebasé de manière hebdomadaire.
+* [ ] 01 novembre 2019 - `future` fermé aux nouveaux PRs.
+* [ ] 01 novembre 2019 - Appel aux testeurs.
+* [ ] 27 novembre 2019 - `master` est bloqué, pas de PRs fusionnés.
+* [ ] 29 novembre 2019 - `future` est fusionné dans `master`.
+* [ ] 30 novembre 2019 - `master` est débloqué. Les PRs peuvent à nouveau être fusionnés.
+
+## Quels changements seront inclus?
+
+Pour voir une liste de candidats de breaking changes, vous pouvez regardez la liste des [labels `breaking_change`](https://github.com/qmk/qmk_firmware/pulls?q=is%3Aopen+label%3Abreaking_change+is%3Apr). De nouveaux changements peuvent être ajoutés entre maintenant et lorsque `future` est fermée, et un PR avec ce label n'est pas garanti d'être fusionné.
+
+Si vous souhaitez que votre breaking change soit inclus dans ce tour, vous devez créer un PR avec le label `breaking_change` et faire en sorte qu'il soit accepté avant que `future` ne soit fermé. Une fois `future` fermé, aucun nouveau breaking change sera accepté.
+
+Critère d'acceptation:
+
+* Le PR est complété et prêt à fusionner
+* Le PR a un ChangeLog
+
+# Checklists
+
+Cette section documente plusieurs processus que nous utilisons en lançant le processus de Breaking Change.
+
+## Rebase `future` de `master`
+
+Ceci est lancé chaque vendredi tant que `future` est ouvert.
+
+Processus:
+
+```
+cd qmk_firmware
+git checkout master
+git pull --ff-only
+git checkout future
+git rebase master
+git push --force
+```
+
+## Créer la branche `future`
+
+Ceci est fait immédiatement après la fusion de la branche `future` précédente.
+
+* `qmk_firmware` git commands
+    * [ ] `git checkout master`
+    * [ ] `git pull --ff-only`
+    * [ ] `git checkout -b future`
+    * [ ] Modifie `readme.md`
+        * [ ] Ajoute un message en haut qui indique que c'est une branche de test.
+        * [ ] Ajoute un lien vers ce document
+    * [ ] `git commit -m 'Branch point for <DATE> Breaking Change'`
+    * [ ] `git tag breakpoint_<YYYY>_<MM>_<DD>`
+    * [ ] `git tag <next_version>` # Evite que le label point d'arrêt soit confondu par un incrément de version
+    * [ ] `git push origin future`
+    * [ ] `git push --tags`
+
+## 4 Semaines Avant la Fusion
+
+* `future` est maintenant fermé aux nouveaux PRs, seul des correctifs pour les PRs courants peuvent être mergés
+* Envoi de l'appel aux testeurs
+    * [ ] Discord
+    * [ ] GitHub PR
+    * [ ] https://reddit.com/r/olkb
+
+## 1 Semaine Avant la Fusion
+
+* Annonce que master sera fermée entre <2 jours avant> à <Jour de la fusion>
+    * [ ] Discord
+    * [ ] GitHub PR
+    * [ ] https://reddit.com/r/olkb
+
+## 2 Jours Avant la Fusion
+
+* Annonce que master est fermé pour 2 jours
+    * [ ] Discord
+    * [ ] GitHub PR
+    * [ ] https://reddit.com/r/olkb
+
+## Jour de la fusion
+
+* `qmk_firmware` git commands
+    * [ ] `git checkout future`
+    * [ ] `git pull --ff-only`
+    * [ ] `git rebase origin/master`
+    * [ ] Modifie `readme.md`
+        * [ ] Supprimer les notes à propos de `future`
+    * [ ] Regroupe ChangeLog dans un fichier.
+    * [ ] `git commit -m 'Merge point for <DATE> Breaking Change'`
+    * [ ] `git push origin future`
+* Actions sur Github
+    * [ ] Crée un PR pour `future`
+    * [ ] S'assurer que Travis ne relève aucun problème
+    * [ ] Fusion le PR `future`

docs/fr-FR/cli.md

@@ -0,0 +1,146 @@
+# La CLI de QMK
+
+Cette page décrit comment configurer et utiliser la CLI QMK.
+
+# Vue d'ensemble
+
+La CLI de QMK permet de simplifier la compilation et l'intéraction avec les clavier QMK. Nous avons définis plusieurs commandes pour simplifier et rationaliser les tâches telles qu'obtenir et compiler le firmware QMK, créer de nouvelles keymaps, et plus.
+
+* [CLI globale](#global-cli)
+* [CLI locale](#local-cli)
+* [Les commandes CLI](#cli-commands)
+
+# Pré-requis
+
+La CLI nécessite Python 3.5 ou plus récent. Nous essayons de limiter le nombre de pré-requis, mais vous allez aussi devoir installer les paquets listés dans le fichier [`requirements.txt`](https://github.com/qmk/qmk_firmware/blob/master/requirements.txt).
+
+# CLI globale
+
+QMK met à disposition une CLI installable qui peut être utilisée pour configurer votre environnement de compilation QMK, fonctionne avec QMK, et qui rend l'utilisation de plusieurs copies de `qmk_firmware` plus simple. Nous recommandons d'installer et de mettre à jour ceci régulièrement.
+
+## Installer en utilisant Homebrew (macOS, quelques Linux)
+
+Si vous avez installé [Homebrew](https://brew.sh) vous pouvez entrer ce qui suit et installer QMK:
+
+```
+brew tap qmk/qmk
+brew install qmk
+export QMK_HOME='~/qmk_firmware' # Optional, set the location for `qmk_firmware`
+qmk setup  # This will clone `qmk/qmk_firmware` and optionally set up your build environment
+```
+
+## Installer en utilisant easy_install ou pip
+
+Si votre système n'est pas listé ci-dessus, vous pouvez installer QMK manuellement. Premièrement, vérifiez que vous avez bien installé Python 3.5 (ou plus récent) et pip. Ensuite, installez QMK avec cette commande:
+
+```
+pip3 install qmk
+export QMK_HOME='~/qmk_firmware' # Optional, set the location for `qmk_firmware`
+qmk setup  # This will clone `qmk/qmk_firmware` and optionally set up your build environment
+```
+
+## Paquets pour d'autres systèmes d'exploitation
+
+Nous recherchons des gens pour créer et maintenir un paquet `qmk` pour plus de systèmes d'exploitation. Si vous voulez créer un paquet pour votre système d'exploitation, suivez ces directives:
+
+* Suivez les bonnes pratiques pour votre système d'exploitation lorsqu'elles entrent en conflit avec ces directives
+    * Documentez pourquoi dans un commentaire lorsque vous ne les suivez pas
+* Installez en utilisant un virtualenv
+* Expliquez à l'utilisateur de définir la variable d'environnement `QMK_Home` pour "check out" les sources du firmware à un autre endroit que `~/qmk_firmware`.
+
+# CLI locale
+
+Si vous ne voulez pas utiliser la CLI globale, il y a une CLI locale empaquetée avec `qmk_firmware`. Vous pouvez le trouver dans `qmk_firmware/bin/qmk`. Vous pouvez lancer la commande `qmk` depuis n'importe quel répertoire et elle fonctionnera toujours sur cette copie de `qmk_firmware`.
+
+**Exemple**:
+
+```
+$ ~/qmk_firmware/bin/qmk hello
+Ψ Hello, World!
+```
+
+## Limitations de la CLI locale
+
+Il y a quelques limitations à la CLI locale comparé à la globale:
+
+* La CLI locale ne supporte pas `qmk setup` ou `qmk clone`
+* La CLI locale n'opère pas sur le même arbre `qmk_firmware`, même si vous avez plusieurs dépôts clonés.
+* La CLI locale ne s'exécute pas dans un virtualenv, donc il y a des risques que des dépendances seront en conflit
+
+# Les commandes CLI
+
+## `qmk compile`
+
+Cette commande permet de compiler le firmware de n'importe quel répertoire. Vous pouvez compiler des exports JSON de <https://config.qmk.fm> ou compiler des keymaps du dépôt.
+
+**Utilisation pour les exports de configuration**:
+
+```
+qmk compile <configuratorExport.json>
+```
+
+**Utilisation pour les Keymaps**:
+
+```
+qmk compile -kb <keyboard_name> -km <keymap_name>
+```
+
+## `qmk cformat`
+
+Cette commande formatte le code C en utilisant clang-format. Lancez-la sans arguments pour formatter tout le code core, ou passez les noms de fichiers à la ligne de commande pour la lancer sur des fichiers spécifiques.
+
+**Utilisation**:
+
+```
+qmk cformat [file1] [file2] [...] [fileN]
+```
+
+## `qmk config`
+
+Cette commande vous permet de configurer le comportement de QMK. Pour la documentation complète de `qmk config`, regardez [Configuration de CLI](cli_configuration.md).
+
+**Utilisation**:
+
+```
+qmk config [-ro] [config_token1] [config_token2] [...] [config_tokenN]
+```
+
+## `qmk doctor`
+
+Cette commande examine votre environnement et vous alertes des potentiels problèmes de compilation ou de flash.
+
+**Utilisation**:
+
+```
+qmk doctor
+```
+
+## `qmk new-keymap`
+
+Cette commande crée une nouvelle keymap basée sur une keymap par défaut d'un clavier existant.
+
+**Utilisation**:
+
+```
+qmk new-keymap [-kb KEYBOARD] [-km KEYMAP]
+```
+
+## `qmk pyformat`
+
+Cette commande formatte le code python dans `qmk_firmware`.
+
+**Utilisation**:
+
+```
+qmk pyformat
+```
+
+## `qmk pytest`
+
+Cette commande démarre la suite de test python. Si vous faites des changements dans le code Python, assurez vous que les tests se lancent avec succès.
+
+**Utilisation**:
+
+```
+qmk pytest
+```

docs/fr-FR/cli_configuration.md

@@ -0,0 +1,121 @@
+# Configuration de QMK CLI
+
+Ce document explique comment fonctionne la commande `qmk config`.
+
+# Introduction
+
+La configuration pour QMK CLI est un système clé/valeur. Chaque clé est composée d'une sous-commande et d'un argument séparé par une virgule. Cela permet une traduction simple et directe entre les clés de configuration et l'argument qu'elle définit.
+
+## Exemple simple
+
+Comme exemple, regardons la commande `qmk compile --keyboard clueboard/66/rev4 --keymap default`.
+
+Il y a deux arguments de ligne de commande qui peuvent être lu de la configuration:
+
+* `compile.keyboard`
+* `compile.keymap`
+
+Essayons de les définir:
+
+```shell
+$ qmk config compile.keyboard=clueboard/66/rev4 compile.keymap=default
+compile.keyboard: None -> clueboard/66/rev4
+compile.keymap: None -> default
+Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini'
+```
+
+Maintenant, je peux lancer la commande `qmk compile` sans avoir à spécifier mon clavier et keymap à chaque fois.
+
+## Définir les options par défaut
+
+Parfois, il est utile de partager une configuration entre plusieurs commandes. Par exemple, plusieurs commandes prennent un argument `--keyboard`. Plutôt que de devoir définir cette valeur pour chaque commande, vous pouvez définir une valeur d'utilisateur qui sera utilisée par toutes les commandes qui prennent cet argument.
+
+Exemple:
+
+```
+$ qmk config user.keyboard=clueboard/66/rev4 user.keymap=default
+user.keyboard: None -> clueboard/66/rev4
+user.keymap: None -> default
+Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini'
+```
+
+# CLI Documentation (`qmk config`)
+
+La commande `qmk config` est utilisée pour intéragir avec la configuration sous-jacente. Lancée sans argument, elle affiche la configuration courante. Lorsque des arguments sont définis, ils sont considérés comme étant des jetons de configuration, qui sont des chaînes de caractère ne contenant aucun espace avec le format suivant:
+
+    <subcommand|general|default>[.<key>][=<value>]
+
+## Définir des valeurs de configuration
+
+Vous pouvez définir des valeurs de configuration en mettant le caractère égal (=) dans votre clé de configuration. La clé doit toujours être dans le format complet `<section>.<key>`.
+
+Exemple:
+
+```
+$ qmk config default.keymap=default
+default.keymap: None -> default
+Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini'
+```
+
+## Lire des valeurs de configuration
+
+Vous pouvez lire les valeurs de configuration pour la totalité de la configuration, une seule clé, ou une section entière. Vous pouvez aussi spécifier plusieurs clés pour afficher plus d'une valeur.
+
+### Exemple avec la totalité de la configuration
+
+    qmk config
+
+### Exemple avec une section entière
+
+    qmk config compile
+
+### Exemple avec une clé unique
+
+    qmk config compile.keyboard
+
+### Exemple avec plusieurs clés
+
+    qmk config user compile.keyboard compile.keymap
+
+## Supprimer des valeurs de configuration
+
+Vous pouvez supprimer une valeur de configuration en la définissant avec la chaîne spéciale `None`.
+
+Exemple:
+
+```
+$ qmk config default.keymap=None
+default.keymap: default -> None
+Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini'
+```
+
+## Plusieurs opérations
+
+Vous pouvez combiner plusieures opérations d'écriture et de lecture en une seule commande. Elle seront exécutées et affichées dans l'ordre:
+
+```
+$ qmk config compile default.keymap=default compile.keymap=None
+compile.keymap=skully
+compile.keyboard=clueboard/66_hotswap/gen1
+default.keymap: None -> default
+compile.keymap: skully -> None
+Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini'
+```
+
+# Options de configuration utilisateur
+
+| Clé | Valeur par défaut | Description |
+|-----|---------------|-------------|
+| user.keyboard | None | Le chemin d'accès vers le clavier (Exemple: `clueboard/66/rev4`) |
+| user.keymap | None | Le nom de la keymap (Exemple: `default`) |
+| user.name | None | Le nom d'utilisateur GitHub de l'utilisateur. |
+
+# Toutes les options de configuration
+
+| Clé | Valeur par défaut | Description |
+|-----|---------------|-------------|
+| compile.keyboard | None | Le chemin d'accès vers le clavier (Exemple: `clueboard/66/rev4`) |
+| compile.keymap | None | Le nom de la keymap (Exemple: `default`) |
+| hello.name | None | Le nom à saluer lorsque démarré. |
+| new_keyboard.keyboard | None | Le chemin d'accès vers le clavier (Exemple: `clueboard/66/rev4`) |
+| new_keyboard.keymap | None | Le nom de la keymap (Example: `default`) |

docs/fr-FR/contributing.md

@@ -0,0 +1,154 @@
+# Comment contribuer
+
+👍🎉 Premièrement, merci de prendre le temps de lire ceci et de contribuer! 🎉👍
+
+Les contributions de tiers nous aide à améliorer et faire grandir QMK. Nous voulons rendre les pull requests et le processus de contribution utile et simple à la fois pour les contributeurs et les mainteneurs. C'est pourquoi nous avons mis en places des directives pour les contibuteurs afin que votre pull request puisse être accepté sans changement majeur.
+
+* [Aperçu du projet](#project-overview)
+* [Conventions de codage](#coding-conventions)
+* [Directives générales](#general-guidelines)
+* [Que veut dire le code de conduite pour moi?](#what-does-the-code-of-conduct-mean-for-me)
+
+## Je ne veux pas lire tout ce pavé! J'ai juste une question!
+
+Si vous voulez poser une question sur QMK, vous pouvez le faire sur le [sous-reddit OLKB](https://reddit.com/r/olkb) ou sur [Discord](https://discord.gg/Uq7gcHh).
+
+Merci de garder ceci en tête:
+
+* Cela peut prendre plusieurs heures pour que quelqu'un réponde à votre question. Merci d'être patient!
+* Tous ceux impliqués avec QMK fait don de son temps et de son énergie. Nous ne sommes pas payés pour travailler sur ou répondre aux questions concernant QMK.
+* Essayez de poser vos questions de manière à ce qu'elles soient le plus simple à répondre possible. Si vous n'êtes pas sûrs de savoir comment faire, voici quelques bon guides (en anglais):
+  * https://opensource.com/life/16/10/how-ask-technical-questions
+  * http://www.catb.org/esr/faqs/smart-questions.html
+
+# Aperçu du projet
+
+QMK est majoritairement écrit en C, avec quelques fonctions et parties spécifiques écrites en C++. Il est destiné aux processeurs intégrés que l'on trouve dans des clavier, particulièrement AVR ([LUFA](http://www.fourwalledcubicle.com/LUFA.php)) et ARM ([ChibiOS](http://www.chibios.com)). Si vous maîtrisez déjà la programmation sur Arduino, vous trouverez beaucoup de concepts et de limitations familiers. Une expérience préalable avec les Arduino n'est pas nécessaire à contribuer avec succès à QMK.
+
+<!-- FIXME: We should include a list of resources for learning C here. -->
+
+# Où trouver de l'aide?
+
+Si vous avez besoin d'aide, vous pouvez [ouvrir une issue](https://github.com/qmk/qmk_firmware/issues) ou [un chat sur Discord](https://discord.gg/Uq7gcHh).
+
+# Comment contribuer?
+
+Vous n'avez encore jamais contribué à un projet open source? Vous vous demandez comment les contributions dans QMK fonctionnent? Voici un aperçu rapide!
+
+0. Enregistrez-vous sur [GitHub](https://github.com).
+1. Définissez une keymap à contribuer, [trouvez une issue](https://github.com/qmk/qmk_firmware/issues) que vous souhaitez corriger, ou [une fonction](https://github.com/qmk/qmk_firmware/issues?q=is%3Aopen+is%3Aissue+label%3Afeature) que vous voulez ajouter.
+2. Créez un fork sur le dépôt associé avec une issue sur votre compte GitHub. Cela veut dire que vous allez avoir une copie du dépôt sous `votre-login-GitHub/qmk_firmware`.
+3. Clonez le dépôt sur votre macine locale en utilisant `git clone https://github.com/login-github/repository-name.git`.
+4. Si vous travaillez sur une nouvelle fonctionnalité, pensez à ouvrir une issue pour parler avec nous du travail que vous souhaitez démarrer.
+5. Créez une nouvelle branche pour votre correctif en utilisant `git checkout -b nom-de-branche`.
+6. Faites les changements nécessaires pour corriger le problème ou ajouter la fonctionnalité.
+7. Utilisez `git add chemin-de-fichier` pour ajouter les contenus des fichiers modifiés au "snapshot" que git utilise pour gérer l'état du projet, appelé aussi l'index.
+8. Utilisez `git commit -m "Insérez une description courte des changements (en anglais)"` pour enregistrer le contenu de l'index avec un message descriptif.
+9. Poussez les changements vers votre dépôt sur GitHub en utilisant `git push origin nom-de-branche`.
+10. Créez un pull request sur [QMK Firmware](https://github.com/qmk/qmk_firmware/pull/new/master).
+11. Donnez un titre à votre pull request en utilisant une description courte des changements que vous avez fait et ajoutez le numéro de l'issue ou du bug associé avec votre changement. Les commentaires de PR devraient se faire en anglais de préférence. Par exemple, vous pouvez utiliser un titre tel que celui-là: "Added more log outputting to resolve #4352".
+12. Dans la description du pull request, expliquez les changements que vous avez fait et tous les problèmes qui existent, selon vous, sur le pull request que vous avez fait. Vous pouvez aussi utiliser la description pour poser des questions au mainteneur. Il n'est pas nécessaire que votre pull request soit parfait (aucun pull request ne l'est), le reviewer sera là pour vous aider à résoudre les problèmes et l'améliorer!
+13. Attendez que le pull request soit revu par un mainteneur.
+14. Faites des changements au pull request si le mainteneur le recommande.
+15. Célébrez votre succès une fois votre pull request fusionné!
+
+# Conventions de codage
+
+La grande majorité de notre style est plutôt simple à comprendre. Si vous connaissez C ou Python, vous ne devriez pas avoir trop de difficulté avec notre style.
+
+* [Conventions de codage - C](coding_conventions_c.md)
+* [Conventions de codage - Python](coding_conventions_python.md)
+
+# Directives générales
+
+Nous avons un certain nombre de type de changements dans QMK, chacun nécessitant un niveau de rigueur différent. Nous voulons que vous gardiez les directives suivantes en tête quel que soit le changement que vous êtes en train de faire.
+
+* Séparez les PR dans des unités logiques. Par exemple, ne soumettez pas un PR qui couvre deux fonctionnalités séparées, soumettez plutôt un PR pour chaque fonctionnalité.
+* Vérifiez les espaces blancs non nécessaires avec `git diff --check` avant de commit.
+* Assurez-vous que votre code compile.
+  * Keymaps: Assurez-vous que `make keyboard:your_new_keymap` ne renvoie pas d'erreur.
+  * Claviers: Assurez-vous que `make keyboard:all` ne renvoie pas d'erreur.
+  * Core: Assurez-vous que `make all` ne renvoie pas d'erreur.
+* Assurez-vous que les messages de commit soient compréhensibles d'eux-même. Vous devriez écrire une description simple (pas plus de 70 caractères) sur la première ligne, suivi d'une ligne vide, suivi d'un détail de votre commit, si nécessaire. Exemple:
+
+```
+Adjust the fronzlebop for the kerpleplork
+
+The kerpleplork was intermittently failing with error code 23. The root cause was the fronzlebop setting, which causes the kerpleplork to activate every N iterations.
+
+Limited experimentation on the devices I have available shows that 7 is high enough to avoid confusing the kerpleplork, but I'd like to get some feedback from people with ARM devices to be sure.
+```
+
+## Documentation
+
+La documentation est l'une des manière les plus simples de démarrer la contribution sur QMK. Il est simple de trouver des endroits où la documentation est fausse ou incomplète, et il est tout aussi simple de la corriger! Nous avons aussi grandement besoin de quelqu'un pour éditer notre documentation, donc si vous avez des compétences en édition mais que vous n'êtes pas sûr de savoir où aller, n'hésitez pas [demandez de l'aide](#where-can-i-go-for-help)!
+
+Vous trouverez toute notre documentation dans le répertoire `qmk_firmware/docs`, ou si vous préférez utiliser des outils web, vous pouvez cliquer sur le bouton "Suggest An Edit" en haut de chaque page sur http://docs.qmk.fm/.
+
+Lorsque vous donnez des exemples de code dans la documentation, essayez de suivre les conventions de nommage utilisées ailleurs dnas la documentation. Par exemple, standardisez les enums en utilisant `my_layers` ou `my_keycodes` afin de garder une consistance:
+
+```c
+enum my_layers {
+  _FIRST_LAYER,
+  _SECOND_LAYER
+};
+
+enum my_keycodes {
+  FIRST_LAYER = SAFE_RANGE,
+  SECOND_LAYER
+};
+```
+
+## Keymaps
+
+La plupart des contributeurs débutants démarrent avec leurs keymaps personnelles. Nous essayons de garder les standards pour les keymaps pluôt simple (les keymaps reflètent, après tout, la personnalité de leurs créateurs) mais nous demandons que vous suiviez les directives suivantes afin que d'autres puissent découvrir et apprendre de votre keymap.
+
+* Ecrivez un fichier `readme.md` en utilisant [la template](documentation_templates.md).
+* Tous les PR de keymaps doivent être "squashés", donc si la manière dont vos commits sont squashés vous est important, vous devez le faire vous-même.
+* Ne regroupez pas des fonctionnalités avec votre PR de keymap. Envoyez d'abord votre fonctionnalité, puis créez un second PR pour la keymap.
+* N'incluez pas de fichier `Makefile` dans votre dossier de keymap (ils ne sont plus utilisés)
+* Mettez à jour les copyrights dans les en-têtes de fichiers (cherchez `%YOUR_NAME%`)
+
+## Claviers
+
+Les claviers sont la raison d'être de QMK. Certains claviers sont maintenus par la communauté, alors que d'autre sont maintenus par les gens responsables de la création du clavier. Le fichier `readme.md` devrait vous informer de qui maintient le clavier. Si vous avez des questions concernant un clavier en particulier, vous pouvez [Ouvrir une issue](https://github.com/qmk/qmk_firmware/issues) et tagger le mainteneur dans votre question.
+
+Nous vous demandons aussi que vous suiviez ces directives:
+
+* Ecrivez un fichier `readme.md` en utilisant [le template](documentation_templates.md).
+* Gardez un nombre de commits raisonnable, ou nous squasherons votre PR.
+* Ne regroupez pas des fonctionnalités avec le PR pour votre clavier. Envoyez d'abord votre fonctionnalité, puis créez un second PR pour le clavier.
+* Appelez les fichiers `.c`/`.h` du nom du dossier parent, par exemple `/keyboards/<kb1>/<kb2>/<kb2>.[ch]`
+* N'incluez pas de fichier `Makefile` dans votre dossier de keymap (ils ne sont plus utilisés)
+* Mettez à jour les copyrights dans les en-têtes de fichiers (cherchez `%YOUR_NAME%`)
+
+## Quantum/TMK Core
+
+Faites attention d'être sûr d'implémenter votre nouvelle fonctionnalité de la meilleure manière qu'il soit avant d'investir beaucoup de travail à son développement. Vous pouvez apprendre les bases de QMK en lisant [Comprendre QMK](understanding_qmk.md), qui vous donnera une idée du flux du programme QMK. A partir de là, parlez nous afin de définir la meilleure façon d'implémenter votre idée. Il y a deux façons principale de le faire:
+
+* [Chat sur Discord](https://discord.gg/Uq7gcHh)
+* [Ouvrir une Issue](https://github.com/qmk/qmk_firmware/issues/new)
+
+Les PR de nouvelles fonctionnalités de de correction de bug affectent tous les claviers. Nous sommes aussi dans un processus de restructuration de QMK. Pour cette raison, il est absolument nécessaire que tout changement important ou significatif soit discuté avant que l'implémentation soit faite. Si vous ouvrez un PR sans nous avoir parlé, préparez vous à faire des refontes significatives si vous changements ne sont pas compatibles avec ce que nous avons planifié.
+
+Voici quelques choses à garder en tête lorsque vous travaillez sur une fonctionnalité ou un bug fix.
+
+* **Désactivé par défaut** - la mémoire est plutôt limitée sur la plupart des puces que QMK supporte, et il est important que les keymaps courantes ne soient pas cassées. S'il vous plaît faites que vos features doivent être **activées** plutôt que désactivées. Si vous pensez qu'elle devrait être activée par défaut, ou que cela réduit la taille du code, parlez-nous en.
+* **Compilez localement avant de soumettre** - Cela devrait aller sans dire, mais votre code doit compiler! Notre système Travis devrait relever les problèmes, mais il est généralement plus rapide de compiler quelques claviers en local plutôt que d'attendre le retour des résultats
+* **Faites attention aux révisions et différentes bases de puces** - beaucoup de claviers ont des révisions qui permettent des changements de configuration mineurs, voir des bases de chip différentes. Essayez de faire que votre fonctionnalité soit supportée à la fois sur ARM et AVR, ou désactivez-là automatiquement sur les plateformes non supportées.
+* **Expliquez votre fonctionnalité** - Documentez-là dans `docs/`, soit dans un nouveau fichier, ou dans une partie d'un fichier existant. Si vous ne la documentez pas, personne ne pourra bénéficier de votre dur labeur.
+
+Nous vous demandons aussi de suivre ces ces directives:
+
+* Gardez un nombre de commits raisonnable, ou nous squasherons votre PR.
+* Ne regroupez pas des claviers ou des keymaps avec des changements core. Soumettez vos changements core en premier.
+* Ecrivez des [Tests Unitaires](unit_testing.md) pour votre fonctionnalité.
+* Suivez le style du fichier que vous modifiez. Si le style n'est pas clair ou qu'il y a un mélange de fichiers, vous devriez vous conformer aux [conventions de codage](#coding-conventions) au dessus.
+
+## Refactoriser
+
+Afin de maintenir une vision claire sur comment les choses sont architectuées dans QMK, nous essayons de planifier des refactorisations en profondeur et qu'un collaborateur fasse le changement. Si vous avez une idée de refactorisation, ou une suggestion, [ouvrez une issue] [open an issue](https://github.com/qmk/qmk_firmware/issues), nous adorons discuter de comment améliorer QMK.
+
+# Que veut dire le code de conduite pour moi?
+
+Note [Code De Conduite](https://github.com/qmk/qmk_firmware/blob/master/CODE_OF_CONDUCT.md) veut dire que vous avez la responsabilité de traiter tout le monde dans le projet avec respect et courtoisie, peut importe leur identité. Si vous êtes victime d'une attitude ou de commentaires inapropriés, tels que décrit dans notre Code de Conduite, nous sommes là pour vous et nous ferons de notre mieux pour nous assurer que le fautif soit réprimandé, tel que décrit dans notre code.

docs/fr-FR/flashing.md

@@ -0,0 +1,236 @@
+# Instructions pour flasher et informations sur les bootloader
+
+Les claviers utilisent différents types de bootloaders et certains doivent être flashés différement. Heureusement, certains projets comme la [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) ont pour objectifs de permettre de flasher les différents bootloader sans trop se faire de soucis et ça peut importe les manières de les flasher.
+
+Si vous avez un bootloader sélectionné avec la variable `BOOTLOADER` dans votre fichier `rules.mk` alors QMK vas automatiquement calculer si votre fichier .hex n'est pas trop grand pour être flashé sur votre appareil, et il affichera la taille finale du firmware. Pour vérifier la taille manuellement, vous pouvez aussi compiler le firmware avec l'option `check-size`. Exemple : `make planck/rev4:default:check-size`.
+
+## DFU
+
+Le bootloader pour les processeurs Atmel DFU est fourni par défaut sur tous les processeurs atmega32u4. Celui-ci est utilisé par beaucoup de claviers plus vieux que les OLKB et Clueboard qui ont leur propre ICs sur leurs PCBs. D'autres claviers utilisent le bootloader DFU de LUFA (ou son fork QMK), notamment les nouveaux claviers OLKB. Ce dernier ajoute des fonctionnalités spécifiques sur le matériel.
+
+Pour vérifier la compatibilité avec le bootloader DFU, vérifiez que ce bloc de code est présent dans votre fichier `rules.mk`. Parfois il peut être inscrit `lufa-dfu` ou `qmk-dfu` à la place.
+
+```make
+# Bootloader selection
+#   Teensy       halfkay
+#   Pro Micro    caterina
+#   Atmel DFU    atmel-dfu
+#   LUFA DFU     lufa-dfu
+#   QMK DFU      qmk-dfu
+#   ATmega32A    bootloadHID
+#   ATmega328P   USBasp
+BOOTLOADER = atmel-dfu
+```
+
+Méthodes de flash compatibles :
+
+* [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) (interface graphique recommandé)
+* [dfu-programmer](https://github.com/dfu-programmer/dfu-programmer) / `:dfu` avec QMK (outil en ligne de commande recommandé)
+* [Atmel's Flip](http://www.microchip.com/developmenttools/productdetails.aspx?partno=flip) (non recommandé)
+
+Ordre des actions :
+
+1. Pressez le keycode `RESET`, ou appuyez sur le bouton physique RESET ou alors créez un contact entre RST et GND.
+2. Attendez que l'OS detecte l'appareil.
+3. Éffacez la mémoire, cela peut être fait automatiquement.
+4. Flasher le fichier .hex.
+5. Redémarrez l'appareil en mode « application », cela peut être fait automatiquement.
+
+Alternativement :
+
+    make <keyboard>:<keymap>:dfu
+
+### DFU QMK
+
+QMK a un fork du bootloader LUFA DFU qui vous permet de faire un simple scan de la matrice pour quitter le bootloader et retourner à l'application. En même temps que le flash se produira, il est possible de faire flasher un led ou de produire un son via un haut parleur. Pour activer ces fonctionnalités, vous pouvez utiliser ce bloc dans votre fichier `config.h` (La touche permettant de quitter le bootloader a besoin d'être reliée entre les ports définis en INPUT et OUTPUT ici):
+
+    #define QMK_ESC_OUTPUT F1 // usually COL
+    #define QMK_ESC_INPUT D5 // usually ROW
+    #define QMK_LED E6
+    #define QMK_SPEAKER C6
+
+Le fabriquant et le nom du produit proviennent de vos définitions dans fichier  `config.h`, et la chaîne de caractère « bootloader » est ajoutée au nom du prodruit.
+
+Pour génerer le bootloader, utilisez la cible `bootloader`. Exemple : `make planck/rev4:default:bootloader`.
+
+Pour génerer un fichier .hex prêt pour la production qui contiendra tant l'application que le bootloader, utilisez la cible `production`. Exemple : `make planck/rev4:default:production`.
+
+### Commandes DFU
+
+Il y a plusieurs commandes DFU que vous pouvez utiliser pour flasher le firmware sur un appareil DFU.
+
+* `:dfu` - C'est l'option normale qui attend qu'un appareil DFU soit disponible et qui flashe le firmware dès que c'est le cas. La vérification sera faite toutes les 5 secondes.
+* `:dfu-ee` - Cette option flash un fichier `.eep` à la place d'un fichier `.hex`. Ce cas est plutôt rare.
+* `:dfu-split-left` - Cette option flashe le firmware normal comme avec l'option (`:dfu`). Mais cela aussi flash le coté gauche du fichier EEPROM pour les claviers scindés. _C'est l'option idéale pour un clavier scindé basé sur le Elite C_
+* `:dfu-split-right` - Cette option flashe le firmware normal comme avec l'option (`:dfu`).  Mais cela aussi flash le coté droite du fichier EEPROM pour les claviers scindés. _C'est l'option idéale pour un clavier scindé basé sur le Elite C_
+
+## Caterina
+
+Les cartes arduinos et leurs clones utilisent le [bootloader Caterina](https://github.com/arduino/ArduinoCore-avr/tree/master/bootloaders/caterina) (tous les claviers utilisant un Pro Micro, ou un clone). Ils utilisent aussi le protocole avr109 pour communiquer en virtuellement en série (serial en Anglais). Les bootloaders comme le [A-Star](https://www.pololu.com/docs/0J61/9) sont basés sur Caterina.
+
+Pour vérifier la compatibilité avec un bootloader Caterina, vérifiez que ce bloc est présent dans votre fichier `rules.mk` :
+
+```make
+# Bootloader selection
+#   Teensy       halfkay
+#   Pro Micro    caterina
+#   Atmel DFU    atmel-dfu
+#   LUFA DFU     lufa-dfu
+#   QMK DFU      qmk-dfu
+#   ATmega32A    bootloadHID
+#   ATmega328P   USBasp
+BOOTLOADER = caterina
+```
+
+Flashers compatibles :
+
+* [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) (Interface graphique recomandée)
+* [avrdude](http://www.nongnu.org/avrdude/) avec avr109 / `:avrdude` (Outil en ligne de commande recomandé)
+* [AVRDUDESS](https://github.com/zkemble/AVRDUDESS)
+
+Séquence de flash : 
+
+1. Pressez la touche avec le keycode `RESET`, ou reliez les ports GND et RST. Vous n'avez que 7 secondes pour flasher une fois que l'opération a été faite.
+2. Attendez que l'OS détecte l'appareil.
+3. Flasher le fichier .hex.
+4. Attendez que l'appareil redémarre automatiquement.
+
+ou, utilisez :
+
+    make <keyboard>:<keymap>:avrdude
+
+ou, si vous vous voulez flasher plusieurs claviers, utilisez la commande suivante :
+
+    make <keyboard>:<keymap>:avrdude-loop
+
+Quand vous avez fini de flasher vos claviers, vous aurez besoin d'utiliser Ctrl + C ou alors la touche ayant la fonction similaire sur votre OS pour sortir de la boucle.
+
+## Halfkay
+
+Halfkay est un protocole ultra-simple développé par PJRC qui utilise HID et qui est fourni avec tous les Teensys après le modèle 2.0.
+
+Pour vérifier la compatibilité avec le booloader Halfkay, vérifiez que ce bloc est présent dans votre fichier `rules.mk` :
+
+```make
+# Bootloader selection
+#   Teensy       halfkay
+#   Pro Micro    caterina
+#   Atmel DFU    atmel-dfu
+#   LUFA DFU     lufa-dfu
+#   QMK DFU      qmk-dfu
+#   ATmega32A    bootloadHID
+#   ATmega328P   USBasp
+BOOTLOADER = halfkay
+```
+
+Flasher compatibles :
+
+* [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) (Interface graphique recomandée)
+* [Teensy Loader](https://www.pjrc.com/teensy/loader.html) (petit utilitaire ultra simple)
+ [Teensy Loader en ligne de commande](https://www.pjrc.com/teensy/loader_cli.html) (Outil en ligne de commande recommandé)
+
+Séquence de flash :
+
+1. Pressez la touche du keycode `RESET`, ou reliez les ports RST et GND rapidement. Vous avez ensuite 7 secondes pour réaliser le flash.
+2. Attendez que l'OS détecte l'appareil.
+3. Flasher le fichier .hex.
+4. Redémarrez l'appareil en mode « application ». Cela peut être fait automatiquement.
+
+## USBasploader
+
+USBasploader est un bootloader développé par matrixstorm. Il est utilisé sur des processeurs AVR non-USB comme le ATmega328P, qui fonctionne grâce à V-USB.
+
+Pour vérifier la compatibilité avec le booloader USBasploader, vérifiez que ce bloc est présent dans votre fichier `rules.mk` :
+
+```make
+# Bootloader selection
+#   Teensy       halfkay
+#   Pro Micro    caterina
+#   Atmel DFU    atmel-dfu
+#   LUFA DFU     lufa-dfu
+#   QMK DFU      qmk-dfu
+#   ATmega32A    bootloadHID
+#   ATmega328P   USBasp
+BOOTLOADER = USBasp
+```
+
+Flashers compatibles :
+
+* [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) (Interface graphique recommandé)
+* [avrdude](http://www.nongnu.org/avrdude/) avec le programmeur `usbasp`.
+* [AVRDUDESS](https://github.com/zkemble/AVRDUDESS)
+
+Séquence de flash :
+
+1. Pressez la touche du keycode `RESET`, ou reliez le port de boot pendant que RST et GND snt reliés. Cela doit être fait très rapidement.
+2. Attendez que l'OS détecte l'appareil.
+3. Flasher le fichier .hex.
+4. Redémarrez l'appareil en mode « application ». Cela peut être fait automatiquement.
+
+## BootloadHID
+
+BootloadHID est un bootloader pour les microcontroleurs AVR. L'utilitaire de téleversement ne demande pas de drivers au niveau du kernel et peut être lancé sans installer aucune DLLs.
+
+Pour vérifier la compatibilité avec le bootloader bootloadHID, vérifiez que ce bloc existe dans votre fichier `rules.mk` : 
+
+```make
+# Bootloader selection
+#   Teensy       halfkay
+#   Pro Micro    caterina
+#   Atmel DFU    atmel-dfu
+#   LUFA DFU     lufa-dfu
+#   QMK DFU      qmk-dfu
+#   ATmega32A    bootloadHID
+#   ATmega328P   USBasp
+BOOTLOADER = bootloadHID
+```
+
+Utilitaires de flash compatibles :
+
+* [HIDBootFlash](http://vusb.wikidot.com/project:hidbootflash) (Utilitaire avec interface graphique recommandé)
+* [bootloadhid Command Line](https://www.obdev.at/products/vusb/bootloadhid.html) / `:BootloadHID` avec QMK (utilitaire en ligne de commande recommandé)
+
+Séquence de flash
+
+1. Entrez dans le bootloader en utilisant l'une de ces méthodes :
+    * Pressez la touche du keycode `RESET` (Cela ne fonctionnera pas sur certains appareils).
+    * Verouillez la touche « Salt » tout en branchant le clavier (Géneralement ce principe est documenté dans le fichier readme du clavier)
+2. Attendez que l'OS détecte l'appareil.
+3. Flasher le fichier .hex.
+4. Redémarrez l'appareil en mode « application ». Cela peut être fait automatiquement.
+
+Ou alors :
+
+    make <keyboard>:<keymap>:bootloadHID
+
+## STM32
+
+Tous les processeurs STM32 contiennent un bootloader installé en usine qui ne peut pas être modifié ou supprimé. Certains processeurs STM32 ont des bootloaders qui ne peuvent pas être programmés par USB (ex : STM32F103) mais le processus reste le même.
+
+Pour le moment, aucune variable `BOOTLOADER` n'est nécessaire dans le fichier `rules.mk`.
+
+Flashers compatibles :
+
+* [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) (interface graphique recommandé)
+* [dfu-util](https://github.com/Stefan-Schmidt/dfu-util) / `:dfu-util` (utilitaire en ligne de commande recommandé)
+
+Séquence pour flasher:
+
+1. Entrez dans le bootloader en utilisant l'une de ces méthodes :
+    * Utilisez une touche sur laquelle le keycode `RESET` (Cela peut ne pas fonctionner sur les appareils STM32F042)
+    * Si un circuit de réinitialisation (Reset) est présent alors utilisé le bouton qui lui est dédié.
+    * Autrement, vous devez réaliser une liaison entre BOOT0 et VCC (en appuyant sur le bouton ou à l'aide d'un pont) puis faire un pont entre RESET et GND et enfin relacher le pont BOOT0.
+2. Attendre que l'os détecte l'appareil.
+3. Flasher un fichier `.bin`.h
+    * Vous allez recevoir un avertissement à propos de la signature DFU. Ignorez-la.
+4. Réinitialisez l'appareil en mode « application ». Cela peut être fait automatiquement.
+    * Si vous êtes en train de travailler en ligne de commande, par exemple avec un `make planck/rev6:default:dfu-util` alors soyez bien sur que l'argument `:leave` est passé aux argument DFU grâce à la variable `DFU_ARGS` à l'intérieur de votre fichier `rules.mk` (Ex : `DFU_ARGS = -d 0483:df11 -a 0 -s 0x08000000:leave`) afin que votre appareil redémarre après avoir été flashé.
+
+### Commandes STM32
+
+Il y a différentes commandes que vous pouvez utiliser pour flasher un firmware dans un appareil STM32  :
+
+* `:dfu-util` - La commande par défaut pour flasher un appareil STM32.
+* `:dfu-util-split-left` - Permet de flasher un firmware normalement, tout comme l'option précedente mais permet de configurer le coté gauche des paramètres EEPROM sur un clavier scindé.
+* `:dfu-util-split-right` - Permet de flasher un firmware normalement, tout comme l'option précedente mais permet de configurer le coté droit des paramètres EEPROM sur un clavier scindé.
+* `:st-link-cli` - Cela permet de flasher le firmware avec l'utilitaire en ligne de commande ST-LINK's plutôt que d'utiliser dfu-util.

docs/fr-FR/getting_started_getting_help.md

@@ -0,0 +1,15 @@
+# Trouver de l'aide
+
+Il y a beaucoup de ressources pour trouver de l'aide avec QMK.
+
+## Chat temps-réel
+
+Vous trouverez des développeurs QMK et des utilisateurs sur notre [Serveur Discord](https://discord.gg/Uq7gcHh) principal. Il y a des canaux spécifiques dans le serveurs pour discuter des firmware, toolbox, hardware et configurateurs.
+
+## Sous-Reddit OLKB
+
+Le forum officiel de QMK est [/r/olkb](https://reddit.com/r/olkb) sur [reddit.com](https://reddit.com).
+
+## Tickets GitHub
+
+Vous pouvez ouvrir un [ticket sur GitHub](https://github.com/qmk/qmk_firmware/issues). Ceci est spécialement pratique lorsque votre problème demande une discussion long terme ou un débugage.

docs/fr-FR/getting_started_github.md

@@ -0,0 +1,61 @@
+# Comment utiliser GitHub avec QMK
+
+GitHub peut être un peu compliqué pour ceux qui n'y sont pas familier. Ce guide va vous expliquer chaque étape de "fork", clone et envoi d'un pull request avec QMK.
+
+?> Ce guide part du principe que vous êtes suffisamment à l'aise pour envoyer commandes sur la ligne de commande et que vous avez Git installé sur votre système.
+
+Commencez par la [page GitHub de QMK](https://github.com/qmk/qmk_firmware), et vous verrez un bouton dans le coin en haut à droite qui indique "Fork":
+
+![Fork on Github](http://i.imgur.com/8Toomz4.jpg)
+
+Si vous faites partie d'une organisation, vous aurez besoin de savoir quel compte utiliser pour le fork. Dans la plupart des cas, vous voudrez créer le fork dans votre compte personnel. Une fois le fork complet (cela peut quelque fois prendre un peu de temps), appuyez sur le bouton "Clone or download":
+
+![Download from Github](http://i.imgur.com/N1NYcSz.jpg)
+
+Faites attention à sélectionner "HTTPS", et sélectionnez le liens et copiez-le:
+
+![HTTPS link](http://i.imgur.com/eGO0ohO.jpg)
+
+Ensuite, entrez `git clone` dans la ligne de commande, et collez votre lien:
+
+```
+user@computer:~$ git clone https://github.com/whoeveryouare/qmk_firmware.git
+Cloning into 'qmk_firmware'...
+remote: Counting objects: 46625, done.
+remote: Compressing objects: 100% (2/2), done.
+remote: Total 46625 (delta 0), reused 0 (delta 0), pack-reused 46623
+Receiving objects: 100% (46625/46625), 84.47 MiB | 3.14 MiB/s, done.
+Resolving deltas: 100% (29362/29362), done.
+Checking out files: 100% (2799/2799), done.
+```
+
+Vous avez maintenant votre fork QMK sur votre machine locale, vous pouvez ajouter votre keymap, la compiler et la flasher sur votre board. Une fois heureux avec vos changements, vous pouvez les ajouter, commit, et pousser vers votre fork comme suit:
+
+```
+user@computer:~$ git add .
+user@computer:~$ git commit -m "adding my keymap"
+[master cccb1608] adding my keymap
+ 1 file changed, 1 insertion(+)
+ create mode 100644 keyboards/planck/keymaps/mine/keymap.c
+user@computer:~$ git push
+Counting objects: 1, done.
+Delta compression using up to 4 threads.
+Compressing objects: 100% (1/1), done.
+Writing objects: 100% (1/1), 1.64 KiB | 0 bytes/s, done.
+Total 1 (delta 1), reused 0 (delta 0)
+remote: Resolving deltas: 100% (1/1), completed with 1 local objects.
+To https://github.com/whoeveryouare/qmk_firmware.git
+ + 20043e64...7da94ac5 master -> master
+```
+
+Vos changements existent maintenant dans votre fork sur GitHub. Si vous allez à cete adresse (`https://github.com/<whoeveryouare>/qmk_firmware`), vous pouvez créer un nouveau "Pull Request" en cliquant sur ce bouton:
+
+![New Pull Request](http://i.imgur.com/DxMHpJ8.jpg)
+
+Maintenant, vous pourrez voir exactement ce que vous avez commité. Si ça vous semble bien, vous pouvez le finaliser en cliquant sur "Create Pull Request":
+
+![Create Pull Request](http://i.imgur.com/Ojydlaj.jpg)
+
+Une fois transmis, nous pourrons vous parler de vos changements, vous demander de faire des changements, et éventuellement de les accepter!
+
+Merci de contribuer à QMK :)

docs/fr-FR/getting_started_introduction.md

@@ -0,0 +1,62 @@
+# Introduction
+
+Le but de cette page est d'expliquer les informations de base qui vous serons nécessaire pour travailler sur le projet QMK. Il a pour pré-requis que vous soyez familier à la navigation à l'aide d'un shell Unix, mais ne s'attend pas à ce que vous soyez familier avec C ou la compilation en utilisant make.
+
+## Structure de base de QMK
+
+QMK est un fork du projet [tmk_keyboard](https://github.com/tmk/tmk_keyboard) créé par [Jun Wako](https://github.com/tmk). Le code originel de TMK, avec quelques modifications, se trouve dans le dossier `tmk`. Les additions que QMK amène au projet se trouvent dans le dossier `quantum`. Les projets de clavier se trouvent dans les dossiers `handwired` et `keyboard`.
+
+### Structure du Userspace
+
+Dans le dossier `users` se trouve un répertoire pour chaque utilisateur. C'est un endroit où les utilisateurs peuvent mettre du code qui serait partagé entre plusieurs claviers. Merci de lire la documentation  [Fonctionnalité Userspace](feature_userspace.md) pour plus d'information.
+
+### Structure du projet clavier
+
+Dans le dossier `keyboards`, son sous-dossier `handwired` et ses sous-dossiers pour les revendeurs et fabriquants (par exemple `clueboard`) se trouve un répertoire pour chaque projet clavier. Par exemple `qmk_firmware/keyboards/clueboard/2x1800`.
+
+A l'intérieur, vous trouverez la structure suivante:
+
+* `keymaps/`: différentes keymaps qui peuvent être compilées
+* `rules.mk`: Ce fichier définit les options "make" par défaut. Ne modifiez pas ce fichier directement, utilisez à la place un `rules.mk` spécifique à la keymap.
+* `config.h`: Ce fichier définit les options de compilation par défaut. Ne modifiez pas ce fichier directement, utilisez à la place un `config.h` spécifique à la keymap.
+* `info.json`: Le fichier utilisé pour définir les options de layout de QMK Configurator. Voyez [Support Configurator](reference_configurator_support.md) pour plus d'information.
+* `readme.md`: une brève description du clavier.
+* `<keyboardName>.h`: Ce fichier définit le layout du fichier par rapport à la matrice de commutation.
+* `<keyboardName>.c`: Ce fichier définit du code custom pour le clavier.
+
+Pour plus d'information sur la structure du projet, voyez [Directives clavier QMK](hardware_keyboard_guidelines.md).
+
+### Structure d'une Keymap
+
+Dans chaque dossier keymap, vous allez trouver les fichiers suivants. Seul le fichier `keymap.c` est nécessaire, et si le reste des fichiers n'existent pas, les options par défaut seront choisies.
+
+* `config.h`: les options de configuration de votre keymap
+* `keymap.c`: tout le code de votre keymap, requis
+* `rules.mk`: les features de QMK qui sont activées
+* `readme.md`: une description de votre keymap, comment d'autres l'utiliseront, et des explications des fonctionnalités. Uploadez les images vers un service comme imgur.
+
+# Le fichier `config.h`
+
+Le fichier `config.h` peut être mis à 3 endroits:
+
+* keyboard (`/keyboards/<keyboard>/config.h`)
+* userspace (`/users/<user>/config.h`)
+* keymap (`/keyboards/<keyboard>/keymaps/<keymap>/config.h`)
+
+Le système de compilation cherche automatiquement les fichiers de configuration dans l'ordre au dessus. Si vous souhaitez surcharger une configuration définie par un `config.h` précédent, vous devrez d'abord ajouter le code suivant.
+
+```
+#pragma once
+```
+
+Ensuite, pour surcharger l'option du fichier `config.h` précédent, vous devez `#undef` puis `#define` l'option à nouveau.
+
+Voici à quoi l'ensemble du code resemble une fois regroupé:
+
+```
+#pragma once
+
+// overrides go here!
+#undef MY_SETTING
+#define MY_SETTING 4
+```

docs/fr-FR/newbs.md

@@ -0,0 +1,23 @@
+# Le Guide pour débutant complet à QMK
+
+QMK est un firmware Open Source pour votre clavier mécanique. Vous pouvez utiliser QMK pour customiser votre clavier de manière simple et puissante. Tout le monde, du débutant complet au développeur avancé, ont utilisé avec succès QMK pour customiser leur clavier. Ce guide vous aidera à faire de même, quelles que soient vos compétences.
+
+Vous voulez savoir si votre clavier peut utiliser QMK? Si c'est un clavier mécanique que vous avez vous-même construit, il y a de bonnes chances que vous pouvez. Nous supportons un [grand nombre de "hobbyist boards"](http://qmk.fr/keyboards), donc même si votre clavier ne peut pas utiliser QMK, vous ne devriez pas avoir trop de problème pour en trouver un qui vous convienne.
+
+## Vue d'ensemble
+
+Il y a 7 sections principales dans ce guide:
+
+* [Pour débuter](fr-FR/newbs_getting_started.md)
+* [Compiler votre premier firmware en utilisant la ligne de commande](fr-FR/newbs_building_firmware.md)
+* [Compiler votre premier firmware en utilisant l'interface graphique en ligne](fr-FR/newbs_building_firmware_configurator.md)
+* [Flasher le Firmware](fr-FR/newbs_flashing.md)
+* [Test et Débuggage](fr-FR/newbs_testing_debugging.md)
+* [Bonnes pratiques Git](fr-FR/newbs_best_practices.md)
+* [Ressources d'apprentissage](fr-FR/newbs_learn_more_resources.md)
+
+Ce guide a pour but principal d'aider quelqu'un qui n'a jamais compilé de logiciel avant. Les recommandations et les choix qu'il contient vont donc dans ce sens. Il y a des méthodes alternatives pour beaucoup de ces procédures, et nous supportons la plupart de ces alternatives. Si vous avez un doute sur comment accomplir une tâche, vous pouvez [nous demander de l'aide](fr-FR/getting_started_getting_help.md).
+
+## Ressources additionnelles
+
+* [Thomas Baart's QMK Basics Blog](https://thomasbaart.nl/category/mechanical-keyboards/firmware/qmk/qmk-basics/) – Un blog créé par un utilisateur qui couvre les bases de l'utilisation du Firmware QMK, vue d'un point de vue d'un nouvel utilisateur (anglais).

docs/fr-FR/newbs_best_practices.md

@@ -0,0 +1,161 @@
+# Bonnes Pratiques
+
+## Ou, "Comment j'ai appris à ne plus m'en faire et aimer Git."
+
+Ce document a pour but d'apprendre aux novices les meilleures solutions pour faciliter la contribution à QMK. Nous allons étudier le processus de contribution à QMK, détaillant quelques moyens de rendre cette tâche plus simple. Nous allons faire quelques erreurs afin de vous apprendre à les résoudre.
+
+Ce document suppose les choses suivantes:
+
+1. Vous avez un compte GitHub, et avez [créé un "fork" pour le dépôt qmk_firmware](fr-FR/getting_started_github.md) avec votre compte.
+2. Vous avez [configuré votre environnement de compilation](fr-FR/newbs_getting_started.md?id=environment-setup).
+
+## La branche master de votre fork: Mettre à jour souvent, ne jamais commit
+
+Il est hautement recommandé pour le développement de QMK, peu importe ce qui est fait ou où, de garder votre branche `master` à jour, mais de ne ***jamais*** commit dessus. A la place, faites tous vos changement dans une branche de développement et crééz des "pull requests" de votre branche lorsque vous développez.
+
+Pour réduire les chances de conflits de fusion (merge) — des cas où deux ou plus d'utilisateurs ont édité la même section d'un fichier en parallèle — gardez votre branche `master` relativement à jour et démarrez chaque nouveau développement en créant une nouvelle branche.
+
+### Mettre à jour votre branche master
+
+Pour garder votre branche `master` à jour, il est recommandé d'ajouter le dépôt du firmware QMK comme un dépôt distant (remote) dans git. pour se faire, ouvrez votre interface de ligne de commande Git et entrez:
+
+```bash
+git remote add upstream https://github.com/qmk/qmk_firmware.git
+```
+
+Pour vérifier que le dépôt a bien été ajouté, lancez la commande `git remote -v`, qui devrait retourner le résultat suivant:
+
+```bash
+$ git remote -v
+origin  https://github.com/<your_username>/qmk_firmware.git (fetch)
+origin  https://github.com/<your_username>/qmk_firmware.git (push)
+upstream        https://github.com/qmk/qmk_firmware.git (fetch)
+upstream        https://github.com/qmk/qmk_firmware.git (push)
+```
+
+Maintenant que c'est fait, vous pouvez vérifier les mises à jour au dépôt en lançant `git fetch upstream`. Cela récupère les branches et les tags &mdash; appelé de manière générale "refs" &mdash; du dépôt QMK, qui a maintenant le surnom `upstream`. Nous pouvons maintenant comparer les données sur notre "fork" `origin` à celles contenues par QMK.
+
+Pour mettre à jour la branche master de votre "fork", lancez les commandes suivantes (en appuyant sur Enter après chaque ligne):
+
+```bash
+git checkout master
+git fetch upstream
+git pull upstream master
+git push origin master
+```
+
+Cela vous change la branche courante en master, synchronise les données de réferences du dépôt QMK vers votre ordinateur. La commande pull tire les données de réferences vers votre branche courante puis les y téleverse. La commande push permet de pousser la branche courante (master) vers votre fork github.
+
+### Faire des changements
+
+Pour faire des changements, créez une nouvelle branche en entrant:
+
+```bash
+git checkout -b dev_branch
+git push --set-upstream origin dev_branch
+```
+
+Ceci crée une branche nommée `dev_branch`, bascule vers cette branche, et ensuite sauvegarde cette nouvelle branche vers votre fork. L'argument `--set-upstream` demande à git d'utiliser votre fork et la branche `dev_branch` à chaque fois que vous utilisez `git push` ou `git pull` depuis cette branche. Vous ne devez l'utiliser que pour le premier "push", après celà, vous pouvez utiliser simplement `git push` ou `git pull`, sans le reste des arguments.
+
+!> Avec `git push`, vous pouvez utiliser `-u` à la place de `--set-upstream` &mdash; `-u` est un alias pour `--set-upstream`.
+
+Vous pouvez appeler votre branche à peu prêt comme vous voulez, toutefois il est recommandé d'utiliser un nom qui est lié aux changements que vous allez faire.
+
+Par défaut, `git checkout -b` va faire de la branche actuelle la branche de base de votre nouvelle branche. Vous pouvez définir la base de votre nouvelle branche comme étant n'importe quelle branche existante qui n'est pas la courante en utilisant la commande:
+
+```bash
+git checkout -b dev_branch master
+```
+
+Maintenant que vous avez une branche de développement, ouvrez votre éditeur de texte et faites vos changements. Il est recommandé de faire beaucoup de petits commits dans votre branche. Ainsi, un changement qui crée un problème peut être plus facilement retracé et annulé si nécessaire. Pour faire un changement, éditez et sauvez n'importe quel fichier qui doit être mis à jour, ajoutez les à la *zone de staging* de Git, et commitez les vers votre branche:
+
+```bash
+git add path/to/updated_file
+git commit -m "My commit message."
+```
+
+`git add` ajoute les fichiers qui ont été changés dans la *zone de staging* de Git, qui est sa "zone de chargement". Elle contient tous les changements qui vont être *validés* (committed) par `git commit`, qui sauvegarde les changements vers le dépôt. Utilisez des messages de validation descriptifs afin que vous puissiez savoir ce qui a changé d'un coup d'oeil.
+
+!> Si vous changez beaucoup de fichiers, mais tous les fichiers font partie du même changement, vous pouvez utiliser `git add .` pour ajouter tous les fichiers changés dans le répertoire courant, plutôt que d'avoir à ajouter chaque fichiers individuellement.
+
+### Publier Vos Changements
+
+La dernière étape est de pousser vos changements vers votre fork. pour se faire, entrez `git push`. Git publie maintenant l'état courant de `dev_branch` vers votre fork.
+
+## Résoudre Les Conflits De Merge
+
+Parfois, lorsque votre travail sur une branche met beaucoup de temps à se compléter, des changements réalisés par d'autres peuvent entrer en conflit avec les changements que vous avez fait sur votre branche au moment où vous avez ouvert un pull request. Ceci est appelé un *conflit de merge*, et c'est ce qui arrive lorsque plusieurs personnes modifient les mêmes parties de mêmes fichiers.
+
+### Rebaser Vos Changements
+
+Un *rebase* est la manière pour Git de prendre les changements qui ont été faits à un point, les annuler, et les réappliquer sur un autre point. Dans le cas d'un conflit de merge, vous pouvez rebaser votre branche pour récupérer les changements qui ont été faits entre le moment où vous avez créé votre branche et le présent.
+
+Pour démarrer, lancez les commandes suivantes:
+
+```bash
+git fetch upstream
+git rev-list --left-right --count HEAD...upstream/master
+```
+
+La commande `git rev-list` retourne le nombre de commits qui diffère entre la branche courante et la branche master de QMK. Nous lançons `git fetch` en premier afin d'être sûr que les refs qui représentent l'état courant du dépôt upstream soient à jour. Le résultat de la commande `git rev-list` retourne deux nombres:
+
+```bash
+$ git rev-list --left-right --count HEAD...upstream/master
+7       35
+```
+
+Le premier nombre représente combien il y a eu de commits sur la branche courante depuis qu'elle a été créée, et le second nombre est combien de commits ont été faits sur la branche `upstream/master` depuis que la branche a été créée et, ainsi, les changements qui ne sont pas enregistrés sur la branche courante.
+
+Maintenant que l'état actuel de la branche courante et la branche upstream sont connus, nous pouvons maintenant démarrer une opération de rebase:
+
+```bash
+git rebase upstream/master
+```
+
+Ceci dit à Git d'annuler les commits de la branche courrante puis de les réappliquer sur la branche master de QMK.
+
+```bash
+$ git rebase upstream/master
+First, rewinding head to replay your work on top of it...
+Applying: Commit #1
+Using index info to reconstruct a base tree...
+M       conflicting_file_1.txt
+Falling back to patching base and 3-way merge...
+Auto-merging conflicting_file_1.txt
+CONFLICT (content): Merge conflict in conflicting_file_1.txt
+error: Failed to merge in the changes.
+hint: Use 'git am --show-current-patch' to see the failed patch
+Patch failed at 0001 Commit #1
+
+Resolve all conflicts manually, mark them as resolved with
+"git add/rm <conflicted_files>", then run "git rebase --continue".
+You can instead skip this commit: run "git rebase --skip".
+To abort and get back to the state before "git rebase", run "git rebase --abort".
+```
+
+Ceci nous dit que nous avons un conflit de merge, et nous donne le nom du fichier en conflit. Ouvez le fichier conflictuel dans votre éditeur de texte et, quelque part dans le fichier, vous trouverez quelque chose comme ça:
+
+```bash
+<<<<<<< HEAD
+<p>For help with any issues, email us at support@webhost.us.</p>
+=======
+<p>Need help? Email support@webhost.us.</p>
+>>>>>>> Commit #1
+```
+
+La ligne `<<<<<<< HEAD` montre le début d'un conflit de merge et la ligne `>>>>>>> Commit #1` indique la fin, avec les sections conflictuelles séparées par `=======`. La partie du côté `HEAD` vient de la version du fichier provenant de la branche master de QMK, et la partie marquée avec le numéro du commit provient de la branche courrante.
+
+Parce que Git suis *les changements des fichiers*, plutôt que les contenus des fichiers directement, si Git ne peut pas trouver le texte qu'il y avait dans le fichier avant que le commit soit fait, il ne saura pas comment modifier le fichier. Modifier le fichier à nouveau va résoudre le conflit. Faites votre changement, et sauvez le fichier.
+
+```bash
+<p>Need help? Email support@webhost.us.</p>
+```
+
+Maintenant, lancez:
+
+```bash
+git add conflicting_file_1.txt
+git rebase --continue
+```
+
+Git enregistre le changement dans le fichier conflictuel, et continue à appliquer les commits depuis votre branche jusqu'à ce qu'il arrive à la fin.

docs/fr-FR/newbs_building_firmware.md

@@ -0,0 +1,81 @@
+# Compiler Votre Premier Firmware
+
+Maintenant que vous avez configuré votre environnement de build, vous être prêts à compiler un firmware customisé. Pour cette section, nous allons utiliser trois programmes différents: votre explorateur de fichier, votre éditeur de texte et votre fenêtre de terminal. Gardez les 3 ouverts jusqu'à ce que vous ayez terminé et soyez content de votre firmware de clavier.
+
+Si vous avez fermé et rouvert votre fenêtre de terminal depuis le démarrage de ce guide, n'oubliez pas de `cd qmk_firmware` afin que votre terminal soit dans le bon répertoire.
+
+## Naviguez vers votre répertoire keymaps
+
+Démarrez par naviguer dans le répertoire `keymaps` de votre clavier.
+
+?> Si vous êtes sous macOS ou Windows, il y a des commandes que vous pouvez utiliser pour facilement ouvrir le dossier keymaps.
+
+?> macOS:
+
+    open keyboards/<keyboard_folder>/keymaps
+
+?> Windows:
+
+    start .\\keyboards\\<keyboard_folder>\\keymaps
+
+## Créez une copie de la keymap `default`
+
+Une fois le dossier `keymaps` ouvert, créez une copie du répertoire `default`. Nous vous recommandons de nommer ce répertoire de la même manière que votre nom d'utilisateur GitHub. Vous pouvez aussi utiliser le nom que vous voulez, tant qu'il contient uniquement des lettres minuscules, des nombres et le caractère souligné (_).
+
+Afin d'automatiser ce processus, vous avez aussi l'option de lancer le script `new_keymap.sh`.
+
+Naviguez vers le répertoire `qmk_firmware/util` et tapez ce qui suit:
+
+```
+./new_keymap.sh <keyboard path> <username>
+```
+
+Par exemple, pour un utilisateur s'appeleant John, essayant de créer une nouvelle keymap pour le 1up60hse, il taperait:
+
+```
+./new_keymap.sh 1upkeyboards/1up60hse john
+```
+
+## Ouvrez `keymap.c` dans votre éditeur de texte préféré
+
+Ouvrez votre fichier `keymap.c`. Dans ce fichier, vous trouverez la structure qui contrôle comment votre clavier se comporte. En haut du fichier `keymap.c` il peut y avoir quelques `defines` et `enums` qui rendent la keymap plus simple à lire. Plus bas, vous trouverez une ligne telle que celle-ci:
+
+    const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
+
+Cette ligne indique le début d'une liste de calques (layers). En dessous, vous trouverez des lignes contenant soit `LAYOUT`, soit `KEYMAP` et ces lignes indiquent le début d'un calque. En dessous de cette ligne se trouve la liste des touches qui comprennent ce calque particulier.
+
+!> Lorsque vous éditez votre fichier keymap, faites attention à ne pas ajouter ou enlever une virgule. Si vous le faites, vous aller empêcher votre firmware de compiler et il ne sera pas facile de trouver où la virgule est manquante ou en trop.
+
+## Customisez le layout à votre goût
+
+Libre à vous de choisir comment compléter cette étape. Faites le petit changement qui vous dérange ou retravaillez tout de zéro. Vous pouvez supprimer des calques si vous ne les utilisez pas tous, ou ajouter des calques jusqu'à un maximum de 32. Vérifiez la documentation suivante pour trouver ce que vous pouvez définir ici:
+
+* [Keycodes](keycodes.md)
+* [Fonctionnalités](features.md)
+* [FAQ](faq.md)
+
+?> Lorsque vous découvrez comment des keymaps fonctionnent, faites de petits changements. De gros changements rendent le débuggage des problèmes éventuels plus difficile.
+
+## Compilez votre firmware
+
+Lorsque les changements de votre keymap sont complets, vous allez devoir compiler le firmware. Pour ce faire, retournez à votre terminal et lancez la commande de compilation:
+
+    make <my_keyboard>:<my_keymap>
+
+Par exemple, si votre keymap s'appelle "xyverz" et vous compilez une keymap pour une plank rev5, vous allez utiliser cette commande:
+
+    make planck/rev5:xyverz
+
+Durant la compilation, vous allez avoir beaucoup de messages sur l'écran vous informant de quels fichiers sont en train d'être compilés. Il devrait se terminer avec des messages qui ressemblent comme suit:
+
+```
+Linking: .build/planck_rev5_xyverz.elf                                                              [OK]
+Creating load file for flashing: .build/planck_rev5_xyverz.hex                                      [OK]
+Copying planck_rev5_xyverz.hex to qmk_firmware folder                                               [OK]
+Checking file size of planck_rev5_xyverz.hex                                                        [OK]
+ * File size is fine - 18392/28672
+```
+
+## Flasher votre firmware
+
+Allez sur la page [Flasher le firmware](fr-FR/newbs_flashing.md) pour apprendre comment écrire votre nouveau firmware sur votre clavier.

docs/fr-FR/newbs_building_firmware_configurator.md

@@ -0,0 +1,105 @@
+# Configurateur de QMK
+
+Le [Configurateur de QMK](https://config.qmk.fm) est une interface graphique en ligne permettant de générer des fichiers "hex" du firmware de QMK.
+
+?> **S'il vous plaît, suivez les étapes suivantes dans l'ordre.**
+
+Regardez le [Tutoriel vidéo](https://youtu.be/tx54jkRC9ZY)
+
+Le configurateur de QMK fonctionne mieux avec Chrome et Firefox.
+
+!> **Les fichiers d'autres outils, tels que KLE ou kbfirmware ne seront pas compatibles avec le configurateur QMK. Ne les chargez pas, ne les importez pas. Le configurateur QMK est un outil DIFFERENT.**
+
+## Sélectionner votre clavier
+
+Cliquez la boîte déroulante et sélectionnez le clavier pour lequel vous voulez créer une keymap.
+
+?> Si votre clavier a plusieurs versions, faites attention à utiliser la bonne.
+
+Je vais le répéter, parce que c'est important
+
+!> **FAITES ATTENTION A UTILISER LA BONNE VERSION !**
+
+Si votre clavier est annoncé comme fonctionnant grâce à QMK mais n'est pas dans la liste, il y a des chances que le développeur ne l'ait pas encore fait, ou que nous n'avons pas encore eu le temps de le merger. Ajoutez un problème (issue) sur [qmk_firmware](https://github.com/qmk/qmk_firmware/issues) demandant le support de votre clavier, s'il n'y a pas de [Pull Request](https://github.com/qmk/qmk_firmware/pulls?q=is%3Aopen+is%3Apr+label%3Akeyboard) ouvert pour lui. Il y a aussi des clavier alimentés par QMK qui sont sur le compte GitHub du fabriquant, il est bon de le vérifier aussi.
+
+## Sélectionner la disposition de votre clavier
+
+Choisissez la disposition (layout) qui représente le mieux la keymap que vous voulez créer. Certains clavier n'ont pas encore assez de dispositions ou des dispositions incorrectes. Ils seront supportés dans le future.
+
+## Nom de la Keymap
+
+Appelez cette keymap comme vous voulez.
+
+?> Si vous rencontrez des problèmes lors de la compilation, il peut être utile de changer ce nom, il peut déjà exister dans le dépôt du firmware QMK.
+
+## Créer votre keymap
+
+Entrer un keycode peut s'accomplir de 3 façons différentes.
+
+1. Glisser déposer
+2. Cliquer sur un endroit vide sur le layout et cliquer sur le keycode souhaité
+3. Cliquer sur un endroit vide sur le layout et appuyer sur une touche physique de votre clavier.
+
+Passez votre souris au dessus d'une touche et un affichage vous dira quel est le rôle du keycode. Pour une version plus verbeuse suivre:
+
+[Référence Keycode basique](https://docs.qmk.fm/#/keycodes_basic)
+[Référence Keycode avancé](https://docs.qmk.fm/#/feature_advanced_keycodes)
+
+Dans le cas où vous ne trouvez pas une disposition qui supporte votre keymap, par exemple trois places pour une barre d'espace, ou deux places pour retour clavier, ou deux places pour shift, etc. etc. remplissez les TOUTES.
+
+### Exemples
+
+3 places pour la barre d'espace: Remplissez les TOUTES avec la barre d'espace
+
+2 places pour un retour clavier: Remplissez les DEUX avec un retour clavier
+
+2 places pour un shift droit: Remplissez les DEUX avec un shift droit
+
+1 place pour un shift gauche et 1 place pour le support ISO: Remplissez les deux avec un shift gauche
+
+5 places, mais seulement 4 touches: Deviner et vérifier, ou demander à quelqu'un qui l'a déjà fait.
+
+## Sauvez votre keymap pour des éditions futures
+
+Une fois satisfait de votre keymap, ou si vous souhaitez revenir travailler dessus plus tard, appuyez sur le bouton `Export Keymap`. Il vous permettra de sauvegarder votre keymap avec le nom choisi au dessus suivi de .json.
+
+Vous pouvez ensuite charger ce fichier .json à nouveau en appuxant sur le bouton `Import Keymap`.
+
+!> **ATTENTION** Ce n'est pas le même type de fichier .json utilisé pour kbfirmware.com ou n'importe quel autre outil. Si vous essayez d'utiliser ce fichier pour d'autres outil, ou le fichier .json d'autres outils avec le configurateur QMK, il y a des chances que votre clavier **explose**.
+
+## Générer votre fichier firmware
+
+Appuyez sur le bouton `Compile`.
+
+Une fois la compilation terminée, vous pourrez appuyer sur le bouton vert `Download Firmware`.
+
+## Ecrire votre firmware sur votre clavier
+
+Merci de vous référer à [Flasher le Firmware](fr-FR/newbs_flashing.md)
+
+## Dépannage
+
+#### Mon fichier json ne fonctionne pas
+
+Si le fichier .json a été généré par le configurateur QMK, bravo vous avez trouvé un bug. Merci d'ouvrir une issue sur [qmk_configurator](https://github.com/qmk/qmk_configurator/issues)
+
+Sinon... vous avez raté mon message écris en gras qui dit de ne pas utiliser d'autres fichiers .json?
+
+#### Il y a des espaces en trop dans mon alyout? Qu'est-ce que je fais?
+
+Si vous voulez dire que vous avez trois places pour une barre d'espace, le mieux est de les remplir tous avec une barre d'espace. Vous pouvez faire de même avec les retour clavier et les shift.
+
+#### C'est quoi le keycode pour .......
+
+Merci de regarder
+
+[Référence keycode basique](https://docs.qmk.fm/#/keycodes_basic)
+[Référence keycode avancé](https://docs.qmk.fm/#/feature_advanced_keycodes)
+
+#### Ca ne compile pas?
+
+Merci de vérifier les autres dispositions de votre keymap afin d'être sûr qu'il n'y a pas de touches aléatoires.
+
+## Problèmes et Bugs
+
+Nous acceptons toujours les demandes des clients et les rapports de bugs. Merci de les remplirs sur [qmk_configurator](https://github.com/qmk/qmk_configurator/issues)