Copyright (c) 2009 Hugh Hood
All Rights Reserved

[Disclaimer: The author has taken all reasonable steps to insure this Howto article is accurate. However, you are reminded that it’s a good idea to have a backup of your system(s) before you tweak anything.]

I. Introduction

For many years, powerful Unix based computers have allowed both local and dialup connections from serial communication terminals. In their most basic form, often referred to as ‘dumb terminals’, these devices, consisting of a display monitor and input keyboard with little or no software, computing power, or mass storage devices of their own, permit text to be sent to and received from the Unix based hosts to which they are connected.

Typically, these terminals’ purpose is to input data or commands into the Unix host system, for processing and storage by that system.

Possibly the most famous terminal is the DEC VT-100, whose name will be recognized from the terminal emulation settings section of any good telecommunications software program, including both the freeware ProTERM 3.1 and Ewen Wannop’s Spectrum on the Apple II platform.

With the introduction of Mac OS X several years ago, Apple adopted Unix as its operating system of choice, replacing the older Macintosh system software that had been developed for over a decade.

This change opened the door for users of Macintosh computers to employ the power of Unix, and also permits users of Apple II computers, with their monitors, keyboards, CPU, software and local storage, to access this power as ‘intelligent’ serial terminals of the Macintosh.

II. Why Use Unix from an Apple II?

Over the last 10 years, articles have appeared on the internet about connecting the Apple II series to computers running Unix and the Unix-compatible Linux operating systems. Stories by Devin Reade, Blake Patterson and Paul Weinstein, for example, have given detailed instructions on making the connection.

The reasons given for doing this have been diverse, but include the ‘neat’ factor, and well as using the Apple II as a text terminal for IRC (Internet Relay Chat) chatting and running the text based web browser ‘Lynx’ and email client ‘Pine’.

Of course, in 2009, most users have access to GUI based web browsers and email clients and would consider the experiences offered by Lynx and Pine to be a step backward from that to which they have become accustomed.

Other reasons included accessing the vast universe of powerful Unix command line utilities that do everything from converting graphics and text files among various formats to performing complex mathematical and statistical computations on sets of user supplied data. Unix, which supports powerful features such as input/output redirection via ‘pipes’, can be commanded to perform many impressive tasks. [1]

Most, but admittedly not all, of these uses, employing the Apple II as a ‘dumb’ terminal at relatively slow speeds of 19,200 baud or less, lacked the day to day practical in-house benefit this author thought necessary to justify the time and effort involved in making the connection.

III. A ‘Practical’ Benefit

Those of us who work in a combined Apple II – Mac OS X environment oftentimes find the need easily to share and transfer files between the two platforms. For example, a co-worker using the Mac with Mark Munz’s DejaIIx AppleWorks emulator may need an AppleWorks file. Or, perhaps some text or other file is required to complete a Microsoft Word document or Entourage email on which the Mac user is working. Conversely, program and other files downloaded from the internet by the Mac may need to be transferred to the Apple II, including, naturally, Apple II disk images and the files thereon.

Considering that current Macs (those running OS X 10.4 Tiger and 10.5 Leopard) don’t inherently support Apple II compatible AppleTalk file sharing and that the OS X Finder doesn’t natively recognize the ProDOS file system [2], sharing files between Apple II’s and OS X Macs has not been a trivial task.

Workarounds have included copying files to HFS formatted Zip Disks and CF Cards (necessarily requiring an Apple IIGS and the HFS-capable GS/OS) for transfer via ‘sneakernet’, and using Ewen Wannop’s GS/OS program SAFE2 on an Apple IIGS equipped with an ethernet card to ‘FTP’ (File Transfer Protocol) the files to the Mac.

A more ‘unique’ solution involves running David Schmidt’s excellent ADTPro utility on both the Apple II and Mac simultaneously to exchange files between the two platforms.

Likewise, a Mac user running a telecommunications program such as ZTerm could effect a protocol file transfer with a serially-connected Apple II user simultaneously running a similar program.

Each of the last two methods involves conscious attention on the part of the both the Apple II user and the Mac user to make the transfer. This can be inconvenient, and fortunately, it is unnecessary.

