Added ESPJoy Manual

Addes ESPJoy to ZXUNO+ Manual

doc/src/English ESPjoy Manual.adoc

@@ -0,0 +1,34 @@
+= ESPjoy English Manual
+:author: kounch
+:revnumber: 1.0.0
+:doctype: book
+:notitle:
+:front-cover-image: image:img/portadaespjoy.png[]
+:email: kounch@users.noreply.github.com
+:Revision: 1.0
+:description: ESPjoy English Manual
+:keywords: Manual, English, ESPjoy
+:icons: font
+:source-highlighter: rouge
+:toc: left
+:toc-title: Index
+:toclevels: 4
+
+<<<
+
+== Introduction
+
+include::espjoy_en.adoc[]
+
+== References
+
+https://antoniovillena.com/product/espjoy/
+
+http://github.com/Dacarsoft/DB9_2_Keyboard
+
+https://github.com/MickGyver/DaemonBite-Retro-Controllers-USB/tree/master/SegaTwoControllersUSB
+
+https://avrdude.readthedocs.io/en/latest/
+
+https://stackoverflow.com/questions/45646127/how-to-upload-a-hex-file-into-an-arduino-leonardo-using-avrdude-from-the-command
+

doc/src/English ZXUNO+ and +UNO Manual.adoc

@@ -1,6 +1,6 @@
 = ZXUNO+ and +UNO Manual
 :author: kounch
-:revnumber: 1.5.0
+:revnumber: 1.6.0
 :doctype: book
 :notitle:
 :front-cover-image: image:img/portadauno.jpg[]
@@ -4570,6 +4570,12 @@ CHROMA81: enabled
 
 == Other Hardware
 
+=== ESPJoy
+
+include::espjoy_en.adoc[leveloffset=+2]
+
+<<<
+
 === Rotary Encoders
 
 The Pong core supports the use of quadrature https://en.wikipedia.org/wiki/Rotary_encoder[rotary encoders] as control devices. They can be connected to joystick ports. Although the testing has been done with 600 ppr encoders, lower ppr encoders, like 400 or 300, should also work.

doc/src/Manual de ESPjoy.adoc

@@ -0,0 +1,34 @@
+= Manual de ESPjoy
+:author: kounch
+:revnumber: 1.0.0
+:doctype: book
+:notitle:
+:front-cover-image: image:img/portadaespjoy.png[]
+:email: kounch@users.noreply.github.com
+:Revision: 1.0
+:description: Manual en castellano de ESPjoy
+:keywords: Manual, Castellano, ESPjoy
+:icons: font
+:source-highlighter: rouge
+:toc: left
+:toc-title: Índice
+:toclevels: 4
+
+<<<
+
+== Introducción
+
+include::espjoy_es.adoc[]
+
+== Referencias
+
+https://antoniovillena.com/product/espjoy/
+
+http://github.com/Dacarsoft/DB9_2_Keyboard
+
+https://github.com/MickGyver/DaemonBite-Retro-Controllers-USB/tree/master/SegaTwoControllersUSB
+
+https://avrdude.readthedocs.io/en/latest/
+
+https://stackoverflow.com/questions/45646127/how-to-upload-a-hex-file-into-an-arduino-leonardo-using-avrdude-from-the-command
+

doc/src/Manual de ZXUNO+ y +UNO.adoc

@@ -1,6 +1,6 @@
 = Manual de ZXUNO+ y +UNO
 :author: kounch
-:revnumber: 1.5.0
+:revnumber: 1.6.0
 :doctype: book
 :notitle:
 :front-cover-image: image:img/portadauno.jpg[]
@@ -4605,6 +4605,12 @@ CHROMA81: enabled
 
 == Otro Hardware
 
+=== ESPJoy
+
+include::espjoy_es.adoc[leveloffset=+2]
+
+<<<
+
 === Codificadores rotatorios
 
 El core de Pong está también preparado para usar https://es.wikipedia.org/wiki/Codificador_rotatorio[codificadores rotatorios] (encoders), de tipo cuadratura, conectados a un 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.

doc/src/README.md

@@ -8,7 +8,7 @@ In order to make PDF and ePub files from the source code (`.adoc` files), folow
 
 - Run on the shell commands like these (adjusting paths as needed):
 
-      asciidoctor-pdf -a pdf-stylesdir=... -a pdf-style=style.yml -o ".../English ZXUno4ALL Manual.pdf" English ZXUNO+ and +UNO Manual.adoc
+      asciidoctor-pdf -a pdf-theme=style.yml -a pdf-themesdir="..." -o ".../English ZXUno4ALL Manual.pdf" English ZXUNO+ and +UNO Manual.adoc
 
       asciidoctor-epub3 -o ".../English ZXUno4ALL Manual.epub" English ZXUNO+ and +UNO Manual.adoc
 
@@ -22,6 +22,6 @@ Para poder generar desde el código fuente (archivos `.adoc`), ficheros PDF y eP
 
 - Ejecutar unos comandos similares a los siguientes
 
-      asciidoctor-pdf -a pdf-stylesdir=... -a pdf-style=style.yml -o ".../Manual de ZXUNO+ y +UNO.pdf" Manual de ZXUNO+ y +UNO.adoc
+      asciidoctor-pdf -a pdf-theme=style.yml -a pdf-themesdir="..." -o ".../Manual de ZXUNO+ y +UNO.pdf" Manual de ZXUNO+ y +UNO.adoc
 
       asciidoctor-epub3 -o ".../Manual de ZXUNO+ y +UNO.epub" Manual de ZXUNO+ y +UNO.adoc

doc/src/espjoy_en.adoc

