ARM split - Add support for dfu-util EE_HANDS flashing (#6543)

* Initial stab at some fake dfu-util-split-left behaviour

* Apply suggestions from code review

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

* Clang format fixes

* Fake eeprom init for both left and right hand

.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

.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"
     }
 }

Makefile

@@ -371,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)))
@@ -407,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

bin/qmk

@@ -4,10 +4,8 @@
 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
+from time import strftime
 
 # Add the QMK python libs to our path
 script_dir = os.path.dirname(os.path.realpath(__file__))
@@ -15,12 +13,8 @@ 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:
+with open(os.path.join(qmk_dir, 'requirements.txt'), 'r') as fd:
     for line in fd.readlines():
         line = line.strip().replace('<', '=').replace('>', '=')
 
@@ -32,72 +26,58 @@ with open('requirements.txt', 'r') as fd:
 
         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.')
+            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.PIPE)
+result = subprocess.run(command, universal_newlines=True, stdout=subprocess.PIPE, stderr=subprocess.STDOUT)
 
 if result.returncode == 0:
-    os.environ['QMK_VERSION'] = 'QMK ' + result.stdout.strip()
+    os.environ['QMK_VERSION'] = result.stdout.strip()
 else:
-    os.environ['QMK_VERSION'] = 'QMK ' + strftime('%Y-%m-%d-%H:%M:%S')
+    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}'
 
-# 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)
+@milc.cli.entrypoint('QMK Helper Script')
+def qmk_main(cli):
+    """The function that gets run when no subcommand is provided.
+    """
+    cli.print_help()
 
-    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]
+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)
 
-# 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)
+    # Import the subcommands
+    import qmk.cli
 
-    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__':
+    # Execute
     return_code = milc.cli()
+
     if return_code is False:
         exit(1)
-    elif return_code is not True and isinstance(return_code, int) and return_code < 256:
+
+    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)
-    else:
-        exit(0)
+
+    exit(0)
+
+
+if __name__ == '__main__':
+    main()

bin/qmk-compile-json

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

bin/qmk-doctor

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

bin/qmk-hello

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

bin/qmk-json-keymap

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

build_json.mk

@@ -23,5 +23,5 @@ endif
 
 # Generate the keymap.c
 ifneq ("$(KEYMAP_JSON)","")
-    _ = $(shell test -e $(KEYMAP_C) || bin/qmk-json-keymap $(KEYMAP_JSON) -o $(KEYMAP_C))
+    _ = $(shell test -e $(KEYMAP_C) || bin/qmk json-keymap $(KEYMAP_JSON) -o $(KEYMAP_C))
 endif

docs/_summary.md

@@ -9,6 +9,7 @@
 * [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)
@@ -48,7 +49,7 @@
   * [Useful Functions](ref_functions.md)
   * [Configurator Support](reference_configurator_support.md)
   * [info.json Format](reference_info_json.md)
-  * [Python Development](python_development.md)
+  * [Python CLI Development](cli_development.md)
 
 * [Features](features.md)
   * [Basic Keycodes](keycodes_basic.md)

docs/breaking_changes.md

@@ -14,7 +14,7 @@ The next Breaking Change is scheduled for Nov 29.
 
 ### Important Dates
 
-* [ ] 2019 Oct 04 - `future` is created. It will be rebased weekly.
+* [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.
@@ -51,7 +51,9 @@ git rebase master
 git push --force
 ```
 
-## 8 Weeks Before Merge
+## Creating the `future` branch
+
+This happens immediately after the previous `future` branch is merged.
 
 * `qmk_firmware` git commands
     * [ ] `git checkout master`
@@ -65,9 +67,6 @@ git push --force
     * [ ] `git tag <next_version>` # Prevent the breakpoint tag from confusing version incrementing
     * [ ] `git push origin future`
     * [ ] `git push --tags`
-* GitHub Actions
-    * [ ] Switch all [breaking_change PR's](https://github.com/qmk/qmk_firmware/pulls?utf8=%E2%9C%93&q=is%3Apr+is%3Aopen+label%3Abreaking_change) to `future`
-    * [ ] Any that have a ChangeLog entry may be merged immediately.
 
 ## 4 Weeks Before Merge
 

docs/cli.md

@@ -4,22 +4,70 @@ 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:
+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.
 
-* `qmk compile`
-* `qmk doctor`
+* [Global CLI](#global-cli)
+* [Local CLI](#local-cli)
+* [CLI Commands](#cli-commands)
 
-# Setup
+# Requirements
 
-Simply add the `qmk_firmware/bin` directory to your `PATH`. You can run the `qmk` commands from any directory.
+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:
 
 ```
-export PATH=$PATH:$HOME/qmk_firmware/bin
+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
 ```
 
-You may want to add this to your `.profile`, `.bash_profile`, `.zsh_profile`, or other shell startup scripts.
+## Install Using easy_install or pip
 
-# Commands
+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`
 
@@ -46,3 +94,53 @@ This command formats C code using clang-format. Run it with no arguments to form
 ```
 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/config_options.md

@@ -224,6 +224,7 @@ There are a few different ways to set handedness for split keyboards (listed in
 2. Set `EE_HANDS` and flash `eeprom-lefthand.eep`/`eeprom-righthand.eep` to each half
    * For boards with DFU bootloader you can use `:dfu-split-left`/`:dfu-split-right` to flash these EEPROM files
    * For boards with Caterina bootloader (like stock Pro Micros), use `:avrdude-split-left`/`:avrdude-split-right`
+   * For boards with ARM DFU bootloader (like Proton C), use `:dfu-util-split-left`/`:dfu-util-split-right`
 3. Set `MASTER_RIGHT`: Half that is plugged into the USB port is determined to be the master and right half (inverse of the default)
 4. Default: The side that is plugged into the USB port is the master half and is assumed to be the left half. The slave side is the right half
 

docs/driver_installation_zadig.md

@@ -8,10 +8,14 @@ We recommend the use of the [Zadig](https://zadig.akeo.ie/) utility. If you have
 
 ## Installation
 
-Place your keyboard into the bootloader mode, either by hitting the `RESET` keycode (which may be on a different layer), or by pressing the reset switch 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 keyboards may have specific instructions for entering the bootloader, for example the [Bootmagic Lite](feature_bootmagic.md#bootmagic-lite) key (Escape) might be on a different key, such as Left Control. Refer to the board's README if you are unsure.
+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**.
 
-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`.
@@ -19,7 +23,7 @@ Zadig will automatically detect the bootloader device. You may sometimes need to
 
 !> 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.
+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)
 
