
README
======
PBButtons is a program suite to support laptop specific functions and
make them available again under Linux. Basically it was developed to
support the special hotkeys of an Apple iBook, Powerbook or TiBook but
since version 0.5 the design has been changed to support all kind of
laptop or notebook.

                    (c) 2002-2005 Matthias Grimm

With this programs the keys for the display brightness, the volume of
speaker and headphone, the mute key and the eject key will do their job
as expected.

This package contains the PBButtons server: pbbuttonsd

The server work as a daemon that do all the work. It runs in background
and is preferable started at boot time. Multiple clients could register
themselves to get messages about events from the server. The following
list shows what's done by the daemon.

Advanced Power Management:
- suspend the machine (configurable) if idle to save energy,
- prevent the machine from entering sleep mode if CPU
  or Net is busy until the job is finished,
- send a warning if battery is running low,
- configurable emergency actions if battery is critically low,
- dims the display if user is passive to save energy
- suspend the machine (configzrable) if cover was closed,
- executes external scripts on certain power management events
  to allow most flexibility,
- is able to replace power management daemons like pmud, apmd, etc.

Support for laptop dependent hotkeys:
- to adjust display brightness
- to adjust keyboard illumination,
- to adjust the sound volume,
- to mute/unmute the sound channels,
- to open/close the CDROM tray,
- to trigger sleep mode.
- to switch external video on/off

Support for laptop dependent specialities:
- initializes trackpad and keyboard mode during startup,
- disables trackpad's mouse click emulation while typing
  on a keyboard,
- keeps keyboard settings during machine suspend,
- cycles through the trackpad operating modes via hotkeys,
- supports PowerBook's ambient light sensor and automatic
  adjustment of LCD and keyboard brightness.

Currently the following events cause a message broadcast to clients:
- The display brightness has changed by the user,
- the keyboard brightness has changed by the user,
- the speaker volume has changed by the user,
- the speakers has been muted/unmuted by the user,
- the battery is running out of energy,
- the machine is going to enter sleep mode,
- the machine is going to be shut down by the daemon and
- the user wants to eject a cdrom.

It is up to the clients what they do with this messages.

Furthermore the client/server interface was redesigned so that every
current and future feature could be configured at runtime by a appropriate
client. See program documentation for details.

Due to the redesign of the client/server interface the versions 0.5.x isn't
compatible to older versions. Older clients won't work with the new daemon.
Please update also any clients you use.


REQUIREMENTS
============
To use this program, you need some additional parts:
1. An laptop or notebook supported by pbbuttonsd.
   - Apple Powerbooks and iBooks are fully supported
   - Intel based laptops are supported without powermanagement and
     model specific features.
   Help with writing additional hardware modules to support more machines
   is always welcome.
2. Kernel support for /proc/pmu/ for battery features (only on pmac).
3. Kernel support for /dev/input/event% for input handling. This support is
   sufficiently implemented for Powerbooks in Kernel 2.4 (versions
   2.4.18-rc2-benh or newer should be preferred). User of x86 notebooks need
   the full patch from Vojtech Pavlik. Kernel 2.6 should be prepared
   sufficiently.
4. OSS or ALSA Sounddriver,
5. Kernel 2.4.18-rc2-benh or later for full funcionallity.


INSTALLATION
============
To compile and install pbbuttonsd please see INSTALL.

Pbbuttonsd can be compiled for a specific laptop model or family to
support specific features. To do this the model must be specified
and command line option for ./configure in the following manner:

  ./configure LAPTOP=<model> <other options>

Currently two models/families were supported:

LAPTOP=[POWERBOOK | powerbook | pb | PB]
   Apple PowerBooks or iBooks, all models.

LAPTOP=[I386 | i386]
   Generic support for Intel based laptops. Up to now support for
   powermanagement and specific laptop features is missing but it's
   also up to you to push this tool forward.

Two additional features could be activated at compile time. To do this
call the configure script with the option --enable-<FEATURE>:

 debug:    Activates additional output to console. Pbbuttonsd should not
           be called with -d (detach) to get full benefit of this option.
           The complete internal data communication between modules and
           the current status of the sleeplocks will be displayed.

 The former features 'batcycle' and 'batlog' have become runtime options
 They are not longer available on compile level. Please see man-pages
 for details.

