Henry-Hiles/qmk_userspace
1
0
Fork 0
forked from mirrors/qmk_userspace
Code Pull requests Activity

[docs] Improve documentation regarding info.json (#18508)

Browse source 
* docs: raise info.json awareness

* docs: note that DD migration is WIP
This commit is contained in:
Less/Rikki 2022-09-29 13:08:45 -04:00 • committed by GitHub
parent bfcbcfe3c7
commit 00dc764f72
Failed to generate hash of commit
2 changed files with 31 additions and 10 deletions
Download patch file Download diff file Expand all files Collapse all files

29
docs/reference_info_json.md
View file

@ -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": {