A2CLOUD: coming attractions

If you’ve made it this far, you’re in pretty good shape with A2CLOUD — you should have two mass storage volumes and internet access for your Apple II, and maybe have learned a thing or two about Unix!

But wait, there’s more, and in time (perhaps) I’ll be posting about how to use your Apple II and Raspberry Pi to:

  • √ chat in the #a2c.chat room
  • √ read and post in the comp.sys.apple2 newsgroup
  • √ run Apple IIgs and IIe emulators on your Raspberry Pi
  • √ control your Pi’s desktop with your Apple II keyboard and mouse, and program your Apple II itself from your Pi, using David Schmenk’s awesome Apple II Pi
  • √ use your Pi as a file server and network boot host with A2SERVER
  • use virtual drives with disk images stored on a computer across the internet
  • use TCP/IP on your IIgs without an Uthernet or LanceGS card
  • access an ADTPro server on another computer from your Apple II…over Wi-Fi!
  • use Pine for email
  • any other entertaining ideas that occur to me

I’ll also be posting on other Apple II stuff that isn’t necessarily related to A2CLOUD on the rest of my PR#6 blog.

Let me know if you have any questions or suggestions at ivan@ivanx.com. (I will probably be more motivated to post about these things if you let me know you’d like to read about them. Just saying.)

Ok, have fun. See ya on comp.sys.apple2!

Obsolete Stuff

Setting up A2CLOUD requires installing a bunch of stuff on your Pi. I’ve tried to make this easy.

If you have never used your Pi, you will need to load your SD card with either Raspbian or A2SERVER (which is based on Raspbian). If you don’t plan on using A2SERVER, and have a screen and keyboard attached to your Pi, you can use the fairly easy NOOBS installation process described on the Raspbian download page.

If you are instead installing the Raspbian or A2SERVER image file, you might find my Raspberry Pi Party page useful, particularly if you have a Mac. From there, you can get Pi Filler, which is a self-explanatory tool for loading up your SD card. For non-Mac platforms, you can look for guidance on the Raspberry Pi wiki and forum to accomplish the same thing.

Once you’ve loaded Raspbian, the next thing you need to do is put the SD card in your Pi, and attach power. If you’ve got a screen and keyboard attached, you’ll see it boot up. If not, you can log in with SSH from another computer. If you have a Mac, you can use Pi Finder to help log in to your Pi from Terminal. If you have Windows, you can use Advanced IP Scanner to find your Pi on your network, and PuTTY to log in. The username is “pi”, and the password is either “raspberry” or “apple2”, depending on whether you have vanilla Raspbian or A2SERVER installed.

Once you’ve logged in and found yourself at the Linux prompt, type sudo raspi-config and choose the first option in the menu to expand the filesystem. Then reboot when it asks you to.

A2CLOUD: other stuff

This is a post for new techniques or features that aren’t fully ready, or other stuff that doesn’t seem to fit into the main guide. View the comments to see, or post one of your own.

If this is at the top of a bunch of posts below, you’re reading the A2CLOUD guide backwards. Click “A2CLOUD” in the menu header above to fix it, or just go to http://ivanx.com/a2cloud.


A2CLOUD: release history and notes

A2CLOUD is sorta always in a state of development with tiny tweaks happening without announcement, often to the installer script rather than any visible features per se, and those changes and other small details are (somewhat) documented at the end of the script itself. But here are the noteworthy enhancements. To update, type a2cloud-update.

v1.8.1, May 5, 2015

  • ADTPro 2.0.1
  • Apple II Pi client 1.5

v1.8.0, March 17, 2015

  • compatible with every Raspberry Pi, including Raspberry Pi 2 Model B
  • GSport installed for non-Raspberry Pi computers, with option for new GS/OS+Spectrum installation, or GSport Internet Starter Kit premade image
  • Links web browser
  • desktop shortcuts and Apple II menu group for emulators and ADTPro
  • new a2cloud-update os command will perform full Raspple II update, including Raspbian OS and NOOBS install manager, A2CLOUD, A2SERVER, and Apple II Pi
  • many small improvements and fixes to A2CLOUD environment and installer script

v1.7.2, February 7, 2015

  • supports Raspberry Pi Model A and A+ (and Pi 2 Model B)
  • resolves issues with Raspbian 2015-01-31 (kernel 3.18)

