Apple-2-Tools/Epple-II
1
0
Fork 0
mirror of https://github.com/cmosher01/Epple-II.git synced 2025-01-09 10:29:45 +00:00
Code Issues Projects Releases Wiki Activity

more docs

Browse Source
This commit is contained in:
Christopher Mosher 2019-04-12 16:00:57 -04:00
parent 56c859cb0b
commit 1f6a73bcfa
5 changed files with 873 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
docs/_config.yml
View File

@ -1 +1,3 @@
theme: jekyll-theme-slate
show_downloads: true
google_analytics:
theme: jekyll-theme-cayman

5
docs/configuration.md
View File

@ -1,5 +1,6 @@
# Configuration
---
title: Configuration
---
The Epple \]\[ Emulator is most useful when properly configured.
After downloading and installing the Epple \]\[ Program, some System ROM (demo or real), and
optionally the peripheral card ROMs you want to use, you will need to configure the program.

1
docs/index.md
View File

@ -1,5 +1,6 @@
[screenshots](screenshots.md)
[configuration](configuration.md)
[reference](usermanual.md)
---

23
docs/screenshots.md
View File

@ -1,8 +1,7 @@
# Screenshots
## DOS 3.3 System Master boot
---
title: Screenshots
---
### DOS 3.3 System Master boot
image::dos330boot.png[]
@ -16,7 +15,7 @@ between Applesoft and Integer BASIC by using the `FP` and
## DOS 3.1 System Master on Revision 0 motherboard
### DOS 3.1 System Master on Revision 0 motherboard
image::dos310rev0.png[]
@ -39,7 +38,7 @@ later revisions.
## PRODOS 1.1.1 boot
### PRODOS 1.1.1 boot
image::prodos.png[]
@ -48,7 +47,7 @@ and disk drive. We're booting a PRODOS 1.1.1 disk.
## Bishop's Apple Split
### Bishop's Apple Split
image::applesplit.png[]
@ -92,7 +91,7 @@ RUN
## Mysterious Pink Line
### Mysterious Pink Line
image::pinkmystery.png[]
@ -118,7 +117,7 @@ RUN
## Display Aspect Ratio
### Display Aspect Ratio
image::aspectratio.png[]
@ -150,7 +149,7 @@ HOME
## Split Screen HIRES/LORES colors
### Split Screen HIRES/LORES colors
image::splitcolorstv.png[]
image::splitcolorsmon.png[]
@ -202,7 +201,7 @@ RUN
## Miscellaneous
### Miscellaneous
image::gplrom.png[]

855
docs/usermanual.md Normal file
View File

@ -0,0 +1,855 @@
---
title: User Manual
---
### Overview
Epple \]\[ (the Emulated Apple \]\[ is a free (as in GPLv3), cross-platform
(Windows, Linux) emulator of the Apple \]\[ and Apple \]\[ plus computers
from Apple, Inc. It strives for accurate emulation of the original machines,
with a few extra features added.
### Commands
#### slot
The `slot` command inserts a card into a peripheral slot of the emulated Apple.
```
slot <slot> <card>
```
`slot` Slot number, 0 through 7, to insert the card into.
`card` The type of card to insert into the slot (see <<cards>>):
* `language`
* `firmware`
* `disk`
* `clock`
* `stdout`
* `stdin`
* `empty`
The `slot` command inserts a card into a peripheral slot. For example:
```
slot 0 language
```
inserts a language card into slot zero. Use `empty` to remove a card:
```
slot 0 empty
```
[NOTE]
The emulated Apple should be _powered off_ before inserting or removing cards.
#### motherboard
The `motherboard` command configures the emulated Apple's motherboard RAM chips and strapping block.
```
motherboard ram {C|D|E} { 4K | 4096 | 16K | 4116 | - | (other-models) } [...up to 8]
motherboard strap {C|D|E} { 4K | 16K } <base>
```
The RAM configuration lines represent the rows of chips on the motherboard. The motherboard labels the
rows as C, D, and E. Each row has 8 chips, one per bit in a byte. The Apple \]\[ accepts 4K or 16K chips.
You use the `ram` command to insert (or remove) chips from the sockets.
You configure each row's address range by using a "strapping block" on the original Apple. In the
emulator, use the `strap` command to perform this function. You should strap 4K rows to a 4K range
of RAM. You should always assign some RAM to the zero address.
For more information about RAM configuration, see
https://archive.org/details/Apple_II_Reference_Manual_1979_Apple/page/n79[Christopher Espinosa, Apple II Reference Manual
(Cupertino, Calif.: Apple Computer, 1978), pp. 70-72].
In the +motherboard ram+ configuration line `(other-models)` of chips are supported, and will produce different bit patterns at power-on time:
```
MM5290
MK4116
MCM4116
```
Example of normal 48K RAM configuration:
```
ram e 16K
strap e 16K 8000
ram d 16K
strap d 16K 4000
ram c 16K
strap c 16K 0000
```
Example of 4K, showing how you could specify each chip:
```
ram e - - - - - - - -
ram d - - - - - - - -
ram c 4K 4K 4K 4K 4K 4K 4K 4K
strap c 4K 0000
```
Example of 4K at zero address, and 8K at HI-RES page one:
```
ram e 4K
strap e 4K 3000
ram d 4K
strap d 4K 2000
ram c 4K
strap c 4K 0000
```
#### import
The `import` command imports a binary image file into the emulated Apple's memory.
```
import slot <slot> { rom | rom7 | rombank } <base> <file-path>
import motherboard rom <base> <file-path>
```
`slot` Slot number, 0 through 7, of peripheral card to import the binary image into.
`base` Base address in hexadecimal within the given memory area at which to start loading the binary image.
`file-path` Path of the binary image to import.
The `import` command reads the binary image byte-for-byte from the given file-path
into an area of ROM in the emulated Apple. You can load into either the motherboard or
a card in one of the slots. For a card in a slot, you can choose either the normal ROM,
the bank-switched ROM, or the so-called *seventh ROM* area.
You also have to specify the base address within the specific memory
area at which the image file will be loaded. Note that the base address is specified as the offset
within the specific memory area, and not necessarily as the actual memory address as seen
by the Apple. So for motherboard ROM, for example, specifying a base as 2DED will cause the
image to be loaded at offset $2DED in the ROM, which will be addressed by the Apple at
memory address $FDED, because motherboard ROM *starts* at address $D000, and $D000 + $2DED = $FDED.
For peripheral cards, the ROM will be seen at locations `$Cs00-$CsFF`, where s is the slot
number (1 through 7). The *seventh ROM* can be seen as locations `$C800-$CFFF`; Jim Sather
describes this functionality in
http://www.scribd.com/doc/201423/Understanding-the-Apple-II-by-Jim-Sather-1983Quality-Software[Understanding the Apple II],
on page 6-4, section *The Seventh ROM Chip.* The EPPLE \]\[ emulator handles this processing correctly. A card can
also have bank-switched ROM, which will show up at addresses `$D000-$FFFF` when switched in
(stealing that address range from motherboard ROM... see
http://www.scribd.com/doc/201423/Understanding-the-Apple-II-by-Jim-Sather-1983Quality-Software[Understanding the Apple II],
p. 5-26 *The 16K RAM Card*).
#### load
The `load` command loads a https://applesaucefdc.com/woz/[WOZ 2.0 format] floppy disk image into one of the emulated disk drives.
```
load slot <slot> drive <drive> [ <file-path> ]
```
`slot` Slot number, 0 through 7, of Disk \]\[ controller card to load the disk image into.
`drive` Drive number, 1 or 2, of the disk drive on the controller card to load the disk image into.
`file-path` Optional path of the disk image to import. If omitted, a dialog box will be presented to select the file to load.
The `load` command will load a WOZ 2.0 image into a disk drive. Specify the slot that
contains a Disk \]\[ controller peripheral card, and specify which drive number (1 or 2).
[NOTE]
The floppy disk image MUST be a WOZ 2.0 DISK IMAGE.
Other formats (for example, nibble, +.nib+, DOS order, +.do+, PRODOS order,
+.po+, +.dsk+, or anything else) must first be converted to WOZ 2.0 format.
You can use https://applesaucefdc.com/[Applesauce] to generate such files from original floppy disks. Or you can convert +.dsk+ or +.d13+ images using +to_woz2+ (source: https://github.com/cmosher01/Apple-II-Disk-Tools ).
#### unload
The `unload` command removes a floppy disk image from one of the emulated disk drives.
```
unload slot <slot> drive <drive>
```
`slot` Slot number, 0 through 7, of Disk \]\[ controller card to which the drive is attached.
`drive` Drive number, 1 or 2, of the disk drive on the controller card to remove the floppy disk image from.
The `unload` command removes the disk from the specified slot and drive.
[WARNING]
If the disk has been modified but not saved, the modifications will be DISCARDED.
#### save
The `save` command saves changes made on an emulated floppy disk back to the original image file.
```
save slot <slot> drive <drive>
```
`slot` Slot number, 0 through 7, of Disk \]\[ controller card to which the drive is attached.
`drive` Drive number, 1 or 2, of the disk drive on the controller card to save.
The `save` command saves any changes that the emulated Apple \]\[ has made to the floppy
disk image. It is important to note that the emulator operates on the image only in memory, and does
not immediately write changes back to the real file. You need to issue the `save` command
in order to write changes back to the file. Note that the emulator will display a asterisk `\*`
next to the file-name of a disk image if it has any unsaved changes.
#### cassette
The `cassette` command performs various operations of the emulated cassette tape.
```
cassette load [ <file-path> ]
cassette rewind
cassette tone
cassette blank <file-path>
cassette save
cassette eject { in | out }
```
`file-path` File path of the cassette tape image file, a standard WAVE file.
See below for more information about operating the emulated cassette tape interface.
#### revision
The `revision` command specifies which revision of Apple \]\[ motherboard to use.
```
revision <rev>
```
`rev` Revision number of the motherboard. Currently, only two values make any difference in behavior: 0 or 1.
The `revision` command chooses which revision of the Apple \]\[ motherboard to
use. The only revisions that make any difference (for now, at least) are 0 or 1. Zero
is the original (rare) version of the motherboard, that only had two hi-res
colors (green and purple), and always displayed text with green and purple fringes.
### Display
The orignal Apple \]\[s didn't come with a display. The user needed to use either a standard
television or a monitor in order to see the computer's output. The EPPLE \]\[ emulates a variety of
displays; you can cycle between the different types using `F2`.
There are two major types of displays: televisions and monitors. Monitors generally have
higher quality (sharper) displays. The displays show the normal visible area of the NTSC
video signal generated by the emulated Apple \]\[ machine.
#### Monitors
The emulator provides a color monitor, and a green monochrome monitor.
These emulate standard, no-frills NTSC monitors. The most noticeable characteristic of a monitor
is the horizontal display of pixels. Monitors react faster than TVs, so two adjacent pixels will
not merge together; both will be distinctly visible, with blackness between them. For example,
type in the following Applesoft command, then cycle through the display types. The monitors
will show thin, vertical, green lines; TVs will show continuous horizontal lines.
```
GR : COLOR=4 : HLIN 10,20 AT 10
```
#### Televisions
Televisions react more slowly to
changes in the incoming video signal than monitors do, and as a result, horizontal pixels will
merge together, forming a more uniform appearance. EPPLE \]\['s television mode emulates the
signal decoding circuitry of a real television. This includes separating out the *chroma* portion
of the incoming NTSC video signal using a filter algorithm, and _calculating_ the color to display.
#### Scan Lines
NTSC displays (TVs or monitors) usually receive signals that are interlaced. However, the
Apple \]\[ doesn't generate interlaced screens. This causes blank rows between each displayed
row of pixels. The EPPLE \]\[ emulates this behavior, but also allows you to *fill in* these
black rows with a copy of the row above it, for a more continuous display (vertically). Use
the F4 key to toggle between these two modes.
#### Resolution
The Apple \]\[s are commonly documented as having a resolution of 280x192 pixels, and to an
extent this is true. Vertically there are 192 pixels, but since there is no interlacing,
it is more accurate to display them with one blank space between each. So the EPPLE \]\[ has
two times 192, or 384, vertical pixels in its display. Horizontally there are 280 pixels, but
each could also be shifted right one-half dot, allowing for two times 280, or 560, different
horizontal displayable positions. To emulate this, the EPPLE \]\[ shows each emulated pixel as
two pixels wide, and displays an emulated half-dot shift as an actual one pixel shift. So the
display area of the EPPLE \]\[ is 560x384. There is an informational area below and to the
right of the emulated display that shows various statistics of the emulator. So the total screen
area used by the EPPLE \]\[ is a standard 640x480 pixels.
#### Full Screen
The EPPLE \]\[ can run in either full-screen mode, or within a window. Use the `F3` key to toggle
between the two.
#### Informational Area
The area at the bottom and the right of the EPPLE \]\[ display show various information about
the emulator.
* POWER light
* current cards in SLOTS
* CASSETTE tape information
* emulated CPU speed (MHz)
* function-keys help
### Keyboard
The EPPLE \]\[ emulates the original Apple \]\[ keyboard. The original Apple \]\[
keyboard had symbols in different places than current common PC keyboards. For
example, Shift-2 on the Apple \]\[ produces a double quote, but on a PC keyboard
it produces an at-sign. For ease of typing, the EPPLE \]\[ emulator does not
mimic the positions of the original keys, but rather mimics the symbols on
the current PC keyboard. So, for example, if you type Shift-2 on the PC
keyboard into the EPPLE \]\[, it produces an at-sign, as you would normally expect.
The Apple \]\[ keyboard didn't produce lower-case letters; neither does the emulator.
Also, the Apple couldn't produce an opening square bracket ([), braces, vertical
bar, backslash. There were no up- or down-arrow keys. You cannot type these into
the emulator, either. There are other, unusual, cases that are emulated correctly,
as well, such as typing Control in conjunction with a number key simply produces
that number. So typing a Control-3 is the same as just typing a 3. Also, typing
Shift-Control-2 produces the NUL character (ASCII $80).
The Apple \]\[ keyboards didn't automatically repeat typing characters when a
key was held down. Instead, the user would hold down the REPT (*repeat*) key
while holding down the key that was to be repeated. On the EPPLE \]\[, this
behavior is emulated, and the F10 key is used as the REPT key.
The Apple \]\[ had no keyboard buffer (actually, it had a buffer of one character).
So if you typed several characters on the keyboard before the currently running
program had a chance to read them, they would get lost (only the final character
typed would be remembered). This behavior can be
toggled on or off in the EPPLE \]\[. By default, the EPPLE \]\[ will buffer up any
characters you type and deliver them to the emulated machine when it asks for
them. However, the Apple program must be written properly to allow this to work.
Some Apple \]\[ programs (like maybe some games) may not work correctly in this
respect, so you may want to turn off buffering in these cases. With buffering
turned off, the EPPLE \]\[ accurately emulates the original Apple \]\[. Use the F12
key to toggle the keyboard buffering. Note that pasting from the clipboard (with
the Insert key) will most definitely cause keys to be lost if the keyboard
buffer is turned off. So if you have a big Applesoft program in the clipboard
and you want to paste it into the EPPLE \]\[ correctly, make sure the keyboard
buffer is on.
Special Keys:
* `F1` Emulates the POWER switch on the back of the Apple \]\[.
* `F2` Cycles among different display types (TV, monitor, etc.).
* `F3` Toggles between full-screen or window display.
* `F4` Toggles between showing scan lines on the display, or duplicating
each scan line to the following line, to fill-in the otherwise black line.
* `F5` Go to *command entry* mode.
* `F6` Emulates the RESET key.
* `F7` Pastes characters from the clipboard into the emulated Apple
(as if they had been typed on the keyboard).
* `F8` Save a bitmap file of the current EPPLE \]\[ screen.
The file will be in the default directory, named +ep2_YYYYMMDDHHMMSS.bmp+.
* `F9` Quit the EPPLE \]\[ program, immediately!
* `F10` Emulates the REPT key.
* `F11` Toggles between running the emulator at authentic speed
(1.02 MHz CPU), or as fast as possible.
* `F12` Toggles the keyboard buffer.
### Peripheral Cards
#### Disk \]\[ Controller
The Disk \]\[ Controller card emulates the floppy disk controller card and associated
disk drives in the original Apple \]\[ systems. In the emulator, each card has two
drives attached to it, referred to as drive 1 and drive 2. The floppy disks
themselves are represented by a *nibble* image of the contents. The
emulator emulates the hardware, but to be of any use, you will need to provide
the firmware ROM code.
To use a disk card and drives, add these lines to your epple2.conf file, for example:
```
slot 6 disk
import slot 6 rom 0 /usr/lib/apple2/dos3x/16sector/controller/disk2.ex65
```
The first line uses the `slot` command to
insert a disk contoller card into slot 6, which is the standard
slot used for disk cards.
The `disk` keyword loads the 16-sector P6 ROM (Logic State Sequencer).
Alternatively, use `disk13` to load the 13-sector P6 ROM (for DOS 3.2 or earlier).
The next line uses the `import`
command to load the card's ROM with the disk controller
firmware. This firmware is known as the *bootstrap* or *P5* ROM code.
It is seen by the Apple \]\[ at memory addresses `$Cs00-$CsFF`, where s is the
slot number (so in the common case of the card being in slot 6, the ROM is
at `$C600-$C6FF`). The firmware is copyright by Apple, and is available from
the http://mosher.mine.nu/apple2/[Apple II Library].
You can also load a floppy disk image (nibble format) into the drive, either by putting
the `load` command into the `epple2.conf` file, or by using the command prompt
in the emulator (`F5` key). For example, you could load the DOS 3.3 system master into
slot 6, drive 1, with this command
```
load slot 6 drive 1 /usr/lib/apple2/dos3x/16sector/disks/dos330/clean330sysmas.nib
```
#### Language
The language card emulates an Apple 16K RAM card, commonly called a Language Card.
To use a language card, add this line to your epple2.conf file:
```
slot 0 language
```
Note that DOS and ProDOS will make use of a language card only if it is in slot _zero_.
The language card has RAM at addresses $E000 through $FFFF, as well as two banks of RAM
at addresses $D000 through $DFFF. A program switches between these RAMs and/or the
motherboard ROM by using the I/O switches at $C080 through $C08F.
The information area of the Epple \]\[ will show the current state of the
language card as follows:
* `R` Read from card RAM (vs. motherboard ROM)
* `W` Write to card RAM (vs. write-disabled)
* `B1` Use $D000 bank 1
* `B2` Use $D000 bank 2
An overview of the I/O switches that control the language card
is provided by Jim Sather in
http://www.scribd.com/doc/201423/Understanding-the-Apple-II-by-Jim-Sather-1983Quality-Software[Understanding the Apple II],
p. 5-30, Table 5.4, as follows:
|==================================================================
| BANK2 BANK1 ACTION READ?
|==================================================================
| C080 C088 WRTCOUNT = 0*, WRITE DISABLE ENABLE
| C084 C08C____________________________________________________
| RC081 RC089 WRTCOUNT = WRTCOUNT + 1* DISABLE
| RC085 RC08D____________________________________________________
| WC081 WC089 WRTCOUNT = 0* DISABLE
| WC085 WC08D____________________________________________________
| C082 C08A WRTCOUNT = 0*, WRITE DISABLE DISABLE
| C086 C08E____________________________________________________
| RC083 RC08B WRTCOUNT = WRTCOUNT + 1* ENABLE
| RC087 RC08F____________________________________________________
| WC083 WC08B WRTCOUNT = 0* ENABLE
| WC087 WC08F
|==================================================================
* Writing to expansion RAM is enabled when WRTCOUNT reaches 2.
#### Firmware
The firmware card emulates a (modified) Apple Firmware card.
The firmware card is simply an alternate ROM, at addresses
$D000 through $FFFF, that is switched using the I/O switches
at addresses $C080 through $C08F. In order to make use of the
firmware card, you will need to load the ROM with a binary image
from a file on disk. For example, to insert an Integer BASIC
firmware card into the emulator, add these lines to your
+epple2.conf+ file:
```
# Firmware card with Integer BASIC and old Monitor
slot 0 firmware
import slot 0 rombank 1000 /usr/lib/apple2/system/intbasic/intbasic.ex65
import slot 0 rombank 2425 /usr/lib/apple2/system/other/other.ex65
import slot 0 rombank 2800 /usr/lib/apple2/system/monitor/apple2/monitor.ex65
```
For an Applesoft BASIC firmware card, use these:
```
# Firmware card with Applesoft BASIC and Autostart Monitor
slot 0 firmware
import slot 0 rombank 0000 /usr/lib/apple2/system/applesoft/applesoft.ex65
import slot 0 rombank 2800 /usr/lib/apple2/system/monitor/apple2plus/monitor.ex65
```
Note that the addresses specified in the +epple2.conf+ file for the
rombank are based on the beginning of the bank ROM itself. For example, specifying
`1000` (which is 1000 hex) represents the final memory address of $E000, because
the bank ROM is always based at address $D000.
The idea is that you would load your motherboard with, for
example, Applesoft BASIC and the Autostart Monitor ROM (to emulate
an Apple \]\[ plus), and then install a firmware card with Integer
BASIC and the old Monitor. Booting with DOS 3.3, then, would allow
you to type `FP` to use Applesoft BASIC, or `INT` to switch to Integer BASIC.
Note that DOS and ProDOS will make use of a firmware card only if it is in slot _zero_.
Jim Sather, in
http://www.scribd.com/doc/201423/Understanding-the-Apple-II-by-Jim-Sather-1983Quality-Software[Understanding the Apple II],
on pages 6-18 through 6-21, explains
how to modify a firmware card to allow independent switching of the $F800-$FFFF
ROM memory. This area is occupied by the Monitor, so it is primarily
intended to allow the user to switch between the old Monitor and the Autostart
Monitor, independent of switching between Integer and Applesoft BASIC. The EPPLE \]\[
firmware card emulates this behavior.
The information area of the EPPLE \]\[ will show the current state of the
firmware card as follows:
* `D` Read from firmware card $D000-$F7FF (vs. motherboard BASIC ROM)
* `F8` Read from firmware card $F800-$FFFF (vs. motherboard Monitor ROM)
#### Clock
The clock card emulates a ProDOS-compatible real-time clock card for the Apple \]\[.
To use a clock card, you will need to configure the EPPLE \]\[ to insert one into
a slot, typically slot 4. You will also need to load the card with its ROM code,
which is provided with the emulator in the clock.ex65 file.
For example, add this to your epple2.conf file:
```
slot 4 clock
import slot 4 rom 0 /usr/lib/epple2/cards/clock.ex65
```
Of course you may need to adjust the path for your particular system.
To verify that the clock card is working correctly, you can run the following Applesoft
program to retrieve the current time from the clock card and print it.
This program assumes the card is in slot 4.
``` visualbasic
NEW
10 CALL -15360 : REM $C400 SLOT 4 ENTRY POINT
20 A = 512 : REM $0200 INPUT BUFFER
30 C = PEEK(A)
40 IF C < 160 THEN 99
50 PRINT CHR$(C);
60 A = A+1
70 GOTO 30
99 END
RUN
```
The card returns data (into the GETLN input buffer at $200) in
the following format:
`mm,ww,dd,hh,nn,ss,000,yyyy,Time Zone,v`
* `mm` Month, 01-12
* `ww` Weekday, 00=Sunday... 06=Saturday
* `dd` Day, 01-31
* `hh` Hour, 00-23
* `nn` Minute, 00-59
* `ss` Second, 00-61
* `000` Milliseconds; always zero
* `yyyy` Year, e.g., 2008
* `Time Zone` time zone string (could contain lower-case characters,
which won't display correctly)
* `v` Daylight Saving Time in effect, 0=no, 1=yes
Note that only `mm,ww,dd,hh,nn` fields are used by ProDOS. The other
fields, `ss,000,yyyy,Time Zone,v`, are an EPPLE \]\[ extension. Also note
that ProDOS was not designed to work for years past 2007, so
ProDOS will show the incorrect year, but the other fields will be accurate.
I believe patches exist for ProDOS to fix this.
#### Standard Input
The *standard input* card doesn't emulate a real piece of hardware; rather, it
reads characters from standard input (stdin) (of the EPPLE \]\[ emulator).
To use a standard input card, add these lines to your `epple2.conf` file:
```
# IN#2 reads from standard input
slot 2 stdin
import slot 2 rom 0 /usr/lib/epple2/cards/stdin.ex65
```
That will insert a stdin card into slot 2, and then load its
ROM image into the card.
The stdin ROM is provided with the EPPLE \]\[ distribution.
For example, if you have a stdin card installed in slot 2, start
the EPPLE \]\[ emulator from the command line, and at the Applesoft
prompt, type `IN#2`. Then you can switch back to the
command shell, and whatever you type will be fed into the emulated
Apple. Use RESET or `IN#0` to go back to normal.
#### Standard Output
The *standard output* card doesn't emulate a real piece of hardware; rather, it acts
similar to a printer card, but instead of sending characters to a printer, it sends
them to standard output (stdout) (of the EPPLE \]\[ emulator).
To use a standard output card, add these lines to your `epple2.conf` file:
```
# PR#1 prints to standard output
slot 1 stdout
import slot 1 rom 0 /usr/lib/epple2/cards/stdout.ex65
```
This will insert a stdout card into slot 1 (which is the typical
slot for a printer card), and then load its ROM image into the card.
The stdout ROM is provided with the EPPLE \]\[ distribution.
For example, if you have a stdout card installed, at the Applesoft
prompt, type `PR#1`. Whatever you type next will be
echoed to standard output. Type `PR#0` to stop echoing.
### Cassette Tape Interface
The Apple \]\[ and Apple \]\[ plus machines have the ability to save and load binary
data to and from cassette tape. The user would attach a standard cassette tape
recorder to the jacks on the back of the Apple \]\[, and use the monitor commands
`R` and `W`, or the BASIC commands `LOAD` and `SAVE`, to read and write data
on the cassette tape. The user would have to press the play and/or record buttons
on the player at the right time.
The Apple \]\[ has two cassette ports, CASSETTE IN and CASSETTE OUT. To save a program to
tape, the user would attach a cassette recorder to the CASSETTE OUT port, load a blank
cassette into the recorder, press RECORD (and PLAY), then on the Apple type SAVE. When
finished, the user would press STOP, and eject the tape.
To load a previously saved program
from tape, the user would attach the player to the CASSETTE IN port, then load and REWIND
the tape. The user would PLAY the tape until the header tone could be heard, then STOP.
On the Apple \]\[ the user would type LOAD and immediately press PLAY on the cassette player.
After the file loaded, the user would STOP and eject the tape.
The Epple \]\[ emulates the cassette interface, using a standard WAVE (PCM) file to
hold the recorded portion of the tape. It provides two ports, one for CASSETTE IN and
a separate one for CASSETTE OUT. Generally you'll use only one at a time. Use CASSETTE IN
for LOADing a program, or CASSETTE OUT for SAVEing a program.
To load a program from a cassette image WAVE file, use `cassette load`
to put the tape into the cassette player. The tape will automatically rewind and
advance to the header tone. Then use the Apple LOAD command to load the program
from the tape. If the Apple gives you `ERR`, that means it could not interpret the
WAVE audio correctly.
If you want to rewind the tape, you can use the `casssette rewind` command.
Use `cassette eject in` to close the file.
To save an in-memory program to a cassette tape image WAVE file, use
`cassette blank <file-path>` to put a new blank tape image into
the cassette recorder. Then use the Apple SAVE command to record to the tape, and then
`cassette save` to save the WAVE file. Use `cassette eject out` to close the file.
The emulator will not overwrite existing data in a tape image file.
#### Commands
`cassette load [ <file-path> ]`
This loads an existing WAVE file (from the host computer) containing a cassette tape image
onto the CASSETTE IN port,
in preparation for loading the program from it. If +file-path+
is omitted, a dialog box will be presented to select the file to load.
The tape is automatically positioned at the first header tone.
`cassette rewind`
This command rewinds the tape currently on the CASSETTE IN port. After rewinding
the tape, you will typically need to fast-forward to the head tone using
the +cassette tone+ command.
`cassette tone`
If more than one program is stored in one WAVE file, then after loading the first
program, you may need to fast-forward to the next header tone. This command will
do just that.
`cassette blank <file-path>`
This creates a new empty file (on the host computer) that represents a cassette tape image,
and loads it onto the CASSETTE OUT port,
in preparation for saving a program to it.
The file must not already exist. The file type should be +.wav+ to indicate a WAVE format file.
`cassette save`
This command saves the changed tape to the file. Note that the display will show
an asterisk `\*` next to the file name if there are unsaved changes that need to
be saved.
`cassette eject { in | out }`
This removes the file from the specified cassette port (CASSETTE IN port, or CASSETE OUT port).
#### Example of Saving to Tape
Start up the emulator with Applesoft ROMs for this tutorial.
Enter a simple Applesoft program, just as an example, that we
are going to save to a cassette tape image file.
``` visualbasic
]NEW
]10 PRINT "HELLO"
]20 END
]LIST
10 PRINT "HELLO"
20 END
]RUN
HELLO
```
We first need to load a tape image file into the cassette machine.
Enter command mode by pressing `F5`, then make a new tape
image file.
```
command: cassette blank hello.wav
```
This will create a new, empty tape file image named +hello.wav+
in the current default directory. (We could have specified a full path
name for the file if we wanted to place it in a different directory.)
Notice that the emulator now displays the name of the tape image file.
Next, we tell Applesoft to save the program to the cassette. For this,
we just use the `SAVE` command. Note that this is not the
DOS `SAVE` command; the DOS command has a file name after
`SAVE`. We just use `SAVE` with no file name.
``` visualbasic
]SAVE
```
It will take 10 seconds or so for it to save. Notice that the
current position of the tape is counting up as the Apple saves
the program. When it is finished, you need to save the changes
to the file. Press `F5` and enter the emulator command to save
the tape image file.
```
command: cassette save
```
Now do a NEW to clear the program, and LIST to prove that it's gone.
``` visualbasic
]NEW
]LIST
```
We can now eject the tape (close the file).
```
command: cassette eject out
```
#### Example of Loading from Tape
To load the saved program (from the previous section) into the Apple again,
we will need to first load the tape image file back into the cassette machine.
Press `F5` to enter command mode and load the image file.
```
command: cassette load
```
This will bring up the Open File dialog box. Choose
hello.wav file you just saved. Notice the
emulator now displays the name of the tape image file, along with the
position and length of the tape image. Notice the emulator automatically
advances the tape to the first header section.
Next, we tell Applesoft to load the program from the cassette. For this,
we just use the `LOAD` command. Note that this is not the
DOS `LOAD` command; the DOS command has a file name after
`LOAD`. We just use `LOAD` with no file name.
``` visualbasic
]LOAD
```
It will take several seconds for it to load. Notice that the
current position of the tape is counting up as the Apple loads
the program. When it is finished, the program will be loaded.
``` visualbasic
]LIST
10 PRINT "HELLO"
20 END
]RUN
HELLO
```
### Paddles
The Epple \]\[ provides two paddles to the Apple \]\[ machine.
One paddle is controlled by moving the mouse left and right; the other
paddle is controlled by moving the mouse up and down. The paddle buttons
are emulated by the mouse buttons (left and right click).
In
http://www.scribd.com/doc/201423/Understanding-the-Apple-II-by-Jim-Sather-1983Quality-Software[Understanding the Apple II],
on page 7-33, Jim Sather describes soldering fixed resistors across a game connector
to create two real-time clock references. This is emulated by the Epple \]\[. Paddle timers 2 and 3
are 100-microsecond and 1-millisecond references, respectively.
### Speaker
The Apple \]\[ could generate sound via a speaker that generated square wave
audio. A program could read memory location `$C030` to toggle the speaker and
generate a *click* sound.
The Epple \]\[ emulator will generate sounds from the emulated Apple and
send them to the audio device. It generates 8-bit mono sound, with a 22,050 Hz
sampling rate.