Core de Atari 2600, nueva sección de hardware, y más

doc/English ZXDOS+ and gomaDOS+ Manual.adoc

@@ -1,6 +1,6 @@
 = ZXDOS+ and gomaDOS+ Manual
 :author: kounch
-:revnumber: 1.1.8
+:revnumber: 1.1.9
 :doctype: book
 :front-cover-image: image:img/portada.jpg[]
 :email: kounch@users.noreply.github.com
@@ -774,7 +774,16 @@ Copy the file to the root of the MicroSD card, turn on and press `F2` to enter B
 
 === ROMs
 
-To update the ROMs installed for ZX Spectrum, a file named `ROMS.ZX1` must be obtained, which must be copied to the MicroSD card. Boot the ZXDOS+ using a "rooted" ROM, and then just enter the command `.romsupgr`. This will burn all the ROMs, which will be available for use.
+The flash memory of a ZXDOS+ has reserved 64 slots, 16K each, to store ZX Spectrum ROM images. Thus, an original ZX Spectrum ROM (16K) will take one slot, a ZX Spectrum 128K ROM (32K) will be two slots, and a ZX Spectrum +2A ROM (64K) will need 4 slots.
+
+You can add a new ROM pressing the key `N` at the BIOS <<_roms,ROMs screen>>, connecting an audio cable to the board, and playing a ROM audio tape. ROM audio tapes can be made from a `.tap` file built with the `GenRom` utility, available at https://github.com/zxdos/zxuno/tree/master/modflash[ZX-Uno Code Repository].
+
+To update at once all the ROMs installed for ZX Spectrum, a file named `ROMS.ZX1` must be obtained, which must be copied to the MicroSD card. Boot the ZXDOS+ using a "rooted" ROM, and then just enter the command `.romsupgr`. This will burn all the ROMs, which will be available for use.
+
+[WARNING]
+====
+At this moment, `romsupgr`, only works correctly with files using a maximum of 35 slots.
+====
 
 [NOTE]
 ====
