HP-Kermit: HP48 Kermit Interface v1.0beta
Copyright 1997 by Matthew Mastracci
All Right Reserved

Introduction
------------

I've been planning on creating a Win '95 Explorer extension that would allow
you to explore and share your HP like it were a regular drive.  The problem 
was that I needed a way of getting the data (directories, file names, stack) 
from the calculator, without taking up too much memory.  

Until Jarno Peschier mentioned it, I didn't even realise that the HP's Kermit 
server could do all the things I wanted it to.  Before I go head-first into
implementing a Windows Kermit-based Explorer extension, I had to make sure I
got the Kermit parts right.  That's where this program comes in.  :)

Setup    
-----

1.  Edit the KERMIT.CFG file with your serial port.
2.  Ensure that the HP is sending via wire at 9600, parity none 
    (right-shift-1/Transfer).
3.  Use right-shift-right-arrow at the stack on your HP to start the server
    (or use the command "SERVER").
4.  Type KERMIT to start the client on your PC.
5.  Use the KERMIT /T option to test your HP<->PC link (if KERMIT doesn't 
    work).

That's it!

Note: If the program halts when you run the first command (and ESC doesn't 
clear it), your serial port setting is wrong.  Hit Ctrl-C to kill the 
program.  Check the KERMIT.CFG file and try it again.

Commands
--------

Entering commands in HP-Kermit is quite easy.  Each of the commands has a 
one-letter abbreviation as follows:

Command        Description
--------------------------------------------------
A              About the program
B              Send break to server (abort)
C [directory]  Change working directory
D              Get listing for current directory
E [command]    Execute a command on the server
L [filename]   Start/stop logging to file
R [files]      Retrieve files from the server
S [files]      Send files to the server
Q              Quit the program, shutting down the server
ESC            Quit without shutting down the server
!              Toggles debugging mode on and off

A: About

Displays a short message about the program and outputs some of your current
setup.

B: Break

Sends a break packet to the server if it somehow gets stuck in a transfer.

C: Change directory

Allows you to traverse the directory tree in your HP.  Typing "HOME" will 
bring you to your home directory, "UPDIR" will bring you up a directory,
"dir-name" will bring you into the directory "dir-name" and typing 
"{ HOME dir-name }" will bring you to the absolute path { HOME dir-name }.

Old directory     Input           New directory
{ HOME }          D1              { HOME D1 }
{ HOME D1 }       UPDIR           { HOME }
{ HOME }          { HOME D1 D2 }  { HOME D1 D2 }
{ HOME D1 D2 }    HOME            { HOME }

D: Directory listing

Gives you a directory listing, including file name, size, type and CRC and 
the free space on the calculator.

E: Execute command mode

Allows you to type commands to your HP as if you were at the stack.  Hit a
tilde ('~') and ENTER on a blank line to quit.

L: Log to file

Logs most activities to the log file (including stack output and directory
listings).  Executing this command again will close the logfile.

R: Retrieve files

Downloads the file you specify from the HP.  This function is case-sensitive.

S: Send files

Uploads the file you specify to the HP.  This function will strip directories
and capitalize the name you give it, so "c:\hp48\programs\blah.lib" becomes
simply "BLAH.LIB".

Q: Quit, shut down server

Quits the HP-Kermit program, bringing the server down as well.

ESC: Quit, don't shut down server

Quits HP-Kermit, but leaves the server up and running.  Basically equivalent
to a DOS-shell, just start the KERMIT program again to resume your session.

!: Toggle debugging mode

Just that.  It's quite confusing and not very pretty.  I may ask you for this
output if you have any problems, but you probably won't need it.

Aborting a Command
------------------

All commands can be cancelled with the ESC key.  If you find a download has
been halted (if the HP48 server crashes), ESC will cancel the download.  It
will also unfreeze the program if you "accidentally" type "KILL" in the 
command mode.  If you start the server up while the program is waiting at
any prompt, it will function normally.

Example Session
---------------

I've provided a simple example to show how you could go through the process
of installing a library on your HP, completely from your PC (except for the
ON-C at the end):

---- Start ----
HP-Kermit: HP48 Kermit Interface
Copyright 1997 by Matthew Mastracci

(? for help)> D
Finished, received 175 byte(s)
Current directory: { HOME }
WHIRL                Program             728.5 50950
PRTPAR               List                 33.5  8626
IOPAR                List                 29.5 47844
CST                  List                110.0 34455
PPAR                 List                 63.0 57404
VIEW                 Directory          4493.0 35406
ECON                 Directory          2882.0 20718
15543 free bytes
(? for help)> S
Send which file? c:\hp48\programs\ufl1.lib
Finished, sent 1016 byte(s) to UFL1.LIB
(? for help)> D
Finished, received 202 byte(s)
Current directory: { HOME }
UFL1.LIB             Library            1020.0  5847
WHIRL                Program             728.5 50950
PRTPAR               List                 33.5  8626
IOPAR                List                 29.5 47844
CST                  List                110.0 34455
PPAR                 List                 63.0 57404
VIEW                 Directory          4493.0 35406
ECON                 Directory          2882.0 20718
14523 free bytes
(? for help)> E
Command mode (hit ~ and ENTER to quit)
HP> 'UFL1.LIB' RCL
1: Library 257:  UFL   :1.0 Font Lev. 1
HP> 0 STO
Empty Stack
HP> ~
(? for help)> Q
Shutting down server
Done!
---- End ----

Troubleshooting
---------------

 Q. I start the server on the HP and the Kermit program on the PC, but when I
    try to do anything (ie: directory) it freezes.
 A1.You haven't configured the program correctly (editing KERMIT.CFG) or 
    there is a problem with your serial cable and/or serial port. 
 A2.You are a victim of the timing problem.  Use the KERMIT /T option to test
    the link.  If the connection drops some (but not all) of the characters,
    email me ASAP with your system configuration and I'll see what I can do.

 Q. I can't change directories!
 A. The Change Working Directory command is case sensitive.  'a' isn't 
    interpreted as 'A'.

Contacting Me
-------------

Suggestions, comments, concerns, complaints or compliments are always 
welcome.  

E-mail: mmastrac@acs.ucalgary.ca
Web page: http://www.ucalgary.ca/~mmastrac

Future Plans
------------

 - More comprehensive (and much clearer) logging 
 - More in-depth online help
 - Better documentation
 - Improved serial port configuration (ie: Base address, Interrupt, IRQ)

Revision History
----------------

1.0b : 10/11/97
 - First public beta
 - Most bugs out  ;)

1.0a : Internal (never released)

Resolved Problems (please contact me if these crop up)
-----------------

 - There were a few timing issues with the HP's UART that seem to be worked  
   around on the two machines I've tested.  If you experience these, please 
   contact me ASAP.

 - If you hit Ctrl-C you would kill the program and probably leave the COM 
   port in an undefined state.  Typing "mode com1:9600,n,8,1" restored it.
   This has been fixed.

