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.

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 keyboard - keeps keyboard settings during sleep mode, - cycles through the trackpad operating mode via hotkeys, - support ambient light sensor and automatic adjustment of LCD and keyboard 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 automatically 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 hardware 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 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.
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 possible. 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 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

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

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 controls 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_BACKLIGHT but say NO to PMAC_BACKLIGHT_LEGACY, backlight will work but pbbuttonsd will never get the chance to gain control over the backlight 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. 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.

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 accurate 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 estimations based on default values that won't be better than the kernel battery data. Therefore it is recommended to do one complete battery discharge/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 during initial discharge cycle.

The most important time of a battery discharge cycle is the last minutes. 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 completely drained during the initial discharge cycle (until pbbuttonsd triggers sleep or the hardware switch off hardly, prepare for the second 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 continuously 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 separately. 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 scenario 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 battery 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 initiated by sending the HUP signal to the server:

kill -HUP `cat /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.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.