The ESP32 SoftCard for the Apple II

jeffmazur wrote:

To run the code:

1. Launch the CVT Merlin Pro image

2. Hit "R" to Read the file and type "CVT"

3. Type "ASM" followed by return

4. Hit "Q" return followed by "E"

5. Type "GET" return to load object code

6. Type "MON" return to enter monitor

7. Type 3000G to run program

I can't figure out an easy way to I get the assembly code into Merlin-Pro 2.43. I tried using CyderPress to add the text file and then use "Read text file", but the encoding seems to be different and it doesn't work. My idea is to write the assembly code in VS Code with the Merlin 6502 extension, which does syntax highlighting and IntelliSense and then somehow get it into Merlin.

With Merlin-8 v2.58 it's supper easy, since it has a multiline editor and I can just copy the source from VS Code and <Shift><Insert> it in AppleWin.

Btw, I was able to compile and run the second version in Merlin-8 after simply converting it to upper case in VS Code:

Merlin.gif

When I run it, it still goes to monitor and then I have to type 3000G. Is this happening because of Merlin-8?

I also tried it on the real hardware and it found the card and switched the video. There is a small bug causing keystrokes not to be sent until the joystick is moved, but I think I can fix it.

Yep, in all the excitement I was assembling and running the wrong file! The second version works almost perfectly on the real hardware too! Thanks for all your help, I think this is a great place for me to start.

I was looking for a very simple edit and run procedure and I think VS Code + Merlin-8 is good enough for now. Larger changes can be done by shift-inserting the entire source into AppleWin running Merlin-8 from a 32 MB ProDOS volume of an SD card. Then all I have to do is move the SD card from my laptop to the Dan ][ Controller and I can run it on the real Apple II with an ESP32 SoftCard. The microSD card extenders ended up being super useful for that. Smaller changes can be done simply within Merlin-8 on the real Apple II, since it's multiline editor is not so bad.

Here is the entire dev setup with the JTAG and UART connected. Normally the lid is closed and there is a color CRT monitor on top:

Setup.jpg

Well, at this point it's already working 100% like the Basic program, except probably faster by a double digit factor.

Some of the issues were actually being caused by running way faster than before. I found that at least 4 NOP operations are needed  when sending 2 consecutive bytes, otherwise the ESP32 ends up missing one. I added a much larger delay to be on the safe side. Going to assembly by itself is such a huge optimization, that I don't think I need to worry about it.

Project Update

I finally finished with the assembly program with full Apple Mouse II support. Now the mouse is working perfectly in the Macintosh emulator, but I left the joystick as well. I am also planning to enable it in Doom, Wolfenstein 3D and have it emulate a joystick in the Sega and Nintendo emulators.

The assembly program got more complicated than I expected, since the Apple Mouse II only works in clamped mode. This is perfect for fixed resolution with linear cursor motion. For example the resolution of the Macintosh Classic is 512x342, so when the mouse is clamped between 0,0 and 512,342 the mouse firmware itself makes sure it never goes off screen. However I needed it to be able to go infinitely far in any direction, so I ended up implementing a roll-over in the assembly program. Basically it starts in the middle of the bounding box and as soon as it hits one of the bounds it jumps right back to the middle. This allows it to go forever in any direction, without me having to worry that it will hit the bounding box and stop. This behavior allows me to use it as a joystick and also it can have a non-linear motion of the cursor, like in modern computers.

Here is the completed assembly program: ESP32.zip

Also for anyone getting into assembly for the Apple II, I would highly recommend the Merlin 6502 extension for VS Code. It has the most useful IntelliSence for every instruction, it’s completely aware of all Apple II special routine addresses and it has the ability to generate perfectly spaced code that looks pretty when pasted in Merlin. Even though I use Eclipse for development, it was easy to set up Eclipse to launch VS Code when double-clicking an .asm file. 

Once again big thanks to jeffmazur for providing the foundation.

Project Update

      -    In addition to the Macintosh emulator, I also added Apple Mouse II support to Doom, Wolfenstein 3D, Nintendo and Sega     

      -    Implemented true KeyDown/KeyUp events instead of just KeyPress for when the ESP32 SoftCard is hosted in an Apple IIe.

The latter allows for much more natural keyboard control for all the games when a key is held down, as it no longer relies on the Apple II’s hardware keyboard repeat. I would like to thank S.Elliot for his detailed blogpost on the AY-5-3600-PRO/KR9600-PRO bug. All Apple IIe machines with an original keyboard encoder have it and I would have wasted days if I ran into it blind, as I am using the same approach to detect KeyDown/KeyUp as Apple IIe’s implementation of Prince of Persia.

Speaking of which, the ESP32 SoftCard allows 3 additional 8-bit versions of Prince of Persia to be played (Nintendo, Sega and Macintosh), so I really wanted to get this one right.

PofP Nintendo.JPG

 

PofP Sega.JPG

 

PofP Macintosh.JPG

Project Update:

The firmware update capability is now complete. I decided to do it really simple through the SD card. I will post new firmware versions here or on other forums and they can be placed in a /Firmware folder on the SD card. Any version can be upgraded or downgraded to any other version, since the file contains the firmware in its entirety. The update takes about 75 seconds, during which the progress is displayed in the center of the screen in percents.

There are a number of fallback mechanisms to prevent bricking the card, including MD5 checksum of the written firmware as well as using 2 application partitions to make sure the old firmware is not deactivated until the new one is fully written and verified. The command to initiate the update is simply "update":

Update.JPG

jeffmazur wrote:

...

Sounds like you're ready for some real-world beta testing...  Can't wait to get my hands on one.

You are getting one for free for all the help with the assembly! :)