IV. Intelligent Terminal Apple II to Mac File Transfers

With the Apple II acting as an intelligent terminal connected to the Mac, swift and errorless file transfers between the two machines, using the Zmodem error-correcting protocol, occur without any interaction on the part of the Mac user.

The Apple II user in essence ‘runs the show’ with Apple II telecom software (e.g. ProTERM 3.1 or Spectrum) controlling the sending and receiving on the Apple II end, while the Unix programs ‘rz’ and ‘sz’ work behind the scenes to handle things on the Mac end. When the Apple II starts a Zmodem file send, the Unix program ‘rz’ (receive Zmodem) is automatically started on the Mac to receive and save the file.

When it’s time to receive a file on the Apple II, the Apple II user merely types ‘sz [filename]’ (send Zmodem), and the Apple II automatically starts its Zmodem receive operation.

In addition, the ‘rz’ and ‘sz’ commands contains many optional modifiers, including one that enables auto conversions between Unix ‘newline’ characters and CR/LF pairs during the Zmodem receive and send processes.

To be sure, this serial terminal method of file transfer is not ethernet, nor is it AppleTalk file sharing, but at the higher rates of 57,600 and 115,200 baud it can be very speedy. For example, a 34 kByte file transferred from an Apple II to a Mac via Zmodem at 115,200 baud completes error free in 4 seconds, with a throughput of 8,577 characters per second (cps). Even at 57,600 baud, this transfer manages 4,901 cps in 7 seconds.

To achieve the higher speed transfers, Apple IIe users would need a Super Serial Card with Lightning Systems ‘Turbo ASB’ daughter card. ProTERM 3.1 includes a driver for this combination. Otherwise, Apple IIe operators would be limited to 19,200 baud transfers. [3]

Users of the Apple IIGS need no additional hardware for rapid file transfers. Both ProTERM 3.1 and Spectrum are capable of rates of 57,600 baud using the IIGS’ built-in SCC printer and modem ports. In addition, with a patch developed by this author with help from David Schmidt, David Empson and David Wilson, ProTERM 3.1 is completely capable of transferring files at 115,200 baud using the IIGS’s serial ports. [4]

Not to be completely left out, Apple IIc and IIc+ owners can expect transfer rates between 9,600 and 19,200 baud.

In all cases, the most reliable, error free, high speed connections will use Hardware Handshaking (RTS/CTS) rather than Software Handshaking (Xon/Xoff). And, by ensuring correct cabling and setting of port parameters, Hardware Handshaking is easily obtained.

V. System Requirements

o An Apple IIe, IIc, IIc+ or IIGS

o An Apple II telecommunications program

o An Apple Super Serial Card (Apple IIe only)

o A Mac running OS X 10.2 or later

o A Mac with either a real or emulated serial port [5]

o A Mac with the Unix programs ‘sz’ and ‘rz’. These programs are not included with OS X. To install, simply download and install either ‘Fink’ or ‘MacPorts’ to enable a fairly effortless install and build of the ‘lrzsz’ bundle, which contains ‘sz’ and ‘rz’, and provides Z/Y/X modem support.

o A hardware handshaking ‘null modem’ (aka ‘printer’ or ‘crossover’) cable

VI. Setting Up the Mac

Preparing the Mac to enable Apple II serial terminal connections is not difficult, as it only involves determining the available serial ports and then modifying three text files in the Mac’s ‘/etc/’ directory. [6] These files are ‘/etc/ttys’, ‘etc/gettytab’ and ‘/etc/profile’.

Please remember to back up your hard drive before making any changes to these 3 files, in order to avoid the sometimes harsh wrath of the law of unintended consequences.

A. Determining Available Serial Ports

To obtain a listing of the Mac’s available Serial Ports, simply launch the ‘Terminal’ application and enter the following command:

ls /dev/cu* # [7]

You will receive a listing resembling:

