eremusone/espectrum

A ZX spectrum 48K, 128K and Pentagon 128 emulator running on the Espressif ESP32 SoC

This is an emulator of the Sinclair ZX Spectrum computer running on Espressif ESP32 SoC powered boards.

Currently, it can be used with Lilygo's TTGo VGA32 board, Antonio Villena's ESPectrum board and ESP32-SBC-FabGL board from Olimex.

Just connect a VGA monitor or CRT TV (with special VGA-RGB cable needed), a PS/2 keyboard, prepare a SD Card as needed and power via microUSB.

This project is based on David Crespo excellent work on ZX-ESPectrum-Wiimote which is a fork of the ZX-ESPectrum project by Rampa and Queru which was inspired by Pete's Todd PaseVGA project.

Features

• ZX Spectrum 48K, 128K and Pentagon 128K 100% cycle accurate emulation (no PSRAM needed).
• Perfect Z80 emulation (Authored by José Luis Sánchez)
• Selectable Sinclair 48K, Sinclair 128K and Amstrad +2 english and spanish ROMs.
• Possibility of using one 48K and one 128K custom ROM with easy flashing procedure from SD card.
• ZX81+ IF2 ROM by courtesy Paul Farrow with .P file loading from SD card.
• 6 bpp VGA output in three modes: Standard VGA (60 and 70hz), VGA 50hz and CRT 15khz 50hz.
• Support for two aspect ratios: 16:9 or 4:3 monitors (using 360x200 or 320x240 modes)
• Multicolor attribute effects emulated (Bifrost*2, Nirvana and Nirvana+ engines).
• Border effects emulated (Aquaplane, The Sentinel, Overscan demo).
• Floating bus effect emulated (Arkanoid, Sidewize).
• Contended memory and contended I/O emulation.
• AY-3-8912 sound emulation.
• Beeper & Mic emulation (Cobra’s Arc).
• Dual PS/2 keyboard support: you can connect two devices using PS/2 protocol at the same time.
• PS/2 Joystick emulation (Cursor, Sinclair, Kempston and Fuller).
• Two real joysticks support (Up to 8 button joysticks) using ESPjoy adapter or DIY DB9 to PS/2 converter.
• Emulation of Betadisk interface with four drives and TRD (read and write) and SCL (read only) support.
• Realtime (with OSD) and fast TAP file loading.
• TAP file saving to SD card.
• SNA and Z80 snapshot loading.
• Snapshot saving and loading.
• Complete file navigation system with autoindexing, folder support and search functions.
• Complete OSD menu in two languages: English & Spanish.
• BMP screen capture to SD Card (thanks David Crespo 😉).

Work in progress

• +2A/+3 models.
• TZX support.
• DSK support.
• On screen keyboard.

Installing

You can flash the binaries directly to the board if do not want to mess with code and compilers. Check the releases section

Compiling and installing

Quick start from PlatformIO:

• Clone this repo and Open from VSCode/PlatFormIO
• Execute task: Upload
• Enjoy

Windows, GNU/Linux and MacOS/X. This version has been developed using PlatformIO.

Install platformIO:

• There is an extension for Atom and VSCode, please check this website.
• Select your board, pico32 which behaves just like the TTGo VGA32.

Compile and flash it

PlatformIO > Project Tasks > Build , then

PlatformIO > Project Tasks > Upload.

Run these tasks (Upload also does a Build) whenever you make any change in the code.

Prepare micro SD Card

The SD card should be formatted in FAT16 / FAT32.

Just that: then put your .sna, .z80, .p, .tap, .trd and .scl whenever you like and create and use folders as you need.

There's also no need to sort files using external utilities: the emulator creates and updates indexes to sort files in folders by itself.

PS/2 Keyboard functions

• F1 Main menu
• F2 Load (SNA,Z80,P)
• F3 Load custom snapshot
• F4 Save customn snapshot
• F5 Select TAP file
• F6 Play/Stop tape
• F7 Tape Browser
• F8 CPU / Tape load stats ( [CPU] microsecs per CPU cycle, [IDL] idle microsecs, [FPS] Frames per second, [FND] FPS w/no delay applied )
• F9 Volume down
• F10 Volume up
• F11 Hard reset
• F12 Reset ESP32
• CTRL + F1 Hardware info
• CTRL + F2 Turbo mode
• CTRL + F5..F8 Screen centering in CRT 15K/50hz mode
• CTRL + F9 Input poke
• CTRL + F10 NMI
• Pause Pause
• PrntScr BMP screen capture (Folder /.c at SDCard)

