Search by Tags

Backlight (Linux)


Compare with Revision

Subscribe for this article updates

Backlight Control Signals

On the Apalis Standard two dedicated pins are used for backlight control, BKL1_ON and BKL1_PWM. Note that Apalis iMX6 and Apalis T30 use the same PWM instance on the pins PWM4 and BKL1_PWM, hence PWM4 can not be used independently when BKL1_PWM is in use.

On our Colibri carrier boards BL_ON together with PWM<A> are used for adjusting LCD brightness. On the Colibri Evaluation Board and Iris Carrier Board the BL_ON signal also controls the VGA DAC operation.

Some displays have their maximum brightness if the PWM signal is constant at 3.3V while other displays are inverted and have their maximum brightness when the PWM signal is at 0V. The PWM signal logic of the displays sold by Toradex is documented in the table under PWM Logic.

The Linux kernel exposes backlights throught a sysfs ABI called backlight (located under /sys/class/backlight/, see also the kernel documentation located in the source tree under Documentation/ABI/stable/sysfs-class-backlight). The Linux BSP of all modules make use of the backlight API, however there are subtle differences mostly arising from the different kernel version used.

Apalis/Colibri T20/T30

The backlight driver controls both BL_ON/BKL1_ON and the PWM and targets a display which is brightest at 0% aka inverted. However apart from the behaviour at the extremes it works just fine with a display which is brightest at 100% aka not inverted as well.

The sysfs files can be found in the following directory: /sys/class/backlight/pwm-backlight/

The brightness and bl_power files control the duty cycle and BL_ON/BKL1_ON as follows:

bl_power brightness duty cycle BL_ON/BKL1_ON
1 don't care 0/255 0
0 0 0/255 0
0 1 254/255 1
0 4 251/255 1
0 128 127/255 1
0 255 0/255 1

Setting the above examples from the command line:

root@apalis-t30:~# echo 1 > /sys/class/backlight/pwm-backlight/bl_power
root@apalis-t30:~# echo 0 > /sys/class/backlight/pwm-backlight/bl_power
root@apalis-t30:~# echo 0 > /sys/class/backlight/pwm-backlight/brightness
root@apalis-t30:~# echo 1 > /sys/class/backlight/pwm-backlight/brightness
root@apalis-t30:~# echo 4 > /sys/class/backlight/pwm-backlight/brightness
root@apalis-t30:~# echo 128 > /sys/class/backlight/pwm-backlight/brightness
root@apalis-t30:~# echo 255 > /sys/class/backlight/pwm-backlight/brightness

Querying current settings of bl_power and brightness

root@apalis-t30:~# cat /sys/class/backlight/pwm-backlight/bl_power
root@apalis-t30:~# cat /sys/class/backlight/pwm-backlight/brightness

The PWM logic and frequency is part of the platform code in arch/arm/mach-tegra/board-apalis/colibri_t20/t30-panel.c.

Apalis/Colibri iMX6, Colibri iMX7, Colibri VFxx


bl_power brightness BL_ON
1 don't care 0
0 0 0
0 1..max_brightness 1

Note that the Apalis/Colibri iMX6 V2.7 Beta 1 and earlier did not control BL_ON at all.


The files bl_power and brightness in /sys/class/backlight/backlight/ control the PWM signal.

The device tree contains the backlight configuration. This includes a mapping of brightness values to duty cycles with the value 0 generating a duty cycle of 0% and the value in max_brightness generating a duty cycle of 100%. Also the PWM frequency and polarity can be configured.

The following queries the number of brightness steps, sets the duty cycle to 100% and then to 0%.

# cat /sys/class/backlight/backlight/max_brightness
# echo 0 > /sys/class/backlight/backlight/brightness
# echo 7 > /sys/class/backlight/backlight/brightness

The following can be used to switch the duty cycle to 0% and back to the level determined by what is in the brightness file.

# echo 1 > /sys/class/backlight/backlight/bl_power
# echo 0 > /sys/class/backlight/backlight/bl_power

The device tree also allows to define the PWM polarity to adapt to displays with inverted brightness.


diff --git a/arch/arm/boot/dts/vf-colibri.dtsi b/arch/arm/boot/dts/vf-colibri.dtsi
index 7c5e69e..c230ab5 100644
--- a/arch/arm/boot/dts/vf-colibri.dtsi
+++ b/arch/arm/boot/dts/vf-colibri.dtsi
@@ -14,7 +14,7 @@

        bl: backlight {
                compatible = "pwm-backlight";
-               pwms = <&pwm0 0 5000000 0>;
+               pwms = <&pwm0 0 5000000 1>;
                status = "disabled";

Preserve Setting across Boots

systemd versions 208 and later automatically preserves the current setting across boots with the systemd-backlight@.service. The service is enabled by default.

For older systemd you could create a service such as the following: First create the file /etc/systemd/system/backlight.service.

Note: On Vybrid the PWM backlight sysfs path is /sys/class/backlight/backlight/brightness

Description=Backlight brightness service, set and store display brightness setting

ExecStart=/bin/sh -c 'cat /etc/brightness > /sys/class/backlight/pwm-backlight/brightness'
ExecStop=/bin/sh -c 'cat /sys/class/backlight/pwm-backlight/brightness > /etc/brightness'


Reload and enable the service.

$ systemctl --system daemon-reload
$ systemctl enable backlight


PWM logic

Display Inverted
Ampire 5.7" No
Capacitive Multi-Touch Display 7" No
Capacitive Multi-Touch Display 10" No
EDT 5.7" Yes
EDT 7.0" Yes

Capacitive Multi-Touch Display 7"

The adapter PCB for the Capacitive Multi-Touch Display 7" display has a PWM/digital to backlight LED current converter. This converter requires the PWM Frequency to be > 10kHz or it will fall at least for some duty cycles into its digital mode keeping the backlight dark.

This can be accomplished in the device tree for device tree enabled modules or in the platform data. Capacitive Multi-Touch Display (Linux)