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

 Table of Contents
=---------------------------------------------------

Section                                                                 
=---------------------------------------------------------------------------
1.0 Introduction
   1.1 Author's Note
   1.2 Legal Notice
   1.3 Supported Platforms
   1.4 Future Plans
   1.5 Revision History
   1.6 Fixed Problems 

2.0 Setup    
   2.1 Initial Setup
   2.2 Common Communication Settings

3.0 Using HP-Kermit
   3.1 Xmodem Transfer Mode
   3.2 Kermit Interactive Mode
   3.3 A: About (Kermit-only)
   3.4 B: Break (Kermit-only)
   3.5 C: Change directory (Kermit-only)
   3.6 D: Directory listing (Kermit-only)
   3.7 E: Execute command mode (Kermit-only)
   3.8 L: Log to file (Kermit and Xmodem)
   3.9 R: Retrieve files (Kermit and Xmodem)
   3.10 S: Send files (Kermit and Xmodem)
   3.11 Q: Quit, shut down server (Kermit and Xmodem)
   3.12 ESC: Quit, don't shut down server (Kermit and Xmodem)
   3.13 !: Toggle debugging mode (Kermit and Xmodem)
   3.14 Aborting a Command
   3.15 Troubleshooting

4.0 Examples
   4.1 Typical Session
   4.2 Using HP-Kermit For Backups

5.0 Contacting Me

=---------------------------------------------------
 1.0 - Introduction
=---------------------------------------------------

 1.1 - Author's Note
=---------------------------------------------------

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.  :)

 1.2 - Legal Notice
=---------------------------------------------------

HP-Kermit is freeware and may be distributed and used for non-commercial use
freely.  It may also be freely distributed in a software collection sold for 
the cost of producing the collection (ie: non-profit).  If you wish to
distribute the program, but do not fall under either of these two
categories, please contact me and we can work something out.

 1.3 - Supported Platforms
=---------------------------------------------------

Currently, the only supported platform for HP-Kermit is the i386 MS-DOS one.
Plans are currently underway for an Amiga and a Linux port.

 1.4 - Future Plans
=---------------------------------------------------

 - More comprehensive (and much clearer) logging 
 - More in-depth online help

 1.5 - Revision History
=---------------------------------------------------

1.1.1 : 12/05/97
 - Fixed small bug when sending files > 32k via Xmodem

1.1 : 10/23/97
 - First non-beta version
 - Added Xmodem support (send/receive)
 - Fixed odd bug in communication routines that hung Xmodem on packet 32
 - Backing up your HP to your PC now supported (using ARCHIVE)
 - Added improved serial port configuration (and /C option)
 - Renamed executable to HPKERMIT.EXE
 - Fixed bug that would cause transfer to fail if packet was made of all 
   control characters (ie: transferring UFL3.LIB)
 - Source-code cleanup to allow easier porting
 - Added EMU387.DXE to archive for people without coprocessors (ie: 386s)

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

1.0a : Internal (never released)

 1.6 - Fixed Problems 
=---------------------------------------------------

Please contact me ASAP if any of these crop up:

 - There were a few timing issues with the HP's UART that seem to be 
   successfully worked around on the two machines I've tested.  

 - 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" would restore 
   it.  This has been fixed.


=---------------------------------------------------
 2.0 - Setup    
=---------------------------------------------------

 2.1 - Initial Setup
=---------------------------------------------------

1.  Run HPKERMIT /C to configure your serial port.
2.  Ensure that the HP is sending via wire at 9600, parity none 
    (right-shift-1/Transfer), translate mode 3 (128->255).
3.  Use right-shift-right-arrow at the stack on your HP to start the server
    (or use the command "SERVER").