ZX Keyboard functions

Press CAPS SHIFT + SYMBOL SHIFT and:

• 1 Main menu
• 2 Load (SNA,Z80,P)
• 3 Load custom snapshot
• 4 Save custom snapshot
• 5 Select TAP file
• 6 Play/Stop tape
• 7 Tape browser
• 8 CPU / Tape load stats ( [CPU] microsecs per CPU cycle, [IDL] idle microsecs, [FPS] Frames per second, [FND] FPS w/no delay applied )
• 9 Volume down
• 0 Volume up
• Q Hard reset
• W Reset ESP32
• I Hardware info
• T Turbo mode
• Z,X,C,V Screen centering in CRT 15K/50hz mode
• O Input poke
• N NMI
• P Pause
• S BMP screen capture (Folder /.c at SDCard)

How to flash custom ROMs

Two custom ROMs can be installed: one for the 48K architecture and another for the 128K architecture.

The "Update firmware" option is now changed to the "Update" menu with three options: firmware, custom ROM 48K, and custom ROM 128K.

Just like updating the firmware requires a file named "firmware.bin" in the root directory of the SD card, for the emulator to install the custom ROMs, the files must be placed in the mentioned root directory and named as "48custom.rom" and "128custom.rom" respectively.

For the 48K architecture, the ROM file size must be 16384 bytes.

For the 128K architecture, it can be either 16kb or 32kb. If it's 16kb, the second bank of the custom ROM will be flashed with the second bank of the standard Sinclair 128K ROM.

It is important to note that for custom ROMs, fast loading of taps can be used, but the loading should be started manually, considering the possibility that the "traps" of the ROM loading routine might not work depending on the flashed ROM. For example, with Rodolfo Guerra's ROMs, both loading and recording traps using the SAVE command work perfectly.

Finally, keep in mind that when updating the firmware, you will need to re-flash the custom ROMs afterward, so I recommend leaving the files "48custom.rom" and "128custom.rom" on the card for the custom ROMs you wish to use.

Hardware configuration and pinout

Pin assignment in hardpins.h is set to match the boards we've tested emulator in, use it as-is, or change it to your own preference.

Project links

• Website
• Patreon
• Youtube Channel
• Twitter
• Telegram

Supported hardware

• Lilygo FabGL VGA32
• Antonio Villena's ESPectrum board and ESPjoy add-on
• ESP32-SBC-FabGL board from Olimex

Thanks to

• David Crespo for his friendly help and support and his excellent work at his Youtube Channel and the ZX-ESPectrum-Wiimote emulator.
• Pete Todd, developer of the original project PaseVGA.
• Ramón Martínez "Rampa" and Jorge Fuertes "Queru" who improved PaseVGA in the first ZX-ESPectrum.
• Z80 Emulation derived from z80cpp, authored by José Luis Sánchez.
• VGA Driver from ESP32Lib by BitLuni.
• AY-3-8912 emulation from libayemu by Alexander Sashnov.
• PS2 Driver from Fabrizio di Vittorio for his FabGL library.
• Paul Farrow for his kind permission to include his amazing ZX81+ IF2 ROM.
• Azesmbog for testing and providing very valuable info to make the emu more precise.
• David Carrión for hardware and ZX keyboard code.
• ZjoyKiLer for his testing, code and ideas.
• Ackerman for his code and ideas.
• Mark Woodmass and Juan Carlos González Amestoy for his excellent emulators and his help with wd1793 emulation.
• Rodolfo Guerra for his wonderful enhanced ROMs and his help for adding tape load turbo mode support to the emulator.
• Antonio Villena for creating the ESPectrum board.
• Tsvetan Usunov from Olimex Ltd.
• Amstrad PLC for the ZX-Spectrum ROM binaries liberated for emulation purposes.
• Jean Thomas for his ESP32 APLL calculator.

