Nov 1, 2014
ANTIC - Atari Podcast
Guide for Atari Emulation on iOS Devices
Written by C. Olson, October 2014
Greetings, all. Emulation on iOS devices is a subject that has always proven difficult, given the constraints of the App Store and overall Apple philosophy. Anything that executes non-native code is frowned upon at the App Store level, and often rejected outright.
What does this mean? Simply put, you need a jailbroken iOS device. This is a deal breaker for a great many people, and it's understandable. I'll leave the fierce debate on the merits and dangers of jailbroken devices out of this guide -- many opinions on both sides. Moving forward though, I'll assume basic to moderate knowledge of Cydia (the non-Apple 'App Store') and working within the jailbroken file system. If the ability to emulate the Atari encourages you to take the plunge and jailbreak, plenty of tutorials and information exist - please read them carefully. The process has evolved quite a bit over the years but it still carries some risk. Proceed with caution!
All set? Here's a brief outline of what we'll be doing, with detailed steps to follow:
* Download the Atari Emulator "XFormer" (MS-DOS version), preferably on your iOS device.
* Locate the Atari Disk images and file you would like to use - then transfer them to your iOS device or download directory.
* Run Cydia
* Add a Source in Cydia
- This source is a repository for DOSPad, a port of DOSBox, cross platform MS-DOS emulator for iOS.
* Install DOSPad
* Use on-device file management software to move and unzip/unarchive XFormer
* Run DOSPad
* Launch XFormer from the DOSPad C:\> prompt
* Enjoy some Fuji color cycling goodness!
All of the file downloading and transferring can be done on your iOS device, or, you may download files to your computer and transfer them over. I use a file management app called "iFile" which is a paid application on Cydia, and well worth it. For downloading, I use the "Safari Download Plug-in" which is also on Cydia and free - clicking on a download link in Safari will bring up a prompt for you to save the file in a specified location, and, using iFile, you can move, unzip, etc. If you want a little more control over how Safari handles downloads, another paid Cydia app called Safari D+ comes highly recommended. Cydia, like the regular App Store, receives a huge influx of new content daily, so it's quite possible there might be different and more compelling options out there by the time you read this. I don't know if there's a free file management app available, but it's worth a look.
If you have a large library of Atari stuff on your computer that you want to transfer to your iOS device, rest assured that it is possible and not too difficult. You will need to install and configure SSH on your iOS device, and install a file management program on your actual computer. Two programs that I used in the past to do this were iPhone Explorer and I-FunBox. Both of them worked quite well, on both Windows and Macintosh platforms. These are drag and drop, Finder/Windows Explorer-like programs for movement of files, folders and directories.
** CAUTION CAUTION CAUTION **
Be -EXTREMELY- careful when you are moving folders and files on your iOS device! If you mistakenly delete a system directory, there's no going back! Same warning applies when viewing/accessing the iOS file system on your computer. Enable the "Trash" option, if available, in both places. File management programs are excellent utilities, but they do not distinguish between system folders and regular folders!
Guides and information for configuring and installing SSH, using iFile/other file management apps, Safari Downloads, and computer/iOS file transfer are fairly easy to find via search engine, and, frankly, beyond the scope of this guide. There's some very helpful information regarding SSH and device security on the front page of Cydia itself -- a good place to start if you're unfamiliar.
Let's get started.
1) Download XFormer. The version we want is called "XFormer Classic" - here's the link:
Note the path where the download was saved on your iOS device for later steps.
2) If you will be transferring Atari data from your computer, I'd suggest creating an easily accessible Atari-specific directory on your iOS device. Mine is located at /var/mobile/Atari. The underlying iOS file system has Unix roots, which allows for long filenames and lower case, but in the case of both MS-DOS and Atari, filenames must conform to the eight character name and three character extension (8.3) specification (e.g. ATARI.BAS is okay - AtariTenLineProgram-txt.bas is not.) If you want to try things out first, the XFormer emulator ships with Atari DOS and .ATR disk images that contain a few demos and games.
3) Initiate the data transfer, launch your on-device file management app, and verify that your files/folder are, in fact, present.
4) Close the file management program on your computer, if applicable.
5) Run Cydia on your iOS device.
6) Select the "Sources" tab on the bottom of the screen.
7) Tap the "Edit" button in the top right hand corner of the screen.
8) Tap the "Add" button in top left hand corner of the screen.
9) You are presented with a prompt that reads "Enter Cydia/APT URL"
The "http://" should be filled in automatically.
Type the following:
Then tap the "Add Source" button.
10) Cydia should populate with the DOSPad files, plus a few others by this developer.
11) Select the "Changes" tab from the bottom of the screen.
12) The entries from litchie.net should appear near the top of the screen. Select "DOSPad - DOSBox for iOS" and install the package. If you don't see this on screen, select the "Search" tab from the bottom of the screen and type "Dospad" to find it.
13) Make sure you have the location of the XFormer Classic emulator from Step 1. I suggest moving that file into your newly created "Atari" directory to keep everything in one place.
14) Using iFile or a separate unzip/unarchive utility, unzip the XFormer file (pcxf380.zip). This can be done in iFile by simply tapping the file itself and selecting "Unarchiver."
15) At this point, the hard work is done. You should now have an Atari directory that's easily accessible with the requisite Atari data from your computer (if applicable.) DOSPad is installed, and, for the sake of simplicity, the XFormer emulator is unzipped within that same Atari directory. Let's run it!
16) Quit iFile and locate the DOSPad icon on your iOS device. Run DOSPad.
17) If all goes well, you should see the C:\> prompt at the top of the screen. Welcome back to MS-DOS 5.0 and the early 1990's! I'm an MS-DOS enthusiast too, but we're looking to go a little farther back in time. If you're familiar with the MS-DOS command line, most of the
old commands will work, go ahead and try them out, if you like. When finished, type the directory command "DIR" and press Return.
18) If you are running DOSPad on an iPad, you'll be treated to a slick user interface that really takes advantage of the larger screen. In Portrait mode, the keyboard overlay mimics the chiclet-style IBM PS/2 keyboard. In Landscape mode, the display goes full screen - and you can access the keyboard by tapping the top of the screen and selecting the keyboard icon. On the iPhone, Landscape mode shows a full screen display, but in Portrait, the bottom half of the screen toggles between keyboard and gamepad view.
19) Your Atari directory should be visible on the screen somewhere. Assuming your directory is named "ATARI", type "CD ATARI" and press Return.
20) We need to make sure we can find the appropriate disk image file to use with XFormer - type the "DIR" command if you're unsure. If you transferred a large number of files, use "DIR /P" to pause the directory listing or a wildcard -- "DIR *.ATR" will list only .ATR image files.
21) Time to launch XFormer, finally! Type the following and press Return when done:
XFORMER -J ANALOG51.XFD
22) Almost there! You should see an XFormer splash screen, with some very helpful keystrokes listed. Take a screenshot on your iOS device (press the home button and power button simultaneously) so you can refer back when needed. The "-J" switch enables the joystick in XFormer - which can be utilized in Dospad by selecting the gamepad/joystick UI on the screen. Feel free to omit the -J switch if you won't be using the joystick. "ANALOG51.XFD" is one of the Atari disk images that ships with XFormer. I'd suggest trying this out first, and if it works, substitute the name of your intended disk image in its place.
23) "Press Any Key To Begin..." <- Sounds about right!
24) Your iOS device should say "Analog Computing" at the top of the screen, and the rest should look all too familiar. Congratulations! You are now emulating the Atari 130XE.
25) If you would like to try one of the programs included on the Analog disk, use <Start> and <Select>, which are mapped to F7 and F8, respectively.
26) If you want to choose another program, press F12 - this will change the emulated machine, visible on screen - keep pressing F12 until you get back to the 130XE, if desired - this will also force a re-load from the disk image. Note the <Reset> key is mapped to F10, but (as with the actual machine) a cold boot is sometimes necessary for a full reset, which is accomplished using F12.
And there you have it! XFormer comes with excellent documentation - if using iFile, you can read XFORMER.TXT (present in your Atari directory) on your iOS device. Dospad has a message board that doesn't get a huge amount of traffic, but serves as a good resource. You can find this by tapping the Settings icon (which looks like a gear or cog) and scrolling to the bottom of the screen. I've barely scratched the surface of what XFormer can do - the feature set and functionality is really quite incredible. From a 6502 Debug mode, to hot-swapping disk images, to loading single Atari files that are seen as Atari disk images - there's quite a bit more here than I'm able to cover!
Feel free to experiment with different settings for Dospad - you can customize the configuration in-app by tapping the Settings icon and selecting "Customize Config." Personally, I find that XFormer works best with Dospad CPU cycles set to 10000 - and the "core=dynamic" feature in the config file.
Here's the relevant part of what my configuration file looks like:
# Try core=dynamic to improvement performance
# however, it doesn't always work.
# so we are using simple core by default
An external/bluetooth keyboard -does- work with Dospad (and XFormer) but it's not perfect. Keymapping, as I mentioned, is tough. The <Shift> key is the biggest culprit I encounter when using an external keyboard -- mapping it should be possible, but I haven't been successful. I typed in a short program from the Atari Connection magazine, and was able to do the bulk of it with the external keyboard. When something like quotation marks were called for, a quick tap of the Shift + " key with the iPad in portrait mode (and, thus, the keyboard visible) worked just fine. If you have a ton of "DATA" statements to do, no worries! Parentheses, on the other hand, are a different story.
This concludes the Atari Emulation on iOS guide. This version, 1.0, was originally written as a companion piece for the ANTIC Atari 8-bit podcast, in October 2014, by C. Olson. Except for the paid Cydia apps, all software that I have mentioned here is readily available and free of charge. Feel free to distribute this guide, but please do so in its entirety and provide attribution. Thanks for reading, and enjoy the Atari! -CGO
<< END Atari iOS Guide <<