https://github.com/linusg/rpi-backlight
🔆 A Python module for controlling power and brightness of the official Raspberry Pi 7" touch display
https://github.com/linusg/rpi-backlight
backlight brightness cli display gui library linux python python3 raspberry-pi raspbian rpi-backlight touch-display
Last synced: 2 months ago
JSON representation
🔆 A Python module for controlling power and brightness of the official Raspberry Pi 7" touch display
- Host: GitHub
- URL: https://github.com/linusg/rpi-backlight
- Owner: linusg
- License: mit
- Created: 2016-10-02T15:56:46.000Z (over 8 years ago)
- Default Branch: main
- Last Pushed: 2024-12-03T23:40:16.000Z (7 months ago)
- Last Synced: 2025-04-07T18:06:57.224Z (3 months ago)
- Topics: backlight, brightness, cli, display, gui, library, linux, python, python3, raspberry-pi, raspbian, rpi-backlight, touch-display
- Language: Python
- Homepage: https://rpi-backlight.readthedocs.io
- Size: 2.64 MB
- Stars: 280
- Watchers: 6
- Forks: 33
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGES.rst
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# rpi-backlight
> A Python module for controlling power and brightness of the official Raspberry Pi 7" touch display.
[](https://pypi.org/project/rpi-backlight/)
[](https://pepy.tech/project/rpi-backlight)
[](https://rpi-backlight.readthedocs.io/en/latest/)
[](https://github.com/linusg/rpi-backlight/blob/main/LICENSE)
[](https://github.com/ambv/black)
[](https://github.com/linusg/rpi-backlight/actions?query=workflow%3ABuild)
[](https://rpi-backlight.readthedocs.io/en/latest/)
[](https://github.com/linusg/rpi-backlight/issues)
**Note:** _This GIF was created using the old v1 API, so please don't use it as API reference 🙂_
## Features
- Set the display brightness **smoothly** or **abrupt**
- Set the display power on or off
- Get the current brightness
- Get the display power state (on/off)
- Command line interface
- Graphical user interface
## Requirements
- A **Raspberry Pi or ASUS Tinker Board** including a correctly assembled **7" touch display v1.1 or higher**
(look on the display's circuit board to see its version), or a [**Surface RT**](https://openrt.gitbook.io/open-surfacert/surface-rt/linux/root-filesystem/distros/raspberry-pi-os) or an [**ARM Chromebook**](https://askubuntu.com/q/1506894) running a Linux-based OS
- Python 3.7+
- Optional: Raspberry Pi: ``pygobject`` for the GUI, already installed on a recent Raspbian
- Optional: Tinker Board: ``gir1.2-gtk-3.0`` for the GUI install
## Installation
Install from PyPI:
```console
$ pip3 install rpi-backlight
```
**Note:** Create this udev rule to update permissions, otherwise you'll have to run
Python code, the GUI and CLI as root when _changing_ the power or brightness:
```console
$ 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
```
### Emulator
For testing without a physical display (e.g. on your main Linux/macOS/Windows machine)
you can use [`linusg/rpi-backlight-emulator`](https://github.com/linusg/rpi-backlight-emulator).
## Usage
### API
Example in a Python shell:
```python
>>> 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
>>>
```
For more details see [docs](https://rpi-backlight.readthedocs.io/en/latest/api.html).
### CLI
Open a terminal and run `rpi-backlight`.
```console
$ 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:
$ rpi-backlight -p toggle
$ rpi-backlight -p toggle -d 1.5
$
```
For all available options see [docs](https://rpi-backlight.readthedocs.io/en/latest/usage.html#command-line-interface).
### GUI
Open a terminal and run `rpi-backlight-gui`.
### Adding a shortcut to the LXDE panel
See [docs](https://rpi-backlight.readthedocs.io/en/latest/usage.html#adding-a-shortcut-to-the-lxde-panel).
## Tests
Tests use `pytest`, install with `pip3 install pytest`.
Now, run from the repository root directory:
```console
$ python3 -m pytest
```
## Contributing
Please free to open an issue for bug reports and to discuss new features - pull requests for new features or bug fixes are welcome as well!
## 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`](LICENSE) for
more information.