rpi-backlight 2.0.0b5

A Python module for controlling power and brightness of the official Raspberry Pi 7" touch display.

rpi-backlight

A Python module for controlling power and brightness of the official Raspberry Pi 7" touch display.

Note: This GIF was created using the old v1 API, so please don't use it as API reference 🙂

Features

• Change the display brightness smoothly or abrupt
• Set the display power on or off
• Get the current brightness
• Get the maximum brightness
• Get the display power state (on/off)
• Command line interface
• Graphical user interface

Requirements

• A Raspberry Pi including a correctly assembled 7" touch display v1.1 or higher running a Linux-based OS
• Python 3.5+
• Optional: pygobject for the GUI, already installed on a recent Raspbian

Installation

Install from PyPI:

$ pip3 install rpi-backlight

Note: You may need to change the backlight rules file in order to run the code:

$ echo 'SUBSYSTEM=="backlight",RUN+="/bin/chmod 666 /sys/class/backlight/%k/brightness /sys/class/backlight/%k/bl_power"' | sudo tee -a /etc/udev/rules.d/backlight-permissions.rules

Otherwise you'll have to run Python code, The GUI and CLI as root when changing the power or brightness.

Emulator

For testing without a physical display (e.g. on your main Linux/macOS/Windows machine) you can use linusg/rpi-backlight-emulator.

Usage

API

Example in a Python shell:

>>> from rpi_backlight import Backlight
>>>
>>> backlight = Backlight()
>>> backlight.brightness
100
>>> backlight.brightness = 50
>>> backlight.brightness
50
>>>
>>> with backlight.fade(duration=1):
...     backlight.brightness = 0
...
>>> backlight.fade_duration = 0.5
>>> # subsequent `backlight.brightness = x` will fade 500ms
>>>
>>> backlight.power
True
>>> backlight.power = False
>>> backlight.power
False
>>>

CLI

Open a terminal and run rpi-backlight:

$ rpi-backlight -b 100
$ rpi-backlight --set-brightness 20 --duration 1.5
$ rpi-backlight --get-brightness
20
$ rpi-backlight --get-power
on
$ rpi-backlight --p off
$ rpi-backlight --get-power
off
$ rpi-backlight --set-power off :emulator:
$

Available flags:

• --get-brightness - get brightness, will output value between 0 and 100
• --get-power - get power, will output on or off
• -b / --set-brightness - set brightness, provide value between 0 and 100
• -p / --set-power - set power on/off, provide on or off
• -d / --duration - use in combination with -b / --brightness to fade the brightness, provide value in seconds >= 0

You can set the backlight sysfs path using a positional argument, set it to :emulator: to use with rpi-backlight-emulator.

GUI

Open a terminal and run rpi-backlight-gui.

Adding a shortcut to the LXDE panel

First, create a .desktop file for rpi-backlight (e.g. /home/pi/.local/share/applications/rpi-backlight.desktop) with the following content:

[Desktop Entry]
Version=1.0
Type=Application
Terminal=false
Name=rpi-backlight GUI
Exec=/home/pi/.local/bin/rpi-backlight-gui
Icon=/usr/share/icons/HighContrast/256x256/status/display-brightness.png
Categories=Utility;

The absolute path to rpi-backlight-gui might differ if you did not follow the installation instructions above, e.g. installed as root.

Make it executable:

$ chmod +x /home/pi/.local/share/applications/rpi-backlight.desktop

You should now be able to start the rpi-backlight GUI from the menu: (Raspberry pi Logo) → Accessoires → rpi-backlight GUI.

Next, right-click on the panel and choose Add / Remove panel items. Select Application Launch Bar and click Preferences:

Select rpi-backlight GUI on the right and click Add:

You're done! The result should look like this:

Tests

Tests use pytest, install with pip3 install pytest.

Now, run from the repository root directory:

$ python3 -m pytest

Todo

I'm currently finalizing the 2.0.0 API and rebuilding the CLI - feel free to open an issue for bug reports and to discuss new features!

License

The source code and all other files in this repository are licensed under the MIT license, so you can easily use it in your own projects. See LICENSE for more information.