Tindie ESP32 SoftCard Expansion Card User Manual

June 1, 2024
tindie

ESP32 SoftCard Expansion Card for Apple II
Family of Computers

Tindie ESP32 SoftCard Expansion Card

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:

Tindie ESP32 SoftCard Expansion Card - Fig 1

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 can be used to cycles through them. The commands are not case sensitive, even though they are listed in upper case. Both the left arrow and the key on the Apple IIe behave as backspace, while hitting clears the currently typed command.

List of Commands

BEEP or – produce a very short 2 kHz beep
BEEP – produce a 2 kHz beep with a specified duration
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 – switch to the specified composite video 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 – connect to the hotspot with the specified SSID
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 – start the FTP server and forbid anonymous users
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 or CD – change the current directory (specified by name)

and – Adjust the horizontal screen position and – Adjust the vertical screen position – Reset the horizontal and vertical screen adjustments – Toggle lower-case (applies to Apple II/II+ only)

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:
Tindie ESP32 SoftCard Expansion Card - Fig 2 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:

  1. Place the Disk ][ Interface card in slot 6 and connect the floppy to Drive 1. This will not work in any other slot.
  2. 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.
  3. 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.
  4. Insert an empty floppy disk into the floppy drive and close its door.
  5. From the Basic prompt type LOAD and hit
  6. 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:

  1. Extract the contents of the ZIP file into a separate directory on your PC.
  2. Place all 4:3 videos in the sub-directory InputVideos4by3 and all 16:9 videos in InputVideos16by9.
  3. 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.
  4. 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:

  1. Example.ntsc.ts – the main playback video for NTSC with sound
  2. Example.ntsc.fwd.ts – the 15x speed fast-forward version of the video w/o sound
  3. Example.ntsc.rwd.ts – the 15x speed reverse version of the video w/o sound
  4. Example.ntsc.idx – an index file used for synchronization during FF and Rewind
  5. Example.ntsc.img.ts – the thumbnail of the video to display in browse mode
  6. 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 now cycles back to the first command, instead of just stopping at the last.
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 when the host is Apple II+.
– 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 .

References

Read User Manual Online (PDF format)

Read User Manual Online (PDF format)  >>

Download This Manual (PDF format)

Download this manual  >>

Related Manuals