Using ADTPro to transfer a disk image from a Linux PC to an Apple IIe

• Apple II system with at least 64K memory. I have used this exclusively with an Apple //e.
• Super Serial II Card or Super Serial Board (a clone)
  
  You can purchase a Super Serial Board here. This is what I am using since the Super Serial II card in the system I bought was completely dead. I had no problems with the vendor or the product.
  
  Note that ADTPro can also transfer images via Ethernet (such as via an Uther Apple II Ethernet card), via the Apple's cassette port, or via the modem port on an Apple IIgs. For the purpose of this essay, we will only be covering serial communications. For more information on other interfaces, see the ADTPro website.
• ADTPro software, which you can download here. You want the adtpro package. This package contains everything you need for both your Linux machine and the Apple II.
• Dependencies. On Gentoo Linux, this was Java. You might also have to make a path modification. This is covered below.
• Null modem cable and any necessary connectors. Though ADTPro can work with a straight serial connection, we will be covering null modem connections for the purpose of this essay. Cable and adapter recommendations can be found here. Instructions on how to configure your serial card, what you need in your Linux kernel for serial communications, and how to connect everything can be found here. These procedures are part of the larger Apple IIe serial terminal essay.
• DS/DD Floppy Disks. I bought a hundred from some dude on ebay. You can find floppies from various retailers but you will probably get them much cheaper from ebay.

Back: Table of Contents

ADTPro simply runs a listening server on your PC, and a client on your Apple 2 system. You set the "working" directory - that's the directory with the Apple software you want to transfer - on your server/PC machine (this can also be set on the client/Apple side, but it is easier to do from the server/PC side). On the Apple side, just specify the name of the Apple disk image you want to transfer, and the image will be sent across the serial cable while progress bars on both sides show you the status of the transfer. The image will then be written to the floppy on the Apple side, which should then be bootable.

If you don't have an ADTPro disk ready to go, you'll have to bootstrap your machine. This involves:

1. Sending ProDOS over the serial cable to the empty Apple, directly into RAM
2. Sending ADTPro over the serial cable to the empty Apple, directly into RAM
3. Sending a (bootable) disk image of the ADTPro client over the serial cable, and writing it to disk.

Once the ADTPro disk is created, you can boot the client with this disk from that point on and immediately start transferring disk images. Once we get to this point, we will transfer the disk image for Modem.MGR.

Back: Table of Contents

ADTPro is not contained in the package managers of any of the Linux distributions I have handy at the time of this writing (Gentoo, Debian, Ubuntu), but it makes sense to check yours to be sure. There is probably not a lot of demand for this application relative to others, so you'll probably have to download and unpack it yourself Grab the tarball (.tar.gz).

Fortunately, ADTPro is a Java application, so Java appears to be the only actual dependency you'll have to worry about.

Once you've downloaded it, untar it and cd into the new directory. Obviously, the filename will change as new versions are released. At the time of this writing, it is:

tar zxvf ./ADTPro-1.0.6.tar.gz
cd ./ADTPro-1.0.6

Since this is a Java application, there is no compiling as such. You should feel free to put the ADTPro directory somewhere permanent, like /opt/adtpro. The directory structure is self contained, so it won't scatter files across your system.

You might as well try running it as-is first:

./adtpro.sh

If you get no errors, the ADTPro server application appears, and you see the following in your console, you're ready for the next step:

ADTPro Server version 1.0.6

RXTX: Experimental:  JNI_OnLoad called.
Stable Library
=========================================
Native lib Version = RXTX-2.1-7
Java lib Version   = RXTX-2.1-7

Note: You may see a message about a stale lock file being removed. This is normal; it's just cleaning up an old lock file that is lo longer in use.

RXTX: java.lang.UnsatisfiedLinkError: /mnt/archive/incoming/adtpro/ADTPro
-1.0.6/lib/rxtx/Linux/i686-unknown-linux-gnu/librxtxSerial.so: /mnt/archi
ve/incoming/adtpro/ADTPro-1.0.6/lib/rxtx/Linux/i686-unknown-linux-gnu/lib
rxtxSerial.so: wrong ELF class: ELFCLASS32 (Possible cause: architecture 
word width mismatch) thrown while loading gnu.io.RXTXCommDriver
Serial library not installed.

nano -w ./adtpro.sh

export MY_JAVA_HOME ...

export MY_JAVA_HOME=/opt/emul-linux-x86-java-1.6.0.03/bin/

./adtpro.sh

ADTPro Server version 1.0.6

RXTX: Experimental:  JNI_OnLoad called.
Stable Library
=========================================
Native lib Version = RXTX-2.1-7
Java lib Version   = RXTX-2.1-7

check_group_uucp(): error testing lock file creation Error details:Permis
sion denied check_lock_status: No permission to create lock file.

