Fix build. (#9163)

* Update ARM split keyboard docs

* Update docs/serial_driver.md

Co-authored-by: Nick Brassel <nick@tzarc.org>

Co-authored-by: Nick Brassel <nick@tzarc.org>

Makefile

@@ -29,6 +29,9 @@ $(info QMK Firmware $(QMK_VERSION))
 endif
 endif
 
+# avoid 'Entering|Leaving directory' messages
+MAKEFLAGS += --no-print-directory
+
 ON_ERROR := error_occurred=1
 
 BREAK_ON_ERRORS = no
@@ -292,7 +295,7 @@ define PARSE_RULE
         $$(info |     make project_folder:keymap[:target])
         $$(info |  Examples:)
         $$(info |     make planck/rev4:default:dfu)
-        $$(info |     make planck:default)
+        $$(info |     make planck/rev4:default)
         $$(info |)
     endif
 endef

Vagrantfile

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

common_features.mk

@@ -70,7 +70,7 @@ ifeq ($(strip $(POINTING_DEVICE_ENABLE)), yes)
     SRC += $(QUANTUM_DIR)/pointing_device.c
 endif
 
-VALID_EEPROM_DRIVER_TYPES := vendor custom transient i2c
+VALID_EEPROM_DRIVER_TYPES := vendor custom transient i2c spi
 EEPROM_DRIVER ?= vendor
 ifeq ($(filter $(EEPROM_DRIVER),$(VALID_EEPROM_DRIVER_TYPES)),)
   $(error EEPROM_DRIVER="$(EEPROM_DRIVER)" is not a valid EEPROM driver)
@@ -85,6 +85,11 @@ else
     COMMON_VPATH += $(DRIVER_PATH)/eeprom
     QUANTUM_LIB_SRC += i2c_master.c
     SRC += eeprom_driver.c eeprom_i2c.c
+  else ifeq ($(strip $(EEPROM_DRIVER)), spi)
+    OPT_DEFS += -DEEPROM_DRIVER -DEEPROM_SPI
+    COMMON_VPATH += $(DRIVER_PATH)/eeprom
+    QUANTUM_LIB_SRC += spi_master.c
+    SRC += eeprom_driver.c eeprom_spi.c
   else ifeq ($(strip $(EEPROM_DRIVER)), transient)
     OPT_DEFS += -DEEPROM_DRIVER -DEEPROM_TRANSIENT
     COMMON_VPATH += $(DRIVER_PATH)/eeprom

docs/_summary.md

@@ -34,7 +34,9 @@
     * [Customizing Functionality](custom_quantum_functions.md)
     * [Driver Installation with Zadig](driver_installation_zadig.md)
     * [Keymap Overview](keymap.md)
-    * [Vagrant Guide](getting_started_vagrant.md)
+    * Development Environments
+      * [Docker Guide](getting_started_docker.md)
+      * [Vagrant Guide](getting_started_vagrant.md)
     * Flashing
       * [Flashing](flashing.md)
       * [Flashing ATmega32A (ps2avrgb)](flashing_bootloadhid.md)
@@ -126,6 +128,7 @@
       * [SPI Driver](spi_driver.md)
       * [WS2812 Driver](ws2812_driver.md)
       * [EEPROM Driver](eeprom_driver.md)
+      * ['serial' Driver](serial_driver.md)
     * [GPIO Controls](internals_gpio_control.md)
     * [Keyboard Guidelines](hardware_keyboard_guidelines.md)
 

docs/cli.md

@@ -13,18 +13,17 @@ QMK requires Python 3.6 or greater. We try to keep the number of requirements sm
 If you have installed [Homebrew](https://brew.sh) you can tap and install QMK:
 
 ```
-brew tap qmk/qmk
-brew install qmk
+brew install qmk/qmk/qmk
 export QMK_HOME='~/qmk_firmware' # Optional, set the location for `qmk_firmware`
 qmk setup  # This will clone `qmk/qmk_firmware` and optionally set up your build environment
 ```
 
-### Install Using easy_install or pip :id=install-using-easy_install-or-pip
+### Install Using pip :id=install-using-easy_install-or-pip
 
-If your system is not listed above you can install QMK manually. First ensure that you have python 3.6 (or later) installed and have installed pip. Then install QMK with this command:
+If your system is not listed above you can install QMK manually. First ensure that you have Python 3.6 (or later) installed and have installed pip. Then install QMK with this command:
 
 ```
-pip3 install qmk
+python3 -m pip install qmk
 export QMK_HOME='~/qmk_firmware' # Optional, set the location for `qmk_firmware`
 qmk setup  # This will clone `qmk/qmk_firmware` and optionally set up your build environment
 ```

docs/config_options.md

@@ -191,7 +191,12 @@ If you define these options you will enable the associated feature, which may in
 * `#define RGBLIGHT_ANIMATIONS`
   * run RGB animations
 * `#define RGBLIGHT_LAYERS`
-  * Lets you define [lighting layers](feature_rgblight.md) that can be toggled on or off. Great for showing the current keyboard layer or caps lock state.
+  * Lets you define [lighting layers](feature_rgblight.md?id=lighting-layers) that can be toggled on or off. Great for showing the current keyboard layer or caps lock state.
+* `#define RGBLIGHT_MAX_LAYERS`
+  * Defaults to 8. Can be expanded up to 32 if more [lighting layers](feature_rgblight.md?id=lighting-layers) are needed.
+  * Note: Increasing the maximum will increase the firmware size and slow sync on split keyboards.
+* `#define RGBLIGHT_LAYER_BLINK` 
+  * Adds ability to [blink](feature_rgblight.md?id=lighting-layer-blink) a lighting layer for a specified number of milliseconds (e.g. to acknowledge an action).
 * `#define RGBLED_NUM 12`
   * number of LEDs
 * `#define RGBLIGHT_SPLIT`

docs/eeprom_driver.md

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

docs/faq_build.md

@@ -113,26 +113,16 @@ OPT_DEFS += -DBOOTLOADER_SIZE=2048
 ```
 
 ## `avr-gcc: internal compiler error: Abort trap: 6 (program cc1)` on MacOS
+
 This is an issue with updating on brew, causing symlinks that avr-gcc depend on getting mangled.
 
 The solution is to remove and reinstall all affected modules.
 
 ```
-brew rm avr-gcc
-brew rm avr-gcc@8
-brew rm dfu-programmer
-brew rm dfu-util
-brew rm gcc-arm-none-eabi
-brew rm arm-gcc-bin@8
-brew rm avrdude
-brew install avr-gcc@8
-brew install dfu-programmer
-brew install dfu-util
-brew install arm-gcc-bin@8
-brew install avrdude
+brew rm avr-gcc avr-gcc@8 dfu-programmer dfu-util gcc-arm-none-eabi arm-gcc-bin@8 avrdude qmk
+brew install qmk/qmk/qmk
 brew link --force avr-gcc@8
 brew link --force arm-gcc-bin@8
-
 ```
 
 ### `avr-gcc` and LUFA

docs/feature_hd44780.md

@@ -1,6 +1,6 @@
 # HD44780 LCD Displays
 
-This is an integration of Peter Fleury's LCD library. This page will explain the basics. [For in depth documentation visit his page.](http://homepage.hispeed.ch/peterfleury/doxygen/avr-gcc-libraries/group__pfleury__lcd.html)
+This is an integration of Peter Fleury's LCD library. This page will explain the basics. [For in depth documentation visit his page.](http://www.peterfleury.epizy.com/doxygen/avr-gcc-libraries/group__pfleury__lcd.html)
 
 You can enable support for HD44780 Displays by setting the `HD44780_ENABLE` flag in your keyboards `rules.mk` to yes.
 
@@ -50,8 +50,8 @@ LCD_DISP_ON_CURSOR_BLINK : display on, cursor on flashing
 ````
 This is best done in your keyboards `matrix_init_kb` or your keymaps `matrix_init_user`.  
 It is advised to clear the display before use.  
-To do so call `lcd_clrsrc()`.
+To do so call `lcd_clrscr()`.
 
 To now print something to your Display you first call `lcd_gotoxy(column, line)`. To go to the start of the first line you would call `lcd_gotoxy(0, 0)` and then print a string with `lcd_puts("example string")`.
 
-There are more methods available to control the display. [For in depth documentation please visit the linked page.](http://homepage.hispeed.ch/peterfleury/doxygen/avr-gcc-libraries/group__pfleury__lcd.html)
+There are more methods available to control the display. [For in depth documentation please visit the linked page.](http://www.peterfleury.epizy.com/doxygen/avr-gcc-libraries/group__pfleury__lcd.html)

docs/feature_rawhid.md

@@ -44,7 +44,11 @@ To connect your host computer to your keyboard with raw HID you need four pieces
 3. Usage Page
 4. Usage
 
-The first two can easily be found in your keyboard's `config.h` in the keyboard's main directory under `VENDOR_ID` and `PRODUCT_ID`. **Usage Page** is **`0xFF60`** and **Usage** is **`0x0061`**.
+The first two can easily be found in your keyboard's `config.h` in the keyboard's main directory under `VENDOR_ID` and `PRODUCT_ID`.
+
+The final two can be overridden in your keyboard's `config.h` in the keyboard's main directory by redefining the values: `#define RAW_USAGE_PAGE 0xFF60` and `#define RAW_USAGE_ID 0x61`.
+
+By default, **Usage Page** is `0xFF60` and **Usage** is `0x61`.
 
 ### Building your host
 

docs/feature_rgb_matrix.md

@@ -437,12 +437,16 @@ Where `28` is an unused index from `eeconfig.h`.
 |`rgb_matrix_sethsv_noeeprom(h, s, v)`       |Set LEDs to the given HSV value where `h`/`s`/`v` are between 0 and 255 (not written to EEPROM) |
 
 ### Query Current Status :id=query-current-status
-|Function               |Description      |
-|-----------------------|-----------------|
-|`rgb_matrix_get_mode()`  |Get current mode |
-|`rgb_matrix_get_hue()`   |Get current hue  |
-|`rgb_matrix_get_sat()`   |Get current sat  |
-|`rgb_matrix_get_val()`   |Get current val  |
+|Function                         |Description                |
+|---------------------------------|---------------------------|
+|`rgb_matrix_is_enabled()`        |Gets current on/off status |
+|`rgb_matrix_get_mode()`          |Gets current mode          |
+|`rgb_matrix_get_hue()`           |Gets current hue           |
+|`rgb_matrix_get_sat()`           |Gets current sat           |
+|`rgb_matrix_get_val()`           |Gets current val           |
+|`rgb_matrix_get_hsv()`           |Gets hue, sat, and val and returns a [`HSV` structure](https://github.com/qmk/qmk_firmware/blob/7ba6456c0b2e041bb9f97dbed265c5b8b4b12192/quantum/color.h#L56-L61)|
+|`rgb_matrix_get_speed()`         |Gets current speed         |
+|`rgb_matrix_get_suspend_state()` |Gets current suspend state |
 
 ## Callbacks :id=callbacks
 

docs/feature_rgblight.md

@@ -94,6 +94,7 @@ if `RGBLIGHT_EFFECT_xxxx` or `RGBLIGHT_ANIMATIONS` is defined, you also have a n
 |`RGBLIGHT_MODE_STATIC_GRADIENT`| 0,1,..,9        |Static gradient                        |
 |`RGBLIGHT_MODE_RGB_TEST`     | *None*            |RGB Test                               |
 |`RGBLIGHT_MODE_ALTERNATING`  | *None*            |Alternating                            |
+|`RGBLIGHT_MODE_TWINKLE`      | 0,1,2,3,4,5       |Twinkle                                |
 
 Check out [this video](https://youtube.com/watch?v=VKrpPAHlisY) for a demonstration.
 
@@ -103,8 +104,8 @@ Note: For versions older than 0.6.117, The mode numbers were written directly. I
 
 Use these defines to add or remove animations from the firmware. When you are running low on flash space, it can be helpful to disable animations you are not using.
 
-|Define                              |Default      |Description                                                                          |
-|------------------------------------|-------------|-------------------------------------------------------------------------------------|
+|Define                              |Default      |Description                                                              |
+|------------------------------------|-------------|-------------------------------------------------------------------------|
 |`RGBLIGHT_ANIMATIONS`               |*Not defined*|Enable all additional animation modes.                                   |
 |`RGBLIGHT_EFFECT_ALTERNATING`       |*Not defined*|Enable alternating animation mode.                                       |
 |`RGBLIGHT_EFFECT_BREATHING`         |*Not defined*|Enable breathing animation mode.                                         |
@@ -115,6 +116,7 @@ Use these defines to add or remove animations from the firmware. When you are ru
 |`RGBLIGHT_EFFECT_RGB_TEST`          |*Not defined*|Enable RGB test animation mode.                                          |
 |`RGBLIGHT_EFFECT_SNAKE`             |*Not defined*|Enable snake animation mode.                                             |
 |`RGBLIGHT_EFFECT_STATIC_GRADIENT`   |*Not defined*|Enable static gradient mode.                                             |
+|`RGBLIGHT_EFFECT_TWINKLE`           |*Not defined*|Enable twinkle animation mode.                                           |
 
 ### Effect and Animation Settings
 
@@ -131,6 +133,8 @@ The following options are used to tweak the various animations:
 |`RGBLIGHT_EFFECT_KNIGHT_OFFSET`     |`0`          |The number of LEDs to start the "Knight" animation from the start of the strip by    |
 |`RGBLIGHT_RAINBOW_SWIRL_RANGE`      |`255`        |Range adjustment for the rainbow swirl effect to get different swirls                |
 |`RGBLIGHT_EFFECT_SNAKE_LENGTH`      |`4`          |The number of LEDs to light up for the "Snake" animation                             |
+|`RGBLIGHT_EFFECT_TWINKLE_LIFE`      |`75`         |Adjusts how quickly each LED brightens and dims when twinkling (in animation steps)  |
+|`RGBLIGHT_EFFECT_TWINKLE_PROBABILITY`|`1/127`     |Adjusts how likely each LED is to twinkle (on each animation step)                   |
 
 ### Example Usage to Reduce Memory Footprint
   1. Remove `RGBLIGHT_ANIMATIONS` from `config.h`.
@@ -168,6 +172,9 @@ const uint8_t RGBLED_SNAKE_INTERVALS[] PROGMEM = {100, 50, 20};
 // How long (in milliseconds) to wait between animation steps for each of the "Knight" animations
 const uint8_t RGBLED_KNIGHT_INTERVALS[] PROGMEM = {127, 63, 31};
 
+// How long (in milliseconds) to wait between animation steps for each of the "Twinkle" animations
+const uint8_t RGBLED_TWINKLE_INTERVALS[] PROGMEM = {50, 25, 10};
+
 // These control which hues are selected for each of the "Static gradient" modes
 const uint8_t RGBLED_GRADIENT_RANGES[] PROGMEM = {255, 170, 127, 85, 64};
 ```
@@ -177,6 +184,10 @@ const uint8_t RGBLED_GRADIENT_RANGES[] PROGMEM = {255, 170, 127, 85, 64};
 By including `#define RGBLIGHT_LAYERS` in your `config.h` file you can enable lighting layers. These make
 it easy to use your underglow LEDs as status indicators to show which keyboard layer is currently active, or the state of caps lock, all without disrupting any animations. [Here's a video](https://youtu.be/uLGE1epbmdY) showing an example of what you can do.
 
+### Defining Lighting Layers :id=defining-lighting-layers
+
+By default, 8 layers are possible. This can be expanded to as many as 32 by overriding the definition of `RGBLIGHT_MAX_LAYERS` in `config.h` (e.g. `#define RGBLIGHT_MAX_LAYERS 32`). Please note, if you use a split keyboard, you will need to flash both sides of the split after changing this. Also, increasing the maximum will increase the firmware size, and will slow sync on split keyboards.
+
 To define a layer, we modify `keymap.c` to list out LED ranges and the colors we want to overlay on them using an array of `rgblight_segment_t` using the `RGBLIGHT_LAYER_SEGMENTS` macro. We can define multiple layers and enable/disable them independently:
 
 ```c
@@ -211,8 +222,12 @@ void keyboard_post_init_user(void) {
     rgblight_layers = my_rgb_layers;
 }
 ```
+Note: For split keyboards with two controllers, both sides need to be flashed when updating the contents of rgblight_layers.
 
-Finally, we enable and disable the lighting layers whenever the state of the keyboard changes:
+### Enabling and disabling lighting layers :id=enabling-lighting-layers
+
+Everything above just configured the definition of each lighting layer.
+We can now enable and disable the lighting layers whenever the state of the keyboard changes:
 
 ```c
 layer_state_t layer_state_set_user(layer_state_t state) {
@@ -228,7 +243,40 @@ bool led_update_user(led_t led_state) {
 }
 ```
 
-Note: For split keyboards with two controllers, both sides need to be flashed when updating the contents of rgblight_layers.
+### Lighting layer blink :id=lighting-layer-blink
+
+By including `#define RGBLIGHT_LAYER_BLINK` in your `config.h` file you can turn a lighting
+layer on for a specified duration. Once the specified number of milliseconds has elapsed
+the layer will be turned off. This is useful, e.g., if you want to acknowledge some
+action (e.g. toggling some setting):
+
+```c
+const rgblight_segment_t PROGMEM _yes_layer[] = RGBLIGHT_LAYER_SEGMENTS( {9, 6, HSV_GREEN} );
+const rgblight_segment_t PROGMEM _no_layer[] = RGBLIGHT_LAYER_SEGMENTS( {9, 6, HSV_RED} );
+
+const rgblight_segment_t* const PROGMEM _rgb_layers[] =
+    RGBLIGHT_LAYERS_LIST( _yes_layer, _no_layer );
+
+void keyboard_post_init_user(void) {
+    rgblight_layers = _rgb_layers;
+}
+
+// Note we user post_process_record_user because we want the state
+// after the flag has been flipped...
+void post_process_record_user(uint16_t keycode, keyrecord_t *record) {
+    switch (keycode) {
+        case DEBUG:
+            rgblight_blink_layer(debug_enable ? 0 : 1, 500);
+            break;
+
+        case NK_TOGG:
+        case NK_ON:
+        case NK_OFF:
+            rgblight_blink_layer(keymap_config.nkro ? 0 : 1, 500);
+            break;
+    }
+}
+```
 
 ## Functions
 
@@ -328,12 +376,14 @@ rgblight_sethsv(HSV_GREEN, 2); // led 2
 |`rgblight_set_layer_state(i, is_on)`        |Enable or disable lighting layer `i` based on value of `bool is_on` |
 
 #### query
-|Function               |Description      |
-|-----------------------|-----------------|
-|`rgblight_get_mode()`  |Get current mode |
-|`rgblight_get_hue()`   |Get current hue  |
-|`rgblight_get_sat()`   |Get current sat  |
-|`rgblight_get_val()`   |Get current val  |
+|Function               |Description                |
+|-----------------------|---------------------------|
+|`rgblight_is_enabled()`|Gets current on/off status |
+|`rgblight_get_mode()`  |Gets current mode          |
+|`rgblight_get_hue()`   |Gets current hue           |
+|`rgblight_get_sat()`   |Gets current sat           |
+|`rgblight_get_val()`   |Gets current val           |
+|`rgblight_get_speed()` |Gets current speed         |
 
 ## Colors
 

docs/feature_split_keyboard.md

@@ -8,9 +8,20 @@ QMK Firmware has a generic implementation that is usable by any board, as well a
 
 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. 
+!> ARM is not yet fully supported for Split Keyboards and has many limitations. Progress is being made, but we have not yet reached 100% feature parity.
 
 
+## Compatibility Overview
+
+| Transport                    | AVR                | ARM                |
+|------------------------------|--------------------|--------------------|
+| ['serial'](serial_driver.md) | :heavy_check_mark: | :white_check_mark: <sup>1</sup> |
+| I2C                          | :heavy_check_mark: |                    |
+
+Notes:
+
+1. Both hardware and software limitations are detailed within the [driver documentation](serial_driver.md).
+
 ## Hardware Configuration
 
 This assumes that you're using two Pro Micro-compatible controllers, and are using TRRS jacks to connect to two halves. 

docs/feature_swap_hands.md

@@ -28,3 +28,4 @@ Note that the array indices are reversed same as the matrix and the values are o
 |`SH_MOFF`  |Momentarily turns off swap.                                              |
 |`SH_TG`    |Toggles swap on and off with every key press.                            |
 |`SH_TT`    |Toggles with a tap; momentary when held.                                 |
+|`SH_OS`    |One shot swap hands: toggles while pressed or until next key press.      |

docs/getting_started_docker.md

@@ -0,0 +1,47 @@
+# Docker Quick Start
+
+This project includes a Docker workflow that will allow you to build a new firmware for your keyboard very easily without major changes to your primary operating system. This also ensures that when you clone the project and perform a build, you have the exact same environment as anyone else and the QMK build infrastructure. This makes it much easier for people to help you troubleshoot any issues you encounter.
+
+## Requirements
+
+The main prerequisite is a working `docker` install.
+* [Docker CE](https://docs.docker.com/install/#supported-platforms)
+
+## Usage
+
+Acquire a local copy of the QMK's repository (including submodules):
+
+```bash
+git clone --recurse-submodules https://github.com/qmk/qmk_firmware.git
+cd qmk_firmware
+```
+
+Run the following command to build a keymap:
+```bash
+util/docker_build.sh <keyboard>:<keymap>
+# For example: util/docker_build.sh planck/rev6:default
+```
+
+This will compile the desired keyboard/keymap and leave the resulting `.hex` or `.bin` file in the QMK directory for you to flash. If `:keymap` is omitted, all keymaps are used. Note that the parameter format is the same as when building with `make`.
+
+There is also support for building _and_ flashing the keyboard straight from Docker by specifying the `target` as well:
+
+```bash
+util/docker_build.sh keyboard:keymap:target
+# For example: util/docker_build.sh planck/rev6:default:flash
+```
+
+You can also start the script without any parameters, in which case it will ask you to input the build parameters one by one, which you may find easier to use:
+
+```bash
+util/docker_build.sh
+# Reads parameters as input (leave blank for all keyboards/keymaps)
+```
+
+## FAQ
+
+### Why can't I flash on Windows/macOS
+
+On Windows and macOS, it requires [Docker Machine](http://gw.tnode.com/docker/docker-machine-with-usb-support-on-windows-macos/) to be running. This is tedious to set up, so it's not recommended; use [QMK Toolbox](https://github.com/qmk/qmk_toolbox) instead.
+
+!> Docker for Windows requires [Hyper-V](https://docs.microsoft.com/en-us/virtualization/hyper-v-on-windows/quick-start/enable-hyper-v) to be enabled. This means that it cannot work on versions of Windows which don't have Hyper-V, such as Windows 7, Windows 8 and **Windows 10 Home**.

docs/index.html

@@ -32,7 +32,7 @@
 
         // Moved pages
         '/adding_a_keyboard_to_qmk': '/hardware_keyboard_guidelines',
-        '/build_environment_setup': '/getting_started_build_tools',
+        '/build_environment_setup': '/newbs_getting_started',
         '/cli_dev_configuration': '/cli_configuration',
         '/dynamic_macros': '/feature_dynamic_macros',
         '/feature_common_shortcuts': '/feature_advanced_keycodes',
@@ -45,6 +45,7 @@
         '/tap_dance': '/feature_tap_dance',
         '/unicode': '/feature_unicode',
         '/python_development': '/cli_development',
+        '/getting_started_build_tools':'/newbs_getting_started',
       },
       basePath: '/',
       name: 'QMK Firmware',

docs/isp_flashing_guide.md

@@ -115,12 +115,18 @@ The simplest and quickest way to get things back to normal is to flash only a bo
 
 You can find the stock bootloaders in the [`util/` folder](https://github.com/qmk/qmk_firmware/tree/master/util). Be sure to flash the correct bootloader for your chip:
 
-* [`atmega32u4`](https://github.com/qmk/qmk_firmware/blob/master/util/bootloader_atmega32u4_1_0_0.hex) - Most keyboards, Planck Rev 1-5, Preonic Rev 1-2
-* [`Pro Micro`](https://github.com/sparkfun/Arduino_Boards/blob/master/sparkfun/avr/bootloaders/caterina/Caterina-promicro16.hex) - The default bootloader for Pro Micro controllers
-* [`at90usb1286`](https://github.com/qmk/qmk_firmware/blob/master/util/bootloader_at90usb128x_1_0_1.hex) - Planck Light Rev 1
-* [`atmega32a`](https://github.com/qmk/qmk_firmware/blob/master/util/bootloader_atmega32a_1_0_0.hex) - jj40, and other V-USB/ps2avrGB keyboards
+* **Atmel DFU**
+  * [ATmega16U4](https://github.com/qmk/qmk_firmware/blob/master/util/bootloader_atmega16u4_1.0.1.hex)
+  * [ATmega32U4](https://github.com/qmk/qmk_firmware/blob/master/util/bootloader_atmega32u4_1.0.0.hex)
+  * [AT90USB64](https://github.com/qmk/qmk_firmware/blob/master/util/bootloader_at90usb64_1.0.0.hex)
+  * [AT90USB128](https://github.com/qmk/qmk_firmware/blob/master/util/bootloader_at90usb128_1.0.1.hex)
+* **Caterina**
+  * [Pro Micro (5V/16MHz)](https://github.com/sparkfun/Arduino_Boards/blob/master/sparkfun/avr/bootloaders/caterina/Caterina-promicro16.hex)
+  * [Pro Micro (3.3V/8MHz)](https://github.com/sparkfun/Arduino_Boards/blob/master/sparkfun/avr/bootloaders/caterina/Caterina-promicro8.hex)
+* **BootloadHID (PS2AVRGB)**
+  * [ATmega32A](https://github.com/qmk/qmk_firmware/blob/master/util/bootloader_ps2avrgb_bootloadhid_1.0.1.hex)
 
-If you're not sure what your board uses, look in the `rules.mk` file for the keyboard in QMK. The `MCU =` line will have the value you need. It may differ between different versions of the board.
+If you're not sure what your board uses, look in the `rules.mk` file for the keyboard in QMK. The `MCU` and `BOOTLOADER` lines will have the value you need. It may differ between different versions of the board.
 
 ### Production Techniques
 

docs/ja/feature_hd44780.md

@@ -55,7 +55,7 @@ LCD_DISP_ON_CURSOR_BLINK : ディスプレイオン、点滅カーソル
 ````
 これはキーボードの `matrix_init_kb` またはキーマップの `matrix_init_user` で行うのが最適です。
 使用前にディスプレイをクリアすることをお勧めします。
-そのためには、`lcd_clrsrc()` を呼びます。
+そのためには、`lcd_clrscr()` を呼びます。
 
 ディスプレイに何かを表示するには、最初に `lcd_gotoxy(column, line)` を呼びます。最初の行の先頭に移動するには、`lcd_gotoxy(0, 0)` を呼び出し、その後 `lcd_puts("example string")` を使って文字列を出力します。
 

docs/ja/feature_layouts.md

@@ -0,0 +1,114 @@
+# レイアウト: 複数のキーボードで1つのキーマップを使用
+
+<!---
+  original document: 0.8.134:docs/feature_layouts.md
+  git diff 0.8.134 HEAD -- docs/feature_layouts.md | cat
+-->
+
+`layouts/` フォルダは、様々なキーボードに適用できる色々な物理キーレイアウトを含みます。
+
+```
+layouts/
++ default/
+| + 60_ansi/
+| | + readme.md
+| | + layout.json
+| | + a_good_keymap/
+| | | + keymap.c
+| | | + readme.md
+| | | + config.h
+| | | + rules.mk
+| | + <keymap folder>/
+| | + ...
+| + <layout folder>/
++ community/
+| + <layout folder>/
+| + ...
+```
+
+`layouts/default/` と `layouts/community/` は、レイアウト「repositories」の2つの例です。現在のところ、`default` にはユーザの参考用に、レイアウトに関する全ての情報および、`default_<layout>` という名前の1つのデフォルトのキーマップが含まれています。`community` には全ての共有キーマップが含まれており、それらはユーザが `layouts/` にクローンするための別のリポジトリに分割することを最終的な目的としていますQMK は `layouts/` 内のすべてのフォルダを検索するため、ここに複数のリポジトリを持つことができます。
+
+各レイアウトフォルダは、レイアウトの物理的な側面に基づいて、可能な限り一般的な名称で(`[a-z0-9_]`)という名前が付けられ、キーボードで定義されるレイアウトと一緒に `readme.md` を含みます。
+
+```md
+# 60_ansi
+
+   LAYOUT_60_ansi
+```
+
+新しい名前は既存のレイアウトで設定された標準に準拠しようと努力する必要があり、必要に応じて PR/Issue で議論することができます。
+
+## レイアウトのサポート
+
+キーボードがレイアウトをサポートするために、変数は `<keyboard>.h` で定義し、引数/キー (できれば物理レイアウト)の数に一致している必要があります。
+
+    #define LAYOUT_60_ansi KEYMAP_ANSI
+
+レイアウトの名前は次の正規表現に一致しなければなりません: `[a-z0-9_]+`
+
+フォルダ名はキーボードの `rules.mk` に追加する必要があります:
+
+    LAYOUTS = 60_ansi
+
+`LAYOUTS` は任意のキーボードフォルダレべルの `rules.mk` に設定することができます:
+
+    LAYOUTS = 60_iso
+
+ただし、`LAYOUT_<layout>` 変数は `<folder>.h` でも定義する必要があります。
+
+## キーマップのビルド
+
+以下の形式でコマンドを使ってキーボードキーマップを作成できるはずです:
+
+    make <keyboard>:<layout>
+
+### レイアウトの競合
+キーボードが複数のレイアウトオプションをサポートし、
+
+    LAYOUTS = ortho_4x4 ortho_4x12
+
+なおかつ両方のオプションについてレイアウトが存在する場合、
+```
+layouts/
++ community/
+| + ortho_4x4/
+| | + <layout>/
+| | | + ...
+| + ortho_4x12/
+| | + <layout>/
+| | | + ...
+| + ...
+```
+
+FORCE_LAYOUT 引数はどのレイアウトをビルドするかを指定するために使うことができます
+
+    make <keyboard>:<layout> FORCE_LAYOUT=ortho_4x4
+    make <keyboard>:<layout> FORCE_LAYOUT=ortho_4x12
+
+## キーボードに依存しないレイアウトを作成するためのヒント
+
+### インクルード
+
+`#include "planck.h"` を使う代わりに、以下の行を使ってコンパイルされる `<keyboard>.h` (`<folder>.h` はここでインクルードすべきではありません)ファイルをインクルードすることができます:
+
+    #include QMK_KEYBOARD_H
+
+キーボード固有のコードを保持したい場合は、これらの変数を使って `#ifdef` 文でエスケープすることができます:
+
+* `KEYBOARD_<folder1>_<folder2>`
+
+例えば:
+
+```c
+#ifdef KEYBOARD_planck
+    #ifdef KEYBOARD_planck_rev4
+        planck_rev4_function();
+    #endif
+#endif
+```
+
+名前は小文字でキーボード/リビジョンのフォルダ/ファイル名と正確に一致することに注意してください。
+
+### キーマップ
+
+同じレイアウトで分割および非分割キーボードをサポートするためには、キーマップでキーボード非依存の `LAYOUT_<layout name>` マクロを使う必要があります。例えば、Let's Split および Planck が同じレイアウトを共有するには、`LAYOUT_planck_grid` や C 配列の場合の単なる `{}` の代わりに、`LAYOUT_ortho_4x12` を使う必要があります。

docs/ja/feature_leader_key.md

@@ -0,0 +1,151 @@
+# リーダーキー: 新しい種類のモディファイア
+
+<!---
+  original document: 0.8.134:docs/feature_leader_key.md
+  git diff 0.8.134 HEAD -- docs/feature_leader_key.md | cat
+-->
+
+もしあなたが Vim を使ったことがある場合、リーダーキーは何であるかを知っています。そうでなければ、素晴らしい概念を発見しようとしています。:) 例えば、Alt+Shift+W を押す(3つのキーを同時に押す)代わりに、キーの_シーケンス_を押すことができたらどうでしょう？つまり、特別なモディファイア (リーダーキー)を押して、続けて W と C を押すと (単純にキーを高速に繋げます)、何かが起こります。
+
+それが `KC_LEAD` の機能です。以下は例です:
+
+1. リーダーキーとして使いたいキーボードのキーを選択します。それにキーコード `KC_LEAD` を割り当てます。このキーはこのためだけの専用です -- 単一アクションのキーで、他の用途には使うことができません。
+2. `config.h` に `#define LEADER_TIMEOUT 300` という行を追加します。これによって `KC_LEAD` キーのタイムアウトを設定します。具体的には、`KC_LEAD` キーを押してからリーダーキーのシーケンスを完了するまで一定の時間しかありません。ここでの `300` はそれを300msに設定します。この値を増やして、シーケンスを入力する時間を増やすことができます。ただし、この時間中に押されたキーは全て途中で遮られ、送信されません。そのためこの値は小さくしておいたほうが良いかもしれません。
+   * デフォルトでは、このタイムアウトは、`KC_LEAD` を押してからシーケンス全体が完了するまでに掛かる時間です。これは一部の人にとっては非常に短いかもしれません。そのため、このタイムアウトを増やしたほうが良い場合もあります。必要に応じて、`LEADER_PER_KEY_TIMING` オプションを有効にしたほうが良い場合もあります。これは各キーがタップされる度にタイムアウトまでの時間をリセットする機能です。これにより、タイムアウト時間を短くしつつも、比較的長いシーケンスを使うことができます。このオプションを有効にするには、`config.h` に `#define LEADER_PER_KEY_TIMING` を追加します。
+3. `matrix_scan_user` 関数の中で、以下のようなものを追加します:
+
+```c
+LEADER_EXTERNS();
+
+void matrix_scan_user(void) {
+  LEADER_DICTIONARY() {
+    leading = false;
+    leader_end();
+
+    SEQ_ONE_KEY(KC_F) {
+      // マクロ内でできること
+      SEND_STRING("QMK is awesome.");
+    }
+    SEQ_TWO_KEYS(KC_D, KC_D) {
+      SEND_STRING(SS_LCTL("a") SS_LCTL("c"));
+    }
+    SEQ_THREE_KEYS(KC_D, KC_D, KC_S) {
+      SEND_STRING("https://start.duckduckgo.com\n");
+    }
+    SEQ_TWO_KEYS(KC_A, KC_S) {
+      register_code(KC_LGUI);
+      register_code(KC_S);
+      unregister_code(KC_S);
+      unregister_code(KC_LGUI);
+    }
+  }
+}
+```
+
+ご覧のとおり、幾つかの関数があります。`SEQ_ONE_KEY` を単一キーシーケンス (リーダーの後に1つのキーのみ)に使い、より長いシーケンスについては `SEQ_TWO_KEYS`、`SEQ_THREE_KEYS` から `SEQ_FIVE_KEYS` を使うことができます。
+
+これらはそれぞれ1つ以上のキーコードを引数として受け付けます。これは重要な点です: **キーボードの任意のレイヤー**のキーコードを使うことができます。当たり前ですが、リーダーマクロが発動するにはそのレイヤーがアクティブである必要があります
+
+## `rules.mk` にリーダーキーサポートを追加
+
+リーダーキーのサポートを追加するには、単純にキーマップの `rules.mk` に1行を追加します:
+
+```make
+LEADER_ENABLE = yes
+```
+
+## リーダーキーのキーごとのタイミング
+
+長いリーダーキー文字列のためや 200wpm のタイピングスキルが無い場合に、非常に長いタイムアウト時間に頼るのではなく、キーを押すごとに入力を完了するまでの時間を増やす機能を使用することができます。これは、リーダーキーを使ってタップダンスを再現する場合に非常に役立ちます (C, C, C のような同じキーを複数回タップする場合)。
+
+これを有効にするには、以下を `config.h` に配置します:
+```c
+#define LEADER_PER_KEY_TIMING
+```
+
+この後、`LEADER_TIMEOUT` を 300ms 未満に下げることをお勧めします。
+
+```c
+#define LEADER_TIMEOUT 250
+```
+
+これで、リーダーキーのタイムアウト時間を 1000ms に設定することなく以下のようなことが可能になると思われます。
+
+```c
+SEQ_THREE_KEYS(KC_C, KC_C, KC_C) {
+  SEND_STRING("Per key timing is great!!!");
+}
+```
+
+## 厳密なキー処理
+
+デフォルトでは、リーダーキー機能は、リーダーシーケンスの確認時に [`モッドタップ`](ja/mod_tap.md) および [`レイヤータップ`](ja/feature_layers.md#switching-and-toggling-layers) 機能からのキーコードをフィルターします。つまり、`LT(3, KC_A)` を使っている場合、`LT(3, KC_A)` ではなくシーケンスの `KC_A` として取り出され、新しいユーザにとってより期待される動作を提供します。
+
+ほとんどの場合これで問題ありませんが、シーケンスでキーコード全体(例えば、上の例での `LT(3, KC_A)`) を指定したい場合は、`config.h` ファイルに `#define LEADER_KEY_STRICT_KEY_PROCESSING` を追加することこのような機能を有効にすることができます。これでフィルタリングが無効になり、キーコード全体を指定する必要があります。
+
+## カスタマイズ
+
+リーダーキー機能には、リーダーキー機能の動作にいくらかのカスタマイズを追加する方法があります。リーダーキー機能のプロセスの特定の部分で呼び出すことができる2つの関数、`leader_start()` と `leader_end()` です。
+
+`KC_LEAD` キーがタップされた時に `leader_start()` 関数が呼ばれ、リーダーシーケンスが完了するか、リーダータイムアウトの時間に達した時に `leader_end()` 関数が呼ばれます。
+
+リーダーシーケンスにフィードバック(ビープまたは音楽を再生するなど)を追加するために、これらの関数をコード (通常 は`keymap.c`)に追加することができます。
+
+```c
+void leader_start(void) {
+  // シーケンスの開始
+}
+
+void leader_end(void) {
+  // シーケンスの終了 (成功しない/失敗を検知)
+}
+```
+
+### 例
+
+この例では、リーダーシーケンスを開始するために `KC_LEAD` を押すとマリオの "One Up" 音が再生され、正常に完了した場合は "All Star" が再生され、失敗した場合は "Rick Roll" を再生されます。
+
+```c
+bool did_leader_succeed;
+#ifdef AUDIO_ENABLE
+float leader_start[][2] = SONG(ONE_UP_SOUND );
+float leader_succeed[][2] = SONG(ALL_STAR);
+float leader_fail[][2] = SONG(RICK_ROLL);
+#endif
+LEADER_EXTERNS();
+
+void matrix_scan_user(void) {
+  LEADER_DICTIONARY() {
+    did_leader_succeed = leading = false;
+
+    SEQ_ONE_KEY(KC_E) {
+      // マクロ内でできること
+      SEND_STRING(SS_LCTL(SS_LSFT("t")));
+      did_leader_succeed = true;
+    } else
+    SEQ_TWO_KEYS(KC_E, KC_D) {
+      SEND_STRING(SS_LGUI("r") "cmd\n" SS_LCTL("c"));
+      did_leader_succeed = true;
+    }
+    leader_end();
+  }
+}
+
+void leader_start(void) {
+#ifdef AUDIO_ENABLE
+    PLAY_SONG(leader_start);
+#endif
+}
+
+void leader_end(void) {
+  if (did_leader_succeed) {
+#ifdef AUDIO_ENABLE
+    PLAY_SONG(leader_succeed);
+#endif
+  } else {
+#ifdef AUDIO_ENABLE
+    PLAY_SONG(leader_fail);
+#endif
+  }
+}
+```

docs/ja/feature_led_matrix.md

@@ -0,0 +1,95 @@
+# LED マトリックスライト
+
+<!---
+  original document: 0.8.141:docs/feature_led_matrix.md
+  git diff 0.8.141 HEAD -- docs/feature_led_matrix.md | cat
+-->
+
+この機能により、外部ドライバによって駆動される LED マトリックスを使うことができます。この機能は、バックライト制御と同じキーコードを使えるようにするため、バックライトシステムに接続します。
+
+RGB LED を使いたい場合は、代わりに [RGB マトリックスサブシステム](ja/feature_rgb_matrix.md) を使うべきです。
+
+## ドライバ設定
+
+### IS31FL3731
+
+I2C IS31FL3731 RGB コントローラを使ったアドレス指定可能な LED マトリックスライトのための基本的なサポートがあります:有効にするには、`rules.mk` に以下を追加します:
+
+    LED_MATRIX_ENABLE = IS31FL3731
+
+1から4個の IS31FL3731 IC を使うことができます。キーボード上に存在しない IC の `LED_DRIVER_ADDR_<N>` 定義を指定しないでください。`config.h` に以下の項目を定義することができます:
+
+| 変数 | 説明 | デフォルト |
+|----------|-------------|---------|
+| `ISSI_TIMEOUT` | (オプション) i2c メッセージを待つ時間 | 100 |
+| `ISSI_PERSISTENCE` | (オプション) 失敗したメッセージをこの回数再試行する | 0 |
+| `LED_DRIVER_COUNT` | (必須) LED ドライバ IC の数 |  |
+| `LED_DRIVER_LED_COUNT` | (必須) 全てのドライバの LED ライトの数 |  |
+| `LED_DRIVER_ADDR_1` | (必須) 最初の LED ドライバのアドレス |  |
+| `LED_DRIVER_ADDR_2` | (オプション) 2番目の LED ドライバのアドレス |  |
+| `LED_DRIVER_ADDR_3` | (オプション) 3番目の LED ドライバのアドレス |  |
+| `LED_DRIVER_ADDR_4` | (オプション) 4番目の LED ドライバのアドレス |  |
+
+2つのドライバを使う例です。
+
+    // これは7ビットのアドレスで、左シフトされます
+    // ビット0に0を設定すると書き込み、1を設定すると読み込みです (I2C プロトコルに従う)
+    // アドレスは配線によって変わります:
+    // 0b1110100 AD <-> GND
+    // 0b1110111 AD <-> VCC
+    // 0b1110101 AD <-> SCL
+    // 0b1110110 AD <-> SDA
+    #define LED_DRIVER_ADDR_1 0b1110100
+    #define LED_DRIVER_ADDR_2 0b1110110
+    
+    #define LED_DRIVER_COUNT 2
+    #define LED_DRIVER_1_LED_COUNT 25
+    #define LED_DRIVER_2_LED_COUNT 24
+    #define LED_DRIVER_LED_COUNT LED_DRIVER_1_LED_TOTAL + LED_DRIVER_2_LED_TOTAL
+
+現在、2つのドライバのみがサポートされますが、4つの組み合わせ全てをサポートすることは簡単です。
+
+`<keyboard>.c` に全ての LED を列挙する配列を定義します:
+
+    const is31_led g_is31_leds[DRIVER_LED_TOTAL] = {
+    /* これらの位置については IS31 マニュアルを参照してください
+    *   driver
+    *   |  LED address
+    *   |  | */
+    {0, C3_3},
+    ....
+    }
+
+ここで、`Cx_y` は[データシート](http://www.issi.com/WW/pdf/31FL3731.pdf)およびヘッダファイル `drivers/issi/is31fl3731-simple.h` で定義されるマトリックス内の LED の位置です。`driver` は `config.h` で定義したドライバのインデックス(`0`、`1`、`2`、`3`のいずれか)です。
+
+## キーコード
+
+現在のところ、全ての LED マトリックスのキーコードは[バックライトシステム](ja/feature_backlight.md)と共有されます。
+
+## LED マトリックス効果
+
+現在のところ、LED マトリックス効果は作成されていません。
+
+## カスタムレイヤー効果
+
+カスタムレイヤー効果は `<keyboard>.c` 内で以下を定義することで行うことができます:
+
+    void led_matrix_indicators_kb(void) {
+    led_matrix_set_index_value(index, value);
+    }
+
+同様の関数がキーマップ内で `led_matrix_indicators_user` として動作します。
+
+## サスペンド状態
+
+サスペンド機能を使うには、以下を `<keyboard>.c` に追加します:
+
+    void suspend_power_down_kb(void)
+    {
+    led_matrix_set_suspend_state(true);
+    }
+    
+    void suspend_wakeup_init_kb(void)
+    {
+    led_matrix_set_suspend_state(false);
+    }

docs/ja/feature_thermal_printer.md

@@ -0,0 +1,15 @@
+# 感熱式プリンタ
+
+<!---
+  original document: 0.8.147:docs/feature_thermal_printer.md
+  git diff 0.8.147 HEAD -- docs/feature_thermal_printer.md | cat
+-->
+
+<!-- FIXME: Describe thermal printers support here. -->
+
+## 感熱式プリンタのキーコード
+
+| キー | 説明 |
+|-----------|----------------------------------------|
+| `PRINT_ON` | ユーザが入力した全ての印刷を開始 |
+| `PRINT_OFF` | ユーザが入力した全ての印刷を停止 |

docs/ja/feature_velocikey.md

@@ -0,0 +1,35 @@
+# Velocikey
+
+<!---
+  original document: 0.8.147:docs/feature_velocikey.md
+  git diff 0.8.147 HEAD -- docs/feature_velocikey.md | cat
+-->
+
+Velocikey は入力の速度を使って(レインボー渦巻効果のような)ライト効果の速度を制御できる機能です。速く入力すればするほどライトが速くなります！
+
+## 使用法
+Velocikey を使うためには、2つのステップがあります。最初に、キーボードをコンパイルする時に、`rules.mk` に `VELOCIKEY_ENABLE=yes` を設定する必要があります。例えば:
+
+```
+BOOTMAGIC_ENABLE = no
+MOUSEKEY_ENABLE = no
+STENO_ENABLE = no
+EXTRAKEY_ENABLE = yes
+VELOCIKEY_ENABLE = yes
+```
+
+次に、キーボードの使用中に、VLK_TOG キーコードを使って Velocikey を有効にする必要もあります。これは機能をオンおよびオフにします。
+
+以下の全てのライト効果が、Velocikey を有効にすることで制御されます:
+- RGB 明滅動作
+- RGB レインボームード
+- RGB レインボー渦巻
+- RGB スネーク
+- RGB ナイト
+
+LED 明滅動作の効果のサポートは計画されていますがまだ利用できません。
+
+Velocikey が有効になっている限り、現在オンになっている RGB ライトの他の全ての速度設定に関係なく、速度が制御されます。
+
+## 設定
+Velocikey は現在のところキーボード設定を介したどのような設定もサポートしません。速度の増加あるいは減少率などを調整したい場合は、`velocikey.c` を編集し、そこで値を調整して、好みの速度を実現する必要があります。

docs/keycodes.md

@@ -531,6 +531,7 @@ See also: [Swap Hands](feature_swap_hands.md)
 |`SH_MOFF`  |Momentarily turns off swap.                                              |
 |`SH_TG`    |Toggles swap on and off with every key press.                            |
 |`SH_TT`    |Toggles with a tap; momentary when held.                                 |
+|`SH_OS`    |One shot swap hands: toggle while pressed or until next key press.       |
 
 ## Unicode Support :id=unicode-support
 

docs/keymap.md

@@ -71,10 +71,22 @@ On the other hand, you can change `layer_state` to overlay the base layer with o
 
 
 ### Layer Precedence and Transparency
-Note that ***higher layer has higher priority on stack of layers***, namely firmware falls down from top layer to bottom to look up keycode. Once it spots keycode other than **`KC_TRNS`**(transparent) on a layer it stops searching and lower layers aren't referred.
+Note that ***higher layers have higher priority within the stack of layers***. The firmware works its way down from the highest active layers to look up keycodes. Once the firmware locates a keycode other than `KC_TRNS` (transparent) on an active layer, it stops searching, and lower layers aren't referenced.
 
-You can place `KC_TRANS` on overlay layer changes just part of layout to fall back on lower or base layer.
-Key with `KC_TRANS` (`KC_TRNS` and `_______` are the alias) doesn't has its own keycode and refers to lower valid layers for keycode, instead.
+           ____________
+          /           /  <--- Higher layer
+         /  KC_TRNS  //
+        /___________//   <--- Lower layer (KC_A)
+        /___________/
+    
+    In the above scenario, the non-transparent keys on the higher layer would be usable, but whenever `KC_TRNS` (or equivalent) is defined, the keycode (`KC_A`) on the lower level would be used.
+
+**Note:** Valid ways to denote transparency on a given layer:
+* `KC_TRANSPARENT`
+* `KC_TRNS` (alias)
+* `_______` (alias)
+
+These keycodes allow the processing to fall through to lower layers in search of a non-transparent keycode to process.
 
 ## Anatomy of a `keymap.c`
 

docs/newbs_flashing.md

@@ -1,18 +1,41 @@
-# Flashing Your Keyboard 
+# Flashing Your Keyboard
 
-Now that you've built a custom firmware file you'll want to flash your keyboard. 
+Now that you've built a custom firmware file you'll want to flash your keyboard.
+
+## Put Your Keyboard into DFU (Bootloader) Mode
+
+In order to flash your custom firmware you must first put your keyboard into a special flashing mode. While it is in this mode you will not be able to type or otherwise use your keyboard. It is very important that you do not unplug the keyboard or otherwise interrupt the flashing process while the firmware is being written.
+
+Different keyboards have different ways to enter this special mode. If your PCB currently runs QMK, TMK, or PS2AVRGB (Bootmapper Client) and you have not been given specific instructions, try the following, in order:
+
+* Hold down both shift keys and press `Pause`
+* Hold down both shift keys and press `B`
+* Unplug your keyboard, hold down the Spacebar and `B` at the same time, plug in your keyboard and wait a second before releasing the keys
+* Unplug your keyboard, hold down the top or bottom left key (usually Escape or Left Control) and plug in your keyboard
+* Press the physical `RESET` button, usually located on the underside of the PCB
+* Locate header pins on the PCB labeled `RESET` and `GND`, and short them together while plugging your PCB in
+
+If you've attempted all of the above to no avail, and the main chip on the board says `STM32` on it, this may be a bit more complicated. Generally your best bet is to ask on [Discord](https://discord.gg/Uq7gcHh) for assistance. It's likely some photos of the board will be asked for -- if you can get them ready beforehand it'll help move things along!
+
+Otherwise, you should see a message in yellow, similar to this in QMK Toolbox:
+
+```
+*** DFU device connected: Atmel Corp. ATmega32U4 (03EB:2FF4:0000)
+```
+
+and this bootloader device will also be present in Device Manager, System Information.app, or `lsusb`.
 
 ## Flashing Your Keyboard with QMK Toolbox
 
-The simplest way to flash your keyboard will be with the [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases). 
+The simplest way to flash your keyboard will be with the [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases).
 
-However, the QMK Toolbox is only available for Windows and macOS currently.  If you're using Linux (or just wish to flash the firmware from the command line), proceed down to [Flash Your Keyboard From The Command Line](#flash-your-keyboard-from-the-command-line).
+However, the Toolbox is currently only available for Windows and macOS. If you're using Linux (or just wish to flash the firmware from the command line), skip to the [Flash your Keyboard from the Command Line](#flash-your-keyboard-from-the-command-line) section.
 
-### Load The File Into QMK Toolbox
+### Load the File into QMK Toolbox
 
 Begin by opening the QMK Toolbox application. You'll want to locate the firmware file in Finder or Explorer. Your keyboard firmware may be in one of two formats- `.hex` or `.bin`. QMK tries to copy the appropriate one for your keyboard into the root `qmk_firmware` directory.
 
-If you are on Windows or macOS there are commands you can use to easily open the current firmware folder in Explorer or Finder.
+If you are on Windows or macOS, there are commands you can use to easily open the current folder in Explorer or Finder.
 
 #### Windows
 
@@ -38,65 +61,44 @@ For example, the `planck/rev5` with a `default` keymap will have this filename:
 planck_rev5_default.hex
 ```
 
-Once you have located your firmware file drag it into the "Local file" box in QMK Toolbox, or click "Open" and navigate to where your firmware file is stored. 
-
-### Put Your Keyboard Into DFU (Bootloader) Mode
-
-In order to flash your custom firmware you have to put your keyboard into a special flashing mode. While it is in this mode you will not be able to type or otherwise use your keyboard. It is very important that you do not unplug your keyboard or otherwise interrupt the flashing process while the firmware is being written.
-
-Different keyboards have different ways to enter this special mode. If your PCB currently runs QMK or TMK and you have not been given specific instructions try the following, in order:
-
-* Hold down both shift keys and press `Pause`
-* Hold down both shift keys and press `B`
-* Unplug your keyboard, hold down the Spacebar and `B` at the same time, plug in your keyboard and wait a second before releasing the keys
-* Press the physical `RESET` button on the bottom of the PCB
-* Locate header pins on the PCB labeled `BOOT0` or `RESET`, short those together while plugging your PCB in
-
-When you are successful you will see a message similar to this in QMK Toolbox:
-
-```
-*** Clueboard - Clueboard 66% HotSwap disconnected -- 0xC1ED:0x2390
-*** DFU device connected
-```
+Once you have located your firmware file drag it into the "Local file" box in QMK Toolbox, or click "Open" and navigate to where your firmware file is stored.
 
 ### Flash Your Keyboard
 
 Click the `Flash` button in QMK Toolbox. You will see output similar to the following:
 
 ```
-*** Clueboard - Clueboard 66% HotSwap disconnected -- 0xC1ED:0x2390
-*** DFU device connected
+*** DFU device connected: Atmel Corp. ATmega32U4 (03EB:2FF4:0000)
 *** Attempting to flash, please don't remove device
->>> dfu-programmer atmega32u4 erase --force
+>>> dfu-programmer.exe atmega32u4 erase --force
     Erasing flash...  Success
     Checking memory from 0x0 to 0x6FFF...  Empty.
->>> dfu-programmer atmega32u4 flash /Users/skully/qmk_firmware/clueboard_66_hotswap_gen1_skully.hex
-    Checking memory from 0x0 to 0x55FF...  Empty.
-    0%                            100%  Programming 0x5600 bytes...
+>>> dfu-programmer.exe atmega32u4 flash "D:\Git\qmk_firmware\gh60_satan_default.hex"
+    Checking memory from 0x0 to 0x3F7F...  Empty.
+    0%                            100%  Programming 0x3F80 bytes...
     [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>]  Success
     0%                            100%  Reading 0x7000 bytes...
     [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>]  Success
     Validating...  Success
-    0x5600 bytes written into 0x7000 bytes memory (76.79%).
->>> dfu-programmer atmega32u4 reset
+    0x3F80 bytes written into 0x7000 bytes memory (56.70%).
+>>> dfu-programmer.exe atmega32u4 reset
     
-*** DFU device disconnected
-*** Clueboard - Clueboard 66% HotSwap connected -- 0xC1ED:0x2390
+*** DFU device disconnected: Atmel Corp: ATmega32U4 (03EB:2FF4:0000)
 ```
 
 ## Flash your Keyboard from the Command Line
 
-This has been made pretty simple compared to what it used to be.  When you are ready to compile and flash your firmware, open up your terminal window and run the flash command: 
+This has been made pretty simple compared to what it used to be. When you are ready to compile and flash your firmware, open up your terminal window and run the flash command:
 
     qmk flash
 
-If you have not configured your keyboard/keymap name, or you have multiple keyboards, you can specify the keyboard and keymap:
+If you have not configured your keyboard/keymap name in the CLI, or you have multiple keyboards, you can specify the keyboard and keymap:
 
     qmk flash -kb <my_keyboard> -km <my_keymap>
 
-This will check the keyboard's configuration, and then attempt to flash it based on the specified bootloader.  This means that you don't need to know which bootloader that your keyboard uses.  Just run the command, and let the command do the heavy lifting.
+This will check the keyboard's configuration, and then attempt to flash it based on the specified bootloader. This means that you don't need to know which bootloader that your keyboard uses. Just run the command, and let the command do the heavy lifting.
 
-However, this does rely on the bootloader being set by the keyboard.  If this information is not configured, or you're using a board that doesn't have a supported target to flash it, you will see this error:
+However, this does rely on the bootloader being set by the keyboard. If this information is not configured, or you're using a board that doesn't have a supported target to flash it, you will see this error:
 
     WARNING: This board's bootloader is not specified or is not supported by the ":flash" target at this time.
 

docs/newbs_getting_started.md

@@ -57,10 +57,9 @@ You may be asked to close and reopen the window. Do this and keep running the ab
 
 You will need to install Homebrew. Follow the instructions on the [Homebrew homepage](https://brew.sh).
 
-After Homebrew is installed run these commands:
+After Homebrew is installed run this command:
 
-    brew tap qmk/qmk
-    brew install qmk
+    brew install qmk/qmk/qmk
 
 ### Linux
 
@@ -70,10 +69,21 @@ You will need to install Git and Python. It's very likely that you already have
 * Fedora / Red Hat / CentOS: `sudo yum install git python3 python3-pip`
 * Arch / Manjaro: `sudo pacman -S git python python-pip python-setuptools libffi`
 
-
 Install the global CLI to bootstrap your system:
 
-  `python3 -m pip install --user qmk` (on Arch-based distros you can also try the `qmk` package from AUR (**note**: it's maintained by a community member): `yay -S qmk`)
+`python3 -m pip install --user qmk` (on Arch-based distros you can also try the `qmk` package from AUR (**note**: it's maintained by a community member): `yay -S qmk`)
+
+### FreeBSD
+
+You will need to install Git and Python. It's possible that you already have both, but if not, run the following commands to install them:
+
+    pkg install git python3
+
+Make sure that `$HOME/.local/bin` is added to your `$PATH` so that locally install Python packages are available.
+
+Once installed, you can install QMK CLI:
+
+    python3 -m pip install --user qmk
 
 ## 3. Run QMK Setup :id=set-up-qmk
 
@@ -89,6 +99,12 @@ This is due to a [bug](https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=839155)
 Sadly, Ubuntu reitroduced this bug and is [yet to fix it](https://bugs.launchpad.net/ubuntu/+source/bash/+bug/1588562).
 Luckily, the fix is easy. Run this as your user: `echo "PATH=$HOME/.local/bin:$PATH" >> $HOME/.bashrc && source $HOME/.bashrc`
 
+?>**Note on FreeBSD**:
+It is suggested to run `qmk setup` as a non-`root` user to start with, but this will likely identify packages that need to be installed to your
+base system using `pkg`. However the installation will probably fail when run as an unprivileged user.
+To manually install the base dependencies, run `./util/qmk_install.sh` either as `root`, or with `sudo`.
+Once that completes, re-run `qmk setup` to complete the setup and checks.
+
 ?> If you already know [how to use GitHub](getting_started_github.md), we recommend that you create your own fork and use `qmk setup <github_username>/qmk_firmware` to clone your personal fork. If you don't know what that means you can safely ignore this message.
 
 ## 4. Test Your Build Environment

docs/proton_c_conversion.md

@@ -36,7 +36,7 @@ These are defaults based on what has been implemented for ARM boards.
 | [RGB Lighting](feature_rgblight.md) | Disabled                                                                                                         |
 | [Backlight](feature_backlight.md)   | Forces [task driven PWM](feature_backlight.md#software-pwm-driver) until ARM can provide automatic configuration |
 | USB Host (e.g. USB-USB converter)   | Not supported (USB host code is AVR specific and is not currently supported on ARM)                              |
-| [Split keyboards](feature_split_keyboard.md) | Not supported yet                                                                                       |
+| [Split keyboards](feature_split_keyboard.md) | Partial - heavily dependent on enabled features                                                         |
 
 ## Manual Conversion
 

docs/serial_driver.md

@@ -0,0 +1,69 @@
+# 'serial' Driver
+This driver powers the [Split Keyboard](feature_split_keyboard.md) feature.
+
+?> Serial in this context should be read as **sending information one bit at a time**, rather than implementing UART/USART/RS485/RS232 standards.
+
+All drivers in this category have the following characteristics:
+* Provides data and signaling over a single conductor
+* Limited to single master, single slave
+
+## Supported Driver Types
+
+|                   | AVR                | ARM                |
+|-------------------|--------------------|--------------------|
+| bit bang          | :heavy_check_mark: | :heavy_check_mark: |
+| USART Half-duplex |                    | :heavy_check_mark: |
+
+## Driver configuration
+
+### Bitbang
+Default driver, the absence of configuration assumes this driver. To configure it, add this to your rules.mk:
+
+```make
+SERIAL_DRIVER = bitbang
+```
+
+Configure the driver via your config.h:
+```c
+#define SOFT_SERIAL_PIN D0  // or D1, D2, D3, E6
+#define SELECT_SOFT_SERIAL_SPEED 1 // or 0, 2, 3, 4, 5
+                                   //  0: about 189kbps (Experimental only)
+                                   //  1: about 137kbps (default)
+                                   //  2: about 75kbps
+                                   //  3: about 39kbps
+                                   //  4: about 26kbps
+                                   //  5: about 20kbps
+```
+
+#### ARM
+
+!> The bitbang driver causes connection issues with bitbang WS2812 driver
+
+Along with the generic options above, you must also turn on the `PAL_USE_CALLBACKS` feature in your halconf.h.
+
+### USART Half-duplex
+Targeting STM32 boards where communication is offloaded to a USART hardware device. The advantage is that this provides fast and accurate timings. `SOFT_SERIAL_PIN` for this driver is the configured USART TX pin. **The TX pin must have appropriate pull-up resistors**. To configure it, add this to your rules.mk:
+
+```make
+SERIAL_DRIVER = usart
+```
+
+Configure the hardware via your config.h:
+```c
+#define SOFT_SERIAL_PIN B6  // USART TX pin
+#define SELECT_SOFT_SERIAL_SPEED 1 // or 0, 2, 3, 4, 5
+                                   //  0: about 460800 baud
+                                   //  1: about 230400 baud (default)
+                                   //  2: about 115200 baud
+                                   //  3: about 57600 baud
+                                   //  4: about 38400 baud
+                                   //  5: about 19200 baud
+#define SERIAL_USART_DRIVER SD1 // USART driver of TX pin. default: SD1
+#define SERIAL_USART_TX_PAL_MODE 7 // Pin "alternate function", see the respective datasheet for the appropriate values for your MCU. default: 7
+```
+
+You must also enable the ChibiOS `SERIAL` feature:
+* In your board's halconf.h: `#define HAL_USE_SERIAL TRUE`
+* In your board's mcuconf.h: `#define STM32_SERIAL_USE_USARTn TRUE` (where 'n' matches the peripheral number of your selected USART on the MCU)
+
+Do note that the configuration required is for the `SERIAL` peripheral, not the `UART` peripheral.

doxygen-todo

@@ -1,5 +1,4 @@
 tmk_core/protocol
-tmk_core/protocol/bluefruit
 tmk_core/protocol/chibios
 tmk_core/protocol/iwrap
 tmk_core/protocol/lufa