1
0
Fork 0

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. 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. 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. 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. 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. 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. 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. 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. 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). Also. I use `rgblight_sethsv` since it works with animation modes (that support it).
## Diablo Layer
Diablo Layer
------------
This layer has some special handling. 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. 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. 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. 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 # git ls-files --others --exclude-from=.git/info/exclude
# Lines that start with '#' are comments. # 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: Then you can create these files:
###### secrets.c ### secrets.c
```c ```c
#include "drashna.h" // replace with your keymap's "h" file, or whatever file stores the keycodes #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 ```c
static const char * const secrets[] = { static const char * const secrets[] = {
"secret1", "secret1",
@ -142,7 +134,7 @@ static const char * const secrets[] = {
Replacing the strings with the codes that you need. 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: 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; 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. 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);` 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 ```c
return process_record_keymap(keycode, record) && process_record_secrets(keycode, record); 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: 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)","") ifneq ("$(wildcard $(USER_PATH)/secrets.c)","")
SRC += secrets.c SRC += secrets.c
endif 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: 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) ifeq ($(strip $(NO_SECRETS)), yes)
OPT_DEFS += -DNO_SECRETS OPT_DEFS += -DNO_SECRETS
endif 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. 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.
## Pro Micro Hacking
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
-----------------
Well, you can get the QMK DFU bootloader working on the ProMicro. But you need to change fuses. Well, you can get the QMK DFU bootloader working on the ProMicro. But you need to change fuses.