readmeEnglish.md

Tiny Galaksija ESP32

Galaksija emulator port to TTGO VGA32 v1.x (1.0, 1.1, 1.2, 1.4) board with ESP32.
Based on the x86 emulator by Miodrag Jevremovic, Tomaž Šolc and Peter Bakota.

I have made several modifications:

• Ported from x86 PC to ESP32
• No PSRAM used, running on ESP32 with 520 KB RAM (TTGO VGA32 v1.x)
• Use of a single core
• Low resource OSD
• Created project compatible with Arduino IDE and Platform IO
• Project compatible with Web Editor and ArduinoDroid (6.3.1) with tool makearduinodroidwin.bat and makearduinodroidlinux.sh
• Support for mode 8 and 64 colors (reduced version by Ricardo Massaro).
• VGA 360x200, 320x200 and 320x240
• Startup video mode selection in build.
• Video mode selection at boot (500 ms) by pressing a key.
• Switching video mode on the fly, at any time and without rebooting.
• Crt b&w, green or orange color filter
• Reduced emulation from 64KB of RAM to just 8KB. Only Galaksija's 6 KB of RAM is emulated.
• Mapping ROMs to Flash, instead of RAM
• Various optimizations in video dump and CPU emulation.
• Reduced Z80 emulation code to only 2 files (Z80Z80.h and Z80Z80.cpp).
• Reduction and compaction of the project to be able to be taken to more limited platforms than the ESP32.
• CPU and Video Statistics in OSD.
• Free RAM statistics from OSD.
• UART remote keyboard.

Video modes

There are 16 possible video modes, which are actually divided into 3 basic ones, but both with the possibility of 3 bpp (8 colors) or 6 bpp (64 colors):

• 360x200
• 320x200
• 320x240

Since the Galaksija had a resolution of 256x208, it is ideal to use 320x240.
Video modes can be selected during boot (500 ms) or reboot, and another time can be specified in gbConfig.h in the use_lib_boot_time_select_vga section , by simply pressing the same key, from '0' to 'F'.
The startup video mode can also be set in the build, but it is most convenient to hot-switch it from the OSD at any time.
Likewise, for each video mode, there is the possibility of using the Espressif pll adjustment function, or a custom one, which prevents the ESP32 from hanging. This special video mode has the addition of the apll.
Different video settings are also allowed, with fabgl or bitluni modes.

There is an option of CRT filters, in the classic style:

• black and white
• green match
• Orange

The color will vary depending on whether we have video mode:

• 3 bpp (8 colors)
• 6 bpp (64 colors)

The 64-color mode is recommended, and we will notice the snow effect on TV in blue tone (3 bpp) or gray scale (6 bpp).

Precompiled version

In the precompile folder there is an already compiled version (VGA 360x200) to be able to be recorded with the flash download tool 3.9.2. with demo games in FLASH.

https://github.com/rpsubc8/ESP32TinyGalaksija/tree/main/esp32/precompile

We must choose the ESP32 type:

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

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

Requirements

Is required:

• TTGO VGA32 v1.x (1.0, 1.1, 1.2, 1.4)
• Visual Studio 1.48.1 PLATFORMIO 2.2.1 Espressif32 v3.3.2
• Arduino IDE 1.8.11 Espressif System 1.0.6
• ArduinoDroid (6.3.1)

ArduinoDroid

The ArduinoDroid will allow us to compile and upload the Galaksija project to the ESP32 from a 64-bit Android device, that is, a mobile phone, a tablet or an Android box, as long as our device is supported.

If we are on Windows, the makearduinodroidwin.bat script must be executed just once, which leaves us with the entire data structure of the dataFlash directory, as well as the rest of the files, in the directory from which the script is launched.
If we are on Android with termux or Linux, we must run makearduinodroidlinux.sh.

Basically, we are left with all the files on a single level, without possible subdirectories.
The 'notdelete' directory is internal to the script and is used to copy the gbCompileOpt.h.
At the end of the script itself, we can open the galaksija.ino, and recompile from the ArduinoDroid, without anything special. The script has a pause at the beginning, in case we want to stop the script from outside, as well as a stop at the end, to see the results of the process.

