readmeSpanish.md

Tiny ESP32 AMSTRAD CPC

Port del emulador de PC de Tom Walker (AMSTRAD CPC) a la placa TTGO VGA32 v1.x (1.0, 1.1, 1.2, 1.4) con ESP32.

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.2)
• Uso de un sólo core
• OSD de bajos recursos
• Creado proyecto compatible con Arduino IDE y Platform IO
• Emulación de AY8912 (libreria fabgl) versión reducida de dcrespo3d(David Crespo Tascón)
• Ajuste de pantalla X
• Menú de velocidad de CPU de emulación (AUTO), sonido, teclado
• Soporte para modo 8 y 64 colores (versión reducida de Ricardo Massaro).
• Soporte DSK de 42 tracks y 11 sectores.
• Emula sólo el CRTC 0
• Soporta modo 0, 1 y 2 de video
• VGA 400x300
• VGA 320x200 con o sin bordes
• Emulación CPC 464 y 664
• Emulacion CPC 6128 (inestable)
• Emulación de AMX Mouse (librería reducida de Rob Kent jazzycamel)
• Ya se permite tener el modo de video 400x300 64 colores, el modo 128 KB, así como el ratón y el sonido todo activo.
• Paleta monocromo Verde para simular GT65

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
• Librería reducida Arduino fabgl 0.9.0 (incluida en proyecto PLATFORMIO)
• Librería reducida Arduino bitluni 0.3.3 (incluida en proyecto)

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 TinyCPCEMttgovga32. 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 CPCem.ino del directorio CPCem.

Debemos instalar las extensiones de spressif 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):

• Seleccionar Máquina permite elegir CPC 464, 664 o 6128.
• Seleccionar DSK permite elegir el disco.
• Offset X de la pantalla
• Permite saltar un frame
• Cambiar los milisegundos de polling para video, teclado, ratón y sonido
• Cambiar los milisegundos de espera en cada frame
• Sonido Volumen (100%, 75,%, 50%, 25%, 5%)
• Sonido activo o en silencio
• Espera de CPU en modo AUTO (ajuste 20 ms por frame real) o la espera en ms que queramos
• Ratón Detectar, permite volver a inicializar el ratón, si se ha desconectado en caliente
• Ratón ON y OFF, permite inhabilitar la lectura del ratón. De está forma la emulación va más rápida.

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

Los ficheros deben ser convertidos a .h en hexadecimal. Puede usarse la herramienta online:
http://tomeko.net/online_tools/file_to_hex.php?lang=en Los DSK están en formato DUMP para ahorrar memoria, y se debe utilizar la herramienta dsk2h para generar los .h necesarios.

Opciones

El archivo gbConfig.h se seleccionan las opciones:

• use_lib_400x300: Se usa modo de vídeo 400x300.
• use_lib_320x200_video_border: Se usa modo de vídeo 320x200 con bordes, de manera que se reduce el tamaño de la pantalla a la mitad. Este modo consume menos RAM que el 400x300 y es más rápido. El modo con bordes, es más lento que el normal, dado que realiza el ajuste de aspecto.
• use_lib_320x200_video_noborder: Se usa modo de vídeo 320x200 sin bordes. En este modo no se reduce la pantalla a la mitad, pero se pierden los bordes. Este modo consume menos RAM que el 400x300 y es más rápido.
• use_lib_vga8colors: Obliga a usar RGB modo de 8 colores (3 pines). Saca 8 colores, frente a los 64 del modo normal (6 pines RRGGBB).
• use_lib_sound_ay8912: Se utiliza un mezclador de 3 canales en modo dirty, emulando el AY8912. Consume un poco de RAM. Se requiere la librería fabgl 0.9.0 reducida, ya incluida en el proyecto
• use_lib_log_serial: Se envian logs por puerto serie usb
• usb_lib_optimice_checkchange_bankswitch: Sólo conmuta bancos cuando son distintos, ganando velocidad.
• use_lib_128k: Permite usar el modo 128K, incluyendo la rom del 6128 en la compilación, así como 2 bloques de memoria de 64KB. Está en fase de pruebas, y al requerir más RAM, se tiene que usar otras opciones de configuración de bajo consumo de RAM.
• use_lib_cheat_128k: Modo experimental de 128 KB.
• gb_ms_keyboard: Se debe especificar el número de milisegundos de polling para el teclado.
• gb_ms_sound: Se debe especificar el número de milisegundos de polling para el sonido.
• gb_frame_crt_skip: Si es 1 se salta un frame.
• gb_delay_emulate_ms: Milisegundos de espera por cada frame completado.
• use_lib_amx_mouse: Se usa un ratón PS/2 como si fuera un AMX mouse (emulado).
El uso del ratón consume un poco de CPU y memoria.
• gb_delay_init_ms: Especifica un número de milisegundos inciales de espera en el arranque del ratón, para que lo detecte correctamente.
• use_lib_amx_mouse_lefthanded: Ratón para zurdos (intercambia botones)
• gb_ms_mouse: Muestreo en milisegundos de cada lectura de ratón.
• use_lib_lookup_znptable: Usa tabla precalculada en FLASH para cálculos BCD. Consume 256 bytes.
• use_lib_lookup_znptable16: Usa tabla precalculada en FLASH para cálculos BCD. Consume 64 KBs.

