This level contains all of the options for that particular keymap. If you wish to override a previous declaration, you can use `#undef <variable>` to undefine it, where you can then redefine it without an error.
-# The `config.h` file
+# 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.
+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:
-## `config.h` Options
+ #include "config_common.h"
-### Hardware Options
+
+## Hardware Options
* `#define VENDOR_ID 0x1234`
* defines your VID, and for most DIY projects, can be whatever you want
* `#define PRODUCT_ID 0x5678`
* 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 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 enable if both are enabled)
+ * 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 - B5, B6, B7 use PWM, others use softPWM
* `#define BACKLIGHT_LEVELS 3`
- * number of levels your backlight will have (not including off)
+ * number of levels your backlight will have (maximum 15 excluding off)
+* `#define BACKLIGHT_BREATHING`
+ * enables backlight breathing (only works with backlight pins B5, B6 and B7)
+* `#define BREATHING_PERIOD 6`
+ * the length of one backlight "breath" in seconds
* `#define DEBOUNCING_DELAY 5`
* the delay when reading the value of the pin (5 is default)
* `#define LOCKING_SUPPORT_ENABLE`
* tries to keep switch state consistent with keyboard LED state
* `#define IS_COMMAND() ( keyboard_report->mods == (MOD_BIT(KC_LSHIFT) | MOD_BIT(KC_RSHIFT)) )`
* key combination that allows the use of magic commands (useful for debugging)
+* `#define USB_MAX_POWER_CONSUMPTION`
+ * sets the maximum power (in mA) over USB for the device (default: 500)
+* `#define SCL_CLOCK 100000L`
+ * sets the SCL_CLOCK speed for split keyboards. The default is `100000L` but some boards can be set to `400000L`.
-### Features That Can Be Disabled
+## 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 debuging
+ * disable debugging
* `#define NO_PRINT`
* disable printing/debugging using hid_listen
* `#define NO_ACTION_LAYER`
* `#define NO_ACTION_FUNCTION`
* disable the action function (deprecated)
-### Features That Can Be Enabled
+## 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 PREVENT_STUCK_MODIFIERS`
- * when switching layers, this will release all mods
+ * 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 Configured
+## Behaviors That Can Be Configured
* `#define TAPPING_TERM 200`
- * how long before a tap becomes a hold
+ * how long before a tap becomes a hold, if set above 500, a key tapped during the tapping term will turn it into a hold too
* `#define RETRO_TAPPING`
* tap anyway, even after TAPPING_TERM, if there was no other key interruption between press and release
+ * See [Retro Tapping](feature_advanced_keycodes.md#retro-tapping) for details
* `#define TAPPING_TOGGLE 2`
* how many taps before triggering the toggle
* `#define PERMISSIVE_HOLD`
- * makes tap and hold keys work better for fast typers who don't want tapping term set above 500
+ * makes tap and hold keys trigger the hold if another key is pressed before releasing, even if it hasn't hit the `TAPPING_TERM`
+ * See [Permissive Hold](feature_advanced_keycodes.md#permissive-hold) for details
+* `#define IGNORE_MOD_TAP_INTERRUPT`
+ * makes it possible to do rolling combos (zx) with keys that convert to other keys on hold, by enforcing the `TAPPING_TERM` for both keys.
+ * See [Mod tap interrupt](feature_advanced_keycodes.md#ignore-mod-tap-interrupt) for details
+* `#define TAPPING_FORCE_HOLD`
+ * makes it possible to use a dual role key as modifier shortly after having been tapped
+ * See [Hold after tap](feature_advanced_keycodes.md#tapping-force-hold)
+ * Breaks any Tap Toggle functionality (`TT` or the One Shot Tap Toggle)
* `#define LEADER_TIMEOUT 300`
* how long before the leader key times out
* `#define ONESHOT_TIMEOUT 300`
* how long before oneshot times out
* `#define ONESHOT_TAP_TOGGLE 2`
* how many taps before oneshot toggle is triggered
-* `#define IGNORE_MOD_TAP_INTERRUPT`
- * makes it possible to do rolling combos (zx) with keys that convert to other keys on hold
-
-### RGB Light Configuration
+* `#define QMK_KEYS_PER_SCAN 4`
+ * Allows sending more than one key per scan. By default, only one key event gets
+ sent via `process_record()` per scan. This has little impact on most typing, but
+ if you're doing a lot of chords, or your scan rate is slow to begin with, you can
+ have some delay in processing key events. Each press and release is a separate
+ event. For a keyboard with 1ms or so scan times, even a very fast typist isn't
+ going to produce the 500 keystrokes a second needed to actually get more than a
+ few ms of delay from this. But if you're doing chording on something with 3-4ms
+ scan times? You probably want this.
+* `#define COMBO_COUNT 2`
+ * Set this to the number of combos that you're using in the [Combo](feature_combo.md) feature.
+* `#define COMBO_TERM 200`
+ * how long for the Combo keys to be detected. Defaults to `TAPPING_TERM` if not defined.
+* `#define TAP_CODE_DELAY 100`
+ * Sets the delay between `register_code` and `unregister_code`, if you're having issues with it registering properly (common on VUSB boards). The value is in milliseconds.
+
+## RGB Light Configuration
* `#define RGB_DI_PIN D7`
* pin the DI on the ws2812 is hooked-up to
* `#define RGBLIGHT_HUE_STEP 12`
* units to step when in/decreasing hue
* `#define RGBLIGHT_SAT_STEP 25`
- * units to step when in/decresing saturation
+ * units to step when in/decreasing saturation
* `#define RGBLIGHT_VAL_STEP 12`
* units to step when in/decreasing value (brightness)
* `#define RGBW_BB_TWI`
- * bit-bangs twi to EZ RGBW LEDs (only required for Ergodox EZ)
+ * bit-bangs TWI to EZ RGBW LEDs (only required for Ergodox EZ)
-### Mouse Key Options
+## Mouse Key Options
* `#define MOUSEKEY_INTERVAL 20`
* `#define MOUSEKEY_DELAY 0`
* `#define MOUSEKEY_MAX_SPEED 7`
* `#define MOUSEKEY_WHEEL_DELAY 0`
+## Split Keyboard Options
+
+Split Keyboard specific options, make sure you have 'SPLIT_KEYBOARD = yes' in your rules.mk
+
+* `#define SPLIT_HAND_PIN B7`
+ * For using high/low pin to determine handedness, low = right hand, high = left hand. Replace 'B7' with the pin you are using. This is optional and you can still use the EEHANDS method or MASTER_LEFT / MASTER_RIGHT defines like the stock Let's Split uses.
+
+* `#define USE_I2C`
+ * For using I2C instead of Serial (defaults to serial)
+
+* `#define SOFT_SERIAL_PIN D0`
+ * When using serial, define this. `D0` or `D1`,`D2`,`D3`,`E6`.
+
# The `rules.mk` File
This is a [make](https://www.gnu.org/software/make/manual/make.html) file that is included by the top-level `Makefile`. It is used to set some information about the MCU that we will be compiling for as well as enabling and disabling certain features.
-## `rules.mk` options
-
-### Build Options
+## Build Options
* `DEFAULT_FOLDER`
* Used to specify a default folder when a keyboard has more than one sub-folder.
+* `FIRMWARE_FORMAT`
+ * Defines which format (bin, hex) is copied to the root `qmk_firmware` folder after building.
* `SRC`
* Used to add files to the compilation/linking list.
* `LAYOUTS`
* A list of [layouts](feature_layouts.md) this keyboard supports.
-### AVR MCU Options
+## AVR MCU Options
* `MCU = atmega32u4`
* `F_CPU = 16000000`
* `ARCH = AVR8`
* `F_USB = $(F_CPU)`
* `OPT_DEFS += -DINTERRUPT_CONTROL_ENDPOINT`
-* `OPT_DEFS += -DBOOTLOADER_SIZE=4096`
+* `BOOTLOADER = atmel-dfu` with the following options:
+ * `atmel-dfu`
+ * `lufa-dfu`
+ * `qmk-dfu`
+ * `halfkay`
+ * `caterina`
+ * `bootloadHID`
-### Feature Options
+## 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.
* Console for debug(+400)
* `COMMAND_ENABLE`
* Commands for debug and configuration
+* `COMBO_ENABLE`
+ * Key combo feature
* `NKRO_ENABLE`
- * USB Nkey Rollover - if this doesn't work, see here: https://github.com/tmk/tmk_keyboard/wiki/FAQ#nkro-doesnt-work
+ * 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`
* `UNICODE_ENABLE`
* Unicode
* `BLUETOOTH_ENABLE`
- * Enable Bluetooth with the Adafruit EZ-Key HID
+ * Legacy option to Enable Bluetooth with the Adafruit EZ-Key HID. See BLUETOOTH
+* `BLUETOOTH`
+ * Current options are AdafruitEzKey, 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
+* `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.
projects / qmk_firmware.git / blobdiff