https://DevOpsCloud.io -- Cloud Monk Losang Jinpa

Return to Apple II

• Using an Apple IIe as a serial terminal with Gentoo Linux by Quag7 (July 4, 2007) - Apple II as a serial terminal with Linux

This document provides step-by-step instructions on configuring an Apple //e to act as a serial terminal for a GNU/Linux computer. It includes directions on downloading and installing communication/terminal software for an Apple 8 bit system, configuring the Apple's terminal emulation and serial communications, and setting up the Linux machine to utilize the serial port.

A visitor to our IRC channel, #rasterburn (jescis) asked what stood in for the ALT key on an Apple IIe. We couldn't figure it out. If you know how to type an ALT-something on an Apple IIe (in MODEM.MGR), please mail me at the address in the footer of this page, even if it's an awkward workaround. Thanks!

Before I get started on this painstakingly detailed how-to, I want to make clear to anyone reading this that for those who haven't considered trying this, this is not an original idea and I am not representing it as such. Anyone who has considered this knows that this *can* be done, but I felt the need to actually, you know, do it, for some reason. At the end of the day, when the hookers are all asleep, the eight ball is gone, and the BATF has made a ghastly mistake and kicked in the door of the octogenarian Christian Scientist next door, you might be feeling a little out of sorts. This is a fun little project for those times, and one of the best things about it is that, in turning your mind toward matters retrocomputery and technical, you can stop adding to the odious list of sins and treachery that you've been compiling over the last 48 hours. As you reflect upon each and every atrocity against Man and God that you have committed (perhaps to your parish priest), you can make a mental note that it all stopped when you started screwing around with the null modem cable.

Presumably, many have done this before and could not bothered to document it because it was considered trifling. Well, I have spent far more time on things far more pointless, and, so, it is in consideration of ye idle sleepless sinners, that I write to you this here, uh, procedure, for taking an Apple IIe and using it as a a serial terminal for your GNU/Linux box.

These instructions were written for a Gentoo Linux machine but they should be easily adaptable to any distribution you run, so if you're part of the great gothic hordes of (x)buntu users (Dear hordes: just kidding about the gothic part), you could probably adapt these instructions to your hippie distribution without too many problems (yes, I said it.)

The end result of this process is a fairly usable serial terminal.

Contents Thanks Checklist - stuff you need Configuring your Linux system for serial support The physical serial connection Using ADTPro to create a Modem.MGR floppy disk Configuring Modem MGR Configuring Linux to use a serial terminal Boot Modem MGR and configure baud rate and terminal emulation + establish serial connection Screenshots Other wastes of time and bandwidth Photos of the Apple //e as a serial term sent by others

Thanks Paul Weinsten (pdw) - After having problems with VT52 for days, which was the only emulation the Apple terminal software I was using would support, I came across pdw's page about hooking up an Apple IIc as a serial terminal. He writes about a program called Modem.MGR which can emulate VT220, which does the trick. VT52 is inadequate for many Linux applications. With VT52, my screen would become corrupted with uninterpreted escape sequences. So thanks, pdw! Devin Reade - Devin's 1998 description of How to Hook an Apple IIgs up to a Linux Machine via a Dedicated Serial Line was invaluable. ADTPro Team - ADTPro allows you to bootstrap an old Apple with no DOS, from “bare metal,” as they put it. This remarkable program can help anyone breathe life into an old neglected Apple 8 bit. It's still my favorite of any of the retrocomputing utilities I've encountered. You can go online, pick up an old Apple //e, and make it useful without having to track down any floppies. None of this would have been possible without this application. ADTPro rocks, and you'll see why as you read on. Back: Table of Contents

