Skip to content

Latest commit

 

History

History
190 lines (157 loc) · 11 KB

readmeEnglish.md

File metadata and controls

190 lines (157 loc) · 11 KB

Tiny Fairchild Channel F

Port of the FreeChaF retroarch emulator (FairChild Channel F) to the TTGO VGA32 v1.0, v1.1, v1.2 and v1.4 board with ESP32.

I have made several modifications:
  • Ported from retroarch to ESP32
  • No PSRAM used, running on ESP32 520 KB RAM (TTGO VGA32 v1.x)
  • Use of a single core
  • Low resource OSD
  • Created project compatible with Arduino IDE and Platform IO
  • Web Editor and ArduinoDroid (6.3.1) compatible project with tool makeandroid.bat
  • Any digital pin can be used for audio (SPEAKER_PIN in hardware.h).
  • Any digital pin can be used for video (hardware.h).
  • X and Y screen adjustment
  • Emulation video speed menu, keyboard
  • Support for 64-color mode and 8-color mode.
  • VGA 200x150
  • VGA 320x200
  • The complete bitluni library is not required. I have reduced to the minimum, saving RAM and FLASH, based on Ricardo Massaro's library.
  • Support for reading cartridges via WIFI
  • Precompiled version (flash download 3.9.2) 200x150



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 with 200x150 resolution with the demo games in FLASH.

https://github.com/rpsubc8/ESP32TinyFairChild/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) o Single core ESP32
  • Visual Studio 1.48.1 PLATFORMIO 2.2.0
  • Arduino IDE 1.8.11
  • ArduinoDroid (6.3.1)

The attached image is of my TTGO VGA32 v1.2 board without psram or SD module.



ArduinoDroid

You must run, just once, the script makeandroid.bat, which leaves the entire data structure of the dataFlash directory in the root directory, as well as replacing the main files with .h calls without using the dataFlash data directory.
At the end, the script itself ends up deleting the dataFlash directory.
The script uses fart.exe (find and replace text).
Once, it has been successfully executed, it can be used with the ArduinoDroid.



Arduino Web Editor

The makeandroid.bat script must be run once only. Once finished, it is uploaded to the cloud as any other project, either compressed in zip or by files.



PlatformIO

PLATFORMIO 2.2.0 must be installed from the Visual Studio extensions.

Then the working directory TinyFairChildttgovga32 will be selected. We must modify the platformio.ini file 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's all set up so we don't have to install any libraries.



Arduino IDE

The whole project is compatible with the Arduino 1.8.11 framework. We just need to open the fairChild.ino in the fairChild directory.

For normal mode, the project is already prepared, so no library is needed. We must disable the PSRAM option, and in case of exceeding 1 MB of binary, select 4 MB partition at upload time. 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.



Keyboard

The keyboard is divided into 3 parts
  • System Control: 0,1,2,3
  • Control A: Left, Right, Up, Down, o,p
  • Control B: a,d,w,s c,v



Options

The gbConfig.h file options are selected:
  • use_lib_200x150: Video mode 200x150 is used. You have to choose only one video mode, either 200x150 or 320x200.
  • use_lib_320x200: 320x200 video mode is used.
  • use_lib_vga8colors: Forces to use RGB 8-color mode (3 pins). Outputs 8 colors, as opposed to 64 in normal mode (6 pins RRGGBB)
  • FIX_PERIBOARD_NOT_INITING: In those keyboards that need ECO to initialize. Solution by David Crespo Tascón.
  • use_lib_log_serial: It allows to leave traces through the usb serial port. If enabled, it consumes a little more RAM, CPU and FLASH..
  • gb_ms_keyboard: The number of polling milliseconds for the keyboard must be specified.
  • gb_ms_vga: The number of polling milliseconds for the VGA frame must be specified.
  • gb_add_offset_x: Shift to the right of the frame in multiples of 4 pixels.
  • gb_add_offset_y: Downward displacement of the frame in pixels.
  • use_lib_delay_tick_cpu_auto: If 1, the emulation speed is auto-set to 14914 ticks of 20 millis. If 0, it waits for the millis specified in use_lib_delay_tick_cpu_micros.
  • use_lib_delay_tick_cpu_micros: The number of milliseconds to wait for the CPU while use_lib_delay_tick_cpu_auto is 0 must be specified.
  • 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.



Tool chf2h

I have created a very basic tool, to convert .chf files to .h in ready mode to be processed by the emulator. We just have to leave the .chf files in the input/cart folder and run the chf2h.exe file, so that an output will be generated in the output/dataFlash directory. For testing purposes, a file has been left in the input/cart directory, which it is recommended to delete in case of making a new custom list. It is also recommended to delete the files in the fairChild/dataFlash/gbcart.h and fairChild/dataFlash/cart directory to have a clean project.


Tool chf2h 

 input/
  cart/
   ColorOrgan.chf
 output/
  dataFlash/
   cart/
Subsequently we must copy the dataFlash directory into the TinyFairChildttgovga32\fairChild project overwriting the previous dataFlash folder. It is recommended that you clean up the project and recompile.
This tool is very simple, and does not check for errors, so it is recommended to leave the files with very simple names and as simple as possible. The project in PLATFORM.IO is prepared for 1MB of Flash. If we need the 4MB of flash, we will have to modify the entry in the platformio.ini file. 
board_build.partitions = huge_app.csv
In the Arduino IDE, we must choose the option Partition Scheme (Huge APP).



WIFI support

A basic WIFI support has been added for TEST, to be able to load the cartridges (chf) 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 is left pointing to the project's github pages server. RAM consumption with https is higher than with http: 
https://rpsubc8.github.io/ESP32TinyFairChild/www/fairchild/output

To activate this mode, you must 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/fairchild/output"
  #define gb_wifi_url_base_path "https://rpsubc8.github.io/ESP32TinyFairChild/www/fairchild/output"

  //millisecons delay stream read
  #define gb_wifi_delay_available 0

  #define use_lib_wifi_debug

For the time being, the configuration is set in our gbWIFIConfig.h which 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 names (length 8) of chf. Limit of 128 files
  outdat  --> The chf 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 CHF to .chf extensions

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

 AlienInvBaseballBoogie2 Bowling CheckersColorOrgF8NationFninja  Football

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

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 in 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.