
  VT52BIS - WHY & HOW                                        J.A. Bezemer
                                             <costar@panic.et.tudelft.nl>
                                                            February 1999


HISTORY

VT52BIS was born out of the need of a fully functional and fast terminal
emulator for the HP48, and the lack of one. I tried several available
terminal emulators, but none of them was satisfactory. The original ANSI
1.5 was the closest to my liking. So I contacted the author, Gasper
Fele-Zorz, and together we developed this new vt52bis standard and changed
some other things. (The complete list of changes is in the file
change.log.) 

The main goal was to use the HP48 as a serial terminal to a Linux system. 
All efforts have been made to make this as complete as possible; other
features like the DIALER were not really needed, but are still included
in the `full' version for completeness. 


FEATURES

  - Entirely System RPL & Machine Language, so very fast
  - 33x10 characters on screen (may be extended to e.g. 80x24, but
    scrolling is very slow)
  - Support for inverse="standout" mode (slow but needed in Lynx);
    with/without standout mode is changeable at any moment
  - Up to ten concurrent screens, just like the Linux console
  - Display is password-lockable
  - Digraphs ("e, ae etc.) can be entered easily with a "Compose"-like key
  - Can scroll back a few screenfulls for each concurrent screen
  - Copy/Paste facility (rather laborious but sometimes useful)
  - User-redefineable key mapping, with possibility for multi-character
    sequences bound to a single key
  - Default key mapping resembles well-known VT52/VT23 key mapping very
    closely; includes a full set of cursor keys and ten function keys
  - Comes in a full and a mini version


THE PROGRAM `SCREEN'

Most features are accomplished by close interaction of the terminal
emulation software on the HP48 and the `screen' program that is running on
the Linux computer. A schematic is given below:


   ____________________________          _______________________________
  |                            |        |                               |
  |            HP48            |        |           COMPUTER            |
  |                            | serial |                               |
  | screen                     | cable  |                               |
  |keyboard <---> VT52BIS <--->|<------>|<---> Screen <--+---> program1 |
  |                            |        |                |        :     |
  |                            |        |                +---> programN |
  |____________________________|        |_______________________________|

              |                    |                     |
              |                    |                     |
           MLDISP          vt52bis Esc-codes     "vt100" Esc-codes
          commands         MLDISP Ctrl-codes

 terminfo:                  hp48-vt52bis           screen.hp48-vt
                            hp48-vt52bis-n


Screen is able to do a lot of things that make life easy. It allows up to
ten programs to use one single screen concurrently, giving the user the
ability to switch between each `window'. It also does backscrolling,
cut'n'paste, screen locking, digraphs and much more. ANSI 1.5B's default
key mapping provides easy access to many of the often used functions of
screen.

The Escape- and Ctrl-codes that must be sent to make the terminal do what
it's supposed to do, must be known to screen. These codes are described in
a `terminfo' description; you can choose either "hp48-vt52bis" or
"hp48-vt52bis-n": with and without standout functionality. 

In the same way, communication between screen and the "real" programs is
governed by another terminfo description. You can use the standard
"screen" or even "vt100", but the optimized "screen.hp48-vt" will perform
much better. When screen is started, it will automatically choose
"screen.hp48-vt" if available, otherwise "screen". When telnetting to
other machines where "screen" is not available, "vt100" will suffice.


PREPARING YOUR HP48

You have to download the terminal emulation program to your HP48. You can
choose either the `full' or the `mini' version; they are in the full/
resp. mini/ directories. The 00readme.txt files in these directories
provide more details on installation. 

Of course, you must have a serial cable between the HP48 and the computer.
See the HP48 FAQ at http://www.engr.uvic.ca/~aschoorl/faq/ for more
information about that.


PREPARING YOUR LINUX COMPUTER

Normal console logins are handled by the `getty' or `mingetty' program,
that displays the `login:'-prompt. To use the HP48 as a serial terminal,
you need a getty on the appropriate serial port. To do this, you must edit
/etc/inittab - that's were the getty's are started.

On my Debian system, I've added a line that reads:

  T1:23:respawn:/sbin/getty -L ttyS1 9600 hp48-vt52bis

Where:
  "T1" is the ID of the inittab entry
  "23" are the runlevels (2 and 3 in my case) where this line is valid
  "respawn" means that another getty should be started when you've
      logged out (so you can login again)
  "/sbin/getty" is the getty program name
  "-L" means that it's a Local line, and no hardware handshake should be
      used
  "ttyS1" is the serial line, in my case /dev/ttyS1 = COM2
  "9600" is the baud rate
  "hp48-vt52bis" is the name of the terminfo description that should be
      used by default (you may also use hp48-vt52bis-n if you find the
      inverse=standout effect too slow). If you want to be more generic,
      "vt100" is okay here, but then you have to change the TERM
      variable manually each time you log in.

On non-Debian systems, you may have to do some other things. To determine
what to do, examine the existing /etc/inittab, and read the manpages of
inittab and (min)getty.

After you have modified /etc/inittab, use the command

  init q

to make `init' aware that things have changed. There will now be a getty
running at the serial port.