@@ -39,4 +43,4 @@ Right-click it and hit **Uninstall device**. Make sure to tick **Delete the driv
 
 ![The Device Uninstall dialog, with the "delete driver" checkbox ticked](https://i.imgur.com/aEs2RuA.png)
 
-Click **Action -> Scan for hardware changes**. At this point, you should be able to type again. Double check in Zadig that the keyboard device(s) are using the `HidUsb` driver. If so, you're all done, and your board should be functional again!
+Click **Action → Scan for hardware changes**. At this point, you should be able to type again. Double check in Zadig that the keyboard device(s) are using the `HidUsb` driver. If so, you're all done, and your board should be functional again!

docs/feature_backlight.md

@@ -32,16 +32,18 @@ This feature is distinct from both the [RGB underglow](feature_rgblight.md) and
 
 Hardware PWM is supported according to the following table:
 
-|Backlight Pin|AT90USB64/128|ATmega16/32U4|ATmega16/32U2|ATmega32A|
-|-------------|-------------|-------------|-------------|---------|
-|`B5`         |Timer 1      |Timer 1      |             |         |
-|`B6`         |Timer 1      |Timer 1      |             |         |
-|`B7`         |Timer 1      |Timer 1      |Timer 1      |         |
-|`C4`         |Timer 3      |             |             |         |
-|`C5`         |Timer 3      |             |Timer 1      |         |
-|`C6`         |Timer 3      |Timer 3      |Timer 1      |         |
-|`D4`         |             |             |             |Timer 1  |
-|`D5`         |             |             |             |Timer 1  |
+|Backlight Pin|AT90USB64/128|ATmega16/32U4|ATmega16/32U2|ATmega32A|ATmega328P|
+|-------------|-------------|-------------|-------------|---------|----------|
+|`B1`         |             |             |             |         |Timer 1   |
+|`B2`         |             |             |             |         |Timer 1   |
+|`B5`         |Timer 1      |Timer 1      |             |         |          |
+|`B6`         |Timer 1      |Timer 1      |             |         |          |
+|`B7`         |Timer 1      |Timer 1      |Timer 1      |         |          |
+|`C4`         |Timer 3      |             |             |         |          |
+|`C5`         |Timer 3      |             |Timer 1      |         |          |
+|`C6`         |Timer 3      |Timer 3      |Timer 1      |         |          |
+|`D4`         |             |             |             |Timer 1  |          |
+|`D5`         |             |             |             |Timer 1  |          |
 
 All other pins will use software PWM. If the [Audio](feature_audio.md) feature is disabled or only using one timer, the backlight PWM can be triggered by a hardware timer:
 

docs/feature_bootmagic.md

@@ -34,6 +34,8 @@ Hold down the Bootmagic key (Space by default) and the desired hotkey while plug
 |`X`               |Toggle key matrix debugging                  |
 |`K`               |Toggle keyboard debugging                    |
 |`M`               |Toggle mouse debugging                       |
+|`L`               |Set "Left Hand" for EE_HANDS handedness      |
+|`R`               |Set "Right Hand" for EE_HANDS handedness     |
 |Backspace         |Clear the EEPROM                             |
 |Caps Lock         |Toggle treating Caps Lock as Left Control    |
 |Left Control      |Toggle swapping Caps Lock and Left Control   |
@@ -83,6 +85,8 @@ Hold down the Bootmagic key (Space by default) and the desired hotkey while plug
 |`MAGIC_UNSWAP_LCTL_LGUI`          |         |Unswap Left Control and Left GUI          |
 |`MAGIC_SWAP_RCTL_RGUI`            |         |Swap Right Control and Right GUI          |
 |`MAGIC_UNSWAP_RCTL_RGUI`          |         |Unswap Right Control and Right GUI        |
+|`MAGIC_EE_HANDS_LEFT`             |         |Set "Left Hand" for EE_HANDS handedness   |
+|`MAGIC_EE_HANDS_RIGHT`            |         |Set "Right Hand" for EE_HANDS handedness  |
 
 ## Configuration
 
@@ -98,6 +102,8 @@ If you would like to change the hotkey assignments for Bootmagic, `#define` thes
 |`BOOTMAGIC_KEY_DEBUG_MATRIX`            |`KC_X`       |Toggle matrix debugging                            |
 |`BOOTMAGIC_KEY_DEBUG_KEYBOARD`          |`KC_K`       |Toggle keyboard debugging                          |
 |`BOOTMAGIC_KEY_DEBUG_MOUSE`             |`KC_M`       |Toggle mouse debugging                             |
+|`BOOTMAGIC_KEY_EE_HANDS_LEFT`           |`KC_L`       |Set "Left Hand" for EE_HANDS handedness            |
+|`BOOTMAGIC_KEY_EE_HANDS_RIGHT`          |`KC_R`       |Set "Right Hand" for EE_HANDS handedness           |
 |`BOOTMAGIC_KEY_SWAP_CONTROL_CAPSLOCK`   |`KC_LCTRL`   |Swap Left Control and Caps Lock                    |
 |`BOOTMAGIC_KEY_CAPSLOCK_TO_CONTROL`     |`KC_CAPSLOCK`|Toggle treating Caps Lock as Left Control          |
 |`BOOTMAGIC_KEY_SWAP_LALT_LGUI`          |`KC_LALT`    |Toggle swapping Left Alt and Left GUI (for macOS)  |

docs/feature_split_keyboard.md

@@ -96,6 +96,8 @@ However, you'll have to flash the EEPROM files for the correct hand to each cont
 * `:avrdude-split-right`
 * `:dfu-split-left`
 * `:dfu-split-right`
+* `:dfu-util-split-left`
+* `:dfu-util-split-right`
 
 This setting is not changed when re-initializing the EEPROM using the `EEP_RST` key, or using the `eeconfig_init()` function.  However, if you reset the EEPROM outside of the firmware's built in options (such as flashing a file that overwrites the `EEPROM`, like how the [QMK Toolbox]()'s "Reset EEPROM" button works), you'll need to re-flash the controller with the `EEPROM` files. 
 

