Apple Emulation with Echo II or II Plus Emulation
Prepared by Jayson Smith
jaybird@bluegrasspals.com or Mastodon @jaybird110127@dragonscave.space
Using the open-source MAME emulator

# Introduction

This package contains an emulator called MAME which I have set up to emulate an Enhanced Apple IIe with an Echo II or Echo II Plus speech synthesizer. Here are some notes about the contents of this archive.

- In the disks subfolder are several talking disk images supplied so you can have fun with your virtual Apple. I have quite a few more, but these are just some to get you started.
- You'll also see a folder called roms, which you don't need to do anything with. If you go poking around in there anyway, you'll see several zip files. Do NOT unzip them, they are designed to stay zipped.

# Join the Blindapple mailing list!

Do you want to discuss this emulator, Apple games, and all things Apple II? Join my mailing list! Visit https://groups.io/g/blindapple or Send a blank message to blindapple+subscribe@groups.io and reply to the confirmation message you receive. This is a good place to get in touch with other blind Apple IIe enthusiasts.

# A Word About ROMs

According to the letter of the law, it is illegal to distribute the ROMs needed by this emulator to anyone who does not own the equipment being emulated. However, without those files, the emulator would be completely useless, and you'd have to find some way to obtain the ROMs. Since the firmware is so old, I'm taking the chance and distributing the files anyway.

# Obtaining the Package

Placeholder for how to get the package, this will be filled in when it goes live!

Unzip the package to a directory where you can get to the contents. This Readme will be one of the files.

# Before You Start

You may need a full desktop keyboard. If you're using Jaws, you'll also want to set up a script to put it to sleep when mame.exe is running. Otherwise, it will try to grab some Apple keystrokes, and in general not do very nice things.

# Getting Started

To start the emulator with a disk in drive 1, type the following at a command prompt, for example:

a2 -flop1 disks\egames.dsk

A2 is a batch file which runs the MAME emulator, passing all the proper parameters. You can replace egames.dsk with the name of some other disk image.

If you did everything correctly, you should hear the traditional Apple IIe system beep followed by simulated floppy drive noises, and you should hear speech within about fifteen seconds. Almost all bootable disks included in this package will talk when they boot. A few disks are not bootable, please see disks.txt for details.

Do not switch away from the emulator window after starting it, or while using the Apple. This may mess things up.

If you want to run BEX (Braille Edit EXpress) by Raised Dot Computing, you will need to use the a2bex command instead of just a2. A2bex is a batch file which configures the system to emulate an Echo II Plus rather than an Echo II, which BEX seems to require.

# Notes on Floppy Drives

The Apple IIe supports two floppy drives. They are designated on the command line as -flop1 and -flop2. If you want to put another disk, such as a data disk, in the second drive, just add another command line parameter -flop2 and the name of the second disk. The Apple will only boot from drive 1.

# Disks directory contents:

Please see the file called disks.txt in this directory for a complete list of files in the disks directory, along with descriptions.

You can put any disk images you already have into this folder.

# Notes on Using your Apple

Once the Apple has started, things pretty much work like you'd think they would. The four arrow keys really do act as the Apple's arrow keys, left and right alt on Windows, left and right option on Mac, are open and closed apple, F12 is reset. In most cases, even if your real caps lock is turned off, the Apple's caps lock will be turned on, simply because so many Apple games and programs require all upper case input. If you want to change this, just hit your caps lock.

# Instructions for using DOS

If you boot a disk and the Echo says, "Ready," with no instructions in sight, that means the disk doesn't have a menu system. Here are some pointers to get you started with such disks.

To get a catalog of the files on the disk, type CATALOG and press Return or Enter. If the Apple beeps and says, "Syntax Error, Ready," you need to push your caps lock. After every eighteen files, it will pause. Hit the space bar to continue. You'll know the catalog is finished when it says "Ready" again.

There are several types of files on disks. For each file, the first thing you'll hear is a letter. If the letter is A, you can run that program by typing RUN, followed by a space, followed by the name of the program and pressing Return. Files with a file type letter of A are written in Applesoft BASIC, the most common form of BASIC.

After the file type letter, you'll hear three digits. This relates to how much space the file is using on the disk, you don't have to worry about that. Finally, you will hear the file name, which can contain spaces. For example, if the system said, "A zero zero two HELLO," you could type RUN HELLO to run that program.

If the file type letter is I, this is a program written in an older form of BASIC called Integer BASIC. To run such programs, you first need to teach your Apple computer Integer BASIC. To do this, type: BRUN INTEGER and press Return. When that command completes, the system will say, "Greater than." Now you can RUN Integer BASIC programs just like Applesoft programs. You can keep running Integer programs until you reboot, turn the computer off, or run an Applesoft program. Any of these things will make the computer forget Integer BASIC, so you'll have to BRUN INTEGER to teach it again if you want to run another Integer program. Note that on some disks, the Integer BASIC program may be called INT instead of INTEGER.

On all talking DOS 3.3 disks included here, you'll see a few files you don't need to run. Every disk will contain an Applesoft program called HELLO. This is the program that runs when the disk is first booted, so you don't need to run it again. There will also be files with a file type letter of B called TEXTALKER.RAM and TEXTALKER.OBJ, or names similar to these. These are files relating to the Textalker software which makes the system talk. You don't need to worry about these.

If you need a quick reminder about all of this, boot using the egames.dsk disk. First it will ask if you want slow speech, press Y or N depending on your preference. Then it will tell you this disk contains games and programs in DOS 3.3, and ask if you want notes about using them. Answer Y here, and you'll be given instructions.

The disk called echocric.dsk contains lessons on using the Echo speech synthesizer. You should consult these lessons for information about controlling the Echo speech and reviewing the screen. Complete instructions are included.

# Session Recordings

The program records a wav file of your Apple session in a file called session.wav. If you don't want this file, just delete it. It is overwritten with each new emulator session, so if you do anything you want to preserve, you need to take steps to do so before you run Mess again.

# Switching Disks

We don't currently know of a good way to switch disks, but for now, the following method will work.

1. Press F9 to get to MAME's user interface mode.
2. Press F6, then press one more key. We prefer to press a number key, such as the digit 1. The key you press may be seen by the Apple. In most cases, this won't matter.
3. Press Escape to exit the emulator.
4. Run the emulator again, just as you did before, but with different filenames for the -flop1 and/or -flop2 parameters. However, after disks are specified, you must put a space after the last filename, then type -state, a space, and the one character you used. For example, "-state 1"
5. When you press Enter to run this command, the Apple may or may not beep. In either case, it should be at exactly the same place it was before, but with different disks in the drives.

# Notes about Loading Times

Please be aware that this program doesn't significantly speed up disk access, so there may be long pauses while Apple programs load. If you have requested a program and the system seems to have frozen, just give it some more time. Some programs load very slowly, as they did on the real hardware. MAME does simulate the floppy drive noises, so you should be able to tell if a program is still loading.

# Exiting

To exit the emulator, first press F9 to enable MAME's user interface keys. Then hit escape. This will flip the power switch on the virtual Apple, so anything you were doing will be lost forever.

Have fun!