users/drashna/readme.md

   1 # Overview
   2
   3 This is my personal userspace file.  Most of my code exists here, as it's heavily shared.
   4
   5 ## Custom userspace handlers
   6
   7 Specifically QMK works by using customized handlers for everything. This allows for multiple levels of customization.
   8
   9 `matrix_scan` calls `matrix_scan_quantum`, which alls `matrix_scan_kb`, which calls `matrix_scan_user`.
  10 `process_record` calls a bunch of stuff, but eventually calls `process_record_kb` which calls `process_record_user`
  11 The same goes for `matrix_init`, `layer_state_set`, `led_set`, and a few other functions.
  12
  13 All (most) `_user` functions are handled here instead.  To allow keyboard specific configuration, I've created `_keymap` functions that can be called by the keymap.c files instead.
  14
  15 This allows for keyboard specific configuration while maintaining the ability to customize the board.
  16
  17 My [Ergodox EZ Keymap](https://github.com/qmk/qmk_firmware/blob/master/layouts/community/ergodox/drashna/keymap.c#L297) is a good example of this, as it uses the LEDs as modifier indicators.
  18
  19 ## Keyboard Layout Templates
  20
  21 This borrows from @jola5's "Not quite neo" code.  This allows me to maintain blocks of keymaps in the userspace, so that I can modify the userspace, and this is reflected in all of the keyboards that use it, at once.
  22
  23 This makes adding tap/hold mods, or other special keycodes or functions to all keyboards super easy, as it's done to all of them at once.
  24
  25 The caveat here is that the keymap needs a processor/wrapper, as it doesn't like the substitutions.  However, this is as simple as just pushing it through a define. For instance:
  26
  27 `#define LAYOUT_ergodox_wrapper(...)   LAYOUT_ergodox(__VA_ARGS__)`
  28
  29 Once that's been done and you've switched the keymaps to use the "wrapper", it will read the substitution blocks just fine.
  30
  31 Credit goes to @jola5 for first implementing this awesome idea.
  32
  33
  34 ## Custom Keycodes
  35
  36 Keycodes are defined in the drashna.h file and need to be included in the keymap.c files, so that they can be used there.
  37
  38 A bunch of macros are present and are only included on boards that are not the Ergodox EZ or Orthodox, as they are not needed for those boards.
  39
  40 Included is a custom macro for compiling my keyboards.  This includes the bootloader target (`:teensy`, `:avrdude`, or `:dfu`), and keeps RGBLIGHT, AUDIO and/or FAUXCLICKY enabled, if it previously was (regardless of the rules file).
  41
  42 This also includes a modified RESET keycode as well, that sets the underglow to red.
  43
  44 ## Layer Indication
  45
  46 This uses the `layer_state_set_*` command to change the layer color, to indicate which layer it is on.  This includes the default keymap, as well.
  47
  48 Since this is done via userspace, it is the same between all systems.
  49
  50 Additionally, there is a custom keycode to toggle layer indication. And all RGB keycodes disable layer indication by default, as well.  This way, I can leave special effects doing when I want.
  51
  52 Also. I use `rgblight_sethsv` since it works with animation modes (that support it).
  53
  54 ## Diablo Layer
  55
  56 This layer has some special handling.
  57
  58 When Tap Dances are enabled, this layer has the ability to "spam" keypresses.
  59
  60 For instance, tapping the TD "1" twice causes the layer to hit "1" ever 1 second (appoximately).  This is useful for auto-hotkeying skills (such as bone armor or devour).
  61
  62 Tappind once disables this, and switching layers temporarily disables this, until you switch back to the layer.
  63
  64 For critics that think this is cheating, search "diablo 3 num lock auto cast".  This is just a simpler method, since I no longer own a normal (non QMK) numpad.
  65
  66 ## Secret Macros
  67
  68 With help from gitter and Colinta, this adds the ability to add hidden macros from other users.
  69
  70 First, I have several files that are hidden/excluded from Git/GitHub.  These contain everything needed for the macros. To hide these files, open `.git/info/exclude` and add `secrets.c` and  `secrets.h` to that file, below the comments.
  71
  72 And this requires `KC_SECRET_1` through `KC_SECRET_5` to be defined in your `<name>.h` file to define the keycodes for the new macros.
  73
  74
  75 ### .git/info/exclude
  76
  77 ```
  78 # git ls-files --others --exclude-from=.git/info/exclude
  79 # Lines that start with '#' are comments.
  80 # For a project mostly in C, the following would be a good set of
  81 # exclude patterns (uncomment them if you want to use them):
  82 # *.[oa]
  83 # *~
  84 /users/drashna/secrets.c
  85 /users/drashna/secrets.h
  86 ```
  87
  88 Then you can create these files:
  89
  90 ### secrets.c
  91
  92 ```c
  93 #include "drashna.h"  // replace with your keymap's "h" file, or whatever file stores the keycodes
  94
  95 #if (__has_include("secrets.h") && !defined(NO_SECRETS))
  96 #include "secrets.h"
  97 #else
  98 // `PROGMEM const char secret[][x]` may work better, but it takes up more space in the firmware
  99 // And I'm not familiar enough to know which is better or why...
 100 static const char * const secret[] = {
 101   "test1",
 102   "test2",
 103   "test3",
 104   "test4",
 105   "test5"
 106 };
 107 #endif
 108
 109 bool process_record_secrets(uint16_t keycode, keyrecord_t *record) {
 110   switch (keycode) {
 111     case KC_SECRET_1 ... KC_SECRET_5: // Secrets!  Externally defined strings, not stored in repo
 112       if (!record->event.pressed) {
 113         clear_oneshot_layer_state(ONESHOT_OTHER_KEY_PRESSED);
 114         send_string_with_delay(secret[keycode - KC_SECRET_1], MACRO_TIMER);
 115       }
 116       return false;
 117       break;
 118   }
 119   return true;
 120 }
 121 ```
 122
 123 ### secrets.h
 124
 125 ```c
 126 static const char * const secrets[] = {
 127   "secret1",
 128   "secret2",
 129   "secret3",
 130   "secret4",
 131   "secret5"
 132 };
 133 ```
 134
 135 Replacing the strings with the codes that you need.
 136
 137 ### name.c
 138
 139 In the `<name>.c` file, you will want to add this to the top:
 140
 141 ```c
 142 __attribute__ ((weak))
 143 bool process_record_secrets(uint16_t keycode, keyrecord_t *record) {
 144   return true;
 145 }
 146 ```
 147
 148 This is so that the function can be called here, and replaced in the `secrets.c` file, and so it won't error out if it doesn't exist.
 149
 150 And then, in the `process_record_user` function, assuming you have `return process_record_keymap(keycode, record)` here,  you'll want to replace the "final" return with the following. Otherwise, you want to replace the `return true;` with `return process_record_secrets(keycode, record);`
 151
 152 ```c
 153   return process_record_keymap(keycode, record) && process_record_secrets(keycode, record);
 154 }
 155 ```
 156
 157 ### rules.mk
 158
 159 Here, you want your `/users/<name>/rules.mk` file to "detect" the existence of the `secrets.c` file, and only add it if the file exists.  To do so, add this block:
 160
 161 ```make
 162 ifneq ("$(wildcard $(USER_PATH)/secrets.c)","")
 163   SRC += secrets.c
 164 endif
 165 ```
 166
 167 Additionally, if you want to make sure that you can disable the function without messing with the file, you need to add this to your `/users/<name>/rules.mk`, so that it catches the flag:
 168
 169 ```make
 170 ifeq ($(strip $(NO_SECRETS)), yes)
 171     OPT_DEFS += -DNO_SECRETS
 172 endif
 173 ```
 174
 175 Then, if you run `make keyboard:name NO_SECRETS=yes`, it will default to the test strings in your `<name>.c` file, rather than reading from your file.
 176
 177 ## Pro Micro Hacking
 178
 179 Well, you can get the QMK DFU bootloader working on the ProMicro. But you need to change fuses.
 180
 181 What worked to get into the firmware properly was:
 182
 183 ```
 184 Low: 0x5E High: 0xD9 Extended: 0xC3 Lock: 0x3F
 185 ```
 186
 187 The reason that there was some issues before, is that JTAG was still enabled, and using some of the pins that the keyboard uses.  Disabling JTAG (either by fuse, or modifying the matrix code for splits fixes the issue).
 188
 189 And for reference, if you want to go back to caterina, the default fuse settings I believe were:
 190
 191 ```
 192 Low: 0xFF High: 0xD8 Extended: 0xC3 Lock: 0x3F
 193 ```