Thanks also to all this writters, hobbist and documenters

• Retrowiki especially the people at ESP32 TTGO VGA32 subforum.
• RetroReal for his kindness and hospitality and his great work.
• Rodrigo Méndez Ron
• Armand López El Viejoven FX
• Javi Ortiz El Spectrumero
• José Luis Rodríguez VidaExtraRetro
• El Mundo del Spectrum
• Microhobby magazine.
• The World of Spectrum
• Dr. Ian Logan & Dr. Frank O'Hara for The Complete Spectrum ROM Disassembly book.
• Chris Smith for the The ZX-Spectrum ULA book.

And all the involved people from the golden age

• Sir Clive Sinclair.
• Christopher Curry.
• The Sinclair Team.
• Lord Alan Michael Sugar.
• Investrónica team.
• Matthew Smith for Manic Miner.

espectrum's Issues

ESPjoy

I own an ESPectrum and an ESPjoy from Antonio Villena. With this version 1.0, I cannot use my joystick.
I saw that it was necessary to update the firmware of the card.
On the github of the indicated page, the programming .hex file does not seem to be up to date, so I went through the Arduino IDE.
With an AVRasp programmer and configuring the target board as "Arduino Leonardo", it seems to me that it worked.
But, it still doesn't work in the emulator.
I may be confused with the menu with a PS/2 option and another joystick option.
Someone explain to me how it works?
THANKS.

Sub folders needed in parent folders to organize collections

Please can you enable use of sub-folders on "t","c","s","p" to reorganize collections of files?
Thanks

PS/2 to Joy shematics

Hi looked in the code and documentation but can't find a schematic on how to connect the db9 joystick ports to the ps/2 mouse port.

Where i can find it ?

Reading names of too many files in dirs failed

I have zip archives with several folders (Games, Music, Demos, Magazines, etc...) and a lot of files in each (61000+, 3000+, ...)
When reading these unpacked folders with 61000+ file names emulator crashes and restarts.
I understand the problem - no space in RAM for all of them
but maybe we could calc amount, and then read names by pages.
Also what do you think about zip support? Does it make a sense ?

Selected z80 or TAP changed after loading

Verification:

1. open z80 files with f2
2. position selected is first sorted z80 file
3. move dow to select a random z80 file
4. enter to load/execute
5. now reopen again z80 files with f2 to select another z80 file
6. position selected is again first z80 file, this should be done only after hard reset

How to save TAP?

I try to restore game progress in the ELITE game. I have a TAP file from Fuse emulator with my saves.
So, I load "Elite48.tap" then, when I try to change tape-file to file with my saves my ESPecroom restarts. What's wrong?

Typing quickly does not register all keypresses

I have been trying some non-game programs in the emulator, such as 128K BASIC, HiSoft Pascal Compiler, and Tasword.

For all of them, if you type too quickly, not all of the characters appear on the screen.

Please could this be fixed in a future release?

How do you flash a custom ROM?

The README.md says:

Possibility of using one 48K and one 128K custom ROM with easy flashing procedure from SD card.

However, I can find no documentation explaining how to do this. I have put a .rom file on the root of the SD card, but whenever I choose Update -> Custom ROM 48K or Custom ROM 128 k -> Yes, it says No custom ROM file found.

What should the custom ROM files be called? And where should they be placed?

Also, please can this information be added to the README.md so it's clear for anyone else with the same question?

Thanks in advance!

ESP32-SBC-FabGL open menu issue

Hello,
With your clues, I can now compiling and installing firmware on board with Visual Code Studio (PlatformIO).

I did a Clone of your repo and modified hardpins.h as you told me on the last post.
So I compiling and upload to the board.
Now, when I power the board, on my VGA monitor I can see spectrum default image aligned to left.
If I press F1 to access menus, the behavior is like if I keep pressing the "UP" key from keyboard, and could not stop the rolling selected option from the menu.
Only function keys (menu access) are working on my Ps/2 keyboard. When I press for ex; "J" key nothing happens

Note:
If I flash the board using your bin file from the releases section with ESP32 Flash Download Tool, the menus are working great without that issue, and image is align to center, and PS/2 Keyboard works fine. However can't access SD card as discussed before.