Today I am planning to order the first 10 assembled cards of Rev.2 and hopefully this will be the last revision. I had to add one more transistor and a jumper to select either Apple II/II+ or Apple IIe because to a difference in the speaker circuit between the two models:

Rev2Final.png

Actually this is an amazing idea for one more emulator. It is completely in line with the philosophy of the ESP32 SoftCard of extending the capabilities of the Apple II/II+/IIe, but not repeating them.

I just need to find a good open source Apple IIgs emulator to port. A quick search led me to this one, but I am a little worried that it was written as late as 2017, which means it would not have any speed optimizations and it might be too slow for the ESP32. And I wouldn't really know until I fully port it, which can take several 14-hour days. I ran into this when I was porting the Macintosh emulator. The first one I ported was based in PCE/macplus, but I ran into issues and had to completely scrap it and switch to Mini vMac, which is probably the best Macintosh emulator that exists today.

Another unknown is whether the ESP32 is fast enough to emulate a 16-bit processor running at 2.8 MHz even if the code is optimized. The Macintosh runs at 8 MHz but the vMac code was written in 1999 and it's highly optimized for speed. Both the Nintendo Entertainment System and Sega Master System emulators are emulating 8-bit processor running at 1.8 MHz and 3.58 MHz respectively. Doom on the other hand can render at more than 20 FPS, but it runs natively (not through an emulator) on the ESP32 SoftCard, which has a dual-core 32-bit processor running at 240 MHz.

Looking into this further, there is another limitation. The ESP32 SoftCard cannot produce 640x200 with colors, simply because the composite video standards NTSC and PAL do not support it. The color resolutions are limited to 320x200 for NTSC and 320x240 for PAL. The card can do 640x200 in NTSC or 640x240 in PAL (and this is what it uses in text mode) but only with 256 levels of grey. So if implemented, these Apple IIgs resolutions will appear grayscale.

robespierre wrote:

Analog color television standards do not say anything about pixels at all...

The standards might not say anything about pixels, but they do say a hell of a lot about color subcarrier frequencies and how much bandwidth is reserved for the luma versus the chroma. As a result a horizontal rasterization of 320 color pixels is something that almost all PAL color TVs and color monitors are capable of displaying fairly accurately, while almost none of them are able to do that for a horizontal rasterization of 640 color pixels. Same applies to NTSC, with a few more compromises.

