README

== illum ==

Illum is a backlight manager for linux. It changes the screen backlight level
based on keypresses (brightness up and brightness down).

=== Instal (via distro) ===

Arch Linux:

   https://aur.archlinux.org/packages/illum-git/

   pacaur -S illum-git
   systemctl enable illum.service
   systemctl start illum.service

Gentoo:

   https://github.com/jmesmon/overlay
   https://github.com/jmesmon/overlay/blob/master/sys-apps/illum/illum-9999.ebuild

   layman -a jmesmon
   ACCEPT_KEYWORDS="**" emerge illum-git
   rc-update add illum default
   /etc/init.d/illum start

=== build ===

   git submodule update --init
   ./build

OR

   git submodule update --init
   ./configure
   ninja

Note that `ninja` does not recognize env vars like CC and CFLAGS, but
`./configure` does. `./build` is just a convenience wrapper to configure and
then call ninja.

=== Use ===

Run `./illum-d`.

Currently, it attaches to all event sources that supply backlight up and
backlight down keys (assuming they exist under /dev/input/* )

=== Notes ===

 - The user running illum-d needs the appropriate permisions to read from the
   input device (on Arch a member of group 'input' works) and to write to the
   backlight control

=== Dependencies ===

 - libev :: an event loop
 - libevdev :: wrapper for linux's input event system
 - ccan (as a submodule) :: misc utility code

To build:

 - sh
 - ninja
 - pkg-config (to find libevdev)
 - a C compiler (gcc is tested)
 
=== License ===

GNU Affero General Public License version 3 (AGPL-3) as published by GNU: https://www.gnu.org/licenses/agpl-3.0.en.html

==== TODO ====

 - support a "sticky" levels when switching between 0 and 1 (raw values) to
   better support backlights that can turn completely off.
 - better brightness curve (right now is based on squaring, exponential might
   be more acurrate).
 - automatically select "best" backlight driver rather than just "first"
 - play nice with old-bios that also want to adjust the screen on keypresses
 - figure out the right way to enumerate input devices (rather than readdir of
   /dev/input)
 - Hotplug new input devices
 - support using key combinations to adjust at different rates/different ways.
 - add a client control program/library to allow syncronized control from different sources.
 - dimming based on "activity"
    - detects activity
    - obeys inhibits (time limited and lifetime limited)
    - [optionally] displays the current backlight status via an overlay
      - showing other status (caps lock, num lock) may also be useful on come
        machines
    - dim bl durring inactivity

Inspiration:

 - brightd: dims on inactivity