ventto / lux

POSIX Shell script to easily control brightness on backlight-controllers.

Lux

Lux is a POSIX-compliant Shell script to control brightness

Perks

• No requirement: POSIX-compliant (minimal: usermod, udevadm)
• Lightweight: ~200 lines
• Auto: Find the best max-brightness-value controller automatically
• Threshold: Restrict brightness value with min/max relevant limits

Installation

Package Manager Utilities

$ pacman -S lux

Manually

• Install lux:

$ git clone https://github.com/Ventto/lux.git
$ cd lux
$ sudo make install

• To control the brightness level, you need to setup the relevant group permissions permanently.
  So first, run lux with sudo and then logout/login.

• If you are in a hurry, you can directly get these permissions properly in a new shell:

$ newgrp video

Usage

Usage: lux OPERATION [-c CONTROLLER_NAME] [-m MIN] [-M MAX]

Brightness option values are positive integers.
Percent mode, add "%" after values (operation options only).
Without option, it prints controller name and brightness info.

Information:
  -h  Prints this help and exits
  -v  Prints version info and exists

Thresholds (can be used in conjunction):
  -m MIN
      Set the brightness MIN (raw value)
  -M MAX
      Set the brightness MAX (raw value)

Operations (with percent mode):
  -a VALUE[%]
      Increase the brightness VALUE
  -s VALUE[%]
      Subtract the brightness VALUE
  -S VALUE[%]
      Set the brightness VALUE (thresholds will be ignored)
  -g Print the current brightness raw value
  -G Print the current brightness percentage

Controllers:
  -c CONTROLLER_NAME
      Set the controller to use.
      Use any CONTROLLER_NAME in /sys/class/backlight.

Examples

• Print information about brightness value:

$ lux
/sys/class/backlight/nv_backlight 0;1000;2000  # { current: 1000, max: 2000 }

$ lux -g
1000

$ lux -G
50%

• Set the brightness value to zero (useful for pitchblack-shortcut):

$ lux -S 0

• Increase the brightness:

$ lux -a 15%    (percentage)
$ lux -a 15     (raw value)

• Limit the value between [500;1999] and increase the brightness:

$ lux -g
1990

$ lux -m 500 -M 1999 -a 10

$ lux -g
1999

• Set the backlight controller manually and set the brightness:

$ ls /sys/class/backlight
intel_backlight

$ lux -c intel_backlight -S 50

FAQ

The max is 2000. Setting the value from 1 to 500 seems to do nothing.

• Set the minimum of 500:

$ lux -m 500 [OPTION]...

Pitch black when the brightness equals the maximum, how avoiding this ?

$ cat /sys/class/backlight/intel_backlight/max_brightness
2000
$ lux -M 1999 ...

Set the brightness value after initializing an X session ?

$ echo "lux -S 75%" >> $HOME/.xinitrc

lux's Issues

Not actually in Arch repos

lux is the AUR, but not actually in the Arch repos. Probably worth updating the README to reflect this. (might be as simple as replacing pacman with your favoriate aur helper)

manpage is not being generated properly

Reproduction

(click to expand)

$ mkdir --parents /home/a/development/github/Ventto
$ git -C /home/a/development/github/Ventto clone --recursive https://github.com/Ventto/lux.git
Cloning into 'lux'...
remote: Enumerating objects: 1, done.
remote: Counting objects: 100% (1/1), done.
remote: Total 408 (delta 0), reused 0 (delta 0), pack-reused 407
Receiving objects: 100% (408/408), 73.55 KiB | 489.00 KiB/s, done.
Resolving deltas: 100% (187/187), done.
$ sudo make -C /home/a/development/github/Ventto/lux install
Password:
make: Entering directory '/data/github/Ventto/lux'
help2man -n 'Shell script to easily control brightness.' \
	-N -h -h -v -v lux.sh | gzip - > lux.1.gz
help2man: can't get `-h' info from lux.sh
Try `--no-discard-stderr' if option outputs to stderr
mkdir -p /usr/share/man/man1
mkdir -p /usr/share/licenses/lux
mkdir -p /etc/udev/rules.d
mkdir -p /usr/bin
chmod 644 lux.1.gz
chmod 644 LICENSE
chmod 644 99-lux.rules
chmod 755 lux.sh
cp lux.1.gz /usr/share/man/man1/lux.1.gz
cp LICENSE /usr/share/licenses/lux/LICENSE
cp 99-lux.rules /etc/udev/rules.d/99-lux.rules
cp lux.sh /usr/bin/lux
make: Leaving directory '/data/github/Ventto/lux'

System information

(Click to expand)

$ uname --all
Linux a 4.19.40_1 #1 SMP PREEMPT Mon May 6 18:20:42 UTC 2019 x86_64 GNU/Linux
$ make --version
GNU Make 4.2.1
Built for x86_64-unknown-linux-gnu
Copyright (C) 1988-2016 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
$ help2man --version
GNU help2man 1.47.10

Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2009, 2010,
2011, 2012, 2013, 2014, 2015, 2016, 2017 Free Software Foundation, Inc.
This is free software; see the source for copying conditions.  There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

Written by Brendan O'Dea <[email protected]>

Other information

/usr/share/man/man1/lux.1.gz is a 20 byte file which produces an empty file lux.1 when extracted.

man-page is empty

man lux shows me an empty man-page. How about removing the man-pages completely? The program is so simple that lux -h should be sufficient. There are many programs which use this approach because of their simplicity. Also this would simplify lux even more and would get rid of the help2man dependency.

Fails to work when run as root on a Debian-based system

I fixed this by removing the quotes from around ${SUDO_USER} on line 103. Maybe more should be done.

•    if ! id -nG "${SUDO_USER}" | grep video > /dev/null ; then
  

•    if ! id -nG ${SUDO_USER} | grep video > /dev/null ; then
  

Set min brightness

Can't set minimum brightness "lux -m 50" doesn't work

$ lux -m 50
Usage: lux [OPTION]...
Brightness option values are positive integers.
Percent mode, add "%" after values (operation options only).

Without option, it prints controller name and brightness info:
{controller} {min;value;max}

Information:
  -h:  Prints this help and exits
  -v:  Prints version info and exists

Thresholds (can be used in conjunction):
  -m:  Set the brightness min (min < max)
  -M:  Set the brightness max (max > min)

Operations (with percent mode):
  -a:  Add value
  -s:  Subtract value
  -S:  Set the brightness value (set thresholds will be ignored)

Controllers:
  -c:  Set the controller to use (needs argument).
       Use any controller name in /sys/class/backlight as argument.
       Otherwise a controller is automatically chosen (default).

License conflict

While the projects itself is licensed under the MIT license, the script mentions GPLv3+ as its license. This commit tells the script should be upgraded to reflect that.

Feature: display current value in %

$ lux
/sys/class/backlight/intel_backlight 0;3749;7499

$ lux -g
50%