@@ -783,6 +792,11 @@ Remember that if the ZXDOS+ is started by pressing the `/` key (on the numeric k
 
 To do the opposite process (save the ROMs in a `ROMS.ZX1` file), you can use the` .romsback` command.
 
+[WARNING]
+====
+At this moment, `romsback`, only stores correctly the first 35 used slots.
+====
+
 `ROMS.ZX1` files can be easily edited with the http: // guest: zxuno@svn.zxuno.comsvn/zxuno/software/ZX1RomPack/[ZX1RomPack] utility. Although it is a Windows program, it works perfectly, for example using https://www.winehq.org[Wine] or similar programs, either on MacOS or Linux.  
 
 === Cores
@@ -821,6 +835,21 @@ Do a Hard-reset, or turn it off and on.
 
 If everything has been done correctly, when you turn on the ZXDOS+ you will see how esxdos detects the card and loads the necessary components to work, showing the new version at the top.
 
+=== Flash Memory
+
+You also can update all the FPGA flash memory. At this moment, from the BIOS you can only use 16MiB image files. To use a 32MiB image, you must use <<_esxdos,esxdos>> `UPGR32M` command and a file named `FLASH.ZX2`.
+
+Copy the image file (16MiB) `FLASH.ZXD` to the root of the microSD card.
+
+Turn on the ZXDOS+ and press the `F2` key (`Caps Shift+1` on gomaDOS+) during boot to access the BIOS setup. Select the menu `Upgrade` and then choos the option __"Upgrade flash from SD"__. Press Enter, choose `Yes`, and press Enter again to start the Flash writing process.
+
+Do a Hard-Reset or turn of and on again.
+
+[WARNING]
+====
+This process can't be undone, and it will replace all the previously installed cores, the BIOS, the ZX Spectrum ROMs and their configuration with the data in the image file. 
+====
+
 <<<
 
 == Other cores
@@ -922,6 +951,7 @@ Some of its features are:
 - 128K Nextor (MSX-DOS2 evolution) ROM with SD driver
 - Reconfigurable keyboard map
 - Scanlines
+- Joystick support
 
 ==== microSD format
 
@@ -1251,7 +1281,7 @@ Some features of this core are:
 - Two different video modes: RGB/PAL60Hz and VGA 60Hz
 - 7 game variants
 - Support for 2 or 4 players
-- Support for Joysticks, keyboard and/or mouse controls
+- Support for Joysticks, keyboard, mouse and rotary encoder controls (see <<_rotary_enoders,here>> for more information)
 - Several colour modes
 
 ==== microSD format
@@ -1401,6 +1431,112 @@ At multicart menu, use the directional controls to choose one ROM, and then fire
 
 <<<
 
+=== Atari 2600
+
+https://en.wikipedia.org/wiki/Atari_2600[Atari 2600]  is a home video game console originally branded as the Atari Video Computer System (Atari VCS).
+
+ZXDOS+ core version is developed by avlixa.
+
+Some of the features of the core are:
+
+- RGB and VGA support
+- Support for joysticks, keyboard, mouse and rotary encoder controls (see <<_rotary_enoders,here>> for more information)
+
+==== microSD card format
+
+You need a microSD card with the first partition in FAT16 format to store ROM image files of the games to load.
+
+See the <<_cores,corresponding section>> for instructions of how to install the Atari 2600 core in ZXDOS+.
+
+==== Keyboard
+
+For gomaDOS+, it is recommended to change the keyboard mode to `Atari 800` (`Caps Shift + Symbol Shift + U` and then `4`) o `PC XT` (`Caps Shift + Symbol Shift + U` and then `9`).
+
+==== Special keys and buttons
+
+During the core exeution:
+
+- `W`, `A`, `S`, `D` or joystick 1: Directional controls for player 1
+- `F` or joystick 1 fire button: Player 1 fire button
+- `I`, `J`, `K`, `L` or joystick 2: Directional controls for player 2
+- `H` oor joystick 2 fire button: Player 2 fire button
+- `Scroll Lock` (`Caps Shift+Symbol Shift+G` on gomaDOS+): change between RGB and VGA video mode
+- `Ctrl+Alt+Backspace` (`Caps Shift+Symbol Shift+B` on gomaDOS+): Hard reset.
+
+<<<
+
+==== Basic Guide
+
+Pressing `Esc` or joystick button 2 (`Caps Shift+Space` on gomaDOS+, `Atari800` keyboard mode) shows or hides the configuration menu. Cursor keys (`Caps Shift+5`, `Caps Shift+6`, `Caps Shift+7` and `Caps Shift+8` on gomaDOS+, `Atari800` keyboard mode) and `Enter` to select and choose menu options.
+
+[.text-center] 
+image:img/a2600.jpg[pdfwidth=70%]
+
+The following options are available:
+
+- Reset core
+- Scanlines
+- RGB Mode (PAL/NTSC)
+- Paddle Size
+- Sound
+- Color
+- Difficulty A
+- Difficulty B
+- Select
+- Start
+- Load ROM
+- Joystick
+- Paddle Accuracy
+- Exit
+
+<<<
+
+== Other Hardware
+
+=== Rotary Encoders
+
+Pong and Atari 2600 cores support the use of quadrature https://en.wikipedia.org/wiki/Rotary_encoder[rotary encoders] as control devices. They can be connected to the joystick ports. Although the testing has been done with 600 ppr encoders, lower ppr encoders, like 400 or 300, should also work.
+
+You can also use an Atari 2600 https://en.wikipedia.org/wiki/Paddle_(game_controller)[paddle] driving controller. In this case the playing experience is bad, since they have few ppr and you must do several full rotations. When using them, it's recommended to set the accuracy setting to 8, to have enough speed.
+
+==== Connection
+
+Both ZXDOS+ and gomaDOS+ have joystick pin 5 connected to positive VCC, used as main power, and pin 8 as GND. The rotary encoders to use must support voltage from 3,4v to 5v.
+
+A rotary encoder has 5 wires: Earth Ground (not connected), Vcc (`+`), GND (`0V`or `-`), `A` and `B`.
+
+`A` y `B` are connected to pins 1 and 2 for the first encoder, 3 and 4 for the seconde one. This way you can have up to 4 encoders connected using both joystick ports.
+
+[.text-center] 
+image:img/db9joy.png[pdfwidth=40%]
+
+This way, the connections should be:
+
+. Line `A` encoder 1
+. Line `B` encoder 1
+. Line `A` encoder 2
+. Line `B` encoder 2
+. Vcc(`+`)
+. Fire 1
+. NC
+. `GND`
+. Fire 2
+
+<<<
+
+==== Pong Core Configuration
+
+Follow these directions to choose the configuration:
+
+- For 1 or 2 endoders on joystick port 2 de joystick, select `1/2 Paddle in J2` option
+- For 2 encoders, one for each joystick port, select `2/4 Paddle in J1&J2` option. This is also valid to connect two Atari 2600 driving paddles
+- For 4 encoders, two for each joystick port, select `2/4 Paddle in J1&J2` option
+- For 1 or 2 encoders on joystick port 2 along with a mouse (in this case the encoders are for players 2 and 4), select `Mouse PS/2` option
+
+It is recommended to wait, and make the connection after selecting the chosen option, since the encoders interfere with the up/down directions of the joystick, blocking access to the menu. Another option is to add a on/off switch for the encoder that will disable the power.
+
+<<<
+
 == Troubleshooting
 
 === Firmware recovery
@@ -1575,7 +1711,7 @@ image:img/recovery2.png[pdfwidth=70%]
 
 [WARNING]
 ====
-This will replace all the previously installed cores and ZX Spectrum ROMs.
+This process can't be undone, and it will replace all the previously installed cores, the BIOS, the ZX Spectrum ROMs and their configuration with the data in the image file.
 ====
 
 [NOTE]

doc/Manual de ZXDOS+ y gomaDOS+.adoc

@@ -1,6 +1,6 @@
 = Manual de ZXDOS+ y gomaDOS+
 :author: kounch
-:revnumber: 1.1.8
+:revnumber: 1.1.9
 :doctype: book
 :front-cover-image: image:img/portada.jpg[]
 :email: kounch@users.noreply.github.com
@@ -652,7 +652,7 @@ Tal y como se ha explicado en la parte de instalación, existe una serie de coma
 - `playrmov`: Reproduce videos en <<#_creación_de_vídeos_rdm_radastan_movie,formato radastaniano (ficheros `.RDM`)>>. Este comando no funciona en modo 48K.
 - `romsback`: Copia a un fichero `ROMS.ZX1` en el directorio raíz de la tarjeta microSD todas las ROMS del core ZX Spectrum almacenadas en la memoria SPI Flash. Se debe ejecutar desde una ROM en modo "root". 
 - `romsupgr`: Copia el contenido de un fichero `ROMS.ZX1` en el directorio raíz de la tarjeta microSD con todas las ROMS para el core ZX Spectrum a la memoria SPI Flash. Se debe ejecutar desde una ROM en modo "root". 
-- `upgr16m`: Copia el contenido de un fichero `FLASH.ZX1` en el directorio raíz de la tarjeta SD a una memoria SPI Flash de 16 megas. Se debe ejecutar desde una ROM en modo "root". 
+- `upgr16m`: Copia el contenido de un fichero `FLASH.ZX1` en el directorio raíz de la tarjeta SD a una memoria SPI Flash de 16 megas. Se debe ejecutar desde una ROM en modo "root".
 - `upgr32m`: Copia el contenido de un fichero `FLASH.ZX2` a una memoria SPI Flash de 32 megas.Versión del comando upgrade exclusivo para memorias SPI Flash de 32 Megas. Se debe ejecutar desde una ROM en modo "root". 
 - `zxuc`: Configura todas las opciones de la BIOS, permitiendo grabar en la microSD las opciones  seleccionadas en archivos de configuración que pueden posteriormente ser cargados.
 - `zxunocfg`: Configura determinados aspectos del funcionamiento del ZX-Uno como los timings, la contención, el tipo de teclado, la velocidad de la CPU, el tipo y frecuencia vertical del vídeo.
@@ -772,7 +772,16 @@ Copiar el fichero en la raíz de la tarjeta MicroSD, encender y pulsar `F2` para
 
 === ROMs
 
-Para actualizar las ROM instaladas para ZX Spectrum se ha de obtener un fichero con el nombre `ROMS.ZX1`, y se tiene que copiar en la tarjeta MicroSD. Arrancar el ZXDOS+ usando una ROM "rooted", y entonces bastará con introducir el comando `.romsupgr`. Esto grabará todas las ROM, que quedarán disponibles para su uso.
+La memoria flash del ZXDOS+ dispone de 64 "slots", de 16K cada uno, para almacenar imágenes ROM de ZX Spectrum y compatibles. Así, la ROM del ZX Spectrum original (16K) ocuparía un slot del almacenamiento, la del ZX Spectrum 128K (32K) ocuparía dos slots, y la del ZX Spectrum +2A (64K) ocuparía 4 slots.
+
+Se puede añadir una nueva ROM desde <<_roms,la pantalla ROMs>> de la BIOS, pulsando la tecla `N`, conectando un cable de audio a la entrada de sonido de la placa, y reproduciendo una cinta de carga de ROM. Las cintas de carga de ROM se pueden crear desde un archivo `.tap` generado con la utilidad `GenRom`, disponible en el https://github.com/zxdos/zxuno/tree/master/modflash[repositorio de código de ZX-Uno].
+
+Para actualizar las ROM instaladas para ZX Spectrum de forma masiva, se ha de obtener un fichero con el nombre `ROMS.ZX1`, y se tiene que copiar en la tarjeta MicroSD. Arrancar el ZXDOS+ usando una ROM "rooted", y entonces bastará con introducir el comando `.romsupgr`. Esto grabará todas las ROM, que quedarán disponibles para su uso.
+
+[WARNING]
+====
+La versión actual `romsupgr`, en ZXDOS+, sólo funciona correctamente con ficheros que tengan un máximo de 35 slots de ROM ocupados.
+====
 
 [NOTE]
 ====
@@ -781,6 +790,11 @@ Recordar que, si se inicia el ZXDOS+ pulsando la tecla `/` (del teclado numéric
 
 Para hacer el proceso contrario (guardar las ROM en un fichero `ROMS.ZX1`), se puede usar el comando `.romsback`.
 
+[WARNING]
+====
+La versión actual de `romsback`, en ZXDOS+, sólo almacena correctamente los primeros 35 slots de ROM ocupados.
+====
+
 Los ficheros `ROMS.ZX1` se pueden editar fácilmente con la utilidad http://guest:zxuno@svn.zxuno.comsvn/zxuno/software/ZX1RomPack/[ZX1RomPack]. Aunque es un programa de Windows, funciona perfectamente, por ejemplo, usando https://www.winehq.org[Wine] o programas similares, tanto en MacOS como en Linux. 
 
 === Cores
@@ -819,6 +833,21 @@ Realizar un Hard-reset, o apagar y encender.
 
 Si todo se ha hecho correctamente, al encender el ZXDOS+ se verá cómo esxdos detecta la tarjeta y carga los componentes necesarios para funcionar, mostrando la nueva versión en la parte superior.
 
+=== Memoria Flash
+
+También es posible actualizar la memoria flash de la FPGA. Por el momento desde el menú de la BIOS sólo es posible utilizar imágenes de 16MiB. Para poder usar una imagen de 32MiB, se ha de usar el comando `UPGR32M` de <<_esxdos,esxdos>> y un fichero con el nombre `FLASH.ZX2`.
+
+Copiar el archivo de imagen (de 16MiB) `FLASH.ZXD` en la raíz de la tarjeta microSD.
+
+Iniciar el ZXDOS+ con la tarjeta insertada y pulsar F2 (`Caps Shift+1` en gomaDOS+) para acceder a la configuración de BIOS. Seleccionar el menú `Upgrade` y elegir __"Upgrade flash from SD"__. En el diálogo que pregunta __"Load from SD"__ contestar __"Yes"__ a la pregunta __"Are you sure?"__. Se leerá el contenido del fichero `FLASH...`, .
+
+Realizar un Hard-reset, o apagar y encender.
+
+[WARNING]
+====
+Este proceso sustituye todos los cores instalados, la BIOS, así como las ROMs de ZX Spectrum y la configuración por lo que haya en la imagen, y no se puede deshacer.
+====
+
 <<<
 
 == Otros cores
@@ -920,6 +949,7 @@ Algunas de sus características son:
 - Utiliza Nextor ROM con un controladr para SD
 - Mapa de teclado configurable
 - Simulación de línea de exploración (Scanlines)
+- Soporte para joystick
 
 ==== Formato de Tarjeta microSD
 
@@ -1249,7 +1279,7 @@ Algunas las características del core son:
 - Dos modos de vídeo seleccionables: RGB/PAL60Hz y VGA 60Hz
 - 7 tipos de juego
 - Soporte 2 o 4 jugadores
-- Compatible con joystick(s), teclado y ratón
+- Compatible con joystick(s), teclado, ratón y codificadores (encoders) rotatorios (ver <<_codificadores_rotatorios,aquí>> para más información)
 - Varios modos de color
 
 ==== Formato de Tarjeta microSD
@@ -1294,7 +1324,7 @@ En él se pueden activar o desactivar las siguientes opciones:
 - Velocidad Aleatoria (Random Speed)
 - Ángulo Aleatorio (Random Angle)
 - Control por Joystick, teclado o ratón (Joystick)
-- Precisión de las palas (Paddle Accuracy)
+- Precisión del movimiento (Paddle Accuracy)
 - Modo de color (Mode)
 - Salir del menú (Exit menu)
 
@@ -1366,7 +1396,7 @@ Algunas de las características del core son:
 
 ==== Formato de Tarjeta microSD
 
-Se debe de utilizar una tarjeta microSD, con la primera partición en formato FAT16, para almacenar los ficheros con las imágenes ROM y otros archivos necesarios. Los archivos se pueden descargar desde la https://github.com/fbelavenuto/colecofpga/tree/master/SD_Card[web del proyecto original en GitHub]
+Se debe de utilizar una tarjeta microSD, con la primera partición en formato FAT16, para almacenar los ficheros con las imágenes ROM y otros archivos necesarios. Los archivos se pueden descargar desde la https://github.com/fbelavenuto/colecofpga/tree/master/SD_Card[web del proyecto original en GitHub].
 
 Si no estuviera ya, <<_cores,instalar el core de ColecoVision>> en el ZXDOS+.
 
@@ -1399,6 +1429,112 @@ En el menú multicartucho, usar los controles de dirección para elegir la ROM a
 
 <<<
 
+=== Atari 2600
+
+La https://es.wikipedia.org/wiki/Atari_2600[Atari 2600] es una videoconsola lanzada al mercado bajo el nombre de Atari VCS (Video Computer System).
+
+La versión para ZXDOS+ está desarrollada por avlixa.
+
+Algunas de las características del core son:
+
+- Dos modos de vídeo seleccionables: RGB y VGA
+- Compatible con joystick(s), teclado, ratón y codificadores (encoders) rotatorios (ver <<_codificadores_rotatorios,aquí>> para más información)
+
+==== Formato de Tarjeta microSD
+
+Se debe de utilizar una tarjeta microSD, con la primera partición en formato FAT16, para almacenar los ficheros con las imágenes ROM que se deseen cargar.
+
+Si no estuviera ya, <<_cores,instalar el core de Atari 2600>> en el ZXDOS+.
+
+==== Teclado
+
+En gomaDOS+, se recomienda cambiar el modo de teclado a `Atari 800` (`Caps Shift + Symbol Shift + U` y luego `4`) o `PC XT` (`Caps Shift + Symbol Shift + U` y luego `9`).
+
+==== Teclas especiales y botones
+
+Durante la ejecución del core:
+
+- `W`, `A`, `S`, `D` o el joystick 1: Controles de dirección del jugador 1
+- `F` o el botón de disparo del joystick 1: Disparo del jugador 1
+- `I`, `J`, `K`, `L` o el joystick 2: Controles de dirección del jugador 2
+- `H` o el botón de disparo del joystick 2: Disparo del jugador 2
+- `Bloq. Despl.` (`Caps Shift+Symbol Shift+G` en gomaDOS+): para cambiar entre modo de video compuesto y VGA
+- `Ctrl+Alt+Backspace` (`Caps Shift+Symbol Shift+B` en gomaDOS+): Hard reset.
+
+<<<
+
+==== Guía básica
+
+Pulsando `Esc` o el botón 2 del joystick (o `Caps Shift+Espacio` en gomaDOS+, en modo de teclado `Atari800`) se muestra el menú de configuración. Se usan las teclas de cursor (`Caps Shift+5`, `Caps Shift+6`, `Caps Shift+7` y `Caps Shift+8` en gomaDOS+, en modo de teclado `Atari800`) y `Enter` para elegir y seleccionar en el menú.
+
+[.text-center] 
+image:img/a2600.jpg[pdfwidth=70%]
+
+En él se pueden activar, desactivar o configurar las siguientes opciones:
+
+- Reiniciar el core (Reset)
+- Línea de exploración (Scanlines)
+- Modo RGB (PAL/NTSC)
+- Tamaño de las palas (Paddle Size)
+- Sonido (Sound)
+- Color (Color)
+- Dificultad A (Difficulty A)
+- Dificultad B (Difficulty B)
+- Select
+- Start
+- Cargar ROM (Load ROM)
+- Joystick
+- Precisión de paddle (Paddle Accuracy)
+- Salir del menú (Exit)
+
+<<<
+
+== Otro Hardware
+
+=== Codificadores rotatorios
+
+Los cores de Pong y Atari 2600 están también preparados para usar https://es.wikipedia.org/wiki/Codificador_rotatorio[codificadores rotatorios] (encoders), de tipo cuadratura, conectados al puerto de joystick. Está probado con codificadores de 600 ppr (pulsos por revolución), pero teóricamente deberían servir también de menor ppr, como de 400 o 300.
+
+También se puede utilizar con https://es.wikipedia.org/wiki/Paddle_(controlador_de_videojuegos)[paddle] del tipo volante de Atari 2600, pero **no** con los paddle del tipo raqueta. Eso sí, la experiencia en este caso es pobre, ya que son de muy pocos ppr y se deben hacer varios giros completos. Si se utilizan, se recomienda ajustar la precisión(accuracy) al valor 8 para conseguir una velocidad aceptable.
+
+==== Conexión
+
+Tanto el ZXDOS+ como el gomaDOS+ tienen conectado el pin 5 del joystick a voltaje positivo, que se utiliza para alimentación, y el pin 8 como GND. Los codificadores utilizados deben admitir voltajes de 3,4v a 5v.
+
+Los codificadores tienen 5 cables: Tierra (no conectada), Vcc (`+`), GND (`0V`ó `-`), `A` y `B`.
+
+Las conexiones `A` y `B` se conectan en los pines 1 y 2 para el primer codificador, y 3 y 4 para el segundo. Así se pueden tener hasta 4 codificadores conectados entre los 2 puertos de joystick.
+
+[.text-center] 
+image:img/db9joy.png[pdfwidth=40%]
+
+De esta manera, las conexiones serían:
+
+. Línea `A` codificador 1
+. Línea `B` codificador 1
+. Línea `A` codificador 2
+. Línea `B` codificador 2
+. Vcc(`+`)
+. Disparo 1
+. NC
+. `GND`
+. Disparo 2
+
+<<<
+
+==== Configuración del Core de Pong
+
+La forma de elegir la configuración es la siguiente:
+
+- Para 1 o 2 codificadores en el puerto 2 de joystick, seleccionar la opción `1/2 Paddle in J2`.
+- Para 2 codificadores, uno en cada puerto de joystick, seleccionar la opción `2/4 Paddle in J1&J2`. Esta opción también sirve para conectar 2 paddle tipo driving de Atari 2600.
+- Para  4 codificadores, dos en cada puerto de joystick, seleccionar la opción `2/4 Paddle in J1&J2`.
+- Para 1 o 2 codificadores en el puerto 2 de joystick junto con el ratón (en este caso los codificadores se asocian para los jugadores 2 y 4), seleccionar la opción `Mouse PS/2`.
+
+Se recomienda no realizar la conexión hasta haber seleccionado la opción deseada, ya que los codificadores actúan sobre el botón arriba/abajo del joystick y por tanto no permiten manejar el menú. Otra opción sería añadir un interruptor on/off en el codificador que deshabilite la alimentación y así no emita señal mientras se realiza la selección de menú.
+
+<<<
+
 == Solución de problemas
 
 === Recuperación del firmware
@@ -1573,7 +1709,7 @@ image:img/recovery2.png[pdfwidth=70%]
 
 [WARNING]
 ====
-Este proceso sustituirá todos los cores instalados por los que haya en la imagen, así como las ROMs de ZX Spectrum.
+Este proceso sustituirá todos los cores instalados, la BIOS, así como las ROMs de ZX Spectrum y la configuración por lo que haya en la imagen, y no se puede deshacer.
 ====
 
 [NOTE]