@@ -0,0 +1,241 @@
+https://antoniovillena.com/product/espjoy/[ESPjoy] is an adapter board with https://en.wikipedia.org/wiki/D-sub[DE-9] ports for https://en.wikipedia.org/wiki/Atari_joystick_port[Atari standard] or https://en.wikipedia.org/wiki/Sega_Genesis[Sega Genesis (Mega Drive)] controllers that converts their button presses to equivalent keyboard press signals.
+
+It is originally designed to use with https://zxespectrum.speccy.org[ESPectrum], but can be used with other devices, as it is able to convert to two different keyboard protocols (USB and PS/2), with a built-in switch for selection.
+
+This keyboard translation is very useful for emulators or for FPGA-based devices, such as the https://zxuno.speccy.org[ZX-Uno] family and its derivatives or https://github.com/MiSTer-devel/Wiki_MiSTer/wiki[MiSTer], that do not have support for joystick connectors. For example, for computer cores when not using a permanently connected keyboard.
+
+The on-board firmware sends keystrokes when a button of any connected controller is pressed and can use two controllers simultaneously.
+
+One or two-button (Atari standard) controllers and joysticks are supported, as well as three or 6-button Sega controllers.
+
+<<<
+
+== Buttons and ports
+
+[width="100%",cols="2a,3a",frame="none"]
+|===
+|[cols="1,4"]
+!===
+!1 !First DE-9 Port
+!2 !Second DE-9 Port
+!===
+|image:img/ESPjoyFront.png[scaledwidth=70%]
+|===
+
+[width="100%",cols="3a,2a",frame="none"]
+|===
+| image:img/ESPjoyBack.png[scaledwidth=70%]
+|[cols="1,4"]
+!===
+!3 !USB Mini-B Port
+!4 !Protocol selection switch
+!===
+|===
+
+<<<
+
+== Use
+
+=== Configuration
+
+To use with ESPectrum, the PS/2 option on the switch hast to be selected. The USB option can be used with MiSTer or another compatible system (PC, Mac, etc.). With the original firmware designed by David Carrión a HID keyboard is emulated, so it can be used without problem in MiSTer with computer cores.
+
+Connection detection is performed in the first seconds after boot when the board is connected to a USB or PS/2 port is receiving power. If the board is connected to a device such as a PC or similar while starting up, it is very likely that the USB detection will fail, because the operating system is not yet ready when the board detection timeout is reached. In that case, it has to be disconnected and reconnected once the PC device is ready to detect the connection.
+
+[TIP]
+====
+The PS/2 or USB mode selection switch hast to be set before connecting the board to power, or it will not function properly.
+====
+
+=== Keymap selection
+
+On startup, by pressing and holding any of the specified buttons, according to the tables below, you can select one of the different keyboard translations.
+
+[NOTE]
+====
+The default assignment behavior (when no button is pressed at startup) varies depending on the firmware you have installed on the ESPJoy. When the option (Original) is specified, we are talking about the firmware not adapted for ESPectrum. In the other case (ESPectrum), it's about ESPectrum adapted firmware.
+====
+
+[WARNING]
+====
+The default assignment on ESPectrum firmware, when using the PS/2, port makes it incompatible with standard PS/2 devices. Therefore, in that case, you have to press a button which activates a different keyboard configuration during startup.
+====
+
+[WARNING]
+====
+There are some clone controllers that can send strange signals in some directions. Because of this, the startup check in the code may fail, and the activation at startup, e.g. when pressing left on the keyboard, could not work properly. 
+====
+
+<<<
+
+*Port 1 (PS/2)*
+
+[align="center",width="100%",%header,cols="2a,1a,1a,1a,1a,1a,1a,1a,1a,1a,1a,1a,1a",options="header"]
+|===
+|[.tiny]#Press on Start#|[.tiny]#Up#|[.tiny]#Down#|[.tiny]#Left#|[.tiny]#Right#|[.tiny]#A#|[.tiny]#B#|[.tiny]#C#|[.tiny]#Start#|[.tiny]#X#|[.tiny]#Y#|[.tiny]#Z#|[.tiny]#Mode#
+|[.tiny]#None (Original)#|[.tiny]#Up#|[.tiny]#Down#|[.tiny]#Left#|[.tiny]#Right#|[.tiny]#Escape#|[.tiny]#Enter#|[.tiny]#Right Alt#|[.tiny]#F1#|[.tiny]#X#|[.tiny]#Y#|[.tiny]#Z#|[.tiny]#M#
+|[.tiny]#None (ESPectrum)#|[.tiny]#Up#|[.tiny]#Down#|[.tiny]#Left#|[.tiny]#Right#|[.tiny]#A#|[.tiny]#B#|[.tiny]#C#|[.tiny]#Start#|[.tiny]#X#|[.tiny]#Y#|[.tiny]#Z#|[.tiny]#Mode#
+|[.tiny]#Up#|[.tiny]#Q#|[.tiny]#A#|[.tiny]#O#|[.tiny]#P#|[.tiny]#Escape#|[.tiny]#M#|[.tiny]#Enter#|[.tiny]#F1#|[.tiny]#X#|[.tiny]#Y#|[.tiny]#Z#|[.tiny]#C#
+|[.tiny]#Down#|[.tiny]#Up#|[.tiny]#Down#|[.tiny]#Left#|[.tiny]#Right#|[.tiny]#Escape#|[.tiny]#Enter#|[.tiny]#`0`#|[.tiny]#F5#|[.tiny]#X#|[.tiny]#Y#|[.tiny]#Z#|[.tiny]#M#
+|[.tiny]#Left#|[.tiny]#7#|[.tiny]#6#|[.tiny]#5#|[.tiny]#8#|[.tiny]#Escape#|[.tiny]#`0`#|[.tiny]#Enter#|[.tiny]#F1#|[.tiny]#X#|[.tiny]#Y#|[.tiny]#Z#|[.tiny]#M#
+|===
+
+*Port 2 (PS/2)*
+
+[align="center",width="100%",%header,cols="2a,1a,1a,1a,1a,1a,1a,1a,1a,1a,1a,1a,1a",options="header"]
+|===
+|[.tiny]#Press on Start#|[.tiny]#Up#|[.tiny]#Down#|[.tiny]#Left#|[.tiny]#Right#|[.tiny]#A#|[.tiny]#B#|[.tiny]#C#|[.tiny]#Start#|[.tiny]#X#|[.tiny]#Y#|[.tiny]#Z#|[.tiny]#Mode#
+|[.tiny]#None (Original)#|[.tiny]#Q#|[.tiny]#A#|[.tiny]#O#|[.tiny]#P#|[.tiny]#Escape#|[.tiny]#M#|[.tiny]#Enter#|[.tiny]#F1#|[.tiny]#X#|[.tiny]#Y#|[.tiny]#Z#|[.tiny]#C#
+|[.tiny]#None (ESPectrum)#|[.tiny]#Up#|[.tiny]#Down#|[.tiny]#Left#|[.tiny]#Right#|[.tiny]#A#|[.tiny]#B#|[.tiny]#C#|[.tiny]#Start#|[.tiny]#X#|[.tiny]#Y#|[.tiny]#Z#|[.tiny]#Mode#
+|[.tiny]#Up#|[.tiny]#Up#|[.tiny]#Down#|[.tiny]#Left#|[.tiny]#Right#|[.tiny]#Escape#|[.tiny]#Enter#|[.tiny]#Right Alt#|[.tiny]#F1#|[.tiny]#X#|[.tiny]#Y#|[.tiny]#Z#|[.tiny]#M#
+|[.tiny]#Down#|[.tiny]#Up#|[.tiny]#Down#|[.tiny]#Left#|[.tiny]#Right#|[.tiny]#Escape#|[.tiny]#Enter#|[.tiny]#`0`#|[.tiny]#F5#|[.tiny]#X#|[.tiny]#Y#|[.tiny]#Z#|[.tiny]#M#
+|[.tiny]#Left#|[.tiny]#7#|[.tiny]#6#|[.tiny]#5#|[.tiny]#8#|[.tiny]#Escape#|[.tiny]#`0`#|[.tiny]#Enter#|[.tiny]#F1#|[.tiny]#X#|[.tiny]#Y#|[.tiny]#Z#|[.tiny]#M#
+|===
+
+*Port 1 (USB)*
+
+[align="center",width="100%",%header,cols="2a,1a,1a,1a,1a,1a,1a,1a,1a,1a,1a,1a,1a",options="header"]
+|===
+|[.tiny]#Press on Start#|[.tiny]#Up#|[.tiny]#Down#|[.tiny]#Left#|[.tiny]#Right#|[.tiny]#A#|[.tiny]#B#|[.tiny]#C#|[.tiny]#Start#|[.tiny]#X#|[.tiny]#Y#|[.tiny]#Z#|[.tiny]#Mode#
+|[.tiny]#None (Original)#|[.tiny]#Up#|[.tiny]#Down#|[.tiny]#Left#|[.tiny]#Right#|[.tiny]#Escape#|[.tiny]#Enter#|[.tiny]#Right Alt#|[.tiny]#F12#|[.tiny]#X#|[.tiny]#Y#|[.tiny]#Z#|[.tiny]#M#
+|[.tiny]#Up#|[.tiny]#Q#|[.tiny]#A#|[.tiny]#O#|[.tiny]#P#|[.tiny]#Escape#|[.tiny]#M#|[.tiny]#Enter#|[.tiny]#F12#|[.tiny]#X#|[.tiny]#Y#|[.tiny]#Z#|[.tiny]#C#
+|[.tiny]#Down#|[.tiny]#Up#|[.tiny]#Down#|[.tiny]#Left#|[.tiny]#Right#|[.tiny]#Escape#|[.tiny]#Enter#|[.tiny]#`0`#|[.tiny]#F5#|[.tiny]#X#|[.tiny]#Y#|[.tiny]#Z#|[.tiny]#M#
+|[.tiny]#Left#|[.tiny]#7#|[.tiny]#6#|[.tiny]#5#|[.tiny]#8#|[.tiny]#Escape#|[.tiny]#`0`#|[.tiny]#Enter#|[.tiny]#F12#|[.tiny]#X#|[.tiny]#Y#|[.tiny]#Z#|[.tiny]#M#
+|===
+
+*Port 2 (USB)*
+
+[align="center",width="100%",%header,cols="2a,1a,1a,1a,1a,1a,1a,1a,1a,1a,1a,1a,1a",options="header"]
+|===
+|[.tiny]#Press on Start#|[.tiny]#Up#|[.tiny]#Down#|[.tiny]#Left#|[.tiny]#Right#|[.tiny]#A#|[.tiny]#B#|[.tiny]#C#|[.tiny]#Start#|[.tiny]#X#|[.tiny]#Y#|[.tiny]#Z#|[.tiny]#Mode#
+|[.tiny]#None (Original)#|[.tiny]#Q#|[.tiny]#A#|[.tiny]#O#|[.tiny]#P#|[.tiny]#Escape#|[.tiny]#M#|[.tiny]#Enter#|[.tiny]#F12#|[.tiny]#X#|[.tiny]#Y#|[.tiny]#Z#|[.tiny]#C#
+|[.tiny]#Up#|[.tiny]#Up#|[.tiny]#Down#|[.tiny]#Left#|[.tiny]#Right#|[.tiny]#Escape#|[.tiny]#Enter#|[.tiny]#Right Alt#|[.tiny]#F12#|[.tiny]#X#|[.tiny]#Y#|[.tiny]#Z#|[.tiny]#M#
+|[.tiny]#Down#|[.tiny]#Up#|[.tiny]#Down#|[.tiny]#Left#|[.tiny]#Right#|[.tiny]#Escape#|[.tiny]#Enter#|[.tiny]#`0`#|[.tiny]#F5#|[.tiny]#X#|[.tiny]#Y#|[.tiny]#Z#|[.tiny]#M#
+|[.tiny]#Left#|[.tiny]#7#|[.tiny]#6#|[.tiny]#5#|[.tiny]#8#|[.tiny]#Escape#|[.tiny]#`0`#|[.tiny]#Enter#|[.tiny]#F12#|[.tiny]#X#|[.tiny]#Y#|[.tiny]#Z#|[.tiny]#M#
+|===
+
+<<<
+
+== Firmware upgrade
+
+There are different possible firmware versions (the program stored in the flash memory of the board and which does keystroke translating) that you can use:
+
+- The original firmware, which can be used to send PS/2 or USB keystrokes, and is available here:
+
+http://github.com/Dacarsoft/DB9_2_Keyboard
+
+- The specific variant for https://zxespectrum.speccy.org[ESPectrum], and which sends, by default, for PS/2, special emulator keystrokes, available here:
+
+https://github.com/dacarsoft/DB9_2_Keyboard/tree/DB9_2_Keyboard_ESPectrum
+
+- You can also install the Daemonbite firmware available at this location:
+
+https://github.com/MickGyver/DaemonBite-Retro-Controllers-USB/tree/master/SegaTwoControllersUSB
+
+[NOTE]
+====
+In the latter case, the ESPJoy will function as a USB HID game controller, but without PS/2 protocol support.
+====
+
+To update the board program there are several software options, but all require a computer or similar device with USB ports and a Windows, Linux or macOS operating system.
+
+The way to do the programming will depend on the format in which the program is available.
+
+<<<
+
+=== Firmware as source code (INO format)
+
+In this case, the firmware is not completely ready to be installed on the board and has to be compiled from its source code before being written to the board's flash memory. The best option in this case is to use the official https://www.arduino.cc[Arduino] development environment.
+
+==== Arduino IDE
+
+In order to do this type of installation, you can use a computer (Windows, Mac, Linux) with https://www.arduino.cc/en/software [Arduino IDE] installed.
+
+===== Update
+
+Once the environment is ready with Arduino IDE installed, download the desired version of the project from the corresponding repository (standard, ESPectrum, etc.). You should have a folder with a bunch of files, one of the with the `.ino` extension in its name.
+
+Open the project file in Arduino IDE (for example `DB9_2_Keyboard_ESPectrum.ino`).
+
+Set the switch on the board to the position marked with "USB" (the closest position to the USB Mini-B connector). Connect the ESPjoy to the computer using the USB cable and select it at the top of the IDE window ("Arduino Leonardo" option).
+
+[.text-center]
+image:img/ideleonardo.png[scaledwidth=40%]
+
+<<<
+
+Finally, press the firmware upload button image:img/uploadbutton.png[scaledwidth=2%] and wait a few seconds while the project is compiled and uploaded to the device.
+
+[.text-center]
+image:img/ideupload.png[scaledwidth=40%] image:img/ideuploading.png[scaledwidth=40%]
+
+<<<
+
+=== Firmware in HEX format
+
+In this other case, the firmware is completely ready to be written to the board flash memory. There are multiple programs that can be used to do the programming.
+
+==== AVRDUDE
+
+AVR Downloader Uploader is a command line utility to download/upload/manipulate the ROM and EEPROM contents of multiple microcontrollers.
+
+In order to use it with ESPJoy, you need a recent version that supports the `-r` parameter (reconnect to -P port after "touching" it). See the <<#_about_arduino_leonardo_programming,technical_notes>> at the end of this manual for more information.
+
+The latest binary version for Windows can be downloaded from the official repository:
+
+https://github.com/avrdudes/avrdude
+
+For other systems, it is easy to compile the executable from the source code available in that repository. It is also available from multiple package installation systems, such as https://brew.sh/ [Homebrew for Mac], or the various official repositories of Linux distributions. 
+
+===== Upgrade
+
+After getting the desired `.hex` file firmware version from the (e.g. `DB9_2_Keyboard.ino.hex`), set the switch on the board to the position marked with "USB" (the closest position to the USB Mini-B connector). Then connect the ESPJoy board to a USB port of the computer , and identify that port in the operating system.
+
+<<<
+
+Once the port name has been identified, the file can be written to the board with a command such as the following:
+
+[source,shell]
+----
+.../avrdude -F -patmega32u4 -cavr109 -b57600 -r -P <port> -U flash:w:<file.hex>:i
+----
+
+Where `<port>` is the name of the port where the board is connected and `<file.hex>` is the path to the `.hex` file you want to save.
+
+For example, for a port named `/dev/cu.usbmodemHIDPC1` and a `DB9_2_Keyboard.ino.hex` file:
+
+[source,shell]
+----
+.../avrdude -F -patmega32u4 -cavr109 -b57600 -r -P /dev/cu.usbmodemHIDPC1 -U flash:w:DB9_2_Keyboard.ino.hex:i
+----
+
+Wait for a few seconds, and, if all goes well, the console will display messages indicating that the program has been successfully recorded.
+
+[.text-center]
+image:img/avrdudeupload.png[scaledwidth=60%]
+
+<<<
+
+== Technical Notes
+
+=== About Arduino Leonardo programming
+
+The ESPJoy board is based on a https://www.microchip.com/en-us/product/ATmega32U4[ATmega32u4] programmable controller, which is the one used by https://docs.arduino.cc/hardware/leonardo/[Arduino Leonardo] boards.
+
+These devices have a bootloader that can be used for flash programming, but can also be omitted to directly run the saved program. This is how you which one of the two possibilities is triggered:
+
+- If it is started after a reset command (i.e. the board has a reset button that has been pressed), the programming mode (program saving in flash memory) is always activated.
+- If there is no program stored in flash (the first word is `0xffff`), the programming mode is always activated.
+- If it boots after a cold start (meaning that the device is activated for the first time after power is applied), it will try to execute the stored program.
+- If it boots after a reset by watchdog, then:
+  * If there is the appropriate code written to a magic location in SRAM (`0x7777 `written to `0x0800`), then it will go into programming mode.
+  * If not, it will try to execute the user code.
+- If it boots after any other type of reset, it will go to programming mode.
+
+The boot loader is designed to detect if a 1200 baud serial connection to the port has been opened and closed, and, if so, performs the necessary steps to perform a watchdog reset.
+
+Finally, note that the bootloader has a timeout of 8 seconds. If programming has not started within that time after triggering (via any method) in programming mode, it will try again to execute the user code.
+
+As a consequence of this, programming via commands, etc. with Windows requires specific drivers for both modes (program execution and programming) to be installed for all serial (COM) ports, so that the new connection after the restart by watchdog will work correctly.
+
+When programming with <<#_avrdude,AVRDUDE>>, it is highly recommended to use a version that has the `-r` parameter, and therefore automatically performs this port opening and closing process, and subsequent connection, within the 8 seconds margin required for programming. Otherwise it can be somewhat complex to do it manually.

