[docs] Improve documentation regarding info.json (#18508)
* docs: raise info.json awareness * docs: note that DD migration is WIP
This commit is contained in:
Less/Rikki
GitHub
parent
bfcbcfe3c7
commit
00dc764f72
|
|
@ -2,7 +2,17 @@
|
|||
|
||||
QMK is nearly infinitely configurable. Wherever possible we err on the side of allowing users to customize their keyboard, even at the expense of code size. That level of flexibility makes for a daunting configuration experience, however.
|
||||
|
||||
There are two main types of configuration files in QMK- `config.h` and `rules.mk`. These files exist at various levels in QMK and all files of the same type are combined to build the final configuration. The levels, from lowest priority to highest priority, are:
|
||||
There are three main types of configuration files in QMK:
|
||||
|
||||
* `config.h`, which contains various preprocessor directives (`#define`, `#ifdef`)
|
||||
* `rules.mk`, which contains additional variables
|
||||
* `info.json`, which is utilized for [data-driven configuration](https://docs.qmk.fm/#/data_driven_config)
|
||||
|
||||
This page will only discuss the first two types, `config.h` and `rules.mk`.
|
||||
|
||||
?> While not all settings have data-driven equivalents yet, keyboard makers are encouraged to utilize the `info.json` file to set the metadata for their boards when possible. See the [`info.json` Format](https://docs.qmk.fm/#/reference_info_json) page for more details.
|
||||
|
||||
These files exist at various levels in QMK and all files of the same type are combined to build the final configuration. The levels, from lowest priority to highest priority, are:
|
||||
|
||||
* QMK Default
|
||||
* Keyboard
|
||||
|
|
|
|||
|
|
@ -1,12 +1,12 @@
|
|||
# `info.json`
|
||||
|
||||
This file is used by the [QMK API](https://github.com/qmk/qmk_api). It contains the information [QMK Configurator](https://config.qmk.fm/) needs to display a representation of your keyboard. You can also set metadata here.
|
||||
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.
|
||||
|
||||
You can create `info.json` files at every level under `qmk_firmware/keyboards/<name>` to specify this metadata. 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/<name>`. 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%.
|
||||
|
||||
## `info.json` Format
|
||||
|
||||
The `info.json` file is a JSON formatted dictionary with the following keys available to be set. You do not have to set all of them, merely the keys that apply to your keyboard.
|
||||
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.
|
||||
|
|
@ -20,6 +20,11 @@ The `info.json` file is a JSON formatted dictionary with the following keys avai
|
|||
* `maintainer`
|
||||
* 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.
|
||||
|
||||
There are many more optional keys, some of which are described below. Others may be found by examining `data/schemas`.
|
||||
|
||||
* `debounce`
|
||||
* The amount of time in milliseconds to wait for debounce to happen.
|
||||
* Default: `5`
|
||||
|
|
@ -33,8 +38,6 @@ The `info.json` file is a JSON formatted dictionary with the following keys avai
|
|||
* 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.
|
||||
* `usb`
|
||||
* Configure USB VID, PID, and other parameters. See the [USB](#USB) section for more detail.
|
||||
|
||||
### Layout Format
|
||||
|
||||
|
|
@ -45,7 +48,7 @@ Within our `info.json` file the `layouts` portion of the dictionary contains sev
|
|||
|
||||
### Key Dictionary Format
|
||||
|
||||
Each Key Dictionary in a layout describes the physical properties of a key. If you are familiar with the Raw Code for <https://keyboard-layout-editor.com> 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.
|
||||
Each Key Dictionary in a layout describes the physical properties of a key. If you are familiar with the Raw Data for <https://keyboard-layout-editor.com> 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.
|
||||
|
||||
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.
|
||||
|
||||
|
|
@ -115,7 +118,7 @@ Example:
|
|||
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
|
||||
Enable by setting
|
||||
|
||||
```json
|
||||
"features": {
|
||||
|
|
@ -155,6 +158,13 @@ Used for indicating Num Lock, Caps Lock, and Scroll Lock. May be soldered in-swi
|
|||
* 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:
|
||||
|
||||
|
|
@ -208,7 +218,8 @@ Example:
|
|||
"saturation_steps": 17,
|
||||
"brightness_steps": 17,
|
||||
"animations": {
|
||||
"all": true
|
||||
"knight": true,
|
||||
"rainbow_swirl": true
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
@ -254,7 +265,7 @@ The device version is a BCD (binary coded decimal) value, in the format `MMmr`,
|
|||
|
||||
This section controls the basic [rotary encoder](feature_encoders.md) support.
|
||||
|
||||
Enable by setting
|
||||
Enable by setting
|
||||
|
||||
```json
|
||||
"features": {
|
||||
|
|
|
|||
Loading…
Reference in New Issue