Checklist - stuff you need A Linux machine with a working serial port. A working Apple //e system. Super Serial II Card or Super Serial Board which can be purchased new for $12.95. Jumper settings and configuration are the same for each card. ADTPro software for transferring software from PC across serial cable to Apple IIe. Modem.MGR, terminal/communication software for the Apple II series. I used the ProDOS version. So should you, unless you have some kind of weird DOS 3.3 fetish. I have relentlessly queried Google's image search for such a thing, but I have not gotten any juicy hits. However, I've been on the internet long enough to know there's at least one of you out there with this kink - maybe some sort of Woz cosplay thing; I'm still working that out as a purely theoretical consideration. Null modem cable and any gender changers and/or extension cables needed to connect the Apple to your PC. Since it has probably been awhile, remember that null modem cables are not the same as straight serial cables. The transmit and receive lines are crosslinked in a null modem cable. I was able to buy one of these off of the rack at CompUSA, so they're not difficult to find. Mine was listed, perhaps confusingly, as a “data transfer” cable in a “null modem configuration.” I also used a “straight through” switchbox cable to extend this and a 9 to 25 pin adapter. The Apple serial cards provide a DB25 female plug that I connected to a 9 pin serial port on my PC via an adapter. You'll have to assess your situation; the important thing here is to make sure there's a null modem cable hooked in there somewhere to crosslink the transmit and receive. Online documentation about cables tends to make the assumption that we all like to solder our own and read pinout diagrams (speaking of weird fetishes…). Not me pal, but if it's your thing, well, your kink is OK. Fortunately, everything you need can be bought at a brick-and-mortar computer store or online. This is what I used:

Belkin Pro Series Serial Direct Cable - (F3B207-06) - DB9 (F) to DB9 (F) null modem cable. Serial Cable Adapter (DB9 to DB25) - (F2L087) - DB9 (M) to DB25 (F) Belkin Pro Series Switchbox Cable - (F3D111-06) - DB25 (M) to DB25 (M) No, I am not a Belkin stockholder and frankly I think some of their electronic equipment sucks. Their cables seem to work fine. If my Belkin references in an article like this causes some sort of run-up on Belkin stock, we are deeply screwed as a civilization. Even more screwed, I mean. More screwed than the guy Dick Cheney SHOT IN THE FACE.

Thanks to the ADTPro development team, you won't actually need any software or DOS disks for your Apple system. If you just grabbed one from a junk pile or bought one off of ebay, you can follow the ADTPro instructions for bootstrapping from bare metal which will give you a bootable ADTPro disk, which also has ProDOS. But I'm getting ahead of myself. First thing we need to do is make sure your Linux system has proper serial support. It occurs to me that this last sentence has probably never been uttered, even once, at the Playboy mansion. This should depress both of us.

Back: Table of Contents

Configuring your Linux system for serial support The first thing you will need to do is ensure that your kernel has been configured to load the proper modules for your serial port. I have been a Gentoo user for several years now so I haven't looked too closely at the many “kitchen sink” distributions out there but I would guess that most of them ship kernels with serial support compiled in or available as a module. In any case, should you decide to configure your own kernel, you can find what you need in:

Linux kernel configuration: Serial drivers section Linux kernel configuration: Serial drivers

Compile serial support into kernel. Device Drivers

       Character Devices
              Serial Drivers

You will need:

<*> 8250/16550 and compatible serial support Previously, this stated that “Console on 8250/16550 and compatible serial port” was necessary as well. This is not the case.

Tim Riker sent an e-mail stating:

FYI: the kernel config option “Console on 8250/16550 and compatible serial port” allows the kernel to output boot messages to a serial port. This option is NOT required to run a serial terminal.

The agetty line you have will work just fine without it.

If you do have kernel serial console support built in, then you can alter the kernel boot options to see bootup messages. Adding this:

console=tty1 console=ttyS0,9600N81

should get console messages on both the video screen (tty1) and the first serial port at 9600 bps, ie: your apple.

WARNING: this also means that kernel error messages will show up on this output device, which may mess up any binary transfers in progress.

1. setterm -msg off

should disable this. Note that these are the names/descriptions in the 2.6.23 kernel. They may change by the time you read this.

Recompile your kernel and reboot if necessary. Your distribution's website should have instructions and how-tos on compiling the kernel for your distribution. Gentoo users do this in a fairly raw way; there is a “Debian way” which involves making the kernel into a .deb package which can be installed and uninstalled at will, though you can do it the cheap and sleazy way if you like.

If you have never compiled your own kernel, this is a good excuse to learn how to do so since the modifications you have made here are fairly minor and the chances of disaster are minimal. It is not a complicated process at all. If you are completely new to it, your best bet is to follow the process specifically outlined for your distribution. This way, if you need to go to mailing lists, IRC, or message boards for further help, people won't wig out at you and curse the next seven generations of your family for doing it the “wrong” way.

Back: Table of Contents

