ARM split - Add bootmagic/magic keycodes for setting handedness (#6545)

* Add docs on bootmagic/magic keycodes for setting handedness

* Clang format fixes

* Maintain backwards compatibility

* Maintain backwards compatibility

.editorconfig

@@ -16,6 +16,10 @@ insert_final_newline = true
 trim_trailing_whitespace = false
 indent_size = 4
 
+[{qmk,*.py}]
+charset = utf-8
+max_line_length = 200
+
 # Make these match what we have in .gitattributes
 [*.mk]
 end_of_line = lf

.gitignore

@@ -25,7 +25,7 @@ quantum/version.h
 CMakeLists.txt
 cmake-build-debug
 doxygen/
-.DS_STORE
+.DS_Store
 /util/wsl_downloaded
 /util/win_downloaded
 /keyboards/*/Makefile
@@ -70,3 +70,6 @@ util/Win_Check_Output.txt
 secrets.tar
 id_rsa_*
 /.vs
+
+# python things
+__pycache__

.gitmodules

@@ -11,3 +11,6 @@
 [submodule "lib/googletest"]
 	path = lib/googletest
 	url = https://github.com/google/googletest
+[submodule "lib/lufa"]
+	path = lib/lufa
+	url = https://github.com/qmk/lufa

.travis.yml

@@ -13,8 +13,6 @@ env:
   - MAKEFLAGS="-j3 --output-sync"
 services:
   - docker
-before_install:
-  - docker build -t qmkfm/qmk_firmware .
 install:
   - npm install -g moxygen
 script:
@@ -29,7 +27,7 @@ addons:
     - diffutils
     - dos2unix
     - doxygen
-after_success:
+after_script:
   bash util/travis_compiled_push.sh
 notifications:
   webhooks:

.vscode/extensions.json

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

.vscode/settings.json

@@ -8,10 +8,12 @@
         "**/*.hex": true
     },
     "files.associations": {
-        "*.h": "c",
-        "*.c": "c",
-        "*.cpp": "cpp",
-        "*.hpp": "cpp",
-        "xstddef": "c"
+      "*.h": "c",
+      "*.c": "c",
+      "*.cpp": "cpp",
+      "*.hpp": "cpp",
+      "xstddef": "c",
+      "type_traits": "c",
+      "utility": "c"
     }
 }

CODE_OF_CONDUCT.md

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

Dockerfile

