Chapter 15 Serial Communications

As the FreeBSD kernel boots, it will probe for the serial ports in your system for which the kernel was configured. You can either watch your system closely for the messages it prints or run the command

    % dmesg | grep sio

after your system is up and running.

Here is some example output from the above command:

    sio0 at 0x3f8-0x3ff irq 4 on isa
    sio0: type 16550A
    sio1 at 0x2f8-0x2ff irq 3 on isa
    sio1: type 16550A

This shows two serial ports. The first is on irq 4, is using port address 0x3f8, and has a 16550A-type UART chip. The second uses the same kind of chip but is on irq 3 and is at port address 0x2f8. Internal modem cards are treated just like serial ports---except that they always have a modem ``attached'' to the port.

The GENERIC kernel includes support for two serial ports using the same irq and port address settings in the above example. If these settings are not right for your system, or if you have added modem cards or have more serial ports than your kernel is configured for, just reconfigure your kernel. See section about building a kernel for more details.

Refer to the answer to the previous question.

Do not worry, they have been merged with the ttydX devices. You will have to change any old configuration files you have, though.

The third serial port, sio2 (see sio(4), known as COM3 in DOS), is on /dev/cuaa2 for dial-out devices, and on /dev/ttyd2 for dial-in devices. What is the difference between these two classes of devices?

You use ttydX for dial-ins. When opening /dev/ttydX in blocking mode, a process will wait for the corresponding cuaaX device to become inactive, and then wait for the carrier detect line to go active. When you open the cuaaX device, it makes sure the serial port is not already in use by the ttydX device. If the port is available, it ``steals'' it from the ttydX device. Also, the cuaaX device does not care about carrier detect. With this scheme and an auto-answer modem, you can have remote users log in and you can still dial out with the same modem and the system will take care of all the conflicts.

Again, the section on kernel configuration provides information about configuring your kernel. For a multiport serial card, place an sio(4) line for each serial port on the card in the kernel configuration file. But place the irq and vector specifiers on only one of the entries. All of the ports on the card should share one irq. For consistency, use the last serial port to specify the irq. Also, specify the COM_MULTIPORT option.

The following example is for an AST 4-port serial card on irq 7:

    options "COM_MULTIPORT"
    device sio4 at isa? port 0x2a0 tty flags 0x781
    device sio5 at isa? port 0x2a8 tty flags 0x781
    device sio6 at isa? port 0x2b0 tty flags 0x781
    device sio7 at isa? port 0x2b8 tty flags 0x781 irq 7 vector siointr

The flags indicate that the master port has minor number 7 (0x700), diagnostics enabled during probe (0x080), and all the ports share an irq (0x001).

Not yet. You will have to use a different irq for each card.

The ttydX (or cuaaX) device is the regular device you will want to open for your applications. When a process opens the device, it will have a default set of terminal I/O settings. You can see these settings with the command

    # stty -a -f /dev/ttyd1

When you change the settings to this device, the settings are in effect until the device is closed. When it is reopened, it goes back to the default set. To make changes to the default set, you can open and adjust the settings of the ``initial state'' device. For example, to turn on CLOCAL mode, 8 bits, and XON/XOFF flow control by default for ttyd5, do:

    # stty -f /dev/ttyid5 clocal cs8 ixon ixoff

A good place to do this is in /etc/rc.serial. Now, an application will have these settings by default when it opens ttyd5. It can still change these settings to its liking, though.

You can also prevent certain settings from being changed by an application by making adjustments to the ``lock state'' device. For example, to lock the speed of ttyd5 to 57600 bps, do

    # stty -f /dev/ttyld5 57600

Now, an application that opens ttyd5 and tries to change the speed of the port will be stuck with 57600 bps.

Naturally, you should make the initial state and lock state devices writable only by root. The MAKEDEV(8) script does NOT do this when it creates the device entries.

So you want to become an Internet service provider, eh? First, you will need one or more modems that can auto-answer. Your modem will need to assert carrier-detect when it detects a carrier and not assert it all the time. It will need to hang up the phone and reset itself when the data terminal ready (DTR) line goes from on to off. It should probably use RTS/CTS flow control or no local flow control at all. Finally, it must use a constant speed between the computer and itself, but (to be nice to your callers) it should negotiate a speed between itself and the remote modem.