If you don't have `screen' installed yet, you should do so now. All major
Linux distributions come with a nice screen package, that you can install
in the usual way. However, if you want to compile it yourself, the sources
are available via anonymous FTP at ftp://ftp.gnu.ai.mit.edu/pub/gnu/.


The system doesn't know the HP48 terminal characteristics yet. Therefore
you have to copy the terminfo descriptions from the terminfo/ directory to
the subdir ".terminfo" of your home directory. More info is in the
00readme.txt file in the terminfo/ directory. (And don't forget the
$TERMINFO initialization in the shell startup file.)

(NOTE: This is only valid for systems that use terminfo. If you use an
older system that uses the now obsolete termcap database, see
src/termcap.txt.)


The last step is creating a `.screenrc' file in your home directory. It
should contain this single line:

  defflow on

This lets screen capture the XON/XOFF flow control characters, which is
necessary because we're using a very slow HP48...


LOGGING IN

After preparing your HP48 and your computer, you should be able to log in.
On the HP48, start the TTY or TTY52 program. On the HP48 screen, you
should see a familiar greeting. You may enter your login name and
password.

(Notes:
If there's no login prompt, check if you followed all steps correctly.
Ctrl-D (=RightShift-D) on the HP48 will cause the getty to restart.
In some cases, the password prompt may be invisible - just key in your
password as usual.
For `weird' characters, see doc/keys.txt)


If you didn't specify hp48-vt52bis(-n) as default terminal type in the
/etc/inittab file, you should switch manually to that description now. In
sh/bash-like shells, enter:

  TERM=hp48-vt52bis             (or hp48-vt52bis-n)
  export TERM

  (some bashes also support the shorter `export TERM=hp48-vt52bis')

and in csh/tcsh-like shells:

  set term=hp48-vt52bis         (or hp48-vt52bis-n)

Note that LeftShift is the CapsLock key. The Backspace (`<=' `DROP') key
may not be interpreted correctly yet - better avoid typos ;-) 


Then start the `screen' program by typing

  screen

You should see a info/copyright screen. After pressing ENTER, the screen
is cleared, and you're in your familiar shell again.

For a quick example, type `less /etc/passwd'; `q' to exit.
Alpha-* (`times') creates a new window; Alpha-0..9 switches between
windows.


SOMETHING MAY GO WRONG

The most usual effect is the terminal `locking up'. In that case, the
display isn't updated any more, because the computer thinks that the HP48
is still busy. In such a case, press Alpha-/ (`divide') (pressing it twice
sometimes gives a better result). 
This seems to be a problem with the HP48 firmware, and occurs often when
a key is pressed during a large display update.


If the terminal always stops updating the display after half a screen, the
xon/xoff setting is not correct. Make sure the HP48 actually sends
xon/xoff characters - the last item of TERMPAR should be 1, as should be
the third and fourth item of IOPAR. My TERMPAR is { "" "" 33 10 6 1 } and
IOPAR is { 9600 0 1 1 3 1 } and everything works fine. 

Also, the computer should accept these characters. To ensure this, enter
the command `stty sane ixon ixoff' from within the terminal emulator,
which restores some `sane' values. (And make sure you have a .screenrc
file as described above.)


KEY MAPPING / SPECIAL KEYS

Plase refer to the file keys.txt for details about the key mapping and
the `screen special keys'.


DETACHING / REATTACHING

One powerful feature of screen is the possibility of `detaching' the
physical terminal from the screen program. When you want to switch from
`with standout' to `without standout' and vice versa, this feature comes
in handy.

Type in Ctrl-A d (RightShift-A d) to detach the screen. You'll be returned
to the shell you were in before starting the screen program. Now you can
change the terminal description to for example `without standout'.
In sh/bash-like shells, enter:

  TERM=hp48-vt52bis-n
  export TERM

  (some bashes also support the shorter `export TERM=hp48-vt52bis-n')

and in csh/tcsh-like shells:

  set term=hp48-vt52bis-n

Then reattach the screen by typing `screen -r'. 


There's something even nicer: you may reattach the screen to other
terminals as well! E.g. resize an xterm to 33x10 and reattach the screen
there... But note that some programs can't dynamically resize their screen -
so you may have to restart these programs if you reattach on a non-33x10 
terminal.


LEAVING THE TERMINAL TEMPORARILY

If you want to temporarily leave the terminal emulator (e.g. to do some
calculations, or to change the batteries :), just press the ON key. If you
want to return, use the normal TTY or TTY52. To restore the screen, press
Alpha-/ (where `/' is the `divide' key) (you may have to press `/' twice
for a better result). 

If you're worried about security, press Alpha-Z just before leaving the
terminal emulator. This will cause the screen to be locked. After
returning, you must type your password before you're allowed to continue.


SPECIFICATIONS FOR VT52BIS

Please refer to the files specs.txt and keys.txt for the vt52bis
input/output specifications.


ENHANCING

If you don't want to type `screen' each time you log in, you can automate
things. "I'll leave that as an excercise for the reader" ;-) 
Well, here's a hint: in your shell startup script, test if it runs on
ttySx and if so, run screen; logout.

If you want every user to be able to use the terminfo descriptions, copy
them from your private .terminfo/ directory to the hierarchy under
/etc/terminfo/ or /usr/share/terminfo/ . 

