Adjusted the linear led table and hsv_to_rgb to better handle 255 hue (#5739 )

* Adjusted the linear led table and hsv_to_rgb to better handle 255 hue * small math adjustments to better handle specific uint8_t rounding and overflows
Simple fix for selecting which tracked key press to work off of for simple reactive effects (#5745 )
2019-05-01 18:59:01 -07:00 · 2019-05-01 11:36:50 -07:00 · 2019-05-01 08:02:02 -07:00 · 2019-05-01 05:48:33 -07:00 · 2019-04-30 22:35:49 -07:00 · 2019-04-30 21:54:52 -07:00
560 changed files with 18613 additions and 8679 deletions
@@ -1,4 +1,4 @@
---
+---
 BasedOnStyle: Google
 AlignAfterOpenBracket: Align
 AlignConsecutiveAssignments: 'true'
@@ -20,7 +20,7 @@ SortIncludes: 'false'
 SpaceBeforeAssignmentOperators: 'true'
 SpaceBeforeParens: ControlStatements
 SpaceInEmptyParentheses: 'false'
-TabWidth: '2'
+TabWidth: '4'
 UseTab: Never

 ...
@@ -5,7 +5,7 @@ root = true

 [*]
 indent_style = space
-indent_size = 2
+indent_size = 4

 # We recommend you to keep these unchanged
 charset = utf-8
@@ -54,6 +54,7 @@ util/Win_Check_Output.txt
 .vscode/tasks.json
 .vscode/last.sql
 .vscode/temp.sql
+.vscode/ipch/
 .stfolder
 .tags

@@ -21,7 +21,7 @@ before_script:
  - avr-gcc --version
 script:
 - git rev-parse --short HEAD
- make test:all
+- bash util/travis_test.sh
 - bash util/travis_build.sh
 - bash util/travis_docs.sh
 addons:
@@ -280,6 +280,23 @@ ifneq ("$(wildcard $(KEYBOARD_PATH_1)/config.h)","")
    CONFIG_H += $(KEYBOARD_PATH_1)/config.h
 endif

+POST_CONFIG_H :=
+ifneq ("$(wildcard $(KEYBOARD_PATH_1)/post_config.h)","")
+    POST_CONFIG_H += $(KEYBOARD_PATH_1)/post_config.h
+endif
+ifneq ("$(wildcard $(KEYBOARD_PATH_2)/post_config.h)","")
+    POST_CONFIG_H += $(KEYBOARD_PATH_2)/post_config.h
+endif
+ifneq ("$(wildcard $(KEYBOARD_PATH_3)/post_config.h)","")
+    POST_CONFIG_H += $(KEYBOARD_PATH_3)/post_config.h
+endif
+ifneq ("$(wildcard $(KEYBOARD_PATH_4)/post_config.h)","")
+    POST_CONFIG_H += $(KEYBOARD_PATH_4)/post_config.h
+endif
+ifneq ("$(wildcard $(KEYBOARD_PATH_5)/post_config.h)","")
+    POST_CONFIG_H += $(KEYBOARD_PATH_5)/post_config.h
+endif
+
 # Save the defines and includes here, so we don't include any keymap specific ones
 PROJECT_DEFS := $(OPT_DEFS)
 PROJECT_INC := $(VPATH) $(EXTRAINCDIRS) $(KEYBOARD_PATHS)
@@ -355,6 +372,7 @@ ifeq ($(strip $(VISUALIZER_ENABLE)), yes)
    include $(VISUALIZER_PATH)/visualizer.mk
 endif

+CONFIG_H += $(POST_CONFIG_H)
 ALL_CONFIGS := $(PROJECT_CONFIG) $(CONFIG_H)

 OUTPUTS := $(KEYMAP_OUTPUT) $(KEYBOARD_OUTPUT)
@@ -103,7 +103,9 @@ ifeq ($(strip $(UNICODE_COMMON)), yes)
 endif

 ifeq ($(strip $(RGBLIGHT_ENABLE)), yes)
+    POST_CONFIG_H += $(QUANTUM_DIR)/rgblight_post_config.h
    OPT_DEFS += -DRGBLIGHT_ENABLE
+    SRC += $(QUANTUM_DIR)/color.c
    SRC += $(QUANTUM_DIR)/rgblight.c
    CIE1931_CURVE = yes
    LED_BREATHING_TABLE = yes
@@ -114,7 +116,7 @@ ifeq ($(strip $(RGBLIGHT_ENABLE)), yes)
    endif
 endif

-VALID_MATRIX_TYPES := yes IS31FL3731 IS31FL3733 IS31FL3737 custom
+VALID_MATRIX_TYPES := yes IS31FL3731 IS31FL3733 IS31FL3737 WS2812 custom

 LED_MATRIX_ENABLE ?= no
 ifneq ($(strip $(LED_MATRIX_ENABLE)), no)
@@ -172,6 +174,19 @@ ifeq ($(strip $(RGB_MATRIX_ENABLE)), IS31FL3737)
    SRC += i2c_master.c
 endif

+ifeq ($(strip $(RGB_MATRIX_ENABLE)), WS2812)
+    OPT_DEFS += -DWS2812
+    SRC += ws2812.c
+endif
+
+ifeq ($(strip $(RGB_MATRIX_CUSTOM_KB)), yes)
+    OPT_DEFS += -DRGB_MATRIX_CUSTOM_KB
+endif
+
+ifeq ($(strip $(RGB_MATRIX_CUSTOM_USER)), yes)
+    OPT_DEFS += -DRGB_MATRIX_CUSTOM_USER
+endif
+
 ifeq ($(strip $(TAP_DANCE_ENABLE)), yes)
    OPT_DEFS += -DTAP_DANCE_ENABLE
    SRC += $(QUANTUM_DIR)/process_keycode/process_tap_dance.c
@@ -313,6 +328,7 @@ ifneq ($(strip $(DEBOUNCE_TYPE)), custom)
 endif

 ifeq ($(strip $(SPLIT_KEYBOARD)), yes)
+    POST_CONFIG_H += $(QUANTUM_DIR)/split_common/post_config.h
    OPT_DEFS += -DSPLIT_KEYBOARD

    # Include files used by all split keyboards
@@ -329,3 +345,16 @@ ifeq ($(strip $(SPLIT_KEYBOARD)), yes)
    endif
    COMMON_VPATH += $(QUANTUM_PATH)/split_common
 endif
+
+ifeq ($(strip $(OLED_DRIVER_ENABLE)), yes)
+    OPT_DEFS += -DOLED_DRIVER_ENABLE
+    COMMON_VPATH += $(DRIVER_PATH)/oled
+    QUANTUM_LIB_SRC += i2c_master.c
+    SRC += oled_driver.c
+endif
+
+SPACE_CADET_ENABLE ?= yes
+ifeq ($(strip $(SPACE_CADET_ENABLE)), yes)
+  SRC += $(QUANTUM_DIR)/process_keycode/process_space_cadet.c
+  OPT_DEFS += -DSPACE_CADET_ENABLE
+endif
@@ -63,13 +63,13 @@
  * [LED Matrix](feature_led_matrix.md)
  * [Macros](feature_macros.md)
  * [Mouse Keys](feature_mouse_keys.md)
+  * [OLED Driver](feature_oled_driver)
  * [One Shot Keys](feature_advanced_keycodes.md#one-shot-keys)
  * [Pointing Device](feature_pointing_device.md)
  * [PS/2 Mouse](feature_ps2_mouse.md)
  * [RGB Lighting](feature_rgblight.md)
  * [RGB Matrix](feature_rgb_matrix.md)
-  * [Space Cadet Shift](feature_space_cadet_shift.md)
-  * [Space Cadet Shift Enter](feature_space_cadet_shift_enter.md)
+  * [Space Cadet](feature_space_cadet.md)
  * [Stenography](feature_stenography.md)
  * [Swap Hands](feature_swap_hands.md)
  * [Tap Dance](feature_tap_dance.md)
@@ -180,10 +180,12 @@ If you define these options you will enable the associated feature, which may in
  * run RGB animations
 * `#define RGBLED_NUM 12`
  * number of LEDs
+* `#define RGBLIGHT_SPLIT`
+  * Needed if both halves of the board have RGB LEDs wired directly to the RGB output pin on the controllers instead of passing the output of the left half to the input of the right half
 * `#define RGBLED_SPLIT { 6, 6 }`
  * number of LEDs connected that are directly wired to `RGB_DI_PIN` on each half of a split keyboard
  * First value indicates number of LEDs for left half, second value is for the right half
-  * Needed if both halves of the board have RGB LEDs wired directly to the RGB output pin on the controllers instead of passing the output of the left half to the input of the right half
+  * When RGBLED_SPLIT is defined, RGBLIGHT_SPLIT is implicitly defined.
 * `#define RGBLIGHT_HUE_STEP 12`
  * units to step when in/decreasing hue
 * `#define RGBLIGHT_SAT_STEP 25`
@@ -56,7 +56,7 @@ Never made an open source contribution before? Wondering how contributions work

 Most of our style is pretty easy to pick up on, but right now it's not entirely consistent. You should match the style of the code surrounding your change, but if that code is inconsistent or unclear use the following guidelines:

-* We indent using two spaces (soft tabs)
+* We indent using four (4) spaces (soft tabs)
 * We use a modified One True Brace Style
  * Opening Brace: At the end of the same line as the statement that opens the block
  * Closing Brace: Lined up with the first character of the statement that opens the block
@@ -71,6 +71,14 @@ Most of our style is pretty easy to pick up on, but right now it's not entirely
  * If you not sure if a comment is obvious, go ahead and include it.
 * In general we don't wrap lines, they can be as long as needed. If you do choose to wrap lines please do not wrap any wider than 76 columns.
 * We use `#pragma once` at the start of header files rather than old-style include guards (`#ifndef THIS_FILE_H`, `#define THIS_FILE_H`, ..., `#endif`)
+* We accept both forms of preprocessor if's: `#ifdef DEFINED` and `#if defined(DEFINED)`
+  * If you are not sure which to prefer use the `#if defined(DEFINED)` form.
+  * Do not change existing code from one style to the other, except when moving to a multiple condition `#if`.
+  * Do not put whitespace between `#` and `if`.
+  * When deciding how (or if) to indent directives keep these points in mind:
+    * Readability is more important than consistency.
+    * Follow the file's existing style. If the file is mixed follow the style that makes sense for the section you are modifying.
+    * When choosing to indent you can follow the indention level of the surrounding C code, or preprocessor directives can have their own indent level. Choose the style that best communicates the intent of your code.

 Here is an example for easy reference:

@@ -30,7 +30,31 @@ You should then be able to use the keycodes below to change the backlight level.

 This feature is distinct from both the [RGB underglow](feature_rgblight.md) and [RGB matrix](feature_rgb_matrix.md) features as it usually allows for only a single colour per switch, though you can obviously use multiple different coloured LEDs on a keyboard.

-Hardware PWM is only supported on certain pins of the MCU, so if the backlighting is not connected to one of them, a software implementation will be used, and backlight breathing will not be available. Currently the supported pins are `B5`, `B6`, `B7`, and `C6`.
+Hardware PWM is only supported on certain pins of the MCU, so if the backlighting is not connected to one of them, a software PWM implementation triggered by hardware timer interrupts will be used.
+
+Hardware PWM is supported according to the following table:
+
+| Backlight Pin | Hardware timer |
+|---------------|----------------|
+|`B5`           | Timer 1        |
+|`B6`           | Timer 1        |
+|`B7`           | Timer 1        |
+|`C6`           | Timer 3        |
+| other         | Software PWM   |
+
+The [audio feature](feature_audio.md) also uses hardware timers. Please refer to the following table to know what hardware timer the software PWM will use depending on the audio configuration:
+
+| Audio Pin(s) | Audio Timer | Software PWM Timer |
+|--------------|-------------|--------------------|
+| `C4`         | Timer 3     | Timer 1            |
+| `C5`         | Timer 3     | Timer 1            |
+| `C6`         | Timer 3     | Timer 1            |
+| `B5`         | Timer 1     | Timer 3            |
+| `B6`         | Timer 1     | Timer 3            |
+| `B7`         | Timer 1     | Timer 3            |
+| `Bx` & `Cx`  | Timer 1 & 3 | None               |
+
+When all timers are in use for [audio](feature_audio.md), the backlight software PWM will not use a hardware timer, but instead will be triggered during the matrix scan. In this case the backlight doesn't support breathing and might show lighting artifacts (for instance flickering), because the PWM computation might not be called with enough timing precision.

 ## Configuration

@@ -39,11 +63,26 @@ To change the behaviour 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|
 |`BACKLIGHT_LEVELS`   |`3`          |The number of brightness levels (maximum 15 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 hardware PWM is used                                                          |
+|`BACKLIGHT_BREATHING`|*Not defined*|Enable backlight breathing, if supported                                                          |
 |`BREATHING_PERIOD`   |`6`          |The length of one backlight "breath" in seconds                                                              |

+## Multiple backlight pins
+
+Most keyboards have only one backlight pin which control all backlight LEDs (especially if the backlight is connected to an hardware PWM pin).
+In software PWM, it is possible to define multiple backlight pins. All those pins will be turned on and off at the same time during the PWM duty cycle.
+This feature allows to set for instance the Caps Lock LED (or any other controllable LED) brightness at the same level as the other LEDs of the backlight. This is useful if you have mapped LCTRL in place of Caps Lock and you need the Caps Lock LED to be part of the backlight instead of being activated when Caps Lock is on.
+
+To activate multiple backlight pins, you need to add something like this to your user `config.h`:
+
+~~~c
+#define BACKLIGHT_LED_COUNT 2
+#undef BACKLIGHT_PIN
+#define BACKLIGHT_PINS { F5, B2 }
+~~~
+
 ## Hardware PWM Implementation

 When using the supported pins for backlighting, QMK will use a hardware timer configured to output a PWM signal. This timer will count up to `ICRx` (by default `0xFFFF`) before resetting to 0.
@@ -53,6 +92,15 @@ In this way `OCRxx` essentially controls the duty cycle of the LEDs, and thus th
 The breathing effect is achieved by registering an interrupt handler for `TIMER1_OVF_vect` that is called whenever the counter resets, roughly 244 times per second.
 In this handler, the value of an incrementing counter is mapped onto a precomputed brightness curve. To turn off breathing, the interrupt handler is simply disabled, and the brightness reset to the level stored in EEPROM.

+## Software PWM Implementation
+
+When `BACKLIGHT_PIN` is not set to a hardware backlight pin, QMK will use a hardware timer configured to trigger software interrupts. This time will count up to `ICRx` (by default `0xFFFF`) before resetting to 0.
+When resetting to 0, the CPU will fire an OVF (overflow) interrupt that will turn the LEDs on, starting the duty cycle.
+The desired brightness is calculated and stored in the `OCRxx` register. When the counter reaches this value, the CPU will fire a Compare Output match interrupt, which will turn the LEDs off.
+In this way `OCRxx` essentially controls the duty cycle of the LEDs, and thus the brightness, where `0x0000` is completely off and `0xFFFF` is completely on.
+
+The breathing effect is the same as in the hardware PWM implementation.
+
 ## Backlight Functions

 |Function  |Description                                                |
@@ -195,6 +195,49 @@ This will clear all mods currently pressed.

 This will clear all keys besides the mods currently pressed.

+## 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. 
+
+```c
+bool is_alt_tab_active = false;    # ADD this near the begining of keymap.c
+uint16_t alt_tab_timer = 0;        # we will be using them soon.
+
+enum custom_keycodes {             # Make sure have the awesome keycode ready
+  ALT_TAB = SAFE_RANGE,
+};
+
+bool process_record_user(uint16_t keycode, keyrecord_t *record) {
+  switch (keycode) {               # This will do most of the grunt work with the keycodes.
+    case ALT_TAB:
+      if (record->event.pressed) {
+        if (!is_alt_tab_active) {
+          is_alt_tab_active = true;
+          register_code(KC_LALT);
+        } 
+        alt_tab_timer = timer_read();
+        register_code(KC_TAB);
+      } else {
+        unregister_code(KC_TAB);
+      }
+      break;
+  }
+  return true;
+}
+
+void matrix_scan_user(void) {     # The very important timer. 
+  if (is_alt_tab_active) {
+    if (timer_elapsed(alt_tab_timer) > 1000) {
+      unregister_code16(LALT(KC_TAB));
+      is_alt_tab_active = false;
+    }
+  }
+}
+```
+
+---

 ##  **(DEPRECATED)** The Old Way: `MACRO()` & `action_get_macro`

@@ -273,7 +316,9 @@ const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
 ```


-### Advanced Example: Single-Key Copy/Paste
+## Advanced Example: 
+
+### Single-Key Copy/Paste

 This example defines a macro which sends `Ctrl-C` when pressed down, and `Ctrl-V` when released.

@@ -1,114 +1,119 @@
-# Mousekeys
+# Mouse keys

+Mouse keys is a feature that allows you to emulate a mouse using your keyboard. You can move the pointer at different speeds, press 5 buttons and scroll in 8 directions.

-Mousekeys is a feature that allows you to emulate a mouse using your keyboard. You can move the pointer around, click up to 5 buttons, and even scroll in all 4 directions.
+## Adding mouse keys to your keyboard

-There are 2 ways to define how the mousekeys behave, using "[auto-accelerating](#configuring-the-behavior-of-mousekeys-with-auto-accelerated-movement)" or "[3-speed constant](#configuring-the-behavior-of-mousekeys-with-3-speed-constant-movement)" behavior.
+To use mouse keys, you must at least enable mouse keys support and map mouse actions to keys on your keyboard.

-In either case, you will need to enable mousekeys in your makefile,
-and add the relevant [keycodes](#mapping-mouse-actions-to-keyboard-keys) to your keymap.
+### Enabling mouse keys

-#### Enable Mousekeys
+To enable mouse keys, add the following line to your keymap’s `rules.mk`:

-To enable the mousekey functionality, add the following line to your keymap's `rules.mk`:
-
-```
+```c
 MOUSEKEY_ENABLE = yes
 ```

-#### Mapping Mouse Actions to Keyboard Keys
+### Mapping mouse actions

-You can use these keycodes within your keymap to map button presses to mouse actions:
+In your keymap you can use the following keycodes to map key presses to mouse actions:

-|Key             |Aliases  |Description                        |
-|----------------|---------|-----------------------------------|
-|`KC_MS_UP`      |`KC_MS_U`|Mouse Cursor Up                    |
-|`KC_MS_DOWN`    |`KC_MS_D`|Mouse Cursor Down                  |
-|`KC_MS_LEFT`    |`KC_MS_L`|Mouse Cursor Left                  |
-|`KC_MS_RIGHT`   |`KC_MS_R`|Mouse Cursor Right                 |
-|`KC_MS_BTN1`    |`KC_BTN1`|Mouse Button 1                     |
-|`KC_MS_BTN2`    |`KC_BTN2`|Mouse Button 2                     |
-|`KC_MS_BTN3`    |`KC_BTN3`|Mouse Button 3                     |
-|`KC_MS_BTN4`    |`KC_BTN4`|Mouse Button 4                     |
-|`KC_MS_BTN5`    |`KC_BTN5`|Mouse Button 5                     |
-|`KC_MS_WH_UP`   |`KC_WH_U`|Mouse Wheel Up                     |
-|`KC_MS_WH_DOWN` |`KC_WH_D`|Mouse Wheel Down                   |
-|`KC_MS_WH_LEFT` |`KC_WH_L`|Mouse Wheel Left                   |
-|`KC_MS_WH_RIGHT`|`KC_WH_R`|Mouse Wheel Right                  |
-|`KC_MS_ACCEL0`  |`KC_ACL0`|Set mouse acceleration to 0(slow)  |
-|`KC_MS_ACCEL1`  |`KC_ACL1`|Set mouse acceleration to 1(medium)|
-|`KC_MS_ACCEL2`  |`KC_ACL2`|Set mouse acceleration to 2(fast)  |
+|Key             |Aliases  |Description      |
+|----------------|---------|-----------------|
+|`KC_MS_UP`      |`KC_MS_U`|Move cursor up   |
+|`KC_MS_DOWN`    |`KC_MS_D`|Move cursor down |
+|`KC_MS_LEFT`    |`KC_MS_L`|Move cursor left |
+|`KC_MS_RIGHT`   |`KC_MS_R`|Move cursor right|
+|`KC_MS_BTN1`    |`KC_BTN1`|Press button 1   |
+|`KC_MS_BTN2`    |`KC_BTN2`|Press button 2   |
+|`KC_MS_BTN3`    |`KC_BTN3`|Press button 3   |
+|`KC_MS_BTN4`    |`KC_BTN4`|Press button 4   |
+|`KC_MS_BTN5`    |`KC_BTN5`|Press button 5   |
+|`KC_MS_WH_UP`   |`KC_WH_U`|Move wheel up    |
+|`KC_MS_WH_DOWN` |`KC_WH_D`|Move wheel down  |
+|`KC_MS_WH_LEFT` |`KC_WH_L`|Move wheel left  |
+|`KC_MS_WH_RIGHT`|`KC_WH_R`|Move wheel right |
+|`KC_MS_ACCEL0`  |`KC_ACL0`|Set speed to 0   |
+|`KC_MS_ACCEL1`  |`KC_ACL1`|Set speed to 1   |
+|`KC_MS_ACCEL2`  |`KC_ACL2`|Set speed to 2   |

+## Configuring mouse keys

-## Configuring the Behavior of Mousekeys with auto-accelerated movement
+Mouse keys supports two different modes to move the cursor:

-This behavior is intended to emulate the X Window System MouseKeysAccel feature. You can read more about it [on Wikipedia](https://en.wikipedia.org/wiki/Mouse_keys).
+* **Accelerated (default):** Holding movement keys accelerates the cursor until it reaches its maximum speed.
+* **Constant:** Holding movement keys moves the cursor at constant speeds.

-The default speed for controlling the mouse with the keyboard is intentionally slow. You can adjust these parameters by adding these settings to your keymap's `config.h` file. All times are specified in milliseconds (ms).
+The same principle applies to scrolling.

-```
-#define MOUSEKEY_DELAY             300
-#define MOUSEKEY_INTERVAL          50
-#define MOUSEKEY_MAX_SPEED         10
-#define MOUSEKEY_TIME_TO_MAX       20
-#define MOUSEKEY_WHEEL_MAX_SPEED   8
-#define MOUSEKEY_WHEEL_TIME_TO_MAX 40
-```
+Configuration options that are times, intervals or delays are given in milliseconds. Scroll speed is given as multiples of the default scroll step. For example, a scroll speed of 8 means that each scroll action covers 8 times the length of the default scroll step as defined by your operating system or application.

-#### `MOUSEKEY_DELAY`
+### Accelerated mode

-When one of the mouse movement buttons is pressed this setting is used to define the delay between that button press and the mouse cursor moving. Some people find that small movements are impossible if this setting is too low, while settings that are too high feel sluggish.
+This is the default mode. You can adjust the cursor and scrolling acceleration using the following settings in your keymap’s `config.h` file:

-#### `MOUSEKEY_INTERVAL`
+|Define                      |Default|Description                                              |
+|----------------------------|-------|---------------------------------------------------------|
+|`MOUSEKEY_DELAY`            |300    |Delay between pressing a movement key and cursor movement|
+|`MOUSEKEY_INTERVAL`         |50     |Time between cursor movements                            |
+|`MOUSEKEY_MAX_SPEED`        |10     |Maximum cursor speed at which acceleration stops         |
+|`MOUSEKEY_TIME_TO_MAX`      |20     |Time until maximum cursor speed is reached               |
+|`MOUSEKEY_WHEEL_MAX_SPEED`  |8      |Maximum number of scroll steps per scroll action         |
+|`MOUSEKEY_WHEEL_TIME_TO_MAX`|40     |Time until maximum scroll speed is reached               |

-When a movement key is held down this specifies how long to wait between each movement report. Lower settings will translate into an effectively higher mouse speed.
+Tips:

-#### `MOUSEKEY_MAX_SPEED`
+* Setting `MOUSEKEY_DELAY` too low makes the cursor unresponsive. Setting it too high makes small movements difficult.
+* For smoother cursor movements, lower the value of `MOUSEKEY_INTERVAL`. If the refresh rate of your display is 60Hz, you could set it to `16` (1/60). As this raises the cursor speed significantly, you may want to lower `MOUSEKEY_MAX_SPEED`.
+* Setting `MOUSEKEY_TIME_TO_MAX` or `MOUSEKEY_WHEEL_TIME_TO_MAX` to `0` will disable acceleration for the cursor or scrolling respectively. This way you can make one of them constant while keeping the other accelerated, which is not possible in constant speed mode.

-As a movement key is held down the speed of the mouse cursor will increase until it reaches `MOUSEKEY_MAX_SPEED`.
+Cursor acceleration uses the same algorithm as the X Window System MouseKeysAccel feature. You can read more about it [on Wikipedia](https://en.wikipedia.org/wiki/Mouse_keys).

-#### `MOUSEKEY_TIME_TO_MAX`
+### Constant mode

-How long you want to hold down a movement key for until `MOUSEKEY_MAX_SPEED` is reached. This controls how quickly your cursor will accelerate.
+In this mode you can define multiple different speeds for both the cursor and the mouse wheel. There is no acceleration. `KC_ACL0`, `KC_ACL1` and `KC_ACL2` change the cursor and scroll speed to their respective setting.

-#### `MOUSEKEY_WHEEL_MAX_SPEED`
+You can choose whether speed selection is momentary or tap-to-select:

-The top speed for scrolling movements.
+* **Momentary:** The chosen speed is only active while you hold the respective key. When the key is raised, mouse keys returns to the unmodified speed.
+* **Tap-to-select:** The chosen speed is activated when you press the respective key and remains active even after the key has been raised. The default speed is that of `KC_ACL1`. There is no unmodified speed.

-#### `MOUSEKEY_WHEEL_TIME_TO_MAX`
+The default speeds from slowest to fastest are as follows:

-How long you want to hold down a scroll key for until `MOUSEKEY_WHEEL_MAX_SPEED` is reached. This controls how quickly your scrolling will accelerate.
+* **Momentary:** `KC_ACL0` < `KC_ACL1` < *unmodified* < `KC_ACL2`
+* **Tap-to-select:** `KC_ACL0` < `KC_ACL1` < `KC_ACL2`

+To use constant speed mode, you must at least define `MK_3_SPEED` in your keymap’s `config.h` file:

-## Configuring the Behavior of Mousekeys with 3-speed constant movement
-
-In your keymap's `config.h`, you must add the line:
-```
+```c
 #define MK_3_SPEED
 ```
-Then you can precisely define 3 different speeds for both the cursor and the mouse wheel, and also whether speed selection is momentary or tap-to-select.
-For each speed, you can specify how many milliseconds you want between reports(interval), and how far you want to it to move per report(offset).

-For example:
+To enable momentary mode, also define `MK_MOMENTARY_ACCEL`:

-```
-#define MK_3_SPEED
-#define MK_MOMENTARY_ACCEL // comment this out for tap-to-select acceleration
-// cursor speeds:
-#define MK_C_OFFSET_SLOW     1 // pixels
-#define MK_C_INTERVAL_SLOW 100 // milliseconds
-#define MK_C_OFFSET_MED      4
-#define MK_C_INTERVAL_MED   16
-#define MK_C_OFFSET_FAST    12
-#define MK_C_INTERVAL_FAST  16
-// scroll wheel speeds:
-#define MK_W_OFFSET_SLOW     1 // wheel clicks
-#define MK_W_INTERVAL_SLOW 400 // milliseconds
-#define MK_W_OFFSET_MED      1
-#define MK_W_INTERVAL_MED  200
-#define MK_W_OFFSET_FAST     1
-#define MK_W_INTERVAL_FAST 100
+```c
+#define MK_MOMENTARY_ACCEL
 ```

-Medium values will be used as the default or unmodified speed.
-The speed at which both the cursor and scrolling move can be selected with KC_ACL0, KC_ACL1, KC_ACL2 for slow, medium, and fast. However, if you leave MK_MOMENTARY_ACCEL defined then there is no need to ever send KC_ACL1, since that will be the unmodified speed.
+Use the following settings if you want to adjust cursor movement or scrolling:
+
+|Define               |Default      |Description                                |
+|---------------------|-------------|-------------------------------------------|
+|`MK_3_SPEED`         |*Not defined*|Enable constant cursor speeds              |
+|`MK_MOMENTARY_ACCEL` |*Not defined*|Enable momentary speed selection           |
+|`MK_C_OFFSET_UNMOD`  |16           |Cursor offset per movement (unmodified)    |
+|`MK_C_INTERVAL_UNMOD`|16           |Time between cursor movements (unmodified) |
+|`MK_C_OFFSET_0`      |1            |Cursor offset per movement (`KC_ACL0`)     |
+|`MK_C_INTERVAL_0`    |32           |Time between cursor movements (`KC_ACL0`)  |
+|`MK_C_OFFSET_1`      |4            |Cursor offset per movement (`KC_ACL1`)     |
+|`MK_C_INTERVAL_1`    |16           |Time between cursor movements (`KC_ACL1`)  |
+|`MK_C_OFFSET_2`      |32           |Cursor offset per movement (`KC_ACL2`)     |
+|`MK_C_INTERVAL_2`    |16           |Time between cursor movements (`KC_ACL2`)  |
+|`MK_W_OFFSET_UNMOD`  |1            |Scroll steps per scroll action (unmodified)|
+|`MK_W_INTERVAL_UNMOD`|40           |Time between scroll steps (unmodified)     |
+|`MK_W_OFFSET_0`      |1            |Scroll steps per scroll action (`KC_ACL0`) |
+|`MK_W_INTERVAL_0`    |360          |Time between scroll steps (`KC_ACL0`)      |
+|`MK_W_OFFSET_1`      |1            |Scroll steps per scroll action (`KC_ACL1`) |
+|`MK_W_INTERVAL_1`    |120          |Time between scroll steps (`KC_ACL1`)      |
+|`MK_W_OFFSET_2`      |1            |Scroll steps per scroll action (`KC_ACL2`) |
+|`MK_W_INTERVAL_2`    |20           |Time between scroll steps (`KC_ACL2`)      |
@@ -0,0 +1,274 @@
+# OLED Driver
+
+## OLED Supported Hardware
+
+128x32 OLED modules using SSD1306 driver IC over I2C. Supported on AVR based keyboards. Possible but untested hardware includes ARM based keyboards and other sized OLED modules using SSD1306 over I2C, such as 128x64. 
+
+!> Warning: This OLED Driver currently uses the new i2c_master driver from split common code. If your split keyboard uses i2c to communication between sides this driver could cause an address conflict (serial is fine). Please contact your keyboard vendor and ask them to migrate to the latest split common code to fix this. 
+
+## Usage
+
+To enable the OLED feature, there are three steps. First, when compiling your keyboard, you'll need to set `OLED_DRIVER_ENABLE=yes` in `rules.mk`, e.g.:
+
+```
+OLED_DRIVER_ENABLE = yes
+```
+
+This enables the feature and the `OLED_DRIVER_ENABLE` define. Then in your `keymap.c` file, you will need to implement the user task call, e.g:
+
+```C++
+#ifdef OLED_DRIVER_ENABLE
+void oled_task_user(void) {
+  // Host Keyboard Layer Status
+  oled_write_P(PSTR("Layer: "), false);
+  switch (biton32(layer_state)) {
+    case _QWERTY:
+      oled_write_P(PSTR("Default\n"), false);
+      break;
+    case _FN:
+      oled_write_P(PSTR("FN\n"), false);
+      break;
+    case _ADJ:
+      oled_write_P(PSTR("ADJ\n"), false);
+      break;
+    default:
+      // Or use the write_ln shortcut over adding '\n' to the end of your string
+      oled_write_ln_P(PSTR("Undefined"), false);
+  }
+
+  // Host Keyboard LED Status
+  uint8_t led_usb_state = host_keyboard_leds();
+  oled_write_P(led_usb_state & (1<<USB_LED_NUM_LOCK) ? PSTR("NUMLCK ") : PSTR("       "), false);
+  oled_write_P(led_usb_state & (1<<USB_LED_CAPS_LOCK) ? PSTR("CAPLCK ") : PSTR("       "), false);
+  oled_write_P(led_usb_state & (1<<USB_LED_SCROLL_LOCK) ? PSTR("SCRLCK ") : PSTR("       "), false);
+}
+#endif
+```
+
+## Logo Example
+
+In the default font, ranges in the font file are reserved for a QMK Logo. To Render this logo to the oled screen, use the following code example:
+
+```C++
+static void render_logo(void) {
+  static const char PROGMEM qmk_logo[] = {
+    0x80,0x81,0x82,0x83,0x84,0x85,0x86,0x87,0x88,0x89,0x8a,0x8b,0x8c,0x8d,0x8e,0x8f,0x90,0x91,0x92,0x93,0x94,
+    0xa0,0xa1,0xa2,0xa3,0xa4,0xa5,0xa6,0xa7,0xa8,0xa9,0xaa,0xab,0xac,0xad,0xae,0xaf,0xb0,0xb1,0xb2,0xb3,0xb4,
+    0xc0,0xc1,0xc2,0xc3,0xc4,0xc5,0xc6,0xc7,0xc8,0xc9,0xca,0xcb,0xcc,0xcd,0xce,0xcf,0xd0,0xd1,0xd2,0xd3,0xd4,0};
+
+  oled_write_P(qmk_logo, false);
+}
+```
+
+## Other Examples
+
+In split keyboards, it is very common to have two OLED displays that each render different content and oriented flipped differently. You can do this by switching which content to render by using the return from `is_keyboard_master()` or `is_keyboard_left()` found in `split_util.h`, e.g:
+
+```C++
+#ifdef OLED_DRIVER_ENABLE
+oled_rotation_t oled_init_user(oled_rotation_t rotation) {
+  if (!is_keyboard_master())
+    return OLED_ROTATION_180;  // flips the display 180 degrees if offhand
+  return rotation;
+}
+
+void oled_task_user(void) {
+  if (is_keyboard_master()) {
+    render_status();     // Renders the current keyboard state (layer, lock, caps, scroll, etc)
+  } else {
+    render_logo();       // Renders a statuc logo
+    oled_scroll_left();  // Turns on scrolling
+  }
+}
+#endif
+```
+
+
+ ## Basic Configuration
+
+|Define                 |Default        |Description                                     |
+|-----------------------|---------------|------------------------------------------------|
+|`OLED_DISPLAY_ADDRESS` |`0x3C`         |The i2c address of the OLED Display             |
+|`OLED_FONT_H`          |`"glcdfont.c"` |The font code file to use for custom fonts      |
+|`OLED_FONT_START`      |`0`            |The starting characer index for custom fonts    |
+|`OLED_FONT_END`        |`224`          |The ending characer index for custom fonts      |
+|`OLED_FONT_WIDTH`      |`6`            |The font width                                  |
+|`OLED_FONT_HEIGHT`     |`8`            |The font height (untested)                      |
+|`OLED_DISABLE_TIMEOUT` |*Not defined*  |Disables the built in OLED timeout feature. Useful when implementing custom timeout rules.|
+
+
+
+ ## 128x64 & Custom sized OLED Displays
+
+ The default display size for this feature is 128x32 and all necessary defines are precalculated with that in mind. We have added a define, `OLED_DISPLAY_128X64`, to switch all the values to be used in a 128x64 display, as well as added a custom define, `OLED_DISPLAY_CUSTOM`, that allows you to provide the necessary values to the driver.
+
+|Define                 |Default        |Description                                                      |
+|-----------------------|---------------|-----------------------------------------------------------------|
+|`OLED_DISPLAY_128X64`  |*Not defined*  |Changes the display defines for use with 128x64 displays.        |
+|`OLED_DISPLAY_CUSTOM`  |*Not defined*  |Changes the display defines for use with custom displays.<br />Requires user to implement the below defines. |
+|`OLED_DISPLAY_WIDTH`   |`128`          |The width of the OLED display.                                   |
+|`OLED_DISPLAY_HEIGHT`  |`32`           |The height of the OLED display.                                  |
+|`OLED_MATRIX_SIZE`     |`512`          |The local buffer size to allocate.<br />`(OLED_DISPLAY_HEIGHT / 8 * OLED_DISPLAY_WIDTH)`|
+|`OLED_BLOCK_TYPE`      |`uint16_t`     |The unsigned integer type to use for dirty rendering.|
+|`OLED_BLOCK_COUNT`     |`16`           |The number of blocks the display is divided into for dirty rendering.<br />`(sizeof(OLED_BLOCK_TYPE) * 8)`|
+|`OLED_BLOCK_SIZE`      |`32`           |The size of each block for dirty rendering<br />`(OLED_MATRIX_SIZE / OLED_BLOCK_COUNT)`|
+|`OLED_SOURCE_MAP`      |`{ 0, ... N }` |Precalculated source array to use for mapping source buffer to target OLED memory in 90 degree rendering.         |
+|`OLED_TARGET_MAP`      |`{ 24, ... N }`|Precalculated target array to use for mapping source buffer to target OLED memory in 90 degree rendering.         |
+
+
+### 90 Degree Rotation - Technical Mumbo Jumbo 
+
+```C
+// OLED Rotation enum values are flags
+typedef enum {
+    OLED_ROTATION_0   = 0,
+    OLED_ROTATION_90  = 1,
+    OLED_ROTATION_180 = 2,
+    OLED_ROTATION_270 = 3, // OLED_ROTATION_90 | OLED_ROTATION_180
+} oled_rotation_t;
+```
+
+ OLED displays driven by SSD1306 drivers only natively support in hard ware 0 degree and 180 degree rendering. This feature is done in software and not free. Using this feature will increase the time to calculate what data to send over i2c to the OLED. If you are strapped for cycles, this can cause keycodes to not register. In testing however, the rendering time on an `atmega32u4` board only went from 2ms to 5ms and keycodes not registering was only noticed once we hit 15ms. 
+ 
+ 90 Degree Rotated Rendering is achieved by using bitwise operations to rotate each 8 block of memory and uses two precalculated arrays to remap buffer memory to OLED memory. The memory map defines are precalculated for remap performance and are calculated based on the OLED Height, Width, and Block Size. For example, in the 128x32 implementation with a `uint8_t` block type, we have a 64 byte block size. This gives us eight 8 byte blocks that need to be rotated and rendered. The OLED renders horizontally two 8 byte blocks before moving down a page, e.g:
+
+|   |   |   |   |   |   |
+|---|---|---|---|---|---|
+| 0 | 1 |   |   |   |   |
+| 2 | 3 |   |   |   |   |
+| 4 | 5 |   |   |   |   |
+| 6 | 7 |   |   |   |   |
+
+However the local buffer is stored as if it was Height x Width display instead of Width x Height, e.g:
+
+|   |   |   |   |   |   |
+|---|---|---|---|---|---|
+| 3 | 7 |   |   |   |   |
+| 2 | 6 |   |   |   |   |
+| 1 | 5 |   |   |   |   |
+| 0 | 4 |   |   |   |   |
+
+So those precalculated arrays just index the memory offsets in the order in which each one iterates its data.
+
+## OLED API
+
+```C++
+// OLED Rotation enum values are flags
+typedef enum {
+    OLED_ROTATION_0   = 0,
+    OLED_ROTATION_90  = 1,
+    OLED_ROTATION_180 = 2,
+    OLED_ROTATION_270 = 3, // OLED_ROTATION_90 | OLED_ROTATION_180
+} oled_rotation_t;
+
+// Initialize the OLED display, rotating the rendered output based on the define passed in.
+// Returns true if the OLED was initialized successfully
+bool oled_init(oled_rotation_t rotation);
+
+// Called at the start of oled_init, weak function overridable by the user
+// rotation - the value passed into oled_init
+// Return new oled_rotation_t if you want to override default rotation
+oled_rotation_t oled_init_user(oled_rotation_t rotation);
+
+// Clears the display buffer, resets cursor position to 0, and sets the buffer to dirty for rendering
+void oled_clear(void);
+
+// Renders the dirty chunks of the buffer to OLED display
+void oled_render(void);
+
+// Moves cursor to character position indicated by column and line, wraps if out of bounds
+// Max column denoted by 'oled_max_chars()' and max lines by 'oled_max_lines()' functions
+void oled_set_cursor(uint8_t col, uint8_t line);
+
+// Advances the cursor to the next page, writing ' ' if true
+// Wraps to the begining when out of bounds
+void oled_advance_page(bool clearPageRemainder);
+
+// Moves the cursor forward 1 character length
+// Advance page if there is not enough room for the next character
+// Wraps to the begining when out of bounds
+void oled_advance_char(void);
+
+// Writes a single character to the buffer at current cursor position
+// Advances the cursor while writing, inverts the pixels if true
+// Main handler that writes character data to the display buffer
+void oled_write_char(const char data, bool invert);
+
+// Writes a string to the buffer at current cursor position
+// Advances the cursor while writing, inverts the pixels if true
+void oled_write(const char *data, bool invert);
+
+// Writes a string to the buffer at current cursor position
+// Advances the cursor while writing, inverts the pixels if true
+// Advances the cursor to the next page, wiring ' ' to the remainder of the current page
+void oled_write_ln(const char *data, bool invert);
+
+// Writes a PROGMEM string to the buffer at current cursor position
+// Advances the cursor while writing, inverts the pixels if true
+// Remapped to call 'void oled_write(const char *data, bool invert);' on ARM
+void oled_write_P(const char *data, bool invert);
+
+// Writes a PROGMEM string to the buffer at current cursor position
+// Advances the cursor while writing, inverts the pixels if true
+// Advances the cursor to the next page, wiring ' ' to the remainder of the current page
+// Remapped to call 'void oled_write_ln(const char *data, bool invert);' on ARM
+void oled_write_ln_P(const char *data, bool invert);
+
+// Can be used to manually turn on the screen if it is off
+// Returns true if the screen was on or turns on
+bool oled_on(void);
+
+// Can be used to manually turn off the screen if it is on
+// Returns true if the screen was off or turns off
+bool oled_off(void);
+
+// Basically it's oled_render, but with timeout management and oled_task_user calling!
+void oled_task(void);
+
+// Called at the start of oled_task, weak function overridable by the user
+void oled_task_user(void);
+
+// Scrolls the entire display right
+// Returns true if the screen was scrolling or starts scrolling
+// NOTE: display contents cannot be changed while scrolling
+bool oled_scroll_right(void);
+
+// Scrolls the entire display left
+// Returns true if the screen was scrolling or starts scrolling
+// NOTE: display contents cannot be changed while scrolling
+bool oled_scroll_left(void);
+
+// Turns off display scrolling
+// Returns true if the screen was not scrolling or stops scrolling
+bool oled_scroll_off(void);
+
+// Returns the maximum number of characters that will fit on a line
+uint8_t oled_max_chars(void);
+
+// Returns the maximum number of lines that will fit on the OLED
+uint8_t oled_max_lines(void);
+```
+
+## SSD1306.h driver conversion guide
+
+|Old API                    |Recommended New API                |
+|---------------------------|-----------------------------------|
+|`struct CharacterMatrix`   |*removed - delete all references*  |
+|`iota_gfx_init`            |`oled_init`                        |
+|`iota_gfx_on`              |`oled_on`                          |
+|`iota_gfx_off`             |`oled_off`                         |
+|`iota_gfx_flush`           |`oled_render`                      |
+|`iota_gfx_write_char`      |`oled_write_char`                  |
+|`iota_gfx_write`           |`oled_write`                       |
+|`iota_gfx_write_P`         |`oled_write_P`                     |
+|`iota_gfx_clear_screen`    |`oled_clear`                       |
+|`matrix_clear`             |*removed - delete all references*  |
+|`matrix_write_char_inner`  |`oled_write_char`                  |
+|`matrix_write_char`        |`oled_write_char`                  |
+|`matrix_write`             |`oled_write`                       |
+|`matrix_write_ln`          |`oled_write_ln`                    |
+|`matrix_write_P`           |`oled_write_P`                     |
+|`matrix_write_ln_P`        |`oled_write_ln_P`                  |
+|`matrix_render`            |`oled_render`                      |
+|`iota_gfx_task`            |`oled_task`                        |
+|`iota_gfx_task_user`       |`oled_task_user`                   |
@@ -5,7 +5,7 @@ This feature allows you to use RGB LED matrices driven by external drivers. It h
 If you want to use single color LED's you should use the [LED Matrix Subsystem](feature_led_matrix.md) instead.

 ## Driver configuration
-
+---
 ### IS31FL3731

 There is basic support for addressable RGB matrix lighting with the I2C IS31FL3731 RGB controller. To enable it, add this to your `rules.mk`:
@@ -52,6 +52,7 @@ const is31_led g_is31_leds[DRIVER_LED_TOTAL] = {

 Where `Cx_y` is the location of the LED in the matrix defined by [the datasheet](http://www.issi.com/WW/pdf/31FL3731.pdf) and the header file `drivers/issi/is31fl3731.h`. The `driver` is the index of the driver you defined in your `config.h` (`0` or `1` right now).

+---
 ###  IS31FL3733/IS31FL3737

 !> For the IS31FL3737, replace all instances of `IS31FL3733` below with `IS31FL3737`.
@@ -102,30 +103,63 @@ const is31_led g_is31_leds[DRIVER_LED_TOTAL] = {

 Where `X_Y` is the location of the LED in the matrix defined by [the datasheet](http://www.issi.com/WW/pdf/31FL3733.pdf) and the header file `drivers/issi/is31fl3733.h`. The `driver` is the index of the driver you defined in your `config.h` (Only `0` right now).

-From this point forward the configuration is the same for all the drivers. 
+---
+
+### WS2812 (AVR only)
+
+There is basic support for addressable RGB matrix lighting with a WS2811/WS2812{a,b,c} addressable LED strand. To enable it, add this to your `rules.mk`:

 ```C
-const rgb_led g_rgb_leds[DRIVER_LED_TOTAL] = {
+RGB_MATRIX_ENABLE = WS2812
+```
+
+Configure the hardware via your `config.h`:
+
+```C
+// The pin connected to the data pin of the LEDs
+#define RGB_DI_PIN D7
+// The number of LEDs connected
+#define DRIVER_LED_TOTAL 70
+```
+
+---
+
+From this point forward the configuration is the same for all the drivers. The struct rgb_led array tells the system for each led, what key electrical matrix it represents, what the physical position is on the board, and if the led is for a modifier key or not. Here is a brief example:
+
+```C
+rgb_led g_rgb_leds[DRIVER_LED_TOTAL] = {
 /*  {row | col << 4}
    *    |         {x=0..224, y=0..64}
-    *    |            |              modifier
+    *    |            |              flags
    *    |            |                | */
    {{0|(0<<4)},   {20.36*0, 21.33*0}, 1},
-    {{0|(1<<4)},   {20.36*1, 21.33*0}, 1},
+    {{0|(1<<4)},   {20.36*1, 21.33*0}, 4},
    ....
 }
 ```

-The format for the matrix position used in this array is `{row | (col << 4)}`. The `x` is between (inclusive) 0-224, and `y` is between (inclusive) 0-64. The easiest way to calculate these positions is:
+The first part, `{row | col << 4}`, tells the system what key this LED represents by using the key's electrical matrix row & col. The second part, `{x=0..224, y=0..64}` represents the LED's physical position on the keyboard. The `x` is between (inclusive) 0-224, and `y` is between (inclusive) 0-64 as the effects are based on this range. The easiest way to calculate these positions is imagine your keyboard is a grid, and the top left of the keyboard represents x, y coordinate 0, 0 and the bottom right of your keyboard represents 224, 64. Using this as a basis, you can use the following formula to calculate the physical position:

 ```C
-x = 224 / ( NUMBER_OF_COLS - 1 ) * ROW_POSITION
-y = 64 / (NUMBER_OF_ROWS - 1 ) * COL_POSITION
+x = 224 / (NUMBER_OF_COLS - 1) * COL_POSITION
+y =  64 / (NUMBER_OF_ROWS - 1) * ROW_POSITION
 ```

-Where all variables are decimels/floats.
+Where NUMBER_OF_COLS, NUMBER_OF_ROWS, COL_POSITION, & ROW_POSITION are all based on the physical layout of your keyboard, not the electrical layout.

-`modifier` is a boolean, whether or not a certain key is considered a modifier (used in some effects).
+`flags` is a bitmask, whether or not a certain LEDs is of a certain type. It is recommended that LEDs are set to only 1 type.
+
+## Flags
+
+|Define                              |Description                                |
+|------------------------------------|-------------------------------------------|
+|`#define HAS_FLAGS(bits, flags)`    |Returns true if `bits` has all `flags` set.|
+|`#define HAS_ANY_FLAGS(bits, flags)`|Returns true if `bits` has any `flags` set.|
+|`#define LED_FLAG_NONE      0x00`   |If thes LED has no flags.                  |
+|`#define LED_FLAG_ALL       0xFF`   |If thes LED has all flags.                 |
+|`#define LED_FLAG_MODIFIER  0x01`   |If the Key for this LED is a modifier.     |
+|`#define LED_FLAG_UNDERGLOW 0x02`   |If the LED is for underglow.               |
+|`#define LED_FLAG_KEYLIGHT  0x04`   |If the LED is for key backlight.           |

 ## Keycodes

@@ -155,7 +189,7 @@ enum rgb_matrix_effects {
    RGB_MATRIX_GRADIENT_UP_DOWN,    // Static gradient top to bottom, speed controls how much gradient changes
    RGB_MATRIX_BREATHING,           // Single hue brightness cycling animation
    RGB_MATRIX_CYCLE_ALL,           // Full keyboard solid hue cycling through full gradient
-    RGB_MATRIX_CYCLE_LEFT_RIGHT,    // Full gradient scrolling left to right 
+    RGB_MATRIX_CYCLE_LEFT_RIGHT,    // Full gradient scrolling left to right
    RGB_MATRIX_CYCLE_UP_DOWN,       // Full gradient scrolling top to bottom
    RGB_MATRIX_RAINBOW_MOVING_CHEVRON,  // Full gradent Chevron shapped scrolling left to right
    RGB_MATRIX_DUAL_BEACON,         // Full gradient spinning around center of keyboard
@@ -167,6 +201,12 @@ enum rgb_matrix_effects {
 #if defined(RGB_MATRIX_KEYPRESSES) || defined(RGB_MATRIX_KEYRELEASES)
    RGB_MATRIX_SOLID_REACTIVE_SIMPLE,   // Pulses keys hit to hue & value then fades value out
    RGB_MATRIX_SOLID_REACTIVE,      // Static single hue, pulses keys hit to shifted hue then fades to current hue
+    RGB_MATRIX_SOLID_REACTIVE_WIDE       // Hue & value pulse near a single key hit then fades value out
+    RGB_MATRIX_SOLID_REACTIVE_MULTIWIDE  // Hue & value pulse near multiple key hits then fades value out
+    RGB_MATRIX_SOLID_REACTIVE_CROSS      // Hue & value pulse the same column and row of a single key hit then fades value out
+    RGB_MATRIX_SOLID_REACTIVE_MULTICROSS // Hue & value pulse the same column and row of multiple key hits then fades value out
+    RGB_MATRIX_SOLID_REACTIVE_NEXUS      // Hue & value pulse away on the same column and row of a single key hit then fades value out
+    RGB_MATRIX_SOLID_REACTIVE_MULTINEXUS // Hue & value pulse away on the same column and row of multiple key hits then fades value out
    RGB_MATRIX_SPLASH,              // Full gradient & value pulse away from a single key hit then fades value out
    RGB_MATRIX_MULTISPLASH,         // Full gradient & value pulse away from multiple key hits then fades value out
    RGB_MATRIX_SOLID_SPLASH,        // Hue & value pulse away from a single key hit then fades value out
@@ -175,44 +215,122 @@ enum rgb_matrix_effects {
    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_GRADIENT_UP_DOWN`      |Disables `RGB_MATRIX_GRADIENT_UP_DOWN`      |
-|`#define DISABLE_RGB_MATRIX_BREATHING`             |Disables `RGB_MATRIX_BREATHING`             |
-|`#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_MOVING_CHEVRON`|Disables `RGB_MATRIX_RAINBOW_MOVING_CHEVRON`|
-|`#define DISABLE_RGB_MATRIX_DUAL_BEACON`           |Disables `RGB_MATRIX_DUAL_BEACON`           |
-|`#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_RAINDROPS`             |Disables `RGB_MATRIX_RAINDROPS`             |
-|`#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_SOLID_REACTIVE_SIMPLE` |Disables `RGB_MATRIX_SOLID_REACTIVE_SIMPLEE`|
-|`#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`     |
+|Define                                                 |Description                                    |
+|-------------------------------------------------------|-----------------------------------------------|
+|`#define DISABLE_RGB_MATRIX_ALPHAS_MODS`               |Disables `RGB_MATRIX_ALPHAS_MODS`              |
+|`#define DISABLE_RGB_MATRIX_GRADIENT_UP_DOWN`          |Disables `RGB_MATRIX_GRADIENT_UP_DOWN`         |
+|`#define DISABLE_RGB_MATRIX_BREATHING`                 |Disables `RGB_MATRIX_BREATHING`                |
+|`#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_MOVING_CHEVRON`    |Disables `RGB_MATRIX_RAINBOW_MOVING_CHEVRON`   |
+|`#define DISABLE_RGB_MATRIX_DUAL_BEACON`               |Disables `RGB_MATRIX_DUAL_BEACON`              |
+|`#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_RAINDROPS`                 |Disables `RGB_MATRIX_RAINDROPS`                |
+|`#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_SOLID_REACTIVE_SIMPLE`     |Disables `RGB_MATRIX_SOLID_REACTIVE_SIMPLE`    |
+|`#define DISABLE_RGB_MATRIX_SOLID_REACTIVE_WIDE`       |Disables `RGB_MATRIX_SOLID_REACTIVE_WIDE`      |
+|`#define DISABLE_RGB_MATRIX_SOLID_REACTIVE_MULTIWIDE`  |Disables `RGB_MATRIX_SOLID_REACTIVE_MULTIWIDE` |
+|`#define DISABLE_RGB_MATRIX_SOLID_REACTIVE_CROSS`      |Disables `RGB_MATRIX_SOLID_REACTIVE_CROSS`     |
+|`#define DISABLE_RGB_MATRIX_SOLID_REACTIVE_MULTICROSS` |Disables `RGB_MATRIX_SOLID_REACTIVE_MULTICROSS`|
+|`#define DISABLE_RGB_MATRIX_SOLID_REACTIVE_NEXUS`      |Disables `RGB_MATRIX_SOLID_REACTIVE_NEXUS`     |
+|`#define DISABLE_RGB_MATRIX_SOLID_REACTIVE_MULTINEXUS` |Disables `RGB_MATRIX_SOLID_REACTIVE_MULTINEXUS`|
+|`#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
+## Custom RGB Matrix Effects

-Custom layer effects can be done by defining this in your `<keyboard>.c`:
+By setting `RGB_MATRIX_CUSTOM_USER` (and/or `RGB_MATRIX_CUSTOM_KB`) in `rule.mk`, new effects can be defined directly from userspace, without having to edit any QMK core files.
+
+To declare new effects, create a new `rgb_matrix_user/kb.inc` that looks something like this:
+
+`rgb_matrix_user.inc` should go in the root of the keymap directory.
+`rgb_matrix_kb.inc` should go in the root of the keyboard directory.

 ```C
-void rgb_matrix_indicators_kb(void) {
-    rgb_matrix_set_color(index, red, green, blue);
+// !!! DO NOT ADD #pragma once !!! //
+
+// Step 1.
+// Declare custom effects using the RGB_MATRIX_EFFECT macro
+// (note the lack of semicolon after the macro!)
+RGB_MATRIX_EFFECT(my_cool_effect)
+RGB_MATRIX_EFFECT(my_cool_effect2)
+
+// Step 2.
+// Define effects inside the `RGB_MATRIX_CUSTOM_EFFECT_IMPLS` ifdef block
+#ifdef RGB_MATRIX_CUSTOM_EFFECT_IMPLS
+
+// e.g: A simple effect, self-contained within a single method
+static bool my_cool_effect(effect_params_t* params) {
+  RGB_MATRIX_USE_LIMITS(led_min, led_max);
+  for (uint8_t i = led_min; i < led_max; i++) {
+    rgb_matrix_set_color(i, 0xff, 0xff, 0x00);
+  }
+  return led_max < DRIVER_LED_TOTAL;
 }
+
+// e.g: A more complex effect, relying on external methods and state, with
+// dedicated init and run methods
+static uint8_t some_global_state;
+static void my_cool_effect2_complex_init(effect_params_t* params) {
+  some_global_state = 1;
+}
+static bool my_cool_effect2_complex_run(effect_params_t* params) {
+  RGB_MATRIX_USE_LIMITS(led_min, led_max);
+  for (uint8_t i = led_min; i < led_max; i++) {
+    rgb_matrix_set_color(i, 0xff, some_global_state++, 0xff);
+  }
+
+  return led_max < DRIVER_LED_TOTAL;
+}
+static bool my_cool_effect2(effect_params_t* params) {
+  if (params->init) my_cool_effect2_complex_init(params);
+  return my_cool_effect2_complex_run(params);
+}
+
+#endif // RGB_MATRIX_CUSTOM_EFFECT_IMPLS
 ```

-A similar function works in the keymap as `rgb_matrix_indicators_user`.
+For inspiration and examples, check out the built-in effects under `quantum/rgb_matrix_animation/`
+
+
+## Colors
+
+These are shorthands to popular colors. The `RGB` ones can be passed to the `setrgb` functions, while the `HSV` ones to the `sethsv` functions.
+
+|RGB                |HSV                |
+|-------------------|-------------------|
+|`RGB_WHITE`        |`HSV_WHITE`        |
+|`RGB_RED`          |`HSV_RED`          |
+|`RGB_CORAL`        |`HSV_CORAL`        |
+|`RGB_ORANGE`       |`HSV_ORANGE`       |
+|`RGB_GOLDENROD`    |`HSV_GOLDENROD`    |
+|`RGB_GOLD`         |`HSV_GOLD`         |
+|`RGB_YELLOW`       |`HSV_YELLOW`       |
+|`RGB_CHARTREUSE`   |`HSV_CHARTREUSE`   |
+|`RGB_GREEN`        |`HSV_GREEN`        |
+|`RGB_SPRINGGREEN`  |`HSV_SPRINGGREEN`  |
+|`RGB_TURQUOISE`    |`HSV_TURQUOISE`    |
+|`RGB_TEAL`         |`HSV_TEAL`         |
+|`RGB_CYAN`         |`HSV_CYAN`         |
+|`RGB_AZURE`        |`HSV_AZURE`        |
+|`RGB_BLUE`         |`HSV_BLUE`         |
+|`RGB_PURPLE`       |`HSV_PURPLE`       |
+|`RGB_MAGENTA`      |`HSV_MAGENTA`      |
+|`RGB_PINK`         |`HSV_PINK`         |
+
+These are defined in [`rgblight_list.h`](https://github.com/qmk/qmk_firmware/blob/master/quantum/rgblight_list.h). Feel free to add to this list!
+

 ## Additional `config.h` Options

@@ -231,10 +349,10 @@ A similar function works in the keymap as `rgb_matrix_indicators_user`.
 The EEPROM for it is currently shared with the RGBLIGHT system (it's generally assumed only one RGB would be used at a time), but could be configured to use its own 32bit address with:

 ```C
-#define EECONFIG_RGB_MATRIX (uint32_t *)16
+#define EECONFIG_RGB_MATRIX (uint32_t *)28
 ```

-Where `16` is an unused index from `eeconfig.h`.
+Where `28` is an unused index from `eeconfig.h`.

 ## Suspended state

@@ -75,6 +75,7 @@ Your RGB lighting can be configured by placing these `#define`s in your `config.
 |`RGBLIGHT_VAL_STEP`  |`17`         |The number of steps to increment the brightness by                           |
 |`RGBLIGHT_LIMIT_VAL` |`255`        |The maximum brightness level                                                 |
 |`RGBLIGHT_SLEEP`     |*Not defined*|If defined, the RGB lighting will be switched off when the host goes to sleep|
+|`RGBLIGHT_SPLIT`     |*Not defined*|If defined, synchronization functionality for split keyboards is added|

 ## Animations

@@ -144,7 +145,7 @@ const uint8_t RGBLED_SNAKE_INTERVALS[] PROGMEM = {100, 50, 20};
 const uint8_t RGBLED_KNIGHT_INTERVALS[] PROGMEM = {127, 63, 31};

 // These control which hues are selected for each of the "Static gradient" modes
-const uint16_t RGBLED_GRADIENT_RANGES[] PROGMEM = {360, 240, 180, 120, 90};
+const uint8_t RGBLED_GRADIENT_RANGES[] PROGMEM = {255, 170, 127, 85, 64};
 ```

 ## Functions
@@ -190,7 +191,40 @@ If you need to change your RGB lighting in code, for example in a macro to chang
 |`rgblight_decrease_val_noeeprom()`          |Decrease the value for all LEDs. This wraps around at minimum value (not written to EEPROM)                                                                   |
 |`rgblight_set_clipping_range(pos, num)`     |Set clipping Range                                                                                                                                            |

-Additionally, [`rgblight_list.h`](https://github.com/qmk/qmk_firmware/blob/master/quantum/rgblight_list.h) defines several predefined shortcuts for various colors. Feel free to add to this list!
+## Colors
+
+These are shorthands to popular colors. The `RGB` ones can be passed to the `setrgb` functions, while the `HSV` ones to the `sethsv` functions.
+
+|RGB                |HSV                |
+|-------------------|-------------------|
+|`RGB_WHITE`        |`HSV_WHITE`        |
+|`RGB_RED`          |`HSV_RED`          |
+|`RGB_CORAL`        |`HSV_CORAL`        |
+|`RGB_ORANGE`       |`HSV_ORANGE`       |
+|`RGB_GOLDENROD`    |`HSV_GOLDENROD`    |
+|`RGB_GOLD`         |`HSV_GOLD`         |
+|`RGB_YELLOW`       |`HSV_YELLOW`       |
+|`RGB_CHARTREUSE`   |`HSV_CHARTREUSE`   |
+|`RGB_GREEN`        |`HSV_GREEN`        |
+|`RGB_SPRINGGREEN`  |`HSV_SPRINGGREEN`  |
+|`RGB_TURQUOISE`    |`HSV_TURQUOISE`    |
+|`RGB_TEAL`         |`HSV_TEAL`         |
+|`RGB_CYAN`         |`HSV_CYAN`         |
+|`RGB_AZURE`        |`HSV_AZURE`        |
+|`RGB_BLUE`         |`HSV_BLUE`         |
+|`RGB_PURPLE`       |`HSV_PURPLE`       |
+|`RGB_MAGENTA`      |`HSV_MAGENTA`      |
+|`RGB_PINK`         |`HSV_PINK`         |
+
+```c
+rgblight_setrgb(RGB_ORANGE);
+rgblight_sethsv_noeeprom(HSV_GREEN);
+rgblight_setrgb_at(RGB_GOLD, 3);
+rgblight_sethsv_range(HSV_WHITE, 0, 6);
+```
+
+These are defined in [`rgblight_list.h`](https://github.com/qmk/qmk_firmware/blob/master/quantum/rgblight_list.h). Feel free to add to this list!
+

 ## Changing the order of the LEDs

@@ -0,0 +1,59 @@
+# Space Cadet: The Future, Built In
+
+Steve Losh described the [Space Cadet Shift](http://stevelosh.com/blog/2012/10/a-modern-space-cadet/) quite well. Essentially, when you tap Left Shift on its own, you get an opening parenthesis; tap Right Shift on its own and you get the closing one. When held, the Shift keys function as normal. Yes, it's as cool as it sounds, and now even cooler supporting Control and Alt as well!
+
+## Usage
+
+Firstly, in your keymap, do one of the following:
+- Replace the Left Shift key with `KC_LSPO` (Left Shift, Parenthesis Open), and Right Shift with `KC_RSPC` (Right Shift, Parenthesis Close).
+- Replace the Left Control key with `KC_LCPO` (Left Control, Parenthesis Open), and Right Control with `KC_RCPC` (Right Control, Parenthesis Close).
+- Replace the Left Alt key with `KC_LAPO` (Left Alt, Parenthesis Open), and Right Alt with `KC_RAPC` (Right Alt, Parenthesis Close).
+- Replace any Shift key in your keymap with `KC_SFTENT` (Right Shift, Enter).
+
+## Keycodes
+
+|Keycode    |Description                                |
+|-----------|-------------------------------------------|
+|`KC_LSPO`  |Left Shift when held, `(` when tapped      |
+|`KC_RSPC`  |Right Shift when held, `)` when tapped     |
+|`KC_LCPO`  |Left Control when held, `(` when tapped    |
+|`KC_RCPC`  |Right Control when held, `)` when tapped   |
+|`KC_LAPO`  |Left Alt when held, `(` when tapped        |
+|`KC_RAPC`  |Right Alt when held, `)` when tapped       |
+|`KC_SFTENT`|Right Shift when held, `Enter` when tapped |
+
+## Caveats
+
+Space Cadet's functionality can conflict with the default Command functionality when both Shift keys are held at the same time. See the [Command feature](feature_command.md) for info on how to change it, or make sure that Command is disabled in your `rules.mk` with:
+
+```make
+COMMAND_ENABLE = no
+```
+
+## Configuration
+
+By default Space Cadet assumes a US ANSI layout, but if your layout uses different keys for parentheses, you can redefine them in your `config.h`. In addition, you can redefine the modifier to send on tap, or even send no modifier at all. The new configuration defines bundle all options up into a single define of 3 key codes in this order: the `Modifier` when held or when used with other keys, the `Tap Modifer` sent when tapped (no modifier if `KC_TRNS`), finally the `Keycode` sent when tapped. Now keep in mind, mods from other keys will still apply to the `Keycode` if say `KC_RSFT` is held while tapping `KC_LSPO` key with `KC_TRNS` as the `Tap Modifer`.
+
+|Define          |Default                        |Description                                                                      |
+|----------------|-------------------------------|---------------------------------------------------------------------------------|
+|`LSPO_KEYS`     |`KC_LSFT, LSPO_MOD, LSPO_KEY`  |Send `KC_LSFT` when held, the mod and  key defined by `LSPO_MOD` and `LSPO_KEY`. |
+|`RSPC_KEYS`     |`KC_RSFT, RSPC_MOD, RSPC_KEY`  |Send `KC_RSFT` when held, the mod and  key defined by `RSPC_MOD` and `RSPC_KEY`. |
+|`LCPO_KEYS`     |`KC_LCTL, KC_LCTL, KC_9`       |Send `KC_LCTL` when held, the mod `KC_LCTL` with the key `KC_9` when tapped.     |
+|`RCPO_KEYS`     |`KC_RCTL, KC_RCTL, KC_0`       |Send `KC_RCTL` when held, the mod `KC_RCTL` with the key `KC_0` when tapped.     |
+|`LAPO_KEYS`     |`KC_LALT, KC_LALT, KC_9`       |Send `KC_LALT` when held, the mod `KC_LALT` with the key `KC_9` when tapped.     |
+|`RAPO_KEYS`     |`KC_RALT, KC_RALT, KC_0`       |Send `KC_RALT` when held, the mod `KC_RALT` with the key `KC_0` when tapped.     |
+|`SFTENT_KEYS`   |`KC_RSFT, KC_TRNS, SFTENT_KEY` |Send `KC_RSFT` when held, no mod with the key `SFTENT_KEY` when tapped.          |
+
+
+## Obsolete Configuration
+
+These defines are used in the above defines internally to support backwards compatibility, so you may continue to use them, however the above defines open up a larger range of flexibility than before. As an example, say you want to not send any modifier when you tap just `KC_LSPO`, with the old defines you had an all or nothing choice of using the `DISABLE_SPACE_CADET_MODIFIER` define. Now you can define that key as: `#define KC_LSPO_KEYS KC_LSFT, KC_TRNS, KC_9`. This tells the system to set Left Shift if held or used with other keys, then on tap send no modifier (transparent) with the `KC_9`
+
+|Define                        |Default      |Description                                                       |
+|------------------------------|-------------|------------------------------------------------------------------|
+|`LSPO_KEY`                    |`KC_9`       |The keycode to send when Left Shift is tapped                     |
+|`RSPC_KEY`                    |`KC_0`       |The keycode to send when Right Shift is tapped                    |
+|`LSPO_MOD`                    |`KC_LSFT`    |The modifier to apply to `LSPO_KEY`                               |
+|`RSPC_MOD`                    |`KC_RSFT`    |The modifier to apply to `RSPC_KEY`                               |
+|`SFTENT_KEY`                  |`KC_ENT`     |The keycode to send when the Shift key is tapped                  |
+|`DISABLE_SPACE_CADET_MODIFIER`|*Not defined*|If defined, prevent the Space Cadet from applying a modifier      |
@@ -1,37 +0,0 @@
-# Space Cadet Shift: The Future, Built In
-
-Steve Losh described the [Space Cadet Shift](http://stevelosh.com/blog/2012/10/a-modern-space-cadet/) quite well. Essentially, when you tap Left Shift on its own, you get an opening parenthesis; tap Right Shift on its own and you get the closing one. When held, the Shift keys function as normal. Yes, it's as cool as it sounds.
-
-## Usage
-
-Replace the Left Shift key in your keymap with `KC_LSPO` (Left Shift, Parenthesis Open), and Right Shift with `KC_RSPC` (Right Shift, Parenthesis Close).
-
-## Keycodes
-
-|Keycode  |Description                           |
-|---------|--------------------------------------|
-|`KC_LSPO`|Left Shift when held, `(` when tapped |
-|`KC_RSPC`|Right Shift when held, `)` when tapped|
-
-## Caveats
-
-Space Cadet's functionality can conflict with the default Command functionality when both Shift keys are held at the same time. Make sure that Command is disabled in your `rules.mk` with:
-
-```make
-COMMAND_ENABLE = no
-```
-
-## Configuration
-
-By default Space Cadet assumes a US ANSI layout, but if your layout uses different keys for parentheses, you can redefine them in your `config.h`.
-You can also disable the rollover, allowing you to use the opposite Shift key to cancel the Space Cadet state in the event of an erroneous press, instead of emitting a pair of parentheses when the keys are released.
-Also, by default, the Space Cadet applies modifiers LSPO_MOD and RSPC_MOD to keys defined by LSPO_KEY and RSPC_KEY. You can override this behavior by redefining those variables in your `config.h`. You can also prevent the Space Cadet to apply a modifier by defining DISABLE_SPACE_CADET_MODIFIER in your `config.h`.
-
-|Define                        |Default      |Description                                                                     |
-|------------------------------|-------------|--------------------------------------------------------------------------------|
-|`LSPO_KEY`                    |`KC_9`       |The keycode to send when Left Shift is tapped                                   |
-|`RSPC_KEY`                    |`KC_0`       |The keycode to send when Right Shift is tapped                                  |
-|`LSPO_MOD`                    |`KC_LSFT`    |The keycode to send when Left Shift is tapped                                   |
-|`RSPC_MOD`                    |`KC_RSFT`    |The keycode to send when Right Shift is tapped                                  |
-|`DISABLE_SPACE_CADET_ROLLOVER`|*Not defined*|If defined, use the opposite Shift key to cancel Space Cadet                    |
-|`DISABLE_SPACE_CADET_MODIFIER`|*Not defined*|If defined, prevent the Space Cadet to apply a modifier to LSPO_KEY and RSPC_KEY|
@@ -1,31 +0,0 @@
-# Space Cadet Shift Enter
-
-Based on the [Space Cadet Shift](feature_space_cadet_shift.md) feature. Tap the Shift key on its own, and it behaves like Enter. When held, the Shift functions as normal.
-
-## Usage
-
-Replace any Shift key in your keymap with `KC_SFTENT` (Shift, Enter), and you're done.
-
-## Keycodes
-
-|Keycode    |Description                             |
-|-----------|----------------------------------------|
-|`KC_SFTENT`|Right Shift when held, Enter when tapped|
-
-## Caveats
-
-As with Space Cadet Shift, this feature may conflict with Command, so it should be disabled in your `rules.mk` with:
-
-```make
-COMMAND_ENABLE = no
-```
-
-This feature also uses the same timers as Space Cadet Shift, so using them in tandem may produce strange results.
-
-## Configuration
-
-By default Space Cadet assumes a US ANSI layout, but if you'd like to use a different key for Enter, you can redefine it in your `config.h`:
-
-|Define      |Default |Description                                     |
-|------------|--------|------------------------------------------------|
-|`SFTENT_KEY`|`KC_ENT`|The keycode to send when the Shift key is tapped|
@@ -198,15 +198,17 @@ From here, you should have a working keyboard once you program a firmware. Befor

 To start out, download [the firmware](https://github.com/qmk/qmk_firmware/) - we'll be using my (Jack's) fork of TMK called QMK/Quantum. We'll be doing a lot from the Terminal/command prompt, so get that open, along with a decent text editor like [Sublime Text](http://www.sublimetext.com/) (paid) or [Visual Studio Code](https://code.visualstudio.com) (free).

-The first thing we're going to do is create a new project using the script in the root directory of the firmware. In your terminal, run this command with `<project_name>` replaced by the name of your project - it'll need to be different from any other project in the `keyboards/` folder:
+The first thing we're going to do is create a new keyboard. In your terminal, run this command, which will ask you some questions and generate a basic keyboard project:

 ```
-    util/new_project.sh <project_name>
+./util/new_keyboard.sh
 ```

 You'll want to navigate to the `keyboards/<project_name>/` folder by typing, like the print-out from the script specifies:

-    cd keyboards/<project_name>
+```
+cd keyboards/<project_name>
+```

 ### `config.h`

@@ -326,7 +328,7 @@ Carefully flip your keyboard over, open up a new text document, and try typing -
 2. Check the solder joints on the diode - if the diode is loose, part of your row may register, while the other may not.
 3. Check the solder joints on the columns - if your column wiring is loose, part or all of the column may not work.
 4. Check the solder joints on both sides of the wires going to/from the Teensy - the wires need to be fully soldered and connect to both sides.
-5. Check the <project_name>.h file for errors and incorrectly placed `KC_NO`s - if you're unsure where they should be, instead duplicate a k*xy* variable.
+5. Check the `<project_name>.h` file for errors and incorrectly placed `KC_NO`s - if you're unsure where they should be, instead duplicate a k*xy* variable.
 6. Check to make sure you actually compiled the firmware and flashed the Teensy correctly. Unless you got error messages in the terminal, or a pop-up during flashing, you probably did everything correctly.

 If you've done all of these things, keep in mind that sometimes you might have had multiple things affecting the keyswitch, so it doesn't hurt to test the keyswitch by shorting it out at the end.
@@ -335,4 +337,4 @@ If you've done all of these things, keep in mind that sometimes you might have h

 Now that you have a working board, it's time to get things in their permanent positions. I've often used liberal amounts of hot glue to secure and insulate things, so if that's your style, start spreading that stuff like butter. Otherwise, double-sided tape is always an elegant solution, and electrical tape is a distant second. Due to the nature of these builds, a lot of this part is up to you and how you planned (or didn't plan) things out.

-There are a lot of possibilities inside the firmware - explore [docs.qmk.fm](http://docs.qmk.fm) for a full feature list, and dive into the different project (Planck, Clueboard, Ergodox EZ, etc) to see how people use all of them. You can always stop by [the OLKB subreddit for help!](http://reddit.com/r/olkb)
+There are a lot of possibilities inside the firmware - explore [docs.qmk.fm](http://docs.qmk.fm) for a full feature list, and dive into the different keyboards (Planck, Clueboard, Ergodox EZ, etc) to see how people use all of them. You can always stop by [the OLKB subreddit for help!](http://reddit.com/r/olkb)
@@ -6,14 +6,26 @@ If you have not yet you should read the [Keyboard Guidelines](hardware_keyboard_

 ## Adding Your AVR Keyboard to QMK

-QMK has a number of features to simplify working with AVR keyboards. For most keyboards you don't have to write a single line of code. To get started run the `util/new_project.sh` script:
+QMK has a number of features to simplify working with AVR keyboards. For most keyboards you don't have to write a single line of code. To get started, run the `util/new_keyboard.sh` script:

-```bash
-$ util/new_project.sh my_awesome_keyboard
-######################################################
-# /keyboards/my_awesome_keyboard project created. To start
-# working on things, cd into keyboards/my_awesome_keyboard
-######################################################
+```
+$ ./util/new_keyboard.sh
+Generating a new QMK keyboard directory
+
+Keyboard Name: mycoolkb
+Keyboard Type [avr]: 
+Your Name [John Smith]: 
+
+Copying base template files... done
+Copying avr template files... done
+Renaming keyboard files... done
+Replacing %KEYBOARD% with mycoolkb... done
+Replacing %YOUR_NAME% with John Smith... done
+
+Created a new keyboard called mycoolkb.
+
+To start working on things, cd into keyboards/mycoolkb,
+or open the directory in your favourite text editor.
 ```

 This will create all the files needed to support your new keyboard, and populate the settings with default values. Now you just need to customize it for your keyboard.
@@ -14,9 +14,9 @@ QMK is used on a lot of different hardware. While support for the most common MC

 Support for addressing pins on the ProMicro by their Arduino name rather than their AVR name. This needs to be better documented, if you are trying to do this and reading the code doesn't help please [open an issue](https://github.com/qmk/qmk_firmware/issues/new) and we can help you through the process.

-## SSD1306 (AVR Only)
+## SSD1306 OLED Driver

-Support for SSD1306 based OLED displays. This needs to be better documented, if you are trying to do this and reading the code doesn't help please [open an issue](https://github.com/qmk/qmk_firmware/issues/new) and we can help you through the process.
+Support for SSD1306 based OLED displays. For more information see the [OLED Driver Feature](feature_oled_driver.md) page.

 ## uGFX

@@ -32,4 +32,4 @@ Support for up to 2 drivers. Each driver impliments 2 charlieplex matrices to in

 ## IS31FL3733

-Support for up to a single driver with room for expansion. Each driver can control 192 individual LEDs or 64 RGB LEDs. For more information on how to setup the driver see the [RGB Matrix](feature_rgb_matrix.md) page.
+Support for up to a single driver with room for expansion. Each driver can control 192 individual LEDs or 64 RGB LEDs. For more information on how to setup the driver see the [RGB Matrix](feature_rgb_matrix.md) page.
@@ -1,15 +1,25 @@
-Setting up your ARM based PCB is a little more involved than an Atmel MCU, but is easy enough. Start by using `util/new_project.sh <keyboard>` to create a new project:
+Setting up your ARM based PCB is a little more involved than an Atmel MCU, but is easy enough. Start by running `util/new_keyboard.sh`:

 ```
-$ util/new_project.sh simontester
-######################################################
-# /keyboards/simontester project created. To start
-# working on things, cd into keyboards/simontester
-######################################################
+$ ./util/new_keyboard.sh
+Generating a new QMK keyboard directory
+
+Keyboard Name: mycoolkb
+Keyboard Type [avr]: 
+Your Name [John Smith]: 
+
+Copying base template files... done
+Copying avr template files... done
+Renaming keyboard files... done
+Replacing %KEYBOARD% with mycoolkb... done
+Replacing %YOUR_NAME% with John Smith... done
+
+Created a new keyboard called mycoolkb.
+
+To start working on things, cd into keyboards/mycoolkb,
+or open the directory in your favourite text editor.
 ```

-
-
 # END OF NEW ARM DOC, OLD ATMEL DOC FOLLOWS

 ## `/keyboards/<keyboard>/config.h`
@@ -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 (*Quantum Mechanical Keyboard*) 是一个社区维护的开源软件，包括 QMK 固件, QMK 工具箱, qmk.fm网站, 和这些文档。QMK 固件是一个基于[tmk\_keyboard](http://github.com/tmk/tmk_keyboard)的键盘固件，它在爱特梅尔AVR微控制器实现一些有用的功能,确切地说, 是在 [OLKB product line](http://olkb.com), 在 [ErgoDox EZ](http://www.ergodox-ez.com) 键盘, 和 [Clueboard product line](http://clueboard.co/). 上。它被移植到使用ChibiOS的ARM芯片上. 它可以在飞线键盘或定制PCB键盘中发挥功能.
+
+## 如何得到它
+
+如果你打算贡献布局, 键盘, 或者其他QMK特性, 一下是最简单的方法：[从Github获得repo分支](https://github.com/qmk/qmk_firmware#fork-destination-box), 并克隆你的repo到本地进行编辑，推送，然后从你的分支打开 [Pull Request](https://github.com/qmk/qmk_firmware/pulls).
+
+此外, 你也可以直接下载 ([zip](https://github.com/qmk/qmk_firmware/zipball/master), [tar](https://github.com/qmk/qmk_firmware/tarball/master)), 或者从git克隆 (`git@github.com:qmk/qmk_firmware.git`), 或 https (`https://github.com/qmk/qmk_firmware.git`).
+
+## 如何编译
+
+在你能编译之前, 你需要[部署环境](getting_started_build_tools.md) 用于 AVR or/and ARM 开发。完成后, 你可以使用 `make` 命令来编译一个键盘和布局使用以下命令:
+
+    make planck/rev4:default
+
+这将建立 `planck`的`rev4` 修订版本并使用 `default`布局。并非所有键盘都有修订版本 (也叫做子项目或文件夹)，在此情况下，修订版本可以省略，如下:
+
+    make preonic:default
+
+## 如何定制
+
+QMK 有许多 [特性](features.md)来探索，也有很多 [参考文档](http://docs.qmk.fm) 供您发掘。你可以通过修改 [布局](keymap.md)和[键码](keycodes.md)来利用许多特性。
@@ -0,0 +1,106 @@
+* [完全菜鸟指南](newbs.md)
+  * [入门](newbs_getting_started.md)
+  * [构建你的第一个固件](newbs_building_firmware.md)
+  * [刷新固件](newbs_flashing.md)
+  * [测试和调试](newbs_testing_debugging.md)
+  * [Git最佳实践](newbs_best_practices.md)
+  * [学习资源](newbs_learn_more_resources.md)
+
+* [QMK基础](README.md)
+  * [QMK 简介](getting_started_introduction.md)
+  * [贡献 QMK](contributing.md)
+  * [如何使用Github](getting_started_github.md)
+  * [获得帮助](getting_started_getting_help.md)
+
+* [问题解答](faq.md)
+  * [一般问题](faq_general.md)
+  * [构建/编译QMK](faq_build.md)
+  * [调试/故障排除 QMK](faq_debug.md)
+  * [键盘布局](faq_keymap.md)
+
+* 详细指南
+  * [安装构建工具](getting_started_build_tools.md)
+  * [流浪者指南](getting_started_vagrant.md)
+  * [构建/编译指令](getting_started_make_guide.md)
+  * [刷新固件](flashing.md)
+  * [定制功能](custom_quantum_functions.md)
+  * [布局概述](keymap.md)
+
+* [硬件](hardware.md)
+  * [AVR 处理器](hardware_avr.md)
+  * [驱动](hardware_drivers.md)
+
+* 参考
+  * [键盘指南](hardware_keyboard_guidelines.md)
+  * [配置选项](config_options.md)
+  * [键码](keycodes.md)
+  * [记录最佳实践](documentation_best_practices.md)
+  * [文档指南](documentation_templates.md)
+  * [词汇表](reference_glossary.md)
+  * [单元测试](unit_testing.md)
+  * [有用的功能](ref_functions.md)
+  * [配置器支持](reference_configurator_support.md)
+  * [info.json 格式](reference_info_json.md)
+
+* [特性](features.md)
+  * [基本键码](keycodes_basic.md)
+  * [US ANSI 控制键](keycodes_us_ansi_shifted.md)
+  * [量子键码](quantum_keycodes.md)
+  * [高级键码](feature_advanced_keycodes.md)
+  * [音频](feature_audio.md)
+  * [自动控制](feature_auto_shift.md)
+  * [背光](feature_backlight.md)
+  * [蓝牙](feature_bluetooth.md)
+  * [Bootmagic](feature_bootmagic.md)
+  * [组合](feature_combo)
+  * [命令](feature_command.md)
+  * [动态宏指令](feature_dynamic_macros.md)
+  * [编码器](feature_encoders.md)
+  * [Grave Escape](feature_grave_esc.md)
+  * [键锁](feature_key_lock.md)
+  * [层](feature_layouts.md)
+  * [引导键](feature_leader_key.md)
+  * [LED 阵列](feature_led_matrix.md)
+  * [宏指令](feature_macros.md)
+  * [鼠标键](feature_mouse_keys.md)
+  * [一键功能](feature_advanced_keycodes.md#one-shot-keys)
+  * [指针设备](feature_pointing_device.md)
+  * [PS/2 鼠标](feature_ps2_mouse.md)
+  * [RGB 光](feature_rgblight.md)
+  * [RGB 矩阵](feature_rgb_matrix.md)
+  * [空格候补换挡](feature_space_cadet_shift.md)
+  * [空格候补换挡回车](feature_space_cadet_shift_enter.md)
+  * [速录机](feature_stenography.md)
+  * [换手](feature_swap_hands.md)
+  * [踢踏舞](feature_tap_dance.md)
+  * [终端](feature_terminal.md)
+  * [热敏打印机](feature_thermal_printer.md)
+  * [Unicode](feature_unicode.md)
+  * [用户空间](feature_userspace.md)
+  * [速度键](feature_velocikey.md)
+
+* 针对制造者和定制者
+  * [飞线指南](hand_wire.md)
+  * [ISP 刷新指南](isp_flashing_guide.md)
+  * [ARM 调试指南](arm_debugging.md)
+  * [I2C 驱动](i2c_driver.md)
+  * [GPIO 控制器](internals_gpio_control.md)
+  * [Proton C 转换](proton_c_conversion.md)
+
+* 深入了解
+  * [键盘如何工作](how_keyboards_work.md)
+  * [理解 QMK](understanding_qmk.md)
+
+* 其他话题
+  * [使用Eclipse开发QMK](other_eclipse.md)
+  * [使用VSCode开发QMK](other_vscode.md)
+  * [支持](support.md)
+
+* QMK 内构 (正在编写)
+  * [定义](internals_defines.md)
+  * [输入回调寄存器](internals_input_callback_reg.md)
+  * [Midi 设备](internals_midi_device.md)
+  * [Midi 设备设置过程](internals_midi_device_setup_process.md)
+  * [Midi 工具库](internals_midi_util.md)
+  * [发送函数](internals_send_functions.md)
+  * [Sysex 工具](internals_sysex_tools.md)
@@ -42,6 +42,18 @@ static const I2CConfig i2cconfig = {
  0
 };

+static i2c_status_t chibios_to_qmk(const msg_t* status) {
+  switch (*status) {
+    case I2C_NO_ERROR:
+      return I2C_STATUS_SUCCESS;
+    case I2C_TIMEOUT:
+      return I2C_STATUS_TIMEOUT;
+    // I2C_BUS_ERROR, I2C_ARBITRATION_LOST, I2C_ACK_FAILURE, I2C_OVERRUN, I2C_PEC_ERROR, I2C_SMB_ALERT
+    default:
+      return I2C_STATUS_ERROR;
+  }
+}
+
 __attribute__ ((weak))
 void i2c_init(void)
 {
@@ -57,29 +69,30 @@ void i2c_init(void)
  //i2cInit(); //This is invoked by halInit() so no need to redo it.
 }

-// This is usually not needed
-uint8_t i2c_start(uint8_t address)
+i2c_status_t i2c_start(uint8_t address)
 {
  i2c_address = address;
  i2cStart(&I2C_DRIVER, &i2cconfig);
-  return 0;
+  return I2C_STATUS_SUCCESS;
 }

-uint8_t i2c_transmit(uint8_t address, uint8_t* data, uint16_t length, uint16_t timeout)
+i2c_status_t i2c_transmit(uint8_t address, const uint8_t* data, uint16_t length, uint16_t timeout)
 {
  i2c_address = address;
  i2cStart(&I2C_DRIVER, &i2cconfig);
-  return i2cMasterTransmitTimeout(&I2C_DRIVER, (i2c_address >> 1), data, length, 0, 0, MS2ST(timeout));
+  msg_t status = i2cMasterTransmitTimeout(&I2C_DRIVER, (i2c_address >> 1), data, length, 0, 0, MS2ST(timeout));
+  return chibios_to_qmk(&status);
 }

-uint8_t i2c_receive(uint8_t address, uint8_t* data, uint16_t length, uint16_t timeout)
+i2c_status_t i2c_receive(uint8_t address, uint8_t* data, uint16_t length, uint16_t timeout)
 {
  i2c_address = address;
  i2cStart(&I2C_DRIVER, &i2cconfig);
-  return i2cMasterReceiveTimeout(&I2C_DRIVER, (i2c_address >> 1), data, length, MS2ST(timeout));
+  msg_t status = i2cMasterReceiveTimeout(&I2C_DRIVER, (i2c_address >> 1), data, length, MS2ST(timeout));
+  return chibios_to_qmk(&status);
 }

-uint8_t i2c_writeReg(uint8_t devaddr, uint8_t regaddr, uint8_t* data, uint16_t length, uint16_t timeout)
+i2c_status_t i2c_writeReg(uint8_t devaddr, uint8_t regaddr, const uint8_t* data, uint16_t length, uint16_t timeout)
 {
  i2c_address = devaddr;
  i2cStart(&I2C_DRIVER, &i2cconfig);
@@ -91,18 +104,19 @@ uint8_t i2c_writeReg(uint8_t devaddr, uint8_t regaddr, uint8_t* data, uint16_t l
  }
  complete_packet[0] = regaddr;

-  return i2cMasterTransmitTimeout(&I2C_DRIVER, (i2c_address >> 1), complete_packet, length + 1, 0, 0, MS2ST(timeout));
+  msg_t status = i2cMasterTransmitTimeout(&I2C_DRIVER, (i2c_address >> 1), complete_packet, length + 1, 0, 0, MS2ST(timeout));
+  return chibios_to_qmk(&status);
 }

-uint8_t i2c_readReg(uint8_t devaddr, uint8_t* regaddr, uint8_t* data, uint16_t length, uint16_t timeout)
+i2c_status_t i2c_readReg(uint8_t devaddr, uint8_t* regaddr, uint8_t* data, uint16_t length, uint16_t timeout)
 {
  i2c_address = devaddr;
  i2cStart(&I2C_DRIVER, &i2cconfig);
-  return i2cMasterTransmitTimeout(&I2C_DRIVER, (i2c_address >> 1), regaddr, 1, data, length, MS2ST(timeout));
+  msg_t status = i2cMasterTransmitTimeout(&I2C_DRIVER, (i2c_address >> 1), regaddr, 1, data, length, MS2ST(timeout));
+  return chibios_to_qmk(&status);
 }

-uint8_t i2c_stop(void)
+void i2c_stop(void)
 {
  i2cStop(&I2C_DRIVER);
-  return 0;
 }
@@ -40,11 +40,17 @@
  #define I2C_DRIVER I2CD1
 #endif

+typedef int16_t i2c_status_t;
+
+#define I2C_STATUS_SUCCESS (0)
+#define I2C_STATUS_ERROR   (-1)
+#define I2C_STATUS_TIMEOUT (-2)
+
 void i2c_init(void);
-uint8_t i2c_start(uint8_t address);
-uint8_t i2c_transmit(uint8_t address, uint8_t* data, uint16_t length, uint16_t timeout);
-uint8_t i2c_receive(uint8_t address, uint8_t* data, uint16_t length, uint16_t timeout);
-uint8_t i2c_transmit_receive(uint8_t address, uint8_t * tx_body, uint16_t tx_length, uint8_t * rx_body, uint16_t rx_length);
-uint8_t i2c_writeReg(uint8_t devaddr, uint8_t regaddr, uint8_t* data, uint16_t length, uint16_t timeout);
-uint8_t i2c_readReg(uint8_t devaddr, uint8_t* regaddr, uint8_t* data, uint16_t length, uint16_t timeout);
-uint8_t i2c_stop(void);
+i2c_status_t i2c_start(uint8_t address);
+i2c_status_t i2c_transmit(uint8_t address, const uint8_t* data, uint16_t length, uint16_t timeout);
+i2c_status_t i2c_receive(uint8_t address, uint8_t* data, uint16_t length, uint16_t timeout);
+i2c_status_t i2c_transmit_receive(uint8_t address, uint8_t * tx_body, uint16_t tx_length, uint8_t * rx_body, uint16_t rx_length);
+i2c_status_t i2c_writeReg(uint8_t devaddr, uint8_t regaddr, const uint8_t* data, uint16_t length, uint16_t timeout);
+i2c_status_t i2c_readReg(uint8_t devaddr, uint8_t* regaddr, uint8_t* data, uint16_t length, uint16_t timeout);
+void i2c_stop(void);
@@ -121,7 +121,7 @@ int16_t i2c_read_nack(uint16_t timeout) {
  return TWDR;
 }

-i2c_status_t i2c_transmit(uint8_t address, uint8_t* data, uint16_t length, uint16_t timeout) {
+i2c_status_t i2c_transmit(uint8_t address, const uint8_t* data, uint16_t length, uint16_t timeout) {
  i2c_status_t status = i2c_start(address | I2C_WRITE, timeout);

  for (uint16_t i = 0; i < length && status >= 0; i++) {
@@ -155,7 +155,7 @@ i2c_status_t i2c_receive(uint8_t address, uint8_t* data, uint16_t length, uint16
  return (status < 0) ? status : I2C_STATUS_SUCCESS;
 }

-i2c_status_t i2c_writeReg(uint8_t devaddr, uint8_t regaddr, uint8_t* data, uint16_t length, uint16_t timeout) {
+i2c_status_t i2c_writeReg(uint8_t devaddr, uint8_t regaddr, const uint8_t* data, uint16_t length, uint16_t timeout) {
  i2c_status_t status = i2c_start(devaddr | 0x00, timeout);
  if (status >= 0) {
    status = i2c_write(regaddr, timeout);
@@ -22,10 +22,10 @@ i2c_status_t i2c_start(uint8_t address, uint16_t timeout);
 i2c_status_t i2c_write(uint8_t data, uint16_t timeout);
 int16_t i2c_read_ack(uint16_t timeout);
 int16_t i2c_read_nack(uint16_t timeout);
-i2c_status_t i2c_transmit(uint8_t address, uint8_t* data, uint16_t length, uint16_t timeout);
+i2c_status_t i2c_transmit(uint8_t address, const uint8_t* data, uint16_t length, uint16_t timeout);
 i2c_status_t i2c_receive(uint8_t address, uint8_t* data, uint16_t length, uint16_t timeout);
-i2c_status_t i2c_writeReg(uint8_t devaddr, uint8_t regaddr, uint8_t* data, uint16_t length, uint16_t timeout);
+i2c_status_t i2c_writeReg(uint8_t devaddr, uint8_t regaddr, const uint8_t* data, uint16_t length, uint16_t timeout);
 i2c_status_t i2c_readReg(uint8_t devaddr, uint8_t regaddr, uint8_t* data, uint16_t length, uint16_t timeout);
 void i2c_stop(void);

-#endif // I2C_MASTER_H
+#endif // I2C_MASTER_H
@@ -27,6 +27,12 @@
 #include <util/delay.h>
 #include "debug.h"

+#if !defined(LED_ARRAY) && defined(RGB_MATRIX_ENABLE)
+// LED color buffer
+LED_TYPE led[DRIVER_LED_TOTAL];
+  #define LED_ARRAY led
+#endif
+
 #ifdef RGBW_BB_TWI

 // Port for the I2C
@@ -141,6 +147,25 @@ unsigned char I2C_Write(unsigned char c)

 #endif

+#ifdef RGB_MATRIX_ENABLE
+// Set an led in the buffer to a color
+void inline ws2812_setled(int i, uint8_t r, uint8_t g, uint8_t b)
+{
+    led[i].r = r;
+    led[i].g = g;
+    led[i].b = b;
+}
+
+void ws2812_setled_all  (uint8_t r, uint8_t g, uint8_t b)
+{
+  for (int i = 0; i < sizeof(led)/sizeof(led[0]); i++) {
+    led[i].r = r;
+    led[i].g = g;
+    led[i].b = b;
+  }
+}
+#endif
+
 // Setleds for standard RGB
 void inline ws2812_setleds(LED_TYPE *ledarray, uint16_t leds)
 {
@@ -30,7 +30,6 @@

 #include "rgblight_types.h"

-
 /* User Interface
 *
 * Input:
@@ -43,6 +42,10 @@
 *         - Send out the LED data
 *         - Wait 50�s to reset the LEDs
 */
+#ifdef RGB_MATRIX_ENABLE
+void ws2812_setled      (int index, uint8_t r, uint8_t g, uint8_t b);
+void ws2812_setled_all  (uint8_t r, uint8_t g, uint8_t b);
+#endif

 void ws2812_setleds     (LED_TYPE *ledarray, uint16_t number_of_leds);
 void ws2812_setleds_pin (LED_TYPE *ledarray, uint16_t number_of_leds,uint8_t pinmask);
--- a/Show More
+++ b/Show More