The physical serial connection If you can, make sure the serial card is in slot #2 in the Apple.

You can put it in any other slot (I think) except for slot #3, but will be easiest if you put it in slot #2 since that is the traditional slot for that card, and the directions from ADTPro will assume you are using slot #2. For awhile, I had the card in slot #4, and ADTPro handled this fine but a few of the term programs I used couldn't find it. In addition, ADTPro will default to slot #6 for your drive controller, which is also the traditional slot for that card. This is the greatest number of times I have ever used the word slot in a single paragraph. And I used <strong> tags for each. Isn't that, like, beyond obsessive? Yeah, and Catcher in the Rye is my favorite book too and one time I pulled a cat's tail. ph33r me.

I didn't have to power down my PC to hook the serial cable up and make it work. Make sure the ribbon cable off of which the female DB25 plug hangs from the Apple is plugged into the slot correctly with the “buckle” side facing outward from the card. Then go ahead and connect everything.

Important Note: It is extremely important that you properly configure the serial card. The appropriate settings and further instructions are helpfully documented on the ADTPro page on serial connections.

Two possible configurations are offered:

Straight-through / terminal connection Null-modem / modem connection Choose null-modem / modem configuration.

Since we're using a null modem cable, the block should be inserted with the arrow pointing upward. Make sure all of the switches are set as indicated. This should take you a minute or two at the most.