If we notice, everything revolves around the pragma gb_use_lib_compile_arduinodroid of the gbCompileOpt.h header, which in normal mode is used with multi-level paths and in ArduinoDroid with the script, in a single level.
This script searches for the files going up levels until it reaches TinyGalaksijattgovga32/galaksija, so it is required to download the complete project with the entire structure:

 TinyGalaksijattgovga32
  galaksija
   dataFlash
  include
  lib
  test
 tools
  arduinodroid
   galaksija
  data2h

The ArduinoDroid (6.3.1) with ESP32 support only works with 64-bit processors.

Arduino Web Editor

The makearduinodroidwin.bat script must be executed only once. Once finished, it is uploaded to the cloud as any project, whether compressed in zip or files.

It's basically the same thing, since you're trying to keep everything at a single directory level. It is recommended to import the project compressed in zip with normal compression, not maximum, since some cloud web editors do not support zip 100%.

PlatformIO

PLATFORMIO 2.2.1 must be installed from the Visual Studio extensions. Espressif32 v3.3.2 is also required.

The working directory TinyGalaksijattgovga32 will then be selected. We must modify the platformio.ini file and 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. Everything is ready to avoid having to install the bitluni or fabgl libraries.

Arduino IDE

The entire project is compatible with Arduino 1.8.11 framework. We just have to open galaksija.ino from the galaksija directory.

We must install the Espressif extensions in the additional card url manager https://dl.espressif.com/dl/package_esp32_index.json
The project is already prepared, so no bitluni or fabgl library is needed. We must disable the PSRAM option, and if the binary exceeds 1 MB, select 4 MB 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

The following actions are allowed from the menu (F1 key):

• Load or select a tape (GTP)
• Load or select a snapshot (GAL)
• Select language Spanish or English
• Select 16 video modes
• Change the color green, orange or black and white, like retro monitors
• Show CPU and video statistics
• Enable USB debugging output (serial)
• Help
• Reset the ESP32 or the emulator
• Intercept the tape routine when we type the OLD command from BASIC, and we have selected a GTP, instead of loading and executing it.
• Change polling milliseconds for video, keyboard
• View free RAM

There is a basic low-resource OSD, that is, very simple, which is displayed by pressing the F1 key.

Some menus and submenus are immediately executed, that is, when you accept with the ENTER key, the OSD is closed and the action is applied. Other menus, on the other hand, return to the previous menu.
You can always exit the OSD with the ESC key.
The Up and Down cursors allow you to navigate through each action. If they are held down for a couple of milliseconds, they allow quick action.

GTP (tapes)

Whenever we load a GTP (tape) from the OSD, it will allow us to choose between:

• Load: Allows us to load it.
• Select: It only selects it, being able to read it from BASIC with the OLD command.

When the OLD command is issued, there is a little trick that is not 100% correct, but efficient in host consumption, to intercept the ROM routine, and proceed to load it. This interception can also be disabled from the OSD. If we have chosen loading, instead of selection, when we have already chosen a tape from the OSD, it will appear if we want to use WARM START BASIC.

Later, it will tell us if we want it to do an automatic RUN from BASIC or not.

If we accept, from BASIC, RUN will be written automatically.
It is advisable to have a clean execution, whenever we load games, that is, restart the emulator, to leave everything as good as possible.
When memory errors occur, a trace is left through the serial port, and after a couple of them, the emulator (not the ESP32) restarts itself, leaving us a trace.

Snapshot GAL

Whenever we load a GAL, it will give us the option of executing RUN or not from BASIC.
GALs must be 8268 bytes in size.

Statistics

There is an option is OSD Options that allows us to see what is called the OSD, which are the statistics of CPU and video consumption, for each second (1000 milliseconds).

In a 50 fps (frames per second) emulation there are 2 sections:

• CPU time (20 milliseconds)
• Video dump time (20 milliseconds)

It's 20 milliseconds, because it's 50 fps (1000 / 50 = 20). The video dump time does not have to be 50 real fps, since what is important is the CPU time, which is what will set the real 50 fps. We can then get 50 fps from the CPU, but have 24 fps in the video dump, and it would be totally functional. However, in this emulator, it is possible to exceed 50 real fps.
The statistics have been placed on the right and vertically, so as not to interfere at any time on the emulated screen.

