readmeSpanish.md

Tiny Galaksija ESP32

Port del emulador Galaksija a la placa TTGO VGA32 v1.x (1.0, 1.1, 1.2, 1.4) con ESP32.
Basado en el emulador x86 de Miodrag Jevremovic, Tomaž Šolc y Peter Bakota.

He realizado varias modificaciones:

• Portado de x86 PC a ESP32
• No se usa PSRAM, funcionando en ESP32 de 520 KB de RAM (TTGO VGA32 v1.x)
• Uso de un sólo core
• OSD de bajos recursos
• Creado proyecto compatible con Arduino IDE y Platform IO
• Proyecto compatible con Web Editor y ArduinoDroid (6.3.1) con tool makearduinodroidwin.bat y makearduinodroidlinux.sh
• Soporte para modo 8 y 64 colores (versión reducida de Ricardo Massaro).
• VGA 360x200, 320x200 y 320x240
• Selección de modo de video de inicio en compilación.
• Selección de modo de video en el arranque (500 ms) pulsando una tecla.
• Cambio del modo de video en caliente, en cualquier momento y sin necesidad de reiniciar.
• Filtro color crt b&w, verde o naranja
• Reducción de emulación de 64KB de RAM a sólo 8 KB. Sólo se emulan los 6 KB de RAM de Galaksija.
• Mapeo de las ROMs en Flash, en lugar de RAM
• Varias optimizaciones en volcado de video y emulación CPU.
• Reducción de código de emulación Z80 a sólo 2 archivos (Z80Z80.h y Z80Z80.cpp).
• Reducción y compactación del proyecto para poder ser llevado a plataformas más limitadas que el ESP32.
• Estadísticas de CPU y Video en OSD.
• Estadísticas de RAM libre desde OSD.
• Teclado remoto UART.

Modos de video

Existen 16 posibles modos de video, que en realidad se dividen en 3 básicos, pero con posibilidad ambos de 3 bpp (8 colores) o 6 bpp (64 colores):

• 360x200
• 320x200
• 320x240

Dado que el Galaksija tenía una resolución de 256x208, lo ideal es usar 320x240.
Los modos de video se pueden seleccionar durante el arranque (500 ms) o reinicio, pudiendo especificar otro tiempo en el gbConfig.h en la sección use_lib_boot_time_select_vga, con sólo pulsar la tecla del mismo, desde el '0' al 'F'.
El modo de video de inicio también se puede fijar en la compilación, pero lo más cómodo es cambiarlo en caliente desde el OSD en cualquier instante.
Así mismo, existen para cada modo de video, la posibilidad de poder usar la función del ajuste del pll de Espressif, o bien una custom, que evita que se quede colgado el ESP32. Dicho modo especial de video tiene el añadido del apll.
También se permiten diferentes ajustes de video, con modos de fabgl o bitluni.

Existe una opción de filtros CRT, al estilo clásico:

• Blanco y negro
• Fósforo verde
• Naranja

El color variará en función de que tengamos el modo de video:

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

Se recomienda el modo de 64 colores, y nos daremos cuenta por el efecto de nieve en TV en tonalidad azul (3 bpp) o escala de grises (6 bpp).

Versión precompilada

En la carpeta precompile se encuentra una versión ya compilada (VGA 360x200) para poder ser grabada con el flash download tool 3.9.2. con los juegos de demostración en FLASH.

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

Debemos de elegir el tipo ESP32:

Posteriormente, seleccionaremos los archivos tal y como la captura adjunta, con los mismos valores de offset:

Y le daremos a start. Si todo ha sido correcto, sólo tendremos que reiniciar el ESP32.

Requerimientos

Se requiere:

• 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

El ArduinoDroid nos permitirá compilar y subir al ESP32 el proyecto de Galaksija desde un dispositivo Android de 64 bits, es decir, un móvil, una tablet o un android box, siempre y cuando, nuestro dispositivo esté soportado.

Si estamos en windows, se debe ejecutar, sólo una vez, el script makearduinodroidwin.bat, que nos deja toda la estructura de datos del directorio dataFlash, así como el resto de archivos, en el directorio desde el que se lanza el script.
Si estamos en un Android con termux o en Linux, debemos ejecutar el makearduinodroidlinux.sh.