4.  Type HPKERMIT to start the client on your PC.
5.  Use the HPKERMIT /T option to test your HP<->PC link (if HPKERMIT 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.

 2.2 - Common Communication Settings
=---------------------------------------------------

The following table lists the standard communication settings for the various
communication ports, as implemented in the program:

COM Port        Base Port      IRQ     Interrupt 
1               3f8             04      0c
2               2f8             03      0b
3               3e8             04      0c
4               2e8             03      0b
5..8            3f8             04      0c   (usually varies with setup)

Note: Interrupt is usually IRQ + 8 for standard configurations

=---------------------------------------------------
 3.0 - Using HP-Kermit
=---------------------------------------------------

HP-Kermit supports both Kermit and Xmodem for file transfers.  The following
table compares the two protocols:

Kermit (no command line switches)       Xmodem ('/X' command line switch)
- Requires control-character quoting    - Data sent raw
- Up to 94 characters per packet        - 128 bytes per packet
- Can send in ASCII or Binary mode      - Binary mode only
- Can translate extended characters     - No translation performed
- Slower for large file transfers       - Constant speed throughout transfer,
  (due to HP processing)                  almost always faster than Kermit
- Best for creating programs or         - Best for sending large binary files
  textfiles on the PC for transfer

 3.1 - Xmodem Transfer Mode
=---------------------------------------------------

Use the '/X' command line option to start HP-Kermit in Xmodem Transfer mode.
This mode will allow the program to connect with the HP48's XSEND and XRECV 
commands.  This mode is highly recommended for binary transfers of files 
larger than 10 kbytes.  

To send a file to the HP48 using Xmodem:

1.  Hit 'S' on your computer for the "Send File" command
2.  Enter the name of the file, including the path if not in the current 
    directory.
3.  Enter the quoted name of the file to receive on the HP (ie: 'TMP')
4.  Type 'XRECV'

To receive a file from the HP48 using Xmodem:

1.  Enter the quoted name of the file to send from the HP (ie: 'TMP')
2.  Type 'XSEND'
3.  Hit 'R' on your computer for the "Receive File" command
4.  Enter the name of the file, including the path if not in the current 
    directory.

Notes:
 - Starting the transfer on the sending side first will begin the transfer 
   much faster.  
 - You can transfer raw text files from your PC to your HP this way, but no 
   character translation will be performed (Kermit is much better for this)
   
 3.2 - Kermit Interactive Mode
=---------------------------------------------------

Kermit Interactive mode is the default mode of HP-Kermit, invoked when there
are no command line switches.  Entering commands in HP-Kermit is quite easy.  
Each of the commands has a one-letter abbreviation as follows:

 3.3 - A: About (Kermit-only)
=---------------------------------------------------

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

 3.4 - B: Break (Kermit-only)
=---------------------------------------------------

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

 3.5 - C: Change directory (Kermit-only)
=---------------------------------------------------

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 }

 3.6 - D: Directory listing (Kermit-only)
=---------------------------------------------------

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

 3.7 - E: Execute command mode (Kermit-only)
=---------------------------------------------------

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.

 3.8 - L: Log to file (Kermit and Xmodem)
=---------------------------------------------------

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

 3.9 - R: Retrieve files (Kermit and Xmodem)
=---------------------------------------------------

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

 3.10 - S: Send files (Kermit and Xmodem)
=---------------------------------------------------

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".

 3.11 - Q: Quit, shut down server (Kermit and Xmodem)
=---------------------------------------------------

Quits the HP-Kermit program, bringing the server down as well.  Functions the
same way as ESC in Xmodem mode.

 3.12 - ESC: Quit, don't shut down server (Kermit and Xmodem)
=---------------------------------------------------

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.

 3.13 - !: Toggle debugging mode (Kermit and Xmodem)
=---------------------------------------------------

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.

 3.14 - 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.

 3.15 - 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'.


=---------------------------------------------------
 4.0 - Examples
=---------------------------------------------------

 4.1 - Typical 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 ----

 4.2 - Using HP-Kermit For Backups
=---------------------------------------------------

You can quickly receive backups of your HP's memory using the ARCHIVE 
command for safekeeping on your PC if your calculator's memory is ever lost:

1.  Start HP-Kermit.
2.  Enter "R" to receive a file and type "backup" as the filename.
3.  On the HP, enter the name to transfer as ":IO:name" (without the quotes),
    where "name" is the name of file to store on your PC.
4.  Run the ARCHIVE command on the HP48 (from RIGHT-SHIFT MEMORY NXT ARCHIVE).

This will download a file to your PC containing a backup of your HP's home
directory.  You can later restore this file by sending it back to the HP48,
RCLing it to the stack and running the RESTORE command.  Note that this 
procedure is identical to the one on page 27-12 of the user guide.


=---------------------------------------------------
 5.0 - Contacting Me
=---------------------------------------------------

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

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

The latest version of HP-Kermit will always be available from:

http://www.acs.ucalgary.ca/~mmastrac/files/hp-kermit.html

This manual compiled using MC v1.05 by Matthew Mastracci
