330e2e6a |
1 | # `info.json` |
2 | |
3 | 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. |
4 | |
5 | 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%. |
6 | |
7 | ## `info.json` Format |
8 | |
9 | 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. |
10 | |
11 | * `keyboard_name` |
12 | * A free-form text string describing the keyboard. |
13 | * Example: `Clueboard 66%` |
14 | * `url` |
15 | * A URL to the keyboard's product page, [QMK.fm/keyboards](https://qmk.fm/keyboards) page, or other page describing information about the keyboard. |
16 | * `maintainer` |
17 | * GitHub username of the maintainer, or `qmk` for community maintained boards |
18 | * `width` |
19 | * Width of the board in Key Units |
20 | * `height` |
21 | * Height of the board in Key Units |
22 | * `layouts` |
23 | * Physical Layout representations. See the next section for more detail. |
24 | |
25 | ### Layout Format |
26 | |
27 | 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. |
28 | |
29 | * `width` |
30 | * Optional: The width of the layout in Key Units |
31 | * `height` |
32 | * Optional: The height of the layout in Key Units |
33 | * `key_count` |
34 | * **Required**: The number of keys in this layout |
35 | * `layout` |
36 | * A list of Key Dictionaries describing the physical layout. See the next section for more details. |
37 | |
38 | ### Key Dictionary Format |
39 | |
40 | 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. |
41 | |
42 | 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. |
43 | |
83f74dd9 |
44 | * `x` |
330e2e6a |
45 | * **Required**: The absolute position of the key in the horizontal axis, in Key Units. |
83f74dd9 |
46 | * `y` |
330e2e6a |
47 | * **Required**: The absolute position of the key in the vertical axis, in Key Units. |
83f74dd9 |
48 | * `w` |
330e2e6a |
49 | * The width of the key, in Key Units. Ignored if `ks` is provided. Default: `1` |
83f74dd9 |
50 | * `h` |
330e2e6a |
51 | * The height of the key, in Key Units. Ignored if `ks` is provided. Default: `1` |
83f74dd9 |
52 | * `r` |
330e2e6a |
53 | * How many degrees clockwise to rotate the key. |
83f74dd9 |
54 | * `rx` |
330e2e6a |
55 | * The absolute position of the point to rotate the key around in the horizontal axis. Default: `x` |
83f74dd9 |
56 | * `ry` |
330e2e6a |
57 | * The absolute position of the point to rotate the key around in the vertical axis. Default: `y` |
83f74dd9 |
58 | * `ks` |
330e2e6a |
59 | * Key Shape: define a polygon by providing a list of points, in Key Units. |
60 | * **Important**: These are relative to the top-left of the key, not absolute. |
61 | * Example ISO Enter: `[ [0,0], [1.5,0], [1.5,2], [0.25,2], [0.25,1], [0,1], [0,0] ]` |
bcb18154 |
62 | * `label` |
63 | * What to name this position in the matrix. |
64 | * This should usually be the same name as what is silkscreened on the PCB at this location. |
330e2e6a |
65 | |
66 | ## How is the Metadata Exposed? |
67 | |
68 | This metadata is primarily used in two ways: |
69 | |
70 | * To allow web-based configurators to dynamically generate UI |
71 | * To support the new `make keyboard:keymap:qmk` target, which bundles this metadata up with the firmware to allow QMK Toolbox to be smarter. |
72 | |
c6183ab4 |
73 | Configurator authors can see the [QMK Compiler](https://docs.api.qmk.fm/using-the-api) docs for more information on using the JSON API. |