Skip to content

Latest commit

 

History

History
164 lines (136 loc) · 8.78 KB

readmeEnglish.md

File metadata and controls

164 lines (136 loc) · 8.78 KB
Raw

Tiny ESP32 Vectrex

x86 port of John Hawthorn's Vectrex emulator to the ESP32.

I have made several modifications:
  • Ported to ESP32
  • No PSRAM used, running on ESP32 520 KB RAM (TTGO VGA32 v1.x)
  • Use of a low-resource OSD
  • Created project compatible with Arduino IDE and Platform IO
  • Black and white mode 1 bpp (2 colors) VGA2Controller
  • 640x480, 800x600 and 1024x768 support
  • For video, fabgl 1.0.8 is used.
  • Half speed emulation, 23 fps at 640x480 and 19 fps at 1024x768
  • No sound at the moment
  • Support for reading cartridges via WIFI
  • Precompiled version (flash download 3.9.2) 1024x768



Precompiled version

In the precompile folder there is a version already compiled to be saved with the flash download tool 3.9.2. It is a version for the 1024x768 video mode and the FLASH demo games.

https://github.com/rpsubc8/ESP32TinyVectrex/tree/main/ESP32/precompile

We must choose the ESP32 type:

Subsequently, select the files as shown in the attached screenshot, with the same offset values:

And we will press start. If everything has been correct, we will only have to restart the ESP32.



Requirements

Required:
  • TTGO VGA32 v1.x (1.0, 1.1, 1.2, 1.4)
  • Visual Studio 1.66.1 PLATFORMIO 2.4.3 Espressif32 v3.5.0 (python 3.6)
  • Arduino IDE 1.8.11 Espressif System 1.0.6
  • Arduino fabgl 1.0.8 reduced library (included in PLATFORMIO project)



PlatformIO

PLATFORMIO 2.4.3 must be installed from the Visual Studio extensions. Espressif32 v3.5.0 (python 3.6) is also required.

The TinyVectrex working directory is then selected. We must modify the platformio.ini file the upload_port option to select the COM port where we have our TTGO VGA32 board.

Then we will proceed to compile and upload to the board. No partitions are used, so we must upload the entire compiled binary. It is all set up so you don't have to install the fabgl libraries.



Arduino IDE

The whole project is compatible with the Arduino 1.8.11 framework. We only have to open the TinyVectrex.ino in the TinyVectrex directory.

We must install the spressif extensions in the additional card urls manager https://dl.espressif.com/dl/package_esp32_index.json For video, fabgl 1.0.8 must be installed.

We must deactivate the PSRAM option, and in case of exceeding 1 MB of binary, select 4 MB of partition when uploading. Although the code does not use PSRAM, if the option is active and our ESP32 does not have it, an exception will be generated and it will restart in loop mode.



Usability

Loading is allowed:
  • 32K cartridges
  • Restart
A basic low-resource OSD is available, i.e. very simple, which is displayed by pressing the F1 key.

The files must be converted to .h in hexadecimal. The online tool can be used:
http://tomeko.net/online_tools/file_to_hex.php?lang=en
Allowed to use:
  • Cursors left, right, up, down
  • Keys a, s, d, f



Options

The gbConfig.h file selects the options:
  • use_lib_vga640x480: 640x480 video mode.
  • use_lib_vga800x600: 800x600 video mode.
  • use_lib_vga1024x768: 1024x768 video mode.
  • use_lib_gfx: Disables video output. Displays nothing on the screen. Use only to measure emulation times.
  • use_lib_wifi: Enable WIFI to be able to load cartridges from a web server. As it requires a lot of RAM, it is advisable to use an http server, instead of https. The network name and password must be entered in the gbWifiConfig.h file.



WIFI support

A basic WIFI support has been added for TEST, to be able to load the cartridges (bin) from a basic HTML server, without the need of CORS, so the deployment is very fast. Apache Server, NGINX, etc... can be used.
By default, it has been left pointing to the local server, since the github pages of the project requires https (RAM consumption), and will give memory failure: 
https://rpsubc8.github.io/ESP32TinyVectrex/www/vectrex/output

To activate this mode, uncomment the line use_lib_wifi in gbConfig.h
We must configure in the file gbWIFIConfig.h the data:

  #define gb_wifi_ssd "nombreDeNuestraRedWIFIdelRooter"
  #define gb_wifi_pass "passwordDeNuestraRedWIFIdelRooter"

  //#define gb_wifi_url_base_path "http://192.168.0.36/vectrex/output"
  #define gb_wifi_url_base_path "https://rpsubc8.github.io/ESP32TinyVectrex/www/vectrex/output"

  //millisecons delay stream read
  #define gb_wifi_delay_available 0

  #define use_lib_wifi_debug

For now, the configuration is fixed in our gbWIFIConfig.h that we will have to recompile, so that it will only connect to our rooter network. Therefore we must change gb_wifi_ssd and gb_wifi_pass.
The gb_wifi_url_base_path is the path where our outlist and outdat directories are located, which contain the list of files, as well as the files themselves, so this path will be different if we use a local server.

The concept is simple, you have:

  outlist --> File with the list of bin names (length 8). Limit of 128 files
  outdat  --> The bin files.

For now, to optimize RAM consumption, we have left an 8:3 name length structure, i.e. 8 name characters and 3 extension characters. I leave some intermediate tools to prepare and make the conversion:

  build.bat --> Launches all bats, processing input to output
  
  data83.bat --> Converts all input files to 8:3 format
  
  list.bat --> Generates the outlist (list of files).
  dsk.exe --> Generates a txt file containing a list of files with name length 8.
  lowercart.bat --> Convert BIN to .bin extensions

An example outlist, for example from cart.txt, containing:

 ArmorAttBedlam  Berzerk BlitzActCleanBosCleanSweCosmicChDarkToweDEADLINEdemo2019

Whenever a file is added, we must regenerate the list with the list.bat or by calling the whole build.bat process.

Inside is the list of files with a maximum length of 8 characters, which is what will be displayed in the cartridge selection menu in the ESP32. These files, for now, are intended for a maximum of 128 entries, which is equivalent to 1024 bytes (128 x 8).
Each time a request is made to a type, the .TXT file with the list (1024 bytes, 128 names) is loaded. And when it is selected, the request is made to the file in the outdat.
When a file is selected, it will be loaded into outdat with its path. The files must have the extension in lower case.

If you are using an external WEB server, it is possible that policies may prevent you from making consecutive requests, so it is advisable not to make requests too close together.

To debug the WIFI, uncomment use_lib_wifi_debug in the gbWifiConfig.h file.



Test Applications

The MineStorm game is included:

  • rainy (demoscene)
  • OnslaughtElect (demoscene)
  • demo 2019 party (demoscene)
  • deadline 2019 (demoscene)
  • raiding party (demoscene)
  • trex