./adtpro.sh

ADTPro Server version 1.0.6

RXTX: Experimental:  JNI_OnLoad called.
Stable Library
=========================================
Native lib Version = RXTX-2.1-7
Java lib Version   = RXTX-2.1-7

Back: Table of Contents

By this point, the following should be complete:

• ADTPro is running without errors.
• On the Apple side, your serial card is configured properly.
• All the cables are hooked up.
• Serial support is compiled into your Linux kernel.

Now it is time to load ADTPro into RAM on the Apple side in two steps:

1. Send ProDOS across the serial cable into the Apple's RAM.
2. Send the ADTPro client across the serial cable into the Apple's RAM.

This is just downright fun if you are a nerd like I am. Lines and lines of hex will fill the screen (nearly as visceral a thrill as watching compiler output on Gentoo!) as ProDOS streams across the serial cable. (Dude, you ever USE Gentoo? On a fast system, you know, whatever, but my last system was a 1 GHz Pentium Celeron and I swear, it was like The Jaunt - you ever read that? Longer than you think, indeed. I've seen Michael Bay films that don't drag as much, and that's saying a lot. God I hate Michael Bay. I hate every stupid film him and his buddy Bruckheimer have ever put out. What is it with geeks, anyway, that they'll watch any piece of crap, as long as it has explosions and guys in spandex suits? Seriously, some otherwise intelligent people are as bad as rap fans when it comes to forking money over for crappy movies.)

Err, anyway, turning on the Apple IIe.

As the instructions on the ADTPro site indicate, turn on the Apple and immediately hit a CTRL-Reset to abort the attempt to load an OS from the floppy drive. Your best bet here is to leave the drive door open, CTRL-Reset to abort the boot attempt, then insert a blank DS/DD floppy disk. You will have an opportunity to format this later, so don't concern yourself with that. If the disk you will be using for ADTPro is used or in an unknown state, you will be overwriting everything with a disk image, so keep this in mind.

You should be looking at a prompt -- a lonely prompt with a blinking cursor on an otherwise blank screen.

ADTPro should already be running. If not, run it via the shell script you edited earlier. Remember, you will probably have to be root. Be sure to look for any errors in the console:

./adtpro.sh

Click the Serial button. If this is your first time running ADTPro, a configuration dialog will come up. Your mileage may vary, but what works best on my system is:

Earlier versions of ADTPro had a Pacing default of 75. I tried this initially but I experienced some corruption at that speed. Pacing seems to set a delay between lines of data sent across the serial cable for the purpose of bootstrapping. As this is a raw data stream, I don't think there's any kind of error checking or correction, so it doesn't hurt to be a little more conservative here. 150 increases the delay between lines and seems to work consistently for me. In any case, you will likely only be bootstrapping once to make your bootable ADTPro floppy anyway, so don't sweat the slightly slower speed.

Note that you can change these settings in File > Serial Configuration.

Click the Serial button. This will activate the Serial connection from the PC side. You will see Connected. on the bottom of the ADTPro application. You will need to do this every time you boot ADTPro.

Sending ProDOS:

Next, we're going to send ProDOS over to the Apple. Select Bootstrapping > ProDOS > Send ProDOS. A box will pop up telling you to type some stuff on the Apple. The example it gives assumes you have your serial card in port 2:

IN#2  Press Return 
<CTRL-A>  The serial card will prompt.  On my system this is APX-SSB-1: 
14B  Press Return 

You will be back at a prompt, as if nothing has happened.

However, the Apple is now ready to receive data - to be programmed, really, via input from the serial cable.

Click OK ADTPro to begin bootstrapping. If your serial connection is set up properly, you will see data fill the Apple's screen. [ Video ~3.1 MB ]

This will continue for a few minutes (~307 seconds = ~5 minutes on my machine). You can watch the progress of the send on the PC/server side. If you should suddenly hear a beep and the process breaks, leaving you flailing in a cold green puddle of hex, you probably need to raise your Pacing interval to increase the pause between each line sent.

If everything works successfully, you should be looking at a ProDOS screen with a prompt when the streaming finishes.

Sending the ADTPro client program:

Select Bootstrapping > ProDOS > Send ADTPro Serial Client. A box will pop up telling you to type some stuff on the Apple. The example it gives assumes you have your serial card in port 2:

IN#2  Press Return 
<ctrl-A>  The serial card will prompt.  On my system this is APX-SSB-1: 
14B  Press Return 

Click OK on the dialog box that ADTPro popped up and if your serial connection is set up properly, you will see data fill the Apple's screen once again. The ADTPro client is now being sent.

As with ProDOS, this process will continue for a few minutes (~237 seconds = ~4 minutes on my machine). As before, you can watch the progress of the send on the PC/server side, and likewise, if you hear a beep and the transfer dies, you will have to start over with a higher Pacing setting to increase the pause between each line sent.

