Remove obsolete info.json entries (#2712)

[qmk_firmware.git] / docs / feature_backlight.md

diff --git a/docs/feature_backlight.md b/docs/feature_backlight.md
index c419b7cccb96b2998c607cd2ca86b2bd0c4651ae..5336e85266e2e0fe341bf3112d0c77f580d10238 100644 (file)
--- a/docs/feature_backlight.md
+++ b/docs/feature_backlight.md
@@ -6,12 +6,34 @@
 
 These keycodes control the backlight. Most keyboards use this for single color in-switch lighting.
 
-|Name|Description|
-|----|-----------|
-|`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_DEC`|Turn the backlight level down by 1|
-|`BL_INC`|Turn the backlight level up by 1|
-|`BL_TOGG`|Toggle the backlight on or off|
-|`BL_STEP`|Step through backlight levels, wrapping around to 0 when you reach the top.|
+|Key      |Description                               |
+|---------|------------------------------------------|
+|`BL_TOGG`|Turn the backlight on or off              |
+|`BL_STEP`|Cycle through backlight levels            |
+|`BL_ON`  |Set the backlight to max brightness       |
+|`BL_OFF` |Turn the backlight off                    |
+|`BL_INC` |Increase the backlight level              |
+|`BL_DEC` |Decrease the 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 (maximum 15 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.