v1.7.1, August 11, 2014

  • A2CLOUD is no longer “beta” on non-Raspberry Pi computers
  • A2CLOUD includes KEGS and Linapple on non-Raspberry Pi computers
  • A2CLOUD has a faster install script for non-Raspberry Pi computers (downloads binaries)
  • unbit/unexec/bsq archive tools are installed

v1.7.0, August 2, 2014

  • a2cloud-setup installs Java 8 if not already installed

v1.6.9, July 24, 2014 (KansasFest)

  • ADTPro 2.0.0 (quicker and more reliable transfer; selectable filenames from list)
  • confirmed working on Raspberry Pi Model B+ (use the USB ports closer to the Ethernet port)

v1.6.8, Apr 7, 2014

  • ADTPro 1.3.0
  • TTYtter installs properly on non-Pi systems

v1.6.7, Feb 19, 2014

  • A2CLOUD boot floppy contains A2PI client version 1.4
  • A2CLOUD boot floppy splash screen provides simple menu for virtual drives, Apple II Pi, or BASIC
  • A2CLOUD.HDV is now called A2CLOUD.PO (a symbolic link called A2CLOUD.HDV is still there for backwards compatibility/habits)
  • bug fixes for cppo, shk2image, and some launcher scripts

v1.6.6, Feb 17, 2014

  • beta support for Debian and Ubuntu Linux on non-Pi machines
  • ttytter support for color and avoiding non-ASCII characters when running  under Screen
  • opens LXTerminal window by default when starting graphical desktop
  • a2cloud-setup installs Screen if not already installed
  • a2cloud-setup shows installed and available versions
  • a2cloud-setup -y bypasses all prompts

v1.6.5, Feb 5, 2014

  • can use term mono and term color instead of term vt100 and term pcansi

v1.6.4, Jan 31, 2014

  • support for screen command to allow switching between multiple terminals on Apple II
  • term -f can be used to force emulation setting even when term doesn’t want to

v1.6.3, Jan 23, 2014

  • Set TTYtter to always use -ssl mode, which is required by Twitter after 14-Jan-14.
  • Set TTYtter to avoid display of non-ASCII characters on serial port shell
  • Set TTYtter to use color ANSI text (for IIgs) if shell is currently set to display it
  • Provided TTYtter readline module for enhanced input with -readline option
  • Added appleiipi-update command

v1.6.2, Jan 19, 2014

  • Improved display of non-ASCII characters in Apple II terminal emulation programs
  • Support for “PC ANSI” colored text and graphics characters , for use with Spectrum’s ANSI online display, via new term command
  • Added sciibin and unblu for converting BinSCII and Binary II files
  • baud command supports 300 baud, in case you really want to kick it old school

v1.6.1, Jan 14, 2014

  • Added telnet and ttytter (Twitter client)
  • fix for network boot failure when set up under v1.6

v1.6, Dec 31, 2013

  • ADTPro/VSDRIVE 1.2.9 (much faster virtual drives read performance, for the price of a short delay on the vsd1/vsd2 commands and a need to type vsdsync after changing an active virtual drive directly on the Pi; ability to run VSDRIVE from ProDOS program launcher, not just BASIC.SYSTEM)
  • if A2SERVER is installed, shares the ADTPro disks folder as ADTDISKS on the network
  • responds to name “raspberrypi.local” as alternative to IP address to Mac OS X (and Windows with Bonjour Print Services installed) computers on network

v1.5.2, Dec 22 2013

  • added dos2pro command
  • Apple II Pi is now installed with GSport emulator and “apple2user” packages
  • speedier install by downloading A2CLOUD disk images instead of building them

v1.5, Dec 1 2013

  • Adds IRC and newsreader clients (Irssi and Tin) and, with shortcuts for Apple II community (a2chat and a2news commands)
  • adds KEGS and LinApple emulators
  • installs Apple II Pi
  • easy installation via Raspple II

v1.2.3, Nov 2013

  • A2PI client version 1.3 added to A2CLOUD disk
  • faster install for unar/lsar, nulib2, and cftp (downloads rather than compiles)
  • console (built-in serial) login disabled, to allow Apple II Pi to have that port
  • installs xrdp/tightvncserver for remote desktop access from another computer
  • adds DSK2FILE image utility to A2CLOUD disk

v1.0, Sep 2 2013

  • first proper release with full documentation, bug fixes, and demo video

beta, Jul 27, 2013

  • internet access and virtual drives for any Apple II via a Raspberry Pi; introduced at KansasFest 2013

A2CLOUD: Apple II Pi