Do you have any suggestion???

Regards

Show full snapshot/tape names

When browsing from SNA/Z80 snapshots, or TAP files to load, files with longer names are truncated to 8+3.

Please make the Select Snapshot and Select TAP windows the width of the screen so that all filenames are fully visible.

ESPectrum 1.0 rc1 on ESP32-SBC-FabGL no image

Hello,
I flashed this board from olimex with your rc1 bin file, as I did on TTGo VGA32, but I have no display on my VGA monitor with this Olimex Board...
Maybe there is a fix, but I am not a programmer and I don't know how to compile form source code files.
If someone can help I will be gratful
Thank you

POKE function Issue.

Hi.
I see a new POKE function with "SS"+"CS"+"O" keys press.
When i go to the address box, i can delete the "16384" value with "CS" +"0" but i can't input a new value with the numeric keys
on the Antonio Villena's ESPectrum board.
Thanks.

ESPectrum 1.0 rc1 on ESP32-SBC-FabGL SD card issue

Hello,
When i select external Sd as my storage option, and press F5, no games list is presented.
This card when inserted om my other board TTGo vga32 works great.
Anyone can help me?
Regards

Libretro core

Hi,

The Libretro project is widely used in the emulation scene for its wide arrays of emulated computers, consoles, and game engines.

The project is centered around the concepts of cores, which are emulators built as dynamic libraries that use the Libretro API, and a frontend, which is an application that interfaces with the OS and is capable of loading a core and rendering its audio and video frames, and directs input events to it. RetroArch is the official Libretro frontend, but others exist.

It currently has a ZX Spectrum core, ported from the Fuse emulator, which I'm the original author, but I'd like to port the ZX-ESPectrum-IDF code to the Libretro API. Would the authors of this code be willing to change the license to LGPL, so it could be used with any Libretro frontend?

Best regards,

Andre

Error can't compile - could not find the package

Hello,

I was trying compile pico32 and when tried download dependencies it was giving me an error:

Tool Manager: Installing espressif/toolchain-riscv32-esp @↓ 8.4.0+2021r2-patch2 Error: Could not find package with 'espressif/toolchain-riscv32-esp @ 8.4.0.+2021r2-patch2' requirements for your system 'windows_amd64'

@rampa069 give support and adding in platformio.ini file after [env] next lines fix my error and can finish and play with ZX-ESPectrum-IDF:

[env] platform_packages = toolchain-riscv32-esp @ 8.4.0+2021r2-patch5

I open this Issues to help others can compile without error.

Best Regards and great job!

SD Card Support

Hi,
I assume that I can use a 32GB formatted FAT32 SD card. The directories documented under RC3 no longer seem to exist? I put everything in the root? I only created the two newly documented directories. Correct?
Greetings Axel

Acts as if the down arrow key is pressed.

Hi, just flashed the latest version, rc1 and it's behaving as though the down arrow key is being pressed in all menus. Not sure why that would be the case. I'm using a PS/2 keyboard (IBM Model M), which was fine with the previous beta. What happens is I press F1 to get the menu, the menu appears, there's a short (typmatic repeat delay?) and it starts going down the menu list by itself. And just goes round and round. Tried removing the keyboard (to see if that made a diff, after hitting F1 to get the menu) and it just loops around. Can 'catch' menu items with enter/return, and the sub menus show the same issue, looping around. Interestingly if I actually press the down arrow key, it speeds up and slows down when I release the key, so it's not a stuck key issue, seems to be something with the keyboard routine. The Snapshot list, it runs to the end and then stops (don't think that menu loops). Anyway, love the emulator, keep up the good work. Think this is by far the best ESP32VGA spectrum emulator available, if not the best standalone emulator period.

20230609_060151.mp4

Muted sound not recovered after loading new snapshot

Hi Víctor,

Verify with this MOP:

1. Load Monty z80 from here
   https://github.com/rcmolina/z802tzx3/blob/master/MONTY2.z80
2. Wait until game initial sound
3. Press F2 again and reopen the same file.
4. If sound still working, then repeat loading again.
5. If not sound any more, when F2 also notice moving the selecting file bar does nor generate any tick,, sound is lost forever until reset with F12