Tindie ESP32 SoftCard Expansion Card User Manual
- June 1, 2024
- tindie
Table of Contents
ESP32 SoftCard Expansion Card for Apple II
Family of Computers
Installation and User’s Manual
Introduction
The ESP32 SoftCard is designed to extend the capabilities of the Apple II family of computers using the ESP32 module. Similarly, to the original Z80 SoftCard, it has its own processor allowing it to run software not originally meant for the Apple II. Also similar to the original 80-column card, it generates its own composite video. The composite standards NTSC, NTSC-50 and PAL are supported and the user can switch between them using a command. In addition, the ESP32 SoftCard produces its own 8bit sound that is mixed and played through the Apple IIspeaker. For most of its applications the card also needs a FAT32 formatted microSD card, which is provided.
As of version 3.07 of its firmware the ESP32 SoftCard has the following capabilities:
- Run Doom. Its shareware or full WAD files and MP3 music need to be placed in a folder of the SD card.
- Run Wolfenstein 3D. A shareware or a full version of the game needs to be in a folder of the SD card.
- Emulate a Macintosh classic. The ROM and floppy/hard drive images need to be on the SD card.
- Emulate an IBM PC/XT compatible running DOS and Windows 3.0. The floppy/hard drive images need to be on the SD card.
- Emulate Sega Master System, NES and TurboGrafx-16 (a.k.a. PC Engine in Japan). The game ROMs need to be on the SD card.
- Play videos stored on the SD card. The maximum resolution is 320×240 for PAL or NTSC-50 and 320×200 for regular NTSC.
- Connect to the Internet through Wi-Fi.
- Listen to Internet audio streams or play MP3 files stored on the SD card.
- A rudimentary 80×25 text mode command console with more than 30 distinct commands.
- Support for an Apple II joystick. The joystick can be used in Doom, Wolfenstein 3D, the game console emulators and the Macintosh emulator, where it can either be a regular joystick or emulate a mouse. In the PC/XT emulator it controls the arrow keys, but it does not emulate a mouse.
- Support for the Apple Mouse II. The mouse can be used in Doom, Wolfenstein 3D, SMS, NES, TurboGrafx-16, the Macintosh emulator and the PC/XT emulator.
- Support for 256 grayscale mode for monochrome monitors.
- Ability to upgrade the firmware from the SD card as new capabilities/bug fixes are added.
- An FTP server which gives access to the entire SD card.
Hardware Requirements
The card has been thoroughly tested on Apple II+, Apple IIe and Pravetz 82. It
has also been shown to work properly on Apple IIgs, Laser 128, Pravetz 8C and
Pravetz 8M by some of the early adopters.
The ESP32 SoftCard is not a bootable card and it requires either a Disk
II/Smartport emulating device, such as FloppyEmu, CFFA3000 Card, Dan ][
Controller, TJ Boldt ProDOS card, etc., or an actual Apple II floppy drive
with at least one empty diskette.
The card ships with a 20″ (50 cm) video cable and a 32 GB microSD card.
More information can be found on the Applefritter website or simply by
searching for “The ESP32 SoftCard for the Apple II”.
Installation
The ESP32 SoftCard can be installed in any free slot of an Apple II/II+, IIe or IIgs. The program that runs on the Apple II CPU automatically determines the slot.
Video Loop
The video signal must be connected through the card, so that it can
automatically switch between the Apple II composite video signal and composite
video generated by the ESP32 module. The card comes with a 50 cm (20”) video
cable. It can be used to connect the composite video output of the Apple II to
the lower RCA connector labeled VIDEO IN on the card. The monitor then must be
plugged in to the upper RCA connector labeled VIDEO OUT. When the card is not
in use, the Apple II video signal simply comes in though VIDEO IN and goes out
through VIDEO OUT.
Audio Loop
The Apple II speaker must also be connected though the card for the sound to
work.
The supplied female-female jumper cable can be used to connect the speaker
connector on the Apple II motherboard to the connector labeled SPEAKER IN on
the card. The Apple II speaker itself must be plugged-in to the connector
labeled SPEAKER OUT on the card. If the speaker cable is not long enough, the
supplied male-female jumper cable can be used as an extension.
The card was specifically designed to prevent any damage by reversing the plus
and minus of the SPEAKER IN connector. Because of this, a trial and error can
be used to determine the proper polarity. The default Apple II boot beep will
be heard only when the polarity is correct.
The Apple II+/Apple IIe IIgs Jumper
This jumper must be closed if the ESP32 SoftCard is hosted in an Apple II/II+
and open if hosted in an Apple IIe. There is no risk of damage if the jumper
is not set correctly, however it will have the following negative effects: for
Apple II/II+ the sound from the
Apple II will be really quiet and for Apple IIe and IIgs there might be noise
coming out of the speaker when the Wi-Fi is operating.
Power-on Boot Beep
When the Apple II is powered on, the ESP32 SoftCard makes its own 2 kHz boot
beep.
It can be heard immediately after the Apple II boot beep when the sound is
wired correctly as shown on this video:
https://www.youtube.com/watch?v=Jak6qlXeGTk
Basic Operation
The ESP32 SoftCard Interface Program
The ESP32 SoftCard Interface Program runs on the Apple II CPU and provides
all the communication between the Apple II peripheral devices and the ESP32
SoftCard. It is written in Assembly and it can run under DOS 3.3 or ProDOS. It
can be loaded from an Apple II floppy or any Disk II/SmartPort emulating
device, like a CFFA3000 Card, a Dan ][ Controller, a TJ Boldt ProDOS card,
etc. It also has its own version number that is independent from the version
number of the ESP32 SoftCard’s firmware.
The Interface Program comes in two almost identical varieties: ESP32NTSC and ESP32PAL. Which one of the two is executed determines the initial video standard of the composite video signal generated by the card. This is necessary, because some NTSC displays do not support PAL and vice-versa. The card supports both standard and the user can switch between them by typing the commands PAL or NTSC from the cards command prompt. However there is no way to automatically determine which video standard the connected display supports, so if for example the card always started in NTSC, some PAL displays will just show a blank screen and the user will never see the card’s command prompt.
The following ZIP file contains a DOS 3.3 and a ProDOS image of version 1.0:
ESP32 SoftCard Interface Program v1.0.zip (All Apple ][, ][+, //e)
ESP32 SoftCard Interface Program v1.0.C.zip (IIgs and clones)
Once ESP32NTSC or ESP32PAL is executed, the following is quickly shown on the screen before the video signal switches to the one generated by the card:
The ESP32 SoftCard’s Command Prompt
Once the video switches to the ESP32 SoftCard, all keyboard, joystick and
mouse events are sent to the card by the Interface program. The user is
presented with an 80×25 text screen and a command prompt. More than 30
different commands are available and typing HELP provides a list and a short
description. The up and down arrow keys as well as the
key on the Apple IIe behave as backspace, while hitting
List of Commands
BEEP or
BEEP
HOME or CLS – clear the screen and place the prompt in the top line
NTSC – switch the composite video standard to NTSC
NTSC-50 or NTSC50 – switch the composite video standard to NTSC-50
PAL – switch the composite video standard to PAL
STANDARD – display the current composite video standard
STANDARD
SCAN – perform a Wi-Fi network scan and list the results
CONNECT – connect to a Wi-Fi hotspot after performing a network scan
CONNECT <#> – connect to the hotspot specified by the number
CONNECT
DISCONNECT – disconnect from the currently connected hotspot
FTPSERVER – start the FTP server on port 21
FTPSERVER ANONYMOUS – start the FTP server and allow anonymous users only
FTPSERVER
FTPSERVER STOP – stop the FTP server
IPCONFIG or IP – display the IP information
MEMORY or MEM – display the current memory usage
FONT – display all characters of the system font
JOYSTICK – test and calibrate the joystick if present
MOUSE – test and configure the Apple Mouse II if present
SCREEN – adjust the picture position on the screen
SYSTEM – display various system information
TASKS – list all currently running tasks
UPDATE – update the firmware from the SD card
EXIT – exit the ESP32 SoftCard interface program and return to Basic
REBOOT – reboot the ESP32 SoftCard without returning to Basic
DOOM – start the version of Doom placed in /Doom
WOLF3D – start the version of Wolfenstein 3D placed in /Wolf3D
TG16 or PCE – start the TurboGrafx-16 (a.k.a. PC Engine) emulator
SEGA or SMS – start the Sega Master System emulator
NINTENDO or NES – start the Nintendo Entertainment System emulator
MACINTOSH or MAC – start the Macintosh Classic emulator
PC – start the IBM PC/XT compatible emulator
VIDEO – start the video player in browse mode for videos placed in /Videos
LISTEN – list all Internet audio streams placed in /AudioStreams.txt
LISTEN <#> – listen to the audio stream specified by the number
PLAY <filename/video> – play the specified MP3 file or video from /Videos
PLAY <#> – play the MP3 file or video in /Videos specified by the number
PAUSE – pause the current MP3 or audio stream playback
RESUME – resume the paused MP3 or audio stream playback
STOP – stop the current MP3 or audio stream playback
VOLUME <#> – change the volume of the MP3 or audio stream playback
CATALOG or CAT or DIR – list the current directory
PREFIX or CD – display the name of the current directory
PREFIX <#> or CD <#> – change the current directory (specified by number)
PREFIX
Audio Out
Some monitors from the 80s (like the Philips one above) have a built-in
speaker and an audio amplifier. And even though the card does not have a
connector for external audio, it is fairly easy to add one for anyone with
minimal soldering skills. The desired connector can be placed anywhere in the
prototyping area and needs to be connected to ground and the top pin of the
RV3 potentiometer as indicated below:
CAUTION – The SPEAKER OUT connector cannot and must not be used for this
purpose, because it is not connected to ground.
Creating a Boot Disk with the ESP32 SoftCard Interface and Cassette Port
As previously mentioned, a DOS 3.3 or ProDOS image containing the Interface
Program can be downloaded from this link: ESP32 SoftCard Interface Program
v1.0.zip
and it can be used in any Disk II/SmartPort emulating device, like a CFFA3000
Card, a Dan ][ Controller, a TJ Boldt ProDOS card, etc. However, if the user
only has a single floppy drive and none of these modern cards, it is still
quite easy to create a DOS 3.3 or ProDOS boot disk containing ESP32NTSC and
ESP32PAL.
For this purpose the Apple II’s Cassette In port can be used with a smart phone or a laptop using an ordinary 3.5 mm AUX audio cable. Here are the steps:
- Place the Disk ][ Interface card in slot 6 and connect the floppy to Drive 1. This will not work in any other slot.
- Connect the Cassette In port to the headphones port of your smartphone or laptop using the AUX audio cable. After that make sure the volume is at maximum.
- Without a floppy in the drive turn the Apple II on and then hit
. This will cause the drive to stop spinning the machine will boot into Basic. - Insert an empty floppy disk into the floppy drive and close its door.
- From the Basic prompt type LOAD and hit
- From your smartphone or laptop play one of the two AIF files contained in the ZIP archive: ESP32 SoftCard v1.0.AIFs_.zip
Then just wait and follow the instructions on the screen. The entire process takes less than 2 minutes and when completed the machine will reboot from the newly formatted floppy disk.
ESP32 SoftCard Video Converter
The ESP32 SoftCard has a video player which is capable of playing videos
with a maximum resolution of 320×200 in NTSC and 320×240 in PAL. It is also
capable of 15x fastforward and reverse using the arrow keys. However the ESP32
is not powerful enough toplay just any video format and downscale it to the
NTSC or PAL graphics resolutions. Thisis why the videos must be pre-converted
and reencoded using a modern PC. There is a small tool for Windows that can
convert multiple videos of various formats in a batch process.
ESP32 SoftCard Video Converter v1.0
ESP32 SoftCard Video Converter v1.0.zip
(Windows)
ESP32_SoftCard_Video_Converter.zip (MacOs and
Linux)
This tool uses FFmpeg to convert videos of many different formats and any
resolution to a format that the ESP32 SoftCard can play. For each video it
creates a separate sub-directory and produces 10 different files, 5 for NTSC
and 5 for PAL.
It also auto-generates a thumbnail for each video, if one is not provided.
This thumbnail is what appears on the screen when the ESP32 SoftCard’s video
player is in browse mode.
Usage:
- Extract the contents of the ZIP file into a separate directory on your PC.
- Place all 4:3 videos in the sub-directory InputVideos4by3 and all 16:9 videos in InputVideos16by9.
- Run Go.bat and wait for the ALL DONE message. This can take a while depending on the number of videos and the speed of your PC.
- Copy the entire contents of the OutputVideos sub-directory to /Videos on the SD card. Each video needs to be in its own sub-directory.
Important: The /Videos directory on the SD card should not contain any
files, just sub-directories.
The conversion will also generate a thumbnail image for each video and place
it in the same directory as the input video, if one is not provided. The
timestamp for the auto-generated thumbnail image is defined in Go.bat and can
be changed. If a thumbnail image is provided, it will not be overwritten. The
thumbnail has the same filename as the video, but with a .PNG extension. One
strategy is for run the conversion once to generate all the thumbnails, modify
them if needed and then run it again.
Here are the 10 generated files for a video called Example.mp4:
- Example.ntsc.ts – the main playback video for NTSC with sound
- Example.ntsc.fwd.ts – the 15x speed fast-forward version of the video w/o sound
- Example.ntsc.rwd.ts – the 15x speed reverse version of the video w/o sound
- Example.ntsc.idx – an index file used for synchronization during FF and Rewind
- Example.ntsc.img.ts – the thumbnail of the video to display in browse mode
- Example.pal.* – the other 5 files for PAL, equivalent to the ones described above
Contents of the ESP32 SoftCard Video Converter:
-
InputVideos4by3 – an empty sub-directory where all 4:3 videos should be placed for conversion by the user
-
InputVideos16by19 – an empty sub-directory where all 16:9 videos should be placed for conversion by the user
-
OutputVideos – an empty directory where all converted videos will be placed by the conversion process, each in its own sub-directory
-
Convert.bat – a batch file that generates the 5 different files by calling ffmpeg.exe. This batch file is only called by Go.bat
-
Go.bat – the batch file which converts all videos placed in InputVideos4by3 and InputVideos16by9
-
ReadMe.txt – instructions how to use the tool
-
ffmpeg.exe – one of the 3 executables of FFmpeg. It does all the heavy lifting.
Downloaded from: https://ffmpeg.org -
VideoIndexer.exe – a small command-line utility written in C that generates the index file
-
VideoIndexerSource.zip – the C source code of VideoIndexer.exe
Firmware revision history:
v1.00
– Initial full featured release
v1.01
– Video Player: Added separate videos for PAL and NTSC due to the different
aspect ratios.
– Video Player: Fixed a bug causing the picture not to be centered
horizontally in NTSC.
v1.02
– Doom: Fixed a crash at the end of the first level right before the level
complete screen.
– Doom: The settings will now be saved when the user saves a game and when he
quits Doom.
– Audio Player: Executing the LISTEN command while not connected to the
Internet will now initiate a Wi-Fi connection.
– Audio Player: Increased the timeout of the LISTEN command, which was only
250ms – not enough when the streaming site is too far.
– Audio Player: Playback will now stop before starting Doom, Wolfenstein 3D,
the video player or any of the emulators.
– SD Card: Listing a directory will no longer show sub-directories and files
starting with a dot.
v1.03
– Wi-Fi: Increased the connect timeout from 10 to 20 seconds.
– Audio Player: Fixed a crash that happens sometimes at the very end of an
MP3.
– Video Player: Doubled the buffer of the SBC codec to 8K to avoid buffer
overflow causing popping in the audio.
v1.04
– Added the NTSC-50 composite video standard (320×240) for older NTSC color
CRT TVs and monitors. To switch, just type NTSC-50.
– Video Player: fixed a crash when trying to play an unconverted video or an
MP3 placed in the /Videos directory.
– Command prompt: Hitting
v1.05
– Sega/Nintendo emulators: Fixed the incorrect sound frequency in NTSC-50.
v1.06
– Mouse: Added the ability to invert the X-axis or Y-axis of the mouse using
the MOUSE command.
– SD Card: The SYSTEM command now also shows the number of sectors and the
sector size of the SD card.
v1.07
– Mac emulator: increased the memory available to the Mac emulator from 2.5 MB
to 3 MB.
– Mac emulator: executing the MAC command from a sub-directory will load the
Mac ROM and disk images found in that sub-directory.
– Sega/Nintendo emulators: executing the SEGA or NINTENDO command from a
subdirectory will only show the ROMs in thatsub-directory.
v1.08
– Fixed a video noise issue that was occurring when the ESP32 SoftCard is
hosted inside an Apple IIgs.
– Nintendo: Fixed an issue causing the video to break on NTSC when the game
“Blades of Steel” is launched first.
—–
v2.00
– Added the TurboGrafx-16 (a.k.a. PC Engine) game console emulator.
To start just type TG16 or PCE.
v2.01
– Command prompt: Updated the help screen to include the TG16/PCE command.
– TurboGrafx-16: fixed a bug causing some games to go into an unsupported
graphics mode on PAL when relaunched.
v2.02
– FTP server: fixed a bug causing random disconnects during the transfer of
large files.
– FTP server: fixed a bug that prevented non-anonymous users from being able
to connect.
– FTP server: increased the transfer speed from around 1 Mbps to around 2
Mbps.
– Audio player: fixed a bug causing HTTPS URLs not to connect. Now they
properly default to HTTP.
– Audio player: fixed a parsing bug that was causing some URLs with a colon
after a slash to fail.
– Audio player: fixed a bug causing long stream names or long URLs to break
the LISTEN command table.
—–
v3.00
– Added an IBM PC/XT compatible emulator. To start just type PC.
– Added the ability to toggle lowercase using
– Audio player: fixed a bug that was causing streams with 48K sample rate to
skip.
v3.01
– The Wi-Fi radio is now off until it is needed. This reduces to power
consumption of the card by 70 mA.
– Command prompt: fixed a bug causing the Wi-Fi password to remain unmasked
when using CONNECT
– Command prompt: fixed a bug causing spaces to be removed from the SSID also
when using CONNECT
v3.02
– PC Emulator: made the Hercules/MDA vertical synchronization requirements the
same as the ones for the Macintosh emulator.
– PC Emulator: fixed a bug preventing the typing of numbers or pressing the
left mouse button on all Apple II+ with no joystick.
– PC Emulator: fixed a bug causing all Sierra On-Line AGI games not to display
properly when TGA or CGA is selected.
– PC Emulator: fixed a bug causing incorrect colors in 256-color MCGA mode for
games that update the palette dynamically.
v3.03
– Video Player: fixed a crash in PAL when the screen has been shifted all the
way to the right using
v3.04
– Mac and PC emulators: added an option for 480i in NTSC and 576i in PAL for
Plasma/LCD/LED TVs and monitors.
– Mac emulator: added a table showing the disk images that will be mounted,
similar to the PC emulator.
v3.05
– NES emulator: fixed a bug that was causing the sound in Super Mario Bros. 3
to glitch on NTSC.
v3.06
– SMS emulator: fixed a major bug introduced in v3.00 that was causing
glitching in some games on NTSC.
v3.07
– PC Emulator: fixed a bug that was causing a reduction in performance after
exiting something using .