David Schmenk has created Apple II Pi, which takes a different approach than A2CLOUD. With A2CLOUD, the idea is to use your Pi as a peripheral for your Apple II.

Apple II Pi flips this around: you can use your Apple II’s keyboard, mouse, joystick, and drives to control your Raspberry Pi, primarily so you can use the GSport emulator, giving you a virtual souped up Apple II. To get benefit from this, you’ll need a screen attached to your Pi.

To use Apple II Pi, you’ll need the Apple II Pi card, or a Raspberry Pi console cable attached to a Super Serial Card (even in a IIgs) or a IIc/IIc+ serial port, via the appropriate serial cable and possibly a DE-9 (aka DB-9) male-to-male null modem adapter. The software is already installed by Raspple II or A2CLOUD (if it doesn’t seem to work, try updating A2CLOUD by typing a2cloud-update).

Once connected, boot the A2CLOUD floppy, and press space on the splash screen. The first time you do this, it will ask you to choose the slot of your Apple II Pi card or Super Serial Card. It should then connect immediately; your Apple II will sound a tone, and any keystrokes you type will show up on the Raspberry Pi’s screen, rather than your Apple II; on the Raspbian desktop, you can use your Apple II mouse. And if you want to see your Apple II prompt on your Raspberry Pi, type a2term; prepare to be pleasantly disoriented.

Apple II Pi also lets you go straight into GSport, bypassing the Raspbian command line, by logging in with username “apple2” (no password); type alt-F4 (or openApple-solidApple-4 on an Apple II keyboard) to quit. When you do, your Pi will fully shut down.

Apple II Pi has many more sophisticated abilities, such being able to develop 6502 code on the Raspberry Pi and execute it on the Apple II. For more info on how to use it, check out Dave’s web site and the Ultimate Apple 2 forums.

A2CLOUD: emulate an Apple II

Though the purpose of A2CLOUD is primarily to extend the functionality of your actual Apple II, there are also emulators provided in case you want a virtual Apple II. (If you’re using Apple II Pi, that’s in fact sort of the point.)

You’ll either need a screen attached to your Raspberry Pi, or remote desktop software.

For an emulated Apple IIgs, use GSport, a descendent of the KEGS emulator with significant enhancements by David Schmidt, David Schmenk, Peter Neubauer, Christopher Mason, and others. GSport’s features include Uthernet card emulation, AppleTalk networking, and ImageWriter and Epson printer emulation. Type gsport to if you are at the command prompt and want a full-screen experience, or double-click GSport on the Raspbian desktop. Press F4 for the configuration screen, and alt-F4 to exit. Usage instructions are on the GSport home page.

For a emulated Apple IIe, type linapple to run the LinApple emulator. It has some nifty features like built-in software downloading and a built-in help screen. More information is here.

You can also use GSport’s ancestor, KEGS, by choosing it from the menu of the Raspbian desktop. (To start the Raspbian desktop, type startx or use remote desktop software.) Usage instructions are here.

A2CLOUD: increase serial port speed

I chose the default speed of 4800 baud for Pi as a lowest common denominator that should work in almost any situation, even a IIc using Z-Link without any kind of hardware handshaking serial cable. It should be fine for command-line stuff, but might be slower than you’d like if you use any full-screen programs (like cftp) or are transferring with YMODEM.

You can try to use a faster baud rate with the following command:

baud baudRate

baudRate can be 300, 1200, 2400, 4800, 9600, 19200, 38400, 57600, or 115200. The change will take effect immediately (unless you’re not doing it from your Apple II itself, in which case it won’t do anything), so you’ll need to change the setting in ProTERM or Z-Link, too.

If you want to make the change permanent, with the change taking effect on logout, use:

baud -d baudRate

To see the current speed, just type baud by itself.

You’ll only be able to use 38400 or 57600 on a IIgs (and not with Z-Link), but Hugh Hood has come up with clever ProTERM macros that enable 115200 baud on any Apple II, and A2CLOUD provides them with ProTERM. If you use 115200 baud, you’ll likely drop some characters, especially on an 8-bit Apple II. One strategy you might want to try is to use a slower speed normally, but then “upshift” to 115200 for transfers. When you’re done, you can switch back to the slower speed.