Básicamente, nos quedan todos los archivos en un único nivel, sin subdirectorios posibles.
El directorio 'notdelete' es interno del script y se utiliza para copiar el gbCompileOpt.h.
Al finalizar, el propio script, podemos abrir el galaksija.ino, y recompilar desde el ArduinoDroid, sin nada especial. El script posee una pausa al inicio, por si queremos parar el script desde fuera, así como una parada al final, para ver los resultados del proceso.

Si nos damos cuenta, todo gira en torno al pragma gb_use_lib_compile_arduinodroid de la cabecera gbCompileOpt.h, que en modo normal se utiliza con paths de múltiples niveles y en ArduinoDroid con el script, en un sólo nivel.
Este script busca los archivos subiendo niveles hasta llegar al TinyGalaksijattgovga32/galaksija, así que se requiere que se baje el proyecto completo con toda la estructura:

 TinyGalaksijattgovga32
  galaksija
   dataFlash
  include
  lib
  test
 tools
  arduinodroid
   galaksija
  data2h

El ArduinoDroid (6.3.1) con soporte para ESP32 sólo funciona con procesadores de 64 bits.

Arduino Web Editor

Se debe ejecutar, sólo una vez, el script makearduinodroidwin.bat. Una vez finalizado, se sube a la nube como un proyecto cualquiera, ya sea comprimido en zip o por archivos.

Básicamente es lo mismo, dado que se intenta dejar todo en un único nivel de directorio. Se recomienda importar el proyecto comprimido en zip con una compresión normal, nada de máxima, dado que algunos editores web del cloud no soportan el zip al 100%.

PlatformIO

Se debe instalar el PLATFORMIO 2.2.1 desde las extensiones del Visual Studio. Se requiere también Espressif32 v3.3.2.

Luego se seleccionará el directorio de trabajo TinyGalaksijattgovga32. Debemos modificar el fichero platformio.ini la opción upload_port para seleccionar el puerto COM donde tenemos nuestra placa TTGO VGA32.

Luego procederemos a compilar y subir a la placa. No se usa particiones, así que debemos subir todo el binario compilado. Está todo preparado para no tener que instalar las librerias de bitluni ni fabgl.

Arduino IDE

Todo el proyecto es compatible con la estructura de Arduino 1.8.11. Tan sólo tenemos que abrir el galaksija.ino del directorio galaksija.

Debemos instalar las extensiones de Espressif en el gestor de urls adicionales de tarjetas https://dl.espressif.com/dl/package_esp32_index.json
Ya está preparado el proyecto, de forma que no se necesita ninguna librería de bitluni ni fabgl. Debemos desactivar la opción de PSRAM, y en caso de superar 1 MB de binario, seleccionar 4 MB de partición a la hora de subir. Aunque el código no use PSRAM, si la opción está activa y nuestro ESP32 no dispone de ella, se generará una excepción y reinicio del mismo en modo bucle.

Usabilidad

Se permiten las siguientes acciones desde el menú (tecla F1):

• Cargar o seleccionar una cinta (GTP)
• Cargar o seleccionar un snapshot (GAL)
• Selecionar idioma Español o inglés
• Seleccionar 16 modos de video
• Cambiar el color verde, naranja o blanco y negro, como los monitores retro
• Mostrar estadísticas de CPU y video
• Activar la salida de depuración por usb (serie)
• Ayuda
• Resetear el ESP32 o el emulador
• Interceptar la rutina de cinta cuando escribimos el comando OLD desde BASIC, y hemos seleccionado un GTP, en lugar de cargarlo y ejecutarlo.
• Cambiar los milisegundos de polling para video, teclado
• Ver la RAM libre

Se dispone de un OSD básico de bajos recursos, es decir, muy simple, que se visualiza pulsando la tecla F1.

Algunos menús y submenús son de ejecución inmediata, es decir, al aceptar con la tecla ENTER, ya se cierra el OSD y se aplica la acción. Otros menús, por el contrario, vuelven al menu anterior.
Siempre se puede salir del OSD con la tecla ESC.
Los cursores Arriba y Abajo permiten navegar por cada acción. Si se mantienen durante un par de milisegundos pulsadas, permiten acción rápida.

