PBBUTTONSD(1)

NAME
pbbuttonsd - daemon to support Laptop specific functions

SYNOPSIS
pbbuttonsd [options]

DESCRIPTION
PBButtonsd is a daemon which brings support for many Laptop specific functions to Linux. Basically it was designed to support Apple iBooks, Powerbooks or TiBooks but since version 0.5 the design has been changed to support any Notebook.

For every supported Notebook a special module is necessary to do all the hardware dependent jobs. At the moment only Apple Computers will be fully supported but basic functions work also on Intel based machines. Help to build up support for more machines is always welcome.

Supported features:

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

USER INTERFACE
The main input to PBButtonsd works through key codes. Certain keys ensure appropriate actions. This keys are widely user configurable in the configuration file. In detail following keys are supported:

Config Option    Modifier Description
LCD_IllumUpKey   --       Increase display brightness by one.
                 shift    Increase display brightness to maximum value.
                          The shift modifier here is hard coded and
                          can't be configured.
LCD_IllumDownKey --       Decrease display brightness by one until it
                          is completely dark.
                 shift    Decrease display brightness to minimum value.
                          The shift modifier here is hard coded and
                          can't be configured.
KBD_IllumUpKey   --       Increase keyboard illumination brightness
                          by one.
                 shift    Increase keyboard illumination brightness to
                          maximum value. The shift modifier here is
                          hard coded and can't be configured.
KBD_IllumDownKey --       Decrease keyboard illumination brightness by
                          one until it is completely dark.
                 shift    Decrease keyboard illumination brightness to
                          minimum value. The shift modifier here is
                          hard coded and can't be configured.
KBD_IllumOnKey   --       Switch keyboard illumination on/off. The
                          level won't change.
CRT_MirrorKey    --       Enable/disable external video output.
SleepKey         --       Trigger configured sleep action.
VolumeUpKey      --       Increase volume of configured channels by
                          ten percent. This works on all sound hardware
                          the same way.
                 shift    Increase volume level in fine steps. This function
                          uses the volume scale the hardware supports so
                          that small volume adjustment might not result in
                          audible volume change.
                          OSS always handle the volume level in percent
                          so that this function will change the volume
                          level by one percent.
                          The shift modifier here is hard coded and can't
                          be configured.
VolumeDownKey    --       Decrease volume of configured channels by
                          ten percent.
                 shift    Decrease volume level in small steps. Smallest
                          hardware supported step with ALSA and one
                          percent with OSS.
                          The shift modifier here is hard coded and
                          can't be configured.
MuteKey          --       Disable/enable sound output. The volume level
                          won't change. Pressing any other volume con-
                          trol key will automaticaly enable sound out-
                          put again.
EjectCDKey       --       Ejects a CDROM from CDROM drive. If necessary
                          the device will be unmounted before. This
                          would fail if the device was busy.
TPModeUpKey      --       Cycle trackpad mode forward (notap, tap,
                          drag or lock).
TPModeDownKey    --       Cycle trackpad mode backward (lock, drag,
                          tap or notap).

Not all of this keys must work on your system. Most of them are hardware dependent and if your notebook didn't have the required hardware the related function would not work. Read your notebook's manual and pbbuttonsd.conf (5) to figure out what you could expect.

COMMANDS AND SIGNALS
PBButtonsd has an IPC interface (Inter Process Communication) and you could send commands to the server to trigger certain actions. Use the command line tool 'pbbcmd' with following syntax to send commands:

pbbcmd config <command> 0

Commands usually don't need an argument. To keep pbbcmd's user interface simple it expects in config mode always an argument. So please satisfy it with a 0. Following commands are understood:

SAVECONFIG saves the configuration if enabled by pbbuttonsd's security checks (see 'configuration file' section below) and you have the right permission.
EJECTCD unmount and ejects the CDROM or closes the tray again, if already open.
GOTOSLEEP puts the machine to sleep (also known as suspend to RAM) if possible. If sleep was not supported on this machine the screen will be blanked.
REINIT This command triggers reinitialization of hardware under control of pbbuttonsd (for example trackpad and keyboard on powerbooks). The PMCS script to reinitialize the power policy will also be launched after receiving this command. This could be helpful when after a 'suspend to disc' all the hardware needs to be reinitialized.

Beside the IPC interface pbbuttonsd understands some signals:

