backlight.md (13685B)
1 # Backlighting {#backlighting} 2 3 Many keyboards support backlit keys by way of individual LEDs placed through or underneath the keyswitches. This feature is distinct from both the [RGB Underglow](rgblight) and [RGB Matrix](rgb_matrix) features as it usually allows for only a single colour per switch, though you can obviously install multiple different single coloured LEDs on a keyboard. 4 5 QMK is able to control the brightness of these LEDs by switching them on and off rapidly in a certain ratio, a technique known as *Pulse Width Modulation*, or PWM. By altering the duty cycle of the PWM signal, it creates the illusion of dimming. 6 7 ## Usage {#usage} 8 9 Most keyboards have backlighting enabled by default if they support it, but if it is not working for you (or you have added support), check that your `rules.mk` includes the following: 10 11 ```make 12 BACKLIGHT_ENABLE = yes 13 ``` 14 15 ## Keycodes {#keycodes} 16 17 |Key |Aliases |Description | 18 |-------------------------------|---------|-----------------------------------| 19 |`QK_BACKLIGHT_TOGGLE` |`BL_TOGG`|Turn the backlight on or off | 20 |`QK_BACKLIGHT_STEP` |`BL_STEP`|Cycle through backlight levels | 21 |`QK_BACKLIGHT_ON` |`BL_ON` |Set the backlight to max brightness| 22 |`QK_BACKLIGHT_OFF` |`BL_OFF` |Turn the backlight off | 23 |`QK_BACKLIGHT_UP` |`BL_UP` |Increase the backlight level | 24 |`QK_BACKLIGHT_DOWN` |`BL_DOWN`|Decrease the backlight level | 25 |`QK_BACKLIGHT_TOGGLE_BREATHING`|`BL_BRTG`|Toggle backlight breathing | 26 27 ## Basic Configuration {#basic-configuration} 28 29 Add the following to your `config.h`: 30 31 |Define |Default |Description | 32 |-----------------------------|------------------|-----------------------------------------------------------------------------------------------------------------| 33 |`BACKLIGHT_PIN` |*Not defined* |The pin that controls the LEDs | 34 |`BACKLIGHT_LEVELS` |`3` |The number of brightness levels (maximum 31 excluding off) | 35 |`BACKLIGHT_CAPS_LOCK` |*Not defined* |Enable Caps Lock indicator using backlight (for keyboards without dedicated LED) | 36 |`BACKLIGHT_BREATHING` |*Not defined* |Enable backlight breathing, if supported | 37 |`BREATHING_PERIOD` |`6` |The length of one backlight "breath" in seconds | 38 |`BACKLIGHT_ON_STATE` |`1` |The state of the backlight pin when the backlight is "on" - `1` for high, `0` for low | 39 |`BACKLIGHT_LIMIT_VAL` |`255` |The maximum duty cycle of the backlight -- `255` allows for full brightness, any lower will decrease the maximum.| 40 |`BACKLIGHT_DEFAULT_ON` |`true` |Enable backlight upon clearing the EEPROM | 41 |`BACKLIGHT_DEFAULT_BREATHING`|`false` |Whether to enable backlight breathing upon clearing the EEPROM | 42 |`BACKLIGHT_DEFAULT_LEVEL` |`BACKLIGHT_LEVELS`|The default backlight level to use upon clearing the EEPROM | 43 44 Unless you are designing your own keyboard, you generally should not need to change the `BACKLIGHT_PIN` or `BACKLIGHT_ON_STATE`. 45 46 ### "On" State {#on-state} 47 48 Most backlight circuits are driven by an N-channel MOSFET or NPN transistor. This means that to turn the transistor *on* and light the LEDs, you must drive the backlight pin, connected to the gate or base, *high*. 49 Sometimes, however, a P-channel MOSFET, or a PNP transistor is used. In this case, when the transistor is on, the pin is driven *low* instead. 50 51 To configure the "on" state of the backlight circuit, add the following to your `config.h`: 52 53 ```c 54 #define BACKLIGHT_ON_STATE 0 55 ``` 56 57 ### Multiple Backlight Pins {#multiple-backlight-pins} 58 59 Most keyboards have only one backlight pin which controls all backlight LEDs (especially if the backlight is connected to a hardware PWM pin). 60 The `timer` and `software` drivers allow you to define multiple backlight pins, which will be turned on and off at the same time during the PWM duty cycle. 61 62 This feature allows to set, for instance, the Caps Lock LED's (or any other controllable LED) brightness at the same level as the other LEDs of the backlight. This is useful if you have mapped Control in place of Caps Lock and you need the Caps Lock LED to be part of the backlight instead of being activated when Caps Lock is on, as it is usually wired to a separate pin from the backlight. 63 64 To configure multiple backlight pins, add something like this to your `config.h`, instead of `BACKLIGHT_PIN`: 65 66 ```c 67 #define BACKLIGHT_PINS { F5, B2 } 68 ``` 69 70 ## Driver Configuration {#driver-configuration} 71 72 Backlight driver selection is configured in `rules.mk`. Valid drivers are `pwm` (default), `timer`, `software`, or `custom`. See below for information on individual drivers. 73 74 ### PWM Driver {#pwm-driver} 75 76 This is the default backlight driver, which leverages the hardware PWM output capability of the microcontroller. 77 78 ```make 79 BACKLIGHT_DRIVER = pwm 80 ``` 81 82 ### Timer Driver {#timer-driver} 83 84 This driver is similar to the PWM driver, but instead of directly configuring the pin to output a PWM signal, an interrupt handler is attached to the timer to turn the pin on and off as appropriate. 85 86 ```make 87 BACKLIGHT_DRIVER = timer 88 ``` 89 90 ### Software Driver {#software-driver} 91 92 In this mode, PWM is "emulated" while running other keyboard tasks. It offers maximum hardware compatibility without extra platform configuration. However, breathing is not supported, and the backlight can flicker when the keyboard is busy. 93 94 ```make 95 BACKLIGHT_DRIVER = software 96 ``` 97 98 ### Custom Driver {#custom-driver} 99 100 If none of the above drivers apply to your board (for example, you are using a separate IC to control the backlight), you can implement a custom backlight driver using a simple API. 101 102 ```make 103 BACKLIGHT_DRIVER = custom 104 ``` 105 106 ```c 107 void backlight_init_ports(void) { 108 // Optional - runs on startup 109 // Usually you want to configure pins here 110 } 111 void backlight_set(uint8_t level) { 112 // Optional - runs on level change 113 // Usually you want to respond to the new value 114 } 115 116 void backlight_task(void) { 117 // Optional - runs periodically 118 // Note that this is called in the main keyboard loop, 119 // so long running actions here can cause performance issues 120 } 121 ``` 122 123 ## AVR Configuration {#avr-configuration} 124 125 ### PWM Driver {#avr-pwm-driver} 126 127 The following table describes the supported pins for the PWM driver. Only cells marked with a timer number are capable of hardware PWM output; any others must use the `timer` driver. 128 129 |Backlight Pin|AT90USB64/128|AT90USB162|ATmega16/32U4|ATmega16/32U2|ATmega32A|ATmega328/P| 130 |-------------|-------------|----------|-------------|-------------|---------|-----------| 131 |`B1` | | | | | |Timer 1 | 132 |`B2` | | | | | |Timer 1 | 133 |`B5` |Timer 1 | |Timer 1 | | | | 134 |`B6` |Timer 1 | |Timer 1 | | | | 135 |`B7` |Timer 1 |Timer 1 |Timer 1 |Timer 1 | | | 136 |`C4` |Timer 3 | | | | | | 137 |`C5` |Timer 3 |Timer 1 | |Timer 1 | | | 138 |`C6` |Timer 3 |Timer 1 |Timer 3 |Timer 1 | | | 139 |`D4` | | | | |Timer 1 | | 140 |`D5` | | | | |Timer 1 | | 141 142 ### Timer Driver {#avr-timer-driver} 143 144 Any GPIO pin can be used with this driver. The following table describes the supported timers: 145 146 |AT90USB64/128|AT90USB162|ATmega16/32U4|ATmega16/32U2|ATmega32A|ATmega328/P| 147 |-------------|----------|-------------|-------------|---------|-----------| 148 |Timers 1 & 3 |Timer 1 |Timers 1 & 3 |Timer 1 |Timer 1 |Timer 1 | 149 150 The following `#define`s apply only to the `timer` driver: 151 152 |Define |Default|Description | 153 |-----------------------|-------|----------------| 154 |`BACKLIGHT_PWM_TIMER` |`1` |The timer to use| 155 156 Note that the choice of timer may conflict with the [Audio](audio) feature. 157 158 ## ChibiOS/ARM Configuration {#arm-configuration} 159 160 ### PWM Driver {#arm-pwm-driver} 161 162 Depending on the ChibiOS board configuration, you may need to enable PWM at the keyboard level. For STM32, this would look like: 163 164 ::: code-group 165 ```c [halconf.h] 166 #pragma once 167 168 #define HAL_USE_PWM TRUE // [!code focus] 169 170 #include_next <halconf.h> 171 ``` 172 ```c [mcuconf.h] 173 #pragma once 174 175 #include_next <mcuconf.h> 176 177 #undef STM32_PWM_USE_TIM4 // [!code focus] 178 #define STM32_PWM_USE_TIM4 TRUE // [!code focus] 179 ``` 180 ::: 181 182 The following `#define`s apply only to the `pwm` driver: 183 184 |Define |Default |Description | 185 |-----------------------|-------------|---------------------------------------------------------------| 186 |`BACKLIGHT_PWM_DRIVER` |`PWMD4` |The PWM driver to use | 187 |`BACKLIGHT_PWM_CHANNEL`|`3` |The PWM channel to use | 188 |`BACKLIGHT_PAL_MODE` |`2` |The pin alternative function to use | 189 |`BACKLIGHT_PWM_PERIOD` |*Not defined*|The PWM period in counter ticks - Default is platform dependent| 190 191 192 Refer to the ST datasheet for your particular MCU to determine these values. For example, these defaults are set up for pin `B8` on a Proton-C (STM32F303) using `TIM4_CH3` on AF2. Unless you are designing your own keyboard, you generally should not need to change them. 193 194 ### Timer Driver {#arm-timer-driver} 195 196 Depending on the ChibiOS board configuration, you may need to enable general-purpose timers at the keyboard level. For STM32, this would look like: 197 198 ::: code-group 199 ```c [halconf.h] 200 #pragma once 201 202 #define HAL_USE_GPT TRUE // [!code focus] 203 204 #include_next <halconf.h> 205 ``` 206 ```c [mcuconf.h] 207 #pragma once 208 209 #include_next <mcuconf.h> 210 211 #undef STM32_GPT_USE_TIM15 // [!code focus] 212 #define STM32_GPT_USE_TIM15 TRUE // [!code focus] 213 ``` 214 ::: 215 216 The following `#define`s apply only to the `timer` driver: 217 218 |Define |Default |Description | 219 |----------------------|--------|----------------| 220 |`BACKLIGHT_GPT_DRIVER`|`GPTD15`|The timer to use| 221 222 ## Example Schematic 223 224 Since the MCU can only supply so much current to its GPIO pins, instead of powering the backlight directly from the MCU, the backlight pin is connected to a transistor or MOSFET that switches the power to the LEDs. 225 226 In this typical example, the backlight LEDs are all connected in parallel towards an N-channel MOSFET. Its gate pin is wired to one of the microcontroller's GPIO pins through a 470Ω resistor to avoid ringing. 227 A pulldown resistor is also placed between the gate pin and ground to keep it at a defined state when it is not otherwise being driven by the MCU. 228 The values of these resistors are not critical - see [this Electronics StackExchange question](https://electronics.stackexchange.com/q/68748) for more information. 229 230  231 232 ## API {#api} 233 234 ### `void backlight_toggle(void)` {#api-backlight-toggle} 235 236 Toggle the backlight on or off. 237 238 --- 239 240 ### `void backlight_enable(void)` {#api-backlight-enable} 241 242 Turn the backlight on. 243 244 --- 245 246 ### `void backlight_disable(void)` {#api-backlight-disable} 247 248 Turn the backlight off. 249 250 --- 251 252 ### `void backlight_step(void)` {#api-backlight-step} 253 254 Cycle through backlight levels. 255 256 --- 257 258 ### `void backlight_increase(void)` {#api-backlight-increase} 259 260 Increase the backlight level. 261 262 --- 263 264 ### `void backlight_decrease(void)` {#api-backlight-decrease} 265 266 Decrease the backlight level. 267 268 --- 269 270 ### `void backlight_level(uint8_t level)` {#api-backlight-level} 271 272 Set the backlight level. 273 274 #### Arguments {#api-backlight-level-arguments} 275 276 - `uint8_t level` 277 The level to set, from 0 to `BACKLIGHT_LEVELS`. 278 279 --- 280 281 ### `uint8_t get_backlight_level(void)` {#api-get-backlight-level} 282 283 Get the current backlight level. 284 285 #### Return Value {#api-get-backlight-level-return} 286 287 The current backlight level, from 0 to `BACKLIGHT_LEVELS`. 288 289 --- 290 291 ### `bool is_backlight_enabled(void)` {#api-is-backlight-enabled} 292 293 Get the current backlight state. 294 295 #### Return Value {#api-is-backlight-enabled-return} 296 297 `true` if the backlight is enabled. 298 299 --- 300 301 ### `void backlight_toggle_breathing(void)` {#api-backlight-toggle-breathing} 302 303 Toggle backlight breathing on or off. 304 305 --- 306 307 ### `void backlight_enable_breathing(void)` {#api-backlight-enable-breathing} 308 309 Turn backlight breathing on. 310 311 --- 312 313 ### `void backlight_disable_breathing(void)` {#api-backlight-disable-breathing} 314 315 Turn backlight breathing off. 316 317 --- 318 319 ### `bool is_backlight_breathing(void)` {#api-is-backlight-breathing} 320 321 Get the current backlight breathing state. 322 323 #### Return Value {#api-is-backlight-breathing-return} 324 325 `true` if backlight breathing is enabled.