Fix omnikeyish

WHAT YEAR IS IT?!

.gitignore

@@ -70,3 +70,6 @@ id_rsa_*
 
 # python things
 __pycache__
+
+# prerequisites for updating ChibiOS
+/util/fmpp*

.gitmodules

@@ -1,13 +1,15 @@
 [submodule "lib/chibios"]
 	path = lib/chibios
 	url = https://github.com/qmk/ChibiOS
+	branch = master
 [submodule "lib/chibios-contrib"]
 	path = lib/chibios-contrib
 	url = https://github.com/qmk/ChibiOS-Contrib
-	branch = k-type-fix
+	branch = master
 [submodule "lib/ugfx"]
 	path = lib/ugfx
 	url = https://github.com/qmk/uGFX
+	branch = master
 [submodule "lib/googletest"]
 	path = lib/googletest
 	url = https://github.com/google/googletest

.vscode/settings.json

@@ -5,7 +5,8 @@
     // Configure glob patterns for excluding files and folders.
     "files.exclude": {
         "**/.build": true,
-        "**/*.hex": true
+        "**/*.hex": true,
+        "**/*.bin": true
     },
     "files.associations": {
       "*.h": "c",

Makefile

@@ -623,13 +623,19 @@ endif
 # Generate the version.h file
 ifndef SKIP_GIT
     GIT_VERSION := $(shell git describe --abbrev=6 --dirty --always --tags 2>/dev/null || date +"%Y-%m-%d-%H:%M:%S")
+    CHIBIOS_VERSION := $(shell cd lib/chibios && git describe --abbrev=6 --dirty --always --tags 2>/dev/null || date +"%Y-%m-%d-%H:%M:%S")
+    CHIBIOS_CONTRIB_VERSION := $(shell cd lib/chibios-contrib && git describe --abbrev=6 --dirty --always --tags 2>/dev/null || date +"%Y-%m-%d-%H:%M:%S")
 else
     GIT_VERSION := NA
+    CHIBIOS_VERSION := NA
+    CHIBIOS_CONTRIB_VERSION := NA
 endif
 ifndef SKIP_VERSION
 BUILD_DATE := $(shell date +"%Y-%m-%d-%H:%M:%S")
 $(shell echo '#define QMK_VERSION "$(GIT_VERSION)"' > $(ROOT_DIR)/quantum/version.h)
 $(shell echo '#define QMK_BUILDDATE "$(BUILD_DATE)"' >> $(ROOT_DIR)/quantum/version.h)
+$(shell echo '#define CHIBIOS_VERSION "$(CHIBIOS_VERSION)"' >> $(ROOT_DIR)/quantum/version.h)
+$(shell echo '#define CHIBIOS_CONTRIB_VERSION "$(CHIBIOS_CONTRIB_VERSION)"' >> $(ROOT_DIR)/quantum/version.h)
 else
 BUILD_DATE := NA
 endif

common_features.mk

@@ -298,6 +298,7 @@ VALID_BACKLIGHT_TYPES := pwm software custom
 BACKLIGHT_ENABLE ?= no
 BACKLIGHT_DRIVER ?= pwm
 ifeq ($(strip $(BACKLIGHT_ENABLE)), yes)
+    SRC += $(QUANTUM_DIR)/process_keycode/process_backlight.c
     ifeq ($(filter $(BACKLIGHT_DRIVER),$(VALID_BACKLIGHT_TYPES)),)
         $(error BACKLIGHT_DRIVER="$(BACKLIGHT_DRIVER)" is not a valid backlight type)
     endif

docs/ChangeLog/20200229.md

@@ -0,0 +1,75 @@
+# QMK Breaking Change - 2020 Feb 29 Changelog
+
+Four times a year QMK runs a process for merging Breaking Changes. A Breaking Change is any change which modifies how QMK behaves in a way that is incompatible or potentially dangerous. We limit these changes to 4 times per year so that users can have confidence that updating their QMK tree will not break their keymaps.
+
+
+## Update ChibiOS/ChibiOS-Contrib/uGFX submodules
+
+* General Notes
+    * A `make git-submodule` may be required after pulling the latest QMK firmware code to update affected submodules to the upgraded revisions
+    * Enabling link-time-optimization (`LINK_TIME_OPTIMIZATION_ENABLE = yes`) should work on a lot more boards
+* Upgrade to ChibiOS ver19.1.3
+    * This will allow QMK to update to upstream ChibiOS a lot easier -- the old version was ~2 years out of date. Automated update scripts have been made available to simplify future upgrades.
+    * Includes improved MCU support and bugfixes
+    * ChibiOS revision is now included in Command output
+    * Timers should now be more accurate
+* Upgrade to newer ChibiOS-Contrib
+    * Also includes improved MCU support and bugfixes
+    * ChibiOS-Contrib revision is now included in Command output
+* Upgrade to newer uGFX
+    * Required in order to support updated ChibiOS
+
+
+## Fix ChibiOS timer overflow for 16-bit SysTick devices
+
+* On 16-bit SysTick devices, the timer subsystem in QMK was incorrectly dealing with overflow.
+    * When running at a 100000 SysTick frequency (possible on 16-bit devices, but uncommon), this overflow would occur after 0.65 seconds.
+* Timers are now correctly handling this overflow case and timing should now be correct on ChibiOS/ARM.
+
+
+## Update LUFA submodule
+
+* Updates the LUFA submodule to include updates from upstream (abcminiuser/lufa)
+* Includes some cleanup for QMK DFU generation
+
+
+## Encoder flip
+
+* Flips the encoder direction so that `clockwise == true` is for actually turning the knob clockwise
+* Adds `ENCODER_DIRECTION_FLIP` define, so that reversing the expected dirction is simple for users.
+* Cleans up documentation page for encoders
+
+
+## Adding support for `BACKLIGHT_ON_STATE` for hardware PWM backlight
+
+* Previously, the define only affected software PWM, and hardware PWM always assumed an N-channel MOSFET.
+* The hardware PWM backlight setup has been updated to respect this option.
+* The default "on" state has been changed to `1` - **this impacts all keyboards using software PWM backlight that do not define it explicitly**. If your keyboard's backlight is acting strange, it may have a P-channel MOSFET, and will need to have `#define BACKLIGHT_ON_STATE 0` added to the keyboard-level `config.h`. Please see the PR for more detailed information.
+
+
+## Migrating `ACTION_LAYER_TAP_KEY()` entries in `fn_actions` to `LT()` keycodes
+
+* `fn_actions` is deprecated, and its functionality has been superseded by direct keycodes and `process_record_user()`
+* The end result of removing this obsolete feature should result in a decent reduction in firmware size and code complexity
+* All keymaps affected are recommended to switch away from `fn_actions` in favour of the [custom keycode](https://docs.qmk.fm/#/custom_quantum_functions) and [macro](https://docs.qmk.fm/#/feature_macros) features
+
+
+## Moving backlight keycode handling to `process_keycode/`
+
+* This refactors the backlight keycode logic to be clearer and more modular.
+* All backlight-related keycodes are now actioned in a single file.
+* The `ACTION_BACKLIGHT_*` macros have also been deleted. If you are still using these in a `fn_actions[]` block, please switch to using the backlight keycodes or functions directly.
+
+
+## Refactor Planck keymaps to use Layout Macros
+
+* Refactor Planck keymaps to use layout macros instead of raw matrix assignments
+* Makes keymaps revision-agnostic
+* Should reduce noise and errors in Travis CI logs
+
+
+## GON NerD codebase refactor
+
+* Splits the codebase for GON NerD 60 and NerdD TKL PCBs into two separate directories.
+* If your keymap is for a NerD 60 PCB, your `make` command is now `make gon/nerd60:<keymap>`.
+* If your keymap is for a NerD TKL PCB, your `make` command is now `make gon/nerdtkl:<keymap>`.

docs/breaking_changes.md

@@ -6,20 +6,21 @@ The breaking change period is when we will merge PR's that change QMK in dangero
 
 ## What has been included in past Breaking Changes?
 
+* [2020 Feb 29](ChangeLog/20200229.md)
 * [2019 Aug 30](ChangeLog/20190830.md)
 
 ## When is the next Breaking Change?
 
-The next Breaking Change is scheduled for February 29, 2020.
+The next Breaking Change is scheduled for May 30, 2020.
 
 ### Important Dates
 
-* [x] 2019 Sep 21 - `future` is created. It will be rebased weekly.
-* [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.
+* [x] 2020 Feb 29 - `future` is created. It will be rebased weekly.
+* [ ] 2020 May 2 - `future` closed to new PR's.
+* [ ] 2020 May 2 - Call for testers.
+* [ ] 2020 May 28 - `master` is locked, no PR's merged.
+* [ ] 2020 May 30 - Merge `future` to `master`.
+* [ ] 2020 May 30 - `master` is unlocked. PR's can be merged again.
 
 ## What changes will be included?
 

docs/cli.md

@@ -71,14 +71,36 @@ There are some limitations to the local CLI compared to the global CLI:
 
 ## `qmk cformat`
 
-This command formats C code using clang-format. Run it with no arguments to format all core code, or pass filenames on the command line to run it on specific files.
+This command formats C code using clang-format. 
 
-**Usage**:
+Run it with no arguments to format all core code that has been changed. Default checks `origin/master` with `git diff`, branch can be changed using `-b <branch_name>`
+
+Run it with `-a` to format all core code, or pass filenames on the command line to run it on specific files.
+
+**Usage for specified files**:
 
 ```
 qmk cformat [file1] [file2] [...] [fileN]
 ```
 
+**Usage for all core files**:
+
+```
+qmk cformat -a
+```
+
+**Usage for only changed files against origin/master**:
+
+```
+qmk cformat
+```
+
+**Usage for only changed files against branch_name**:
+
+```
+qmk cformat -b branch_name
+```
+
 ## `qmk compile`
 
 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.
@@ -252,6 +274,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/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`
@@ -140,6 +142,8 @@ If you define these options you will enable the associated feature, which may in
 * `#define PERMISSIVE_HOLD`
   * makes tap and hold keys trigger the hold if another key is pressed before releasing, even if it hasn't hit the `TAPPING_TERM`
   * See [Permissive Hold](feature_advanced_keycodes.md#permissive-hold) for details
+* `#define PERMISSIVE_HOLD_PER_KEY`
+  * enabled handling for per key `PERMISSIVE_HOLD` settings
 * `#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

docs/feature_advanced_keycodes.md

@@ -265,6 +265,25 @@ Normally, if you do all this within the `TAPPING_TERM` (default: 200ms) this wil
 
 ?> If you have `Ignore Mod Tap Interrupt` 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 PERMISSIVE_HOLD_PER_KEY
+```
+
+You can then add the following function to your keymap:
+
+```c
+bool get_permissive_hold(uint16_t keycode, keyrecord_t *record) {
+  switch (keycode) {
+    case SFT_T(KC_A):
+      return true;
+    default:
+      return false;
+  }
+}
+```
+
 ## Ignore Mod Tap Interrupt
 
 To enable this setting, add this to your `config.h`:

docs/feature_backlight.md

@@ -119,10 +119,22 @@ When both timers are in use for Audio, the backlight PWM will not use a hardware
 
 To change the behavior of the backlighting, `#define` these in your `config.h`:
 
-|Define               |Default      |Description                                                                                                   |
-|---------------------|-------------|--------------------------------------------------------------------------------------------------------------|
-|`BACKLIGHT_PIN`      |`B7`         |The pin that controls the LEDs. Unless you are designing your own keyboard, you shouldn't need to change this |
-|`BACKLIGHT_PINS`     |*Not defined*|experimental: see below for more information                                                                  |
+|Define               |Default      |Description                                                                                                  |
+|---------------------|-------------|-------------------------------------------------------------------------------------------------------------|
+|`BACKLIGHT_PIN`      |`B7`         |The pin that controls the LEDs. Unless you are designing your own keyboard, you shouldn't need to change this|
+|`BACKLIGHT_PINS`     |*Not defined*|experimental: see below for more information                                                                 |
+|`BACKLIGHT_LEVELS`   |`3`          |The number of brightness levels (maximum 31 excluding off)                                                   |
+|`BACKLIGHT_CAPS_LOCK`|*Not defined*|Enable Caps Lock indicator using backlight (for keyboards without dedicated LED)                             |
+|`BACKLIGHT_BREATHING`|*Not defined*|Enable backlight breathing, if supported                                                                     |
+|`BREATHING_PERIOD`   |`6`          |The length of one backlight "breath" in seconds                                                              |
+|`BACKLIGHT_ON_STATE` |`1`          |The state of the backlight pin when the backlight is "on" - `1` for high, `0` for low                        |
+
+### Backlight On State
+
+Most backlight circuits are driven by an N-channel MOSFET or NPN transistor. This means that to turn the transistor *on* and light the LEDs, you must drive the backlight pin, connected to the gate or base, *high*.
+Sometimes, however, a P-channel MOSFET, or a PNP transistor is used. In this case, when the transistor is on, the pin is driven *low* instead.
+
+This functionality is configured at the keyboard level with the `BACKLIGHT_ON_STATE` define.
 
 ### Multiple backlight pins
 
@@ -167,7 +179,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_encoders.md

@@ -2,23 +2,35 @@
 
 Basic encoders are supported by adding this to your `rules.mk`:
 
-    ENCODER_ENABLE = yes
+```make
+ENCODER_ENABLE = yes
+```
 
 and this to your `config.h`:
 
-    #define ENCODERS_PAD_A { B12 }
-    #define ENCODERS_PAD_B { B13 }
+```c
+#define ENCODERS_PAD_A { B12 }
+#define ENCODERS_PAD_B { B13 }
+```
 
 Each PAD_A/B variable defines an array so multiple encoders can be defined, e.g.:
 
-    #define ENCODERS_PAD_A { encoder1a, encoder2a }
-    #define ENCODERS_PAD_B { encoder1b, encoder2b }
+```c
+#define ENCODERS_PAD_A { encoder1a, encoder2a }
+#define ENCODERS_PAD_B { encoder1b, encoder2b }
+```
 
-If your encoder's clockwise directions are incorrect, you can swap the A & B pad definitions.
+If your encoder's clockwise directions are incorrect, you can swap the A & B pad definitions.  They can also be flipped with a define:
+
+```c
+#define ENCODER_DIRECTION_FLIP
+```
 
 Additionally, the resolution can be specified in the same file (the default & suggested is 4):
 
-    #define ENCODER_RESOLUTION 4
+```c
+#define ENCODER_RESOLUTION 4
+```
 
 ## Split Keyboards
 
@@ -33,27 +45,31 @@ If you are using different pinouts for the encoders on each half of a split keyb
 
 The callback functions can be inserted into your `<keyboard>.c`:
 
-    void encoder_update_kb(uint8_t index, bool clockwise) {
-        encoder_update_user(index, clockwise);
-    }
+```c
+void encoder_update_kb(uint8_t index, bool clockwise) {
+    encoder_update_user(index, clockwise);
+}
+```
 
 or `keymap.c`:
 
-    void encoder_update_user(uint8_t index, bool clockwise) {
-      if (index == 0) { /* First encoder */
+```c
+void encoder_update_user(uint8_t index, bool clockwise) {
+    if (index == 0) { /* First encoder */
         if (clockwise) {
-          tap_code(KC_PGDN);
+            tap_code(KC_PGDN);
         } else {
-          tap_code(KC_PGUP);
+            tap_code(KC_PGUP);
         }
-      } else if (index == 1) { /* Second encoder */  
+        } else if (index == 1) { /* Second encoder */  
         if (clockwise) {
-          tap_code(KC_UP);
+            tap_code(KC_DOWN);
         } else {
-          tap_code(KC_DOWN);
+            tap_code(KC_UP);
         }
-      }
     }
+}
+```
 
 ## Hardware
 

docs/feature_macros.md

@@ -107,6 +107,16 @@ Would tap `KC_HOME` - note how the prefix is now `X_`, and not `KC_`. You can al
 
 Which would send "VE" followed by a `KC_HOME` tap, and "LO" (spelling "LOVE" if on a newline).
 
+Delays can be also added to the string:
+
+* `SS_DELAY(msecs)` will delay for the specified number of milliseconds.
+
+For example:
+
+    SEND_STRING("VE" SS_DELAY(1000) SS_TAP(X_HOME) "LO");
+
+Which would send "VE" followed by a 1-second delay, then a `KC_HOME` tap, and "LO" (spelling "LOVE" if on a newline, but delayed in the middle).
+
 There's also a couple of mod shortcuts you can use:
 
 * `SS_LCTL(string)`
@@ -154,6 +164,8 @@ SEND_STRING(".."SS_TAP(X_END));
 
 There are some functions you may find useful in macro-writing. Keep in mind that while you can write some fairly advanced code within a macro, if your functionality gets too complex you may want to define a custom keycode instead. Macros are meant to be simple.
 
+?> You can also use the functions described in [Useful function](ref_functions.md) for additional functionality. For example `reset_keyboard()` allows you to reset the keyboard as part of a macro.
+
 ### `record->event.pressed`
 
 This is a boolean value that can be tested to see if the switch is being pressed or released. An example of this is
@@ -198,11 +210,11 @@ This will clear all mods currently pressed.
 
 This will clear all keys besides the mods currently pressed.
 
-## Advanced Example: 
+## Advanced Example:
 
 ### Super ALT↯TAB
 
-This macro will register `KC_LALT` and tap `KC_TAB`, then wait for 1000ms. If the key is tapped again, it will send another `KC_TAB`; if there is no tap, `KC_LALT` will be unregistered, thus allowing you to cycle through windows. 
+This macro will register `KC_LALT` and tap `KC_TAB`, then wait for 1000ms. If the key is tapped again, it will send another `KC_TAB`; if there is no tap, `KC_LALT` will be unregistered, thus allowing you to cycle through windows.
 
 ```c
 bool is_alt_tab_active = false;    # ADD this near the begining of keymap.c
@@ -219,7 +231,7 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) {
         if (!is_alt_tab_active) {
           is_alt_tab_active = true;
           register_code(KC_LALT);
-        } 
+        }
         alt_tab_timer = timer_read();
         register_code(KC_TAB);
       } else {
@@ -230,7 +242,7 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) {
   return true;
 }
 
-void matrix_scan_user(void) {     # The very important timer. 
+void matrix_scan_user(void) {     # The very important timer.
   if (is_alt_tab_active) {
     if (timer_elapsed(alt_tab_timer) > 1000) {
       unregister_code(KC_LALT);
@@ -319,7 +331,7 @@ const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
 ```
 
 
-## Advanced Example: 
+## Advanced Example:
 
 ### Single-Key Copy/Paste
 

docs/feature_oled_driver.md

@@ -104,7 +104,7 @@ void oled_task_user(void) {
 |`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_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.           |

docs/feature_unicode.md

@@ -193,12 +193,23 @@ By default, when the keyboard boots, it will initialize the input mode to the la
 
 !> Using `UNICODE_SELECTED_MODES` means you don't have to initially set the input mode in `matrix_init_user()` (or a similar function); the Unicode system will do that for you on startup. This has the added benefit of avoiding unnecessary writes to EEPROM.
 
-## `send_unicode_hex_string`
+## `send_unicode_string()`
 
-To type multiple characters for things like (ノಠ痊ಠ)ノ彡┻━┻, you can use `send_unicode_hex_string()` much like `SEND_STRING()` except you would use hex values separate by spaces.
-For example, the table flip seen above would be `send_unicode_hex_string("0028 30CE 0CA0 75CA 0CA0 0029 30CE 5F61 253B 2501 253B")`
+This function is much like `send_string()` but allows you to input UTF-8 characters directly, and supports all code points (provided the selected input method also supports it). Make sure your `keymap.c` is formatted in UTF-8 encoding.
 
-There are many ways to get a hex code, but an easy one is [this site](https://r12a.github.io/app-conversion/). Just make sure to convert to hexadecimal, and that is your string.
+```c
+send_unicode_string("(ノಠ痊ಠ)ノ彡┻━┻");
+```
+
+## `send_unicode_hex_string()`
+
+Similar to `send_unicode_string()`, but the characters are represented by their code point values in ASCII, separated by spaces. For example, the table flip above would be achieved with:
+
+```c
+send_unicode_hex_string("0028 30CE 0CA0 75CA 0CA0 0029 30CE 5F61 253B 2501 253B");
+```
+
+An easy way to convert your Unicode string to this format is by using [this site](https://r12a.github.io/app-conversion/), and taking the result in the "Hex/UTF-32" section.
 
 ## Additional Language Support
 
@@ -228,6 +239,6 @@ AutoHotkey inserts the Text right of `Send, ` when this combination is pressed.
 
 If you enable the US International layout on the system, it will use punctuation to accent the characters.
 
-For instance, typing "`a" will result in à.
+For instance, typing "\`a" will result in à.
 
 You can find details on how to enable this [here](https://support.microsoft.com/en-us/help/17424/windows-change-keyboard-layout).

docs/ja/cli.md

@@ -1,8 +1,8 @@
 # QMK CLI
 
 <!---
-  original document: d598f01cb:docs/cli.md
-  git diff d598f01cb HEAD -- docs/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/config_options.md

@@ -1,8 +1,8 @@
 # QMK の設定
 
 <!---
-  original document: 9ff61601e:docs/config_options.md
-  git diff 9ff61601e 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`
@@ -274,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 に関する情報を設定するために使われます。

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_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/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/ws2812_driver.md

@@ -15,7 +15,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      |                    | :heavy_check_mark: |
-| PWM      |                    | Soon™              |
+| PWM      |                    | :heavy_check_mark: |
 
 ## Driver configuration
 
@@ -66,4 +66,36 @@ While not an exhaustive list, the following table provides the scenarios that ha
 | 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.*
+*Other supported ChibiOS boards and/or pins may function, it will be highly chip and configuration dependent.*
+
+### PWM
+
+Targeting STM32 boards where WS2812 support is offloaded to an PWM timer and DMA stream. The advantage is that the use of DMA offloads processing of the WS2812 protocol from the MCU. To configure it, add this to your rules.mk:
+
+```make
+WS2812_DRIVER = pwm
+```
+
+Configure the hardware via your config.h:
+```c
+#define WS2812_PWM_DRIVER PWMD2  // default: PWMD2
+#define WS2812_PWM_CHANNEL 2  // default: 2
+#define WS2812_PWM_PAL_MODE 2  // Pin "alternate function", see the respective datasheet for the appropriate values for your MCU. default: 2
+#define WS2812_DMA_STREAM STM32_DMA1_STREAM2  // DMA Stream for TIMx_UP, see the respective reference manual for the appropriate values for your MCU.
+#define WS2812_DMA_CHANNEL 2  // DMA Channel for TIMx_UP, see the respective reference manual for the appropriate values for your MCU.
+```
+
+You must also turn on the PWM 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:
+
+| | Status |
+|-|-|
+| f072 | ? |
+| f103 | :heavy_check_mark: |
+| f303 | :heavy_check_mark: |
+| f401/f411 | :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)-->

drivers/arm/i2c_master.c

@@ -29,6 +29,8 @@
 #include <string.h>
 #include <hal.h>
 
+static uint8_t i2c_address;
+
 static const I2CConfig i2cconfig = {
 #ifdef USE_I2CV1
     I2C1_OPMODE,
@@ -69,49 +71,27 @@ __attribute__((weak)) void i2c_init(void) {
 }
 
 i2c_status_t i2c_start(uint8_t address) {
-#if I2C_USE_MUTUAL_EXCLUSION
-    i2cAcquireBus(&I2C_DRIVER);
-#endif
-
+    i2c_address = address;
     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) {
-#if I2C_USE_MUTUAL_EXCLUSION
-    i2cAcquireBus(&I2C_DRIVER);
-#endif
-
+    i2c_address = address;
     i2cStart(&I2C_DRIVER, &i2cconfig);
-    msg_t status = i2cMasterTransmitTimeout(&I2C_DRIVER, (address >> 1), data, length, 0, 0, MS2ST(timeout));
-
-#if I2C_USE_MUTUAL_EXCLUSION
-    i2cReleaseBus(&I2C_DRIVER);
-#endif
-
+    msg_t status = i2cMasterTransmitTimeout(&I2C_DRIVER, (i2c_address >> 1), data, length, 0, 0, TIME_MS2I(timeout));
     return chibios_to_qmk(&status);
 }
 
 i2c_status_t i2c_receive(uint8_t address, uint8_t* data, uint16_t length, uint16_t timeout) {
-#if I2C_USE_MUTUAL_EXCLUSION
-    i2cAcquireBus(&I2C_DRIVER);
-#endif
-
+    i2c_address = address;
     i2cStart(&I2C_DRIVER, &i2cconfig);
-    msg_t status = i2cMasterReceiveTimeout(&I2C_DRIVER, (address >> 1), data, length, MS2ST(timeout));
-
-#if I2C_USE_MUTUAL_EXCLUSION
-    i2cReleaseBus(&I2C_DRIVER);
-#endif
-
+    msg_t status = i2cMasterReceiveTimeout(&I2C_DRIVER, (i2c_address >> 1), data, length, TIME_MS2I(timeout));
     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) {
-#if I2C_USE_MUTUAL_EXCLUSION
-    i2cAcquireBus(&I2C_DRIVER);
-#endif
-
+    i2c_address = devaddr;
     i2cStart(&I2C_DRIVER, &i2cconfig);
 
     uint8_t complete_packet[length + 1];
@@ -120,34 +100,15 @@ 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, (devaddr >> 1), complete_packet, length + 1, 0, 0, MS2ST(timeout));
-
-#if I2C_USE_MUTUAL_EXCLUSION
-    i2cReleaseBus(&I2C_DRIVER);
-#endif
-
+    msg_t status = i2cMasterTransmitTimeout(&I2C_DRIVER, (i2c_address >> 1), complete_packet, length + 1, 0, 0, TIME_MS2I(timeout));
     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) {
-#if I2C_USE_MUTUAL_EXCLUSION
-    i2cAcquireBus(&I2C_DRIVER);
-#endif
-
+    i2c_address = devaddr;
     i2cStart(&I2C_DRIVER, &i2cconfig);
-    msg_t status = i2cMasterTransmitTimeout(&I2C_DRIVER, (devaddr >> 1), &regaddr, 1, data, length, MS2ST(timeout));
-
-#if I2C_USE_MUTUAL_EXCLUSION
-    i2cReleaseBus(&I2C_DRIVER);
-#endif
-
+    msg_t status = i2cMasterTransmitTimeout(&I2C_DRIVER, (i2c_address >> 1), &regaddr, 1, data, length, TIME_MS2I(timeout));
     return chibios_to_qmk(&status);
 }
 
-void i2c_stop(void) {
-    i2cStop(&I2C_DRIVER);
-
-#if I2C_USE_MUTUAL_EXCLUSION
-    i2cReleaseBus(&I2C_DRIVER);
-#endif
-}
+void i2c_stop(void) { i2cStop(&I2C_DRIVER); }

drivers/arm/ws2812_pwm.c

@@ -1 +1,207 @@
-#error("NOT SUPPORTED")
+#include "ws2812.h"
+#include "quantum.h"
+#include "hal.h"
+
+/* Adapted from https://github.com/joewa/WS2812-LED-Driver_ChibiOS/ */
+
+#ifdef RGBW
+#    error "RGBW not supported"
+#endif
+
+#ifndef WS2812_PWM_DRIVER
+#    define WS2812_PWM_DRIVER PWMD2  // TIMx
+#endif
+#ifndef WS2812_PWM_CHANNEL
+#    define WS2812_PWM_CHANNEL 2  // Channel
+#endif
+#ifndef WS2812_PWM_PAL_MODE
+#    define WS2812_PWM_PAL_MODE 2  // DI Pin's alternate function value
+#endif
+#ifndef WS2812_DMA_STREAM
+#    define WS2812_DMA_STREAM STM32_DMA1_STREAM2  // DMA Stream for TIMx_UP
+#endif
+#ifndef WS2812_DMA_CHANNEL
+#    define WS2812_DMA_CHANNEL 2  // DMA Channel for TIMx_UP
+#endif
+
+#ifndef WS2812_PWM_TARGET_PERIOD
+//#    define WS2812_PWM_TARGET_PERIOD 800000 // Original code is 800k...?
+#    define WS2812_PWM_TARGET_PERIOD 80000  // TODO: work out why 10x less on f303/f4x1
+#endif
+
+/* --- PRIVATE CONSTANTS ---------------------------------------------------- */
+
+#define WS2812_PWM_FREQUENCY (STM32_SYSCLK / 2)                             /**< Clock frequency of PWM, must be valid with respect to system clock! */
+#define WS2812_PWM_PERIOD (WS2812_PWM_FREQUENCY / WS2812_PWM_TARGET_PERIOD) /**< Clock period in ticks. 1 / 800kHz = 1.25 uS (as per datasheet) */
+
+/**
+ * @brief   Number of bit-periods to hold the data line low at the end of a frame
+ *
+ * The reset period for each frame must be at least 50 uS; so we add in 50 bit-times
+ * of zeroes at the end. (50 bits)*(1.25 uS/bit) = 62.5 uS, which gives us some
+ * slack in the timing requirements
+ */
+#define WS2812_RESET_BIT_N (50)
+#define WS2812_COLOR_BIT_N (RGBLED_NUM * 24)                   /**< Number of data bits */
+#define WS2812_BIT_N (WS2812_COLOR_BIT_N + WS2812_RESET_BIT_N) /**< Total number of bits in a frame */
+
+/**
+ * @brief   High period for a zero, in ticks
+ *
+ * Per the datasheet:
+ * WS2812:
+ * - T0H: 200 nS to 500 nS, inclusive
+ * - T0L: 650 nS to 950 nS, inclusive
+ * WS2812B:
+ * - T0H: 200 nS to 500 nS, inclusive
+ * - T0L: 750 nS to 1050 nS, inclusive
+ *
+ * The duty cycle is calculated for a high period of 350 nS.
+ */
+#define WS2812_DUTYCYCLE_0 (WS2812_PWM_FREQUENCY / (1000000000 / 350))
+
+/**
+ * @brief   High period for a one, in ticks
+ *
+ * Per the datasheet:
+ * WS2812:
+ * - T1H: 550 nS to 850 nS, inclusive
+ * - T1L: 450 nS to 750 nS, inclusive
+ * WS2812B:
+ * - T1H: 750 nS to 1050 nS, inclusive
+ * - T1L: 200 nS to 500 nS, inclusive
+ *
+ * The duty cycle is calculated for a high period of 800 nS.
+ * This is in the middle of the specifications of the WS2812 and WS2812B.
+ */
+#define WS2812_DUTYCYCLE_1 (WS2812_PWM_FREQUENCY / (1000000000 / 800))
+
+/* --- PRIVATE MACROS ------------------------------------------------------- */
+
+/**
+ * @brief   Determine the index in @ref ws2812_frame_buffer "the frame buffer" of a given bit
+ *
+ * @param[in] led:                  The led index [0, @ref RGBLED_NUM)
+ * @param[in] byte:                 The byte number [0, 2]
+ * @param[in] bit:                  The bit number [0, 7]
+ *
+ * @return                          The bit index
+ */
+#define WS2812_BIT(led, byte, bit) (24 * (led) + 8 * (byte) + (7 - (bit)))
+
+/**
+ * @brief   Determine the index in @ref ws2812_frame_buffer "the frame buffer" of a given red bit
+ *
+ * @note    The red byte is the middle byte in the color packet
+ *
+ * @param[in] led:                  The led index [0, @ref RGBLED_NUM)
+ * @param[in] bit:                  The bit number [0, 7]
+ *
+ * @return                          The bit index
+ */
+#define WS2812_RED_BIT(led, bit) WS2812_BIT((led), 1, (bit))
+
+/**
+ * @brief   Determine the index in @ref ws2812_frame_buffer "the frame buffer" of a given green bit
+ *
+ * @note    The red byte is the first byte in the color packet
+ *
+ * @param[in] led:                  The led index [0, @ref RGBLED_NUM)
+ * @param[in] bit:                  The bit number [0, 7]
+ *
+ * @return                          The bit index
+ */
+#define WS2812_GREEN_BIT(led, bit) WS2812_BIT((led), 0, (bit))
+
+/**
+ * @brief   Determine the index in @ref ws2812_frame_buffer "the frame buffer" of a given blue bit
+ *
+ * @note    The red byte is the last byte in the color packet
+ *
+ * @param[in] led:                  The led index [0, @ref RGBLED_NUM)
+ * @param[in] bit:                  The bit index [0, 7]
+ *
+ * @return                          The bit index
+ */
+#define WS2812_BLUE_BIT(led, bit) WS2812_BIT((led), 2, (bit))
+
+/* --- PRIVATE VARIABLES ---------------------------------------------------- */
+
+static uint32_t ws2812_frame_buffer[WS2812_BIT_N + 1]; /**< Buffer for a frame */
+
+/* --- PUBLIC FUNCTIONS ----------------------------------------------------- */
+/*
+ * Gedanke: Double-buffer type transactions: double buffer transfers using two memory pointers for
+the memory (while the DMA is reading/writing from/to a buffer, the application can
+write/read to/from the other buffer).
+ */
+
+void ws2812_init(void) {
+    // Initialize led frame buffer
+    uint32_t i;
+    for (i = 0; i < WS2812_COLOR_BIT_N; i++) ws2812_frame_buffer[i] = WS2812_DUTYCYCLE_0;      // All color bits are zero duty cycle
+    for (i = 0; i < WS2812_RESET_BIT_N; i++) ws2812_frame_buffer[i + WS2812_COLOR_BIT_N] = 0;  // All reset bits are zero
+
+#if defined(USE_GPIOV1)
+    palSetLineMode(RGB_DI_PIN, PAL_MODE_STM32_ALTERNATE_PUSHPULL);
+#else
+    palSetLineMode(RGB_DI_PIN, PAL_MODE_ALTERNATE(WS2812_PWM_PAL_MODE) | PAL_STM32_OSPEED_HIGHEST | PAL_STM32_PUPDR_FLOATING);
+#endif
+
+    // PWM Configuration
+    //#pragma GCC diagnostic ignored "-Woverride-init"  // Turn off override-init warning for this struct. We use the overriding ability to set a "default" channel config
+    static const PWMConfig ws2812_pwm_config = {
+        .frequency = WS2812_PWM_FREQUENCY,
+        .period    = WS2812_PWM_PERIOD,  // Mit dieser Periode wird UDE-Event erzeugt und ein neuer Wert (Länge WS2812_BIT_N) vom DMA ins CCR geschrieben
+        .callback  = NULL,
+        .channels =
+            {
+                [0 ... 3]                = {.mode = PWM_OUTPUT_DISABLED, .callback = NULL},     // Channels default to disabled
+                [WS2812_PWM_CHANNEL - 1] = {.mode = PWM_OUTPUT_ACTIVE_HIGH, .callback = NULL},  // Turn on the channel we care about
+            },
+        .cr2  = 0,
+        .dier = TIM_DIER_UDE,  // DMA on update event for next period
+    };
+    //#pragma GCC diagnostic pop  // Restore command-line warning options
+
+    // Configure DMA
+    // dmaInit(); // Joe added this
+    dmaStreamAlloc(WS2812_DMA_STREAM - STM32_DMA1_STREAM1, 10, NULL, NULL);
+    dmaStreamSetPeripheral(WS2812_DMA_STREAM, &(WS2812_PWM_DRIVER.tim->CCR[WS2812_PWM_CHANNEL - 1]));  // Ziel ist der An-Zeit im Cap-Comp-Register
+    dmaStreamSetMemory0(WS2812_DMA_STREAM, ws2812_frame_buffer);
+    dmaStreamSetTransactionSize(WS2812_DMA_STREAM, WS2812_BIT_N);
+    dmaStreamSetMode(WS2812_DMA_STREAM, STM32_DMA_CR_CHSEL(WS2812_DMA_CHANNEL) | STM32_DMA_CR_DIR_M2P | STM32_DMA_CR_PSIZE_WORD | STM32_DMA_CR_MSIZE_WORD | STM32_DMA_CR_MINC | STM32_DMA_CR_CIRC | STM32_DMA_CR_PL(3));
+    // M2P: Memory 2 Periph; PL: Priority Level
+
+    // Start DMA
+    dmaStreamEnable(WS2812_DMA_STREAM);
+
+    // Configure PWM
+    // NOTE: It's required that preload be enabled on the timer channel CCR register. This is currently enabled in the
+    // ChibiOS driver code, so we don't have to do anything special to the timer. If we did, we'd have to start the timer,
+    // disable counting, enable the channel, and then make whatever configuration changes we need.
+    pwmStart(&WS2812_PWM_DRIVER, &ws2812_pwm_config);
+    pwmEnableChannel(&WS2812_PWM_DRIVER, WS2812_PWM_CHANNEL - 1, 0);  // Initial period is 0; output will be low until first duty cycle is DMA'd in
+}
+
+void ws2812_write_led(uint16_t led_number, uint8_t r, uint8_t g, uint8_t b) {
+    // Write color to frame buffer
+    for (uint8_t bit = 0; bit < 8; bit++) {
+        ws2812_frame_buffer[WS2812_RED_BIT(led_number, bit)]   = ((r >> bit) & 0x01) ? WS2812_DUTYCYCLE_1 : WS2812_DUTYCYCLE_0;
+        ws2812_frame_buffer[WS2812_GREEN_BIT(led_number, bit)] = ((g >> bit) & 0x01) ? WS2812_DUTYCYCLE_1 : WS2812_DUTYCYCLE_0;
+        ws2812_frame_buffer[WS2812_BLUE_BIT(led_number, bit)]  = ((b >> bit) & 0x01) ? WS2812_DUTYCYCLE_1 : WS2812_DUTYCYCLE_0;
+    }
+}
+
+// Setleds for standard RGB
+void ws2812_setleds(LED_TYPE* ledarray, uint16_t leds) {
+    static bool s_init = false;
+    if (!s_init) {
+        ws2812_init();
+        s_init = true;
+    }
+
+    for (uint16_t i = 0; i < leds; i++) {
+        ws2812_write_led(i, ledarray[i].r, ledarray[i].g, ledarray[i].b);
+    }
+}

drivers/arm/ws2812_spi.c

@@ -60,7 +60,7 @@ void ws2812_init(void) {
 
     // TODO: more dynamic baudrate
     static const SPIConfig spicfg = {
-        NULL, PAL_PORT(RGB_DI_PIN), PAL_PAD(RGB_DI_PIN),
+        0, 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)
     };