One additional module could be activated at compile time. To do this
call the configure script with the option --with-<MODULE>:

 oss:    The OSS mixer module will be compiled is. This is the default
         behaviour. If you don't have OSS on your system or you don't
         want to use it, give --without-oss to disable the OSS mixer
         module.

 alsa:   The native ALSA mixer module will be compiled is. This would be
         the default behaviour if the ALSA libraries were found in your
         system. If you don't have ALSA or you don't want to use the
         native ALSA mixer give --without-alsa to disable it. ALSA's OSS
         emulation works also with the OSS mixer modules.

         -- if both mixer modules were compiled in you could choose  --
         -- the module to be used in pbbuttonsd's configuration file --

 pmud:   Additional code will be integrated in Pbbuttonsd to use pmud as
         low level power manager. Normally PBButtons will do all necessary
         jobs by its own, but for special applications it could make sense
         to keep pmud running. In this case PBButtons must be compiled
         with pmud support to cooperate and don't conflict with it.
         Compiled with pmud support PBButtonsd uses pmud to trigger sleep
         mode and release cover control. If the machine went to sleep after
         closing the lid would be the responsibility of pmud then.

         -- I recommend not to use this option. Compile pbbuttonsd   --
         -- without pmud support. It will work better.               --

BUILDING FROM CVS
=================
If you got the source from the CVS repository you would need to run
  ./autogen.sh
first to build all necessary files for compiling. To do this the
autotools (autoconf and automake) and a recent gettext development
package have to be installed.

After autogen.sh have successfully executed the program can be compiled
and installed with the usual tripple: ./configure; make; make install.


DIFFERENCES TO PMUD
===================
PBButtonsd could be configured to work in friendly coexistence with pmud
but it is designed to fully replace it. So, if there isn't any very good
reason to keep pmud running, remove it and configure PBButtonsd to do all
the jobs. This is also important because pmud's development has been given
up.

Of course there are a lot of differences between pmud and PBButtons and
please read the documentation to catch all details. At this point only
those pmud options should be discussed that PBButtonsd doesn't support.

- test pccard eject
  >> Not possible on Pismo, it seems to be that the pmu doesn't
  >> recognize this key, need feedback from users in this case
- option to send SIGPWR whenever sleep is requested or triggered
  >> I don't think that it would be meaningful but pmud did it.
- maybe export pmu version in environment
  >> I don't think it's necessary except to be 100% compatible with pmud
- option to disable backlight control by pbbuttonsd
  >> pmud has such an option but until now nobody requested it for
  >> pbbuttonsd. If so it could be easily implemented.
   
You see that some options depend on user request. If you think you need
one or more of the missing options or you missed any other feature, please
write an email to me. Until now I always found a way to content the users.


LEGAL NOTICE
============

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version
2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; see the file COPYING.  If not, write to
the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.


CREDITS
=======

Special thanks deserve some people who supported pbbuttonsd with
their own contributions:

  ALSA mixer module    from John Steele Scott <toojays@toojays.net>
  catalan translation  from David Riera <riets@ya.com> and 
                       Oriol Pellicer <oriol@elsud.org>
  spanish translation  from Rudy Godoy <rudy@kernel-panik.org>

This program wouldn't exists if not some people wrote other programs
from which I learned how special things worked. I can't name all of
them so I picked those out, whose programs I could call the 'parents'
of PBButtons:

  keyevd       from Joseph P. Garcia <jpgarcia@execpc.com>
  ikeyd        from Stefan Pfetzing <dreamind@dreamind.de>
  pmud         from Stephan Leemburg <sleemburg@jvc.nl>
  snooze       from Paul Mackerras <paulus@linuxcare.com> and
                    Stephan Leemburg <sleemburg@jvc.nl>
  trackpad     from Ben Herrenschmidt <benh@kernel.crashing.org>
  fnset        from Jimi X <jimix@watson.ibm.com>
  lmud         from Andreas Jaggi <andreas.jaggi@waterwav.ch>
  alcd         from Federico Gamio <federico@gamio.net>

Also thanks to all unknown developers, who make my little program
possible.


HOW IT WORKS
============

The daemon 'pbbuttonsd' gets its input directly from the keyboard event handler.
Consequently the keys are always active. It doesn't matter if X11 is in front
or if you are working on a console or which X11 window has the focus. You
can always use the hotkeys and get the appropriate reaction.

A lot of parameters are configurable with a configuration file. Please read the
man page for details.

  Enjoy
    Matthias Grimm


