Update readme for userspace

This commit is contained in:
Drashna Jaelre 2018-10-16 08:22:37 -07:00 committed by MechMerlin
parent 3d15038dd4
commit 2776b9ee90

View File

@ -1,11 +1,8 @@
Overview
========
# Overview
This is my personal userspace file. Most of my code exists here, as it's heavily shared.
Custom userspace handlers
-------------------------
## Custom userspace handlers
Specifically QMK works by using customized handlers for everything. This allows for multiple levels of customization.
@ -17,11 +14,9 @@ All (most) `_user` functions are handled here instead. To allow keyboard specif
This allows for keyboard specific configuration while maintaining the ability to customize the board.
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.
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.
Keyboard Layout Templates
-------------------------
## Keyboard Layout Templates
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.
@ -36,8 +31,7 @@ Once that's been done and you've switched the keymaps to use the "wrapper", it w
Credit goes to @jola5 for first implementing this awesome idea.
Custom Keycodes
---------------
## Custom Keycodes
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.
@ -47,8 +41,7 @@ Included is a custom macro for compiling my keyboards. This includes the bootlo
This also includes a modified RESET keycode as well, that sets the underglow to red.
Layer Indication
----------------
## Layer Indication
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.
@ -58,9 +51,7 @@ Additionally, there is a custom keycode to toggle layer indication. And all RGB
Also. I use `rgblight_sethsv` since it works with animation modes (that support it).
Diablo Layer
------------
## Diablo Layer
This layer has some special handling.
@ -72,8 +63,7 @@ Tappind once disables this, and switching layers temporarily disables this, unti
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.
Secret Macros
-------------
## Secret Macros
With help from gitter and Colinta, this adds the ability to add hidden macros from other users.
@ -82,7 +72,8 @@ First, I have several files that are hidden/excluded from Git/GitHub. These con
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.
###### .git/info/exclude
### .git/info/exclude
```
# git ls-files --others --exclude-from=.git/info/exclude
# Lines that start with '#' are comments.
@ -96,7 +87,7 @@ And this requires `KC_SECRET_1` through `KC_SECRET_5` to be defined in your `<na
Then you can create these files:
###### secrets.c
### secrets.c
```c
#include "drashna.h" // replace with your keymap's "h" file, or whatever file stores the keycodes
@ -129,7 +120,8 @@ bool process_record_secrets(uint16_t keycode, keyrecord_t *record) {
}
```
###### secrets.h
### secrets.h
```c
static const char * const secrets[] = {
"secret1",
@ -142,7 +134,7 @@ static const char * const secrets[] = {
Replacing the strings with the codes that you need.
###### name.c
### name.c
In the `<name>.c` file, you will want to add this to the top:
@ -152,26 +144,29 @@ bool process_record_secrets(uint16_t keycode, keyrecord_t *record) {
return true;
}
```
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.
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);`
```c
return process_record_keymap(keycode, record) && process_record_secrets(keycode, record);
}
```
###### rules.mk
### rules.mk
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:
```c
```make
ifneq ("$(wildcard $(USER_PATH)/secrets.c)","")
SRC += secrets.c
endif
```
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:
```c
```make
ifeq ($(strip $(NO_SECRETS)), yes)
OPT_DEFS += -DNO_SECRETS
endif
@ -179,37 +174,7 @@ endif
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.
Userspace EEPROM config
-----------------------
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.
To implement this, first you need to specify the location:
```c
#define EECONFIG_USERSPACE (uint8_t *)20
```
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:
```c
typedef union {
uint8_t raw;
struct {
bool clicky_enable :1;
bool is_overwatch :1;
};
} userspace_config_t;
```
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);`
From there, you'd want to use the data structure (such as `userspace_config.is_overwatch`) when you want to check this value.
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.
Pro Micro Hacking
-----------------
## Pro Micro Hacking
Well, you can get the QMK DFU bootloader working on the ProMicro. But you need to change fuses.