Most embedded TFT LCD products use a separate LED backlight circuit. Linux usually controls brightness through a pwm-backlight node in Device Tree. If this node is wrong, the panel may show no visible image even when the display data path is working.
A simplified Device Tree example looks like this:
backlight: backlight {
compatible = "pwm-backlight";
pwms = <&pwm0 0 25000 0>;
brightness-levels = <0 32 64 128 192 255>;
default-brightness-level = <5>;
enable-gpios = <&gpio1 3 GPIO_ACTIVE_HIGH>;
};
Actual syntax depends on the kernel, SoC, and board pin naming.
compatible: selects the PWM backlight driverpwms: selects PWM controller, channel, period, and polaritybrightness-levels: maps brightness index to PWM duty valuedefault-brightness-level: default index at bootenable-gpios: optional GPIO that enables the backlight driverThe PWM controls brightness. The enable GPIO often turns the LED driver on or off.
Check:
If brightness control appears in Linux but the screen stays dark, measure the PWM pin and backlight enable pin.
brightness-levels does not have to be linear, but it should match the visual behavior of the product. Human brightness perception is not perfectly linear. A table with more steps near low brightness can make dimming feel smoother.
For early bring-up, use a simple table first:
brightness-levels = <0 32 64 128 192 255>;
default-brightness-level = <5>;
After the display works, tune the table for the final product. Do not tune brightness while the basic enable GPIO or PWM channel is still uncertain.
The PWM period must be compatible with the LED driver. If the frequency is too low, the user may see flicker. If it is too high, the LED driver may not respond as expected. The correct value depends on the backlight driver circuit, not only the LCD panel.
Polarity also matters. If the PWM polarity is inverted, brightness may work backward or stay off at the expected default value. Test minimum, middle, and maximum brightness after boot.
Many backlight circuits use both PWM and enable. PWM controls brightness, while enable turns the LED driver on. If enable polarity is wrong, the PWM signal may be present but the backlight remains off.
Check the schematic:
After boot, inspect the backlight class:
ls /sys/class/backlight
cat /sys/class/backlight/*/max_brightness
cat /sys/class/backlight/*/brightness
Try writing a safe brightness value. If software brightness changes but the screen does not respond, measure the PWM output. If the PWM output changes but the LEDs do not, inspect the LED driver power and enable signal.
Test brightness at boot, after suspend/resume, after Android or Linux UI starts, and after several reboots. Some systems briefly turn the backlight on before the panel is initialized, causing a white flash. For a polished product, sequence the panel and backlight so the image is ready before illumination.
PWM configuration cannot fix an undersized LED driver. Check the panel backlight current and voltage requirement against the board circuit. A small display may only need modest current, while a larger high-brightness industrial panel may need a dedicated boost driver. If the driver cannot supply enough current, the display may look dim even with 100 percent PWM duty.
Also consider thermal behavior. Running the backlight at full brightness inside a sealed enclosure can raise panel and board temperature. Production firmware may need a maximum brightness limit or thermal policy.
On Android, the kernel backlight driver is only one layer. The framework, brightness slider, default settings, and power policy also affect the final behavior. Test manual brightness, automatic dimming if enabled, screen-off behavior, and wake-up brightness. If the kernel node works but Android brightness does not, inspect framework or vendor display configuration rather than changing the PWM node again.