Without the chroma however, the horizontal rasterization can go as high as 720 with a pixel sampling frequency of 16 MHz and most monochrome monitors will be able to display individual pixels. In the ESP32 SoftCard however I do not go over 640 and I set the pixel sampling frequency to 14.5 MHz for text mode.

natas666 wrote:

not sure if helpful or not: https://github.com/andrew-jacobs/em-65c816-esp32

and a bit more tested: https://github.com/ducalex/retro-go/tree/master/snes9x-go

very old https://www.zophar.net/apple2/xgs-32-xgs-dos.html

 

Yes, I know that SNES was ported for the ESP32, however it is very slow (it can only do about 25% of the speed of the console), which is why I decided not to bother with it. However the next gen ESP32 is coming soon and it will be able to go as high as 400 MHz, so maybe with some optimization it can be brought up to full speed.

profdc9 wrote:

A simple port for the ESP32 softcard could the PC emulator

http://www.fabglib.org/_v_g_a_2_p_c_emulator_2_p_c_emulator_8ino-example.html

https://hackaday.com/2021/07/28/emulating-the-ibm-pc-on-an-esp32/

Kind of like the PC Transporter.

I am watching this project very closely as well and I think Windows 3.0 is pretty impressive. But again I think the current gen of the ESP32 is a bit slow for most interesting PC-emulated programs. However the next one (ESP32-P4) might be fast enough.

Hardware:

The 10 cards of Rev.2 arrived from JLCPCB last week and the hardware is finally perfect. However I made a really rookie mistake by not double-checking the gerbers after I generated them from KiCad. As a result of not checking one single box, the silkscreen is missing all the component values as well as the very important labels VIDEO IN, VIDEO OUT, SPEAKER IN and SPEAKER OUT. I will not be sending these cards to anyone as I don’t want pictures of them on the Internet and I don’t want people plugging things in the wrong jacks. Yesterday I ordered another 10 cards with the corrected silkscreen and they should arrive in 2-3 weeks.

Software:

I decided to remove one of the features I listed in the first page of this topic: the text-based FTP client. This was the very first feature I added, and it was even before the card could generate its own composite video. Back then the card was acting more as a terminal. Here is a video from two years ago when I first got this working: https://youtu.be/t7niEO8KbfU

Back in those days I though this project would be an Internet connectivity card. But I let it find its own path and now it has taken a somewhat different direction, which has made the text-based FTP client rather silly in contrast with the rest of the capabilities. So, instead I just finished adding a more useful feature: an FTP server that provides full access to the SD card, so it doesn’t have to be removed from its slot or be connected through an SD card extender when the user wants to add something, like more Sega/Nintendo ROMs, MP3s or videos.

And with that the ESP32 SoftCard is finally feature complete both in terms of hardware and software.

FTP Server.JPG

Thanks!

I am not planning to order or ship empty PCB boards at this point however. Even though flashing the firmware from the SD card is very easy, this is not the case when flashing a blank ESP32 module for the first time. It cannot be done from the SD card and instead it requires an external programmer. Also the initial programming process itself contains several steps that are not automated and require the installation of a whole bunch of ESP32 development tools.

I received the latest batch of 10 yesterday and everything is finally perfect!

The cards from this batch will be sold at cost to the people who said that they wanted one in this forum prior to this post. I will also send a couple as presents to people who helped me with the project and the rest will go on eBay, so that I can figure out what they should cost.

I receive them almost completely pre-assembled from JLCPCB (bottom card on the picture below). Then I perform the initial programming through the UART, solder the two RCA connectors and the three pots, break the edge rails, put all the DIP chips in their sockets and the cards are ready for testing.

ESP32SoftCardRev2Made.JPG

Thanks! One of the fronts still lagging behind is documentation, so in the next few posts I’ll go though some aspects of the operation of the card. Hopefully when I’m done, I can compile everything into a single PDF. Since there is quite a lot of ground to cover, I’ll do this in parts and I’ll start with the installation:

Part 1: Installation

The ESP32 SoftCard can be installed in any free slot of an Apple II/II+ or IIe. The program that runs on the Apple II CPU finds it automatically.

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 its own composite video. 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. Also the 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 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 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