The classic Super Serial II card and Super Serial Board are clones (or look that way from the user's side), so the configuration is exactly the same. I don't know about the old Super Serial II cards, but the Super Serial Board's block pops off fairly easily using only your fingers. A chip puller might be prudent, but I didn't have one and the block popped out without a problem, leaving all the pins happily intact. I left my chip pullers back in the 1980s, along with the trauma that resulted from watching that bit in the When Doves Cry video where Prince stands up in the bathtub and beckons you, the viewer, to come closer. What the hell was that all about, anyway?

Back: Table of Contents

Using ADTPro to create a Modem.MGR floppy disk The recommended program for the purposes of a serial terminal is Modem.MGR owing to its excellent VT220 support. VT220 emulation is necessary for the escape sequences and cursor movement that many Linux applications require. Other emulations such as VT52, VT100, and VT102, will give mixed results. Modem.MGR may be downloaded here.

If you know how to turn these images into floppies (or already have Modem.MGR floppies ready to boot), do so and continue on to Configuring Modem.MGR, otherwise…

The next steps are:

Download and install ADTPro on your Linux PC. Transfer ProDOS into the Apple's RAM via serial cable. Transfer the 8 bit ADTPro software into the Apple's RAM via serial cable. Use ADTPro to transfer itself across the serial cable a second time, and write this instance to a floppy disk. Boot ADTPro on the Apple side via the floppy you just created. Download and unzip Modem.MGR from the Internet (if you have not already done so) on your Linux PC. Send the Modem.MGR disk images over the serial cable via ADTPro, and create bootable Modem.MGR floppy disks on the Apple side. I have broken the ADTPro procedure out into its own document:

Using ADTPro to create an Apple 8 bit-readable floppy from a disk image downloaded from the Internet

If you already have Modem.MGR floppy disks, you can skip these steps and continue with Configuring Modem.MGR.

Back: Table of Contents

Configuring Modem.MGR Modem.MGR: Insert Work Disk Modem.MGR: Insert work disk

The work disk will be the one you boot from. The installation disk is necessary only for the initial configuration.Modem.MGR: Main Installation Menu Modem.MGR: Main installation menu

Modem.MGR: Install Video Driver Modem.MGR: Install video driver

Select Option 2: Apple // 80 columnModem.MGR: Install Modem Driver Modem.MGR: Install modem driver

Select Option 2: Internal plug-in serial/comm. card with external modemModem.MGR: Install Serial/Comm. Card Driver Modem.MGR: Install serial/comm. card driver

Select Option 3: Apple Super Serial (If that is what you are using)

Then specify which slot the card is in.Modem.MGR: Install External Modem Driver Modem.MGR: Install external modem driver

Select Option 10: Non-smart Modem Insert the installation (MMGRPDINST.DSK) floppy into drive 1, and, if you are still looking at an ADTPro screen, reboot by power cycling the machine or using the Apple 3 finger salute, which is CTRL-Open Apple-Reset. Modem.MGR will begin the booting process. You will be prompted to install the work disk at some point, and will then be asked to re-insert the installation disk. Just follow the directions on the screen until you get to the MAIN INSTALLATION MENU. When you are at the MAIN INSTALLATION MENU, select option 1, Install video driver and press Return.

Assuming your Apple IIe supports 80 columns, select option 2, Apple // 80 column. Otherwise, select option 1, Apple 40 column.

If you plan on running in 40 columns, you might want to reconsider running as a serial terminal and play Ultima IV instead, or perhaps join the lower-caste Commodore community and learn to live as a Morlock.

Wow, that was dorky even for me. (And before you get snippy, I grew up a Commodore user - This serial terminal is my first Apple 8 bit system, and I bought it from ebay in 2007. Whatever the Commodore 64's virtues, 40 columns sucked then, and it sucks now.)

There are other options here as well. If you have the requisite hardware, give them a try. You can always boot the installation disk again and reconfigure. Press Return. You will be asked whether you want Normal or split-screen. Enter N for normal and press Return. Enter Y for Yes to confirm, and press Return again. Your selection will be confirmed. Press a key to return to the MAIN INSTALLATION MENU. Press 2, install modem driver and hit Return.

Select option 2, Internal plug-in serial/comm. card with external modem, even though you aren't actually using an external modem. Press Return. You will then be asked to select the serial/comm. card you are using. Select option 3, Apple Super Serial, and press Return.

You will be asked what slot the card is in. That should be slot #2 if you followed my advice. Otherwise, enter the slot your serial card is in and press Return. Confirm your selection by pressing Y and hitting Return.

Your null modem cable essentially allows communications software to read and write to the serial port / cable as if it were a modem. So as far as any communication software you might use is concerned, there's a modem connected (albeit a null one). Next, you will be asked what modem you are using. You will lie nakedly and deceptively to Modem.MGR, and you will feel no guilt in doing so because that is how you roll.

Select option 10, Non-smart Modem because your null modem cable is an AT-command set-impeded neanderthal grunter at best, and press Return. Confirm with a Y, and hit Return. Then press any key to return to the MAIN INSTALLATION MENU again. That's it for configuration. Press 9, Save new installation, and hit Return to save your configuration. You'll be asked to insert the WORK disk. Do so and press Return. Your configuration will be written to this disk. Leave the WORK disk in the drive for now because you're going to be booting from it shortly. Back: Table of Contents

Configuring Linux to use a serial terminal These instructions are for Gentoo Linux but they are probably the same, or similar, on other distributions. All that is involved is configuring /etc/inittab to have /sbin/agetty attach to the serial port. A cursory look at my file server suggests that Debian uses the filename getty which I take to be the same program as agetty, since the man page pulls up the agetty page. (Hey don't look at *me*).

First, make sure anything that uses the serial port is closed, and this includes ADTPro, which may still be running from before. Close it down, along with anything else that touches the serial port. When one program is using a serial port, it writes a lockfile to prevent other applications from attempting to use it, so if something is open that is already using it (and locking it), you may have problems. Accordingly, once /sbin/agetty is attached to the serial port, you won't be able to use ADTPro. In order to get ADTPro working again, you're going to have to detach /sbin/agetty from that port by commenting out the line you're about to uncomment in /etc/inittab and using the init q command to reload /etc/inittab, which is described below.

As root, open /etc/inittab in your favorite editor. Try hard not to screw up this file, because it is important. You might want to make a backup of it first. If you are a Gentoo user you are probably used to rampaging through your system like a crack-addled wolverine, so you will probably skip this step. I mean, I did.

Next, scroll down to the section cryptically titled SERIAL CONSOLES. You'll see example entries for ttyS0 (first serial port) and ttyS1 (second serial port). Choose the one you have the Apple connected to and uncomment it. Make sure the speed is set to 9600, and change the terminal emulation to vt220, so that the line looks something like this (Make sure to use the line pointing to the right port for your configuration):

1. SERIAL CONSOLES

s0:2345:respawn:/sbin/agetty 9600 ttyS0 vt220 Save the file and exit back to the prompt.

Now we need to make the system reload inittab to see the change you just made. At the prompt, as root, enter:

init q The system won't print a confirmation message. it will simply return you to a prompt.

Note: If you want to use ADTPro to transfer files again, your best bet is to comment out the same line you just uncommented in /etc/inittab and enter init q to reload/re-read it. Generally speaking, the line should be uncommented when you want to use the serial terminal, and commented out for everything else.

You may also want to review Tim Riker's comment about seeing boot messages on the serial console.

Back: Table of Contents

Boot Modem.MGR and configure baud rate and terminal emulation + establish serial connection Modem.MGR Configuration Menu Terminal Mode Modem.MGR Configuration Options

Choose terminal settings.Modem.MGR Terminal Mode: Baud Rate Terminal Mode Modem.MGR Baud Rate

Selection Option N: 9600Modem.MGR Terminal Emulation Terminal Mode Modem.MGR terminal emulation

Select Option V: VT220 Emulation Make sure the Modem MGR WORK disk is in Drive 1. Reboot the system by power cycling or use the Apple three finger salute (CTRL-Open Apple-Reset).

When Modem MGR boots, you'll see a list of options. If you've come down off of your savage binge, you'll also probably be alert enough to notice that the screen is displaying a very useful 80 columns, provided your system supports it and you configured Modem.MGR properly. There are two remaining things that need to be set here:

Baud Rate: Press ESC and then M for Modem Baud Rate. Set this to N for 9600. You will be asked to “Wait.” but there is nothing left to do to (presumably it is waiting for AT command responses, since it thinks it is talking to a modem). The baud rate is now set. If for some reason you set your baud rate to something other than 9600 in /etc/inittab, make sure the numbers match. Terminal Emulation: To set up terminal emulation, press the CTRL-ESC key and then the : (colon) key at the prompt that appears.

Select option V for VT220.

There is no need to press Return. For future reference, Open Apple-ESC will bring back the help menu, since you probably noticed you're looking at a blank screen now. Now, press Return. If everything has gone properly, you should see a Linux login prompt.

Now do the Apple-8-Bit-Computer-Still-in-Use-as-a-Serial-Console-in-the-21st-Century dance. Get all crazy mad stupid fresh, too, like the way Rerun used to pop and lock in WHAT'S HAPPENING!!

Turn the Caps Lock off and log in. Run top. This is a good way to test your terminal emulation. If you see a lot of escape codes, and/or the screen scrolls rather than re-draws, you may have to re-set the terminal emulation on the Apple side again.

To do this, simply press Open Apple-ESC to bring up the menu. Then press ESC by itself, then : (colon), then V for VT220. Very occasionally noise corrupts my terminal (such as if I cat a binary file by mistake) and Modem.MGR seems to revert to some other less satisfactory emulation. I use this process to re-set Modem.MGR to VT220, and that's generally enough to clean things up.

Press Return a few times, then run top again. Hopefully, the screen will redraw properly, if a little slower than you are used to. That's life at 9600 bps, baby. Or Baud if you're old sk00l. And wrong. (No I am not that pedantic, but some dork reading this will be. That is, if anyone reads this at all.)

Back: Table of Contents

Screenshots Linux login prompt on Apple IIe Linux Login Prompt on Apple IIe

The first thing you'll see… Apple IIe - configuring a kernel with menuconfig make menuconfig

Configuring the Linux kernel.

Lack of extended ASCII makes things a little messy, but usable. Apple IIe - Connecting to the Late Night BBS ddial telnet - ddial

Telnetting to a real telnet-accessible ddial running on original Apple 8 bit hardware.

Unfortunately, this is now defunct. Apple IIe - www.textfiles.com via links2 browser Links2 - web browser

Viewing http://www.textfiles.com

This is one of the few web sites to display gracefully in console-based web browsers. Apple IIe - nano nano

Default text editor in Gentoo.

Clone of pine's pico Apple IIe - linux_logo - Gentoo Logo Linux Logo

w/ -L3 argument (Gentoo logo) This has been changed to -L2 in subsequent versions. Apple IIe - top top

Apple displays process data for Gentoo box Apple IIe - standard directory listing Directory listing Apple IIe - irc via Rhapsody client - Undernet IRC

Rhapsody IRC client on some ghetto Undernet piracy channel Apple IIe - Editing /etc/inittab with vim vim

Popular text editor Apple IIe - www.gentoo.org via links2 browser links2 - web browser

Viewing http://www.gentoo.org Apple IIe - pine pine

The famous console-based e-mail client

The first internet e-mail I ever received, I read in pine. Apple IIe - Connected to Monochrome BBS telnet

Telnetting to the UK's unique Monochrome BBS

Telnet to: mono.org Apple IIe - VNStat monthly bandwidth report VNStat monthly bandwidth report

Monthly bandwidth usage measured on router by VNStat Apple IIe - Output of tty and w commands tty and w output

Shows which tty is in use + who is connected to the system Apple IIe - Cottonwood BBS login screen (Apple connecting to a telnettable Commodore board) Cottonwood BBS login screen

Telnetting to a BBS running on original Commodore hardware.

Telnet to: cottonwood.servebbs.com Apple IIe - IRC via weechat IRC via weechat

weechat works particularly well as a console-based IRC client. Apple IIe - slurm realtime bandwidth monitor slurm realtime bandwidth monitor

You can see “ghosts” of the cursor in the photograph as it continuously redraws the screen at 9600 bps. Apple IIe - running linux_logo Running linux_logo next to its little Commodore buddy.

Commodore 128 serial terminal - COMING SOON! Apple IIe - linux_logo linux_logo Apple IIe - IRC via weechat IRC via weechat Back: Table of Contents

Other wastes of time and bandwidth Well, now you're using your Apple IIe as a Linux terminal. The only major drawbacks are 9600 bps refresh, which is not really much of a hindrance for most applications, and extended ASCII characters won't draw properly, but that's a minor nuisance. You might also miss having a numeric keypad and Page Up/Page Down keys. The arrow keys on the Apple IIe are positioned…oddly. If you started out as a hobbyist on 8 bit computers, however, you may find yourself reverting to old habits which work around these problems pretty well.

There's more you can do with your old Apple. For example, there is the Contiki operating system with a TCP/IP stack. This includes a web browser, telnet client, rudimentary IRC client, and proof-of-concept web server. You might find the Wikipedia article interesting. To use this, you'll want to get this network card. I have this hooked up and it works, but, due to the primitive nature of Contiki's offerings on the Apple platform (for example, the IRC client cannot handle private messages), you will probably find your old Apple is far more useful as a serial terminal running Linux's myriad console offerings.

I would also add, for those of you who might get a kick out of running a website on your old Apple, the web server provided by Contiki does work, but it has hard-coded content. There's no interface for Apple I/O, so you can't, for example, serve your own HTML off of a floppy. There's no reason someone couldn't code this if they knew what they were doing, but no such thing yet exists.

Huge bundles of Apple software are available in the usual …places… on the internet. Many of them are available as TOSEC packs, properly named and cataloged according to that standard (Note that TOSEC itself does not release these - they simply maintain a database and naming scheme for old software). The status of software in these packages ranges from freeware, to gray-area abandonware, to status unknown, to OMFG warez. I'm not going to make a statement about how I feel about this, but it would be nice if software developers of that period who don't mind their software being used by retrocomputing hobbyists would step forward and explicitly say so. Nevertheless, emulation enthusiasts have done a remarkable job of preserving a great deal of software from the old days, thoughtfully packaging much of it up as ADTPro-transferrable DSK images. Download and use it at your own peril (and/or conscience, where matters of conscience apply).

Lastly, there are a variety of Apple hobbyist sites on the internet. I should mention A2Central which maintains a lot of information and hosts a BBS (by which I mean a real BBS, not a web board).

Speaking of Bulletin Board Systems, where are the Apple 8 bit retro-boards? There are several telnet-accessible BBSes running on Commodores, and even some on old Ataris, but only one running on an Apple: The Age of Reason, Gene Buckle's board. You can check out The Age of Reason by telnetting to: aor.retroarchive.org

If you run, or know of someone running a BBS on an old Apple, please mail me at the address at the bottom of this page so I can mention it here.

Tune in next time when I build a supercomputing cluster out of TI-99/4a systems running a h4x0r3d version of CP/M that can predict the weather for the next thousand years and dynamically generate printable 80 column ASCII pornography via images captured realtime from from Britain's growing Orwellian Big Brother camera network.

Actually, I've done this serial terminal project with a Commodore 128, and that procedure is coming soon, though it's a little more complicated.

https://web.archive.org/web/20100817014158/http:/dataswamp.net/apple2eserialterm/index.php