For many Hayes command-set--compatible modems, this command will make these settings and store them in nonvolatile memory:

    AT &C1 &D3 &K3 &Q6 S0=1 &W

See the section on sending AT commands below for information on how to make these settings without resorting to an MS-DOS terminal program.

Next, make an entry in /etc/ttys (see ttys(5)) for the modem. This file lists all the ports on which the operating system will await logins. Add a line that looks something like this:

    ttyd1 "/usr/libexec/getty std.57600" dialup on insecure

This line indicates that the second serial port (/dev/ttyd1) has a modem connected running at 57600 bps and no parity (std.57600, which comes from the file /etc/gettytab, see gettytab(5)). The terminal type for this port is dialup. The port is on and is insecure---meaning root logins on the port are not allowed. For dialin ports like this one, use the ttydX entry.

It is common practice to use dialup as the terminal type. Many users set up in their .profile or .login files a prompt for the actual terminal type if the starting type is dialup. The example shows the port as insecure. To become root on this port, you have to login as a regular user, then su(1) to become root. If you use secure then root can login in directly.

After making modifications to /etc/ttys, you need to send a hangup or HUP signal to the init(8) process:

    # kill -HUP 1

This forces the init(8) process to reread /etc/ttys. The init process will then start getty processes on all on ports. You can find out if logins are available for your port by typing

    % ps -ax | grep '[t]tyd1'

You should see something like:

    747 ??  I      0:00.04 /usr/libexec/getty std.57600 ttyd1

If you are using another computer as a terminal into your FreeBSD system, get a null modem cable to go between the two serial ports. If you are using an actual terminal, see its accompanying instructions.

Then, modify /etc/ttys (see ttys(5)), like above. For example, if you are hooking up a WYSE-50 terminal to the fifth serial port, use an entry like this:

    ttyd4 "/usr/libexec/getty std.38400" wyse50 on secure

This example shows that the port on /dev/ttyd4 has a wyse50 terminal connected at 38400 bps with no parity (std.38400 from /etc/gettytab, see gettytab(5)) and root logins are allowed (secure).

On your system, the programs tip(1) and cu(1) are probably executable only by uucp and group dialer. You can use the group dialer to control who has access to your modem or remote systems. Just add yourself to group dialer.

Alternatively, you can let everyone on your system run tip(1) and cu(1) by typing:

    # chmod 4511 /usr/bin/cu
    # chmod 4511 /usr/bin/tip

Actually, the manual page for tip(1) is out of date. There is a generic Hayes dialer already built in. Just use at=hayes in your /etc/remote (see remote(5)) file.

The Hayes driver is not smart enough to recognize some of the advanced features of newer modems---messages like BUSY, NO DIALTONE, or CONNECT 115200 will just confuse it. You should turn those messages off when you use tip(1) (using ATX0&W).

Also, the dial timeout for tip(1) is 60 seconds. Your modem should use something less, or else tip will think there is a communication problem. Try ATS7=45&W.

Actually, as shipped tip(1) does not yet support it fully. The solution is to edit the file tipconf.h in the directory /usr/src/usr.bin/tip/tip. Obviously you need the source distribution to do this.

Edit the line #define HAYES 0 to #define HAYES 1. Then make and make install. Everything works nicely after that.

Make what is called a ``direct'' entry in your /etc/remote file (see remote(5)). For example, if your modem is hooked up to the first serial port, /dev/cuaa0, then put in the following line:

    cuaa0:dv=/dev/cuaa0:br#19200:pa=none

Use the highest bps rate your modem supports in the br capability. Then, type tip cuaa0 (see tip(1)) and you will be connected to your modem.

If there is no /dev/cuaa0 on your system, do this:

    # cd /dev
    # sh MAKEDEV cuaa0

Or use cu as root with the following command:

    # cu -lline -sspeed

with line being the serial port (e.g. /dev/cuaa0) and speed being the speed (e.g.57600). When you are done entering the AT commands hit ~. to exit.