This is pretty much everything as far as installation goes. How to actually use the card is coming up in the next post.

Once again – thanks for the encouragement! Let’s continue with the documentation:

Part 2: 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

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:

InterfaceProgram.JPG

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 80x25 text screen and a command prompt. More than 30 different commands are available and typing HELP proves a list and a short description. The up and down arrow keys as well as the <Tab> key on the Apple IIe can be used to cycles through them. The commands are not case sensitive, even though they are listen in upper case. Both the left arrow and the <Del> key on the Apple IIe behave as backspace, while hitting <ESC> clears the currently typed command. 

Here are all currently supported commands:

Commands1.JPG

Commands2.JPG

This pretty much covers the basics. I will go into the various features in more detail in future posts.

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:

AudioOut.png

The SPEAKER OUT connector cannot and must not be used for this purpose, because it is not connected to ground.

Today I decided to have some fun with this: https://www.youtube.com/watch?v=r7pitaBpB2Y

Creating a Boot Disk with the ESP32 SoftCard Interface Program using the Cassette In Port

As previously mentioned, a DOS 3.3 or ProDOS image containing the Interface Program can be downloaded from the link in post #91 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 <Ctrl><Reset>. 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 <Enter>

      6. From you 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.

Here is a short video demonstrating the process described in the previous post: https://www.youtube.com/watch?v=GaqDtSio5L4

Update:

From the initial batch of 10 cards, 8 have already been shipped to the small group of early adaptors. As I mentioned earlier, the remaining 2 will go on eBay, and the first listing is already up: https://www.ebay.com/itm/256119408697

Here is the first public firmware update, which addresses some of the issues found by skate323k137 and jeffmazur (thanks, guys!):

 ESP32 SoftCard FW v.1.02.zip

To update just add the .bin file to the /Firmware directory on the SD card and execute the UPDATE command.

Complete version 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

There are still a coupe of lower priority issues, so another firmware update will follow in a few days.

Firmware Update

Here is the latest firmware with fixes for the remaining issues found by jeffmazur and skate323k137:

ESP32 SoftCard FW v.1.03.zip

Version history: (Continued)

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

Project Update

At this point I am looking into adding another emulator, this time the 16-bit Sega Genesis. I found an optimized port that is claiming to run at full speed with sound on a single core Cortex-M7 running at 280 MHz, so in theory it should be able to run at full speed on the ESP32 as well. However I wouldn’t know until I port all the code and get it to run, but I figured it’s worth the risk. Besides it has been ported to an ESP32 already, so it doesn’t seem like a lot of work.

If it works out, it might end up being the best emulator so far. I’ve been watching lots of videos on YouTube and the games for the Sega Genesis are sick!

As previously mentioned, the ESP32 SoftCard has a video player which is capable of playing videos with a maximum resolution of 320x200 in NTSC and 320x240 in PAL. It is also capable of 15x fast forward and reverse using the arrow keys. However the ESP32 is not powerful enough to play just any video format and downscale it to the NTSC or PAL graphics resolutions. This is why the videos must be pre-converted and reencoded using a modern PC. For this purpose I am releasing a small tool for Windows that can convert multiple videos of various formats in a batch process.

ESP32 SoftCard Video Converter v1.0

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:

    Example.ntsc.ts – the main playback video for NTSC with sound

    Example.ntsc.fwd.ts – the 15x speed fast-forward version of the video without sound

    Example.ntsc.rwd.ts – the 15x speed reverse version of the video without sound

    Example.ntsc.idx – an index file used for synchronization when switching playback to fast-forward or reverse

    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

A couple of notes:

    1. I realize that a lot of people don’t use Windows and I plan to release a Mac version later, but right now I don’t have the time and it’s the best I can do.

    2. I also realize that this utility includes 2 executable files. If you feel funny about downloading and running executables from a random guy on the Internet (and most definitely you should), please use a sandboxed PC or just download FFmpeg yourself and compile the VideoIndexer. Once again, this is the best I can do at this point due to time constrains.

Download: ESP32 SoftCard Video Converter v1.0.zip