logo

qmk_firmware

custom branch of QMK firmware git clone https://anongit.hacktivis.me/git/qmk_firmware.git

porting_your_keyboard_to_qmk.md (7548B)

    

  1. # Adding Your Keyboard to QMK
  3. This page describes the support for [Compatible Microcontrollers](compatible_microcontrollers) in QMK.
  5. If you have not yet you should read the [Keyboard Guidelines](hardware_keyboard_guidelines) to get a sense of how keyboards fit into QMK.
  7. QMK has a number of features to simplify working with keyboards. For most, you don't have to write a single line of code. To get started, run `qmk new-keyboard`:
  9. ```
  10. $ qmk new-keyboard
  11. Ψ Generating a new QMK keyboard directory
  13. Ψ Name Your Keyboard Project
  14. Ψ For more information, see:
  15. https://docs.qmk.fm/hardware_keyboard_guidelines#naming-your-keyboard-project
  16. Keyboard Name? mycoolkeeb
  17. Ψ Attribution
  18. Ψ Used for maintainer, copyright, etc.
  19. Your GitHub Username? [jsmith] 
  20. Ψ More Attribution
  21. Ψ Used for maintainer, copyright, etc.
  22. Your Real Name? [John Smith] 
  23. Ψ Pick Base Layout
  24. Ψ As a starting point, one of the common layouts can be used to
  25. bootstrap the process
  26. Default Layout?
  27.     1. 60_abnt2
  28.     ...
  29.     65. none of the above
  30. Please enter your choice: [65] 
  31. Ψ What Powers Your Project
  32. Ψ Is your board using a separate development board, such as a Pro Micro,
  33. or is the microcontroller integrated onto the PCB?
  35. For more information, see:
  36. https://docs.qmk.fm/compatible_microcontrollers
  37. Using a Development Board? [y/n] y
  38. Ψ Select Development Board
  39. Ψ For more information, see:
  40. https://docs.qmk.fm/compatible_microcontrollers
  41. Development Board?
  42.     1. bit_c_pro
  43.     ...
  44.     14. promicro
  45.     ...
  46.     18. svlinky
  47. Please enter your choice: [14] 
  48. Ψ Created a new keyboard called mycoolkeeb.
  49. Ψ Build Command: qmk compile -kb mycoolkeeb -km default.
  50. Ψ Project Location: /Users/jsmith/qmk_firmware/keyboards/mycoolkeeb.
  51. Ψ Now update the config files to match the hardware!
  52. ```
  54. This will create all the files needed to support your new keyboard, and populate the settings with default values. Now you just need to customize it for your keyboard.
  56. ## `readme.md`
  58. This is where you'll describe your keyboard. Please follow the [Keyboard Readme Template](documentation_templates#keyboard-readmemd-template) when writing your `readme.md`. You're encouraged to place an image at the top of your `readme.md`, please use an external service such as [Imgur](https://imgur.com) to host the images.
  60. ## `keyboard.json`
  62. The `keyboard.json` file is where you configure the hardware and feature set for your keyboard. There are a lot of options that can be placed in that file, too many to list here. For a complete overview of available options see the [Data Driven Configuration Options](reference_info_json) page.
  64. ### Hardware Configuration
  66. At the top of the `keyboard.json` you'll find USB related settings. These control how your keyboard appears to the Operating System. If you don't have a good reason to change you should leave the `usb.vid` as `0xFEED`. For the `usb.pid` you should pick a number that is not yet in use.
  68. Do change the `manufacturer` and `keyboard_name` lines to accurately reflect your keyboard.
  70. ```json
  71.     "keyboard_name": "my_awesome_keyboard",
  72.     "maintainer": "You",
  73.     "usb": {
  74.         "vid": "0xFEED",
  75.         "pid": "0x0000",
  76.         "device_version": "1.0.0"
  77.     },
  78. ```
  80. ::: tip
  81. Windows and macOS will display the `manufacturer` and `keyboard_name` in the list of USB devices. `lsusb` on Linux instead prefers the values in the list maintained by the [USB ID Repository](http://www.linux-usb.org/usb-ids.html). By default, it will only use `manufacturer` and `keyboard_name` if the list does not contain that `usb.vid` / `usb.pid`. `sudo lsusb -v` will show the values reported by the device, and they are also present in kernel logs after plugging it in.
  82. :::
  84. ### Matrix Configuration
  86. The next section of the `keyboard.json` deals with your keyboard's matrix. The first thing you should define is which pins on your MCU are connected to rows and columns. To do so simply specify the names of those pins:
  88. #### Diode Matrix
  90. ```json
  91.     "matrix_pins": {
  92.         "cols": ["C1", "C2", "C3", "C4"],
  93.         "rows": ["D1", "D2", "D3", "D4"]
  94.     },
  95. ```
  97. The matrix dimensions are inferred from the length of the `matrix_pins.cols` and `matrix_pins.rows` arrays (previously specified explicitly in `config.h` with `MATRIX_ROWS` and `MATRIX_COLS`).
  99. Finally, you can specify the direction your diodes point. This can be `COL2ROW` or `ROW2COL`.
  101. ```json
  102.     "diode_direction": "ROW2COL",
  103. ```
  105. #### Direct Pin Matrix
  107. To configure a keyboard where each switch is connected to a separate pin and ground instead of sharing row and column pins, use `matrix_pins.direct`. This overrides the behaviour of `diode_direction`, `matrix_pins.cols` and `matrix_pins.rows`, and they should not be specified together.
  109. ```json
  110.     "matrix_pins": {
  111.         "direct": [
  112.             ["F1", "E6", "B0", "B2", "B3"],
  113.             ["F5", "F0", "B1", "B7", "D2"],
  114.             ["F6", "F7", "C7", "D5", "D3"],
  115.             ["B5", "C6", "B6", null, null]
  116.         ]
  117.     },
  118. ```
  120. Here, the matrix dimensions are inferred directly from the dimensions of the `matrix_pins.direct` array. Since there are no row or column pins to prescribe the matrix dimensions, you can arrange it however you like. Each "row" must contain the same number of "column"s; use `null` to fill in blank spaces, but try to minimize them.
  122. ### Layout Macros
  124. Next is configuring layout macro(s). These define the physical arrangement of keys, and their position within the matrix that switches are connected to. This allows you to have a physical arrangement of keys that differs from the wiring matrix.
  126. ```json
  127.     "layouts": {
  128.         "LAYOUT_ortho_4x4": {
  129.             "layout": [
  130.                 {"matrix": [0, 0], "x": 0, "y": 0},
  131.                 {"matrix": [0, 1], "x": 1, "y": 0},
  132.                 {"matrix": [0, 2], "x": 2, "y": 0},
  133.                 {"matrix": [0, 3], "x": 3, "y": 0},
  134.                 {"matrix": [1, 0], "x": 0, "y": 1},
  135.                 {"matrix": [1, 1], "x": 1, "y": 1},
  136.                 {"matrix": [1, 2], "x": 2, "y": 1},
  137.                 {"matrix": [1, 3], "x": 3, "y": 1},
  138.                 {"matrix": [2, 0], "x": 0, "y": 2},
  139.                 {"matrix": [2, 1], "x": 1, "y": 2},
  140.                 {"matrix": [2, 2], "x": 2, "y": 2},
  141.                 {"matrix": [2, 3], "x": 3, "y": 2},
  142.                 {"matrix": [3, 0], "x": 0, "y": 3},
  143.                 {"matrix": [3, 1], "x": 1, "y": 3},
  144.                 {"matrix": [3, 2], "x": 2, "y": 3},
  145.                 {"matrix": [3, 3], "x": 3, "y": 3}
  146.             ]
  147.         }
  148.     }
  149. ```
  151. In the above example,
  153. * `LAYOUT_ortho_4x4` defines the name of the layout macro
  154.   * It must conform to the [layout guidelines](hardware_keyboard_guidelines#keyboard-name-h)
  155. * `"matrix": [0, 0]` defines the matrix row and column that the key is associated with
  157. ::: tip
  158. See also: [Split Keyboard Layout Macro](features/split_keyboard#layout-macro) and [Matrix to Physical Layout](understanding_qmk#matrix-to-physical-layout-map).
  159. :::
  161. ## Additional Configuration
  163. There are a lot of features that can be turned on or off, configured or tuned. Some of these have yet to be migrated over to [Data Driven Configuration](data_driven_config). The following sections cover the process for when a data-driven option is unavailable.
  165. ### Configuration Options
  167. For available options for `config.h`, you should see the [Config Options](config_options#the-configh-file) page for more details.
  169. ### Build Options
  171. For available options for `rules.mk`, see the [Config Options](config_options#feature-options) page for a detailed list and description.