Skip to main content
Version: 5.0

Backlight (Linux)

Backlight Control Signals​

On the Apalis Standard, two dedicated pins are used for backlight control, BKL1_ON, and BKL1_PWM. Note that so far all Apalis modules 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.

On the Verdin Standard, two dedicated pins are used for backlight control: DSI_1_BKL_EN and PWM_3_DSI.

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 through 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 behavior 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_powerbrightnessduty cycleBL_ON/BKL1_ON
1don't care0/2550
000/2550
01254/2551
04251/2551
0128127/2551
02550/2551

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
0
root@apalis-t30:~# cat /sys/class/backlight/pwm-backlight/brightness
255

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, Apalis iMX8, Apalis/Colibri iMX8X, Colibri iMX6ULL, Colibri iMX7, Colibri VFxx, Verdin iMX8M Mini​

BL_ON​

bl_powerbrightnessBL_ON
1don't care0
000
01..max_brightness1

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

PWM​

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 brightest and then to its darkest.

# cat /sys/class/backlight/backlight/max_brightness
7
# echo 7 > /sys/class/backlight/backlight/brightness
# echo 1 > /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 defining the PWM polarity to adapt to displays with inverted brightness.

e.g.

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

[Unit]
Description=Backlight brightness service, set and store display brightness setting
After=multi-user.target

[Service]
Type=oneshot
RemainAfterExit=true
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'

[Install]
WantedBy=multi-user.target

Reload and enable the service.

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

Displays​

PWM logic​

DisplayInverted
Ampire 5.7"No
Capacitive Multi-Touch Display 7"No
Capacitive Multi-Touch Display 10"No
EDT 5.7"Yes
EDT 7.0"Yes
Resistive Touch Display 7" ParallelYes
Capacitive Touch Display 7" ParallelYes

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 > 10 kHz or it will fall into its digital mode at least for some duty cycles 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)

Send Feedback!