===================================================
VoltageCalib HACK - v1.2 - 3/29/2000, Peter Strobel
===================================================

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
WARNING: Please read that dokumentation carefully. VoltageCalib is a safe app,
as long as you use it right. But patching wrong values can cause data loss,
since your Pilot won't 'know' the right battery voltage anymore.
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!


CONTENTS:
=========

 1. WHAT'S VOLTAGE CALIB?
 2. INSTALLATION
 3. HOW CAN CONFIGURE VOLTAGE CALIB?
 4. RELEASE HISTORY AND UPDATES
 5. WHAT'S COOKING
 6. HOW TO CONTACT ME
 7. DISCLAIMER




1. WHAT'S VOLTAGE CALIB?
------------------------

When I was writing VoltageControl, BatteryMonitor etc., I already found out,
that the internal voltage meassurement of the Pilot is not the most accurate
one. So I decided to create VoltageCalib, a little hack that corrects the
result of the analog-to-digital conversion process and feeds it to the rest of
the routines that look for the battery voltage.
That means, all apps, hacks and the warning levels are using the corrected
voltage (I doubt that any program goes deeper than VCalib <g>). Did you ever
wonder why you can use 'empty' Pilot batteries still in your walkman for a
while? Well, that's because they weren't empty in fact. All my three Pilots
are reading a too low voltage without correction, up to 0.1 to 0.15 V. Now,
given that the Pilot is using only 2 cells, that's alot of juice left, even if
your Pilot is telling you they're empty!

Anyway, even if my Pilots are all nearly equally off, I understand not all
might be equal, so you can configure VoltageCalib for your needs. To be more
specific, VoltageCalib can correct the readout between -0.4V and +0.4V . No
Pilot should be more off than that and if, it's probably a matter for the 3Com
repair service. Since I still hate bloated apps, I wrote again an external
patch utility to configure VoltageCalib. That way, I could keep the app to
the little size of exactly 874 Bytes and you have to setup the calibration
factor anyway only once!
I know, not all of you use a PC, but I tried to keep the patch utility as
simple as possible, it's a non-graphical DOS application that should run also
on any DOS emulation (I'm sorry, I'm not a MAC guy - but isn't there something
like a DOS-box on nearly all platforms?). More about VCAL.EXE later ...

VoltageCalib is compatible with 'nearly' all OS versions. I tested v1.2
for a long time, but couldn't get it to work on OS 3.3 - I truly assume a
very strange bug in the battery routines of OS 3.3! I didn't care longer,
since it works perfectly under OS 3.5 and it'll be available to the public
in May 2000 anyway.


ATTENTION: VCAL also works on the Palm V(x) or the Palm IIIc. Apart from the
fact, that it's not so easy to verify the true voltage of their LiIon cell,
it can be dangerous to mess around with the voltage readout on these devices!
Let's assume you set VCAL to correct for +0.3 or more volt, than there won't
be any warning before your battery is empty. The OS would still read good
3.9V (nearly full LiIon), while the voltage is indeed down to 3.6 (nearly
empty). It'll never warn you. On the other hand, you can set the calibration
to -0.1V and so get a much earlier warning than usual.




2. INSTALLATION
---------------

VoltageCalib is a Hackmaster extension ... therefore ...

----------------------------------------------------------------------------
... we will be back after these short messages ...

To use VoltageCalib, you need to run Ed Keyes HackMaster on your Pilot. Look
for the latest version of HackMaster on http://www.daggerware.com.
Because of questions I got from users, I want to point out once more: I have
nothing to do with HackMaster. HackMaster is a program, that allows system
extensions/replacements like VoltageCalib to reside in 'peace' amongst others
of its kind on the Pilot. If you want to know more about HackMaster, please
check Ed's pages. There you'll find also the HackMaster API, in case you want
to write your own hack.

PLEASE NOTE: Hackmaster is a great piece of software, and the farsight of Ed
============ made it possible, that the Pilot community can enjoy alot of
             great system extensions, Palm (USR, 3Com, whoever) missed to
             implement. PLEASE REGISTER HACKMASTER IF YOU USE IT !

ATTENTION:   A hack *MUST BE DISABLED* before you can delete it safely from
==========   your Pilot! I still get angry e-mails from people, who had bad
             crashes. I'm sorry, there is nothing a hack programmer can do.
             This is just a Hackmaster rule.