Field	Description
C	ESP32 microseconds that it takes to process the current 20 milli frame
M	Microseconds of the ESP32 that it takes to process the fastest frame of 20 millis in 1000 millis
MX	Microseconds of the ESP32 that it takes to process the slowest frame of 20 millis in 1000 millis
I	ESP32 free microseconds in a 20 milli frame, counting the video dump
FPS	Real FPS processed by the emulator at 1000 millis
FND	FPS that would give us no limit at 20 millis per frame, setting the CPU menu to 0 ms (fast)
V	Microseconds of the ESP32 that it takes to dump a frame of 20 millis
F	Real FPS we are actually dumping the video at

Test keyboard PS/2

To test a PS/2 keyboard:

https://github.com/rpsubc8/testkeyboardPS2

PS/2 keyboard

A 100% PS/2 keyboard is required, and does not require an initialization command.
The Galaksija has a 54-element keystroke buffer.
The following keys are emulated:

Emulator keys	Keys (real PS/2 keyboard)	Buffer Galaksija
0 .. 9	0 .. 9	32 .. 41
A .. Z	A .. Z	1 .. 26
Above	Above	27
Below	Below	28
Left	Left	29
Right	Right	30
Space bar	Space bar	31
Delete	Delete	29
;	;	42
"	'	43
,	,	44
=	=	45
.	.	46
/	/	47
ENTER	ENTER or RETURN	48
CONTROL	CONTROL	50
SCROLL	SCROLL	52
SHIFT	SHIFT left or right	53

Galaksija entry 51, which would be DELETE, is not mapped in the emulator.
The F1 key on the PS/2 keyboard brings up the emulator's OSD menu.

Remote keyboard

Using the keyboard is allowed from the Visual Studio console or from a putty terminal.
The remote keyboard does not have the same response as a real keyboard, since key commands are sent, and not a map of pressed characters.
It cannot be used in the Arduino IDE console, because it always waits for ENTER to be sent to accept commands.
We have to activate the use_lib_log_keyboard_uart pragma in gbConfig.h, compile and run.
Not all the keys are mapped, and it is something basic, useful for testing, without failing to use the real PS/2 keyboard.

PC keys	Function
F2 or TAB	Shows the OSD menu
ESC	Exit menu
Above	Above
Below	Below
Left	Left
Right	Right
Delete or DEL	Delete
ENTER	ENTER
0 .. 9	0 .. 9
A .. Z	A .. Z
.	.
-	Left shift

If we press the '-' at the same time as another key, for example, the 'A' is the equivalent of pressing (SHIFT + A) in the emulator.

GPIO

The hardware.h file contains what is needed for the GPIO of:

• Keyboard:
  • KEYBOARD_DATA - (32)
  • KEYBOARD_CLK - (33)
• VGA syncs:
  • HSYNC_PIN - (23)
  • VSYNC_PIN - (15)
• VGA red
  • PIN_RED_LOW - (21)
  • PIN_RED_HIGH -(22)
• VGA green
  • PIN_GREEN_LOW - (18)
  • PIN_GREEN_HIGH - (19)
• VGA blue
  • PIN_BLUE_LOW - (4)
  • PIN_BLUE_HIGH - (5)

It is designed for the TTGO VGA v1.2 board, so if we have another type of board, this is where we must define the changes.
When we use 6 bpp, we are using all the VGA GPIOs, but when we use 3 bpp, we only use:

• PIN_RED_HIGH - (22)
• PIN_GREEN_HIGH - (19)
• PIN_BLUE_HIGH - (5)

Options

The options are selected in the gbConfig.h file: We can choose the time (milliseconds) to be able to select the video mode during boot:

• use_lib_boot_time_select_vga: The higher the value, the longer it will take to boot. If during this time, we press the keys from 0 to 9 or the letters from A to F, we will be choosing a video mode. It is also valid for reboot.

We have the possibility of choosing one of the 16 possible default video modes, that is, by compilation, and that is the one that starts by default when the board starts up (360x200):