docs/feature_tap_dance.md

@@ -30,7 +30,9 @@ Next, you will want to define some tap-dance keys, which is easiest to do with t
 After this, you'll want to use the `tap_dance_actions` array to specify what actions shall be taken when a tap-dance key is in action. Currently, there are five possible options:
 
 * `ACTION_TAP_DANCE_DOUBLE(kc1, kc2)`: Sends the `kc1` keycode when tapped once, `kc2` otherwise. When the key is held, the appropriate keycode is registered: `kc1` when pressed and held, `kc2` when tapped once, then pressed and held.
-* `ACTION_TAP_DANCE_DUAL_ROLE(kc, layer)`: Sends the `kc` keycode when tapped once, or moves to `layer`. (this functions like the `TO` layer keycode).
+* `ACTION_TAP_DANCE_LAYER_MOVE(kc, layer)`: Sends the `kc` keycode when tapped once, or moves to `layer`. (this functions like the `TO` layer keycode).
+    * This is the same as `ACTION_TAP_DANCE_DUAL_ROLE`, but renamed to something that is clearer about its functionality.  Both names will work.
+* `ACTION_TAP_DANCE_LAYER_TOGGLE(kc, layer)`: Sends the `kc` keycode when tapped once, or toggles the state of `layer`. (this functions like the `TG` layer keycode).
 * `ACTION_TAP_DANCE_FN(fn)`: Calls the specified function - defined in the user keymap - with the final tap count of the tap dance action.
 * `ACTION_TAP_DANCE_FN_ADVANCED(on_each_tap_fn, on_dance_finished_fn, on_dance_reset_fn)`: Calls the first specified function - defined in the user keymap - on every tap, the second function when the dance action finishes (like the previous option), and the last function when the tap dance action resets.
 * `ACTION_TAP_DANCE_FN_ADVANCED_TIME(on_each_tap_fn, on_dance_finished_fn, on_dance_reset_fn, tap_specific_tapping_term)`: This functions identically to the `ACTION_TAP_DANCE_FN_ADVANCED` function, but uses a custom tapping term for it, instead of the predefined `TAPPING_TERM`.

docs/flashing.md

@@ -10,11 +10,17 @@ Atmel's DFU bootloader comes on all atmega32u4 chips by default, and is used by
 
 To ensure compatibility with the DFU bootloader, make sure this block is present your `rules.mk` (optionally with `lufa-dfu` or `qmk-dfu` instead):
 
-    # Bootloader
-    #     This definition is optional, and if your keyboard supports multiple bootloaders of
-    #     different sizes, comment this out, and the correct address will be loaded
-    #     automatically (+60). See bootloader.mk for all options.
-    BOOTLOADER = atmel-dfu
+```make
+# Bootloader selection
+#   Teensy       halfkay
+#   Pro Micro    caterina
+#   Atmel DFU    atmel-dfu
+#   LUFA DFU     lufa-dfu
+#   QMK DFU      qmk-dfu
+#   ATmega32A    bootloadHID
+#   ATmega328P   USBasp
+BOOTLOADER = atmel-dfu
+```
 
 Compatible flashers:
 
