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

Author: craigthomas

README.md

@@ -9,21 +9,24 @@
 
 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. [Configuration File](#configuration-file)
+9. [Keyboard](#keyboard)
     1. [Emulated Keyboard](#emulated-keyboard)
     2. [Pass-through Keyboard](#pass-through-keyboard)
-9. [Current Status](#current-status)
+10. [Current Status](#current-status)
 
 ## What Is It?
 
@@ -53,13 +56,87 @@ 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.
+
+### 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.
+
+### Windows
+
+_Under construction._
+
+## 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. 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
+```
+
+For Windows, I recommend using Eclipse Temurin (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).
 
 To build the project, switch to the root of the source directory, and type:
 
@@ -73,16 +150,14 @@ On Windows, switch to the root of the source directory, and type:
 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

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.20.0'
 }

src/main/java/ca/craigthomas/yacoco3e/components/Emulator.java

@@ -6,13 +6,16 @@
 
 import ca.craigthomas.yacoco3e.datatypes.*;
 import ca.craigthomas.yacoco3e.listeners.*;
+import net.java.games.input.Controller;
+import net.java.games.input.ControllerEnvironment;
 
 import javax.swing.*;
 import java.awt.*;
 import java.awt.event.KeyEvent;
 import java.time.Duration;
 import java.time.Instant;
 import java.time.temporal.ChronoUnit;
+import java.util.ArrayList;
 import java.util.TimerTask;
 import java.util.Timer;
 import java.util.logging.Logger;
@@ -31,6 +34,8 @@ public class Emulator extends Thread
     private IOController io;
     private Cassette cassette;
     private Memory memory;
+    private int leftJoystickNumber;
+    private int rightJoystickNumber;
 
     // The Canvas on which all the drawing will take place
     private Canvas canvas;
@@ -39,6 +44,8 @@ public class Emulator extends Thread
     private JFrame container;
     private JMenuBar menuBar;
 
+    Controller [] controllers;
+
     /* State variables */
     public boolean trace;
     private boolean verbose;
@@ -117,6 +124,7 @@ private Emulator(Builder builder) {
         io = new IOController(memory, new RegisterSet(), keyboard, screen, cassette, builder.useDAC);
         cpu = new CPU(io);
         io.setCPU(cpu);
+
         trace = builder.trace;
         verbose = builder.verbose;
         status = EmulatorStatus.STOPPED;
@@ -129,11 +137,9 @@ private Emulator(Builder builder) {
                 }
             }
         } catch (Exception e) {
-            System.out.println("Nimbus LAF not available");
+            LOGGER.warning("Nimbus LAF not available");
         }
 
-        initEmulatorJFrame();
-
         // Check to see if we specified a configuration file
         ConfigFile builderConfig = ConfigFile.parseConfigFile(builder.configFile);
 
@@ -142,6 +148,9 @@ private Emulator(Builder builder) {
 
         // Attempt to load the assets for the emulator
         loadAssets(builderConfig, commandLineConfig);
+
+        // Initialize the main emulator JFrame
+        initEmulatorJFrame();
     }
 
     /**
@@ -197,13 +206,37 @@ public void loadFromConfigFile(ConfigFile config) {
             }
         }
 
+        // Load drive images
         String drive0 = config.getDrive0Image();
         if (drive0 != null) {
             JV1Disk disk = new JV1Disk();
             if (disk.loadFile(drive0)) {
                 io.disk[0].loadFromVirtualDisk(disk);
             }
         }
+
+        // Enumerate joystick controllers and set current joystick types
+        controllers = ControllerEnvironment.getDefaultEnvironment().getControllers();
+        LOGGER.info("Joystick #0, Name: 'No Joystick', Type: None");
+        leftJoystickNumber = 0;
+        rightJoystickNumber = 0;
+        int index = 1;
+        for (Controller controller : controllers) {
+            Controller.Type controllerType = controller.getType();
+            if (controllerType != Controller.Type.MOUSE && controllerType != Controller.Type.KEYBOARD) {
+                LOGGER.info("Joystick #" + index  + ", Name: '" + controller.getName() + "', Type: " + controller.getType());
+                if (controller.getName().stripTrailing().equals(config.getLeftJoystick())) {
+                    leftJoystickNumber = index;
+                }
+                if (controller.getName().stripTrailing().equals(config.getRightJoystick())) {
+                    rightJoystickNumber = index;
+                }
+                index++;
+            }
+        }
+        io.setJoystickControllers(controllers);
+        io.setLeftJoystickNumber(leftJoystickNumber);
+        io.setRightJoystickNumber(rightJoystickNumber);
     }
 
     /**
@@ -344,6 +377,74 @@ private void initEmulatorJFrame() {
 
         menuBar.add(keyboardMenu);
 
+        // Joystick menu
+        JMenu joystickMenu = new JMenu("Joystick");
+        joystickMenu.setMnemonic(KeyEvent.VK_J);
+
+        JMenu leftJoystickMenuItem = new JMenu("Left Joystick");
+        leftJoystickMenuItem.setMnemonic(KeyEvent.VK_L);
+
+        JRadioButtonMenuItem leftJoystickNoneMenuItem = new JRadioButtonMenuItem("No Joystick");
+        leftJoystickNoneMenuItem.setSelected(leftJoystickNumber == 0);
+        leftJoystickMenuItem.add(leftJoystickNoneMenuItem);
+
+        // Enumerate all joystick devices and add menu items for each
+        ArrayList<JRadioButtonMenuItem> options = new ArrayList<>();
+        options.add(leftJoystickNoneMenuItem);
+
+        // Loop through all the joystick controllers and generate menu items for each
+        int index = 1;
+        for (Controller controller : controllers) {
+            Controller.Type controllerType = controller.getType();
+            if (controllerType != Controller.Type.MOUSE && controllerType != Controller.Type.KEYBOARD) {
+                JRadioButtonMenuItem leftJoystickControllerMenuItem = new JRadioButtonMenuItem(controller.getName());
+                leftJoystickControllerMenuItem.setSelected(leftJoystickNumber == index);
+                leftJoystickMenuItem.add(leftJoystickControllerMenuItem);
+                options.add(leftJoystickControllerMenuItem);
+                index++;
+            }
+        }
+
+        // Reset the joystick index and add the list of joystick menu items to the menu
+        index = 0;
+        for (JRadioButtonMenuItem button : options) {
+            button.addActionListener(new SetLeftJoystickMenuItemActionListener(this, options.toArray(new JRadioButtonMenuItem[0]), index));
+            index++;
+        }
+
+        joystickMenu.add(leftJoystickMenuItem);
+
+        JMenu rightJoystickMenuItem = new JMenu("Right Joystick");
+        rightJoystickMenuItem.setMnemonic(KeyEvent.VK_R);
+
+        JRadioButtonMenuItem rightJoystickNoneMenuItem = new JRadioButtonMenuItem("No Joystick");
+        rightJoystickNoneMenuItem.setSelected(rightJoystickNumber == 0);
+        rightJoystickMenuItem.add(rightJoystickNoneMenuItem);
+
+        options = new ArrayList<>();
+        options.add(rightJoystickNoneMenuItem);
+
+        index = 1;
+        for (Controller controller : controllers) {
+            Controller.Type controllerType = controller.getType();
+            if (controllerType != Controller.Type.MOUSE && controllerType != Controller.Type.KEYBOARD) {
+                JRadioButtonMenuItem rightJoystickControllerMenuItem = new JRadioButtonMenuItem(controller.getName());
+                rightJoystickControllerMenuItem.setSelected(rightJoystickNumber == index);
+                rightJoystickMenuItem.add(rightJoystickControllerMenuItem);
+                options.add(rightJoystickControllerMenuItem);
+            }
+        }
+
+        // Reset the joystick index and add the list of joystick menu items to the menu
+        index = 0;
+        for (JRadioButtonMenuItem button : options) {
+            button.addActionListener(new SetRightJoystickMenuItemActionListener(this, options.toArray(new JRadioButtonMenuItem[0]), index));
+            index++;
+        }
+
+        joystickMenu.add(rightJoystickMenuItem);
+        menuBar.add(joystickMenu);
+
         // Debug menu
         JMenu debugMenu = new JMenu("Debugging");
         debugMenu.setMnemonic(KeyEvent.VK_U);
@@ -403,6 +504,24 @@ public void switchKeyListener(Keyboard newKeyboard) {
         io.setKeyboard(keyboard);
     }
 
+    /**
+     * Switches out the existing left joystick for a new one.
+     *
+     * @param newJoystickNumber the new joystick device number to use (0 for none)
+     */
+    public void switchLeftJoystick(int newJoystickNumber) {
+        io.setLeftJoystickNumber(newJoystickNumber);
+    }
+
+    /**
+     * Switches out the existing right joystick for a new one.
+     *
+     * @param newJoystickNumber the new joystick device number to use (0 for none)
+     */
+    public void switchRightJoystick(int newJoystickNumber) {
+        io.setRightJoystickNumber(newJoystickNumber);
+    }
+
     /**
      * Will redraw the contents of the screen to the emulator window. Optionally, if
      * isInTraceMode is True, will also draw the contents of the overlayScreen to the screen.
@@ -430,6 +549,7 @@ public void start() {
         screenRefreshTimer = new Timer();
         screenRefreshTimerTask = new TimerTask() {
             public void run() {
+                io.pollJoysticks();
                 screen.refreshScreen();
                 refreshScreen();
             }