/dev/cu.modem            # Beige G3 modem port
/dev/cu.printer          # Beige G3 printer port
/dev/cu.serial           # Stealth serial port
/dev/cu.USA28X2b1P1.1    # Keyspan USB-Serial Adapter port 1
/dev/cu.USA28X2b1P2.2    # Keyspan USB-Serial Adapter port 2
/dev/cu.Bluetooth-Modem  # Bluetooth Serial port
/dev/cu.SxProS4P4.1      # Keyspan SxPro4 port 1
/dev/cu.SxProS4P4.2      # Keyspan SxPro4 port 2
/dev/cu.SxProS4P4.3      # Keyspan SxPro4 port 3
/dev/cu.SxProS4P4.4      # Keyspan SxPro4 port 4

Choose a serial port that you do not plan to employ for another use (e.g. a Fax Modem) and make note of its full pathname (i.e. /dev/cu.SxProS4P4.4) and its device name (i.e. cu.SxProS4P4.4).

On this author’s system, the serial terminal’s device name is ‘cu.SxProS4P4.4′.

B. File: /etc/ttys

On Mac OS X, the Unix program ‘getty’, which runs on startup, looks for and initializes a serial port for use as a terminal that has been enabled by an appropriate line in the /etc/ttys file.

The getty program sets the serial port parameters and waits for evidence of a connection (e.g. a connected user pressing the ‘Return’ key), at which point it prompts the user for his login name and password.

Normally, OS X does not enable access to such serial ports for use as terminals.

Now, using your text editor, open the file /etc/ttys and look for the following lines: [8]

# The tty.serial entry initializes the serial port (if any) for use as a
# terminal (enabling logons over serial). If marked secure, the serial
# port will allow root logons.
# To make the serial port available for outbound
# communications, the tty.serial entry should be turned off
# (set the 4th field to off).

tty.serial   "/usr/libexec/getty serial.57600"  vt100  off  secure
   ^                           ^                  ^     ^     ^
   |                           |                  |     |     |
   1                           2                  3     4     5

Note there are five principle fields, each separated from the others by either spaces or tabs.

The first field specifies the serial port to use. Here, ‘tty.serial’ is specified. Please remember that this author recommends using the ‘cu’ prefix rather than the ‘tty’ prefix when specifying the serial ports.

The second field, in quotes, is the Unix command string to start getty and initialize the serial port according a certain set of parameters stored in the /etc/gettytab file, as specified by the last part of the command. In this example, the command directs getty to use the ‘serial.57600′ entry in the /etc/gettytab file. Note that the ‘57600’ is merely part of the entry name, and does not necessarily set the baud rate, unless the gettytab entry itself so specifies.

The third field directs the type of terminal emulation to be employed. Here, the common DEC VT-100 emulation is selected, although numerous other emulations are available for selection.[9]

The fourth field is a simple flag that either enables the serial terminal (i.e. ‘on’) or disables it (i.e. ‘off).

Finally, the fifth field, marked either ‘secure’ or ‘insecure’, specifies whether the user will be allowed to log on as ‘root’, which will be of interest to serious Unix operators.

On occasion, other fields in addition to the five principle ones will be used to specify additional terminal functions or port parameters, but this author has found that their use from within Mac OS X may be ineffective, and he instead prefers to set those type of items via a proper entry in the /etc/gettytab file.

On this author’s system, the appropriate line in the /etc/ttys file is:

cu.SxProS4P4.4 “/usr/libexec/getty local.57600″ vt100 on secure

Here, we are specifying the serial device to be ‘cu.SxProS4P4.4′, using the ‘local.57600′ entry from the gettytab file and vt100 terminal emulation, and allowing logins as ‘root’.

C. File: /etc/gettytab

The gettytab file is a data base containing distinct entries for different types of terminals. Each entry specifies the configuration parameters for that particular type of terminal, with emphasis on those parameters dealing with serial port and telecom settings.

In the instance where the command line in /etc/ttys directs getty to use a non-existent gettytab entry, gettytab contains a default entry that is used instead, which may or may not result in a working connection, depending upon the characteristics of the terminal attempting to connect.

Gettytab contains a number of pre-configured entries. Unfortunately, this author, and others, have found that most of the ‘pre-made’ entries in the gettytab file are lacking in one respect or another.

In fact, in the comments contained in the gettytab file itself, one can read:

# Most of the table entries here are just copies of the old getty table,
# it is by no means certain, or even likely, that any of them are optimal
# for any purpose whatever. Nor is it likely that more than a couple are
# even correct.

