docs/config_options.md

   1 # The `config.h` file
   2
   3 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 (namely keymaps). This file can exist at a couple different levels:
   4
   5 ## Keyboard
   6
   7 ```c
   8 #ifndef CONFIG_H
   9 #define CONFIG_H
  10
  11 #include "config_common.h"
  12
  13 // config options
  14
  15 #ifdef SUBPROJECT_<subproject>
  16     #include "<subproject>/config.h"
  17 #endif
  18
  19 #endif
  20 ```
  21
  22 This file contains config options that should apply to the whole keyboard, and won't change in subprojects, or most keymaps. The suproject block here only applies to keyboards with subprojects.
  23
  24 ## Subproject
  25
  26 ```c
  27 #ifndef <subproject>_CONFIG_H
  28 #define <subproject>_CONFIG_H
  29
  30 #include "../config.h"
  31
  32 // config options
  33
  34 #endif
  35 ```
  36
  37 For keyboards that have subprojects, this file contains config options that should apply to only that subproject, and won't change in most keymaps.
  38
  39 ## Keymap
  40
  41 ```c
  42 #ifndef CONFIG_USER_H
  43 #define CONFIG_USER_H
  44
  45 #include "../../config.h"
  46
  47 // config options
  48
  49 #endif
  50 ```
  51
  52 This file 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.
  53
  54 # Config Options
  55
  56 ```c
  57 #define VENDOR_ID 0x1234 // defines your VID, and for most DIY projects, can be whatever you want
  58 #define PRODUCT_ID 0x5678 // defines your PID, and for most DIY projects, can be whatever you want
  59 #define DEVICE_VER 0 // defines the device version (often used for revisions)
  60
  61 #define MANUFACTURER Me // generally who/whatever brand produced the board
  62 #define PRODUCT Board // the name of the keyboard
  63 #define DESCRIPTION a keyboard // a short description of what the keyboard is
  64
  65 #define MATRIX_ROWS 5 // the number of rows in your keyboard's matrix
  66 #define MATRIX_COLS 15 // the number of columns in your keyboard's matrix
  67
  68 #define MATRIX_ROW_PINS { D0, D5, B5, B6 } // pins of the rows, from top to bottom
  69 #define MATRIX_COL_PINS { F1, F0, B0, C7, F4, F5, F6, F7, D4, D6, B4, D7 } // pins of the columns, from left to right
  70 #define UNUSED_PINS { D1, D2, D3, B1, B2, B3 } // pins unused by the keyboard for reference
  71 #define MATRIX_HAS_GHOST // define is matrix has ghost (unlikely)
  72 #define DIODE_DIRECTION COL2ROW // COL2ROW or ROW2COL - how your matrix is configured
  73 // COL2ROW means the black mark on your diode is facing to the rows, and between the switch and the rows
  74
  75 #define AUDIO_VOICES // turns on the alternate audio voices (to cycle through)
  76 #define C6_AUDIO // enables audio on pin C6
  77 #define B5_AUDIO // enables audio on pin B5 (duophony is enable if both are enabled)
  78
  79 #define BACKLIGHT_PIN B7 // pin of the backlight - B5, B6, B7 use PWM, others use softPWM
  80 #define BACKLIGHT_LEVELS 3 // number of levels your backlight will have (not including off)
  81
  82 #define DEBOUNCING_DELAY 5 // the delay when reading the value of the pin (5 is default)
  83
  84 #define LOCKING_SUPPORT_ENABLE // mechanical locking support. Use KC_LCAP, KC_LNUM or KC_LSCR instead in keymap
  85 #define LOCKING_RESYNC_ENABLE // tries to keep switch state consistent with keyboard LED state
  86
  87 #define IS_COMMAND() ( \ // key combination that allows the use of magic commands (useful for debugging)
  88     keyboard_report->mods == (MOD_BIT(KC_LSHIFT) | MOD_BIT(KC_RSHIFT)) \
  89 )
  90
  91 // the following options can save on file size at the expense of that feature
  92 #define NO_DEBUG // disable debuging (saves on file size)
  93 #define NO_PRINT // disable printing (saves of file size)
  94 #define NO_ACTION_LAYER // no layers
  95 #define NO_ACTION_TAPPING // no tapping for layers/mods
  96 #define NO_ACTION_ONESHOT // no oneshot for layers/mods
  97 #define NO_ACTION_MACRO // no macros
  98 #define NO_ACTION_FUNCTION // no functions
  99
 100 #define FORCE_NKRO // NKRO by default requires to be turned on, this forces it to be on always
 101
 102 #define PREVENT_STUCK_MODIFIERS // when switching layers, this will release all mods
 103
 104 #define TAPPING_TERM 200 // how long before a tap becomes a hold
 105 #define TAPPING_TOGGLE 2 // how many taps before triggering the toggle
 106
 107 #define PERMISSIVE_HOLD // makes tap and hold keys work better for fast typers who don't want tapping term set above 500
 108
 109 #define LEADER_TIMEOUT 300 // how long before the leader key times out
 110
 111 #define ONESHOT_TIMEOUT 300 // how long before oneshot times out
 112 #define ONESHOT_TAP_TOGGLE 2 // how many taps before oneshot toggle is triggered
 113
 114 #define IGNORE_MOD_TAP_INTERRUPT // makes it possible to do rolling combos (zx) with keys that convert to other keys on hold
 115
 116 // ws2812 options
 117 #define RGB_DI_PIN D7 // pin the DI on the ws2812 is hooked-up to
 118 #define RGBLIGHT_ANIMATIONS // run RGB animations
 119 #define RGBLED_NUM 15 // number of LEDs
 120 #define RGBLIGHT_HUE_STEP 12 // units to step when in/decreasing hue
 121 #define RGBLIGHT_SAT_STEP 25 // units to step when in/decresing saturation
 122 #define RGBLIGHT_VAL_STEP 12 // units to step when in/decreasing value (brightness)
 123
 124 #define RGBW_BB_TWI // bit-bangs twi to EZ RGBW LEDs (only required for Ergodox EZ)
 125
 126 // mousekey options (self-describing)
 127 #define MOUSEKEY_INTERVAL 20
 128 #define MOUSEKEY_DELAY 0
 129 #define MOUSEKEY_TIME_TO_MAX 60
 130 #define MOUSEKEY_MAX_SPEED 7
 131 #define MOUSEKEY_WHEEL_DELAY 0
 132
 133 ```