GTP (cintas)

Siempre que carguemos un GTP (cinta) desde el OSD, nos permitirá elegir entre:

• Load: Nos permite cargarlo.
• Select: Sólo lo selecciona, pudiendo desde BASIC leerlo con el comando OLD.

Cuando se lanza el comando OLD, existe un pequeño truco no 100% correcto, pero eficiente en consumo de host, para interceptar la rutina de ROM, y proceder a cargarlo. Dicha intercepción se puede deshabilitar también desde el OSD.
Si hemos elegido la carga, en lugar de la selección, cuando ya hemos elegido una cinta desde el OSD, nos aparecerá si queremos usar el WARM START BASIC.

Posteriormente, nos dirá si queremos que haga un RUN automático desde BASIC o no.

En caso de que aceptemos, desde BASIC, se procederá a escribir RUN de manera automática.
Es recomendable tener una ejecución limpia, siempre que carguemos juegos, es decir, reiniciar el emulador, para dejar todo lo mejor posible.
Cuando ocurren errores de memoria, se deja traza por el puerto serie, y al cabo de un par de ellos, se autoreinicia el emulador (no el ESP32), dejándonos una traza.

Snapshot GAL

Siempre que carguemos un GAL, nos dejará la opción de ejecutar RUN o no desde BASIC.
Los GAL deben ser de tamaño 8268 bytes.

Estadísticas

Hay una opción es OSD Options que nos permite ver lo que se llama el OSD, que son las estadísticas de consumos de CPU y video, por cada segundo (1000 milisegundos).

En una emulación de 50 fps (cuadros por segundo) existen 2 secciones:

• Tiempo de CPU (20 milisegundos)
• Tiempo de volcado de video (20 milisegundos)

Son 20 milisegundos, porque son 50 fps (1000 / 50 = 20). El tiempo de volcado de video, no tiene porque ser 50 fps reales, dado que lo importante, es el de CPU, que es el que va a marcar los 50 fps reales. Podemos pues, conseguir 50 fps de CPU, pero tener 24 fps en volcado de video, y sería totalmente funcional. No obstante, en este emulador, se consigue superar los 50 fps reales.
Se han puesto las estadísticas a la derecha y en vertical, para no interferir en ningún momento en la pantalla emulada.

Campo	Descripción
C	Microsegundos del ESP32 que tarda en procesar el frame actual de 20 milis
M	Microsegundos del ESP32 que tarda en procesar el frame más rápido de 20 milis en 1000 milis
MX	Microsegundos del ESP32 que tarda en procesar el frame más lento de 20 milis en 1000 milis
I	Microsegundos libres del ESP32 en un frame de 20 milis, contando el volcado de video
FPS	FPS reales que procesa el emulador en 1000 milis
FND	FPS que nos daría sin límite en 20 milis por frame, poniendo en menú CPU a 0 ms (rápido)
V	Microsegundos del ESP32 que tarda en volcar un frame de 20 milis
F	FPS reales a los que estamos volcando el video realmente

Test teclado PS/2

Para testear un teclado PS/2:

https://github.com/rpsubc8/testkeyboardPS2

Teclado PS/2

Se requiere un teclado 100% PS/2, y que no requiera comando de inicialización.
El Galaksija tiene un buffer para teclas pulsadas de 54 elementos.
Están emuladas las siguiente teclas:

Teclas emulador	Teclas (teclado PS/2 real)	Buffer Galaksija
0 .. 9	0 .. 9	32 .. 41
A .. Z	A .. Z	1 .. 26
Arriba	Arriba	27
Abajo	Abajo	28
Izquierda	Izquierda	29
Derecha	Derecha	30
Barra espaciadora	Barra espaciadora	31
Borrar	Borrar o Suprimir	29
;	;	42
"	'	43
,	,	44
=	=	45
.	.	46
/	/	47
ENTER	ENTER o RETURN	48
CONTROL	CONTROL	50
SCROLL	SCROLL	52
SHIFT	SHIFT izquierdo o derecho	53

