diff options
| -rw-r--r-- | docs/hardware_keyboard_guidelines.md | 88 |
1 files changed, 88 insertions, 0 deletions
diff --git a/docs/hardware_keyboard_guidelines.md b/docs/hardware_keyboard_guidelines.md index 8d348a944..aedaa6301 100644 --- a/docs/hardware_keyboard_guidelines.md +++ b/docs/hardware_keyboard_guidelines.md @@ -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. +## 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 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! |