Document info.json files
This commit is contained in:
parent
4e41beeaa6
commit
432674781a
|
@ -16,6 +16,94 @@ In an effort to keep the repo size down, we're no longer accepting images of any
|
||||||
|
|
||||||
Any sort of hardware file (plate, case, pcb) can't be stored in qmk_firmware, but we have the [qmk.fm repo](https://github.com/qmk/qmk.fm) where such files (as well as in-depth info) can be stored and viewed on [qmk.fm](http://qmk.fm). Downloadable files are stored in `/<keyboard>/` (name follows the same format as above) which are served at `http://qmk.fm/<keyboard>/`, and pages are generated from `/_pages/<keyboard>/` which are served at the same location (.md files are generated into .html files through Jekyll). Check out the `lets_split` directory for an example.
|
Any sort of hardware file (plate, case, pcb) can't be stored in qmk_firmware, but we have the [qmk.fm repo](https://github.com/qmk/qmk.fm) where such files (as well as in-depth info) can be stored and viewed on [qmk.fm](http://qmk.fm). Downloadable files are stored in `/<keyboard>/` (name follows the same format as above) which are served at `http://qmk.fm/<keyboard>/`, and pages are generated from `/_pages/<keyboard>/` which are served at the same location (.md files are generated into .html files through Jekyll). Check out the `lets_split` directory for an example.
|
||||||
|
|
||||||
|
## Keyboard Metadata
|
||||||
|
|
||||||
|
As QMK grows so does the ecosystem surrounding QMK. To make it easier for projects in that ecosystem to tie into QMK as we make changes we are developing a metadata system to expose information about keyboards in QMK.
|
||||||
|
|
||||||
|
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%.
|
||||||
|
|
||||||
|
### `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.
|
||||||
|
|
||||||
|
* `keyboard_name`
|
||||||
|
* A free-form text string describing the keyboard.
|
||||||
|
* Example: `Clueboard 66%`
|
||||||
|
* `manufacturer`
|
||||||
|
* A free-form text string naming the manufacturer.
|
||||||
|
* Example: `Clueboard`
|
||||||
|
* `identifier`
|
||||||
|
* The Vendor, Product, and Revision ID's joined by a :
|
||||||
|
* Example: `c1ed:2370:0001`
|
||||||
|
* `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.
|
||||||
|
* `processor`
|
||||||
|
* The MCU or CPU this keyboard uses.
|
||||||
|
* Example: `atmega32u4` or `stm32f303`
|
||||||
|
* `bootloader`
|
||||||
|
* What bootloader this keyboard uses. Available options:
|
||||||
|
* `atmel-dfu`
|
||||||
|
* `kiibohd-dfu-util`
|
||||||
|
* `lufa-dfu`
|
||||||
|
* `qmk-dfu`
|
||||||
|
* `stm32-dfu-util`
|
||||||
|
* (FIXME: This list is incomplete.)
|
||||||
|
* `maintainer`
|
||||||
|
* GitHub username of the maintainer, or `qmk` for community maintained boards
|
||||||
|
* `width`
|
||||||
|
* Width of the board in Key Units
|
||||||
|
* `height`
|
||||||
|
* Height of the board in Key Units
|
||||||
|
* `layouts`
|
||||||
|
* Physical Layout representations. See the next section for more detail.
|
||||||
|
|
||||||
|
#### Layout Format
|
||||||
|
|
||||||
|
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`. Within each layout macro are keys for `width`, `height`, and `key_count`, each of which should be self-explanatory.
|
||||||
|
|
||||||
|
* `width`
|
||||||
|
* Optional: The width of the layout in Key Units
|
||||||
|
* `height`
|
||||||
|
* Optional: The height of the layout in Key Units
|
||||||
|
* `key_count`
|
||||||
|
* **Required**: The number of keys in this layout
|
||||||
|
* `layout`
|
||||||
|
* A list of Key Dictionaries describing the physical layout. See the next section for more details.
|
||||||
|
|
||||||
|
#### 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 <http://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.
|
||||||
|
|
||||||
|
* `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. 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] ]`
|
||||||
|
|
||||||
|
### 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.compile.qmk.fm/api_docs.html) docs for more information on using the JSON API.
|
||||||
|
|
||||||
## Non-production/handwired projects
|
## Non-production/handwired projects
|
||||||
|
|
||||||
We're happy to accept any project that uses QMK, including prototypes and handwired ones, but we have a separate `/keyboards/handwired/` folder for them, so the main `/keyboards/` folder doesn't get overcrowded. If a prototype project becomes a production project at some point in the future, we'd be happy to move it to the main `/keyboards/` folder!
|
We're happy to accept any project that uses QMK, including prototypes and handwired ones, but we have a separate `/keyboards/handwired/` folder for them, so the main `/keyboards/` folder doesn't get overcrowded. If a prototype project becomes a production project at some point in the future, we'd be happy to move it to the main `/keyboards/` folder!
|
||||||
|
|
Loading…
Reference in New Issue