The <@> sign in the phone number capability tells tip to look in /etc/phones for a phone number. But the <@> sign is also a special character in capability files like /etc/remote. Escape it with a backslash:

    pn=\@

Put what is called a ``generic'' entry in your /etc/remote file (see remote(5)). For example:

    tip115200|Dial any phone number at 115200 bps:\
            :dv=/dev/cuaa0:br#115200:at=hayes:pa=none:du:
    tip57600|Dial any phone number at 57600 bps:\
            :dv=/dev/cuaa0:br#57600:at=hayes:pa=none:du:

Then you can do something like tip -115200 5551234. If you prefer cu(1) over tip(1), use a generic cu entry:

    cu115200|Use cu to dial any number at 115200bps:\
            :dv=/dev/cuaa1:br#57600:at=hayes:pa=none:du:

and type cu 5551234 -s 115200.

Put in an entry for tip1200 or cu1200, but go ahead and use whatever bps rate is appropriate with the br capability. tip(1) thinks a good default is 1200 bps which is why it looks for a tip1200 entry. You do not have to use 1200 bps, though.

Rather than waiting until you are connected and typing CONNECT host each time, use tip's cm capability. For example, these entries in /etc/remote (see remote(5)):

    pain|pain.deep13.com|Forrester's machine:\
            :cm=CONNECT pain\n:tc=deep13:
    muffin|muffin.deep13.com|Frank's machine:\
            :cm=CONNECT muffin\n:tc=deep13:
    deep13:Gizmonics Institute terminal server:\
            :dv=/dev/cuaa2:br#38400:at=hayes:du:pa=none:pn=5551234:

will let you type tip pain or tip muffin to connect to the hosts pain or muffin; and tip deep13 to get to the terminal server.

This is often a problem where a university has several modem lines and several thousand students trying to use them...

Make an entry for your university in /etc/remote (see remote(5)) and use <\@> for the pn capability:

    big-university:\
            :pn=\@:tc=dialout
    dialout:\
            :dv=/dev/cuaa3:br#9600:at=courier:du:pa=none:

Then, list the phone numbers for the university in /etc/phones (see phones(5)):

    big-university 5551111
    big-university 5551112
    big-university 5551113
    big-university 5551114

tip(1) will try each one in the listed order, then give up. If you want to keep retrying, run tip(1) in a while loop.

CTRL+P is the default ``force'' character, used to tell tip(1) that the next character is literal data. You can set the force character to any other character with the ~s escape, which means ``set a variable''.

Type ~sforce=single-char followed by a newline. single-char is any single character. If you leave out single-char, then the force character is the nul character, which you can get by typing CTRL+2 or CTRL+SPACE. A pretty good value for single-char is SHIFT+CTRL+6, which I have seen only used on some terminal servers.

You can have the force character be whatever you want by specifying the following in your $HOME/.tiprc file:

    force=single-char

You must have pressed CTRL+A, tip(1) ``raise character'', specially designed for people with broken Caps Lock keys. Use ~s as above and set the variable ``raisechar'' to something reasonable. In fact, you can set it to the same as the force character, if you never expect to use either of these features.

Here is a sample .tiprc file perfect for Emacs users who need to type CTRL+2 and CTRL+A a lot:

    force=^^
    raisechar=^^

The ^^ is SHIFT+CTRL+6.

If you are talking to another Unix system, you can send and receive files with ~p (put) and ~t (take). These commands run cat(1) and echo(1) on the remote system to accept and send files. The syntax is:

    ~p <local-file> [<remote-file>]
    ~t <remote-file> [<local-file>]

There is no error checking, so you probably should use another protocol, like zmodem.

First, install one of the zmodem programs from the ports collection (such as one of the two from the comms category, lrzsz or rzsz.

To receive files, start the sending program on the remote end. Then, press enter and type ~C rz (or ~C lrz if you installed lrzsz) to begin receiving them locally.

To send files, start the receiving program on the remote end. Then, press enter and type ~C sz files (or ~C lsz files) to send them to the remote system.

Motherboards and cards with Acer UARTs do not probe properly under the FreeBSD sio probe. Obtain a patch from www.lemis.com to fix your problem.