If everything goes smoothly, you will see a friendly-looking ADTPro client screen. The next order of business is to make an ADTPro floppy, so you don't have to do this bootstrapping business anymore.

Back: Table of Contents

Most importantly, by now you should be crazy mad blunted and cranking the Wu-Tang Clan's "Enter the Wu-Tang (36 Chambers)" because this is the obvious soundtrack for staying in on a Saturday and doing this sort of thing. Anyone could be reading this, but one of two things is true: Either you already have this album on, or, protestations to the contrary, you *need* to have this on. If you're listening to the soundtrack to some kind of anime series, you have failed.

Next order of bidness is to make an ADTPro boot disk, which you will use (I'm serious about the anime soundtrack thing) to transfer any and all disk images in the future.

If you have not put a fresh or expendable disk in the drive, do so now.

Press F to format. ADTPro will scan for available drives. Using the up and down keys, select the drive that the disk is in, and press Return. You will be prompted for a volume name. Feel free to use the default (/BLANK) because this will be overwritten when you transfer the disk image anyway. Press Return to format the disk.

You will be asked if you want to format another. Go ahead and format more if you want. Otherwise, press N to bring you back to the main ADTPro menu.

Transferring the ADTPro image and making a floppy

The procedure for transferring the ADTPro image is the same as for transferring any other disk image in the future. Make note of it. If you find an image of, say, Zork III online and feel the need to transfer it to a floppy so you can play it on your IIe, use the same procedure.

On the Server (PC) side, select File > Change working directory and select the disks directory off of the main ADTPro directory. Click the Set working directory button. In the future, you'll select the directory that contains the disk images the same way. You can also do this from the client / Apple side, but it is easier (GUI file selection dialogs) on the server side.

On the Client/Apple side, select G which will bring up the ADTPro client configuration screen.

The setting you will most likely need to change here is the BAUD RATE, and possibly the COMMS DEVICE setting if your serial card is anywhere other than slot #2.

Use the up and down arrow keys to select the BAUD RATE setting and use the left and right arrow keys to select the baud rate you want. In most cases, you will want to set this to 9600. Make sure the ADTPro application/server on the PC side is set to the same rate. This is indicated in the title bar of the ADTPro window (drag the window border to the right to expand it a bit if you can't see it). There is no point attempting to save this setting now because the ADTPro client you are running is only in RAM. Later, when you boot ADTPro from the floppy, you'll need to change the BAUD RATE setting again, and you'll want to set SAVE CONFIG to yes. It will then write your settings to the ADTPro floppy.

For now, though, once you have the BAUD RATE set to 9600, just press Return to bring you back to the main ADTPro screen.

You are now ready to transfer the ADTPro disk image and write it to the newly formatted floppy disk.

Click R on the Apple side to select (R)ECEIVE. You will be prompted for a filename. You will have to determine this by looking in the disks directory on the PC side for the proper filename. Look for a filename titled ADTPRO-x.x.x.DSK As of this writing, the filename is:

ADTPRO-1.0.6.DSK

Enter this at the FILENAME:prompt on the Apple side and press Return to bring up the disk selection dialog.

For future reference, the .DSK extension indicates an Apple floppy disk image and most of the software (abandonware, warez, shareware, etc.) you find on the internet will be in this format.

You will now be prompted to select the destination volume -- in this case, the blank disk you just formatted. If you left the default disk name as /BLANK in the format step, you will see it in the list. Use the up and down arrow keys to select it and press Return.

The disk image will now transfer, intermittently writing to the floppy. On both the PC (server) and Apple (client) side, progress bars will begin to tick up as data is transferred.

When the process is complete, you will receive a confirmation on the Apple side:

COMPLETE!
PRESS A KEY TO CONTINUE...

On the PC side, you'll get a benchmark for how long the image took to transfer. The ADTPro disk image takes ~115 seconds to transfer on my system.

Back: Table of Contents

Make sure that the ADTPro disk you just created is in Drive 1.

Reset the system by power cycling or using the Apple 3 finger salute, which is CTRL-Open Apple-Reset. Open-Apple refers to the key to the left of the space bar with the hollow Apple diagram. Look, don't get snarky with ME, pal. I'm not an Apple guy and how to reset wasn't obvious to me.

ADTPro should boot, but this time with a menu offering Serial, Audio, or Ethernet transfer programs. Select Serial and you should be back at the familiar ADTPro screen.

Since you're now booting with a fresh copy of ADTPro, you'll want to set the configuration options again and write them to the disk so you don't have to set them again on subsequent boots. Select G to go to the configuration screen, and set things properly for your system. On mine, this is:

The only difference this time is you want to save the configuration. Remember, to move around, use the up and down arrows to select the option you want to set and the left-right arrow keys to select the value you want. Once again, make sure the BAUD RATE matches on both the Apple and PC side. Press Return to save your selections. They will be written to the ADTPro floppy. Hit a key to continue and you will be back at the main screen.

Back: Table of Contents

They are out there, in precisely the places you might expect. There are several archives of public domain, shareware, or legal abandonware online that you can find via a search engine, such as:

• http://www.apple2.org.za/mirrors/ground.icaen.uiowa.edu/apple8/
• http://www.umich.edu/~archive/apple2/

What you will find online will not always be in an easily usable format.

DSK images are also available in huge packs, sometimes of thousands of applications or games, labeled according to the TOSEC file naming/cataloging standard. These packs generally contain all of the classics, but the legal status of these applications is questionable (or obviously not legal). They can be found in various forms on file sharing networks, torrent trackers dedicated to retrogaming, and so forth. One benefit of these packs is that they tend to be comprised of packages named according to the TOSEC standard, making applications and old games easy to find. The applications in the packs tend to be in the easily usable .dsk format, which works great with ADTPro.

The TOSEC people will no doubt appreciate me making clear that TOSEC does not package, distribute, or otherwise make these applications available. They merely provide a naming and catalogging scheme. TOSEC's purpose is to document applications and games which would otherwise be lost or forgotten. Those who actually package these applications for distribution merely use TOSEC's naming and catalogging scheme but otherwise have no formal connection to TOSEC.

Suffice to say, they can be found and obtained with a minimum to moderate amount of effort, but their legal status is mixed. Fortunately, you can also go to ebay to buy old software. I have boxes and boxes of original software diskettes that came with the Apple 8 bit systems I bought used, mostly from ebay.

For the sake of this document, we're going to use a widely available public domain application called Modem.MGR, a communications program, to make our first (well, second after ADTPro) disk.

This is the same software used with modems back in the BBS days before SLIP and PPP internet access. We're looking for the Apple 8 bit equivalent of Hyperterm (Windows) or Minicom (Linux). For the purpose of using the Apple as a serial terminal, I tried several of these with mixed success until pdw's article on making a terminal out of an Apple IIc pointed me toward a program called Modem.MGR. Fortunately, this software is easily obtainable on the internet. What Modem.MGR provides that other term apps don't, is VT220 emulation, which will enable you to use Linux apps that involve a lot of screen redrawing and cursor movement like top, links2 (Web browser), WeeChat (IRC client), and others. If you know of other freely available Apple term programs that do reasonable terminal emulation (especially ANSI graphics / Extended ASCII), please let me know. (I have been informed by several Apple junkies that the Apple II series never supported ANSI - if you can prove them wrong, mail me!)

Probably, you will want the ProDOS Modem MGR disk set, which comes in a zip file. Download and unzip the archive:

unzip MMGR_PDOS_DSK.zip

Inside are three disk images. Only two are important. These are:

MMGRPDINST.DSK
MMGRPDWORK.DSK

The INST disk is used to configure the term software's features, and the resulting configuration is written to the WORK disk, which is bootable. If you get it right the first time, you'll only need to use the INST floppy once.

Back: Table of Contents

First, we have to get the images from your PC's hard drive on to Apple floppies. ADTPro should still be running on both the PC and Apple side. If not, boot the ADTPro floppy on the Apple side and run the Java application on the PC side via the shell script, as before. Remember to click the Serial button to initialize the Serial connection, or ADTPro won't be able to connect for the upcoming transfer.

The procedure is the same as the one used to transfer the ADTPro disk image over. First, use the (F)ORMAT option on the Apple side to format two floppies, one to hold each disk image, then go back to the main ADTPro menu. As before, it doesn't really matter what you call each disk since the Modem MGR images will overwrite this information, so you can leave it as /BLANK.

Then, on the PC side, go to File > Change working directory and set the directory to wherever you unzipped the Modem MGR disk images to and click the Set working directory button.

Insert one of the freshly formatted floppies into the Apple disk drive (the last one you formatted is probably still in there), click (R)ECEIVE, and enter the filename: MMGRPDINST.DSK

You will be prompted for which disk to save the image to. Make sure you select the right one and don't accidentally overwrite the ADTPRO disk, which is mostly an issue if you have two disk drives and have left the ADTPRO disk in drive 1.

The disk image will transfer as before. Stare into the paranoia-inducing oblivion of the progress bars as 280 blocks of your life tick slowly away.

Repeat this process for the second disk, MMGRPDWORK.DSK

Back: Table of Contents

This is the basic procedure for transferring disk images you've downloaded from the Internet to a bootable Apple floppy via a serial cable. You can repeat these steps for anything else you find on the Internet.

If you are reading this as part of the Apple serial term essay, continue with the next step: Configuring Modem.MGR.

Back: Table of Contents