Full Screen Battery Status -- a battery monitor for Palm OS(R)
Philip Boulain <lionsphil@dsl.pipex.com> http://www.cattsoft.co.uk/
===================================================================

About
-----
The title says pretty much all there is to say, really. This is a battery
status display. You may ask "why bother when there's one on the launcher?"
Well, FSBS has a few advantages:
 * It gives a large bar and percentage readout, so you can tell how much
   charge you have left with a little more precision.
 * Unlike the launcher's bar, it won't turn into a useless lightning bolt
   when charging, so you can see how far from fully charged you are.
 * It tries to estimate how long your battery will last. Unfortunately,
   it can only tell this from samples it takes while running, so I don't
   claim that it does a very good job of it.
And, finally, I wanted something simple to start with when learning how to
program my Palm. ;)

Requirements
------------
Palm OS 3.0 or higher is strongly reccommended. You _might_ get it running
on Palm OS 2.0 if you compile a custom version (see below), but the 2.0
API doesn't give percentage charge information, so FSBS has to guess.

I've tested FSBS successfully on the Palm emulator running OS 3.5, a real
Palm Vx running OS 3.5, and the Palm simulator running 5.4. It only needs
the lowest resolution and a monochrome display.

Installation / Usage / Removal 
------------------------------
To install FSBS, just drop the PRC file in palmOne Quick Install and HotSync.
To run it, tap "Battery" in the launcher -- it should be in the "Utilities"
category. FSBS only displays information, so there are no commands.
The estimated time is displayed as days:hours:minutes.
You can remove FSBS using the normal "Delete..." option from the launcher
menu.

Problems
--------
Problem : The estimated time display is blank.
Cause   : FSBS hasn't had time to gather enough information to make an
          estimation.
Solution: Leave FSBS running until an estimate appears. If your Palm
          powers itself off first...congratulations -- you bought a handheld
          with a battery life so good that I can't measure it discharging. ;)

Problem : The estimate used to appear, but it's gone blank again.
Cause   : 1) You've started/stopped charging your Palm.
             FSBS keeps different statistics for charging and discharging,
             so it may be able to make estimates for one but not the other.
          2) The statistics have been deleted.
             FSBS's statistics are stored in your Palm's memory, and are
             not archived when you HotSync because they're not important
             user information. If you hard reset your Palm, or delete FSBS,
             they will be lost. FSBS also discards its statistics if it can't
             read them, possibly because you changed versions.
Solution: As above. Just let FSBS gather new statistics.

Problem : No gauge displays, and/or some readings say things like 'mem'.
Cause   : Your Palm is seriously low on memory.
Solution: Erm, pass. FSBS only needs a few bytes, so I expect that other
          applications are likewise unhappy. Try a soft reset (?).

Problem : "Unknown battery type" appears.
Cause   : Your Palm indicated that it has a battery type that FSBS doesn't
          recognise.
Solution: Mail me and tell me what on Earth you're running it on. ;)
          FSBS supports all the power sources listed in the Palm API
          documentation (including anti-matter!)
          Otherwise, this is safe to ignore.

Known bugs
----------
There are no known serious bugs in FSBS, other than that the estimation
is pretty poor. It shouldn't leak memory, crash, or anything like that.
Bad Things *might* happen if you try to run it on a Palm OS 1 device.
It's also easily confused by Palms where the battery charge *falls* while
plugged in, or rises while not, and will make the estimate less accurate.
It happens, suprisingly...

Compiling
---------
All the files in the archive which aren't the PRC are an Eclipse project,
for the incredibly nifty Palm OS Developer Suite. If you're using that,
you should be able to just build the Release target. If not, ignore the
autogenerated makefile and just compile the contents of src/ and rsc/
into a Palm program using gcc and prc-tools.

There are a few things you might want to poke if you're making a
custom install:
  Disable experimental 'thick' digits
Change EXPERIMENTAL_FAT_DIGITS in src/Digital.c to be undefined to disable
'fatter' digits in the percentage and estimated time displays. They're
a little prettier and easier to read from a distance, and no longer have
the CPU (and thus battery!) penalty of flickery redraw of 1.0, but are
still somewhat experimental.
Do this if you have a 1.5x device (one that runs at a resolution of
240xsomething), or you'll get ugly gaps in the segments. =/

  Possible Palm OS 2.0 support
Near the top of src/BatteryStatus.h, change USE_SYSBATTERYINFO_V2 to be
defined, and fill in the voltages for your battery. FSBS will work out
a percentage from the voltage.

  Polling rate
Change UpdateTimeSeconds near the top of src/AppMain.c to change how often
FSBS measures the battery charge. Smaller values will result in greater
accuracy, but less sleep time for your Palm (and thus ever so slightly
greater battery drain). The minimum value is one second.

  Smaller binary
If you're compiling for just your handheld, modify rsc/AppResources.xrd
(possibly using the Palm OS Resource Editor in the Developer Suite) to
remove application icons not needed for your display mode.

If you make any fixes or improvements to the code, send them to me at
lionsphil@dsl.pipex.com! =)

Licence / legal
---------------
Battery Status is Free Software, licensed under the GNU GPL. Here's the
standard boilerplate stuff for it:

 Fullscreen Battery Status -- a battery monitor for Palm OS(R)
 Copyright (C) 2005 Philip Boulain

 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; if not, write to the Free Software
 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA

Palm OS and HotSync are trademarks of PalmSource, Inc. or its affiliates.