# Configuring QMK QMK is nearly infinitely configurable. Wherever possible we err on the side of allowing users to customize their keyboard, even at the expense of code size. That level of flexibility makes for a daunting configuration experience, however. There are two main types of configuration files in QMK- `config.h` and `rules.mk`. These files exist at various levels in QMK and all files of the same type are combined to build the final configuration. The levels, from lowest priority to highest priority, are: * QMK Default * Keyboard * Folders (Up to 5 levels deep) * Keymap ## QMK Default Every available setting in QMK has a default. If that setting is not set at the Keyboard, Folder, or Keymap level this is the setting that will be used. ## Keyboard This level contains config options that should apply to the whole keyboard. Some settings won't change in revisions, or most keymaps. Other settings are merely defaults for this keyboard and can be overridden by folders and/or keymaps. ## Folders Some keyboards have folders and sub-folders to allow for different hardware configurations. Most keyboards only go 1 folder deep, but QMK supports structures up to 5 folders deep. Each folder can have its own `config.h` and `rules.mk` files that are incorporated into the final configuration. ## Keymap This level contains all of the options for that particular keymap. If you wish to override a previous declaration, you can use `#undef ` to undefine it, where you can then redefine it without an error. # The `config.h` File This is a C header file that is one of the first things included, and will persist over the whole project (if included). Lots of variables can be set here and accessed elsewhere. The `config.h` file shouldn't be including other `config.h` files, or anything besides this: #include "config_common.h" ## Hardware Options * `#define VENDOR_ID 0x1234` * defines your VID, and for most DIY projects, can be whatever you want * `#define PRODUCT_ID 0x5678` * defines your PID, and for most DIY projects, can be whatever you want * `#define DEVICE_VER 0` * defines the device version (often used for revisions) * `#define MANUFACTURER Me` * generally who/whatever brand produced the board * `#define PRODUCT Board` * the name of the keyboard * `#define MATRIX_ROWS 5` * the number of rows in your keyboard's matrix * `#define MATRIX_COLS 15` * the number of columns in your keyboard's matrix * `#define MATRIX_ROW_PINS { D0, D5, B5, B6 }` * pins of the rows, from top to bottom * `#define MATRIX_COL_PINS { F1, F0, B0, C7, F4, F5, F6, F7, D4, D6, B4, D7 }` * pins of the columns, from left to right * `#define MATRIX_IO_DELAY 30` * the delay in microseconds when between changing matrix pin state and reading values * `#define UNUSED_PINS { D1, D2, D3, B1, B2, B3 }` * pins unused by the keyboard for reference * `#define MATRIX_HAS_GHOST` * define is matrix has ghost (unlikely) * `#define DIODE_DIRECTION COL2ROW` * COL2ROW or ROW2COL - how your matrix is configured. COL2ROW means the black mark on your diode is facing to the rows, and between the switch and the rows. * `#define DIRECT_PINS { { F1, F0, B0, C7 }, { F4, F5, F6, F7 } }` * pins mapped to rows and columns, from left to right. Defines a matrix where each switch is connected to a separate pin and ground. * `#define AUDIO_VOICES` * turns on the alternate audio voices (to cycle through) * `#define C4_AUDIO` * enables audio on pin C4 * `#define C5_AUDIO` * enables audio on pin C5 * `#define C6_AUDIO` * enables audio on pin C6 * `#define B5_AUDIO` * enables audio on pin B5 (duophony is enables if one of B[5-7]\_AUDIO is enabled along with one of C[4-6]\_AUDIO) * `#define B6_AUDIO` * enables audio on pin B6 (duophony is enables if one of B[5-7]\_AUDIO is enabled along with one of C[4-6]\_AUDIO) * `#define B7_AUDIO` * enables audio on pin B7 (duophony is enables if one of B[5-7]\_AUDIO is enabled along with one of C[4-6]\_AUDIO) * `#define BACKLIGHT_PIN B7` * pin of the backlight * `#define BACKLIGHT_LEVELS 3` * number of levels your backlight will have (maximum 31 excluding off) * `#define BACKLIGHT_BREATHING` * enables backlight breathing * `#define BREATHING_PERIOD 6` * the length of one backlight "breath" in seconds * `#define DEBOUNCE 5` * the delay when reading the value of the pin (5 is default) * `#define LOCKING_SUPPORT_ENABLE` * mechanical locking support. Use KC_LCAP, KC_LNUM or KC_LSCR instead in keymap * `#define LOCKING_RESYNC_ENABLE` * tries to keep switch state consistent with keyboard LED state * `#define IS_COMMAND() (get_mods() == MOD_MASK_SHIFT)` * key combination that allows the use of magic commands (useful for debugging) * `#define USB_MAX_POWER_CONSUMPTION 500` * sets the maximum power (in mA) over USB for the device (default: 500) * `#define USB_POLLING_INTERVAL_MS 10` * sets the USB polling rate in milliseconds for the keyboard, mouse, and shared (NKRO/media keys) interfaces * `#define F_SCL 100000L` * sets the I2C clock rate speed for keyboards using I2C. The default is `400000L`, except for keyboards using `split_common`, where the default is `100000L`. ## Features That Can Be Disabled If you define these options you will disable the associated feature, which can save on code size. * `#define NO_DEBUG` * disable debugging * `#define NO_PRINT` * disable printing/debugging using hid_listen * `#define NO_ACTION_LAYER` * disable layers * `#define NO_ACTION_TAPPING` * disable tap dance and other tapping features * `#define NO_ACTION_ONESHOT` * disable one-shot modifiers * `#define NO_ACTION_MACRO` * disable old-style macro handling using `MACRO()`, `action_get_macro()` _(deprecated)_ * `#define NO_ACTION_FUNCTION` * disable old-style function handling using `fn_actions`, `action_function()` _(deprecated)_ ## Features That Can Be Enabled If you define these options you will enable the associated feature, which may increase your code size. * `#define FORCE_NKRO` * NKRO by default requires to be turned on, this forces it on during keyboard startup regardless of EEPROM setting. NKRO can still be turned off but will be turned on again if the keyboard reboots. * `#define STRICT_LAYER_RELEASE` * force a key release to be evaluated using the current layer stack instead of remembering which layer it came from (used for advanced cases) ## Behaviors That Can Be Conf

