From 4931510ad38aadb1769c9241bfad0c3d77ad687f Mon Sep 17 00:00:00 2001 From: Balz Guenat Date: Mon, 1 Jan 2018 23:47:51 +0100 Subject: backlight breathing overhaul (#2187) * add breathing to bananasplit * backlight breathing overhaul * fix the backlight_tick thing. * fix for vision_division backlight * fix a few keymaps and probably break breathing for some weirdly set-up boards. * remove BL_x keycodes because they made unreasonable assumptions * some fixes for BL keycodes * integer cie lightness scaling * use cie lightness for non-breathing backlight and make breathing able to reach true max brightness --- docs/config_options.md | 4 ++++ docs/faq_keymap.md | 2 +- docs/feature_backlight.md | 28 +++++++++++++++++++++++++--- docs/hardware_avr.md | 3 ++- 4 files changed, 32 insertions(+), 5 deletions(-) (limited to 'docs') diff --git a/docs/config_options.md b/docs/config_options.md index a9ff54995..1dd4cdbaa 100644 --- a/docs/config_options.md +++ b/docs/config_options.md @@ -70,6 +70,10 @@ This is a C header file that is one of the first things included, and will persi * pin of the backlight - B5, B6, B7 use PWM, others use softPWM * `#define BACKLIGHT_LEVELS 3` * number of levels your backlight will have (not including off) +* `#define BACKLIGHT_BREATHING` + * enables backlight breathing (only works with backlight pins B5, B6 and B7) +* `#define BREATHING_PERIOD 6` + * the length of one backlight "breath" in seconds * `#define DEBOUNCING_DELAY 5` * the delay when reading the value of the pin (5 is default) * `#define LOCKING_SUPPORT_ENABLE` diff --git a/docs/faq_keymap.md b/docs/faq_keymap.md index 7093dec20..0fed0445f 100644 --- a/docs/faq_keymap.md +++ b/docs/faq_keymap.md @@ -127,7 +127,7 @@ https://github.com/tekezo/Karabiner/issues/403 ## Esc and ` on a Single Key -See the [Grave Escape](feature_grave_escape.md) feature. +See the [Grave Escape](feature_grave_esc.md) feature. ## Arrow on Right Modifier Keys with Dual-Role This turns right modifier keys into arrow keys when the keys are tapped while still modifiers when the keys are hold. In TMK the dual-role function is dubbed **TAP**. diff --git a/docs/feature_backlight.md b/docs/feature_backlight.md index aa747f90e..97421c043 100644 --- a/docs/feature_backlight.md +++ b/docs/feature_backlight.md @@ -10,8 +10,30 @@ These keycodes control the backlight. Most keyboards use this for single color i |---------|------------------------------------------| |`BL_TOGG`|Turn the backlight on or off | |`BL_STEP`|Cycle through backlight levels | -|`BL_x` |Set a specific backlight level between 0-9| -|`BL_ON` |An alias for `BL_9` | -|`BL_OFF` |An alias for `BL_0` | +|`BL_ON` |Set backlight to max brightness | +|`BL_OFF` |Turn backlight off | |`BL_INC` |Increase backlight level | |`BL_DEC` |Decrease backlight level | +|`BL_BRTG`|Toggle backlight breathing | + +Note that for backlight breathing, you need to have `#define BACKLIGHT_BREATHING` in your config.h. + +## Configuration Options in `config.h` + +* `BACKLIGHT_PIN B7` defines the pin that controlls the LEDs. Unless you design your own keyboard, you don't need to set this. +* `BACKLIGHT_LEVELS 3` defines the number of brightness levels (excluding OFF). +* `BACKLIGHT_BREATHING` if defined, enables backlight breathing. Note that this is only available if `BACKLIGHT_PIN` is B5, B6 or B7. +* `BREATHING_PERIOD 6` defines the length of one backlight "breath" in seconds. + +## Notes on Implementation + +To change the brightness when using pins B5, B6 or B7, the PWM (Pulse Width Modulation) functionality of the on-chip timer is used. +The timer is a counter that counts up to a certain TOP value (`0xFFFF` set in ICR1) before resetting to 0. +We also set an OCR1x register. +When the counter reaches the value stored in that register, the PWM pin drops to low. +The PWM pin is pulled high again when the counter resets to 0. +Therefore, OCR1x basically sets the duty cycle of the LEDs and as such the brightness where `0` is the darkest and `0xFFFF` the brightest setting. + +To enable the breathing effect, we register an interrupt handler to be called whenever the counter resets (with `ISR(TIMER1_OVF_vect)`). +In this handler, which gets called roughly 244 times per second, we compute the desired brightness using a precomputed brightness curve. +To disable breathing, we can just disable the respective interrupt vector and reset the brightness to the desired level. diff --git a/docs/hardware_avr.md b/docs/hardware_avr.md index c6f3881dc..770817045 100644 --- a/docs/hardware_avr.md +++ b/docs/hardware_avr.md @@ -101,8 +101,9 @@ By default QMK supports backlighting on pins `B5`, `B6`, and `B7`. If you are us ``` #define BACKLIGHT_PIN B7 -#define BACKLIGHT_BREATHING #define BACKLIGHT_LEVELS 3 +#define BACKLIGHT_BREATHING +#define BREATHING_PERIOD 6 ``` {% hint style='info' %} -- cgit v1.2.3-24-g4f1b