users/drashna/readme.md

   1 Overview
   2 ========
   3
   4 This is my personal userspace file.  Most of my code exists here, as it's heavily shared.
   5
   6
   7 Custom userspace handlers
   8 -------------------------
   9
  10 Specifically QMK works by using customized handlers for everything. This allows for multiple levels of customization.
  11
  12 `matrix_scan` calls `matrix_scan_quantum`, which alls `matrix_scan_kb`, which calls `matrix_scan_user`.
  13 `process_record` calls a bunch of stuff, but eventually calls `process_record_kb` which calls `process_record_user`
  14 The same goes for `matrix_init`, `layer_state_set`, `led_set`, and a few other functions.
  15
  16 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.
  17
  18 This allows for keyboard specific configuration while maintaining the ability to customize the board.
  19
  20 My [Ergodox EZ Keymap](https://github.com/qmk/qmk_firmware/blob/master/keyboards/ergodox_ez/keymaps/drashna/keymap.c#L399) is a good example of this, as it uses the LEDs as modifier indicators.
  21
  22
  23 Keyboard Layout Templates
  24 -------------------------
  25
  26 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.
  27
  28 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.
  29
  30 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:
  31
  32 `#define LAYOUT_ergodox_wrapper(...)   LAYOUT_ergodox(__VA_ARGS__)`
  33
  34 Once that's been done and you've switched the keymaps to use the "wrapper", it will read the substitution blocks just fine.
  35
  36 Credit goes to @jola5 for first implementing this awesome idea.
  37
  38
  39 Custom Keycodes
  40 ---------------
  41
  42 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.
  43
  44 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.
  45
  46 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).
  47
  48 This also includes a modified RESET keycode as well, that sets the underglow to red.
  49
  50 Layer Indication
  51 ----------------
  52
  53 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.
  54
  55 Since this is done via userspace, it is the same between all systems.
  56
  57 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.
  58
  59 Also. I use `rgblight_sethsv` since it works with animation modes (that support it).
  60
  61
  62 Diablo Layer
  63 ------------
  64
  65 This layer has some special handling.
  66
  67 When Tap Dances are enabled, this layer has the ability to "spam" keypresses.
  68
  69 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).
  70
  71 Tappind once disables this, and switching layers temporarily disables this, until you switch back to the layer.
  72
  73 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.
  74
  75 Secret Macros
  76 -------------
  77
  78 With help from gitter and Colinta, this adds the ability to add hidden strings to be used for macros.
  79
  80 I have a number of long strings that I need to use that are semi-private.  This uses the `__has_include` function to check for the file. If it exists, then it includes the custom text. Otherwise, it uses some default values.
  81
  82 If you would *also* like to take advantage of this feature, you'll first want to make sure your "secrets" file isn't included in the repo.  Open `.git/info/exclude` and add `secrets.h` to that file, below the comments.
  83
  84 ###### .git/info/exclude
  85 ```
  86 # git ls-files --others --exclude-from=.git/info/exclude
  87 # Lines that start with '#' are comments.
  88 # For a project mostly in C, the following would be a good set of
  89 # exclude patterns (uncomment them if you want to use them):
  90 # *.[oa]
  91 # *~
  92 /users/drashna/secrets.h
  93 ```
  94
  95 Then you can create this file and add your macro strings to it:
  96
  97 ###### secrets.h
  98 ```c
  99 static const char * const secrets[] = {
 100   "secret1",
 101   "secret2",
 102   "secret3",
 103   "secret4",
 104   "secret5"
 105 };
 106 ```
 107
 108 Replacing the strings with the codes that you need.
 109
 110 In the `<name>.c` file, you will want to add this to the top:
 111
 112 ```c
 113
 114 #if (__has_include("secrets.h") && !defined(NO_SECRETS))
 115 #include "secrets.h"
 116 #else
 117 // `PROGMEM const char secret[][x]` may work better, but it takes up more space in the firmware
 118 // And I'm not familiar enough to know which is better or why...
 119 static const char * const secrets[] = {
 120   "test1",
 121   "test2",
 122   "test3",
 123   "test4",
 124   "test5"
 125 };
 126 #endif
 127 ```
 128
 129 And then, in the `process_record_user` function, you'll want to add this block:
 130 ```c
 131   case KC_SECRET_1 ... KC_SECRET_5:
 132     if (!record->event.pressed) {
 133       send_string_P(secret[keycode - KC_SECRET_1]);
 134     }
 135     return false;
 136     break;
 137 ```
 138
 139 And this requires `KC_SECRET_1` through `KC_SECRET_5` to be defined in your `<name>.h` file fo the new macros, as well.
 140
 141 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:
 142 ```c
 143 ifeq ($(strip $(NO_SECRETS)), yes)
 144     OPT_DEFS += -DNO_SECRETS
 145 endif
 146 ```
 147
 148 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.
 149
 150
 151 Userspace EEPROM config
 152 -----------------------
 153
 154 This adds EEPROM support fo the userspace, so that certain values are configurable in such a way that persists when power is lost.  Namely, just the clicky feature and the Overwatch macro option ("is_overwatch").  This is done by reading and saving the structure from EEPROM.
 155
 156 To implement this, first you need to specify the location:
 157
 158 ```c
 159 #define EECONFIG_USERSPACE (uint8_t *)20
 160 ```
 161 This tells us where in the EEPROM that the data structure is located, and this specifies that it's a byte (8 bits).  However, to maximize it's usage, we want to specify a data structure here, so that we can use multiple settings.  To do that:
 162
 163 ```c
 164 typedef union {
 165   uint8_t raw;
 166   struct {
 167     bool     clicky_enable  :1;
 168     bool     is_overwatch   :1;
 169   };
 170 } userspace_config_t;
 171 ```
 172 Then, in your C file, you want to add: `userspace_config_t userspace_config;`, and in your `matrix_init_*` function, you want to add `userspace_config.raw = eeprom_read_byte(EECONFIG_USERSPACE);`
 173
 174 From there, you'd want to use the data structure (such as `userspace_config.is_overwatch`) when you want to check this value.
 175
 176 And if you want to update it, update directly and then use `eeprom_update_byte(EECONFIG_USERSPACE, userspace_config.raw);` to write the value back to the EEPROM.
 177
 178
 179 Pro Micro Hacking
 180 -----------------
 181
 182 Well, you can get the QMK DFU bootloader working on the ProMicro. But you need to change fuses.
 183
 184 What worked to get into the firmware properly was:
 185
 186 ```
 187 Low: 0x5E High: 0x99 Extended: 0xF3 Lock: 0xFF
 188 ```
 189
 190 But some of the columns and rows didn't work, like the pin mapping was wrong. Even when setting the bootloader settings.
 191
 192  This is here for future reference.  And the default fuse settings I believe were:
 193
 194 ```
 195 Low: 0xFF High: 0xD8 Extended: 0xC3 Lock: 0x3F
 196 ```