
README
======
GKrellm-PMU creates a battery display for Apple Powerbook
without using APM frontends, which tend to be less verbose.

    This is Gkrellm-PMU Version 2.x (The reincarnation)

The original Gkrellm-PMU Plugin was written by Joseph Palani
Garcia. The last version he published was version 1.4 in 2001.
Unfortunately it seemed that he stopped development and did't
ported Gkrellm-PMU to Gkrellm 2.0 and GTK+ 2.0. Because I used
Gkrellm-PMU for a long time and wanted to use it further on,
I took the source and updated and cleaned it up to be up to
the mark.

The originally source was difficult to understand for me.
The first try to port it to Gkrellm 2 according the gkrellm
plugin porting guide failed. I can't find the cause so I
choose the easier way to reimplement it from scratch using
the original source as guide. Some of the changes are:
- Gkrellm-PMU doesn't use pmud anymore. It get its input
  only from the kernel through /proc/pmu.
- The APM support was removed because gkrellm has a built-in
  APM-plugin
- The direct reading of the pmu was removed because do it
  through the kernel is the better way. As result the new
  Gkrellm-PMU plugin needs Kernel 2.4 or later and only
  supports data exported to /proc/pmu/*.

Traditionally the kernel has problems to track battery status,
if the batteries are completely removed (for eg. possible on
Pismo). In this case /proc/pmu/* reports still a battery in 
system but the parameters are not valid anymore.

To improve this situation and to display always the correct
battery states, gkrellm-pmu version 2.3 got support for
PBButtonsd which is able to provide the correct information.
Gkrellm-PMU will autodetect PBButtons at startup. If PBButtonsd
was not available or PBButtonsd support was not compiled in,
gkrellm-PMU would use /proc/pmu as usual. Gkrellm-PMU will work 
anyway.


REQUIREMENTS
============
To use this programe, you need some additional parts:
1. an Apple Laptop or Notebook
2. the GTK and GLib libraries version 2.0 or later,
3. A kernel 2.4 or later with /proc/pmu support.
4. Gkrellm Version 2 or later.
5. Optional: PBButtonsd 0.6.5 or later for best performance
             but will also compile with older versions
6. Optional: PBButtonsd 0.7.3 or later for accurate discharge
             time predictions from IBaM. This includes advantages
             from point 5.
7. Optional: PBButtonsd 0.7.4 or later for accurate charge and
             discharge time predictions from IBaM. This includes
             advantages from point 5 and 6.

COMPILE & INSTALL
=================
For details about compiling and installing of gkrellm-pmu
please see INSTALL.

The configure script autodetects if pbbuttonsd is installed and
automatically include pbbuttonsd support. It is save to compile
always with pbbuttonsd support because Gkrellm-PMU looks for
pbbuttonsd also at startup and disables the extension if it is
not found.

There is no configure command line switch to generally disable
pbbuttond support. You need to remove the libpbb include files
to achive this.


INTERFACE DESCRIPTION
=====================
On the left is a battery panel similar to those used in the
control strip. The battery symbol will change color and fill
grade by current charge. The percent value is also shown in
detail using a analogue meter.

Possible symbols could occur:
  Green and full gauche       - 100%
  Green and 80% gauche        - 20-99%
  Yellow and half gauche      - 1-20%
  Red and nearly empty gauche - < 1%
  transparent                 - not installed

Also, additional icons are shown for status:
  Bolt - charging
  Plug - plugged in (and not charging)
  +/-  - in use

Beside this symbols more verbose status information is shown.
Clicking on them with the left mouse button will cycle through
different values. The settings are saved on exit.
  Time Remaining (-:-- when inactive)
  Total Percent remaining
  Total Draw in mA. (negative is in use, positive is charging)
  Total Voltage (in volts)

The values will be displayed indipendently for each battery
unless. the option 'sum_batteries' is set.

If IBaM is enabled, the time remaining will automatically
replaced by the value delivered by PBButtonsd. Currently IBaM
can't handle multiple batteries seperatly, so that this option
is only available if 'sum_batteries' has been activated.

With IBaM enabled GKrellm-PMU always shows the remaining time
on battery even if the battery are charging. If battery charging
is in progress the showed time is equivalent to that time the
computer would run on battery if the charging process was
interrupted now. If you want to see the time until the batteries
are fully recharged here, set the option 'Show Charge Time'.

A click on the panel with the right mouse button will open the
config window. A click with the middle mouse button will expand
display to reveal a battery load meter. Useful to visually
understand relative changes.

A right-click on the chart opens the chart config window to adjust
various parameters of the chart. The settings will be saved.

A click with any other mouse button will hide the chart again.
This plugin can be themed. See the included 'Theming' file.


CONFIGURABLE OPTIONS
====================
[Show Charge Time]
If this is set, the time display shows time remaining when
charging rather than remaining inactive. For those really
impatient people who absolutely must know.

[Show Batt NA]
If the computer supports mores than one battery and this option
is set all batteries will be shown in the panel even one ore more
are not available at the moment.

[Sum Batteries]
With this option set all batteries in the system will be summed
up and will be shown as one single battery.

[Use IBaM]
With this option set the charge and discharge time values will be
queried from PBButtonsd, instead of reading /proc/pmu/battery*.
PBButtonsd uses IBaM for calculating much more accurate time
estimations than /proc/pmu/battery*.


LEGAL NOTICE
============
This program 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.


CREDITS
=======
Thanks to Joseph Palani Garcia <jpgarcia@execpc.com> for his
wonderfull program.

  Enjoy
    Matthias Grimm