@@ -1,26 +1,4 @@
-FROM debian:9
-
-RUN apt-get update && apt-get install --no-install-recommends -y \
-    avr-libc \
-    avrdude \
-    binutils-arm-none-eabi \
-    binutils-avr \
-    build-essential \
-    dfu-programmer \
-    dfu-util \
-    gcc \
-    gcc-avr \
-    git \
-    libnewlib-arm-none-eabi \
-    software-properties-common \
-    unzip \
-    wget \
-    zip \
-    && rm -rf /var/lib/apt/lists/*
-
-# upgrade gcc-arm-none-eabi from the default 5.4.1 to 6.3.1 due to ARM runtime issues
-RUN wget -q https://developer.arm.com/-/media/Files/downloads/gnu-rm/6-2017q2/gcc-arm-none-eabi-6-2017-q2-update-linux.tar.bz2 -O - | \
-    tar xj --strip-components=1 -C /
+FROM qmkfm/base_container
 
 VOLUME /qmk_firmware
 WORKDIR /qmk_firmware

Makefile

@@ -20,7 +20,10 @@ endif
 override SILENT := false
 
 ifndef SUB_IS_SILENT
-QMK_VERSION := $(shell git describe --abbrev=0 --tags 2>/dev/null)
+ifndef SKIP_GIT
+    QMK_VERSION := $(shell git describe --abbrev=0 --tags 2>/dev/null)
+endif
+
 ifneq ($(QMK_VERSION),)
 $(info QMK Firmware $(QMK_VERSION))
 endif
@@ -94,6 +97,7 @@ $(eval $(call NEXT_PATH_ELEMENT))
 # 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))
@@ -105,6 +109,9 @@ define GET_KEYBOARDS
     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))
@@ -364,6 +371,9 @@ define PARSE_KEYBOARD
     # The same if all was specified
     else ifeq ($$(call COMPARE_AND_REMOVE_FROM_RULE,all),true)
         $$(eval $$(call PARSE_ALL_KEYMAPS))
+    # List all keymaps for the given keyboard
+    else ifeq ($$(call COMPARE_AND_REMOVE_FROM_RULE,list-keymaps),true)
+        $$(eval $$(call LIST_ALL_KEYMAPS))
     # Try to match the specified keyamp with the list of known keymaps
     else ifeq ($$(call TRY_TO_MATCH_RULE_FROM_LIST,$$(KEYMAPS)),true)
         $$(eval $$(call PARSE_KEYMAP,$$(MATCHED_ITEM)))
@@ -400,6 +410,16 @@ endef
 #     endif
 # endef
 
+# Prints a list of all known keymaps for the given keyboard
+define LIST_ALL_KEYMAPS
+    COMMAND_true_LIST_KEYMAPS := \
+        printf "$$(KEYMAPS)\n";
+    COMMAND_false_LIST_KEYMAPS := \
+        printf "$$(MSG_AVAILABLE_KEYMAPS)\n"; \
+        printf "$$(KEYMAPS)\n";
+    COMMANDS += LIST_KEYMAPS
+endef
+
 # $1 Keymap
 # This is the meat of compiling a keyboard, when entering this, everything is known
 # keyboard, subproject, and keymap
@@ -541,6 +561,7 @@ ifndef SKIP_GIT
 	if [ ! -e lib/chibios ]; then git submodule sync lib/chibios && git submodule update --depth 1 --init lib/chibios; fi
 	if [ ! -e lib/chibios-contrib ]; then git submodule sync lib/chibios-contrib && git submodule update --depth 1 --init lib/chibios-contrib; fi
 	if [ ! -e lib/ugfx ]; then git submodule sync lib/ugfx && git submodule update --depth 1 --init lib/ugfx; fi
+	if [ ! -e lib/lufa ]; then git submodule sync lib/lufa && git submodule update --depth 1 --init lib/lufa; fi
 	git submodule status --recursive 2>/dev/null | \
 	while IFS= read -r x; do \
 		case "$$x" in \

Vagrantfile

@@ -52,26 +52,37 @@ Vagrant.configure(2) do |config|
   end
 
   # Docker provider pulls from hub.docker.com respecting docker.image if
-  # config.vm.box is nil. Note that this bind-mounts from the current dir to
+  # config.vm.box is nil. In this case, we adhoc build util/vagrant/Dockerfile.
+  # Note that this bind-mounts from the current dir to
   # /vagrant in the guest, so unless your UID is 1000 to match vagrant in the
   # image, you'll need to: chmod -R a+rw .
   config.vm.provider "docker" do |docker, override|
     override.vm.box = nil
-    docker.image = "jesselang/debian-vagrant:stretch"
+    docker.build_dir = "util/vagrant"
     docker.has_ssh = true
   end
 
-  # This script ensures the required packages for AVR programming are installed
-  # It also ensures the system always gets the latest updates when powered on
-  # If this causes issues you can run a 'vagrant destroy' and then
-  # add a # before ,run: (or change "always" to "once") and run 'vagrant up' to get a working
-  # non-updated box and then attempt to troubleshoot or open a Github issue
-  config.vm.provision "shell", inline: "/vagrant/util/qmk_install.sh", run: "always"
+  # Unless we are running the docker container directly
+  #   1. run container detached on vm
+  #   2. attach on 'vagrant ssh'
+  ["virtualbox", "vmware_workstation", "vmware_fusion"].each do |type|
+    config.vm.provider type do |virt, override|
+      override.vm.provision "docker" do |d|
+        d.run "qmkfm/base_container",
+          cmd: "tail -f /dev/null",
+          args: "--privileged -v /dev:/dev -v '/vagrant:/vagrant'"
+      end
+
+      override.vm.provision "shell", inline: <<-SHELL
+        echo 'docker restart qmkfm-base_container && exec docker exec -it qmkfm-base_container /bin/bash -l' >> ~vagrant/.bashrc
+      SHELL
+    end
+  end
 
   config.vm.post_up_message = <<-EOT
 
-  Log into the VM using 'vagrant ssh'. QMK directory synchronized with host is
-  located at /vagrant
+  Log into the environment using 'vagrant ssh'. QMK directory synchronized with
+  host is located at /vagrant
   To compile the .hex files use make command inside this directory, e.g.
      cd /vagrant
      make <keyboard>:default

bin/qmk

@@ -0,0 +1,83 @@
+#!/usr/bin/env python3
+"""CLI wrapper for running QMK commands.
+"""
+import os
+import subprocess
+import sys
+from importlib.util import find_spec
+from time import strftime
+
+# 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 not find_spec(module):
+            print('Could not find module %s!', module)
+            print('Please run `pip3 install -r requirements.txt` to install the python dependencies.')
+            exit(255)
+
+# Figure out our version
+# TODO(skullydazed/anyone): Find a method that doesn't involve git. This is slow in docker and on windows.
+command = ['git', 'describe', '--abbrev=6', '--dirty', '--always', '--tags']
+result = subprocess.run(command, universal_newlines=True, stdout=subprocess.PIPE, stderr=subprocess.STDOUT)
+
+if result.returncode == 0:
+    os.environ['QMK_VERSION'] = result.stdout.strip()
+else:
+    os.environ['QMK_VERSION'] = 'nogit-' + strftime('%Y-%m-%d-%H:%M:%S') + '-dirty'
+
+# Setup the CLI
+import milc
+
+milc.EMOJI_LOGLEVELS['INFO'] = '{fg_blue}Ψ{style_reset_all}'
+
+
+@milc.cli.entrypoint('QMK Helper Script')
+def qmk_main(cli):
+    """The function that gets run when no subcommand is provided.
+    """
+    cli.print_help()
+
+
+def main():
+    """Setup our environment and then call the CLI entrypoint.
+    """
+    # Change to the root of our checkout
+    os.environ['ORIG_CWD'] = os.getcwd()
+    os.chdir(qmk_dir)
+
+    # Import the subcommands
+    import qmk.cli
+
+    # Execute
+    return_code = milc.cli()
+
+    if return_code is False:
+        exit(1)
+
+    elif return_code is not True and isinstance(return_code, int):
+        if return_code < 0 or return_code > 255:
+            milc.cli.log.error('Invalid return_code: %d', return_code)
+            exit(255)
+
+        exit(return_code)
+
+    exit(0)
+
+
+if __name__ == '__main__':
+    main()

bootloader.mk

@@ -19,12 +19,14 @@
 #
 # Sets the bootloader defined in the keyboard's/keymap's rules.mk
 # Current options:
-#   atmel-dfu
-#   lufa-dfu
-#   qmk-dfu
-#   halfkay
-#   caterina
-#   bootloadHID
+#
+# 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)
 #
 # BOOTLOADER_SIZE can still be defined manually, but it's recommended
 # you add any possible configuration to this list
@@ -32,40 +34,40 @@
 ifeq ($(strip $(BOOTLOADER)), atmel-dfu)
     OPT_DEFS += -DBOOTLOADER_ATMEL_DFU
     OPT_DEFS += -DBOOTLOADER_DFU
-    ifeq ($(strip $(MCU)), atmega32u4)
-      BOOTLOADER_SIZE = 4096
+    ifneq (,$(filter $(MCU), at90usb646 atmega16u2 atmega16u4 atmega32u2 atmega32u4))
+        BOOTLOADER_SIZE = 4096
     endif
     ifeq ($(strip $(MCU)), at90usb1286)
-      BOOTLOADER_SIZE = 8192
+        BOOTLOADER_SIZE = 8192
     endif
 endif
 ifeq ($(strip $(BOOTLOADER)), lufa-dfu)
     OPT_DEFS += -DBOOTLOADER_LUFA_DFU
     OPT_DEFS += -DBOOTLOADER_DFU
-    ifeq ($(strip $(MCU)), atmega32u4)
-      BOOTLOADER_SIZE = 4096
+    ifneq (,$(filter $(MCU), at90usb646 atmega16u2 atmega16u4 atmega32u2 atmega32u4))
+        BOOTLOADER_SIZE = 4096
     endif
     ifeq ($(strip $(MCU)), at90usb1286)
-      BOOTLOADER_SIZE = 8192
+        BOOTLOADER_SIZE = 8192
     endif
 endif
 ifeq ($(strip $(BOOTLOADER)), qmk-dfu)
     OPT_DEFS += -DBOOTLOADER_QMK_DFU
     OPT_DEFS += -DBOOTLOADER_DFU
-    ifeq ($(strip $(MCU)), atmega32u4)
-      BOOTLOADER_SIZE = 4096
+    ifneq (,$(filter $(MCU), at90usb646 atmega16u2 atmega16u4 atmega32u2 atmega32u4))
+        BOOTLOADER_SIZE = 4096
     endif
     ifeq ($(strip $(MCU)), at90usb1286)
-      BOOTLOADER_SIZE = 8192
+        BOOTLOADER_SIZE = 8192
     endif
 endif
 ifeq ($(strip $(BOOTLOADER)), halfkay)
     OPT_DEFS += -DBOOTLOADER_HALFKAY
     ifeq ($(strip $(MCU)), atmega32u4)
-      BOOTLOADER_SIZE = 512
+        BOOTLOADER_SIZE = 512
     endif
     ifeq ($(strip $(MCU)), at90usb1286)
-      BOOTLOADER_SIZE = 1024
+        BOOTLOADER_SIZE = 1024
     endif
 endif
 ifeq ($(strip $(BOOTLOADER)), caterina)
@@ -76,6 +78,10 @@ ifeq ($(strip $(BOOTLOADER)), bootloadHID)
     OPT_DEFS += -DBOOTLOADER_BOOTLOADHID
     BOOTLOADER_SIZE = 4096
 endif
+ifeq ($(strip $(BOOTLOADER)), USBasp)
+    OPT_DEFS += -DBOOTLOADER_USBASP
+    BOOTLOADER_SIZE = 4096
+endif
 
 ifdef BOOTLOADER_SIZE
     OPT_DEFS += -DBOOTLOADER_SIZE=$(strip $(BOOTLOADER_SIZE))

build_json.mk

@@ -0,0 +1,27 @@
+# Look for a json keymap file
+ifneq ("$(wildcard $(MAIN_KEYMAP_PATH_5)/keymap.json)","")
+    KEYMAP_C := $(KEYBOARD_OUTPUT)/src/keymap.c
+    KEYMAP_JSON := $(MAIN_KEYMAP_PATH_5)/keymap.json
+    KEYMAP_PATH := $(MAIN_KEYMAP_PATH_5)
+else ifneq ("$(wildcard $(MAIN_KEYMAP_PATH_4)/keymap.json)","")
+    KEYMAP_C := $(KEYBOARD_OUTPUT)/src/keymap.c
+    KEYMAP_JSON := $(MAIN_KEYMAP_PATH_4)/keymap.json
+    KEYMAP_PATH := $(MAIN_KEYMAP_PATH_4)
+else ifneq ("$(wildcard $(MAIN_KEYMAP_PATH_3)/keymap.json)","")
+    KEYMAP_C := $(KEYBOARD_OUTPUT)/src/keymap.c
+    KEYMAP_JSON := $(MAIN_KEYMAP_PATH_3)/keymap.json
+    KEYMAP_PATH := $(MAIN_KEYMAP_PATH_3)
+else ifneq ("$(wildcard $(MAIN_KEYMAP_PATH_2)/keymap.json)","")
+    KEYMAP_C := $(KEYBOARD_OUTPUT)/src/keymap.c
+    KEYMAP_JSON := $(MAIN_KEYMAP_PATH_2)/keymap.json
+    KEYMAP_PATH := $(MAIN_KEYMAP_PATH_2)
+else ifneq ("$(wildcard $(MAIN_KEYMAP_PATH_1)/keymap.json)","")
+    KEYMAP_C := $(KEYBOARD_OUTPUT)/src/keymap.c
+    KEYMAP_JSON := $(MAIN_KEYMAP_PATH_1)/keymap.json
+    KEYMAP_PATH := $(MAIN_KEYMAP_PATH_1)
+endif
+
+# Generate the keymap.c
+ifneq ("$(KEYMAP_JSON)","")
+    _ = $(shell test -e $(KEYMAP_C) || bin/qmk json-keymap $(KEYMAP_JSON) -o $(KEYMAP_C))
+endif

build_keyboard.mk

@@ -98,31 +98,38 @@ 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)
 
-ifneq ("$(wildcard $(MAIN_KEYMAP_PATH_5)/keymap.c)","")
-    -include $(MAIN_KEYMAP_PATH_5)/rules.mk
-    KEYMAP_C := $(MAIN_KEYMAP_PATH_5)/keymap.c
-    KEYMAP_PATH := $(MAIN_KEYMAP_PATH_5)
-else ifneq ("$(wildcard $(MAIN_KEYMAP_PATH_4)/keymap.c)","")
-    -include $(MAIN_KEYMAP_PATH_4)/rules.mk
-    KEYMAP_C := $(MAIN_KEYMAP_PATH_4)/keymap.c
-    KEYMAP_PATH := $(MAIN_KEYMAP_PATH_4)
-else ifneq ("$(wildcard $(MAIN_KEYMAP_PATH_3)/keymap.c)","")
-    -include $(MAIN_KEYMAP_PATH_3)/rules.mk
-    KEYMAP_C := $(MAIN_KEYMAP_PATH_3)/keymap.c
-    KEYMAP_PATH := $(MAIN_KEYMAP_PATH_3)
-else ifneq ("$(wildcard $(MAIN_KEYMAP_PATH_2)/keymap.c)","")
-    -include $(MAIN_KEYMAP_PATH_2)/rules.mk
-    KEYMAP_C := $(MAIN_KEYMAP_PATH_2)/keymap.c
-    KEYMAP_PATH := $(MAIN_KEYMAP_PATH_2)
-else ifneq ("$(wildcard $(MAIN_KEYMAP_PATH_1)/keymap.c)","")
-    -include $(MAIN_KEYMAP_PATH_1)/rules.mk
-    KEYMAP_C := $(MAIN_KEYMAP_PATH_1)/keymap.c
-    KEYMAP_PATH := $(MAIN_KEYMAP_PATH_1)
-else ifneq ($(LAYOUTS),)
-    include build_layout.mk
-else
-    $(error Could not find keymap)
-    # this state should never be reached
+# Check for keymap.json first, so we can regenerate keymap.c
+include build_json.mk
+
+ifeq ("$(wildcard $(KEYMAP_PATH))", "")
+    # Look through the possible keymap folders until we find a matching keymap.c
+    ifneq ("$(wildcard $(MAIN_KEYMAP_PATH_5)/keymap.c)","")
+        -include $(MAIN_KEYMAP_PATH_5)/rules.mk
+        KEYMAP_C := $(MAIN_KEYMAP_PATH_5)/keymap.c
+        KEYMAP_PATH := $(MAIN_KEYMAP_PATH_5)
+    else ifneq ("$(wildcard $(MAIN_KEYMAP_PATH_4)/keymap.c)","")
+        -include $(MAIN_KEYMAP_PATH_4)/rules.mk
+        KEYMAP_C := $(MAIN_KEYMAP_PATH_4)/keymap.c
+        KEYMAP_PATH := $(MAIN_KEYMAP_PATH_4)
+    else ifneq ("$(wildcard $(MAIN_KEYMAP_PATH_3)/keymap.c)","")
+        -include $(MAIN_KEYMAP_PATH_3)/rules.mk
+        KEYMAP_C := $(MAIN_KEYMAP_PATH_3)/keymap.c
+        KEYMAP_PATH := $(MAIN_KEYMAP_PATH_3)
+    else ifneq ("$(wildcard $(MAIN_KEYMAP_PATH_2)/keymap.c)","")
+        -include $(MAIN_KEYMAP_PATH_2)/rules.mk
+        KEYMAP_C := $(MAIN_KEYMAP_PATH_2)/keymap.c
+        KEYMAP_PATH := $(MAIN_KEYMAP_PATH_2)
+    else ifneq ("$(wildcard $(MAIN_KEYMAP_PATH_1)/keymap.c)","")
+        -include $(MAIN_KEYMAP_PATH_1)/rules.mk
+        KEYMAP_C := $(MAIN_KEYMAP_PATH_1)/keymap.c
+        KEYMAP_PATH := $(MAIN_KEYMAP_PATH_1)
+    else ifneq ($(LAYOUTS),)
+        # If we haven't found a keymap yet fall back to community layouts
+        include build_layout.mk
+    else
+        $(error Could not find keymap)
+        # this state should never be reached
+    endif
 endif
 
 ifeq ($(strip $(CTPC)), yes)
@@ -313,7 +320,6 @@ ifneq ("$(wildcard $(USER_PATH)/config.h)","")
     CONFIG_H += $(USER_PATH)/config.h
 endif
 
-
 # Object files directory
 #     To put object files in current directory, use a dot (.), do NOT make
 #     this an empty or blank macro!
@@ -323,7 +329,7 @@ ifneq ("$(wildcard $(KEYMAP_PATH)/config.h)","")
     CONFIG_H += $(KEYMAP_PATH)/config.h
 endif
 
-# # project specific files
+# project specific files
 SRC += $(KEYBOARD_SRC) \
     $(KEYMAP_C) \
     $(QUANTUM_SRC)
@@ -392,6 +398,7 @@ $(KEYBOARD_OUTPUT)_CONFIG := $(PROJECT_CONFIG)
 all: build check-size
 build: elf cpfirmware
 check-size: build
+objs-size: build
 
 include show_options.mk
 include $(TMK_PATH)/rules.mk

common_features.mk

@@ -267,20 +267,21 @@ ifeq ($(strip $(ENCODER_ENABLE)), yes)
     OPT_DEFS += -DENCODER_ENABLE
 endif
 
-ifeq ($(strip $(HAPTIC_ENABLE)), DRV2605L)
-    COMMON_VPATH += $(DRIVER_PATH)/haptic
-    SRC += haptic.c
+HAPTIC_ENABLE ?= no
+ifneq ($(strip $(HAPTIC_ENABLE)),no)
+	COMMON_VPATH += $(DRIVER_PATH)/haptic
+	SRC += haptic.c
+	OPT_DEFS += -DHAPTIC_ENABLE
+endif
+
+ifneq ($(filter DRV2605L, $(HAPTIC_ENABLE)), )
     SRC += DRV2605L.c
     QUANTUM_LIB_SRC += i2c_master.c
-    OPT_DEFS += -DHAPTIC_ENABLE
     OPT_DEFS += -DDRV2605L
 endif
 
-ifeq ($(strip $(HAPTIC_ENABLE)), SOLENOID)
-    COMMON_VPATH += $(DRIVER_PATH)/haptic
-    SRC += haptic.c
+ifneq ($(filter SOLENOID, $(HAPTIC_ENABLE)), )
     SRC += solenoid.c
-    OPT_DEFS += -DHAPTIC_ENABLE
     OPT_DEFS += -DSOLENOID_ENABLE
 endif
 
@@ -358,3 +359,9 @@ ifeq ($(strip $(SPACE_CADET_ENABLE)), yes)
   SRC += $(QUANTUM_DIR)/process_keycode/process_space_cadet.c
   OPT_DEFS += -DSPACE_CADET_ENABLE
 endif
+
+
+ifeq ($(strip $(DIP_SWITCH_ENABLE)), yes)
+  SRC += $(QUANTUM_DIR)/dip_switch.c
+  OPT_DEFS += -DDIP_SWITCH_ENABLE
+endif

docs/ChangeLog/20190830.md

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

docs/_summary.md

@@ -8,15 +8,21 @@
 
 * [QMK Basics](README.md)
   * [QMK Introduction](getting_started_introduction.md)
+  * [QMK CLI](cli.md)
+  * [QMK CLI Config](cli_configuration.md)
   * [Contributing to QMK](contributing.md)
   * [How to Use Github](getting_started_github.md)
   * [Getting Help](getting_started_getting_help.md)
 
+* [Breaking Changes](breaking_changes.md)
+  * [2019 Aug 30](ChangeLog/20190830.md)
+
 * [FAQ](faq.md)
   * [General FAQ](faq_general.md)
   * [Build/Compile QMK](faq_build.md)
   * [Debugging/Troubleshooting QMK](faq_debug.md)
   * [Keymap](faq_keymap.md)
+  * [Driver Installation with Zadig](driver_installation_zadig.md)
 
 * Detailed Guides
   * [Install Build Tools](getting_started_build_tools.md)
@@ -34,6 +40,8 @@
   * [Keyboard Guidelines](hardware_keyboard_guidelines.md)
   * [Config Options](config_options.md)
   * [Keycodes](keycodes.md)
+  * [Coding Conventions - C](coding_conventions_c.md)
+  * [Coding Conventions - Python](coding_conventions_python.md)
   * [Documentation Best Practices](documentation_best_practices.md)
   * [Documentation Templates](documentation_templates.md)
   * [Glossary](reference_glossary.md)
@@ -41,6 +49,7 @@
   * [Useful Functions](ref_functions.md)
   * [Configurator Support](reference_configurator_support.md)
   * [info.json Format](reference_info_json.md)
+  * [Python CLI Development](cli_development.md)
 
 * [Features](features.md)
   * [Basic Keycodes](keycodes_basic.md)
@@ -55,6 +64,7 @@
   * [Combos](feature_combo.md)
   * [Command](feature_command.md)
   * [Debounce API](feature_debounce_type.md)
+  * [DIP Switch](feature_dip_switch.md)
   * [Dynamic Macros](feature_dynamic_macros.md)
   * [Encoders](feature_encoders.md)
   * [Grave Escape](feature_grave_esc.md)
@@ -73,6 +83,7 @@
   * [RGB Lighting](feature_rgblight.md)
   * [RGB Matrix](feature_rgb_matrix.md)
   * [Space Cadet](feature_space_cadet.md)
+  * [Split Keyboard](feature_split_keyboard.md)
   * [Stenography](feature_stenography.md)
   * [Swap Hands](feature_swap_hands.md)
   * [Tap Dance](feature_tap_dance.md)

docs/breaking_changes.md

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

docs/cli.md

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

docs/cli_configuration.md

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

docs/cli_development.md

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

docs/coding_conventions_c.md

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

docs/config_options.md

@@ -76,7 +76,7 @@ This is a C header file that is one of the first things included, and will persi
 * `#define B7_AUDIO`
   * enables audio on pin B7 (duophony is enables if one of B[5-7]\_AUDIO is enabled along with one of C[4-6]\_AUDIO)
 * `#define BACKLIGHT_PIN B7`
-  * pin of the backlight - `B5`, `B6`, `B7` and `C6` (and `D4` on ATmega32A) use hardware PWM, others use software implementation
+  * pin of the backlight
 * `#define BACKLIGHT_LEVELS 3`
   * number of levels your backlight will have (maximum 15 excluding off)
 * `#define BACKLIGHT_BREATHING`
@@ -89,10 +89,12 @@ This is a C header file that is one of the first things included, and will persi
   * mechanical locking support. Use KC_LCAP, KC_LNUM or KC_LSCR instead in keymap
 * `#define LOCKING_RESYNC_ENABLE`
   * tries to keep switch state consistent with keyboard LED state
-* `#define IS_COMMAND() (get_mods() == (MOD_BIT(KC_LSHIFT) | MOD_BIT(KC_RSHIFT)))`
+* `#define IS_COMMAND() (get_mods() == MOD_MASK_SHIFT)`
   * key combination that allows the use of magic commands (useful for debugging)
-* `#define USB_MAX_POWER_CONSUMPTION`
+* `#define USB_MAX_POWER_CONSUMPTION 500`
   * sets the maximum power (in mA) over USB for the device (default: 500)
+* `#define USB_POLLING_INTERVAL_MS 10`
+  * sets the USB polling rate in milliseconds for the keyboard, mouse, and shared (NKRO/media keys) interfaces
 * `#define F_SCL 100000L`
   * sets the I2C clock rate speed for keyboards using I2C. The default is `400000L`, except for keyboards using `split_common`, where the default is `100000L`.
 
@@ -171,8 +173,8 @@ If you define these options you will enable the associated feature, which may in
   * how long for the Combo keys to be detected. Defaults to `TAPPING_TERM` if not defined.
 * `#define TAP_CODE_DELAY 100`
   * Sets the delay between `register_code` and `unregister_code`, if you're having issues with it registering properly (common on VUSB boards). The value is in milliseconds.
-* `#define TAP_HOLD_CAPS_DELAY 200`
-  * Sets the delay for Tap Hold keys (`LT`, `MT`) when using `KC_CAPSLOCK` keycode, as this has some special handling on MacOS.  The value is in milliseconds, and defaults to 200ms if not defined. 
+* `#define TAP_HOLD_CAPS_DELAY 80`
+  * Sets the delay for Tap Hold keys (`LT`, `MT`) when using `KC_CAPSLOCK` keycode, as this has some special handling on MacOS.  The value is in milliseconds, and defaults to 80 ms if not defined. For macOS, you may want to set this to 200 or higher.
 
 ## RGB Light Configuration
 
@@ -248,6 +250,9 @@ There are a few different ways to set handedness for split keyboards (listed in
 * `#define MATRIX_COL_PINS_RIGHT { <col pins> }`
   * If you want to specify a different pinout for the right half than the left half, you can define `MATRIX_ROW_PINS_RIGHT`/`MATRIX_COL_PINS_RIGHT`. Currently, the size of `MATRIX_ROW_PINS` must be the same as `MATRIX_ROW_PINS_RIGHT` and likewise for the definition of columns.
 
+* `#define DIRECT_PINS_RIGHT { { F1, F0, B0, C7 }, { F4, F5, F6, F7 } }`
+  * If you want to specify a different direct pinout for the right half than the left half, you can define `DIRECT_PINS_RIGHT`. Currently, the size of `DIRECT_PINS` must be the same as `DIRECT_PINS_RIGHT`.
+
 * `#define RGBLED_SPLIT { 6, 6 }`
   * See [RGB Light Configuration](#rgb-light-configuration)
 
@@ -289,6 +294,7 @@ This is a [make](https://www.gnu.org/software/make/manual/make.html) file that i
   * `halfkay`
   * `caterina`
   * `bootloadHID`
+  * `USBasp`
 
 ## Feature Options
 

docs/contributing.md

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

docs/custom_quantum_functions.md

@@ -297,8 +297,8 @@ This runs code every time that the layers get changed.  This can be useful for l
 This example shows how to set the [RGB Underglow](feature_rgblight.md) lights based on the layer, using the Planck as an example
 
 ```c
-uint32_t layer_state_set_user(uint32_t state) {
-    switch (biton32(state)) {
+layer_state_t layer_state_set_user(layer_state_t state) {
+    switch (get_highest_layer(state)) {
     case _RAISE:
         rgblight_setrgb (0x00,  0x00, 0xFF);
         break;
@@ -320,8 +320,8 @@ uint32_t layer_state_set_user(uint32_t state) {
 ```
 ### `layer_state_set_*` Function Documentation
 
-* Keyboard/Revision: `uint32_t layer_state_set_kb(uint32_t state)`
-* Keymap: `uint32_t layer_state_set_user(uint32_t state)`
+* Keyboard/Revision: `layer_state_t layer_state_set_kb(layer_state_t state)`
+* Keymap: `layer_state_t layer_state_set_user(layer_state_t state)`
 
 
 The `state` is the bitmask of the active layers, as explained in the [Keymap Overview](keymap.md#keymap-layer-status)
@@ -377,8 +377,8 @@ void keyboard_post_init_user(void) {
 The above function will use the EEPROM config immediately after reading it, to set the default layer's RGB color. The "raw" value of it is converted in a usable structure based on the "union" that you created above. 
 
 ```c
-uint32_t layer_state_set_user(uint32_t state) {
-    switch (biton32(state)) {
+layer_state_t layer_state_set_user(layer_state_t state) {
+    switch (get_highest_layer(state)) {
     case _RAISE:
         if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_magenta(); rgblight_mode_noeeprom(1); }
         break;

docs/driver_installation_zadig.md

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

docs/faq_build.md

@@ -19,7 +19,11 @@ Note that running `make` with `sudo` is generally ***not*** a good idea, and you
 
 ### 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/`.
+`sudo` when flashing firmware, or place these files in `/etc/udev/rules.d/`. Once added run the following:
+```console
+sudo udevadm control --reload-rules
+sudo udevadm trigger
+```
 
 **/etc/udev/rules.d/50-atmel-dfu.rules:**
 ```
@@ -43,22 +47,39 @@ SUBSYSTEMS=="usb", ATTRS{idVendor}=="feed", MODE:="0666"
 SUBSYSTEMS=="usb", ATTRS{idVendor}=="1c11", MODE:="0666"
 ```
 