/*
    ChibiOS - Copyright (C) 2006..2015 Giovanni Di Sirio

    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
    You may obtain a copy of the License at

        http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.
*/

#include "hal.h"
#include "ch_test.h"
#include "test_root.h"

/**
 * @page test_sequence_XXX Sequence brief description
 *
 * File: @ref test_sequence_XXX.c
 *
 * <h2>Description</h2>
 * Sequence detailed description.
 *
 * <h2>Test Cases</h2>
 * - @subpage test_XXX_001
 * .
 */

/****************************************************************************
 * Shared code.
 ****************************************************************************/


/****************************************************************************
 * Test cases.
 ****************************************************************************/

#if TEST_XXX_000_CONDITION || defined(__DOXYGEN__)
/**
 * @page test_XXX_001 Brief description
 *
 * <h2>Description</h2>
 * Detailed description.
 *
 * <h2>Conditions</h2>
 * This test is only executed if the following preprocessor condition
 * evaluates to true:
 * - TEST_XXX_001_CONDITION
 * .
 *
 * <h2>Test Steps</h2>
 * - Step description.
 * .
 */

static void test_XXX_001_setup(void) {

}

static void test_XXX_001_teardown(void) {

}

static void test_XXX_001_execute(void) {

  /* Step description.*/
  test_set_step(1);
  {
  }
}

static const testcase_t test_XXX_001 = {
  "Brief description",
  test_XXX_001_setup,
  test_XXX_001_teardown,
  test_XXX_001_execute
};
#endif /* TEST_XXX_001_CONDITION */

 /****************************************************************************
 * Exported data.
 ****************************************************************************/

/**
 * @brief   Sequence brief description.
 */