@@ -64,11 +70,17 @@ Arduino boards and their clones use the [Caterina bootloader](https://github.com
 
 To ensure compatibility with the Caterina bootloader, make sure this block is present your `rules.mk`:
 
-    # Bootloader
-    #     This definition is optional, and if your keyboard supports multiple bootloaders of
-    #     different sizes, comment this out, and the correct address will be loaded
-    #     automatically (+60). See bootloader.mk for all options.
-    BOOTLOADER = caterina
+```make
+# Bootloader selection
+#   Teensy       halfkay
+#   Pro Micro    caterina
+#   Atmel DFU    atmel-dfu
+#   LUFA DFU     lufa-dfu
+#   QMK DFU      qmk-dfu
+#   ATmega32A    bootloadHID
+#   ATmega328P   USBasp
+BOOTLOADER = caterina
+```
 
 Compatible flashers:
 
@@ -100,11 +112,17 @@ Halfkay is a super-slim protocol developed by PJRC that uses HID, and come on al
 
 To ensure compatibility with the Halfkay bootloader, make sure this block is present your `rules.mk`:
 
-    # Bootloader
-    #     This definition is optional, and if your keyboard supports multiple bootloaders of
-    #     different sizes, comment this out, and the correct address will be loaded
-    #     automatically (+60). See bootloader.mk for all options.
-    BOOTLOADER = halfkay
+```make
+# Bootloader selection
+#   Teensy       halfkay
+#   Pro Micro    caterina
+#   Atmel DFU    atmel-dfu
+#   LUFA DFU     lufa-dfu
+#   QMK DFU      qmk-dfu
+#   ATmega32A    bootloadHID
+#   ATmega328P   USBasp
+BOOTLOADER = halfkay
+```
 
 Compatible flashers:
 
@@ -125,11 +143,17 @@ USBasploader is a bootloader developed by matrixstorm. It is used in some non-US
 
 To ensure compatibility with the USBasploader bootloader, make sure this block is present in your `rules.mk`:
 
-    # Bootloader
-    #     This definition is optional, and if your keyboard supports multiple bootloaders of
-    #     different sizes, comment this out, and the correct address will be loaded
-    #     automatically (+60). See bootloader.mk for all options.
-    BOOTLOADER = USBasp
+```make
+# Bootloader selection
+#   Teensy       halfkay
+#   Pro Micro    caterina
+#   Atmel DFU    atmel-dfu
+#   LUFA DFU     lufa-dfu
+#   QMK DFU      qmk-dfu
+#   ATmega32A    bootloadHID
+#   ATmega328P   USBasp
+BOOTLOADER = USBasp
+```
 
 Compatible flashers:
 
@@ -150,11 +174,17 @@ BootloadHID is a USB bootloader for AVR microcontrollers. The uploader tool requ
 
 To ensure compatibility with the bootloadHID bootloader, make sure this block is present your `rules.mk`:
 
-    # Bootloader
-    #     This definition is optional, and if your keyboard supports multiple bootloaders of
-    #     different sizes, comment this out, and the correct address will be loaded
-    #     automatically (+60). See bootloader.mk for all options.
-    BOOTLOADER = bootloadHID
+```make
+# Bootloader selection
+#   Teensy       halfkay
+#   Pro Micro    caterina
+#   Atmel DFU    atmel-dfu
+#   LUFA DFU     lufa-dfu
+#   QMK DFU      qmk-dfu
+#   ATmega32A    bootloadHID
+#   ATmega328P   USBasp
+BOOTLOADER = bootloadHID
+```
 
 Compatible flashers:
 
@@ -202,4 +232,6 @@ Flashing sequence:
 There are a number of DFU commands that you can use to flash firmware to a STM32 device:
 
 * `:dfu-util` - The default command for flashing to STM32 devices.
-* `:st-link-cli` - This allows you to flash the firmware via ST-LINK's CLI utility, rather than dfu-util.
+* `:dfu-util-split-left` - This flashes the normal firmware, just like the default option (`:dfu-util`). However, this also configures the "Left Side" EEPROM setting for split keyboards.
+* `:dfu-util-split-right` - This flashes the normal firmware, just like the default option (`:dfu-util`). However, this also configures the "Right Side" EEPROM setting for split keyboards.
+* `:st-link-cli` - This allows you to flash the firmware via ST-LINK's CLI utility, rather than dfu-util. 

docs/keycodes.md

@@ -257,35 +257,37 @@ This is a reference only. Each group of keys links to the page documenting their
 
 ## [Bootmagic](feature_bootmagic.md)
 
-|Key                               |Aliases  |Description                         |
-|----------------------------------|---------|------------------------------------|
-|`MAGIC_SWAP_CONTROL_CAPSLOCK`     |         |Swap Caps Lock and Left Control     |
-|`MAGIC_CAPSLOCK_TO_CONTROL`       |         |Treat Caps Lock as Control          |
-|`MAGIC_SWAP_LCTL_LGUI`            |         |Swap Left Control and GUI           |
-|`MAGIC_SWAP_RCTL_RGUI`            |         |Swap Right Control and GUI          |
-|`MAGIC_SWAP_LALT_LGUI`            |         |Swap Left Alt and GUI               |
-|`MAGIC_SWAP_RALT_RGUI`            |         |Swap Right Alt and GUI              |
-|`MAGIC_NO_GUI`                    |         |Disable the GUI key                 |
-|`MAGIC_SWAP_GRAVE_ESC`            |         |Swap <code>&#96;</code> and Escape  |
-|`MAGIC_SWAP_BACKSLASH_BACKSPACE`  |         |Swap `\` and Backspace              |
-|`MAGIC_HOST_NKRO`                 |         |Force NKRO on                       |
-|`MAGIC_SWAP_ALT_GUI`              |`AG_SWAP`|Swap Alt and GUI on both sides      |
+|Key                               |Aliases  |Description                                |
+|----------------------------------|---------|-------------------------------------------|
+|`MAGIC_SWAP_CONTROL_CAPSLOCK`     |         |Swap Caps Lock and Left Control            |
+|`MAGIC_CAPSLOCK_TO_CONTROL`       |         |Treat Caps Lock as Control                 |
+|`MAGIC_SWAP_LCTL_LGUI`            |         |Swap Left Control and GUI                  |
+|`MAGIC_SWAP_RCTL_RGUI`            |         |Swap Right Control and GUI                 |
+|`MAGIC_SWAP_LALT_LGUI`            |         |Swap Left Alt and GUI                      |
+|`MAGIC_SWAP_RALT_RGUI`            |         |Swap Right Alt and GUI                     |
+|`MAGIC_NO_GUI`                    |         |Disable the GUI key                        |
+|`MAGIC_SWAP_GRAVE_ESC`            |         |Swap <code>&#96;</code> and Escape         |
+|`MAGIC_SWAP_BACKSLASH_BACKSPACE`  |         |Swap `\` and Backspace                     |
+|`MAGIC_HOST_NKRO`                 |         |Force NKRO on                              |
+|`MAGIC_SWAP_ALT_GUI`              |`AG_SWAP`|Swap Alt and GUI on both sides             |
 |`MAGIC_SWAP_CTL_GUI`              |`CG_SWAP`|Swap Ctrl and GUI on both sides (for macOS)|
-|`MAGIC_UNSWAP_CONTROL_CAPSLOCK`   |         |Unswap Caps Lock and Left Control   |
-|`MAGIC_UNCAPSLOCK_TO_CONTROL`     |         |Stop treating Caps Lock as Control  |
-|`MAGIC_UNSWAP_LCTL_LGUI`          |         |Unswap Left Control and GUI         |
-|`MAGIC_UNSWAP_RCTL_RGUI`          |         |Unswap Right Control and GUI        |
-|`MAGIC_UNSWAP_LALT_LGUI`          |         |Unswap Left Alt and GUI             |
-|`MAGIC_UNSWAP_RALT_RGUI`          |         |Unswap Right Alt and GUI            |
-|`MAGIC_UNNO_GUI`                  |         |Enable the GUI key                  |
-|`MAGIC_UNSWAP_GRAVE_ESC`          |         |Unswap <code>&#96;</code> and Escape|
-|`MAGIC_UNSWAP_BACKSLASH_BACKSPACE`|         |Unswap `\` and Backspace            |
-|`MAGIC_UNHOST_NKRO`               |         |Force NKRO off                      |
-|`MAGIC_UNSWAP_ALT_GUI`            |`AG_NORM`|Unswap Alt and GUI on both sides    |
-|`MAGIC_UNSWAP_CTL_GUI`            |`CG_NORM`|Unswap Ctrl and GUI on both sides      |
-|`MAGIC_TOGGLE_ALT_GUI`            |`AG_TOGG`|Toggle Alt and GUI swap on both sides  |
-|`MAGIC_TOGGLE_CTL_GUI`            |`CG_TOGG`|Toggle Ctrl and GUI swap on both sides |
-|`MAGIC_TOGGLE_NKRO`               |         |Turn NKRO on or off                    |
+|`MAGIC_UNSWAP_CONTROL_CAPSLOCK`   |         |Unswap Caps Lock and Left Control          |
+|`MAGIC_UNCAPSLOCK_TO_CONTROL`     |         |Stop treating Caps Lock as Control         |
+|`MAGIC_UNSWAP_LCTL_LGUI`          |         |Unswap Left Control and GUI                |
+|`MAGIC_UNSWAP_RCTL_RGUI`          |         |Unswap Right Control and GUI               |
+|`MAGIC_UNSWAP_LALT_LGUI`          |         |Unswap Left Alt and GUI                    |
+|`MAGIC_UNSWAP_RALT_RGUI`          |         |Unswap Right Alt and GUI                   |
+|`MAGIC_UNNO_GUI`                  |         |Enable the GUI key                         |
+|`MAGIC_UNSWAP_GRAVE_ESC`          |         |Unswap <code>&#96;</code> and Escape       |
+|`MAGIC_UNSWAP_BACKSLASH_BACKSPACE`|         |Unswap `\` and Backspace                   |
+|`MAGIC_UNHOST_NKRO`               |         |Force NKRO off                             |
+|`MAGIC_UNSWAP_ALT_GUI`            |`AG_NORM`|Unswap Alt and GUI on both sides           |
+|`MAGIC_UNSWAP_CTL_GUI`            |`CG_NORM`|Unswap Ctrl and GUI on both sides          |
+|`MAGIC_TOGGLE_ALT_GUI`            |`AG_TOGG`|Toggle Alt and GUI swap on both sides      |
+|`MAGIC_TOGGLE_CTL_GUI`            |`CG_TOGG`|Toggle Ctrl and GUI swap on both sides     |
+|`MAGIC_TOGGLE_NKRO`               |         |Turn NKRO on or off                        |
+|`MAGIC_EE_HANDS_LEFT`             |         |Set "Left Hand" for EE_HANDS handedness    |
+|`MAGIC_EE_HANDS_RIGHT`            |         |Set "Right Hand" for EE_HANDS handedness   |
 
 ## [Bluetooth](feature_bluetooth.md)
 

docs/newbs_flashing.md

@@ -215,7 +215,7 @@ Additionally, if you want to flash multiple boards, use the following command:
 When you're done flashing boards, you'll need to hit Ctrl + C or whatever the correct keystroke is for your operating system to break the loop.
 
 
-## HalfKay
+### HalfKay
 
 For the PJRC devices (Teensy's), when you're ready to compile and flash your firmware, open up your terminal window and run the build command: 
 
@@ -248,7 +248,7 @@ Programming.....................................................................
 Booting
 ```
 
-## BootloadHID
+### BootloadHID
 
 For Bootmapper Client(BMC)/bootloadHID/ATmega32A based boards, when you're ready to compile and flash your firmware, open up your terminal window and run the build command: 
 
@@ -284,7 +284,7 @@ Uploading 22016 (0x5600) bytes starting at 0 (0x0)
 0x05580 ... 0x05600
 ```
 
-## STM32 (ARM)
+### STM32 (ARM)
 
 For a majority of ARM boards (including the Proton C, Planck Rev 6, and Preonic Rev 3), when you're ready to compile and flash your firmware, open up your terminal window and run the build command: 
 
@@ -334,6 +334,16 @@ File downloaded successfully
 Transitioning to dfuMANIFEST state
 ```
 
+#### STM32 Commands
+
+There are a number of DFU commands that you can use to flash firmware to a STM32 device:
+
+* `:dfu-util` - The default command for flashing to STM32 devices. 
+* `:dfu-util-wait` - This works like the default command, but it gives you a (configurable) 10 second timeout before it attempts to flash the firmware.  You can use `TIME_DELAY=20` from the command line to change the timeout.
+   * Eg: `make <keyboard>:<keymap>:dfu-util TIME_DELAY=5`
+* `:dfu-util-split-left` - This flashes the normal firmware, just like the default option (`:dfu-util`). However, this also configures the "Left Side" EEPROM setting for split keyboards.
+* `:dfu-util-split-right` - This flashes the normal firmware, just like the default option (`:dfu-util`). However, this also configures the "Right Side" EEPROM setting for split keyboards.
+
 ## Test It Out!
 
 Congrats! Your custom firmware has been programmed to your keyboard!

docs/python_development.md

@@ -1,45 +0,0 @@
-# Python Development in QMK
-
-This document gives an overview of how QMK has structured its python code. You should read this before working on any of the python code.
-
-## Script directories
-
-There are two places scripts live in QMK: `qmk_firmware/bin` and `qmk_firmware/util`. You should use `bin` for any python scripts that utilize the `qmk` wrapper. Scripts that are standalone and not run very often live in `util`.
-
-We discourage putting anything into `bin` that does not utilize the `qmk` wrapper. If you think you have a good reason for doing so please talk to us about your use case.
-
-## Python Modules
-
-Most of the QMK python modules can be found in `qmk_firmware/lib/python`. This is the path that we append to `sys.path`.
-
-We have a module hierarchy under that path:
-
-* `qmk_firmware/lib/python`
-    * `milc.py` - The CLI library we use. Will be pulled out into its own module in the future.
-    * `qmk` - Code associated with QMK
-        * `cli` - Modules that will be imported for CLI commands.
-        * `errors.py` - Errors that can be raised within QMK apps
-        * `keymap.py` - Functions for working with keymaps
-
-## CLI Scripts
-
-We have a CLI wrapper that you should utilize for any user facing scripts. We think it's pretty easy to use and it gives you a lot of nice things for free.
-
-To use the wrapper simply place a module into `qmk_firmware/lib/python/qmk/cli`, and create a symlink to `bin/qmk` named after your module. Dashes in command names will be converted into dots so you can use hierarchy to manage commands.
-
-When `qmk` is run it checks to see how it was invoked. If it was invoked as `qmk` the module name is take from `sys.argv[1]`. If it was invoked as `qmk-<module-name>` then everything after the first dash is taken as the module name. Dashes and underscores are converted to dots, and then `qmk.cli` is prepended before the module is imported.
-
-The module uses `@cli.entrypoint()` and `@cli.argument()` decorators to define an entrypoint, which is where execution starts.
-
-## Example CLI Script
-
-We have provided a QMK Hello World script you can use as an example. To run it simply run `qmk hello` or `qmk-hello`. The source code is listed below.
-
-```
-from milc import cli
-
-@cli.argument('-n', '--name', default='World', help='Name to greet.')
-@cli.entrypoint('QMK Python Hello World.')
-def main(cli):
-    cli.echo('Hello, %s!', cli.config.general.name)
-```

docs/redirects.json

@@ -43,6 +43,10 @@
             {
                 "from": "unicode.html",
                 "to": "feature_unicode.html"
+            },
+            {
+                "from": "python_development.html",
+                "to": "cli_development.html"
             }
         ]
 }

