Scroll to navigation

PBBUTTONSD.CNF(5) File Formats Manual PBBUTTONSD.CNF(5)

NAME

pbbuttonsd.cnf - configuration file for pbbuttonsd >= 0.8.

DESCRIPTION

pbbuttonsd.cnf tells pbbuttonsd how the user wants it to work and is usually found as /etc/pbbuttons.cnf.

With Pbbuttonsd 0.8 the format of the configuratione file slightly changed. It uses now the keyfile format defined by the freedesktop organisation. It is very similar to the old format which was proprietary to pbbuttonsd but is not exactly the same. The main advantage of the new file format is that pbbuttonsd can now use code of the glib to pare it, instead doing everything by itself.

The file format could be found on http://freedesktop.org/Standards/desktop-entry-spec. A rough short form of the file formatcomes here.

An option looks always like this:

keyword=value

Empty lines and lines starting with a number-sign (#) will be ignored. Comments behind options are not allowed and lead to unwanted results.

The value contains the whole rest of the line including any white spaces. So quoting is not necessary and forbidden. Quoted strings will be read as quoted strings and may cause unwanted results. The quotation marks won't be filtered out.

It isn't necessary to define every option or a configfile at all because there are useful default's built into the program.

The config file is split up into sections to group options which belong together. The section headlines are corresponding to the pbbuttonsd modules and group the options. It os allowed to have two options with the same name as long as they are in different sections. Each module has a config file section. The available options depends on the modules functionality.

KEYCODE DEFINITIONS

Some of the options need key definitions. A key could be defined as follows.

The key definition could have multiple parts. The first is the keycode as it could be found in ..include/linux/input.h. This keycode at least must be given otherwise the built-in default value will be used.

The other parts are the optional modifiers that could be combined with the keycode to trigger the certain function. The shift, alt and ctrl modifier are supported. They are added to the keycode with a plus-sign (+). The sequence doesn't matter.


EXAMPLE: 225 + shift + ctrl
This means the key 225 has to be pressed together with shift and ctrl to trigger the function.

GENERAL

Lets talk about security. PBButtonsd accepts messages through the kernel IPC-message protokoll without verification who sent the message. This doesn't seem to be a problem because IPC is only used locally and can't be accessed directly over network. Only those options which could be abused to get root rights were protected and could only be changed by the owner of pbbuttonsd's process.


This didn't satisfy some users so I implemented this option to give those users more control who should be allowed to send messages to pbbuttonsd. If this option is set only the named user (only one possible at the moment) is allowed to change pbbuttonsd's options via the IPC-interface. Messages from all other users (root included) will be rejected. Query the current configuration is further possible for all users.


To completely disable the possibility to change options via IPC name a user that doesn't exist. In this case no logged-in user is allowed to change options. Setting the option in the config file and 'kill -HUP <process-id>' would then be the only way to change options on the fly then.

PBButtonsd uses the kernel input layer and its event devices to get input from the keyboards and mice. This layer support all types of input devices also those which will be connected or removed later during operation. Normally pbbuttonsd scans the event devices once at startup and uses all keyboards and mice found at that time but most people wanted to be able to plug-in or remove external input devices at any time.


With this option set to 'yes' pbbuttonsd would scan for new input devices on a regular time basis. Due to the continuous access to the /dev/input/event% device files, spin-down functions of hard disks might be influenced. If you have problems with this, you could disable this feature and trigger a rescan by hand when necessary.

Pbbuttonsd is able to launch user defined scripts and it uses some external helper utilities. This scripts and utilities were started as separate processes with their own environment independent from pbbuttonsd's. During a helper process is active pbbuttonsd's process is blocked and waits for the child process to end. Without security mechanism this could lead into an knocked out pbbuttonsd due to a hanging script. To prevent such a situation pbbuttonsd has an eye on its child processes and if they consume too much time they will be killed by the parent process.


It was very difficult in the past to define a correct timeout value because of a huge amount of different scripts written and used by users. With this option the individual timeout value in seconds can be defined. Be careful with high values because an error in your script can block pbbuttonsd for a long time. The minimum value is 1 second. values below this will force a one second timeout.

MODULE POWERSAVE

This module does all the hardware independent power saving stuff.

onAC_Policy = policy (default: performance)
onBattery_Policy = policy (default: powersave)
This options set the power management policies that should become active after power source has changed. following policies were supported:



'nochange' current policy won't be changed
'powersave' minimum power consumption
'custom' user defined
'performance' maximum system performance


The pmcs script does all actions needed to activate the options according the selected power policy.

onAC_TimerAction = action (default: suspend-to-ram)
onBattery_TimerAction = action (default: suspend-to-ram)
After some time without user action, so called idle time, the timer emits an event. Pbbuttonsd can connect an action to this event that would be executed when this event occours. Four actions are possible (see below). This option can independently configured for AC or battery power source.


none
Nothing will be done. If onXX_TimerAction was set to 'none' the timer event would be ignored.


suspend-to-ram
This action suspends the machine and conserves the memory content in RAM. This mode is also known as 'sleep' and works only if it is supported by the hardware.


suspend-to-disk
This action suspends the machine and save the memory content to hard disk. This mode is controlled by the kernel and is supported since kernel version 2.6. A backport for kernel 2.4 is also available.


This action works a little bit different to suspend-to-ram. If the event suspend-to-ram occours the PMCS script will be executed to perform preliminary jobs. Suspend-to-ram is then triggered by pbbuttonsd.


If the event suspend-to-disk occurs the PMCS script will also be executed but in contrast to suspend-to-ram it has also to initiate suspend mode after all preliminary jobs are done. Pbbuttonsd doesn't expect the script to return.


blankscreen
If this action was configured the screen would be switched off. The computer will continue to run. This could be helpful in some cases where for example the machine must be reachable over a network without anyone working with it directly.


This mode is the fallback action if suspend-to-ram is not supported by the hardware.


Attention: With a switched-off display you might not be able to see that the computer is still running but it continues to consume power. To give you a hint the computer will play a beep every 30 seconds as a reminder.


shutdown
This action triggers a machine shutdown. The PMCS script is called to initiate the shutdown. Usually this is done with the ´halt´ command.

onAC_CoverAction = action (default: suspend-to-ram)
onBattery_CoverAction = action (default: suspend-to-ram)

This options define the action to perform if cover has been closed or opened. For possible actions and it's description please see onXX_TimerAction. It could independently configured for AC or battery power source.


This options will only work if pbbuttonsd was compiled without pmud support so that pbbuttonsd has control over the cover.


Attention: With a switched-off display you might not be able to see that the computer is still running but it continues to consume power. To give you a hint the computer will play a beep every 30 seconds as a reminder.

onAC_KeyAction = action (default: suspend-to-ram)
onBattery_KeyAction = action (default: suspend-to-ram)

This options define the action to perform after the sleepkey has been triggered. For possible actions and it's decription please see onXX_TimerAction. It could be independently configured for AC and battery power source.

onAC_SuspendTime = value (default: 3000 = 5 minutes)
onBattery_SuspendTime = value (default: 3000 = 5 minutes)

This option sets the idle time in 1/100 seconds after the machine should be put to sleep or the display should be switched off. It could independently controlled for AC or battery power source.


Set this value to 0 to disable sleep when idle.

onAC_DimTime = value (default: 600 = 1 minutes)
onBattery_DimTime = value (default: 600 = 1 minutes)

This option sets the idle time in 1/100 seconds after the display should be dimmed to minimum level. It could independently controlled for AC or battery power source.


Set this value to 0 to disable display dimming. The display brightness won't change automatically and keep its value for unlimited time.

Key to trigger sleep mode or blank the screen, corresponding to the current configuration and the machine's abilities.
This option sets the delay time used for an additional validity check of the sleep key to prevent unwillingly triggered sleeps due to small keyboards. The key must be pressed for longer than the given time period to trigger sleep. The value must be given in milliseconds, for example to set a delay time of 2 seconds set the delay time to 2000. If the given value is zero, sleep mode would be entered immediately.


This option might be dangerous if the power key is used to trigger sleep mode, because the power key has a second hard-wired meaning. If you press the power key for a long time, the machine will be switched off completely. This is an emergency feature of the Macintosh hardware. Therefore it could be very tricky to press the power key long enough to trigger sleep and release the key just before the hardware switched power off. Use this option with care.

BWL_First = minutes (default: 20)
BWL_Second = minutes (default: 10)
BWL_Last = minutes (default: 3)

This options set the battery warn levels in minutes. If the remaining time on battery falls below one of the above values the appropriate battery warning would be displayed (gtkpbbuttons or something similar must be running to see them).


If the time remaining reaches 'zero' the non-configurable battery warnlevel 4 is entered, which causes the machine to shutdown immediately. The clients will be noticed by a message about the coming shutdown.


Defining new warn levels be aware that you fulfill following conditions:
- BWL_First > BWL_Second > BWM_Last > 0 - the difference of two adjacent warnlevels must be greater than 6 minutes.


Violation of this conditions will result in an error message and fall back to default values.

If the battery is critically low the machine have to be set into a safe state. This could be done on different ways. Which way is the right for your system could be configured with this option. There are three actions possible:


sleep - The machine would be forced to sleep mode. This action gives security only for a short period because also in sleep mode the computer consumes power and continue to discharge the battery but slower. This gives you enough time to plug in the AC connector to recharge the battery and go on with your work.
This action could only be chosen if the machine supports sleep mode. If not this action defaults to signal.


signal - A SIGPWR signal would be sent to the INIT process. The further actions depend on your system configuration in /etc/inittab. Please check your installation to be sure the SIGPWR does what you want. Pbbuttonsd won't do anything else to prevent data losses due to battery voltage collapse.
Pbbuttons tried first to send the init process the signal with the new init request through /dev/initctl. If that fails it tried the old method through /etc/powerstatus. If that fails too and the machine supports sleep mode this action defaults to sleep, otherwise it defaults to command.


command - This is the former standard action in case of critically battery power. a command would be executed which usually shut down the computer safely. The script_pmcs (see below) will be called with argument 'emergency' in this case.

Pbbuttonsd can be configured to switch off the display instead of entering sleep mode even though the lid was closed. As configured in such a way the machine only to switch off its display after sleep timeout and continue running on full power. If in this situation also the hard disk spun down, no sign of computer's life would exist anymore and the machine looks like a switched off computer.


This may lead to unexpectedly drained batteries or needlessly long idle runs because the computer looks like already switched-off and you may then forget to switch it off really. Due to pbbuttonsd's smart power management functions nothing harmful can happen to the computer or to your valuable data. So this is a convenience option.


To have always a sign of life from the computer pbbuttonsd will play a beep every roundabout 30 seconds if the computer was still running with switched-off display. Someone will take the risk to get rid of this nice little beep (others called it annoying). For those this option was implemented. It will switch off the heartbeat beep if set to 'no'.


Usual cases when the heartbeat beep will occur are using your PowerBook with closed lid connected to an external keyboard and monitor or access your computer remotely via the network. In the second case the heartbeat beep will first occur with delay of the configured sleep timeout.

This option sets the script name that should be called at following events: change of power policy, change of power source, change of suspend state and if configured at low battery (emergency). For security reasons this script should only be readable by the user who runs pbbuttonsd (usually root) and not be writable at all.


Up to three '%s' could be placed in the command string. The first '%s' will be replaced with the action (see etc/power/README for action list), the second with the current powersource ('ac' or 'battery') and the third with an action depending option. (for example the action 'suspend' may get the option 'ram'. This means suspend-to-ram).

This directory is used to store statistical data measured during battery charge and discharge time. This data is used by the new IBAM algorithm for reliable and accurate battery and charge time predictions.


This option would only be available if pbbuttonsd was compiled with IBAM support.

With option enabled high CPU loads prevent the machine from entering sleep mode. Every second the current CPU load will be calculated and compared with a minimum level. Is the current CPU load below this level for a certain period of time the sleep lock will be opened and the machine is allowed to enter sleep mode. Jumps the CPU load over the border line the sleep lock will be closed immediately and the time measurement starts from the beginning.
With this Tag the minimum CPU load level could be set.
With this option the period of low CPU load time in seconds could be set.
With option enabled high net loads prevent the machine from entering sleep mode. Every second the current net load will be calculated and compared with a minimum level. Is the transfer rate in bytes per second below this level for a certain period of time the sleep lock will be opened and the machine is allowed to enter sleep mode. Jumps the net load over the border line the sleep lock will be closed immediately and the time measurement starts from the beginning.
With this Tag the minimum transfer rate in bytes per second could be set.
With this Tag the period of low net load time in seconds could be set.
With this option the network device to observe could be defined. Up to now only one network device could be set and observed.

MODULE DISPLAY

This module controls the light sources inside the laptop. Mostly this is the LCD backlight but recent computers come with an additionally keyboard illumination which is also controlled by this module. The module works hardware independently.

With this option the initial brightness level of the LCD backlight in percent could be set. This value becomes active during pbbuttonsds start up phase.


Was this option commented out, pbbuttonsd wouldn't change the LCD brightness during start up. The display stays as bright as it has been before pbbuttonsd was started. Comment this option out if you want this behaviour.

PBButtonsd is able to dim and recover the display brightness smoothly. Set the value to zero, blending would be disabled. In this case PBButtonsd would work as used to.


With a value greater than null fading will be activated. Fill in the time a full dim (from lowest to highest brightness level or vica versa) should last. PBButtonsd will take into account that some backlight controllers are not as fine grained controlable as others and adjusts its internal timing to fulfill your request as best as possible.


The time value must be given in miliseconds (1/1000th of a second).

LCD_AutoAdjust = mode (default: linear)
KBD_AutoAdjust = mode (default: hysteresis)

Enable automatic LCD brightness and keyboard illumination adjustment and set the mode for the brightness contoller. the brightness level will be automatically adjusted depending on ambient light. Possible modes are:


off No automatic brightness adjustment
linear Linear dependency between ambient light and brightness level (see graph below)
hysteresis Brightness level toggles dependent on ambient light thresholds (see graph below).



lêvel 2 lêvel 2
| o------ | +--<--o-----
| / | | |
| / | | |
|------o |------o-->--+
| 1 | 1
+------ambient-light-> +--------ambient-light->
linear hysteresis


Point one and point two define the characteristic of the controller. Each point is an ambient light/brightness level pair. They could be defined with the AutoadjParm options (see description below). Both points must be given to make the controller work properly.


This option work only on laptops with an ambient light sensor as for eg. the 17" Aluminum PowerBook or the MacBook from Apple. If such a sensor isn't present this option will be ignored. Furthermore not every machine have an illuminated keyboard.

LCD_AutoAdjParm_onBattery = A1, L1, A2, L2 (default: 0%,1%,54%,100%)
LCD_AutoAdjParm_onAC = A1, L1, A2, L2 (default: 0%,1%,94%,100%)
KBD_AutoAdjParm_onBattery = A1, L1, A2, L2 (default: 0%,100%,28%,0%)
KBD_AutoAdjParm_onAC = A1, L1, A2, L2 (default: 0%,100%,28%,0%)

With this options the characteristic of the automatic brightness controller could be changed. Each option has four parameters which all four must be present to be accepted.


Each paramerterset consists out of two ambient light/brightness level pairs called a point (A=Ambient light, L=brightness Level). The meaning of this points depend on the operating mode that was set with AutoadjMode. All parameters must be given in percent (0-100%).


Linear mode
In linear mode the brightness level will be smoothly changed from L1 to L2. The ambient light values set the start- and endpoint of this brightness change. The brightness level will be kept stable if the abmient light is below A1 or above A2.


Hysteresis mode
In hysteresis mode the brigtness level toggles between L1 and L2. The ambient light values A1 and A2 define when this will happen. To prevent fast flickering the threshold changes depending on the curent brightness level. If the backlight is at L1 and the ambient lightbecomes brighter than A2 the brightness level will be switched to L2. If the ambient light level falls below A2 again the brightness level stick to L2. In order to switch the brightness level back to L1 the ambient light level must decrease below A1 (see sketch above).


The behaviour of the automatic brightness controller can be individually defined for the LCD backlight and the keyboard illumination and might also set differently dependent on the power source.


This options could be used to limit the working range of the automatic brightness controller in general or depending on the power source, which is very useful most of the time. It might help to save energy when running on battery.

Use alternative key to increase LCD illumination level.


In conjunction with shift the brightness will be set to maximum level. This second function is statically bound to the modifier shift so that the key definition must not contain shift. It will be ignored, if mentioned.

Use alternative key to decrease LCD illumination level.


In conjunction with shift the brightness will be set to minimum level. This second function is statically bound to the modifier shift so that the key definition mustn't contain shift. It will be ignored, if mentioned.

With this option the initial brightness level of the keyboard illumination on percent could be set. The value becomes active during pbbuttonsds start up phase. Comment this option out if you don't want this behaviour.


This option work only on machines that support keyboard illumination.

If you switched on your keyboard illumination with the foreseen on/off key the keyboard illumination level would switch to 6% by default. With this option you could set a different start value in percent.


This value is only valid during startup because the level will follow all manual and automatic brightness changes during program runtime. So if you set this option to 50% and press the keyboard-illumination-up key twice the on/off key would switch beween 62% and 0 because you manually modified the start value. The same happens if the automatic adjustment algorithm changes the keyboard brightness.
The initial value will only have an effect if automatic keyboard illumination adjustment is disabled.

PBButtonsd is able to dim and recover the keyboard illumination smoothly. Set the value to zero, blending would be disabled.


With a value greater than null fading will be activated. Fill in the time a full dim (from lowest to highest brightness level or vica versa) should last. PBButtonsd will take into account that some backlight controllers might not as fine grained controlable as others and adjusts its internal timing to fulfill your request as best as possible.


The time value must be given in miliseconds (1/1000th of a second).


This option work only on machines that support keyboard illumination.

Use alternative key to increase keyboard illumination level.


In conjunction with shift the brightness will be set to maximum level. This second function is statically bound to the modifier shift so that the key definition must not contain shift. It will be ignored, if mentioned.


This option work only on machines that support keyboard illumination.

Use alternative key to decrease keyboard illumination level.


In conjunction with shift the brightness will be set to minimum level. This second function is statically bound to the modifier shift so that the key definition mustn't contain shift. It will be ignored, if mentioned.


This option work only on machines that support keyboard illumination.

Use alternative key to switch keyboard illumination on/off. Pbbuttonsd tried to remember the brightness level but on some machines the currently set level can't be evaluated so that the keyboard illumination may start with minimum level.


This option work only on machines that support keyboard illumination.

This option defines the framebuffer device to be used for blanking the screen.
In the case only the display should be blanked instead of putting the machine into sleep mode, the framebuffer device could switch the whole display off. If you want that set this option to 'yes'. If not only the backlight will be switched off on blank.


Recent kernel versions will do this automatically because the backlight controller is part of the framebuffer or graphics card driver. If you relialize any problems with the backlight, like the display remains dark after wakeup or cover open, set this option to ´no´.

Normally the display brightness will be dimmed to the lowest possible value if the machine is idle for some time. This will save a lot of power and keep the user able to loom what happened on the screen.


With this option set to yes the display will be dimmed to fully darkness. This was requested by users who want to use this function as simple screensaver.


Please keep in mind that switching the backlight of a laptop to often will decrease its lifetime so the author of pbbuttons doesn't recommend to use this option. Use it at your own risk.

Set the key to switch the external video output on/off. This will only work if the framebuffer device of the used graphics card support this feature. Pbbuttonsd will only send an IOCTL to the framebuffer like m3mirror from Ben Herrenschmidt does.

MODULE MIXER

This module controls a mixer device. This module is able to automatically adapt itself to the underlying sound system. If more than one sound system is available on the computer, the mixer module will automatically decide which is the best to use. Currently two soundsystems are supported:
- Open Sound System (OSS) and
- Advanced Linux Sound Architecture (ALSA).

The mixer module will first probe ALSA and if that fails fall back to OSS.

If a sound module is loaded by the kernel additional hardware might be switched on and power consumption will increase. Especially on mobile computers this is mostly not wanted due to limited battery power.

Pbbuttonsd will postpone the mixer initialization to the first use to prevent the kernel module loading from the beginning. The older versions of pbbuttonsd had an option "MixerInitDelay" to toggle this behaviour. The current version will always postpone the mixer initialization because it changes nothing and makes configuration of pbbuttonsd a bit easier because there is one option less to set.


With the first trigger of a volume hotkey the mixer control will instantly be initialized and is ready to work. If any of the volume hotkeys were pressed without a working sound module, a kernel with the kernel module loader compiled in, would try to load the sound module automatically. If he succeeded, the volume control would work as usual, otherwise pbbuttonsd would try it again next time a volume hotkey is pressed.

With this option the initial volume level could be set. Every time pbbuttonsd was started the volume level would be set to this value. Comment this option out if you did't want that.
If set to 'yes' the speakers would be muted at startup.
Use alternative key to increase volume.


In conjunction with shift the volume will be increased by 10. This second function is statically bound to the modifier shift so that the key definition mustn't contain shift. It will be ignored, if mentioned.

Use alternative key to decrease volume.


In conjunction with shift the volume will be decreased by 10. This second function is statically bound to the modifier shift so that the key definition mustn't contain shift. It will be ignored, if mentioned.

Use alternative key to mute/unmute.

MODULE MIXER OSS

This section contains options only valid if OSS is chosen by the mixer module.

Use an alternative mixer device.


This device is used to control the sound volume or to mute/unmute the sound channels.

This option defines the OSS mixer channels which pbbuttonsd should control. Every combination is valid nevertheless if the combination makes sense or not. Valid channel names are: volume, bass, treble, synth, pcm, speaker, line, mic, cd, imix, altpcm, reclev, igain, ogain, line1, line2, line3, digital1, digital2, digital3, phonein, phoneout, video, radio and monitor.


The first channel in the list is the master, all following are slaves. Only the volume level of the master channel is read back to adjust pbbuttonsd's internal volume reference. Slave channels will be set to master channel's volume on every volume change from pbbuttonsd.

MODULE MIXER ALSA

This section contains options only valid if ALSA is chosen by the mixer module.

Use an alternative sound card.


This card is used to control the sound volume or to mute/unmute the sound channels or elements as they are called from ALSA.

This option defines the ALSA mixer elements (ALSA) which pbbuttonsd should control. Every combination is valid nevertheless if the combination makes sense or not. Valid element names for ALSA could be queried from the program amixer.


The first element in the list is the master (not to confuse with the ALSA element ´Master´), all following are slaves. Only the volume level of the master element is read back to adjust pbbuttonsd's internal volume reference. Slave elements will be set to master element's volume on every volume change.

MODULE CDROM

This module controls a CDROM drive.

Use an alternative cdrom device. The device will be checked but no error would be reported if it did't exist because of a possibly not plugged-in CDROM drive.
Use alternative key to eject a CDROM.
This option sets the delay time used for an additional validity check of the eject key to prevent ejects of the CD by mistake due to small keyboards. The key must be pressed for longer than the given time period to eject the CDROM. The value must be given in milliseconds, for example to set a delay time of 2 seconds set the delay time to 2000. If the given value is zero, the CD-Drive reacts immediatly.

MODULE PMAC

This module contains all the hardware dependent stuff for Apple PowerBooks.

Use an alternative ADB device.


This device is used to read battery status and some other information. It is also used to control the keyboard and trackpad settings.

Use an alternative PMU device.


This device is used to control sleep mode and the backlight device.

Use alternative key to cycle forward through the trackpad operating modes. These modes are: notap, tap, drag, lock. Please see your computer manual to learn what those modes mean and how they work.
Use alternative key to cycle backward through the trackpad operation modes.
If this option was set, the given trackpad mode will be setup during startup otherwise the current mode won't be changed. Following modes are supported: notap, tap, drag and lock.
Usually the trackpad would stay in it's current mode if the keyboard was used. With this option set the trackpad would be configured in ´notap-mode´ as soon as the first key is hit. This will prevent cursor movement through accidently touching the trackpad while typing.


WARNING: It was reported that computers using this option and recent kernels might freeze once and again. The reason is not known yet. Therefore please use this option with care.


This option is only useful if mouseemu is not running. Mouseemu offer this and some more trackpad related functions. Set this option to ´no´, if you have mouseemu running.

If this option was set, the given keyboard mode will be setup during startup otherwise the current mode won't be changed. Following modes are supported: fkeysfirst and fkeyslast.
Setting this option to one of the following values activates some sort of battery data logging.


none disable battery data logging


cycle Pbbuttonsd counts the battery cycles so that it would be possible to estimate batteries lifetime. Usually Li-Ion batteries allow 500 charge/discharge cycles.


log 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 cycle option.

SEE ALSO

pbbuttonsd (1)

AUTHOR

Matthias Grimm.

February 6, 2007