jlj-qmk/docs/feature_backlight.md

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 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.