From 736451558e3c66d10838625a30c904cfa30b170c Mon Sep 17 00:00:00 2001 From: Ryan Date: Sun, 27 Aug 2023 06:03:29 +1000 Subject: [PATCH] Rework info.json reference (#21324) * Rework info.json reference * Apply suggestions from code review Co-authored-by: Sergey Vlasov * Update backlight.pins description * Add rgblight.driver and lowercase other driver names * Remove `split.main` and `split.matrix_grid` for now as they are not working yet --------- Co-authored-by: Sergey Vlasov --- docs/reference_info_json.md | 980 ++++++++++++++++++++++++------------ 1 file changed, 651 insertions(+), 329 deletions(-) diff --git a/docs/reference_info_json.md b/docs/reference_info_json.md index b5c9b3be996..91581afc73b 100644 --- a/docs/reference_info_json.md +++ b/docs/reference_info_json.md @@ -1,369 +1,691 @@ -# `info.json` +# `info.json` Reference :id=info-json-reference The information contained in `info.json` is combined with the `config.h` and `rules.mk` files, dynamically generating the necessary configuration for your keyboard at compile time. It is also used by the [QMK API](https://github.com/qmk/qmk_api), and contains the information [QMK Configurator](https://config.qmk.fm/) needs to display a representation of your keyboard. Its key/value pairs are ruled by the [`data/schemas/keyboard.jsonschema`](https://github.com/qmk/qmk_firmware/blob/master/data/schemas/keyboard.jsonschema) file. To learn more about the why and how of the schema file see the [Data Driven Configuration](https://docs.qmk.fm/#/data_driven_config) page. -You can create `info.json` files at every level under `qmk_firmware/keyboards/`. These files are combined, with more specific files overriding keys in less specific files. This means you do not need to duplicate your metadata information. For example, `qmk_firmware/keyboards/clueboard/info.json` specifies `manufacturer` and `maintainer`, while `qmk_firmware/keyboards/clueboard/66/info.json` specifies more specific information about Clueboard 66%. +You can create `info.json` files at every level under `qmk_firmware/keyboards/`. These files are combined, with more specific files overriding keys in less specific files. This means you do not need to duplicate your metadata information. For example, `qmk_firmware/keyboards/clueboard/info.json` specifies information common to all Clueboard products, such as `manufacturer` and `maintainer`, while `qmk_firmware/keyboards/clueboard/66/info.json` contains more specific information about Clueboard 66%. -## `info.json` Format +## General Metadata :id=general-metadata -The `info.json` file is a JSON formatted dictionary. The first six keys noted here must be defined in `info.json`, or your keyboard will not be accepted into the QMK repository. - -* `keyboard_name` - * A free-form text string describing the keyboard. - * Example: `Clueboard 66%` -* `manufacturer` - * A free-form text string describing the keyboard's manufacturer. - * Example: `Clueboard` -* `url` - * A URL to the keyboard's product page, [QMK.fm/keyboards](https://qmk.fm/keyboards) page, or other page describing information about the keyboard. - * Example: `https://clueboard.co` -* `maintainer` +* `keyboard_name` (Required) + * A free-form text string describing the keyboard. This will be used as the USB product string. Can include Unicode characters, escaped to ASCII eg. `\u03A8` (Ψ). + * Example: `"Clueboard 66%"` +* `maintainer` (Required) * GitHub username of the maintainer, or `qmk` for community maintained boards. - * Example: `skullydazed` -* `usb` - * Configure USB VID, PID, and device version. See the [USB](#USB) section for more detail. -* `debounce` - * The amount of time in milliseconds 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 [Layout Format](#layout-format) section for more detail. -* `matrix_pins` - * Configure the pins corresponding to columns and rows, or direct pins. See the [Matrix Pins](#matrix-pins) section for more detail. -* `rgblight` - * Configure the [RGB Lighting feature](feature_rgblight.md). See the [RGB Lighting](#rgb-lighting) section for more detail. + * Example: `"skullydazed"` +* `manufacturer` (Required) + * A free-form text string describing the keyboard's manufacturer. This will be used as the USB manufacturer string. Can include Unicode characters, escaped to ASCII eg. `\u03A8` (Ψ). + * Example: `"Clueboard"` +* `url` (Required) + * A URL to the keyboard's product page, [QMK.fm/keyboards](https://qmk.fm/keyboards) page, or other page describing information about the keyboard. + * Example: `"https://clueboard.co"` +* `bootloader_instructions` + * Instructions for putting the keyboard into a mode that allows for firmware flashing. + * Example: `"Press the button marked RESET on the back of the PCB"` +* `tags` + * A list of tags describing the keyboard. + * Example: `["ortho", "split", "rgb"]` +## Hardware Configuration :id=hardware-configuration -?> For all the available keys and their allowed values refer back to the [`data/schemas/keyboard.jsonschema`](https://github.com/qmk/qmk_firmware/blob/master/data/schemas/keyboard.jsonschema) file. +* `board` + * Override the default ChibiOS board name (ARM-based keyboards only). + * Example: `"BLACKPILL_STM32_F411"` +* `bootloader` + * The bootloader in use on the keyboard. Required if `development_board` is not specified. +* `development_board` + * The microcontroller development board, if applicable. + * Example: `"promicro"` +* `pin_compatible` + * The form factor of the development board, if applicable. Must be one of `elite_c`, `promicro`. +* `processor` + * The microcontroller in use on the keyboard. Required if `development_board` is not specified. -## Layout Format +## Firmware Configuration :id=firmware-configuration -Within our `info.json` file the `layouts` portion of the dictionary contains several nested dictionaries. The outer layer consists of QMK layout macros, for example `LAYOUT_ansi` or `LAYOUT_iso`. +* `build` + * `debounce_type` + * The debounce algorithm to use. Must be one of `asym_eager_defer_pk`, `custom`, `sym_defer_g`, `sym_defer_pk`, `sym_defer_pr`, `sym_eager_pk`, `sym_eager_pr`. + * `firmware_format` + * The format of the final output binary. Must be one of `bin`, `hex`, `uf2`. + * `lto` + * Enable Link-Time Optimization. + * Default: `false` +* `features` + * A dictionary of features to enable or disable. + * Example: + ```json + { + "rgb_matrix": true, + "rgblight": false + } + ``` +* `qmk` + * `tap_capslock_delay` + * The delay between keydown and keyup for Caps Lock tap events in milliseconds. + * Default: `80` (80 ms) + * `tap_keycode_delay` + * The delay between keydown and keyup for tap events in milliseconds. + * Default: `0` (no delay) +* `tapping` + * `hold_on_other_key_press` + * Default: `false` + * `hold_on_other_key_press_per_key` + * Default: `false` + * `permissive_hold` + * Default: `false` + * `permissive_hold_per_key` + * Default: `false` + * `retro` + * Default: `false` + * `retro_per_key` + * Default: `false` + * `term` + * Default: `200` (200 ms) + * `term_per_key` + * Default: `false` + * `toggle` + * Default: `5` -* `layout` - * A list of Key Dictionaries describing the physical layout. See the next section for more details. +## APA102 :id=apa102 -### Key Dictionary Format +Configures the APA102 driver. -Each Key Dictionary in a layout describes the physical properties of a key. If you are familiar with the Raw Data for you will find many of the concepts the same. We re-use the same key names and layout choices wherever possible, but unlike keyboard-layout-editor each key is stateless, inheriting no properties from the keys that came before it. +* `apa102` + * `clock_pin` (Required) + * The GPIO pin connected to `CI` on the first LED in the chain. + * `data_pin` (Required) + * The GPIO pin connected to `DI` on the first LED in the chain. + * `default_brightness` + * The initial global brightness level (independent of the RGB data), from 0 to 31. + * Default: `31` + +## Audio :id=audio + +Configures the [Audio](feature_audio.md) feature. + +* `audio` + * `macro_beep` + * Play a short beep for `\a` (ASCII `BEL`) characters in Send String macros. + * Default: `false` + * `pins` (Required) + * The GPIO pin(s) connected to the speaker(s). + * `voices` + * Use multiple audio voices. + * Default: `false` + +## Backlight :id=backlight + +Configures the [Backlight](feature_backlight.md) feature. + +* `backlight` + * `as_caps_lock` + * Use the backlight as a Caps Lock indicator. + * Default: `false` + * `breathing` + * Whether backlight breathing is enabled. + * Default: `false` + * `breathing_period` + * The length of one backlight breathing cycle in seconds. + * Default: `6` (6 seconds) + * `driver` + * The driver to use. Must be one of `custom`, `pwm`, `software`, `timer`. + * Default: `"pwm"` + * `levels` + * The number of brightness levels (excluding off), from 1 to 31. + * Default: `3` + * `max_brightness` + * The maximum PWM value which brightness is scaled to, from 0 to 255. + * Default: `255` + * `on_state` + * The logical GPIO state required to turn the LEDs on. + * Default: `1` (on = high) + * `pin` + * The GPIO pin connected to the backlight circuit. + * `pins` + * A list of GPIO pins connected to the backlight LEDs (`software` and `timer` drivers only). + +## Bluetooth :id=bluetooth + +Configures the [Bluetooth](feature_bluetooth.md) feature. + +* `bluetooth` + * `driver` + * The driver to use. Must be one of `custom`, `bluefruit_le`, `rn42`. + +## Bootmagic :id=bootmagic + +Configures the [Bootmagic](feature_bootmagic.md) feature. + +* `bootmagic` + * `enabled` + * Enables the Bootmagic feature. + * Default: `false` + * `matrix` + * The matrix position of the key to check during startup. This should generally be set to the (physically) top left key. + * Default: `[0, 0]` + +## Caps Word :id=caps-word + +Configures the [Caps Word](feature_caps_word.md) feature. + +* `caps_word` + * `both_shifts_turns_on` + * Activate Caps Word by pressing both Shift keys. + * Default: `false` + * `double_tap_shift_turns_on` + * Activate Caps Word by pressing Left Shift twice. + * Default: `false` + * `enabled` + * Enables the Caps Word feature. + * Default: `false` + * `idle_timeout` + * The amount of time before Caps Word automatically deactivates in milliseconds. + * Default: `5000` (5 seconds) + * `invert_on_shift` + * Invert shift state instead of deactivating Caps Word when Shift is pressed. + * Default: `false` + +## Combo :id=combo + +Configures the [Combo](feature_combo.md) feature. + +* `combo` + * `term` + * The amount of time to recognize a combo in milliseconds. + * Default: `50` (50 ms) + +## EEPROM :id=eeprom + +Configures the [EEPROM](eeprom_driver.md) driver. + +* `eeprom` + * `driver` + * The EEPROM backend to use. Must be one of `custom`, `i2c`, `legacy_stm32_flash`, `spi`, `transient`, `vendor`, `wear_leveling`. + * Default: `"vendor"` + +## Encoder :id=encoder + +Configures the [Encoder](feature_encoders.md) feature. + +* `encoder` + * `rotary` + * A list of encoder objects. + * `pin_a` (Required) + * The GPIO pin connected to the encoder's `A` pin. + * `pin_b` (Required) + * The GPIO pin connected to the encoder's `B` pin. + * `resolution` + * The number of edge transitions on both pins required to register an input. + * Default: `4` + +## Indicators :id=indicators + +Configures the [LED Indicators](feature_led_indicators.md) feature. + +* `indicators` + * `caps_lock` + * The GPIO pin connected to the Caps Lock LED. + * `compose` + * The GPIO pin connected to the Compose LED. + * `kana` + * The GPIO pin connected to the Kana LED. + * `num_lock` + * The GPIO pin connected to the Num Lock LED. + * `on_state` + * The logical GPIO state required to turn the LEDs on. + * Default: `1` (on = high) + * `scroll_lock` + * The GPIO pin connected to the Scroll Lock LED. + +## Layouts :id=layouts + +The `layouts` portion of the dictionary contains several nested dictionaries. The outer layer consists of QMK layout names, for example `LAYOUT_60_ansi` or `LAYOUT_60_iso`. + +Each key dictionary in a layout describes the physical properties of a key. If you are familiar with the Raw Data format for [Keyboard Layout Editor](https://keyboard-layout-editor.com), you will find many of the concepts the same. Key names and layout choices are reused wherever possible, but unlike KLE each key is stateless, inheriting no properties from the keys that came before it. All key positions and rotations are specified in relation to the top-left corner of the keyboard, and the top-left corner of each key. -* `x` - * **Required**. The absolute position of the key in the horizontal axis, in Key Units. -* `y` - * **Required**. The absolute position of the key in the vertical axis, in Key Units. -* `w` - * The width of the key, in Key Units. - * Default: `1` -* `h` - * The height of the key, in Key Units. - * Default: `1` -* `label` - * What to name this position in the matrix. This should usually correspond to the keycode for the first layer of the default keymap. -* `matrix` - * A two item list describing the row and column location for this key. - * Example: `[0, 4]` +The ISO enter key is represented by a 1.25u×2uh key. Renderers which utilize info.json layout data (such as `qmk info -l` and the QMK Configurator) should display this key as expected. -## 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"] +* `community_layouts` + * A list of community layouts supported by the keyboard. + * Example: `["60_ansi", "60_iso"]` +* `layout_aliases` + * A mapping of layout aliases to layout definitions. + * Example: + ```json + { + "LAYOUT_ansi": "LAYOUT_60_ansi", + "LAYOUT_iso": "LAYOUT_60_iso" } -} -``` + ``` +* `layouts` + * A dictionary of layouts supported by the keyboard. + * `LAYOUT_` + * `layout` + * A list of key dictionaries comprising the layout. Each key dictionary contains: + * `matrix` (Required) + * The matrix position for the key. + * Example: `[0, 4]` (row 0, column 4) + * `x` (Required) + * The absolute position of the key in the horizontal axis, in key units. + * `y` (Required) + * The absolute position of the key in the vertical axis, in key units. + * `h` + * The height of the key, in key units. + * Default: `1` (1u) + * `label` + * What to name the key. This is *not* a key assignment as in the keymap, but should usually correspond to the keycode for the first layer of the default keymap. + * Example: `"Escape"` + * `r` + * The rotation angle in degrees. Currently not implemented. + * `rx` + * The absolute X position of the rotation axis. Currently not implemented. + * `ry` + * The absolute Y position of the rotation axis. Currently not implemented. + * `w` + * The width of the key, in key units. + * Default: `1` (1u) + * Example: `{"label": "Shift", "matrix": [4, 0], "x": 0, "y": 4.25, "w": 2.25}` -### Direct Pins +## Leader Key :id=leader-key -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. +Configures the [Leader Key](feature_leader_key.md) feature. -When specifying direct pins you need to arrange them in nested arrays. The outer array consists of rows, while the inner array uses text strings to identify the pins used in each row. You can use `null` to indicate an empty spot in the matrix. +* `leader_key` + * `timing` + * Reset the `timeout` on each keypress. + * Default: `false` + * `strict_processing` + * Do not extract the tap keycodes from Layer-Tap and Mod-Tap key events. + * Default: `false` + * `timeout` + * The amount of time to complete a leader sequence in milliseconds. + * Default: `300` (300 ms) -Notice that when using direct pins, `diode_direction` is left undefined. +## LED Matrix :id=led-matrix -Example: +Configures the [LED Matrix](feature_led_matrix.md) feature. -```json -{ - "matrix_pins": { - "direct": [ - ["A10", "A9"], - ["A0", "B8"], - [null, "B11"], - ["B9", "A8"], - ["A7", "B1"], - [null, "B2"] - ] - } -} -``` - -### Additional Options - -* `input_pressed_state` - * This configures state of the GPIO pins when the key is pressed - `1` for high, `0` for low - * Default: `0` - -Example: - -```json - "matrix_pins": { - "input_pressed_state": 1, -}, -``` - -## Non-RGB LED Lighting - -This section controls basic 2-pin LEDs, which typically pass through keyswitches and are soldered into the PCB, or are placed in PCB sockets. -### Backlight - -Enable by setting - -```json - "features": { - "backlight": true - } -``` - -* `breathing` - * Enable backlight breathing, if supported -* `breathing_period` - * The length of one backlight “breath” in seconds -* `levels` - * The number of brightness levels (maximum 31, excluding off) -* `max_brightness` - * The maximum duty cycle of the backlight LED(s) (0-255) -* `pin` - * The pin that controls the backlight LED(s) -* `pins` - * Array of pins that controls the backlight LED(s) (See [Multiple Backlight Pins](feature_backlight.md#multiple-backlight-pins)) -* `on_state` - * The state of the indicator pins when the LED is "on" - `1` for high, `0` for low - * Default: `1` - -Example: - -```json -{ - "backlight": { - "breathing": true, - "breathing_period": 5, - "levels": 15, - "pin": "B7" - } -} -``` - -### LED Indicators - -Used for indicating Num Lock, Caps Lock, and Scroll Lock. May be soldered in-switch or in a dedicated area. - -* `num_lock` - * The pin that controls the `Num Lock` LED -* `caps_lock` - * The pin that controls the `Caps Lock` LED -* `scroll_lock` - * The pin that controls the `Scroll Lock` LED -* `compose` - * The pin that controls the `Compose` LED -* `kana` - * The pin that controls the `Kana` LED -* `on_state` - * The state of the indicator pins when the LED is "on" - `1` for high, `0` for low - * Default: `1` - -Example: - -```json -{ - "indicators": { - "num_lock": "B6", - "caps_lock": "D2", - "scroll_lock": "A3" - } -} - -``` - -## 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 - * Example `[ 10 , 10 ]` -* `max_brightness` - * What the maximum brightness (value) level is (0-255) -* `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": { - "knight": true, - "rainbow_swirl": true +* `led_matrix` + * `animations` + * A dictionary of effects to enable or disable. Effects which are absent default to `false`. + * Example: + ```json + { + "alpha_mods": true, + "breathing": true, + "cycle_left_right": false } - } -} -``` + ``` + * `center_point` + * The centroid (geometric center) of the LEDs. Used for certain effects. + * Default: `[112, 32]` + * `driver` (Required) + * The driver to use. Must be one of `ckled2001`, `custom`, `is31fl3731`, `is31fl3742a`, `is31fl3743a`, `is31fl3745`, `is31fl3746a`. + * `layout` (Required) + * List of LED configuration dictionaries. Each dictionary contains: + * `flags` (Required) + * A bitfield of flags describing the type of LED. + * `x` (Required) + * The position of the LED in the horizontal axis, from 0 to 224. + * `y` (Required) + * The position of the LED in the vertical axis, from 0 to 64. + * `matrix` + * The key matrix position associated with the LED. + * Example: `[0, 2]` + * Example: `{"matrix": [2, 1], "x": 20, "y": 48, "flags": 2}` + * `max_brightness` + * The maximum value which brightness is scaled to, from 0 to 255. + * Default: `255` + * `speed_steps` + * The number of speed adjustment steps. + * Default: `16` + * `split_count` + * For split keyboards, the number of LEDs on each half. + * Example: `[16, 16]` + * `timeout` + * The LED activity timeout in milliseconds. + * Default: `0` (no timeout) + * `val_steps` + * The number of brightness adjustment steps. + * Default: `8` -### RGBLight Animations +## Matrix :id=matrix -The following animations can be enabled: - -|Key |Description | -|-----------------|--------------------------------------| -|`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 parameters defined. At a minimum you need to set the Vendor ID, Product ID, and device version. - -Example: - -```json -{ - "usb": { - "vid": "0xC1ED", - "pid": "0x23B0", - "device_version": "1.0.0" - } -} -``` - -The device version is a BCD (binary coded decimal) value, in the format `MMmr`, so the below value would look like `0x0100` in the generated code. This also means the maximum valid values for each part are `99.9.9`, despite it being a hexadecimal value under the hood. - -## Encoders - -This section controls the basic [rotary encoder](feature_encoders.md) support. - -Enable by setting - -```json - "features": { - "encoder": true - } -``` - -The following items can be set. Not every value is required. - -* `pin_a` - * __Required__. A pad definition -* `pin_b` - * __Required__. B pad definition -* `resolution` - * How many pulses the encoder registers between each detent - -Examples: - -```json -{ - "encoder": { - "rotary": [ - { "pin_a": "B5", "pin_b": "A2" } +* `debounce` + * The debounce time in milliseconds. + * Default: `5` (5 ms) +* `diode_direction` + * Which way the diodes are "pointing". Unused for `matrix_pins.direct`. Must be one of `COL2ROW`, `ROW2COL`. +* `matrix_pins` + * `cols` + * A list of GPIO pins connected to the matrix columns. + * Example: `["A0", "A1", "A2"]` + * `custom` + * Whether to use a custom matrix scanning implementation. + * Default: `false` + * `custom_lite` + * Whether to use a "lite" custom matrix scanning implementation. + * Default: `false` + * `direct` + * A 2-dimensional list of GPIO pins connected to each keyswitch, forming the "matrix" rows and columns. + * Example: + ```json + [ + ["A0", "A1", "A2"], + ["B0", "B1", "B2"], + ["C0", "C1", "C2"] ] - } -} -``` + ``` + * `ghost` + * Whether the matrix has no anti-ghosting diodes. + * Default: `false` + * `input_pressed_state` + * The logical GPIO state of the input pins when a key is pressed. + * Default: `0` (pressed = low) + * `io_delay` + * The amount of time to wait between row/col selection and col/row pin reading, in microseconds. + * Default: `30` (30 µs) + * `rows` + * A list of GPIO pins connected to the matrix rows. + * Example: `["B0", "B1", "B2"]` -```json -{ - "encoder": { - "rotary": [ - { "pin_a": "B5", "pin_b": "A2", "resolution": 4 } - { "pin_a": "B6", "pin_b": "A3", "resolution": 2 } - ] - } -} -``` +## Mouse Keys :id=mouse-keys -## Secure +Configures the [Mouse Keys](feature_mouse_keys.md) feature. -The following options can be configured: +* `mouse_key` + * `delay` + * `enabled` + * Enables the Mouse Keys feature. + * Default: `false` + * `interval` + * `max_speed` + * `time_to_max` + * `wheel_delay` -|Key |Description | -|------------------|---------------------------------------------------------------------------------| -|`unlock_sequence` | Timeout for the user to perform the configured unlock sequence - `0` to disable | -|`unlock_timeout` | Timeout while unlocked before returning to locked - `0` to disable | -|`idle_timeout` | Array of matrix locations describing a sequential sequence of keypresses | +## One Shot :id=one-shot -Example: +Configures [One Shot keys](one_shot_keys.md). -```json -{ - "secure": { - "unlock_sequence": [ [0,0], [0,1] ], - "unlock_timeout": 5000, - "idle_timeout": 60000 - } -} -``` +* `oneshot` + * `tap_toggle` + * The number of times to tap the key in order to hold it. + * `timeout` + * The amount of time before the key is released in milliseconds. -## Bootmagic +## PS/2 :id=ps2 -This section configures [Bootmagic Lite](feature_bootmagic.md) support. +Configures the [PS/2](feature_ps2_mouse.md) feature. -The following options can be configured: +* `ps2` + * `clock_pin` + * The GPIO pin connected to `CLK` on the PS/2 device. + * `data_pin` + * The GPIO pin connected to `DATA` on the PS/2 device. + * `driver` + * The PS/2 driver to use. Must be one of `busywait`, `interrupt`, `usart`, `vendor`. + * Default: `"busywait"` + * `enabled` + * Enable the PS/2 feature. + * Default: `false` + * `mouse_enabled` + * Enable the PS/2 mouse handling. + * Default: `false` -|Key |Description | -|---------|-----------------------------------------------------------------------------| -|`matrix` | A two item list describing the row and column location for the trigger key. | +## QMK LUFA Bootloader :id=qmk-lufa-bootloader -Example: +* `qmk_lufa_bootloader` + * `esc_input` (Required) + * The GPIO pin connected to the designated "exit bootloader" key's row (if `COL2ROW`). + * `esc_output` (Required) + * The GPIO pin connected to the designated "exit bootloader" key's column (if `COL2ROW`). + * `led` + * The GPIO pin connected to an LED to flash. + * `speaker` + * The GPIO pin connected to a speaker to click (can also be used for a second LED). -```json -{ - "bootmagic": { - "enabled": true, - "matrix": [0, 0] - }, -} -``` +## RGBLight :id=rgblight + +Configures the [RGB Lighting](feature_rgblight.md) feature. + +* `rgblight` + * `led_count` (Required) + * The number of LEDs in the chain. + * `animations` + * A dictionary of effects to enable or disable. Effects which are absent default to `false`. + * Example: + ```json + { + "breathing": true, + "rainbow_mood": true, + "snake": false + } + ``` + * `brightness_steps` + * The number of brightness adjustment steps. + * Default: `17` + * `driver` + * The driver to use. Must be one of `apa102`, `custom`, `ws2812`. + * Default: `"ws2812"` + * `hue_steps` + * The number of hue adjustment steps. + * Default: `8` + * `layers` + * `blink` + * Enable layer blinking API. + * Default: `false` + * `enabled` + * Enable RGB Lighting Layers. + * Default: `false` + * `max` + * The maximum layer count, from 1 to 32. + * Default: `8` + * `led_map` + * Remap LED indices. + * Example: `[4, 3, 2, 1, 0]` + * `max_brightness` + * The maximum value which the HSV "V" component is scaled to, from 0 to 255. + * Default: `255` + * `rgbw` + * Enable RGBW LEDs. + * Default: `false` + * `saturation_steps` + * The number of saturation adjustment steps. + * Default: `17` + * `sleep` + * Turn off the LEDs when the host goes to sleep. + * Default: `false` + * `split` + * Enable synchronization between split halves. + * Default: `false` + * `split_count` + * When `rgblight.split` is enabled, the number of LEDs on each half. + * Example: `[10, 10]` + +## RGB Matrix :id=rgb-matrix + +Configures the [RGB Matrix](feature_rgb_matrix.md) feature. + +* `rgb_matrix` + * `animations` + * A dictionary of effects to enable or disable. Effects which are absent default to `false`. + * Example: + ```json + { + "alpha_mods": true, + "breathing": true, + "cycle_left_right": false + } + ``` + * `center_point` + * The centroid (geometric center) of the LEDs. Used for certain effects. + * Default: `[112, 32]` + * `driver` (Required) + * The driver to use. Must be one of `aw20216`, `ckled2001`, `custom`, `is31fl3731`, `is31fl3733`, `is31fl3736`, `is31fl3737`, `is31fl3741`, `is31fl3742a`, `is31fl3743a`, `is31fl3745`, `is31fl3746a`, `ws2812`. + * `hue_steps` + * The number of hue adjustment steps. + * Default: `8` + * `layout` (Required) + * List of LED configuration dictionaries. Each dictionary contains: + * `flags` (Required) + * A bitfield of flags describing the type of LED. + * `x` (Required) + * The position of the LED in the horizontal axis, from 0 to 224. + * `y` (Required) + * The position of the LED in the vertical axis, from 0 to 64. + * `matrix` + * The key matrix position associated with the LED. + * Example: `[0, 2]` + * Example: `{"matrix": [2, 1], "x": 20, "y": 48, "flags": 2}` + * `max_brightness` + * The maximum value which the HSV "V" component is scaled to, from 0 to 255. + * Default: `255` + * `sat_steps` + * The number of saturation adjustment steps. + * Default: `16` + * `speed_steps` + * The number of speed adjustment steps. + * Default: `16` + * `split_count` + * For split keyboards, the number of LEDs on each half. + * Example: `[16, 16]` + * `timeout` + * The LED activity timeout in milliseconds. + * Default: `0` (no timeout) + * `val_steps` + * The number of brightness adjustment steps. + * Default: `16` + +## Secure :id=secure + +Configures the [Secure](feature_secure.md) feature. + +* `secure` + * `enabled` + * Enable the Secure feature. + * Default: `false` + * `idle_timeout` + * Timeout while unlocked before returning to the locked state. Set to `0` to disable. + * Default: `60000` (1 minute) + * `unlock_sequence` + * A list of up to five matrix locations comprising the "unlock sequence". + * Example: `[[0, 0], [0, 1], [4, 3]]` + * `unlock_timeout` + * Timeout for the user to perform the unlock sequence. Set to `0` to disable. + * Default: `5000` (5 seconds) + +## Split Keyboard :id=split-keyboard + +Configures the [Split Keyboard](feature_split_keyboard.md) feature. + +* `split` + * `bootmagic` + * `matrix` + * See [Bootmagic](#bootmagic) config. + * `enabled` + * Enable the Split Keyboard feature. + * Default: `false` + * `encoder` + * `right` + * `rotary` + * See [Encoder](#encoder) config. + * `matrix_pins` + * `right` + * See [Matrix](#matrix) config. + * `soft_serial_pin` + * The GPIO pin to use (`serial` transport protocol only). + * `soft_serial_speed` + * The protocol speed, from `0` to `5` (`serial` transport protocol only). + * Default: `1` + * `transport` + * `protocol` + * The split transport protocol to use. Must be one of `custom`, `i2c`, `serial`, `serial_usart`. + * `sync_matrix_state` + * Mirror the main/primary half's matrix state to the secondary half. + * Default: `false` + * `sync_modifiers` + * Mirror the modifier state to the secondary half. + * Default: `false` + * `watchdog` + * Reboot the secondary half if it loses connection. + * Default: `false` + * `watchdog_timeout` + * The amount of time to wait for communication from the primary half in milliseconds. + * `usb_detect` + * `enabled` + * Detect USB connection when determining split half roles. + * `polling_interval` + * The polling frequency in milliseconds. + * Default: `10` (10 ms) + * `timeout` + * The amount of time to wait for a USB connection in milliseconds. + * Default: `2000` (2 seconds) + +## Stenography :id=stenography + +Configures the [Stenography](feature_stenography.md) feature. + +* `stenography` + * `enabled` + * Enable the Stenography feature. + * Default: `false` + * `protocol` + * The Steno protocol to use. Must be one of `all`, `geminipr`, `txbolt`. + * Default: `"all"` + +## USB :id=usb + +* `usb` + * `device_version` (Required) + * A BCD version number in the format `MM.m.r` (up to `99.9.9`). + * Example: `"1.0.0"` + * `pid` (Required) + * The USB product ID as a four-digit hexadecimal number. + * Example: `"0x23B0"` + * `vid` (Required) + * The USB vendor ID as a four-digit hexadecimal number. + * Example: `"0xC1ED"` + * `force_nkro` + * Force NKRO to be active. + * Default: `false` + * `max_power` + * The maximum current draw the host should expect from the device. This does not control the actual current usage. + * Default: `500` (500 mA) + * `no_startup_check` + * Disable USB suspend check after keyboard startup. + * Default: `false` + * `polling_interval` + * The frequency at which the host should poll the keyboard for reports. + * Default: `1` (1 ms/1000 Hz) + * `shared_endpoint` + * `keyboard` + * Send keyboard reports through the "shared" USB endpoint. + * Default: `false` + * `mouse` + * Send mouse reports through the "shared" USB endpoint. + * Default: `true` + * `suspend_wakeup_delay` + * The amount of time to wait after sending a wakeup packet, in milliseconds. + * Default: `0` (disabled) + * `wait_for` + * Force the keyboard to wait for USB enumeration before starting up. + * Default: `false` + +## WS2812 :id=ws2812 + +Configures the [WS2812](ws2812_driver.md) driver. + +* `ws2812` + * `driver` + * The driver to use. Must be one of `bitbang`, `custom`, `i2c`, `pwm`, `spi`, `vendor`. + * Default: `"bitbang"` + * `pin` (Required) + * The GPIO pin connected to `DI` on the first LED in the chain (`bitbang`, `pwm`, `spi` and `vendor` drivers only). + * `i2c_address` + * The I²C address of the WS2812 controller (`i2c` driver only). + * Default: `"0xB0"` + * `i2c_timeout` + * The I²C timeout in milliseconds (`i2c` driver only). + * Default: `100` (100 ms)