La entrada 51 de Galaksija, que sería el DELETE no está mapeada en el emulador.
La tecla F1 del teclado PS/2 saca el menú OSD del emulador.

Teclado remoto

Se permite usar el teclado desde la consola de Visual Studio o desde un terminal putty.
El teclado remoto no tiene la misma respuesta que un teclado real, dado que se envían comandos de teclas, y no un mapa de caracteres pulsados.
En la consola del Arduino IDE no se puede usar, porque siempre se espera el envio del ENTER para aceptar comandos.
Tenemos que activar en el gbConfig.h el pragma use_lib_log_keyboard_uart, compilar y ejecutar.
No estan todas las teclas mapeadas, y es algo básico, útil para pruebas, sin falta de usar el teclado PS/2 real.

Teclas PC	Función
F2 o TAB	Muestra el menú OSD
ESC	Salir del menú
Arriba	Arriba
Abajo	Abajo
Izquierda	Izquierda
Derecha	Derecha
Borrar o DEL	Borrar
ENTER	ENTER
0 .. 9	0 .. 9
A .. Z	A .. Z
.	.
-	SHIFT izquierdo

Si pulsamos el '-' al mismo tiempo que otra tecla, por ejemplo, la 'A' es el equivalente a pulsar el (SHIFT + A) en el emulador.

GPIO

El archivo hardware.h contiene lo necesario para el GPIO de:

• Teclado:
  • KEYBOARD_DATA - (32)
  • KEYBOARD_CLK - (33)
• VGA sincronismos:
  • HSYNC_PIN - (23)
  • VSYNC_PIN - (15)
• VGA rojo
  • PIN_RED_LOW - (21)
  • PIN_RED_HIGH -(22)
• VGA verde
  • PIN_GREEN_LOW - (18)
  • PIN_GREEN_HIGH - (19)
• VGA azul
  • PIN_BLUE_LOW - (4)
  • PIN_BLUE_HIGH - (5)

Está pensado para la placa TTGO VGA v1.2, así que si tenemos otro tipo de placa, aquí es donde debemos definir los cambios.
Cuando usamos 6 bpp, estamos usando todos los GPIO de VGA, pero cuando usamos el 3 bpp, sólo usamos:

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

Opciones

El archivo gbConfig.h se seleccionan las opciones: Podemos elegir el tiempo (milisegundos) para poder seleccionar el modo de video durante el arranque:

• use_lib_boot_time_select_vga: Cuanto más alto sea el valor, más tiempo tardará en arrancar. Si durante este tiempo, pulsamos las teclas del 0 al 9 o las letras de la A a la F, estaremos eligiendo un modo de video. Es válido también para el reinicio.

Tenemos la posibilidad de elegir uno de los 16 posibles modos de video por defecto, es decir, por compilación, y que sea el que se inicia por defecto al arrancar la placa (360x200):

• use_lib_boot_vga_360x200x70hz_bitluni_3bpp: 360x200 8 colores
• use_lib_boot_vga_360x200x70hz_bitluni_apll_3bpp: 360x200 8 colores corección apll, para ESP32 que se quedan colgados.
• use_lib_boot_vga_320x200x70hz_bitluni_3bpp: 320x200 8 colores
• use_lib_boot_vga_320x200x70hz_fabgl_3bpp: 320x200 8 colores con parámetros de fabgl
• use_lib_boot_vga_320x200x70hz_bitluni_apll_3bpp: 320x200 8 colores corección apll, para ESP32 que se quedan colgados.
• use_lib_boot_vga_320x240x60hz_bitluni_3bpp: 320x240 8 colores
• use_lib_boot_vga_320x240x60hz_fabgl_3bpp: 320x240 8 colores con parámetros de fabgl
• use_lib_boot_vga_320x240x60hz_bitluni_apll_3bpp: 320x240 8 colores corección apll, para ESP32 que se quedan colgados.
• use_lib_boot_vga_360x200x70hz_bitluni_6bpp: 360x200 64 colores
• use_lib_boot_vga_360x200x70hz_bitluni_apll_6bpp: 360x200 64 colores corección apll, para ESP32 que se quedan colgados.
• use_lib_boot_vga_320x200x70hz_bitluni_6bpp: 320x200 64 colores
• use_lib_boot_vga_320x200x70hz_fabgl_6bpp: 320x200 64 colores con parámetros de fabgl
• use_lib_boot_vga_320x200x70hz_bitluni_apll_6bpp: 320x200 64 colores corección apll, para ESP32 que se quedan colgados.
• use_lib_boot_vga_320x240x60hz_bitluni_6bpp: 320x240 64 colores
• use_lib_boot_vga_320x240x60hz_fabgl_6bpp: 320x240 64 colores con parámetros de fabgl
• use_lib_boot_vga_320x240x60hz_bitluni_apll_6bpp: 320x240 64 colores corección apll, para ESP32 que se quedan colgados.

