HPTalx README
-------------

HPTalx copyright (c) 1999, 2000 by Bruno Barberi Gnecco.

This is HPTalx, a HP<->PC communications program for Linux, written by
Bruno Barberi Gnecco and released under GNU Public License; see the GPL
file. Use it at your own risk; the author is not responsible for any damage 
from its use or misuse.

You can get the latest version of HPTalx at

http://www.geocities.com/RodeoDrive/1980/hptalx.html


DEVELOPMENT RELEASE
-------------------

This is a development release. Do not expect full functionality, and expect
bugs. Patches and bug reports are *more* than welcome, please email me:
brunobg@geocities.com. I'm looing for someone that worked with XModem, so
if you did, please contact.

As of 1.1.0, you should expect the functionality of the stable release,
but not anything else (XModem DO NOT WORK).


REQUIREMENTS
------------

HPTalx uses Kermit. You can get Kermit at:

http://www.columbia.edu/kermit/

You must be running CKermit 7.0. Tests were made with 7.0 Beta 11. kermit
binary must be in PATH. You don't need CKermit if you intend to use Xmodem
protocols.

To compile HPTalx, you need GTK+ libraries. I'm not sure, but I think
GTK+1.0 will not work. I'm running 1.2.6. You can get them at

http://www.gtk.org

If you want to use XModem or the ROM upload, you need stty (part of the 
sh-utils GNU package, get it at your closest GNU repository); versions 1.6
and 2.0 are OK. You also need the lrzsz package; version 0.11 didn't work 
properly here, but you may give it a try; since it's quite old, the best is
to upgrade to 0.12.20, which I tested successfully: 

http://www.ohse.de

stty, lsx and lrx must be in PATH. Note that HPTalx will run without them,
only unable to do ROM uploads and without xmodem support.

I don't see a reason to need kernel 2.2.x, but I didn't test in 2.0.x.
You should upgrade, anyway! 

As of version 1.0, HPTalx started to use pseudo terminals instead of pipes.
This means that you must have libutils installed in your system. This library
is supposed to come with libc, but I'm not sure it does with libc5. 

Now you know why HPTalx is so small! :)


COMPILING AND INSTALLING
------------------------

Just type make and it will compile. If you don't own a HP49 or are not
interested in ROM updates, uncomment UPDATE_ROM in the Makefile. The
program will still be able to connect with 49s, but will not be able to
update its ROM. This will cut the program size (anyway, HPTalx size after
compilation and striping is 50k, so it doesn't hurt that much!).

To install, type make install. The default install directory is /usr/local/bin.
You can change it editing Makefile.


CREDITS
-------

I'd like to thank to people from C-Kermit. They were very kind with me,
patiently answering all my questions. 

I also got some answers from comp.sys.hp48, thanks a lot, and thanks to
everyone that emailed me -- you may be credited more specifically elsewhere,
but specially to Karsten Mauler, for insisting that his bug really existed
(and proving it, and pointing many more), and keep trying my patches everyday
for many days, in a faint hope to not see kermit's prompt again. 

Thanks for M Bunte for the upgrade code, and for Cyrille de Brbisson for 
the XModem server commands.

Last, but not least, thanks to all the people that emailed me with suggestions
and complaints.


MISCELLANEOUS
-------------

If you can run Kermit/sx/rx, then you have all necessary permissions for 
HPTalx.

It's not a security breach more than Kermit/sx/rx: it can work as a little 
file manager too (copy, delete, etc), and it may open any /dev/ttyS? device.
It also can run other programs, and create files/directories. Although it's
least likely that an authorized user running it will result in a decrease of
security, it should NOT be run by untrusted users. Versions > 1.0.1 do not use
kermit to do file operations (such as listing, copying, etc). As always, you 
should not run it as root, to avoid (your own:) mistakes. 

HP48SX is not supported (thanks to Tom Napolitano to let me know about
it). Problems are (at least): it doesn't have a VERSION command and its
kermit server doesn't support DIR. I don't have a SX, so if you do please
help. HP just released HPs 39 and 40, which are still untested and may or
may not work; comments are apreciated.


DOCUMENTATION
-------------

HPTalx is basically a GUI frontend to protocols, but not just that. You can 
also upgrade your ROM (49), use it as a file manager, and much more.

What it used to do until 1.0 was the usual pipe stuff: fork, execute kermit,
redirect stdin/out of both processes one to the other, and work as a frontend.
This had several limitations, because kermit can detect if you are in a 
terminal or not and will behave differently; so, following advice from C-Kermit
support, I changed pipes to pseudo terminals. 

Version 2.0 supports XModem too, interfaced by the rx/sx programs. I was hoping
that doing it was a simple, small patch, but I eventually reviewed the whole 
program, since it was becoming a real mess. I hope it's legible again (mental
note: do not add a major feature without doing the same level of design you
did when you started the code).

ROM upgrade is done using Mathias Bunte's upgrade, which is released under GPL
and modified to fit my needs.

See Changes.


TROUBLESHOOTING
---------------
T: Some things do not work!
A: THIS IS A DEVELOPMENT RELEASE. They really may not work.

T: My transfer rate decreases during download!
T: Why is the transfer rate so slow?
A: Blame HP. Data received is put in the stack; as it becomes bigger and bigger,
the manipulation gets slower. This doesn't happen with XModem.

T: I can't upload my ROM! XModem doesn't work!
A: Did you select the .flash file? If you didn't, HPTalx can't find it. 

When you upload the ROM, the program opens the same port used by kermit. This
doesn't seem to be a problem, as HPTalx is frozen and kermit doesn't lock
the port. In the tests I performed everything went alright, but if you
have problems with ROM upgrade chances are the problem is here. 

Martin Hansen wrote to me, saying that he could only make things work when
he set the group id to uucp. This was caused because kermit wasn't allowed
to write to /var/lock. 

Is lsx/lrx in the PATH? Check it.

T: HPTalx says "Unknown calculator".
A: Occasionally the program refuses to connect with the calculator. Your
mileage may vary, and this is a bug that I couldn't fix totally yet. It is 
caused because I couldn't find a guaranteed way to be sure that the HP is 
ready during connection: a lot of commands are sent to the HP, and the reply
may take any amount of time.

I've been trying to fix it by adding some delays, but as things are 
asynchronous, it's hard to say that it'll always work.

You probably aren't interested in why it doesn't work; then, as a good computer
programmer, I can only say: "Try again". :) Well, if the stack is clean things
are more likely to work, too.

XModem server doesn't have this problem.

T: HPTalx freezes after "Transfering files".
A: Does the file you are uploading has a space or an hyphen? CKermit doesn't
work with these symbols; see the question below. Rename the file and try
again, or use the xmodem server.

T: CRASH?
A: Versions previous to 1.0.1 had a bug (which is not my fault) that caused
HPTalx to crash after some directory browsing in the PC. It's fixed. Another
problem: you can't change to a directory whose name contains a space; this is a 
kermit limitation (bug?).

As always please report any bugs and suggestions to brunobg@geocities.com.
