Joystick implementation (#163)

* Add new routines to query game devices and poll from them.

Implement comparator to joystick voltages.

Fix reversed controls, add CA2 auto-transition when bit 4 is zero.

Add ability to set joystick via config file

* Clarify README for joystick usage and JDK and JRE selection.

Author: craigthomas

README.md

@@ -9,21 +9,25 @@
 
 1. [What Is It?](#what-is-it)
 2. [License](#license)
-3. [Compiling](#compiling)
-4. [Running](#running)
+3. [Requirements](#requirements)
+    1. [Linux](#linux)
+    2. [Windows](#windows) 
+4. [Compiling From Source](#compiling-from-source) 
+5. [Running](#running)
     1. [Specifying a System ROM](#specifying-a-system-rom)
     2. [Trace Mode](#trace-mode)
-5. [Cassette Tapes](#cassette-tapes)
+6. [Cassette Tapes](#cassette-tapes)
     1. [Reading](#reading)
     2. [Writing](#writing)
-6. [Disk Drives](#disk-drives)
+7. [Disk Drives](#disk-drives)
     1. [Loading a Disk Image](#loading-a-disk-image)
     2. [Saving a Disk Image](#saving-a-disk-image)
-7. [Configuration File](#configuration-file)
-8. [Keyboard](#keyboard)
+8. [Joysticks](#joysticks)
+9. [Configuration File](#configuration-file)
+10. [Keyboard](#keyboard)
     1. [Emulated Keyboard](#emulated-keyboard)
     2. [Pass-through Keyboard](#pass-through-keyboard)
-9. [Current Status](#current-status)
+11. [Current Status](#current-status)
 
 ## What Is It?
 
@@ -53,36 +57,129 @@ Third Party Licenses and Attributions below for more information on those
 software components.
 
 
-## Compiling
+## Requirements
 
-You will need a copy of the Java Development Kit (JDK) version 8 or greater 
-installed in to compile the JAR file. I strongly recommend using an open-source 
-licensed JDK build (GPL v2 with Classpath Exception), available at 
-[https://adoptopenjdk.net](https://adoptopenjdk.net) and install OpenJDK 8 or 
-OpenJDK 11.
+The project needs several different packages installed in order to run the
+emulator properly. Please see the platform specific steps below for
+more information.
 
-To build the project, switch to the root of the source directory, and type:
+### Linux
+
+At a minimum, you will need to install the Java Runtime Environment (JRE) 17 or
+higher. Additionally, if you wish to use joysticks, you will need to install the 
+`libjinput` API bindings, add your username to the `group` file, as well as fix a
+potential API binding bug. 
+
+1. *Required* - a Java Runtime Environment (JRE) version 17 or higher. The simplest way to
+do this is to install OpenJDK 17 or higher. On Ubuntu or Debian systems, this can
+be done with :
 
+    ```bash
+    sudo apt update
+    sudo apt install openjdk-17-jre
+    ```
+
+2. *Optional* - for proper joystick support you will need to install the `jinput` joystick 
+library API on the system with:
+
+    ```bash
+    sudo apt install libjinput-java libjinput-jni
+    ```
+
+    Once installed, you may need to correct a missing file problem with the `libjinput-jni`
+    installation. The emulator dependencies require a shared object file called 
+    `libjinput-linux64.so` to be present in the `/usr/lib/jni` directory. However, the
+    `libjinput-jni` package may only install a file called `libjinput.so`. The 
+    solution is to create a symbolic link from `libjinput.so` to `linjinput-linux64.so`. 
+    First, check to see if the `libjinput-linux64.so` file already exists with:
+
+    ```bash
+    ls -l /usr/lib/jni
+    ```
+   
+    If the `libjinput-linux64.so` file is *NOT* listed, you will need to create a symbolic 
+    link with the following command:
+
+    ```bash
+    sudo ln -s /usr/lib/jni/libjinput.so /usr/lib/jni/libjinput-linux64.so
+    ```
+
+    Finally, you will need to add yourself to the `input` group so that the emulator can read
+    joystick information:
+
+    ```bash
+    sudo usermod -a -G input <your username>
+    ```
+   
+    You will need to end your current session and restart in order for the group information
+    to be updated. In some cases, you may need to reboot for the group change to take effect.
+
+To run the emulator, see the section called [Running](#running) below.
+
+### Windows
+
+At a minimum, you will need to install the Java Runtime Environment (JRE) 17 or
+higher. 
+
+1. *Required* - a Java Runtime Environment (JRE) version 17 or higher. I recommend using 
+   Eclipse Temurin JRE (formerly AdoptJDK) as the software
+   is licensed under the GNU license version 2 with classpath exception. The latest
+   JRE builds are available at [https://adoptium.net/en-GB/temurin/releases](https://adoptium.net/en-GB/temurin/releases)
+   (make sure you select _JRE_ as the type you wish to download). Run the installer
+   and follow the directions as required to install the runtime. 
+
+To run the emulator, see the section called [Running](#running) below.
+
+## Compiling From Source
+
+_Note this section is optional - this is only if you want to compile the project
+yourself from source code._ If you want to build the emulator from source code, 
+you will need a copy of the Java Development Kit (JDK) version 17 or greater 
+installed in to compile the JAR file. 
+
+### Linux
+
+For most Linux distributions there is likely an `openjdk-17-jdk` package that will do 
+this for you automatically. On Ubuntu and Debian based systems, this is typically:
+
+```bash
+sudo apt update
+sudo apt install openjdk-17-jdk
+```
+
+Next, to build the project, switch to the root of the source directory, and type:
+
 ```bash
 ./gradlew build
 ```
 
-On Windows, switch to the root of the source directory, and type:
+The compiled Jar file will be placed in the `build/libs` directory. Note that
+for some components such as joystick detection and control to work correctly,
+operating-specific steps may be required. See the _Requirements_ section above
+to install necessary sub-systems.
+
+
+### Windows 
+
+For Windows, I recommend using Eclipse Temurin JDK (formerly AdoptJDK) as the software
+is licensed under the GNU license version 2 with classpath exception. The latest
+JDK builds are available at [https://adoptium.net/en-GB/temurin/releases](https://adoptium.net/en-GB/temurin/releases)
+(make sure you select _JDK_ as the type you wish to download).
+
+Next, switch to the root of the source directory, and type:
 
 ```bash
 gradlew.bat build
 ```
 
-The compiled Jar file will be placed in the `build/libs` directory.
+The compiled Jar file will be placed in the `build/libs` directory. Note that
+for some components such as joystick detection and control to work correctly, 
+operating-specific steps may be required. See the _Requirements_ section above
+to install necessary sub-systems.
 
 
 ## Running
 
-For the emulator to run, you will need to have the Java 8 Runtime Environment (JRE)
-installed on your computer. See [Oracle's Java SE Runtime Environment Download](https://www.oracle.com/technetwork/java/javase/downloads/jre8-downloads-2133155.html)
-page for more information on installing the JRE. Alternatively, you can
-use [OpenJDK](https://openjdk.java.net/install/).
-
 Simply double-clicking the jar file will start the emulator running. By
 default, the emulator will be in paused mode until you attach a system
 ROM to it. You can do so by clicking *ROM*, *Load System ROM*. You can
@@ -192,6 +289,22 @@ select a location on your computer where the disk file will be saved to.
 Once entered, the contents of the drive will be saved to the virtual disk
 file, and can be loaded from the host computer in a future session.
 
+## Joysticks
+
+Joystick control is still experimental and only currently available under
+Linux. When running the emulator, to set the joystick to be used,
+click on *Joystick* and then *Left Joystick* or *Right Joystick* to select
+which device should be used as the left or right joystick. If no USB
+joystick devices are found, then *No joystick* will be the only option
+available. 
+
+To troubleshoot joystick configuration, when the emulator starts, a 
+list of detected joysticks will be printed to the console. The 
+`Joystick #0` device will always be `No Joystick`. Other enumerated
+joysticks will be printed after this one. The name of the detected joystick
+can be used in the configuration file below to automatically associate
+the left or right joystick device during emulator startup.
+
 
 ## Configuration File
 
@@ -205,19 +318,22 @@ Super Extended Color Basic ROM file).
 Megabug).
 * `cassetteROM` - the full path to the ROM file used in the cassette recorder.
 * `drive0Image` - the `DSK` image to be used in drive 0.
-* `drive1Image` - the `DSK` image to be used in drive 0.
-* `drive2Image` - the `DSK` image to be used in drive 0.
-* `drive3Image` - the `DSK` image to be used in drive 0.
+* `drive1Image` - the `DSK` image to be used in drive 1.
+* `drive2Image` - the `DSK` image to be used in drive 2.
+* `drive3Image` - the `DSK` image to be used in drive 3.
+* `leftJoystick` - the name of the detected joystick to use as the left joystick.
+* `rightJoystick` - the name of the detected joystick to use as the right joystick.
 
 Leaving any one of the keys out will result in the emulator ignoring that particular
-ROM image. An example YAML configuration file that specifies ROMs to use for the
-system, cartridge slot, cassette, and drive 0 is as follows:
+configuration option. An example YAML configuration file that specifies ROMs to use for the
+system, cartridge slot, cassette, joystick, and drive 0 is as follows:
 
 ```
 systemROM: "C:\Users\basic3.rom"
 cartridgeROM: "C:\disk11.rom"
 cassetteROM: "C:\Users\zaxxon.cas"
 drive0Image: "C:\megabug.dsk"
+leftJoystick: "usb gamepad"
 ```
 
 If you start the emulator without command-line arguments, it will look for a configuration file named

build.gradle

@@ -32,6 +32,9 @@ dependencies {
     implementation 'org.apache.commons:commons-lang3:3.20.0'
     implementation 'com.beust:jcommander:1.82'
     implementation 'org.yaml:snakeyaml:2.5'
+    implementation 'net.java.jinput:jinput:2.0.10'
+    runtimeOnly 'net.java.jinput:jinput-platform:2.0.7:natives-linux'
+    implementation 'net.java.jutils:jutils:1.0.0'
     testImplementation 'junit:junit:4.13.2'
     testImplementation 'org.mockito:mockito-core:5.21.0'
 }