Add samuel's literate keymap file for planck (#4998)

* added my own keymap

* changed thing

* updated keymap Samuel

* updated laypout for better one handed use

* updated stuff I want

* happy with my lagout

* formatting

* Added new literate config

* made everything nice

* cleaned

* fixed spelling and two small bugs in macros

* Made press and lift function for modifiers

.editorconfig

@@ -8,7 +8,6 @@ indent_style = space
 indent_size = 2
 
 # We recommend you to keep these unchanged
-end_of_line = lf
 charset = utf-8
 trim_trailing_whitespace = true
 insert_final_newline = true
@@ -16,3 +15,22 @@ insert_final_newline = true
 [*.md]
 trim_trailing_whitespace = false
 indent_size = 4
+
+# Make these match what we have in .gitattributes
+[*.mk]
+end_of_line = lf
+
+[Makefile]
+end_of_line = lf
+
+[*.sh]
+end_of_line = lf
+
+# The gitattributes file will handle the line endings conversion properly according to the operating system settings for other files
+
+
+# We don't have gitattributes properly for these
+# So if the user have for example core.autocrlf set to true
+# the line endings would be wrong.
+[lib/**]
+end_of_line = unset

.github/ISSUE_TEMPLATE/blank.md

@@ -0,0 +1,5 @@
+---
+name: Blank issue
+about: If you're 100% sure that you don't need one of the other issue templates, use this one instead. 
+
+---

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,32 @@
+---
+name: Bug report
+about: Create a report to help us improve the QMK Firmware
+---
+<!-- Provide a general summary of the bug 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. -->
+
+## Describe the Bug
+
+<!-- A clear and concise description of what the bug is. -->
+
+## System Information
+
+ - Keyboard:  
+   - Revision (if applicable):  
+ - Operating system:
+ - AVR GCC version: 
+<!-- Run `avr-gcc --version` to find this out. -->
+ - ARM GCC version: 
+<!-- Run `arm-none-eabi-gcc --version` to find this out. -->
+ - QMK Firmware version:
+<!-- Run `git describe --abbrev=0 --tags` to find this out. -->
+ - Any keyboard related software installed? 
+   - [ ] AutoHotKey
+   - [ ] Karabiner
+   - [ ] Other:
+
+## Additional Context
+
+<!-- Add any other relevant information about the problem here. -->

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,19 @@
+---
+name: Feature request
+about: Suggest a new feature or changes to existing features 
+---
+<!--- Provide a general summary of the changes you want 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. -->
+
+## Feature Request Type
+
+- [ ] Core functionality
+- [ ] Add-on hardware support (eg. audio, RGB, OLED screen, etc.)
+- [ ] Alteration (enhancement/optimization) of existing feature(s)
+- [ ] New behavior
+
+## Description
+
+<!-- A few sentences describing what it is that you'd like to see in QMK. Additional information (such as links to spec sheets, licensing info, other related issues or PRs, etc) would be helpful. -->

.github/ISSUE_TEMPLATE/other_issues.md

@@ -0,0 +1,9 @@
+---
+name: Other issues
+about: Anything else that doesn't fall into the above categories. 
+---
+<!--- Provide a general summary of the changes you want in the title above. -->
+
+<!--- Anything on lines wrapped in comments like these will not show up in the final text. -->
+
+<!-- Please check https://docs.qmk.fm/#/support for additional resources first. If that doesn't answer your question, choose the bug report template instead, as that may be more appropriate. -->

.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

@@ -1,3 +1,4 @@
+.history/
 .dep
 *.o
 *.bin
@@ -23,6 +24,7 @@ quantum/version.h
 .idea/
 CMakeLists.txt
 cmake-build-debug
+doxygen/
 .DS_STORE
 /util/wsl_downloaded
 /util/win_downloaded
@@ -42,6 +44,7 @@ cmake-build-debug
 .project
 .settings/
 .idea
+*.iml
 .browse.VC.db*
 *.stackdump
 util/Win_Check_Output.txt
@@ -52,6 +55,7 @@ util/Win_Check_Output.txt
 .vscode/last.sql
 .vscode/temp.sql
 .stfolder
+.tags
 
 # ignore image files
 *.png

.travis.yml

@@ -11,15 +11,18 @@ env:
   global:
   - secure: vBTSL34BDPxDilKUuTXqU4CJ26Pv5hogD2nghatkxSQkI1/jbdnLj/DQdPUrMJFDIY6TK3AltsBx72MaMsLQ1JO/Ou24IeHINHXzUC1FlS9yQa48cpxnhX5kzXNyGs3oa0qaFbvnr7RgYRWtmD52n4bIZuSuW+xpBv05x2OCizdT2ZonH33nATaHGFasxROm4qYZ241VfzcUv766V6RVHgL4x9V08warugs+RENVkfzxxwhk3NmkrISabze0gSVJLHBPHxroZC6EUcf/ocobcuDrCwFqtEt90i7pNIAFUE7gZsN2uE75LmpzAWin21G7lLPcPL2k4FJVd8an1HiP2WmscJU6U89fOfMb2viObnKcCzebozBCmKGtHEuXZo9FcReOx49AnQSpmESJGs+q2dL/FApkTjQiyT4J6O5dJpoww0/r57Wx0cmmqjETKBb5rSgXM51Etk3wO09mvcPHsEwrT7qH8r9XWdyCDoEn7FCLX3/LYnf/D4SmZ633YPl5gv3v9XEwxR5+04akjgnvWDSNIaDbWBdxHNb7l4pMc+WR1bwCyMyA7KXj0RrftEGOrm9ZRLe6BkbT4cycA+j77nbPOMcyZChliV9pPQos+4TOJoTzcK2L8yWVoY409aDNVuAjdP6Yum0R2maBGl/etLmIMpJC35C5/lZ+dUNjJAM=
 before_install:
-  - wget http://www.atmel.com/images/avr8-gnu-toolchain-3.5.4.1709-linux.any.x86_64.tar.gz || wget http://qmk.fm/avr8-gnu-toolchain-3.5.4.1709-linux.any.x86_64.tar.gz
+  - wget http://ww1.microchip.com/downloads/en/DeviceDoc/avr8-gnu-toolchain-3.5.4.1709-linux.any.x86_64.tar.gz || wget http://qmk.fm/avr8-gnu-toolchain-3.5.4.1709-linux.any.x86_64.tar.gz
 install:
   - tar -zxf avr8-gnu-toolchain-3.5.4.1709-linux.any.x86_64.tar.gz
   - export PATH="$PATH:$TRAVIS_BUILD_DIR/avr8-gnu-toolchain-linux_x86_64/bin"
+  - npm install -g moxygen
 before_script:
   - avr-gcc --version
 script:
-- make test:all AUTOGEN=false
+- git rev-parse --short HEAD
+- make test:all
 - bash util/travis_build.sh
+- bash util/travis_docs.sh
 addons:
   apt:
     packages:
@@ -30,7 +33,8 @@ addons:
     - libnewlib-arm-none-eabi
     - diffutils
     - dos2unix
-after_success: 
+    - doxygen
+after_success:
   bash util/travis_compiled_push.sh
 notifications:
   webhooks:
@@ -38,4 +42,4 @@ notifications:
       - 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
+    on_start: never     # options: [always|never|change] default: always

.vscode/settings.json

@@ -11,6 +11,7 @@
         "*.h": "c",
         "*.c": "c",
         "*.cpp": "cpp",
-        "*.hpp": "cpp"
+        "*.hpp": "cpp",
+        "xstddef": "c"
     }
-}
+}

CODE_OF_CONDUCT.md

@@ -1,10 +1,10 @@
 # Code Of Conduct
 
-QMK strives to be an inclusive and tolerant community. We welcome participation from anyone regardless of age, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, political belief, race, religion, or sexual identity and orientation. 
+QMK strives to be an inclusive, tolerant, and welcoming community. We encourage participation from anyone regardless of age, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, political belief, race, religion, or sexual identity and orientation.
 
-> “A gentle word turns away wrath, but a harsh word stirs up anger.”
+> “A gentle word turns away wrath, but a harsh word stirs up anger."
 
-Our users, contributors, and collaborators are expected to treat each other with respect, to assume good intentions, and to gently correct, where possible, rather than react with escalation. Some examples of behavior we will not tolerate include, but is not limited to:
+Our users, contributors, and collaborators are expected to treat each other with kindness and respect, to assume good intentions, and to gently correct, where possible, rather than react with escalation. While our goal is to be as accurate as possible, kindness and understanding are more valuable than correctness. Some examples of behavior we will not tolerate include, but is not limited to:
 
 * The use of sexualized language or imagery
 * Unwelcome advances, sexual or otherwise

Dockerfile

@@ -1,28 +1,29 @@
-FROM debian:jessie
-MAINTAINER Erik Dasque <erik@frenchguys.com>
+FROM debian
 
-RUN apt-get update && apt-get install --no-install-recommends -y build-essential \
+RUN apt-get update && apt-get install --no-install-recommends -y \
+    avr-libc \
+    avrdude \
+    binutils-arm-none-eabi \
+    binutils-avr \
+    build-essential \
+    dfu-programmer \
+    dfu-util \
     gcc \
+    gcc-arm-none-eabi \
+    gcc-avr \
+    git \
+    libnewlib-arm-none-eabi \
+    software-properties-common \
     unzip \
     wget \
     zip \
-    gcc-avr \
-    binutils-avr \
-    avr-libc \
-    dfu-programmer \
-    dfu-util \
-    gcc-arm-none-eabi \
-    binutils-arm-none-eabi \
-    libnewlib-arm-none-eabi \
-    git \
-    software-properties-common \
-    avrdude \
     && rm -rf /var/lib/apt/lists/*
 
-ENV keyboard=ergodox
-ENV subproject=ez
-ENV keymap=default
+ENV KEYBOARD=ergodox_ez
+ENV KEYMAP=default
 
-VOLUME /qmk
-WORKDIR /qmk
-CMD make clean ; make keyboard=${keyboard} subproject=${subproject} keymap=${keymap}
+VOLUME /qmk_firmware
+WORKDIR /qmk_firmware
+COPY . .
+
+CMD make $KEYBOARD:$KEYMAP

Doxyfile

@@ -0,0 +1,266 @@
+# Doxyfile 1.8.14
+
+# This file describes the settings to be used by the documentation system
+# doxygen (www.doxygen.org) for qmk_firmware (github.com/qmk/qmk_firmware)
+#
+# All text after a double hash (##) is considered a comment and is placed in
+# front of the TAG it is preceding.
+#
+# All text after a single hash (#) is considered a comment and will be ignored.
+# The format is:
+# TAG = value [value, ...]
+# For lists, items can also be appended using:
+# TAG += value [value, ...]
+# Values that contain spaces should be placed between quotes (\" \").
+
+#---------------------------------------------------------------------------
+# Project related configuration options
+#---------------------------------------------------------------------------
+
+DOXYFILE_ENCODING      = UTF-8
+PROJECT_NAME           = "QMK Firmware"
+PROJECT_NUMBER         = https://github.com/qmk/qmk_firmware
+PROJECT_BRIEF          = "Keyboard controller firmware for Atmel AVR and ARM USB families"
+OUTPUT_DIRECTORY       = doxygen
+ALLOW_UNICODE_NAMES    = NO
+OUTPUT_LANGUAGE        = English
+BRIEF_MEMBER_DESC      = YES
+REPEAT_BRIEF           = YES
+ABBREVIATE_BRIEF       = "The $name class" \
+                         "The $name widget" \
+                         "The $name file" \
+                         is \
+                         provides \
+                         specifies \
+                         contains \
+                         represents \
+                         a \
+                         an \
+                         the
+ALWAYS_DETAILED_SEC    = NO
+INLINE_INHERITED_MEMB  = NO
+FULL_PATH_NAMES        = YES
+STRIP_FROM_PATH        = 
+STRIP_FROM_INC_PATH    = 
+SHORT_NAMES            = NO
+JAVADOC_AUTOBRIEF      = NO
+QT_AUTOBRIEF           = NO
+MULTILINE_CPP_IS_BRIEF = NO
+INHERIT_DOCS           = YES
+SEPARATE_MEMBER_PAGES  = NO
+TAB_SIZE               = 4
+ALIASES                = 
+TCL_SUBST              = 
+OPTIMIZE_OUTPUT_FOR_C  = YES
+OPTIMIZE_OUTPUT_JAVA   = NO
+OPTIMIZE_FOR_FORTRAN   = NO
+OPTIMIZE_OUTPUT_VHDL   = NO
+EXTENSION_MAPPING      = 
+MARKDOWN_SUPPORT       = YES
+TOC_INCLUDE_HEADINGS   = 2
+AUTOLINK_SUPPORT       = YES
+BUILTIN_STL_SUPPORT    = NO
+CPP_CLI_SUPPORT        = NO
+SIP_SUPPORT            = NO
+IDL_PROPERTY_SUPPORT   = YES
+DISTRIBUTE_GROUP_DOC   = NO
+GROUP_NESTED_COMPOUNDS = NO
+SUBGROUPING            = YES
+INLINE_GROUPED_CLASSES = NO
+INLINE_SIMPLE_STRUCTS  = NO
+TYPEDEF_HIDES_STRUCT   = NO
+LOOKUP_CACHE_SIZE      = 0
+
+#---------------------------------------------------------------------------
+# Build related configuration options
+#---------------------------------------------------------------------------
+
+EXTRACT_ALL            = NO
+EXTRACT_PRIVATE        = NO
+EXTRACT_PACKAGE        = NO
+EXTRACT_STATIC         = NO
+EXTRACT_LOCAL_CLASSES  = YES
+EXTRACT_LOCAL_METHODS  = NO
+EXTRACT_ANON_NSPACES   = NO
+HIDE_UNDOC_MEMBERS     = NO
+HIDE_UNDOC_CLASSES     = NO
+HIDE_FRIEND_COMPOUNDS  = NO
+HIDE_IN_BODY_DOCS      = NO
+INTERNAL_DOCS          = NO
+CASE_SENSE_NAMES       = NO
+HIDE_SCOPE_NAMES       = YES
+HIDE_COMPOUND_REFERENCE= NO
+SHOW_INCLUDE_FILES     = YES
+SHOW_GROUPED_MEMB_INC  = NO
+FORCE_LOCAL_INCLUDES   = NO
+INLINE_INFO            = YES
+SORT_MEMBER_DOCS       = YES
+SORT_BRIEF_DOCS        = NO
+SORT_MEMBERS_CTORS_1ST = NO
+SORT_GROUP_NAMES       = NO
+SORT_BY_SCOPE_NAME     = NO
+STRICT_PROTO_MATCHING  = NO
+GENERATE_TODOLIST      = YES
+GENERATE_TESTLIST      = YES
+GENERATE_BUGLIST       = YES
+GENERATE_DEPRECATEDLIST= YES
+ENABLED_SECTIONS       = 
+MAX_INITIALIZER_LINES  = 30
+SHOW_USED_FILES        = YES
+SHOW_FILES             = YES
+SHOW_NAMESPACES        = YES
+FILE_VERSION_FILTER    = 
+LAYOUT_FILE            = 
+CITE_BIB_FILES         = 
+
+#---------------------------------------------------------------------------
+# Configuration options related to warning and progress messages
+#---------------------------------------------------------------------------
+
+QUIET                  = NO
+WARNINGS               = YES
+WARN_IF_UNDOCUMENTED   = YES
+WARN_IF_DOC_ERROR      = YES
+WARN_NO_PARAMDOC       = NO
+WARN_AS_ERROR          = NO
+WARN_FORMAT            = "$file:$line: $text"
+WARN_LOGFILE           = 
+
+#---------------------------------------------------------------------------
+# Configuration options related to the input files
+#---------------------------------------------------------------------------
+
+INPUT                  = tmk_core quantum drivers
+INPUT_ENCODING         = UTF-8
+FILE_PATTERNS          = *.c \
+                         *.cc \
+                         *.cxx \
+                         *.cpp \
+                         *.c++ \
+                         *.h \
+                         *.hh \
+                         *.hxx \
+                         *.hpp \
+                         *.h++
+RECURSIVE              = YES
+EXCLUDE                = 
+EXCLUDE_SYMLINKS       = NO
+EXCLUDE_PATTERNS       = 
+EXCLUDE_SYMBOLS        = 
+EXAMPLE_PATH           = 
+EXAMPLE_PATTERNS       = *
+EXAMPLE_RECURSIVE      = NO
+IMAGE_PATH             = 
+INPUT_FILTER           = 
+FILTER_PATTERNS        = 
+FILTER_SOURCE_FILES    = NO
+FILTER_SOURCE_PATTERNS = 
+USE_MDFILE_AS_MAINPAGE = 
+
+#---------------------------------------------------------------------------
+# Configuration options related to source browsing
+#---------------------------------------------------------------------------
+
+SOURCE_BROWSER         = YES
+INLINE_SOURCES         = NO
+STRIP_CODE_COMMENTS    = YES
+REFERENCED_BY_RELATION = NO
+REFERENCES_RELATION    = NO
+REFERENCES_LINK_SOURCE = YES
+SOURCE_TOOLTIPS        = YES
+USE_HTAGS              = NO
+VERBATIM_HEADERS       = YES
+
+#---------------------------------------------------------------------------
+# Configuration options related to the alphabetical class index
+#---------------------------------------------------------------------------
+
+ALPHABETICAL_INDEX     = YES
+COLS_IN_ALPHA_INDEX    = 5
+IGNORE_PREFIX          = 
+
+#---------------------------------------------------------------------------
+# Configuration options related to disabled outputs
+#---------------------------------------------------------------------------
+
+GENERATE_HTML          = NO
+GENERATE_LATEX         = NO
+GENERATE_RTF           = NO
+GENERATE_MAN           = NO
+GENERATE_DOCBOOK       = NO
+GENERATE_AUTOGEN_DEF   = NO
+GENERATE_PERLMOD       = NO
+
+#---------------------------------------------------------------------------
+# Configuration options related to the XML output
+#---------------------------------------------------------------------------
+
+GENERATE_XML           = YES
+XML_OUTPUT             = xml
+XML_PROGRAMLISTING     = YES
+
+#---------------------------------------------------------------------------
+# Configuration options related to the preprocessor
+#---------------------------------------------------------------------------
+
+ENABLE_PREPROCESSING   = YES
+MACRO_EXPANSION        = NO
+EXPAND_ONLY_PREDEF     = NO
+SEARCH_INCLUDES        = YES
+INCLUDE_PATH           = 
+INCLUDE_FILE_PATTERNS  = 
+PREDEFINED             = 
+EXPAND_AS_DEFINED      = 
+SKIP_FUNCTION_MACROS   = YES
+
+#---------------------------------------------------------------------------
+# Configuration options related to external references
+#---------------------------------------------------------------------------
+
+TAGFILES               = 
+GENERATE_TAGFILE       = 
+ALLEXTERNALS           = NO
+EXTERNAL_GROUPS        = YES
+EXTERNAL_PAGES         = YES
+PERL_PATH              = /usr/bin/perl
+
+#---------------------------------------------------------------------------
+# Configuration options related to the dot tool
+#---------------------------------------------------------------------------
+
+CLASS_DIAGRAMS         = YES
+MSCGEN_PATH            = 
+DIA_PATH               = 
+HIDE_UNDOC_RELATIONS   = YES
+HAVE_DOT               = NO
+DOT_NUM_THREADS        = 0
+DOT_FONTNAME           = Helvetica
+DOT_FONTSIZE           = 10
+DOT_FONTPATH           = 
+CLASS_GRAPH            = YES
+COLLABORATION_GRAPH    = YES
+GROUP_GRAPHS           = YES
+UML_LOOK               = NO
+UML_LIMIT_NUM_FIELDS   = 10
+TEMPLATE_RELATIONS     = NO
+INCLUDE_GRAPH          = YES
+INCLUDED_BY_GRAPH      = YES
+CALL_GRAPH             = NO
+CALLER_GRAPH           = NO
+GRAPHICAL_HIERARCHY    = YES
+DIRECTORY_GRAPH        = YES
+DOT_IMAGE_FORMAT       = png
+INTERACTIVE_SVG        = NO
+DOT_PATH               = 
+DOTFILE_DIRS           = 
+MSCFILE_DIRS           = 
+DIAFILE_DIRS           = 
+PLANTUML_JAR_PATH      = 
+PLANTUML_CFG_FILE      = 
+PLANTUML_INCLUDE_PATH  = 
+DOT_GRAPH_MAX_NODES    = 50
+MAX_DOT_GRAPH_DEPTH    = 0
+DOT_TRANSPARENT        = NO
+DOT_MULTI_TARGETS      = NO
+GENERATE_LEGEND        = YES
+DOT_CLEANUP            = YES

Makefile

@@ -67,7 +67,7 @@ $(eval $(call NEXT_PATH_ELEMENT))
 # It's really a very simple if else chain, if you squint enough,
 # but the makefile syntax makes it very verbose.
 # If we are in a subfolder of keyboards
-# 
+#
 # *** No longer needed **
 #
 # ifeq ($(CURRENT_PATH_ELEMENT),keyboards)
@@ -112,17 +112,29 @@ $(eval $(call GET_KEYBOARDS))
 # Only consider folders with makefiles, to prevent errors in case there are extra folders
 #KEYBOARDS += $(patsubst $(ROOD_DIR)/keyboards/%/rules.mk,%,$(wildcard $(ROOT_DIR)/keyboards/*/*/rules.mk))
 
+.PHONY: list-keyboards
 list-keyboards:
 	echo $(KEYBOARDS)
-	exit 0
 
 define PRINT_KEYBOARD
 	$(info $(PRINTING_KEYBOARD))
 endef
 
+.PHONY: generate-keyboards-file
 generate-keyboards-file:
 	$(foreach PRINTING_KEYBOARD,$(KEYBOARDS),$(eval $(call PRINT_KEYBOARD)))
-	exit 0
+
+.PHONY: clean
+clean:
+	echo -n 'Deleting .build/ ... '
+	rm -rf $(BUILD_DIR)
+	echo 'done.'
+
+.PHONY: distclean
+distclean: clean
+	echo -n 'Deleting *.bin and *.hex ... '
+	rm -f *.bin *.hex
+	echo 'done.'
 
 #Compatibility with the old make variables, anything you specify directly on the command line
 # always overrides the detected folders
@@ -301,11 +313,6 @@ define PARSE_KEYBOARD
     KEYBOARD_FOLDER_PATH_3 := $$(patsubst %/,%,$$(dir $$(KEYBOARD_FOLDER_PATH_2)))
     KEYBOARD_FOLDER_PATH_4 := $$(patsubst %/,%,$$(dir $$(KEYBOARD_FOLDER_PATH_3)))
     KEYBOARD_FOLDER_PATH_5 := $$(patsubst %/,%,$$(dir $$(KEYBOARD_FOLDER_PATH_4)))
-    KEYBOARD_FOLDER_1 := $$(notdir $$(KEYBOARD_FOLDER_PATH_1))
-    KEYBOARD_FOLDER_2 := $$(notdir $$(KEYBOARD_FOLDER_PATH_2))
-    KEYBOARD_FOLDER_3 := $$(notdir $$(KEYBOARD_FOLDER_PATH_3))
-    KEYBOARD_FOLDER_4 := $$(notdir $$(KEYBOARD_FOLDER_PATH_4))
-    KEYBOARD_FOLDER_5 := $$(notdir $$(KEYBOARD_FOLDER_PATH_5))
 
     KEYMAPS :=
     # get a list of all keymaps
@@ -319,35 +326,35 @@ define PARSE_KEYBOARD
         $$(KEYBOARD_FOLDER_3) $$(KEYBOARD_FOLDER_4) $$(KEYBOARD_FOLDER_5), $$(KEYMAPS)))
 
     KEYBOARD_LAYOUTS :=
-    ifneq ("$$(wildcard $(ROOT_DIR)/keyboards/$$(KEYBOARD_FOLDER_5)/rules.mk)","")
+    ifneq ("$$(wildcard $(ROOT_DIR)/keyboards/$$(KEYBOARD_FOLDER_PATH_5)/rules.mk)","")
       LAYOUTS :=
-      $$(eval include $(ROOT_DIR)/keyboards/$$(KEYBOARD_FOLDER_5)/rules.mk)
+      $$(eval include $(ROOT_DIR)/keyboards/$$(KEYBOARD_FOLDER_PATH_5)/rules.mk)
       KEYBOARD_LAYOUTS := $$(sort $$(LAYOUTS) $$(KEYBOARD_LAYOUTS))
     endif
-    ifneq ("$$(wildcard $(ROOT_DIR)/keyboards/$$(KEYBOARD_FOLDER_4)/rules.mk)","")
+    ifneq ("$$(wildcard $(ROOT_DIR)/keyboards/$$(KEYBOARD_FOLDER_PATH_4)/rules.mk)","")
       LAYOUTS :=
-      $$(eval include $(ROOT_DIR)/keyboards/$$(KEYBOARD_FOLDER_4)/rules.mk)
+      $$(eval include $(ROOT_DIR)/keyboards/$$(KEYBOARD_FOLDER_PATH_4)/rules.mk)
       KEYBOARD_LAYOUTS := $$(sort $$(LAYOUTS) $$(KEYBOARD_LAYOUTS))
     endif
-    ifneq ("$$(wildcard $(ROOT_DIR)/keyboards/$$(KEYBOARD_FOLDER_3)/rules.mk)","")
+    ifneq ("$$(wildcard $(ROOT_DIR)/keyboards/$$(KEYBOARD_FOLDER_PATH_3)/rules.mk)","")
       LAYOUTS :=
-      $$(eval include $(ROOT_DIR)/keyboards/$$(KEYBOARD_FOLDER_3)/rules.mk)
+      $$(eval include $(ROOT_DIR)/keyboards/$$(KEYBOARD_FOLDER_PATH_3)/rules.mk)
       KEYBOARD_LAYOUTS := $$(sort $$(LAYOUTS) $$(KEYBOARD_LAYOUTS))
     endif
-    ifneq ("$$(wildcard $(ROOT_DIR)/keyboards/$$(KEYBOARD_FOLDER_2)/rules.mk)","")
+    ifneq ("$$(wildcard $(ROOT_DIR)/keyboards/$$(KEYBOARD_FOLDER_PATH_2)/rules.mk)","")
       LAYOUTS :=
-      $$(eval include $(ROOT_DIR)/keyboards/$$(KEYBOARD_FOLDER_2)/rules.mk)
+      $$(eval include $(ROOT_DIR)/keyboards/$$(KEYBOARD_FOLDER_PATH_2)/rules.mk)
       KEYBOARD_LAYOUTS := $$(sort $$(LAYOUTS) $$(KEYBOARD_LAYOUTS))
     endif
-    ifneq ("$$(wildcard $(ROOT_DIR)/keyboards/$$(KEYBOARD_FOLDER_1)/rules.mk)","")
+    ifneq ("$$(wildcard $(ROOT_DIR)/keyboards/$$(KEYBOARD_FOLDER_PATH_1)/rules.mk)","")
       LAYOUTS :=
-      $$(eval include $(ROOT_DIR)/keyboards/$$(KEYBOARD_FOLDER_1)/rules.mk)
+      $$(eval include $(ROOT_DIR)/keyboards/$$(KEYBOARD_FOLDER_PATH_1)/rules.mk)
       KEYBOARD_LAYOUTS := $$(sort $$(LAYOUTS) $$(KEYBOARD_LAYOUTS))
     endif
 
     LAYOUT_KEYMAPS :=
     $$(foreach LAYOUT,$$(KEYBOARD_LAYOUTS),$$(eval LAYOUT_KEYMAPS += $$(notdir $$(patsubst %/.,%,$$(wildcard $(ROOT_DIR)/layouts/*/$$(LAYOUT)/*/.)))))
-    
+
     KEYMAPS := $$(sort $$(KEYMAPS) $$(LAYOUT_KEYMAPS))
 
     # if the rule after removing the start of it is empty (we haven't specified a kemap or target)
@@ -547,9 +554,10 @@ endif
 	# it has to be there to allow parallel execution of the submake
 	# This always tries to compile everything, even if error occurs in the middle
 	# But we return the error code at the end, to trigger travis failures
-	$(foreach COMMAND,$(COMMANDS),$(RUN_COMMAND))
+	# The sort at this point is to remove duplicates
+	$(foreach COMMAND,$(sort $(COMMANDS)),$(RUN_COMMAND))
 	if [ -f $(ERROR_FILE) ]; then printf "$(MSG_ERRORS)" & exit 1; fi;
-	$(foreach TEST,$(TESTS),$(RUN_TEST))
+	$(foreach TEST,$(sort $(TESTS)),$(RUN_TEST))
 	if [ -f $(ERROR_FILE) ]; then printf "$(MSG_ERRORS)" & exit 1; fi;
 
 # These no longer work because of the colon system
@@ -575,9 +583,10 @@ lib/%:
 	git submodule sync $?
 	git submodule update --init $?
 
+.PHONY: git-submodule
 git-submodule:
 	git submodule sync --recursive
-	git submodule update --init --recursive
+	git submodule update --init --recursive --progress
 
 ifdef SKIP_VERSION
 SKIP_GIT := yes

Vagrantfile

@@ -2,27 +2,11 @@
 # vi: set ft=ruby :
 
 Vagrant.configure(2) do |config|
-  # You can only have one config.vm.box uncommented at a time
+  # define a name instead of just 'default'
+  config.vm.define "qmk_firmware"
 
-  # Comment this and uncomment another if you don't want to use the minimal Arch box
-  #config.vm.box = "dragon788/arch-ala-elasticdog"
-
-  # VMware/Virtualbox 64 bit
-  config.vm.box = "phusion/ubuntu-14.04-amd64"
-  #
-  # VMware/Virtualbox 64 bit
-  #config.vm.box = "puphpet/centos65-x64"
-  #
-  # The opensuse boxes don't have dfu-util in their default repositories
-  #
-  # The virtualbox version has tools issues
-  # VMware/Virtualbox 64 bit
-  #config.vm.box = "bento/opensuse-13.2-x86_64"
-  #
-  # Virtualbox only
-  #config.vm.box = "bento/opensuse-13.2-i386"
-  # config.vm.box = ""
-  # config.vm.box = ""
+  # VMware/Virtualbox ( and also Hyperv/Parallels) 64 bit
+  config.vm.box = "bento/ubuntu-16.04"
 
   # This section allows you to customize the Virtualbox VM
   # settings, ie showing the GUI or upping the memory
@@ -34,13 +18,16 @@ Vagrant.configure(2) do |config|
     # your Teensy via the VM rather than your host OS
     #vb.customize ['modifyvm', :id, '--usb', 'on']
     #vb.customize ['usbfilter', 'add', '0',
-    #    	  '--target', :id,
-    #    	  '--name', 'teensy',
-    #    	  '--vendorid', '0x16c0',
-    #    	  '--productid','0x0478'
-    #		 ]
+    #         '--target', :id,
+    #         '--name', 'teensy',
+    #         '--vendorid', '0x16c0',
+    #         '--productid','0x0478'
+    #        ]
     # Customize the amount of memory on the VM:
     vb.memory = "512"
+    # Uncomment the below lines if you have time sync
+    # issues with make and incremental builds
+    #vb.customize [ "guestproperty", "set", :id, "/VirtualBox/GuestAdd/VBoxService/--timesync-set-threshold", 1000 ]
   end
 
   # This section allows you to customize the VMware VM
@@ -75,24 +62,21 @@ Vagrant.configure(2) do |config|
   # This script ensures the required packages for AVR programming are installed
   # It also ensures the system always gets the latest updates when powered on
   # If this causes issues you can run a 'vagrant destroy' and then
-  # add a # before ,args: and run 'vagrant up' to get a working
+  # add a # before ,run: (or change "always" to "once") and run 'vagrant up' to get a working
   # non-updated box and then attempt to troubleshoot or open a Github issue
-
-  config.vm.provision "shell", run: "always", path: "./util/install_dependencies.sh", args: "-update"
+  config.vm.provision "shell", inline: "/bin/sh -c 'yes | /vagrant/util/qmk_install.sh'", run: "always"
 
   config.vm.post_up_message = <<-EOT
-  Log into the VM using 'vagrant ssh' on OSX or from Git Bash (Win)
-  or 'vagrant ssh-config' and Putty or Bitvise SSH or another SSH tool
 
-  Change directory (cd) to the keyboard you wish to program
-  (Optionally) modify your layout,
-  then run 'make clean'
-  and then 'make' to compile the .eep and .hex files.
-
-  Or you can copy and paste the example line below.
-
-  cd /vagrant; cd keyboards; cd ergodox; make clean; make
+  Log into the VM using 'vagrant ssh'. QMK directory synchronized with host is
+  located at /vagrant
+  To compile the .hex files use make command inside this directory, e.g.
+     cd /vagrant
+     make <keyboard>:default
 
+  Examples:
+     make planck/rev4:default:dfu
+     make planck:default
 
   EOT
 end

bootloader.mk

@@ -32,21 +32,41 @@
 ifeq ($(strip $(BOOTLOADER)), atmel-dfu)
     OPT_DEFS += -DBOOTLOADER_ATMEL_DFU
     OPT_DEFS += -DBOOTLOADER_DFU
-    BOOTLOADER_SIZE = 4096
+    ifeq ($(strip $(MCU)), atmega32u4)
+      BOOTLOADER_SIZE = 4096
+    endif
+    ifeq ($(strip $(MCU)), at90usb1286)
+      BOOTLOADER_SIZE = 8192
+    endif
 endif
 ifeq ($(strip $(BOOTLOADER)), lufa-dfu)
     OPT_DEFS += -DBOOTLOADER_LUFA_DFU
     OPT_DEFS += -DBOOTLOADER_DFU
-    BOOTLOADER_SIZE = 4096
+    ifeq ($(strip $(MCU)), atmega32u4)
+      BOOTLOADER_SIZE = 4096
+    endif
+    ifeq ($(strip $(MCU)), at90usb1286)
+      BOOTLOADER_SIZE = 8192
+    endif
 endif
 ifeq ($(strip $(BOOTLOADER)), qmk-dfu)
     OPT_DEFS += -DBOOTLOADER_QMK_DFU
     OPT_DEFS += -DBOOTLOADER_DFU
-    BOOTLOADER_SIZE = 4096
+    ifeq ($(strip $(MCU)), atmega32u4)
+      BOOTLOADER_SIZE = 4096
+    endif
+    ifeq ($(strip $(MCU)), at90usb1286)
+      BOOTLOADER_SIZE = 8192
+    endif
 endif
 ifeq ($(strip $(BOOTLOADER)), halfkay)
     OPT_DEFS += -DBOOTLOADER_HALFKAY
-    BOOTLOADER_SIZE = 512
+    ifeq ($(strip $(MCU)), atmega32u4)
+      BOOTLOADER_SIZE = 512
+    endif
+    ifeq ($(strip $(MCU)), at90usb1286)
+      BOOTLOADER_SIZE = 1024
+    endif
 endif
 ifeq ($(strip $(BOOTLOADER)), caterina)
     OPT_DEFS += -DBOOTLOADER_CATERINA
@@ -59,4 +79,4 @@ endif
 
 ifdef BOOTLOADER_SIZE
     OPT_DEFS += -DBOOTLOADER_SIZE=$(strip $(BOOTLOADER_SIZE))
-endif
+endif

build_keyboard.mk

@@ -1,3 +1,9 @@
+# Determine what keyboard we are building and setup the build environment.
+#
+# We support folders up to 5 levels deep below `keyboards/`. This file is
+# responsible for determining which folder is being used and doing the
+# corresponding environment setup.
+
 ifndef VERBOSE
 .SILENT:
 endif
@@ -6,26 +12,16 @@ endif
 
 include common.mk
 
-# 5/4/3/2/1
-KEYBOARD_FOLDER_PATH_1 := $(KEYBOARD)
-KEYBOARD_FOLDER_PATH_2 := $(patsubst %/,%,$(dir $(KEYBOARD_FOLDER_PATH_1)))
-KEYBOARD_FOLDER_PATH_3 := $(patsubst %/,%,$(dir $(KEYBOARD_FOLDER_PATH_2)))
-KEYBOARD_FOLDER_PATH_4 := $(patsubst %/,%,$(dir $(KEYBOARD_FOLDER_PATH_3)))
-KEYBOARD_FOLDER_PATH_5 := $(patsubst %/,%,$(dir $(KEYBOARD_FOLDER_PATH_4)))
-KEYBOARD_FOLDER_1 := $(notdir $(KEYBOARD_FOLDER_PATH_1))
-KEYBOARD_FOLDER_2 := $(notdir $(KEYBOARD_FOLDER_PATH_2))
-KEYBOARD_FOLDER_3 := $(notdir $(KEYBOARD_FOLDER_PATH_3))
-KEYBOARD_FOLDER_4 := $(notdir $(KEYBOARD_FOLDER_PATH_4))
-KEYBOARD_FOLDER_5 := $(notdir $(KEYBOARD_FOLDER_PATH_5))
-
+# Set the filename for the final firmware binary
 KEYBOARD_FILESAFE := $(subst /,_,$(KEYBOARD))
-
 TARGET ?= $(KEYBOARD_FILESAFE)_$(KEYMAP)
 KEYBOARD_OUTPUT := $(BUILD_DIR)/obj_$(KEYBOARD_FILESAFE)
+STM32_PATH := quantum/stm32
 
 # Force expansion
 TARGET := $(TARGET)
 
+# For split boards we need to set a master half.
 MASTER ?= left
 ifdef master
     MASTER = $(master)
@@ -39,133 +35,62 @@ $(error MASTER does not have a valid value(left/right))
     endif
 endif
 
-KEYBOARD_PATHS :=
+ifdef SKIP_VERSION
+    OPT_DEFS += -DSKIP_VERSION
+endif
 
+# Determine which subfolders exist.
+KEYBOARD_FOLDER_PATH_1 := $(KEYBOARD)
+KEYBOARD_FOLDER_PATH_2 := $(patsubst %/,%,$(dir $(KEYBOARD_FOLDER_PATH_1)))
+KEYBOARD_FOLDER_PATH_3 := $(patsubst %/,%,$(dir $(KEYBOARD_FOLDER_PATH_2)))
+KEYBOARD_FOLDER_PATH_4 := $(patsubst %/,%,$(dir $(KEYBOARD_FOLDER_PATH_3)))
+KEYBOARD_FOLDER_PATH_5 := $(patsubst %/,%,$(dir $(KEYBOARD_FOLDER_PATH_4)))
+KEYBOARD_FOLDER_1 := $(notdir $(KEYBOARD_FOLDER_PATH_1))
+KEYBOARD_FOLDER_2 := $(notdir $(KEYBOARD_FOLDER_PATH_2))
+KEYBOARD_FOLDER_3 := $(notdir $(KEYBOARD_FOLDER_PATH_3))
+KEYBOARD_FOLDER_4 := $(notdir $(KEYBOARD_FOLDER_PATH_4))
+KEYBOARD_FOLDER_5 := $(notdir $(KEYBOARD_FOLDER_PATH_5))
+KEYBOARD_PATHS :=
 KEYBOARD_PATH_1 := keyboards/$(KEYBOARD_FOLDER_PATH_1)
 KEYBOARD_PATH_2 := keyboards/$(KEYBOARD_FOLDER_PATH_2)
 KEYBOARD_PATH_3 := keyboards/$(KEYBOARD_FOLDER_PATH_3)
 KEYBOARD_PATH_4 := keyboards/$(KEYBOARD_FOLDER_PATH_4)
 KEYBOARD_PATH_5 := keyboards/$(KEYBOARD_FOLDER_PATH_5)
 
-ifneq ("$(wildcard $(KEYBOARD_PATH_5)/rules.mk)","")
+ifneq ("$(wildcard $(KEYBOARD_PATH_5)/)","")
     KEYBOARD_PATHS += $(KEYBOARD_PATH_5)
+endif
+ifneq ("$(wildcard $(KEYBOARD_PATH_4)/)","")
+    KEYBOARD_PATHS += $(KEYBOARD_PATH_4)
+endif
+ifneq ("$(wildcard $(KEYBOARD_PATH_3)/)","")
+    KEYBOARD_PATHS += $(KEYBOARD_PATH_3)
+endif
+ifneq ("$(wildcard $(KEYBOARD_PATH_2)/)","")
+    KEYBOARD_PATHS += $(KEYBOARD_PATH_2)
+endif
+ifneq ("$(wildcard $(KEYBOARD_PATH_1)/)","")
+    KEYBOARD_PATHS += $(KEYBOARD_PATH_1)
+endif
+
+
+# Pull in rules.mk files from all our subfolders
+ifneq ("$(wildcard $(KEYBOARD_PATH_5)/rules.mk)","")
     include $(KEYBOARD_PATH_5)/rules.mk
 endif
 ifneq ("$(wildcard $(KEYBOARD_PATH_4)/rules.mk)","")
-    KEYBOARD_PATHS += $(KEYBOARD_PATH_4)
     include $(KEYBOARD_PATH_4)/rules.mk
 endif
 ifneq ("$(wildcard $(KEYBOARD_PATH_3)/rules.mk)","")
-    KEYBOARD_PATHS += $(KEYBOARD_PATH_3)
     include $(KEYBOARD_PATH_3)/rules.mk
 endif
 ifneq ("$(wildcard $(KEYBOARD_PATH_2)/rules.mk)","")
-    KEYBOARD_PATHS += $(KEYBOARD_PATH_2)
     include $(KEYBOARD_PATH_2)/rules.mk
 endif
 ifneq ("$(wildcard $(KEYBOARD_PATH_1)/rules.mk)","")
-    KEYBOARD_PATHS += $(KEYBOARD_PATH_1)
     include $(KEYBOARD_PATH_1)/rules.mk
 endif
 
-KEYBOARD_SRC :=
-
-KEYBOARD_C_1 := $(KEYBOARD_PATH_1)/$(KEYBOARD_FOLDER_1).c
-KEYBOARD_C_2 := $(KEYBOARD_PATH_2)/$(KEYBOARD_FOLDER_2).c
-KEYBOARD_C_3 := $(KEYBOARD_PATH_3)/$(KEYBOARD_FOLDER_3).c
-KEYBOARD_C_4 := $(KEYBOARD_PATH_4)/$(KEYBOARD_FOLDER_4).c
-KEYBOARD_C_5 := $(KEYBOARD_PATH_5)/$(KEYBOARD_FOLDER_5).c
-
-ifneq ("$(wildcard $(KEYBOARD_C_5))","")
-    KEYBOARD_SRC += $(KEYBOARD_C_5)
-endif
-ifneq ("$(wildcard $(KEYBOARD_C_4))","")
-    KEYBOARD_SRC += $(KEYBOARD_C_4)
-endif
-ifneq ("$(wildcard $(KEYBOARD_C_3))","")
-    KEYBOARD_SRC += $(KEYBOARD_C_3)
-endif
-ifneq ("$(wildcard $(KEYBOARD_C_2))","")
-    KEYBOARD_SRC += $(KEYBOARD_C_2)
-endif
-ifneq ("$(wildcard $(KEYBOARD_C_1))","")
-    KEYBOARD_SRC += $(KEYBOARD_C_1)
-endif
-
-OPT_DEFS += -DKEYBOARD_$(KEYBOARD_FILESAFE)
-
-
-ifneq ("$(wildcard $(KEYBOARD_PATH_1)/$(KEYBOARD_FOLDER_1).h)","")
-    QMK_KEYBOARD_H = $(KEYBOARD_FOLDER_1).h
-endif
-ifneq ("$(wildcard $(KEYBOARD_PATH_2)/$(KEYBOARD_FOLDER_2).h)","")
-    QMK_KEYBOARD_H = $(KEYBOARD_FOLDER_2).h
-endif
-ifneq ("$(wildcard $(KEYBOARD_PATH_3)/$(KEYBOARD_FOLDER_3).h)","")
-    QMK_KEYBOARD_H = $(KEYBOARD_FOLDER_3).h
-endif
-ifneq ("$(wildcard $(KEYBOARD_PATH_4)/$(KEYBOARD_FOLDER_4).h)","")
-    QMK_KEYBOARD_H = $(KEYBOARD_FOLDER_4).h
-endif
-ifneq ("$(wildcard $(KEYBOARD_PATH_5)/$(KEYBOARD_FOLDER_5).h)","")
-    QMK_KEYBOARD_H = $(KEYBOARD_FOLDER_5).h
-endif
-
-# We can assume a ChibiOS target When MCU_FAMILY is defined , since it's not used for LUFA
-ifdef MCU_FAMILY
-    PLATFORM=CHIBIOS
-else
-    PLATFORM=AVR
-endif
-
-ifeq ($(PLATFORM),CHIBIOS)
-    include $(TMK_PATH)/protocol/chibios.mk
-    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
-    endif
-endif
-
-CONFIG_H :=
-ifneq ("$(wildcard $(KEYBOARD_PATH_5)/config.h)","")
-    CONFIG_H += $(KEYBOARD_PATH_5)/config.h
-endif
-ifneq ("$(wildcard $(KEYBOARD_PATH_4)/config.h)","")
-    CONFIG_H += $(KEYBOARD_PATH_4)/config.h
-endif
-ifneq ("$(wildcard $(KEYBOARD_PATH_3)/config.h)","")
-    CONFIG_H += $(KEYBOARD_PATH_3)/config.h
-endif
-ifneq ("$(wildcard $(KEYBOARD_PATH_2)/config.h)","")
-    CONFIG_H += $(KEYBOARD_PATH_2)/config.h
-endif
-ifneq ("$(wildcard $(KEYBOARD_PATH_1)/config.h)","")
-    CONFIG_H += $(KEYBOARD_PATH_1)/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)
 
 MAIN_KEYMAP_PATH_1 := $(KEYBOARD_PATH_1)/keymaps/$(KEYMAP)
 MAIN_KEYMAP_PATH_2 := $(KEYBOARD_PATH_2)/keymaps/$(KEYMAP)
@@ -195,14 +120,182 @@ else ifneq ("$(wildcard $(MAIN_KEYMAP_PATH_1)/keymap.c)","")
     KEYMAP_PATH := $(MAIN_KEYMAP_PATH_1)
 else ifneq ($(LAYOUTS),)
     include build_layout.mk
-else 
+else
     $(error Could not find keymap)
     # this state should never be reached
 endif
 
-# User space stuff
-USER_PATH := users/$(KEYMAP)
+ifeq ($(strip $(CTPC)), yes)
+  CONVERT_TO_PROTON_C=yes
+endif
+
+ifeq ($(strip $(CONVERT_TO_PROTON_C)), yes)
+    TARGET := $(TARGET)_proton_c
+    include $(STM32_PATH)/proton_c.mk
+    OPT_DEFS += -DCONVERT_TO_PROTON_C
+endif
+
+ifneq ($(FORCE_LAYOUT),)
+    TARGET := $(TARGET)_$(FORCE_LAYOUT)
+endif
+
+include quantum/mcu_selection.mk
+
+ifdef MCU_FAMILY
+    OPT_DEFS += -DQMK_STM32
+    KEYBOARD_PATHS += $(STM32_PATH)
+endif
+
+
+# Find all the C source files to be compiled in subfolders.
+KEYBOARD_SRC :=
+
+KEYBOARD_C_1 := $(KEYBOARD_PATH_1)/$(KEYBOARD_FOLDER_1).c
+KEYBOARD_C_2 := $(KEYBOARD_PATH_2)/$(KEYBOARD_FOLDER_2).c
+KEYBOARD_C_3 := $(KEYBOARD_PATH_3)/$(KEYBOARD_FOLDER_3).c
+KEYBOARD_C_4 := $(KEYBOARD_PATH_4)/$(KEYBOARD_FOLDER_4).c
+KEYBOARD_C_5 := $(KEYBOARD_PATH_5)/$(KEYBOARD_FOLDER_5).c
+
+ifneq ("$(wildcard $(KEYBOARD_C_5))","")
+    KEYBOARD_SRC += $(KEYBOARD_C_5)
+endif
+ifneq ("$(wildcard $(KEYBOARD_C_4))","")
+    KEYBOARD_SRC += $(KEYBOARD_C_4)
+endif
+ifneq ("$(wildcard $(KEYBOARD_C_3))","")
+    KEYBOARD_SRC += $(KEYBOARD_C_3)
+endif
+ifneq ("$(wildcard $(KEYBOARD_C_2))","")
+    KEYBOARD_SRC += $(KEYBOARD_C_2)
+endif
+ifneq ("$(wildcard $(KEYBOARD_C_1))","")
+    KEYBOARD_SRC += $(KEYBOARD_C_1)
+endif
+
+# Generate KEYBOARD_name_subname for all levels of the keyboard folder
+KEYBOARD_FILESAFE_1 := $(subst .,,$(subst /,_,$(KEYBOARD_FOLDER_PATH_1)))
+KEYBOARD_FILESAFE_2 := $(subst .,,$(subst /,_,$(KEYBOARD_FOLDER_PATH_2)))
+KEYBOARD_FILESAFE_3 := $(subst .,,$(subst /,_,$(KEYBOARD_FOLDER_PATH_3)))
+KEYBOARD_FILESAFE_4 := $(subst .,,$(subst /,_,$(KEYBOARD_FOLDER_PATH_4)))
+KEYBOARD_FILESAFE_5 := $(subst .,,$(subst /,_,$(KEYBOARD_FOLDER_PATH_5)))
+
+ifneq ("$(wildcard $(KEYBOARD_PATH_5)/)","")
+    OPT_DEFS += -DKEYBOARD_$(KEYBOARD_FILESAFE_5)
+endif
+ifneq ("$(wildcard $(KEYBOARD_PATH_4)/)","")
+    OPT_DEFS += -DKEYBOARD_$(KEYBOARD_FILESAFE_4)
+endif
+ifneq ("$(wildcard $(KEYBOARD_PATH_3)/)","")
+    OPT_DEFS += -DKEYBOARD_$(KEYBOARD_FILESAFE_3)
+endif
+ifneq ("$(wildcard $(KEYBOARD_PATH_2)/)","")
+    OPT_DEFS += -DKEYBOARD_$(KEYBOARD_FILESAFE_2)
+endif
+ifneq ("$(wildcard $(KEYBOARD_PATH_1)/)","")
+    OPT_DEFS += -DKEYBOARD_$(KEYBOARD_FILESAFE_1)
+endif
+
+# Setup the define for QMK_KEYBOARD_H. This is used inside of keymaps so
+# that the same keymap may be used on multiple keyboards.
+#
+# We grab the most top-level include file that we can. That file should
+# use #ifdef statements to include all the neccesary subfolder includes,
+# as described here:
+#
+#    https://docs.qmk.fm/#/feature_layouts?id=tips-for-making-layouts-keyboard-agnostic
+#
+ifneq ("$(wildcard $(KEYBOARD_PATH_1)/$(KEYBOARD_FOLDER_1).h)","")
+    QMK_KEYBOARD_H = $(KEYBOARD_FOLDER_1).h
+endif
+ifneq ("$(wildcard $(KEYBOARD_PATH_2)/$(KEYBOARD_FOLDER_2).h)","")
+    QMK_KEYBOARD_H = $(KEYBOARD_FOLDER_2).h
+endif
+ifneq ("$(wildcard $(KEYBOARD_PATH_3)/$(KEYBOARD_FOLDER_3).h)","")
+    QMK_KEYBOARD_H = $(KEYBOARD_FOLDER_3).h
+endif
+ifneq ("$(wildcard $(KEYBOARD_PATH_4)/$(KEYBOARD_FOLDER_4).h)","")
+    QMK_KEYBOARD_H = $(KEYBOARD_FOLDER_4).h
+endif
+ifneq ("$(wildcard $(KEYBOARD_PATH_5)/$(KEYBOARD_FOLDER_5).h)","")
+    QMK_KEYBOARD_H = $(KEYBOARD_FOLDER_5).h
+endif
+
+# Determine and set parameters based on the keyboard's processor family.
+# We can assume a ChibiOS target When MCU_FAMILY is defined since it's
+# not used for LUFA
+ifdef MCU_FAMILY
+    FIRMWARE_FORMAT?=bin
+    PLATFORM=CHIBIOS
+else ifdef ARM_ATSAM
+    PLATFORM=ARM_ATSAM
+    FIRMWARE_FORMAT=bin
+else
+    PLATFORM=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)","")
+    CONFIG_H += $(KEYBOARD_PATH_5)/config.h
+endif
+ifneq ("$(wildcard $(KEYBOARD_PATH_4)/config.h)","")
+    CONFIG_H += $(KEYBOARD_PATH_4)/config.h
+endif
+ifneq ("$(wildcard $(KEYBOARD_PATH_3)/config.h)","")
+    CONFIG_H += $(KEYBOARD_PATH_3)/config.h
+endif
+ifneq ("$(wildcard $(KEYBOARD_PATH_2)/config.h)","")
+    CONFIG_H += $(KEYBOARD_PATH_2)/config.h
+endif
+ifneq ("$(wildcard $(KEYBOARD_PATH_1)/config.h)","")
+    CONFIG_H += $(KEYBOARD_PATH_1)/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)
+endif
+USER_PATH := users/$(USER_NAME)
+
 -include $(USER_PATH)/rules.mk
+ifneq ("$(wildcard $(USER_PATH)/config.h)","")
+    CONFIG_H += $(USER_PATH)/config.h
+endif
+
 
 # Object files directory
 #     To put object files in current directory, use a dot (.), do NOT make
@@ -214,6 +307,7 @@ ifneq ("$(wildcard $(KEYMAP_PATH)/config.h)","")
 endif
 
 # # project specific files
+SRC += $(patsubst %.c,%.clib,$(LIB_SRC))
 SRC += $(KEYBOARD_SRC) \
     $(KEYMAP_C) \
     $(QUANTUM_SRC)
@@ -232,6 +326,7 @@ include $(TMK_PATH)/protocol.mk
 include $(TMK_PATH)/common.mk
 include bootloader.mk
 
+SRC += $(patsubst %.c,%.clib,$(QUANTUM_LIB_SRC))
 SRC += $(TMK_COMMON_SRC)
 OPT_DEFS += $(TMK_COMMON_DEFS)
 EXTRALDFLAGS += $(TMK_COMMON_LDFLAGS)
@@ -245,6 +340,15 @@ endif
     include $(TMK_PATH)/avr.mk
 endif
 
+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
     VISUALIZER_PATH = $(QUANTUM_PATH)/visualizer
@@ -268,11 +372,8 @@ $(KEYBOARD_OUTPUT)_CONFIG := $(PROJECT_CONFIG)
 
 # Default target.
 all: build check-size
+build: elf cpfirmware
+check-size: build
 
-# Change the build target to build a HEX file or a library.
-build: elf cphex
-#build: elf hex eep lss sym
-#build: lib
-
-
+include show_options.mk
 include $(TMK_PATH)/rules.mk

build_layout.mk

@@ -15,4 +15,13 @@ define SEARCH_LAYOUTS
     $$(foreach LAYOUTS_REPO,$$(LAYOUTS_REPOS),$$(eval $$(call SEARCH_LAYOUTS_REPO)))
 endef
 
+ifneq ($(FORCE_LAYOUT),)
+    ifneq (,$(findstring $(FORCE_LAYOUT),$(LAYOUTS)))
+        $(info Forcing layout: $(FORCE_LAYOUT))
+        LAYOUTS := $(FORCE_LAYOUT)
+    else
+        $(error Forced layout does not exist)
+    endif
+endif
+
 $(foreach LAYOUT,$(LAYOUTS),$(eval $(call SEARCH_LAYOUTS)))

common.mk

@@ -3,16 +3,16 @@ include message.mk
 # Directory common source files exist
 TOP_DIR = .
 TMK_DIR = tmk_core
-TMK_PATH = $(TOP_DIR)/$(TMK_DIR)
-LIB_PATH = $(TOP_DIR)/lib
+TMK_PATH = $(TMK_DIR)
+LIB_PATH = lib
 
 QUANTUM_DIR = quantum
-QUANTUM_PATH = $(TOP_DIR)/$(QUANTUM_DIR)
+QUANTUM_PATH = $(QUANTUM_DIR)
 
 DRIVER_DIR = drivers
-DRIVER_PATH = $(TOP_DIR)/$(DRIVER_DIR)
+DRIVER_PATH = $(DRIVER_DIR)
 
-BUILD_DIR := $(TOP_DIR)/.build
+BUILD_DIR := .build
 
 COMMON_VPATH := $(TOP_DIR)
 COMMON_VPATH += $(TMK_PATH)
@@ -21,4 +21,4 @@ COMMON_VPATH += $(QUANTUM_PATH)/keymap_extras
 COMMON_VPATH += $(QUANTUM_PATH)/audio
 COMMON_VPATH += $(QUANTUM_PATH)/process_keycode
 COMMON_VPATH += $(QUANTUM_PATH)/api
-COMMON_VPATH += $(DRIVER_PATH)
+COMMON_VPATH += $(DRIVER_PATH)

common_features.mk

@@ -34,7 +34,12 @@ ifeq ($(strip $(AUDIO_ENABLE)), yes)
     OPT_DEFS += -DAUDIO_ENABLE
     MUSIC_ENABLE := 1
     SRC += $(QUANTUM_DIR)/process_keycode/process_audio.c
-    SRC += $(QUANTUM_DIR)/audio/audio.c
+    SRC += $(QUANTUM_DIR)/process_keycode/process_clicky.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
@@ -56,8 +61,8 @@ endif
 
 ifeq ($(strip $(STENO_ENABLE)), yes)
     OPT_DEFS += -DSTENO_ENABLE
-	VIRTSER_ENABLE := yes
-	SRC += $(QUANTUM_DIR)/process_keycode/process_steno.c
+    VIRTSER_ENABLE := yes
+    SRC += $(QUANTUM_DIR)/process_keycode/process_steno.c
 endif
 
 ifeq ($(strip $(VIRTSER_ENABLE)), yes)
@@ -70,9 +75,9 @@ ifeq ($(strip $(FAUXCLICKY_ENABLE)), yes)
 endif
 
 ifeq ($(strip $(POINTING_DEVICE_ENABLE)), yes)
-	OPT_DEFS += -DPOINTING_DEVICE_ENABLE
-	OPT_DEFS += -DMOUSE_ENABLE
-	SRC += $(QUANTUM_DIR)/pointing_device.c
+    OPT_DEFS += -DPOINTING_DEVICE_ENABLE
+    OPT_DEFS += -DMOUSE_ENABLE
+    SRC += $(QUANTUM_DIR)/pointing_device.c
 endif
 
 ifeq ($(strip $(UCIS_ENABLE)), yes)
@@ -105,10 +110,60 @@ ifeq ($(strip $(RGBLIGHT_ENABLE)), yes)
     ifeq ($(strip $(RGBLIGHT_CUSTOM_DRIVER)), yes)
         OPT_DEFS += -DRGBLIGHT_CUSTOM_DRIVER
     else
-	    SRC += ws2812.c
+        SRC += ws2812.c
     endif
 endif
 
+VALID_MATRIX_TYPES := yes IS31FL3731 IS31FL3733 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
+        OPT_DEFS += -DLED_MATRIX_ENABLE -DBACKLIGHT_ENABLE -DBACKLIGHT_CUSTOM_DRIVER
+        SRC += $(QUANTUM_DIR)/led_matrix.c
+        SRC += $(QUANTUM_DIR)/led_matrix_drivers.c
+    endif
+endif
+
+ifeq ($(strip $(LED_MATRIX_ENABLE)), IS31FL3731)
+    OPT_DEFS += -DIS31FL3731
+    COMMON_VPATH += $(DRIVER_PATH)/issi
+    SRC += is31fl3731-simple.c
+    SRC += i2c_master.c
+endif
+
+RGB_MATRIX_ENABLE ?= no
+ifneq ($(strip $(RGB_MATRIX_ENABLE)), no)
+ifeq ($(filter $(RGB_MATRIX_ENABLE),$(VALID_MATRIX_TYPES)),)
+    $(error RGB_MATRIX_ENABLE="$(RGB_MATRIX_ENABLE)" is not a valid matrix type)
+endif
+    OPT_DEFS += -DRGB_MATRIX_ENABLE
+    SRC += $(QUANTUM_DIR)/color.c
+    SRC += $(QUANTUM_DIR)/rgb_matrix.c
+    SRC += $(QUANTUM_DIR)/rgb_matrix_drivers.c
+    CIE1931_CURVE = yes
+endif
+
+ifeq ($(strip $(RGB_MATRIX_ENABLE)), yes)
+	RGB_MATRIX_ENABLE = IS31FL3731
+endif
+
+ifeq ($(strip $(RGB_MATRIX_ENABLE)), IS31FL3731)
+    OPT_DEFS += -DIS31FL3731
+    COMMON_VPATH += $(DRIVER_PATH)/issi
+    SRC += is31fl3731.c
+    SRC += i2c_master.c
+endif
+
+ifeq ($(strip $(RGB_MATRIX_ENABLE)), IS31FL3733)
+    OPT_DEFS += -DIS31FL3733
+    COMMON_VPATH += $(DRIVER_PATH)/issi
+    SRC += is31fl3733.c
+    SRC += i2c_master.c
+endif
+
 ifeq ($(strip $(TAP_DANCE_ENABLE)), yes)
     OPT_DEFS += -DTAP_DANCE_ENABLE
     SRC += $(QUANTUM_DIR)/process_keycode/process_tap_dance.c
@@ -128,6 +183,9 @@ endif
 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)
@@ -152,6 +210,9 @@ ifeq ($(strip $(BACKLIGHT_ENABLE)), yes)
     ifeq ($(strip $(VISUALIZER_ENABLE)), yes)
         CIE1931_CURVE = yes
     endif
+    ifeq ($(strip $(BACKLIGHT_CUSTOM_DRIVER)), yes)
+        OPT_DEFS += -DBACKLIGHT_CUSTOM_DRIVER
+    endif
 endif
 
 ifeq ($(strip $(CIE1931_CURVE)), yes)
@@ -171,18 +232,85 @@ endif
 ifeq ($(strip $(TERMINAL_ENABLE)), yes)
     SRC += $(QUANTUM_DIR)/process_keycode/process_terminal.c
     OPT_DEFS += -DTERMINAL_ENABLE
+    OPT_DEFS += -DUSER_PRINT
 endif
 
 ifeq ($(strip $(USB_HID_ENABLE)), yes)
     include $(TMK_DIR)/protocol/usb_hid.mk
 endif
 
+ifeq ($(strip $(ENCODER_ENABLE)), yes)
+    SRC += $(QUANTUM_DIR)/encoder.c
+    OPT_DEFS += -DENCODER_ENABLE
+endif
+
+ifeq ($(strip $(HAPTIC_ENABLE)), DRV2605L)
+    COMMON_VPATH += $(DRIVER_PATH)/haptic
+    SRC += DRV2605L.c
+    SRC += i2c_master.c
+    OPT_DEFS += -DDRV2605L
+endif
+
+ifeq ($(strip $(HD44780_ENABLE)), yes)
+    SRC += drivers/avr/hd44780.c
+    OPT_DEFS += -DHD44780_ENABLE
+endif
+
+ifeq ($(strip $(DYNAMIC_KEYMAP_ENABLE)), yes)
+    OPT_DEFS += -DDYNAMIC_KEYMAP_ENABLE
+    SRC += $(QUANTUM_DIR)/dynamic_keymap.c
+endif
+
+ifeq ($(strip $(LEADER_ENABLE)), yes)
+  SRC += $(QUANTUM_DIR)/process_keycode/process_leader.c
+  OPT_DEFS += -DLEADER_ENABLE
+endif
+
+include $(DRIVER_PATH)/qwiic/qwiic.mk
+
 QUANTUM_SRC:= \
     $(QUANTUM_DIR)/quantum.c \
     $(QUANTUM_DIR)/keymap_common.c \
-    $(QUANTUM_DIR)/keycode_config.c \
-    $(QUANTUM_DIR)/process_keycode/process_leader.c
+    $(QUANTUM_DIR)/keycode_config.c
 
-ifndef CUSTOM_MATRIX
-    QUANTUM_SRC += $(QUANTUM_DIR)/matrix.c
+# Include the standard or split matrix code if needed
+ifneq ($(strip $(CUSTOM_MATRIX)), yes)
+    ifeq ($(strip $(SPLIT_KEYBOARD)), yes)
+        QUANTUM_SRC += $(QUANTUM_DIR)/split_common/matrix.c
+    else
+        QUANTUM_SRC += $(QUANTUM_DIR)/matrix.c
+    endif
+endif
+
+DEBOUNCE_DIR:= $(QUANTUM_DIR)/debounce
+# Debounce Modules. If implemented in matrix.c, don't use these.
+DEBOUNCE_TYPE?= sym_g
+VALID_DEBOUNCE_TYPES := sym_g eager_pk custom
+ifeq ($(filter $(DEBOUNCE_TYPE),$(VALID_DEBOUNCE_TYPES)),)
+    $(error DEBOUNCE_TYPE="$(DEBOUNCE_TYPE)" is not a valid debounce algorithm)
+endif
+ifeq ($(strip $(DEBOUNCE_TYPE)), sym_g)
+    QUANTUM_SRC += $(DEBOUNCE_DIR)/debounce_sym_g.c
+else ifeq ($(strip $(DEBOUNCE_TYPE)), eager_pk)
+    QUANTUM_SRC += $(DEBOUNCE_DIR)/debounce_eager_pk.c
+endif
+
+
+
+ifeq ($(strip $(SPLIT_KEYBOARD)), yes)
+    OPT_DEFS += -DSPLIT_KEYBOARD
+
+    # Include files used by all split keyboards
+    QUANTUM_SRC += $(QUANTUM_DIR)/split_common/split_flags.c \
+                   $(QUANTUM_DIR)/split_common/split_util.c
+
+    # Determine which (if any) transport files are required
+    ifneq ($(strip $(SPLIT_TRANSPORT)), custom)
+        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 both drivers here without bloat.
+        QUANTUM_LIB_SRC += $(QUANTUM_DIR)/split_common/i2c.c \
+                           $(QUANTUM_DIR)/split_common/serial.c
+    endif
+    COMMON_VPATH += $(QUANTUM_PATH)/split_common
 endif

docs/CNAME

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

docs/LANGS.md

@@ -0,0 +1,4 @@
+# Languages
+
+* [English](/)
+* [Chinese](zh/)

docs/README.md

@@ -1,16 +1,23 @@
 # Quantum Mechanical Keyboard Firmware
 
-## What is QMK Firmware? {#what-is-qmk-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/)
 
-QMK (*Quantum Mechanical Keyboard*) is an open source community that maintains QMK Firmware, QMK Flasher, 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.
+## What is QMK Firmware?
 
-## How to Get It {#how-to-get-it}
+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 {#how-to-compile}
+## 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:
 
@@ -20,6 +27,6 @@ This would build the `rev4` revision of the `planck` with the `default` keymap.
 
     make preonic:default
 
-## How to Customize {#how-to-customize}
+## 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/_summary.md

@@ -1,11 +1,16 @@
-* [Getting Started](README.md)
+* [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)
+  * [Best Practices](newbs_best_practices.md)
+  * [Learning Resources](newbs_learn_more_resources.md)
+
+* [QMK Basics](README.md)
   * [QMK Introduction](getting_started_introduction.md)
-  * [Install Build Tools](getting_started_build_tools.md)
-    * Alternative: [Vagrant Guide](getting_started_vagrant.md)
-  * [Build/Compile Instructions](getting_started_make_guide.md)
-  * [Flashing Instructions](flashing.md)
   * [Contributing to QMK](contributing.md)
   * [How to Use Github](getting_started_github.md)
+  * [Getting Help](getting_started_getting_help.md)
 
 * [FAQ](faq.md)
   * [General FAQ](faq_general.md)
@@ -13,64 +18,72 @@
   * [Debugging/Troubleshooting QMK](faq_debug.md)
   * [Keymap](faq_keymap.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)
-  * [Keyboard Guidelines](hardware_keyboard_guidelines.md)
   * [AVR Processors](hardware_avr.md)
-  * ARM Processors (TBD)
   * [Drivers](hardware_drivers.md)
 
+* Reference
+  * [Keyboard Guidelines](hardware_keyboard_guidelines.md)
+  * [Config Options](config_options.md)
+  * [Keycodes](keycodes.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)
+
 * [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)
+  * [Command](feature_command.md)
   * [Dynamic Macros](feature_dynamic_macros.md)
+  * [Encoders](feature_encoders.md)
   * [Grave Escape](feature_grave_esc.md)
   * [Key Lock](feature_key_lock.md)
   * [Layouts](feature_layouts.md)
   * [Leader Key](feature_leader_key.md)
   * [Macros](feature_macros.md)
   * [Mouse Keys](feature_mouse_keys.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)
-  * [Space Cadet](feature_space_cadet.md)
+  * [RGB Matrix](feature_rgb_matrix.md)
+  * [Space Cadet Shift](feature_space_cadet_shift.md)
+  * [Space Cadet Shift Enter](feature_space_cadet_shift_enter.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)
 
-* [Keycodes](keycodes.md)
-  * [Backlight](feature_backlight.md#backlight-keycodes)
-  * [Basic](keycodes_basic.md)
-  * [Bluetooth](feature_bluetooth.md#bluetooth-keycodes)
-  * [Bootmagic](feature_bootmagic.md#bootmagic-keycodes)
-  * [Layer Switching](feature_advanced_keycodes.md#switching-and-toggling-layers)
-  * [Mod+Key](feature_advanced_keycodes.md#modifier-keys)
-  * [Mod Tap](feature_advanced_keycodes.md#mod-tap)
-  * [One Shot Keys](feature_advanced_keycodes.md#one-shot-keys)
-  * [Quantum](quantum_keycodes.md)
-  * [RGB Light](feature_rgblight.md#rgblight-keycodes)
-  * [Shifted Keys](feature_advanced_keycodes.md#shifted-keycodes)
-  * [Stenography](feature_stenography.md#keycode-reference)
-  * [Thermal Printer](feature_thermal_printer.md#thermal-printer-keycodes)
-  * [US ANSI Shifted Keys](keycodes_us_ansi_shifted.md)
-
-* Reference
-  * [Config Options](config_options.md)
-  * [Customizing Functionality](custom_quantum_functions.md)
-  * [Documentation Best Practices](documentation_best_practices.md)
-  * [Documentation Templates](documentation_templates.md)
-  * [Glossary](glossary.md)
-  * [Keymap Overview](keymap.md)
-  * [Unit Testing](unit_testing.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)
@@ -78,3 +91,13 @@
 
 * Other Topics
   * [Using Eclipse with QMK](eclipse.md)
+  * [Support](support.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 correcly installed on our machine. The necesarry 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 necesarry depencencies.
+
+XPM runs using Node.js so grab that form [here](https://nodejs.org/en/). After installation, open a terminal and type `npm -v`. A reply with the version number means that the instalation was successful.
+
+XPM instalation 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`
+
+### Programer/Debugger Drivers
+
+Now its the time to install your programer'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 manufuturer 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

@@ -1,7 +1,9 @@
-A QMK collaborator is a keyboard maker/designer that is interested in helping QMK grow and fully support their keyboard(s), and encouraging their users/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:
+# Becoming a QMK Collaborator
 
-* **Have a PCB available for sale** - unfortunately there's just too much variation and complications with handwired keyboards.
-* **Maintain the your keyboard's directory** - this may just require an initial setup to get your keyboard working, but it could also include accommodating changes made to QMK's core.
-* **Approve and merge your keyboard's keymap pull requests** - we like to encourage users to contribute their keymaps for others to see and work from when creating their own.
+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/config_options.md

@@ -31,9 +31,8 @@ This is a C header file that is one of the first things included, and will persi
 
     #include "config_common.h"
 
-## `config.h` Options
 
-### Hardware Options
+## Hardware Options
 * `#define VENDOR_ID 0x1234`
   * defines your VID, and for most DIY projects, can be whatever you want
 * `#define PRODUCT_ID 0x5678`
@@ -62,24 +61,40 @@ This is a C header file that is one of the first things included, and will persi
   * 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 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 enable if both are enabled)
+  * 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 - B5, B6, B7 use PWM, others use softPWM
 * `#define BACKLIGHT_LEVELS 3`
-  * number of levels your backlight will have (not including off)
+  * number of levels your backlight will have (maximum 15 excluding off)
+* `#define BACKLIGHT_BREATHING`
+  * enables backlight breathing (only works with backlight pins B5, B6 and B7)
+* `#define BREATHING_PERIOD 6`
+  * the length of one backlight "breath" in seconds
 * `#define DEBOUNCING_DELAY 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() ( keyboard_report->mods == (MOD_BIT(KC_LSHIFT) | MOD_BIT(KC_RSHIFT)) )`
+* `#define IS_COMMAND() (get_mods() == (MOD_BIT(KC_LSHIFT) | MOD_BIT(KC_RSHIFT)))`
   * key combination that allows the use of magic commands (useful for debugging)
+* `#define USB_MAX_POWER_CONSUMPTION`
+  * sets the maximum power (in mA) over USB for the device (default: 500)
+* `#define SCL_CLOCK 100000L`
+  * sets the SCL_CLOCK speed for split keyboards. The default is `100000L` but some boards can be set to `400000L`.
 
-### Features That Can Be Disabled
+## Features That Can Be Disabled
 
 If you define these options you will disable the associated feature, which can save on code size.
 
@@ -94,37 +109,49 @@ If you define these options you will disable the associated feature, which can s
 * `#define NO_ACTION_ONESHOT`
   * disable one-shot modifiers
 * `#define NO_ACTION_MACRO`
-  * disable all macro handling
+  * disable old style macro handling: MACRO() & action_get_macro
 * `#define NO_ACTION_FUNCTION`
-  * disable the action function (deprecated)
+  * disable calling of action_function() from the fn_actions array (deprecated)
 
-### Features That Can Be Enabled
+## 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 PREVENT_STUCK_MODIFIERS`
-  * when switching layers, this will release all mods
+* `#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
+## Behaviors That Can Be Configured
 
 * `#define TAPPING_TERM 200`
-  * how long before a tap becomes a hold
+  * 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 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 work better for fast typers who don't want tapping term set above 500
+  * 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 IGNORE_MOD_TAP_INTERRUPT`
-  * makes it possible to do rolling combos (zx) with keys that convert to other keys on hold
 * `#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
@@ -134,8 +161,14 @@ If you define these options you will enable the associated feature, which may in
     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.
 
-### RGB Light Configuration
+## RGB Light Configuration
 
 * `#define RGB_DI_PIN D7`
   * pin the DI on the ws2812 is hooked-up to
@@ -152,7 +185,7 @@ If you define these options you will enable the associated feature, which may in
 * `#define RGBW_BB_TWI`
   * bit-bangs TWI to EZ RGBW LEDs (only required for Ergodox EZ)
 
-### Mouse Key Options
+## Mouse Key Options
 
 * `#define MOUSEKEY_INTERVAL 20`
 * `#define MOUSEKEY_DELAY 0`
@@ -160,22 +193,71 @@ If you define these options you will enable the associated feature, which may in
 * `#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
+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
+
+* `#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 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
+
 # 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.
 
-## `rules.mk` Options
-
-### Build Options
+## 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
+## AVR MCU Options
 * `MCU = atmega32u4`
 * `F_CPU = 16000000`
 * `ARCH = AVR8`
@@ -189,7 +271,7 @@ This is a [make](https://www.gnu.org/software/make/manual/make.html) file that i
   * `caterina`
   * `bootloadHID`
 
-### Feature Options
+## 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.
 
@@ -203,15 +285,60 @@ Use these to enable or disable building certain features. The more you have enab
   * Console for debug(+400)
 * `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`
-  * Enable Bluetooth with the Adafruit EZ-Key HID
+  * 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.
+* `CUSTOM_DEBOUNCE`
+  * Allows replacing the standard key debouncing routine with a 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.
+
+## 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

@@ -11,7 +11,7 @@ Third-party contributions help us grow and improve QMK. We want to make the pull
 
 ## 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 [Gitter](https://gitter.im/qmk/qmk_firmware).
+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:
 
@@ -29,7 +29,7 @@ QMK is largely written in C, with specific features and parts written in C++. It
 
 # 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 gitter](http://gitter.im/QMK/qmk_firmware).
+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?
 
@@ -57,19 +57,39 @@ Never made an open source contribution before? Wondering how contributions work
 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 two spaces (soft tabs)
-* We use One True Brace Style
+* 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 use C style comments: `/* */`
+* 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`)
+
+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;
+  }
+}
+```
 
 # General Guidelines
 
@@ -101,7 +121,7 @@ You'll find all our documentation in the `qmk_firmware/docs` directory, or if yo
 
 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](https://docs.qmk.fm/documentation_templates.html#).
+* 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)
@@ -113,7 +133,7 @@ Keyboards are the raison d'être for QMK. Some keyboards are community maintaine
 
 We also ask that you follow these guidelines:
 
-* Write a `readme.md` using [the template](https://docs.qmk.fm/documentation_templates.html#).
+* 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]`
@@ -124,7 +144,7 @@ We also ask that you follow these guidelines:
 
 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 Gitter](https://gitter.im/qmk/qmk_firmware)
+* [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.
@@ -140,7 +160,7 @@ 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](http://docs.qmk.fm/unit_testing.html) for your feature
+* 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

docs/custom_quantum_functions.md

@@ -27,7 +27,7 @@ The first step to creating your own custom keycode(s) is to enumerate them. This
 
 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
@@ -36,7 +36,7 @@ enum my_keycodes {
 
 ## 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 you to send any key up or down events that are required.
+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.
 
@@ -44,7 +44,7 @@ These function are called every time a key is pressed or released.
 
 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:
@@ -60,6 +60,8 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) {
         PLAY_NOTE_ARRAY(tone_qwerty);
       }
       return true; // Let QMK send the enter press/release events
+    default:
+      return true; // Process all other keycodes normally
   }
 }
 ```
@@ -73,22 +75,22 @@ The `keycode` argument is whatever is defined in your keymap, eg `MO(1)`, `KC_L`
 
 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
-| }
+  keyevent_t event {
+    keypos_t key {
+      uint8_t col
+      uint8_t row
+    }
+    bool     pressed
+    uint16_t time
+  }
 }
 ```
 
 # LED Control
 
-This allows you to control the 5 LED's defined as part of the USB Keyboard spec. It will be called when the state of one of those 5 LEDs changes.
+QMK provides methods to read the 5 LEDs defined as part of the HID spec:
 
 * `USB_LED_NUM_LOCK`
 * `USB_LED_CAPS_LOCK`
@@ -96,31 +98,44 @@ This allows you to control the 5 LED's defined as part of the USB Keyboard spec.
 * `USB_LED_COMPOSE`
 * `USB_LED_KANA`
 
-### Example `led_set_kb()` Implementation
+These five constants correspond to the positional bits of the host LED state.
+There are two ways to get the host LED state:
 
-```
-void led_set_kb(uint8_t usb_led) {
-    if (usb_led & (1<<USB_LED_NUM_LOCK)) {
+* 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)) {
         PORTB |= (1<<0);
     } else {
         PORTB &= ~(1<<0);
     }
-    if (usb_led & (1<<USB_LED_CAPS_LOCK)) {
+    if (IS_LED_ON(usb_led, USB_LED_CAPS_LOCK)) {
         PORTB |= (1<<1);
     } else {
         PORTB &= ~(1<<1);
     }
-    if (usb_led & (1<<USB_LED_SCROLL_LOCK)) {
+    if (IS_LED_ON(usb_led, USB_LED_SCROLL_LOCK)) {
         PORTB |= (1<<2);
     } else {
         PORTB &= ~(1<<2);
     }
-    if (usb_led & (1<<USB_LED_COMPOSE_LOCK)) {
+    if (IS_LED_ON(usb_led, USB_LED_COMPOSE)) {
         PORTB |= (1<<3);
     } else {
         PORTB &= ~(1<<3);
     }
-    if (usb_led & (1<<USB_LED_KANA_LOCK)) {
+    if (IS_LED_ON(usb_led, USB_LED_KANA)) {
         PORTB |= (1<<4);
     } else {
         PORTB &= ~(1<<4);
@@ -133,18 +148,52 @@ void led_set_kb(uint8_t usb_led) {
 * Keyboard/Revision: `void led_set_kb(uint8_t usb_led)`
 * Keymap: `void led_set_user(uint8_t usb_led)`
 
-# Matrix Initialization Code
+## `host_keyboard_leds()`
 
-Before a keyboard can be used the hardware must be initialized. QMK handles initialization of the keyboard matrix itself, but if you have other hardware like LED's or i&#xb2;c controllers you will need to set up that hardware before it can be used.
+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.
 
-### Example `matrix_init_kb()` Implementation
+## 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 B1, B2, and B3 as LED pins.
 
-```
-void matrix_init_kb(void) {
-  // Call the keymap level matrix init.
-  matrix_init_user();
+```c
+void keyboard_pre_init_user(void) {
+  // Call the keyboard pre init code.
 
   // Set our LED pins as output
   DDRB |= (1<<1);
@@ -153,18 +202,54 @@ void matrix_init_kb(void) {
 }
 ```
 
+### `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 gitter](https://gitter.im/qmk/qmk_firmware).
+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
 
@@ -173,4 +258,210 @@ This example has been deliberately omitted. You should understand enough about Q
 
 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 LED's or a display) or other functionality that you want to trigger regularly even when the user isn't typing.
+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 is board is idled and when it wakes up, respectively.
+
+
+### Example suspend_power_down_user() and suspend_wakeup_init_user() Implementation
+
+This example, at the keyboard level, sets up B1, B2, and B3 as LED pins.
+
+```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
+uint32_t layer_state_set_user(uint32_t state) {
+    switch (biton32(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: `void uint32_t layer_state_set_kb(uint32_t state)`
+* Keymap: `uint32_t layer_state_set_user(uint32_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:
+```
+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 `matrix_init_user` and `process_record_user` to configure everything. 
+
+Now, using the `matrix_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: 
+```
+void matrix_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. 
+
+```
+uint32_t layer_state_set_user(uint32_t state) {
+    switch (biton32(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` and `EPRM`. 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:
+```
+
+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 EPRM:
+        if (record->event.pressed) {
+            eeconfig_init(); // resets the EEPROM to default
+        }
+        return false;
+    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. For example, if you want to set rgb layer indication by default, and save the default valued. 
+
+```
+void eeconfig_init_user(void) {  // EEPROM is getting reset! 
+  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. 

docs/documentation_best_practices.md

@@ -22,60 +22,27 @@ Your page should generally have multiple "H1" headings. Only H1 and H2 headings
 
 You can have styled hint blocks drawn around text to draw attention to it.
 
-```
-{% hint style='info' %}
-This uses `hint style='info'`
-{% endhint %}
-```
-
-### Examples:
-
-{% hint style='info' %}
-This uses `hint style='info'`
-{% endhint %}
-
-{% hint style='tip' %}
-This uses `hint style='tip'`
-{% endhint %}
-
-{% hint style='danger' %}
-This uses `hint style='danger'`
-{% endhint %}
-
-{% hint style='working' %}
-This uses `hint style='working'`
-{% endhint %}
-
-# Styled Terminal Blocks
-
-You can present styled terminal blocks by including special tokens inside your text block.
+### Important
 
 ```
-\`\`\`
-**[terminal]
-**[prompt foo@joe]**[path ~]**[delimiter  $ ]**[command ./myscript]
-Normal output line. Nothing special here...
-But...
-You can add some colors. What about a warning message?
-**[warning [WARNING] The color depends on the theme. Could look normal too]
-What about an error message?
-**[error [ERROR] This is not the error you are looking for]
-\`\`\`
+!> This is important
 ```
 
-### Example
+Renders as:
+
+!> This is important
+
+### General Tips
 
 ```
-**[terminal]
-**[prompt foo@joe]**[path ~]**[delimiter  $ ]**[command ./myscript]
-Normal output line. Nothing special here...
-But...
-You can add some colors. What about a warning message?
-**[warning [WARNING] The color depends on the theme. Could look normal too]
-What about an error message?
-**[error [ERROR] This is not the error you are looking for]
+?> 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:
@@ -94,4 +61,4 @@ This page describes my cool feature. You can use my cool feature to make coffee
 |KC_SUGAR||Order Sugar|
 ```
 
-Place your documentation into `docs/feature_<my_cool_feature>.md`, and add that file to the appropriate place in `docs/_summary.md`. If you have added any keycodes be sure to add them to `docs/keycodes.md` with a link back to your feature page.
+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

@@ -36,7 +36,7 @@ Make example for this keyboard (after setting up your build environment):
 
     make planck/rev4:default
 
-See [build environment setup](https://docs.qmk.fm/build_environment_setup.html) then the [make instructions](https://docs.qmk.fm/make_instructions.html) for more information.
+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/eclipse.md

@@ -1,6 +1,6 @@
 # Setting up Eclipse for QMK Development
 
-[Eclipse](https://en.wikipedia.org/wiki/Eclipse_(software)) is an open-source [Integrated Development Environment](https://en.wikipedia.org/wiki/Integrated_development_environment) (IDE) widely used for Java development, but with an extensible plugin system that allows to customize it for other languages and usages.
+[Eclipse][1] is an open-source [Integrated Development Environment](https://en.wikipedia.org/wiki/Integrated_development_environment) (IDE) widely used for Java development, but with an extensible plugin system that allows to customize it for other languages and usages.
 
 Using an IDE such as Eclipse provides many advantages over a plain text editor, such as:
 * intelligent code completion
@@ -17,7 +17,7 @@ Note that this set-up has been tested on Ubuntu 16.04 only for the moment.
 
 # Prerequisites
 ## Build Environment
-Before starting, you must have followed the [Getting Started](home.md#getting-started) section corresponding to your system. In particular, you must have been able to build the firmware with [the `make` command](../#the-make-command).
+Before starting, you must have followed the [Getting Started](README.md#getting-started) section corresponding to your system. In particular, you must have been able to build the firmware with [the `make` command](../#the-make-command).
 
 ## Java
 Eclipse is a Java application, so you will need to install Java 8 or more recent to be able to run it. You may choose between the JRE or the JDK, the latter being useful if you intend to do Java development.
@@ -84,3 +84,5 @@ We will now configure a make target that cleans the project and builds the keyma
 7. (Optional) Toggle the <kbd>Hide Empty Folders</kbd> icon button above the targets tree to only show your build target.
 8. Double-click the build target you created to trigger a build.
 9. Select the <kbd>Console</kbd> view at the bottom to view the running build.
+
+  [1]: https://en.wikipedia.org/wiki/Eclipse_(software)

docs/faq_build.md

@@ -1,40 +1,25 @@
 # Frequently Asked Build Questions
 
-This page covers questions about building QMK. If you have not yet you should read the [Build Environment Setup](getting_started_build_tools.md) and [Make Instructions](getting_started_make_guide.md) guides.
+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 permission to operate a device. For Linux users see udev rules below. Easy way is to use `sudo` command, if you are not familiar with this command check its manual with `man sudo` or this page on line.
+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).
 
-In short when your controller is ATMega32u4,
+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
+or just:
 
     $ sudo make <keyboard>:<keymap>:dfu
 
-But to run `make` with root privilege is not good idea. Use former method if possible.
+Note that running `make` with `sudo` is generally *not* a good idea, and you should use one of the former methods, if possible.
 
-## 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
-
-## Linux `udev` Rules
-On Linux you need proper privilege to access device file of MCU, you'll have to use `sudo` when flashing firmware. You can circumvent this with placing these files in `/etc/udev/rules.d/`.
+### 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/`.
 
 **/etc/udev/rules.d/50-atmel-dfu.rules:**
 ```
@@ -52,6 +37,33 @@ SUBSYSTEMS=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2ff0", MODE:="066
 SUBSYSTEMS=="usb", ATTRS{idVendor}=="feed", 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
+
+If you're using Windows to flash your keyboard, and you are running into issues, check the Device Manager.  If you see an "Unknown Device" when the keyboard is in "bootloader mode", then you may have a driver issue. 
+
+Re-running the installation script for MSYS2 may help (eg run `./util/qmk_install.sh` from MSYS2/WSL) or reinstalling the QMK Toolbox may fix the issue. 
+
+If that doesn't work, then you may need to grab the [Zadig Utility](https://zadig.akeo.ie/). Download this, find the device in question, and select the `WinUS(libusb-1.0)` option, and hit "Reinstall driver". Once you've done that, try flashing your board, again. 
+
+## 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.
@@ -61,7 +73,6 @@ 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.
 
@@ -89,3 +100,35 @@ Note that Teensy2.0++ bootloader size is 2048byte. Some Makefiles may have wrong
 #   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@7
+brew link --force avr-gcc@7
+```

docs/faq_keymap.md

@@ -11,8 +11,17 @@ Keycodes are actually defined in [common/keycode.h](https://github.com/qmk/qmk_f
 
 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/9ce023dc6caadc0cf11c88c782350a8c -->
-![Keyboard Layout Image](https://i.imgur.com/45m4mRf.png)
+<!-- 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
 
@@ -22,15 +31,14 @@ The key found on most modern keyboards that is located between `KC_RGUI` and `KC
 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
+* http://en.wikipedia.org/wiki/Magic_SysRq_key
+* http://en.wikipedia.org/wiki/System_request
 
-## Power Key Doesn't Work
-Use `KC_PWR` instead of `KC_POWER` or vice versa.
-- `KC_PWR` works with Windows and Linux, not with OSX.
-- `KC_POWER` works with OSX and Linux, not with Windows.
+## Power Keys Aren't Working
 
-More info: http://geekhack.org/index.php?topic=14290.msg1327264#msg1327264
+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.
@@ -40,9 +48,9 @@ https://github.com/tmk/tmk_keyboard/issues/67
 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
+* 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
@@ -66,26 +74,26 @@ 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
+* 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
+* 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
+* http://en.wikipedia.org/wiki/Compose_key
 
 And see this for **Unicode** input.
-- http://en.wikipedia.org/wiki/Unicode_input
+* http://en.wikipedia.org/wiki/Unicode_input
 
+## `Fn` Key on macOS
 
-## Apple/Mac Keyboard `Fn`
-Not supported.
+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.
 
-Apple/Mac keyboard sends keycode for Fn unlike most of other keyboards.
-I think you can send Apple Fn key using Apple venter specific Page 0xff01 and usage 0x0003. But you have to change HID Report Descriptor for this, of course.
+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.
 
-https://opensource.apple.com/source/IOHIDFamily/IOHIDFamily-606.1.7/IOHIDFamily/AppleHIDUsageTables.h
+See [this issue](https://github.com/qmk/qmk_firmware/issues/2179) for detailed information.
 
 
 ## Media Control Keys in Mac OSX
@@ -127,7 +135,7 @@ https://github.com/tekezo/Karabiner/issues/403
 
 ## Esc and <code>&#96;</code> on a Single Key
 
-See the [Grave Escape](feature_grave_escape.md) feature.
+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**.
@@ -203,20 +211,3 @@ 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
-
-## Timer Functionality
-
-It's possible to start timers and read values for time-specific events - here's an example:
-
-```c
-static uint16_t key_timer;
-key_timer = timer_read();
-
-if (timer_elapsed(key_timer) < 100) {
-  // do something if less than 100ms have passed
-} else {
-  // do something if 100ms or more have passed
-}
-```
-
-It's best to declare the `static uint16_t key_timer;` at the top of the file, outside of any code blocks you're using it in.

docs/feature_advanced_keycodes.md

@@ -1,8 +1,8 @@
 # Advanced Keycodes
 
-Your keymap can include keycodes that are more advanced than normal, for example shifted keys. This page documents the functions that are available to you.
+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
+## Assigning Custom Names
 
 People often define custom names using `#define`. For example:
 
@@ -13,121 +13,125 @@ People often define custom names using `#define`. For example:
 
 This will allow you to use `FN_CAPS` and `ALT_TAB` in your `KEYMAP()`, keeping it more readable.
 
-### Limits of These Aliases
+## Caveats
 
-Currently, the keycodes able to used with these functions are limited to the [Basic Keycodes](keycodes_basic.md), meaning you can't use keycodes like `KC_TILD`, or anything greater than 0xFF. For a full list of the keycodes able to be used see [Basic Keycodes](keycodes_basic.md).
+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.
+
+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.
+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.
 
-* `MO(layer)` - momentary switch to *layer*. As soon as you let go of the key, the layer is deactivated and you pop back out to the previous layer.
-* `LT(layer, kc)` - momentary switch to *layer* when held, and *kc* when tapped.
-* `TG(layer)` - toggles a layer on or off.
-* `TO(layer)` - Goes to a layer. This code is special, because it lets you go either up or down the stack -- just goes directly to the layer you want. So while other codes only let you go _up_ the stack (from layer 0 to layer 3, for example), `TO(2)` is going to get you to layer 2, no matter where you activate it from -- even if you're currently on layer 5. This gets activated on keydown (as soon as the key is pressed).
-* `TT(layer)` - Layer Tap-Toggle. If you hold the key down, the layer becomes active, and then deactivates when you let go. And if you tap it, the layer simply becomes active (toggles on). It needs 5 taps by default, but you can set it by defining `TAPPING_TOGGLE`, for example, `#define TAPPING_TOGGLE 2` for just two taps.
+* `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
+## 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 "base" layer. This is your normal typing layer, and could be whatever layout you want (qwerty, dvorak, colemak, etc.)
+* 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.
-* Never try to stack a higher numbered layer on top of a lower numbered layer. Doing so is tricky and error prone.
+* 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
+## 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
+## 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](../tmk_core/common/action_layer.h).
+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 functions allow you to combine a mod with a keycode. When pressed the keydown for the mod will be sent first, and then *kc* will be sent. When released the keyup for *kc* will be sent and then the mod will be sent.
+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.
 
-* `LSFT(kc)` or `S(kc)` - applies left Shift to *kc* (keycode)
-* `RSFT(kc)` - applies right Shift to *kc*
-* `LCTL(kc)` - applies left Control to *kc*
-* `RCTL(kc)` - applies right Control to *kc*
-* `LALT(kc)` - applies left Alt to *kc*
-* `RALT(kc)` - applies right Alt to *kc*
-* `LGUI(kc)` - applies left GUI (command/win) to *kc*
-* `RGUI(kc)` - applies right GUI (command/win) to *kc*
-* `HYPR(kc)` - applies Hyper (all modifiers) to *kc*
-* `MEH(kc)`  - applies Meh (all modifiers except Win/Cmd) to *kc*
-* `LCAG(kc)` - applies CtrlAltGui to *kc*
+|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 these, like this:
+You can also chain them, for example `LCTL(LALT(KC_DEL))` makes a key that sends Control+Alt+Delete with a single keypress.
 
-    LALT(LCTL(KC_DEL)) -- this makes a key that sends Alt, Control, and Delete in a single keypress.
+# Mod-Tap
 
-# Shifted Keycodes
+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 following shortcuts automatically add `LSFT()` to keycodes to get commonly used symbols.
+The modifiers this keycode and `OSM()` accept are prefixed with `MOD_`, not `KC_`:
 
-|Key                     |Aliases           |Description        |
-|------------------------|------------------|-------------------|
-|`KC_TILDE`              |`KC_TILD`         |`~`                |
-|`KC_EXCLAIM`            |`KC_EXLM`         |`!`                |
-|`KC_AT`                 |                  |`@`                |
-|`KC_HASH`               |                  |`#`                |
-|`KC_DOLLAR`             |`KC_DLR`          |`$`                |
-|`KC_PERCENT`            |`KC_PERC`         |`%`                |
-|`KC_CIRCUMFLEX`         |`KC_CIRC`         |`^`                |
-|`KC_AMPERSAND`          |`KC_AMPR`         |`&`                |
-|`KC_ASTERISK`           |`KC_ASTR`         |`*`                |
-|`KC_LEFT_PAREN`         |`KC_LPRN`         |`(`                |
-|`KC_RIGHT_PAREN`        |`KC_RPRN`         |`)`                |
-|`KC_UNDERSCORE`         |`KC_UNDS`         |`_`                |
-|`KC_PLUS`               |                  |`+`                |
-|`KC_LEFT_CURLY_BRACE`   |`KC_LCBR`         |`{`                |
-|`KC_RIGHT_CURLY_BRACE`  |`KC_RCBR`         |`}`                |
-|`KC_PIPE`               |                  |<code>&#124;</code>|
-|`KC_COLON`              |`KC_COLN`         |`:`                |
-|`KC_DOUBLE_QUOTE`       |`KC_DQT`/`KC_DQUO`|`"`                |
-|`KC_LEFT_ANGLE_BRACKET` |`KC_LT`/`KC_LABK` |`<`                |
-|`KC_RIGHT_ANGLE_BRACKET`|`KC_GT`/`KC_RABK` |`>`                |
-|`KC_QUESTION`           |`KC_QUES`         |`?`                |
+|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)      |
 
-# Mod Tap
+You can combine these by ORing them together like so:
 
-`MT(mod, kc)` - is *mod* (modifier key - MOD_LCTL, MOD_LSFT) when held, and *kc* when tapped. In other words, you can have a key that sends Esc (or the letter O or whatever) when you tap it, but works as a Control key or a Shift key when you hold it down.
+```c
+MT(MOD_LCTL | MOD_LSFT, KC_ESC)
+```
 
-These are the values you can use for the `mod` in `MT()` and `OSM()`:
+This key would activate Left Control and Left Shift when held, and send Escape when tapped.
 
-  * MOD_LCTL
-  * MOD_LSFT
-  * MOD_LALT
-  * MOD_LGUI
-  * MOD_RCTL
-  * MOD_RSFT
-  * MOD_RALT
-  * MOD_RGUI
-  * MOD_HYPR
-  * MOD_MEH
+For convenience, QMK includes some Mod-Tap shortcuts to make common combinations more compact in your keymap:
 
-These can also be combined like `MOD_LCTL | MOD_LSFT` e.g. `MT(MOD_LCTL | MOD_LSFT, KC_ESC)` which would activate Control and Shift when held, and send Escape when tapped. Note however, that you cannot mix right and left side modifiers.
+|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/)|
 
-We've added shortcuts to make common modifier/tap (mod-tap) mappings more compact:
+## Caveats
 
-  * `CTL_T(kc)` - is LCTL when held and *kc* when tapped
-  * `SFT_T(kc)` - is LSFT when held and *kc* when tapped
-  * `ALT_T(kc)` - is LALT when held and *kc* when tapped
-  * `ALGR_T(kc)` - is AltGr when held and *kc* when tapped
-  * `GUI_T(kc)` - is LGUI when held and *kc* when tapped
-  * `ALL_T(kc)` - is Hyper (all mods) when held and *kc* when tapped. To read more about what you can do with a Hyper key, see [this blog post by Brett Terpstra](http://brettterpstra.com/2012/12/08/a-useful-caps-lock-key/)
-  * `LCAG_T(kc)` - is CtrlAltGui when held and *kc* when tapped
-  * `MEH_T(kc)` - is like Hyper, but not as cool -- does not include the Cmd/Win key, so just sends Alt+Ctrl+Shift.
+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
 
@@ -137,6 +141,8 @@ For example, if you define a key as `OSM(MOD_LSFT)`, you can type a capital A ch
 
 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
@@ -147,23 +153,176 @@ You can control the behavior of one shot keys by defining these in `config.h`:
 * `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 layer as part of a macro or tap dance routine. To do this, 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 more complicated actions, take a look at the oneshot implementation in [`process_record`](../tmk_core/common/action.c#L429).
+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 it easier for fast typists to use dual-function keys. Without this, if you let go of a held key inside the tapping term, it won't register.
+This makes tap and hold keys (like Mod Tap) work better for fast typist, or for high `TAPPING_TERM` settings. 
 
-Example: (Tapping Term = 200ms)
+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:
+
+- `SHFT_T(KC_A)` Down
+- `KC_X` Down
+- `KC_X` Up
+- `SHFT_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:
+
+- `SHFT_T(KC_A)` Down
+- `KC_X` Down
+- `SHFT_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:
 
 - SHFT_T(KC_A) Down
-- KC_X Down
-- KC_X Up
+- SHFT_T(KC_A) Up
+- SHFT_T(KC_A) Down
+- wait more than tapping term...
 - SHFT_T(KC_A) Up
 
-With defaults, if above is typed within tapping term, this will emit `ax`. With permissive hold, if above is typed within tapping term, this will emit `X` (so, Shift+X).
+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

@@ -1,6 +1,18 @@
 # Audio
 
-Your keyboard can make sounds! If you've got a Planck, Preonic, or basically any AVR keyboard that allows access to the C6 or B5 port (`#define C6_AUDIO` and/or `#define B5_AUDIO`), 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.
+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:
 
@@ -47,6 +59,22 @@ 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.
@@ -78,13 +106,78 @@ By default, `MUSIC_MASK` is set to `keycode < 0xFF` which means keycodes less th
 
 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.
+
 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
+
+## 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. |
+| `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. | 
+
+
+
+
 ## MIDI Functionality
 
-This is still a WIP, but check out `quantum/keymap_midi.c` to see what's happening. Enable from the Makefile.
+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
 

docs/feature_auto_shift.md

@@ -1,7 +1,7 @@
 # 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. Viola! No shift key needed!
+and you get its shifted state. Voilà! No shift key needed!
 
 ## Why Auto Shift?
 
@@ -28,10 +28,7 @@ Yes, unfortunately.
    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. 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.
-3. You will have characters that are shifted when you did not intend on shifting, and
+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
@@ -48,6 +45,18 @@ 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
@@ -79,10 +88,7 @@ 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.
 
-{% hint style='info' %}
-Auto Shift has three special keys that can help you get this value right very
-quick. See "Auto Shift Setup" for more details!
-{% endhint %}
+?> 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)
 
@@ -110,6 +116,9 @@ Map three keys temporarily in your keymap:
 | 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.
 

docs/feature_backlight.md

@@ -1,17 +1,76 @@
 # Backlighting
 
-<!-- FIXME: Describe how backlighting works in QMK -->
+Many keyboards support backlit keys by way of individual LEDs placed through or underneath the keyswitches. 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.
 
-## Backlight Keycodes
+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.
 
-These keycodes control the backlight. Most keyboards use this for single color in-switch lighting.
+## 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
+```
+
+You should then be able to use the keycodes below to change the backlight level.
+
+## Keycodes
 
 |Key      |Description                               |
 |---------|------------------------------------------|
 |`BL_TOGG`|Turn the backlight on or off              |
 |`BL_STEP`|Cycle through backlight levels            |
-|`BL_x`   |Set a specific backlight level between 0-9|
-|`BL_ON`  |An alias for `BL_9`                       |
-|`BL_OFF` |An alias for `BL_0`                       |
-|`BL_INC` |Increase backlight level                  |
-|`BL_DEC` |Decrease backlight level                  |
+|`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                |
+
+## Caveats
+
+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 use multiple different coloured LEDs on a keyboard.
+
+Hardware PWM is only supported on certain pins of the MCU, so if the backlighting is not connected to one of them, a software implementation will be used, and backlight breathing will not be available. Currently the supported pins are `B5`, `B6`, `B7`, and `C6`.
+
+## Configuration
+
+To change the behaviour 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_LEVELS`   |`3`          |The number of brightness levels (maximum 15 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 hardware PWM is used                                                          |
+|`BREATHING_PERIOD`   |`6`          |The length of one backlight "breath" in seconds                                                              |
+
+## 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.
+
+## 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 to specified level  |
+|`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

@@ -1,10 +1,40 @@
 # Bluetooth
 
-## Bluetooth Functionality
+## 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
 

docs/feature_bootmagic.md

@@ -1,29 +1,153 @@
 # Bootmagic
 
-<!-- FIXME: Describe the bootmagic feature here. -->
+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 Keycodes
+**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.
 
-Shortcuts for bootmagic options. You can use these even when bootmagic is off.
+**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.
 
-|Key                               |Aliases  |Description                         |
-|----------------------------------|---------|------------------------------------|
-|`MAGIC_SWAP_CONTROL_CAPSLOCK`     |         |Swap Left Control and Caps Lock     |
-|`MAGIC_CAPSLOCK_TO_CONTROL`       |         |Treat Caps Lock as Control          |
-|`MAGIC_SWAP_LALT_LGUI`            |         |Swap Left Alt and GUI               |
-|`MAGIC_SWAP_RALT_RGUI`            |         |Swap Right Alt and GUI              |
-|`MAGIC_NO_GUI`                    |         |Disable the GUI key                 |
-|`MAGIC_SWAP_GRAVE_ESC`            |         |Swap <code>&#96;</code> and Escape  |
-|`MAGIC_SWAP_BACKSLASH_BACKSPACE`  |         |Swap Backslash and Backspace        |
-|`MAGIC_HOST_NKRO`                 |         |Force NKRO on                       |
-|`MAGIC_SWAP_ALT_GUI`              |`AG_SWAP`|Swap Alt and GUI on both sides      |
-|`MAGIC_UNSWAP_CONTROL_CAPSLOCK`   |         |Unswap Left Control and Caps Lock   |
-|`MAGIC_UNCAPSLOCK_TO_CONTROL`     |         |Stop treating CapsLock as Control   |
-|`MAGIC_UNSWAP_LALT_LGUI`          |         |Unswap Left Alt and GUI             |
-|`MAGIC_UNSWAP_RALT_RGUI`          |         |Unswap Right Alt and GUI            |
-|`MAGIC_UNNO_GUI`                  |         |Enable the GUI key                  |
-|`MAGIC_UNSWAP_GRAVE_ESC`          |         |Unswap <code>&#96;</code> and Escape|
-|`MAGIC_UNSWAP_BACKSLASH_BACKSPACE`|         |Unswap Backslash and Backspace      |
-|`MAGIC_UNHOST_NKRO`               |         |Force NKRO off                      |
-|`MAGIC_UNSWAP_ALT_GUI`            |`AG_NORM`|Unswap Left Alt and GUI             |
-|`MAGIC_TOGGLE_NKRO`               |         |Turn NKRO on or off                 |
+**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                       |
+|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 Left Alt and Left GUI              |
+|`MAGIC_TOGGLE_ALT_GUI`            |`AG_TOGG`|Toggle Left Alt 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            |
+
+## 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_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(DEBOUNCING_DELAY * 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,89 @@
+# 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, yu 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.
+!> You cannot reuse (share) keys in combos. Each key should only belong to a single combo.  
+
+## 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) {
+        register_code(KC_LCTL);
+        register_code(KC_C);
+        unregister_code(KC_C);
+        unregister_code(KC_LCTL);
+      }
+      break;
+
+    case XV_PASTE:
+      if (pressed) {
+        register_code(KC_LCTL);
+        register_code(KC_V);
+        unregister_code(KC_V);
+        unregister_code(KC_LCTL);
+      }
+      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`.

docs/feature_command.md

@@ -0,0 +1,50 @@
+# 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()`                      |<code>(get_mods() == (MOD_BIT(KC_LSHIFT) &#124; MOD_BIT(KC_RSHIFT)))</code>|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_HELP1`                   |`H`                                                                        |Print Command help to the console               |
+|`MAGIC_KEY_HELP2`                   |`SLASH`                                                                    |Print Command help to the console (alternate)   |
+|`MAGIC_KEY_LAYER0`                  |`0`                                                                        |Make layer 0 the default layer                  |
+|`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_LAYER0_ALT1`             |`ESC`                                                                      |Make layer 0 the default layer (alternate)      |
+|`MAGIC_KEY_LAYER0_ALT2`             |`GRAVE`                                                                    |Make layer 0 the default layer (alternate)      |
+|`MAGIC_KEY_BOOTLOADER`              |`PAUSE`                                                                    |Enter the bootloader                            |
+|`MAGIC_KEY_LOCK`                    |`CAPS`                                                                     |Lock the keyboard so nothing can be typed       |
+|`MAGIC_KEY_EEPROM`                  |`E`                                                                        |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,46 @@
+# Debounce algorithm
+
+QMK supports multiple debounce algorithms through its debounce API.
+
+The underlying debounce algorithm is determined by which matrix.c file you are using.
+
+The logic for which debounce method called is below. It checks various defines that you have set in rules.mk
+
+```
+DEBOUNCE_TYPE?= sym_g
+VALID_DEBOUNCE_TYPES := sym_g eager_pk custom
+ifeq ($(filter $(DEBOUNCE_TYPE),$(VALID_DEBOUNCE_TYPES)),)
+    $(error DEBOUNCE_TYPE="$(DEBOUNCE_TYPE)" is not a valid debounce algorithm)
+endif
+ifeq ($(strip $(DEBOUNCE_TYPE)), sym_g)
+    QUANTUM_SRC += $(DEBOUNCE_DIR)/debounce_sym_g.c
+else ifeq ($(strip $(DEBOUNCE_TYPE)), eager_pk)
+    QUANTUM_SRC += $(DEBOUNCE_DIR)/debounce_eager_pk.c
+endif
+```
+
+# Debounce selection
+
+| DEBOUNCE_ALGO    | Description                                                 | What to do                    |
+| -------------    | ---------------------------------------------------         | ----------------------------- |
+| Not defined      | You are using the included matrix.c and debounce.c          | Nothing. Debounce_sym_g will be compiled, and used if necessary |
+| custom           | Use your own debounce.c                                     | ```SRC += debounce.c``` add your own debounce.c and implement necessary functions |
+| sym_g / eager_pk | You are using the included matrix.c and debounce.c          | Use an alternative debounce algorithm |
+
+**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 included ```debounce_sym_g.c```s for sample implementations.
+* 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:
+* debounce_eager_pk - debouncing per key. On any state change, response is immediate, followed by ```DEBOUNCE_DELAY``` millseconds of no further input for that key
+* debounce_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_dynamic_macros.md

@@ -4,10 +4,10 @@ QMK supports temporary macros created on the fly. We call these Dynamic Macros.
 
 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 `planck_keycodes` enum — `DYNAMIC_MACRO_RANGE`:
+To enable them, first add a new element to the end of your `keycodes` enum — `DYNAMIC_MACRO_RANGE`:
 
 ```c
-enum planck_keycodes {
+enum keycodes {
 	QWERTY = SAFE_RANGE,
 	COLEMAK,
 	DVORAK,
@@ -20,7 +20,7 @@ enum planck_keycodes {
 };
 ```
 
-It must be the last element because `dynamic_macros.h` will add some more keycodes after it.
+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:
 

docs/feature_encoders.md

@@ -0,0 +1,52 @@
+# Encoders
+
+Basic encoders are supported by adding this to your `rules.mk`:
+
+    ENCODER_ENABLE = yes
+
+and this to your `config.h`:
+
+    #define NUMBER_OF_ENCODERS 1
+    #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
+
+## 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

@@ -1,17 +1,24 @@
 # Grave Escape
 
-Grave Escape is a feature that allows you to share the grave key (<code>&#96;</code> and `~`) on the same key as Escape. When `KC_GESC` is used it will act as `KC_ESC`, unless Shift or GUI is pressed, in which case it will act as `KC_GRAVE`.
+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`. When pressed it will behave like `KC_ESC`, but with Shift or GUI held it will send `KC_GRAVE`.
+
+## Keycodes
 
 |Key      |Aliases    |Description                                                       |
 |---------|-----------|------------------------------------------------------------------|
 |`KC_GESC`|`GRAVE_ESC`|Escape when pressed, <code>&#96;</code> when Shift or GUI are held|
 
-There are several possible key combinations this will break, among them Ctrl+Shift+Esc on Windows and Cmd+Opt+Esc on macOS. You can use these options in your `config.h` to work around this:
+## Configuration
 
-| Option | Description |
-|--------|-------------|
-| `GRAVE_ESC_ALT_OVERRIDE` | Always send Escape if Alt is pressed. |
-| `GRAVE_ESC_CTRL_OVERRIDE` | Always send Escape if Ctrl is pressed. |
-| `GRAVE_ESC_GUI_OVERRIDE` | Always send Escape if GUI is pressed. |
-| `GRAVE_ESC_SHIFT_OVERRIDE` | Always send Escape if SHIFT is pressed. |
+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_hd44780.md

@@ -0,0 +1,56 @@
+# 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. This will use about 400 KB of extra space.
+
+## Configuration
+
+You will need to configure the pins used by your display and its number of lines and collumn in your keyboards `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 posible methods 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

@@ -1,11 +1,22 @@
-## Key Lock: Holding Down Keys for You
+# Key Lock
 
-Sometimes, you need to hold down a specific key for a long period of time. Whether this is while typing in ALL CAPS, or playing a video game that hasn't implemented auto-run, Key Lock is here to help. Key Lock adds a new keycode, `KC_LOCK`, that will hold down the next key you hit for you. The key is released when you hit it again. Here's an example: let's say you need to type in all caps for a few sentences. You hit KC_LOCK, and then shift. Now, shift will be considered held until you hit it again. You can think of key lock as caps lock, but supercharged.
+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.
 
-Here's how to use it:
+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.
 
-1. Pick a key on your keyboard. This will be the key lock key. Assign it the keycode `KC_LOCK`. This will be a single-action key: you won't be able to use it for anything else.
-2. Enable key lock by including `KEY_LOCK_ENABLE = yes` in your Makefile.
-3. That's it!
+## Usage
 
-Important: switching layers does not cancel the key lock. Additionally, key lock is only able to hold standard action keys and One Shot modifier keys (for example, if you have your shift defined as `OSM(KC_LSFT)`; see [One Shot Keys](quantum_keycodes.md#one-shot-keys)). 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. If it's not, then it can't be.
+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](quantum_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

@@ -35,10 +35,12 @@ New names should try to stick to the standards set by existing layouts, and can
 
 ## Supporting a Layout
 
-For a keyboard to support a layout, the variable (`[a-z0-9_]`) must be defined in it's `<keyboard>.h`, and match the number of arguments/keys (and preferably the physical 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
@@ -49,8 +51,39 @@ The folder name must be added to the keyboard's `rules.mk`:
 
 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
@@ -70,3 +103,7 @@ For example:
 ```
 
 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

@@ -5,10 +5,11 @@ If you've ever used Vim, you know what a Leader key is. If not, you're about to
 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` somewhere in your keymap.c file, probably near the top. The 300 there is 300ms -- that's how long you have for the sequence of keys following the leader. You can tweak this value for comfort, of course.
-3. Within your `matrix_scan_user` function, do something like this:
+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) {
@@ -17,14 +18,16 @@ void matrix_scan_user(void) {
     leader_end();
 
     SEQ_ONE_KEY(KC_F) {
-      register_code(KC_S);
-      unregister_code(KC_S);
+      // 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_H);
-      unregister_code(KC_H);
-    }
-    SEQ_THREE_KEYS(KC_A, KC_S, KC_D) {
       register_code(KC_LGUI);
       register_code(KC_S);
       unregister_code(KC_S);
@@ -34,4 +37,110 @@ void matrix_scan_user(void) {
 }
 ```
 
-As you can see, you have three function. you can use - `SEQ_ONE_KEY` for single-key sequences (Leader followed by just one key), and `SEQ_TWO_KEYS` and `SEQ_THREE_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.
+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

@@ -2,9 +2,7 @@
 
 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.
 
-{% hint style='danger' %}
-**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.
-{% endhint %}
+!> **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`
 
@@ -14,24 +12,28 @@ Here is an example `keymap.c` for a two-key keyboard:
 
 ```c
 enum custom_keycodes {
-	MY_CUSTOM_MACRO = SAFE_RANGE
+  QMKBEST = SAFE_RANGE,
 };
 
 bool process_record_user(uint16_t keycode, keyrecord_t *record) {
-	if (record->event.pressed) {
-		switch(keycode) {
-			case MY_CUSTOM_MACRO:
-				SEND_STRING("QMK is the best thing ever!"); // this is our macro!
-				return false; break;
-		}
-	}
-	return true;
+  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] = {
-	  {MY_CUSTOM_MACRO, KC_ESC}
-	}
+  [0] = {
+    {QMKBEST, KC_ESC}
+  }
 };
 ```
 
@@ -39,7 +41,7 @@ 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 `false` to indicate to the caller that the key press we just processed need not be processed any further.
+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.
@@ -47,28 +49,42 @@ You can do that by adding another keycode and adding another case to the switch
 
 ```c
 enum custom_keycodes {
-	MY_CUSTOM_MACRO = SAFE_RANGE,
-	MY_OTHER_MACRO
+  QMKBEST = SAFE_RANGE,
+  QMKURL,
+  MY_OTHER_MACRO
 };
 
 bool process_record_user(uint16_t keycode, keyrecord_t *record) {
-	if (record->event.pressed) {
-		switch(keycode) {
-			case MY_CUSTOM_MACRO:
-				SEND_STRING("QMK is the best thing ever!");
-				return false; break;
-			case MY_OTHER_MACRO:
-				SEND_STRING(SS_LCTRL("ac")); // selects all and copies
-				return false; break;
-		}
-	}
-	return true;
+  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}
-	}
+  [0] = {
+    {MY_CUSTOM_MACRO, MY_OTHER_MACRO}
+  }
 };
 ```
 
@@ -97,6 +113,7 @@ There's also a couple of mod shortcuts you can use:
 * `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:
@@ -131,29 +148,27 @@ SEND_STRING(".."SS_TAP(X_END));
 
 ## The Old Way: `MACRO()` & `action_get_macro`
 
-{% hint style='info' %}
-This is inherited from TMK, and hasn't been updated - it's recommend that you use `SEND_STRING` and `process_record_user` instead.
-{% endhint %}
+?> This is inherited from TMK, and hasn't been updated - it's recommend 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;
+    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) {
+    if (!record->event.pressed) {
 
 ### Macro Commands
 
@@ -172,21 +187,21 @@ Use the `M()` function within your `KEYMAP()` to call a macro. For example, here
 
 ```c
 const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
-	[0] = KEYMAP(
-		M(0), M(1)
-	),
+    [0] = KEYMAP(
+        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;
+    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;
 };
 ```
 
@@ -201,9 +216,9 @@ If you have a bunch of macros you want to refer to from your keymap while keepin
 #define M_BYE M(1)
 
 const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
-	[0] = KEYMAP(
-		M_HI, M_BYE
-	),
+    [0] = KEYMAP(
+        M_HI, M_BYE
+    ),
 };
 ```
 
@@ -216,11 +231,11 @@ There are some functions you may find useful in macro-writing. Keep in mind that
 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
-	}
+    if (record->event.pressed) {
+        // on keydown
+    } else {
+        // on keyup
+    }
 ```
 
 ### `register_code(<kc>);`
@@ -231,6 +246,12 @@ This sends the `<kc>` keydown event to the computer. Some examples would be `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.
+
 ### `clear_keyboard();`
 
 This will clear all mods and keys currently pressed.
@@ -249,16 +270,16 @@ This example defines a macro which sends `Ctrl-C` when pressed down, and `Ctrl-V
 
 ```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;
+    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

@@ -5,17 +5,17 @@ Mousekeys is a feature that allows you to emulate a mouse using your keyboard. Y
 
 ## Adding Mousekeys to a Keymap
 
-There are two steps to adding Mousekeys support to your keyboard. You must enable support in the Makefile and you must map mouse actions to keys on your keyboard.
+There are two steps to adding Mousekeys support to your keyboard. You must enable support in the `rules.mk` file and you must map mouse actions to keys on your keyboard.
 
-### Adding Mousekeys Support in the `Makefile`
+### Adding Mousekeys Support in the `rules.mk`
 
-To add support for Mousekeys you simply need to add a single line to your keymap's `Makefile`:
+To add support for Mousekeys you simply need to add a single line to your keymap's `rules.mk`:
 
 ```
 MOUSEKEY_ENABLE = yes
 ```
 
-You can see an example here: https://github.com/qmk/qmk_firmware/blob/master/keyboards/clueboard/keymaps/mouse_keys/Makefile
+You can see an example here: https://github.com/qmk/qmk_firmware/blob/master/keyboards/clueboard/66/keymaps/mouse_keys/rules.mk
 
 ### Mapping Mouse Actions to Keyboard Keys
 
@@ -40,7 +40,7 @@ You can use these keycodes within your keymap to map button presses to mouse act
 |`KC_MS_ACCEL1`  |`KC_ACL1`|Set mouse acceleration to 1|
 |`KC_MS_ACCEL2`  |`KC_ACL2`|Set mouse acceleration to 2|
 
-You can see an example in the `_ML` here: https://github.com/qmk/qmk_firmware/blob/master/keyboards/clueboard/keymaps/mouse_keys/keymap.c#L46
+You can see an example in the `_ML` here: https://github.com/qmk/qmk_firmware/blob/master/keyboards/clueboard/66/keymaps/mouse_keys/keymap.c#L46
 
 ## Configuring the Behavior of Mousekeys
 

docs/feature_ps2_mouse.md

@@ -6,6 +6,24 @@ To hook up a Trackpoint, you need to obtain a Trackpoint module (i.e. harvest fr
 
 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.

docs/feature_rgb_matrix.md

@@ -0,0 +1,221 @@
+# 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`:
+
+    RGB_MATRIX_ENABLE = IS31FL3731
+
+Configure the hardware via your `config.h`:
+
+	// 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
+
+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
+	 *   |  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
+
+There is basic support for addressable RGB matrix lighting with the I2C IS31FL3733 RGB controller. To enable it, add this to your `rules.mk`:
+
+    RGB_MATRIX_ENABLE = IS31FL3733
+
+Configure the hardware via your `config.h`:
+
+	// 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 1
+	#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`:
+
+	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).
+
+From this point forward the configuration is the same for all the drivers. 
+
+	const rgb_led g_rgb_leds[DRIVER_LED_TOTAL] = {
+	/* {row | col << 4}
+	 *    |           {x=0..224, y=0..64}
+	 *    |              |               modifier
+	 *    |              |                 | */
+	    {{0|(0<<4)},   {20.36*0, 21.33*0}, 1},
+	    {{0|(1<<4)},   {20.36*1, 21.33*0}, 1},
+	    ....
+	}
+
+The format for the matrix position used in this array is `{row | (col << 4)}`. The `x` is between (inclusive) 0-224, and `y` is between (inclusive) 0-64. The easiest way to calculate these positions is:
+
+    x = 224 / ( NUMBER_OF_ROWS - 1 ) * ROW_POSITION
+    y = 64 / (NUMBER_OF_COLS - 1 ) * COL_POSITION
+
+Where all variables are decimels/floats.
+
+`modifier` is a boolean, whether or not a certain key is considered a modifier (used in some effects).
+
+## 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
+
+These are the effects that are currently available:
+
+	enum rgb_matrix_effects {
+	    RGB_MATRIX_SOLID_COLOR = 1,
+	    RGB_MATRIX_ALPHAS_MODS,
+	    RGB_MATRIX_DUAL_BEACON,
+	    RGB_MATRIX_GRADIENT_UP_DOWN,
+	    RGB_MATRIX_RAINDROPS,
+	    RGB_MATRIX_CYCLE_ALL,
+	    RGB_MATRIX_CYCLE_LEFT_RIGHT,
+	    RGB_MATRIX_CYCLE_UP_DOWN,
+	    RGB_MATRIX_RAINBOW_BEACON,
+	    RGB_MATRIX_RAINBOW_PINWHEELS,
+	    RGB_MATRIX_RAINBOW_MOVING_CHEVRON,
+	    RGB_MATRIX_JELLYBEAN_RAINDROPS,
+	    RGB_MATRIX_DIGITAL_RAIN,
+	#ifdef RGB_MATRIX_KEYPRESSES
+	    RGB_MATRIX_SOLID_REACTIVE,
+	    RGB_MATRIX_SPLASH,
+	    RGB_MATRIX_MULTISPLASH,
+	    RGB_MATRIX_SOLID_SPLASH,
+	    RGB_MATRIX_SOLID_MULTISPLASH,
+	#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_DUAL_BEACON`           |Disables `RGB_MATRIX_DUAL_BEACON`           |
+|`#define DISABLE_RGB_MATRIX_GRADIENT_UP_DOWN`      |Disables `RGB_MATRIX_GRADIENT_UP_DOWN`      |
+|`#define DISABLE_RGB_MATRIX_RAINDROPS`             |Disables `RGB_MATRIX_RAINDROPS`             |
+|`#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_RAINBOW_BEACON`        |Disables `RGB_MATRIX_RAINBOW_BEACON`        |
+|`#define DISABLE_RGB_MATRIX_RAINBOW_PINWHEELS`     |Disables `RGB_MATRIX_RAINBOW_PINWHEELS`     |
+|`#define DISABLE_RGB_MATRIX_RAINBOW_MOVING_CHEVRON`|Disables `RGB_MATRIX_RAINBOW_MOVING_CHEVRON`|
+|`#define DISABLE_RGB_MATRIX_JELLYBEAN_RAINDROPS`   |Disables `RGB_MATRIX_JELLYBEAN_RAINDROPS`   |
+|`#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_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 layer effects
+
+Custom layer effects can be done by defining this in your `<keyboard>.c`:
+
+    void rgb_matrix_indicators_kb(void) {
+        rgb_matrix_set_color(index, red, green, blue);
+    }
+
+A similar function works in the keymap as `rgb_matrix_indicators_user`.
+
+## Additional `config.h` Options
+
+	#define RGB_MATRIX_KEYPRESSES // reacts to keypresses (will slow down matrix scan by a lot)
+	#define RGB_MATRIX_KEYRELEASES // reacts to keyreleases (not recommened)
+	#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_SKIP_FRAMES 1 // number of frames to skip when displaying animations (0 is full effect) if not defined defaults to 1
+    #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
+
+## 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:
+
+    #define EECONFIG_RGB_MATRIX (uint32_t *)16
+
+Where `16` is an unused index from `eeconfig.h`.
+
+## Suspended state
+
+To use the suspend feature, add this to your `<keyboard>.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

@@ -1,102 +1,46 @@
 # RGB Lighting
 
-If you've installed addressable RGB lights on your keyboard you can control them with QMK. Currently we support the following addressable LEDs on Atmel AVR processors:
+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.
 
-* WS2811 and variants (WS2812, WS2812B, WS2812C, etc)
-* SK6812RGBW
+![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 pre-installed. Others have to have LEDs installed after the fact. See below for information on modifying your keyboard.
+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.
 
-## Selecting Colors
+Currently QMK supports the following addressable LEDs on AVR microcontrollers (however, the white LED in RGBW variants is not supported):
 
-QMK uses Hue, Saturation, and Value to set color rather than using RGB. You can use the color wheel below to see how this works. Changing the Hue will cycle around the circle. Saturation will affect the intensity of the color, which you can see as you move from the inner part to the outer part of the wheel. Value sets the overall brightness.
+ * WS2811, WS2812, WS2812B, WS2812C, etc.
+ * SK6812, SK6812MINI, SK6805
 
-<img src="gitbook/images/color-wheel.svg" alt="HSV Color Wheel" width="250">
+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.
 
-If you would like to learn more about HSV you can start with the [Wikipedia article](https://en.wikipedia.org/wiki/HSL_and_HSV).
+## Usage
 
-## Configuration
+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:
 
-Before RGB Lighting can be used you have to enable it in `rules.mk`:
-
-    RGBLIGHT_ENABLE = yes
-
-You can configure the behavior of the RGB lighting by defining values inside `config.h`.
-
-### Required Configuration
-
-At minimum you have to define the pin your LED strip is connected to and the number of LEDs connected.
-
-```c
-#define RGB_DI_PIN D7     // The pin the LED strip is connected to
-#define RGBLED_NUM 14     // Number of LEDs in your strip
+```make
+RGBLIGHT_ENABLE = yes
 ```
 
-### Optional Configuration
+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.
 
-You can change the behavior of the RGB Lighting by setting these configuration values. Use `#define <Option> <Value>` in a `config.h` at the keyboard, revision, or keymap level.
+|Define      |Description                                  |
+|------------|---------------------------------------------|
+|`RGB_DI_PIN`|The pin connected to the data pin of the LEDs|
+|`RGBLED_NUM`|The number of LEDs connected                 |
 
-| Option | Default Value | Description |
-|--------|---------------|-------------|
-| `RGBLIGHT_HUE_STEP` | 10 | How many hues you want to have available. |
-| `RGBLIGHT_SAT_STEP` | 17 | How many steps of saturation you'd like. |
-| `RGBLIGHT_VAL_STEP` | 17 | The number of levels of brightness you want. |
+Then you should be able to use the keycodes below to change the RGB lighting to your liking.
 
-### Animations
+### Color Selection
 
-If you have `#define RGBLIGHT_ANIMATIONS` in your `config.h` you will have a number of animation modes you can cycle through using the `RGB_MOD` key. You can also `#define` other options to tweak certain animations.
+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.
 
-| Option | Default Value | Description |
-|--------|---------------|-------------|
-| `RGBLIGHT_ANIMATIONS` | | `#define` this to enable animation modes. |
-| `RGBLIGHT_EFFECT_BREATHE_CENTER` | 1.85 | Used to calculate the curve for the breathing animation. Valid values 1.0-2.7. |
-| `RGBLIGHT_EFFECT_BREATHE_MAX` | 255 | The maximum brightness for the breathing mode. Valid values 1-255. |
-| `RGBLIGHT_EFFECT_SNAKE_LENGTH` | 4 | The number of LEDs to light up for the "snake" animation. |
-| `RGBLIGHT_EFFECT_KNIGHT_LENGTH` | 3 | The number of LEDs to light up for the "knight" animation. |
-| `RGBLIGHT_EFFECT_KNIGHT_OFFSET` | 0 | Start the knight animation this many LEDs from the start of the strip. |
-| `RGBLIGHT_EFFECT_KNIGHT_LED_NUM` | RGBLED_NUM | The number of LEDs to have the "knight" animation travel. |
-| `RGBLIGHT_EFFECT_CHRISTMAS_INTERVAL` | 1000 | How long to wait between light changes for the "christmas" animation. Specified in ms. |
-| `RGBLIGHT_EFFECT_CHRISTMAS_STEP` | 2 | How many LED's to group the red/green colors by for the christmas mode. |
+<img src="gitbook/images/color-wheel.svg" alt="HSV Color Wheel" width="250"/>
 
-You can also tweak the behavior of the animations by defining these consts in your `keymap.c`. These mostly affect the speed different modes animate at.
+Changing the **Hue** cycles around the circle.  
+Changing the **Saturation** moves between the inner and outer sections of the wheel, affecting the intensity of the color.  
+Changing the **Value** sets the overall brightness.
 
-```c
-// How long (in ms) to wait between animation steps for the breathing mode
-const uint8_t RGBLED_BREATHING_INTERVALS[] PROGMEM = {30, 20, 10, 5};
-
-// How long (in ms) to wait between animation steps for the rainbow mode
-const uint8_t RGBLED_RAINBOW_MOOD_INTERVALS[] PROGMEM = {120, 60, 30};
-
-// How long (in ms) to wait between animation steps for the swirl mode
-const uint8_t RGBLED_RAINBOW_SWIRL_INTERVALS[] PROGMEM = {100, 50, 20};
-
-// How long (in ms) to wait between animation steps for the snake mode
-const uint8_t RGBLED_SNAKE_INTERVALS[] PROGMEM = {100, 50, 20};
-
-// How long (in ms) to wait between animation steps for the knight modes
-const uint8_t RGBLED_KNIGHT_INTERVALS[] PROGMEM = {127, 63, 31};
-
-// These control which colors are selected for the gradient mode
-const uint16_t RGBLED_GRADIENT_RANGES[] PROGMEM = {360, 240, 180, 120, 90};
-```
-
-### LED Control
-
-Look in `rgblights.h` for all available functions, but if you want to control all or some LEDs your goto functions are:
-
-```c
-rgblight_disable();  // turn all lights off
-rgblight_enable();  // turn lights on, based on their previous state (stored in EEPROM)
-
-rgblight_setrgb(r, g, b);  // where r/g/b is a number from 0..255.  Turns all the LEDs to this color
-rgblight_sethsv(h, s, v);  // HSV color control
-rgblight_setrgb_at(r,g,b, LED);  // control a single LED.  0 <= LED < RGBLED_NUM
-rgblight_sethsv_at(h,s,v, LED);  // control a single LED.  0 <= LED < RGBLED_NUM
-```
-
-## RGB Lighting Keycodes
-
-These control the RGB Lighting functionality.
+## Keycodes
 
 |Key                |Aliases   |Description                                                         |
 |-------------------|----------|--------------------------------------------------------------------|
@@ -117,24 +61,127 @@ These control the RGB Lighting functionality.
 |`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                                |
 
-note: for backwards compatibility, `RGB_SMOD` is an alias for `RGB_MOD`.
+## 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|
+
+## 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.
+
+The following options can be used to tweak the various animations:
+
+|Define                              |Default      |Description                                                                          |
+|------------------------------------|-------------|-------------------------------------------------------------------------------------|
+|`RGBLIGHT_EFFECT_BREATHING`         |*Not defined*|If defined, enable breathing animation mode.                                         |
+|`RGBLIGHT_EFFECT_RAINBOW_MOOD`      |*Not defined*|If defined, enable rainbow mood animation mode.                                      |
+|`RGBLIGHT_EFFECT_RAINBOW_SWIRL`     |*Not defined*|If defined, enable rainbow swirl animation mode.                                     |
+|`RGBLIGHT_EFFECT_SNAKE`             |*Not defined*|If defined, enable snake animation mode.                                             |
+|`RGBLIGHT_EFFECT_KNIGHT`            |*Not defined*|If defined, enable knight animation mode.                                            |
+|`RGBLIGHT_EFFECT_CHRISTMAS`         |*Not defined*|If defined, enable christmas animation mode.                                         |
+|`RGBLIGHT_EFFECT_STATIC_GRADIENT`   |*Not defined*|If defined, enable static gradient mode.                                             |
+|`RGBLIGHT_EFFECT_RGB_TEST`          |*Not defined*|If defined, enable RGB test animation mode.                                          |
+|`RGBLIGHT_EFFECT_ALTERNATING`       |*Not defined*|If defined, enable alternating animation mode.                                       |
+|`RGBLIGHT_ANIMATIONS`               |*Not defined*|If defined, enables all additional animation modes                                   |
+|`RGBLIGHT_EFFECT_BREATHE_CENTER`    |`1.85`       |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_SNAKE_LENGTH`      |`4`          |The number of LEDs to light up for the "Snake" animation                             |
+|`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_EFFECT_KNIGHT_LED_NUM`    |`RGBLED_NUM` |The number of LEDs to have the "Knight" animation travel                             |
+|`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_RAINBOW_SWIRL_RANGE`      |`360`        |Range adjustment for the rainbow swirl effect to get different swirls                |
+
+You can also modify the speeds that the different modes animate at:
+
+```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 uint16_t RGBLED_GRADIENT_RANGES[] PROGMEM = {360, 240, 180, 120, 90};
+```
+
+## 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:
+
+|Function                           |Description                                                                                                                                                            |
+|-----------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+|`rgblight_enable()`                |Turn LEDs on, based on their previous state                                                                                                                            |
+|`rgblight_enable_noeeprom()`       |Turn LEDs on, based on their previous state (not written to EEPROM)                                                                                                    |
+|`rgblight_disable()`               |Turn LEDs off                                                                                                                                                          |
+|`rgblight_disable_noeeprom()`      |Turn LEDs off (not written to EEPROM)                                                                                                                                  |
+|`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_setrgb(r, g, b)`         |Set all LEDs to the given RGB value where `r`/`g`/`b` are between 0 and 255 (not written to EEPROM)                                                                    |
+|`rgblight_setrgb_at(r, g, b, led)` |Set a single LED to the given RGB value, where `r`/`g`/`b` are between 0 and 255 and `led` is between 0 and `RGBLED_NUM` (not written to EEPROM)                       |
+|`rgblight_sethsv(h, s, v)`         |Set all LEDs to the given HSV value where `h` is between 0 and 360 and `s`/`v` are between 0 and 255                                                                   |
+|`rgblight_sethsv_noeeprom(h, s, v)`|Set all LEDs to the given HSV value where `h` is between 0 and 360 and `s`/`v` are between 0 and 255 (not written to EEPROM)                                           |
+|`rgblight_sethsv_at(h, s, v, led)` |Set a single LED to the given HSV value, where `h` is between 0 and 360, `s`/`v` are between 0 and 255, and `led` is between 0 and `RGBLED_NUM` (not written to EEPROM)|
+|`rgblight_toggle()`                |Toggle all LEDs between on and off                                                                                                                                     |
+|`rgblight_toggle_noeeprom()`       |Toggle all LEDs between on and off (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)                                                            |
+|`rgblight_increase_hue()`          |Increase the hue for all LEDs. This wraps around at maximum hue                                                                                                        |
+|`rgblight_increase_hue_noeeprom()` |Increase the hue for all LEDs. This wraps around at maximum hue (not written to EEPROM)                                                                                |
+|`rgblight_decrease_hue()`          |Decrease the hue for all LEDs. This wraps around at minimum hue                                                                                                        |
+|`rgblight_decrease_hue_noeeprom()` |Decrease the hue for all LEDs. This wraps around at minimum hue (not written to EEPROM)                                                                                |
+|`rgblight_increase_sat()`          |Increase the saturation for all LEDs. This wraps around at maximum saturation                                                                                          |
+|`rgblight_increase_sat_noeeprom()` |Increase the saturation for all LEDs. This wraps around at maximum saturation (not written to EEPROM)                                                                  |
+|`rgblight_decrease_sat()`          |Decrease the saturation for all LEDs. This wraps around at minimum saturation                                                                                          |
+|`rgblight_decrease_sat_noeeprom()` |Decrease the saturation for all LEDs. This wraps around at minimum saturation (not written to EEPROM)                                                                  |
+|`rgblight_increase_val()`          |Increase the value for all LEDs. This wraps around at maximum value                                                                                                    |
+|`rgblight_increase_val_noeeprom()` |Increase the value for all LEDs. This wraps around at maximum value (not written to EEPROM)                                                                            |
+|`rgblight_decrease_val()`          |Decrease the value for all LEDs. This wraps around at minimum value                                                                                                    |
+|`rgblight_decrease_val_noeeprom()` |Decrease the value for all LEDs. This wraps around at minimum value (not written to EEPROM)                                                                            |
+
+Additionally, [`rgblight_list.h`](https://github.com/qmk/qmk_firmware/blob/master/quantum/rgblight_list.h) defines several predefined shortcuts for various colors. Feel free to add to this list!
 
 ## Hardware Modification
 
-![Planck with RGB Underglow](https://raw.githubusercontent.com/qmk/qmk_firmware/master/keyboards/planck/keymaps/yang/planck-with-rgb-underglow.jpg)
-
-Here is a quick demo on Youtube (with NPKC KC60) (https://www.youtube.com/watch?v=VKrpPAHlisY).
-
-For this mod, you need an unused pin wiring to DI of WS2812 strip. After wiring the VCC, GND, and DI, you can enable the underglow in your Makefile.
-
-    RGBLIGHT_ENABLE = yes
-
-In order to use the underglow animation functions, you need to have `#define RGBLIGHT_ANIMATIONS` in your `config.h`.
-
-Please add the following options into your config.h, and set them up according your hardware configuration. These settings are for the `F4` pin by default:
-
-    #define RGB_DI_PIN F4     // The pin your RGB strip is wired to
-    #define RGBLED_NUM 14     // Number of LEDs
-
-You'll need to edit `RGB_DI_PIN` to the pin you have your `DI` on your RGB strip wired to.
+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

@@ -1,24 +0,0 @@
-## Space Cadet Shift: The Future, Built In
-
-Steve Losh [described](http://stevelosh.com/blog/2012/10/a-modern-space-cadet/) the Space Cadet Shift quite well. Essentially, you hit the left Shift on its own, and you get an opening parenthesis; hit the right Shift on its own, and you get the closing one. When hit with other keys, the Shift key keeps working as it always does. Yes, it's as cool as it sounds.
-
-To use it, use `KC_LSPO` (Left Shift, Parenthesis Open) for your left Shift on your keymap, and `KC_RSPC` (Right Shift, Parenthesis Close) for your right Shift.
-
-It's defaulted to work on US keyboards, but if your layout uses different keys for parenthesis, you can define those in your `config.h` like this:
-
-    #define LSPO_KEY KC_9
-    #define RSPC_KEY KC_0
-
-You can also choose between different rollover behaviors of the shift keys by defining:
-
-    #define DISABLE_SPACE_CADET_ROLLOVER
-
-in your `config.h`. Disabling rollover allows you to use the opposite shift key to cancel the space cadet state in the event of an erroneous press instead of emitting a pair of parentheses when the keys are released.
-
-The only other thing you're going to want to do is create a `Makefile` in your keymap directory and set the following:
-
-```
-COMMAND_ENABLE   = no  # Commands for debug and configuration
-```
-
-This is just to keep the keyboard from going into command mode when you hold both Shift keys at the same time.

docs/feature_space_cadet_shift.md

@@ -0,0 +1,37 @@
+# Space Cadet Shift: 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.
+
+## Usage
+
+Replace the Left Shift key in your keymap with `KC_LSPO` (Left Shift, Parenthesis Open), and Right Shift with `KC_RSPC` (Right Shift, Parenthesis Close).
+
+## Keycodes
+
+|Keycode  |Description                           |
+|---------|--------------------------------------|
+|`KC_LSPO`|Left Shift when held, `(` when tapped |
+|`KC_RSPC`|Right Shift when held, `)` when tapped|
+
+## Caveats
+
+Space Cadet's functionality can conflict with the default Command functionality when both Shift keys are held at the same time. 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`.
+You can also disable the rollover, allowing you to use the opposite Shift key to cancel the Space Cadet state in the event of an erroneous press, instead of emitting a pair of parentheses when the keys are released.
+Also, by default, the Space Cadet applies modifiers LSPO_MOD and RSPC_MOD to keys defined by LSPO_KEY and RSPC_KEY. You can override this behavior by redefining those variables in your `config.h`. You can also prevent the Space Cadet to apply a modifier by defining DISABLE_SPACE_CADET_MODIFIER in your `config.h`.
+
+|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 keycode to send when Left Shift is tapped                                   |
+|`RSPC_MOD`                    |`KC_RSFT`    |The keycode to send when Right Shift is tapped                                  |
+|`DISABLE_SPACE_CADET_ROLLOVER`|*Not defined*|If defined, use the opposite Shift key to cancel Space Cadet                    |
+|`DISABLE_SPACE_CADET_MODIFIER`|*Not defined*|If defined, prevent the Space Cadet to apply a modifier to LSPO_KEY and RSPC_KEY|

docs/feature_space_cadet_shift_enter.md

@@ -0,0 +1,31 @@
+# Space Cadet Shift Enter
+
+Based on the [Space Cadet Shift](feature_space_cadet_shift.md) feature. Tap the Shift key on its own, and it behaves like Enter. When held, the Shift functions as normal.
+
+## Usage
+
+Replace any Shift key in your keymap with `KC_SFTENT` (Shift, Enter), and you're done.
+
+## Keycodes
+
+|Keycode    |Description                             |
+|-----------|----------------------------------------|
+|`KC_SFTENT`|Right Shift when held, Enter when tapped|
+
+## Caveats
+
+As with Space Cadet Shift, this feature may conflict with Command, so it should be disabled in your `rules.mk` with:
+
+```make
+COMMAND_ENABLE = no
+```
+
+This feature also uses the same timers as Space Cadet Shift, so using them in tandem may produce strange results.
+
+## Configuration
+
+By default Space Cadet assumes a US ANSI layout, but if you'd like to use a different key for Enter, you can redefine it in your `config.h`:
+
+|Define      |Default |Description                                     |
+|------------|--------|------------------------------------------------|
+|`SFTENT_KEY`|`KC_ENT`|The keycode to send when the Shift key is tapped|

docs/feature_space_shift_cadet.md

@@ -1,26 +0,0 @@
-## Space Cadet Shift Enter: The future, built in
-
-Based on the Space Cadet Shift by Steve Losh [described](http://stevelosh.com/blog/2012/10/a-modern-space-cadet/) 
-Essentially, you hit the Shift on its own, and it acts as the enter key. When hit with other keys, the Shift key keeps working as it always does. Yes, it's as cool as it sounds. This solution works better than using a macro since the timers defined in quantum allow us to tell when another key is pressed, rather than just having a janky timer than results in accidental endlines. 
-
-To use it, use `KC_SFTENT` (Shift, Enter) for any Shift on your keymap.
-
-It's defaulted to work on US keyboards, but if you'd like to use a different key for Enter, you can define those in your `config.h` like this:
-
-    #define SFTENT_KEY KC_ENT
-
-
-The only other thing you're going to want to do is create a `rules.mk` in your keymap directory and set the following:
-
-```
-COMMAND_ENABLE   = no  # Commands for debug and configuration
-```
-
-This is just to keep the keyboard from going into command mode when you hold both Shift keys at the same time.
-
-
-
-
-
-PLEASE NOTE: this feature uses the same timers as the Space Cadet Shift feature, so using them in tandem may produce unwanted results. 
-

docs/feature_stenography.md

@@ -56,6 +56,29 @@ On the display tab click 'Open stroke display'. With Plover disabled you should
 * [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`.
@@ -106,3 +129,4 @@ As defined in `keymap_steno.h`.
 |`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

@@ -6,9 +6,9 @@ Hit the semicolon key once, send a semicolon. Hit it twice, rapidly -- send a co
 
 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.
 
-To make it clear how this is different from `ACTION_FUNCTION_TAP`, lets explore a certain setup! We want one key to send `Space` on single tap, but `Enter` on double-tap.
+To make it clear how this is different from `ACTION_FUNCTION_TAP`, 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 send first. Thus, `SPC a` will result in `a SPC` being sent, if they are typed within `TAPPING_TERM`. With the tap dance feature, that'll come out as `SPC a`, correctly.
+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 they are typed within `TAPPING_TERM`. With the tap dance feature, that'll come out as `SPC a`, correctly.
 
 The implementation hooks into two parts of the system, to achieve this: into `process_record_quantum()`, and the matrix scan. We need the latter to be able to time out a tap sequence even when a key is not being pressed, so `SPC` alone will time out and register after `TAPPING_TERM` time.
 
@@ -16,13 +16,17 @@ But lets start with how to use it, first!
 
 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. 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.
 
-This array specifies what actions shall be taken when a tap-dance key is in action. Currently, there are three possible options:
+This array specifies 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_DUAL_ROLE(kc, layer)`: Sends the `kc` keycode when tapped once, or moves to `layer`. (this functions like the `TO` 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 on when the dance action finishes (like the previous option), and the last function when the tap dance action resets.
+* `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(KC_SPC, KC_ENT)` will result in `Space` being sent on single-tap, `Enter` otherwise.
+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.
 
 And that's the bulk of it!
 
@@ -179,42 +183,98 @@ Below is a specific example:
 *  Double Tap = Send `Escape`
 *  Double Tap and Hold = Send `Alt`
 
-The following example can be easily expanded to more than 4 quite easily:
-```c
-//**************** Definitions needed for quad function to work *********************//
-//Enums used to clearly convey the state of the tap dance
-enum {
-  SINGLE_TAP = 1,
-  SINGLE_HOLD = 2,
-  DOUBLE_TAP = 3,
-  DOUBLE_HOLD = 4,
-  DOUBLE_SINGLE_TAP = 5 //send SINGLE_TAP twice - NOT DOUBLE_TAP
-  // Add more enums here if you want for triple, quadruple, etc.
-};
+## 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 count = 1, and it has been interrupted - it doesn't matter if it is pressed or not: Send SINGLE_TAP
-    if (state->interrupted || state->pressed==0) return SINGLE_TAP;
+    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;
   }
-  //If count = 2, and it has been interrupted - assume that user is trying to type the letter associated
-  //with single tap. In example below, that means to send `xx` instead of `Escape`.
   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;
   }
-  else return 6; //magic number. At some point this method will expand to work for more presses
+  //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
 }
 
-//**************** Definitions needed for quad function to work *********************//
-
 //instanalize an instance of 'tap' for the 'x' tap dance.
 static tap xtap_state = {
   .is_press_action = true,
@@ -245,6 +305,12 @@ void x_reset (qk_tap_dance_state_t *state, void *user_data) {
   }
   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 add this to your list of tap dance functions:
-`[X_TAP_DANCE] = 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.

docs/feature_terminal.md

@@ -14,12 +14,14 @@ When enabled, a `> ` prompt will appear, where you'll be able to type, backspace
 
 `#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
+* Command history - Done
 * SD card support
 * LCD support for buffer display
 * Keycode -> name string LUT
@@ -43,14 +45,39 @@ QMK Firmware
   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
+  about help keycode keymap exit print-buffer flush-buffer
 ```
 
 ### `keycode <layer> <row> <col>`

docs/feature_unicode.md

@@ -1,43 +1,171 @@
 # Unicode Support
 
-There are three Unicode keymap definition method available in QMK:
+There are three Unicode keymap definition methods available in QMK:
 
-## UNICODE_ENABLE
+## `UNICODE_ENABLE`
 
-Supports Unicode input up to 0xFFFF. The keycode function is `UC(n)` in
-keymap file, where *n* is a 4 digit hexadecimal.
+Supports Unicode up to `0x7FFF`. This covers characters for most modern languages, as well as symbols, but it doesn't cover emoji. The keycode function is `UC(c)` in the keymap file, where _c_ is the code point's number (preferably hexadecimal, up to 4 digits long). For example: `UC(0x45B)`, `UC(0x30C4)`.
 
-## UNICODEMAP_ENABLE
+## `UNICODEMAP_ENABLE`
 
-Supports Unicode up to 0xFFFFFFFF. You need to maintain a separate mapping
-table `const uint32_t PROGMEM unicode_map[] = {...}` in your keymap file.
-The keycode function is `X(n)` where *n* is the array index of the mapping
-table.
+Supports Unicode up to `0x10FFFF` (all possible code points). You need to maintain a separate mapping table `const uint32_t PROGMEM unicode_map[] = {...}` in your keymap file. The keycode function is `X(i)`, where _i_ is an array index into the mapping table. The table may contain at most 1024 entries.
 
-## UCIS_ENABLE
+You may want to have an enum to make referencing easier. So, you could add something like this to your keymap file:
 
-TBD
+```c
+enum unicode_names {
+  BANG,
+  IRONY,
+  SNEK,
+};
 
-Unicode input in QMK works by inputing a sequence of characters to the OS,
-sort of like macro. Unfortunately, each OS has different ideas on how Unicode is inputted.
+const uint32_t PROGMEM unicode_map[] = {
+  [BANG]  = 0x203D,  // ‽
+  [IRONY] = 0x2E2E,  // ⸮
+  [SNEK]  = 0x1F40D, // 🐍
+};
+```
 
-This is the current list of Unicode input method in QMK:
+Then you can use `X(BANG)` etc. in your keymap.
 
-* UC_OSX: MacOS Unicode Hex Input support. Works only up to 0xFFFF. Disabled by default. To enable: go to System Preferences -> Keyboard -> Input Sources, and enable Unicode Hex.
-* UC_OSX_RALT: Same as UC_OSX, but sends the Right Alt key for unicode input
-* UC_LNX: Unicode input method under Linux. Works up to 0xFFFFF. Should work almost anywhere on ibus enabled distros. Without ibus, this works under GTK apps, but rarely anywhere else.
-* UC_WIN: (not recommended) Windows built-in Unicode input. To enable: create registry key under `HKEY_CURRENT_USER\Control Panel\Input Method\EnableHexNumpad` of type `REG_SZ` called `EnableHexNumpad`, set its value to 1, and reboot. This method is not recommended because of reliability and compatibility issue, use WinCompose method below instead.
-* UC_WINC: Windows Unicode input using WinCompose. Requires [WinCompose](https://github.com/samhocevar/wincompose). Works reliably under many (all?) variations of Windows.
+## `UCIS_ENABLE`
 
-# Additional Language Support
+Supports Unicode up to `0x10FFFF` (all possible code points). As with `UNICODEMAP`, you need to maintain a mapping table in your keymap file. However, there are no built-in keycodes for this feature — you will have to add a keycode or function that calls `qk_ucis_start()`. Once this function's been called, you can type the corresponding mnemonic for your character, then hit Space or Enter to complete it, or Esc to cancel. If the mnemonic matches an entry in your table, the typed text will automatically be erased and the corresponding Unicode character inserted.
+
+For instance, you would 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)  // 😙
+);
+```
+
+You call `qk_ucis_start()`, then type "rofl" and hit Enter. QMK should erase the "rofl" text and input 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`**: Mac OS X built-in Unicode hex input. Supports code points up to `0xFFFF` (`0x10FFFF` with `UNICODEMAP`).
+
+  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`), but this can be changed by defining [`UNICODE_OSX_KEY`](#input-key-configuration) with another keycode.
+
+* **`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.
+
+* **`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. Afterwards, reboot.
+  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.8.2, supports code points up to `0xFFFFF` (all currently assigned 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 the right Alt key (`KC_RALT`), but this can be changed in the WinCompose settings and by defining [`UNICODE_WINC_KEY`](#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` |             |Cycles forwards through the available modes. [(Disabled by default)](#input-method-cycling)|
+|`UNICODE_MODE_REVERSE` |`UC_RMOD`|             |Cycles forwards through the available modes. [(Disabled by default)](#input-method-cycling)|
+|`UNICODE_MODE_OSX`     |`UC_M_OS`|`UC_OSX`     |Switch to Mac OS X 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 such a large and variable feature, there are a number of options that you can customize to 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 Mac.
+* `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
+
+Additionally, you can customize the keys used to trigger the unicode input for macOS and WinCompose by adding defines to your `config.h`
+
+```c
+#define UNICODE_OSX_KEY  KC_LALT
+#define UNICODE_WINC_KEY KC_RALT
+```
+
+#### Input Method Cycling
+
+Also, you can choose which input methods are availble for cycling through.  By default, this is disabled. But if you want to enabled it, then limiting it to just those modes makes sense.  Note that `UNICODE_SELECTED_MODES` define is comma delimited.
+
+```c
+#define UNICODE_SELECTED_MODES UC_OSX, UC_LNX, UC_WIN, UC_BSD, UC_WINC
+```
+
+## `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
+## International Characters on Windows
 
-[AutoHotkey](https://autohotkey.com) allows Windows users to create custom hotkeys among others.
+### 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 running in the background.
+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.
@@ -52,3 +180,11 @@ In the default script of AutoHotkey you can define custom hotkeys.
 
 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

@@ -3,16 +3,14 @@
 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`
+  * `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)
 
-`<name>.c` will need to be added to 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 though.
 
 All this only happens when you build a keymap named `<name>`, like this:
 
@@ -22,47 +20,179 @@ For example,
 
     make planck:jack
 
-Will include the `/users/jack/` folder in the path, along with `/users/jack/rules.mk`.
+Will include the `/users/jack/` folder in the path, along with `/users/jack/rules.mk`.  
 
-## Readme
+!> 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).
 
-## Example
+You can use this as a template: 
+```
+Copyright <year> <name> <email> @<github_username>
 
-For a brief example, checkout `/users/_example/` , or for a more detailed examples check out [`template.h`](https://github.com/qmk/qmk_firmware/blob/master/users/drashna/template.h) and [`template.c`](https://github.com/qmk/qmk_firmware/blob/master/users/drashna/template.c) in `/users/drashna/` .
+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.
 
-### Consolidated Macros
+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.
 
-If you wanted to consolidate macros and other functions into your userspace for all of your keymaps, you can do that.  The issue is that you then cannot call any function defined in your userspace, or it gets complicated.  To better handle this, you can call the functions here and create new functions to use in individual keymaps.
+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, lets looks at the `layer_state_set_user` function.  Lets enable the [Tri Layer State](ref_functions.md#olkb-tri-layers) functionalitly to all of our boards, and then still have your `keymap.c` still able to use this functionality. 
+
+In your `<name.c>` file, you'd want to add this: 
+```c
+__attribute__ ((weak))
+uint32_t layer_state_set_keymap (uint32_t state) {
+  return state;
+}
+
+uint32_t layer_state_set_user (uint32_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:
-```
-#ifndef USERSPACE
-#define USERSPACE
+```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
 };
-
-#endif
 ```
 
 Now you want to create the `<name>.c` file, and add this content to it:
 
-```
+```c
 #include "<name>.h"
-#include "quantum.h"
-#include "action.h"
-#include "version.h"
 
 __attribute__ ((weak))
 bool process_record_keymap(uint16_t keycode, keyrecord_t *record) {
@@ -90,6 +220,8 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) {
 }
 ```
 
-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.
+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.
 
 Additionally, 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 will dump the HEX in the ".build" folder instead).
+
+

docs/features.md

@@ -3,22 +3,30 @@
 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, type shifted keys, and more. Go beyond typing simple characters.
+* [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.
 * [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").
 * [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. 
+* [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.
 * [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.
+* [One Shot Keys](feature_advanced_keycodes.md#one-shot-keys) - Sticky Keys, lets 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.
-* [Space Cadet](feature_space_cadet.md) - Use your left/right shift keys to type parenthesis and brackets.
+* [RGB Matrix](feature_rgb_matrix.md) - RGB Matrix lights for per key lighting.
+* [Space Cadet](feature_space_cadet_shift.md) - Use your left/right shift keys to type parenthesis and brackets.
 * [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.

docs/flashing.md

@@ -2,7 +2,7 @@
 
 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 it bytes (along with the max). To run this process manually, compile with the target `check-size`, eg `make planck/rev4:default:check-size`.
+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
 
@@ -20,7 +20,7 @@ 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.atmel.com/tools/flip.aspx) (not recommended)
+* [Atmel's Flip](http://www.microchip.com/developmenttools/productdetails.aspx?partno=flip) (not recommended)
 
 Flashing sequence:
 
@@ -71,13 +71,19 @@ 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
-4. Flash a .hex file
-5. Wait for the device to reset automatically
+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).
@@ -100,5 +106,28 @@ 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
-4. Flash a .hex file
-5. Reset the device into application mode (may be done automatically)
+3. Flash a .hex file
+4. Reset the device into application mode (may be done automatically)
+
+## 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

docs/getting_started_build_tools.md

@@ -4,9 +4,11 @@ This page describes setting up the build environment for QMK. These instructions
 
 <!-- FIXME: We should have ARM instructions somewhere. -->
 
+Note: If it is your first time here, Check out the "Complete Newbs guide" instead
+
 ## Linux
 
-To ensure you are always up to date, you can just run `sudo util/install_dependencies.sh`. That should always install all the dependencies needed. **This will run `apt-get upgrade`.**
+To ensure you are always up to date, you can just run `sudo util/qmk_install.sh`. That should always install all the dependencies needed. **This will run `apt-get upgrade`.**
 
 You can also install things manually, but this documentation might not be always up to date with all requirements.
 
@@ -31,11 +33,21 @@ git
 
 Install the dependencies with your favorite package manager.
 
-Debian/Ubuntu example:
+Debian / Ubuntu example:
 
     sudo apt-get update
     sudo apt-get install gcc unzip wget zip gcc-avr binutils-avr avr-libc dfu-programmer dfu-util gcc-arm-none-eabi binutils-arm-none-eabi libnewlib-arm-none-eabi
 
+Fedora / Red Hat example:
+
+    sudo dnf install gcc unzip wget zip dfu-util dfu-programmer avr-gcc avr-libc binutils-avr32-linux-gnu arm-none-eabi-gcc-cs arm-none-eabi-binutils-cs arm-none-eabi-newlib
+    
+Arch / Manjaro example:
+
+    pacman -S base-devel gcc unzip wget zip avr-gcc avr-binutils avr-libc dfu-util arm-none-eabi-gcc arm-none-eabi-binutils arm-none-eabi-newlib git
+
+(the `dfu-programmer` package is availble on AUR only so you should download from there or use an AUR helper)
+
 ## Nix
 
 If you're on [NixOS](https://nixos.org/), or have Nix installed on Linux or macOS, run `nix-shell` from the repository root to get a build environment.
@@ -50,11 +62,14 @@ If you're using [homebrew,](http://brew.sh/) you can use the following commands:
     brew tap osx-cross/avr
     brew tap PX4/homebrew-px4
     brew update
-    brew install avr-gcc
+    brew install avr-gcc@7
+    brew link --force avr-gcc@7
     brew install dfu-programmer
+    brew install dfu-util
     brew install gcc-arm-none-eabi
+    brew install avrdude
 
-This is the recommended method. If you don't have homebrew, [install it!](http://brew.sh/) It's very much worth it for anyone who works in the command line. Note that the `make` and `make install` portion during the homebrew installation of avr-libc can take over 20 minutes and exhibit high CPU usage.
+This is the recommended method. If you don't have homebrew, [install it!](http://brew.sh/) It's very much worth it for anyone who works in the command line. Note that the `make` and `make install` portion during the homebrew installation of `avr-gcc@7` can take over 20 minutes and exhibit high CPU usage.
 
 ## Windows with msys2 (recommended)
 
@@ -62,9 +77,9 @@ The best environment to use, for Windows Vista through any later version (tested
 
 * Install msys2 by downloading it and following the instructions here: http://www.msys2.org
 * Open the ``MSYS2 MingGW 64-bit`` shortcut
-* Navigate to your qmk checkout. For example, if it's in the root of your c drive:
+* Navigate to your QMK repository. For example, if it's in the root of your c drive:
  * `$ cd /c/qmk_firmware`
-* Run `util/msys2_install.sh` and follow the prompts
+* Run `util/qmk_install.sh` and follow the prompts
 
 ## Windows 10 (deprecated)
 These are the old instructions for Windows 10. We recommend you use [MSYS2 as outlined above](#windows-with-msys2-recommended).
@@ -114,24 +129,27 @@ If you have trouble and want to ask for help, it is useful to generate a *Win_Ch
 
 ## Docker
 
-If this is a bit complex for you, Docker might be the turn-key solution you need. After installing [Docker](https://www.docker.com/products/docker), run the following command at the root of the QMK folder to build a keyboard/keymap:
-
+If this is a bit complex for you, Docker might be the turnkey solution you need. After installing [Docker CE](https://docs.docker.com/install/#supported-platforms), run the following command from the `qmk_firmware` directory to build a keyboard/keymap:
 ```bash
-# You'll run this every time you want to build a keymap
-# modify the keymap and keyboard assignment to compile what you want
-# defaults are ergodox/default
+util/docker_build.sh keyboard:keymap
+# For example: util/docker_build.sh ergodox_ez:steno
+```
+This will compile the desired keyboard/keymap and leave the resulting `.hex` or `.bin` file in the QMK directory for you to flash. If `:keymap` is omitted, the `default` keymap is used. Note that the parameter format is the same as when building with `make`.
 
-docker run -e keymap=gwen -e keyboard=ergodox_ez --rm -v $('pwd'):/qmk:rw edasque/qmk_firmware
+You can also start the script without any parameters, in which case it will ask you to input the build parameters one by one, which you may find easier to use:
+```bash
+util/docker_build.sh
+# Reads parameters as input (leave blank for defaults)
 ```
 
-On Windows Docker seems to have issues with the VOLUME tag in Dockerfile, and `$('pwd')` won't print a Windows compliant path; use full path instead, like this:
-
+There is also support for building _and_ flashing the keyboard straight from Docker by specifying the `target` as well:
 ```bash
-docker run -e keymap=default -e keyboard=ergobox_ez --rm -v D:/Users/Sacapuces/Documents/Repositories/qmk:/qmk:rw edasque/qmk_firmware
-
+util/docker_build.sh keyboard:keymap:target
+# For example: util/docker_build.sh planck/rev6:default:dfu-util
 ```
+If you're on Linux, this should work out of the box. On Windows and macOS, it requires [Docker Machine](http://gw.tnode.com/docker/docker-machine-with-usb-support-on-windows-macos/) to be running. This is tedious to set up, so it's not recommended; use [QMK Toolbox](https://github.com/qmk/qmk_toolbox) instead.
 
-This will compile the targeted keyboard/keymap and leave it in your QMK directory for you to flash.
+!> Docker for Windows requires [Hyper-V](https://docs.microsoft.com/en-us/virtualization/hyper-v-on-windows/quick-start/enable-hyper-v) to be enabled. This means that it cannot work on versions of Windows which don't have Hyper-V, such as Windows 7, Windows 8 and **Windows 10 Home**.
 
 ## Vagrant
 If you have any problems building the firmware, you can try using a tool called Vagrant. It will set up a virtual computer with a known configuration that's ready-to-go for firmware building. OLKB does NOT host the files for this virtual computer. Details on how to set up Vagrant are in the [vagrant guide](getting_started_vagrant.md).

docs/getting_started_getting_help.md

@@ -0,0 +1,15 @@
+# Getting Help
+
+There are a lot of resources for getting help with QMK.
+
+## Realtime Chat
+
+You can find QMK developers and users on our main [Discord server](https://discord.gg/Uq7gcHh). There are specific channels in the server for chatting about the firmware, Toolbox, hardware, and configurator.
+
+## OLKB Subreddit
+
+The official QMK forum is [/r/olkb](https://reddit.com/r/olkb) on [reddit.com](https://reddit.com).
+
+## Github Issues
+
+You can open an [issue on GitHub](https://github.com/qmk/qmk_firmware/issues). This is especially handy when your issue will require long-term discussion or debugging.

docs/getting_started_github.md

@@ -2,15 +2,13 @@
 
 Github can be a little tricky to those that aren't familiar with it - this guide will walk through each step of forking, cloning, and submitting a pull request with QMK.
 
-{% hint style='info' %}
-This guide assumes you're somewhat comfortable with running things at the command line, and have git installed on your system.
-{% endhint %}
+?> This guide assumes you're somewhat comfortable with running things at the command line, and have git installed on your system.
 
 Start on the [QMK Github page](https://github.com/qmk/qmk_firmware), and you'll see a button in the upper right that says "Fork":
 
 ![Fork on Github](http://i.imgur.com/8Toomz4.jpg)
 
-If you're apart of an organization, you'll need to choose which account to fork it to. In most circumstances, you'll want to fork it to your personal account. Once your fork is completed (sometimes this takes a little while), click the "Clone or Download" button:
+If you're a part of an organization, you'll need to choose which account to fork it to. In most circumstances, you'll want to fork it to your personal account. Once your fork is completed (sometimes this takes a little while), click the "Clone or Download" button:
 
 ![Download from Github](http://i.imgur.com/N1NYcSz.jpg)
 
@@ -21,8 +19,7 @@ And be sure to select "HTTPS", and select the link and copy it:
 From here, enter `git clone ` into the command line, and then paste your link:
 
 ```
-**[terminal]
-**[prompt you@computer]**[path ~]**[delimiter  $ ]**[command git clone https://github.com/whoeveryouare/qmk_firmware.git]
+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.
@@ -35,13 +32,12 @@ Checking out files: 100% (2799/2799), done.
 You now have your QMK fork on your local machine, and you can add your keymap, compile it and flash it to your board. Once you're happy with your changes, you can add, commit, and push them to your fork like this:
 
 ```
-**[terminal]
-**[prompt you@computer]**[path ~/qmk_firmware]**[delimiter  $ ]**[command git add .]
-**[prompt you@computer]**[path ~/qmk_firmware]**[delimiter  $ ]**[command git commit -m "adding my keymap"]
+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
-**[prompt you@computer]**[path ~/qmk_firmware]**[delimiter  $ ]**[command git push]
+user@computer:~$ git push
 Counting objects: 1, done.
 Delta compression using up to 4 threads.
 Compressing objects: 100% (1/1), done.

docs/getting_started_introduction.md

@@ -6,12 +6,16 @@ This page attempts to explain the basic information you need to know to work wit
 
 QMK is a fork of [Jun Wako](https://github.com/tmk)'s [tmk_keyboard](https://github.com/tmk/tmk_keyboard) project. The original TMK code, with modifications, can be found in the `tmk` folder. The QMK additions to the project may be found in the `quantum` folder. Keyboard projects may be found in the `handwired` and `keyboard` folders.
 
+### Userspace Structure
+
+Within the folder `users` is a directory for each user. This is a place for users to put code that they might use between keyboards. See the docs for [Userspace feature](feature_userspace.md) for more information.
+
 ### Keyboard Project Structure
 
 Within the folder `keyboards` and its subfolder `handwired` is a directory for each keyboard project, for example `qmk_firmware/keyboards/clueboard`. Within it you'll find the following structure:
 
 * `keymaps/`: Different keymaps that can be built
-* `rules.mk`: The file that sets the default "make" options. Do not edit this file directly, instead use a keymap specific `Makefile`
+* `rules.mk`: The file that sets the default "make" options. Do not edit this file directly, instead use a keymap specific `rules.mk`.
 * `config.h`: The file that sets the default compile time options. Do not edit this file directly, instead use a keymap specific `config.h`.
 
 ### Keymap Structure
@@ -25,23 +29,26 @@ In every keymap folder, the following files may be found. Only `keymap.c` is req
 
 # The `config.h` File
 
-There are 2 `config.h` locations:
+There are 3 possible `config.h` locations:
 
 * keyboard (`/keyboards/<keyboard>/config.h`)
+* userspace (`/users/<user>/config.h`)
 * keymap (`/keyboards/<keyboard>/keymaps/<keymap>/config.h`)
 
-If the keymap `config.h` exists, that file is included by the build system and the keyboard `config.h` is not included. If you wish to override settings in your keymap's `config.h` you will need to include some glue code:
+The build system automatically picks up the config files in the above order. If you wish to override any setting set by a previous `config.h` you will need to first include some boilerplate code for the settings you wish to change.
 
 ```
-#ifndef CONFIG_USER_H
-#define CONFIG_USER_H
-
-#include "config_common.h"
+#pragma once
 ```
 
-If you want to override a setting from the parent `config.h` file, you need to `#undef` and then `#define` the setting again, like this:
+Then to override a setting from the previous `config.h` file you must `#undef` and then `#define` the setting again.
 
-```c
+The boilerplate code and setting look like this together:
+
+```
+#pragma once
+
+// overrides go here!
 #undef MY_SETTING
 #define MY_SETTING 4
 ```

docs/getting_started_make_guide.md

@@ -14,7 +14,7 @@ The full syntax of the `make` command is `<keyboard_folder>:<keymap>:<target>`,
 The `<target>` means the following
 * If no target is given, then it's the same as `all` below
 * `all` compiles as many keyboard/revision/keymap combinations as specified. For example, `make planck/rev4:default` will generate a single .hex, while `make planck/rev4:all` will generate a hex for every keymap available to the planck.
-* `dfu`, `teensy` or `dfu-util`, compile and upload the firmware to the keyboard. If the compilation fails, then nothing will be uploaded. The programmer to use depends on the keyboard. For most keyboards it's `dfu`, but for ChibiOS keyboards you should use `dfu-util`, and `teensy` for standard Teensys. To find out which command you should use for your keyboard, check the keyboard specific readme.
+* `dfu`, `teensy`, `avrdude` or `dfu-util`, compile and upload the firmware to the keyboard. If the compilation fails, then nothing will be uploaded. The programmer to use depends on the keyboard. For most keyboards it's `dfu`, but for ChibiOS keyboards you should use `dfu-util`, and `teensy` for standard Teensys. To find out which command you should use for your keyboard, check the keyboard specific readme.
  * **Note**: some operating systems need root access for these commands to work, so in that case you need to run for example `sudo make planck/rev4:default:dfu`.
 * `clean`, cleans the build output folders to make sure that everything is built from scratch. Run this before normal compilation if you have some unexplainable problems.
 
@@ -93,19 +93,17 @@ This enables MIDI sending and receiving with your keyboard. To enter MIDI send m
 
 `UNICODE_ENABLE`
 
-This allows you to send unicode symbols via `UC(<unicode>)` in your keymap. Only codes up to 0x7FFF are currently supported.
+This allows you to send Unicode characters using `UC(<code point>)` in your keymap. Code points up to `0x7FFF` are supported. This covers characters for most modern languages, as well as symbols, but it doesn't cover emoji.
 
 `UNICODEMAP_ENABLE`
 
-This allows sending unicode symbols using `X(<unicode>)` in your keymap. Codes
-up to 0xFFFFFFFF are supported, including emojis. You will need to maintain
-a separate mapping table in your keymap file.
+This allows you to send Unicode characters using `X(<map index>)` in your keymap. You will need to maintain a mapping table in your keymap file. All possible code points (up to `0x10FFFF`) are supported.
 
-Known limitations:
-- Under Mac OS, only codes up to 0xFFFF are supported.
-- Under Linux ibus, only codes up to 0xFFFFF are supported (but anything important is still under this limit for now).
+`UCIS_ENABLE`
 
-Characters out of range supported by the OS will be ignored.
+This allows you to send Unicode characters by inputting a mnemonic corresponding to the character you want to send. You will need to maintain a mapping table in your keymap file. All possible code points (up to `0x10FFFF`) are supported.
+
+For further details, as well as limitations, see the [Unicode page](feature_unicode.md).
 
 `BLUETOOTH_ENABLE`
 
@@ -117,7 +115,7 @@ This allows you output audio on the C6 pin (needs abstracting). See the [audio p
 
 `FAUXCLICKY_ENABLE`
 
-Uses buzzer to emulate clicky switches. A cheap imitation of the Cherry blue switches. By default, uses the C6 pin, same as AUDIO_ENABLE.
+Uses buzzer to emulate clicky switches. A cheap imitation of the Cherry blue switches. By default, uses the C6 pin, same as `AUDIO_ENABLE`.
 
 `VARIABLE_TRACE`
 
@@ -133,6 +131,22 @@ This consumes about 5390 bytes.
 
 This enables [key lock](feature_key_lock.md). This consumes an additional 260 bytes.
 
+`SPLIT_KEYBOARD`
+
+This 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
+
+`SPLIT_TRANSPORT`
+
+As there is no standard split communication driver for ARM-based split keyboards yet, `SPLIT_TRANSPORT = custom` must be used for these. It will prevent the standard split keyboard communication code (which is AVR-specific) from being included, allowing a custom implementation to be used.
+
+`CUSTOM_MATRIX`
+
+Lets you replace the default matrix scanning routine with your own code. You will need to provide your own implementations of matrix_init() and matrix_scan().
+
+`CUSTOM_DEBOUNCE`
+
+Lets you replace the default key debouncing routine with your own code. You will need to provide your own implementation of debounce().
+
 ## Customizing Makefile Options on a Per-Keymap Basis
 
 If your keymap directory has a file called `rules.mk` any options you set in that file will take precedence over other `rules.mk` options for your particular keyboard.

docs/glossary.md

@@ -1,170 +0,0 @@
-# Glossary of QMK Terms
-
-## ARM
-A line of 32-bit MCU's produced by a number of companies, such as Atmel, Cypress, Kinetis, NXP, ST, and TI.
-
-## AVR
-A line of 8-bit MCU's produced by [Atmel](http://atmel.com). AVR was the original platform that TMK supported.
-
-## AZERTY
-The standard Français (French) keyboard layout. Named for the first 6 keys on the keyboard.
-
-## Backlight
-A generic term for lighting on a keyboard. The backlight is typically, but not always, an array of LED's that shine through keycaps and/or switches.
-
-## Bluetooth
-A short range peer to peer wireless protocol. Most common wireless protocol for a keyboard.
-
-## Bootloader
-A special program that is written to a protected area of your MCU that allows the MCU to upgrade its own firmware, typically over USB.
-
-## Bootmagic
-A feature that allows for various keyboard behavior changes to happen on the fly, such as swapping or disabling common keys.
-
-## C
-A low-level programming language suitable for system code. Most QMK code is written in C.
-
-## Colemak
-An alternative keyboard layout that is gaining in popularity.
-
-## Compile
-The process of turning human readable code into machine code your MCU can run.
-
-## Dvorak
-An alternative keyboard layout developed by Dr. August Dvorak in the 1930's. A shortened form of the Dvorak Simplified Keyboard.
-
-## Dynamic Macro
-A macro which has been recorded on the keyboard and which will be lost when the keyboard is unplugged or the computer rebooted.
-
-* [Dynamic Macro Documentation](feature_dynamic_macros.md)
-
-## Eclipse
-An IDE that is popular with many C developers.
-
-* [Eclipse Setup Instructions](eclipse.md)
-
-## Firmware
-The software that controls your MCU.
-
-## FLIP
-Software provided by Atmel for flashing AVR devices. We generally recommend [QMK Flasher](https://github.com/qmk/qmk_flasher) instead, but for some advanced use cases FLIP is required.
-
-## git
-Versioning software used at the command line
-
-## GitHub
-The website that hosts most of the QMK project. It provides integration with git, issue tracking, and other features that help us run QMK.
-
-## ISP
-In-system programming, a method of programming an AVR chip using external hardware and the JTAG pins.
-
-## hid_listen
-An interface for receiving debugging messages from your keyboard. You can view these messages using [QMK Flasher](https://github.com/qmk/qmk_flasher) or [PJRC's hid_listen](https://www.pjrc.com/teensy/hid_listen.html)
-
-## Keycode
-A 2-byte number that represents a particular key. `0x00`-`0xFF` are used for [Basic Keycodes](keycodes_basic.md) while `0x100`-`0xFFFF` are used for [Quantum Keycodes](quantum_keycodes.md).
-
-## Key Down
-An event that happens when a key is pressed down, but is completed before a key is released.
-
-## Key Up
-An event that happens when a key is released.
-
-## Keymap
-An array of keycodes mapped to a physical keyboard layout, which are processed on key presses and releases
-
-## Layer
-An abstraction used to allow a key to serve multiple purposes. The highest active layer takes precedence.
-
-## Leader Key
-A feature that allows you to tap the leader key followed by a sequence of 1, 2, or 3 keys to activate key presses or other quantum features.
-
-* [Leader Key Documentation](feature_leader_key.md)
-
-## LED
-Light Emitting Diode, the most common device used for indicators on a keyboard.
-
-## Make
-Software package that is used to compile all the source files. You run `make` with various options to compile your keyboard firmware.
-
-## Matrix
-A wiring pattern of columns and rows that enables the MCU to detect keypresses with a fewer number of pins. The matrix often incorporates diodes to allow for NKRO.
-
-## Macro
-A feature that lets you send multiple keypress events (hid reports) after having pressed only a single key.
-
-* [Macro Documentation](feature_macros.md)
-
-## MCU
-Microcontrol Unit, the processor that powers your keyboard.
-
-## Modifier
-A key that is held down while typing another key to modify the action of that key. Examples include Ctrl, Alt, and Shift.
-
-## Mousekeys
-A feature that lets you control your mouse cursor and click from your keyboard.
-
-* [Mousekeys Documentation](feature_mouse_keys.md)
-
-## N-Key Rollover (NKRO)
-A term that applies to keyboards that are capable of reporting any number of key-presses at once.
-
-## Oneshot Modifier
-A modifier that acts as if it is held down until another key is released, so you can press the mod and then press the key, rather than holding the mod while pressing the key. Also known as a Sticky key or a Dead key.
-
-## ProMicro
-A low cost AVR development board. Clones of this device are often found on ebay very inexpensively (under $5) but people often struggle with flashing their pro micros.
-
-## Pull Request
-A request to submit code to QMK. We encourage all users to submit Pull Requests for their personal keymaps.
-
-## QWERTY
-The standard English keyboard layout, and often a shortcut for other language's standard layouts. Named for the first 6 letters on the keyboard.
-
-## QWERTZ
-The standard Deutsche (German) keyboard layout. Named for the first 6 letters on the keyboard.
-
-## Rollover
-The term for pressing a key while a key is already held down. Variants include 2KRO, 6KRO, and NKRO.
-
-## Scancode
-A 1 byte number that is sent as part of a HID report over USB that represents a single key. These numbers are documented in the [HID Usage Tables](http://www.usb.org/developers/hidpage/Hut1_12v2.pdf) published by the [USB-IF](http://www.usb.org/).
-
-## Space Cadet Shift
-A special set of shift keys which allow you to type various types of braces by tapping the left or right shift one or more times.
-
-* [Space Cadet Shift Documentation](feature_space_cadet.md)
-
-## Tap
-Pressing and releasing a key. In some situations you will need to distinguish between a key down and a key up event, and Tap always refers to both at once.
-
-## Tap Dance
-A feature that lets you assign multiple keycodes to the same key based on how many times you press it.
-
-* [Tap Dance Documentation](feature_tap_dance.md)
-
-## Teensy
-A low-cost AVR development board that is commonly used for hand-wired builds. A teensy is often chosen despite costing a few dollars more due to its halfkay bootloader, which makes flashing very simple.
-
-## Underlight
-A generic term for LEDs that light the underside of the board. These LED's typically shine away from the bottom of the PCB and towards the surface the keyboard rests on.
-
-## Unicode
-In the larger computer world Unicode is a set of encoding schemes for representing characters in any language. As it relates to QMK it means using various OS schemes to send unicode codepoints instead of scancodes.
-
-* [Unicode Documentation](feature_unicode.md)
-
-## Unit Testing
-A framework for running automated tests against QMK. Unit testing helps us be confident that our changes do not break anything.
-
-* [Unit Testing Documentation](unit_testing.md)
-
-## USB
-Universal Serial Bus, the most common wired interface for a keyboard.
-
-## USB Host (or simply Host)
-The USB Host is your computer, or whatever device your keyboard is plugged into.
-
-# Couldn't Find the Term You're Looking For?
-
-[Open an issue](https://github.com/qmk/qmk_firmware/issues) with your question and the term in question could be added here. Better still, open a pull request with the definition. :)

docs/hardware_avr.md

@@ -8,7 +8,7 @@ If you have not yet you should read the [Keyboard Guidelines](hardware_keyboard_
 
 QMK has a number of features to simplify working with AVR keyboards. For most keyboards you don't have to write a single line of code. To get started run the `util/new_project.sh` script:
 
-```
+```bash
 $ util/new_project.sh my_awesome_keyboard
 ######################################################
 # /keyboards/my_awesome_keyboard project created. To start
@@ -30,7 +30,7 @@ This is where all the custom logic for your keyboard goes. Many keyboards do not
 
 This is the file you define your [Layout Macro(s)](feature_layouts.md) in. At minimum you should have a `#define LAYOUT` for your keyboard that looks something like this:
 
-```
+```c
 #define LAYOUT(          \
       k00, k01, k02,     \
       k10,   k11         \
@@ -57,7 +57,7 @@ At the top of the `config.h` you'll find USB related settings. These control how
 
 Do change the `MANUFACTURER`, `PRODUCT`, and `DESCRIPTION` lines to accurately reflect your keyboard.
 
-```
+```c
 #define VENDOR_ID       0xFEED
 #define PRODUCT_ID      0x6060
 #define DEVICE_VER      0x0001
@@ -66,22 +66,20 @@ Do change the `MANUFACTURER`, `PRODUCT`, and `DESCRIPTION` lines to accurately r
 #define DESCRIPTION     A custom keyboard
 ```
 
-{% hint style='info' %}
-Note: On Windows and macOS the `MANUFACTURER`, `PRODUCT`, and `DESCRIPTION` fields will be displayed in the list of USB devices. On Linux these values will not be visible in `lsusb`, since Linux takes that information from the list published by the USB-IF.
-{% endhint %}
+?> Note: On Windows and macOS the `MANUFACTURER`, `PRODUCT`, and `DESCRIPTION` fields will be displayed in the list of USB devices. ?> On Linux these values will not be visible in lsusb by default, since Linux takes the information from the list maintained by [USB ID Repository](http://www.linux-usb.org/usb-ids.html) by default. lsusb will show the information reported by the device when executed with -v option. It is also present in kernel logs after plugging in the device.
 
 ### Keyboard Matrix Configuration
 
 The next section of the `config.h` file deals with your keyboard's matrix. The first thing you should set is the matrix's size. This is usually, but not always, the same number of rows and columns as the physical key arrangement.
 
-```
+```c
 #define MATRIX_ROWS 2
 #define MATRIX_COLS 3
 ```
 
 Once you've defined the size of your matrix you need to define which pins on your MCU are connected to rows and columns. To do so simply specify the names of those pins:
 
-```
+```c
 #define MATRIX_ROW_PINS { D0, D5 }
 #define MATRIX_COL_PINS { F1, F0, B0 }
 #define UNUSED_PINS
@@ -91,7 +89,7 @@ The number of `MATRIX_ROW_PINS` entries must be the same as the number you assig
 
 Finally, you can specify the direction your diodes point. This can be `COL2ROW`, `ROW2COL`, or `CUSTOM_MATRIX`.
 
-```
+```c
 #define DIODE_DIRECTION COL2ROW
 ```
 
@@ -99,15 +97,14 @@ Finally, you can specify the direction your diodes point. This can be `COL2ROW`,
 
 By default QMK supports backlighting on pins `B5`, `B6`, and `B7`. If you are using one of those you can simply enable it here. For more details see the [Backlight Documentation](feature_backlight.md).
 
-```
+```c
 #define BACKLIGHT_PIN B7
-#define BACKLIGHT_BREATHING
 #define BACKLIGHT_LEVELS 3
+#define BACKLIGHT_BREATHING
+#define BREATHING_PERIOD 6
 ```
 
-{% hint style='info' %}
-You can use backlighting on any pin you like, but you will have to do more work to support that. See the [Backlight Documentation](feature_backlight.md) for more details.
-{% endhint %}
+?> You can use backlighting on any pin you like, but you will have to do more work to support that. See the [Backlight Documentation](feature_backlight.md) for more details.
 
 ### Other Configuration Options
 
@@ -121,7 +118,7 @@ You use the `rules.mk` file to tell QMK what files to build and what features to
 
 These options tell the build system what CPU to build for. Be very careful if you change any of these settings, you can render your keyboard inoperable.
 
-```
+```make
 MCU = atmega32u4
 F_CPU = 16000000
 ARCH = AVR8
@@ -129,26 +126,26 @@ F_USB = $(F_CPU)
 OPT_DEFS += -DINTERRUPT_CONTROL_ENDPOINT
 ```
 
-### Bootloader Size
+### Bootloaders
 
-The bootloader is a special section of your MCU that allows you to upgrade the code stored on the MCU. Think of it like a Rescue Partition for your keyboard. If you are using a teensy 2.0, or a device like the Ergodox EZ that uses the teensy bootloader you should set this to `512`. Most other bootloaders should be set to `4096`, but `1024` and `2048` are other possible values you may encounter.
+The bootloader is a special section of your MCU that allows you to upgrade the code stored on the MCU. Think of it like a Rescue Partition for your keyboard. 
 
-#### Teensy 2.0 Bootloader Example
+#### Teensy Bootloader Example
 
-```
-OPT_DEFS += -DBOOTLOADER_SIZE=512
-```
-
-#### Teensy 2.0++ Bootloader Example
-
-```
-OPT_DEFS += -DBOOTLOADER_SIZE=1024
+```make
+BOOTLOADER = halfkay
 ```
 
 #### Atmel DFU Loader Example
 
+```make
+BOOTLOADER = atmel-dfu
 ```
-OPT_DEFS += -DBOOTLOADER_SIZE=4096
+
+#### Pro Micro Bootloader Example
+
+```make
+BOOTLOADER = caterina
 ```
 
 ### Build Options

docs/hardware_drivers.md

@@ -25,3 +25,11 @@ You can make use of uGFX within QMK to drive character and graphic LCD's, LED ar
 ## WS2812 (AVR Only)
 
 Support for WS2811/WS2812{a,b,c} LED's. For more information see the [RGB Light](feature_rgblight.md) page.
+
+## IS31FL3731
+
+Support for up to 2 drivers. Each driver impliments 2 charlieplex matrices to individually address LEDs using I2C. This allows up to 144 same color LEDs or 32 RGB LEDs. For more information on how to setup the driver see the [RGB Matrix](feature_rgb_matrix.md) page.
+
+## IS31FL3733
+
+Support for up to a single driver with room for expansion. Each driver can control 192 individual LEDs or 64 RGB LEDs. For more information on how to setup the driver see the [RGB Matrix](feature_rgb_matrix.md) page.

docs/hardware_keyboard_guidelines.md

@@ -1,108 +1,120 @@
 # QMK Keyboard Guidelines
 
-We welcome all keyboard projects into QMK, but ask that you try to stick to a couple guidelines that help us keep things organised and consistent.
+Since starting, QMK has grown by leaps and bounds thanks to people like you who contribute to creating and maintaining our community keyboards. As we've grown we've discovered some patterns that work well, and ask that you conform to them to make it easier for other people to benefit from your hard work.
+
 
 ## Naming Your Keyboard/Project
 
-All names should be lowercase alphanumeric, and separated by an underscore (`_`), but not begin with one. Your directory and your `.h` and `.c` files should have exactly the same name. All folders should follow the same format.
+All keyboard names are in lower case, consisting only of letters, numbers, and underscore (`_`). Names may not begin with an underscore. Forward slash (`/`) is used as a sub-folder separation character.
 
-## `readme.md`
+The names `test`, `keyboard`, and `all` are reserved for make commands and may not be used as a keyboard or subfolder name.
 
-All projects need to have a `readme.md` file that explains what the keyboard is, who made it, where it is available, and links to more information. Please follow the [published template](documentation_templates.md#keyboard-readmemd-template).
+Valid Examples:
+
+* `412_64`
+* `chimera_ortho`
+* `clueboard/66/rev3`
+* `planck`
+* `v60_type_r`
+
+## Sub-folders
+
+QMK uses sub-folders both for organization and to share code between revisions of the same keyboard. You can nest folders up to 4 levels deep:
+
+    qmk_firmware/keyboards/top_folder/sub_1/sub_2/sub_3/sub_4
+
+If a sub-folder has a `rules.mk` file it will be considered a compilable keyboard. It will be available in QMK Configurator and tested with `make all`. If you are using a folder to organize several keyboards from the same maker you should not have a `rules.mk` file.
+
+Example:
+
+Clueboard uses sub-folders for both purposes, organization and keyboard revisions.
+
+* [`qmk_firmware`](https://github.com/qmk/qmk_firmware/tree/master)
+  * [`keyboards`](https://github.com/qmk/qmk_firmware/tree/master/keyboards)
+    * [`clueboard`](https://github.com/qmk/qmk_firmware/tree/master/keyboards/clueboard)  ← This is the organization folder, there's no `rules.mk` file
+      * [`60`](https://github.com/qmk/qmk_firmware/tree/master/keyboards/clueboard/60)  ← This is a compilable keyboard, it has a `rules.mk` file
+      * [`66`](https://github.com/qmk/qmk_firmware/tree/master/keyboards/clueboard/66) ← This is also compilable- it uses `DEFAULT_FOLDER` to specify `rev3` as the default revision
+        * [`rev1`](https://github.com/qmk/qmk_firmware/tree/master/keyboards/clueboard/66/rev1) ← compilable: `make clueboard/66/rev1`
+        * [`rev2`](https://github.com/qmk/qmk_firmware/tree/master/keyboards/clueboard/66/rev2) ← compilable: `make clueboard/66/rev2`
+        * [`rev3`](https://github.com/qmk/qmk_firmware/tree/master/keyboards/clueboard/66/rev3) ← compilable: `make clueboard/66/rev3` or `make clueboard/66`
+
+## Keyboard Folder Structure
+
+Your keyboard should be located in `qmk_firmware/keyboards/` and the folder name should be your keyboard's name as described in the previous section. Inside this folder should be several files:
+
+* `readme.md`
+* `info.json`
+* `config.h`
+* `rules.mk`
+* `<keyboard_name>.c`
+* `<keyboard_name>.h`
+
+### `readme.md`
+
+All projects need to have a `readme.md` file that explains what the keyboard is, who made it and where it's available. If applicable, it should also contain links to more information, such as the maker's website. Please follow the [published template](documentation_templates.md#keyboard-readmemd-template).
+
+### `info.json`
+
+This file is used by the [QMK API](https://github.com/qmk/qmk_api). It contains the information [QMK Configurator](https://config.qmk.fm/) needs to display a representation of your keyboard. You can also set metadata here. For more information see the [reference page](reference_info_json.md).
+
+### `config.h`
+
+All projects need to have a `config.h` file that sets things like the matrix size, product name, USB VID/PID, description and other settings. In general, use this file to set essential information and defaults for your keyboard that will always work.
+
+### `rules.mk`
+
+The presence of this file means that the folder is a keyboard target and can be used in `make` commands. This is where you setup the build environment for your keyboard and configure the default set of features.
+
+### `<keyboard_name.c>`
+
+This is where you will write custom code for your keyboard. Typically you will write code to initialize and interface with the hardware in your keyboard. If your keyboard consists of only a key matrix with no LEDs, speakers, or other auxillary hardware this file can be blank.
+
+The following functions are typically defined in this file:
+
+* `void matrix_init_kb(void)`
+* `void matrix_scan_kb(void)`
+* `bool process_record_kb(uint16_t keycode, keyrecord_t *record)`
+* `void led_set_kb(uint8_t usb_led)`
+
+### `<keyboard_name.h>`
+
+This file is used to define the matrix for your keyboard. You should define at least one C macro which translates an array into a matrix representing the physical switch matrix for your keyboard. If it's possible to build your keyboard with multiple layouts you should define additional macros.
+
+If you have only a single layout you should call this macro `LAYOUT`.
+
+When defining multiple layouts you should have a base layout, named `LAYOUT_all`, that supports all possible switch positions on your matrix, even if that layout is impossible to build physically. This is the macro you should use in your `default` keymap. You should then have additional keymaps named `default_<layout>` that use your other layout macros. This will make it easier for people to use the layouts you define.
+
+Layout macro names are entirely lowercase, except for the word `LAYOUT` at the front.
+
+As an example, if you have a 60% PCB that supports ANSI and ISO you might define the following layouts and keymaps:
+
+| Layout Name | Keymap Name | Description |
+|-------------|-------------|-------------|
+| LAYOUT_all | default | A layout that supports both ISO and ANSI |
+| LAYOUT_ansi | default_ansi | An ANSI layout |
+| LAYOUT_iso | default_iso | An ISO layout |
 
 ## Image/Hardware Files
 
-In an effort to keep the repo size down, we're no longer accepting images of any format in the repo, with few exceptions. Hosting them elsewhere (imgur) and linking them in the `readme.md` is the preferred method.
+In an effort to keep the repo size down we're no longer accepting binary files of any format, with few exceptions. Hosting them elsewhere (such as <https://imgur.com>) and linking them in the `readme.md` is preferred.
 
-Any sort of hardware file (plate, case, pcb) can't be stored in qmk_firmware, but we have the [qmk.fm repo](https://github.com/qmk/qmk.fm) where such files (as well as in-depth info) can be stored and viewed on [qmk.fm](http://qmk.fm). Downloadable files are stored in `/<keyboard>/` (name follows the same format as above) which are served at `http://qmk.fm/<keyboard>/`, and pages are generated from `/_pages/<keyboard>/` which are served at the same location (.md files are generated into .html files through Jekyll). Check out the `lets_split` directory for an example.
+Hardware files (such as plates, cases, pcb) can be contributed to the [qmk.fm repo](https://github.com/qmk/qmk.fm) and they will be made available on [qmk.fm](http://qmk.fm). Downloadable files are stored in `/<keyboard>/` (name follows the same format as above) which are served at `http://qmk.fm/<keyboard>/`, and pages are generated from `/_pages/<keyboard>/` which are served at the same location (.md files are generated into .html files through Jekyll). Check out the `lets_split` folder for an example.
 
-## Keyboard Metadata
+## Keyboard Defaults
 
-As QMK grows so does the ecosystem surrounding QMK. To make it easier for projects in that ecosystem to tie into QMK as we make changes we are developing a metadata system to expose information about keyboards in QMK.
+Given the amount of functionality that QMK exposes it's very easy to confuse new users. When putting together the default firmware for your keyboard we recommend limiting your enabled features and options to the minimal set needed to support your hardware. Recommendations for specific features follow.
 
-You can create `info.json` files at every level under `qmk_firmware/keyboards/<name>` to specify this metadata. These files are combined, with more specific files overriding keys in less specific files. This means you do not need to duplicate your metadata information. For example, `qmk_firmware/keyboards/clueboard/info.json` specifies `manufacturer` and `maintainer`, while `qmk_firmware/keyboards/clueboard/66/info.json` specifies more specific information about Clueboard 66%.
+### Bootmagic and Command
 
-### `info.json` Format
+[Bootmagic](feature_bootmagic.md) and [Command](feature_command.md) are two related features that allow a user to control their keyboard in non-obvious ways. We recommend you think long and hard about if you're going to enable either feature, and how you will expose this functionality. Keep in mind that users who want this functionality can enable it in their personal keymaps without affecting all the novice users who may be using your keyboard as their first programmable board.
 
-The `info.json` file is a JSON formatted dictionary with the following keys available to be set. You do not have to set all of them, merely the keys that apply to your keyboard.
+By far the most common problem new users encounter is accidentally triggering Bootmagic while they're plugging in their keyboard. They're holding the keyboard by the bottom, unknowingly pressing in alt and spacebar, and then they find that these keys have been swapped on them. We recommend leaving this feature disabled by default, but if you do turn it on consider setting `BOOTMAGIC_KEY_SALT` to a key that is hard to press while plugging your keyboard in.
 
-* `keyboard_name`
-  * A free-form text string describing the keyboard.
-  * Example: `Clueboard 66%`
-* `manufacturer`
-  * A free-form text string naming the manufacturer.
-  * Example: `Clueboard`
-* `identifier`
-  * The Vendor, Product, and Revision ID's joined by a :
-  * Example: `c1ed:2370:0001`
-* `url`
-  * A URL to the keyboard's product page, [QMK.fm/keyboards](https://qmk.fm/keyboards) page, or other page describing information about the keyboard.
-* `processor`
-  * The MCU or CPU this keyboard uses.
-  * Example: `atmega32u4` or `stm32f303`
-* `bootloader`
-  * What bootloader this keyboard uses. Available options:
-    * `atmel-dfu`
-    * `kiibohd-dfu-util`
-    * `lufa-dfu`
-    * `qmk-dfu`
-    * `stm32-dfu-util`
-    * (FIXME: This list is incomplete.)
-* `maintainer`
-  * GitHub username of the maintainer, or `qmk` for community maintained boards
-* `width`
-  * Width of the board in Key Units
-* `height`
-  * Height of the board in Key Units
-* `layouts`
-  * Physical Layout representations. See the next section for more detail.
+If your keyboard does not have 2 shift keys you should provide a working default for `IS_COMMAND`, even when you have set `COMMAND_ENABLE = no`. This will give your users a default to conform to if they do enable Command.
 
-#### Layout Format
+## Custom Keyboard Programming
 
-Within our `info.json` file the `layouts` portion of the dictionary contains several nested dictionaries. The outer layer consists of QMK layout macros, for example `LAYOUT_ansi` or `LAYOUT_iso`. Within each layout macro are keys for `width`, `height`, and `key_count`, each of which should be self-explanatory.
-
-* `width`
-  * Optional: The width of the layout in Key Units
-* `height`
-  * Optional: The height of the layout in Key Units
-* `key_count`
-  * **Required**: The number of keys in this layout
-* `layout`
-  * A list of Key Dictionaries describing the physical layout. See the next section for more details.
-
-#### Key Dictionary Format
-
-Each Key Dictionary in a layout describes the physical properties of a key. If you are familiar with the Raw Code for <http://keyboard-layout-editor.com> you will find many of the concepts the same. We re-use the same key names and layout choices wherever possible, but unlike keyboard-layout-editor each key is stateless, inheriting no properties from the keys that came before it.
-
-All key positions and rotations are specified in relation to the top-left corner of the keyboard, and the top-left corner of each key.
-
-* `X`
-  * **Required**: The absolute position of the key in the horizontal axis, in Key Units.
-* `Y`
-  * **Required**: The absolute position of the key in the vertical axis, in Key Units.
-* `W`
-  * The width of the key, in Key Units. Ignored if `ks` is provided. Default: `1`
-* `H`
-  * The height of the key, in Key Units. Ignored if `ks` is provided. Default: `1`
-* `R`
-  * How many degrees clockwise to rotate the key.
-* `RX`
-  * The absolute position of the point to rotate the key around in the horizontal axis. Default: `x`
-* `RY`
-  * The absolute position of the point to rotate the key around in the vertical axis. Default: `y`
-* `KS`
-  * Key Shape: define a polygon by providing a list of points, in Key Units.
-  * **Important**: These are relative to the top-left of the key, not absolute.
-  * Example ISO Enter: `[ [0,0], [1.5,0], [1.5,2], [0.25,2], [0.25,1], [0,1], [0,0] ]`
-
-### How is the Metadata Exposed?
-
-This metadata is primarily used in two ways:
-
-* To allow web-based configurators to dynamically generate UI
-* To support the new `make keyboard:keymap:qmk` target, which bundles this metadata up with the firmware to allow QMK Toolbox to be smarter.
-
-Configurator authors can see the [QMK Compiler](https://docs.compile.qmk.fm/api_docs.html) docs for more information on using the JSON API.
+As documented on [Customizing Functionality](custom_quantum_functions.md) you can define custom functions for your keyboard. Please keep in mind that your users may want to customize that behavior as well, and make it possible for them to do that. If you are providing a custom function, for example `process_record_kb()`, make sure that your function calls the `_user()` version of the call too. You should also take into account the return value of the `_user()` version, and only run your custom code if the user returns `true`.
 
 ## Non-Production/Handwired Projects
 

docs/how_keyboards_work.md

@@ -27,17 +27,17 @@ This usually happens with a periodic scan of key presses. This speed often is li
 
 ## 2. What the Firmware Sends
 
-The [HID specification](http://www.usb.org/developers/hidpage/Hut1_12v2.pdf) tells what a keyboard can actually send through USB to have a chance to be properly recognised. This includes a pre-defined list of scancodes which are simple numbers from `0x00` to `0xE7`. The firmware assigns a scancode to each key of the keyboard.
+The [HID specification](https://www.usb.org/sites/default/files/documents/hut1_12v2.pdf) tells what a keyboard can actually send through USB to have a chance to be properly recognised. This includes a pre-defined list of scancodes which are simple numbers from `0x00` to `0xE7`. The firmware assigns a scancode to each key of the keyboard.
 
-The firmware does not send actually letters or characters, but only scancodes.
-Thus, by modifying the firmware, you only can modify what scancode is sent over
+The firmware does not send actual letters or characters, but only scancodes.
+Thus, by modifying the firmware, you can only modify what scancode is sent over
 USB for a given key.
 
 ## 3. What the Operating System Does
 
 Once the keycode reaches the operating system, a piece of software has to have
 it match an actual character thanks to a keyboard layout. For example, if your
-layout is set to QWERTY, a sample of the matching table is as follow:
+layout is set to QWERTY, a sample of the matching table is as follows:
 
 | keycode | character |
 |---------|-----------|
@@ -55,11 +55,11 @@ As the layout is generally fixed (unless you create your own), the firmware can
 
 ## List of Characters You Can Send
 
-Putting aside shortcuts, having a limited set of keycodes mapped to a limited layout means that **the list of characters you can assign to a given key only is the ones present in the layout**.
+Putting aside shortcuts, having a limited set of keycodes mapped to a limited layout means that **the list of characters you can assign to a given key are only the ones present in the layout**.
 
-For example, this means that if you have a QWERTY US layout, and you want to assign 1 key to produce `€` (euro currency symbol), you are unable to do so, because the QWERTY US layout does not have such mapping. You could fix that by using a QWERTY UK layout, or a QWERTY US International.
+For example, this means that if you have a QWERTY US layout, and you want to assign one key to produce `€` (euro currency symbol), you are unable to do so, because the QWERTY US layout does not have such mapping. You could fix that by using a QWERTY UK layout, or a QWERTY US International.
 
-You may wonder why a keyboard layout containing all of Unicode is not devised then? The limited number of keycode available through USB simply disallow such a thing.
+You may wonder why a keyboard layout containing all of Unicode is not devised then? The limited number of keycodes available through USB simply disallows such a thing.
 
 ## How to (Maybe) Enter Unicode Characters
 

docs/i2c_driver.md

@@ -0,0 +1,86 @@
+# I2C Master Driver
+
+The I2C Master drivers used in QMK have a set of common functions to allow portability between MCUs.
+
+## Available functions
+
+|Function                                                                                                          |Description                                                                                                                                                                  |
+|------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+|`void i2c_init(void);`                                                                                            |Initializes the I2C driver. This function should be called once before any transaction is initiated.                                                                         |
+|`uint8_t i2c_start(uint8_t address);`                                                                             |Starts an I2C transaction. Address is the 7-bit slave address without the direction bit.                                                                                     |
+|`uint8_t i2c_transmit(uint8_t address, uint8_t* data, uint16_t length, uint16_t timeout);`                        |Transmit data over I2C. Address is the 7-bit slave address without the direction. Returns status of transaction.                                                             |
+|`uint8_t i2c_receive(uint8_t address, uint8_t* data, uint16_t length, uint16_t timeout);`                         |Receive data over I2C. Address is the 7-bit slave address without the direction. Saves number of bytes specified by `length` in `data` array. Returns status of transaction. |
+|`uint8_t i2c_writeReg(uint8_t devaddr, uint8_t regaddr, uint8_t* data, uint16_t length, uint16_t timeout);`       |Same as the `i2c_transmit` function but `regaddr` sets where in the slave the data will be written.                                                                          |
+|`uint8_t i2c_readReg(uint8_t devaddr, uint8_t regaddr, uint8_t* data, uint16_t length, uint16_t timeout);`        |Same as the `i2c_receive` function but `regaddr` sets from where in the slave the data will be read.                                                                         |
+|`uint8_t i2c_stop(uint16_t timeout);`                                                                             |Stops the I2C driver.                                                                                                                                                        |
+
+### Function Return
+
+All the above functions, except `void i2c_init(void);` return the following truth table:
+
+|Return Value   |Description                                        |
+|---------------|---------------------------------------------------|
+|0              |Operation executed successfully.                   |
+|-1             |Operation failed.                                  |
+|-2             |Operation timed out.                               |
+
+
+## AVR
+
+### Configuration
+
+The following defines can be used to configure the I2C master driver.
+
+|Variable          |Description                                        |Default|
+|------------------|---------------------------------------------------|-------|
+|`F_SCL`           |Clock frequency in Hz                              |400KHz |
+|`Prescaler`       |Divides master clock to aid in I2C clock selection |1      |
+
+AVRs usually have set GPIO which turn into I2C pins, therefore no further configuration is required.
+
+## ARM
+
+For ARM the Chibios I2C HAL driver is under the hood.
+This section assumes an STM32 MCU.
+
+### Configuration
+
+The configuration for ARM MCUs can be quite complex as often there are multiple I2C drivers which can be assigned to a variety of ports.
+
+Firstly the `mcuconf.h` file must be setup to enable the necessary hardware drivers.
+
+|Variable                      |Description                                                                        |Default|
+|------------------------------|------------------------------------------------------------------------------------|-------|
+|`#STM32_I2C_USE_XXX`          |Enable/Disable the hardware driver XXX (each driver should be explicitly listed)    |FALSE  |
+|`#STM32_I2C_BUSY_TIMEOUT`     |Time in ms until the I2C command is aborted if no response is received              |50     |
+|`#STM32_I2C_XXX_IRQ_PRIORITY` |Interrupt priority for hardware driver XXX (THIS IS AN EXPERT SETTING)              |10     |
+|`#STM32_I2C_USE_DMA`          |Enable/Disable the ability of the MCU to offload the data transfer to the DMA unit  |TRUE   |
+|`#STM32_I2C_XXX_DMA_PRIORITY` |Priority of DMA unit for hardware driver XXX (THIS IS AN EXPERT SETTING)            |1      |
+
+Secondly, in the `halconf.h` file, `#define HAL_USE_I2C` must be set to `TRUE`. This allows ChibiOS to load its I2C driver.
+
+Lastly, we need to assign the correct GPIO pins depending on the I2C hardware driver we want to use.
+
+By default the I2C1 hardware driver is assumed to be used. If another hardware driver is used,  `#define I2C_DRIVER I2CDX` should be added to the `config.h` file with X being the number of hardware driver used. For example is I2C3 is enabled, the `config.h` file should contain `#define I2C_DRIVER I2CD3`. This aligns the QMK I2C driver with the Chibios I2C driver.
+
+STM32 MCUs allows a variety of pins to be configured as I2C pins depending on the hardware driver used. By default B6 and B7 are set to I2C. You can use these defines to set your i2c pins:
+
+| Variable    | Description                                  | Default |
+|-------------|----------------------------------------------|---------|
+| `I2C1_BANK` | The bank of pins (`GPIOA`, `GPIOB`, `GPIOC`) | `GPIOB` |
+| `I2C1_SCL`  | The pin number for the SCL pin (0-9)         | `6`     |
+| `I2C1_SDA`  | The pin number for the SDA pin (0-9)         | `7`     |
+
+You can also overload the `void i2c_init(void)` function, which has a weak attribute. If you do this the configuration variables above will not be used. Please consult the datasheet of your MCU for the available GPIO configurations. The following is an example initialization function:
+
+```C
+void i2c_init(void)
+{
+  setPinInput(B6); // Try releasing special pins for a short time
+  setPinInput(B7);
+  wait_ms(10); // Wait for the release to happen
+
+  palSetPadMode(GPIOB, 6, PAL_MODE_ALTERNATE(4) | PAL_STM32_OTYPE_OPENDRAIN | PAL_STM32_PUPDR_PULLUP); // Set B6 to I2C function
+  palSetPadMode(GPIOB, 7, PAL_MODE_ALTERNATE(4) | PAL_STM32_OTYPE_OPENDRAIN | PAL_STM32_PUPDR_PULLUP); // Set B7 to I2C function
+}
+```

docs/index.html

@@ -0,0 +1,47 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title>QMK Firmware</title>
+  <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
+  <meta name="description" content="Description">
+  <meta name="viewport" content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0">
+  <link rel="stylesheet" href="//unpkg.com/docsify/lib/themes/vue.css" title="light">
+  <link rel="stylesheet" href="qmk.css" title="dark" disabled>
+  <link rel="stylesheet" href="sidebar.css" />
+</head>
+<body>
+  <div id="app"></div>
+  <script>
+    window.$docsify = {
+      name: 'QMK Firmware',
+      nameLink: 'https://qmk.fm/',
+      repo: 'qmk/qmk_firmware',
+      loadSidebar: '_summary.md',
+      auto2top: true,
+      formatUpdated: '{YYYY}/{MM}/{DD} {HH}:{mm}',
+      search: {
+        paths: 'auto',
+        placeholder: 'Search Documentation...',
+        noData: 'We could not find any documents matching your search.',
+        depth: 6
+      },
+      fallbackLanguages: ['zh']
+    }
+  </script>
+  <script src="//unpkg.com/docsify/lib/docsify.min.js"></script>
+  <script src="//unpkg.com/docsify/lib/plugins/search.min.js"></script>
+  <script src="//unpkg.com/docsify/lib/plugins/emoji.min.js"></script>
+  <script src="//unpkg.com/prismjs/components/prism-bash.min.js"></script>
+  <script src="//unpkg.com/prismjs/components/prism-c.min.js"></script>
+  <script src="//unpkg.com/prismjs/components/prism-cpp.min.js"></script>
+  <script src="//unpkg.com/prismjs/components/prism-json.min.js"></script>
+  <script src="//unpkg.com/prismjs/components/prism-makefile.min.js"></script>
+  <script>
+    // Register the offline cache worker
+    if (typeof navigator.serviceWorker !== 'undefined') {
+      navigator.serviceWorker.register('sw.js')
+    }
+  </script>
+</body>
+</html>

docs/internals_defines.md

@@ -0,0 +1,78 @@
+# group `defines` {#group__defines}
+
+## Summary
+
+ Members                        | Descriptions                                
+--------------------------------|---------------------------------------------
+`define `[`SYSEX_BEGIN`](#group__defines_1ga1a3c39bb790dda8a368c4247caabcf79)            | 
+`define `[`SYSEX_END`](#group__defines_1ga753706d1d28e6f96d7caf1973e80feed)            | 
+`define `[`MIDI_STATUSMASK`](#group__defines_1gab78a1c818a5f5dab7a8946543f126c69)            | 
+`define `[`MIDI_CHANMASK`](#group__defines_1ga239edc0a6f8405d3a8f2804f1590b909)            | 
+`define `[`MIDI_CC`](#group__defines_1ga45f116a1daab76b3c930c2cecfaef215)            | 
+`define `[`MIDI_NOTEON`](#group__defines_1gafd416f27bf3590868c0c1f55c30be4c7)            | 
+`define `[`MIDI_NOTEOFF`](#group__defines_1gabed24bea2d989fd655e2ef2ad0765adc)            | 
+`define `[`MIDI_AFTERTOUCH`](#group__defines_1ga3a322d8cfd53576a2e167c1840551b0f)            | 
+`define `[`MIDI_PITCHBEND`](#group__defines_1gabcc799504e8064679bca03f232223af4)            | 
+`define `[`MIDI_PROGCHANGE`](#group__defines_1gaefb3f1595ffbb9db66b46c2c919a3d42)            | 
+`define `[`MIDI_CHANPRESSURE`](#group__defines_1gaeb3281cc7fcd0daade8ed3d2dfc33dbe)            | 
+`define `[`MIDI_CLOCK`](#group__defines_1gafa5e4e295aafd15ab7893344599b3b89)            | 
+`define `[`MIDI_TICK`](#group__defines_1ga3b99408ff864613765d4c3c2ceb52aa7)            | 
+`define `[`MIDI_START`](#group__defines_1ga8233631c85823aa546f932ad8975caa4)            | 
+`define `[`MIDI_CONTINUE`](#group__defines_1gab24430f0081e27215b0da84dd0ee745c)            | 
+`define `[`MIDI_STOP`](#group__defines_1ga3af9271d4b1f0d22904a0b055f48cf62)            | 
+`define `[`MIDI_ACTIVESENSE`](#group__defines_1gacd88ed42dba52bb4b2052c5656362677)            | 
+`define `[`MIDI_RESET`](#group__defines_1ga02947f30ca62dc332fdeb10c5868323b)            | 
+`define `[`MIDI_TC_QUARTERFRAME`](#group__defines_1gaaa072f33590e236d1bfd8f28e833ae31)            | 
+`define `[`MIDI_SONGPOSITION`](#group__defines_1ga412f6ed33a2150051374bee334ee1705)            | 
+`define `[`MIDI_SONGSELECT`](#group__defines_1gafcab254838b028365ae0259729e72c4e)            | 
+`define `[`MIDI_TUNEREQUEST`](#group__defines_1ga8100b907b8c0a84e58b1c53dcd9bd795)            | 
+`define `[`SYSEX_EDUMANUFID`](#group__defines_1ga5ef855ed955b00a2239ca16afbeb164f)            | 
+
+## Members
+
+#### `define `[`SYSEX_BEGIN`](#group__defines_1ga1a3c39bb790dda8a368c4247caabcf79) {#group__defines_1ga1a3c39bb790dda8a368c4247caabcf79}
+
+#### `define `[`SYSEX_END`](#group__defines_1ga753706d1d28e6f96d7caf1973e80feed) {#group__defines_1ga753706d1d28e6f96d7caf1973e80feed}
+
+#### `define `[`MIDI_STATUSMASK`](#group__defines_1gab78a1c818a5f5dab7a8946543f126c69) {#group__defines_1gab78a1c818a5f5dab7a8946543f126c69}
+
+#### `define `[`MIDI_CHANMASK`](#group__defines_1ga239edc0a6f8405d3a8f2804f1590b909) {#group__defines_1ga239edc0a6f8405d3a8f2804f1590b909}
+
+#### `define `[`MIDI_CC`](#group__defines_1ga45f116a1daab76b3c930c2cecfaef215) {#group__defines_1ga45f116a1daab76b3c930c2cecfaef215}
+
+#### `define `[`MIDI_NOTEON`](#group__defines_1gafd416f27bf3590868c0c1f55c30be4c7) {#group__defines_1gafd416f27bf3590868c0c1f55c30be4c7}
+
+#### `define `[`MIDI_NOTEOFF`](#group__defines_1gabed24bea2d989fd655e2ef2ad0765adc) {#group__defines_1gabed24bea2d989fd655e2ef2ad0765adc}
+
+#### `define `[`MIDI_AFTERTOUCH`](#group__defines_1ga3a322d8cfd53576a2e167c1840551b0f) {#group__defines_1ga3a322d8cfd53576a2e167c1840551b0f}
+
+#### `define `[`MIDI_PITCHBEND`](#group__defines_1gabcc799504e8064679bca03f232223af4) {#group__defines_1gabcc799504e8064679bca03f232223af4}
+
+#### `define `[`MIDI_PROGCHANGE`](#group__defines_1gaefb3f1595ffbb9db66b46c2c919a3d42) {#group__defines_1gaefb3f1595ffbb9db66b46c2c919a3d42}
+
+#### `define `[`MIDI_CHANPRESSURE`](#group__defines_1gaeb3281cc7fcd0daade8ed3d2dfc33dbe) {#group__defines_1gaeb3281cc7fcd0daade8ed3d2dfc33dbe}
+
+#### `define `[`MIDI_CLOCK`](#group__defines_1gafa5e4e295aafd15ab7893344599b3b89) {#group__defines_1gafa5e4e295aafd15ab7893344599b3b89}
+
+#### `define `[`MIDI_TICK`](#group__defines_1ga3b99408ff864613765d4c3c2ceb52aa7) {#group__defines_1ga3b99408ff864613765d4c3c2ceb52aa7}
+
+#### `define `[`MIDI_START`](#group__defines_1ga8233631c85823aa546f932ad8975caa4) {#group__defines_1ga8233631c85823aa546f932ad8975caa4}
+
+#### `define `[`MIDI_CONTINUE`](#group__defines_1gab24430f0081e27215b0da84dd0ee745c) {#group__defines_1gab24430f0081e27215b0da84dd0ee745c}
+
+#### `define `[`MIDI_STOP`](#group__defines_1ga3af9271d4b1f0d22904a0b055f48cf62) {#group__defines_1ga3af9271d4b1f0d22904a0b055f48cf62}
+
+#### `define `[`MIDI_ACTIVESENSE`](#group__defines_1gacd88ed42dba52bb4b2052c5656362677) {#group__defines_1gacd88ed42dba52bb4b2052c5656362677}
+
+#### `define `[`MIDI_RESET`](#group__defines_1ga02947f30ca62dc332fdeb10c5868323b) {#group__defines_1ga02947f30ca62dc332fdeb10c5868323b}
+
+#### `define `[`MIDI_TC_QUARTERFRAME`](#group__defines_1gaaa072f33590e236d1bfd8f28e833ae31) {#group__defines_1gaaa072f33590e236d1bfd8f28e833ae31}
+
+#### `define `[`MIDI_SONGPOSITION`](#group__defines_1ga412f6ed33a2150051374bee334ee1705) {#group__defines_1ga412f6ed33a2150051374bee334ee1705}
+
+#### `define `[`MIDI_SONGSELECT`](#group__defines_1gafcab254838b028365ae0259729e72c4e) {#group__defines_1gafcab254838b028365ae0259729e72c4e}
+
+#### `define `[`MIDI_TUNEREQUEST`](#group__defines_1ga8100b907b8c0a84e58b1c53dcd9bd795) {#group__defines_1ga8100b907b8c0a84e58b1c53dcd9bd795}
+
+#### `define `[`SYSEX_EDUMANUFID`](#group__defines_1ga5ef855ed955b00a2239ca16afbeb164f) {#group__defines_1ga5ef855ed955b00a2239ca16afbeb164f}
+

docs/internals_gpio_control.md

@@ -0,0 +1,23 @@
+# GPIO Control
+
+QMK has a GPIO control abstraction layer which is microcontroller agnostic. This is done to allow easy access to pin control across different platforms.
+
+## Functions
+
+The following functions can provide basic control of GPIOs and are found in `quantum/quantum.h`.
+
+|Function              |Description                                                       |
+|----------------------|------------------------------------------------------------------|
+|`setPinInput(pin)`    |Set pin as input with high impedance (High-Z)                     |
+|`setPinInputHigh(pin)`|Set pin as input with build in pull-up                            |
+|`setPinInputLow(pin)` |Set pin as input with build in pull-down (Supported only on STM32)|
+|`setPinOutput(pin)`   |Set pin as output                                                 |
+|`writePinHigh(pin)`   |Set pin level as high, assuming it is an output                   |
+|`writePinLow(pin)`    |Set pin level as low, assuming it is an output                    |
+|`writePin(pin, level)`|Set pin level, assuming it is an output                           |
+|`readPin(pin)`        |Returns the level of the pin                                      |
+
+## Advanced Settings
+
+Each microcontroller can have multiple advanced settings regarding its GPIO. This abstraction layer does not limit the use of architecture-specific functions. Advanced users should consult the datasheet of their desired device and include any needed libraries. For AVR, the standard avr/io.h library is used; for STM32, the ChibiOS [PAL library](http://chibios.sourceforge.net/docs3/hal/group___p_a_l.html) is used.
+

docs/internals_input_callback_reg.md

@@ -0,0 +1,169 @@
+# group `input_callback_reg` {#group__input__callback__reg}
+
+These are the functions you use to register your input callbacks.
+
+The functions are called when the appropriate midi message is matched on the associated device's input.
+
+## Summary
+
+ Members                        | Descriptions                                
+--------------------------------|---------------------------------------------
+`public void `[`midi_register_cc_callback`](#group__input__callback__reg_1ga64ab672abbbe393c9c4a83110c8df718)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_three_byte_func_t func)`            | Register a control change message (cc) callback.
+`public void `[`midi_register_noteon_callback`](#group__input__callback__reg_1ga3962f276c17618923f1152779552103e)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_three_byte_func_t func)`            | Register a note on callback.
+`public void `[`midi_register_noteoff_callback`](#group__input__callback__reg_1gac847b66051bd6d53b762958be0ec4c6d)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_three_byte_func_t func)`            | Register a note off callback.
+`public void `[`midi_register_aftertouch_callback`](#group__input__callback__reg_1gaa95bc901bd9edff956a667c9a69dd01f)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_three_byte_func_t func)`            | Register an after touch callback.
+`public void `[`midi_register_pitchbend_callback`](#group__input__callback__reg_1ga071a28f02ba14f53de219be70ebd9a48)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_three_byte_func_t func)`            | Register a pitch bend callback.
+`public void `[`midi_register_songposition_callback`](#group__input__callback__reg_1gaf2adfd79637f3553d8f26deb1ca22ed6)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_three_byte_func_t func)`            | Register a song position callback.
+`public void `[`midi_register_progchange_callback`](#group__input__callback__reg_1gae6ba1a35a4cde9bd15dd42f87401d127)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_two_byte_func_t func)`            | Register a program change callback.
+`public void `[`midi_register_chanpressure_callback`](#group__input__callback__reg_1ga39b31f1f4fb93917ce039b958f21b4f5)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_two_byte_func_t func)`            | Register a channel pressure callback.
+`public void `[`midi_register_songselect_callback`](#group__input__callback__reg_1gaf9aafc76a2dc4b9fdbb4106cbda6ce72)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_two_byte_func_t func)`            | Register a song select callback.
+`public void `[`midi_register_tc_quarterframe_callback`](#group__input__callback__reg_1ga0a119fada2becc628cb15d753b257e6e)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_two_byte_func_t func)`            | Register a tc quarter frame callback.
+`public void `[`midi_register_realtime_callback`](#group__input__callback__reg_1ga764f440e857b89084b1a07f9da2ff93a)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_one_byte_func_t func)`            | Register a realtime callback.
+`public void `[`midi_register_tunerequest_callback`](#group__input__callback__reg_1gae40ff3ce20bda79fef87da24b8321cb1)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_one_byte_func_t func)`            | Register a tune request callback.
+`public void `[`midi_register_sysex_callback`](#group__input__callback__reg_1ga63ce9631b025785c1848d0122d4c4c48)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_sysex_func_t func)`            | Register a sysex callback.
+`public void `[`midi_register_fallthrough_callback`](#group__input__callback__reg_1ga7ed189164aa9682862b3181153afbd94)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_var_byte_func_t func)`            | Register fall through callback.
+`public void `[`midi_register_catchall_callback`](#group__input__callback__reg_1ga9dbfed568d047a6cd05708f11fe39e99)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_var_byte_func_t func)`            | Register a catch all callback.
+
+## Members
+
+#### `public void `[`midi_register_cc_callback`](#group__input__callback__reg_1ga64ab672abbbe393c9c4a83110c8df718)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_three_byte_func_t func)` {#group__input__callback__reg_1ga64ab672abbbe393c9c4a83110c8df718}
+
+Register a control change message (cc) callback.
+
+#### Parameters
+* `device` the device associate with 
+
+* `func` the callback function to register
+
+#### `public void `[`midi_register_noteon_callback`](#group__input__callback__reg_1ga3962f276c17618923f1152779552103e)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_three_byte_func_t func)` {#group__input__callback__reg_1ga3962f276c17618923f1152779552103e}
+
+Register a note on callback.
+
+#### Parameters
+* `device` the device associate with 
+
+* `func` the callback function to register
+
+#### `public void `[`midi_register_noteoff_callback`](#group__input__callback__reg_1gac847b66051bd6d53b762958be0ec4c6d)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_three_byte_func_t func)` {#group__input__callback__reg_1gac847b66051bd6d53b762958be0ec4c6d}
+
+Register a note off callback.
+
+#### Parameters
+* `device` the device associate with 
+
+* `func` the callback function to register
+
+#### `public void `[`midi_register_aftertouch_callback`](#group__input__callback__reg_1gaa95bc901bd9edff956a667c9a69dd01f)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_three_byte_func_t func)` {#group__input__callback__reg_1gaa95bc901bd9edff956a667c9a69dd01f}
+
+Register an after touch callback.
+
+#### Parameters
+* `device` the device associate with 
+
+* `func` the callback function to register
+
+#### `public void `[`midi_register_pitchbend_callback`](#group__input__callback__reg_1ga071a28f02ba14f53de219be70ebd9a48)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_three_byte_func_t func)` {#group__input__callback__reg_1ga071a28f02ba14f53de219be70ebd9a48}
+
+Register a pitch bend callback.
+
+#### Parameters
+* `device` the device associate with 
+
+* `func` the callback function to register
+
+#### `public void `[`midi_register_songposition_callback`](#group__input__callback__reg_1gaf2adfd79637f3553d8f26deb1ca22ed6)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_three_byte_func_t func)` {#group__input__callback__reg_1gaf2adfd79637f3553d8f26deb1ca22ed6}
+
+Register a song position callback.
+
+#### Parameters
+* `device` the device associate with 
+
+* `func` the callback function to register
+
+#### `public void `[`midi_register_progchange_callback`](#group__input__callback__reg_1gae6ba1a35a4cde9bd15dd42f87401d127)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_two_byte_func_t func)` {#group__input__callback__reg_1gae6ba1a35a4cde9bd15dd42f87401d127}
+
+Register a program change callback.
+
+#### Parameters
+* `device` the device associate with 
+
+* `func` the callback function to register
+
+#### `public void `[`midi_register_chanpressure_callback`](#group__input__callback__reg_1ga39b31f1f4fb93917ce039b958f21b4f5)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_two_byte_func_t func)` {#group__input__callback__reg_1ga39b31f1f4fb93917ce039b958f21b4f5}
+
+Register a channel pressure callback.
+
+#### Parameters
+* `device` the device associate with 
+
+* `func` the callback function to register
+
+#### `public void `[`midi_register_songselect_callback`](#group__input__callback__reg_1gaf9aafc76a2dc4b9fdbb4106cbda6ce72)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_two_byte_func_t func)` {#group__input__callback__reg_1gaf9aafc76a2dc4b9fdbb4106cbda6ce72}
+
+Register a song select callback.
+
+#### Parameters
+* `device` the device associate with 
+
+* `func` the callback function to register
+
+#### `public void `[`midi_register_tc_quarterframe_callback`](#group__input__callback__reg_1ga0a119fada2becc628cb15d753b257e6e)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_two_byte_func_t func)` {#group__input__callback__reg_1ga0a119fada2becc628cb15d753b257e6e}
+
+Register a tc quarter frame callback.
+
+#### Parameters
+* `device` the device associate with 
+
+* `func` the callback function to register
+
+#### `public void `[`midi_register_realtime_callback`](#group__input__callback__reg_1ga764f440e857b89084b1a07f9da2ff93a)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_one_byte_func_t func)` {#group__input__callback__reg_1ga764f440e857b89084b1a07f9da2ff93a}
+
+Register a realtime callback.
+
+The callback will be called for all of the real time message types.
+
+#### Parameters
+* `device` the device associate with 
+
+* `func` the callback function to register
+
+#### `public void `[`midi_register_tunerequest_callback`](#group__input__callback__reg_1gae40ff3ce20bda79fef87da24b8321cb1)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_one_byte_func_t func)` {#group__input__callback__reg_1gae40ff3ce20bda79fef87da24b8321cb1}
+
+Register a tune request callback.
+
+#### Parameters
+* `device` the device associate with 
+
+* `func` the callback function to register
+
+#### `public void `[`midi_register_sysex_callback`](#group__input__callback__reg_1ga63ce9631b025785c1848d0122d4c4c48)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_sysex_func_t func)` {#group__input__callback__reg_1ga63ce9631b025785c1848d0122d4c4c48}
+
+Register a sysex callback.
+
+#### Parameters
+* `device` the device associate with 
+
+* `func` the callback function to register
+
+#### `public void `[`midi_register_fallthrough_callback`](#group__input__callback__reg_1ga7ed189164aa9682862b3181153afbd94)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_var_byte_func_t func)` {#group__input__callback__reg_1ga7ed189164aa9682862b3181153afbd94}
+
+Register fall through callback.
+
+This is only called if a more specific callback is not matched and called. For instance, if you don't register a note on callback but you get a note on message the fall through callback will be called, if it is registered.
+
+#### Parameters
+* `device` the device associate with 
+
+* `func` the callback function to register
+
+#### `public void `[`midi_register_catchall_callback`](#group__input__callback__reg_1ga9dbfed568d047a6cd05708f11fe39e99)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_var_byte_func_t func)` {#group__input__callback__reg_1ga9dbfed568d047a6cd05708f11fe39e99}
+
+Register a catch all callback.
+
+If registered, the catch all callback is called for every message that is matched, even if a more specific or the fallthrough callback is registered.
+
+#### Parameters
+* `device` the device associate with 
+
+* `func` the callback function to register
+

docs/internals_midi_device.md

@@ -0,0 +1,143 @@
+# group `midi_device` {#group__midi__device}
+
+You use the functions when you are implementing your own midi device.
+
+You set a send function to actually send bytes via your device, this method is called when you call a send function with this device, for instance midi_send_cc
+
+You use the midi_device_input to process input data from the device and pass it through the device's associated callbacks.
+
+You use the midi_device_set_pre_input_process_func if you want to have a function called at the beginning of the device's process function, generally to poll for input and pass that into midi_device_input
+
+## Summary
+
+ Members                        | Descriptions                                
+--------------------------------|---------------------------------------------
+`define `[`MIDI_INPUT_QUEUE_LENGTH`](#group__midi__device_1ga4aaa419caebdca2bbdfc1331e79781a8)            | 
+`enum `[`input_state_t`](#group__midi__device_1gac203e877d3df4275ceb8e7180a61f621)            | 
+`public void `[`midi_device_input`](#group__midi__device_1gad8d3db8eb35d9cfa51ef036a0a9d70db)`(`[`MidiDevice`](#struct__midi__device)` * device,uint8_t cnt,uint8_t * input)`            | Process input bytes. This function parses bytes and calls the appropriate callbacks associated with the given device. You use this function if you are creating a custom device and you want to have midi input.
+`public void `[`midi_device_set_send_func`](#group__midi__device_1ga59f5a46bdd4452f186cc73d9e96d4673)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_var_byte_func_t send_func)`            | Set the callback function that will be used for sending output data bytes. This is only used if you're creating a custom device. You'll most likely want the callback function to disable interrupts so that you can call the various midi send functions without worrying about locking.
+`public void `[`midi_device_set_pre_input_process_func`](#group__midi__device_1ga4de0841b87c04fc23cb56b6451f33b69)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_no_byte_func_t pre_process_func)`            | Set a callback which is called at the beginning of the midi_device_process call. This can be used to poll for input data and send the data through the midi_device_input function. You'll probably only use this if you're creating a custom device.
+`struct `[`_midi_device`](docs/api_midi_device.md#struct__midi__device) | This structure represents the input and output functions and processing data for a midi device.
+
+## Members
+
+#### `define `[`MIDI_INPUT_QUEUE_LENGTH`](#group__midi__device_1ga4aaa419caebdca2bbdfc1331e79781a8) {#group__midi__device_1ga4aaa419caebdca2bbdfc1331e79781a8}
+
+#### `enum `[`input_state_t`](#group__midi__device_1gac203e877d3df4275ceb8e7180a61f621) {#group__midi__device_1gac203e877d3df4275ceb8e7180a61f621}
+
+ Values                         | Descriptions                                
+--------------------------------|---------------------------------------------
+IDLE            | 
+ONE_BYTE_MESSAGE            | 
+TWO_BYTE_MESSAGE            | 
+THREE_BYTE_MESSAGE            | 
+SYSEX_MESSAGE            | 
+
+#### `public void `[`midi_device_input`](#group__midi__device_1gad8d3db8eb35d9cfa51ef036a0a9d70db)`(`[`MidiDevice`](#struct__midi__device)` * device,uint8_t cnt,uint8_t * input)` {#group__midi__device_1gad8d3db8eb35d9cfa51ef036a0a9d70db}
+
+Process input bytes. This function parses bytes and calls the appropriate callbacks associated with the given device. You use this function if you are creating a custom device and you want to have midi input.
+
+#### Parameters
+* `device` the midi device to associate the input with 
+
+* `cnt` the number of bytes you are processing 
+
+* `input` the bytes to process
+
+#### `public void `[`midi_device_set_send_func`](#group__midi__device_1ga59f5a46bdd4452f186cc73d9e96d4673)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_var_byte_func_t send_func)` {#group__midi__device_1ga59f5a46bdd4452f186cc73d9e96d4673}
+
+Set the callback function that will be used for sending output data bytes. This is only used if you're creating a custom device. You'll most likely want the callback function to disable interrupts so that you can call the various midi send functions without worrying about locking.
+
+#### Parameters
+* `device` the midi device to associate this callback with 
+
+* `send_func` the callback function that will do the sending
+
+#### `public void `[`midi_device_set_pre_input_process_func`](#group__midi__device_1ga4de0841b87c04fc23cb56b6451f33b69)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_no_byte_func_t pre_process_func)` {#group__midi__device_1ga4de0841b87c04fc23cb56b6451f33b69}
+
+Set a callback which is called at the beginning of the midi_device_process call. This can be used to poll for input data and send the data through the midi_device_input function. You'll probably only use this if you're creating a custom device.
+
+#### Parameters
+* `device` the midi device to associate this callback with 
+
+* `midi_no_byte_func_t` the actual callback function
+
+# struct `_midi_device` {#struct__midi__device}
+
+This structure represents the input and output functions and processing data for a midi device.
+
+A device can represent an actual physical device [serial port, usb port] or something virtual. You should not need to modify this structure directly.
+
+## Summary
+
+ Members                        | Descriptions                                
+--------------------------------|---------------------------------------------
+`public midi_var_byte_func_t `[`send_func`](docs/api_midi_device.md#struct__midi__device_1a25d4c94b4bbccd5b98f1032b469f3ff9) | 
+`public midi_three_byte_func_t `[`input_cc_callback`](docs/api_midi_device.md#struct__midi__device_1a6da5236c1bc73877728df92d213a78d1) | 
+`public midi_three_byte_func_t `[`input_noteon_callback`](docs/api_midi_device.md#struct__midi__device_1aa10b15cf1a7fb825a5df0d2abbe34a1c) | 
+`public midi_three_byte_func_t `[`input_noteoff_callback`](docs/api_midi_device.md#struct__midi__device_1aaf290043078534d3a5a0ea4c840eba84) | 
+`public midi_three_byte_func_t `[`input_aftertouch_callback`](docs/api_midi_device.md#struct__midi__device_1acb0b4901c545cec4b28b126f2d8c315f) | 
+`public midi_three_byte_func_t `[`input_pitchbend_callback`](docs/api_midi_device.md#struct__midi__device_1a305fea672caeb996f2233bf8cd2bef18) | 
+`public midi_three_byte_func_t `[`input_songposition_callback`](docs/api_midi_device.md#struct__midi__device_1a5f3f13638b3fef3fc561ed1bf301d586) | 
+`public midi_two_byte_func_t `[`input_progchange_callback`](docs/api_midi_device.md#struct__midi__device_1adaf1da617c9a10a9dcad00ab1959d3da) | 
+`public midi_two_byte_func_t `[`input_chanpressure_callback`](docs/api_midi_device.md#struct__midi__device_1ab7ca2925c539915d43974eff604d85f7) | 
+`public midi_two_byte_func_t `[`input_songselect_callback`](docs/api_midi_device.md#struct__midi__device_1a89bed8a5a55376120cfc0a62b42f057f) | 
+`public midi_two_byte_func_t `[`input_tc_quarterframe_callback`](docs/api_midi_device.md#struct__midi__device_1ad9813e75d22e284f9f65a907d20600f0) | 
+`public midi_one_byte_func_t `[`input_realtime_callback`](docs/api_midi_device.md#struct__midi__device_1a9448eba4afb7e43650434748db3777be) | 
+`public midi_one_byte_func_t `[`input_tunerequest_callback`](docs/api_midi_device.md#struct__midi__device_1a0cb8fd53e00cf1d4202d4fa04d038e8d) | 
+`public midi_sysex_func_t `[`input_sysex_callback`](docs/api_midi_device.md#struct__midi__device_1afff9a0ce641762aaef24c1e6953ec9a2) | 
+`public midi_var_byte_func_t `[`input_fallthrough_callback`](docs/api_midi_device.md#struct__midi__device_1abb974ec6d734001b4a0e370f292be503) | 
+`public midi_var_byte_func_t `[`input_catchall_callback`](docs/api_midi_device.md#struct__midi__device_1aae0d535129d4fd650edc98eb3f7584f8) | 
+`public midi_no_byte_func_t `[`pre_input_process_callback`](docs/api_midi_device.md#struct__midi__device_1aeb0bb8923d66c23d874e177dc4265754) | 
+`public uint8_t `[`input_buffer`](docs/api_midi_device.md#struct__midi__device_1a7c5684857d6af4ebc4dc12da27bd6b2a) | 
+`public input_state_t `[`input_state`](docs/api_midi_device.md#struct__midi__device_1a69a687d2d1c449ec15a11c07a5722e39) | 
+`public uint16_t `[`input_count`](docs/api_midi_device.md#struct__midi__device_1a68dea8e7b6151e89c85c95caa612ee5d) | 
+`public uint8_t `[`input_queue_data`](docs/api_midi_device.md#struct__midi__device_1ada41de021135dc423abedcbb30f366ff) | 
+`public `[`byteQueue_t`](#structbyte_queue__t)` `[`input_queue`](#struct__midi__device_1a49c8538a8a02193c58e28a56eb695d8f) | 
+
+## Members
+
+#### `public midi_var_byte_func_t `[`send_func`](docs/api_midi_device.md#struct__midi__device_1a25d4c94b4bbccd5b98f1032b469f3ff9) {#struct__midi__device_1a25d4c94b4bbccd5b98f1032b469f3ff9}
+
+#### `public midi_three_byte_func_t `[`input_cc_callback`](docs/api_midi_device.md#struct__midi__device_1a6da5236c1bc73877728df92d213a78d1) {#struct__midi__device_1a6da5236c1bc73877728df92d213a78d1}
+
+#### `public midi_three_byte_func_t `[`input_noteon_callback`](docs/api_midi_device.md#struct__midi__device_1aa10b15cf1a7fb825a5df0d2abbe34a1c) {#struct__midi__device_1aa10b15cf1a7fb825a5df0d2abbe34a1c}
+
+#### `public midi_three_byte_func_t `[`input_noteoff_callback`](docs/api_midi_device.md#struct__midi__device_1aaf290043078534d3a5a0ea4c840eba84) {#struct__midi__device_1aaf290043078534d3a5a0ea4c840eba84}
+
+#### `public midi_three_byte_func_t `[`input_aftertouch_callback`](docs/api_midi_device.md#struct__midi__device_1acb0b4901c545cec4b28b126f2d8c315f) {#struct__midi__device_1acb0b4901c545cec4b28b126f2d8c315f}
+
+#### `public midi_three_byte_func_t `[`input_pitchbend_callback`](docs/api_midi_device.md#struct__midi__device_1a305fea672caeb996f2233bf8cd2bef18) {#struct__midi__device_1a305fea672caeb996f2233bf8cd2bef18}
+
+#### `public midi_three_byte_func_t `[`input_songposition_callback`](docs/api_midi_device.md#struct__midi__device_1a5f3f13638b3fef3fc561ed1bf301d586) {#struct__midi__device_1a5f3f13638b3fef3fc561ed1bf301d586}
+
+#### `public midi_two_byte_func_t `[`input_progchange_callback`](docs/api_midi_device.md#struct__midi__device_1adaf1da617c9a10a9dcad00ab1959d3da) {#struct__midi__device_1adaf1da617c9a10a9dcad00ab1959d3da}
+
+#### `public midi_two_byte_func_t `[`input_chanpressure_callback`](docs/api_midi_device.md#struct__midi__device_1ab7ca2925c539915d43974eff604d85f7) {#struct__midi__device_1ab7ca2925c539915d43974eff604d85f7}
+
+#### `public midi_two_byte_func_t `[`input_songselect_callback`](docs/api_midi_device.md#struct__midi__device_1a89bed8a5a55376120cfc0a62b42f057f) {#struct__midi__device_1a89bed8a5a55376120cfc0a62b42f057f}
+
+#### `public midi_two_byte_func_t `[`input_tc_quarterframe_callback`](docs/api_midi_device.md#struct__midi__device_1ad9813e75d22e284f9f65a907d20600f0) {#struct__midi__device_1ad9813e75d22e284f9f65a907d20600f0}
+
+#### `public midi_one_byte_func_t `[`input_realtime_callback`](docs/api_midi_device.md#struct__midi__device_1a9448eba4afb7e43650434748db3777be) {#struct__midi__device_1a9448eba4afb7e43650434748db3777be}
+
+#### `public midi_one_byte_func_t `[`input_tunerequest_callback`](docs/api_midi_device.md#struct__midi__device_1a0cb8fd53e00cf1d4202d4fa04d038e8d) {#struct__midi__device_1a0cb8fd53e00cf1d4202d4fa04d038e8d}
+
+#### `public midi_sysex_func_t `[`input_sysex_callback`](docs/api_midi_device.md#struct__midi__device_1afff9a0ce641762aaef24c1e6953ec9a2) {#struct__midi__device_1afff9a0ce641762aaef24c1e6953ec9a2}
+
+#### `public midi_var_byte_func_t `[`input_fallthrough_callback`](docs/api_midi_device.md#struct__midi__device_1abb974ec6d734001b4a0e370f292be503) {#struct__midi__device_1abb974ec6d734001b4a0e370f292be503}
+
+#### `public midi_var_byte_func_t `[`input_catchall_callback`](docs/api_midi_device.md#struct__midi__device_1aae0d535129d4fd650edc98eb3f7584f8) {#struct__midi__device_1aae0d535129d4fd650edc98eb3f7584f8}
+
+#### `public midi_no_byte_func_t `[`pre_input_process_callback`](docs/api_midi_device.md#struct__midi__device_1aeb0bb8923d66c23d874e177dc4265754) {#struct__midi__device_1aeb0bb8923d66c23d874e177dc4265754}
+
+#### `public uint8_t `[`input_buffer`](docs/api_midi_device.md#struct__midi__device_1a7c5684857d6af4ebc4dc12da27bd6b2a) {#struct__midi__device_1a7c5684857d6af4ebc4dc12da27bd6b2a}
+
+#### `public input_state_t `[`input_state`](docs/api_midi_device.md#struct__midi__device_1a69a687d2d1c449ec15a11c07a5722e39) {#struct__midi__device_1a69a687d2d1c449ec15a11c07a5722e39}
+
+#### `public uint16_t `[`input_count`](docs/api_midi_device.md#struct__midi__device_1a68dea8e7b6151e89c85c95caa612ee5d) {#struct__midi__device_1a68dea8e7b6151e89c85c95caa612ee5d}
+
+#### `public uint8_t `[`input_queue_data`](docs/api_midi_device.md#struct__midi__device_1ada41de021135dc423abedcbb30f366ff) {#struct__midi__device_1ada41de021135dc423abedcbb30f366ff}
+
+#### `public `[`byteQueue_t`](#structbyte_queue__t)` `[`input_queue`](#struct__midi__device_1a49c8538a8a02193c58e28a56eb695d8f) {#struct__midi__device_1a49c8538a8a02193c58e28a56eb695d8f}
+

docs/internals_midi_device_setup_process.md

@@ -0,0 +1,31 @@
+# group `midi_device_setup_process` {#group__midi__device__setup__process}
+
+These are method that you must use to initialize and run a device.
+
+## Summary
+
+ Members                        | Descriptions                                
+--------------------------------|---------------------------------------------
+`public void `[`midi_device_init`](#group__midi__device__setup__process_1gaf29deddc94ea98a59daa0bde1aefd9d9)`(`[`MidiDevice`](#struct__midi__device)` * device)`            | Initialize a device.
+`public void `[`midi_device_process`](#group__midi__device__setup__process_1gaa3d5993d0e998a1b59bbf5ab9c7b492b)`(`[`MidiDevice`](#struct__midi__device)` * device)`            | Process input data.
+
+## Members
+
+#### `public void `[`midi_device_init`](#group__midi__device__setup__process_1gaf29deddc94ea98a59daa0bde1aefd9d9)`(`[`MidiDevice`](#struct__midi__device)` * device)` {#group__midi__device__setup__process_1gaf29deddc94ea98a59daa0bde1aefd9d9}
+
+Initialize a device.
+
+You must call this before using the device in question.
+
+#### Parameters
+* `device` the device to initialize
+
+#### `public void `[`midi_device_process`](#group__midi__device__setup__process_1gaa3d5993d0e998a1b59bbf5ab9c7b492b)`(`[`MidiDevice`](#struct__midi__device)` * device)` {#group__midi__device__setup__process_1gaa3d5993d0e998a1b59bbf5ab9c7b492b}
+
+Process input data.
+
+This method drives the input processing, you must call this method frequently if you expect to have your input callbacks called.
+
+#### Parameters
+* `device` the device to process
+

docs/internals_midi_util.md

@@ -0,0 +1,54 @@
+# group `midi_util` {#group__midi__util}
+
+## Summary
+
+ Members                        | Descriptions                                
+--------------------------------|---------------------------------------------
+`enum `[`midi_packet_length_t`](#group__midi__util_1gae29ff56aee2b430ffe53933b97e5e79e)            | An enumeration of the possible packet length values.
+`public bool `[`midi_is_statusbyte`](#group__midi__util_1ga12e3b42ff9cbb4b4f2bc455fc8743ee5)`(uint8_t theByte)`            | Test to see if the byte given is a status byte.
+`public bool `[`midi_is_realtime`](#group__midi__util_1gad2f52c363e34a8000d80c983c324e2d7)`(uint8_t theByte)`            | Test to see if the byte given is a realtime message.
+`public `[`midi_packet_length_t`](#group__midi__util_1gae29ff56aee2b430ffe53933b97e5e79e)` `[`midi_packet_length`](#group__midi__util_1gaa168b43af6ae9de0debce1625e4b8175)`(uint8_t status)`            | Find the length of the packet associated with the status byte given.
+
+## Members
+
+#### `enum `[`midi_packet_length_t`](#group__midi__util_1gae29ff56aee2b430ffe53933b97e5e79e) {#group__midi__util_1gae29ff56aee2b430ffe53933b97e5e79e}
+
+ Values                         | Descriptions                                
+--------------------------------|---------------------------------------------
+UNDEFINED            | 
+ONE            | 
+TWO            | 
+THREE            | 
+
+An enumeration of the possible packet length values.
+
+#### `public bool `[`midi_is_statusbyte`](#group__midi__util_1ga12e3b42ff9cbb4b4f2bc455fc8743ee5)`(uint8_t theByte)` {#group__midi__util_1ga12e3b42ff9cbb4b4f2bc455fc8743ee5}
+
+Test to see if the byte given is a status byte.
+
+#### Parameters
+* `theByte` the byte to test 
+
+#### Returns
+true if the byte given is a midi status byte
+
+#### `public bool `[`midi_is_realtime`](#group__midi__util_1gad2f52c363e34a8000d80c983c324e2d7)`(uint8_t theByte)` {#group__midi__util_1gad2f52c363e34a8000d80c983c324e2d7}
+
+Test to see if the byte given is a realtime message.
+
+#### Parameters
+* `theByte` the byte to test 
+
+#### Returns
+true if it is a realtime message, false otherwise
+
+#### `public `[`midi_packet_length_t`](#group__midi__util_1gae29ff56aee2b430ffe53933b97e5e79e)` `[`midi_packet_length`](#group__midi__util_1gaa168b43af6ae9de0debce1625e4b8175)`(uint8_t status)` {#group__midi__util_1gaa168b43af6ae9de0debce1625e4b8175}
+
+Find the length of the packet associated with the status byte given.
+
+#### Parameters
+* `status` the status byte 
+
+#### Returns
+the length of the packet, will return UNDEFINED if the byte is not a status byte or if it is a sysex status byte
+

docs/internals_send_functions.md

@@ -0,0 +1,241 @@
+# group `send_functions` {#group__send__functions}
+
+These are the functions you use to send midi data through a device.
+
+## Summary
+
+ Members                        | Descriptions                                
+--------------------------------|---------------------------------------------
+`public void `[`midi_send_cc`](#group__send__functions_1gaaf884811c92df405ca8fe1a00082f960)`(`[`MidiDevice`](#struct__midi__device)` * device,uint8_t chan,uint8_t num,uint8_t val)`            | Send a control change message (cc) via the given device.
+`public void `[`midi_send_noteon`](#group__send__functions_1ga467bcf46dbf03ec269ce565b46bc2775)`(`[`MidiDevice`](#struct__midi__device)` * device,uint8_t chan,uint8_t num,uint8_t vel)`            | Send a note on message via the given device.
+`public void `[`midi_send_noteoff`](#group__send__functions_1gaedb7d8805425eef5d47d57ddcb4c7a49)`(`[`MidiDevice`](#struct__midi__device)` * device,uint8_t chan,uint8_t num,uint8_t vel)`            | Send a note off message via the given device.
+`public void `[`midi_send_aftertouch`](#group__send__functions_1ga0014847571317a0e34b2ef46a6bc584f)`(`[`MidiDevice`](#struct__midi__device)` * device,uint8_t chan,uint8_t note_num,uint8_t amt)`            | Send an after touch message via the given device.
+`public void `[`midi_send_pitchbend`](#group__send__functions_1gae5a4a1e71611e7534be80af9ce3d3491)`(`[`MidiDevice`](#struct__midi__device)` * device,uint8_t chan,int16_t amt)`            | Send a pitch bend message via the given device.
+`public void `[`midi_send_programchange`](#group__send__functions_1ga7b15588ef25e5e1ff09c2afc3151ce86)`(`[`MidiDevice`](#struct__midi__device)` * device,uint8_t chan,uint8_t num)`            | Send a program change message via the given device.
+`public void `[`midi_send_channelpressure`](#group__send__functions_1gaf23e69fdf812e89c0036f51f88ab2e1b)`(`[`MidiDevice`](#struct__midi__device)` * device,uint8_t chan,uint8_t amt)`            | Send a channel pressure message via the given device.
+`public void `[`midi_send_clock`](#group__send__functions_1ga4e1b11a7cdb0875f6e03ce7c79c581aa)`(`[`MidiDevice`](#struct__midi__device)` * device)`            | Send a clock message via the given device.
+`public void `[`midi_send_tick`](#group__send__functions_1ga2b43c7d433d940c5b907595aac947972)`(`[`MidiDevice`](#struct__midi__device)` * device)`            | Send a tick message via the given device.
+`public void `[`midi_send_start`](#group__send__functions_1ga1569749a8d58ccc56789289d7c7245cc)`(`[`MidiDevice`](#struct__midi__device)` * device)`            | Send a start message via the given device.
+`public void `[`midi_send_continue`](#group__send__functions_1gaed5dc29d754a27372e89ab8bc20ee120)`(`[`MidiDevice`](#struct__midi__device)` * device)`            | Send a continue message via the given device.
+`public void `[`midi_send_stop`](#group__send__functions_1ga026e1a620276cb653ac501aa0d12a988)`(`[`MidiDevice`](#struct__midi__device)` * device)`            | Send a stop message via the given device.
+`public void `[`midi_send_activesense`](#group__send__functions_1ga9b6e4c6ce4719d2604187b325620db37)`(`[`MidiDevice`](#struct__midi__device)` * device)`            | Send an active sense message via the given device.
+`public void `[`midi_send_reset`](#group__send__functions_1ga3671e39a6d93ca9568fc493001af1b1b)`(`[`MidiDevice`](#struct__midi__device)` * device)`            | Send a reset message via the given device.
+`public void `[`midi_send_tcquarterframe`](#group__send__functions_1ga5b85639910eec280bb744c934d0fd45a)`(`[`MidiDevice`](#struct__midi__device)` * device,uint8_t time)`            | Send a tc quarter frame message via the given device.
+`public void `[`midi_send_songposition`](#group__send__functions_1gab1c9eeef3b57a8cd2e6128d18e85eb7f)`(`[`MidiDevice`](#struct__midi__device)` * device,uint16_t pos)`            | Send a song position message via the given device.
+`public void `[`midi_send_songselect`](#group__send__functions_1ga42de7838ba70d949af9a50f9facc3c50)`(`[`MidiDevice`](#struct__midi__device)` * device,uint8_t song)`            | Send a song select message via the given device.
+`public void `[`midi_send_tunerequest`](#group__send__functions_1ga8db6c7e04d48e4d2266dd59118ca0656)`(`[`MidiDevice`](#struct__midi__device)` * device)`            | Send a tune request message via the given device.
+`public void `[`midi_send_byte`](#group__send__functions_1ga857e85eb90b288385642d4d991e09881)`(`[`MidiDevice`](#struct__midi__device)` * device,uint8_t b)`            | Send a byte via the given device.
+`public void `[`midi_send_data`](#group__send__functions_1ga36e2f2e45369d911b76969361679054b)`(`[`MidiDevice`](#struct__midi__device)` * device,uint16_t count,uint8_t byte0,uint8_t byte1,uint8_t byte2)`            | Send up to 3 bytes of data.
+`public void `[`midi_send_array`](#group__send__functions_1ga245243cb1da18d2cea18d4b18d846ead)`(`[`MidiDevice`](#struct__midi__device)` * device,uint16_t count,uint8_t * array)`            | Send an array of formatted midi data.
+
+## Members
+
+#### `public void `[`midi_send_cc`](#group__send__functions_1gaaf884811c92df405ca8fe1a00082f960)`(`[`MidiDevice`](#struct__midi__device)` * device,uint8_t chan,uint8_t num,uint8_t val)` {#group__send__functions_1gaaf884811c92df405ca8fe1a00082f960}
+
+Send a control change message (cc) via the given device.
+
+#### Parameters
+* `device` the device to use for sending 
+
+* `chan` the channel to send on, 0-15 
+
+* `num` the cc num 
+
+* `val` the value of that cc num
+
+#### `public void `[`midi_send_noteon`](#group__send__functions_1ga467bcf46dbf03ec269ce565b46bc2775)`(`[`MidiDevice`](#struct__midi__device)` * device,uint8_t chan,uint8_t num,uint8_t vel)` {#group__send__functions_1ga467bcf46dbf03ec269ce565b46bc2775}
+
+Send a note on message via the given device.
+
+#### Parameters
+* `device` the device to use for sending 
+
+* `chan` the channel to send on, 0-15 
+
+* `num` the note number 
+
+* `vel` the note velocity
+
+#### `public void `[`midi_send_noteoff`](#group__send__functions_1gaedb7d8805425eef5d47d57ddcb4c7a49)`(`[`MidiDevice`](#struct__midi__device)` * device,uint8_t chan,uint8_t num,uint8_t vel)` {#group__send__functions_1gaedb7d8805425eef5d47d57ddcb4c7a49}
+
+Send a note off message via the given device.
+
+#### Parameters
+* `device` the device to use for sending 
+
+* `chan` the channel to send on, 0-15 
+
+* `num` the note number 
+
+* `vel` the note velocity
+
+#### `public void `[`midi_send_aftertouch`](#group__send__functions_1ga0014847571317a0e34b2ef46a6bc584f)`(`[`MidiDevice`](#struct__midi__device)` * device,uint8_t chan,uint8_t note_num,uint8_t amt)` {#group__send__functions_1ga0014847571317a0e34b2ef46a6bc584f}
+
+Send an after touch message via the given device.
+
+#### Parameters
+* `device` the device to use for sending 
+
+* `chan` the channel to send on, 0-15 
+
+* `note_num` the note number 
+
+* `amt` the after touch amount
+
+#### `public void `[`midi_send_pitchbend`](#group__send__functions_1gae5a4a1e71611e7534be80af9ce3d3491)`(`[`MidiDevice`](#struct__midi__device)` * device,uint8_t chan,int16_t amt)` {#group__send__functions_1gae5a4a1e71611e7534be80af9ce3d3491}
+
+Send a pitch bend message via the given device.
+
+#### Parameters
+* `device` the device to use for sending 
+
+* `chan` the channel to send on, 0-15 
+
+* `amt` the bend amount range: -8192..8191, 0 means no bend
+
+#### `public void `[`midi_send_programchange`](#group__send__functions_1ga7b15588ef25e5e1ff09c2afc3151ce86)`(`[`MidiDevice`](#struct__midi__device)` * device,uint8_t chan,uint8_t num)` {#group__send__functions_1ga7b15588ef25e5e1ff09c2afc3151ce86}
+
+Send a program change message via the given device.
+
+#### Parameters
+* `device` the device to use for sending 
+
+* `chan` the channel to send on, 0-15 
+
+* `num` the program to change to
+
+#### `public void `[`midi_send_channelpressure`](#group__send__functions_1gaf23e69fdf812e89c0036f51f88ab2e1b)`(`[`MidiDevice`](#struct__midi__device)` * device,uint8_t chan,uint8_t amt)` {#group__send__functions_1gaf23e69fdf812e89c0036f51f88ab2e1b}
+
+Send a channel pressure message via the given device.
+
+#### Parameters
+* `device` the device to use for sending 
+
+* `chan` the channel to send on, 0-15 
+
+* `amt` the amount of channel pressure
+
+#### `public void `[`midi_send_clock`](#group__send__functions_1ga4e1b11a7cdb0875f6e03ce7c79c581aa)`(`[`MidiDevice`](#struct__midi__device)` * device)` {#group__send__functions_1ga4e1b11a7cdb0875f6e03ce7c79c581aa}
+
+Send a clock message via the given device.
+
+#### Parameters
+* `device` the device to use for sending
+
+#### `public void `[`midi_send_tick`](#group__send__functions_1ga2b43c7d433d940c5b907595aac947972)`(`[`MidiDevice`](#struct__midi__device)` * device)` {#group__send__functions_1ga2b43c7d433d940c5b907595aac947972}
+
+Send a tick message via the given device.
+
+#### Parameters
+* `device` the device to use for sending
+
+#### `public void `[`midi_send_start`](#group__send__functions_1ga1569749a8d58ccc56789289d7c7245cc)`(`[`MidiDevice`](#struct__midi__device)` * device)` {#group__send__functions_1ga1569749a8d58ccc56789289d7c7245cc}
+
+Send a start message via the given device.
+
+#### Parameters
+* `device` the device to use for sending
+
+#### `public void `[`midi_send_continue`](#group__send__functions_1gaed5dc29d754a27372e89ab8bc20ee120)`(`[`MidiDevice`](#struct__midi__device)` * device)` {#group__send__functions_1gaed5dc29d754a27372e89ab8bc20ee120}
+
+Send a continue message via the given device.
+
+#### Parameters
+* `device` the device to use for sending
+
+#### `public void `[`midi_send_stop`](#group__send__functions_1ga026e1a620276cb653ac501aa0d12a988)`(`[`MidiDevice`](#struct__midi__device)` * device)` {#group__send__functions_1ga026e1a620276cb653ac501aa0d12a988}
+
+Send a stop message via the given device.
+
+#### Parameters
+* `device` the device to use for sending
+
+#### `public void `[`midi_send_activesense`](#group__send__functions_1ga9b6e4c6ce4719d2604187b325620db37)`(`[`MidiDevice`](#struct__midi__device)` * device)` {#group__send__functions_1ga9b6e4c6ce4719d2604187b325620db37}
+
+Send an active sense message via the given device.
+
+#### Parameters
+* `device` the device to use for sending
+
+#### `public void `[`midi_send_reset`](#group__send__functions_1ga3671e39a6d93ca9568fc493001af1b1b)`(`[`MidiDevice`](#struct__midi__device)` * device)` {#group__send__functions_1ga3671e39a6d93ca9568fc493001af1b1b}
+
+Send a reset message via the given device.
+
+#### Parameters
+* `device` the device to use for sending
+
+#### `public void `[`midi_send_tcquarterframe`](#group__send__functions_1ga5b85639910eec280bb744c934d0fd45a)`(`[`MidiDevice`](#struct__midi__device)` * device,uint8_t time)` {#group__send__functions_1ga5b85639910eec280bb744c934d0fd45a}
+
+Send a tc quarter frame message via the given device.
+
+#### Parameters
+* `device` the device to use for sending 
+
+* `time` the time of this quarter frame, range 0..16383
+
+#### `public void `[`midi_send_songposition`](#group__send__functions_1gab1c9eeef3b57a8cd2e6128d18e85eb7f)`(`[`MidiDevice`](#struct__midi__device)` * device,uint16_t pos)` {#group__send__functions_1gab1c9eeef3b57a8cd2e6128d18e85eb7f}
+
+Send a song position message via the given device.
+
+#### Parameters
+* `device` the device to use for sending 
+
+* `pos` the song position
+
+#### `public void `[`midi_send_songselect`](#group__send__functions_1ga42de7838ba70d949af9a50f9facc3c50)`(`[`MidiDevice`](#struct__midi__device)` * device,uint8_t song)` {#group__send__functions_1ga42de7838ba70d949af9a50f9facc3c50}
+
+Send a song select message via the given device.
+
+#### Parameters
+* `device` the device to use for sending 
+
+* `song` the song to select
+
+#### `public void `[`midi_send_tunerequest`](#group__send__functions_1ga8db6c7e04d48e4d2266dd59118ca0656)`(`[`MidiDevice`](#struct__midi__device)` * device)` {#group__send__functions_1ga8db6c7e04d48e4d2266dd59118ca0656}
+
+Send a tune request message via the given device.
+
+#### Parameters
+* `device` the device to use for sending
+
+#### `public void `[`midi_send_byte`](#group__send__functions_1ga857e85eb90b288385642d4d991e09881)`(`[`MidiDevice`](#struct__midi__device)` * device,uint8_t b)` {#group__send__functions_1ga857e85eb90b288385642d4d991e09881}
+
+Send a byte via the given device.
+
+This is a generic method for sending data via the given midi device. This would be useful for sending sysex data or messages that are not implemented in this API, if there are any. Please contact the author if you find some so we can add them.
+
+#### Parameters
+* `device` the device to use for sending 
+
+* `b` the byte to send
+
+#### `public void `[`midi_send_data`](#group__send__functions_1ga36e2f2e45369d911b76969361679054b)`(`[`MidiDevice`](#struct__midi__device)` * device,uint16_t count,uint8_t byte0,uint8_t byte1,uint8_t byte2)` {#group__send__functions_1ga36e2f2e45369d911b76969361679054b}
+
+Send up to 3 bytes of data.
+
+% 4 is applied to count so that you can use this to pass sysex through
+
+#### Parameters
+* `device` the device to use for sending 
+
+* `count` the count of bytes to send, %4 is applied 
+
+* `byte0` the first byte 
+
+* `byte1` the second byte, ignored if cnt % 4 != 2 
+
+* `byte2` the third byte, ignored if cnt % 4 != 3
+
+#### `public void `[`midi_send_array`](#group__send__functions_1ga245243cb1da18d2cea18d4b18d846ead)`(`[`MidiDevice`](#struct__midi__device)` * device,uint16_t count,uint8_t * array)` {#group__send__functions_1ga245243cb1da18d2cea18d4b18d846ead}
+
+Send an array of formatted midi data.
+
+Can be used for sysex.
+
+#### Parameters
+* `device` the device to use for sending 
+
+* `count` the count of bytes to send 
+
+* `array` the array of bytes
+

docs/internals_sysex_tools.md

@@ -0,0 +1,61 @@
+# group `sysex_tools` {#group__sysex__tools}
+
+## Summary
+
+ Members                        | Descriptions                                
+--------------------------------|---------------------------------------------
+`public uint16_t `[`sysex_encoded_length`](#group__sysex__tools_1ga061e5607030412d6e62e2390d8013f0a)`(uint16_t decoded_length)`            | Compute the length of a message after it is encoded.
+`public uint16_t `[`sysex_decoded_length`](#group__sysex__tools_1ga121fc227d3acc1c0ea08c9a5c26fa3b0)`(uint16_t encoded_length)`            | Compute the length of a message after it is decoded.
+`public uint16_t `[`sysex_encode`](#group__sysex__tools_1ga54d77f8d32f92a6f329daefa2b314742)`(uint8_t * encoded,const uint8_t * source,uint16_t length)`            | Encode data so that it can be transmitted safely in a sysex message.
+`public uint16_t `[`sysex_decode`](#group__sysex__tools_1gaaad1d9ba2d5eca709a0ab4ba40662229)`(uint8_t * decoded,const uint8_t * source,uint16_t length)`            | Decode encoded data.
+
+## Members
+
+#### `public uint16_t `[`sysex_encoded_length`](#group__sysex__tools_1ga061e5607030412d6e62e2390d8013f0a)`(uint16_t decoded_length)` {#group__sysex__tools_1ga061e5607030412d6e62e2390d8013f0a}
+
+Compute the length of a message after it is encoded.
+
+#### Parameters
+* `decoded_length` The length, in bytes, of the message to encode.
+
+#### Returns
+The length, in bytes, of the message after encodeing.
+
+#### `public uint16_t `[`sysex_decoded_length`](#group__sysex__tools_1ga121fc227d3acc1c0ea08c9a5c26fa3b0)`(uint16_t encoded_length)` {#group__sysex__tools_1ga121fc227d3acc1c0ea08c9a5c26fa3b0}
+
+Compute the length of a message after it is decoded.
+
+#### Parameters
+* `encoded_length` The length, in bytes, of the encoded message.
+
+#### Returns
+The length, in bytes, of the message after it is decoded.
+
+#### `public uint16_t `[`sysex_encode`](#group__sysex__tools_1ga54d77f8d32f92a6f329daefa2b314742)`(uint8_t * encoded,const uint8_t * source,uint16_t length)` {#group__sysex__tools_1ga54d77f8d32f92a6f329daefa2b314742}
+
+Encode data so that it can be transmitted safely in a sysex message.
+
+#### Parameters
+* `encoded` The output data buffer, must be at least sysex_encoded_length(length) bytes long. 
+
+* `source` The input buffer of data to be encoded. 
+
+* `length` The number of bytes from the input buffer to encode.
+
+#### Returns
+number of bytes encoded.
+
+#### `public uint16_t `[`sysex_decode`](#group__sysex__tools_1gaaad1d9ba2d5eca709a0ab4ba40662229)`(uint8_t * decoded,const uint8_t * source,uint16_t length)` {#group__sysex__tools_1gaaad1d9ba2d5eca709a0ab4ba40662229}
+
+Decode encoded data.
+
+#### Parameters
+* `decoded` The output data buffer, must be at least sysex_decoded_length(length) bytes long. 
+
+* `source` The input buffer of data to be decoded. 
+
+* `length` The number of bytes from the input buffer to decode.
+
+#### Returns
+number of bytes decoded.
+

docs/isp_flashing_guide.md

@@ -19,58 +19,79 @@ If you're having trouble flashing/erasing your board, and running into cryptic e
     Memory write error, use debug for more info.
     commands.c:360: Error writing memory data. (err -4)
 
-You're likely going to need to ISP flash your board/device to get it working again. Luckily, this process is pretty straight-forward, provided you have any extra programmable keyboard, Arduino, or Teensy 2.0/Teensy 2.0++. There are also dedicated ISP flashers available for this, but most cost >$15, and it's assumed that if you are googling this error, this is the first you've heard about ISP flashing, and don't have one readily available (whereas you might have some other AVR board). __We'll be using a Teensy 2.0 with Windows 10 in this guide__ - if you are comfortable doing this on another system, please consider editing this guide and contributing those instructions!
+You're likely going to need to ISP flash your board/device to get it working again. Luckily, this process is pretty straight-forward, provided you have any extra programmable keyboard, Pro Micro, or Teensy 2.0/Teensy 2.0++. There are also dedicated ISP flashers available for this, but most cost >$15, and it's assumed that if you are googling this error, this is the first you've heard about ISP flashing, and don't have one readily available (whereas you might have some other AVR board). __We'll be using a Teensy 2.0 or Pro Micro with Windows 10 in this guide__ - if you are comfortable doing this on another system, please consider editing this guide and contributing those instructions!   
 
 ## Software Needed
 
-* [The Arduino IDE](https://www.arduino.cc/en/Main/Software)
-* [Teensyduino](https://www.pjrc.com/teensy/td_download.html) (if you're using a Teensy)
-* [WinAVR](http://www.ladyada.net/learn/avr/setup-win.html) (Windows)
+* [Teensy Loader](https://www.pjrc.com/teensy/loader.html) (if using a Teensy)
+* QMK Toolbox (flash as usual - be sure to select the correct MCU) or `avrdude` via [WinAVR](http://www.ladyada.net/learn/avr/setup-win.html) (for Teensy & Pro Micro)
 
 ## Wiring
 
 This is pretty straight-forward - we'll be connecting like-things to like-things in the following manner:
 
-    Flasher B0  <-> Keyboard RESET
-    Flasher B1  <-> Keyboard B1 (SCLK)
-    Flasher B2  <-> Keyboard B2 (MOSI)
-    Flasher B3  <-> Keyboard B3 (MISO)
-    Flasher VCC <-> Keyboard VCC
-    Flasher GND <-> Keyboard GND
+### Teensy 2.0
 
-## The ISP Firmware
+    Teensy B0  <-> Keyboard RESET
+    Teensy B1  <-> Keyboard B1 (SCLK)
+    Teensy B2  <-> Keyboard B2 (MOSI)
+    Teensy B3  <-> Keyboard B3 (MISO)
+    Teensy VCC <-> Keyboard VCC
+    Teensy GND <-> Keyboard GND
+    
+### Pro Micro
+
+    Pro Micro 10 (B6)  <-> Keyboard RESET
+    Pro Micro 15 (B1)  <-> Keyboard B1 (SCLK)
+    Pro Micro 16 (B2)  <-> Keyboard B2 (MOSI)
+    Pro Micro 14 (B3)  <-> Keyboard B3 (MISO)
+    Pro Micro VCC      <-> Keyboard VCC
+    Pro Micro GND      <-> Keyboard GND
+
+## The ISP Firmware (now pre-compiled)
+
+The only difference between the .hex files below is which pin is connected to RESET. You can use them on other boards as well, as long as you're aware of the pins being used. If for some reason neither of these pins are available, [create an issue](https://github.com/qmk/qmk_firmware/issues/new), and we can generate one for you!
+
+* Teensy 2.0: [`util/teensy_2.0_ISP_B0.hex`](https://github.com/qmk/qmk_firmware/blob/master/util/teensy_2.0_ISP_B0.hex) (`B0`)
+* Pro Micro: [`util/pro_micro_ISP_B6_10.hex`](https://github.com/qmk/qmk_firmware/blob/master/util/pro_micro_ISP_B6_10.hex) (`B6/10`)
+
+**Flash your Teenys/Pro Micro with one of these and continue - you won't need the file after flashing your ISP device.**
+
+## Just the Bootloader File
+
+If you just want to get things back to normal, you can flash only a bootloader from [`util/` folder](https://github.com/qmk/qmk_firmware/tree/master/util), and use your normal process to flash the firmware afterwards. Be sure to flash the correct bootloader for your chip:
+
+* [`atmega32u4`](https://github.com/qmk/qmk_firmware/blob/master/util/bootloader_atmega32u4_1_0_0.hex) - Most keyboards, Planck Rev 1-5, Preonic Rev 1-2
+* [`at90usb1286`](https://github.com/qmk/qmk_firmware/blob/master/util/bootloader_at90usb128x_1_0_1.hex) - Planck Light Rev 1
+
+If you're not sure what your board uses, look in the `rules.mk` file for the keyboard in QMK. The `MCU =` line will have the value you need. It may differ between different versions of the board.
+
+### Advanced/Production Techniques
+
+If you'd like to flash both the bootloader **and** the regular firmware at the same time, you need to combine the files. 
+
+1. Open the original firmware .hex file in a text editor
+2. Remove the last line (which should be `:00000001FF` - this is an EOF message)
+3. Copy the entire bootloader's contents onto a new line (with no empty lines between) and paste it at the end of the original file
+4. Save it as a new file by naming it `<keyboard>_<keymap>_production.hex`
+
+It's possible to use other bootloaders here in the same way, but __you need a bootloader__, otherwise you'll have to use ISP again to write new firmware to your keyboard.
+
+## Flashing Your Bootloader/Production File
 
 Make sure your keyboard is unplugged from any device, and plug in your Teensy.
 
-1. Run Arduino after you have everything installed
-2. Select `Tools > Board * > Teensy 2.0`
-3. Click `File > Examples > 11.ArduinoISP > ArduinoISP`
+### QMK Toolbox
 
-Then scroll down until you see something that looks like this block of code:
+1. `AVRISP device connected` will show up in yellow
+2. Select the correct bootloader/production .hex file with the `Open` dialog (spaces can't be in the path)
+3. Be sure the correct `Microcontroller` option is selected
+4. Hit `Flash`
+5. Wait, as nothing will output for a while, especially with production files
 
-    // Configure which pins to use:
+If the verification and fuse checks are ok, you're done! Your board may restart automatically, otherwise, unplug your Teensy and plug in your keyboard - you can leave your Teensy wired to your keyboard while testing things, but it's recommended that you desolder it/remove the wiring once you're sure everything works.
 
-    // The standard pin configuration.
-    #ifndef ARDUINO_HOODLOADER2
-
-    #define RESET     0  // Use 0 (B0) instead of 10
-    #define LED_HB    11 // Use 11 (LED on the Teensy 2.0)
-    #define LED_ERR   8  // This won't be used unless you have an LED hooked-up to 8 (D3)
-    #define LED_PMODE 7  // This won't be used unless you have an LED hooked-up to 7 (D2)
-
-And make the changes in the last four lines. If you're using something besides the Teensy 2.0, you'll want to choose something else that makes sense for `LED_HB`. We define `RESET` as `0`/`B0` because that's what's close - if you want to use another pin for some reason, [you can use the pinouts to choose something else](https://www.pjrc.com/teensy/pinout.html).
-
-Once you've made your changes, you can click the Upload button (right arrow), which will open up the Teensy flasher app - you'll need to press the reset button on the Teensy the first time, but after that, it's automatic (you shouldn't be flashing this more than once, though). Once flashed, the orange LED on the Teensy will flash on and off, indicating it's ready for some action.
-
-## The `.hex` File
-
-Before flashing your firmware, you're going to need to and do a little preparation. We'll be appending [this bootloader (also a .hex file)](https://github.com/qmk/qmk_firmware/blob/master/util/bootloader_atmega32u4_1_0_0.hex) to the end of our firmware by opening the original .hex file in a text editor, and removing the last line, which should be `:00000001FF` (this is an EOF message). After that's been removed, copy the entire bootloader's contents and paste it at the end of the original file, and save it.
-
-It's possible to use other bootloaders here in the same way, but __you need a bootloader__, otherwise you'll have to ISP to write new firmware to your keyboard.
-
-## Flashing Your Firmware
-
-Make sure your keyboard is unplugged from any device, and plug in your Teensy.
+### Command Line
 
 Open `cmd` and navigate to your where your modified .hex file is. We'll pretend this file is called `main.hex`, and that your Teensy 2.0 is on the `COM3` port - if you're unsure, you can open your Device Manager, and look for `Ports > USB Serial Device`. Use that COM port here. You can confirm it's the right port with:
 

docs/keycode.txt

@@ -1,261 +0,0 @@
-Keycode Symbol Table
-====================
-Keycodes are defined in `common/keycode.h`.
-Range of 00-A4 and E0-E7 are identical with HID Usage:
-<http://www.usb.org/developers/hidpage/Hut1_12v2.pdf>
-Virtual keycodes are defined out of above range to support special actions.
-
-
-Keycode Symbol      Short name      Description
---------------------------------------------------------------------------------
-KC_NO                               00 Reserved (no event indicated)
-KC_ROLL_OVER                        01 Keyboard ErrorRollOver
-KC_POST_FAIL                        02 Keyboard POSTFail
-KC_UNDEFINED                        03 Keyboard ErrorUndefined
-KC_A                                04 Keyboard a and A
-KC_B                                05 Keyboard b and B
-KC_C                                06 Keyboard c and C
-KC_D                                07 Keyboard d and D
-KC_E                                08 Keyboard e and E
-KC_F                                09 Keyboard f and F
-KC_G                                0A Keyboard g and G
-KC_H                                0B Keyboard h and H
-KC_I                                0C Keyboard i and I
-KC_J                                0D Keyboard j and J
-KC_K                                0E Keyboard k and K
-KC_L                                0F Keyboard l and L
-KC_M                                10 Keyboard m and M
-KC_N                                11 Keyboard n and N
-KC_O                                12 Keyboard o and O
-KC_P                                13 Keyboard p and P
-KC_Q                                14 Keyboard q and Q
-KC_R                                15 Keyboard r and R
-KC_S                                16 Keyboard s and S
-KC_T                                17 Keyboard t and T
-KC_U                                18 Keyboard u and U
-KC_V                                19 Keyboard v and V
-KC_W                                1A Keyboard w and W
-KC_X                                1B Keyboard x and X
-KC_Y                                1C Keyboard y and Y
-KC_Z                                1D Keyboard z and Z
-KC_1                                1E Keyboard 1 and !
-KC_2                                1F Keyboard 2 and @
-KC_3                                20 Keyboard 3 and #
-KC_4                                21 Keyboard 4 and $
-KC_5                                22 Keyboard 5 and %
-KC_6                                23 Keyboard 6 and ^
-KC_7                                24 Keyboard 7 and &
-KC_8                                25 Keyboard 8 and *
-KC_9                                26 Keyboard 9 and (
-KC_0                                27 Keyboard 0 and )
-KC_ENTER            KC_ENT          28 Keyboard Return (ENTER)
-KC_ESCAPE           KC_ESC          29 Keyboard ESCAPE
-KC_BSPACE           KC_BSPC         2A Keyboard DELETE (Backspace)
-KC_TAB                              2B Keyboard Tab
-KC_SPACE            KC_SPC          2C Keyboard Spacebar
-KC_MINUS            KC_MINS         2D Keyboard - and (underscore)
-KC_EQUAL            KC_EQL          2E Keyboard = and +
-KC_LBRACKET         KC_LBRC         2F Keyboard [ and {
-KC_RBRACKET         KC_RBRC         30 Keyboard ] and }
-KC_BSLASH           KC_BSLS         31 Keyboard \ and |
-KC_NONUS_HASH       KC_NUHS         32 Keyboard Non-US # and ~
-KC_SCOLON           KC_SCLN         33 Keyboard ; and :
-KC_QUOTE            KC_QUOT         34 Keyboard ‘ and “
-KC_GRAVE            KC_GRV          35 Keyboard Grave Accent and Tilde
-KC_COMMA            KC_COMM         36 Keyboard , and <
-KC_DOT                              37 Keyboard . and >
-KC_SLASH            KC_SLSH         38 Keyboard / and ?
-KC_CAPSLOCK         KC_CAPS         39 Keyboard Caps Lock
-KC_F1                               3A Keyboard F1
-KC_F2                               3B Keyboard F2
-KC_F3                               3C Keyboard F3
-KC_F4                               3D Keyboard F4
-KC_F5                               3E Keyboard F5
-KC_F6                               3F Keyboard F6
-KC_F7                               40 Keyboard F7
-KC_F8                               41 Keyboard F8
-KC_F9                               42 Keyboard F9
-KC_F10                              43 Keyboard F10
-KC_F11                              44 Keyboard F11
-KC_F12                              45 Keyboard F12
-KC_PSCREEN          KC_PSCR         46 Keyboard PrintScreen
-KC_SCROLLLOCK       KC_SLCK         47 Keyboard Scroll Lock
-KC_PAUSE            KC_PAUS         48 Keyboard Pause
-KC_INSERT           KC_INS          49 Keyboard Insert
-KC_HOME                             4A Keyboard Home
-KC_PGUP                             4B Keyboard PageUp
-KC_DELETE           KC_DEL          4C Keyboard Delete Forward
-KC_END                              4D Keyboard End
-KC_PGDOWN           KC_PGDN         4E Keyboard PageDown
-KC_RIGHT            KC_RGHT         4F Keyboard RightArrow
-KC_LEFT                             50 Keyboard LeftArrow
-KC_DOWN                             51 Keyboard DownArrow
-KC_UP                               52 Keyboard UpArrow
-KC_NUMLOCK          KC_NLCK         53 Keypad Num Lock and Clear
-KC_KP_SLASH         KC_PSLS         54 Keypad /
-KC_KP_ASTERISK      KC_PAST         55 Keypad *
-KC_KP_MINUS         KC_PMNS         56 Keypad -
-KC_KP_PLUS          KC_PPLS         57 Keypad +
-KC_KP_ENTER         KC_PENT         58 Keypad ENTER
-KC_KP_1             KC_P1           59 Keypad 1 and End
-KC_KP_2             KC_P2           5A Keypad 2 and Down Arrow
-KC_KP_3             KC_P3           5B Keypad 3 and PageDn
-KC_KP_4             KC_P4           5C Keypad 4 and Left Arrow
-KC_KP_5             KC_P5           5D Keypad 5
-KC_KP_6             KC_P6           5E Keypad 6 and Right Arrow
-KC_KP_7             KC_P7           5F Keypad 7 and Home
-KC_KP_8             KC_P8           60 Keypad 8 and Up Arrow
-KC_KP_9             KC_P9           61 Keypad 9 and PageUp
-KC_KP_0             KC_P0           62 Keypad 0 and Insert
-KC_KP_DOT           KC_PDOT         63 Keypad . and Delete
-KC_NONUS_BSLASH     KC_NUBS         64 Keyboard Non-US \ and |
-KC_APPLICATION      KC_APP          65 Keyboard Application
-KC_POWER                            66 Keyboard Power
-KC_KP_EQUAL         KC_PEQL         67 Keypad =
-KC_F13                              68 Keyboard F13
-KC_F14                              69 Keyboard F14
-KC_F15                              6A Keyboard F15
-KC_F16                              6B Keyboard F16
-KC_F17                              6C Keyboard F17
-KC_F18                              6D Keyboard F18
-KC_F19                              6E Keyboard F19
-KC_F20                              6F Keyboard F20
-KC_F21                              70 Keyboard F21
-KC_F22                              71 Keyboard F22
-KC_F23                              72 Keyboard F23
-KC_F24                              73 Keyboard F24
-KC_EXECUTE                          74 Keyboard Execute
-KC_HELP                             75 Keyboard Help
-KC_MENU                             76 Keyboard Menu
-KC_SELECT                           77 Keyboard Select
-KC_STOP                             78 Keyboard Stop
-KC_AGAIN                            79 Keyboard Again
-KC_UNDO                             7A Keyboard Undo
-KC_CUT                              7B Keyboard Cut
-KC_COPY                             7C Keyboard Copy
-KC_PASTE                            7D Keyboard Paste
-KC_FIND                             7E Keyboard Find
-KC__MUTE                            7F Keyboard Mute
-KC__VOLUP                           80 Keyboard Volume Up
-KC__VOLDOWN                         81 Keyboard Volume Down
-KC_LOCKING_CAPS                     82 Keyboard Locking Caps Lock
-KC_LOCKING_NUM                      83 Keyboard Locking Num Lock
-KC_LOCKING_SCROLL                   84 Keyboard Locking Scroll Lock
-KC_KP_COMMA         KC_PCMM         85 Keypad Comma
-KC_KP_EQUAL_AS400                   86 Keypad Equal Sign
-KC_INT1             KC_RO           87 Keyboard International115
-KC_INT2             KC_KANA         88 Keyboard International216
-KC_INT3             KC_JYEN         89 Keyboard International317
-KC_INT4             KC_HENK         8A Keyboard International418
-KC_INT5             KC_MHEN         8B Keyboard International519
-KC_INT6                             8C Keyboard International620
-KC_INT7                             8D Keyboard International721
-KC_INT8                             8E Keyboard International822
-KC_INT9                             8F Keyboard International922
-KC_LANG1                            90 Keyboard LANG125
-KC_LANG2                            91 Keyboard LANG226
-KC_LANG3                            92 Keyboard LANG330
-KC_LANG4                            93 Keyboard LANG431
-KC_LANG5                            94 Keyboard LANG532
-KC_LANG6                            95 Keyboard LANG68
-KC_LANG7                            96 Keyboard LANG78
-KC_LANG8                            97 Keyboard LANG88
-KC_LANG9                            98 Keyboard LANG98
-KC_ALT_ERASE                        99 Keyboard Alternate Erase
-KC_SYSREQ                           9A Keyboard SysReq/Attention
-KC_CANCEL                           9B Keyboard Cancel
-KC_CLEAR                            9C Keyboard Clear
-KC_PRIOR                            9D Keyboard Prior
-KC_RETURN                           9E Keyboard Return
-KC_SEPARATOR                        9F Keyboard Separator
-KC_OUT                              A0 Keyboard Out
-KC_OPER                             A1 Keyboard Oper
-KC_CLEAR_AGAIN                      A2 Keyboard Clear/Again
-KC_CRSEL                            A3 Keyboard CrSel/Props
-KC_EXSEL                            A4 Keyboard ExSel
-/* Modifiers */
-KC_LCTRL            KC_LCTL         E0 Keyboard LeftControl
-KC_LSHIFT           KC_LSFT         E1 Keyboard LeftShift
-KC_LALT                             E2 Keyboard LeftAlt
-KC_LGUI                             E3 Keyboard Left GUI(Windows/Apple/Meta key)
-KC_RCTRL            KC_RCTL         E4 Keyboard RightControl
-KC_RSHIFT           KC_RSFT         E5 Keyboard RightShift
-KC_RALT                             E6 Keyboard RightAlt
-KC_RGUI                             E7 Keyboard Right GUI(Windows/Apple/Meta key)
-
-/*
- * Virtual keycodes
- */
-/* System Control */
-KC_SYSTEM_POWER     KC_PWR          System Power Down
-KC_SYSTEM_SLEEP     KC_SLEP         System Sleep
-KC_SYSTEM_WAKE      KC_WAKE         System Wake
-/* Consumer Page */
-KC_AUDIO_MUTE       KC_MUTE
-KC_AUDIO_VOL_UP     KC_VOLU
-KC_AUDIO_VOL_DOWN   KC_VOLD
-KC_MEDIA_NEXT_TRACK KC_MNXT
-KC_MEDIA_PREV_TRACK KC_MPRV
-KC_MEDIA_STOP       KC_MSTP
-KC_MEDIA_PLAY_PAUSE KC_MPLY
-KC_MEDIA_SELECT     KC_MSEL
-KC_MAIL             KC_MAIL
-KC_CALCULATOR       KC_CALC
-KC_MY_COMPUTER      KC_MYCM
-KC_WWW_SEARCH       KC_WSCH
-KC_WWW_HOME         KC_WHOM
-KC_WWW_BACK         KC_WBAK
-KC_WWW_FORWARD      KC_WFWD
-KC_WWW_STOP         KC_WSTP
-KC_WWW_REFRESH      KC_WREF
-KC_WWW_FAVORITES    KC_WFAV
-/* Mousekey */
-KC_MS_UP            KC_MS_U         Mouse Cursor Up
-KC_MS_DOWN          KC_MS_D         Mouse Cursor Down
-KC_MS_LEFT          KC_MS_L         Mouse Cursor Left
-KC_MS_RIGHT         KC_MS_R         Mouse Cursor Right
-KC_MS_BTN1          KC_BTN1         Mouse Button 1
-KC_MS_BTN2          KC_BTN2         Mouse Button 2
-KC_MS_BTN3          KC_BTN3         Mouse Button 3
-KC_MS_BTN4          KC_BTN4         Mouse Button 4
-KC_MS_BTN5          KC_BTN5         Mouse Button 5
-KC_MS_WH_UP         KC_WH_U         Mouse Wheel Up
-KC_MS_WH_DOWN       KC_WH_D         Mouse Wheel Down
-KC_MS_WH_LEFT       KC_WH_L         Mouse Wheel Left
-KC_MS_WH_RIGHT      KC_WH_R         Mouse Wheel Right
-KC_MS_ACCEL0        KC_ACL0         Mouse Acceleration 0
-KC_MS_ACCEL1        KC_ACL1         Mouse Acceleration 1
-KC_MS_ACCEL2        KC_ACL2         Mouse Acceleration 2
-/* Fn key */
-KC_FN0
-KC_FN1
-KC_FN2
-KC_FN3
-KC_FN4
-KC_FN5
-KC_FN6
-KC_FN7
-KC_FN8
-KC_FN9
-KC_FN10
-KC_FN11
-KC_FN12
-KC_FN13
-KC_FN14
-KC_FN15
-KC_FN16
-KC_FN17
-KC_FN18
-KC_FN19
-KC_FN20
-KC_FN21
-KC_FN22
-KC_FN23
-KC_FN24
-KC_FN25
-KC_FN26
-KC_FN27
-KC_FN28
-KC_FN29
-KC_FN30
-KC_FN31

docs/keycodes.md

@@ -6,225 +6,249 @@ This is a reference only. Each group of keys links to the page documenting their
 
 ## [Basic Keycodes](keycodes_basic.md)
 
-|Key                    |Aliases   |Description                                    |
-|-----------------------|----------|-----------------------------------------------|
-|`KC_1`                 |          |`1` and `!`                                    |
-|`KC_2`                 |          |`2` and `@`                                    |
-|`KC_3`                 |          |`3` and `#`                                    |
-|`KC_4`                 |          |`4` and `$`                                    |
-|`KC_5`                 |          |`5` and `%`                                    |
-|`KC_6`                 |          |`6` and `^`                                    |
-|`KC_7`                 |          |`7` and `&`                                    |
-|`KC_8`                 |          |`8` and `*`                                    |
-|`KC_9`                 |          |`9` and `(`                                    |
-|`KC_0`                 |          |`0` and `)`                                    |
-|`KC_F1`                |          |                                               |
-|`KC_F2`                |          |                                               |
-|`KC_F3`                |          |                                               |
-|`KC_F4`                |          |                                               |
-|`KC_F5`                |          |                                               |
-|`KC_F6`                |          |                                               |
-|`KC_F7`                |          |                                               |
-|`KC_F8`                |          |                                               |
-|`KC_F9`                |          |                                               |
-|`KC_F10`               |          |                                               |
-|`KC_F11`               |          |                                               |
-|`KC_F12`               |          |                                               |
-|`KC_F13`               |          |                                               |
-|`KC_F14`               |          |                                               |
-|`KC_F15`               |          |                                               |
-|`KC_F16`               |          |                                               |
-|`KC_F17`               |          |                                               |
-|`KC_F18`               |          |                                               |
-|`KC_F19`               |          |                                               |
-|`KC_F20`               |          |                                               |
-|`KC_F21`               |          |                                               |
-|`KC_F22`               |          |                                               |
-|`KC_F23`               |          |                                               |
-|`KC_F24`               |          |                                               |
-|`KC_A`                 |          |`a` and `A`                                    |
-|`KC_B`                 |          |`b` and `B`                                    |
-|`KC_C`                 |          |`c` and `C`                                    |
-|`KC_D`                 |          |`d` and `D`                                    |
-|`KC_E`                 |          |`e` and `E`                                    |
-|`KC_F`                 |          |`f` and `F`                                    |
-|`KC_G`                 |          |`g` and `G`                                    |
-|`KC_H`                 |          |`h` and `H`                                    |
-|`KC_I`                 |          |`i` and `I`                                    |
-|`KC_J`                 |          |`j` and `J`                                    |
-|`KC_K`                 |          |`k` and `K`                                    |
-|`KC_L`                 |          |`l` and `L`                                    |
-|`KC_M`                 |          |`m` and `M`                                    |
-|`KC_N`                 |          |`n` and `N`                                    |
-|`KC_O`                 |          |`o` and `O`                                    |
-|`KC_P`                 |          |`p` and `P`                                    |
-|`KC_Q`                 |          |`q` and `Q`                                    |
-|`KC_R`                 |          |`r` and `R`                                    |
-|`KC_S`                 |          |`s` and `S`                                    |
-|`KC_T`                 |          |`t` and `T`                                    |
-|`KC_U`                 |          |`u` and `U`                                    |
-|`KC_V`                 |          |`v` and `V`                                    |
-|`KC_W`                 |          |`w` and `W`                                    |
-|`KC_X`                 |          |`x` and `X`                                    |
-|`KC_Y`                 |          |`y` and `Y`                                    |
-|`KC_Z`                 |          |`z` and `Z`                                    |
-|`KC_ENTER`             |`KC_ENT`  |Return (Enter)                                 |
-|`KC_ESCAPE`            |`KC_ESC`  |Escape                                         |
-|`KC_BSPACE`            |`KC_BSPC` |Delete (Backspace)                             |
-|`KC_TAB`               |          |Tab                                            |
-|`KC_SPACE`             |`KC_SPC`  |Spacebar                                       |
-|`KC_MINUS`             |`KC_MINS` |`-` and `_`                                    |
-|`KC_EQUAL`             |`KC_EQL`  |`=` and `+`                                    |
-|`KC_LBRACKET`          |`KC_LBRC` |`[` and `{`                                    |
-|`KC_RBRACKET`          |`KC_RBRC` |`]` and `}`                                    |
-|`KC_BSLASH`            |`KC_BSLS` |`\` and <code>&#124;</code>                    |
-|`KC_NONUS_HASH`        |`KC_NUHS` |Non-US `#` and `~`                             |
-|`KC_NONUS_BSLASH`      |`KC_NUBS` |Non-US `\` and <code>&#124;</code>             |
-|`KC_INT1`              |`KC_RO`   |JIS `\` and <code>&#124;</code>                |
-|`KC_INT2`              |`KC_KANA` |JIS Katakana/Hiragana                          |
-|`KC_INT3`              |`KC_JYEN` |JIS `¥`                                        |
-|`KC_SCOLON`            |`KC_SCLN` |`;` and `:`                                    |
-|`KC_QUOTE`             |`KC_QUOT` |`'` and `"`                                    |
-|`KC_GRAVE`             |`KC_GRV`  |<code>&#96;</code> and `~`                     |
-|`KC_COMMA`             |`KC_COMM` |`,` and `<`                                    |
-|`KC_DOT`               |          |`.` and `>`                                    |
-|`KC_SLASH`             |`KC_SLSH` |`/` and `?`                                    |
-|`KC_CAPSLOCK`          |`KC_CAPS` |Caps Lock                                      |
-|`KC_LCTRL`             |`KC_LCTL` |Left Control                                   |
-|`KC_LSHIFT`            |`KC_LSFT` |Left Shift                                     |
-|`KC_LALT`              |          |Left Alt                                       |
-|`KC_LGUI`              |          |Left GUI (Windows/Command/Meta key)            |
-|`KC_RCTRL`             |`KC_RCTL` |Right Control                                  |
-|`KC_RSHIFT`            |`KC_RSFT` |Right Shift                                    |
-|`KC_RALT`              |          |Right Alt                                      |
-|`KC_RGUI`              |          |Right GUI (Windows/Command/Meta key)           |
-|`KC_LOCKING_CAPS`      |`KC_LCAP` |Locking Caps Lock                              |
-|`KC_LOCKING_NUM`       |`KC_LNUM` |Locking Num Lock                               |
-|`KC_LOCKING_SCROLL`    |`KC_LSCR` |Locking Scroll Lock                            |
-|`KC_INT4`              |`KC_HENK` |JIS Henkan                                     |
-|`KC_INT5`              |`KC_MHEN` |JIS Muhenkan                                   |
-|`KC_PSCREEN`           |`KC_PSCR` |Print Screen                                   |
-|`KC_SCROLLLOCK`        |`KC_SLCK` |Scroll Lock                                    |
-|`KC_PAUSE`             |`KC_PAUS` |Pause                                          |
-|`KC_INSERT`            |`KC_INS`  |Insert                                         |
-|`KC_HOME`              |          |Home                                           |
-|`KC_PGUP`              |          |Page Up                                        |
-|`KC_DELETE`            |`KC_DEL`  |Forward Delete                                 |
-|`KC_END`               |          |End                                            |
-|`KC_PGDOWN`            |`KC_PGDN` |Page Down                                      |
-|`KC_RIGHT`             |`KC_RGHT` |Right Arrow                                    |
-|`KC_LEFT`              |          |Left Arrow                                     |
-|`KC_DOWN`              |          |Down Arrow                                     |
-|`KC_UP`                |          |Up Arrow                                       |
-|`KC_APPLICATION`       |`KC_APP`  |Application (Windows Menu Key)                 |
-|`KC_POWER`             |          |Deprecated by MS in favor of `KC_SYSTEM_POWER`.|
-|`KC_EXECUTE`           |          |Execute                                        |
-|`KC_HELP`              |          |Help                                           |
-|`KC_MENU`              |          |Menu                                           |
-|`KC_SELECT`            |          |Select                                         |
-|`KC_AGAIN`             |          |Again                                          |
-|`KC_UNDO`              |          |Undo                                           |
-|`KC_CUT`               |          |Cut                                            |
-|`KC_COPY`              |          |Copy                                           |
-|`KC_PASTE`             |          |Paste                                          |
-|`KC_FIND`              |          |Find                                           |
-|`KC_ALT_ERASE`         |          |Alternate Erase                                |
-|`KC_SYSREQ`            |          |SysReq/Attention                               |
-|`KC_CANCEL`            |          |Cancel                                         |
-|`KC_CLEAR`             |          |Clear                                          |
-|`KC_PRIOR`             |          |Prior                                          |
-|`KC_RETURN`            |          |Return                                         |
-|`KC_SEPARATOR`         |          |Separator                                      |
-|`KC_OUT`               |          |Out                                            |
-|`KC_OPER`              |          |Oper                                           |
-|`KC_CLEAR_AGAIN`       |          |Clear/Again                                    |
-|`KC_CRSEL`             |          |CrSel/Props                                    |
-|`KC_EXSEL`             |          |ExSel                                          |
-|`KC_SYSTEM_POWER`      |`KC_PWR`  |System Power Down. Recommended over `KC_POWER`.|
-|`KC_SYSTEM_SLEEP`      |`KC_SLEP` |System Sleep                                   |
-|`KC_SYSTEM_WAKE`       |`KC_WAKE` |System Wake                                    |
-|`KC_MAIL`              |`KC_MAIL` |                                               |
-|`KC_CALCULATOR`        |`KC_CALC` |                                               |
-|`KC_MY_COMPUTER`       |`KC_MYCM` |                                               |
-|`KC_WWW_SEARCH`        |`KC_WSCH` |                                               |
-|`KC_WWW_HOME`          |`KC_WHOM` |                                               |
-|`KC_WWW_BACK`          |`KC_WBAK` |                                               |
-|`KC_WWW_FORWARD`       |`KC_WFWD` |                                               |
-|`KC_WWW_STOP`          |`KC_WSTP` |                                               |
-|`KC_WWW_REFRESH`       |`KC_WREF` |                                               |
-|`KC_WWW_FAVORITES`     |`KC_WFAV` |                                               |
-|`KC_STOP`              |          |Stop                                           |
-|`KC__MUTE`             |          |Mute (macOS)                                   |
-|`KC__VOLUP`            |          |Volume Up (macOS)                              |
-|`KC__VOLDOWN`          |          |Volume Down (macOS)                            |
-|`KC_AUDIO_MUTE`        |`KC_MUTE` |Mute (Windows/macOS/Linux)                     |
-|`KC_AUDIO_VOL_UP`      |`KC_VOLU` |Volume Up (Windows/macOS/Linux)                |
-|`KC_AUDIO_VOL_DOWN`    |`KC_VOLD` |Volume Down (Windows/macOS/Linux)              |
-|`KC_MEDIA_NEXT_TRACK`  |`KC_MNXT` |Next Track (Windows)                           |
-|`KC_MEDIA_PREV_TRACK`  |`KC_MPRV` |Previous Track (Windows)                       |
-|`KC_MEDIA_FAST_FORWARD`|`KC_MFFD` |Next Track (macOS)                             |
-|`KC_MEDIA_REWIND`      |`KC_MRWD` |Previous Track (macOS)                         |
-|`KC_MEDIA_STOP`        |`KC_MSTP` |Stop Track                                     |
-|`KC_MEDIA_PLAY_PAUSE`  |`KC_MPLY` |Play/Pause Track                               |
-|`KC_MEDIA_SELECT`      |`KC_MSEL` |                                               |
-|`KC_NUMLOCK`           |`KC_NLCK` |Keypad Num Lock and Clear                      |
-|`KC_KP_SLASH`          |`KC_PSLS` |Keypad `/`                                     |
-|`KC_KP_ASTERISK`       |`KC_PAST` |Keypad `*`                                     |
-|`KC_KP_MINUS`          |`KC_PMNS` |Keypad `-`                                     |
-|`KC_KP_PLUS`           |`KC_PPLS` |Keypad `+`                                     |
-|`KC_KP_ENTER`          |`KC_PENT` |Keypad Enter                                   |
-|`KC_KP_1`              |`KC_P1`   |Keypad `1` and End                             |
-|`KC_KP_2`              |`KC_P2`   |Keypad `2` and Down Arrow                      |
-|`KC_KP_3`              |`KC_P3`   |Keypad `3` and Page Down                       |
-|`KC_KP_4`              |`KC_P4`   |Keypad `4` and Left Arrow                      |
-|`KC_KP_5`              |`KC_P5`   |Keypad `5`                                     |
-|`KC_KP_6`              |`KC_P6`   |Keypad `6` and Right Arrow                     |
-|`KC_KP_7`              |`KC_P7`   |Keypad `7` and Home                            |
-|`KC_KP_8`              |`KC_P8`   |Keypad `8` and Up Arrow                        |
-|`KC_KP_9`              |`KC_P9`   |Keypad `9` and Page Up                         |
-|`KC_KP_0`              |`KC_P0`   |Keypad `0` and Insert                          |
-|`KC_KP_DOT`            |`KC_PDOT` |Keypad `.` and Delete                          |
-|`KC_KP_EQUAL`          |`KC_PEQL` |Keypad `=`                                     |
-|`KC_KP_COMMA`          |`KC_PCMM` |Keypad `,`                                     |
-|`KC_KP_EQUAL_AS400`    |          |Keypad `=` on AS/400 keyboards                 |
-|`KC_NO`                |          |Ignore this key (NOOP)                         |
-|`KC_TRANSPARENT`       |`KC_TRNS` |Use the next lowest non-transparent key        |
-
-## [Mouse Keys](feature_mouse_keys.md)
-
-|Key             |Aliases  |Description                |
-|----------------|---------|---------------------------|
-|`KC_MS_UP`      |`KC_MS_U`|Mouse Cursor Up            |
-|`KC_MS_DOWN`    |`KC_MS_D`|Mouse Cursor Down          |
-|`KC_MS_LEFT`    |`KC_MS_L`|Mouse Cursor Left          |
-|`KC_MS_RIGHT`   |`KC_MS_R`|Mouse Cursor Right         |
-|`KC_MS_BTN1`    |`KC_BTN1`|Mouse Button 1             |
-|`KC_MS_BTN2`    |`KC_BTN2`|Mouse Button 2             |
-|`KC_MS_BTN3`    |`KC_BTN3`|Mouse Button 3             |
-|`KC_MS_BTN4`    |`KC_BTN4`|Mouse Button 4             |
-|`KC_MS_BTN5`    |`KC_BTN5`|Mouse Button 5             |
-|`KC_MS_WH_UP`   |`KC_WH_U`|Mouse Wheel Up             |
-|`KC_MS_WH_DOWN` |`KC_WH_D`|Mouse Wheel Down           |
-|`KC_MS_WH_LEFT` |`KC_WH_L`|Mouse Wheel Left           |
-|`KC_MS_WH_RIGHT`|`KC_WH_R`|Mouse Wheel Right          |
-|`KC_MS_ACCEL0`  |`KC_ACL0`|Set mouse acceleration to 0|
-|`KC_MS_ACCEL1`  |`KC_ACL1`|Set mouse acceleration to 1|
-|`KC_MS_ACCEL2`  |`KC_ACL2`|Set mouse acceleration to 2|
+|Key                    |Aliases                       |Description                                    |
+|-----------------------|------------------------------|-----------------------------------------------|
+|`KC_NO`                |`XXXXXXX`                     |Ignore this key (NOOP)                         |
+|`KC_TRANSPARENT`       |`KC_TRNS`, `_______`          |Use the next lowest non-transparent key        |
+|`KC_A`                 |                              |`a` and `A`                                    |
+|`KC_B`                 |                              |`b` and `B`                                    |
+|`KC_C`                 |                              |`c` and `C`                                    |
+|`KC_D`                 |                              |`d` and `D`                                    |
+|`KC_E`                 |                              |`e` and `E`                                    |
+|`KC_F`                 |                              |`f` and `F`                                    |
+|`KC_G`                 |                              |`g` and `G`                                    |
+|`KC_H`                 |                              |`h` and `H`                                    |
+|`KC_I`                 |                              |`i` and `I`                                    |
+|`KC_J`                 |                              |`j` and `J`                                    |
+|`KC_K`                 |                              |`k` and `K`                                    |
+|`KC_L`                 |                              |`l` and `L`                                    |
+|`KC_M`                 |                              |`m` and `M`                                    |
+|`KC_N`                 |                              |`n` and `N`                                    |
+|`KC_O`                 |                              |`o` and `O`                                    |
+|`KC_P`                 |                              |`p` and `P`                                    |
+|`KC_Q`                 |                              |`q` and `Q`                                    |
+|`KC_R`                 |                              |`r` and `R`                                    |
+|`KC_S`                 |                              |`s` and `S`                                    |
+|`KC_T`                 |                              |`t` and `T`                                    |
+|`KC_U`                 |                              |`u` and `U`                                    |
+|`KC_V`                 |                              |`v` and `V`                                    |
+|`KC_W`                 |                              |`w` and `W`                                    |
+|`KC_X`                 |                              |`x` and `X`                                    |
+|`KC_Y`                 |                              |`y` and `Y`                                    |
+|`KC_Z`                 |                              |`z` and `Z`                                    |
+|`KC_1`                 |                              |`1` and `!`                                    |
+|`KC_2`                 |                              |`2` and `@`                                    |
+|`KC_3`                 |                              |`3` and `#`                                    |
+|`KC_4`                 |                              |`4` and `$`                                    |
+|`KC_5`                 |                              |`5` and `%`                                    |
+|`KC_6`                 |                              |`6` and `^`                                    |
+|`KC_7`                 |                              |`7` and `&`                                    |
+|`KC_8`                 |                              |`8` and `*`                                    |
+|`KC_9`                 |                              |`9` and `(`                                    |
+|`KC_0`                 |                              |`0` and `)`                                    |
+|`KC_ENTER`             |`KC_ENT`                      |Return (Enter)                                 |
+|`KC_ESCAPE`            |`KC_ESC`                      |Escape                                         |
+|`KC_BSPACE`            |`KC_BSPC`                     |Delete (Backspace)                             |
+|`KC_TAB`               |                              |Tab                                            |
+|`KC_SPACE`             |`KC_SPC`                      |Spacebar                                       |
+|`KC_MINUS`             |`KC_MINS`                     |`-` and `_`                                    |
+|`KC_EQUAL`             |`KC_EQL`                      |`=` and `+`                                    |
+|`KC_LBRACKET`          |`KC_LBRC`                     |`[` and `{`                                    |
+|`KC_RBRACKET`          |`KC_RBRC`                     |`]` and `}`                                    |
+|`KC_BSLASH`            |`KC_BSLS`                     |`\` and <code>&#124;</code>                    |
+|`KC_NONUS_HASH`        |`KC_NUHS`                     |Non-US `#` and `~`                             |
+|`KC_SCOLON`            |`KC_SCLN`                     |`;` and `:`                                    |
+|`KC_QUOTE`             |`KC_QUOT`                     |`'` and `"`                                    |
+|`KC_GRAVE`             |`KC_GRV`, `KC_ZKHK`           |<code>&#96;</code> and `~`, JIS Zenkaku/Hankaku|
+|`KC_COMMA`             |`KC_COMM`                     |`,` and `<`                                    |
+|`KC_DOT`               |                              |`.` and `>`                                    |
+|`KC_SLASH`             |`KC_SLSH`                     |`/` and `?`                                    |
+|`KC_CAPSLOCK`          |`KC_CLCK`, `KC_CAPS`          |Caps Lock                                      |
+|`KC_F1`                |                              |F1                                             |
+|`KC_F2`                |                              |F2                                             |
+|`KC_F3`                |                              |F3                                             |
+|`KC_F4`                |                              |F4                                             |
+|`KC_F5`                |                              |F5                                             |
+|`KC_F6`                |                              |F6                                             |
+|`KC_F7`                |                              |F7                                             |
+|`KC_F8`                |                              |F8                                             |
+|`KC_F9`                |                              |F9                                             |
+|`KC_F10`               |                              |F10                                            |
+|`KC_F11`               |                              |F11                                            |
+|`KC_F12`               |                              |F12                                            |
+|`KC_PSCREEN`           |`KC_PSCR`                     |Print Screen                                   |
+|`KC_SCROLLLOCK`        |`KC_SLCK`, `KC_BRMD`          |Scroll Lock, Brightness Down (macOS)           |
+|`KC_PAUSE`             |`KC_PAUS`, `KC_BRK`, `KC_BRMU`|Pause, Brightness Up (macOS)                   |
+|`KC_INSERT`            |`KC_INS`                      |Insert                                         |
+|`KC_HOME`              |                              |Home                                           |
+|`KC_PGUP`              |                              |Page Up                                        |
+|`KC_DELETE`            |`KC_DEL`                      |Forward Delete                                 |
+|`KC_END`               |                              |End                                            |
+|`KC_PGDOWN`            |`KC_PGDN`                     |Page Down                                      |
+|`KC_RIGHT`             |`KC_RGHT`                     |Right Arrow                                    |
+|`KC_LEFT`              |                              |Left Arrow                                     |
+|`KC_DOWN`              |                              |Down Arrow                                     |
+|`KC_UP`                |                              |Up Arrow                                       |
+|`KC_NUMLOCK`           |`KC_NLCK`                     |Keypad Num Lock and Clear                      |
+|`KC_KP_SLASH`          |`KC_PSLS`                     |Keypad `/`                                     |
+|`KC_KP_ASTERISK`       |`KC_PAST`                     |Keypad `*`                                     |
+|`KC_KP_MINUS`          |`KC_PMNS`                     |Keypad `-`                                     |
+|`KC_KP_PLUS`           |`KC_PPLS`                     |Keypad `+`                                     |
+|`KC_KP_ENTER`          |`KC_PENT`                     |Keypad Enter                                   |
+|`KC_KP_1`              |`KC_P1`                       |Keypad `1` and End                             |
+|`KC_KP_2`              |`KC_P2`                       |Keypad `2` and Down Arrow                      |
+|`KC_KP_3`              |`KC_P3`                       |Keypad `3` and Page Down                       |
+|`KC_KP_4`              |`KC_P4`                       |Keypad `4` and Left Arrow                      |
+|`KC_KP_5`              |`KC_P5`                       |Keypad `5`                                     |
+|`KC_KP_6`              |`KC_P6`                       |Keypad `6` and Right Arrow                     |
+|`KC_KP_7`              |`KC_P7`                       |Keypad `7` and Home                            |
+|`KC_KP_8`              |`KC_P8`                       |Keypad `8` and Up Arrow                        |
+|`KC_KP_9`              |`KC_P9`                       |Keypad `9` and Page Up                         |
+|`KC_KP_0`              |`KC_P0`                       |Keypad `0` and Insert                          |
+|`KC_KP_DOT`            |`KC_PDOT`                     |Keypad `.` and Delete                          |
+|`KC_NONUS_BSLASH`      |`KC_NUBS`                     |Non-US `\` and <code>&#124;</code>             |
+|`KC_APPLICATION`       |`KC_APP`                      |Application (Windows Menu Key)                 |
+|`KC_POWER`             |                              |System Power (macOS)                           |
+|`KC_KP_EQUAL`          |`KC_PEQL`                     |Keypad `=`                                     |
+|`KC_F13`               |                              |F13                                            |
+|`KC_F14`               |                              |F14                                            |
+|`KC_F15`               |                              |F15                                            |
+|`KC_F16`               |                              |F16                                            |
+|`KC_F17`               |                              |F17                                            |
+|`KC_F18`               |                              |F18                                            |
+|`KC_F19`               |                              |F19                                            |
+|`KC_F20`               |                              |F20                                            |
+|`KC_F21`               |                              |F21                                            |
+|`KC_F22`               |                              |F22                                            |
+|`KC_F23`               |                              |F23                                            |
+|`KC_F24`               |                              |F24                                            |
+|`KC_EXECUTE`           |`KC_EXEC`                     |Execute                                        |
+|`KC_HELP`              |                              |Help                                           |
+|`KC_MENU`              |                              |Menu                                           |
+|`KC_SELECT`            |`KC_SLCT`                     |Select                                         |
+|`KC_STOP`              |                              |Stop                                           |
+|`KC_AGAIN`             |`KC_AGIN`                     |Again                                          |
+|`KC_UNDO`              |                              |Undo                                           |
+|`KC_CUT`               |                              |Cut                                            |
+|`KC_COPY`              |                              |Copy                                           |
+|`KC_PASTE`             |`KC_PSTE`                     |Paste                                          |
+|`KC_FIND`              |                              |Find                                           |
+|`KC__MUTE`             |                              |Mute (macOS)                                   |
+|`KC__VOLUP`            |                              |Volume Up (macOS)                              |
+|`KC__VOLDOWN`          |                              |Volume Down (macOS)                            |
+|`KC_LOCKING_CAPS`      |`KC_LCAP`                     |Locking Caps Lock                              |
+|`KC_LOCKING_NUM`       |`KC_LNUM`                     |Locking Num Lock                               |
+|`KC_LOCKING_SCROLL`    |`KC_LSCR`                     |Locking Scroll Lock                            |
+|`KC_KP_COMMA`          |`KC_PCMM`                     |Keypad `,`                                     |
+|`KC_KP_EQUAL_AS400`    |                              |Keypad `=` on AS/400 keyboards                 |
+|`KC_INT1`              |`KC_RO`                       |JIS `\` and `_`                                |
+|`KC_INT2`              |`KC_KANA`                     |JIS Katakana/Hiragana                          |
+|`KC_INT3`              |`KC_JYEN`                     |JIS `¥` and <code>&#124;</code>                |
+|`KC_INT4`              |`KC_HENK`                     |JIS Henkan                                     |
+|`KC_INT5`              |`KC_MHEN`                     |JIS Muhenkan                                   |
+|`KC_INT6`              |                              |JIS Numpad `,`                                 |
+|`KC_INT7`              |                              |International 7                                |
+|`KC_INT8`              |                              |International 8                                |
+|`KC_INT9`              |                              |International 9                                |
+|`KC_LANG1`             |`KC_HAEN`                     |Hangul/English                                 |
+|`KC_LANG2`             |`KC_HANJ`                     |Hanja                                          |
+|`KC_LANG3`             |                              |JIS Katakana                                   |
+|`KC_LANG4`             |                              |JIS Hiragana                                   |
+|`KC_LANG5`             |                              |JIS Zenkaku/Hankaku                            |
+|`KC_LANG6`             |                              |Language 6                                     |
+|`KC_LANG7`             |                              |Language 7                                     |
+|`KC_LANG8`             |                              |Language 8                                     |
+|`KC_LANG9`             |                              |Language 9                                     |
+|`KC_ALT_ERASE`         |`KC_ERAS`                     |Alternate Erase                                |
+|`KC_SYSREQ`            |                              |SysReq/Attention                               |
+|`KC_CANCEL`            |                              |Cancel                                         |
+|`KC_CLEAR`             |`KC_CLR`                      |Clear                                          |
+|`KC_PRIOR`             |                              |Prior                                          |
+|`KC_RETURN`            |                              |Return                                         |
+|`KC_SEPARATOR`         |                              |Separator                                      |
+|`KC_OUT`               |                              |Out                                            |
+|`KC_OPER`              |                              |Oper                                           |
+|`KC_CLEAR_AGAIN`       |                              |Clear/Again                                    |
+|`KC_CRSEL`             |                              |CrSel/Props                                    |
+|`KC_EXSEL`             |                              |ExSel                                          |
+|`KC_LCTRL`             |`KC_LCTL`                     |Left Control                                   |
+|`KC_LSHIFT`            |`KC_LSFT`                     |Left Shift                                     |
+|`KC_LALT`              |                              |Left Alt                                       |
+|`KC_LGUI`              |`KC_LCMD`, `KC_LWIN`          |Left GUI (Windows/Command/Meta key)            |
+|`KC_RCTRL`             |`KC_RCTL`                     |Right Control                                  |
+|`KC_RSHIFT`            |`KC_RSFT`                     |Right Shift                                    |
+|`KC_RALT`              |`KC_ALGR`                     |Right Alt (AltGr)                              |
+|`KC_RGUI`              |`KC_RCMD`, `KC_RWIN`          |Right GUI (Windows/Command/Meta key)           |
+|`KC_SYSTEM_POWER`      |`KC_PWR`                      |System Power Down                              |
+|`KC_SYSTEM_SLEEP`      |`KC_SLEP`                     |System Sleep                                   |
+|`KC_SYSTEM_WAKE`       |`KC_WAKE`                     |System Wake                                    |
+|`KC_AUDIO_MUTE`        |`KC_MUTE`                     |Mute                                           |
+|`KC_AUDIO_VOL_UP`      |`KC_VOLU`                     |Volume Up                                      |
+|`KC_AUDIO_VOL_DOWN`    |`KC_VOLD`                     |Volume Down                                    |
+|`KC_MEDIA_NEXT_TRACK`  |`KC_MNXT`                     |Next Track (Windows)                           |
+|`KC_MEDIA_PREV_TRACK`  |`KC_MPRV`                     |Previous Track (Windows)                       |
+|`KC_MEDIA_STOP`        |`KC_MSTP`                     |Stop Track (Windows)                           |
+|`KC_MEDIA_PLAY_PAUSE`  |`KC_MPLY`                     |Play/Pause Track                               |
+|`KC_MEDIA_SELECT`      |`KC_MSEL`                     |Launch Media Player (Windows)                  |
+|`KC_MEDIA_EJECT`       |`KC_EJCT`                     |Eject (macOS)                                  |
+|`KC_MAIL`              |                              |Launch Mail (Windows)                          |
+|`KC_CALCULATOR`        |`KC_CALC`                     |Launch Calculator (Windows)                    |
+|`KC_MY_COMPUTER`       |`KC_MYCM`                     |Launch My Computer (Windows)                   |
+|`KC_WWW_SEARCH`        |`KC_WSCH`                     |Browser Search (Windows)                       |
+|`KC_WWW_HOME`          |`KC_WHOM`                     |Browser Home (Windows)                         |
+|`KC_WWW_BACK`          |`KC_WBAK`                     |Browser Back (Windows)                         |
+|`KC_WWW_FORWARD`       |`KC_WFWD`                     |Browser Forward (Windows)                      |
+|`KC_WWW_STOP`          |`KC_WSTP`                     |Browser Stop (Windows)                         |
+|`KC_WWW_REFRESH`       |`KC_WREF`                     |Browser Refresh (Windows)                      |
+|`KC_WWW_FAVORITES`     |`KC_WFAV`                     |Browser Favorites (Windows)                    |
+|`KC_MEDIA_FAST_FORWARD`|`KC_MFFD`                     |Next Track (macOS)                             |
+|`KC_MEDIA_REWIND`      |`KC_MRWD`                     |Previous Track (macOS)                         |
+|`KC_BRIGHTNESS_UP`     |`KC_BRIU`                     |Brightness Up                                  |
+|`KC_BRIGHTNESS_DOWN`   |`KC_BRID`                     |Brightness Down                                |
 
 ## [Quantum Keycodes](quantum_keycodes.md#qmk-keycodes)
 
-|Key          |Aliases    |Description                                                          |
-|-------------|-----------|---------------------------------------------------------------------|
-|`RESET`      |           |Put the keyboard into DFU mode for flashing                          |
-|`DEBUG`      |           |Toggle debug mode                                                    |
-|`KC_GESC`    |`GRAVE_ESC`|Escape when tapped, <code>&#96;</code> when pressed with Shift or GUI|
-|`KC_LSPO`    |           |Left Shift when held, `(` when tapped                                |
-|`KC_RSPC`    |           |Right Shift when held, `)` when tapped                               |
-|`KC_LEAD`    |           |The [Leader key](feature_leader_key.md)                              |
-|`KC_LOCK`    |           |The [Lock key](feature_key_lock.md)                                  |
-|`FUNC(n)`    |`F(n)`     |Call `fn_action(n)` (deprecated)                                     |
-|`M(n)`       |           |Call macro `n`                                                       |
-|`MACROTAP(n)`|           |Macro-tap `n` idk FIXME                                              |
+|Key            |Aliases    |Description                                                          |
+|---------------|-----------|---------------------------------------------------------------------|
+|`RESET`        |           |Put the keyboard into DFU mode for flashing                          |
+|`DEBUG`        |           |Toggle debug mode                                                    |
+|`EEPROM_RESET` |`EEP_RST`  |Resets EEPROM state by reinitializing it                             |
+|`KC_GESC`      |`GRAVE_ESC`|Escape when tapped, <code>&#96;</code> when pressed with Shift or GUI|
+|`KC_LSPO`      |           |Left Shift when held, `(` when tapped                                |
+|`KC_RSPC`      |           |Right Shift when held, `)` when tapped                               |
+|`KC_LEAD`      |           |The [Leader key](feature_leader_key.md)                              |
+|`KC_LOCK`      |           |The [Lock key](feature_key_lock.md)                                  |
+|`FUNC(n)`      |`F(n)`     |Call `fn_action(n)` (deprecated)                                     |
+|`M(n)`         |           |Call macro `n`                                                       |
+|`MACROTAP(n)`  |           |Macro-tap `n` idk FIXME                                              |
+
+## [Audio Keys](feature_audio.md)
+
+|Key             |Aliases  |Description                       |
+|----------------|---------|----------------------------------|
+|`AU_ON`         |         |Turns on Audio Feature            |
+|`AU_OFF`        |         |Turns off Audio Feature           |
+|`AU_TOG`        |         |Toggles Audio state               |
+|`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    |
+
+## [Backlighting](feature_backlight.md)
+
+|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                |
 
 ## [Bootmagic](feature_bootmagic.md)
 
@@ -248,19 +272,90 @@ This is a reference only. Each group of keys links to the page documenting their
 |`MAGIC_UNSWAP_BACKSLASH_BACKSPACE`|         |Unswap `\` and Backspace            |
 |`MAGIC_UNHOST_NKRO`               |         |Force NKRO off                      |
 |`MAGIC_UNSWAP_ALT_GUI`            |`AG_NORM`|Unswap Alt and GUI on both sides    |
+|`MAGIC_TOGGLE_ALT_GUI`            |`AG_TOGG`|Toggle Alt and GUI swap on both sides|
 |`MAGIC_TOGGLE_NKRO`               |         |Turn NKRO on or off                 |
 
-## [Backlighting](feature_backlight.md)
+## [Bluetooth](feature_bluetooth.md)
 
-|Key      |Description                               |
-|---------|------------------------------------------|
-|`BL_TOGG`|Turn the backlight on or off              |
-|`BL_STEP`|Cycle through backlight levels            |
-|`BL_x`   |Set a specific backlight level between 0-9|
-|`BL_ON`  |An alias for `BL_9`                       |
-|`BL_OFF` |An alias for `BL_0`                       |
-|`BL_INC` |Increase backlight level                  |
-|`BL_DEC` |Decrease backlight level                  |
+|Key       |Description                                   |
+|----------|----------------------------------------------|
+|`OUT_AUTO`|Automatically switch between USB and Bluetooth|
+|`OUT_USB` |USB only                                      |
+|`OUT_BT`  |Bluetooth only                                |
+
+## [Layer Switching](feature_advanced_keycodes.md#switching-and-toggling-layers)
+
+|Key             |Description                                                                       |
+|----------------|----------------------------------------------------------------------------------|
+|`DF(layer)`     |Set the base (default) layer                                                      |
+|`MO(layer)`     |Momentarily turn on `layer` when pressed (requires `KC_TRNS` on destination layer)|
+|`OSL(layer)`    |Momentarily activates `layer` until a key is pressed. See [One Shot Keys](https://docs.qmk.fm/#/feature_advanced_keycodes?id=one-shot-keys) for details. |
+|`LM(layer, mod)`|Momentarily turn on `layer` (like MO) with `mod` active as well.  Where `mod` is a mods_bit.  Mods can be viewed [here](https://docs.qmk.fm/#/feature_advanced_keycodes?id=mod-tap).  Example Implementation: `LM(LAYER_1, MOD_LALT)`|
+|`LT(layer, kc)` |Turn on `layer` when held, `kc` when tapped                                       |
+|`TG(layer)`     |Toggle `layer` on or off                                                          |
+|`TO(layer)`     |Turn on `layer` when pressed                                                      |
+|`TT(layer)`     |Normally acts like MO unless it's tapped multiple times, which toggles `layer` on |
+
+## [Mouse Keys](feature_mouse_keys.md)
+
+|Key             |Aliases  |Description                |
+|----------------|---------|---------------------------|
+|`KC_MS_UP`      |`KC_MS_U`|Mouse Cursor Up            |
+|`KC_MS_DOWN`    |`KC_MS_D`|Mouse Cursor Down          |
+|`KC_MS_LEFT`    |`KC_MS_L`|Mouse Cursor Left          |
+|`KC_MS_RIGHT`   |`KC_MS_R`|Mouse Cursor Right         |
+|`KC_MS_BTN1`    |`KC_BTN1`|Mouse Button 1             |
+|`KC_MS_BTN2`    |`KC_BTN2`|Mouse Button 2             |
+|`KC_MS_BTN3`    |`KC_BTN3`|Mouse Button 3             |
+|`KC_MS_BTN4`    |`KC_BTN4`|Mouse Button 4             |
+|`KC_MS_BTN5`    |`KC_BTN5`|Mouse Button 5             |
+|`KC_MS_WH_UP`   |`KC_WH_U`|Mouse Wheel Up             |
+|`KC_MS_WH_DOWN` |`KC_WH_D`|Mouse Wheel Down           |
+|`KC_MS_WH_LEFT` |`KC_WH_L`|Mouse Wheel Left           |
+|`KC_MS_WH_RIGHT`|`KC_WH_R`|Mouse Wheel Right          |
+|`KC_MS_ACCEL0`  |`KC_ACL0`|Set mouse acceleration to 0|
+|`KC_MS_ACCEL1`  |`KC_ACL1`|Set mouse acceleration to 1|
+|`KC_MS_ACCEL2`  |`KC_ACL2`|Set mouse acceleration to 2|
+
+## [Modifiers](feature_advanced_keycodes.md#modifier-keys)
+
+|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`|
+|`KC_MEH`  |                               |Left Control, Shift and Alt                         |
+|`KC_HYPR` |                               |Left Control, Shift, Alt and GUI                    |
+
+## [Mod-Tap Keys](feature_advanced_keycodes.md#mod-tap)
+
+|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/)|
 
 ## [RGB Lighting](feature_rgblight.md)
 
@@ -283,6 +378,23 @@ This is a reference only. Each group of keys links to the page documenting their
 |`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                                  |
+
+## [RGB Matrix Lighting](feature_rgb_matrix.md)
+
+|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_SPI`          |          |Increase effect speed (does no support eeprom yet)                  |
+|`RGB_SPD`          |          |Decrease effect speed (does no support eeprom yet)                  |
 
 ## [Thermal Printer](feature_thermal_printer.md)
 
@@ -291,102 +403,54 @@ This is a reference only. Each group of keys links to the page documenting their
 |`PRINT_ON` |Start printing everything the user types|
 |`PRINT_OFF`|Stop printing everything the user types |
 
-## [Bluetooth](feature_bluetooth.md)
+## [US ANSI Shifted Symbols](keycodes_us_ansi_shifted.md)
 
-|Key       |Description                                   |
-|----------|----------------------------------------------|
-|`OUT_AUTO`|Automatically switch between USB and Bluetooth|
-|`OUT_USB` |USB only                                      |
-|`OUT_BT`  |Bluetooth only                                |
+|Key                     |Aliases            |Description        |
+|------------------------|-------------------|-------------------|
+|`KC_TILDE`              |`KC_TILD`          |`~`                |
+|`KC_EXCLAIM`            |`KC_EXLM`          |`!`                |
+|`KC_AT`                 |                   |`@`                |
+|`KC_HASH`               |                   |`#`                |
+|`KC_DOLLAR`             |`KC_DLR`           |`$`                |
+|`KC_PERCENT`            |`KC_PERC`          |`%`                |
+|`KC_CIRCUMFLEX`         |`KC_CIRC`          |`^`                |
+|`KC_AMPERSAND`          |`KC_AMPR`          |`&`                |
+|`KC_ASTERISK`           |`KC_ASTR`          |`*`                |
+|`KC_LEFT_PAREN`         |`KC_LPRN`          |`(`                |
+|`KC_RIGHT_PAREN`        |`KC_RPRN`          |`)`                |
+|`KC_UNDERSCORE`         |`KC_UNDS`          |`_`                |
+|`KC_PLUS`               |                   |`+`                |
+|`KC_LEFT_CURLY_BRACE`   |`KC_LCBR`          |`{`                |
+|`KC_RIGHT_CURLY_BRACE`  |`KC_RCBR`          |`}`                |
+|`KC_PIPE`               |                   |<code>&#124;</code>|
+|`KC_COLON`              |`KC_COLN`          |`:`                |
+|`KC_DOUBLE_QUOTE`       |`KC_DQUO`, `KC_DQT`|`"`                |
+|`KC_LEFT_ANGLE_BRACKET` |`KC_LABK`, `KC_LT` |`<`                |
+|`KC_RIGHT_ANGLE_BRACKET`|`KC_RABK`, `KC_GT` |`>`                |
+|`KC_QUESTION`           |`KC_QUES`          |`?`                |
 
-## [Modifiers](quantum_keycodes.md#modifiers)
-
-|Key       |Aliases   |Description                                         |
-|----------|----------|----------------------------------------------------|
-|`KC_HYPR` |          |Hold Left Control, Shift, Alt and GUI               |
-|`KC_MEH`  |          |Hold Left Control, Shift and Alt                    |
-|`LCTL(kc)`|          |Hold Left Control and press `kc`                    |
-|`LSFT(kc)`|`S(kc)`   |Hold Left Shift and press `kc`                      |
-|`LALT(kc)`|          |Hold Left Alt and press `kc`                        |
-|`LGUI(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)`|          |Hold Right Alt and press `kc`                       |
-|`RGUI(kc)`|          |Hold Right GUI and press `kc`                       |
-|`HYPR(kc)`|          |Hold Left Control, Shift, Alt and GUI and press `kc`|
-|`MEH(kc)` |          |Hold Left Control, Shift and Alt and press `kc`     |
-|`LCAG(kc)`|          |Hold Left Control, Alt and GUI and press `kc`       |
-|`ALTG(kc)`|          |Hold Right Control and Alt and press `kc`           |
-|`SCMD(kc)`|`SWIN(kc)`|Hold Left Shift and GUI and press `kc`              |
-|`LCA(kc)` |          |Hold Left Control and Alt and press `kc`            |
-
-## [Mod-Tap Keys](quantum_keycodes.md#mod-tap-keys)
-
-|Key         |Aliases     |Description                                            |
-|------------|------------|-------------------------------------------------------|
-|`LCTL_T(kc)`|`CTL_T(kc)` |Left Control when held, `kc` when tapped               |
-|`RCTL_T(kc)`|            |Right Control when held, `kc` when tapped              |
-|`LSFT_T(kc)`|`SFT_T(kc)` |Left Shift when held, `kc` when tapped                 |
-|`RSFT_T(kc)`|            |Right Shift when held, `kc` when tapped                |
-|`LALT_T(kc)`|`ALT_T(kc)` |Left Alt when held, `kc` when tapped                   |
-|`RALT_T(kc)`|`ALGR_T(kc)`|Right Alt when held, `kc` when tapped                  |
-|`LGUI_T(kc)`|`GUI_T(kc)` |Left GUI when held, `kc` when tapped                   |
-|`RGUI_T(kc)`|            |Right 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|
-|`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 |
-|`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/)|
-|`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       |
-
-## [US ANSI Shifted Keys](keycodes_us_ansi_shifted.md)
-
-|Key                     |Aliases           |Description        |
-|------------------------|------------------|-------------------|
-|`KC_TILDE`              |`KC_TILD`         |`~`                |
-|`KC_EXCLAIM`            |`KC_EXLM`         |`!`                |
-|`KC_AT`                 |                  |`@`                |
-|`KC_HASH`               |                  |`#`                |
-|`KC_DOLLAR`             |`KC_DLR`          |`$`                |
-|`KC_PERCENT`            |`KC_PERC`         |`%`                |
-|`KC_CIRCUMFLEX`         |`KC_CIRC`         |`^`                |
-|`KC_AMPERSAND`          |`KC_AMPR`         |`&`                |
-|`KC_ASTERISK`           |`KC_ASTR`         |`*`                |
-|`KC_LEFT_PAREN`         |`KC_LPRN`         |`(`                |
-|`KC_RIGHT_PAREN`        |`KC_RPRN`         |`)`                |
-|`KC_UNDERSCORE`         |`KC_UNDS`         |`_`                |
-|`KC_PLUS`               |                  |`+`                |
-|`KC_LEFT_CURLY_BRACE`   |`KC_LCBR`         |`{`                |
-|`KC_RIGHT_CURLY_BRACE`  |`KC_RCBR`         |`}`                |
-|`KC_PIPE`               |                  |<code>&#124;</code>|
-|`KC_COLON`              |`KC_COLN`         |`:`                |
-|`KC_DOUBLE_QUOTE`       |`KC_DQT`/`KC_DQUO`|`"`                |
-|`KC_LEFT_ANGLE_BRACKET` |`KC_LT`/`KC_LABK` |`<`                |
-|`KC_RIGHT_ANGLE_BRACKET`|`KC_GT`/`KC_RABK` |`>`                |
-|`KC_QUESTION`           |`KC_QUES`         |`?`                |
-
-## [Switching and Toggling Layers](feature_common_shortcuts.md#switching-and-toggling-layers)
-
-|Key            |Description                                                                       |
-|---------------|----------------------------------------------------------------------------------|
-|`LT(layer, kc)`|Turn on `layer` when held, `kc` when tapped                                       |
-|`TO(layer)`    |Turn on `layer` when pressed                                                      |
-|`MO(layer)`    |Momentarily turn on `layer` when pressed (requires `KC_TRNS` on destination layer)|
-|`DF(layer)`    |Set the base (default) layer                                                      |
-|`TG(layer)`    |Toggle `layer` on or off                                                          |
-|`TT(layer)`    |Tap toggle? idk FIXME                                                             |
-
-## [One Shot Keys](quantum_keycodes.md#one-shot-keys)
+## [One Shot Keys](feature_advanced_keycodes.md#one-shot-keys)
 
 |Key         |Description                       |
 |------------|----------------------------------|
 |`OSM(mod)`  |Hold `mod` for one keypress       |
 |`OSL(layer)`|Switch to `layer` for one keypress|
 
+## [Swap Hands](feature_swap_hands.md)
+
+|Key        |Description                                                              |
+|-----------|-------------------------------------------------------------------------|
+|`SH_T(key)`|Sends `key` with a tap; momentary swap when held.                        |
+|`SW_ON`    |Turns on swapping and leaves it on.                                      |
+|`SW_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.                                 |
+
 ## [Unicode Support](feature_unicode.md)
 
-|Key         |Aliases|                                                 |
-|------------|-------|-------------------------------------------------|
-|`UNICODE(n)`|`UC(n)`|Send Unicode character `n`                       |
-|`X(n)`      |       |Send Unicode character `n` via a different method|
+|Key    |Description                                                                |
+|-------|---------------------------------------------------------------------------|
+|`UC(c)`|Send Unicode code point `c` (`UNICODE_ENABLE`)                             |
+|`X(i)` |Send Unicode code point at index `i` in `unicode_map` (`UNICODEMAP_ENABLE`)|

docs/keycodes_basic.md

@@ -1,6 +1,6 @@
 # Basic Keycodes
 
-The basic set of keycodes are based on the [HID Keyboard/Keypad Usage Page (0x07)](http://www.usb.org/developers/hidpage/Hut1_12v2.pdf) with the exception of `KC_NO`, `KC_TRNS` and keycodes in the `0xA5-DF` range. See below for more details.
+The basic set of keycodes are based on the [HID Keyboard/Keypad Usage Page (0x07)](https://www.usb.org/sites/default/files/documents/hut1_12v2.pdf) with the exception of `KC_NO`, `KC_TRNS` and keycodes in the `0xA5-DF` range. See below for more details.
 
 ## Letters and Numbers
 
@@ -47,117 +47,145 @@ The basic set of keycodes are based on the [HID Keyboard/Keypad Usage Page (0x07
 
 |Key     |Description|
 |--------|-----------|
-|`KC_F1` |           |
-|`KC_F2` |           |
-|`KC_F3` |           |
-|`KC_F4` |           |
-|`KC_F5` |           |
-|`KC_F6` |           |
-|`KC_F7` |           |
-|`KC_F8` |           |
-|`KC_F9` |           |
-|`KC_F10`|           |
-|`KC_F11`|           |
-|`KC_F12`|           |
-|`KC_F13`|           |
-|`KC_F14`|           |
-|`KC_F15`|           |
-|`KC_F16`|           |
-|`KC_F17`|           |
-|`KC_F18`|           |
-|`KC_F19`|           |
-|`KC_F20`|           |
-|`KC_F21`|           |
-|`KC_F22`|           |
-|`KC_F23`|           |
-|`KC_F24`|           |
+|`KC_F1` |F1         |
+|`KC_F2` |F2         |
+|`KC_F3` |F3         |
+|`KC_F4` |F4         |
+|`KC_F5` |F5         |
+|`KC_F6` |F6         |
+|`KC_F7` |F7         |
+|`KC_F8` |F8         |
+|`KC_F9` |F9         |
+|`KC_F10`|F10        |
+|`KC_F11`|F11        |
+|`KC_F12`|F12        |
+|`KC_F13`|F13        |
+|`KC_F14`|F14        |
+|`KC_F15`|F15        |
+|`KC_F16`|F16        |
+|`KC_F17`|F17        |
+|`KC_F18`|F18        |
+|`KC_F19`|F19        |
+|`KC_F20`|F20        |
+|`KC_F21`|F21        |
+|`KC_F22`|F22        |
+|`KC_F23`|F23        |
+|`KC_F24`|F24        |
 
 ## Punctuation
 
-|Key              |Aliases  |Description                       |
-|-----------------|---------|----------------------------------|
-|`KC_ENTER`       |`KC_ENT` |Return (Enter)                    |
-|`KC_ESCAPE`      |`KC_ESC` |Escape                            |
-|`KC_BSPACE`      |`KC_BSPC`|Delete (Backspace)                |
-|`KC_TAB`         |         |Tab                               |
-|`KC_SPACE`       |`KC_SPC` |Spacebar                          |
-|`KC_MINUS`       |`KC_MINS`|`-` and `_`                       |
-|`KC_EQUAL`       |`KC_EQL` |`=` and `+`                       |
-|`KC_LBRACKET`    |`KC_LBRC`|`[` and `{`                       |
-|`KC_RBRACKET`    |`KC_RBRC`|`]` and `}`                       |
-|`KC_BSLASH`      |`KC_BSLS`|`\` and <code>&#124;</code>       |
-|`KC_NONUS_HASH`  |`KC_NUHS`|Non-US `#` and `~`                |
-|`KC_NONUS_BSLASH`|`KC_NUBS`|Non-US `\` and <code>&#124;</code>|
-|`KC_INT1`        |`KC_RO`  |JIS `\` and <code>&#124;</code>   |
-|`KC_INT2`        |`KC_KANA`|JIS Katakana/Hiragana             |
-|`KC_INT3`        |`KC_JYEN`|JIS `¥`                           |
-|`KC_SCOLON`      |`KC_SCLN`|`;` and `:`                       |
-|`KC_QUOTE`       |`KC_QUOT`|`'` and `"`                       |
-|`KC_GRAVE`       |`KC_GRV` |<code>&#96;</code> and `~`        |
-|`KC_COMMA`       |`KC_COMM`|`,` and `<`                       |
-|`KC_DOT`         |         |`.` and `>`                       |
-|`KC_SLASH`       |`KC_SLSH`|`/` and `?`                       |
-|`KC_CAPSLOCK`    |`KC_CAPS`|Caps Lock                         |
+|Key              |Aliases            |Description                                    |
+|-----------------|-------------------|-----------------------------------------------|
+|`KC_ENTER`       |`KC_ENT`           |Return (Enter)                                 |
+|`KC_ESCAPE`      |`KC_ESC`           |Escape                                         |
+|`KC_BSPACE`      |`KC_BSPC`          |Delete (Backspace)                             |
+|`KC_TAB`         |                   |Tab                                            |
+|`KC_SPACE`       |`KC_SPC`           |Spacebar                                       |
+|`KC_MINUS`       |`KC_MINS`          |`-` and `_`                                    |
+|`KC_EQUAL`       |`KC_EQL`           |`=` and `+`                                    |
+|`KC_LBRACKET`    |`KC_LBRC`          |`[` and `{`                                    |
+|`KC_RBRACKET`    |`KC_RBRC`          |`]` and `}`                                    |
+|`KC_BSLASH`      |`KC_BSLS`          |`\` and <code>&#124;</code>                    |
+|`KC_NONUS_HASH`  |`KC_NUHS`          |Non-US `#` and `~`                             |
+|`KC_SCOLON`      |`KC_SCLN`          |`;` and `:`                                    |
+|`KC_QUOTE`       |`KC_QUOT`          |`'` and `"`                                    |
+|`KC_GRAVE`       |`KC_GRV`, `KC_ZKHK`|<code>&#96;</code> and `~`, JIS Zenkaku/Hankaku|
+|`KC_COMMA`       |`KC_COMM`          |`,` and `<`                                    |
+|`KC_DOT`         |                   |`.` and `>`                                    |
+|`KC_SLASH`       |`KC_SLSH`          |`/` and `?`                                    |
+|`KC_NONUS_BSLASH`|`KC_NUBS`          |Non-US `\` and <code>&#124;</code>             |
+
+## Lock Keys
+
+|Key                |Aliases             |Description                         |
+|-------------------|--------------------|------------------------------------|
+|`KC_CAPSLOCK`      |`KC_CLCK`, `KC_CAPS`|Caps Lock                           |
+|`KC_SCROLLLOCK`    |`KC_SLCK`, `KC_BRMD`|Scroll Lock, Brightness Down (macOS)|
+|`KC_NUMLOCK`       |`KC_NLCK`           |Keypad Num Lock and Clear           |
+|`KC_LOCKING_CAPS`  |`KC_LCAP`           |Locking Caps Lock                   |
+|`KC_LOCKING_NUM`   |`KC_LNUM`           |Locking Num Lock                    |
+|`KC_LOCKING_SCROLL`|`KC_LSCR`           |Locking Scroll Lock                 |
 
 ## Modifiers
 
-|Key                |Aliases  |Description                         |
-|-------------------|---------|------------------------------------|
-|`KC_LCTRL`         |`KC_LCTL`|Left Control                        |
-|`KC_LSHIFT`        |`KC_LSFT`|Left Shift                          |
-|`KC_LALT`          |         |Left Alt                            |
-|`KC_LGUI`          |         |Left GUI (Windows/Command/Meta key) |
-|`KC_RCTRL`         |`KC_RCTL`|Right Control                       |
-|`KC_RSHIFT`        |`KC_RSFT`|Right Shift                         |
-|`KC_RALT`          |         |Right Alt                           |
-|`KC_RGUI`          |         |Right GUI (Windows/Command/Meta key)|
-|`KC_LOCKING_CAPS`  |`KC_LCAP`|Locking Caps Lock                   |
-|`KC_LOCKING_NUM`   |`KC_LNUM`|Locking Num Lock                    |
-|`KC_LOCKING_SCROLL`|`KC_LSCR`|Locking Scroll Lock                 |
-|`KC_INT4`          |`KC_HENK`|JIS Henkan                          |
-|`KC_INT5`          |`KC_MHEN`|JIS Muhenkan                        |
+|Key        |Aliases             |Description                         |
+|-----------|--------------------|------------------------------------|
+|`KC_LCTRL` |`KC_LCTL`           |Left Control                        |
+|`KC_LSHIFT`|`KC_LSFT`           |Left Shift                          |
+|`KC_LALT`  |                    |Left Alt                            |
+|`KC_LGUI`  |`KC_LCMD`, `KC_LWIN`|Left GUI (Windows/Command/Meta key) |
+|`KC_RCTRL` |`KC_RCTL`           |Right Control                       |
+|`KC_RSHIFT`|`KC_RSFT`           |Right Shift                         |
+|`KC_RALT`  |`KC_ALGR`           |Right Alt (AltGr)                   |
+|`KC_RGUI`  |`KC_RCMD`, `KC_RWIN`|Right GUI (Windows/Command/Meta key)|
+
+## International
+
+|Key       |Aliases  |Description                    |
+|----------|---------|-------------------------------|
+|`KC_INT1` |`KC_RO`  |JIS `\` and `_`                |
+|`KC_INT2` |`KC_KANA`|JIS Katakana/Hiragana          |
+|`KC_INT3` |`KC_JYEN`|JIS `¥` and <code>&#124;</code>|
+|`KC_INT4` |`KC_HENK`|JIS Henkan                     |
+|`KC_INT5` |`KC_MHEN`|JIS Muhenkan                   |
+|`KC_INT6` |         |JIS Numpad `,`                 |
+|`KC_INT7` |         |International 7                |
+|`KC_INT8` |         |International 8                |
+|`KC_INT9` |         |International 9                |
+|`KC_LANG1`|`KC_HAEN`|Hangul/English                 |
+|`KC_LANG2`|`KC_HANJ`|Hanja                          |
+|`KC_LANG3`|         |JIS Katakana                   |
+|`KC_LANG4`|         |JIS Hiragana                   |
+|`KC_LANG5`|         |JIS Zenkaku/Hankaku            |
+|`KC_LANG6`|         |Language 6                     |
+|`KC_LANG7`|         |Language 7                     |
+|`KC_LANG8`|         |Language 8                     |
+|`KC_LANG9`|         |Language 9                     |
 
 ## Commands
 
-|Key               |Aliases  |Description                   |
-|------------------|---------|------------------------------|
-|`KC_PSCREEN`      |`KC_PSCR`|Print Screen                  |
-|`KC_SCROLLLOCK`   |`KC_SLCK`|Scroll Lock                   |
-|`KC_PAUSE`        |`KC_PAUS`|Pause                         |
-|`KC_INSERT`       |`KC_INS` |Insert                        |
-|`KC_HOME`         |         |Home                          |
-|`KC_PGUP`         |         |Page Up                       |
-|`KC_DELETE`       |`KC_DEL` |Forward Delete                |
-|`KC_END`          |         |End                           |
-|`KC_PGDOWN`       |`KC_PGDN`|Page Down                     |
-|`KC_RIGHT`        |`KC_RGHT`|Right Arrow                   |
-|`KC_LEFT`         |         |Left Arrow                    |
-|`KC_DOWN`         |         |Down Arrow                    |
-|`KC_UP`           |         |Up Arrow                      |
-|`KC_APPLICATION`  |`KC_APP` |Application (Windows Menu Key)|
-|`KC_POWER`        |         |Power                         |
-|`KC_EXECUTE`      |         |Execute                       |
-|`KC_HELP`         |         |Help                          |
-|`KC_MENU`         |         |Menu                          |
-|`KC_SELECT`       |         |Select                        |
-|`KC_AGAIN`        |         |Again                         |
-|`KC_UNDO`         |         |Undo                          |
-|`KC_CUT`          |         |Cut                           |
-|`KC_COPY`         |         |Copy                          |
-|`KC_PASTE`        |         |Paste                         |
-|`KC_FIND`         |         |Find                          |
-|`KC_ALT_ERASE`    |         |Alternate Erase               |
-|`KC_SYSREQ`       |         |SysReq/Attention              |
-|`KC_CANCEL`       |         |Cancel                        |
-|`KC_CLEAR`        |         |Clear                         |
-|`KC_PRIOR`        |         |Prior                         |
-|`KC_RETURN`       |         |Return                        |
-|`KC_SEPARATOR`    |         |Separator                     |
-|`KC_OUT`          |         |Out                           |
-|`KC_OPER`         |         |Oper                          |
-|`KC_CLEAR_AGAIN`  |         |Clear/Again                   |
-|`KC_CRSEL`        |         |CrSel/Props                   |
-|`KC_EXSEL`        |         |ExSel                         |
+|Key               |Aliases                       |Description                   |
+|------------------|------------------------------|------------------------------|
+|`KC_PSCREEN`      |`KC_PSCR`                     |Print Screen                  |
+|`KC_PAUSE`        |`KC_PAUS`, `KC_BRK`, `KC_BRMU`|Pause, Brightness Up (macOS)  |
+|`KC_INSERT`       |`KC_INS`                      |Insert                        |
+|`KC_HOME`         |                              |Home                          |
+|`KC_PGUP`         |                              |Page Up                       |
+|`KC_DELETE`       |`KC_DEL`                      |Forward Delete                |
+|`KC_END`          |                              |End                           |
+|`KC_PGDOWN`       |`KC_PGDN`                     |Page Down                     |
+|`KC_RIGHT`        |`KC_RGHT`                     |Right Arrow                   |
+|`KC_LEFT`         |                              |Left Arrow                    |
+|`KC_DOWN`         |                              |Down Arrow                    |
+|`KC_UP`           |                              |Up Arrow                      |
+|`KC_APPLICATION`  |`KC_APP`                      |Application (Windows Menu Key)|
+|`KC_POWER`        |                              |System Power (macOS/Linux)    |
+|`KC_EXECUTE`      |`KC_EXEC`                     |Execute                       |
+|`KC_HELP`         |                              |Help                          |
+|`KC_MENU`         |                              |Menu                          |
+|`KC_SELECT`       |`KC_SLCT`                     |Select                        |
+|`KC_STOP`         |                              |Stop                          |
+|`KC_AGAIN`        |`KC_AGIN`                     |Again                         |
+|`KC_UNDO`         |                              |Undo                          |
+|`KC_CUT`          |                              |Cut                           |
+|`KC_COPY`         |                              |Copy                          |
+|`KC_PASTE`        |`KC_PSTE`                     |Paste                         |
+|`KC_FIND`         |                              |Find                          |
+|`KC__MUTE`        |                              |Mute (macOS)                  |
+|`KC__VOLUP`       |                              |Volume Up (macOS)             |
+|`KC__VOLDOWN`     |                              |Volume Down (macOS)           |
+|`KC_ALT_ERASE`    |`KC_ERAS`                     |Alternate Erase               |
+|`KC_SYSREQ`       |                              |SysReq/Attention              |
+|`KC_CANCEL`       |                              |Cancel                        |
+|`KC_CLEAR`        |`KC_CLR`                      |Clear                         |
+|`KC_PRIOR`        |                              |Prior                         |
+|`KC_RETURN`       |                              |Return                        |
+|`KC_SEPARATOR`    |                              |Separator                     |
+|`KC_OUT`          |                              |Out                           |
+|`KC_OPER`         |                              |Oper                          |
+|`KC_CLEAR_AGAIN`  |                              |Clear/Again                   |
+|`KC_CRSEL`        |                              |CrSel/Props                   |
+|`KC_EXSEL`        |                              |ExSel                         |
 
 ## Media Keys
 
@@ -165,41 +193,39 @@ These keycodes are not part of the Keyboard/Keypad usage page. The `SYSTEM_` key
 
 Windows and macOS use different keycodes for "next track" and "previous track". Make sure you choose the keycode that corresponds to your OS.
 
-|Key                    |Aliases  |Description                      |
-|-----------------------|---------|---------------------------------|
-|`KC_SYSTEM_POWER`      |`KC_PWR` |System Power Down                |
-|`KC_SYSTEM_SLEEP`      |`KC_SLEP`|System Sleep                     |
-|`KC_SYSTEM_WAKE`       |`KC_WAKE`|System Wake                      |
-|`KC_MAIL`              |`KC_MAIL`|                                 |
-|`KC_CALCULATOR`        |`KC_CALC`|                                 |
-|`KC_MY_COMPUTER`       |`KC_MYCM`|                                 |
-|`KC_WWW_SEARCH`        |`KC_WSCH`|                                 |
-|`KC_WWW_HOME`          |`KC_WHOM`|                                 |
-|`KC_WWW_BACK`          |`KC_WBAK`|                                 |
-|`KC_WWW_FORWARD`       |`KC_WFWD`|                                 |
-|`KC_WWW_STOP`          |`KC_WSTP`|                                 |
-|`KC_WWW_REFRESH`       |`KC_WREF`|                                 |
-|`KC_STOP`              |         |Stop                             |
-|`KC_WWW_FAVORITES`     |`KC_WFAV`|                                 |
-|`KC__MUTE`             |         |Mute (macOS)                     |
-|`KC__VOLUP`            |         |Volume Up (macOS)                |
-|`KC__VOLDOWN`          |         |Volume Down (macOS)              |
-|`KC_AUDIO_MUTE`        |`KC_MUTE`|Mute (Windows/macOS/Linux)       |
-|`KC_AUDIO_VOL_UP`      |`KC_VOLU`|Volume Up (Windows/macOS/Linux)  |
-|`KC_AUDIO_VOL_DOWN`    |`KC_VOLD`|Volume Down (Windows/macOS/Linux)|
-|`KC_MEDIA_NEXT_TRACK`  |`KC_MNXT`|Next Track (Windows)             |
-|`KC_MEDIA_PREV_TRACK`  |`KC_MPRV`|Previous Track (Windows)         |
-|`KC_MEDIA_FAST_FORWARD`|`KC_MFFD`|Next Track (macOS)               |
-|`KC_MEDIA_REWIND`      |`KC_MRWD`|Previous Track (macOS)           |
-|`KC_MEDIA_STOP`        |`KC_MSTP`|Stop Track                       |
-|`KC_MEDIA_PLAY_PAUSE`  |`KC_MPLY`|Play/Pause Track                 |
-|`KC_MEDIA_SELECT`      |`KC_MSEL`|                                 |
+|Key                    |Aliases  |Description                  |
+|-----------------------|---------|-----------------------------|
+|`KC_SYSTEM_POWER`      |`KC_PWR` |System Power Down            |
+|`KC_SYSTEM_SLEEP`      |`KC_SLEP`|System Sleep                 |
+|`KC_SYSTEM_WAKE`       |`KC_WAKE`|System Wake                  |
+|`KC_AUDIO_MUTE`        |`KC_MUTE`|Mute                         |
+|`KC_AUDIO_VOL_UP`      |`KC_VOLU`|Volume Up                    |
+|`KC_AUDIO_VOL_DOWN`    |`KC_VOLD`|Volume Down                  |
+|`KC_MEDIA_NEXT_TRACK`  |`KC_MNXT`|Next Track (Windows)         |
+|`KC_MEDIA_PREV_TRACK`  |`KC_MPRV`|Previous Track (Windows)     |
+|`KC_MEDIA_STOP`        |`KC_MSTP`|Stop Track (Windows)         |
+|`KC_MEDIA_PLAY_PAUSE`  |`KC_MPLY`|Play/Pause Track             |
+|`KC_MEDIA_SELECT`      |`KC_MSEL`|Launch Media Player (Windows)|
+|`KC_MEDIA_EJECT`       |`KC_EJCT`|Eject (macOS)                |
+|`KC_MAIL`              |         |Launch Mail (Windows)        |
+|`KC_CALCULATOR`        |`KC_CALC`|Launch Calculator (Windows)  |
+|`KC_MY_COMPUTER`       |`KC_MYCM`|Launch My Computer (Windows) |
+|`KC_WWW_SEARCH`        |`KC_WSCH`|Browser Search (Windows)     |
+|`KC_WWW_HOME`          |`KC_WHOM`|Browser Home (Windows)       |
+|`KC_WWW_BACK`          |`KC_WBAK`|Browser Back (Windows)       |
+|`KC_WWW_FORWARD`       |`KC_WFWD`|Browser Forward (Windows)    |
+|`KC_WWW_STOP`          |`KC_WSTP`|Browser Stop (Windows)       |
+|`KC_WWW_REFRESH`       |`KC_WREF`|Browser Refresh (Windows)    |
+|`KC_WWW_FAVORITES`     |`KC_WFAV`|Browser Favorites (Windows)  |
+|`KC_MEDIA_FAST_FORWARD`|`KC_MFFD`|Next Track (macOS)           |
+|`KC_MEDIA_REWIND`      |`KC_MRWD`|Previous Track (macOS)       |
+|`KC_BRIGHTNESS_UP`     |`KC_BRIU`|Brightness Up                |
+|`KC_BRIGHTNESS_DOWN`   |`KC_BRID`|Brightness Down              |
 
 ## Number Pad
 
 |Key                |Aliases  |Description                   |
 |-------------------|---------|------------------------------|
-|`KC_NUMLOCK`       |`KC_NLCK`|Keypad Num Lock and Clear     |
 |`KC_KP_SLASH`      |`KC_PSLS`|Keypad `/`                    |
 |`KC_KP_ASTERISK`   |`KC_PAST`|Keypad `*`                    |
 |`KC_KP_MINUS`      |`KC_PMNS`|Keypad `-`                    |
@@ -224,7 +250,7 @@ Windows and macOS use different keycodes for "next track" and "previous track".
 
 In addition to these, keycodes in the range of `0xA5-DF` are reserved for internal use by TMK.
 
-|Key             |Aliases  |Description                            |
-|----------------|---------|---------------------------------------|
-|`KC_NO`         |         |Ignore this key (NOOP)                 |
-|`KC_TRANSPARENT`|`KC_TRNS`|Use the next lowest non-transparent key|
+|Key             |Aliases             |Description                            |
+|----------------|--------------------|---------------------------------------|
+|`KC_NO`         |`XXXXXXX`           |Ignore this key (NOOP)                 |
+|`KC_TRANSPARENT`|`KC_TRNS`, `_______`|Use the next lowest non-transparent key|

docs/keycodes_us_ansi_shifted.md

@@ -1,31 +1,37 @@
 # US ANSI Shifted Symbols
 
-These keycodes correspond to characters that are "shifted" on a standard US ANSI keyboards. They do not have dedicated keycodes but are instead typed by holding down shift and then sending a keycode.
+These keycodes correspond to characters that are "shifted" on a standard US ANSI keyboard. They do not have keycodes of their own but are simply shortcuts for `LSFT(kc)`, and as such send a Left Shift with the unshifted keycode, not the symbol itself.
 
-It's important to remember that all of these keycodes send a left shift - this may cause unintended actions if unaccounted for. The short code is preferred in most situations.
+## Caveats
 
-## US ANSI Shifted Keycodes
+Unfortunately, these keycodes cannot be used in Mod-Taps or Layer-Taps, since any modifiers specified in the keycode are ignored.
 
-|Key                     |Aliases           |Description        |
-|------------------------|------------------|-------------------|
-|`KC_TILDE`              |`KC_TILD`         |`~`                |
-|`KC_EXCLAIM`            |`KC_EXLM`         |`!`                |
-|`KC_AT`                 |                  |`@`                |
-|`KC_HASH`               |                  |`#`                |
-|`KC_DOLLAR`             |`KC_DLR`          |`$`                |
-|`KC_PERCENT`            |`KC_PERC`         |`%`                |
-|`KC_CIRCUMFLEX`         |`KC_CIRC`         |`^`                |
-|`KC_AMPERSAND`          |`KC_AMPR`         |`&`                |
-|`KC_ASTERISK`           |`KC_ASTR`         |`*`                |
-|`KC_LEFT_PAREN`         |`KC_LPRN`         |`(`                |
-|`KC_RIGHT_PAREN`        |`KC_RPRN`         |`)`                |
-|`KC_UNDERSCORE`         |`KC_UNDS`         |`_`                |
-|`KC_PLUS`               |                  |`+`                |
-|`KC_LEFT_CURLY_BRACE`   |`KC_LCBR`         |`{`                |
-|`KC_RIGHT_CURLY_BRACE`  |`KC_RCBR`         |`}`                |
-|`KC_PIPE`               |                  |<code>&#124;</code>|
-|`KC_COLON`              |`KC_COLN`         |`:`                |
-|`KC_DOUBLE_QUOTE`       |`KC_DQT`/`KC_DQUO`|`"`                |
-|`KC_LEFT_ANGLE_BRACKET` |`KC_LT`/`KC_LABK` |`<`                |
-|`KC_RIGHT_ANGLE_BRACKET`|`KC_GT`/`KC_RABK` |`>`                |
-|`KC_QUESTION`           |`KC_QUES`         |`?`                |
+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.
+
+## Keycodes
+
+|Key                     |Aliases            |Description        |
+|------------------------|-------------------|-------------------|
+|`KC_TILDE`              |`KC_TILD`          |`~`                |
+|`KC_EXCLAIM`            |`KC_EXLM`          |`!`                |
+|`KC_AT`                 |                   |`@`                |
+|`KC_HASH`               |                   |`#`                |
+|`KC_DOLLAR`             |`KC_DLR`           |`$`                |
+|`KC_PERCENT`            |`KC_PERC`          |`%`                |
+|`KC_CIRCUMFLEX`         |`KC_CIRC`          |`^`                |
+|`KC_AMPERSAND`          |`KC_AMPR`          |`&`                |
+|`KC_ASTERISK`           |`KC_ASTR`          |`*`                |
+|`KC_LEFT_PAREN`         |`KC_LPRN`          |`(`                |
+|`KC_RIGHT_PAREN`        |`KC_RPRN`          |`)`                |
+|`KC_UNDERSCORE`         |`KC_UNDS`          |`_`                |
+|`KC_PLUS`               |                   |`+`                |
+|`KC_LEFT_CURLY_BRACE`   |`KC_LCBR`          |`{`                |
+|`KC_RIGHT_CURLY_BRACE`  |`KC_RCBR`          |`}`                |
+|`KC_PIPE`               |                   |<code>&#124;</code>|
+|`KC_COLON`              |`KC_COLN`          |`:`                |
+|`KC_DOUBLE_QUOTE`       |`KC_DQUO`, `KC_DQT`|`"`                |
+|`KC_LEFT_ANGLE_BRACKET` |`KC_LABK`, `KC_LT` |`<`                |
+|`KC_RIGHT_ANGLE_BRACKET`|`KC_RABK`, `KC_GT` |`>`                |
+|`KC_QUESTION`           |`KC_QUES`          |`?`                |

docs/keymap.md

@@ -33,7 +33,7 @@ The state of the Keymap layer is determined by two 32 bit parameters:
 * **`default_layer_state`** indicates a base keymap layer (0-31) which is always valid and to be referred (the default layer).
 * **`layer_state`** has current on/off status of each layer in its bits.
 
-Keymap layer '0' is usually `default_layer`, wither other layers initially off after booting up the firmware, although this can configured differently in `config.h`. It is useful to change `default_layer` when you completely switch a key layout, for example, if you want to switch to Colemak instead of Qwerty.
+Keymap layer '0' is usually the `default_layer`, with other layers initially off after booting up the firmware, although this can configured differently in `config.h`. It is useful to change `default_layer` when you completely switch a key layout, for example, if you want to switch to Colemak instead of Qwerty.
 
     Initial state of Keymap          Change base layout
     -----------------------          ------------------
@@ -89,11 +89,15 @@ There are 3 main sections of a `keymap.c` file you'll want to concern yourself w
 
 At the top of the file you'll find this:
 
-    #include "clueboard.h"
+    #include QMK_KEYBOARD_H
 
     // Helpful defines
     #define GRAVE_MODS  (MOD_BIT(KC_LSHIFT)|MOD_BIT(KC_RSHIFT)|MOD_BIT(KC_LGUI)|MOD_BIT(KC_RGUI)|MOD_BIT(KC_LALT)|MOD_BIT(KC_RALT))
-    #define _______ KC_TRNS
+
+    /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * 
+     *  You can use _______ in place for KC_TRNS (transparent)   *
+     *  Or you can use XXXXXXX for KC_NO (NOOP)                  *
+     * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 
     // Each layer gets a name for readability.
     // The underscores don't mean anything - you can
@@ -105,7 +109,9 @@ At the top of the file you'll find this:
     #define _FL 1
     #define _CL 2
 
-These are some handy definitions we can use when building our keymap and our custom function. The `GRAVE_MODS` definition will be used later in our custom function. The `_______` define makes it easier to see what keys a layer is overriding, while the `_BL`, `_FL`, and `_CL` defines make it easier to refer to each of our layers.
+These are some handy definitions we can use when building our keymap and our custom function. The `GRAVE_MODS` definition will be used later in our custom function, and the following `_BL`, `_FL`, and `_CL` defines make it easier to refer to each of our layers.
+
+Note: You may also find some older keymap files may also have a define(s) for `_______` and/or `XXXXXXX`. These can be used in place for `KC_TRNS` and `KC_NO` respectively, making it easier to see what keys a layer is overriding. These definitions are now unecessary, as they are included by default.
 
 ### Layers and Keymaps
 
@@ -171,6 +177,8 @@ In this case we've instructed QMK to call the `ACTION_FUNCTION` callback, which
 
 > This `fn_actions[]` interface is mostly for backward compatibility.  In QMK, you don't need to use `fn_actions[]`.  You can directly use `ACTION_FUNCTION(N)` or any other action code value itself normally generated by the macro in `keymaps[][MATRIX_ROWS][MATRIX_COLS]`.  N in `F(N)` can only be 0 to 31.  Use of the action code directly in `keymaps` unlocks this limitation.
 
+You can get a full list of Action Functions in [action_code.h](https://github.com/qmk/qmk_firmware/blob/master/tmk_core/common/action_code.h). 
+
 #### `action_function()`
 
 To actually handle the keypress event we define an `action_function()`. This function will be called when the key is pressed, and then again when the key is released. We have to handle both situations within our code, as well as determining whether to send/release `KC_ESC` or `KC_GRAVE`.

docs/newbs.md

@@ -0,0 +1,23 @@
+# The Complete Newbs Guide To QMK
+
+QMK is a powerful Open Source firmware for your mechanical keyboard. You can use QMK to customize your keyboard in ways both simple and powerful. People of all skill levels, from complete newbie to master programmer, have successfully used QMK to customize their keyboard. This guide will help you do the same, no matter your skill level.
+
+Not sure if your keyboard can run QMK? If it's a mechanical keyboard you built yourself chances are good it can. We support a [large number of hobbyist boards](http://qmk.fm/keyboards/), so even if your current keyboard can't run QMK you shouldn't have trouble finding one to suit your needs.
+
+## Overview
+
+There are 7 main sections to this guide:
+
+* [Getting Started](newbs_getting_started.md)
+* [Building Your First Firmware using the command line](newbs_building_firmware.md)
+* [Building Your First Firmware using the online GUI](newbs_building_firmware_configurator.md)
+* [Flashing Firmware](newbs_flashing.md)
+* [Testing and Debugging](newbs_testing_debugging.md)
+* [Git Best Practices](newbs_best_practices.md)
+* [Learn More with these Resources](newbs_learn_more_resources.md)
+
+This guide is focused on helping someone who has never compiled software before. It makes choices and recommendations based on that viewpoint. There are alternative methods for many of these procedures, and we support most of those alternatives. If you have any doubt about how to accomplish a task you can [ask us for guidance](getting_started_getting_help.md).
+
+## Additional Resources
+
+* [Thomas Baart's QMK Basics Blog](https://thomasbaart.nl/category/mechanical-keyboards/firmware/qmk/qmk-basics/) – A user-created blog covering the basics of how to use QMK Firmware, as seen from a new user's perspective.

docs/newbs_best_practices.md

@@ -0,0 +1,163 @@
+# Best Practices
+
+## Or, "How I Learned to Stop Worrying and Love Git."
+
+This document aims to instruct novices in the best ways to have a smooth experience in contributing to QMK. We will walk through the process of contributing to QMK, detailing some ways to make this task easier, and then later we'll break some things in order to teach you how to fix them.
+
+This document assumes a few things:
+
+1. You have a GitHub account, and have [forked the qmk_firmware repository](getting_started_github.md) to your account.
+2. You've [set up your build environment](newbs_getting_started.md?id=environment-setup).
+
+
+## Your fork's master: Update Often, Commit Never
+
+It is highly recommended for QMK development, regardless of what is being done or where, to keep your `master` branch updated, but ***never*** commit to it. Instead, do all your changes in a development branch and issue pull requests from your branches when you're developing.
+
+To reduce the chances of merge conflicts — instances where two or more users have edited the same part of a file concurrently — keep your `master` branch relatively up-to-date, and start any new developments by creating a new branch.
+
+### Updating your master branch
+
+To keep your `master` branch updated, it is recommended to add the QMK Firmware repository ("repo") as a remote repository in git. To do this, open your Git command line interface and enter:
+
+```
+git remote add upstream https://github.com/qmk/qmk_firmware.git
+```
+
+To verify that the repository has been added, run `git remote -v`, which should return the following:
+
+```
+$ 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)
+```
+
+Now that this is done, you can check for updates to the repo by running `git fetch upstream`. This retrieves the branches and tags &mdash; collectively referred to as "refs" &mdash; from the QMK repo, which now has the nickname `upstream`. We can now compare the data on our fork `origin` to that held by QMK.
+
+To update your fork's master, run the following, hitting the Enter key after each line:
+
+```
+git checkout master
+git fetch upstream
+git pull upstream master
+git push origin master
+```
+
+This switches you to your `master` branch, retrieves the refs from the QMK repo, downloads the current QMK `master` branch to your computer, and then uploads it to your fork.
+
+### Making Changes
+
+To make changes, create a new branch by entering:
+
+```
+git checkout -b dev_branch
+git push --set-upstream origin dev_branch
+```
+
+This creates a new branch named `dev_branch`, checks it out, and then saves the new branch to your fork. The `--set-upstream` argument tells git to use your fork and the `dev_branch` branch every time you use `git push` or `git pull` from this branch. It only needs to be used on the first push; after that, you can safely use `git push` or `git pull`, without the rest of the arguments.
+
+!> With `git push`, you can use `-u` in place of `--set-upstream` &mdash; `-u` is an alias for `--set-upstream`.
+
+You can name your branch nearly anything you want, though it is recommended to name it something related to the changes you are going to make.
+
+By default `git checkout -b` will base your new branch on the branch that is checked out. You can base your new branch on an existing branch that is not checked out by adding the name of the existing branch to the command:
+
+```
+git checkout -b dev_branch master
+```
+
+Now that you have a development branch, open your text editor and make whatever changes you need to make. It is recommended to make many small commits to your branch; that way, any change that causes issues can be more easily traced and undone if needed. To make your changes, edit and save any files that need to be updated, add them to Git's *staging area*, and then commit them to your branch:
+
+```
+git add path/to/updated_file
+git commit -m "My commit message."
+```
+
+`git add` adds files that have been changed to Git's *staging area*, which is Git's "loading zone." This contains the changes that are going to be *committed* by `git commit`, which saves the changes to the repo. Use descriptive commit messages so you can know what was changed at a glance.
+
+!> If you've changed a lot of files, but all the files are part of the same change, you can use `git add .` to add all the changed files that are in your current directory, rather than having to add each file individually.
+
+### Publishing Your Changes
+
+The last step is to push your changes to your fork. To do this, enter `git push`. Git now publishes the current state of `dev_branch` to your fork.
+
+
+## Resolving Merge Conflicts
+
+Sometimes when your work in a branch takes a long time to complete, changes that have been made by others conflict with changes you have made to your branch when you open a pull request. This is called a *merge conflict*, and is what happens when multiple people edit the same parts of the same files.
+
+### Rebasing Your Changes
+
+A *rebase* is Git's way of taking changes that were applied at one point, reversing them, and then applying the same changes to another point. In the case of a merge conflict, you can rebase your branch to grab the changes that were made between when you created your branch and the present time.
+
+To start, run the following:
+
+```
+git fetch upstream
+git rev-list --left-right --count HEAD...upstream/master
+```
+
+The `git rev-list` command entered here returns the number of commits that differ between the current branch and QMK's master branch. We run `git fetch` first to make sure we have the refs that represent the current state of the upstream repo. The output of the `git rev-list` command entered returns two numbers:
+
+```
+$ git rev-list --left-right --count HEAD...upstream/master
+7       35
+```
+
+The first number represents the number of commits on the current branch since it was created, and the second number is the number of commits made to `upstream/master` since the current branch was created, and thus, the changes that are not recorded in the current branch.
+
+Now that the current states of both the current branch and the upstream repo are known, we can start a rebase operation:
+
+```
+git rebase upstream/master
+```
+
+This tells Git to undo the commits on the current branch, and then reapply them against QMK's master branch.
+
+```
+$ 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".
+```
+
+This tells us that we have a merge conflict, and gives the name of the file with the conflict. Open the conflicting file in your text editor, and somewhere in the file, you'll find something like this:
+
+```
+<<<<<<< HEAD
+<p>For help with any issues, email us at support@webhost.us.</p>
+=======
+<p>Need help? Email support@webhost.us.</p>
+>>>>>>> Commit #1
+```
+
+The line `<<<<<<< HEAD` marks the beginning of a merge conflict, and the `>>>>>>> Commit #1` line marks the end, with the conflicting sections separated by `=======`. The part on the `HEAD` side is from the QMK master version of the file, and the part marked with the commit message is from the current branch and commit.
+
+Because Git tracks *changes to files* rather than the contents of the files directly, if Git can't find the text that was in the file previous to the commit that was made, it won't know how to edit the file. Re-editing the file will solve the conflict. Make your changes, and then save the file.
+
+```
+<p>Need help? Email support@webhost.us.</p>
+```
+
+Now run:
+
+```
+git add conflicting_file_1.txt
+git rebase --continue
+```
+
+Git logs the changes to the conflicting file, and continues applying the commits from our branch until it reaches the end.

docs/newbs_building_firmware.md

@@ -0,0 +1,81 @@
+# Building Your First Firmware
+
+Now that you have setup your build environment you are ready to start building custom firmware. For this section of the guide we will bounce between 3 programs- your file manager, your text editor, and your terminal window. Keep all 3 open until you are done and happy with your keyboard firmware.
+
+If you have closed and reopened your terminal window since following the first part of the guide, don't forget to `cd qmk_firmware` so that your terminal is in the correct directory.
+
+## Navigate To Your Keymaps Folder
+
+Start by navigating to the `keymaps` folder for your keyboard.
+
+?> If you are on macOS or Windows there are commands you can use to easily open the keymaps folder.
+
+?> macOS:
+
+    open keyboards/<keyboard_folder>/keymaps
+
+?> Windows:
+
+    start .\\keyboards\\<keyboard_folder>\\keymaps
+
+## Create a Copy Of The `default` Keymap
+
+Once you have the `keymaps` folder open you will want to create a copy of the `default` folder. We highly recommend you name your folder the same as your GitHub username, but you can use any name you want as long as it contains only lower case letters, numbers, and the underscore character.
+
+To automate the process, you also have the option to run the `new_keymap.sh` script. 
+
+Navigate to the `qmk_firmware/util` directory and type the following:
+
+```
+./new_keymap.sh <keyboard path> <username>
+```
+
+For example, for a user named John, trying to make a new keymap for the 1up60hse, they would type in
+
+```
+./new_keymap.sh 1upkeyboards/1up60hse john
+```
+
+## Open `keymap.c` In Your Favorite Text Editor
+
+Open up your `keymap.c`. Inside this file you'll find the structure that controls how your keyboard behaves. At the top of `keymap.c` there may be some defines and enums that make the keymap easier to read. Farther down you'll find a line that looks like this:
+
+    const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
+
+This line indicates the start of the list of Layers. Below that you'll find lines containing either `LAYOUT` or `KEYMAP`, and these lines indicate the start of a layer. Below that line is the list of keys that comprise a that particular layer.
+
+!> When editing your keymap file be careful not to add or remove any commas. If you do you will prevent your firmware from compiling and it may not be easy to figure out where the extra, or missing, comma is.
+
+## Customize The Layout To Your Liking
+
+How to complete this step is entirely up to you. Make the one change that's been bugging you, or completely rework everything. You can remove layers if you don't need all of them, or add layers up to a total of 32. Check the following documentation to find out what you can define here:
+
+* [Keycodes](keycodes.md)
+* [Features](features.md)
+* [FAQ](faq.md)
+
+?> While you get a feel for how keymaps work, keep each change small. Bigger changes make it harder to debug any problems that arise.
+
+## Build Your Firmware
+
+When your changes to the keymap are complete you will need to build the firmware. To do so go back to your terminal window and run the build command:
+
+    make <my_keyboard>:<my_keymap>
+
+For example, if your keymap is named "xyverz" and you're building a keymap for a rev5 planck, you'll use this command:
+
+    make planck/rev5:xyverz
+
+While this compiles you will have a lot of output going to the screen informing you of what files are being compiled. It should end with output that looks similar to this:
+
+```
+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
+```
+
+## Flash Your Firmware
+
+Move on to [Flashing Firmware](newbs_flashing.md) to learn how to write your new firmware to your keyboard.

docs/newbs_building_firmware_configurator.md

@@ -0,0 +1,105 @@
+# QMK Configurator
+
+The [QMK Configurator](https://config.qmk.fm) is an online graphical user interface that generates QMK Firmware hex files.  
+
+?> **Please follow these steps in order.**
+
+Watch the [Video Tutorial](https://youtu.be/7RH-1pAbjvw)
+
+The QMK Configurator works best with Chrome/Firefox. 
+
+
+!> **Files from other tools such as KLE, or kbfirmware will not be compatible with QMK Configurator. Do not load them, do not import them. QMK Configurator is a DIFFERENT tool. **
+
+## Selecting your keyboard
+
+Click the drop down box and select the keyboard you want to create a keymap for. 
+
+?> If your keyboard has several versions, make sure you select the correct one.** 
+
+I'll say that again because it's important
+
+!> **MAKE SURE YOU SELECT THE RIGHT VERSION!**
+
+If your keyboard has been advertised to be powered by QMK but is not in the list, chances are a developer hasn't gotten to it yet or we haven't had a chance to merge it in yet. File an issue at [qmk_firmware](https://github.com/qmk/qmk_firmware/issues) requesting to support that particular keyboard, if there is no active [Pull Request](https://github.com/qmk/qmk_firmware/pulls?q=is%3Aopen+is%3Apr+label%3Akeyboard) for it. There are also QMK powered keyboards that are in their manufacturer's own github accounts. Double check for that as well. 
+
+## Selecting your keyboard layout
+
+Choose the layout that best represents the keymap you want to create. Some keyboards do not have enough layouts or correct layouts defined yet. They will be supported in the future. 
+
+## Keymap Name
+
+Call this keymap what you want. 
+
+?> If you are running into issues when compiling, it may be worth changing this name, as it may already exist in the QMK  Firmware repo.
+
+## Creating Your Keymap
+
+Keycode Entry is accomplished in 3 ways.  
+1. Drag and dropping 
+2. Clicking on an empty spot on the layout and clicking the keycode you desire
+3. Clicking on an empty spot on the layout, pressing the physical key on your keyboard. 
+
+Hover your mouse over a key and a short blurb will tell you what that keycode does. For a more verbose description please see    
+
+[Basic Keycode Reference](https://docs.qmk.fm/#/keycodes_basic)    
+[Advanced Keycode Reference](https://docs.qmk.fm/#/feature_advanced_keycodes)    
+
+In the event that you can't find a layout that supports your keymap, for example three spots for spacebar, or two spots for backspace, or 2 spots for shift etc etc, Fill them ALL up. 
+
+### Example:
+
+3 spots for spacebar: Fill them ALL with spacebar
+
+2 spots for backspace: Fill them BOTH with backspace
+
+2 spots for right shift: Fill them BOTH with right shift
+
+1 spot for left shift and 1 spot for iso support: Fill them both with left shift
+
+5 spots, but only 4 keys: Guess and check or ask someone who has done it before. 
+
+## Saving Your Keymap for Future Edits
+
+When you're satisfied with your keymap or just want to work on it later, press the `Export Keymap` button. It will save your keymap as the name you chose above appended with .json. 
+
+You can then load this .json file in the future by pressing the `Import Keymap` button. 
+
+!> **CAUTION:** This is not the same type of .json file used for kbfirmware.com or any other tool. If you try to use this for those tools, or the .json from those tools with QMK Configurator, there is a chance your keyboard will **explode**. 
+
+## Generating your firmware file
+
+Press the green `Compile` button.
+
+When the compilation is done, you will be able to press the green `Download Firmware` button. 
+
+## Flashing Your Keyboard
+
+Please refer to [Flashing Firmware](newbs_flashing.md)
+
+## Troubleshooting
+
+#### My .json file is not working
+
+If the .json file was generated with QMK Configurator, congratulations you have stumbled upon a bug. File an issue at [qmk_configurator](https://github.com/qmk/qmk_configurator/issues)
+
+If not....how did you miss my big bold message at the top saying not to use other .json files? 
+
+#### There are extra spaces in my layout? What do I do? 
+
+If you're referring to having three spots for space bar, the best course of action is to just fill them all with space bar. The same can be done for backspace and shifts
+
+#### What is the keycode for.......
+
+Please see
+
+[Basic Keycode Reference](https://docs.qmk.fm/#/keycodes_basic)    
+[Advanced Keycode Reference](https://docs.qmk.fm/#/feature_advanced_keycodes)    
+
+#### It won't compile
+
+Please double check the other layers of your keymap to make sure there are no random keys present. 
+
+## Problems and Bugs
+
+We are always accepting customer requests and bug reports. Please file them at [qmk_configurator](https://github.com/qmk/qmk_configurator/issues)

docs/newbs_flashing.md

@@ -0,0 +1,240 @@
+# Flashing Your Keyboard 
+
+Now that you've built a custom firmware file you'll want to flash your keyboard. 
+
+## Flashing Your Keyboard with QMK Toolbox
+
+The simplest way to flash your keyboard will be with the [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases). 
+
+However, the QMK Toolbox is only available for Windows and macOS currently.  If you're using Linux (or just wish to flash the firmware from the command line), you'll have to use the [method outlined below](newbs_flashing.md#flash-your-keyboard-from-the-command-line).
+
+### Load The File Into QMK Toolbox
+
+Begin by opening the QMK Toolbox application. You'll want to locate the firmware file in Finder or Explorer. Your keyboard firmware may be in one of two formats- `.hex` or `.bin`. QMK tries to copy the appropriate one for your keyboard into the root `qmk_firmware` directory.
+
+?> If you are on Windows or macOS there are commands you can use to easily open the current firmware folder in Explorer or Finder.
+
+?> Windows:
+
+    start .
+
+?> macOS:
+
+    open .
+
+The firmware file always follows this naming format:
+
+    <keyboard_name>_<keymap_name>.{bin,hex}
+
+For example, the `plank/rev5` with a `default` keymap will have this filename:
+
+    planck_rev5_default.hex
+
+Once you have located your firmware file drag it into the "Local file" box in QMK Toolbox, or click "Open" and navigate to where your firmware file is stored. 
+
+### Put Your Keyboard Into DFU (Bootloader) Mode
+
+In order to flash your custom firmware you have to put your keyboard into a special flashing mode. While it is in this mode you will not be able to type or otherwise use your keyboard. It is very important that you do not unplug your keyboard or otherwise interrupt the flashing process while the firmware is being written.
+
+Different keyboards have different ways to enter this special mode. If your PCB currently runs QMK or TMK and you have not been given specific instructions try the following, in order:
+
+* Hold down both shift keys and press `Pause`
+* Hold down both shift keys and press `B`
+* Unplug your keyboard, hold down the Spacebar and `B` at the same time, plug in your keyboard and wait a second before releasing the keys
+* Press the physical `RESET` button on the bottom of the PCB
+* Locate header pins on the PCB labeled `BOOT0` or `RESET`, short those together while plugging your PCB in
+
+When you are successful you will see a message similar to this in QMK Toolbox:
+
+```
+*** Clueboard - Clueboard 66% HotSwap disconnected -- 0xC1ED:0x2390
+*** DFU device connected
+```
+
+### Flash Your Keyboard
+
+Click the `Flash` button in QMK Toolbox. You will see output similar to the following:
+
+```
+*** Clueboard - Clueboard 66% HotSwap disconnected -- 0xC1ED:0x2390
+*** DFU device connected
+*** Attempting to flash, please don't remove device
+>>> dfu-programmer atmega32u4 erase --force
+    Erasing flash...  Success
+    Checking memory from 0x0 to 0x6FFF...  Empty.
+>>> dfu-programmer atmega32u4 flash /Users/skully/qmk_firmware/clueboard_66_hotswap_gen1_skully.hex
+    Checking memory from 0x0 to 0x55FF...  Empty.
+    0%                            100%  Programming 0x5600 bytes...
+    [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>]  Success
+    0%                            100%  Reading 0x7000 bytes...
+    [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>]  Success
+    Validating...  Success
+    0x5600 bytes written into 0x7000 bytes memory (76.79%).
+>>> dfu-programmer atmega32u4 reset
+    
+*** DFU device disconnected
+*** Clueboard - Clueboard 66% HotSwap connected -- 0xC1ED:0x2390
+```
+
+## Flash your Keyboard from the Command Line
+
+First thing you'll need to know is which bootloader that your keyboard uses.  There are four main bootloaders that are used, usually. Pro-Micro and clones use CATERINA, and Teensy's use Halfkay, OLKB boards use QMK-DFU, and other atmega32u4 chips use DFU. 
+
+You can find more information about the bootloaders in the [Flashing Instructions and Bootloader Information](flashing.md) page. 
+
+If you know what bootloader that you're using, then when compiling the firmware, you can actually add some extra text to the `make` command to automate the flashing process. 
+
+### DFU
+
+For the DFU bootloader, when you're ready to compile and flash your firmware, open up your terminal window and run the built command: 
+
+    make <my_keyboard>:<my_keymap>:dfu
+
+For example, if your keymap is named "xyverz" and you're building a keymap for a rev5 planck, you'll use this command:
+
+    make planck/rev5:xyverz:dfu
+
+Once it finishes compiling, it should output the following:
+
+```
+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                                                        
+ * File size is fine - 18574/28672
+ ```
+
+After it gets to this point, the build script will look for the DFU bootloader every 5 seconds.  It will repeat the following until the device is found or you cancel it. 
+
+    dfu-programmer: no device present.
+    Error: Bootloader not found. Trying again in 5s.
+
+Once it does this, you'll want to reset the controller.  It should then show output similiar to this: 
+
+```
+*** Attempting to flash, please don't remove device
+>>> dfu-programmer atmega32u4 erase --force
+    Erasing flash...  Success
+    Checking memory from 0x0 to 0x6FFF...  Empty.
+>>> dfu-programmer atmega32u4 flash /Users/skully/qmk_firmware/clueboard_66_hotswap_gen1_skully.hex
+    Checking memory from 0x0 to 0x55FF...  Empty.
+    0%                            100%  Programming 0x5600 bytes...
+    [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>]  Success
+    0%                            100%  Reading 0x7000 bytes...
+    [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>]  Success
+    Validating...  Success
+    0x5600 bytes written into 0x7000 bytes memory (76.79%).
+>>> dfu-programmer atmega32u4 reset
+```
+
+If you have any issues with this, you may need to this: 
+
+    sudo make <my_keyboard>:<my_keymap>:dfu
+
+### Caterina 
+
+For Arduino boards and their close (such as the SparkFun ProMicro), when you're ready to compile and flash your firmware, open up your terminal window and run the built command: 
+
+    make <my_keyboard>:<my_keymap>:avrdude
+
+For example, if your keymap is named "xyverz" and you're building a keymap for a rev2 Lets Split, you'll use this command:
+
+    make lets_split/rev2:xyverz:avrdude
+
+Once the firmware finishes compiling, it will output something like this: 
+
+```
+Linking: .build/lets_split_rev2_xyverz.elf                                                            [OK]
+Creating load file for flashing: .build/lets_split_rev2_xyverz.hex                                    [OK]
+Checking file size of lets_split_rev2_xyverz.hex                                                      [OK]
+ * File size is fine - 27938/28672
+Detecting USB port, reset your controller now..............
+```
+
+At this point, reset the board and then the script will detect the bootloader and then flash the board.  The output should look something like this: 
+
+```
+Detected controller on USB port at /dev/ttyS15
+
+Connecting to programmer: .
+Found programmer: Id = "CATERIN"; type = S
+    Software Version = 1.0; No Hardware Version given.
+Programmer supports auto addr increment.
+Programmer supports buffered memory access with buffersize=128 bytes.
+
+Programmer supports the following devices:
+    Device code: 0x44
+
+avrdude.exe: AVR device initialized and ready to accept instructions
+
+Reading | ################################################## | 100% 0.00s
+
+avrdude.exe: Device signature = 0x1e9587 (probably m32u4)
+avrdude.exe: NOTE: "flash" memory has been specified, an erase cycle will be performed
+             To disable this feature, specify the -D option.
+avrdude.exe: erasing chip
+avrdude.exe: reading input file "./.build/lets_split_rev2_xyverz.hex"
+avrdude.exe: input file ./.build/lets_split_rev2_xyverz.hex auto detected as Intel Hex
+avrdude.exe: writing flash (27938 bytes):
+
+Writing | ################################################## | 100% 2.40s
+
+avrdude.exe: 27938 bytes of flash written
+avrdude.exe: verifying flash memory against ./.build/lets_split_rev2_xyverz.hex:
+avrdude.exe: load data flash data from input file ./.build/lets_split_rev2_xyverz.hex:
+avrdude.exe: input file ./.build/lets_split_rev2_xyverz.hex auto detected as Intel Hex
+avrdude.exe: input file ./.build/lets_split_rev2_xyverz.hex contains 27938 bytes
+avrdude.exe: reading on-chip flash data:
+
+Reading | ################################################## | 100% 0.43s
+
+avrdude.exe: verifying ...
+avrdude.exe: 27938 bytes of flash verified
+
+avrdude.exe: safemode: Fuses OK (E:CB, H:D8, L:FF)
+
+avrdude.exe done.  Thank you.
+```
+If you have any issues with this, you may need to this: 
+
+    sudo make <my_keyboard>:<my_keymap>:avrdude
+
+## HalfKay
+
+For the PJRC devices (Teensy's), when you're ready to compile and flash your firmware, open up your terminal window and run the built command: 
+
+    make <my_keyboard>:<my_keymap>:teensy
+
+For example, if your keymap is named "xyverz" and you're building a keymap for an Ergodox or Ergodox EZ, you'll use this command:
+
+    make erdogox_ez:xyverz:teensy
+
+Once the firmware finishes compiling, it will output something like this: 
+
+```
+Linking: .build/ergodox_ez_xyverz.elf                                                               [OK]
+Creating load file for flashing: .build/ergodox_ez_xyverz.hex                                       [OK]
+Checking file size of ergodox_ez_xyverz.hex                                                         [OK]
+ * File size is fine - 25584/32256
+ Teensy Loader, Command Line, Version 2.1
+Read "./.build/ergodox_ez_xyverz.hex": 25584 bytes, 79.3% usage
+Waiting for Teensy device...
+ (hint: press the reset button)
+ ```
+
+ At this point, reset your board.  Once you've done that, you'll see output like this: 
+
+ ```
+ Found HalfKay Bootloader
+Read "./.build/ergodox_ez_drashna.hex": 28532 bytes, 88.5% usage
+Programming............................................................................................................................................................................
+...................................................
+Booting
+```
+
+
+## Test It Out!
+
+Congrats! Your custom firmware has been programmed to your keyboard!
+
+Give it a try and make sure everything works the way you want it to. We've written [Testing and Debugging](newbs_testing_debugging.md) to round out this Newbie Guide, so head over there to learn about how to troubleshoot your custom functionality.

docs/newbs_getting_started.md

@@ -0,0 +1,100 @@
+# Introduction
+
+Your computer keyboard has a processor inside of it, not unlike the one inside your computer. This processor runs software that is responsible for detecting button presses and sending reports about the state of the keyboard when buttons are pressed or released. QMK fills the role of that software, detecting button presses and passing that information on to the host computer. When you build your custom keymap, you are creating the equivalent of an executable program for your keyboard.
+
+QMK tries to put a lot of power into your hands by making easy things easy, and hard things possible. You don't have to know how to program to create powerful keymaps — you only have to follow a few simple syntax rules.
+
+# Getting Started
+
+Before you can build keymaps, you need to install some software and set up your build environment. This only has to be done once no matter how many keyboards you plan to compile firmware for. 
+
+If you would prefer a more graphical user interface approach, please consider using the online [QMK Configurator](https://config.qmk.fm). Please refer to [Building Your First Firmware using the online GUI](newbs_building_firmware_configurator.md). 
+
+
+## Download Software
+
+### Text Editor
+
+You'll need a program that can edit and save **plain text** files. If you're on Windows you can make do with Notepad, and on Linux you can use gedit. Both of these are simple but functional text editors. On macOS, be careful with the default TextEdit app: it will not save plain text files unless you explicitly select _Make Plain Text_ from the _Format_ menu.
+
+You can also download and install a dedicated text editor like [Sublime Text](https://www.sublimetext.com/) or [VS Code](https://code.visualstudio.com/). This is probably the best way to go regardless of platform, as these programs are specifically made for editing code.
+
+?> Not sure which text editor to use? Laurence Bradford wrote [a great introduction](https://learntocodewith.me/programming/basics/text-editors/) to the subject.
+
+### QMK Toolbox
+
+QMK Toolbox is an optional graphical program for Windows and macOS that allows you to both program and debug your custom keyboard. You will likely find it invaluable for easily flashing your keyboard and viewing debug messages that it prints.
+
+[Download the latest release here.](https://github.com/qmk/qmk_toolbox/releases/latest)
+
+* For Windows: `qmk_toolbox.exe` (portable) or `qmk_toolbox_install.exe` (installer)
+* For macOS: `QMK.Toolbox.app.zip` (portable) or `QMK.Toolbox.pkg` (installer)
+
+## Set Up Your Environment
+
+We've tried to make QMK as easy to set up as possible. You only have to prepare your Linux or Unix environment, then let QMK install the rest.
+
+?> If you haven't worked with the Linux/Unix command line before, there are a few basic concepts and commands you should learn. These resources will teach you enough to be able to work with QMK:<br>
+[Must Know Linux Commands](https://www.guru99.com/must-know-linux-commands.html)<br>
+[Some Basic Unix Commands](https://www.tjhsst.edu/~dhyatt/superap/unixcmd.html)
+
+### Windows
+
+You will need to install MSYS2 and Git.
+
+* Follow the installation instructions on the [MSYS2 homepage](http://www.msys2.org).
+* Close any open MSYS2 terminals and open a new MSYS2 MinGW 64-bit terminal.
+* Install Git by running this command: `pacman -S git`.
+
+### macOS
+
+You will need to install Homebrew. Follow the instructions on the [Homebrew homepage](https://brew.sh).
+
+After Homebrew is installed, continue with _Set Up QMK_. In that step you will run a script that will install other packages.
+
+### Linux
+
+You will need to install Git. It's very likely that you already have it, but if not, one of the following commands should install it:
+
+* Debian / Ubuntu / Devuan: `apt-get install git`
+* Fedora / Red Hat / CentOS: `yum install git`
+* Arch: `pacman -S git`
+
+?> Docker is also an option on all platforms. [Click here for details.](getting_started_build_tools.md#docker)
+
+## Set Up QMK
+
+Once you have set up your Linux/Unix environment, you are ready to download QMK. We will do this by using Git to "clone" the QMK repository. Open a Terminal or MSYS2 MinGW window and leave it open for the remainder of this guide. Inside that window run these two commands:
+
+    git clone https://github.com/qmk/qmk_firmware.git
+    cd qmk_firmware
+
+?> If you already know [how to use GitHub](getting_started_github.md), we recommend that you create and clone your own fork instead. If you don't know what that means, you can safely ignore this message.
+
+QMK comes with a script to help you set up the rest of what you'll need. You should run it now by typing in this command:
+
+    util/qmk_install.sh
+
+## Test Your Build Environment
+
+Now that your QMK build environment is set up, you can build a firmware for your keyboard. Start by trying to build the keyboard's default keymap. You should be able to do that with a command in this format:
+
+    make <keyboard>:default
+
+For example, to build a firmware for a Clueboard 66% you would use:
+
+    make clueboard/66/rev3:default
+
+When it is done you should have a lot of output that ends similar to this:
+
+```
+Linking: .build/clueboard_66_rev3_default.elf                                                       [OK]
+Creating load file for flashing: .build/clueboard_66_rev3_default.hex                               [OK]
+Copying clueboard_66_rev3_default.hex to qmk_firmware folder                                        [OK]
+Checking file size of clueboard_66_rev3_default.hex                                                 [OK]
+ * The firmware size is fine - 26356/28672 (2316 bytes free)
+```
+
+# Creating Your Keymap
+
+You are now ready to create your own personal keymap! Move on to [Building Your First Firmware](newbs_building_firmware.md) for that.