docs/hardware_avr.md

   1 # Keyboards with AVR Processors
   2
   3 This page describes the support for for AVR processors in QMK. AVR processors include the atmega32u4, atmega32u2, at90usb1286, and other processors from Atmel Corporation. AVR processors are 8-bit MCU's that are designed to be easy to work with. The most common AVR processors in keyboards have on-board USB and plenty of GPIO for supporting large keyboard matrices. They are the most popular MCU for use in keyboards today.
   4
   5 If you have not yet you should read the [Keyboard Guidelines](hardware_keyboard_guidelines.md) to get a sense of how keyboards fit into QMK.
   6
   7 ## Adding Your AVR Keyboard to QMK
   8
   9 QMK has a number of features to simplify working with AVR keyboards. For most keyboards you don't have to write a single line of code. To get started, run the `util/new_keyboard.sh` script:
  10
  11 ```
  12 $ ./util/new_keyboard.sh
  13 Generating a new QMK keyboard directory
  14
  15 Keyboard Name: mycoolkb
  16 Keyboard Type [avr]:
  17 Your Name [John Smith]:
  18
  19 Copying base template files... done
  20 Copying avr template files... done
  21 Renaming keyboard files... done
  22 Replacing %KEYBOARD% with mycoolkb... done
  23 Replacing %YOUR_NAME% with John Smith... done
  24
  25 Created a new keyboard called mycoolkb.
  26
  27 To start working on things, cd into keyboards/mycoolkb,
  28 or open the directory in your favourite text editor.
  29 ```
  30
  31 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.
  32
  33 ## `readme.md`
  34
  35 This is where you'll describe your keyboard. Please follow the [Keyboard Readme Template](documentation_templates.md#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](http://imgur.com) to host the images.
  36
  37 ## `<keyboard>.c`
  38
  39 This is where all the custom logic for your keyboard goes. Many keyboards do not need to put anything at all in here. You can learn more about writing custom logic in [Custom Quantum Functions](custom_quantum_functions.md).
  40
  41 ## `<keyboard>.h`
  42
  43 This is the file you define your [Layout Macro(s)](feature_layouts.md) in. At minimum you should have a `#define LAYOUT` for your keyboard that looks something like this:
  44
  45 ```c
  46 #define LAYOUT(          \
  47       k00, k01, k02,     \
  48       k10,   k11         \
  49 ) {                      \
  50     { k00, k01,   k02 }, \
  51     { k10, KC_NO, k11 }, \
  52 }
  53 ```
  54
  55 The first half of the `LAYOUT` pre-processor macro defines the physical arrangement of keys. The second half of the macro defines the matrix the switches are connected to. This allows you to have a physical arrangement of keys that differs from the wiring matrix.
  56
  57 Each of the `k__` variables needs to be unique, and typically they follow the format `k<row><col>`.
  58
  59 The physical matrix (the second half) must have a number of rows equaling `MATRIX_ROWS`, and each row must have exactly `MATRIX_COLS` elements in it. If you do not have this many physical keys you can use `KC_NO` to fill in the blank spots.
  60
  61 ## `config.h`
  62
  63 The `config.h` 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 there. For a complete overview of available options see the [Config Options](config_options.md) page.
  64
  65 ### Hardware Configuration
  66
  67
  68 At the top of the `config.h` 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 `VENDOR_ID` as `0xFEED`. For the `PRODUCT_ID` you should pick a number that is not yet in use.
  69
  70 Do change the `MANUFACTURER`, `PRODUCT`, and `DESCRIPTION` lines to accurately reflect your keyboard.
  71
  72 ```c
  73 #define VENDOR_ID       0xFEED
  74 #define PRODUCT_ID      0x6060
  75 #define DEVICE_VER      0x0001
  76 #define MANUFACTURER    You
  77 #define PRODUCT         my_awesome_keyboard
  78 #define DESCRIPTION     A custom keyboard
  79 ```
  80
  81 ?> Note: On Windows and macOS the `MANUFACTURER`, `PRODUCT`, and `DESCRIPTION` fields will be displayed in the list of USB devices. ?> On Linux these values will not be visible in lsusb by default, since Linux takes the information from the list maintained by [USB ID Repository](http://www.linux-usb.org/usb-ids.html) by default. lsusb will show the information reported by the device when executed with -v option. It is also present in kernel logs after plugging in the device.
  82
  83 ### Keyboard Matrix Configuration
  84
  85 The next section of the `config.h` file deals with your keyboard's matrix. The first thing you should set is the matrix's size. This is usually, but not always, the same number of rows and columns as the physical key arrangement.
  86
  87 ```c
  88 #define MATRIX_ROWS 2
  89 #define MATRIX_COLS 3
  90 ```
  91
  92 Once you've defined the size of your matrix you need to define which pins on your MCU are connected to rows and columns. To do so simply specify the names of those pins:
  93
  94 ```c
  95 #define MATRIX_ROW_PINS { D0, D5 }
  96 #define MATRIX_COL_PINS { F1, F0, B0 }
  97 #define UNUSED_PINS
  98 ```
  99
 100 The number of `MATRIX_ROW_PINS` entries must be the same as the number you assigned to `MATRIX_ROWS`, and likewise for `MATRIX_COL_PINS` and `MATRIX_COLS`. You do not have to specify `UNUSED_PINS`, but you can if you want to document what pins are open.
 101
 102 Finally, you can specify the direction your diodes point. This can be `COL2ROW` or `ROW2COL`.
 103
 104 ```c
 105 #define DIODE_DIRECTION COL2ROW
 106 ```
 107
 108 #### Direct Pin Matrix
 109 To configure a keyboard where each switch is connected to a separate pin and ground instead of sharing row and column pins, use `DIRECT_PINS`. The mapping defines the pins of each switch in rows and columns, from left to right. Must conform to the sizes within `MATRIX_ROWS` and `MATRIX_COLS`, use `NO_PIN` to fill in blank spaces. Overrides the behaviour of `DIODE_DIRECTION`, `MATRIX_ROW_PINS` and `MATRIX_COL_PINS`.
 110
 111 ```c
 112 // #define MATRIX_ROW_PINS { D0, D5 }
 113 // #define MATRIX_COL_PINS { F1, F0, B0 }
 114 #define DIRECT_PINS { \
 115     { F1, E6, B0, B2, B3 }, \
 116     { F5, F0, B1, B7, D2 }, \
 117     { F6, F7, C7, D5, D3 }, \
 118     { B5, C6, B6, NO_PIN, NO_PIN } \
 119 }
 120 #define UNUSED_PINS
 121
 122 /* COL2ROW, ROW2COL */
 123 //#define DIODE_DIRECTION
 124 ```
 125
 126 ### Backlight Configuration
 127
 128 By default QMK supports backlighting on pins `B5`, `B6`, and `B7`. If you are using one of those you can simply enable it here. For more details see the [Backlight Documentation](feature_backlight.md).
 129
 130 ```c
 131 #define BACKLIGHT_PIN B7
 132 #define BACKLIGHT_LEVELS 3
 133 #define BACKLIGHT_BREATHING
 134 #define BREATHING_PERIOD 6
 135 ```
 136
 137 ?> You can use backlighting on any pin you like, but you will have to do more work to support that. See the [Backlight Documentation](feature_backlight.md) for more details.
 138
 139 ### Other Configuration Options
 140
 141 There are a lot of features that can be configured or tuned in `config.h`. You should see the [Config Options](config_options.md) page for more details.
 142
 143 ## `rules.mk`
 144
 145 You use the `rules.mk` file to tell QMK what files to build and what features to enable. If you are building around an atmega32u4 you can largely leave these defaults alone. If you are using another MCU you may have to tweak some parameters.
 146
 147 ### MCU Options
 148
 149 These options tell the build system what CPU to build for. Be very careful if you change any of these settings, you can render your keyboard inoperable.
 150
 151 ```make
 152 MCU = atmega32u4
 153 F_CPU = 16000000
 154 ARCH = AVR8
 155 F_USB = $(F_CPU)
 156 OPT_DEFS += -DINTERRUPT_CONTROL_ENDPOINT
 157 ```
 158
 159 ### Bootloaders
 160
 161 The bootloader is a special section of your MCU that allows you to upgrade the code stored on the MCU. Think of it like a Rescue Partition for your keyboard.
 162
 163 #### Teensy Bootloader Example
 164
 165 ```make
 166 BOOTLOADER = halfkay
 167 ```
 168
 169 #### Atmel DFU Loader Example
 170
 171 ```make
 172 BOOTLOADER = atmel-dfu
 173 ```
 174
 175 #### Pro Micro Bootloader Example
 176
 177 ```make
 178 BOOTLOADER = caterina
 179 ```
 180
 181 ### Build Options
 182
 183 There are a number of features that can be turned on or off in `rules.mk`. See the [Config Options](config_options.md#feature-options) page for a detailed list and description.