+**/etc/udev/rules.d/55-catalina.rules:**
+```
+# ModemManager should ignore the following devices
+ATTRS{idVendor}=="2a03", ENV{ID_MM_DEVICE_IGNORE}="1"
+ATTRS{idVendor}=="2341", ENV{ID_MM_DEVICE_IGNORE}="1"
+```
+
+**Note:** ModemManager filtering only works when not in strict mode, the following commands can update that settings:
+```console
+sudo sed -i 's/--filter-policy=strict/--filter-policy=default/' /lib/systemd/system/ModemManager.service
+sudo systemctl daemon-reload
+sudo systemctl restart ModemManager
+```
+
+**/etc/udev/rules.d/56-dfu-util.rules:**
+```
+# stm32duino
+SUBSYSTEMS=="usb", ATTRS{idVendor}=="1eaf", ATTRS{idProduct}=="0003", MODE:="0666"
+# Generic stm32
+SUBSYSTEMS=="usb", ATTRS{idVendor}=="0483", ATTRS{idProduct}=="df11", MODE:="0666"
+```
+
 ### Serial device is not detected in bootloader mode on Linux
 Make sure your kernel has appropriate support for your device. If your device uses USB ACM, such as
 Pro Micro (Atmega32u4), make sure to include `CONFIG_USB_ACM=y`. Other devices may require `USB_SERIAL` and any of its sub options.
 
 ## Unknown Device for DFU Bootloader
 