SIGHUP 1 pbbuttonsd reloads its configuration and scans for input devices (see 'connecting/disconnecting new keyboards' section below).
SIGINT 2 usually emitted by CTRL-C. pbbuttonsd will clean up its resources and terminates
SIGUSR1 10 pbbuttonsd reinitializes hardware components under its control (for example trackpad and keyboard on powerbooks). Sending this signal is the same as sending the command REINIT except that IPC will not be used. This is for the complete paranoid guys ;-)
SIGTERM 15 pbbuttonsd will clean up its resources and terminates

POWERBOOK SPECIALITIES
In kernels before 2.4.18-rc2-benh the brightness of the display was handled by the kernel itself. The brightness hotkeys were blocked by the kernel and there was no chance for a user space daemon like PBButtonsd to get the necessary information.

Nevertheless to get the brightness keys work with older kernels, a special kernel patch could be applied. Without this patch the daemon work as well with the little limitation not to control the display brightness. This is done by the kernel, so a possibly attached client wouldn't be informed on brightness level changes.

There are no limitations with newer kernels.

GENERAL
To get visual feedback from the adjustments a user made, a SystemV IPC interface is implemented to exchange messages with a client which for example displays the brightness and volume levels on a X Desktop.

If battery level is critically low pbbuttonsd has multiple mechanism to react on. The default behavior is to put the machine to sleep. Alternatively it is possible to send the init process the SIGPWR signal or to shut the machine down directly by a configurable script. Everything could be done to bring the machine down in a controlled way before the power management unit will switch the machine off the hard way due to lack of energy. This would prevent data losses and other problems.

To be able to shut down the machine pbbuttonsd must be running as 'root' because only the superuser is allowed to call the shutdown program or could send init requests to the init process.

POWER POLICIES
Since version 0.6 PBButtonsd supports so called power policies. With this policies the user can roughly define how the machine should handle the current load condition. If low current consumption, maximum performance or anything in between is most important at this time. Three policies are supported: 'powersave', 'custom' and 'performance'.

Each power source can be connected to a policy that becomes active as soon as the power source changes. Sometimes it may not desirable that the policy changes as soon as the power source changes. For this case the policy connected to this power source can be set to 'nochange'.

The pmcs script is responsible to put the set policy into practice. PBButtonsd will call this script among others every time the policy changes or has to be reset after periods of sleep or suspend.

CONFIGURATION FILE
PBButtonsd uses a configuration file for setting up all it's features. This file is usually located in etc. From version 0.5.4 on PBButtonsd is also able to write the current configuration to a file.

To make this solution as secure as possible a batch of security checks will be performed until configuration writing would be allowed:

1. The owner of the writable configuration file must be the same as the owner of pbbuttonsd process.
2. The configuration file is only writable by the owner.

If any of this conditions failed, writing of the configuration file would be disabled.

CONNECTING / DISCONNECTING NEW INPUT DEVICES
PBButtonsd uses for its input the event hander in /dev/input/event%, which handles also hot-plugable devices such as USB or ADB (Mac only) input devices. PBButtonsd scanned those devices at start time and work with the found devices. Keyboards or mice connected later weren't recognized by PBButtonsd.

The only way I found to realize newly connected devices is to regularly scan the event devices. This is because first the input layer hasn't any summary keyboard device as is has for mouse devices and second there is no way foreseen for the input layer to inform user space programs about event handler changes.

Although this solution is quite a hack, I implemented it for convenient use. Because of scanning the event devices often might prevent the hard disc from spin down the scanning is _not_ done automatically and must be triggered by the user after she/he had connected a keyboard for example to the USB Bus. Scanning is initiated by sending the HUP signal to the server:

kill -HUP `cat /var/run/pbbuttonsd.pid`

Be aware that the configuration file will also be reloaded in this case.

OPTIONS
PBButtonsd accepts the following options:

-c, --configfile=CONFIGFILE
    Use an alternative configuration file, default is /etc/pbbuttonsd.conf.

-h, --help
    Show summary of options.

-v, --version
    Show version of PBButtonsd.

-q, --quiet
    Suppress the welcome message. Some startup scripts want to have full control about their output.

-d, --detach[=PIDFILE]
    Start PBButtonsd as background process. optional an alternative pidfile. The daemon writes it's pid into this file.
    In this mode we can't assume to have a valid terminal so all outputs will be blocked and no error message will be printed.

If you don't use this flag and start PBButtonsd as background
    process by adding a '&' to the command line, please redirect 'stdout' and 'stderr' to a valid file as well (or at least to /dev/null if you don't need error output). If you don't do so PBButtonsd may be stopped by the shell because of using invalid file descriptors.

SEE ALSO
pbbuttonsd.conf (5), gtkpbbuttons (1)

AUTHOR
Matthias Grimm.