The backlight of the 2.8" PiTFT has 4 LEDs in series and it draws ~75mA at all times, controlled by a transistor. The PiTFT 3.5" display has 6 LEDs in a row, and we use a boost converter to get the 5V from the Pi up to the ~20V needed to light up all the LEDs.

There might be times you'd like to save some power and turn off the backlight. The screen and touchplate will still work, you just can't see anything. We designed the board with the STMPE610 touchscreen controller which has 2 extra GPIO and tied one of them to control the backlight. You can use the command line to control the backlight.

By default, the backlight's on...but you can control it in two ways!

PWM Backlight Control with GPIO 18

If you want precise control, you can use the PWM output on GPIO 18. There's python code for controlling the PWM but you can also just use the kernel module and shell commands.

You'll need to make sure the STMPE control is not 'active' as the STMPE GPIO overrides the PWM output.

sudo sh -c 'echo "0" > /sys/class/backlight/soc\:backlight/brightness'

(Or if you are running an old kernel before the backlight object, try sudo sh -c "echo 'in' > /sys/class/gpio/gpio508/direction")

OK now you can set the GPIO #18 pin to PWM mode using WiringPi's gpio command

With these basic shell commands, you can set the GPIO #18 pin to PWM mode with 1000 Hz frequency, set the output to 100 (out of 1023, so dim!), set the output to 1023 (out of 1023, nearly all the way on) and 0 (off)

gpio -g mode 18 pwm
gpio pwmc 1000
gpio -g pwm 18 100
gpio -g pwm 18 1023
gpio -g pwm 18 0

Disabling Backlight Control

If you'd like to not have #18 control the backlight, simply cut the solder jumper, the tiny trace between the two large gold pads marked Lite #18

On / Off Using STMPE GPIO

Another option is to just turn it on and off using the extra GPIO created by the touchscreen driver

Thanks to the raspberry Pi overlay system, this GPIO is already set up for you in a file called /sys/class/backlight/soc:backlight/brightness

STMPE is only installed on resistive touchscreen displays. Look further down in the guide for some alternatives for the capacitive touchscreen.

To turn the backlight off run

sudo sh -c 'echo "0" > /sys/class/backlight/soc\:backlight/brightness'

To turn it back on, run

sudo sh -c 'echo "1" > /sys/class/backlight/soc\:backlight/brightness'

On / Off Using GPIO for the Capacitive Display

If you installed the capacitive display, you may notice that /sys/class/backlight isn't available. This is because the capacitive display uses a different touchscreen driver than the STMPE. You can however still control it using GPIO 18. Start by getting access to the GPIO by making a device link:

echo 18 >/sys/class/gpio/export

Check that the gpio18 was created:

ls /sys/class/gpio/

Set the direction to out with:

echo out >/sys/class/gpio/gpio18/direction

The backlight should turn off. You can turn it on with:

echo 1 >/sys/class/gpio/gpio18/value

or back off again with

echo 0 >/sys/class/gpio/gpio18/value

For older versions of PiTFT Kernel

On older versions of the PiTFT kernel/overlay, the GPIO was not tied to the backlight device. Start by getting access to the GPIO by making a device link

sudo sh -c "echo 508 > /sys/class/gpio/export"
ls -l /sys/class/gpio

For some really old versions, the GPIO pin was #252 not #508 so substitute that if you're running something from 2014 or earlier

Once you verify that you see GPIO #508, then you can set it to an output, this will turn off the display since it will output 0 by default

sudo sh -c "echo 'out' > /sys/class/gpio/gpio508/direction"

Then turn the display back on with

sudo sh -c "echo '1' > /sys/class/gpio/gpio508/value"

or back off

sudo sh -c "echo '0' > /sys/class/gpio/gpio508/value"

Python Backlight Control with Blinka

You can also use python to control the backlight using Python. With Blinka, you can use it to turn the backlight off or on or even use PWM to control the level of the backlight. Since Python is such a flexible language, you can add some effects such as fading the backlight in or fading it out. First make sure you have Blinka installed. For the Raspberry Pi, you can follow our CircuitPython Libraries on Linux and Raspberry Pi guide. To turn the backlight on, you can use this simple demo script:

import board
import digitalio
backlight = digitalio.DigitalInOut(board.D18)
backlight.value = True

To turn it off, you can use this script:

import board
import digitalio
backlight = digitalio.DigitalInOut(board.D18)
backlight.value = False

To use PWM and demonstrate the fading in and fading out effect, you can try running this script:

import time
import board
import pwmio

led = pwmio.PWMOut(board.D18, frequency=5000, duty_cycle=0)

while True:
    for i in range(101):
        led.duty_cycle = int(i * 65535 / 100)  # Up
        time.sleep(0.01)
    time.sleep(1)
    for i in range(100, -1, -1):
        led.duty_cycle = int(i * 65535 / 100)  # Down
        time.sleep(0.01)
    time.sleep(1)

This guide was first published on Nov 29, 2013. It was last updated on Mar 08, 2024.

This page (Backlight Control) was last updated on Mar 08, 2024.

Text editor powered by tinymce.