• use_lib_boot_vga_360x200x70hz_bitluni_3bpp: 360x200 8 colors.
• use_lib_boot_vga_360x200x70hz_bitluni_apll_3bpp: 360x200 8 colors apll correction, for ESP32 that hang.
• use_lib_boot_vga_320x200x70hz_bitluni_3bpp: 320x200 8 colors.
• use_lib_boot_vga_320x200x70hz_fabgl_3bpp: 320x200 8 colors with fabgl parameters.
• use_lib_boot_vga_320x200x70hz_bitluni_apll_3bpp: 320x200 8 colors apll correction, for ESP32 that hang.
• use_lib_boot_vga_320x240x60hz_bitluni_3bpp: 320x240 8 colors.
• use_lib_boot_vga_320x240x60hz_fabgl_3bpp: 320x240 8 colors with fabgl parameters.
• use_lib_boot_vga_320x240x60hz_bitluni_apll_3bpp: 320x240 8 colors apll correction, for ESP32 that hang.
• use_lib_boot_vga_360x200x70hz_bitluni_6bpp: 360x200 64 colors
• use_lib_boot_vga_360x200x70hz_bitluni_apll_6bpp: 360x200 64 colors apll correction, for ESP32 that hang.
• use_lib_boot_vga_320x200x70hz_bitluni_6bpp: 320x200 64 colors
• use_lib_boot_vga_320x200x70hz_fabgl_6bpp: 320x200 64 colors with fabgl parameters.
• use_lib_boot_vga_320x200x70hz_bitluni_apll_6bpp: 320x200 64 colors apll correction, for ESP32 that hang.
• use_lib_boot_vga_320x240x60hz_bitluni_6bpp: 320x240 64 colors
• use_lib_boot_vga_320x240x60hz_fabgl_6bpp: 320x240 64 colors with fabgl parameters.
• use_lib_boot_vga_320x240x60hz_bitluni_apll_6bpp: 320x240 64 colors apll correction, for ESP32 that hang.

As expected, you cannot select all the modes at the same time, so you must uncomment the one you want, and comment on the rest.
There are more options.

• use_lib_log_serial: Logs are sent via USB serial port.
• use_lib_fix_double_precision: Do not use FPU for PLL calculation.
• use_lib_debug_i2s: Detailed information of video mode initialization.
• use_lib_keyboard_uart: Allows you to use a remote keyboard via UART via putty or the VStudio console.
• use_lib_log_keyboard_uart: The remote keyboard trace.

Tool data2h

I have created a very basic tool (win32) to convert .GTP and .GAL files into .h in ready mode to be processed by the emulator.
It is recommended to have short file names. Additionally, the tool cuts to 32 characters to display in the OSD.

We just have to leave the .GAL and .GTP files in the input/GAL folder and input/GTP run the data2h.exe file , so that an output will be generated in the output/dataFlash directory.Tool data2h

 input/
  gal/
  gtp/
 output/
  dataFlash/
   gal/
   gtp/ 

Later we must copy the dataFlash directory to the TinyGalaksijattgovga32\galaksija project, overwriting the previous dataFlash folder. It is recommended to clean the project and compile again.
This tool is very simple, and does not control errors, so it is recommended to leave the files with very simple names and as simple as possible.
Since the source code is available, it can be compiled for Linux or for Android under Termux. In Termux we have to install the gcc or clang package and compile:

 gcc -s data2h.cpp -odata2h.a

It must be done from the home data directory of the Android device, so if we do it in any other directory, the data2h.a created will never be able to be executed, unless the device is rooted.

The project in PLATFORM.IO is prepared for 1 MB 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 Partition Scheme (Huge APP) option.

DIY circuit

If we don't want to use a TTGO VGA32 v1.x board, we can build it following fabgl's schematic:

Minimalist version

A minimalist version can be made, without resistors, capacitors, and so on, only with direct connectors and cables, at least in the case of 8 colors and a single keyboard:

It only works for PS/2 keyboards that can be powered at 3.3v, which although there are a few, tends to exclude especially the very old ones, as well as the modern ones with lights. The audio output (not required in the emulator), is intended for headphones, and will be quite low. Make sure that if we connect an audio amplifier of dubious condition or something similar, as it does not have resistors, we could be scared.
The VGA video output is for 8 colors (3 pins). The same thing, if we connect a monitor of questionable condition, although the VGA is for output, we could be scared.

Although it is very simple, it requires minimal knowledge of electronics, so if you don't know what you are doing, it is better not to do anything. I ignore what may happen.