4 files changed, 32 insertions, 5 deletions

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 <code>&#96;</code> 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' %}