File: pbbuttonsd.1

package info (click to toggle)
pbbuttonsd 0.7.9-5
  • links: PTS
  • area: main
  • in suites: jessie, jessie-kfreebsd
  • size: 2,416 kB
  • ctags: 2,350
  • sloc: ansic: 17,517; sh: 4,626; makefile: 552; yacc: 288; cpp: 203; sed: 16
file content (572 lines) | stat: -rw-r--r-- 23,654 bytes parent folder | download | duplicates (2)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
.\"                              hey, Emacs:   -*- nroff -*-
.\" pbbuttons 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.
.\"
.TH PBBUTTONSD 1 "September 30, 2006"
.\" Please update the above date whenever this man page is modified.
.\"
.\" Some roff macros, for reference:
.\" .nh        disable hyphenation
.\" .hy        enable hyphenation
.\" .ad l      left justify
.\" .ad b      justify to both left and right margins (default)
.\" .nf        disable filling
.\" .fi        enable filling
.\" .br        insert line break
.\" .sp <n>    insert n+1 empty lines
.\" for manpage-specific macros, see man(7)
.SH NAME
pbbuttonsd \- daemon to support Laptop specific functions
.SH SYNOPSIS
.B pbbuttonsd
.RI [ options ]
.SH DESCRIPTION
.ad b
\fBPBButtonsd\fP 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.
.PP
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.
.PP
Supported features:
.PP
Advanced Power Management:
.ad l
.in +2
.ti -2
\- puts the machine to sleep if idle to save energy,
.ti -2
\- prevent the machine from entering sleep mode if CPU
or Net is busy until the job is finished,
.ti -2
\- send a warning if battery is running low,
.ti -2
\- configurable emergency actions if battery is critically low,
.ti -2
\- dims the display if user is passive to save energy
.ti -2
\- puts machine to sleep if cover was closed,
.ti -2
\- executes external scripts on certain power management events
to allow most flexibility,
.ti -2
\- is able to replace power management daemons like pmud, apmd, etc.
.PP
Support for laptop dependent hotkeys:
.in +2
.ti -2
\- to adjust display brightness
.ti -2
\- to adjust keyboard illumination,
.ti -2
\- to adjust the sound volume,
.ti -2
\- to mute/unmute the sound channels,
.ti -2
\- to open/close the CDROM tray,
.ti -2
\- to trigger sleep mode.
.ti -2
\- to switch external video on/off
.PP
Support for laptop dependent specialities:
.in +2
.ti -2
\- initializes trackpad and keyboard mode during startup,
.ti -2
\- disables trackpad's mouse click emulation while typing on the keyboard
.ti -2
\- keeps keyboard settings during sleep mode,
.ti -2
\- cycles through the trackpad operating mode via hotkeys,
.ti -2
\- supports PowerBook's ambient light sensor and automatic
adjustment of LCD and keyboard brightness.
.SH USER INTERFACE
.ad b
The main input to \fBPBButtonsd\fP 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:
.PP
.nf
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).

TPModeDownKey    \-\-       Cycle trackpad mode backward (lock, drag,
                          tap or notap).
