Move everything to Python 3.6 (#8835)

* fixing layout for configurator

adding missing bottom row key to resolve formatting

.clang_complete

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

.gitignore

@@ -24,6 +24,7 @@ quantum/version.h
 .idea/
 CMakeLists.txt
 cmake-build-debug
+.clang_complete
 doxygen/
 .DS_Store
 /util/wsl_downloaded
@@ -47,7 +48,6 @@ doxygen/
 *.iml
 .browse.VC.db*
 *.stackdump
-util/Win_Check_Output.txt
 # Let these ones be user specific, since we have so many different configurations
 .vscode/c_cpp_properties.json
 .vscode/launch.json

.vscode/settings.json

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

bin/qmk

@@ -2,52 +2,61 @@
 """CLI wrapper for running QMK commands.
 """
 import os
-import subprocess
 import sys
 from importlib.util import find_spec
-from time import strftime
+from pathlib import Path
 
 # Add the QMK python libs to our path
-script_dir = os.path.dirname(os.path.realpath(__file__))
-qmk_dir = os.path.abspath(os.path.join(script_dir, '..'))
-python_lib_dir = os.path.abspath(os.path.join(qmk_dir, 'lib', 'python'))
-sys.path.append(python_lib_dir)
+script_dir = Path(os.path.realpath(__file__)).parent
+qmk_dir = script_dir.parent
+python_lib_dir = Path(qmk_dir / 'lib' / 'python').resolve()
+sys.path.append(str(python_lib_dir))
 
-# Make sure our modules have been setup
-with open(os.path.join(qmk_dir, 'requirements.txt'), 'r') as fd:
-    for line in fd.readlines():
-        line = line.strip().replace('<', '=').replace('>', '=')
 
-        if line[0] == '#':
-            continue
+def _check_modules(requirements):
+    """ Check if the modules in the given requirements.txt are available.
+    """
+    with Path(qmk_dir / requirements).open() as fd:
+        for line in fd.readlines():
+            line = line.strip().replace('<', '=').replace('>', '=')
 
-        if '#' in line:
-            line = line.split('#')[0]
+            if len(line) == 0 or line[0] == '#' or line.startswith('-r'):
+                continue
 
-        module = line.split('=')[0] if '=' in line else line
+            if '#' in line:
+                line = line.split('#')[0]
+
+            module = dict()
+            module['name'] = module['import'] = line.split('=')[0] if '=' in line else line
 
-        if module in ['pep8-naming']:
             # Not every module is importable by its own name.
-            continue
+            if module['name'] == "pep8-naming":
+                module['import'] = "pep8ext_naming"
 
-        if not find_spec(module):
-            print('Could not find module %s!' % module)
-            print('Please run `pip3 install -r requirements.txt` to install the python dependencies.')
-            exit(255)
+            if not find_spec(module['import']):
+                print('Could not find module %s!' % module['name'])
+                print('Please run `python3 -m pip install -r %s` to install required python dependencies.' % (qmk_dir / requirements,))
+                if developer:
+                    print('You can also turn off developer mode: qmk config user.developer=None')
+                print()
+                exit(255)
 
-# Figure out our version
-# TODO(skullydazed/anyone): Find a method that doesn't involve git. This is slow in docker and on windows.
-command = ['git', 'describe', '--abbrev=6', '--dirty', '--always', '--tags']
-result = subprocess.run(command, universal_newlines=True, stdout=subprocess.PIPE, stderr=subprocess.STDOUT)
 
-if result.returncode == 0:
-    os.environ['QMK_VERSION'] = result.stdout.strip()
-else:
-    os.environ['QMK_VERSION'] = 'nogit-' + strftime('%Y-%m-%d-%H:%M:%S') + '-dirty'
+developer = False
+# Make sure our modules have been setup
+_check_modules('requirements.txt')
 
 # Setup the CLI
 import milc  # noqa
 
+# For developers additional modules are needed
+if milc.cli.config.user.developer:
+    # Do not run the check for 'config',
+    # so users can turn off developer mode
+    if len(sys.argv) == 1 or (len(sys.argv) > 1 and 'config' != sys.argv[1]):
+        developer = True
+        _check_modules('requirements-dev.txt')
+
 milc.EMOJI_LOGLEVELS['INFO'] = '{fg_blue}Ψ{style_reset_all}'
 
 

build_json.mk

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

build_keyboard.mk

@@ -231,44 +231,19 @@ endif
 # We can assume a ChibiOS target When MCU_FAMILY is defined since it's
 # not used for LUFA
 ifdef MCU_FAMILY
-    FIRMWARE_FORMAT?=bin
     PLATFORM=CHIBIOS
+    PLATFORM_KEY=chibios
+    FIRMWARE_FORMAT?=bin
 else ifdef ARM_ATSAM
     PLATFORM=ARM_ATSAM
+    PLATFORM_KEY=arm_atsam
     FIRMWARE_FORMAT=bin
 else
     PLATFORM=AVR
+    PLATFORM_KEY=avr
     FIRMWARE_FORMAT?=hex
 endif
 
-ifeq ($(PLATFORM),CHIBIOS)
-    include $(TMK_PATH)/chibios.mk
-    OPT_OS = chibios
-    ifneq ("$(wildcard $(KEYBOARD_PATH_5)/bootloader_defs.h)","")
-        OPT_DEFS += -include $(KEYBOARD_PATH_5)/bootloader_defs.h
-     else ifneq ("$(wildcard $(KEYBOARD_PATH_5)/boards/$(BOARD)/bootloader_defs.h)","")
-        OPT_DEFS += -include $(KEYBOARD_PATH_5)/boards/$(BOARD)/bootloader_defs.h
-    else ifneq ("$(wildcard $(KEYBOARD_PATH_4)/bootloader_defs.h)","")
-        OPT_DEFS += -include $(KEYBOARD_PATH_4)/bootloader_defs.h
-     else ifneq ("$(wildcard $(KEYBOARD_PATH_4)/boards/$(BOARD)/bootloader_defs.h)","")
-        OPT_DEFS += -include $(KEYBOARD_PATH_4)/boards/$(BOARD)/bootloader_defs.h
-    else ifneq ("$(wildcard $(KEYBOARD_PATH_3)/bootloader_defs.h)","")
-        OPT_DEFS += -include $(KEYBOARD_PATH_3)/bootloader_defs.h
-     else ifneq ("$(wildcard $(KEYBOARD_PATH_3)/boards/$(BOARD)/bootloader_defs.h)","")
-        OPT_DEFS += -include $(KEYBOARD_PATH_3)/boards/$(BOARD)/bootloader_defs.h
-    else ifneq ("$(wildcard $(KEYBOARD_PATH_2)/bootloader_defs.h)","")
-        OPT_DEFS += -include $(KEYBOARD_PATH_2)/bootloader_defs.h
-     else ifneq ("$(wildcard $(KEYBOARD_PATH_2)/boards/$(BOARD)/bootloader_defs.h)","")
-        OPT_DEFS += -include $(KEYBOARD_PATH_2)/boards/$(BOARD)/bootloader_defs.h
-    else ifneq ("$(wildcard $(KEYBOARD_PATH_1)/bootloader_defs.h)","")
-        OPT_DEFS += -include $(KEYBOARD_PATH_1)/bootloader_defs.h
-     else ifneq ("$(wildcard $(KEYBOARD_PATH_1)/boards/$(BOARD)/bootloader_defs.h)","")
-        OPT_DEFS += -include $(KEYBOARD_PATH_1)/boards/$(BOARD)/bootloader_defs.h
-    else ifneq ("$(wildcard $(TOP_DIR)/drivers/boards/$(BOARD)/bootloader_defs.h)","")
-        OPT_DEFS += -include $(TOP_DIR)/drivers/boards/$(BOARD)/bootloader_defs.h
-    endif
-endif
-
 # Find all of the config.h files and add them to our CONFIG_H define.
 CONFIG_H :=
 ifneq ("$(wildcard $(KEYBOARD_PATH_5)/config.h)","")
@@ -304,11 +279,6 @@ ifneq ("$(wildcard $(KEYBOARD_PATH_5)/post_config.h)","")
     POST_CONFIG_H += $(KEYBOARD_PATH_5)/post_config.h
 endif
 
-# Save the defines and includes here, so we don't include any keymap specific ones
-PROJECT_DEFS := $(OPT_DEFS)
-PROJECT_INC := $(VPATH) $(EXTRAINCDIRS) $(KEYBOARD_PATHS)
-PROJECT_CONFIG := $(CONFIG_H)
-
 # Userspace setup and definitions
 ifeq ("$(USER_NAME)","")
     USER_NAME := $(KEYMAP)
@@ -354,23 +324,17 @@ SRC += $(TMK_COMMON_SRC)
 OPT_DEFS += $(TMK_COMMON_DEFS)
 EXTRALDFLAGS += $(TMK_COMMON_LDFLAGS)
 
-ifeq ($(PLATFORM),AVR)
-ifeq ($(strip $(PROTOCOL)), VUSB)
-    include $(TMK_PATH)/protocol/vusb.mk
+include $(TMK_PATH)/$(PLATFORM_KEY).mk
+ifneq ($(strip $(PROTOCOL)),)
+    include $(TMK_PATH)/protocol/$(strip $(shell echo $(PROTOCOL) | tr '[:upper:]' '[:lower:]')).mk
 else
-    include $(TMK_PATH)/protocol/lufa.mk
-endif
-    include $(TMK_PATH)/avr.mk
+    include $(TMK_PATH)/protocol/$(PLATFORM_KEY).mk
 endif
 
-ifeq ($(PLATFORM),ARM_ATSAM)
-    include $(TMK_PATH)/arm_atsam.mk
-    include $(TMK_PATH)/protocol/arm_atsam.mk
-endif
-
-ifeq ($(PLATFORM),CHIBIOS)
-    include $(TMK_PATH)/protocol/chibios.mk
-endif
+# TODO: remove this bodge?
+PROJECT_DEFS := $(OPT_DEFS)
+PROJECT_INC := $(VPATH) $(EXTRAINCDIRS) $(KEYBOARD_PATHS)
+PROJECT_CONFIG := $(CONFIG_H)
 
 ifeq ($(strip $(VISUALIZER_ENABLE)), yes)
     VISUALIZER_DIR = $(QUANTUM_DIR)/visualizer

build_test.mk

@@ -41,6 +41,7 @@ all: elf
 
 VPATH += $(COMMON_VPATH)
 PLATFORM:=TEST
+PLATFORM_KEY:=test
 
 ifneq ($(filter $(FULL_TESTS),$(TEST)),)
 include tests/$(TEST)/rules.mk

common_features.mk

@@ -13,52 +13,42 @@
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
-SERIAL_DIR := $(QUANTUM_DIR)/serial_link
 SERIAL_PATH := $(QUANTUM_PATH)/serial_link
-SERIAL_SRC := $(wildcard $(SERIAL_PATH)/protocol/*.c)
-SERIAL_SRC += $(wildcard $(SERIAL_PATH)/system/*.c)
-SERIAL_DEFS += -DSERIAL_LINK_ENABLE
-COMMON_VPATH += $(SERIAL_PATH)
+
+QUANTUM_SRC += \
+    $(QUANTUM_DIR)/quantum.c \
+    $(QUANTUM_DIR)/keymap_common.c \
+    $(QUANTUM_DIR)/keycode_config.c
 
 ifeq ($(strip $(API_SYSEX_ENABLE)), yes)
     OPT_DEFS += -DAPI_SYSEX_ENABLE
-    SRC += $(QUANTUM_DIR)/api/api_sysex.c
     OPT_DEFS += -DAPI_ENABLE
-    SRC += $(QUANTUM_DIR)/api.c
     MIDI_ENABLE=yes
+    SRC += $(QUANTUM_DIR)/api/api_sysex.c
+    SRC += $(QUANTUM_DIR)/api.c
 endif
 
-MUSIC_ENABLE := 0
-
 ifeq ($(strip $(AUDIO_ENABLE)), yes)
     OPT_DEFS += -DAUDIO_ENABLE
-    MUSIC_ENABLE := 1
+    MUSIC_ENABLE = yes
     SRC += $(QUANTUM_DIR)/process_keycode/process_audio.c
     SRC += $(QUANTUM_DIR)/process_keycode/process_clicky.c
-    ifeq ($(PLATFORM),AVR)
-        SRC += $(QUANTUM_DIR)/audio/audio.c
-    else
-        SRC += $(QUANTUM_DIR)/audio/audio_arm.c
-    endif
+    SRC += $(QUANTUM_DIR)/audio/audio_$(PLATFORM_KEY).c
     SRC += $(QUANTUM_DIR)/audio/voices.c
     SRC += $(QUANTUM_DIR)/audio/luts.c
 endif
 
 ifeq ($(strip $(MIDI_ENABLE)), yes)
     OPT_DEFS += -DMIDI_ENABLE
-    MUSIC_ENABLE := 1
+    MUSIC_ENABLE = yes
     SRC += $(QUANTUM_DIR)/process_keycode/process_midi.c
 endif
 
-ifeq ($(MUSIC_ENABLE), 1)
+MUSIC_ENABLE ?= no
+ifeq ($(MUSIC_ENABLE), yes)
     SRC += $(QUANTUM_DIR)/process_keycode/process_music.c
 endif
 
-ifeq ($(strip $(COMBO_ENABLE)), yes)
-    OPT_DEFS += -DCOMBO_ENABLE
-    SRC += $(QUANTUM_DIR)/process_keycode/process_combo.c
-endif
-
 ifeq ($(strip $(STENO_ENABLE)), yes)
     OPT_DEFS += -DSTENO_ENABLE
     VIRTSER_ENABLE ?= yes
@@ -80,28 +70,6 @@ ifeq ($(strip $(POINTING_DEVICE_ENABLE)), yes)
     SRC += $(QUANTUM_DIR)/pointing_device.c
 endif
 
-ifeq ($(strip $(UCIS_ENABLE)), yes)
-    OPT_DEFS += -DUCIS_ENABLE
-    UNICODE_COMMON := yes
-    SRC += $(QUANTUM_DIR)/process_keycode/process_ucis.c
-endif
-
-ifeq ($(strip $(UNICODEMAP_ENABLE)), yes)
-    OPT_DEFS += -DUNICODEMAP_ENABLE
-    UNICODE_COMMON := yes
-    SRC += $(QUANTUM_DIR)/process_keycode/process_unicodemap.c
-endif
-
-ifeq ($(strip $(UNICODE_ENABLE)), yes)
-    OPT_DEFS += -DUNICODE_ENABLE
-    UNICODE_COMMON := yes
-    SRC += $(QUANTUM_DIR)/process_keycode/process_unicode.c
-endif
-
-ifeq ($(strip $(UNICODE_COMMON)), yes)
-    SRC += $(QUANTUM_DIR)/process_keycode/process_unicode_common.c
-endif
-
 VALID_EEPROM_DRIVER_TYPES := vendor custom transient i2c
 EEPROM_DRIVER ?= vendor
 ifeq ($(filter $(EEPROM_DRIVER),$(VALID_EEPROM_DRIVER_TYPES)),)
@@ -249,31 +217,18 @@ ifeq ($(strip $(RGB_KEYCODES_ENABLE)), yes)
     SRC += $(QUANTUM_DIR)/process_keycode/process_rgb.c
 endif
 
-ifeq ($(strip $(TAP_DANCE_ENABLE)), yes)
-    OPT_DEFS += -DTAP_DANCE_ENABLE
-    SRC += $(QUANTUM_DIR)/process_keycode/process_tap_dance.c
-endif
-
-ifeq ($(strip $(KEY_LOCK_ENABLE)), yes)
-    OPT_DEFS += -DKEY_LOCK_ENABLE
-    SRC += $(QUANTUM_DIR)/process_keycode/process_key_lock.c
-endif
-
 ifeq ($(strip $(PRINTING_ENABLE)), yes)
     OPT_DEFS += -DPRINTING_ENABLE
     SRC += $(QUANTUM_DIR)/process_keycode/process_printer.c
     SRC += $(TMK_DIR)/protocol/serial_uart.c
 endif
 
-ifeq ($(strip $(AUTO_SHIFT_ENABLE)), yes)
-    OPT_DEFS += -DAUTO_SHIFT_ENABLE
-    SRC += $(QUANTUM_DIR)/process_keycode/process_auto_shift.c
-    ifeq ($(strip $(AUTO_SHIFT_MODIFIERS)), yes)
-        OPT_DEFS += -DAUTO_SHIFT_MODIFIERS
-    endif
-endif
-
 ifeq ($(strip $(SERIAL_LINK_ENABLE)), yes)
+    SERIAL_SRC := $(wildcard $(SERIAL_PATH)/protocol/*.c)
+    SERIAL_SRC += $(wildcard $(SERIAL_PATH)/system/*.c)
+    SERIAL_DEFS += -DSERIAL_LINK_ENABLE
+    COMMON_VPATH += $(SERIAL_PATH)
+
     SRC += $(patsubst $(QUANTUM_PATH)/%,%,$(SERIAL_SRC))
     OPT_DEFS += $(SERIAL_DEFS)
     VAPTH += $(SERIAL_PATH)
@@ -315,11 +270,7 @@ ifeq ($(strip $(BACKLIGHT_ENABLE)), yes)
     else
         SRC += $(QUANTUM_DIR)/backlight/backlight_driver_common.c
         ifeq ($(strip $(BACKLIGHT_DRIVER)), pwm)
-            ifeq ($(PLATFORM),AVR)
-                SRC += $(QUANTUM_DIR)/backlight/backlight_avr.c
-            else
-                SRC += $(QUANTUM_DIR)/backlight/backlight_arm.c
-            endif
+            SRC += $(QUANTUM_DIR)/backlight/backlight_$(PLATFORM_KEY).c
         else
             SRC += $(QUANTUM_DIR)/backlight/backlight_$(strip $(BACKLIGHT_DRIVER)).c
         endif
@@ -371,34 +322,16 @@ ifeq ($(strip $(USB_HID_ENABLE)), yes)
     include $(TMK_DIR)/protocol/usb_hid.mk
 endif
 
+ifeq ($(strip $(WPM_ENABLE)), yes)
+    SRC += $(QUANTUM_DIR)/wpm.c
+    OPT_DEFS += -DWPM_ENABLE
+endif
+
 ifeq ($(strip $(ENCODER_ENABLE)), yes)
     SRC += $(QUANTUM_DIR)/encoder.c
     OPT_DEFS += -DENCODER_ENABLE
 endif
 
-HAPTIC_ENABLE ?= no
-ifneq ($(strip $(HAPTIC_ENABLE)),no)
-	COMMON_VPATH += $(DRIVER_PATH)/haptic
-	SRC += haptic.c
-	OPT_DEFS += -DHAPTIC_ENABLE
-endif
-
-ifneq ($(filter DRV2605L, $(HAPTIC_ENABLE)), )
-    SRC += DRV2605L.c
-    QUANTUM_LIB_SRC += i2c_master.c
-    OPT_DEFS += -DDRV2605L
-endif
-
-ifneq ($(filter SOLENOID, $(HAPTIC_ENABLE)), )
-    SRC += solenoid.c
-    OPT_DEFS += -DSOLENOID_ENABLE
-endif
-
-ifeq ($(strip $(HD44780_ENABLE)), yes)
-    SRC += drivers/avr/hd44780.c
-    OPT_DEFS += -DHD44780_ENABLE
-endif
-
 ifeq ($(strip $(VELOCIKEY_ENABLE)), yes)
     OPT_DEFS += -DVELOCIKEY_ENABLE
     SRC += $(QUANTUM_DIR)/velocikey.c
@@ -417,26 +350,11 @@ ifeq ($(strip $(DYNAMIC_KEYMAP_ENABLE)), yes)
     SRC += $(QUANTUM_DIR)/dynamic_keymap.c
 endif
 
-ifeq ($(strip $(LEADER_ENABLE)), yes)
-  SRC += $(QUANTUM_DIR)/process_keycode/process_leader.c
-  OPT_DEFS += -DLEADER_ENABLE
-endif
-
-
 ifeq ($(strip $(DIP_SWITCH_ENABLE)), yes)
-  SRC += $(QUANTUM_DIR)/dip_switch.c
-  OPT_DEFS += -DDIP_SWITCH_ENABLE
+    OPT_DEFS += -DDIP_SWITCH_ENABLE
+    SRC += $(QUANTUM_DIR)/dip_switch.c
 endif
 
-include $(DRIVER_PATH)/qwiic/qwiic.mk
-
-QUANTUM_SRC:= \
-    $(QUANTUM_DIR)/quantum.c \
-    $(QUANTUM_DIR)/keymap_common.c \
-    $(QUANTUM_DIR)/keycode_config.c
-
-
-
 VALID_CUSTOM_MATRIX_TYPES:= yes lite no
 
 CUSTOM_MATRIX ?= no
@@ -494,6 +412,29 @@ ifeq ($(strip $(SPLIT_KEYBOARD)), yes)
     COMMON_VPATH += $(QUANTUM_PATH)/split_common
 endif
 
+HAPTIC_ENABLE ?= no
+ifneq ($(strip $(HAPTIC_ENABLE)),no)
+    COMMON_VPATH += $(DRIVER_PATH)/haptic
+    SRC += haptic.c
+    OPT_DEFS += -DHAPTIC_ENABLE
+endif
+
+ifneq ($(filter DRV2605L, $(HAPTIC_ENABLE)), )
+    SRC += DRV2605L.c
+    QUANTUM_LIB_SRC += i2c_master.c
+    OPT_DEFS += -DDRV2605L
+endif
+
+ifneq ($(filter SOLENOID, $(HAPTIC_ENABLE)), )
+    SRC += solenoid.c
+    OPT_DEFS += -DSOLENOID_ENABLE
+endif
+
+ifeq ($(strip $(HD44780_ENABLE)), yes)
+    SRC += drivers/avr/hd44780.c
+    OPT_DEFS += -DHD44780_ENABLE
+endif
+
 ifeq ($(strip $(OLED_DRIVER_ENABLE)), yes)
     OPT_DEFS += -DOLED_DRIVER_ENABLE
     COMMON_VPATH += $(DRIVER_PATH)/oled
@@ -501,10 +442,34 @@ ifeq ($(strip $(OLED_DRIVER_ENABLE)), yes)
     SRC += oled_driver.c
 endif
 
+include $(DRIVER_PATH)/qwiic/qwiic.mk
+
+ifeq ($(strip $(UCIS_ENABLE)), yes)
+    OPT_DEFS += -DUCIS_ENABLE
+    UNICODE_COMMON := yes
+    SRC += $(QUANTUM_DIR)/process_keycode/process_ucis.c
+endif
+
+ifeq ($(strip $(UNICODEMAP_ENABLE)), yes)
+    OPT_DEFS += -DUNICODEMAP_ENABLE
+    UNICODE_COMMON := yes
+    SRC += $(QUANTUM_DIR)/process_keycode/process_unicodemap.c
+endif
+
+ifeq ($(strip $(UNICODE_ENABLE)), yes)
+    OPT_DEFS += -DUNICODE_ENABLE
+    UNICODE_COMMON := yes
+    SRC += $(QUANTUM_DIR)/process_keycode/process_unicode.c
+endif
+
+ifeq ($(strip $(UNICODE_COMMON)), yes)
+    SRC += $(QUANTUM_DIR)/process_keycode/process_unicode_common.c
+endif
+
 SPACE_CADET_ENABLE ?= yes
 ifeq ($(strip $(SPACE_CADET_ENABLE)), yes)
-  SRC += $(QUANTUM_DIR)/process_keycode/process_space_cadet.c
-  OPT_DEFS += -DSPACE_CADET_ENABLE
+    SRC += $(QUANTUM_DIR)/process_keycode/process_space_cadet.c
+    OPT_DEFS += -DSPACE_CADET_ENABLE
 endif
 
 MAGIC_ENABLE ?= yes
@@ -523,3 +488,31 @@ ifeq ($(strip $(DYNAMIC_MACRO_ENABLE)), yes)
     SRC += $(QUANTUM_DIR)/process_keycode/process_dynamic_macro.c
     OPT_DEFS += -DDYNAMIC_MACRO_ENABLE
 endif
+
+ifeq ($(strip $(COMBO_ENABLE)), yes)
+    SRC += $(QUANTUM_DIR)/process_keycode/process_combo.c
+    OPT_DEFS += -DCOMBO_ENABLE
+endif
+
+ifeq ($(strip $(TAP_DANCE_ENABLE)), yes)
+    SRC += $(QUANTUM_DIR)/process_keycode/process_tap_dance.c
+    OPT_DEFS += -DTAP_DANCE_ENABLE
+endif
+
+ifeq ($(strip $(KEY_LOCK_ENABLE)), yes)
+    SRC += $(QUANTUM_DIR)/process_keycode/process_key_lock.c
+    OPT_DEFS += -DKEY_LOCK_ENABLE
+endif
+
+ifeq ($(strip $(LEADER_ENABLE)), yes)
+    SRC += $(QUANTUM_DIR)/process_keycode/process_leader.c
+    OPT_DEFS += -DLEADER_ENABLE
+endif
+
+ifeq ($(strip $(AUTO_SHIFT_ENABLE)), yes)
+    SRC += $(QUANTUM_DIR)/process_keycode/process_auto_shift.c
+    OPT_DEFS += -DAUTO_SHIFT_ENABLE
+    ifeq ($(strip $(AUTO_SHIFT_MODIFIERS)), yes)
+        OPT_DEFS += -DAUTO_SHIFT_MODIFIERS
+    endif
+endif

docs/_summary.md

@@ -52,7 +52,7 @@
   * Simple Keycodes
     * [Full List](keycodes.md)
     * [Basic Keycodes](keycodes_basic.md)
-    * [Layer Switching](feature_advanced_keycodes.md)
+    * [Modifier Keys](feature_advanced_keycodes.md)
     * [Quantum Keycodes](quantum_keycodes.md)
 
   * Advanced Keycodes
@@ -71,6 +71,7 @@
     * [Combos](feature_combo.md)
     * [Debounce API](feature_debounce_type.md)
     * [Key Lock](feature_key_lock.md)
+    * [Layers](feature_layers.md)
     * [One Shot Keys](one_shot_keys.md)
     * [Pointing Device](feature_pointing_device.md)
     * [Swap Hands](feature_swap_hands.md)
@@ -79,6 +80,7 @@
     * [Terminal](feature_terminal.md)
     * [Unicode](feature_unicode.md)
     * [Userspace](feature_userspace.md)
+    * [WPM Calculation](feature_wpm.md)
 
   * Hardware Features
     * Displays
@@ -119,6 +121,7 @@
     * [Drivers](hardware_drivers.md)
       * [ADC Driver](adc_driver.md)
       * [I2C Driver](i2c_driver.md)
+      * [SPI Driver](spi_driver.md)
       * [WS2812 Driver](ws2812_driver.md)
       * [EEPROM Driver](eeprom_driver.md)
     * [GPIO Controls](internals_gpio_control.md)
@@ -133,6 +136,10 @@
       * [Development Environment](api_development_environment.md)
       * [Architecture Overview](api_development_overview.md)
 
+  * Hardware Platform Development
+    * Arm/ChibiOS
+      * [Early initialization](platformdev_chibios_earlyinit.md)
+
   * QMK Reference
     * [Contributing to QMK](contributing.md)
     * [Translating the QMK Docs](translating.md)

docs/adc_driver.md

@@ -2,7 +2,7 @@
 
 QMK can leverage the Analog-to-Digital Converter (ADC) on supported MCUs to measure voltages on certain pins. This can be useful for implementing things such as battery level indicators for Bluetooth keyboards, or volume controls using a potentiometer, as opposed to a [rotary encoder](feature_encoders.md).
 
-This driver currently supports both AVR and a limited selection of ARM devices. On AVR devices, the values returned are 10-bit integers (0-1023) mapped between 0V and VCC (usually 5V or 3.3V). On supported ARM devices, there is more flexibility in control of operation through `#define`s, but by default the values returned are 12-bit integers (0-4095) mapped between 0V and VCC (usually 3.3V).
+This driver currently supports both AVR and a limited selection of ARM devices. The values returned are 10-bit integers (0-1023) mapped between 0V and VCC (usually 5V or 3.3V for AVR, 3.3V only for ARM), however on ARM there is more flexibility in control of operation through `#define`s if you need more precision.
 
 ## Usage
 

docs/cli.md

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

docs/cli_commands.md

@@ -1,38 +1,6 @@
 # QMK CLI Commands
 
-# CLI Commands
-
-## `qmk cformat`
-
-This command formats C code using clang-format. 
-
-Run it with no arguments to format all core code that has been changed. Default checks `origin/master` with `git diff`, branch can be changed using `-b <branch_name>`
-
-Run it with `-a` to format all core code, or pass filenames on the command line to run it on specific files.
-
-**Usage for specified files**:
-
-```
-qmk cformat [file1] [file2] [...] [fileN]
-```
-
-**Usage for all core files**:
-
-```
-qmk cformat -a
-```
-
-**Usage for only changed files against origin/master**:
-
-```
-qmk cformat
-```
-
-**Usage for only changed files against branch_name**:
-
-```
-qmk cformat -b branch_name
-```
+# User Commands
 
 ## `qmk compile`
 
@@ -136,16 +104,6 @@ This command lets you configure the behavior of QMK. For the full `qmk config` d
 qmk config [-ro] [config_token1] [config_token2] [...] [config_tokenN]
 ```
 
-## `qmk docs`
-
-This command starts a local HTTP server which you can use for browsing or improving the docs. Default port is 8936.
-
-**Usage**:
-
-```
-qmk docs [-p PORT]
-```
-
 ## `qmk doctor`
 
 This command examines your environment and alerts you to potential build or flash problems. It can fix many of them if you want it to.
@@ -180,28 +138,6 @@ Creates a keymap.c from a QMK Configurator export.
 qmk json2c [-o OUTPUT] filename
 ```
 
-## `qmk kle2json`
-
-This command allows you to convert from raw KLE data to QMK Configurator JSON. It accepts either an absolute file path, or a file name in the current directory. By default it will not overwrite `info.json` if it is already present. Use the `-f` or `--force` flag to overwrite.
-
-**Usage**:
-
-```
-qmk kle2json [-f] <filename>
-```
-
-**Examples**:
-
-```
-$ qmk kle2json kle.txt 
-☒ File info.json already exists, use -f or --force to overwrite.
-```
-
-```
-$ qmk kle2json -f kle.txt -f
-Ψ Wrote out to info.json
-```
-
 ## `qmk list-keyboards`
 
 This command lists all the keyboards currently defined in `qmk_firmware`
@@ -232,6 +168,74 @@ This command creates a new keymap based on a keyboard's existing default keymap.
 qmk new-keymap [-kb KEYBOARD] [-km KEYMAP]
 ```
 
+---
+
+# Developer Commands
+
+## `qmk cformat`
+
+This command formats C code using clang-format. 
+
+Run it with no arguments to format all core code that has been changed. Default checks `origin/master` with `git diff`, branch can be changed using `-b <branch_name>`
+
+Run it with `-a` to format all core code, or pass filenames on the command line to run it on specific files.
+
+**Usage for specified files**:
+
+```
+qmk cformat [file1] [file2] [...] [fileN]
+```
+
+**Usage for all core files**:
+
+```
+qmk cformat -a
+```
+
+**Usage for only changed files against origin/master**:
+
+```
+qmk cformat
+```
+
+**Usage for only changed files against branch_name**:
+
+```
+qmk cformat -b branch_name
+```
+
+## `qmk docs`
+
+This command starts a local HTTP server which you can use for browsing or improving the docs. Default port is 8936.
+
+**Usage**:
+
+```
+qmk docs [-p PORT]
+```
+
+## `qmk kle2json`
+
+This command allows you to convert from raw KLE data to QMK Configurator JSON. It accepts either an absolute file path, or a file name in the current directory. By default it will not overwrite `info.json` if it is already present. Use the `-f` or `--force` flag to overwrite.
+
+**Usage**:
+
+```
+qmk kle2json [-f] <filename>
+```
+
+**Examples**:
+
+```
+$ qmk kle2json kle.txt 
+☒ File info.json already exists, use -f or --force to overwrite.
+```
+
+```
+$ qmk kle2json -f kle.txt -f
+Ψ Wrote out to info.json
+```
+
 ## `qmk pyformat`
 
 This command formats python code in `qmk_firmware`.
@@ -251,3 +255,4 @@ This command runs the python test suite. If you make changes to python code you
 ```
 qmk pytest
 ```
+

docs/cli_development.md

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

docs/coding_conventions_c.md

@@ -20,11 +20,11 @@ Most of our style is pretty easy to pick up on, but right now it's not entirely
 * We accept both forms of preprocessor if's: `#ifdef DEFINED` and `#if defined(DEFINED)`
   * If you are not sure which to prefer use the `#if defined(DEFINED)` form.
   * Do not change existing code from one style to the other, except when moving to a multiple condition `#if`.
-  * Do not put whitespace between `#` and `if`.
-  * When deciding how (or if) to indent directives keep these points in mind:
-    * Readability is more important than consistency.
-    * Follow the file's existing style. If the file is mixed follow the style that makes sense for the section you are modifying.
-    * When choosing to indent you can follow the indention level of the surrounding C code, or preprocessor directives can have their own indent level. Choose the style that best communicates the intent of your code.
+* When deciding how (or if) to indent preprocessor directives, keep these points in mind:
+  * Readability is more important than consistency.
+  * Follow the file's existing style. If the file is mixed, follow the style that makes sense for the section you are modifying.
+  * When indenting, keep the hash at the start of the line and add whitespace between `#` and `if`, starting with 4 spaces after the `#`.
+  * You can follow the indention level of the surrounding C code, or preprocessor directives can have their own indentation levels. Choose the style that best communicates the intent of your code.
 
 Here is an example for easy reference:
 

docs/coding_conventions_python.md

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

docs/config_options.md

@@ -115,9 +115,9 @@ If you define these options you will disable the associated feature, which can s
 * `#define NO_ACTION_ONESHOT`
   * disable one-shot modifiers
 * `#define NO_ACTION_MACRO`
-  * disable old style macro handling: MACRO() & action_get_macro
+  * disable old-style macro handling using `MACRO()`, `action_get_macro()` _(deprecated)_
 * `#define NO_ACTION_FUNCTION`
-  * disable calling of action_function() from the fn_actions array (deprecated)
+  * disable old-style function handling using `fn_actions`, `action_function()` _(deprecated)_
 
 ## Features That Can Be Enabled
 
@@ -317,10 +317,10 @@ This is a [make](https://www.gnu.org/software/make/manual/make.html) file that i
 * `LAYOUTS`
   * A list of [layouts](feature_layouts.md) this keyboard supports.
 * `LINK_TIME_OPTIMIZATION_ENABLE`
-  * Enables Link Time Optimization (`LTO`) when compiling the keyboard.  This makes the process take longer, but can significantly reduce the compiled size (and since the firmware is small, the added time is not noticeable).  However, this will automatically disable the old Macros and Functions features automatically, as these break when `LTO` is enabled.
-  It does this by automatically defining `NO_ACTION_MACRO` and `NO_ACTION_FUNCTION`
+  * Enables Link Time Optimization (LTO) when compiling the keyboard.  This makes the process take longer, but it can significantly reduce the compiled size (and since the firmware is small, the added time is not noticeable).
+However, this will automatically disable the legacy TMK Macros and Functions features, as these break when LTO is enabled.  It does this by automatically defining `NO_ACTION_MACRO` and `NO_ACTION_FUNCTION`.  (Note: This does not affect QMK [Macros](feature_macros.md) and [Layers](feature_layers.md).)
 * `LTO_ENABLE`
-  * It has the same meaning as LINK_TIME_OPTIMIZATION_ENABLE.  You can use `LTO_ENABLE` instead of `LINK_TIME_OPTIMIZATION_ENABLE`.
+  * Has the same meaning as `LINK_TIME_OPTIMIZATION_ENABLE`.  You can use `LTO_ENABLE` instead of `LINK_TIME_OPTIMIZATION_ENABLE`.
 
 ## AVR MCU Options
 * `MCU = atmega32u4`

docs/de/_summary.md

@@ -98,6 +98,7 @@
   * [ISP Flashing Guide](de/isp_flashing_guide.md)
   * [ARM Debugging Guide](de/arm_debugging.md)
   * [I2C Driver](de/i2c_driver.md)
+  * [SPI Driver](de/spi_driver.md)
   * [GPIO Controls](de/internals_gpio_control.md)
   * [Proton C Conversion](de/proton_c_conversion.md)
 

docs/es/_summary.md

@@ -98,6 +98,7 @@
   * [Guía de flasheado de ISP](es/isp_flashing_guide.md)
   * [Guía de depuración de ARM](es/arm_debugging.md)
   * [Driver I2C](es/i2c_driver.md)
+  * [Driver SPI](es/spi_driver.md)
   * [Controles GPIO](es/internals_gpio_control.md)
   * [Conversión Proton C](es/proton_c_conversion.md)
 

docs/faq_debug.md

@@ -160,10 +160,3 @@ As of now root of its cause is not clear but some build options seem to be relat
 
 https://github.com/tmk/tmk_keyboard/issues/266
 https://geekhack.org/index.php?topic=41989.msg1967778#msg1967778
-
-
-
-## FLIP Doesn't Work
-### `AtLibUsbDfu.dll` Not Found
-Remove current driver and reinstall one FLIP provides from DeviceManager.
-http://imgur.com/a/bnwzy

docs/feature_advanced_keycodes.md

@@ -1,46 +1,3 @@
-# Switching and Toggling Layers :id=switching-and-toggling-layers
-
-These functions allow you to activate layers in various ways. Note that layers are not generally independent layouts -- multiple layers can be activated at once, and it's typical for layers to use `KC_TRNS` to allow keypresses to pass through to lower layers. For a detailed explanation of layers, see [Keymap Overview](keymap.md#keymap-and-layers). When using momentary layer switching with MO(), LM(), TT(), or LT(), make sure to leave the key on the above layers transparent or it may not work as intended.
-
-* `DF(layer)` - switches the default layer. The default layer is the always-active base layer that other layers stack on top of. See below for more about the default layer. This might be used to switch from QWERTY to Dvorak layout. (Note that this is a temporary switch that only persists until the keyboard loses power. To modify the default layer in a persistent way requires deeper customization, such as calling the `set_single_persistent_default_layer` function inside of [process_record_user](custom_quantum_functions.md#programming-the-behavior-of-any-keycode).)
-* `MO(layer)` - momentarily activates *layer*. As soon as you let go of the key, the layer is deactivated. 
-* `LM(layer, mod)` - Momentarily activates *layer* (like `MO`), but with modifier(s) *mod* active. Only supports layers 0-15 and the left modifiers: `MOD_LCTL`, `MOD_LSFT`, `MOD_LALT`, `MOD_LGUI` (note the use of `MOD_` constants instead of `KC_`). These modifiers can be combined using bitwise OR, e.g. `LM(_RAISE, MOD_LCTL | MOD_LALT)`.
-* `LT(layer, kc)` - momentarily activates *layer* when held, and sends *kc* when tapped. Only supports layers 0-15.
-* `OSL(layer)` - momentarily activates *layer* until the next key is pressed. See [One Shot Keys](one_shot_keys.md) for details and additional functionality.
-* `TG(layer)` - toggles *layer*, activating it if it's inactive and vice versa
-* `TO(layer)` - activates *layer* and de-activates all other layers (except your default layer). This function is special, because instead of just adding/removing one layer to your active layer stack, it will completely replace your current active layers, uniquely allowing you to replace higher layers with a lower one. This is activated on keydown (as soon as the key is pressed).
-* `TT(layer)` - Layer Tap-Toggle. If you hold the key down, *layer* is activated, and then is de-activated when you let go (like `MO`). If you repeatedly tap it, the layer will be toggled on or off (like `TG`). It needs 5 taps by default, but you can change this by defining `TAPPING_TOGGLE` -- for example, `#define TAPPING_TOGGLE 2` to toggle on just two taps.
-
-## Caveats
-
-Currently, `LT()` and `MT()` are limited to the [Basic Keycode set](keycodes_basic.md), meaning you can't use keycodes like `LCTL()`, `KC_TILD`, or anything greater than `0xFF`. Modifiers specified as part of a Layer Tap or Mod Tap's keycode will be ignored. If you need to apply modifiers to your tapped keycode, [Tap Dance](feature_tap_dance.md#example-5-using-tap-dance-for-advanced-mod-tap-and-layer-tap-keys) can be used to accomplish this.
-
-Additionally, if at least one right-handed modifier is specified in a Mod Tap or Layer Tap, it will cause all modifiers specified to become right-handed, so it is not possible to mix and match the two.
-
-# Working with Layers
-
-Care must be taken when switching layers, it's possible to lock yourself into a layer with no way to deactivate that layer (without unplugging your keyboard.) We've created some guidelines to help users avoid the most common problems.
-
-## Beginners
-
-If you are just getting started with QMK you will want to keep everything simple. Follow these guidelines when setting up your layers:
-
-* Setup layer 0 as your default, "base" layer. This is your normal typing layer, and could be whatever layout you want (qwerty, dvorak, colemak, etc.). It's important to set this as the lowest layer since it will typically have most or all of the keyboard's keys defined, so would block other layers from having any effect if it were above them (i.e., had a higher layer number). 
-* Arrange your layers in a "tree" layout, with layer 0 as the root. Do not try to enter the same layer from more than one other layer.
-* In a layer's keymap, only reference higher-numbered layers. Because layers are processed from the highest-numbered (topmost) active layer down, modifying the state of lower layers can be tricky and error-prone.
-
-## Intermediate Users
-
-Sometimes you need more than one base layer. For example, if you want to switch between QWERTY and Dvorak, switch between layouts for different countries, or switch your layout for different videogames. Your base layers should always be the lowest numbered layers. When you have multiple base layers you should always treat them as mutually exclusive. When one base layer is on the others are off.
-
-## Advanced Users
-
-Once you have a good feel for how layers work and what you can do, you can get more creative. The rules listed in the beginner section will help you be successful by avoiding some of the tricker details but they can be constraining, especially for ultra-compact keyboard users. Understanding how layers work will allow you to use them in more advanced ways.
-
-Layers stack on top of each other in numerical order. When determining what a keypress does, QMK scans the layers from the top down, stopping when it reaches the first active layer that is not set to `KC_TRNS`. As a result if you activate a layer that is numerically lower than your current layer, and your current layer (or another layer that is active and higher than your target layer) has something other than `KC_TRNS`, that is the key that will be sent, not the key on the layer you just activated. This is the cause of most people's "why doesn't my layer get switched" problem.
-
-Sometimes, you might want to switch between layers in a macro or as part of a tap dance routine. `layer_on` activates a layer, and `layer_off` deactivates it. More layer-related functions can be found in [action_layer.h](https://github.com/qmk/qmk_firmware/blob/master/tmk_core/common/action_layer.h).
-
 # Modifier Keys :id=modifier-keys
 
 These allow you to combine a modifier with a keycode. When pressed, the keydown event for the modifier, then `kc` will be sent. On release, the keyup event for `kc`, then the modifier will be sent.
@@ -49,11 +6,11 @@ These allow you to combine a modifier with a keycode. When pressed, the keydown
 |----------|-------------------------------|----------------------------------------------------|
 |`LCTL(kc)`|`C(kc)`                        |Hold Left Control and press `kc`                    |
 |`LSFT(kc)`|`S(kc)`                        |Hold Left Shift and press `kc`                      |
-|`LALT(kc)`|`A(kc)`                        |Hold Left Alt and press `kc`                        |
+|`LALT(kc)`|`A(kc)`, `LOPT(kc)`            |Hold Left Alt and press `kc`                        |
 |`LGUI(kc)`|`G(kc)`, `LCMD(kc)`, `LWIN(kc)`|Hold Left GUI and press `kc`                        |
 |`RCTL(kc)`|                               |Hold Right Control and press `kc`                   |
 |`RSFT(kc)`|                               |Hold Right Shift and press `kc`                     |
-|`RALT(kc)`|`ALGR(kc)`                     |Hold Right Alt and press `kc`                       |
+|`RALT(kc)`|`ROPT(kc)`, `ALGR(kc)`         |Hold Right Alt and press `kc`                       |
 |`RGUI(kc)`|`RCMD(kc)`, `LWIN(kc)`         |Hold Right GUI and press `kc`                       |
 |`SGUI(kc)`|`SCMD(kc)`, `SWIN(kc)`         |Hold Left Shift and GUI and press `kc`              |
 |`LCA(kc)` |                               |Hold Left Control and Alt and press `kc`            |
@@ -61,12 +18,16 @@ These allow you to combine a modifier with a keycode. When pressed, the keydown
 |`MEH(kc)` |                               |Hold Left Control, Shift and Alt and press `kc`     |
 |`HYPR(kc)`|                               |Hold Left Control, Shift, Alt and GUI and press `kc`|
 
-You can also chain them, for example `LCTL(LALT(KC_DEL))` makes a key that sends Control+Alt+Delete with a single keypress.
+You can also chain them, for example `LCTL(LALT(KC_DEL))` or `C(A(KC_DEL))` makes a key that sends Control+Alt+Delete with a single keypress.
 
-# Legacy Content
+# Legacy Content :id=legacy-content
 
 This page used to encompass a large set of features. We have moved many sections that used to be part of this page to their own pages. Everything below this point is simply a redirect so that people following old links on the web find what they're looking for.
 
+## Layers :id=switching-and-toggling-layers
+
+* [Layers](feature_layers.md)
+
 ## Mod-Tap :id=mod-tap
 
 * [Mod-Tap](mod_tap.md)

docs/feature_bootmagic.md

@@ -123,7 +123,7 @@ If you would like to change the hotkey assignments for Bootmagic, `#define` thes
 
 # Bootmagic Lite :id=bootmagic-lite
 
-In addition to the full blown Bootmagic feature, is the Bootmagic Lite feature that only handles jumping into the bootloader.  This is great for boards that don't have a physical reset button but you need a way to jump into the bootloader, and don't want to deal with the headache that Bootmagic can cause.
+In addition to the full blown Bootmagic feature, is the Bootmagic Lite feature that only handles jumping into the bootloader. This is great for boards that don't have a physical reset button but you need a way to jump into the bootloader, and don't want to deal with the headache that Bootmagic can cause.
 
 To enable this version of Bootmagic, you need to enable it in your `rules.mk` with:
 
@@ -131,7 +131,7 @@ To enable this version of Bootmagic, you need to enable it in your `rules.mk` wi
 BOOTMAGIC_ENABLE = lite
 ```
 
-Additionally, you may want to specify which key to use.  This is especially useful for keyboards that have unusual matrices.  To do so, you need to specify the row and column of the key that you want to use. Add these entries to your `config.h` file:
+Additionally, you may want to specify which key to use. This is especially useful for keyboards that have unusual matrices. To do so, you need to specify the row and column of the key that you want to use. Add these entries to your `config.h` file:
 
 ```c
 #define BOOTMAGIC_LITE_ROW 0
@@ -144,9 +144,20 @@ And to trigger the bootloader, you hold this key down when plugging the keyboard
 
 !> Using bootmagic lite will **always reset** the EEPROM, so you will lose any settings that have been saved.
 
+## Split Keyboards
+
+When handedness is predetermined via an option like `SPLIT_HAND_PIN`, you might need to configure a different key between halves. This To do so, add these entries to your `config.h` file:
+
+```c
+#define BOOTMAGIC_LITE_ROW_RIGHT 4
+#define BOOTMAGIC_LITE_COLUMN_RIGHT 1
+```
+
+By default, these values are not set.
+
 ## Advanced Bootmagic Lite
 
-The `bootmagic_lite` function is defined weakly, so that you can replace this in your code, if you need.  A great example of this is the Zeal60 boards that have some additional handling needed.
+The `bootmagic_lite` function is defined weakly, so that you can replace this in your code, if you need. A great example of this is the Zeal60 boards that have some additional handling needed.
 
 To replace the function, all you need to do is add something like this to your code:
 
@@ -163,4 +174,4 @@ void bootmagic_lite(void) {
 }
 ```
 
-You can additional feature here. For instance, resetting the eeprom or requiring additional keys to be pressed to trigger bootmagic.  Keep in mind that `bootmagic_lite` is called before a majority of features are initialized in the firmware.
+You can additional feature here. For instance, resetting the eeprom or requiring additional keys to be pressed to trigger bootmagic. Keep in mind that `bootmagic_lite` is called before a majority of features are initialized in the firmware.

docs/feature_debounce_type.md

@@ -38,5 +38,6 @@ For use in keyboards where refreshing ```NUM_KEYS``` 8-bit counters is computati
 appropriate for the ErgoDox models; the matrix is rotated 90°, and hence its "rows" are really columns, and each finger only hits a single "row" at a time in normal use.
 * eager_pk - debouncing per key. On any state change, response is immediate, followed by ```DEBOUNCE``` milliseconds of no further input for that key
 * sym_g - debouncing per keyboard. On any state change, a global timer is set. When ```DEBOUNCE``` milliseconds of no changes has occured, all input changes are pushed.
+* sym_pk - debouncing per key. On any state change, a per-key timer is set. When ```DEBOUNCE``` milliseconds of no changes have occured on that key, the key status change is pushed.
 
 

docs/feature_layers.md

@@ -0,0 +1,94 @@
+# Layers :id=layers
+
+One of the most powerful and well used features of QMK Firmware is the ability to use layers.  For most people, this amounts to a function key that allows for different keys, much like what you would see on a laptop or tablet keyboard. 
+
+For a detailed explanation of how the layer stack works, checkout [Keymap Overview](keymap.md#keymap-and-layers).
+
+## Switching and Toggling Layers :id=switching-and-toggling-layers
+
+These functions allow you to activate layers in various ways. Note that layers are not generally independent layouts -- multiple layers can be activated at once, and it's typical for layers to use `KC_TRNS` to allow keypresses to pass through to lower layers. When using momentary layer switching with MO(), LM(), TT(), or LT(), make sure to leave the key on the above layers transparent or it may not work as intended.
+
+* `DF(layer)` - switches the default layer. The default layer is the always-active base layer that other layers stack on top of. See below for more about the default layer. This might be used to switch from QWERTY to Dvorak layout. (Note that this is a temporary switch that only persists until the keyboard loses power. To modify the default layer in a persistent way requires deeper customization, such as calling the `set_single_persistent_default_layer` function inside of [process_record_user](custom_quantum_functions.md#programming-the-behavior-of-any-keycode).)
+* `MO(layer)` - momentarily activates *layer*. As soon as you let go of the key, the layer is deactivated. 
+* `LM(layer, mod)` - Momentarily activates *layer* (like `MO`), but with modifier(s) *mod* active. Only supports layers 0-15 and the left modifiers: `MOD_LCTL`, `MOD_LSFT`, `MOD_LALT`, `MOD_LGUI` (note the use of `MOD_` constants instead of `KC_`). These modifiers can be combined using bitwise OR, e.g. `LM(_RAISE, MOD_LCTL | MOD_LALT)`.
+* `LT(layer, kc)` - momentarily activates *layer* when held, and sends *kc* when tapped. Only supports layers 0-15.
+* `OSL(layer)` - momentarily activates *layer* until the next key is pressed. See [One Shot Keys](one_shot_keys.md) for details and additional functionality.
+* `TG(layer)` - toggles *layer*, activating it if it's inactive and vice versa
+* `TO(layer)` - activates *layer* and de-activates all other layers (except your default layer). This function is special, because instead of just adding/removing one layer to your active layer stack, it will completely replace your current active layers, uniquely allowing you to replace higher layers with a lower one. This is activated on keydown (as soon as the key is pressed).
+* `TT(layer)` - Layer Tap-Toggle. If you hold the key down, *layer* is activated, and then is de-activated when you let go (like `MO`). If you repeatedly tap it, the layer will be toggled on or off (like `TG`). It needs 5 taps by default, but you can change this by defining `TAPPING_TOGGLE` -- for example, `#define TAPPING_TOGGLE 2` to toggle on just two taps.
+
+### Caveats :id=caveats
+
+Currently, `LT()` and `MT()` are limited to the [Basic Keycode set](keycodes_basic.md), meaning you can't use keycodes like `LCTL()`, `KC_TILD`, or anything greater than `0xFF`. Specifically, dual function keys like `LT` and `MT` use a 16 bit keycode. 4 bits are used for the function identifier, the next 12 are divided into the parameters. Layer Tap uses 4 bits for the layer (and is why it's limited to layers 0-16, actually), while Mod Tap does the same, 4 bits for the identifier, 4 bits for which mods are used, and all of them use 8 bits for the keycode. Because of this, the keycode used is limited to `0xFF` (0-255), which are the basic keycodes only. 
+
+Expanding this would be complicated, at best. Moving to a 32-bit keycode would solve a lot of this, but would double the amount of space that the keymap matrix uses. And it could potentially cause issues, too. If you need to apply modifiers to your tapped keycode, [Tap Dance](feature_tap_dance.md#example-5-using-tap-dance-for-advanced-mod-tap-and-layer-tap-keys) can be used to accomplish this.
+
+Additionally, if at least one right-handed modifier is specified in a Mod Tap or Layer Tap, it will cause all modifiers specified to become right-handed, so it is not possible to mix and match the two.
+
+## Working with Layers :id=working-with-layers
+
+Care must be taken when switching layers, it's possible to lock yourself into a layer with no way to deactivate that layer (without unplugging your keyboard.) We've created some guidelines to help users avoid the most common problems.
+
+### Beginners :id=beginners
+
+If you are just getting started with QMK you will want to keep everything simple. Follow these guidelines when setting up your layers:
+
+* Setup layer 0 as your default, "base" layer. This is your normal typing layer, and could be whatever layout you want (qwerty, dvorak, colemak, etc.). It's important to set this as the lowest layer since it will typically have most or all of the keyboard's keys defined, so would block other layers from having any effect if it were above them (i.e., had a higher layer number). 
+* Arrange your layers in a "tree" layout, with layer 0 as the root. Do not try to enter the same layer from more than one other layer.
+* In a layer's keymap, only reference higher-numbered layers. Because layers are processed from the highest-numbered (topmost) active layer down, modifying the state of lower layers can be tricky and error-prone.
+
+### Intermediate Users :id=intermediate-users
+
+Sometimes you need more than one base layer. For example, if you want to switch between QWERTY and Dvorak, switch between layouts for different countries, or switch your layout for different videogames. Your base layers should always be the lowest numbered layers. When you have multiple base layers you should always treat them as mutually exclusive. When one base layer is on the others are off.
+
+### Advanced Users :id=advanced-users
+
+Once you have a good feel for how layers work and what you can do, you can get more creative. The rules listed in the beginner section will help you be successful by avoiding some of the tricker details but they can be constraining, especially for ultra-compact keyboard users. Understanding how layers work will allow you to use them in more advanced ways.
+
+Layers stack on top of each other in numerical order. When determining what a keypress does, QMK scans the layers from the top down, stopping when it reaches the first active layer that is not set to `KC_TRNS`. As a result if you activate a layer that is numerically lower than your current layer, and your current layer (or another layer that is active and higher than your target layer) has something other than `KC_TRNS`, that is the key that will be sent, not the key on the layer you just activated. This is the cause of most people's "why doesn't my layer get switched" problem.
+
+Sometimes, you might want to switch between layers in a macro or as part of a tap dance routine. `layer_on` activates a layer, and `layer_off` deactivates it. More layer-related functions can be found in [action_layer.h](https://github.com/qmk/qmk_firmware/blob/master/tmk_core/common/action_layer.h).
+
+## Functions :id=functions
+
+There are a number of functions (and variables) related to how you can use or manipulate the layers.
+
+|Function                                      |Description                                                                                              |
+|----------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| `layer_state_set(layer_mask)`                | Directly sets the layer state (recommended, do not use unless you know what you are doing).             |
+| `layer_clear()`                              | Clears all layers (turns them all off).                                                                 |
+| `layer_move(layer)`                          | Turns specified layer on, and all other layers off.                                                     |
+| `layer_on(layer)`                            | Turns specified layer on, leaves all other layers in existing state.                                    |
+| `layer_off(layer)`                           | Turns specified layer off, leaves all other layers in existing state.                                   |
+| `layer_invert(layer)`                        | Interverts/toggles the state of the specified layer                                                     |
+| `layer_or(layer_mask)`                       | Turns on layers based on matching bits between specifed layer and existing layer state.                 |
+| `layer_and(layer_mask)`                      | Turns on layers based on matching enabled bits between specifed layer and existing layer state.         |
+| `layer_xor(layer_mask)`                      | Turns on layers based on non-matching bits between specifed layer and existing layer state.             |
+| `layer_debug(layer_mask)`                    | Prints out the current bit mask and highest active layer to debugger console.                           |
+| `default_layer_set(layer_mask)`              | Directly sets the default layer state (recommended, do not use unless you know what you are doing).     |
+| `default_layer_or(layer_mask)`               | Turns on layers based on matching bits between specifed layer and existing default layer state.         |
+| `default_layer_and(layer_mask)`              | Turns on layers based on matching enabled bits between specifed layer and existing default layer state. |
+| `default_layer_xor(layer_mask)`              | Turns on layers based on non-matching bits between specifed layer and existing default layer state.     |
+| `default_layer_debug(layer_mask)`            | Prints out the current bit mask and highest active default layer to debugger console.                   |
+| [`set_single_persistent_default_layer(layer)`](ref_functions.md#setting-the-persistent-default-layer) | Sets the default layer and writes it to persistent memory (EEPROM).  |
+| [`update_tri_layer(x, y, z)`](ref_functions.md#update_tri_layerx-y-z) | Checks if layers `x` and `y` are both on, and sets `z` based on that (on if both on, otherwise off). |
+| [`update_tri_layer_state(state, x, y, z)`](ref_functions.md#update_tri_layer_statestate-x-y-z) | Does the same as `update_tri_layer(x, y, z)`, but from `layer_state_set_*` functions. |
+
+
+In additional to the functions that you can call, there are a number of callback functions that get called every time the layer changes. This passed the layer state to the function, which can be read or modified.
+
+|Callbacks                                     |Description                                                                                    |
+|-----------------------------------------------------|----------------------------------------------------------------------------------------|
+| `layer_state_set_kb(layer_state_t state)`           | Callback for layer functions, for keyboard.                                            |
+| `layer_state_set_user(layer_state_t state)`         | Callback for layer functions, for users.                                               |
+| `default_layer_state_set_kb(layer_state_t state)`   | Callback for default layer functions, for keyboard. Called on keyboard initialization. |
+| `default_layer_state_set_user(layer_state_t state)` | Callback for default layer functions, for users. Called on keyboard initialization.    |
+
+?> For additional details on how you can use these callbacks, check out the [Layer Change Code](custom_quantum_functions.md#layer-change-code) document.
+
+|Check functions                                                  |Description                                                                   |
+|-------------------------------------------|------------------------------------------------------------------------------|
+| `layer_state_cmp(cmp_layer_state, layer)` | This checks the `cmp_layer_state` to see if the specific `layer` is enabled. This is meant for use with the layer callbacks. |
+| `layer_state_is(layer)`                   | This checks the layer state to see if the specific `layer` is enabled. (calls `layer_state_cmp` for the global layer state). |
+
+!> There is `IS_LAYER_ON(layer)` as well, however the `layer_state_cmp` function has some additional handling to ensure that on layer 0 that it returns the correct value. Otherwise, if you check to see if layer 0 is on, you may get an incorrect value returned. 

docs/feature_leader_key.md

@@ -74,9 +74,9 @@ SEQ_THREE_KEYS(KC_C, KC_C, KC_C) {
 
 ## Strict Key Processing
 
-By default, the Leader Key feature will filter the keycode out of [`Mod-Tap`](mod_tap.md) and [`Layer Tap`](feature_advanced_keycodes.md#switching-and-toggling-layers) functions when checking for the Leader sequences. That means if you're using `LT(3, KC_A)`, it will pick this up as `KC_A` for the sequence, rather than `LT(3, KC_A)`, giving a more expected behavior for newer users.
+By default, the Leader Key feature will filter the keycode out of [`Mod-Tap`](mod_tap.md) and [`Layer Tap`](feature_layers.md#switching-and-toggling-layers) functions when checking for the Leader sequences. That means if you're using `LT(3, KC_A)`, it will pick this up as `KC_A` for the sequence, rather than `LT(3, KC_A)`, giving a more expected behavior for newer users.
 
-While, this may be fine for most, if you want to specify the whole keycode (eg, `LT(3, KC_A)` from the example above) in the sequence, you can enable this by added `#define LEADER_KEY_STRICT_KEY_PROCESSING` to your `config.h` file.  This well then disable the filtering, and you'll need to specify the whole keycode.
+While, this may be fine for most, if you want to specify the whole keycode (eg, `LT(3, KC_A)` from the example above) in the sequence, you can enable this by added `#define LEADER_KEY_STRICT_KEY_PROCESSING` to your `config.h` file.  This will then disable the filtering, and you'll need to specify the whole keycode.
 
 ## Customization 
 

docs/feature_macros.md

@@ -88,6 +88,46 @@ const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
 };
 ```
 
+### Advanced Macros
+
+In addition to the `process_record_user()` function, is the `post_process_record_user()` function. This runs after `process_record` and can be used to do things after a keystroke has been sent.  This is useful if you want to have a key pressed before and released after a normal key, for instance. 
+
+In this example, we modify most normal keypresses so that `F22` is pressed before the keystroke is normally sent, and release it __only after__ it's been released.
+
+```c
+static uint8_t f22_tracker;
+
+bool process_record_user(uint16_t keycode, keyrecord_t *record) {
+  switch (keycode) {
+    case KC_A ... KC_F21: //notice how it skips over F22
+    case KC_F23 ... KC_EXSEL: //exsel is the last one before the modifier keys
+      if (record->event.pressed) {
+        register_code(KC_F22); //this means to send F22 down
+        f22_tracker++;
+        register_code(keycode);
+        return false;
+      }
+      break;
+  }
+  return true;
+}
+
+void post_process_record_user(uint16_t keycode, keyrecord_t *record) {
+  switch (keycode) {
+    case KC_A ... KC_F21: //notice how it skips over F22
+    case KC_F23 ... KC_EXSEL: //exsel is the last one before the modifier keys
+      if (!record->event.pressed) {
+        f22_tracker--;
+        if (!f22_tracker) {
+            unregister_code(KC_F22); //this means to send F22 up
+        }
+      }
+      break;
+  }
+}
+```
+
+
 ### TAP, DOWN and UP
 
 You may want to use keys in your macros that you can't write down, such as `Ctrl` or `Home`.
@@ -121,11 +161,11 @@ There's also a couple of mod shortcuts you can use:
 
 * `SS_LCTL(string)`
 * `SS_LSFT(string)`
-* `SS_LALT(string)`
+* `SS_LALT(string)` or `SS_LOPT(string)`
 * `SS_LGUI(string)`, `SS_LCMD(string)` or `SS_LWIN(string)`
 * `SS_RCTL(string)`
 * `SS_RSFT(string)`
-* `SS_RALT(string)` or `SS_ALGR(string)`
+* `SS_RALT(string)`, `SS_ROPT(string)` or `SS_ALGR(string)`
 * `SS_RGUI(string)`, `SS_RCMD(string)` or `SS_RWIN(string)`
 
 These press the respective modifier, send the supplied string and then release the modifier.

docs/feature_ps2_mouse.md

@@ -266,6 +266,25 @@ To reverse the scroll axes you can put:
 
 into config.h.
 
+### Rotate Mouse Axes :id=rotate-mouse-axes
+
+Transform the output of the device with a clockwise rotation of 90, 180, or 270
+degrees.
+
+When compensating for device orientation, rotate the output the same amount in
+the opposite direction.  E.g. if the normal device orientation is considered to
+be North-facing, compensate as follows:
+
+```c
+#define PS2_MOUSE_ROTATE 270 /* Compensate for East-facing device orientation. */
+```
+```c
+#define PS2_MOUSE_ROTATE 180 /* Compensate for South-facing device orientation. */
+```
+```c
+#define PS2_MOUSE_ROTATE 90 /* Compensate for West-facing device orientation. */
+```
+
 ### Debug Settings :id=debug-settings
 
 To debug the mouse, add `debug_mouse = true` or enable via bootmagic.

docs/feature_rgb_matrix.md

@@ -396,18 +396,88 @@ The EEPROM for it is currently shared with the RGBLIGHT system (it's generally a
 
 Where `28` is an unused index from `eeconfig.h`.
 
-## Suspended state :id=suspended-state
+## Functions :id=functions
 
-To use the suspend feature, add this to your `<keyboard>.c`:
+### Direct Operation :id=direct-operation
+|Function                                    |Description  |
+|--------------------------------------------|-------------|
+|`rgb_matrix_set_color_all(r, g, b)`         |Set all of the LEDs to the given RGB value, where `r`/`g`/`b` are between 0 and 255 (not written to EEPROM) |
+|`rgb_matrix_set_color(index, r, g, b)`      |Set a single LED to the given RGB value, where `r`/`g`/`b` are between 0 and 255, and `index` is between 0 and `DRIVER_LED_TOTAL` (not written to EEPROM) |
+
+### Disable/Enable Effects :id=disable-enable-effects
+|Function                                    |Description  |
+|--------------------------------------------|-------------|
+|`rgb_matrix_toggle()`                       |Toggle effect range LEDs between on and off |
+|`rgb_matrix_toggle_noeeprom()`              |Toggle effect range LEDs between on and off (not written to EEPROM) |
+|`rgb_matrix_enable()`                       |Turn effect range LEDs on, based on their previous state |
+|`rgb_matrix_enable_noeeprom()`              |Turn effect range LEDs on, based on their previous state (not written to EEPROM) |
+|`rgb_matrix_disable()`                      |Turn effect range LEDs off |
+|`rgb_matrix_disable_noeeprom()`             |Turn effect range LEDs off (not written to EEPROM) |
+
+### Change Effect Mode :id=change-effect-mode
+|Function                                    |Description  |
+|--------------------------------------------|-------------|
+|`rgb_matrix_mode(mode)`                     |Set the mode, if RGB animations are enabled |
+|`rgb_matrix_mode_noeeprom(mode)`            |Set the mode, if RGB animations are enabled (not written to EEPROM) |
+|`rgb_matrix_step()`                         |Change the mode to the next RGB animation in the list of enabled RGB animations |
+|`rgb_matrix_step_reverse()`                 |Change the mode to the previous RGB animation in the list of enabled RGB animations |
+|`rgb_matrix_increase_speed()`               |Increases the speed of the animations |
+|`rgb_matrix_decrease_speed()`               |Decreases the speed of the animations |
+
+### Change Color :id=change-color
+|Function                                    |Description  |
+|--------------------------------------------|-------------|
+|`rgb_matrix_increase_hue()`                 |Increase the hue for effect range LEDs. This wraps around at maximum hue |
+|`rgb_matrix_decrease_hue()`                 |Decrease the hue for effect range LEDs. This wraps around at minimum hue |
+|`rgb_matrix_increase_sat()`                 |Increase the saturation for effect range LEDs. This wraps around at maximum saturation |
+|`rgb_matrix_decrease_sat()`                 |Decrease the saturation for effect range LEDs. This wraps around at minimum saturation |
+|`rgb_matrix_increase_val()`                 |Increase the value for effect range LEDs. This wraps around at maximum value |
+|`rgb_matrix_decrease_val()`                 |Decrease the value for effect range LEDs. This wraps around at minimum value |
+|`rgb_matrix_sethsv(h, s, v)`                |Set LEDs to the given HSV value where `h`/`s`/`v` are between 0 and 255 |
+|`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  |
+
+## Callbacks :id=callbacks
+
+### Indicators :id=indicators
+
+If you want to set custom indicators, such as an LED for Caps Lock, or layer indication, you can use the `rgb_matrix_indicators_kb` or `rgb_matrix_indicators_user` function for that: 
+```c
+void rgb_matrix_indicators_kb(void) {
+    rgb_matrix_set_color(index, red, green, blue);
+}
+```
+
+### Suspended state :id=suspended-state
+To use the suspend feature, make sure that `#define RGB_DISABLE_WHEN_USB_SUSPENDED true` is added to the `config.h` file. 
+
+Additionally add this to your `<keyboard>.c`:
 
 ```c
-void suspend_power_down_kb(void)
-{
+void suspend_power_down_kb(void) {
+    rgb_matrix_set_suspend_state(true);
+    suspend_power_down_user();
+}
+
+void suspend_wakeup_init_kb(void) {
+    rgb_matrix_set_suspend_state(false);
+    suspend_wakeup_init_user();
+}
+```
+or add this to your `keymap.c`:
+```c
+void suspend_power_down_user(void) {
     rgb_matrix_set_suspend_state(true);
 }
 
-void suspend_wakeup_init_kb(void)
-{
+void suspend_wakeup_init_user(void) {
     rgb_matrix_set_suspend_state(false);
 }
 ```

docs/feature_rgblight.md

@@ -175,23 +175,23 @@ const uint8_t RGBLED_GRADIENT_RANGES[] PROGMEM = {255, 170, 127, 85, 64};
 ## Lighting Layers
 
 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. 
+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.
 
 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
 // Light LEDs 6 to 9 and 12 to 15 red when caps lock is active. Hard to ignore!
 const rgblight_segment_t PROGMEM my_capslock_layer[] = RGBLIGHT_LAYER_SEGMENTS(
-	{6, 4, HSV_RED},       // Light 4 LEDs, starting with LED 6
-	{12, 4, HSV_RED}       // Light 4 LEDs, starting with LED 12
+    {6, 4, HSV_RED},       // Light 4 LEDs, starting with LED 6
+    {12, 4, HSV_RED}       // Light 4 LEDs, starting with LED 12
 );
 // Light LEDs 9 & 10 in cyan when keyboard layer 1 is active
 const rgblight_segment_t PROGMEM my_layer1_layer[] = RGBLIGHT_LAYER_SEGMENTS(
-	{9, 2, HSV_CYAN}
+    {9, 2, HSV_CYAN}
 );
 // Light LEDs 11 & 12 in purple when keyboard layer 2 is active
 const rgblight_segment_t PROGMEM my_layer2_layer[] = RGBLIGHT_LAYER_SEGMENTS(
-	{11, 2, HSV_PURPLE}, 
+    {11, 2, HSV_PURPLE}
 );
 // etc..
 ```
@@ -201,14 +201,14 @@ We combine these layers into an array using the `RGBLIGHT_LAYERS_LIST` macro, an
 ```c
 // Now define the array of layers. Later layers take precedence
 const rgblight_segment_t* const PROGMEM my_rgb_layers[] = RGBLIGHT_LAYERS_LIST(
-	my_capslock_layer,
-	my_layer1_layer,    // Overrides caps lock layer
-	my_layer2_layer     // Overrides other layers
+    my_capslock_layer,
+    my_layer1_layer,    // Overrides caps lock layer
+    my_layer2_layer     // Overrides other layers
 );
 
 void keyboard_post_init_user(void) {
-	// Enable the LED layers
-	rgblight_layers = my_rgb_layers;
+    // Enable the LED layers
+    rgblight_layers = my_rgb_layers;
 }
 ```
 
@@ -216,18 +216,20 @@ Finally, we enable and disable the lighting layers whenever the state of the key
 
 ```c
 layer_state_t layer_state_set_user(layer_state_t state) {
-	// Both layers will light up if both kb layers are active
-	rgblight_set_layer_state(1, layer_state_cmp(state, 1));
-	rgblight_set_layer_state(2, layer_state_cmp(state, 2));
-	return state;
+    // Both layers will light up if both kb layers are active
+    rgblight_set_layer_state(1, layer_state_cmp(state, 1));
+    rgblight_set_layer_state(2, layer_state_cmp(state, 2));
+    return state;
 }
 
 bool led_update_user(led_t led_state) {
-	rgblight_set_layer_state(0, led_state.caps_lock);
-	return true;
+    rgblight_set_layer_state(0, led_state.caps_lock);
+    return true;
 }
 ```
 
+Note: For split keyboards with two controllers, both sides need to be flashed when updating the contents of rgblight_layers.
+
 ## Functions
 
 If you need to change your RGB lighting in code, for example in a macro to change the color whenever you switch layers, QMK provides a set of functions to assist you. See [`rgblight.h`](https://github.com/qmk/qmk_firmware/blob/master/quantum/rgblight.h) for the full list, but the most commonly used functions include:

docs/feature_unicode.md

@@ -90,13 +90,15 @@ Unicode input in QMK works by inputting a sequence of characters to the OS, sort
 
 The following input modes are available:
 
-* **`UC_OSX`**: macOS built-in Unicode hex input. Supports code points up to `0xFFFF` (`0x10FFFF` with Unicode Map).
+* **`UC_MAC`**: macOS built-in Unicode hex input. Supports code points up to `0xFFFF` (`0x10FFFF` with Unicode Map).
 
   To enable, go to _System Preferences > Keyboard > Input Sources_, add _Unicode Hex Input_ to the list (it's under _Other_), then activate it from the input dropdown in the Menu Bar.
-  By default, this mode uses the left Option key (`KC_LALT`) for Unicode input, but this can be changed by defining [`UNICODE_KEY_OSX`](#input-key-configuration) with another keycode.
+  By default, this mode uses the left Option key (`KC_LALT`) for Unicode input, but this can be changed by defining [`UNICODE_KEY_MAC`](#input-key-configuration) with another keycode.
 
   !> Using the _Unicode Hex Input_ input source may disable some Option based shortcuts, such as Option + Left Arrow and Option + Right Arrow.
 
+  !> `UC_OSX` is a deprecated alias of `UC_MAC` that will be removed in a future version of QMK.
+
 * **`UC_LNX`**: Linux built-in IBus Unicode input. Supports code points up to `0x10FFFF` (all possible code points).
 
   Enabled by default and works almost anywhere on IBus-enabled distros. Without IBus, this mode works under GTK apps, but rarely anywhere else.
@@ -124,7 +126,7 @@ You can switch the input mode at any time by using one of the following keycodes
 |----------------------|---------|------------|--------------------------------------------------------------|
 |`UNICODE_MODE_FORWARD`|`UC_MOD` |Next in list|[Cycle](#input-mode-cycling) through selected modes           |
 |`UNICODE_MODE_REVERSE`|`UC_RMOD`|Prev in list|[Cycle](#input-mode-cycling) through selected modes in reverse|
-|`UNICODE_MODE_OSX`    |`UC_M_OS`|`UC_OSX`    |Switch to macOS input                                         |
+|`UNICODE_MODE_MAC`    |`UC_M_MA`|`UC_MAC`    |Switch to macOS input                                         |
 |`UNICODE_MODE_LNX`    |`UC_M_LN`|`UC_LNX`    |Switch to Linux input                                         |
 |`UNICODE_MODE_WIN`    |`UC_M_WI`|`UC_WIN`    |Switch to Windows input                                       |
 |`UNICODE_MODE_BSD`    |`UC_M_BS`|`UC_BSD`    |Switch to BSD input (not implemented)                         |
@@ -145,9 +147,9 @@ If you have the [Audio feature](feature_audio.md) enabled on the board, you can
 For instance, you can add these definitions to your `config.h` file:
 
 ```c
-#define UNICODE_SONG_OSX  COIN_SOUND
+#define UNICODE_SONG_MAC  AUDIO_ON_SOUND
 #define UNICODE_SONG_LNX  UNICODE_LINUX
-#define UNICODE_SONG_BSD  MARIO_GAMEOVER
+#define UNICODE_SONG_BSD  TERMINAL_SOUND
 #define UNICODE_SONG_WIN  UNICODE_WINDOWS
 #define UNICODE_SONG_WINC UNICODE_WINDOWS
 ```
@@ -171,7 +173,7 @@ You can customize the keys used to trigger Unicode input for macOS, Linux and Wi
 
 |Define            |Type      |Default           |Example                                    |
 |------------------|----------|------------------|-------------------------------------------|
-|`UNICODE_KEY_OSX` |`uint8_t` |`KC_LALT`         |`#define UNICODE_KEY_OSX  KC_RALT`         |
+|`UNICODE_KEY_MAC` |`uint8_t` |`KC_LALT`         |`#define UNICODE_KEY_MAC  KC_RALT`         |
 |`UNICODE_KEY_LNX` |`uint16_t`|`LCTL(LSFT(KC_U))`|`#define UNICODE_KEY_LNX  LCTL(LSFT(KC_E))`|
 |`UNICODE_KEY_WINC`|`uint8_t` |`KC_RALT`         |`#define UNICODE_KEY_WINC KC_RGUI`         |
 
@@ -180,7 +182,7 @@ You can customize the keys used to trigger Unicode input for macOS, Linux and Wi
 You can choose which input modes are available for cycling through. By default, this is disabled. If you want to enable it, limiting it to just the modes you use makes sense. Note that the values in the list are comma-delimited.
 
 ```c
-#define UNICODE_SELECTED_MODES UC_OSX, UC_LNX, UC_WIN, UC_WINC
+#define UNICODE_SELECTED_MODES UC_MAC, UC_LNX, UC_WIN, UC_WINC
 ```
 
 You can cycle through the selected modes by using the `UC_MOD`/`UC_RMOD` keycodes, or by calling `cycle_unicode_input_mode(offset)` in your code (`offset` is how many modes to move forward by, so +1 corresponds to `UC_MOD`).

docs/feature_wpm.md

@@ -0,0 +1,25 @@
+# Word Per Minute (WPM) Calculcation
+
+The WPM feature uses time between keystrokes to compute a rolling average words
+per minute rate and makes this available for various uses.
+
+Enable the WPM system by adding this to your `rules.mk`:
+
+    WPM_ENABLE = yes
+
+For split keyboards using soft serial, the computed WPM
+score will be available on the master AND slave half.
+
+## Public Functions
+
+`uint8_t get_current_wpm(void);`
+This function returns the current WPM as an unsigned integer.
+
+
+## Customized keys for WPM calc
+
+By default, the WPM score only includes letters, numbers, space and some
+punctuation.  If you want to change the set of characters considered as part of
+the WPM calculation, you can implement `wpm_keycode_user(uint16_t keycode)`
+and return true for any characters you would like included in the calculation,
+or false to not count that particular keycode.

docs/flashing.md

@@ -26,7 +26,6 @@ Compatible flashers:
 
 * [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) (recommended GUI)
 * [dfu-programmer](https://github.com/dfu-programmer/dfu-programmer) / `:dfu` in QMK (recommended command line)
-* [Atmel's Flip](http://www.microchip.com/developmenttools/productdetails.aspx?partno=flip) (not recommended)
 
 Flashing sequence:
 

docs/fr-fr/_summary.md

@@ -101,7 +101,8 @@
   * [Guide des claviers soudés à la main](fr-fr/hand_wire.md)
   * [Guide de flash de l’ISP](fr-fr/isp_flashing_guide.md)
   * [Guide du débogage ARM](fr-fr/arm_debugging.md)
-  * [Drivers i2c](fr-fr/i2c_driver.md)
+  * [Drivers I2C](fr-fr/i2c_driver.md)
+  * [Drivers SPI](fr-fr/spi_driver.md)
   * [Contrôles des GPIO](fr-fr/internals_gpio_control.md)
   * [Conversion en Proton C](fr-fr/proton_c_conversion.md)
 

docs/fr-fr/faq_debug.md

@@ -155,11 +155,3 @@ Pour le moment, l'origine du problème n'est pas comprise, mais certaines option
 
 https://github.com/tmk/tmk_keyboard/issues/266
 https://geekhack.org/index.php?topic=41989.msg1967778#msg1967778
-
-## FLIP ne marche pas
-
-### `AtLibUsbDfu.dll` Not Found
-
-Supprimez le pilote actuel et réinstallez celui donné par FLIP dans le gestionnaire de périphériques.
-
-http://imgur.com/a/bnwzy

docs/fr-fr/flashing.md

@@ -26,7 +26,6 @@ Méthodes de flash compatibles :
 
 * [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) (interface graphique recommandé)
 * [dfu-programmer](https://github.com/dfu-programmer/dfu-programmer) / `:dfu` avec QMK (outil en ligne de commande recommandé)
-* [Atmel's Flip](http://www.microchip.com/developmenttools/productdetails.aspx?partno=flip) (non recommandé)
 
 Ordre des actions :
 

docs/getting_started_vagrant.md

@@ -20,7 +20,6 @@ The "easy" way to flash the firmware is using a tool from your host OS:
 
 * [QMK Toolbox](https://github.com/qmk/qmk_toolbox) (recommended)
 * [Teensy Loader](https://www.pjrc.com/teensy/loader.html)
-* [Atmel FLIP](http://www.atmel.com/tools/flip.aspx)
 
 If you want to program via the command line you can uncomment the ['modifyvm'] lines in the Vagrantfile to enable the USB passthrough into Linux and then program using the command line tools like dfu-util/dfu-programmer or you can install the Teensy CLI version.
 

docs/hardware_keyboard_guidelines.md

@@ -61,10 +61,76 @@ This file is used by the [QMK API](https://github.com/qmk/qmk_api). It contains
 
 All projects need to have a `config.h` file that sets things like the matrix size, product name, USB VID/PID, description and other settings. In general, use this file to set essential information and defaults for your keyboard that will always work.
 
+The `config.h` files can also be placed in sub-folders, and the order in which they are read is as follows:
+
+* `keyboards/top_folder/config.h`
+  * `keyboards/top_folder/sub_1/config.h`
+    * `keyboards/top_folder/sub_1/sub_2/config.h`
+      * `keyboards/top_folder/sub_1/sub_2/sub_3/config.h`
+        * `keyboards/top_folder/sub_1/sub_2/sub_3/sub_4/config.h`
+          * `users/a_user_folder/config.h`
+          * `keyboards/top_folder/keymaps/a_keymap/config.h`
+        * `keyboards/top_folder/sub_1/sub_2/sub_3/sub_4/post_config.h`
+      * `keyboards/top_folder/sub_1/sub_2/sub_3/post_config.h`
+    * `keyboards/top_folder/sub_1/sub_2/post_config.h`
+  * `keyboards/top_folder/sub_1/post_config.h`
+* `keyboards/top_folder/post_config.h`
+
+The `post_config.h` file can be used for additional post-processing, depending on what is specified in the `config.h` file. For example, if you define the `IOS_DEVICE_ENABLE` macro in your keymap-level `config.h` file as follows, you can configure more detailed settings accordingly in the `post_config.h` file:
+
+* `keyboards/top_folder/keymaps/a_keymap/config.h`
+  ```c
+  #define IOS_DEVICE_ENABLE
+  ```
+* `keyboards/top_folder/post_config.h`
+  ```c
+  #ifndef IOS_DEVICE_ENABLE
+    // USB_MAX_POWER_CONSUMPTION value for this keyboard
+    #define USB_MAX_POWER_CONSUMPTION 400
+  #else
+    // fix iPhone and iPad power adapter issue
+    // iOS device need lessthan 100
+    #define USB_MAX_POWER_CONSUMPTION 100
+  #endif
+  
+  #ifdef RGBLIGHT_ENABLE
+    #ifndef IOS_DEVICE_ENABLE
+      #define RGBLIGHT_LIMIT_VAL 200
+      #define RGBLIGHT_VAL_STEP 17
+    #else
+      #define RGBLIGHT_LIMIT_VAL 35
+      #define RGBLIGHT_VAL_STEP 4
+    #endif
+    #ifndef RGBLIGHT_HUE_STEP
+      #define RGBLIGHT_HUE_STEP 10
+    #endif
+    #ifndef RGBLIGHT_SAT_STEP
+      #define RGBLIGHT_SAT_STEP 17
+    #endif
+  #endif
+  ```
+
+?> If you define options using `post_config.h` as in the above example, you should not define the same options in the keyboard- or user-level `config.h`.
+
 ### `rules.mk`
 
 The presence of this file means that the folder is a keyboard target and can be used in `make` commands. This is where you setup the build environment for your keyboard and configure the default set of features.
 
+The `rules.mk` file can also be placed in a sub-folder, and its reading order is as follows:
+
+* `keyboards/top_folder/rules.mk`
+  * `keyboards/top_folder/sub_1/rules.mk`
+    * `keyboards/top_folder/sub_1/sub_2/rules.mk`
+      * `keyboards/top_folder/sub_1/sub_2/sub_3/rules.mk`
+        * `keyboards/top_folder/sub_1/sub_2/sub_3/sub_4/rules.mk`
+          * `keyboards/top_folder/keymaps/a_keymap/rules.mk`
+          * `users/a_user_folder/rules.mk`
+* `common_features.mk`
+
+Many of the settings written in the `rules.mk` file are interpreted by `common_features.mk`, which sets the necessary source files and compiler options.
+
+?> See `build_keyboard.mk` and `common_features.mk` for more details.
+
 ### `<keyboard_name.c>`
 
 This is where you will write custom code for your keyboard. Typically you will write code to initialize and interface with the hardware in your keyboard. If your keyboard consists of only a key matrix with no LEDs, speakers, or other auxiliary hardware this file can be blank.

docs/he-il/_summary.md

@@ -114,6 +114,7 @@
   * [מדריך לצריבת ISP](he-il/isp_flashing_guide.md)
   * [מדריך לדיבאגינג ARM](he-il/arm_debugging.md)
   * [מנהל התקן I2C](he-il/i2c_driver.md)
+  * [מנהל התקן SPI](he-il/spi_driver.md)
   * [בקרת GPIO](he-il/internals_gpio_control.md)
   * [המרת Proton C](he-il/proton_c_conversion.md)
 

docs/ja/README.md

@@ -1,8 +1,8 @@
 # Quantum Mechanical Keyboard Firmware
 
 <!---
-  original document: eae21eed7:docs/README.md
-  git diff eae21eed7 HEAD -- docs/README.md | cat
+  original document: 0.8.58:docs/README.md
+  git diff 0.8.58 HEAD -- docs/README.md | cat
 -->
 
 [![現在のバージョン](https://img.shields.io/github/tag/qmk/qmk_firmware.svg)](https://github.com/qmk/qmk_firmware/tags)
@@ -12,26 +12,37 @@
 [![GitHub 貢献者](https://img.shields.io/github/contributors/qmk/qmk_firmware.svg)](https://github.com/qmk/qmk_firmware/pulse/monthly)
 [![GitHub フォーク](https://img.shields.io/github/forks/qmk/qmk_firmware.svg?style=social&label=Fork)](https://github.com/qmk/qmk_firmware/)
 
-## QMK ファームウェアとは何か？
+## QMK ファームウェアとは何でしょうか？
 
-QMK (*Quantum Mechanical Keyboard*)は QMK ファームウェア、QMK ツールボックス、qmk.fm およびそれらのドキュメントを保守するオープンソースコミュニティです。QMK ファームウェアは[tmk\_keyboard](http://github.com/tmk/tmk_keyboard) を元にしたキーボードファームウェアで、Atmel AVR コントローラ、より具体的には [OLKB 製品](http://olkb.com)、[ErgoDox EZ](http://www.ergodox-ez.com) キーボードおよび [Clueboard 製品](http://clueboard.co/) のための幾つかの便利な機能を持ちます。また、ChibiOS を使って ARM チップに移植されています。これを使ってあなたの作った手配線のキーボードあるいはカスタムキーボード PCB で作ったキーボードを動かすことができます。
+QMK (*Quantum Mechanical Keyboard*)は、コンピュータ入力デバイスの開発を中心としたオープンソースコミュニティです。コミュニティには、キーボード、マウス、MIDI デバイスなど、全ての種類の入力デバイスが含まれます。協力者の中心グループは、[QMK ファームウェア](https://github.com/qmk/qmk_firmware)、[QMK Configurator](https://config.qmk.fm)、[QMK ツールボックス](https://github.com/qmk/qmk_toolbox)、[qmk.fm](https://qmk.fm)、そして、このドキュメントを、あなたのようなコミュニティメンバーの助けを借りて保守しています。
 
-## 入手方法
+## 始めましょう
 
-QMK のキーマップ、キーボード、機能に貢献をする予定がある場合、最も簡単なのは、[Github を介してリポジトリをフォークし](https://github.com/qmk/qmk_firmware#fork-destination-box)、リポジトリをあなたの開発環境にクローンして変更を加え、それらをプッシュし、[プルリクエスト](https://github.com/qmk/qmk_firmware/pulls)を開くことです。
+QMK は初めてですか？始めるには2つの方法があります:
 
-それ以外の場合は、`git clone https://github.com/qmk/qmk_firmware` を介して直接クローンすることができます。zip または tar ファイルをダウンロードしないでください。コンパイルするためのサブモジュールをダウンロードするために git リポジトリが必要です。
+* 基本: [QMK Configurator](https://config.qmk.fm)
+    * ドロップダウンからあなたのキーボードを選択し、キーボードをプログラムします。
+    * 見ることができる [紹介ビデオ](https://www.youtube.com/watch?v=-imgglzDMdY) があります。
+    * 読むことができる概要 [ドキュメント](ja/newbs_building_firmware_configurator.md) があります。
+* 発展: [ソースを使用します](ja/newbs.md)
+    * より強力ですが、使うのはより困難です。
 
-## コンパイル方法
+## 自分用にアレンジします
 
-コンパイルをする前に、AVR または ARM 開発のための[環境をインストール](ja/getting_started_build_tools.md)する必要があります。それが完了したら、`make` コマンドを使用して、以下の表記でキーボードとキーマップをビルドします。
+QMK には、探求すべき多くの[機能](ja/features.md)と、深く知るためのリファレンスドキュメントがたくさんあります。ほとんどの機能は[キーマップ](ja/keymap.md)を変更し、[キーコード](ja/keycodes.md)を変更することで活用されます。
 
-    make planck/rev4:default
+## 手助けが必要ですか？
 
-これは、`planck` の `rev4` リビジョンを `default` キーマップでビルドします。全てのキーボードにリビジョン(サブプロジェクトまたはフォルダとも呼ばれます)があるわけではありません。その場合は省略されます:
+[サポートページ](ja/support.md) をチェックして、QMK の使い方について手助けを得る方法を確認してください。
 
-    make preonic:default
+## 貢献する
 
-## カスタマイズ方法
+QMK コミュニティに貢献する方法はたくさんあります。始める最も簡単な方法は、それを使って友人に QMK という単語を広めることです。
 
-QMK には、探求すべき多くの[機能](ja/features.md)と、深堀りするための[リファレンス ドキュメント](http://docs.qmk.fm)がたくさんあります。ほとんどの機能は[キーマップ](ja/keymap.md)を変更し、[キーコード](ja/keycodes.md)を変更することで活用されます。
+* フォーラムやチャットルームで人々を支援します:
+    * [/r/olkb](https://www.reddit.com/r/olkb/)
+    * [Discord サーバ](https://discord.gg/Uq7gcHh)
+* 下にある「Edit This Page」をクリックしてドキュメントに貢献します
+* [ドキュメントをあなたの言語に翻訳します](ja/translating.md)
+* [バグを報告します](https://github.com/qmk/qmk_firmware/issues/new/choose)
+* [プルリクエストを開きます](ja/contributing.md)

docs/ja/_summary.md

@@ -1,130 +1,163 @@
-* [完全な初心者のガイド](ja/newbs.md)
-   * [はじめに](ja/newbs_getting_started.md)
-   * [初めてのファームウェアの構築](ja/newbs_building_firmware.md)
-   * [ファームウェアのフラッシュ](ja/newbs_flashing.md)
-   * [テストとデバッグ](ja/newbs_testing_debugging.md)
-   * [QMK における Git 運用作法](ja/newbs_git_best_practices.md)
-     * [あなたのフォークの master ブランチ](ja/newbs_git_using_your_master_branch.md)
-     * [マージの競合の解決](ja/newbs_git_resolving_merge_conflicts.md)
-     * [同期のとれていない git ブランチの再同期](ja/newbs_git_resynchronize_a_branch.md)
-   * [学習リソース](ja/newbs_learn_more_resources.md)
+* チュートリアル
+  * [入門](ja/newbs.md)
+  * [セットアップ](ja/newbs_getting_started.md)
+  * [初めてのファームウェアの構築](ja/newbs_building_firmware.md)
+  * [ファームウェアのフラッシュ](ja/newbs_flashing.md)
+  * [テストとデバッグ](ja/newbs_testing_debugging.md)
+  * [手助けを得る/サポート](ja/support.md)
+  * [他のリソース](ja/newbs_learn_more_resources.md)
 
-* [QMKの基本](ja/README.md)
-   * [QMK の導入](ja/getting_started_introduction.md)
-   * [QMK CLI](ja/cli.md)
-   * [QMK CLI 設定](ja/cli_configuration.md)
-   * [QMK への貢献](ja/contributing.md)
-   * [Github の使い方](ja/getting_started_github.md)
-   * [ヘルプ](ja/getting_started_getting_help.md)
+* FAQ
+  * [一般的な FAQ](ja/faq_general.md)
+  * [QMK のビルド/コンパイル](ja/faq_build.md)
+  * [QMK のデバッグ/トラブルシューティング](ja/faq_debug.md)
+  * [キーマップ FAQ](ja/faq_keymap.md)
+  * [用語](ja/reference_glossary.md)
 
-* [破壊的な変更](ja/breaking_changes.md)
-   * [プルリクエストにフラグが付けられた](ja/breaking_changes_instructions.md)
-   * [2019年8月30日](ja/ChangeLog/20190830.md)
+* Configurator
+  * [概要](ja/newbs_building_firmware_configurator.md)
+  * [ステップ・バイ・ステップ](ja/configurator_step_by_step.md)
+  * [トラブルシューティング](ja/configurator_troubleshooting.md)
+  * QMK API
+    * [概要](ja/api_overview.md)
+    * [API ドキュメント](ja/api_docs.md)
+    * [キーボードサポート](ja/reference_configurator_support.md)
 
-* [FAQ](ja/faq.md)
-   * [一般的な FAQ](ja/faq_general.md)
-   * [QMK のビルド/コンパイル](ja/faq_build.md)
-   * [QMK のデバッグ/トラブルシューティング](ja/faq_debug.md)
-   * [キーマップ](ja/faq_keymap.md)
-   * [Zadig を使ったドライバのインストール](ja/driver_installation_zadig.md)
+* CLI
+    * [概要](ja/cli.md)
+    * [設定](ja/cli_configuration.md)
+    * [コマンド](ja/cli_commands.md)
 
-* 詳細なガイド
-   * [ビルドツールのインストール](ja/getting_started_build_tools.md)
-   * [Vagrant のガイド](ja/getting_started_vagrant.md)
-   * [ビルド/コンパイルの説明](ja/getting_started_make_guide.md)
-   * [ファームウェアのフラッシュ](ja/flashing.md)
-   * [機能のカスタマイズ](ja/custom_quantum_functions.md)
-   * [キーマップの概要](ja/keymap.md)
+* QMK を使う
+  * ガイド
+    * [機能のカスタマイズ](ja/custom_quantum_functions.md)
+    * [Zadig を使ったドライバのインストール](ja/driver_installation_zadig.md)
+    * [キーマップの概要](ja/keymap.md)
+    * [Vagrant のガイド](ja/getting_started_vagrant.md)
+    * 書き込み
+      * [書き込み](ja/flashing.md)
+      * [ATmega32A の書き込み (ps2avrgb)](ja/flashing_bootloadhid.md)
+    * IDE
+      * [Eclipse で QMK を使用](ja/other_eclipse.md)
+      * [VSCode で QMK を使用](ja/other_vscode.md)
+    * Git のベストプラクティス
+      * [入門](ja/newbs_git_best_practices.md)
+      * [フォーク](ja/newbs_git_using_your_master_branch.md)
+      * [マージの競合の解決](ja/newbs_git_resolving_merge_conflicts.md)
+      * [ブランチの修正](ja/newbs_git_resynchronize_a_branch.md)
+    * キーボードを作る
+      * [Hand Wiring ガイド](ja/hand_wire.md)
+      * [ISP 書き込みガイド](ja/isp_flashing_guide.md)
 
-* [ハードウェア](ja/hardware.md)
-   * [互換性のあるマイクロコントローラ](ja/compatible_microcontrollers.md)
-   * [AVR プロセッサ](ja/hardware_avr.md)
-   * [ドライバ](ja/hardware_drivers.md)
+  * 単純なキーコード
+    * [完全なリスト](ja/keycodes.md)
+    * [基本的なキーコード](ja/keycodes_basic.md)
+    * [修飾キー](ja/feature_advanced_keycodes.md)
+    * [Quantum キーコード](ja/quantum_keycodes.md)
 
-* リファレンス
-   * [キーボード ガイドライン](ja/hardware_keyboard_guidelines.md)
-   * [設定オプション](ja/config_options.md)
-   * [キーコード](ja/keycodes.md)
-   * [コーディング規約 - C](ja/coding_conventions_c.md)
-   * [コーディング規約 - Python](ja/coding_conventions_python.md)
-   * [ドキュメント ベストプラクティス](ja/documentation_best_practices.md)
-   * [ドキュメント テンプレート](ja/documentation_templates.md)
-   * [用語](ja/reference_glossary.md)
-   * [ユニットテスト](ja/unit_testing.md)
-   * [便利な関数](ja/ref_functions.md)
-   * [Configurator サポート](ja/reference_configurator_support.md)
-   * [info.json 形式](ja/reference_info_json.md)
-   * [Python CLI 開発](ja/cli_development.md)
+  * 高度なキーコード
+    * [コマンド](ja/feature_command.md)
+    * [動的マクロ](ja/feature_dynamic_macros.md)
+    * [グレイブ エスケープ](ja/feature_grave_esc.md)
+    * [リーダーキー](ja/feature_leader_key.md)
+    * [モッドタップ](ja/mod_tap.md)
+    * [マクロ](ja/feature_macros.md)
+    * [マウスキー](ja/feature_mouse_keys.md)
+    * [Space Cadet Shift](ja/feature_space_cadet.md)
+    * [US ANSI シフトキー](ja/keycodes_us_ansi_shifted.md)
 
-* [機能](ja/features.md)
-   * [基本的なキーコード](ja/keycodes_basic.md)
-   * [US ANSI シフトキー](ja/keycodes_us_ansi_shifted.md)
-   * [Quantum キーコード](ja/quantum_keycodes.md)
-   * [Advanced キーコード](ja/feature_advanced_keycodes.md)
-   * [オーディオ](ja/feature_audio.md)
-   * [自動シフト](ja/feature_auto_shift.md)
-   * [バックライト](ja/feature_backlight.md)
-   * [ブルートゥース](ja/feature_bluetooth.md)
-   * [ブートマジック](ja/feature_bootmagic.md)
-   * [コンボ](ja/feature_combo.md)
-   * [コマンド](ja/feature_command.md)
-   * [デバウンス API](ja/feature_debounce_type.md)
-   * [DIP スイッチ](ja/feature_dip_switch.md)
-   * [動的マクロ](ja/feature_dynamic_macros.md)
-   * [エンコーダ](ja/feature_encoders.md)
-   * [グレイブ エスケープ](ja/feature_grave_esc.md)
-   * [触覚フィードバック](ja/feature_haptic_feedback.md)
-   * [HD44780 LCD コントローラ](ja/feature_hd44780.md)
-   * [キーロック](ja/feature_key_lock.md)
-   * [レイアウト](ja/feature_layouts.md)
-   * [リーダー キー](ja/feature_leader_key.md)
-   * [LED マトリクス](ja/feature_led_matrix.md)
-   * [マクロ](ja/feature_macros.md)
-   * [マウスキー](ja/feature_mouse_keys.md)
-   * [OLED ドライバ](ja/feature_oled_driver.md)
-   * [One Shot Keys](ja/one_shot_keys.md)
-   * [ポインティング デバイス](ja/feature_pointing_device.md)
-   * [PS/2 マウス](ja/feature_ps2_mouse.md)
-   * [RGB ライト](ja/feature_rgblight.md)
-   * [RGB マトリクス](ja/feature_rgb_matrix.md)
-   * [Space Cadet](ja/feature_space_cadet.md)
-   * [分割キーボード](ja/feature_split_keyboard.md)
-   * [Stenography](ja/feature_stenography.md)
-   * [Swap Hands](ja/feature_swap_hands.md)
-   * [タップ ダンス](ja/feature_tap_dance.md)
-   * [ターミナル](ja/feature_terminal.md)
-   * [感熱式プリンタ](ja/feature_thermal_printer.md)
-   * [ユニコード](ja/feature_unicode.md)
-   * [ユーザスペース](ja/feature_userspace.md)
-   * [Velocikey](ja/feature_velocikey.md)
+  * ソフトウェア機能
+    * [自動シフト](ja/feature_auto_shift.md)
+    * [コンボ](ja/feature_combo.md)
+    * [デバウンス API](ja/feature_debounce_type.md)
+    * [キーロック](ja/feature_key_lock.md)
+    * [レイヤー](ja/feature_layers.md)
+    * [One Shot Keys](ja/one_shot_keys.md)
+    * [ポインティング デバイス](ja/feature_pointing_device.md)
+    * [Swap Hands](ja/feature_swap_hands.md)
+    * [タップダンス](ja/feature_tap_dance.md)
+    * [タップホールド設定](ja/tap_hold.md)
+    * [ターミナル](ja/feature_terminal.md)
+    * [ユニコード](ja/feature_unicode.md)
+    * [ユーザスペース](ja/feature_userspace.md)
+    * [WPM 計算](ja/feature_wpm.md)
 
-* メーカーおよびモッダーのために
-   * [Hand Wiring ガイド](ja/hand_wire.md)
-   * [ISP 書き込みガイド](ja/isp_flashing_guide.md)
-   * [ARM デバッグ ガイド](ja/arm_debugging.md)
-   * [ADC ドライバ](ja/adc_driver.md)
-   * [I2C ドライバ](ja/i2c_driver.md)
-   * [WS2812 ドライバ](ja/ws2812_driver.md)
-   * [EEPROM ドライバ](ja/eeprom_driver.md)
-   * [GPIO コントロール](ja/internals_gpio_control.md)
-   * [カスタムマトリックス](ja/custom_matrix.md)
-   * [Proton C 規約](ja/proton_c_conversion.md)
+  * ハードウェア機能
+    * 表示
+      * [HD44780 LCD コントローラ](ja/feature_hd44780.md)
+      * [OLED ドライバ](ja/feature_oled_driver.md)
+    * 電飾
+      * [バックライト](ja/feature_backlight.md)
+      * [LED マトリックス](ja/feature_led_matrix.md)
+      * [RGB ライト](ja/feature_rgblight.md)
+      * [RGB マトリックス](ja/feature_rgb_matrix.md)
+    * [オーディオ](ja/feature_audio.md)
+    * [Bluetooth](ja/feature_bluetooth.md)
+    * [ブートマジック](ja/feature_bootmagic.md)
+    * [カスタムマトリックス](ja/custom_matrix.md)
+    * [DIP スイッチ](ja/feature_dip_switch.md)
+    * [エンコーダ](ja/feature_encoders.md)
+    * [触覚フィードバック](ja/feature_haptic_feedback.md)
+    * [Proton C 規約](ja/proton_c_conversion.md)
+    * [PS/2 マウス](ja/feature_ps2_mouse.md)
+    * [分割キーボード](ja/feature_split_keyboard.md)
+    * [Stenography](ja/feature_stenography.md)
+    * [感熱式プリンタ](ja/feature_thermal_printer.md)
+    * [Velocikey](ja/feature_velocikey.md)
 
-* より深く知るために
-   * [キーボードがどのように動作するか](ja/how_keyboards_work.md)
-   * [QMK の理解](ja/understanding_qmk.md)
+* QMK の開発
+  * 破壊的な変更
+    * [概要](ja/breaking_changes.md)
+    * [プルリクエストにフラグが付けられた](ja/breaking_changes_instructions.md)
+    * 履歴
+      * [2020年2月29日](ja/ChangeLog/20200229.md)
+      * [2019年8月30日](ja/ChangeLog/20190830.md)
 
-* 他の話題
-   * [Eclipse で QMK を使用](ja/other_eclipse.md)
-   * [VSCode で QMK を使用](ja/other_vscode.md)
-   * [サポート](ja/getting_started_getting_help.md)
-   * [翻訳を追加する方法](ja/translating.md)
+  * C 開発
+    * [ARM デバッグ ガイド](ja/arm_debugging.md)
+    * [AVR プロセッサ](ja/hardware_avr.md)
+    * [コーディング規約](ja/coding_conventions_c.md)
+    * [互換性のあるマイクロコントローラ](ja/compatible_microcontrollers.md)
+    * [ドライバ](ja/hardware_drivers.md)
+      * [ADC ドライバ](ja/adc_driver.md)
+      * [I2C ドライバ](ja/i2c_driver.md)
+      * [SPI ドライバ](ja/spi_driver.md)
+      * [WS2812 ドライバ](ja/ws2812_driver.md)
+      * [EEPROM ドライバ](ja/eeprom_driver.md)
+    * [GPIO コントロール](ja/internals_gpio_control.md)
+    * [キーボード ガイドライン](ja/hardware_keyboard_guidelines.md)
 
-* QMK の内部詳細(作成中)
-   * [定義](ja/internals_defines.md)
-   * [Input Callback Reg](ja/internals_input_callback_reg.md)
-   * [Midi ドライバ](ja/internals_midi_device.md)
-   * [Midi デバイスのセットアップ手順](ja/internals_midi_device_setup_process.md)
-   * [Midi ユーティリティ](ja/internals_midi_util.md)
-   * [Send Functions](ja/internals_send_functions.md)
-   * [Sysex Tools](ja/internals_sysex_tools.md)
+  * Python 開発
+    * [コーディング規約](ja/coding_conventions_python.md)
+    * [QMK CLI 開発](ja/cli_development.md)
+
+  * Configurator 開発
+    * QMK API
+      * [開発環境](ja/api_development_environment.md)
+      * [アーキテクチャの概要](ja/api_development_overview.md)
+
+  * QMK Reference
+    * [QMK への貢献](ja/contributing.md)
+    * [QMK ドキュメントの翻訳](ja/translating.md)
+    * [設定オプション](ja/config_options.md)
+    * [Make ドキュメント](ja/getting_started_make_guide.md)
+    * [ドキュメント ベストプラクティス](ja/documentation_best_practices.md)
+    * [ドキュメント テンプレート](ja/documentation_templates.md)
+    * [コミュニティレイアウト](ja/feature_layouts.md)
+    * [ユニットテスト](ja/unit_testing.md)
+    * [便利な関数](ja/ref_functions.md)
+    * [info.json 形式](ja/reference_info_json.md)
+
+  * より深く知るために
+    * [キーボードがどのように動作するか](ja/how_keyboards_work.md)
+    * [マトリックスがどのように動作するか](ja/how_a_matrix_works.md)
+    * [QMK を理解する](ja/understanding_qmk.md)
+
+  * QMK の内部詳細(作成中)
+    * [定義](ja/internals_defines.md)
+    * [Input Callback Reg](ja/internals_input_callback_reg.md)
+    * [Midi デバイス](ja/internals_midi_device.md)
+    * [Midi デバイスのセットアップ手順](ja/internals_midi_device_setup_process.md)
+    * [Midi ユーティリティ](ja/internals_midi_util.md)
+    * [Send Functions](ja/internals_send_functions.md)
+    * [Sysex Tools](ja/internals_sysex_tools.md)

docs/ja/arm_debugging.md

@@ -1,8 +1,8 @@
 # Eclipse を使った ARM デバッグ
 
 <!---
-  original document: eae21eed7:docs/arm_debugging.md
-  git diff eae21eed7 HEAD -- docs/arm_debugging.md | cat
+  original document: 0.8.58:docs/arm_debugging.md
+  git diff 0.8.58 HEAD -- docs/arm_debugging.md | cat
 -->
 
 このページでは、SWD アダプタとオープンソース/フリーツールを使って ARM MCU をデバッグするためのセットアップ方法について説明します。このガイドでは、GNU MCU Eclipse IDE for C/C++ Developers および OpenOCD を必要な依存関係と一緒にインストールします。
@@ -60,7 +60,7 @@ Java は Eclipse で必要とされるため、[ここ](https://www.oracle.com/t
 
 Eclipse に QMK をビルドしようとするデバイスを教える必要があります。QMK フォルダを右クリック -> Properties -> C/C++ Build -> Settings を選択します。Devices タブを選択し、Devices の下から MCU の適切な種類を選択します。私の例では、STM32F303CC です。
 
-この間に、Build コマンドもセットアップしましょう。C/C++ Build を選択し、Behavior タブを選択します。build コマンドのところで、`all` を必要な make コマンドに置き換えます。例えば、rev6 Planck の default キーマップの場合、これは `planck/rev6:default` になります。Apply and Close を選択します。
+この間に、Build コマンドもセットアップしましょう。C/C++ Build を選択し、Behavior タブを選択します。Build コマンドのところで、`all` を必要な make コマンドに置き換えます。例えば、rev6 Planck の default キーマップの場合、これは `planck/rev6:default` になります。Apply and Close を選択します。
 
 ## ビルド
 
@@ -70,13 +70,13 @@ Eclipse に QMK をビルドしようとするデバイスを教える必要が
 
 ### デバッガの接続
 
-ARM MCU は、クロック信号(SWCLK) とデータ信号(SWDIO) で構成される Single Wire Debug (SWD) プロトコルを使います。MCU を 完全に操作するには、この2本のワイヤとグラウンドを接続するだけで十分です。ここでは、キーボードは USB を介して電力が供給されると想定しています。手動でリセットボタンを使えるため、RESET 信号は必要ありません。より高度なセットアップのために printf と scanf をホストに非同期にパイプする SWO 信号を使用できますが、私たちのセットアップでは無視します。
+ARM MCU は、クロック信号(SWCLK) とデータ信号(SWDIO) で構成される Single Wire Debug (SWD) プロトコルを使います。MCU を完全に操作するには、この2本のワイヤとグラウンドを接続するだけで十分です。ここでは、キーボードは USB を介して電力が供給されると想定しています。手動でリセットボタンを使えるため、RESET 信号は必要ありません。より高度なセットアップのために printf と scanf をホストに非同期にパイプする SWO 信号を使用できますが、私たちのセットアップでは無視します。
 
 注意: SWCLK と SWDIO ピンがキーボードのマトリックスで使われていないことを確認してください。もし使われている場合は、一時的に他のピンに切り替えることができます。
 
 ### デバッガの設定
 
-QMK フォルダを右クリックし、Debug As -> Debug Configurations... を選択します。ここで、GDB OpenOCD Debugging をダブルクリックします。Debugger タブを選択し、MCU に必要な設定を入力します。これを見つけるにはいじったりググったりする必要があるかもしれません。STM32F3 用のデフォルトスクリプトは stm32f3discovery.cfg と呼ばれます。OpenOCD に伝えるには、Config options で `-f board/stm32f3discovery.cfg` と入力します。
+QMK フォルダを右クリックし、Debug As -> Debug Configurations... を選択します。ここで、GDB OpenOCD Debugging をダブルクリックします。Debugger タブを選択し、MCU に必要な設定を入力します。これを見つけるにはいじったりググったりする必要があるかもしれません。STM32F3 用のデフォルトスクリプトは `stm32f3discovery.cfg` と呼ばれます。OpenOCD に伝えるには、Config options で `-f board/stm32f3discovery.cfg` と入力します。
 
 注意: 私の場合、この設定スクリプトはリセット操作を無効にするために編集が必要です。スクリプトの場所は、通常はパス `openocd/version/.content/scripts/board` の下の実際の実行可能フィールドの中で見つかります。ここで、私は `reset_config srst_only` を `reset_config none` に編集しました。
 
@@ -86,7 +86,7 @@ Apply and Close を選択します。
 
 キーボードをリセットしてください。
 
-虫アイコンをクリックし、もし全てうまく行けば Debug パースペクティブに移動します。ここでは、main 関数の最初でプログラムカウンタが停止するので、Play ボタンを押します。全てのデバッガのほとんどの機能は ARM MCU で動作しますが、正確な詳細については google があなたのお友達です！
+虫アイコンをクリックし、もし全てうまく行けば Debug パースペクティブに移動します。ここでは、main 関数の最初でプログラムカウンタが停止し、Play ボタンが押されるのを待ちます。全てのデバッガのほとんどの機能は Arm MCU で動作しますが、正確な詳細については Google があなたのお友達です！
 
 
 ハッピーデバッギング！

docs/ja/cli.md

@@ -1,29 +1,19 @@
-# QMK CLI
+# QMK CLI :id=qmk-cli
 
 <!---
-  original document: 79e6b7866:docs/cli.md
-  git diff 79e6b7866 HEAD -- docs/cli.md | cat
+  original document: 0.8.58:docs/cli.md
+  git diff 0.8.58 HEAD -- docs/cli.md | cat
 -->
 
-このページは QMK CLI のセットアップと使用方法について説明します。
-
-# 概要
+## 概要 :id=overview
 
 QMK CLI を使用すると QMK キーボードの構築と作業が簡単になります。QMK ファームウェアの取得とコンパイル、キーマップの作成などのようなタスクを簡素化し合理化するためのコマンドを多く提供します。
 
-* [グローバル CLI](#global-cli)
-* [ローカル CLI](#local-cli)
-* [CLI コマンド](#cli-commands)
+### 必要事項 :id=requirements
 
-# 必要事項
+CLI は Python 3.5 以上を必要とします。我々は必要事項の数を少なくしようとしていますが、[`requirements.txt`](https://github.com/qmk/qmk_firmware/blob/master/requirements.txt) に列挙されているパッケージもインストールする必要があります。これらは QMK CLI をインストールするときに自動的にインストールされます。
 
-CLI は Python 3.5 以上を必要とします。我々は必要事項の数を少なくしようとしていますが、[`requirements.txt`](https://github.com/qmk/qmk_firmware/blob/master/requirements.txt) にリストされているパッケージもインストールする必要があります。
-
-# グローバル CLI :id=global-cli
-
-QMK は、QMK ビルド環境のセットアップ、QMK の操作、および `qmk_firmware` の複数のコピーの操作を容易にできるインストール可能な CLI を提供します。これを定期的にインストールおよび更新することをお勧めします。
-
-## Homebrew を使ったインストール (macOS、いくつかの Linux)
+### Homebrew を使ったインストール (macOS、いくつかの Linux) :id=install-using-homebrew
 
 [Homebrew](https://brew.sh) をインストールしている場合は、タップして QMK をインストールすることができます:
 
@@ -34,7 +24,7 @@ export QMK_HOME='~/qmk_firmware' # オプション、`qmk_firmware` の場所を
 qmk setup  # これは `qmk/qmk_firmware` をクローンし、オプションでビルド環境をセットアップします
 ```
 
-## easy_install あるいは pip を使ってインストール
+### easy_install あるいは pip を使ってインストール :id=install-using-easy_install-or-pip
 
 上のリストにあなたのシステムがない場合は、QMK を手動でインストールすることができます。最初に、python 3.5 (以降)をインストールしていて、pip をインストールしていることを確認してください。次に以下のコマンドを使って QMK をインストールします:
 
@@ -44,7 +34,7 @@ export QMK_HOME='~/qmk_firmware' # オプション、`qmk_firmware` の場所を
 qmk setup  # これは `qmk/qmk_firmware` をクローンし、オプションでビルド環境をセットアップします
 ```
 
-## 他のオペレーティングシステムのためのパッケージ
+### 他のオペレーティングシステムのためのパッケージ :id=packaging-for-other-operating-systems
 
 より多くのオペレーティングシステム用に `qmk` パッケージを作成および保守する人を探しています。OS 用のパッケージを作成する場合は、以下のガイドラインに従ってください:
 
@@ -52,247 +42,3 @@ qmk setup  # これは `qmk/qmk_firmware` をクローンし、オプション
    * 逸脱する場合は、理由をコメントに文章化してください。
 * virtualenv を使ってインストールしてください
 * 環境変数 `QMK_HOME` を設定して、ファームウェアソースを `~/qmk_firmware` 以外のどこかにチェックアウトするようにユーザに指示してください。
-
-# ローカル CLI :id=local-cli
-
-グローバル CLI を使いたくない場合は、`qmk_firmware` に付属のローカル CLI があります。`qmk_firmware/bin/qmk` で見つけることができます。任意のディレクトリから `qmk` コマンドを実行でき、常に `qmk_firmware` のコピー上で動作します。
-
-**例**:
-
-```
-$ ~/qmk_firmware/bin/qmk hello
-Ψ Hello, World!
-```
-
-## ローカル CLI の制限
-
-グローバル CLI と比較して、ローカル CLI には幾つかの制限があります:
-
-* ローカル CLI は `qmk setup` あるいは `qmk clone` をサポートしません。
-* 複数のリポジトリがクローンされている場合でも、ローカル CLI は常に `qmk_firmware` ツリー上で動作します。
-* ローカル CLI は virtualenv で動作しません。そのため依存関係が競合する可能性があります
-
-# CLI コマンド :id=cli-commands
-
-## `qmk cformat`
-
-このコマンドは clang-format を使って C コードを整形します。引数無しで実行して全てのコアコードを整形するか、コマンドラインでファイル名を渡して特定のファイルに対して実行します。
-
-**使用法**:
-
-```
-qmk cformat [file1] [file2] [...] [fileN]
-```
-
-## `qmk compile`
-
-このコマンドにより、任意のディレクトリからファームウェアをコンパイルすることができます。<https://config.qmk.fm> からエクスポートした JSON をコンパイルするか、リポジトリ内でキーマップをコンパイルするか、現在の作業ディレクトリでキーボードをコンパイルすることができます。
-
-**Configurator Exports での使い方**:
-
-```
-qmk compile <configuratorExport.json>
-```
-
-**キーマップでの使い方**:
-
-```
-qmk compile -kb <keyboard_name> -km <keymap_name>
-```
-
-**キーボードディレクトリでの使い方**:  
-
-default キーマップのあるキーボードディレクトリ、キーボードのキーマップディレクトリ、`--keymap <keymap_name>` で与えられるキーマップディレクトリにいなければなりません。
-```
-qmk compile
-```
-
-**例**:
-```
-$ qmk config compile.keymap=default
-$ cd ~/qmk_firmware/keyboards/planck/rev6
-$ qmk compile
-Ψ Compiling keymap with make planck/rev6:default
-...
-```
-あるいはオプションのキーマップ引数を指定して
-
-```
-$ cd ~/qmk_firmware/keyboards/clueboard/66/rev4
-$ qmk compile -km 66_iso
-Ψ Compiling keymap with make clueboard/66/rev4:66_iso
-...
-```
-あるいはキーマップディレクトリで
-
-```
-$ cd ~/qmk_firmware/keyboards/gh60/satan/keymaps/colemak
-$ qmk compile
-Ψ Compiling keymap with make make gh60/satan:colemak
-...
-```
-
-**レイアウトディレクトリでの使い方**:  
-
-`qmk_firmware/layouts/` 以下のキーマップディレクトリにいなければなりません。
-```
-qmk compile -kb <keyboard_name>
-```
-
-**例**:
-```
-$ cd ~/qmk_firmware/layouts/community/60_ansi/mechmerlin-ansi
-$ qmk compile -kb dz60
-Ψ Compiling keymap with make dz60:mechmerlin-ansi
-...
-```
-
-## `qmk flash`
-
-このコマンドは `qmk compile` に似ていますが、ブートローダを対象にすることもできます。ブートローダはオプションで、デフォルトでは `:flash` に設定されています。
-違うブートローダを指定するには、`-bl <bootloader>` を使ってください。利用可能なブートローダの詳細については、<https://docs.qmk.fm/#/ja/flashing>
-を見てください。
-
-**Configurator Exports での使い方**:
-
-```
-qmk flash <configuratorExport.json> -bl <bootloader>
-```
-
-**キーマップでの使い方**:
-
-```
-qmk flash -kb <keyboard_name> -km <keymap_name> -bl <bootloader>
-```
-
-**ブートローダのリスト**
-
-```
-qmk flash -b
-```
-
-## `qmk config`
-
-このコマンドにより QMK の挙動を設定することができます。完全な `qmk config` のドキュメントについては、[CLI 設定](ja/cli_configuration.md)を見てください。
-
-**使用法**:
-
-```
-qmk config [-ro] [config_token1] [config_token2] [...] [config_tokenN]
-```
-
-## `qmk docs`
-
-このコマンドは、ドキュメントを参照または改善するために使うことができるローカル HTTP サーバを起動します。デフォルトのポートは 8936 です。
-
-**使用法**:
-
-```
-qmk docs [-p PORT]
-```
-
-## `qmk doctor`
-
-このコマンドは環境を調査し、潜在的なビルドあるいは書き込みの問題について警告します。必要に応じてそれらの多くを修正できます。
-
-**使用法**:
-
-```
-qmk doctor [-y] [-n]
-```
-
-**例**:
-
-環境に問題がないか確認し、それらを修正するよう促します:
-
-    qmk doctor
-
-環境を確認し、見つかった問題を自動的に修正します:
-
-    qmk doctor -y
-
-環境を確認し、問題のみをレポートします:
-
-    qmk doctor -n
-
-## `qmk json2c`
-
-QMK Configurator からエクスポートしたものから keymap.c を生成します。
-
-**使用法**:
-
-```
-qmk json2c [-o OUTPUT] filename
-```
-
-## `qmk kle2json`
-
-このコマンドにより、生の KLE データから QMK Configurator の JSON へ変換することができます。絶対パスあるいは現在のディレクトリ内のファイル名のいずれかを受け取ります。デフォルトでは、`info.json` が既に存在している場合は上書きしません。上書きするには、`-f` あるいは `--force` フラグを使ってください。
-
-**使用法**:
-
-```
-qmk kle2json [-f] <filename>
-```
-
-**例**:
-
-```
-$ qmk kle2json kle.txt 
-☒ File info.json already exists, use -f or --force to overwrite.
-```
-
-```
-$ qmk kle2json -f kle.txt -f
-Ψ Wrote out to info.json
-```
-
-## `qmk list-keyboards`
-
-このコマンドは現在 `qmk_firmware` で定義されている全てのキーボードをリスト化します。
-
-**使用法**:
-
-```
-qmk list-keyboards
-```
-
-## `qmk list-keymaps`
-
-このコマンドは指定されたキーボード(とリビジョン)の全てのキーマップをリスト化します。
-
-**使用法**:
-
-```
-qmk list-keymaps -kb planck/ez
-```
-
-## `qmk new-keymap`
-
-このコマンドは、キーボードの既存のデフォルトのキーマップに基づいて新しいキーマップを作成します。
-
-**使用法**:
-
-```
-qmk new-keymap [-kb KEYBOARD] [-km KEYMAP]
-```
-
-## `qmk pyformat`
-
-このコマンドは `qmk_firmware` 内の python コードを整形します。
-
-**使用法**:
-
-```
-qmk pyformat
-```
-
-## `qmk pytest`
-
-このコマンドは python のテストスィートを実行します。python コードに変更を加えた場合、これの実行が成功することを確認する必要があります。
-
-**使用法**:
-
-```
-qmk pytest
-```

docs/ja/cli_commands.md

@@ -0,0 +1,258 @@
+# QMK CLI コマンド
+
+<!---
+  original document: 0.8.58:docs/cli.md
+  git diff 0.8.58 HEAD -- docs/cli.md | cat
+-->
+
+# CLI コマンド
+
+## `qmk cformat`
+
+このコマンドは clang-format を使って C コードを整形します。
+
+引数無しで実行すると、変更された全てのコアコードを整形します。デフォルトでは `git diff` で `origin/master` をチェックし、ブランチは `-b <branch_name>` を使って変更できます。
+
+`-a` で全てのコアコードを整形するか、コマンドラインでファイル名を渡して特定のファイルに対して実行します。
+
+**指定したファイルに対する使い方**:
+
+```
+qmk cformat [file1] [file2] [...] [fileN]
+```
+
+**全てのコアファイルに対する使い方**:
+
+```
+qmk cformat -a
+```
+
+**origin/master で変更されたファイルのみに対する使い方**:
+
+```
+qmk cformat
+```
+
+**branch_name で変更されたファイルのみに対する使い方**:
+
+```
+qmk cformat -b branch_name
+```
+
+## `qmk compile`
+
+このコマンドにより、任意のディレクトリからファームウェアをコンパイルすることができます。<https://config.qmk.fm> からエクスポートした JSON をコンパイルするか、リポジトリ内でキーマップをコンパイルするか、現在の作業ディレクトリでキーボードをコンパイルすることができます。
+
+**Configurator Exports での使い方**:
+
+```
+qmk compile <configuratorExport.json>
+```
+
+**キーマップでの使い方**:
+
+```
+qmk compile -kb <keyboard_name> -km <keymap_name>
+```
+
+**キーボードディレクトリでの使い方**:  
+
+default キーマップのあるキーボードディレクトリ、キーボードのキーマップディレクトリ、`--keymap <keymap_name>` で与えられるキーマップディレクトリにいなければなりません。
+```
+qmk compile
+```
+
+**指定したキーマップをサポートする全てのキーボードをビルドする場合の使い方**:
+
+```
+qmk compile -kb all -km <keymap_name>
+```
+
+**例**:
+```
+$ qmk config compile.keymap=default
+$ cd ~/qmk_firmware/keyboards/planck/rev6
+$ qmk compile
+Ψ Compiling keymap with make planck/rev6:default
+...
+```
+あるいはオプションのキーマップ引数を指定して
+
+```
+$ cd ~/qmk_firmware/keyboards/clueboard/66/rev4
+$ qmk compile -km 66_iso
+Ψ Compiling keymap with make clueboard/66/rev4:66_iso
+...
+```
+あるいはキーマップディレクトリで
+
+```
+$ cd ~/qmk_firmware/keyboards/gh60/satan/keymaps/colemak
+$ qmk compile
+Ψ Compiling keymap with make make gh60/satan:colemak
+...
+```
+
+**レイアウトディレクトリでの使い方**:  
+
+`qmk_firmware/layouts/` 以下のキーマップディレクトリにいなければなりません。
+```
+qmk compile -kb <keyboard_name>
+```
+
+**例**:
+```
+$ cd ~/qmk_firmware/layouts/community/60_ansi/mechmerlin-ansi
+$ qmk compile -kb dz60
+Ψ Compiling keymap with make dz60:mechmerlin-ansi
+...
+```
+
+## `qmk flash`
+
+このコマンドは `qmk compile` に似ていますが、ブートローダを対象にすることもできます。ブートローダはオプションで、デフォルトでは `:flash` に設定されています。
+違うブートローダを指定するには、`-bl <bootloader>` を使ってください。利用可能なブートローダの詳細については、[ファームウェアを書き込む](ja/flashing.md)を見てください。
+
+**Configurator Exports での使い方**:
+
+```
+qmk flash <configuratorExport.json> -bl <bootloader>
+```
+
+**キーマップでの使い方**:
+
+```
+qmk flash -kb <keyboard_name> -km <keymap_name> -bl <bootloader>
+```
+
+**ブートローダの列挙**
+
+```
+qmk flash -b
+```
+
+## `qmk config`
+
+このコマンドにより QMK の挙動を設定することができます。完全な `qmk config` のドキュメントについては、[CLI 設定](ja/cli_configuration.md)を見てください。
+
+**使用法**:
+
+```
+qmk config [-ro] [config_token1] [config_token2] [...] [config_tokenN]
+```
+
+## `qmk docs`
+
+このコマンドは、ドキュメントを参照または改善するために使うことができるローカル HTTP サーバを起動します。デフォルトのポートは 8936 です。
+
+**使用法**:
+
+```
+qmk docs [-p PORT]
+```
+
+## `qmk doctor`
+
+このコマンドは環境を調査し、潜在的なビルドあるいは書き込みの問題について警告します。必要に応じてそれらの多くを修正できます。
+
+**使用法**:
+
+```
+qmk doctor [-y] [-n]
+```
+
+**例**:
+
+環境に問題がないか確認し、それらを修正するよう促します:
+
+    qmk doctor
+
+環境を確認し、見つかった問題を自動的に修正します:
+
+    qmk doctor -y
+
+環境を確認し、問題のみをレポートします:
+
+    qmk doctor -n
+
+## `qmk json2c`
+
+QMK Configurator からエクスポートしたものから keymap.c を生成します。
+
+**使用法**:
+
+```
+qmk json2c [-o OUTPUT] filename
+```
+
+## `qmk kle2json`
+
+このコマンドにより、生の KLE データから QMK Configurator の JSON へ変換することができます。絶対パスあるいは現在のディレクトリ内のファイル名のいずれかを受け取ります。デフォルトでは、`info.json` が既に存在している場合は上書きしません。上書きするには、`-f` あるいは `--force` フラグを使ってください。
+
+**使用法**:
+
+```
+qmk kle2json [-f] <filename>
+```
+
+**例**:
+
+```
+$ qmk kle2json kle.txt 
+☒ File info.json already exists, use -f or --force to overwrite.
+```
+
+```
+$ qmk kle2json -f kle.txt -f
+Ψ Wrote out to info.json
+```
+
+## `qmk list-keyboards`
+
+このコマンドは現在 `qmk_firmware` で定義されている全てのキーボードを列挙します。
+
+**使用法**:
+
+```
+qmk list-keyboards
+```
+
+## `qmk list-keymaps`
+
+このコマンドは指定されたキーボード(とリビジョン)の全てのキーマップを列挙します。
+
+**使用法**:
+
+```
+qmk list-keymaps -kb planck/ez
+```
+
+## `qmk new-keymap`
+
+このコマンドは、キーボードの既存のデフォルトのキーマップに基づいて新しいキーマップを作成します。
+
+**使用法**:
+
+```
+qmk new-keymap [-kb KEYBOARD] [-km KEYMAP]
+```
+
+## `qmk pyformat`
+
+このコマンドは `qmk_firmware` 内の python コードを整形します。
+
+**使用法**:
+
+```
+qmk pyformat
+```
+
+## `qmk pytest`
+
+このコマンドは python のテストスィートを実行します。python コードに変更を加えた場合、これの実行が成功することを確認する必要があります。
+
+**使用法**:
+
+```
+qmk pytest
+```

docs/ja/config_options.md

@@ -1,8 +1,8 @@
 # QMK の設定
 
 <!---
-  original document: 2fe288d01:docs/config_options.md
-  git diff 2fe288d01 HEAD -- docs/config_options.md | cat
+  original document: 0.8.62:docs/config_options.md
+  git diff 0.8.62 HEAD -- docs/config_options.md | cat
 -->
 
 QMK はほぼ無制限に設定可能です。可能なところはいかなるところでも、やりすぎな程、ユーザーがコードサイズを犠牲にしてでも彼らのキーボードをカスタマイズをすることを許しています。ただし、このレベルの柔軟性により設定が困難になります。
@@ -39,167 +39,173 @@ QMK での全ての利用可能な設定にはデフォルトがあります。
 
 ## ハードウェアオプション
 * `#define VENDOR_ID 0x1234`
-   * VID を定義します。ほとんどの DIY プロジェクトにおいて、任意のものを定義できます
+  * VID を定義します。ほとんどの DIY プロジェクトにおいて、任意のものを定義できます
 * `#define PRODUCT_ID 0x5678`
-   * PID を定義します。ほとんどの DIY プロジェクトでは、任意のものを定義できます
+  * PID を定義します。ほとんどの DIY プロジェクトでは、任意のものを定義できます
 * `#define DEVICE_VER 0`
-   * デバイスのバージョンを定義します (多くの場合リビジョンに使われます)
+  * デバイスのバージョンを定義します (多くの場合リビジョンに使われます)
 * `#define MANUFACTURER Me`
-   * 一般的に、誰もしくはどのブランドがボードを作成したか
+  * 一般的に、誰もしくはどのブランドがボードを作成したか
 * `#define PRODUCT Board`
-   * キーボードの名前
+  * キーボードの名前
 * `#define DESCRIPTION a keyboard`
-   * キーボードの簡単な説明
+  * キーボードの簡単な説明
 * `#define MATRIX_ROWS 5`
-   * キーボードのマトリックスの行の数
+  * キーボードのマトリックスの行の数
 * `#define MATRIX_COLS 15`
-   * キーボードのマトリックスの列の数
+  * キーボードのマトリックスの列の数
 * `#define MATRIX_ROW_PINS { D0, D5, B5, B6 }`
-   * 行のピン、上から下へ
+  * 行のピン、上から下へ
 * `#define MATRIX_COL_PINS { F1, F0, B0, C7, F4, F5, F6, F7, D4, D6, B4, D7 }`
-   * 列のピン、左から右へ
+  * 列のピン、左から右へ
+* `#define MATRIX_IO_DELAY 30`
+  * マトリックスピン状態の変更と値の読み取り間のマイクロ秒単位の遅延
 * `#define UNUSED_PINS { D1, D2, D3, B1, B2, B3 }`
-   * 参考として、キーボードで使われていないピン
+  * 参考として、キーボードで使われていないピン
 * `#define MATRIX_HAS_GHOST`
-   * マトリックスにゴーストがあるか(ありそうにないか)定義します
+  * マトリックスにゴーストがあるか(ありそうにないか)定義します
 * `#define DIODE_DIRECTION COL2ROW`
-   * COL2ROW あるいは ROW2COL - マトリックスがどのように設定されているか。COL2ROW は、スイッチとロウ(行)ラインの間にダイオードが黒い印をロウ(行)ラインに向けて置いてあることを意味します。
+  * COL2ROW あるいは ROW2COL - マトリックスがどのように設定されているか。COL2ROW は、スイッチとロウ(行)ラインの間にダイオードが黒い印をロウ(行)ラインに向けて置いてあることを意味します。
 * `#define DIRECT_PINS { { F1, F0, B0, C7 }, { F4, F5, F6, F7 } }`
-   * ロウ(行)ラインとカラム(列)ラインにマップされているピンを左から右に。各スイッチが個別のピンとグラウンドに接続されているマトリックスを定義します。
+  * ロウ(行)ラインとカラム(列)ラインにマップされているピンを左から右に。各スイッチが個別のピンとグラウンドに接続されているマトリックスを定義します。
 * `#define AUDIO_VOICES`
-   * (循環させるために)代替音声を有効にします
+  * (循環させるために)代替音声を有効にします
 * `#define C4_AUDIO`
-   * ピン C4 のオーディオを有効にします
+  * ピン C4 のオーディオを有効にします
 * `#define C5_AUDIO`
-   * ピン C5 のオーディオを有効にします
+  * ピン C5 のオーディオを有効にします
 * `#define C6_AUDIO`
-   * ピン C6 のオーディオを有効にします
+  * ピン C6 のオーディオを有効にします
 * `#define B5_AUDIO`
-   * ピン B5 のオーディオを有効にします (C[4-6]\_AUDIO の1つとともに B[5-7]\_AUDIO の1つが有効にされている場合、疑似ステレオが有効にされます)
+  * ピン B5 のオーディオを有効にします (C[4-6]\_AUDIO の1つとともに B[5-7]\_AUDIO の1つが有効にされている場合、疑似ステレオが有効にされます)
 * `#define B6_AUDIO`
-   * ピン B6 のオーディオを有効にします (C[4-6]\_AUDIO の1つとともに B[5-7]\_AUDIO の1つが有効にされている場合、疑似ステレオが有効にされます)
+  * ピン B6 のオーディオを有効にします (C[4-6]\_AUDIO の1つとともに B[5-7]\_AUDIO の1つが有効にされている場合、疑似ステレオが有効にされます)
 * `#define B7_AUDIO`
-   * ピン B7 のオーディオを有効にします (C[4-6]\_AUDIO の1つとともに B[5-7]\_AUDIO の1つが有効にされている場合、疑似ステレオが有効にされます)
+  * ピン B7 のオーディオを有効にします (C[4-6]\_AUDIO の1つとともに B[5-7]\_AUDIO の1つが有効にされている場合、疑似ステレオが有効にされます)
 * `#define BACKLIGHT_PIN B7`
-   * バックライトのピン
+  * バックライトのピン
 * `#define BACKLIGHT_LEVELS 3`
-   * バックライトのレベル数 (off を除いて最大31)
+  * バックライトのレベル数 (off を除いて最大31)
 * `#define BACKLIGHT_BREATHING`
-   * バックライトのブレスを有効にします
+  * バックライトのブレスを有効にします
 * `#define BREATHING_PERIOD 6`
-   * 1つのバックライトの "ブレス" の長さの秒数
+  * 1つのバックライトの "ブレス" の長さの秒数
 * `#define DEBOUNCE 5`
-   * ピンの値を読み取る時の遅延 (5がデフォルト)
+  * ピンの値を読み取る時の遅延 (5がデフォルト)
 * `#define LOCKING_SUPPORT_ENABLE`
-   * メカニカルロックのサポート。キーマップで KC_LCAP、 KC_LNUM そして KC_LSCR を使えるようにします
+  * メカニカルロックのサポート。キーマップで KC_LCAP、 KC_LNUM そして KC_LSCR を使えるようにします
 * `#define LOCKING_RESYNC_ENABLE`
-   * キーボードの LED の状態をスイッチの状態と一致させ続けようとします
+  * キーボードの LED の状態をスイッチの状態と一致させ続けようとします
 * `#define IS_COMMAND() (get_mods() == MOD_MASK_SHIFT)`
-   * マジックコマンドの使用を可能にするキーの組み合わせ (デバッグに便利です)
+  * マジックコマンドの使用を可能にするキーの組み合わせ (デバッグに便利です)
 * `#define USB_MAX_POWER_CONSUMPTION 500`
-   * デバイスの USB 経由の最大電力(mA) を設定します (デフォルト: 500)
+  * デバイスの USB 経由の最大電力(mA) を設定します (デフォルト: 500)
 * `#define USB_POLLING_INTERVAL_MS 10`
-   * キーボード、マウス および 共有 (NKRO/メディアキー) インタフェースのための USB ポーリングレートをミリ秒で設定します
+  * キーボード、マウス および 共有 (NKRO/メディアキー) インタフェースのための USB ポーリングレートをミリ秒で設定します
 * `#define F_SCL 100000L`
-   * I2C を使用するキーボードのための I2C クロックレート速度を設定します。デフォルトは `400000L` ですが、`split_common` を使っているキーボードは別でデフォルトは `100000L` です。
+  * I2C を使用するキーボードのための I2C クロックレート速度を設定します。デフォルトは `400000L` ですが、`split_common` を使っているキーボードは別でデフォルトは `100000L` です。
 
 ## 無効にできる機能
 
 これらのオプションを定義すると、関連する機能が無効になり、コードサイズを節約できます。
 
 * `#define NO_DEBUG`
-   * デバッグを無効にします
+  * デバッグを無効にします
 * `#define NO_PRINT`
-   * hid_listen を使った出力やデバッグを無効にします
+  * hid_listen を使った出力やデバッグを無効にします
 * `#define NO_ACTION_LAYER`
-   * レイヤーを無効にします
+  * レイヤーを無効にします
 * `#define NO_ACTION_TAPPING`
-   * タップダンスと他のタップ機能を無効にします
+  * タップダンスと他のタップ機能を無効にします
 * `#define NO_ACTION_ONESHOT`
-   * ワンショットモディファイアを無効にします
+  * ワンショットモディファイアを無効にします
 * `#define NO_ACTION_MACRO`
-   * 古い形式のマクロ処理を無効にします: MACRO() & action_get_macro
+  * 古い形式のマクロ処理を無効にします: MACRO() & action_get_macro
 * `#define NO_ACTION_FUNCTION`
-   * fn_actions 配列(非推奨)からの action_function() の呼び出しを無効にします 
+  * fn_actions 配列(非推奨)からの action_function() の呼び出しを無効にします 
 
 ## 有効にできる機能
 
 これらのオプションを定義すると、関連する機能が有効になり、コードサイズが大きくなるかもしれません。
 
 * `#define FORCE_NKRO`
-   * NKRO をデフォルトでオンにする必要があります。これにより EEPROM の設定に関係なく、キーボードの起動時に NKRO が強制的にオンになります。NKRO は引き続きオフにできますが、キーボードを再起動すると再びオンになります。
+  * NKRO をデフォルトでオンにする必要があります。これにより EEPROM の設定に関係なく、キーボードの起動時に NKRO が強制的にオンになります。NKRO は引き続きオフにできますが、キーボードを再起動すると再びオンになります。
 * `#define STRICT_LAYER_RELEASE`
-   * キーリリースがどのレイヤーから来たのかを覚えるのではなく、現在のレイヤースタックを使って強制的に評価されるようにします (高度なケースに使われます)
+  * キーリリースがどのレイヤーから来たのかを覚えるのではなく、現在のレイヤースタックを使って強制的に評価されるようにします (高度なケースに使われます)
 
 ## 設定可能な挙動
 
 * `#define TAPPING_TERM 200`
-   * タップがホールドになるまでの時間。500以上に設定された場合、タップ期間中にタップされたキーもホールドになります。(訳注: PERMISSIVE_HOLDも参照)
+  * タップがホールドになるまでの時間。500以上に設定された場合、タップ期間中にタップされたキーもホールドになります。(訳注: PERMISSIVE_HOLDも参照)
 * `#define TAPPING_TERM_PER_KEY`
-   * キーごとの `TAPPING_TERM` 設定の処理を有効にします
+  * キーごとの `TAPPING_TERM` 設定の処理を有効にします
 * `#define RETRO_TAPPING`
-   * 押下とリリースの間に他のキーによる中断がなければ、TAPPING_TERM の後であってもとにかくタップします
-   * 詳細は [Retro Tapping](ja/feature_advanced_keycodes.md#retro-tapping) を見てください
+  * 押下とリリースの間に他のキーによる中断がなければ、TAPPING_TERM の後であってもとにかくタップします
+  * 詳細は [Retro Tapping](ja/tap_hold.md#retro-tapping) を見てください
 * `#define TAPPING_TOGGLE 2`
-   * トグルを引き起こす前のタップ数
+  * トグルを引き起こす前のタップ数
 * `#define PERMISSIVE_HOLD`
-   * `TAPPING_TERM` にヒットしていなくても、リリースする前に別のキーが押されると、タップとフォールドキーがホールドを引き起こします
-   * 詳細は [Permissive Hold](ja/feature_advanced_keycodes.md#permissive-hold) を見てください
+  * `TAPPING_TERM` にヒットしていなくても、リリースする前に別のキーが押されると、タップとホールドキーがホールドを引き起こします
+  * 詳細は [Permissive Hold](ja/tap_hold.md#permissive-hold) を見てください
+* `#define PERMISSIVE_HOLD_PER_KEY`
+  * キーごとの `PERMISSIVE_HOLD` 設定の処理を有効にします
 * `#define IGNORE_MOD_TAP_INTERRUPT`
-   * 両方のキーに `TAPPING_TERM` を適用することで、ホールド時に他のキーに変換するキーを使ってローリングコンボ (zx) をすることができるようにします
-   * 詳細は [Mod tap interrupt](ja/feature_advanced_keycodes.md#ignore-mod-tap-interrupt) を見てください
+  * 両方のキーに `TAPPING_TERM` を適用することで、ホールド時に他のキーに変換するキーを使ってローリングコンボ (zx) をすることができるようにします
+  * 詳細は [Ignore Mod Tap Interrupt](ja/tap_hold.md#ignore-mod-tap-interrupt) を見てください
 * `#define IGNORE_MOD_TAP_INTERRUPT_PER_KEY`
-   * キーごとの `IGNORE_MOD_TAP_INTERRUPT` 設定の処理を有効にします
+  * キーごとの `IGNORE_MOD_TAP_INTERRUPT` 設定の処理を有効にします
 * `#define TAPPING_FORCE_HOLD`
-   * タップされた直後に、デュアルロールキーを修飾子として使用できるようにします
-   * [Hold after tap](ja/feature_advanced_keycodes.md#tapping-force-hold)を見てください
-   * タップトグル機能を無効にします (`TT` あるいは One Shot Tap Toggle)
+  * タップされた直後に、デュアルロールキーを修飾子として使用できるようにします
+  * [Tapping Force Hold](ja/tap_hold.md#tapping-force-hold)を見てください
+  * タップトグル機能を無効にします (`TT` あるいは One Shot Tap Toggle)
 * `#define TAPPING_FORCE_HOLD_PER_KEY`
-   * キーごとの `TAPPING_FORCE_HOLD` 設定処理を有効にします。
+  * キーごとの `TAPPING_FORCE_HOLD` 設定処理を有効にします。
 * `#define LEADER_TIMEOUT 300`
-   * リーダーキーがタイムアウトするまでの時間
-      * タイムアウトする前にシーケンスを終了できない場合は、タイムアウトの設定を増やす必要があるかもしれません。あるいは、`LEADER_PER_KEY_TIMING` オプションを有効にすると良いでしょう。これは各キーがタップされた後でタイムアウトを再設定します。
+  * リーダーキーがタイムアウトするまでの時間
+    * タイムアウトする前にシーケンスを終了できない場合は、タイムアウトの設定を増やす必要があるかもしれません。あるいは、`LEADER_PER_KEY_TIMING` オプションを有効にすると良いでしょう。これは各キーがタップされた後でタイムアウトを再設定します。
 * `#define LEADER_PER_KEY_TIMING`
-   * 全体では無く各キーを押すたびに実行されるリーダーキーコードのタイマーを設定します
+  * 全体では無く各キーを押すたびに実行されるリーダーキーコードのタイマーを設定します
 * `#define LEADER_KEY_STRICT_KEY_PROCESSING`
-   * Mod-Tap および Layer-Tap キーコードのためのキーコードフィルタリングを無効にします。例えば、これを有効にすると、`KC_A` を使いたい場合は `MT(MOD_CTL, KC_A)` を指定する必要があります。
+  * Mod-Tap および Layer-Tap キーコードのためのキーコードフィルタリングを無効にします。例えば、これを有効にすると、`KC_A` を使いたい場合は `MT(MOD_CTL, KC_A)` を指定する必要があります。
 * `#define ONESHOT_TIMEOUT 300`
-   * ワンショットがタイムアウトするまでの時間
+  * ワンショットがタイムアウトするまでの時間
 * `#define ONESHOT_TAP_TOGGLE 2`
-   * ワンショットトグルが引き起こされるまでのタップ数
+  * ワンショットトグルが引き起こされるまでのタップ数
 * `#define QMK_KEYS_PER_SCAN 4`
-   * 走査ごとに1つ以上のキーを送信できるようにします。デフォルトでは、走査ごとに `process_record()` 経由で1つのキーイベントのみが送信されます。これはほとんどのタイピングにほとんど影響しませんが、多くのコードを入力しているか、走査レートが最初から遅い場合、キーイベントの処理に多少の遅延が生じる可能性があります。それぞれのプレスとリリースは別のイベントです。スキャン時間が 1ms 程度のキーボードの場合、とても高速なタイピストでさえ、実際にキーボードから数 ms 以上の遅延を発生させるのに必要な 500 キーストロークを1秒間に生成することはないでしょう。しかし、3～4ms の走査時間でコードを入力している場合はどうでしょうか？おそらくこれが必要です。
+  * 走査ごとに1つ以上のキーを送信できるようにします。デフォルトでは、走査ごとに `process_record()` 経由で1つのキーイベントのみが送信されます。これはほとんどのタイピングにほとんど影響しませんが、多くのコードを入力しているか、走査レートが最初から遅い場合、キーイベントの処理に多少の遅延が生じる可能性があります。それぞれのプレスとリリースは別のイベントです。スキャン時間が 1ms 程度のキーボードの場合、とても高速なタイピストでさえ、実際にキーボードから数 ms 以上の遅延を発生させるのに必要な 500 キーストロークを1秒間に生成することはないでしょう。しかし、3～4ms の走査時間でコードを入力している場合はどうでしょうか？おそらくこれが必要です。
 * `#define COMBO_COUNT 2`
-   * [コンボ](ja/feature_combo.md)機能で使っているコンボの数にこれを設定します。
+  * [コンボ](ja/feature_combo.md)機能で使っているコンボの数にこれを設定します。
 * `#define COMBO_TERM 200`
-   * コンボキーが検出されるまでの時間。定義されていない場合は、デフォルトは `TAPPING_TERM` です。
+  * コンボキーが検出されるまでの時間。定義されていない場合は、デフォルトは `TAPPING_TERM` です。
 * `#define TAP_CODE_DELAY 100`
-   * 適切な登録に問題がある場合(VUSB ボードで珍しくない)、`register_code` と `unregister_code` の間の遅延を設定します。値はミリ秒です。
+  * 適切な登録に問題がある場合(VUSB ボードで珍しくない)、`register_code` と `unregister_code` の間の遅延を設定します。値はミリ秒です。
 * `#define TAP_HOLD_CAPS_DELAY 80`
-   * MacOS で特別な処理が行われるため、`KC_CAPSLOCK` を使う時にタップホールドキー (`LT`, `MT`) に遅延を設定します。この値はミリ秒で、定義されていない場合はデフォルトは80msです。macOS については、これを200以上に設定すると良いでしょう。
+  * MacOS で特別な処理が行われるため、`KC_CAPSLOCK` を使う時にタップホールドキー (`LT`, `MT`) に遅延を設定します。この値はミリ秒で、定義されていない場合はデフォルトは80msです。macOS については、これを200以上に設定すると良いでしょう。
 
 ## RGB ライト設定 :id=rgb-light-configuration
 
 * `#define RGB_DI_PIN D7`
-   * WS2812 の DI 端子につなぐピン
+  * WS2812 の DI 端子につなぐピン
 * `#define RGBLIGHT_ANIMATIONS`
-   * RGB アニメーションを実行します
+  * RGB アニメーションを実行します
+* `#define RGBLIGHT_LAYERS`
+  * オンとオフを切り替えることができる [ライトレイヤー](ja/feature_rgblight.md) を定義できます。現在のキーボードレイヤーまたは Caps Lock 状態を表示するのに最適です。
 * `#define RGBLED_NUM 12`
-   * LED の数
+  * LED の数
 * `#define RGBLIGHT_SPLIT`
-   * 分割キーボードの左半分の RGB LED の出力を右半分の RGB LED の入力につなげるかわりに、それぞれの側で個別にコントローラの出力ピンが直接 RGB LED の入力に繋がっているときは、この定義が必要です。
+  * 分割キーボードの左半分の RGB LED の出力を右半分の RGB LED の入力につなげるかわりに、それぞれの側で個別にコントローラの出力ピンが直接 RGB LED の入力に繋がっているときは、この定義が必要です。
 * `#define RGBLED_SPLIT { 6, 6 }`
-   * 分割キーボードの各半分の `RGB_DI_PIN` に直接配線されている接続されている LED の数
-   * 最初の値は左半分の LED の数を示し、2番目の値は右半分です。
-   * RGBLED_SPLIT が定義されている場合、RGBLIGHT_SPLIT は暗黙的に定義されます。
+  * 分割キーボードの各半分の `RGB_DI_PIN` に直接配線されている接続されている LED の数
+  * 最初の値は左半分の LED の数を示し、2番目の値は右半分です。
+  * RGBLED_SPLIT が定義されている場合、RGBLIGHT_SPLIT は暗黙的に定義されます。
 * `#define RGBLIGHT_HUE_STEP 12`
-   * 色相の増減時のステップ単位
+  * 色相の増減時のステップ単位
 * `#define RGBLIGHT_SAT_STEP 25`
-   * 彩度の増減時のステップ単位
+  * 彩度の増減時のステップ単位
 * `#define RGBLIGHT_VAL_STEP 12`
-   * 値(明度)の増減時のステップ単位
+  * 値(明度)の増減時のステップ単位
 * `#define RGBW`
-   * RGBW LED のサポートを有効にします
+  * RGBW LED のサポートを有効にします
 
 ## マウスキーオプション
 
@@ -214,7 +220,7 @@ QMK での全ての利用可能な設定にはデフォルトがあります。
 分割キーボード固有のオプション。あなたの rules.mk に 'SPLIT_KEYBOARD = yes' が有ることを確認してください。
 
 * `SPLIT_TRANSPORT = custom`
-   * 標準の分割通信ルーチンをカスタムのものに置き換えることができます。現在、ARM ベースの分割キーボードはこれを使わなければなりません。
+  * 標準の分割通信ルーチンをカスタムのものに置き換えることができます。現在、ARM ベースの分割キーボードはこれを使わなければなりません。
 
 ### 左右の設定
 
@@ -233,52 +239,52 @@ QMK での全ての利用可能な設定にはデフォルトがあります。
 #### 左右を定義します
 
 * `#define SPLIT_HAND_PIN B7`
-   * high/low ピンを使って左右を決定します。low = 右手、high = 左手。`B7` を使っているピンに置き換えます。これはオプションで、`SPLIT_HAND_PIN` が未定義のままである場合、EE_HANDS メソッドまたは標準の Let's Splitが使っている MASTER_LEFT / MASTER_RIGHT 定義をまだ使うことができます。
+  * high/low ピンを使って左右を決定します。low = 右手、high = 左手。`B7` を使っているピンに置き換えます。これはオプションで、`SPLIT_HAND_PIN` が未定義のままである場合、EE_HANDS メソッドまたは標準の Let's Splitが使っている MASTER_LEFT / MASTER_RIGHT 定義をまだ使うことができます。
 
 * `#define EE_HANDS` (`SPLIT_HAND_PIN` が定義されていない場合のみ動作します)
-   * `eeprom-lefthand.eep`/`eeprom-righthand.eep` がそれぞれの半分に書き込まれた後で、EEPROM 内に格納されている左右の設定の値を読み込みます。
+  * `eeprom-lefthand.eep`/`eeprom-righthand.eep` がそれぞれの半分に書き込まれた後で、EEPROM 内に格納されている左右の設定の値を読み込みます。
 
 * `#define MASTER_RIGHT`
-   * マスター側が右側と定義されます。
+  * マスター側が右側と定義されます。
 
 ### 他のオプション
 
 * `#define USE_I2C`
-   * Serial の代わりに I2C を使う場合 (デフォルトは serial)
+  * Serial の代わりに I2C を使う場合 (デフォルトは serial)
 
 * `#define SOFT_SERIAL_PIN D0`
-   * serial を使う場合、これを定義します。`D0` あるいは `D1`,`D2`,`D3`,`E6`。
+  * serial を使う場合、これを定義します。`D0` あるいは `D1`,`D2`,`D3`,`E6`。
 
 * `#define MATRIX_ROW_PINS_RIGHT { <row pins> }`
 * `#define MATRIX_COL_PINS_RIGHT { <col pins> }`
-   * 右半分に左半分と異なるピン配置を指定したい場合は、`MATRIX_ROW_PINS_RIGHT`/`MATRIX_COL_PINS_RIGHT` を定義することができます。現在のところ、`MATRIX_ROW_PINS` のサイズは `MATRIX_ROW_PINS_RIGHT` と同じでなければならず、列の定義も同様です。
+  * 右半分に左半分と異なるピン配置を指定したい場合は、`MATRIX_ROW_PINS_RIGHT`/`MATRIX_COL_PINS_RIGHT` を定義することができます。現在のところ、`MATRIX_ROW_PINS` のサイズは `MATRIX_ROW_PINS_RIGHT` と同じでなければならず、列の定義も同様です。
 
 * `#define DIRECT_PINS_RIGHT { { F1, F0, B0, C7 }, { F4, F5, F6, F7 } }`
-   * 右半分に左半分と異なる直接ピン配置を指定したい場合は、`DIRECT_PINS_RIGHT` を定義することができます。現在のところ、`DIRECT_PINS` のサイズは `DIRECT_PINS_RIGHT` と同じでなければなりません。
+  * 右半分に左半分と異なる直接ピン配置を指定したい場合は、`DIRECT_PINS_RIGHT` を定義することができます。現在のところ、`DIRECT_PINS` のサイズは `DIRECT_PINS_RIGHT` と同じでなければなりません。
 
 * `#define RGBLED_SPLIT { 6, 6 }`
-   * [RGB ライト設定](#rgb-light-configuration)を見てください。
+  * [RGB ライト設定](#rgb-light-configuration)を見てください。
 
 * `#define SELECT_SOFT_SERIAL_SPEED <speed>` (デフォルトの速度は1です)
-   * serial 通信を使う時のプロトコルの速度を設定します。
-   * 速度:
-      * 0: 約 189kbps (実験目的のみ)
-      * 1: 約 137kbps (デフォルト)
-      * 2: 約 75kbps
-      * 3: 約 39kbps
-      * 4: 約 26kbps
-      * 5: 約 20kbps
+  * serial 通信を使う時のプロトコルの速度を設定します。
+  * 速度:
+    * 0: 約 189kbps (実験目的のみ)
+    * 1: 約 137kbps (デフォルト)
+    * 2: 約 75kbps
+    * 3: 約 39kbps
+    * 4: 約 26kbps
+    * 5: 約 20kbps
 
 * `#define SPLIT_USB_DETECT`
-   * マスタ/スレーブを委任する時に(タイムアウト付きで) USB 接続を検出します
-   * ARM についてはデフォルトの挙動
-   * AVR Teensy については必須
+  * マスタ/スレーブを委任する時に(タイムアウト付きで) USB 接続を検出します
+  * ARM についてはデフォルトの挙動
+  * AVR Teensy については必須
 
 * `#define SPLIT_USB_TIMEOUT 2000`
-   * `SPLIT_USB_DETECT` を使う時のマスタ/スレーブを検出する場合の最大タイムアウト
+  * `SPLIT_USB_DETECT` を使う時のマスタ/スレーブを検出する場合の最大タイムアウト
 
 * `#define SPLIT_USB_TIMEOUT_POLL 10`
-   * `SPLIT_USB_DETECT` を使う時のマスタ/スレーブを検出する場合のポーリング頻度
+  * `SPLIT_USB_DETECT` を使う時のマスタ/スレーブを検出する場合のポーリング頻度
 
 # `rules.mk` ファイル
 
@@ -287,11 +293,11 @@ QMK での全ての利用可能な設定にはデフォルトがあります。
 ## ビルドオプション
 
 * `DEFAULT_FOLDER`
-   * キーボードに1つ以上のサブフォルダがある場合にデフォルトのフォルダを指定するために使われます。
+  * キーボードに1つ以上のサブフォルダがある場合にデフォルトのフォルダを指定するために使われます。
 * `FIRMWARE_FORMAT`
-   * ビルドの後でルート `qmk_firmware` フォルダにコピーされる形式 (bin, hex) を定義します。
+  * ビルドの後でルート `qmk_firmware` フォルダにコピーされる形式 (bin, hex) を定義します。
 * `SRC`
-   * コンパイル・リンクリストにファイルを追加するために使われます。
+  * コンパイル・リンクリストにファイルを追加するために使われます。
 * `LIB_SRC`
   * コンパイル・リンクリストにライブラリとしてファイルを追加するために使われます。  
     `LIB_SRC` で指定されたファイルは、`SRC` で指定されたファイルの後にリンクされます。  
@@ -307,11 +313,11 @@ QMK での全ての利用可能な設定にはデフォルトがあります。
      ...  a.o c.o  ...  lib_b.a lib_d.a  ...
     ```
 * `LAYOUTS`
-   * このキーボードがサポートする[レイアウト](ja/feature_layouts.md)のリスト
+  * このキーボードがサポートする[レイアウト](ja/feature_layouts.md)のリスト
 * `LINK_TIME_OPTIMIZATION_ENABLE`
-   * キーボードをコンパイルする時に、Link Time Optimization (`LTO`) を有効にします。これは処理に時間が掛かりますが、コンパイルされたサイズを大幅に減らします (そして、ファームウェアが小さいため、追加の時間は分からないくらいです)。ただし、`LTO` が有効な場合、古いマクロと関数の機能が壊れるため、自動的にこれらの機能を無効にします。これは `NO_ACTION_MACRO` と `NO_ACTION_FUNCTION` を自動的に定義することで行われます。
+  * キーボードをコンパイルする時に、Link Time Optimization (`LTO`) を有効にします。これは処理に時間が掛かりますが、コンパイルされたサイズを大幅に減らします (そして、ファームウェアが小さいため、追加の時間は分からないくらいです)。ただし、`LTO` が有効な場合、古いマクロと関数の機能が壊れるため、自動的にこれらの機能を無効にします。これは `NO_ACTION_MACRO` と `NO_ACTION_FUNCTION` を自動的に定義することで行われます。
 * `LTO_ENABLE`
-   * LINK_TIME_OPTIMIZATION_ENABLE と同じ意味です。`LINK_TIME_OPTIMIZATION_ENABLE` の代わりに `LTO_ENABLE` を使うことができます。
+  * LINK_TIME_OPTIMIZATION_ENABLE と同じ意味です。`LINK_TIME_OPTIMIZATION_ENABLE` の代わりに `LTO_ENABLE` を使うことができます。
 
 ## AVR MCU オプション
 * `MCU = atmega32u4`
@@ -320,56 +326,56 @@ QMK での全ての利用可能な設定にはデフォルトがあります。
 * `F_USB = $(F_CPU)`
 * `OPT_DEFS += -DINTERRUPT_CONTROL_ENDPOINT`
 * `BOOTLOADER = atmel-dfu` と以下のオプション:
-   * `atmel-dfu`
-   * `lufa-dfu`
-   * `qmk-dfu`
-   * `halfkay`
-   * `caterina`
-   * `bootloadHID`
-   * `USBasp`
+  * `atmel-dfu`
+  * `lufa-dfu`
+  * `qmk-dfu`
+  * `halfkay`
+  * `caterina`
+  * `bootloadHID`
+  * `USBasp`
 
-## 機能オプション
+## 機能オプション :id=feature-options
 
 これらを使って特定の機能のビルドを有効または無効にします。有効にすればするほどファームウェアが大きくなり、MCU には大きすぎるファームウェアを構築するリスクがあります。
 
 * `BOOTMAGIC_ENABLE`
-   * 仮想 DIP スイッチ設定
+  * 仮想 DIP スイッチ設定
 * `MOUSEKEY_ENABLE`
-   * マウスキー
+  * マウスキー
 * `EXTRAKEY_ENABLE`
-   * オーディオ制御とシステム制御
+  * オーディオ制御とシステム制御
 * `CONSOLE_ENABLE`
-   * デバッグ用コンソール
+  * デバッグ用コンソール
 * `COMMAND_ENABLE`
-   * デバッグ及び設定用のコマンド
+  * デバッグ及び設定用のコマンド
 * `COMBO_ENABLE`
-   * キーコンボ機能
+  * キーコンボ機能
 * `NKRO_ENABLE`
-   * USB N-キーロールオーバー - これが動作しない場合は、ここを見てください: https://github.com/tmk/tmk_keyboard/wiki/FAQ#nkro-doesnt-work
+  * USB N-キーロールオーバー - これが動作しない場合は、ここを見てください: https://github.com/tmk/tmk_keyboard/wiki/FAQ#nkro-doesnt-work
 * `AUDIO_ENABLE`
-   * オーディオサブシステムを有効にします。
+  * オーディオサブシステムを有効にします。
 * `RGBLIGHT_ENABLE`
-   * キーボードアンダーライト機能を有効にします
+  * キーボードアンダーライト機能を有効にします
 * `LEADER_ENABLE`
-   * リーダーキーコードを有効にします
+  * リーダーキーコードを有効にします
 * `MIDI_ENABLE`
-   * MIDI 制御
+  * MIDI 制御
 * `UNICODE_ENABLE`
-   * Unicode
+  * Unicode
 * `BLUETOOTH_ENABLE`
-   * Adafruit EZ-Key HID で Bluetooth を有効にするレガシーオプション。BLUETOOTH を見てください
+  * Adafruit EZ-Key HID で Bluetooth を有効にするレガシーオプション。BLUETOOTH を見てください
 * `BLUETOOTH`
-   * 現在のオプションは、AdafruitEzKey、AdafruitBLE、RN42
+  * 現在のオプションは、AdafruitEzKey、AdafruitBLE、RN42
 * `SPLIT_KEYBOARD`
-   * 分割キーボード (let's split や bakingpy のキーボードのようなデュアル MCU) のサポートを有効にし、quantum/split_common にある全ての必要なファイルをインクルードします
+  * 分割キーボード (let's split や bakingpy のキーボードのようなデュアル MCU) のサポートを有効にし、quantum/split_common にある全ての必要なファイルをインクルードします
 * `CUSTOM_MATRIX`
-   * 標準マトリックス走査ルーチンを独自のものに置き換えることができます。
+  * 標準マトリックス走査ルーチンを独自のものに置き換えることができます。
 * `DEBOUNCE_TYPE`
-   * 標準キーデバウンスルーチンを代替または独自のものに置き換えることができます。
+  * 標準キーデバウンスルーチンを代替または独自のものに置き換えることができます。
 * `WAIT_FOR_USB`
-   * キーボードが起動する前に、USB 接続が確立されるのをキーボードに待機させます
+  * キーボードが起動する前に、USB 接続が確立されるのをキーボードに待機させます
 * `NO_USB_STARTUP_CHECK`
-   * キーボードの起動後の usb サスペンドチェックを無効にします。通常、キーボードはタスクが実行される前にホストがウェイク アップするのを待ちます。分割キーボードは半分はウェイクアップコールを取得できませんが、マスタにコマンドを送信する必要があるため、役に立ちます。
+  * キーボードの起動後の usb サスペンドチェックを無効にします。通常、キーボードはタスクが実行される前にホストがウェイク アップするのを待ちます。分割キーボードは半分はウェイクアップコールを取得できませんが、マスタにコマンドを送信する必要があるため、役に立ちます。
 
 ## USB エンドポイントの制限
 

docs/ja/contributing.md

@@ -1,8 +1,8 @@
 # 貢献方法
 
 <!---
-  original document: d47809575:docs/contributing.md
-  git diff d47809575 HEAD -- docs/contributing.md | cat
+  original document: 0.8.62:docs/contributing.md
+  git diff 0.8.62 HEAD -- docs/contributing.md | cat
 -->
 
 👍🎉 まず、これを読み貢献する時間を作ってくれてありがとうございます！🎉👍
@@ -106,7 +106,7 @@ enum my_keycodes {
 };
 ```
 
-### ドキュメントのプレビュー
+### ドキュメントのプレビュー :id=previewing-the-documentation
 
 開発環境をセットアップした場合は、プルリクエストを開く前に以下のコマンドを `qmk_firmware/` フォルダから実行することで、あなたの変更をプレビューすることができます:
 
@@ -122,7 +122,7 @@ enum my_keycodes {
 
 ほとんどの初めての QMK 貢献者は、個人のキーマップから始めます。キーマップの標準はかなりカジュアルなものにしようとしています(キーマップは結局のところ作成者の性格を反映しています)が、他の人があなたのキーマップを簡単に見つけて学ぶことができるように、これらのガイドラインに従うようにお願いします。
 
-* [the template](documentation_templates.md) を使って `readme.md` を書きます。
+* [テンプレート](documentation_templates.md) を使って `readme.md` を書きます。
 * 全てのキーマップの PR は squash されるため、コミットがどのように squash されるかを気にする場合は、自分で行う必要があります。
 * キーマップの PR に機能をまとめないでください。最初に機能をサブミットし、次にキーマップのための2つ目の PR をサブミットします。
 * `Makefile` をキーマップフォルダに含めないでください(もう使われていません)。
@@ -134,7 +134,7 @@ enum my_keycodes {
 
 また以下のガイドラインに従うことをお願いします:
 
-* [the template](ja/documentation_templates.md) を使って `readme.md` を書きます。
+* [テンプレート](ja/documentation_templates.md) を使って `readme.md` を書きます。
 * コミットの数を適切に保ってください。そうでなければあなたの PR を squash します。
 * コア機能を新しいキーボードにまとめないでください。最初に機能をサブミットし、次にキーボード用に別の PR をサブミットしてください。
 * `.c`/`.h` ファイルにすぐ上の親フォルダに従って名前を付けます。例えば、`/keyboards/<kb1>/<kb2>/<kb2>.[ch]`

docs/ja/custom_matrix.md

@@ -0,0 +1,114 @@
+# カスタムマトリックス
+
+<!---
+  grep --no-filename "^[ ]*git diff" docs/ja/*.md | sh
+  original document: 0.8.46:docs/custom_matrix.md
+  git diff 0.8.46 HEAD -- docs/custom_matrix.md | cat
+-->
+
+QMKは、デフォルトのマトリックススキャンルーチンを独自のコードで部分的に入れ替えたり全部入れ替えたりしたりするメカニズムを提供します。
+
+この機能を使用する理由は次のとおりです:
+
+* キーボードのスイッチと MCU ピンの間に追加のハードウェアがある場合
+  * I/O マルチプレクサ
+  * ラインデコーダー
+* 一般的ではないキースイッチマトリックス
+  * `COL2ROW` と `ROW2COL` の同時使用
+
+## 前提条件
+
+カスタムマトリックスの実装には、通常、追加のソースファイルのコンパイルが含まれます。
+一貫性を保つために、このソースファイルのファイル名は `matrix.c` とすることをお勧めします。
+
+あなたのキーボードディレクトリに新しいファイルを追加します:
+```text
+keyboards/<keyboard>/matrix.c
+```
+
+そして、新しいファイルのコンパイルを指定するため、以下を `rules.mk` に追加します
+```make
+SRC += matrix.c
+```
+
+## マトリックスコードの部分置き換え
+
+カスタムマトリックスを実装する際、定型コードを書かなくてすむように、さまざまなスキャン関数のデフォルト実装を提供しています。
+
+設定するには、以下を `rules.mk` に追加します：
+```make
+CUSTOM_MATRIX = lite
+```
+
+そして、キーボードディレクトリの `matrix.c` ファイルに次の関数を実装します。
+
+```c
+void matrix_init_custom(void) {
+    // TODO: ここでハードウェアの初期化をする
+}
+
+bool matrix_scan_custom(matrix_row_t current_matrix[]) {
+    bool matrix_has_changed = false;
+
+    // TODO: ここで、マトリックススキャンを行なう
+
+    return matrix_has_changed;
+}
+```
+
+## マトリックスコードの全面置き換え
+
+スキャンルーチンをさらに変更する必要がある場合は、完全なスキャンルーチンを実装することを選択できます。
+
+設定するには、以下を `rules.mk` に追加します：
+```make
+CUSTOM_MATRIX = yes
+```
+
+そして、キーボードディレクトリの `matrix.c` ファイルに次の関数を実装します。
+
+```c
+matrix_row_t matrix_get_row(uint8_t row) {
+    // TODO: 要求された行データを返します
+}
+
+void matrix_print(void) {
+    // TODO: printf() を使って現在のマトリックスの状態をコンソールにダンプします
+}
+
+void matrix_init(void) {
+    // TODO: ここでハードウェアとグローバルマトリックスの状態を初期化します
+
+    // ハードウェアによるデバウンスがない場合 - 設定されているデバウンスルーチンを初期化します
+    debounce_init(MATRIX_ROWS);
+
+    // 正しいキーボード動作のためにこれを呼び出す*必要があります*
+    matrix_init_quantum();
+}
+
+uint8_t matrix_scan(void) {
+    bool matrix_has_changed = false;
+
+    // TODO: ここにマトリックススキャンルーチンを追加します
+
+    // ハードウェアによるデバウンスがない場合 - 設定されているデバウンスルーチンを使用します
+    debounce(raw_matrix, matrix, MATRIX_ROWS, changed);
+
+    // 正しいキーボード動作のためにこれを呼び出す*必要があります*
+    matrix_scan_quantum();
+
+    return matrix_has_changed;
+}
+```
+
+また、次のコールバックのデフォルトも提供します。
+
+```c
+__attribute__((weak)) void matrix_init_kb(void) { matrix_init_user(); }
+
+__attribute__((weak)) void matrix_scan_kb(void) { matrix_scan_user(); }
+
+__attribute__((weak)) void matrix_init_user(void) {}
+
+__attribute__((weak)) void matrix_scan_user(void) {}
+```

docs/ja/custom_quantum_functions.md

@@ -1,8 +1,8 @@
 # キーボードの挙動をカスタマイズする方法
 
 <!---
-  original document: 7494490d6:docs/custom_quantum_functions.md
-  git diff 7494490d6 HEAD -- docs/custom_quantum_functions.md | cat
+  original document: 0.8.62:docs/custom_quantum_functions.md
+  git diff 0.8.62 HEAD -- docs/custom_quantum_functions.md | cat
 -->
 
 多くの人にとって、カスタムキーボードはボタンの押下をコンピュータに送信するだけではありません。単純なボタンの押下やマクロよりも複雑なことを実行できるようにしたいでしょう。QMK にはコードを挿入したり、機能を上書きしたり、様々な状況でキーボードの挙動をカスタマイズできるフックがあります。
@@ -39,7 +39,7 @@ enum my_keycodes {
 };
 ```
 
-## 任意のキーコードの挙動のプログラミング
+## 任意のキーコードの挙動のプログラミング :id=programming-the-behavior-of-any-keycode
 
 既存のキーの挙動を上書きしたい場合、あるいは新しいキーについて挙動を定義する場合、`process_record_kb()` および `process_record_user()` 関数を使うべきです。これらは実際のキーイベントが処理される前のキー処理中に QMK によって呼び出されます。これらの関数が `true` を返す場合、QMK はキーコードを通常通りに処理します。これは、キーを置き換えるのではなく、キーの機能を拡張するのに便利です。これらの関数が `false` を返す場合、QMK は通常のキー処理をスキップし、必要なキーのアップまたはダウンイベントを送信するのかはユーザ次第です。
 
@@ -316,7 +316,7 @@ void suspend_wakeup_init_user(void) {
 * キーボード/リビジョン : `void suspend_power_down_kb(void)` および `void suspend_wakeup_init_user(void)`
 * キーマップ: `void suspend_power_down_kb(void)` および `void suspend_wakeup_init_user(void)`
 
-# レイヤー切り替えコード
+# レイヤー切り替えコード :id=layer-change-code
 
 これはレイヤーが切り替えられるたびにコードを実行します。レイヤー表示あるいはカスタムレイヤー処理に役立ちます。
 
@@ -491,14 +491,24 @@ void eeconfig_init_user(void) {  // EEPROM がリセットされます！
 
 # カスタムタッピング期間
 
-デフォルトでは、タッピング期間はグローバルに設定されていて、キーでは設定することができません。ほとんどのユーザにとって、これは全然問題ありません。しかし、場合によっては、`LT` キーとは異なるタイムアウトによって、デュアルファンクションキーが大幅に改善されます。なぜなら、一部のキーは他のキーよりも押し続けやすいためです。それぞれにカスタムキーコードを使う代わりに、キーごとに設定可能な `TAPPING_TERM` を使用できます。
+デフォルトでは、タッピング期間と(`IGNORE_MOD_TAP_INTERRUPT` のような)関連オプションはグローバルに設定されていて、キーでは設定することができません。ほとんどのユーザにとって、これは全然問題ありません。しかし、場合によっては、`LT` キーとは異なるタイムアウトによって、デュアルファンクションキーが大幅に改善されます。なぜなら、一部のキーは他のキーよりも押し続けやすいためです。それぞれにカスタムキーコードを使う代わりに、キーごとに設定可能なタイムアウトの挙動を設定できます。
 
-この機能を有効にするには、最初に `config.h` に `#define TAPPING_TERM_PER_KEY` を追加する必要があります。
+キーごとのタイムアウトの挙動を制御するための2つの設定可能なオプションがあります:
+
+- `TAPPING_TERM_PER_KEY`
+- `IGNORE_MOD_TAP_INTERRUPT_PER_KEY`
+
+必要な機能ごとに、`config.h` に `#define` 行を追加する必要があります。
+
+```
+#define TAPPING_TERM_PER_KEY
+#define IGNORE_MOD_TAP_INTERRUPT_PER_KEY
+```
 
 
 ## `get_tapping_term` の実装例
 
-キーコードに基づいて `TAPPING TERM` を変更するには、次のようなものを `keymap.c` ファイルに追加します:
+キーコードに基づいて `TAPPING_TERM` を変更するには、次のようなものを `keymap.c` ファイルに追加します:
 
 ```c
 uint16_t get_tapping_term(uint16_t keycode) {
@@ -513,6 +523,21 @@ uint16_t get_tapping_term(uint16_t keycode) {
 }
 ```
 
-### `get_tapping_term` 関数のドキュメント
+## `get_ignore_mod_tap_interrupt` の実装例
+
+キーコードに基づいて `IGNORE_MOD_TAP_INTERRUPT` の値を変更するには、次のようなものを `keymap.c` ファイルに追加します:
+
+```c
+bool get_ignore_mod_tap_interrupt(uint16_t keycode) {
+  switch (keycode) {
+    case SFT_T(KC_SPC):
+      return true;
+    default:
+      return false;
+  }
+}
+```
+
+## `get_tapping_term` / `get_ignore_mod_tap_interrupt` 関数のドキュメント
 
 ここにある他の多くの関数とは異なり、quantum あるいはキーボードレベルの関数を持つ必要はありません (または理由さえありません)。ここではユーザレベルの関数だけが有用なため、そのようにマークする必要はありません。

docs/ja/faq.md

@@ -1,11 +0,0 @@
-# よくある質問
-
-<!---
-  original document: d598f01cb:docs/faq.md
-  git diff d598f01cb HEAD -- docs/faq.md | cat
--->
-
-* [一般](ja/faq_general.md)
-* [QMK のビルドあるいはコンパイル](ja/faq_build.md)
-* [QMK のデバッグとトラブルシューティング](ja/faq_debug.md)
-* [キーマップ](ja/faq_keymap.md)

docs/ja/faq_debug.md

@@ -152,10 +152,3 @@ https://geekhack.org/index.php?topic=14290.msg1884034#msg1884034
 
 https://github.com/tmk/tmk_keyboard/issues/266
 https://geekhack.org/index.php?topic=41989.msg1967778#msg1967778
-
-
-
-## FLIP が動作しない
-### `AtLibUsbDfu.dll` が見つかりません
-デバイスマネージャから現在のドライバを削除し、FLIP が提供するものを再インストールします。
-http://imgur.com/a/bnwzy

docs/ja/faq_general.md

@@ -1,14 +1,52 @@
 # よくある質問
 
 <!---
-  original document: d598f01cb:docs/faq_general.md
-  git diff d598f01cb HEAD -- docs/faq_general.md | cat
+  original document: 0.8.62:docs/faq_general.md
+  git diff 0.8.62 HEAD -- docs/faq_general.md | cat
 -->
 
 ## QMK とは何か？
 
 Quantum Mechanical Keyboard の略である [QMK](https://github.com/qmk) は、カスタムキーボードのためのツールをビルドしている人々のグループです。[TMK](https://github.com/tmk/tmk_keyboard) の大幅に修正されたフォークである [QMK ファームウェア](https://github.com/qmk/qmk_firmware)から始まりました。
 
+## どこから始めればいいかわかりません！
+
+この場合は、[初心者ガイド](ja/newbs.md) から始めるべきです。ここには多くの素晴らしい情報があり、それらはあなたが始めるのに必要な全てをカバーするはずです。
+
+問題がある場合は、[QMK Configurator](https://config.qmk.fm)にアクセスしてください。あなたが必要なものの大部分が処理されます。
+
+## ビルドしたファームウェアを書き込むにはどうすればいいですか？
+
+まず、[コンパイル/書き込み FAQ ページ](ja/faq-build.md) に進みます。そこにはたくさんの情報があり、そこには一般的な問題に対する多くの解決策があります。
+
+## ここで取り上げていない問題がある場合はどうしますか？
+
+OK、問題ありません。[GitHub で issue を開く](https://github.com/qmk/qmk_firmware/issues) をチェックして、誰かが同じこと(似ているかだけでなく実際に同じであることを確認してください)を経験しているかどうかを確認してください。
+
+もし何も見つからない場合は、[新しい issue](https://github.com/qmk/qmk_firmware/issues/new) を開いてください！
+
+## バグを見つけたらどうしますか？
+
+[issue](https://github.com/qmk/qmk_firmware/issues/new) を開いてください。そしてもし修正方法を知っている場合は、GitHub で修正のプルリクエストを開いてください。
+
+## しかし、`git` と `GitHub` は怖いです！
+
+心配しないでください。開発を容易にするために `git` と GitHub を使い始めるための、かなり良い [ガイドライン](ja/newbs_git_best_practices.md) があります。
+
+さらに、追加の `git` と GitHub の関連リンクを [ここ](ja/newbs_learn_more_resources.md) に見つけることができます。
+
+## サポートを追加したいキーボードがあります
+
+素晴らしい！プルリクエストを開いてください。私たちはコードをレビューし、マージします！
+
+### `QMK` でブランドしたい場合はどうればいいですか？
+
+素晴らしい！私たちはあなたを支援したいと思います！
+
+実際、私たちにはあなたのページとキーボードに QMK ブランドを追加するための [完全なページ](https://qmk.fm/powered/) があります。これは QMK を公式にサポートするために必要なほぼ全て(知識と画像)をカバーしています。
+
+これについて質問がある場合は、issue を開くか、[Discord](https://discord.gg/Uq7gcHh) に進んでください。
+
 ## QMK と TMK の違いは何か？
 
 TMK は [Jun Wako](https://github.com/tmk) によって設計され実装されました。QMK は [Jack Humbert](https://github.com/jackhumbert) の Planck 用 TMK のフォークとして始まりました。しばらくして、Jack のフォークは TMK からかなり分岐し、2015年に Jack はフォークを QMK に名前を変えることにしました。

docs/ja/faq_keymap.md

@@ -1,8 +1,8 @@
 # キーマップの FAQ
 
 <!---
-  original document: 376419a4f:docs/faq_keymap.md
-  git diff 376419a4f HEAD -- docs/faq_keymap.md | cat
+  original document: 0.8.62:docs/faq_keymap.md
+  git diff 0.8.62 HEAD -- docs/faq_keymap.md | cat
 -->
 
 このページは人々がキーマップについてしばしば持つ疑問について説明します。まだ読んだことが無い場合には、[キーマップの概要](ja/keymap.md)を最初に読むべきです。
@@ -19,9 +19,20 @@
 <!-- Source for this image: http://www.keyboard-layout-editor.com/#/gists/bf431647d1001cff5eff20ae55621e9a -->
 ![キーボードのレイアウトイメージ](https://i.imgur.com/5wsh5wM.png)
 
+## 複雑なキーコードのカスタム名を作成する方法はありますか？
+
+時には、読みやすくするために、一部のキーコードにカスタム名を定義すると役に立ちます。人々は、しばしば `#define` を使ってカスタム名を定義します。例えば:
+
+```c
+#define FN_CAPS LT(_FL, KC_CAPSLOCK)
+#define ALT_TAB LALT(KC_TAB)
+```
+
+これにより、キーマップで `FN_CAPS` と `ALT_TAB` を使えるようになり、読みやすくなります。
+
 ## 一部のキーが入れ替わっているか、または動作しない
 
-QMK には2つの機能、ブートマジックとコマンドがあり、これによりその場でキーボードの動作を変更することができます。これには Ctrl/Caps の交換、Gui の無効化、Alt/GUI の交換、Backspace/Backslash の交換、全てのキーの無効化およびその他の動作の変更が含まれますが、これらに限定されません。
+QMK には2つの機能、ブートマジックとコマンドがあり、これによりその場でキーボードの動作を変更することができます。これには Ctrl/Caps の交換、Gui の無効化、Alt/Gui の交換、Backspace/Backslash の交換、全てのキーの無効化およびその他の動作の変更が含まれますが、これらに限定されません。
 
 迅速な解決策として、キーボードを接続している時に `Space`+`Backspace` を押してみてください。これはキーボードに保存されている設定をリセットし、これらのキーを通常の操作に戻します。うまく行かない場合は、以下を見てください:
 

docs/ja/feature_advanced_keycodes.md

@@ -0,0 +1,85 @@
+# レイヤーの切り替えとトグル :id=switching-and-toggling-layers
+
+<!---
+  original document: 5d5ff80:docs/feature_advanced_keycodes.md
+  git diff 5d5ff80 HEAD -- docs/feature_advanced_keycodes.md | cat
+-->
+
+これらの機能により、様々な方法でレイヤーをアクティブ化することができます。レイヤーは一般的に独立したレイアウトでは無いことに注意してください -- 複数のレイヤーを一度にアクティブ化することができ、レイヤーが `KC_TRNS` を使ってキーの押下を下のレイヤーに渡すことが一般的です。レイヤーの詳細については、[キーマップの概要](ja/keymap.md#keymap-and-layers)を見てください。MO()、LM()、TT() あるいは LT() を使って一時的なレイヤーの切り替えを使う場合、上のレイヤーのキーを透過にするようにしてください。さもないと意図したように動作しないかもしれません。
+
+* `DF(layer)` - デフォルトレイヤーを切り替えます。デフォルトレイヤーは、他のレイヤーがその上に積み重なっている、常にアクティブな基本レイヤーです。デフォルトレイヤーの詳細については以下を見てください。これは QWERTY から Dvorak レイアウトに切り替えるために使うことができます。(これは一時的な切り替えであり、キーボードの電源が切れるまでしか持続しないことに注意してください。デフォルトレイヤーを永続的に変更するには、[process_record_user](ja/custom_quantum_functions.md#programming-the-behavior-of-any-keycode) 内で `set_single_persistent_default_layer` 関数を呼び出すなど、より深いカスタマイズが必要です。)
+* `MO(layer)` - 一時的に*レイヤー*をアクティブにします。キーを放すとすぐに、レイヤーは非アクティブになります。
+* `LM(layer, mod)` - (`MO` のように)一時的に*レイヤー*をアクティブにしますが、モディファイア *mod* がアクティブな状態です。layer 0-15 と、左モディファイアのみをサポートします: `MOD_LCTL`、`MOD_LSFT`、`MOD_LALT`、`MOD_LGUI` (`KC_` の代わりに `MOD_` 定数を使うことに注意してください)。これらのモディファイアは、例えば `LM(_RAISE, MOD_LCTL | MOD_LALT)` のように、ビット単位の OR を使って組み合わせることができます。
+* `LT(layer, kc)` - ホールドされた時に*レイヤー*を一時的にアクティブにし、タップされた時に *kc* を送信します。layer 0-15 のみをサポートします。
+* `OSL(layer)` - 次のキーが押されるまで、一時的に*レイヤー*をアクティブにします。詳細と追加機能については、[ワンショットキー](ja/one_shot_keys.md)を見てください。
+* `TG(layer)` - *レイヤー*を切り替えます。非アクティブな場合はアクティブにし、逆も同様です。
+* `TO(layer)` - *レイヤー*をアクティブにし、他の全てのレイヤー(デフォルトレイヤーを除く)を非アクティブにします。この関数は特別です。1つのレイヤーをアクティブなレイヤースタックに追加/削除する代わりに、現在のアクティブなレイヤーを完全に置き換え、唯一上位のレイヤーを下位のレイヤーで置き換えることができるからです。これはキーダウンで(キーが押されるとすぐに)アクティブになります。
+* `TT(layer)` - レイヤーのタップ切り替え。キーを押したままにすると*レイヤー*がアクティブにされ、放すと非アクティブになります (`MO` 風)。繰り返しタップすると、レイヤーはオンあるいはオフを切り替えます (`TG` 風)。デフォルトでは5回のタップが必要ですが、`TAPPING_TOGGLE` を定義することで変更することができます -- 例えば、2回のタップだけで切り替えるには、`#define TAPPING_TOGGLE 2` を定義します。
+
+## 注意事項
+
+現在のところ、`LT()` と `MT()` は[基本的なキーコードセット](ja/keycodes_basic.md)に制限されています。つまり、`LCTL()`、`KC_TILD` あるいは `0xFF` より大きなキーコードを使うことができません。レイヤータップあるいはモッドタップのキーコードの一部として指定されたモディファイアは無視されます。タップしたキーコードにモディファイアを適用する必要がある場合は、[タップダンス](ja/feature_tap_dance.md#example-5-using-tap-dance-for-advanced-mod-tap-and-layer-tap-keys)を使うことができます。
+
+さらに、モッドタップあるいはレイヤータップで少なくとも1つの右手用のモディファイアが指定された場合、指定された全てのモディファイアが右手用になるため、2つをうまく組み合わせて一致させることはできません。
+
+# レイヤーの使用
+
+レイヤーを切り替える時は注意してください。(キーボードを取り外さずに)そのレイヤーを非アクティブにすることができずレイヤーから移動できなくなる可能性があります。最も一般的な問題を避けるためのガイドラインを作成しました。
+
+## 初心者
+
+QMK を使い始めたばかりの場合は、全てを単純にしたいでしょう。レイヤーをセットアップする時は、これらのガイドラインに従ってください:
+
+* デフォルトの "base" レイヤーとして、layer 0 をセットアップします。これは通常の入力レイヤーであり、任意のレイアウト (qwerty、dvorak、colemak など)にすることができます。通常はキーボードのキーのほとんどまたは全てが定義されているため、これを最下位のレイヤーとして設定することが重要です。そうすることで、もしそれが他のレイヤーの上 (つまりレイヤー番号が大きい)にある場合の影響を防ぎます。
+* layer 0 をルートとして、レイヤーを "ツリー" レイアウトに配置します。他の複数のレイヤーから同じレイヤーに行こうとしないでください。
+* 各レイヤーのキーマップでは、より高い番号のレイヤーのみを参照します。レイヤーは最大の番号(最上位)のアクティブレイヤーから処理されるため、下位レイヤーの状態を変更するのは難しくエラーが発生しやすくなります。
+
+## 中級ユーザ
+
+複数の基本レイヤーが必要な場合があります。例えば、QWERTY と Dvorak を切り替える場合、国ごとに異なるレイアウトを切り替える場合、あるいは異なるビデオゲームごとにレイアウトを切り替える場合などです。基本レイヤーは常に最小の番号のレイヤーである必要があります。複数の基本レイヤーがある場合、常にそれらを相互排他的に扱う必要があります。1つの基本レイヤーがオンの場合、他をオフにします。
+
+## 上級ユーザ
+
+レイヤーがどのように動作し、何ができるかを理解したら、より創造的になります。初心者のセクションで列挙されている規則は、幾つかの巧妙な詳細を回避するのに役立ちますが、特に超コンパクトなキーボードのユーザにとって制約になる場合があります。レイヤーの仕組みを理解することで、レイヤーをより高度な方法で使うことができます。
+
+レイヤーは番号順に上に積み重なっています。キーの押下の動作を決定する時に、QMK は上から順にレイヤーを走査し、`KC_TRNS` に設定されていない最初のアクティブなレイヤーに到達すると停止します。結果として、現在のレイヤーよりも数値的に低いレイヤーをアクティブにし、現在のレイヤー(あるいはアクティブでターゲットレイヤーよりも高い別のレイヤー)に `KC_TRNS` 以外のものがある場合、それが送信されるキーであり、アクティブ化したばかりのレイヤー上のキーではありません。これが、ほとんどの人の "なぜレイヤーが切り替わらないのか" 問題の原因です。
+
+場合によっては、マクロ内あるいはタップダンスルーチンの一部としてレイヤーを切り替えほうが良いかもしれません。`layer_on` はレイヤーをアクティブにし、`layer_off` はそれを非アクティブにします。もっと多くのレイヤーに関する関数は、[action_layer.h](https://github.com/qmk/qmk_firmware/blob/master/tmk_core/common/action_layer.h) で見つけることができます。
+
+# 修飾キー :id=modifier-keys
+
+以下のようにキーコードとモディファイアを組み合わせることができます。押すと、モディファイアのキーダウンイベントが送信され、次に `kc` のキーダウンイベントが送信されます。放すと、`kc` のキーアップイベントが送信され、次にモディファイアのキーアップイベントが送信されます。
+
+| キー | エイリアス | 説明 |
+|----------|-------------------------------|----------------------------------------------------|
+| `LCTL(kc)` | `C(kc)` | 左 Control を押しながら `kc` を押します。 |
+| `LSFT(kc)` | `S(kc)` | 左 Shift を押しながら `kc` を押します。 |
+| `LALT(kc)` | `A(kc)`, `LOPT(kc)` | 左 Alt を押しながら `kc`を押します。 |
+| `LGUI(kc)` | `G(kc)`, `LCMD(kc)`, `LWIN(kc)` | 左 GUI を押しながら `kc` を押します。 |
+| `RCTL(kc)` |  | 右 Control を押しながら `kc` を押します。 |
+| `RSFT(kc)` |  | 右 Shift を押しながら `kc` を押します。 |
+| `RALT(kc)` | `ROPT(kc)`, `ALGR(kc)` | 右 Alt を押しながら `kc` を押します。 |
+| `RGUI(kc)` | `RCMD(kc)`, `LWIN(kc)` | 右 GUI を押しながら `kc` を押します。 |
+| `SGUI(kc)` | `SCMD(kc)`, `SWIN(kc)` | 左 Shift と左 GUI を押しながら `kc` を押します。 |
+| `LCA(kc)` |  | 左 Control と左 Alt を押しながら `kc` を押します。 |
+| `LCAG(kc)` |  | 左 Control、左 Alt、左 GUI を押しながら `kc` を押します。 |
+| `MEH(kc)` |  | 左 Control、左 Shift、左 Alt を押しながら `kc` を押します。 |
+| `HYPR(kc)` |  | 左 Control、左 Shift、左 Alt、左 GUI を押しながら `kc` を押します。 |
+
+また、それらを繋げることができます。例えば、`LCTL(LALT(KC_DEL))` は1回のキー押下で Control+Alt+Delete を送信するキーを作成します。
+
+# 過去の内容
+
+このページには多くの機能が含まれていました。このページを構成していた多くのセクションをそれぞれのページに移動しました。これより下は全て単なるリダイレクトであるため、web上で古いリンクをたどっている人は探しているものを見つけることができます。
+
+## モッドタップ :id=mod-tap
+
+* [モッドタップ](ja/mod_tap.md)
+
+## ワンショットキー :id=one-shot-keys
+
+* [ワンショットキー](ja/one_shot_keys.md)
+
+## タップホールド設定オプション :id=tap-hold-configuration-options
+
+* [タップホールド設定オプション](ja/tap_hold.md)

docs/ja/feature_audio.md

@@ -0,0 +1,328 @@
+# オーディオ
+
+<!---
+  original document: 5d5ff80:docs/feature_audio.md
+  git diff 5d5ff80 HEAD -- docs/feature_audio.md | cat
+-->
+
+キーボードは音を出すことができます！Planck、Preonic あるいは特定の PWM 対応ピンにアクセスできる AVR キーボードがある場合は、単純なスピーカーを接続してビープ音を鳴らすことができます。これらのビープ音を使ってレイヤーの変化、モディファイア、特殊キーを示したり、あるいは単にイカした8ビットの曲を鳴らすことができます。
+
+最大2つの同時オーディオ音声がサポートされ、1つはタイマー1によってもう一つはタイマー3によって駆動されます。以下のピンは config.h の中でオーディオ出力として定義することができます:
+
+Timer 1:
+`#define B5_AUDIO`
+`#define B6_AUDIO`
+`#define B7_AUDIO`
+
+Timer 3:
+`#define C4_AUDIO`
+`#define C5_AUDIO`
+`#define C6_AUDIO`
+
+`rules.mk` に `AUDIO_ENABLE = yes` を追加すると、他の設定無しで自動的に有効になる幾つかの異なるサウンドがあります:
+
+```
+STARTUP_SONG // キーボードの起動時に再生 (audio.c)
+GOODBYE_SONG // RESET キーを押すと再生 (quantum.c)
+AG_NORM_SONG // AG_NORM キーを押すと再生 (quantum.c)
+AG_SWAP_SONG // AG_SWAP キーを押すと再生 (quantum.c)
+CG_NORM_SONG // CG_NORM キーを押すと再生 (quantum.c)
+CG_SWAP_SONG // CG_SWAP キーを押すと再生 (quantum.c)
+MUSIC_ON_SONG // 音楽モードがアクティブになると再生 (process_music.c)
+MUSIC_OFF_SONG // 音楽モードが非アクティブになると再生 (process_music.c)
+CHROMATIC_SONG // 半音階音楽モードが選択された時に再生 (process_music.c)
+GUITAR_SONG // ギター音楽モードが選択された時に再生 (process_music.c)
+VIOLIN_SONG // バイオリン音楽モードが選択された時に再生 (process_music.c)
+MAJOR_SONG // メジャー音楽モードが選択された時に再生 (process_music.c)
+```
+
+`config.h` の中で以下のような操作を行うことで、デフォルトの曲を上書きすることができます:
+
+```c
+#ifdef AUDIO_ENABLE
+  #define STARTUP_SONG SONG(STARTUP_SOUND)
+#endif
+```
+
+サウンドの完全なリストは、[quantum/audio/song_list.h](https://github.com/qmk/qmk_firmware/blob/master/quantum/audio/song_list.h) で見つかります - このリストに自由に追加してください！利用可能な音は [quantum/audio/musical_notes.h](https://github.com/qmk/qmk_firmware/blob/master/quantum/audio/musical_notes.h) で見つかります。
+
+特定の時にカスタムサウンドを再生するために、以下のように曲を定義することができます(ファイルの上部付近に):
+
+```c
+float my_song[][2] = SONG(QWERTY_SOUND);
+```
+
+以下のように曲を再生します:
+
+```c
+PLAY_SONG(my_song);
+```
+
+または、以下のようにループで再生することができます:
+
+```c
+PLAY_LOOP(my_song);
+```
+
+オーディオがキーボードに組み込まれていない時に問題が起きる事を避けるために、`#ifdef AUDIO_ENABLE` / `#endif` で全てのオーディオ機能をくるむことをお勧めします。
+
+オーディオで利用可能なキーコードは以下の通りです:
+
+* `AU_ON` - オーディオ機能をオン
+* `AU_OFF` - オーディオ機能をオフ
+* `AU_TOG` - オーディオ機能を切り替え
+
+!> これらのキーコードは全てのオーディオ機能をオンおよびオフにします。オフにするとオーディオフィードバック、オーディオクリック、音楽モードなどが完全に無効になります。
+
+## ARM オーディオボリューム
+
+ARM デバイスの場合、DAC サンプル値を調整できます。キーボードがあなたやあなたの同僚にとって騒々しい場合、`config.h` 内の `DAC_SAMPLE_MAX` を使って最大量を設定することができます:
+
+```c
+#define DAC_SAMPLE_MAX 65535U
+```
+
+## 音楽モード
+
+音楽モードは列を半音階に、行をオクターブにマップします。これは格子配列キーボードで最適に動作しますが、他のものでも動作させることができます。`0xFF` 未満の全てのキーコードはブロックされるため、音の演奏中は入力できません - 特別なキー/mod があればそれらは引き続き動作します。これを回避するには、音楽モードを有効にする前(あるいは後)で、KC_NO を使って別のレイヤーにジャンプします。
+
+メモリの問題により、録音は実験的です - 奇妙な動作が発生した場合は、キーボードの取り外しと再接続で問題が解決するでしょう。
+
+利用可能なキーコード:
+
+* `MU_ON` - 音楽モードをオン
+* `MU_OFF` - 音楽モードをオフ
+* `MU_TOG` - 音楽モードの切り替え
+* `MU_MOD` - 音楽モードの循環
+   * `CHROMATIC_MODE` - 半音階。行はオクターブを変更します
+   * `GUITAR_MODE` - 半音階、ただし行は弦を変更します (+5 階)
+   * `VIOLIN_MODE` - 半音階。ただし行は弦を変換します (+7 階)
+   * `MAJOR_MODE` - メージャースケール
+
+音楽モードでは、以下のキーコードは動作が異なり、通過しません:
+
+* `LCTL` - 録音を開始
+* `LALT` - 録音を停止/演奏を停止
+* `LGUI` - 録音を再生
+* `KC_UP` - 再生をスピードアップ
+* `KC_DOWN` - 再生をスローダウン
+
+ピッチ標準 (`PITCH_STANDARD_A`) はデフォルトで 440.0f です - これを変更するには、`config.h` に以下のようなものを追加します:
+
+    #define PITCH_STANDARD_A 432.0f
+
+音楽モードも完全に無効にすることができます。コントローラの容量が足りなくて困っている場合に役に立ちます。無効にするには、これを `config.h` に追加します:
+
+    #define NO_MUSIC_MODE
+
+### 音楽マスク
+
+デフォルトで、`MUSIC_MASK` は `keycode < 0xFF` に設定されます。これは、`0xFF` 未満のキーコードが音に変換され、何も出力しないことを意味します。`config.h` の中で以下のものを定義することで、これを変更することができます:
+
+    #define MUSIC_MASK keycode != KC_NO
+
+これは全てのキーコードを捕捉します - これは、キーボードを再起動するまで、音楽モードで動けなくなることに注意してください！
+
+どのキーコードを引き続き処理するかを制御する、より高度な方法については、`<keyboard>.c` の中の `music_mask_kb(keycode)` および `keymap.c` の中の `music_mask_user(keycode)` を使うことができます:
+
+    bool music_mask_user(uint16_t keycode) {
+      switch (keycode) {
+        case RAISE:
+        case LOWER:
+          return false;
+        default:
+          return true;
+      }
+    }
+
+false を返すものはマスクの一部では無く、常に処理されます。
+
+### 音楽マップ
+
+デフォルトでは、音楽モードはキーのスケールを決定するために列と行を使います。キーボードレイアウトに一致する長方形のマトリックスを使うキーボードの場合、これで十分です。しかし、(Planck Rev6 あるいは多くの分割キーボードなどのように)より複雑なマトリックスを使うキーボードの場合、非常に歪んだ感じを受けることになります。
+
+しかしながら、音楽マップオプションにより、音楽モードのためにスケーリングを再マップすることができるため、レイアウトに一致し、より自然になります。
+
+この機能を使うには、`#define MUSIC_MAP` を `config.h` ファイルに追加します。そして、`キーボードの名前.c` または `keymap.c` に `uint8_t music_map` を追加します。
+
+```c
+const uint8_t music_map[MATRIX_ROWS][MATRIX_COLS] = LAYOUT_ortho_4x12(
+	36, 37, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47,
+	24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35,
+	12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23,
+	 0,  1,  2,  3,  4,  5,  6,  7,  8,  9, 10, 11
+);
+```
+
+キーボードが使用する `LAYOUT` マクロも使用したいでしょう。これは正しいキーの位置にマップします。キーボードレイアウトの左下から開始し、右に移動してさらに上に移動します。完全なマトリックスができるまで、全てのエントリを入力します。
+
+これを実装する方法の例として、[Planck Keyboard](https://github.com/qmk/qmk_firmware/blob/e9ace1487887c1f8b4a7e8e6d87c322988bec9ce/keyboards/planck/planck.c#L24-L29) を見ることができます。
+
+## オーディオクリック
+
+これは、ボタンを押すたびにクリック音を追加し、キーボードからのクリック音をシミュレートします。キーを押すたびにわずかに音が異なるため、すばやく入力しても長い単一の音のようには聞こえません。
+
+* `CK_TOGG` - ステータスを切り替えます (有効にされた場合、音を再生します)
+* `CK_ON` - オーディオクリックをオンにします (音を再生します)
+* `CK_OFF` - オーディオクリックをオフにします (音を再生しません）
+* `CK_RST` - 周波数をデフォルトの状態に再設定します (デフォルトの周波数で音を再生します)
+* `CK_UP` - クリック音の周波数を増やします (新しい周波数で音を再生します)
+* `CK_DOWN` - クリック音の周波数を減らします (新しい周波数で音を再生します)
+
+
+容量を節約するためにデフォルトではこの機能は無効です。有効にするには、`config.h` に以下を追加します:
+
+    #define AUDIO_CLICKY
+
+
+これらの値を定義することで、デフォルト、最小および最大周波数、ステッピングおよび組み込みのランダム性を設定することができます:
+
+| オプション | デフォルト値 | 説明 |
+|--------|---------------|-------------|
+| `AUDIO_CLICKY_FREQ_DEFAULT` | 440.0f | クリック音のデフォルト/開始音の周波数を設定します。 |
+| `AUDIO_CLICKY_FREQ_MIN` | 65.0f | 最小周波数を設定します (60f 未満は少しバグがあります)。 |
+| `AUDIO_CLICKY_FREQ_MAX` | 1500.0f | 最大周波数を設定します。高すぎると同僚があなたを攻撃する可能性があります。 |
+| `AUDIO_CLICKY_FREQ_FACTOR` | 1.18921f | UP/DOWN キーコードのステップを設定します。これは掛け算の係数です。デフォルトでは、音楽のマイナーの1/3ずつ、周波数を上げ/下げします。 |
+| `AUDIO_CLICKY_FREQ_RANDOMNESS` | 0.05f | クリックのランダム性の係数を設定します。これを `0f` に設定すると各クリックが同一になり、`1.0f` に設定するとこの音は90年代のコンピュータ画面のスクロール/タイピングの効果があります。 |
+| `AUDIO_CLICKY_DELAY_DURATION` | 1 | 1がテンポの 1/16、または64分音符である整数音符の長さ (実装の詳細については、`quantum/audio/musical_notes.h` を見てください)。メインのクリック効果は、この時間だけ遅れます。これらを6-12前後の値に調整すると、うるさいスイッチの補正に役立ちます。 |
+
+
+
+
+## MIDI 機能
+
+これはまだ WIP ですが、何が起きているかを見るために、`quantum/process_keycode/process_midi.c` を調べてください。Makefile から有効にします。
+
+
+## オーディオキーコード
+
+| キー | エイリアス | 説明 |
+|----------------|---------|----------------------------------|
+| `AU_ON` |  | オーディオモードオン |
+| `AU_OFF` |  | オーディオモードオフ |
+| `AU_TOG` |  | オーディオモードを切り替えます |
+| `CLICKY_TOGGLE` | `CK_TOGG` | オーディオクリックモードを切り替えます |
+| `CLICKY_UP` | `CK_UP` | クリック音の周波数を増やします |
+| `CLICKY_DOWN` | `CK_DOWN` | クリック音の周波数を減らします |
+| `CLICKY_RESET` | `CK_RST` | 周波数をデフォルトに再設定します |
+| `MU_ON` |  | 音楽モードをオンにします |
+| `MU_OFF` |  | 音楽モードをオフにします |
+| `MU_TOG` |  | 音楽モードを切り替えます |
+| `MU_MOD` |  | 音楽モードを循環します |
+
+<!-- FIXME: this formatting needs work
+
+## Audio
+
+```c
+#ifdef AUDIO_ENABLE
+    AU_ON,
+    AU_OFF,
+    AU_TOG,
+
+    #ifdef FAUXCLICKY_ENABLE
+        FC_ON,
+        FC_OFF,
+        FC_TOG,
+    #endif
+
+    // Music mode on/off/toggle
+    MU_ON,
+    MU_OFF,
+    MU_TOG,
+
+    // Music voice iterate
+    MUV_IN,
+    MUV_DE,
+#endif
+```
+
+### Midi
+
+#if !MIDI_ENABLE_STRICT || (defined(MIDI_ENABLE) && defined(MIDI_BASIC))
+    MI_ON,  // send midi notes when music mode is enabled
+    MI_OFF, // don't send midi notes when music mode is enabled
+#endif
+
+MIDI_TONE_MIN,
+MIDI_TONE_MAX
+
+MI_C = MIDI_TONE_MIN,
+MI_Cs,
+MI_Db = MI_Cs,
+MI_D,
+MI_Ds,
+MI_Eb = MI_Ds,
+MI_E,
+MI_F,
+MI_Fs,
+MI_Gb = MI_Fs,
+MI_G,
+MI_Gs,
+MI_Ab = MI_Gs,
+MI_A,
+MI_As,
+MI_Bb = MI_As,
+MI_B,
+
+MIDI_TONE_KEYCODE_OCTAVES > 1
+
+where x = 1-5:
+MI_C_x,
+MI_Cs_x,
+MI_Db_x = MI_Cs_x,
+MI_D_x,
+MI_Ds_x,
+MI_Eb_x = MI_Ds_x,
+MI_E_x,
+MI_F_x,
+MI_Fs_x,
+MI_Gb_x = MI_Fs_x,
+MI_G_x,
+MI_Gs_x,
+MI_Ab_x = MI_Gs_x,
+MI_A_x,
+MI_As_x,
+MI_Bb_x = MI_As_x,
+MI_B_x,
+
+MI_OCT_Nx 1-2
+MI_OCT_x 0-7
+MIDI_OCTAVE_MIN = MI_OCT_N2,
+MIDI_OCTAVE_MAX = MI_OCT_7,
+MI_OCTD, // octave down
+MI_OCTU, // octave up
+
+MI_TRNS_Nx 1-6
+MI_TRNS_x 0-6
+MIDI_TRANSPOSE_MIN = MI_TRNS_N6,
+MIDI_TRANSPOSE_MAX = MI_TRNS_6,
+MI_TRNSD, // transpose down
+MI_TRNSU, // transpose up
+
+MI_VEL_x 1-10
+MIDI_VELOCITY_MIN = MI_VEL_1,
+MIDI_VELOCITY_MAX = MI_VEL_9,
+MI_VELD, // velocity down
+MI_VELU, // velocity up
+
+MI_CHx 1-16
+MIDI_CHANNEL_MIN = MI_CH1
+MIDI_CHANNEL_MAX = MI_CH16,
+MI_CHD, // previous channel
+MI_CHU, // next channel
+
+MI_ALLOFF, // all notes off
+
+MI_SUS, // sustain
+MI_PORT, // portamento
+MI_SOST, // sostenuto
+MI_SOFT, // soft pedal
+MI_LEG,  // legato
+
+MI_MOD, // modulation
+MI_MODSD, // decrease modulation speed
+MI_MODSU, // increase modulation speed
+#endif // MIDI_ADVANCED
+
+-->

docs/ja/feature_auto_shift.md

@@ -0,0 +1,135 @@
+# 自動シフト: なぜシフトキーが必要ですか？
+
+<!---
+  original document: 5d5ff80:docs/feature_auto_shift.md
+  git diff 5d5ff80 HEAD -- docs/feature_auto_shift.md | cat
+-->
+
+キーをタップすると、その文字を取得します。キーをタップするが、*わずかに*長く押し続けると、シフト状態になります。ほら！シフトキーは必要ありません！
+
+## なぜ自動シフトなのですか？
+
+多くの人が腱鞘炎などの症状に苦しんでいます。一般的な原因は、指を繰り返し長い距離を伸ばすことです。私たちはキーボード上でシフトキーに手を伸ばすためにあまりにも頻繁に小指を伸ばします。自動シフトキーはそれを軽減しようとしています。
+
+## どのように動作しますか？
+
+キーをタップする時に、キーを放す前にほんの短い間押したままにします。この押したままにする時間は全ての人にとって異なる長さです。自動シフトは、定数 `AUTO_SHIFT_TIMEOUT` を定義し、これは普段の押された状態の時間の2倍に通常は設定されます。タイマーは、キーを押す時に開始され、キーを放す時に止まります。押された時間が `AUTO_SHIFT_TIMEOUT` 以上の場合に、キーのシフトバージョンが発行されます。時間が `AUTO_SHIFT_TIMEOUT` 時間よりも短い場合は、通常の状態が発行されます。
+
+## 自動シフトには制限がありますか？
+
+残念ながらあります。
+
+1. キーリピートが動作しなくなります。例えば、20個の 'a' 文字が必要な場合、'a' キーを1、2秒押し続けるかもしれません。オペレーティングシステムに押されたキーの状態を発行する代わりに押された時間を計るので、自動シフトでは動作しません。
+2. シフトをするつもりがない時にシフトされた文字を取得し、シフトしたい時にそうではない他の文字を取得するでしょう。これは結局は練習になります。急いでいる時は、シフトされたバージョンのために十分長くキーを押したと思うかもしれませんが、そうではありませんでした。一方、キーをタップしていると思うかもしれませんが、実際には予想よりも少し長い間押していました。
+
+## どうやって自動シフトを有効にしますか？
+
+キーマップフォルダの `rules.mk` に追加します:
+
+    AUTO_SHIFT_ENABLE = yes
+
+`rules.mk` が存在しない場合、それを作成することができます。
+
+そして自動シフトキーを有効にした新しいファームウェアをコンパイルしてインストールします！以上です！
+
+## モディファイア
+
+デフォルトで、1つ以上のモディファイアと一緒にキーが押されると自動シフトは無効になります。従って、本当に長い間 Ctrl+A を保持しても、Ctrl+Shift+A と同じではありません。
+
+`config.h` に定義を追加することで、モディファイアの自動シフトを再度有効にすることができます
+
+```c
+#define AUTO_SHIFT_MODIFIERS
+```
+
+この場合、`AUTO_SHIFT_TIMEOUT` を超えて押された Ctrl+A は Ctrl+Shift+A として送信されます
+
+
+## 自動シフトの設定
+
+必要に応じて、自動シフトの挙動を変更することができる幾つかの設定があります。キーマップフォルダにある `config.h` に様々な変数を設定することで行われます。`config.h` ファイルが存在しない場合、それを作成することができます。
+
+例
+
+```c
+#pragma once
+
+#define AUTO_SHIFT_TIMEOUT 150
+#define NO_AUTO_SHIFT_SPECIAL
+```
+
+### AUTO_SHIFT_TIMEOUT (単位: ミリ秒)
+
+これは、シフトされた状態を取得するためにどれだけ長くキーを押し続けなければならないかを制御します。
+明らかにこれは人によって異なります。一般的な人にとって、135 から 150 の設定がうまく機能します。ただし、少なくとも 175 の値から開始する必要があります。これはデフォルト値です。その後、ここから下げていきます。間違って検出することなくシフトされた状態を取得するのに必要な、最も短い時間を得るという考え方です。
+
+完璧に動作するまで、いろいろな値を試してみます。多くの人は、全てが所定の値で適切に動作するものの、時々、1つあるいは2つのキーがシフト状態を発行することが分かるでしょう。これは単に習慣と、幾つかのキーを他のキーよりも少し長く押し続けることによるものです。この値を見つけたら、問題のキーを通常よりも少し早くタップするとともに、その値を設定します。
+
+?> 自動シフトには、この値を素早く取得するのに役立つ3つの特別なキーがあります。詳細は「自動シフトのセットアップ」を見てください！
+
+### NO_AUTO_SHIFT_SPECIAL (単純にこのように定義します)
+
+-\_, =+, [{, ]}, ;:, '", ,<, .> および /? を含む特殊キーを自動シフトしません
+
+### NO_AUTO_SHIFT_NUMERIC (単純にこのように定義します)
+
+0から9までの数字キーを自動シフトしません。
+
+### NO_AUTO_SHIFT_ALPHA (単純にこのように定義します)
+
+AからZを含むアルファベット文字を自動シフトしません。
+
+## 自動シフトセットアップの使用
+
+これにより、`AUTO_SHIFT_TIMEOUT` で設定している時間を一時的に増減させたり報告するために、3つのキーを定義することができます。
+
+### セットアップ
+
+3つのキーを一時的にキーマップにマップします:
+
+| キー名 | 説明 |
+|----------|-----------------------------------------------------|
+| KC_ASDN | 自動シフトタイムアウト変数を下げる |
+| KC_ASUP | 自動シフトタイムアウト変数を上げる |
+| KC_ASRP | 現在の自動シフトタイムアウト値を報告する |
+| KC_ASON | 自動シフト機能をオンにする |
+| KC_ASOFF | 自動シフト機能をオフにする |
+| KC_ASTG | 自動シフト機能の状態を切り替える |
+
+新しいファームウェアをコンパイルしてアップロードします。
+
+### 使い方
+
+これらのテスト中は、完全に普段通り入力する必要があり、意図的にシフトされたキーを使わずに入力するように注意する必要があります。
+
+1. アルファベットの複数の文を入力します。
+2. 大文字に注意してください。
+3. 大文字が存在しない場合は、自動シフトタイムアウト値を減らすために `KC_ASDN` にマップしたキーを押し、ステップ1に戻ります。
+4. 大文字が幾つかある場合は、押す時間を短くしてこれらのキーをタップする必要があるか、あるいはタイムアウトを増やす必要があるかを決定します。
+5. タイムアウトを増やすことに決めた場合は、`KC_ASUP` にマップしたキーを押し、ステップ1に戻ります。
+6. 結果に満足したら、`KC_ASRP` にマップしたキーを押します。キーボードは `AUTO_SHIFT_TIMEOUT` の値を自動的に入力します。
+7. 報告された値で `config.h` の `AUTO_SHIFT_TIMEOUT` を更新します。
+8. `config.h` から `AUTO_SHIFT_SETUP` を削除します。
+9. `KC_ASDN`、`KC_ASUP` および `KC_ASRP` のキーバインディングを削除します。
+10. 新しいファームウェアをコンパイルしてアップロードします。
+
+#### 実行例
+
+    hello world. my name is john doe. i am a computer programmer playing with
+    keyboards right now.
+    
+     [KC_ASDN を何度か押します] 
+    
+    heLLo woRLd. mY nAMe is JOHn dOE. i AM A compUTeR proGRaMMER PlAYiNG witH
+    KEYboArDS RiGHT NOw.
+    
+     [KC_ASUP を数回押します] 
+    
+    hello world. my name is john Doe. i am a computer programmer playing with
+    keyboarDs right now.
+    
+     [KC_ASRPを押します] 
+    
+    115
+
+キーボードは現在の `AUTO_SHIFT_TIMEOUT` 値を表す `115` を入力しました。これで設定が完了しました！テスト中に現れる *D* キーを少し練習してください。それで完璧です。

docs/ja/feature_backlight.md

@@ -0,0 +1,253 @@
+# バックライト
+
+<!---
+  original document: 5d5ff80:docs/feature_backlight.md
+  git diff 5d5ff80 HEAD -- docs/feature_backlight.md | cat
+-->
+
+多くのキーボードは、キースイッチを貫通して配置されたり、キースイッチの下に配置された個々の LED によって、バックライトキーをサポートします。この機能は通常スイッチごとに単一の色しか使用できないため、[RGB アンダーグロー](ja/feature_rgblight.md)および [RGB マトリックス](ja/feature_rgb_matrix.md)機能のどちらとも異なりますが、キーボードに複数の異なる単一色の LED を取り付けることは当然可能です。
+
+QMK は *パルス幅変調*(*Pulse Width Modulation*) すなわち PWM として知られている技術で急速にオンおよびオフを切り替えることで、これらの LED の輝度を制御できます。PWM 信号のデューティサイクルを変えることで、調光の錯覚を起こすことができます。
+
+MCU は、GPIO ピンにはそんなに電流を供給できません。MCU から直接バックライトに給電せずに、バックライトピンは LED への電力を切り替えるトランジスタあるいは MOSFET に接続されます。
+
+## 機能の設定
+
+ほとんどのキーボードではバックライトをサポートしている場合にデフォルトで有効になっていますが、もし機能しない場合は `rules.mk` が以下を含んでいることを確認してください:
+
+```makefile
+BACKLIGHT_ENABLE = yes
+```
+
+## キーコード
+有効にすると、以下のキーコードを使ってバックライトレベルを変更することができます。
+
+| キー | 説明 |
+|---------|------------------------------------------|
+| `BL_TOGG` | バックライトをオンあるいはオフにする |
+| `BL_STEP` | バックライトレベルを循環する |
+| `BL_ON` | バックライトを最大輝度に設定する |
+| `BL_OFF` | バックライトをオフにする |
+| `BL_INC` | バックライトレベルを上げる |
+| `BL_DEC` | バックライトレベルを下げる |
+| `BL_BRTG` | バックライトの明滅動作を切り替える |
+
+## バックライト関数群
+
+| 関数 | 説明 |
+|----------|-----------------------------------------------------------|
+| `backlight_toggle()` | バックライトをオンあるいはオフにする |
+| `backlight_enable()` | バックライトをオンにする |
+| `backlight_disable()` | バックライトをオフにする |
+| `backlight_step()` | バックライトレベルを循環する |
+| `backlight_increase()` | バックライトレベルを上げる |
+| `backlight_decrease()` | バックライトレベルを下げる |
+| `backlight_level(x)` | バックライトのレベルを特定のレベルに設定する |
+| `get_backlight_level()` | 現在のバックライトレベルを返す |
+| `is_backlight_enabled()` | バックライトが現在オンかどうかを返す |
+
+### バックライトの明滅動作の関数群
+
+| 関数 | 説明 |
+|----------|---------------------------------------------------|
+| `breathing_toggle()` | バックライトの明滅動作をオンまたはオフにする |
+| `breathing_enable()` | バックライトの明滅動作をオンにする |
+| `breathing_disable()` | バックライトの明滅動作をオフにする |
+
+## ドライバの設定
+
+どのドライバを使うかを選択するには、以下を使って `rules.mk` を設定します:
+
+```makefile
+BACKLIGHT_DRIVER = software # 有効なドライバの値は 'pwm,software,no' です
+```
+
+各ドライバについてのヘルプは以下を見てください。
+
+## 共通のドライバ設定
+
+バックライトの挙動を変更するには、`config.h` の中で以下の `#define` をします:
+
+| 定義 | デフォルト | 説明 |
+|---------------------|-------------|--------------------------------------------------------------------------------------|
+| `BACKLIGHT_LEVELS` | `3` | 輝度のレベルの数 (オフを除いて最大 31) |
+| `BACKLIGHT_CAPS_LOCK` | *定義なし* | バックライトを使って Caps Lock のインジケータを有効にする (専用 LED の無いキーボードのため) |
+| `BACKLIGHT_BREATHING` | *定義なし* | サポートされる場合は、バックライトの明滅動作を有効にする |
+| `BREATHING_PERIOD` | `6` | 各バックライトの "明滅" の長さ（秒） |
+| `BACKLIGHT_ON_STATE` | `0` | バックライトが "オン" の時のバックライトピンの状態 - high の場合は `1`、low の場合は `0` |
+
+### バックライトオン状態
+
+ほとんどのバックライトの回路は N チャンネルの MOSFET あるいは NPN トランジスタによって駆動されます。これは、トランジスタを*オン*にして LED を点灯させるには、ゲートまたはベースに接続されているバックライトピンを *high* に駆動する必要があることを意味します。
+ただし、P チャンネルの MOSFET あるいは PNP トランジスタが使われる場合があります。この場合、トランジスタがオンの時、ピンは代わりに *low* で駆動されます。
+
+この機能は `BACKLIGHT_ON_STATE` 定義することでキーボードレベルで設定されます。
+
+## AVR ドライバ
+
+AVR ボードでは、デフォルトのドライバは現在のところ最善のシナリオを選択するために構成を探っています。ドライバはデフォルトで設定されますが、rules.mk 内の同等の設定は以下の通りです:
+```makefile
+BACKLIGHT_DRIVER = pwm
+```
+
+### 注意事項
+
+ハードウェア PWM は以下の表に従ってサポートされます:
+
+| バックライトピン | 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 |  |
+
+他の全てのピンはソフトウェア PWM を使います。[オーディオ](ja/feature_audio.md)機能が無効あるいは1つのタイマだけを使っている場合は、ハードウェアタイマによってバックライト PWM を引き起こすことができます:
+
+| オーディオピン | オーディオタイマ | ソフトウェア PWM タイマ |
+|---------|-----------|------------------|
+| `C4` | Timer 3 | Timer 1 |
+| `C5` | Timer 3 | Timer 1 |
+| `C6` | Timer 3 | Timer 1 |
+| `B5` | Timer 1 | Timer 3 |
+| `B6` | Timer 1 | Timer 3 |
+| `B7` | Timer 1 | Timer 3 |
+
+両方のタイマーがオーディオのために使われている場合、バックライト PWM はハードウェアタイマを使いませんが、代わりにマトリックススキャンの間に引き起こされます。この場合、PWM の計算は十分なタイミングの精度で呼ばれないかもしれないため、バックライトの明滅はサポートされず、バックライトもちらつくかもしれません。
+
+### AVR 設定
+
+バックライトの挙動を変更するには、`config.h` の中で以下の `#define` をします:
+
+| 定義 | デフォルト | 説明 |
+|---------------------|-------------|--------------------------------------------------------------------------------------------------------------|
+| `BACKLIGHT_PIN` | `B7` | LED を制御するピン。自身のキーボードを設計している場合を除き、これを変更する必要はないはずです |
+| `BACKLIGHT_PINS` | *定義なし* | 実験的: 詳細は以下を見てください |
+| `BACKLIGHT_LEVELS` | `3` | 輝度のレベルの数 (オフを除いて最大 31) |
+| `BACKLIGHT_CAPS_LOCK` | *定義なし* | バックライトを使って Caps Lock のインジケータを有効にする (専用 LED の無いキーボードのため) |
+| `BACKLIGHT_BREATHING` | *定義なし* | サポートされる場合は、バックライトの明滅動作を有効にする |
+| `BREATHING_PERIOD` | `6` | 各バックライトの "明滅" の長さ（秒） |
+| `BACKLIGHT_ON_STATE` | `1` | バックライトが "オン" の時のバックライトピンの状態 - high の場合は `1`、low の場合は `0` |
+
+### バックライトオン状態
+
+ほとんどのバックライトの回路は N チャンネルの MOSFET あるいは NPN トランジスタによって駆動されます。これは、トランジスタを*オン*にして LED を点灯させるには、ゲートまたはベースに接続されているバックライトピンを *high* に駆動する必要があることを意味します。
+ただし、P チャンネルの MOSFET あるいは PNP トランジスタが使われる場合があります。この場合、トランジスタがオンの時、ピンは代わりに *low* で駆動されます。
+
+この機能は `BACKLIGHT_ON_STATE` 定義することでキーボードレベルで設定されます。
+
+### 複数のバックライトピン
+
+ほとんどのキーボードは、全てのバックライト LED を制御するたった1つのバックライトピンを持ちます (特にバックライトがハードウェア PWM ピンに接続されている場合)。
+ソフトウェア PWM では、複数のバックライトピンを定義することができます。これらすべてのピンは PWM デューティサイクル時に同時にオンおよびオフになります。
+この機能により、例えば Caps Lock LED (またはその他の制御可能な LED) の輝度を、バックライトの他の LED と同じレベルに設定することができます。Caps Lock の代わりに LCTRL をマップしていて、Caps Lock がオンの時に Caps Lock LED をアクティブにする代わりにバックライトの一部にする必要がある場合に便利です。
+
+複数のバックライトピンをアクティブにするには、`config.h` に次のようなものを追加する必要があります:
+
+```c
+#define BACKLIGHT_LED_COUNT 2
+#undef BACKLIGHT_PIN
+#define BACKLIGHT_PINS { F5, B2 }
+```
+
+### ハードウェア PWM 実装
+
+バックライト用にサポートされているピンを使う場合、QMK は PWM 信号を出力するように設定されたハードウェアタイマを使います。タイマーは 0 にリセットする前に `ICRx` (デフォルトでは `0xFFFF`) までカウントします。
+希望の輝度が計算され、`OCRxx` レジスタ内に格納されます。カウンタがこの値まで達すると、バックライトピンは low になり、カウンタがリセットされると再び high になります。
+このように `OCRxx` は基本的に LED のデューティサイクル、従って輝度を制御します。`0x0000` は完全にオフで、 `0xFFFF` は完全にオンです。
+
+明滅動作の効果はカウンタがリセットされる(秒間あたりおよそ244回)たびに呼び出される `TIMER1_OVF_vect` の割り込みハンドラを登録することで可能になります。
+このハンドラ内で、増分カウンタの値が事前に計算された輝度曲線にマップされます。明滅動作をオフにするには、割り込みを単純に禁止し、輝度を EEPROM に格納されているレベルに再設定します。
+
+### タイマーにアシストされた PWM 実装
+
+`BACKLIGHT_PIN` がハードウェアバックライトピンに設定されていない場合、QMK はソフトウェア割り込みを引き起こすように設定されているハードウェアタイマを使います。タイマーは 0 にリセットする前に `ICRx` (デフォルトでは `0xFFFF`) までカウントします。
+0 に再設定すると、CPU は LED をオンにする OVF (オーバーフロー)割り込みを発火し、デューティサイクルを開始します。
+希望の輝度が計算され、`OCRxx` レジスタ内に格納されます。カウンタがこの値に達すると、CPU は比較出力一致割り込みを発火し、LED をオフにします。
+このように `OCRxx` は基本的に LED のデューティサイクル、従って輝度を制御します。 `0x0000` は完全にオフで、 `0xFFFF` は完全にオンです。
+
+明滅の効果はハードウェア PWM 実装と同じです。
+
+## ARM ドライバ
+
+まだ初期段階ですが、ARM バックライトサポートは最終的に AVR と同等の機能を持つことを目指しています。ドライバはデフォルトで設定されますが、rules.mk 内の同等の設定は以下の通りです:
+```makefile
+BACKLIGHT_DRIVER = pwm
+```
+
+### 注意事項
+
+現在のところ、ハードウェア PWM のみがサポートされ、タイマーはアシストされず、自動設定は提供されません。
+
+?> STMF072 のバックライトサポートのテストは制限されています。人によって違うかもしれません。不明な場合は、rules.mk で `BACKLIGHT_ENABLE = no` を設定します。
+
+### ARM 設定
+
+バックライトの挙動を変更するには、`config.h` の中で以下の `#define` をします:
+
+| 定義 | デフォルト | 説明 |
+|------------------------|-------------|-------------------------------------------------------------------------------------------------------------|
+| `BACKLIGHT_PIN` | `B7` | LED を制御するピン。自身のキーボードを設計している場合を除き、これを変更する必要はないはずです |
+| `BACKLIGHT_PWM_DRIVER` | `PWMD4` | 使用する PWM ドライバ。ピンから PWM タイマへのマッピングについては、ST データシートを見てください。自身のキーボードを設計している場合を除き、これを変更する必要はないはずです |
+| `BACKLIGHT_PWM_CHANNEL` | `3` | 使用する PWM チャンネル。ピンから PWM チャンネルへのマッピングについては、ST データシートを見てください。自身のキーボードを設計している場合を除き、これを変更する必要はないはずです |
+| `BACKLIGHT_PAL_MODE` | `2` | 使用するピンの代替機能。ピンの AF マッピングについては ST データシートを見てください。自身のキーボードを設計している場合を除き、これを変更する必要はないはずです |
+
+## Software PWM Driver :id=software-pwm-driver
+
+他のキーボードのタスクを実行中に PWM をエミュレートすることにより、追加のプラットフォーム設定なしで最大のハードウェア互換性を提供します。トレードオフは、キーボードが忙しい時にバックライトが揺れる可能性があることです。有効にするには、rules.mk に以下を追加します:
+```makefile
+BACKLIGHT_DRIVER = software
+```
+
+### ソフトウェア PWM 設定
+
+バックライトの挙動を変更するには、`config.h` の中で以下の `#define` をします:
+
+| 定義 | デフォルト | 説明 |
+|-----------------|-------------|-------------------------------------------------------------------------------------------------------------|
+| `BACKLIGHT_PIN` | `B7` | LED を制御するピン。自身のキーボードを設計している場合を除き、これを変更する必要はないはずです |
+| `BACKLIGHT_PINS` | *定義なし* | 実験的: 詳細は以下を見てください |
+
+### 複数のバックライトピン
+
+ほとんどのキーボードは、全てのバックライト LED を制御するたった1つのバックライトピンを持ちます (特にバックライトがハードウェア PWM ピンに接続されている場合)。
+ソフトウェア PWM では、複数のバックライトピンを定義することができます。これらすべてのピンは PWM デューティサイクル時に同時にオンおよびオフになります。
+この機能により、例えば Caps Lock LED (またはその他の制御可能な LED) の輝度を、バックライトの他の LED と同じレベルに設定することができます。Caps Lock の代わりに LCTRL をマップしていて、Caps Lock がオンの時に Caps Lock LED をアクティブにする代わりにバックライトの一部にする必要がある場合に便利です。
+
+複数のバックライトピンをアクティブにするには、`config.h` に次のようなものを追加する必要があります:
+
+```c
+#undef BACKLIGHT_PIN
+#define BACKLIGHT_PINS { F5, B2 }
+```
+
+## カスタムドライバ
+
+有効にするには、rules.mk に以下を追加します:
+
+```makefile
+BACKLIGHT_DRIVER = custom
+```
+
+カスタムドライバ API を実装する場合、提供されるキーボードフックは以下の通りです:
+
+```c
+void backlight_init_ports(void) {
+    // オプション - 起動時に実行されます
+    //          - 通常、ここでピンを設定します
+}
+void backlight_set(uint8_t level) {
+    // オプション - レベルの変更時に実行されます
+    //          - 通常、ここで新しい値に応答します
+}
+
+void backlight_task(void) {
+    // オプション - 定期的に実行されます
+    //          - ここで長時間実行されるアクションはパフォーマンスの問題を引き起こします
+}
+```

docs/ja/feature_bluetooth.md

@@ -0,0 +1,52 @@
+# Bluetooth
+
+<!---
+  original document: 5d5ff80:docs/feature_bluetooth.md
+  git diff 5d5ff80 HEAD -- docs/feature_bluetooth.md | cat
+-->
+
+## Bluetooth の既知のサポートハードウェア
+
+現在のところ Bluetooth のサポートは AVR ベースのチップに限られます。Bluetooth 2.1 については、QMK は RN-42 モジュールと、Bluefruit EZ-Key をサポートしますが、後者はもう生産されていません。より最近の BLE プロトコルについては、現在のところ Adafruit Bluefruit SPI Friend のみが直接サポートされています。iOS デバイスに接続するには、BLE が必要です。iOS はマウス入力をサポートしないことに注意してください。
+
+| ボード | Bluetooth プロトコル | 接続タイプ | rules.mk | Bluetooth チップ |
+|----------------------------------------------------------------|----------------------------|----------------|---------------------------|--------------|
+| [Adafruit EZ-Key HID](https://www.adafruit.com/product/1535) | Bluetooth Classic | UART | `BLUETOOTH = AdafruitEZKey` |  |
+| Roving Networks RN-42 (Sparkfun Bluesmirf) | Bluetooth Classic | UART | `BLUETOOTH = RN42` | RN-42 |
+| [Bluefruit LE SPI Friend](https://www.adafruit.com/product/2633) | Bluetooth Low Energy | SPI | `BLUETOOTH = AdafruitBLE` | nRF51822 |
+
+まだサポートされていませんが、可能性のあるもの:
+* [Bluefruit LE UART Friend](https://www.adafruit.com/product/2479)。[tmk 実装がおそらく見つかります](https://github.com/tmk/tmk_keyboard/issues/514)
+* RN-42 ファームウェアが書き込まれた HC-05 ボード。どちらも明らかに CSR BC417 チップを使っています。RN-42 ファームウェアを使って書き込むと、HID 機能が提供されます。
+* Sparkfun Bluetooth Mate
+* HM-13 ベースのボード
+
+### Adafruit BLE SPI Friend
+現在のところ QMK によってサポートされている唯一の bluetooth チップセットは、Adafruit Bluefruit SPI Friend です。Adafruit のカスタムファームウェアを実行する Nordic nRF5182 ベースのチップです。データは Hardware SPI を介した Adafruit の SDEP を使って転送されます。[Feather 32u4 Bluefruit LE](https://www.adafruit.com/product/2829) は Adafruit ファームウェアを搭載した Nordic BLE チップに SPI 経由で接続された AVR mcu であるため、サポートされます。SPI friend を使ってカスタムボードを構築する場合、32u4 feather が使用するピン選択を使うのが最も簡単ですが、以下の定義で config.h オプションでピンを変更することができます:
+* #define AdafruitBleResetPin D4
+* #define AdafruitBleCSPin    B4
+* #define AdafruitBleIRQPin   E6
+
+Bluefruit UART friend は SPI friend に変換することができますが、これにはMDBT40 チップへの直接の再書き込みとはんだ付けが[必要です](https://github.com/qmk/qmk_firmware/issues/2274)。
+
+## Adafruit EZ-Key hid
+これには[ハードウェアの変更](https://www.reddit.com/r/MechanicalKeyboards/comments/3psx0q/the_planck_keyboard_with_bluetooth_guide_and/?ref=search_posts)が必要ですが、Makefile を使って有効にすることができます。ファームウェアは引き続き USB 経由で文字を出力するため、コンピュータ経由で充電する場合は注意してください。任意にオフにするために Bluefruit 上にスイッチを持つことは理にかなっています。
+
+
+<!-- FIXME: Document bluetooth support more completely. -->
+## Bluetooth の Rules.mk オプション
+これらのうちの1つだけを使ってください
+* BLUETOOTH_ENABLE = yes (レガシーオプション)
+* BLUETOOTH = RN42
+* BLUETOOTH = AdafruitEZKey
+* BLUETOOTH = AdafruitBLE
+
+## Bluetooth キーコード
+
+これは複数のキーボードの出力が選択できる場合に使われます。現在のところ、これは USB と Bluetooth の両方をサポートするキーボードで、それらの間の切り替えのみが可能です。
+
+| 名前 | 説明 |
+|----------|----------------------------------------------|
+| `OUT_AUTO` | USB と Bluetooth を自動的に切り替える |
+| `OUT_USB` | USB のみ |
+| `OUT_BT` | Bluetooth のみ |

docs/ja/feature_bootmagic.md

@@ -0,0 +1,171 @@
+# ブートマジック
+
+<!---
+  original document: 5d5ff80:docs/feature_bootmagic.md
+  git diff 5d5ff80 HEAD -- docs/feature_bootmagic.md | cat
+-->
+
+再書き込みせずにキーボードの挙動を変更することができる、3つの独立した関連する機能があります。それぞれは似たような機能を持ちますが、キーボードがどのように設定されているかによって異なる方法でアクセスされます。
+
+**ブートマジック**は初期化の間にキーボードを設定するためのシステムです。ブートマジックコマンドを起動するには、ブートマジックキーと1つ以上のコマンドキーを押し続けます。
+
+**ブートマジックキーコード** は前に `MAGIC_` が付いており、キーボードが初期化された*後で*ブートマジックの機能にアクセスすることができます。キーコードを使うには、他のキーコードと同じようにそれらをキーマップに割り当てます。
+
+以前は**マジック**として知られていた**コマンド**は、キーボードの異なる側面を制御することができる別の機能です。ブートマジックと一部の機能を共有しますが、コンソールにバージョン情報を出力するような、ブートマジックにはできないこともできます。詳細は、[コマンド](ja/feature_command.md)を見てください。
+
+一部のキーボードでは、ブートマジックはデフォルトで無効になっています。その場合、`rules.mk` 内で以下のように明示的に有効にする必要があります:
+
+```make
+BOOTMAGIC_ENABLE = full
+```
+
+?> `full` の代わりに `yes` が使われていることがあるかもしれませんが、これは問題ありません。ただし、`yes` は非推奨で、理想的には `full` (あるいは`lite`) が使われるべきです。
+
+さらに、以下を `rules.mk` ファイルに追加することで、[ブートマジックライト](#bootmagic-lite) (スケールダウンした、とても基本的なバージョンのブートマジック)を使うことができます:
+
+```make
+BOOTMAGIC_ENABLE = lite
+```
+
+## ホットキー
+
+キーボードを接続しながら、ブートマジックキー(デフォルトはスペース)と目的のホットキーを押します。例えば、スペースと `B` を押したままにすると、ブートローダに入ります。
+
+| ホットキー | 説明 |
+|------------------|---------------------------------------------|
+| エスケープ | EEPROM のブートマジック設定を無視する |
+| `B` | ブートローダに入る |
+| `D` | シリアルを介するデバッグ出力の切り替え |
+| `X` | キーマトリックスのデバッグ出力の切り替え |
+| `K` | キーボードのデバッグの切り替え |
+| `M` | マウスのデバッグの切り替え |
+| `L` | EE_HANDS 左右設定に、"左手"を設定 |
+| `R` | EE_HANDS 左右設定に、"右手"を設定 |
+| Backspace | EEPROM をクリア |
+| Caps Lock | Caps Lock を左コントロールとして扱うかを切り替え |
+| 左 Control | Caps Lock と左コントロールの入れ替えを切り替え |
+| 左 Alt | 左 Alt と左 GUI の入れ替えを切り替え |
+| 右 Alt | 右 Alt と右 GUI の入れ替えを切り替え |
+| 左 GUI | GUI キーの有効・無効を切り替え (ゲームの時に便利です) |
+| <code>&#96;</code> | <code>&#96;</code> とエスケープの入れ替えを切り替え |
+| `\` | `\` とバックスペースの入れ替えを切り替え |
+| `N` | N キーロールオーバー (NKRO) の有効・無効を切り替え |
+| `0` | レイヤー 0 をデフォルトレイヤーにする |
+| `1` | レイヤー 1 をデフォルトレイヤーにする |
+| `2` | レイヤー 2 をデフォルトレイヤーにする |
+| `3` | レイヤー 3 をデフォルトレイヤーにする |
+| `4` | レイヤー 4 をデフォルトレイヤーにする |
+| `5` | レイヤー 5 をデフォルトレイヤーにする |
+| `6` | レイヤー 6 をデフォルトレイヤーにする |
+| `7` | レイヤー 7 をデフォルトレイヤーにする |
+
+## キーコード :id=keycodes
+
+| キー | エイリアス | 説明 |
+|----------------------------------|---------|--------------------------------------------------------------------------|
+| `MAGIC_SWAP_CONTROL_CAPSLOCK` | `CL_SWAP` | Caps Lock と左コントロールの入れ替え |
+| `MAGIC_UNSWAP_CONTROL_CAPSLOCK` | `CL_NORM` | Caps Lock と左コントロールの入れ替えの解除 |
+| `MAGIC_CAPSLOCK_TO_CONTROL` | `CL_CTRL` | Caps Lock をコントロールとして扱う |
+| `MAGIC_UNCAPSLOCK_TO_CONTROL` | `CL_CAPS` | Caps Lock をコントロールとして扱うことを止める |
+| `MAGIC_SWAP_LCTL_LGUI` | `LCG_SWP` | 左コントロールと GUI の入れ替え |
+| `MAGIC_UNSWAP_LCTL_LGUI` | `LCG_NRM` | 左コントロールと GUI の入れ替えを解除 |
+| `MAGIC_SWAP_RCTL_RGUI` | `RCG_SWP` | 右コントロールと GUI の入れ替え |
+| `MAGIC_UNSWAP_RCTL_RGUI` | `RCG_NRM` | 右コントロールと GUI の入れ替えを解除 |
+| `MAGIC_SWAP_CTL_GUI` | `CG_SWAP` | 両側のコントロールと GUI の入れ替え |
+| `MAGIC_UNSWAP_CTL_GUI` | `CG_NORM` | 両側のコントロールと GUI の入れ替えを解除 |
+| `MAGIC_TOGGLE_CTL_GUI` | `CG_TOGG` | 両側のコントロールと GUI の入れ替えの切り替え |
+| `MAGIC_SWAP_LALT_LGUI` | `LAG_SWP` | 左 Alt と GUI の入れ替え |
+| `MAGIC_UNSWAP_LALT_LGUI` | `LAG_NRM` | 左 Alt と GUI の入れ替えを解除 |
+| `MAGIC_SWAP_RALT_RGUI` | `RAG_SWP` | 右 Alt と GUI の入れ替え |
+| `MAGIC_UNSWAP_RALT_RGUI` | `RAG_NRM` | 右 Alt と GUI の入れ替えを解除 |
+| `MAGIC_SWAP_ALT_GUI` | `AG_SWAP` | 両側の Alt と GUI の入れ替え |
+| `MAGIC_UNSWAP_ALT_GUI` | `AG_NORM` | 両側の Alt と GUI の入れ替えを解除 |
+| `MAGIC_TOGGLE_ALT_GUI` | `AG_TOGG` | 両側の Alt と GUI の入れ替えの切り替え |
+| `MAGIC_NO_GUI` | `GUI_OFF` | GUI キーを無効にする |
+| `MAGIC_UNNO_GUI` | `GUI_ON` | GUI キーを有効にする |
+| `MAGIC_SWAP_GRAVE_ESC` | `GE_SWAP` | <code>&#96;</code> とエスケープの入れ替え |
+| `MAGIC_UNSWAP_GRAVE_ESC` | `GE_NORM` | <code>&#96;</code> とエスケープの入れ替えを解除 |
+| `MAGIC_SWAP_BACKSLASH_BACKSPACE` | `BS_SWAP` | `\` とバックスペースを入れ替え |
+| `MAGIC_UNSWAP_BACKSLASH_BACKSPACE` | `BS_NORM` | `\` とバックスペースの入れ替えを解除する |
+| `MAGIC_HOST_NKRO` | `NK_ON` | N キーロールオーバーを有効にする |
+| `MAGIC_UNHOST_NKRO` | `NK_OFF` | N キーロールオーバーを無効にする |
+| `MAGIC_TOGGLE_NKRO` | `NK_TOGG` | N キーロールオーバーの有効・無効を切り替え |
+| `MAGIC_EE_HANDS_LEFT` | `EH_LEFT` | 分割キーボードのマスター側を左手に設定(`EE_HANDS` 用) |
+| `MAGIC_EE_HANDS_RIGHT` | `EH_RGHT` | 分割キーボードのマスター側を右手に設定(`EE_HANDS` 用) |
+
+## 設定
+
+ブートマジックのためのホットキーの割り当てを変更したい場合は、キーボードあるいはキーマップレベルのどちらかで、`config.h` にこれらを `#define` します。
+
+| 定義 | デフォルト | 説明 |
+|----------------------------------------|-------------|---------------------------------------------------|
+| `BOOTMAGIC_KEY_SALT` | `KC_SPACE` | ブートマジックキー |
+| `BOOTMAGIC_KEY_SKIP` | `KC_ESC` | EEPROM のブートマジック設定を無視する |
+| `BOOTMAGIC_KEY_EEPROM_CLEAR` | `KC_BSPACE` | EEPROM 設定をクリアする |
+| `BOOTMAGIC_KEY_BOOTLOADER` | `KC_B` | ブートローダに入る |
+| `BOOTMAGIC_KEY_DEBUG_ENABLE` | `KC_D` | シリアルを介するデバッグ出力の切り替え |
+| `BOOTMAGIC_KEY_DEBUG_MATRIX` | `KC_X` | マトリックスのデバッグを切り替え |
+| `BOOTMAGIC_KEY_DEBUG_KEYBOARD` | `KC_K` | キーボードのデバッグの切り替え |
+| `BOOTMAGIC_KEY_DEBUG_MOUSE` | `KC_M` | マウスのデバッグの切り替え |
+| `BOOTMAGIC_KEY_EE_HANDS_LEFT` | `KC_L` | EE_HANDS 左右設定に、"左手"を設定 |
+| `BOOTMAGIC_KEY_EE_HANDS_RIGHT` | `KC_R` | EE_HANDS 左右設定に、"右手"を設定 |
+| `BOOTMAGIC_KEY_SWAP_CONTROL_CAPSLOCK` | `KC_LCTRL` | 左コントロールと Caps Lock の入れ替え |
+| `BOOTMAGIC_KEY_CAPSLOCK_TO_CONTROL` | `KC_CAPSLOCK` | Caps Lock を左コントロールとして扱うかを切り替え |
+| `BOOTMAGIC_KEY_SWAP_LALT_LGUI` | `KC_LALT` | 左 Alt と左 GUI の入れ替えを切り替え (macOS 用) |
+| `BOOTMAGIC_KEY_SWAP_RALT_RGUI` | `KC_RALT` | 右 Alt と右 GUI の入れ替えを切り替え (macOS 用) |
+| `BOOTMAGIC_KEY_NO_GUI` | `KC_LGUI` | GUI キーの有効・無効を切り替え (ゲームの時に便利です) |
+| `BOOTMAGIC_KEY_SWAP_GRAVE_ESC` | `KC_GRAVE` | <code>&#96;</code> とエスケープの入れ替えを切り替え |
+| `BOOTMAGIC_KEY_SWAP_BACKSLASH_BACKSPACE` | `KC_BSLASH` | `\` とバックスペースの入れ替えを切り替え |
+| `BOOTMAGIC_HOST_NKRO` | `KC_N` | N キーロールオーバー (NKRO) の有効・無効を切り替え |
+| `BOOTMAGIC_KEY_DEFAULT_LAYER_0` | `KC_0` | レイヤー 0 をデフォルトレイヤーにする |
+| `BOOTMAGIC_KEY_DEFAULT_LAYER_1` | `KC_1` | レイヤー 1 をデフォルトレイヤーにする |
+| `BOOTMAGIC_KEY_DEFAULT_LAYER_2` | `KC_2` | レイヤー 2 をデフォルトレイヤーにする |
+| `BOOTMAGIC_KEY_DEFAULT_LAYER_3` | `KC_3` | レイヤー 3 をデフォルトレイヤーにする |
+| `BOOTMAGIC_KEY_DEFAULT_LAYER_4` | `KC_4` | レイヤー 4 をデフォルトレイヤーにする |
+| `BOOTMAGIC_KEY_DEFAULT_LAYER_5` | `KC_5` | レイヤー 5 をデフォルトレイヤーにする |
+| `BOOTMAGIC_KEY_DEFAULT_LAYER_6` | `KC_6` | レイヤー 6 をデフォルトレイヤーにする |
+| `BOOTMAGIC_KEY_DEFAULT_LAYER_7` | `KC_7` | レイヤー 7 をデフォルトレイヤーにする |
+
+# ブートマジックライト :id=bootmagic-lite
+
+本格的なブートマジック機能の他に、ブートローダへのジャンプのみを処理するブートマジックライトがあります。これは、物理的なリセットボタンが無くブートローダにジャンプする方法が必要だが、ブートマジックが引き起こす問題を扱いたくないキーボードに適しています。
+
+ブートマジックのこのバージョンを有効にするには、以下を使って `rules.mk` で有効にする必要があります:
+
+```make
+BOOTMAGIC_ENABLE = lite
+```
+
+さらに、どのキーを使うかを指定したほうが良いかもしれません。これは普通ではないマトリックスを持つキーボードで特に便利です。そのためには、使いたいキーの行と列を指定する必要があります。`config.h` ファイルにこれらのエントリを追加します:
+
+```c
+#define BOOTMAGIC_LITE_ROW 0
+#define BOOTMAGIC_LITE_COLUMN 1
+```
+
+デフォルトでは、これらは 0 と 0 に設定されます。これは通常はほとんどのキーボードで "ESC" キーです。
+
+ブートローダを起動するには、キーボードを接続する時にこのキーを押し続けます。たった1つのキーです。
+
+!> ブートマジックライトを使用すると、EEPROM を**常にリセットします**。つまり保存された全ての設定は失われます。
+
+## 高度なブートマジックライト
+
+`bootmagic_lite` 関数は必要に応じてコード内で置き換えることができるように、弱く定義されています。これの良い例は Zeal60 キーボードで、追加の処理が必要です。
+
+関数を置き換えるには、以下のようなものをコードに追加するだけです:
+
+```c
+void bootmagic_lite(void) {
+    matrix_scan();
+    wait_ms(DEBOUNCE * 2);
+    matrix_scan();
+
+    if (matrix_get_row(BOOTMAGIC_LITE_ROW) & (1 << BOOTMAGIC_LITE_COLUMN)) {
+      // ブートローダにジャンプする。
+      bootloader_jump();
+    }
+}
+```
+
+追加の機能をここに追加することができます。例えば、eeprom のリセットやブートマジックを起動するために押す必要がある追加のキーです。`bootmagic_lite` はファームウェア内で大部分の機能が初期化される前に呼ばれることに注意してください。

docs/ja/feature_combo.md

@@ -0,0 +1,108 @@
+# コンボ
+
+<!---
+  original document: 0.8.94:docs/feature_combo.md
+  git diff 0.8.94 HEAD -- docs/feature_combo.md | cat
+-->
+
+コンボ機能は、同時押し方式でのカスタムアクション追加機能です。同時に複数のキーを押して、異なる効果を生み出すことができます。例えば、タッピング時間内で `A` と `S` を押すと、代わりに `ESC` が押されます。もっと複雑なタスクを実行させることもできます。
+
+この機能を有効にするには、`rules.mk` に `COMBO_ENABLE = yes` を追加する必要があります。
+
+さらに、使用するコンボの数を `config.h` の中で、`#define COMBO_COUNT 1` (1を使用するコンボの数で置き換えます)と書いて、指定する必要があります。
+<!-- At this time, this is necessary -->
+
+また、デフォルトでは、コンボのタッピング時間は `TAPPING_TERM` と同じ値に設定されます (ほとんどのキーボードではデフォルトで 200)。ただし、`config.h` で定義することにより異なる値を指定することができます。例えば: `#define COMBO_TERM 300` はコンボのためのタイムアウト時間を 300ms に設定します。
+
+次に、`keymap.c` ファイルに、`COMBO_END` で終了するキーのシーケンス、およびキーの組み合わせを列挙する構造体、その結果のアクションを定義する必要があります。
+
+```c
+const uint16_t PROGMEM test_combo[] = {KC_A, KC_B, COMBO_END};
+combo_t key_combos[COMBO_COUNT] = {COMBO(test_combo, KC_ESC)};
+```
+
+これは、A と B のキーを押した場合に、"Escape" を送信します。
+
+!> このメソッドは[基本的なキーコード](ja/keycodes_basic.md)のみをサポートします。詳細な制御については例を見てください。
+
+## 例
+
+リストを追加したい場合は、以下のようなものを使います:
+
+```c
+enum combos {
+  AB_ESC,
+  JK_TAB
+};
+
+const uint16_t PROGMEM ab_combo[] = {KC_A, KC_B, COMBO_END};
+const uint16_t PROGMEM jk_combo[] = {KC_J, KC_K, COMBO_END};
+
+combo_t key_combos[COMBO_COUNT] = {
+  [AB_ESC] = COMBO(ab_combo, KC_ESC),
+  [JK_TAB] = COMBO(jk_combo, KC_TAB)
+};
+```
+
+より複雑な実装として、カスタム処理を追加するために `process_combo_event` 関数を使うことができます。
+
+```c
+enum combo_events {
+  ZC_COPY,
+  XV_PASTE
+};
+
+const uint16_t PROGMEM copy_combo[] = {KC_Z, KC_C, COMBO_END};
+const uint16_t PROGMEM paste_combo[] = {KC_X, KC_V, COMBO_END};
+
+combo_t key_combos[COMBO_COUNT] = {
+  [ZC_COPY] = COMBO_ACTION(copy_combo),
+  [XV_PASTE] = COMBO_ACTION(paste_combo),
+};
+
+void process_combo_event(uint8_t combo_index, bool pressed) {
+  switch(combo_index) {
+    case ZC_COPY:
+      if (pressed) {
+        tap_code16(LCTL(KC_C));
+      }
+      break;
+    case XV_PASTE:
+      if (pressed) {
+        tap_code16(LCTL(KC_V));
+      }
+      break;
+  }
+}
+```
+
+これは、Z と C を押すと Ctrl+C を送信し、X と V を押すと Ctrl+V を送信します。これを変更して、レイヤーの変更、サウンドの再生、設定の変更などを行うこともできます。
+
+## 追加の設定
+
+長いコンボあるいはさらに長いコンボを使っている場合、構造体があなたのしていることに対応するのに十分な大きさで無いかもしれないため、問題が発生するかもしれません。
+
+この場合、`config.h` ファイルに `#define EXTRA_LONG_COMBOS` または `#define EXTRA_EXTRA_LONG_COMBOS` のどちらかを追加することができます。
+
+`COMBO_ALLOW_ACTION_KEYS` を定義することでアクションキーを有効にすることもできます。
+
+## キーコード
+
+その場でコンボ機能を有効、無効および切り替えすることができます。ゲームなどで、一時的にそれらを無効にする必要がある場合に便利です。
+
+| キーコード | 説明 |
+|----------|---------------------------------|
+| `CMB_ON` | コンボ機能をオンにします |
+| `CMB_OFF` | コンボ機能をオフにします |
+| `CMB_TOG` | コンボ機能のオンとオフを切り替えます |
+
+## ユーザコールバック
+
+キーコードに加えて、状態を設定または状態をチェックするために使うことができる幾つかの関数があります:
+
+| 関数 | 説明 |
+|-----------|--------------------------------------------------------------------|
+| `combo_enable()` | コンボ機能を有効にします |
+| `combo_disable()` | コンボ機能を無効にし、コンボバッファをクリアします |
+| `combo_toggle()` | コンボ機能の状態を切り替えます |
+| `is_combo_enabled()` | コンボ機能の状態(true か false)を返します |

docs/ja/feature_dip_switch.md

@@ -0,0 +1,95 @@
+# DIP スイッチ
+
+<!---
+  original document: 0.8.94:docs/feature_dip_switch.md
+  git diff 0.8.94 HEAD -- docs/feature_dip_switch.md | cat
+-->
+
+DIP スイッチは、以下を `rules.mk` に追加することでサポートされます:
+
+    DIP_SWITCH_ENABLE = yes
+
+さらに、以下を `config.h` に追加します:
+
+```c
+#define DIP_SWITCH_PINS { B14, A15, A10, B9 }
+```
+
+## コールバック
+
+コールバック関数を `<keyboard>.c` に記述することができます:
+
+```c
+void dip_switch_update_kb(uint8_t index, bool active) { 
+    dip_switch_update_user(index, active); 
+}
+```
+
+
+あるいは `keymap.c` に記述することもできます:
+
+```c
+void dip_switch_update_user(uint8_t index, bool active) { 
+    switch (index) {
+        case 0:
+            if(active) { audio_on(); } else { audio_off(); }
+            break;
+        case 1:
+            if(active) { clicky_on(); } else { clicky_off(); }
+            break;
+        case 2:
+            if(active) { music_on(); } else { music_off(); }
+            break;
+        case 3:
+            if (active) {
+                #ifdef AUDIO_ENABLE
+                    PLAY_SONG(plover_song);
+                #endif
+                layer_on(_PLOVER);
+            } else {
+                #ifdef AUDIO_ENABLE
+                    PLAY_SONG(plover_gb_song);
+                #endif
+                layer_off(_PLOVER);
+            }
+            break;
+    }
+}
+```
+
+更に、より複雑な処理ができるビットマスク関数をサポートします。
+
+
+```c
+void dip_switch_update_mask_kb(uint32_t state) { 
+    dip_switch_update_mask_user(state); 
+}
+```
+
+
+あるいは `keymap.c` に記述することもできます:
+
+```c
+void dip_switch_update_mask_user(uint32_t state) { 
+    if (state & (1UL<<0) && state & (1UL<<1)) {
+        layer_on(_ADJUST); // C on esc
+    } else {
+        layer_off(_ADJUST);
+    }
+    if (state & (1UL<<0)) {
+        layer_on(_TEST_A); // A on ESC
+    } else {
+        layer_off(_TEST_A);
+    }
+    if (state & (1UL<<1)) {
+        layer_on(_TEST_B); // B on esc
+    } else {
+        layer_off(_TEST_B);
+    }
+}
+```
+
+
+## ハードウェア
+
+DIP スイッチの片側は MCU のピンへ直接配線し、もう一方の側はグラウンドに配線する必要があります。機能的に同じであるため、どちら側がどちらに接続されているかは問題にはならないはずです。

docs/ja/flashing.md

@@ -1,13 +1,13 @@
 # 書き込みの手順とブートローダ情報
 
 <!---
-  original document: 7494490d6:docs/flashing.md
-  git diff 7494490d6 HEAD -- docs/flashing.md | cat
+  original document: 0.8.62:docs/flashing.md
+  git diff 0.8.62 HEAD -- docs/flashing.md | cat
 -->
 
 キーボードが使用するブートローダにはかなり多くの種類があり、ほぼ全てが異なる書き込みの方法を使います。幸いなことに、[QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) のようなプロジェクトは、あまり深く考える必要無しに様々なタイプと互換性を持つことを目指していますが、この文章では様々なタイプのブートローダとそれらを書き込むために利用可能な方法について説明します。
 
-`rules.mk` の `BOOTLOADER` 変数で選択されたブートローダがある場合、QMK は .hex ファイルがデバイスに書き込むのに適切なサイズかどうかを自動的に計算し、合計サイズをバイト単位で(最大値とともに)出力します。この処理を手動で実行するには、`check-size` を付けてコンパイルします。例えば、`make planck/rev4:default:check-size`。
+`rules.mk` の `BOOTLOADER` 変数で選択されたブートローダがある場合、QMK は .hex ファイルがデバイスに書き込むのに適切なサイズかどうかを自動的に計算し、合計サイズをバイト単位で(最大値とともに)出力します。
 
 ## DFU
 
@@ -31,7 +31,6 @@ BOOTLOADER = atmel-dfu
 
 * [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) (推奨の GUI)
 * QMK の [dfu-programmer](https://github.com/dfu-programmer/dfu-programmer) / `:dfu` (推奨のコマンドライン)
-* [Atmel の Flip](http://www.microchip.com/developmenttools/productdetails.aspx?partno=flip) (非推奨)
 
 書き込み手順:
 
@@ -105,7 +104,7 @@ BOOTLOADER = caterina
     make <keyboard>:<keymap>:avrdude
 
 
-#### Caterina コマンド
+### Caterina コマンド
 
 ファームウェアを DFU デバイスに書き込むために使用できる DFU コマンドがいくつかあります。
 

docs/ja/getting_started_build_tools.md

@@ -1,146 +0,0 @@
-# ビルドツールのインストール
-
-<!---
-  original document: 5a02cc00a:docs/getting_started_build_tools.md
-  git diff 5a02cc00a HEAD -- docs/getting_started_build_tools.md | cat
--->
-
-このページは QMK のためのビルド環境のセットアップを説明します。これらの手順は (atmega32u4 のような) AVR プロセッサを対象としてします。
-
-<!-- FIXME: We should have ARM instructions somewhere. -->
-
-**注意:** ここが初めての場合は、[QMK 初心者ガイド](ja/newbs.md)ページを調べてください。
-
-続ける前に、`make git-submodule` を実行して、サブモジュール(サードパーティライブラリ)が最新であることを再確認してください。
-
-## Linux
-
-常に最新の状態を保つためには、単に `sudo util/qmk_install.sh` を実行してください。全ての必要な依存関係が常にインストールされるはずです。**これは `apt-get upgrade` を実行します。**
-
-手動でインストールすることもできますが、このドキュメントは常に全ての要件を満たしているとは限りません。
-
-現在の要件は以下の通りですが、何をしようとしているかによっては全てが必要とは限りません。また、一部のシステムではパッケージとして全ての依存関係が利用できるとは限らず、あるいは名前が異なる場合があるかもしれません。
-
-```
-build-essential
-gcc
-unzip
-wget
-zip
-gcc-avr
-binutils-avr
-avr-libc
-dfu-programmer
-dfu-util
-gcc-arm-none-eabi
-binutils-arm-none-eabi
-libnewlib-arm-none-eabi
-git
-```
-
-好みのパッケージマネージャを使って依存関係をインストールします。
-
-Debian / Ubuntu の例:
-
-    sudo apt-get update
-    sudo apt-get install gcc unzip wget zip gcc-avr binutils-avr avr-libc dfu-programmer dfu-util gcc-arm-none-eabi binutils-arm-none-eabi libnewlib-arm-none-eabi
-
-Fedora / Red Hat の例:
-
-    sudo dnf install gcc unzip wget zip dfu-util dfu-programmer avr-gcc avr-libc binutils-avr32-linux-gnu arm-none-eabi-gcc-cs arm-none-eabi-binutils-cs arm-none-eabi-newlib
-
-Arch / Manjaro の例:
-
-    pacman -S base-devel gcc unzip wget zip avr-gcc avr-binutils avr-libc dfu-util arm-none-eabi-gcc arm-none-eabi-binutils arm-none-eabi-newlib git dfu-programmer dfu-util
-
-## Nix
-
-[NixOS](https://nixos.org/) の場合、あるいは Linux または MacOS に Nix をインストールした場合は、ビルド環境を取得するためにリポジトリのルートで `nix-shell` を実行します。
-
-デフォルトでは、これは AVR と ARM の両方のためのコンパイラをダウンロードします。両方が必要ではない場合は、`avr` あるいは `arm` 引数を無効にします。例えば:
-
-    nix-shell --arg arm false
-
-## macOS
-[Homebrew](http://brew.sh/) を使っている場合は、以下のコマンドを使うことができます:
-
-    brew tap osx-cross/avr
-    brew tap osx-cross/arm
-    brew update
-    brew install avr-gcc@8
-    brew link --force avr-gcc@8
-    brew install dfu-programmer
-    brew install dfu-util
-    brew install arm-gcc-bin@8
-    brew link --force arm-gcc-bin@8
-    brew install avrdude
-
-これはお勧めの方法です。homebrew が無い場合は、[インストールしてください！](http://brew.sh/) コマンドラインで作業する人にとってとても価値があります。`avr-gcc@8` の homebrew でのインストール中、`make` と `make install` 部分は20分以上かかり、CPU使用率が高くなることに注意してください。
-
-## msys2 を使った Windows (推奨) :id=windows-with-msys2-recommended
-
-Windows Vista 以降のバージョン(7および10でテスト済み)について、使用するのに最適な環境は [msys2](http://www.msys2.org) です。
-
-* msys2 をダウンロードし、こちらの指示に従ってインストールしてください: http://www.msys2.org
-* ``MSYS2 MingGW 64-bit`` のショートカットを開きます
-* QMK リポジトリに移動します。例えば、c ドライブのルートにある場合:
-* `$ cd /c/qmk_firmware`
-* `util/qmk_install.sh` を実行し、指示に従います
-
-## Windows 10 (非推奨)
-Windows 10 の古い手順です。[上記の概要のように MSYS2](#windows-with-msys2-recommended) を使うことをお勧めします。
-
-### Creators Update
-Creators Update 以降の Windows 10 の場合、ファームウェアを直接ビルドして書き込むことができます。Creators Update の前は、ビルドだけが可能でした。まだそうではないか、不明な場合は、[これらの指示](https://support.microsoft.com/en-us/instantanswers/d4efb316-79f0-1aa1-9ef3-dcada78f3fa0/get-the-windows-10-creators-update)に従ってください。
-
-### Linux 用の Windows Subsystem
-Creators Update に加えて、Linux 用の Windows 10 Subystem が必要ですので、[これらの指示](http://www.howtogeek.com/249966/how-to-install-and-use-the-linux-bash-shell-on-windows-10/)に従ってインストールしてください。Anniversary update からの Linux 用の Windows 10 Subsystem が既にある場合、一部のキーボードは 14.04LTS に含まれるツールチェーンを使ってコンパイルしないため、16.04LTS に[アップグレード](https://betanews.com/2017/04/14/upgrade-windows-subsystem-for-linux/)することをお勧めします。`sudo do-release-upgrade` メソッドを選択した場合は、自分が何をしているかを知る必要があることに注意してください。
-
-### Git
-すでに Windows ファイルシステムにリポジトリをクローンしている場合は、この章を無視することができます。
-
-WSL Git では**なく**、Windows 用の通常の Git を使って Windows ファイルシステムにリポジトリをクローンする必要があります。以前に Git をインストールしたことが無ければ、[ダウンロード](https://git-scm.com/download/win)し、インストールしてください。次に[セットアップします](https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup)。特に貢献する予定がある場合は、eメールとユーザ名をセットアップすることが重要です。
-
-Git がインストールされたら、Git Bash コマンドを開き、QMK をクローンしたい場所へディレクトリを変更します: スラッシュを使う必要があり、c ドライブは `/c/path/to/where/you/want/to/go` のようにアクセスされることに注意してください。次に、`git clone --recurse-submodules https://github.com/qmk/qmk_firmware` を実行します。これは現在のフォルダのサブディレクトリとして新しいフォルダ `qmk_firmware` を作成します。
-
-### ツールチェーンのセットアップ
-ツールチェーンのセットアップは Linux 用の Windows サブシステムを介して行われ、手順は完全に自動化されています。全てを手動で行いたい場合は、スクリプト以外の手順はありませんが、常に issue を開いて詳細情報を求めることができます。
-
-1. スタートメニューから "Bash On Ubuntu On Windows" を開いてください。
-2. クローンした `qmk_firmware` ディレクトリに移動します。パスは WSL 内で `/mnt/` から始まることに注意してください。つまり、例えば `cd /mnt/c/path/to/qmk_firmware` と書く必要があります。
-3. `util/wsl_install.sh` を実行し、画面上の手順に従います。
-4. Bash コマンドウィンドウを閉じ、再び開きます。
-5. ファームウェアをコンパイルし書き込む準備ができました！
-
-### 心に留めておくべき幾つかの重要なこと
-* 全ての最新の更新を取得するために `util/wsl_install.sh` を再実行することができます。
-* WSL は外部で実行可能ファイルを実行できないため、QMK リポジトリは Windows ファイルシステム上にある必要があります。
-* WSL Git は Windows の Git と互換性が**無い**ため、全ての Git 操作には、Windows Git Bash あるいは windows Git GUI を使ってください。
-* WSL 内あるいは普通に Windows を使ってファイルを編集できますが、makefile あるいはシェルスクリプトを編集する場合は、行末をUnix形式にしてファイルを保存するエディタを使うようにしてください。そうでなければコンパイルは機能しないかもしれません。
-
-## Docker
-
-これが少し複雑な場合は、Docker があなたが必要とするすぐに使える解決法かもしれません。[Docker CE](https://docs.docker.com/install/#supported-platforms) をインストールした後で、キーボード/キーマップをビルドするために `qmk_firmware` ディレクトリから以下のコマンドを実行します:
-```bash
-util/docker_build.sh keyboard:keymap
-# 例えば: util/docker_build.sh ergodox_ez:steno
-```
-これは目的のキーボード/キーマップをコンパイルし、結果として書き込み用に `.hex` あるいは `.bin` ファイルを QMK ディレクトリの中に残します。`:keymap` が省略された場合は全てのキーマップが使われます。パラメータの形式は、`make` を使ってビルドする時と同じであることに注意してください。
-
-スクリプトをパラメータ無しで開始することもできます。この場合、1つずつビルドパラメータを入力するように求められます。これが使いやすいと思うかもしれません:
-```bash
-util/docker_build.sh
-# パラメータを入力として読み込みます (空白にすると全てのキーボード/キーマップ)
-```
-
-`target` を指定することで Docker から直接キーボードをビルドし_かつ_書き込むためのサポートもあります。
-```bash
-util/docker_build.sh keyboard:keymap:target
-# 例えば: util/docker_build.sh planck/rev6:default:flash
-```
-Linux を使っている場合は、これはそのままで動作するはずです。Windows と macOS では、実行するのに [Docker Machine](http://gw.tnode.com/docker/docker-machine-with-usb-support-on-windows-macos/) が必要です。これはセットアップが面倒なので、お勧めではありません: 代わりに [QMK Toolbox](https://github.com/qmk/qmk_toolbox) を使ってください。
-
-!> Docker for Windows は[Hyper-V](https://docs.microsoft.com/en-us/virtualization/hyper-v-on-windows/quick-start/enable-hyper-v) を有効にする必要があります。これは、Windows 7、Windows 8 および **Windows 10 Home** のような Hyper-V を搭載していない Windows のバージョンでは機能しないことを意味します。
-
-## Vagrant
-ファームウェアをビルドするのに問題がある場合は、Vagrant と呼ばれるツールを試してみることができます。それは、ファームウェアをビルドする準備ができた既知の構成を搭載した仮想コンピュータをセットアップします。OLKB はこの仮想コンピュータのためのファイルをホストしません。Vagrant をセットアップする方法の詳細は、[vagrant ガイド](ja/getting_started_vagrant.md)にあります。

docs/ja/getting_started_getting_help.md

@@ -1,20 +0,0 @@
-# 助けを得る
-
-<!---
-  original document: d598f01cb:docs/getting_started_getting_help.md
-  git diff d598f01cb HEAD -- docs/getting_started_getting_help.md | cat
--->
-
-QMK に関して助けを得るための多くのリソースがあります。
-
-## リアルタイム チャット
-
-メインの [Discord server](https://discord.gg/Uq7gcHh) で QMK の開発者とユーザを見つけることができます。サーバには、ファームウェア、Toolbox、ハードウェアおよび Configurator についてチャットするための特定のチャンネルがあります。
-
-## OLKB Subreddit
-
-公式の QMK フォーラムは [reddit.com](https://reddit.com) の [/r/olkb](https://reddit.com/r/olkb) です。
-
-## Github Issues
-
-[GitHub で issue](https://github.com/qmk/qmk_firmware/issues) を開くことができます。issue が長期的な議論あるいはデバッグを必要とする場合は、特に便利です。

docs/ja/getting_started_github.md

@@ -1,8 +1,8 @@
 # QMK で Github を使う方法
 
 <!---
-  original document: d598f01cb:docs/getting_started_github.md
-  git diff d598f01cb HEAD -- docs/getting_started_github.md | cat
+  original document: 0.8.82:docs/getting_started_github.md
+  git diff 0.8.82 HEAD -- docs/getting_started_github.md | cat
 -->
 
 Github は慣れていない人には少し注意が必要です - このガイドは、QMK におけるフォーク、クローン、プルリクエストのサブミットの各ステップについて説明します。

docs/ja/getting_started_introduction.md

@@ -1,8 +1,8 @@
 # はじめに
 
 <!---
-  original document: d598f01cb:docs/getting_started_introduction.md
-  git diff d598f01cb HEAD -- docs/getting_started_introduction.md | cat
+  original document: 0.8.82:docs/getting_started_introduction.md
+  git diff 0.8.82 HEAD -- docs/getting_started_introduction.md | cat
 -->
 
 このページでは、QMK プロジェクトで作業するために知っておくべき基本的な情報について説明しようと思います。Unix シェルの操作に精通していることを前提としていますが、C について、または make を使ったコンパイルについて精通しているとは想定していません。

docs/ja/getting_started_vagrant.md

@@ -25,7 +25,6 @@ Vagrant 以外に、適切なプロバイダがインストールされ、その
 
 * [QMK Toolbox](https://github.com/qmk/qmk_toolbox) (推奨)
 * [Teensy ローダー](https://www.pjrc.com/teensy/loader.html)
-* [Atmel FLIP](http://www.atmel.com/tools/flip.aspx)
 
 コマンドラインでプログラムしたい場合は、Vagranfile の ['modifyvm'] 行のコメントを解除して Linux への USB パススルーを有効にし、dfu-util/dfu-programmer のようなコマンドラインツールを使ってプログラムすることができます。あるいは Teensy CLI バージョンをインストールすることができます。
 

docs/ja/hardware_avr.md

@@ -0,0 +1,189 @@
+# AVR マイコンを使ったキーボード
+
+<!---
+  grep --no-filename "^[ ]*git diff" docs/ja/*.md | sh
+  original document: c9e3fa6f7:docs/hardware_avr.md
+  git diff c9e3fa6f7 HEAD -- docs/hardware_avr.md | cat
+-->
+
+このページでは QMK における AVR マイコンのサポートについて説明します。AVR マイコンには、Atmel 社製の atmega32u4、atmega32u2、at90usb1286 やその他のマイコンを含みます。AVR マイコンは、簡単に動かせるよう設計された8ビットの MCU です。キーボードでよく使用される AVR マイコンには USB 機能や大きなキーボードマトリックスのためのたくさんの GPIO を搭載しています。これらは、現在、キーボードで使われる最も一般的な MCU です。
+
+まだ読んでない場合は、[キーボードガイドライン](ja/hardware_keyboard_guidelines.md) を読んで、キーボードを QMK にどのように適合させるかを把握する必要があります。
+
+## AVR を使用したキーボードを QMK に追加する
+
+QMK には AVR を使ったキーボードでの作業を簡略化するための機能が多数あります。大体のキーボードでは1行もコードを書く必要がありません。まずはじめに、`util/new_keyboard.sh` スクリプトを実行します。
+
+```
+$ ./util/new_keyboard.sh
+Generating a new QMK keyboard directory
+
+Keyboard Name: mycoolkb
+Keyboard Type [avr]: 
+Your Name [John Smith]: 
+
+Copying base template files... done
+Copying avr template files... done
+Renaming keyboard files... done
+Replacing %KEYBOARD% with mycoolkb... done
+Replacing %YOUR_NAME% with John Smith... done
+
+Created a new keyboard called mycoolkb.
+
+To start working on things, cd into keyboards/mycoolkb,
+or open the directory in your favourite text editor.
+```
+
+これにより、新しいキーボードをサポートするために必要なすべてのファイルが作成され、デフォルト値で設定が入力されます。あとはあなたのキーボード用にカスタマイズするだけです。
+
+## `readme.md`
+
+このファイルではキーボードに関する説明を記述します。[キーボード Readme テンプレート](ja/documentation_templates.md#keyboard-readmemd-template)に従って `readme.md` を記入して下さい。`readme.md` の上部に画像を配置することをお勧めします。画像は [Imgur](http://imgur.com) のような外部サービスを利用してください。
+
+## `<keyboard>.c`
+
+このファイルではキーボード上で実行される全てのカスタマイズされたロジックを記述します。多くのキーボードの場合、何も書く必要はありません。
+[機能のカスタマイズ](ja/custom_quantum_functions.md)で、カスタマイズされたロジックの記述方法を詳しく学ぶことが出来ます。
+
+## `<keyboard>.h`
+
+このファイルでは、[レイアウト](ja/feature_layouts.md)を定義します。最低限、以下のような `#define LAYOUT` を記述する必要があります。
+
+```c
+#define LAYOUT(          \
+      k00, k01, k02,     \
+      k10,   k11         \
+) {                      \
+    { k00, k01,   k02 }, \
+    { k10, KC_NO, k11 }, \
+}
+```
+
+`LAYOUT` マクロの前半部ではキーの物理的な配置を定義します。後半部ではスイッチが接続されるマトリックスを定義します。これによってマトリックス配線の順とは異なるキーを物理的に配置できます。
+
+それぞれの `k__` 変数はユニークでなければいけません。通常は `k<row><col>` というフォーマットに従って記述されます。
+
+物理マトリックス（後半部）では、`MATRIX_ROWS` に等しい行数が必要であり、各行には正確に `MATRIX_COLS` と等しい数の要素が含まれていなければいけません。物理キーが存在しない場合は、`KC_NO` を使用して空白を埋める事ができます。
+
+## `config.h`
+
+`config.h` ファイルには、ハードウェアや機能の設定を記述します。このファイルで設定できるオプションは列挙しきれないほどたくさんあります。利用できるオプションの概要は[設定オプション](ja/config_options.md)を参照して下さい。
+
+### ハードウェアの設定
+
+`config.h` の先頭には USB に関する設定があります。これらはキーボードが OS からどのように見えるかを制御しています。変更する理由がない場合は、`VENDOR_ID` を `0xFEED` のままにしておく必要があります。`PRODUCT_ID` にはまだ使用されていない番号を選ばなければいけません。
+
+`MANUFACTURER`、 `PRODUCT`、 `DESCRIPTION` をキーボードにあった設定に変更します。
+
+```c
+#define VENDOR_ID       0xFEED
+#define PRODUCT_ID      0x6060
+#define DEVICE_VER      0x0001
+#define MANUFACTURER    You
+#define PRODUCT         my_awesome_keyboard
+#define DESCRIPTION     A custom keyboard
+```
+
+?> Windows や macOS では、`MANUFACTURER` と `PRODUCT` が USBデバイスのリストに表示されます。Linux 上の `lsusb` では、代わりにデフォルトで [USB ID Repository](http://www.linux-usb.org/usb-ids.html) によって維持されているリストからこれらを取得します。`lsusb -v` を使用するとデバイスから示された値を表示します。また、接続したときのカーネルログにも表示されます。
+
+### キーボードマトリックスの設定
+
+`config.h` ファイルの次のセクションではキーボードのマトリックスを扱います。最初に設定するのはマトリックスのサイズです。これは通常、常にではありませんが、物理キー配置と同じ数の行・列になります。
+
+```c
+#define MATRIX_ROWS 2
+#define MATRIX_COLS 3
+```
+
+マトリックスのサイズを定義したら、MCU のどのピンを行と列に接続するかを定義します。そのためにはピンの名前を指定するだけです。
+
+```c
+#define MATRIX_ROW_PINS { D0, D5 }
+#define MATRIX_COL_PINS { F1, F0, B0 }
+#define UNUSED_PINS
+```
+
+
+`MATRIX_ROW_PINS` の要素の数は `MATRIX_ROWS` に定義した数と同じでなければいけません。同様に `MATRIX_COL_PINS` の要素の数も `MATRIX_COLS` と等しい必要があります。`UNUSED_PINS` は定義しなくても問題ありませんがどのピンが空いているのか記録しておきたい場合は定義できます。
+
+最後にダイオードの方向を定義します。これには `COL2ROW` か `ROW2COL` を設定します。
+
+```c
+#define DIODE_DIRECTION COL2ROW
+```
+
+#### ダイレクトピンマトリックス
+
+各スイッチが、列と行のピンを共有する代わりに、それぞれ個別のピンとグランドに接続されているキーボードを定義するには、`DIRECT_PINS` を使用します。マッピング定義では、列と行の各スイッチのピンを左から右の順に定義します。`MATRIX_ROWS` と `MATRIX_COLS` 内のサイズに準拠する必要があり、空白を埋めるには `NO_PIN` を使用します。これによって `DIODE_DIRECTION`、`MATRIX_ROW_PINS`、`MATRIX_COL_PINS` の動作を上書きします。
+
+```c
+// #define MATRIX_ROW_PINS { D0, D5 }
+// #define MATRIX_COL_PINS { F1, F0, B0 }
+#define DIRECT_PINS { \
+    { F1, E6, B0, B2, B3 }, \
+    { F5, F0, B1, B7, D2 }, \
+    { F6, F7, C7, D5, D3 }, \
+    { B5, C6, B6, NO_PIN, NO_PIN } \
+}
+#define UNUSED_PINS
+
+/* COL2ROW, ROW2COL */
+//#define DIODE_DIRECTION
+```
+
+### バックライトの設定
+
+QMK では GPIO ピンでのバックライト制御をサポートしています。これらの設定を選択して MCU から制御できます。詳しくは[バックライト](ja/feature_backlight.md)を参照して下さい。
+
+```c
+#define BACKLIGHT_PIN B7
+#define BACKLIGHT_LEVELS 3
+#define BACKLIGHT_BREATHING
+#define BREATHING_PERIOD 6
+```
+
+### その他の設定オプション
+
+`config.h` で設定・調整できる機能はたくさんあります。詳しくは[設定オプション](ja/config_options.md)を参照して下さい。
+
+## `rules.mk`
+
+`rules.mk` ファイルを使用して、ビルドするファイルや有効にする機能をQMKへ指示します。atmega32u4 を使っている場合、これらのオプションはデフォルトのままにしておくことが出来ます。他の MCU を使用している場合はいくつかのパラメータを調整する必要があります。
+
+### MCU オプション
+
+このオプションではビルドする CPU をビルドシステムに指示します。これらの設定を変更する場合は非常に注意して下さい。キーボードを操作不能にしてしまう可能性があります。
+
+```make
+MCU = atmega32u4
+F_CPU = 16000000
+ARCH = AVR8
+F_USB = $(F_CPU)
+OPT_DEFS += -DINTERRUPT_CONTROL_ENDPOINT
+```
+
+### ブートローダー
+
+ブートローダーは MCU に保存されているプログラムをアップグレードするための特別なセクションです。キーボードのレスキューパーティションのようなものだと考えて下さい。
+
+#### Teensy Bootloader の例
+
+```make
+BOOTLOADER = halfkay
+```
+
+#### Atmel DFU Loader の例
+
+```make
+BOOTLOADER = atmel-dfu
+```
+
+#### Pro Micro Bootloader の例
+
+```make
+BOOTLOADER = caterina
+```
+
+### ビルドオプション
+
+`rules.mk` にはオン・オフできるたくさんの機能があります。詳細なリストと説明は[設定オプション](ja/config_options.md#feature-options)を参照して下さい。

docs/ja/hardware_drivers.md

@@ -0,0 +1,45 @@
+# QMK ハードウェアドライバー
+
+<!---
+  grep --no-filename "^[ ]*git diff" docs/ja/*.md | sh
+  original document: c9e3fa6f7:docs/hardware_drivers.md
+  git diff c9e3fa6f7 HEAD -- docs/hardware_drivers.md | cat
+-->
+
+QMK はたくさんの異なるハードウェアで使われています。最も一般的な MCU とマトリックス構成をサポートしていますが、キーボードへ他のハードウェアを追加し制御するためのドライバーもいくつか用意されています。例えば、マウスやポインティングデバイス、分割キーボード用の IO エキスパンダ、Bluetooth モジュール、LCD、OLED、TFT 液晶などがあります。
+
+<!-- FIXME: This should talk about how drivers are integrated into QMK and how you can add your own driver.
+
+# Driver System Overview
+
+-->
+
+# 使用できるドライバー
+
+## ProMicro (AVR のみ)
+
+ProMicro のピンを AVR の名前ではなく、Arduino の名前で指定できます。この部分はより詳しく文書化される必要があります。もしこれを使用したい場合にコードを読んでも分からない場合、[issue を開く](https://github.com/qmk/qmk_firmware/issues/new)を通して助けることができるかもしれません。
+
+## SSD1306 OLED ドライバー
+
+SSD1306 ベースの OLED ディスプレイのサポート。詳しくは[OLED ドライバ](ja/feature_oled_driver.md)を参照して下さい。
+
+## uGFX
+
+QMK 内で uGFX を使用して、キャラクタ LCD やグラフィック LCD、LED アレイ、OLED ディスプレイ、TFT 液晶や他のディスプレイを制御できます。この部分はより詳しく文書化される必要があります。もしこれを使用したい場合にコードを読んでも分からない場合、[issue を開く](https://github.com/qmk/qmk_firmware/issues/new)を通して助けることができるかもしれません。
+
+## WS2812
+
+WS2811/WS2812{a,b,c} LED のサポート。 詳しくは [RGB ライト](ja/feature_rgblight.md)を参照して下さい。
+
+## IS31FL3731
+
+最大2つの LED ドライバーのサポート。各ドライバーは、I2C を使って個別に LED を制御する2つのチャーリープレクスマトリックスを実装しています。最大144個の単色 LED か32個の RGB LED を使用できます。ドライバーの設定方法の詳細は[RGB マトリックス](ja/feature_rgb_matrix.md)を参照して下さい。
+
+## IS31FL3733
+
+拡張の余地がある最大1つの LED ドライバーのサポート。各ドライバーは192個の単色 LED か64個の RGB LED を制御できます。ドライバーの設定方法の詳細は [RGB マトリックス](ja/feature_rgb_matrix.md)を参照して下さい。
+
+## 24xx シリーズ 外部 I2C EEPROM
+
+オンチップ EEPROM の代わりに使用する I2C ベースの外部 EEPROM のサポート。ドライバーの設定方法の詳細は [EEPROM ドライバー](ja/eeprom_driver.md)を参照して下さい。 

docs/ja/hardware_keyboard_guidelines.md

@@ -0,0 +1,155 @@
+# QMK キーボードガイドライン
+
+<!---
+  grep --no-filename "^[ ]*git diff" docs/ja/*.md | sh
+  original document: c9e3fa6f7:docs/hardware_keyboard_guidelines.md
+  git diff c9e3fa6f7 HEAD -- docs/hardware_keyboard_guidelines.md | cat
+-->
+
+QMK は開始以来、コミュニティにおけるキーボードの作成や保守に貢献しているあなたのような人たちのおかげで飛躍的に成長しました。私たちが成長するにつれて、うまくやるためのいくつかのパターンを発見しました。他の人たちがあなたの苦労の恩恵を受けやすくするため、それにあわせてもらえるようお願いします。
+
+## あなたのキーボード/プロジェクトの名前を決める
+
+キーボードの名前は全て小文字で、アルファベット、数字、アンダースコア(`_`)のみで構成されています。アンダースコア(`_`)で始めてはいけません。スラッシュ(`/`)はサブフォルダの区切り文字として使用されます。
+
+`test`、`keyboard`、`all` はmakeコマンド用に予約されており、キーボードまたはサブフォルダ名として使用することは出来ません。
+
+正しい例:
+
+* `412_64`
+* `chimera_ortho`
+* `clueboard/66/rev3`
+* `planck`
+* `v60_type_r`
+
+## サブフォルダ
+
+QMK では、まとめるためや同じキーボードのリビジョン間でコードを共有するためにサブフォルダを使用します。フォルダは最大4階層までネストできます。
+
+    qmk_firmware/keyboards/top_folder/sub_1/sub_2/sub_3/sub_4
+
+サブフォルダ内に `rules.mk` ファイルが存在するとコンパイル可能なキーボードとして見なされます。QMK Configurator から使用できるようになり、`make all` でテストされます。同じメーカーのキーボードをまとめるためにフォルダを使用している場合は `rules.mk` ファイルを置いてはいけません。
+
+例:
+
+Clueboard は、サブフォルダをまとめるためとキーボードのリビジョン管理の両方のために使用しています。
+
+* [`qmk_firmware`](https://github.com/qmk/qmk_firmware/tree/master)
+  * [`keyboards`](https://github.com/qmk/qmk_firmware/tree/master/keyboards)
+    * [`clueboard`](https://github.com/qmk/qmk_firmware/tree/master/keyboards/clueboard)  &larr; これはまとめるためのフォルダです。 `rules.mk` ファイルはありません。
+      * [`60`](https://github.com/qmk/qmk_firmware/tree/master/keyboards/clueboard/60)  &larr; これはコンパイルできるキーボードです。`rules.mk` が存在します。
+      * [`66`](https://github.com/qmk/qmk_firmware/tree/master/keyboards/clueboard/66) &larr; これもコンパイルできるキーボードです。 デフォルトのリビジョンとして `DEFAULT_FOLDER` に `rev3` を指定しています。
+        * [`rev1`](https://github.com/qmk/qmk_firmware/tree/master/keyboards/clueboard/66/rev1) &larr; コンパイル可能: `make clueboard/66/rev1`
+        * [`rev2`](https://github.com/qmk/qmk_firmware/tree/master/keyboards/clueboard/66/rev2) &larr; コンパイル可能: `make clueboard/66/rev2`
+        * [`rev3`](https://github.com/qmk/qmk_firmware/tree/master/keyboards/clueboard/66/rev3) &larr; コンパイル可能: `make clueboard/66/rev3` もしくは `make clueboard/66`
+
+## キーボードのフォルダ構成
+
+キーボードは `qmk_firmware/keyboards/` 内にあり、前のセクションで説明したようにフォルダ名はキーボードの名前にする必要があります。このフォルダ内にはいくつかのファイルがあります。
+
+* `readme.md`
+* `info.json`
+* `config.h`
+* `rules.mk`
+* `<keyboard_name>.c`
+* `<keyboard_name>.h`
+
+### `readme.md`
+
+全てのプロジェクトにはどのようなキーボードなのか、誰が設計したか、どこで入手できるかを説明する `readme.md` ファイルが必要です。もしあれば、メーカーの Web サイトなどの詳しい情報へのリンクも含める必要があります。[キーボード readme テンプレート](ja/documentation_templates.md#keyboard-readmemd-template)を参考にして下さい。
+
+### `info.json`
+
+このファイルは [QMK API](https://github.com/qmk/qmk_api) から使用されます。[QMK Configurator](https://config.qmk.fm/) が必要とするキーボードの情報が含まれています。ここでメタデータを設定することもできます。詳しくは [info.json 形式](ja/reference_info_json.md) を参照して下さい。
+
+### `config.h`
+
+全てのプロジェクトには、マトリックスサイズ、製品名、USB VID/PID、説明、その他の設定などが含まれた `config.h` ファイルが必要です。一般に、このファイルを使用して常に機能するキーボードの重要な情報やデフォルトを設定します。
+
+### `rules.mk`
+
+このファイルが存在するということは、フォルダがキーボードであり、`make` コマンドで使用できることを意味します。ここでキーボードのビルド環境を構築し、デフォルトの機能を設定します。
+
+### `<keyboard_name.c>`
+
+ここではキーボードのカスタマイズされたコードを記述します。通常、初期化してキーボードのハードウェアを制御するコードを記述します。キーボードが LED やスピーカー、その他付属ハードウェアのないキーマトリックスのみで構成されている場合は空にできます。
+
+通常、以下の関数がこのファイルで定義されます。
+
+* `void matrix_init_kb(void)`
+* `void matrix_scan_kb(void)`
+* `bool process_record_kb(uint16_t keycode, keyrecord_t *record)`
+* `void led_set_kb(uint8_t usb_led)`
+
+### `<keyboard_name.h>`
+
+このファイルはキーボードのマトリックスを定義するために使用されます。配列をキーボードの物理的なスイッチマトリックスに変換する C マクロを最低限1つ定義する必要があります。複数のレイアウトでキーボードを構築出来る場合は、追加のマクロを定義しなければいけません。
+
+レイアウトが1つしかない場合は、このマクロは `LAYOUT` とします。
+
+複数のレイアウトを定義する場合、物理的に構成することが出来なくとも、マトリックス上で全てのスイッチ位置をサポートする `LAYOUT_all` という名前の基本となるレイアウトが必要です。これは `default` キーマップで使用すべきマクロです。次に、他のレイアウトマクロを使用する `default_<layout>` といった追加のキーマップを用意します。これによって、他の人が定義されたレイアウトを使いやすくなります。
+
+レイアウトマクロの名前は全て小文字で、先頭の `LAYOUT` だけ大文字です。
+
+例として、ANSI と ISO をサポートする 60% PCB がある場合、以下のようにレイアウトとキーマップを定義出来ます。
+
+| レイアウト名 | キーマップ名 | 説明 |
+|-------------|-------------|-------------|
+| LAYOUT_all | default | ISO と ANSI のどちらもサポートしたレイアウト |
+| LAYOUT_ansi | default_ansi | ANSI レイアウト |
+| LAYOUT_iso | default_iso | ISO レイアウト |
+
+## 画像/ハードウェアのファイル
+
+リポジトリのサイズを小さく保つために、いくつかの例外を除いて、どの形式のバイナリファイルも受け入れないようになりました。外部の場所（<https://imgur.com>など）でホストして、`readme.md` でリンクすることをおすすめします。
+
+ハードウェアのファイル(プレートやケース、PCB など)は [qmk.fm リポジトリ](https://github.com/qmk/qmk.fm)に提供でき、[qmk.fm](http://qmk.fm) で利用可能になります。ダウンロード出来るファイルは `/<keyboard>/`（名前は上記と同じ形式）に保存され、`http://qmk.fm/<keyboard>/` で提供されます。ページは `/_pages/<keyboard>/` から生成されて、同じ場所で提供されます（ .mdファイルはJekyllを通して .htmlファイル変換されます）。`lets_split` ファイルを参照して下さい。
+
+## キーボードのデフォルト設定
+
+QMK が提供する機能の量を考えれば、新しいユーザーが混乱するのは当たり前です。キーボードのデフォルトファームウェアをまとめるなら、有効にする機能とオプションをハードウェアのサポートに必要な最低限のセットにすることをおすすめします。特定の機能に関するおすすめは以下の通りです。
+
+### ブートマジックとコマンド
+
+[ブートマジック](ja/feature_bootmagic.md) と[コマンド](ja/feature_command.md)は、ユーザーがキーボードを明白でない方法で制御出来るようにする2つの関連機能です。いずれかの機能を有効にする場合、この機能をどのように提供するかについて、よく考えることをおすすめします。この機能が必要なユーザーは、あなたのキーボードを最初のプログラムできるキーボードとして使用している初心者に影響を与えることなく、個人的なキーマップ内で有効に出来ることを覚えておきましょう。
+
+新規ユーザーが遭遇する最も多い問題は、キーボードを接続している間に間違えてブートマジックをトリガーしてしまうことです。キーボードの下を持っているとき、知らない間に Alt とスペースバーを押して、これらのキーが交換されてしまったことに気づきます。デフォルトではこの機能を無効にすることをおすすめしますが、有効にする場合は、キーボードを接続している間に押し間違えないキーへ `BOOTMAGIC_KEY_SALT` を設定することを検討して下さい。
+
+キーボードに2つの Shift キーがない場合は、`COMMAND_ENABLE = no` を指定していても `IS_COMMAND` が動作するデフォルトを設定しておくべきです。ユーザーがコマンドを有効化したときに使用するデフォルトが与えられます。
+
+## カスタムキーボードプログラミング
+
+[機能のカスタマイズ](ja/custom_quantum_functions.md)にあるようにキーボードのカスタム関数を定義できます。ユーザーも同様にその動作をカスタマイズしたいかもしれないということと、ユーザーにそれを可能にすることを忘れないで下さい。 `process_record_kb()`のようなカスタム関数を提供している場合、関数がその関数の `_user()` 版を呼び出すことを確認して下さい。また、その関数の`_user()` 版の戻り値を確認して、user が `true` を返した場合のみカスタムコードを実行しなければいけません。
+
+## 生産しない/手配線 プロジェクト
+
+プロトタイプや手配線によるものなど QMK を使用するどんなプロジェクトも受け入れますが、`/keyboards/` フォルダが乱雑になるのを防ぐために、`/keyboards/handwired/` を用意しています。いつかプロトタイプのプロジェクトが製品のプロジェクトになった時点でメインの `/keyboards/` フォルダへ移動します！
+
+## エラーとしての警告
+
+キーボードを開発するときは、全ての警告がエラーとして扱われることに注意して下さい。小さな警告が蓄積されて、将来大きなエラーを引き起こす可能性があります。(そして、警告を放っておくのは良くない習慣です)
+
+## 著作権表示
+
+別のプロジェクトを元にしてキーボードの設定をするものの同じコードを使用しない場合は、ファイル上部にある著作権表示を次の形式に従って自分の名前を表示するよう、更新して下さい。
+
+    Copyright 2017 Your Name <your@email.com>
+
+
+他の人のコードを修正し、その変更が些細な部分のみであれば、著作権表示の名前をそのままにしておかないといけません。ファイルに対して重要な作業を行った場合、以下のようにあなたの名前を追加します。
+
+    Copyright 2017 Their Name <original_author@example.com> Your Name <you@example.com>
+
+年はファイルが作成された最初の年にします。後年にそのファイルに対して作業が行われた場合、次のように2つ目の年を追加して反映することが出来ます。
+
+    Copyright 2015-2017 Your Name <you@example.com>
+
+## ライセンス
+
+QMK のコア部分は [GNU General Public License](https://www.gnu.org/licenses/licenses.en.html) でライセンスされます。AVR マイコン用のバイナリを提供する場合は、[GPLv2](https://www.gnu.org/licenses/old-licenses/gpl-2.0.html) か、[GPLv3](https://www.gnu.org/licenses/gpl.html) のどちらかから選択出来ます。ARM マイコン用のバイナリを提供する場合は、 [ChibiOS](http://www.chibios.org) の GPLv3 ライセンスに準拠するため、[GPL Version 3](https://www.gnu.org/licenses/gpl.html) を選択しなければいけません。
+
+[uGFX](https://ugfx.io) を使用している場合は、[uGFX License](https://ugfx.io/license.html) に準拠する必要があります。uGFX を利用したデバイスを販売するには個別に商用ライセンスを取得しなければいけません。
+
+## 技術的な詳細
+
+キーボードを QMK で動作させるための詳細は[ハードウェア](ja/hardware.md)を参照して下さい！

docs/ja/i2c_driver.md

@@ -1,38 +1,48 @@
-# I2C マスタドライバ
+# I2C マスタドライバ :id=i2c-master-driver
 
 <!---
   grep --no-filename "^[ ]*git diff" docs/ja/*.md | sh
-  original document: 85041ff05:docs/i2c_driver.md
-  git diff 85041ff05 HEAD -- docs/i2c_driver.md | cat
+  original document: 0.8.62:docs/i2c_driver.md
+  git diff 0.8.62 HEAD -- docs/i2c_driver.md | cat
 -->
 
 QMK で使われる I2C マスタドライバには、MCU 間のポータビリティを提供するための一連の関数が用意されています。
 
-## 使用できる関数
+## I2C アドレスについての重要なメモ :id=note-on-i2c-addresses
+
+このドライバが期待する全てのアドレスは、アドレスバイトの上位7ビットにプッシュする必要があります。最下位ビットの設定(読み込み/書き込みを示す)は、それぞれの関数によって行われます。データシートやインターネットで列挙されているほとんど全ての I2C アドレスは、下位7ビットを占める7ビットとして表され、1ビット左(より上位)にシフトする必要があります。これは、ビット単位のシフト演算子 `<< 1` を使用して簡単に実行できます。
+
+これは、呼び出しごとに以下の関数を実行するか、アドレスの定義で1度だけ実行するかどちらかで行うことができます。例えば、デバイスのアドレスが `0x18` の場合:
+
+`#define MY_I2C_ADDRESS (0x18 << 1)`
+
+I2C アドレスと他の技術詳細について、さらなる情報を得るためには https://www.robot-electronics.co.uk/i2c-tutorial を見てください。
+
+## 使用できる関数 :id=available-functions
 
 | 関数                                                                                                        | 説明                                                                                                                                                                                |
 |-------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | `void i2c_init(void);`                                                                                      | I2C ドライバを初期化します。他のあらゆるトランザクションを開始する前に、この関数を一度だけ呼ぶ必要があります。                                                                      |
-| `uint8_t i2c_start(uint8_t address, uint16_t timeout);`                                                     | I2C トランザクションを開始します。アドレスは方向ビットのない7ビットスレーブアドレスです。                                                                                           |
-| `uint8_t i2c_transmit(uint8_t address, uint8_t* data, uint16_t length, uint16_t timeout);`                  | I2C 経由でデータを送信します。アドレスは方向ビットのない7ビットスレーブアドレスです。トランザクションのステータスを返します。                                                       |
-| `uint8_t i2c_receive(uint8_t address, uint8_t* data, uint16_t length, uint16_t timeout);`                   | I2C 経由でデータを受信します。アドレスは方向ビットのない7ビットスレーブアドレスです。 `length` で指定した長さのバイト列を `data` に保存し、トランザクションのステータスを返します。 |
-| `uint8_t i2c_writeReg(uint8_t devaddr, uint8_t regaddr, uint8_t* data, uint16_t length, uint16_t timeout);` | `i2c_transmit` と同様ですが、 `regaddr` でスレーブのデータ書き込み先のレジスタを指定します。                                                                                    |
-| `uint8_t i2c_readReg(uint8_t devaddr, uint8_t regaddr, uint8_t* data, uint16_t length, uint16_t timeout);`  | `i2c_receive` と同様ですが、 `regaddr` でスレーブのデータ読み込み先のレジスタを指定します。                                                                                     |
-| `uint8_t i2c_stop(void);`                                                                                   | I2C トランザクションを終了します。                                                                                                                                                  |
+| `i2c_status_t i2c_start(uint8_t address, uint16_t timeout);`                                                     | I2C トランザクションを開始します。アドレスは方向ビットのない7ビットスレーブアドレスです。                                                                                           |
+| `i2c_status_t i2c_transmit(uint8_t address, uint8_t* data, uint16_t length, uint16_t timeout);`                  | I2C 経由でデータを送信します。アドレスは方向ビットのない7ビットスレーブアドレスです。トランザクションのステータスを返します。                                                       |
+| `i2c_status_t i2c_receive(uint8_t address, uint8_t* data, uint16_t length, uint16_t timeout);`                   | I2C 経由でデータを受信します。アドレスは方向ビットのない7ビットスレーブアドレスです。 `length` で指定した長さのバイト列を `data` に保存し、トランザクションのステータスを返します。 |
+| `i2c_status_t i2c_writeReg(uint8_t devaddr, uint8_t regaddr, uint8_t* data, uint16_t length, uint16_t timeout);` | `i2c_transmit` と同様ですが、 `regaddr` でスレーブのデータ書き込み先のレジスタを指定します。                                                                                    |
+| `i2c_status_t i2c_readReg(uint8_t devaddr, uint8_t regaddr, uint8_t* data, uint16_t length, uint16_t timeout);`  | `i2c_receive` と同様ですが、 `regaddr` でスレーブのデータ読み込み先のレジスタを指定します。                                                                                     |
+| `i2c_status_t i2c_stop(void);`                                                                                   | I2C トランザクションを終了します。                                                                                                                                                  |
 
-### 関数の戻り値
+### 関数の戻り値 :id=function-return
 
 `void i2c_init(void)` を除く上にあるすべての関数は、次の真理値表にある値を返します。
 
-| 戻り値 | 説明                         |
-|--------|------------------------------|
-| 0      | 処理が正常に実行されました。 |
-| -1     | 処理に失敗しました。         |
-| -2     | 処理がタイムアウトしました。 |
+|戻り値の定数        |値 |説明                        |
+|--------------------|---|----------------------------|
+|`I2C_STATUS_SUCCESS`|0  |処理が正常に実行されました。|
+|`I2C_STATUS_ERROR`  |-1 |処理に失敗しました。        |
+|`I2C_STATUS_TIMEOUT`|-2 |処理がタイムアウトしました。|
 
-## AVR
+## AVR :id=avr
 
-### 設定
+### 設定 :id=avr-configuration
 
 I2Cマスタドライバを設定するために、次の定義が使えます。
 
@@ -43,11 +53,11 @@ I2Cマスタドライバを設定するために、次の定義が使えます
 
 AVR は通常 I2C ピンとして使う GPIO が設定されているので、これ以上の設定は必要ありません。
 
-## ARM
+## ARM :id=arm
 
 ARM の場合は、内部に ChibiOS I2C HAL ドライバがあります。この節では STM32 MCU を使用していると仮定します。
 
-### 設定
+### 設定 :id=arm-configuration
 
 ARM MCU 用の設定はしばしば非常に複雑です。これは、多くの場合複数の I2C ドライバをさまざまなポートに対して割り当てられるためです。
 
@@ -82,7 +92,7 @@ ChibiOS I2C ドライバの設定項目は STM32 MCU の種類に依存します
     STM32F1xx, STM32F2xx, STM32F4xx, STM32L0xx, STM32L1xx では I2Cv1 が使われます。
     STM32F0xx, STM32F3xx, STM32F7xx, STM32L4xx では I2Cv2 が使われます。
 
-#### I2Cv1
+#### I2Cv1 :id=i2cv1
 
 STM32 MCU の I2Cv1 では、クロック周波数とデューティ比を次の変数で変更できます。詳しくは <https://www.playembedded.org/blog/stm32-i2c-chibios/#I2Cv1_configuration_structure> を参照してください。
 
@@ -92,7 +102,7 @@ STM32 MCU の I2Cv1 では、クロック周波数とデューティ比を次の
 | `I2C1_CLOCK_SPEED` | `100000`         |
 | `I2C1_DUTY_CYCLE`  | `STD_DUTY_CYCLE` |
 
-#### I2Cv2
+#### I2Cv2 :id=i2cv2
 
 STM32 MCU の I2Cv2 では、信号のタイミングパラメータを次の変数で変更できます。詳しくは <https://www.st.com/en/embedded-software/stsw-stm32126.html> を参照してください。
 
@@ -111,11 +121,11 @@ STM32 MCU では GPIO ピンを設定するとき、別の「代替機能」モ
 | `I2C1_SCL_PAL_MODE` | `4`    |
 | `I2C1_SDA_PAL_MODE` | `4`    |
 
-#### その他
+#### その他 :id=other
 
 `void i2c_init(void)` 関数は `weak` 属性が付いており、オーバーロードすることができます。この場合、上記で設定した変数は使用されません。可能な GPIO の設定については、 MCU のデータシートを参照してください。次に示すのは初期化関数の例です：
 
-```C
+```c
 void i2c_init(void)
 {
   setPinInput(B6); // Try releasing special pins for a short time

docs/ja/keymap.md

@@ -1,14 +1,14 @@
 # キーマップの概要
 
 <!---
-  original document: 7494490d6:docs/keymap.md
-  git diff 7494490d6 HEAD -- docs/keymap.md | cat
+  original document: 0.8.62:docs/keymap.md
+  git diff 0.8.62 HEAD -- docs/keymap.md | cat
 -->
 
 QMK のキーマップは C のソースファイルの中で定義されます。そのデータ構造は配列の配列です。外側はレイヤーを要素とする配列で、レイヤーはキーを要素とする配列。ほとんどのキーボードは `LAYOUT()` マクロを定義して、この配列の配列を作成しやすくしています。
 
 
-## キーマップとレイヤー
+## キーマップとレイヤー :id=keymap-and-layers
 QMKでは、**`const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS]`**は、**アクションコード**を保持している **16 bit** データの中でキーマップ情報の複数の**レイヤー**を保持します。最大で**32個のレイヤー**を定義することができます。
 
 普通のキー定義の場合、**アクションコード**の上位8ビットは全て0で、下位8ビットは**キーコード**としてキーによって生成された USB HID usage コードを保持します。
@@ -32,7 +32,8 @@ QMKでは、**`const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS]`**は
 
 TMK の歴史的経緯から、キーマップに保存されたアクションコードは、一部のドキュメントではキーコードと呼ばれる場合があります。
 
-### キーマップレイヤーステータス
+### キーマップレイヤーステータス :id=keymap-layer-status
+
 キーマップレイヤーの状態は、2つの32ビットパラメータによって決定されます。
 
 * **`default_layer_state`** は、常に有効で参照される基本キーマップレイヤー (0-31) を示します (デフォルトレイヤー)。

docs/keycodes.md

@@ -175,11 +175,11 @@ See also: [Basic Keycodes](keycodes_basic.md)
 |`KC_EXSEL`             |                              |ExSel                                          |
 |`KC_LCTRL`             |`KC_LCTL`                     |Left Control                                   |
 |`KC_LSHIFT`            |`KC_LSFT`                     |Left Shift                                     |
-|`KC_LALT`              |                              |Left Alt                                       |
+|`KC_LALT`              |`KC_LOPT`                     |Left Alt (Option)                              |
 |`KC_LGUI`              |`KC_LCMD`, `KC_LWIN`          |Left GUI (Windows/Command/Meta key)            |
 |`KC_RCTRL`             |`KC_RCTL`                     |Right Control                                  |
 |`KC_RSHIFT`            |`KC_RSFT`                     |Right Shift                                    |
-|`KC_RALT`              |`KC_ALGR`                     |Right Alt (AltGr)                              |
+|`KC_RALT`              |`KC_ROPT`, `KC_ALGR`          |Right Alt (Option/AltGr)                       |
 |`KC_RGUI`              |`KC_RCMD`, `KC_RWIN`          |Right GUI (Windows/Command/Meta key)           |
 |`KC_SYSTEM_POWER`      |`KC_PWR`                      |System Power Down                              |
 |`KC_SYSTEM_SLEEP`      |`KC_SLEP`                     |System Sleep                                   |
@@ -326,7 +326,7 @@ See also: [Key Lock](feature_key_lock.md)
 
 ## Layer Switching :id=layer-switching
 
-See also: [Layer Switching](feature_advanced_keycodes.md#switching-and-toggling-layers)
+See also: [Layer Switching](feature_layers.md#switching-and-toggling-layers)
 
 |Key             |Description                                                                       |
 |----------------|----------------------------------------------------------------------------------|
@@ -378,11 +378,11 @@ See also: [Modifier Keys](feature_advanced_keycodes.md#modifier-keys)
 |----------|-------------------------------|----------------------------------------------------|
 |`LCTL(kc)`|`C(kc)`                        |Hold Left Control and press `kc`                    |
 |`LSFT(kc)`|`S(kc)`                        |Hold Left Shift and press `kc`                      |
-|`LALT(kc)`|`A(kc)`                        |Hold Left Alt and press `kc`                        |
+|`LALT(kc)`|`A(kc)`, `LOPT(kc)`            |Hold Left Alt and press `kc`                        |
 |`LGUI(kc)`|`G(kc)`, `LCMD(kc)`, `LWIN(kc)`|Hold Left GUI and press `kc`                        |
 |`RCTL(kc)`|                               |Hold Right Control and press `kc`                   |
 |`RSFT(kc)`|                               |Hold Right Shift and press `kc`                     |
-|`RALT(kc)`|`ALGR(kc)`                     |Hold Right Alt and press `kc`                       |
+|`RALT(kc)`|`ROPT(kc)`, `ALGR(kc)`         |Hold Right Alt and press `kc`                       |
 |`RGUI(kc)`|`RCMD(kc)`, `LWIN(kc)`         |Hold Right GUI and press `kc`                       |
 |`SGUI(kc)`|`SCMD(kc)`, `SWIN(kc)`         |Hold Left Shift and GUI and press `kc`              |
 |`LCA(kc)` |                               |Hold Left Control and Alt and press `kc`            |
@@ -401,11 +401,11 @@ See also: [Mod-Tap](mod_tap.md)
 |`MT(mod, kc)`|                                                                 |`mod` when held, `kc` when tapped                      |
 |`LCTL_T(kc)` |`CTL_T(kc)`                                                      |Left Control when held, `kc` when tapped               |
 |`LSFT_T(kc)` |`SFT_T(kc)`                                                      |Left Shift when held, `kc` when tapped                 |
-|`LALT_T(kc)` |`ALT_T(kc)`                                                      |Left Alt when held, `kc` when tapped                   |
+|`LALT_T(kc)` |`LOPT_T(kc)`, `ALT_T(kc)`, `OPT_T(kc)`                           |Left Alt when held, `kc` when tapped                   |
 |`LGUI_T(kc)` |`LCMD_T(kc)`, `LWIN_T(kc)`, `GUI_T(kc)`, `CMD_T(kc)`, `WIN_T(kc)`|Left GUI when held, `kc` when tapped                   |
 |`RCTL_T(kc)` |                                                                 |Right Control when held, `kc` when tapped              |
 |`RSFT_T(kc)` |                                                                 |Right Shift when held, `kc` when tapped                |
-|`RALT_T(kc)` |`ALGR_T(kc)`                                                     |Right Alt when held, `kc` when tapped                  |
+|`RALT_T(kc)` |`ROPT_T(kc)`, `ALGR_T(kc)`                                       |Right Alt when held, `kc` when tapped                  |
 |`RGUI_T(kc)` |`RCMD_T(kc)`, `RWIN_T(kc)`                                       |Right GUI when held, `kc` when tapped                  |
 |`SGUI_T(kc)` |`SCMD_T(kc)`, `SWIN_T(kc)`                                       |Left Shift and GUI when held, `kc` when tapped         |
 |`LCA_T(kc)`  |                                                                 |Left Control and Alt when held, `kc` when tapped       |
@@ -543,7 +543,7 @@ See also: [Unicode Support](feature_unicode.md)
 |`XP(i, j)`            |         |Send Unicode code point at index `i`, or `j` if Shift/Caps is on|
 |`UNICODE_MODE_FORWARD`|`UC_MOD` |Cycle through selected input modes                              |
 |`UNICODE_MODE_REVERSE`|`UC_RMOD`|Cycle through selected input modes in reverse                   |
-|`UNICODE_MODE_OSX`    |`UC_M_OS`|Switch to macOS input                                           |
+|`UNICODE_MODE_MAC`    |`UC_M_MA`|Switch to macOS input                                           |
 |`UNICODE_MODE_LNX`    |`UC_M_LN`|Switch to Linux input                                           |
 |`UNICODE_MODE_WIN`    |`UC_M_WI`|Switch to Windows input                                         |
 |`UNICODE_MODE_BSD`    |`UC_M_BS`|Switch to BSD input (not implemented)                           |

docs/keycodes_basic.md

@@ -112,11 +112,11 @@ The basic set of keycodes are based on the [HID Keyboard/Keypad Usage Page (0x07
 |-----------|--------------------|------------------------------------|
 |`KC_LCTRL` |`KC_LCTL`           |Left Control                        |
 |`KC_LSHIFT`|`KC_LSFT`           |Left Shift                          |
-|`KC_LALT`  |                    |Left Alt                            |
+|`KC_LALT`  |`KC_LOPT`           |Left Alt (Option)                   |
 |`KC_LGUI`  |`KC_LCMD`, `KC_LWIN`|Left GUI (Windows/Command/Meta key) |
 |`KC_RCTRL` |`KC_RCTL`           |Right Control                       |
 |`KC_RSHIFT`|`KC_RSFT`           |Right Shift                         |
-|`KC_RALT`  |`KC_ALGR`           |Right Alt (AltGr)                   |
+|`KC_RALT`  |`KC_ROPT`, `KC_ALGR`|Right Alt (Option/AltGr)            |
 |`KC_RGUI`  |`KC_RCMD`, `KC_RWIN`|Right GUI (Windows/Command/Meta key)|
 
 ## International

docs/mod_tap.md

@@ -31,11 +31,11 @@ For convenience, QMK includes some Mod-Tap shortcuts to make common combinations
 |------------|-----------------------------------------------------------------|-------------------------------------------------------|
 |`LCTL_T(kc)`|`CTL_T(kc)`                                                      |Left Control when held, `kc` when tapped               |
 |`LSFT_T(kc)`|`SFT_T(kc)`                                                      |Left Shift when held, `kc` when tapped                 |
-|`LALT_T(kc)`|`ALT_T(kc)`                                                      |Left Alt when held, `kc` when tapped                   |
+|`LALT_T(kc)`|`LOPT_T(kc)`, `ALT_T(kc)`, `OPT_T(kc)`                           |Left Alt when held, `kc` when tapped                   |
 |`LGUI_T(kc)`|`LCMD_T(kc)`, `LWIN_T(kc)`, `GUI_T(kc)`, `CMD_T(kc)`, `WIN_T(kc)`|Left GUI when held, `kc` when tapped                   |
 |`RCTL_T(kc)`|                                                                 |Right Control when held, `kc` when tapped              |
 |`RSFT_T(kc)`|                                                                 |Right Shift when held, `kc` when tapped                |
-|`RALT_T(kc)`|`ALGR_T(kc)`                                                     |Right Alt when held, `kc` when tapped                  |
+|`RALT_T(kc)`|`ROPT_T(kc)`, `ALGR_T(kc)`                                       |Right Alt when held, `kc` when tapped                  |
 |`RGUI_T(kc)`|`RCMD_T(kc)`, `RWIN_T(kc)`                                       |Right GUI when held, `kc` when tapped                  |
 |`SGUI_T(kc)`|`SCMD_T(kc)`, `SWIN_T(kc)`                                       |Left Shift and GUI when held, `kc` when tapped         |
 |`LCA_T(kc)` |                                                                 |Left Control and Alt when held, `kc` when tapped       |

docs/newbs_getting_started.md

@@ -42,11 +42,15 @@ We've tried to make QMK as easy to set up as possible. You only have to prepare
 You will need to install MSYS2, Git, and the QMK CLI.
 
 * Follow the installation instructions on the [MSYS2 homepage](http://www.msys2.org).
-* Close any open MSYS2 terminals and open a new MSYS2 MinGW 64-bit terminal.
+* Close any open MSYS2 terminals and open a new MSYS2 MinGW 64-bit terminal. NOTE: This is **not** the same as the MSYS terminal that opens when installation is completed.
 
-After opening a new MSYS2 MinGW 64-bit terminal run these commands:
+After opening a new MSYS2 MinGW 64-bit terminal, make sure `pacman` is up to date with:
 
-    pacman -S git python3-pip
+    pacman -Syu
+
+You may be asked to close and reopen the window. Do this and keep running the above command until it says `there is nothing to do`. Then run the following:
+
+    pacman -S git mingw-w64-x86_64-toolchain mingw-w64-x86_64-python3-pip
     python3 -m pip install qmk
 
 ### macOS
@@ -64,7 +68,7 @@ You will need to install Git and Python. It's very likely that you already have
 
 * Debian / Ubuntu / Devuan: `apt-get install git python3 && python3 -m pip install qmk`
 * Fedora / Red Hat / CentOS: `yum install git python3 && python3 -m pip install qmk`
-* Arch: `pacman -S qmk`
+* Arch: `yay -S qmk` (or use any other AUR Helper)
 
 ## 3. Run QMK Setup :id=set-up-qmk
 
@@ -74,7 +78,7 @@ After installing QMK you can set it up with this command:
 
 In most situations you will want to answer Yes to all of the prompts.
 
-?> 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>` to clone your personal fork. If you don't know what that means you can safely ignore this message.
+?> 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/platformdev_chibios_earlyinit.md

@@ -0,0 +1,53 @@
+# Arm/ChibiOS Early Initialization :id=chibios-early-init
+
+This page describes a part of QMK that is a somewhat advanced concept, and is only relevant to keyboard designers.
+
+QMK uses ChibiOS as the underlying layer to support a multitude of Arm-based devices. Each ChibiOS-supported keyboard has a low-level board definition which is responsible for initializing hardware peripherals such as the clocks, and GPIOs.
+
+Older QMK revisions required duplication of these board definitions inside your keyboard's directory in order to override such early initialization points; this is now abstracted into the following APIs, and allows usage of the board definitions supplied with ChibiOS itself. Check `<qmk_firmware>/lib/chibios/os/hal/boards` for the list of official definitions. If your keyboard needs extra initialization at a very early stage, consider providing keyboard-level overrides of the following APIs:
+
+## `early_hardware_init_pre()` :id=early-hardware-init-pre
+
+The function `early_hardware_init_pre` is the earliest possible code that can be executed by a keyboard firmware. This is intended as a replacement for the ChibiOS board definition's `__early_init` function, and is the equivalent of executing at the start of the function.
+
+This is executed before RAM gets cleared, and before clocks or GPIOs are configured; any delays or preparation using GPIOs is not likely to work at this point. After executing this function, RAM on the MCU may be zero'ed. Assigning values to variables during execution of this function may be overwritten.
+
+As such, if you wish to override this API consider limiting use to writing to low-level registers. The default implementation of this function can be configured to jump to bootloader if a `RESET` key was pressed, by ensuring `#define EARLY_INIT_PERFORM_BOOTLOADER_JUMP TRUE` is in the keyboard's `config.h` file.
+
+To implement your own version of this function, in your keyboard's source files:
+
+```c
+void early_hardware_init_pre(void) {
+    // do things with registers
+}
+```
+
+## `early_hardware_init_post()` :id=early-hardware-init-post
+
+The function `early_hardware_init_post` is the next earliest possible code that can be executed by a keyboard firmware. This is executed after RAM has been cleared, and clocks and GPIOs are configured. This is intended as a replacement for the ChibiOS board definition's `__early_init` function, and is the equivalent of executing at the end of the function.
+
+Much like `early_hardware_init_pre`, ChibiOS has not yet been initialized either, so the same restrictions on delays and timing apply.
+
+If you wish to override this API, consider limiting functionality to register writes, variable initialization, and GPIO toggling. The default implementation of this function is to do nothing.
+
+To implement your own version of this function, in your keyboard's source files:
+
+```c
+void early_hardware_init_post(void) {
+    // toggle GPIO pins and write to variables
+}
+```
+
+## `board_init()` :id=board-init
+
+The function `board_init` is executed directly after the ChibiOS initialization routines have completed. At this stage, all normal low-level functionality should be available for use (including timers and delays), with the restriction that USB is not yet connected. This is intended as a replacement for the ChibiOS board definition's `boardInit` function.
+
+The default implementation of this function is to do nothing.
+
+To implement your own version of this function, in your keyboard's source files:
+
+```c
+void board_init(void) {
+    // initialize anything that requires ChibiOS
+}
+```

docs/proton_c_conversion.md

@@ -1,5 +1,9 @@
 # Converting a board to use the Proton C
 
+Since the Proton C is a drop-in replacement for a Pro Micro we've made it easy to use. This page documents a handy automated process for converting keyboards, as well as documenting the manual process if you'd like to make use of Proton C features that aren't available on Pro Micros.
+
+## Automatic Conversion
+
 If a board currently supported in QMK uses a Pro Micro (or compatible board) and you want to use the Proton C, you can generate the firmware by appending `CONVERT_TO_PROTON_C=yes` (or `CTPC=yes`) to your make argument, like this:
 
     make 40percentclub/mf68:default CTPC=yes
@@ -8,13 +12,15 @@ You can add the same argument to your keymap's `rules.mk`, which will accomplish
 
 This exposes the `CONVERT_TO_PROTON_C` flag that you can use in your code with `#ifdef`s, like this:
 
-    #ifdef CONVERT_TO_PROTON_C
-        // Proton C code
-    #else
-        // Pro Micro code
-    #endif
+```c
+#ifdef CONVERT_TO_PROTON_C
+    // Proton C code
+#else
+    // Pro Micro code
+#endif
+```
 
-Before being able to compile, you may get some errors about `PORTB/DDRB`, etc not being defined, so you'll need to convert the keyboard's code to use the [GPIO Controls](internals_gpio_control.md) that will work for both ARM and AVR. This shouldn't affect the AVR builds at all.
+If you get errors about `PORTB/DDRB`, etc not being defined, so you'll need to convert the keyboard's code to use the [GPIO Controls](internals_gpio_control.md) that will work for both ARM and AVR. This shouldn't affect the AVR builds at all.
 
 The Proton C only has one on-board LED (C13), and by default, the TXLED (D5) is mapped to it. If you want the RXLED (B0) mapped to it instead, add this like to your `config.h`:
 
@@ -31,3 +37,54 @@ These are defaults based on what has been implemented for ARM boards.
 | [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                                                                                       |
+
+## Manual Conversion
+
+To use the Proton C natively, without having to specify `CTPC=yes`, you need to change the `MCU` line in `rules.mk`:
+
+```
+MCU = STM32F303
+```
+
+Remove these variables if they exist:
+
+* `BOOTLOADER`
+* `EXTRA_FLAGS`
+
+Finally convert all pin assignments in `config.h` to the stm32 equivalents.
+
+| Pro Micro Left | Proton C Left | | Proton C Right | Pro Micro Right |
+|-----------|----------|-|----------|-----------|
+| `D3` | `A9` | | 5v | RAW (5v) |
+| `D2` | `A10` | | GND | GND |
+| GND | GND | | FLASH | RESET |
+| GND | GND | | 3.3v | VCC <sup>1</sup> |
+| `D1` | `B7` | | `A2` | `F4` |
+| `D0` | `B6` | | `A1` | `F5` |
+| `D4` | `B5` | | `A0` | `F6` |
+| `C6` | `B4` | | `B8` | `F7` |
+| `D7` | `B3` | | `B13` | `B1` |
+| `E6` | `B2` | | `B14` | `B3` |
+| `B4` | `B1` | | `B15` | `B2` |
+| `B5` | `B0` | | `B9` | `B6` |
+| `B0` (RX LED) | `C13` <sup>2</sup> | | `C13` <sup>2</sup> | `D5` (TX LED) |
+
+You can also make use of several new pins on the extended portion of the Proton C:
+
+| Left | | Right | 
+|------|-|-------|
+| `A4`<sup>3</sup> | | `B10` |
+| `A5`<sup>4</sup> | | `B11` |
+| `A6` | | `B12` |
+| `A7` | | `A14`<sup>5</sup> (SWCLK) |
+| `A8` | | `A13`<sup>5</sup> (SWDIO) |
+| `A15` | | RESET<sup>6</sup> |
+
+Notes:
+
+1. On a Pro Micro VCC can be 3.3v or 5v.
+2. A Proton C only has one onboard LED, not two like a Pro Micro. The Pro Micro has an RX LED on `D5` and a TX LED on `B0`.
+3. `A4` is shared with the speaker.
+4. `A5` is shared with the speaker.
+5. `A13` and `A14` are used for hardware debugging (SWD). You can also use them for GPIO, but should use them last.
+6. Short RESET to 3.3v (pull high) to reboot the MCU. This does not enter bootloader mode like a Pro Micro, it only resets the MCU.

docs/pt-br/_summary.md

@@ -98,6 +98,7 @@
   * [ISP Flashing Guide](pt-br/isp_flashing_guide.md)
   * [ARM Debugging Guide](pt-br/arm_debugging.md)
   * [I2C Driver](pt-br/i2c_driver.md)
+  * [SPI Driver](pt-br/spi_driver.md)
   * [GPIO Controls](pt-br/internals_gpio_control.md)
   * [Proton C Conversion](pt-br/proton_c_conversion.md)
 

docs/ref_functions.md

@@ -8,7 +8,7 @@ There are actually separate functions that you can use there, depending on what
 
 ### `update_tri_layer(x, y, z)`
 
-The first is the `update_tri_layer(x, y, z)` function.   This function check to see if layers `x` and `y` are both on. If they are both on, then it runs on layer `z`.  Otherwise, if both `x` and `y` are not both on (either only one is, or neither is), then it runs off layer `z`.
+The first is the `update_tri_layer(x, y, z)` function.   This function check to see if layers `x` and `y` are both on. If they are both on, then it turns on layer `z`.  Otherwise, if both `x` and `y` are not both on (either only one is, or neither is), then it turns off layer `z`.
 
 This function is useful if you want to create specific keys that have this functionality, but other layer keycodes won't do this.
 
@@ -43,7 +43,7 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) {
 ```
 
 ### `update_tri_layer_state(state, x, y, z)`
-The other function is `update_tri_layer_state(state, x, y, z)`.  This function is meant to be called from they [`layer_state_set_*` functions](custom_quantum_functions.md#layer-change-code).  This means that any time that you use a keycode to change the layer, this will be checked.  So you could use `LT(layer, kc)` to change the layer and it will trigger the same layer check.
+The other function is `update_tri_layer_state(state, x, y, z)`.  This function is meant to be called from the [`layer_state_set_*` functions](custom_quantum_functions.md#layer-change-code).  This means that any time that you use a keycode to change the layer, this will be checked.  So you could use `LT(layer, kc)` to change the layer and it will trigger the same layer check.
 
 The caveat to this method is that you cannot access the `z` layer without having `x` and `y` layers on, since if you try to activate just layer `z`, it will run this code and turn off layer `z` before you could use it.
 

docs/reference_glossary.md

@@ -46,9 +46,6 @@ An IDE that is popular with many C developers.
 ## Firmware
 The software that controls your MCU.
 
-## FLIP
-Software provided by Atmel for flashing AVR devices. We generally recommend [QMK Flasher](https://github.com/qmk/qmk_flasher) instead, but for some advanced use cases FLIP is required.
-
 ## git
 Versioning software used at the command line
 

docs/ru-ru/_summary.md

@@ -99,6 +99,7 @@
   * [ISP Flashing Guide](ru-ru/isp_flashing_guide.md)
   * [ARM Debugging Guide](ru-ru/arm_debugging.md)
   * [I2C Driver](ru-ru/i2c_driver.md)
+  * [SPI Driver](ru-ru/spi_driver.md)
   * [WS2812 Driver](ru-ru/ws2812_driver.md)
   * [GPIO Controls](ru-ru/internals_gpio_control.md)
   * [Proton C Conversion](ru-ru/proton_c_conversion.md)

docs/spi_driver.md

@@ -0,0 +1,121 @@
+# SPI Master Driver
+
+The SPI Master drivers used in QMK have a set of common functions to allow portability between MCUs.
+
+## AVR Configuration
+
+No special setup is required - just connect the `SS`, `SCK`, `MOSI` and `MISO` pins of your SPI devices to the matching pins on the MCU:
+
+|MCU            |`SS`|`SCK`|`MOSI`|`MISO`|
+|---------------|----|-----|------|------|
+|ATMega16/32U2/4|`B0`|`B1` |`B2`  |`B3`  |
+|AT90USB64/128  |`B0`|`B1` |`B2`  |`B3`  |
+|ATmega32A      |`B4`|`B7` |`B5`  |`B6`  |
+|ATmega328P     |`B2`|`B5` |`B3`  |`B4`  |
+
+You may use more than one slave select pin, not just the `SS` pin. This is useful when you have multiple devices connected and need to communicate with them individually.
+`SPI_SS_PIN` can be passed to `spi_start()` to refer to `SS`.
+
+## ChibiOS/ARM Configuration
+
+ARM support for this driver is not ready yet. Check back later!
+
+## Functions
+
+### `void spi_init(void)`
+
+Initialize the SPI driver. This function must be called only once, before any of the below functions can be called.
+
+---
+
+### `bool spi_start(pin_t slavePin, bool lsbFirst, uint8_t mode, uint16_t divisor)`
+
+Start an SPI transaction.
+
+#### Arguments
+
+ - `pin_t slavePin`  
+   The QMK pin to assert as the slave select pin, eg. `B4`.
+ - `bool lsbFirst`  
+   Determines the endianness of the transmission. If `true`, the least significant bit of each byte is sent first.
+ - `uint8_t mode`  
+   The SPI mode to use:
+
+   |Mode|Clock Polarity      |Clock Phase            |
+   |----|--------------------|-----------------------|
+   |`0` |Leading edge rising |Sample on leading edge |
+   |`1` |Leading edge rising |Sample on trailing edge|
+   |`2` |Leading edge falling|Sample on leading edge |
+   |`3` |Leading edge falling|Sample on trailing edge|
+
+ - `uint16_t divisor`  
+   The SPI clock divisor, will be rounded up to the nearest power of two. This number can be calculated by dividing the MCU's clock speed by the desired SPI clock speed. For example, an MCU running at 8 MHz wanting to talk to an SPI device at 4 MHz would set the divisor to `2`.
+
+#### Return Value
+
+`false` if the supplied parameters are invalid or the SPI peripheral is already in use, or `true`.
+
+---
+
+### `spi_status_t spi_write(uint8_t data)`
+
+Write a byte to the selected SPI device.
+
+#### Arguments
+
+ - `uint8_t data`  
+   The byte to write.
+
+#### Return Value
+
+`SPI_STATUS_TIMEOUT` if the timeout period elapses, or `SPI_STATUS_SUCCESS`.
+
+---
+
+### `spi_status_t spi_read(void)`
+
+Read a byte from the selected SPI device.
+
+#### Return Value
+
+`SPI_STATUS_TIMEOUT` if the timeout period elapses, or the byte read from the device.
+
+---
+
+### `spi_status_t spi_transmit(const uint8_t *data, uint16_t length)`
+
+Send multiple bytes to the selected SPI device.
+
+#### Arguments
+
+ - `const uint8_t *data`  
+   A pointer to the data to write from.
+ - `uint16_t length`  
+   The number of bytes to write. Take care not to overrun the length of `data`.
+
+#### Return Value
+
+`SPI_STATUS_TIMEOUT` if the timeout period elapses, `SPI_STATUS_SUCCESS` on success, or `SPI_STATUS_ERROR` otherwise.
+
+---
+
+### `spi_status_t spi_receive(uint8_t *data, uint16_t length)`
+
+Receive multiple bytes from the selected SPI device.
+
+#### Arguments
+
+ - `uint8_t *data`  
+   A pointer to the buffer to read into.
+ - `uint16_t length`  
+   The number of bytes to read. Take care not to overrun the length of `data`.
+
+#### Return Value
+
+`SPI_STATUS_TIMEOUT` if the internal transmission timeout period elapses, `SPI_STATUS_SUCCESS` on success, or `SPI_STATUS_ERROR` otherwise.
+
+---
+
+### `void spi_stop(void)`
+
+End the current SPI transaction. This will deassert the slave select pin and reset the endianness, mode and divisor configured by `spi_start()`.

docs/understanding_qmk.md

@@ -162,6 +162,15 @@ The `process_record()` function itself is deceptively simple, but hidden within
 
 At any step during this chain of events a function (such as `process_record_kb()`) can `return false` to halt all further processing.
 
+After this is called, `post_process_record()` is called, which can be used to handle additional cleanup that needs to be run after the keycode is normally handled. 
+
+* [`void post_process_record(keyrecord_t *record)`]()
+  * [`void post_process_record_quantum(keyrecord_t *record)`]()
+    * [Map this record to a keycode]()
+    * [`void post_process_clicky(uint16_t keycode, keyrecord_t *record)`]()
+    * [`void post_process_record_kb(uint16_t keycode, keyrecord_t *record)`]()
+      * [`void post_process_record_user(uint16_t keycode, keyrecord_t *record)`]()
+      
 <!--
 #### Mouse Handling
 

docs/zh-cn/_summary.md

@@ -104,6 +104,7 @@
   * [ARM调试指南](zh-cn/arm_debugging.md)
   * [ADC设备](zh-cn/adc_driver.md)
   * [I2C设备](zh-cn/i2c_driver.md)
+  * [SPI设备](zh-cn/spi_driver.md)
   * [WS2812设备](zh-cn/ws2812_driver.md)
   * [EEPROM设备](zh-cn/eeprom_driver.md)
   * [GPIO控制](zh-cn/internals_gpio_control.md)

docs/zh-cn/faq_debug.md

@@ -139,10 +139,3 @@ https://geekhack.org/index.php?topic=14290.msg1884034#msg1884034
 
 https://github.com/tmk/tmk_keyboard/issues/266
 https://geekhack.org/index.php?topic=41989.msg1967778#msg1967778
-
-
-
-## FLIP 不工作
-### `AtLibUsbDfu.dll` 未找到
-从设备管理器中删除当前驱动程序并在设备管理器重新安装一个FLIP提供的程序。
-http://imgur.com/a/bnwzy

docs/zh-cn/reference_glossary.md

@@ -46,9 +46,6 @@ Français (法国)标准键盘布局。用键盘的前六个字母命名。
 ## Firmware(固件)
 用来控制单片机的软件。
 
-## FLIP
-爱特梅尔(Atmel)提供的AVR器件刷写软件。我们一般推荐 [QMK刷写工具](https://github.com/qmk/qmk_flasher)，但是对于一些高级用例，需要FLIP。
-
 ## git
 命令行版本控制软件
 

drivers/arm/analog.c

@@ -1,207 +0,0 @@
-/* Copyright 2019 Drew Mills
- *
- * This program is free software: you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation, either version 2 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program.  If not, see <http://www.gnu.org/licenses/>.
- */
-
-#include "analog.h"
-#include "quantum.h"
-
-/* User configurable ADC options */
-#ifndef ADC_CIRCULAR_BUFFER
-#    define ADC_CIRCULAR_BUFFER FALSE
-#endif
-
-#ifndef ADC_NUM_CHANNELS
-#    define ADC_NUM_CHANNELS 1
-#elif ADC_NUM_CHANNELS != 1
-#    error "The ARM ADC implementation currently only supports reading one channel at a time."
-#endif
-
-#ifndef ADC_BUFFER_DEPTH
-#    define ADC_BUFFER_DEPTH 2
-#endif
-
-// For more sampling rate options, look at hal_adc_lld.h in ChibiOS
-#ifndef ADC_SAMPLING_RATE
-#    define ADC_SAMPLING_RATE ADC_SMPR_SMP_1P5
-#endif
-
-// Options are 12, 10, 8, and 6 bit.
-#ifndef ADC_RESOLUTION
-#    define ADC_RESOLUTION ADC_CFGR1_RES_12BIT
-#endif
-
-static ADCConfig   adcCfg = {};
-static adcsample_t sampleBuffer[ADC_NUM_CHANNELS * ADC_BUFFER_DEPTH];
-
-// Initialize to max number of ADCs, set to empty object to initialize all to false.
-#if defined(STM32F0XX)
-static bool adcInitialized[1] = {};
-#elif defined(STM32F3XX)
-static bool adcInitialized[4] = {};
-#else
-#    error "adcInitialized has not been implemented for this ARM microcontroller."
-#endif
-
-static ADCConversionGroup adcConversionGroup = {
-    ADC_CIRCULAR_BUFFER,
-    (uint16_t)(ADC_NUM_CHANNELS),
-    NULL,  // No end callback
-    NULL,  // No error callback
-#if defined(STM32F0XX)
-    ADC_CFGR1_CONT | ADC_RESOLUTION,
-    ADC_TR(0, 0).ADC_SAMPLING_RATE,
-    NULL,  // Doesn't specify a default channel
-#elif defined(STM32F3XX)
-    ADC_CFGR_CONT | ADC_RESOLUTION,
-    ADC_TR(0, 4095),
-    {
-        ADC_SAMPLING_RATE,
-        ADC_SAMPLING_RATE,
-    },
-    {
-        0,  // Doesn't specify a default channel
-        0,
-        0,
-        0,
-    },
-#endif
-};
-
-static inline ADCDriver* intToADCDriver(uint8_t adcInt) {
-    ADCDriver* target;
-
-    switch (adcInt) {
-        // clang-format off
-#if STM32_ADC_USE_ADC1
-        case 0: target = &ADCD1; break;
-#endif
-#if STM32_ADC_USE_ADC2
-        case 1: target = &ADCD2; break;
-#endif
-#if STM32_ADC_USE_ADC3
-        case 2: target = &ADCD3; break;
-#endif
-#if STM32_ADC_USE_ADC4
-        case 3: target = &ADCD4; break;
-#endif
-        default: target = NULL; break;
-            // clang-format on
-    }
-
-    return target;
-}
-
-static inline void manageAdcInitializationDriver(uint8_t adc, ADCDriver* adcDriver) {
-    if (!adcInitialized[adc]) {
-        adcStart(adcDriver, &adcCfg);
-        adcInitialized[adc] = true;
-    }
-}
-
-static inline void manageAdcInitialization(uint8_t adc) { manageAdcInitializationDriver(adc, intToADCDriver(adc)); }
-
-pin_and_adc pinToMux(pin_t pin) {
-    switch (pin) {
-        // clang-format off
-#if defined(STM32F0XX)
-        case A0:  return (pin_and_adc){ ADC_CHANNEL_IN0,  0 };
-        case A1:  return (pin_and_adc){ ADC_CHANNEL_IN1,  0 };
-        case A2:  return (pin_and_adc){ ADC_CHANNEL_IN2,  0 };
-        case A3:  return (pin_and_adc){ ADC_CHANNEL_IN3,  0 };
-        case A4:  return (pin_and_adc){ ADC_CHANNEL_IN4,  0 };
-        case A5:  return (pin_and_adc){ ADC_CHANNEL_IN5,  0 };
-        case A6:  return (pin_and_adc){ ADC_CHANNEL_IN6,  0 };
-        case A7:  return (pin_and_adc){ ADC_CHANNEL_IN7,  0 };
-        case B0:  return (pin_and_adc){ ADC_CHANNEL_IN8,  0 };
-        case B1:  return (pin_and_adc){ ADC_CHANNEL_IN9,  0 };
-        case C0:  return (pin_and_adc){ ADC_CHANNEL_IN10, 0 };
-        case C1:  return (pin_and_adc){ ADC_CHANNEL_IN11, 0 };
-        case C2:  return (pin_and_adc){ ADC_CHANNEL_IN12, 0 };
-        case C3:  return (pin_and_adc){ ADC_CHANNEL_IN13, 0 };
-        case C4:  return (pin_and_adc){ ADC_CHANNEL_IN14, 0 };
-        case C5:  return (pin_and_adc){ ADC_CHANNEL_IN15, 0 };
-#elif defined(STM32F3XX)
-        case A0:  return (pin_and_adc){ ADC_CHANNEL_IN1,  0 };
-        case A1:  return (pin_and_adc){ ADC_CHANNEL_IN2,  0 };
-        case A2:  return (pin_and_adc){ ADC_CHANNEL_IN3,  0 };
-        case A3:  return (pin_and_adc){ ADC_CHANNEL_IN4,  0 };
-        case A4:  return (pin_and_adc){ ADC_CHANNEL_IN1,  1 };
-        case A5:  return (pin_and_adc){ ADC_CHANNEL_IN2,  1 };
-        case A6:  return (pin_and_adc){ ADC_CHANNEL_IN3,  1 };
-        case A7:  return (pin_and_adc){ ADC_CHANNEL_IN4,  1 };
-        case B0:  return (pin_and_adc){ ADC_CHANNEL_IN12, 2 };
-        case B1:  return (pin_and_adc){ ADC_CHANNEL_IN1,  2 };
-        case B2:  return (pin_and_adc){ ADC_CHANNEL_IN12, 1 };
-        case B12: return (pin_and_adc){ ADC_CHANNEL_IN2,  3 };
-        case B13: return (pin_and_adc){ ADC_CHANNEL_IN3,  3 };
-        case B14: return (pin_and_adc){ ADC_CHANNEL_IN4,  3 };
-        case B15: return (pin_and_adc){ ADC_CHANNEL_IN5,  3 };
-        case C0:  return (pin_and_adc){ ADC_CHANNEL_IN6,  0 }; // Can also be ADC2
-        case C1:  return (pin_and_adc){ ADC_CHANNEL_IN7,  0 }; // Can also be ADC2
-        case C2:  return (pin_and_adc){ ADC_CHANNEL_IN8,  0 }; // Can also be ADC2
-        case C3:  return (pin_and_adc){ ADC_CHANNEL_IN9,  0 }; // Can also be ADC2
-        case C4:  return (pin_and_adc){ ADC_CHANNEL_IN5,  1 };
-        case C5:  return (pin_and_adc){ ADC_CHANNEL_IN11, 1 };
-        case D8:  return (pin_and_adc){ ADC_CHANNEL_IN12, 3 };
-        case D9:  return (pin_and_adc){ ADC_CHANNEL_IN13, 3 };
-        case D10: return (pin_and_adc){ ADC_CHANNEL_IN7,  2 }; // Can also be ADC4
-        case D11: return (pin_and_adc){ ADC_CHANNEL_IN8,  2 }; // Can also be ADC4
-        case D12: return (pin_and_adc){ ADC_CHANNEL_IN9,  2 }; // Can also be ADC4
-        case D13: return (pin_and_adc){ ADC_CHANNEL_IN10, 2 }; // Can also be ADC4
-        case D14: return (pin_and_adc){ ADC_CHANNEL_IN11, 2 }; // Can also be ADC4
-        case E7:  return (pin_and_adc){ ADC_CHANNEL_IN13, 2 };
-        case E8:  return (pin_and_adc){ ADC_CHANNEL_IN6,  2 }; // Can also be ADC4
-        case E9:  return (pin_and_adc){ ADC_CHANNEL_IN2,  2 };
-        case E10: return (pin_and_adc){ ADC_CHANNEL_IN14, 2 };
-        case E11: return (pin_and_adc){ ADC_CHANNEL_IN15, 2 };
-        case E12: return (pin_and_adc){ ADC_CHANNEL_IN16, 2 };
-        case E13: return (pin_and_adc){ ADC_CHANNEL_IN3,  2 };
-        case E14: return (pin_and_adc){ ADC_CHANNEL_IN1,  3 };
-        case E15: return (pin_and_adc){ ADC_CHANNEL_IN2,  3 };
-        case F2:  return (pin_and_adc){ ADC_CHANNEL_IN10, 0 }; // Can also be ADC2
-        case F4:  return (pin_and_adc){ ADC_CHANNEL_IN5,  0 };
-#else
-#error "An ADC pin-to-mux configuration has not been specified for this microcontroller."
-#endif
-        default:  return (pin_and_adc){ 0, 0 };
-            // clang-format on
-    }
-}
-
-adcsample_t analogReadPin(pin_t pin) { return adc_read(pinToMux(pin)); }
-
-adcsample_t analogReadPinAdc(pin_t pin, uint8_t adc) {
-    pin_and_adc target = pinToMux(pin);
-    target.adc         = adc;
-    return adc_read(target);
-}
-
-adcsample_t adc_read(pin_and_adc mux) {
-#if defined(STM32F0XX)
-    adcConversionGroup.sqr = ADC_CHSELR_CHSEL1;
-#elif defined(STM32F3XX)
-    adcConversionGroup.sqr[0] = ADC_SQR1_SQ1_N(mux.pin);
-#else
-#    error "adc_read has not been updated to support this ARM microcontroller."
-#endif
-
-    ADCDriver* targetDriver = intToADCDriver(mux.adc);
-    manageAdcInitializationDriver(mux.adc, targetDriver);
-
-    adcConvert(targetDriver, &adcConversionGroup, &sampleBuffer[0], ADC_BUFFER_DEPTH);
-    adcsample_t* result = sampleBuffer;
-
-    return *result;
-}

drivers/arm/analog.h

@@ -1,57 +0,0 @@
-/* Copyright 2019 Drew Mills
- *
- * This program is free software: you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation, either version 2 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program.  If not, see <http://www.gnu.org/licenses/>.
- */
-
-#pragma once
-
-#include "quantum.h"
-#include "ch.h"
-#include <hal.h>
-
-#if !defined(STM32F0XX) && !defined(STM32F3XX)
-#    error "Only STM23F0 and STM32F3 devices have ADC support in QMK at this time."
-#endif
-
-#if !HAL_USE_ADC
-#    error "You need to set HAL_USE_ADC to TRUE in your halconf.h to use the ADC."
-#endif
-
-#if !STM32_ADC_USE_ADC1 && !STM32_ADC_USE_ADC2 && !STM32_ADC_USE_ADC3 && !STM32_ADC_USE_ADC4
-#    error "You need to set one of the 'STM32_ADC_USE_ADCx' settings to TRUE in your mcuconf.h to use the ADC."
-#endif
-
-#if STM32_ADC_DUAL_MODE
-#    error "STM32 ADC Dual Mode is not supported at this time."
-#endif
-
-#if STM32_ADCV3_OVERSAMPLING
-#    error "STM32 ADCV3 Oversampling is not supported at this time."
-#endif
-
-typedef struct {
-    pin_t   pin;
-    uint8_t adc;
-} pin_and_adc;
-#define PIN_AND_ADC(p, a) \
-    (pin_and_adc) { p, a }
-
-// analogReference has been left un-defined for ARM devices.
-// void analogReference(uint8_t mode);
-
-adcsample_t analogReadPin(pin_t pin);
-adcsample_t analogReadPinAdc(pin_t pin, uint8_t adc);
-pin_and_adc pinToMux(pin_t pin);
-
-adcsample_t adc_read(pin_and_adc mux);

drivers/avr/spi_master.c

@@ -0,0 +1,176 @@
+/*  Copyright 2020
+ *
+ *  This program is free software: you can redistribute it and/or modify
+ *  it under the terms of the GNU General Public License as published by
+ *  the Free Software Foundation, either version 3 of the License, or
+ *  (at your option) any later version.
+ *
+ *  This program is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *  GNU General Public License for more details.
+ *
+ *  You should have received a copy of the GNU General Public License
+ *  along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+#include <avr/io.h>
+
+#include "spi_master.h"
+#include "quantum.h"
+#include "timer.h"
+
+#if defined(__AVR_ATmega16U2__) || defined(__AVR_ATmega32U2__) || defined(__AVR_ATmega16U4__) || defined(__AVR_ATmega32U4__) || defined(__AVR_AT90USB646__) || defined(__AVR_AT90USB647__) || defined(__AVR_AT90USB1286__) || defined(__AVR_AT90USB1287__)
+#    define SPI_SCK_PIN B1
+#    define SPI_MOSI_PIN B2
+#    define SPI_MISO_PIN B3
+#elif defined(__AVR_ATmega32A__)
+#    define SPI_SCK_PIN B7
+#    define SPI_MOSI_PIN B5
+#    define SPI_MISO_PIN B6
+#elif defined(__AVR_ATmega328P__)
+#    define SPI_SCK_PIN B5
+#    define SPI_MOSI_PIN B3
+#    define SPI_MISO_PIN B4
+#endif
+
+#ifndef SPI_TIMEOUT
+#    define SPI_TIMEOUT 100
+#endif
+
+static pin_t   currentSlavePin    = NO_PIN;
+static uint8_t currentSlaveConfig = 0;
+static bool    currentSlave2X     = false;
+
+void spi_init(void) {
+    writePinHigh(SPI_SS_PIN);
+    setPinOutput(SPI_SCK_PIN);
+    setPinOutput(SPI_MOSI_PIN);
+    setPinInput(SPI_MISO_PIN);
+
+    SPCR = (_BV(SPE) | _BV(MSTR));
+}
+
+bool spi_start(pin_t slavePin, bool lsbFirst, uint8_t mode, uint16_t divisor) {
+    if (currentSlavePin != NO_PIN || slavePin == NO_PIN) {
+        return false;
+    }
+
+    currentSlaveConfig = 0;
+
+    if (lsbFirst) {
+        currentSlaveConfig |= _BV(DORD);
+    }
+
+    switch (mode) {
+        case 1:
+            currentSlaveConfig |= _BV(CPHA);
+            break;
+        case 2:
+            currentSlaveConfig |= _BV(CPOL);
+            break;
+        case 3:
+            currentSlaveConfig |= (_BV(CPOL) | _BV(CPHA));
+            break;
+    }
+
+    uint16_t roundedDivisor = 1;
+    while (roundedDivisor < divisor) {
+        roundedDivisor <<= 1;
+    }
+
+    switch (roundedDivisor) {
+        case 16:
+            currentSlaveConfig |= _BV(SPR0);
+            break;
+        case 64:
+            currentSlaveConfig |= _BV(SPR1);
+            break;
+        case 128:
+            currentSlaveConfig |= (_BV(SPR1) | _BV(SPR0));
+            break;
+        case 2:
+            currentSlave2X = true;
+            break;
+        case 8:
+            currentSlave2X = true;
+            currentSlaveConfig |= _BV(SPR0);
+            break;
+        case 32:
+            currentSlave2X = true;
+            currentSlaveConfig |= _BV(SPR1);
+            break;
+    }
+
+    SPCR |= currentSlaveConfig;
+    if (currentSlave2X) {
+        SPSR |= _BV(SPI2X);
+    }
+    currentSlavePin = slavePin;
+    setPinOutput(currentSlavePin);
+    writePinLow(currentSlavePin);
+
+    return true;
+}
+
+spi_status_t spi_write(uint8_t data) {
+    SPDR = data;
+
+    uint16_t timeout_timer = timer_read();
+    while (!(SPSR & _BV(SPIF))) {
+        if ((timer_read() - timeout_timer) >= SPI_TIMEOUT) {
+            return SPI_STATUS_TIMEOUT;
+        }
+    }
+
+    return SPDR;
+}
+
+spi_status_t spi_read() {
+    SPDR = 0x00;  // Dummy
+
+    uint16_t timeout_timer = timer_read();
+    while (!(SPSR & _BV(SPIF))) {
+        if ((timer_read() - timeout_timer) >= SPI_TIMEOUT) {
+            return SPI_STATUS_TIMEOUT;
+        }
+    }
+
+    return SPDR;
+}
+
+spi_status_t spi_transmit(const uint8_t *data, uint16_t length) {
+    spi_status_t status = SPI_STATUS_ERROR;
+
+    for (uint16_t i = 0; i < length; i++) {
+        status = spi_write(data[i]);
+    }
+
+    return status;
+}
+
+spi_status_t spi_receive(uint8_t *data, uint16_t length) {
+    spi_status_t status = SPI_STATUS_ERROR;
+
+    for (uint16_t i = 0; i < length; i++) {
+        status = spi_read();
+
+        if (status > 0) {
+            data[i] = status;
+        }
+    }
+
+    return (status < 0) ? status : SPI_STATUS_SUCCESS;
+}
+
+void spi_stop(void) {
+    if (currentSlavePin != NO_PIN) {
+        setPinOutput(currentSlavePin);
+        writePinHigh(currentSlavePin);
+        currentSlavePin = NO_PIN;
+        SPSR &= ~(_BV(SPI2X));
+        SPCR &= ~(currentSlaveConfig);
+        currentSlaveConfig = 0;
+        currentSlave2X     = false;
+    }
+}

drivers/avr/spi_master.h

@@ -0,0 +1,57 @@
+/*  Copyright 2020
+ *
+ *  This program is free software: you can redistribute it and/or modify
+ *  it under the terms of the GNU General Public License as published by
+ *  the Free Software Foundation, either version 3 of the License, or
+ *  (at your option) any later version.
+ *
+ *  This program is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *  GNU General Public License for more details.
+ *
+ *  You should have received a copy of the GNU General Public License
+ *  along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+#pragma once
+
+#include "quantum.h"
+
+typedef int16_t spi_status_t;
+
+// Hardware SS pin is defined in the header so that user code can refer to it
+#if defined(__AVR_ATmega16U2__) || defined(__AVR_ATmega32U2__) || defined(__AVR_ATmega16U4__) || defined(__AVR_ATmega32U4__) || defined(__AVR_AT90USB646__) || defined(__AVR_AT90USB647__) || defined(__AVR_AT90USB1286__) || defined(__AVR_AT90USB1287__)
+#    define SPI_SS_PIN B0
+#elif defined(__AVR_ATmega32A__)
+#    define SPI_SS_PIN B4
+#elif defined(__AVR_ATmega328P__)
+#    define SPI_SS_PIN B2
+#endif
+
+#define SPI_STATUS_SUCCESS (0)
+#define SPI_STATUS_ERROR (-1)
+#define SPI_STATUS_TIMEOUT (-2)
+
+#define SPI_TIMEOUT_IMMEDIATE (0)
+#define SPI_TIMEOUT_INFINITE (0xFFFF)
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+void spi_init(void);
+
+bool spi_start(pin_t slavePin, bool lsbFirst, uint8_t mode, uint16_t divisor);
+
+spi_status_t spi_write(uint8_t data);
+
+spi_status_t spi_read(void);
+
+spi_status_t spi_transmit(const uint8_t *data, uint16_t length);
+
+spi_status_t spi_receive(uint8_t *data, uint16_t length);
+
+void spi_stop(void);
+#ifdef __cplusplus
+}
+#endif

drivers/avr/ws2812.c

@@ -20,12 +20,13 @@
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
-
 #include "ws2812.h"
 #include <avr/interrupt.h>
 #include <avr/io.h>
 #include <util/delay.h>
 
+#define pinmask(pin) (_BV((pin)&0xF))
+
 /*
  * Forward declare internal functions
  *
@@ -33,20 +34,21 @@
  * The length is the number of bytes to send - three per LED.
  */
 
-void ws2812_sendarray(uint8_t *array, uint16_t length);
-void ws2812_sendarray_mask(uint8_t *array, uint16_t length, uint8_t pinmask);
+static inline void ws2812_sendarray_mask(uint8_t *data, uint16_t datlen, uint8_t masklo, uint8_t maskhi);
 
 // Setleds for standard RGB
-void inline ws2812_setleds(LED_TYPE *ledarray, uint16_t leds) {
-    // ws2812_setleds_pin(ledarray,leds, _BV(ws2812_pin));
-    ws2812_setleds_pin(ledarray, leds, _BV(RGB_DI_PIN & 0xF));
+void inline ws2812_setleds(LED_TYPE *ledarray, uint16_t number_of_leds) {
+    // wrap up usage of RGB_DI_PIN
+    ws2812_setleds_pin(ledarray, number_of_leds, RGB_DI_PIN);
 }
 
-void inline ws2812_setleds_pin(LED_TYPE *ledarray, uint16_t leds, uint8_t pinmask) {
-    // new universal format (DDR)
-    _SFR_IO8((RGB_DI_PIN >> 4) + 1) |= pinmask;
+void ws2812_setleds_pin(LED_TYPE *ledarray, uint16_t number_of_leds, uint8_t pin) {
+    DDRx_ADDRESS(RGB_DI_PIN) |= pinmask(pin);
 
-    ws2812_sendarray_mask((uint8_t *)ledarray, leds * sizeof(LED_TYPE), pinmask);
+    uint8_t masklo = ~(pinmask(pin)) & PORTx_ADDRESS(pin);
+    uint8_t maskhi = pinmask(pin) | PORTx_ADDRESS(pin);
+
+    ws2812_sendarray_mask((uint8_t *)ledarray, number_of_leds * sizeof(LED_TYPE), masklo, maskhi);
 
 #ifdef RGBW
     _delay_us(80);
@@ -55,8 +57,6 @@ void inline ws2812_setleds_pin(LED_TYPE *ledarray, uint16_t leds, uint8_t pinmas
 #endif
 }
 
-void ws2812_sendarray(uint8_t *data, uint16_t datlen) { ws2812_sendarray_mask(data, datlen, _BV(RGB_DI_PIN & 0xF)); }
-
 /*
   This routine writes an array of bytes with RGB values to the Dataout pin
   using the fast 800kHz clockless WS2811/2812 protocol.
@@ -118,14 +118,9 @@ void ws2812_sendarray(uint8_t *data, uint16_t datlen) { ws2812_sendarray_mask(da
 #define w_nop8 w_nop4 w_nop4
 #define w_nop16 w_nop8 w_nop8
 
-void inline ws2812_sendarray_mask(uint8_t *data, uint16_t datlen, uint8_t maskhi) {
-    uint8_t curbyte, ctr, masklo;
-    uint8_t sreg_prev;
+static inline void ws2812_sendarray_mask(uint8_t *data, uint16_t datlen, uint8_t masklo, uint8_t maskhi) {
+    uint8_t curbyte, ctr, sreg_prev;
 
-    // masklo  =~maskhi&ws2812_PORTREG;
-    // maskhi |=        ws2812_PORTREG;
-    masklo = ~maskhi & _SFR_IO8((RGB_DI_PIN >> 4) + 2);
-    maskhi |= _SFR_IO8((RGB_DI_PIN >> 4) + 2);
     sreg_prev = SREG;
     cli();
 
@@ -188,7 +183,7 @@ void inline ws2812_sendarray_mask(uint8_t *data, uint16_t datlen, uint8_t maskhi
                      "       dec   %0    \n\t"  //  '1' [+2] '0' [+2]
                      "       brne  loop%=\n\t"  //  '1' [+3] '0' [+4]
                      : "=&d"(ctr)
-                     : "r"(curbyte), "I"(_SFR_IO_ADDR(_SFR_IO8((RGB_DI_PIN >> 4) + 2))), "r"(maskhi), "r"(masklo));
+                     : "r"(curbyte), "I"(_SFR_IO_ADDR(PORTx_ADDRESS(RGB_DI_PIN))), "r"(maskhi), "r"(masklo));
     }
 
     SREG = sreg_prev;

drivers/avr/ws2812.h

@@ -29,7 +29,7 @@
  * Input:
  *         ledarray:           An array of GRB data describing the LED colors
  *         number_of_leds:     The number of LEDs to write
- *         pinmask (optional): Bitmask describing the output bin. e.g. _BV(PB0)
+ *         pin (optional):     A pin_t definition for the line to drive
  *
  * The functions will perform the following actions:
  *         - Set the data-out pin as output
@@ -37,4 +37,4 @@
  *         - Wait 50us to reset the LEDs
  */
 void ws2812_setleds(LED_TYPE *ledarray, uint16_t number_of_leds);
-void ws2812_setleds_pin(LED_TYPE *ledarray, uint16_t number_of_leds, uint8_t pinmask);
+void ws2812_setleds_pin(LED_TYPE *ledarray, uint16_t number_of_leds, uint8_t pin);

drivers/chibios/analog.c

@@ -0,0 +1,276 @@
+/* Copyright 2019 Drew Mills
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#include "quantum.h"
+#include "analog.h"
+#include "ch.h"
+#include <hal.h>
+
+#if !HAL_USE_ADC
+#    error "You need to set HAL_USE_ADC to TRUE in your halconf.h to use the ADC."
+#endif
+
+#if !STM32_ADC_USE_ADC1 && !STM32_ADC_USE_ADC2 && !STM32_ADC_USE_ADC3 && !STM32_ADC_USE_ADC4
+#    error "You need to set one of the 'STM32_ADC_USE_ADCx' settings to TRUE in your mcuconf.h to use the ADC."
+#endif
+
+#if STM32_ADC_DUAL_MODE
+#    error "STM32 ADC Dual Mode is not supported at this time."
+#endif
+
+#if STM32_ADCV3_OVERSAMPLING
+#    error "STM32 ADCV3 Oversampling is not supported at this time."
+#endif
+
+// Otherwise assume V3
+#if defined(STM32F0XX) || defined(STM32L0XX)
+#    define USE_ADCV1
+#elif defined(STM32F1XX) || defined(STM32F2XX) || defined(STM32F4XX)
+#    define USE_ADCV2
+#endif
+
+// BODGE to make v2 look like v1,3 and 4
+#ifdef USE_ADCV2
+#    if !defined(ADC_SMPR_SMP_1P5) && defined(ADC_SAMPLE_3)
+#        define ADC_SMPR_SMP_1P5 ADC_SAMPLE_3
+#        define ADC_SMPR_SMP_7P5 ADC_SAMPLE_15
+#        define ADC_SMPR_SMP_13P5 ADC_SAMPLE_28
+#        define ADC_SMPR_SMP_28P5 ADC_SAMPLE_56
+#        define ADC_SMPR_SMP_41P5 ADC_SAMPLE_84
+#        define ADC_SMPR_SMP_55P5 ADC_SAMPLE_112
+#        define ADC_SMPR_SMP_71P5 ADC_SAMPLE_144
+#        define ADC_SMPR_SMP_239P5 ADC_SAMPLE_480
+#    endif
+
+#    if !defined(ADC_SMPR_SMP_1P5) && defined(ADC_SAMPLE_1P5)
+#        define ADC_SMPR_SMP_1P5 ADC_SAMPLE_1P5
+#        define ADC_SMPR_SMP_7P5 ADC_SAMPLE_7P5
+#        define ADC_SMPR_SMP_13P5 ADC_SAMPLE_13P5
+#        define ADC_SMPR_SMP_28P5 ADC_SAMPLE_28P5
+#        define ADC_SMPR_SMP_41P5 ADC_SAMPLE_41P5
+#        define ADC_SMPR_SMP_55P5 ADC_SAMPLE_55P5
+#        define ADC_SMPR_SMP_71P5 ADC_SAMPLE_71P5
+#        define ADC_SMPR_SMP_239P5 ADC_SAMPLE_239P5
+#    endif
+
+// we still sample at 12bit, but scale down to the requested bit range
+#    define ADC_CFGR1_RES_12BIT 12
+#    define ADC_CFGR1_RES_10BIT 10
+#    define ADC_CFGR1_RES_8BIT 8
+#    define ADC_CFGR1_RES_6BIT 6
+#endif
+
+/* User configurable ADC options */
+#ifndef ADC_COUNT
+#    if defined(STM32F0XX) || defined(STM32F1XX) || defined(STM32F4XX)
+#        define ADC_COUNT 1
+#    elif defined(STM32F3XX)
+#        define ADC_COUNT 4
+#    else
+#        error "ADC_COUNT has not been set for this ARM microcontroller."
+#    endif
+#endif
+
+#ifndef ADC_NUM_CHANNELS
+#    define ADC_NUM_CHANNELS 1
+#elif ADC_NUM_CHANNELS != 1
+#    error "The ARM ADC implementation currently only supports reading one channel at a time."
+#endif
+
+#ifndef ADC_BUFFER_DEPTH
+#    define ADC_BUFFER_DEPTH 1
+#endif
+
+// For more sampling rate options, look at hal_adc_lld.h in ChibiOS
+#ifndef ADC_SAMPLING_RATE
+#    define ADC_SAMPLING_RATE ADC_SMPR_SMP_1P5
+#endif
+
+// Options are 12, 10, 8, and 6 bit.
+#ifndef ADC_RESOLUTION
+#    define ADC_RESOLUTION ADC_CFGR1_RES_10BIT
+#endif
+
+static ADCConfig   adcCfg = {};
+static adcsample_t sampleBuffer[ADC_NUM_CHANNELS * ADC_BUFFER_DEPTH];
+
+// Initialize to max number of ADCs, set to empty object to initialize all to false.
+static bool adcInitialized[ADC_COUNT] = {};
+
+// TODO: add back TR handling???
+static ADCConversionGroup adcConversionGroup = {
+    .circular     = FALSE,
+    .num_channels = (uint16_t)(ADC_NUM_CHANNELS),
+#if defined(USE_ADCV1)
+    .cfgr1 = ADC_CFGR1_CONT | ADC_RESOLUTION,
+    .smpr  = ADC_SAMPLING_RATE,
+#elif defined(USE_ADCV2)
+#    if !defined(STM32F1XX)
+    .cr2   = ADC_CR2_SWSTART,  // F103 seem very unhappy with, F401 seems very unhappy without...
+#    endif
+    .smpr2 = ADC_SMPR2_SMP_AN0(ADC_SAMPLING_RATE) | ADC_SMPR2_SMP_AN1(ADC_SAMPLING_RATE) | ADC_SMPR2_SMP_AN2(ADC_SAMPLING_RATE) | ADC_SMPR2_SMP_AN3(ADC_SAMPLING_RATE) | ADC_SMPR2_SMP_AN4(ADC_SAMPLING_RATE) | ADC_SMPR2_SMP_AN5(ADC_SAMPLING_RATE) | ADC_SMPR2_SMP_AN6(ADC_SAMPLING_RATE) | ADC_SMPR2_SMP_AN7(ADC_SAMPLING_RATE) | ADC_SMPR2_SMP_AN8(ADC_SAMPLING_RATE) | ADC_SMPR2_SMP_AN9(ADC_SAMPLING_RATE),
+    .smpr1 = ADC_SMPR1_SMP_AN10(ADC_SAMPLING_RATE) | ADC_SMPR1_SMP_AN11(ADC_SAMPLING_RATE) | ADC_SMPR1_SMP_AN12(ADC_SAMPLING_RATE) | ADC_SMPR1_SMP_AN13(ADC_SAMPLING_RATE) | ADC_SMPR1_SMP_AN14(ADC_SAMPLING_RATE) | ADC_SMPR1_SMP_AN15(ADC_SAMPLING_RATE),
+#else
+    .cfgr = ADC_CFGR_CONT | ADC_RESOLUTION,
+    .smpr = {ADC_SMPR1_SMP_AN0(ADC_SAMPLING_RATE) | ADC_SMPR1_SMP_AN1(ADC_SAMPLING_RATE) | ADC_SMPR1_SMP_AN2(ADC_SAMPLING_RATE) | ADC_SMPR1_SMP_AN3(ADC_SAMPLING_RATE) | ADC_SMPR1_SMP_AN4(ADC_SAMPLING_RATE) | ADC_SMPR1_SMP_AN5(ADC_SAMPLING_RATE) | ADC_SMPR1_SMP_AN6(ADC_SAMPLING_RATE) | ADC_SMPR1_SMP_AN7(ADC_SAMPLING_RATE) | ADC_SMPR1_SMP_AN8(ADC_SAMPLING_RATE) | ADC_SMPR1_SMP_AN9(ADC_SAMPLING_RATE), ADC_SMPR2_SMP_AN10(ADC_SAMPLING_RATE) | ADC_SMPR2_SMP_AN11(ADC_SAMPLING_RATE) | ADC_SMPR2_SMP_AN12(ADC_SAMPLING_RATE) | ADC_SMPR2_SMP_AN13(ADC_SAMPLING_RATE) | ADC_SMPR2_SMP_AN14(ADC_SAMPLING_RATE) | ADC_SMPR2_SMP_AN15(ADC_SAMPLING_RATE) | ADC_SMPR2_SMP_AN16(ADC_SAMPLING_RATE) | ADC_SMPR2_SMP_AN17(ADC_SAMPLING_RATE) | ADC_SMPR2_SMP_AN18(ADC_SAMPLING_RATE)},
+#endif
+};
+
+// clang-format off
+__attribute__((weak)) adc_mux pinToMux(pin_t pin) {
+    switch (pin) {
+#if defined(STM32F0XX)
+        case A0:  return TO_MUX( ADC_CHSELR_CHSEL0,  0 );
+        case A1:  return TO_MUX( ADC_CHSELR_CHSEL1,  0 );
+        case A2:  return TO_MUX( ADC_CHSELR_CHSEL2,  0 );
+        case A3:  return TO_MUX( ADC_CHSELR_CHSEL3,  0 );
+        case A4:  return TO_MUX( ADC_CHSELR_CHSEL4,  0 );
+        case A5:  return TO_MUX( ADC_CHSELR_CHSEL5,  0 );
+        case A6:  return TO_MUX( ADC_CHSELR_CHSEL6,  0 );
+        case A7:  return TO_MUX( ADC_CHSELR_CHSEL7,  0 );
+        case B0:  return TO_MUX( ADC_CHSELR_CHSEL8,  0 );
+        case B1:  return TO_MUX( ADC_CHSELR_CHSEL9,  0 );
+        case C0:  return TO_MUX( ADC_CHSELR_CHSEL10, 0 );
+        case C1:  return TO_MUX( ADC_CHSELR_CHSEL11, 0 );
+        case C2:  return TO_MUX( ADC_CHSELR_CHSEL12, 0 );
+        case C3:  return TO_MUX( ADC_CHSELR_CHSEL13, 0 );
+        case C4:  return TO_MUX( ADC_CHSELR_CHSEL14, 0 );
+        case C5:  return TO_MUX( ADC_CHSELR_CHSEL15, 0 );
+#elif defined(STM32F3XX)
+        case A0:  return TO_MUX( ADC_CHANNEL_IN1,  0 );
+        case A1:  return TO_MUX( ADC_CHANNEL_IN2,  0 );
+        case A2:  return TO_MUX( ADC_CHANNEL_IN3,  0 );
+        case A3:  return TO_MUX( ADC_CHANNEL_IN4,  0 );
+        case A4:  return TO_MUX( ADC_CHANNEL_IN1,  1 );
+        case A5:  return TO_MUX( ADC_CHANNEL_IN2,  1 );
+        case A6:  return TO_MUX( ADC_CHANNEL_IN3,  1 );
+        case A7:  return TO_MUX( ADC_CHANNEL_IN4,  1 );
+        case B0:  return TO_MUX( ADC_CHANNEL_IN12, 2 );
+        case B1:  return TO_MUX( ADC_CHANNEL_IN1,  2 );
+        case B2:  return TO_MUX( ADC_CHANNEL_IN12, 1 );
+        case B12: return TO_MUX( ADC_CHANNEL_IN2,  3 );
+        case B13: return TO_MUX( ADC_CHANNEL_IN3,  3 );
+        case B14: return TO_MUX( ADC_CHANNEL_IN4,  3 );
+        case B15: return TO_MUX( ADC_CHANNEL_IN5,  3 );
+        case C0:  return TO_MUX( ADC_CHANNEL_IN6,  0 ); // Can also be ADC2
+        case C1:  return TO_MUX( ADC_CHANNEL_IN7,  0 ); // Can also be ADC2
+        case C2:  return TO_MUX( ADC_CHANNEL_IN8,  0 ); // Can also be ADC2
+        case C3:  return TO_MUX( ADC_CHANNEL_IN9,  0 ); // Can also be ADC2
+        case C4:  return TO_MUX( ADC_CHANNEL_IN5,  1 );
+        case C5:  return TO_MUX( ADC_CHANNEL_IN11, 1 );
+        case D8:  return TO_MUX( ADC_CHANNEL_IN12, 3 );
+        case D9:  return TO_MUX( ADC_CHANNEL_IN13, 3 );
+        case D10: return TO_MUX( ADC_CHANNEL_IN7,  2 ); // Can also be ADC4
+        case D11: return TO_MUX( ADC_CHANNEL_IN8,  2 ); // Can also be ADC4
+        case D12: return TO_MUX( ADC_CHANNEL_IN9,  2 ); // Can also be ADC4
+        case D13: return TO_MUX( ADC_CHANNEL_IN10, 2 ); // Can also be ADC4
+        case D14: return TO_MUX( ADC_CHANNEL_IN11, 2 ); // Can also be ADC4
+        case E7:  return TO_MUX( ADC_CHANNEL_IN13, 2 );
+        case E8:  return TO_MUX( ADC_CHANNEL_IN6,  2 ); // Can also be ADC4
+        case E9:  return TO_MUX( ADC_CHANNEL_IN2,  2 );
+        case E10: return TO_MUX( ADC_CHANNEL_IN14, 2 );
+        case E11: return TO_MUX( ADC_CHANNEL_IN15, 2 );
+        case E12: return TO_MUX( ADC_CHANNEL_IN16, 2 );
+        case E13: return TO_MUX( ADC_CHANNEL_IN3,  2 );
+        case E14: return TO_MUX( ADC_CHANNEL_IN1,  3 );
+        case E15: return TO_MUX( ADC_CHANNEL_IN2,  3 );
+        case F2:  return TO_MUX( ADC_CHANNEL_IN10, 0 ); // Can also be ADC2
+        case F4:  return TO_MUX( ADC_CHANNEL_IN5,  0 );
+#elif defined(STM32F4XX) // TODO: add all pins
+        case A0:  return TO_MUX( ADC_CHANNEL_IN0,  0 );
+        //case A1:  return TO_MUX( ADC_CHANNEL_IN1,  0 );
+#elif defined(STM32F1XX) // TODO: add all pins
+        case A0:  return TO_MUX( ADC_CHANNEL_IN0,  0 );
+#endif
+    }
+
+    // return an adc that would never be used so intToADCDriver will bail out
+    return TO_MUX(0, 0xFF);
+}
+// clang-format on
+
+static inline ADCDriver* intToADCDriver(uint8_t adcInt) {
+    switch (adcInt) {
+#if STM32_ADC_USE_ADC1
+        case 0:
+            return &ADCD1;
+#endif
+#if STM32_ADC_USE_ADC2
+        case 1:
+            return &ADCD2;
+#endif
+#if STM32_ADC_USE_ADC3
+        case 2:
+            return &ADCD3;
+#endif
+#if STM32_ADC_USE_ADC4
+        case 3:
+            return &ADCD4;
+#endif
+    }
+
+    return NULL;
+}
+
+static inline void manageAdcInitializationDriver(uint8_t adc, ADCDriver* adcDriver) {
+    if (!adcInitialized[adc]) {
+        adcStart(adcDriver, &adcCfg);
+        adcInitialized[adc] = true;
+    }
+}
+
+int16_t analogReadPin(pin_t pin) {
+    palSetLineMode(pin, PAL_MODE_INPUT_ANALOG);
+
+    return adc_read(pinToMux(pin));
+}
+
+int16_t analogReadPinAdc(pin_t pin, uint8_t adc) {
+    palSetLineMode(pin, PAL_MODE_INPUT_ANALOG);
+
+    adc_mux target = pinToMux(pin);
+    target.adc     = adc;
+    return adc_read(target);
+}
+
+int16_t adc_read(adc_mux mux) {
+#if defined(USE_ADCV1)
+    // TODO: fix previous assumption of only 1 input...
+    adcConversionGroup.chselr = 1 << mux.input; /*no macro to convert N to ADC_CHSELR_CHSEL1*/
+#elif defined(USE_ADCV2)
+    adcConversionGroup.sqr3 = ADC_SQR3_SQ1_N(mux.input);
+#else
+    adcConversionGroup.sqr[0] = ADC_SQR1_SQ1_N(mux.input);
+#endif
+
+    ADCDriver* targetDriver = intToADCDriver(mux.adc);
+    if (!targetDriver) {
+        return 0;
+    }
+
+    manageAdcInitializationDriver(mux.adc, targetDriver);
+    if (adcConvert(targetDriver, &adcConversionGroup, &sampleBuffer[0], ADC_BUFFER_DEPTH) != MSG_OK) {
+        return 0;
+    }
+
+#ifdef USE_ADCV2
+    // fake 12-bit -> N-bit scale
+    return (*sampleBuffer) >> (12 - ADC_RESOLUTION);
+#else
+    // already handled as part of adcConvert
+    return *sampleBuffer;
+#endif
+}

drivers/chibios/analog.h

@@ -0,0 +1,41 @@
+/* Copyright 2019 Drew Mills
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#pragma once
+
+#include <stdint.h>
+#include "quantum.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+typedef struct {
+    uint16_t input;
+    uint8_t  adc;
+} adc_mux;
+#define TO_MUX(i, a) \
+    (adc_mux) { i, a }
+
+int16_t analogReadPin(pin_t pin);
+int16_t analogReadPinAdc(pin_t pin, uint8_t adc);
+adc_mux pinToMux(pin_t pin);
+
+int16_t adc_read(adc_mux mux);
+
+#ifdef __cplusplus
+}
+#endif

drivers/oled/oled_driver.c

@@ -23,9 +23,6 @@ along with this program.  If not, see <http://www.gnu.org/licenses/>.
 #include <string.h>
 
 #include "progmem.h"
-#ifndef __AVR__
-#    define memcpy_P(des, src, len) memcpy(des, src, len)
-#endif
 
 // Used commands from spec sheet: https://cdn-shop.adafruit.com/datasheets/SSD1306.pdf
 // for SH1106: https://www.velleman.eu/downloads/29/infosheets/sh1106_datasheet.pdf