_/qmk_firmware
1
0
Fork 0
Code Releases Activity
qmk_firmware/docs/feature_backlight.md
Balz Guenat 4931510ad3 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
2018-01-01 17:47:51 -05:00

2.2 KiB
Raw Blame History

Backlighting

Backlight Keycodes

These keycodes control the backlight. Most keyboards use this for single color in-switch lighting.

Key Description
BL_TOGG Turn the backlight on or off
BL_STEP Cycle through backlight levels
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.