.fi
.PP
.ad b
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.conf (5) to figure out what
you could expect.
.PP
.SH COMMANDS AND SIGNALS
\fBPBButtonsd\fP 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:
.PP
.ad c
pbbcmd <command>
.PP
.ad l
Following commands are understood:
.PP
.in +15
.ti -15
SAVECONFIG     saves the configuration if enabled by pbbuttonsd's
security checks (see 'configuration file' section below) and you
have the right permission.
.br
.ti -15
EJECTCD        unmount and ejects the CDROM or closes the tray
again, if already open.
.br
.ti -15
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.
.br
.ti -15
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/.
.br
.ti -15
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.
.PP
Beside the IPC interface pbbuttonsd understands some signals:
.PP
.in +12
.ti -12
SIGHUP   1  pbbuttonsd reloads its configuration and scans for
input devices (see 'connecting/disconnecting new keyboards'
section below).
.br
.ti -12
SIGINT   2  usually emitted by CTRL-C. pbbuttonsd will clean up used
resources and terminates
.ti -12
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 ;-)
.ti -12
SIGTERM 15  pbbuttonsd will clean up its resources and terminates
.PP
.SH KERNEL CONFIGURATION
.ad b
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
\fBPBButtonsd\fP to get the necessary information.
.PP
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.
.PP
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":
.PP
.in +4
.ti -4
.B "Backlight control for LCD screens"
.br
.RI ( CONF_PMU_BACKLIGHT )
.PP
.in +4
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.
.PP
.in +4
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 \fBYES\fP to this option.
.PP
.in +4
.ti -4
.B "Provide legacy ioctl's on /dev/pmu for the backlight"
.br
.RI ( CONF_PMU_BACKLIGHT_LEGACY )
.PP
.in +4
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.
.PP
.in +4
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.
.PP
.in +4
This mixture of related but independent functions make it necessary to say
\fBYES\fP to this option as well until the Kernel guys cleaned up this mess.
.PP
Finally your Kernel 2.6.18 configuration should look like this:
.PP
.ad l
.in +4
[*] \fBB\fPacklight control for LCD screens
.br
.in +6
[*] \fBP\fProvide legacy ioctl's on /dev/pmu for the backlight
.ad b
.PP
\fBPBButtonsd\fP will then automatically detect the best suited interface
and use it.
.SH 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.
.PP
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.
.PP
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.
.PP
.SH POWER POLICIES
Since version 0.6 \fBPBButtonsd\fP 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'.
.PP
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'.
.PP
The pmcs script is responsible to put the set policy into practice.
\fBPBButtonsd\fP will call this script among others every time the
policy changes or has to be reset after periods of sleep or suspend.
.PP
.SH PBButtonsd AND SLEEP MODE (Suspend to RAM)
\fBPBButtonsd\fP 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.
.PP
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.
\fBPBButtonsd\fP would support that via its Power Management Control
Scripts (see /etc/power/).
.PP
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:
.PP
.ad l
.in +2
.ti -2
\- trigger a key on the keyboard
.ti -2
\- open the cover (closing the cover doesn't wake up the machine)
.ti -2
\- insert or remove an USB device
.ti -2
\- timer
.ti -2
\- other computers address the sleeping computer via LAN
.ad b
.PP
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.
.PP
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:
.br
.ad c
echo > "lid_wakeup=0" > /proc/pmu/options
.br
.ad b
.PP
And the following command enable the wake up on "cover open" again:
.br
.ad c
echo > "lid_wakeup=1" > /proc/pmu/options
.br
.ad b
.PP
Other wake up options are not foreseen by the kernel but may be added in the
future. \fBPBButtonsd\fP is completely out of control until the kernel has 
finished its wake up procedure and gives control back to user space.

.SH 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.
.PP
If IBaM is compiled into \fBpbbuttonsd\fP all internal time calculations
based on kernel battery information would be replaced. Through the IPC
signal TimeRemaining \fBpbbuttonsd\fP clients could benefit from accurate
time estimations too.
.PP
Once started \fBPbbuttonsd\fP will collect battery data and saves
them to disk for statistical analysis. The more data \fBpbbuttonsd\fP
have to analyse the more accurate the time estimations will be.
.PP
Because at the very beginning \fBpbbuttonsd\fP has no data to analyse
it is recommended to perform the initial procedure described below to fill
the database with real data. If \fBpbbuttonsd\fP 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.
.SH IBaM INITIAL PROCEDURE
This step is not necessary if you only update \fBPBButtonsd\fP. The
updated version will continue to use the existing data.
.PP
At the very beginnig \fBpbbuttonsd\fP 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 \fBpbbuttonsd\fP
with integrated IBaM to initially fill the database with real data.
.PP
Unplug AC power from your laptop. IBaM will now save the time intervals
between changes in battery status. \fBPBButtonsd\fP 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.
.PP
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 \fBpbbuttonsd\fP triggers sleep or the
hardware switch off hardly, prepare for the second case to prevent data
losses).
.PP
After your battery is completely drained, plug in your AC connector and
continue working as usual.
.PP
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.
.PP
The database is updated continously so that any aging of the battery is taken
into account. When \fBpbbuttons\fP tells you now, you still have 10 minutes
left on battery, then you \fBwill\fP have 10 minutes left even if your
battery is growing old and the capacity decreases.
.SH 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).
.PP
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.
.PP
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, \fBpbbuttonsd\fP 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.
.PP
IBaM works best if you use always the same battery configuration (one or two
batteries).
.SH CONFIGURATION FILE
\fBPBButtonsd\fP uses a configuration file for setting up all it's features.
This file is usually located in \fIetc\fP. From version 0.5.4 on
\fBPBButtonsd\fP is also able to write the current configuration to a file.
.PP
To make this solution as secure as possible a batch of security checks
will be performed until configuration writing would be allowed:
.PP
.ad l
.in +3
.ti -3
1. The owner of the writable configuration file must be the same as
the owner of pbbuttonsd process.
.ti -3
2. The configuration file is only writable by the owner.
.ad b
.PP
If any of this conditions failed, writing of the configuration file would
be disabled.
.PP
.SH CONNECTING / DISCONNECTING NEW INPUT DEVICES
\fBPBButtonsd\fP 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. \fBPBButtonsd\fP scanns those devices at start time and
work with the found devices.
.PP
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.
.PP
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:
.PP
.ad c
kill \-HUP \`cat /var/run/pbbuttonsd.pid\`
.PP
.ad b
Be aware that the configuration file will also be reloaded in this case.
.PP
.SH OPTIONS
\fBPBButtonsd\fP accepts the following options:
.TP
\fB\-c\fR, \fB\-\-configfile\fR=\fICONFIGFILE\fR
Use an alternative configuration file, default is /etc/pbbuttonsd.conf.
.TP
.B \-h, \-\-help
Show summary of options.
.TP
.B \-v, \-\-version
Show version of \fBPBButtonsd\fP.
.TP
.B \-q, \-\-quiet
Suppress the welcome message. Some startup scripts want to have full
control about their output.
.TP
\fB\-d\fR, \fB\-\-detach\fR[=\fIPIDFILE\fR]
Start \fBPBButtonsd\fP as background process. optional an alternative
pidfile. The daemon writes it's pid into this file.
.br
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.
.TP
.in +7
If you don't use this flag and start \fBPBButtonsd\fP 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
\fBPBButtonsd\fP may be stopped by the shell because of using
invalid file descriptors.

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

.SH AUTHOR
Matthias Grimm.