Aplicaciones Test

Al arrancar el ESP32, se realiza en modo CPC464 cargando el BASIC. Podemos elegir los siguientes juegos:

• Corsair Trainer
• Babas Palace
• Amsthrees
• Sokoban
• Max Desk: prueba de ratón
• AMX Mouse: Editor de imágenes con ratón

Se ha compactado todo en varios discos:

 
 Disco 1 
  babaspalace (run "disc.bas")
   cod0.bin 40K
   cod1.bin 2K
   disc.bas 1K   
   loader.bin 1K   
  amsthree (run "amsthree.bin")   
   amsthree.bin 38K   
  sokoban (run "sokoban.bin")
   sokoban.bin 9K
   sokoban.dat 19K
 
 
 Disco 2
  corsair trainer (run "disc.bin")
   code.bin 16K
   codex.bin 16K
   data.bin 17K
   disc.bin 8K
   intro.bin 17K
   menuexo.bin  3K
  amxmousev2 (run "amx.bas")
   amx.bas 1K
   art.bin 9K
   art.icn 2K
   char.bin 1K
   colhats.bin 1K
   demloa.bin 1K
   demo.rs 9K
   icondes.bas 10K
   monmc.bin 1K
   mspr.bin 2K 
   ocode.bin 1K
   pat1.pcn 1K
   patdes.bas 8K
   pgen.bas 11K
   rom.icn 2K
   rsxb.bin 2K
   scrload.bas 2K
   vdutab.o 1K


 Disco3
  Max desk oculto (run "maxdesk")
   maxdesk 1k
   maxdesk.n01 1k
   maxdesk.n02 34k
   maxdesk.n04 17k
   maxdesk.n05 2k
   sysvars.bin 1k

AMX Mouse

Para poder usar un ratón como si fuera un AMX Mouse, se requiere activar en el fichero de configuración el soporte.

Se permite configurar el ratón para zurdos (también desde el OSD), así como los tiempos de muestreo, todo ello en el fichero gbConfig.h.

DIY circuito

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

Tool dsk2h

He creado una herramienta muy básica, para convertir los archivos .dsk en .h, así como roms en modo lista para ser procesados por el emulador. Tan sólo tenemos que dejar los archivos .dsk en la carpeta dsks, así como .rom en romextra y ejecutar el archivo dsk2h.exe, de forma que se generará una salida en el directorio dataFlash. Para pruebas, se ha dejado 2 archivos en el directorio dsks, así como un par de roms, que se recomienda borrar en caso de realizar una nueva lista personalizada. También se recomienda borrar los archivos del directorio CPCem\dataFlash\dsk para tener un proyecto limpio.

Tool dsk2h

 input/
  dsks/
  romextra/
 output/ 
  dataFlash/
   dsk/
   romextra/   

Posteriormente debemos copiar el directorio dataFlash en el proyecto TinyCPCEMttgovga32\CPCem 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.
El proyecto en PLATFORM.IO está preparado para 2 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).

Cargar ROMS

Los juegos en formato ROM (16 KB), se pueden cargar en LOW y en HIGH (slot 0 al 15). Cuando se selecciona la opción de Run ROM se autoescribe el nombre de la ROM que se invoca como comando RSX. Este comando RSX coincide con el nombre del archivo rom que se generó, por lo que debemos darle el nombre de archivo .ROM exacto al que se invoca.
Cuando queramos cargar otro juego, debemos resetear, o bien seleccionando el menú de Machine o bien Reset.
Si queremos lanzar el juego arkanoid, debemos elegir desde el menú Load or Run ROM, luego Run ROM y por último nos pedirá seleccionar Arkanoid. Al finalizar, seleccionamos High ROM(0..15), en donde ponemos por ejemplo el slot 1, y en un par de segundos, se escribirá |arkanoid.
Si elegimos sólo Load ROM, hará lo mismo que lo anterior, pero sin lanzar el RSX |arkanoid. Este nombre de archivo debe coincidir con el nombre real del juego interno.
Si tenemos juego de varias ROMS, por ejemplo 3weeks.rom y 3weeks2.rom, debemos cargar 3weeks.rom en slot 1 y 3weeks2.rom en slot 2, y por último lanzar el principal, que en este caso sería 3weeks.rom

Más información de ROMS: https://www.cpcwiki.eu/index.php/ROM_List

Monocromo

En el modo de 64 colores, se ha añadido la posibilidad de elegir 3 tipos de paleta de color monocromo verde. Dado que el DAC es de 6 bits, sólo se permite 11 niveles de verde, además del negro.

Por tanto, no podemos conseguir la misma calidad que un monitor GT65.

CPM

Para ejecutar el Sistema Operativo CPM se requiere el DSK del mismo (no incluido en este proyecto), y pulsar la tecla |.

La Tecla Tilde se saca con la combinación SHIFT + F10.