2021 February 27 Breaking Changes Update (#12040)

1 files changed, 137 insertions, 21 deletions

diff --git a/docs/reference_info_json.md b/docs/reference_info_json.md
index 67c189d786..30d813e93a 100644
--- a/docs/reference_info_json.md
+++ b/docs/reference_info_json.md
@@ -19,8 +19,20 @@ The `info.json` file is a JSON formatted dictionary with the following keys avai
   * Width of the board in Key Units
 * `height`
   * Height of the board in Key Units
+* `debounce`
+  * How many milliseconds (ms) to wait for debounce to happen. (Default: 5)
+* `diode_direction`
+  * The direction diodes face. See [`DIRECT_PINS` in the hardware configuration](https://docs.qmk.fm/#/config_options?id=hardware-options) for more details.
+* `layout_aliases`
+  * A dictionary containing layout aliases. The key is the alias and the value is a layout in `layouts` it maps to.
 * `layouts`
-  * Physical Layout representations. See the next section for more detail.
+  * Physical Layout representations. See the [Layout Format](#layout_format) section for more detail.
+* `matrix_pins`
+  * Configure the pins corresponding to columns and rows, or direct pins. See [Matrix Pins](#matrix_pins) for more detail.
+* `rgblight`
+  * Configure the [RGB Lighting feature](feature_rgblight.md). See the [RGB Lighting](#rgb_lighting) section for more detail.
+* `usb`
+  * Configure USB VID, PID, and other parameters. See [USB](#USB) for more detail.
 
 ### Layout Format
 
@@ -49,25 +61,129 @@ All key positions and rotations are specified in relation to the top-left corner
   * The width of the key, in Key Units. Ignored if `ks` is provided. Default: `1`
 * `h`
   * The height of the key, in Key Units. Ignored if `ks` is provided. Default: `1`
-* `r`
-  * How many degrees clockwise to rotate the key.
-* `rx`
-  * The absolute position of the point to rotate the key around in the horizontal axis. Default: `x`
-* `ry`
-  * The absolute position of the point to rotate the key around in the vertical axis. Default: `y`
-* `ks`
-  * Key Shape: define a polygon by providing a list of points, in Key Units.
-  * **Important**: These are relative to the top-left of the key, not absolute.
-  * Example ISO Enter: `[ [0,0], [1.5,0], [1.5,2], [0.25,2], [0.25,1], [0,1], [0,0] ]`
 * `label`
   * What to name this position in the matrix.
-  * This should usually be the same name as what is silkscreened on the PCB at this location.
-
-## How is the Metadata Exposed?
-
-This metadata is primarily used in two ways:
-
-* To allow web-based configurators to dynamically generate UI
-* To support the new `make keyboard:keymap:qmk` target, which bundles this metadata up with the firmware to allow QMK Toolbox to be smarter.
-
-Configurator authors can see the [QMK Compiler](https://docs.api.qmk.fm/using-the-api) docs for more information on using the JSON API.
+  * This should usually correspond to the keycode for the first layer of the default keymap.
+* `matrix`
+  * A 2 item list describing the row and column location for this key.
+
+### Matrix Pins
+
+Currently QMK supports connecting switches either directly to GPIO pins or via a switch matrix. At this time you can not combine these, they are mutually exclusive.
+
+#### Switch Matrix
+
+Most keyboards use a switch matrix to connect keyswitches to the MCU. You can define your pin columns and rows to configure your switch matrix. When defining switch matrices you should also define your `diode_direction`.
+
+Example:
+
+```json
+{
+  "diode_direction": "COL2ROW",
+  "matrix_pins": {
+    "cols": ["F4", "E6", "B1", "D2"],
+    "rows": ["B0", "D3", "D5", "D4", "D6"]
+  }
+}
+```
+
+#### Direct Pins
+
+Direct pins are when you connect one side of the switch to GND and the other side to a GPIO pin on your MCU. No diode is required, but there is a 1:1 mapping between switches and pins.
+
+When specifying direct pins you need to arrange them in nested arrays. The outer array consists of rows, while the inner array is a text string corresponding to a pin. You can use `null` to indicate an empty spot in the matrix.
+
+Example:
+
+```json
+{
+    "matrix_pins": {
+        "direct": [
+            ["A10", "A9"],
+            ["A0", "B8"],
+            [null, "B11"],
+            ["B9", "A8"],
+            ["A7", "B1"],
+            [null, "B2"]
+        ]
+    }
+}
+```
+
+### RGB Lighting
+
+This section controls the legacy WS2812 support in QMK. This should not be confused with the RGB Matrix feature, which can be used to control both WS2812 and ISSI RGB LEDs.
+
+The following items can be set. Not every value is required.
+
+* `led_count`
+    * The number of LEDs in your strip
+* `pin`
+    * The GPIO pin that your LED strip is connected to
+* `animations`
+    * A dictionary that lists enabled and disabled animations. See [RGB Light Animations](#rgb_light_animations) below.
+* `sleep`
+    * Set to `true` to enable lighting during host sleep
+* `split`
+    * Set to `true` to enable synchronization functionality between split halves
+* `split_count`
+    * For split keyboards, the number of LEDs on each side
+* `max_brightness`
+    * (0-255) What the maxmimum brightness (value) level is
+* `hue_steps`
+    * How many steps of adjustment to have for hue
+* `saturation_steps`
+    * How many steps of adjustment to have for saturation
+* `brightness_steps`
+    * How many steps of adjustment to have for brightness (value)
+
+Example:
+
+```json
+{
+    "rgblight": {
+        "led_count": 4,
+        "pin": "F6",
+        "hue_steps": 10,
+        "saturation_steps": 17,
+        "brightness_steps": 17,
+        "animations": {
+            "all": true
+        }
+    }
+}
+```
+
+#### RGB Light Animations
+
+The following animations can be enabled:
+
+| Key | Description |
+|-----|-------------|
+| `all` | Enable all additional animation modes. |
+| `alternating` | Enable alternating animation mode. |
+| `breathing` | Enable breathing animation mode. |
+| `christmas` | Enable christmas animation mode. |
+| `knight` | Enable knight animation mode. |
+| `rainbow_mood` | Enable rainbow mood animation mode. |
+| `rainbow_swirl` | Enable rainbow swirl animation mode. |
+| `rgb_test` | Enable RGB test animation mode. |
+| `snake` | Enable snake animation mode. |
+| `static_gradient` | Enable static gradient mode. |
+| `twinkle` | Enable twinkle animation mode. |
+
+### USB
+
+Every USB keyboard needs to have its USB parmaters defined. At a minimum you need to set vid, pid, and device version.
+
+Example:
+
+```json
+{
+  "usb": {
+    "vid": "0xC1ED",
+    "pid": "0x23B0",
+    "device_ver": "0x0001"
+  }
+}
+```