PBBUTTONSD(1)PBBUTTONSD(1)NAMEpbbuttonsd - daemon to support Laptop specific functions
SYNOPSISpbbuttonsd [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.
From its roots pbbuttons support Apple PowerBooks and iBooks by 100%.
Support for the new Intel based MacBooks is very new but grows
steadily. I would say we reached 70% by now. Also the support for other
intel based notebooks jumped forward by adding the ACPI support to
pbbuttonsd, but because laptop support is very hardware dependent, I
guess we have only 30% on this 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 key‐
board
- keeps keyboard settings during sleep mode,
- cycles through the trackpad operating mode via hotkeys,
- support ambient light sensor and automatic adjustment of LCD and key‐
board brightness on Apple PowerBooks and MacBook Pros.
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.
shift Increase display brightness to maximum value.
The shift modifier here is hard coded and
can't be configured.
LCD_IllumDownKey -- Decrease display brightness until complete
darkness.
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.
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
until complete darkness.
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). This function is only available
on Apple PowerBooks.
TPModeDownKey -- Cycle trackpad mode backward (lock, drag,
tap or notap). This function is only available
on Apple PowerBooks.
Not all of this keys must work on your system. Most of them are hard‐
ware dependent and if your notebook doesn't have the required hardware
the related function will not work. Read your notebook's manual and
pbbuttonsd.cnf (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 <command>
Following commands are understood:
SAVECONFIG saves the configuration if enabled by pbbuttonsd's secu‐
rity 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.
SLEEP 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. Sleep is a kernel function
and will only be triggered by pbbuttonsd.
HIBERNATE saves the memory and the process information to disk
(also known as suspend to Disk or Hibernate) if possi‐
ble. If hibernate was not supported on this machine
nothing will happen. Hibernate is a kernel function and
will only be triggered by pbbuttonsd through a PMCS
script usually placed in /etc/power/.
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 scans for new input devices (see
'connecting/disconnecting new keyboards' section below).
SIGINT 2 usually emitted by CTRL-C. pbbuttonsd will clean up used
resources and terminates
SIGUSR1 10 pbbuttonsd reinitializes hardware components under its con‐
trol (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
KERNEL CONFIGURATION
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 PBBut‐
tonsd to get the necessary information.
Nevertheless to get the brightness keys work with older kernels, a spe‐
cial kernel patch could be applied. Without this patch the daemon work
as well with the little limitation not to control the display bright‐
ness. This is done by the kernel, so a possibly attached client
wouldn't be informed on brightness level changes.
With kernel >= 2.6.18 a new SysFS interface to the backlight controller
has been introduced. Unfortunately the kernel configuration become very
confusing and misunderstanding. The Kernel has two options regarding
the backlight in section "Device Drivers -> Macintosh Device Drivers":
Backlight control for LCD screens
(CONF_PMU_BACKLIGHT)
The help text says that this option enables generic backlight code.
In fact without this option you won't get any backlight interface
running, neither SysFS nor PMU, so say YES here.
Unfortunately this option enables also code to control display
brightness for older PowerBooks. That means the kernel itself con‐
trols the backlight brightness and interfere with any user space
daemmon. The reference in the help text to use a user space daemon
like pbbuttonsd is very kind, but The user space daemon is helpless
if the kernel itself do the job. Nevertheless say YES to this
option.
Provide legacy ioctl's on /dev/pmu for the backlight
(CONF_PMU_BACKLIGHT_LEGACY)
This option apears if backlight control has been enabled. This
option adds some code to read and write the backlight level via the
pmu driver (/dev/pmu). This interface was used by pbbuttonsd in
the past and normaly it isn't needed any longer because the SysFS
interface should make it redundant.
Unfortunately the function to disable the direct kernel control of
the backlight (for old PowerBooks, you remenber?) is part of the
code added by this option. That means if you say YES to PMAC_BACK‐
LIGHT but say NO to PMAC_BACKLIGHT_LEGACY, backlight will work but
pbbuttonsd will never get the chance to gain control over the back‐
light controller. Kernel and user space daemon will interfere with
eachother in an unacceptable way and that leads to unwanted
results.
This mixture of related but independent functions make it necessary
to say YES to this option as well until the Kernel guys cleaned up
this mess.
Finally your Kernel 2.6.18 configuration should look like this:
[*] Backlight control for LCD screens
[*] Provide legacy ioctl's on /dev/pmu for the backlight
PBButtonsd will then automatically detect the best suited interface and
use it.
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. Alter‐
natively 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 pro‐
gram 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 perfor‐
mance 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.
PBButtonsd AND SLEEP MODE (Suspend to RAM)
PBButtonsd can't suspend the machine by its own. It uses kernel API
functions for that. This means pbbuttonsd only asks the kernel: "Please
suspend the machine". If the kernel do so and what happens after the
request is up to the kernel.
Problems in this stage often occour due to old device drivers which
don't support the suspend mode very well. The kernel API changed a lot
here and it took a lot of time to adapt all the device drivers to the
new interface. A solution could be to unload problematic device drivers
before triggering sleep and reload them after wake up. PBButtonsd
would support that via its Power Management Control Scripts (see
/etc/power/).
The machine went to sleep after the main CPU has been switched off.
Now, the computer is only controlled by the PMU which is a small
(mostly 8bit) microprocessor with ROM (Read Only Memory) code. After
the occourence of a dedicated event the PMU reactivates the main CPU
and the machine wake up again. Those events could be:
- trigger a key on the keyboard
- open the cover (closing the cover doesn't wake up the machine)
- insert or remove an USB device
- timer
- other computers address the sleeping computer via LAN
The PMU needs to know which events should trigger a wake up procedure.
The first two are explicitly enabled by the kernel before putting the
machine to sleep. The third seems to be not maskable by the PMU, that
means it will always wake up the computer. And the last two weren't
supported at all yet on Linux.
While the key trigger event will unconditionally wake up the machine,
the cover open event could be configured via the /proc/pmu/options
interface. The following command will prevent your machine from waking
up after the cover has been opened:
echo > "lid_wakeup=0" > /proc/pmu/options
And the following command enable the wake up on "cover open" again:
echo > "lid_wakeup=1" > /proc/pmu/options
Other wake up options are not foreseen by the kernel but may be added
in the future. PBButtonsd is completely out of control until the kernel
has finished its wake up procedure and gives control back to user
space.
IBaM (Intelligent Battery Monitoring)
IBaM is an advanced battery monitoring method, which uses statistical
and adaptive linear methods to provide accurate estimations of battery
time remaining or of the time needed until full recharge.
If IBaM is compiled into pbbuttonsd all internal time calculations
based on kernel battery information would be replaced. Through the IPC
signal TimeRemaining pbbuttonsd clients could benefit from accurate
time estimations too.
Once started Pbbuttonsd will collect battery data and saves them to
disk for statistical analysis. The more data pbbuttonsd have to analyse
the more accurate the time estimations will be.
Because at the very beginning pbbuttonsd has no data to analyse it is
recommended to perform the initial procedure described below to fill
the database with real data. If pbbuttonsd has to initialize IBaM's
database during normal usage with arbitrary charge and discharge
cycles, it might take longer to get reliable time predictions and accu‐
rate battery warnings.
IBaM INITIAL PROCEDURE
This step is not necessary if you only update PBButtonsd. The updated
version will continue to use the existing data.
At the very beginnig pbbuttonsd has no data to analyse and all estima‐
tions based on default values that won't be better than the kernel bat‐
tery data. Therefore it is recommended to do one complete battery dis‐
charge/charge cycle after installing this version of pbbuttonsd with
integrated IBaM to initially fill the database with real data.
Unplug AC power from your laptop. IBaM will now save the time intervals
between changes in battery status. PBButtonsd will already use the data
in this early stage and the battery warnings might be unreliable or
won't occur at all. This is normal behaviour and will only happen dur‐
ing initial discharge cycle.
The most important time of a battery discharge cycle is the last min‐
utes. During the last, let's say 20 minutes of battery time it is most
important to get reliable and accurate battery warnings. But this aim
could only be reached if the IBaM database contains data about the last
minutes on battery. It is very important that the battery will be com‐
pletely drained during the initial discharge cycle (until pbbuttonsd
triggers sleep or the hardware switch off hardly, prepare for the sec‐
ond case to prevent data losses).
After your battery is completely drained, plug in your AC connector and
continue working as usual.
IBaM is fully initialized now and it's prepared to show its full power
and benefit. Depending on your load cases the time estimations will
fluctuating a bit the first time. But after roundabout three battery
charge/discharge cycles the predicted time and the battery warnings
will be rather stable and reliable.
The database is updated continously so that any aging of the battery is
taken into account. When pbbuttons tells you now, you still have 10
minutes left on battery, then you will have 10 minutes left even if
your battery is growing old and the capacity decreases.
IBaM and multiple batteries
Currently IBaM is not able to handle multiple batteries seperatly. It
always sums up all batteries in system and calculates with the result.
Therefore the IBaM statistics will be influenced if you change your
battery configuration (adding or removing batteries).
Battery warnings will be slightly inaccurate after changing the battery
configuration. If you run a long time with a unchanged configuration
this changes would hardly be significant or not seen at all. The sce‐
nario described in the paragraph below is only likely if you did only a
few charge/discharge cycles.
After plugging in an additional battery pbbuttonsd might show low bat‐
tery warnings too early and vica versa after you removed your second
battery. Especially after you decreased overall battery capacity by
removing a second battery, pbbuttonsd might get aware of low battery
condition too late. As result the machine will switch off the hard
way. To prevent data losses in this case you should not wait for the
last warning before you plug in the AC connector. IBaM will resync
itself automatically during the next charge/discharge cycles.
IBaM works best if you use always the same battery configuration (one
or two batteries).
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 scanns those devices at start time and work
with the found devices.
Before Hotplug, the only way for pbbuttonsd to realize newly connected
devices is to regularly scan the event devices. Unfortunately there is
no summary keyboard device as there is for mice and hotplug isn't
available for kernel 2.4 and before. Because external USB input devices
become quite common, the autorescan feature is enabled by default.
If your hard disk is prevented from spinning down due to the regular
event device scans, you might want to disable this feature. This could
be done in the configuration file. In this case you have to trigger a
rescan manually after connecting new input devices. Scanning is initi‐
ated 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/pbbut‐
tonsd.cnf.
-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.cnf (5), gtkpbbuttons (1)
AUTHOR
Matthias Grimm.
February 07, 2007 PBBUTTONSD(1)
