
README
======

PBButtons is a programm 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 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.

What is done by the daemon?
    - increse/decrease the display brightness
    - increse/decrease the volume level
    - mute/unmute the speakers
    - supervise battery level and warn if neccesary
    - shutdown the machine if battery level is critically low
    - dim the display to save energy if idle
    - put the machine into sleep mode if idle for longer periods of time
    - keep keyboard settings while in sleep mode (Because of that to work 
      sleep mode must be triggerd by pbbuttonsd)
    - cycle the trackpad mode
    - put the machine into sleep mode on command
    - eject a CDROM on command
    - supervise CPU and network load to block sleep mode until
      the running job is done.
    - adjust power management features according current situation
    
Currently the following events cause a message broadcast to clients:
    - The display brightness is changed by the user,
    - the speaker volume is changed by the user,
    - the speakers are muted/unmuted by the user,
    - the battery is running out of energy,
    - the machine is going to enter sleep mode and
    - the machine is going to be shut down by the daemon.

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 programe, you need some additional parts:
1. An laptop or notebook supported by pbbuttonsd. Up to now it exists only
   a hardware module for Apple computers but this may change in near future.
   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 inplemented 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 runnung OSS emulation,
5. for older kernel versions than 2.4.18-rc2-benh an additional kernel patch
   is nessecary 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.

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

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

The former versions of PBButtons there was a script included to check the
environment. With the new client/server model it isn't nessecary 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 therfore some extra
permissions. To check the system what exactly have to be done, the script
'setupenv.sh' was included. This script checks all nessecary 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 nessecary 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.


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
  >> recognise 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 meaningfull 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
=======

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>

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


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

The daemon 'pbbuttonsd' gets its input directly from the keboard 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.

The following matrix shows all program functions on default keys:

Brightness keys  up	       The display brightness inreases by one.
                 shift up      The display brightness switches to MAXLEVEL.
		 down          The display brightness decreases by
		               one until it is switched completely off.
		 shift down    The display brightness switches to MINLEVEL
		               without switching the backlight completely off.

                 alt up        cycle trackpad mode forward (notap, tap, drag, lock)
		 alt down      cycle trackpad mode backward (lock, drag,...)
				  
Volume keys      This keys modify the speaker and the headphone volume together.
                 Also both stereo channels will be set to the same volume. For
		 a more detailed control a mixer program is nessecary.
		 This is the same manner as the Mac OS will do it. 
		 
                 up            Increases the volume by one.
		 shift up      Increases the volume by ten.
		 down          Decreases the volume by one.
		 shift down    Decreases the volume by ten.

Mute key         pressed once  The volume level of the speaker and headphone
                               will be set to zero.
			       
		 pressed again The old volume levels will be set again. This
		               also would happen, if one of the volume keys
			       was pressed during mute mode. 
		
power key	 pressed       put the machine into sleep mode

Eject key        pressed       a CD will be unmounted an ejected.
			       
A lot of parameters are configurable with a configuration file. Please read the
man page for details.

  Enjoy
    Matthias Grimm


