Merge pull request #7276 from zvecr/feature/backlight_driver_config

Convert backlight to follow driver rules pattern
This commit is contained in:
Joel Challis 2019-12-16 16:39:54 +00:00 committed by GitHub
commit adb72b60b0
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 52 additions and 19 deletions

View File

@ -231,15 +231,16 @@ endif
# backward compat
ifeq ($(strip $(BACKLIGHT_CUSTOM_DRIVER)), yes)
BACKLIGHT_ENABLE = custom
BACKLIGHT_DRIVER = custom
endif
VALID_BACKLIGHT_TYPES := yes software custom
VALID_BACKLIGHT_TYPES := pwm software custom
BACKLIGHT_ENABLE ?= no
ifneq ($(strip $(BACKLIGHT_ENABLE)), no)
ifeq ($(filter $(BACKLIGHT_ENABLE),$(VALID_BACKLIGHT_TYPES)),)
$(error BACKLIGHT_ENABLE="$(BACKLIGHT_ENABLE)" is not a valid backlight type)
BACKLIGHT_DRIVER ?= pwm
ifeq ($(strip $(BACKLIGHT_ENABLE)), yes)
ifeq ($(filter $(BACKLIGHT_DRIVER),$(VALID_BACKLIGHT_TYPES)),)
$(error BACKLIGHT_DRIVER="$(BACKLIGHT_DRIVER)" is not a valid backlight type)
endif
ifeq ($(strip $(VISUALIZER_ENABLE)), yes)
@ -250,10 +251,10 @@ ifneq ($(strip $(BACKLIGHT_ENABLE)), no)
SRC += $(QUANTUM_DIR)/backlight/backlight.c
OPT_DEFS += -DBACKLIGHT_ENABLE
ifeq ($(strip $(BACKLIGHT_ENABLE)), software)
ifeq ($(strip $(BACKLIGHT_DRIVER)), software)
SRC += $(QUANTUM_DIR)/backlight/backlight_soft.c
else
ifeq ($(strip $(BACKLIGHT_ENABLE)), custom)
ifeq ($(strip $(BACKLIGHT_DRIVER)), custom)
OPT_DEFS += -DBACKLIGHT_CUSTOM_DRIVER
endif

View File

@ -6,16 +6,14 @@ QMK is able to control the brightness of these LEDs by switching them on and off
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.
## Driver configuration
## Feature Configuration
Most keyboards have backlighting enabled by default if they support it, but if it is not working for you, check that your `rules.mk` includes the following:
```makefile
BACKLIGHT_ENABLE = software # Valid driver values are 'yes,software,no'
BACKLIGHT_ENABLE = yes
```
See below for help on individual drivers.
## Keycodes
Once enabled the following keycodes below can be used to change the backlight level.
@ -51,6 +49,16 @@ Once enabled the following keycodes below can be used to change the backlight le
|`breathing_enable()` |Turns on backlight breathing |
|`breathing_disable()` |Turns off backlight breathing |
## Driver Configuration
To select which driver to use, configure your `rules.mk` with the following:
```makefile
BACKLIGHT_DRIVER = software # Valid driver values are 'pwm,software,no'
```
See below for help on individual drivers.
## Common Driver Configuration
To change the behavior of the backlighting, `#define` these in your `config.h`:
@ -72,9 +80,9 @@ This functionality is configured at the keyboard level with the `BACKLIGHT_ON_ST
## AVR driver
On AVR boards, the default driver currently sniffs the configuration to pick the best scenario. To enable it, add this to your rules.mk:
On AVR boards, the default driver currently sniffs the configuration to pick the best scenario. The driver is configured by default, however the equivalent setting within rules.mk would be:
```makefile
BACKLIGHT_ENABLE = yes
BACKLIGHT_DRIVER = pwm
```
### Caveats
@ -150,9 +158,9 @@ The breathing effect is the same as in the hardware PWM implementation.
## ARM Driver
While still in its early stages, ARM backlight support aims to eventually have feature parity with AVR. To enable it, add this to your rules.mk:
While still in its early stages, ARM backlight support aims to eventually have feature parity with AVR. The driver is configured by default, however the equivalent setting within rules.mk would be:
```makefile
BACKLIGHT_ENABLE = yes
BACKLIGHT_DRIVER = pwm
```
### Caveats
@ -176,7 +184,7 @@ To change the behavior of the backlighting, `#define` these in your `config.h`:
Emulation of PWM while running other keyboard tasks, it offers maximum hardware compatibility without extra platform configuration. The tradeoff is the backlight might jitter when the keyboard is busy. To enable, add this to your rules.mk:
```makefile
BACKLIGHT_ENABLE = software
BACKLIGHT_DRIVER = software
```
### Software PWM Configuration
@ -200,3 +208,29 @@ To activate multiple backlight pins, you need to add something like this to your
#undef BACKLIGHT_PIN
#define BACKLIGHT_PINS { F5, B2 }
```
## Custom Driver
To enable, add this to your rules.mk:
```makefile
BACKLIGHT_DRIVER = custom
```
When implementing the custom driver API, the provided keyboard hooks are as follows:
```c
void backlight_init_ports(void) {
// Optional - Run on startup
// - usually you want to configure pins here
}
void backlight_set(uint8_t level) {
// Optional - Run on level change
// - usually you want to respond to the new value
}
void backlight_task(void) {
// Optional - Run periodically
// - long running actions here can cause performance issues
}
```

View File

@ -5,9 +5,7 @@ AUDIO_ENABLE = yes
WS2812_DRIVER = bitbang
# Force task driven PWM until ARM can provide automatic configuration
ifneq ($(strip $(BACKLIGHT_ENABLE)), no)
BACKLIGHT_ENABLE = software
endif
BACKLIGHT_DRIVER = software
# The rest of these settings shouldn't change