-If you're using Windows to flash your keyboard, and you are running into issues, check the Device Manager.  If you see an "Unknown Device" when the keyboard is in "bootloader mode", then you may have a driver issue.
+Issues encountered when flashing keyboards on Windows are most often due to having the wrong drivers installed for the bootloader, or none at all.
 
-Re-running the installation script for MSYS2 may help (eg run `./util/qmk_install.sh` from MSYS2/WSL) or reinstalling the QMK Toolbox may fix the issue.
-
-If that doesn't work, then you may need to grab the [Zadig Utility](https://zadig.akeo.ie/). Download this, find the device in question, and select the `WinUSB` option, and hit "Reinstall driver". Once you've done that, try flashing your board, again.  If that doesn't work, try all of the options, until one works. 
-
-?> There isn't a best option for which driver should be used here.  Some options work better on some systems than others.  libUSB and WinUSB seem to be the best options here.
-
-If the bootloader doesn't show up in the list for devices, you may need to enable the "List all devices" option in the `Options` menu, and then find the bootloader in question. 
+Re-running the QMK installation script (`./util/qmk_install.sh` from the `qmk_firmware` directory in MSYS2 or WSL) or reinstalling the QMK Toolbox may fix the issue. Alternatively, you can download and run the [`qmk_driver_installer`](https://github.com/qmk/qmk_driver_installer) package manually.
 
+If that doesn't work, then you may need to download and run Zadig. See [Bootloader Driver Installation with Zadig](driver_installation_zadig.md) for more detailed information.
 
 ## WINAVR is Obsolete
 It is no longer recommended and may cause some problem.

docs/faq_debug.md

@@ -87,6 +87,7 @@ Size after:
 - 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**.
 
@@ -183,22 +184,15 @@ Pressing any key during sleep should wake host.
 
 Arduino Leonardo and micro have **ATMega32U4** and can be used for TMK, though Arduino bootloader may be a problem.
 
+## Enabling JTAG
 
-## Using PF4-7 Pins of USB AVR?
-You need to set JTD bit of MCUCR yourself to use PF4-7 as GPIO. Those pins are configured to serve JTAG function by default. MCUs like ATMega*U* or AT90USB* are affected with this.
+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 are using Teensy this isn't needed. Teensy is shipped with JTAGEN fuse bit unprogrammed to disable the function.
+If you would like to keep JTAG enabled, just add the following to your `config.h`:
 
-See this code.
+```c
+#define NO_JTAG_DISABLE
 ```
-    // JTAG disable for PORT F. write JTD bit twice within four cycles.
-    MCUCR |= (1<<JTD);
-    MCUCR |= (1<<JTD);
-```
-https://github.com/tmk/tmk_keyboard/blob/master/keyboard/hbkb/matrix.c#L67
-
-And read **26.5.1 MCU Control Register – MCUCR** of ATMega32U4 datasheet.
-
 
 ## Adding LED Indicators of Lock Keys
 You need your own LED indicators for CapsLock, ScrollLock and NumLock? See this post.

docs/feature_audio.md

@@ -21,6 +21,8 @@ STARTUP_SONG // plays when the keyboard starts up (audio.c)
 GOODBYE_SONG // plays when you press the RESET key (quantum.c)
 AG_NORM_SONG // plays when you press AG_NORM (quantum.c)
 AG_SWAP_SONG // plays when you press AG_SWAP (quantum.c)
+CG_NORM_SONG // plays when you press CG_NORM (quantum.c)
+CG_SWAP_SONG // plays when you press CG_SWAP (quantum.c)
 MUSIC_ON_SONG // plays when music mode is activated (process_music.c)
 MUSIC_OFF_SONG // plays when music mode is deactivated (process_music.c)
 CHROMATIC_SONG // plays when the chromatic music mode is selected (process_music.c)