Allow 30us matrix delay to be keyboard/user overridable (#8216)

* Allow 30us matrix delay to be configurable via define

* Move wait logic to matrix_common

* Move wait logic to matrix_common - fix wait includes

.github/workflows/cli.yml

@@ -0,0 +1,28 @@
+name: CLI CI
+
+on:
+  push:
+    branches:
+    - master
+    - future
+  pull_request:
+    paths:
+    - 'lib/python/**'
+    - 'bin/qmk'
+    - 'requirements.txt'
+    - '.github/workflows/cli.yml'
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    container: qmkfm/base_container
+
+    steps:
+    - uses: actions/checkout@v1
+      with:
+        submodules: recursive
+    - name: Install dependencies
+      run: pip3 install -r requirements.txt
+    - name: Run tests
+      run: bin/qmk pytest

.gitignore

@@ -63,9 +63,6 @@ util/Win_Check_Output.txt
 *.gif
 *.jpg
 
-# Do not ignore MiniDox left/right hand eeprom files
-!keyboards/minidox/*.eep
-
 # things travis sees
 secrets.tar
 id_rsa_*

.travis.yml

@@ -12,6 +12,18 @@ env:
   - MAKEFLAGS="-j3 --output-sync"
 services:
   - docker
+addons:
+  apt:
+    sources:
+      - ubuntu-toolchain-r-test
+      - llvm-toolchain-trusty-7
+    packages:
+    - pandoc
+    - diffutils
+    - dos2unix
+    - doxygen
+    - clang-format-7
+    - libstdc++-7-dev
 install:
   - npm install -g moxygen
 script:
@@ -20,13 +32,6 @@ script:
   - bash util/travis_test.sh
   - bash util/travis_build.sh
   - bash util/travis_docs.sh
-addons:
-  apt:
-    packages:
-    - pandoc
-    - diffutils
-    - dos2unix
-    - doxygen
 after_script:
   bash util/travis_compiled_push.sh
 notifications:

bootloader.mk

@@ -82,6 +82,13 @@ ifeq ($(strip $(BOOTLOADER)), USBasp)
     OPT_DEFS += -DBOOTLOADER_USBASP
     BOOTLOADER_SIZE = 4096
 endif
+ifeq ($(strip $(BOOTLOADER)), lufa-ms)
+    # DO NOT USE THIS BOOTLOADER IN NEW PROJECTS!
+    # It is extremely prone to bricking, and is only included to support existing boards.
+    OPT_DEFS += -DBOOTLOADER_MS
+    BOOTLOADER_SIZE = 6144
+    FIRMWARE_FORMAT = bin
+endif
 
 ifdef BOOTLOADER_SIZE
     OPT_DEFS += -DBOOTLOADER_SIZE=$(strip $(BOOTLOADER_SIZE))

common_features.mk

@@ -61,7 +61,7 @@ endif
 
 ifeq ($(strip $(STENO_ENABLE)), yes)
     OPT_DEFS += -DSTENO_ENABLE
-    VIRTSER_ENABLE := yes
+    VIRTSER_ENABLE ?= yes
     SRC += $(QUANTUM_DIR)/process_keycode/process_steno.c
 endif
 
@@ -82,19 +82,19 @@ endif
 
 ifeq ($(strip $(UCIS_ENABLE)), yes)
     OPT_DEFS += -DUCIS_ENABLE
-    UNICODE_COMMON = yes
+    UNICODE_COMMON := yes
     SRC += $(QUANTUM_DIR)/process_keycode/process_ucis.c
 endif
 
 ifeq ($(strip $(UNICODEMAP_ENABLE)), yes)
     OPT_DEFS += -DUNICODEMAP_ENABLE
-    UNICODE_COMMON = yes
+    UNICODE_COMMON := yes
     SRC += $(QUANTUM_DIR)/process_keycode/process_unicodemap.c
 endif
 
 ifeq ($(strip $(UNICODE_ENABLE)), yes)
     OPT_DEFS += -DUNICODE_ENABLE
-    UNICODE_COMMON = yes
+    UNICODE_COMMON := yes
     SRC += $(QUANTUM_DIR)/process_keycode/process_unicode.c
 endif
 
@@ -102,18 +102,69 @@ 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)),)
+  $(error EEPROM_DRIVER="$(EEPROM_DRIVER)" is not a valid EEPROM driver)
+else
+  OPT_DEFS += -DEEPROM_ENABLE
+  ifeq ($(strip $(EEPROM_DRIVER)), custom)
+    OPT_DEFS += -DEEPROM_DRIVER -DEEPROM_CUSTOM
+    COMMON_VPATH += $(DRIVER_PATH)/eeprom
+    SRC += eeprom_driver.c
+  else ifeq ($(strip $(EEPROM_DRIVER)), i2c)
+    OPT_DEFS += -DEEPROM_DRIVER -DEEPROM_I2C
+    COMMON_VPATH += $(DRIVER_PATH)/eeprom
+    QUANTUM_LIB_SRC += i2c_master.c
+    SRC += eeprom_driver.c eeprom_i2c.c
+  else ifeq ($(strip $(EEPROM_DRIVER)), transient)
+    OPT_DEFS += -DEEPROM_DRIVER -DEEPROM_TRANSIENT
+    COMMON_VPATH += $(DRIVER_PATH)/eeprom
+    SRC += eeprom_driver.c eeprom_transient.c
+  else ifeq ($(strip $(EEPROM_DRIVER)), vendor)
+    OPT_DEFS += -DEEPROM_VENDOR
+    ifeq ($(PLATFORM),AVR)
+      # Automatically provided by avr-libc, nothing required
+    else ifeq ($(PLATFORM),CHIBIOS)
+      ifeq ($(MCU_SERIES), STM32F3xx)
+        SRC += $(PLATFORM_COMMON_DIR)/eeprom_stm32.c
+        SRC += $(PLATFORM_COMMON_DIR)/flash_stm32.c
+        OPT_DEFS += -DEEPROM_EMU_STM32F303xC
+        OPT_DEFS += -DSTM32_EEPROM_ENABLE
+      else ifeq ($(MCU_SERIES), STM32F1xx)
+        SRC += $(PLATFORM_COMMON_DIR)/eeprom_stm32.c
+        SRC += $(PLATFORM_COMMON_DIR)/flash_stm32.c
+        OPT_DEFS += -DEEPROM_EMU_STM32F103xB
+        OPT_DEFS += -DSTM32_EEPROM_ENABLE
+      else ifeq ($(MCU_SERIES)_$(MCU_LDSCRIPT), STM32F0xx_STM32F072xB)
+        SRC += $(PLATFORM_COMMON_DIR)/eeprom_stm32.c
+        SRC += $(PLATFORM_COMMON_DIR)/flash_stm32.c
+        OPT_DEFS += -DEEPROM_EMU_STM32F072xB
+        OPT_DEFS += -DSTM32_EEPROM_ENABLE
+      else
+        # This will effectively work the same as "transient" if not supported by the chip
+        SRC += $(PLATFORM_COMMON_DIR)/eeprom_teensy.c
+      endif
+    else ifeq ($(PLATFORM),ARM_ATSAM)
+      SRC += $(PLATFORM_COMMON_DIR)/eeprom.c
+    else ifeq ($(PLATFORM),TEST)
+      SRC += $(PLATFORM_COMMON_DIR)/eeprom.c
+    endif
+  endif
+endif
+
 ifeq ($(strip $(RGBLIGHT_ENABLE)), yes)
     POST_CONFIG_H += $(QUANTUM_DIR)/rgblight_post_config.h
     OPT_DEFS += -DRGBLIGHT_ENABLE
     SRC += $(QUANTUM_DIR)/color.c
     SRC += $(QUANTUM_DIR)/rgblight.c
-    CIE1931_CURVE = yes
-    LED_BREATHING_TABLE = yes
-    RGB_KEYCODES_ENABLE = yes
+    CIE1931_CURVE := yes
+    LED_BREATHING_TABLE := yes
+    RGB_KEYCODES_ENABLE := yes
     ifeq ($(strip $(RGBLIGHT_CUSTOM_DRIVER)), yes)
         OPT_DEFS += -DRGBLIGHT_CUSTOM_DRIVER
     else
-        WS2812_DRIVER_REQUIRED = yes
+        WS2812_DRIVER_REQUIRED := yes
     endif
 endif
 
@@ -124,7 +175,9 @@ ifneq ($(strip $(LED_MATRIX_ENABLE)), no)
     ifeq ($(filter $(LED_MATRIX_ENABLE),$(VALID_MATRIX_TYPES)),)
         $(error LED_MATRIX_ENABLE="$(LED_MATRIX_ENABLE)" is not a valid matrix type)
     else
-        OPT_DEFS += -DLED_MATRIX_ENABLE -DBACKLIGHT_ENABLE -DBACKLIGHT_CUSTOM_DRIVER
+        BACKLIGHT_ENABLE = yes
+        BACKLIGHT_DRIVER = custom
+        OPT_DEFS += -DLED_MATRIX_ENABLE
         SRC += $(QUANTUM_DIR)/led_matrix.c
         SRC += $(QUANTUM_DIR)/led_matrix_drivers.c
     endif
@@ -147,12 +200,12 @@ endif
     SRC += $(QUANTUM_DIR)/color.c
     SRC += $(QUANTUM_DIR)/rgb_matrix.c
     SRC += $(QUANTUM_DIR)/rgb_matrix_drivers.c
-    CIE1931_CURVE = yes
-    RGB_KEYCODES_ENABLE = yes
+    CIE1931_CURVE := yes
+    RGB_KEYCODES_ENABLE := yes
 endif
 
 ifeq ($(strip $(RGB_MATRIX_ENABLE)), yes)
-	RGB_MATRIX_ENABLE = IS31FL3731
+	RGB_MATRIX_ENABLE := IS31FL3731
 endif
 
 ifeq ($(strip $(RGB_MATRIX_ENABLE)), IS31FL3731)
@@ -178,7 +231,7 @@ endif
 
 ifeq ($(strip $(RGB_MATRIX_ENABLE)), WS2812)
     OPT_DEFS += -DWS2812
-    WS2812_DRIVER_REQUIRED = yes
+    WS2812_DRIVER_REQUIRED := yes
 endif
 
 ifeq ($(strip $(RGB_MATRIX_CUSTOM_KB)), yes)
@@ -232,12 +285,12 @@ endif
 endif
 
 ifeq ($(strip $(LCD_ENABLE)), yes)
-    CIE1931_CURVE = yes
+    CIE1931_CURVE := yes
 endif
 
 # backward compat
 ifeq ($(strip $(BACKLIGHT_CUSTOM_DRIVER)), yes)
-    BACKLIGHT_DRIVER = custom
+    BACKLIGHT_DRIVER := custom
 endif
 
 VALID_BACKLIGHT_TYPES := pwm software custom
@@ -249,21 +302,15 @@ ifeq ($(strip $(BACKLIGHT_ENABLE)), yes)
         $(error BACKLIGHT_DRIVER="$(BACKLIGHT_DRIVER)" is not a valid backlight type)
     endif
 
-    ifeq ($(strip $(VISUALIZER_ENABLE)), yes)
-        CIE1931_CURVE = yes
-    endif
-
     COMMON_VPATH += $(QUANTUM_DIR)/backlight
     SRC += $(QUANTUM_DIR)/backlight/backlight.c
     OPT_DEFS += -DBACKLIGHT_ENABLE
 
-    ifeq ($(strip $(BACKLIGHT_DRIVER)), software)
+    ifeq ($(strip $(BACKLIGHT_DRIVER)), custom)
+        OPT_DEFS += -DBACKLIGHT_CUSTOM_DRIVER
+    else ifeq ($(strip $(BACKLIGHT_DRIVER)), software)
         SRC += $(QUANTUM_DIR)/backlight/backlight_soft.c
     else
-        ifeq ($(strip $(BACKLIGHT_DRIVER)), custom)
-            OPT_DEFS += -DBACKLIGHT_CUSTOM_DRIVER
-        endif
-
         ifeq ($(PLATFORM),AVR)
             SRC += $(QUANTUM_DIR)/backlight/backlight_avr.c
         else
@@ -280,6 +327,8 @@ ifeq ($(strip $(WS2812_DRIVER_REQUIRED)), yes)
         $(error WS2812_DRIVER="$(WS2812_DRIVER)" is not a valid WS2812 driver)
     endif
 
+    OPT_DEFS += -DWS2812_DRIVER_$(strip $(shell echo $(WS2812_DRIVER) | tr '[:lower:]' '[:upper:]'))
+
     ifeq ($(strip $(WS2812_DRIVER)), bitbang)
         SRC += ws2812.c
     else
@@ -292,14 +341,18 @@ ifeq ($(strip $(WS2812_DRIVER_REQUIRED)), yes)
     endif
 endif
 
+ifeq ($(strip $(VISUALIZER_ENABLE)), yes)
+    CIE1931_CURVE := yes
+endif
+
 ifeq ($(strip $(CIE1931_CURVE)), yes)
     OPT_DEFS += -DUSE_CIE1931_CURVE
-    LED_TABLES = yes
+    LED_TABLES := yes
 endif
 
 ifeq ($(strip $(LED_BREATHING_TABLE)), yes)
     OPT_DEFS += -DUSE_LED_BREATHING_TABLE
-    LED_TABLES = yes
+    LED_TABLES := yes
 endif
 
 ifeq ($(strip $(LED_TABLES)), yes)
@@ -349,6 +402,14 @@ ifeq ($(strip $(VELOCIKEY_ENABLE)), yes)
     SRC += $(QUANTUM_DIR)/velocikey.c
 endif
 
+ifeq ($(strip $(VIA_ENABLE)), yes)
+    DYNAMIC_KEYMAP_ENABLE := yes
+    RAW_ENABLE := yes
+    BOOTMAGIC_ENABLE := lite
+    SRC += $(QUANTUM_DIR)/via.c
+    OPT_DEFS += -DVIA_ENABLE
+endif
+
 ifeq ($(strip $(DYNAMIC_KEYMAP_ENABLE)), yes)
     OPT_DEFS += -DDYNAMIC_KEYMAP_ENABLE
     SRC += $(QUANTUM_DIR)/dynamic_keymap.c
@@ -359,6 +420,12 @@ ifeq ($(strip $(LEADER_ENABLE)), yes)
   OPT_DEFS += -DLEADER_ENABLE
 endif
 
+
+ifeq ($(strip $(DIP_SWITCH_ENABLE)), yes)
+  SRC += $(QUANTUM_DIR)/dip_switch.c
+  OPT_DEFS += -DDIP_SWITCH_ENABLE
+endif
+
 include $(DRIVER_PATH)/qwiic/qwiic.mk
 
 QUANTUM_SRC:= \
@@ -366,12 +433,28 @@ QUANTUM_SRC:= \
     $(QUANTUM_DIR)/keymap_common.c \
     $(QUANTUM_DIR)/keycode_config.c
 
-# Include the standard or split matrix code if needed
+
+
+VALID_CUSTOM_MATRIX_TYPES:= yes lite no
+
+CUSTOM_MATRIX ?= no
+
 ifneq ($(strip $(CUSTOM_MATRIX)), yes)
-    ifeq ($(strip $(SPLIT_KEYBOARD)), yes)
-        QUANTUM_SRC += $(QUANTUM_DIR)/split_common/matrix.c
-    else
-        QUANTUM_SRC += $(QUANTUM_DIR)/matrix.c
+    ifeq ($(filter $(CUSTOM_MATRIX),$(VALID_CUSTOM_MATRIX_TYPES)),)
+        $(error CUSTOM_MATRIX="$(CUSTOM_MATRIX)" is not a valid custom matrix type)
+    endif
+
+    # Include common stuff for all non custom matrix users
+    QUANTUM_SRC += $(QUANTUM_DIR)/matrix_common.c
+
+    # if 'lite' then skip the actual matrix implementation
+    ifneq ($(strip $(CUSTOM_MATRIX)), lite)
+        # Include the standard or split matrix code if needed
+        ifeq ($(strip $(SPLIT_KEYBOARD)), yes)
+            QUANTUM_SRC += $(QUANTUM_DIR)/split_common/matrix.c
+        else
+            QUANTUM_SRC += $(QUANTUM_DIR)/matrix.c
+        endif
     endif
 endif
 
@@ -394,9 +477,17 @@ ifeq ($(strip $(SPLIT_KEYBOARD)), yes)
         QUANTUM_SRC += $(QUANTUM_DIR)/split_common/transport.c
         # Functions added via QUANTUM_LIB_SRC are only included in the final binary if they're called.
         # Unused functions are pruned away, which is why we can add multiple drivers here without bloat.
-        QUANTUM_LIB_SRC += $(QUANTUM_DIR)/split_common/serial.c \
-                           i2c_master.c \
-                           i2c_slave.c
+        ifeq ($(PLATFORM),AVR)
+            QUANTUM_LIB_SRC += i2c_master.c \
+                               i2c_slave.c
+        endif
+
+        SERIAL_DRIVER ?= bitbang
+        ifeq ($(strip $(SERIAL_DRIVER)), bitbang)
+            QUANTUM_LIB_SRC += serial.c
+        else
+            QUANTUM_LIB_SRC += serial_$(strip $(SERIAL_DRIVER)).c
+        endif
     endif
     COMMON_VPATH += $(QUANTUM_PATH)/split_common
 endif
@@ -420,12 +511,13 @@ ifeq ($(strip $(MAGIC_ENABLE)), yes)
     OPT_DEFS += -DMAGIC_KEYCODE_ENABLE
 endif
 
+GRAVE_ESC_ENABLE ?= yes
+ifeq ($(strip $(GRAVE_ESC_ENABLE)), yes)
+    SRC += $(QUANTUM_DIR)/process_keycode/process_grave_esc.c
+    OPT_DEFS += -DGRAVE_ESC_ENABLE
+endif
+
 ifeq ($(strip $(DYNAMIC_MACRO_ENABLE)), yes)
     SRC += $(QUANTUM_DIR)/process_keycode/process_dynamic_macro.c
     OPT_DEFS += -DDYNAMIC_MACRO_ENABLE
 endif
-
-ifeq ($(strip $(DIP_SWITCH_ENABLE)), yes)
-  SRC += $(QUANTUM_DIR)/dip_switch.c
-  OPT_DEFS += -DDIP_SWITCH_ENABLE
-endif

docs/_summary.md

@@ -18,6 +18,7 @@
   * [Getting Help](getting_started_getting_help.md)
 
 * [Breaking Changes](breaking_changes.md)
+  * [My Pull Request Was Flagged](breaking_changes_instructions.md)
   * [2019 Aug 30](ChangeLog/20190830.md)
 
 * [FAQ](faq.md)
@@ -104,7 +105,9 @@
   * [ADC Driver](adc_driver.md)
   * [I2C Driver](i2c_driver.md)
   * [WS2812 Driver](ws2812_driver.md)
+  * [EEPROM Driver](eeprom_driver.md)
   * [GPIO Controls](internals_gpio_control.md)
+  * [Custom Matrix](custom_matrix.md)
   * [Proton C Conversion](proton_c_conversion.md)
 
 * For a Deeper Understanding

docs/arm_debugging.md

@@ -1,4 +1,4 @@
-# ARM Debugging usign Eclipse
+# ARM Debugging using Eclipse
 
 This page describes how to setup debugging for ARM MCUs using an SWD adapter and open-source/free tools. In this guide we will install GNU MCU Eclipse IDE for C/C++ Developers and OpenOCD together with all the necessary dependencies.
 
@@ -18,7 +18,7 @@ XPM installation instructions can be found [here](https://www.npmjs.com/package/
 
 ### The ARM Toolchain
 
-Using XPM it is very easy to install the ARM toolchain. Enter the command `xpm install --global @gnu-mcu-eclipse/arm-none-eabi-gcc`.
+Using XPM it is very easy to install the ARM toolchain. Enter the command `xpm install --global @xpack-dev-tools/arm-none-eabi-gcc`.
 
 ### Windows build tools
 
@@ -33,7 +33,7 @@ If you have an ST-Link the drivers can be found [here](https://www.st.com/en/dev
 
 ### OpenOCD
 
-This dependency allows SWD access from GDB and it is essential for debugging. Run `xpm install --global @gnu-mcu-eclipse/openocd`.
+This dependency allows SWD access from GDB and it is essential for debugging. Run `xpm install --global @xpack-dev-tools/openocd`.
 
 ### Java
 
@@ -45,17 +45,17 @@ Now its finally time to install the IDE. Use the Release page [here](https://git
 
 ## Configuring Eclipse
 
-Open up the Eclipse IDE we just downloaded. To import our QMK directory select File -> Import -> C/C++ -> Existing code as Makefile Project. Select next and use Browse to select your QMK folder. In the tool-chain list select ARM Cross GCC and select Finish.
+Open up the Eclipse IDE we just downloaded. To import our QMK directory select File -> Import -> C/C++ -> Existing Code as Makefile Project. Select Next and use Browse to select your QMK folder. In the tool-chain list select ARM Cross GCC and select Finish.
 
-Now you can see the QMK folder on the left hand side. Right click it and select Properties. On the left hand side, expand MCU and select ARM Toolchain Paths. Press xPack and OK. Repeat for OpenOCD Path  and if you are on windows for Build Tool Path. Select Apply and Close.
+Now you can see the QMK folder on the left hand side. Right click it and select Properties. On the left hand side, expand MCU and select ARM Toolchains Paths. Press xPack and OK. Repeat for OpenOCD Path and if you are on Windows for Build Tools Path. Select Apply and Close.
 
-Now its time to install the necessary MCU packages. Go to Packs perspective by selecting Window -> Open Perspective -> Others -> Packs. Now select the yellow refresh symbol next to the Packs tab. This will take a long time as it is requesting the MCU definitions from various places. If some of the links fail you can probably select Ignore.
+Now its time to install the necessary MCU packages. Go to Packs perspective by selecting Window -> Perspective -> Open Perspective -> Other... -> Packs. Now select the yellow refresh symbol next to the Packs tab. This will take a long time as it is requesting the MCU definitions from various places. If some of the links fail you can probably select Ignore.
 
-When this finishes you must find the MCU which we will be building/debugging for. In this example I will be using the STM32F3 series MCUs. On the left, select STMicroelectonics -> STM32F3 Series. On the middle window we can see the pack. Right click and select Install. Once that is done we can go back to the default perspective, Window -> Open Perspective -> Others -> C/C++.
+When this finishes you must find the MCU which we will be building/debugging for. In this example I will be using the STM32F3 series MCUs. On the left, select STMicroelectronics -> STM32F3 Series. On the middle window we can see the pack. Right click and select Install. Once that is done we can go back to the default perspective, Window -> Perspective -> Open Perspective -> Other... -> C/C++.
 
-We need to let eclipse know the device we intent to build QMK on. Right click on the QMK folder -> Properties -> C/C++ Build -> Settings. Select the Devices tab and under devices select the appropriate variant of your MCU. For my example it is STM32F303CC
+We need to let eclipse know the device we intent to build QMK on. Right click on the QMK folder -> Properties -> C/C++ Build -> Settings. Select the Devices tab and under Devices select the appropriate variant of your MCU. For my example it is STM32F303CC
 
-While we are here let's setup the build command as well. Select C/C++ Build and then the Behavior tab. On the build command, replace `all` with your necessary make command. For example for a rev6 Planck with the default keymap this would be `planck/rev6:default`. Select Apply and Close.
+While we are here let's setup the build command as well. Select C/C++ Build and then the Behavior tab. On the Build command, replace `all` with your necessary make command. For example for a rev6 Planck with the default keymap this would be `planck/rev6:default`. Select Apply and Close.
 
 ## Building
 
@@ -71,7 +71,7 @@ NOTE: Make sure the SWCLK and SWDIO pins are not used in the matrix of your keyb
 
 ### Configuring the Debugger
 
-Right click on your QMK folder, select Debug As -> Debug Configuration. Here double click on GDB OpenOCD Debugging. Select the debugger tab and enter the configuration necessary for your MCU. This might take some fiddling and googleing to find out. The default script for the STM32F3 is called stm32f3discovery.cfg. To let OpenOCD know, in the Config options enter `-f board/stm32f3discovery.cfg`.
+Right click on your QMK folder, select Debug As -> Debug Configurations... . Here double click on GDB OpenOCD Debugging. Select the Debugger tab and enter the configuration necessary for your MCU. This might take some fiddling and Googling to find out. The default script for the STM32F3 is called `stm32f3discovery.cfg`. To let OpenOCD know, in the Config options enter `-f board/stm32f3discovery.cfg`.
 
 NOTE: In my case this configuration script requires editing to disable the reset assertion. The locations of the scripts can be found in the actual executable field usually under the path `openocd/version/.content/scripts/board`. Here I edited `reset_config srst_only` to `reset_config none`.
 
@@ -81,7 +81,7 @@ Select Apply and Close.
 
 Reset your keyboard.
 
-Press the bug icon and if all goes well you should soon find yourself in the debug perspective. Here the program counter will pause at the beginning of the main function and way for you to press Play. Most of the features of all debuggers work on ARM MCUs but for exact details google is your friend!
+Press the bug icon and if all goes well you should soon find yourself in the Debug perspective. Here the program counter will pause at the beginning of the main function and wait for you to press Play. Most of the features of all debuggers work on Arm MCUs but for exact details Google is your friend!
 
 
 Happy debugging!

docs/breaking_changes.md

@@ -10,16 +10,16 @@ The breaking change period is when we will merge PR's that change QMK in dangero
 
 ## When is the next Breaking Change?
 
-The next Breaking Change is scheduled for Nov 29.
+The next Breaking Change is scheduled for February 29, 2020.
 
 ### Important Dates
 
 * [x] 2019 Sep 21 - `future` is created. It will be rebased weekly.
-* [ ] 2019 Nov 01 - `future` closed to new PR's.
-* [ ] 2019 Nov 01 - Call for testers.
-* [ ] 2019 Nov 27 - `master` is locked, no PR's merged.
-* [ ] 2019 Nov 29 - Merge `future` to `master`.
-* [ ] 2019 Nov 30 - `master` is unlocked. PR's can be merged again.
+* [x] 2020 Feb 1 - `future` closed to new PR's.
+* [x] 2020 Feb 1 - Call for testers.
+* [ ] 2020 Feb 26 - `master` is locked, no PR's merged.
+* [ ] 2020 Feb 28 - Merge `future` to `master`.
+* [ ] 2020 Feb 29 - `master` is unlocked. PR's can be merged again.
 
 ## What changes will be included?
 

docs/breaking_changes_instructions.md

@@ -0,0 +1,42 @@
+# Breaking Changes: My Pull Request Was Flagged
+
+A QMK member may have replied to your pull request stating that your submission is a breaking change. In their judgment, the changes you have proposed have greater implications for either QMK, or its users.
+
+Some things that may cause a pull request to be flagged are:
+
+- **Edits to User Keymaps**
+  A user may submit their keymap to QMK, then some time later open a pull request with further updates, only to find it can't be merged because it was edited in the `qmk/qmk_firmware` repository. As not all users are proficient at using Git or GitHub, the user may find themself unable to fix the issue on their own.
+- **Changes to Expected Behavior**
+  Changes to QMK behavior may cause users to believe their hardware or QMK is broken if they flash new firmware that incorporates changes to existing QMK features, and find themselves without a means to restore the desired behavior.
+- **Changes Requiring User Action**
+  Changes may also require action to be taken by users, such as updating a toolchain or taking some action in Git.
+- **Changes Necessitating Increased Scrutiny**
+  On occasion, a submission may have implications for QMK as a project. This could be copyright/licensing issues, coding conventions, large feature overhauls, "high-risk" changes that need wider testing by our community, or something else entirely.
+- **Changes Requiring Communication to End Users**
+  This includes warnings about future deprecations, outdated practices, and anything else that needs to be communicated but doesn't fit into one of the above categories.
+
+## What Do I Do?
+
+If it is determined that your submission is a breaking change, there are a few things you can do to smooth the process:
+
+### Consider Splitting Up Your PR
+
+If you are contributing core code, and the only reason it needs to go through breaking changes is that you are updating keymaps to match your change, consider whether you can submit your feature in a way that the old keymaps continue to work. Then submit a separate PR that goes through the breaking changes process to remove the old code.
+
+### Contribute a ChangeLog Entry
+
+We require submissions that go through the Breaking Change process to include a changelog entry. The entry should be a short summary of the changes your pull request makes – [each section here started as a changelog](ChangeLog/20190830.md "n.b. This should link to the 2019 Aug 30 Breaking Changes doc  - @noroadsleft").
+
+Your changelog should be located at `docs/ChangeLog/YYYYMMDD/PR####.md`, where `YYYYMMDD` is the date on which QMK's breaking change branch – usually named `future` – will be merged into the `master` branch, and `####` is the number of your pull request.
+
+If your submission requires action on the part of users, your changelog should instruct users what action(s) must be taken, or link to a location that does so.
+
+### Document Your Changes
+
+Understanding the purpose for your submission, and possible implications or actions it will require can make the review process more straightforward. A changelog may suffice for this purpose, but more extensive changes may require a level of detail that is ill-suited for a changelog.
+
+Commenting on your pull request and being responsive to questions, comments, and change requests is much appreciated.
+
+### Ask for Help
+
+Having your submission flagged may have caught you off guard. If you find yourself intimidated or overwhelmed, let us know. Comment on your pull request, or [reach out to the QMK team on Discord](https://discord.gg/Uq7gcHh).

docs/cli.md

@@ -81,7 +81,7 @@ qmk cformat [file1] [file2] [...] [fileN]
 
 ## `qmk compile`
 
-This command allows you to compile firmware from any directory. You can compile JSON exports from <https://config.qmk.fm> or compile keymaps in the repo.
+This command allows you to compile firmware from any directory. You can compile JSON exports from <https://config.qmk.fm>, compile keymaps in the repo, or compile the keyboard in the current working directory.
 
 **Usage for Configurator Exports**:
 
@@ -95,6 +95,53 @@ qmk compile <configuratorExport.json>
 qmk compile -kb <keyboard_name> -km <keymap_name>
 ```
 
+**Usage in Keyboard Directory**:  
+
+Must be in keyboard directory with a default keymap, or in keymap directory for keyboard, or supply one with `--keymap <keymap_name>`
+```
+qmk compile
+```
+
+**Example**:
+```
+$ qmk config compile.keymap=default
+$ cd ~/qmk_firmware/keyboards/planck/rev6
+$ qmk compile
+Ψ Compiling keymap with make planck/rev6:default
+...
+```
+or with optional keymap argument
+
+```
+$ cd ~/qmk_firmware/keyboards/clueboard/66/rev4 
+$ qmk compile -km 66_iso
+Ψ Compiling keymap with make clueboard/66/rev4:66_iso
+...
+```
+or in keymap directory
+
+```
+$ cd ~/qmk_firmware/keyboards/gh60/satan/keymaps/colemak
+$ qmk compile
+Ψ Compiling keymap with make make gh60/satan:colemak
+...
+```
+
+**Usage in Layout Directory**:  
+
+Must be under `qmk_firmware/layouts/`, and in a keymap folder.
+```
+qmk compile -kb <keyboard_name>
+```
+
+**Example**:
+```
+$ cd ~/qmk_firmware/layouts/community/60_ansi/mechmerlin-ansi
+$ qmk compile -kb dz60
+Ψ Compiling keymap with make dz60:mechmerlin-ansi
+...
+```
+
 ## `qmk flash`
 
 This command is similar to `qmk compile`, but can also target a bootloader. The bootloader is optional, and is set to `:flash` by default.
@@ -141,14 +188,28 @@ qmk docs [-p PORT]
 
 ## `qmk doctor`
 
-This command examines your environment and alerts you to potential build or flash problems.
+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.
 
 **Usage**:
 
 ```
-qmk doctor
+qmk doctor [-y] [-n]
 ```
 
+**Examples**:
+
+Check your environment for problems and prompt to fix them:
+
+    qmk doctor
+
+Check your environment and automatically fix any problems found:
+
+    qmk doctor -y
+
+Check your environment and report problems only:
+
+    qmk doctor -n
+
 ## `qmk json-keymap`
 
 Creates a keymap.c from a QMK Configurator export.
@@ -191,6 +252,16 @@ This command lists all the keyboards currently defined in `qmk_firmware`
 qmk list-keyboards
 ```
 
+## `qmk list-keymaps`
+
+This command lists all the keymaps for a specified keyboard (and revision).
+
+**Usage**:
+
+```
+qmk list-keymaps -kb planck/ez
+```
+
 ## `qmk new-keymap`
 
 This command creates a new keymap based on a keyboard's existing default keymap.

docs/coding_conventions_python.md

@@ -309,6 +309,18 @@ FIXME(username): Revisit this code when the frob feature is done.
 
 ...where username is your GitHub username.
 
-# Unit Tests
+# Testing
 
-These are good. We should have some one day.
+We use a combination of Integration and Unit testing to ensure that the our code is as bug-free as possible. All the tests can be found in `lib/python/qmk/tests/`. You can run all the tests with `qmk pytest`.
+
+At the time of this writing our tests are not very comprehensive. Looking at the current tests and writing new test cases for untested situations is a great way to both familiarize yourself with the codebase and contribute to QMK.
+
+## 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.
+
+## Unit Tests
+
+The other `test_*.py` files in `lib/python/qmk/tests/` contain unit tests. You can write tests for individual functions inside `lib/python/qmk/` here. Generally these files are named after the module, with dots replaced by underscores.
+
+At the time of this writing we do not do any mocking for our tests. If you would like to help us change this please [open an issue](https://github.com/qmk/qmk_firmware/issues/new?assignees=&labels=cli%2C+python&template=other_issues.md&title=) or [join #cli on Discord](https://discord.gg/heQPAgy) and start a conversation there.

docs/config_options.md

@@ -53,6 +53,8 @@ This is a C header file that is one of the first things included, and will persi
   * pins of the rows, from top to bottom
 * `#define MATRIX_COL_PINS { F1, F0, B0, C7, F4, F5, F6, F7, D4, D6, B4, D7 }`
   * pins of the columns, from left to right
+* `#define MATRIX_IO_DELAY 30`
+  * the delay in microseconds when between changing matrix pin state and reading values
 * `#define UNUSED_PINS { D1, D2, D3, B1, B2, B3 }`
   * pins unused by the keyboard for reference
 * `#define MATRIX_HAS_GHOST`
@@ -78,7 +80,7 @@ This is a C header file that is one of the first things included, and will persi
 * `#define BACKLIGHT_PIN B7`
   * pin of the backlight
 * `#define BACKLIGHT_LEVELS 3`
-  * number of levels your backlight will have (maximum 15 excluding off)
+  * number of levels your backlight will have (maximum 31 excluding off)
 * `#define BACKLIGHT_BREATHING`
   * enables backlight breathing
 * `#define BREATHING_PERIOD 6`
@@ -143,10 +145,14 @@ If you define these options you will enable the associated feature, which may in
 * `#define IGNORE_MOD_TAP_INTERRUPT`
   * makes it possible to do rolling combos (zx) with keys that convert to other keys on hold, by enforcing the `TAPPING_TERM` for both keys.
   * See [Mod tap interrupt](feature_advanced_keycodes.md#ignore-mod-tap-interrupt) for details
+* `#define IGNORE_MOD_TAP_INTERRUPT_PER_KEY`
+  * enables handling for per key `IGNORE_MOD_TAP_INTERRUPT` settings
 * `#define TAPPING_FORCE_HOLD`
   * makes it possible to use a dual role key as modifier shortly after having been tapped
   * See [Hold after tap](feature_advanced_keycodes.md#tapping-force-hold)
   * Breaks any Tap Toggle functionality (`TT` or the One Shot Tap Toggle)
+* `#define TAPPING_FORCE_HOLD_PER_KEY`
+  * enables handling for per key `TAPPING_FORCE_HOLD` settings
 * `#define LEADER_TIMEOUT 300`
   * how long before the leader key times out
     * If you're having issues finishing the sequence before it times out, you may need to increase the timeout setting. Or you may want to enable the `LEADER_PER_KEY_TIMING` option, which resets the timeout after each key is tapped.
@@ -272,9 +278,12 @@ There are a few different ways to set handedness for split keyboards (listed in
   * Default behavior for ARM
   * Required for AVR Teensy
 
-* `#define SPLIT_USB_TIMEOUT 2500`
+* `#define SPLIT_USB_TIMEOUT 2000`
   * Maximum timeout when detecting master/slave when using `SPLIT_USB_DETECT`
 
+* `#define SPLIT_USB_TIMEOUT_POLL 10`
+  * Poll frequency when detecting master/slave when using `SPLIT_USB_DETECT`
+
 # The `rules.mk` File
 
 This is a [make](https://www.gnu.org/software/make/manual/make.html) file that is included by the top-level `Makefile`. It is used to set some information about the MCU that we will be compiling for as well as enabling and disabling certain features.
@@ -287,8 +296,27 @@ This is a [make](https://www.gnu.org/software/make/manual/make.html) file that i
   * Defines which format (bin, hex) is copied to the root `qmk_firmware` folder after building.
 * `SRC`
   * Used to add files to the compilation/linking list.
+* `LIB_SRC`
+  * Used to add files as a library to the compilation/linking list.  
+    The files specified by `LIB_SRC` is linked after the files specified by `SRC`.  
+    For example, if you specify:
+    ```
+    SRC += a.c
+    LIB_SRC += lib_b.c
+    SRC += c.c
+    LIB_SRC += lib_d.c
+    ```
+    The link order is as follows.
+    ```
+     ...  a.o c.o  ...  lib_b.a lib_d.a  ...
+    ```
 * `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`
+* `LTO_ENABLE`
+  * It 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`
@@ -347,9 +375,6 @@ Use these to enable or disable building certain features. The more you have enab
   * Forces the keyboard to wait for a USB connection to be established before it starts up
 * `NO_USB_STARTUP_CHECK`
   * Disables usb suspend check after keyboard startup. Usually the keyboard waits for the host to wake it up before any tasks are performed. This is useful for split keyboards as one half will not get a wakeup call but must send commands to the master.
-* `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`
-  * Alternatively, you can use `LTO_ENABLE` instead of `LINK_TIME_OPTIMIZATION_ENABLE`. 
 
 ## USB Endpoint Limitations
 

docs/custom_matrix.md

@@ -0,0 +1,108 @@
+# Custom Matrix
+
+QMK provides a mechanism to supplement or replace the default matrix scanning routine with your own code.
+
+The reasons to use this feature include:
+
+* Extra hardware between the keyboard's switches and MCU pins
+  * I/O multiplexer
+  * Line decoder
+* Irregular switch matrix
+  * Simultaneous use of `COL2ROW` and `ROW2COL`
+
+## Prerequisites
+
+Implementing custom matrix usually involves compilation of an additional source file. It is recommended that for consistency, this file is called `matrix.c`.
+
+Add a new file to your keyboard directory:
+```text
+keyboards/<keyboard>/matrix.c
+```
+
+And to configure compilation for the new file, add this to your `rules.mk`:
+```make
+SRC += matrix.c
+```
+
+## 'lite'
+
+Provides a default implementation for various scanning functions, reducing the boilerplate code when implementing custom matrix.
+To configure it, add this to your `rules.mk`:
+
+```make
+CUSTOM_MATRIX = lite
+```
+
+And implement the following functions in a `matrix.c` file in your keyboard folder:
+
+```c
+void matrix_init_custom(void) {
+    // TODO: initialize hardware here
+}
+
+bool matrix_scan_custom(matrix_row_t current_matrix[]) {
+    bool matrix_has_changed = false;
+
+    // TODO: add matrix scanning routine here
+
+    return matrix_has_changed;
+}
+```
+
+
+## Full Replacement
+
+When more control over the scanning routine is required, you can choose to implement the full scanning routine.
+To configure it, add this to your rules.mk:
+
+```make
+CUSTOM_MATRIX = yes
+```
+
+And implement the following functions in a `matrix.c` file in your keyboard folder:
+
+```c
+matrix_row_t matrix_get_row(uint8_t row) {
+    // TODO: return the requested row data
+}
+
+void matrix_print(void) {
+    // TODO: use print() to dump the current matrix state to console
+}
+
+void matrix_init(void) {
+    // TODO: initialize hardware and global matrix state here
+
+    // Unless hardware debouncing - Init the configured debounce routine
+    debounce_init(MATRIX_ROWS);
+
+    // This *must* be called for correct keyboard behavior
+    matrix_init_quantum();
+}
+
+uint8_t matrix_scan(void) {
+    bool matrix_has_changed = false;
+
+    // TODO: add matrix scanning routine here
+
+    // Unless hardware debouncing - use the configured debounce routine
+    debounce(raw_matrix, matrix, MATRIX_ROWS, changed);
+
+    // This *must* be called for correct keyboard behavior
+    matrix_scan_quantum();
+
+    return matrix_has_changed;
+}
+```
+
+And also provide defaults for the following callbacks:
+
+```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/custom_quantum_functions.md

@@ -489,14 +489,24 @@ The `val` is the value of the data that you want to write to EEPROM.  And the `e
 
 # Custom Tapping Term
 
-By default, the tapping term is defined globally, and is not configurable by key.  For most users, this is perfectly fine.  But in come cases, dual function keys would be greatly improved by different timeouts than `LT` keys, or because some keys may be easier to hold than others.  Instead of using custom key codes for each, this allows for per key configurable `TAPPING_TERM`.
+By default, the tapping term and related options (such as `IGNORE_MOD_TAP_INTERRUPT`) are defined globally, and are not configurable by key.  For most users, this is perfectly fine.  But in some cases, dual function keys would be greatly improved by different timeout behaviors than `LT` keys, or because some keys may be easier to hold than others.  Instead of using custom key codes for each, this allows for per key configurable timeout behaviors.
 
-To enable this functionality, you need to add `#define TAPPING_TERM_PER_KEY` to your `config.h`, first. 
+There are two configurable options to control per-key timeout behaviors:
+
+- `TAPPING_TERM_PER_KEY`
+- `IGNORE_MOD_TAP_INTERRUPT_PER_KEY`
+
+You need to add `#define` lines to your `config.h` for each feature you want.
+
+```
+#define TAPPING_TERM_PER_KEY
+#define IGNORE_MOD_TAP_INTERRUPT_PER_KEY
+```
 
 
 ## Example `get_tapping_term` Implementation
 
-To change the `TAPPING TERM` based on the keycode, you'd want to add something like the following to your `keymap.c` file: 
+To change the `TAPPING_TERM` based on the keycode, you'd want to add something like the following to your `keymap.c` file:
 
 ```c
 uint16_t get_tapping_term(uint16_t keycode) {
@@ -511,6 +521,21 @@ uint16_t get_tapping_term(uint16_t keycode) {
 }
 ```
 
-### `get_tapping_term` Function Documentation
+## Example `get_ignore_mod_tap_interrupt` Implementation
 
-Unlike many of the other functions here, there isn't a need (or even reason) to have a quantum or keyboard level function. Only a user level function is useful here, so no need to mark it as such.
+To change the `IGNORE_MOD_TAP_INTERRUPT` value based on the keycode, you'd want to add something like the following to your `keymap.c` file:
+
+```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` Function Documentation
+
+Unlike many of the other functions here, there isn't a need (or even reason) to have a quantum or keyboard level function. Only user level functions are useful here, so no need to mark them as such.

docs/eeprom_driver.md

@@ -0,0 +1,50 @@
+# EEPROM Driver Configuration
+
+The EEPROM driver can be swapped out depending on the needs of the keyboard, or whether extra hardware is present.
+
+Driver                      | Description
+--------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+`EEPROM_DRIVER = vendor`    | Uses the on-chip driver provided by the chip manufacturer. For AVR, this is provided by avr-libc. This is supported on ARM for a subset of chips -- STM32F3xx, STM32F1xx, and STM32F072xB will be emulated by writing to flash. Other chips will generally act as "transient" below.
+`EEPROM_DRIVER = i2c`       | Supports writing to I2C-based 24xx EEPROM chips. See the driver section below.
+`EEPROM_DRIVER = transient` | Fake EEPROM driver -- supports reading/writing to RAM, and will be discarded when power is lost.
+
+## Vendor Driver Configuration
+
+No configurable options are available.
+
+## I2C Driver Configuration
+
+Currently QMK supports 24xx-series chips over I2C. As such, requires a working i2c_master driver configuration. You can override the driver configuration via your config.h:
+
+`config.h` override                         | Description                                                                         | Default Value
+------------------------------------------- | ----------------------------------------------------------------------------------- | ------------------------------------
+`#define EXTERNAL_EEPROM_I2C_BASE_ADDRESS`  | Base I2C address for the EEPROM -- shifted left by 1 as per i2c_master requirements | 0b10100000
+`#define EXTERNAL_EEPROM_I2C_ADDRESS(addr)` | Calculated I2C address for the EEPROM                                               | `(EXTERNAL_EEPROM_I2C_BASE_ADDRESS)`
+`#define EXTERNAL_EEPROM_BYTE_COUNT`        | Total size of the EEPROM in bytes                                                   | 8192
+`#define EXTERNAL_EEPROM_PAGE_SIZE`         | Page size of the EEPROM in bytes, as specified in the datasheet                     | 32
+`#define EXTERNAL_EEPROM_ADDRESS_SIZE`      | The number of bytes to transmit for the memory location within the EEPROM           | 2
+`#define EXTERNAL_EEPROM_WRITE_TIME`        | Write cycle time of the EEPROM, as specified in the datasheet                       | 5
+
+Default values and extended descriptions can be found in `drivers/eeprom/eeprom_i2c.h`.
+
+Alternatively, there are pre-defined hardware configurations for available chips/modules:
+
+Module           | Equivalent `#define`            | Source
+-----------------|---------------------------------|------------------------------------------
+CAT24C512 EEPROM | `#define EEPROM_I2C_CAT24C512`  | <https://www.sparkfun.com/products/14764>
+RM24C512C EEPROM | `#define EEPROM_I2C_RM24C512C`  | <https://www.sparkfun.com/products/14764>
+24LC128 EEPROM   | `#define EEPROM_I2C_24LC128`    | <https://www.microchip.com/wwwproducts/en/24LC128>
+24LC256 EEPROM   | `#define EEPROM_I2C_24LC256`    | <https://www.sparkfun.com/products/525>
+MB85RC256V FRAM  | `#define EEPROM_I2C_MB85RC256V` | <https://www.adafruit.com/product/1895>
+
+?> If you find that the EEPROM is not cooperating, ensure you've correctly shifted up your EEPROM address by 1. For example, the datasheet might state the address as `0b01010000` -- the correct value of `EXTERNAL_EEPROM_I2C_BASE_ADDRESS` needs to be `0b10100000`.
+
+## Transient Driver configuration
+
+The only configurable item for the transient EEPROM driver is its size:
+
+`config.h` override             | Description                               | Default Value
+------------------------------- | ----------------------------------------- | -------------
+`#define TRANSIENT_EEPROM_SIZE` | Total size of the EEPROM storage in bytes | 64
+
+Default values and extended descriptions can be found in `drivers/eeprom/eeprom_transient.h`.

docs/faq_build.md

@@ -119,24 +119,29 @@ The solution is to remove and reinstall all affected modules.
 
 ```
 brew rm avr-gcc
+brew rm avr-gcc@8
 brew rm dfu-programmer
 brew rm dfu-util
 brew rm gcc-arm-none-eabi
+brew rm arm-gcc-bin@8
 brew rm avrdude
-brew install avr-gcc
+brew install avr-gcc@8
 brew install dfu-programmer
 brew install dfu-util
-brew install gcc-arm-none-eabi
+brew install arm-gcc-bin@8
 brew install avrdude
+brew link --force avr-gcc@8
+brew link --force arm-gcc-bin@8
+
 ```
 
-### avr-gcc 8.1 and LUFA
+### `avr-gcc` and LUFA
 
-If you updated your avr-gcc to above 7 you may see errors involving LUFA. For example:
+If you updated your `avr-gcc` and you see errors involving LUFA, for example:
 
 `lib/lufa/LUFA/Drivers/USB/Class/Device/AudioClassDevice.h:380:5: error: 'const' attribute on function returning 'void'`
 
-For now, you need to rollback avr-gcc to 7 in brew.
+For now, you need to rollback `avr-gcc` to 8 in Homebrew.
 
 ```
 brew uninstall --force avr-gcc

docs/feature_advanced_keycodes.md

@@ -291,6 +291,25 @@ Normally, this would send `X` (`SHIFT`+`x`). With `Ignore Mod Tap Interrupt` ena
 
 ?> If you have `Permissive Hold` enabled, as well, this will modify how both work. The regular key has the modifier added if the first key is released first or if both keys are held longer than the `TAPPING_TERM`.
 
+For more granular control of this feature, you can add the following to your `config.h`:
+
+```c
+#define IGNORE_MOD_TAP_INTERRUPT_PER_KEY
+```
+
+You can then add the following function to your keymap:
+
+```c
+bool get_ignore_mod_tap_interrupt(uint16_t keycode) {
+  switch (keycode) {
+    case SFT_T(KC_SPC):
+      return true;
+    default:
+      return false;
+  }
+}
+```
+
 ## Tapping Force Hold
 
 To enable `tapping force hold`, add the following to your `config.h`: 
@@ -315,6 +334,25 @@ With `TAPPING_FORCE_HOLD`, the second press will be interpreted as a Shift, allo
 
 !> `TAPPING_FORCE_HOLD` will break anything that uses tapping toggles (Such as the `TT` layer keycode, and the One Shot Tapping Toggle).
 
+For more granular control of this feature, you can add the following to your `config.h`:
+
+```c
+#define TAPPING_FORCE_HOLD_PER_KEY
+```
+
+You can then add the following function to your keymap:
+
+```c
+bool get_tapping_force_hold(uint16_t keycode, keyrecord_t *record) {
+  switch (keycode) {
+    case LT(1, KC_BSPC):
+      return true;
+    default:
+      return false;
+  }
+}
+```
+
 ## Retro Tapping
 
 To enable `retro tapping`, add the following to your `config.h`: 

docs/feature_backlight.md

@@ -167,7 +167,7 @@ BACKLIGHT_DRIVER = pwm
 
 Currently only hardware PWM is supported, not timer assisted, and does not provide automatic configuration.
 
-?> STMF072 support is being investigated.
+?> Backlight support for STMF072 has had limited testing, YMMV. If unsure, set `BACKLIGHT_ENABLE = no` in your rules.mk.
 
 ### ARM Configuration
 

docs/feature_oled_driver.md

@@ -1,139 +1,142 @@
 # OLED Driver
 
-## OLED Supported Hardware
+## Supported Hardware
 
 OLED modules using SSD1306 or SH1106 driver ICs, communicating over I2C.
 Tested combinations:
 
-| IC driver |   Size | Keyboard Platform | Notes                    |
-|-----------|--------|-------------------|--------------------------|
-| SSD1306   | 128x32 | AVR               | Primary support          |
-| SSD1306   | 128x64 | AVR               | Verified working         |
-| SSD1306   | 128x32 | ARM               |                          |
-| SH1106    | 128x64 | AVR               | No rotation or scrolling |
+|IC       |Size  |Platform|Notes                   |
+|---------|------|--------|------------------------|
+|SSD1306  |128x32|AVR     |Primary support         |
+|SSD1306  |128x64|AVR     |Verified working        |
+|SSD1306  |128x32|Arm     |                        |
+|SH1106   |128x64|AVR     |No rotation or scrolling|
 
-Hardware configurations using ARM-based microcontrollers or different sizes of OLED modules may be compatible, but are untested.
+Hardware configurations using Arm-based microcontrollers or different sizes of OLED modules may be compatible, but are untested.
 
-!> Warning: This OLED Driver currently uses the new i2c_master driver from split common code. If your split keyboard uses I2C to communicate between sides, this driver could cause an address conflict (serial is fine). Please contact your keyboard vendor and ask them to migrate to the latest split common code to fix this. In addition, the display timeout system to reduce OLED burn-in also uses split common to detect keypresses, so you will need to implement custom timeout logic for non-split common keyboards.
+!> Warning: This OLED driver currently uses the new i2c_master driver from Split Common code. If your split keyboard uses I2C to communicate between sides, this driver could cause an address conflict (serial is fine). Please contact your keyboard vendor and ask them to migrate to the latest Split Common code to fix this. In addition, the display timeout system to reduce OLED burn-in also uses Split Common to detect keypresses, so you will need to implement custom timeout logic for non-Split Common keyboards.
 
 ## Usage
 
-To enable the OLED feature, there are three steps. First, when compiling your keyboard, you'll need to set `OLED_DRIVER_ENABLE=yes` in `rules.mk`, e.g.:
+To enable the OLED feature, there are three steps. First, when compiling your keyboard, you'll need to add the following to your `rules.mk`:
 
-```
+```make
 OLED_DRIVER_ENABLE = yes
 ```
 
-This enables the feature and the `OLED_DRIVER_ENABLE` define. Then in your `keymap.c` file, you will need to implement the user task call, e.g:
+Then in your `keymap.c` file, implement the OLED task call. This example assumes your keymap has three layers named `_QWERTY`, `_FN` and `_ADJ`:
 
-```C++
+```c
 #ifdef OLED_DRIVER_ENABLE
 void oled_task_user(void) {
-  // Host Keyboard Layer Status
-  oled_write_P(PSTR("Layer: "), false);
-  switch (get_highest_layer(layer_state)) {
-    case _QWERTY:
-      oled_write_P(PSTR("Default\n"), false);
-      break;
-    case _FN:
-      oled_write_P(PSTR("FN\n"), false);
-      break;
-    case _ADJ:
-      oled_write_P(PSTR("ADJ\n"), false);
-      break;
-    default:
-      // Or use the write_ln shortcut over adding '\n' to the end of your string
-      oled_write_ln_P(PSTR("Undefined"), false);
-  }
+    // Host Keyboard Layer Status
+    oled_write_P(PSTR("Layer: "), false);
 
-  // Host Keyboard LED Status
-  uint8_t led_usb_state = host_keyboard_leds();
-  oled_write_P(led_usb_state & (1<<USB_LED_NUM_LOCK) ? PSTR("NUMLCK ") : PSTR("       "), false);
-  oled_write_P(led_usb_state & (1<<USB_LED_CAPS_LOCK) ? PSTR("CAPLCK ") : PSTR("       "), false);
-  oled_write_P(led_usb_state & (1<<USB_LED_SCROLL_LOCK) ? PSTR("SCRLCK ") : PSTR("       "), false);
+    switch (get_highest_layer(layer_state)) {
+        case _QWERTY:
+            oled_write_P(PSTR("Default\n"), false);
+            break;
+        case _FN:
+            oled_write_P(PSTR("FN\n"), false);
+            break;
+        case _ADJ:
+            oled_write_P(PSTR("ADJ\n"), false);
+            break;
+        default:
+            // Or use the write_ln shortcut over adding '\n' to the end of your string
+            oled_write_ln_P(PSTR("Undefined"), false);
+    }
+
+    // Host Keyboard LED Status
+    led_t led_state = host_keyboard_led_state();
+    oled_write_P(led_state.num_lock ? PSTR("NUM ") : PSTR("    "), false);
+    oled_write_P(led_state.caps_lock ? PSTR("CAP ") : PSTR("    "), false);
+    oled_write_P(led_state.scroll_lock ? PSTR("SCR ") : PSTR("    "), false);
 }
 #endif
 ```
 
 ## Logo Example
 
-In the default font, ranges in the font file are reserved for a QMK Logo. To Render this logo to the oled screen, use the following code example:
+In the default font, certain ranges of characters are reserved for a QMK logo. To render this logo to the OLED screen, use the following code example:
 
-```C++
+```c
 static void render_logo(void) {
-  static const char PROGMEM qmk_logo[] = {
-    0x80,0x81,0x82,0x83,0x84,0x85,0x86,0x87,0x88,0x89,0x8a,0x8b,0x8c,0x8d,0x8e,0x8f,0x90,0x91,0x92,0x93,0x94,
-    0xa0,0xa1,0xa2,0xa3,0xa4,0xa5,0xa6,0xa7,0xa8,0xa9,0xaa,0xab,0xac,0xad,0xae,0xaf,0xb0,0xb1,0xb2,0xb3,0xb4,
-    0xc0,0xc1,0xc2,0xc3,0xc4,0xc5,0xc6,0xc7,0xc8,0xc9,0xca,0xcb,0xcc,0xcd,0xce,0xcf,0xd0,0xd1,0xd2,0xd3,0xd4,0};
+    static const char PROGMEM qmk_logo[] = {
+        0x80, 0x81, 0x82, 0x83, 0x84, 0x85, 0x86, 0x87, 0x88, 0x89, 0x8A, 0x8B, 0x8C, 0x8D, 0x8E, 0x8F, 0x90, 0x91, 0x92, 0x93, 0x94,
+        0xA0, 0xA1, 0xA2, 0xA3, 0xA4, 0xA5, 0xA6, 0xA7, 0xA8, 0xA9, 0xAA, 0xAB, 0xAC, 0xAD, 0xAE, 0xAF, 0xB0, 0xB1, 0xB2, 0xB3, 0xB4,
+        0xC0, 0xC1, 0xC2, 0xC3, 0xC4, 0xC5, 0xC6, 0xC7, 0xC8, 0xC9, 0xCA, 0xCB, 0xCC, 0xCD, 0xCE, 0xCF, 0xD0, 0xD1, 0xD2, 0xD3, 0xD4, 0x00
+    };
 
-  oled_write_P(qmk_logo, false);
+    oled_write_P(qmk_logo, false);
 }
 ```
 
 ## Other Examples
 
-In split keyboards, it is very common to have two OLED displays that each render different content and oriented flipped differently. You can do this by switching which content to render by using the return from `is_keyboard_master()` or `is_keyboard_left()` found in `split_util.h`, e.g:
+In split keyboards, it is very common to have two OLED displays that each render different content and are oriented or flipped differently. You can do this by switching which content to render by using the return value from `is_keyboard_master()` or `is_keyboard_left()` found in `split_util.h`, e.g:
 
-```C++
+```c
 #ifdef OLED_DRIVER_ENABLE
 oled_rotation_t oled_init_user(oled_rotation_t rotation) {
-  if (!is_keyboard_master())
-    return OLED_ROTATION_180;  // flips the display 180 degrees if offhand
-  return rotation;
+    if (!is_keyboard_master()) {
+        return OLED_ROTATION_180;  // flips the display 180 degrees if offhand
+    }
+
+    return rotation;
 }
 
 void oled_task_user(void) {
-  if (is_keyboard_master()) {
-    render_status();     // Renders the current keyboard state (layer, lock, caps, scroll, etc)
-  } else {
-    render_logo();       // Renders a statuc logo
-    oled_scroll_left();  // Turns on scrolling
-  }
+    if (is_keyboard_master()) {
+        render_status();  // Renders the current keyboard state (layer, lock, caps, scroll, etc)
+    } else {
+        render_logo();  // Renders a static logo
+        oled_scroll_left();  // Turns on scrolling
+    }
 }
 #endif
 ```
 
+## Basic Configuration
 
- ## Basic Configuration
-
-| Define                     | Default           | Description                                                                                                                |
-|----------------------------|-------------------|----------------------------------------------------------------------------------------------------------------------------|
-| `OLED_DISPLAY_ADDRESS`     | `0x3C`            | The i2c address of the OLED Display                                                                                        |
-| `OLED_FONT_H`              | `"glcdfont.c"`    | The font code file to use for custom fonts                                                                                 |
-| `OLED_FONT_START`          | `0`               | The starting characer index for custom fonts                                                                               |
-| `OLED_FONT_END`            | `224`             | The ending characer index for custom fonts                                                                                 |
-| `OLED_FONT_WIDTH`          | `6`               | The font width                                                                                                             |
-| `OLED_FONT_HEIGHT`         | `8`               | The font height (untested)                                                                                                 |
-| `OLED_TIMEOUT`             | `60000`           | Turns off the OLED screen after 60000ms of keyboard inactivity. Helps reduce OLED Burn-in. Set to 0 to disable.            |
-| `OLED_SCROLL_TIMEOUT`      | `0`               | Scrolls the OLED screen after 0ms of OLED inactivity. Helps reduce OLED Burn-in. Set to 0 to disable.                      |
-| `OLED_SCROLL_TIMEOUT_RIGHT`| *Not defined*     | Scroll timeout direction is right when defined, left when undefined.                                                       |
-| `OLED_IC`                  | `OLED_IC_SSD1306` | Set to `OLED_IC_SH1106` if you're using the SH1106 OLED controller.                                                        |
-| `OLED_COLUMN_OFFSET`       | `0`               | (SH1106 only.) Shift output to the right this many pixels.<br />Useful for 128x64 displays centered on a 132x64 SH1106 IC. |
+|Define                     |Default          |Description                                                                                                               |
+|---------------------------|-----------------|--------------------------------------------------------------------------------------------------------------------------|
+|`OLED_DISPLAY_ADDRESS`     |`0x3C`           |The i2c address of the OLED Display                                                                                       |
+|`OLED_FONT_H`              |`"glcdfont.c"`   |The font code file to use for custom fonts                                                                                |
+|`OLED_FONT_START`          |`0`              |The starting characer index for custom fonts                                                                              |
+|`OLED_FONT_END`            |`223`            |The ending characer index for custom fonts                                                                                |
+|`OLED_FONT_WIDTH`          |`6`              |The font width                                                                                                            |
+|`OLED_FONT_HEIGHT`         |`8`              |The font height (untested)                                                                                                |
+|`OLED_TIMEOUT`             |`60000`          |Turns off the OLED screen after 60000ms of keyboard inactivity. Helps reduce OLED Burn-in. Set to 0 to disable.           |
+|`OLED_SCROLL_TIMEOUT`      |`0`              |Scrolls the OLED screen after 0ms of OLED inactivity. Helps reduce OLED Burn-in. Set to 0 to disable.                     |
+|`OLED_SCROLL_TIMEOUT_RIGHT`|*Not defined*    |Scroll timeout direction is right when defined, left when undefined.                                                      |
+|`OLED_IC`                  |`OLED_IC_SSD1306`|Set to `OLED_IC_SH1106` if you're using the SH1106 OLED controller.                                                       |
+|`OLED_COLUMN_OFFSET`       |`0`              |(SH1106 only.) Shift output to the right this many pixels.<br />Useful for 128x64 displays centered on a 132x64 SH1106 IC.|
 
  ## 128x64 & Custom sized OLED Displays
 
  The default display size for this feature is 128x32 and all necessary defines are precalculated with that in mind. We have added a define, `OLED_DISPLAY_128X64`, to switch all the values to be used in a 128x64 display, as well as added a custom define, `OLED_DISPLAY_CUSTOM`, that allows you to provide the necessary values to the driver.
 
-|Define                 |Default        |Description                                                      |
-|-----------------------|---------------|-----------------------------------------------------------------|
-|`OLED_DISPLAY_128X64`  |*Not defined*  |Changes the display defines for use with 128x64 displays.        |
-|`OLED_DISPLAY_CUSTOM`  |*Not defined*  |Changes the display defines for use with custom displays.<br />Requires user to implement the below defines. |
-|`OLED_DISPLAY_WIDTH`   |`128`          |The width of the OLED display.                                   |
-|`OLED_DISPLAY_HEIGHT`  |`32`           |The height of the OLED display.                                  |
-|`OLED_MATRIX_SIZE`     |`512`          |The local buffer size to allocate.<br />`(OLED_DISPLAY_HEIGHT / 8 * OLED_DISPLAY_WIDTH)`. |
-|`OLED_BLOCK_TYPE`      |`uint16_t`     |The unsigned integer type to use for dirty rendering. |
-|`OLED_BLOCK_COUNT`     |`16`           |The number of blocks the display is divided into for dirty rendering.<br />`(sizeof(OLED_BLOCK_TYPE) * 8)`. |
-|`OLED_BLOCK_SIZE`      |`32`           |The size of each block for dirty rendering<br />`(OLED_MATRIX_SIZE / OLED_BLOCK_COUNT)`. |
-|`OLED_COM_PINS`        |`COM_PINS_SEQ` |How the SSD1306 chip maps it's memory to display.<br />Options are `COM_PINS_SEQ`, `COM_PINS_ALT`, `COM_PINS_SEQ_LR`, & `COM_PINS_ALT_LR`. |
-|`OLED_SOURCE_MAP`      |`{ 0, ... N }` |Precalculated source array to use for mapping source buffer to target OLED memory in 90 degree rendering.         |
-|`OLED_TARGET_MAP`      |`{ 24, ... N }`|Precalculated target array to use for mapping source buffer to target OLED memory in 90 degree rendering.         |
+|Define               |Default        |Description                                                                                                                             |
+|---------------------|---------------|----------------------------------------------------------------------------------------------------------------------------------------|
+|`OLED_DISPLAY_128X64`|*Not defined*  |Changes the display defines for use with 128x64 displays.                                                                               |
+|`OLED_DISPLAY_CUSTOM`|*Not defined*  |Changes the display defines for use with custom displays.<br>Requires user to implement the below defines.                              |
+|`OLED_DISPLAY_WIDTH` |`128`          |The width of the OLED display.                                                                                                          |
+|`OLED_DISPLAY_HEIGHT`|`32`           |The height of the OLED display.                                                                                                         |
+|`OLED_MATRIX_SIZE`   |`512`          |The local buffer size to allocate.<br>`(OLED_DISPLAY_HEIGHT / 8 * OLED_DISPLAY_WIDTH)`.                                                 |
+|`OLED_BLOCK_TYPE`    |`uint16_t`     |The unsigned integer type to use for dirty rendering.                                                                                   |
+|`OLED_BLOCK_COUNT`   |`16`           |The number of blocks the display is divided into for dirty rendering.<br>`(sizeof(OLED_BLOCK_TYPE) * 8)`.                               |
+|`OLED_BLOCK_SIZE`    |`32`           |The size of each block for dirty rendering<br>`(OLED_MATRIX_SIZE / OLED_BLOCK_COUNT)`.                                                  |
+|`OLED_COM_PINS`      |`COM_PINS_SEQ` |How the SSD1306 chip maps it's memory to display.<br>Options are `COM_PINS_SEQ`, `COM_PINS_ALT`, `COM_PINS_SEQ_LR`, & `COM_PINS_ALT_LR`.|
+|`OLED_SOURCE_MAP`    |`{ 0, ... N }` |Precalculated source array to use for mapping source buffer to target OLED memory in 90 degree rendering.                               |
+|`OLED_TARGET_MAP`    |`{ 24, ... N }`|Precalculated target array to use for mapping source buffer to target OLED memory in 90 degree rendering.                               |
 
 
-### 90 Degree Rotation - Technical Mumbo Jumbo 
+### 90 Degree Rotation - Technical Mumbo Jumbo
 
 !> Rotation is unsupported on the SH1106.
 
-```C
+```c
 // OLED Rotation enum values are flags
 typedef enum {
     OLED_ROTATION_0   = 0,
@@ -143,9 +146,9 @@ typedef enum {
 } oled_rotation_t;
 ```
 
- OLED displays driven by SSD1306 drivers only natively support in hard ware 0 degree and 180 degree rendering. This feature is done in software and not free. Using this feature will increase the time to calculate what data to send over i2c to the OLED. If you are strapped for cycles, this can cause keycodes to not register. In testing however, the rendering time on an `atmega32u4` board only went from 2ms to 5ms and keycodes not registering was only noticed once we hit 15ms. 
- 
- 90 Degree Rotated Rendering is achieved by using bitwise operations to rotate each 8 block of memory and uses two precalculated arrays to remap buffer memory to OLED memory. The memory map defines are precalculated for remap performance and are calculated based on the OLED Height, Width, and Block Size. For example, in the 128x32 implementation with a `uint8_t` block type, we have a 64 byte block size. This gives us eight 8 byte blocks that need to be rotated and rendered. The OLED renders horizontally two 8 byte blocks before moving down a page, e.g:
+OLED displays driven by SSD1306 drivers only natively support in hardware 0 degree and 180 degree rendering. This feature is done in software and not free. Using this feature will increase the time to calculate what data to send over i2c to the OLED. If you are strapped for cycles, this can cause keycodes to not register. In testing however, the rendering time on an ATmega32U4 board only went from 2ms to 5ms and keycodes not registering was only noticed once we hit 15ms.
+
+90 degree rotation is achieved by using bitwise operations to rotate each 8 block of memory and uses two precalculated arrays to remap buffer memory to OLED memory. The memory map defines are precalculated for remap performance and are calculated based on the display height, width, and block size. For example, in the 128x32 implementation with a `uint8_t` block type, we have a 64 byte block size. This gives us eight 8 byte blocks that need to be rotated and rendered. The OLED renders horizontally two 8 byte blocks before moving down a page, e.g:
 
 |   |   |   |   |   |   |
 |---|---|---|---|---|---|
@@ -167,8 +170,8 @@ So those precalculated arrays just index the memory offsets in the order in whic
 
 ## OLED API
 
-```C++
-// OLED Rotation enum values are flags
+```c
+// OLED rotation enum values are flags
 typedef enum {
     OLED_ROTATION_0   = 0,
     OLED_ROTATION_90  = 1,
@@ -272,26 +275,26 @@ uint8_t oled_max_lines(void);
 
 !> Scrolling and rotation are unsupported on the SH1106.
 
-## SSD1306.h driver conversion guide
+## SSD1306.h Driver Conversion Guide
 
-|Old API                    |Recommended New API                |
-|---------------------------|-----------------------------------|
-|`struct CharacterMatrix`   |*removed - delete all references*  |
-|`iota_gfx_init`            |`oled_init`                        |
-|`iota_gfx_on`              |`oled_on`                          |
-|`iota_gfx_off`             |`oled_off`                         |
-|`iota_gfx_flush`           |`oled_render`                      |
-|`iota_gfx_write_char`      |`oled_write_char`                  |
-|`iota_gfx_write`           |`oled_write`                       |
-|`iota_gfx_write_P`         |`oled_write_P`                     |
-|`iota_gfx_clear_screen`    |`oled_clear`                       |
-|`matrix_clear`             |*removed - delete all references*  |
-|`matrix_write_char_inner`  |`oled_write_char`                  |
-|`matrix_write_char`        |`oled_write_char`                  |
-|`matrix_write`             |`oled_write`                       |
-|`matrix_write_ln`          |`oled_write_ln`                    |
-|`matrix_write_P`           |`oled_write_P`                     |
-|`matrix_write_ln_P`        |`oled_write_ln_P`                  |
-|`matrix_render`            |`oled_render`                      |
-|`iota_gfx_task`            |`oled_task`                        |
-|`iota_gfx_task_user`       |`oled_task_user`                   |
+|Old API                  |Recommended New API              |
+|-------------------------|---------------------------------|
+|`struct CharacterMatrix` |*removed - delete all references*|
+|`iota_gfx_init`          |`oled_init`                      |
+|`iota_gfx_on`            |`oled_on`                        |
+|`iota_gfx_off`           |`oled_off`                       |
+|`iota_gfx_flush`         |`oled_render`                    |
+|`iota_gfx_write_char`    |`oled_write_char`                |
+|`iota_gfx_write`         |`oled_write`                     |
+|`iota_gfx_write_P`       |`oled_write_P`                   |
+|`iota_gfx_clear_screen`  |`oled_clear`                     |
+|`matrix_clear`           |*removed - delete all references*|
+|`matrix_write_char_inner`|`oled_write_char`                |
+|`matrix_write_char`      |`oled_write_char`                |
+|`matrix_write`           |`oled_write`                     |
+|`matrix_write_ln`        |`oled_write_ln`                  |
+|`matrix_write_P`         |`oled_write_P`                   |
+|`matrix_write_ln_P`      |`oled_write_ln_P`                |
+|`matrix_render`          |`oled_render`                    |
+|`iota_gfx_task`          |`oled_task`                      |
+|`iota_gfx_task_user`     |`oled_task_user`                 |

docs/feature_rgb_matrix.md

@@ -199,6 +199,7 @@ enum rgb_matrix_effects {
     RGB_MATRIX_SOLID_COLOR = 1,     // Static single hue, no speed support
     RGB_MATRIX_ALPHAS_MODS,         // Static dual hue, speed is hue for secondary hue
     RGB_MATRIX_GRADIENT_UP_DOWN,    // Static gradient top to bottom, speed controls how much gradient changes
+    RGB_MATRIX_GRADIENT_LEFT_RIGHT,    // Static gradient left to right, speed controls how much gradient changes
     RGB_MATRIX_BREATHING,           // Single hue brightness cycling animation
     RGB_MATRIX_BAND_SAT,        // Single hue band fading saturation scrolling left to right
     RGB_MATRIX_BAND_VAL,        // Single hue band fading brightness scrolling left to right
@@ -379,6 +380,10 @@ These are defined in [`rgblight_list.h`](https://github.com/qmk/qmk_firmware/blo
 #define RGB_MATRIX_LED_FLUSH_LIMIT 16 // limits in milliseconds how frequently an animation will update the LEDs. 16 (16ms) is equivalent to limiting to 60fps (increases keyboard responsiveness)
 #define RGB_MATRIX_MAXIMUM_BRIGHTNESS 200 // limits maximum brightness of LEDs to 200 out of 255. If not defined maximum brightness is set to 255
 #define RGB_MATRIX_STARTUP_MODE RGB_MATRIX_CYCLE_LEFT_RIGHT // Sets the default mode, if none has been set
+#define RGB_MATRIX_STARTUP_HUE 0 // Sets the default hue value, if none has been set
+#define RGB_MATRIX_STARTUP_SAT 255 // Sets the default saturation value, if none has been set
+#define RGB_MATRIX_STARTUP_VAL RGB_MATRIX_MAXIMUM_BRIGHTNESS // Sets the default brightness value, if none has been set
+#define RGB_MATRIX_STARTUP_SPD 127 // Sets the default animation speed, if none has been set
 ```
 
 ## EEPROM storage

docs/feature_split_keyboard.md

@@ -198,10 +198,15 @@ This option changes the startup behavior to detect an active USB connection when
 ?> This setting will stop the ability to demo using battery packs.
 
 ```c
-#define SPLIT_USB_TIMEOUT 2500
+#define SPLIT_USB_TIMEOUT 2000
 ```
 This sets the maximum timeout when detecting master/slave when using `SPLIT_USB_DETECT`.
 
+```c
+#define SPLIT_USB_TIMEOUT_POLL 10
+```
+This sets the poll frequency when detecting master/slave when using `SPLIT_USB_DETECT`
+
 ## Additional Resources
 
 Nicinabox has a [very nice and detailed guide](https://github.com/nicinabox/lets-split-guide) for the Let's Split keyboard, that covers most everything you need to know, including troubleshooting information. 

docs/fr-fr/getting_started_github.md

@@ -16,17 +16,23 @@ Faites attention à sélectionner "HTTPS", et sélectionnez le lien et copiez-le
 
 ![HTTPS link](http://i.imgur.com/eGO0ohO.jpg)
 
-Ensuite, entrez `git clone` dans la ligne de commande, et collez votre lien:
+Ensuite, entrez `git clone --recurse-submodules ` dans la ligne de commande, et collez votre lien:
 
 ```
-user@computer:~$ git clone https://github.com/whoeveryouare/qmk_firmware.git
+user@computer:~$ git clone --recurse-submodules https://github.com/whoeveryouare/qmk_firmware.git
 Cloning into 'qmk_firmware'...
-remote: Counting objects: 46625, done.
-remote: Compressing objects: 100% (2/2), done.
-remote: Total 46625 (delta 0), reused 0 (delta 0), pack-reused 46623
-Receiving objects: 100% (46625/46625), 84.47 MiB | 3.14 MiB/s, done.
-Resolving deltas: 100% (29362/29362), done.
-Checking out files: 100% (2799/2799), done.
+remote: Enumerating objects: 9, done.
+remote: Counting objects: 100% (9/9), done.
+remote: Compressing objects: 100% (5/5), done.
+remote: Total 183883 (delta 5), reused 4 (delta 4), pack-reused 183874
+Receiving objects: 100% (183883/183883), 132.90 MiB | 9.57 MiB/s, done.
+Resolving deltas: 100% (119972/119972), done.
+...
+Submodule path 'lib/chibios': checked out '587968d6cbc2b0e1c7147540872f2a67e59ca18b'
+Submodule path 'lib/chibios-contrib': checked out 'ede48346eee4b8d6847c19bc01420bee76a5e486'
+Submodule path 'lib/googletest': checked out 'ec44c6c1675c25b9827aacd08c02433cccde7780'
+Submodule path 'lib/lufa': checked out 'ce10f7642b0459e409839b23cc91498945119b4d'
+Submodule path 'lib/ugfx': checked out '3e97b74e03c93631cdd3ddb2ce43b963fdce19b2'
 ```
 
 Vous avez maintenant votre fork QMK sur votre machine locale, vous pouvez ajouter votre keymap, la compiler et la flasher sur votre board. Une fois heureux avec vos changements, vous pouvez les ajouter, commit, et pousser vers votre fork comme suit:

docs/fr-fr/getting_started_introduction.md

@@ -4,7 +4,7 @@ Le but de cette page est d'expliquer les informations de base qui vous serons n
 
 ## Structure de base de QMK
 
-QMK est un fork du projet [tmk_keyboard](https://github.com/tmk/tmk_keyboard) créé par [Jun Wako](https://github.com/tmk). Le code originel de TMK, avec quelques modifications, se trouve dans le dossier `tmk`. Les additions que QMK amène au projet se trouvent dans le dossier `quantum`. Les projets de clavier se trouvent dans les dossiers `handwired` et `keyboard`.
+QMK est un fork du projet [tmk_keyboard](https://github.com/tmk/tmk_keyboard) créé par [Jun Wako](https://github.com/tmk). Le code originel de TMK, avec quelques modifications, se trouve dans le dossier `tmk_core`. Les additions que QMK amène au projet se trouvent dans le dossier `quantum`. Les projets de clavier se trouvent dans les dossiers `handwired` et `keyboard`.
 
 ### Structure du Userspace
 

docs/getting_started_build_tools.md

@@ -43,7 +43,7 @@ Debian / Ubuntu example:
 Fedora / Red Hat example:
 
     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 example:
 
     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
@@ -57,16 +57,17 @@ By default, this will download compilers for both AVR and ARM. If you don't need
     nix-shell --arg arm false
 
 ## macOS
-If you're using [homebrew,](http://brew.sh/) you can use the following commands:
+If you're using [Homebrew](http://brew.sh/), you can use the following commands:
 
     brew tap osx-cross/avr
-    brew tap PX4/homebrew-px4
+    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 gcc-arm-none-eabi
+    brew install arm-gcc-bin@8
+    brew link --force arm-gcc-bin@8
     brew install avrdude
 
 This is the recommended method. If you don't have homebrew, [install it!](http://brew.sh/) It's very much worth it for anyone who works in the command line. Note that the `make` and `make install` portion during the homebrew installation of `avr-gcc@8` can take over 20 minutes and exhibit high CPU usage.
@@ -119,12 +120,12 @@ If this is a bit complex for you, Docker might be the turnkey solution you need.
 util/docker_build.sh keyboard:keymap
 # For example: util/docker_build.sh ergodox_ez:steno
 ```
-This will compile the desired keyboard/keymap and leave the resulting `.hex` or `.bin` file in the QMK directory for you to flash. If `:keymap` is omitted, the `default` keymap is used. Note that the parameter format is the same as when building with `make`.
+This will compile the desired keyboard/keymap and leave the resulting `.hex` or `.bin` file in the QMK directory for you to flash. If `:keymap` is omitted, all keymaps are used. Note that the parameter format is the same as when building with `make`.
 
 You can also start the script without any parameters, in which case it will ask you to input the build parameters one by one, which you may find easier to use:
 ```bash
 util/docker_build.sh
-# Reads parameters as input (leave blank for defaults)
+# Reads parameters as input (leave blank for all keyboards/keymaps)
 ```
 
 There is also support for building _and_ flashing the keyboard straight from Docker by specifying the `target` as well:

docs/getting_started_github.md

@@ -16,17 +16,23 @@ And be sure to select "HTTPS", and select the link and copy it:
 
 ![HTTPS link](http://i.imgur.com/eGO0ohO.jpg)
 
-From here, enter `git clone ` into the command line, and then paste your link:
+From here, enter `git clone --recurse-submodules ` into the command line, and then paste your link:
 
 ```
 user@computer:~$ git clone --recurse-submodules https://github.com/whoeveryouare/qmk_firmware.git
 Cloning into 'qmk_firmware'...
-remote: Counting objects: 46625, done.
-remote: Compressing objects: 100% (2/2), done.
-remote: Total 46625 (delta 0), reused 0 (delta 0), pack-reused 46623
-Receiving objects: 100% (46625/46625), 84.47 MiB | 3.14 MiB/s, done.
-Resolving deltas: 100% (29362/29362), done.
-Checking out files: 100% (2799/2799), done.
+remote: Enumerating objects: 9, done.
+remote: Counting objects: 100% (9/9), done.
+remote: Compressing objects: 100% (5/5), done.
+remote: Total 183883 (delta 5), reused 4 (delta 4), pack-reused 183874
+Receiving objects: 100% (183883/183883), 132.90 MiB | 9.57 MiB/s, done.
+Resolving deltas: 100% (119972/119972), done.
+...
+Submodule path 'lib/chibios': checked out '587968d6cbc2b0e1c7147540872f2a67e59ca18b'
+Submodule path 'lib/chibios-contrib': checked out 'ede48346eee4b8d6847c19bc01420bee76a5e486'
+Submodule path 'lib/googletest': checked out 'ec44c6c1675c25b9827aacd08c02433cccde7780'
+Submodule path 'lib/lufa': checked out 'ce10f7642b0459e409839b23cc91498945119b4d'
+Submodule path 'lib/ugfx': checked out '3e97b74e03c93631cdd3ddb2ce43b963fdce19b2'
 ```
 
 You now have your QMK fork on your local machine, and you can add your keymap, compile it and flash it to your board. Once you're happy with your changes, you can add, commit, and push them to your fork like this:

docs/getting_started_make_guide.md

@@ -135,7 +135,7 @@ As there is no standard split communication driver for ARM-based split keyboards
 
 `CUSTOM_MATRIX`
 
-Lets you replace the default matrix scanning routine with your own code. You will need to provide your own implementations of matrix_init() and matrix_scan().
+Lets you replace the default matrix scanning routine with your own code. For further details, see the [Custom Matrix page](custom_matrix.md).
 
 `DEBOUNCE_TYPE`
 

docs/hardware_drivers.md

@@ -33,3 +33,7 @@ Support for up to 2 drivers. Each driver impliments 2 charlieplex matrices to in
 ## IS31FL3733
 
 Support for up to a single driver with room for expansion. Each driver can control 192 individual LEDs or 64 RGB LEDs. For more information on how to setup the driver see the [RGB Matrix](feature_rgb_matrix.md) page.
+
+## 24xx series external I2C EEPROM
+
+Support for an external I2C-based EEPROM instead of using the on-chip EEPROM. For more information on how to setup the driver see the [EEPROM Driver](eeprom_driver.md) page.

docs/he-il/getting_started_github.md

@@ -17,19 +17,25 @@ Github עלול להיות קצת טריקי למי שלא מכיר את העב
 
 ![קישור HTTPS](http://i.imgur.com/eGO0ohO.jpg)
 
-מכאן והלאה, הקיש `git clone ` בשורת הפקודה והדביקו את הלינק שלכם:
+מכאן והלאה, הקיש `git clone --recurse-submodules ` בשורת הפקודה והדביקו את הלינק שלכם:
 
 <div dir="ltr" markdown="1">
 
 ```
-user@computer:~$ git clone https://github.com/whoeveryouare/qmk_firmware.git
+user@computer:~$ git clone --recurse-submodules https://github.com/whoeveryouare/qmk_firmware.git
 Cloning into 'qmk_firmware'...
-remote: Counting objects: 46625, done.
-remote: Compressing objects: 100% (2/2), done.
-remote: Total 46625 (delta 0), reused 0 (delta 0), pack-reused 46623
-Receiving objects: 100% (46625/46625), 84.47 MiB | 3.14 MiB/s, done.
-Resolving deltas: 100% (29362/29362), done.
-Checking out files: 100% (2799/2799), done.
+remote: Enumerating objects: 9, done.
+remote: Counting objects: 100% (9/9), done.
+remote: Compressing objects: 100% (5/5), done.
+remote: Total 183883 (delta 5), reused 4 (delta 4), pack-reused 183874
+Receiving objects: 100% (183883/183883), 132.90 MiB | 9.57 MiB/s, done.
+Resolving deltas: 100% (119972/119972), done.
+...
+Submodule path 'lib/chibios': checked out '587968d6cbc2b0e1c7147540872f2a67e59ca18b'
+Submodule path 'lib/chibios-contrib': checked out 'ede48346eee4b8d6847c19bc01420bee76a5e486'
+Submodule path 'lib/googletest': checked out 'ec44c6c1675c25b9827aacd08c02433cccde7780'
+Submodule path 'lib/lufa': checked out 'ce10f7642b0459e409839b23cc91498945119b4d'
+Submodule path 'lib/ugfx': checked out '3e97b74e03c93631cdd3ddb2ce43b963fdce19b2'
 ```
 
 </div>
@@ -66,4 +72,4 @@ To https://github.com/whoeveryouare/qmk_firmware.git
 ![צרו Pull Request](http://i.imgur.com/Ojydlaj.jpg)
 
 אחרי שהגשתם, אנו עלולים לפנות אליכם לגבי השינויים שהצעתם, נבקש שתבצעו שינויים ובסופו של דבר נקבל את השינויים! תודה שתרמתם לפרוייקט QMK :)
-</div>
+</div>

docs/he-il/getting_started_introduction.md

@@ -5,7 +5,7 @@
 
 ## מבנה QMK בסיסי
 
-QMK הוא פורק של הפרוייקט [tmk_keyboard](https://github.com/tmk/tmk_keyboard) של [Jun Wako](https://github.com/tmk). קוד הTMK המקורי, עם התאמות, יכול להמצא בתיקיית `tmk`. התוספות של QMK לפרוייקט יכולות להמצא בתיקיית `quantum`. פרוייקטי מקלדות יכולות להמצא בתיקיות `handwired` ו- `keyboard`.
+QMK הוא פורק של הפרוייקט [tmk_keyboard](https://github.com/tmk/tmk_keyboard) של [Jun Wako](https://github.com/tmk). קוד הTMK המקורי, עם התאמות, יכול להמצא בתיקיית `tmk_core`. התוספות של QMK לפרוייקט יכולות להמצא בתיקיית `quantum`. פרוייקטי מקלדות יכולות להמצא בתיקיות `handwired` ו- `keyboard`.
 
 ### מבנה אחסון המשתמש
 
@@ -69,4 +69,4 @@ In every keymap folder, the following files may be found. Only `keymap.c` is req
 ```
 
 </div>
-</div>
+</div>

docs/he-il/quantum_keycodes.md

@@ -17,18 +17,8 @@
 |`DEBUG`        |           |Toggle debug mode                                                    |
 |`EEPROM_RESET` |`EEP_RST`  |Resets EEPROM state by reinitializing it                             |
 |`KC_GESC`      |`GRAVE_ESC`|Escape when tapped, <code>&#96;</code> when pressed with Shift or GUI|
-|`KC_LSPO`      |           |Left Shift when held, `(` when tapped                                |
-|`KC_RSPC`      |           |Right Shift when held, `)` when tapped                               |
-|`KC_LCPO`      |           |Left Control when held, `(` when tapped                              |
-|`KC_RCPC`      |           |Right Control when held, `)` when tapped                             |
-|`KC_LAPO`      |           |Left Alt when held, `(` when tapped                                  |
-|`KC_RAPC`      |           |Right Alt when held, `)` when tapped                                 |
-|`KC_SFTENT`    |           |Right Shift when held, Enter when tapped                             |
 |`KC_LEAD`      |           |The [Leader key](feature_leader_key.md)                              |
 |`KC_LOCK`      |           |The [Lock key](feature_key_lock.md)                                  |
-|`FUNC(n)`      |`F(n)`     |Call `fn_action(n)` (deprecated)                                     |
-|`M(n)`         |           |Call macro `n`                                                       |
-|`MACROTAP(n)`  |           |Macro-tap `n` idk FIXME                                              |
 ```
 
 </div>

docs/ja/README.md

@@ -2,7 +2,7 @@
 
 <!---
   original document: eae21eed7:docs/README.md
-  git diff eae21eed7 HEAD docs/README.md | cat
+  git diff eae21eed7 HEAD -- docs/README.md | cat
 -->
 
 [![現在のバージョン](https://img.shields.io/github/tag/qmk/qmk_firmware.svg)](https://github.com/qmk/qmk_firmware/tags)

docs/ja/_summary.md

@@ -3,36 +3,41 @@
    * [初めてのファームウェアの構築](ja/newbs_building_firmware.md)
    * [ファームウェアのフラッシュ](ja/newbs_flashing.md)
    * [テストとデバッグ](ja/newbs_testing_debugging.md)
-   * [Gitのベストプラクティス](ja/newbs_best_practices.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)
 
 * [QMKの基本](ja/README.md)
-   * [QMKの導入](ja/getting_started_introduction.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)
+   * [QMK への貢献](ja/contributing.md)
+   * [Github の使い方](ja/getting_started_github.md)
    * [ヘルプ](ja/getting_started_getting_help.md)
 
 * [破壊的な変更](ja/breaking_changes.md)
+   * [プルリクエストにフラグが付けられた](ja/breaking_changes_instructions.md)
    * [2019年8月30日](ja/ChangeLog/20190830.md)
 
 * [FAQ](ja/faq.md)
-   * [一般的なFAQ](ja/faq_general.md)
-   * [QMKのビルド/コンパイル](ja/faq_build.md)
-   * [QMKのデバッグ/トラブルシューティング](ja/faq_debug.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)
+   * [Zadig を使ったドライバのインストール](ja/driver_installation_zadig.md)
 
 * 詳細なガイド
    * [ビルドツールのインストール](ja/getting_started_build_tools.md)
-   * [Vagrantのガイド](ja/getting_started_vagrant.md)
+   * [Vagrant のガイド](ja/getting_started_vagrant.md)
    * [ビルド/コンパイルの説明](ja/getting_started_make_guide.md)
    * [ファームウェアのフラッシュ](ja/flashing.md)
    * [機能のカスタマイズ](ja/custom_quantum_functions.md)
    * [キーマップの概要](ja/keymap.md)
 
 * [ハードウェア](ja/hardware.md)
+   * [互換性のあるマイクロコントローラ](ja/compatible_microcontrollers.md)
    * [AVR プロセッサ](ja/hardware_avr.md)
    * [ドライバ](ja/hardware_drivers.md)
 
@@ -63,7 +68,7 @@
    * [ブートマジック](ja/feature_bootmagic.md)
    * [コンボ](ja/feature_combo.md)
    * [コマンド](ja/feature_command.md)
-   * [Debounce API](ja/feature_debounce_type.md)
+   * [デバウンス API](ja/feature_debounce_type.md)
    * [DIP スイッチ](ja/feature_dip_switch.md)
    * [動的マクロ](ja/feature_dynamic_macros.md)
    * [エンコーダ](ja/feature_encoders.md)
@@ -87,27 +92,31 @@
    * [Stenography](ja/feature_stenography.md)
    * [Swap Hands](ja/feature_swap_hands.md)
    * [タップ ダンス](ja/feature_tap_dance.md)
-   * [Terminal](ja/feature_terminal.md)
+   * [ターミナル](ja/feature_terminal.md)
    * [感熱式プリンタ](ja/feature_thermal_printer.md)
    * [ユニコード](ja/feature_unicode.md)
-   * [Userspace](ja/feature_userspace.md)
+   * [ユーザスペース](ja/feature_userspace.md)
    * [Velocikey](ja/feature_velocikey.md)
 
 * メーカーおよびモッダーのために
-   * [Hand Wiring Guide](ja/hand_wire.md)
-   * [ISP Flashing Guide](ja/isp_flashing_guide.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)
 
 * より深く知るために
    * [キーボードがどのように動作するか](ja/how_keyboards_work.md)
-   * [QMKの理解](ja/understanding_qmk.md)
+   * [QMK の理解](ja/understanding_qmk.md)
 
 * 他の話題
-   * [EclipseでQMKを使用](ja/other_eclipse.md)
-   * [VSCodeでQMKを使用](ja/other_vscode.md)
+   * [Eclipse で QMK を使用](ja/other_eclipse.md)
+   * [VSCode で QMK を使用](ja/other_vscode.md)
    * [サポート](ja/support.md)
    * [翻訳を追加する方法](ja/translating.md)
 

docs/ja/arm_debugging.md

@@ -2,7 +2,7 @@
 
 <!---
   original document: eae21eed7:docs/arm_debugging.md
-  git diff eae21eed7 HEAD docs/arm_debugging.md | cat
+  git diff eae21eed7 HEAD -- docs/arm_debugging.md | cat
 -->
 
 このページでは、SWD アダプタとオープンソース/フリーツールを使って ARM MCU をデバッグするためのセットアップ方法について説明します。このガイドでは、GNU MCU Eclipse IDE for C/C++ Developers および OpenOCD を必要な依存関係と一緒にインストールします。
@@ -23,7 +23,7 @@ XPM のインストール手順は[ここ](https://www.npmjs.com/package/xpm)で
 
 ### ARM ツールチェーン
 
-XPM を使うと、ARM ツールチェーンをとても簡単にインストールできます。`xpm install --global @gnu-mcu-eclipse/arm-none-eabi-gcc` とコマンドを入力します。
+XPM を使うと、ARM ツールチェーンをとても簡単にインストールできます。`xpm install --global @xpack-dev-tools/arm-none-eabi-gcc` とコマンドを入力します。
 
 ### Windows ビルドツール
 
@@ -38,7 +38,7 @@ ST-Link を持っている場合は、ドライバは[ここ](https://www.st.com
 
 ### OpenOCD
 
-この依存関係により、SWD は GDB からアクセスでき、デバッグに不可欠です。`xpm install --global @gnu-mcu-eclipse/openocd` を実行します。
+この依存関係により、SWD は GDB からアクセスでき、デバッグに不可欠です。`xpm install --global @xpack-dev-tools/openocd` を実行します。
 
 ### Java
 
@@ -50,33 +50,33 @@ Java は Eclipse で必要とされるため、[ここ](https://www.oracle.com/t
 
 ## Eclipse の設定
 
-ダウンロードした Eclipse IDE を開きます。QMK ディレクトリをインポートするために、File -> Import -> C/C++ -> Existing code as Makefile Project を選択します。Next を選択し、Browse を使用して QMK フォルダを選択します。tool-chain リストから ARM Cross GCC を選択し、Finish を選択します。
+ダウンロードした Eclipse IDE を開きます。QMK ディレクトリをインポートするために、File -> Import -> C/C++ -> Existing Code as Makefile Project を選択します。Next を選択し、Browse を使用して QMK フォルダを選択します。tool-chain リストから ARM Cross GCC を選択し、Finish を選択します。
 
-これで、左側に QMK フォルダが表示されます。右クリックして、Properties を選択します。左側で MCU を展開し、ARM Toolchain Paths を選択します。xPack を押して OK を押します。OpenOCD Path で同じことを繰り返し、Windows の場合は、Build Tool Path でも同じことを繰り返します。Apply and Close を選択します。
+これで、左側に QMK フォルダが表示されます。右クリックして、Properties を選択します。左側で MCU を展開し、ARM Toolchains Paths を選択します。xPack を押して OK を押します。OpenOCD Path で同じことを繰り返し、Windows の場合は、Build Tools Path でも同じことを繰り返します。Apply and Close を選択します。
 
-ここで、必要な MCU パッケージをインストールします。Window -> Open Perspective -> Others -> Packs を選択して、Packs perspective に移動します。Packs タブの横にある黄色のリフレッシュ記号を選択します。これは様々な場所から MCU の定義を要求するため、時間が掛かります。一部のリンクが失敗した場合は、おそらく Ignore を選択できます。
+ここで、必要な MCU パッケージをインストールします。Window -> Perspective -> Open Perspective -> Other... -> Packs を選択して、Packs perspective に移動します。Packs タブの横にある黄色のリフレッシュ記号を選択します。これは様々な場所から MCU の定義を要求するため、時間が掛かります。一部のリンクが失敗した場合は、おそらく Ignore を選択できます。
 
-これが終了すると、ビルドやデバッグする MCU を見つけることができるはずです。この例では、STM32F3 シリーズの MCU を使います。左側で、STMicroelectronics -> STM32F3 Series を選択します。中央のウィンドウに、pack が表示されます。右クリックし、Install を選択します。それが終了したら、Window -> Open Perspective -> Others -> C/C++ を選択してデフォルトのパースペクティブに戻ることができます。
+これが終了すると、ビルドやデバッグする MCU を見つけることができるはずです。この例では、STM32F3 シリーズの MCU を使います。左側で、STMicroelectronics -> STM32F3 Series を選択します。中央のウィンドウに、pack が表示されます。右クリックし、Install を選択します。それが終了したら、Window -> Perspective -> Open Perspective -> Other... -> C/C++ を選択してデフォルトのパースペクティブに戻ることができます。
 
-Eclipse に QMK をビルドしようとするデバイスを教える必要があります。QMK フォルダを右クリック -> Properties -> C/C++ Build -> Settings を選択します。Devices タブを選択し、devices の下から MCU の適切な種類を選択します。私の例では、STM32F303CC です。
+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 を選択します。
 
 ## ビルド
 
-全て正しくセットアップできていれば、ハンマーボタンを押すとファームウェアがビルドされ、.binファイルが出力されるはずです。
+全て正しくセットアップできていれば、ハンマーボタンを押すとファームウェアがビルドされ、.bin ファイルが出力されるはずです。
 
 ## デバッグ
 
 ### デバッガの接続
 
-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 Configuration を選択します。ここで、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,8 +1,8 @@
 # QMK CLI
 
 <!---
-  original document: d598f01cb:cli.md
-  git diff d598f01cb HEAD cli.md | cat
+  original document: 79e6b7866:docs/cli.md
+  git diff 79e6b7866 HEAD -- docs/cli.md | cat
 -->
 
 このページは QMK CLI のセットアップと使用方法について説明します。
@@ -86,7 +86,7 @@ qmk cformat [file1] [file2] [...] [fileN]
 
 ## `qmk compile`
 
-このコマンドにより、任意のディレクトリからファームウェアをコンパイルすることができます。<https://config.qmk.fm> からエクスポートした JSON をコンパイルするか、リポジトリ内でキーマップをコンパイルすることができます。
+このコマンドにより、任意のディレクトリからファームウェアをコンパイルすることができます。<https://config.qmk.fm> からエクスポートした JSON をコンパイルするか、リポジトリ内でキーマップをコンパイルするか、現在の作業ディレクトリでキーボードをコンパイルすることができます。
 
 **Configurator Exports での使い方**:
 
@@ -100,6 +100,53 @@ 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` に設定されています。
@@ -146,14 +193,28 @@ qmk docs [-p PORT]
 
 ## `qmk doctor`
 
-このコマンドは環境を調査し、潜在的なビルドあるいは書き込みの問題について警告します。
+このコマンドは環境を調査し、潜在的なビルドあるいは書き込みの問題について警告します。必要に応じてそれらの多くを修正できます。
 
 **使用法**:
 
 ```
-qmk doctor
+qmk doctor [-y] [-n]
 ```
 
+**例**:
+
+環境に問題がないか確認し、それらを修正するよう促します:
+
+    qmk doctor
+
+環境を確認し、見つかった問題を自動的に修正します:
+
+    qmk doctor -y
+
+環境を確認し、問題のみをレポートします:
+
+    qmk doctor -n
+
 ## `qmk json-keymap`
 
 QMK Configurator からエクスポートしたものから keymap.c を生成します。
@@ -196,6 +257,16 @@ $ qmk kle2json -f kle.txt -f
 qmk list-keyboards
 ```
 
+## `qmk list-keymaps`
+
+このコマンドは指定されたキーボード(とリビジョン)の全てのキーマップをリスト化します。
+
+**使用法**:
+
+```
+qmk list-keymaps -kb planck/ez
+```
+
 ## `qmk new-keymap`
 
 このコマンドは、キーボードの既存のデフォルトのキーマップに基づいて新しいキーマップを作成します。

docs/ja/cli_configuration.md

@@ -1,8 +1,8 @@
 # QMK CLI 設定
 
 <!---
-  original document: d598f01cb:cli_configuration.md
-  git diff d598f01cb HEAD cli_configuration.md | cat
+  original document: d598f01cb:docs/cli_configuration.md
+  git diff d598f01cb HEAD -- docs/cli_configuration.md | cat
 -->
 
 このドキュメントは `qmk config` がどのように動作するかを説明します。

docs/ja/config_options.md

@@ -1,8 +1,8 @@
 # QMK の設定
 
 <!---
-  original document: eae21eed7:docs/config_options.md
-  git diff eae21eed7 HEAD docs/config_options.md | cat
+  original document: 2fe288d01:docs/config_options.md
+  git diff 2fe288d01 HEAD -- docs/config_options.md | cat
 -->
 
 QMK はほぼ無制限に設定可能です。可能なところはいかなるところでも、やりすぎな程、ユーザーがコードサイズを犠牲にしてでも彼らのキーボードをカスタマイズをすることを許しています。ただし、このレベルの柔軟性により設定が困難になります。
@@ -83,7 +83,7 @@ QMK での全ての利用可能な設定にはデフォルトがあります。
 * `#define BACKLIGHT_PIN B7`
    * バックライトのピン
 * `#define BACKLIGHT_LEVELS 3`
-   * バックライトのレベル数 (off を除いて最大15)
+   * バックライトのレベル数 (off を除いて最大31)
 * `#define BACKLIGHT_BREATHING`
    * バックライトのブレスを有効にします
 * `#define BREATHING_PERIOD 6`
@@ -148,10 +148,14 @@ QMK での全ての利用可能な設定にはデフォルトがあります。
 * `#define IGNORE_MOD_TAP_INTERRUPT`
    * 両方のキーに `TAPPING_TERM` を適用することで、ホールド時に他のキーに変換するキーを使ってローリングコンボ (zx) をすることができるようにします
    * 詳細は [Mod tap interrupt](ja/feature_advanced_keycodes.md#ignore-mod-tap-interrupt) を見てください
+* `#define IGNORE_MOD_TAP_INTERRUPT_PER_KEY`
+   * キーごとの `IGNORE_MOD_TAP_INTERRUPT` 設定の処理を有効にします
 * `#define TAPPING_FORCE_HOLD`
    * タップされた直後に、デュアルロールキーを修飾子として使用できるようにします
    * [Hold after tap](ja/feature_advanced_keycodes.md#tapping-force-hold)を見てください
    * タップトグル機能を無効にします (`TT` あるいは One Shot Tap Toggle)
+* `#define TAPPING_FORCE_HOLD_PER_KEY`
+   * キーごとの `TAPPING_FORCE_HOLD` 設定処理を有効にします。
 * `#define LEADER_TIMEOUT 300`
    * リーダーキーがタイムアウトするまでの時間
       * タイムアウトする前にシーケンスを終了できない場合は、タイムアウトの設定を増やす必要があるかもしれません。あるいは、`LEADER_PER_KEY_TIMING` オプションを有効にすると良いでしょう。これは各キーがタップされた後でタイムアウトを再設定します。
@@ -185,7 +189,7 @@ QMK での全ての利用可能な設定にはデフォルトがあります。
 * `#define RGBLIGHT_SPLIT`
    * 分割キーボードの左半分の RGB LED の出力を右半分の RGB LED の入力につなげるかわりに、それぞれの側で個別にコントローラの出力ピンが直接 RGB LED の入力に繋がっているときは、この定義が必要です。
 * `#define RGBLED_SPLIT { 6, 6 }`
-   * 分割キーボードの各半分の `RGB_DI_PIN` に直接配線されている接続されているLEDの数
+   * 分割キーボードの各半分の `RGB_DI_PIN` に直接配線されている接続されている LED の数
    * 最初の値は左半分の LED の数を示し、2番目の値は右半分です。
    * RGBLED_SPLIT が定義されている場合、RGBLIGHT_SPLIT は暗黙的に定義されます。
 * `#define RGBLIGHT_HUE_STEP 12`
@@ -214,7 +218,7 @@ QMK での全ての利用可能な設定にはデフォルトがあります。
 
 ### 左右の設定
 
-一つ覚えておかなければならないことは、USB ポートが接続されている側が常にマスター側であるということです。USB に接続されていない側はスレーブです。
+1つ覚えておかなければならないことは、USB ポートが接続されている側が常にマスター側であるということです。USB に接続されていない側はスレーブです。
 
 分割キーボードの左右を設定するには、幾つかの異なる方法があります (優先度の順にリストされています):
 
@@ -258,7 +262,7 @@ QMK での全ての利用可能な設定にはデフォルトがあります。
 * `#define SELECT_SOFT_SERIAL_SPEED <speed>` (デフォルトの速度は1です)
    * serial 通信を使う時のプロトコルの速度を設定します。
    * 速度:
-      * 0: 約189kbps (実験目的のみ)
+      * 0: 約 189kbps (実験目的のみ)
       * 1: 約 137kbps (デフォルト)
       * 2: 約 75kbps
       * 3: 約 39kbps
@@ -270,9 +274,12 @@ QMK での全ての利用可能な設定にはデフォルトがあります。
    * ARM についてはデフォルトの挙動
    * AVR Teensy については必須
 
-* `#define SPLIT_USB_TIMEOUT 2500`
+* `#define SPLIT_USB_TIMEOUT 2000`
    * `SPLIT_USB_DETECT` を使う時のマスタ/スレーブを検出する場合の最大タイムアウト
 
+* `#define SPLIT_USB_TIMEOUT_POLL 10`
+   * `SPLIT_USB_DETECT` を使う時のマスタ/スレーブを検出する場合のポーリング頻度
+
 # `rules.mk` ファイル
 
 これは、トップレベルの `Makefile` から include される [make](https://www.gnu.org/software/make/manual/make.html) ファイルです。これは特定の機能を有効または無効にするだけでなく、コンパイルする MCU に関する情報を設定するために使われます。
@@ -285,8 +292,26 @@ QMK での全ての利用可能な設定にはデフォルトがあります。
    * ビルドの後でルート `qmk_firmware` フォルダにコピーされる形式 (bin, hex) を定義します。
 * `SRC`
    * コンパイル・リンクリストにファイルを追加するために使われます。
+* `LIB_SRC`
+  * コンパイル・リンクリストにライブラリとしてファイルを追加するために使われます。  
+    `LIB_SRC` で指定されたファイルは、`SRC` で指定されたファイルの後にリンクされます。  
+    例えば、次のように指定した場合:
+    ```
+    SRC += a.c
+    LIB_SRC += lib_b.c
+    SRC += c.c
+    LIB_SRC += lib_d.c
+    ```
+    リンク順は以下の通りです。
+    ```
+     ...  a.o c.o  ...  lib_b.a lib_d.a  ...
+    ```
 * `LAYOUTS`
    * このキーボードがサポートする[レイアウト](ja/feature_layouts.md)のリスト
+* `LINK_TIME_OPTIMIZATION_ENABLE`
+   * キーボードをコンパイルする時に、Link Time Optimization (`LTO`) を有効にします。これは処理に時間が掛かりますが、コンパイルされたサイズを大幅に減らします (そして、ファームウェアが小さいため、追加の時間は分からないくらいです)。ただし、`LTO` が有効な場合、古いマクロと関数の機能が壊れるため、自動的にこれらの機能を無効にします。これは `NO_ACTION_MACRO` と `NO_ACTION_FUNCTION` を自動的に定義することで行われます。
+* `LTO_ENABLE`
+   * LINK_TIME_OPTIMIZATION_ENABLE と同じ意味です。`LINK_TIME_OPTIMIZATION_ENABLE` の代わりに `LTO_ENABLE` を使うことができます。
 
 ## AVR MCU オプション
 * `MCU = atmega32u4`
@@ -345,9 +370,6 @@ QMK での全ての利用可能な設定にはデフォルトがあります。
    * キーボードが起動する前に、USB 接続が確立されるのをキーボードに待機させます
 * `NO_USB_STARTUP_CHECK`
    * キーボードの起動後の usb サスペンドチェックを無効にします。通常、キーボードはタスクが実行される前にホストがウェイク アップするのを待ちます。分割キーボードは半分はウェイクアップコールを取得できませんが、マスタにコマンドを送信する必要があるため、役に立ちます。
-* `LINK_TIME_OPTIMIZATION_ENABLE`
-   * キーボードをコンパイルする時に、Link Time Optimization (`LTO`) を有効にします。これは処理に時間が掛かりますが、コンパイルされたサイズを大幅に減らします (そして、ファームウェアが小さいため、追加の時間は分からないくらいです)。ただし、`LTO` が有効な場合、古いマクロと関数の機能が壊れるため、自動的にこれらの機能を無効にします。これは `NO_ACTION_MACRO` と `NO_ACTION_FUNCTION` を自動的に定義することで行われます。
-   * `LINK_TIME_OPTIMIZATION_ENABLE` の代わりに `LTO_ENABLE` を使うことができます。
 
 ## USB エンドポイントの制限
 

docs/ja/contributing.md

@@ -1,8 +1,8 @@
 # 貢献方法
 
 <!---
-  original document: d598f01cb:contributing.md
-  git diff d598f01cb HEAD contributing.md | cat
+  original document: d47809575:docs/contributing.md
+  git diff d47809575 HEAD -- docs/contributing.md | cat
 -->
 
 👍🎉 まず、これを読み貢献する時間を作ってくれてありがとうございます！🎉👍
@@ -90,7 +90,7 @@ kerpleplork はエラーコード 23 で連続的に失敗していました。
 
 ドキュメントは QMK への貢献を始める最も簡単な方法の1つです。ドキュメントが間違っているか不完全な場所を見つけ、これらを修正するのは簡単です！私たちもドキュメントを編集する人を非常に必要としています。編集するスキルがあるが、どこにどのように飛び乗ればいいのか分からない場合は、[助けをもとめて](#where-can-i-go-for-help)ください！
 
-全てのドキュメントは `qmk_firmware/docs` ディレクトリの中にあります。あるいは web ベースのワークフローを使いたい場合は、http://docs.qmk.fm/ の各ページの上部にある "Suggest An Edit" をクリックすることができます。
+全てのドキュメントは `qmk_firmware/docs` ディレクトリの中にあります。あるいは web ベースのワークフローを使いたい場合は、https://docs.qmk.fm/ の各ページの下部にある "Edit this page" リンクをクリックすることができます。
 
 ドキュメントの中にコードの例を提供する場合は、ドキュメント内の他の場所で使用されている命名規則を順守してください。例えば、一貫性を保つために、`my_layers` あるいは `my_keycodes` として列挙型を標準化します:
 

docs/ja/custom_quantum_functions.md

@@ -0,0 +1,518 @@
+# キーボードの挙動をカスタマイズする方法
+
+<!---
+  original document: 7494490d6:docs/custom_quantum_functions.md
+  git diff 7494490d6 HEAD -- docs/custom_quantum_functions.md | cat
+-->
+
+多くの人にとって、カスタムキーボードはボタンの押下をコンピュータに送信するだけではありません。単純なボタンの押下やマクロよりも複雑なことを実行できるようにしたいでしょう。QMK にはコードを挿入したり、機能を上書きしたり、様々な状況でキーボードの挙動をカスタマイズできるフックがあります。
+
+このページでは、QMK に関する特別な知識は想定していませんが、[QMK の理解](ja/understanding_qmk.md)を読むとより根本的なレベルで何が起きているかを理解するのに役立ちます。
+
+## コア、キーボード、キーマップ階層 :id=a-word-on-core-vs-keyboards-vs-keymap
+
+私たちは QMK を階層として構造化しました:
+
+* コア (`_quantum`)
+   * キーボード/リビジョン (`_kb`)
+      * キーマップ (`_user`)
+
+以下で説明される各関数は `_kb()` サフィックスあるいは `_user()` サフィックスを使って定義することができます。`_kb()` サフィックスはキーボード/リビジョンレベルで使うことを意図しており、一方で `_user()` サフィックスはキーマップレベルで使われるべきです。
+
+キーボード/リビジョンレベルで関数を定義する場合、`_kb()` は他の何かを実行する前に `_user()` を呼び出すよう実装することが重要です。そうでなければ、キーマップレベル関数は呼ばれないでしょう。
+
+# カスタムキーコード
+
+最も一般的なタスクは、既存のキーコードの挙動を変更するか、新しいキーコードを作成することです。コードの観点からは、それぞれの仕組みは非常に似ています。
+
+## 新しいキーコードの定義
+
+独自のカスタムキーコードを作成する最初のステップは、それらを列挙することです。これは、カスタムキーコードに名前を付け、そのキーコードにユニークな番号を割り当てることの両方を意味します。QMK は、カスタムキーコードを固定範囲の番号に制限するのではなく、`SAFE_RANGE` マクロを提供します。カスタムキーコードを列挙する時に `SAFE_RANGE` を使うと、ユニークな番号を取得することが保証されます。
+
+
+これは2つのキーコードを列挙する例です。このブロックを `keymap.c` に追加した後で、キーマップの中で `FOO` と `BAR` を使うことができます。
+
+```c
+enum my_keycodes {
+  FOO = SAFE_RANGE,
+  BAR
+};
+```
+
+## 任意のキーコードの挙動のプログラミング
+
+既存のキーの挙動を上書きしたい場合、あるいは新しいキーについて挙動を定義する場合、`process_record_kb()` および `process_record_user()` 関数を使うべきです。これらは実際のキーイベントが処理される前のキー処理中に QMK によって呼び出されます。これらの関数が `true` を返す場合、QMK はキーコードを通常通りに処理します。これは、キーを置き換えるのではなく、キーの機能を拡張するのに便利です。これらの関数が `false` を返す場合、QMK は通常のキー処理をスキップし、必要なキーのアップまたはダウンイベントを送信するのかはユーザ次第です。
+
+これらの関数はキーが押されるか放されるたびに呼び出されます。
+
+### `process_record_user()` の実装例
+
+この例は2つの事を行います。`FOO` と呼ばれるカスタムキーコードの挙動を定義し、Enter キーが押されるたびに音を再生します。
+
+```c
+bool process_record_user(uint16_t keycode, keyrecord_t *record) {
+  switch (keycode) {
+    case FOO:
+      if (record->event.pressed) {
+        // 押された時に何かをします
+      } else {
+        // 放された時に何かをします
+      }
+      return false; // このキーの以降の処理をスキップします
+    case KC_ENTER:
+      // enter が押された時に音を再生します
+      if (record->event.pressed) {
+        PLAY_NOTE_ARRAY(tone_qwerty);
+      }
+      return true; // QMK に enter のプレスまたはリリースイベントを送信させます
+    default:
+      return true; // 他の全てのキーコードを通常通りに処理します
+  }
+}
+```
+
+### `process_record_*` 関数のドキュメント
+
+* キーボード/リビジョン: `bool process_record_kb(uint16_t keycode, keyrecord_t *record)`
+* キーマップ: `bool process_record_user(uint16_t keycode, keyrecord_t *record)`
+
+`keycode` 引数はキーマップで定義されているものです。例えば `MO(1)`、`KC_L` など。これらのイベントを処理するには `switch...case` ブロックを使うべきです。
+
+`record` 引数は実際のプレスに関する情報を含みます:
+
+```c
+keyrecord_t record {
+  keyevent_t event {
+    keypos_t key {
+      uint8_t col
+      uint8_t row
+    }
+    bool     pressed
+    uint16_t time
+  }
+}
+```
+
+# LED 制御
+
+QMK は HID 仕様で定義された5つの LED の読み取りメソッドを提供します:
+
+* Num Lock
+* Caps Lock
+* Scroll Lock
+* Compose
+* Kana
+
+ロック LED の状態を取得するには2つの方法があります:
+
+* `bool led_update_kb(led_t led_state)` あるいは `_user(led_t led_state)` を実装する、または
+* `led_t host_keyboard_led_state()` を呼び出す
+
+!> `host_keyboard_led_state()` は `led_update_user()` が呼ばれる前に新しい値を既に反映している場合があります。
+
+LED の状態を `uint8_t` として提供する2つの非推奨の関数があります:
+
+* `uint8_t led_set_kb(uint8_t usb_led)` と `_user(uint8_t usb_led)`
+* `uint8_t host_keyboard_leds()`
+
+## `led_update_user()`
+
+この関数はこれら5つの LED のいずれかの状態が変化すると呼ばれます。LED の状態を構造体のパラメータとして受け取ります。
+
+慣例により、`led_update_kb()` にそのコードを実行するようフックさせるために `led_update_user()` から `true` を返し、`led_update_kb()` でコードを実行したくない場合は `false` を返します。
+
+以下はいくつかの例です:
+
+- レイヤー表示のような何かのために LED を使うために LED を上書きする
+   - `_kb()` 関数を実行したくないので、`false`  を返します。これはレイヤーの挙動を上書きするためです。
+- LED がオンあるいはオフになった時に音楽を再生する。
+   - `_kb` 関数を実行したいので、`true` を返します。これはデフォルトの LED の挙動に追加されます。
+
+?> `led_set_*` 関数は `bool` の代わりに `void` を返すため、キーボードの LED 制御を上書きすることができません。従って、代わりに `led_update_*` を使うことをお勧めします。
+
+### `led_update_kb()` の実装例
+
+```c
+bool led_update_kb(led_t led_state) {
+    bool res = led_update_user(led_state);
+    if(res) {
+        // writePin は 1 でピンを high に、0 で low に設定します。
+        // この例では、ピンは反転していて、
+        // low/0 は LED がオンになり、high/1 は LED がオフになります。
+        // この挙動は、LED がピンと VCC の間にあるか、ピンと GND の間にあるかどうかに依存します。
+        writePin(B0, !led_state.num_lock);
+        writePin(B1, !led_state.caps_lock);
+        writePin(B2, !led_state.scroll_lock);
+        writePin(B3, !led_state.compose);
+        writePin(B4, !led_state.kana);
+    }
+    return res;
+}
+```
+
+### `led_update_user()` の実装例
+
+この不完全な例は Caps Lock がオンまたはオフになった場合に音を再生します。また LED の状態を保持する必要があるため、`true` を返します。
+
+```c
+#ifdef AUDIO_ENABLE
+  float caps_on[][2] = SONG(CAPS_LOCK_ON_SOUND);
+  float caps_off[][2] = SONG(CAPS_LOCK_OFF_SOUND);
+#endif
+
+bool led_update_user(led_t led_state) {
+    #ifdef AUDIO_ENABLE
+    static uint8_t caps_state = 0;
+    if (caps_state != led_state.caps_lock) {
+        led_state.caps_lock ? PLAY_SONG(caps_on) : PLAY_SONG(caps_off);
+        caps_state = led_state.caps_lock;
+    }
+    #endif
+    return true;
+}
+```
+
+### `led_update_*` 関数のドキュメント
+
+* キーボード/リビジョン: `bool led_update_kb(led_t led_state)`
+* キーマップ: `bool led_update_user(led_t led_state)`
+
+## `host_keyboard_led_state()`
+
+最後に受信した LED の状態を `led_t` として取得するためにこの関数を呼びます。これは、`led_update_*` の外部から、例えば [`matrix_scan_user()`](#matrix-scanning-code) の中で LED の状態を読み取るのに便利です。
+
+## 物理的な LED の状態の設定
+
+一部のキーボードの実装は、物理的な LED の状態を設定するための便利なメソッドを提供しています。
+
+### Ergodox キーボード
+
+Ergodox の実装は、個々の LED をオンあるいはオフにするために `ergodox_right_led_1`/`2`/`3_on`/`off()` と、インデックスによってそれらをオンあるいはオフにするために `ergodox_right_led_on`/`off(uint8_t led)` を提供します。
+
+さらに、LED の明度を指定することができます。全ての LED に同じ明度を指定するなら `ergodox_led_all_set(uint8_t n)` を使い、個別の LED の明度を指定するなら `ergodox_right_led_1`/`2`/`3_set(uint8_t n)` を使い、LED のインデックスを指定して明度を指定するには  `ergodox_right_led_set(uint8_t led, uint8_t n)` を使います。
+
+Ergodox キーボードは、最低の明度として `LED_BRIGHTNESS_LO` を、最高の輝度(これはデフォルトです)として `LED_BRIGHTNESS_HI` も定義しています。
+
+# キーボードの初期化コード
+
+キーボードの初期化プロセスには幾つかのステップがあります。何をしたいかによって、どの関数を使うべきかに影響します。
+
+3つの主な初期化関数があり、呼び出される順番にリストされています。
+
+* `keyboard_pre_init_*` - ほとんどのものが開始される前に起こります。非常に早くに実行したいハードウェアのセットアップに適しています。
+* `matrix_init_*` - ファームウェアのスタートアッププロセスの途中で起こります。ハードウェアは初期化されますが、機能はまだ初期化されていない場合があります。
+* `keyboard_post_init_*` - ファームウェアのスタートアッププロセスの最後に起こります。これはほとんどの場合、 "カスタマイズ"コードを配置する場所です。
+
+!> ほとんどの人にとって、`keyboard_post_init_user` が呼び出したいものです。例えば、ここで RGB アンダーグローのセットアップを行います。
+
+## キーボードの事前初期化コード
+
+これは USB さえ起動する前の、起動中の非常に早い段階で実行されます。
+
+この直後にマトリックスが初期化されます。
+
+これは主にハードウェア向きの初期化のためであるため、ほとんどのユーザは使うべきではありません。
+
+ただし、初期化が必要なハードウェアがある場合には、これが最適な場所です (LED ピンの初期化など)。
+
+### `keyboard_pre_init_user()` の実装例
+
+この例は、キーボードレベルで、LED ピンとして B0、B1、B2、B3 および B4 をセットアップします。
+
+```c
+void keyboard_pre_init_user(void) {
+  // キーボードの事前初期コードを呼び出します。
+
+  // LED ピンを出力として設定します
+  setPinOutput(B0);
+  setPinOutput(B1);
+  setPinOutput(B2);
+  setPinOutput(B3);
+  setPinOutput(B4);
+}
+```
+
+### `keyboard_pre_init_*` 関数のドキュメント
+
+* キーボード/リビジョン: `void keyboard_pre_init_kb(void)`
+* キーマップ: `void keyboard_pre_init_user(void)`
+
+## マトリックスの初期化コード
+
+これは、マトリックスが初期化され、ハードウェアの一部がセットアップされた後で、ただし機能の多くが初期化される前に、呼び出されます。
+
+他の場所で必要になるかもしれないものをセットアップするのに役立ちますが、ハードウェアに関連するものではなく、開始場所に依存するものでもありません。
+
+
+### `matrix_init_*` 関数のドキュメント
+
+* キーボード/リビジョン: `void matrix_init_kb(void)`
+* キーマップ: `void matrix_init_user(void)`
+
+
+## キーボードの事後初期化コード
+
+キーボードの初期化プロセスの極めて最後のタスクとして実行されます。この時点で初期化される必要があるような、特定の機能を変更したい場合に便利です。
+
+
+### `keyboard_post_init_user()` の実装例
+
+この例は、他の全てのものが初期化された後で実行され、rgb アンダーグローの設定をセットアップします。
+
+```c
+void keyboard_post_init_user(void) {
+  // post init コードを呼びます
+  rgblight_enable_noeeprom(); // 設定を保存せずに Rgb を有効にします
+  rgblight_sethsv_noeeprom(180, 255, 255); // 保存せずに色を青緑/シアンに設定します
+  rgblight_mode_noeeprom(RGBLIGHT_MODE_BREATHING + 3); // 保存せずにモードを高速なブリージングに設定します
+}
+```
+
+### `keyboard_post_init_*` 関数のドキュメント
+
+* キーボード/リビジョン: `void keyboard_post_init_kb(void)`
+* キーマップ: `void keyboard_post_init_user(void)`
+
+# マトリックススキャンコード :id=matrix-scanning-code
+
+可能であれば常に `process_record_*()` を使ってキーボードをカスタマイズし、その方法でイベントをフックし、コードがキーボードのパフォーマンスに悪影響を与えないようにします。ただし、まれにマトリックススキャンにフックする必要があります。これらの関数は1秒あたり少なくとも10回は呼び出されるため、これらの関数のコードのパフォーマンスに非常に注意してください。
+
+### `matrix_scan_*` の実装例
+
+この例は意図的に省略されています。このようなパフォーマンスに敏感な領域にフックする前に、例を使わずにこれを書くために、QMK 内部について十分理解する必要があります。助けが必要であれば、[issue を開く](https://github.com/qmk/qmk_firmware/issues/new) か [Discord で会話](https://discord.gg/Uq7gcHh)してください。
+
+### `matrix_scan_*` 関数のドキュメント
+
+* キーボード/リビジョン: `void matrix_scan_kb(void)`
+* キーマップ: `void matrix_scan_user(void)`
+
+この関数はマトリックススキャンのたびに呼び出されます。これは基本的に MCU が処理できる頻度です。大量に実行されるため、ここに何を置くかについては注意してください。
+
+カスタムマトリックススキャンコードが必要な場合は、この関数を使う必要があります。また、カスタムステータス出力 (LED あるいはディスプレイなど)や、ユーザが入力していない場合でも定期的にトリガーするその他の機能のために使うことができます。
+
+
+# キーボードアイドリング/ウェイクコード
+
+キーボードがサポートしている場合、多くの機能を停止することで"アイドル"にすることができます。これの良い例は、RGB ライトあるいはバックライトです。これにより、電力消費を節約できるか、キーボードの動作が改善されるかもしれません。
+
+これは2つの関数によって制御されます: `suspend_power_down_*` および `suspend_wakeup_init_*`。これらはシステムキーボードがアイドルになった時と、起動した時のそれぞれで呼ばれます。
+
+
+### suspend_power_down_user() と suspend_wakeup_init_user() の実装例
+
+
+```c
+void suspend_power_down_user(void) {
+    rgb_matrix_set_suspend_state(true);
+}
+
+void suspend_wakeup_init_user(void) {
+    rgb_matrix_set_suspend_state(false);
+}
+```
+
+### キーボードサスペンド/ウェイク関数のドキュメント
+
+* キーボード/リビジョン : `void suspend_power_down_kb(void)` および `void suspend_wakeup_init_user(void)`
+* キーマップ: `void suspend_power_down_kb(void)` および `void suspend_wakeup_init_user(void)`
+
+# レイヤー切り替えコード
+
+これはレイヤーが切り替えられるたびにコードを実行します。レイヤー表示あるいはカスタムレイヤー処理に役立ちます。
+
+### `layer_state_set_*` の実装例
+
+この例は、レイヤーに基づいて [RGB アンダーグロー](ja/feature_rgblight.md)を設定する方法を示していて、Planck を例として使っています。
+
+```c
+layer_state_t layer_state_set_user(layer_state_t state) {
+    switch (get_highest_layer(state)) {
+    case _RAISE:
+        rgblight_setrgb (0x00,  0x00, 0xFF);
+        break;
+    case _LOWER:
+        rgblight_setrgb (0xFF,  0x00, 0x00);
+        break;
+    case _PLOVER:
+        rgblight_setrgb (0x00,  0xFF, 0x00);
+        break;
+    case _ADJUST:
+        rgblight_setrgb (0x7A,  0x00, 0xFF);
+        break;
+    default: //  他の全てのレイヤーあるいはデフォルトのレイヤー
+        rgblight_setrgb (0x00,  0xFF, 0xFF);
+        break;
+    }
+  return state;
+}
+```
+### `layer_state_set_*` 関数のドキュメント
+
+* キーボード/リビジョン: `layer_state_t layer_state_set_kb(layer_state_t state)`
+* キーマップ: `layer_state_t layer_state_set_user(layer_state_t state)`
+
+
+[キーマップの概要](ja/keymap.md#keymap-layer-status)で説明されるように、`state` はアクティブなレイヤーのビットマスクです。
+
+
+# 永続的な設定 (EEPROM)
+
+これによりキーボードのための永続的な設定を設定することができます。これらの設定はコントローラの EEPROM に保存され、電源が落ちた後であっても保持されます。設定は `eeconfig_read_kb` および `eeconfig_read_user` を使って読み取ることができ、`eeconfig_update_kb` および `eeconfig_update_user` を使って書きこむことができます。これは切り替え可能な機能 (rgb レイヤーの表示の切り替えなど)に役立ちます。さらに、`eeconfig_init_kb` および `eeconfig_init_user` を使って EEPROM のデフォルト値を設定できます。
+
+ここでの複雑な部分は、EEPROM を介してデータを保存およびアクセスできる方法がたくさんあり、これを行うための"正しい"方法が無いということです。ただし、各関数には DWORD (4 バイト)しかありません。
+
+EEPROM の書き込み回数には制限があることに注意してください。これは非常に高い値ですが、EEPROM に書き込むのはこれだけではなく、もし頻繁に書き込むと、MCU の寿命を大幅に短くする可能性があります。
+
+* この例を理解していない場合は、この機能はかなり複雑なため、この機能を使うことを避けても構いません。
+
+### 実装例
+
+これは、設定を追加し、読み書きする例です。この例では、ユーザキーマップを使っています。これは複雑な機能で、多くのことが行われています。実際、動作のために上記の多くの関数を使います！
+
+
+keymap.c ファイルの中で、先頭にこれを追加します:
+```c
+typedef union {
+  uint32_t raw;
+  struct {
+    bool     rgb_layer_change :1;
+  };
+} user_config_t;
+
+user_config_t user_config;
+```
+
+これは、設定をメモリ内に保存し、EEPROM に書き込むことができる32ビット構造体をセットアップします。これを使うと、この構造体に変数が定義されるため、変数を定義する必要が無くなります。`bool` (boolean) の値は1ビットを使い、`uint8_t` は8ビットを使い、`uint16_t` は16ビットを使うことに注意してください。組み合わせて使うことができますが、順番の変更は読み書きされる値が変更されるため、問題が発生するかもしれません。
+
+`layer_state_set_*` 関数のために `rgb_layer_change` を使い、全てを設定するために `keyboard_post_init_user` および `process_record_user` を使います。
+
+ここで、上の `keyboard_post_init_user` コードを使って、作成したばかりの構造体を設定するために `eeconfig_read_user()` を追加します。そして、この構造体をすぐに使ってキーマップの機能を制御することができます。それは以下のようになります:
+```c
+void keyboard_post_init_user(void) {
+  // キーマップレベルのマトリックスの初期化処理を呼びます
+
+  // EEPROM からユーザ設定を読み込みます
+  user_config.raw = eeconfig_read_user();
+
+  // 有効な場合はデフォルトレイヤーを設定します
+  if (user_config.rgb_layer_change) {
+    rgblight_enable_noeeprom();
+    rgblight_sethsv_noeeprom_cyan();
+    rgblight_mode_noeeprom(1);
+  }
+}
+```
+上記の関数は読み取ったばかりの EEPROM 設定を使い、デフォルトのレイヤーの RGB 色を設定します。その「生の」値は、上で作成した「共用体」に基づいて使用可能な構造に変換されます。
+
+```c
+layer_state_t layer_state_set_user(layer_state_t state) {
+    switch (get_highest_layer(state)) {
+    case _RAISE:
+        if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_magenta(); rgblight_mode_noeeprom(1); }
+        break;
+    case _LOWER:
+        if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_red(); rgblight_mode_noeeprom(1); }
+        break;
+    case _PLOVER:
+        if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_green(); rgblight_mode_noeeprom(1); }
+        break;
+    case _ADJUST:
+        if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_white(); rgblight_mode_noeeprom(1); }
+        break;
+    default: //  他の全てのレイヤーあるいはデフォルトのレイヤー
+        if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_cyan(); rgblight_mode_noeeprom(1); }
+        break;
+    }
+  return state;
+}
+```
+これにより、値が有効になっていた場合のみ、RGB アンダーグローが変更されます。この値を設定するために、`RGB_LYR` と呼ばれる `process_record_user` 用の新しいキーコードを作成します。さらに、通常の RGB コードを使う場合、上記の例を使ってオフになることを確認します。以下のようになります:
+```c
+bool process_record_user(uint16_t keycode, keyrecord_t *record) {
+  switch (keycode) {
+    case FOO:
+      if (record->event.pressed) {
+        // 押された時に何かをします
+      } else {
+        // 放された時に何かをします
+      }
+      return false; // このキーの以降の処理をスキップします
+    case KC_ENTER:
+        // enter が押された時に音を再生します
+        if (record->event.pressed) {
+            PLAY_NOTE_ARRAY(tone_qwerty);
+        }
+        return true; // QMK に enter のプレスまたはリリースイベントを送信させます
+    case RGB_LYR:  // これにより、アンダーグローをレイヤー表示として、あるいは通常通りに使うことができます。
+        if (record->event.pressed) {
+            user_config.rgb_layer_change ^= 1; // 状態を切り替えます
+            eeconfig_update_user(user_config.raw); // 新しい状態を EEPROM に書き込みます
+            if (user_config.rgb_layer_change) { // レイヤーの状態表示が有効な場合
+                layer_state_set(layer_state);   // すぐにレイヤーの色を更新します
+            }
+        }
+        return false; break;
+    case RGB_MODE_FORWARD ... RGB_MODE_GRADIENT: // 任意の RGB コード に対して(quantum_keycodes.h を見てください。400行目参照)
+        if (record->event.pressed) { // これはレイヤー表示を無効にします。これを変更する場合は、無効にしたいだろうため。
+            if (user_config.rgb_layer_change) {        // 有効な場合のみ
+                user_config.rgb_layer_change = false;  // 無効にします
+                eeconfig_update_user(user_config.raw); // 設定を EEPROM に書き込みます
+            }
+        }
+        return true; break;
+    default:
+      return true; // 他の全てのキーコードを通常通りに処理します
+  }
+}
+```
+最後に、`eeconfig_init_user` 関数を追加して、EEPROM がリセットされた時にデフォルト値、さらにはカスタムアクションを指定できるようにします。EEPROM を強制的にリセットするには、`EEP_RST` キーコードあるいは[ブートマジック](ja/feature_bootmagic.md)機能を使います。例えば、デフォルトで rgb レイヤー表示を設定し、デフォルト値を保存したい場合。
+
+```c
+void eeconfig_init_user(void) {  // EEPROM がリセットされます！
+  user_config.raw = 0;
+  user_config.rgb_layer_change = true; // デフォルトでこれを有効にします
+  eeconfig_update_user(user_config.raw); // デフォルト値を EEPROM に書き込みます
+
+  // これらの値も EEPROM に書き込むためには、noeeprom 以外のバージョンを使います
+  rgblight_enable(); // デフォルトで RGB を有効にします
+  rgblight_sethsv_cyan();  // デフォルトでシアンに設定します
+  rgblight_mode(1); // デフォルトでソリッドに設定します
+}
+```
+
+これで完了です。RGB レイヤー表示は必要な場合にのみ機能します。キーボードを取り外した後でも保存されます。RGB コードのいずれかを使うと、レイヤー表示が無効になり、設定したモードと色がそのままになります。
+
+### 'EECONFIG' 関数のドキュメント
+
+* キーボード/リビジョン: `void eeconfig_init_kb(void)`、`uint32_t eeconfig_read_kb(void)` および `void eeconfig_update_kb(uint32_t val)`
+* キーマップ: `void eeconfig_init_user(void)`、`uint32_t eeconfig_read_user(void)` および `void eeconfig_update_user(uint32_t val)`
+
+`val` は EEPROM に書き込みたいデータの値です。`eeconfig_read_*` 関数は EEPROM から32ビット(DWORD) 値を返します。
+
+# カスタムタッピング期間
+
+デフォルトでは、タッピング期間はグローバルに設定されていて、キーでは設定することができません。ほとんどのユーザにとって、これは全然問題ありません。しかし、場合によっては、`LT` キーとは異なるタイムアウトによって、デュアルファンクションキーが大幅に改善されます。なぜなら、一部のキーは他のキーよりも押し続けやすいためです。それぞれにカスタムキーコードを使う代わりに、キーごとに設定可能な `TAPPING_TERM` を使用できます。
+
+この機能を有効にするには、最初に `config.h` に `#define TAPPING_TERM_PER_KEY` を追加する必要があります。
+
+
+## `get_tapping_term` の実装例
+
+キーコードに基づいて `TAPPING TERM` を変更するには、次のようなものを `keymap.c` ファイルに追加します:
+
+```c
+uint16_t get_tapping_term(uint16_t keycode) {
+  switch (keycode) {
+    case SFT_T(KC_SPC):
+      return TAPPING_TERM + 1250;
+    case LT(1, KC_GRV):
+      return 130;
+    default:
+      return TAPPING_TERM;
+  }
+}
+```
+
+### `get_tapping_term` 関数のドキュメント
+
+ここにある他の多くの関数とは異なり、quantum あるいはキーボードレベルの関数を持つ必要はありません (または理由さえありません)。ここではユーザレベルの関数だけが有用なため、そのようにマークする必要はありません。

docs/ja/driver_installation_zadig.md

@@ -0,0 +1,53 @@
+# Zadig を使ったブートローダドライバのインストール
+
+<!---
+  original document: d598f01cb:docs/driver_installation_zadig.md
+  git diff d598f01cb HEAD -- docs/driver_installation_zadig.md | cat
+-->
+
+QMK はホストにたいして通常の HID キーボードデバイスとして振る舞うため特別なドライバは必要ありません。しかし、Windows でのキーボードへの書き込みは、多くの場合、キーボードをリセットした時に現れるブートローダデバイスで*行います*。
+
+2つの注目すべき例外があります: 通常 Pro Micro で見られる Caterina ブートローダや、PJRC Teensy に書き込まれている HalfKay ブートローダは、それぞれシリアルポートと汎用 HID デバイスとして振る舞うため、ドライバは必要ありません。
+
+[Zadig](https://zadig.akeo.ie/) ユーティリティを使うことをお勧めします。MSYS2 あるいは WSL を使って開発環境をセットアップした場合、`qmk_install.sh` スクリプトはドライバをインストールするかどうかをたずねます。
+
+## インストール
+
+`RESET` キーコード (別のレイヤにあるかもしれません)を押すか、通常はキーボードの下面にあるリセットスイッチを押して、キーボードをブートローダモードにします。どちらもキーボードに無い場合は、Escape または Space+`B` を押しながら接続してみてください (詳細は、[ブートマジック](ja/feature_bootmagic.md) ドキュメントを見てください)。一部のキーボードはブートマジックの代わりに[コマンド](ja/feature_command.md)を使います。この場合、キーボードが接続されている状態で「左Shift + 右Shift + `B`」あるいは「左Shift + 右Shift + Escape」を押すと、ブートローダモードに入ることができます。
+一部のキーボードはブートローダに入るために特定の操作をする必要があります。例えば、[ブートマジック Lite](ja/feature_bootmagic.md#bootmagic-lite) キー (デフォルト: Escape) は別のキー(例えば、左Control)かもしれません。また、コマンドを有効にするキーの組み合わせ (デフォルト: 左Shift + 右Shift) は何か他のキー(例えば 左Control + 右Control)を押し続ける必要がある場合があります。不明な場合は、キーボードの README ファイルを参照してください。
+
+USBaspLoader を使ってデバイスをブートローダモードにするには、`BOOT` ボタンを押しながら `RESET` ボタンをタップしてください。
+あるいは `BOOT` を押し続けながら USB ケーブルを挿入します。
+
+Zadig は自動的にブートローダデバイスを検知します。**Options → List All Devices** を確認する必要がある場合があります。
+
+- Atmel AVR MCU を搭載したキーボードの場合、ブートローダは `ATm32U4DFU` に似た名前が付けられ、ベンダー ID は `03EB` です。
+- USBasp ブートローダは `USBasp` として表示され、VID/PID は`16C0:05DC` です。
+- QMK-DFU ブートローダを使って書き込まれた AVR キーボードは `<keyboard name> Bootloader` という名前が付けられ、VID は `03EB` です。
+- ほとんどの ARM キーボードでは、`STM32 BOOTLOADER` と呼ばれ、VID/PID は `0483:DF11` です。
+
+!> Zadig が `HidUsb` ドライバを使用する1つ以上のデバイスを表示する場合、キーボードはおそらくブートローダモードではありません。矢印はオレンジ色になり、システムドライバの変更を確認するように求められます。この場合、続行**しないでください**！
+
+矢印が緑色で表示されたら、ドライバを選択し、**Install Driver** をクリックします。`libusb-win32` ドライバは通常 AVR で動作し、`WinUSB`は ARM で動作しますが、それでもキーボードに書き込みできない場合は、リストから異なるドライバをインストールしてみてください。msys2 を使ってコマンドライン経由で USBaspLoader デバイスに書き込むには、`libusbk` ドライバがお勧めです。そうではなく書き込みに QMK Toolbox を使っている場合は `libusb-win32` がうまく動作します。
+
+![ブートローダドライバが正常にインストールされた Zadig](https://i.imgur.com/b8VgXzx.png)
+
+最後に、新しいドライバがロードされたことを確認するためにキーボードのプラグを抜いて再接続します。書き込みに QMK Toolbox を使う場合は、ドライバの変更を認識しない場合があるため、QMK Toolkit を終了して再起動します。
+
+## 間違ったデバイスのインストールからの回復
+
+キーボードが入力できなくなった場合は、ブートローダではなくキーボード自体のドライバを間違って入れ替えた可能性があります。これはキーボードがブートローダモードでない場合に起こりえます。これは Zadig で簡単に確認することができます - 健全なキーボードには、全てのインタフェースに `HidUsb` ドライバがインストールされています:
+
+![Zadig から見た健全なキーボード](https://i.imgur.com/Hx0E5kC.png)
+
+デバイスマネージャーを開き、キーボードと思われるデバイスを探します。
+
+![デバイスマネージャーにおける、間違ったドライバがインストールされたキーボード](https://i.imgur.com/L3wvX8f.png)
+
+右クリックし、**デバイスのアンインストール** をクリックします。最初に **このデバイスのドライバーソフトウェアを削除します** にチェックが付いていることを確認してください。
+
+!["ドライバの削除"にチェックボックスにチェックが付いた、デバイスのアンインストールダイアログ](https://i.imgur.com/aEs2RuA.png)
+
+**Action → Scan for hardware changes** をクリックします。この時点で、再び入力できるようになっているはずです。Zadig でキーボードデバイスが `HidUsb` ドライバを使っていることを再確認します。そうであれば完了です。キーボードは再び機能するはずです！
+
+?> Windows が新しいドライバを使えるようにするために、この時点でコンピュータを完全に再起動する必要があるかもしれません。

docs/ja/faq.md

@@ -0,0 +1,11 @@
+# よくある質問
+
+<!---
+  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_build.md

@@ -0,0 +1,160 @@
+# よくあるビルドの質問
+
+<!---
+  original document: 0f43c2652:docs/faq_build.md
+  git diff 0f43c2652 HEAD -- docs/faq_build.md | cat
+-->
+
+このページは QMK のビルドに関する質問を説明します。まだビルドをしていない場合は、[ビルド環境のセットアップ](ja/getting_started_build_tools.md) および [Make 手順](ja/getting_started_make_guide.md)ガイドを読むべきです。
+
+## Linux でプログラムできません
+デバイスを操作するには適切な権限が必要です。Linux ユーザの場合は、以下の `udev` ルールに関する指示を見てください。`udev` に問題がある場合は、回避策は `sudo` コマンドを使うことです。このコマンドに慣れていない場合は、`man sudo` コマンドでマニュアルを確認するか、[この web ページを見てください](https://linux.die.net/man/8/sudo)。
+
+コントローラが ATMega32u4 の場合の `sudo` の使い方の例:
+
+    $ sudo dfu-programmer atmega32u4 erase --force
+    $ sudo dfu-programmer atmega32u4 flash your.hex
+    $ sudo dfu-programmer atmega32u4 reset
+
+あるいは、単純に:
+
+    $ sudo make <keyboard>:<keymap>:dfu
+
+`make` を `sudo` で実行することは一般的には良い考えでは***なく***、可能であれば前者の方法のいずれかを使うべきです。
+
+### Linux の `udev` ルール
+Linux では、MCU にアクセスするには適切な権限が必要です。ファームウェアを書き込む時に `sudo` を使うか、`/etc/udev/rules.d/` にこれらのファイルを配置することで、アクセスすることができます。権限の追加が完了したら、以下を実行します:
+```console
+sudo udevadm control --reload-rules
+sudo udevadm trigger
+```
+
+**/etc/udev/rules.d/50-atmel-dfu.rules:**
+```
+# Atmel ATMega32U4
+SUBSYSTEMS=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2ff4", MODE:="0666"
+# Atmel USBKEY AT90USB1287
+SUBSYSTEMS=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2ffb", MODE:="0666"
+# Atmel ATMega32U2
+SUBSYSTEMS=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2ff0", MODE:="0666"
+```
+
+**/etc/udev/rules.d/52-tmk-keyboard.rules:**
+```
+# tmk keyboard products     https://github.com/tmk/tmk_keyboard
+SUBSYSTEMS=="usb", ATTRS{idVendor}=="feed", MODE:="0666"
+```
+**/etc/udev/rules.d/54-input-club-keyboard.rules:**
+
+```
+# Input Club keyboard bootloader
+SUBSYSTEMS=="usb", ATTRS{idVendor}=="1c11", MODE:="0666"
+```
+
+**/etc/udev/rules.d/55-caterina.rules:**
+```
+# ModemManager should ignore the following devices
+ATTRS{idVendor}=="2a03", ENV{ID_MM_DEVICE_IGNORE}="1"
+ATTRS{idVendor}=="2341", ENV{ID_MM_DEVICE_IGNORE}="1"
+```
+
+**注意:** ModemManager フィルタリングは厳格モードでは無い場合のみ動作します。以下のコマンドでその設定を変更することができます:
+```console
+sudo sed -i 's/--filter-policy=strict/--filter-policy=default/' /lib/systemd/system/ModemManager.service
+sudo systemctl daemon-reload
+sudo systemctl restart ModemManager
+```
+
+**/etc/udev/rules.d/56-dfu-util.rules:**
+```
+# stm32duino
+SUBSYSTEMS=="usb", ATTRS{idVendor}=="1eaf", ATTRS{idProduct}=="0003", MODE:="0666"
+# Generic stm32
+SUBSYSTEMS=="usb", ATTRS{idVendor}=="0483", ATTRS{idProduct}=="df11", MODE:="0666"
+```
+
+**/etc/udev/rules.d/57-bootloadhid.rules:**
+```
+# bootloadHID
+SUBSYSTEMS=="usb", ATTRS{idVendor}=="16c0", ATTRS{idProduct}=="05df", MODE:="0666"
+```
+
+### Linux のブートローダモードで Serial デバイスが検知されない
+カーネルがデバイスを適切にサポートしていることを確認してください。デバイスが、Pro Micro (Atmega32u4) のように USB ACM を使う場合、`CONFIG_USB_ACM=y` を含めるようにしてください。他のデバイスは `USB_SERIAL` およびそのサブオプションを必要とするかもしれません。
+
+## DFU ブートローダの不明なデバイス
+
+Windows 上でキーボードを書き込む時に発生する問題は、ブートローダ用に間違ったドライバがインストールされているか、全くインストールされていないかによるものがほとんどです。
+
+QMK インストールスクリプト (MSYS2 あるいは WSL 内の `qmk_firmware` ディレクトリから `./util/qmk_install.sh`) を再実行するか、QMK Toolbox の再インストールでこの問題が解決するかもしれません。別のやり方として、手動で [`qmk_driver_installer`](https://github.com/qmk/qmk_driver_installer) パッケージをダウンロードして実行することができます。
+
+それでもうまく行かない場合は、Zadig をダウンロードして実行する必要があります。詳細な情報は [Zadig を使ったブートローダドライバのインストール](ja/driver_installation_zadig.md)を見てください。
+
+## USB VID と PID
+`config.h` を編集することで任意の ID を使うことができます。おそらく未使用の ID を使っても、他の製品と衝突するとても低い可能性があることを除いて、実際には問題はありません。
+
+QMK のほとんどのキーボードは、vendor ID として、`0xFEED` を使います。他のキーボードを調べて、ユニークな ID を選択してください。
+
+またこれも見てください。
+https://github.com/tmk/tmk_keyboard/issues/150
+
+ここで本当にユニークな VID:PID を買うことができます。個人的な使用にはこれは必要ないと思います。
+- http://www.obdev.at/products/vusb/license.html
+- http://www.mcselec.com/index.php?page=shop.product_details&flypage=shop.flypage&product_id=92&option=com_phpshop&Itemid=1
+
+## AVR のための BOOTLOADER_SIZE
+Teensy2.0++ ブートローダのサイズは 2048 バイトであることに注意してください。一部の Makefile には間違ったコメントがあります。
+
+```
+# Boot Section Size in *bytes*
+#   Teensy halfKay   512
+#   Teensy++ halfKay 2048
+#   Atmel DFU loader 4096       (TMK Alt Controller)
+#   LUFA bootloader  4096
+#   USBaspLoader     2048
+OPT_DEFS += -DBOOTLOADER_SIZE=2048
+```
+
+## MacOS での `avr-gcc: internal compiler error: Abort trap: 6 (program cc1)` 
+これは brew での更新に関する問題で、avr-gcc が依存するシンボリックリンクを壊します。
+
+解決法は全ての影響を受けたモジュールを削除し再インストールすることです。
+
+```
+brew rm avr-gcc
+brew rm avr-gcc@8
+brew rm dfu-programmer
+brew rm dfu-util
+brew rm gcc-arm-none-eabi
+brew rm arm-gcc-bin@8
+brew rm avrdude
+brew install avr-gcc@8
+brew install dfu-programmer
+brew install dfu-util
+brew install arm-gcc-bin@8
+brew install avrdude
+brew link --force avr-gcc@8
+brew link --force arm-gcc-bin@8
+```
+
+### `avr-gcc` と LUFA
+
+`avr-gcc` を更新し、LUFA に関連するエラーが表示された場合、例えば:
+
+`lib/lufa/LUFA/Drivers/USB/Class/Device/AudioClassDevice.h:380:5: error: 'const' attribute on function returning 'void'`
+
+今のところ、Homebrew で `avr-gcc` を 8 にロールバックする必要があります。
+
+```
+brew uninstall --force avr-gcc
+brew install avr-gcc@8
+brew link --force avr-gcc@8
+```
+
+### キーボードに書き込んだが何も起こらない、あるいはキーの押下が登録されない - ARM (rev6 planck、clueboard 60、hs60v2 など) でも同じ (Feb 2019)
+ARM ベースのチップ上での EEPROM の動作によって、保存された設定が無効になる場合があります。これはデフォルトレイヤに影響し、まだ調査中の特定の環境下でキーボードが使えなくなる*しれません*。EEPROM のリセットでこれが修正されます。
+
+[Planck rev6 reset EEPROM](https://cdn.discordapp.com/attachments/473506116718952450/539284620861243409/planck_rev6_default.bin) を使って eeprom のリセットを強制することができます。このイメージを書き込んだ後で、通常のファームウェアを書き込むと、キーボードが_通常_ の動作順序に復元されます。
+[Preonic rev3 reset EEPROM](https://cdn.discordapp.com/attachments/473506116718952450/537849497313738762/preonic_rev3_default.bin)
+
+いずれかの形式でブートマジックが有効になっている場合は、これも実行できるはずです (実行方法の詳細については、[ブートマジックドキュメント](feature_bootmagic.md)とキーボード情報を見てください)。

docs/ja/faq_debug.md

@@ -0,0 +1,161 @@
+# デバッグの FAQ
+
+<!---
+  original document: 376419a4f:docs/faq_debug.md
+  git diff 376419a4f HEAD -- docs/faq_debug.md | cat
+-->
+
+このページは、キーボードのトラブルシューティングについての様々な一般的な質問を説明します。
+
+# デバッグコンソール
+
+## `hid_listen` がデバイスを認識できない
+デバイスのデバッグコンソールの準備ができていない場合、以下のように表示されます:
+
+```
+Waiting for device:.........
+```
+
+デバイスが接続されると、*hid_listen* がデバイスを見つけ、以下のメッセージが表示されます:
+
+```
+Waiting for new device:.........................
+Listening:
+```
+
+この 'Listening:' のメッセージが表示されない場合は、[Makefile] を `CONSOLE_ENABLE=yes` に設定してビルドしてみてください
+
+Linux のような OS でデバイスにアクセスするには、権限が必要かもしれません。
+- `sudo hid_listen` を試してください
+
+## コンソールにメッセージが表示されない
+以下を調べてください:
+- *hid_listen* がデバイスを検出する。上記を見てください。
+- **Magic**+d を使ってデバッグを有効にする。[マジックコマンド](https://github.com/tmk/tmk_keyboard#magic-commands)を見てください。
+- `debug_enable=true` を設定します。[テストとデバッグ](ja/newbs_testing_debugging.md#debugging)を見てください
+- デバッグ print の代わりに 'print' 関数を使ってみてください。**common/print.h** を見てください。
+- コンソール機能を持つ他のデバイスを切断します。[Issue #97](https://github.com/tmk/tmk_keyboard/issues/97) を見てください。
+
+## Linux あるいは UNIX のようなシステムはスーパーユーザ権限を必要とします
+権限付きで *hid_listen* を実行するために 'sudo' を使ってください。
+```
+$ sudo hid_listen
+```
+
+または rules ディレクトリにファイルを置いて、TMK デバイスのための *udev rule* を追加します。ディレクトリは各システムで異なるかもしれません。
+
+File: /etc/udev/rules.d/52-tmk-keyboard.rules (Ubuntu の場合)
+```
+# tmk keyboard products     https://github.com/tmk/tmk_keyboard
+SUBSYSTEMS=="usb", ATTRS{idVendor}=="feed", MODE:="0666"
+```
+
+***
+
+# 雑多なこと
+## 安全性の考慮
+
+あなたはおそらくキーボードを「文鎮化」したくないでしょう。文鎮化するとファームウェアを書き換えられないようになります。リスクがあまりに高い(そしてそうでないかもしれない)ものの一部のリストを示します。
+
+- キーボードマップに RESET が含まれない場合、DFU モードに入るには、PCB のリセットボタンを押す必要があります。底部のネジを外す必要があります。
+- tmk_core / common にあるファイルを触るとキーボードが操作不能になるかもしれません。
+- .hex ファイルが大きすぎると問題を引き起こします; `make dfu` コマンドはブロックを削除し、
+サイズを検査し(おっと、間違った順序です！)、エラーを出力し、
+キーボードへの書き込みに失敗し、DFU モードのままになります。
+   - この目的のためには、Planck の最大の .hex ファイルサイズは 7000h (10進数で28672)であることに注意してください。
+
+```
+Linking: .build/planck_rev4_cbbrowne.elf                                                            [OK]
+Creating load file for Flash: .build/planck_rev4_cbbrowne.hex                                       [OK]
+
+Size after:
+   text    data     bss     dec     hex filename
+      0   22396       0   22396    577c planck_rev4_cbbrowne.hex
+```
+
+- 上のファイルのサイズは 22396/577ch で、28672/7000h より小さいです
+- 適切な替わりの .hex ファイルがある限り、それをロードして再試行することができます
+- あなたがキーボードの Makefile で指定したかもしれない一部のオプションは、余分なメモリを消費します; BOOTMAGIC_ENABLE、MOUSEKEY_ENABLE、EXTRAKEY_ENABLE、CONSOLE_ENABLE、API_SYSEX_ENABLE に注意してください
+- DFU ツールは(オプションの余計なフルーツサラダを投げ込まない限り)ブートローダに書き込むことを許可しないので、
+ここにはリスクはほとんどありません。
+- EEPROM の書き込みサイクルは、約100000です。ファームウェアを繰り返し継続的に書き換えるべきではありません。それは最終的に EEPROM を焼き焦がします。
+
+## NKRO が動作しません
+最初に、**Makefile** 内でビルドオプション `NKRO_ENABLE` を使ってファームウェアをコンパイルする必要があります。
+
+**NKRO** がまだ動作しない場合は、`Magic` **N** コマンド(デフォルトでは `LShift+RShift+N`)を試してみてください。**NKRO** モードと **6KRO** モード間を一時的に切り替えるためにこのコマンドを使うことができます。**NKRO** が機能しない状況、特に BIOS の場合は **6KRO** モードに切り替える必要があります。
+
+ファームウェアを `BOOTMAGIC_ENABLE` でビルドした場合、`ブートマジック` **N** コマンドで切り替える必要があります (デフォルトでは `Space+N`)。この設定は EEPROM に格納され、電源を入れ直しても保持されます。
+
+https://github.com/tmk/tmk_keyboard#boot-magic-configuration---virtual-dip-switch
+
+
+## TrackPoint はリセット回路が必要です (PS/2 マウスサポート)
+リセット回路が無いとハードウェアの不適切な初期化のために一貫性の無い結果になります。TPM754 の回路図を見てください。
+
+- http://geekhack.org/index.php?topic=50176.msg1127447#msg1127447
+- http://www.mikrocontroller.net/attachment/52583/tpm754.pdf
+
+
+## 16 を超えるマトリックの列を読み込めない
+列が 16 を超える場合、[matrix.h] の `read_cols()` 内の `1<<16` の代わりに `1UL<<16` を使ってください。
+
+C では、AVR の場合 `1` は [16 bit] である [int] 型の1を意味し、15 を超えて左にシフトすることはできません。`1<<16` すると予期しないゼロが発生します。`1UL` として [unsigned long] 型を使う必要があります。
+
+http://deskthority.net/workshop-f7/rebuilding-and-redesigning-a-classic-thinkpad-keyboard-t6181-60.html#p146279
+
+## 特別なエクストラキーが動作しない (システム、オーディオコントロールキー)
+QMK でそれらを使うには、`rules.mk` 内で `EXTRAKEY_ENABLE` を定義する必要があります。
+
+```
+EXTRAKEY_ENABLE = yes          # オーディオ制御とシステム制御
+```
+
+## スリープから復帰しない
+
+Windows では、**デバイスマネージャ**の**電源の管理**タブ内の `このデバイスで、コンピュータのスタンバイ状態を解除できるようにする` 設定を調べてください。また BIOS 設定も調べてください。
+
+スリープ中に任意のキーを押すとホストが起動するはずです。
+
+## Arduino を使っていますか？
+
+**Arduino のピンの命名は実際のチップと異なることに注意してください。** 例えば、Arduino のピン `D0` は `PD0` ではありません。回路図を自身で確認してください。
+
+- http://arduino.cc/en/uploads/Main/arduino-leonardo-schematic_3b.pdf
+- http://arduino.cc/en/uploads/Main/arduino-micro-schematic.pdf
+
+Arduino の Leonardo と micro には **ATMega32U4** が載っていて、TMK 用に使うことができますが、Arduino のブートローダが問題になることがあります。
+
+## JTAG を有効にする
+
+デフォルトでは、キーボードが起動するとすぐに JTAG デバッグインタフェースが無効になります。JTAG 対応 MCU は `JTAGEN` ヒューズが設定された状態で出荷されており、キーボードがスイッチマトリックス、LED などに使用している可能性のある MCU の特定のピンを乗っ取ります。
+
+JTAG を有効にしたままにしたい場合は、単に以下のものを `config.h` に追加します:
+
+```c
+#define NO_JTAG_DISABLE
+```
+
+## USB 3 の互換性
+USB 3 ポートで問題がある人がいると聞きました。USB 2 ポートを試してください。
+
+
+## Mac の互換性
+### OS X 10.11 と Hub
+https://geekhack.org/index.php?topic=14290.msg1884034#msg1884034
+
+
+## リジューム (スリープとウェークアップ)/電源サイクルの問題
+一部の人がキーボードが BIOS で動作しなくなった、またはリジューム(電源サイクル)の後で動作しなくなったと報告しました。
+
+今のところ、この問題の根本は明確ではないですが、幾つかのビルドオプションが関係しているようです。Makefileで、`CONSOLE_ENABLE`、`NKRO_ENABLE`、`SLEEP_LED_ENABLE` あるいは他のオプションを無効にしてみてください。
+
+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

@@ -0,0 +1,20 @@
+# よくある質問
+
+<!---
+  original document: d598f01cb:docs/faq_general.md
+  git diff d598f01cb 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)から始まりました。
+
+## QMK と TMK の違いは何か？
+
+TMK は [Jun Wako](https://github.com/tmk) によって設計され実装されました。QMK は [Jack Humbert](https://github.com/jackhumbert) の Planck 用 TMK のフォークとして始まりました。しばらくして、Jack のフォークは TMK からかなり分岐し、2015年に Jack はフォークを QMK に名前を変えることにしました。
+
+技術的な観点から、QMK は幾つかの新しい機能を追加した TMK に基づいています。最も注目すべきことは、QMK は利用可能なキーコードの数を増やし、`S()`、`LCTL()` および `MO()` などの高度な機能を実装するためにこれらを使っています。[キーコード](keycodes.md)でこれらのキーコードの完全なリストを見ることができます。
+
+プロジェクトとコミュニティの管理の観点から、TMK は公式にサポートされている全てのキーボードを自分で管理しており、コミュニティのサポートも少し受けています。他のキーボード用に別個のコミュニティが維持するフォークが存在するか、作成できます。デフォルトでは少数のキーマップのみが提供されるため、ユーザは一般的にお互いにキーマップを共有しません。QMK は集中管理されたリポジトリを介して、キーボードとキーマップの両方を共有することを奨励しており、品質基準に準拠する全てのプルリクエストを受け付けます。これらはほとんどコミュニティで管理されますが、必要な場合は QMK チームも支援します。
+
+どちらのアプローチもメリットとデメリットがあり、理に適う場合は TMK と QMK の間でコードは自由にやり取りされます。

docs/ja/faq_keymap.md

@@ -0,0 +1,149 @@
+# キーマップの FAQ
+
+<!---
+  original document: 376419a4f:docs/faq_keymap.md
+  git diff 376419a4f HEAD -- docs/faq_keymap.md | cat
+-->
+
+このページは人々がキーマップについてしばしば持つ疑問について説明します。まだ読んだことが無い場合には、[キーマップの概要](ja/keymap.md)を最初に読むべきです。
+
+## どのキーコードを使えますか？
+あなたが利用可能なキーコードのインデックスについては、[キーコード](ja/keycodes.md)を見てください。より広範なドキュメントがある場合は、そこからリンクしてあります。
+
+キーコードは実際には [common/keycode.h](https://github.com/qmk/qmk_firmware/blob/master/tmk_core/common/keycode.h) で定義されています。
+
+## デフォルトのキーコードとは何か？
+
+世界中で使用されている ANSI、ISO および JIS の3つの標準キーボードがあります。北米では主に ANSI が使われ、ヨーロッパおよびアフリカでは主に ISO が使われ、日本では JIS が使われます。言及されていない地域では、ANSI あるいは ISO が使われています。これらのレイアウトに対応するキーコードは以下の通りです:
+
+<!-- Source for this image: http://www.keyboard-layout-editor.com/#/gists/bf431647d1001cff5eff20ae55621e9a -->
+![キーボードのレイアウトイメージ](https://i.imgur.com/5wsh5wM.png)
+
+## 一部のキーが入れ替わっているか、または動作しない
+
+QMK には2つの機能、ブートマジックとコマンドがあり、これによりその場でキーボードの動作を変更することができます。これには Ctrl/Caps の交換、Gui の無効化、Alt/GUI の交換、Backspace/Backslash の交換、全てのキーの無効化およびその他の動作の変更が含まれますが、これらに限定されません。
+
+迅速な解決策として、キーボードを接続している時に `Space`+`Backspace` を押してみてください。これはキーボードに保存されている設定をリセットし、これらのキーを通常の操作に戻します。うまく行かない場合は、以下を見てください:
+
+* [ブートマジック](ja/feature_bootmagic.md)
+* [コマンド](ja/feature_command.md)
+
+## メニューキーが動作しない
+
+ほとんどの最近のキーボードにある、`KC_RGUI` と `KC_RCTL` の間にあるキーは、実際には `KC_APP` と呼ばれます。これは、そのキーが発明された時に、関連する標準にすでに `MENU` という名前のキーが存在していたため、MS はそれを `APP` キーと呼ぶことを選択したためです。
+
+## `KC_SYSREQ` が動作しません
+`KC_SYSREQ` の代わりに、Print Screen(`KC_PSCREEN` あるいは `KC_PSCR`) のキーコードを使ってください。'Alt + Print Screen' のキーの組み合わせは、'システムリクエスト' と認識されます。
+
+[issue #168](https://github.com/tmk/tmk_keyboard/issues/168) と以下を見てください
+* http://en.wikipedia.org/wiki/Magic_SysRq_key
+* http://en.wikipedia.org/wiki/System_request
+
+## 電源キーが動作しません
+
+やや紛らわしいことに、QMK には2つの "Power" キーコードがあります: キーボード/キーパッド HID usage page では `KC_POWER`、Consumer page では `KC_SYSTEM_POWER` (あるいは `KC_PWR`)。
+
+前者は macOS でのみ認識されますが、後者 `KC_SLEP` および `KC_WAKE` は3つの主要なオペレーティングシステム全てでサポートされるため、これらを使うことをお勧めします。Windows ではこれらのキーはすぐに機能しますが、macOS ではそれらはダイアログが表示されるまで押し続ける必要があります。
+
+## ワンショットモディファイア
+私の個人的な 'the' の問題を解決します。'The' ではなく 'the' あるいは 'THe' を間違って入力することがありました。ワンショットシフトはこれを軽減します。
+https://github.com/tmk/tmk_keyboard/issues/67
+
+## モディファイヤ/レイヤスタック
+修飾キーあるいはレイヤは、レイヤの切り替えが適切に設定されていない場合、スタックするかもしれません。
+修飾キーおよびレイヤ切り替えの場合、リリースイベント時に修飾キーの登録を解除する、もしくは前のレイヤに戻るために、目的のレイヤの同じ位置に `KC_TRANS` を配置する必要があります。
+
+* https://github.com/tmk/tmk_core/blob/master/doc/keymap.md#31-momentary-switching
+* http://geekhack.org/index.php?topic=57008.msg1492604#msg1492604
+* https://github.com/tmk/tmk_keyboard/issues/248
+
+
+## メカニカルロックスイッチのサポート
+
+この機能は [Alps](http://deskthority.net/wiki/Alps_SKCL_Lock) のような*メカニカルロックスイッチ*用です。以下を `config.h` に追加することで有効にすることができます:
+
+```
+#define LOCKING_SUPPORT_ENABLE
+#define LOCKING_RESYNC_ENABLE
+```
+
+この機能を有効にした後で、キーマップでキーコード `KC_LCAP`、`KC_LNUM` および `KC_LSCR` を使います。
+
+古いビンテージメカニカルキーボードにはロックスイッチが付いている場合がありますが、最新のものにはありません。***ほとんどの場合この機能は必要なく、単にキーコード `KC_CAPS`、`KC_NLCK` および `KC_SLCK`*** を使います。
+
+## セディーユ 'Ç' のような ASCII 以外の特別文字の入力
+
+[ユニコード](ja/feature_unicode.md) 機能を見てください。
+
+## macOS での `Fn` キー
+
+ほとんどの Fn キーと異なり、Apple のキーボードの Fn キーには実際には独自のキーコードのようなものがあります。基本的な 6KRO HID レポートの6番目のキーコードの代わりになります -- つまり、Apple キーボードは実際には 5KRO のみです。
+
+QMK にこのキーを送信させることは技術的に可能です。ただし、そうするには Fn キーの状態を追加するためにレポート形式の修正を必要とします。 
+さらに悪いことに、キーボードの VID と PID が実際の Apple のキーボードのものと一致しない限り、認識されません。公式の QMK がこの機能をサポートすることで法的な問題が起きるため、サポートされることはないでしょう。
+
+詳細については、[この issue](https://github.com/qmk/qmk_firmware/issues/2179) を見てください。
+
+## Mac OSX でサポートされるキーは？
+このソースコードから、どのキーコードが OSX でサポートされるかを知ることができます。
+
+`usb_2_adb_keymap` 配列は、キーボード/キーパッドページの Page usages を ADB スキャンコード(OSX 内部キーコード)にマップします。
+
+https://opensource.apple.com/source/IOHIDFamily/IOHIDFamily-606.1.7/IOHIDFamily/Cosmo_USB2ADB.c
+
+`IOHIDConsumer::dispatchConsumerEvent` は Consumer page usages を処理します。
+
+https://opensource.apple.com/source/IOHIDFamily/IOHIDFamily-606.1.7/IOHIDFamily/IOHIDConsumer.cpp
+
+
+## Mac OSX での JIS キー
+`無変換(Muhenkan)`, `変換(Henkan)`, `ひらがな(hiragana)` のような日本語 JIS キーボード固有のキーは OSX では認識されません。**Seil** を使ってこれらのキーを使うことができます。以下のオプションを試してください。
+
+* PC キーボードで NFER キーを有効にする
+* PC キーボードで XFER キーを有効にする
+* PC キーボードで KATAKANA キーを有効にする
+
+https://pqrs.org/osx/karabiner/seil.html
+
+
+## RN-42 Bluetooth が Karabiner で動作しない
+Karabiner - Mac OSX 上のキーマッピングツール - は、デフォルトでは RN-42 モジュールからの入力を無視します。Karabiner をキーボードで動作させるにはこのオプションを有効にする必要があります。
+https://github.com/tekezo/Karabiner/issues/403#issuecomment-102559237
+
+この問題の詳細についてはこれらを見てください。
+https://github.com/tmk/tmk_keyboard/issues/213
+https://github.com/tekezo/Karabiner/issues/403
+
+
+## 単一のキーでの Esc と<code>&#96;</code>
+
+[Grave Escape](feature_grave_esc.md) 機能を見てください。
+
+## Mac OSX での Eject
+`KC_EJCT` キーコードは OSX で動作します。https://github.com/tmk/tmk_keyboard/issues/250
+Windows 10 はコードを無視し、Linux/Xorg は認識しますが、デフォルトではマッピングがありません。
+
+実際の Apple キーボードにある Eject キーコードは実際には分かりません。HHKB は Mac モードでは Eject キー (`Fn+f`) に `F20` を使いますが、これはおそらく Apple の Eject キーコードと同じではありません。
+
+
+## `action_util.c` の `weak_mods` と `real_mods` は何か
+___改善されるべきです___
+
+real_mods は実際の物理的な修飾キーの状態を保持することを目的にしていますが、weak_mods は実際の修飾キーの状態に影響しない仮想あるいは一時的なモディファイアの状態を保持します。
+
+物理的な左シフトキーを押しながら ACTION_MODS_KEY(LSHIFT, KC_A) を入力するとします
+
+weak_mods では、
+* (1) 左シフトキーを押し続ける: real_mods |= MOD_BIT(LSHIFT)
+* (2) ACTION_MODS_KEY(LSHIFT, KC_A) を押す: weak_mods |= MOD_BIT(LSHIFT)
+* (3) ACTION_MODS_KEY(LSHIFT, KC_A) を放す: weak_mods &= ~MOD_BIT(LSHIFT)
+real_mods はモディファイアの状態を維持します。
+
+weak mods 無しでは、
+* (1) 左シフトキーを押し続ける: real_mods |= MOD_BIT(LSHIFT)
+* (2) ACTION_MODS_KEY(LSHIFT, KC_A) を押す: real_mods |= MOD_BIT(LSHIFT)
+* (3) ACTION_MODS_KEY(LSHIFT, KC_A) を放す: real_mods &= ~MOD_BIT(LSHIFT)
+ここで、real_mods は 'physical left shift' '物理的な左シフト' の状態を見失います。
+
+キーボードレポートが送信される時、weak_mods は real_mods と論理和がとられます。
+https://github.com/tmk/tmk_core/blob/master/common/action_util.c#L57

docs/ja/flashing.md

@@ -0,0 +1,247 @@
+# 書き込みの手順とブートローダ情報
+
+<!---
+  original document: 7494490d6:docs/flashing.md
+  git diff 7494490d6 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`。
+
+## DFU
+
+Atmel の DFU ブートローダはデフォルトで全ての atmega32u4 チップに搭載されており、PCB (旧 OLKB キーボード、Clueboard) に独自の IC を持つ多くのキーボードで使われています。一部のキーボードは、LUFA の DFU ブートローダ(または QMK のフォーク) (新しい OLKB キーボード)を使う場合もあり、そのハードウェアに固有の追加機能が追加されます。
+
+DFU ブートローダとの互換性を確保するために、以下のブロックが `rules.mk` にあることを確認してください(オプションとして代わりに `lufa-dfu` や `qmk-dfu` が使えます):
+
+```make
+# Bootloader selection
+#   Teensy       halfkay
+#   Pro Micro    caterina
+#   Atmel DFU    atmel-dfu
+#   LUFA DFU     lufa-dfu
+#   QMK DFU      qmk-dfu
+#   ATmega32A    bootloadHID
+#   ATmega328P   USBasp
+BOOTLOADER = atmel-dfu
+```
+
+互換性のあるフラッシャ:
+
+* [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) (非推奨)
+
+書き込み手順:
+
+1. `RESET` キーコードを押すか、RESET ボタンをタップします(または RST を GND にショートします)。
+2. OS がデバイスを検知するのを待ちます。
+3. メモリを消去します(自動的に実行されるかもしれません)
+4. .hex ファイルを書き込みます
+5. デバイスをアプリケーションモードにリセットします(自動的に実行されるかもしれません)
+
+あるいは:
+
+    make <keyboard>:<keymap>:dfu
+
+### QMK DFU
+
+QMK には LUFA DFU ブートローダのフォークがあり、ブートローダを終了してアプリケーションに戻る時に単純なマトリックススキャンを行うことができます。また、何かが起きた時に、LED を点滅したり、スピーカーでカチカチ音をたてたりします。これらの機能を有効にするには、`config.h` で以下のブロックを有効にします (ブートローダを終了するキーは、ここで定義された INPUT と OUTPUT に接続する必要があります):
+
+    #define QMK_ESC_OUTPUT F1 // 通常 COL
+    #define QMK_ESC_INPUT D5 // 通常 ROW
+    #define QMK_LED E6
+    #define QMK_SPEAKER C6
+
+製造元と製品名は `config.h` から自動的に取得され、製品に「Bootloader」が追加されます。
+
+このブートローダを生成するには、`bootloader` ターゲット、例えば `make planck/rev4:default:bootloader` を使います。
+
+実稼働対応の .hex ファイル(アプリケーションおよびブートローダを含む)を生成するには、`production` ターゲット、例えば `make planck/rev4:default:production` を使います。
+
+### DFU コマンド
+
+ファームウェアを DFU デバイスに書き込むために使用できる DFU コマンドがいくつかあります。
+
+* `:dfu` - これが通常のオプションで、DFU デバイスが使用可能になるまで待機したのちファームウェアを書き込みます。5秒ごとに、DFU デバイスが存在するかチェックしています。
+* `:dfu-ee` - 通常の hex ファイルの代わりに `eep` ファイルを書き込みます。これを使用するのはまれです。
+* `:dfu-split-left` - デフォルトオプション (`:dfu`) と同様に、通常のファームウェアが書き込まれます。ただし、分割キーボードの「左側の」 EEPROM ファイルも書き込まれます。_これは、Elite C ベースの分割キーボードに最適です。_
+* `:dfu-split-right` - デフォルトオプション (`:dfu`) と同様に、通常のファームウェアが書き込まれます。ただし、分割キーボードの「右側の」 EEPROM ファイルも書き込まれます。_これは、Elite C ベースの分割キーボードに最適です。_
+
+## Caterina
+
+Arduino ボードとそのクローンは [Caterina ブートローダ](https://github.com/arduino/ArduinoCore-avr/tree/master/bootloaders/caterina) (Pro Micro またはそのクローンで構築されたキーボード)を使用し、avr109 プロトコルを使って仮想シリアルを介して通信します。[A-Star](https://www.pololu.com/docs/0J61/9) のようなブートローダは Caterina に基づいています。
+
+Caterina ブートローダとの互換性を確保するために、以下のブロックが `rules.mk` にあることを確認してください:
+
+```make
+# Bootloader selection
+#   Teensy       halfkay
+#   Pro Micro    caterina
+#   Atmel DFU    atmel-dfu
+#   LUFA DFU     lufa-dfu
+#   QMK DFU      qmk-dfu
+#   ATmega32A    bootloadHID
+#   ATmega328P   USBasp
+BOOTLOADER = caterina
+```
+
+互換性のあるフラッシャ:
+
+* [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) (推奨の GUI)
+* avr109 を使った [avrdude](http://www.nongnu.org/avrdude/) / `:avrdude` (推奨のコマンドライン)
+* [AVRDUDESS](https://github.com/zkemble/AVRDUDESS)
+
+書き込み手順:
+
+1. `RESET` キーコードを押すか、RST をすばやく GND にショートします (入力後7秒で書き込みます)
+2. OS がデバイスを検知するのを待ちます。
+3. .hex ファイルを書き込みます
+4. デバイスが自動的にリセットされるのを待ちます
+
+あるいは
+
+    make <keyboard>:<keymap>:avrdude
+
+
+#### Caterina コマンド
+
+ファームウェアを DFU デバイスに書き込むために使用できる DFU コマンドがいくつかあります。
+
+* `:avrdude` - これが通常のオプションで、Caterina デバイスが(新しい COM ポートを検出して)使用可能になるまで待機し、ファームウェアを書き込みます。
+* `:avrdude-loop` - これは `:avrdude` と同じコマンドを実行します。ただし書き込みが終了すると再び Caterina デバイスの書き込み待ちに戻ります。これは何台ものデバイスへ書き込むのに便利です。_Ctrl+C を押して、手動でこの繰り返しを終了させる必要があります。_
+* `:avrdude-split-left` - デフォルトオプション (`:avrdude`) と同様に通常のファームウェアが書き込まれます。ただし、分割キーボードの「左側の」 EEPROM ファイルも書き込まれます。_これは、Pro Micro ベースの分割キーボードに最適です。_
+* `:avrdude-split-right` - デフォルトオプション (`:avrdude`) と同様に通常のファームウェアが書き込まれます。ただし、分割キーボードの「右側の」 EEPROM ファイルも書き込まれます。_これは、Pro Micro ベースの分割キーボードに最適です。_
+
+
+
+## Halfkay
+
+Halfkay は PJRC によって開発された超スリムなプロトコルであり、HID を使用し、全ての Teensys (つまり 2.0)に搭載されています。
+
+Halfkay ブートローダとの互換性を確保するために、以下のブロックが `rules.mk` にあることを確認してください:
+
+```make
+# Bootloader selection
+#   Teensy       halfkay
+#   Pro Micro    caterina
+#   Atmel DFU    atmel-dfu
+#   LUFA DFU     lufa-dfu
+#   QMK DFU      qmk-dfu
+#   ATmega32A    bootloadHID
+#   ATmega328P   USBasp
+BOOTLOADER = halfkay
+```
+
+互換性のあるフラッシャ:
+
+* [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) (推奨の GUI)
+* [Teensy ローダー](https://www.pjrc.com/teensy/loader.html)
+* [Teensy ローダーコマンドライン](https://www.pjrc.com/teensy/loader_cli.html) (推奨のコマンドライン)
+
+書き込み手順:
+
+1. `RESET` キーコードを押すか、RST をすばやく GND にショートします (入力後7秒で書き込みます)
+2. OS がデバイスを検知するのを待ちます。
+3. .hex ファイルを書き込みます
+4. デバイスをアプリケーションモードにリセットします(自動的に実行されるかもしれません)
+
+## USBasploader
+
+USBasploader は matrixstorm によって開発されたブートローダです。V-USB を実行する ATmega328P のような非 USB AVR チップで使われます。
+
+USBasploader ブートローダとの互換性を確保するために、以下のブロックが `rules.mk` にあることを確認してください:
+
+```make
+# Bootloader selection
+#   Teensy       halfkay
+#   Pro Micro    caterina
+#   Atmel DFU    atmel-dfu
+#   LUFA DFU     lufa-dfu
+#   QMK DFU      qmk-dfu
+#   ATmega32A    bootloadHID
+#   ATmega328P   USBasp
+BOOTLOADER = USBasp
+```
+
+互換性のあるフラッシャ:
+
+* [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) (推奨の GUI)
+* `usbasp` プログラマを使った [avrdude](http://www.nongnu.org/avrdude/)
+* [AVRDUDESS](https://github.com/zkemble/AVRDUDESS)
+
+書き込み手順:
+
+1. `RESET` キーコードを押すか、RST を GND にすばやくショートしながら、ブートピンを GND にショートしたままにします。
+2. OS がデバイスを検知するのを待ちます。
+3. .hex ファイルを書き込みます
+4. デバイスをアプリケーションモードにリセットします(自動的に実行されるかもしれません)
+
+## BootloadHID
+
+BootloadHID は AVR マイクロコントローラ用の USB ブートローダです。アップローダーツールは Windows でカーネルレベルのドライバを必要としないため、DLL をインストールせずに実行することができます。
+
+bootloadHID ブートローダとの互換性を確保するために、以下のブロックが `rules.mk` にあることを確認してください:
+
+```make
+# Bootloader selection
+#   Teensy       halfkay
+#   Pro Micro    caterina
+#   Atmel DFU    atmel-dfu
+#   LUFA DFU     lufa-dfu
+#   QMK DFU      qmk-dfu
+#   ATmega32A    bootloadHID
+#   ATmega328P   USBasp
+BOOTLOADER = bootloadHID
+```
+
+互換性のあるフラッシャ:
+
+* [HIDBootFlash](http://vusb.wikidot.com/project:hidbootflash) (推奨の Windows GUI)
+* [bootloadhid コマンドライン](https://www.obdev.at/products/vusb/bootloadhid.html) / QMK の `:BootloadHID` (推奨のコマンドライン)
+
+書き込み手順:
+
+1. 以下のいずれかの方法を使ってブートローダに入ります:
+   * `RESET` キーコードをタップします (全てのデバイスでは動作しないかもしれません)
+   * キーボードを接続しながらソルトキーを押し続けます (通常はキーボードの readme に書かれています)
+2. OS がデバイスを検知するのを待ちます。
+3. .hex ファイルを書き込みます
+4. デバイスをアプリケーションモードにリセットします(自動的に実行されるかもしれません)
+
+あるいは:
+
+    make <keyboard>:<keymap>:bootloadHID
+
+## STM32
+
+全ての STM32 チップには、変更も削除もできない工場出荷時のブートローダがプリロードされています。一部の STM32 チップには USB プログラミングが付属していないブートローダがありますが(例えば STM32F103)、プロセスは同じです。
+
+現時点では、STM32 の `rules.mk` には、`BOOTLOADER` 変数は不要です。
+
+互換性のあるフラッシャ:
+
+* [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) (推奨の GUI)
+* [dfu-util](https://github.com/Stefan-Schmidt/dfu-util) / `:dfu-util` (推奨のコマンドライン)
+
+書き込み手順:
+
+1. 以下のいずれかの方法を使ってブートローダに入ります:
+   * `RESET` キーコードをタップします (STM32F042 デバイスでは動作しないかもしれません)
+   * リセット回路が存在する場合、RESET ボタンをタップします
+   * それ以外の場合は、(BOOT0 ボタンあるいはブリッジ経由で)BOOT0 を VCC にブリッジし、(REEST ボタンあるいはブリッジ経由で)RESET を GND にショートし、BOOT0 ブリッジを放す必要があります。
+2. OS がデバイスを検知するのを待ちます。
+3. .bin ファイルを書き込みます
+   * DFU 署名に関する警告が表示されます; 無視してください
+4. デバイスをアプリケーションモードにリセットします(自動的に実行されるかもしれません)
+   * コマンドラインからビルドする場合(例えば、`make planck/rev6:default:dfu-util`)、`rules.mk` の中で `:leave` が `DFU_ARGS` 変数に渡されるようにしてください (例えば、`DFU_ARGS = -d 0483:df11 -a 0 -s 0x08000000:leave`)。そうすれば、書き込みの後でデバイスがリセットされます
+
+### STM32 コマンド
+
+ファームウェアを STM32 デバイスに書き込むために使用できる DFU コマンドがいくつかあります。
+
+* `:dfu-util` - STM32 デバイスに書き込むためのデフォルトコマンドで、STM32 ブートローダデバイスが見つかるまで待機します。
+* `:dfu-util-split-left` - デフォルトのオプション (`:dfu-util`) と同様に、通常のファームウェアが書き込まれます。ただし、分割キーボードの「左側の」 EEPROM の設定も行われます。
+* `:dfu-util-split-right` - デフォルトのオプション (`:dfu-util`) と同様に、通常のファームウェアが書き込まれます。ただし、分割キーボードの「右側の」 EEPROM の設定も行われます。
+* `:st-link-cli` - dfu-util ではなく、ST-LINK の CLI ユーティリティを介してファームウェアを書き込めます。

docs/ja/getting_started_build_tools.md

@@ -0,0 +1,146 @@
+# ビルドツールのインストール
+
+<!---
+  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,8 +1,8 @@
 # 助けを得る
 
 <!---
-  original document: d598f01cb:getting_started_getting_help.md
-  git diff d598f01cb HEAD getting_started_getting_help.md | cat
+  original document: d598f01cb:docs/getting_started_getting_help.md
+  git diff d598f01cb HEAD -- docs/getting_started_getting_help.md | cat
 -->
 
 QMK に関して助けを得るための多くのリソースがあります。

docs/ja/getting_started_github.md

@@ -1,8 +1,8 @@
 # QMK で Github を使う方法
 
 <!---
-  original document: d598f01cb:getting_started_github.md
-  git diff d598f01cb HEAD getting_started_github.md | cat
+  original document: d598f01cb:docs/getting_started_github.md
+  git diff d598f01cb HEAD -- docs/getting_started_github.md | cat
 -->
 
 Github は慣れていない人には少し注意が必要です - このガイドは、QMK におけるフォーク、クローン、プルリクエストのサブミットの各ステップについて説明します。
@@ -21,17 +21,23 @@ Github は慣れていない人には少し注意が必要です - このガイ
 
 ![HTTPS リンク](http://i.imgur.com/eGO0ohO.jpg)
 
-ここから、`git clone` をコマンドラインに入力し、リンクを貼り付けます:
+ここから、`git clone --recurse-submodules ` をコマンドラインに入力し、リンクを貼り付けます:
 
 ```
 user@computer:~$ git clone --recurse-submodules https://github.com/whoeveryouare/qmk_firmware.git
 Cloning into 'qmk_firmware'...
-remote: Counting objects: 46625, done.
-remote: Compressing objects: 100% (2/2), done.
-remote: Total 46625 (delta 0), reused 0 (delta 0), pack-reused 46623
-Receiving objects: 100% (46625/46625), 84.47 MiB | 3.14 MiB/s, done.
-Resolving deltas: 100% (29362/29362), done.
-Checking out files: 100% (2799/2799), done.
+remote: Enumerating objects: 9, done.
+remote: Counting objects: 100% (9/9), done.
+remote: Compressing objects: 100% (5/5), done.
+remote: Total 183883 (delta 5), reused 4 (delta 4), pack-reused 183874
+Receiving objects: 100% (183883/183883), 132.90 MiB | 9.57 MiB/s, done.
+Resolving deltas: 100% (119972/119972), done.
+...
+Submodule path 'lib/chibios': checked out '587968d6cbc2b0e1c7147540872f2a67e59ca18b'
+Submodule path 'lib/chibios-contrib': checked out 'ede48346eee4b8d6847c19bc01420bee76a5e486'
+Submodule path 'lib/googletest': checked out 'ec44c6c1675c25b9827aacd08c02433cccde7780'
+Submodule path 'lib/lufa': checked out 'ce10f7642b0459e409839b23cc91498945119b4d'
+Submodule path 'lib/ugfx': checked out '3e97b74e03c93631cdd3ddb2ce43b963fdce19b2'
 ```
 
 ローカルマシンに QMK のフォークができるので、キーマップの追加、コンパイル、キーボードへの書き込みができます。変更に満足したら、以下のようにそれらをフォークへ追加、コミットおよびプッシュすることができます:

docs/ja/getting_started_introduction.md

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

docs/ja/getting_started_make_guide.md

@@ -0,0 +1,153 @@
+# より詳細な `make` 手順
+
+<!---
+  original document: 5f35203d1:docs/getting_started_make_guide.md
+  git diff 5f35203d1 HEAD -- docs/getting_started_make_guide.md | cat
+-->
+
+`make` コマンドの完全な構文は `<keyboard_folder>:<keymap>:<target>` です:
+
+* `<keyboard_folder>` はキーボードのパスです。例えば、`planck`
+   * 全てのキーボードをコンパイルするには `all` を使います。
+   * リビジョンを選択してコンパイルするためのパスを指定します。例えば `planck/rev4` あるいは `planck/rev3`
+   * キーボードにフォルダが無い場合は、省略することができます
+   * デフォルトのフォルダをコンパイルする場合は、省略することができます
+* `<keymap>` はキーマップの名前です。例えば、`algernon`
+   * 全てのキーマップをコンパイルするには `all` を使います。
+* `<target>` の詳細は以下で説明します。
+
+`<target>` は以下を意味します
+* target が指定されない場合は、以下の `all` と同じです
+* `all` は指定されたキーボード/リビジョン/キーマップの可能な全ての組み合わせのコンパイルを行います。例えば、`make planck/rev4:default` は1つの .hex を生成しますが、`make planck/rev4:all` は planck で利用可能な全てのキーマップについて hex を生成します。
+* `flash`、`dfu`、`teensy`、`avrdude`、`dfu-util` または `bootloadHID` はファームウェアをコンパイルし、キーボードにアップロードします。コンパイルが失敗すると、何もアップロードされません。使用するプログラマはキーボードに依存します。ほとんどのキーボードでは `dfu` ですが、ChibiOS キーボードについては `dfu-util` 、標準的な Teensy については `teensy` を使います。キーボードに使うコマンドを見つけるには、キーボード固有の readme をチェックしてください。
+* **注意**: 一部のオペレーティングシステムではこれらのコマンドが機能するためには root アクセスが必要です。その場合、例えば `sudo make planck/rev4:default:flash` を実行する必要があります。
+* `clean` は、全てをゼロからビルドするためにビルド出力フォルダを掃除します。説明できない問題がある場合は、通常のコンパイルの前にこれを実行してください。
+
+make コマンドの最後、つまり target の後に追加のオプションを追加することもできます
+
+* `make COLOR=false` - カラー出力をオフ
+* `make SILENT=true` - エラー/警告以外の出力をオフ
+* `make VERBOSE=true` - 全ての gcc のものを出力 (デバッグする必要が無い限り面白くありません)
+* `make EXTRAFLAGS=-E` - コンパイルせずにコードを前処理 (#define コマンドをデバッグしようとする場合に便利)
+
+make コマンド自体にもいくつかの追加オプションがあります。詳細は `make --help` を入力してください。最も有用なのはおそらく `-jx` です。これは複数の CPU を使ってコンパイルしたいことを指定し、`x` は使用したい CPU の数を表します。設定すると、特に多くのキーボード/キーマップをコンパイルしている場合は、コンパイル時間を大幅に短縮することができます。通常は、コンパイル中に他の作業を行うための余裕をもたせるために、持っている CPU の数より1つ少ない値に設定します。全てのオペレーティングシステムと make バージョンがオプションをサポートしているわけではないことに注意してください。
+
+コマンドの例を幾つか示します
+
+* `make all:all` は、全てをビルドします (全てのキーボードフォルダ、全てのキーマップ)。`root` から単に `make` を実行すると、これを実行します。
+* `make ergodox_infinity:algernon:clean` は、Ergodox Infinity キーボードのビルド出力を掃除します。
+* `make planck/rev4:default:flash COLOR=false` カラー出力なしでキーマップをビルドしアップロードします。
+
+## `rules.mk` オプション
+
+無効にするにはこれらの変数を `no` に設定します。有効にするには `yes` に設定します。
+
+`BOOTMAGIC_ENABLE`
+
+これにより、1つのキーとソルトキー(デフォルトではスペース)を押し続けることで、電力が失われても持続する様々な EEPROM 設定へアクセスできます。誤って設定が変更されることが多く、デバッグするのが難しい混乱した結果を生成するため、これを無効にしておくことをお勧めします。ヘルプセッションで発生する、より一般的な問題の1つです。
+
+`MOUSEKEY_ENABLE`
+
+これにより、キーコード/カスタム関数を介して、カーソルの動きとクリックを制御することができます。
+
+`EXTRAKEY_ENABLE`
+
+これにより、システムとオーディオ制御キーコードを使うことができます。
+
+`CONSOLE_ENABLE`
+
+これにより、[`hid_listen`](https://www.pjrc.com/teensy/hid_listen.html) を使って読むことができるメッセージを出力することができます。
+
+デフォルトで、全てのデバッグ( *dprint* ) 出力 ( *print*、*xprintf* )、およびユーザ出力 ( *uprint* ) メッセージが有効になります。これにより、フラッシュメモリの大部分が消費され、キーボードの .hex ファイルが大きすぎてプログラムできなくなるかもしれません。
+
+デバッグメッセージ( *dprint* ) を無効にし、.hex ファイルのサイズを小さくするには、`config.h` に `#define NO_DEBUG` を含めます。
+
+出力メッセージ( *print*、*xprintf* )とユーザ出力( *uprint* ) を無効にし、.hex のファイルサイズを小さくするには、`config.h` に `#define NO_PRINT` を含めます。
+
+出力メッセージ ( *print*、*xprintf* ) を無効にし、ユーザメッセージ ( *uprint* )を**そのままにする**には、`config.h` に `#define USER_PRINT` を含めます(この場合は、`#define NO_PRINT` も含めないでください)。
+
+テキストを見るには、`hid_listen` を開き、出力メッセージを見るのを楽しんでください。
+
+**注意:** キーマップコード以外の *uprint* メッセージを含めないでください。QMK システムフレームワーク内で使うべきではありません。さもないと、他の人の .hex ファイルが肥大化します。
+
+`COMMAND_ENABLE`
+
+これはマジックコマンドを有効にし、通常はデフォルトのマジックキーの組み合わせ `LSHIFT+RSHIFT+KEY` で起動されます。マジックコマンドは、デバッグメッセージ (`MAGIC+D`) の有効化や NKRO の一時的な切り替え (`MAGIC+N`) を含みます。
+
+`SLEEP_LED_ENABLE`
+
+コンピュータがスリープの間に LED がブレスできるようにします。ここでは Timer1 が使われます。この機能は大部分が未使用でテストされておらず、更新もしくは抽象化が必要です。
+
+`NKRO_ENABLE`
+
+これにより、キーボードはホスト OS に最大 248 個のキーが同時に押されていることを伝えることができます (NKRO 無しのデフォルトは 6 です)。NKRO は、`NKRO_ENABLE` が設定されていたとしても、デフォルトではオフです。config.h に `#define FORCE_NKRO` を追加するか、`MAGIC_TOGGLE_NKRO` をキーにバインドしてキーを押すことで、NKRO を強制することができます。
+
+`BACKLIGHT_ENABLE`
+
+これはスイッチ内の LED のバックライトを有効にします。`config.h` 内に以下を入れることでバックライトピンを指定することができます:
+
+    #define BACKLIGHT_PIN B7
+
+`MIDI_ENABLE`
+
+キーボードで MIDI の送受信を有効にします。MIDI 送信モードに入るためにキーコード `MI_ON` を使うことができ、オフにするために `MI_OFF` を使うことができます。これはほとんどテストされていない機能ですが、詳細については `quantum/quantum.c` ファイルで見つけることができます。
+
+`UNICODE_ENABLE`
+
+これによりキーマップで `UC(<code point>)` を使って Unicode 文字を送信することができます。`0x7FFF` までのコードポイントがサポートされます。これはほとんどの現代言語の文字と記号を対象にしますが、絵文字は対象外です。
+
+`UNICODEMAP_ENABLE`
+
+これによりキーマップで `X(<map index>)` を使って Unicode 文字を送信することができます。キーマップファイル内にマッピングテーブルを保持する必要があります。可能な全てのコードポイント( `0x10FFFF` まで)がサポートされます。
+
+`UCIS_ENABLE`
+
+これにより、送信したい文字に対応するニーモニックを入力することで Unicode 文字を送信することができます。キーマップファイル内にマッピングテーブルを保持する必要があります。可能な全てのコードポイント( `0x10FFFF` まで)がサポートされます。
+
+詳細と制限については、[Unicode ページ](ja/feature_unicode.md) を見てください。
+
+`BLUETOOTH_ENABLE`
+
+これによりキーコードをワイヤレスで送信するために Bluefruit EZ-key と連動することができます。D2 と D3 ピンを使います。
+
+`AUDIO_ENABLE`
+
+C6 ピン(抽象化が必要)でオーディオ出力できます。詳細は[オーディオページ](ja/feature_audio.md)を見てください。
+
+`FAUXCLICKY_ENABLE`
+
+クリック音のあるスイッチをエミュレートするためにブザーを使います。Cherry社製の青軸スイッチの安っぽい模倣です。デフォルトでは、`AUDIO_ENABLE` と同じように C6 ピンを使います。
+
+`VARIABLE_TRACE`
+
+これを使って変数の値の変更をデバッグします。詳細についてはユニットテストのページの[変数のトレース](ja/unit_testing.md#tracing-variables)のセクションを見てください。
+
+`API_SYSEX_ENABLE`
+
+これにより Quantum SYSEX API を使って文字列を送信することができます (どこに？)
+
+`KEY_LOCK_ENABLE`
+
+これは [キーロック](ja/feature_key_lock.md) を有効にします。
+
+`SPLIT_KEYBOARD`
+
+分割キーボード (let's split や bakingpy's boards のようなデュアル MCU) のサポートを有効にし、quantum/split_common にある全ての必要なファイルをインクルードします
+
+`SPLIT_TRANSPORT`
+
+ARM ベースの分割キーボード用の標準分割通信ドライバはまだ無いため、これらのために `SPLIT_TRANSPORT = custom` を使わなければなりません。カスタムの実装が使われるようにすることで、標準の分割キーボード通信コード(AVR 固有)が含まれないようにします。
+
+`CUSTOM_MATRIX`
+
+デフォルトのマトリックス走査ルーチンを独自のコードで置き換えます。詳細については、[カスタムマトリックスページ](ja/custom_matrix.md) を見てください。
+
+`DEBOUNCE_TYPE`
+
+デフォルトのキーデバウンスルーチンを別のものに置き換えます。`custom` の場合、独自の実装を提供する必要があります。
+
+## キーマップごとに Makefile オプションをカスタマイズ
+
+あなたのキーマップディレクトリに `rules.mk` というファイルがある場合、そのファイルで設定した全てのオプションは、あなたのキーボードの他の `rules.mk` オプションよりも優先されます。
+
+あなたのキーボードの `rules.mk` に `BACKLIGHT_ENABLE = yes` があるとします。あなたの特定のキーボードでバックライトが無いようにするには、`rules.mk` というファイルを作成し、`BACKLIGHT_ENABLE = no` を指定します。

docs/ja/getting_started_vagrant.md

@@ -0,0 +1,62 @@
+# Vagrant クイックスタート
+
+<!---
+  original document: 7494490d6:docs/getting_started_vagrant.md
+  git diff 7494490d6 HEAD -- docs/getting_started_vagrant.md | cat
+-->
+
+このプロジェクトは、プライマリオペレーティングシステムに大きな変更を加えることなくキーボードの新しいファームウェアを非常に簡単に構築することができる `Vagrantfile` を含みます。これは、あなたがプロジェクトをクローンしビルドを実行した時に、ビルドのために Vagrantfile を使っている他のユーザと全く同じ環境を持つことも保証します。これにより、人々はあなたが遭遇した問題の解決をより簡単に行えるようになります。
+
+## 必要事項
+
+このリポジトリ内の `Vagrantfile` を使うには、[Vagrant](http://www.vagrantup.com/) およびサポートされるプロバイダがインストールされている必要があります:
+
+* [VirtualBox](https://www.virtualbox.org/) (バージョン 5.0.12 以降)
+   * 'Vagrant を使うために最もアクセスしやすいプラットフォーム' として販売
+* [VMware Workstation](https://www.vmware.com/products/workstation) および [Vagrant VMware プラグイン](http://www.vagrantup.com/vmware)
+   * (有料) VMware プラグインには、ライセンスされた VMware Workstation/Fusion のコピーが必要です。
+* [Docker](https://www.docker.com/)
+
+Vagrant 以外に、適切なプロバイダがインストールされ、その後におそらくコンピュータを再起動すると、このプロジェクトをチェックアウトしたフォルダ内の任意の場所で 'vagrant up' を単純に実行することができ、このプロジェクトをビルドするのに必要な全てのツールが含まれる環境(仮想マシンあるいはコンテナ)が開始されます。Vagrant をうまく始めるためのヒントの投稿がありますが、それ以外に、以下のビルドドキュメントを参照することもできます。
+
+## ファームウェアの書き込み
+
+ファームウェアを書き込む"簡単"な方法は、ホスト OS からツールを使うことです:
+
+* [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 バージョンをインストールすることができます。
+
+## Vagrantfile の概要
+開発環境は QMK Docker イメージ、`qmkfm/base_container` を実行するように設定されています。これはシステム間の予測可能性が保証されるだけでなく、CI 環境もミラーされます。
+
+## FAQ
+
+### Virtualbox で問題が発生するのはなぜですか？
+Virtualbox 5 の特定のバージョンはこの Vagrantfile のボックスにインストールされている Virtualbox の拡張機能と互換性が無いようです。/vagrant のマウントで問題が発生した場合は、Virtualbox のバージョンを少なくとも 5.0.12 にアップグレードしてください。**または、以下のコマンドを実行してみることができます:**
+
+```console
+vagrant plugin install vagrant-vbguest
+```
+
+### 既存の環境を削除するにはどうすればいいですか？
+あなたの環境での作業が完了しましたか？このプロジェクトをチェックアウトしたフォルダの中のどこからでも、以下を実行してください:
+
+```console
+vagrant destroy
+```
+
+### Docker を直接使いたい場合はどうしますか？
+仮想マシン無しで Vagrant のワークフローを活用したいですか？Vagrantfile は仮想マシンの実行をバイパスし、コンテナを直接実行するように設定されています。Docker を強制的に使うように環境を立ち上げる場合は、以下を実行してください:
+```console
+vagrant up --provider=docker
+```
+
+### Docker コンテナではなく仮想マシンにアクセスするにはどうすればいいですか？
+以下を実行して、公式の QMK ビルダーイメージから直接起動する `vagrant` ユーザをバイパスするようにします:
+
+```console
+vagrant ssh -c 'sudo -i'
+```

docs/ja/keymap.md

@@ -0,0 +1,174 @@
+# キーマップの概要
+
+<!---
+  original document: 7494490d6:docs/keymap.md
+  git diff 7494490d6 HEAD -- docs/keymap.md | cat
+-->
+
+QMK のキーマップは C のソースファイルの中で定義されます。そのデータ構造は配列の配列です。外側はレイヤーを要素とする配列で、レイヤーはキーを要素とする配列。ほとんどのキーボードは `LAYOUT()` マクロを定義して、この配列の配列を作成しやすくしています。
+
+
+## キーマップとレイヤー
+QMKでは、**`const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS]`**は、**アクションコード**を保持している **16 bit** データの中でキーマップ情報の複数の**レイヤー**を保持します。最大で**32個のレイヤー**を定義することができます。
+
+普通のキー定義の場合、**アクションコード**の上位8ビットは全て0で、下位8ビットは**キーコード**としてキーによって生成された USB HID usage コードを保持します。
+
+各レイヤーは同時に有効にできます。レイヤーには 0 から 31 までのインデックスが付けられ、上位のレイヤーが優先されます。
+
+    Keymap: 32 Layers                   Layer: action code matrix
+    -----------------                   ---------------------
+    stack of layers                     array_of_action_code[row][column]
+           ____________ precedence               _______________________
+          /           / | high                  / ESC / F1  / F2  / F3   ....
+      31 /___________// |                      /-----/-----/-----/-----
+      30 /___________// |                     / TAB /  Q  /  W  /  E   ....
+      29 /___________/  |                    /-----/-----/-----/-----
+       :   _:_:_:_:_:__ |               :   /LCtrl/  A  /  S  /  D   ....
+       :  / : : : : : / |               :  /  :     :     :     :
+       2 /___________// |               2 `--------------------------
+       1 /___________// |               1 `--------------------------
+       0 /___________/  V low           0 `--------------------------
+
+
+TMK の歴史的経緯から、キーマップに保存されたアクションコードは、一部のドキュメントではキーコードと呼ばれる場合があります。
+
+### キーマップレイヤーステータス
+キーマップレイヤーの状態は、2つの32ビットパラメータによって決定されます。
+
+* **`default_layer_state`** は、常に有効で参照される基本キーマップレイヤー (0-31) を示します (デフォルトレイヤー)。
+* **`layer_state`** は現在の各レイヤーのオン/オフの状態をビットで持ちます。
+
+キーマップレイヤー '0' は通常 `default_layer` で、他のレイヤーはファームウェアの起動後に最初はオフになっていますが、これは `config.h` で異なる設定にすることが可能です。例えば Qwerty ではなく Colemak に切り替えるなど、キーレイアウトを完全に切り替える場合、`default_layer` を変更すると便利です。
+
+    Initial state of Keymap          Change base layout
+    -----------------------          ------------------
+
+      31                               31
+      30                               30
+      29                               29
+       :                                :
+       :                                :   ____________
+       2   ____________                 2  /           /
+       1  /           /              ,->1 /___________/
+    ,->0 /___________/               |  0
+    |                                |
+    `--- default_layer = 0           `--- default_layer = 1
+         layer_state   = 0x00000001       layer_state   = 0x00000002
+
+一方、`layer_state` を変更して、基本レイヤーをナビゲーションキー、ファンクションキー (F1-F12)、メディアキー、特別なアクションなどの機能を持つ他のレイヤーでオーバーレイすることができます。
+
+    Overlay feature layer
+    ---------------------      bit|status
+           ____________        ---+------
+      31  /           /        31 |   0
+      30 /___________// -----> 30 |   1
+      29 /___________/  -----> 29 |   1
+       :                        : |   :
+       :   ____________         : |   :
+       2  /           /         2 |   0
+    ,->1 /___________/  ----->  1 |   1
+    |  0                        0 |   0
+    |                                 +
+    `--- default_layer = 1            |
+         layer_state   = 0x60000002 <-'
+
+
+
+### レイヤーの優先順位と透過性
+***上位のレイヤーはレイヤーのスタックでより高い優先順位を持つ***ことに注意してください。つまり、ファームウェアはキーコードを最上位から最下位まで検索します。レイヤーで **`KC_TRNS`**(透過)以外のキーコードを見つけると、検索を中止し、下位レイヤーは参照されません。
+
+オーバーレイレイヤーに `KC_TRANS`  を配置して、レイアウトの一部だけを変更して下位レイヤーまたは基本レイヤーにフォールバックすることができます。
+`KC_TRANS` (`KC_TRNS` と `_______` はエイリアス) のキーには独自のキーコードがなく、キーコードの有効な下位レイヤーを参照します。
+
+## `keymap.c` の分析
+
+この例では、[デフォルトの Clueboard 66% キーマップの古いバージョン](https://github.com/qmk/qmk_firmware/blob/ca01d94005f67ec4fa9528353481faa622d949ae/keyboards/clueboard/keymaps/default/keymap.c)を見ていきます。そのファイルを別のブラウザウィンドウで開くとコンテキスト内のすべてを見ることができるので便利です。
+
+`keymap.c` ファイルには、あなたが関心があるであろう以下の2つの主要なセクションがあります:
+
+* [定義](#definitions)
+* [レイヤー/キーマップデータ構造](#layers-and-keymaps)
+
+### 定義 :id=definitions
+
+ファイルの上部に以下のものがあります:
+
+    #include QMK_KEYBOARD_H
+    
+    // 便利な定義
+    #define GRAVE_MODS  (MOD_BIT(KC_LSHIFT)|MOD_BIT(KC_RSHIFT)|MOD_BIT(KC_LGUI)|MOD_BIT(KC_RGUI)|MOD_BIT(KC_LALT)|MOD_BIT(KC_RALT))
+    
+    /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
+    *  KC_TRNS (透過) の代わりに _______ を使うことができます   *
+     *  あるいは、KC_NO (NOOP)  として XXXXXXX を使うことができます    *
+    * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
+    
+    // 各レイヤーは読みやすいように名前を持ちます。
+    // アンダースコアは何も意味を持ちません
+    // STUFF あるいは他の名前のレイヤーを持つことができます。
+    // レイヤー名は全て同じ長さである必要はなく、
+    // また名前を完全に省略して単に数字を使うことができます。
+    #define _BL 0
+    #define _FL 1
+    #define _CL 2
+
+これらはキーマップとカスタム関数を作成するときに使うことができる便利な定義です。`GRAVE_MODS` 定義は後でカスタム関数で使われ、その下の `_BL`、`_FL`、`_CL` 定義は各レイヤーを参照しやすくします。
+
+注意: 古いキーマップファイルに `_______` および `XXXXXXX` の定義が含まれているかもしれません。これらはそれぞれ `KC_TRNS` および `KC_NO` の代わりに使うことができ、レイヤーがどのキーを上書きしているかを簡単に確認することができます。これらの定義はデフォルトで含まれるため、今では不要になりました。
+
+### レイヤーとキーマップ :id=layers-and-keymaps
+
+このファイルの主要部分は `keymaps[]` 定義です。ここで、レイヤーとそれらの内容を列挙します。ファイルのこの部分は、以下の定義から始まります:
+
+    const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
+
+この後で、LAYOUT() マクロのリストがあります。LAYOUT() は単一のレイヤーを定義するためのキーのリストです。通常、1つ以上の"基本レイヤー" (QWERTY、Dvorak、Colemak など)があり、その上に1つ以上の"機能"レイヤーを重ねます。レイヤーの処理方法により、"より上位"のレイヤーの上に"より下位"のレイヤーを重ねることはできません。
+
+QMK の `keymaps[][MATRIX_ROWS][MATRIX_COLS]` は、16ビットのアクションコード( quantum キーコードとも呼ばれる)を保持します。一般的なキーを表すキーコードの場合、その上位バイトは0で、その下位バイトはキーボードの USB HID usage ID です。
+
+> QMK のフォーク元の TMK は、代わりに `const uint8_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS]` を使い、8ビットキーコードを保持します。一部のキーコード値は、`fn_actions[]` 配列を介して特定のアクションコードの実行を引き起こすために予約されています。
+
+#### 基本レイヤー
+
+Clueboard の基本レイヤーの例です:
+
+    /* Keymap _BL: Base Layer (Default Layer)
+    */
+    [_BL] = LAYOUT(
+    F(0),    KC_1,    KC_2,   KC_3,   KC_4,   KC_5,   KC_6,   KC_7,   KC_8,   KC_9,    KC_0,     KC_MINS,  KC_EQL,   KC_GRV,  KC_BSPC,          KC_PGUP, \
+    KC_TAB,  KC_Q,    KC_W,   KC_E,   KC_R,   KC_T,   KC_Y,   KC_U,   KC_I,   KC_O,    KC_P,     KC_LBRC,  KC_RBRC,  KC_BSLS,                   KC_PGDN, \
+    KC_CAPS, KC_A,    KC_S,   KC_D,   KC_F,   KC_G,   KC_H,   KC_J,   KC_K,   KC_L,    KC_SCLN,  KC_QUOT,  KC_NUHS,  KC_ENT,                             \
+    KC_LSFT, KC_NUBS, KC_Z,   KC_X,   KC_C,   KC_V,   KC_B,   KC_N,   KC_M,   KC_COMM, KC_DOT,   KC_SLSH,  KC_RO,    KC_RSFT,          KC_UP,            \
+    KC_LCTL, KC_LGUI, KC_LALT, KC_MHEN,          KC_SPC,KC_SPC,                        KC_HENK,  KC_RALT,  KC_RCTL,  MO(_FL), KC_LEFT, KC_DOWN, KC_RGHT),
+
+これについて注意すべきいくつかの興味深いこと:
+
+* C ソースの観点からは、これは単一の配列に過ぎませんが、物理デバイス上の各キーがどこにあるかをより簡単に可視化するために、空白が埋め込まれています。
+* 単純なキーボードスキャンコードの先頭には KC_ が付いていますが、"特別な"キーには付いていません。
+* 左上のキーはカスタム機能 0 (`F(0)`) をアクティブにします。
+* "Fn" キーは `MO(_FL)` で定義され、そのキーが押されている間は `_FL` レイヤーに移動します。
+
+#### 機能オーバーレイレイヤー
+
+機能レイヤーはコードの観点から基本レイヤーと違いはありません。ただし概念的には、置き換えの代わりにオーバーレイとしてそのレイヤーを構築します。多くの人にとってはこの区別は重要ではありませんが、より複雑なレイヤー設定を構築するにつれて、ますます重要になります。
+
+    [_FL] = LAYOUT(
+    KC_GRV,  KC_F1,   KC_F2,  KC_F3,  KC_F4,  KC_F5,  KC_F6,  KC_F7,  KC_F8,  KC_F9,   KC_F10,   KC_F11,   KC_F12,   _______, KC_DEL,           BL_STEP, \
+    _______, _______, _______,_______,_______,_______,_______,_______,KC_PSCR,KC_SLCK, KC_PAUS,  _______,  _______,  _______,                   _______, \
+    _______, _______, MO(_CL),_______,_______,_______,_______,_______,_______,_______, _______,  _______,  _______,  _______,                           \
+    _______, _______, _______,_______,_______,_______,_______,_______,_______,_______, _______,  _______,  _______,  _______,          KC_PGUP,         \
+    _______, _______, _______, _______,        _______,_______,                        _______,  _______,  _______,  MO(_FL), KC_HOME, KC_PGDN, KC_END),
+
+注意すべきいくつかの興味深いこと:
+
+* `_______` 定義を使って、`KC_TRNS` を `_______` に変換しました。これによりこのレイヤーで変更されたキーを簡単に見つけることができます。
+* このレイヤーで `_______` キーのいずれかを押すと、次の下位のアクティブなレイヤーのキーがアクティブになります。
+
+# 核心となる詳細
+
+これで独自のキーマップを作成するための基本的な概要が得られました。詳細は以下のリソースを見てください:
+
+* [キーコード](ja/keycodes.md)
+* [キーマップ FAQ](ja/faq_keymap.md)
+
+これらのドキュメントの改善に積極的に取り組んでいます。それらを改善する方法について提案がある場合は、[issue を報告](https://github.com/qmk/qmk_firmware/issues/new)してください！

docs/ja/newbs.md

@@ -2,8 +2,8 @@
 
 <!---
   grep --no-filename "^[ ]*git diff" docs/ja/*.md | sh
-  original document: ed0575fc8:docs/newbs.md
-  git diff ed0575fc8 HEAD docs/newbs.md | cat
+  original document: adf4acf59:docs/newbs.md
+  git diff adf4acf59 HEAD -- docs/newbs.md | cat
 -->
 
 QMK は、メカニカルキーボード用の強力なオープンソースファームウェアです。
@@ -24,7 +24,7 @@ QMK は[多くの趣味のキーボード](http://qmk.fm/keyboards/)をサポー
 * [オンライン GUI を使用して初めてのファームウェアを構築する](ja/newbs_building_firmware_configurator.md)
 * [ファームウェアを書きこむ](ja/newbs_flashing.md)
 * [テストとデバッグ](ja/newbs_testing_debugging.md)
-* [QMK における Git 運用作法](ja/newbs_best_practices.md)
+* [QMK における Git 運用作法](ja/newbs_git_best_practices.md)
 * [さらに学ぶための学習リソース](ja/newbs_learn_more_resources.md)
 
 このガイドは、これまでソフトウェアをコンパイルしたことがない人を支援することに特化しています。

docs/ja/newbs_best_practices.md

@@ -1,263 +0,0 @@
-<!-- # Best Practices -->
-# QMK における Git 運用作法
-
-<!---
-  grep --no-filename "^[ ]*git diff" docs/ja/*.md | sh
-  original document: e75919960:docs/newbs_best_practices.md
-  git diff e75919960 HEAD docs/newbs_best_practices.md | cat
--->
-
-<!-- ## Or, "How I Learned to Stop Worrying and Love Git." -->
-## または、如何にして私は心配することをやめて Git を愛することを学んだか。
-
-<!-- _Almost the same as #7231:25fdbf2a0:newbs_git_best_practices.md L5_ -->
-<!-- This document aims to instruct novices in the best ways to have a smooth experience in contributing to QMK. We will walk through the process of contributing to QMK, detailing some ways to make this task easier, and then later we'll break some things in order to teach you how to fix them. -->
-この文書は、QMK への貢献をスムーズに行なう最もよい方法を初心者に教えることを目的としています。
-QMK に貢献するプロセスを順を追って説明し、この作業を簡単にするいくつかの方法を詳しく説明します。
-その後、意図的に一部を壊してみせて、それらを修正する方法を教えます。
-
-<!-- This document assumes a few things: -->
-このドキュメントは以下のことを前提としています:
-
-<!-- _Same as #7231:25fdbf2a0:newbs_git_best_practices.md L9_  -->
-<!-- 1. You have a GitHub account, and have [forked the qmk_firmware repository](getting_started_github.md) to your account. -->
-<!-- 2. You've [set up your build environment](newbs_getting_started.md?id=environment-setup). -->
-<!-- #7231:da7d49246: 2. You've set up both [your build environment](newbs_getting_started.md?id=set-up-your-environment) and [QMK](newbs_getting_started.md?id=set-up-qmk). -->
-
-1. あなたは GitHub アカウントがあり、アカウントに [qmk_firmware リポジトリをフォーク](ja/getting_started_github.md) している。
-2. あなたは、[環境構築](ja/newbs_getting_started.md#set-up-your-environment) と [QMK の設定](ja/newbs_getting_started.md#set-up-qmk) を両方とも完了している。
-
-<!-- ## Your fork's master: Update Often, Commit Never -->
-## あなたのフォークの master ブランチ: 更新は頻繁に、コミットはしないこと
-
-<!-- _Same as #7231:25fdbf2a0:newbs_git_using_your_master_branch.md L3_  -->
-<!-- It is highly recommended for QMK development, regardless of what is being done or where, to keep your `master` branch updated, but ***never*** commit to it. Instead, do all your changes in a development branch and issue pull requests from your branches when you're developing. -->
-QMK の開発では、何がどこで行われているかにかかわらず、`master` ブランチを最新の状態に保つことを強くお勧めします、しかし `master` ブランチには***絶対に直接コミットしないでください***。
-代わりに、あなたのすべての変更は開発ブランチで行い、あなたが開発する時にはそのブランチからプルリクエストを発行します。
-
-<!-- _Same as #7231:25fdbf2a0:newbs_git_using_your_master_branch.md L5_  -->
-<!-- To reduce the chances of merge conflicts &mdash; instances where two or more users have edited the same part of a file concurrently &mdash; keep your `master` branch relatively up-to-date, and start any new developments by creating a new branch. -->
-マージの競合 &mdash; これは 2人以上のユーザーがファイルの同じ部分をそれぞれ異なる編集をして統合できなくなった状態 &mdash; の可能性を減らすため `master` ブランチをなるべく最新の状態に保ち、新しいブランチを作成して新しい開発を開始します。
-
-<!-- ### Updating your master branch -->
-### あなたの master ブランチを更新する
-
-<!-- _Same as #7231:25fdbf2a0:newbs_git_using_your_master_branch.md L9_  -->
-<!-- To keep your `master` branch updated, it is recommended to add the QMK Firmware repository ("repo") as a remote repository in git. To do this, open your Git command line interface and enter: -->
-`master` ブランチを最新の状態に保つには、git のリモートリポジトリとして QMK ファームウェアのリポジトリ(以降、QMK リポジトリ)を追加することをお勧めします。
-これを行うには、Git コマンドラインインターフェイスを開き、次のように入力します。
-
-```
-git remote add upstream https://github.com/qmk/qmk_firmware.git
-```
-
-<!-- _Same as #7231:25fdbf2a0:newbs_git_using_your_master_branch.md L15_  -->
-<!-- To verify that the repository has been added, run `git remote -v`, which should return the following: -->
-リポジトリが追加されたことを確認するには、`git remote -v` を実行します。
-次のように表示されます。(訳注: `upstream` は`上流`という意味です。)
-
-```
-$ git remote -v
-origin  https://github.com/<your_username>/qmk_firmware.git (fetch)
-origin  https://github.com/<your_username>/qmk_firmware.git (push)
-upstream        https://github.com/qmk/qmk_firmware.git (fetch)
-upstream        https://github.com/qmk/qmk_firmware.git (push)
-```
-
-<!-- _Same as #7231:25fdbf2a0:newbs_git_using_your_master_branch.md L25_  -->
-<!-- Now that this is done, you can check for updates to the repo by running `git fetch upstream`. This retrieves the branches and tags &mdash; collectively referred to as "refs" &mdash; from the QMK repo, which now has the nickname `upstream`. We can now compare the data on our fork `origin` to that held by QMK. -->
-これが完了すると、`git fetch upstream` を実行してリポジトリの更新を確認できます。
-このコマンドは `upstream` というニックネームを持つ QMK リポジトリから、ブランチとタグ &mdash; "refs" と総称されます &mdash; を取得します。
-これで、あなたのフォーク `origin` のデータを QMK が保持するデータと比較できます。
-
-<!-- _Same as #7231:25fdbf2a0:newbs_git_using_your_master_branch.md L27_  -->
-<!-- To update your fork's master, run the following, hitting the Enter key after each line: -->
-あなたのフォークの `master` を更新するには、次を実行します、各行の後にEnterキーを押してください:
-
-```
-git checkout master
-git fetch upstream
-git pull upstream master
-git push origin master
-```
-
-<!-- _Same as #7231:25fdbf2a0:newbs_git_using_your_master_branch.md L36_  -->
-<!-- This switches you to your `master` branch, retrieves the refs from the QMK repo, downloads the current QMK `master` branch to your computer, and then uploads it to your fork. -->
-これにより、あなたの `master` ブランチに切り替わり、QMK リポジトリから 'refs' を取得し、現在の QMK の `master` ブランチをコンピュータにダウンロードしてから、あなたのフォークにアップロードします。
-
-<!-- ### Making Changes -->
-### 変更を行なう
-
-<!-- _Same as #7231:25fdbf2a0:newbs_git_using_your_master_branch.md L40_  -->
-<!-- To make changes, create a new branch by entering: -->
-変更するには、以下を入力して新しいブランチを作成します:
-
-```
-git checkout -b dev_branch
-git push --set-upstream origin dev_branch
-```
-
-<!-- _Same as #7231:25fdbf2a0:newbs_git_using_your_master_branch.md L47_  -->
-<!-- This creates a new branch named `dev_branch`, checks it out, and then saves the new branch to your fork. The `--set-upstream` argument tells git to use your fork and the `dev_branch` branch every time you use `git push` or `git pull` from this branch. It only needs to be used on the first push; after that, you can safely use `git push` or `git pull`, without the rest of the arguments. -->
-これにより、`dev_branch` という名前の新しいブランチが作成され、チェックアウトされ、新しいブランチがあなたのフォークに保存されます。
-`--set-upstream` 引数は、このブランチから `git push` または `git pull` を使用するたびに、あなたのフォークと `dev_branch` ブランチを使用するように git に指示します。
-この引数は最初のプッシュでのみ使用する必要があります。
-その後、残りの引数なしで `git push` または `git pull` を安全に使用できます。
-
-<!-- _Same as #7231:25fdbf2a0:newbs_git_using_your_master_branch.md L49_  -->
-<!--  With `git push`, you can use `-u` in place of `--set-upstream` &mdash; `-u` is an alias for `--set-upstream`. -->
-!> `git push` では、`-set-upstream` の代わりに `-u` を使用できます、 `-u` は `--set-upstream` のエイリアスです。
-
-<!-- _Same as #7231:25fdbf2a0:newbs_git_using_your_master_branch.md L51_  -->
-<!-- You can name your branch nearly anything you want, though it is recommended to name it something related to the changes you are going to make. -->
-ブランチにはほぼ任意の名前を付けることができますが、あなたが行なう変更を表す名前を付けることをお勧めします。
-
-<!-- _Same as #7231:25fdbf2a0:newbs_git_using_your_master_branch.md L53_  -->
-<!-- By default `git checkout -b` will base your new branch on the branch that is checked out. You can base your new branch on an existing branch that is not checked out by adding the name of the existing branch to the command: -->
-デフォルトでは、`git checkout -b`は、今チェックアウトされているブランチに基づいて新しいブランチを作成します。
-コマンド末尾に既存のブランチの名前を追加指定することにより、チェックアウトされていない既存のブランチを基にして新しいブランチを作成できます:
-
-```
-git checkout -b dev_branch master
-```
-
-<!-- _Same as #7231:25fdbf2a0:newbs_git_using_your_master_branch.md L59_  -->
-<!-- Now that you have a development branch, open your text editor and make whatever changes you need to make. It is recommended to make many small commits to your branch; that way, any change that causes issues can be more easily traced and undone if needed. To make your changes, edit and save any files that need to be updated, add them to Git's *staging area*, and then commit them to your branch: -->
-これで開発ブランチができたのでテキストエディタを開き必要な変更を加えます。
-ブランチに対して多くの小さなコミットを行うことをお勧めします。
-そうすることで、問題を引き起こす変更をより簡単に特定し必要に応じて元に戻すことができます。
-変更を加えるには、更新が必要なファイルを編集して保存し、Git の *ステージングエリア* に追加してから、ブランチにコミットします:
-
-```
-git add path/to/updated_file
-git commit -m "My commit message."
-```
-
-<!-- _Same as #7231:25fdbf2a0:newbs_git_using_your_master_branch.md L66_  -->
-<!-- `git add` adds files that have been changed to Git's *staging area*, which is Git's "loading zone." This contains the changes that are going to be *committed* by `git commit`, which saves the changes to the repo. Use descriptive commit messages so you can know what was changed at a glance. -->
-`git add`は、変更されたファイルを Git の *ステージングエリア* に追加します。
-これは、Git の「ロードゾーン」です。
-これには、`git commit` によって *コミット* される変更が含まれており、リポジトリへの変更が保存されます。
-変更内容が一目でわかるように、説明的なコミットメッセージを使用します。
-
-<!-- _Same as #7231:25fdbf2a0:newbs_git_using_your_master_branch.md L68_  -->
-<!-- !> If you've changed a lot of files, but all the files are part of the same change, you can use `git add .` to add all the changed files that are in your current directory, rather than having to add each file individually. -->
-!> 多くのファイルを変更したが、すべてのファイルが同じ変更の一部である場合、各ファイルを個別に追加するのではなく、 `git add .` を使用して、現在のディレクトリにあるすべての変更されたファイルを追加できます。
-
-<!-- ### Publishing Your Changes -->
-### 変更を公開する
-
-<!-- _Same as #7231:25fdbf2a0:newbs_git_using_your_master_branch.md L72_  -->
-<!-- The last step is to push your changes to your fork. To do this, enter `git push`. Git now publishes the current state of `dev_branch` to your fork. -->
-最後のステップは、変更をフォークにプッシュすることです。これを行うには、`git push`と入力します。
-Git は `dev_branch` の現在の状態をフォークに公開します。
-
-<!-- ## Resolving Merge Conflicts -->
-##  マージの競合の解決
-
-<!-- _Same as #7231:25fdbf2a0:newbs_git_resolving_merge_conflicts.md L3_  -->
-<!-- Sometimes when your work in a branch takes a long time to complete, changes that have been made by others conflict with changes you have made to your branch when you open a pull request. This is called a *merge conflict*, and is what happens when multiple people edit the same parts of the same files. -->
-ブランチでの作業の完了に時間がかかる場合、他の人が行った変更が、プルリクエストを開いたときにブランチに加えた変更と競合することがあります。
-これは *マージの競合* と呼ばれ、複数の人が同じファイルの同じ部分を編集すると発生します。
-
-<!-- ### Rebasing Your Changes -->
-### 変更のリベース
-
-<!-- _Same as #7231:25fdbf2a0:newbs_git_resolving_merge_conflicts.md L9_  -->
-<!-- A *rebase* is Git's way of taking changes that were applied at one point, reversing them, and then applying the same changes to another point. In the case of a merge conflict, you can rebase your branch to grab the changes that were made between when you created your branch and the present time. -->
-*リベース* は、ある時点で適用された変更を取得し、それらを元に戻し、次に同じ変更を別のポイントに適用する Git の方法です。
-マージの競合が発生した場合、ブランチをリベースして、ブランチを作成してから現在までに行われた変更を取得できます。
-
-<!-- _Same as #7231:25fdbf2a0:newbs_git_resolving_merge_conflicts.md L11_  -->
-<!-- To start, run the following: -->
-開始するには、次を実行します:
-
-```
-git fetch upstream
-git rev-list --left-right --count HEAD...upstream/master
-```
-
-<!-- _Same as #7231:25fdbf2a0:newbs_git_resolving_merge_conflicts.md L18_  -->
-<!-- The `git rev-list` command entered here returns the number of commits that differ between the current branch and QMK's master branch. We run `git fetch` first to make sure we have the refs that represent the current state of the upstream repo. The output of the `git rev-list` command entered returns two numbers: -->
-ここに入力された `git rev-list` コマンドは、現在のブランチと QMK の master ブランチで異なるコミットの数を返します。
-最初に `git fetch` を実行して、upstream リポジトリの現在の状態を表す refs があることを確認します。
-入力された `git rev-list` コマンドの出力は2つの数値を返します:
-
-```
-$ git rev-list --left-right --count HEAD...upstream/master
-7       35
-```
-
-<!-- _Same as #7231:25fdbf2a0:newbs_git_resolving_merge_conflicts.md L25_  -->
-<!-- The first number represents the number of commits on the current branch since it was created, and the second number is the number of commits made to `upstream/master` since the current branch was created, and thus, the changes that are not recorded in the current branch. -->
-最初の数字は、現在のブランチが作成されてからのコミット数を表し、2番目の数字は、現在のブランチが作成されてから `upstream/master` に対して行われたコミットの数であり、したがって、現在のブランチに記録されていない変更です。
-
-<!-- _Same as #7231:25fdbf2a0:newbs_git_resolving_merge_conflicts.md L27_-->
-<!-- Now that the current states of both the current branch and the upstream repo are known, we can start a rebase operation: -->
-現在のブランチと upstream リポジトリの両方の現在の状態がわかったので、リベース操作を開始できます:
-
-```
-git rebase upstream/master
-```
-
-<!-- _Same as #7231:25fdbf2a0:newbs_git_resolving_merge_conflicts.md L33_  -->
-<!-- This tells Git to undo the commits on the current branch, and then reapply them against QMK's master branch. -->
-これにより、Git は現在のブランチのコミットを取り消してから、QMK の master ブランチに対してコミットを再適用します。
-
-```
-$ git rebase upstream/master
-First, rewinding head to replay your work on top of it...
-Applying: Commit #1
-Using index info to reconstruct a base tree...
-M       conflicting_file_1.txt
-Falling back to patching base and 3-way merge...
-Auto-merging conflicting_file_1.txt
-CONFLICT (content): Merge conflict in conflicting_file_1.txt
-error: Failed to merge in the changes.
-hint: Use 'git am --show-current-patch' to see the failed patch
-Patch failed at 0001 Commit #1
-
-Resolve all conflicts manually, mark them as resolved with
-"git add/rm <conflicted_files>", then run "git rebase --continue".
-You can instead skip this commit: run "git rebase --skip".
-To abort and get back to the state before "git rebase", run "git rebase --abort".
-```
-
-<!-- _Same as #7231:25fdbf2a0:newbs_git_resolving_merge_conflicts.md L54_  -->
-<!-- This tells us that we have a merge conflict, and gives the name of the file with the conflict. Open the conflicting file in your text editor, and somewhere in the file, you'll find something like this: -->
-これにより、マージの競合があることがわかり、競合のあるファイルの名前が示されます。
-テキストエディタで競合するファイルを開くと、ファイルのどこかに次のような行があります:
-
-```
-<<<<<<< HEAD
-<p>For help with any issues, email us at support@webhost.us.</p>
-=======
-<p>Need help? Email support@webhost.us.</p>
->>>>>>> Commit #1
-```
-
-<!-- _Same as #7231:25fdbf2a0:newbs_git_resolving_merge_conflicts.md L64_  -->
-<!-- The line `<<<<<<< HEAD` marks the beginning of a merge conflict, and the `>>>>>>> Commit #1` line marks the end, with the conflicting sections separated by `=======`. The part on the `HEAD` side is from the QMK master version of the file, and the part marked with the commit message is from the current branch and commit. -->
-行 `<<<<<<< HEAD` はマージ競合の始まりを示し、行 `>>>>>>> commit #1` は終了を示し、競合するセクションは `=======` で区切られます。
-`HEAD` 側の部分はファイルの QMK master バージョンからのものであり、コミットメッセージでマークされた部分は現在のブランチとコミットからのものです。
-
-<!-- _Same as #7231:25fdbf2a0:newbs_git_resolving_merge_conflicts.md L66_  -->
-<!-- Because Git tracks *changes to files* rather than the contents of the files directly, if Git can't find the text that was in the file previous to the commit that was made, it won't know how to edit the file. Re-editing the file will solve the conflict. Make your changes, and then save the file. -->
-Git はファイルの内容ではなく *ファイルへの変更* を直接追跡するため、Git がコミットの前にファイル内にあったテキストを見つけられない場合、ファイルの編集方法がわかりません。
-ファイルを再編集して、競合を解決します。
-変更を加えてから、ファイルを保存します。
-
-```
-<p>Need help? Email support@webhost.us.</p>
-```
-
-そしてコマンド実行:
-
-```
-git add conflicting_file_1.txt
-git rebase --continue
-```
-
-<!-- _Same as #7231:25fdbf2a0:newbs_git_resolving_merge_conflicts.md L79_  -->
-<!-- Git logs the changes to the conflicting file, and continues applying the commits from our branch until it reaches the end. -->
-Git は、競合するファイルへの変更をログに記録し、ブランチのコミットが最後に達するまで適用し続けます。

docs/ja/newbs_building_firmware.md

@@ -2,8 +2,8 @@
 
 <!---
   grep --no-filename "^[ ]*git diff" docs/ja/*.md | sh
-  original document: ed0575fc8:docs/newbs_building_firmware.md
-  git diff ed0575fc8 HEAD docs/newbs_building_firmware.md | cat
+  original document: 0f43c2652:docs/newbs_building_firmware.md
+  git diff 0f43c2652 HEAD -- docs/newbs_building_firmware.md | cat
 -->
 
 ビルド環境をセットアップしたので、カスタムファームウェアのビルドを開始する準備ができました。
@@ -56,7 +56,7 @@ macOS または Windows を使用している場合は、キーマップフォ
 
 この行はレイヤーのリストの開始を表わしています。
 その下には、`LAYOUT` または `KEYMAP` のいずれかを含む行があり、これらの行はレイヤーの開始を表わしています。
-その行の下には、その特定のレイヤーを構成するキーのリストがあります。
+その行の下には、そのレイヤーを構成するキーのリストがあります。
 
 !> キーマップファイルを編集するときは、カンマを追加したり削除したりしないように注意してください。そうするとファームウェアのコンパイルができなくなり、余分であったり欠落していたりするカンマがどこにあるのかを容易に把握できない場合があります。
 

docs/ja/newbs_building_firmware_configurator.md

@@ -3,7 +3,7 @@
 <!---
   grep --no-filename "^[ ]*git diff" docs/ja/*.md | sh
   original document: ed0575fc8:docs/newbs_building_firmware_configurator.md
-  git diff ed0575fc8 HEAD docs/newbs_building_firmware_configurator.md | cat
+  git diff ed0575fc8 HEAD -- docs/newbs_building_firmware_configurator.md | cat
 -->
 
 [QMK Configurator](https://config.qmk.fm) は、QMKファームウェアの hex ファイルを生成するオンライングラフィカルユーザーインターフェイスです。
@@ -63,7 +63,7 @@ QMK Configurator は Chrome/Firefox で最適に動作します。
 
 2分割の右シフト: 両方とも右シフトで埋めます。
 
-左シフトとISOサポート用に1つずつ: 両方とも左シフトで埋めます。
+左シフトと ISO サポート用に1つずつ: 両方とも左シフトで埋めます。
 
 5分割だが4キーのみ: 以前やったことがある人を推測して確認するか尋ねてください。
 
@@ -73,7 +73,7 @@ QMK Configurator は Chrome/Firefox で最適に動作します。
 
 後日、`Import Keymap` ボタンを押すことで、この .json ファイルをロードできます。
 
-!> **注意:** このファイルは、kbfirmware.com またはその他のツールに使用される .jsonファイルと同じ形式ではありません。これらのツールにこれを使用したり、QMK Configurator でこれらのツールの .json を使用しようとすると、キーボードが **爆発** する可能性があります。
+!> **注意:** このファイルは、kbfirmware.com またはその他のツールに使用される .json ファイルと同じ形式ではありません。これらのツールにこれを使用したり、QMK Configurator でこれらのツールの .json を使用しようとすると、キーボードが **爆発** する可能性があります。
 
 ## ファームウェアファイルを生成する
 

docs/ja/newbs_flashing.md

@@ -3,7 +3,7 @@
 <!---
   grep --no-filename "^[ ]*git diff" docs/ja/*.md | sh
   original document: ed0575fc8:docs/newbs_flashing.md
-  git diff ed0575fc8 HEAD docs/newbs_flashing.md | cat
+  git diff ed0575fc8 HEAD -- docs/newbs_flashing.md | cat
 -->
 
 カスタムファームウェアは出来たので、キーボードに書き込みたくなるでしょう/フラッシュしたくなるでしょう。
@@ -13,7 +13,7 @@
 キーボードに書き込む最も簡単な方法は [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) を使うことです。
 
 ただし、QMK Toolbox は、現在は Windows と macOS でしか使えません。
-Linuxを使用している場合(および、コマンドラインでファームウェアを書き込みたい場合)は、下の方で概説する[方法](ja/newbs_flashing.md#flash-your-keyboard-from-the-command-line)で行なう必要があります。
+Linux を使用している場合(および、コマンドラインでファームウェアを書き込みたい場合)は、下の方で概説する[方法](ja/newbs_flashing.md#flash-your-keyboard-from-the-command-line)で行なう必要があります。
 
 ### QMK Toolbox にファイルをロードする
 
@@ -65,7 +65,7 @@ planck_rev5_default.hex
 * 基板(PCB)に付けられている物理的な `RESET` ボタンを押す
 * PCB 上の `BOOT0` か `RESET` のラベルの付いたヘッダピンを探し、PCB 接続中にそれらを互いにショートする
 
-うまくいけば、QMK Toolboxに次のようなメッセージが表示されます。
+うまくいけば、QMK Toolbox に次のようなメッセージが表示されます。
 
 ```
 *** Clueboard - Clueboard 66% HotSwap disconnected -- 0xC1ED:0x2390
@@ -121,7 +121,7 @@ QMK Toolbox の `Flash` ボタンをクリックします。
 この場合、あなたは明示的にブートローダを指定する方法を使わなければなりません。
 
 ブートローダは主に 5 種類のものが使われています。
-Pro Micro とそのクローンは Caterina を、Teensy は HalfKay を、OLKBの AVR ボードは QMK-DFU を、その他の ATmega32U4 ボードは DFU を、そして多くの ARM ボードは ARM DFU を使います。
+Pro Micro とそのクローンは Caterina を、Teensy は HalfKay を、OLKB の AVR ボードは QMK-DFU を、その他の ATmega32U4 ボードは DFU を、そして多くの ARM ボードは ARM DFU を使います。
 
 より詳しいブートローダの情報は、[Flashing Instructions and Bootloader Information](ja/flashing.md) にあります。
 
@@ -178,10 +178,10 @@ Checking file size of planck_rev5_xyverz.hex
 
 ファームウェアを DFU デバイスに書き込むために使用できる DFU コマンドがいくつかあります。
 
-* `:dfu` - これが通常のオプションで、DFUデバイスが使用可能になるまで待機したのちファームウェアを書き込みます。5秒ごとに、DFUデバイスが存在するかチェックしています。
+* `:dfu` - これが通常のオプションで、DFU デバイスが使用可能になるまで待機したのちファームウェアを書き込みます。5秒ごとに、DFU デバイスが存在するかチェックしています。
 * `:dfu-ee` - 通常の hex ファイルの代わりに `eep` ファイルを書き込みます。これを使用するのはまれです。
-* `:dfu-split-left` - デフォルトオプション (`:dfu`) と同様に、通常のファームウェアが書き込まれます。ただし、分割キーボードの「左側の」 EEPROMファイルも書き込まれます。_これは、Elite C ベースの分割キーボードに最適です。_
-* `:dfu-split-right` - デフォルトオプション (`:dfu`) と同様に、通常のファームウェアが書き込まれます。ただし、分割キーボードの「右側の」EEPROMファイルも書き込まれます。_これは、Elite C ベースの分割キーボードに最適です。_
+* `:dfu-split-left` - デフォルトオプション (`:dfu`) と同様に、通常のファームウェアが書き込まれます。ただし、分割キーボードの「左側の」 EEPROM ファイルも書き込まれます。_これは、Elite C ベースの分割キーボードに最適です。_
+* `:dfu-split-right` - デフォルトオプション (`:dfu`) と同様に、通常のファームウェアが書き込まれます。ただし、分割キーボードの「右側の」EEPROM ファイルも書き込まれます。_これは、Elite C ベースの分割キーボードに最適です。_
 
 
 ### Caterina 
@@ -259,8 +259,8 @@ avrdude.exe done.  Thank you.
 
 * `:avrdude` - これが通常のオプションで、Caterina デバイスが(新しい COM ポートを検出して)使用可能になるまで待機し、ファームウェアを書き込みます。
 * `:avrdude-loop` - これは `:avrdude` と同じです。ただし書き込みが終了すると再び Caterina デバイスの書き込み待ちに戻ります。これは何台ものデバイスへの書き込みに便利です。_Control+C を押して、手動でこの繰り返しを終了させる必要があります。_
-* `:avrdude-split-left` - デフォルトオプション(`:avrdude`)と同様に通常のファームウェアが書き込まれます。ただし、分割キーボードの「左側の」EEPROMファイルもフラッシュされます。 _これは、Pro Micro ベースの分割キーボードに最適です。_
-* `:avrdude-split-right` - デフォルトオプション(`:avrdude`)と同様に通常のファームウェアが書き込まれます。ただし、分割キーボードの「右側の」EEPROMファイルもフラッシュされます。 _これは、Pro Micro ベースの分割キーボードに最適です。_
+* `:avrdude-split-left` - デフォルトオプション(`:avrdude`)と同様に通常のファームウェアが書き込まれます。ただし、分割キーボードの「左側の」EEPROM ファイルもフラッシュされます。 _これは、Pro Micro ベースの分割キーボードに最適です。_
+* `:avrdude-split-right` - デフォルトオプション(`:avrdude`)と同様に通常のファームウェアが書き込まれます。ただし、分割キーボードの「右側の」EEPROM ファイルもフラッシュされます。 _これは、Pro Micro ベースの分割キーボードに最適です。_
 
 ### HalfKay
 

docs/ja/newbs_getting_started.md

@@ -2,8 +2,8 @@
 
 <!---
   grep --no-filename "^[ ]*git diff" docs/ja/*.md | sh
-  original document: docs/newbs_getting_started.md
-  git diff 161d469 HEAD docs/newbs_getting_started.md | cat
+  original document: 161d469:docs/newbs_getting_started.md
+  git diff 161d469 HEAD -- docs/newbs_getting_started.md | cat
 -->
 
 キーボードにはプロセッサが入っており、それはコンピュータに入っているものと大して違わないものです。
@@ -12,7 +12,7 @@ QMK は、そのソフトウェアの役割を果たし、ボタンの押下を
 カスタムキーマップを作るということは、キーボード上で動くプログラムを作るということなのです。
 
 QMK は、簡単なことは簡単に、そして、難しいことを可能なことにすることで、あなたの手にたくさんのパワーをもたらします。
-パワフルなキーマップを作るためにプログラムを作成する方法を知る必要はありません。いくつかのシンプルな文法に従うだけでOKです。
+パワフルなキーマップを作るためにプログラムを作成する方法を知る必要はありません。いくつかのシンプルな文法に従うだけで OK です。
 
 # はじめに
 

docs/ja/newbs_git_best_practices.md

@@ -0,0 +1,24 @@
+# QMK における Git 運用作法 :id=best-git-practices-for-working-with-qmk
+
+<!---
+  grep --no-filename "^[ ]*git diff" docs/ja/*.md | sh
+  original document: adf4acf59:docs/newbs_git_best_practices.md
+  git diff adf4acf59 HEAD -- docs/newbs_git_best_practices.md | cat
+-->
+
+## または、"如何にして私は心配することをやめて Git を愛することを学んだか。"
+
+このセクションは、QMK への貢献をスムーズに行なう最もよい方法を初心者に教えることを目的としています。
+QMK に貢献するプロセスを順を追って説明し、この作業を簡単にするいくつかの方法を詳しく説明します。
+その後、意図的に一部を壊してみせて、それらを修正する方法を説明します。
+
+このセクションは以下のことを前提としています:
+
+1. あなたは GitHub アカウントがあり、アカウントに [qmk_firmware リポジトリをフォーク](ja/getting_started_github.md) している。
+2. あなたは、[環境構築](ja/newbs_getting_started.md#set-up-your-environment) と [QMK の設定](ja/newbs_getting_started.md#set-up-qmk) を両方とも完了している。
+
+---
+
+- パート 1: [あなたのフォークの master ブランチ: 更新は頻繁に、コミットはしないこと](ja/newbs_git_using_your_master_branch.md)
+- パート 2: [マージの競合の解決](ja/newbs_git_resolving_merge_conflicts.md)
+- パート 3: [同期のとれていない git ブランチの再同期](ja/newbs_git_resynchronize_a_branch.md)

docs/ja/newbs_git_resolving_merge_conflicts.md

@@ -0,0 +1,94 @@
+#  マージの競合の解決
+
+<!---
+  grep --no-filename "^[ ]*git diff" docs/ja/*.md | sh
+  original document: adf4acf59:docs/newbs_git_resolving_merge_conflicts.md
+  git diff adf4acf59 HEAD -- docs/newbs_git_resolving_merge_conflicts.md | cat
+-->
+
+ブランチでの作業の完了に時間がかかる場合、他の人が行った変更が、プルリクエストを開いたときにブランチに加えた変更と競合することがあります。
+これは *マージの競合* と呼ばれ、複数の人が同じファイルの同じ部分を編集すると発生します。
+
+?> このドキュメントは [あなたのフォークの master ブランチ: 更新は頻繁に、コミットはしないこと](ja/newbs_git_using_your_master_branch.md) で詳述されている概念に基づいています。
+その概念に慣れていない場合は、まずそれを読んでから、ここに戻ってください。
+
+## 変更のリベース
+
+*リベース* は、コミット履歴のある時点で適用された変更を取得し、それらを元に戻し、次に同じ変更を別のポイントに適用する Git の方法です。
+マージの競合が発生した場合、ブランチをリベースして、ブランチを作成してから現在までに行われた変更を取得できます。
+
+開始するには、次を実行します:
+
+```
+git fetch upstream
+git rev-list --left-right --count HEAD...upstream/master
+```
+
+ここに入力された `git rev-list` コマンドは、現在のブランチと QMK の master ブランチで異なるコミットの数を返します。
+最初に `git fetch` を実行して、upstream リポジトリの現在の状態を表す refs があることを確認します。
+入力された `git rev-list` コマンドの出力は2つの数値を返します:
+
+```
+$ git rev-list --left-right --count HEAD...upstream/master
+7       35
+```
+
+最初の数字は、現在のブランチが作成されてからのコミット数を表し、2番目の数字は、現在のブランチが作成されてから `upstream/master` に対して行われたコミットの数であり、したがって、現在のブランチに記録されていない変更です。
+
+現在のブランチと upstream リポジトリの両方の現在の状態がわかったので、リベース操作を開始できます:
+
+```
+git rebase upstream/master
+```
+
+これにより、Git は現在のブランチのコミットを取り消してから、QMK の master ブランチに対してコミットを再適用します。
+
+```
+$ git rebase upstream/master
+First, rewinding head to replay your work on top of it...
+Applying: Commit #1
+Using index info to reconstruct a base tree...
+M       conflicting_file_1.txt
+Falling back to patching base and 3-way merge...
+Auto-merging conflicting_file_1.txt
+CONFLICT (content): Merge conflict in conflicting_file_1.txt
+error: Failed to merge in the changes.
+hint: Use 'git am --show-current-patch' to see the failed patch
+Patch failed at 0001 Commit #1
+
+Resolve all conflicts manually, mark them as resolved with
+"git add/rm <conflicted_files>", then run "git rebase --continue".
+You can instead skip this commit: run "git rebase --skip".
+To abort and get back to the state before "git rebase", run "git rebase --abort".
+```
+
+これにより、マージの競合があることがわかり、競合のあるファイルの名前が示されます。
+テキストエディタで競合するファイルを開くと、ファイルのどこかに次のような行があります:
+
+```
+<<<<<<< HEAD
+<p>For help with any issues, email us at support@webhost.us.</p>
+=======
+<p>Need help? Email support@webhost.us.</p>
+>>>>>>> Commit #1
+```
+
+行 `<<<<<<< HEAD` はマージ競合の始まりを示し、行 `>>>>>>> commit #1` は終了を示し、競合するセクションは `=======` で区切られます。
+`HEAD` 側の部分はファイルの QMK master バージョンからのものであり、コミットメッセージでマークされた部分は現在のブランチとコミットからのものです。
+
+Git はファイルの内容ではなく *ファイルへの変更* を直接追跡するため、Git がコミットの前にファイル内にあったテキストを見つけられない場合、ファイルの編集方法がわかりません。
+ファイルを再編集して、競合を解決します。
+変更を加えてから、ファイルを保存します。
+
+```
+<p>Need help? Email support@webhost.us.</p>
+```
+
+そしてコマンド実行:
+
+```
+git add conflicting_file_1.txt
+git rebase --continue
+```
+
+Git は、競合するファイルへの変更をログに記録し、ブランチのコミットが最後に達するまで適用し続けます。

docs/ja/newbs_git_resynchronize_a_branch.md

@@ -0,0 +1,88 @@
+# 同期のとれていない git ブランチの再同期
+
+<!---
+  grep --no-filename "^[ ]*git diff" docs/ja/*.md | sh
+  original document: adf4acf59:docs/newbs_git_resynchronize_a_branch.md
+  git diff adf4acf59 HEAD -- docs/newbs_git_resynchronize_a_branch.md | cat
+-->
+
+仮にあなたの `master` ブランチにあなたのコミットを行い、そしてあなたの QMK リポジトリの更新が必要になったとします。
+(フォーク元の) QMK の `master` ブランチをあなたの `master` ブランチに `git pull` することもできますが、GitHub は、あなたのブランチが `qmk:master` より何コミットか先行していると通知します、この状態で QMK にプルリクエストを行う場合、問題が発生する可能性があります。
+(訳注：この通知は、GitHub のあなたのリポジトリの code ペインのブランチ選択メニューの下のあたりで `This branch is 3 commit ahead of qmk:master` という様な文面で表示されています。)
+
+?> このドキュメントは [あなたのフォークの master ブランチ: 更新は頻繁に、コミットはしないこと](ja/newbs_git_using_your_master_branch.md) で詳述されている概念に基づいています。その概念に慣れていない場合は、まずそれを読んでから、ここに戻ってください。  
+(訳注：この文書で言う、「同期のとれていない git ブランチ」とは、master ブランチに関する、この「コミットしない」方針を逸脱して、QMK の master リポジトリに存在しないコミットがあなたのフォークの master ブランチに入っている状態を指します。)
+
+## あなた自身の `master` ブランチでの変更のバックアップ（オプション）
+
+救えるものなら自分の行った変更を失いたくはないでしょう。
+あなたの `master` ブランチに既に加えた変更を保存したい場合、最も簡単な方法は、単に「ダーティな」`master` ブランチの複製を作成することです：
+
+```sh
+git branch old_master master
+```
+
+これで、 `master` ブランチの複製である `old_master` という名前のブランチができました。
+
+## あなたのブランチの再同期
+
+さあ、`master` ブランチを再同期します。
+この手順では、QMK のリポジトリを git のリモートリポジトリとして設定する必要があります。
+設定済みのリモートリポジトリを確認するには、`git remote -v` を実行し、次のような結果が返されなければなりません。
+
+```sh
+QMKuser ~/qmk_firmware (master)
+$ git remote -v
+origin  https://github.com/<your_username>/qmk_firmware.git (fetch)
+origin  https://github.com/<your_username>/qmk_firmware.git (push)
+upstream        https://github.com/qmk/qmk_firmware.git (fetch)
+upstream        https://github.com/qmk/qmk_firmware.git (push)
+```
+
+もし、上記のようにならずに以下のように参照されるフォークが、1つだけ表示される場合：
+
+```sh
+QMKuser ~/qmk_firmware (master)
+$ git remote -v
+origin  https://github.com/qmk/qmk_firmware.git (fetch)
+origin  https://github.com/qmk/qmk_firmware.git (push)
+```
+
+新しいリモートリポジトリを追加します：
+
+```sh
+git remote add upstream https://github.com/qmk/qmk_firmware.git
+```
+
+次に、`origin` リモートリポジトリを、あなた自身のフォークにリダイレクトします：
+
+```sh
+git remote set-url origin https://github.com/<あなたのユーザ名>/qmk_firmware.git
+```
+
+両方のリモートリポジトリが設定されたので、次を実行して、QMK である `upstream` リポジトリの参照を更新する必要があります。
+
+```sh
+git fetch upstream
+```
+
+この時点で、次を実行してあなたの(訳注：master)ブランチを QMK のブランチに再同期します。
+(訳注： 今現在 `master` ブランチがチェックアウトされていなければなりません。
+ そうなってなければ、`git checkout master` を先に実行しておく必要があります。)
+
+```sh
+git reset --hard upstream/master
+```
+
+これらの手順により、あなたのコンピュータ上のリポジトリが更新されますが、あなたの GitHub 上のフォークはまだ同期されていません。
+GitHub 上のフォークを再同期するには、あなたのフォークにプッシュして、ローカルリポジトリに反映されていないリモート変更をオーバーライドするように Git に指示する必要があります。
+これを行うには、次を実行します：
+
+```sh
+git push --force-with-lease
+```
+
+!> 他のユーザーがコミットを投稿するフォークで `git push --force-with-lease` を**実行しないでください**。これをすると、かれらのコミットが消去されてしまいます。
+
+これで、あなたの GitHub フォーク、あなたのローカルファイル、および QMK のリポジトリはすべて同じになりました。
+ここから、[ブランチを使って](ja/newbs_git_using_your_master_branch.md#making-changes)さらに必要な変更を加え、通常どおりそれらを投稿できます。

docs/ja/newbs_git_using_your_master_branch.md

@@ -0,0 +1,101 @@
+# あなたのフォークの master ブランチ: 更新は頻繁に、コミットはしないこと
+
+<!---
+  grep --no-filename "^[ ]*git diff" docs/ja/*.md | sh
+  original document: adf4acf59:docs/newbs_git_using_your_master_branch.md
+  git diff adf4acf59 HEAD -- docs/newbs_git_using_your_master_branch.md | cat
+-->
+
+QMK の開発では、何がどこで行われているかにかかわらず、`master` ブランチを最新の状態に保つことを強くお勧めします、しかし `master` ブランチには***絶対に直接コミットしないでください***。
+代わりに、あなたのすべての変更は開発ブランチで行い、あなたが開発する時にはそのブランチからプルリクエストを発行します。
+
+マージの競合 &mdash; これは 2人以上のユーザーがファイルの同じ部分をそれぞれ異なる編集をして統合できなくなった状態 &mdash; の可能性を減らすため `master` ブランチをなるべく最新の状態に保ち、新しいブランチを作成して新しい開発を開始します。
+
+## あなたの master ブランチを更新する
+
+`master` ブランチを最新の状態に保つには、git のリモートリポジトリとして QMK ファームウェアのリポジトリ(以降、QMK リポジトリ)を追加することをお勧めします。
+これを行うには、Git コマンドラインインターフェイスを開き、次のように入力します。
+
+```
+git remote add upstream https://github.com/qmk/qmk_firmware.git
+```
+
+?> `upstream`(訳注: `upstream` は`上流`という意味です)という名前は任意ですが、一般的な慣習です。
+QMK のリモートリポジトリには、あなたにとって分かりやすい名前を付けることができます。
+Git の `remote` コマンドは、構文 `git remote add <name> <url>` を使用します。
+`<name>` はリモートリポジトリの省略形としてあなたが指定するものです。
+この名前は、`fetch`、`pull`、`push` やそれ以外の多くの Git コマンドで、対象のリモートリポジトリを指定するために使用されます。
+
+リポジトリが追加されたことを確認するには、`git remote -v` を実行します。
+次のように表示されます。
+
+```
+$ git remote -v
+origin  https://github.com/<your_username>/qmk_firmware.git (fetch)
+origin  https://github.com/<your_username>/qmk_firmware.git (push)
+upstream        https://github.com/qmk/qmk_firmware.git (fetch)
+upstream        https://github.com/qmk/qmk_firmware.git (push)
+```
+
+これが完了すると、`git fetch upstream` を実行してリポジトリの更新を確認できます。
+このコマンドは `upstream` というニックネームを持つ QMK リポジトリから、ブランチとタグ &mdash; "refs" と総称されます &mdash; を取得します。
+これで、あなたのフォーク `origin` のデータを QMK が保持するデータと比較できます。
+
+あなたのフォークの `master` を更新するには、次を実行します、各行の後に Enter キーを押してください:
+
+```
+git checkout master
+git fetch upstream
+git pull upstream master
+git push origin master
+```
+
+これにより、あなたの `master` ブランチに切り替わり、QMK リポジトリから 'refs' を取得し、現在の QMK の `master` ブランチをコンピュータにダウンロードしてから、あなたのフォークにアップロードします。
+
+## 変更を行なう :id=making-changes
+
+変更するには、以下を入力して新しいブランチを作成します:
+
+```
+git checkout -b dev_branch
+git push --set-upstream origin dev_branch
+```
+
+これにより、`dev_branch` という名前の新しいブランチが作成され、チェックアウトされ、新しいブランチがあなたのフォークに保存されます。
+`--set-upstream` 引数は、このブランチから `git push` または `git pull` を使用するたびに、あなたのフォークと `dev_branch` ブランチを使用するように git に指示します。
+この引数は最初のプッシュでのみ使用する必要があります。
+その後、残りの引数なしで `git push` または `git pull` を安全に使用できます。
+
+?> `git push` では、`-set-upstream` の代わりに `-u` を使用できます、 `-u` は `--set-upstream` のエイリアスです。
+
+ブランチにはほぼ任意の名前を付けることができますが、あなたが行なう変更を表す名前を付けることをお勧めします。
+
+デフォルトでは、`git checkout -b`は、今チェックアウトされているブランチに基づいて新しいブランチを作成します。
+コマンド末尾に既存のブランチの名前を追加指定することにより、チェックアウトされていない既存のブランチを基にして新しいブランチを作成できます:
+
+```
+git checkout -b dev_branch master
+```
+
+これで開発ブランチができたのでテキストエディタを開き必要な変更を加えます。
+ブランチに対して多くの小さなコミットを行うことをお勧めします。
+そうすることで、問題を引き起こす変更をより簡単に特定し必要に応じて元に戻すことができます。
+変更を加えるには、更新が必要なファイルを編集して保存し、Git の *ステージングエリア* に追加してから、ブランチにコミットします:
+
+```
+git add path/to/updated_file
+git commit -m "My commit message."
+```
+
+`git add`は、変更されたファイルを Git の *ステージングエリア* に追加します。
+これは、Git の「ロードゾーン」です。
+これには、`git commit` によって *コミット* される変更が含まれており、リポジトリへの変更が保存されます。
+変更内容が一目でわかるように、説明的なコミットメッセージを使用します。
+
+?> 複数のファイルを変更した場合、`git add -- path/to/file1 path/to/file2 ...` を実行すれば、あなたの望むファイルを追加できます。
+
+## 変更を公開する
+
+最後のステップは、変更をフォークにプッシュすることです。
+これを行うには、`git push`と入力します。
+Git は、 `dev_branch`の現在の状態をフォークに公開します。

docs/ja/newbs_learn_more_resources.md

@@ -3,10 +3,10 @@
 <!---
   grep --no-filename "^[ ]*git diff" docs/ja/*.md | sh
   original document: ed0575fc8:docs/newbs_learn_more_resources.md
-  git diff ed0575fc8 HEAD docs/newbs_learn_more_resources.md | cat
+  git diff ed0575fc8 HEAD -- docs/newbs_learn_more_resources.md | cat
 -->
 
-これらのリソースは、QMKコミュニティの新しいメンバーに、初心者向けドキュメントで提供されている情報に対する理解を深めることを目的としています。
+これらのリソースは、QMK コミュニティの新しいメンバーに、初心者向けドキュメントで提供されている情報に対する理解を深めることを目的としています。
 
 ## Git に関するリース:
 
@@ -14,13 +14,17 @@
 
 * [Great General Tutorial](https://www.codecademy.com/learn/learn-git)
 * [Git Game To Learn From Examples](https://learngitbranching.js.org/)
-* [Git Resources to Learn More About Github](ja/getting_started_github.md)
-* [Git Resources Aimed Specifically toward QMK](ja/contributing.md)
+* [Git Resources to Learn More About Github](getting_started_github.md)
+* [Git Resources Aimed Specifically toward QMK](contributing.md)
 
 ### 日本語
 
 _日本語のリソース情報を募集中です。_
 
+* [Git Game To Learn From Examples(日本語対応有り)](https://learngitbranching.js.org/)
+* [QMK で Github を使う方法](ja/getting_started_github.md)
+* [貢献方法](ja/contributing.md)
+
 ## コマンドラインに関するリソース:
 
 ### 英語

docs/ja/newbs_testing_debugging.md

@@ -3,7 +3,7 @@
 <!---
   grep --no-filename "^[ ]*git diff" docs/ja/*.md | sh
   original document: ed0575fc8:docs/newbs_testing_debugging.md
-  git diff ed0575fc8 HEAD docs/newbs_testing_debugging.md | cat
+  git diff ed0575fc8 HEAD -- docs/newbs_testing_debugging.md | cat
 -->
 
 カスタムファームウェアをキーボードへ書き込んだら、テストする準備が整います。運が良ければ全て問題なく動作しているはずですが、もしそうでなければこのドキュメントがどこが悪いのか調べるのに役立ちます。
@@ -12,7 +12,7 @@
 
 通常、キーボードをテストするのは非常に簡単です。全てのキーをひとつずつ押して、期待されるキーが送信されていることを確認します。キーを押したことを見逃さないためのプログラムもあります。
 
-メモ：　これらのプログラムはQMKによって提供・承認されたものではありません。
+メモ：　これらのプログラムは QMK によって提供・承認されたものではありません。
 
 * [QMK Configurator](https://config.qmk.fm/#/test/) (Web Based)
 * [Switch Hitter](https://web.archive.org/web/20190413233743/https://elitekeyboards.com/switchhitter.php) (Windows Only)
@@ -40,7 +40,7 @@ void keyboard_post_init_user(void) {
 
 ### hid_listenを使ったデバッグ
 
-ターミナルベースの方法がお好みですか？PJRCが提供する[hid_listen](https://www.pjrc.com/teensy/hid_listen.html)もデバッグメッセージの表示に使用できます。ビルド済みの実行ファイルはWindows, Linux, MacOS用が用意されています。
+ターミナルベースの方法がお好みですか？PJRC が提供する[hid_listen](https://www.pjrc.com/teensy/hid_listen.html)もデバッグメッセージの表示に使用できます。ビルド済みの実行ファイルは Windows, Linux, MacOS 用が用意されています。
 
 <!-- FIXME: Describe the debugging messages here. -->
 
@@ -50,7 +50,7 @@ void keyboard_post_init_user(void) {
 
     #include <print.h>
 
-そのあとは、いくつかの異なったprint関数を使用することが出来ます。
+そのあとは、いくつかの異なった print 関数を使用することが出来ます。
 
 * `print("string")`: シンプルな文字列を出力します
 * `uprintf("%s string", var)`: フォーマットされた文字列を出力します

docs/keycodes.md

@@ -208,24 +208,11 @@ This is a reference only. Each group of keys links to the page documenting their
 
 ## [Quantum Keycodes](quantum_keycodes.md#qmk-keycodes)
 
-|Key            |Aliases    |Description                                                          |
-|---------------|-----------|---------------------------------------------------------------------|
-|`RESET`        |           |Put the keyboard into DFU mode for flashing                          |
-|`DEBUG`        |           |Toggle debug mode                                                    |
-|`EEPROM_RESET` |`EEP_RST`  |Resets EEPROM state by reinitializing it                             |
-|`KC_GESC`      |`GRAVE_ESC`|Escape when tapped, <code>&#96;</code> when pressed with Shift or GUI|
-|`KC_LSPO`      |           |Left Shift when held, `(` when tapped                                |
-|`KC_RSPC`      |           |Right Shift when held, `)` when tapped                               |
-|`KC_LCPO`      |           |Left Control when held, `(` when tapped                              |
-|`KC_RCPC`      |           |Right Control when held, `)` when tapped                             |
-|`KC_LAPO`      |           |Left Alt when held, `(` when tapped                                  |
-|`KC_RAPC`      |           |Right Alt when held, `)` when tapped                                 |
-|`KC_SFTENT`    |           |Right Shift when held, Enter when tapped                             |
-|`KC_LEAD`      |           |The [Leader key](feature_leader_key.md)                              |
-|`KC_LOCK`      |           |The [Lock key](feature_key_lock.md)                                  |
-|`FUNC(n)`      |`F(n)`     |Call `fn_action(n)` (deprecated)                                     |
-|`M(n)`         |           |Call macro `n`                                                       |
-|`MACROTAP(n)`  |           |Macro-tap `n` idk FIXME                                              |
+|Key           |Aliases  |Description                                            |
+|--------------|---------|-------------------------------------------------------|
+|`RESET`       |         |Put the keyboard into bootloader mode for flashing     |
+|`DEBUG`       |         |Toggle debug mode                                      |
+|`EEPROM_RESET`|`EEP_RST`|Reinitializes the keyboard's EEPROM (persistent memory)|
 
 ## [Audio Keys](feature_audio.md)
 
@@ -299,7 +286,7 @@ This is a reference only. Each group of keys links to the page documenting their
 
 ## [Dynamic Macros](feature_dynamic_macros.md)
 
-|Key              |Alias    |Description                                       |
+|Key              |Aliases  |Description                                       |
 |-----------------|---------|--------------------------------------------------|
 |`DYN_REC_START1` |`DM_REC1`|Start recording Macro 1                           |
 |`DYN_REC_START2` |`DM_REC2`|Start recording Macro 2                           |
@@ -307,6 +294,18 @@ This is a reference only. Each group of keys links to the page documenting their
 |`DYN_MACRO_PLAY2`|`DM_PLY2`|Replay Macro 2                                    |
 |`DYN_REC_STOP`   |`DM_RSTP`|Finish the macro that is currently being recorded.|
 
+## [Grave Escape](feature_grave_esc.md)
+
+|Key        |Aliases  |Description                                                       |
+|-----------|---------|------------------------------------------------------------------|
+|`GRAVE_ESC`|`KC_GESC`|Escape when pressed, <code>&#96;</code> when Shift or GUI are held|
+
+## [Key Lock](feature_key_lock.md)
+
+|Key      |Description                                                   |
+|---------|--------------------------------------------------------------|
+|`KC_LOCK`|Hold down the next key pressed, until the key is pressed again|
+
 ## [Layer Switching](feature_advanced_keycodes.md#switching-and-toggling-layers)
 
 |Key             |Description                                                                       |
@@ -320,6 +319,12 @@ This is a reference only. Each group of keys links to the page documenting their
 |`TO(layer)`     |Turns on `layer` and turns off all other layers, except the default layer |
 |`TT(layer)`     |Normally acts like MO unless it's tapped multiple times, which toggles `layer` on |
 
+## [Leader Key](feature_leader_key.md)
+
+|Key      |Description             |
+|---------|------------------------|
+|`KC_LEAD`|Begins a leader sequence|
+
 ## [Mouse Keys](feature_mouse_keys.md)
 
 |Key             |Aliases  |Description                |
@@ -461,6 +466,18 @@ This is a reference only. Each group of keys links to the page documenting their
 |`OSM(mod)`  |Hold `mod` for one keypress       |
 |`OSL(layer)`|Switch to `layer` for one keypress|
 
+## [Space Cadet](feature_space_cadet.md)
+
+|Key        |Description                             |
+|-----------|----------------------------------------|
+|`KC_LCPO`  |Left Control when held, `(` when tapped |
+|`KC_RCPC`  |Right Control when held, `)` when tapped|
+|`KC_LSPO`  |Left Shift when held, `(` when tapped   |
+|`KC_RSPC`  |Right Shift when held, `)` when tapped  |
+|`KC_LAPO`  |Left Alt when held, `(` when tapped     |
+|`KC_RAPC`  |Right Alt when held, `)` when tapped    |
+|`KC_SFTENT`|Right Shift when held, Enter when tapped|
+
 ## [Swap Hands](feature_swap_hands.md)
 
 |Key        |Description                                                              |

docs/newbs_building_firmware.md

@@ -42,7 +42,7 @@ Open up your `keymap.c`. Inside this file you'll find the structure that control
 
     const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
 
-This line indicates the start of the list of Layers. Below that you'll find lines containing either `LAYOUT` or `KEYMAP`, and these lines indicate the start of a layer. Below that line is the list of keys that comprise a that particular layer.
+This line indicates the start of the list of Layers. Below that you'll find lines containing either `LAYOUT` or `KEYMAP`, and these lines indicate the start of a layer. Below that line is the list of keys that comprise a particular layer.
 
 !> When editing your keymap file be careful not to add or remove any commas. If you do you will prevent your firmware from compiling and it may not be easy to figure out where the extra, or missing, comma is.
 

docs/newbs_git_resynchronize_a_branch.md

@@ -1,6 +1,6 @@
 # Resynchronizing an Out-of-Sync Git Branch
 
-Suppose you have committed to your `master` branch, and now need to update your QMK repository. You could `git pull` QMK's `master` branch into your own, but GitHub will tell you that your commit is a number of commits ahead of `qmk:master`, which can create issues if you want to make a pull request to QMK.
+Suppose you have committed to your `master` branch, and now need to update your QMK repository. You could `git pull` QMK's `master` branch into your own, but GitHub will tell you that your branch is a number of commits ahead of `qmk:master`, which can create issues if you want to make a pull request to QMK.
 
 ?> This document builds upon the concepts detailed in [Your Fork's Master: Update Often, Commit Never](newbs_git_using_your_master_branch.md). If you are not familiar with that document, please read it first, then return here.
 

docs/porting_your_keyboard_to_qmk_(arm_and_other_chibios_cpus).md

@@ -38,7 +38,7 @@ To configure a keyboard where each switch is connected to a separate pin and gro
 
 `BACKLIGHT_BREATHING` is a fancier backlight feature that adds breathing/pulsing/fading effects to the backlight. It uses the same timer as the normal backlight. These breathing effects must be called by code in your keymap.
 
-`BACKLIGHT_LEVELS` is how many levels exist for your backlight - max is 15, and they are computed automatically from this number.
+`BACKLIGHT_LEVELS` is how many levels exist for your backlight - max is 31, and they are computed automatically from this number.
 
 ## `/keyboards/<keyboard>/Makefile`
 

docs/quantum_keycodes.md

@@ -8,21 +8,8 @@ On this page we have documented keycodes between `0x00FF` and `0xFFFF` which are
 
 ## QMK Keycodes
 
-|Key            |Aliases    |Description                                                          |
-|---------------|-----------|---------------------------------------------------------------------|
-|`RESET`        |           |Put the keyboard into DFU mode for flashing                          |
-|`DEBUG`        |           |Toggle debug mode                                                    |
-|`EEPROM_RESET` |`EEP_RST`  |Resets EEPROM state by reinitializing it                             |
-|`KC_GESC`      |`GRAVE_ESC`|Escape when tapped, <code>&#96;</code> when pressed with Shift or GUI|
-|`KC_LSPO`      |           |Left Shift when held, `(` when tapped                                |
-|`KC_RSPC`      |           |Right Shift when held, `)` when tapped                               |
-|`KC_LCPO`      |           |Left Control when held, `(` when tapped                              |
-|`KC_RCPC`      |           |Right Control when held, `)` when tapped                             |
-|`KC_LAPO`      |           |Left Alt when held, `(` when tapped                                  |
-|`KC_RAPC`      |           |Right Alt when held, `)` when tapped                                 |
-|`KC_SFTENT`    |           |Right Shift when held, Enter when tapped                             |
-|`KC_LEAD`      |           |The [Leader key](feature_leader_key.md)                              |
-|`KC_LOCK`      |           |The [Lock key](feature_key_lock.md)                                  |
-|`FUNC(n)`      |`F(n)`     |Call `fn_action(n)` (deprecated)                                     |
-|`M(n)`         |           |Call macro `n`                                                       |
-|`MACROTAP(n)`  |           |Macro-tap `n` idk FIXME                                              |
+|Key           |Aliases  |Description                                            |
+|--------------|---------|-------------------------------------------------------|
+|`RESET`       |         |Put the keyboard into bootloader mode for flashing     |
+|`DEBUG`       |         |Toggle debug mode                                      |
+|`EEPROM_RESET`|`EEP_RST`|Reinitializes the keyboard's EEPROM (persistent memory)|

docs/ru-ru/getting_started_github.md

@@ -15,17 +15,23 @@ GitHub может показаться несколько сложным для
 
 ![HTTPS link](http://i.imgur.com/eGO0ohO.jpg)
 
-Теперь введите `git clone` в командную строку, а затем вставьте ссылку:
+Теперь введите `git clone --recurse-submodules ` в командную строку, а затем вставьте ссылку:
 
 ```
-user@computer:~$ git clone https://github.com/whoeveryouare/qmk_firmware.git
+user@computer:~$ git clone --recurse-submodules https://github.com/whoeveryouare/qmk_firmware.git
 Cloning into 'qmk_firmware'...
-remote: Counting objects: 46625, done.
-remote: Compressing objects: 100% (2/2), done.
-remote: Total 46625 (delta 0), reused 0 (delta 0), pack-reused 46623
-Receiving objects: 100% (46625/46625), 84.47 MiB | 3.14 MiB/s, done.
-Resolving deltas: 100% (29362/29362), done.
-Checking out files: 100% (2799/2799), done.
+remote: Enumerating objects: 9, done.
+remote: Counting objects: 100% (9/9), done.
+remote: Compressing objects: 100% (5/5), done.
+remote: Total 183883 (delta 5), reused 4 (delta 4), pack-reused 183874
+Receiving objects: 100% (183883/183883), 132.90 MiB | 9.57 MiB/s, done.
+Resolving deltas: 100% (119972/119972), done.
+...
+Submodule path 'lib/chibios': checked out '587968d6cbc2b0e1c7147540872f2a67e59ca18b'
+Submodule path 'lib/chibios-contrib': checked out 'ede48346eee4b8d6847c19bc01420bee76a5e486'
+Submodule path 'lib/googletest': checked out 'ec44c6c1675c25b9827aacd08c02433cccde7780'
+Submodule path 'lib/lufa': checked out 'ce10f7642b0459e409839b23cc91498945119b4d'
+Submodule path 'lib/ugfx': checked out '3e97b74e03c93631cdd3ddb2ce43b963fdce19b2'
 ```
 
 Теперь у вас есть форк QMK на вашем локальном компьютере, и вы можете добавить свою раскладку, скомпилировать ее и прошить ей свою клавиатуру. Как только вы будете довольны своими изменениями, есть возможность добавить, зафиксировать их и сделать коммит в свой форк следующим образом:

docs/ru-ru/getting_started_introduction.md

@@ -4,7 +4,7 @@
 
 ## Базовая структура QMK
 
-QMK - это форк [Джуна Вако (Jun Wako)](https://github.com/tmk) проекта [tmk_keyboard](https://github.com/tmk/tmk_keyboard). Оригинальный код TMK с изменениями можно найти в папке `tmk`. Дополнения QMK к проекту можно найти в папке `quantum`. Проекты клавиатур можно найти в папках `handwired` и `keyboard`.
+QMK - это форк [Джуна Вако (Jun Wako)](https://github.com/tmk) проекта [tmk_keyboard](https://github.com/tmk/tmk_keyboard). Оригинальный код TMK с изменениями можно найти в папке `tmk_core`. Дополнения QMK к проекту можно найти в папке `quantum`. Проекты клавиатур можно найти в папках `handwired` и `keyboard`.
 
 ### Структура пространства пользователя
 

docs/ws2812_driver.md

@@ -14,7 +14,7 @@ These LEDs are called "addressable" because instead of using a wire per color, e
 |----------|--------------------|--------------------|
 | bit bang | :heavy_check_mark: | :heavy_check_mark: |
 | I2C      | :heavy_check_mark: |                    |
-| SPI      |                    | Soon™              |
+| SPI      |                    | :heavy_check_mark: |
 | PWM      |                    | Soon™              |
 
 ## Driver configuration
@@ -40,3 +40,30 @@ Configure the hardware via your config.h:
 #define WS2812_ADDRESS 0xb0 // default: 0xb0
 #define WS2812_TIMEOUT 100 // default: 100
 ```
+
+### SPI
+Targeting STM32 boards where WS2812 support is offloaded to an SPI hardware device. The advantage is that the use of DMA offloads processing of the WS2812 protocol from the MCU. `RGB_DI_PIN` for this driver is the configured SPI MOSI pin. Due to the nature of repurposing SPI to drive the LEDs, the other SPI pins, MISO and SCK, **must** remain unused. To configure it, add this to your rules.mk:
+
+```make
+WS2812_DRIVER = spi
+```
+
+Configure the hardware via your config.h:
+```c
+#define WS2812_SPI SPID1 // default: SPID1
+#define WS2812_SPI_MOSI_PAL_MODE 5 // Pin "alternate function", see the respective datasheet for the appropriate values for your MCU. default: 5
+```
+
+You must also turn on the SPI feature in your halconf.h and mcuconf.h
+
+#### Testing Notes
+
+While not an exhaustive list, the following table provides the scenarios that have been partially validated:
+
+| | SPI1 | SPI2 | SPI3 |
+|-|-|-|-|
+| f072 | ? | B15 :heavy_check_mark: | N/A |
+| f103 | A7 :heavy_check_mark: | B15 :heavy_check_mark: | N/A |
+| f303 | A7 :heavy_check_mark: B5 :heavy_check_mark:  | B15 :heavy_check_mark: | B5 :heavy_check_mark: |
+
+*Other supported ChibiOS boards and/or pins may function, it will be highly chip and configuration dependent.*

docs/zh-cn/_summary.md

@@ -3,30 +3,41 @@
   * [构建你的第一个固件](zh-cn/newbs_building_firmware.md)
   * [刷新固件](zh-cn/newbs_flashing.md)
   * [测试和调试](zh-cn/newbs_testing_debugging.md)
-  * [Git最佳实践](zh-cn/newbs_best_practices.md)
+  * [Git最佳实践](zh-cn/newbs_git_best_practices.md)
+    * [使用你分叉(fork)的主分支(master)](zh-cn/newbs_git_using_your_master_branch.md)
+    * [解决合并冲突](zh-cn/newbs_git_resolving_merge_conflicts.md)
+    * [重新同步一个分支](zh-cn/newbs_git_resynchronize_a_branch.md)
   * [学习资源](zh-cn/newbs_learn_more_resources.md)
 
 * [QMK基础](zh-cn/README.md)
   * [QMK简介](zh-cn/getting_started_introduction.md)
-  * [向QMK贡献](zh-cn/contributing.md)
+  * [QMK命令行工具](zh-cn/cli.md)
+  * [QMK命令行工具配置](zh-cn/cli_configuration.md)
+  * [向QMK贡献代码](zh-cn/contributing.md)
   * [如何使用Github](zh-cn/getting_started_github.md)
   * [获得帮助](zh-cn/getting_started_getting_help.md)
 
-* [问题解答](zh-cn/faq.md)
+* [非兼容性修改](zh-cn/breaking_changes.md)
+  * [我的PR已经被标记为非兼容性修改](zh-cn/breaking_changes_instructions.md)
+  * [2019年8月30日](zh-cn/ChangeLog/20190830.md)
+
+* [问题与解答](zh-cn/faq.md)
   * [一般问题](zh-cn/faq_general.md)
   * [构建/编译](zh-cn/faq_build.md)
   * [调试/故障排除](zh-cn/faq_debug.md)
-  * [键盘映射](zh-cn/faq_keymap.md)
+  * [布局](zh-cn/faq_keymap.md)
+  * [Zadig驱动安装](zh-cn/driver_installation_zadig.md)
 
 * 详细指南
   * [安装构建工具](zh-cn/getting_started_build_tools.md)
   * [vagrant指南](zh-cn/getting_started_vagrant.md)
-  * [构建/编译指令](zh-cn/getting_started_make_guide.md)
+  * [构建/编译指南](zh-cn/getting_started_make_guide.md)
   * [刷新固件](zh-cn/flashing.md)
   * [定制功能](zh-cn/custom_quantum_functions.md)
-  * [映射概述](zh-cn/keymap.md)
+  * [布局概述](zh-cn/keymap.md)
 
 * [硬件](zh-cn/hardware.md)
+  * [兼容的单片机](zh-cn/compatible_microcontrollers.md)
   * [AVR处理器](zh-cn/hardware_avr.md)
   * [驱动](zh-cn/hardware_drivers.md)
 
@@ -34,13 +45,16 @@
   * [键盘指南](zh-cn/hardware_keyboard_guidelines.md)
   * [配置选项](zh-cn/config_options.md)
   * [键码](zh-cn/keycodes.md)
-  * [记录最佳实践](zh-cn/documentation_best_practices.md)
+  * [代码书写规范 - C](zh-cn/coding_conventions_c.md)
+  * [代码书写规范 - Python](zh-cn/coding_conventions_python.md)
+  * [文档书写规范](zh-cn/documentation_best_practices.md)
   * [文档模板](zh-cn/documentation_templates.md)
   * [术语表](zh-cn/reference_glossary.md)
   * [单元测试](zh-cn/unit_testing.md)
-  * [有用的功能](zh-cn/ref_functions.md)
+  * [实用函数](zh-cn/ref_functions.md)
   * [配置器支持](zh-cn/reference_configurator_support.md)
   * [info.json 格式](zh-cn/reference_info_json.md)
+  * [Python 命令行开发](zh-cn/cli_development.md)
 
 * [特性](zh-cn/features.md)
   * [基本键码](zh-cn/keycodes_basic.md)
@@ -54,22 +68,27 @@
   * [热改键](zh-cn/feature_bootmagic.md)
   * [组合](zh-cn/feature_combo)
   * [命令](zh-cn/feature_command.md)
+  * [消抖 API](zh-cn/feature_debounce_type.md)
   * [拨动开关](zh-cn/feature_dip_switch.md)
   * [动态宏指令](zh-cn/feature_dynamic_macros.md)
   * [编码器](zh-cn/feature_encoders.md)
   * [重音号Esc复合键](zh-cn/feature_grave_esc.md)
+  * [触摸反馈](zh-cn/feature_haptic_feedback.md)
+  * [HD44780 LCD控制器](zh-cn/feature_hd44780.md)
   * [自锁键](zh-cn/feature_key_lock.md)
   * [布局](zh-cn/feature_layouts.md)
   * [前导键](zh-cn/feature_leader_key.md)
   * [LED阵列](zh-cn/feature_led_matrix.md)
   * [宏指令](zh-cn/feature_macros.md)
   * [鼠标键](zh-cn/feature_mouse_keys.md)
+  * [OLED驱动](zh-cn/feature_oled_driver.md)
   * [一键功能](zh-cn/feature_advanced_keycodes.md#one-shot-keys)
   * [指针设备](zh-cn/feature_pointing_device.md)
   * [PS/2鼠标](zh-cn/feature_ps2_mouse.md)
   * [RGB灯光](zh-cn/feature_rgblight.md)
   * [RGB矩阵](zh-cn/feature_rgb_matrix.md)
   * [空格候补换挡](zh-cn/feature_space_cadet.md)
+  * [分体键盘](zh-cn/feature_split_keyboard.md)
   * [速录机](zh-cn/feature_stenography.md)
   * [换手](zh-cn/feature_swap_hands.md)
   * [多击键](zh-cn/feature_tap_dance.md)
@@ -79,28 +98,35 @@
   * [用户空间](zh-cn/feature_userspace.md)
   * [速度键](zh-cn/feature_velocikey.md)
 
-* 针对制造者和定制者
+* 制造和定制者指南
   * [手工连线指南](zh-cn/hand_wire.md)
   * [ISP刷新指南](zh-cn/isp_flashing_guide.md)
   * [ARM调试指南](zh-cn/arm_debugging.md)
-  * [I2C驱动](zh-cn/i2c_driver.md)
-  * [GPIO控制器](zh-cn/internals_gpio_control.md)
+  * [ADC设备](zh-cn/adc_driver.md)
+  * [I2C设备](zh-cn/i2c_driver.md)
+  * [WS2812设备](zh-cn/ws2812_driver.md)
+  * [EEPROM设备](zh-cn/eeprom_driver.md)
+  * [GPIO控制](zh-cn/internals_gpio_control.md)
+  * [自定义键盘矩阵](zh-cn/custom_matrix.md)
   * [Proton C转换](zh-cn/proton_c_conversion.md)
 
 * 深入了解
-  * [键盘如何工作](zh-cn/how_keyboards_work.md)
-  * [理解QMK](zh-cn/understanding_qmk.md)
+  * [键盘工作原理](zh-cn/how_keyboards_work.md)
+  * [深入了解QMK](zh-cn/understanding_qmk.md)
 
 * 其他话题
   * [使用Eclipse开发QMK](zh-cn/other_eclipse.md)
   * [使用VSCode开发QMK](zh-cn/other_vscode.md)
   * [支持](zh-cn/support.md)
+  * [翻译QMK文档](zh-cn/translating.md)
 
 * QMK 内构 (正在编写)
   * [定义](zh-cn/internals_defines.md)
   * [输入回调寄存器](zh-cn/internals_input_callback_reg.md)
   * [Midi设备](zh-cn/internals_midi_device.md)
-  * [Midi设备设置过程](zh-cn/internals_midi_device_setup_process.md)
+  * [Midi设备配置过程](zh-cn/internals_midi_device_setup_process.md)
   * [Midi工具库](zh-cn/internals_midi_util.md)
   * [发送函数](zh-cn/internals_send_functions.md)
   * [Sysex工具](zh-cn/internals_sysex_tools.md)
+<!--fromen:20200126-6:03AM(GMT+8)-->
+<!--cn:20200211-11:04AM(GMT+8)-->

docs/zh-cn/custom_quantum_functions.md

@@ -1,31 +1,31 @@
-# <EFBFBD><EFBFBD><EFBFBD>ζ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>̵Ĺ<EFBFBD><EFBFBD><EFBFBD>
+# 如何定制你键盘的功能
 
-<EFBFBD><EFBFBD><EFBFBD>ںܶ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>˵<EFBFBD><EFBFBD><EFBFBD>ƻ<EFBFBD><EFBFBD><EFBFBD><EFBFBD>̿ɲ<EFBFBD>ֻ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ĵ<EFBFBD><EFBFBD>Է<EFBFBD><EFBFBD><EFBFBD><EFBFBD>㰴<EFBFBD><EFBFBD><EFBFBD>Ǹ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ô<EFBFBD>򵥡<EFBFBD><EFBFBD><EFBFBD><EFBFBD>϶<EFBFBD><EFBFBD><EFBFBD>ʵ<EFBFBD>ֱȼ򵥰<EFBFBD><EFBFBD><EFBFBD><EFBFBD>ͺ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ӵĹ<EFBFBD><EFBFBD>ܡ<EFBFBD>QMK<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ע<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>Ĺ<EFBFBD><EFBFBD><EFBFBD>, <20><><EFBFBD>ǹ<EFBFBD><C7B9><EFBFBD>, <20><><EFBFBD>⣬<EFBFBD><E2A3AC><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>Զ<EFBFBD><D4B6><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ڲ<EFBFBD>ͬ<EFBFBD><CDAC><EFBFBD><EFBFBD><EFBFBD>µ<EFBFBD><C2B5><EFBFBD>Ϊ<EFBFBD><CEAA>
+对于很多人来说客制化键盘可不只是向你的电脑发送你按了那个件这么简单。你肯定想实现比简单按键和宏更复杂的功能。QMK有能让你注入代码的钩子, 覆盖功能, 另外，还可以自定义键盘在不同情况下的行为。
 
-<EFBFBD><EFBFBD>ҳ<EFBFBD><EFBFBD><EFBFBD>ٶ<EFBFBD><EFBFBD>κ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>QMK֪ʶ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>Ķ<EFBFBD>[<EFBFBD><EFBFBD><EFBFBD><EFBFBD>QMK](understanding_qmk.md)<29><><EFBFBD><EFBFBD><EFBFBD>ڸ<EFBFBD><DAB8><EFBFBD><EFBFBD><EFBFBD><EFBFBD>IJ<EFBFBD><C4B2><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ⷢ<EFBFBD><E2B7A2><EFBFBD><EFBFBD>ʲô<CAB2><C3B4>
+本页不假定任何特殊的QMK知识，但阅读[理解QMK](understanding_qmk.md)将会在更基础的层面帮你理解发生了什么。
 
-## A Word on Core vs <EFBFBD><EFBFBD><EFBFBD><EFBFBD> vs <20><><EFBFBD><EFBFBD>
+## A Word on Core vs 键盘 vs 布局
 
-<EFBFBD><EFBFBD><EFBFBD>ǰ<EFBFBD>qmk<EFBFBD><EFBFBD>֯<EFBFBD><EFBFBD>һ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>νṹ<EFBFBD><EFBFBD>
+我们把qmk组织成一个层次结构：
 
 * Core (`_quantum`)
   * Keyboard/Revision (`_kb`)
     * Keymap (`_user`)
 
-<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ÿһ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ڶ<EFBFBD><EFBFBD><EFBFBD><EFBFBD>ϼ<EFBFBD>һ<EFBFBD><EFBFBD>`_kb()`<EFBFBD><EFBFBD> `_user()` <EFBFBD><EFBFBD>׺<EFBFBD><EFBFBD> <20><><EFBFBD><EFBFBD><EFBFBD>ڼ<EFBFBD><DABC><EFBFBD>/<2F>޶<EFBFBD><DEB6><EFBFBD>ʹ<EFBFBD><CAB9>`_kb()`<EFBFBD><EFBFBD>׺<EFBFBD><EFBFBD><EFBFBD>ڲ<EFBFBD><EFBFBD>ֲ<EFBFBD>ʹ<EFBFBD><EFBFBD>`_user()`<EFBFBD><EFBFBD>׺<EFBFBD><EFBFBD>
+下面描述的每一个函数都可以在定义上加一个`_kb()`或 `_user()` 后缀。 建议在键盘/修订层使用`_kb()`后缀，在布局层使用`_user()`后缀。
 
-<EFBFBD>ڼ<EFBFBD><EFBFBD><EFBFBD>/<2F>޶<EFBFBD><DEB6>㶨<EFBFBD>庯<EFBFBD><E5BAAF>ʱ<EFBFBD><CAB1>`_kb()`<EFBFBD><EFBFBD>ִ<EFBFBD><EFBFBD><EFBFBD>κδ<EFBFBD><EFBFBD><EFBFBD>ǰ<EFBFBD>ȵ<EFBFBD><EFBFBD><EFBFBD>`_user()`<EFBFBD>DZ<EFBFBD>Ҫ<EFBFBD>ģ<EFBFBD><EFBFBD><EFBFBD>Ȼ<EFBFBD><EFBFBD><EFBFBD>ֲ㺯<EFBFBD><EFBFBD><EFBFBD>Ͳ<EFBFBD>Ҫ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>á<EFBFBD>
-<!-- <EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>⣺<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>Ǿ䷭<EFBFBD><EFBFBD><EFBFBD>IJ<EFBFBD>̫<EFBFBD><EFBFBD>-->
-# <EFBFBD>Զ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>
+在键盘/修订层定义函数时，`_kb()`在执行任何代码前先调用`_user()`是必要的，不然布局层函数就不要被调用。
+<!-- 翻译问题：上面那句翻译的不太好-->
+# 自定义键码
 
-<EFBFBD><EFBFBD>ĿǰΪֹ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>Ǹ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>м<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>Ϊ<EFBFBD>򴴽<EFBFBD><EFBFBD>µļ<EFBFBD><EFBFBD>롣<EFBFBD>Ӵ<EFBFBD><EFBFBD><EFBFBD><EFBFBD>Ƕ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>Щ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ơ<EFBFBD>
+到目前为止，最常见的任务是更改现有键码的行为或创建新的键码。从代码角度来看这些操作都很相似。
 
-## <EFBFBD><EFBFBD><EFBFBD><EFBFBD>һ<EFBFBD><EFBFBD><EFBFBD>¼<EFBFBD><EFBFBD><EFBFBD>
+## 定义一个新键码
 
-<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>һ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ö<EFBFBD>ٳ<EFBFBD><EFBFBD><EFBFBD>ȫ<EFBFBD><EFBFBD><EFBFBD><EFBFBD>Ҳ<EFBFBD><EFBFBD><EFBFBD>Ǹ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ֲ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>Ψһ<EFBFBD><EFBFBD>ֵ<EFBFBD><EFBFBD>QMKû<EFBFBD><EFBFBD>ֱ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ֵ<EFBFBD><EFBFBD>С<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ṩ<EFBFBD><EFBFBD>һ<EFBFBD><EFBFBD>`SAFE_RANGE`<EFBFBD>ꡣ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ö<EFBFBD><EFBFBD>ʱ<EFBFBD><EFBFBD>`SAFE_RANGE`<EFBFBD><EFBFBD><EFBFBD><EFBFBD>֤<EFBFBD><EFBFBD>ȡ<EFBFBD><EFBFBD><EFBFBD><EFBFBD>Ψһ<EFBFBD>ļ<EFBFBD><EFBFBD><EFBFBD>ֵ<EFBFBD><EFBFBD>
+创建键码第一步，先枚举出它全部，也就是给键码起个名字并分配唯一数值。QMK没有直接限制最大键码值大小，而是提供了一个`SAFE_RANGE`宏。你可以在枚举时用`SAFE_RANGE`来保证你取得了唯一的键码值。
 
 
-<EFBFBD><EFBFBD><EFBFBD><EFBFBD>ö<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ӡ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ӵ<EFBFBD>`keymap.c`<EFBFBD>Ļ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ڲ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>`FOO`<EFBFBD><EFBFBD>`BAR`<EFBFBD>ˡ<EFBFBD>
+这有枚举两个键码的例子。把这块加到`keymap.c`的话你就在布局中能用`FOO`和`BAR`了。
 
 ```c
 enum my_keycodes {
@@ -34,46 +34,46 @@ enum my_keycodes {
 };
 ```
 
-## Ϊ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>Ϊ<EFBFBD><EFBFBD><EFBFBD><EFBFBD>
+## 为键码的行为编程
 
-<EFBFBD><EFBFBD><EFBFBD>㸲<EFBFBD><EFBFBD>һ<EFBFBD><EFBFBD><EFBFBD>Ѵ<EFBFBD><EFBFBD>ڰ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>Ϊʱ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>Ϊ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>¼<EFBFBD>ʱ<EFBFBD><EFBFBD><EFBFBD><EFBFBD>Ҫ<EFBFBD><EFBFBD>`process_record_kb()`<EFBFBD><EFBFBD>`process_record_user()`<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ڼ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ʵ<EFBFBD><EFBFBD><EFBFBD>¼<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ǰ<EFBFBD><EFBFBD>QMK<EFBFBD><EFBFBD><EFBFBD>á<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>`true`<EFBFBD><EFBFBD>QMK<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ķ<EFBFBD>ʽ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>롣<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>Ժܷ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>չ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>Ĺ<EFBFBD><EFBFBD>ܶ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>滻<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>`false` QMK<4D><4B><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>Ȼ<EFBFBD><C8BB><EFBFBD><EFBFBD><EFBFBD>ͼ<EFBFBD><CDBC><EFBFBD>̧<EFBFBD><CCA7><EFBFBD><EFBFBD><EFBFBD>ǰ<EFBFBD><C7B0><EFBFBD><EFBFBD>¼<EFBFBD><C2BC><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ˡ<EFBFBD>
+当你覆盖一个已存在按键的行为时，或将这个行为赋给新键时，你要用`process_record_kb()`和`process_record_user()`函数。这俩函数在键处理中真实键事件被处理前被QMK调用。如果这俩函数返回`true`，QMK将会用正常的方式处理键码。这样可以很方便的扩展键码的功能而不是替换它。如果函数返回`false` QMK会跳过正常键处理，然后发送键子抬起还是按下事件就由你决定了。
 
-<EFBFBD><EFBFBD>ij<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>»<EFBFBD><EFBFBD>ͷ<EFBFBD>ʱ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ᱻ<EFBFBD><EFBFBD><EFBFBD>á<EFBFBD>
+当某个键按下或释放时这俩函数会被调用。
 
-### process_record_user()`<EFBFBD><EFBFBD><EFBFBD><EFBFBD>ʾ<EFBFBD><EFBFBD>ʵ<EFBFBD><EFBFBD>
+### process_record_user()`函数示例实现
 
-<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>¡<EFBFBD><EFBFBD>Զ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>һ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>`FOO`<EFBFBD>ļ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>Ϊ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ڰ<EFBFBD><EFBFBD>»س<EFBFBD>ʱ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>
+这个例子做了两个事。自定义了一个叫做`FOO`的键码的行为，并补充了在按下回车时播放音符。
 
 ```c
 bool process_record_user(uint16_t keycode, keyrecord_t *record) {
   switch (keycode) {
     case FOO:
       if (record->event.pressed) {
-        // <EFBFBD><EFBFBD><EFBFBD><EFBFBD>ʱ<EFBFBD><EFBFBD>Щʲô
+        // 按下时做些什么
       } else {
-        // <EFBFBD>ͷ<EFBFBD>ʱ<EFBFBD><EFBFBD>Щʲô
+        // 释放时做些什么
       }
-      return false; // <EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>˼<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>н<EFBFBD>һ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>
+      return false; // 跳过此键的所有进一步处理
     case KC_ENTER:
-      // <EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>»س<EFBFBD>ʱ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>
+      // 当按下回车时播放音符
       if (record->event.pressed) {
         PLAY_NOTE_ARRAY(tone_qwerty);
       }
-      return true; // <EFBFBD><EFBFBD>QMK<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>س<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>/<2F>ͷ<EFBFBD><CDB7>¼<EFBFBD>
+      return true; // 让QMK触发回车按下/释放事件
     default:
-      return true; // <EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>
+      return true; // 正常处理其他键码
   }
 }
 ```
 
-### `process_record_*` <EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ĵ<EFBFBD>
+### `process_record_*` 函数文档
 
-* <EFBFBD><EFBFBD><EFBFBD><EFBFBD>/<2F>޶<EFBFBD>: `bool process_record_kb(uint16_t keycode, keyrecord_t *record)`
-* <EFBFBD><EFBFBD><EFBFBD><EFBFBD>: `bool process_record_user(uint16_t keycode, keyrecord_t *record)`
+* 键盘/修订: `bool process_record_kb(uint16_t keycode, keyrecord_t *record)`
+* 布局: `bool process_record_user(uint16_t keycode, keyrecord_t *record)`
 
-`keycode(<EFBFBD><EFBFBD><EFBFBD><EFBFBD>)`<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ڲ<EFBFBD><EFBFBD><EFBFBD><EFBFBD>϶<EFBFBD><EFBFBD><EFBFBD><EFBFBD>ģ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>`MO(1)`, `KC_L`, <EFBFBD>ȵȡ<EFBFBD> <20><>Ҫ<EFBFBD><D2AA> `switch...case` <EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>Щ<EFBFBD>¼<EFBFBD><EFBFBD><EFBFBD>
+`keycode(键码)`参数是在布局上定义的，比如`MO(1)`, `KC_L`, 等等。 你要用 `switch...case` 块来处理这些事件。
 
-`record`<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ʵ<EFBFBD>ʰ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>Ϣ<EFBFBD><EFBFBD>
+`record`参数含有实际按键的信息：
 
 ```c
 keyrecord_t record {
@@ -88,9 +88,9 @@ keyrecord_t record {
 }
 ```
 
-# LED<EFBFBD><EFBFBD><EFBFBD><EFBFBD>
+# LED控制
 
-qmk<EFBFBD>ṩ<EFBFBD>˶<EFBFBD>ȡHID<EFBFBD>淶<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>5<EFBFBD><EFBFBD>LED<EFBFBD>ķ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>:
+qmk提供了读取HID规范包含的5个LED的方法。:
 
 * `USB_LED_NUM_LOCK`
 * `USB_LED_CAPS_LOCK`
@@ -98,20 +98,20 @@ qmk
 * `USB_LED_COMPOSE`
 * `USB_LED_KANA`
 
-<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>Ӧ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>LED״̬<EFBFBD><EFBFBD>λ<EFBFBD><EFBFBD>λ<EFBFBD><EFBFBD>
-<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ַ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>Ի<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>LED״̬<EFBFBD><EFBFBD>
+这五个常量对应于主机LED状态的位置位。
+有两种方法可以获得主机LED状态：
 
-* ͨ<EFBFBD><EFBFBD>ִ<EFBFBD><EFBFBD> `led_set_user()`
-* ͨ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD> `host_keyboard_leds()`
+* 通过执行 `led_set_user()`
+* 通过调用 `host_keyboard_leds()`
 
 ## `led_set_user()`
 
-<EFBFBD><EFBFBD>5<EFBFBD><EFBFBD>LED<EFBFBD><EFBFBD><EFBFBD>κ<EFBFBD>һ<EFBFBD><EFBFBD><EFBFBD><EFBFBD>״̬<EFBFBD><EFBFBD>Ҫ<EFBFBD>ı<EFBFBD>ʱ<EFBFBD><EFBFBD><EFBFBD>˺<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>á<EFBFBD><EFBFBD>˺<EFBFBD><EFBFBD><EFBFBD>ͨ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>LED<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>
-ʹ<EFBFBD><EFBFBD>`IS_LED_ON(usb_led, led_name)`<EFBFBD><EFBFBD>`IS_LED_OFF(usb_led, led_name)`<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>LED״̬<EFBFBD><EFBFBD>
+当5个LED中任何一个的状态需要改变时，此函数将被调用。此函数通过参数输入LED参数。
+使用`IS_LED_ON(usb_led, led_name)`和`IS_LED_OFF(usb_led, led_name)`这两个宏来检查LED状态。
 
-!> `host_keyboard_leds()`<EFBFBD><EFBFBD><EFBFBD>ܻ<EFBFBD><EFBFBD><EFBFBD>`led_set_user()`<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ǰ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ֵ<EFBFBD><EFBFBD>
+!> `host_keyboard_leds()`可能会在`led_set_user()`被调用前返回新值。
 
-### `led_set_user()`<EFBFBD><EFBFBD><EFBFBD><EFBFBD>ʾ<EFBFBD><EFBFBD>ʵ<EFBFBD><EFBFBD>
+### `led_set_user()`函数示例实现
 
 ```c
 void led_set_user(uint8_t usb_led) {
@@ -143,59 +143,59 @@ void led_set_user(uint8_t usb_led) {
 }
 ```
 
-### `led_set_*`<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ĵ<EFBFBD>
+### `led_set_*`函数文档
 
-* <EFBFBD><EFBFBD><EFBFBD><EFBFBD>/<2F>޶<EFBFBD>: `void led_set_kb(uint8_t usb_led)`
-* <EFBFBD><EFBFBD><EFBFBD><EFBFBD>: `void led_set_user(uint8_t usb_led)`
+* 键盘/修订: `void led_set_kb(uint8_t usb_led)`
+* 布局: `void led_set_user(uint8_t usb_led)`
 
 ## `host_keyboard_leds()`
 
-<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>᷵<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>յ<EFBFBD><EFBFBD><EFBFBD>LED״̬<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>`led_set_*`֮<EFBFBD><EFBFBD><EFBFBD><EFBFBD>ȡLED״̬ʱ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ã<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>[`matrix_scan_user()`](#<EFBFBD><EFBFBD><EFBFBD><EFBFBD>ɨ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>).
-Ϊ<EFBFBD>˱<EFBFBD><EFBFBD>ݣ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>`IS_HOST_LED_ON(led_name)`<EFBFBD><EFBFBD>`IS_HOST_LED_OFF(led_name)` <EFBFBD>꣬<EFBFBD><EFBFBD><EFBFBD><EFBFBD>ֱ<EFBFBD>ӵ<EFBFBD><EFBFBD>úͼ<EFBFBD><EFBFBD><EFBFBD>`host_keyboard_leds()`<EFBFBD><EFBFBD>
+调用这个函数会返回最后收到的LED状态。这个函数在`led_set_*`之外读取LED状态时很有用，比如在[`matrix_scan_user()`](#矩阵扫描代码).
+为了便捷，你可以用`IS_HOST_LED_ON(led_name)`和`IS_HOST_LED_OFF(led_name)` 宏，而不直接调用和检查`host_keyboard_leds()`。
 
-## <EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>LED״̬
+## 设置物理LED状态
 
-һЩ<EFBFBD><EFBFBD><EFBFBD><EFBFBD>ʵ<EFBFBD><EFBFBD><EFBFBD><EFBFBD>Ϊ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>LED<EFBFBD><EFBFBD>״̬<EFBFBD>ṩ<EFBFBD>˷<EFBFBD><EFBFBD><EFBFBD><EFBFBD>ķ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>
+一些键盘实现了为设置物理LED的状态提供了方便的方法。
 
 ### Ergodox Boards
 
-Ergodoxʵ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ṩ`ergodox_right_led_1`/`2`/`3_on`/`off()`<EFBFBD><EFBFBD><EFBFBD><EFBFBD>ÿ<EFBFBD><EFBFBD>LED<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>, Ҳ<><D2B2><EFBFBD><EFBFBD><EFBFBD><EFBFBD> `ergodox_right_led_on`/`off(uint8_t led)` <EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>򿪻<EFBFBD><EFBFBD>ر<EFBFBD><EFBFBD><EFBFBD><EFBFBD>ǡ<EFBFBD>
+Ergodox实现了提供`ergodox_right_led_1`/`2`/`3_on`/`off()`来让每个LED开或关, 也可以用 `ergodox_right_led_on`/`off(uint8_t led)` 按索引打开或关闭他们。
 
-<EFBFBD><EFBFBD><EFBFBD>⣬<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ʹ<EFBFBD><EFBFBD>`ergodox_led_all_set(uint8_t n)`ָ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>LED<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ȼ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ÿ<EFBFBD><EFBFBD>LED<EFBFBD><EFBFBD>`ergodox_right_led_1`/`2`/`3_set(uint8_t n)`<EFBFBD><EFBFBD>ʹ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>Ļ<EFBFBD><EFBFBD><EFBFBD>`ergodox_right_led_set(uint8_t led, uint8_t n)`<EFBFBD><EFBFBD>
+此外，还可以使用`ergodox_led_all_set(uint8_t n)`指定所有LED的亮度级别；针对每个LED用`ergodox_right_led_1`/`2`/`3_set(uint8_t n)`；使用索引的话用`ergodox_right_led_set(uint8_t led, uint8_t n)`。
 
-Ergodox boards ͬʱ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ȼ<EFBFBD><EFBFBD><EFBFBD>`LED_BRIGHTNESS_LO`<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ȼ<EFBFBD><EFBFBD><EFBFBD>`LED_BRIGHTNESS_HI`(Ĭ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>).
+Ergodox boards 同时定义了最低亮度级别`LED_BRIGHTNESS_LO`和最高亮度级别`LED_BRIGHTNESS_HI`(默认最高).
 
-# <EFBFBD><EFBFBD><EFBFBD>̳<EFBFBD>ʼ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>
+# 键盘初始化代码
 
-<EFBFBD><EFBFBD><EFBFBD>̳<EFBFBD>ʼ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>м<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>衣<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>Ǹ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ȡ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>Ҫ<EFBFBD><EFBFBD>ʲô<EFBFBD><EFBFBD>
+键盘初始化过程有几个步骤。你是用那个函数取决于你想要做什么。
 
-<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>Ҫ<EFBFBD><EFBFBD>ʼ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>˳<EFBFBD><EFBFBD><EFBFBD>г<EFBFBD><EFBFBD><EFBFBD>
+有三个主要初始化函数，按调用顺序列出。
 
-* `keyboard_pre_init_*` - <EFBFBD><EFBFBD><EFBFBD>ڴ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ǰ<EFBFBD><EFBFBD><EFBFBD>С<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>Щ<EFBFBD><EFBFBD>Ҫ<EFBFBD><EFBFBD>ǰ<EFBFBD><EFBFBD><EFBFBD>е<EFBFBD>Ӳ<EFBFBD><EFBFBD><EFBFBD><EFBFBD>ʼ<EFBFBD><EFBFBD><EFBFBD><EFBFBD>
-* `matrix_init_*` - <EFBFBD>ڹ̼<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>м䱻<EFBFBD><EFBFBD><EFBFBD>á<EFBFBD><EFBFBD><EFBFBD>ʱӲ<EFBFBD><EFBFBD><EFBFBD>ѳ<EFBFBD>ʼ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>δ<EFBFBD><EFBFBD>ʼ<EFBFBD><EFBFBD><EFBFBD><EFBFBD>
-* `keyboard_post_init_*` - <EFBFBD>ڹ̼<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>󱻵<EFBFBD><EFBFBD>á<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>£<EFBFBD><EFBFBD><EFBFBD><EFBFBD>ġ<EFBFBD><EFBFBD><EFBFBD><EFBFBD>ƻ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>붼<EFBFBD><EFBFBD><EFBFBD>Է<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>
+* `keyboard_pre_init_*` - 会在大多数其他东西运行前运行。适用于哪些需要提前运行的硬件初始化。
+* `matrix_init_*` - 在固件启动过程中间被调用。此时硬件已初始化，功能尚未初始化。
+* `keyboard_post_init_*` - 在固件启动过程最后被调用。大多数情况下，你的“客制化”代码都可以放在这里。
 
-!> <EFBFBD><EFBFBD><EFBFBD>ڴ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>˵`keyboard_post_init_user`<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>Ҫ<EFBFBD><EFBFBD><EFBFBD>õĺ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>, <20><>ʱ<EFBFBD><CAB1><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>RGB<47>Ʒ<EFBFBD><C6B7>⡣
+!> 对于大多数人来说`keyboard_post_init_user`是你想要调用的函数。例如, 此时你可以设置RGB灯发光。
 
-## <EFBFBD><EFBFBD><EFBFBD><EFBFBD>Ԥ<EFBFBD><EFBFBD>ʼ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>
+## 键盘预初始化代码
 
-<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>뼫<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>У<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>USB<EFBFBD><EFBFBD>ʼ<EFBFBD><EFBFBD>ǰ<EFBFBD><EFBFBD><EFBFBD>С<EFBFBD>
+这代码极早运行，甚至都在USB初始化前运行。
 
-<EFBFBD><EFBFBD><EFBFBD><EFBFBD>֮<EFBFBD>󲻾þ<EFBFBD><EFBFBD><EFBFBD><EFBFBD>ͱ<EFBFBD><EFBFBD><EFBFBD>ʼ<EFBFBD><EFBFBD><EFBFBD>ˡ<EFBFBD>
+在这之后不久矩阵就被初始化了。
 
-<EFBFBD><EFBFBD><EFBFBD>ڴ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>û<EFBFBD><EFBFBD><EFBFBD>˵,<2C><><EFBFBD>ò<EFBFBD><C3B2><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>Ϊ<EFBFBD><CEAA><EFBFBD><EFBFBD>Ҫ<EFBFBD><D2AA><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>Ӳ<EFBFBD><D3B2><EFBFBD>ij<EFBFBD>ʼ<EFBFBD><CABC><EFBFBD><EFBFBD>
+对于大多数用户来说,这用不到，因为它主要是用于面向硬件的初始化。
 
-<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>Ӳ<EFBFBD><EFBFBD><EFBFBD><EFBFBD>ʼ<EFBFBD><EFBFBD><EFBFBD>Ļ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ٺò<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>(<28><><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ʼ<EFBFBD><CABC>LED<45><44><EFBFBD><EFBFBD>һ<EFBFBD><D2BB><EFBFBD><EFBFBD>).
+但如果你有硬件初始化的话放在这里再好不过了(比如初始化LED引脚一类的).
 
-### `keyboard_pre_init_user()`<EFBFBD><EFBFBD><EFBFBD><EFBFBD>ʾ<EFBFBD><EFBFBD>ʵ<EFBFBD><EFBFBD>
+### `keyboard_pre_init_user()`函数示例实现
 
-<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ڼ<EFBFBD><EFBFBD>̼<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>趨 B0, B1, B2, B3, <EFBFBD><EFBFBD> B4 <EFBFBD><EFBFBD>LED<EFBFBD><EFBFBD><EFBFBD>š<EFBFBD>
+本例中在键盘级别，设定 B0, B1, B2, B3, 和 B4 是LED引脚。
 
 ```c
 void keyboard_pre_init_user(void) {
-  // <EFBFBD><EFBFBD><EFBFBD>ü<EFBFBD><EFBFBD><EFBFBD>Ԥ<EFBFBD><EFBFBD>ʼ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>
+  // 调用键盘预初始化代码
 
-  // <EFBFBD><EFBFBD><EFBFBD><EFBFBD>LED<EFBFBD><EFBFBD><EFBFBD><EFBFBD>Ϊ<EFBFBD><EFBFBD><EFBFBD><EFBFBD>ģʽ
+  // 设置LED引脚为输出模式
   setPinOutput(B0);
   setPinOutput(B1);
   setPinOutput(B2);
@@ -204,73 +204,73 @@ void keyboard_pre_init_user(void) {
 }
 ```
 
-### `keyboard_pre_init_*` <EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ĵ<EFBFBD>
+### `keyboard_pre_init_*` 函数文档
 
-* <EFBFBD><EFBFBD><EFBFBD><EFBFBD>/<2F>޶<EFBFBD>: `void keyboard_pre_init_kb(void)`
-* <EFBFBD><EFBFBD><EFBFBD><EFBFBD>: `void keyboard_pre_init_user(void)`
+* 键盘/修订: `void keyboard_pre_init_kb(void)`
+* 布局: `void keyboard_pre_init_user(void)`
 
-## <EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ʼ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>
+## 矩阵初始化代码
 
-<EFBFBD>⽫<EFBFBD><EFBFBD><EFBFBD>ھ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ʼ<EFBFBD><EFBFBD>ʱ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ã<EFBFBD><EFBFBD><EFBFBD>ijЩӲ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>úú󣬵<EFBFBD><EFBFBD><EFBFBD>һЩ<EFBFBD><EFBFBD><EFBFBD>ܱ<EFBFBD><EFBFBD><EFBFBD>ʼ<EFBFBD><EFBFBD>ǰ<EFBFBD><EFBFBD> 
+这将会在矩阵初始化时被调用，在某些硬件设置好后，但在一些功能被初始化前。 
 
-<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ط<EFBFBD><EFBFBD><EFBFBD><EFBFBD>õ<EFBFBD><EFBFBD>Ķ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ʱ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ã<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>Ӳ<EFBFBD><EFBFBD><EFBFBD>޹أ<EFBFBD>Ҳ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>λ<EFBFBD>á<EFBFBD>
+这在你设置其他地方会用到的东西的时候会很有用，但与硬件无关，也不依赖于它的启动位置。
 
 
-### `matrix_init_*`<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ĵ<EFBFBD>
+### `matrix_init_*`函数文档
 
-* <EFBFBD><EFBFBD><EFBFBD><EFBFBD>/<2F>޶<EFBFBD>: `void matrix_init_kb(void)`
-* <EFBFBD><EFBFBD><EFBFBD><EFBFBD>: `void matrix_init_user(void)`
+* 键盘/修订: `void matrix_init_kb(void)`
+* 布局: `void matrix_init_user(void)`
 
 
-## <EFBFBD><EFBFBD><EFBFBD>̺<EFBFBD><EFBFBD><EFBFBD>ʼ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>
+## 键盘后初始化代码
 
-<EFBFBD><EFBFBD><EFBFBD>Ǽ<EFBFBD><EFBFBD>̳<EFBFBD>ʼ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>е<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>һ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ijЩ<EFBFBD><EFBFBD><EFBFBD>ԣ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ã<EFBFBD><EFBFBD><EFBFBD>Ϊ<EFBFBD><EFBFBD>ʱӦ<EFBFBD>ö<EFBFBD><EFBFBD><EFBFBD><EFBFBD>ǽ<EFBFBD><EFBFBD>г<EFBFBD>ʼ<EFBFBD><EFBFBD><EFBFBD><EFBFBD>
+这是键盘初始化过程中的最后一个任务。如果您想更改某些特性，这会很有用，因为此时应该对它们进行初始化。
 
 
-### `keyboard_post_init_user()`ʾ<EFBFBD><EFBFBD>ʵ<EFBFBD><EFBFBD>
+### `keyboard_post_init_user()`示例实现
 
-<EFBFBD><EFBFBD>ʾ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>г<EFBFBD>ʼ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ɺ<EFBFBD><EFBFBD><EFBFBD><EFBFBD>У<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>RGB<EFBFBD>ơ<EFBFBD>
+本示例在所有初始化完成后运行，配置RGB灯。
 
 ```c
 void keyboard_post_init_user(void) {
-  // <EFBFBD><EFBFBD><EFBFBD>ú<EFBFBD><EFBFBD><EFBFBD>ʼ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>
-  rgblight_enable_noeeprom(); // ʹ<EFBFBD><EFBFBD>Rgb<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>
-  rgblight_sethsv_noeeprom(180, 255, 255); // <EFBFBD><EFBFBD><EFBFBD><EFBFBD>ɫ<EFBFBD><EFBFBD><EFBFBD>õ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ɫ(<28><>ɫ)<29><><EFBFBD><EFBFBD><EFBFBD><EFBFBD>
-  rgblight_mode_noeeprom(RGBLIGHT_MODE_BREATHING + 3); // <EFBFBD><EFBFBD><EFBFBD>ÿ<EFBFBD><EFBFBD>ٺ<EFBFBD><EFBFBD><EFBFBD>ģʽ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>
+  // 调用后初始化代码
+  rgblight_enable_noeeprom(); // 使能Rgb，不保存设置
+  rgblight_sethsv_noeeprom(180, 255, 255); // 将颜色设置到蓝绿色(青色)不保存
+  rgblight_mode_noeeprom(RGBLIGHT_MODE_BREATHING + 3); // 设置快速呼吸模式不保存
 }
 ```
 
-### `keyboard_post_init_*` <EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ĵ<EFBFBD>
+### `keyboard_post_init_*` 函数文档
 
-* <EFBFBD><EFBFBD><EFBFBD><EFBFBD>/<2F>޶<EFBFBD>: `void keyboard_post_init_kb(void)`
-* <EFBFBD><EFBFBD><EFBFBD><EFBFBD>: `void keyboard_post_init_user(void)`
+* 键盘/修订: `void keyboard_post_init_kb(void)`
+* 布局: `void keyboard_post_init_user(void)`
 
-# <EFBFBD><EFBFBD><EFBFBD><EFBFBD>ɨ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>
+# 矩阵扫描代码
 
-<EFBFBD><EFBFBD><EFBFBD>ܵĻ<EFBFBD><EFBFBD><EFBFBD>Ҫ<EFBFBD><EFBFBD>`process_record_*()`<EFBFBD>Զ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>̣<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ַ<EFBFBD>ʽ<EFBFBD><EFBFBD><EFBFBD>ӵ<EFBFBD><EFBFBD>¼<EFBFBD><EFBFBD>У<EFBFBD><EFBFBD><EFBFBD>ȷ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>벻<EFBFBD><EFBFBD><EFBFBD>Լ<EFBFBD><EFBFBD>̲<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>Ӱ<EFBFBD>졣Ȼ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ڼ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>£<EFBFBD><EFBFBD>б<EFBFBD>Ҫ<EFBFBD><EFBFBD><EFBFBD>о<EFBFBD><EFBFBD><EFBFBD>ɨ<EFBFBD>衣<EFBFBD><EFBFBD><EFBFBD><EFBFBD>Щ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>Ҫ<EFBFBD>ر<EFBFBD>ע<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ܣ<EFBFBD><EFBFBD><EFBFBD>Ϊ<EFBFBD><EFBFBD>ÿ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ٱ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>10<EFBFBD>Ρ<EFBFBD>
+可能的话你要用`process_record_*()`自定义键盘，以这种方式连接到事件中，以确保代码不会对键盘产生负面的性能影响。然而，在极少数情况下，有必要进行矩阵扫描。在这些函数中要特别注意代码的性能，因为它每秒至少被调用10次。
 
-### `matrix_scan_*`ʾ<EFBFBD><EFBFBD>ʵ<EFBFBD><EFBFBD>
+### `matrix_scan_*`示例实现
 
-<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ӱ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ʡ<EFBFBD><EFBFBD><EFBFBD>ˡ<EFBFBD><EFBFBD><EFBFBD>hook<EFBFBD><EFBFBD><EFBFBD><EFBFBD>һ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ܼ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>е<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>֮ǰ<EFBFBD><EFBFBD><EFBFBD><EFBFBD>Ӧ<EFBFBD><EFBFBD><EFBFBD>㹻<EFBFBD>˽<EFBFBD>qmk<EFBFBD><EFBFBD><EFBFBD>ڲ<EFBFBD><EFBFBD>ṹ<EFBFBD><EFBFBD><EFBFBD>Ա<EFBFBD><EFBFBD><EFBFBD>û<EFBFBD><EFBFBD>ʾ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>±<EFBFBD>д<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>Ҫ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>[<EFBFBD><EFBFBD><EFBFBD><EFBFBD>һ<EFBFBD><EFBFBD>issue](https://github.com/qmk/qmk_firmware/issues/new)<EFBFBD><EFBFBD>[<EFBFBD><EFBFBD>Discord<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ǽ<EFBFBD><EFBFBD><EFBFBD>](https://discord.gg/Uq7gcHh).
+这个例子被故意省略了。在hook这样一个对性能及其敏感的区域之前，您应该足够了解qmk的内部结构，以便在没有示例的情况下编写。如果你需要帮助，请[建立一个issue](https://github.com/qmk/qmk_firmware/issues/new)或[在Discord上与我们交流](https://discord.gg/Uq7gcHh).
 
-### `matrix_scan_*` <EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ĵ<EFBFBD>
+### `matrix_scan_*` 函数文档
 
-* <EFBFBD><EFBFBD><EFBFBD><EFBFBD>/<2F>޶<EFBFBD>: `void matrix_scan_kb(void)`
-* <EFBFBD><EFBFBD><EFBFBD><EFBFBD>: `void matrix_scan_user(void)`
+* 键盘/修订: `void matrix_scan_kb(void)`
+* 布局: `void matrix_scan_user(void)`
 
-<EFBFBD>ú<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ÿ<EFBFBD>ξ<EFBFBD><EFBFBD><EFBFBD>ɨ<EFBFBD><EFBFBD>ʱ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ã<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>MCU<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ͬ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>д<EFBFBD><EFBFBD><EFBFBD><EFBFBD>Ҫ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>Ϊ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>кܶ<EFBFBD><EFBFBD>Ρ<EFBFBD>
+该函数在每次矩阵扫描时被调用，这基本与MCU处理能力上限相同。在这里写代码要谨慎，因为它会运行很多次。
 
-<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>Զ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ɨ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ʱ<EFBFBD>õ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>Ҳ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>Զ<EFBFBD><EFBFBD><EFBFBD>״̬<EFBFBD><EFBFBD><EFBFBD><EFBFBD>(<28><><EFBFBD><EFBFBD>LED<45>ƻ<EFBFBD><C6BB><EFBFBD><EFBFBD><EFBFBD>Ļ)<29><><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>û<EFBFBD><C3BB><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>Ҳ<EFBFBD>붨<EFBFBD><EBB6A8><EFBFBD><EFBFBD><EFBFBD>еĹ<D0B5><C4B9>ܡ<EFBFBD>
+你会在自定义矩阵扫描代码时用到这个函数。这也可以用作自定义状态输出(比如LED灯或者屏幕)或者其他即便用户不输入你也想定期运行的功能。
 
 
-# <EFBFBD><EFBFBD><EFBFBD><EFBFBD> <20><><EFBFBD><EFBFBD>/<2F><><EFBFBD><EFBFBD> <20><><EFBFBD><EFBFBD>
+# 键盘 空闲/唤醒 代码
 
-<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>֧<EFBFBD>־Ϳ<EFBFBD><EFBFBD><EFBFBD>ͨ<EFBFBD><EFBFBD>ֹͣһ<EFBFBD><EFBFBD>Ʊ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ﵽ"<22><><EFBFBD><EFBFBD>"<22><>RGB<47>ƺͱ<C6BA><CDB1><EFBFBD><EFBFBD><EFBFBD><EFBFBD>Ǻܺõ<DCBA><C3B5><EFBFBD><EFBFBD>ӡ<EFBFBD><D3A1><EFBFBD><EFBFBD><EFBFBD><EFBFBD>Խ<EFBFBD>Լ<EFBFBD>ܺģ<DCBA>Ҳ<EFBFBD><D2B2><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>̷<EFBFBD>ζ<EFBFBD><CEB6><EFBFBD>ѡ<EFBFBD>
+如果键盘支持就可以通过停止一大票功能来达到"空闲"。RGB灯和背光就是很好的例子。这可以节约能耗，也可能让你键盘风味更佳。
 
-<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>: `suspend_power_down_*`<EFBFBD><EFBFBD>`suspend_wakeup_init_*`, <EFBFBD>ֱ<EFBFBD><EFBFBD><EFBFBD>ϵͳ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>кͻ<EFBFBD><EFBFBD><EFBFBD>ʱ<EFBFBD><EFBFBD><EFBFBD>á<EFBFBD>
+用两个函数控制: `suspend_power_down_*`和`suspend_wakeup_init_*`, 分别在系统板空闲和唤醒时调用。
 
 
-### suspend_power_down_user()<EFBFBD><EFBFBD>suspend_wakeup_init_user()ʾ<EFBFBD><EFBFBD>ʵ<EFBFBD><EFBFBD>
+### suspend_power_down_user()和suspend_wakeup_init_user()示例实现
 
 
 ```c
@@ -283,18 +283,18 @@ void suspend_wakeup_init_user(void) {
 }
 ```
 
-### <EFBFBD><EFBFBD><EFBFBD><EFBFBD> <20><><EFBFBD><EFBFBD>/<2F><><EFBFBD><EFBFBD> <20><><EFBFBD><EFBFBD><EFBFBD>ĵ<EFBFBD>
+### 键盘 挂起/唤醒 函数文档
 
-* <EFBFBD><EFBFBD><EFBFBD><EFBFBD>/<2F>޶<EFBFBD>: `void suspend_power_down_kb(void)` <EFBFBD><EFBFBD>`void suspend_wakeup_init_user(void)`
-* <EFBFBD><EFBFBD><EFBFBD><EFBFBD>: `void suspend_power_down_kb(void)` <EFBFBD><EFBFBD> `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)`
 
-# <EFBFBD><EFBFBD><EFBFBD>ı<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>
+# 层改变代码
 
-ÿ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ı<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>д<EFBFBD><EFBFBD>롣<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ڲ<EFBFBD>ָʾ<EFBFBD><EFBFBD><EFBFBD>Զ<EFBFBD><EFBFBD><EFBFBD><EFBFBD>㴦<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>á<EFBFBD>
+每当层改变这个就运行代码。这对于层指示或自定义层处理很有用。
 
-### `layer_state_set_*` ʾ<EFBFBD><EFBFBD>ʵ<EFBFBD><EFBFBD>
+### `layer_state_set_*` 示例实现
 
-<EFBFBD><EFBFBD><EFBFBD><EFBFBD>ʹ<EFBFBD><EFBFBD><EFBFBD><EFBFBD>Planck<EFBFBD><EFBFBD><EFBFBD><EFBFBD>ʾ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD> [RGB<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>](feature_rgblight.md)ʹ֮<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>Ӧ
+本例使用了Planck键盘示范了如何设置 [RGB背光灯](feature_rgblight.md)使之与层对应
 
 ```c
 uint32_t layer_state_set_user(uint32_t state) {
@@ -318,31 +318,31 @@ uint32_t layer_state_set_user(uint32_t state) {
   return state;
 }
 ```
-### `layer_state_set_*` <EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ĵ<EFBFBD>
+### `layer_state_set_*` 函数文档
 
-* <EFBFBD><EFBFBD><EFBFBD><EFBFBD>/<2F>޶<EFBFBD>: `uint32_t layer_state_set_kb(uint32_t state)`
-* <EFBFBD><EFBFBD><EFBFBD><EFBFBD>: `uint32_t layer_state_set_user(uint32_t state)`
+* 键盘/修订: `uint32_t layer_state_set_kb(uint32_t state)`
+* 布局: `uint32_t layer_state_set_user(uint32_t state)`
 
 
-<EFBFBD><EFBFBD>`״̬`<EFBFBD>ǻ<EFBFBD><EFBFBD><EFBFBD><EFBFBD>bitmask, <20><><EFBFBD><EFBFBD>[<EFBFBD><EFBFBD><EFBFBD>ָ<EFBFBD><EFBFBD><EFBFBD>](keymap.md#<EFBFBD><EFBFBD><EFBFBD>ֵIJ<EFBFBD>״̬)
+该`状态`是活动层的bitmask, 详见[布局概述](keymap.md#布局的层状态)
 
 
-# <EFBFBD><EFBFBD><EFBFBD>籣<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD> (EEPROM)
+# 掉电保存配置 (EEPROM)
 
-<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ó<EFBFBD><EFBFBD>ڵı<EFBFBD><EFBFBD><EFBFBD><EFBFBD>ڼ<EFBFBD><EFBFBD><EFBFBD><EFBFBD>С<EFBFBD><EFBFBD><EFBFBD>Щ<EFBFBD><EFBFBD><EFBFBD>ñ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ص<EFBFBD>EEPROM<EFBFBD><EFBFBD><EFBFBD><EFBFBD>粻<EFBFBD><EFBFBD><EFBFBD><EFBFBD>ʧ<EFBFBD><EFBFBD> <20><><EFBFBD>ÿ<EFBFBD><C3BF><EFBFBD><EFBFBD><EFBFBD>`eeconfig_read_kb`<EFBFBD><EFBFBD>`eeconfig_read_user`<EFBFBD><EFBFBD>ȡ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>`eeconfig_update_kb`<EFBFBD><EFBFBD>`eeconfig_update_user`д<EFBFBD>롣<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ϣ<EFBFBD><EFBFBD><EFBFBD>ܹ<EFBFBD><EFBFBD>л<EFBFBD><EFBFBD>Ĺ<EFBFBD><EFBFBD>ܺ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>(<28><><EFBFBD><EFBFBD><EFBFBD>л<EFBFBD>RGB<47><42>ָʾ<D6B8><CABE><EFBFBD><EFBFBD><EFBFBD>⣬<EFBFBD><E2A3AC><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>`eeconfig_init_kb`<EFBFBD><EFBFBD>`eeconfig_init_user`<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>EEPROMĬ<EFBFBD><EFBFBD>ֵ<EFBFBD><EFBFBD> 
+这会让你的配置长期的保存在键盘中。这些配置保存在你主控的EEPROM里，掉电不会消失。 设置可以用`eeconfig_read_kb`和`eeconfig_read_user`读取，可以用`eeconfig_update_kb`和`eeconfig_update_user`写入。这对于您希望能够切换的功能很有用(比如切换RGB层指示。此外，你可以用`eeconfig_init_kb`和`eeconfig_init_user`来设置EEPROM默认值。 
 
-<EFBFBD><EFBFBD>ӵIJ<EFBFBD><EFBFBD>ֿ<EFBFBD><EFBFBD><EFBFBD><EFBFBD>ǣ<EFBFBD><EFBFBD>кܶ෽<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ͨ<EFBFBD><EFBFBD>EEPROM<EFBFBD>洢<EFBFBD>ͷ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ݣ<EFBFBD><EFBFBD><EFBFBD><EFBFBD>Ҳ<EFBFBD>û<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ַ<EFBFBD><EFBFBD><EFBFBD><EFBFBD>ǡ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ȷ<EFBFBD><EFBFBD><EFBFBD>ġ<EFBFBD><EFBFBD><EFBFBD>ÿ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ֻ<EFBFBD><EFBFBD>һ<EFBFBD><EFBFBD>˫<EFBFBD><EFBFBD>(<28><><EFBFBD>ֽ<EFBFBD>)<29>ռ䡣
+最复杂的部分可能是，有很多方法可以通过EEPROM存储和访问数据，并且并没有用哪种方法是“政治正确”的。你每个功能只有一个双字(四字节)空间。
 
-<EFBFBD><EFBFBD>סEEPROM<EFBFBD><EFBFBD><EFBFBD><EFBFBD>д<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ġ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>д<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ܸߣ<EFBFBD><EFBFBD><EFBFBD><EFBFBD>Dz<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ֻ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>д<EFBFBD><EFBFBD>EEPROM<EFBFBD>С<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>д<EFBFBD><EFBFBD>Ƶ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>MCU<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>̡<EFBFBD>
+记住EEPROM是有写入寿命的。尽管写入寿命很高，但是并不是只有设置写道EEPROM中。如果你写入频繁，你的MCU寿命将会变短。
 
-* <EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ӣ<EFBFBD><EFBFBD><EFBFBD>ô<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ϣ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ʹ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ԣ<EFBFBD><EFBFBD><EFBFBD>Ϊ<EFBFBD><EFBFBD><EFBFBD>൱<EFBFBD><EFBFBD><EFBFBD>ӡ<EFBFBD>
+* 如果您不理解这个例子，那么您可能希望避免使用这个特性，因为它相当复杂。
 
-### ʾ<EFBFBD><EFBFBD>ʵ<EFBFBD><EFBFBD>
+### 示例实现
 
-<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ã<EFBFBD><EFBFBD><EFBFBD><EFBFBD>Ҷ<EFBFBD>д<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ʹ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>û<EFBFBD><EFBFBD><EFBFBD><EFBFBD>֡<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>һ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ӵĺ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>кܶ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>Ҫ<EFBFBD><EFBFBD><EFBFBD><EFBFBD>ʵ<EFBFBD><EFBFBD><EFBFBD>ϣ<EFBFBD><EFBFBD><EFBFBD>ʹ<EFBFBD><EFBFBD><EFBFBD>˺ܶ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>
+本例讲解了如何添加设置，并且读写。本里使用了用户布局。这是一个复杂的函数，有很多事情要做。实际上，它使用了很多上述函数来工作！
 
 
-<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>keymap.c<EFBFBD>ļ<EFBFBD><EFBFBD>У<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>´<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>:
+在你的keymap.c文件中，将以下代码添加至顶部:
 ```c
 typedef union {
   uint32_t raw;
@@ -354,19 +354,19 @@ typedef union {
 user_config_t user_config;
 ```
 
-<EFBFBD><EFBFBD><EFBFBD>ϴ<EFBFBD><EFBFBD>뽨<EFBFBD><EFBFBD><EFBFBD><EFBFBD>һ<EFBFBD><EFBFBD><EFBFBD>ṹ<EFBFBD>壬<EFBFBD>ýṹ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>Դ洢<EFBFBD><EFBFBD><EFBFBD>ò<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>д<EFBFBD><EFBFBD>EEPROM<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>㽫<EFBFBD><EFBFBD><EFBFBD>趨<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>Ϊ<EFBFBD>ڽṹ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>Ȼ<EFBFBD><EFBFBD><EFBFBD>塣Ҫ<EFBFBD><EFBFBD>ס`bool` (<28><><EFBFBD><EFBFBD>)ֵʹ<D6B5><CAB9>1λ, `uint8_t`ʹ<EFBFBD><EFBFBD>8λ, `uint16_t`ʹ<EFBFBD><EFBFBD>16λ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>Ի<EFBFBD><EFBFBD>ϴ<EFBFBD><EFBFBD><EFBFBD>ʹ<EFBFBD>ã<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>˳<EFBFBD><EFBFBD><EFBFBD>Ǵ<EFBFBD><EFBFBD><EFBFBD><EFBFBD>ܻ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>鷳<EFBFBD><EFBFBD><EFBFBD><EFBFBD>Ϊ<EFBFBD>ǻ<EFBFBD><EFBFBD>ı<EFBFBD>д<EFBFBD><EFBFBD>д<EFBFBD><EFBFBD><EFBFBD><EFBFBD>ֵ<EFBFBD><EFBFBD> 
+以上代码建立了一个结构体，该结构体可以存储设置并可用于写入EEPROM。如此这般将无需定义变量，因为在结构体中已然定义。要记住`bool` (布尔)值使用1位, `uint8_t`使用8位, `uint16_t`使用16位。你可以混合搭配使用，但是顺序记错可能会招致麻烦，因为那会改变写入写出的值。 
 
- `layer_state_set_*`<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ʹ<EFBFBD><EFBFBD><EFBFBD><EFBFBD>`rgb_layer_change`<EFBFBD><EFBFBD>ʹ<EFBFBD><EFBFBD><EFBFBD><EFBFBD>`keyboard_post_init_user`<EFBFBD><EFBFBD>`process_record_user`<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>һ<EFBFBD>С<EFBFBD>
+ `layer_state_set_*`函数中使用了`rgb_layer_change`，使用了`keyboard_post_init_user`和`process_record_user`来配置一切。
 
-<EFBFBD><EFBFBD><EFBFBD><EFBFBD>Ҫʹ<EFBFBD><EFBFBD>`keyboard_post_init_user<EFBFBD><EFBFBD><EFBFBD><EFBFBD>Ҫ<EFBFBD><EFBFBD><EFBFBD><EFBFBD>`eeconfig_read_user()`<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ոմ<EFBFBD><EFBFBD><EFBFBD><EFBFBD>Ľṹ<EFBFBD>塣Ȼ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ʹ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ṹ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>IJ<EFBFBD><EFBFBD><EFBFBD><EFBFBD>еĹ<EFBFBD><EFBFBD>ܡ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD> 
+首先要使用`keyboard_post_init_user，你要加入`eeconfig_read_user()`来填充你刚刚创建的结构体。然后您可以立即使用这个结构来控制您的布局中的功能。就像这样： 
 ```c
 void keyboard_post_init_user(void) {
-  // <EFBFBD><EFBFBD><EFBFBD>ò<EFBFBD><EFBFBD>ּ<EFBFBD><EFBFBD><EFBFBD><EFBFBD>ľ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ʼ<EFBFBD><EFBFBD>
+  // 调用布局级别的矩阵初始化
 
-  // <EFBFBD><EFBFBD>EEPROM<EFBFBD><EFBFBD><EFBFBD>û<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>
+  // 从EEPROM读用户配置
   user_config.raw = eeconfig_read_user();
 
-  // <EFBFBD><EFBFBD>ʹ<EFBFBD>ܣ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>Ĭ<EFBFBD>ϲ<EFBFBD>
+  // 如使能，设置默认层
   if (user_config.rgb_layer_change) {
     rgblight_enable_noeeprom();
     rgblight_sethsv_noeeprom_cyan(); 
@@ -374,7 +374,7 @@ void keyboard_post_init_user(void) {
   }
 }
 ```
-<EFBFBD><EFBFBD><EFBFBD>Ϻ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ڶ<EFBFBD>EEPROM<EFBFBD><EFBFBD><EFBFBD>ú<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ʹ<EFBFBD>ø<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>Ĭ<EFBFBD>ϲ<EFBFBD>RGB<EFBFBD><EFBFBD>ɫ<EFBFBD><EFBFBD>"raw"<22><>ֵ<EFBFBD>Ǵ<EFBFBD><C7B4><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>"union"<22><><EFBFBD><EFBFBD><EFBFBD>Ľṹ<C4BD><E1B9B9><EFBFBD><EFBFBD>ת<EFBFBD><D7AA><EFBFBD><EFBFBD><EFBFBD>ġ<EFBFBD> 
+以上函数会在读EEPROM配置后立即使用该设置来设置默认层RGB颜色。"raw"的值是从你上面基于"union"创建的结构体中转换来的。 
 
 ```c
 uint32_t layer_state_set_user(uint32_t state) {
@@ -391,86 +391,86 @@ uint32_t layer_state_set_user(uint32_t state) {
     case _ADJUST:
         if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_white(); rgblight_mode_noeeprom(1); }
         break;
-    default: //  <EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>Ĭ<EFBFBD>ϲ<EFBFBD>
+    default: //  针对其他层或默认层
         if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_cyan(); rgblight_mode_noeeprom(1); }
         break;
     }
   return state;
 }
 ```
-<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ֵʹ<EFBFBD><EFBFBD>ʱ<EFBFBD><EFBFBD><EFBFBD>ı<EFBFBD>RGB<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ơ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ֵ, Ϊ`process_record_user`<EFBFBD><EFBFBD><EFBFBD><EFBFBD>һ<EFBFBD><EFBFBD><EFBFBD>¼<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>`RGB_LYR`<60><><EFBFBD><EFBFBD><EFBFBD><EFBFBD>Ҫȷ<D2AA><C8B7><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ʹ<EFBFBD><CAB9><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>RGB<47><42><EFBFBD>룬ʹ<EBA3AC><CAB9><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ʾ<EFBFBD><CABE><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>رգ<D8B1><D5A3>뽫<EFBFBD><EBBDAB><EFBFBD><EFBFBD><EFBFBD><EFBFBD>Ϊ<EFBFBD><CEAA>
+这样仅在值使能时会改变RGB背光灯。现在配置这个值, 为`process_record_user`创建一个新键码叫做`RGB_LYR`。我们要确保，如果使用正常的RGB代码，使用上面的示例将其关闭，请将其设置为：
 ```c
 
 bool process_record_user(uint16_t keycode, keyrecord_t *record) {
   switch (keycode) {
     case FOO:
       if (record->event.pressed) {
-        // <EFBFBD><EFBFBD><EFBFBD><EFBFBD>ʱ<EFBFBD><EFBFBD><EFBFBD><EFBFBD>ʲô
+        // 按下时做点什么
       } else {
-        // <EFBFBD>ͷ<EFBFBD>ʱ<EFBFBD><EFBFBD><EFBFBD><EFBFBD>ʲô
+        // 释放时做点什么
       }
-      return false; // <EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>˼<EFBFBD><EFBFBD>Ľ<EFBFBD>һ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>
+      return false; // 跳过此键的进一步处理
     case KC_ENTER:
-        // <EFBFBD>ڰ<EFBFBD><EFBFBD>»س<EFBFBD>ʱ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>
+        // 在按下回车时播放音符
         if (record->event.pressed) {
             PLAY_NOTE_ARRAY(tone_qwerty);
         }
-        return true; // <EFBFBD><EFBFBD>QMK<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>س<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>/<2F>ͷ<EFBFBD><CDB7>¼<EFBFBD>
-    case RGB_LYR:  // <EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>underglow<EFBFBD><EFBFBD>Ϊ<EFBFBD><EFBFBD>ָʾ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ʹ<EFBFBD>á<EFBFBD>
+        return true; // 让QMK产生回车按下/释放事件
+    case RGB_LYR:  // 本句让underglow作为层指示，或正常使用。
         if (record->event.pressed) { 
-            user_config.rgb_layer_change ^= 1; // <EFBFBD>л<EFBFBD>״̬
-            eeconfig_update_user(user_config.raw); // <EFBFBD><EFBFBD>EEPROMд<EFBFBD><EFBFBD><EFBFBD><EFBFBD>״̬
-            if (user_config.rgb_layer_change) { // <EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>״̬<EFBFBD><EFBFBD>ʹ<EFBFBD><EFBFBD>
-                layer_state_set(layer_state);   // <EFBFBD><EFBFBD>ô<EFBFBD><EFBFBD><EFBFBD≯<EFBFBD><EFBFBD>²<EFBFBD><EFBFBD><EFBFBD>ɫ
+            user_config.rgb_layer_change ^= 1; // 切换状态
+            eeconfig_update_user(user_config.raw); // 向EEPROM写入新状态
+            if (user_config.rgb_layer_change) { // 如果层状态被使能
+                layer_state_set(layer_state);   // 那么立刻更新层颜色
             }
         }
         return false; break;
-    case RGB_MODE_FORWARD ... RGB_MODE_GRADIENT: // <EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>е<EFBFBD>RGB<EFBFBD><EFBFBD><EFBFBD><EFBFBD> (see quantum_keycodes.h, L400 <EFBFBD><EFBFBD><EFBFBD>Բο<EFBFBD>)
-        if (record->event.pressed) { //<EFBFBD><EFBFBD><EFBFBD><EFBFBD>ʧ<EFBFBD>ܲ<EFBFBD>ָʾ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ı<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>Ҫ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>
-            if (user_config.rgb_layer_change) {        // <EFBFBD><EFBFBD><EFBFBD><EFBFBD>ʹ<EFBFBD><EFBFBD>ʱ
-                user_config.rgb_layer_change = false;  // ʧ<EFBFBD>ܣ<EFBFBD>Ȼ<EFBFBD><EFBFBD> 
-                eeconfig_update_user(user_config.raw); // <EFBFBD><EFBFBD>EEPROMд<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>
+    case RGB_MODE_FORWARD ... RGB_MODE_GRADIENT: // 对于所有的RGB代码 (see quantum_keycodes.h, L400 可以参考)
+        if (record->event.pressed) { //本句失能层指示，假设你改变了这个…你要把它禁用
+            if (user_config.rgb_layer_change) {        // 仅当使能时
+                user_config.rgb_layer_change = false;  // 失能，然后 
+                eeconfig_update_user(user_config.raw); // 向EEPROM写入设置
             }
         }
         return true; break;
     default:
-      return true; // <EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>
+      return true; // 按其他键正常
   }
 }
 ```
-<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>Ҫ<EFBFBD><EFBFBD><EFBFBD><EFBFBD>`eeconfig_init_user`<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>Ե<EFBFBD>EEPROM<EFBFBD><EFBFBD><EFBFBD><EFBFBD>ʱ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ָ<EFBFBD><EFBFBD>Ĭ<EFBFBD><EFBFBD>ֵ, <20><><EFBFBD><EFBFBD><EFBFBD>Զ<EFBFBD><D4B6><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ǿ<EFBFBD><C7BF><EFBFBD><EFBFBD><EFBFBD><EFBFBD>EEPROM<4F><4D><EFBFBD><EFBFBD><EFBFBD><EFBFBD>`EEP_RST`<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>[Bootmagic](feature_bootmagic.md)<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>磬<EFBFBD><EFBFBD><EFBFBD><EFBFBD>Ҫ<EFBFBD><EFBFBD>Ĭ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>RGB<EFBFBD><EFBFBD>ָʾ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>Ĭ<EFBFBD><EFBFBD>ֵ
+最后你要加入`eeconfig_init_user`函数，所以当EEPROM重置时，可以指定默认值, 甚至自定义操作。想强制重置EEPROM，请用`EEP_RST`键码或[Bootmagic](feature_bootmagic.md)函数。比如，如果要在默认情况下设置RGB层指示，并保存默认值
 
 ```c
-void eeconfig_init_user(void) {  // EEPROM<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>
+void eeconfig_init_user(void) {  // EEPROM正被重置
   user_config.raw = 0;
-  user_config.rgb_layer_change = true; // <EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ҪĬ<EFBFBD><EFBFBD>ʹ<EFBFBD><EFBFBD>
-  eeconfig_update_user(user_config.raw); // <EFBFBD><EFBFBD>EEPROMд<EFBFBD><EFBFBD>Ĭ<EFBFBD><EFBFBD>ֵ
+  user_config.rgb_layer_change = true; // 我们想要默认使能
+  eeconfig_update_user(user_config.raw); // 向EEPROM写入默认值
 
-  // use the non noeeprom versions, <EFBFBD><EFBFBD>Ҫ<EFBFBD><EFBFBD>EEPROMд<EFBFBD><EFBFBD><EFBFBD><EFBFBD>Щֵ
-  rgblight_enable(); // Ĭ<EFBFBD><EFBFBD>ʹ<EFBFBD><EFBFBD>RGB
-  rgblight_sethsv_cyan();  // Ĭ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ɫ
-  rgblight_mode(1); // Ĭ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ó<EFBFBD><EFBFBD><EFBFBD>
+  // use the non noeeprom versions, 还要向EEPROM写入这些值
+  rgblight_enable(); // 默认使能RGB
+  rgblight_sethsv_cyan();  // 默认设置青色
+  rgblight_mode(1); // 默认设置长亮
 }
 ```
 
-Ȼ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ˡ<EFBFBD>RGB<EFBFBD><EFBFBD>ָʾ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ʱ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>û<EFBFBD>һֱ<EFBFBD><EFBFBD><EFBFBD>棬<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>¼<EFBFBD><EFBFBD>̡<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ʹ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>RGB<EFBFBD><EFBFBD><EFBFBD>룬<EFBFBD><EFBFBD>ָʾ<EFBFBD><EFBFBD>ʧ<EFBFBD>ܣ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ˡ<EFBFBD> 
+然后就完事了。RGB层指示会在你想让它工作时工作。这个设置会一直保存，即便你拔下键盘。如果你使用其他RGB代码，层指示将失能，现在它可以做你所想了。 
 
-### 'EECONFIG' <EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ĵ<EFBFBD>
+### 'EECONFIG' 函数文档
 
-* <EFBFBD><EFBFBD><EFBFBD><EFBFBD>/<2F>޶<EFBFBD>: `void eeconfig_init_kb(void)`, `uint32_t eeconfig_read_kb(void)`<EFBFBD><EFBFBD>`void eeconfig_update_kb(uint32_t val)`
-* <EFBFBD><EFBFBD><EFBFBD><EFBFBD>: `void eeconfig_init_user(void)`, `uint32_t eeconfig_read_user(void)`<EFBFBD><EFBFBD>`void eeconfig_update_user(uint32_t val)`
+* 键盘/修订: `void eeconfig_init_kb(void)`, `uint32_t eeconfig_read_kb(void)`和`void eeconfig_update_kb(uint32_t val)`
+* 布局: `void eeconfig_init_user(void)`, `uint32_t eeconfig_read_user(void)`和`void eeconfig_update_user(uint32_t val)`
 
-`val` <EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>д<EFBFBD><EFBFBD>EEPROM<EFBFBD><EFBFBD>ֵ<EFBFBD><EFBFBD>`eeconfig_read_*`<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>EEPROM<EFBFBD><EFBFBD><EFBFBD><EFBFBD>һ<EFBFBD><EFBFBD>32λ(˫<><CBAB>)<29><>ֵ<EFBFBD><D6B5>
+`val` 是你想写入EEPROM的值，`eeconfig_read_*`函数会从EEPROM返回一个32位(双字)的值。
 
-# <EFBFBD>Զ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>-<2D><><EFBFBD><EFBFBD><EFBFBD>ٽ<EFBFBD>ֵ(TAPPING_TERM)
-Ĭ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>,<2C><><EFBFBD><EFBFBD>-<2D><><EFBFBD><EFBFBD><EFBFBD>ٽ<EFBFBD>ֵ<EFBFBD><D6B5>ȫ<EFBFBD><C8AB>ͳһ<CDB3>ģ<EFBFBD><C4A3><EFBFBD><EFBFBD>Ҳ<EFBFBD><D2B2><EFBFBD>ͨ<EFBFBD><CDA8><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>á<EFBFBD><C3A1><EFBFBD><EFBFBD>ڴ<EFBFBD><DAB4><EFBFBD><EFBFBD><EFBFBD><EFBFBD>û<EFBFBD><C3BB><EFBFBD>˵<EFBFBD><CBB5><EFBFBD>ܺá<DCBA><C3A1><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>Щ<EFBFBD><D0A9><EFBFBD><EFBFBD><EFBFBD>£<EFBFBD><C2A3><EFBFBD><EFBFBD><EFBFBD>`LT`<60><><EFBFBD><EFBFBD>˵<EFBFBD><CBB5><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ʱ<EFBFBD><CAB1>˫<EFBFBD><CBAB><EFBFBD>ܼ<EFBFBD><DCBC><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>󣬿<EFBFBD><F3A3ACBF><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>Ϊ<EFBFBD><CEAA>Щ<EFBFBD><D0A9><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ļ<EFBFBD><C4BC><EFBFBD><EFBFBD><EFBFBD><EFBFBD>װ<EFBFBD>ס<EFBFBD><D7A1>Ϊ<EFBFBD>˲<EFBFBD><CBB2><EFBFBD>ÿ<EFBFBD><C3BF><EFBFBD><EFBFBD><EFBFBD>Զ<EFBFBD><D4B6><EFBFBD><EFBFBD><EFBFBD><EFBFBD>룬<EFBFBD><EBA3AC><EFBFBD><EFBFBD><EFBFBD>ܿ<EFBFBD><DCBF><EFBFBD>Ϊÿ<CEAA><C3BF><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>`TAPPING_TERM`<EFBFBD><EFBFBD>
+# 自定义击键-长按临界值(TAPPING_TERM)
+默认情况下,击键-长按临界值是全球统一的，并且不能通过键进行配置。对于大多数用户来说这很好。但是在有些情况下，对于`LT`键来说按键延时对双功能键的提升更大，可能是因为有些键比其他的键更容易按住。为了不给每个都自定义键码，本功能可以为每个键定义`TAPPING_TERM`。
 
-<EFBFBD><EFBFBD>ʹ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ܵĻ<EFBFBD>, Ҫ<><D2AA><EFBFBD><EFBFBD>`config.h`<EFBFBD><EFBFBD><EFBFBD><EFBFBD>`#define TAPPING_TERM_PER_KEY`<EFBFBD><EFBFBD>
+想使能这个功能的话, 要先在`config.h`加上`#define TAPPING_TERM_PER_KEY`。
 
 
-## `get_tapping_term`ʾ<EFBFBD><EFBFBD>ʵ<EFBFBD><EFBFBD>
+## `get_tapping_term`示例实现
 
-<EFBFBD><EFBFBD>Ҫ<EFBFBD>޸Ļ<EFBFBD><EFBFBD>ڼ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>`TAPPING TERM`,<EFBFBD><EFBFBD>Ҫ<EFBFBD><EFBFBD>`keymap.c`<EFBFBD>ļ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>´<EFBFBD><EFBFBD><EFBFBD>: 
+想要修改基于键码的`TAPPING TERM`,你要向`keymap.c`文件添加如下代码: 
 
 ```c
 uint16_t get_tapping_term(uint16_t keycode) {
@@ -485,6 +485,6 @@ uint16_t get_tapping_term(uint16_t keycode) {
 }
 ```
 
-### `get_tapping_term` <EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ĵ<EFBFBD>
+### `get_tapping_term` 函数文档
 
-<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ƪ<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>,<2C><><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>Ҫquantum<75><6D><EFBFBD>߼<EFBFBD><DFBC>̼<EFBFBD><CCBC><EFBFBD><EFBFBD>ĺ<EFBFBD><C4BA><EFBFBD><EFBFBD><EFBFBD>ֻҪ<D6BB>û<EFBFBD><C3BB><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>ɡ<EFBFBD>
+不像这篇的其他功能,这个不需要quantum或者键盘级别的函数，只要用户级函数即可。

docs/zh-cn/getting_started_github.md

@@ -16,17 +16,23 @@ Github can be a little tricky to those that aren't familiar with it - this guide
 
 ![HTTPS链接](http://i.imgur.com/eGO0ohO.jpg)
 
-然后，在命令行输入`git clone `，然后粘贴你的链接:
+然后，在命令行输入`git clone --recurse-submodules `，然后粘贴你的链接:
 
 ```
-user@computer:~$ git clone https://github.com/whoeveryouare/qmk_firmware.git
+user@computer:~$ git clone --recurse-submodules https://github.com/whoeveryouare/qmk_firmware.git
 Cloning into 'qmk_firmware'...
-remote: Counting objects: 46625, done.
-remote: Compressing objects: 100% (2/2), done.
-remote: Total 46625 (delta 0), reused 0 (delta 0), pack-reused 46623
-Receiving objects: 100% (46625/46625), 84.47 MiB | 3.14 MiB/s, done.
-Resolving deltas: 100% (29362/29362), done.
-Checking out files: 100% (2799/2799), done.
+remote: Enumerating objects: 9, done.
+remote: Counting objects: 100% (9/9), done.
+remote: Compressing objects: 100% (5/5), done.
+remote: Total 183883 (delta 5), reused 4 (delta 4), pack-reused 183874
+Receiving objects: 100% (183883/183883), 132.90 MiB | 9.57 MiB/s, done.
+Resolving deltas: 100% (119972/119972), done.
+...
+Submodule path 'lib/chibios': checked out '587968d6cbc2b0e1c7147540872f2a67e59ca18b'
+Submodule path 'lib/chibios-contrib': checked out 'ede48346eee4b8d6847c19bc01420bee76a5e486'
+Submodule path 'lib/googletest': checked out 'ec44c6c1675c25b9827aacd08c02433cccde7780'
+Submodule path 'lib/lufa': checked out 'ce10f7642b0459e409839b23cc91498945119b4d'
+Submodule path 'lib/ugfx': checked out '3e97b74e03c93631cdd3ddb2ce43b963fdce19b2'
 ```
 
 现在你本地计算机有QMK的分叉了,你可以添加你的布局了, 为你的键盘编译并刷新固件吧。如果你觉得你的修改很不错, 你可以添加,提交,然后想你的分叉推出（pull）你的改变，像这样:

docs/zh-cn/getting_started_introduction.md

@@ -4,7 +4,7 @@
 
 ## 基本QMK结构
 
-QMK是[Jun Wako](https://github.com/tmk)的[tmk_keyboard](https://github.com/tmk/tmk_keyboard)工程的一个分叉。经过更改的TMK原始代码放在`tmk` 文件夹中。 QMK增加的新东西可以在 `quantum` 文件夹中找到。 键盘项目可以在 `handwired`（手动飞线） 和 `keyboard`（PCB键盘）这两个文件夹找到。
+QMK是[Jun Wako](https://github.com/tmk)的[tmk_keyboard](https://github.com/tmk/tmk_keyboard)工程的一个分叉。经过更改的TMK原始代码放在`tmk_core` 文件夹中。 QMK增加的新东西可以在 `quantum` 文件夹中找到。 键盘项目可以在 `handwired`（手动飞线） 和 `keyboard`（PCB键盘）这两个文件夹找到。
 
 ### 用户空间结构
 

doxygen-todo

@@ -6,7 +6,6 @@ tmk_core/protocol/lufa
 tmk_core/protocol/midi
 tmk_core/protocol/midi/bytequeue
 tmk_core/protocol/midi/Config
-tmk_core/protocol/pjrc
 tmk_core/protocol/usb_hid
 tmk_core/protocol/vusb
 tmk_core/tool

drivers/arm/i2c_master.c

@@ -24,14 +24,11 @@
  * STM32_I2C_USE_I2C1 is TRUE in the mcuconf.h file. Pins B6 and B7 are used
  * but using any other I2C pins should be trivial.
  */
-
-#include "i2c_master.h"
 #include "quantum.h"
+#include "i2c_master.h"
 #include <string.h>
 #include <hal.h>
 
-static uint8_t i2c_address;
-
 static const I2CConfig i2cconfig = {
 #ifdef USE_I2CV1
     I2C1_OPMODE,
@@ -72,27 +69,49 @@ __attribute__((weak)) void i2c_init(void) {
 }
 
 i2c_status_t i2c_start(uint8_t address) {
-    i2c_address = address;
+#if I2C_USE_MUTUAL_EXCLUSION
+    i2cAcquireBus(&I2C_DRIVER);
+#endif
+
     i2cStart(&I2C_DRIVER, &i2cconfig);
     return I2C_STATUS_SUCCESS;
 }
 
 i2c_status_t i2c_transmit(uint8_t address, const uint8_t* data, uint16_t length, uint16_t timeout) {
-    i2c_address = address;
+#if I2C_USE_MUTUAL_EXCLUSION
+    i2cAcquireBus(&I2C_DRIVER);
+#endif
+
     i2cStart(&I2C_DRIVER, &i2cconfig);
-    msg_t status = i2cMasterTransmitTimeout(&I2C_DRIVER, (i2c_address >> 1), data, length, 0, 0, MS2ST(timeout));
+    msg_t status = i2cMasterTransmitTimeout(&I2C_DRIVER, (address >> 1), data, length, 0, 0, MS2ST(timeout));
+
+#if I2C_USE_MUTUAL_EXCLUSION
+    i2cReleaseBus(&I2C_DRIVER);
+#endif
+
     return chibios_to_qmk(&status);
 }
 
 i2c_status_t i2c_receive(uint8_t address, uint8_t* data, uint16_t length, uint16_t timeout) {
-    i2c_address = address;
+#if I2C_USE_MUTUAL_EXCLUSION
+    i2cAcquireBus(&I2C_DRIVER);
+#endif
+
     i2cStart(&I2C_DRIVER, &i2cconfig);
-    msg_t status = i2cMasterReceiveTimeout(&I2C_DRIVER, (i2c_address >> 1), data, length, MS2ST(timeout));
+    msg_t status = i2cMasterReceiveTimeout(&I2C_DRIVER, (address >> 1), data, length, MS2ST(timeout));
+
+#if I2C_USE_MUTUAL_EXCLUSION
+    i2cReleaseBus(&I2C_DRIVER);
+#endif
+
     return chibios_to_qmk(&status);
 }
 
 i2c_status_t i2c_writeReg(uint8_t devaddr, uint8_t regaddr, const uint8_t* data, uint16_t length, uint16_t timeout) {
-    i2c_address = devaddr;
+#if I2C_USE_MUTUAL_EXCLUSION
+    i2cAcquireBus(&I2C_DRIVER);
+#endif
+
     i2cStart(&I2C_DRIVER, &i2cconfig);
 
     uint8_t complete_packet[length + 1];
@@ -101,15 +120,34 @@ i2c_status_t i2c_writeReg(uint8_t devaddr, uint8_t regaddr, const uint8_t* data,
     }
     complete_packet[0] = regaddr;
 
-    msg_t status = i2cMasterTransmitTimeout(&I2C_DRIVER, (i2c_address >> 1), complete_packet, length + 1, 0, 0, MS2ST(timeout));
+    msg_t status = i2cMasterTransmitTimeout(&I2C_DRIVER, (devaddr >> 1), complete_packet, length + 1, 0, 0, MS2ST(timeout));
+
+#if I2C_USE_MUTUAL_EXCLUSION
+    i2cReleaseBus(&I2C_DRIVER);
+#endif
+
     return chibios_to_qmk(&status);
 }
 
 i2c_status_t i2c_readReg(uint8_t devaddr, uint8_t regaddr, uint8_t* data, uint16_t length, uint16_t timeout) {
-    i2c_address = devaddr;
+#if I2C_USE_MUTUAL_EXCLUSION
+    i2cAcquireBus(&I2C_DRIVER);
+#endif
+
     i2cStart(&I2C_DRIVER, &i2cconfig);
-    msg_t status = i2cMasterTransmitTimeout(&I2C_DRIVER, (i2c_address >> 1), &regaddr, 1, data, length, MS2ST(timeout));
+    msg_t status = i2cMasterTransmitTimeout(&I2C_DRIVER, (devaddr >> 1), &regaddr, 1, data, length, MS2ST(timeout));
+
+#if I2C_USE_MUTUAL_EXCLUSION
+    i2cReleaseBus(&I2C_DRIVER);
+#endif
+
     return chibios_to_qmk(&status);
 }
 
-void i2c_stop(void) { i2cStop(&I2C_DRIVER); }
+void i2c_stop(void) {
+    i2cStop(&I2C_DRIVER);
+
+#if I2C_USE_MUTUAL_EXCLUSION
+    i2cReleaseBus(&I2C_DRIVER);
+#endif
+}

drivers/arm/i2c_master.h

@@ -27,10 +27,6 @@
 #include "ch.h"
 #include <hal.h>
 
-#if defined(STM32F1XX) || defined(STM32F1xx) || defined(STM32F2xx) || defined(STM32F4xx) || defined(STM32F4XX) || defined(STM32L0xx) || defined(STM32L1xx)
-#    define USE_I2CV1
-#endif
-
 #ifdef I2C1_BANK
 #    define I2C1_SCL_BANK I2C1_BANK
 #    define I2C1_SDA_BANK I2C1_BANK
@@ -51,20 +47,6 @@
 #    define I2C1_SDA 7
 #endif
 
-#if defined(STM32F1XX) || defined(STM32F1xx)
-#    define USE_GPIOV1
-#endif
-
-#ifndef USE_GPIOV1
-// The default PAL alternate modes are used to signal that the pins are used for I2C
-#    ifndef I2C1_SCL_PAL_MODE
-#        define I2C1_SCL_PAL_MODE 4
-#    endif
-#    ifndef I2C1_SDA_PAL_MODE
-#        define I2C1_SDA_PAL_MODE 4
-#    endif
-#endif
-
 #ifdef USE_I2CV1
 #    ifndef I2C1_OPMODE
 #        define I2C1_OPMODE OPMODE_I2C
@@ -99,6 +81,16 @@
 #    define I2C_DRIVER I2CD1
 #endif
 
+#ifndef USE_GPIOV1
+// The default PAL alternate modes are used to signal that the pins are used for I2C
+#    ifndef I2C1_SCL_PAL_MODE
+#        define I2C1_SCL_PAL_MODE 4
+#    endif
+#    ifndef I2C1_SDA_PAL_MODE
+#        define I2C1_SDA_PAL_MODE 4
+#    endif
+#endif
+
 typedef int16_t i2c_status_t;
 
 #define I2C_STATUS_SUCCESS (0)
@@ -109,7 +101,6 @@ void         i2c_init(void);
 i2c_status_t i2c_start(uint8_t address);
 i2c_status_t i2c_transmit(uint8_t address, const uint8_t* data, uint16_t length, uint16_t timeout);
 i2c_status_t i2c_receive(uint8_t address, uint8_t* data, uint16_t length, uint16_t timeout);
-i2c_status_t i2c_transmit_receive(uint8_t address, uint8_t* tx_body, uint16_t tx_length, uint8_t* rx_body, uint16_t rx_length);
 i2c_status_t i2c_writeReg(uint8_t devaddr, uint8_t regaddr, const uint8_t* data, uint16_t length, uint16_t timeout);
 i2c_status_t i2c_readReg(uint8_t devaddr, uint8_t regaddr, uint8_t* data, uint16_t length, uint16_t timeout);
 void         i2c_stop(void);

drivers/arm/ws2812_spi.c

@@ -1 +1,90 @@
-#error("NOT SUPPORTED")
+#include "quantum.h"
+#include "ws2812.h"
+
+/* Adapted from https://github.com/gamazeps/ws2812b-chibios-SPIDMA/ */
+
+#ifdef RGBW
+#    error "RGBW not supported"
+#endif
+
+// Define the spi your LEDs are plugged to here
+#ifndef WS2812_SPI
+#    define WS2812_SPI SPID1
+#endif
+
+#ifndef WS2812_SPI_MOSI_PAL_MODE
+#    define WS2812_SPI_MOSI_PAL_MODE 5
+#endif
+
+#define BYTES_FOR_LED_BYTE 4
+#define NB_COLORS 3
+#define BYTES_FOR_LED (BYTES_FOR_LED_BYTE * NB_COLORS)
+#define DATA_SIZE (BYTES_FOR_LED * RGBLED_NUM)
+#define RESET_SIZE 200
+#define PREAMBLE_SIZE 4
+
+static uint8_t txbuf[PREAMBLE_SIZE + DATA_SIZE + RESET_SIZE] = {0};
+
+/*
+ * As the trick here is to use the SPI to send a huge pattern of 0 and 1 to
+ * the ws2812b protocol, we use this helper function to translate bytes into
+ * 0s and 1s for the LED (with the appropriate timing).
+ */
+static uint8_t get_protocol_eq(uint8_t data, int pos) {
+    uint8_t eq = 0;
+    if (data & (1 << (2 * (3 - pos))))
+        eq = 0b1110;
+    else
+        eq = 0b1000;
+    if (data & (2 << (2 * (3 - pos))))
+        eq += 0b11100000;
+    else
+        eq += 0b10000000;
+    return eq;
+}
+
+static void set_led_color_rgb(LED_TYPE color, int pos) {
+    uint8_t* tx_start = &txbuf[PREAMBLE_SIZE];
+
+    for (int j = 0; j < 4; j++) tx_start[BYTES_FOR_LED * pos + j] = get_protocol_eq(color.g, j);
+    for (int j = 0; j < 4; j++) tx_start[BYTES_FOR_LED * pos + BYTES_FOR_LED_BYTE + j] = get_protocol_eq(color.r, j);
+    for (int j = 0; j < 4; j++) tx_start[BYTES_FOR_LED * pos + BYTES_FOR_LED_BYTE * 2 + j] = get_protocol_eq(color.b, j);
+}
+
+void ws2812_init(void) {
+#if defined(USE_GPIOV1)
+    palSetLineMode(RGB_DI_PIN, PAL_MODE_STM32_ALTERNATE_PUSHPULL);
+#else
+    palSetLineMode(RGB_DI_PIN, PAL_MODE_ALTERNATE(WS2812_SPI_MOSI_PAL_MODE) | PAL_STM32_OTYPE_PUSHPULL);
+#endif
+
+    // TODO: more dynamic baudrate
+    static const SPIConfig spicfg = {
+        NULL, PAL_PORT(RGB_DI_PIN), PAL_PAD(RGB_DI_PIN),
+        SPI_CR1_BR_1 | SPI_CR1_BR_0  // baudrate : fpclk / 8 => 1tick is 0.32us (2.25 MHz)
+    };
+
+    spiAcquireBus(&WS2812_SPI);     /* Acquire ownership of the bus.    */
+    spiStart(&WS2812_SPI, &spicfg); /* Setup transfer parameters.       */
+    spiSelect(&WS2812_SPI);         /* Slave Select assertion.          */
+}
+
+void ws2812_setleds(LED_TYPE* ledarray, uint16_t leds) {
+    static bool s_init = false;
+    if (!s_init) {
+        ws2812_init();
+        s_init = true;
+    }
+
+    for (uint8_t i = 0; i < leds; i++) {
+        set_led_color_rgb(ledarray[i], i);
+    }
+
+    // Send async - each led takes ~0.03ms, 50 leds ~1.5ms, animations flushing faster than send will cause issues.
+    // Instead spiSend can be used to send synchronously (or the thread logic can be added back).
+#ifdef WS2812_SPI_SYNC
+    spiSend(&WS2812_SPI, sizeof(txbuf) / sizeof(txbuf[0]), txbuf);
+#else
+    spiStartSend(&WS2812_SPI, sizeof(txbuf) / sizeof(txbuf[0]), txbuf);
+#endif
+}

drivers/boards/GENERIC_STM32_F072XB/board.c

@@ -0,0 +1,97 @@
+/*
+    ChibiOS - Copyright (C) 2006..2016 Giovanni Di Sirio
+
+    Licensed under the Apache License, Version 2.0 (the "License");
+    you may not use this file except in compliance with the License.
+    You may obtain a copy of the License at
+
+        http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+*/
+
+/*
+ * This file has been automatically generated using ChibiStudio board
+ * generator plugin. Do not edit manually.
+ */
+
+#include "hal.h"
+
+#if HAL_USE_PAL || defined(__DOXYGEN__)
+/**
+ * @brief   PAL setup.
+ * @details Digital I/O ports static configuration as defined in @p board.h.
+ *          This variable is used by the HAL when initializing the PAL driver.
+ */
+const PALConfig pal_default_config = {
+#    if STM32_HAS_GPIOA
+    {VAL_GPIOA_MODER, VAL_GPIOA_OTYPER, VAL_GPIOA_OSPEEDR, VAL_GPIOA_PUPDR, VAL_GPIOA_ODR, VAL_GPIOA_AFRL, VAL_GPIOA_AFRH},
+#    endif
+#    if STM32_HAS_GPIOB
+    {VAL_GPIOB_MODER, VAL_GPIOB_OTYPER, VAL_GPIOB_OSPEEDR, VAL_GPIOB_PUPDR, VAL_GPIOB_ODR, VAL_GPIOB_AFRL, VAL_GPIOB_AFRH},
+#    endif
+#    if STM32_HAS_GPIOC
+    {VAL_GPIOC_MODER, VAL_GPIOC_OTYPER, VAL_GPIOC_OSPEEDR, VAL_GPIOC_PUPDR, VAL_GPIOC_ODR, VAL_GPIOC_AFRL, VAL_GPIOC_AFRH},
+#    endif
+#    if STM32_HAS_GPIOD
+    {VAL_GPIOD_MODER, VAL_GPIOD_OTYPER, VAL_GPIOD_OSPEEDR, VAL_GPIOD_PUPDR, VAL_GPIOD_ODR, VAL_GPIOD_AFRL, VAL_GPIOD_AFRH},
+#    endif
+#    if STM32_HAS_GPIOE
+    {VAL_GPIOE_MODER, VAL_GPIOE_OTYPER, VAL_GPIOE_OSPEEDR, VAL_GPIOE_PUPDR, VAL_GPIOE_ODR, VAL_GPIOE_AFRL, VAL_GPIOE_AFRH},
+#    endif
+#    if STM32_HAS_GPIOF
+    {VAL_GPIOF_MODER, VAL_GPIOF_OTYPER, VAL_GPIOF_OSPEEDR, VAL_GPIOF_PUPDR, VAL_GPIOF_ODR, VAL_GPIOF_AFRL, VAL_GPIOF_AFRH},
+#    endif
+#    if STM32_HAS_GPIOG
+    {VAL_GPIOG_MODER, VAL_GPIOG_OTYPER, VAL_GPIOG_OSPEEDR, VAL_GPIOG_PUPDR, VAL_GPIOG_ODR, VAL_GPIOG_AFRL, VAL_GPIOG_AFRH},
+#    endif
+#    if STM32_HAS_GPIOH
+    {VAL_GPIOH_MODER, VAL_GPIOH_OTYPER, VAL_GPIOH_OSPEEDR, VAL_GPIOH_PUPDR, VAL_GPIOH_ODR, VAL_GPIOH_AFRL, VAL_GPIOH_AFRH},
+#    endif
+#    if STM32_HAS_GPIOI
+    {VAL_GPIOI_MODER, VAL_GPIOI_OTYPER, VAL_GPIOI_OSPEEDR, VAL_GPIOI_PUPDR, VAL_GPIOI_ODR, VAL_GPIOI_AFRL, VAL_GPIOI_AFRH}
+#    endif
+};
+#endif
+
+__attribute__((weak)) void enter_bootloader_mode_if_requested(void) {}
+
+/**
+ * @brief   Early initialization code.
+ * @details This initialization must be performed just after stack setup
+ *          and before any other initialization.
+ */
+void __early_init(void) {
+    enter_bootloader_mode_if_requested();
+    stm32_clock_init();
+}
+
+#if HAL_USE_MMC_SPI || defined(__DOXYGEN__)
+/**
+ * @brief   MMC_SPI card detection.
+ */
+bool mmc_lld_is_card_inserted(MMCDriver *mmcp) {
+    (void)mmcp;
+    /* TODO: Fill the implementation.*/
+    return true;
+}
+
+/**
+ * @brief   MMC_SPI card write protection detection.
+ */
+bool mmc_lld_is_write_protected(MMCDriver *mmcp) {
+    (void)mmcp;
+    /* TODO: Fill the implementation.*/
+    return false;
+}
+#endif
+
+/**
+ * @brief   Board-specific initialization code.
+ * @todo    Add your board-specific code, if any.
+ */
+void boardInit(void) {}

drivers/boards/GENERIC_STM32_F072XB/board.h

@@ -0,0 +1,386 @@
+/*
+    ChibiOS - Copyright (C) 2006..2016 Giovanni Di Sirio
+
+    Licensed under the Apache License, Version 2.0 (the "License");
+    you may not use this file except in compliance with the License.
+    You may obtain a copy of the License at
+
+        http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+*/
+
+/*
+ * This file has been automatically generated using ChibiStudio board
+ * generator plugin. Do not edit manually.
+ */
+
+#ifndef BOARD_H
+#define BOARD_H
+
+/*
+ * Setup for Generic STM32_F072 Board
+ */
+
+/*
+ * Board identifier.
+ */
+#define BOARD_GENERIC_STM32_F072XB
+#define BOARD_NAME "STM32_F072"
+
+/*
+ * Board oscillators-related settings.
+ * NOTE: LSE not fitted.
+ * NOTE: HSE not fitted.
+ */
+#if !defined(STM32_LSECLK)
+#    define STM32_LSECLK 0U
+#endif
+
+#define STM32_LSEDRV (3U << 3U)
+
+#if !defined(STM32_HSECLK)
+#    define STM32_HSECLK 0U
+#endif
+
+#define STM32_HSE_BYPASS
+
+/*
+ * MCU type as defined in the ST header.
+ */
+#define STM32F072xB
+
+/*
+ * IO pins assignments.
+ */
+#define GPIOA_BUTTON 0U
+#define GPIOA_PIN1 1U
+#define GPIOA_PIN2 2U
+#define GPIOA_PIN3 3U
+#define GPIOA_PIN4 4U
+#define GPIOA_PIN5 5U
+#define GPIOA_PIN6 6U
+#define GPIOA_PIN7 7U
+#define GPIOA_PIN8 8U
+#define GPIOA_PIN9 9U
+#define GPIOA_PIN10 10U
+#define GPIOA_USB_DM 11U
+#define GPIOA_USB_DP 12U
+#define GPIOA_SWDIO 13U
+#define GPIOA_SWCLK 14U
+#define GPIOA_PIN15 15U
+
+#define GPIOB_PIN0 0U
+#define GPIOB_PIN1 1U
+#define GPIOB_PIN2 2U
+#define GPIOB_PIN3 3U
+#define GPIOB_PIN4 4U
+#define GPIOB_PIN5 5U
+#define GPIOB_PIN6 6U
+#define GPIOB_PIN7 7U
+#define GPIOB_PIN8 8U
+#define GPIOB_PIN9 9U
+#define GPIOB_PIN10 10U
+#define GPIOB_PIN11 11U
+#define GPIOB_PIN12 12U
+#define GPIOB_SPI2_SCK 13U
+#define GPIOB_SPI2_MISO 14U
+#define GPIOB_SPI2_MOSI 15U
+
+#define GPIOC_MEMS_CS 0U
+#define GPIOC_PIN1 1U
+#define GPIOC_PIN2 2U
+#define GPIOC_PIN3 3U
+#define GPIOC_PIN4 4U
+#define GPIOC_PIN5 5U
+#define GPIOC_LED_RED 6U
+#define GPIOC_LED_BLUE 7U
+#define GPIOC_LED_ORANGE 8U
+#define GPIOC_LED_GREEN 9U
+#define GPIOC_PIN10 10U
+#define GPIOC_PIN11 11U
+#define GPIOC_PIN12 12U
+#define GPIOC_PIN13 13U
+#define GPIOC_OSC32_IN 14U
+#define GPIOC_OSC32_OUT 15U
+
+#define GPIOD_PIN0 0U
+#define GPIOD_PIN1 1U
+#define GPIOD_PIN2 2U
+#define GPIOD_PIN3 3U
+#define GPIOD_PIN4 4U
+#define GPIOD_PIN5 5U
+#define GPIOD_PIN6 6U
+#define GPIOD_PIN7 7U
+#define GPIOD_PIN8 8U
+#define GPIOD_PIN9 9U
+#define GPIOD_PIN10 10U
+#define GPIOD_PIN11 11U
+#define GPIOD_PIN12 12U
+#define GPIOD_PIN13 13U
+#define GPIOD_PIN14 14U
+#define GPIOD_PIN15 15U
+
+#define GPIOE_PIN0 0U
+#define GPIOE_PIN1 1U
+#define GPIOE_PIN2 2U
+#define GPIOE_PIN3 3U
+#define GPIOE_PIN4 4U
+#define GPIOE_PIN5 5U
+#define GPIOE_PIN6 6U
+#define GPIOE_PIN7 7U
+#define GPIOE_PIN8 8U
+#define GPIOE_PIN9 9U
+#define GPIOE_PIN10 10U
+#define GPIOE_PIN11 11U
+#define GPIOE_PIN12 12U
+#define GPIOE_PIN13 13U
+#define GPIOE_PIN14 14U
+#define GPIOE_PIN15 15U
+
+#define GPIOF_OSC_IN 0U
+#define GPIOF_OSC_OUT 1U
+#define GPIOF_PIN2 2U
+#define GPIOF_PIN3 3U
+#define GPIOF_PIN4 4U
+#define GPIOF_PIN5 5U
+#define GPIOF_PIN6 6U
+#define GPIOF_PIN7 7U
+#define GPIOF_PIN8 8U
+#define GPIOF_PIN9 9U
+#define GPIOF_PIN10 10U
+#define GPIOF_PIN11 11U
+#define GPIOF_PIN12 12U
+#define GPIOF_PIN13 13U
+#define GPIOF_PIN14 14U
+#define GPIOF_PIN15 15U
+
+/*
+ * IO lines assignments.
+ */
+#define LINE_BUTTON PAL_LINE(GPIOA, 0U)
+#define LINE_USB_DM PAL_LINE(GPIOA, 11U)
+#define LINE_USB_DP PAL_LINE(GPIOA, 12U)
+#define LINE_SWDIO PAL_LINE(GPIOA, 13U)
+#define LINE_SWCLK PAL_LINE(GPIOA, 14U)
+
+#define LINE_SPI2_SCK PAL_LINE(GPIOB, 13U)
+#define LINE_SPI2_MISO PAL_LINE(GPIOB, 14U)
+#define LINE_SPI2_MOSI PAL_LINE(GPIOB, 15U)
+
+#define LINE_MEMS_CS PAL_LINE(GPIOC, 0U)
+#define LINE_LED_RED PAL_LINE(GPIOC, 6U)
+#define LINE_LED_BLUE PAL_LINE(GPIOC, 7U)
+#define LINE_LED_ORANGE PAL_LINE(GPIOC, 8U)
+#define LINE_LED_GREEN PAL_LINE(GPIOC, 9U)
+#define LINE_OSC32_IN PAL_LINE(GPIOC, 14U)
+#define LINE_OSC32_OUT PAL_LINE(GPIOC, 15U)
+
+#define LINE_OSC_IN PAL_LINE(GPIOF, 0U)
+#define LINE_OSC_OUT PAL_LINE(GPIOF, 1U)
+
+/*
+ * I/O ports initial setup, this configuration is established soon after reset
+ * in the initialization code.
+ * Please refer to the STM32 Reference Manual for details.
+ */
+#define PIN_MODE_INPUT(n) (0U << ((n)*2U))
+#define PIN_MODE_OUTPUT(n) (1U << ((n)*2U))
+#define PIN_MODE_ALTERNATE(n) (2U << ((n)*2U))
+#define PIN_MODE_ANALOG(n) (3U << ((n)*2U))
+#define PIN_ODR_LOW(n) (0U << (n))
+#define PIN_ODR_HIGH(n) (1U << (n))
+#define PIN_OTYPE_PUSHPULL(n) (0U << (n))
+#define PIN_OTYPE_OPENDRAIN(n) (1U << (n))
+#define PIN_OSPEED_VERYLOW(n) (0U << ((n)*2U))
+#define PIN_OSPEED_LOW(n) (1U << ((n)*2U))
+#define PIN_OSPEED_MEDIUM(n) (2U << ((n)*2U))
+#define PIN_OSPEED_HIGH(n) (3U << ((n)*2U))
+#define PIN_PUPDR_FLOATING(n) (0U << ((n)*2U))
+#define PIN_PUPDR_PULLUP(n) (1U << ((n)*2U))
+#define PIN_PUPDR_PULLDOWN(n) (2U << ((n)*2U))
+#define PIN_AFIO_AF(n, v) ((v) << (((n) % 8U) * 4U))
+
+/*
+ * GPIOA setup:
+ *
+ * PA0  - BUTTON                    (input floating).
+ * PA1  - PIN1                      (input pullup).
+ * PA2  - PIN2                      (input pullup).
+ * PA3  - PIN3                      (input pullup).
+ * PA4  - PIN4                      (input pullup).
+ * PA5  - PIN5                      (input pullup).
+ * PA6  - PIN6                      (input pullup).
+ * PA7  - PIN7                      (input pullup).
+ * PA8  - PIN8                      (input pullup).
+ * PA9  - PIN9                      (input pullup).
+ * PA10 - PIN10                     (input pullup).
+ * PA11 - USB_DM                    (input floating).
+ * PA12 - USB_DP                    (input floating).
+ * PA13 - SWDIO                     (alternate 0).
+ * PA14 - SWCLK                     (alternate 0).
+ * PA15 - PIN15                     (input pullup).
+ */
+#define VAL_GPIOA_MODER (PIN_MODE_INPUT(GPIOA_BUTTON) | PIN_MODE_INPUT(GPIOA_PIN1) | PIN_MODE_INPUT(GPIOA_PIN2) | PIN_MODE_INPUT(GPIOA_PIN3) | PIN_MODE_INPUT(GPIOA_PIN4) | PIN_MODE_INPUT(GPIOA_PIN5) | PIN_MODE_INPUT(GPIOA_PIN6) | PIN_MODE_INPUT(GPIOA_PIN7) | PIN_MODE_INPUT(GPIOA_PIN8) | PIN_MODE_INPUT(GPIOA_PIN9) | PIN_MODE_INPUT(GPIOA_PIN10) | PIN_MODE_INPUT(GPIOA_USB_DM) | PIN_MODE_INPUT(GPIOA_USB_DP) | PIN_MODE_ALTERNATE(GPIOA_SWDIO) | PIN_MODE_ALTERNATE(GPIOA_SWCLK) | PIN_MODE_INPUT(GPIOA_PIN15))
+#define VAL_GPIOA_OTYPER (PIN_OTYPE_PUSHPULL(GPIOA_BUTTON) | PIN_OTYPE_PUSHPULL(GPIOA_PIN1) | PIN_OTYPE_PUSHPULL(GPIOA_PIN2) | PIN_OTYPE_PUSHPULL(GPIOA_PIN3) | PIN_OTYPE_PUSHPULL(GPIOA_PIN4) | PIN_OTYPE_PUSHPULL(GPIOA_PIN5) | PIN_OTYPE_PUSHPULL(GPIOA_PIN6) | PIN_OTYPE_PUSHPULL(GPIOA_PIN7) | PIN_OTYPE_PUSHPULL(GPIOA_PIN8) | PIN_OTYPE_PUSHPULL(GPIOA_PIN9) | PIN_OTYPE_PUSHPULL(GPIOA_PIN10) | PIN_OTYPE_PUSHPULL(GPIOA_USB_DM) | PIN_OTYPE_PUSHPULL(GPIOA_USB_DP) | PIN_OTYPE_PUSHPULL(GPIOA_SWDIO) | PIN_OTYPE_PUSHPULL(GPIOA_SWCLK) | PIN_OTYPE_PUSHPULL(GPIOA_PIN15))
+#define VAL_GPIOA_OSPEEDR (PIN_OSPEED_VERYLOW(GPIOA_BUTTON) | PIN_OSPEED_VERYLOW(GPIOA_PIN1) | PIN_OSPEED_VERYLOW(GPIOA_PIN2) | PIN_OSPEED_VERYLOW(GPIOA_PIN3) | PIN_OSPEED_VERYLOW(GPIOA_PIN4) | PIN_OSPEED_VERYLOW(GPIOA_PIN5) | PIN_OSPEED_VERYLOW(GPIOA_PIN6) | PIN_OSPEED_VERYLOW(GPIOA_PIN7) | PIN_OSPEED_VERYLOW(GPIOA_PIN8) | PIN_OSPEED_VERYLOW(GPIOA_PIN9) | PIN_OSPEED_VERYLOW(GPIOA_PIN10) | PIN_OSPEED_VERYLOW(GPIOA_USB_DM) | PIN_OSPEED_VERYLOW(GPIOA_USB_DP) | PIN_OSPEED_HIGH(GPIOA_SWDIO) | PIN_OSPEED_HIGH(GPIOA_SWCLK) | PIN_OSPEED_HIGH(GPIOA_PIN15))
+#define VAL_GPIOA_PUPDR (PIN_PUPDR_FLOATING(GPIOA_BUTTON) | PIN_PUPDR_PULLUP(GPIOA_PIN1) | PIN_PUPDR_PULLUP(GPIOA_PIN2) | PIN_PUPDR_PULLUP(GPIOA_PIN3) | PIN_PUPDR_PULLUP(GPIOA_PIN4) | PIN_PUPDR_PULLUP(GPIOA_PIN5) | PIN_PUPDR_PULLUP(GPIOA_PIN6) | PIN_PUPDR_PULLUP(GPIOA_PIN7) | PIN_PUPDR_PULLUP(GPIOA_PIN8) | PIN_PUPDR_PULLUP(GPIOA_PIN9) | PIN_PUPDR_PULLUP(GPIOA_PIN10) | PIN_PUPDR_FLOATING(GPIOA_USB_DM) | PIN_PUPDR_FLOATING(GPIOA_USB_DP) | PIN_PUPDR_PULLUP(GPIOA_SWDIO) | PIN_PUPDR_PULLDOWN(GPIOA_SWCLK) | PIN_PUPDR_PULLUP(GPIOA_PIN15))
+#define VAL_GPIOA_ODR (PIN_ODR_HIGH(GPIOA_BUTTON) | PIN_ODR_HIGH(GPIOA_PIN1) | PIN_ODR_HIGH(GPIOA_PIN2) | PIN_ODR_HIGH(GPIOA_PIN3) | PIN_ODR_HIGH(GPIOA_PIN4) | PIN_ODR_HIGH(GPIOA_PIN5) | PIN_ODR_HIGH(GPIOA_PIN6) | PIN_ODR_HIGH(GPIOA_PIN7) | PIN_ODR_HIGH(GPIOA_PIN8) | PIN_ODR_HIGH(GPIOA_PIN9) | PIN_ODR_HIGH(GPIOA_PIN10) | PIN_ODR_HIGH(GPIOA_USB_DM) | PIN_ODR_HIGH(GPIOA_USB_DP) | PIN_ODR_HIGH(GPIOA_SWDIO) | PIN_ODR_HIGH(GPIOA_SWCLK) | PIN_ODR_HIGH(GPIOA_PIN15))
+#define VAL_GPIOA_AFRL (PIN_AFIO_AF(GPIOA_BUTTON, 0U) | PIN_AFIO_AF(GPIOA_PIN1, 0U) | PIN_AFIO_AF(GPIOA_PIN2, 0U) | PIN_AFIO_AF(GPIOA_PIN3, 0U) | PIN_AFIO_AF(GPIOA_PIN4, 0U) | PIN_AFIO_AF(GPIOA_PIN5, 0U) | PIN_AFIO_AF(GPIOA_PIN6, 0U) | PIN_AFIO_AF(GPIOA_PIN7, 0U))
+#define VAL_GPIOA_AFRH (PIN_AFIO_AF(GPIOA_PIN8, 0U) | PIN_AFIO_AF(GPIOA_PIN9, 0U) | PIN_AFIO_AF(GPIOA_PIN10, 0U) | PIN_AFIO_AF(GPIOA_USB_DM, 0U) | PIN_AFIO_AF(GPIOA_USB_DP, 0U) | PIN_AFIO_AF(GPIOA_SWDIO, 0U) | PIN_AFIO_AF(GPIOA_SWCLK, 0U) | PIN_AFIO_AF(GPIOA_PIN15, 0U))
+
+/*
+ * GPIOB setup:
+ *
+ * PB0  - PIN0                      (input pullup).
+ * PB1  - PIN1                      (input pullup).
+ * PB2  - PIN2                      (input pullup).
+ * PB3  - PIN3                      (input pullup).
+ * PB4  - PIN4                      (input pullup).
+ * PB5  - PIN5                      (input pullup).
+ * PB6  - PIN6                      (input pullup).
+ * PB7  - PIN7                      (input pullup).
+ * PB8  - PIN8                      (input pullup).
+ * PB9  - PIN9                      (input pullup).
+ * PB10 - PIN10                     (input pullup).
+ * PB11 - PIN11                     (input pullup).
+ * PB12 - PIN12                     (input pullup).
+ * PB13 - SPI2_SCK                  (alternate 0).
+ * PB14 - SPI2_MISO                 (alternate 0).
+ * PB15 - SPI2_MOSI                 (alternate 0).
+ */
+#define VAL_GPIOB_MODER (PIN_MODE_INPUT(GPIOB_PIN0) | PIN_MODE_INPUT(GPIOB_PIN1) | PIN_MODE_INPUT(GPIOB_PIN2) | PIN_MODE_INPUT(GPIOB_PIN3) | PIN_MODE_INPUT(GPIOB_PIN4) | PIN_MODE_INPUT(GPIOB_PIN5) | PIN_MODE_INPUT(GPIOB_PIN6) | PIN_MODE_INPUT(GPIOB_PIN7) | PIN_MODE_INPUT(GPIOB_PIN8) | PIN_MODE_INPUT(GPIOB_PIN9) | PIN_MODE_INPUT(GPIOB_PIN10) | PIN_MODE_INPUT(GPIOB_PIN11) | PIN_MODE_INPUT(GPIOB_PIN12) | PIN_MODE_ALTERNATE(GPIOB_SPI2_SCK) | PIN_MODE_ALTERNATE(GPIOB_SPI2_MISO) | PIN_MODE_ALTERNATE(GPIOB_SPI2_MOSI))
+#define VAL_GPIOB_OTYPER (PIN_OTYPE_PUSHPULL(GPIOB_PIN0) | PIN_OTYPE_PUSHPULL(GPIOB_PIN1) | PIN_OTYPE_PUSHPULL(GPIOB_PIN2) | PIN_OTYPE_PUSHPULL(GPIOB_PIN3) | PIN_OTYPE_PUSHPULL(GPIOB_PIN4) | PIN_OTYPE_PUSHPULL(GPIOB_PIN5) | PIN_OTYPE_PUSHPULL(GPIOB_PIN6) | PIN_OTYPE_PUSHPULL(GPIOB_PIN7) | PIN_OTYPE_PUSHPULL(GPIOB_PIN8) | PIN_OTYPE_PUSHPULL(GPIOB_PIN9) | PIN_OTYPE_PUSHPULL(GPIOB_PIN10) | PIN_OTYPE_PUSHPULL(GPIOB_PIN11) | PIN_OTYPE_PUSHPULL(GPIOB_PIN12) | PIN_OTYPE_PUSHPULL(GPIOB_SPI2_SCK) | PIN_OTYPE_PUSHPULL(GPIOB_SPI2_MISO) | PIN_OTYPE_PUSHPULL(GPIOB_SPI2_MOSI))
+#define VAL_GPIOB_OSPEEDR (PIN_OSPEED_VERYLOW(GPIOB_PIN0) | PIN_OSPEED_VERYLOW(GPIOB_PIN1) | PIN_OSPEED_HIGH(GPIOB_PIN2) | PIN_OSPEED_HIGH(GPIOB_PIN3) | PIN_OSPEED_HIGH(GPIOB_PIN4) | PIN_OSPEED_VERYLOW(GPIOB_PIN5) | PIN_OSPEED_VERYLOW(GPIOB_PIN6) | PIN_OSPEED_VERYLOW(GPIOB_PIN7) | PIN_OSPEED_VERYLOW(GPIOB_PIN8) | PIN_OSPEED_VERYLOW(GPIOB_PIN9) | PIN_OSPEED_VERYLOW(GPIOB_PIN10) | PIN_OSPEED_VERYLOW(GPIOB_PIN11) | PIN_OSPEED_VERYLOW(GPIOB_PIN12) | PIN_OSPEED_VERYLOW(GPIOB_SPI2_SCK) | PIN_OSPEED_VERYLOW(GPIOB_SPI2_MISO) | PIN_OSPEED_VERYLOW(GPIOB_SPI2_MOSI))
+#define VAL_GPIOB_PUPDR (PIN_PUPDR_PULLUP(GPIOB_PIN0) | PIN_PUPDR_PULLUP(GPIOB_PIN1) | PIN_PUPDR_PULLUP(GPIOB_PIN2) | PIN_PUPDR_PULLUP(GPIOB_PIN3) | PIN_PUPDR_PULLUP(GPIOB_PIN4) | PIN_PUPDR_PULLUP(GPIOB_PIN5) | PIN_PUPDR_PULLUP(GPIOB_PIN6) | PIN_PUPDR_PULLUP(GPIOB_PIN7) | PIN_PUPDR_PULLUP(GPIOB_PIN8) | PIN_PUPDR_PULLUP(GPIOB_PIN9) | PIN_PUPDR_PULLUP(GPIOB_PIN10) | PIN_PUPDR_PULLUP(GPIOB_PIN11) | PIN_PUPDR_PULLUP(GPIOB_PIN12) | PIN_PUPDR_FLOATING(GPIOB_SPI2_SCK) | PIN_PUPDR_FLOATING(GPIOB_SPI2_MISO) | PIN_PUPDR_FLOATING(GPIOB_SPI2_MOSI))
+#define VAL_GPIOB_ODR (PIN_ODR_HIGH(GPIOB_PIN0) | PIN_ODR_HIGH(GPIOB_PIN1) | PIN_ODR_HIGH(GPIOB_PIN2) | PIN_ODR_HIGH(GPIOB_PIN3) | PIN_ODR_HIGH(GPIOB_PIN4) | PIN_ODR_HIGH(GPIOB_PIN5) | PIN_ODR_HIGH(GPIOB_PIN6) | PIN_ODR_HIGH(GPIOB_PIN7) | PIN_ODR_HIGH(GPIOB_PIN8) | PIN_ODR_HIGH(GPIOB_PIN9) | PIN_ODR_HIGH(GPIOB_PIN10) | PIN_ODR_HIGH(GPIOB_PIN11) | PIN_ODR_HIGH(GPIOB_PIN12) | PIN_ODR_HIGH(GPIOB_SPI2_SCK) | PIN_ODR_HIGH(GPIOB_SPI2_MISO) | PIN_ODR_HIGH(GPIOB_SPI2_MOSI))
+#define VAL_GPIOB_AFRL (PIN_AFIO_AF(GPIOB_PIN0, 0U) | PIN_AFIO_AF(GPIOB_PIN1, 0U) | PIN_AFIO_AF(GPIOB_PIN2, 0U) | PIN_AFIO_AF(GPIOB_PIN3, 0U) | PIN_AFIO_AF(GPIOB_PIN4, 0U) | PIN_AFIO_AF(GPIOB_PIN5, 0U) | PIN_AFIO_AF(GPIOB_PIN6, 0U) | PIN_AFIO_AF(GPIOB_PIN7, 0U))
+#define VAL_GPIOB_AFRH (PIN_AFIO_AF(GPIOB_PIN8, 0U) | PIN_AFIO_AF(GPIOB_PIN9, 0U) | PIN_AFIO_AF(GPIOB_PIN10, 0U) | PIN_AFIO_AF(GPIOB_PIN11, 0U) | PIN_AFIO_AF(GPIOB_PIN12, 0U) | PIN_AFIO_AF(GPIOB_SPI2_SCK, 0U) | PIN_AFIO_AF(GPIOB_SPI2_MISO, 0U) | PIN_AFIO_AF(GPIOB_SPI2_MOSI, 0U))
+
+/*
+ * GPIOC setup:
+ *
+ * PC0  - MEMS_CS                   (output pushpull maximum).
+ * PC1  - PIN1                      (input pullup).
+ * PC2  - PIN2                      (input pullup).
+ * PC3  - PIN3                      (input pullup).
+ * PC4  - PIN4                      (input pullup).
+ * PC5  - PIN5                      (input pullup).
+ * PC6  - LED_RED                   (output pushpull maximum).
+ * PC7  - LED_BLUE                  (output pushpull maximum).
+ * PC8  - LED_ORANGE                (output pushpull maximum).
+ * PC9  - LED_GREEN                 (output pushpull maximum).
+ * PC10 - PIN10                     (input pullup).
+ * PC11 - PIN11                     (input pullup).
+ * PC12 - PIN12                     (input pullup).
+ * PC13 - PIN13                     (input pullup).
+ * PC14 - OSC32_IN                  (input floating).
+ * PC15 - OSC32_OUT                 (input floating).
+ */
+#define VAL_GPIOC_MODER (PIN_MODE_OUTPUT(GPIOC_MEMS_CS) | PIN_MODE_INPUT(GPIOC_PIN1) | PIN_MODE_INPUT(GPIOC_PIN2) | PIN_MODE_INPUT(GPIOC_PIN3) | PIN_MODE_INPUT(GPIOC_PIN4) | PIN_MODE_INPUT(GPIOC_PIN5) | PIN_MODE_OUTPUT(GPIOC_LED_RED) | PIN_MODE_OUTPUT(GPIOC_LED_BLUE) | PIN_MODE_OUTPUT(GPIOC_LED_ORANGE) | PIN_MODE_OUTPUT(GPIOC_LED_GREEN) | PIN_MODE_INPUT(GPIOC_PIN10) | PIN_MODE_INPUT(GPIOC_PIN11) | PIN_MODE_INPUT(GPIOC_PIN12) | PIN_MODE_INPUT(GPIOC_PIN13) | PIN_MODE_INPUT(GPIOC_OSC32_IN) | PIN_MODE_INPUT(GPIOC_OSC32_OUT))
+#define VAL_GPIOC_OTYPER (PIN_OTYPE_PUSHPULL(GPIOC_MEMS_CS) | PIN_OTYPE_PUSHPULL(GPIOC_PIN1) | PIN_OTYPE_PUSHPULL(GPIOC_PIN2) | PIN_OTYPE_PUSHPULL(GPIOC_PIN3) | PIN_OTYPE_PUSHPULL(GPIOC_PIN4) | PIN_OTYPE_PUSHPULL(GPIOC_PIN5) | PIN_OTYPE_PUSHPULL(GPIOC_LED_RED) | PIN_OTYPE_PUSHPULL(GPIOC_LED_BLUE) | PIN_OTYPE_PUSHPULL(GPIOC_LED_ORANGE) | PIN_OTYPE_PUSHPULL(GPIOC_LED_GREEN) | PIN_OTYPE_PUSHPULL(GPIOC_PIN10) | PIN_OTYPE_PUSHPULL(GPIOC_PIN11) | PIN_OTYPE_PUSHPULL(GPIOC_PIN12) | PIN_OTYPE_PUSHPULL(GPIOC_PIN13) | PIN_OTYPE_PUSHPULL(GPIOC_OSC32_IN) | PIN_OTYPE_PUSHPULL(GPIOC_OSC32_OUT))
+#define VAL_GPIOC_OSPEEDR (PIN_OSPEED_HIGH(GPIOC_MEMS_CS) | PIN_OSPEED_VERYLOW(GPIOC_PIN1) | PIN_OSPEED_VERYLOW(GPIOC_PIN2) | PIN_OSPEED_VERYLOW(GPIOC_PIN3) | PIN_OSPEED_VERYLOW(GPIOC_PIN4) | PIN_OSPEED_VERYLOW(GPIOC_PIN5) | PIN_OSPEED_HIGH(GPIOC_LED_RED) | PIN_OSPEED_HIGH(GPIOC_LED_BLUE) | PIN_OSPEED_HIGH(GPIOC_LED_ORANGE) | PIN_OSPEED_HIGH(GPIOC_LED_GREEN) | PIN_OSPEED_VERYLOW(GPIOC_PIN10) | PIN_OSPEED_VERYLOW(GPIOC_PIN11) | PIN_OSPEED_VERYLOW(GPIOC_PIN12) | PIN_OSPEED_VERYLOW(GPIOC_PIN13) | PIN_OSPEED_HIGH(GPIOC_OSC32_IN) | PIN_OSPEED_HIGH(GPIOC_OSC32_OUT))
+#define VAL_GPIOC_PUPDR (PIN_PUPDR_FLOATING(GPIOC_MEMS_CS) | PIN_PUPDR_PULLUP(GPIOC_PIN1) | PIN_PUPDR_PULLUP(GPIOC_PIN2) | PIN_PUPDR_PULLUP(GPIOC_PIN3) | PIN_PUPDR_PULLUP(GPIOC_PIN4) | PIN_PUPDR_PULLUP(GPIOC_PIN5) | PIN_PUPDR_FLOATING(GPIOC_LED_RED) | PIN_PUPDR_FLOATING(GPIOC_LED_BLUE) | PIN_PUPDR_FLOATING(GPIOC_LED_ORANGE) | PIN_PUPDR_FLOATING(GPIOC_LED_GREEN) | PIN_PUPDR_PULLUP(GPIOC_PIN10) | PIN_PUPDR_PULLUP(GPIOC_PIN11) | PIN_PUPDR_PULLUP(GPIOC_PIN12) | PIN_PUPDR_PULLUP(GPIOC_PIN13) | PIN_PUPDR_FLOATING(GPIOC_OSC32_IN) | PIN_PUPDR_FLOATING(GPIOC_OSC32_OUT))
+#define VAL_GPIOC_ODR (PIN_ODR_HIGH(GPIOC_MEMS_CS) | PIN_ODR_HIGH(GPIOC_PIN1) | PIN_ODR_HIGH(GPIOC_PIN2) | PIN_ODR_HIGH(GPIOC_PIN3) | PIN_ODR_HIGH(GPIOC_PIN4) | PIN_ODR_HIGH(GPIOC_PIN5) | PIN_ODR_LOW(GPIOC_LED_RED) | PIN_ODR_LOW(GPIOC_LED_BLUE) | PIN_ODR_LOW(GPIOC_LED_ORANGE) | PIN_ODR_LOW(GPIOC_LED_GREEN) | PIN_ODR_HIGH(GPIOC_PIN10) | PIN_ODR_HIGH(GPIOC_PIN11) | PIN_ODR_HIGH(GPIOC_PIN12) | PIN_ODR_HIGH(GPIOC_PIN13) | PIN_ODR_HIGH(GPIOC_OSC32_IN) | PIN_ODR_HIGH(GPIOC_OSC32_OUT))
+#define VAL_GPIOC_AFRL (PIN_AFIO_AF(GPIOC_MEMS_CS, 0U) | PIN_AFIO_AF(GPIOC_PIN1, 0U) | PIN_AFIO_AF(GPIOC_PIN2, 0U) | PIN_AFIO_AF(GPIOC_PIN3, 0U) | PIN_AFIO_AF(GPIOC_PIN4, 0U) | PIN_AFIO_AF(GPIOC_PIN5, 0U) | PIN_AFIO_AF(GPIOC_LED_RED, 0U) | PIN_AFIO_AF(GPIOC_LED_BLUE, 0U))
+#define VAL_GPIOC_AFRH (PIN_AFIO_AF(GPIOC_LED_ORANGE, 0U) | PIN_AFIO_AF(GPIOC_LED_GREEN, 0U) | PIN_AFIO_AF(GPIOC_PIN10, 0U) | PIN_AFIO_AF(GPIOC_PIN11, 0U) | PIN_AFIO_AF(GPIOC_PIN12, 0U) | PIN_AFIO_AF(GPIOC_PIN13, 0U) | PIN_AFIO_AF(GPIOC_OSC32_IN, 0U) | PIN_AFIO_AF(GPIOC_OSC32_OUT, 0U))
+
+/*
+ * GPIOD setup:
+ *
+ * PD0  - PIN0                      (input pullup).
+ * PD1  - PIN1                      (input pullup).
+ * PD2  - PIN2                      (input pullup).
+ * PD3  - PIN3                      (input pullup).
+ * PD4  - PIN4                      (input pullup).
+ * PD5  - PIN5                      (input pullup).
+ * PD6  - PIN6                      (input pullup).
+ * PD7  - PIN7                      (input pullup).
+ * PD8  - PIN8                      (input pullup).
+ * PD9  - PIN9                      (input pullup).
+ * PD10 - PIN10                     (input pullup).
+ * PD11 - PIN11                     (input pullup).
+ * PD12 - PIN12                     (input pullup).
+ * PD13 - PIN13                     (input pullup).
+ * PD14 - PIN14                     (input pullup).
+ * PD15 - PIN15                     (input pullup).
+ */
+#define VAL_GPIOD_MODER (PIN_MODE_INPUT(GPIOD_PIN0) | PIN_MODE_INPUT(GPIOD_PIN1) | PIN_MODE_INPUT(GPIOD_PIN2) | PIN_MODE_INPUT(GPIOD_PIN3) | PIN_MODE_INPUT(GPIOD_PIN4) | PIN_MODE_INPUT(GPIOD_PIN5) | PIN_MODE_INPUT(GPIOD_PIN6) | PIN_MODE_INPUT(GPIOD_PIN7) | PIN_MODE_INPUT(GPIOD_PIN8) | PIN_MODE_INPUT(GPIOD_PIN9) | PIN_MODE_INPUT(GPIOD_PIN10) | PIN_MODE_INPUT(GPIOD_PIN11) | PIN_MODE_INPUT(GPIOD_PIN12) | PIN_MODE_INPUT(GPIOD_PIN13) | PIN_MODE_INPUT(GPIOD_PIN14) | PIN_MODE_INPUT(GPIOD_PIN15))
+#define VAL_GPIOD_OTYPER (PIN_OTYPE_PUSHPULL(GPIOD_PIN0) | PIN_OTYPE_PUSHPULL(GPIOD_PIN1) | PIN_OTYPE_PUSHPULL(GPIOD_PIN2) | PIN_OTYPE_PUSHPULL(GPIOD_PIN3) | PIN_OTYPE_PUSHPULL(GPIOD_PIN4) | PIN_OTYPE_PUSHPULL(GPIOD_PIN5) | PIN_OTYPE_PUSHPULL(GPIOD_PIN6) | PIN_OTYPE_PUSHPULL(GPIOD_PIN7) | PIN_OTYPE_PUSHPULL(GPIOD_PIN8) | PIN_OTYPE_PUSHPULL(GPIOD_PIN9) | PIN_OTYPE_PUSHPULL(GPIOD_PIN10) | PIN_OTYPE_PUSHPULL(GPIOD_PIN11) | PIN_OTYPE_PUSHPULL(GPIOD_PIN12) | PIN_OTYPE_PUSHPULL(GPIOD_PIN13) | PIN_OTYPE_PUSHPULL(GPIOD_PIN14) | PIN_OTYPE_PUSHPULL(GPIOD_PIN15))
+#define VAL_GPIOD_OSPEEDR (PIN_OSPEED_VERYLOW(GPIOD_PIN0) | PIN_OSPEED_VERYLOW(GPIOD_PIN1) | PIN_OSPEED_VERYLOW(GPIOD_PIN2) | PIN_OSPEED_VERYLOW(GPIOD_PIN3) | PIN_OSPEED_VERYLOW(GPIOD_PIN4) | PIN_OSPEED_VERYLOW(GPIOD_PIN5) | PIN_OSPEED_VERYLOW(GPIOD_PIN6) | PIN_OSPEED_VERYLOW(GPIOD_PIN7) | PIN_OSPEED_VERYLOW(GPIOD_PIN8) | PIN_OSPEED_VERYLOW(GPIOD_PIN9) | PIN_OSPEED_VERYLOW(GPIOD_PIN10) | PIN_OSPEED_VERYLOW(GPIOD_PIN11) | PIN_OSPEED_VERYLOW(GPIOD_PIN12) | PIN_OSPEED_VERYLOW(GPIOD_PIN13) | PIN_OSPEED_VERYLOW(GPIOD_PIN14) | PIN_OSPEED_VERYLOW(GPIOD_PIN15))
+#define VAL_GPIOD_PUPDR (PIN_PUPDR_PULLUP(GPIOD_PIN0) | PIN_PUPDR_PULLUP(GPIOD_PIN1) | PIN_PUPDR_PULLUP(GPIOD_PIN2) | PIN_PUPDR_PULLUP(GPIOD_PIN3) | PIN_PUPDR_PULLUP(GPIOD_PIN4) | PIN_PUPDR_PULLUP(GPIOD_PIN5) | PIN_PUPDR_PULLUP(GPIOD_PIN6) | PIN_PUPDR_PULLUP(GPIOD_PIN7) | PIN_PUPDR_PULLUP(GPIOD_PIN8) | PIN_PUPDR_PULLUP(GPIOD_PIN9) | PIN_PUPDR_PULLUP(GPIOD_PIN10) | PIN_PUPDR_PULLUP(GPIOD_PIN11) | PIN_PUPDR_PULLUP(GPIOD_PIN12) | PIN_PUPDR_PULLUP(GPIOD_PIN13) | PIN_PUPDR_PULLUP(GPIOD_PIN14) | PIN_PUPDR_PULLUP(GPIOD_PIN15))
+#define VAL_GPIOD_ODR (PIN_ODR_HIGH(GPIOD_PIN0) | PIN_ODR_HIGH(GPIOD_PIN1) | PIN_ODR_HIGH(GPIOD_PIN2) | PIN_ODR_HIGH(GPIOD_PIN3) | PIN_ODR_HIGH(GPIOD_PIN4) | PIN_ODR_HIGH(GPIOD_PIN5) | PIN_ODR_HIGH(GPIOD_PIN6) | PIN_ODR_HIGH(GPIOD_PIN7) | PIN_ODR_HIGH(GPIOD_PIN8) | PIN_ODR_HIGH(GPIOD_PIN9) | PIN_ODR_HIGH(GPIOD_PIN10) | PIN_ODR_HIGH(GPIOD_PIN11) | PIN_ODR_HIGH(GPIOD_PIN12) | PIN_ODR_HIGH(GPIOD_PIN13) | PIN_ODR_HIGH(GPIOD_PIN14) | PIN_ODR_HIGH(GPIOD_PIN15))
+#define VAL_GPIOD_AFRL (PIN_AFIO_AF(GPIOD_PIN0, 0U) | PIN_AFIO_AF(GPIOD_PIN1, 0U) | PIN_AFIO_AF(GPIOD_PIN2, 0U) | PIN_AFIO_AF(GPIOD_PIN3, 0U) | PIN_AFIO_AF(GPIOD_PIN4, 0U) | PIN_AFIO_AF(GPIOD_PIN5, 0U) | PIN_AFIO_AF(GPIOD_PIN6, 0U) | PIN_AFIO_AF(GPIOD_PIN7, 0U))
+#define VAL_GPIOD_AFRH (PIN_AFIO_AF(GPIOD_PIN8, 0U) | PIN_AFIO_AF(GPIOD_PIN9, 0U) | PIN_AFIO_AF(GPIOD_PIN10, 0U) | PIN_AFIO_AF(GPIOD_PIN11, 0U) | PIN_AFIO_AF(GPIOD_PIN12, 0U) | PIN_AFIO_AF(GPIOD_PIN13, 0U) | PIN_AFIO_AF(GPIOD_PIN14, 0U) | PIN_AFIO_AF(GPIOD_PIN15, 0U))
+
+/*
+ * GPIOE setup:
+ *
+ * PE0  - PIN0                      (input pullup).
+ * PE1  - PIN1                      (input pullup).
+ * PE2  - PIN2                      (input pullup).
+ * PE3  - PIN3                      (input pullup).
+ * PE4  - PIN4                      (input pullup).
+ * PE5  - PIN5                      (input pullup).
+ * PE6  - PIN6                      (input pullup).
+ * PE7  - PIN7                      (input pullup).
+ * PE8  - PIN8                      (input pullup).
+ * PE9  - PIN9                      (input pullup).
+ * PE10 - PIN10                     (input pullup).
+ * PE11 - PIN11                     (input pullup).
+ * PE12 - PIN12                     (input pullup).
+ * PE13 - PIN13                     (input pullup).
+ * PE14 - PIN14                     (input pullup).
+ * PE15 - PIN15                     (input pullup).
+ */
+#define VAL_GPIOE_MODER (PIN_MODE_INPUT(GPIOE_PIN0) | PIN_MODE_INPUT(GPIOE_PIN1) | PIN_MODE_INPUT(GPIOE_PIN2) | PIN_MODE_INPUT(GPIOE_PIN3) | PIN_MODE_INPUT(GPIOE_PIN4) | PIN_MODE_INPUT(GPIOE_PIN5) | PIN_MODE_INPUT(GPIOE_PIN6) | PIN_MODE_INPUT(GPIOE_PIN7) | PIN_MODE_INPUT(GPIOE_PIN8) | PIN_MODE_INPUT(GPIOE_PIN9) | PIN_MODE_INPUT(GPIOE_PIN10) | PIN_MODE_INPUT(GPIOE_PIN11) | PIN_MODE_INPUT(GPIOE_PIN12) | PIN_MODE_INPUT(GPIOE_PIN13) | PIN_MODE_INPUT(GPIOE_PIN14) | PIN_MODE_INPUT(GPIOE_PIN15))
+#define VAL_GPIOE_OTYPER (PIN_OTYPE_PUSHPULL(GPIOE_PIN0) | PIN_OTYPE_PUSHPULL(GPIOE_PIN1) | PIN_OTYPE_PUSHPULL(GPIOE_PIN2) | PIN_OTYPE_PUSHPULL(GPIOE_PIN3) | PIN_OTYPE_PUSHPULL(GPIOE_PIN4) | PIN_OTYPE_PUSHPULL(GPIOE_PIN5) | PIN_OTYPE_PUSHPULL(GPIOE_PIN6) | PIN_OTYPE_PUSHPULL(GPIOE_PIN7) | PIN_OTYPE_PUSHPULL(GPIOE_PIN8) | PIN_OTYPE_PUSHPULL(GPIOE_PIN9) | PIN_OTYPE_PUSHPULL(GPIOE_PIN10) | PIN_OTYPE_PUSHPULL(GPIOE_PIN11) | PIN_OTYPE_PUSHPULL(GPIOE_PIN12) | PIN_OTYPE_PUSHPULL(GPIOE_PIN13) | PIN_OTYPE_PUSHPULL(GPIOE_PIN14) | PIN_OTYPE_PUSHPULL(GPIOE_PIN15))
+#define VAL_GPIOE_OSPEEDR (PIN_OSPEED_VERYLOW(GPIOE_PIN0) | PIN_OSPEED_VERYLOW(GPIOE_PIN1) | PIN_OSPEED_VERYLOW(GPIOE_PIN2) | PIN_OSPEED_VERYLOW(GPIOE_PIN3) | PIN_OSPEED_VERYLOW(GPIOE_PIN4) | PIN_OSPEED_VERYLOW(GPIOE_PIN5) | PIN_OSPEED_VERYLOW(GPIOE_PIN6) | PIN_OSPEED_VERYLOW(GPIOE_PIN7) | PIN_OSPEED_VERYLOW(GPIOE_PIN8) | PIN_OSPEED_VERYLOW(GPIOE_PIN9) | PIN_OSPEED_VERYLOW(GPIOE_PIN10) | PIN_OSPEED_VERYLOW(GPIOE_PIN11) | PIN_OSPEED_VERYLOW(GPIOE_PIN12) | PIN_OSPEED_VERYLOW(GPIOE_PIN13) | PIN_OSPEED_VERYLOW(GPIOE_PIN14) | PIN_OSPEED_VERYLOW(GPIOE_PIN15))
+#define VAL_GPIOE_PUPDR (PIN_PUPDR_PULLUP(GPIOE_PIN0) | PIN_PUPDR_PULLUP(GPIOE_PIN1) | PIN_PUPDR_PULLUP(GPIOE_PIN2) | PIN_PUPDR_PULLUP(GPIOE_PIN3) | PIN_PUPDR_PULLUP(GPIOE_PIN4) | PIN_PUPDR_PULLUP(GPIOE_PIN5) | PIN_PUPDR_PULLUP(GPIOE_PIN6) | PIN_PUPDR_PULLUP(GPIOE_PIN7) | PIN_PUPDR_PULLUP(GPIOE_PIN8) | PIN_PUPDR_PULLUP(GPIOE_PIN9) | PIN_PUPDR_PULLUP(GPIOE_PIN10) | PIN_PUPDR_PULLUP(GPIOE_PIN11) | PIN_PUPDR_PULLUP(GPIOE_PIN12) | PIN_PUPDR_PULLUP(GPIOE_PIN13) | PIN_PUPDR_PULLUP(GPIOE_PIN14) | PIN_PUPDR_PULLUP(GPIOE_PIN15))
+#define VAL_GPIOE_ODR (PIN_ODR_HIGH(GPIOE_PIN0) | PIN_ODR_HIGH(GPIOE_PIN1) | PIN_ODR_HIGH(GPIOE_PIN2) | PIN_ODR_HIGH(GPIOE_PIN3) | PIN_ODR_HIGH(GPIOE_PIN4) | PIN_ODR_HIGH(GPIOE_PIN5) | PIN_ODR_HIGH(GPIOE_PIN6) | PIN_ODR_HIGH(GPIOE_PIN7) | PIN_ODR_HIGH(GPIOE_PIN8) | PIN_ODR_HIGH(GPIOE_PIN9) | PIN_ODR_HIGH(GPIOE_PIN10) | PIN_ODR_HIGH(GPIOE_PIN11) | PIN_ODR_HIGH(GPIOE_PIN12) | PIN_ODR_HIGH(GPIOE_PIN13) | PIN_ODR_HIGH(GPIOE_PIN14) | PIN_ODR_HIGH(GPIOE_PIN15))
+#define VAL_GPIOE_AFRL (PIN_AFIO_AF(GPIOE_PIN0, 0U) | PIN_AFIO_AF(GPIOE_PIN1, 0U) | PIN_AFIO_AF(GPIOE_PIN2, 0U) | PIN_AFIO_AF(GPIOE_PIN3, 0U) | PIN_AFIO_AF(GPIOE_PIN4, 0U) | PIN_AFIO_AF(GPIOE_PIN5, 0U) | PIN_AFIO_AF(GPIOE_PIN6, 0U) | PIN_AFIO_AF(GPIOE_PIN7, 0U))
+#define VAL_GPIOE_AFRH (PIN_AFIO_AF(GPIOE_PIN8, 0U) | PIN_AFIO_AF(GPIOE_PIN9, 0U) | PIN_AFIO_AF(GPIOE_PIN10, 0U) | PIN_AFIO_AF(GPIOE_PIN11, 0U) | PIN_AFIO_AF(GPIOE_PIN12, 0U) | PIN_AFIO_AF(GPIOE_PIN13, 0U) | PIN_AFIO_AF(GPIOE_PIN14, 0U) | PIN_AFIO_AF(GPIOE_PIN15, 0U))
+
+/*
+ * GPIOF setup:
+ *
+ * PF0  - OSC_IN                    (input floating).
+ * PF1  - OSC_OUT                   (input floating).
+ * PF2  - PIN2                      (input pullup).
+ * PF3  - PIN3                      (input pullup).
+ * PF4  - PIN4                      (input pullup).
+ * PF5  - PIN5                      (input pullup).
+ * PF6  - PIN6                      (input pullup).
+ * PF7  - PIN7                      (input pullup).
+ * PF8  - PIN8                      (input pullup).
+ * PF9  - PIN9                      (input pullup).
+ * PF10 - PIN10                     (input pullup).
+ * PF11 - PIN11                     (input pullup).
+ * PF12 - PIN12                     (input pullup).
+ * PF13 - PIN13                     (input pullup).
+ * PF14 - PIN14                     (input pullup).
+ * PF15 - PIN15                     (input pullup).
+ */
+#define VAL_GPIOF_MODER (PIN_MODE_INPUT(GPIOF_OSC_IN) | PIN_MODE_INPUT(GPIOF_OSC_OUT) | PIN_MODE_INPUT(GPIOF_PIN2) | PIN_MODE_INPUT(GPIOF_PIN3) | PIN_MODE_INPUT(GPIOF_PIN4) | PIN_MODE_INPUT(GPIOF_PIN5) | PIN_MODE_INPUT(GPIOF_PIN6) | PIN_MODE_INPUT(GPIOF_PIN7) | PIN_MODE_INPUT(GPIOF_PIN8) | PIN_MODE_INPUT(GPIOF_PIN9) | PIN_MODE_INPUT(GPIOF_PIN10) | PIN_MODE_INPUT(GPIOF_PIN11) | PIN_MODE_INPUT(GPIOF_PIN12) | PIN_MODE_INPUT(GPIOF_PIN13) | PIN_MODE_INPUT(GPIOF_PIN14) | PIN_MODE_INPUT(GPIOF_PIN15))
+#define VAL_GPIOF_OTYPER (PIN_OTYPE_PUSHPULL(GPIOF_OSC_IN) | PIN_OTYPE_PUSHPULL(GPIOF_OSC_OUT) | PIN_OTYPE_PUSHPULL(GPIOF_PIN2) | PIN_OTYPE_PUSHPULL(GPIOF_PIN3) | PIN_OTYPE_PUSHPULL(GPIOF_PIN4) | PIN_OTYPE_PUSHPULL(GPIOF_PIN5) | PIN_OTYPE_PUSHPULL(GPIOF_PIN6) | PIN_OTYPE_PUSHPULL(GPIOF_PIN7) | PIN_OTYPE_PUSHPULL(GPIOF_PIN8) | PIN_OTYPE_PUSHPULL(GPIOF_PIN9) | PIN_OTYPE_PUSHPULL(GPIOF_PIN10) | PIN_OTYPE_PUSHPULL(GPIOF_PIN11) | PIN_OTYPE_PUSHPULL(GPIOF_PIN12) | PIN_OTYPE_PUSHPULL(GPIOF_PIN13) | PIN_OTYPE_PUSHPULL(GPIOF_PIN14) | PIN_OTYPE_PUSHPULL(GPIOF_PIN15))
+#define VAL_GPIOF_OSPEEDR (PIN_OSPEED_VERYLOW(GPIOF_OSC_IN) | PIN_OSPEED_VERYLOW(GPIOF_OSC_OUT) | PIN_OSPEED_VERYLOW(GPIOF_PIN2) | PIN_OSPEED_VERYLOW(GPIOF_PIN3) | PIN_OSPEED_VERYLOW(GPIOF_PIN4) | PIN_OSPEED_VERYLOW(GPIOF_PIN5) | PIN_OSPEED_VERYLOW(GPIOF_PIN6) | PIN_OSPEED_VERYLOW(GPIOF_PIN7) | PIN_OSPEED_VERYLOW(GPIOF_PIN8) | PIN_OSPEED_VERYLOW(GPIOF_PIN9) | PIN_OSPEED_VERYLOW(GPIOF_PIN10) | PIN_OSPEED_VERYLOW(GPIOF_PIN11) | PIN_OSPEED_VERYLOW(GPIOF_PIN12) | PIN_OSPEED_VERYLOW(GPIOF_PIN13) | PIN_OSPEED_VERYLOW(GPIOF_PIN14) | PIN_OSPEED_VERYLOW(GPIOF_PIN15))
+#define VAL_GPIOF_PUPDR (PIN_PUPDR_FLOATING(GPIOF_OSC_IN) | PIN_PUPDR_FLOATING(GPIOF_OSC_OUT) | PIN_PUPDR_PULLUP(GPIOF_PIN2) | PIN_PUPDR_PULLUP(GPIOF_PIN3) | PIN_PUPDR_PULLUP(GPIOF_PIN4) | PIN_PUPDR_PULLUP(GPIOF_PIN5) | PIN_PUPDR_PULLUP(GPIOF_PIN6) | PIN_PUPDR_PULLUP(GPIOF_PIN7) | PIN_PUPDR_PULLUP(GPIOF_PIN8) | PIN_PUPDR_PULLUP(GPIOF_PIN9) | PIN_PUPDR_PULLUP(GPIOF_PIN10) | PIN_PUPDR_PULLUP(GPIOF_PIN11) | PIN_PUPDR_PULLUP(GPIOF_PIN12) | PIN_PUPDR_PULLUP(GPIOF_PIN13) | PIN_PUPDR_PULLUP(GPIOF_PIN14) | PIN_PUPDR_PULLUP(GPIOF_PIN15))
+#define VAL_GPIOF_ODR (PIN_ODR_HIGH(GPIOF_OSC_IN) | PIN_ODR_HIGH(GPIOF_OSC_OUT) | PIN_ODR_HIGH(GPIOF_PIN2) | PIN_ODR_HIGH(GPIOF_PIN3) | PIN_ODR_HIGH(GPIOF_PIN4) | PIN_ODR_HIGH(GPIOF_PIN5) | PIN_ODR_HIGH(GPIOF_PIN6) | PIN_ODR_HIGH(GPIOF_PIN7) | PIN_ODR_HIGH(GPIOF_PIN8) | PIN_ODR_HIGH(GPIOF_PIN9) | PIN_ODR_HIGH(GPIOF_PIN10) | PIN_ODR_HIGH(GPIOF_PIN11) | PIN_ODR_HIGH(GPIOF_PIN12) | PIN_ODR_HIGH(GPIOF_PIN13) | PIN_ODR_HIGH(GPIOF_PIN14) | PIN_ODR_HIGH(GPIOF_PIN15))
+#define VAL_GPIOF_AFRL (PIN_AFIO_AF(GPIOF_OSC_IN, 0U) | PIN_AFIO_AF(GPIOF_OSC_OUT, 0U) | PIN_AFIO_AF(GPIOF_PIN2, 0U) | PIN_AFIO_AF(GPIOF_PIN3, 0U) | PIN_AFIO_AF(GPIOF_PIN4, 0U) | PIN_AFIO_AF(GPIOF_PIN5, 0U) | PIN_AFIO_AF(GPIOF_PIN6, 0U) | PIN_AFIO_AF(GPIOF_PIN7, 0U))
+#define VAL_GPIOF_AFRH (PIN_AFIO_AF(GPIOF_PIN8, 0U) | PIN_AFIO_AF(GPIOF_PIN9, 0U) | PIN_AFIO_AF(GPIOF_PIN10, 0U) | PIN_AFIO_AF(GPIOF_PIN11, 0U) | PIN_AFIO_AF(GPIOF_PIN12, 0U) | PIN_AFIO_AF(GPIOF_PIN13, 0U) | PIN_AFIO_AF(GPIOF_PIN14, 0U) | PIN_AFIO_AF(GPIOF_PIN15, 0U))
+
+#if !defined(_FROM_ASM_)
+#    ifdef __cplusplus
+extern "C" {
+#    endif
+void boardInit(void);
+#    ifdef __cplusplus
+}
+#    endif
+#endif /* _FROM_ASM_ */
+
+#endif /* BOARD_H */

drivers/boards/GENERIC_STM32_F072XB/board.mk

@@ -0,0 +1,5 @@
+# List of all the board related files.
+BOARDSRC = $(BOARD_PATH)/boards/GENERIC_STM32_F072XB/board.c
+
+# Required include directories
+BOARDINC = $(BOARD_PATH)/boards/GENERIC_STM32_F072XB

drivers/boards/GENERIC_STM32_F072XB/cfg/board.chcfg

@@ -0,0 +1,703 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- STM32F0xx board Template -->
+<board
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:noNamespaceSchemaLocation="http://www.chibios.org/xml/schema/boards/stm32f0xx_board.xsd">
+  <configuration_settings>
+    <templates_path>resources/gencfg/processors/boards/stm32f0xx/templates</templates_path>
+    <output_path>..</output_path>
+    <hal_version>3.0.x</hal_version>
+  </configuration_settings>
+  <board_name>ST STM32F072B-Discovery</board_name>
+  <board_id>ST_STM32F072B_DISCOVERY</board_id>
+  <board_functions></board_functions>
+  <subtype>STM32F072xB</subtype>
+  <clocks HSEFrequency="0" HSEBypass="true" LSEFrequency="0"
+  	LSEBypass="false" LSEDrive="3 High Drive (default)" />
+  <ports>
+    <GPIOA>
+      <pin0
+        ID="BUTTON"
+        Type="PushPull"
+        Speed="Minimum"
+        Resistor="Floating"
+        Level="High"
+        Mode="Input"
+        Alternate="0" />
+      <pin1
+        ID=""
+        Type="PushPull"
+        Speed="Minimum"
+        Resistor="PullUp"
+        Level="High"
+        Mode="Input"
+        Alternate="0" />
+      <pin2
+        ID=""
+        Type="PushPull"
+        Speed="Minimum"
+        Resistor="PullUp"
+        Level="High"
+        Mode="Input"
+        Alternate="0" />
+      <pin3
+        ID=""
+        Type="PushPull"
+        Speed="Minimum"
+        Resistor="PullUp"
+        Level="High"
+        Mode="Input"
+        Alternate="0" />
+      <pin4
+        ID=""
+        Type="PushPull"
+        Speed="Minimum"
+        Resistor="PullUp"
+        Level="High"
+        Mode="Input"
+        Alternate="0" />
+      <pin5
+        ID=""
+        Type="PushPull"
+        Speed="Minimum"
+        Resistor="PullUp"
+        Level="High"
+        Mode="Input"
+        Alternate="0" />
+      <pin6
+        ID=""
+        Type="PushPull"
+        Speed="Minimum"
+        Resistor="PullUp"
+        Level="High"
+        Mode="Input"
+        Alternate="0" />
+      <pin7
+        ID=""
+        Type="PushPull"
+        Speed="Minimum"
+        Resistor="PullUp"
+        Level="High"
+        Mode="Input"
+        Alternate="0" />
+      <pin8
+        ID=""
+        Type="PushPull"
+        Speed="Minimum"
+        Resistor="PullUp"
+        Level="High"
+        Mode="Input"
+        Alternate="0" />
+      <pin9
+        ID=""
+        Type="PushPull"
+        Speed="Minimum"
+        Resistor="PullUp"
+        Level="High"
+        Mode="Input"
+        Alternate="0" />
+      <pin10
+        ID=""
+        Type="PushPull"
+        Speed="Minimum"
+        Resistor="PullUp"
+        Level="High"
+        Mode="Input"
+        Alternate="0" />
+      <pin11
+        ID="USB_DM"
+        Type="PushPull"
+        Speed="Minimum"
+        Resistor="Floating"
+        Level="High"
+        Mode="Input"
+        Alternate="0" />
+      <pin12
+        ID="USB_DP"
+        Type="PushPull"
+        Speed="Minimum"
+        Resistor="Floating"
+        Level="High"
+        Mode="Input"
+        Alternate="0" />
+      <pin13
+        ID="SWDIO"
+        Type="PushPull"
+        Speed="Maximum"
+        Resistor="PullUp"
+        Level="High"
+        Mode="Alternate"
+        Alternate="0" />
+      <pin14
+        ID="SWCLK"
+        Type="PushPull"
+        Speed="Maximum"
+        Resistor="PullDown"
+        Level="High"
+        Mode="Alternate"
+        Alternate="0" />
+      <pin15
+        ID=""
+        Type="PushPull"
+        Speed="Maximum"
+        Resistor="PullUp"
+        Level="High"
+        Mode="Input"
+        Alternate="0" />
+    </GPIOA>
+    <GPIOB>
+      <pin0
+        ID=""
+        Type="PushPull"
+        Speed="Minimum"
+        Resistor="PullUp"
+        Level="High"
+        Mode="Input"
+        Alternate="0" />
+      <pin1
+        ID=""
+        Type="PushPull"
+        Speed="Minimum"
+        Resistor="PullUp"
+        Level="High"
+        Mode="Input"
+        Alternate="0" />
+      <pin2
+        ID=""
+        Type="PushPull"
+        Speed="Maximum"
+        Resistor="PullUp"
+        Level="High"
+        Mode="Input"
+        Alternate="0" />
+      <pin3
+        ID=""
+        Type="PushPull"
+        Speed="Maximum"
+        Resistor="PullUp"
+        Level="High"
+        Mode="Input"
+        Alternate="0" />
+      <pin4
+        ID=""
+        Type="PushPull"
+        Speed="Maximum"
+        Resistor="PullUp"
+        Level="High"
+        Mode="Input"
+        Alternate="0" />
+      <pin5
+        ID=""
+        Type="PushPull"
+        Speed="Minimum"
+        Resistor="PullUp"
+        Level="High"
+        Mode="Input"
+        Alternate="0" />
+      <pin6
+        ID=""
+        Type="PushPull"
+        Speed="Minimum"
+        Resistor="PullUp"
+        Level="High"
+        Mode="Input"
+        Alternate="0" />
+      <pin7
+        ID=""
+        Type="PushPull"
+        Speed="Minimum"
+        Resistor="PullUp"
+        Level="High"
+        Mode="Input"
+        Alternate="0" />
+      <pin8
+        ID=""
+        Type="PushPull"
+        Speed="Minimum"
+        Resistor="PullUp"
+        Level="High"
+        Mode="Input"
+        Alternate="0" />
+      <pin9
+        ID=""
+        Type="PushPull"
+        Speed="Minimum"
+        Resistor="PullUp"
+        Level="High"
+        Mode="Input"
+        Alternate="0" />
+      <pin10
+        ID=""
+        Type="PushPull"
+        Speed="Minimum"
+        Resistor="PullUp"
+        Level="High"
+        Mode="Input"
+        Alternate="0" />
+      <pin11
+        ID=""
+        Type="PushPull"
+        Speed="Minimum"
+        Resistor="PullUp"
+        Level="High"
+        Mode="Input"
+        Alternate="0" />
+      <pin12
+        ID=""
+        Type="PushPull"
+        Speed="Minimum"
+        Resistor="PullUp"
+        Level="High"
+        Mode="Input"
+        Alternate="0" />
+      <pin13
+        ID="SPI2_SCK"
+        Type="PushPull"
+        Speed="Minimum"
+        Resistor="Floating"
+        Level="High"
+        Mode="Alternate"
+        Alternate="0" />
+      <pin14
+        ID="SPI2_MISO"
+        Type="PushPull"
+        Speed="Minimum"
+        Resistor="Floating"
+        Level="High"
+        Mode="Alternate"
+        Alternate="0" />
+      <pin15
+        ID="SPI2_MOSI"
+        Type="PushPull"
+        Speed="Minimum"
+        Resistor="Floating"
+        Level="High"
+        Mode="Alternate"
+        Alternate="0" />
+    </GPIOB>
+    <GPIOC>
+      <pin0
+        ID="MEMS_CS"
+        Type="PushPull"
+        Speed="Maximum"
+        Resistor="Floating"
+        Level="High"
+        Mode="Output"
+        Alternate="0" />
+      <pin1
+        ID=""
+        Type="PushPull"
+        Speed="Minimum"
+        Resistor="PullUp"
+        Level="High"
+        Mode="Input"
+        Alternate="0" />
+      <pin2
+        ID=""
+        Type="PushPull"
+        Speed="Minimum"
+        Resistor="PullUp"
+        Level="High"
+        Mode="Input"
+        Alternate="0" />
+      <pin3
+        ID=""
+        Type="PushPull"
+        Speed="Minimum"
+        Resistor="PullUp"
+        Level="High"
+        Mode="Input"
+        Alternate="0" />
+      <pin4
+        ID=""
+        Type="PushPull"
+        Speed="Minimum"
+        Resistor="PullUp"
+        Level="High"
+        Mode="Input"
+        Alternate="0" />
+      <pin5
+        ID=""
+        Type="PushPull"
+        Speed="Minimum"
+        Resistor="PullUp"
+        Level="High"
+        Mode="Input"
+        Alternate="0" />
+      <pin6
+        ID="LED_RED"
+        Type="PushPull"
+        Speed="Maximum"
+        Resistor="Floating"
+        Level="Low"
+        Mode="Output"
+        Alternate="0" />
+      <pin7
+        ID="LED_BLUE"
+        Type="PushPull"
+        Speed="Maximum"
+        Resistor="Floating"
+        Level="Low"
+        Mode="Output"
+        Alternate="0" />
+      <pin8
+        ID="LED_ORANGE"
+        Type="PushPull"
+        Speed="Maximum"
+        Resistor="Floating"
+        Level="Low"
+        Mode="Output"
+        Alternate="0" ></pin8>
+      <pin9
+        ID="LED_GREEN"
+        Type="PushPull"
+        Speed="Maximum"
+        Resistor="Floating"
+        Level="Low"
+        Mode="Output"
+        Alternate="0" />
+      <pin10
+        ID=""
+        Type="PushPull"
+        Speed="Minimum"
+        Resistor="PullUp"
+        Level="High"
+        Mode="Input"
+        Alternate="0" />
+      <pin11
+        ID=""
+        Type="PushPull"
+        Speed="Minimum"
+        Resistor="PullUp"
+        Level="High"
+        Mode="Input"
+        Alternate="0" />
+      <pin12
+        ID=""
+        Type="PushPull"
+        Speed="Minimum"
+        Resistor="PullUp"
+        Level="High"
+        Mode="Input"
+        Alternate="0" />
+      <pin13
+        ID=""
+        Type="PushPull"
+        Speed="Minimum"
+        Resistor="PullUp"
+        Level="High"
+        Mode="Input"
+        Alternate="0" />
+      <pin14
+        ID="OSC32_IN"
+        Type="PushPull"
+        Speed="Maximum"
+        Resistor="Floating"
+        Level="High"
+        Mode="Input"
+        Alternate="0" />
+      <pin15
+        ID="OSC32_OUT"
+        Type="PushPull"
+        Speed="Maximum"
+        Resistor="Floating"
+        Level="High"
+        Mode="Input"
+        Alternate="0" />
+    </GPIOC>
+    <GPIOD>
+      <pin0
+        ID=""
+        Type="PushPull"
+        Speed="Minimum"
+        Resistor="PullUp"
+        Level="High"
+        Mode="Input"
+        Alternate="0" />
+      <pin1
+        ID=""
+        Type="PushPull"
+        Speed="Minimum"
+        Resistor="PullUp"
+        Level="High"
+        Mode="Input"
+        Alternate="0" />
+      <pin2
+        ID=""
+        Type="PushPull"
+        Speed="Minimum"
+        Resistor="PullUp"
+        Level="High"
+        Mode="Input"
+        Alternate="0" />
+      <pin3
+        ID=""
+        Type="PushPull"
+        Speed="Minimum"
+        Resistor="PullUp"
+        Level="High"
+        Mode="Input"
+        Alternate="0" />
+      <pin4
+        ID=""
+        Type="PushPull"
+        Speed="Minimum"
+        Resistor="PullUp"
+        Level="High"
+        Mode="Input"
+        Alternate="0" />
+      <pin5
+        ID=""
+        Type="PushPull"
+        Speed="Minimum"
+        Resistor="PullUp"
+        Level="High"
+        Mode="Input"
+        Alternate="0" />
+      <pin6
+        ID=""
+        Type="PushPull"
+        Speed="Minimum"
+        Resistor="PullUp"
+        Level="High"
+        Mode="Input"
+        Alternate="0" />
+      <pin7
+        ID=""
+        Type="PushPull"
+        Speed="Minimum"
+        Resistor="PullUp"
+        Level="High"
+        Mode="Input"
+        Alternate="0" />
+      <pin8
+        ID=""
+        Type="PushPull"
+        Speed="Minimum"
+        Resistor="PullUp"
+        Level="High"
+        Mode="Input"
+        Alternate="0" />
+      <pin9
+        ID=""
+        Type="PushPull"
+        Speed="Minimum"
+        Resistor="PullUp"
+        Level="High"
+        Mode="Input"
+        Alternate="0" />
+      <pin10
+        ID=""
+        Type="PushPull"
+        Speed="Minimum"
+        Resistor="PullUp"
+        Level="High"
+        Mode="Input"
+        Alternate="0" />
+      <pin11
+        ID=""
+        Type="PushPull"
+        Speed="Minimum"
+        Resistor="PullUp"
+        Level="High"
+        Mode="Input"
+        Alternate="0" />
+      <pin12
+        ID=""
+        Type="PushPull"
+        Speed="Minimum"
+        Resistor="PullUp"
+        Level="High"
+        Mode="Input"
+        Alternate="0" />
+      <pin13
+        ID=""
+        Type="PushPull"
+        Speed="Minimum"
+        Resistor="PullUp"
+        Level="High"
+        Mode="Input"
+        Alternate="0" />
+      <pin14
+        ID=""
+        Type="PushPull"
+        Speed="Minimum"
+        Resistor="PullUp"
+        Level="High"
+        Mode="Input"
+        Alternate="0" />
+      <pin15
+        ID=""
+        Type="PushPull"
+        Speed="Minimum"
+        Resistor="PullUp"
+        Level="High"
+        Mode="Input"
+        Alternate="0" />
+    </GPIOD>
+    <GPIOE>
+    	<pin0 ID="" Type="PushPull" Speed="Minimum" Resistor="PullUp"
+    		Level="High" Mode="Input" Alternate="0" />
+    	<pin1 ID="" Type="PushPull" Speed="Minimum" Resistor="PullUp"
+    		Level="High" Mode="Input" Alternate="0" />
+    	<pin2 ID="" Type="PushPull" Speed="Minimum" Resistor="PullUp"
+    		Level="High" Mode="Input" Alternate="0" />
+    	<pin3 ID="" Type="PushPull" Speed="Minimum" Resistor="PullUp"
+    		Level="High" Mode="Input" Alternate="0" />
+    	<pin4 ID="" Type="PushPull" Speed="Minimum" Resistor="PullUp"
+    		Level="High" Mode="Input" Alternate="0" />
+    	<pin5 ID="" Type="PushPull" Speed="Minimum" Resistor="PullUp"
+    		Level="High" Mode="Input" Alternate="0" />
+    	<pin6 ID="" Type="PushPull" Speed="Minimum" Resistor="PullUp"
+    		Level="High" Mode="Input" Alternate="0" />
+    	<pin7 ID="" Type="PushPull" Speed="Minimum" Resistor="PullUp"
+    		Level="High" Mode="Input" Alternate="0" />
+    	<pin8 ID="" Type="PushPull" Speed="Minimum" Resistor="PullUp"
+    		Level="High" Mode="Input" Alternate="0" />
+    	<pin9 ID="" Type="PushPull" Speed="Minimum" Resistor="PullUp"
+    		Level="High" Mode="Input" Alternate="0" />
+    	<pin10 ID="" Type="PushPull" Speed="Minimum" Resistor="PullUp"
+    		Level="High" Mode="Input" Alternate="0" />
+    	<pin11 ID="" Type="PushPull" Speed="Minimum" Resistor="PullUp"
+    		Level="High" Mode="Input" Alternate="0" />
+    	<pin12 ID="" Type="PushPull" Speed="Minimum" Resistor="PullUp"
+    		Level="High" Mode="Input" Alternate="0" />
+    	<pin13 ID="" Type="PushPull" Speed="Minimum" Resistor="PullUp"
+    		Level="High" Mode="Input" Alternate="0" />
+    	<pin14 ID="" Type="PushPull" Speed="Minimum" Resistor="PullUp"
+    		Level="High" Mode="Input" Alternate="0" />
+    	<pin15 ID="" Type="PushPull" Speed="Minimum" Resistor="PullUp"
+    		Level="High" Mode="Input" Alternate="0" />
+    </GPIOE>
+    <GPIOF>
+      <pin0
+        ID="OSC_IN"
+        Type="PushPull"
+        Speed="Minimum"
+        Resistor="Floating"
+        Level="High"
+        Mode="Input"
+        Alternate="0" />
+      <pin1
+        ID="OSC_OUT"
+        Type="PushPull"
+        Speed="Minimum"
+        Resistor="Floating"
+        Level="High"
+        Mode="Input"
+        Alternate="0" />
+      <pin2
+        ID=""
+        Type="PushPull"
+        Speed="Minimum"
+        Resistor="PullUp"
+        Level="High"
+        Mode="Input"
+        Alternate="0" />
+      <pin3
+        ID=""
+        Type="PushPull"
+        Speed="Minimum"
+        Resistor="PullUp"
+        Level="High"
+        Mode="Input"
+        Alternate="0" />
+      <pin4
+        ID=""
+        Type="PushPull"
+        Speed="Minimum"
+        Resistor="PullUp"
+        Level="High"
+        Mode="Input"
+        Alternate="0" />
+      <pin5
+        ID=""
+        Type="PushPull"
+        Speed="Minimum"
+        Resistor="PullUp"
+        Level="High"
+        Mode="Input"
+        Alternate="0" />
+      <pin6
+        ID=""
+        Type="PushPull"
+        Speed="Minimum"
+        Resistor="PullUp"
+        Level="High"
+        Mode="Input"
+        Alternate="0" />
+      <pin7
+        ID=""
+        Type="PushPull"
+        Speed="Minimum"
+        Resistor="PullUp"
+        Level="High"
+        Mode="Input"
+        Alternate="0" />
+      <pin8
+        ID=""
+        Type="PushPull"
+        Speed="Minimum"
+        Resistor="PullUp"
+        Level="High"
+        Mode="Input"
+        Alternate="0" />
+      <pin9
+        ID=""
+        Type="PushPull"
+        Speed="Minimum"
+        Resistor="PullUp"
+        Level="High"
+        Mode="Input"
+        Alternate="0" />
+      <pin10
+        ID=""
+        Type="PushPull"
+        Speed="Minimum"
+        Resistor="PullUp"
+        Level="High"
+        Mode="Input"
+        Alternate="0" />
+      <pin11
+        ID=""
+        Type="PushPull"
+        Speed="Minimum"
+        Resistor="PullUp"
+        Level="High"
+        Mode="Input"
+        Alternate="0" />
+      <pin12
+        ID=""
+        Type="PushPull"
+        Speed="Minimum"
+        Resistor="PullUp"
+        Level="High"
+        Mode="Input"
+        Alternate="0" />
+      <pin13
+        ID=""
+        Type="PushPull"
+        Speed="Minimum"
+        Resistor="PullUp"
+        Level="High"
+        Mode="Input"
+        Alternate="0" />
+      <pin14
+        ID=""
+        Type="PushPull"
+        Speed="Minimum"
+        Resistor="PullUp"
+        Level="High"
+        Mode="Input"
+        Alternate="0" />
+      <pin15
+        ID=""
+        Type="PushPull"
+        Speed="Minimum"
+        Resistor="PullUp"
+        Level="High"
+        Mode="Input"
+        Alternate="0" />
+    </GPIOF>
+  </ports>
+</board>

drivers/boards/STM32_F103_STM32DUINO/board.h

@@ -24,8 +24,8 @@
 /*
  * Board identifier.
  */
-#define BOARD_GENERIC_STM32_F103
-#define BOARD_NAME              "Generic STM32F103x board"
+#define BOARD_STM32_F103_STM32DUINO
+#define BOARD_NAME              "GENERIC STM32F103C8T6 board - stm32duino bootloader"
 
 /*
  * Board frequencies.

drivers/boards/STM32_F103_STM32DUINO/board.mk

@@ -0,0 +1,5 @@
+# List of all the board related files.
+BOARDSRC = $(BOARD_PATH)/boards/STM32_F103_STM32DUINO/board.c
+
+# Required include directories
+BOARDINC = $(BOARD_PATH)/boards/STM32_F103_STM32DUINO

drivers/eeprom/eeprom_custom.c-template

@@ -0,0 +1,46 @@
+/* Copyright 2019 Nick Brassel (tzarc)
+ *
+ * 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 <stdint.h>
+#include <string.h>
+
+#include "eeprom_driver.h"
+
+void eeprom_driver_init(void) {
+    /* Any initialisation code */
+ }
+
+void eeprom_driver_erase(void) {
+    /* Wipe out the EEPROM, setting values to zero */
+}
+
+void eeprom_read_block(void *buf, const void *addr, size_t len) {
+    /*
+        Read a block of data:
+            buf: target buffer
+            addr: 0-based offset within the EEPROM
+            len: length to read
+     */
+}
+
+void eeprom_write_block(const void *buf, void *addr, size_t len) {
+    /*
+        Write a block of data:
+            buf: target buffer
+            addr: 0-based offset within the EEPROM
+            len: length to write
+     */
+}

drivers/eeprom/eeprom_driver.c

@@ -0,0 +1,73 @@
+/* Copyright 2019 Nick Brassel (tzarc)
+ *
+ * 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 <stdint.h>
+#include <string.h>
+
+#include "eeprom_driver.h"
+
+uint8_t eeprom_read_byte(const uint8_t *addr) {
+    uint8_t ret;
+    eeprom_read_block(&ret, addr, 1);
+    return ret;
+}
+
+uint16_t eeprom_read_word(const uint16_t *addr) {
+    uint16_t ret;
+    eeprom_read_block(&ret, addr, 2);
+    return ret;
+}
+
+uint32_t eeprom_read_dword(const uint32_t *addr) {
+    uint32_t ret;
+    eeprom_read_block(&ret, addr, 4);
+    return ret;
+}
+
+void eeprom_write_byte(uint8_t *addr, uint8_t value) { eeprom_write_block(&value, addr, 1); }
+
+void eeprom_write_word(uint16_t *addr, uint16_t value) { eeprom_write_block(&value, addr, 2); }
+
+void eeprom_write_dword(uint32_t *addr, uint32_t value) { eeprom_write_block(&value, addr, 4); }
+
+void eeprom_update_block(const void *buf, void *addr, size_t len) {
+    uint8_t read_buf[len];
+    eeprom_read_block(read_buf, addr, len);
+    if (memcmp(buf, read_buf, len) != 0) {
+        eeprom_write_block(buf, addr, len);
+    }
+}
+
+void eeprom_update_byte(uint8_t *addr, uint8_t value) {
+    uint8_t orig = eeprom_read_byte(addr);
+    if (orig != value) {
+        eeprom_write_byte(addr, value);
+    }
+}
+
+void eeprom_update_word(uint16_t *addr, uint16_t value) {
+    uint16_t orig = eeprom_read_word(addr);
+    if (orig != value) {
+        eeprom_write_word(addr, value);
+    }
+}
+
+void eeprom_update_dword(uint32_t *addr, uint32_t value) {
+    uint32_t orig = eeprom_read_dword(addr);
+    if (orig != value) {
+        eeprom_write_dword(addr, value);
+    }
+}

drivers/eeprom/eeprom_driver.h

@@ -0,0 +1,22 @@
+/* Copyright 2019 Nick Brassel (tzarc)
+ *
+ * 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 "eeprom.h"
+
+void eeprom_driver_init(void);
+void eeprom_driver_erase(void);

drivers/eeprom/eeprom_i2c.c

@@ -0,0 +1,120 @@
+/* Copyright 2019 Nick Brassel (tzarc)
+ *
+ * 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 <stdint.h>
+#include <string.h>
+
+/*
+    Note that the implementations of eeprom_XXXX_YYYY on AVR are normally
+    provided by avr-libc. The same functions are reimplemented below and are
+    rerouted to the external i2c equivalent.
+
+    Seemingly, as this is compiled from within QMK, the object file generated
+    during the build overrides the avr-libc implementation during the linking
+    stage.
+
+    On other platforms such as ARM, there are no provided implementations, so
+    there is nothing to override during linkage.
+*/
+
+#include "wait.h"
+#include "i2c_master.h"
+#include "eeprom.h"
+#include "eeprom_i2c.h"
+
+// #define DEBUG_EEPROM_OUTPUT
+
+#ifdef DEBUG_EEPROM_OUTPUT
+#    include "print.h"
+#endif  // DEBUG_EEPROM_OUTPUT
+
+static inline void init_i2c_if_required(void) {
+    static int done = 0;
+    if (!done) {
+        i2c_init();
+        done = 1;
+    }
+}
+
+static inline void fill_target_address(uint8_t *buffer, const void *addr) {
+    intptr_t p = (intptr_t)addr;
+    for (int i = 0; i < EXTERNAL_EEPROM_ADDRESS_SIZE; ++i) {
+        buffer[EXTERNAL_EEPROM_ADDRESS_SIZE - 1 - i] = p & 0xFF;
+        p >>= 8;
+    }
+}
+
+void eeprom_driver_init(void) {}
+
+void eeprom_driver_erase(void) {
+    uint8_t buf[EXTERNAL_EEPROM_PAGE_SIZE];
+    memset(buf, 0x00, EXTERNAL_EEPROM_PAGE_SIZE);
+    for (intptr_t addr = 0; addr < EXTERNAL_EEPROM_BYTE_COUNT; addr += EXTERNAL_EEPROM_PAGE_SIZE) {
+        eeprom_write_block(buf, (void *)addr, EXTERNAL_EEPROM_PAGE_SIZE);
+    }
+}
+
+void eeprom_read_block(void *buf, const void *addr, size_t len) {
+    uint8_t complete_packet[EXTERNAL_EEPROM_ADDRESS_SIZE];
+    fill_target_address(complete_packet, addr);
+
+    init_i2c_if_required();
+    i2c_transmit(EXTERNAL_EEPROM_I2C_ADDRESS((intptr_t)addr), complete_packet, EXTERNAL_EEPROM_ADDRESS_SIZE, 100);
+    i2c_receive(EXTERNAL_EEPROM_I2C_ADDRESS((intptr_t)addr), buf, len, 100);
+
+#ifdef DEBUG_EEPROM_OUTPUT
+    dprintf("[EEPROM R] 0x%04X: ", ((int)addr));
+    for (size_t i = 0; i < len; ++i) {
+        dprintf(" %02X", (int)(((uint8_t *)buf)[i]));
+    }
+    dprintf("\n");
+#endif  // DEBUG_EEPROM_OUTPUT
+}
+
+void eeprom_write_block(const void *buf, void *addr, size_t len) {
+    uint8_t  complete_packet[EXTERNAL_EEPROM_ADDRESS_SIZE + EXTERNAL_EEPROM_PAGE_SIZE];
+    uint8_t *read_buf    = (uint8_t *)buf;
+    intptr_t target_addr = (intptr_t)addr;
+
+    init_i2c_if_required();
+    while (len > 0) {
+        intptr_t page_offset  = target_addr % EXTERNAL_EEPROM_PAGE_SIZE;
+        int      write_length = EXTERNAL_EEPROM_PAGE_SIZE - page_offset;
+        if (write_length > len) {
+            write_length = len;
+        }
+
+        fill_target_address(complete_packet, (const void *)target_addr);
+        for (uint8_t i = 0; i < write_length; i++) {
+            complete_packet[EXTERNAL_EEPROM_ADDRESS_SIZE + i] = read_buf[i];
+        }
+
+#ifdef DEBUG_EEPROM_OUTPUT
+        dprintf("[EEPROM W] 0x%04X: ", ((int)target_addr));
+        for (uint8_t i = 0; i < write_length; i++) {
+            dprintf(" %02X", (int)(read_buf[i]));
+        }
+        dprintf("\n");
+#endif  // DEBUG_EEPROM_OUTPUT
+
+        i2c_transmit(EXTERNAL_EEPROM_I2C_ADDRESS((intptr_t)addr), complete_packet, EXTERNAL_EEPROM_ADDRESS_SIZE + write_length, 100);
+        wait_ms(EXTERNAL_EEPROM_WRITE_TIME);
+
+        read_buf += write_length;
+        target_addr += write_length;
+        len -= write_length;
+    }
+}

drivers/eeprom/eeprom_i2c.h

@@ -0,0 +1,115 @@
+/* Copyright 2019 Nick Brassel (tzarc)
+ *
+ * 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
+
+/*
+    Default device configurations:
+
+    For the Sparkfun Qwiic I2C EEPROM module: https://www.sparkfun.com/products/14764
+        #define EEPROM_I2C_CAT24C512 // (part number 24512A)
+        #define EEPROM_I2C_RM24C512C // (part number 24512C)
+
+    For the Sparkfun I2C EEPROM chip: https://www.sparkfun.com/products/525
+        #define EEPROM_I2C_24LC256
+
+    For the Adafruit I2C FRAM chip: https://www.adafruit.com/product/1895
+        #define EEPROM_I2C_MB85RC256V
+*/
+#if defined(EEPROM_I2C_CAT24C512)
+#    define EXTERNAL_EEPROM_BYTE_COUNT 65536
+#    define EXTERNAL_EEPROM_PAGE_SIZE 128
+#    define EXTERNAL_EEPROM_ADDRESS_SIZE 2
+#    define EXTERNAL_EEPROM_WRITE_TIME 5
+#elif defined(EEPROM_I2C_RM24C512C)
+#    define EXTERNAL_EEPROM_BYTE_COUNT 65536
+#    define EXTERNAL_EEPROM_PAGE_SIZE 128
+#    define EXTERNAL_EEPROM_ADDRESS_SIZE 2
+#    define EXTERNAL_EEPROM_WRITE_TIME 3
+#elif defined(EEPROM_I2C_24LC256)
+#    define EXTERNAL_EEPROM_BYTE_COUNT 32768
+#    define EXTERNAL_EEPROM_PAGE_SIZE 64
+#    define EXTERNAL_EEPROM_ADDRESS_SIZE 2
+#    define EXTERNAL_EEPROM_WRITE_TIME 5
+#elif defined(EEPROM_I2C_24LC128)
+#    define EXTERNAL_EEPROM_BYTE_COUNT 16384
+#    define EXTERNAL_EEPROM_PAGE_SIZE 64
+#    define EXTERNAL_EEPROM_ADDRESS_SIZE 2
+#    define EXTERNAL_EEPROM_WRITE_TIME 5
+#elif defined(EEPROM_I2C_MB85RC256V)
+#    define EXTERNAL_EEPROM_BYTE_COUNT 32768
+#    define EXTERNAL_EEPROM_PAGE_SIZE 128
+#    define EXTERNAL_EEPROM_ADDRESS_SIZE 2
+#    define EXTERNAL_EEPROM_WRITE_TIME 0
+#endif
+
+/*
+    The base I2C address of the EEPROM.
+    This needs to be shifted up by 1, to match i2c_master requirements.
+*/
+#ifndef EXTERNAL_EEPROM_I2C_BASE_ADDRESS
+#    define EXTERNAL_EEPROM_I2C_BASE_ADDRESS 0b10100000
+#endif
+
+/*
+    The calculated I2C address based on the input memory location.
+
+    For EEPROM chips that embed part of the memory location in the I2C address
+    such as AT24M02 you can use something similar to the following (ensuring the
+    result is shifted by left by 1):
+
+    #define EXTERNAL_EEPROM_I2C_ADDRESS(loc) \
+        (EXTERNAL_EEPROM_I2C_BASE_ADDRESS | ((((loc) >> 16) & 0x07) << 1))
+
+*/
+#ifndef EXTERNAL_EEPROM_I2C_ADDRESS
+#    define EXTERNAL_EEPROM_I2C_ADDRESS(loc) (EXTERNAL_EEPROM_I2C_BASE_ADDRESS)
+#endif
+
+/*
+    The total size of the EEPROM, in bytes. The EEPROM datasheet will usually
+    specify this value in kbits, and will require conversion to bytes.
+*/
+#ifndef EXTERNAL_EEPROM_BYTE_COUNT
+#    define EXTERNAL_EEPROM_BYTE_COUNT 8192
+#endif
+
+/*
+    The page size in bytes of the EEPROM, as specified in the datasheet.
+*/
+#ifndef EXTERNAL_EEPROM_PAGE_SIZE
+#    define EXTERNAL_EEPROM_PAGE_SIZE 32
+#endif
+
+/*
+    The address size in bytes of the EEPROM. For EEPROMs with <=256 bytes, this
+    will likely be 1. For EEPROMs >256 and <=65536, this will be 2. For EEPROMs
+    >65536, this will likely need to be 2 with the modified variant of
+    EXTERNAL_EEPROM_I2C_ADDRESS above.
+
+    As expected, consult the datasheet for specifics of your EEPROM.
+*/
+#ifndef EXTERNAL_EEPROM_ADDRESS_SIZE
+#    define EXTERNAL_EEPROM_ADDRESS_SIZE 2
+#endif
+
+/*
+    The write cycle time of the EEPROM in milliseconds, as specified in the
+    datasheet.
+*/
+#ifndef EXTERNAL_EEPROM_WRITE_TIME
+#    define EXTERNAL_EEPROM_WRITE_TIME 5
+#endif

drivers/eeprom/eeprom_transient.c

@@ -0,0 +1,52 @@
+/* Copyright 2019 Nick Brassel (tzarc)
+ *
+ * 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 <stdint.h>
+#include <string.h>
+
+#include "eeprom_driver.h"
+#include "eeprom_transient.h"
+
+__attribute__((aligned(4))) static uint8_t transientBuffer[TRANSIENT_EEPROM_SIZE] = {0};
+
+size_t clamp_length(intptr_t offset, size_t len) {
+    if (offset + len > TRANSIENT_EEPROM_SIZE) {
+        len = TRANSIENT_EEPROM_SIZE - offset;
+    }
+
+    return len;
+}
+
+void eeprom_driver_init(void) { eeprom_driver_erase(); }
+
+void eeprom_driver_erase(void) { memset(transientBuffer, 0x00, TRANSIENT_EEPROM_SIZE); }
+
+void eeprom_read_block(void *buf, const void *addr, size_t len) {
+    intptr_t offset = (intptr_t)addr;
+    memset(buf, 0x00, len);
+    len = clamp_length(offset, len);
+    if (len > 0) {
+        memcpy(buf, &transientBuffer[offset], len);
+    }
+}
+
+void eeprom_write_block(const void *buf, void *addr, size_t len) {
+    intptr_t offset = (intptr_t)addr;
+    len             = clamp_length(offset, len);
+    if (len > 0) {
+        memcpy(&transientBuffer[offset], buf, len);
+    }
+}

drivers/eeprom/eeprom_transient.h

@@ -0,0 +1,25 @@
+/* Copyright 2019 Nick Brassel (tzarc)
+ *
+ * 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
+
+/*
+    The size of the transient EEPROM buffer size.
+*/
+#ifndef TRANSIENT_EEPROM_SIZE
+#    include "eeconfig.h"
+#    define TRANSIENT_EEPROM_SIZE (((EECONFIG_SIZE + 3) / 4) * 4)  // based off eeconfig's current usage, aligned to 4-byte sizes, to deal with LTO
+#endif