drivers/arm/i2c_master.c

@@ -32,6 +32,17 @@
 
 static uint8_t i2c_address;
 
+// ChibiOS uses two initialization structure for v1 and v2/v3 i2c APIs.
+// The F1 series uses the v1 api, which have to initialized this way.
+#ifdef STM32F103xB
+static const I2CConfig i2cconfig = {
+  OPMODE_I2C,
+  400000,
+  FAST_DUTY_CYCLE_2,
+};
+#else
+// This configures the I2C clock to 400khz assuming a 72Mhz clock
+// For more info : https://www.st.com/en/embedded-software/stsw-stm32126.html
 static const I2CConfig i2cconfig = {
 #ifdef USE_I2CV1
     I2C1_OPMODE,
@@ -41,6 +52,7 @@ static const I2CConfig i2cconfig = {
     STM32_TIMINGR_PRESC(I2C1_TIMINGR_PRESC) | STM32_TIMINGR_SCLDEL(I2C1_TIMINGR_SCLDEL) | STM32_TIMINGR_SDADEL(I2C1_TIMINGR_SDADEL) | STM32_TIMINGR_SCLH(I2C1_TIMINGR_SCLH) | STM32_TIMINGR_SCLL(I2C1_TIMINGR_SCLL), 0, 0
 #endif
 };
+#endif
 
 static i2c_status_t chibios_to_qmk(const msg_t* status) {
     switch (*status) {
@@ -60,7 +72,6 @@ __attribute__((weak)) void i2c_init(void) {
     palSetPadMode(I2C1_SDA_BANK, I2C1_SDA, PAL_MODE_INPUT);
 
     chThdSleepMilliseconds(10);
-
 #ifdef USE_I2CV1
     palSetPadMode(I2C1_SCL_BANK, I2C1_SCL, PAL_MODE_STM32_ALTERNATE_OPENDRAIN);
     palSetPadMode(I2C1_SDA_BANK, I2C1_SDA, PAL_MODE_STM32_ALTERNATE_OPENDRAIN);
@@ -68,8 +79,6 @@ __attribute__((weak)) void i2c_init(void) {
     palSetPadMode(I2C1_SCL_BANK, I2C1_SCL, PAL_MODE_ALTERNATE(I2C1_SCL_PAL_MODE) | PAL_STM32_OTYPE_OPENDRAIN);
     palSetPadMode(I2C1_SDA_BANK, I2C1_SDA, PAL_MODE_ALTERNATE(I2C1_SDA_PAL_MODE) | PAL_STM32_OTYPE_OPENDRAIN);
 #endif
-
-    // i2cInit(); //This is invoked by halInit() so no need to redo it.
 }
 
 i2c_status_t i2c_start(uint8_t address) {

keyboards/1upkeyboards/1up60hse/rules.mk

@@ -1,51 +1,15 @@
 # MCU name
 MCU = atmega32u4
 
-# Processor frequency.
-#     This will define a symbol, F_CPU, in all source code files equal to the
-#     processor frequency in Hz. You can then use this symbol in your source code to
-#     calculate timings. Do NOT tack on a 'UL' at the end, this will be done
-#     automatically to create a 32-bit value in your source code.
-#
-#     This will be an integer division of F_USB below, as it is sourced by
-#     F_USB after it has run through any CPU prescalers. Note that this value
-#     does not *change* the processor frequency - it should merely be updated to
-#     reflect the processor speed set externally so that the code can use accurate
-#     software delays.
-F_CPU = 16000000
-
-
-#
-# LUFA specific
-#
-# Target architecture (see library "Board Types" documentation).
-ARCH = AVR8
-
-# Input clock frequency.
-#     This will define a symbol, F_USB, in all source code files equal to the
-#     input clock frequency (before any prescaling is performed) in Hz. This value may
-#     differ from F_CPU if prescaling is used on the latter, and is required as the
-#     raw input clock is fed directly to the PLL sections of the AVR for high speed
-#     clock generation for the USB and other AVR subsections. Do NOT tack on a 'UL'
-#     at the end, this will be done automatically to create a 32-bit value in your
-#     source code.
-#
-#     If no clock division is performed on the input clock inside the AVR (via the
-#     CPU clock adjust registers or the clock division fuses), this will be equal to F_CPU.
-F_USB = $(F_CPU)
-
-# Interrupt driven control endpoint task(+60)
-OPT_DEFS += -DINTERRUPT_CONTROL_ENDPOINT
-
-
-# Boot Section Size in *bytes*
-#   Teensy halfKay   512
-#   Teensy++ halfKay 1024
-#   Atmel DFU loader 4096
-#   LUFA bootloader  4096
-#   USBaspLoader     2048
-OPT_DEFS += -DBOOTLOADER_SIZE=4096
-
+# Bootloader selection
+#   Teensy       halfkay
+#   Pro Micro    caterina
+#   Atmel DFU    atmel-dfu
+#   LUFA DFU     lufa-dfu
+#   QMK DFU      qmk-dfu
+#   ATmega32A    bootloadHID
+#   ATmega328P   USBasp
+BOOTLOADER = atmel-dfu
 
 # Build Options
 #   change yes to no to disable

keyboards/1upkeyboards/1up60hte/rules.mk

@@ -1,6 +1,14 @@
 # MCU name
 MCU = atmega32u4
 
+# Bootloader selection
+#   Teensy       halfkay
+#   Pro Micro    caterina
+#   Atmel DFU    atmel-dfu
+#   LUFA DFU     lufa-dfu
+#   QMK DFU      qmk-dfu
+#   ATmega32A    bootloadHID
+#   ATmega328P   USBasp
 BOOTLOADER = atmel-dfu
 
 # Build Options

keyboards/1upkeyboards/1up60rgb/rules.mk

@@ -1,45 +1,15 @@
 # MCU name
 MCU = atmega32u4
 
-# Processor frequency.
-#     This will define a symbol, F_CPU, in all source code files equal to the
-#     processor frequency in Hz. You can then use this symbol in your source code to
-#     calculate timings. Do NOT tack on a 'UL' at the end, this will be done
-#     automatically to create a 32-bit value in your source code.
-#
-#     This will be an integer division of F_USB below, as it is sourced by
-#     F_USB after it has run through any CPU prescalers. Note that this value
-#     does not *change* the processor frequency - it should merely be updated to
-#     reflect the processor speed set externally so that the code can use accurate
-#     software delays.
-F_CPU = 16000000
-
-#
-# LUFA specific
-#
-# Target architecture (see library "Board Types" documentation).
-ARCH = AVR8
-
-# Input clock frequency.
-#     This will define a symbol, F_USB, in all source code files equal to the
-#     input clock frequency (before any prescaling is performed) in Hz. This value may
-#     differ from F_CPU if prescaling is used on the latter, and is required as the
-#     raw input clock is fed directly to the PLL sections of the AVR for high speed
-#     clock generation for the USB and other AVR subsections. Do NOT tack on a 'UL'
-#     at the end, this will be done automatically to create a 32-bit value in your
-#     source code.
-#
-#     If no clock division is performed on the input clock inside the AVR (via the
-#     CPU clock adjust registers or the clock division fuses), this will be equal to F_CPU.
-F_USB = $(F_CPU)
-
-# Interrupt driven control endpoint task(+60)
-OPT_DEFS += -DINTERRUPT_CONTROL_ENDPOINT
-
-
-# Boot Section Size in *bytes*
-OPT_DEFS += -DBOOTLOADER_SIZE=4096
-
+# Bootloader selection
+#   Teensy       halfkay
+#   Pro Micro    caterina
+#   Atmel DFU    atmel-dfu
+#   LUFA DFU     lufa-dfu
+#   QMK DFU      qmk-dfu
+#   ATmega32A    bootloadHID
+#   ATmega328P   USBasp
+BOOTLOADER = atmel-dfu
 
 # Build Options
 #   comment out to disable the options.

keyboards/1upkeyboards/super16/rules.mk

@@ -1,62 +1,16 @@
 # MCU name
 MCU = atmega32u4
 
-# Processor frequency.
-#     This will define a symbol, F_CPU, in all source code files equal to the
-#     processor frequency in Hz. You can then use this symbol in your source code to
-#     calculate timings. Do NOT tack on a 'UL' at the end, this will be done
-#     automatically to create a 32-bit value in your source code.
-#
-#     This will be an integer division of F_USB below, as it is sourced by
-#     F_USB after it has run through any CPU prescalers. Note that this value
-#     does not *change* the processor frequency - it should merely be updated to
-#     reflect the processor speed set externally so that the code can use accurate
-#     software delays.
-F_CPU = 16000000
-
-#
-# LUFA specific
-#
-# Target architecture (see library "Board Types" documentation).
-ARCH = AVR8
-
-# Input clock frequency.
-#     This will define a symbol, F_USB, in all source code files equal to the
-#     input clock frequency (before any prescaling is performed) in Hz. This value may
-#     differ from F_CPU if prescaling is used on the latter, and is required as the
-#     raw input clock is fed directly to the PLL sections of the AVR for high speed
-#     clock generation for the USB and other AVR subsections. Do NOT tack on a 'UL'
-#     at the end, this will be done automatically to create a 32-bit value in your
-#     source code.
-#
-#     If no clock division is performed on the input clock inside the AVR (via the
-#     CPU clock adjust registers or the clock division fuses), this will be equal to F_CPU.
-F_USB = $(F_CPU)
-
-# Interrupt driven control endpoint task(+60)
-OPT_DEFS += -DINTERRUPT_CONTROL_ENDPOINT
-
-
 # Bootloader selection
 #   Teensy       halfkay
 #   Pro Micro    caterina
 #   Atmel DFU    atmel-dfu
 #   LUFA DFU     lufa-dfu
 #   QMK DFU      qmk-dfu
-#   atmega32a    bootloadHID
+#   ATmega32A    bootloadHID
+#   ATmega328P   USBasp
 BOOTLOADER = caterina
 
-# If you don't know the bootloader type, then you can specify the
-# Boot Section Size in *bytes* by uncommenting out the OPT_DEFS line
-#   Teensy halfKay      512
-#   Teensy++ halfKay    1024
-#   Atmel DFU loader    4096
-#   LUFA bootloader     4096
-#   USBaspLoader        2048
-# OPT_DEFS += -DBOOTLOADER_SIZE=4096
-
-#EXTRAFLAGS += -flto
-
 # Build Options
 #   change yes to no to disable
 #