doc/src/espjoy_es.adoc

@@ -0,0 +1,241 @@
+https://antoniovillena.com/product/espjoy/[ESPjoy] es un placa adaptadora con puertos https://es.wikipedia.org/wiki/D-sub[DE-9] para mandos https://es.wikipedia.org/wiki/Joystick_Atari[norma Atari] o https://es.wikipedia.org/wiki/Mega_Drive[Sega Mega Drive (Genesis)] y que convierte pulsaciones de sus botones a señales equivalentes de teclado.
+
+Está diseñada originalmente para usarse con https://zxespectrum.speccy.org[ESPectrum], pero puede utilizarse con otros dispositivos, ya que es capaz de convertir, según se desee, a dos protocolos distintos de teclado (USB y PS/2), usando un interruptor incorporado.
+
+Esta traducción a teclado es muy útil para emuladores o para aquellos dispositivos basados en FPGA, como la familia https://zxuno.speccy.org[ZX-Uno] y sus derivados o https://github.com/MiSTer-devel/Wiki_MiSTer/wiki[MiSTer], que no tengan soporte para conectores de joystick. Por ejemplo, para el uso en cores de ordenadores cuando no se desea un teclado conectado permanentemente.
+
+El programa (firmware) grabado en la placa envía pulsaciones cuando se pulsa un botón de algún mando conectado y es capaz de utilizar dos mandos de manera simultánea.
+
+Son compatibles los mandos y joystick de uno o dos botones (norma Atari), así como mandos Sega de tres o de 6 botones.
+
+<<<
+
+== Puertos y botones
+
+[width="100%",cols="2a,3a",frame="none"]
+|===
+|[cols="1,4"]
+!===
+!1 !Primer Puerto DE-9
+!2 !Segundo Puerto DE-9
+!===
+|image:img/ESPjoyFront.png[scaledwidth=70%]
+|===
+
+[width="100%",cols="3a,2a",frame="none"]
+|===
+| image:img/ESPjoyBack.png[scaledwidth=70%]
+|[cols="1,4"]
+!===
+!3 !Puerto USB Mini-B
+!4 !Interruptor de selección de protocolo
+!===
+|===
+
+<<<
+
+== Uso
+
+=== Configuración
+
+Para utilizarlo en ESPectrum se ha de seleccionar la opción PS/2 del interruptor. La opción USB se puede utilizar con MiSTer u otro sistema compatible (PC, Mac, etc.). Con el firmware original diseñado por David Carrión se emula un teclado HID, por lo que se puede usar sin problema en MiSTer con cores de ordenadores.
+
+La detección de la conexión se realiza en los primeros segundos del arranque cuando la placa se conecta a un puerto USB o PS/2 y recibe alimentación. Si la placa está conectada a un dispositivo como un PC o similar durante el arranque del mismo, es muy probable que falle la detección USB, porque el sistema operativo no esté aún preparado cuando se alcanza el límite de tiempo de espera de detección de la placa. En ese caso, se ha de desconectar y volver a conectar una vez que el dispositivo esté preparado para detectar la conexión.
+
+[TIP]
+====
+El interruptor de selección del modo PS/2 o USB se ha de cambiar siempre antes de conectar la placa a la alimentación, o no funcionará correctametne.
+====
+
+=== Selección del mapa de teclas
+
+Durante el arranque, si se mantiene pulsado alguno de los botones especificados, según las tablas que hay a continuaciónm, se pueden seleccionar distintas traducciones de teclado .
+
+[NOTE]
+====
+El comportamiento en la asignación por defecto (cuando no se pulsa ningún botón en el arranque) varía según el firmware que haya instalado en el ESPJoy. Cuando se indique la opción (Original) se estará hablando el firmware no adaptado para ESPectrum. En el otro caso (ESPectrum), se refiere al firmware adaptado para ESPectrum.
+====
+
+[WARNING]
+====
+La asignación por defecto del firmware de ESPectrum al usar el puerto PS/2 lo hace incompatible con otros dispositivos al usar una conexión PS/2. Por tanto, en ese caso, se ha de pulsar obligatoriamente un botón que active una configuración distinta de teclado durante el arranque.
+====
+
+[WARNING]
+====
+Existen algunos mandos clónicos que pueden enviar señales extrañas en algunas direcciones. Debido a esto, falla la comprobación en el código, y no funciona correctamente la activación en el arranque, por ejemplo, al pulsar izquierda en el mando. 
+====
+
+<<<
+
+*Puerto 1 (PS/2)*
+
+[align="center",width="100%",%header,cols="2a,1a,1a,1a,1a,1a,1a,1a,1a,1a,1a,1a,1a",options="header"]
+|===
+|[.tiny]#Pulsación Arranque#|[.tiny]#Arriba#|[.tiny]#Abajo#|[.tiny]#Izquierda#|[.tiny]#Derecha#|[.tiny]#A#|[.tiny]#B#|[.tiny]#C#|[.tiny]#Start#|[.tiny]#X#|[.tiny]#Y#|[.tiny]#Z#|[.tiny]#Mode#
+|[.tiny]#Ninguna (Original)#|[.tiny]#Arriba#|[.tiny]#Abajo#|[.tiny]#Izquierda#|[.tiny]#Derecha#|[.tiny]#Escape#|[.tiny]#Enter#|[.tiny]#Alt Dcha.#|[.tiny]#F1#|[.tiny]#X#|[.tiny]#Y#|[.tiny]#Z#|[.tiny]#M#
+|[.tiny]#Ninguna (ESPectrum)#|[.tiny]#Arriba#|[.tiny]#Abajo#|[.tiny]#Izquierda#|[.tiny]#Derecha#|[.tiny]#A#|[.tiny]#B#|[.tiny]#C#|[.tiny]#Start#|[.tiny]#X#|[.tiny]#Y#|[.tiny]#Z#|[.tiny]#Mode#
+|[.tiny]#Arriba#|[.tiny]#Q#|[.tiny]#A#|[.tiny]#O#|[.tiny]#P#|[.tiny]#Escape#|[.tiny]#M#|[.tiny]#Enter#|[.tiny]#F1#|[.tiny]#X#|[.tiny]#Y#|[.tiny]#Z#|[.tiny]#C#
+|[.tiny]#Abajo#|[.tiny]#Arriba#|[.tiny]#Abajo#|[.tiny]#Izquierda#|[.tiny]#Derecha#|[.tiny]#Escape#|[.tiny]#Enter#|[.tiny]#`0`#|[.tiny]#F5#|[.tiny]#X#|[.tiny]#Y#|[.tiny]#Z#|[.tiny]#M#
+|[.tiny]#Izquierda#|[.tiny]#7#|[.tiny]#6#|[.tiny]#5#|[.tiny]#8#|[.tiny]#Escape#|[.tiny]#`0`#|[.tiny]#Enter#|[.tiny]#F1#|[.tiny]#X#|[.tiny]#Y#|[.tiny]#Z#|[.tiny]#M#
+|===
+
+*Puerto 2 (PS/2)*
+
+[align="center",width="100%",%header,cols="2a,1a,1a,1a,1a,1a,1a,1a,1a,1a,1a,1a,1a",options="header"]
+|===
+|[.tiny]#Pulsación Arranque#|[.tiny]#Arriba#|[.tiny]#Abajo#|[.tiny]#Izquierda#|[.tiny]#Derecha#|[.tiny]#A#|[.tiny]#B#|[.tiny]#C#|[.tiny]#Start#|[.tiny]#X#|[.tiny]#Y#|[.tiny]#Z#|[.tiny]#Mode#
+|[.tiny]#Ninguna (Original)#|[.tiny]#Q#|[.tiny]#A#|[.tiny]#O#|[.tiny]#P#|[.tiny]#Escape#|[.tiny]#M#|[.tiny]#Enter#|[.tiny]#F1#|[.tiny]#X#|[.tiny]#Y#|[.tiny]#Z#|[.tiny]#C#
+|[.tiny]#Ninguna (ESPectrum)#|[.tiny]#Arriba#|[.tiny]#Abajo#|[.tiny]#Izquierda#|[.tiny]#Derecha#|[.tiny]#A#|[.tiny]#B#|[.tiny]#C#|[.tiny]#Start#|[.tiny]#X#|[.tiny]#Y#|[.tiny]#Z#|[.tiny]#Mode#
+|[.tiny]#Arriba#|[.tiny]#Arriba#|[.tiny]#Abajo#|[.tiny]#Izquierda#|[.tiny]#Derecha#|[.tiny]#Escape#|[.tiny]#Enter#|[.tiny]#Alt Dcha.#|[.tiny]#F1#|[.tiny]#X#|[.tiny]#Y#|[.tiny]#Z#|[.tiny]#M#
+|[.tiny]#Abajo#|[.tiny]#Arriba#|[.tiny]#Abajo#|[.tiny]#Izquierda#|[.tiny]#Derecha#|[.tiny]#Escape#|[.tiny]#Enter#|[.tiny]#`0`#|[.tiny]#F5#|[.tiny]#X#|[.tiny]#Y#|[.tiny]#Z#|[.tiny]#M#
+|[.tiny]#Izquierda#|[.tiny]#7#|[.tiny]#6#|[.tiny]#5#|[.tiny]#8#|[.tiny]#Escape#|[.tiny]#`0`#|[.tiny]#Enter#|[.tiny]#F1#|[.tiny]#X#|[.tiny]#Y#|[.tiny]#Z#|[.tiny]#M#
+|===
+
+*Puerto 1 (USB)*
+
+[align="center",width="100%",%header,cols="2a,1a,1a,1a,1a,1a,1a,1a,1a,1a,1a,1a,1a",options="header"]
+|===
+|[.tiny]#Pulsación Arranque#|[.tiny]#Arriba#|[.tiny]#Abajo#|[.tiny]#Izquierda#|[.tiny]#Derecha#|[.tiny]#A#|[.tiny]#B#|[.tiny]#C#|[.tiny]#Start#|[.tiny]#X#|[.tiny]#Y#|[.tiny]#Z#|[.tiny]#Mode#
+|[.tiny]#Ninguna (Original)#|[.tiny]#Arriba#|[.tiny]#Abajo#|[.tiny]#Izquierda#|[.tiny]#Derecha#|[.tiny]#Escape#|[.tiny]#Enter#|[.tiny]#Alt Dcha.#|[.tiny]#F12#|[.tiny]#X#|[.tiny]#Y#|[.tiny]#Z#|[.tiny]#M#
+|[.tiny]#Arriba#|[.tiny]#Q#|[.tiny]#A#|[.tiny]#O#|[.tiny]#P#|[.tiny]#Escape#|[.tiny]#M#|[.tiny]#Enter#|[.tiny]#F12#|[.tiny]#X#|[.tiny]#Y#|[.tiny]#Z#|[.tiny]#C#
+|[.tiny]#Abajo#|[.tiny]#Arriba#|[.tiny]#Abajo#|[.tiny]#Izquierda#|[.tiny]#Derecha#|[.tiny]#Escape#|[.tiny]#Enter#|[.tiny]#`0`#|[.tiny]#F5#|[.tiny]#X#|[.tiny]#Y#|[.tiny]#Z#|[.tiny]#M#
+|[.tiny]#Izquierda#|[.tiny]#7#|[.tiny]#6#|[.tiny]#5#|[.tiny]#8#|[.tiny]#Escape#|[.tiny]#`0`#|[.tiny]#Enter#|[.tiny]#F12#|[.tiny]#X#|[.tiny]#Y#|[.tiny]#Z#|[.tiny]#M#
+|===
+
+*Puerto 2 (USB)*
+
+[align="center",width="100%",%header,cols="2a,1a,1a,1a,1a,1a,1a,1a,1a,1a,1a,1a,1a",options="header"]
+|===
+|[.tiny]#Pulsación Arranque#|[.tiny]#Arriba#|[.tiny]#Abajo#|[.tiny]#Izquierda#|[.tiny]#Derecha#|[.tiny]#A#|[.tiny]#B#|[.tiny]#C#|[.tiny]#Start#|[.tiny]#X#|[.tiny]#Y#|[.tiny]#Z#|[.tiny]#Mode#
+|[.tiny]#Ninguna (Original)#|[.tiny]#Q#|[.tiny]#A#|[.tiny]#O#|[.tiny]#P#|[.tiny]#Escape#|[.tiny]#M#|[.tiny]#Enter#|[.tiny]#F12#|[.tiny]#X#|[.tiny]#Y#|[.tiny]#Z#|[.tiny]#C#
+|[.tiny]#Arriba#|[.tiny]#Arriba#|[.tiny]#Abajo#|[.tiny]#Izquierda#|[.tiny]#Derecha#|[.tiny]#Escape#|[.tiny]#Enter#|[.tiny]#Alt Dcha.#|[.tiny]#F12#|[.tiny]#X#|[.tiny]#Y#|[.tiny]#Z#|[.tiny]#M#
+|[.tiny]#Abajo#|[.tiny]#Arriba#|[.tiny]#Abajo#|[.tiny]#Izquierda#|[.tiny]#Derecha#|[.tiny]#Escape#|[.tiny]#Enter#|[.tiny]#`0`#|[.tiny]#F5#|[.tiny]#X#|[.tiny]#Y#|[.tiny]#Z#|[.tiny]#M#
+|[.tiny]#Izquierda#|[.tiny]#7#|[.tiny]#6#|[.tiny]#5#|[.tiny]#8#|[.tiny]#Escape#|[.tiny]#`0`#|[.tiny]#Enter#|[.tiny]#F12#|[.tiny]#X#|[.tiny]#Y#|[.tiny]#Z#|[.tiny]#M#
+|===
+
+<<<
+
+== Actualización de firmware
+
+Existen diferentes versiones de firmware (el programa grabado en la memoria flash de la placa y que se encarga de realizar la traducción a pulsaciones de teclado):
+
+- El firmware original, que puede utilizarse para enviar pulsaciones de teclado PS/2 o USB y que está disponible aquí:
+
+http://github.com/Dacarsoft/DB9_2_Keyboard
+
+- La variante específica para https://zxespectrum.speccy.org[ESPectrum], y que envía, por defecto, para PS/2, unas pulsaciones especiales para el emulador, disponible aquí:
+
+https://github.com/dacarsoft/DB9_2_Keyboard/tree/DB9_2_Keyboard_ESPectrum
+
+- También se puede instalar el firmware Daemonbite disponible en esta ubicación:
+
+https://github.com/MickGyver/DaemonBite-Retro-Controllers-USB/tree/master/SegaTwoControllersUSB
+
+[NOTE]
+====
+En este último caso, el ESPJoy funcionará como mando de juegos HID USB, pero perdiendo el soporte de protocolo PS/2.
+====
+
+Para actualizar la programación de la placa, existen varias opciones de software, aunque todas requieren un ordenador o similar con puertos USB y un sistema operativo Windows, Linux o macOS.
+
+La forma de programar dependerá del formato en que se encuentre disponible el programa.
+
+<<<
+
+=== Firmware como código fuente (formato INO)
+
+En este caso, el firmware no está completamente listo para ser instalado en la placa y tiene que ser compilado desde su código fuente antes ser grabado en la memoria flash de la placa. El mejor sistema en este caso, consiste en utilizar el entorno de desarrollo oficial de https://www.arduino.cc[Arduino].
+
+==== Arduino IDE
+
+Para poder hacer este tipo de instalación, se puede usar un ordenador (Windows, Mac, Linux) con el entorno https://www.arduino.cc/en/software[Arduino IDE] instalado.
+
+===== Actualización
+
+Una vez preparado el entorno con Arduino IDE instalado, descargar la versión deseada del proyecto desde el repositorio correspondiente (estándar, ESPectrum, etc.). Normalmente es una carpeta con varios ficheros, uno de los cuales tiene la extensión `.ino` en el nombre.
+
+Abrir el fichero del proyecto en Arduino IDE (por ejemplo `DB9_2_Keyboard_ESPectrum.ino`).
+
+Colocar el interruptor de la placa en la posición marcada como "USB" (la posición más cercana al conector USB Mini-B). Conectar el ESPjoy al equipo usando el cable USB y seleccionarlo en la parte superior de la ventana del IDE (opción "Arduino Leonardo").
+
+[.text-center]
+image:img/ideleonardo.png[scaledwidth=40%]
+
+<<<
+
+Finalmente, pulsar el botón de carga del firmware (upload) image:img/uploadbutton.png[scaledwidth=2%] y esperar unos segundos mientras se compila el proyecto y se carga en el dispositivo.
+
+[.text-center]
+image:img/ideupload.png[scaledwidth=40%]          image:img/ideuploading.png[scaledwidth=40%]
+
+<<<
+
+=== Firmware en formato HEX
+
+En este otro caso, el firmware está completamente listo para ser grabado en la memoria flash de la placa. Existen múltiples programas que se pueden utilizar para hacer la grabación.
+
+==== AVRDUDE
+
+AVR Downloader Uploader es un programa de línea de comandos que sirve para manipular los contenidos ROM y EEPROM de múltiples microcontroladores.
+
+Para poder utilizarlo con ESPJoy, se necesita una versión reciente que soporte el parámetro `-r` (reconnect to -P port after "touching" it). Véanse las <<#_sobre_la_programación_de_arduino_leonardo,notas Técnicas>> al final de este manual para más información.
+
+La última versión ejecutable para Windows se puede descargar desde el repositorio oficial:
+
+https://github.com/avrdudes/avrdude
+
+Para otros sistemas, es bastante sencillo compilar el ejecutable desde el código fuente disponible en dicho repositorio. También está disponible en múltiples sistemas de instalación de paquetes, como https://brew.sh/[Homebrew para Mac], o los distintos repositorios oficiales de distribuciones de Linux. 
+
+===== Actualización
+
+Tras obtener la versión de firmware deseada del fichero `.hex` (por ejemplo `DB9_2_Keyboard.ino.hex`), colocar el interruptor de la placa en la posición marcada como "USB" (la posición más cercana al conector USB Mini-B). A continuación conectar la placa ESPJoy al ordenador a un puerto USB, e identificar dicho puerto en el sistema operativo.
+
+<<<
+
+Una vez identificado el nombre del puerto, se puede grabar el fichero en la placa con un comando como el siguiente:
+
+[source,shell]
+----
+.../avrdude -F -patmega32u4 -cavr109 -b57600 -r -P <puerto> -U flash:w:<fichero.hex>:i
+----
+
+Donde `<puerto>` es la identificación del puerto donde está conectada la placa y `<fichero.hex>` es la ruta al fichero `.hex` que se desea grabar.
+
+Por ejemplo, para un puerto llamado `/dev/cu.usbmodemHIDPC1` y un fichero `DB9_2_Keyboard.ino.hex`:
+
+[source,shell]
+----
+.../avrdude -F -patmega32u4 -cavr109 -b57600 -r -P /dev/cu.usbmodemHIDPC1 -U flash:w:DB9_2_Keyboard.ino.hex:i
+----
+
+Esperar unos segundos, y, si todo va bien, en la consola aparecerán mensajes indicando que se ha grabado el programa correctamente.
+
+[.text-center]
+image:img/avrdudeupload.png[scaledwidth=60%]
+
+<<<
+
+== Notas Técnicas
+
+=== Sobre la programación de Arduino Leonardo
+
+La placa ESPJoy está basada en un controlador programable https://www.microchip.com/en-us/product/ATmega32U4[ATmega32u4], que es el mismo que utilizan las placas https://docs.arduino.cc/hardware/leonardo/[Arduino Leonardo].
+
+Estos dispositivos disponen de un cargador de arranque que se puede utilizar para la programación de la flash, pero también puede omitirse para ejecutar directamente la programación guardada. Así es como se determina cuál de las dos posibilidades es la que se activa:
+
+- Si se inicia después de una orden de reinicio (es decir, se ha pulsado el botón de reinicio cuando la placa dispone del mismo), siempre se activa el modo de programación (grabación de programa en la memoria flash).
+- Si no hay programa almacenado en la flash (la primera palabra es `0xffff`), siempre se activa el modo de programación.
+- Si arranca después de un encendido en frío (lo que significa que el dispositivo se activa por primera vez después de aplicar alimentación), intentará ejecutar el programa almacenado.
+- Si arranca después de un reinicio (reset) por watchdog (perro guardián), entonces:
+  * Si hay el código adecuado escrito en una ubicación mágica en la SRAM (`0x7777` escrito en `0x0800`), entonces pasará al modo de programación.
+  * Si no, intentará ejecutar el código de usuario.
+- Si arranca después de cualquier otro tipo de reinicio, pasará a modo programación.
+
+El gestor de arranque esta hecho de forma que detecta si se ha abierto y cerrado una conexión serie a 1200 baud al puerto, y, en ese caso, realiza los pasos necesarios para hacer un reinicio por watchdog.
+
+Finalmente, señalar que el gestor de arranque tiene un tiempo de espera de 8 segundos. Si la programación no se ha iniciado en ese tiempo después de activar (a través de cualquier método) en el modo de programación, intentará de nuevo ejecutar el código de usuario.
+
+Como consecuencia de esto, la programación por vía de comandos, etc. en Windows requiere que estén instalados los controladores específicos para los dos modos (ejecución de programa y programación) para todos los puertos serie (COM), para que la nueva conexión tras el reinicio por watchdog funcione correctamente.
+
+En el caso de la grabación con <<#_avrdude,AVRDUDE>>, es muy recomendable usar una versión que disponga del parámetro `-r`, y que por tanto realiza automáticamente este proceso de apertura y cierre de conexión, y conexión posterior, dentro de los 8 segundos de margen necesarios para la programación. En otro caso puede ser algo complicado realizarlo de forma manual.

doc/src/espjoy_style.yml

@@ -0,0 +1,33 @@
+extends: default
+
+font:
+  catalog:
+    merge: true 
+    Verdana:
+      normal: Verdana.ttf
+      italic: Verdana Italic.ttf
+      bold: Verdana Bold.ttf
+      bold_italic: Verdana Bold Italic.ttf
+
+base:
+  font-family: Verdana
+
+page:
+  size: [830, 580]
+
+title-page:
+  size: [830, 580]
+
+header:
+  height: 15mm
+  font-family: M+ 1mn
+  recto:
+    right:
+      content: "{document-title} : {section-or-chapter-title}"
+  verso:
+    left:
+      content: "{document-title} : {section-or-chapter-title}"
+
+role:
+  tiny:
+    font-size: 6

doc/src/style.yml

@@ -9,3 +9,7 @@ header:
   verso:
     left:
       content: "{document-title} : {section-or-chapter-title}"
+
+role:
+  tiny:
+    font-size: 6