keyboard.json

keyboard.json is the file that stores all the information you enter about your keyboard. It is automatically generated by the GUI utilities, but this documentation exists to help you if you ever find it necessary to modify it by hand . Some fields are written here with angle brackets "<>" to show that you should replace it with your content, be sure to remove the angle brackets as well.

keyboard.json is defined with the following top-level fields:

"ui_desc",
"desc",
"spec",
"keys"

ui_desc provides the graphical row and column information needed to render it. it is defined as follows:

"ui_desc": {
    "rows": <number of rows>,
    "cols": <number of cols>
}

desc provides text descriptions for your keyboard. Here is a sample:

"desc": {
    "manufacturer": "Jonny Walker",
    "description": "A nice keyboard",
    "product_name": "nice_keyboard"
}

Only product name is important here, manufacturer and description can be left blank (i.e, "" or null) if desired. Additionally, product name must obey windows file naming conventions as it will be used to produce many files of the same name.

spec contains some technical specifications. It is further divided into the following fields.

"spec": {
    "avrdude": { ... },
    "matrix_spec": { ... },
    "diode_direction: "<diode direction>"
}

avrdude contains information about your keyboard needed for flashing. It is defined as follows:

"avrdude": {
    "partno": "<avrdude microprocessor abreviation>",
    "partno_verbose": "<full avrdude microprocessor name>",
    "programmer": ""
}

You can find the short and verbose partno code for your microprocessor here. "programmer" is almost always left blank unless you have an avrdude programmer you need to specify.

matrix_spec holds information about the keyboard matrix physically wired into your keyboard. Here is a sample:

"matrix_spec": {
      "rows": 2,
      "cols": 3,
      "row_pins": [ "D0", "D5" ],
      "col_pins": [ "F1", "F0", "B0" ]
}

rows and cols are just that, the number of pins used for the rows and columns respectively. row_pins are ordered top-to-bottom, col_pins are ordered left-to-right. "rows" should be the same as the length of the "row_pins" array, and likewise for "cols" and "col_pins". You can find out what pin names you need to use by providing their name as given on your microprocessor specification sheet, or the hexadecimal address of that pin. You can find samples of this here

diode_direction is the orientation of the diodes you used in your keyboard matrix. it takes either "COL2ROW", "ROW2COL" or blank to specify no diodes.

finally, keys is an array where each of the keys in your keyboard are defined individually. Each key has the following fields

{
    "graphics": {...},
    "binding": {...},
    "matrix": {...}
}

graphics is defined as follows:

"graphics": {
    "row": <the key's row in its visual depiction>,
    "col": <the key's column in its visual depiction>,
    "text": <the key's text in its visual depiction>
}

recall that "ui_desc" describes the graphical row and column information for your entire keyboard. Here, "row" and "col" place it in that grid for it to be displayed visually.

binding specifies the action associated with that key it is specified as follows:

"binding": {
    "on_tap": [ ... ],
    "on_hold": [ ... ]
}

"on_tap" specifies the action of that key when it is pressed and released naturally. "on_hold" specifies the action of the key when it is pressed and held down. They are both defined as an array of key codes. You can find the complete list of valid key codes here Additionally, only modifier keys are valid in the "on_hold" list. You can find those key codes here. Use only the names to the left of the comma to specify your keys. To specify a single action, put exactly one item into the array. For macros, specify delays in terms of milliseconds as "ms" and specify key down and key up signals by placing a + or - in front of the key code respectively. for example:

"binding": {
    "on_tap": [ "+", "LEFT CONTROL", ""10ms", "C", "10ms", "-", "LEFT CONTROL" ]
}

will define a copy macro for the key it is defined in. Notice that it is not necessary to define a field if you do not use it.

matrix defines the row and pin pair that each key is associated with. Here is an example:

"matrix": {
    "row": "D7",
    "col": "F6"
}

Refer to matrix_spec above for pin definitions

For complete examples of keyboard.json files, please look at the files contained here