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_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
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
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
| 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 |
| Resistive Touch Display 7" Parallel | Yes |
| Capacitive Touch Display 7" Parallel | 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 > 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.