From eb19fb5b57487747d608fad986a70296da4deb12 Mon Sep 17 00:00:00 2001 From: Drashna Jaelre Date: Sat, 25 Aug 2018 20:01:09 -0700 Subject: Helpful functions --- docs/_sidebar.md | 1 + docs/_summary.md | 1 + docs/feature_backlight.md | 19 +++++++++++++++++++ docs/ref_functions.md | 48 +++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 69 insertions(+) create mode 100644 docs/ref_functions.md (limited to 'docs') diff --git a/docs/_sidebar.md b/docs/_sidebar.md index d439298dad..a35014dd8c 100644 --- a/docs/_sidebar.md +++ b/docs/_sidebar.md @@ -36,6 +36,7 @@ * [Documentation Templates](documentation_templates.md) * [Glossary](reference_glossary.md) * [Unit Testing](unit_testing.md) + * [Useful Functions](ref_functions.md) * [Features](features.md) * [Basic Keycodes](keycodes_basic.md) diff --git a/docs/_summary.md b/docs/_summary.md index d439298dad..a35014dd8c 100644 --- a/docs/_summary.md +++ b/docs/_summary.md @@ -36,6 +36,7 @@ * [Documentation Templates](documentation_templates.md) * [Glossary](reference_glossary.md) * [Unit Testing](unit_testing.md) + * [Useful Functions](ref_functions.md) * [Features](features.md) * [Basic Keycodes](keycodes_basic.md) diff --git a/docs/feature_backlight.md b/docs/feature_backlight.md index 6140e6a0ab..8f883e08fb 100644 --- a/docs/feature_backlight.md +++ b/docs/feature_backlight.md @@ -51,3 +51,22 @@ In this way `OCRxx` essentially controls the duty cycle of the LEDs, and thus th The breathing effect is achieved by registering an interrupt handler for `TIMER1_OVF_vect` that is called whenever the counter resets, roughly 244 times per second. In this handler, the value of an incrementing counter is mapped onto a precomputed brightness curve. To turn off breathing, the interrupt handler is simply disabled, and the brightness reset to the level stored in EEPROM. + +## Backlight Functions + +|Function |Description | +|----------|----------------------------------------------------------| +|`backlight_toggle()` |Turn the backlight on or off | +|`backlight_step()` |Cycle through backlight levels | +|`backlight_increase()` |Increase the backlight level | +|`backlight_decrease()` |Decrease the backlight level | +|`backlight_level(x)` |Sets the backlight level to specified level | +|`get_backlight_level()`|Toggle backlight breathing | + +### Backlight Breathing Functions + +|Function |Description | +|----------|----------------------------------------------------------| +|`breathing_toggle()` |Turn the backlight breathing on or off | +|`breathing_enable()` |Turns on backlight breathing | +|`breathing_disable()` |Turns off backlight breathing | diff --git a/docs/ref_functions.md b/docs/ref_functions.md new file mode 100644 index 0000000000..7d0cda3227 --- /dev/null +++ b/docs/ref_functions.md @@ -0,0 +1,48 @@ +# List of Useful Core Functions To Make Your Keyboard Better + +There are a lot of hidden functions in QMK that are incredible useful, or may add a bit of functionality that you've been wanting. Functions that are specific to certain features are not included here, as those will be on their respective feature page. + +## (OLKB) Tri Layers + +There are actually separate functions that you can use there, depending on what you're after. + +The first is the `update_tri_layer(x, y, z)` function. This function check to see if layers `x` and `y` are both on. If they are both on, then it runs on layer `z`. Otherwise, if both `x` and `y` are not both on (either only one is, or neither is), then it runs off layer `z`. + +This function is useful if you want to create specific keys that have this functionality, but other layer keycodes won't do this. + +The other function is `update_tri_layer_state(state, x, y, z)`. This function is meant to be called from they [`layer_state_set_*` functions](custom_quantum_functions.md#layer-change-code). This means that any time that you use a keycode to change the layer, this will be checked. So you could use `LT(layer, kc)` to change the layer and it will trigger the same layer check. + +The caveat to this method is that you cannot access the `z` layer without having `x` and `y` layers on, since if you try to activate just layer `z`, it will run this code and turn off layer `z` before you could use it. + +## Setting the Persistent Default Layer + +Do you want to set the default layer, so that it's retained even after you unplug the board? If so, this is the function for you. + +To use this, you would use `set_single_persistent_default_layer(layer)`. If you have a name defined for your layer, you can use that instead (such as _QWERTY, _DVORAK or _COLEMAK). + +This will set the default layer, update the persistent settings, and play a tune if you have [Audio](feature_audio.md) enabled on your board, and the default layer sounds set. + +To configure the default layer sounds, you would want to define this in your `config.h` file, like this: + +```c +#define DEFAULT_LAYER_SONGS { SONG(QWERTY_SOUND), \ + SONG(COLEMAK_SOUND), \ + SONG(DVORAK_SOUND) \ + } +``` + + +?> There are a large number of predefined songs in [quantum/audio/song_list.h](https://github.com/qmk/qmk_firmware/blob/master/quantum/audio/song_list.h) that you can use. + +## Reseting the keyboard + +There is the `RESET` quantum keycode that you can use. But if you want to reset the board as part of a macro, rather than hitting a key separately, you can do that. + +And to do so, add `reset_keyboard()` to your function or macro, and this will reset to bootloader. + +## Wiping the EEPROM (Persistent Storage) + +If you're having issues with Audio, RGB Underglow, backlighting or keys acting weird, then you can reset the EEPROM (persistent setting storage). Bootmagic is one way to do this, but if that isn't enabled, then you can use a custom macro to do so. + +To wipe the EEPROM, run `eeconfig_init()` from your function or macro to reset most of the settings to default. + -- cgit v1.2.3