Como es de esperar, no se puede seleccionar todos los modos al mismo tiempo, así que se debe descomentar el que queremos, y comentar el resto.
Existen más opciones.

• use_lib_log_serial: Se envian logs por puerto serie usb
• use_lib_fix_double_precision: No usar FPU para el cálculo del PLL.
• use_lib_debug_i2s: Información detallada de la inicialización del modo de video.
• use_lib_keyboard_uart: Permite usar un teclado remoto via UART por putty o la consola de VStudio.
• use_lib_log_keyboard_uart: La traza del teclado remoto.

Tool data2h

He creado una herramienta muy básica (win32), para convertir los archivos .GTP y .GAL en .h en modo lista para ser procesados por el emulador.
Se recomienda tener nombres de ficheros reducidos. Además la tool realiza un cortado a 32 caracteres para mostrar en el OSD.

Tan sólo tenemos que dejar los archivos .GAL y .GTP en la carpeta input/GAL e input/GTP ejecutar el archivo data2h.exe, de forma que se generará una salida en el directorio output/dataFlash. Tool data2h

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

Posteriormente debemos copiar el directorio dataFlash en el proyecto TinyGalaksijattgovga32\galaksija sobreescribiendo la carpeta dataFlash previa. Se recomienda limpiar el proyecto y volver a compilar.
Esta herramienta es muy simple, y no controla los errores, por lo que se recomienda dejarle los archivos con nombres muy simples y lo más sencillo posible.
Dado que está disponible el código fuente, se puede compilar para Linux o para Android bajo Termux. En Termux tenemos que instalar el paquete gcc o el clang y compilar:

 gcc -s data2h.cpp -odata2h.a

Debe hacerse desde el directorio home de datos del dispositivo Android, de manera que si lo hacemos en cualquier otro directorio, nunca se podra ejecutar el data2h.a creado, salvo que el dispositivo este rooteado.

El proyecto en PLATFORM.IO está preparado para 1 MB de Flash. Si necesitamos los 4MB de flash, tendremos que modificar la entrada del archivo platformio.ini

board_build.partitions = huge_app.csv

En el Arduino IDE, debemos elegir la opción Partition Scheme (Huge APP).

DIY circuito

Si no queremos usar una placa TTGO VGA32 v1.x, podemos construirla siguiendo el esquema de fabgl:

Versión minimalista

Se puede realizar una versión minimalista, sin resistencias, condensadores, y demás, sólo con conectores y cables directos, al menos para el caso de 8 colores y un sólo teclado:

Sólo sirve para teclados PS/2 que pueden alimentarse a 3.3v, que aunque son unos cuantos, suele excluir sobre todo a los muy antigüos, así como a los modernos con lucecitas. La salida de audio (no se requiere en el emulador), está pensada para auriculares, y será bastante bajo. Asegurarse de que si le conectamos un amplificador de audio de dudoso estado o algo similar, al no llevar resistencias, podemos llevar un susto.
La salida de video VGA es para 8 colores (3 pins). Lo mismo, si le conectamos un monitor de dudoso estado, aunque el VGA es para salida, podriamos llevar un susto.

Aunque es muy simple, se requiere unos conocimientos mínimos de electrónica, por lo que si no se sabe lo que se está haciendo, mejor no hacer nada. Me desentiendo de lo que pueda ocurrir.