TRG-USER:    Note that it's not yet possible to run a hack in Flash. My
=========    best experience is, to keep Hackmaster and all hacks in RAM.
             Rumors are saying that Ed's working on an update for that.

... and now for something completely different ...
----------------------------------------------------------------------------

After you hotsynced VoltageCalib the usual way with your desktop app, go to
Hackmaster and activate the VoltageCalib Hack. That's it!

Originally VCal comes with a correction offset of +0.077V, that's a good
average to start with.
PLEASE NOTE: Due to an averaging process the OS does when reading out the
             battery voltage, it takes a while after you activated the hack
             until the readout stabilizes to the new, corrected value!




3. HOW CAN CONFIGURE VOLTAGE CALIB?
-----------------------------------

The biggest problem for the 'non-technician' user is, to find out what offset
is necessary. Sorry, I can't help you with that one. Best is of course, if you
have a friend that has a voltmeter to check the battery voltage directly at the
battery terminals while you look at your voltage readout on your Pilot and
you'll see how much the voltage is off.
If you have no possibility to check the battery voltage externally, you can try
check the voltage when you just inserted new batteries. Fresh Alkalines (I
checked Duracell and Energizer) have all relativ exactly 1.56V, so you should
get a readout of 3.12V. Try to avoid big activities or backlight when you read
the voltage - that'll cause a drop of the voltage due to the load.

All technicians - just meassure the battery voltage and compare it with the
Pilot display. It's basically better, if you meassure it when the voltage is
more towards 2V than 3V. If there are any non-linear errors over the range, you
have the maximum accuracy at the interesting values - that's when the battery
life comes towards its end.

To patch the existing VCAL.PRC file, just keep it together with VCAL.EXE in one
directory and call VCAL.EXE with the offset you want to patch. That is, if your
readout is let's say 0.1V too low, call VCAL 0.1 . If it's too high, you can
call VCAL with a negativ value. After the patch, hotsync the changed VCAL.PRC.
PLEASE --- DON'T FORGET TO DISABLE AN EVENTUALLY ALREADY INSTALLED VCAL IN
HACKMASTER FIRST !!!
Update in v1.1: Call VCAL.EXE without a correction parameter, if you want to
                know the current setting of the VCAL.PRC file.  

FYI: The resolution of the A/D converter is 78 steps per volt, that means that
     not every offset is possible, but steps of roughly 0.0128V. You don't have
     to worry about that, the patch program chooses the closest possible value
     and tells you that actual value.

In the [i]nfo screen of the hack you can always look up the actual offset the
hack is producing, this value is also patched.




4. Release history and updates
------------------------------

v1.0   	- Initial release of VoltageCalib.
	  (05/06/98)

v1.1 	- Fixed a bug in the patch utility that showed only with a
	  patch value of 0.09V.
	- Added read-only mode for the path utility. 
	- The hack file was only corrected to match with the patch
          utility version and for an e-mail correction in the [i]nfo
	  screen.
	  (08/29/98)
v1.2    - update for OS 3.5



5. WHAT'S COOKING
-----------------

- Well, you never know what's coming. I realized, that the internal A/D (more
  likely the curcuitry around it) shows also a slight unlinearity. That means,
  if the result is correct at i.e. 3.0V it's off again at 2.0V ... maybe I
  expand VCalib to take care of that too, if I can find a rule behind it.




6. HOW TO CONTACT ME
--------------------

Well, VoltageCalib is freeware, so no need to register. But if you'd like to
see more of my software, just visit my site at

          http://www.pspilot.de


If you have suggestions, likes, dislikes, found bugs etc., feel free to e-mail
me at:
          PSPilot@pstec.de




=====================================================
7. Now for the unavoidable disclaimer and legal stuff
=====================================================

VoltageCalib and it's patch app are freeware. But if you're an author of little
apps, it would be nice to send me a copy of your software if you like mine :)

You may give a copy of VCAL.ZIP to others under the same terms, but make
sure to keep always all files in the archive. VCAL.ZIP may be included on
any disk or CDROM of shareware sold by non-profit organizations. If you want
to include it in a commercial software collection, please contact me.

I took great care to release VoltageCalib bugfree, and in the moment there
are no known bugs. However, VoltageCalib is provided without warranty of
any kind, express or implied. I can accept no liability for data loss or any
other problems caused directly or indirectly by the use of VoltageCalib.

VoltageCalib and the patch app are copyright 1998 by Peter Strobel.



(c)Peter Strobel - 1998, 6th May