Given this, we will select and modify the ‘best’ of what is offered, and leave the remaining details up to the ‘stty’ command, which is described in the next section.

This author’s experiences indicate that when using a local serial terminal the best results are obtained by working with and modifying the entries beginning with the word ‘local’, rather than those starting with ‘serial’, ‘special’ or ‘std’, as the ‘local’ implementation appears to present fewer compatibility issues.

With that in mind, consider that in most versions of Mac OS X [10], the /etc/gettytab file will contain:

# Entry specifying explicit device settings.  See termios(4) and
# /usr/include/termios.h, too.  The entry forces the tty into
# CLOCAL mode (so no DCD is required), and uses Xon/Xoff flow control.
#
local.9600|CLOCAL tty @ 9600 Bd:\
	:c0#0x0000c300:c1#0x0000cb00:c2#0x0000cb00:\
	:o0#0x00000007:o1#0x00000002:o2#0x00000007:\
	:i0#0x00000704:i1#0x00000000:i2#0x00000704:\
	:l0#0x000005cf:l1#0x00000000:l2#0x000005cf:\
	:sp#9600:

In essence, this entry directs a local (no DCD) connection at 9600 baud, and uses software handshaking (Xon/Xoff). The other lines are ‘flags’ to control numerous parameters, whose explanations are well beyond the scope of this article.

For our purposes, we will want not only a higher speed (57,600 baud), but also hardware handshaking (RTS/CTS), which is essential at higher baud rates and preferred for swift error free Zmodem file transfers.

On this author’s system, the appropriate entry in the /etc/gettytab file is:

local.57600|CLOCAL tty @ 57600 Bd:\
	:c0#0x0000c300:c1#0x0000cb00:c2#0x0000cb00:\
	:o0#0x00000007:o1#0x00000002:o2#0x00000007:\
	:i0#0x00000704:i1#0x00000000:i2#0x00000704:\
	:l0#0x000005cf:l1#0x00000000:l2#0x000005cf:\
	:sp#57600:

Here, notice that we have duplicated all the information from the ‘local.9600′ entry, but have changed the speed specified on the first and last lines from ‘9600’ to ‘57600’. Again, remember that the ‘local.57600′ entry corresponds with the enabling line from the /etc/ttys file:

cu.SxProS4P4.4 "/usr/libexec/getty local.57600"    vt100  on  secure
                                      ^
                                      |
                            points to gettytab entry

Note that in the gettytab entry you would replace the ‘57600’ with the speed you desire for your particular connection. Starting out at 9,600 or 19,200 baud to test your initial connection is recommended.

While this author has successfully used speeds up to 115,200 baud on an Apple IIGS with a 7/32 ZipGSX accelerator card, other machines may need to stay at one of the slower supported rates.

D. File: /etc/profile

There are some serial port settings that are much easier to set and change with the Unix command ‘stty’ than with the ‘flags’ specified by the various gettytab entries. The ‘stty’ command permits control of not only baud rate but also of a myriad of other serial port and telecom parameters.

To avoid the drudgery of specifying these settings manually upon every boot, we will employ the /etc/profile file, which conveniently, contains Unix commands that are executed after getty initializes the serial port.

Thus, by placing the desired ‘stty’ commands in the /etc/profile file, we can tailor the serial port settings for our terminal connection automatically upon every boot.

The lines to be added to the /etc/profile file (with comments) are as follows:

stty -f /dev/cu.SxProS4P4.4 crtscts
# Enable RTS/CTS flow control.

stty -f /dev/cu.SxProS4P4.4 clocal
# Assume a line without modem control (no DCD).

stty -f /dev/cu.SxProS4P4.4 -parenb
# Disable parity generation and detection.

stty -f /dev/cu.SxProS4P4.4 cs8
# Select 8-bit character size.

stty -f/dev/cu.SxProS4P4.4 -cstopb
# Use one stop bit per character.

stty -f /dev/cu.SxProS4P4.4 -iexten
# Disable any implementation defined special control characters
# not currently controlled by icanon, isig, or ixon.
# Also, this is required for error-free Zmodem transfers.

stty -f /dev/cu.SxProS4P4.4 -ixon
# Disable START/STOP output control.

