Fix MATRIX_X_PINS_RIGHT ARM compilation (#6395)

* Add my plaid keymap

* Move planck / plaid keymaps to common layout folder

.editorconfig

@@ -16,12 +16,18 @@ 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
+indent_style = tab
 
 [Makefile]
 end_of_line = lf
+indent_style = tab
 
 [*.sh]
 end_of_line = lf

.gitignore

@@ -70,3 +70,6 @@ util/Win_Check_Output.txt
 secrets.tar
 id_rsa_*
 /.vs
+
+# python things
+__pycache__

.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:

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

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,97 @@
+#!/usr/bin/env python3
+"""CLI wrapper for running QMK commands.
+"""
+import os
+import subprocess
+import sys
+from glob import glob
+from time import strftime
+from importlib import import_module
+from importlib.util import find_spec
+
+# 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)
+
+# Change to the root of our checkout
+os.environ['ORIG_CWD'] = os.getcwd()
+os.chdir(qmk_dir)
+
+# Make sure our modules have been setup
+with open('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('Your QMK build environment is not fully setup!\n')
+            print('Please run `./util/qmk_install.sh` to setup QMK.')
+            exit(255)
+
+# Figure out our version
+command = ['git', 'describe', '--abbrev=6', '--dirty', '--always', '--tags']
+result = subprocess.run(command, text=True, capture_output=True)
+
+if result.returncode == 0:
+    os.environ['QMK_VERSION'] = 'QMK ' + result.stdout.strip()
+else:
+    os.environ['QMK_VERSION'] = 'QMK ' + strftime('%Y-%m-%d-%H:%M:%S')
+
+# Setup the CLI
+import milc
+milc.EMOJI_LOGLEVELS['INFO'] = '{fg_blue}ψ{style_reset_all}'
+
+# If we were invoked as `qmk <cmd>` massage sys.argv into `qmk-<cmd>`.
+# This means we can't accept arguments to the qmk script itself.
+script_name = os.path.basename(sys.argv[0])
+if script_name == 'qmk':
+    if len(sys.argv) == 1:
+        milc.cli.log.error('No subcommand specified!\n')
+
+    if len(sys.argv) == 1 or sys.argv[1] in ['-h', '--help']:
+        milc.cli.echo('usage: qmk <subcommand> [...]')
+        milc.cli.echo('\nsubcommands:')
+        subcommands = glob(os.path.join(qmk_dir, 'bin', 'qmk-*'))
+        for subcommand in sorted(subcommands):
+            subcommand = os.path.basename(subcommand).split('-', 1)[1]
+            milc.cli.echo('\t%s', subcommand)
+        milc.cli.echo('\nqmk <subcommand> --help for more information')
+        exit(1)
+
+    if sys.argv[1] in ['-V', '--version']:
+        milc.cli.echo(os.environ['QMK_VERSION'])
+        exit(0)
+
+    sys.argv[0] = script_name = '-'.join((script_name, sys.argv[1]))
+    del sys.argv[1]
+
+# Look for which module to import
+if script_name == 'qmk':
+    milc.cli.print_help()
+    exit(0)
+elif not script_name.startswith('qmk-'):
+    milc.cli.log.error('Invalid symlink, must start with "qmk-": %s', script_name)
+else:
+    subcommand = script_name.replace('-', '.').replace('_', '.').split('.')
+    subcommand.insert(1, 'cli')
+    subcommand = '.'.join(subcommand)
+
+    try:
+        import_module(subcommand)
+    except ModuleNotFoundError as e:
+        if e.__class__.__name__ != subcommand:
+            raise
+
+        milc.cli.log.error('Invalid subcommand! Could not import %s.', subcommand)
+        exit(1)
+
+if __name__ == '__main__':
+    milc.cli()

bin/qmk-compile-json

@@ -0,0 +1 @@
+qmk

bin/qmk-doctor

@@ -0,0 +1 @@
+qmk

bin/qmk-hello

@@ -0,0 +1 @@
+qmk

bin/qmk-json-keymap

@@ -0,0 +1 @@
+qmk

bootloader.mk

@@ -76,6 +76,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

@@ -133,7 +133,7 @@ ifeq ($(strip $(LED_MATRIX_ENABLE)), IS31FL3731)
     OPT_DEFS += -DIS31FL3731
     COMMON_VPATH += $(DRIVER_PATH)/issi
     SRC += is31fl3731-simple.c
-    SRC += i2c_master.c
+    QUANTUM_LIB_SRC += i2c_master.c
 endif
 
 RGB_MATRIX_ENABLE ?= no
@@ -157,21 +157,21 @@ ifeq ($(strip $(RGB_MATRIX_ENABLE)), IS31FL3731)
     OPT_DEFS += -DIS31FL3731 -DSTM32_I2C -DHAL_USE_I2C=TRUE
     COMMON_VPATH += $(DRIVER_PATH)/issi
     SRC += is31fl3731.c
-    SRC += i2c_master.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
-    SRC += i2c_master.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
-    SRC += i2c_master.c
+    QUANTUM_LIB_SRC += i2c_master.c
 endif
 
 ifeq ($(strip $(RGB_MATRIX_ENABLE)), WS2812)
@@ -271,7 +271,7 @@ ifeq ($(strip $(HAPTIC_ENABLE)), DRV2605L)
     COMMON_VPATH += $(DRIVER_PATH)/haptic
     SRC += haptic.c
     SRC += DRV2605L.c
-    SRC += i2c_master.c
+    QUANTUM_LIB_SRC += i2c_master.c
     OPT_DEFS += -DHAPTIC_ENABLE
     OPT_DEFS += -DDRV2605L
 endif

docs/_summary.md

@@ -8,6 +8,7 @@
 
 * [QMK Basics](README.md)
   * [QMK Introduction](getting_started_introduction.md)
+  * [QMK CLI](cli.md)
   * [Contributing to QMK](contributing.md)
   * [How to Use Github](getting_started_github.md)
   * [Getting Help](getting_started_getting_help.md)
@@ -34,6 +35,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 +44,7 @@
   * [Useful Functions](ref_functions.md)
   * [Configurator Support](reference_configurator_support.md)
   * [info.json Format](reference_info_json.md)
+  * [Python Development](python_development.md)
 
 * [Features](features.md)
   * [Basic Keycodes](keycodes_basic.md)
@@ -73,6 +77,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/cli.md

@@ -0,0 +1,31 @@
+# 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 help you work with QMK:
+
+* `qmk compile-json`
+
+# Setup
+
+Simply add the `qmk_firmware/bin` directory to your `PATH`. You can run the `qmk` commands from any directory.
+
+```
+export PATH=$PATH:$HOME/qmk_firmware/bin
+```
+
+You may want to add this to your `.profile`, `.bash_profile`, `.zsh_profile`, or other shell startup scripts.
+
+# Commands
+
+## `qmk compile-json`
+
+This command allows you to compile JSON files you have downloaded from <https://config.qmk.fm>.
+
+**Usage**:
+
+```
+qmk compile-json mine.json
+```

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

@@ -89,7 +89,7 @@ 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`
   * sets the maximum power (in mA) over USB for the device (default: 500)
@@ -171,8 +171,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
 
@@ -289,6 +289,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/faq_build.md

@@ -49,15 +49,13 @@ Pro Micro (Atmega32u4), make sure to include `CONFIG_USB_ACM=y`. Other devices m
 
 ## 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. 
 
-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.
+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. Alternatively, you can download and run the [`qmk_driver_installer`](https://github.com/qmk/qmk_driver_installer) package.
 
-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. 
+If that doesn't work, then you may need to grab the [Zadig Utility](https://zadig.akeo.ie/). Download this, and run it on the system.  Then, you will need to reset your board into bootloader mode.  After that, locate the device in question. If the device doesn't show up in the list (or nothing shows up in the list), you may need to enable the `List all devices` option in the `Options` menu.
 
-?> 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. 
+From here, you will need to know what type of controller the board is using.  You may see it listed in the Device Manager as `ATmega32U4` device (which is an AVR board), or an `STM32` device (Which is an ARM board).  For AVR boards, use `libusb-win32` for the driver. For ARM boards, use the `WinUSB` driver.  Once the correct driver type has been selected, click on the `Replace Driver` button, unplug your board, plug it back in, and reset it again.
 
 
 ## WINAVR is Obsolete

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**.
 

docs/feature_advanced_keycodes.md

@@ -256,10 +256,10 @@ If you press a Mod Tap key, tap another key (press and release) and then release
 
 For Instance:
 
-- `SHFT_T(KC_A)` Down
+- `SFT_T(KC_A)` Down
 - `KC_X` Down
 - `KC_X` Up
-- `SHFT_T(KC_A)` Up
+- `SFT_T(KC_A)` Up
 
 Normally, if you do all this within the `TAPPING_TERM` (default: 200ms) this will be registered as `ax` by the firmware and host system. With permissive hold enabled, this modifies how this is handled by considering the Mod Tap keys as a Mod if another key is tapped, and would registered as `X` (`SHIFT`+`x`). 
 
@@ -279,9 +279,9 @@ Setting `Ignore Mod Tap Interrupt` requires  holding both keys for the `TAPPING_
 
 For Instance:
 
-- `SHFT_T(KC_A)` Down
+- `SFT_T(KC_A)` Down
 - `KC_X` Down
-- `SHFT_T(KC_A)` Up
+- `SFT_T(KC_A)` Up
 - `KC_X` Up
 
 Normally, this would send `X` (`SHIFT`+`x`). With `Ignore Mod Tap Interrupt` enabled, holding both keys are required for the `TAPPING_TERM` to register the hold action. A quick tap will output `ax` in this case, while a hold on both will still output `X`  (`SHIFT`+`x`).
@@ -303,11 +303,11 @@ When the user holds a key after tap, this repeats the tapped key rather to hold
 
 Example:
 
-- SHFT_T(KC_A) Down
-- SHFT_T(KC_A) Up
-- SHFT_T(KC_A) Down
+- SFT_T(KC_A) Down
+- SFT_T(KC_A) Up
+- SFT_T(KC_A) Down
 - wait more than tapping term...
-- SHFT_T(KC_A) Up
+- SFT_T(KC_A) Up
 
 With default settings, `a` will be sent on the first release, then `a` will be sent on the second press allowing the computer to trigger its auto repeat function.
 

docs/feature_backlight.md

@@ -65,7 +65,7 @@ To change the behaviour of the backlighting, `#define` these in your `config.h`:
 |---------------------|-------------|-------------------------------------------------------------------------------------------------------------|
 |`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 15 excluding off)                                                   |
+|`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                                                              |
@@ -73,8 +73,10 @@ To change the behaviour of the backlighting, `#define` these in your `config.h`:
 
 ## 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, *low*.
-Sometimes, however, a P-channel MOSFET, or a PNP transistor is used. In this case you must `#define BACKLIGHT_ON_STATE 1`, so that when the transistor is on, the pin is driven *high* instead.
+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
 

docs/feature_combo.md

@@ -59,19 +59,12 @@ void process_combo_event(uint8_t combo_index, bool pressed) {
   switch(combo_index) {
     case ZC_COPY:
       if (pressed) {
-        register_code(KC_LCTL);
-        register_code(KC_C);
-        unregister_code(KC_C);
-        unregister_code(KC_LCTL);
+        tap_code16(LCTL(KC_C));
       }
       break;
-
     case XV_PASTE:
       if (pressed) {
-        register_code(KC_LCTL);
-        register_code(KC_V);
-        unregister_code(KC_V);
-        unregister_code(KC_LCTL);
+        tap_code16(LCTL(KC_V));
       }
       break;
   }
@@ -87,3 +80,24 @@ If you're using long combos, or even longer combos, you may run into issues with
 In this case, you can add either `#define EXTRA_LONG_COMBOS` or `#define EXTRA_EXTRA_LONG_COMBOS` in your `config.h` file.
 
 You may also be able to enable action keys by defining `COMBO_ALLOW_ACTION_KEYS`.
+
+## Keycodes 
+
+You can enable, disable and toggle the Combo feature on the fly.  This is useful if you need to disable them temporarily, such as for a game. 
+
+|Keycode   |Description                      |
+|----------|---------------------------------|
+|`CMB_ON`  |Turns on Combo feature           |
+|`CMB_OFF` |Turns off Combo feature          |
+|`CMB_TOG` |Toggles Combo feature on and off |
+
+## User callbacks
+
+In addition to the keycodes, there are a few functions that you can use to set the status, or check it:
+
+|Function   |Description                                                         |
+|-----------|--------------------------------------------------------------------|
+| `combo_enable()`     | Enables the combo feature                               |
+| `combo_disable()`    | Disables the combo feature, and clears the combo buffer |
+| `combo_toggle()`     | Toggles the state of the combo feature                  |
+| `is_combo_enabled()` | Returns the status of the combo feature state (true or false) |

docs/feature_command.md

@@ -16,36 +16,36 @@ To use Command, hold down the key combination defined by the `IS_COMMAND()` macr
 
 If you would like to change the key assignments for Command, `#define` these in your `config.h` at either the keyboard or keymap level. All keycode assignments here must omit the `KC_` prefix.
 
-|Define                              |Default                                                                    |Description                                     |
-|------------------------------------|---------------------------------------------------------------------------|------------------------------------------------|
-|`IS_COMMAND()`                      |<code>(get_mods() == (MOD_BIT(KC_LSHIFT) &#124; MOD_BIT(KC_RSHIFT)))</code>|The key combination to activate Command         |
-|`MAGIC_KEY_SWITCH_LAYER_WITH_FKEYS` |`true`                                                                     |Set default layer with the Function row         |
-|`MAGIC_KEY_SWITCH_LAYER_WITH_NKEYS` |`true`                                                                     |Set default layer with the number keys          |
-|`MAGIC_KEY_SWITCH_LAYER_WITH_CUSTOM`|`false`                                                                    |Set default layer with `MAGIC_KEY_LAYER0..9`    |
-|`MAGIC_KEY_DEBUG`                   |`D`                                                                        |Toggle debugging over serial                    |
-|`MAGIC_KEY_DEBUG_MATRIX`            |`X`                                                                        |Toggle key matrix debugging                     |
-|`MAGIC_KEY_DEBUG_KBD`               |`K`                                                                        |Toggle keyboard debugging                       |
-|`MAGIC_KEY_DEBUG_MOUSE`             |`M`                                                                        |Toggle mouse debugging                          |
-|`MAGIC_KEY_CONSOLE`                 |`C`                                                                        |Enable the Command console                      |
-|`MAGIC_KEY_VERSION`                 |`V`                                                                        |Print the running QMK version to the console    |
-|`MAGIC_KEY_STATUS`                  |`S`                                                                        |Print the current keyboard status to the console|
-|`MAGIC_KEY_HELP`                    |`H`                                                                        |Print Command help to the console               |
-|`MAGIC_KEY_HELP_ALT`                |`SLASH`                                                                    |Print Command help to the console (alternate)   |
-|`MAGIC_KEY_LAYER0`                  |`0`                                                                        |Make layer 0 the default layer                  |
-|`MAGIC_KEY_LAYER0_ALT`              |`GRAVE`                                                                    |Make layer 0 the default layer (alternate)      |
-|`MAGIC_KEY_LAYER1`                  |`1`                                                                        |Make layer 1 the default layer                  |
-|`MAGIC_KEY_LAYER2`                  |`2`                                                                        |Make layer 2 the default layer                  |
-|`MAGIC_KEY_LAYER3`                  |`3`                                                                        |Make layer 3 the default layer                  |
-|`MAGIC_KEY_LAYER4`                  |`4`                                                                        |Make layer 4 the default layer                  |
-|`MAGIC_KEY_LAYER5`                  |`5`                                                                        |Make layer 5 the default layer                  |
-|`MAGIC_KEY_LAYER6`                  |`6`                                                                        |Make layer 6 the default layer                  |
-|`MAGIC_KEY_LAYER7`                  |`7`                                                                        |Make layer 7 the default layer                  |
-|`MAGIC_KEY_LAYER8`                  |`8`                                                                        |Make layer 8 the default layer                  |
-|`MAGIC_KEY_LAYER9`                  |`9`                                                                        |Make layer 9 the default layer                  |
-|`MAGIC_KEY_BOOTLOADER`              |`B`                                                                        |Jump to bootloader                              |
-|`MAGIC_KEY_BOOTLOADER_ALT`          |`ESC`                                                                      |Jump to bootloader (alternate)                  |
-|`MAGIC_KEY_LOCK`                    |`CAPS`                                                                     |Lock the keyboard so nothing can be typed       |
-|`MAGIC_KEY_EEPROM`                  |`E`                                                                        |Print stored EEPROM config to the console       |
-|`MAGIC_KEY_EEPROM_CLEAR`            |`BSPACE`                                                                   |Clear the EEPROM                                |
-|`MAGIC_KEY_NKRO`                    |`N`                                                                        |Toggle N-Key Rollover (NKRO)                    |
-|`MAGIC_KEY_SLEEP_LED`               |`Z`                                                                        |Toggle LED when computer is sleeping            |
+|Define                              |Default                         |Description                                     |
+|------------------------------------|--------------------------------|------------------------------------------------|
+|`IS_COMMAND()`                      |`(get_mods() == MOD_MASK_SHIFT)`|The key combination to activate Command         |
+|`MAGIC_KEY_SWITCH_LAYER_WITH_FKEYS` |`true`                          |Set default layer with the Function row         |
+|`MAGIC_KEY_SWITCH_LAYER_WITH_NKEYS` |`true`                          |Set default layer with the number keys          |
+|`MAGIC_KEY_SWITCH_LAYER_WITH_CUSTOM`|`false`                         |Set default layer with `MAGIC_KEY_LAYER0..9`    |
+|`MAGIC_KEY_DEBUG`                   |`D`                             |Toggle debugging over serial                    |
+|`MAGIC_KEY_DEBUG_MATRIX`            |`X`                             |Toggle key matrix debugging                     |
+|`MAGIC_KEY_DEBUG_KBD`               |`K`                             |Toggle keyboard debugging                       |
+|`MAGIC_KEY_DEBUG_MOUSE`             |`M`                             |Toggle mouse debugging                          |
+|`MAGIC_KEY_CONSOLE`                 |`C`                             |Enable the Command console                      |
+|`MAGIC_KEY_VERSION`                 |`V`                             |Print the running QMK version to the console    |
+|`MAGIC_KEY_STATUS`                  |`S`                             |Print the current keyboard status to the console|
+|`MAGIC_KEY_HELP`                    |`H`                             |Print Command help to the console               |
+|`MAGIC_KEY_HELP_ALT`                |`SLASH`                         |Print Command help to the console (alternate)   |
+|`MAGIC_KEY_LAYER0`                  |`0`                             |Make layer 0 the default layer                  |
+|`MAGIC_KEY_LAYER0_ALT`              |`GRAVE`                         |Make layer 0 the default layer (alternate)      |
+|`MAGIC_KEY_LAYER1`                  |`1`                             |Make layer 1 the default layer                  |
+|`MAGIC_KEY_LAYER2`                  |`2`                             |Make layer 2 the default layer                  |
+|`MAGIC_KEY_LAYER3`                  |`3`                             |Make layer 3 the default layer                  |
+|`MAGIC_KEY_LAYER4`                  |`4`                             |Make layer 4 the default layer                  |
+|`MAGIC_KEY_LAYER5`                  |`5`                             |Make layer 5 the default layer                  |
+|`MAGIC_KEY_LAYER6`                  |`6`                             |Make layer 6 the default layer                  |
+|`MAGIC_KEY_LAYER7`                  |`7`                             |Make layer 7 the default layer                  |
+|`MAGIC_KEY_LAYER8`                  |`8`                             |Make layer 8 the default layer                  |
+|`MAGIC_KEY_LAYER9`                  |`9`                             |Make layer 9 the default layer                  |
+|`MAGIC_KEY_BOOTLOADER`              |`B`                             |Jump to bootloader                              |
+|`MAGIC_KEY_BOOTLOADER_ALT`          |`ESC`                           |Jump to bootloader (alternate)                  |
+|`MAGIC_KEY_LOCK`                    |`CAPS`                          |Lock the keyboard so nothing can be typed       |
+|`MAGIC_KEY_EEPROM`                  |`E`                             |Print stored EEPROM config to the console       |
+|`MAGIC_KEY_EEPROM_CLEAR`            |`BSPACE`                        |Clear the EEPROM                                |
+|`MAGIC_KEY_NKRO`                    |`N`                             |Toggle N-Key Rollover (NKRO)                    |
+|`MAGIC_KEY_SLEEP_LED`               |`Z`                             |Toggle LED when computer is sleeping            |

docs/feature_encoders.md

@@ -6,7 +6,6 @@ Basic encoders are supported by adding this to your `rules.mk`:
 
 and this to your `config.h`:
 
-    #define NUMBER_OF_ENCODERS 1
     #define ENCODERS_PAD_A { B12 }
     #define ENCODERS_PAD_B { B13 }
 

docs/feature_oled_driver.md

@@ -14,7 +14,7 @@ Tested combinations:
 
 Hardware configurations using ARM-based microcontrollers or different sizes of OLED modules may be compatible, but are untested.
 
-!> Warning: This OLED Driver currently uses the new i2c_master driver from split common code. If your split keyboard uses i2c to communication between sides this driver could cause an address conflict (serial is fine). Please contact your keyboard vendor and ask them to migrate to the latest split common code to fix this. 
+!> Warning: This OLED Driver currently uses the new i2c_master driver from split common code. If your split keyboard uses I2C to communicate between sides, this driver could cause an address conflict (serial is fine). Please contact your keyboard vendor and ask them to migrate to the latest split common code to fix this. In addition, the display timeout system to reduce OLED burn-in also uses split common to detect keypresses, so you will need to implement custom timeout logic for non-split common keyboards.
 
 ## Usage
 

docs/feature_space_cadet.md

@@ -43,6 +43,7 @@ By default Space Cadet assumes a US ANSI layout, but if your layout uses differe
 |`LAPO_KEYS`     |`KC_LALT, KC_LSFT, KC_9`       |Send `KC_LALT` when held, the mod `KC_LSFT` with the key `KC_9` when tapped.     |
 |`RAPC_KEYS`     |`KC_RALT, KC_RSFT, KC_0`       |Send `KC_RALT` when held, the mod `KC_RSFT` with the key `KC_0` when tapped.     |
 |`SFTENT_KEYS`   |`KC_RSFT, KC_TRNS, SFTENT_KEY` |Send `KC_RSFT` when held, no mod with the key `SFTENT_KEY` when tapped.          |
+|`SPACE_CADET_MODIFIER_CARRYOVER`   |*Not defined* |Store current modifiers before the hold mod is pressed and use them with the tap mod and keycode. Useful for when you frequently release a modifier before triggering Space Cadet.  |
 
 
 ## Obsolete Configuration

docs/feature_split_keyboard.md

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