Fix Bug with (RGB|LED)_DISABLE_WHEN_USB_SUSPENDED define (#13060)

* Set bootloader to stm32-dfu for STM32F303

* Set bootloader to stm32-dfu for STM32F0x2

* Set bootloader to stm32-dfu for STM32F4x1

* Set bootloader to stm32duino for sowbug

* Delete redundant bootloader_defs headers

* Add some missing MCU name comments

* Move APM32 dfu-suffix overrides underneath bootloader

* Remove redundant STM32_BOOTLOADER_ADDRESS defines/rules

.clang_complete

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

.gitattributes

@@ -92,3 +92,4 @@ GRAPHICS
 # hex files
 *.hex binary
 *.eep binary
+nix/sources.nix linguist-generated=true

.github/PULL_REQUEST_TEMPLATE.md

@@ -26,7 +26,8 @@
 
 <!--- 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 code follows the code style of this project: [**C**](https://docs.qmk.fm/#/coding_conventions_c), [**Python**](https://docs.qmk.fm/#/coding_conventions_python)
+- [ ] I have read the [**PR Checklist** document](https://docs.qmk.fm/#/pr_checklist) and have made the appropriate changes.
 - [ ] 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).

.github/labeler.yml

@@ -0,0 +1,42 @@
+core:
+  - quantum/**/*
+  - tmk_core/**/*
+  - drivers/**/*
+  - tests/**/*
+  - util/**/*
+  - platforms/**/*
+  - Makefile
+  - '*.mk'
+dependencies:
+  - any:
+    - 'lib/**/*'
+    - '!lib/python/**/*'
+keyboard:
+  - any:
+    - 'keyboards/**/*'
+    - '!keyboards/**/keymaps/**/*'
+keymap:
+  - users/**/*
+  - layouts/**/*
+  - keyboards/**/keymaps/**/*
+via:
+  - keyboards/**/keymaps/via/*
+cli:
+  - bin/qmk
+  - requirements.txt
+  - lib/python/**/*
+python:
+  - '**/*.py'
+documentation:
+  - docs/**/*
+translation:
+  - docs/fr-fr/**/*
+  - docs/es/**/*
+  - docs/ja/**/*
+  - docs/he-il/**/*
+  - docs/pt-br/**/*
+  - docs/zh-cn/**/*
+  - docs/de/**/*
+  - docs/ru-ru/**/*
+CI:
+  - .github/**/*

.github/workflows/api.yml

@@ -0,0 +1,37 @@
+name: Update API Data
+
+on:
+  push:
+    branches:
+    - master
+    paths:
+    - 'keyboards/**'
+    - 'layouts/community/**'
+
+jobs:
+  api_data:
+    runs-on: ubuntu-latest
+    container: qmkfm/base_container
+
+    # protect against those who develop with their fork on master
+    if: github.repository == 'qmk/qmk_firmware'
+
+    steps:
+    - uses: actions/checkout@v2
+      with:
+        fetch-depth: 1
+        persist-credentials: false
+
+    - name: Generate API Data
+      run: qmk generate-api
+
+    - name: Upload API Data
+      uses: jakejarvis/s3-sync-action@master
+      with:
+        args: --acl public-read --follow-symlinks --delete
+      env:
+        AWS_S3_BUCKET: ${{ secrets.API_SPACE_MASTER }}
+        AWS_ACCESS_KEY_ID: ${{ secrets.SPACES_ACCESS_KEY }}
+        AWS_SECRET_ACCESS_KEY: ${{ secrets.SPACES_SECRET_KEY }}
+        AWS_S3_ENDPOINT: https://nyc3.digitaloceanspaces.com
+        SOURCE_DIR: 'api_data'

.github/workflows/auto_tag.yaml

@@ -0,0 +1,33 @@
+name: Essential files modified
+
+on:
+  push:
+    branches:
+    - master
+    paths:
+    - quantum/**/*
+    - tmk_core/**/*
+    - drivers/**/*
+    - tests/**/*
+    - util/**/*
+    - platforms/**/*
+    - Makefile
+    - '*.mk'
+
+jobs:
+  tag:
+    runs-on: ubuntu-latest
+
+    # protect against those who develop with their fork on master
+    if: github.repository == 'qmk/qmk_firmware'
+
+    steps:
+    - uses: actions/checkout@v2
+      with:
+        fetch-depth: 0
+
+    - name: Bump version and push tag
+      uses: anothrNick/github-tag-action@1.26.0
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        DEFAULT_BUMP: 'patch'

.github/workflows/cli.yml

@@ -19,10 +19,10 @@ jobs:
     container: qmkfm/base_container
 
     steps:
-    - uses: actions/checkout@v1
+    - uses: actions/checkout@v2
       with:
         submodules: recursive
     - name: Install dependencies
-      run: pip3 install -r requirements.txt
+      run: pip3 install -r requirements-dev.txt
     - name: Run tests
       run: bin/qmk pytest

.github/workflows/develop_api.yml

@@ -0,0 +1,37 @@
+name: Update Develop API Data
+
+on:
+  push:
+    branches:
+    - develop
+    paths:
+    - 'keyboards/**'
+    - 'layouts/community/**'
+
+jobs:
+  api_data:
+    runs-on: ubuntu-latest
+    container: qmkfm/base_container
+
+    # protect against those who work in their fork on develop
+    if: github.repository == 'qmk/qmk_firmware'
+
+    steps:
+    - uses: actions/checkout@v2
+      with:
+        fetch-depth: 1
+        persist-credentials: false
+
+    - name: Generate API Data
+      run: qmk generate-api
+
+    - name: Upload API Data
+      uses: jakejarvis/s3-sync-action@master
+      with:
+        args: --acl public-read --follow-symlinks --delete
+      env:
+        AWS_S3_BUCKET: ${{ secrets.API_SPACE_DEVELOP }}
+        AWS_ACCESS_KEY_ID: ${{ secrets.SPACES_ACCESS_KEY }}
+        AWS_SECRET_ACCESS_KEY: ${{ secrets.SPACES_SECRET_KEY }}
+        AWS_S3_ENDPOINT: https://nyc3.digitaloceanspaces.com
+        SOURCE_DIR: 'api_data'

.github/workflows/develop_update.yml

@@ -0,0 +1,37 @@
+name: Update develop after master merge
+
+on:
+  push:
+    branches:
+    - master
+
+
+jobs:
+  develop_update:
+    runs-on: ubuntu-latest
+
+    if: github.repository == 'qmk/qmk_firmware'
+
+    steps:
+    - uses: actions/checkout@v2
+      with:
+        fetch-depth: 0
+
+    - name: Checkout develop
+      run: |
+        git fetch origin master develop
+        git checkout develop
+
+    - name: Check if branch locked
+      id: check_locked
+      uses: andstor/file-existence-action@v1
+      with:
+        files: ".locked"
+
+    - name: Update develop from master
+      if: steps.check_locked.outputs.files_exists == 'false'
+      run: |
+        git config --global user.name "QMK Bot"
+        git config --global user.email "hello@qmk.fm"
+        git merge origin/master
+        git push origin develop

.github/workflows/docs.yml

@@ -0,0 +1,43 @@
+name: Generate Docs
+
+on:
+  push:
+    branches:
+    - master
+    paths:
+    - 'tmk_core/**'
+    - 'quantum/**'
+    - 'platforms/**'
+    - 'docs/**'
+    - '.github/workflows/docs.yml'
+
+jobs:
+  generate:
+    runs-on: ubuntu-latest
+    container: qmkfm/base_container
+
+    # protect against those who develop with their fork on master
+    if: github.repository == 'qmk/qmk_firmware'
+
+    steps:
+    - uses: actions/checkout@v2
+      with:
+        fetch-depth: 1
+
+    - name: Install dependencies
+      run: |
+        apt-get update && apt-get install -y rsync nodejs npm doxygen
+        npm install -g moxygen
+
+    - name: Build docs
+      run: |
+        qmk --verbose generate-docs
+
+    - name: Deploy
+      uses: JamesIves/github-pages-deploy-action@3.7.1
+      with:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        BASE_BRANCH: master
+        BRANCH: gh-pages
+        FOLDER: .build/docs
+        GIT_CONFIG_EMAIL: hello@qmk.fm

.github/workflows/format.yaml

@@ -0,0 +1,42 @@
+name: PR Lint Format
+
+on:
+  pull_request:
+    paths:
+    - 'drivers/**'
+    - 'lib/arm_atsam/**'
+    - 'lib/lib8tion/**'
+    - 'lib/python/**'
+    - 'platforms/**'
+    - 'quantum/**'
+    - 'tests/**'
+    - 'tmk_core/**'
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+
+    container: qmkfm/base_container
+
+    steps:
+    - uses: rlespinasse/github-slug-action@v3.x
+
+    - uses: actions/checkout@v2
+      with:
+        fetch-depth: 0
+
+    - uses: trilom/file-changes-action@v1.2.4
+      id: file_changes
+      with:
+        output: ' '
+        fileOutput: ' '
+
+    - name: Run qmk cformat and qmk pyformat
+      shell: 'bash {0}'
+      run: |
+        qmk cformat --core-only -n $(< ~/files.txt)
+        cformat_exit=$?
+        qmk pyformat -n
+        pyformat_exit=$?
+
+        exit $((cformat_exit + pyformat_exit))

.github/workflows/labeler.yml

@@ -0,0 +1,14 @@
+name: "Pull Request Labeler"
+
+on:
+  pull_request_target:
+    types: [opened, synchronize, reopened, ready_for_review, locked]
+
+jobs:
+  triage:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/labeler@main
+      with:
+        repo-token: "${{ secrets.GITHUB_TOKEN }}"
+        configuration-path: '.github/labeler.yml'

.github/workflows/lint.yml

@@ -0,0 +1,55 @@
+name: PR Lint keyboards
+
+on:
+  pull_request:
+    paths:
+    - 'keyboards/**'
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+
+    container: qmkfm/base_container
+
+    steps:
+    - uses: actions/checkout@v2
+      with:
+        fetch-depth: 0
+
+    - uses: trilom/file-changes-action@v1.2.4
+      id: file_changes
+      with:
+        output: '\n'
+
+    - name: Print info
+      run: |
+        git rev-parse --short HEAD
+        echo ${{ github.event.pull_request.base.sha }}
+        echo '${{ steps.file_changes.outputs.files}}'
+
+    - name: Run qmk lint
+      shell: 'bash {0}'
+      run: |
+        QMK_CHANGES=$(echo -e '${{ steps.file_changes.outputs.files}}')
+        QMK_KEYBOARDS=$(qmk list-keyboards)
+
+        exit_code=0
+        for KB in $QMK_KEYBOARDS; do
+          KEYBOARD_CHANGES=$(echo "$QMK_CHANGES" | grep -E '^(keyboards/'${KB}'/)')
+          if [[ -z "$KEYBOARD_CHANGES" ]]; then
+            # skip as no changes for this keyboard
+            continue
+          fi
+
+          KEYMAP_ONLY=$(echo "$KEYBOARD_CHANGES" | grep -cv /keymaps/)
+          if [[ $KEYMAP_ONLY -gt 0 ]]; then
+            echo "linting ${KB}"
+
+            qmk lint --keyboard ${KB} && qmk info -l --keyboard ${KB}
+            exit_code=$(($exit_code + $?))
+          fi
+        done
+        if [[ $exit_code -gt 255 ]]; then
+            exit 255
+        fi
+        exit $exit_code

.gitignore

@@ -5,6 +5,7 @@
 *.eep
 *.elf
 *.hex
+*.uf2
 *.qmk
 !util/bootloader.hex
 !quantum/tools/eeprom_reset.hex
@@ -16,6 +17,7 @@
 *.swp
 tags
 *~
+api_data/v1
 build/
 .build/
 *.bak
@@ -24,6 +26,7 @@ quantum/version.h
 .idea/
 CMakeLists.txt
 cmake-build-debug
+.clang_complete
 doxygen/
 .DS_Store
 /util/wsl_downloaded
@@ -47,8 +50,8 @@ doxygen/
 *.iml
 .browse.VC.db*
 *.stackdump
-util/Win_Check_Output.txt
 # Let these ones be user specific, since we have so many different configurations
+*.code-workspace
 .vscode/c_cpp_properties.json
 .vscode/launch.json
 .vscode/tasks.json
@@ -70,6 +73,10 @@ id_rsa_*
 
 # python things
 __pycache__
+.python-version
 
 # prerequisites for updating ChibiOS
 /util/fmpp*
+
+# Allow to exist but don't include it in the repo
+user_song_list.h

.gitmodules

@@ -12,7 +12,13 @@
 	branch = master
 [submodule "lib/googletest"]
 	path = lib/googletest
-	url = https://github.com/google/googletest
+	url = https://github.com/qmk/googletest
 [submodule "lib/lufa"]
 	path = lib/lufa
 	url = https://github.com/qmk/lufa
+[submodule "lib/vusb"]
+	path = lib/vusb
+	url = https://github.com/qmk/v-usb
+[submodule "lib/printf"]
+	path = lib/printf
+	url = https://github.com/qmk/printf

.travis.yml

@@ -18,20 +18,15 @@ addons:
       - ubuntu-toolchain-r-test
       - llvm-toolchain-trusty-7
     packages:
-    - pandoc
     - diffutils
-    - dos2unix
-    - doxygen
     - clang-format-7
     - libstdc++-7-dev
-install:
-  - npm install -g moxygen
 script:
+  - git fetch --depth=50 origin $TRAVIS_BRANCH:$TRAVIS_BRANCH
   - git rev-parse --short HEAD
   - git diff --name-only HEAD $TRAVIS_BRANCH
   - bash util/travis_test.sh
   - bash util/travis_build.sh
-  - bash util/travis_docs.sh
 after_script:
   bash util/travis_compiled_push.sh
 notifications:

.vscode/settings.json

@@ -9,13 +9,18 @@
         "**/*.bin": true
     },
     "files.associations": {
-      "*.h": "c",
-      "*.c": "c",
-      "*.inc": "c",
-      "*.cpp": "cpp",
-      "*.hpp": "cpp",
-      "xstddef": "c",
-      "type_traits": "c",
-      "utility": "c"
+        "*.h": "c",
+        "*.c": "c",
+        "*.inc": "c",
+        "*.cpp": "cpp",
+        "*.hpp": "cpp",
+        "xstddef": "c",
+        "type_traits": "c",
+        "utility": "c",
+        "ranges": "c"
+    },
+    "[markdown]": {
+        "editor.trimAutoWhitespace": false,
+        "files.trimTrailingWhitespace": false
     }
 }

Makefile

@@ -29,6 +29,16 @@ $(info QMK Firmware $(QMK_VERSION))
 endif
 endif
 
+# Determine which qmk cli to use
+ifeq (,$(shell which qmk))
+    QMK_BIN = bin/qmk
+else
+    QMK_BIN = qmk
+endif
+
+# avoid 'Entering|Leaving directory' messages
+MAKEFLAGS += --no-print-directory
+
 ON_ERROR := error_occurred=1
 
 BREAK_ON_ERRORS = no
@@ -65,71 +75,15 @@ PATH_ELEMENTS := $(subst /, ,$(STARTING_DIR))
 # Initialize the path elements list for further processing
 $(eval $(call NEXT_PATH_ELEMENT))
 
-# This function sets the KEYBOARD; KEYMAP and SUBPROJECT to the correct
-# variables depending on which directory you stand in.
-# 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)
-#     $(eval $(call NEXT_PATH_ELEMENT))
-#     KEYBOARD := $(CURRENT_PATH_ELEMENT)
-#     $(eval $(call NEXT_PATH_ELEMENT))
-#     # If we are in a subfolder of keymaps, or in other words in a keymap
-#     # folder
-#     ifeq ($(CURRENT_PATH_ELEMENT),keymaps)
-#         $(eval $(call NEXT_PATH_ELEMENT))
-#         KEYMAP := $(CURRENT_PATH_ELEMENT)
-#      # else if we are not in the keyboard folder itself
-#     else ifneq ($(CURRENT_PATH_ELEMENT),)
-#         # the we can assume it's a subproject, as no other folders
-#         # should have make files in them
-#         SUBPROJECT := $(CURRENT_PATH_ELEMENT)
-#         $(eval $(call NEXT_PATH_ELEMENT))
-#         # if we are inside a keymap folder of a subproject
-#         ifeq ($(CURRENT_PATH_ELEMENT),keymaps)
-#             $(eval $(call NEXT_PATH_ELEMENT))
-#             KEYMAP := $(CURRENT_PATH_ELEMENT)
-#         endif
-#     endif
-# endif
-
-define GET_KEYBOARDS
-ifndef ALT_GET_KEYBOARDS
-    All_RULES_MK := $$(patsubst $(ROOT_DIR)/keyboards/%/rules.mk,%,$$(wildcard $(ROOT_DIR)/keyboards/*/rules.mk))
-    All_RULES_MK += $$(patsubst $(ROOT_DIR)/keyboards/%/rules.mk,%,$$(wildcard $(ROOT_DIR)/keyboards/*/*/rules.mk))
-    All_RULES_MK += $$(patsubst $(ROOT_DIR)/keyboards/%/rules.mk,%,$$(wildcard $(ROOT_DIR)/keyboards/*/*/*/rules.mk))
-    All_RULES_MK += $$(patsubst $(ROOT_DIR)/keyboards/%/rules.mk,%,$$(wildcard $(ROOT_DIR)/keyboards/*/*/*/*/rules.mk))
-
-    KEYMAPS_MK := $$(patsubst $(ROOT_DIR)/keyboards/%/rules.mk,%,$$(wildcard $(ROOT_DIR)/keyboards/*/keymaps/*/rules.mk))
-    KEYMAPS_MK += $$(patsubst $(ROOT_DIR)/keyboards/%/rules.mk,%,$$(wildcard $(ROOT_DIR)/keyboards/*/*/keymaps/*/rules.mk))
-    KEYMAPS_MK += $$(patsubst $(ROOT_DIR)/keyboards/%/rules.mk,%,$$(wildcard $(ROOT_DIR)/keyboards/*/*/*/keymaps/*/rules.mk))
-    KEYMAPS_MK += $$(patsubst $(ROOT_DIR)/keyboards/%/rules.mk,%,$$(wildcard $(ROOT_DIR)/keyboards/*/*/*/*/keymaps/*/rules.mk))
-
-    KEYBOARDS := $$(sort $$(filter-out $$(KEYMAPS_MK), $$(All_RULES_MK)))
-else
-    KEYBOARDS := $(shell find keyboards/ -type f -iname "rules.mk" | grep -v keymaps | sed 's!keyboards/\(.*\)/rules.mk!\1!' | sort | uniq)
-endif
-endef
-
-$(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 targets to enable a few simple make commands outside the main processing below.
 .PHONY: list-keyboards
 list-keyboards:
-	echo $(KEYBOARDS)
-
-define PRINT_KEYBOARD
-	$(info $(PRINTING_KEYBOARD))
-endef
+	util/list_keyboards.sh | sort -u | tr '\n' ' '
 
 .PHONY: generate-keyboards-file
 generate-keyboards-file:
-	$(foreach PRINTING_KEYBOARD,$(KEYBOARDS),$(eval $(call PRINT_KEYBOARD)))
+	util/list_keyboards.sh | sort -u
 
 .PHONY: clean
 clean:
@@ -139,8 +93,8 @@ clean:
 
 .PHONY: distclean
 distclean: clean
-	echo -n 'Deleting *.bin and *.hex ... '
-	rm -f *.bin *.hex
+	echo -n 'Deleting *.bin, *.hex, and *.uf2 ... '
+	rm -f *.bin *.hex *.uf2
 	echo 'done.'
 
 #Compatibility with the old make variables, anything you specify directly on the command line
@@ -155,8 +109,6 @@ endif
 # Uncomment these for debugging
 # $(info Keyboard: $(KEYBOARD))
 # $(info Keymap: $(KEYMAP))
-# $(info Subproject: $(SUBPROJECT))
-# $(info Keyboards: $(KEYBOARDS))
 
 
 # Set the default goal depending on where we are running make from
@@ -214,7 +166,6 @@ endef
 # A recursive helper function for finding the longest match
 # $1 The list to be checked
 # It works by always removing the currently matched item from the list
-# and call itself recursively, until a match is found
 define TRY_TO_MATCH_RULE_FROM_LIST_HELPER2
     # Stop the recursion when the list is empty
     ifneq ($1,)
@@ -269,16 +220,29 @@ endef
 define PARSE_RULE
     RULE := $1
     COMMANDS :=
+    REQUIRE_PLATFORM_KEY :=
     # If the rule starts with all, then continue the parsing from
     # PARSE_ALL_KEYBOARDS
     ifeq ($$(call COMPARE_AND_REMOVE_FROM_RULE,all),true)
         KEYBOARD_RULE=all
         $$(eval $$(call PARSE_ALL_KEYBOARDS))
+    else ifeq ($$(call COMPARE_AND_REMOVE_FROM_RULE,all-avr),true)
+        KEYBOARD_RULE=all
+        REQUIRE_PLATFORM_KEY := avr
+        $$(eval $$(call PARSE_ALL_KEYBOARDS))
+    else ifeq ($$(call COMPARE_AND_REMOVE_FROM_RULE,all-chibios),true)
+        KEYBOARD_RULE=all
+        REQUIRE_PLATFORM_KEY := chibios
+        $$(eval $$(call PARSE_ALL_KEYBOARDS))
+    else ifeq ($$(call COMPARE_AND_REMOVE_FROM_RULE,all-arm_atsam),true)
+        KEYBOARD_RULE=all
+        REQUIRE_PLATFORM_KEY := arm_atsam
+        $$(eval $$(call PARSE_ALL_KEYBOARDS))
     else ifeq ($$(call COMPARE_AND_REMOVE_FROM_RULE,test),true)
         $$(eval $$(call PARSE_TEST))
     # If the rule starts with the name of a known keyboard, then continue
     # the parsing from PARSE_KEYBOARD
-    else ifeq ($$(call TRY_TO_MATCH_RULE_FROM_LIST,$$(KEYBOARDS)),true)
+    else ifeq ($$(call TRY_TO_MATCH_RULE_FROM_LIST,$$(shell util/list_keyboards.sh | sort -u)),true)
         KEYBOARD_RULE=$$(MATCHED_ITEM)
         $$(eval $$(call PARSE_KEYBOARD,$$(MATCHED_ITEM)))
     # Otherwise use the KEYBOARD variable, which is determined either by
@@ -291,8 +255,8 @@ define PARSE_RULE
         $$(info |  QMK's make format recently changed to use folder locations and colons:)
         $$(info |     make project_folder:keymap[:target])
         $$(info |  Examples:)
-        $$(info |     make planck/rev4:default:dfu)
-        $$(info |     make planck:default)
+        $$(info |     make dz60:default)
+        $$(info |     make planck/rev6:default:flash)
         $$(info |)
     endif
 endef
@@ -395,26 +359,9 @@ endef
 # if we are going to compile all keyboards, match the rest of the rule
 # for each of them
 define PARSE_ALL_KEYBOARDS
-    $$(eval $$(call PARSE_ALL_IN_LIST,PARSE_KEYBOARD,$(KEYBOARDS)))
+    $$(eval $$(call PARSE_ALL_IN_LIST,PARSE_KEYBOARD,$(shell util/list_keyboards.sh noci | sort -u)))
 endef
 
-# $1 Subproject
-# When entering this, the keyboard and subproject are known, so now we need
-# to determine which keymaps are going to get compiled
-# define PARSE_SUBPROJECT
-
-# endef
-
-# If we want to parse all subprojects, but the keyboard doesn't have any,
-# then use defaultsp instead
-# define PARSE_ALL_SUBPROJECTS
-#     ifeq ($$(SUBPROJECTS),)
-#         $$(eval $$(call PARSE_SUBPROJECT,defaultsp))
-#     else
-#         $$(eval $$(call PARSE_ALL_IN_LIST,PARSE_SUBPROJECT,$$(SUBPROJECTS)))
-#     endif
-# endef
-
 # Prints a list of all known keymaps for the given keyboard
 define LIST_ALL_KEYMAPS
     COMMAND_true_LIST_KEYMAPS := \
@@ -444,7 +391,7 @@ define PARSE_KEYMAP
     # Format it in bold
     KB_SP := $(BOLD)$$(KB_SP)$(NO_COLOR)
     # Specify the variables that we are passing forward to submake
-    MAKE_VARS := KEYBOARD=$$(CURRENT_KB) KEYMAP=$$(CURRENT_KM)
+    MAKE_VARS := KEYBOARD=$$(CURRENT_KB) KEYMAP=$$(CURRENT_KM) REQUIRE_PLATFORM_KEY=$$(REQUIRE_PLATFORM_KEY) QMK_BIN=$$(QMK_BIN)
     # And the first part of the make command
     MAKE_CMD := $$(MAKE) -r -R -C $(ROOT_DIR) -f build_keyboard.mk $$(MAKE_TARGET)
     # The message to display
@@ -463,6 +410,8 @@ define BUILD
         LOG=$$$$($$(MAKE_CMD) $$(MAKE_VARS) SILENT=true 2>&1) ; \
         if [ $$$$? -gt 0 ]; \
             then $$(PRINT_ERROR_PLAIN); \
+        elif [ "$$$$LOG" = "skipped" ] ; \
+            then $$(PRINT_SKIPPED_PLAIN); \
         elif [ "$$$$LOG" != "" ] ; \
             then $$(PRINT_WARNING_PLAIN); \
         else \
@@ -554,19 +503,21 @@ if [ $$error_occurred -gt 0 ]; then $(HANDLE_ERROR); fi;
 
 endef
 
-# Let's match everything, we handle all the rule parsing ourselves
+# Catch everything and parse the command line ourselves.
 .PHONY: %
 %:
 	# Check if we have the CMP tool installed
 	cmp $(ROOT_DIR)/Makefile $(ROOT_DIR)/Makefile >/dev/null 2>&1; if [ $$? -gt 0 ]; then printf "$(MSG_NO_CMP)"; exit 1; fi;
-	# Ensure that python3 is installed. This check can be removed after python is used in more places.
-	if ! python3 --version 1> /dev/null 2>&1; then printf "$(MSG_PYTHON_MISSING)"; fi
+	# Ensure that $(QMK_BIN) works.
+	if ! $(QMK_BIN) hello 1> /dev/null 2>&1; then printf "$(MSG_PYTHON_MISSING)"; exit 1; fi
 	# Check if the submodules are dirty, and display a warning if they are
 ifndef SKIP_GIT
 	if [ ! -e lib/chibios ]; then git submodule sync lib/chibios && git submodule update --depth 50 --init lib/chibios; fi
 	if [ ! -e lib/chibios-contrib ]; then git submodule sync lib/chibios-contrib && git submodule update --depth 50 --init lib/chibios-contrib; fi
 	if [ ! -e lib/ugfx ]; then git submodule sync lib/ugfx && git submodule update --depth 50 --init lib/ugfx; fi
 	if [ ! -e lib/lufa ]; then git submodule sync lib/lufa && git submodule update --depth 50 --init lib/lufa; fi
+	if [ ! -e lib/vusb ]; then git submodule sync lib/vusb && git submodule update --depth 50 --init lib/vusb; fi
+	if [ ! -e lib/printf ]; then git submodule sync lib/printf && git submodule update --depth 50 --init lib/printf; fi
 	git submodule status --recursive 2>/dev/null | \
 	while IFS= read -r x; do \
 		case "$$x" in \
@@ -588,25 +539,6 @@ endif
 	$(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
-
-# All should compile everything
-# .PHONY: all
-# all: all-keyboards test-all
-
-# Define some shortcuts, mostly for compatibility with the old syntax
-# .PHONY: all-keyboards
-# all-keyboards: all\:all\:all
-
-# .PHONY: all-keyboards-defaults
-# all-keyboards-defaults: all\:default
-
-# .PHONY: test
-# test: test-all
-
-# .PHONY: test-clean
-# test-clean: test-all-clean
-
 lib/%:
 	git submodule sync $?
 	git submodule update --init $?
@@ -632,12 +564,13 @@ else
 endif
 ifndef SKIP_VERSION
 BUILD_DATE := $(shell date +"%Y-%m-%d-%H:%M:%S")
+else
+BUILD_DATE := 2020-01-01-00:00:00
+endif
+
 $(shell echo '#define QMK_VERSION "$(GIT_VERSION)"' > $(ROOT_DIR)/quantum/version.h)
 $(shell echo '#define QMK_BUILDDATE "$(BUILD_DATE)"' >> $(ROOT_DIR)/quantum/version.h)
 $(shell echo '#define CHIBIOS_VERSION "$(CHIBIOS_VERSION)"' >> $(ROOT_DIR)/quantum/version.h)
 $(shell echo '#define CHIBIOS_CONTRIB_VERSION "$(CHIBIOS_CONTRIB_VERSION)"' >> $(ROOT_DIR)/quantum/version.h)
-else
-BUILD_DATE := NA
-endif
 
 include $(ROOT_DIR)/testlist.mk

Vagrantfile

@@ -89,7 +89,7 @@ Vagrant.configure(2) do |config|
 
   Examples:
      make planck/rev4:default:dfu
-     make planck:default
+     make planck/rev4:default
 
   EOT
 end

api_data/_config.yml

@@ -0,0 +1 @@
+theme: jekyll-theme-cayman

api_data/readme.md

@@ -0,0 +1,5 @@
+# QMK Keyboard Metadata
+
+This directory contains machine parsable data about keyboards supported by QMK. The latest version is always available online at <https://keyboards.qmk.fm>.
+
+Do not edit anything here by hand. It is generated with the `qmk generate-api` command.

bin/qmk

@@ -2,48 +2,14 @@
 """CLI wrapper for running QMK commands.
 """
 import os
-import subprocess
 import sys
-from importlib.util import find_spec
-from time import strftime
+from pathlib import Path
 
 # Add the QMK python libs to our path
-script_dir = os.path.dirname(os.path.realpath(__file__))
-qmk_dir = os.path.abspath(os.path.join(script_dir, '..'))
-python_lib_dir = os.path.abspath(os.path.join(qmk_dir, 'lib', 'python'))
-sys.path.append(python_lib_dir)
-
-# Make sure our modules have been setup
-with open(os.path.join(qmk_dir, 'requirements.txt'), 'r') as fd:
-    for line in fd.readlines():
-        line = line.strip().replace('<', '=').replace('>', '=')
-
-        if line[0] == '#':
-            continue
-
-        if '#' in line:
-            line = line.split('#')[0]
-
-        module = line.split('=')[0] if '=' in line else line
-
-        if module in ['pep8-naming']:
-            # Not every module is importable by its own name.
-            continue
-
-        if not find_spec(module):
-            print('Could not find module %s!' % module)
-            print('Please run `pip3 install -r requirements.txt` to install the python dependencies.')
-            exit(255)
-
-# Figure out our version
-# TODO(skullydazed/anyone): Find a method that doesn't involve git. This is slow in docker and on windows.
-command = ['git', 'describe', '--abbrev=6', '--dirty', '--always', '--tags']
-result = subprocess.run(command, universal_newlines=True, stdout=subprocess.PIPE, stderr=subprocess.STDOUT)
-
-if result.returncode == 0:
-    os.environ['QMK_VERSION'] = result.stdout.strip()
-else:
-    os.environ['QMK_VERSION'] = 'nogit-' + strftime('%Y-%m-%d-%H:%M:%S') + '-dirty'
+script_dir = Path(os.path.realpath(__file__)).parent
+qmk_dir = script_dir.parent
+python_lib_dir = Path(qmk_dir / 'lib' / 'python').resolve()
+sys.path.append(str(python_lib_dir))
 
 # Setup the CLI
 import milc  # noqa
@@ -63,8 +29,11 @@ def main():
     """
     # Change to the root of our checkout
     os.environ['ORIG_CWD'] = os.getcwd()
+    os.environ['DEPRECATED_BIN_QMK'] = '1'
     os.chdir(qmk_dir)
 
+    print('Warning: The bin/qmk script is being deprecated. Please install the QMK CLI: python3 -m pip install qmk', file=sys.stderr)
+
     # Import the subcommands
     import qmk.cli  # noqa
 

bootloader.mk

@@ -20,13 +20,19 @@
 # Sets the bootloader defined in the keyboard's/keymap's rules.mk
 # Current options:
 #
-# halfkay        PJRC Teensy
-# caterina       Pro Micro (Sparkfun/generic)
-# atmel-dfu      Atmel factory DFU
-# lufa-dfu       LUFA DFU
-# qmk-dfu        QMK DFU (LUFA + blinkenlight)
-# bootloadHID    HIDBootFlash compatible (ATmega32A)
-# USBasp         USBaspLoader (ATmega328P)
+# AVR:
+#     halfkay     PJRC Teensy
+#     caterina    Pro Micro (Sparkfun/generic)
+#     atmel-dfu   Atmel factory DFU
+#     lufa-dfu    LUFA DFU
+#     qmk-dfu     QMK DFU (LUFA + blinkenlight)
+#     bootloadHID HIDBootFlash compatible (ATmega32A)
+#     USBasp      USBaspLoader (ATmega328P)
+# ARM:
+#     kiibohd     Input:Club Kiibohd bootloader (only used on their boards)
+#     stm32duino  STM32Duino (STM32F103x8)
+#     stm32-dfu   STM32 USB DFU in ROM
+#     apm32-dfu   APM32 USB DFU in ROM
 #
 # BOOTLOADER_SIZE can still be defined manually, but it's recommended
 # you add any possible configuration to this list
@@ -34,30 +40,30 @@
 ifeq ($(strip $(BOOTLOADER)), atmel-dfu)
     OPT_DEFS += -DBOOTLOADER_ATMEL_DFU
     OPT_DEFS += -DBOOTLOADER_DFU
-    ifneq (,$(filter $(MCU), at90usb646 atmega16u2 atmega16u4 atmega32u2 atmega32u4))
+    ifneq (,$(filter $(MCU), at90usb162 atmega16u2 atmega32u2 atmega16u4 atmega32u4 at90usb646 at90usb647))
         BOOTLOADER_SIZE = 4096
     endif
-    ifeq ($(strip $(MCU)), at90usb1286)
+    ifneq (,$(filter $(MCU), at90usb1286 at90usb1287))
         BOOTLOADER_SIZE = 8192
     endif
 endif
 ifeq ($(strip $(BOOTLOADER)), lufa-dfu)
     OPT_DEFS += -DBOOTLOADER_LUFA_DFU
     OPT_DEFS += -DBOOTLOADER_DFU
-    ifneq (,$(filter $(MCU), at90usb646 atmega16u2 atmega16u4 atmega32u2 atmega32u4))
+    ifneq (,$(filter $(MCU), at90usb162 atmega16u2 atmega32u2 atmega16u4 atmega32u4 at90usb646 at90usb647))
         BOOTLOADER_SIZE = 4096
     endif
-    ifeq ($(strip $(MCU)), at90usb1286)
+    ifneq (,$(filter $(MCU), at90usb1286 at90usb1287))
         BOOTLOADER_SIZE = 8192
     endif
 endif
 ifeq ($(strip $(BOOTLOADER)), qmk-dfu)
     OPT_DEFS += -DBOOTLOADER_QMK_DFU
     OPT_DEFS += -DBOOTLOADER_DFU
-    ifneq (,$(filter $(MCU), at90usb646 atmega16u2 atmega16u4 atmega32u2 atmega32u4))
+    ifneq (,$(filter $(MCU), at90usb162 atmega16u2 atmega32u2 atmega16u4 atmega32u4 at90usb646 at90usb647))
         BOOTLOADER_SIZE = 4096
     endif
-    ifeq ($(strip $(MCU)), at90usb1286)
+    ifneq (,$(filter $(MCU), at90usb1286 at90usb1287))
         BOOTLOADER_SIZE = 8192
     endif
 endif
@@ -83,13 +89,56 @@ ifeq ($(strip $(BOOTLOADER)), USBasp)
     BOOTLOADER_SIZE = 4096
 endif
 ifeq ($(strip $(BOOTLOADER)), lufa-ms)
-    # DO NOT USE THIS BOOTLOADER IN NEW PROJECTS!
-    # It is extremely prone to bricking, and is only included to support existing boards.
     OPT_DEFS += -DBOOTLOADER_MS
     BOOTLOADER_SIZE = 6144
     FIRMWARE_FORMAT = bin
+    $(info LUFA MASS STORAGE Bootloader selected)
+    $(info DO NOT USE THIS BOOTLOADER IN NEW PROJECTS!)
+    $(info It is extremely prone to bricking, and is only included to support existing boards.)
+    $(info )
 endif
-
 ifdef BOOTLOADER_SIZE
     OPT_DEFS += -DBOOTLOADER_SIZE=$(strip $(BOOTLOADER_SIZE))
 endif
+
+ifeq ($(strip $(BOOTLOADER)), stm32-dfu)
+    OPT_DEFS += -DBOOTLOADER_STM32_DFU
+
+    # Options to pass to dfu-util when flashing
+    DFU_ARGS ?= -d 0483:DF11 -a 0 -s 0x08000000:leave
+    DFU_SUFFIX_ARGS ?= -v 0483 -p DF11
+endif
+ifeq ($(strip $(BOOTLOADER)), apm32-dfu)
+    OPT_DEFS += -DBOOTLOADER_APM32_DFU
+
+    # Options to pass to dfu-util when flashing
+    DFU_ARGS ?= -d 314B:0106 -a 0 -s 0x08000000:leave
+    DFU_SUFFIX_ARGS ?= -v 314B -p 0106
+endif
+ifeq ($(strip $(BOOTLOADER)), kiibohd)
+    OPT_DEFS += -DBOOTLOADER_KIIBOHD
+    ifeq ($(strip $(MCU_ORIG)), MK20DX128)
+        MCU_LDSCRIPT = MK20DX128BLDR4
+    endif
+    ifeq ($(strip $(MCU_ORIG)), MK20DX256)
+        MCU_LDSCRIPT = MK20DX256BLDR8
+    endif
+
+    # Options to pass to dfu-util when flashing
+    DFU_ARGS = -d 1C11:B007
+    DFU_SUFFIX_ARGS = -v 1C11 -p B007
+endif
+ifeq ($(strip $(BOOTLOADER)), stm32duino)
+    OPT_DEFS += -DBOOTLOADER_STM32DUINO
+    MCU_LDSCRIPT = STM32F103x8_stm32duino_bootloader
+    BOARD = STM32_F103_STM32DUINO
+    # STM32F103 does NOT have an USB bootloader in ROM (only serial), so setting anything here does not make much sense
+    STM32_BOOTLOADER_ADDRESS = 0x80000000
+
+    # Options to pass to dfu-util when flashing
+    DFU_ARGS = -d 1EAF:0003 -a 2 -R
+    DFU_SUFFIX_ARGS = -v 1EAF -p 0003
+endif
+ifeq ($(strip $(BOOTLOADER)), tinyuf2)
+    OPT_DEFS += -DBOOTLOADER_TINYUF2
+endif

build_full_test.mk

@@ -30,4 +30,4 @@ $(TEST)_SRC += $(patsubst $(ROOTDIR)/%,%,$(wildcard $(TEST_PATH)/*.cpp))
 
 $(TEST)_DEFS=$(TMK_COMMON_DEFS) $(OPT_DEFS)
 $(TEST)_CONFIG=$(TEST_PATH)/config.h
-VPATH+=$(TOP_DIR)/tests/test_common
+VPATH+=$(TOP_DIR)/tests/test_common

build_json.mk

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

build_keyboard.mk

@@ -12,11 +12,13 @@ endif
 
 include common.mk
 
+# Set the qmk cli to use
+QMK_BIN ?= qmk
+
 # 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)
@@ -91,13 +93,16 @@ ifneq ("$(wildcard $(KEYBOARD_PATH_1)/rules.mk)","")
     include $(KEYBOARD_PATH_1)/rules.mk
 endif
 
-
 MAIN_KEYMAP_PATH_1 := $(KEYBOARD_PATH_1)/keymaps/$(KEYMAP)
 MAIN_KEYMAP_PATH_2 := $(KEYBOARD_PATH_2)/keymaps/$(KEYMAP)
 MAIN_KEYMAP_PATH_3 := $(KEYBOARD_PATH_3)/keymaps/$(KEYMAP)
 MAIN_KEYMAP_PATH_4 := $(KEYBOARD_PATH_4)/keymaps/$(KEYMAP)
 MAIN_KEYMAP_PATH_5 := $(KEYBOARD_PATH_5)/keymaps/$(KEYMAP)
 
+# Pull in rules from info.json
+INFO_RULES_MK = $(shell $(QMK_BIN) generate-rules-mk --quiet --escape --keyboard $(KEYBOARD) --output $(KEYBOARD_OUTPUT)/src/rules.mk)
+include $(INFO_RULES_MK)
+
 # Check for keymap.json first, so we can regenerate keymap.c
 include build_json.mk
 
@@ -137,9 +142,7 @@ ifeq ($(strip $(CTPC)), 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
+    include platforms/chibios/QMK_PROTON_C/convert_to_proton_c.mk
 endif
 
 ifneq ($(FORCE_LAYOUT),)
@@ -148,12 +151,6 @@ 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 :=
 
@@ -211,6 +208,7 @@ endif
 #
 #    https://docs.qmk.fm/#/feature_layouts?id=tips-for-making-layouts-keyboard-agnostic
 #
+QMK_KEYBOARD_H = $(KEYBOARD_OUTPUT)/src/default_keyboard.h
 ifneq ("$(wildcard $(KEYBOARD_PATH_1)/$(KEYBOARD_FOLDER_1).h)","")
     QMK_KEYBOARD_H = $(KEYBOARD_FOLDER_1).h
 endif
@@ -279,6 +277,39 @@ ifneq ("$(wildcard $(KEYBOARD_PATH_5)/post_config.h)","")
     POST_CONFIG_H += $(KEYBOARD_PATH_5)/post_config.h
 endif
 
+# Pull in stuff from info.json
+INFO_JSON_FILES :=
+ifneq ("$(wildcard $(KEYBOARD_PATH_1)/info.json)","")
+    INFO_JSON_FILES += $(KEYBOARD_PATH_1)/info.json
+endif
+ifneq ("$(wildcard $(KEYBOARD_PATH_2)/info.json)","")
+    INFO_JSON_FILES += $(KEYBOARD_PATH_2)/info.json
+endif
+ifneq ("$(wildcard $(KEYBOARD_PATH_3)/info.json)","")
+    INFO_JSON_FILES += $(KEYBOARD_PATH_3)/info.json
+endif
+ifneq ("$(wildcard $(KEYBOARD_PATH_4)/info.json)","")
+    INFO_JSON_FILES += $(KEYBOARD_PATH_4)/info.json
+endif
+ifneq ("$(wildcard $(KEYBOARD_PATH_5)/info.json)","")
+    INFO_JSON_FILES += $(KEYBOARD_PATH_5)/info.json
+endif
+
+CONFIG_H += $(KEYBOARD_OUTPUT)/src/info_config.h $(KEYBOARD_OUTPUT)/src/layouts.h
+
+$(KEYBOARD_OUTPUT)/src/info_config.h: $(INFO_JSON_FILES)
+	$(QMK_BIN) generate-config-h --quiet --keyboard $(KEYBOARD) --output $(KEYBOARD_OUTPUT)/src/info_config.h
+
+$(KEYBOARD_OUTPUT)/src/default_keyboard.h: $(INFO_JSON_FILES)
+	$(QMK_BIN) generate-keyboard-h --quiet --keyboard $(KEYBOARD) --output $(KEYBOARD_OUTPUT)/src/default_keyboard.h
+
+$(KEYBOARD_OUTPUT)/src/layouts.h: $(INFO_JSON_FILES)
+	$(QMK_BIN) generate-layouts --quiet --keyboard $(KEYBOARD) --output $(KEYBOARD_OUTPUT)/src/layouts.h
+
+generated-files: $(KEYBOARD_OUTPUT)/src/info_config.h $(KEYBOARD_OUTPUT)/src/default_keyboard.h $(KEYBOARD_OUTPUT)/src/layouts.h
+
+.INTERMEDIATE : generated-files
+
 # Userspace setup and definitions
 ifeq ("$(USER_NAME)","")
     USER_NAME := $(KEYMAP)
@@ -289,6 +320,12 @@ USER_PATH := users/$(USER_NAME)
 ifneq ("$(wildcard $(USER_PATH)/config.h)","")
     CONFIG_H += $(USER_PATH)/config.h
 endif
+ifneq ("$(wildcard $(USER_PATH)/post_config.h)","")
+    POST_CONFIG_H += $(USER_PATH)/post_config.h
+endif
+
+# Disable features that a keyboard doesn't support
+-include disable_features.mk
 
 # Object files directory
 #     To put object files in current directory, use a dot (.), do NOT make
@@ -324,6 +361,13 @@ SRC += $(TMK_COMMON_SRC)
 OPT_DEFS += $(TMK_COMMON_DEFS)
 EXTRALDFLAGS += $(TMK_COMMON_LDFLAGS)
 
+SKIP_COMPILE := no
+ifneq ($(REQUIRE_PLATFORM_KEY),)
+    ifneq ($(REQUIRE_PLATFORM_KEY),$(PLATFORM_KEY))
+        SKIP_COMPILE := yes
+    endif
+endif
+
 include $(TMK_PATH)/$(PLATFORM_KEY).mk
 ifneq ($(strip $(PROTOCOL)),)
     include $(TMK_PATH)/protocol/$(strip $(shell echo $(PROTOCOL) | tr '[:upper:]' '[:lower:]')).mk
@@ -348,7 +392,7 @@ ALL_CONFIGS := $(PROJECT_CONFIG) $(CONFIG_H)
 OUTPUTS := $(KEYMAP_OUTPUT) $(KEYBOARD_OUTPUT)
 $(KEYMAP_OUTPUT)_SRC := $(SRC)
 $(KEYMAP_OUTPUT)_DEFS := $(OPT_DEFS) $(GFXDEFS) \
--DQMK_KEYBOARD=\"$(KEYBOARD)\" -DQMK_KEYBOARD_H=\"$(QMK_KEYBOARD_H)\" -DQMK_KEYBOARD_CONFIG_H=\"$(KEYBOARD_PATH_1)/config.h\" \
+-DQMK_KEYBOARD=\"$(KEYBOARD)\" -DQMK_KEYBOARD_H=\"$(QMK_KEYBOARD_H)\" \
 -DQMK_KEYMAP=\"$(KEYMAP)\" -DQMK_KEYMAP_H=\"$(KEYMAP).h\" -DQMK_KEYMAP_CONFIG_H=\"$(KEYMAP_PATH)/config.h\" \
 -DQMK_SUBPROJECT -DQMK_SUBPROJECT_H -DQMK_SUBPROJECT_CONFIG_H
 $(KEYMAP_OUTPUT)_INC :=  $(VPATH) $(EXTRAINCDIRS)
@@ -359,10 +403,23 @@ $(KEYBOARD_OUTPUT)_INC := $(PROJECT_INC) $(GFXINC)
 $(KEYBOARD_OUTPUT)_CONFIG := $(PROJECT_CONFIG)
 
 # Default target.
+ifeq ($(SKIP_COMPILE),no)
 all: build check-size
+else
+all:
+	echo "skipped" >&2
+endif
+
 build: elf cpfirmware
 check-size: build
+check-md5: build
 objs-size: build
 
 include show_options.mk
 include $(TMK_PATH)/rules.mk
+
+# Ensure we have generated files available for each of the objects
+define GEN_FILES
+$1: generated-files
+endef
+$(foreach O,$(OBJ),$(eval $(call GEN_FILES,$(patsubst %.a,%.o,$(O)))))

build_layout.mk

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

build_test.mk

@@ -17,7 +17,7 @@ OUTPUTS := $(TEST_OBJ)/$(TEST) $(GTEST_OUTPUT)
 GTEST_INC := \
 	$(LIB_PATH)/googletest/googletest/include\
 	$(LIB_PATH)/googletest/googlemock/include\
-	
+
 GTEST_INTERNAL_INC :=\
 	$(LIB_PATH)/googletest/googletest\
 	$(LIB_PATH)/googletest/googlemock
@@ -27,7 +27,7 @@ $(GTEST_OUTPUT)_SRC :=\
 	googletest/src/gtest_main.cc\
 	googlemock/src/gmock-all.cc
 
-$(GTEST_OUTPUT)_DEFS := 
+$(GTEST_OUTPUT)_DEFS :=
 $(GTEST_OUTPUT)_INC := $(GTEST_INC) $(GTEST_INTERNAL_INC)
 
 LDFLAGS += -lstdc++ -lpthread -shared-libgcc
@@ -49,6 +49,7 @@ endif
 
 include common_features.mk
 include $(TMK_PATH)/common.mk
+include $(QUANTUM_PATH)/sequencer/tests/rules.mk
 include $(QUANTUM_PATH)/serial_link/tests/rules.mk
 ifneq ($(filter $(FULL_TESTS),$(TEST)),)
 include build_full_test.mk
@@ -65,4 +66,3 @@ include $(TMK_PATH)/rules.mk
 
 $(shell mkdir -p $(BUILD_DIR)/test 2>/dev/null)
 $(shell mkdir -p $(TEST_OBJ) 2>/dev/null)
-

common.mk

@@ -21,4 +21,5 @@ COMMON_VPATH += $(QUANTUM_PATH)/keymap_extras
 COMMON_VPATH += $(QUANTUM_PATH)/audio
 COMMON_VPATH += $(QUANTUM_PATH)/process_keycode
 COMMON_VPATH += $(QUANTUM_PATH)/api
+COMMON_VPATH += $(QUANTUM_PATH)/sequencer
 COMMON_VPATH += $(DRIVER_PATH)

common_features.mk

@@ -17,9 +17,19 @@ SERIAL_PATH := $(QUANTUM_PATH)/serial_link
 
 QUANTUM_SRC += \
     $(QUANTUM_DIR)/quantum.c \
+    $(QUANTUM_DIR)/send_string.c \
+    $(QUANTUM_DIR)/bitwise.c \
+    $(QUANTUM_DIR)/led.c \
     $(QUANTUM_DIR)/keymap_common.c \
     $(QUANTUM_DIR)/keycode_config.c
 
+ifeq ($(strip $(DEBUG_MATRIX_SCAN_RATE_ENABLE)), yes)
+    OPT_DEFS += -DDEBUG_MATRIX_SCAN_RATE
+    CONSOLE_ENABLE = yes
+else ifeq ($(strip $(DEBUG_MATRIX_SCAN_RATE_ENABLE)), api)
+    OPT_DEFS += -DDEBUG_MATRIX_SCAN_RATE
+endif
+
 ifeq ($(strip $(API_SYSEX_ENABLE)), yes)
     OPT_DEFS += -DAPI_SYSEX_ENABLE
     OPT_DEFS += -DAPI_ENABLE
@@ -28,16 +38,47 @@ ifeq ($(strip $(API_SYSEX_ENABLE)), yes)
     SRC += $(QUANTUM_DIR)/api.c
 endif
 
+ifeq ($(strip $(COMMAND_ENABLE)), yes)
+    SRC += $(QUANTUM_DIR)/command.c
+    OPT_DEFS += -DCOMMAND_ENABLE
+endif
+
+AUDIO_ENABLE ?= no
 ifeq ($(strip $(AUDIO_ENABLE)), yes)
+    ifeq ($(PLATFORM),CHIBIOS)
+        AUDIO_DRIVER ?= dac_basic
+        ifeq ($(strip $(AUDIO_DRIVER)), dac_basic)
+            OPT_DEFS += -DAUDIO_DRIVER_DAC
+        else ifeq ($(strip $(AUDIO_DRIVER)), dac_additive)
+            OPT_DEFS += -DAUDIO_DRIVER_DAC
+        ## stm32f2 and above have a usable DAC unit, f1 do not, and need to use pwm instead
+        else ifeq ($(strip $(AUDIO_DRIVER)), pwm_software)
+            OPT_DEFS += -DAUDIO_DRIVER_PWM
+        else ifeq ($(strip $(AUDIO_DRIVER)), pwm_hardware)
+            OPT_DEFS += -DAUDIO_DRIVER_PWM
+        endif
+    else
+        # fallback for all other platforms is pwm
+        AUDIO_DRIVER ?= pwm_hardware
+        OPT_DEFS += -DAUDIO_DRIVER_PWM
+    endif
     OPT_DEFS += -DAUDIO_ENABLE
     MUSIC_ENABLE = yes
     SRC += $(QUANTUM_DIR)/process_keycode/process_audio.c
     SRC += $(QUANTUM_DIR)/process_keycode/process_clicky.c
-    SRC += $(QUANTUM_DIR)/audio/audio_$(PLATFORM_KEY).c
+    SRC += $(QUANTUM_DIR)/audio/audio.c ## common audio code, hardware agnostic
+    SRC += $(QUANTUM_DIR)/audio/driver_$(PLATFORM_KEY)_$(strip $(AUDIO_DRIVER)).c
     SRC += $(QUANTUM_DIR)/audio/voices.c
     SRC += $(QUANTUM_DIR)/audio/luts.c
 endif
 
+ifeq ($(strip $(SEQUENCER_ENABLE)), yes)
+    OPT_DEFS += -DSEQUENCER_ENABLE
+    MUSIC_ENABLE = yes
+    SRC += $(QUANTUM_DIR)/sequencer/sequencer.c
+    SRC += $(QUANTUM_DIR)/process_keycode/process_sequencer.c
+endif
+
 ifeq ($(strip $(MIDI_ENABLE)), yes)
     OPT_DEFS += -DMIDI_ENABLE
     MUSIC_ENABLE = yes
@@ -59,9 +100,10 @@ ifeq ($(strip $(VIRTSER_ENABLE)), yes)
     OPT_DEFS += -DVIRTSER_ENABLE
 endif
 
-ifeq ($(strip $(FAUXCLICKY_ENABLE)), yes)
-    OPT_DEFS += -DFAUXCLICKY_ENABLE
-    SRC += $(QUANTUM_DIR)/fauxclicky.c
+ifeq ($(strip $(MOUSEKEY_ENABLE)), yes)
+    OPT_DEFS += -DMOUSEKEY_ENABLE
+    OPT_DEFS += -DMOUSE_ENABLE
+    SRC += $(QUANTUM_DIR)/mousekey.c
 endif
 
 ifeq ($(strip $(POINTING_DEVICE_ENABLE)), yes)
@@ -70,7 +112,7 @@ ifeq ($(strip $(POINTING_DEVICE_ENABLE)), yes)
     SRC += $(QUANTUM_DIR)/pointing_device.c
 endif
 
-VALID_EEPROM_DRIVER_TYPES := vendor custom transient i2c
+VALID_EEPROM_DRIVER_TYPES := vendor custom transient i2c spi
 EEPROM_DRIVER ?= vendor
 ifeq ($(filter $(EEPROM_DRIVER),$(VALID_EEPROM_DRIVER_TYPES)),)
   $(error EEPROM_DRIVER="$(EEPROM_DRIVER)" is not a valid EEPROM driver)
@@ -85,6 +127,11 @@ else
     COMMON_VPATH += $(DRIVER_PATH)/eeprom
     QUANTUM_LIB_SRC += i2c_master.c
     SRC += eeprom_driver.c eeprom_i2c.c
+  else ifeq ($(strip $(EEPROM_DRIVER)), spi)
+    OPT_DEFS += -DEEPROM_DRIVER -DEEPROM_SPI
+    COMMON_VPATH += $(DRIVER_PATH)/eeprom
+    QUANTUM_LIB_SRC += spi_master.c
+    SRC += eeprom_driver.c eeprom_spi.c
   else ifeq ($(strip $(EEPROM_DRIVER)), transient)
     OPT_DEFS += -DEEPROM_DRIVER -DEEPROM_TRANSIENT
     COMMON_VPATH += $(DRIVER_PATH)/eeprom
@@ -109,6 +156,17 @@ else
         SRC += $(PLATFORM_COMMON_DIR)/flash_stm32.c
         OPT_DEFS += -DEEPROM_EMU_STM32F072xB
         OPT_DEFS += -DSTM32_EEPROM_ENABLE
+      else ifeq ($(MCU_SERIES)_$(MCU_LDSCRIPT), STM32F0xx_STM32F042x6)
+
+        # Stack sizes: Since this chip has limited RAM capacity, the stack area needs to be reduced.
+        # This ensures that the EEPROM page buffer fits into RAM
+        USE_PROCESS_STACKSIZE = 0x600
+        USE_EXCEPTIONS_STACKSIZE = 0x300
+
+        SRC += $(PLATFORM_COMMON_DIR)/eeprom_stm32.c
+        SRC += $(PLATFORM_COMMON_DIR)/flash_stm32.c
+        OPT_DEFS += -DEEPROM_EMU_STM32F042x6
+        OPT_DEFS += -DSTM32_EEPROM_ENABLE
       else ifneq ($(filter $(MCU_SERIES),STM32L0xx STM32L1xx),)
         OPT_DEFS += -DEEPROM_DRIVER
         COMMON_VPATH += $(DRIVER_PATH)/eeprom
@@ -125,92 +183,129 @@ else
   endif
 endif
 
+RGBLIGHT_ENABLE ?= no
+VALID_RGBLIGHT_TYPES := WS2812 APA102 custom
+
+ifeq ($(strip $(RGBLIGHT_CUSTOM_DRIVER)), yes)
+    RGBLIGHT_DRIVER ?= custom
+endif
+
 ifeq ($(strip $(RGBLIGHT_ENABLE)), yes)
-    POST_CONFIG_H += $(QUANTUM_DIR)/rgblight_post_config.h
-    OPT_DEFS += -DRGBLIGHT_ENABLE
-    SRC += $(QUANTUM_DIR)/color.c
-    SRC += $(QUANTUM_DIR)/rgblight.c
-    CIE1931_CURVE := yes
-    RGB_KEYCODES_ENABLE := yes
-    ifeq ($(strip $(RGBLIGHT_CUSTOM_DRIVER)), yes)
-        OPT_DEFS += -DRGBLIGHT_CUSTOM_DRIVER
+    RGBLIGHT_DRIVER ?= WS2812
+
+    ifeq ($(filter $(RGBLIGHT_DRIVER),$(VALID_RGBLIGHT_TYPES)),)
+        $(error RGBLIGHT_DRIVER="$(RGBLIGHT_DRIVER)" is not a valid RGB type)
     else
+        POST_CONFIG_H += $(QUANTUM_DIR)/rgblight_post_config.h
+        OPT_DEFS += -DRGBLIGHT_ENABLE
+        SRC += $(QUANTUM_DIR)/color.c
+        SRC += $(QUANTUM_DIR)/rgblight.c
+        CIE1931_CURVE := yes
+        RGB_KEYCODES_ENABLE := yes
+    endif
+
+    ifeq ($(strip $(RGBLIGHT_DRIVER)), WS2812)
         WS2812_DRIVER_REQUIRED := yes
     endif
-endif
 
-VALID_MATRIX_TYPES := yes IS31FL3731 IS31FL3733 IS31FL3737 WS2812 custom
+    ifeq ($(strip $(RGBLIGHT_DRIVER)), APA102)
+        APA102_DRIVER_REQUIRED := yes
+    endif
 
-LED_MATRIX_ENABLE ?= no
-ifneq ($(strip $(LED_MATRIX_ENABLE)), no)
-    ifeq ($(filter $(LED_MATRIX_ENABLE),$(VALID_MATRIX_TYPES)),)
-        $(error LED_MATRIX_ENABLE="$(LED_MATRIX_ENABLE)" is not a valid matrix type)
-    else
-        BACKLIGHT_ENABLE = yes
-        BACKLIGHT_DRIVER = custom
-        OPT_DEFS += -DLED_MATRIX_ENABLE
-        SRC += $(QUANTUM_DIR)/led_matrix.c
-        SRC += $(QUANTUM_DIR)/led_matrix_drivers.c
+    ifeq ($(strip $(RGBLIGHT_DRIVER)), custom)
+        OPT_DEFS += -DRGBLIGHT_CUSTOM_DRIVER
     endif
 endif
 
-ifeq ($(strip $(LED_MATRIX_ENABLE)), IS31FL3731)
-    OPT_DEFS += -DIS31FL3731
-    COMMON_VPATH += $(DRIVER_PATH)/issi
-    SRC += is31fl3731-simple.c
-    QUANTUM_LIB_SRC += i2c_master.c
+LED_MATRIX_ENABLE ?= no
+VALID_LED_MATRIX_TYPES := IS31FL3731 custom
+# TODO: IS31FL3733 IS31FL3737 IS31FL3741
+
+ifeq ($(strip $(LED_MATRIX_ENABLE)), yes)
+    ifeq ($(filter $(LED_MATRIX_DRIVER),$(VALID_LED_MATRIX_TYPES)),)
+        $(error "$(LED_MATRIX_DRIVER)" is not a valid matrix type)
+    endif
+    OPT_DEFS += -DLED_MATRIX_ENABLE
+ifneq (,$(filter $(MCU), atmega16u2 atmega32u2 at90usb162))
+    # ATmegaxxU2 does not have hardware MUL instruction - lib8tion must be told to use software multiplication routines
+    OPT_DEFS += -DLIB8_ATTINY
+endif
+    SRC += $(QUANTUM_DIR)/process_keycode/process_backlight.c
+    SRC += $(QUANTUM_DIR)/led_matrix.c
+    SRC += $(QUANTUM_DIR)/led_matrix_drivers.c
+    CIE1931_CURVE := yes
+
+    ifeq ($(strip $(LED_MATRIX_DRIVER)), IS31FL3731)
+        OPT_DEFS += -DIS31FL3731 -DSTM32_I2C -DHAL_USE_I2C=TRUE
+        COMMON_VPATH += $(DRIVER_PATH)/issi
+        SRC += is31fl3731-simple.c
+        QUANTUM_LIB_SRC += i2c_master.c
+    endif
 endif
 
 RGB_MATRIX_ENABLE ?= no
+VALID_RGB_MATRIX_TYPES := IS31FL3731 IS31FL3733 IS31FL3737 IS31FL3741 WS2812 custom
 
-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
+ifeq ($(strip $(RGB_MATRIX_ENABLE)), yes)
+    ifeq ($(filter $(RGB_MATRIX_DRIVER),$(VALID_RGB_MATRIX_TYPES)),)
+        $(error "$(RGB_MATRIX_DRIVER)" is not a valid matrix type)
+    endif
     OPT_DEFS += -DRGB_MATRIX_ENABLE
+ifneq (,$(filter $(MCU), atmega16u2 atmega32u2 at90usb162))
+    # ATmegaxxU2 does not have hardware MUL instruction - lib8tion must be told to use software multiplication routines
+    OPT_DEFS += -DLIB8_ATTINY
+endif
     SRC += $(QUANTUM_DIR)/color.c
     SRC += $(QUANTUM_DIR)/rgb_matrix.c
     SRC += $(QUANTUM_DIR)/rgb_matrix_drivers.c
     CIE1931_CURVE := yes
     RGB_KEYCODES_ENABLE := yes
-endif
 
-ifeq ($(strip $(RGB_MATRIX_ENABLE)), yes)
-	RGB_MATRIX_ENABLE := IS31FL3731
-endif
+    ifeq ($(strip $(RGB_MATRIX_DRIVER)), IS31FL3731)
+        OPT_DEFS += -DIS31FL3731 -DSTM32_I2C -DHAL_USE_I2C=TRUE
+        COMMON_VPATH += $(DRIVER_PATH)/issi
+        SRC += is31fl3731.c
+        QUANTUM_LIB_SRC += i2c_master.c
+    endif
 
-ifeq ($(strip $(RGB_MATRIX_ENABLE)), IS31FL3731)
-    OPT_DEFS += -DIS31FL3731 -DSTM32_I2C -DHAL_USE_I2C=TRUE
-    COMMON_VPATH += $(DRIVER_PATH)/issi
-    SRC += is31fl3731.c
-    QUANTUM_LIB_SRC += i2c_master.c
-endif
+    ifeq ($(strip $(RGB_MATRIX_DRIVER)), IS31FL3733)
+        OPT_DEFS += -DIS31FL3733 -DSTM32_I2C -DHAL_USE_I2C=TRUE
+        COMMON_VPATH += $(DRIVER_PATH)/issi
+        SRC += is31fl3733.c
+        QUANTUM_LIB_SRC += i2c_master.c
+    endif
 
-ifeq ($(strip $(RGB_MATRIX_ENABLE)), IS31FL3733)
-    OPT_DEFS += -DIS31FL3733 -DSTM32_I2C -DHAL_USE_I2C=TRUE
-    COMMON_VPATH += $(DRIVER_PATH)/issi
-    SRC += is31fl3733.c
-    QUANTUM_LIB_SRC += i2c_master.c
-endif
+    ifeq ($(strip $(RGB_MATRIX_DRIVER)), IS31FL3737)
+        OPT_DEFS += -DIS31FL3737 -DSTM32_I2C -DHAL_USE_I2C=TRUE
+        COMMON_VPATH += $(DRIVER_PATH)/issi
+        SRC += is31fl3737.c
+        QUANTUM_LIB_SRC += i2c_master.c
+    endif
 
-ifeq ($(strip $(RGB_MATRIX_ENABLE)), IS31FL3737)
-    OPT_DEFS += -DIS31FL3737 -DSTM32_I2C -DHAL_USE_I2C=TRUE
-    COMMON_VPATH += $(DRIVER_PATH)/issi
-    SRC += is31fl3737.c
-    QUANTUM_LIB_SRC += i2c_master.c
-endif
+    ifeq ($(strip $(RGB_MATRIX_DRIVER)), IS31FL3741)
+        OPT_DEFS += -DIS31FL3741 -DSTM32_I2C -DHAL_USE_I2C=TRUE
+        COMMON_VPATH += $(DRIVER_PATH)/issi
+        SRC += is31fl3741.c
+        QUANTUM_LIB_SRC += i2c_master.c
+    endif
 
-ifeq ($(strip $(RGB_MATRIX_ENABLE)), WS2812)
-    OPT_DEFS += -DWS2812
-    WS2812_DRIVER_REQUIRED := yes
-endif
+    ifeq ($(strip $(RGB_MATRIX_DRIVER)), WS2812)
+        OPT_DEFS += -DWS2812
+        WS2812_DRIVER_REQUIRED := yes
+    endif
 
-ifeq ($(strip $(RGB_MATRIX_CUSTOM_KB)), yes)
-    OPT_DEFS += -DRGB_MATRIX_CUSTOM_KB
-endif
+    ifeq ($(strip $(RGB_MATRIX_DRIVER)), APA102)
+        OPT_DEFS += -DAPA102
+        APA102_DRIVER_REQUIRED := yes
+    endif
 
-ifeq ($(strip $(RGB_MATRIX_CUSTOM_USER)), yes)
-    OPT_DEFS += -DRGB_MATRIX_CUSTOM_USER
+    ifeq ($(strip $(RGB_MATRIX_CUSTOM_KB)), yes)
+        OPT_DEFS += -DRGB_MATRIX_CUSTOM_KB
+    endif
+
+    ifeq ($(strip $(RGB_MATRIX_CUSTOM_USER)), yes)
+        OPT_DEFS += -DRGB_MATRIX_CUSTOM_USER
+    endif
 endif
 
 ifeq ($(strip $(RGB_KEYCODES_ENABLE)), yes)
@@ -234,12 +329,13 @@ ifeq ($(strip $(SERIAL_LINK_ENABLE)), yes)
     VAPTH += $(SERIAL_PATH)
 endif
 
-ifneq ($(strip $(VARIABLE_TRACE)),)
+VARIABLE_TRACE ?= no
+ifneq ($(strip $(VARIABLE_TRACE)),no)
     SRC += $(QUANTUM_DIR)/variable_trace.c
     OPT_DEFS += -DNUM_TRACED_VARIABLES=$(strip $(VARIABLE_TRACE))
-ifneq ($(strip $(MAX_VARIABLE_TRACE_SIZE)),)
-    OPT_DEFS += -DMAX_VARIABLE_TRACE_SIZE=$(strip $(MAX_VARIABLE_TRACE_SIZE))
-endif
+    ifneq ($(strip $(MAX_VARIABLE_TRACE_SIZE)),)
+        OPT_DEFS += -DMAX_VARIABLE_TRACE_SIZE=$(strip $(MAX_VARIABLE_TRACE_SIZE))
+    endif
 endif
 
 ifeq ($(strip $(LCD_ENABLE)), yes)
@@ -251,10 +347,14 @@ ifeq ($(strip $(BACKLIGHT_CUSTOM_DRIVER)), yes)
     BACKLIGHT_DRIVER := custom
 endif
 
-VALID_BACKLIGHT_TYPES := pwm software custom
+VALID_BACKLIGHT_TYPES := pwm timer software custom
 
 BACKLIGHT_ENABLE ?= no
-BACKLIGHT_DRIVER ?= pwm
+ifeq ($(strip $(CONVERT_TO_PROTON_C)), yes)
+    BACKLIGHT_DRIVER ?= software
+else
+    BACKLIGHT_DRIVER ?= pwm
+endif
 ifeq ($(strip $(BACKLIGHT_ENABLE)), yes)
     ifeq ($(filter $(BACKLIGHT_DRIVER),$(VALID_BACKLIGHT_TYPES)),)
         $(error BACKLIGHT_DRIVER="$(BACKLIGHT_DRIVER)" is not a valid backlight type)
@@ -291,6 +391,12 @@ ifeq ($(strip $(WS2812_DRIVER_REQUIRED)), yes)
         SRC += ws2812.c
     else
         SRC += ws2812_$(strip $(WS2812_DRIVER)).c
+
+        ifeq ($(strip $(PLATFORM)), CHIBIOS)
+            ifeq ($(strip $(WS2812_DRIVER)), pwm)
+                OPT_DEFS += -DSTM32_DMA_REQUIRED=TRUE
+            endif
+        endif
     endif
 
     # add extra deps
@@ -299,6 +405,11 @@ ifeq ($(strip $(WS2812_DRIVER_REQUIRED)), yes)
     endif
 endif
 
+ifeq ($(strip $(APA102_DRIVER_REQUIRED)), yes)
+    COMMON_VPATH += $(DRIVER_PATH)/apa102
+    SRC += apa102.c
+endif
+
 ifeq ($(strip $(VISUALIZER_ENABLE)), yes)
     CIE1931_CURVE := yes
 endif
@@ -318,8 +429,9 @@ ifeq ($(strip $(TERMINAL_ENABLE)), yes)
     OPT_DEFS += -DUSER_PRINT
 endif
 
-ifeq ($(strip $(USB_HID_ENABLE)), yes)
-    include $(TMK_DIR)/protocol/usb_hid.mk
+ifeq ($(strip $(WPM_ENABLE)), yes)
+    SRC += $(QUANTUM_DIR)/wpm.c
+    OPT_DEFS += -DWPM_ENABLE
 endif
 
 ifeq ($(strip $(ENCODER_ENABLE)), yes)
@@ -350,6 +462,23 @@ ifeq ($(strip $(DIP_SWITCH_ENABLE)), yes)
     SRC += $(QUANTUM_DIR)/dip_switch.c
 endif
 
+VALID_MAGIC_TYPES := yes full lite
+BOOTMAGIC_ENABLE ?= no
+ifneq ($(strip $(BOOTMAGIC_ENABLE)), no)
+  ifeq ($(filter $(BOOTMAGIC_ENABLE),$(VALID_MAGIC_TYPES)),)
+    $(error BOOTMAGIC_ENABLE="$(BOOTMAGIC_ENABLE)" is not a valid type of magic)
+  endif
+  ifneq ($(strip $(BOOTMAGIC_ENABLE)), full)
+      OPT_DEFS += -DBOOTMAGIC_LITE
+      QUANTUM_SRC += $(QUANTUM_DIR)/bootmagic/bootmagic_lite.c
+  else
+    OPT_DEFS += -DBOOTMAGIC_ENABLE
+    QUANTUM_SRC += $(QUANTUM_DIR)/bootmagic/bootmagic_full.c
+  endif
+endif
+COMMON_VPATH += $(QUANTUM_DIR)/bootmagic
+QUANTUM_SRC += $(QUANTUM_DIR)/bootmagic/magic.c
+
 VALID_CUSTOM_MATRIX_TYPES:= yes lite no
 
 CUSTOM_MATRIX ?= no
@@ -373,9 +502,20 @@ ifneq ($(strip $(CUSTOM_MATRIX)), yes)
     endif
 endif
 
+# Support for translating old names to new names:
+ifeq ($(strip $(DEBOUNCE_TYPE)),sym_g)
+    DEBOUNCE_TYPE:=sym_defer_g
+else ifeq ($(strip $(DEBOUNCE_TYPE)),eager_pk)
+    DEBOUNCE_TYPE:=sym_eager_pk
+else ifeq ($(strip $(DEBOUNCE_TYPE)),sym_pk)
+    DEBOUNCE_TYPE:=sym_defer_pk
+else ifeq ($(strip $(DEBOUNCE_TYPE)),eager_pr)
+    DEBOUNCE_TYPE:=sym_eager_pr
+endif
+
 DEBOUNCE_DIR:= $(QUANTUM_DIR)/debounce
 # Debounce Modules. Set DEBOUNCE_TYPE=custom if including one manually.
-DEBOUNCE_TYPE?= sym_g
+DEBOUNCE_TYPE?= sym_defer_g
 ifneq ($(strip $(DEBOUNCE_TYPE)), custom)
     QUANTUM_SRC += $(DEBOUNCE_DIR)/$(strip $(DEBOUNCE_TYPE)).c
 endif
@@ -389,15 +529,18 @@ ifeq ($(strip $(SPLIT_KEYBOARD)), yes)
 
     # Determine which (if any) transport files are required
     ifneq ($(strip $(SPLIT_TRANSPORT)), custom)
-        QUANTUM_SRC += $(QUANTUM_DIR)/split_common/transport.c
+        QUANTUM_LIB_SRC += $(QUANTUM_DIR)/split_common/transport.c
         # Functions added via QUANTUM_LIB_SRC are only included in the final binary if they're called.
         # Unused functions are pruned away, which is why we can add multiple drivers here without bloat.
         ifeq ($(PLATFORM),AVR)
-            QUANTUM_LIB_SRC += i2c_master.c \
-                               i2c_slave.c
+            ifneq ($(NO_I2C),yes)
+                QUANTUM_LIB_SRC += i2c_master.c \
+                                   i2c_slave.c
+            endif
         endif
 
         SERIAL_DRIVER ?= bitbang
+        OPT_DEFS += -DSERIAL_DRIVER_$(strip $(shell echo $(SERIAL_DRIVER) | tr '[:lower:]' '[:upper:]'))
         ifeq ($(strip $(SERIAL_DRIVER)), bitbang)
             QUANTUM_LIB_SRC += serial.c
         else
@@ -511,3 +654,43 @@ ifeq ($(strip $(AUTO_SHIFT_ENABLE)), yes)
         OPT_DEFS += -DAUTO_SHIFT_MODIFIERS
     endif
 endif
+
+JOYSTICK_ENABLE ?= no
+ifneq ($(strip $(JOYSTICK_ENABLE)), no)
+    OPT_DEFS += -DJOYSTICK_ENABLE
+    SRC += $(QUANTUM_DIR)/process_keycode/process_joystick.c
+    SRC += $(QUANTUM_DIR)/joystick.c
+endif
+
+ifeq ($(strip $(JOYSTICK_ENABLE)), analog)
+    OPT_DEFS += -DANALOG_JOYSTICK_ENABLE
+    SRC += analog.c
+endif
+
+ifeq ($(strip $(JOYSTICK_ENABLE)), digital)
+    OPT_DEFS += -DDIGITAL_JOYSTICK_ENABLE
+endif
+
+USBPD_ENABLE ?= no
+VALID_USBPD_DRIVER_TYPES = custom vendor
+USBPD_DRIVER ?= vendor
+ifeq ($(strip $(USBPD_ENABLE)), yes)
+    ifeq ($(filter $(strip $(USBPD_DRIVER)),$(VALID_USBPD_DRIVER_TYPES)),)
+        $(error USBPD_DRIVER="$(USBPD_DRIVER)" is not a valid USBPD driver)
+    else
+        OPT_DEFS += -DUSBPD_ENABLE
+        ifeq ($(strip $(USBPD_DRIVER)), vendor)
+            # Vendor-specific implementations
+            OPT_DEFS += -DUSBPD_VENDOR
+            ifeq ($(strip $(MCU_SERIES)), STM32G4xx)
+                OPT_DEFS += -DUSBPD_STM32G4
+                SRC += usbpd_stm32g4.c
+            else
+                $(error There is no vendor-provided USBPD driver available)
+            endif
+        else ifeq ($(strip $(USBPD_DRIVER)), custom)
+            OPT_DEFS += -DUSBPD_CUSTOM
+            # Board designers can add their own driver to $(SRC)
+        endif
+    endif
+endif

data/mappings/info_config.json

@@ -0,0 +1,46 @@
+# This file maps keys between `config.h` and `info.json`. It is used by QMK 
+# to correctly and consistently map back and forth between the two systems.
+{
+    # Format:
+    # <config.h key>: {"info_key": <info.json key>, ["value_type": <value_type>], ["to_json": <true/false>], ["to_c": <true/false>]}
+    # value_type: one of "array", "array.int", "int", "hex", "list", "mapping"
+    # to_json: Default `true`. Set to `false` to exclude this mapping from info.json
+    # to_c: Default `true`. Set to `false` to exclude this mapping from config.h
+    # warn_duplicate: Default `true`. Set to `false` to turn off warning when a value exists in both places
+    "DEBOUNCE": {"info_key": "debounce", "value_type": "int"}
+    "DEVICE_VER": {"info_key": "usb.device_ver", "value_type": "hex"},
+    "DESCRIPTION": {"info_key": "keyboard_folder", "to_json": false},
+    "DIODE_DIRECTION": {"info_key": "diode_direction"},
+    "LAYOUTS": {"info_key": "layout_aliases", "value_type": "mapping"},
+    "LED_CAPS_LOCK_PIN": {"info_key": "indicators.caps_lock"},
+    "LED_NUM_LOCK_PIN": {"info_key": "indicators.num_lock"},
+    "LED_SCROLL_LOCK_PIN": {"info_key": "indicators.scroll_lock"},
+    "MANUFACTURER": {"info_key": "manufacturer"},
+    "RGB_DI_PIN": {"info_key": "rgblight.pin"},
+    "RGBLED_NUM": {"info_key": "rgblight.led_count", "value_type": "int"},
+    "RGBLED_SPLIT": {"info_key": "rgblight.split_count", "value_type": "array.int"},
+    "RGBLIGHT_ANIMATIONS": {"info_key": "rgblight.animations.all", "value_type": "bool"},
+    "RGBLIGHT_EFFECT_ALTERNATING": {"info_key": "rgblight.animations.alternating", "value_type": "bool"},
+    "RGBLIGHT_EFFECT_BREATHING": {"info_key": "rgblight.animations.breathing", "value_type": "bool"},
+    "RGBLIGHT_EFFECT_CHRISTMAS": {"info_key": "rgblight.animations.christmas", "value_type": "bool"},
+    "RGBLIGHT_EFFECT_KNIGHT": {"info_key": "rgblight.animations.knight", "value_type": "bool"},
+    "RGBLIGHT_EFFECT_RAINBOW_MOOD": {"info_key": "rgblight.animations.rainbow_mood", "value_type": "bool"},
+    "RGBLIGHT_EFFECT_RAINBOW_SWIRL": {"info_key": "rgblight.animations.rainbow_swirl", "value_type": "bool"},
+    "RGBLIGHT_EFFECT_RGB_TEST": {"info_key": "rgblight.animations.rgb_test", "value_type": "bool"},
+    "RGBLIGHT_EFFECT_SNAKE": {"info_key": "rgblight.animations.snake", "value_type": "bool"},
+    "RGBLIGHT_EFFECT_STATIC_GRADIENT": {"info_key": "rgblight.animations.static_gradient", "value_type": "bool"},
+    "RGBLIGHT_EFFECT_TWINKLE": {"info_key": "rgblight.animations.twinkle"},
+    "RGBLIGHT_LIMIT_VAL": {"info_key": "rgblight.max_brightness", "value_type": "int"},
+    "RGBLIGHT_HUE_STEP": {"info_key": "rgblight.hue_steps", "value_type": "int"},
+    "RGBLIGHT_SAT_STEP": {"info_key": "rgblight.saturation_steps", "value_type": "int"},
+    "RGBLIGHT_VAL_STEP": {"info_key": "rgblight.brightness_steps", "value_type": "int"},
+    "RGBLIGHT_SLEEP": {"info_key": "rgblight.sleep", "value_type": "bool"},
+    "RGBLIGHT_SPLIT": {"info_key": "rgblight.split", "value_type": "bool"},
+    "PRODUCT": {"info_key": "keyboard_folder", "to_json": false},
+    "PRODUCT_ID": {"info_key": "usb.pid", "value_type": "hex"},
+    "VENDOR_ID": {"info_key": "usb.vid", "value_type": "hex"},
+    "QMK_ESC_OUTPUT": {"info_key": "qmk_lufa_bootloader.esc_output"},
+    "QMK_ESC_INPUT": {"info_key": "qmk_lufa_bootloader.esc_input"},
+    "QMK_LED": {"info_key": "qmk_lufa_bootloader.led"},
+    "QMK_SPEAKER": {"info_key": "qmk_lufa_bootloader.speaker"}
+}

data/mappings/info_rules.json

@@ -0,0 +1,15 @@
+# This file maps keys between `rules.mk` and `info.json`. It is used by QMK 
+# to correctly and consistently map back and forth between the two systems.
+{
+    # Format:
+    # <rules.mk key>: {"info_key": <info.json key>, ["value_type": <value_type>], ["to_json": <true/false>], ["to_c": <true/false>]}
+    # value_type: one of "array", "array.int", "int", "list", "hex", "mapping"
+    # to_json: Default `true`. Set to `false` to exclude this mapping from info.json
+    # to_c: Default `true`. Set to `false` to exclude this mapping from rules.mk
+    # warn_duplicate: Default `true`. Set to `false` to turn off warning when a value exists in both places
+    "BOARD": {"info_key": "board"},
+    "BOOTLOADER": {"info_key": "bootloader", "warn_duplicate": false},
+    "LAYOUTS": {"info_key": "community_layouts", "value_type": "list"},
+    "LED_MATRIX_DRIVER": {"info_key": "led_matrix.driver"},
+    "MCU": {"info_key": "processor", "warn_duplicate": false},
+}

data/mappings/keyboard_aliases.json

@@ -0,0 +1,443 @@
+{
+    # Format for each entry:
+    # <alias>: {
+    #     target: <keyboard_folder>,
+    #     layouts: {
+    #         <layout_alias>: <layout_target>
+    #     }
+    # }
+    #
+    # Both target and layouts are optional.
+    '2_milk': {
+          target: 'spaceman/2_milk'
+    },
+    'aeboards/ext65': {
+          target: 'aeboards/ext65/rev1'
+    },
+    'ai03/equinox': {
+          target: 'ai03/equinox/rev1'
+    },
+    aleth42: {
+          target: 'aleth42/rev1'
+    },
+    alice: {
+          target: 'tgr/alice'
+    },
+    angel17: {
+          target: 'angel17/alpha'
+    },
+    angel64: {
+          target: 'angel64/alpha'
+    },
+    at101_blackheart: {
+          target: 'at101_bh'
+    },
+    'atom47/rev2': {
+          target: 'maartenwut/atom47/rev2'
+    },
+    'atom47/rev3': {
+          target: 'maartenwut/atom47/rev3'
+    },
+    bear_face: {
+          target: 'bear_face/v1'
+    },
+    'bpiphany/pegasushoof': {
+          target: 'bpiphany/pegasushoof/2013'
+    },
+    chavdai40: {
+          target: 'chavdai40/rev1'
+    },
+    'candybar/lefty': {
+          target: 'tkc/candybar/lefty'
+    },
+    'candybar/righty': {
+          target: 'tkc/candybar/righty'
+    },
+    canoe: {
+          target: 'percent/canoe'
+    },
+    'cmm_studio/saka68': {
+          target: 'cmm_studio/saka68/solder'
+    },
+    'crkbd/rev1': {
+          target: 'crkbd/rev1/legacy'
+    },
+    'doro67/multi': {
+          layouts: {
+                  LAYOUT_ansi: 'LAYOUT_65_ansi_blocker'
+          }
+    },
+    'doro67/regular': {
+          layouts: {
+                  LAYOUT: 'LAYOUT_65_ansi_blocker'
+          }
+    },
+    'doro67/rgb': {
+          layouts: {
+                  LAYOUT: 'LAYOUT_65_ansi_blocker'
+          }
+    },
+    drakon: {
+          target: 'jagdpietr/drakon'
+    },
+    'dztech/dz60rgb': {
+          target: 'dztech/dz60rgb/v1'
+    },
+    'dztech/dz60rgb_ansi': {
+          target: 'dztech/dz60rgb_ansi/v1'
+    },
+    'dztech/dz60rgb_wkl': {
+          target: 'dztech/dz60rgb_wkl/v1'
+    },
+    'dztech/dz65rgb': {
+          target: 'dztech/dz65rgb/v1'
+    },
+    eek: {
+          target: 'eek/silk_down'
+    },
+    ergoinu: {
+          target: 'dm9records/ergoinu'
+    },
+    'exclusive/e85': {
+          target: 'exclusive/e85/hotswap'
+    },
+    gh60: {
+          target: 'gh60/revc'
+    },
+    'handwired/ferris': {
+          target: 'ferris/0_1'
+    },
+    'helix/pico/sc/back': {
+          target: 'helix/pico/sc'
+    },
+    'helix/pico/sc/under': {
+          target: 'helix/pico/sc'
+    },
+    'helix/rev2/back/oled': {
+          target: 'helix/rev2/back'
+    },
+    'helix/rev2/oled': {
+          target: 'helix/rev2'
+    },
+    'helix/rev2/oled/back': {
+          target: 'helix/rev2/back'
+    },
+    'helix/rev2/oled/under': {
+          target: 'helix/rev2/under'
+    },
+    'helix/rev2/sc/back': {
+          target: 'helix/rev2/sc'
+    },
+    'helix/rev2/sc/oled': {
+          target: 'helix/rev2/sc'
+    },
+    'helix/rev2/sc/oledback': {
+          target: 'helix/rev2/sc'
+    },
+    'helix/rev2/sc/oledunder': {
+          target: 'helix/rev2/sc'
+    },
+    'helix/rev2/sc/under': {
+          target: 'helix/rev2/sc'
+    },
+    'helix/rev2/under': {
+          target: 'helix/rev2/sc'
+    },
+    'helix/rev2/under/oled': {
+          target: 'helix/rev2/under'
+    },
+    id80: {
+          target: 'id80/ansi'
+    },
+    idb_60: {
+          target: 'idb/idb_60',
+          layouts: {
+                  LAYOUT: 'LAYOUT_all'
+          }
+    },
+    jones: {
+          target: 'jones/v03_1'
+    },
+    katana60: {
+          target: 'rominronin/katana60/rev1'
+    },
+    'kbdfans/kbd67mkiirgb': {
+          target: 'kbdfans/kbd67/mkiirgb',
+          layouts: {
+                  LAYOUT: 'LAYOUT_65_ansi_blocker'
+          }
+    },
+    'kbdfans/kbd67/mkiirgb': {
+          target: 'kbdfans/kbd67/mkiirgb/v1'
+    },
+    'keebio/dsp40': {
+          target: 'keebio/dsp40/rev1'
+    },
+    'keycapsss/plaid_pad': {
+          target: 'keycapsss/plaid_pad/rev1'
+    },
+    kudox: {
+          target: 'kudox/rev1'
+    },
+    'lfkeyboards/lfk78': {
+          target: 'lfkeyboards/lfk78/revj'
+    },
+    'lfkeyboards/smk65': {
+          target: 'lfkeyboards/smk65/revb'
+    },
+    'maartenwut/atom47/rev2': {
+          target: 'evyd13/atom47/rev2'
+    },
+    'maartenwut/atom47/rev3': {
+          target: 'evyd13/atom47/rev3'
+    },
+    'maartenwut/eon40': {
+          target: 'evyd13/eon40'
+    },
+    'maartenwut/eon65': {
+          target: 'evyd13/eon65'
+    },
+    'maartenwut/eon75': {
+          target: 'evyd13/eon75'
+    },
+    'maartenwut/eon87': {
+          target: 'evyd13/eon87'
+    },
+    'maartenwut/eon95': {
+          target: 'evyd13/eon95'
+    },
+    'maartenwut/gh80_1800': {
+          target: 'evyd13/gh80_1800'
+    },
+    'maartenwut/gh80_3700': {
+          target: 'evyd13/gh80_3700'
+    },
+    'maartenwut/minitomic': {
+          target: 'evyd13/minitomic'
+    },
+    'maartenwut/mx5160': {
+          target: 'evyd13/mx5160'
+    },
+    'maartenwut/nt660': {
+          target: 'evyd13/nt660'
+    },
+    'maartenwut/omrontkl': {
+          target: 'evyd13/omrontkl'
+    },
+    'maartenwut/plain60': {
+          target: 'evyd13/plain60'
+    },
+    'maartenwut/pockettype': {
+          target: 'evyd13/pockettype'
+    },
+    'maartenwut/quackfire': {
+          target: 'evyd13/quackfire'
+    },
+    'maartenwut/solheim68': {
+          target: 'evyd13/solheim68'
+    },
+    'maartenwut/ta65': {
+          target: 'evyd13/ta65'
+    },
+    'maartenwut/wasdat': {
+          target: 'evyd13/wasdat'
+    },
+    'maartenwut/wasdat_code': {
+          target: 'evyd13/wasdat_code'
+    },
+    'maartenwut/wonderland': {
+          target: 'evyd13/wonderland'
+    },
+    'mechlovin/hannah910': {
+          target: 'mechlovin/hannah910/rev1'
+    },
+    'mechlovin/adelais/rgb_led': {
+          target: 'mechlovin/adelais/rgb_led/rev1'
+    },
+    'mechlovin/adelais/standard_led': {
+          target: 'mechlovin/adelais/standard_led/rev2'
+    },
+    'mechlovin/delphine': {
+          target: 'mechlovin/delphine/mono_led'
+    },
+    'mechlovin/hannah60rgb': {
+          target: 'mechlovin/hannah60rgb/rev1'
+    },
+    'melgeek/z70ultra': {
+          target: 'melgeek/z70ultra/rev1'
+    },
+    'mechlovin/hannah65': {
+          target: 'mechlovin/hannah65/rev1'
+    },
+    model01: {
+          target: 'keyboardio/model01'
+    },
+    m0lly: {
+          target: 'tkc/m0lly'
+    },
+    'montsinger/rebound': {
+          target: 'montsinger/rebound/rev1'
+    },
+    nomu30: {
+          target: 'nomu30/rev1'
+    },
+    'noxary/268_2': {
+          layouts: {
+                  LAYOUT: 'LAYOUT_65_ansi_blocker'
+          }
+    },
+    oddball: {
+          target: 'oddball/v1'
+    },
+    omnikey_blackheart: {
+          target: 'omnikey_bh'
+    },
+    'pabile/p20': {
+          target: 'pabile/p20/ver1'
+    },
+    'pancake/feather': {
+          target: 'spaceman/pancake/feather'
+    },
+    'pancake/promicro': {
+          target: 'spaceman/pancake/promicro'
+    },
+    'percent/canoe': {
+          layouts: {
+                  LAYOUT_iso: 'LAYOUT_65_iso_blocker'
+          }
+    },
+    plaid: {
+          target: 'dm9records/plaid'
+    },
+    plain60: {
+          target: 'maartenwut/plain60'
+    },
+    'ploopyco/trackball': {
+          target: 'ploopyco/trackball/rev1_005'
+    },
+    polilla: {
+          target: 'polilla/rev1'
+    },
+    'preonic/rev1': {
+          layouts: {
+                  LAYOUT_preonic_grid: 'LAYOUT_ortho_5x12'
+          }
+    },
+    'preonic/rev2': {
+          layouts: {
+                  LAYOUT_preonic_grid: 'LAYOUT_ortho_5x12'
+          }
+    },
+    'preonic/rev3': {
+          layouts: {
+                  LAYOUT_preonic_grid: 'LAYOUT_ortho_5x12'
+          }
+    },
+    'primekb/prime_l': {
+          target: 'primekb/prime_l/v1'
+    },
+    'primekb/prime_l_v2': {
+          target: 'primekb/prime_l/v2'
+    },
+    'projectkb/alice': {
+          target: 'projectkb/alice/rev1'
+    },
+    'rama/koyu': {
+          target: 'wilba_tech/rama_works_koyu'
+    },
+    'rama/m6_a': {
+          target: 'wilba_tech/rama_works_m6_a'
+    },
+    'rama/m6_b': {
+          target: 'wilba_tech/rama_works_m6_b'
+    },
+    'rama/m10_b': {
+          target: 'wilba_tech/rama_works_m10_b'
+    },
+    'rama/m60_a': {
+          target: 'wilba_tech/rama_works_m60_a'
+    },
+    'rama/u80_a': {
+          target: 'wilba_tech/rama_works_u80_a'
+    },
+    'ramonimbao/herringbone': {
+          target: 'ramonimbao/herringbone/v1'
+    },
+    'rgbkb/pan': {
+          target: 'rgbkb/pan/rev1/32a'
+    },
+    'rgbkb/pan/rev1': {
+          target: 'rgbkb/pan/rev1/32a'
+    },
+    romac: {
+          target: 'kingly_keys/romac'
+    },
+    ropro: {
+          target: 'kingly_keys/ropro'
+    },
+    satan: {
+          target: 'gh60/satan'
+    },
+    skog: {
+          target: 'percent/skog'
+    },
+    speedo: {
+          target: 'cozykeys/speedo/v2'
+    },
+    stoutgat: {
+          target: 'tkw/stoutgat/v1'
+    },
+    suihankey: {
+          target: 'suihankey/split/alpha'
+    },
+    ta65: {
+          target: 'maartenwut/ta65'
+    },
+    tartan: {
+          target: 'dm9records/tartan'
+    },
+    tkc1800: {
+          target: 'tkc/tkc1800'
+    },
+    'tkw/stoutgat/v2': {
+          target: 'tkw/stoutgat/v2/f411'
+    },
+    underscore33: {
+          target: 'underscore33/rev1'
+    },
+    vinta: {
+          layouts: {
+                  LAYOUT_67_ansi: 'LAYOUT_65_ansi_blocker'
+          }
+    },
+    wasdat: {
+          target: 'maartenwut/wasdat'
+    },
+    'westfoxtrot/cypher': {
+          target: 'westfoxtrot/cypher/rev1'
+    },
+    'whale/sk': {
+          target: 'whale/sk/v3'
+    },
+    'xelus/dawn60': {
+          target: 'xelus/dawn60/rev1'
+    },
+    'xelus/valor': {
+          target: 'xelus/valor/rev1'
+    },
+    yd60mq: {
+          target: 'yd60mq/12led'
+    },
+    ymd75: {
+          target: 'ymd75/rev1'
+    },
+    z150_blackheart: {
+          target: 'z150_bh'
+    },
+    zeal60: {
+          target: 'wilba_tech/zeal60'
+    },
+    zeal65: {
+          target: 'wilba_tech/zeal65'
+    }
+}

data/schemas/api_keyboard.jsonschema

@@ -0,0 +1,35 @@
+{
+    "allOf": [
+        { "$ref": "qmk.keyboard.v1" },
+        {
+            "$id": "qmk.api.keyboard.v1",
+            "keymaps": {
+                "type": "string"
+            },
+            "parse_errors": {
+                "type": "array",
+                "items": {
+                    "type": "string"
+                }
+            },
+            "parse_warnings": {
+                "type": "array",
+                "items": {
+                    "type": "string"
+                }
+            },
+            "processor_type": {
+                "type": "string"
+            },
+            "protocol": {
+                "type": "string"
+            },
+            "keyboard_folder": {
+                "type": "string"
+            },
+            "platform": {
+                "type": "string"
+            }
+        }
+    ]
+}

data/schemas/false.jsonschema

@@ -0,0 +1 @@
+false

data/schemas/keyboard.jsonschema

@@ -0,0 +1,326 @@
+{
+    "$schema": "http://json-schema.org/schema#",
+    "$id": "qmk.keyboard.v1",
+    "title": "Keyboard Information",
+    "type": "object",
+    "properties": {
+        "keyboard_name": {
+            "type": "string",
+            "minLength": 2,
+            "maxLength": 250
+        },
+        "maintainer": {
+            "type": "string",
+            "minLength": 2,
+            "maxLength": 250
+        },
+        "manufacturer": {
+            "type": "string",
+            "minLength": 2,
+            "maxLength": 250
+        },
+        "url": {
+            "type": "string",
+            "format": "uri"
+        },
+        "processor": {
+            "type": "string",
+            "enum": ["cortex-m0", "cortex-m0plus", "cortex-m3", "cortex-m4", "MKL26Z64", "MK20DX128", "MK20DX256", "MK66F18", "STM32F042", "STM32F072", "STM32F103", "STM32F303", "STM32F401", "STM32F411", "STM32F446", "STM32G431", "STM32G474", "STM32L433", "STM32L443", "atmega16u2", "atmega32u2", "atmega16u4", "atmega32u4", "at90usb162", "at90usb646", "at90usb647", "at90usb1286", "at90usb1287", "atmega32a", "atmega328p", "atmega328", "attiny85", "unknown"]
+        },
+        "board": {
+            "type": "string",
+            "minLength": 2,
+            "pattern": "^[a-zA-Z_][0-9a-zA-Z_]*$"
+        },
+        "bootloader": {
+            "type": "string",
+            "enum": ["atmel-dfu", "bootloadHID", "caterina", "halfkay", "kiibohd", "lufa-dfu", "lufa-ms", "micronucleus", "qmk-dfu", "stm32-dfu", "stm32duino", "unknown", "USBasp", "tinyuf2"]
+        },
+        "diode_direction": {
+            "type": "string",
+            "enum": ["COL2ROW", "ROW2COL"]
+        },
+        "debounce": {
+            "type": "number",
+            "min": 0,
+            "multipleOf": 1
+        },
+        "height": {
+            "type": "number",
+            "min": 0.25
+        },
+        "width": {
+            "type": "number",
+            "min": 0.25
+        },
+        "community_layouts": {
+            "type": "array",
+            "items": {
+                "type": "string",
+                "minLength": 2,
+                "pattern": "^[0-9a-z_]*$"
+            }
+        },
+        "features": {
+            "type": "object",
+            "additionalProperties": {"type": "boolean"}
+        },
+        "indicators": {
+            "type": "object",
+            "properties": {
+                "caps_lock": {
+                    "type": "string",
+                    "pattern": "^[A-K]\\d{1,2}$"
+                },
+                "num_lock": {
+                    "type": "string",
+                    "pattern": "^[A-K]\\d{1,2}$"
+                },
+                "scroll_lock": {
+                    "type": "string",
+                    "pattern": "^[A-K]\\d{1,2}$"
+                }
+            }
+        },
+        "layout_aliases": {
+            "type": "object",
+            "additionalProperties": {
+                "oneOf": [
+                    {
+                        "type": "string",
+                        "enum": ["LAYOUT", "LAYOUT_planck_1x2uC"]
+                    },
+                    {
+                        "type": "string",
+                        "pattern": "^LAYOUT_[0-9a-z_]*$"
+                    }
+                ]
+            }
+        },
+        "layouts": {
+            "type": "object",
+            "additionalProperties": {
+                "type": "object",
+                "additionalProperties": false,
+                "properties": {
+                    "filename": {
+                        "type": "string"
+                    },
+                    "c_macro": {
+                        "type": "boolean"
+                    },
+                    "key_count": {
+                        "type": "number",
+                        "min": 0,
+                        "multipleOf": 1
+                    },
+                    "layout": {
+                        "type": "array",
+                        "items": {
+                            "type": "object",
+                            "additionalProperties": false,
+                            "properties": {
+                                "label": {"type": "string"},
+                                "matrix": {
+                                    "type": "array",
+                                    "minItems": 2,
+                                    "maxItems": 2,
+                                    "items": {
+                                        "type": "number",
+                                        "min": 0,
+                                        "multipleOf": 1
+                                    }
+                                },
+                                "h": {
+                                    "type": "number",
+                                    "min": 0.25
+                                },
+                                "r": {
+                                    "type": "number",
+                                    "min": 0
+                                },
+                                "rx": {
+                                    "type": "number",
+                                    "min": 0
+                                },
+                                "ry": {
+                                    "type": "number",
+                                    "min": 0
+                                },
+                                "w": {
+                                    "type": "number",
+                                    "min": 0.25
+                                },
+                                "x": {
+                                    "type": "number",
+                                    "min": 0
+                                },
+                                "y": {
+                                    "type": "number",
+                                    "min": 0
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        },
+        "matrix_pins": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+                "direct": {
+                    "type": "array",
+                    "items": {
+                        "type": "array",
+                        "items": {
+                            "oneOf": [
+                                {
+                                    "type": "string",
+                                    "pattern": "^[A-K]\\d{1,2}$"
+                                },
+                                {
+                                    "type": "number",
+                                    "multipleOf": 1
+                                },
+                                {
+                                    "type": "null"
+                                }
+                            ]
+                        }
+                    }
+                },
+                "cols": {
+                    "type": "array",
+                    "items": {
+                        "oneOf": [
+                            {
+                                "type": "string",
+                                "pattern": "^[A-K]\\d{1,2}$"
+                            },
+                            {
+                                "type": "number",
+                                "multipleOf": 1
+                            },
+                            {
+                                "type": "null"
+                            }
+                        ]
+                    }
+                },
+                "rows": {
+                    "type": "array",
+                    "items": {
+                        "oneOf": [
+                            {
+                                "type": "string",
+                                "pattern": "^[A-K]\\d{1,2}$"
+                            },
+                            {
+                                "type": "number",
+                                "multipleOf": 1
+                            },
+                            {
+                                "type": "null"
+                            }
+                        ]
+                    }
+                }
+            }
+        },
+        "rgblight": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+                "animations": {
+                    "type": "object",
+                    "additionalProperties": {
+                        "type": "boolean"
+                    }
+                },
+                "brightness_steps": {
+                    "type": "number",
+                    "min": 0,
+                    "multipleOf": 1
+                },
+                "hue_steps": {
+                    "type": "number",
+                    "min": 0,
+                    "multipleOf": 1
+                },
+                "led_count": {
+                    "type": "number",
+                    "min": 0,
+                    "multipleOf": 1
+                },
+                "max_brightness": {
+                    "type": "number",
+                    "min": 0,
+                    "max": 255,
+                    "multipleOf": 1
+                },
+                "pin": {
+                    "type": "string",
+                    "pattern": "^[A-K]\\d{1,2}$"
+                },
+                "saturation_steps": {
+                    "type": "number",
+                    "min": 0,
+                    "multipleOf": 1
+                },
+                "sleep": {"type": "boolean"},
+                "split": {"type": "boolean"},
+                "split_count": {
+                    "type": "array",
+                    "minLength": 2,
+                    "maxLength": 2,
+                    "items": {
+                        "type": "number",
+                        "min": 0,
+                        "multipleOf": 1
+                    }
+                }
+            }
+        },
+        "usb": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+                "device_ver": {
+                    "type": "string",
+                    "pattern": "^[0-9A-F]x[0-9A-F][0-9A-F][0-9A-F][0-9A-F]"
+                },
+                "pid": {
+                    "type": "string",
+                    "pattern": "^[0-9A-F]x[0-9A-F][0-9A-F][0-9A-F][0-9A-F]"
+                },
+                "vid": {
+                    "type": "string",
+                    "pattern": "^[0-9A-F]x[0-9A-F][0-9A-F][0-9A-F][0-9A-F]"
+                }
+            }
+        },
+        "qmk_lufa_bootloader": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+                "esc_output": {
+                    "type": "string",
+                    "pattern": "^[A-K]\\d{1,2}$"
+                },
+                "esc_input": {
+                    "type": "string",
+                    "pattern": "^[A-K]\\d{1,2}$"
+                },
+                "led": {
+                    "type": "string",
+                    "pattern": "^[A-K]\\d{1,2}$"
+                },
+                "speaker": {
+                    "type": "string",
+                    "pattern": "^[A-K]\\d{1,2}$"
+                }
+            }
+        }
+    }
+}

data/schemas/true.jsonschema

@@ -0,0 +1 @@
+true

disable_features.mk

@@ -0,0 +1,31 @@
+# Unconditionally disable features that a keyboard advertises it doesn't support
+
+FEATURE_NAMES :=
+FEATURE_NAMES += ADAFRUIT_BLE
+FEATURE_NAMES += AUDIO
+FEATURE_NAMES += BACKLIGHT
+FEATURE_NAMES += BLUETOOTH
+FEATURE_NAMES += DIP_SWITCH
+FEATURE_NAMES += DYNAMIC_KEYMAP
+FEATURE_NAMES += ENCODER
+FEATURE_NAMES += HAPTIC
+FEATURE_NAMES += HD44780
+FEATURE_NAMES += IOS_DEVICE
+FEATURE_NAMES += LCD_BACKLIGHT
+FEATURE_NAMES += LCD
+FEATURE_NAMES += OLED
+FEATURE_NAMES += POINTING_DEVICE
+FEATURE_NAMES += PRINTING
+FEATURE_NAMES += PS2_MOUSE
+FEATURE_NAMES += RGBLIGHT
+FEATURE_NAMES += RGB_MATRIX
+FEATURE_NAMES += SLEEP_LED
+FEATURE_NAMES += SERIAL_LINK
+FEATURE_NAMES += STENO
+FEATURE_NAMES += SWAP_HANDS
+FEATURE_NAMES += VISUALIZER
+FEATURE_NAMES += WATCHDOG
+FEATURE_NAMES += XT
+
+$(foreach AFEATURE,$(FEATURE_NAMES),\
+	 $(if $(filter $($(AFEATURE)_SUPPORTED),no),$(eval $(AFEATURE)_ENABLE=no)))

docs/ChangeLog/20190830.md

@@ -50,4 +50,3 @@ This document marks the inaugural Breaking Change merge. A list of changes follo
 * `KC_DELT` was a redundant, undocumented alias for `KC_DELETE`
 * It has been removed and all its uses replaced with the more common `KC_DEL` alias
 * Around 90 keymaps (mostly for ErgoDox boards) have been modified as a result
-

docs/ChangeLog/20200530.md

@@ -0,0 +1,239 @@
+# QMK Breaking Change - 2020 May 30 Changelog
+
+Four times a year QMK runs a process for merging Breaking Changes. A Breaking Change is any change which modifies how QMK behaves in a way that is incompatible or potentially dangerous. We limit these changes to 4 times per year so that users can have confidence that updating their QMK tree will not break their keymaps.
+
+The list of changes follows.
+
+
+## Core Changes
+
+### Converting V-USB usbdrv to a submodule
+
+[#8321](https://github.com/qmk/qmk_firmware/pull/8321) and [qmk_compiler#62](https://github.com/qmk/qmk_compiler/pull/62).
+
+These PRs move the V-USB driver code out of the qmk_firmware repository and into a submodule pointed at https://github.com/obdev/v-usb. This will make it easier to update the codebase if needed, while applying any potential QMK-specific modifications by forking it to the QMK GitHub organization.
+
+### Unify Tap Hold functions and documentation
+
+[#8348](https://github.com/qmk/qmk_firmware/pull/8348)
+
+Updates all of the per key tap-hold functions to pass the `keyrecord_t` structure, and include documentation changes.
+
+Any remaining versions or code outside of the main repo will need to be converted: 
+| Old function                                         | New Function                                                              |
+|------------------------------------------------------|---------------------------------------------------------------------------|
+|`uint16_t get_tapping_term(uint16_t keycode)`         |`uint16_t get_tapping_term(uint16_t keycode, keyrecord_t *record)`         |
+|`bool get_ignore_mod_tap_interrupt(uint16_t keycode)` |`bool get_ignore_mod_tap_interrupt(uint16_t keycode, keyrecord_t *record)` |
+
+### Python Required In The Build Process
+
+[#9000](https://github.com/qmk/qmk_firmware/pull/9000)
+
+This is the last release of QMK that will work without having Python 3.6 (or later) installed. If your environment is not fully setup you will get a warning instructing you to set it up.
+
+After the next breaking change you will not be able to build if `bin/qmk hello` does not work.
+
+### Upgrade from tinyprintf to mpaland/printf
+
+[#8269](https://github.com/qmk/qmk_firmware/pull/8269)
+
+- Provides debug functionality on ChibiOS/ARM that is more compliant than previous integrations.
+- Less maintenence, fewer QMK customisations, and allows QMK to sidestep previous compile and runtime issues.
+- A `make git-submodule` may be required after pulling the latest QMK Firmware code to update to the new dependency.
+
+### Fixed RGB_DISABLE_AFTER_TIMEOUT to be seconds based & small internals cleanup
+
+[#6480](https://github.com/qmk/qmk_firmware/pull/6480)
+
+- Changes `RGB_DISABLE_AFTER_TIMEOUT` to be based on milliseconds instead of ticks.
+- Includes a code cleanup, resulting in a savings of 100 bytes, depending on features used.
+- Fixed issues with timeouts / suspending at the wrong time not turning off all LEDs in some cases.
+
+The `RGB_DISABLE_AFTER_TIMEOUT` definition is now deprecated, and has been superseded by `RGB_DISABLE_TIMEOUT`. To use the new definition, rename `RGB_DISABLE_AFTER_TIMEOUT` to `RGB_DISABLE_TIMEOUT` in your `config.h` file, and multiply the value set by 1200.
+
+Before: `#define RGB_DISABLE_AFTER_TIMEOUT 100`  
+After: `#define RGB_DISABLE_TIMEOUT 120000`
+
+### Switch to qmk forks for everything
+
+[#9019](https://github.com/qmk/qmk_firmware/pull/9019)
+
+Fork all QMK submodules to protect against upstream repositories disappearing.
+
+### code cleanup regarding deprecated macro PLAY_NOTE_ARRAY by replacing it with PLAY_SONG
+
+[#8484](https://github.com/qmk/qmk_firmware/pull/8484)
+
+Removes the deprecated `PLAY_NOTE_ARRAY` macro. References to it are replaced with `PLAY_SONG`, which references the same function.
+
+### fixing wrong configuration of AUDIO feature
+
+[#8903](https://github.com/qmk/qmk_firmware/pull/8903) and [#8974](https://github.com/qmk/qmk_firmware/pull/8974)
+
+`audio_avr.c` does not default to any pin; there has to be a #define XX_AUDIO in config.h at some level for Audio to actually work. Otherwise, the Audio code ends up cluttering the firmware, possibly breaking builds because the maximum allowed firmware size is exceeded.
+
+These changes fix this by disabling Audio on keyboards that have the feature misconfigured, and therefore non-functional.
+
+Also, add a compile-time error to alert the user to a missing pin-configuration (on AVR boards) when `AUDIO_ENABLE = yes` is set.
+
+
+## Keyboard Refactors
+
+### Migrating Lily58 to use split_common
+
+[#6260](https://github.com/qmk/qmk_firmware/pull/6260)
+
+Modifies the default firmware for Lily58 to use the `split_common` library, instead of including and depending on its own set of libraries for the following functionality:
+
+- SSD1306 display
+- i2c for OLED
+- Serial Communication
+
+This allows current lily58 firmware to advance with updates to the `split_common` library, which is shared with many other split keyboards.
+
+#### To migrate existing Lily58 firmware:
+
+[Changes to `config.h`](https://github.com/qmk/qmk_firmware/pull/6260/files#diff-445ac369c8717dcd6fc6fc3630836fc1):
+- Remove `#define SSD1306OLED` from config.h
+
+
+[Changes to `keymap.c`](https://github.com/qmk/qmk_firmware/pull/6260/files#diff-20943ea59856e9bdf3d99ecb2eee40b7):
+- Find/Replace each instance of `#ifdef SSD1306OLED` with `#ifdef OLED_DRIVER_ENABLE`
+- The following changes are for compatibility with the OLED driver. If you don't use the OLED driver you may safely delete [this section](https://github.com/qmk/qmk_firmware/blob/e6b9980bd45c186f7360df68c24b6e05a80c10dc/keyboards/lily58/keymaps/default/keymap.c#L144-L190)
+- Alternatively, if you did not change the OLED code from that in `default`, you may find it easier to simply copy the [relevant section](https://github.com/qmk/qmk_firmware/blob/4ac310668501ae6786c711ecc8f01f62ddaa1c0b/keyboards/lily58/keymaps/default/keymap.c#L138-L172). Otherwise, the changes you need to make are as follows (sample change [here](https://github.com/qmk/qmk_firmware/pull/6260/files#diff-20943ea59856e9bdf3d99ecb2eee40b7R138-R173))
+- [Remove](https://github.com/qmk/qmk_firmware/pull/6260/files#diff-20943ea59856e9bdf3d99ecb2eee40b7L138-L141) the block
+```c
+#ifdef SSD1306OLED	
+  iota_gfx_init(!has_usb());   // turns on the display	
+#endif
+```
+- Within the block bounded by `#ifdef OLED_DRIVER_ENABLE` and `#endif // OLED_DRIVER_ENABLE`, add the following block to ensure that your two OLEDs are rotated correctly across the left and right sides:
+```c
+oled_rotation_t oled_init_user(oled_rotation_t rotation) {
+  if (!is_keyboard_master())
+    return OLED_ROTATION_180;  // flips the display 180 degrees if offhand
+  return rotation;
+}
+```
+- Remove the functions `matrix_scan_user`, `matrix_update` and `iota_gfx_task_user`
+- Find/Replace `matrix_render_user(struct CharacterMatrix *matrix)` with `iota_gfx_task_user(void)`
+- Find/Replace `is_master` with `is_keyboard_master()`
+- For each instance of `matrix_write_ln(matrix, display_fn())`, rewrite it as `oled_write_ln(read_layer_state(), false);`
+- For each instance of `matrix_write(matrix, read_logo());`, replace with `oled_write(read_logo(), false);`
+
+### Refactor zinc to use split_common
+
+[#7114](https://github.com/qmk/qmk_firmware/pull/7114) and [#9171](https://github.com/qmk/qmk_firmware/pull/9171)
+
+* Refactor to use split_common and remove split codes under the zinc/revx/
+* Add - backlight RGB LED and/or underglow RGB LED option
+* Add - continuous RGB animations feature (between L and R halves) 
+* Fix - keymap files to adapt to changes
+    * all authors of keymaps confirmed this PR
+* Update - documents and rules.mk
+
+### Refactor of TKC1800 to use common OLED code
+
+[#8472](https://github.com/qmk/qmk_firmware/pull/8472)
+
+Modifies the default firmware for TKC1800 to use the in-built I2C and OLED drivers, instead of including and depending on its own set of libraries for the following functionality:
+
+- SSD1306 display
+- i2c for OLED
+
+This allows current TKC1800 firmware to advance with updates to those drivers, which are shared with other keyboards.
+
+#### To migrate existing TKC1800 firmware:
+
+[Changes to `config.h`](https://github.com/qmk/qmk_firmware/pull/8472/files#diff-d10b26e676b4a55cbb00d71955116526):
+- Remove `#define SSD1306OLED` from config.h
+
+[Changes to `tkc1800.c`](https://github.com/qmk/qmk_firmware/pull/8472/files#diff-3b35bd30abe89c8110717c6972cd2cc5):
+- Add the following to avoid debug errors on HID_listen if the screen is not present
+```c
+void keyboard_pre_init_kb(void) {
+  setPinInputHigh(D0);
+  setPinInputHigh(D1);
+
+  keyboard_pre_init_user();
+}
+```
+
+[Changes to `keymap.c`](https://github.com/qmk/qmk_firmware/pull/8472/files#diff-05a2a344ce27e4d045fe68520ccd4771):
+- Find/Replace each instance of `#ifdef SSD1306OLED` with `#ifdef OLED_DRIVER_ENABLE`
+- The following changes are for compatibility with the OLED driver. If you don't use the OLED driver you may safely delete [this section](https://github.com/qmk/qmk_firmware/blob/e6b9980bd45c186f7360df68c24b6e05a80c10dc/keyboards/lily58/keymaps/default/keymap.c#L144-L190)
+- [Remove](https://github.com/qmk/qmk_firmware/pull/6260/files#diff-20943ea59856e9bdf3d99ecb2eee40b7L91-L158) the block
+```c
+#ifdef SSD1306OLED	
+  iota_gfx_init(!has_usb());   // turns on the display	
+#endif
+```
+- Within the block bounded by `#ifdef OLED_DRIVER_ENABLE` and `#endif // OLED_DRIVER_ENABLE`, add the following block to ensure that your two OLEDs are rotated correctly across the left and right sides:
+```c
+oled_rotation_t oled_init_user(oled_rotation_t rotation) {
+  if (!is_keyboard_master())
+    return OLED_ROTATION_180;  // flips the display 180 degrees if offhand
+  return rotation;
+}
+```
+- Remove the function `iota_gfx_task_user`
+
+### Split HHKB to ANSI and JP layouts and Add VIA support for each
+
+[#8582](https://github.com/qmk/qmk_firmware/pull/8582)
+
+- Splits the HHKB codebase into two separate folders `keyboards/hhkb/ansi` and `keyboards/hhkb/jp`.
+- Adds VIA Configurator support for both versions.
+
+#### Migrating existing HHKB keymaps
+
+- Remove any checks for the `HHKB_JP` definition
+  - All checks for this definition have been removed, and each version uses the source that is appropriate to that version.
+- Move the directory for your keymap into the appropriate `keymaps` directory
+  - `keyboards/hhkb/ansi/keymaps/` for ANSI HHKBs
+  - `keyboards/hhkb/jp/keymaps/` for HHKB JPs
+- Compile with the new keyboard names
+  - This PR changes the compilation instructions for the HHKB Alternate Controller. To compile firmware for this controller moving forward, use:
+    - `make hhkb/ansi` for ANSI-layout HHKBs
+    - `make hhkb/jp` for HHKB JP keyboards
+
+
+## Keyboard Moves
+
+- [#8412](https://github.com/qmk/qmk_firmware/pull/8412 "Changing board names to prevent confusion") by blindassassin111
+- [#8499](https://github.com/qmk/qmk_firmware/pull/8499 "Move the Keyboardio Model01 to a keyboardio/ subdir") by algernon
+- [#8830](https://github.com/qmk/qmk_firmware/pull/8830 "Move spaceman keyboards") by Spaceman (formerly known as Rionlion100)
+- [#8537](https://github.com/qmk/qmk_firmware/pull/8537 "Organizing my keyboards (plaid, tartan, ergoinu)") by hsgw
+
+Keyboards by Keyboardio, Spaceman, and hsgw move to vendor folders, while PCBs designed by blindassassin111 are renamed.
+
+Old Name           | New Name
+:----------------- | :-----------------
+2_milk             | spaceman/2_milk
+at101_blackheart   | at101_bh
+ergoinu            | dm9records/ergoinu
+model01            | keyboardio/model01
+omnikey_blackheart | omnikey_bh
+pancake            | spaceman/pancake
+plaid              | dm9records/plaid
+tartan             | dm9records/tartan
+z150_blackheart    | z150_bh
+
+If you own one of these PCBs, please use the new names to compile your firmware moving forward.
+
+
+## Keycode Migration PRs
+
+[#8954](https://github.com/qmk/qmk_firmware/pull/8954 "Migrate `ACTION_LAYER_TOGGLE` to `TG()`"), [#8957](https://github.com/qmk/qmk_firmware/pull/8957 "Migrate `ACTION_MODS_ONESHOT` to `OSM()`"), [#8958](https://github.com/qmk/qmk_firmware/pull/8958 "Migrate `ACTION_DEFAULT_LAYER_SET` to `DF()`"), [#8959](https://github.com/qmk/qmk_firmware/pull/8959 "Migrate `ACTION_LAYER_MODS` to `LM()`"), [#8968](https://github.com/qmk/qmk_firmware/pull/8968 "Migrate `ACTION_MODS_TAP_KEY` to `MT()`"), [#8977](https://github.com/qmk/qmk_firmware/pull/8977 "Migrate miscellaneous `fn_actions` entries"), and [#8979](https://github.com/qmk/qmk_firmware/pull/8979 "Migrate `ACTION_MODS_KEY` to chained mod keycodes")
+
+Authored by fauxpark, these pull requests remove references to deprecated TMK macros that have been superseded by native QMK keycodes.
+
+Old `fn_actions` action | New QMK keycode
+:---------------------- | :--------------
+`ACTION_DEFAULT_LAYER_SET(layer)` | `DF(layer)`
+`ACTION_LAYER_MODS(layer, mod)` | `LM(layer, mod)`
+`ACTION_LAYER_ONESHOT(mod)` | `OSL(mod)`
+`ACTION_LAYER_TOGGLE(layer)` | `TG(layer)`
+`ACTION_MODS_ONESHOT(mod)` | `OSM(mod)`
+`ACTION_MODS_TAP_KEY(mod, kc)` | `MT(mod, kc)`
+`ACTION_MODS_KEY(mod, kc)`<br>e.g. `ACTION_MODS_KEY(MOD_LCTL, KC_0)` | `MOD(kc)`<br>e.g. `LCTL(KC_0)`

docs/ChangeLog/20200829.md

@@ -0,0 +1,148 @@
+# QMK Breaking Change - 2020 Aug 29 Changelog
+
+Four times a year QMK runs a process for merging Breaking Changes. A Breaking Change is any change which modifies how QMK behaves in a way that is incompatible or potentially dangerous. We limit these changes to 4 times per year so that users can have confidence that updating their QMK tree will not break their keymaps.
+
+
+## Changes Requiring User Action :id=changes-requiring-user-action
+
+### Relocated Keyboards :id=relocated-keyboards
+
+#### The Key Company project consolidation ([#9547](https://github.com/qmk/qmk_firmware/pull/9547))
+#### relocating boards by flehrad to flehrad/ folder ([#9635](https://github.com/qmk/qmk_firmware/pull/9635))
+
+Keyboards released by The Key Company and keyboards designed by flehrad have moved to vendor folders. If you own any of the keyboards listed below, please use the new names to compile your firmware moving forward.
+
+Old Name               | New Name
+:--------------------- | :------------------
+candybar/lefty         | tkc/candybar/lefty
+candybar/righty        | tkc/candybar/righty
+m0lly                  | tkc/m0lly
+tkc1800                | tkc/tkc1800
+bigswitch              | flehrad/bigswitch
+handwired/downbubble   | flehrad/downbubble
+handwired/numbrero     | flehrad/numbrero
+snagpad                | flehrad/snagpad
+handwired/tradestation | flehrad/tradestation
+
+### Updated Keyboard Codebases :id=keyboard-updates
+
+#### Keebio RGB wiring update ([#7754](https://github.com/qmk/qmk_firmware/pull/7754))
+
+This pull request changes the configuration for Keebio split boards to use the same RGB strip wiring for each half, which provides the following improvements:
+
+* Easier wiring due to one fewer wire needed (the wire between left DOut to extra data pin) and the fact that wiring is the same for both halves.
+* RGB LEDs can be controlled by each half now instead of just master half.
+* Extra data line is freed up to allow for I2C usage instead of serial.
+
+If you have customized the value of `RGBLED_SPLIT` for your keymap, you will need to undefine it using `#undef RGBLED_SPLIT` before defining it to your customized value.
+
+This change affects:
+
+* BFO-9000
+* Fourier
+* Iris rev2
+* Levinson, revs. 1 and 2
+* Nyquist, revs. 1 and 2
+* Quefrency rev1
+* Viterbi, revs. 1 and 2
+
+### Changes to Core Functionality :id=core-updates
+
+* Bigger Combo index ([#9318](https://github.com/qmk/qmk_firmware/pull/9318))
+
+Allows the Combo feature to support more than 256 combos.
+
+Any fork that uses `process_combo_event` needs to update the function's first argument to `uint16_t`:
+
+* Old function: `void process_combo_event(uint8_t combo_index, bool pressed)`
+* New function: `void process_combo_event(uint16_t combo_index, bool pressed)`
+
+
+## Core Changes :id=core-changes
+
+### Fixes :id=core-fixes
+
+* Mousekeys: scrolling acceleration is no longer coupled to mouse movement acceleration ([#9174](https://github.com/qmk/qmk_firmware/pull/9174))
+* Keymap Extras: correctly assign Question Mark in Czech layout ([#9987](https://github.com/qmk/qmk_firmware/pull/9987))
+
+### Additions and Enhancements :id=core-additions
+
+* allow for WS2812 PWM to work on DMAMUX-capable devices ([#9471](https://github.com/qmk/qmk_firmware/pull/9471))
+  * Newer STM32 MCUs have a DMAMUX peripheral, which allows mapping of DMAs to different DMA streams, rather than hard-defining the target streams in silicon.
+  * Affects STM32L4+ devices, as well as the soon-to-be-supported-by-QMK STM32G4/H7 families.
+  * Tested on F303/Proton C (ChibiOS v19, non-DMAMUX), G474 (ChibiOS v20, with DMAMUX).
+* dual-bank STM32 bootloader support ([#8778](https://github.com/qmk/qmk_firmware/pull/8778) and [#9738](https://github.com/qmk/qmk_firmware/pull/9738))
+  * Adds support for STM32 dual-bank flash bootloaders, by toggling a GPIO during early init in order to charge an RC circuit attached to `BOOT0`.
+  * The main rationale behind this is that dual-bank STM32 devices unconditionally execute user-mode code, regardless of whether or not the user-mode code jumps to the bootloader. If either flash bank is valid (and `BOOT0` is low), then the built-in bootloader will skip any sort of DFU.
+  * This PR allows for the initialisation sequencing to charge the RC circuit based on the example circuit posted on Discord, effectively pulling `BOOT0` high before issuing the system reset. As the RC circuit takes a while to discharge, the system reset executes the ROM bootloader which subsequently sees `BOOT0` high, and starts executing the DFU routines.
+  * Tested with STM32L082 (with current QMK+current ChibiOS), and STM32G474 (against ChibiOS 20.x).
+* update Space Cadet and Tap Dance features to use Custom Tapping Term when appropriate ([#6259](https://github.com/qmk/qmk_firmware/pull/6259))
+  * For the Tap Dance feature, this completely removes the need for the `ACTION_TAP_DANCE_FN_ADVANCED_TIME` dance.
+* HID Joystick Interface ([#4226](https://github.com/qmk/qmk_firmware/pull/4226) and [#9949](https://github.com/qmk/qmk_firmware/pull/9949 "Fix Joystick Compile Issues"))
+  * This implements a joystick feature, including a joystick_task function called from TMK, specific keycodes for joystick buttons and a USB HID interface.
+  * Tested on V-USB backend and Proton C; compiles but untested on LUFA.
+  * In order to test, you have to add `JOYSTICK_ENABLE = yes` to your `rules.mk` and
+    ```c
+    #define JOYSTICK_BUTTON_COUNT 8
+    #define JOYSTICK_AXES_COUNT 2
+    ```
+    in your config.h.
+* Christmas RGB Underglow animation now fades between green and red ([#7648](https://github.com/qmk/qmk_firmware/pull/7648))
+  * `RGBLIGHT_EFFECT_CHRISTMAS_INTERVAL` has been greatly decreased; please check your animation if you have customized this value.
+* layer state now initializes on startup ([#8318](https://github.com/qmk/qmk_firmware/pull/8318))
+  * This should produce more consistent behavior between the two functions and layer masks.
+* added support for HSV->RGB conversion without using CIE curve ([#9856](https://github.com/qmk/qmk_firmware/pull/9856))
+* added NOEEPROM functions for RGB Matrix ([#9487](https://github.com/qmk/qmk_firmware/pull/9487))
+  * Added eeprom_helpers for toggle, mode, sethsv, speed, similar to rgblight versions.
+  * Added set_speed function.
+  * Added helper functions, similar to those in rgblight, in order to add NOEEPROM versions of toggle, step, hue, sat, val, and speed.
+  * Minor: spelling correction for EEPROM in a debug message.
+* flashing firmware using `st-flash` utility from [STLink Tools](https://github.com/stlink-org/stlink) is now supported ([#9964](https://github.com/qmk/qmk_firmware/pull/9964))
+* add ability to dump all makefile variables for the specified target ([#8256](https://github.com/qmk/qmk_firmware/pull/8256))
+  * Adds a new subtarget to builds, `dump_vars`, which allows for printing out all the variables that make knows about, after all substitutions occur.
+  * Example: `make handwired/onekey/proton_c:default:dump_vars`
+* add ability to change the Auto Shift timeout in real time ([#8441](https://github.com/qmk/qmk_firmware/pull/8441))
+* added a timer implementation for backlight on ChibiOS ([#8291](https://github.com/qmk/qmk_firmware/pull/8291))
+* added a third endpoint to V-USB keyboards ([#9020](https://github.com/qmk/qmk_firmware/pull/9020))
+* added a method to read the OLED display buffer from user space ([#8777](https://github.com/qmk/qmk_firmware/pull/8777))
+* K-Type refactor ([#9864](https://github.com/qmk/qmk_firmware/pull/9864))
+  * The K-Type has been refactored to use QMK's native matrix scanning routine, and now has partial support for the RGB Matrix feature.
+* Joysticks can now be used without defining analog pins ([#10169](https://github.com/qmk/qmk_firmware/pull/10169))
+
+### Clean-ups and Optimizations :id=core-optimizations
+
+* iWRAP protocol removed ([#9284](https://github.com/qmk/qmk_firmware/pull/9284))
+* work begun for consolidation of ChibiOS platform files ([#8327](https://github.com/qmk/qmk_firmware/pull/8327) and [#9315](https://github.com/qmk/qmk_firmware/pull/9315))
+  * Start of the consolidation work to move the ChibiOS board definitions as well as the default set of configuration files for existing board definitions used by keyboards.
+    * Uses `/platforms/chibios` as previously discussed on discord.
+    * Consolidates the Proton C configs into the generic F303 definitions.
+    * Allows for defining a default set of `chconf.h`, `halconf.h`, and `mcuconf.h` files within the platform definition, which is able to be overridden by the keyboard directly, though include path ordering.
+    * Adds template `chconf.h`, `halconf.h`, `mcuconf.h`, and `board.h` that can be dropped into a keyboard directory, in order to override rather than replace the entire contents of the respective files.
+    * Removed Proton C QMK board definitions, falling back to ChibiOS board definitions with QMK overrides.
+* Various tidy-ups for USB descriptor code ([#9005](https://github.com/qmk/qmk_firmware/pull/9005))
+  * Renamed `keyboard_led_stats` in lufa.c and ChibiOS usb_main.c to `keyboard_led_state`, as well as `vusb_keyboard_leds`, for consistency
+  * Formatted CDC and MIDI descriptors better
+  * Removed `ENDPOINT_CONFIG` macro, it seems pointless and removes the need for endpoint address defines in the middle of the endpoint numbering enum
+  * Fixed (possibly?) V-USB `GET_REPORT` request handling. Not sure about this one, but the existing code appears to always return an empty report - now `send_keyboard` sets this variable to the current report, matching what the LUFA code does.
+* converted `CONSUMER2BLUEFRUIT()` and `CONSUMER2RN42()` macros to static inline functions ([#9055](https://github.com/qmk/qmk_firmware/pull/9055))
+* Additional cleanups for V-USB code ([#9310](https://github.com/qmk/qmk_firmware/pull/9310))
+  * Removing the UART stuff entirely, now that we have Console support. Also fixing up various other things; switching some `debug()` calls to `dprintf()`, moved `raw_hid_report` out of the way so that we can implement the shared endpoint stuff.
+* removed inclusion of `adafruit_ble.h` from `ssd1306.c` ([#9355](https://github.com/qmk/qmk_firmware/pull/9355))
+* `outputselect.c` is no longer compiled if Bluetooth is disabled ([#9356](https://github.com/qmk/qmk_firmware/pull/9356))
+* `analogRead()` deprecated in favor of `analogReadPin()` ([#9023](https://github.com/qmk/qmk_firmware/pull/9023))
+* forcibly disable NKRO on V-USB controllers ([#9054](https://github.com/qmk/qmk_firmware/pull/9054))
+* removed warning if running backlight on STM32F072 ([#10040](https://github.com/qmk/qmk_firmware/pull/10040))
+* removed unused CORTEX_VTOR_INIT rules.mk option ([#10053](https://github.com/qmk/qmk_firmware/pull/10053))
+* improved handling for enabling Link Time Optimization ([#9832](https://github.com/qmk/qmk_firmware/pull/9832))
+* streamline rules for supporting Kiibohd bootloader ([#10129](https://github.com/qmk/qmk_firmware/pull/10129))
+* Define `STM32_DMA_REQUIRED` when using DMA-based WS2812 driver on STM32 ([#10127](https://github.com/qmk/qmk_firmware/pull/10127))
+* fix DMA stream ID calculation in ws2812_pwm ([#10008](https://github.com/qmk/qmk_firmware/pull/10008))
+* remove support for Adafruit EZ Key Bluetooth controller ([#10103](https://github.com/qmk/qmk_firmware/pull/10103))
+
+
+## QMK Infrastructure and Internals :id=qmk-internals
+
+* Attempt to fix CI for non-master branches. ([#9308](https://github.com/qmk/qmk_firmware/pull/9308))
+  * Actually fetch the branch we're attempting to compare against.
+* Run `qmk cformat` on `develop` branch ([#9501](https://github.com/qmk/qmk_firmware/pull/9501))
+* minor refactor of Bluetooth API ([#9905](https://github.com/qmk/qmk_firmware/pull/9905))

docs/ChangeLog/20201128.md

@@ -0,0 +1,150 @@
+# QMK Breaking Change - 2020 Nov 28 Changelog
+
+Four times a year QMK runs a process for merging Breaking Changes. A Breaking Change is any change which modifies how QMK behaves in a way that is incompatible or potentially dangerous. We limit these changes to 4 times per year so that users can have confidence that updating their QMK tree will not break their keymaps.
+
+
+## Changes Requiring User Action :id=changes-requiring-user-action
+
+### Relocated Keyboards :id=relocated-keyboards
+
+#### Reduce Helix keyboard build variation ([#8669](https://github.com/qmk/qmk_firmware/pull/8669))
+
+The build commands for the Helix keyboard are:
+
+```
+make <helix_build_name>:<keymap_name>
+```
+
+For `<helix_build_name>`, specify the one in the rightmost column of the table below, such as `helix`,` helix/pico`.
+
+| before Oct 17 2019   |  Oct 17 2019            | Mar 10 2020             | Nov 28 2020             |
+| ---------------------|-------------------------|-------------------------| ------------------------|
+| helix/rev1           | helix/rev1              | helix/rev1              | helix/rev1              |
+| helix/pico           | helix/pico              | helix/pico              | helix/pico              |
+|                      | helix/pico/back         | helix/pico/back         | helix/pico/back         |
+|                      | helix/pico/under        | helix/pico/under        | helix/pico/under        |
+|                      |                         | helix/pico/sc           | --                      |
+|                      |                         | helix/pico/sc/back      | helix/pico/sc           |
+|                      |                         | helix/pico/sc/under     | --                      |
+| helix/rev2 (=helix)  | helix/rev2 (=helix)     | helix/rev2 (=helix)     | --                      |
+|                      | helix/rev2/back         | helix/rev2/back         | --                      |
+|                      | helix/rev2/back/oled    | helix/rev2/back/oled    | ( --> helix/rev2/back)  |
+|                      | helix/rev2/oled         | helix/rev2/oled         | helix/rev2　(=helix)     |
+|                      | helix/rev2/oled/back    | helix/rev2/oled/back    | helix/rev2/back         |
+|                      | helix/rev2/oled/under   | helix/rev2/oled/under   | helix/rev2/under        |
+|                      |                         | helix/rev2/sc           | --                      |
+|                      |                         | helix/rev2/sc/back      | --                      |
+|                      |                         | helix/rev2/sc/oled      | --                      |
+|                      |                         | helix/rev2/sc/oledback  | helix/rev2/sc           |
+|                      |                         | helix/rev2/sc/oledunder | --                      |
+|                      |                         | helix/rev2/sc/under     | --                      |
+|                      | helix/rev2/under        | helix/rev2/under        | --                      |
+|                      | helix/rev2/under/oled   | helix/rev2/under/oled   | ( --> helix/rev2/under) |
+
+#### Update the Speedo firmware for v3.0 ([#10657](https://github.com/qmk/qmk_firmware/pull/10657))
+
+The Speedo keyboard has moved to `cozykeys/speedo/v2` as the designer prepares to release the Speedo v3.0.
+
+| Previous Name | New Name                   |
+| :------------ | :------------------------- |
+| speedo        | cozykeys/speedo/v2         |
+| --            | cozykeys/speedo/v3 **new** |
+
+#### Maartenwut/Maarten name change to evyd13/Evy ([#10274](https://github.com/qmk/qmk_firmware/pull/10274))
+
+Maartenwut has rebranded as @evyd13, and all released Maartenwut boards have moved.
+
+| Previous Name          | New Name           |
+| :--------------------- | :----------------- |
+| maartenwut/atom47/rev2 | evyd13/atom47/rev2 |
+| maartenwut/atom47/rev3 | evyd13/atom47/rev3 |
+| maartenwut/eon40       | evyd13/eon40       |
+| maartenwut/eon65       | evyd13/eon65       |
+| maartenwut/eon75       | evyd13/eon75       |
+| maartenwut/eon87       | evyd13/eon87       |
+| maartenwut/eon95       | evyd13/eon95       |
+| maartenwut/gh80_1800   | evyd13/gh80_1800   |
+| maartenwut/gh80_3700   | evyd13/gh80_3700   |
+| maartenwut/minitomic   | evyd13/minitomic   |
+| maartenwut/mx5160      | evyd13/mx5160      |
+| maartenwut/nt660       | evyd13/nt660       |
+| maartenwut/omrontkl    | evyd13/omrontkl    |
+| maartenwut/plain60     | evyd13/plain60     |
+| maartenwut/pockettype  | evyd13/pockettype  |
+| maartenwut/quackfire   | evyd13/quackfire   |
+| maartenwut/solheim68   | evyd13/solheim68   |
+| maartenwut/ta65        | evyd13/ta65        |
+| maartenwut/wasdat      | evyd13/wasdat      |
+| maartenwut/wasdat_code | evyd13/wasdat_code |
+| maartenwut/wonderland  | evyd13/wonderland  |
+
+#### Xelus Valor and Dawn60 Refactors ([#10512](https://github.com/qmk/qmk_firmware/pull/10512), [#10584](https://github.com/qmk/qmk_firmware/pull/10584))
+
+The Valor and Dawn60 keyboards by Xelus22 both now require their revisions to be specified when compiling.
+
+| Previous Name | New Name          |
+| :------------ | :---------------- |
+| xelus/dawn60  | xelus/dawn60/rev1 |
+| xelus/valor   | xelus/valor/rev1  |
+
+
+### Updated Keyboard Codebases :id=keyboard-updates
+
+#### AEboards EXT65 Refactor ([#10820](https://github.com/qmk/qmk_firmware/pull/10820))
+
+The EXT65 codebase has been reworked so keymaps can be used with either revision.
+
+
+## Core Changes :id=core-changes
+
+### Fixes :id=core-fixes
+
+* Reconnect the USB if users wake up a computer from the keyboard to restore the USB state ([#10088](https://github.com/qmk/qmk_firmware/pull/10088))
+* Fix cursor position bug in oled_write_raw functions ([#10800](https://github.com/qmk/qmk_firmware/pull/10800))
+
+### Additions and Enhancements :id=core-additions
+
+* Allow MATRIX_ROWS to be greater than 32 ([#10183](https://github.com/qmk/qmk_firmware/pull/10183))
+* Add support for soft serial to ATmega32U2 ([#10204](https://github.com/qmk/qmk_firmware/pull/10204))
+* Allow direct control of MIDI velocity value ([#9940](https://github.com/qmk/qmk_firmware/pull/9940))
+* Joystick 16-bit support ([#10439](https://github.com/qmk/qmk_firmware/pull/10439))
+* Allow encoder resolutions to be set per encoder ([#10259](https://github.com/qmk/qmk_firmware/pull/10259))
+* Share button state from mousekey to pointing_device ([#10179](https://github.com/qmk/qmk_firmware/pull/10179))
+* Add advanced/efficient RGB Matrix Indicators ([#8564](https://github.com/qmk/qmk_firmware/pull/8564))
+* OLED display update interval support ([#10388](https://github.com/qmk/qmk_firmware/pull/10388))
+* Per-Key Retro Tapping ([#10622](https://github.com/qmk/qmk_firmware/pull/10622))
+* Allow backlight duty cycle limit ([#10260](https://github.com/qmk/qmk_firmware/pull/10260))
+* Add step sequencer feature ([#9703](https://github.com/qmk/qmk_firmware/pull/9703))
+* Added `add_oneshot_mods` & `del_oneshot_mods` ([#10549](https://github.com/qmk/qmk_firmware/pull/10549))
+* Add AT90USB support for serial.c ([#10706](https://github.com/qmk/qmk_firmware/pull/10706))
+* Auto shift: support repeats and early registration (#9826)
+
+### Clean-ups and Optimizations :id=core-optimizations
+
+* Haptic and solenoid cleanup ([#9700](https://github.com/qmk/qmk_firmware/pull/9700))
+* XD75 cleanup ([#10524](https://github.com/qmk/qmk_firmware/pull/10524))
+* Minor change to behavior allowing display updates to continue between task ticks ([#10750](https://github.com/qmk/qmk_firmware/pull/10750))
+* Change some GPIO manipulations in matrix.c to be atomic ([#10491](https://github.com/qmk/qmk_firmware/pull/10491))
+* combine repeated lines of code for ATmega32U2, ATmega16U2, ATmega328 and ATmega328P ([#10837](https://github.com/qmk/qmk_firmware/pull/10837))
+* Remove references to HD44780 ([#10735](https://github.com/qmk/qmk_firmware/pull/10735))
+
+
+## QMK Infrastructure and Internals :id=qmk-internals
+
+* Add ability to build a subset of all keyboards based on platform. ([#10420](https://github.com/qmk/qmk_firmware/pull/10420))
+* Initialise EEPROM drivers at startup, instead of upon first execution ([#10438](https://github.com/qmk/qmk_firmware/pull/10438))
+* Make bootloader_jump weak for ChibiOS ([#10417](https://github.com/qmk/qmk_firmware/pull/10417))
+* Support for STM32 GPIOF,G,H,I,J,K ([#10206](https://github.com/qmk/qmk_firmware/pull/10206))
+* Add milc as a dependency and remove the installed milc ([#10563](https://github.com/qmk/qmk_firmware/pull/10563))
+* ChibiOS upgrade: early init conversions ([#10214](https://github.com/qmk/qmk_firmware/pull/10214))
+* ChibiOS upgrade: configuration file migrator ([#9952](https://github.com/qmk/qmk_firmware/pull/9952))
+* Add definition based on currently-selected serial driver. ([#10716](https://github.com/qmk/qmk_firmware/pull/10716))
+* Allow for modification of output RGB values when using rgblight/rgb_matrix. ([#10638](https://github.com/qmk/qmk_firmware/pull/10638))
+* Allow keyboards/keymaps to execute code at each main loop iteration ([#10530](https://github.com/qmk/qmk_firmware/pull/10530))
+* qmk cformat ([#10767](https://github.com/qmk/qmk_firmware/pull/10767))
+* Add a Make variable to easily enable DEBUG_MATRIX_SCAN_RATE on the command line ([#10824](https://github.com/qmk/qmk_firmware/pull/10824))
+* update Chibios OS USB for the OTG driver ([#8893](https://github.com/qmk/qmk_firmware/pull/8893))
+* Fixup version.h writing when using `SKIP_VERSION=yes` ([#10972](https://github.com/qmk/qmk_firmware/pull/10972), [#10974](https://github.com/qmk/qmk_firmware/pull/10974))
+* Rename ledmatrix.h to match .c file ([#7949](https://github.com/qmk/qmk_firmware/pull/7949))
+* Split RGB_MATRIX_ENABLE into _ENABLE and _DRIVER ([#10231](https://github.com/qmk/qmk_firmware/pull/10231))
+* Split LED_MATRIX_ENABLE into _ENABLE and _DRIVER ([#10840](https://github.com/qmk/qmk_firmware/pull/10840))

docs/ChangeLog/20210227.md

@@ -0,0 +1,169 @@
+# QMK Breaking Changes - 2021 February 27 Changelog
+
+## Changes Requiring User Action
+
+The following keyboards have had their source moved within QMK:
+
+Old Keyboard Name | New Keyboard Name
+:---------------- | :----------------
+bear_65 | jacky_studio/bear_65
+s7_elephant/rev1 | jacky_studio/s7_elephant/rev1
+s7_elephant/rev2 | jacky_studio/s7_elephant/rev2
+aplx6 | aplyard/aplx6/rev1
+southpaw75 | fr4/southpaw75
+
+The [Aplyard Aplx6 rev2](https://github.com/qmk/qmk_firmware/tree/0.12.0/keyboards/aplyard/aplx6/rev1) and the [FR4Boards Unix60](https://github.com/qmk/qmk_firmware/tree/0.12.0/keyboards/fr4/unix60) have also been added as part of these changes.
+
+Additionally, the `handwired/bluepill/bluepill70` keyboard has been removed.
+
+## Core Changes
+
+### ChibiOS Update and Config Migration
+
+QMK's ChibiOS and ChibiOS-Contrib submodules have been updated to version 20.3.2.
+
+Along with this, QMK now provides default configuration files for all commonly-supported ARM microcontrollers running on ChibiOS. As such, keyboards are now only required to define settings which differ from the defaults, thereby reducing the size of pull requests for keyboards running atop ChibiOS.
+
+### QMK Infrastructure and Internals
+
+Python is now required to build QMK. The minimum Python version has been increased to 3.7.
+
+The power of `info.json` has been massively expanded. Most keyboard parameters can now be expressed in `info.json` instead of `config.h`/`rules.mk`. This should make maintaining keyboards easier, and will enable tooling that can allow non-technical users to add and maintain QMK keyboards without writing any code.
+
+To ease migration a new command has been provided, `qmk generate-info-json -kb <keyboard>`. You can use this command to generate a complete `info.json` file for a keyboard and then remove the duplicate information from `config.h` and `rules.mk`. 
+
+Detailed example showing how to generate a new info.json and identify duplicate keys:
+
+```
+user@hostname:~/qmk_firmware/keyboards/lets_split:0$ qmk generate-info-json > new-info.json
+user@hostname:~/qmk_firmware/keyboards/lets_split:0$ mv new-info.json info.json
+user@hostname:~/qmk_firmware/keyboards/lets_split:0$ qmk info
+⚠ lets_split/rev2: DEBOUNCE in config.h is overwriting debounce in info.json
+⚠ lets_split/rev2: DEVICE_VER in config.h is overwriting usb.device_ver in info.json
+⚠ lets_split/rev2: DIODE_DIRECTION in config.h is overwriting diode_direction in info.json
+⚠ lets_split/rev2: MANUFACTURER in config.h is overwriting manufacturer in info.json
+⚠ lets_split/rev2: RGB_DI_PIN in config.h is overwriting rgblight.pin in info.json
+⚠ lets_split/rev2: RGBLED_NUM in config.h is overwriting rgblight.led_count in info.json
+⚠ lets_split/rev2: PRODUCT_ID in config.h is overwriting usb.pid in info.json
+⚠ lets_split/rev2: VENDOR_ID in config.h is overwriting usb.vid in info.json
+⚠ lets_split/rev2: Matrix pins are specified in both info.json and config.h, the config.h values win.
+⚠ lets_split/rev2: LAYOUTS in rules.mk is overwriting community_layouts in info.json
+⚠ lets_split/rev2: Feature bootmagic is specified in both info.json and rules.mk, the rules.mk value wins.
+⚠ lets_split/rev2: Feature mousekey is specified in both info.json and rules.mk, the rules.mk value wins.
+⚠ lets_split/rev2: Feature extrakey is specified in both info.json and rules.mk, the rules.mk value wins.
+⚠ lets_split/rev2: Feature console is specified in both info.json and rules.mk, the rules.mk value wins.
+⚠ lets_split/rev2: Feature command is specified in both info.json and rules.mk, the rules.mk value wins.
+⚠ lets_split/rev2: Feature nkro is specified in both info.json and rules.mk, the rules.mk value wins.
+⚠ lets_split/rev2: Feature backlight is specified in both info.json and rules.mk, the rules.mk value wins.
+⚠ lets_split/rev2: Feature midi is specified in both info.json and rules.mk, the rules.mk value wins.
+⚠ lets_split/rev2: Feature audio is specified in both info.json and rules.mk, the rules.mk value wins.
+⚠ lets_split/rev2: Feature unicode is specified in both info.json and rules.mk, the rules.mk value wins.
+⚠ lets_split/rev2: Feature bluetooth is specified in both info.json and rules.mk, the rules.mk value wins.
+⚠ lets_split/rev2: Feature rgblight is specified in both info.json and rules.mk, the rules.mk value wins.
+⚠ lets_split/rev2: Feature sleep_led is specified in both info.json and rules.mk, the rules.mk value wins.
+Keyboard Name: Let's Split
+Manufacturer: Wootpatoot
+Website:
+Maintainer: QMK Community
+Keyboard Folder: lets_split/rev2
+Layouts: LAYOUT, LAYOUT_ortho_4x12
+Size: 13 x 4
+Processor: atmega32u4
+Bootloader: caterina
+```
+
+## Detailed Change List
+
+### Changes Requiring User Action
+
+* Refactor Jacky's boards (Bear65 and S7 Elephant) ([#10528](https://github.com/qmk/qmk_firmware/pull/10528), [#11981](https://github.com/qmk/qmk_firmware/pull/11981))
+* Remove handwired/bluepill ([#11415](https://github.com/qmk/qmk_firmware/pull/11415))
+* Aplyard Aplx6 Added rev2 & move rev1+rev2 to parent folder ([#10973](https://github.com/qmk/qmk_firmware/pull/10973))
+* added `unix60`, moved together with `southpaw75` into `fr4` folder ([#11195](https://github.com/qmk/qmk_firmware/pull/11195))
+
+### Fixes
+
+* GCC 10 can now compile Drop Alt firmware ([#9485](https://github.com/qmk/qmk_firmware/pull/9485))
+* Fix compiling on `develop` branch ([#11409](https://github.com/qmk/qmk_firmware/pull/11409))
+* Fix broken keyboards and keymaps ([#11412](https://github.com/qmk/qmk_firmware/pull/11412), [#11427](https://github.com/qmk/qmk_firmware/pull/11427), [#11448](https://github.com/qmk/qmk_firmware/pull/11448), [#11447](https://github.com/qmk/qmk_firmware/pull/11447), [#11473](https://github.com/qmk/qmk_firmware/pull/11473), [#11584](https://github.com/qmk/qmk_firmware/pull/11584), [#11600](https://github.com/qmk/qmk_firmware/pull/11600))
+* Fixed up build dependencies so that generated files are made available before compiling any object files ([#11435](https://github.com/qmk/qmk_firmware/pull/11435))
+* Formatting fixes ([`378edd9`](https://github.com/qmk/qmk_firmware/commit/378edd9491f2ab0d3d8a970c9a8e64bc03ca15cf), [#11594](https://github.com/qmk/qmk_firmware/pull/11594), [`27749e1`](https://github.com/qmk/qmk_firmware/commit/27749e1c967c02c05e62a89a0ae2776dd7e5158c))
+* Include `stdbool.h` in `uart.h` to fix compiler errors ([#11728](https://github.com/qmk/qmk_firmware/pull/11728))
+* Decouple USB events from the USB interrupt handler in ChibiOS ([#10437](https://github.com/qmk/qmk_firmware/pull/10437))
+  * Fixes an issue while using Backlight and External EEPROM at the same time that would cause the MCU to lock up.
+* Address wake from sleep instability ([#11450](https://github.com/qmk/qmk_firmware/pull/11450))
+* Fix pressing media key on a momentarily activated layer may lead to missing key up events ([#11162](https://github.com/qmk/qmk_firmware/pull/11162))
+* Fix an RGB initialisation bug on Massdrop keyboards ([#12022](https://github.com/qmk/qmk_firmware/pull/12022))
+* Fix file encoding errors on Windows, and layouts not correctly merging into info.json ([#12039](https://github.com/qmk/qmk_firmware/pull/12039))
+
+### Additions and Enhancements
+
+* Allow configuration of serial USART timeout ([#11057](https://github.com/qmk/qmk_firmware/pull/11057))
+* Added Sync Timer feature for Split Common keyboards ([#10997](https://github.com/qmk/qmk_firmware/pull/10997))
+* Add modifier state to the Split Common transport ([#10400](https://github.com/qmk/qmk_firmware/pull/10400))
+* Add Pix keyboard by sendz (`sendyyeah/pix`) ([#11154](https://github.com/qmk/qmk_firmware/pull/11154))
+* Implement option for kinetic mouse movement algorithm for mouse keys ([#6739](https://github.com/qmk/qmk_firmware/pull/6739))
+* Improved Language Specific Keycodes for US International and Extended Layouts ([#11307](https://github.com/qmk/qmk_firmware/pull/11307))
+* Modified `QWIIC_ENABLE` in `rules.mk` to be yes/no choice, adding `QWIIC_DRIVERS` to allow for inclusion of specific drivers ([#11426](https://github.com/qmk/qmk_firmware/pull/11426))
+* Allow AVR-based keyboards to override the `bootloader_jump` function ([#11418](https://github.com/qmk/qmk_firmware/pull/11418))
+* Refine RGBLight Twinkle effect to be smoother (use breathing curve) ([#11350](https://github.com/qmk/qmk_firmware/pull/11350))
+* Keep track of last matrix activity ([#10730](https://github.com/qmk/qmk_firmware/pull/10730), [`ab375d3`](https://github.com/qmk/qmk_firmware/commit/ab375d3d075c105f09a1ddd0e155f178225518bc), [#11552](https://github.com/qmk/qmk_firmware/pull/11552))
+* fix `matrix_io_delay()` timing in `quantum/matrix.c` ([#9603](https://github.com/qmk/qmk_firmware/pull/9603))
+* Keep track of encoder activity ([#11595](https://github.com/qmk/qmk_firmware/pull/11595))
+* Backport ChibiOS Audio changes from ZSA ([#11687](https://github.com/qmk/qmk_firmware/pull/11687))
+* Add support for 8 buttons to mouse report ([#10807](https://github.com/qmk/qmk_firmware/pull/10807))
+* Allow `post_config.h` to be implemented in userspace ([#11519](https://github.com/qmk/qmk_firmware/pull/11519))
+* Adds AT90USB162 support ([#11570](https://github.com/qmk/qmk_firmware/pull/11570))
+* Stop sounds when suspended ([#11553](https://github.com/qmk/qmk_firmware/pull/11553))
+* Revamp spidey3 userspace and keymaps ([#11768](https://github.com/qmk/qmk_firmware/pull/11768))
+* Add support for analog USBPD on STM32G4xx ([#11824](https://github.com/qmk/qmk_firmware/pull/11824))
+* Master matrix can now be transported to the slave side in Split Common keyboards ([#11046](https://github.com/qmk/qmk_firmware/pull/11046))
+* RGBLight: Allow configurable default settings ([#11912](https://github.com/qmk/qmk_firmware/pull/11912))
+* Add `tap_code_delay(code, delay)` ([#11913](https://github.com/qmk/qmk_firmware/pull/11913), [#11938](https://github.com/qmk/qmk_firmware/pull/11938))
+
+### Clean-ups and Optimizations
+
+* Fix duplicate `I2C_KEYMAP_START` define ([#11237](https://github.com/qmk/qmk_firmware/pull/11237))
+* Rewrite APA102 support for RGBLight ([#10894](https://github.com/qmk/qmk_firmware/pull/10894))
+* Update ADB Protocol implementation in TMK Core ([#11168](https://github.com/qmk/qmk_firmware/pull/11168))
+* Remove unused `action_get_macro()` usages in user files ([#11165](https://github.com/qmk/qmk_firmware/pull/11165))
+* Remove `QMK_KEYBOARD_CONFIG_H` ([#11576](https://github.com/qmk/qmk_firmware/pull/11576))
+* Remove duplicated housekeeping in `arm_atsam` ([#11672](https://github.com/qmk/qmk_firmware/pull/11672))
+* UART driver refactor ([#11637](https://github.com/qmk/qmk_firmware/pull/11637))
+* Move `transport.c` to `QUANTUM_LIB_SRC` ([#11751](https://github.com/qmk/qmk_firmware/pull/11751))
+* Remove `MIDI_ENABLE_STRICT` from user keymaps ([#11750](https://github.com/qmk/qmk_firmware/pull/11750))
+* Remove legacy print backward compatiblitly ([#11805](https://github.com/qmk/qmk_firmware/pull/11805))
+* Migrate mousekey to quantum ([#11804](https://github.com/qmk/qmk_firmware/pull/11804))
+* remove deprecated `qmk json-keymap` ([#11823](https://github.com/qmk/qmk_firmware/pull/11823))
+* Remove FAUXCLICKY feature (deprecated) ([#11829](https://github.com/qmk/qmk_firmware/pull/11829))
+* Refactor platform logic within `print.h` ([#11863](https://github.com/qmk/qmk_firmware/pull/11863))
+* Audio system overhaul ([#11820](https://github.com/qmk/qmk_firmware/pull/11820))
+* Output selection: Remove "USB and BT" option for Bluetooth ([#11940](https://github.com/qmk/qmk_firmware/pull/11940))
+* `tmk_core/common/action.c`: refactor for code size; merge multiple `case`s into one ([#11943](https://github.com/qmk/qmk_firmware/pull/11943))
+* Remove rules and settings from user keymaps that are already defined at keyboard level ([#11966](https://github.com/qmk/qmk_firmware/pull/11966))
+
+### QMK Infrastructure and Internals
+
+* bump to python 3.7 ([#11408](https://github.com/qmk/qmk_firmware/pull/11408))
+* `develop` branch is now formatted as part of CI tasks ([#11893](https://github.com/qmk/qmk_firmware/pull/11893), [#11905](https://github.com/qmk/qmk_firmware/pull/11905), [#11907](https://github.com/qmk/qmk_firmware/pull/11907), [#11928](https://github.com/qmk/qmk_firmware/pull/11928), [#11936](https://github.com/qmk/qmk_firmware/pull/11936))
+* Configure keyboard matrix from info.json ([#10817](https://github.com/qmk/qmk_firmware/pull/10817))
+* Validate our JSON data using json_schema ([#11101](https://github.com/qmk/qmk_firmware/pull/11101))
+* Use the schema to eliminate custom code ([#11108](https://github.com/qmk/qmk_firmware/pull/11108))
+* Add support for specifying BOARD in `info.json` ([#11492](https://github.com/qmk/qmk_firmware/pull/11492))
+* Document how to add data driven configurations ([#11502](https://github.com/qmk/qmk_firmware/pull/11502))
+* Process info.json rules ahead of userspace rules ([#11542](https://github.com/qmk/qmk_firmware/pull/11542))
+* Remove duplicate manufacturer definitions ([#11544](https://github.com/qmk/qmk_firmware/pull/11544))
+* Update list of MCUs in `keyboard.jsonschema` to mirror `qmk.constants.py` ([#11688](https://github.com/qmk/qmk_firmware/pull/11688))
+* Create a system to map between `info.json` and `config.h`/`rules.mk` ([#11548](https://github.com/qmk/qmk_firmware/pull/11548))
+* Make LAYOUT parsing more robust ([#12000](https://github.com/qmk/qmk_firmware/pull/12000))
+
+
+### ChibiOS Update and Config Migration
+
+* Add board specific to Proton-C, with usual defaults turned on to match Pro-Micro ([#10976](https://github.com/qmk/qmk_firmware/pull/10976))
+* Disable almost all ChibiOS subsystems in default configs ([#11111](https://github.com/qmk/qmk_firmware/pull/11111))
+* Config Migrations ([#10418](https://github.com/qmk/qmk_firmware/pull/10418), [#11123](https://github.com/qmk/qmk_firmware/pull/11123), [#11261](https://github.com/qmk/qmk_firmware/pull/11261), [#11413](https://github.com/qmk/qmk_firmware/pull/11413), [#11414](https://github.com/qmk/qmk_firmware/pull/11414), [#11495](https://github.com/qmk/qmk_firmware/pull/11495), [#11504](https://github.com/qmk/qmk_firmware/pull/11504), [#11529](https://github.com/qmk/qmk_firmware/pull/11529), [#11588](https://github.com/qmk/qmk_firmware/pull/11588), [#11598](https://github.com/qmk/qmk_firmware/pull/11598), [#11607](https://github.com/qmk/qmk_firmware/pull/11607), [#11617](https://github.com/qmk/qmk_firmware/pull/11617), [#11620](https://github.com/qmk/qmk_firmware/pull/11620), [#11630](https://github.com/qmk/qmk_firmware/pull/11630), [#11646](https://github.com/qmk/qmk_firmware/pull/11646), [#11689](https://github.com/qmk/qmk_firmware/pull/11689), [#11846](https://github.com/qmk/qmk_firmware/pull/11846), [#11927](https://github.com/qmk/qmk_firmware/pull/11927), [#12001](https://github.com/qmk/qmk_firmware/pull/12001))
+* Disable subsystems repo-wide ([#11449](https://github.com/qmk/qmk_firmware/pull/11449))
+* Leftover early initialisation conversions ([#11615](https://github.com/qmk/qmk_firmware/pull/11615))
+* Fix up comments showing how to execute config migration ([#11621](https://github.com/qmk/qmk_firmware/pull/11621))
+* Add STM32G431 and STM32G474 board definitions ([#11793](https://github.com/qmk/qmk_firmware/pull/11793))

docs/ChangeLog/20210529.md

@@ -0,0 +1,192 @@
+# QMK Breaking Changes - 2021 May 29 Changelog
+
+## Notable Changes :id=notable-changes
+
+### RGB Matrix support for split common ([#11055](https://github.com/qmk/qmk_firmware/pull/11055)) :id=rgb-matrix-split-common
+
+Split boards can now use RGB Matrix without defining a custom matrix.
+
+### Teensy 3.6 support ([#12258](https://github.com/qmk/qmk_firmware/pull/12258)) :id=teensy-3-6-support
+
+Added support for MK66F18 (Teensy 3.6) microcontroller.
+
+### New command: qmk console ([#12828](https://github.com/qmk/qmk_firmware/pull/12828)) :id=new-command-qmk-console
+
+A new `qmk console` command has been added for attaching to your keyboard's console. It operates similiarly to QMK Toolbox by allowing you to connect to one or more keyboard consoles to display debugging messages.
+
+### Improved command: qmk config :id=improve-command-qmk-config
+
+We've updated the `qmk config` command to show only the configuration items you have actually set. You can now display (almost) all of the available configuration options, along with their default values, using `qmk config -a`.
+
+### LED Matrix Improvements ([#12509](https://github.com/qmk/qmk_firmware/pull/12509), [#12580](https://github.com/qmk/qmk_firmware/pull/12580), [#12588](https://github.com/qmk/qmk_firmware/pull/12588), [#12633](https://github.com/qmk/qmk_firmware/pull/12633), [#12651](https://github.com/qmk/qmk_firmware/pull/12651), [#12685](https://github.com/qmk/qmk_firmware/pull/12685)) :id=led-matrix-improvements
+
+LED Matrix has been improved with effects, CIE1931 curves, and a task system.
+
+## Changes Requiring User Action :id=changes-requiring-user-action
+
+### Updated Keyboard Codebases :id=updated-keyboard-codebases
+
+* Durgod keyboard refactor in preparation for adding additional durgod keyboards ([#11978](https://github.com/qmk/qmk_firmware/pull/11978))
+* Updated Function96 with V2 files and removed chconf.h and halconf.h ([#12613](https://github.com/qmk/qmk_firmware/pull/12613))
+* [Keyboard] updated a vendor name / fixed minor keymap issues ([#12881](https://github.com/qmk/qmk_firmware/pull/12881))
+* [Keyboard] Corne - Remove legacy revision support ([#12226](https://github.com/qmk/qmk_firmware/pull/12226))
+
+The following keyboards have had their source moved within QMK:
+
+Old Keyboard Name | New Keyboard Name
+:---------------- | :----------------
+crkbd/rev1/common | crkbd/rev1
+function96 | function96/v1
+nckiibs/flatbread60 | delikeeb/flatbread60
+nckiibs/vaguettelite | delikeeb/vaguettelite
+nckiibs/vanana/rev1 | delikeeb/vanana/rev1
+nckiibs/vanana/rev2 | delikeeb/vanana/rev2
+nckiibs/vaneela | delikeeb/vaneela
+nckiibs/vaneelaex | delikeeb/vaneelaex
+nckiibs/waaffle/rev3/elite_c | delikeeb/waaffle/rev3/elite_c
+nckiibs/waaffle/rev3/pro_micro | delikeeb/waaffle/rev3/pro_micro
+
+The [Function96 V2](https://github.com/qmk/qmk_firmware/tree/0.13.0/keyboards/function96/v2) has also been added as part of these changes.
+
+The codebase for the [Durgod K320](https://github.com/qmk/qmk_firmware/tree/0.13.0/keyboards/durgod/k320) has been reworked in anticipation of additional Durgod keyboards gaining QMK support.
+
+Additionally, the `crkbd/rev1/legacy` keyboard has been removed.
+
+### Bootmagic Deprecation and Refactor ([#12172](https://github.com/qmk/qmk_firmware/pull/12172)) :id=bootmagic-deprecation-and-refactor
+
+QMK has decided to deprecate the full Bootmagic feature and leave Bootmagic Lite as the only remaining option.
+
+This pull request changes the behavior of `BOOTMAGIC_ENABLE` such that specifying `BOOTMAGIC_ENABLE = yes` enables Bootmagic Lite instead of full Bootmagic.
+
+If attempts to use Bootmagic functionality result in unexpected behavior, check your `rules.mk` file and change the `BOOTMAGIC_ENABLE` setting to specify either `lite` or `full`.
+
+#### Tentative Deprecation Schedule
+
+This is the current planned roadmap for the behavior of `BOOTMAGIC_ENABLE`:
+
+- From 2021 May 29, setting `BOOTMAGIC_ENABLE = yes` will enable Bootmagic Lite instead of full Bootmagic.
+- From 2021 Aug 28, `BOOTMAGIC_ENABLE` must be either `yes`, `lite`, or `no` – setting `BOOTMAGIC_ENABLE = full` will cause compilation to fail.
+- From 2021 Nov 27, `BOOTMAGIC_ENABLE` must be either `yes` or `no` – setting `BOOTMAGIC_ENABLE = lite` will cause compilation to fail.
+
+### Removal of LAYOUT_kc ([#12160](https://github.com/qmk/qmk_firmware/pull/12160)) :id=removal-of-layout-kc
+
+We've removed support for `LAYOUT_kc` macros, if your keymap uses one you will need to update it use a regular `LAYOUT` macro.
+
+### Encoder callbacks are now boolean ([#12805](https://github.com/qmk/qmk_firmware/pull/12805), [#12985](https://github.com/qmk/qmk_firmware/pull/12985)) :id=encoder-callback-boolean
+
+To allow for keyboards to override (or not) keymap level code the `encoder_update_kb` function has been changed from `void` to `bool`. You will need to update your function definition to reflect this and ensure that you return a `true` or `false` value.
+
+Example code before change:
+
+```c
+void encoder_update_kb(uint8_t index, bool clockwise) {
+    encoder_update_user(index, clockwise);
+}
+```
+
+Example code after change:
+
+```c
+bool encoder_update_kb(uint8_t index, bool clockwise) {
+    return encoder_update_user(index, clockwise);
+}
+```
+
+## Core Changes :id=core-changes
+
+### Fixes :id=core-fixes
+
+* Fix connection issue in split keyboards when slave and OLED display are connected via I2C (fixes #9335) ([#11487](https://github.com/qmk/qmk_firmware/pull/11487))
+* Terrazzo: Fix wrong LED Matrix function names ([#12561](https://github.com/qmk/qmk_firmware/pull/12561))
+* Apply the "NO_LIMITED_CONTROLLER_CONNECT" fix to atmega16u2 ([#12482](https://github.com/qmk/qmk_firmware/pull/12482))
+* Fix comment parsing ([#12750](https://github.com/qmk/qmk_firmware/pull/12750))
+* Turn OLED off on suspend in soundmonster Corne keymap ([#10419](https://github.com/qmk/qmk_firmware/pull/10419))
+* Fixup build errors on `develop` branch. ([#12723](https://github.com/qmk/qmk_firmware/pull/12723))
+* Fix syntax error when compiling for ARM ([#12866](https://github.com/qmk/qmk_firmware/pull/12866))
+* Add missing LED Matrix suspend code to suspend.c ([#12878](https://github.com/qmk/qmk_firmware/pull/12878))
+* Fix spelling mistake regarding LED Matrix in split_common. ([#12888](https://github.com/qmk/qmk_firmware/pull/12888))
+* [Keymap] Fix QWERTY/DVORAK status output for kzar keymap ([#12895](https://github.com/qmk/qmk_firmware/pull/12895))
+* Fixup housekeeping from being invoked twice per loop. ([#12933](https://github.com/qmk/qmk_firmware/pull/12933))
+* wait for matrix row signal to go HIGH for every row ([#12945](https://github.com/qmk/qmk_firmware/pull/12945))
+* ensure we do not conflict with existing keymap aliases ([#12976](https://github.com/qmk/qmk_firmware/pull/12976))
+* [Keyboard] Fix Terrazzo build failure ([#12977](https://github.com/qmk/qmk_firmware/pull/12977))
+* Do not hard set config in CPTC files ([#11864](https://github.com/qmk/qmk_firmware/pull/11864))
+
+### Additions and Enhancements :id=core-additions
+
+* ARM - Refactor SLEEP_LED to support more platforms ([#8403](https://github.com/qmk/qmk_firmware/pull/8403))
+* Add ability to toggle One Shot functionality ([#4198](https://github.com/qmk/qmk_firmware/pull/4198))
+* Add RGB Matrix support to Split Common ([#11055](https://github.com/qmk/qmk_firmware/pull/11055))
+* Add support for complementary outputs to the ChibiOS WS2812 PWM driver ([#11988](https://github.com/qmk/qmk_firmware/pull/11988))
+* Enable RGB Matrix for Corne ([#12091](https://github.com/qmk/qmk_firmware/pull/12091))
+* Set default OLED Update Interval for Split Keyboards to improve matrix scan performance ([#12107](https://github.com/qmk/qmk_firmware/pull/12107))
+* Add support for MK66F18 (Teensy 3.6) micro controller ([#12258](https://github.com/qmk/qmk_firmware/pull/12258))
+* Split RGB Matrix support for RGBKB Zygomorph ([#11083](https://github.com/qmk/qmk_firmware/pull/11083))
+* Add baudrate and circular buffer to ARM WS2812 SPI config ([#12216](https://github.com/qmk/qmk_firmware/pull/12216))
+* Add keyboard level weak function for slave matrix scan ([#12317](https://github.com/qmk/qmk_firmware/pull/12317))
+* Add link to schematic on EasyEDA for XD60 ([#12018](https://github.com/qmk/qmk_firmware/pull/12018))
+* Add Config functions for LED Matrix ([#12361](https://github.com/qmk/qmk_firmware/pull/12361))
+* Add pin definitions for MK66F18 ([#12419](https://github.com/qmk/qmk_firmware/pull/12419))
+* add kinesis/kint36 keyboard ([#10171](https://github.com/qmk/qmk_firmware/pull/10171))
+* Add support for producing UF2-format binaries. ([#12435](https://github.com/qmk/qmk_firmware/pull/12435))
+* Implement CIE1931 curve for LED Matrix ([#12417](https://github.com/qmk/qmk_firmware/pull/12417))
+* Change `BOOTMAGIC_ENABLE=yes` to use Bootmagic Lite ([#12172](https://github.com/qmk/qmk_firmware/pull/12172))
+* Add kzar keymap for Kinesis Advantage ([#12444](https://github.com/qmk/qmk_firmware/pull/12444))
+* LED Matrix: suspend code ([#12509](https://github.com/qmk/qmk_firmware/pull/12509))
+* LED Matrix: Task system ([#12580](https://github.com/qmk/qmk_firmware/pull/12580))
+* Add missing RGB_MODE_TWINKLE / RGB_M_TW keycodes ([#11935](https://github.com/qmk/qmk_firmware/pull/11935))
+* Enhancement of WPM feature ([#11727](https://github.com/qmk/qmk_firmware/pull/11727))
+* Add Per Key functionality for AutoShift ([#11536](https://github.com/qmk/qmk_firmware/pull/11536))
+* LED Matrix: Reactive effect buffers & advanced indicators ([#12588](https://github.com/qmk/qmk_firmware/pull/12588))
+* LED Matrix: support for Split keyboards ([#12633](https://github.com/qmk/qmk_firmware/pull/12633))
+* add setting to enable infinite timeout for leader key ([#6580](https://github.com/qmk/qmk_firmware/pull/6580), [#12721](https://github.com/qmk/qmk_firmware/pull/12721 "Fix bad PR merge for #6580"))
+* Update ADC driver for STM32F1xx, STM32F3xx, STM32F4xx ([#12403](https://github.com/qmk/qmk_firmware/pull/12403))
+* Add initial support for tinyuf2 bootloader (when hosted on F411 blackpill) ([#12600](https://github.com/qmk/qmk_firmware/pull/12600))
+* Add support for STM32F446 MCU ([#12619](https://github.com/qmk/qmk_firmware/pull/12619))
+* Add STM32L433 and L443 support ([#12063](https://github.com/qmk/qmk_firmware/pull/12063))
+* Added OLED fade out support ([#12086](https://github.com/qmk/qmk_firmware/pull/12086))
+* New command: `qmk console` ([#12828](https://github.com/qmk/qmk_firmware/pull/12828))
+* LED Matrix: Effects! ([#12651](https://github.com/qmk/qmk_firmware/pull/12651))
+* Add setup, clone, and env to the list of commands we allow even with broken modules ([#12868](https://github.com/qmk/qmk_firmware/pull/12868))
+* LED Matrix: Documentation ([#12685](https://github.com/qmk/qmk_firmware/pull/12685))
+* Add function to allow repeated blinking of one layer ([#12237](https://github.com/qmk/qmk_firmware/pull/12237))
+* Add support for up to 4 IS31FL3733 drivers ([#12342](https://github.com/qmk/qmk_firmware/pull/12342))
+* Convert Encoder callbacks to be boolean functions ([#12805](https://github.com/qmk/qmk_firmware/pull/12805), [#12985](https://github.com/qmk/qmk_firmware/pull/12985))
+* [Keymap] Update to Drashna keymap and user code (based on develop) ([#12936](https://github.com/qmk/qmk_firmware/pull/12936))
+* Add Full-duplex serial driver for ARM boards ([#9842](https://github.com/qmk/qmk_firmware/pull/9842))
+* Document LED_MATRIX_FRAMEBUFFER_EFFECTS ([#12987](https://github.com/qmk/qmk_firmware/pull/12987))
+* Backlight: add defines for default level and breathing state ([#12560](https://github.com/qmk/qmk_firmware/pull/12560), [#13024](https://github.com/qmk/qmk_firmware/pull/13024))
+* Add dire message about LUFA mass storage bootloader ([#13014](https://github.com/qmk/qmk_firmware/pull/13014))
+
+### Clean-ups and Optimizations :id=core-optimizations
+
+* Overhaul bootmagic logic to have single entrypoint ([#8532](https://github.com/qmk/qmk_firmware/pull/8532))
+* Refactor of USB code within split_common ([#11890](https://github.com/qmk/qmk_firmware/pull/11890))
+* Begin the process of deprecating `bin/qmk` in favor of the global CLI ([#12109](https://github.com/qmk/qmk_firmware/pull/12109))
+* LED Matrix: decouple from Backlight ([#12054](https://github.com/qmk/qmk_firmware/pull/12054))
+* Remove `FUNC()` ([#12161](https://github.com/qmk/qmk_firmware/pull/12161))
+* Move gpio wait logic to wait.h ([#12067](https://github.com/qmk/qmk_firmware/pull/12067))
+* LED Matrix: Clean up includes ([#12197](https://github.com/qmk/qmk_firmware/pull/12197))
+* Consistently use bin/qmk when that script is called ([#12286](https://github.com/qmk/qmk_firmware/pull/12286))
+* LED Matrix: Additional common_features.mk tweaks ([#12187](https://github.com/qmk/qmk_firmware/pull/12187))
+* LED Matrix: Fix up eeconfig code ([#12327](https://github.com/qmk/qmk_firmware/pull/12327))
+* Big quantum_keycodes cleanup ([#12249](https://github.com/qmk/qmk_firmware/pull/12249))
+* Fix up builds that are now too big for `develop` branch. ([#12495](https://github.com/qmk/qmk_firmware/pull/12495))
+* [Keyboard] kint36: switch to sym_eager_pk debouncing ([#12626](https://github.com/qmk/qmk_firmware/pull/12626))
+* [Keyboard] kint2pp: reduce input latency by ≈10ms ([#12625](https://github.com/qmk/qmk_firmware/pull/12625))
+* eeprom driver: Refactor where eeprom driver initialisation (and EEPROM emulation initialisation) occurs to make it non-target-specific. ([#12671](https://github.com/qmk/qmk_firmware/pull/12671))
+* Change RGB/LED Matrix to use a simple define for USB suspend ([#12697](https://github.com/qmk/qmk_firmware/pull/12697), [#12770](https://github.com/qmk/qmk_firmware/pull/12770 "Fixing transport's led/rgb matrix suspend state logic"))
+* Remove pointless SERIAL_LINK_ENABLE rules ([#12846](https://github.com/qmk/qmk_firmware/pull/12846))
+* Make Swap Hands use PROGMEM ([#12284](https://github.com/qmk/qmk_firmware/pull/12284))
+* Remove KEYMAP and LAYOUT_kc ([#12160](https://github.com/qmk/qmk_firmware/pull/12160))
+* Rename `point_t` -> `led_point_t` ([#12864](https://github.com/qmk/qmk_firmware/pull/12864))
+* Deprecate `send_unicode_hex_string()` ([#12602](https://github.com/qmk/qmk_firmware/pull/12602))
+* [Keyboard] Remove redundant legacy and common headers for crkbd ([#13023](https://github.com/qmk/qmk_firmware/pull/13023))
+
+### QMK Infrastructure and Internals :id=qmk-internals
+
+* trivial change to trigger api update ([`b15288fb87`](https://github.com/qmk/qmk_firmware/commit/b15288fb87))
+* fix some references to bin/qmk that slipped in ([#12832](https://github.com/qmk/qmk_firmware/pull/12832))
+* Resolve a number of warnings in `qmk generate-api` ([#12833](https://github.com/qmk/qmk_firmware/pull/12833))
+* Fix another bin/qmk reference ([#12856](https://github.com/qmk/qmk_firmware/pull/12856))
+* Use milc.subcommand.config instead of qmk.cli.config ([#12915](https://github.com/qmk/qmk_firmware/pull/12915))

docs/README.md

@@ -1,30 +1,24 @@
 # Quantum Mechanical Keyboard Firmware
 
-[![Current Version](https://img.shields.io/github/tag/qmk/qmk_firmware.svg)](https://github.com/qmk/qmk_firmware/tags)
-[![Build Status](https://travis-ci.org/qmk/qmk_firmware.svg?branch=master)](https://travis-ci.org/qmk/qmk_firmware)
-[![Discord](https://img.shields.io/discord/440868230475677696.svg)](https://discord.gg/Uq7gcHh)
-[![Docs Status](https://img.shields.io/badge/docs-ready-orange.svg)](https://docs.qmk.fm)
-[![GitHub contributors](https://img.shields.io/github/contributors/qmk/qmk_firmware.svg)](https://github.com/qmk/qmk_firmware/pulse/monthly)
-[![GitHub forks](https://img.shields.io/github/forks/qmk/qmk_firmware.svg?style=social&label=Fork)](https://github.com/qmk/qmk_firmware/)
-
 ## What is QMK Firmware?
 
 QMK (*Quantum Mechanical Keyboard*) is an open source community centered around developing computer input devices. The community encompasses all sorts of input devices, such as keyboards, mice, and MIDI devices. A core group of collaborators maintains [QMK Firmware](https://github.com/qmk/qmk_firmware), [QMK Configurator](https://config.qmk.fm), [QMK Toolbox](https://github.com/qmk/qmk_toolbox), [qmk.fm](https://qmk.fm), and this documentation with the help of community members like you.
 
 ## Get Started
 
-Totally new to QMK? There are two ways to get started:
+<div class="flex-container">
 
-* Basic: [QMK Configurator](https://config.qmk.fm)
-    * Just select your keyboard from the dropdown and program your keyboard.
-    * We have an [introductory video](https://www.youtube.com/watch?v=-imgglzDMdY) you can watch.
-    * There is also an overview [document you can read](newbs_building_firmware_configurator.md).
-* Advanced: [Use The Source](newbs.md)
-    * More powerful, but harder to use
+?> **Basic** [QMK Configurator](newbs_building_firmware_configurator.md) <br>
+User friendly graphical interfaces, no programming knowledge required.
+
+?> **Advanced** [Use The Source](newbs.md) <br> 
+More powerful, but harder to use.
+
+</div>
 
 ## Make It Yours
 
-QMK has lots of [features](features.md) to explore, and a good deal of reference documentation to dig through. Most features are taken advantage of by modifying your [keymap](keymap.md), and changing the [keycodes](keycodes.md).
+QMK has lots of features to explore, and a good deal of reference documentation to dig through. Most features are taken advantage of by modifying your [keymap](keymap.md), and changing the [keycodes](keycodes.md).
 
 ## Need help?
 

docs/_summary.md

@@ -3,14 +3,15 @@
   * [Setup](newbs_getting_started.md)
   * [Building Your First Firmware](newbs_building_firmware.md)
   * [Flashing Firmware](newbs_flashing.md)
-  * [Testing and Debugging](newbs_testing_debugging.md)
   * [Getting Help/Support](support.md)
   * [Other Resources](newbs_learn_more_resources.md)
+  * [Syllabus](syllabus.md)
 
 * FAQs
   * [General FAQ](faq_general.md)
   * [Build/Compile QMK](faq_build.md)
-  * [Debugging/Troubleshooting QMK](faq_debug.md)
+  * [Troubleshooting QMK](faq_misc.md)
+  * [Debugging QMK](faq_debug.md)
   * [Keymap FAQ](faq_keymap.md)
   * [Glossary](reference_glossary.md)
 
@@ -22,18 +23,22 @@
     * [Overview](api_overview.md)
     * [API Documentation](api_docs.md)
     * [Keyboard Support](reference_configurator_support.md)
+    * [Adding Default Keymaps](configurator_default_keymaps.md)
 
 * CLI
     * [Overview](cli.md)
     * [Configuration](cli_configuration.md)
     * [Commands](cli_commands.md)
+    * [Tab Completion](cli_tab_complete.md)
 
 * Using QMK
   * Guides
     * [Customizing Functionality](custom_quantum_functions.md)
     * [Driver Installation with Zadig](driver_installation_zadig.md)
     * [Keymap Overview](keymap.md)
-    * [Vagrant Guide](getting_started_vagrant.md)
+    * Development Environments
+      * [Docker Guide](getting_started_docker.md)
+      * [Vagrant Guide](getting_started_vagrant.md)
     * Flashing
       * [Flashing](flashing.md)
       * [Flashing ATmega32A (ps2avrgb)](flashing_bootloadhid.md)
@@ -52,6 +57,7 @@
   * Simple Keycodes
     * [Full List](keycodes.md)
     * [Basic Keycodes](keycodes_basic.md)
+    * [Language-Specific Keycodes](reference_keymap_extras.md)
     * [Modifier Keys](feature_advanced_keycodes.md)
     * [Quantum Keycodes](quantum_keycodes.md)
 
@@ -74,12 +80,15 @@
     * [Layers](feature_layers.md)
     * [One Shot Keys](one_shot_keys.md)
     * [Pointing Device](feature_pointing_device.md)
+    * [Raw HID](feature_rawhid.md)
+    * [Sequencer](feature_sequencer.md)
     * [Swap Hands](feature_swap_hands.md)
     * [Tap Dance](feature_tap_dance.md)
     * [Tap-Hold Configuration](tap_hold.md)
     * [Terminal](feature_terminal.md)
     * [Unicode](feature_unicode.md)
     * [Userspace](feature_userspace.md)
+    * [WPM Calculation](feature_wpm.md)
 
   * Hardware Features
     * Displays
@@ -97,6 +106,9 @@
     * [DIP Switch](feature_dip_switch.md)
     * [Encoders](feature_encoders.md)
     * [Haptic Feedback](feature_haptic_feedback.md)
+    * [Joystick](feature_joystick.md)
+    * [LED Indicators](feature_led_indicators.md)
+    * [MIDI](feature_midi.md)
     * [Proton C Conversion](proton_c_conversion.md)
     * [PS/2 Mouse](feature_ps2_mouse.md)
     * [Split Keyboard](feature_split_keyboard.md)
@@ -105,12 +117,12 @@
     * [Velocikey](feature_velocikey.md)
 
 * Developing QMK
+  * [PR Checklist](pr_checklist.md)
   * Breaking Changes
     * [Overview](breaking_changes.md)
     * [My Pull Request Was Flagged](breaking_changes_instructions.md)
-    * History
-      * [2020 Feb 29](ChangeLog/20200229.md)
-      * [2019 Aug 30](ChangeLog/20190830.md)
+    * [Most Recent ChangeLog](ChangeLog/20210529.md "QMK v0.13.0 - 2021 May 29")
+    * [Past Breaking Changes](breaking_changes_history.md)
 
   * C Development
     * [ARM Debugging Guide](arm_debugging.md)
@@ -119,9 +131,13 @@
     * [Compatible Microcontrollers](compatible_microcontrollers.md)
     * [Drivers](hardware_drivers.md)
       * [ADC Driver](adc_driver.md)
+      * [Audio Driver](audio_driver.md)
       * [I2C Driver](i2c_driver.md)
+      * [SPI Driver](spi_driver.md)
       * [WS2812 Driver](ws2812_driver.md)
       * [EEPROM Driver](eeprom_driver.md)
+      * ['serial' Driver](serial_driver.md)
+      * [UART Driver](uart_driver.md)
     * [GPIO Controls](internals_gpio_control.md)
     * [Keyboard Guidelines](hardware_keyboard_guidelines.md)
 
@@ -134,10 +150,16 @@
       * [Development Environment](api_development_environment.md)
       * [Architecture Overview](api_development_overview.md)
 
+  * Hardware Platform Development
+    * Arm/ChibiOS
+      * [Selecting an MCU](platformdev_selecting_arm_mcu.md)
+      * [Early initialization](platformdev_chibios_earlyinit.md)
+
   * QMK Reference
     * [Contributing to QMK](contributing.md)
     * [Translating the QMK Docs](translating.md)
     * [Config Options](config_options.md)
+    * [Data Driven Configuration](data_driven_config.md)
     * [Make Documentation](getting_started_make_guide.md)
     * [Documentation Best Practices](documentation_best_practices.md)
     * [Documentation Templates](documentation_templates.md)

docs/adc_driver.md

@@ -22,7 +22,7 @@ Then place this include at the top of your code:
 
 ### AVR
 
-|Channel|AT90USB64/128|ATmega16/32U4|ATmega32A|ATmega328P|
+|Channel|AT90USB64/128|ATmega16/32U4|ATmega32A|ATmega328/P|
 |-------|-------------|-------------|---------|----------|
 |0      |`F0`         |`F0`         |`A0`     |`C0`      |
 |1      |`F1`         |`F1`         |`A1`     |`C1`      |
@@ -39,81 +39,87 @@ Then place this include at the top of your code:
 |12     |             |`B5`         |         |          |
 |13     |             |`B6`         |         |          |
 
-<sup>\* The ATmega328P possesses two extra ADC channels; however, they are not present on the DIP pinout, and are not shared with GPIO pins. You can use `adc_read()` directly to gain access to these.</sup>
+<sup>\* The ATmega328/P possesses two extra ADC channels; however, they are not present on the DIP pinout, and are not shared with GPIO pins. You can use `adc_read()` directly to gain access to these.</sup>
 
 ### ARM
 
 Note that some of these pins are doubled-up on ADCs with the same channel. This is because the pins can be used for either ADC.
 
-Also note that the F0 and F3 use different numbering schemes. The F0 has a single ADC and the channels are 0-based, whereas the F3 has 4 ADCs and the channels are 1 based. This is because the F0 uses the `ADCv1` implementation of the ADC, whereas the F3 uses the `ADCv3` implementation.
+Also note that the F0 and F3 use different numbering schemes. The F0 has a single ADC and the channels are 0-indexed, whereas the F3 has 4 ADCs and the channels are 1-indexed. This is because the F0 uses the `ADCv1` implementation of the ADC, whereas the F3 uses the `ADCv3` implementation.
 
-|ADC|Channel|STM32F0XX|STM32F3XX|
-|---|-------|---------|---------|
-|1  |0      |`A0`     |         |
-|1  |1      |`A1`     |`A0`     |
-|1  |2      |`A2`     |`A1`     |
-|1  |3      |`A3`     |`A2`     |
-|1  |4      |`A4`     |`A3`     |
-|1  |5      |`A5`     |`F4`     |
-|1  |6      |`A6`     |`C0`     |
-|1  |7      |`A7`     |`C1`     |
-|1  |8      |`B0`     |`C2`     |
-|1  |9      |`B1`     |`C3`     |
-|1  |10     |`C0`     |`F2`     |
-|1  |11     |`C1`     |         |
-|1  |12     |`C2`     |         |
-|1  |13     |`C3`     |         |
-|1  |14     |`C4`     |         |
-|1  |15     |`C5`     |         |
-|1  |16     |         |         |
-|2  |1      |         |`A4`     |
-|2  |2      |         |`A5`     |
-|2  |3      |         |`A6`     |
-|2  |4      |         |`A7`     |
-|2  |5      |         |`C4`     |
-|2  |6      |         |`C0`     |
-|2  |7      |         |`C1`     |
-|2  |8      |         |`C2`     |
-|2  |9      |         |`C3`     |
-|2  |10     |         |`F2`     |
-|2  |11     |         |`C5`     |
-|2  |12     |         |`B2`     |
-|2  |13     |         |         |
-|2  |14     |         |         |
-|2  |15     |         |         |
-|2  |16     |         |         |
-|3  |1      |         |`B1`     |
-|3  |2      |         |`E9`     |
-|3  |3      |         |`E13`    |
-|3  |4      |         |         |
-|3  |5      |         |         |
-|3  |6      |         |`E8`     |
-|3  |7      |         |`D10`    |
-|3  |8      |         |`D11`    |
-|3  |9      |         |`D12`    |
-|3  |10     |         |`D13`    |
-|3  |11     |         |`D14`    |
-|3  |12     |         |`B0`     |
-|3  |13     |         |`E7`     |
-|3  |14     |         |`E10`    |
-|3  |15     |         |`E11`    |
-|3  |16     |         |`E12`    |
-|4  |1      |         |`E14`    |
-|4  |2      |         |`B12`    |
-|4  |3      |         |`B13`    |
-|4  |4      |         |`B14`    |
-|4  |5      |         |`B15`    |
-|4  |6      |         |`E8`     |
-|4  |7      |         |`D10`    |
-|4  |8      |         |`D11`    |
-|4  |9      |         |`D12`    |
-|4  |10     |         |`D13`    |
-|4  |11     |         |`D14`    |
-|4  |12     |         |`D8`     |
-|4  |13     |         |`D9`     |
-|4  |14     |         |         |
-|4  |15     |         |         |
-|4  |16     |         |         |
+|ADC|Channel|STM32F0xx|STM32F1xx|STM32F3xx|STM32F4xx|
+|---|-------|---------|---------|---------|---------|
+|1  |0      |`A0`     |`A0`     |         |`A0`     |
+|1  |1      |`A1`     |`A1`     |`A0`     |`A1`     |
+|1  |2      |`A2`     |`A2`     |`A1`     |`A2`     |
+|1  |3      |`A3`     |`A3`     |`A2`     |`A3`     |
+|1  |4      |`A4`     |`A4`     |`A3`     |`A4`     |
+|1  |5      |`A5`     |`A5`     |`F4`     |`A5`     |
+|1  |6      |`A6`     |`A6`     |`C0`     |`A6`     |
+|1  |7      |`A7`     |`A7`     |`C1`     |`A7`     |
+|1  |8      |`B0`     |`B0`     |`C2`     |`B0`     |
+|1  |9      |`B1`     |`B1`     |`C3`     |`B1`     |
+|1  |10     |`C0`     |`C0`     |`F2`     |`C0`     |
+|1  |11     |`C1`     |`C1`     |         |`C1`     |
+|1  |12     |`C2`     |`C2`     |         |`C2`     |
+|1  |13     |`C3`     |`C3`     |         |`C3`     |
+|1  |14     |`C4`     |`C4`     |         |`C4`     |
+|1  |15     |`C5`     |`C5`     |         |`C5`     |
+|1  |16     |         |         |         |         |
+|2  |0      |         |`A0`¹    |         |`A0`²    |
+|2  |1      |         |`A1`¹    |`A4`     |`A1`²    |
+|2  |2      |         |`A2`¹    |`A5`     |`A2`²    |
+|2  |3      |         |`A3`¹    |`A6`     |`A3`²    |
+|2  |4      |         |`A4`¹    |`A7`     |`A4`²    |
+|2  |5      |         |`A5`¹    |`C4`     |`A5`²    |
+|2  |6      |         |`A6`¹    |`C0`     |`A6`²    |
+|2  |7      |         |`A7`¹    |`C1`     |`A7`²    |
+|2  |8      |         |`B0`¹    |`C2`     |`B0`²    |
+|2  |9      |         |`B1`¹    |`C3`     |`B1`²    |
+|2  |10     |         |`C0`¹    |`F2`     |`C0`²    |
+|2  |11     |         |`C1`¹    |`C5`     |`C1`²    |
+|2  |12     |         |`C2`¹    |`B2`     |`C2`²    |
+|2  |13     |         |`C3`¹    |         |`C3`²    |
+|2  |14     |         |`C4`¹    |         |`C4`²    |
+|2  |15     |         |`C5`¹    |         |`C5`²    |
+|2  |16     |         |         |         |         |
+|3  |0      |         |`A0`¹    |         |`A0`²    |
+|3  |1      |         |`A1`¹    |`B1`     |`A1`²    |
+|3  |2      |         |`A2`¹    |`E9`     |`A2`²    |
+|3  |3      |         |`A3`¹    |`E13`    |`A3`²    |
+|3  |4      |         |`F6`¹    |         |`F6`²    |
+|3  |5      |         |`F7`¹    |`B13`    |`F7`²    |
+|3  |6      |         |`F8`¹    |`E8`     |`F8`²    |
+|3  |7      |         |`F9`¹    |`D10`    |`F9`²    |
+|3  |8      |         |`F10`¹   |`D11`    |`F10`²   |
+|3  |9      |         |         |`D12`    |`F3`²    |
+|3  |10     |         |`C0`¹    |`D13`    |`C0`²    |
+|3  |11     |         |`C1`¹    |`D14`    |`C1`²    |
+|3  |12     |         |`C2`¹    |`B0`     |`C2`²    |
+|3  |13     |         |`C3`¹    |`E7`     |`C3`²    |
+|3  |14     |         |         |`E10`    |`F4`²    |
+|3  |15     |         |         |`E11`    |`F5`²    |
+|3  |16     |         |         |`E12`    |         |
+|4  |1      |         |         |`E14`    |         |
+|4  |2      |         |         |`E15`    |         |
+|4  |3      |         |         |`B12`    |         |
+|4  |4      |         |         |`B14`    |         |
+|4  |5      |         |         |`B15`    |         |
+|4  |6      |         |         |`E8`     |         |
+|4  |7      |         |         |`D10`    |         |
+|4  |8      |         |         |`D11`    |         |
+|4  |9      |         |         |`D12`    |         |
+|4  |10     |         |         |`D13`    |         |
+|4  |11     |         |         |`D14`    |         |
+|4  |12     |         |         |`D8`     |         |
+|4  |13     |         |         |`D9`     |         |
+|4  |14     |         |         |         |         |
+|4  |15     |         |         |         |         |
+|4  |16     |         |         |         |         |
+
+<sup>¹ As of ChibiOS 20.3.4, the ADC driver for STM32F1xx devices supports only ADC1, therefore any configurations involving ADC2 or ADC3 cannot actually be used. In particular, pins `F6`…`F10`, which are present at least on some STM32F103x[C-G] devices, cannot be used as ADC inputs because of this driver limitation.</sup>
+
+<sup>² Not all STM32F4xx devices have ADC2 and/or ADC3, therefore some configurations shown in this table may be unavailable; in particular, pins `F4`…`F10` cannot be used as ADC inputs on devices which do not have ADC3. Check the device datasheet to confirm which pin functions are supported.</sup>
 
 ## Functions
 
@@ -122,32 +128,29 @@ Also note that the F0 and F3 use different numbering schemes. The F0 has a singl
 |Function                    |Description                                                                                                        |
 |----------------------------|-------------------------------------------------------------------------------------------------------------------|
 |`analogReference(mode)`     |Sets the analog voltage reference source. Must be one of `ADC_REF_EXTERNAL`, `ADC_REF_POWER` or `ADC_REF_INTERNAL`.|
-|`analogRead(pin)`           |Reads the value from the specified Arduino pin, eg. `4` for ADC6 on the ATmega32U4.                                |
-|`analogReadPin(pin)`        |Reads the value from the specified QMK pin, eg. `F6` for ADC6 on the ATmega32U4.                                   |
-|`pinToMux(pin)`             |Translates a given QMK pin to a mux value. If an unsupported pin is given, returns the mux value for "0V (GND)".   |
+|`analogReadPin(pin)`        |Reads the value from the specified pin, eg. `F6` for ADC6 on the ATmega32U4.                                       |
+|`pinToMux(pin)`             |Translates a given pin to a mux value. If an unsupported pin is given, returns the mux value for "0V (GND)".       |
 |`adc_read(mux)`             |Reads the value from the ADC according to the specified mux. See your MCU's datasheet for more information.        |
 
 ### ARM
 
-Note that care was taken to match all of the functions used for AVR devices, however complications in the ARM platform prevent that from always being possible. For example, the `STM32` chips do not have assigned Arduino pins. We could use the default pin numbers, but those numbers change based on the package type of the device. For this reason, please specify your target pins with their identifiers (`A0`, `F3`, etc.). Also note that there are some variants of functions that accept the target ADC for the pin. Some pins can be used for multiple ADCs, and this specified can help you pick which ADC will be used to interact with that pin.
-
-|Function                    |Description                                                                                                         |
-|----------------------------|--------------------------------------------------------------------------------------------------------------------|
-|`analogReadPin(pin)`        |Reads the value from the specified QMK pin, eg. `A0` for channel 0 on the STM32F0 and ADC1 channel 1 on the STM32F3. Note that if a pin can be used for multiple ADCs, it will pick the lower numbered ADC for this function. eg. `C0` will be channel 6 of ADC 1 when it could be used for ADC 2 as well.|
-|`analogReadPinAdc(pin, adc)`|Reads the value from the specified QMK pin and ADC, eg. `C0, 1` will read from channel 6, ADC 2 instead of ADC 1. Note that the ADCs are 0-indexed for this function.|
-|`pinToMux(pin)`             |Translates a given QMK pin to a channel and ADC combination. If an unsupported pin is given, returns the mux value for "0V (GND)".|
-|`adc_read(mux)`             |Reads the value from the ADC according to the specified pin and adc combination. See your MCU's datasheet for more information.|
+|Function                    |Description                                                                                                                                                                                                                                                                                           |
+|----------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+|`analogReadPin(pin)`        |Reads the value from the specified pin, eg. `A0` for channel 0 on the STM32F0 and ADC1 channel 1 on the STM32F3. Note that if a pin can be used for multiple ADCs, it will pick the lower numbered ADC for this function. eg. `C0` will be channel 6 of ADC 1 when it could be used for ADC 2 as well.|
+|`analogReadPinAdc(pin, adc)`|Reads the value from the specified pin and ADC, eg. `C0, 1` will read from channel 6, ADC 2 instead of ADC 1. Note that the ADCs are 0-indexed for this function.                                                                                                                                     |
+|`pinToMux(pin)`             |Translates a given pin to a channel and ADC combination. If an unsupported pin is given, returns the mux value for "0V (GND)".                                                                                                                                                                        |
+|`adc_read(mux)`             |Reads the value from the ADC according to the specified pin and ADC combination. See your MCU's datasheet for more information.                                                                                                                                                                       |
 
 ## Configuration
 
 ## ARM
 
-The ARM implementation of the ADC has a few additional options that you can override in your own keyboards and keymaps to change how it operates.
+The ARM implementation of the ADC has a few additional options that you can override in your own keyboards and keymaps to change how it operates. Please consult the corresponding `hal_adc_lld.h` in ChibiOS for your specific microcontroller for further documentation on your available options.
 
-|`#define`          |Type  |Default              |Description|
-|-------------------|------|---------------------|-----------|
-|ADC_CIRCULAR_BUFFER|`bool`|`false`              |If `TRUE`, then the implementation will use a circular buffer.|
-|ADC_NUM_CHANNELS   |`int` |`1`                  |Sets the number of channels that will be scanned as part of an ADC operation. The current implementation only supports `1`.|
-|ADC_BUFFER_DEPTH   |`int` |`2`                  |Sets the depth of each result. Since we are only getting a 12-bit result by default, we set this to `2` bytes so we can contain our one value. This could be set to 1 if you opt for a 8-bit or lower result.|
-|ADC_SAMPLING_RATE  |`int` |`ADC_SMPR_SMP_1P5`   |Sets the sampling rate of the ADC. By default, it is set to the fastest setting. Please consult the corresponding `hal_adc_lld.h` in ChibiOS for your specific microcontroller for further documentation on your available options.|
-|ADC_RESOLUTION     |`int` |`ADC_CFGR1_RES_12BIT`|The resolution of your result. We choose 12 bit by default, but you can opt for 12, 10, 8, or 6 bit. Please consult the corresponding `hal_adc_lld.h` in ChibiOS for your specific microcontroller for further documentation on your available options.|
+|`#define`            |Type  |Default                                       |Description                                                                                                                                                                                                 |
+|---------------------|------|----------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+|`ADC_CIRCULAR_BUFFER`|`bool`|`false`                                       |If `true`, then the implementation will use a circular buffer.                                                                                                                                              |
+|`ADC_NUM_CHANNELS`   |`int` |`1`                                           |Sets the number of channels that will be scanned as part of an ADC operation. The current implementation only supports `1`.                                                                                 |
+|`ADC_BUFFER_DEPTH`   |`int` |`2`                                           |Sets the depth of each result. Since we are only getting a 10-bit result by default, we set this to 2 bytes so we can contain our one value. This could be set to 1 if you opt for an 8-bit or lower result.|
+|`ADC_SAMPLING_RATE`  |`int` |`ADC_SMPR_SMP_1P5`                            |Sets the sampling rate of the ADC. By default, it is set to the fastest setting.                                                                                                                            |
+|`ADC_RESOLUTION`     |`int` |`ADC_CFGR1_RES_10BIT` or `ADC_CFGR_RES_10BITS`|The resolution of your result. We choose 10 bit by default, but you can opt for 12, 10, 8, or 6 bit. Different MCUs use slightly different names for the resolution constants.                              |

docs/api_docs.md

@@ -28,7 +28,7 @@ As you can see the payload describes all aspects of a keyboard necessary to crea
 To compile your keymap into a firmware simply POST your JSON to the `/v1/compile` endpoint. In the following example we've placed the JSON payload into a file named `json_data`.
 
 ```
-$ curl -H "Content-Type: application/json" -X POST -d "$(< json_data)" http://api.qmk.fm/v1/compile
+$ curl -H "Content-Type: application/json" -X POST -d "$(< json_data)" https://api.qmk.fm/v1/compile
 {
   "enqueued": true,
   "job_id": "ea1514b3-bdfc-4a7b-9b5c-08752684f7f6"
@@ -40,7 +40,7 @@ $ curl -H "Content-Type: application/json" -X POST -d "$(< json_data)" http://ap
 After submitting your keymap you can check the status using a simple HTTP GET call:
 
 ```
-$ curl http://api.qmk.fm/v1/compile/ea1514b3-bdfc-4a7b-9b5c-08752684f7f6
+$ curl https://api.qmk.fm/v1/compile/ea1514b3-bdfc-4a7b-9b5c-08752684f7f6
 {
   "created_at": "Sat, 19 Aug 2017 21:39:12 GMT",
   "enqueued_at": "Sat, 19 Aug 2017 21:39:12 GMT",

docs/api_overview.md

@@ -1,6 +1,6 @@
 # QMK API
 
-The QMK API provides an asynchronous API that Web and GUI tools can use to compile arbitrary keymaps for any keyboard supported by [QMK](http://qmk.fm/). The stock keymap template supports all QMK keycodes that do not require supporting C code. Keyboard maintainers can supply their own custom templates to enable more functionality.
+The QMK API provides an asynchronous API that Web and GUI tools can use to compile arbitrary keymaps for any keyboard supported by [QMK](https://qmk.fm/). The stock keymap template supports all QMK keycodes that do not require supporting C code. Keyboard maintainers can supply their own custom templates to enable more functionality.
 
 ## App Developers
 

docs/audio_driver.md

@@ -0,0 +1,221 @@
+# Audio Driver :id=audio-driver
+
+The [Audio feature](feature_audio.md) breaks the hardware specifics out into separate, exchangeable driver units, with a common interface to the audio-"core" - which itself handles playing songs and notes while tracking their progress in an internal state, initializing/starting/stopping the driver as needed.
+
+Not all MCUs support every available driver, either the platform-support is not there (yet?) or the MCU simply does not have the required hardware peripheral.
+
+
+## AVR :id=avr
+
+Boards built around an Atmega32U4 can use two sets of PWM capable pins, each driving a separate speaker.
+The possible configurations are:
+
+|              | Timer3      | Timer1       |
+|--------------|-------------|--------------|
+| one speaker  | C4,C5 or C6 |              |
+| one speaker  |             | B4, B5 or B7 |
+| two speakers | C4,C5 or C6 | B4, B5 or B7 |
+
+Currently there is only one/default driver for AVR based boards, which is automatically configured to:
+
+```make
+AUDIO_DRIVER = pwm_hardware
+```
+
+
+## ARM :id=arm
+
+For Arm based boards, QMK depends on ChibiOS - hence any MCU supported by the later is likely usable, as long as certain hardware peripherals are available.
+
+Supported wiring configurations, with their ChibiOS/MCU peripheral requirement are listed below;
+piezo speakers are marked with :one: for the first/primary and :two: for the secondary.
+
+  | driver       | GPTD6<br>Tim6                            | GPTD7<br>Tim7          | GPTD8<br>Tim8 | PWMD1<sup>1</sup><br>Tim1_Ch1 |
+  |--------------|------------------------------------------|------------------------|---------------|-------------------------------|
+  | dac_basic    | A4+DACD1 = :one:                         | A5+DACD2 = :one:       | state         |                               |
+  |              | A4+DACD1 = :one: + Gnd                   | A5+DACD2 = :two: + Gnd | state         |                               |
+  |              | A4+DACD1 = :two: + Gnd                   | A5+DACD2 = :one: + Gnd | state         |                               |
+  |              | A4+DACD1 = :one: + Gnd                   |                        | state         |                               |
+  |              |                                          | A5+DACD2 = :one: + Gnd | state         |                               |
+  | dac_additive | A4+DACD1 = :one: + Gnd                   |                        |               |                               |
+  |              | A5+DACD2 = :one: + Gnd                   |                        |               |                               |
+  |              | A4+DACD1 + A5+DACD2 = :one: <sup>2</sup> |                        |               |                               |
+  | pwm_software | state-update                             |                        |               | any = :one:                   |
+  | pwm hardware | state-update                             |                        |               | A8 = :one: <sup>3</sup>       |
+
+
+<sup>1</sup>: the routing and alternate functions for PWM differ sometimes between STM32 MCUs, if in doubt consult the data-sheet  
+<sup>2</sup>: one piezo connected to A4 and A5, with AUDIO_PIN_ALT_AS_NEGATIVE set  
+<sup>3</sup>: TIM1_CH1 = A8 on STM32F103C8, other combinations are possible, see Data-sheet. configured with: AUDIO_PWM_DRIVER and AUDIO_PWM_CHANNEL
+
+
+
+### DAC basic :id=dac-basic
+
+The default driver for ARM boards, in absence of an overriding configuration.
+This driver needs one Timer per enabled/used DAC channel, to trigger conversion; and a third timer to trigger state updates with the audio-core.
+
+Additionally, in the board config, you'll want to make changes to enable the DACs, GPT for Timers 6, 7 and 8:
+
+``` c
+//halconf.h:
+#define HAL_USE_DAC                 TRUE
+#define HAL_USE_GPT                 TRUE
+#include_next <halconf.h>
+```
+
+``` c
+// mcuconf.h:
+#include_next <mcuconf.h>
+#undef STM32_DAC_USE_DAC1_CH1
+#define STM32_DAC_USE_DAC1_CH1              TRUE
+#undef STM32_DAC_USE_DAC1_CH2
+#define STM32_DAC_USE_DAC1_CH2              TRUE
+#undef STM32_GPT_USE_TIM6
+#define STM32_GPT_USE_TIM6                  TRUE
+#undef STM32_GPT_USE_TIM7
+#define STM32_GPT_USE_TIM7                  TRUE
+#undef STM32_GPT_USE_TIM8
+#define STM32_GPT_USE_TIM8                  TRUE
+```
+
+?> Note: DAC1 (A4) uses TIM6, DAC2 (A5) uses TIM7, and the audio state timer uses TIM8 (configurable). 
+
+You can also change the timer used for the overall audio state by defining the driver.  For instance: 
+
+```c
+#define AUDIO_STATE_TIMER GPTD9
+```
+
+### DAC additive :id=dac-additive
+
+only needs one timer (GPTD6, Tim6) to trigger the DAC unit to do a conversion; the audio state updates are in turn triggered during the DAC callback.
+
+Additionally, in the board config, you'll want to make changes to enable the DACs, GPT for Timer 6:
+
+``` c
+//halconf.h:
+#define HAL_USE_DAC                 TRUE
+#define HAL_USE_GPT                 TRUE
+#include_next <halconf.h>
+```
+
+``` c
+// mcuconf.h:
+#include_next <mcuconf.h>
+#undef STM32_DAC_USE_DAC1_CH1
+#define STM32_DAC_USE_DAC1_CH1              TRUE
+#undef STM32_DAC_USE_DAC1_CH2
+#define STM32_DAC_USE_DAC1_CH2              TRUE
+#undef STM32_GPT_USE_TIM6
+#define STM32_GPT_USE_TIM6                  TRUE
+```
+
+### DAC Config
+
+| Define                           | Defaults                   | Description                                                --------------------------------------------------------------------------------------------- |
+| `AUDIO_DAC_SAMPLE_MAX`           | `4095U`                    | Highest value allowed. Lower value means lower volume. And 4095U is the upper limit, since this is limited to a 12 bit value. Only effects non-pregenerated samples.  |
+| `AUDIO_DAC_OFF_VALUE`            | `AUDIO_DAC_SAMPLE_MAX / 2` | The value of the DAC when notplaying anything. Some setups may require a high (`AUDIO_DAC_SAMPLE_MAX`) or low (`0`) value here.                                        |
+| `AUDIO_MAX_SIMULTANEOUS_TONES`   | __see next table__         | The number of tones that can be played simultaneously.  A value that is too high may freeze the controller or glitch out when too many tones are being played.        |
+| `AUDIO_DAC_SAMPLE_RATE`          | __see next table__         | Effective bit rate of the DAC (in hertz), higher limits simultaneous tones, and lower sacrifices quality.                                                          |
+
+There are a number of predefined quality settings that you can use, with "sane minimum" being the default.  You can use custom values by simply defining the sample rate and number of simultaneous tones, instead of using one of the listed presets. 
+
+| Define                            | Sample Rate | Simultaneous tones  |
+| `AUDIO_DAC_QUALITY_VERY_LOW`      | `11025U`    | `8`                 |
+| `AUDIO_DAC_QUALITY_LOW`           | `22040U`    | `4`                 |
+| `AUDIO_DAC_QUALITY_HIGH`          | `44100U`    | `2`                 |
+| `AUDIO_DAC_QUALITY_VERY_HIGH`     | `88200U`    | `1`                 |
+| `AUDIO_DAC_QUALITY_SANE_MINIMUM`  | `16384U`    | `8`                 |
+
+
+```c
+        /* zero crossing (or approach, whereas zero == DAC_OFF_VALUE, which can be configured to anything from 0 to DAC_SAMPLE_MAX)
+         * ============================*=*========================== AUDIO_DAC_SAMPLE_MAX
+         *                          *       *
+         *                        *           *
+         * ---------------------------------------------------------
+         *                     *                 *                  } AUDIO_DAC_SAMPLE_MAX/100
+         * --------------------------------------------------------- AUDIO_DAC_OFF_VALUE
+         *                  *                       *               } AUDIO_DAC_SAMPLE_MAX/100
+         * ---------------------------------------------------------
+         *               *
+         * *           *
+         *   *       *
+         * =====*=*================================================= 0x0
+         */
+```
+
+
+### PWM hardware :id=pwm-hardware
+
+This driver uses the ChibiOS-PWM system to produce a square-wave on specific output pins that are connected to the PWM hardware.
+The hardware directly toggles the pin via its alternate function. See your MCU's data-sheet for which pin can be driven by what timer - looking for TIMx_CHy and the corresponding alternate function.
+
+A configuration example for the STM32F103C8 would be:
+``` c
+//halconf.h:
+#define HAL_USE_PWM                 TRUE
+#define HAL_USE_PAL                 TRUE
+#define HAL_USE_GPT                 TRUE
+#include_next <halconf.h>
+```
+
+``` c
+// mcuconf.h:
+#include_next <mcuconf.h>
+#undef STM32_PWM_USE_TIM1
+#define STM32_PWM_USE_TIM1                  TRUE
+#undef STM32_GPT_USE_TIM4
+#define STM32_GPT_USE_TIM4                  TRUE
+```
+
+If we now target pin A8, looking through the data-sheet of the STM32F103C8, for the timers and alternate functions
+- TIM1_CH1 = PA8 <- alternate0
+- TIM1_CH2 = PA9
+- TIM1_CH3 = PA10
+- TIM1_CH4 = PA11
+
+with all this information, the configuration would contain these lines:
+``` c
+//config.h:
+#define AUDIO_PIN A8
+#define AUDIO_PWM_DRIVER PWMD1
+#define AUDIO_PWM_CHANNEL 1
+#define AUDIO_STATE_TIMER GPTD4
+```
+
+ChibiOS uses GPIOv1 for the F103, which only knows of one alternate function.
+On 'larger' STM32s, GPIOv2 or GPIOv3 are used; with them it is also necessary to configure `AUDIO_PWM_PAL_MODE` to the correct alternate function for the selected pin, timer and timer-channel.
+
+
+### PWM software :id=pwm-software
+
+This driver uses the PWM callbacks from PWMD1 with TIM1_CH1 to toggle the selected AUDIO_PIN in software.
+During the same callback, with AUDIO_PIN_ALT_AS_NEGATIVE set, the AUDIO_PIN_ALT is toggled inversely to AUDIO_PIN. This is useful for setups that drive a piezo from two pins (instead of one and Gnd).
+
+You can also change the timer used for software PWM by defining the driver.  For instance: 
+
+```c
+#define AUDIO_STATE_TIMER GPTD8
+```
+
+
+### Testing Notes :id=testing-notes
+
+While not an exhaustive list, the following table provides the scenarios that have been partially validated:
+
+|                          | DAC basic          | DAC additive       | PWM hardware       | PWM software       |
+|--------------------------|--------------------|--------------------|--------------------|--------------------|
+| Atmega32U4               | :o:                | :o:                | :heavy_check_mark: | :o:                |
+| STM32F103C8 (bluepill)   | :x:                | :x:                | :heavy_check_mark: | :heavy_check_mark: |
+| STM32F303CCT6 (proton-c) | :heavy_check_mark: | :heavy_check_mark: | ?                  | :heavy_check_mark: |
+| STM32F405VG              | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
+| L0xx                     | :x: (no Tim8)      | ?                  | ?                  | ?                  |
+
+
+:heavy_check_mark: : works and was tested  
+:o: : does not apply  
+:x: : not supported by MCU
+
+*Other supported ChibiOS boards and/or pins may function, it will be highly chip and configuration dependent.*

docs/breaking_changes.md

@@ -6,27 +6,32 @@ The breaking change period is when we will merge PR's that change QMK in dangero
 
 ## What has been included in past Breaking Changes?
 
+* [2021 May 29](ChangeLog/20210529.md)
+* [2021 Feb 27](ChangeLog/20210227.md)
+* [2020 Nov 28](ChangeLog/20201128.md)
+* [2020 Aug 29](ChangeLog/20200829.md)
+* [2020 May 30](ChangeLog/20200530.md)
 * [2020 Feb 29](ChangeLog/20200229.md)
 * [2019 Aug 30](ChangeLog/20190830.md)
 
 ## When is the next Breaking Change?
 
-The next Breaking Change is scheduled for May 30, 2020.
+The next Breaking Change is scheduled for August 28, 2021.
 
 ### Important Dates
 
-* [x] 2020 Feb 29 - `future` is created. It will be rebased weekly.
-* [ ] 2020 May 2 - `future` closed to new PR's.
-* [ ] 2020 May 2 - Call for testers.
-* [ ] 2020 May 28 - `master` is locked, no PR's merged.
-* [ ] 2020 May 30 - Merge `future` to `master`.
-* [ ] 2020 May 30 - `master` is unlocked. PR's can be merged again.
+* [x] 2021 May 29 - `develop` is created. Each push to `master` is subsequently merged to `develop`
+* [ ] 2021 Jul 31 - `develop` closed to new PR's.
+* [ ] 2021 Jul 31 - Call for testers.
+* [ ] 2021 Aug 26 - `master` is locked, no PR's merged.
+* [ ] 2021 Aug 28 - Merge `develop` to `master`.
+* [ ] 2021 Aug 28 - `master` is unlocked. PR's can be merged again.
 
 ## What changes will be included?
 
-To see a list of breaking change candidates you can look at the [`breaking_change` label](https://github.com/qmk/qmk_firmware/pulls?q=is%3Aopen+label%3Abreaking_change+is%3Apr). New changes might be added between now and when `future` is closed, and a PR with that label applied is not guaranteed to be merged.
+To see a list of breaking change candidates you can look at the [`breaking_change` label](https://github.com/qmk/qmk_firmware/pulls?q=is%3Aopen+label%3Abreaking_change+is%3Apr). New changes might be added between now and when `develop` is closed, and a PR with that label applied is not guaranteed to be merged.
 
-If you want your breaking change to be included in this round you need to create a PR with the `breaking_change` label and have it accepted before `future` closes. After `future` closes no new breaking changes will be accepted.
+If you want your breaking change to be included in this round you need to create a PR with the `breaking_change` label and have it accepted before `develop` closes. After `develop` closes no new breaking changes will be accepted.
 
 Criteria for acceptance:
 
@@ -37,41 +42,26 @@ Criteria for acceptance:
 
 This section documents various processes we use when running the Breaking Changes process.
 
-## Rebase `future` from `master`
+## Creating the `develop` branch
 
-This is run every Friday while `future` is open.
-
-Process:
-
-```
-cd qmk_firmware
-git checkout master
-git pull --ff-only
-git checkout future
-git rebase master
-git push --force
-```
-
-## Creating the `future` branch
-
-This happens immediately after the previous `future` branch is merged.
+This happens immediately after the previous `develop` branch is merged.
 
 * `qmk_firmware` git commands
     * [ ] `git checkout master`
     * [ ] `git pull --ff-only`
-    * [ ] `git checkout -b future`
+    * [ ] `git checkout -b develop`
     * [ ] Edit `readme.md`
         * [ ] Add a big notice at the top that this is a testing branch.
         * [ ] Include a link to this document
     * [ ] `git commit -m 'Branch point for <DATE> Breaking Change'`
     * [ ] `git tag breakpoint_<YYYY>_<MM>_<DD>`
     * [ ] `git tag <next_version>` # Prevent the breakpoint tag from confusing version incrementing
-    * [ ] `git push origin future`
+    * [ ] `git push origin develop`
     * [ ] `git push --tags`
 
 ## 4 Weeks Before Merge
 
-* `future` is now closed to new PR's, only fixes for current PR's may be merged
+* `develop` is now closed to new PR's, only fixes for current PR's may be merged
 * Post call for testers
     * [ ] Discord
     * [ ] GitHub PR
@@ -94,15 +84,15 @@ This happens immediately after the previous `future` branch is merged.
 ## Day Of Merge
 
 * `qmk_firmware` git commands
-    * [ ] `git checkout future`
+    * [ ] `git checkout develop`
     * [ ] `git pull --ff-only`
     * [ ] `git rebase origin/master`
     * [ ] Edit `readme.md`
-        * [ ] Remove the notes about `future`
+        * [ ] Remove the notes about `develop`
     * [ ] Roll up the ChangeLog into one file.
     * [ ] `git commit -m 'Merge point for <DATE> Breaking Change'`
-    * [ ] `git push origin future`
-* Github Actions
-    * [ ] Create a PR for `future`
+    * [ ] `git push origin develop`
+* GitHub Actions
+    * [ ] Create a PR for `develop`
     * [ ] Make sure travis comes back clean
-    * [ ] Merge `future` PR
+    * [ ] Merge `develop` PR

docs/breaking_changes_history.md

@@ -0,0 +1,11 @@
+# Past Breaking Changes
+
+This page links to all previous changelogs from the QMK Breaking Changes process.
+
+* [2021 May 29](ChangeLog/20210529.md) - version 0.13.0
+* [2021 Feb 27](ChangeLog/20210227.md) - version 0.12.0
+* [2020 Nov 28](ChangeLog/20201128.md) - version 0.11.0
+* [2020 Aug 29](ChangeLog/20200829.md) - version 0.10.0
+* [2020 May 30](ChangeLog/20200530.md) - version 0.9.0
+* [2020 Feb 29](ChangeLog/20200229.md) - version 0.8.0
+* [2019 Aug 30](ChangeLog/20190830.md) - version 0.7.0

docs/breaking_changes_instructions.md

@@ -27,7 +27,7 @@ If you are contributing core code, and the only reason it needs to go through br
 
 We require submissions that go through the Breaking Change process to include a changelog entry. The entry should be a short summary of the changes your pull request makes – [each section here started as a changelog](ChangeLog/20190830.md "n.b. This should link to the 2019 Aug 30 Breaking Changes doc  - @noroadsleft").
 
-Your changelog should be located at `docs/ChangeLog/YYYYMMDD/PR####.md`, where `YYYYMMDD` is the date on which QMK's breaking change branch – usually named `future` – will be merged into the `master` branch, and `####` is the number of your pull request.
+Your changelog should be located at `docs/ChangeLog/YYYYMMDD/PR####.md`, where `YYYYMMDD` is the date on which QMK's breaking change branch – usually named `develop` – will be merged into the `master` branch, and `####` is the number of your pull request.
 
 If your submission requires action on the part of users, your changelog should instruct users what action(s) must be taken, or link to a location that does so.
 

docs/cli.md

@@ -6,25 +6,24 @@ The QMK CLI makes building and working with QMK keyboards easier. We have provid
 
 ### Requirements :id=requirements
 
-The CLI requires Python 3.5 or greater. We try to keep the number of requirements small but you will also need to install the packages listed in [`requirements.txt`](https://github.com/qmk/qmk_firmware/blob/master/requirements.txt). These are installed automatically when you install the QMK CLI.
+QMK requires Python 3.6 or greater. We try to keep the number of requirements small but you will also need to install the packages listed in [`requirements.txt`](https://github.com/qmk/qmk_firmware/blob/master/requirements.txt). These are installed automatically when you install the QMK CLI.
 
 ### Install Using Homebrew (macOS, some Linux) :id=install-using-homebrew
 
 If you have installed [Homebrew](https://brew.sh) you can tap and install QMK:
 
 ```
-brew tap qmk/qmk
-brew install qmk
+brew install qmk/qmk/qmk
 export QMK_HOME='~/qmk_firmware' # Optional, set the location for `qmk_firmware`
 qmk setup  # This will clone `qmk/qmk_firmware` and optionally set up your build environment
 ```
 
-### Install Using easy_install or pip :id=install-using-easy_install-or-pip
+### Install Using pip :id=install-using-easy_install-or-pip
 
-If your system is not listed above you can install QMK manually. First ensure that you have python 3.5 (or later) installed and have installed pip. Then install QMK with this command:
+If your system is not listed above you can install QMK manually. First ensure that you have Python 3.6 (or later) installed and have installed pip. Then install QMK with this command:
 
 ```
-pip3 install qmk
+python3 -m pip install qmk
 export QMK_HOME='~/qmk_firmware' # Optional, set the location for `qmk_firmware`
 qmk setup  # This will clone `qmk/qmk_firmware` and optionally set up your build environment
 ```

docs/cli_commands.md

@@ -1,53 +1,23 @@
 # QMK CLI Commands
 
-# CLI Commands
-
-## `qmk cformat`
-
-This command formats C code using clang-format. 
-
-Run it with no arguments to format all core code that has been changed. Default checks `origin/master` with `git diff`, branch can be changed using `-b <branch_name>`
-
-Run it with `-a` to format all core code, or pass filenames on the command line to run it on specific files.
-
-**Usage for specified files**:
-
-```
-qmk cformat [file1] [file2] [...] [fileN]
-```
-
-**Usage for all core files**:
-
-```
-qmk cformat -a
-```
-
-**Usage for only changed files against origin/master**:
-
-```
-qmk cformat
-```
-
-**Usage for only changed files against branch_name**:
-
-```
-qmk cformat -b branch_name
-```
+# User Commands
 
 ## `qmk compile`
 
 This command allows you to compile firmware from any directory. You can compile JSON exports from <https://config.qmk.fm>, compile keymaps in the repo, or compile the keyboard in the current working directory.
 
+This command is directory aware. It will automatically fill in KEYBOARD and/or KEYMAP if you are in a keyboard or keymap directory.
+
 **Usage for Configurator Exports**:
 
 ```
-qmk compile <configuratorExport.json>
+qmk compile [-c] <configuratorExport.json>
 ```
 
 **Usage for Keymaps**:
 
 ```
-qmk compile -kb <keyboard_name> -km <keymap_name>
+qmk compile [-c] [-e <var>=<value>] -kb <keyboard_name> -km <keymap_name>
 ```
 
 **Usage in Keyboard Directory**:  
@@ -105,19 +75,20 @@ $ qmk compile -kb dz60
 
 ## `qmk flash`
 
-This command is similar to `qmk compile`, but can also target a bootloader. The bootloader is optional, and is set to `:flash` by default.
-To specify a different bootloader, use `-bl <bootloader>`. Visit the [Flashing Firmware](flashing.md) guide for more details of the available bootloaders.
+This command is similar to `qmk compile`, but can also target a bootloader. The bootloader is optional, and is set to `:flash` by default. To specify a different bootloader, use `-bl <bootloader>`. Visit the [Flashing Firmware](flashing.md) guide for more details of the available bootloaders.
+
+This command is directory aware. It will automatically fill in KEYBOARD and/or KEYMAP if you are in a keyboard or keymap directory.
 
 **Usage for Configurator Exports**:
 
 ```
-qmk flash <configuratorExport.json> -bl <bootloader>
+qmk flash [-bl <bootloader>] [-c] [-e <var>=<value>] <configuratorExport.json>
 ```
 
 **Usage for Keymaps**:
 
 ```
-qmk flash -kb <keyboard_name> -km <keymap_name> -bl <bootloader>
+qmk flash -kb <keyboard_name> -km <keymap_name> [-bl <bootloader>] [-c] [-e <var>=<value>]
 ```
 
 **Listing the Bootloaders**
@@ -136,14 +107,52 @@ This command lets you configure the behavior of QMK. For the full `qmk config` d
 qmk config [-ro] [config_token1] [config_token2] [...] [config_tokenN]
 ```
 
-## `qmk docs`
+## `qmk console`
 
-This command starts a local HTTP server which you can use for browsing or improving the docs. Default port is 8936.
+This command lets you connect to keyboard consoles to get debugging messages. It only works if your keyboard firmware has been compiled with `CONSOLE_ENABLED=yes`.
 
 **Usage**:
 
 ```
-qmk docs [-p PORT]
+qmk console [-d <pid>:<vid>[:<index>]] [-l] [-n] [-t] [-w <seconds>]
+```
+
+**Examples**:
+
+Connect to all available keyboards and show their console messages:
+
+```
+qmk console
+```
+
+List all devices:
+
+```
+qmk console -l
+```
+
+Show only messages from clueboard/66/rev3 keyboards:
+
+```
+qmk console -d C1ED:2370
+```
+
+Show only messages from the second clueboard/66/rev3:
+
+```
+qmk console -d C1ED:2370:2
+```
+
+Show timestamps and VID:PID instead of names:
+
+```
+qmk console -n -t
+```
+
+Disable bootloader messages:
+
+```
+qmk console --no-bootloaders
 ```
 
 ## `qmk doctor`
@@ -170,6 +179,42 @@ Check your environment and report problems only:
 
     qmk doctor -n
 
+## `qmk format-json`
+
+Formats a JSON file in a (mostly) human-friendly way. Will usually correctly detect the format of the JSON (info.json or keymap.json) but you can override this with `--format` if neccesary.
+
+**Usage**:
+
+```
+qmk format-json [-f FORMAT] <json_file>
+```
+
+## `qmk info`
+
+Displays information about keyboards and keymaps in QMK. You can use this to get information about a keyboard, show the layouts, display the underlying key matrix, or to pretty-print JSON keymaps.
+
+**Usage**:
+
+```
+qmk info [-f FORMAT] [-m] [-l] [-km KEYMAP] [-kb KEYBOARD]
+```
+
+This command is directory aware. It will automatically fill in KEYBOARD and/or KEYMAP if you are in a keyboard or keymap directory.
+
+**Examples**:
+
+Show basic information for a keyboard:
+
+    qmk info -kb planck/rev5
+
+Show the matrix for a keyboard:
+
+    qmk info -kb ergodox_ez -m
+
+Show a JSON keymap for a keyboard:
+
+    qmk info -kb clueboard/california -km default
+
 ## `qmk json2c`
 
 Creates a keymap.c from a QMK Configurator export.
@@ -180,6 +225,157 @@ Creates a keymap.c from a QMK Configurator export.
 qmk json2c [-o OUTPUT] filename
 ```
 
+## `qmk c2json`
+
+Creates a keymap.json from a keymap.c.  
+**Note:** Parsing C source files is not easy, therefore this subcommand may not work with your keymap. In some cases not using the C pre-processor helps.
+
+**Usage**:
+
+```
+qmk c2json -km KEYMAP -kb KEYBOARD [-q] [--no-cpp] [-o OUTPUT] filename
+```
+
+## `qmk lint`
+
+Checks over a keyboard and/or keymap and highlights common errors, problems, and anti-patterns.
+
+**Usage**:
+
+```
+qmk lint [-km KEYMAP] [-kb KEYBOARD] [--strict]
+```
+
+This command is directory aware. It will automatically fill in KEYBOARD and/or KEYMAP if you are in a keyboard or keymap directory.
+
+**Examples**:
+
+Do a basic lint check:
+
+    qmk lint -kb rominronin/katana60/rev2
+
+## `qmk list-keyboards`
+
+This command lists all the keyboards currently defined in `qmk_firmware`
+
+**Usage**:
+
+```
+qmk list-keyboards
+```
+
+## `qmk list-keymaps`
+
+This command lists all the keymaps for a specified keyboard (and revision).
+
+This command is directory aware. It will automatically fill in KEYBOARD if you are in a keyboard directory.
+
+**Usage**:
+
+```
+qmk list-keymaps -kb planck/ez
+```
+
+## `qmk new-keyboard`
+
+This command creates a new keyboard based on available templates.
+
+This command will prompt for input to guide you though the generation process.
+
+**Usage**:
+
+```
+qmk new-keyboard
+```
+
+## `qmk new-keymap`
+
+This command creates a new keymap based on a keyboard's existing default keymap.
+
+This command is directory aware. It will automatically fill in KEYBOARD and/or KEYMAP if you are in a keyboard or keymap directory.
+
+**Usage**:
+
+```
+qmk new-keymap [-kb KEYBOARD] [-km KEYMAP]
+```
+
+## `qmk clean`
+
+This command cleans up the `.build` folder. If `--all` is passed, any .hex or .bin files present in the `qmk_firmware` directory will also be deleted.
+
+**Usage**:
+
+```
+qmk clean [-a]
+```
+
+---
+
+# Developer Commands
+
+## `qmk cformat`
+
+This command formats C code using clang-format. 
+
+Run it with no arguments to format all core code that has been changed. Default checks `origin/master` with `git diff`, branch can be changed using `-b <branch_name>`
+
+Run it with `-a` to format all core code, or pass filenames on the command line to run it on specific files.
+
+**Usage for specified files**:
+
+```
+qmk cformat [file1] [file2] [...] [fileN]
+```
+
+**Usage for all core files**:
+
+```
+qmk cformat -a
+```
+
+**Usage for only changed files against origin/master**:
+
+```
+qmk cformat
+```
+
+**Usage for only changed files against branch_name**:
+
+```
+qmk cformat -b branch_name
+```
+
+## `qmk docs`
+
+This command starts a local HTTP server which you can use for browsing or improving the docs. Default port is 8936.
+
+**Usage**:
+
+```
+qmk docs [-p PORT]
+```
+
+## `qmk generate-docs`
+
+This command allows you to generate QMK documentation locally. It can be uses for general browsing or improving the docs. External tools such as [serve](https://www.npmjs.com/package/serve) can be used to browse the generated files.
+
+**Usage**:
+
+```
+qmk generate-docs
+```
+
+## `qmk generate-rgb-breathe-table`
+
+This command generates a lookup table (LUT) header file for the [RGB Lighting](feature_rgblight.md) feature's breathing animation. Place this file in your keyboard or keymap directory as `rgblight_breathe_table.h` to override the default LUT in `quantum/`.
+
+**Usage**:
+
+```
+qmk generate-rgb-breathe-table [-q] [-o OUTPUT] [-m MAX] [-c CENTER]
+```
+
 ## `qmk kle2json`
 
 This command allows you to convert from raw KLE data to QMK Configurator JSON. It accepts either an absolute file path, or a file name in the current directory. By default it will not overwrite `info.json` if it is already present. Use the `-f` or `--force` flag to overwrite.
@@ -202,36 +398,6 @@ $ qmk kle2json -f kle.txt -f
 Ψ Wrote out to info.json
 ```
 
-## `qmk list-keyboards`
-
-This command lists all the keyboards currently defined in `qmk_firmware`
-
-**Usage**:
-
-```
-qmk list-keyboards
-```
-
-## `qmk list-keymaps`
-
-This command lists all the keymaps for a specified keyboard (and revision).
-
-**Usage**:
-
-```
-qmk list-keymaps -kb planck/ez
-```
-
-## `qmk new-keymap`
-
-This command creates a new keymap based on a keyboard's existing default keymap.
-
-**Usage**:
-
-```
-qmk new-keymap [-kb KEYBOARD] [-km KEYMAP]
-```
-
 ## `qmk pyformat`
 
 This command formats python code in `qmk_firmware`.

docs/cli_configuration.md

@@ -108,7 +108,7 @@ compile.keymap: skully -> None
 |-----|---------------|-------------|
 | user.keyboard | None | The keyboard path (Example: `clueboard/66/rev4`) |
 | user.keymap | None | The keymap name (Example: `default`) |
-| user.name | None | The user's github username. |
+| user.name | None | The user's GitHub username. |
 
 # All Configuration Options
 

docs/cli_development.md

@@ -6,6 +6,18 @@ This document has useful information for developers wishing to write new `qmk` s
 
 The QMK CLI operates using the subcommand pattern made famous by git. The main `qmk` script is simply there to setup the environment and pick the correct entrypoint to run. Each subcommand is a self-contained module with an entrypoint (decorated by `@cli.subcommand()`) that performs some action and returns a shell returncode, or None.
 
+## Developer mode:
+
+If you intend to maintain keyboards and/or contribute to QMK, you can enable the CLI's "Developer" mode:
+
+`qmk config user.developer=True`
+
+This will allow you to see all available subcommands.  
+**Note:** You will have to install additional requirements:  
+```bash
+python3 -m pip install -r requirements-dev.txt
+```
+
 # Subcommands
 
 [MILC](https://github.com/clueboard/milc) is the CLI framework `qmk` uses to handle argument parsing, configuration, logging, and many other features. It lets you focus on writing your tool without wasting your time writing glue code.
@@ -32,7 +44,7 @@ def hello(cli):
 
 First we import the `cli` object from `milc`. This is how we interact with the user and control the script's behavior. We use `@cli.argument()` to define a command line flag, `--name`. This also creates a configuration variable named `hello.name` (and the corresponding `user.name`) which the user can set so they don't have to specify the argument. The `cli.subcommand()` decorator designates this function as a subcommand. The name of the subcommand will be taken from the name of the function.
 
-Once inside our function we find a typical "Hello, World!" program. We use `cli.log` to access the underlying [Logger Object](https://docs.python.org/3.5/library/logging.html#logger-objects), whose behavior is user controllable. We also access the value for name supplied by the user as `cli.config.hello.name`. The value for `cli.config.hello.name` will be determined by looking at the `--name` argument supplied by the user, if not provided it will use the value in the `qmk.ini` config file, and if neither of those is provided it will fall back to the default supplied in the `cli.argument()` decorator.
+Once inside our function we find a typical "Hello, World!" program. We use `cli.log` to access the underlying [Logger Object](https://docs.python.org/3.6/library/logging.html#logger-objects), whose behavior is user controllable. We also access the value for name supplied by the user as `cli.config.hello.name`. The value for `cli.config.hello.name` will be determined by looking at the `--name` argument supplied by the user, if not provided it will use the value in the `qmk.ini` config file, and if neither of those is provided it will fall back to the default supplied in the `cli.argument()` decorator.
 
 # User Interaction
 
@@ -44,13 +56,13 @@ There are two main methods for outputting text in a subcommand- `cli.log` and `c
 
 You can use special tokens to colorize your text, to make it easier to understand the output of your program. See [Colorizing Text](#colorizing-text) below.
 
-Both of these methods support built-in string formatting using python's [printf style string format operations](https://docs.python.org/3.5/library/stdtypes.html#old-string-formatting). You can use tokens such as `%s` and `%d` within your text strings then pass the values as arguments. See our Hello, World program above for an example.
+Both of these methods support built-in string formatting using python's [printf style string format operations](https://docs.python.org/3.6/library/stdtypes.html#old-string-formatting). You can use tokens such as `%s` and `%d` within your text strings then pass the values as arguments. See our Hello, World program above for an example.
 
 You should never use the format operator (`%`) directly, always pass values as arguments.
 
 ### Logging (`cli.log`)
 
-The `cli.log` object gives you access to a [Logger Object](https://docs.python.org/3.5/library/logging.html#logger-objects). We have configured our log output to show the user a nice emoji for each log level (or the log level name if their terminal does not support unicode.) This way the user can tell at a glance which messages are most important when something goes wrong.
+The `cli.log` object gives you access to a [Logger Object](https://docs.python.org/3.6/library/logging.html#logger-objects). We have configured our log output to show the user a nice emoji for each log level (or the log level name if their terminal does not support unicode.) This way the user can tell at a glance which messages are most important when something goes wrong.
 
 The default log level is `INFO`. If the user runs `qmk -v <subcommand>` the default log level will be set to `DEBUG`.
 
@@ -198,7 +210,7 @@ Our tests can be found in `lib/python/qmk/tests/`. You will find both unit and i
 
 If your PR does not include a comprehensive set of tests please add comments like this to your code so that other people know where they can help:
 
-    # TODO(unassigned/<yourGithubUsername>): Write <unit|integration> tests
+    # TODO(unassigned/<your_github_username>): Write <unit|integration> tests
 
 We use [nose2](https://nose2.readthedocs.io/en/latest/getting_started.html) to run our tests. You can refer to the nose2 documentation for more details on what you can do in your test functions.
 

docs/cli_tab_complete.md

@@ -0,0 +1,27 @@
+# Tab Completion for QMK
+
+If you are using Bash 4.2 or later, Zsh, or FiSH you can enable Tab Completion for the QMK CLI. This will let you tab complete the names of flags, keyboards, files, and other `qmk` options.
+
+## Setup
+
+There are several ways you can setup tab completion.
+
+### For Your User Only
+
+Add this to the end of your `.profile` or `.bashrc`:
+
+    source ~/qmk_firmware/util/qmk_tab_complete.sh
+
+If you put `qmk_firmware` into another location you will need to adjust this path.
+
+### System Wide Symlink
+
+If you want the tab completion available to all users of the system you can add a symlink to the `qmk_tab_complete.sh` script:
+
+    `ln -s ~/qmk_firmware/util/qmk_tab_complete.sh /etc/profile.d/qmk_tab_complete.sh`
+
+### System Wide Copy
+
+In some cases a symlink may not work. Instead you can copy the file directly into place. Be aware that updates to the tab complete script may happen from time to time, you will want to recopy the file periodically.
+
+    cp util/qmk_tab_complete.sh /etc/profile.d

docs/coding_conventions_c.md

@@ -20,11 +20,11 @@ Most of our style is pretty easy to pick up on, but right now it's not entirely
 * We accept both forms of preprocessor if's: `#ifdef DEFINED` and `#if defined(DEFINED)`
   * If you are not sure which to prefer use the `#if defined(DEFINED)` form.
   * Do not change existing code from one style to the other, except when moving to a multiple condition `#if`.
-  * Do not put whitespace between `#` and `if`.
-  * When deciding how (or if) to indent directives keep these points in mind:
-    * Readability is more important than consistency.
-    * Follow the file's existing style. If the file is mixed follow the style that makes sense for the section you are modifying.
-    * When choosing to indent you can follow the indention level of the surrounding C code, or preprocessor directives can have their own indent level. Choose the style that best communicates the intent of your code.
+* When deciding how (or if) to indent preprocessor directives, keep these points in mind:
+  * Readability is more important than consistency.
+  * Follow the file's existing style. If the file is mixed, follow the style that makes sense for the section you are modifying.
+  * When indenting, keep the hash at the start of the line and add whitespace between `#` and `if`, starting with 4 spaces after the `#`.
+  * You can follow the indention level of the surrounding C code, or preprocessor directives can have their own indentation levels. Choose the style that best communicates the intent of your code.
 
 Here is an example for easy reference:
 
@@ -49,7 +49,7 @@ int foo(void) {
 
 [Clang-format](https://clang.llvm.org/docs/ClangFormat.html) is part of LLVM and can automatically format your code for you, because ain't nobody got time to do it manually. We supply a configuration file for it that applies most of the coding conventions listed above. It will only change whitespace and newlines, so you will still have to remember to include optional braces yourself.
 
-Use the [full LLVM installer](http://llvm.org/builds/) to get clang-format on Windows, or use `sudo apt install clang-format` on Ubuntu.
+Use the [full LLVM installer](https://llvm.org/builds/) to get clang-format on Windows, or use `sudo apt install clang-format` on Ubuntu.
 
 If you run it from the command-line, pass `-style=file` as an option and it will automatically find the .clang-format configuration file in the QMK root directory.
 

docs/coding_conventions_python.md

@@ -2,7 +2,7 @@
 
 Most of our style follows PEP8 with some local modifications to make things less nit-picky. 
 
-* We target Python 3.5 for compatability with all supported platforms.
+* We target Python 3.6 for compatability with all supported platforms.
 * We indent using four (4) spaces (soft tabs)
 * We encourage liberal use of comments
   * Think of them as a story describing the feature
@@ -317,7 +317,7 @@ At the time of this writing our tests are not very comprehensive. Looking at the
 
 ## Integration Tests
 
-Integration tests can be found in `lib/python/qmk/tests/test_cli_commands.py`. This is where CLI commands are actually run and their overall behavior is verified. We use [`subprocess`](https://docs.python.org/3.5/library/subprocess.html#module-subprocess) to launch each CLI command and a combination of checking output and returncode to determine if the right thing happened.
+Integration tests can be found in `lib/python/qmk/tests/test_cli_commands.py`. This is where CLI commands are actually run and their overall behavior is verified. We use [`subprocess`](https://docs.python.org/3.6/library/subprocess.html#module-subprocess) to launch each CLI command and a combination of checking output and returncode to determine if the right thing happened.
 
 ## Unit Tests
 

docs/compatible_microcontrollers.md

@@ -9,21 +9,30 @@ The following use [LUFA](https://www.fourwalledcubicle.com/LUFA.php) as the USB
 * [ATmega16U2](https://www.microchip.com/wwwproducts/en/ATmega16U2) / [ATmega32U2](https://www.microchip.com/wwwproducts/en/ATmega32U2)
 * [ATmega16U4](https://www.microchip.com/wwwproducts/en/ATmega16U4) / [ATmega32U4](https://www.microchip.com/wwwproducts/en/ATmega32U4)
 * [AT90USB64](https://www.microchip.com/wwwproducts/en/AT90USB646) / [AT90USB128](https://www.microchip.com/wwwproducts/en/AT90USB1286)
+* [AT90USB162](https://www.microchip.com/wwwproducts/en/AT90USB162)
 
 Certain MCUs which do not have native USB will use [V-USB](https://www.obdev.at/products/vusb/index.html) instead:
 
 * [ATmega32A](https://www.microchip.com/wwwproducts/en/ATmega32A)
 * [ATmega328P](https://www.microchip.com/wwwproducts/en/ATmega328P)
+* [ATmega328](https://www.microchip.com/wwwproducts/en/ATmega328)
 
 ## ARM
 
-You can also use any ARM chip with USB that [ChibiOS](http://www.chibios.org) supports. Most have plenty of flash. Known to work are:
+You can also use any ARM chip with USB that [ChibiOS](https://www.chibios.org) supports. Most have plenty of flash. Known to work are:
 
 ### STMicroelectronics (STM32)
 
  * [STM32F0x2](https://www.st.com/en/microcontrollers-microprocessors/stm32f0x2.html)
  * [STM32F103](https://www.st.com/en/microcontrollers-microprocessors/stm32f103.html)
  * [STM32F303](https://www.st.com/en/microcontrollers-microprocessors/stm32f303.html)
+ * [STM32F401](https://www.st.com/en/microcontrollers-microprocessors/stm32f401.html)
+ * [STM32F411](https://www.st.com/en/microcontrollers-microprocessors/stm32f411.html)
+ * [STM32F446](https://www.st.com/en/microcontrollers-microprocessors/stm32f446.html)
+ * [STM32G431](https://www.st.com/en/microcontrollers-microprocessors/stm32g4x1.html)
+ * [STM32G474](https://www.st.com/en/microcontrollers-microprocessors/stm32g4x4.html)
+ * [STM32L433](https://www.st.com/en/microcontrollers-microprocessors/stm32l4x3.html)
+ * [STM32L443](https://www.st.com/en/microcontrollers-microprocessors/stm32l4x3.html)
 
 ### NXP (Kinetis)
 

docs/config_options.md

@@ -29,7 +29,9 @@ This level contains all of the options for that particular keymap. If you wish t
 
 This is a C header file that is one of the first things included, and will persist over the whole project (if included). Lots of variables can be set here and accessed elsewhere. The `config.h` file shouldn't be including other `config.h` files, or anything besides this:
 
-    #include "config_common.h"
+```c
+#include "config_common.h"
+```
 
 
 ## Hardware Options
@@ -43,8 +45,6 @@ This is a C header file that is one of the first things included, and will persi
   * generally who/whatever brand produced the board
 * `#define PRODUCT Board`
   * the name of the keyboard
-* `#define DESCRIPTION a keyboard`
-  * a short description of what the keyboard is
 * `#define MATRIX_ROWS 5`
   * the number of rows in your keyboard's matrix
 * `#define MATRIX_COLS 15`
@@ -67,16 +67,22 @@ This is a C header file that is one of the first things included, and will persi
   * turns on the alternate audio voices (to cycle through)
 * `#define C4_AUDIO`
   * enables audio on pin C4
+  * Deprecated. Use `#define AUDIO_PIN C4`
 * `#define C5_AUDIO`
   * enables audio on pin C5
+  * Deprecated. Use `#define AUDIO_PIN C5`
 * `#define C6_AUDIO`
   * enables audio on pin C6
+  * Deprecated. Use `#define AUDIO_PIN C6`
 * `#define B5_AUDIO`
-  * enables audio on pin B5 (duophony is enables if one of B[5-7]\_AUDIO is enabled along with one of C[4-6]\_AUDIO)
+  * enables audio on pin B5 (duophony is enabled if one of B pins is enabled along with one of C pins)
+  * Deprecated. Use `#define AUDIO_PIN B5`, or use `#define AUDIO_PIN_ALT B5` if a `C` pin is enabled with `AUDIO_PIN`
 * `#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)
+  * enables audio on pin B6 (duophony is enabled if one of B pins is enabled along with one of C pins)
+  * Deprecated. Use `#define AUDIO_PIN B6`, or use `#define AUDIO_PIN_ALT B6` if a `C` pin is enabled with `AUDIO_PIN`
 * `#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)
+  * enables audio on pin B7 (duophony is enabled if one of B pins is enabled along with one of C pins)
+  * Deprecated. Use `#define AUDIO_PIN B7`, or use `#define AUDIO_PIN_ALT B7` if a `C` pin is enabled with `AUDIO_PIN`
 * `#define BACKLIGHT_PIN B7`
   * pin of the backlight
 * `#define BACKLIGHT_LEVELS 3`
@@ -97,6 +103,8 @@ This is a C header file that is one of the first things included, and will persi
   * sets the maximum power (in mA) over USB for the device (default: 500)
 * `#define USB_POLLING_INTERVAL_MS 10`
   * sets the USB polling rate in milliseconds for the keyboard, mouse, and shared (NKRO/media keys) interfaces
+* `#define USB_SUSPEND_WAKEUP_DELAY 200`
+  * set the number of milliseconde to pause after sending a wakeup packet
 * `#define F_SCL 100000L`
   * sets the I2C clock rate speed for keyboards using I2C. The default is `400000L`, except for keyboards using `split_common`, where the default is `100000L`.
 
@@ -115,9 +123,9 @@ 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 old style macro handling: MACRO() & action_get_macro
+  * disable old-style macro handling using `MACRO()`, `action_get_macro()` _(deprecated)_
 * `#define NO_ACTION_FUNCTION`
-  * disable calling of action_function() from the fn_actions array (deprecated)
+  * disable old-style function handling using `fn_actions`, `action_function()` _(deprecated)_
 
 ## Features That Can Be Enabled
 
@@ -137,6 +145,8 @@ If you define these options you will enable the associated feature, which may in
 * `#define RETRO_TAPPING`
   * tap anyway, even after TAPPING_TERM, if there was no other key interruption between press and release
   * See [Retro Tapping](tap_hold.md#retro-tapping) for details
+* `#define RETRO_TAPPING_PER_KEY`
+  * enables handling for per key `RETRO_TAPPING` settings
 * `#define TAPPING_TOGGLE 2`
   * how many taps before triggering the toggle
 * `#define PERMISSIVE_HOLD`
@@ -191,7 +201,14 @@ If you define these options you will enable the associated feature, which may in
 * `#define RGBLIGHT_ANIMATIONS`
   * run RGB animations
 * `#define RGBLIGHT_LAYERS`
-  * Lets you define [lighting layers](feature_rgblight.md) that can be toggled on or off. Great for showing the current keyboard layer or caps lock state.
+  * Lets you define [lighting layers](feature_rgblight.md?id=lighting-layers) that can be toggled on or off. Great for showing the current keyboard layer or caps lock state.
+* `#define RGBLIGHT_MAX_LAYERS`
+  * Defaults to 8. Can be expanded up to 32 if more [lighting layers](feature_rgblight.md?id=lighting-layers) are needed.
+  * Note: Increasing the maximum will increase the firmware size and slow sync on split keyboards.
+* `#define RGBLIGHT_LAYER_BLINK` 
+  * Adds ability to [blink](feature_rgblight.md?id=lighting-layer-blink) a lighting layer for a specified number of milliseconds (e.g. to acknowledge an action).
+* `#define RGBLIGHT_LAYERS_OVERRIDE_RGB_OFF`
+  * If defined, then [lighting layers](feature_rgblight?id=overriding-rgb-lighting-onoff-status) will be shown even if RGB Light is off.
 * `#define RGBLED_NUM 12`
   * number of LEDs
 * `#define RGBLIGHT_SPLIT`
@@ -243,7 +260,10 @@ There are a few different ways to set handedness for split keyboards (listed in
 * `#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)
+* `#define SPLIT_HAND_MATRIX_GRID <out_pin>,<in_pin>`
+  * The handedness is determined by using the intersection of the keyswitches in the key matrix, which does not exist. Normally, when this intersection is shorted (level low), it is considered left. If you define `#define SPLIT_HAND_MATRIX_GRID_LOW_IS_RIGHT`, it is determined to be right when the level is low.
+
+* `#define EE_HANDS` (only works if `SPLIT_HAND_PIN` and `SPLIT_HAND_MATRIX_GRID` are 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`
@@ -316,11 +336,9 @@ This is a [make](https://www.gnu.org/software/make/manual/make.html) file that i
     ```
 * `LAYOUTS`
   * A list of [layouts](feature_layouts.md) this keyboard supports.
-* `LINK_TIME_OPTIMIZATION_ENABLE`
-  * Enables Link Time Optimization (`LTO`) when compiling the keyboard.  This makes the process take longer, but can significantly reduce the compiled size (and since the firmware is small, the added time is not noticeable).  However, this will automatically disable the old Macros and Functions features automatically, as these break when `LTO` is enabled.
-  It does this by automatically defining `NO_ACTION_MACRO` and `NO_ACTION_FUNCTION`
 * `LTO_ENABLE`
-  * It has the same meaning as LINK_TIME_OPTIMIZATION_ENABLE.  You can use `LTO_ENABLE` instead of `LINK_TIME_OPTIMIZATION_ENABLE`.
+  * Enables Link Time Optimization (LTO) when compiling the keyboard.  This makes the process take longer, but it can significantly reduce the compiled size (and since the firmware is small, the added time is not noticeable).
+However, this will automatically disable the legacy TMK Macros and Functions features, as these break when LTO is enabled.  It does this by automatically defining `NO_ACTION_MACRO` and `NO_ACTION_FUNCTION`.  (Note: This does not affect QMK [Macros](feature_macros.md) and [Layers](feature_layers.md).)
 
 ## AVR MCU Options
 * `MCU = atmega32u4`
@@ -365,10 +383,8 @@ Use these to enable or disable building certain features. The more you have enab
   * MIDI controls
 * `UNICODE_ENABLE`
   * Unicode
-* `BLUETOOTH_ENABLE`
-  * Legacy option to Enable Bluetooth with the Adafruit EZ-Key HID. See BLUETOOTH
 * `BLUETOOTH`
-  * Current options are AdafruitEzKey, AdafruitBLE, RN42
+  * Current options are 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`

docs/configurator_default_keymaps.md

@@ -0,0 +1,193 @@
+# Adding Default Keymaps to QMK Configurator :id=adding-default-keymaps
+
+This page covers how to add a default keymap for a keyboard to QMK Configurator.
+
+
+## Technical Information :id=technical-information
+
+QMK Configurator uses JSON as its native file format for keymaps. As much as possible, these should be kept such that they behave the same as running `make <keyboard>:default` from `qmk_firmware`.
+
+Keymaps in this directory require four key-value pairs:
+
+* `keyboard` (string)
+  * This is the name of the keyboard, the same as would be used when running a compile job through `make` (e.g. `make 1upkeyboards/1up60rgb:default`).
+* `keymap` (string)
+  * Should be set to `default`.
+* `layout` (string)
+  * This is the layout macro used by the default keymap.
+* `layers` (array)
+  * The keymap itself. This key should contain one array per layer, which themselves should contain the keycodes that make up that layer.
+
+Additionally, most keymaps contain a `commit` key. This key is not consumed by the API that back-stops QMK Configurator, but is used by Configurator's maintainers to tell which version of a keymap was used to create the JSON keymap in this repository. The value is the SHA of the last commit to modify a board's default `keymap.c` in the `qmk_firmware` repository. The SHA is found by checking out [the `master` branch of the `qmk/qmk_firmware` repository](https://github.com/qmk/qmk_firmware/tree/master/) and running `git log -1 --pretty=oneline -- keyboards/<keyboard>/keymaps/default/keymap.c` (use `keymap.json` if the keyboard in question has this file instead), which should return something similar to:
+
+```shell
+f14629ed1cd7c7ec9089604d64f29a99981558e8 Remove/migrate action_get_macro()s from default keymaps (#5625)
+```
+
+In this example, `f14629ed1cd7c7ec9089604d64f29a99981558e8` is the value that should be used for `commit`.
+
+
+## Example :id=example
+
+If one wished to add a default keymap for the H87a by Hineybush, one would run the `git log` command above against the H87a's default keymap in `qmk_firmware`:
+
+```shell
+user ~/qmk_firmware (master)
+$ git log -1 --pretty=oneline master -- keyboards/hineybush/h87a/keymaps/default/keymap.c
+ef8878fba5d3786e3f9c66436da63a560cd36ac9 Hineybush h87a lock indicators (#8237)
+```
+
+Now that we have the commit hash, we need the keymap (edited for readability):
+
+```c
+...
+#include QMK_KEYBOARD_H
+
+const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
+
+  [0] = LAYOUT_all(
+    KC_ESC,           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_PSCR, KC_SLCK, KC_PAUS,
+    KC_GRV,  KC_1,    KC_2,    KC_3,    KC_4,    KC_5,    KC_6,    KC_7,    KC_8,    KC_9,    KC_0,    KC_MINS, KC_EQL,  KC_BSPC, KC_BSPC,    KC_INS,  KC_HOME, KC_PGUP,
+    KC_TAB,  KC_Q,    KC_W,    KC_E,    KC_R,    KC_T,    KC_Y,    KC_U,    KC_I,    KC_O,    KC_P,    KC_LBRC, KC_RBRC, KC_BSLS,             KC_DEL,  KC_END,  KC_PGDN,
+    KC_CAPS, KC_A,    KC_S,    KC_D,    KC_F,    KC_G,    KC_H,    KC_J,    KC_K,    KC_L,    KC_SCLN, KC_QUOT, KC_NUHS, KC_ENT,
+    KC_LSFT, KC_NUBS, KC_Z,    KC_X,    KC_C,    KC_V,    KC_B,    KC_N,    KC_M,    KC_COMM, KC_DOT,  KC_SLSH, KC_RSFT, KC_TRNS,                      KC_UP,
+    KC_LCTL, KC_LGUI, KC_LALT,                            KC_SPC,                             KC_RALT, MO(1),   KC_RGUI, KC_RCTL,             KC_LEFT, KC_DOWN, KC_RGHT),
+
+  [1] = LAYOUT_all(
+    KC_TRNS,          KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, RGB_TOG, RGB_MOD, RGB_HUD, RGB_HUI, RGB_SAD, RGB_SAI, RGB_VAD, RGB_VAI,             BL_TOGG, BL_DEC,  BL_INC,
+    KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS,    KC_TRNS, KC_TRNS, KC_VOLU,
+    KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, RESET,   KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS,             KC_MPLY, KC_MNXT, KC_VOLD,
+    KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS,
+    KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS,                      KC_TRNS,
+    KC_TRNS, KC_TRNS, KC_TRNS,                            KC_TRNS,                            KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS,             KC_TRNS, KC_TRNS, KC_TRNS),
+
+};
+```
+
+The default keymap uses the `LAYOUT_all` macro, so that will be the value of the `layout` key. Compiled to a QMK Configurator JSON keymap, our resulting file should be:
+
+```json
+{
+  "keyboard": "hineybush/h87a",
+  "keymap": "default",
+  "commit": "ef8878fba5d3786e3f9c66436da63a560cd36ac9",
+  "layout": "LAYOUT_all",
+  "layers": [
+    [
+      "KC_ESC",             "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_PSCR", "KC_SLCK", "KC_PAUS",
+      "KC_GRV",  "KC_1",    "KC_2",    "KC_3",    "KC_4",    "KC_5",    "KC_6",    "KC_7",    "KC_8",    "KC_9",    "KC_0",    "KC_MINS", "KC_EQL",  "KC_BSPC", "KC_BSPC",    "KC_INS",  "KC_HOME", "KC_PGUP",
+      "KC_TAB",  "KC_Q",    "KC_W",    "KC_E",    "KC_R",    "KC_T",    "KC_Y",    "KC_U",    "KC_I",    "KC_O",    "KC_P",    "KC_LBRC", "KC_RBRC", "KC_BSLS",               "KC_DEL",  "KC_END",  "KC_PGDN",
+      "KC_CAPS", "KC_A",    "KC_S",    "KC_D",    "KC_F",    "KC_G",    "KC_H",    "KC_J",    "KC_K",    "KC_L",    "KC_SCLN", "KC_QUOT", "KC_NUHS", "KC_ENT",
+      "KC_LSFT", "KC_NUBS", "KC_Z",    "KC_X",    "KC_C",    "KC_V",    "KC_B",    "KC_N",    "KC_M",    "KC_COMM", "KC_DOT",  "KC_SLSH", "KC_RSFT", "KC_TRNS",                          "KC_UP",
+      "KC_LCTL", "KC_LGUI", "KC_LALT",                                  "KC_SPC",                                   "KC_RALT", "MO(1)",   "KC_RGUI", "KC_RCTL",               "KC_LEFT", "KC_DOWN", "KC_RGHT"
+    ],
+    [
+      "KC_TRNS",            "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "RGB_TOG", "RGB_MOD", "RGB_HUD", "RGB_HUI", "RGB_SAD", "RGB_SAI", "RGB_VAD", "RGB_VAI",               "BL_TOGG", "BL_DEC",  "BL_INC",
+      "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS",    "KC_TRNS", "KC_TRNS", "KC_VOLU",
+      "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "RESET",   "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS",               "KC_MPLY", "KC_MNXT", "KC_VOLD",
+      "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS",
+      "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS",                          "KC_TRNS",
+      "KC_TRNS", "KC_TRNS", "KC_TRNS",                                  "KC_TRNS",                                  "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS",               "KC_TRNS", "KC_TRNS", "KC_TRNS"
+    ]
+  ]
+}
+```
+
+The white space in the `layers` arrays have no effect on the functionality of the keymap, but are used to make these files easier for humans to read.
+
+
+## Caveats :id=caveats
+
+### Layers can only be referenced by number :id=layer-references
+
+A common QMK convention is to name layers using a series of `#define`s, or an `enum` statement:
+
+```c
+enum layer_names {
+    _BASE,
+    _MEDIA,
+    _FN
+};
+```
+
+This works in C, but for Configurator, you *must* use the layer's numeric index – `MO(_FN)` would need to be `MO(2)` in the above example.
+
+### No support for custom code of any kind :id=custom-code
+
+Features that require adding functions to the keymap.c file, such as Tap Dance or Unicode, can not be compiled in Configurator **at all**. Even setting `TAP_DANCE_ENABLE = yes` in the `qmk_firmware` repository at the keyboard level will prevent Configurator from compiling **any** firmware for that keyboard. This is limited both by the API and the current spec of our JSON keymap format.
+
+### Limited Support for Custom keycodes :id=custom-keycodes
+
+There is a way to support custom keycodes: if the logic for a custom keycode is implemented at the keyboard level instead of the keymap level in qmk_firmware, that keycode *can* be used in Configurator and it *will* compile and work. Instead of using the following in your `keymap.c`:
+
+```c
+enum custom_keycodes {
+    MACRO_1 = SAFE_RANGE,
+    MACRO_2,
+    MACRO_3
+};
+...
+bool process_record_user(uint16_t keycode, keyrecord_t *record) {
+    switch(keycode) {
+        case MACRO_1:
+            if (record->event.pressed) {
+                SEND_STRING("This is macro #1.");
+            }
+            return false;
+        case MACRO_2:
+            if (record->event.pressed) {
+                SEND_STRING("This is macro #2.");
+            }
+            return false;
+        case MACRO_3:
+            if (record->event.pressed) {
+                SEND_STRING("This is macro #3.");
+            }
+            return false;
+    }
+    return true;
+};
+```
+
+... add the keycode `enum` block to your keyboard's header file (`<keyboard>.h`) as follows (note that the `enum` is named `keyboard_keycodes` here):
+
+```c
+enum keyboard_keycodes {
+    MACRO_1 = SAFE_RANGE,
+    MACRO_2,
+    MACRO_3,
+    NEW_SAFE_RANGE  // Important!
+};
+```
+
+... then the logic to your `<keyboard>.c` through `process_record_kb()`:
+
+```c
+bool process_record_kb(uint16_t keycode, keyrecord_t *record) {
+    switch(keycode) {
+        case MACRO_1:
+            if (record->event.pressed) {
+                SEND_STRING("This is macro #1.");
+            }
+            return false;
+        case MACRO_2:
+            if (record->event.pressed) {
+                SEND_STRING("This is macro #2.");
+            }
+            return false;
+        case MACRO_3:
+            if (record->event.pressed) {
+                SEND_STRING("This is macro #3.");
+            }
+            return false;
+    }
+    return process_record_user(keycode, record);
+};
+```
+
+Note the call to `process_record_user()` at the end. Additionally, users of the keyboard will need to use `NEW_SAFE_RANGE` instead of `SAFE_RANGE` if they wish to add their own custom keycodes at keymap level, beyond what is provided by the keyboard.
+
+
+## Additional Reading :id=additional-reading
+
+For QMK Configurator to support your keyboard, your keyboard must be present in the `master` branch of the `qmk_firmware` repository. For instructions on this, please see [Supporting Your Keyboard in QMK Configurator](reference_configurator_support.md).

docs/configurator_step_by_step.md

@@ -12,7 +12,7 @@ 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.  <!-- FIXME(skullydazed): This feels too wordy and I'm not sure we want to encourage these kinds of issues. Also, should we prompt them to bug the manufacutrer? -->
+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.  <!-- FIXME(skullydazed): This feels too wordy and I'm not sure we want to encourage these kinds of issues. Also, should we prompt them to bug the manufacutrer? -->
 
 ## Step 2: Select Your Keyboard Layout
 

docs/contributing.md

@@ -23,7 +23,7 @@ Please keep these things in mind:
 
 # Project Overview
 
-QMK is largely written in C, with specific features and parts written in C++. It targets embedded processors found in keyboards, particularly AVR ([LUFA](http://www.fourwalledcubicle.com/LUFA.php)) and ARM ([ChibiOS](http://www.chibios.com)). If you are already well versed in Arduino programming you'll find a lot of the concepts and limitations familiar. Prior experience with Arduino is not required to successfully contribute to QMK.
+QMK is largely written in C, with specific features and parts written in C++. It targets embedded processors found in keyboards, particularly AVR ([LUFA](https://www.fourwalledcubicle.com/LUFA.php)) and ARM ([ChibiOS](https://www.chibios.org)). If you are already well versed in Arduino programming you'll find a lot of the concepts and limitations familiar. Prior experience with Arduino is not required to successfully contribute to QMK.
 
 <!-- FIXME: We should include a list of resources for learning C here. -->
 

docs/custom_quantum_functions.md

@@ -57,7 +57,7 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) {
     case KC_ENTER:
       // Play a tone when enter is pressed
       if (record->event.pressed) {
-        PLAY_NOTE_ARRAY(tone_qwerty);
+        PLAY_SONG(tone_qwerty);
       }
       return true; // Let QMK send the enter press/release events
     default:
@@ -88,108 +88,6 @@ keyrecord_t record {
 }
 ```
 
-# LED Control
-
-QMK provides methods to read 5 of the LEDs defined in the HID spec:
-
-* Num Lock
-* Caps Lock
-* Scroll Lock
-* Compose
-* Kana
-
-There are two ways to get the lock LED state:
-
-* by implementing `bool led_update_kb(led_t led_state)` or `_user(led_t led_state)`; or
-* by calling `led_t host_keyboard_led_state()`
-
-!> `host_keyboard_led_state()` may already reflect a new value before `led_update_user()` is called.
-
-Two more deprecated functions exist that provide the LED state as a `uint8_t`:
-
-* `uint8_t led_set_kb(uint8_t usb_led)` and `_user(uint8_t usb_led)`
-* `uint8_t host_keyboard_leds()`
-
-## `led_update_user()`
-
-This function will be called when the state of one of those 5 LEDs changes. It receives the LED state as a struct parameter.
-
-By convention, return `true` from `led_update_user()` to get the `led_update_kb()` hook to run its code, and
-return `false` when you would prefer not to run the code in `led_update_kb()`.
-
-Some examples include:
-
-  - overriding the LEDs to use them for something else like layer indication
-    - return `false` because you do not want the `_kb()` function to run, as it would override your layer behavior.
-  - play a sound when an LED turns on or off.
-    - return `true` because you want the `_kb` function to run, and this is in addition to the default LED behavior.
-
-?> Because the `led_set_*` functions return `void` instead of `bool`, they do not allow for overriding the keyboard LED control, and thus it's recommended to use `led_update_*` instead.
-
-### Example `led_update_kb()` Implementation
-
-```c
-bool led_update_kb(led_t led_state) {
-    bool res = led_update_user(led_state);
-    if(res) {
-        // writePin sets the pin high for 1 and low for 0.
-        // In this example the pins are inverted, setting
-        // it low/0 turns it on, and high/1 turns the LED off.
-        // This behavior depends on whether the LED is between the pin
-        // and VCC or the pin and GND.
-        writePin(B0, !led_state.num_lock);
-        writePin(B1, !led_state.caps_lock);
-        writePin(B2, !led_state.scroll_lock);
-        writePin(B3, !led_state.compose);
-        writePin(B4, !led_state.kana);
-    }
-    return res;
-}
-```
-
-### Example `led_update_user()` Implementation
-
-This incomplete example would play a sound if Caps Lock is turned on or off. It returns `true`, because you also want the LEDs to maintain their state.
-
-```c
-#ifdef AUDIO_ENABLE
-  float caps_on[][2] = SONG(CAPS_LOCK_ON_SOUND);
-  float caps_off[][2] = SONG(CAPS_LOCK_OFF_SOUND);
-#endif
-
-bool led_update_user(led_t led_state) {
-    #ifdef AUDIO_ENABLE
-    static uint8_t caps_state = 0;
-    if (caps_state != led_state.caps_lock) {
-        led_state.caps_lock ? PLAY_SONG(caps_on) : PLAY_SONG(caps_off);
-        caps_state = led_state.caps_lock;
-    }
-    #endif
-    return true;
-}
-```
-
-### `led_update_*` Function Documentation
-
-* Keyboard/Revision: `bool led_update_kb(led_t led_state)`
-* Keymap: `bool led_update_user(led_t led_state)`
-
-## `host_keyboard_led_state()`
-
-Call this function to get the last received LED state as a `led_t`. This is useful for reading the LED state outside `led_update_*`, e.g. in [`matrix_scan_user()`](#matrix-scanning-code).
-
-## 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.
@@ -287,6 +185,14 @@ This function gets called at every matrix scan, which is basically as often as t
 
 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 housekeeping
+
+* Keyboard/Revision: `void housekeeping_task_kb(void)`
+* Keymap: `void housekeeping_task_user(void)`
+
+This function gets called at the end of all QMK processing, before starting the next iteration. You can safely assume that QMK has dealt with the last matrix scan at the time that these functions are invoked -- layer states have been updated, USB reports have been sent, LEDs have been updated, and displays have been drawn.
+
+Similar to `matrix_scan_*`, these are called as often as the MCU can handle. To keep your board responsive, it's suggested to do as little as possible during these function calls, potentially throtting their behaviour if you do indeed require implementing something special.
 
 # Keyboard Idling/Wake Code
 
@@ -319,7 +225,7 @@ This runs code every time that the layers get changed.  This can be useful for l
 
 ### 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
+This example shows how to set the [RGB Underglow](feature_rgblight.md) lights based on the layer, using the Planck as an example.
 
 ```c
 layer_state_t layer_state_set_user(layer_state_t state) {
@@ -343,6 +249,11 @@ layer_state_t layer_state_set_user(layer_state_t state) {
   return state;
 }
 ```
+
+Use the `IS_LAYER_ON_STATE(state, layer)` and `IS_LAYER_OFF_STATE(state, layer)` macros to check the status of a particular layer.
+
+Outside of `layer_state_set_*` functions, you can use the `IS_LAYER_ON(layer)` and `IS_LAYER_OFF(layer)` macros to check global layer state.
+
 ### `layer_state_set_*` Function Documentation
 
 * Keyboard/Revision: `layer_state_t layer_state_set_kb(layer_state_t state)`
@@ -438,7 +349,7 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) {
     case KC_ENTER:
         // Play a tone when enter is pressed
         if (record->event.pressed) {
-            PLAY_NOTE_ARRAY(tone_qwerty);
+            PLAY_SONG(tone_qwerty);
         }
         return true; // Let QMK send the enter press/release events
     case RGB_LYR:  // This allows me to use underglow as layer indication, or as normal
@@ -449,7 +360,7 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) {
                 layer_state_set(layer_state);   // then immediately update the layer color
             }
         }
-        return false; break;
+        return false;
     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
@@ -486,56 +397,3 @@ And you're done.  The RGB layer indication will only work if you want it to. And
 * Keymap: `void eeconfig_init_user(void)`, `uint32_t eeconfig_read_user(void)` and `void eeconfig_update_user(uint32_t val)`
 
 The `val` is the value of the data that you want to write to EEPROM.  And the `eeconfig_read_*` function return a 32 bit (DWORD) value from the EEPROM. 
-
-# Custom Tapping Term
-
-By default, the tapping term and related options (such as `IGNORE_MOD_TAP_INTERRUPT`) are defined globally, and are not configurable by key.  For most users, this is perfectly fine.  But in some cases, dual function keys would be greatly improved by different timeout behaviors than `LT` keys, or because some keys may be easier to hold than others.  Instead of using custom key codes for each, this allows for per key configurable timeout behaviors.
-
-There are two configurable options to control per-key timeout behaviors:
-
-- `TAPPING_TERM_PER_KEY`
-- `IGNORE_MOD_TAP_INTERRUPT_PER_KEY`
-
-You need to add `#define` lines to your `config.h` for each feature you want.
-
-```
-#define TAPPING_TERM_PER_KEY
-#define IGNORE_MOD_TAP_INTERRUPT_PER_KEY
-```
-
-
-## Example `get_tapping_term` Implementation
-
-To change the `TAPPING_TERM` based on the keycode, you'd want to add something like the following to your `keymap.c` file:
-
-```c
-uint16_t get_tapping_term(uint16_t keycode) {
-  switch (keycode) {
-    case SFT_T(KC_SPC):
-      return TAPPING_TERM + 1250;
-    case LT(1, KC_GRV):
-      return 130;
-    default:
-      return TAPPING_TERM;
-  }
-}
-```
-
-## Example `get_ignore_mod_tap_interrupt` Implementation
-
-To change the `IGNORE_MOD_TAP_INTERRUPT` value based on the keycode, you'd want to add something like the following to your `keymap.c` file:
-
-```c
-bool get_ignore_mod_tap_interrupt(uint16_t keycode) {
-  switch (keycode) {
-    case SFT_T(KC_SPC):
-      return true;
-    default:
-      return false;
-  }
-}
-```
-
-## `get_tapping_term` / `get_ignore_mod_tap_interrupt` Function Documentation
-
-Unlike many of the other functions here, there isn't a need (or even reason) to have a quantum or keyboard level function. Only user level functions are useful here, so no need to mark them as such.

docs/data_driven_config.md

@@ -0,0 +1,91 @@
+# Data Driven Configuration
+
+This page describes how QMK's data driven JSON configuration system works. It is aimed at developers who want to work on QMK itself.
+
+## History
+
+Historically QMK has been configured through a combination of two mechanisms- `rules.mk` and `config.h`. While this worked well when QMK was only a handful of keyboards we've grown to encompass nearly 1500 supported keyboards. That extrapolates out to 6000 configuration files under `keyboards/` alone! The freeform nature of these files and the unique patterns people have used to avoid duplication have made ongoing maintenance a challenge, and a large number of our keyboards follow patterns that are outdated and sometimes harder to understand.
+
+We have also been working on bringing the power of QMK to people who aren't comformable with a CLI, and other projects such as VIA are working to make using QMK as easy as installing a program. These tools need information about how a keyboard is laid out or what pins and features are available so that users can take full advantage of QMK. We introduced `info.json` as a first step towards this. The QMK API is an effort to combine these 3 sources of information- `config.h`, `rules.mk`, and `info.json`- into a single source of truth that end-user tools can use.
+
+Now we have support for generating `rules.mk` and `config.h` values from `info.json`, allowing us to have a single source of truth. This will allow us to use automated tooling to maintain keyboards saving a lot of time and maintenance work.
+
+## Overview
+
+On the C side of things nothing changes. When you need to create a new rule or define you follow the same process:
+
+1. Add it to `docs/config_options.md`
+1. Set a default in the appropriate core file
+1. Add your ifdef statements as needed
+
+You will then need to add support for your new configuration to `info.json`. The basic process is:
+
+1. Add it to the schema in `data/schemas/keyboards.jsonschema`
+1. Add a mapping in `data/maps`
+1. (optional and discoraged) Add code to extract/generate it to:
+  * `lib/python/qmk/info.py`
+  * `lib/python/qmk/cli/generate/config_h.py`
+  * `lib/python/qmk/cli/generate/rules_mk.py`
+
+## Adding an option to info.json
+
+This section describes adding support for a `config.h`/`rules.mk` value to info.json.
+
+### Add it to the schema
+
+QMK maintains [jsonschema](https://json-schema.org/) files in `data/schemas`. The values that go into keyboard-specific `info.json` files are kept in `keyboard.jsonschema`. Any value you want to make available to end users to edit must go in here.
+
+In some cases you can simply add a new top-level key. Some examples to follow are `keyboard_name`, `maintainer`, `processor`, and `url`. This is appropriate when your option is self-contained and not directly related to other options.
+
+In other cases you should group like options together in an `object`. This is particularly true when adding support for a feature. Some examples to follow for this are `indicators`, `matrix_pins`, and `rgblight`. If you are not sure how to integrate your new option(s) [open an issue](https://github.com/qmk/qmk_firmware/issues/new?assignees=&labels=cli%2C+python&template=other_issues.md&title=) or [join #cli on Discord](https://discord.gg/heQPAgy) and start a conversation there.
+
+### Add a mapping
+
+In most cases you can add a simple mapping. These are maintained as JSON files in `data/mappings/info_config.json` and `data/mappings/info_rules.json`, and control mapping for `config.h` and `rules.mk`, respectively. Each mapping is keyed by the `config.h` or `rules.mk` variable, and the value is a hash with the following keys:
+
+* `info_key`: (required) The location within `info.json` for this value. See below.
+* `value_type`: (optional) Default `str`. The format for this variable's value. See below.
+* `to_json`: (optional) Default `true`. Set to `false` to exclude this mapping from info.json
+* `to_c`: (optional) Default `true`. Set to `false` to exclude this mapping from config.h
+* `warn_duplicate`: (optional) Default `true`. Set to `false` to turn off warning when a value exists in both places
+
+#### Info Key
+
+We use JSON dot notation to address variables within info.json. For example, to access `info_json["rgblight"]["split_count"]` I would specify `rgblight.split_count`. This allows you to address deeply nested keys with a simple string.
+
+Under the hood we use [Dotty Dict](https://dotty-dict.readthedocs.io/en/latest/), you can refer to that documentation for how these strings are converted to object access.
+
+#### Value Types
+
+By default we treat all values as simple strings. If your value is more complex you can use one of these types to intelligently parse the data:
+
+* `array`: A comma separated array of strings
+* `array.int`: A comma separated array of integers
+* `int`: An integer
+* `hex`: A number formatted as hex
+* `list`: A space separate array of strings
+* `mapping`: A hash of key/value pairs
+
+### Add code to extract it
+
+Most use cases can be solved by the mapping files described above. If yours can't you can instead write code to extract your config values.
+
+Whenever QMK generates a complete `info.json` it extracts information from `config.h` and `rules.mk`. You will need to add code for your new config value to `lib/python/qmk/info.py`. Typically this means adding a new `_extract_<feature>()` function and then calling your function in either `_extract_config_h()` or `_extract_rules_mk()`.
+
+If you are not sure how to edit this file or are not comfortable with Python [open an issue](https://github.com/qmk/qmk_firmware/issues/new?assignees=&labels=cli%2C+python&template=other_issues.md&title=) or [join #cli on Discord](https://discord.gg/heQPAgy) and someone can help you with this part.
+
+### Add code to generate it
+
+The final piece of the puzzle is providing your new option to the build system. This is done by generating two files:
+
+* `.build/obj_<keyboard>/src/info_config.h`
+* `.build/obj_<keyboard>/src/rules.mk`
+
+These two files are generated by the code here:
+
+* `lib/python/qmk/cli/generate/config_h.py`
+* `lib/python/qmk/cli/generate/rules_mk.py`
+
+For `config.h` values you'll need to write a function for your rule(s) and call that function in `generate_config_h()`.
+
+If you have a new top-level `info.json` key for `rules.mk` you can simply add your keys to `info_to_rules` at the top of `lib/python/qmk/cli/generate/rules_mk.py`. Otherwise you'll need to create a new if block for your feature in `generate_rules_mk()`.

docs/de/README.md

@@ -9,11 +9,11 @@
 
 ## Was ist QMK Firmware?
 
-QMK (*Quantum Mechanical Keyboard*) ist eine Open-Source-Community, welche die QMK-Firmware, die QMK-Toolbox, [qmk.fm](https://qmk.fm) und diese Dokumententation betreut. QMK-Firmware ist eine Weiterentwicklung der [tmk\_keyboard](http://github.com/tmk/tmk_keyboard)-Tastatur-Firmware mit vielen nützlichen Zusatzfunktionen für Atmel AVR-Prozessoren. Ursprünglich wurde sie für Produkte von [OLKB](http://olkb.com), das [ErgoDox EZ](http://www.ergodox-ez.com) und das [Clueboard](http://clueboard.co/) entwickelt. Im Laufe der Zeit wurde sie mit Hilfe von [ChibiOS](http://chibios.org) auch für die ARM-Architektur angepasst. Außerdem ist es inzwischen möglich, auch handverdrahtete Tastaturen und selbst geätzte PCBs mit QMK zu verwenden.
+QMK (*Quantum Mechanical Keyboard*) ist eine Open-Source-Community, welche die QMK-Firmware, die QMK-Toolbox, [qmk.fm](https://qmk.fm) und diese Dokumententation betreut. QMK-Firmware ist eine Weiterentwicklung der [tmk\_keyboard](https://github.com/tmk/tmk_keyboard)-Tastatur-Firmware mit vielen nützlichen Zusatzfunktionen für Atmel AVR-Prozessoren. Ursprünglich wurde sie für Produkte von [OLKB](https://olkb.com), das [ErgoDox EZ](https://www.ergodox-ez.com) und das [Clueboard](https://clueboard.co/) entwickelt. Im Laufe der Zeit wurde sie mit Hilfe von [ChibiOS](https://chibios.org) auch für die ARM-Architektur angepasst. Außerdem ist es inzwischen möglich, auch handverdrahtete Tastaturen und selbst geätzte PCBs mit QMK zu verwenden.
 
 ## Bezugsquelle für QMK
 
-Wenn Du vorhast, deine Tastatur, Tastaturbelegung oder Features zu QMK beizusteuern, geht das am einfachsten, indem Du das [Repository auf Github](https://github.com/qmk/qmk_firmware#fork-destination-box) forkst, die Änderungen in deinem lokalen Repo vornimmst und anschließend einen [Pull Request](https://github.com/qmk/qmk_firmware/pulls) einreichst.
+Wenn Du vorhast, deine Tastatur, Tastaturbelegung oder Features zu QMK beizusteuern, geht das am einfachsten, indem Du das [Repository auf GitHub](https://github.com/qmk/qmk_firmware#fork-destination-box) forkst, die Änderungen in deinem lokalen Repo vornimmst und anschließend einen [Pull Request](https://github.com/qmk/qmk_firmware/pulls) einreichst.
 
 Ansonsten kannst Du es als [zip](https://github.com/qmk/qmk_firmware/zipball/master) oder [tar](https://github.com/qmk/qmk_firmware/tarball/master) herunterladen, oder es direkt via git klonen (`git clone git@github.com:qmk/qmk_firmware.git` bzw. `git clone https://github.com/qmk/qmk_firmware.git`).
 

docs/de/_summary.md

@@ -11,7 +11,7 @@
   * [QMK CLI](de/cli.md)
   * [QMK CLI Konfiguration](de/cli_configuration.md)
   * [Zu QMK beitragen](de/contributing.md)
-  * [Anleitung für Github](de/getting_started_github.md)
+  * [Anleitung für GitHub](de/getting_started_github.md)
   * [Nach Hilfe fragen](de/getting_started_getting_help.md)
 
 * [Breaking Changes](de/breaking_changes.md)
@@ -98,6 +98,7 @@
   * [ISP Flashing Guide](de/isp_flashing_guide.md)
   * [ARM Debugging Guide](de/arm_debugging.md)
   * [I2C Driver](de/i2c_driver.md)
+  * [SPI Driver](de/spi_driver.md)
   * [GPIO Controls](de/internals_gpio_control.md)
   * [Proton C Conversion](de/proton_c_conversion.md)
 

docs/de/newbs_getting_started.md

@@ -18,7 +18,7 @@ Wenn Du es vorziehst mit einer grafischen Oberfläche zu entwickeln kannst Du au
 
 Du wirst ein Programm benötigen, mit dem Du **plain text** (= reiner Text) Dateien bearbeiten und speichern kannst. Wenn Du Windows benutzt, reicht dafür schon das normale `Notepad` und für Linux z.B. `gedit` oder `leafpad`. Beide sind sehr rudimentäre Editoren deren Funktionsumfang aber vollkommen ausreicht. Für macOS' standard `TextEdit` muss man ein bisschen vorsichtig sein und darauf achten, beim Speichern explizit unter _Format_ die Option _Reiner Text_ auszuwählen.
 
-Ansonsten ist es empfehlenswert, einen Editor herunterzuladen der für die Programmierung und das Bearbeiten von Code ausgelegt ist wie z.b [Notepad++](http://notepad-plus-plus.org/), [Sublime Text](https://www.sublimetext.com/) oder [VS Code](https://code.visualstudio.com/).
+Ansonsten ist es empfehlenswert, einen Editor herunterzuladen der für die Programmierung und das Bearbeiten von Code ausgelegt ist wie z.b [Notepad++](https://notepad-plus-plus.org/), [Sublime Text](https://www.sublimetext.com/) oder [VS Code](https://code.visualstudio.com/).
 
 ?> Immer noch unsicher, welcher Text Editor der Richtige für Dich ist? Laurence Bradford hat eine hervorragende [Einleitung](https://learntocodewith.me/programming/basics/text-editors/) zu dem Thema geschrieben (auf Englisch).
 
@@ -44,7 +44,7 @@ Wir haben versucht, die Installation der Entwicklungsumgebung für QMK so einfac
 
 Du wirst MSYS2 (o.Ä.) und Git benötigen.
 
-* Befolge die Installationsanleitung auf der [MSYS2 Homepage](http://www.msys2.org)
+* Befolge die Installationsanleitung auf der [MSYS2 Homepage](https://www.msys2.org)
 * Schließe alle offenen MSYS2 Fenster und öffne ein neues MSYS2 MinGW 64-bit Terminal
 * Installiere Git mit dem Kommando: `pacman -S git`
 

docs/de/newbs_learn_more_resources.md

@@ -6,7 +6,7 @@ Git Ressourcen:
 
 * [Gutes allgemeines Tutorial](https://www.codecademy.com/learn/learn-git) (auf Englisch)
 * [Git spielerisch anhand von Beispielen lernen](https://learngitbranching.js.org/) (auf Englisch)
-* [Mehr über den allgemeinen Umgang mit Github](getting_started_github.md)
+* [Mehr über den allgemeinen Umgang mit GitHub](getting_started_github.md)
 * [Mehr über Git im Bezug zu QMK](contributing.md)
 
 Mehr über die Arbeit mit der Befehlszeile:

docs/de/newbs_testing_debugging.md

@@ -10,8 +10,8 @@ Anmerkung: Diese Programme werden weder von QMK bereitgestellt oder gutgeheißen
 
 * [Switch Hitter](https://elitekeyboards.com/switchhitter.php) (Nur für Windows)
 * [Keyboard Viewer](https://www.imore.com/how-use-keyboard-viewer-your-mac) (Nur für Mac)
-* [Keyboard Tester](http://www.keyboardtester.com) (Web basiert)
-* [Keyboard Checker](http://keyboardchecker.com) (Web basiert)
+* [Keyboard Tester](https://www.keyboardtester.com) (Web basiert)
+* [Keyboard Checker](https://keyboardchecker.com) (Web basiert)
 
 ## Debuggen
 
@@ -41,7 +41,9 @@ Bevorzugst Du es lieber auf der Befehlszeile zu debuggen? Dafür eignet sich das
 
 Manchmal ist es hilfreich Debug-Nachrichten innerhalb deines eigenen [Custom Codes](de/custom_quantum_functions.md) zu drucken. Das ist ziemlich einfach. Beginne damit `print.h` am Anfang deiner Datei zu inkludieren:
 
-    #include <print.h>
+```c
+#include "print.h"
+```
 
 Danach stehen dir verschiedene Druck-Funktionen zur Verfügung:
 

docs/documentation_best_practices.md

@@ -61,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/_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.
+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.

docs/documentation_templates.md

@@ -4,12 +4,12 @@ This page documents the templates you should use when submitting new Keymaps and
 
 ## Keymap `readme.md` Template :id=keyboard-readmemd-template
 
-Most keymaps have an image depicting the layout. You can use [Keyboard Layout Editor](http://keyboard-layout-editor.com) to create an image. Upload it to [Imgur](http://imgur.com) or another hosting service, please do not include images in your Pull Request.
+Most keymaps have an image depicting the layout. You can use [Keyboard Layout Editor](https://keyboard-layout-editor.com) to create an image. Upload it to [Imgur](https://imgur.com) or another hosting service, please do not include images in your Pull Request.
 
 Below the image you should write a short description to help people understand your keymap.
 
 ```
-![Clueboard Layout Image](http://i.imgur.com/7Capi8W.png)
+![Clueboard Layout Image](https://i.imgur.com/7Capi8W.png)
 
 # Default Clueboard Layout
 
@@ -24,9 +24,9 @@ the Ctrl, Alt, or GUI modifiers are held down.
 ```
 # Planck
 
-![Planck](http://i.imgur.com/q2M3uEU.jpg)
+![Planck](https://i.imgur.com/q2M3uEU.jpg)
 
-A compact 40% (12x4) ortholinear keyboard kit made and sold by OLKB and Massdrop. [More info on qmk.fm](http://qmk.fm/planck/)
+A compact 40% (12x4) ortholinear keyboard kit made and sold by OLKB and Massdrop. [More info on qmk.fm](https://qmk.fm/planck/)
 
 * Keyboard Maintainer: [Jack Humbert](https://github.com/jackhumbert)
 * Hardware Supported: Planck PCB rev1, rev2, rev3, rev4, Teensy 2.0

docs/driver_installation_zadig.md

@@ -4,7 +4,7 @@ QMK presents itself to the host as a regular HID keyboard device, and as such re
 
 There are two notable exceptions: the Caterina bootloader, usually seen on Pro Micros, and the HalfKay bootloader shipped with PJRC Teensys, appear as a serial port and a generic HID device respectively, and so do not require a driver.
 
-We recommend the use of the [Zadig](https://zadig.akeo.ie/) utility. If you have set up the development environment with MSYS2 or WSL, the `qmk_install.sh` script will have asked if you want it to install the drivers for you.
+We recommend the use of the [Zadig](https://zadig.akeo.ie/) utility. If you have set up the development environment with MSYS2, the `qmk_install.sh` script will have already installed the drivers for you.
 
 ## Installation
 
@@ -14,16 +14,11 @@ Some keyboards may have specific instructions for entering the bootloader. For e
 To put a device in bootloader mode with USBaspLoader, tap the `RESET` button while holding down the `BOOT` button.
 Alternatively, hold `BOOT` while inserting the USB cable.
 
-Zadig will automatically detect the bootloader device. You may sometimes need to check **Options → List All Devices**.
-
- - For keyboards with Atmel AVR MCUs, the bootloader will be named something similar to `ATm32U4DFU`, and have a Vendor ID of `03EB`.
- - USBasp bootloaders will appear as `USBasp`, with a VID/PID of `16C0:05DC`.
- - AVR keyboards flashed with the QMK-DFU bootloader will be named `<keyboard name> Bootloader` and will also have the VID `03EB`.
- - For most ARM keyboards, it will be called `STM32 BOOTLOADER`, and have a VID/PID of `0483:DF11`.
+Zadig should automatically detect the bootloader device, but you may sometimes need to check **Options → List All Devices** and select the device from the dropdown instead.
 
 !> If Zadig lists one or more devices with the `HidUsb` driver, your keyboard is probably not in bootloader mode. The arrow will be colored orange and you will be asked to confirm modifying a system driver. **Do not** proceed if this is the case!
 
-If the arrow appears green, select the driver, and click **Install Driver**. The `libusb-win32` driver will usually work for AVR, and `WinUSB` for ARM, but if you still cannot flash the board, try installing a different driver from the list. For flashing a USBaspLoader device via command line with msys2, the `libusbk` driver is recommended, otherwise `libusb-win32` will work fine if you are using QMK Toolbox for flashing.
+If the arrow appears green, select the driver, and click **Install Driver**. See the [list of known bootloaders](#list-of-known-bootloaders) for the correct driver to install.
 
 ![Zadig with a bootloader driver correctly installed](https://i.imgur.com/b8VgXzx.png)
 
@@ -43,6 +38,40 @@ Right-click it and hit **Uninstall device**. Make sure to tick **Delete the driv
 
 ![The Device Uninstall dialog, with the "delete driver" checkbox ticked](https://i.imgur.com/aEs2RuA.png)
 
-Click **Action → Scan for hardware changes**. At this point, you should be able to type again. Double check in Zadig that the keyboard device(s) are using the `HidUsb` driver. If so, you're all done, and your board should be functional again!
+Click **Action → Scan for hardware changes**. At this point, you should be able to type again. Double check in Zadig that the keyboard device(s) are using the `HidUsb` driver. If so, you're all done, and your board should be functional again! Otherwise, repeat the process until Zadig reports the correct driver.
 
 ?> A full reboot of your computer may sometimes be necessary at this point, to get Windows to pick up the new driver.
+
+## List of Known Bootloaders
+
+This is a list of known bootloader devices and their USB vendor and product IDs, as well as the correct driver to assign for flashing with QMK. Note that the usbser and HidUsb drivers are built in to Windows, and cannot be assigned with Zadig - if your device has an incorrect driver, you must use the Device Manager to uninstall it as described in the previous section.
+
+The device name here is the name that appears in Zadig, and may not be what the Device Manager or QMK Toolbox displays.
+
+|Bootloader   |Device Name                   |VID/PID       |Driver |
+|-------------|------------------------------|--------------|-------|
+|`atmel-dfu`  |ATmega16u2 DFU                |`03EB:2FEF`   |libusb0|
+|`atmel-dfu`  |ATmega32U2 DFU                |`03EB:2FF0`   |libusb0|
+|`atmel-dfu`  |ATm16U4 DFU V1.0.2            |`03EB:2FF3`   |libusb0|
+|`atmel-dfu`  |ATm32U4DFU                    |`03EB:2FF4`   |libusb0|
+|`atmel-dfu`  |*none* (AT90USB64)            |`03EB:2FF9`   |libusb0|
+|`atmel-dfu`  |AT90USB128 DFU                |`03EB:2FFB`   |libusb0|
+|`qmk-dfu`    |(keyboard name) Bootloader    |As `atmel-dfu`|libusb0|
+|`halfkay`    |*none*                        |`16C0:0478`   |HidUsb |
+|`caterina`   |Pro Micro 3.3V                |`1B4F:9203`   |usbser |
+|`caterina`   |Pro Micro 5V                  |`1B4F:9205`   |usbser |
+|`caterina`   |LilyPadUSB                    |`1B4F:9207`   |usbser |
+|`caterina`   |Pololu A-Star 32U4 Bootloader |`1FFB:0101`   |usbser |
+|`caterina`   |Arduino Leonardo              |`2341:0036`   |usbser |
+|`caterina`   |Arduino Micro                 |`2341:0037`   |usbser |
+|`caterina`   |Adafruit Feather 32u4         |`239A:000C`   |usbser |
+|`caterina`   |Adafruit ItsyBitsy 32u4 3V    |`239A:000D`   |usbser |
+|`caterina`   |Adafruit ItsyBitsy 32u4 5V    |`239A:000E`   |usbser |
+|`caterina`   |Arduino Leonardo              |`2A03:0036`   |usbser |
+|`caterina`   |Arduino Micro                 |`2A03:0037`   |usbser |
+|`bootloadHID`|HIDBoot                       |`16C0:05DF`   |HidUsb |
+|`USBasp`     |USBasp                        |`16C0:05DC`   |libusbK|
+|`apm32-dfu`  |APM32 DFU ISP Mode            |`314B:0106`   |WinUSB |
+|`stm32-dfu`  |STM32 BOOTLOADER              |`0483:DF11`   |WinUSB |
+|`kiibohd`    |Kiibohd DFU Bootloader        |`1C11:B007`   |WinUSB |
+|`stm32duino` |Maple 003                     |`1EAF:0003`   |WinUSB |

docs/eeprom_driver.md

@@ -1,4 +1,4 @@
-# EEPROM Driver Configuration
+# EEPROM Driver Configuration :id=eeprom-driver-configuration
 
 The EEPROM driver can be swapped out depending on the needs of the keyboard, or whether extra hardware is present.
 
@@ -6,15 +6,20 @@ Driver                             | Description
 -----------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
 `EEPROM_DRIVER = vendor` (default) | Uses the on-chip driver provided by the chip manufacturer. For AVR, this is provided by avr-libc. This is supported on ARM for a subset of chips -- STM32F3xx, STM32F1xx, and STM32F072xB will be emulated by writing to flash. STM32L0xx and STM32L1xx will use the onboard dedicated true EEPROM. Other chips will generally act as "transient" below.
 `EEPROM_DRIVER = i2c`              | Supports writing to I2C-based 24xx EEPROM chips. See the driver section below.
+`EEPROM_DRIVER = spi`              | Supports writing to SPI-based 25xx EEPROM chips. See the driver section below.
 `EEPROM_DRIVER = transient`        | Fake EEPROM driver -- supports reading/writing to RAM, and will be discarded when power is lost.
 
-## Vendor Driver Configuration
+## Vendor Driver Configuration :id=vendor-eeprom-driver-configuration
+
+#### STM32 L0/L1 Configuration :id=stm32l0l1-eeprom-driver-configuration
 
 !> Resetting EEPROM using an STM32L0/L1 device takes up to 1 second for every 1kB of internal EEPROM used.
 
-No configurable options are available.
+`config.h` override                 | Description                                                                                                              | Default Value
+------------------------------------|--------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------
+`#define STM32_ONBOARD_EEPROM_SIZE` | The size of the EEPROM to use, in bytes. Erase times can be high, so it's configurable here, if not using the default value. | Minimum required to cover base _eeconfig_ data, or `1024` if VIA is enabled.
 
-## I2C Driver Configuration
+## I2C Driver Configuration :id=i2c-eeprom-driver-configuration
 
 Currently QMK supports 24xx-series chips over I2C. As such, requires a working i2c_master driver configuration. You can override the driver configuration via your config.h:
 
@@ -35,13 +40,28 @@ Module           | Equivalent `#define`            | Source
 -----------------|---------------------------------|------------------------------------------
 CAT24C512 EEPROM | `#define EEPROM_I2C_CAT24C512`  | <https://www.sparkfun.com/products/14764>
 RM24C512C EEPROM | `#define EEPROM_I2C_RM24C512C`  | <https://www.sparkfun.com/products/14764>
+24LC64 EEPROM    | `#define EEPROM_I2C_24LC64`     | <https://www.microchip.com/wwwproducts/en/24LC64>
 24LC128 EEPROM   | `#define EEPROM_I2C_24LC128`    | <https://www.microchip.com/wwwproducts/en/24LC128>
 24LC256 EEPROM   | `#define EEPROM_I2C_24LC256`    | <https://www.sparkfun.com/products/525>
 MB85RC256V FRAM  | `#define EEPROM_I2C_MB85RC256V` | <https://www.adafruit.com/product/1895>
 
 ?> If you find that the EEPROM is not cooperating, ensure you've correctly shifted up your EEPROM address by 1. For example, the datasheet might state the address as `0b01010000` -- the correct value of `EXTERNAL_EEPROM_I2C_BASE_ADDRESS` needs to be `0b10100000`.
 
-## Transient Driver configuration
+## SPI Driver Configuration :id=spi-eeprom-driver-configuration
+
+Currently QMK supports 25xx-series chips over SPI. As such, requires a working spi_master driver configuration. You can override the driver configuration via your config.h:
+
+`config.h` override                            | Description                                                                          | Default Value
+-----------------------------------------------|--------------------------------------------------------------------------------------|--------------
+`#define EXTERNAL_EEPROM_SPI_SLAVE_SELECT_PIN` | SPI Slave select pin in order to inform that the EEPROM is currently being addressed | _none_
+`#define EXTERNAL_EEPROM_SPI_CLOCK_DIVISOR`    | Clock divisor used to divide the peripheral clock to derive the SPI frequency        | `64`
+`#define EXTERNAL_EEPROM_BYTE_COUNT`           | Total size of the EEPROM in bytes                                                    | 8192
+`#define EXTERNAL_EEPROM_PAGE_SIZE`            | Page size of the EEPROM in bytes, as specified in the datasheet                      | 32
+`#define EXTERNAL_EEPROM_ADDRESS_SIZE`         | The number of bytes to transmit for the memory location within the EEPROM            | 2
+
+!> There's no way to determine if there is an SPI EEPROM actually responding. Generally, this will result in reads of nothing but zero.
+
+## Transient Driver configuration :id=transient-eeprom-driver-configuration
 
 The only configurable item for the transient EEPROM driver is its size:
 

docs/es/README.md

@@ -9,11 +9,11 @@
 
 ## ¿Qué es el firmware QMK?
 
-QMK (*Quantum Mechanical Keyboard*) es una comunidad open source que mantiene el firmware QMK, QMK Toolbox, qmk.fm, y estos documentos. El firmware QMK es un firmware para teclados basado en [tmk\_keyboard](http://github.com/tmk/tmk_keyboard) con algunas características útiles para controladores Atmel AVR, y más específicamente, la [línea de productos OLKB](http://olkb.com), el teclado [ErgoDox EZ](http://www.ergodox-ez.com), y la [línea de productos Clueboard](http://clueboard.co/). También ha sido portado a chips ARM chips usando ChibiOS. Lo puedes utilizar para manejar tu propio teclado ya sea cableado a mano o basado en una PCB personalizada.
+QMK (*Quantum Mechanical Keyboard*) es una comunidad open source que mantiene el firmware QMK, QMK Toolbox, qmk.fm, y estos documentos. El firmware QMK es un firmware para teclados basado en [tmk\_keyboard](https://github.com/tmk/tmk_keyboard) con algunas características útiles para controladores Atmel AVR, y más específicamente, la [línea de productos OLKB](https://olkb.com), el teclado [ErgoDox EZ](https://www.ergodox-ez.com), y la [línea de productos Clueboard](https://clueboard.co/). También ha sido portado a chips ARM chips usando ChibiOS. Lo puedes utilizar para manejar tu propio teclado ya sea cableado a mano o basado en una PCB personalizada.
 
 ## Cómo conseguirlo
 
-Si estás pensando en contribuir con un keymap, teclado, or característica a QMK, la manera más sencilla es hacer un [fork del repositorio en Github](https://github.com/qmk/qmk_firmware#fork-destination-box), y clonar tu repositorio localmente para hacer los cambios, subirlos, y abir un [Pull Request](https://github.com/qmk/qmk_firmware/pulls) desde tu fork.
+Si estás pensando en contribuir con un keymap, teclado, or característica a QMK, la manera más sencilla es hacer un [fork del repositorio en GitHub](https://github.com/qmk/qmk_firmware#fork-destination-box), y clonar tu repositorio localmente para hacer los cambios, subirlos, y abir un [Pull Request](https://github.com/qmk/qmk_firmware/pulls) desde tu fork.
 
 De cualquier manera, también puedes descargarlo directamente en formatos ([zip](https://github.com/qmk/qmk_firmware/zipball/master), [tar](https://github.com/qmk/qmk_firmware/tarball/master)), o clonarlo via git (`git@github.com:qmk/qmk_firmware.git`), o https (`https://github.com/qmk/qmk_firmware.git`).
 
@@ -29,4 +29,4 @@ Este ejemplo compilaría la revisión `rev4` del teclado `planck` con el keymap
 
 ## Cómo personalizar
 
-QMK tiene montones de [características](es/features.md) para explorar, y una buena cantidad de [documentación de referencia](http://docs.qmk.fm) en la que sumergirse. Se pueden sacar provecho de la mayoría de las características modificando tu [keymap](es/keymap.md), y cambiando los [keycodes](es/keycodes.md).
+QMK tiene montones de [características](es/features.md) para explorar, y una buena cantidad de [documentación de referencia](https://docs.qmk.fm) en la que sumergirse. Se pueden sacar provecho de la mayoría de las características modificando tu [keymap](es/keymap.md), y cambiando los [keycodes](es/keycodes.md).

docs/es/_summary.md

@@ -11,7 +11,7 @@
   * [QMK CLI](es/cli.md)
   * [Configuración de QMK CLI](es/cli_configuration.md)
   * [Contribuyendo a QMK](es/contributing.md)
-  * [Cómo usar Github](es/getting_started_github.md)
+  * [Cómo usar GitHub](es/getting_started_github.md)
   * [Obtener ayuda](es/getting_started_getting_help.md)
 
 * [Cambios incompatibles](es/breaking_changes.md)
@@ -98,6 +98,7 @@
   * [Guía de flasheado de ISP](es/isp_flashing_guide.md)
   * [Guía de depuración de ARM](es/arm_debugging.md)
   * [Driver I2C](es/i2c_driver.md)
+  * [Driver SPI](es/spi_driver.md)
   * [Controles GPIO](es/internals_gpio_control.md)
   * [Conversión Proton C](es/proton_c_conversion.md)
 

docs/es/hardware.md

@@ -1,6 +1,6 @@
 # Hardware
 
-QMK es compatible con una variedad de hardware. Si tu procesador puede ser dirigido por [LUFA](http://www.fourwalledcubicle.com/LUFA.php) o [ChibiOS](http://www.chibios.com), probablemente puedes hacer que QMK se ejecute en él. Esta sección explora cómo hacer que QMK se ejecute y se comunique con hardware de todo tipo.
+QMK es compatible con una variedad de hardware. Si tu procesador puede ser dirigido por [LUFA](https://www.fourwalledcubicle.com/LUFA.php) o [ChibiOS](https://www.chibios.org), probablemente puedes hacer que QMK se ejecute en él. Esta sección explora cómo hacer que QMK se ejecute y se comunique con hardware de todo tipo.
 
 * [Pautas de teclados](hardware_keyboard_guidelines.md)
 * [Procesadores AVR](hardware_avr.md)

docs/es/hardware_avr.md

@@ -32,7 +32,7 @@ Esto creará todos los archivos necesarios para tu nuevo teclado, y rellenará l
 
 ## `readme.md`
 
-Aquí es donde describirás tu teclado. Por favor sigue la [Plantilla del readme de teclados](documentation_templates.md#keyboard-readmemd-template) al escribir tu `readme.md`. Te animamos a colocar una imagen en la parte superior de tu `readme.md`. Por favor, utiliza un servicio externo como [Imgur](http://imgur.com) para alojar las imágenes.
+Aquí es donde describirás tu teclado. Por favor sigue la [Plantilla del readme de teclados](documentation_templates.md#keyboard-readmemd-template) al escribir tu `readme.md`. Te animamos a colocar una imagen en la parte superior de tu `readme.md`. Por favor, utiliza un servicio externo como [Imgur](https://imgur.com) para alojar las imágenes.
 
 ## `<keyboard>.c`
 
@@ -67,7 +67,7 @@ El archivo `config.h` es donde configuras el hardware y el conjunto de caracter
 
 En la parte superior de `config.h` encontrarás ajustes relacionados con USB. Estos controlan la apariencia de tu teclado en el Sistema Operativo. Si no tienes una buena razón para cambiar debes dejar el `VENDOR_ID` como `0xFEED`. Para el `PRODUCT_ID` debes seleccionar un número que todavía no esté en uso.
 
-Cambia las líneas de `MANUFACTURER`, `PRODUCT`, y `DESCRIPTION` para reflejar con precisión tu teclado.
+Cambia las líneas de `MANUFACTURER` y `PRODUCT` para reflejar con precisión tu teclado.
 
 ```c
 #define VENDOR_ID       0xFEED
@@ -75,7 +75,6 @@ Cambia las líneas de `MANUFACTURER`, `PRODUCT`, y `DESCRIPTION` para reflejar c
 #define DEVICE_VER      0x0001
 #define MANUFACTURER    Tú
 #define PRODUCT         mi_teclado_fantastico
-#define DESCRIPTION     Un teclado personalizado
 ```
 
 ?> Windows y macOS mostrarán el `MANUFACTURER` y `PRODUCT` en la lista de dispositivos USB. `lsusb` en Linux toma estos de la lista mantenida por el [Repositorio de ID USB](http://www.linux-usb.org/usb-ids.html) por defecto. `lsusb -v` mostrará los valores reportados por el dispositivo, y también están presentes en los registros del núcleo después de conectarlo.

docs/es/hardware_drivers.md

@@ -33,4 +33,3 @@ Soporte para hasta 2 controladores. Cada controlador implementa 2 matrices charl
 ## IS31FL3733
 
 Soporte para hasta un solo controlador con espacio para expansión. Cada controlador puede controlar 192 LEDs individuales o 64 LEDs RGB. Para obtener más información sobre cómo configurar el controlador, consulta la página de [Matriz RGB](feature_rgb_matrix.md).
-

docs/es/hardware_keyboard_guidelines.md

@@ -98,7 +98,7 @@ Por ejemplo, si tienes un PCB de 60% que soporta ANSI e ISO podría definir los
 
 En un esfuerzo por mantener el tamaño de repo abajo ya no estamos aceptando archivos binarios de cualquier formato, con pocas excepciones. Alojarlos en otro lugar (por ejemplo <https://imgur.com>) y enlazarlos en el `readme.md` es preferible.
 
-Para archivos de hardware (tales como placas, casos, pcb) puedes contribuir a [qmk.fm repo](https://github.com/qmk/qmk.fm) y estarán disponibles en [qmk.fm](http://qmk.fm). Archivos descargables se almacenan en `/<teclado>/` (nombre sigue el mismo formato que el anterior), se sirven en `http://qmk.fm/<teclado>/`, y se generan páginas de `/_pages/<teclado>/` que se sirven en la misma ubicación (Los archivos .md se generan en archivos .html mediante Jekyll). Echa un vistazo a la carpeta `lets_split` para ver un ejemplo.
+Para archivos de hardware (tales como placas, casos, pcb) puedes contribuir a [qmk.fm repo](https://github.com/qmk/qmk.fm) y estarán disponibles en [qmk.fm](https://qmk.fm). Archivos descargables se almacenan en `/<teclado>/` (nombre sigue el mismo formato que el anterior), se sirven en `https://qmk.fm/<teclado>/`, y se generan páginas de `/_pages/<teclado>/` que se sirven en la misma ubicación (Los archivos .md se generan en archivos .html mediante Jekyll). Echa un vistazo a la carpeta `lets_split` para ver un ejemplo.
 
 ## Predeterminados de teclado
 
@@ -140,7 +140,7 @@ El año debe ser el primer año en que se crea el archivo. Si el trabajo se hizo
 
 ## Licencia
 
-El núcleo de QMC está licenciado bajo la [GNU General Public License](https://www.gnu.org/licenses/licenses.en.html). Si estás enviando binarios para los procesadores AVR puedes elegir cualquiera [GPLv2](https://www.gnu.org/licenses/old-licenses/gpl-2.0.html) o [GPLv3](https://www.gnu.org/licenses/gpl.html). Si estás enviando binarios para ARM procesadores debes elegir [GPL Versión 3](https://www.gnu.org/licenses/gpl.html) para cumplir con los [ChibiOS](http://www.chibios.org) licencia GPLv3.
+El núcleo de QMC está licenciado bajo la [GNU General Public License](https://www.gnu.org/licenses/licenses.en.html). Si estás enviando binarios para los procesadores AVR puedes elegir cualquiera [GPLv2](https://www.gnu.org/licenses/old-licenses/gpl-2.0.html) o [GPLv3](https://www.gnu.org/licenses/gpl.html). Si estás enviando binarios para ARM procesadores debes elegir [GPL Versión 3](https://www.gnu.org/licenses/gpl.html) para cumplir con los [ChibiOS](https://www.chibios.org) licencia GPLv3.
 
 Si tu teclado hace uso de la [uGFX](https://gfx.io) características dentro de QMK debes cumplir con la [Licencia de uGFX](https://ugfx.io/license.html), que requiere una licencia comercial separada antes de vender un dispositivo que contiene uGFX.
 

docs/es/newbs.md

@@ -2,7 +2,7 @@
 
 QMK es un poderoso firmware Open Source para tu teclado mecánico. Puedes utilizar QMK para personalizar tu teclado en maneras a la vez simples y potentes. Gente de todos los niveles de habilidad, desde completos novatos hasta expertos programadores, han utilizado con éxito QMK para personalizar sus teclados. Esta guía te ayudará a hacer lo mismo, sin importar tu nivel de habilidad.
 
-¿No estás seguro de si tu teclado puede ejecutar QMK? Si es un teclado mecánico construido por ti mismo probablemente puedas. Damos soporte a [gran número de placas de hobbistas](http://qmk.fm/keyboards/), e incluso si tu teclado actual no pudiera ejecutar QMK no deberías tener problemas encontrando uno que cumpliera tus necesidades.
+¿No estás seguro de si tu teclado puede ejecutar QMK? Si es un teclado mecánico construido por ti mismo probablemente puedas. Damos soporte a [gran número de placas de hobbistas](https://qmk.fm/keyboards/), e incluso si tu teclado actual no pudiera ejecutar QMK no deberías tener problemas encontrando uno que cumpliera tus necesidades.
 
 ## Visión general
 

docs/es/newbs_best_practices.md

@@ -6,7 +6,7 @@ Este documento procura instruir a los novatos en las mejores prácticas para ten
 
 En este documento suponemos un par de cosas:
 
-1. Tienes una cuenta de Github, y has hecho un [fork del repo qmk_firmware](getting_started_github.md) en tu cuenta.
+1. Tienes una cuenta de GitHub, y has hecho un [fork del repo qmk_firmware](getting_started_github.md) en tu cuenta.
 2. Has [configurado tu entorno de desarrollo](newbs_getting_started.md?id=environment-setup).
 
 

docs/es/newbs_building_firmware_configurator.md

@@ -21,7 +21,7 @@ Lo diré otra vez porque es importante
 
 !> **ASEGÚRATE DE QUE SELECCIONAS LA VERSIÓN CORRECTA!**
 
-Si se ha anunciado que tu teclado funciona con QMK pero no está en la lista, es probable que un desarrollador no se haya encargado de él aún o que todavía no hemos tenido la oportunidad de incluirlo. Abre un issue en [qmk_firmware](https://github.com/qmk/qmk_firmware/issues) solicitando soportar ese teclado un particular, si no hay un [Pull Request](https://github.com/qmk/qmk_firmware/pulls?q=is%3Aopen+is%3Apr+label%3Akeyboard) activo para ello. Hay también teclados que funcionan con QMK que están en las cuentas de github de sus manufacturantes. Acuérdate de comprobar esto también. 
+Si se ha anunciado que tu teclado funciona con QMK pero no está en la lista, es probable que un desarrollador no se haya encargado de él aún o que todavía no hemos tenido la oportunidad de incluirlo. Abre un issue en [qmk_firmware](https://github.com/qmk/qmk_firmware/issues) solicitando soportar ese teclado un particular, si no hay un [Pull Request](https://github.com/qmk/qmk_firmware/pulls?q=is%3Aopen+is%3Apr+label%3Akeyboard) activo para ello. Hay también teclados que funcionan con QMK que están en las cuentas de GitHub de sus manufacturantes. Acuérdate de comprobar esto también.
 
 ## Eligiendo el layout de tu teclado
 

docs/es/newbs_getting_started.md

@@ -43,7 +43,7 @@ instale el resto.
 
 Necesitarás instalar MSYS2 y Git.
 
-* Sigue las instrucciones de instalación en la [página de MSYS2](http://www.msys2.org).
+* Sigue las instrucciones de instalación en la [página de MSYS2](https://www.msys2.org).
 * Cierra las terminales abiertas de MSYS2 y abre una nueva termial de MSYS2 MinGW 64-bit.
 * Instala Git ejecutando este comando: `pacman -S git`.
 

docs/es/newbs_learn_more_resources.md

@@ -6,7 +6,7 @@ Recursos de Git:
 
 * [Excelente tutorial general](https://www.codecademy.com/learn/learn-git)
 * [Juego de Git para aprender usando ejemplos](https://learngitbranching.js.org/)
-* [Recursos de Git para aprender más sobre Github](getting_started_github.md)
+* [Recursos de Git para aprender más sobre GitHub](getting_started_github.md)
 * [Recursos de Git dirigidos específicamente a QMK](contributing.md)
 
 

docs/es/newbs_testing_debugging.md

@@ -10,8 +10,8 @@ Nota: Estos programas no los provée ni están relacionados con QMK.
 
 * [Switch Hitter](https://elitekeyboards.com/switchhitter.php) (Sólo Windows)
 * [Keyboard Viewer](https://www.imore.com/how-use-keyboard-viewer-your-mac) (Sólo Mac)
-* [Keyboard Tester](http://www.keyboardtester.com) (Aplicación web)
-* [Keyboard Checker](http://keyboardchecker.com) (Aplicación web)
+* [Keyboard Tester](https://www.keyboardtester.com) (Aplicación web)
+* [Keyboard Checker](https://keyboardchecker.com) (Aplicación web)
 
 ## Depurando
 
@@ -41,7 +41,9 @@ Para plataformas compatibles, [QMK Toolbox](https://github.com/qmk/qmk_toolbox)
 
 A veces, es útil imprimir mensajes de depuración desde tu [código personalizado](custom_quantum_functions.md). Hacerlo es bastante simple. Comienza incluyendo `print.h` al principio de tu fichero:
 
-    #include <print.h>
+```c
+#include "print.h"
+```
 
 Después de eso puedes utilzar algunas funciones print diferentes:
 

docs/faq_build.md

@@ -13,68 +13,29 @@ An example of using `sudo`, when your controller is ATMega32u4:
 
 or just:
 
-    $ sudo make <keyboard>:<keymap>:dfu
+    $ sudo make <keyboard>:<keymap>:flash
 
 Note that running `make` with `sudo` is generally ***not*** a good idea, and you should use one of the former methods, if possible.
 
-### Linux `udev` Rules
-On Linux, you'll need proper privileges to access the MCU. You can either use
-`sudo` when flashing firmware, or place these files in `/etc/udev/rules.d/`. Once added run the following:
-```console
+### Linux `udev` Rules :id=linux-udev-rules
+
+On Linux, you'll need proper privileges to communicate with the bootloader device. You can either use `sudo` when flashing firmware (not recommended), or place [this file](https://github.com/qmk/qmk_firmware/tree/master/util/udev/50-qmk.rules) into `/etc/udev/rules.d/`.
+
+Once added, run the following:
+
+```
 sudo udevadm control --reload-rules
 sudo udevadm trigger
 ```
 
-**/etc/udev/rules.d/50-atmel-dfu.rules:**
-```
-# Atmel ATMega32U4
-SUBSYSTEMS=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2ff4", MODE:="0666"
-# Atmel USBKEY AT90USB1287
-SUBSYSTEMS=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2ffb", MODE:="0666"
-# Atmel ATMega32U2
-SUBSYSTEMS=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2ff0", MODE:="0666"
-```
-
-**/etc/udev/rules.d/52-tmk-keyboard.rules:**
-```
-# tmk keyboard products     https://github.com/tmk/tmk_keyboard
-SUBSYSTEMS=="usb", ATTRS{idVendor}=="feed", MODE:="0666"
-```
-**/etc/udev/rules.d/54-input-club-keyboard.rules:**
+**Note:** With older versions of ModemManager (< 1.12), filtering only works when not in strict mode. The following commands can update that setting:
 
 ```
-# Input Club keyboard bootloader
-SUBSYSTEMS=="usb", ATTRS{idVendor}=="1c11", MODE:="0666"
-```
-
-**/etc/udev/rules.d/55-caterina.rules:**
-```
-# ModemManager should ignore the following devices
-ATTRS{idVendor}=="2a03", ENV{ID_MM_DEVICE_IGNORE}="1"
-ATTRS{idVendor}=="2341", ENV{ID_MM_DEVICE_IGNORE}="1"
-```
-
-**Note:** ModemManager filtering only works when not in strict mode, the following commands can update that settings:
-```console
-sudo sed -i 's/--filter-policy=strict/--filter-policy=default/' /lib/systemd/system/ModemManager.service
+printf '[Service]\nExecStart=\nExecStart=/usr/sbin/ModemManager --filter-policy=default' | sudo tee /etc/systemd/system/ModemManager.service.d/policy.conf
 sudo systemctl daemon-reload
 sudo systemctl restart ModemManager
 ```
 
-**/etc/udev/rules.d/56-dfu-util.rules:**
-```
-# stm32duino
-SUBSYSTEMS=="usb", ATTRS{idVendor}=="1eaf", ATTRS{idProduct}=="0003", MODE:="0666"
-# Generic stm32
-SUBSYSTEMS=="usb", ATTRS{idVendor}=="0483", ATTRS{idProduct}=="df11", MODE:="0666"
-```
-
-**/etc/udev/rules.d/57-bootloadhid.rules:**
-```
-# bootloadHID
-SUBSYSTEMS=="usb", ATTRS{idVendor}=="16c0", ATTRS{idProduct}=="05df", 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.
@@ -96,58 +57,8 @@ 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
-
-## BOOTLOADER_SIZE for AVR
-Note that Teensy2.0++ bootloader size is 2048byte. Some Makefiles may have wrong comment.
-
-```
-# Boot Section Size in *bytes*
-#   Teensy halfKay   512
-#   Teensy++ halfKay 2048
-#   Atmel DFU loader 4096       (TMK Alt Controller)
-#   LUFA bootloader  4096
-#   USBaspLoader     2048
-OPT_DEFS += -DBOOTLOADER_SIZE=2048
-```
-
-## `avr-gcc: internal compiler error: Abort trap: 6 (program cc1)` on MacOS
-This is an issue with updating on brew, causing symlinks that avr-gcc depend on getting mangled.
-
-The solution is to remove and reinstall all affected modules.
-
-```
-brew rm avr-gcc
-brew rm avr-gcc@8
-brew rm dfu-programmer
-brew rm dfu-util
-brew rm gcc-arm-none-eabi
-brew rm arm-gcc-bin@8
-brew rm avrdude
-brew install avr-gcc@8
-brew install dfu-programmer
-brew install dfu-util
-brew install arm-gcc-bin@8
-brew install avrdude
-brew link --force avr-gcc@8
-brew link --force arm-gcc-bin@8
-
-```
-
-### `avr-gcc` and LUFA
-
-If you updated your `avr-gcc` and you 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 8 in Homebrew.
-
-```
-brew uninstall --force avr-gcc
-brew install avr-gcc@8
-brew link --force avr-gcc@8
-```
+- https://www.obdev.at/products/vusb/license.html
+- https://www.mcselec.com/index.php?page=shop.product_details&flypage=shop.flypage&product_id=92&option=com_phpshop&Itemid=1
 
 ### I just flashed my keyboard and it does nothing/keypresses don't register - it's also ARM (rev6 planck, clueboard 60, hs60v2, etc...) (Feb 2019)
 Due to how EEPROM works on ARM based chips, saved settings may no longer be valid.  This affects the default layers, and *may*, under certain circumstances we are still figuring out, make the keyboard unusable.  Resetting the EEPROM will correct this.

docs/faq_debug.md

@@ -2,7 +2,94 @@
 
 This page details various common questions people have about troubleshooting their keyboards.
 
-# Debug Console
+## Debugging :id=debugging
+
+Your keyboard will output debug information if you have `CONSOLE_ENABLE = yes` in your `rules.mk`. By default the output is very limited, but you can turn on debug mode to increase the amount of debug output. Use the `DEBUG` keycode in your keymap, use the [Command](feature_command.md) feature to enable debug mode, or add the following code to your keymap.
+
+```c
+void keyboard_post_init_user(void) {
+  // Customise these values to desired behaviour
+  debug_enable=true;
+  debug_matrix=true;
+  //debug_keyboard=true;
+  //debug_mouse=true;
+}
+```
+
+## Debugging Tools
+
+There are two different tools you can use to debug your keyboard.
+
+### Debugging With QMK Toolbox
+
+For compatible platforms, [QMK Toolbox](https://github.com/qmk/qmk_toolbox) can be used to display debug messages from your keyboard.
+
+### Debugging With hid_listen
+
+Prefer a terminal based solution? [hid_listen](https://www.pjrc.com/teensy/hid_listen.html), provided by PJRC, can also be used to display debug messages. Prebuilt binaries for Windows,Linux,and MacOS are available.
+
+## Sending Your Own Debug Messages
+
+Sometimes it's useful to print debug messages from within your [custom code](custom_quantum_functions.md). Doing so is pretty simple. Start by including `print.h` at the top of your file:
+
+```c
+#include "print.h"
+```
+
+After that you can use a few different print functions:
+
+* `print("string")`: Print a simple string.
+* `uprintf("%s string", var)`: Print a formatted string
+* `dprint("string")` Print a simple string, but only when debug mode is enabled
+* `dprintf("%s string", var)`: Print a formatted string, but only when debug mode is enabled
+
+## Debug Examples
+
+Below is a collection of real world debugging examples. For additional information, refer to [Debugging/Troubleshooting QMK](faq_debug.md).
+
+### Which matrix position is this keypress?
+
+When porting, or when attempting to diagnose pcb issues, it can be useful to know if a keypress is scanned correctly. To enable logging for this scenario, add the following code to your keymaps `keymap.c`
+
+```c
+bool process_record_user(uint16_t keycode, keyrecord_t *record) {
+  // If console is enabled, it will print the matrix position and status of each key pressed
+#ifdef CONSOLE_ENABLE
+    uprintf("KL: kc: 0x%04X, col: %u, row: %u, pressed: %b, time: %u, interrupt: %b, count: %u\n", keycode, record->event.key.col, record->event.key.row, record->event.pressed, record->event.time, record->tap.interrupted, record->tap.count);
+#endif 
+  return true;
+}
+```
+
+Example output
+```text
+Waiting for device:.......
+Listening:
+KL: kc: 169, col: 0, row: 0, pressed: 1
+KL: kc: 169, col: 0, row: 0, pressed: 0
+KL: kc: 174, col: 1, row: 0, pressed: 1
+KL: kc: 174, col: 1, row: 0, pressed: 0
+KL: kc: 172, col: 2, row: 0, pressed: 1
+KL: kc: 172, col: 2, row: 0, pressed: 0
+```
+
+### How long did it take to scan for a keypress?
+
+When testing performance issues, it can be useful to know the frequency at which the switch matrix is being scanned. To enable logging for this scenario, add the following code to your keymaps `config.h`
+
+```c
+#define DEBUG_MATRIX_SCAN_RATE
+```
+
+Example output
+```text
+  > matrix scan frequency: 315
+  > matrix scan frequency: 313
+  > matrix scan frequency: 316
+  > matrix scan frequency: 316
+  > matrix scan frequency: 316
+  > matrix scan frequency: 316
+```
 
 ## `hid_listen` Can't Recognize Device
 When debug console of your device is not ready you will see like this:
@@ -11,7 +98,7 @@ When debug console of your device is not ready you will see like this:
 Waiting for device:.........
 ```
 
-once the device is plugged in then *hid_listen* finds it you will get this message:
+Once the device is plugged in then *hid_listen* finds it you will get this message:
 
 ```
 Waiting for new device:.........................
@@ -20,150 +107,25 @@ Listening:
 
 If you can't get this 'Listening:' message try building with `CONSOLE_ENABLE=yes` in [Makefile]
 
-You may need privilege to access the device on OS like Linux.
-- try `sudo hid_listen`
+You may need privileges to access the device an OS like Linux. Try `sudo hid_listen`.
+
+On many Linux distros you can avoid having to run hid_listen as root
+by creating a file called `/etc/udev/rules.d/70-hid-listen.rules` with
+the following content:
+
+```
+SUBSYSTEM=="hidraw", ATTRS{idVendor}=="abcd", ATTRS{idProduct}=="def1", TAG+="uaccess", RUN{builtin}+="uaccess"
+```
+
+Replace abcd and def1 with your keyboard's vendor and product id,
+letters must be lowercase. The `RUN{builtin}+="uaccess"` part is only
+needed for older distros.
+
 
 ## Can't Get Message on Console
 Check:
 - *hid_listen* finds your device. See above.
-- Enable debug with pressing **Magic**+d. See [Magic Commands](https://github.com/tmk/tmk_keyboard#magic-commands).
-- set `debug_enable=true`. See [Testing and Debugging](newbs_testing_debugging.md#debugging)
-- try using 'print' function instead of debug print. See **common/print.h**.
-- disconnect other devices with console function. See [Issue #97](https://github.com/tmk/tmk_keyboard/issues/97).
-
-## Linux or UNIX Like System Requires Super User Privilege
-Just use 'sudo' to execute *hid_listen* with privilege.
-```
-$ sudo hid_listen
-```
-
-Or add an *udev rule* for TMK devices with placing a file in rules directory. The directory may vary on each system.
-
-File: /etc/udev/rules.d/52-tmk-keyboard.rules(in case of Ubuntu)
-```
-# tmk keyboard products     https://github.com/tmk/tmk_keyboard
-SUBSYSTEMS=="usb", ATTRS{idVendor}=="feed", MODE:="0666"
-```
-
-***
-
-# Miscellaneous
-## Safety Considerations
-
-You probably don't want to "brick" your keyboard, making it impossible
-to rewrite firmware onto it.  Here are some of the parameters to show
-what things are (and likely aren't) too risky.
-
-- If your keyboard map does not include RESET, then, to get into DFU
-  mode, you will need to press the reset button on the PCB, which
-  requires unscrewing the bottom.
-- Messing with tmk_core / common files might make the keyboard
-  inoperable
-- Too large a .hex file is trouble; `make dfu` will erase the block,
-  test the size (oops, wrong order!), which errors out, failing to
-  flash the keyboard, leaving it in DFU mode.
-  - To this end, note that the maximum .hex file size on Planck is
-    7000h (28672 decimal)
-
-```
-Linking: .build/planck_rev4_cbbrowne.elf                                                            [OK]
-Creating load file for Flash: .build/planck_rev4_cbbrowne.hex                                       [OK]
-
-Size after:
-   text    data     bss     dec     hex filename
-      0   22396       0   22396    577c planck_rev4_cbbrowne.hex
-```
-
-  - The above file is of size 22396/577ch, which is less than
-    28672/7000h
-  - As long as you have a suitable alternative .hex file around, you
-    can retry, loading that one
-  - Some of the options you might specify in your keyboard's Makefile
-    consume extra memory; watch out for BOOTMAGIC_ENABLE,
-    MOUSEKEY_ENABLE, EXTRAKEY_ENABLE, CONSOLE_ENABLE, API_SYSEX_ENABLE
-- DFU tools do /not/ allow you to write into the bootloader (unless
-  you throw in extra fruit salad of options), so there is little risk
-  there.
-- EEPROM has around a 100000 write cycle.  You shouldn't rewrite the
-  firmware repeatedly and continually; that'll burn the EEPROM
-  eventually.
-
-## NKRO Doesn't work
-First you have to compile firmware with this build option `NKRO_ENABLE` in **Makefile**.
-
-Try `Magic` **N** command(`LShift+RShift+N` by default) when **NKRO** still doesn't work. You can use this command to toggle between **NKRO** and **6KRO** mode temporarily. In some situations **NKRO** doesn't work you need to switch to **6KRO** mode, in particular when you are in BIOS.
-
-If your firmware built with `BOOTMAGIC_ENABLE` you need to turn its switch on by `BootMagic` **N** command(`Space+N` by default). This setting is stored in EEPROM and kept over power cycles.
-
-https://github.com/tmk/tmk_keyboard#boot-magic-configuration---virtual-dip-switch
-
-
-## TrackPoint Needs Reset Circuit (PS/2 Mouse Support)
-Without reset circuit you will have inconsistent result due to improper initialize of the hardware. See circuit schematic of TPM754.
-
-- http://geekhack.org/index.php?topic=50176.msg1127447#msg1127447
-- http://www.mikrocontroller.net/attachment/52583/tpm754.pdf
-
-
-## Can't Read Column of Matrix Beyond 16
-Use `1UL<<16` instead of `1<<16` in `read_cols()` in [matrix.h] when your columns goes beyond 16.
-
-In C `1` means one of [int] type which is [16 bit] in case of AVR so you can't shift left more than 15. You will get unexpected zero when you say `1<<16`. You have to use [unsigned long] type with `1UL`.
-
-http://deskthority.net/workshop-f7/rebuilding-and-redesigning-a-classic-thinkpad-keyboard-t6181-60.html#p146279
-
-## Special Extra Key Doesn't Work (System, Audio Control Keys)
-You need to define `EXTRAKEY_ENABLE` in `rules.mk` to use them in QMK.
-
-```
-EXTRAKEY_ENABLE = yes          # Audio control and System control
-```
-
-## Wakeup from Sleep Doesn't Work
-
-In Windows check `Allow this device to wake the computer` setting in Power **Management property** tab of **Device Manager**. Also check BIOS setting.
-
-Pressing any key during sleep should wake host.
-
-## Using Arduino?
-
-**Note that Arduino pin naming is different from actual chip.** For example, Arduino pin `D0` is not `PD0`. Check circuit with its schematics yourself.
-
-- http://arduino.cc/en/uploads/Main/arduino-leonardo-schematic_3b.pdf
-- http://arduino.cc/en/uploads/Main/arduino-micro-schematic.pdf
-
-Arduino Leonardo and micro have **ATMega32U4** and can be used for TMK, though Arduino bootloader may be a problem.
-
-## Enabling JTAG
-
-By default, the JTAG debugging interface is disabled as soon as the keyboard starts up. JTAG-capable MCUs come from the factory with the `JTAGEN` fuse set, and it takes over certain pins of the MCU that the board may be using for the switch matrix, LEDs, etc.
-
-If you would like to keep JTAG enabled, just add the following to your `config.h`:
-
-```c
-#define NO_JTAG_DISABLE
-```
-
-## USB 3 Compatibility
-I heard some people have a problem with USB 3 port, try USB 2 port.
-
-
-## Mac Compatibility
-### OS X 10.11 and Hub
-https://geekhack.org/index.php?topic=14290.msg1884034#msg1884034
-
-
-## Problem on BIOS (UEFI)/Resume (Sleep & Wake)/Power Cycles
-Some people reported their keyboard stops working on BIOS and/or after resume(power cycles).
-
-As of now root of its cause is not clear but some build options seem to be related. In Makefile try to disable those options like `CONSOLE_ENABLE`, `NKRO_ENABLE`, `SLEEP_LED_ENABLE` and/or others.
-
-https://github.com/tmk/tmk_keyboard/issues/266
-https://geekhack.org/index.php?topic=41989.msg1967778#msg1967778
-
-
-
-## FLIP Doesn't Work
-### `AtLibUsbDfu.dll` Not Found
-Remove current driver and reinstall one FLIP provides from DeviceManager.
-http://imgur.com/a/bnwzy
+- Enable debug by pressing **Magic**+d. See [Magic Commands](https://github.com/tmk/tmk_keyboard#magic-commands).
+- Set `debug_enable=true`. See [Debugging](#debugging)
+- Try using `print` function instead of debug print. See **common/print.h**.
+- Disconnect other devices with console function. See [Issue #97](https://github.com/tmk/tmk_keyboard/issues/97).

docs/faq_general.md

@@ -34,7 +34,7 @@ Additionally, you can find additional `git` and GitHub related links [here](newb
 
 Awesome! Open up a Pull Request for it. We'll review the code, and merge it!
 
-### What if I want to do brand it with `QMK`?
+### What if I want to brand it with `QMK`?
 
 That's amazing! We would love to assist you with that!
 

docs/faq_keymap.md

@@ -11,7 +11,7 @@ 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/bf431647d1001cff5eff20ae55621e9a -->
+<!-- Source for this image: https://www.keyboard-layout-editor.com/#/gists/bf431647d1001cff5eff20ae55621e9a -->
 ![Keyboard Layout Image](https://i.imgur.com/5wsh5wM.png)
 
 ## How Can I Make Custom Names For Complex Keycodes?
@@ -42,8 +42,8 @@ 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
+* https://en.wikipedia.org/wiki/Magic_SysRq_key
+* https://en.wikipedia.org/wiki/System_request
 
 ## Power Keys Aren't Working
 
@@ -60,13 +60,13 @@ Modifier keys or layers can be stuck unless layer switching is configured proper
 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://geekhack.org/index.php?topic=57008.msg1492604#msg1492604
 * https://github.com/tmk/tmk_keyboard/issues/248
 
 
 ## Mechanical Lock Switch Support
 
-This feature is for *mechanical lock switch* like [this Alps one](http://deskthority.net/wiki/Alps_SKCL_Lock). You can enable it by adding this to your `config.h`:
+This feature is for *mechanical lock switch* like [this Alps one](https://deskthority.net/wiki/Alps_SKCL_Lock). You can enable it by adding this to your `config.h`:
 
 ```
 #define LOCKING_SUPPORT_ENABLE

docs/faq_misc.md

@@ -0,0 +1,117 @@
+# Miscellaneous FAQ
+
+## How do I test my keyboard? :id=testing
+
+Testing your keyboard is usually pretty straightforward. Press every single key and make sure it sends the keys you expect. You can use [QMK Configurator](https://config.qmk.fm/#/test/)'s test mode to check your keyboard, even if it doesn't run QMK.
+
+## Safety Considerations
+
+You probably don't want to "brick" your keyboard, making it impossible
+to rewrite firmware onto it.  Here are some of the parameters to show
+what things are (and likely aren't) too risky.
+
+- If your keyboard map does not include RESET, then, to get into DFU
+  mode, you will need to press the reset button on the PCB, which
+  requires unscrewing the bottom.
+- Messing with tmk_core / common files might make the keyboard
+  inoperable
+- Too large a .hex file is trouble; `make dfu` will erase the block,
+  test the size (oops, wrong order!), which errors out, failing to
+  flash the keyboard, leaving it in DFU mode.
+  - To this end, note that the maximum .hex file size on e.g. Planck
+    is 7000h (28672 decimal)
+
+```
+Linking: .build/planck_rev4_cbbrowne.elf                                                            [OK]
+Creating load file for Flash: .build/planck_rev4_cbbrowne.hex                                       [OK]
+
+Size after:
+   text    data     bss     dec     hex filename
+      0   22396       0   22396    577c planck_rev4_cbbrowne.hex
+```
+
+  - The above file is of size 22396/577ch, which is less than
+    28672/7000h
+  - As long as you have a suitable alternative .hex file around, you
+    can retry, loading that one
+  - Some of the options you might specify in your keyboard's Makefile
+    consume extra memory; watch out for BOOTMAGIC_ENABLE,
+    MOUSEKEY_ENABLE, EXTRAKEY_ENABLE, CONSOLE_ENABLE, API_SYSEX_ENABLE
+- DFU tools do /not/ allow you to write into the bootloader (unless
+  you throw in an extra fruit salad of options), so there is little risk
+  there.
+- EEPROM has around a 100000 (100k) write cycle.  You shouldn't rewrite
+  the firmware repeatedly and continually; that'll burn the EEPROM
+  eventually.
+
+## NKRO Doesn't work
+First you have to compile firmware with the build option `NKRO_ENABLE` in **Makefile**.
+
+Try `Magic` **N** command(`LShift+RShift+N` by default) when **NKRO** still doesn't work. You can use this command to toggle between **NKRO** and **6KRO** mode temporarily. In some situations **NKRO** doesn't work and you will need to switch to **6KRO** mode, in particular when you are in BIOS.
+
+If your firmware was built with `BOOTMAGIC_ENABLE` you need to turn its switch on by `BootMagic` **N** command(`Space+N` by default). This setting is stored in EEPROM and kept over power cycles.
+
+https://github.com/tmk/tmk_keyboard#boot-magic-configuration---virtual-dip-switch
+
+
+## TrackPoint Needs Reset Circuit (PS/2 Mouse Support)
+Without reset circuit you will have inconsistent result due to improper initialization of the hardware. See circuit schematic of TPM754:
+
+- https://geekhack.org/index.php?topic=50176.msg1127447#msg1127447
+- https://www.mikrocontroller.net/attachment/52583/tpm754.pdf
+
+
+## Can't Read Column of Matrix Beyond 16
+Use `1UL<<16` instead of `1<<16` in `read_cols()` in [matrix.h] when your columns goes beyond 16.
+
+In C `1` means one of [int] type which is [16 bit] in case of AVR, so you can't shift left more than 15. Thus, calculating `1<<16` will unexpectedly equal zero. To work around this, you have to use [unsigned long] type with `1UL`.
+
+https://deskthority.net/workshop-f7/rebuilding-and-redesigning-a-classic-thinkpad-keyboard-t6181-60.html#p146279
+
+## Special Extra Key Doesn't Work (System, Audio Control Keys)
+You need to define `EXTRAKEY_ENABLE` in `rules.mk` to use them in QMK.
+
+```
+EXTRAKEY_ENABLE = yes          # Audio control and System control
+```
+
+## Wake from Sleep Doesn't Work
+
+In Windows check `Allow this device to wake the computer` setting in **Power Management** property tab of **Device Manager**. Also check your BIOS settings. Pressing any key during sleep should wake host.
+
+## Using Arduino?
+
+**Note that Arduino pin naming is different from actual chip.** For example, Arduino pin `D0` is not `PD0`. Check circuit with its schematics yourself.
+
+- https://arduino.cc/en/uploads/Main/arduino-leonardo-schematic_3b.pdf
+- https://arduino.cc/en/uploads/Main/arduino-micro-schematic.pdf
+
+Arduino Leonardo and micro have **ATMega32U4** and can be used for TMK, though Arduino bootloader may be a problem.
+
+## Enabling JTAG
+
+By default, the JTAG debugging interface is disabled as soon as the keyboard starts up. JTAG-capable MCUs come from the factory with the `JTAGEN` fuse set, and it takes over certain pins of the MCU that the board may be using for the switch matrix, LEDs, etc.
+
+If you would like to keep JTAG enabled, just add the following to your `config.h`:
+
+```c
+#define NO_JTAG_DISABLE
+```
+
+## USB 3 Compatibility
+Some problems can be fixed by switching from a USB 3.x port to a USB 2.0 port.
+
+
+## Mac Compatibility
+### OS X 10.11 and Hub
+See here: https://geekhack.org/index.php?topic=14290.msg1884034#msg1884034
+
+
+## Problem in BIOS (UEFI) Setup/Resume (Sleep & Wake)/Power Cycles
+Some people reported their keyboard stops working in BIOS and/or after resume(power cycles).
+
+As of now the root cause is not clear, but some build options seem to be related. In Makefile, try to disable options like `CONSOLE_ENABLE`, `NKRO_ENABLE`, `SLEEP_LED_ENABLE` and/or others.
+
+More info:
+- https://github.com/tmk/tmk_keyboard/issues/266
+- https://geekhack.org/index.php?topic=41989.msg1967778#msg1967778

docs/feature_advanced_keycodes.md

@@ -2,23 +2,161 @@
 
 These allow you to combine a modifier with a keycode. When pressed, the keydown event for the modifier, then `kc` will be sent. On release, the keyup event for `kc`, then the modifier will be sent.
 
-|Key       |Aliases                        |Description                                         |
-|----------|-------------------------------|----------------------------------------------------|
-|`LCTL(kc)`|`C(kc)`                        |Hold Left Control and press `kc`                    |
-|`LSFT(kc)`|`S(kc)`                        |Hold Left Shift and press `kc`                      |
-|`LALT(kc)`|`A(kc)`                        |Hold Left Alt and press `kc`                        |
-|`LGUI(kc)`|`G(kc)`, `LCMD(kc)`, `LWIN(kc)`|Hold Left GUI and press `kc`                        |
-|`RCTL(kc)`|                               |Hold Right Control and press `kc`                   |
-|`RSFT(kc)`|                               |Hold Right Shift and press `kc`                     |
-|`RALT(kc)`|`ALGR(kc)`                     |Hold Right Alt and press `kc`                       |
-|`RGUI(kc)`|`RCMD(kc)`, `LWIN(kc)`         |Hold Right GUI and press `kc`                       |
-|`SGUI(kc)`|`SCMD(kc)`, `SWIN(kc)`         |Hold Left Shift and GUI and press `kc`              |
-|`LCA(kc)` |                               |Hold Left Control and Alt and press `kc`            |
-|`LCAG(kc)`|                               |Hold Left Control, Alt and GUI and press `kc`       |
-|`MEH(kc)` |                               |Hold Left Control, Shift and Alt and press `kc`     |
-|`HYPR(kc)`|                               |Hold Left Control, Shift, Alt and GUI and press `kc`|
+|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)`, `LOPT(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)`|`ROPT(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`              |
+|`LSA(kc)` |                               |Hold Left Shift and Left Alt and press `kc`           |
+|`RSA(kc)` |`SAGR(kc)`                     |Hold Right Shift and Right Alt (AltGr) and press `kc` |
+|`RCS(kc)` |                               |Hold Right Control and Right Shift and press `kc`     |
+|`LCAG(kc)`|                               |Hold Left Control, Alt and GUI and press `kc`         |
+|`MEH(kc)` |                               |Hold Left Control, Shift and Alt and press `kc`       |
+|`HYPR(kc)`|                               |Hold Left Control, Shift, Alt and GUI and press `kc`  |
 
-You can also chain them, for example `LCTL(LALT(KC_DEL))` makes a key that sends Control+Alt+Delete with a single keypress.
+You can also chain them, for example `LCTL(LALT(KC_DEL))` or `C(A(KC_DEL))` makes a key that sends Control+Alt+Delete with a single keypress.
+
+# Checking Modifier State :id=checking-modifier-state
+
+The current modifier state can mainly be accessed with two functions: `get_mods()` for normal modifiers and modtaps and `get_oneshot_mods()` for one-shot modifiers (unless they're held, in which case they act like normal modifier keys).
+
+The presence of one or more specific modifiers in the current modifier state can be detected by ANDing the modifier state with a mod mask corresponding to the set of modifiers you want to match for. The reason why bitwise operators are used is that the modifier state is stored as a single byte in the format (GASC)<sub>R</sub>(GASC)<sub>L</sub>.
+
+Thus, to give an example, `01000010` would be the internal representation of LShift+RAlt.
+For more information on bitwise operators in C, click [here](https://en.wikipedia.org/wiki/Bitwise_operations_in_C) to open the Wikipedia page on the topic.
+
+In practice, this means that you can check whether a given modifier is active with `get_mods() & MOD_BIT(KC_<modifier>)` (see the [list of modifier keycodes](keycodes_basic.md#modifiers)) or with `get_mods() & MOD_MASK_<modifier>` if the difference between left and right hand modifiers is not important and you want to match both. Same thing can be done for one-shot modifiers if you replace `get_mods()` with `get_oneshot_mods()`.
+
+To check that *only* a specific set of mods is active at a time, AND the modifier state and your desired mod mask as explained above and compare the result to the mod mask itself: `get_mods() & <mod mask> == <mod mask>`.
+
+For example, let's say you want to trigger a piece of custom code if one-shot left control and one-shot left shift are on but every other one-shot mods are off. To do so, you can compose the desired mod mask by combining the mod bits for left control and shift with `(MOD_BIT(KC_LCTL) | MOD_BIT(KC_LSFT))` and then plug it in: `get_oneshot_mods & (MOD_BIT(KC_LCTL) | MOD_BIT(KC_LSFT)) == (MOD_BIT(KC_LCTL) | MOD_BIT(KC_LSFT))`. Using `MOD_MASK_CS` instead for the mod bitmask would have forced you to press four modifier keys (both versions of control and shift) to fulfill the condition.
+
+The full list of mod masks is as follows:
+
+| Mod Mask Name      | Matching Modifiers                             |
+|--------------------|------------------------------------------------|
+| `MOD_MASK_CTRL`    | LCTRL       , RCTRL                            |
+| `MOD_MASK_SHIFT`   | LSHIFT      , RSHIFT                           |
+| `MOD_MASK_ALT`     | LALT        , RALT                             |
+| `MOD_MASK_GUI`     | LGUI        , RGUI                             |
+| `MOD_MASK_CS`      | CTRL        , SHIFT                            |
+| `MOD_MASK_CA`      | (L/R)CTRL   , (L/R)ALT                         |
+| `MOD_MASK_CG`      | (L/R)CTRL   , (L/R)GUI                         |
+| `MOD_MASK_SA`      | (L/R)SHIFT  , (L/R)ALT                         |
+| `MOD_MASK_SG`      | (L/R)SHIFT  , (L/R)GUI                         |
+| `MOD_MASK_AG`      | (L/R)ALT    , (L/R)GUI                         |
+| `MOD_MASK_CSA`     | (L/R)CTRL   , (L/R)SHIFT , (L/R)ALT            |
+| `MOD_MASK_CSG`     | (L/R)CTRL   , (L/R)SHIFT , (L/R)GUI            |
+| `MOD_MASK_CAG`     | (L/R)CTRL   , (L/R)ALT   , (L/R)GUI            |
+| `MOD_MASK_SAG`     | (L/R)SHIFT  , (L/R)ALT   , (L/R)GUI            |
+| `MOD_MASK_CSAG`    | (L/R)CTRL   , (L/R)SHIFT , (L/R)ALT , (L/R)GUI |
+
+Aside from accessing the currently active modifiers using `get_mods()`, there exists some other functions you can use to modify the modifier state, where the `mods` argument refers to the modifiers bitmask.
+
+* `add_mods(mods)`: Enable `mods` without affecting any other modifiers
+* `register_mods(mods)`: Like `add_mods` but send a keyboard report immediately.
+* `del_mods(mods)`: Disable `mods` without affecting any other modifiers
+* `unregister_mods(mods)`: Like `del_mods` but send a keyboard report immediately.
+* `set_mods(mods)`: Overwrite current modifier state with `mods`
+* `clear_mods()`: Reset the modifier state by disabling all modifiers
+
+Similarly, in addition to `get_oneshot_mods()`, there also exists these functions for one-shot mods:
+
+* `add_oneshot_mods(mods)`: Enable `mods` without affecting any other one-shot modifiers
+* `del_oneshot_mods(mods)`: Disable `mods` without affecting any other one-shot modifiers
+* `set_oneshot_mods(mods)`: Overwrite current one-shot modifier state with `mods`
+* `clear_oneshot_mods()`: Reset the one-shot modifier state by disabling all one-shot modifiers
+
+## Examples :id=examples
+
+The following examples use [advanced macro functions](feature_macros.md#advanced-macro-functions) which you can read more about in the [documentation page on macros](feature_macros.md).
+
+### Alt + Escape for Alt + Tab :id=alt-escape-for-alt-tab
+
+Simple example where chording Left Alt with `KC_ESC` makes it behave like `KC_TAB` for alt-tabbing between applications. This example strictly checks if only Left Alt is active, meaning you can't do Alt+Shift+Esc to switch between applications in reverse order. Also keep in mind that this removes the ability to trigger the actual Alt+Escape keyboard shortcut, though it keeps the ability to do AltGr+Escape.
+
+```c
+bool process_record_user(uint16_t keycode, keyrecord_t *record) {
+    switch (keycode) {
+
+    case KC_ESC:
+        // Detect the activation of only Left Alt
+        if ((get_mods() & MOD_BIT(KC_LALT)) == MOD_BIT(KC_LALT)) {
+            if (record->event.pressed) {
+                // No need to register KC_LALT because it's already active.
+                // The Alt modifier will apply on this KC_TAB.
+                register_code(KC_TAB);
+            } else {
+                unregister_code(KC_TAB);
+            }
+            // Do not let QMK process the keycode further
+            return false;
+        }
+        // Else, let QMK process the KC_ESC keycode as usual
+        return true;
+
+    }
+    return true;
+};
+```
+
+### Shift + Backspace for Delete :id=shift-backspace-for-delete
+
+Advanced example where the original behaviour of shift is cancelled when chorded with `KC_BSPC` and is instead fully replaced by `KC_DEL`. Two main variables are created to make this work well: `mod_state` and `delkey_registered`. The first one stores the modifier state and is used to restore it after registering `KC_DEL`. The second variable is a boolean variable (true or false) which keeps track of the status of `KC_DEL` to manage the release of the whole Backspace/Delete key correctly.
+
+As opposed to the previous example, this doesn't use strict modifier checking. Pressing `KC_BSPC` while one or two shifts are active is enough to trigger this custom code, regardless of the state of other modifiers. That approach offers some perks: Ctrl+Shift+Backspace lets us delete the next word (Ctrl+Delete) and Ctrl+Alt+Shift+Backspace lets us execute the Ctrl+Alt+Del keyboard shortcut.
+
+```c
+// Initialize variable holding the binary
+// representation of active modifiers.
+uint8_t mod_state;
+bool process_record_user(uint16_t keycode, keyrecord_t *record) {
+    // Store the current modifier state in the variable for later reference
+    mod_state = get_mods();
+    switch (keycode) {
+
+    case KC_BSPC:
+        {
+        // Initialize a boolean variable that keeps track
+        // of the delete key status: registered or not?
+        static bool delkey_registered;
+        if (record->event.pressed) {
+            // Detect the activation of either shift keys
+            if (mod_state & MOD_MASK_SHIFT) {
+                // First temporarily canceling both shifts so that
+                // shift isn't applied to the KC_DEL keycode
+                del_mods(MOD_MASK_SHIFT);
+                register_code(KC_DEL);
+                // Update the boolean variable to reflect the status of KC_DEL
+                delkey_registered = true;
+                // Reapplying modifier state so that the held shift key(s)
+                // still work even after having tapped the Backspace/Delete key.
+                set_mods(mod_state);
+                return false;
+            }
+        } else { // on release of KC_BSPC
+            // In case KC_DEL is still being sent even after the release of KC_BSPC
+            if (delkey_registered) {
+                unregister_code(KC_DEL);
+                delkey_registered = false;
+                return false;
+            }
+        }
+        // Let QMK process the KC_BSPC keycode as usual outside of shift
+        return true;
+    }
+
+    }
+    return true;
+};
+```
 
 # Legacy Content :id=legacy-content
 

docs/feature_audio.md

@@ -1,21 +1,117 @@
 # Audio
 
-Your keyboard can make sounds! If you've got a Planck, Preonic, or basically any AVR keyboard that allows access to certain PWM-capable pins, you can hook up a simple speaker and make it beep. You can use those beeps to indicate layer transitions, modifiers, special keys, or just to play some funky 8bit tunes.
+Your keyboard can make sounds! If you've got a spare pin 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:
+To activate this feature, add `AUDIO_ENABLE = yes` to your `rules.mk`.
 
-Timer 1:
-`#define B5_AUDIO`
-`#define B6_AUDIO`
-`#define B7_AUDIO`
+## AVR based boards
+On Atmega32U4 based boards, up to two simultaneous tones can be rendered.
+With one speaker connected to a PWM capable pin on PORTC driven by timer 3 and the other on one of the PWM pins on PORTB driven by timer 1.
 
-Timer 3:
-`#define C4_AUDIO`
-`#define C5_AUDIO`
-`#define C6_AUDIO`
+The following pins can be configured as audio outputs in `config.h` - for one speaker set either one out of:
 
-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:
+* `#define AUDIO_PIN C4`
+* `#define AUDIO_PIN C5`
+* `#define AUDIO_PIN C6`
+* `#define AUDIO_PIN B5`
+* `#define AUDIO_PIN B6`
+* `#define AUDIO_PIN B7`
 
+and *optionally*, for a second speaker, one of:
+* `#define AUDIO_PIN_ALT B5`
+* `#define AUDIO_PIN_ALT B6`
+* `#define AUDIO_PIN_ALT B7`
+
+### Wiring
+per speaker is - for example with a piezo buzzer - the black lead to Ground, and the red lead connected to the selected AUDIO_PIN for the primary; and similarly with AUDIO_PIN_ALT for the secondary.
+
+
+## ARM based boards
+for more technical details, see the notes on [Audio driver](audio_driver.md).
+
+<!-- because I'm not sure where to fit this in: https://waveeditonline.com/ -->
+### DAC (basic)
+Most STM32 MCUs have DAC peripherals, with a notable exception of the STM32F1xx series. Generally, the DAC peripheral drives pins A4 or A5. To enable DAC-based audio output on STM32 devices, add `AUDIO_DRIVER = dac_basic` to `rules.mk` and set in `config.h` either:
+
+`#define AUDIO_PIN A4` or `#define AUDIO_PIN A5`
+
+the other DAC channel can optionally be used with a secondary speaker, just set:
+
+`#define AUDIO_PIN_ALT A4` or `#define AUDIO_PIN_ALT A5`
+
+Do note though that the dac_basic driver is only capable of reproducing one tone per speaker/channel at a time, for more tones simultaneously, try the dac_additive driver.
+
+#### Wiring:
+for two piezos, for example configured as `AUDIO_PIN A4` and `AUDIO_PIN_ALT A5` would be: red lead to A4 and black to Ground, and similarly with the second one: A5 = red, and Ground = black
+
+another alternative is to drive *one* piezo with both DAC pins - for an extra "push".
+wiring red to A4 and black to A5 (or the other way round) and add `#define AUDIO_PIN_ALT_AS_NEGATIVE` to `config.h`
+
+##### Proton-C Example:
+The Proton-C comes (optionally) with one 'builtin' piezo, which is wired to A4+A5.
+For this board `config.h` would include these defines:
+
+```c
+#define AUDIO_PIN A5
+#define AUDIO_PIN_ALT A4
+#define AUDIO_PIN_ALT_AS_NEGATIVE
+```
+
+### DAC (additive)
+Another option, besides dac_basic (which produces sound through a square-wave), is to use the DAC to do additive wave synthesis.
+With a number of predefined wave-forms or by providing your own implementation to generate samples on the fly.
+To use this feature set `AUDIO_DRIVER = dac_additive` in your `rules.mk`, and select in `config.h` EITHER `#define AUDIO_PIN A4` or `#define AUDIO_PIN A5`.
+
+The used waveform *defaults* to sine, but others can be selected by adding one of the following defines to `config.h`:
+
+* `#define AUDIO_DAC_SAMPLE_WAVEFORM_SINE`
+* `#define AUDIO_DAC_SAMPLE_WAVEFORM_TRIANGLE`
+* `#define AUDIO_DAC_SAMPLE_WAVEFORM_TRAPEZOID`
+* `#define AUDIO_DAC_SAMPLE_WAVEFORM_SQUARE`
+
+Should you rather choose to generate and use your own sample-table with the DAC unit, implement `uint16_t dac_value_generate(void)` with your keyboard - for an example implementation see keyboards/planck/keymaps/synth_sample or keyboards/planck/keymaps/synth_wavetable
+
+
+### PWM (software)
+if the DAC pins are unavailable (or the MCU has no usable DAC at all, like STM32F1xx); PWM can be an alternative.
+Note that there is currently only one speaker/pin supported.
+
+set in `rules.mk`:
+
+`AUDIO_DRIVER = pwm_software` and in `config.h`: 
+`#define AUDIO_PIN C13` (can be any pin) to have the selected pin output a pwm signal, generated from a timer callback which toggles the pin in software.
+
+#### Wiring
+the usual piezo wiring: red goes to the selected AUDIO_PIN, black goes to ground.
+
+OR if you can chose to drive one piezo with two pins, for example `#define AUDIO_PIN B1`, `#define AUDIO_PIN_ALT B2` in `config.h`, with `#define AUDIO_PIN_ALT_AS_NEGATIVE` - then the red lead could go to B1, the black to B2.
+
+### PWM (hardware)
+STM32F1xx have to fall back to using PWM, but can do so in hardware; but again on currently only one speaker/pin.
+
+`AUDIO_DRIVER = pwm_hardware` in `rules.mk`, and in `config.h`:
+`#define AUDIO_PIN A8`
+`#define AUDIO_PWM_DRIVER PWMD1`
+`#define AUDIO_PWM_CHANNEL 1`
+(as well as `#define AUDIO_PWM_PAL_MODE 42` if you are on STM32F2 or larger)
+which will use Timer 1 to directly drive pin PA8 through the PWM hardware (TIM1_CH1 = PA8).
+Should you want to use the pwm-hardware on another pin and timer - be ready to dig into the STM32 data-sheet to pick the right TIMx_CHy and pin-alternate function.
+
+
+## Tone Multiplexing
+Since most drivers can only render one tone per speaker at a time (with the one exception: arm dac-additive) there also exists a "workaround-feature" that does time-slicing/multiplexing - which does what the name implies: cycle through a set of active tones (e.g. when playing chords in Music Mode) at a given rate, and put one tone at a time out through the one/few speakers that are available.
+
+To enable this feature, and configure a starting-rate, add the following defines to `config.h`:
+```c
+#define AUDIO_ENABLE_TONE_MULTIPLEXING
+#define AUDIO_TONE_MULTIPLEXING_RATE_DEFAULT 10
+```
+
+The audio core offers interface functions to get/set/change the tone multiplexing rate from within `keymap.c`.
+
+
+## Songs
+There's a couple of different sounds that will automatically be enabled without any other configuration:
 ```
 STARTUP_SONG // plays when the keyboard starts up (audio.c)
 GOODBYE_SONG // plays when you press the RESET key (quantum.c)
@@ -67,15 +163,34 @@ The available keycodes for audio are:
 * `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. 
+!> 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.
+
+## Tempo
+the 'speed' at which SONGs are played is dictated by the set Tempo, which is measured in beats-per-minute. Note lengths are defined relative to that.
+The initial/default tempo is set to 120 bpm, but can be configured by setting `TEMPO_DEFAULT` in `config.c`.
+There is also a set of functions to modify the tempo from within the user/keymap code:
+```c
+void audio_set_tempo(uint8_t tempo);
+void audio_increase_tempo(uint8_t tempo_change);
+void audio_decrease_tempo(uint8_t tempo_change);
+```
 
 ## 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`:
+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 `AUDIO_DAC_SAMPLE_MAX` in your `config.h`:
 
 ```c
-#define DAC_SAMPLE_MAX 65535U
+#define AUDIO_DAC_SAMPLE_MAX 4095U
 ```
+the DAC usually runs in 12Bit mode, hence a volume of 100% = 4095U
+
+Note: this only adjusts the volume aka 'works' if you stick to WAVEFORM_SQUARE, since its samples are generated on the fly - any other waveform uses a hardcoded/precomputed sample-buffer.
+
+## Voices
+Aka "audio effects", different ones can be enabled by setting in `config.h` these defines:
+`#define AUDIO_VOICES` to enable the feature, and `#define AUDIO_VOICE_DEFAULT something` to select a specific effect
+for details see quantum/audio/voices.h and .c
+
 
 ## Music Mode
 
@@ -176,7 +291,7 @@ You can configure the default, min and max frequencies, the stepping and built i
 |--------|---------------|-------------|
 | `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_MAX` | 1500.0f | Sets the highest frequency. Too high may result in coworkers attacking you. |
 | `AUDIO_CLICKY_FREQ_FACTOR` | 1.18921f| Sets the stepping of UP/DOWN key codes.  This is a multiplicative factor.  The default steps the frequency up/down by a musical minor third.  |
 | `AUDIO_CLICKY_FREQ_RANDOMNESS`     |  0.05f |  Sets a factor of randomness for the clicks, Setting this to `0f` will make each click identical, and `1.0f` will make this sound much like the 90's computer screen scrolling/typing effect. | 
 | `AUDIO_CLICKY_DELAY_DURATION` | 1 | An integer note duration where 1 is 1/16th of the tempo, or a sixty-fourth note (see `quantum/audio/musical_notes.h` for implementation details). The main clicky effect will be delayed by this duration.  Adjusting this to values around 6-12 will help compensate for loud switches. |
@@ -186,8 +301,7 @@ You can configure the default, min and max frequencies, the stepping and built i
 
 ## MIDI Functionality
 
-This is still a WIP, but check out `quantum/process_keycode/process_midi.c` to see what's happening. Enable from the Makefile.
-
+See [MIDI](feature_midi.md)
 
 ## Audio Keycodes
 
@@ -204,120 +318,3 @@ This is still a WIP, but check out `quantum/process_keycode/process_midi.c` to s
 |`MU_OFF`        |         |Turns off Music Mode              |
 |`MU_TOG`        |         |Toggles Music Mode                |
 |`MU_MOD`        |         |Cycles through the music modes    |
-
-<!-- FIXME: this formatting needs work
-
-## Audio
-
-```c
-#ifdef AUDIO_ENABLE
-    AU_ON,
-    AU_OFF,
-    AU_TOG,
-
-    #ifdef FAUXCLICKY_ENABLE
-        FC_ON,
-        FC_OFF,
-        FC_TOG,
-    #endif
-
-    // Music mode on/off/toggle
-    MU_ON,
-    MU_OFF,
-    MU_TOG,
-
-    // Music voice iterate
-    MUV_IN,
-    MUV_DE,
-#endif
-```
-
-### Midi
-
-#if !MIDI_ENABLE_STRICT || (defined(MIDI_ENABLE) && defined(MIDI_BASIC))
-    MI_ON,  // send midi notes when music mode is enabled
-    MI_OFF, // don't send midi notes when music mode is enabled
-#endif
-
-MIDI_TONE_MIN,
-MIDI_TONE_MAX
-
-MI_C = MIDI_TONE_MIN,
-MI_Cs,
-MI_Db = MI_Cs,
-MI_D,
-MI_Ds,
-MI_Eb = MI_Ds,
-MI_E,
-MI_F,
-MI_Fs,
-MI_Gb = MI_Fs,
-MI_G,
-MI_Gs,
-MI_Ab = MI_Gs,
-MI_A,
-MI_As,
-MI_Bb = MI_As,
-MI_B,
-
-MIDI_TONE_KEYCODE_OCTAVES > 1
-
-where x = 1-5:
-MI_C_x,
-MI_Cs_x,
-MI_Db_x = MI_Cs_x,
-MI_D_x,
-MI_Ds_x,
-MI_Eb_x = MI_Ds_x,
-MI_E_x,
-MI_F_x,
-MI_Fs_x,
-MI_Gb_x = MI_Fs_x,
-MI_G_x,
-MI_Gs_x,
-MI_Ab_x = MI_Gs_x,
-MI_A_x,
-MI_As_x,
-MI_Bb_x = MI_As_x,
-MI_B_x,
-
-MI_OCT_Nx 1-2
-MI_OCT_x 0-7
-MIDI_OCTAVE_MIN = MI_OCT_N2,
-MIDI_OCTAVE_MAX = MI_OCT_7,
-MI_OCTD, // octave down
-MI_OCTU, // octave up
-
-MI_TRNS_Nx 1-6
-MI_TRNS_x 0-6
-MIDI_TRANSPOSE_MIN = MI_TRNS_N6,
-MIDI_TRANSPOSE_MAX = MI_TRNS_6,
-MI_TRNSD, // transpose down
-MI_TRNSU, // transpose up
-
-MI_VEL_x 1-10
-MIDI_VELOCITY_MIN = MI_VEL_1,
-MIDI_VELOCITY_MAX = MI_VEL_9,
-MI_VELD, // velocity down
-MI_VELU, // velocity up
-
-MI_CHx 1-16
-MIDI_CHANNEL_MIN = MI_CH1
-MIDI_CHANNEL_MAX = MI_CH16,
-MI_CHD, // previous channel
-MI_CHU, // next channel
-
-MI_ALLOFF, // all notes off
-
-MI_SUS, // sustain
-MI_PORT, // portamento
-MI_SOST, // sostenuto
-MI_SOFT, // soft pedal
-MI_LEG,  // legato
-
-MI_MOD, // modulation
-MI_MODSD, // decrease modulation speed
-MI_MODSU, // increase modulation speed
-#endif // MIDI_ADVANCED
-
--->

docs/feature_auto_shift.md

@@ -15,25 +15,31 @@ problem.
 When you tap a key, it stays depressed for a short period of time before it is
 then released. This depressed time is a different length for everyone. Auto Shift
 defines a constant `AUTO_SHIFT_TIMEOUT` which is typically set to twice your
-normal pressed state time. When you press a key, a timer starts and then stops
-when you release the key. If the time depressed is greater than or equal to the
-`AUTO_SHIFT_TIMEOUT`, then a shifted version of the key is emitted. If the time
-is less than the `AUTO_SHIFT_TIMEOUT` time, then the normal state is emitted.
+normal pressed state time. When you press a key, a timer starts, and if you
+have not released the key after the `AUTO_SHIFT_TIMEOUT` period, then a shifted
+version of the key is emitted. If the time is less than the `AUTO_SHIFT_TIMEOUT`
+time, or you press another key, then the normal state is emitted.
+
+If `AUTO_SHIFT_REPEAT` is defined, there is keyrepeat support. Holding the key
+down will repeat the shifted key, though this can be disabled with
+`AUTO_SHIFT_NO_AUTO_REPEAT`. If you want to repeat the normal key, then tap it
+once then immediately (within `TAPPING_TERM`) hold it down again (this works
+with the shifted value as well if auto-repeat is disabled).
 
 ## Are There Limitations to Auto Shift?
 
 Yes, unfortunately.
 
-1. Key repeat will cease to work. For example, before if you wanted 20 'a'
-   characters, you could press and hold the 'a' key for a second or two. This no
-   longer works with Auto Shift because it is timing your depressed time instead
-   of emitting a depressed key state to your operating system.
-2. You will have characters that are shifted when you did not intend on shifting, and
-   other characters you wanted shifted, but were not. This simply comes down to
-   practice. As we get in a hurry, we think we have hit the key long enough
-   for a shifted version, but we did not. On the other hand, we may think we are
-   tapping the keys, but really we have held it for a little longer than
-   anticipated.
+You will have characters that are shifted when you did not intend on shifting, and
+other characters you wanted shifted, but were not. This simply comes down to
+practice. As we get in a hurry, we think we have hit the key long enough for a
+shifted version, but we did not. On the other hand, we may think we are tapping
+the keys, but really we have held it for a little longer than anticipated.
+
+Additionally, with keyrepeat the desired shift state can get mixed up. It will
+always 'belong' to the last key pressed. For example, keyrepeating a capital
+and then tapping something lowercase (whether or not it's an Auto Shift key)
+will result in the capital's *key* still being held, but shift not.
 
 ## How Do I Enable Auto Shift?
 
@@ -103,6 +109,41 @@ Do not Auto Shift numeric keys, zero through nine.
 
 Do not Auto Shift alpha characters, which include A through Z.
 
+### Auto Shift Per Key 
+
+This is a function that allows you to determine which keys shold be autoshifted, much like the tap-hold keys. 
+
+The default function looks like this: 
+
+```c
+bool get_auto_shifted_key(uint16_t keycode, keyrecord_t *record) {
+    switch (keycode) {
+#    ifndef NO_AUTO_SHIFT_ALPHA
+        case KC_A ... KC_Z:
+#    endif
+#    ifndef NO_AUTO_SHIFT_NUMERIC
+        case KC_1 ... KC_0:
+#    endif
+#    ifndef NO_AUTO_SHIFT_SPECIAL
+        case KC_TAB:
+        case KC_MINUS ... KC_SLASH:
+        case KC_NONUS_BSLASH:
+#    endif
+            return true;
+    }
+    return false;
+}
+```
+This functionality is enabled by default, and does not need a define.
+
+### AUTO_SHIFT_REPEAT (simple define)
+
+Enables keyrepeat.
+
+### AUTO_SHIFT_NO_AUTO_REPEAT (simple define)
+
+Disables automatically keyrepeating when `AUTO_SHIFT_TIMEOUT` is exceeded.
+
 ## Using Auto Shift Setup
 
 This will enable you to define three keys temporarily to increase, decrease and report your `AUTO_SHIFT_TIMEOUT`.
@@ -139,7 +180,7 @@ completely normal and with no intention of shifted keys.
    `KC_ASRP`. The keyboard will type by itself the value of your
    `AUTO_SHIFT_TIMEOUT`.
 7. Update `AUTO_SHIFT_TIMEOUT` in your `config.h` with the value reported.
-8. Remove `AUTO_SHIFT_SETUP` from your `config.h`.
+8. Add `AUTO_SHIFT_NO_SETUP` to your `config.h`.
 9. Remove the key bindings `KC_ASDN`, `KC_ASUP` and `KC_ASRP`.
 10. Compile and upload your new firmware.
 

docs/feature_backlight.md

@@ -1,4 +1,4 @@
-# Backlighting
+# Backlighting :id=backlighting
 
 Many keyboards support backlit keys by way of individual LEDs placed through or underneath the keyswitches. This feature is distinct from both the [RGB underglow](feature_rgblight.md) and [RGB matrix](feature_rgb_matrix.md) features as it usually allows for only a single colour per switch, though you can obviously install multiple different single coloured LEDs on a keyboard.
 
@@ -6,103 +6,109 @@ QMK is able to control the brightness of these LEDs by switching them on and off
 
 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.
 
-## Feature Configuration
-
 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:
 
 ```makefile
 BACKLIGHT_ENABLE = yes
 ```
 
-## Keycodes
-Once enabled the following keycodes below can be used to change the backlight level.
+## Keycodes :id=keycodes
 
-|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                |
+Once enabled, the following keycodes below can be used to change the backlight level.
 
-## Backlight Functions
+|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         |
 
-|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 |
+## Functions :id=functions
 
-### Backlight Breathing Functions
+These functions can be used to change the backlighting in custom code:
 
-|Function  |Description                                        |
-|----------|---------------------------------------------------|
-|`breathing_toggle()`  |Turn the backlight breathing on or off |
-|`breathing_enable()`  |Turns on backlight breathing           |
-|`breathing_disable()` |Turns off backlight breathing          |
+|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|
 
-## Driver Configuration
+If backlight breathing is enabled (see below), the following functions are also available:
+
+|Function             |Description                           |
+|---------------------|--------------------------------------|
+|`breathing_toggle()` |Turn the backlight breathing on or off|
+|`breathing_enable()` |Turns on backlight breathing          |
+|`breathing_disable()`|Turns off backlight breathing         |
+
+## Configuration :id=configuration
 
 To select which driver to use, configure your `rules.mk` with the following:
 
 ```makefile
-BACKLIGHT_DRIVER = software # Valid driver values are 'pwm,software,no'
+BACKLIGHT_DRIVER = software
 ```
 
-See below for help on individual drivers.
+Valid driver values are `pwm`, `software`, `custom` or `no`. See below for help on individual drivers.
 
-## Common Driver Configuration
+To configure the backlighting, `#define` these in your `config.h`:
 
-To change the behavior of the backlighting, `#define` these in your `config.h`:
+|Define                       |Default           |Description                                                                                                      |
+|-----------------------------|------------------|-----------------------------------------------------------------------------------------------------------------|
+|`BACKLIGHT_PIN`              |*Not defined*     |The pin that controls the LED(s)                                                                                 |
+|`BACKLIGHT_LEVELS`           |`3`               |The number of brightness levels (maximum 31 excluding off)                                                       |
+|`BACKLIGHT_CAPS_LOCK`        |*Not defined*     |Enable Caps Lock indicator using backlight (for keyboards without dedicated LED)                                 |
+|`BACKLIGHT_BREATHING`        |*Not defined*     |Enable backlight breathing, if supported                                                                         |
+|`BREATHING_PERIOD`           |`6`               |The length of one backlight "breath" in seconds                                                                  |
+|`BACKLIGHT_ON_STATE`         |`1`               |The state of the backlight pin when the backlight is "on" - `1` for high, `0` for low                            |
+|`BACKLIGHT_LIMIT_VAL`        |`255`             |The maximum duty cycle of the backlight -- `255` allows for full brightness, any lower will decrease the maximum.|
+|`BACKLIGHT_DEFAULT_LEVEL`    |`BACKLIGHT_LEVELS`|The default backlight level to use upon clearing the EEPROM                                                      |
+|`BACKLIGHT_DEFAULT_BREATHING`|*Not defined*     |Whether to enable backlight breathing upon clearing the EEPROM                                                   |
 
-|Define               |Default      |Description                                                                           |
-|---------------------|-------------|--------------------------------------------------------------------------------------|
-|`BACKLIGHT_LEVELS`   |`3`          |The number of brightness levels (maximum 31 excluding off)                            |
-|`BACKLIGHT_CAPS_LOCK`|*Not defined*|Enable Caps Lock indicator using backlight (for keyboards without dedicated LED)      |
-|`BACKLIGHT_BREATHING`|*Not defined*|Enable backlight breathing, if supported                                              |
-|`BREATHING_PERIOD`   |`6`          |The length of one backlight "breath" in seconds                                       |
-|`BACKLIGHT_ON_STATE` |`0`          |The state of the backlight pin when the backlight is "on" - `1` for high, `0` for low |
+Unless you are designing your own keyboard, you generally should not need to change the `BACKLIGHT_PIN` or `BACKLIGHT_ON_STATE`.
 
-### Backlight On State
+### Backlight On State :id=backlight-on-state
 
 Most backlight circuits are driven by an N-channel MOSFET or NPN transistor. This means that to turn the transistor *on* and light the LEDs, you must drive the backlight pin, connected to the gate or base, *high*.
 Sometimes, however, a P-channel MOSFET, or a PNP transistor is used. In this case, when the transistor is on, the pin is driven *low* instead.
 
 This functionality is configured at the keyboard level with the `BACKLIGHT_ON_STATE` define.
 
-## AVR driver
+### AVR Driver :id=avr-driver
+
+The `pwm` driver is configured by default, however the equivalent setting within `rules.mk` would be:
 
-On AVR boards, the default driver currently sniffs the configuration to pick the best scenario. The driver is configured by default, however the equivalent setting within rules.mk would be:
 ```makefile
 BACKLIGHT_DRIVER = pwm
 ```
 
-### Caveats
+#### Caveats :id=avr-caveats
 
-Hardware PWM is supported according to the following table:
+On AVR boards, QMK automatically decides which driver to use according to the following table:
 
-|Backlight Pin|AT90USB64/128|ATmega16/32U4|ATmega16/32U2|ATmega32A|ATmega328P|
-|-------------|-------------|-------------|-------------|---------|----------|
-|`B1`         |             |             |             |         |Timer 1   |
-|`B2`         |             |             |             |         |Timer 1   |
-|`B5`         |Timer 1      |Timer 1      |             |         |          |
-|`B6`         |Timer 1      |Timer 1      |             |         |          |
-|`B7`         |Timer 1      |Timer 1      |Timer 1      |         |          |
-|`C4`         |Timer 3      |             |             |         |          |
-|`C5`         |Timer 3      |             |Timer 1      |         |          |
-|`C6`         |Timer 3      |Timer 3      |Timer 1      |         |          |
-|`D4`         |             |             |             |Timer 1  |          |
-|`D5`         |             |             |             |Timer 1  |          |
+|Backlight Pin|AT90USB64/128|AT90USB162|ATmega16/32U4|ATmega16/32U2|ATmega32A|ATmega328/P|
+|-------------|-------------|----------|-------------|-------------|---------|-----------|
+|`B1`         |             |          |             |             |         |Timer 1    |
+|`B2`         |             |          |             |             |         |Timer 1    |
+|`B5`         |Timer 1      |          |Timer 1      |             |         |           |
+|`B6`         |Timer 1      |          |Timer 1      |             |         |           |
+|`B7`         |Timer 1      |Timer 1   |Timer 1      |Timer 1      |         |           |
+|`C4`         |Timer 3      |          |             |             |         |           |
+|`C5`         |Timer 3      |Timer 1   |             |Timer 1      |         |           |
+|`C6`         |Timer 3      |Timer 1   |Timer 3      |Timer 1      |         |           |
+|`D4`         |             |          |             |             |Timer 1  |           |
+|`D5`         |             |          |             |             |Timer 1  |           |
 
-All other pins will use software PWM. If the [Audio](feature_audio.md) feature is disabled or only using one timer, the backlight PWM can be triggered by a hardware timer:
+All other pins will use timer-assisted software PWM:
 
 |Audio Pin|Audio Timer|Software PWM Timer|
 |---------|-----------|------------------|
@@ -113,44 +119,9 @@ All other pins will use software PWM. If the [Audio](feature_audio.md) feature i
 |`B6`     |Timer 1    |Timer 3           |
 |`B7`     |Timer 1    |Timer 3           |
 
-When both timers are in use for Audio, the backlight PWM will not use a hardware timer, but will instead be triggered during the matrix scan. In this case, breathing is not supported, and the backlight might flicker, because the PWM computation may not be called with enough timing precision.
+When both timers are in use for Audio, the backlight PWM cannot use a hardware timer, and will instead be triggered during the matrix scan. In this case, breathing is not supported, and the backlight might flicker, because the PWM computation may not be called with enough timing precision.
 
-### AVR Configuration
-
-To change the behavior of the backlighting, `#define` these in your `config.h`:
-
-|Define               |Default      |Description                                                                                                  |
-|---------------------|-------------|-------------------------------------------------------------------------------------------------------------|
-|`BACKLIGHT_PIN`      |`B7`         |The pin that controls the LEDs. Unless you are designing your own keyboard, you shouldn't need to change this|
-|`BACKLIGHT_PINS`     |*Not defined*|experimental: see below for more information                                                                 |
-|`BACKLIGHT_LEVELS`   |`3`          |The number of brightness levels (maximum 31 excluding off)                                                   |
-|`BACKLIGHT_CAPS_LOCK`|*Not defined*|Enable Caps Lock indicator using backlight (for keyboards without dedicated LED)                             |
-|`BACKLIGHT_BREATHING`|*Not defined*|Enable backlight breathing, if supported                                                                     |
-|`BREATHING_PERIOD`   |`6`          |The length of one backlight "breath" in seconds                                                              |
-|`BACKLIGHT_ON_STATE` |`1`          |The state of the backlight pin when the backlight is "on" - `1` for high, `0` for low                        |
-
-### Backlight On State
-
-Most backlight circuits are driven by an N-channel MOSFET or NPN transistor. This means that to turn the transistor *on* and light the LEDs, you must drive the backlight pin, connected to the gate or base, *high*.
-Sometimes, however, a P-channel MOSFET, or a PNP transistor is used. In this case, when the transistor is on, the pin is driven *low* instead.
-
-This functionality is configured at the keyboard level with the `BACKLIGHT_ON_STATE` define.
-
-### Multiple backlight pins
-
-Most keyboards have only one backlight pin which control all backlight LEDs (especially if the backlight is connected to an hardware PWM pin).
-In software PWM, it is possible to define multiple backlight pins. All those pins will be turned on and off at the same time during the PWM duty cycle.
-This feature allows to set for instance the Caps Lock LED (or any other controllable LED) brightness at the same level as the other LEDs of the backlight. This is useful if you have mapped LCTRL in place of Caps Lock and you need the Caps Lock LED to be part of the backlight instead of being activated when Caps Lock is on.
-
-To activate multiple backlight pins, you need to add something like this to your user `config.h`:
-
-```c
-#define BACKLIGHT_LED_COUNT 2
-#undef BACKLIGHT_PIN
-#define BACKLIGHT_PINS { F5, B2 }
-```
-
-### Hardware PWM Implementation
+#### Hardware PWM Implementation :id=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.
@@ -159,7 +130,7 @@ In this way `OCRxx` essentially controls the duty cycle of the LEDs, and thus th
 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.
 
-### Timer Assisted PWM Implementation
+#### Timer Assisted PWM Implementation :id=timer-assisted-implementation
 
 When `BACKLIGHT_PIN` is not set to a hardware backlight pin, QMK will use a hardware timer configured to trigger software interrupts. This time will count up to `ICRx` (by default `0xFFFF`) before resetting to 0.
 When resetting to 0, the CPU will fire an OVF (overflow) interrupt that will turn the LEDs on, starting the duty cycle.
@@ -168,81 +139,82 @@ In this way `OCRxx` essentially controls the duty cycle of the LEDs, and thus th
 
 The breathing effect is the same as in the hardware PWM implementation.
 
-## ARM Driver
+### ARM Driver :id=arm-configuration
+
+While still in its early stages, ARM backlight support aims to eventually have feature parity with AVR. The `pwm` driver is configured by default, however the equivalent setting within `rules.mk` would be:
 
-While still in its early stages, ARM backlight support aims to eventually have feature parity with AVR. The driver is configured by default, however the equivalent setting within rules.mk would be:
 ```makefile
 BACKLIGHT_DRIVER = pwm
 ```
 
-### Caveats
+#### ChibiOS Configuration :id=arm-configuration
+
+The following `#define`s apply only to ARM-based keyboards:
+
+|Define                 |Default|Description                        |
+|-----------------------|-------|-----------------------------------|
+|`BACKLIGHT_PWM_DRIVER` |`PWMD4`|The PWM driver to use              |
+|`BACKLIGHT_PWM_CHANNEL`|`3`    |The PWM channel to use             |
+|`BACKLIGHT_PAL_MODE`   |`2`    |The pin alternative function to use|
+
+See the ST datasheet for your particular MCU to determine these values. Unless you are designing your own keyboard, you generally should not need to change them.
+
+#### Caveats :id=arm-caveats
 
 Currently only hardware PWM is supported, not timer assisted, and does not provide automatic configuration.
 
-?> Backlight support for STMF072 has had limited testing, YMMV. If unsure, set `BACKLIGHT_ENABLE = no` in your rules.mk.
+### Software PWM Driver :id=software-pwm-driver
 
-### ARM Configuration
+In this mode, PWM is "emulated" while running other keyboard tasks. It offers maximum hardware compatibility without extra platform configuration. The tradeoff is the backlight might jitter when the keyboard is busy. To enable, add this to your `rules.mk`:
 
-To change the behavior of the backlighting, `#define` these in your `config.h`:
-
-|Define                  |Default      |Description                                                                                                  |
-|------------------------|-------------|-------------------------------------------------------------------------------------------------------------|
-|`BACKLIGHT_PIN`         |`B7`         |The pin that controls the LEDs. Unless you are designing your own keyboard, you shouldn't need to change this|
-|`BACKLIGHT_PWM_DRIVER`  |`PWMD4`      |The PWM driver to use, see ST datasheets for pin to PWM timer mapping. Unless you are designing your own keyboard, you shouldn't need to change this|
-|`BACKLIGHT_PWM_CHANNEL` |`3`          |The PWM channel to use, see ST datasheets for pin to PWM channel mapping. Unless you are designing your own keyboard, you shouldn't need to change this|
-|`BACKLIGHT_PAL_MODE`    |`2`          |The pin alternative function to use, see ST datasheets for pin AF mapping. Unless you are designing your own keyboard, you shouldn't need to change this|
-
-## Software PWM Driver :id=software-pwm-driver
-
-Emulation of PWM while running other keyboard tasks, it offers maximum hardware compatibility without extra platform configuration. The tradeoff is the backlight might jitter when the keyboard is busy. To enable, add this to your rules.mk:
 ```makefile
 BACKLIGHT_DRIVER = software
 ```
 
-### Software PWM Configuration
+#### Multiple Backlight Pins :id=multiple-backlight-pins
 
-To change the behavior of the backlighting, `#define` these in your `config.h`:
+Most keyboards have only one backlight pin which controls all backlight LEDs (especially if the backlight is connected to a hardware PWM pin).
+In software PWM, it is possible to define multiple backlight pins, which will be turned on and off at the same time during the PWM duty cycle.
 
-|Define           |Default      |Description                                                                                                  |
-|-----------------|-------------|-------------------------------------------------------------------------------------------------------------|
-|`BACKLIGHT_PIN`  |`B7`         |The pin that controls the LEDs. Unless you are designing your own keyboard, you shouldn't need to change this|
-|`BACKLIGHT_PINS` |*Not defined*|experimental: see below for more information                                                                 |
+This feature allows to set, for instance, the Caps Lock LED's (or any other controllable LED) brightness at the same level as the other LEDs of the backlight. This is useful if you have mapped Control in place of Caps Lock and you need the Caps Lock LED to be part of the backlight instead of being activated when Caps Lock is on, as it is usually wired to a separate pin from the backlight.
 
-### Multiple backlight pins
-
-Most keyboards have only one backlight pin which control all backlight LEDs (especially if the backlight is connected to an hardware PWM pin).
-In software PWM, it is possible to define multiple backlight pins. All those pins will be turned on and off at the same time during the PWM duty cycle.
-This feature allows to set for instance the Caps Lock LED (or any other controllable LED) brightness at the same level as the other LEDs of the backlight. This is useful if you have mapped LCTRL in place of Caps Lock and you need the Caps Lock LED to be part of the backlight instead of being activated when Caps Lock is on.
-
-To activate multiple backlight pins, you need to add something like this to your user `config.h`:
+To activate multiple backlight pins, add something like this to your `config.h`, instead of `BACKLIGHT_PIN`:
 
 ```c
-#undef BACKLIGHT_PIN
 #define BACKLIGHT_PINS { F5, B2 }
 ```
 
-## Custom Driver
+### Custom Driver :id=custom-driver
 
-To enable, add this to your rules.mk:
+If none of the above drivers apply to your board (for example, you are using a separate IC to control the backlight), you can implement a custom backlight driver using this simple API provided by QMK. To enable, add this to your `rules.mk`:
 
 ```makefile
 BACKLIGHT_DRIVER = custom
 ```
 
-When implementing the custom driver API, the provided keyboard hooks are as follows:
+Then implement any of these hooks:
 
 ```c
 void backlight_init_ports(void) {
-    // Optional - Run on startup
-    //          - usually you want to configure pins here
+    // Optional - runs on startup
+    //   Usually you want to configure pins here
 }
 void backlight_set(uint8_t level) {
-    // Optional - Run on level change
-    //          - usually you want to respond to the new value
+    // Optional - runs on level change
+    //   Usually you want to respond to the new value
 }
 
 void backlight_task(void) {
-    // Optional - Run periodically
-    //          - long running actions here can cause performance issues
+    // Optional - runs periodically
+    //   Note that this is called in the main keyboard loop,
+    //   so long running actions here can cause performance issues
 }
 ```
+
+## Example Schematic
+
+In this typical example, the backlight LEDs are all connected in parallel towards an N-channel MOSFET. Its gate pin is wired to one of the microcontroller's GPIO pins through a 470Ω resistor to avoid ringing.
+A pulldown resistor is also placed between the gate pin and ground to keep it at a defined state when it is not otherwise being driven by the MCU.
+The values of these resistors are not critical - see [this Electronics StackExchange question](https://electronics.stackexchange.com/q/68748) for more information.
+
+![Backlight example circuit](https://i.imgur.com/BmAvoUC.png)

docs/feature_bluetooth.md

@@ -2,11 +2,10 @@
 
 ## Bluetooth Known Supported Hardware
 
-Currently Bluetooth support is limited to AVR based chips. For Bluetooth 2.1, QMK has support for RN-42 modules and the Bluefruit EZ-Key, the latter 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.
+Currently Bluetooth support is limited to AVR based chips. For Bluetooth 2.1, QMK has support for RN-42 modules. 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 EZ-Key HID](https://www.adafruit.com/product/1535)   |Bluetooth Classic           | UART           |`BLUETOOTH = AdafruitEZKey` |              |
 |Roving 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`   | nRF51822      |
 
@@ -24,16 +23,15 @@ Currently The only bluetooth chipset supported by QMK is the Adafruit Bluefruit
 
 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
+
+The currently supported Bluetooth chipsets do not support [N-Key Rollover (NKRO)](reference_glossary.md#n-key-rollover-nkro), so `rules.mk` must contain `NKRO_ENABLE = no`.
+
+Use only one of these to enable Bluetooth:
 * BLUETOOTH_ENABLE = yes (Legacy Option)
 * BLUETOOTH = RN42
-* BLUETOOTH = AdafruitEZKey
 * BLUETOOTH = AdafruitBLE
 
 ## Bluetooth Keycodes

docs/feature_combo.md

@@ -55,7 +55,7 @@ combo_t key_combos[COMBO_COUNT] = {
   [XV_PASTE] = COMBO_ACTION(paste_combo),
 };
 
-void process_combo_event(uint8_t combo_index, bool pressed) {
+void process_combo_event(uint16_t combo_index, bool pressed) {
   switch(combo_index) {
     case ZC_COPY:
       if (pressed) {