.TH terminal "" "" "Technical Information"
.PC
.PP
.II "terminal^adding
.II "adding a terminal"
.II "computer^connecting via serial port"
This article describes how you can hook up a terminal to your \*(CO system
via a serial port.
It also discusses common problems that arise with this procedure, as
diagnosed daily by the technical support staff at Mark Williams Company.
For information on connecting a modem to your computer's serial port,
see the article
.BR modem .
.SH "Terminals for Beginners"
To a beginner, a terminal \(em with its many wires and controls \(em may
be daunting.
However, connecting a terminal or PC-based terminal emulator
to a \*(CO system is really very easy.
To make matters even easier, this section discusses how to use a
simple configuration, using only one COM port.
.PP
What you need:
.IP \fB1.\fR 0.3i
A \*(CO system with a COM port.
.IP \fB2.\fR
Either a terminal or
a PC with a COM port and communications software.
An old PC or PC-AT is fine.
(You can also use a Macintosh or other such computer, but that is
beyond the scope of this discussion.)
.IP \fB3.\fR
A ``null modem cable'' purchased from your nearest computer supply store.
This should cost between $10 and $20, in U.S. currency.
The only tricky part about the cable is making sure that the connectors
on the ends match the connectors on your
COM ports (i.e., nine pin vs. 25 pin, and male vs female.
Adaptors are also available.
.PP
What you do:
.IP \fB1.\fR 0.3i
Connect the cable to the COM port on the \*(CO system.
Note that the COM port on your \*(CO system is always a
.I male
plug (that is, it has pins rather than sockets).
Do
.I not
plug your connection into a female plug, as this is the parallel
port.
If you do so, you can damage your equipment.
.IP \fB2.\fR
Connect the cable to the COM port on the terminal/PC.
If you are using a PC as a terminal, the COM port on it will also be male.
If you are using a stand-alone terminal, the plug could be either
male or female.
.IP
If you are using a stand-alone terminal, there may be a plug on the back
that is labelled ``AUX''.
Do
.I not
use this plug; use the other one.
.IP \fB3.\fR
Configure the terminal/PC to use 9600 speed (or ``baud'')
and 8N1 character setting (that is, eight bits, no parity, one stop bit.
Note that you do not need a telephone number:
you won't be dialing anywhere.
.IP \fB4.\fR
Log in on your \*(CO system as the superuser
.BR root .
Type the following command:
.DM
	/etc/enable com?l
.DE
.IP
where `?' is the number of the COM port on your \*(CO system into which
you are plugging the cable from the PC or terminal
Note that the last character is lower-case `L',
.I not
a one.
.IP \fB5.\fR
Now come a tricky part:
use your favorite text editor and edit file
.BR /etc/ttytype .
This file gives the default type of terminal that will be connecting to
\*(CO via a given COM port.
This is important.
If you don't do this, such screen-oriented programs as editors and
.B vsh
will not work properly.
.IP
Each entry in
.B /etc/ttytype
has two columns:
the first gives a type of terminal, and the second names the port.
The following shows an example entry:
.DM
	vt100	com3l
.DE
.IP
In this instance, COM port
.B com3l
has a DEC VT-100 plugged into it by default.
Look for an entry for the COM port into which you plugged your terminal
device.
If you can't find you, you can create one easily enough; however,
having two entries for the same port is not a good idea, as \*(CO will
become confused.
.IP
If you are plugging in a PC, use the terminal type
.BR vt100 .
If you are using a stand-alone terminal, name the type of terminal you
are using, e.g.,
.B wyse370
for a Wyse 370 color terminal.
If you cannot figure out what type of terminal you are using, use
.BR dumb .
This will not allow you to use screen-oriented programs like MicroEMACS,
but at least you will be able to connect to \*(CO; you can figure out the
type of terminal later.
.IP \fB6.\fR
Return to your terminal device.
If you are using a PC, invoke the terminal emulator, and put it into
``connect'' mode.
If you are using a stand-alone terminal, turn it on.
Press \*(RT.
After a short pause, you should see the prompt
.DM
	Coherent login:
.DE
.IP
on your screen.
You can then log in and run normally.
.PP
That's all there is to it.
In this way, you can get more use out of an old, obsolete PC.
After you get it working, you may need to adjust some
other settings, particularly if you are using a communications package
on a PC for a terminal.
.PP
If you see garbage characters when you log in, probably the speed (or
``baud rate'') is not set correctly
either on the COM port of your \*(CO system or on your terminal device.
The Lexicon article on
.B ttys
describes the magic character string used to describe each com port and one of
the letters is the port speed.
.SH "Problems with Terminal Hookup"
As noted above, it is easy to hook up a terminal.
However, problems can arise if you overlook any details.
.PP
When problems arise, they usually come from some form of confusion.
These can include send/receive confusion, baud rate confusion, and
shell/no shell confusion.
The following sections describes eacy type of confusion in turn.
.SH "Send/Receive Confusion"
This most often happens when you've soldered your own connectors, and
you made a mistake.
If you purchased a connector, as we recommended above, then skip to the
next section.
.PP
A serial connection between your computer and a terminal requires at least
three wires:
one each for pins 2, 3, and 7.
These pins, respectively, control
send (TD), receive (RD), and signal-ground (Gnd or SG).
These pin numbers correspond to the 25-pin ``DB-25'' connectors
used on most equipment.
If your system has the AT-style nine-pin ``DB-9'' connectors, you will
need to wire to the corresponding signals.
See the Lexicon entry for
.B RS-232
for details of the pin-outs for these two connectors.
.PP
When hooking up a terminal to a serial port using a three-wire connection,
you must cross pins 2 and 3,
so that each device's send pin talks to the other device's receive pin.
.II "null modem"
You can plug a device called a ``null modem'' between the cable and the
serial port, to do this automatically.
.PP
Note that the only symptom of a problem in the cable is that nothing
appears on your terminal when you type.
.SH "Baud-Rate Confusion"
The terminal and the computer must speak to each other at the same speed, or
``baud rate''.
A typical symptom of baud-rate confusion is garbage characters on the screen.
When the wiring is wrong, you see nothing;
when the baud rate is wrong, you see random collections of characters on
the screen, but nothing meaningful.
.PP
You can fix baud-rate problems by using the command
.B stty
to reset the baud rate on the port, or resetting the baud rate on the
terminal.
The problem should also be solved by editing file
.BR /etc/ttys .
For directions on how to reset the baud rate for a port,
see the Lexicon entry for
.BR stty ;
see the Lexicon entry for
.B ttys
for information on how to edit \fB/etc/ttys\fR.
.PP
Please note, too, that \*(CO supports the following configuration for
terminals:
.DS
	8 word bits
	1 stop bit
	No parity bits
.DE
.PP
These settings, as well as the baud rate, must match before your terminal
will work correctly.
.SH "The Old Shell Game"
Before a terminal is useful to you, you must \fIenable\fR the
port into which it is plugged.
Enabling a port means that the \*(CO system creates a shell for that port:
this, in turn, means that \*(CO prints a login prompt on the
device plugged into that port, and reads and processes interactively
commands that are entered from that port.
The \*(CO system also restricts permissions on all enabled serial ports,
so that only the superuser
.B root
can read and write to the port.
This prevents other users who may be using the system from accessing
the serial port.
.PP
Note that not all ports need be enabled:
for example, you should not enable a COM port into which you've plugged
a printer.
.PP
When you boot the \*(CO system, it reads system file
.B /etc/ttys
and creates a shell for each serial port that needs one.
One way to enable a port is to log in as the superuser
.BR root ,
then use a text editor to change the port's entry in
.BR /etc/ttys ,
as described its Lexicon article.
Finally, typing the command
.DM
	kill quit 1
.DE
.PP
forces \*(CO to re-read
.B /etc/ttys
and so create a shell for the port.
Note that doing this will ensure that the port is re-enabled every time
you boot.
.PP
A better way to enable a port is to use the command
.BR enable ,
as described in its Lexicon article.
For example, to put up a shell on COM port
.BR /dev/com1r ,
log in as the superuser
.B root
and type the command:
.DM
	/etc/enable com1r
.DE
.II "terminal^raw"
.II "terminal^cooked"
.II "raw terminal
.II "cooked terminal"
.SH "Exiting Raw Mode"
A terminal is in
.I cooked
mode.
In cooked mode, the tty driver
interprets and correctly processes such predefined characters as the
end-of-file character or the quit character.
In
.I raw
mode, however, processing of such characters is turned off; and in
general the terminal will behave bizarrely.
Raw mode is used by programs that do not want the tty driver to interpret
characters; for example, a program that uses a tty to transmit a binary
to another machine does not want the tty driver to be interpreting the
binary information being passed through it.
.PP
Occasionally, a program will exit abruptly and leave the terminal in
raw mode.
To return to cooked mode, use the command
.BR "<ctrl-J> stty sane <ctrl-J>" .
This invokes the command
.BR stty ,
which lets you manipulate terminal settings, to restore the previous
cooked state.
See the Lexicon entry on
.B stty
for details on raw and cooked modes; this article also describes the options
of this most useful command.
.SH "See Also"
.Xr "Administering COHERENT," administe
.Xr "asy," asy
.Xr "device drivers," device_dr
.Xr "hs," hs
.Xr "modem," modem
.Xr "RS-232," rs-232
.Xr "sgtty," sgtty
.Xr "stty," stty
.Xr "termcap," termcap
.Xr "terminfo," terminfo
.Xr "termio," termio
.Xr "termios," termios
.Xr "ttys" ttys
.SH Notes
One final bit of hard-won wisdom:
once you have something working,
write down what you did, and store it in a place where you won't lose it.
Note especially what connectors are where and how they have been cabled
together.
It makes life easier just knowing that you are looking for a
female-to-female cable instead of male-to-female or male-to-male.
If you know whether to insert a null modem, you are even better off.
.PP
\*(CO supports multi-port serial cards as well as COM ports 1 through 4.
See the Lexicon entry on
.B "asy"
for a list of the devices that \*(CO supports, and for details.
.PP
.II "Hough, Dave"
Thanks to Dave Hough (tecdah1@sdc.cs.boeing.com), whose posting to
comp.os.coherent is the basis of the ``Beginners'' section, above.
