Make ARM Audio max volume configurable (#4540)

* Make ARM Audio max volume configurable

* Update docs/feature_audio.md

Co-Authored-By: drashna <drashna@live.com>

* Update docs/feature_audio.md

Co-Authored-By: drashna <drashna@live.com>

common_features.mk

@@ -213,6 +213,7 @@ endif
 ifeq ($(strip $(TERMINAL_ENABLE)), yes)
     SRC += $(QUANTUM_DIR)/process_keycode/process_terminal.c
     OPT_DEFS += -DTERMINAL_ENABLE
+    OPT_DEFS += -DUSER_PRINT
 endif
 
 ifeq ($(strip $(USB_HID_ENABLE)), yes)

docs/LANGS.md

@@ -0,0 +1,4 @@
+# Languages
+
+* [English](/)
+* [Chinese](zh/)

docs/_sidebar.md

@@ -39,6 +39,7 @@
   * [Glossary](reference_glossary.md)
   * [Unit Testing](unit_testing.md)
   * [Useful Functions](ref_functions.md)
+  * [Configurator Support](reference_configurator_support.md)
 
 * [Features](features.md)
   * [Basic Keycodes](keycodes_basic.md)
@@ -79,6 +80,7 @@
   * [Hand Wiring Guide](hand_wire.md)
   * [ISP Flashing Guide](isp_flashing_guide.md)
   * [ARM Debugging Guide](arm_debugging.md)
+  * [I2C Driver](i2c_driver.md)
 
 * For a Deeper Understanding
   * [How Keyboards Work](how_keyboards_work.md)

docs/_summary.md

@@ -39,6 +39,7 @@
   * [Glossary](reference_glossary.md)
   * [Unit Testing](unit_testing.md)
   * [Useful Functions](ref_functions.md)
+  * [Configurator Support](reference_configurator_support.md)
 
 * [Features](features.md)
   * [Basic Keycodes](keycodes_basic.md)
@@ -79,6 +80,7 @@
   * [Hand Wiring Guide](hand_wire.md)
   * [ISP Flashing Guide](isp_flashing_guide.md)
   * [ARM Debugging Guide](arm_debugging.md)
+  * [I2C Driver](i2c_driver.md)
 
 * For a Deeper Understanding
   * [How Keyboards Work](how_keyboards_work.md)

docs/config_options.md

@@ -132,14 +132,15 @@ If you define these options you will enable the associated feature, which may in
 * `#define TAPPING_TOGGLE 2`
   * how many taps before triggering the toggle
 * `#define PERMISSIVE_HOLD`
-  * makes tap and hold keys work better for fast typers who don't want tapping term set above 500
+  * 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 IGNORE_MOD_TAP_INTERRUPT`
-  * makes it possible to do rolling combos (zx) with keys that convert to other keys on hold
-  * See [Mod tap interrupt](feature_advanced_keycodes.md#mod-tap-interrupt) for details
+  * 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 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#hold-after-tap)
+  * See [Hold after tap](feature_advanced_keycodes.md#tapping-force-hold)
+  * Breaks any Tap Toggle functionality (`TT` or the One Shot Tap Toggle)
 * `#define LEADER_TIMEOUT 300`
   * how long before the leader key times out
 * `#define ONESHOT_TIMEOUT 300`
@@ -260,3 +261,32 @@ 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.
+
+## USB Endpoint Limitations
+
+In order to provide services over USB, QMK has to use USB endpoints.
+These are a finite resource: each microcontroller has only a certain number.
+This limits what features can be enabled together.
+If the available endpoints are exceeded, a build error is thrown.
+
+The following features can require separate endpoints:
+
+* `MOUSEKEY_ENABLE`
+* `EXTRAKEY_ENABLE`
+* `CONSOLE_ENABLE`
+* `NKRO_ENABLE`
+* `MIDI_ENABLE`
+* `RAW_ENABLE`
+* `VIRTSER_ENABLE`
+
+In order to improve utilisation of the endpoints, the HID features can be combined to use a single endpoint.
+By default, `MOUSEKEY`, `EXTRAKEY`, and `NKRO` are combined into a single endpoint.
+
+The base keyboard functionality can also be combined into the endpoint,
+by setting `KEYBOARD_SHARED_EP = yes`.
+This frees up one more endpoint,
+but it can prevent the keyboard working in some BIOSes,
+as they do not implement Boot Keyboard protocol switching.
+
+Combining the mouse also breaks Boot Mouse compatibility.
+The mouse can be uncombined by setting `MOUSE_SHARED_EP = no` if this functionality is required.

docs/faq_build.md

@@ -126,5 +126,5 @@ For now, you need to rollback avr-gcc to 7 in brew.
 ```
 brew uninstall --force avr-gcc
 brew install avr-gcc@7
-brew link avr-gcc@7
+brew link --force avr-gcc@7
 ```

docs/faq_keymap.md

@@ -11,8 +11,8 @@ Keycodes are actually defined in [common/keycode.h](https://github.com/qmk/qmk_f
 
 There are 3 standard keyboard layouts in use around the world- ANSI, ISO, and JIS. North America primarily uses ANSI, Europe and Africa primarily use ISO, and Japan uses JIS. Regions not mentioned typically use either ANSI or ISO. The keycodes corresponding to these layouts are shown here:
 
-<!-- Source for this image: http://www.keyboard-layout-editor.com/#/gists/070a530eedaed36a2d77f3f6fd455677 -->
-![Keyboard Layout Image](https://i.imgur.com/gvlNUpQ.png)
+<!-- Source for this image: http://www.keyboard-layout-editor.com/#/gists/bf431647d1001cff5eff20ae55621e9a -->
+![Keyboard Layout Image](https://i.imgur.com/5wsh5wM.png)
 
 ## Some Of My Keys Are Swapped Or Not Working
 
@@ -211,20 +211,3 @@ here real_mods lost state for 'physical left shift'.
 
 weak_mods is ORed with real_mods when keyboard report is sent.
 https://github.com/tmk/tmk_core/blob/master/common/action_util.c#L57
-
-## Timer Functionality
-
-It's possible to start timers and read values for time-specific events - here's an example:
-
-```c
-static uint16_t key_timer;
-key_timer = timer_read();
-
-if (timer_elapsed(key_timer) < 100) {
-  // do something if less than 100ms have passed
-} else {
-  // do something if 100ms or more have passed
-}
-```
-
-It's best to declare the `static uint16_t key_timer;` at the top of the file, outside of any code blocks you're using it in.

docs/feature_advanced_keycodes.md

@@ -73,7 +73,6 @@ These allow you to combine a modifier with a keycode. When pressed, the keydown
 |`HYPR(kc)`|                      |Hold Left Control, Shift, Alt and GUI and press `kc`|
 |`MEH(kc)` |                      |Hold Left Control, Shift and Alt and press `kc`     |
 |`LCAG(kc)`|                      |Hold Left Control, Alt and GUI and press `kc`       |
-|`ALTG(kc)`|                      |Hold Right Control and Alt and press `kc`           |
 |`SGUI(kc)`|`SCMD(kc)`, `SWIN(kc)`|Hold Left Shift and GUI and press `kc`              |
 |`LCA(kc)` |                      |Hold Left Control and Alt and press `kc`            |
 
@@ -171,30 +170,56 @@ As of [PR#1359](https://github.com/qmk/qmk_firmware/pull/1359/), there is a new
 #define PERMISSIVE_HOLD
 ```
 
-This makes it easier for fast typists to use dual-function keys. Without this, if you let go of a held key inside the tapping term, it won't register.
+This makes tap and hold keys (like Mod Tap) work better for fast typist, or for high `TAPPING_TERM` settings. 
 
-Example: (Tapping Term = 200ms)
+If you press a Mod Tap key, tap another key (press and release) and then release the Mod Tap key, all within the tapping term, it will output the "tapping" function for both keys.
 
-- SHFT_T(KC_A) Down
-- KC_X Down
-- KC_X Up
-- SHFT_T(KC_A) Up
+For Instance:
 
-With defaults, if above is typed within tapping term, this will emit `ax`. With permissive hold, if above is typed within tapping term, this will emit `X` (so, Shift+X).
+- `SHFT_T(KC_A)` Down
+- `KC_X` Down
+- `KC_X` Up
+- `SHFT_T(KC_A)` Up
 
-# Mod tap interrupt
+Normally, if you do all this within the `TAPPING_TERM` (default: 200ms) this will be registered as `ax` by the firmware and host system. With permissive hold enabled, this modifies how this is handled by considering the Mod Tap keys as a Mod if another key is tapped, and would registered as `X` (`SHIFT`+`x`). 
 
-When a dual role key used for a modifier is quickly followed by another keys, it is interpreted as held even before the tapping term elapsed.  This is a problem if a key is used for example inside a rolling combo because the second key will be pressed before the first key is released.
+?> 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 example, when trying to type the rolling combo "zx" and z being configured to send Ctrl when hold, z rapidly followed by x actually sends Ctrl-x. That's bad.
+# Ignore Mod Tap Interrupt
 
-You can disable this behavior by defining `IGNORE_MOD_TAP_INTERRUPT` in `config.h`.
+To enable this setting, add this to your `config.h`:
 
-Note that this only concerns modifiers and not layer switching keys.
+```c
+#define IGNORE_MOD_TAP_INTERRUPT
+```
 
-# Hold after tap
+Similar to Permissive Hold, this alters how the firmware processes input for fast typist. If you press a Mod Tap key, press another key, release the Mod Tap key, and then release the normal key, it would normally output the "tapping" function for both keys. This may not be desirable for rolling combo keys. 
 
-When the user holds a key after tap, this repeats the tapped key rather to hold a modifier key.  This allows to use auto repeat for the tapped key.  If you prefer to hold a modifier instead, define `TAPPING_FORCE_HOLD` in `config.h`.
+Setting `Ignore Mod Tap Interrupt` requires  holding both keys for the `TAPPING_TERM` to trigger the hold function (the mod).
+
+For Instance:
+
+- `SHFT_T(KC_A)` Down
+- `KC_X` Down
+- `SHFT_T(KC_A)` Up
+- `KC_X` Up
+
+Normally, this would send `X` (`SHIFT`+`x`). With `Ignore Mod Tap Interrupt` enabled, holding both keys are required for the `TAPPING_TERM` to register the hold action. A quick tap will output `ax` in this case, while a hold on both will still output `X`  (`SHIFT`+`x`).
+
+
+?> __Note__: This only concerns modifiers and not layer switching keys.
+
+?> 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`.
+
+# Tapping Force Hold
+
+To enable `tapping force hold`, add the following to your `config.h`: 
+
+```c
+#define TAPPING_FORCE_HOLD
+```
+
+When the user holds a key after tap, this repeats the tapped key rather to hold a modifier key.  This allows to use auto repeat for the tapped key.  
 
 Example:
 
@@ -212,6 +237,12 @@ With `TAPPING_FORCE_HOLD`, the second press will be interpreted as a Shift, allo
 
 # Retro Tapping
 
+To enable `retro tapping`, add the following to your `config.h`: 
+
+```c
+#define RETRO_TAPPING
+```
+
 Holding and releasing a dual function key without pressing another key will result in nothing happening. With retro tapping enabled, releasing the key without pressing another will send the original keycode even if it is outside the tapping term.
 
-For instance, holding and releasing `LT(2, KC_SPACE)` without hitting another key will result in nothing happening. With `RETRO_TAPPING` defined in your `config.h`, it will send `KC_SPACE`.
+For instance, holding and releasing `LT(2, KC_SPACE)` without hitting another key will result in nothing happening. With this enabled, it will send `KC_SPACE` instead.

docs/feature_audio.md

@@ -65,6 +65,13 @@ The available keycodes for audio are:
 * `AU_OFF` - Turn audio mode off
 * `AU_TOG` - Toggle audio mode
 
+## ARM Audio Volume
+
+For ARM devices, you can adjust the DAC sample values. If your board is too loud for you or your coworkers, you can set the max using `DAC_SAMPLE_MAX` in your `config.h`:
+
+```c
+#define DAC_SAMPLE_MAX 65535U
+```
 
 ## Music Mode
 

docs/feature_backlight.md

@@ -54,14 +54,17 @@ In this handler, the value of an incrementing counter is mapped onto a precomput
 
 ## Backlight Functions
 
-|Function  |Description                                               |
-|----------|----------------------------------------------------------|
-|`backlight_toggle()`   |Turn the backlight on or off                 |
-|`backlight_step()`     |Cycle through backlight levels               |
-|`backlight_increase()` |Increase the backlight level                 |
-|`backlight_decrease()` |Decrease the backlight level                 |
-|`backlight_level(x)`   |Sets the backlight level to specified level  |
-|`get_backlight_level()`|Return the current backlight level           |
+|Function  |Description                                                |
+|----------|-----------------------------------------------------------|
+|`backlight_toggle()`    |Turn the backlight on or off                 |
+|`backlight_enable()`    |Turn the backlight on                        |
+|`backlight_disable()`   |Turn the backlight off                       |
+|`backlight_step()`      |Cycle through backlight levels               |
+|`backlight_increase()`  |Increase the backlight level                 |
+|`backlight_decrease()`  |Decrease the backlight level                 |
+|`backlight_level(x)`    |Sets the backlight level to specified level  |
+|`get_backlight_level()` |Return the current backlight level           |
+|`is_backlight_enabled()`|Return whether the backlight is currently on |
 
 ### Backlight Breathing Functions
 

docs/feature_combo.md

@@ -44,15 +44,15 @@ For a more complicated implementation, you can use the `process_combo_event` fun
 ```c
 enum combo_events {
   ZC_COPY,
-  ZV_PASTE
+  XV_PASTE
   };
 
 const uint16_t PROGMEM copy_combo[] = {KC_Z, KC_C, COMBO_END};
-const uint16_t PROGMEM paste_combo[] = {KC_Z, KC_V, COMBO_END};
+const uint16_t PROGMEM paste_combo[] = {KC_X, KC_V, COMBO_END};
 
 combo_t key_combos[COMBO_COUNT] = {
   [ZC_COPY] = COMBO_ACTION(copy_combo),
-  [ZV_PASTE] = COMBO_ACTION(paste_combo),
+  [XV_PASTE] = COMBO_ACTION(paste_combo),
 };
 
 void process_combo_event(uint8_t combo_index, bool pressed) {
@@ -66,7 +66,7 @@ void process_combo_event(uint8_t combo_index, bool pressed) {
       }
       break;
 
-    case ZV_PASTE:
+    case XV_PASTE:
       if (pressed) {
         register_code(KC_LCTL);
         register_code(KC_V);
@@ -78,7 +78,7 @@ void process_combo_event(uint8_t combo_index, bool pressed) {
 }
 ```
 
-This will send Ctrl+C if you hit Z and C, and Ctrl+V if you hit Z and V.  But you could change this to do stuff like change layers, play sounds, or change settings.
+This will send Ctrl+C if you hit Z and C, and Ctrl+V if you hit X and V.  But you could change this to do stuff like change layers, play sounds, or change settings.
 
 ## Additional Configuration
 

docs/feature_rgb_matrix.md

@@ -150,6 +150,30 @@ These are the effects that are currently available:
 	#endif
 	    RGB_MATRIX_EFFECT_MAX
 	};
+    
+You can disable a single effect by defining `DISABLE_[EFFECT_NAME]` in your `config.h`:
+
+
+|Define                                             |Description                                 |
+|---------------------------------------------------|--------------------------------------------|
+|`#define DISABLE_RGB_MATRIX_ALPHAS_MODS`           |Disables `RGB_MATRIX_ALPHAS_MODS`           |
+|`#define DISABLE_RGB_MATRIX_DUAL_BEACON`           |Disables `RGB_MATRIX_DUAL_BEACON`           |
+|`#define DISABLE_RGB_MATRIX_GRADIENT_UP_DOWN`      |Disables `RGB_MATRIX_GRADIENT_UP_DOWN`      |
+|`#define DISABLE_RGB_MATRIX_RAINDROPS`             |Disables `RGB_MATRIX_RAINDROPS`             |
+|`#define DISABLE_RGB_MATRIX_CYCLE_ALL`             |Disables `RGB_MATRIX_CYCLE_ALL`             |
+|`#define DISABLE_RGB_MATRIX_CYCLE_LEFT_RIGHT`      |Disables `RGB_MATRIX_CYCLE_LEFT_RIGHT`      |
+|`#define DISABLE_RGB_MATRIX_CYCLE_UP_DOWN`         |Disables `RGB_MATRIX_CYCLE_UP_DOWN`         |
+|`#define DISABLE_RGB_MATRIX_RAINBOW_BEACON`        |Disables `RGB_MATRIX_RAINBOW_BEACON`        |
+|`#define DISABLE_RGB_MATRIX_RAINBOW_PINWHEELS`     |Disables `RGB_MATRIX_RAINBOW_PINWHEELS`     |
+|`#define DISABLE_RGB_MATRIX_RAINBOW_MOVING_CHEVRON`|Disables `RGB_MATRIX_RAINBOW_MOVING_CHEVRON`|
+|`#define DISABLE_RGB_MATRIX_JELLYBEAN_RAINDROPS`   |Disables `RGB_MATRIX_JELLYBEAN_RAINDROPS`   |
+|`#define DISABLE_RGB_MATRIX_DIGITAL_RAIN`          |Disables `RGB_MATRIX_DIGITAL_RAIN`          |
+|`#define DISABLE_RGB_MATRIX_SOLID_REACTIVE`        |Disables `RGB_MATRIX_SOLID_REACTIVE`        |
+|`#define DISABLE_RGB_MATRIX_SPLASH`                |Disables `RGB_MATRIX_SPLASH`                |
+|`#define DISABLE_RGB_MATRIX_MULTISPLASH`           |Disables `RGB_MATRIX_MULTISPLASH`           |
+|`#define DISABLE_RGB_MATRIX_SOLID_SPLASH`          |Disables `RGB_MATRIX_SOLID_SPLASH`          |
+|`#define DISABLE_RGB_MATRIX_SOLID_MULTISPLASH`     |Disables `RGB_MATRIX_SOLID_MULTISPLASH`     |
+
 
 ## Custom layer effects
 

docs/feature_rgblight.md

@@ -63,8 +63,6 @@ Changing the **Value** sets the overall brightness.
 |`RGB_MODE_GRADIENT`|`RGB_M_G` |Static gradient animation mode                                      |
 |`RGB_MODE_RGBTEST` |`RGB_M_T` |Red, Green, Blue test animation mode                                |
 
-?> For backwards compatibility, `RGB_SMOD` is another alias of `RGB_MOD`.
-
 ## Configuration
 
 Your RGB lighting can be configured by placing these `#define`s in your `config.h`:
@@ -122,6 +120,7 @@ The following options can be used to tweak the various animations:
 |`RGBLIGHT_EFFECT_KNIGHT_LED_NUM`    |`RGBLED_NUM` |The number of LEDs to have the "Knight" animation travel                             |
 |`RGBLIGHT_EFFECT_CHRISTMAS_INTERVAL`|`1000`       |How long to wait between light changes for the "Christmas" animation, in milliseconds|
 |`RGBLIGHT_EFFECT_CHRISTMAS_STEP`    |`2`          |The number of LEDs to group the red/green colors by for the "Christmas" animation    |
+|`RGBLIGHT_RAINBOW_SWIRL_RANGE`      |`360`        |Range adjustment for the rainbow swirl effect to get different swirls                |
 
 You can also modify the speeds that the different modes animate at:
 

docs/feature_unicode.md

@@ -30,7 +30,7 @@ Make sure that the order for both matches.
 
 ## UCIS_ENABLE
 
-Supports Unicode up to 0xFFFFFFFF. As with `UNICODE_MAP`, you may want to main a mapping table in your keymap file.  However, there is no keycodes for this feature, you will have to add a keycode or function to call `qk_ucis_start()`. Once you've run that, you can just type the text for your unicode, and then hit space or enter to complete it, or ESC to cancel it. And if it matches an entry in your table, it will automatically "backspace" the trigger word (from your table) and then will input the unicode sequence.
+Supports Unicode up to 0xFFFFFFFF. As with `UNICODE_MAP`, you may want to maintain a mapping table in your keymap file.  However, there is no keycodes for this feature, you will have to add a keycode or function to call `qk_ucis_start()`. Once you've run that, you can just type the text for your unicode, and then hit space or enter to complete it, or ESC to cancel it. And if it matches an entry in your table, it will automatically "backspace" the trigger word (from your table) and then will input the unicode sequence.
 
 For instance, you would need to have a table like this in your keymap:
 

docs/features.md

@@ -8,13 +8,17 @@ QMK has a staggering number of features for building your keyboard. It can take
 * [Auto Shift](feature_auto_shift.md) - Tap for the normal key, hold slightly longer for its shifted state.
 * [Backlight](feature_backlight.md) - LED lighting support for your keyboard.
 * [Bootmagic](feature_bootmagic.md) - Adjust the behavior of your keyboard using hotkeys.
+* [Combos](feature_combo.md) - Custom actions for multiple key holds.
+* [Command](feature_command.md) - Runtime version of bootmagic (Formerly known as "Magic").
 * [Dynamic Macros](feature_dynamic_macros.md) - Record and playback macros from the keyboard itself.
+* [Grave Escape](feature_grave_esc.md) - Lets you use a single key for Esc and Grave. 
 * [HD44780 LCD Display](feature_hd44780.md) - Support for LCD character displays using the HD44780 standard.
 * [Key Lock](feature_key_lock.md) - Lock a key in the "down" state.
 * [Layouts](feature_layouts.md) - Use one keymap with any keyboard that supports your layout.
 * [Leader Key](feature_leader_key.md) - Tap the leader key followed by a sequence to trigger custom behavior.
 * [Macros](feature_macros.md) - Send multiple key presses when pressing only one physical key.
 * [Mouse keys](feature_mouse_keys.md) - Control your mouse pointer from your keyboard.
+* [One Shot Keys](feature_advanced_keycodes.md#one-shot-keys) - Sticky Keys, lets hit a key rather than holding it.
 * [Pointing Device](feature_pointing_device.md) - Framework for connecting your custom pointing device to your keyboard.
 * [PS2 Mouse](feature_ps2_mouse.md) - Driver for connecting a PS/2 mouse directly to your keyboard.
 * [RGB Light](feature_rgblight.md) - RGB lighting for your keyboard.

docs/getting_started_build_tools.md

@@ -57,6 +57,7 @@ If you're using [homebrew,](http://brew.sh/) you can use the following commands:
     brew tap PX4/homebrew-px4
     brew update
     brew install avr-gcc@7
+    brew link --force avr-gcc@7
     brew install dfu-programmer
     brew install dfu-util
     brew install gcc-arm-none-eabi

docs/i2c_driver.md

@@ -0,0 +1,82 @@
+# I2C Master Driver
+
+The I2C Master drivers used in QMK have a set of common functions to allow portability between MCUs.
+
+## Available functions
+
+|Function                                                                                                          |Description                                                                                                                                                                  |
+|------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+|`void i2c_init(void);`                                                                                            |Initializes the I2C driver. This function should be called once before any transaction is initiated.                                                                         |
+|`uint8_t i2c_start(uint8_t address);`                                                                             |Starts an I2C transaction. Address is the 7-bit slave address without the direction bit.                                                                                     |
+|`uint8_t i2c_transmit(uint8_t address, uint8_t* data, uint16_t length, uint16_t timeout);`                        |Transmit data over I2C. Address is the 7-bit slave address without the direction. Returns status of transaction.                                                             |
+|`uint8_t i2c_receive(uint8_t address, uint8_t* data, uint16_t length, uint16_t timeout);`                         |Receive data over I2C. Address is the 7-bit slave address without the direction. Saves number of bytes specified by `length` in `data` array. Returns status of transaction. |
+|`uint8_t i2c_writeReg(uint8_t devaddr, uint8_t regaddr, uint8_t* data, uint16_t length, uint16_t timeout);`       |Same as the `i2c_transmit` function but `regaddr` sets where in the slave the data will be written.                                                                          |
+|`uint8_t i2c_readReg(uint8_t devaddr, uint8_t regaddr, uint8_t* data, uint16_t length, uint16_t timeout);`        |Same as the `i2c_receive` function but `regaddr` sets from where in the slave the data will be read.                                                                         |
+|`uint8_t i2c_stop(uint16_t timeout);`                                                                             |Stops the I2C driver.                                                                                                                                                        |
+
+### Function Return
+
+All the above functions, except `void i2c_init(void);` return the following truth table:
+
+|Return Value   |Description                                        |
+|---------------|---------------------------------------------------|
+|0              |Operation executed successfully.                   |
+|-1             |Operation failed.                                  |
+|-2             |Operation timed out.                               |
+
+
+## AVR
+
+### Configuration
+
+The following defines can be used to configure the I2C master driver.
+
+|Variable          |Description                                        |Default|
+|------------------|---------------------------------------------------|-------|
+|`#F_SCL`          |Clock frequency in Hz                              |400KHz |
+|`#Prescaler`      |Divides master clock to aid in I2C clock selection |1      |
+
+AVRs usually have set GPIO which turn into I2C pins, therefore no further configuration is required.
+
+## ARM
+
+For ARM the Chibios I2C HAL driver is under the hood.
+This section assumes an STM32 MCU.
+
+### Configuration
+
+The configuration for ARM MCUs can be quite complex as often there are multiple I2C drivers which can be assigned to a variety of ports.
+
+Firstly the `mcuconf.h` file must be setup to enable the necessary hardware drivers.
+
+|Variable                      |Description                                                                        |Default|
+|------------------------------|------------------------------------------------------------------------------------|-------|
+|`#STM32_I2C_USE_XXX`          |Enable/Disable the hardware driver XXX (each driver should be explicitly listed)    |FALSE  |
+|`#STM32_I2C_BUSY_TIMEOUT`     |Time in ms until the I2C command is aborted if no response is received              |50     |
+|`#STM32_I2C_XXX_IRQ_PRIORITY` |Interrupt priority for hardware driver XXX (THIS IS AN EXPERT SETTING)              |10     |
+|`#STM32_I2C_USE_DMA`          |Enable/Disable the ability of the MCU to offload the data transfer to the DMA unit  |TRUE   |
+|`#STM32_I2C_XXX_DMA_PRIORITY` |Priority of DMA unit for hardware driver XXX (THIS IS AN EXPERT SETTING)            |1      |
+
+Secondly, in the `halconf.h` file, `#define HAL_USE_I2C` must be set to `TRUE`. This allows ChibiOS to load its I2C driver.
+
+Lastly, we need to assign the correct GPIO pins depending on the I2C hardware driver we want to use.
+
+By default the I2C1 hardware driver is assumed to be used. If another hardware driver is used,  `#define I2C_DRIVER I2CDX` should be added to the `config.h` file with X being the number of hardware driver used. For example is I2C3 is enabled, the `config.h` file should contain `#define I2C_DRIVER I2CD3`. This aligns the QMK I2C driver with the Chibios I2C driver.
+
+STM32 MCUs allows a variety of pins to be configured as I2C pins depending on the hardware driver used. By default B6 and B7 are set to I2C.
+
+This can be changed by declaring the `i2c_init` function which intentionally has a weak attribute. Please consult the datasheet of your MCU for the available GPIO configurations. The following is an example initialization function:
+
+```C
+void i2c_init(void)
+{
+  setPinInput(B6); // Try releasing special pins for a short time
+  setPinInput(B7);
+  chThdSleepMilliseconds(10); // Wait for the release to happen
+
+  palSetPadMode(GPIOB, 6, PAL_MODE_ALTERNATE(4) | PAL_STM32_OTYPE_OPENDRAIN | PAL_STM32_PUPDR_PULLUP); // Set B6 to I2C function
+  palSetPadMode(GPIOB, 7, PAL_MODE_ALTERNATE(4) | PAL_STM32_OTYPE_OPENDRAIN | PAL_STM32_PUPDR_PULLUP); // Set B7 to I2C function
+}
+```
+
+

docs/index.html

@@ -25,7 +25,8 @@
         placeholder: 'Search Documentation...',
         noData: 'We could not find any documents matching your search.',
         depth: 6
-      }
+      },
+      fallbackLanguages: ['zh']
     }
   </script>
   <script src="//unpkg.com/docsify/lib/docsify.min.js"></script>

docs/keycode.txt

@@ -209,6 +209,8 @@ KC_WWW_FORWARD      KC_WFWD
 KC_WWW_STOP         KC_WSTP
 KC_WWW_REFRESH      KC_WREF
 KC_WWW_FAVORITES    KC_WFAV
+KC_BRIGHTNESS_UP    KC_BRIU
+KC_BRIGHTNESS_DOWN  KC_BRID
 /* Mousekey */
 KC_MS_UP            KC_MS_U         Mouse Cursor Up
 KC_MS_DOWN          KC_MS_D         Mouse Cursor Down

docs/keycodes.md

@@ -141,9 +141,9 @@ This is a reference only. Each group of keys links to the page documenting their
 |`KC_LOCKING_SCROLL`    |`KC_LSCR`           |Locking Scroll Lock                            |
 |`KC_KP_COMMA`          |`KC_PCMM`           |Keypad `,`                                     |
 |`KC_KP_EQUAL_AS400`    |                    |Keypad `=` on AS/400 keyboards                 |
-|`KC_INT1`              |`KC_RO`             |JIS `\` and <code>&#124;</code>                |
+|`KC_INT1`              |`KC_RO`             |JIS `\` and `_`                                |
 |`KC_INT2`              |`KC_KANA`           |JIS Katakana/Hiragana                          |
-|`KC_INT3`              |`KC_JYEN`           |JIS `¥`                                        |
+|`KC_INT3`              |`KC_JYEN`           |JIS `¥` and <code>&#124;</code>                |
 |`KC_INT4`              |`KC_HENK`           |JIS Henkan                                     |
 |`KC_INT5`              |`KC_MHEN`           |JIS Muhenkan                                   |
 |`KC_INT6`              |                    |JIS Numpad `,`                                 |
@@ -203,21 +203,24 @@ This is a reference only. Each group of keys links to the page documenting their
 |`KC_WWW_FAVORITES`     |`KC_WFAV`           |Browser Favorites (Windows)                    |
 |`KC_MEDIA_FAST_FORWARD`|`KC_MFFD`           |Next Track (macOS)                             |
 |`KC_MEDIA_REWIND`      |`KC_MRWD`           |Previous Track (macOS)                         |
+|`KC_BRIGHTNESS_UP`     |`KC_BRIU`           |Brightness Up                                  |
+|`KC_BRIGHTNESS_DOWN`   |`KC_BRID`           |Brightness Down                                |
 
 ## [Quantum Keycodes](quantum_keycodes.md#qmk-keycodes)
 
-|Key          |Aliases    |Description                                                          |
-|-------------|-----------|---------------------------------------------------------------------|
-|`RESET`      |           |Put the keyboard into DFU mode for flashing                          |
-|`DEBUG`      |           |Toggle debug mode                                                    |
-|`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_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 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_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                                              |
 
 ## [Audio Keys](feature_audio.md)
 
@@ -333,7 +336,6 @@ This is a reference only. Each group of keys links to the page documenting their
 |`HYPR(kc)`|                      |Hold Left Control, Shift, Alt and GUI and press `kc`|
 |`MEH(kc)` |                      |Hold Left Control, Shift and Alt and press `kc`     |
 |`LCAG(kc)`|                      |Hold Left Control, Alt and GUI and press `kc`       |
-|`ALTG(kc)`|                      |Hold Right Control and Alt and press `kc`           |
 |`SGUI(kc)`|`SCMD(kc)`, `SWIN(kc)`|Hold Left Shift and GUI and press `kc`              |
 |`LCA(kc)` |                      |Hold Left Control and Alt and press `kc`            |
 
@@ -460,6 +462,7 @@ This is a reference only. Each group of keys links to the page documenting their
 |`SH_MOFF`  |Momentarily turns off swap.                                              |
 |`SH_TG`    |Toggles swap on and off with every key press.                            |
 |`SH_TT`    |Toggles with a tap; momentary when held.                                 |
+
 ## [Unicode Support](feature_unicode.md)
 
 |Key         |Aliases|                                                 |

docs/keycodes_basic.md

@@ -123,9 +123,9 @@ The basic set of keycodes are based on the [HID Keyboard/Keypad Usage Page (0x07
 
 |Key       |Aliases  |Description                    |
 |----------|---------|-------------------------------|
-|`KC_INT1` |`KC_RO`  |JIS `\` and <code>&#124;</code>|
+|`KC_INT1` |`KC_RO`  |JIS `\` and `_`                |
 |`KC_INT2` |`KC_KANA`|JIS Katakana/Hiragana          |
-|`KC_INT3` |`KC_JYEN`|JIS `¥`                        |
+|`KC_INT3` |`KC_JYEN`|JIS `¥` and <code>&#124;</code>|
 |`KC_INT4` |`KC_HENK`|JIS Henkan                     |
 |`KC_INT5` |`KC_MHEN`|JIS Muhenkan                   |
 |`KC_INT6` |         |JIS Numpad `,`                 |
@@ -219,6 +219,8 @@ Windows and macOS use different keycodes for "next track" and "previous track".
 |`KC_WWW_FAVORITES`     |`KC_WFAV`|Browser Favorites (Windows)  |
 |`KC_MEDIA_FAST_FORWARD`|`KC_MFFD`|Next Track (macOS)           |
 |`KC_MEDIA_REWIND`      |`KC_MRWD`|Previous Track (macOS)       |
+|`KC_BRIGHTNESS_UP`     |`KC_BRIU`|Brightness Up                |
+|`KC_BRIGHTNESS_DOWN`   |`KC_BRID`|Brightness Down              |
 
 ## Number Pad
 

docs/newbs_getting_started.md

@@ -1,99 +1,97 @@
 # Introduction
 
-Your computer keyboard has a processor inside of it, not unlike the one inside your computer. This processor runs software that is responsible for detecting button presses and sending reports about the state of the keyboard when they are pressed or released. QMK fills the role of that software, detecting button presses and passing that information on to the host computer. When you build your custom layout you are creating the equivalent of an .exe for your keyboard.
+Your computer keyboard has a processor inside of it, not unlike the one inside your computer. This processor runs software that is responsible for detecting button presses and sending reports about the state of the keyboard when buttons are pressed or released. QMK fills the role of that software, detecting button presses and passing that information on to the host computer. When you build your custom keymap, you are creating the equivalent of an executable program for your keyboard.
 
-QMK tries to put a lot of power into your hands by making easy things easy, and hard things possible. You don't have to know how to program to create powerful layouts, you only have to follow a few simple syntax rules.
+QMK tries to put a lot of power into your hands by making easy things easy, and hard things possible. You don't have to know how to program to create powerful keymaps — you only have to follow a few simple syntax rules.
 
 # Getting Started
 
-Before you can build keymaps you need to install some software and setup your build environment. This only has to be done one time no matter how many keyboards you want to compile firmware for.
+Before you can build keymaps, you need to install some software and set up your build environment. This only has to be done once no matter how many keyboards you plan to compile firmware for.
 
 ## Download Software
 
 ### Text Editor
 
-You'll need a program that can edit and save **plain text** files. If you are on Windows you can make due with Notepad, and on Linux you can use Gedit, both of which are simple but functional text editors. On macOS be careful with TextEdit.app, it will not save plain text files unless you make sure to select "Make Plain text" from the "Format" menu, or you can use another program such as Sublime Text.
+You'll need a program that can edit and save **plain text** files. If you're on Windows you can make do with Notepad, and on Linux you can use gedit. Both of these are simple but functional text editors. On macOS, be careful with the default TextEdit app: it will not save plain text files unless you explicitly select _Make Plain Text_ from the _Format_ menu.
+
+You can also download and install a dedicated text editor like [Sublime Text](https://www.sublimetext.com/) or [VS Code](https://code.visualstudio.com/). This is probably the best way to go regardless of platform, as these programs are specifically made for editing code.
 
 ?> Not sure which text editor to use? Laurence Bradford wrote [a great introduction](https://learntocodewith.me/programming/basics/text-editors/) to the subject.
 
 ### QMK Toolbox
 
-QMK Toolbox is an optional graphical Windows and macOS program that allows you to both program and debug your custom keyboard. You will likely prefer it to easily flash your keyboard and receive the debugging messages that your keyboard will print.
+QMK Toolbox is an optional graphical program for Windows and macOS that allows you to both program and debug your custom keyboard. You will likely find it invaluable for easily flashing your keyboard and viewing debug messages that it prints.
 
-Download the files from the links below:
+[Download the latest release here.](https://github.com/qmk/qmk_toolbox/releases/latest)
 
-For Windows: "qmk_toolbox.exe" or "qmk_toolbox_install.exe" (with installer)
+* For Windows: `qmk_toolbox.exe` (portable) or `qmk_toolbox_install.exe` (installer)
+* For macOS: `QMK.Toolbox.app.zip` (portable) or `QMK.Toolbox.pkg` (installer)
 
-For Mac: "QMK.Toolbox.app.zip" or "QMK.Toolbox.pkg" (with installer)
+## Set Up Your Environment
 
-* [Newest Release](https://github.com/qmk/qmk_toolbox/releases/latest)
-* [Source Code](https://github.com/qmk/qmk_toolbox/)
+We've tried to make QMK as easy to set up as possible. You only have to prepare your Linux or Unix environment, then let QMK install the rest.
 
-## Environment Setup
-
-We've tried to make QMK as easy to setup as possible. You only have to prepare your Linux or Unix environment and let QMK install the rest.
-
-?> If you haven't worked with the Linux/Unix command line before there are a few basic concepts and commands you should learn. These resources will teach you enough to work with QMK:<br>
+?> If you haven't worked with the Linux/Unix command line before, there are a few basic concepts and commands you should learn. These resources will teach you enough to be able to work with QMK:<br>
 [Must Know Linux Commands](https://www.guru99.com/must-know-linux-commands.html)<br>
 [Some Basic Unix Commands](https://www.tjhsst.edu/~dhyatt/superap/unixcmd.html)
 
 ### Windows
 
-You will need to install msys2 and git.
+You will need to install MSYS2 and Git.
 
-* Follow the installation instructions on the msys2 homepage: http://www.msys2.org
-* Close any open msys2 terminals, and open a new terminal
-* Install git by running this command: `pacman -S git`
+* Follow the installation instructions on the [MSYS2 homepage](http://www.msys2.org).
+* Close any open MSYS2 terminals and open a new MSYS2 MinGW 64-bit terminal.
+* Install Git by running this command: `pacman -S git`.
 
 ### macOS
 
-You will need to install homebrew. Follow the instructions on the homebrew homepage: https://brew.sh
+You will need to install Homebrew. Follow the instructions on the [Homebrew homepage](https://brew.sh).
 
-After homebrew is installed continue with "Download QMK", following step "Setup QMK" runs a script that will install other packages.
+After Homebrew is installed, continue with _Set Up QMK_. In that step you will run a script that will install other packages.
 
 ### Linux
 
-You will need to install git. It's extremely likely you already have it, but if not one of the following commands should install it:
+You will need to install Git. It's very likely that you already have it, but if not, one of the following commands should install it:
 
-* Debian/Ubuntu/Devuan: `apt-get install git`
-* Fedora/Redhat/Centos: `yum install git`
+* Debian / Ubuntu / Devuan: `apt-get install git`
+* Fedora / Red Hat / CentOS: `yum install git`
 * Arch: `pacman -S git`
 
-## Download QMK
+?> Docker is also an option on all platforms. [Click here for details.](getting_started_build_tools.md#docker)
 
-Once you have setup your Linux/Unix environment you are ready to download QMK. We will do this by using git to "clone" the QMK repository. Open a Terminal or MSYS2 Console window and leave it open for the remainder of this guide. Inside that window run these two commands:
+## Set Up QMK
+
+Once you have set up your Linux/Unix environment, you are ready to download QMK. We will do this by using Git to "clone" the QMK repository. Open a Terminal or MSYS2 MinGW window and leave it open for the remainder of this guide. Inside that window run these two commands:
 
     git clone https://github.com/qmk/qmk_firmware.git
     cd qmk_firmware
 
-?> If you already know [how to use GitHub](getting_started_github.md) we recommend you create and clone your own fork instead. If you don't know what that means you can safely ignore this message.
+?> If you already know [how to use GitHub](getting_started_github.md), we recommend that you create and clone your own fork instead. If you don't know what that means, you can safely ignore this message.
 
-## Setup QMK
+QMK comes with a script to help you set up the rest of what you'll need. You should run it now by typing in this command:
 
-QMK comes with a script to help you setup the rest of what you'll need. You should run it now by typing in this command:
-
-    ./util/qmk_install.sh
+    util/qmk_install.sh
 
 ## Test Your Build Environment
 
-Now that your QMK build environment is setup you can build a firmware for your keyboard. Start by trying to build the default layout for your keyboard. You should be able to do that with a command in this format:
+Now that your QMK build environment is set up, you can build a firmware for your keyboard. Start by trying to build the keyboard's default keymap. You should be able to do that with a command in this format:
 
     make <keyboard>:default
 
-For example, to build a firmware for a Clueboard 66% use:
+For example, to build a firmware for a Clueboard 66% you would use:
 
     make clueboard/66/rev3:default
 
 When it is done you should have a lot of output that ends similar to this:
 
 ```
-Linking: .build/clueboard_66_rev2_default.elf                                                       [OK]
-Creating load file for flashing: .build/clueboard_66_rev2_default.hex                               [OK]
-Copying clueboard_66_rev2_default.hex to qmk_firmware folder                                        [OK]
-Checking file size of clueboard_66_rev2_default.hex                                                 [OK]
- * File size is fine - 25174/28672
+Linking: .build/clueboard_66_rev3_default.elf                                                       [OK]
+Creating load file for flashing: .build/clueboard_66_rev3_default.hex                               [OK]
+Copying clueboard_66_rev3_default.hex to qmk_firmware folder                                        [OK]
+Checking file size of clueboard_66_rev3_default.hex                                                 [OK]
+ * The firmware size is fine - 26356/28672 (2316 bytes free)
 ```
 
-## Creating Your Layout
+# Creating Your Keymap
 
-Now you are ready to create your own personal layout. Move on to [Building Your First Firmware](newbs_building_firmware.md) for that.
+You are now ready to create your own personal keymap! Move on to [Building Your First Firmware](newbs_building_firmware.md) for that.

docs/newbs_testing_debugging.md

@@ -28,6 +28,6 @@ Sometimes it's useful to print debug messages from within your [custom code](cus
 After that you can use a few different print functions:
 
 * `print("string")`: Print a simple string.
-* `sprintf("%s string", var)`: Print a formatted string
+* `uprintf("%s string", var)`: Print a formatted string
 * `dprint("string")` Print a simple string, but only when debug mode is enabled
 * `dprintf("%s string", var)`: Print a formatted string, but only when debug mode is enabled

docs/quantum_keycodes.md

@@ -8,15 +8,16 @@ 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                                                    |
-|`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_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 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_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                                              |

docs/ref_functions.md

@@ -96,3 +96,24 @@ And to do so, add `reset_keyboard()` to your function or macro, and this will re
 If you're having issues with Audio, RGB Underglow, backlighting or keys acting weird, then you can reset the EEPROM (persistent setting storage).  Bootmagic is one way to do this, but if that isn't enabled, then you can use a custom macro to do so.
 
 To wipe the EEPROM, run `eeconfig_init()` from your function or macro to reset most of the settings to default.
+
+## Tap random key
+
+If you want to send a random character to the host computer, you can use the `tap_random_base64()` function. This [pseudorandomly](https://en.wikipedia.org/wiki/Pseudorandom_number_generator) selects a number between 0 and 63, and then sends a key press based on that selection. (0–25 is `A`–`Z`, 26–51 is `a`–`z`, 52–61 is `0`–`9`, 62 is `+` and 63 is `/`).  
+
+?> Needless to say, but this is _not_ a cryptographically secure method of generating random Base64 keys or passwords.
+
+## Software Timers
+
+It's possible to start timers and read values for time-specific events. Here's an example:
+
+```c
+static uint16_t key_timer;
+key_timer = timer_read();
+
+if (timer_elapsed(key_timer) < 100) {
+  // do something if less than 100ms have passed
+} else {
+  // do something if 100ms or more have passed
+}
+```

docs/reference_configurator_support.md

@@ -0,0 +1,195 @@
+# Supporting Your Keyboard in QMK Configurator
+
+This page covers how to properly support keyboards in the [QMK Configurator](https://config.qmk.fm/).
+
+
+## How the Configurator Understands Keyboards
+
+To understand how the Configurator understands keyboards, first one must understand layout macros. For this exercise, we're going to imagine a 17-key numpad PCB, which we're going to call `numpad`.
+
+```
+┌───┬───┬───┬───┐
+│NLk│ / │ * │ - │
+├───┼───┼───┼───┤
+│7  │8  │9  │ + │
+├───┼───┼───┤   │
+│4  │5  │6  │   │
+├───┼───┼───┼───┤
+│1  │2  │3  │Ent│
+├───┴───┼───┤   │
+│0      │ . │   │
+└───────┴───┴───┘
+```
+
+?> For more on layout macros, see [Understanding QMK: Matrix Scanning](understanding_qmk.md?id=matrix-scanning) and [Understanding QMK: Matrix to Physical Layout Map](understanding_qmk.md?id=matrix-to-physical-layout-map).
+
+The Configurator's API reads the keyboard's `.h` file from `qmk_firmware/keyboards/<keyboard>/<keyboard>.h`. For our numpad, this file would be `qmk_firmware/keyboards/numpad/numpad.h`:
+
+```c
+#pragma once
+
+#define LAYOUT( \
+    k00, k01, k02, k03, \
+    k10, k11, k12, k13, \
+    k20, k21, k22,      \
+    k30, k31, k32, k33, \
+    k40,      k42       \
+  ) { \
+    { k00, k01,   k02, k03   }, \
+    { k10, k11,   k12, k13   }, \
+    { k20, k21,   k22, KC_NO }, \
+    { k30, k31,   k32, k33   }, \
+    { k40, KC_NO, k42, KC_NO }  \
+}
+```
+
+QMK uses `KC_NO` to designate places in the switch matrix where there is no switch. Sometimes, `XXX`, `___` or `____` are used as shorthand to make this section easier to read if it needs to be debugged. This is usually defined near the beginning of the `.h` file:
+
+```c
+#pragma once
+
+#define XXX KC_NO
+
+#define LAYOUT( \
+    k00, k01, k02, k03, \
+    k10, k11, k12, k13, \
+    k20, k21, k22,      \
+    k30, k31, k32, k33, \
+    k40,      k42       \
+  ) { \
+    { k00, k01, k02, k03 }, \
+    { k10, k11, k12, k13 }, \
+    { k20, k21, k22, XXX }, \
+    { k30, k31, k32, k33 }, \
+    { k40, XXX, k42, XXX }  \
+}
+```
+
+!> This usage differs from that of keymap macros, which almost always use `XXXXXXX` (seven capital X's) for `KC_NO` and `_______` (seven underscores) for `KC_TRNS`.
+
+!> To prevent user confusion, using `KC_NO` is preferred.
+
+The layout macro tells the Configurator that our keyboard has 17 keys, arranged in five rows of four columns each. Our switch positions are named `k<row><column>`, counting from 0. The names themselves actually don't matter, as long as they match between the top section, which receives the keycodes from the keymap, and the bottom half which designates where each key is in the matrix.
+
+To display our keyboard in a way that resembles the physical keyboard, we need to build a JSON file that tells the Configurator how to tie the physical locations and sizes of our keys to our switch matrix.
+
+## Building the JSON file
+
+To build the JSON file, the easiest way is to build the layout in [Keyboard Layout Editor](http://www.keyboard-layout-editor.com/) ("KLE"), from which we'll feed the Raw Data into a QMK tool that converts this data into a JSON the Configurator will read and use. Since KLE opens by default with a numpad layout, we're just going to remove the Getting Started instructions, and use what's left.
+
+Once the layout is as desired, move to the Raw Data tab in KLE, and copy the contents:
+
+```
+["Num Lock","/","*","-"],
+["7\nHome","8\n↑","9\nPgUp",{h:2},"+"],
+["4\n←","5","6\n→"],
+["1\nEnd","2\n↓","3\nPgDn",{h:2},"Enter"],
+[{w:2},"0\nIns",".\nDel"]
+```
+
+To convert this data into our JSON, go to the [QMK KLE-JSON Converter](https://qmk.fm/converter/), paste the Raw Data into the Input field, and click the Convert button. After a moment, our JSON data will appear in the Output field. Copy the contents to a new text document, and name the document `info.json`, saving it in the same folder that contains `numpad.h`.
+
+Use the `keyboard_name` object to set the name of the keyboard. The `bootloader` object is deprecated, so it can be deleted. For instruction purposes, we will put each key's object on its own line. This is only to make the file more human-readable, and does not affect the Configurator's functionality.
+
+```json
+{
+    "keyboard_name": "Numpad",
+    "url": "",
+    "maintainer": "qmk",
+    "tags": {
+        "form_factor": "numpad"
+    },
+    "width": 4,
+    "height": 5,
+    "layouts": {
+        "LAYOUT": {
+            "layout": [
+                {"label":"Num Lock", "x":0, "y":0},
+                {"label":"/", "x":1, "y":0},
+                {"label":"*", "x":2, "y":0},
+                {"label":"-", "x":3, "y":0},
+                {"label":"7", "x":0, "y":1},
+                {"label":"8", "x":1, "y":1},
+                {"label":"9", "x":2, "y":1},
+                {"label":"+", "x":3, "y":1, "h":2},
+                {"label":"4", "x":0, "y":2},
+                {"label":"5", "x":1, "y":2},
+                {"label":"6", "x":2, "y":2},
+                {"label":"1", "x":0, "y":3},
+                {"label":"2", "x":1, "y":3},
+                {"label":"3", "x":2, "y":3},
+                {"label":"Enter", "x":3, "y":3, "h":2},
+                {"label":"0", "x":0, "y":4, "w":2},
+                {"label":".", "x":2, "y":4}
+            ]
+        }
+    }
+}
+```
+
+The `layouts` object contains the data that represents the physical layout of the keyboard. It has an object `LAYOUT`, which needs to match the name of our layout macro from `numpad.h`. The `LAYOUT` object itself has an object named `layout`, which contains one JSON object for each physical key on our keyboard, formatted as follows:
+
+```
+  ┌ The name of the key. Not displayed in the Configurator.
+  │                   ┌ The key's X-axis location, in key units from the
+  │                   │ keyboard's left edge.
+  │                   │      ┌ The key's Y-axis location, in key units from
+  │                   │      │ the keyboard's top (rear-facing) edge.
+  ↓                   ↓      ↓
+{"label":"Num Lock", "x":0, "y":0},
+```
+
+Some objects will also have `"w"` and `"h"` keys, which represent a key's width and height, respectively.
+
+?> For more on the `info.json` files, see [QMK Keyboard Guidelines: Keyboard Metadata](hardware_keyboard_guidelines.md?id=keyboard-metadata)
+
+
+## How the Configurator Programs Keys
+
+The Configurator's API uses the layout macro and the JSON file we've given it to create a visual representation of the keyboard that has each visual object tied to a specific key, in sequence:
+
+key in layout macro | JSON object used
+:---: | :----
+k00   | {"label":"Num Lock", "x":0, "y":0}
+k01   | {"label":"/", "x":1, "y":0}
+k02   | {"label":"*", "x":2, "y":0}
+k03   | {"label":"-", "x":3, "y":0}
+k10   | {"label":"7", "x":0, "y":1}
+k11   | {"label":"8", "x":1, "y":1}
+k12   | {"label":"9", "x":2, "y":1}
+k13   | {"label":"+", "x":3, "y":1, "h":2}
+k20   | {"label":"4", "x":0, "y":2}
+k21   | {"label":"5", "x":1, "y":2}
+k22   | {"label":"6", "x":2, "y":2}
+k30   | {"label":"1", "x":0, "y":3}
+k31   | {"label":"2", "x":1, "y":3}
+k32   | {"label":"3", "x":2, "y":3}
+k33   | {"label":"Enter", "x":3, "y":3, "h":2}
+k40   | {"label":"0", "x":0, "y":4, "w":2}
+k42   | {"label":".", "x":2, "y":4}
+
+When a user selects the top-left key in the Configurator, and assigns Num Lock to it, the Configurator builds a keymap file with `KC_NLCK` as the first key, and so on as the keymap is built. The `label` keys are not used; they are only for the user's reference in identifying specific keys when debugging the `info.json` file.
+
+
+## Issues and Hazards
+
+Currently, the Configurator does not support key rotation or non-rectangular key shapes like ISO Enter. Additionally, keys that are vertically-offset from their "row" &mdash; the arrow keys on 1800-layouts like the [TKC1800](https://github.com/qmk/qmk_firmware/tree/4ac48a61a66206beaf2fdd5f2939d8bbedd0004c/keyboards/tkc1800/) being a prominent example &mdash; confuse the KLE-to-JSON Converter, if not adjusted for by the contributor of the `info.json` file.
+
+### Workarounds
+
+#### Non-rectangular keys
+
+For ISO Enter keys, QMK custom is to display it as a rectangular key, 1.25u wide and 2u high, aligned so its right edge is aligned with the right edge of the alphanumeric key block.
+
+![](https://i.imgur.com/JKngtTw.png)  
+*A 60% keyboard in standard ISO layout, as rendered by QMK Configurator.*
+
+#### Vertically-offset keys
+
+For vertically-offset keys, place them in KLE as if they were not offset, then edit the Y-values as needed in the converted JSON file
+
+![](https://i.imgur.com/fmDvDzR.png)  
+*An 1800-layout keyboard as rendered in Keyboard Layout Editor, without the vertical offset applied to the arrow keys.*
+
+![](https://i.imgur.com/8beYMBR.png)  
+*A Unix diff file, showing the changes needed to vertically-offset the arrow keys in our keyboard's JSON file.*

docs/zh/README.md

@@ -0,0 +1,32 @@
+# QMK鍵盤固件
+
+[![當前版本](https://img.shields.io/github/tag/qmk/qmk_firmware.svg)](https://github.com/qmk/qmk_firmware/tags)
+[![築邦](https://travis-ci.org/qmk/qmk_firmware.svg?branch=master)](https://travis-ci.org/qmk/qmk_firmware)
+[![不和諧](https://img.shields.io/discord/440868230475677696.svg)](https://discord.gg/Uq7gcHh)
+[![文檔狀態](https://img.shields.io/badge/docs-ready-orange.svg)](https://docs.qmk.fm)
+[![GitHub的貢獻者](https://img.shields.io/github/contributors/qmk/qmk_firmware.svg)](https://github.com/qmk/qmk_firmware/pulse/monthly)
+[![GitHub的叉](https://img.shields.io/github/forks/qmk/qmk_firmware.svg?style=social&label=Fork)](https://github.com/qmk/qmk_firmware/)
+
+## 什麼是QMK固件？
+
+QMK是一個由社群維護的開源鍵盤韌體，其中包含了QMK Toolbox、qmk.fm和其它文件。QMK韌體是以[tmk\_keyboard](http://github.com/tmk/tmk_keyboard)為基礎，讓一些有用的功能在Atmel AVR控制器實現，使用於[OLKB](https://olkb.com)、[ergodox EZ](http://www.ergodox-ez.com)，和[Clueboard](http://clueboard.co/)的產品中。它也被移植到使用ChibiOS的ARM晶片上。你也可以用它來讓你徒手佈線，或是客製的鍵盤PCB發揮功能。
+
+## 如何得到QMK
+
+如果你打算貢獻鍵盤佈局，鍵盤或功能QMK，最容易做的事情是[叉通過Github上爬行](https://github.com/qmk/qmk_firmware#fork-destination-box)，和克隆你爬在本地進行更改，推動他們，然後打開從你的叉子[拉請求](https://github.com/qmk/qmk_firmware/pulls)。
+
+否則，您可以直接下載([拉鍊](https://github.com/qmk/qmk_firmware/zipball/master) [焦油](https://github.com/qmk/qmk_firmware/tarball/master))，或者通過GIT中克隆它(`git@github.com:qmk/qmk_firmware.git`)或HTTP(`https://github.com/qmk/qmk_firmware.git`)。
+
+## 如何編譯
+
+你可以編譯之前，你需要[安裝環境](getting_started_build_tools.md)用於AVR或/和ARM開發。一旦完成，你會使用`make`命令建立一個鍵盤並用以下符號鍵盤佈局
+
+    make planck/rev4:default
+
+這將建立`rev4` `planck`的修訂與`default`鍵盤映射。並非所有鍵盤有一個修訂版(也稱為子項目或文件夾)，在這種情況下，它可以被省略：
+
+    make preonic:default
+
+## 如何赶近
+
+QMK有很多[特點](features.md)探索和很好的協議[參考文獻](http://docs.qmk.fm)挖通的。大部分功能通過修改[鍵盤映射(keymap.md)，並改變[鍵碼](keycodes.md)冤大頭。

docs/zh/_sidebar.md

@@ -0,0 +1,99 @@
+* [完全指南菜鳥](zh/newbs.md)
+  * [入門](zh/newbs_getting_started.md)
+  * [構建第一個固件](zh/newbs_building_firmware.md)
+  * [刷新固件](zh/newbs_flashing.md)
+  * [測試和調試](zh/newbs_testing_debugging.md)
+  * [最佳實踐](zh/newbs_best_practices.md)
+  * [學習資源](zh/newbs_learn_more_resources.md)
+
+* [QMK基礎](zh/README.md)
+  * [QMK簡介](zh/getting_started_introduction.md)
+  * [特約QMK](zh/contributing.md)
+  * [如何使用Github上](zh/getting_started_github.md)
+  * [獲得幫助](zh/getting_started_getting_help.md)
+
+* [常問問題](zh/faq.md)
+  * [常問問題](zh/faq_general.md)
+  * [構建/編譯QMK](zh/faq_build.md)
+  * [調試/故障排除QMK](zh/faq_debug.md)
+  * [鍵盤佈局](zh/faq_keymap.md)
+
+* 詳細指南
+  * [安裝編譯工具](zh/getting_started_build_tools.md)
+  * [流浪漢指南](zh/getting_started_vagrant.md)
+  * [構建/編譯器指令](zh/getting_started_make_guide.md)
+  * [刷新固件](zh/flashing.md)
+  * [定制功能](zh/custom_quantum_functions.md)
+  * [鍵盤映射概述](zh/keymap.md)
+
+* [硬件](zh/hardware.md)
+  * [AVR處理器](zh/hardware_avr.md)
+  * [司機](zh/hardware_drivers.md)
+
+* 參考
+  * [Keyboard Guidelines](zh/hardware_keyboard_guidelines.md)
+  * [Config Options](zh/config_options.md)
+  * [Keycodes](zh/keycodes.md)
+  * [Documentation Best Practices](zh/documentation_best_practices.md)
+  * [Documentation Templates](zh/documentation_templates.md)
+  * [Glossary](zh/reference_glossary.md)
+  * [Unit Testing](zh/unit_testing.md)
+  * [Useful Functions](zh/ref_functions.md)
+  * [Configurator Support](zh/reference_configurator_support.md)
+
+* [特點](zh/features.md)
+  * [Basic Keycodes](zh/keycodes_basic.md)
+  * [Quantum Keycodes](zh/quantum_keycodes.md)
+  * [Advanced Keycodes](zh/feature_advanced_keycodes.md)
+  * [Audio](zh/feature_audio.md)
+  * [Auto Shift](zh/feature_auto_shift.md)
+  * [Backlight](zh/feature_backlight.md)
+  * [Bluetooth](zh/feature_bluetooth.md)
+  * [Bootmagic](zh/feature_bootmagic.md)
+  * [Combos](zh/feature_combo)
+  * [Command](zh/feature_command.md)
+  * [Dynamic Macros](zh/feature_dynamic_macros.md)
+  * [Encoders](zh/feature_encoders.md)
+  * [Grave Escape](zh/feature_grave_esc.md)
+  * [Key Lock](zh/feature_key_lock.md)
+  * [Layouts](zh/feature_layouts.md)
+  * [Leader Key](zh/feature_leader_key.md)
+  * [Macros](zh/feature_macros.md)
+  * [Mouse Keys](zh/feature_mouse_keys.md)
+  * [One Shot Keys](zh/feature_advanced_keycodes.md#one-shot-keys)
+  * [Pointing Device](zh/feature_pointing_device.md)
+  * [PS/2 Mouse](zh/feature_ps2_mouse.md)
+  * [RGB Lighting](zh/feature_rgblight.md)
+  * [RGB Matrix](zh/feature_rgb_matrix.md)
+  * [Space Cadet Shift](zh/feature_space_cadet_shift.md)
+  * [Space Cadet Shift Enter](zh/feature_space_cadet_shift_enter.md)
+  * [Stenography](zh/feature_stenography.md)
+  * [Swap Hands](zh/feature_swap_hands.md)
+  * [Tap Dance](zh/feature_tap_dance.md)
+  * [Terminal](zh/feature_terminal.md)
+  * [Thermal Printer](zh/feature_thermal_printer.md)
+  * [Unicode](zh/feature_unicode.md)
+  * [Userspace](zh/feature_userspace.md)
+  * [US ANSI Shifted Keys](zh/keycodes_us_ansi_shifted.md)
+
+* 對於製造商和遊戲模組
+  * [Hand Wiring Guide](zh/hand_wire.md)
+  * [ISP Flashing Guide](zh/isp_flashing_guide.md)
+  * [ARM Debugging Guide](zh/arm_debugging.md)
+  * [I2C Driver](zh/i2c_driver.md)
+
+* 為了更深入的了解
+  * [How Keyboards Work](zh/how_keyboards_work.md)
+  * [Understanding QMK](zh/understanding_qmk.md)
+
+* 其它主題
+  * [Using Eclipse with QMK](zh/eclipse.md)
+
+* QMK內部（進行中）
+  * [Defines](zh/internals_defines.md)
+  * [Input Callback Reg](zh/internals_input_callback_reg.md)
+  * [Midi Device](zh/internals_midi_device.md)
+  * [Midi Device Setup Process](zh/internals_midi_device_setup_process.md)
+  * [Midi Util](zh/internals_midi_util.md)
+  * [Send Functions](zh/internals_send_functions.md)
+  * [Sysex Tools](zh/internals_sysex_tools.md)

drivers/arm/i2c_master.c

@@ -26,6 +26,7 @@
  */
 
 #include "i2c_master.h"
+#include "quantum.h"
 #include <string.h>
 #include <hal.h>
 
@@ -41,9 +42,11 @@ static const I2CConfig i2cconfig = {
   0
 };
 
+__attribute__ ((weak))
 void i2c_init(void)
 {
-  palSetGroupMode(GPIOB, GPIOB_PIN6 | GPIOB_PIN7, 0, PAL_MODE_INPUT); // Try releasing special pins for a short time
+  setPinInput(B6); // Try releasing special pins for a short time
+  setPinInput(B7);
   chThdSleepMilliseconds(10);
 
   palSetPadMode(GPIOB, 6, PAL_MODE_ALTERNATE(4) | PAL_STM32_OTYPE_OPENDRAIN | PAL_STM32_PUPDR_PULLUP);

keyboards/1upkeyboards/1up60hse/keymaps/default/config.h

@@ -1,4 +1,5 @@
 /* Copyright 2018 MechMerlin
+ * Copyright 2018 Logan Huskins
  *
  * 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