stty -f /dev/cu.SxProS4P4.4 -ixoff
# The system does NOT send START/STOP characters when the input
# queue is nearly empty/full.

Note that you would replace the ‘cu.SxProS4P4.4′ with the name of your particular serial port.

VII. Setting Up the Apple II

Directing the Apple II to act as a serial terminal for the Mac is far less involved than preparing the Mac to allow it to do so.

For these instructions, we will assume that you have connected the two computers with a hardware handshaking null modem serial cable and have installed ProTERM 3.1 on your Apple II. [11]

In the ProTERM ‘Install’ dialog under the ‘Misc’ menu, you will select ‘Null Modem Driver (RTS/CTS)’ for the ‘Modem’, and also select the correct interface for the ‘Port’ as well as the proper number for the ‘Slot’.

For the ‘Init’, you will want the value to be blank, as there is no modem involved in the connection.

In the ProTERM ‘Create System’ dialog under the ‘Dial’ menu, you will first ‘Enter a System’ and then save it. Then under the same ‘Dial’ menu, select the system you just created to bring up the ‘System Parameters’ dialog.

Here, you will leave ‘System Number’ blank, and select ‘Baud Rate’ to match the speed that you entered in the Mac’s /etc/gettytab file and specified in the /etc/ttys file. Next, mark ‘Data Format’ to be ‘8N1′, ‘Duplex’ as ‘Full’, and ‘Emulate’ to read ‘DEC VT-100′. While you are in this screen, select the ‘Parms’ button and for ‘Auto Protocol Start’ select ‘Zmodem’. Save these parameters and then quit ProTERM.

Please be aware of the ‘Preferences’ dialog under the ProTERM ‘Misc’ menu. This area contains many options under the ‘Xfer’ button that will be of interest for file transfers. Although a discussion of these is beyond the scope of this article, you will want to familiarize yourself with them.

Also beyond the extent of this article is ProTERM’s powerful built-in macro language, which can not only take the mundane out of file transferring operations, but also automate many routine Unix tasks, such as the login process. [12]

VIII. Finally – Making the Connection

The moment of truth has arrived, and you will soon determine whether you have successfully made your Apple II an intelligent serial terminal to your Mac.

First, re-boot your Mac. This will allow ‘getty’ to read the changes you made to the /etc/ttys and /etc/gettytab files, and it will allow the ‘stty’ serial port commands you entered in /etc/profile to be executed.

Now, start ProTERM and from the ‘Dial’ menu, select the system you created. When the ‘System Parameters’ dialog box appears, press ‘Dial’.

The screen should clear. At this point, press the ‘Return’ key once or twice, and you will receive your ‘login:’ prompt. Enter your Mac user name and press the ‘Return’ key to receive your ‘Password:’ prompt.

Enter your password, followed by the ‘Return’ key, and you have arrived.

Assuming you have sufficient ownership and permissions for the areas you want to navigate on the Mac, you are now in charge of the Mac, all from the text screen on your Apple II.

When initiating a Zmodem file send from ProTERM, the program ‘rz’ on the Mac will be automatically started to receive the file. Likewise by entering ‘sz [filename]’ at the prompt, ProTERM will automatically begin receiving the file specified by [filename].

Note that if you prefer to send files to, and receive files from, the Mac’s Desktop, just enter the command ‘cd desktop’ at the prompt to work from there.

IX. Conclusion

Assuming you have managed to read this far with clear, unglazed eyes, you have what it takes to set up your Apple II as an intelligent serial terminal to your Mac and easily transfer files between the two systems without interaction on the part of the Mac user. This can be tremendously useful in mixed Apple II – Mac OS X environments.

Moreover, if, like this author, you are relatively unfamiliar with the Unix operating system and the possibilites for useful computing it provides, you may want to learn more and venture further. The Book ‘Learning Unix for Mac OS X Tiger’, written by Dave Taylor and published by O’Reilly Media, will prove to be a nice introduction.

In any case, enjoy the experience of harnessing the power of Unix and commanding the Mac from the keyboard of your Apple II.

ENDNOTES