const testcase_t * const test_sequence_XXX[] = {
#if TEST_XXX_001_CONDITION || defined(__DOXYGEN__)
  &test_XXX_001,
#endif
  NULL
};

ink Time Optimization (LTO) when compiling the keyboard. This makes the process take longer, but it can significantly reduce the compiled size (and since the firmware is small, the added time is not noticeable). However, this will automatically disable the legacy TMK Macros and Functions features, as these break when LTO is enabled. It does this by automatically defining `NO_ACTION_MACRO` and `NO_ACTION_FUNCTION`. (Note: This does not affect QMK [Macros](feature_macros.md) and [Layers](feature_layers.md).) ## AVR MCU Options * `MCU = atmega32u4` * `F_CPU = 16000000` * `ARCH = AVR8` * `F_USB = $(F_CPU)` * `OPT_DEFS += -DINTERRUPT_CONTROL_ENDPOINT` * `BOOTLOADER = atmel-dfu` with the following options: * `atmel-dfu` * `lufa-dfu` * `qmk-dfu` * `halfkay` * `caterina` * `bootloadHID` * `USBasp` ## Feature Options :id=feature-options Use these to enable or disable building certain features. The more you have enabled the bigger your firmware will be, and you run the risk of building a firmware too large for your MCU. * `BOOTMAGIC_ENABLE` * Virtual DIP switch configuration * `MOUSEKEY_ENABLE` * Mouse keys * `EXTRAKEY_ENABLE` * Audio control and System control * `CONSOLE_ENABLE` * Console for debug * `COMMAND_ENABLE` * Commands for debug and configuration * `COMBO_ENABLE` * Key combo feature * `NKRO_ENABLE` * USB N-Key Rollover - if this doesn't work, see here: https://github.com/tmk/tmk_keyboard/wiki/FAQ#nkro-doesnt-work * `AUDIO_ENABLE` * Enable the audio subsystem. * `RGBLIGHT_ENABLE` * Enable keyboard underlight functionality * `LEADER_ENABLE` * Enable leader key chording * `MIDI_ENABLE` * MIDI controls * `UNICODE_ENABLE` * Unicode * `BLUETOOTH` * Current options are AdafruitBLE, RN42 * `SPLIT_KEYBOARD` * Enables split keyboard support (dual MCU like the let's split and bakingpy's boards) and includes all necessary files located at quantum/split_common * `CUSTOM_MATRIX` * Allows replacing the standard matrix scanning routine with a custom one. * `DEBOUNCE_TYPE` * Allows replacing the standard key debouncing routine with an alternative or custom one. * `WAIT_FOR_USB` * Forces the keyboard to wait for a USB connection to be established before it starts up * `NO_USB_STARTUP_CHECK` * Disables usb suspend check after keyboard startup. Usually the keyboard waits for the host to wake it up before any tasks are performed. This is useful for split keyboards as one half will not get a wakeup call but must send commands to the master. ## USB Endpoint Limitations In order to provide services over USB, QMK has to use USB endpoints. These are a finite resource: each microcontroller has only a certain number. This limits what features can be enabled together. If the available endpoints are exceeded, a build error is thrown. The following features can require separate endpoints: * `MOUSEKEY_ENABLE` * `EXTRAKEY_ENABLE` * `CONSOLE_ENABLE` * `NKRO_ENABLE` * `MIDI_ENABLE` * `RAW_ENABLE` * `VIRTSER_ENABLE` In order to improve utilisation of the endpoints, the HID features can be combined to use a single endpoint. By default, `MOUSEKEY`, `EXTRAKEY`, and `NKRO` are combined into a single endpoint. The base keyboard functionality can also be combined into the endpoint, by setting `KEYBOARD_SHARED_EP = yes`. This frees up one more endpoint, but it can prevent the keyboard working in some BIOSes, as they do not implement Boot Keyboard protocol switching. Combining the mouse also breaks Boot Mouse compatibility. The mouse can be uncombined by setting `MOUSE_SHARED_EP = no` if this functionality is required.