qmk_firmware-mirror/docs/reference_info_json.md

info.json

This file is used by the QMK API. It contains the information QMK Configurator needs to display a representation of your keyboard. You can also set metadata here.

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%
• url
  • A URL to the keyboard's product page, QMK.fm/keyboards page, or other page describing information about the keyboard.
• 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] ]
• label
  • What to name this position in the matrix.
  • This should usually be the same name as what is silkscreened on the PCB at this location.

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 docs for more information on using the JSON API.