Backlight (Linux)
This article guides you on how to control the Backlight of displays connected to your Toradex System on Module (SoM) using the sysfs ABI for Linux. For further information on the ABI, refer to the Kernel documentation under Documentation/ABI/stable/sysfs-class-backlight.
Backlight Enable Signals
Toradex System on Modules (SoMs) dedicate two pins for backlight control: a GPIO pin for toggling the backlight, and a PWM pin for adjusting its brightness. These specific pins are compliant with the family specifications. To identify your brightness control pins, refer to the datasheet for your module.
On Colibri carrier boards, the signals BL_ON and PWM<A> are used for adjusting LCD brightness. The BL_ON signal also controls the VGA DAC operation on the Colibri Evaluation Board and Iris Carrier Board.
| bl_power | brightness | Backlight State |
|---|---|---|
| 1 | don't care | 0 |
| 0 | 0 | 0 |
| 0 | 1..max_brightness | 1 |
Both Colibri and Apalis iMX6 V2.7 Beta 1 and earlier do not have BL_ON control.
For the Verdin family, the pins that control the backlight may vary across different carrier boards and depend on the display type (DSI or LVDS). Check your board's datasheet and schematics for further information.
| bl_power | brightness | Backlight State |
|---|---|---|
| 1 | don't care | 0 |
| 0 | 0 | 0 |
| 0 | 1..max_brightness | 1 |
PWM Logic
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 constant at 0V. The PWM signal logic of the displays sold by Toradex is shown below:
Control the Display Backlight
The display backlight control interface is located at /sys/class/backlight/backlight. In this directory, the two main control files are:
bl_power: Enables/Disables the backlight. The file accepts the values 0 or 1, and the meaning of each value (enabled or disabled) is defined in Backlight Enable Signals.brightness: Controls the backlight intensity and accepts values in the range 0–7. The brightness control logic (whether the intensity increases or decreases with higher values) is described in PWM Logic. The PWM duty-cycle values for each brightness setting are specified in the module's Device Tree.
The sysfs path may vary depending on the module and display you are using. Some possible paths are:
/sys/class/backlight/backlight_dsi1_lvds/sys/class/backlight/lvds_backlight/sys/class/backlight/backlight_dsi
Run the commands below to read the current brightness value, then set the backlight to its brightest and darkest values.
# cat /sys/class/backlight/backlight/max_brightness
7
# echo 7 > /sys/class/backlight/backlight/brightness
# echo 1 > /sys/class/backlight/backlight/brightness
Run the following commands to enable and disable the backlight:
# echo 1 > /sys/class/backlight/backlight/bl_power
# echo 0 > /sys/class/backlight/backlight/bl_power
To invert the defined PWM polarity, you can either modify the Device Tree as shown below or write a Device Tree Overlay. This may be useful to easily control displays with inverted brightness logic.
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 Settings across Reboots
Since systemd version 208, it automatically preserves the current setting across reboots with systemd-backlight@.service. This service is enabled by default.
The following example shows a service for older systemd versions:
[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