## Adding Your AVR Keyboard to QMK
-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_project.sh` script:
+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:
```
-$ util/new_project.sh my_awesome_keyboard
-######################################################
-# /keyboards/my_awesome_keyboard project created. To start
-# working on things, cd into keyboards/my_awesome_keyboard
-######################################################
+$ ./util/new_keyboard.sh
+Generating a new QMK keyboard directory
+
+Keyboard Name: mycoolkb
+Keyboard Type [avr]:
+Your Name [John Smith]:
+
+Copying base template files... done
+Copying avr template files... done
+Renaming keyboard files... done
+Replacing %KEYBOARD% with mycoolkb... done
+Replacing %YOUR_NAME% with John Smith... done
+
+Created a new keyboard called mycoolkb.
+
+To start working on things, cd into keyboards/mycoolkb,
+or open the directory in your favourite text editor.
```
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.
## `<keyboard>.h`
-This is the file you define your [Layout Macro(s)](feature_layouts.md) in. At minumum you should have a `#define LAYOUT` for your keyboard that looks something like this:
+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:
-```
+```c
#define LAYOUT( \
k00, k01, k02, \
k10, k11 \
Each of the `k__` variables needs to be unique, and typically they follow the format `k<row><col>`.
-The physical matrix (the second half) must have a number of rows equalling `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.
+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.
## `config.h`
Do change the `MANUFACTURER`, `PRODUCT`, and `DESCRIPTION` lines to accurately reflect your keyboard.
-```
+```c
#define VENDOR_ID 0xFEED
#define PRODUCT_ID 0x6060
#define DEVICE_VER 0x0001
#define DESCRIPTION A custom keyboard
```
-{% hint style='info' %}
-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`, since Linux takes that information from the list published by the USB-IF.
-{% endhint %}
+?> 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.
### Keyboard Matrix Configuration
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.
-```
+```c
#define MATRIX_ROWS 2
#define MATRIX_COLS 3
```
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:
-```
+```c
#define MATRIX_ROW_PINS { D0, D5 }
#define MATRIX_COL_PINS { F1, F0, B0 }
#define UNUSED_PINS
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.
-Finally, you can specify the direction your diodes point. This can be `COL2ROW`, `ROW2COL`, or `CUSTOM_MATRIX`.
+Finally, you can specify the direction your diodes point. This can be `COL2ROW` or `ROW2COL`.
-```
+```c
#define DIODE_DIRECTION COL2ROW
```
+#### Direct Pin Matrix
+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`.
+
+```c
+// #define MATRIX_ROW_PINS { D0, D5 }
+// #define MATRIX_COL_PINS { F1, F0, B0 }
+#define DIRECT_PINS { \
+ { F1, E6, B0, B2, B3 }, \
+ { F5, F0, B1, B7, D2 }, \
+ { F6, F7, C7, D5, D3 }, \
+ { B5, C6, B6, NO_PIN, NO_PIN } \
+}
+#define UNUSED_PINS
+
+/* COL2ROW, ROW2COL */
+//#define DIODE_DIRECTION
+```
+
### Backlight Configuration
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).
-```
+```c
#define BACKLIGHT_PIN B7
-#define BACKLIGHT_BREATHING
#define BACKLIGHT_LEVELS 3
+#define BACKLIGHT_BREATHING
+#define BREATHING_PERIOD 6
```
-{% hint style='info' %}
-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.
-{% endhint %}
+?> 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.
### Other Configuration Options
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.
-```
+```make
MCU = atmega32u4
F_CPU = 16000000
ARCH = AVR8
OPT_DEFS += -DINTERRUPT_CONTROL_ENDPOINT
```
-### Bootloader Size
+### Bootloaders
-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. If you are using a teensy 2.0, or a device like the Ergodox EZ that uses the teensy bootloader you should set this to `512`. Most other bootloaders should be set to `4096`, but `1024` and `2048` are other possible values you may encounter.
+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.
-#### Teensy 2.0 Bootloader Example
+#### Teensy Bootloader Example
-```
-OPT_DEFS += -DBOOTLOADER_SIZE=512
+```make
+BOOTLOADER = halfkay
```
-#### Teensy 2.0++ Bootloader Example
+#### Atmel DFU Loader Example
-```
-OPT_DEFS += -DBOOTLOADER_SIZE=1024
+```make
+BOOTLOADER = atmel-dfu
```
-#### Atmel DFU Loader Example
+#### Pro Micro Bootloader Example
-```
-OPT_DEFS += -DBOOTLOADER_SIZE=4096
+```make
+BOOTLOADER = caterina
```
### Build Options
projects / qmk_firmware.git / blobdiff