Welcome to the Backlight fading API page.
This page aims to describe numerous approaches to achieve backlight fading.
Work in progress
The backlight thread
All backlight (and buttonlight) operation is done in the backlight thread apart from the rest of the code. The backlight thread accesses (initiates fading in and off) backlight fading by calling
Both set the prerequisites for the fading process. The fading process depends on the actual implementation.
The settings can access the fading and change its behaviour by calling
There is no replacement for
These want to be called no matter of the fading. This is not true for PWM fading.
PWM backlight fading
I, myself, can't tell very much about PWM fading (aka FIXME).
Changing brightness via PWM involves
- a) setting up support for the timer interrupt
- b) accessing the backlight critical variables in an interrupt handler
- c) very low hardware latency in changing brightness (less that a tick)
- d) enough timer hardware to have a timer dedicated to PWM fading (it needs a timer interrupt driven implementation as of now). [Is this true?]
For PWM (interrupt) backlight fading, there's currently one define:
Software driven backlight fading
Currently software driven backlight fading is solely implemented by changing the brightness in a given interval based on the total available brightness levels.
Software brightness has two advantages:
- a) it doesn't need a dedicated timer interrupt
- b) it works even with sort of slower backlight hardware
- c) easy to implement
With the disadvantage of:
- being dependant on the currently selected brightness settings (lowest backlight setting means no fading).
- It linearly traverses through the available brightness levels, although the resulting brightness may not be linear.
There's 2 subimplementations, which are mainly caused by the subtle difference in hardware handling in brightness levels. There's a kind of controllers, that set the brightness to the lowest possible level upon backlight_off, while the other kind sets the backlight to off by setting the backlight brightness level to zero.
Therefore there's two defines:
- BACKLIGHT_FADING_SW_HW_REG and
The available options are limited to ON and OFF.
Using timer options are generally possible, but are likely to be problematic with high latency backlight changing hardware and/or being choppy while fading due to a rather high timer.
Handling backlight fading target specific
There is a third way of implementing: Handling the fading only
This means that all fading is handled in the very target specific "_backlight_on/_off(void)" function. Fading must be finished until _backlight_off/_on() returns to prevent confusion of the backlight thread (it will treat this backlight fading type the same way as no fading). No software controlled or interrupt driven backlight brightness changing is involved.
The configurability depends on the target, but currently only ON and OFF are used.
The corresponding define is
Copyright © by the contributing authors.