
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-2004 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:
- puts the machine to sleep 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
- puts machine to sleep 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 eject the CDROM,
- to trigger sleep mode.

Support for laptop dependent specialities:
- initializes trackpad and keyboard mode during startup,
- keeps keyboard settings during sleep mode,
- cycles through the trackpad operating mode 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 Sounddriver or ALSA with running OSS emulation,
5. for older kernel versions than 2.4.18-rc2-benh an additional kernel patch
   is necessary to get all features working. The patch 'pbbuttons.patch' is
   available on the same Web-Site as PBButtons. Without this patch only the
   volume control functions will popup those nice little windows. The
   display brightness is controlled directly by the kernel.


INSTALL
=======

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.

 batcycle: With this option activated pbbuttonsd counts the battery 
           cycles so that it would be possible to estimate batteries
	   lifetime. Usually Li-Ion batteries allow 500 charge/discharge
	   cycles.

 batlog:   With this option activated pbbuttonsd writes detailed battery
           data like current charge, voltage, time remaining, etc. on a
           regularly time basis to a log file. Also charge/discharge cycles
           will be counted and displayed. Each charge/discharge cycle gets
           its own battery log file. This data should allow investigation
           of a battery ageing.
	   This option includes the batcycle option.

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

 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.             ---

The former versions of PBButtons there was a script included to check the
environment. With the new client/server model it isn't necessary anymore,
but it is still included to support those who wants to run the PBButtons
daemon as normal user. The following description explains what this script
is able to do.

PBButtons uses some system devices and directories to work properly and
if a normal user wanted to use it, it would need therefore some extra
permissions. To check the system what exactly have to be done, the script
'setupenv.sh' was included. This script checks all necessary devices and
directories and the permissions of them and prints a detailed report
what was ok and what has to be changed.

If this script was started as superuser root, it would ask if it should do
all necessary modifications for you. If it was started as normal user, it
would only print the report.

The automatic mode of the script only realize a very simple concept of
access management. It would simply set read or read/write permissions for
'all user' to the concerning devices and directories if not already set.
Higher sophisticated solutions with access right management via groups
have to be installed by yourself. Please read appropriate manuals to get
help for this task.


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 and a recent gettext development package have to be
installed.

After autogen.sh have successfully done it'S job the program can be
compiled and installed as usual with ./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 pmuds 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:

  catalan translation	from David Riera <riets@ya.com> and 
  			Oriol Pellicier <oriol@elsud.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 Leempurg <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