To use Hugh’s macros, choose “Read Globals” from the “Misc” menu, and select either PT3.IIE.GLOBALS, PT3.IIC.GLOBALS, or PT3.IIGS.GLOBALS, depending on what computer you’re using. Then, for a IIe or IIc/IIc+, type solid-apple-F, and it will switch to 115200; you can still switch back to other speeds as usual from the “Online” window. For a IIgs, type shift-option-H, and it will switch to 115200 baud; to switch back to other speeds, type option-H to disable the macro. If you want these macros to automatically be available when ProTERM starts without having to use the “Read Globals” menu item, delete or rename PT3.GLOBALS, and then rename the appropriate globals file to PT3.GLOBALS.


A2CLOUD: transfer files

If you’ve got files on your Pi that aren’t inside one of your viritual disks, and you want to transfer them to your Apple II, you’ve got a few options.


Archive files:

If it’s an archive file, you can (and perhaps should) expand it directly on the Pi, as explained in A2CLOUD: working with archives and disk images. Otherwise, use one of the cool moves below, and then expand it with ShrinkIt or the appropriate program on the Apple II.


Copy a file into a disk image

acmd -c fileToBeCopied imageFileName

You can then use vsd1 or vsd2 to access the image file, or, alternatively, transfer it to a floppy with ADTPro. If you want to copy a file directly to a disk image already in a virtual drive, use $VSD1 or $VSD2 for imageFileName. You must immediately type vsdsync if you modify an image currently assigned to a virtual drive.

If you want to specify a different name and/or file type, you can use the long form:

acmd -p imageFileName APPLE2.FILENAME fileType auxType < fileToBeCopied

fileType should be a three-letter name (e.g. TXT), or a numeric type (e.g. 255 or \$E0). auxType is also needed for file types that require it (e.g. BIN), and can be either decimal, or hexadecimal if preceded with \$. You can use \$2000 for auxType if you’re not sure. If you want the file to go into a ProDOS subdirectory, you can specify the path as part of APPLE2.FILENAME (but do not include the volume name); any subdirectories that don’t already exist will be created.

(This is a slightly modified version of AppleCommander’s normal -p option: the file type and ProDOS file name are optional, the file name is checked to make sure it’s ProDOS-compatible, and any existing file of the same name within the image is first deleted.)


Transfer a file from your Pi to your Apple II

You can transfer a file to be saved on a local or virtual disk by using the YMODEM protocol. To send one or more files with YMODEM, type:

sb fileToBeTransferred1 fileToBeTransferred2 fileToBeTransferred3 (etc)

Once started, you will need to tell ProTERM or Z-Link to receive YMODEM. In ProTERM, choose YMODEM from the Receive menu; in Z-Link, type open-apple-downarrow, then option 4. In either one, accept the default options (unless you want to change them), and the files should transfer. If for whatever reason they don’t, and you can’t get access to the Linux shell prompt again, type ctrl-X until the prompt reappears. Transfer may be slow at the default 4800 baud rate; I’ll explain how to increase the baud rate in the next post.

If you are using ProTERM, you can also try ZMODEM by using sz instead of sb. ZMODEM is a more efficient protocol than YMODEM, it can auto-start, and it can recover from incomplete transfers, but those are less important in a direct-attached (rather than dial-up) situation, and I haven’t had as much success with it as I have had with YMODEM.


Transfer a file from your Apple II to your Pi

You can also go in the other direction — from your Apple II to the Pi. Type rb (for YMODEM) then tell ProTERM or Z-Link to send YMODEM. (If you prefer to send ZMODEM from ProTERM, just do that, and the Pi will automatically start receiving; you don’t need to type a command first.)

Another option is to save a file to a virtual disk — or transfer a real floppy using ADTPro — and then copy files out of the disk image on the Pi with this command:

acmd -g imageFileName APPLE2.FILENAME

If you saved to the virtual disk, you can type $VSD1 or $VSD2 for imageFileName.

acmd (AppleCommander) has some smarts, and it can translate (or “export”, as it prefers to say) from various Apple II file formats into modern formats. If you want it to give that a shot, use -e instead of -g above.

A2CLOUD: expand archives

If you have an archive file, on your Pi, you’ll need to expand it.


Commands for general archive formats:

unzip archiveFileName will extract files from a .zip archive

gunzip compressedFileName will uncompress a .gz compressed file

tar xf archiveFileName will extract files from a .tar archive

tar zxf archiveFileName will extract files from a .tar.gz (or .tgz) archive (both of the previous commands in a single step)

unar archiveFileName will extract files from tons of archive formats, including obsolete ones like StuffIt and DiskDoubler. See The Unarchiver for a full list.


Commands for Apple II archive formats:

nulib2 -x archiveFileName will extract files from a ShrinkIt (.SHK, .SDK, .BXY) or Binary II (.BQY, .BNY) archive. This will mostly be useful when the archive contains a full disk image (typically, but not always, indicated as .SDK); if the archive contains files, use one of the commands below. You can view the contents of an archive before expanding with nulib2 -v archiveFileName.

shk2image archiveFileName imageFileName will extract files from a ShrinkIt or Binary II archive to a ProDOS disk image file (if the one you specify doesn’t exist, an 800K image will be created, unless the name you gave ends in “.dsk”, in which case a 140K image will be created). If you want the archive to be expanded directly to virtual drive 1 or 2, use $VSD1 or $VSD2 for imageFileName.

If you want the archive to be expanded into a ProDOS subdirectory rather than at the top level of the disk image, you can supply a ProDOS path, without the volume name, as an additional argument. The subdirectory (and any subdirectories within it) will be created if it doesn’t exist. For example:

shk2image archiveFileName $VSD2 PATH/TO/PRODOS.DIR.NAME

(You can also uncompress ShrinkIt archives on your Apple II by transferring the archive, as I’ll explain in the next post. It’s slower that way, though.)

For other (and older) Apple II formats: sciibin filename will decode a BinSCII file (.BSC, .BSQ); note that .BSQ files produce ShrinkIt archives when decoded, so use nulib2 -x or shk2image on the result. nulib2 -x filename will extract files from a Binary II (.BNY, .BQY) archive, and will automatically uncompress any Squeezed (.QQ) files within the archive; alternatively, unblu filename will extract files from a Binary II archive and usq filename will uncompress Squeezed files. unbit filename > outfilename will decode an EXEC file made by Executioner; unexec filename > outfilename will decode an EXEC file containing monitor input.

A2CLOUD: use disk images

Once you’ve downloaded stuff to your Pi, or copied stuff on to it from another computer on your network, you can immediately use the vsd1 or vsd2 commands for an uncompressed disk image file (.DSK, .DO, .PO, .RAW, .HDV, .2MG. ISO) containing ProDOS files, and then access them from your Apple II. The image file will be “inserted” into virtual drive 1 or 2, and accessible from VSDRIVE at S2,D1 or S2,D2.

If what you download is an archive file (.SHK, .SDK, .BXY, .ZIP, .TAR.GZ, etc.), you’ll need to expand it first, which you can read about how to do in the next post.

If you’re not sure whether the disk image you downloaded is ProDOS format or not, you can type a2cat imageFileName on your Pi, and it will catalog the disk and tell you the format at the bottom of the listing.

If it’s a DOS 3.3 disk, you can type dos2pro imageFileName to copy the files to a new ProDOS  image, or dos2pro imageFileName DOSFILENAME to copy a single file. Some programs may not work when copied to ProDOS.

Or, you can use ADTPro to transfer the image file to a floppy disk. To make a disk image available to ADTPro, you need to move it into into the ADTPro disk images directory (/usr/local/adtpro/disks) by typing forfloppy imageFileName. To access the files inside that directory, you can also refer to it as $ADTDISKS (e.g. ls $ADTDISKS).

You can also use vsd1 or vsd2 for non-ProDOS disks, but you won’t be able to access them from within ProDOS. However, you can use a ProDOS utility which knows how to access the format (e.g. System Utilities can copy files from DOS 3.3 and Pascal disks).


Some commands for working with Apple II disk images:

mkpo -b totalBlocks newImageFileName PRODOS.VOL.NAME will make a new disk image that has the capacity specified in totalBlocks. (A block is 512 bytes, or half a KB.) The maximum block count is 65535, though if you plan to use the disk image with VSDRIVE, a realistic maximum is 8192. If you omit -b totalBlocks, you’ll get an 800K disk image, unless your image name ends in “.dsk”, in which case you’ll get a 140K disk image. You can also omit PRODOS.VOL.NAME to get an untitled disk image.

dopo imageFileName will convert a DOS-ordered 140K disk image to a ProDOS-ordered image, or vice-versa. The original ordering will not be kept.

acmd will do lots of stuff with Apple II disk images (many formats, including ProDOS, DOS 3.3, and Pascal, are supported). Type acmd by itself to see usage; syntax for copying files in and out of images will be mentioned in the next post on transferring things to your Apple II. (cppo is an alternative, but it’s even slower. It does preserve dates, however.)

$VSD1 and $VSD2 can be used in commands to refer to the disk images assigned to virtual drives 1 and 2, rather than typing out the full path.