[1] Of particular interest to Apple II users will be Andy McFadden’s excellent ‘Nulib2′, which is a Unix command line archive utility. It permits performing many common operations on NuFX (ShrinkIt) and Binary II archives, including creating new archives, as well as listing, adding, deleting, and extracting files from existing archives. In addition, it strips any Binary II header from a transferred file, and preserves the ProDOS file attributes when extracting files from NuFX archives to Mac HFS-formatted volumes.

[2] Both Kelvin Sherlock’s ProFUSE file system for MacFUSE (currently read only, with mounting of ProDOS disk images from the command line) and the pending prodosfs file system for MacFUSE (read/write) should rectify this longstanding shortcoming of OS X.

[3] Due to a bug in the RTS/CTS hardware handshaking control logic in the 6551 ACIA serial controller used in the original Apple Super Serial Card, users desiring error free RTS/CTS hardware handshaking transfers should purchase the later revision 65C51 ACIA to replace the original 6551 IC.

Also, David Schmidt’s ADTPro uses the Super Serial Card (without the Turbo ASB daughtercard) at up to 115,200 baud by accessing a special hardware register on the card. I suspect ProTERM 3.1 will be patched in the future to provide this capability.

[4] This patch will be distributed as a commented ProTERM macro that can be executed from within the program.

[5] The Beige Power Macintosh G3 (circa 1998) was the last Mac that contained a native serial port. Fortunately, adding a serial port to more modern Macs is easy. Options include, but are not limited to (i) GeeThree’s Stealth Serial Port / Griffin Technologies gPort (installed in the modem card slot) (ii) Keyspan’s SXPro4 PCI Card (providing 4 serial ports) (iii) IOGear’s Bluetooth Serial adapter, and (iv) Keyspan’s USA-28XG USB Twin Serial Adapter (providing 2 serial ports).

[6] This author’s Mac text editor of choice is Bare Bones Software’s BBEdit, although purists may be perfectly content with any of the Unix editors included with Mac OS X, including ‘vi’, ‘pico’ and ‘Emacs’.

[7] Others prefer listing and using the ‘tty’ serial devices rather than the ‘cu’ devices, but this author has found better reliability on ‘local’ connections using ‘cu’ devices, as apparently they are less sensitive to the status of the serial ‘DCD’ line, and may, in fact, ignore it entirely.

[8] In Mac OS 10.5 Leopard, the /etc/ttys lines mentioned here appear to have been removed, possibly in an attempt to discourage serial terminal use for security reasons. Although this author has not had access to a Leopard system for testing purposes, he suspects these lines may be added back to the /etc/ttys file in order to re-enable serial terminal support.

[9] Type in the Unix command “toe” at your Unix prompt and you’ll be presented with dozens of supported terminal types in addition to vt100, including appleII and appleIIgs, as well as commodore, amiga, and atari, lisa, linux and many vt*** type emulations. This command lists the Unix table of terminfo entries.

[10] In Mac OS 10.5 Leopard, the /etc/gettytab entries mentioned here appear to have been removed, possibly in an attempt to discourage serial terminal use for security reasons. Although this author has not had access to a Leopard system for testing purposes, he suspects these entries may be added back to the /etc/gettytab file in order to re-enable serial terminal support.

[11] While ProTERM 3.1 was recently reclassified as freeware and thus is an outstanding value, it is by no means the only Apple II telecommunications program capable of performing the tasks outlined in this article. For Apple IIGS users running GS/OS, Ewen Wannop’s excellent program ‘Spectrum’ will match, and in some cases exceed ProTERM’s capabilities, including macro support, multiple terminal emulations and Zmodem file transfers.

With its macro capabilities and TimeOut modules, AppleWorks 5.1 would normally be considered up to this job. Unfortunately, TimeOut Telecom, which runs from within AppleWorks, is a poor choice in this situation. It doesn’t support VT100 terminal emulation nor Zmodem file transfers, and drops characters on the screen display at speeds over 4800 baud.

[12] For example, one macro exploits the power of ProTERM to read native AppleWorks Word Processor (AWP) files. The macro allows the user to select the file, transparently converts it to a plain text (.txt) file, and then does a Zmodem file transfer of the converted file to the Mac, for use in any Mac program able to read text files, including Microsoft Word and Entourage.